法的情報

DirectX 8
プログラマーズ リファレンス

本書に記載されている情報は、URL およびインターネット Web サイトの参照も含めて、予告なしに変更されることがあります。本書で例として取りあげる企業、組織、製品、人物、およびイベントはすべて架空のものです。実在の企業、組織、製品、人物、またはイベントとの関連性を示唆するものではありません。本書の使用にあたっては、お客様の責任において、適用されるすべての著作権法に従ってください。著作権法による権利の制限内にとどまらず、また、使用目的にかかわらず、Microsoft Corporation からの書面による許可なく、本書の一部または全部を無断で複製したり、検索システムに格納または導入したり、あるいはいかなる形式や手段 (電子的、機械的、複写、録音、その他) でも配信することはできません。

Microsoft は、本書の内容に関連する特許、特許申請、商標、著作権、その他の知的所有権を有する場合があります。Microsoft からのライセンス契約文書で明示的に規定されていない限り、本書を入手しても Microsoft から上記特許、商標、著作権、その他の知的所有権のいずれのライセンスを取得したことにもなりません。

© 1995-2000 Microsoft Corporation.All rights reserved.

Microsoft、MS-DOS、Windows、Windows NT、ActiveX、Direct3D、DirectAnimation、DirectDraw、DirectInput、DirectMusic、DirectPlay、DirectShow、DirectSound、DirectX、Natural、および Win32 は、米国およびその他の各国における Microsoft Corporation の登録商標または商標です。

Roland GS Sound Set/Microsoft (R) 1996 Roland Corporation U.S.

Roland は Roland Corporation の登録商標です。

本書に記載されている実在の会社名および製品名は、各社の商標です。

注 : この API を実装する通信デバイスのメーカーは、1996 年の通信法第 255 条 (Section 255 of the Telecommunications Act) に準拠している必要があります。

著作権に関する注意

特別な注意 Roland GS Sound Set/Microsoft、つまり "サンプル セット" にはローランド サウンドキャンバス サウンド セットが組み込まれています。米国 Roland Corporation は、サンプル セットとそれに関連するすべての著作権を保有しています。さらに、サンプル セットの使用は、Microsoft のオペレーティング システム製品およびアプリケーション製品でのみ許可されています。

Microsoft の使用許諾契約書の条項で、サンプル セットに関して米国 Roland Corporation または Microsoft によって明白に許可されていない権利は、すべてローランドが保有します。

サンプル セットの再頒布は、Microsoft オペレーティング システム製品の統合コンポーネントとして、Microsoft の使用許諾契約書の条項に従って、ソフトウェア アプリケーションと一緒に行う場合にのみ認められます。サンプル セットをその他の用途に使用する場合は、米国 Roland Corporation からの別の書面による許可が必要となります。

米国 Roland Corporation の法的権限を持つ代表者による書面による事前承認なく、サンプル セットをハードウェア ROM または同様のデバイスで、使用、複写、または再頒布することはできません。また、サンプル セットを何らかの楽器と共に再頒布することはできません。"楽器" とは、ライセンスされた Microsoft オペレーティング システムを実行しているコンピュータに直接接続しなくても、音楽のサウンドを生成することができるデバイスのことです。いかなる環境においても、サンプル セットを修正することは許可されていません。

Built on 2000年11月18日


DirectX 8.0 の紹介

Microsoft® DirectX® は、ゲームおよびその他のハイパフォーマンスなマルチメディア アプリケーションを作成するための下位レベルのアプリケーション プログラミング インターフェイス (API) のセットである。Microsoft® DirectX® は、2 次元 (2D) と 3 次元 (3D) のグラフィックス、サウンド エフェクトとミュージック、入力デバイス、マルチプレーヤー ゲームなどのネットワーク アプリケーションをサポートする。

このドキュメントでは、DirectX 8.0 に関する概要を記述する。説明するトピックは、次のとおりである。

  • DirectX 8.0 の新機能
  • DirectX 8.0 ドキュメントの使い方
  • DirectX 8.0 のコンポーネント
  • DirectX ツール
  • C または C++ による DirectX プログラミング
  • 参考資料


DirectX 8.0 の新機能

Microsoft® DirectX® 8.0 でサポートされている新機能のいくつかを以下に示す。

DirectDraw と Direct3D の完全な統合
Microsoft DirectDraw® と Microsoft Direct3D® は単一の DirectX Graphics コンポーネントに統合された。API は大きく変更され、より一層使いやすくなり、最新のグラフィックス ハードウェアがサポートされるようになった。
DirectMusic と DirectSound の統合の強化
Microsoft DirectMusic® と Microsoft DirectSound® の統合が、DirectX 7.0 よりも強化された。ウェーブ ファイルやリソースを DirectMusic ローダーでロードして、MIDI ノートと同期される DirectMusic パフォーマンスで演奏できるようになった。
DirectPlay のアップデート
Microsoft DirectPlay® コンポーネントは大きく拡張されて機能が増え、しかもさらに使いやすくなった。特に DirectPlay では、プレーヤー間の音声通信がサポートされるようになった。
DirectInput のアップデート
Microsoft DirectInput® に主要な機能が追加された。それは、アクション マッピングである。アクション マッピングを使用すると、特定のデバイス オブジェクトに依存せずに、入力アクションと入力デバイス間の接続を確立できる。そのため、入力ループが簡単になり、カスタム ゲーム ドライバ、カスタム デバイス プロファイラ、およびゲームのカスタム構成ユーザー インターフェイスの必要性が低下する。
DirectShow が DirectX に含まれた
Microsoft DirectShow® は現在 DirectX の一部であり、このリリース用に更新された。
デバッグ ビルドが利用可能
DirectX コントロール パネル アプリケーションを使用すると、DirectInput、Direct3D、および DirectMusic のデバッグ ビルドとリテール ビルドを切り替えることができる。この機能を有効にするには、SDK をインストールするときにデバッグ オプションを選択する。このオプションを選択すると、システムには DLL のデバッグ バージョンとリテール バージョンがインストールされる。リテール オプションを選択した場合は、DLL のリテール バージョンだけがインストールされる。


DirectX 8.0 ドキュメントの使い方

以下の表記は説明や簡単なコードのほか、メソッド、関数、およびその他の API 要素の構文で使用される。

表記 | 意味
Italic text (斜体文字列) | プレースホルダまたは変数を表す。ここには実際の値を入れる必要がある。たとえば、本文に SetCursorPos(X, Y) と書かれていた場合、実際のコードでは X および Y の部分には具体的な値を入れなければならない。
Bold text (太字文字列) | プログラミング インターフェイスや言語などでの関数、プロシージャ、構造体、マクロ、インターフェイス、メソッド、データ型、およびその他のキーワードを表す。
[] | 省略可能なパラメータを示す。
... | 直前の項目を繰り返し記述できることを示す。
FULL BOLD CAPITALS (すべて太字の大文字) | 多くの型 (タイプ) と構造体の名前に使用される。
FULL CAPITALS （すべて大文字） | 列挙値、フラグ、および定数に使用される。
monospace (モノスペース) | コード例と構文のスペースに使用される。
. . . | サンプル アプリケーションでの省略部分を示す。


DirectX 8.0 のコンポーネント

Microsoft® DirectX® 8.0 は以下のコンポーネントで構成される。

  • DirectX Graphics は、DirectX の前バージョンの Microsoft DirectDraw® コンポーネントと Microsoft Direct3D® コンポーネントが結合された単一の API であり、すべてのグラフィックス プログラミングに使用できる。コンポーネントには、多くのグラフィックス プログラミング作業を簡単にする Direct3DX ユーティリティ ライブラリが含まれる。
  • DirectX Audio は、前バージョンの DirectX の Microsoft DirectSound® コンポーネントと DirectMusic® コンポーネントが結合された単一の API であり、すべてのオーディオ プログラミングに使用できる。
  • Microsoft DirectInput® は、フォース フィードバック テクノロジのフル サポートなど、さまざまな入力デバイスをサポートしている。
  • Microsoft DirectPlay® は、マルチプレーヤー用ネットワーク ゲームをサポートする。
  • Microsoft DirectShow® は、マルチメディア ストリームの高品質なキャプチャおよび再生を提供する。
  • Microsoft DirectSetup は、複数の DirectX コンポーネントを一度にインストールできるようにするための簡単な API である。


DirectX ツール

以下のツールは、Microsoft® DirectX® アプリケーションの開発とトラブルシューティングに利用できる。

  • DirectX Caps Viewer
  • DirectX コントロール パネル アプリケーション
  • DirectX Diagnostic Tool


DirectX Caps Viewer

説明

DirectX Caps Viewer ツールは、Microsoft® DirectX® のすべてのコンポーネントのデバイスと機能を列挙する。

パス

実行可能ファイル : (SDK ルート)\Bin\DXUtils\DXCapsViewer.exe

ユーザーズ ガイド

ツリー ビューでトピックを選択する。右側のペインに情報が表示される。


DirectX コントロール パネル アプリケーション

SDK と共にインストールされる Microsoft® DirectX® コントロール パネル ユーティリティを使用すると、DirectX コンポーネントのプロパティを調べたり変更することができる。このユーティリティには、各 DirectX コンポーネント用のタブが含まれる。このユーティリティを使うと、次のような作業が可能である。

  • DirectX コンポーネントのバージョン情報を取得する。
  • 開発プロセスでトラブルシューティングに役立つデバッグ出力レベルおよびデバッグ設定を変更する。
  • DirectX コンポーネントの特定のドライバおよびハードウェア サポート情報を表示する。
  • Microsoft Direct3D®、DirectMusic®、および DirectInput® のランタイムをデバッグ バージョンとリテール バージョンの間で切り替える。


DirectX Diagnostic Tool

説明

Microsoft® DirectX® Diagnostic Tool は、コンポーネントが正常に機能しているかどうかをテストするだけでなく、システムとシステムにインストールされている DirectX コンポーネントの情報を収集する。DirectX SDK と共にインストールされるこのツールの特別バージョンを使うことにより、開発者は DirectX 開発チームに問題を直接報告できる。

パス

実行可能ファイル : (Windows ルート)\System32\Dxdiag.exe

ユーザーズ ガイド

DirectX Diagnostic Tool ヘルプ ファイルを表示するには、[Help] ボタンをクリックする。


C または C++ による DirectX プログラミング

通常、C または C++ による Microsoft® DirectX® アプリケーション開発には、従来のプログラミング技法が使用される。ただし、DirectX プログラミングには、従来のプログラミングと異なる特殊な要素がいくつかある。ここでは、DirectX 固有のトピックについて簡単に説明し、DirectX アプリケーションのコンパイルおよびデバッグのガイドラインを示す。

  • COM の使い方
  • コールバック関数の使い方
  • バージョン チェック
  • DirectX のサンプルおよびその他の DirectX アプリケーションのコンパイル
  • DirectX アプリケーションのデバッグ


COM の使い方

コンポーネント オブジェクト モデル (COM) は、さまざまなアプリケーションで使用されているオブジェクト指向プログラミング モデルの 1 つである。通常、Microsoft® DirectX® ランタイムは COM 対応オブジェクトの形式をとる。このため、すべての DirectX 開発者は、COM の原理とプログラミング技法に関する基本的知識が最低限必要である。ただし、一般に COM は複雑で難しいとされているが、ほとんどの DirectX アプリケーションで要求される COM プログラミングは簡単で理解しやすい。

COM プログラミングは大きく 2 つの種類に分類される。

  • 既存の COM オブジェクトを使用する場合。これは、C++ オブジェクトを使用する場合と難易度的に大きな違いはない。
  • 独自の COM オブジェクトを実装する場合。これには、複雑で難しい作業が必要な場合がある。COM が複雑だと言われるのは、この種類の COM プログラミングに起因する。

ほとんどの DirectX アプリケーションは、DirectX に用意されている COM オブジェクトだけを使用している。独自の COM オブジェクトを実装する必要はない。つまり、ほとんどの DirectX 開発者が関わるのは、最初の簡単な種類の COM プログラミングだけでよいことになる。

ここでは、DirectX に用意されている COM オブジェクトの使い方について簡単に説明する。ここでの説明は、主に、COM プログラミング経験の少ない開発者を対象としている。COM オブジェクトの詳細および独自の COM オブジェクトの実装方法については、「参考資料」を参照すること。

  • COM オブジェクトとは
  • COM オブジェクトの作成
  • COM インターフェイスの使い方
  • COM オブジェクトの寿命の管理
  • C による COM オブジェクトへのアクセス
  • マクロによる DirectX COM メソッドの呼び出し
  • DirectX COM ドキュメントの表記規則
  • IUnknown インターフェイス


COM オブジェクトとは

COM オブジェクトは、基本的に、1 つまたは複数のタスクを実行するためにアプリケーションで使用されるブラック ボックスのようなものである。DLL として実装するのが最も一般的である。従来の DLL 同様、COM オブジェクトがサポートしているすべての処理は、オブジェクトによって公開されているメソッドをアプリケーションから呼び出すことによって実行できる。アプリケーションが COM オブジェクトとやり取りする方法は、C++ オブジェクトとやり取りする方法と似ている。ただし、これらの間にはいくつかの顕著な相違点がある。

  • COM オブジェクトは、C++ オブジェクトよりもカプセル化の方法が厳密である。オブジェクトを作成しただけでは、公開のメソッドを呼び出せない。COM オブジェクトの公開メソッドは、1 つまたは複数のインターフェイスにグループ化される。メソッドを使用するには、オブジェクトを作成して、そのオブジェクトに適したインターフェイスを取得する必要がある。通常、各インターフェイスには関連性のある一連のメソッドが含まれており、これらのメソッドがオブジェクトの特定の機能へのアクセスを提供する。たとえば、IDirect3DCubeTexture8 インターフェイスには、キューブ テクスチャ リソースを操作するメソッド群が含まれている。インターフェイスに属さないメソッドにはアクセスできない。
  • COM オブジェクトと C++ オブジェクトは、作成方法が異なる。COM オブジェクトを作成する方法は複数あるが、すべての方法で COM 固有の技法が用いられる。Microsoft® DirectX® API には、さまざまなヘルパー関数およびメソッドが含まれており、これらを使用することによって、ほとんどの DirectX オブジェクトを簡単に作成できる。
  • オブジェクトの寿命を制御するには、COM 固有の技法を用いる必要がある。
  • COM オブジェクトは明示的にロードする必要がない。通常、COM オブジェクトは DLL に含まれている。しかし、COM オブジェクトを使用するために、DLL または静的ライブラリへのリンクを明示的にロードする必要はない。オブジェクトを作成するには、各オブジェクトに割り当てられている一意の登録済み識別子を使用する。COM によって正しい DLL が自動的にロードされる。
  • COM はバイナリ仕様である。COM オブジェクトは、さまざまな言語で記述でき、さまざまな言語でアクセスできる。オブジェクトのソース コードについて知る必要はない。たとえば、Microsoft Visual Basic® アプリケーションでは、C++ で記述された COM オブジェクトがごく一般的に使用される。

オブジェクトとインターフェイス

オブジェクトとインターフェイスの違いを理解するのは重要なことである。オブジェクトは、日常的に、その主となるインターフェイスの名前で呼ばれることもある。しかし、厳密には、この 2 つの用語は意味が異なる。

  • 1 つのオブジェクトが複数のインターフェイスを公開している場合がある。たとえば、すべてのオブジェクトは IUnknown インターフェイスを公開する必要があり、通常、各オブジェクトはこのほかにも 1 つ以上のインターフェイスを公開している。1 つのオブジェクトが多数のインターフェイスを公開することもできる。メソッドを使用するには、そのメソッドのオブジェクトを作成するだけでなく、正しいインターフェイスを取得する必要がある。
  • 複数のオブジェクトが同じインターフェイスを公開している場合がある。インターフェイスは、特定の一連の操作を実行するメソッドの集合である。インターフェイスの定義によって指定されるのは、そのインターフェイスに属するメソッドの構文と一般的な機能だけである。COM オブジェクトは、特定の一連の操作をサポートする手段として、適切なインターフェイスを公開する。専門性が高く、公開しているオブジェクトが 1 つだけのインターフェイスもある。その他のインターフェイスはさまざまな環境で利用でき、多数のオブジェクトによって公開されている。その極端な例が IUnknown インターフェイスである。このインターフェイスは、すべての COM オブジェクトが公開しなければならない。

注 インターフェイスを公開するオブジェクトは、必ず、そのインターフェイス定義に含まれるすべてのメソッドをサポートしなければならない。言い換えれば、メソッドを呼び出すときに、それが存在するかどうかを心配する必要はない。ただし、各メソッドの実装方法はオブジェクトによって異なる場合がある。たとえば、最終的な結果は同じでも、オブジェクトによって、使用するアルゴリズムが異なる場合がある。また、メソッドのすべての機能がサポートされているという保証はない。オブジェクトが一般的なインターフェイスを公開するとき、そのインターフェイスに属するメソッド群のサブセットをサポートするだけでよい場合がある。このとき、サポートされていないメソッドも正常に呼び出すことができるが、E_NOTIMPL が返される。オブジェクトのドキュメントを参照して、各オブジェクトでのインターフェイスの実装状態を確認することを勧める。

COM 標準では、公開済みのインターフェイス定義は変更できないことになっている。たとえば、既存のインターフェイスに新しいメソッドを追加することはできない。インターフェイスを変更するのではなく、新しいインターフェイスを作成する必要がある。インターフェイスに必ず含まなければならないメソッドなどの制約はないが、新しい世代のインターフェイスには、その元になっているインターフェイスのすべてのメソッドと、追加される新しいメソッドを含むのが一般的である。

1 つのインターフェイスに複数の世代が存在することも珍しくない。通常、どの世代でも本質的に全体としては同じタスクを実行するが、細部が異なっている。多くの場合、オブジェクトはすべての世代のインターフェイスを公開する。これによって、古いアプリケーションでは、オブジェクトの古いインターフェイスを継続して使用し、新しいアプリケーションでは、新しいインターフェイスの機能を利用することができる。通常、1 つのファミリに属するインターフェイスにはすべて同じ名前が使用され、そこに世代を示す整数が付加される。たとえば、初代のインターフェイスの名前が IMyInterface であったとすると、次の 2 世代の名前は IMyInterface2 および IMyInterface3 となる。Microsoft DirectX® では、通常、各世代のインターフェイスの名前に DirectX のバージョン番号を使用している。

GUID

グローバル ユニーク識別子 (GUID) は、COM プログラミング モデルの主要な部分の 1 つである。GUID を最も簡単に説明すると、GUID は 128 ビットの構造体である。ただし、GUID を作成するときは、ほかに同じ GUID が存在しないことが保証されなければならない。COM は、主に次の 2 つの目的で GUID を使用する。

  • 特定の COM オブジェクトを識別するため。COM オブジェクトに割り当てられた GUID をクラス ID (CLSID) と呼ぶ。CLSID は、関連付けられている COM オブジェクトのインスタンスを作成するときに使用される。
  • 特定の COM インターフェイスを識別するため。COM インターフェイスに割り当てられた GUID をインターフェイス ID (IID) と呼ぶ。IID は、オブジェクトから特定のインターフェイスを要求するときに使用される。公開しているオブジェクトが異なっても、同じインターフェイスであれば、IID も同じである。

注 通常、ドキュメントでオブジェクトやインターフェイスを呼ぶときは、わかりやすいように IDirect3D8 などの説明的な名前が使用される。ドキュメントでは、文脈によって何を示しているのかがわかるので、混同される心配はほとんどない。ただし、厳密に言えば、同じ説明的名前を持つオブジェクトまたはインターフェイスがほかに存在しないという保証はない。特定のオブジェクトまたはインターフェイスを間違いなく表すことができる唯一の方法は、GUID によるものである。

GUID は構造体であるが、等価な文字列として表現されることもある。GUID の文字列形式では、"{VVVVVVVV-WWWW-XXXX-YYYY-ZZZZZZZZZZZZ}" というフォーマットが一般的である。各文字は、16 進表記の整数である。たとえば、IDirect3D8 インターフェイスの IID を文字列形式で表すと次のようになる。

{1DD9E8DA-1C77-4D40-B0CF-98FEFDFF9512}

実際の GUID は使いづらく、誤入力しやすいので、通常は、GUID と共に等価な名前も用意される。CoCreateInstance などの関数を呼び出すときに、実際の構造体の代わりにこの名前を使用できる。慣習的な名付け規則として、インターフェイスおよびオブジェクトの説明的な名前の先頭には、それぞれ IID_ および CLSID_ が付けられる。たとえば、IDirect3D8 インターフェイスの IID は IID_IDirect3D8 となる。

HRESULT 値

すべての COM メソッドは、HRESULT と呼ばれる 32 ビットの整数を返す。ほとんどのメソッドでは、HRESULT は基本的に 1 つの構造体を形成し、次の 2 つの独立した情報を含んでいる。

  • メソッドが成功したか、失敗したか。
  • メソッドでサポートされている操作の結果に関する詳細情報。

一部のメソッドは、Winerror.h に標準セットとして定義されている値だけを HRESULT 値として返す。ただし、メソッドは、より専門的な情報を表すカスタム HRESULT 値も返すことができる。通常、これらの値は、メソッドのリファレンス ページに記載されている。

注 メソッドのリファレンス ページのリストに記載されている HRESULT 値は、返される可能性がある値のサブセットだけである場合が多い。通常、このリストには、メソッド固有の値と、メソッド固有の意味を持つ標準の値だけが記載されている。ドキュメントに明示的に記載されていなくても、メソッドからは、さまざまな標準の HRESULT 値が返される可能性がある。

HRESULT 値はエラー情報を返すために使用される場合が多いが、これらをエラー コードと見なしてはならない。HRESULT 値には、値詳細情報を含むビットと正否を示すビットが独立して格納されているため、正否を表すコードをいくつでも含めることができる。慣習により、成功コードには S_ というプレフィクスが付けられ、失敗を示すコードには E_ というプレフィクスが付けられる。たとえば、最も一般的に使用されるコードに S_OK および E_FAIL がある。それぞれ、単に成功または失敗を示している。

COM メソッドが正否を示すさまざまなコードを返すということは、HRESULT 値のテスト方法に注意が必要であることを意味する。たとえば、ドキュメントに記載されている戻り値を使って、成功の場合は S_OK が返され、失敗の場合は E_FAIL が返されるという仮説に基づいてテストを行ったとする。しかし、メソッドからは、これ以外の失敗または成功を示すコードが返される可能性もある。次のコードは、単純なテストを用いた場合の危険性を示している。hr は、メソッドによって返された HRESULT 値である。

if(hr == E_FAIL)
  {
    //失敗時の処理を行う。
  }
else
  {
    //成功時の処理を行う。
  }

メソッドが失敗を示すために返す値が E_FAIL だけである限り、このテストは正しく機能する。しかし、メソッドから、E_NOTIMPL や E_INVALIDARG などのエラー値が返される可能性もある。これらの値は成功として解釈され、アプリケーションでエラーが発生する原因となる。

メソッドの呼び出しの結果に関する詳細な情報が必要な場合は、関係のある各 HRESULT 値をテストする必要がある。しかし、必要な情報が、成功か失敗かだけの場合もある。HRESULT 値が成功を示しているのか失敗を示しているのかをテストする強力な方法として、Winerror.h に定義されている次のマクロのいずれかに HRESULT 値を渡すことができる。

  • SUCCEEDED マクロは、成功を示すコードに対しては TRUE を返し、失敗を示すコードに対しては FALSE を返す。
  • FAILED マクロは、失敗を示すコードに対しては TRUE を返し、成功を示すコードに対しては FALSE を返す。

FAILED マクロを使うと、前述のコードを次のように修正できる。

if(FAILED(hr))
  {
    //失敗時の処理を行う。
  }
else
  {
    //成功時の処理を行う。
  }

このコードは、E_NOTIMPL や E_INVALIDARG を失敗として正しく処理する。

ほとんどの COM メソッドは構造化された HRESULT 値を返すが、一部の少数のメソッドでは HRESULT を使って単純な 1 つの整数を返す。これらのメソッドは、非明示的に常に成功する。この種の HRESULT を SUCCESS マクロに渡すと、マクロからは必ず TRUE が返される。一般的に使用される例として、IUnknown::Release メソッドがある。このメソッドは、オブジェクトの reference count を 1 ずつデクリメントして、現在の参照カウントを返す。参照カウントの説明については、「COM オブジェクトの寿命の管理」を参照すること。

ポインタのアドレス

COM メソッドのリファレンス ページを参照すると、次のような表記が見つかる。

HRESULT CreateDevice(
  ...,
  IDirect3DDevice8** ppReturnedDeviceInterface
);

COM では、C や C++ でも使用される通常のポインタのほかに、もう 1 つ別のレベルの間接的呼び出しが使用されることがある。この第 2 のレベルの間接的呼び出しは、タイプの宣言の後に続く "**" で示され、通常、変数名には "pp" というプレフィクスが付く。前述の例の ppReturnedDeviceInterface パラメータは、一般的に、IDirect3DDevice8 インターフェイスへの「ポインタのアドレス」と呼ばれる。

C++ と異なり、COM オブジェクトのメソッドに直接アクセスすることはない。その代わり、メソッドを公開しているインターフェイスへのポインタを取得する必要がある。メソッドを呼び出すときは、C++ のメソッドへのポインタを呼び出すときと同様な構文を使用する。たとえば、IMyInterface::DoSomething メソッドを呼び出すには、次のような構文の使用する。

IMyInterface *pMyIface;
...
pMyIface->DoSomething(...);

間接的呼び出しに第 2 のレベルが必要なのは、インターフェイス ポインタを直接作成しないためである。前述の CreateDevice メソッドのような、さまざまなメソッドの 1 つを呼び出さなければならない。このようなメソッドを使ってインターフェイス ポインタを取得するには、目的のインターフェイスへのポインタを変数として宣言し、その変数のアドレスをメソッドに渡す。つまり、ポインタのアドレスをメソッドに渡す。メソッドが戻ったとき、変数は要求されたインターフェイスを指している。このポインタを使用すると、そのインターフェイスの任意のメソッドを呼び出すことができる。インターフェイス ポインタの使い方の詳細については、「COM インターフェイスの使い方」を参照すること。


COM オブジェクトの作成

COM オブジェクトを作成する方法はいくつかある。Microsoft® DirectX® プログラミングでは、次の 2 つの方法が最も一般的に使用されている。

  • 直接、オブジェクトの CLSID を CoCreateInstance 関数に渡す。この関数は、渡されたオブジェクトのインスタンスを作成し、指定されたインターフェイスへのポインタを返す。
  • 間接的に、オブジェクトを作成する DirectX メソッドまたは関数を呼び出す。呼び出されたメソッドがオブジェクトを作成し、そのオブジェクトのインターフェイスを返す。この方法でオブジェクトを作成する場合、通常は、返されるインターフェイスを指定できない。

オブジェクトを作成する際は、CoInitialize 関数を呼び出してあらかじめ COM を初期化しておく必要がある。間接的にオブジェクトを作成する場合は、オブジェクト作成メソッドによってこの処理が行われる。CoCreateInstance を使ってオブジェクトを作成する必要がある場合は、明示的に CoInitialize を呼び出さなければならない。オブジェクトの作成を終了したら、CoUninitialize を呼び出して COM を未初期化する必要がある。CoInitialize を呼び出したら、必ず対応する CoUninitialize を呼び出さなければならない。COM を明示的に初期化する必要があるアプリケーションでは、スタートアップ ルーチンで COM を初期化し、クリーンアップ ルーチンで未初期化するのが一般的である。

CoCreateInstance で COM オブジェクトの新しいインスタンスを作成するには、オブジェクトの CLSID が必要である。公開されている CLSID は、リファレンス ドキュメントまたは該当するヘッダー ファイルに記述されている。CLSID が公開されていない場合は、そのオブジェクトを直接作成することはできない。

CoCreateInstance 関数には 5 つのパラメータがある。DirectX で使用する COM オブジェクトを作成する場合は、通常、次のパラメータを設定する。

  • rclsid。このパラメータには、作成するオブジェクトの CLSID を設定する。
  • pUnkOuter。このパラメータは NULL に設定する。このパラメータは、オブジェクトを結合するときにだけ使用される。結合の詳細については、「参考資料」を参照すること。
  • dwClsContext。このパラメータは、CLSCTX_INPROC_SERVER に設定する。この設定は、オブジェクトが DLL として実装され、アプリケーションの処理の一部として実行されることを示す。
  • riid。このパラメータには、要求するインターフェイスの IID を設定する。この関数は、オブジェクトを作成して、要求されたインターフェイスへのポインタを ppv パラメータに返す。
  • ppv。このパラメータには、関数が戻ったときに riid によって指定されたインターフェイスに設定されるポインタのアドレスを設定する。この変数を要求されたインターフェイスへのポインタとして宣言し、パラメータ リスト内のポインタへの参照を (LPVOID *) としてキャストする。

たとえば、次のコードは、DirectPlay8 オブジェクトの新しいインスタンスを作成して、IDirectPlay8Peer インターフェイスへのポインタを変数 g_pDP に返している。エラーが発生すると、メッセージ ボックスが表示されて、アプリケーションが終了する。

IDirectPlay8Peer*  g_pDP = NULL;
...
CoInitialize( NULL );
...
hr = CoCreateInstance( CLSID_DirectPlay8, NULL, CLSCTX_INPROC_SERVER,
                         IID_IDirectPlay8Peer, (LPVOID*) &g_pDP );

if( FAILED( hr ) )
  {
    MessageBox( NULL, TEXT("Failed Creating IDirectPlay8Peer. "),
                  TEXT("DirectPlay Sample"), MB_OK | MB_ICONERROR );
    return FALSE;
  }

通常は、オブジェクトを間接的に作成する方が非常に簡単である。オブジェクト作成メソッドにインターフェイス ポインタのアドレスを渡すだけでよい。後は、メソッドによってオブジェクトが作成されて、インターフェイス ポインタが返される。通常、間接的な方法でオブジェクトを作成する場合は、メソッドによって返されるインターフェイスを選択できない。ただし、オブジェクトの作成方法について、さまざまな事項を指定できる。たとえば、次のコードは、前述の IDirect3D8::CreateDevice メソッドを呼び出して、ディスプレイ アダプタを表すデバイス オブジェクトを作成している。このメソッドは、オブジェクトの IDirect3DDevice8 インターフェイスへのポインタを返す。最初の 4 つのパラメータは、オブジェクトを作成するために必要な各種の情報を指定し、5 番目のパラメータはインターフェイス ポインタを受け取る。詳細については、リファレンス ドキュメントを参照すること。

IDirect3DDevice8 *g_pd3dDevice = NULL;
...
if( FAILED( g_pD3D->CreateDevice(D3DADAPTER_DEFAULT,
                                 3DDEVTYPE_HAL,
                                 hWnd,
                                 D3DCREATE_SOFTWARE_VERTEXPROCESSING,
                                 &d3dpp,
                                 &g_pd3dDevice )))
  return E_FAIL;


COM インターフェイスの使い方

オブジェクトを作成すると、作成メソッドからインターフェイス ポインタが返される。このポインタを使用すると、そのインターフェイスの任意のメソッドにアクセスできる。ポインタに使用する構文は、C++ のメソッドの場合と同様である。次のコードは、前のトピックで示した例の拡張である。この例では、DirectPlay8 オブジェクトの作成後、CoCreateInstance から返された IDirectPlay8Peer インターフェイス ポインタを使って IDirectPlay8Peer::Initialize メソッドを呼び出し、オブジェクトを初期化している。わかりやすいように、エラー訂正コードは省略してある。

IDirectPlay8Peer*  g_pDP = NULL;
...
CoInitialize( NULL );
...
hr = CoCreateInstance( CLSID_DirectPlay8, NULL,CLSCTX_INPROC_SERVER,
                         IID_IDirectPlay8Peer, (LPVOID*) &g_pDP );
hr = g_pDP->Initialize( NULL, DirectPlayMessageHandler, 0 );


追加のインターフェイスの要求

通常は、作成メソッドから受け取るインターフェイス ポインタだけで用は足りる。実際、オブジェクトが公開するインターフェイスが IUnknown 以外には 1 つだけであることも少なくない。しかし、多くのオブジェクトは複数のインターフェイスを公開する。このため、複数のインターフェイスへのポインタが必要になる場合もある。作成メソッドによって返されるインターフェイスのほかにもインターフェイスが必要な場合、新しいオブジェクトを作成する必要はない。オブジェクトの IUnknown::QueryInterface メソッドを使って別のインターフェイス ポインタを要求できる。

CoCreateInstance でオブジェクトを作成した場合は、IUnknown インターフェイス ポインタを要求した後、IUnknown::QueryInterface を呼び出すことによって、必要なすべてのインターフェイスを要求できる。ただし、この方法は、必要なインターフェイスが 1 つだけの場合は不便である。また、オブジェクト作成メソッドを使わない場合は、返すインターフェイス ポインタを指定できないので、まったく機能しない。実際には、すべての COM インターフェイスは IUnknown インターフェイスを継承または拡張しているので、通常は、明示的な IUnknown ポインタを取得する必要はない。

インターフェイスの拡張は、C++ のクラスの継承に似ている。子インターフェイスは、親インターフェイスのすべてのメソッドと子独自のメソッドを公開する。実際、「拡張」の代わりに「継承」という表現を使用することも多い。ただし、継承はオブジェクト内部で行われるものである。アプリケーションがオブジェクトのインターフェイスを継承または拡張することはできない。しかし、子インターフェイスを使うと、子と親の両方のインターフェイスのすべてのメソッドを呼び出すことができる。

すべてのインターフェイスは IUnknown の子である。このため、オブジェクトに対して取得してどのインターフェイスを使っても、QueryInterface を呼び出すことができる。QueryInterface を呼び出す場合は、要求するインターフェイスの IID とインターフェイス ポインタのアドレスを指定する必要がある。メソッドから戻るとき、このポインタにインターフェイス ポインタが格納される。たとえば、次のコードは IDirectSound8::CreateSoundBuffer を呼び出してプライマリ サウンド バッファ オブジェクトを作成している。このオブジェクトは、複数のインターフェイスを公開する。CreateSoundBuffer メソッドは IDirectSoundBuffer8 インターフェイスを返す。次のコードでは、IDirectSoundBuffer8 インターフェイスを使って QueryInterface を呼び出すことによって、IDirectSound3DListener8 インターフェイスを要求している。

IDirectSoundBuffer8* pDSBPrimary = NULL;
IDirectSound3DListener8* pDSListener;
...
if(FAILED(hr = g_pDS->CreateSoundBuffer( &dsbd, &pDSBPrimary, NULL )))
  return hr;

if(FAILED(hr = pDSBPrimary->QueryInterface(IID_IDirectSound3DListener8,
                                           (LPVOID *)&pDSListener)))
  return hr;


COM オブジェクトの寿命の管理

オブジェクトが作成されると、システムによって必要なメモリ リソースが割り当てられる。必要がなくなったオブジェクトは破棄しなければならない。オブジェクトを破棄すれば、システムは、その分のメモリをほかの目的に利用できる。C++ オブジェクトでは、new および delete の各演算子を使ってオブジェクトの寿命を直接制御できる。COM では、オブジェクトを直接作成したり破棄することはできない。これは、同じオブジェクトを複数のアプリケーションが使用している可能性があるからである。複数のアプリケーションで使用されているオブジェクトを 1 つのアプリケーションが破棄すると、ほかのアプリケーションでは高い確率でエラーが発生する。COM では、「参照カウント」というシステムを使ってオブジェクトの寿命を制御している。

オブジェクトの参照カウントは、そのオブジェクトのいずれかのインターフェイスが要求された回数を示す。インターフェイスが要求されるたびに、参照カウントはインクリメントされる。アプリケーションが必要のなくなったインターフェイスを解放すると、参照カウントはデクリメントされる。オブジェクトは、参照カウントが 0 にならない限り、メモリ上に保持される。参照カウントが 0 になると、そのオブジェクト自体によって自動的に破棄される。オブジェクトの参照カウントについて知る必要はない。オブジェクトのインターフェイスの取得および解放を正しく行っている限り、オブジェクトの寿命は適切に制御される。

注 COM プログラミングでは参照カウントを正しく処理することが非常に重要である。この処理を正しく行わないと、メモリ リークが生じやすくなる。COM プログラマが最も冒しやすいミスの 1 つが、インターフェイスの解放し忘れである。インターフェイスが解放されないと、参照カウントがいつまでも 0 にならず、オブジェクトは半永久的にメモリに残っていることになる。

参照カウントのインクリメントとデクリメント

新しいインターフェイス ポインタを取得するときは、必ず IUnknown::AddRef を呼び出して参照カウントをインクリメントする必要がある。ただし、通常、アプリケーションでこのメソッドを呼び出す必要はない。オブジェクト作成メソッドまたは IUnknown::QueryInterface を呼び出してインターフェイス ポインタを取得した場合は、オブジェクトによって自動的に参照カウントがインクリメントされる。しかし、既存のポインタをコピーするなど、その他の方法でインターフェイス ポインタを取得した場合は、IUnknown::AddRef を明示的に呼び出す必要がある。これを行わないと、元のインターフェイス ポインタを解放したときに、そのポインタのコピーを継続して使用する必要があっても、オブジェクトが破棄される場合がある。

参照カウントをインクリメントしたのがアプリケーションであるかオブジェクトであるかにかかわらず、すべてのインターフェイス ポインタはアプリケーションによって解放しなければならない。インターフェイス ポインタが不要になった場合は、IUnknown::Release を呼び出して参照カウントをデクリメントする。すべてのインターフェイス ポインタにおいて、初期化時に NULL に設定し、解放時に再び NULL に設定するのが一般的である。これによって、クリーンアップ コードで、すべてのインターフェイス コードをテストできる。NULL でないポインタはまだアクティブであり、アプリケーションを終了する前に解放する必要がある。

次のコードは、「追加のインターフェイスの要求」で説明したサンプルを、参照カウントの処理方法を示すために拡張したものである。

IDirectSoundBuffer8* pDSBPrimary = NULL;
IDirectSound3DListener8* pDSListener = NULL;
IDirectSound3DListener8* pDSListener2 = NULL;
...
//オブジェクトを作成し、追加のインターフェイスを取得する。
//オブジェクトによって参照カウントがインクリメントされる。
if(FAILED(hr = g_pDS->CreateSoundBuffer( &dsbd, &pDSBPrimary, NULL )))
  return hr;

if(FAILED(hr=pDSBPrimary->QueryInterface(IID_IDirectSound3DListener8,
                                           (LPVOID *)&pDSListener)))
  return hr;

//IDirectSound3DListener8 インターフェイス ポインタのコピーを作成する。
//AddRef を呼び出して参照カウントをインクリメントする。これによって、
//使用中のオブジェクトが破棄されるのを防ぐことができる。
pDSListener2 = pDSListener;
pDSListener2->AddRef();
...
//クリーンアップ コード。ポインタがまだアクティブであるかどうかを確認する。
//アクティブであれば、Release を呼び出してインターフェイスを解放する。
if(pDSBPrimary != NULL)
{
  pDSBPrimary->Release();
  pDSBPrimary = NULL;
}
if(pDSListener != NULL)
{
  pDSListener->Release();
  pDSListener = NULL;
}
if(pDSListener2 != NULL)
{
  pDSListener2->Release();
  pDSListener2 = NULL;
}


C による COM オブジェクトへのアクセス

COM プログラミングで最も一般的に使用されている言語は C++ であるが、C でも COM オブジェクトにアクセスできる。C を使用した方法は、操作は直接的だが、複雑な構文が必要になる。

  • すべてのメソッドで、パラメータ リストの最初にパラメータが 1 つ追加されている。このパラメータには、インターフェイス ポインタを設定する必要がある。
  • オブジェクトの vtable を明示的に参照する必要がある。

すべての COM オブジェクトにはそれぞれ vtable があり、この中には、そのオブジェクトが公開しているメソッドへのポインタのリストが含まれている。インターフェイス ポインタは vtable 内の場所を示している。そこには、呼び出されたメソッドへのポインタが格納されている。このドキュメントのほかの場所では、vtable については説明されていない。これは、C++ では、vtable は基本的に非可視だからである。ただし、C で COM メソッドを呼び出す場合は、間接的呼び出しのレベルを 1 つ追加して、vtable を明示的に参照する必要がある。

次のコードは、C++ での呼び出し規則を使って IDirectPlay8Peer::Initialize メソッドを呼び出す方法を示している。

g_pDP->Initialize( NULL, DirectPlayMessageHandler, 0 );

C で同じメソッドを呼び出すには、次の構文を使用する。vtable ポインタの名前は lpVtbl と表記される。

g_pDP->lpVtbl->Initialize(g_pDP,NULL, DirectPlayMessageHandler, 0);

コンポーネントによっては、ヘッダー ファイルに、呼び出し用の正しい表記に変換するマクロが定義されている場合もある。詳細については、「マクロによる DirectX COM メソッドの呼び出し」を参照すること。


マクロによる DirectX COM メソッドの呼び出し

Microsoft® DirectX® インターフェイスの多くには、アプリケーションでより簡単にメソッドを使用できるように、各メソッド用に定義されたマクロが用意されている。これらのマクロは、インターフェイスの宣言と同じヘッダー ファイルで定義されている。マクロは、C と C++ の両方のアプリケーションで使用できるように設計されている。C++ マクロを使用するには、_cplusplus を定義する必要がある。これを定義しない場合は、C マクロが使用される。マクロの構文はどちらの言語でも同じであるが、ヘッダー ファイルに含まれる一連のマクロ定義は異なり、それぞれの適切な呼び出し表記が使用される。

たとえば、d3d.h ヘッダー ファイル内の次のコードでは、IDirect3D8::GetAdapterIdentifier メソッドに対する C と C++ 両方のマクロが定義されている。

#if !defined(__cplusplus) || defined(CINTERFACE)

...
#define IDirect3D8_GetAdapterIdentifier(p,a,b,c) (p)->lpVtbl->GetAdapterIdentifier(p,a,b,c)
...
#else
...
#define IDirect3D8_GetAdapterIdentifier(p,a,b,c) (p)->GetAdapterIdentifier(a,b,c)
...

#endif

これらのマクロのいずれかを使用するには、まず、関連付けられているインターフェイスへのポインタを取得する必要がある。マクロの最初のパラメータに、このポインタを設定する。その他のパラメータは、メソッドのパラメータに対応している。マクロの戻り値は、メソッドによって返される HRESULT 値である。次のコードは、マクロを使って IDirect3D8::GetAdapterIdentifier メソッドを呼び出している。pD3D は、IDirect3D8 インターフェイスへのポインタである。

hr = IDirect3D8_GetAdapterIdentifier(pD3D,
                                     Adapter,
                                     dwFlags,
                                     pIdentifier);


DirectX COM ドキュメントの表記規則

便宜上、DirectX COM ドキュメントでは、COM メソッドおよびインターフェイスに同等の C++ クラスの名前が使用される。したがって、IDirectPlay8Peer インターフェイスの Initialize メソッドは、IDirectPlay8Peer::Initialize のように表記される。このような表記規則を使用する主な理由は、同じ名前で機能や構文はまったく異なるメソッドが、複数の異なるインターフェイスによって公開される場合があるからである。たとえば、多くのインターフェイスに Init メソッドまたは Initialize メソッドが含まれるが、その機能やパラメータはまったく異なる。C++ のクラス名を使うのは、メソッドを一意に識別する便利な方法である。

通常、テキストやサンプル コードでは、COM メソッドを呼び出すときに C++ の表記規則を使用する。C++ のメソッド呼び出しを等価な C の呼び出しに変換する方法については、「C による COM オブジェクトへのアクセス」を参照すること。


IUnknown インターフェイス

COM オブジェクトはいずれも、IUnknown というインターフェイスをサポートする。このインターフェイスは、オブジェクトの寿命を制御する機能およびオブジェクトに実装されるほかのインターフェイスを取得する機能を Microsoft® DirectX® に提供する。IUnknown は、次の 3 つのメソッドを持つ。

  • AddRef。インターフェイスまたはほかのアプリケーションがオブジェクトにバインドしてきたときに、オブジェクトの参照カウントを 1 ずつインクリメントする。
  • QueryInterface。特定のインターフェイスへのポインタを要求することにより、オブジェクトがサポートしている機能について問い合わせる。
  • Release。オブジェクトの参照カウントを 1 ずつデクリメントする。参照カウントが 0 になると、そのオブジェクトは解放される。

AddRef メソッドと Release メソッドは、オブジェクトの参照カウントを管理する。たとえば、Microsoft Direct3D® オブジェクトを作成したとする。作成直後、このオブジェクトの参照カウントは 1 に設定される。このオブジェクトのインターフェイスへのポインタを返す関数を作成する場合は、返すポインタを使って AddRef を呼び出し、ポインタを返すたびに参照カウントをインクリメントしておくようにしなければならない。また、AddRef を呼び出した場合は、必ず対応する Release を呼び出さなければならない。ポインタを破棄するには、その前にそのポインタを使って Release を呼び出さなければならない。オブジェクトの参照カウントが 0 になると、オブジェクトは破棄され、そのオブジェクトへのインターフェイスはすべて無効になる。

QueryInterface メソッドは、オブジェクトが指定されたインターフェイスをサポートしているかどうかを調べる。目的のインターフェイスがサポートされていた場合は、そのインターフェイスへのポインタが返される。このポインタを取得できたら、そのインターフェイスが持つ各種メソッドを使ってオブジェクトとやり取りできるようになる。正常にインターフェイスへのポインタが返された場合、QueryInterface はその内部で AddRef を呼び出して参照カウントをインクリメントしている。このため、QueryInterface により取得したポインタを破棄するときは、その前にアプリケーションから Release を呼び出して参照カウントをデクリメントしておかなければならない。

動作環境

Windows NT/2000 : Windows NT 3.1 以降が必要。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Unknwn.h で宣言。


IUnknown::AddRef

オブジェクトの参照カウントを 1 だけ増加させる。

ULONG AddRef();

パラメータ

パラメータなし。

戻り値

新しい参照カウント値を返す。この値は、診断およびテストだけを目的とした値である。

注意

オブジェクトを作成すると、作成したオブジェクトの参照カウントは 1 に設定される。その後、アプリケーションがそのオブジェクトのインターフェイスを取得するか、または AddRef メソッドを呼び出すたびに、オブジェクトの参照カウントは 1 ずつ増加する。Release メソッドを呼び出すと、オブジェクトの参照カウントは 1 だけ減少する。

動作環境

Windows NT/2000 : Windows NT 3.1 以降が必要。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Unknwn.h で宣言。


IUnknown::QueryInterface

オブジェクトが特定の COM インターフェイスをサポートしているかどうかを判別する。インターフェイスがサポートされていた場合は、オブジェクトの参照カウントが 1 だけ増加する。アプリケーションは、このメソッドの呼び出し直後からそのインターフェイスを使用できるようになる。

HRESULT QueryInterface(
  REFIID riid,
  LPVOID* ppvObj
);

パラメータ

riid
要求するインターフェイスの参照識別子。
ppvObj
目的のインターフェイスがサポートされていた場合に、インターフェイスへのポインタが格納されるポインタ変数のアドレス。

戻り値

成功した場合は、S_OK を返す。

失敗した場合は、E_NOINTERFACE または E_POINTER を返す。また、コンポーネントの中には、これらのエラー値に対する個別の定義をヘッダー ファイルに格納しているものもある。たとえば、Microsoft® DirectInput® では DIERR_NOINTERFACE と E_NOINTERFACE は同じ値である。

注意

このメソッドの呼び出しにより取得したインターフェイスを実際に使用する必要がない場合は、取得したインターフェイスの Release メソッドを呼び出してインターフェイスを解放しなければならない。QueryInterface メソッドにより、Microsoft およびサード パーティ各社は、既存の機能や将来追加される機能と衝突することなくオブジェクトを拡張できるようになる。

動作環境

Windows NT/2000 : Windows NT 3.1 以降が必要。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Unknwn.h で宣言。


IUnknown::Release

オブジェクトの参照カウントを 1 だけ減少させる。

ULONG Release();

パラメータ

パラメータなし。

戻り値

新しい参照カウント値を返す。この値は、診断およびテストだけを目的とした値である。

注意

オブジェクトは、参照カウントが 0 になると解放される。AddRef メソッドを呼び出すと、オブジェクトの参照カウントは 1 だけ増加する。

IUnknown::AddRef または IUnknown::QueryInterface を呼び出したか、または Direct3DCreate8 などのオブジェクト作成関数を呼び出して明示的に作成したインターフェイスがある場合は、必ずこのメソッドを呼び出してインターフェイスを解放しなければならない。インターフェイスだけを解放するのに必要な処理は、このメソッドの呼び出しである。

動作環境

Windows NT/2000 : Windows NT 3.1 以降が必要。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Unknwn.h で宣言。


コールバック関数の使い方

コールバック関数は基本的にイベント ハンドラの 1 つで、アプリケーションによって実装されて、システムによって呼び出される。通常、Microsoft® Windows® アプリケーションには複数のコールバック関数が実装されており、それぞれ異なるグループのイベントの処理に使用される。イベントが発生すると、システムは適切なコールバック関数を呼び出してアプリケーションに通知する。また、通常、コールバック関数はパラメータ リストを保持しており、システムはこのリストを使ってイベントに関する詳細情報をアプリケーションに渡す。コールバック関数の最も一般的な例はウィンドウ プロシージャである。この関数は、システムがウィンドウを所有するアプリケーションに Windows メッセージを渡すときに使用される。

Microsoft DirectX® では、コールバック関数をさまざまな目的に使用している。たとえば、システムは複数のデバイスをサポートしている。Microsoft DirectInput® は各デバイスをデバイス オブジェクトで表す。デバイス オブジェクトには、そのデバイスの機能に関する詳細情報が含まれている。通常、アプリケーションがユーザーの入力を正しく処理するには、利用可能なデバイスを列挙して、デバイス オブジェクトを調べる必要がある。この列挙を実行するには、DIEnumDeviceObjectsCallback コールバック関数を実装しなければならない。

列挙を実行するための最初の処理は、IDirectInputDevice8::EnumObjects の呼び出しである。次に、DIEnumDeviceObjectsCallback コールバック関数へのポインタをメソッドに渡す。システムは、各デバイスに対して 1 回ずつこの関数を呼び出し、デバイスの機能に関する情報を含む DIDEVICEOBJECTINSTANCE 構造体を渡す。コールバック関数は、この情報を処理した後、次のデバイス オブジェクトを要求する場合は DIENUM_CONTINUE を返し、列挙を停止する場合は DIENUM_STOP を返す。

詳細については、「コールバック関数の実装」を参照すること。

DirectX では、ほかにもさまざまなコールバック関数がさまざまな目的のために使用される。詳細については、各 DirectX コンポーネントのドキュメントを参照すること。


コールバック関数の実装

コールバック関数にはさまざまな目的および用途がある。このため、通常の関数と同様、コールバック関数についても、各関数のトピックで説明する。ただし、コールバック関数のリファレンスは、通常の API のリファレンスと異なり、その関数を実装する方法を示すテンプレートになっている。コールバック関数のリファレンスは、次の情報を提供する。

  • 関数の使い方
  • 関数の構文
  • 各パラメータに格納される情報の説明
  • 返される可能性のある戻り値の説明

コールバック関数は、CALLBACK 型または WINAPI 型として宣言する。どちらのタイプを使用してもよい。関数名は自由に付けられる。ドキュメントで使用されている名前は、コールバック関数の単なる便宜上のラベルである。

リファレンスの説明に従って関数を実装する。実装方法の詳細は、各関数やアプリケーションの要件によって異なる。さまざまなコールバック関数の実装方法の例については、サンプル コードを参照すること。

関数へのポインタを適切な Microsoft® DirectX® コンポーネントに渡す。DirectX コンポーネントは、この関数ポインタを使って関数を呼び出す。このポインタの渡し方は、関数によって異なるので、詳細については各関数のリファレンスを参照すること。

次のコードは、Microsoft DirectInput® Joystick サンプルの一部である。このコードには、ジョイスティックの軸を列挙するために使用される DIEnumDeviceObjectsCallback の実装の基本的な要素が含まれている。

//関数の宣言。
BOOL CALLBACK EnumAxesCallback( const DIDEVICEOBJECTINSTANCE* pdidoi,
                                VOID* pContext );
...
//IDirectInputDevice8::EnumObjects メソッドを呼び出して
//DirectInput への関数ポインタを渡す。
if ( FAILED( hr = g_pJoystick->EnumObjects( EnumAxesCallback,
                                           (VOID*)hDlg,
                                            DIDFT_AXIS )));
...
//関数の実装。
BOOL CALLBACK EnumAxesCallback( const DIDEVICEOBJECTINSTANCE* pdidoi,
                                VOID* pContext )
{
//2 つのパラメータで渡された情報を処理する。
//次のデバイス オブジェクトを要求する場合は DIENUM_CONTINUE を返す。
//列挙を停止する場合は DIENUM_STOP を返す。
}


バージョン チェック

アプリケーションでは、システムで現在利用可能な Microsoft® DirectX® のバージョン情報が必要になる場合がある。たとえば、システムに古いバージョンの DirectX が存在する場合、アプリケーションはそのバージョンに機能の範囲を合わせるか、最新のバージョンをインストールする必要が生じることがある。

DirectX のバージョン番号を直接取得する方法はない。ただし、各バージョンは、固有のオブジェクトおよびインターフェイスを含んでいる。DirectX のすべてのバージョンは、以前のすべてのバージョンをサポートしている。このため、特定のバージョン固有のインターフェイスおよびオブジェクトは、それらを導入したバージョンとすべての後続バージョンでサポートされる。したがって、必要なバージョンが利用可能かどうかを調べるには、そのバージョン固有のオブジェクトまたはインターフェイスが存在するかどうかをテストするとよい。それらのオブジェクトまたはインターフェイスが存在する限り、それよりも新しいバージョンの DirectX を使用していても、アプリケーションは正常に機能する。

たとえば、バージョン 6.1 のサポートが必要であるとする。Microsoft DirectMusic® オブジェクト (CLSID_DirectMusic) は、DirectX Version 6.1 から導入されたオブジェクトである。DirectMusic オブジェクトの存在は、CoCreateInstance を使ってこのオブジェクトの作成を試みることによってテストできる。成功した場合は、バージョン 6.1 以降がインストールされているので、DirectX 6.1 のすべての機能を使用できる。

ここでは、各バージョン固有のインターフェイスおよびオブジェクトの詳細なリストは示さないので、DirectX ソフトウェア開発キットのサンプルのセクションを参照すること。サンプルの 1 つの GetDXVersion という関数には、DirectX のすべてのバージョンに関するテストが含まれている。GetDXVersion は、そのシステムに存在する DirectX のバージョンに対応する整数を返す。この整数が必要なバージョンの番号と同じであるか、それよりも大きければ、アプリケーションは正常に実行される。サンプル コードは、SDK のルート フォルダの \Samples\Multimedia\DXMisc\GetDXVer にある。

詳細については、「オペレーティング システムのバージョンのチェック」を参照すること。


オペレーティング システムのバージョンのチェック

アプリケーションでは、Microsoft® DirectX® のバージョンだけでなく、それが実行されているオペレーティング システムやインストールされているサービス パックの情報が必要になる場合がある。オペレーティング システムのバージョンを調べるには、Microsoft Windows® 関数の GetVersionEx を使用するとよい。この関数は、次の各種情報を含む OSVERSIONINFO 構造体を返す。

  • そのシステムが Microsoft Windows NT® ベースか Windows 95/98/ME か
  • メジャー バージョン番号およびマイナー バージョン番号
  • サービス パック番号 (Windows NT ベースのシステムの場合)

アプリケーションが対応している最も古いオペレーティング システムについて調べるのが一般的である。そのバージョン以降がインストールされていれば、インストールしたアプリケーションは正常に実行される。

注 GetVersionEx によって返されるオペレーティング システム情報は、DirectX の存在またはバージョン番号を調べるテストには使用できない。特に、システムが Windows NT ベースであるからといって、DirectX が存在しないとは限らない。たとえば、Windows 2000 オペレーティング システムには DirectX 7.0 以降が含まれている。Windows NT ベースのオペレーティング システムの今後のバージョンでも、DirectX のバージョンが含まれるものと予測される。DirectX の存在とバージョン番号は、前のトピックで説明した手順で調べる必要がある。

次のサンプル関数は、GetVersionEx を使ってオペレーティング システムのバージョンをテストする方法を示している。インストールされているバージョンがパラメータ リストに指定されているバージョン以降であれば、関数は TRUE を返す。この場合、インストールしたアプリケーションは正常に実行される。それ以外の場合、関数は FALSE を返す。これは、アプリケーションをインストールしても正しく実行されないことを意味する。

#include <windows.h>
#include <stdio.h>
#include <tchar.h>

BOOL bIsWindowsVersionOK(   DWORD dwWin9xMajor, DWORD dwWin9xMinor,
                            DWORD dwWinNTMajor, DWORD dwWinNTMinor, WORD wWinNTSPMajor )
{
    OSVERSIONINFO           osvi;

    // OSVERSIONINFO 構造体を初期化する。
    ZeroMemory( &osvi, sizeof( osvi ) );
    osvi.dwOSVersionInfoSize = sizeof( osvi );

    GetVersionEx( &osvi );  // この関数が成功したと仮定する。

    // コードのパスを NT の場合と Win9x の場合に分ける。
    if( osvi.dwPlatformId == VER_PLATFORM_WIN32_WINDOWS )
    {
        // メジャー バージョンをチェックする。
        if( osvi.dwMajorVersion > dwWin9xMajor )
            return TRUE;
        else if( osvi.dwMajorVersion == dwWin9xMajor )
        {
            // マイナー バージョンをチェックする。
            if( osvi.dwMinorVersion >= dwWin9xMinor )
                return TRUE;
        }
    }
    else if( osvi.dwPlatformId == VER_PLATFORM_WIN32_NT )
    {
        // メジャー バージョンをチェックする。
        if( osvi.dwMajorVersion > dwWinNTMajor )
            return TRUE;
        else if( osvi.dwMajorVersion == dwWinNTMajor )
        {
            // マイナー バージョンをチェックする。
            if( osvi.dwMinorVersion > dwWinNTMinor )
                return TRUE;
            else if( osvi.dwMinorVersion == dwWinNTMinor )
            {
                // サービス パックをチェックする。
                DWORD dwServicePack = 0;

                if( osvi.szCSDVersion )
                {
                    _stscanf(   osvi.szCSDVersion,
                                _T("Service Pack %d"),
                                &dwServicePack );
                }
                return ( dwServicePack >= wWinNTSPMajor );
            }
        }
    }
    return FALSE;
}


DirectX のサンプルおよびその他の DirectX アプリケーションのコンパイル

ここでは、Microsoft® DirectX® アプリケーションのコンパイル時に考慮すべき点について説明する。DirectX 8.0 は、Microsoft Visual C++ 5.0 SP3 以降のみをサポートする。

  • コンパイルの準備
  • コンポーネントのバージョン定数


コンパイルの準備

この SDK に含まれている各サンプルには、サンプル用のソース ファイル、プロジェクト リソース、リンカなどの設定情報を記述した Microsoft® Visual C++® のプロジェクト ファイル (DSP ファイル) が用意されている。しかし、サンプルを確実にコンパイルし、リンクするには、サンプルをコンパイルする開発者が若干設定作業を行わなければならない場合もある。また、新しいプロジェクトを作成するため、そのプロジェクト用の設定情報を開発者が自分で用意しなければならない場合もある。ここでは、Microsoft DirectX® のサンプルにも、開発者が独自に開発する DirectX アプリケーションにも該当する内容を説明する。

Visual C++ でプロジェクト ファイルを開いた後、アプリケーションをコンパイルする前にいくつかの設定値をチェックしなければならない。以降の説明は、Microsoft Visual C++ 5 および 6 に有効である。

注 以降の説明ではデフォルトのインストール パス (C:\Mssdk\Include および C:\Mssdk\Lib) を使い、ファイルの場所を記述する。インストール パスは異なる場合もある。

インクルード ファイルの検索パス

ヘッダー ファイルのパスが正しいこと、および DirectX のヘッダー ファイルのディレクトリがコンパイラに最初に検索されるパスになっていることを確認すること。インクルード パスを確認するには、［ツール］ メニューの ［オプション］ をクリックし、［ディレクトリ］ タブをクリックする。これにより、次のようなダイアログ ボックスが表示される。

ここでリストの先頭に表示されているパスが、最新の DirectX のヘッダー ファイルを置いているフォルダになっていなければならない。このデフォルト パスは、C:\Mssdk\Include である。このパスが表示されていない場合は、それをリストに追加し、［ディレクトリ］ タブ内のツールバー コントロールを使ってそのパスをリストの先頭へ移動すること。

リンカの検索パス

リンカがリンク ライブラリを検索する際に使用する検索パスと、その検索順を確認すること。リンクの検索パスのリストも、[ディレクトリ] タブで確認できる。これを行うには、[ツール] メニューの [オプション] をクリックし、[ディレクトリ] タブをクリックする。ダイアログ ボックスが表示されたら、［表示するディレクトリ］ ドロップダウン リスト ボックスの ［ライブラリ ファイル］ をクリックする。これにより表示されたリストの先頭のパスが、最新の DirectX のリンク ライブラリを置いているフォルダになっていなければならない。このデフォルト パスは、C:\Mssdk\Lib である。

プロジェクトのリンク ライブラリ

サンプルと一緒に提供されたプロジェクト ファイルを使用する場合は、この設定を確認する必要はない。この設定値はプロジェクト ファイル内で指定されている。新しいアプリケーションをコンパイルする場合は、[プロジェクト] メニューの [設定] をクリックする。これにより、次のようなダイアログ ボックスが表示される。

アプリケーションが適切な標準 DirectX リンク ライブラリにリンクされることも確認しなければならない。


コンポーネントのバージョン定数

Microsoft® DirectX® の以前のバージョンとの互換性を保持するため、いくつかの DirectX コンポーネントはヘッダー ファイルにさまざまな API 要素を定義している。通常、影響される要素は、バージョン固有の構造体の能力やフラグ セットである。いくつかのヘッダー ファイル部分は、プリプロセッサが不必要な定義を除外するプリプロセッサ条件文で囲まれている。定義済み定数の値は、コンポーネントの特定のバージョンを表している。値が定義されていない場合は、ヘッダー ファイルを記述するときに使用された DirectX のバージョンを識別する値が設定される。Microsoft Direct3D® のヘッダー ファイル (D3D8.h) の例を次に示す。

#ifndef DIRECT3D_VERSION
#define DIRECT3D_VERSION         0x0800
#endif  //DIRECT3D_VERSION

これらの定数にほかの値を定義すると、古いバージョンのコンポーネントで新しいバージョンのヘッダー ファイルを使用できる。たとえば、DirectX 7.0 バージョンの D3D のコンパイルに最新のヘッダー ファイルを使用するには、DIRECT3D_VERSION に 0x0700 を定義する。


DirectX アプリケーションのデバッグ

ここでは、C および C++ アプリケーションのデバッグについて説明する。説明するトピックは、次のとおりである。

  • デバッグ用とリテール用の DLL
  • DirectX 8.0 エラー処理ユーティリティ ライブラリ


デバッグ用とリテール用の DLL

Microsoft® DirectX® SDK インストール プログラムは、DirectX ダイナミックリンク ライブラリ (DLL) のデバッグ ビルドまたはリテール ビルドのいずれかのインストール オプションを提供する。

C++ でソフトウェアを開発している場合は、DLL のデバッグ バージョンをインストールするとよい。このオプションを選択すると、システムには DLL のデバッグ バージョンとリテール バージョンがインストールされる。リテール オプションを選択した場合は、DLL のリテール バージョンだけがインストールされる。DLL のデバッグ バージョンには内部データ構造を検証する追加コードがあり、プログラムの実行中に (Microsoft Win32® OutputDebugString 関数を使って) デバッグのエラー メッセージを出力する。エラーが発生すると、問題の詳細がデバッグ出力される。DLL のデバッグ バージョンはリテール バージョンよりも動作が遅いが、アプリケーションのデバッグにはリテール バージョンよりも役立つ。アプリケーションを出荷する場合は、リテール バージョンを出荷すること。

DirectX コントロール パネル ユーティリティを使用すると、DirectInput®、Direct3D®、および DirectMusic® のデバッグ ビルドとリテール ビルドを切り替えることができる。この機能を有効にするには、SDK をインストールするときにデバッグ オプションを選択する。

デバッグ メッセージを確認するには、ウィンドウ内やリモート コンピュータにデバッグ出力が表示されるよう、システムの構成を設定する。Microsoft Visual C++® などの開発環境では、この設定が可能である。設定方法については、開発環境についてのドキュメントを参照すること。

デバッグ用のビルドを使用する場合は、デバッガが関連するシンボリック情報を確実に見つけられるようにするために、以下に示す場所にシンボル ファイルを置いておかなければならない。

OS | デバッガ | .pdb ファイルの場所 | .dbg ファイルの場所
Windows® 95、Windows 98 | Visual C++ | バイナリと同じディレクトリ | バイナリと同じディレクトリ
Windows® NT、Windows 2000 | Visual C++ | バイナリと同じディレクトリ | %SystemRoot%\Symbols\<binary extension>\
Windows NT、Windows 2000 | NTSD/KD | %SystemRoot%\Symbols\<binary extension>\ | %SystemRoot%\Symbols\<binary extension>\

注 Microsoft Windows NT および Windows 2000 で Visual C++ 開発システムを使ってデバッグする場合は、開発ツールの WIN32API Splitsym を使用してはならない。WIN32API Splitsym は、プライベート シンボリック情報を <binary>.dbg ファイルからバイナリ エクステンションのシンボル ディレクトリ (%SystemRoot%\Symbols\Dll\ など) にコピーし、バイナリ ディレクトリからは元のファイルを削除してしまう。Visual C++ を使用するには、プライベート シンボリック情報のファイル (<binary>.dbg) がバイナリ ファイルと同じディレクトリに置かれている必要がある。したがって、デバッグ用のビルドを使用する場合は、プライベート シンボリック情報のコピーだけを行い、削除を行ってはならない。これが問題となるのは、Windows NT および Windows 2000 で Visual C++ を使用する場合だけである。その他のデバッグ情報については、Visual C++ のドキュメントおよび Windows 2000 Driver Development Kit (DDK) のドキュメントを参照すること。


DirectX 8.0 エラー処理ユーティリティ ライブラリ

Microsoft® DirectX® 8.0 SDK には、アプリケーションのデバッグ作業を簡易化するために、2 つのユーティリティ関数と各種のマクロが用意されている。これらの関数およびマクロは Dxerr8.lib ライブラリに含まれている。宣言は Dxerr8.h で行われる。

  • DirectX 8.0 エラー処理関数
  • DirectX 8.0 エラー処理マクロ


DirectX 8.0 エラー処理関数

次の関数およびマクロは、DirectX エラー処理ユーティリティ ライブラリに含まれている。

  • DXGetErrorString8
  • DXTrace


DXGetErrorString8

Microsoft® DirectX® のエラー コードに関連付けられている名前を返す。

TCHAR* DXGetErrorString8(
  HRESULT hr
);

パラメータ

hr
[in] DirectX メソッドによって返される HRESULT 値。エラー コード専用。

戻り値

成功した場合は、指定されたエラー コードの名前を含む文字列へのポインタを返す。Unicode が設定されている場合、DXGetErrorString8 は Unicode の文字列を返す。それ以外の場合は、ANSI 文字列を返す。

注意

この関数は、Microsoft Direct3D®、D3DX、DirectPlay®、DirectInput®、DirectMusic®、または DirectSound® のメソッドからの DirectX エラー メッセージと等価なテキストを取得する。たとえば、hr を 0x88768686 に設定した場合、DXGetErrorString8 は D3DERR_DEVICELOST を返す。

1 つのエラー コードが複数のテキスト文字列に対応している場合、DXGetErrorString8 は汎用的な文字列を返す。たとえば、メモリ不足を示す DirectX エラー コードは、DIERR_OUTOFMEMORY など複数あるが、これらはすべて同じ値に対応付けられる。hr をこれらのコードのいずれかに設定した場合、DXGetErrorString8 は E_OUTOFMEMORY を返す。

動作環境

Windows NT/2000 : Windows® 2000 が必要。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
バージョン : DirectX 8.0 が必要。
ヘッダー : Dxerr8.h で宣言。
インポート ライブラリ : Dxerr8.lib を使用。


DXTrace

メッセージ ボックスを表示し、DXGetErrorString8 にエラー コードを渡す。

HRESULT DXTrace(
  char *strFile,
  DWORD dwLine,
  HRESULT hr,
  TCHAR *strMsg,
  BOOL bPopMsgBox
);

パラメータ

strFile
[in] 現在のファイルの名前へのポインタ。このパラメータは、__FILE__ マクロを使って簡単に設定できる。
dwLine
[in] 行番号。このパラメータは、__LINE__ マクロを使って簡単に設定できる。
hr
[in] エラー コードが格納されている HRESULT。この値は、DXGetErrorString8 に渡されて、等価な名前に変換される。
strMsg
[in] ファイル名、行番号、HRESULT と共に表示されるオプションのメッセージへのポインタ。
bPopMsgBox
[in] メッセージ ボックスを表示するかどうかを指定する。bPopMsgBox を TRUE に設定し、hr を 0 以外の値に設定すると、メッセージ ボックスに、最初の 4 つのパラメータの値が表示される。bPopMsgBox を FALSE に設定すると、情報がデバッガに渡される。

戻り値

成功した場合は 0 を返し、失敗した場合は 0 以外の値を返す。

動作環境

Windows NT/2000 : Windows® 2000 が必要。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
バージョン : DirectX® 8.0 が必要。
ヘッダー : Dxerr8.h で宣言。
インポート ライブラリ : Dxerr8.lib を使用。


DirectX 8.0 エラー処理マクロ

次のマクロを使うと、DXTrace 関数を簡単に使用できる。

  • DXTRACE_MSG
  • DXTRACE_ERR
  • DXTRACE_ERR_NOMSGBOX


DXTRACE_MSG

文字列をデバッガに渡す。

HRESULT DXTRACE_MSG(
  char *str,
);

パラメータ

str
デバッガに渡される文字列へのポインタ。

戻り値

成功した場合は 0 を返し、失敗した場合は 0 以外の値を返す。

注意

文字列と共に、ファイル名および行番号を指定する。マクロの宣言は次のようになる。

DXTRACE_MSG(str) DXTrace( __FILE__, (DWORD)__LINE__, 0, str, FALSE )

動作環境

Windows NT/2000 : Windows® 2000 が必要。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
バージョン : DirectX® 8.0 が必要。
ヘッダー : Dxerr8.h で宣言。


DXTRACE_ERR

メッセージ ボックスにエラー情報を表示する。

HRESULT DXTRACE_ERR(
  char *str,
  HRESULT hr
);

パラメータ

str
メッセージ ボックスに表示される文字列へのポインタ。
hr
エラー コードを含む HRESULT。この値は、DXGetErrorString8 に渡されて、等価な名前に変換される。

戻り値

成功した場合は 0 を返し、失敗した場合は 0 以外の値を返す。

注意

文字列およびエラー名と共に、ファイル名および行番号を指定する。マクロの宣言は次のようになる。

DXTRACE_ERR(str,hr) DXTrace(__FILE__,(DWORD)__LINE__,hr,str,TRUE )

動作環境

Windows NT/2000 : Windows® 2000 が必要。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
バージョン : DirectX® 8.0 が必要。
ヘッダー : Dxerr8.h で宣言。


DXTRACE_ERR_NOMSGBOX

エラー情報をデバッガに渡す。

HRESULT DXTRACE_ERR_NOMSGBOX(
  char *str,
  HRESULT hr
);

パラメータ

str
デバッガに渡される文字列へのポインタ。
hr
エラー コードを含む HRESULT。この値は、DXGetErrorString8 に渡されて、等価な名前に変換される。

戻り値

成功した場合は 0 を返し、失敗した場合は 0 以外の値を返す。

注意

文字列およびエラー名と共に、ファイル名および行番号を指定する。マクロの宣言は次のようになる。

DXTRACE_ERR_NOMSGBOX(str,hr) DXTrace(__FILE__,(DWORD)__LINE__,hr,str, FALSE)

動作環境

Windows NT/2000 : Windows® 2000 が必要。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
バージョン : DirectX® 8.0 が必要。
ヘッダー : Dxerr8.h で宣言。


参考資料

Microsoft Windows® プログラミングに関する一般情報、および Microsoft® DirectX® を説明するときに使用したグラフィックスやマルチメディアの概念や用語については、以下の資料を参照すること。

  • Bradley Bargen および Peter Donnelly 著、『Inside DirectX』、Microsoft Press® 社より 1998 年に出版。
  • Durand R. Begault 著、『3-D Sound for Virtual Reality and Multimedia』、Academic Press 社より 1994 年に出版。
  • James Blinn 著、『Jim Blinn's Corner:A Trip Down the Graphics Pipeline』、Morgan Kaufmann 社より 1996 年に出版。
  • Charles Dodge および Thomas A. Jerse 著、『Computer Music:Synthesis, Composition, and Performance』、Schirmer Books 社より 1997 年に出版 (第 2 版)。
  • James D. Foley 著、『Computer Graphics:Principles and Practice』、Addison-Wesley 社より 1991 年に出版 (第 2 版)。
  • Donald Hearn および M. Pauline Baker 著、『Computer Graphics』、Prentice-Hall 社より 1986 年に出版。
  • Tim Kientzle 著、『A Programmer's Guide to Sound』、Addison-Wesley Developers Press 社より 1998 年に出版。
  • Peter J. Kovach 著、『Inside Direct3D』、Microsoft Press 社より 2000 年に出版。
  • Charles Petzold 著、『Programming Windows 98』、Microsoft Press 社より 1998 年に出版 (第 5 版)。
  • Nigel Thompson 著、『3D Graphics Programming for Windows 95』、Microsoft Press 社より 1996 年に出版。
  • Alan H. Watt および Mark Watt 著、『Advanced Animation and Rendering Techniques』、Addison-Wesley 社より 1992 年に出版。

COM に関する概念や用語の詳細については、以下の資料を参照すること。

  • Kraig Brockschmidt 著、『Inside OLE 2』、Microsoft Press 社より 1995 年に出版 (第 2 版)。
  • Dale E. Rogerson 著、『Inside COM』、Microsoft Press 社より 1997 年に出版。


DirectX Graphics

ここでは、Microsoft® DirectX® Graphics アプリケーション プログラミング インターフェイス (API) の使い方について説明する。

DirectX のほかのコンポーネントと同様に、DirectX Graphics は C、C++、および Microsoft Visual Basic® で使用できる。

DirectX Graphics のヘルプの構成については、「ロードマップ」を参照すること。


ロードマップ

Microsoft® DirectX® Graphics については、以下のトピックで説明する。

DirectX Graphics の新機能。DirectX 8.0 のこのコンポーネントの新機能。以前に Microsoft Direct3D® または Microsoft DirectDraw® を使用したことがある場合は、DirectX 7.0 から大幅に変更されているので、最初にこのトピックを読むことを推奨する。

DirectX Graphics の概要。DirectX Graphics およびアプリケーションで実行できる処理の概要と、いくつかの重要なポイントおよび必要な背景情報。

DirectX Graphics について。基本的な構造を詳しく説明する。ここでは、アプリケーションで頂点ライティングやテクスチャ マッピングを実装する方法は説明しないが、詳細を学習する際に API のしくみの理解に役立つはずである。

DirectX Graphics の使い方。API の使い方のガイドである。このトピックの目次を参考にして、特定の情報が必要になったときに対象となる箇所を参照できる。このトピックは、リファレンス トピックと組み合わせて使用すること。

DirectX Graphics の高度なトピック。アプリケーションで DirectX Graphics の能力を最大限に活用するアプリケーションを作成するための情報である。

プログラミングのヒントおよびツール。DirectX Graphics アプリケーションのコンパイル、デバッグ、および最適化に関するさまざまな情報を提供する。また、ここでは、DirectX 8.0 以前のドライバを使用する場合に発生する問題についても説明する。

DirectX Graphics C/C++ チュートリアル。基本的な機能を段階的に実装するチュートリアルである。実践的に DirectX Graphics を理解することができる。

DirectX Graphics C/C++ サンプル。必要なサンプル コードを見つけるための、SDK のサンプル アプリケーションについてのガイド。

Direct3D C/C++ リファレンス。Microsoft Direct3D® ヘッダー ファイルで宣言されているすべての API 要素について詳しく説明する。

Direct3DX C/C++ リファレンス。Direct3DX ユーティリティ ライブラリ ヘッダー ファイルで宣言されているすべての API 要素について詳しく説明する。

Direct3DX シェーダ アセンブラ リファレンス。Direct3DX 頂点シェーダおよびピクセル シェーダ アセンブラについての詳しいリファレンスである。

エフェクト ファイル形式。エフェクト ファイルのフォーマットについて説明する。一連のパラメータ宣言およびさまざまなテクニックに関する情報で構成される。

X ファイル C/C++ リファレンス。Dxfile.h で宣言されているすべての API 要素について詳しく説明する。

X ファイル フォーマット リファレンス。DirectX (.x) ファイル フォーマットについて詳しく説明する。


DirectX Graphics の新機能

Microsoft® DirectX® 8.0 では、旧リリースの DirectX のオブジェクトとインターフェイスを公開およびサポートすることにより、後方互換性を維持している。ただし、DirectX 8.0 の新しい Microsoft Direct3D® API インターフェイスの一部として、多くの新機能およびパフォーマンスの拡張が追加されている。

DirectDraw と Direct3D の完全な統合
アプリケーションの初期化が簡単になり、データの割り当てと管理のパフォーマンスが向上しており、メモリの使用量が減っている。また、グラフィックス API の統合によって、複数の頂点入力ストリームのパラレル化が可能になり、レンダリングの柔軟性が増している。
プログラム可能な頂点処理言語
カスタム シェーダを作成して、アニメーションのモーフィングやトゥイーニング、行列パレットのスキニング、ユーザー定義のライティング モデル、一般的な環境マッピング、手続きジオメトリ、および開発者が定義するその他のアルゴリズムなどを実現できる。
プログラム可能なピクセル処理言語
カスタム ハードウェア シェーダを作成し、テクスチャを結合する一般的な式、ピクセル単位のライティング (バンプ マッピング)、フォトリアルなスペキュラ エフェクトのためのピクセル単位の環境マッピング、および開発者が定義するその他のアルゴリズムなどを実現できる。
マルチサンプリング レンダリングのサポート
フルスクリーン アンチエイリアシングおよびモーション ブラーや被写界深度などのマルチサンプリング エフェクトが可能になる。
ポイント スプライト
火花、爆発、雨、雪などの粒子システムの高性能レンダリングが可能になる。
3D ボリューム テクスチャ
ピクセル単位のライティングの範囲減衰やボリューム大気エフェクトが可能になり、いっそう複雑なジオメトリに適用できる。
高次プリミティブのサポート
3D コンテンツの外観が向上し、主要な 3D オーサリング ツールからのコンテンツのマッピングが容易になる。
さらに高度なテクノロジ
(さまざまな Direct3D 技法を使って) スキニングされたメッシュを Direct3D にエクスポートするための 3D コンテンツ作成ツール プラグイン、マルチレゾリューションの詳細レベル (LOD) ジオメトリ、高次サーフェス データなど。
インデックス付き頂点ブレンディング
ジオメトリ ブレンディングのサポートが拡張され、頂点ブレンディングに使用する行列を、行列インデックスを使って参照できる。
Direct3DX ユーティリティ ライブラリの拡張
Direct3DX ユーティリティ ライブラリにさまざまな新機能が追加された。Direct3DX ユーティリティ ライブラリは、Direct3D 上のヘルパー層で、3D グラフィックスの開発者が処理しなければならない一般的なタスクを容易にする。スキニング ライブラリ、メッシュの処理のサポート、頂点シェーダやピクセル シェーダをアセンブルするための関数などが含まれる。Microsoft DirectX® 5.0 で最初に導入された D3D_OVERLOADS によって提供されていた機能は、Direct3DX ユーティリティ ライブラリに移動されたことに注意すること。


DirectX Graphics の概要

ここでは、Microsoft® DirectX® Graphics API について紹介し、技術とサービスに関する高度な概要を記述する。

  • DirectX Graphics の機能
  • DirectX Graphics の基礎知識


DirectX Graphics の機能

Microsoft® Direct3D® は、Microsoft Windows® 搭載のコンピュータ上で世界に通用するゲームやインタラクティブ 3D グラフィックスを使えるようにすることを目的に設計されている。3D ビデオディスプレイ ハードウェアへのデバイスに依存したアクセスを、デバイスに依存しない方法で行うことができる描画インターフェイスである。

Direct3D は、ゲームやその他の高性能マルチメディア アプリケーションを Windows オペレーティング システムに移植する必要がある開発者には理想的な下位レベル 3D API である。Direct3D は、アクセラレータ ハードウェアと下位レベルでやり取りするアプリケーションのための方法で、デバイスには依存しない。

Direct3D は、Windows グラフィックス デバイス インターフェイス (GDI) との互換性を維持しながらディスプレイ デバイスへの直接アクセスを提供するソフトウェア デバイスであり、ゲームや 3D グラフィックス パッケージなどの Windows サブシステム ソフトウェアから、特定のディスプレイ デバイスの機能にデバイスに依存しないでアクセスする方法を提供する。

Direct3D は、Windows 95 やそれ以降のバージョン、および Windows 2000 が動作するコンピュータ上に、最上級のゲーム グラフィックスを提供する。

次に示すのは、Direct3D の最新機能である。

  • 切り替え可能な深度バッファリング (Z バッファまたは W バッファを使用)。
  • フラットおよびグーロー シェーディング。
  • 複数の光源とライト タイプ。
  • ミップマッピングなど、マテリアルおよびテクスチャの完全サポート。
  • 強力なソフトウェア エミュレーション ドライバ。
  • トランスフォームとクリッピング。
  • ハードウェア非依存性。
  • Windows 95、Windows 98、Windows ME、および Windows 2000 の完全サポート。
  • Intel の MMX アーキテクチャ、Intel の Streaming Single-Instruction, Multiple-Data (SIMD) Extensions (SSE)®、および AMD® の 3DNow® アーキテクチャ。
  • ハードウェア アブストラクション レイヤ (HAL) のサポート。このサポートによって提供される、ディスプレイ ハードウェアに直接作用する一貫性のあるインターフェイスによって、最大のパフォーマンスを得ることができる。
  • フルスクリーン アプリケーションでの複数のバック バッファによるページ フリッピングのサポート。詳細については、「ページ フリッピングとバック バッファリング」を参照すること。
  • ウィンドウまたはフルスクリーン アプリケーションでのクリッピングのサポート。
  • 3D での Z バッファのサポート。
  • イメージ伸縮ハードウェアへのアクセス。
  • 標準および改良型ディスプレイ デバイス メモリ領域への同時アクセス。
  • その他の機能として、排他的ハードウェア アクセス、および解像度の切り替えなどがある。

これらの機能を組み合わせれば、標準的な Windows GDI ベースのアプリケーションや MS-DOS アプリケーションについて、簡単にその性能を向上させることができる。

Direct3D のワールド管理は、頂点、ポリゴン、およびこれらを制御するコマンドに基づいて行われる。これによって、トランスフォーム、ライティング、ラスタ化 3D グラフィックス パイプラインに直接アクセスできる。ハードウェア アクセラレーションを利用してレンダリングできない場合、Direct3D は強力なソフトウェア エミュレーション機能を提供する。

Direct3D では、シンプルで直接的なメソッドを使用して 3D シーンを設定およびレンダリングできる。レンダリング メソッドの主要セットは DrawPrimitive メソッドと呼ばれる。これらのメソッドにより、アプリケーションではメソッドの呼び出しを 1 回行うだけで、シーンの 1 つまたは複数のオブジェクトをレンダリングできる。これらのメソッドの詳細については、「プリミティブのレンダリング」を参照すること。

Direct3D では、3D ハードウェアへの接続の際に発生するオーバーヘッドが低い。ただし、この接続を実現するためにはかなりの作業を要する。トランスフォームやライティングを実行するには明示的な呼び出しを行わなければならず、必要な行列はすべて提供し、存在するハードウェアの種類やその機能を調べる必要もある。


DirectX Graphics の基礎知識

ここでは、Microsoft® Direct3D® によるグラフィックス プログラミングの概要を説明する。ここで説明する個々の概念は、技術的ではない概要で始まり、DirectDraw がそれをどのようにサポートするかについて多少の具体的説明を加えながら説明する。

ここでの概要を読むにあたっては、グラフィックスの専門家である必要はない。実際、グラフィックスについて詳しい場合は、ここでの説明を読まずに、より詳細なトピックである「DirectX Graphics の使い方」に進んでかまわない。以下のトピックを読み終えれば、基本的な DirectDraw グラフィックス プログラミングの概念を十分に理解することができる。

説明するトピックは、次のとおりである

  • 3D 座標系とジオメトリ
  • シェーディングの技法
  • 行列とトランスフォーム
  • ベクトル、頂点、およびクオータニオン
  • サーフェスのコピー
  • ページ フリッピングとバック バッファリング
  • 矩形


3D 座標系とジオメトリ

Microsoft® Direct3D® アプリケーションをプログラミングするには、3D ジオメトリ原理について理解している必要がある。ここでは、3D シーンの作成において最も重要なジオメトリ原理について説明する。説明するトピックは、次のとおりである。

  • 3D 座標系
  • 3D プリミティブ
  • 三角形ラスタ化ルール

これらのトピックを参照すれば、Direct3D アプリケーションで用いる基本概念について十分に理解できる。これらのトピックの詳細については、「参考資料」を参照すること。


3D 座標系

一般に、3D グラフィックス アプリケーションではデカルト座標系の左手座標系と右手座標系のどちらかを使用する。どちらの座標系でも、x 軸の正方向は右側であり、y 軸の正方向は上方である。z 軸の正方向は、x 軸 の正方向に左手または右手の指を向け、それを y 軸の正の方向に回転した方向になる。親指の方向、手前または奥が、この座標系での z 軸の正方向である。次の図は、これら 2 つの座標システムを示している。

Microsoft® Direct3D® は左手座標系を使用する。右手座標系に基づくアプリケーションを移植する場合は、Direct3D に渡すデータに 2 つの変更を加える必要がある。

  • 三角形の頂点の順序を反転し、システムが前から時計回りにたどれるようにする。つまり、頂点が v0、v1、v2 であるとすると、Direct3D に v0、v2、v1 として渡す。
  • ビュー行列を使用して、ワールド空間を z 軸方向に -1 だけスケーリングする。そのためには、ビュー行列に使用する D3DMATRIX 構造体の _31、_32、_33、および _34 の各メンバの符号を反転する

右手系に相当する座標系を取得するには、D3DXMatrixPerspectiveRH 関数および D3DXMatrixOrthoRH 関数を使用して、射影トランスフォームを定義する。ただし、対応する D3DXMatrixLookAtRH 関数を使用する場合は、背面カリングの順序を逆にし、その順序でキューブ マップをレイ アウトするよう注意すること。

左手座標系と右手座標系は最もよく使用される座標系システムだが、3D ソフトウェアでは、これらの座標系システム以外にもさまざまな座標系が使用されることがある。たとえば、3D モデリング アプリケーションでは、y 軸がビューアの手前または奥を指し、z 軸が上方を指している座標系が使用されることも珍しくない。この場合、右手座標系は、どの軸 (x、y、または z) の正方向もビューアに近づく方向として定義される。左手座標系は、どの軸 (x、y、または z) の正方向もビューアから離れる方向として定義される。z 軸が上方を指している左手座標系を使用したモデリング アプリケーションを移植する場合は、既に説明した手順に加え、頂点データをすべて回転する必要がある。

3D 座標系で定義されたオブジェクトにおいて重要な操作は、平行移動、回転、およびスケーリングである。これらの基本的なトランスフォームを組み合わせてトランスフォーム行列を作成できる。詳細については、「3D トランスフォーム」を参照すること。

これらの操作を組み合わせるとき、その結果はその操作の順序に依存すること、つまり行列を乗算する順序が重要であることに注意する。


3D プリミティブ

3D プリミティブとは、単一の 3D 構成要素を形成する頂点の集合である。最も単純なプリミティブは、3D 座標系にあるポイントの集合である。これをポイント リストと呼ぶ。

多くの場合、3D プリミティブはポリゴンである。ポリゴンとは、少なくとも 3 つの頂点が結ばれた閉じた 3D 図形である。最も単純なポリゴンは三角形である。三角形の 3 つの頂点はすべて同一平面上にあるため、Microsoft® Direct3D® では三角形を使用してほとんどのポリゴンを形成する。同じ平面上にない頂点のレンダリングは非効率的である。三角形を組み合わせて大きく複雑なポリゴンやメッシュを形成できる。

次の図は立方体を示している。2 つの三角形で立方体の各面が形成されている。三角形の集合全体で 1 つのキューブ プリミティブが形成されている。プリミティブのサーフェスにテクスチャとマテリアルを適用して、プリミティブを単一のソリッド フォームのように表示できる。詳細については、「マテリアル」および「テクスチャ」を参照すること。

また、三角形を使用して、サーフェスが滑らかなカーブのように見えるプリミティブを作成できる。次の図は、三角形で球をシミュレートする方法を示している。マテリアルを適用すると、球はレンダリングしたときに曲面に見える。これは、特にグーロー シェーディングを使用する場合に当てはまる。詳細については、「グーロー シェーディング」を参照すること。


三角形ラスタ化ルール

頂点に指定された点はスクリーン上のピクセルと正確に一致しないことが多い。この場合、Microsoft® Direct3D® は三角形ラスタ化ルールを適用して、どのピクセルが与えられた三角形に当てはまるかを決める。

Direct3D では、ジオメトリを塗りつぶすのに、左上フィリング変換を使用する。この変換は、GDI および OpenGL の矩形に使用する変換と同じである。Direct3D では、ピクセルの中心が重要なポイントである。ピクセルの中心が三角形の内部にある場合、そのピクセルはその三角形の一部である。ピクセルの中心は整数座標にある。

ここで説明する、Direct3D の三角形ラスタ化ルールが、利用可能なすべてのハードウェアに当てはまるとは限らない。現在のハードウェアを調べてみると、このルールの実装において若干の違いが見つかることもある。

次の図は、左上の角が (0, 0) で右下の角が (5, 5) の矩形を示している。この矩形は、予想されるとおり 25 ピクセルを占めている。矩形の幅は、右から左を減算した値で定義される。高さは、下から上を減算した値で定義される。

左上フィリング変換では、上は水平スパンの垂直位置座標を表し、左はあるスパン内のピクセルの水平位置座標を表す。エッジは、水平でない限り上のエッジではありえない。一般に、ほとんどの三角形では左エッジと右エッジがあるだけである。

左上フィリング変換によって、三角形がピクセルの中心を通過するときの Direct3D の処理が決まる。次の図は、頂点が (0, 0)、(5, 0)、(5, 5) の三角形と、頂点が (0, 5)、(0, 0)、(5, 5) の三角形を示している。この場合、前者の三角形は 15 ピクセル (黒で表示) を占めるが、後者の三角形は 10 ピクセル (グレーで表示) しか占めない。共有しているエッジが前者の三角形の左のエッジだからである。

たとえば、左上の角が (0.5, 0.5) で右下の角が (2.5, 4.5) の矩形を定義する場合、この矩形の中心ポイントは (1.5, 2.5) になる。Direct3D ラスタライザでこの矩形をラスタ化すると、各ピクセルの中心は明らかに 4 つの三角形のそれぞれの内部に存在し、左上フィリング変換は不要になる。次の図にこれを示す。矩形内部にあるピクセルには、Direct3D がそのピクセルを入れる三角形に対応したラベルが付けられている。

上の例の矩形を左上の角が (1.0, 1.0)、右下の角が (3.0, 5.0)、中心ポイントが (2.0, 3.0) になるように移動すると、Direct3D は左上フィリング変換を適用する。次の図に示すように、この矩形内部のピクセルのほとんどは、2 つ以上の三角形の間の境界をまたがる。

どちらの矩形でも、同じピクセルが影響を受ける。


シェーディングの技法

ここでは、3D ポリゴンのシェーディングを制御するために Microsoft® Direct3D® で使用する技法について説明する。

  • シェーディング モード
  • シェーディング モードの比較
  • シェーディング モードの設定
  • 面法線ベクトルと頂点法線ベクトル
  • 三角形補間要素


シェーディング モード

ポリゴンのレンダリングに使用するシェーディング モードは、ポリゴンの表示に大きな影響を与える。シェーディング モードによって、ポリゴンの面のポイントの色とライティングの強度が決まる。Microsoft® Direct3D® は、次の 2 つのシェーディング モードをサポートしている。

  • フラット シェーディング
  • グーロー シェーディング


フラット シェーディング

フラット シェーディング モードでは、Direct3D レンダリング パイプラインは、ポリゴンの最初の頂点におけるマテリアルの色をポリゴン全体の色として使用して、ポリゴンをレンダリングする。フラット シェーディングでレンダリングした 3D オブジェクトでは、同一平面上にないポリゴンの間に鋭いエッジが現れる。

次の図は、フラット シェーディングでレンダリングしたティーポットを示している。各ポリゴンの輪郭がはっきりと見える。フラット シェーディングは、計算負荷の最も少ないシェーディングである。


グーロー シェーディング

Microsoft® Direct3D® では、ポリゴンをグーロー シェーディングでレンダリングするとき、頂点の法線パラメータおよびライティング パラメータを使用して各頂点の色を計算する。次に、ポリゴンの面にわたって色を補間する。補間は線形で行われる。たとえば、頂点 1 の色の赤成分が 0.8 で頂点 2 の赤成分が 0.4 の場合、Direct3D のライティング モジュールは、グーロー シェーディング モードおよび RGB カラー モデルを使用して、2 つの頂点の間の線の中間点にあたるピクセルに 0.6 の赤成分を割り当てる。

次の図はグーロー シェーディングを示している。このティーポットは、多数の平坦な三角形のポリゴンで構成されている。しかし、グーロー シェーディングを使用すると、このオブジェクトのサーフェスは滑らかな曲面のようになる。

グーロー シェーディング モードで、鋭いエッジを持つオブジェクトを表示することもできる。

詳細については、「面法線ベクトルと頂点法線ベクトル」を参照すること。


シェーディング モードの比較

フラット シェーディング モードの場合、次のピラミッドは隣接する面の間に鋭いエッジがあるように表示される。ただし、グーロー シェーディングの場合、シェーディング値はエッジ間で補間され、最終的な外観は湾曲サーフェスになる。

グーロー シェーディング モードでは、フラット シェーディング モードの場合よりも、平坦なサーフェスでもよりリアル見える。フラット シェーディング モードの場合、サーフェスの色は一様であるが、グーロー シェーディング モードでは面全体でライティングを適切に弱めることができる。この効果は、近くにポイント光源がある場合に特にはっきりする。

グーロー シェーディングは、フラット シェーディングで現れるポリゴン間の鋭いエッジを滑らかにする。ただし、グーロー シェーディングでは、マッハ バンドが生じる。マッハ バンドとは、隣接するポリゴンで色や光がスムーズにブレンドされていない帯を指す。オブジェクトのポリゴンの数を増やしたり、スクリーン解像度を高めたり、アプリケーションの色深度を上げることで、アプリケーション側でマッハ バンドを減らすことができる。

グーロー シェーディングでは、小さな部分でミスが生じることがある。次の図に例を示す。ここでは、スポット ライトが 1 枚のポリゴンの表面にだけ当てられている。

この場合、グーロー シェーディングが頂点間を補間することからスポット ライトがすべて失われ、まるでスポット ライトが存在しないかのように面がレンダリングされている。


シェーディング モードの設定

Microsoft® Direct3D® では、一度に 1 つのシェーディング モードしか選択できない。デフォルトでは、グーロー シェーディングが選択されている。C++ では、IDirect3DDevice8::SetRenderState メソッドを呼び出してシェーディング モードを変更できる。State パラメータを D3DRS_SHADEMODE に設定する。State パラメータには D3DSHADEMODE 列挙のメンバを設定する必要がある。次のサンプル コードは、Direct3D アプリケーションの現在のシェーディング モードを、フラット シェーディング モードまたはグーロー シェーディング モードに設定する方法を示している。

// フラット シェーディングに設定する。
// このコードでは、pDev が IDirect3DDevice8 インターフェイスへの
// 有効なポインタであるとする。
hr = pDev->SetRenderState(D3DRS_SHADEMODE, D3DSHADE_FLAT);
if(FAILED(hr))
{
    // エラー処理コード。
}

// グーロー シェーディングに設定する。これが Direct3D のデフォルト値である。
hr = pDev->SetRenderState(D3DRS_SHADEMODE,
                            D3DSHADE_GOURAUD);
if(FAILED(hr))
{
    // エラー処理コード。
}


面法線ベクトルと頂点法線ベクトル

メッシュの各面には、垂直の法線ベクトルがある。法線ベクトルの方向は、頂点が定義されている順序と、座標系が左手座標系か右手座標系かによって決まる。面の法線ベクトルは面の前面から離れる方向に向く。Microsoft®Direct3D® では、面の前面のみ表示される。前面とは、各頂点が時計回りの順に定義された面である。

前面以外の面は背面である。Direct3D では、背面が常にレンダリングされるわけではない。これを背面カリングと言う。カリング モードを変更すれば背面をレンダリングできる。詳細については、「カリング ステート」を参照すること。

Direct3D アプリケーションでは面法線を指定する必要はない。必要なときはシステムで自動的に計算される。システムでは、フラット シェーディング モードで面法線を使用する。グーロー シェーディング モードでは頂点法線を使用する。また、Direct3D はライティング エフェクトとテクスチャ エフェクトの制御にも頂点法線を使用する。

グーロー シェーディングをポリゴンに適用するとき、Direct3D では頂点法線を使用して光源とサーフェス間の角度を計算する。Direct3D では、頂点の色と強度の値を計算し、プリミティブのサーフェス全体のすべてのポイントに対してこの値を補間する。Direct3D では、この角度を使用してライティングの強度の値を計算する。角度が大きいほど、サーフェスを照らす光が弱くなる。

平坦なオブジェクトを作成する場合、次の図に示すように、頂点法線をサーフェスに対して垂直に設定する。2 つの三角形で構成される平坦なサーフェスが定義されている。

しかし、通常はオブジェクトが三角形ストリップで構成され、それらの三角形が同一平面上にないことが多い。ストリップのすべての三角形全体に滑らかなシェーディングを施すには、まず頂点に関係付けられている各ポリゴンのサーフェスについて、面法線ベクトルを計算するのが簡単である。頂点法線は、その周りの各サーフェスの法線からの角度が等しくなるように設定できる。ただし、この方法はプリミティブが複雑な場合には効率的でないことがある。

この方法について次の図で説明する。この図では、S1 と S2 の 2 つのサーフェスがあり、上から見るとエッジが重なっている。S1 と S2 の法線ベクトルは青色で示す。頂点法線ベクトルは赤色で示す。S1 の面法線と頂点法線ベクトルのなす角度は、S2 の面法線と頂点法線のなす角度と同じである。これら 2 つのサーフェスにライトを当て、グーロー シェーディングで陰影を付けると、サーフェス間のエッジの陰影が滑らかになって丸みを帯びる。

頂点法線が、関係付けられているサーフェスのうち 1 つの方へ傾いている場合、光源と面の角度に応じてサーフェス上の点に対する光の強度が増加または減少する。この例を次の図で示す。この図でも、サーフェスのエッジは重なっている。頂点法線は S1 の方に傾いているので、S1 と光源の角度は、頂点法線と 2 つの面法線の角度が等しい場合よりも小さくなる。

グーロー シェーディングを使用して、鋭いエッジのあるオブジェクトを 3D シーンに表示できる。このためには、次の図に示すように、鋭いエッジが必要な、面の交点の位置座標 2 つの頂点でそれぞれの面と同じ法線ベクトルが必要である。

DrawPrimitive メソッドを使用してシーンをレンダリングする場合、エッジが鋭いオブジェクトは、三角形ストリップではなく三角形リストとして定義する。オブジェクトを三角形ストリップとして定義すると、Direct3D ではそのオブジェクトを複数の三角形の面で構成された単一のポリゴンとして扱う。グーロー シェーディングは、ポリゴンの面全体および隣接する面との間の両方に適用される。その結果、オブジェクトの面の境が滑らかにシェーディングされる。三角形リストは、一連の独立した三角形の面から構成されるポリゴンなので、Direct3D ではポリゴンの各面にグーロー シェーディングが適用される。ただし、面と面の境にはグーロー シェーディングは適用されない。三角形リストの複数の三角形が隣接している場合、その三角形の間には鋭いエッジが表示される。

また、エッジが鋭いオブジェクトをレンダリングするとき、フラット シェーディングに変更する方法もある。これはコンピュータには最も効率的であるが、グーロー シェーディングを適用したオブジェクトよりもリアリティに欠けるオブジェクトがシーンに表示される可能性がある。


三角形補間要素

システムでは、面をレンダリングするとき三角形全体で三角形の頂点の特性を補間する。三角形補間要素は次のとおりである。

  • 色
  • スペキュラ
  • アルファ

次の表に示すように、これらの三角形補間要素はすべて、現在のシェーディング モードによって変わる。

シェーディング モード | 説明
フラット | 補間は行われない。その代わり、三角形の最初の頂点の色が面全体に適用される。
グーロー | 線形補間が 3 つの頂点すべての間で実行される。

色補間要素とスペキュラ補間要素の処理はカラー モデルによって異なる。RGB カラー モデルの場合、システムでは赤色、緑色、および青色成分を使用して補間を行う。モノクロ モデル、つまりランプ モデルの場合、システムでは頂点の色の青色成分のみ使用する。

色のアルファ成分は、別の補間要素として扱われる。理由は、テクスチャ ブレンディングと点描の 2 つの異なる方法で、デバイス ドライバが透明化を実行するためである。

D3DCAPS8 構造体の ShadeCaps メンバを使用して、現在のドライバがサポートしている補間の種類を決定する。


行列とトランスフォーム

Microsoft® Direct3D® の行列を使用して、ワールド トランスフォーム、ビュー トランスフォーム、および射影トランスフォームを定義する。3D グラフィックスのプログラミング未経験者は、ここの内容を学習してプログラムを始めるために重要な概念を理解しておく必要がある。3D プログラミングの経験者は、ここの内容は省略したり、以下のトピックについて簡単に目を通すだけでよい。

  • 行列
  • 3D トランスフォーム


行列

Microsoft® Direct3D® では、行列は 4 × 4 同次行列で表され、D3DMATRIX 構造体で定義される。

D3DMATRIX 構造体 (D3DXMATRIX) の Direct3DX ユーティリティ ライブラリには、かっこ ("()") 演算子が実装されている。この演算子は、C++ プログラマに対して行列中の値にアクセスする便利な方法を提供する。名前で構造体メンバを参照する必要はなく、行および列番号でメンバを参照でき、必要に応じてこの番号をインデックスとして使用できる。このインデックスは 0 から始まり、たとえば、3 行 2 列の要素は M(2, 1) になる。

ここでの説明は、ユーザーが Direct3D で作業を行うために十分な行列についての基本的な知識を習得していることを前提としている。詳細については、「3D トランスフォーム」を参照すること。


3D トランスフォーム

Microsoft®Direct3D® では、行列を使用して 3D トランスフォームを行う。ここでは、行列が 3D トランスフォームを作成する方法、トランスフォームによく使用される行列、および行列を組み合わせて複数のトランスフォームを行う単一の行列を生成する方法について説明する。説明するトピックは、次のとおりである。

  • 3D トランスフォームについて
  • 平行移動
  • 回転
  • スケーリング
  • 行列連結

Direct3D でのトランスフォームの詳細については、「Direct3D レンダリング パイプライン」を参照すること。


3D トランスフォームについて

3D グラフィックスを処理するアプリケーションでは、ジオメトリ トランスフォームを使用して次のことができる。

  • オブジェクトの位置座標をほかのオブジェクトとの相対位置座標で表す。
  • オブジェクトを回転、およびサイズを変更する。
  • 位置座標視点、ビュー方向、およびパースペクティブを変更する。

4 × 4 行列を使用すると、任意のポイントを別のポイントにトランスフォームできる。次の例では、行列を使用してポイント (x, y, z) を再度トランスフォームし、新しいポイント (x', y', z') を生成する。

(x, y, z) に対する次の操作と行列を実行してポイント (x', y', z') を生成する。

最も一般的なトランスフォームは、平行移動、回転、およびスケーリングである。これらの効果を生成する行列を組み合わせて単一の行列を作成し、いくつかのトランスフォームを同時に計算できる。たとえば、一連の点を平行移動して回転させる単一の行列を作成できる。詳細については、「行列連結」を参照すること。

行列は、行と列の順序で記述する。頂点を各軸に対して均一にスケーリングする (一様なスケーリングと呼ばれる) 行列は、数学的には次のように表記される。

C++ の場合、Microsoft® Direct3D® では、D3DMATRIX 構造体を使用して行列を 2 次元配列として宣言する。次の例は、一様なスケーリングを行う行列として機能するように D3DMATRIX 構造体を初期化する方法を示している。

// この例では、s は float 型の変数である

D3DMATRIX scale = {
    s,               0.0f,            0.0f,            0.0f,
    0.0f,            s,               0.0f,            0.0f,
    0.0f,            0.0f,            s,               0.0f,
    0.0f,            0.0f,            0.0f,            1.0f
};


平行移動

次のトランスフォームは、ポイント (x, y, z) を新しいポイント (x', y', z') に平行移動する。

C++ では、独自の平行移動行列を作成できる。次の例は、頂点を平行移動するための行列を作成する関数のソース コードを示している。

D3DXMATRIX Translate(const float dx, const float dy, const float dz) {
    D3DXMATRIX ret;

    D3DXMatrixIdentity(&ret);  // Direct3DX によって実装される。
    ret(3, 0) = dx;
    ret(3, 1) = dy;
    ret(3, 2) = dz;
    return ret;
}    // 平行移動終了。

簡便化するため、Direct3DX ユーティリティ ライブラリによって D3DXMatrixTranslation 関数が提供される。


回転

ここでは、左手座標系のトランスフォームについて説明する。したがって、これまでのトランスフォーム行列とは異なる場合もある。詳細については、「3D 座標系」を参照すること。

次のトランスフォームは、ポイント (x, y, z) を x 軸 を中心に回転して新しいポイント (x', y', z') を生成する。

次のトランスフォームは、ポイントを y 軸を中心に回転する。

次のトランスフォームは、ポイントを z 軸を中心に回転する。

これらの行列の例では、ギリシャ文字シータ (θ) は、回転角度をラジアン単位で表している。角度は、回転軸を中心にして原点方向を向いた時計回りで測定したものである。

C++ アプリケーションでは、Direct3DX ユーティリティ ライブラリによって提供される D3DXMatrixRotationX 関数、D3DXMatrixRotationY 関数、および D3DXMatrixRotationZ 関数を使って回転行列を作成する。次のコードは、D3DXMatrixRotationX 関数のコードである。

D3DXMATRIX* WINAPI D3DXMatrixRotationX
    ( D3DXMATRIX *pOut, float angle )
{
#if DBG
    if(!pOut)
        return NULL;
#endif

    float sin, cos;
    sincosf(angle, &sin, &cos);  // 角度の sin と cos を決定する。

    pOut->_11 = 1.0f; pOut->_12 =  0.0f;   pOut->_13 = 0.0f; pOut->_14 = 0.0f;
    pOut->_21 = 0.0f; pOut->_22 =  cos;    pOut->_23 = sin;  pOut->_24 = 0.0f;
    pOut->_31 = 0.0f; pOut->_32 = -sin;    pOut->_33 = cos;  pOut->_34 = 0.0f;
    pOut->_41 = 0.0f; pOut->_42 =  0.0f;   pOut->_43 = 0.0f; pOut->_44 = 1.0f;

    return pOut;
}


スケーリング

次のトランスフォームは、x、y、および z 方向の任意の値でポイント (x, y, z) を新しいポイント (x', y', z') にスケーリングする。


行列連結

行列を使用する利点の 1 つは、複数の行列を乗算してそれらのエフェクトを組み合わせることができるということである。つまり、モデルを回転し、次に別の位置座標に平行移動する場合、2 つの行列を適用する必要はない。その代わり、回転行列と平行移動行列を乗算して、すべてのエフェクトを持つ合成行列を生成する。この処理は行列連結と呼ばれ、次の公式で記述できる。

この公式では、C は作成する合成行列で、M1 ～ Mn は行列 C に含まれる個々のトランスフォームである。ほとんどの場合、2 つまたは 3 つの行列を連結するが、数に制限はない。

D3DXMatrixMultiply 関数を使って、行列の乗算を実行する。

行列の乗算が実行される順序は重要である。上の公式は、行列連結の "左から右" 規則を反映している。つまり、合成行列を作成するために使用する行列の視覚エフェクトは、左から右の順で現われる。一般的なワールド トランスフォーム行列の例を次に示す。お決まりの "空飛ぶ円盤" 用のワールド トランスフォーム行列を作成すると仮定する。この空飛ぶ円盤を中心 (モデル空間 の y 軸) を軸に回転させ、シーン内の別の場所に平行移動したいとする。この効果を実現するには、次の式のように、まず回転行列を作成し、次にこの行列を平行移動行列で乗じる。

この公式では、Ry は y 軸を中心に回転する行列で、Tw はワールド座標の任意の位置座標への平行移動である。

これらの行列を乗算する順序は重要である。2 つのスカラー値を乗算する場合とは異なり、行列の乗算は可換的ではない。平行移動行列と回転行列を逆の順序で乗算すると、空飛ぶ円盤がワールド空間位置座標に移動してから、ワールド座標の原点を中心に回転するというエフェクトが生じてしまう。

どのような行列を作成する場合でも、期待どおりのエフェクトを実現するためには "左から右" 規則を忘れてはならない。


ベクトル、頂点、およびクオータニオン

Microsoft® Direct3D® では、頂点によって位置と向きが表される。プリミティブの各頂点は、位置を示すベクトル、色、テクスチャ座標、および向きを示す法線ベクトルによって記述される。

クオータニオンは、3 コンポーネント ベクトルを定義する [x, y, z] 値に第 4 の要素を追加する。クオータニオンは、3D 回転で一般的に使用される行列メソッドに代わるものである。クオータニオンは、3D 空間内の軸と、その軸を中心とする回転を表す。たとえば、1 つのクオータニオンで軸 (1,1,2) と 1 ラジアンの回転を表すことができる。クオータニオンは重要な情報も伝えるが、その真価は、クオータニオン上で実行できる 2 つの処理、合成と補間で発揮される。

クオータニオンの合成は、結合処理に類似する。2 つのクオータニオンの合成は、以下のように説明することができる。

1 つのジオメトリに対する 2 つのクオータニオンの合成とは、"ジオメトリを axis2 を中心に rotation2 だけ回転した後に、axis1 を中心に rotation1 だけ回転する" ことである。この場合 Q は、ジオメトリに q2 を適用した後に q1 を適用した結果生成された単一軸を中心とする回転を表す。

クオータニオンの補間を使用すれば、アプリケーションはある軸と向きから別の軸と方向までの滑らかで適切なパスを計算することができる。したがって、q1 から q2 の間を補間すれば、ある向きから別の向きへ簡単にアニメーションすることができる。

合成と補間を組み合わせると、ジオメトリの一見複雑そうな操作を簡単に実行できる。たとえば、一定の向きに回転させたいジオメトリがあるとする。axis2 を中心に r2° だけ回転した後に、axis1 を中心に r1° だけ回転することはわかっているが、最終的なクオータニオンはわからないとする。この場合、合成によってジオメトリ上の 2 つの回転を結合すれば、その結果として、単一のクオータニオンが生成される。そして、元のクオータニオンと合成されたクオータニオンの間を補間し、クオータニオンからクオータニオンへ滑らかなトランジションを実現できる。

Direct3DX ユーティリティ ライブラリには、クオータニオンの操作に役立つ関数がある。たとえば、D3DXQuaternionRotationAxis 関数は、回転の軸を定義するベクトルに回転値を加算し、その結果を D3DXQUATERNION 構造体によって定義されるクオータニオンに返す。さらに、D3DXQuaternionMultiply 関数はクオータニオンを合成し、D3DXQuaternionSlerp は 2 つのクオータニオン間で球状上で線形補間を実行する。

Direct3D アプリケーションでは、以下の関数を使ってクオータニオンの操作を単純化することができる。

  • D3DXQuaternionBaryCentric
  • D3DXQuaternionConjugate
  • D3DXQuaternionDot
  • D3DXQuaternionExp
  • D3DXQuaternionIdentity
  • D3DXQuaternionInverse
  • D3DXQuaternionIsIdentity
  • D3DXQuaternionLength
  • D3DXQuaternionLengthSq
  • D3DXQuaternionLn
  • D3DXQuaternionMultiply
  • D3DXQuaternionNormalize
  • D3DXQuaternionRotationAxis
  • D3DXQuaternionRotationMatrix
  • D3DXQuaternionRotationYawPitchRoll
  • D3DXQuaternionSlerp
  • D3DXQuaternionSquad
  • D3DXQuaternionToAxisAngle

Direct3D アプリケーションでは、以下の関数を使って 3 コンポーネント ベクトルの操作を単純化することができる。

  • D3DXVec3Add
  • D3DXVec3BaryCentric
  • D3DXVec3CatmullRom
  • D3DXVec3Cross
  • D3DXVec3Dot
  • D3DXVec3Hermite
  • D3DXVec3Length
  • D3DXVec3LengthSq
  • D3DXVec3Lerp
  • D3DXVec3Maximize
  • D3DXVec3Minimize
  • D3DXVec3Normalize
  • D3DXVec3Project
  • D3DXVec3Scale
  • D3DXVec3Subtract
  • D3DXVec3Transform
  • D3DXVec3TransformCoord
  • D3DXVec3TransformNormal
  • D3DXVec3Unproject

その他、Direct3DX ユーティリティ ライブラリの算術関数には、2 コンポーネント ベクトルや 4 コンポーネント ベクトルによる処理を単純化するための関数が、多数用意されている。


サーフェスのコピー

このブリット (blit) とは、ビット ブリット (bit block transfer) のことであり、データのブロックをメモリ内のある場所から別の場所に転送するプロセスを指す。ブリットによるデバイス ドライバ インターフェイス (DDI) は、ピクセル数の大きな矩形をフレーム単位で移動する際の主要メカニズム、つまりコピー主体の IDirect3DDevice8::Present メソッドの背後にあるメカニズムとして、Microsoft® DirectX® 8.0 でも引き続き使用されている。ブリット処理におけるアートワークの移動は、IDirect3DDevice8::UpdateTexture メソッドによって実行される。DirectX 8.0 では、アートワークはピクセルの矩形サブセットをコピーする IDirect3DDevice8::CopyRects メソッドを使ってコピーすることもできる。

注 DirectX 8.0 で提供される D3DX 関数によって、アートワークをファイルからロードしたり、色の変更を適用したり、アートワークのサイズを変更したりすることができる。使用できる関数の詳細については、「テクスチャ関数」を参照すること。


ページ フリッピングとバック バッファリング

ページ フリッピングは、マルチメディアやアニメーション、ゲームなどのソフトウェアで主に使用される。ソフトウェア ページ フリッピングは、紙の束を使ってアニメーションを作成する方法に類似する。ページごとに形を少しずつ変えて描画し、紙をすばやくパタパタめくってアニメーションのように見せる方法である。

ソフトウェアでのページ フリッピングは、このプロセスとよく似ている。Microsoft® Direct3D® では、デバイスのプロパティであるスワップ チェーンを介して、ページ フリッピング機能を実装する。最初に、アニメ作家の紙を次のページにフリップするように、スクリーンにフリップする一連の Direct3D バッファをセット アップする。最初のバッファはカラー フロント バッファと呼ばれ、背後のバッファはバックバッファと呼ばれる。アプリケーションはバック バッファに書き込み、次にカラー フロント バッファをフリップしてバック バッファをスクリーンに表示する。システムがイメージを表示している間、ソフトウェアは再びバック バッファに書き込む。このプロセスはアニメーションの間続き、すばやく効率的にイメージをアニメーションさせる。

Direct3D は、比較的単純なダブルバッファ スキーム (1 つのバック バッファを持つカラー フロント バッファ) から、追加のバック バッファを付加したより高度なスキームまで、ページ フリッピング スキームのセット アップを容易にする。


矩形

Microsoft® Direct3D® および Microsoft Windows® プログラミングから、スクリーン上のオブジェクトは境界矩形で参照される。境界矩形の端は常に画面の端と平行であるため、矩形は左上角と右下角の 2 点で記述される。大部分のアプリケーションでは、スクリーンへのブリットやヒット検出を行うために用いられる境界矩形の情報伝達に RECT 構造体が使用される。

RECT 構造体の定義を以下に示す。

typedef struct tagRECT {
    LONG    left;    // これは、左上の角の x 座標。
    LONG    top;     // これは、左上の角の y 座標。
    LONG    right;   // これは、右下の角の x 座標。
    LONG    bottom;  // これは、右下の角の y 座標。
} RECT, *PRECT, NEAR *NPRECT, FAR *LPRECT;

上記の例で、left および top メンバは、境界矩形の左上角の x 座標と y 座標を表す。同様に、right および bottom メンバは、右下角の座標を構成する。次の図は、これらの値を視覚的に説明している。

効率、一貫性、使いやすさなどのために、すべての Direct3D Presentation 関数は矩形範囲を使用する。


DirectX Graphics について

ここでは、Microsoft® DirectX® Graphics の基本的なしくみについて説明する。

  • Direct3D アーキテクチャ
  • Direct3D レンダリング パイプライン


Direct3D アーキテクチャ

ここでは、Microsoft® Direct3D® コンポーネントとその他の Microsoft DirectX® コンポーネント、オペレーティング システム、およびシステム ハードウェアとの関係について説明する。説明するトピックは、次のとおりである

  • Direct3D アーキテクチャの概要
  • ハードウェア アブストラクション レイヤ
  • システムの統合


Direct3D アーキテクチャの概要

Microsoft® Direct3D® アーキテクチャのプログラム可能な部分は、頂点シェーダおよびピクセル シェーダの 2 つである。頂点シェーダは頂点アセンブリの前に呼び出され、頂点を処理する。ピクセル シェーダは DrawPrimitive の呼び出しの後に呼び出され、ピクセルを処理する。

次の単純な図に、Direct3D アーキテクチャを示す。これはアーキテクチャの一部である。Direct3D では 8 つのテクスチャおよびテクスチャ座標をサポートしている。

上の図に示すように、頂点バッファは頂点データを頂点シェーダにストリーミングする。頂点シェーダは、Direct3DX 頂点シェーダ アセンブラによって定義されている命令を使って、ジオメトリ処理を実行する。

頂点シェーダにストリーミングされるデータは、頂点バッファに格納されている必要はないが、格納されていれば理想的である。頂点アセンブリの後で、アセンブルされた頂点データは DrawPrimitive メソッドを使って描画される。この時点で、描画されたプリミティブの各ピクセル (位置、色、テクスチャ、およびテクスチャ座標など) は、ピクセル シェーダに渡される。ピクセル シェーダは、Direct3DX ピクセル シェーダ アセンブラによって定義されている命令を使って、ピクセル処理を実行する。

ピクセルを処理するピクセル シェーダ ステージへの入力には、テクスチャ サーフェスおよびサーフェスのサンプリングを制御する関連するテクスチャ座標が含まれる。出力ピクセルはフレーム バッファに渡される。

Direct3D のプログラム可能な部分のアーキテクチャの詳細については、「頂点シェーダ アーキテクチャ」および「ピクセル シェーダ アーキテクチャ」を参照すること。

頂点シェーダおよびピクセル シェーダをレンダリング パイプラインに組み込む方法の詳細については、「Direct3D レンダリング パイプライン」を参照すること。


頂点シェーダ アーキテクチャ

次の図は、頂点シェーダ アーキテクチャを示している。

頂点データへのデータは、頂点データ ストリームから取得され、定数データは頂点シェーダ宣言子によってロードされる。詳細については、「頂点シェーダ アセンブラ リファレンス」を参照すること。


ピクセル シェーダ アーキテクチャ

次の図は、ピクセル シェーダ アーキテクチャを示している。

ピクセル シェーダへのデータはクリップ空間頂点 (同次座標) である。ディフューズおよびスペキュラ色は、カラー レジスタの値 (v0 および v1) から取得される。テクスチャ座標および設定されたテクスチャは、テクスチャ設定ステージおよび頂点データのテクスチャ レジスタ (t0、t1、t2、および t3) の値から取得される。詳細については、「ピクセル シェーダ アセンブラ リファレンス」を参照すること。


ハードウェア アブストラクション レイヤ

Microsoft® Direct3D® は、ハードウェア アブストラクション レイヤ (HAL) によってデバイスの独立性を提供する。HAL は、デバイス メーカーから提供されるデバイス固有のインターフェイスで、Direct3D はそれを使ってディスプレイ ハードウェアを直接動作させる。アプリケーションは、HAL とは決して相互作用しない。むしろ HAL の提供するインフラを使って、Direct3D はアプリケーションがグラフィックスを表示するために使うインターフェイスやメソッドの一貫したセットを公開する。デバイス メーカーは、Microsoft Windows® のもとでは 16 ビット コード、32 ビット コードの組み合わせで HAL を実装する。Windows NT® および Windows 2000 のもとでは、HAL は常に 32 ビット コードで実装される。HAL は、ディスプレイ ドライバの一部であったり、ドライバの作成者が定義するプライベート インターフェイスからディスプレイ ドライバと通信する個別の DLL になることもできる。

Direct3D HAL は、チップ メーカー、ボード製作者、または OEM 業者により実装される。HAL は、デバイス依存のコードを実装するだけで、エミュレーションは行わない。ある機能がハードウェアにより実行されないとしても、HAL はそれをハードウェア能力と見なして報告しない。さらに、HAL はパラメータを確認しないので、HAL が起動される前に Direct3D がこのパラメータを確認する。

DirectX 8.0 では、HAL は 3 種類の頂点処理モードを持つことができる。ソフトウェア頂点処理、ハードウェア頂点処理、および同一デバイスでの混合頂点処理である。ピュア デバイス タイプは HAL デバイスの一種である。ピュア デバイス タイプはハードウェアによる頂点処理のみをサポートし、アプリケーションが照会できるのはデバイス ステートの小さなサブセットに限られる。さらに、ピュア デバイスは、最小レベルの能力を備えたアダプタでのみ使用できる。


システムの統合

次の図は、Microsoft® Direct3D® と、グラフィックス デバイス インターフェイス (GDI)、ハードウェア アブストラクション レイヤ (HAL)、およびハードウェアとの関係を示している。

前の図に示すように、Direct3D アプリケーションは GDI アプリケーションと共に存在し、これらはグラフィックス カード用のデバイス ドライバを介してグラフィックス ハードウェアにアクセスする。GDI とは異なり、Direct3D は、HAL デバイスが選択されているときにハードウェア機能を利用できる。HAL デバイスは、グラフィックス カードでサポートされる機能セットに基づいて、ハードウェア アクセラレーションを提供する。デバイスにタスクの能力があるかどうかを実行時に判断するための Direct3D メソッドを利用できる。

ソフトウェア デバイスは、DirectX 8.0 機能セット全体をサポートしているわけではないが、アプリケーションが常に、どのシステムにおいても、動作しているデバイスを見つけることができるようにしている。ただし、多くの場合、ソフトウェア デバイス上で実行されるアプリケーションでは、低下した機能でも実行されるように準備する必要がある。ソフトウェア デバイスの能力は、ハードウェア デバイスの能力と同じ方法で調べることができる。

Direct3D でサポートされるデバイスの詳細については、「デバイスの種類」を参照すること。


Direct3D レンダリング パイプライン

Microsoft® Direct3D® レンダリング パイプラインは、頂点トランスフォームおよびライティング パイプライン、およびピクセルおよびテクスチャ ブレンディング パイプラインの動作を指定する一連の処理ステージである。

3D アプリケーションを設計するとき、利便性を考慮してミクロンからパーセクまで、あらゆる単位でワールドを定義できる。アプリケーションは、このワールドの記述を Direct3D に渡す。この記述には、ワールド内にあるすべてのオブジェクトのサイズと相対位置座標、およびビューアの位置座標と向きが含まれる。Direct3D は、この記述 (頂点) をスクリーン上の一連のピクセルに変換する。この処理の最初のステップ (ジオメトリの 2D 画像への変換) のことを、ジオメトリ パイプラインまたはトランスフォーム パイプラインと呼ぶ。頂点を処理した後、ピクセル データを使ってマルチテクスチャ処理およびフォグ ブレンディングが実行される。次に、アルファ、ステンシル、および深度テストが実行される。最後に、フレームバッファ ブレンディングがラスタライザによって実行される。

以下のトピックでは、主に Direct3D における完全なレンダリング パイプラインについて説明する。また、重要な概念について、およびこれらの概念に対応する Direct3D API の概念についても解説する。固定機能処理のトピックでは、旧バージョンの Microsoft DirectX® を使用していた開発者であれば既に理解している手法について説明する。したがって、プログラム可能 (プロシージャ) 処理のトピックでは、Microsoft DirectX 8.0 の頂点処理とピクセル処理で使用される新しいプロシージャ モデルについて説明する。

  • 固定機能による頂点処理とピクセル処理
  • プログラム可能な頂点処理とピクセル処理
  • 頂点プロセッサへの頂点データの提示


固定機能による頂点処理とピクセル処理

ジオメトリの固定機能によるジオメトリ パイプラインを実行するのは、Microsoft® Direct3D® のトランスフォーム エンジンである。これは、ワールド内のモデルとビューアを検出し、スクリーン上に表示できるように頂点を射影し、頂点をビューポートに切り取る。また、トランスフォーム エンジンは、ライティング計算を実行して各頂点のディフューズおよびスペキュラ成分を決定する。

ジオメトリ パイプラインは、頂点を入力として受け取る。トランスフォーム エンジンは、頂点に 3 つのトランスフォーム (ワールド トランスフォーム、ビュー トランスフォーム、および射影トランスフォーム) を適用し、結果をクリップして、そのすべてをラスタライザに渡す。次の図は、一連のステップを示している。

パイプラインの最初の段階においてはトランスフォームは適用されず、モデルの頂点はすべてローカル座標系 (これはローカル原点と向きである) に対して宣言される。この座標向きを一般にモデル空間と呼び、個々のローカル座標はモデル座標と呼ぶ。

ジオメトリ パイプラインでは、最初にローカル座標系のモデルの頂点が、シーンのすべてのオブジェクトで使用する座標系にトランスフォームされる。頂点をワールド座標系で再度定義し直すことを、ワールド トランスフォームと呼ぶ。この新しい向きは、通常はワールド空間と呼ばれ、ワールド空間の各頂点は、ワールド座標を使用して宣言される。

次に、3D ワールドを記述する頂点をカメラに対する相対位置座標で定義し直す。つまり、アプリケーションはシーンの視点 (カメラの位置) を選択し、ワールド空間は視点の位置と向きに合わせて再定義される。すなわち、ワールド空間がカメラ空間にトランスフォームされる。これがビュー トランスフォームである。

次の段階では、射影トランスフォームが行われる。パイプラインにおけるこの段階では、通常、遠くのオブジェクトよりも近くのオブジェクトの方が大きく見えるようにするなど、ビューアからの距離を基準にオブジェクトがスケーリングされて、シーンに奥行きが生まれる。わかりやすくするために、このドキュメントでは、射影トランスフォーム後の頂点が存在する空間を、射影空間と呼ぶことにする。グラフィックス関連の書籍では、射影空間のことを、遠近補正後同次空間と呼ぶ場合もある。すべての射影トランスフォームによってシーンのオブジェクトのサイズがスケーリングされるとは限らない。このような射影は、アフィン射影または正射影と呼ばれることもある。

パイプラインの最後の段階では、スクリーン上で見えない頂点がすべて削除される。これにより、ラスタライザは、見えないオブジェクトに関して色とシェーディングの計算を実行する必要がなくなる。この処理はクリッピングと呼ばれる。クリッピングが完了すると、残りの頂点はビューポート パラメータに従ってスケーリングされ、スクリーン座標系にトランスフォームされる。その結果、これらの頂点は、シーンがラスタ化されたときにスクリーンに表示され、スクリーン空間に存在するようになる。

固定頂点処理とピクセル処理パイプラインについては、以下のトピックに分けて説明する。

  • トランスフォームおよびライティング エンジン
  • ビューポートとクリッピング
  • ラスタ化


トランスフォームおよびライティング エンジン

以下のトピックでは、固定機能によるトランスフォームおよびライティング エンジンの各コンポーネントのしくみを詳しく説明する。

  • ワールド トランスフォーム
  • ビュー トランスフォーム
  • 射影トランスフォーム
  • ライティング エンジン
  • Direct3D のライティングにおける数学的計算


ワールド トランスフォーム

ここでは、ワールド トランスフォームについての基本的な概念を紹介し、Microsoft® Direct3D® アプリケーションでワールド トランスフォーム行列を設定する方法について詳しく説明する。説明するトピックは次のとおりである。

  • ワールド トランスフォームとは
  • ワールド行列の設定


ワールド トランスフォームとは

ワールド トランスフォームでは、頂点がモデルのローカル原点に対して定義されるモデル空間から、頂点がシーン内のすべてのオブジェクトに共通する原点に対して定義されるワールド空間に座標をトランスフォームする。基本的には、ワールド トランスフォームによってモデルがワールドに配置されることから、このような名前が付いている。次の図は、ワールド座標系とモデルのローカル座標系の関係を示している。

ワールド トランスフォームでは、平行移動、回転、およびスケーリングをどのように組み合わせても使用できる。トランスフォームの数学上の説明については、「3D トランスフォーム」を参照すること。


ワールド行列の設定

ほかのすべてのトランスフォームと同様、一連のトランスフォーム行列を、個々の効果をすべて含む単一の行列に連結することでワールド トランスフォームを作成する。簡単な例では、あるモデルがワールド原点にあり、そのローカル座標軸がワールド空間と同じ方向に定義されている場合、ワールド行列は単位行列である。さらに一般的には、ワールド行列はワールド空間への平行移動を組み合わせたものであり、必要に応じてモデルを 1 回または何度も回転することができる。

次の例は、C++ で記述された架空の 3D モデル クラスに関するものである。ここでは、Direct3DX ユーティリティ ライブラリに含まれるヘルパー関数を使用して、モデルを方向付ける回転を 3 回行い、さらにワールド空間での位置座標を基準にそのモデルを再配置する平行移動を行うワールド行列を作成する。

/*
* この例では、次の変数は
* 有効であり、初期化されていると仮定する。
 *
* 変数 m_xPos、m_yPos、m_zPos はモデルの
* ワールド座標での位置を格納する。
 *
* 変数 m_fPitch、m_fYaw、および m_fRoll は浮動小数点数で、
* ピッチ、ヨー、およびロール (ラジアン単位) での
* モデルの向きを格納する。
 */

void C3DModel::MakeWorldMatrix( D3DXMATRIX* pMatWorld )
{
    D3DXMATRIX MatTemp;  // 回転用の Temp 行列。
    D3DXMATRIX MatRot;   // 最終的な回転行列。
                         // pMatWorld に適用される。

    // 左から右に行列を連結して、
    // オブジェクトのワールド位置座標に平行移動を適用した後、
    // 回転を適用する。
    D3DXMatrixTranslation(pMatWorld, m_xPos, m_yPos, m_zPos);
    D3DXMatrixIdentity(&MatRot);

    // ここで、ワールド行列に向き変数を適用する。
    if(m_fPitch || m_fYaw || m_fRoll) {
        // 回転行列を作成し、組み合わせる。
        D3DXMatrixRotationX(&MatTemp, m_fPitch);         // ピッチ。
        D3DXMatrixMultiply(&MatRot, &MatRot, &MatTemp);
        D3DXMatrixRotationY(&MatTemp, m_fYaw);           // ヨー。
        D3DXMatrixMultiply(&MatRot, &MatRot, &MatTemp);
        D3DXMatrixRotationZ(&MatTemp, m_fRoll);          // ロール。
        D3DXMatrixMultiply(&MatRot, &MatRot, &MatTemp);

        // 回転行列を適用し、ワールド行列を完成する。
        D3DXMatrixMultiply(pMatWorld, &MatRot, pMatWorld);
    }
}

ワールド トランスフォーム行列が準備できたら、この行列を設定するために IDirect3DDevice8::SetTransform メソッドを呼び出して、第 1 パラメータに D3DTS_WORLD マクロを指定する。詳細については、「トランスフォームの設定」を参照すること。

注 Microsoft® Direct3D® では、設定されたワールド行列およびビュー行列を使用して、いくつかの内部データ構造を構築する。新しいワールド行列またはビュー行列を設定するたびに、関係する内部構造が再計算される。これらの行列をフレームごとに数千回も設定するなど頻繁に設定すると、多大な計算負荷が発生する。必要な計算を最小限に抑えるには、ワールド行列として設定するワールドビュー行列にワールド行列およびビュー行列を連結した後、ビュー行列を単位行列に設定する。必要に応じてワールド行列を修正、連結、およびリセットできるように、ワールド行列およびビュー行列の各キャッシュ コピーは保持しておくこと。このドキュメントの Direct3D のサンプルでは、簡潔であることを優先して、この最適化はほとんど用いていない。


ビュー トランスフォーム

ここでは、ビュー トランスフォームの基本的な概念を紹介し、Microsoft® Direct3D® アプリケーションでビュー トランスフォーム行列を設定する方法について詳しく説明する。説明するトピックは、次のとおりである。

  • ビュー トランスフォームとは
  • ビュー行列の設定


ビュー トランスフォームとは

ビュー トランスフォームとは、ワールド空間に視点を配置し、頂点をカメラ空間にトランスフォームする処理である。カメラ空間では、カメラ (つまり視点) は原点にあり、ｚ 軸の正方向を向く。Microsoft® Direct3D® では左手座標系を使用するため、z はシーンの正方向を向く。ビュー行列は、ワールド内のオブジェクトをカメラの位置 (カメラ空間の原点) と向きの周囲に再配置する。

ビュー行列は多くの方法で作成できる。すべての方法において、カメラはワールド空間内でいくつかの論理位置座標と向きを持つ。これらの位置座標と方向は、シーン内のモデルに適用するビュー行列を作成する際の始点となる。ビュー行列は、オブジェクトを平行移動および回転して、カメラを原点としたカメラ空間内に位置座標付ける。ビュー行列を作成する方法としては、平行移動行列と各軸に対する回転行列を組み合わせる方法がある。この方法では、次の一般的な行列式が適用される。

この式では、V は作成するビュー行列、T はオブジェクトをワールド内に再配置する平行移動行列、Rx ～ Rz は x、y、および z 軸に沿ってオブジェクトを回転する回転行列である。この平行移動行列と回転行列は、ワールド空間におけるカメラの論理位置座標と向きに基づいている。したがって、ワールドにおいてカメラの論理位置座標が <10,20,100> の場合、平行移動行列は、x 軸に沿って -10 単位、y 軸に沿って -20 単位、z 軸に沿って -100 単位だけオブジェクトを平行移動することになる。この式における回転行列は、カメラの向きに基づいており、カメラ空間の軸がワールド空間からどれくらい回転するかを表す。たとえば、上の例のカメラが真下を向いている場合、次の図に示すように、カメラ空間の z 軸はワールド空間の z 軸から 90° (π/2 ラジアン) だけずれている。

回転行列は、マグニチュードは同じであるが方向が逆の回転を、シーン内のモデルに適用する。このカメラに対するビュー行列は、x 軸を中心とした -90°の回転を含む。回転行列と平行移動行列を組み合わせることで、シーン内のオブジェクトの位置座標と向きを調整するビュー行列を作成して、オブジェクトの上側にカメラを置いてモデルを上から見下ろすことができる。

別の方法として、複雑なビュー行列を直接作成する方法もある。D3DXMatrixLookAtLH および D3DXMatrixLookAtRH ヘルパー関数では、この手法が使用される。この方法では、カメラのワールド空間における位置座標とシーン内の注視点を使用して、カメラ空間の座標軸の向きを記述するベクトルを派生させる。注視点からカメラ位置座標を減算して、カメラの方向ベクトル (ベクトル n) 用のベクトルを生成する。次に、ベクトル n とワールド空間の y 軸の外積をとり、正規化して、右方向ベクトル (ベクトル u) を生成する。次に、ベクトル u と n の外積をとり、上方向ベクトル (ベクトル v) を決める。右方向 (u)、上方向 (v)、およびビュー方向 (n) のベクトルは、ワールド空間におけるカメラ空間の座標軸の向きを記述する。x、y、z の平行移動係数は、カメラ位置座標と u、v、n ベクトルの間の内積の負数をとって計算する。

これらの値を次の行列に入れて、ビュー行列を生成する。

この行列では、u、v、n はそれぞれ上方向、右方向、ビュー方向のベクトルであり、c はカメラのワールド空間位置座標である。この行列には、ワールド空間をカメラ空間に平行移動と回転するために必要な要素がすべて格納される。この行列を作成した後、z 軸を中心とする回転行列を作成して、カメラを回転することができる。

この方法の実装については、「ビュー行列の設定」を参照すること。


ビュー行列の設定

D3DXMatrixLookAtLH および D3DXMatrixLookAtRH ヘルパー関数は、カメラ位置座標および注視点に基づいてビュー行列を作成する。これらの関数は、D3DXVec3Cross、D3DXVec3Dot、D3DXVec3Normalize、および D3DXVec3Subtract ヘルパー関数を使用する。

次のコードは、D3DXMatrixLookAtLH 関数を示している。

D3DXMATRIX* WINAPI D3DXMatrixLookAtLH
    ( D3DXMATRIX *pOut, const D3DXVECTOR3 *pEye, const D3DXVECTOR3 *pAt,
      const D3DXVECTOR3 *pUp )
{
#if DBG
    if(!pOut || !pEye || !pAt || !pUp)
        return NULL;
#endif

    D3DXVECTOR3 XAxis, YAxis, ZAxis;

    // 奥行きを示す z 軸ベクトルを取得する。
    // 視点から注視点までの差である。これは
    // 注視する方向 (+z) である。
    D3DXVec3Subtract(&ZAxis, pAt, pEye);

    // z 軸ベクトルを正規化する。
    D3DXVec3Normalize(&ZAxis, &ZAxis);

    // 注視する方向と pUp ベクトルの外積から
    // 直交軸を計算する。
    D3DXVec3Cross(&XAxis, pUp, &ZAxis);
    D3DXVec3Normalize(&XAxis, &XAxis);
    D3DXVec3Cross(&YAxis, &ZAxis, &XAxis);

    // 行列の構築を開始する。最初の 3 つの行には、
    // ビューを回転して注視点に向けるためのベクトルが含まれる。
    // point.// 4 番目の行には平行移動の値が含まれる。
    // 視点を中心とした回転が行われる。
    pOut->_11 = XAxis.x;
    pOut->_21 = XAxis.y;
    pOut->_31 = XAxis.z;
    pOut->_41 = -D3DXVec3Dot(&XAxis, pEye);

    pOut->_12 = YAxis.x;
    pOut->_22 = YAxis.y;
    pOut->_32 = YAxis.z;
    pOut->_42 = -D3DXVec3Dot(&YAxis, pEye);

    pOut->_13 = ZAxis.x;
    pOut->_23 = ZAxis.y;
    pOut->_33 = ZAxis.z;
    pOut->_43 = -D3DXVec3Dot(&ZAxis, pEye);

    pOut->_14 = 0.0f;
    pOut->_24 = 0.0f;
    pOut->_34 = 0.0f;
    pOut->_44 = 1.0f;

    return pOut;
}

ワールド トランスフォームの場合と同様、IDirect3DDevice8::SetTransform メソッドを呼び出してビュー トランスフォームを設定し、第 1 パラメータに D3DTS_VIEW フラグを指定する。詳細については、「トランスフォームの設定」を参照すること。

パフォーマンスの最適化に関する注 Microsoft® Direct3D® では、設定されたワールド行列およびビュー行列を使用して、いくつかの内部データ構造を構築する。新しいワールド行列またはビュー行列を設定するたびに、関係する内部構造が再計算される。これらの行列をフレームごとに 20,000 回も設定するなど頻繁に設定すると、多大な計算負荷が発生する。必要な計算を最小限に抑えるには、ワールド行列として設定するワールドビュー行列にワールド行列およびビュー行列を連結した後、ビュー行列を単位行列に設定する。ワールド行列およびビュー行列の各キャッシュ コピーは保持しておくこと。必要に応じてワールド行列を修正、連結、およびリセットできる。Direct3D のサンプルでは、簡潔であることを優先して、この最適化はほとんど用いていない。


射影トランスフォーム

射影トランスフォームは、カメラの内部を制御することと考えることができる。つまり、射影トランスフォームは、カメラのレンズを選ぶことに似ている。このトランスフォームは、3 種類のトランスフォームの中で最も複雑である。射影トランスフォームについては、以下のトピックに分けて説明する。

  • 視錐台
  • 射影トランスフォームとは
  • 射影行列の設定
  • W バッファに有効な射影行列


視錐台

視錐台とは、ビューポートのカメラに対して相対的に配置されたシーン内の 3D 立体である。この立体の形は、カメラ空間からスクリーンにモデルを射影する方法に影響を与える。最も一般的な射影は、パースペクティブ射影である。この射影では、カメラの近くにあるオブジェクトが、カメラの遠くにあるオブジェクトよりも大きく表示される。パースペクティブ ビューの場合、視錐台とは先端にカメラがあるピラミッドと考えるとわかりやすい。このピラミッドは、前方および後方クリップ面に当たる。前方および後方クリップ面の間にあるピラミッド内の立体が視錐台である。オブジェクトは、この立体内にあるときにのみ見ることができる。

視錐台は、暗い部屋の中で正方形の窓から外を見ている状況を想像するとわかりやすい。別な表現をすると、前方クリップ面は窓であり、後方クリップ面は視界を最終的に遮るもの、たとえば、街の高層ビル、遠方の山脈、または完全な無の空間である。視錐台の内部 (窓から最終的に遮るものまでの間) にあるものはすべて見ることができ、それ以外のものは見ることができない。

視錐台は、z 座標で指定される前方および後方クリップ面の間の距離と FOV (視野) で定義される。

この図では、変数 D は、カメラから、ジオメトリ パイプラインの最後の部分 (ビュー トランスフォーム) で定義された空間の原点までの距離である。この空間の周りに視錐台の限界を設定する。この変数 D を使用して射影行列を作成する方法については、「射影トランスフォームとは」を参照すること。


射影トランスフォームとは

射影行列とは、一般に、スケーリング パースペクティブ射影である。射影トランスフォームでは視錐台を立方体にトランスフォームする。視錐台の近くの端は遠くの端よりも小さいので、このトランスフォームにはカメラの近くのオブジェクトを拡大するという効果があり、これによってシーンに遠近感が生まれる。

視錐台では、射影トランスフォームに必要なカメラとビュー トランスフォームによって定義される空間の原点の間の距離が、D として定義される。パースペクティブ射影を定義する行列では、次のように、最初にこの変数 D を使用する。

ビュー行列は、カメラをシーンの原点に配置する。射影行列では (0, 0, -D) にカメラを配置する必要があるので、射影行列は次の行列を使用してベクトルを z 方向に -D だけ平行移動する。

これら 2 つの行列を乗算すると、次のような合成行列ができる。

次の図は、パースペクティブ トランスフォームが視錐台を新しい座標空間に変換する方法を示している。視錐台が立方体になること、およびシーンの右上角にあった原点が中心に移動することに注目する。

パースペクティブ トランスフォームでは、x 方向と y 方向の限界は -1 と 1 である。z 方向の限界は、前方面ついては 0 で、後方面については 1 である。

この行列は、カメラから前方のクリップ面までの距離に基づいてオブジェクトを平行移動およびスケーリングする。しかし、この行列は視野 (FOV) を考慮せず、遠くのオブジェクトに対して生成する z 値はほとんど同じなので、深度比較が困難になる。この問題を解決するために、次の行列は、ビューポートのアスペクト比を考慮して頂点を調整し、アスペクト比をパースペクティブ射影に合わせる。

この行列では、Zn は前方のクリップ面の z 値である。変数 w、h、および Q の意味は、次のとおりである。FOVw および FOVh は、ビューポートの水平方向および垂直方向の視野を表す (ラジアン単位)。

アプリケーションでは、視野角度を使用して x と y の倍率を定義することは、ビューポートの水平寸法と垂直寸法 (カメラ空間の) を使用するのに比べて不便な場合がある。数学の練習問題として、次に示す w と h 用の 2 つの式ではビューポートの寸法を使用している。これらの式は上の公式と同等である。

これらの式では、Zn は前方のクリップ面の位置座標を表し、変数 Vw と Vh はカメラ空間でのビューポートの幅と高さを表している。

C++ アプリケーションでは、幅と高さの寸法は、D3DVIEWPORT8 構造体の Width および Height メンバに直接対応する。

どの式を使用する場合でも、Zn をできるだけ大きな値に設定することが重要である。理由は、カメラに極端に近い z 値は大幅には変化しないからである。これによって、16 ビットの z バッファを使用する深度比較は若干複雑になる。

ワールド トランスフォームおよびビュー トランスフォームと同様、IDirect3DDevice8::SetTransform メソッドを呼び出して射影トランスフォームを設定する。詳細については、「トランスフォームの設定」を参照すること。


射影行列の設定

C++ で記述された、次の ProjectionMatrix サンプル関数は、水平および垂直視野の角度のほかに、前方および後方クリップ面を設定する 4 つの入力パラメータを受け取る。このコードは、「射影トランスフォームとは」で示すコードと類似している。視野は pi ラジアン未満にする必要がある。

D3DMATRIX
ProjectionMatrix(const float near_plane, // 近くのクリップ面までの
                                         // 距離
                 const float far_plane,  // 遠くのクリップ面までの
                                         // 距離
                 const float fov_horiz,  // 水平方向の視野の
                                         // 角度 (ラジアン単位)。
                 const float fov_vert)   // 垂直方向の視野の
                                         // 角度 (ラジアン単位)。
{
    float    h, w, Q;

    w = (float)1/tan(fov_horiz*0.5);  // 1/tan(x) == cot(x)
    h = (float)1/tan(fov_vert*0.5);   // 1/tan(x) == cot(x)
    Q = far_plane/(far_plane - near_plane);

    D3DMATRIX ret;
    ZeroMemory(&ret, sizeof(ret));

    ret(0, 0) = w;
    ret(1, 1) = h;
    ret(2, 2) = Q;
    ret(3, 2) = -Q*near_plane;
    ret(2, 3) = 1;
    return ret;
}   // ProjectionMatrix の最後。

行列を作成した後は、IDirect3DDevice8::SetTransform メソッドを呼び出してその行列を設定し、第 1 パラメータに D3DTRANSFORMSTATE_PROJECTION を指定する必要がある。詳細については、「トランスフォームの設定」を参照すること。

ただし、Direct3DX ユーティリティ ライブラリには、射影行列を設定する次の関数が用意されている。

  • D3DXMatrixPerspectiveLH
  • D3DXMatrixPerspectiveRH
  • D3DXMatrixPerspectiveFovLH
  • D3DXMatrixPerspectiveFovRH
  • D3DXMatrixPerspectiveOffCenterLH
  • D3DXMatrixPerspectiveOffCenterRH


W バッファに有効な射影行列

Microsoft® Direct3D® では、ワールド行列、ビュー行列、および射影行列によってトランスフォームされた頂点の W 要素を利用して、深度バッファまたはフォグ エフェクトの計算を深度をベースに実行できる。このような計算では、射影行列により W をワールド空間 Z で対応する W に正規化する必要がある。つまり、射影行列に 1 ではない (3,4) 係数が含まれる場合、(3,4) 係数の逆数を使用してすべての係数をスケーリングすることで、適切な行列を作成しなければならない。対応していない行列を使用すると、フォグ エフェクトと深度バッファが正しく適用されない。射影トランスフォームとはで推奨する射影行列は、w ベースの計算に対応している。

次の図は、対応していない射影行列、および同じ行列をスケーリングして視点との相対フォグが有効になるようにした行列を示している。

上の図では、すべての変数がゼロ以外の値であるとする。視点との相対フォグの詳細については、「視点からの相対深度 対 Z ベースの深度」を参照すること。w ベースの深度バッファリングについては、「深度バッファとは」を参照すること。

注 Direct3D では、現在設定されている射影行列が w ベースの深度計算に使用される。したがって、アプリケーションで Direct3D トランスフォーム パイプラインを使用しない場合であっても、希望の w ベース機能を取得するために適切な射影行列を設定しておく必要がある。


ライティング エンジン

ここでは、Microsoft® Direct3D® ライティング エンジンの概要について説明する。説明するトピックは、次のとおりである

  • ライティング エンジンの有効/無効
  • ライトのカラー タイプとソース
  • フォグ エフェクト

ライティング エンジンの内部動作の詳細については、「Direct3D のライティングにおける数学的計算」を参照すること。


ライティング エンジンの有効/無効

デフォルトでは、Microsoft® Direct3D® は、すべての頂点に対してライティング計算を実行する。この計算は、頂点法線を持たない頂点に対しても実行される旧リリースの Microsoft DirectX® では、頂点法線を持つ頂点に対してのみライティングが実行された。ただし、D3DRS_LIGHTING レンダリング ステートを使用してライティングを無効にできる。IDirect3DDevice8::SetRenderState メソッドを呼び出して、第 1 パラメータとして D3DRS_LIGHTING を渡し、第 2 パラメータとして TRUE または FALSE を渡す。ステートを TRUE に設定するとライティングが有効になり (デフォルト)、FALSE を設定すると無効になる。


ライトのカラー タイプとソース

Microsoft® Direct3D® の光源は、互いに独立してライティング計算の係数として働く個々のライティング コンポーネントとして、ディフューズ色、アンビエント色、およびスペキュラ色を発する。同様に、システムがレンダリングする頂点は、その頂点フォーマットによって定義された個別のディフューズ色、アンビエント色、スペキュラ色、およびエミッション色を使用する。

C++ アプリケーションの場合、これらの頂点カラーは、D3DRS_COLORVERTEX レンダリング ステートを TRUE に設定したときにのみ、システムによって使用される。頂点カラー ソースは選択可能である。つまり、実行時にライティング式の頂点カラー部分のソースを選択するように設定できる。D3DRS_AMBIENTMATERIALSOURCE、D3DRS_DIFFUSEMATERIALSOURCE、および D3DRS_SPECULARMATERIALSOURCE レンダリング ステートは、ライティング計算の際にシステムが描画する色のカラー ソースを制御する。各レンダリング ステートは、D3DMATERIALCOLORSOURCE 列挙型のメンバに設定できる。これは、カラー ソースとして現在のマテリアルを使用するか、または頂点の色を使用するかを指定する値を定義する。


フォグ エフェクト

Microsoft® Direct3D® のトランスフォーム & ライティング エンジンでは、ライティング中にフォグ エフェクトを作成できる。このようなフォグは、フォグ情報が、ラスタ化される頂点のアルファ成分に配置されることから、通常は頂点フォグと呼ばれる。

詳細については、「フォグ」および「頂点フォグ」を参照すること。


Direct3D のライティングにおける数学的計算

ここでは、Microsoft® Direct3D® ライティング エンジンのしくみおよび実装の詳細を説明する。Direct3D は、自然光の振る舞いを評価してライティングをモデル化する。Direct3D ライティング モデルは、ライトの色、ライトの進行方向と距離、ビューアの位置座標、およびマテリアルの特性を監視して、面の各頂点で 2 つの色成分を計算する。Direct3D は、これらの色成分を使用して、面のピクセルをラスタ化するときに描画する色を計算する。

注 すべての計算はモデル空間で行われる。ワールド行列の逆行列を使用してカメラ位置座標と共にライトの位置座標と方向をモデル空間にトランスフォームし、次に逆トランスフォームする。その結果、ワールド行列またはビュー行列によって一様でないスケーリングが生じる場合は、最終的なライティングが不正確になることがある。

ここでは、ディフューズ成分とスペキュラ成分を提供するために Direct3D で使用する公式について技術的観点から説明する。Direct3D の方法を理解すれば、Direct3D ライティング モデルが要望に合うかどうかをより正確に判断できるようになる。Direct3D ライティング モデルは、正確さ、効率性、および使いやすさを目指して設計されている。しかし、Direct3D で使用する公式がニーズに合わない場合は、Direct3D ライティング モジュールは使用せず、独自のライティング モデルを実装することもできる。説明するトピックは、次のとおりである

  • ライティング表記
  • カメラ空間トランスフォーム
  • 基本的なライティング公式
  • ディフューズ公式
  • スペキュラ公式
  • 距離の増加によるライトの減衰
  • 反射率モデル
  • スポットライト フォールオフ モデル

この公式で使用されるパラメータを、次の表に示す。各表には、対応するデフォルト値、型、および許容値の範囲を示す。

次の表は、位置パラメータを示している。

パラメータ | デフォルト値 | 型 | 説明
Pe | (0,0,0) | D3DVECTOR | カメラ空間でのカメラの位置座標。
Po | N/A | D3DVECTOR | カメラ空間における現在のモデル原点 (0,0,0,1) の位置。これは Mw*Mv 行列の 4 行目である。
Mw | N/A | D3DMATRIX | D3DTRANSFORMSTATE_VIEW によって設定されるワールド行列。
Mv | N/A | D3DMATRIX | D3DTRANSFORMSTATE_VIEW によって設定されるビュー行列。
Mwv | N/A | D3DMATRIX | Mw*Mv。
Halfway | N/A | D3DVECTOR | 正規化されたベクトル。スペキュラ反射を計算するために使用される。
La | (0.0, 0.0, 0.0, 0.0) | D3DCOLORVALUE | ライト ステートのアンビエント色。D3DRENDERSTATE_AMBIENT によって設定される。
V | N/A | D3DVECTOR | カメラ空間での頂点の位置座標。
N | N/A | D3DVECTOR | カメラ空間での正規化された頂点の法線。
Vcd | N/A | D3DCOLORVALUE | 頂点のディフューズ色。
Vcs | N/A | D3DCOLORVALUE | 頂点のスペキュラ色。

次の表は、マテリアル パラメータを示している。

パラメータ | デフォルト値 | 型 | 説明
Ma | (0.0, 0.0, 0.0, 0.0) | D3DCOLORVALUE | アンビエント色。
Md | (255, 255, 255, 255) | D3DCOLORVALUE | ディフューズ色。
Ms | (0.0, 0.0, 0.0, 0.0) | D3DCOLORVALUE | スペキュラ色。
Me | (0.0, 0.0, 0.0, 0.0) | D3DCOLORVALUE | エミッション色。
Mp | 0.0 | D3DVALUE | スペキュラ指数。範囲 : (-∞,+∞)

次の表は、光源 i パラメータを示している。

パラメータ | デフォルト値 | 型 | 説明
LpI | (0.0, 0.0, 0.0) | D3DVECTOR | カメラ空間での位置座標。
LdI | (0.0, 0.0, 1.0) | D3DVECTOR | カメラ空間でのライトへの方向。
LrI | 0.0 | D3DVALUE | 距離の範囲。範囲 : [0.0, D3DLIGHT_RANGE_MAX]。
LcaI | (0.0, 0.0, 0.0, 0.0) | D3DCOLORVALUE | アンビエント色。
LcsI | (0.0, 0.0, 0.0, 0.0) | D3DCOLORVALUE | スペキュラ色。
LcI | (1.0, 1.0, 1.0, 0.0) | D3DCOLORVALUE | ディフューズ色。
att0I | 0.0 | D3DVALUE | 固定減衰係数。範囲 : (0, +∞)
att1I | 0.0 | D3DVALUE | 線形減衰係数。範囲 : (0, +∞)
att2I | 0.0 | D3DVALUE | 2 次減衰係数。範囲 : (0, +∞)
falloffI | 0.0 | D3DVALUE | フォールオフ係数。範囲 : (-∞, +∞)
thetaI | 0.0 | D3DVALUE | スポットライトの本影角度 (ラジアン単位)。範囲 : [0, π)
phiI | 0.0 | D3DVALUE | スポットライトの半影角度 (ラジアン単位)。範囲 : [thetaI, π)。


ライティング表記

ライティング公式では次の表記を使用する。

D3DCOLORVALUE コンポーネントの範囲は (-∞, +∞) である。

・ - 内積は d1 ・ d2 = max{d1・d2, 0} として定義される。

norm(P) - 単位ベクトル、またはベクトルの正規化

V1V2 - ポイント V1 からポイント V2 へのベクトル

M-1- 逆行列

MT- 転置行列

V1 / V2。 V1 および V2 は D3DVECTOR 型である。この型はベクトル (V1.x / V2.x, V1.y / V2.y , V1.z / V2.z) と同等である。

V1 * V2。V1 および V2 は D3DVECTOR 型である。この型はベクトル (V1.x * V2.x, V1.y * V2.y , V1.z * V2.z) と同等である。


カメラ空間トランスフォーム

カメラ空間の頂点は、オブジェクトの頂点に Mwv 行列を乗算することによって計算される。

v = Vobject * Mwv

カメラ空間の法線は、オブジェクトの法線に逆転置行列 Mwv を乗算し、その結果を正規化することによって計算される。

N = Nobject * (Mwv-1)T

D3DRENDERSTATE_NORMALIZENORMALS が TRUE に設定されている場合、法線はカメラ空間へのトランスフォームの後、正規化される。

N = norm(N)

カメラ空間でのライトの位置座標 (Lpi) は、光源の位置座標に Mv を乗算することによって計算される。

Lpi = Lporiginal * Mv

D3DLIGHT_DIRECTIONAL ライトのカメラ空間でのライトへの方向は、光源の位置座標に Mv 行列を乗算し、その結果を正規化して否定することによって計算される。

Ldi = -norm(Ldi original * Mv)

D3DLIGHT_POINT および D3DLIGHT_SPOT の場合は、ライトへの方向は次のように計算される。

Ldi = norm(VLpi)


基本的なライティング公式

ライティング ステージの出力は、RGBA フォーマットでのディフューズ (D) 色およびスペキュラ (s) 色である。ライティングは次の 2 つのステートのいずれかである。

1. ライティング オフ (D3DRENDERSTATE_LIGHTING が FALSE に設定されている)。このステートでは、頂点カラーは次のように計算される。

D3DRENDERSTATE_COLORVETEX は無視される。

ディフューズ頂点カラーが存在する場合、出力ディフューズ色は頂点のディフューズ色に等しい。それ以外の場合は、ディフューズ色はデフォルトのディフューズ色 (255,255,255,255) に等しい。出力ディフューズ色は [0, 255] の範囲にスケーリングおよびクランプされる。

スペキュラ頂点カラーが存在する場合、出力スペキュラ色は頂点のスペキュラ色に等しい。それ以外の場合は、スペキュラ色はデフォルトのスペキュラ色 (0,0,0,0) に等しい。出力スペキュラ色は [0, 255] の範囲にスケーリングおよびクランプされる。

2. ライティング オン (D3DRENDERSTATE_LIGHTING が TRUE に設定されている)。このステートでは、Direct3D は以下の公式に従って頂点カラーを計算する。

頂点に法線が存在しない場合、ライティングの式で内積に依存する部分は 0 に設定される。ライティングが計算される。

ライティングがカメラ空間で行われる。

alpha 成分は次のライティングの式では使用されない。


ディフューズ公式

ここでは、ディフューズ ライティングの公式について説明する。

D3DRENDERSTATE_SPECULARENABLE が FALSE に設定されている場合、スペキュラ成分は (0, 0, 0, 0) に設定される。それ以外の場合は、次のように計算される。

ここで


スペキュラ公式

ここでは、スペキュラ ライティングの公式について説明する。

hi は法線とライトへの方向の間の中間ベクトルである。

hi = norm(norm(Vpe) + Ldi))。D3DRENDERSTATE_LOCALVIEWER = TRUE の場合

hi = norm((0,0,-1) + Ldi))。D3DRENDERSTATE_LOCALVIEWER = FALSE の場合

rhoi = norm(Ldi) • norm(VLpi)

di は頂点からライト i までの距離で、次のように計算される。

すべてのライトが処理され、個別に補間された後、ディフューズ成分およびスペキュラ成分は 0 ～ 255 にクランプされる。


距離の増加によるライトの減衰

Microsoft® Direct3D® では、ライトで照らされた頂点と光源の間の距離を、ライトの位置座標と頂点の間のベクトルのマグニチュードによって決定する。これを次の公式で表す。

この公式では、D は計算する距離、V はライトで照らされた頂点の位置座標、L は光源の位置座標である。D がライトの範囲 (つまり、D3DLIGHT8 構造体の Range メンバ) より大きい場合、Direct3D はそれ以上減衰計算を実行せず、ライティング エフェクトを頂点に適用しなくなる。距離がライティングの範囲内にある場合は、Direct3D は以下の公式を適用して、距離の増加に伴うポイント ライトおよびスポットライトのライトの減衰を計算する。ディレクショナル ライトは減衰しない。

この減衰公式では、A は計算した全減衰、D は光源から頂点までの距離である。dvAttenuation0、dvAttenuation1、および dvAttenuation2 の値は、ライト オブジェクトの D3DLIGHT8 構造体のメンバによって指定される、ライトの減衰定数である。対応するメンバはそれぞれ、Attenuation0、Attenuation1、および Attenuation2 である。

減衰定数は公式では係数になる。これらの係数に簡単な調整を加えることで、さまざまな減衰カーブを生成できる。Attenuation0 を 1.0 に設定して、減衰しない光を作成できる (ただし、範囲による制限がある)。また、いろいろな値を試してみて、さまざまな減衰エフェクトを出すことができる。

ライティングの最大範囲における減衰は 0.0 ではない。ライティングの範囲内でライティングが突然現れるのを防止するために、アプリケーションではライティングの範囲を増やすことができる。また、アプリケーションで、ライティング範囲における減衰係数が 0.0 に近づくように減衰定数を設定できる。減衰値をライティングの色の赤、緑、および青成分で乗算して、ライティングの強度を光が頂点まで進む距離の係数として定めることができる。

ライティング減衰を計算した後、Direct3D では、スポットライト エフェクト (適用する場合)、サーフェスからの光の反射角度、および現在のマテリアルの反射率を考慮して、その頂点に対するディフューズ成分とスペキュラ成分を算出する。詳細については、「スポットライト フォールオフ モデル」および「反射率モデル」を参照すること。


反射率モデル

すべての減衰エフェクトでライティング強度を調整した後、Microsoft® Direct3D® では頂点法線と入射光の方向の角度を仮定して、頂点から反射する残光の量を計算する。ディレクショナル ライトではこの手順は実行されない。距離が増加しても光が減衰しないためである。

Direct3D ではディフューズとスペキュラの 2 種類の反射を考慮し、異なる公式を使用して各ライティングで反射する光の量を決定する。反射するライティングの量を計算した後、Direct3D はこれらの新しい値を、現在のマテリアルのディフューズ反射率プロパティとスペキュラ反射率プロパティに適用する。この結果として生じるカラー値は、グーロー シェーディングとスペキュラ ハイライト生成のためにラスタライザが使用するディフューズ成分とスペキュラ成分である。

ディフューズ反射モデル

Microsoft Direct3D では、次の公式を使用してディフューズ反射係数を計算する。

この公式では、Rd はディフューズ反射係数、D はライトが頂点に向かう方向、N は頂点法線である。ベクトル D は正規化される。ベクトル N は、D3DRS_NORMALIZENORMALS レンダリング ステートが有効になっている場合にのみ正規化される。ライティングの方向ベクトルに -1 を乗じて逆ベクトルにして、方向ベクトルと頂点法線の間の適正な関係付けを作成する。この公式の結果は -1.0 ～ 1.0 の範囲の値である。この値は 0.0 ～ 1.0 の範囲に制限され、頂点から反射されるライティングの強度を調整するために使用される。

ディフューズ反射係数を計算した後で、その結果を次のようなディフューズ反射公式に適用して、その頂点におけるディフューズ成分が決定される。次の公式は、アンビエント反射とディフューズ反射を組み合わせて頂点におけるディフューズ成分を作成する。

この公式では、Dv は頂点に対して計算されるディフューズ成分、Ia はシーン内のアンビエント ライト、および A は距離とスポットライト エフェクトのために減衰した光源のライティング強度 (スポットライト フォールオフ モデルで乗算された、距離の増加によるライトの減衰) である。変数 L はライティングのプロパティを表し、V エントリは頂点カラーを表す。ここで、それぞれに適用されている添字 a、d、および e は、色の種類のアンビエント (ambient)、ディフューズ (diffuse)、またはエミッション (emissive) を表す。公式で示すように、まず IaVa + Ve が計算され、すべてのアクティブなライティングの A(RdVdLd + VaLa) が加算される。

D3DRS_COLORVERTEX レンダリング ステートが有効になっている場合、D3DRS_AMBIENTMATERIALSOURCE および D3DRS_DIFFUSEMATERIALSOURCE レンダリング ステートに設定された値に基づいて V の色が選択される。これらのレンダリング ステートを D3DMATERIALCOLORSOURCE 列挙型のメンバに設定して、現在のマテリアルか、頂点の色をカラー ソースとして使用する。

詳細については、「スペキュラ反射モデル」を参照すること。

スペキュラ反射モデル

スペキュラ反射をモデル化するには、光の進行方向だけでなく、視点からの視線の方向もシステムに知らせる必要がある。システムでは Phong スペキュラ反射モデルの簡易バージョンを使用する。このモデルでは、中間ベクトルを使用してスペキュラ反射強度を概算する。中間ベクトルは、光源へのベクトルと視点へのベクトルの間の中間に存在する。Microsoft Direct3D では、アプリケーションは、D3DRS_LOCALVIEWER レンダリング ステートで制御する 2 種類の方法を使用して中間ベクトルを計算できる。D3DRS_LOCALVIEWER を TRUE に設定すると、システムではライティングの方向ベクトルに加えて、カメラの位置座標と頂点の位置座標を使用して中間ベクトルを計算する。次の公式はこの計算を示す。

この公式では、norm は入力ベクトルを正規化する演算子、VC は位置座標から視点または目の位置座標へのベクトル、Ld はライティングの方向ベクトルである。

この方法で中間ベクトルを決定する場合は、計算負荷が大きくなることがある。この代わりに、D3DRS_LOCALVIEWER を FALSE に設定することもできる。この場合、z 軸の無限遠方に視点が存在するとして処理される。この設定は計算負荷は少ないが、正確さで劣る。したがって、この方法は、正射影を使用するアプリケーションに最適である。D3DRS_LOCALVIEWER を FALSE に設定した場合、Direct3D では次の公式を使用して中間ベクトルを計算する。

この公式は最初の公式に類似しているが、ベクトル VC を計算する代わりに、z 軸上の無限遠方にある視点を表すベクトル I (0, 0, -1) を使用している。

中間ベクトル H を求めた後、システムは次の公式を使用してスペキュラ反射を計算する。

この公式では、Rs はスペキュラ反射率、N は頂点法線、H は中間ベクトル、p は現在のマテリアルのスペキュラ反射強度 (マテリアルの D3DMATERIAL8 構造体の Power メンバで指定) である。ベクトル H は正規化される。ベクトル N は、D3DRS_NORMALIZENORMALS レンダリング ステートが有効になっている場合にのみ正規化される。

ディフューズ反射公式と同様、この公式の結果は -1.0 ～ 1.0 の範囲の値であり、この値は 0.0 ～ 1.0 の範囲に制限され、頂点から反射されるライティングを計算するために使用される。また、ディフューズ反射モデルと同様、その頂点におけるスペキュラ成分を求める公式にその結果が適用される。

この公式では、Sv は計算されるスペキュラ色である。A は、距離およびスポットライト エフェクトのために減衰した単一の光源からのライトである。詳細については、「距離の増加によるライトの減衰」および「スポットライト フォールオフ モデル」を参照すること。変数 Rs は以前に計算されたスペキュラ反射率、Vs は頂点のスペキュラ成分、Ls はスペキュラ ライトの色である。

D3DRS_COLORVERTEX レンダリング ステートが有効になっている場合、D3DRS_SPECULARMATERIALSOURCE レンダリング ステートの値に基づいて V のカラー ソースが選択される。このレンダリング ステートを D3DMATERIALCOLORSOURCE 列挙型のメンバに設定して、現在のマテリアルか、頂点の色成分のいずれかをカラー ソースとして使用できる。

詳細については、「ディフューズ反射モデル」を参照すること。


スポットライト フォールオフ モデル

スポットライトは、明るい内部コーンおよび外部コーンの 2 つの部分を持つ光のコーンを放射する。ライティングは、内部コーンの内側が最も明るく、外部コーンの外側にはライティングが存在しない。ライティングの強度は、この 2 つの領域の間で減衰する。一般に、このような減衰をフォールオフと呼ぶ。

頂点を照らす光の量は、頂点が内部コーンの内側にあるか、外部コーンの内側にあるかによって異なる。Microsoft® Direct3D® は、スポットライトの方向ベクトル (L) と頂点からスポットライトへのベクトル (D) の内積を計算する。この値は、2 つのベクトルがなす角度の余弦に等しく、ライティングのコーン角度と比較できる頂点位置座標を示すので、内部コーンまたは外部コーンのどちらに頂点があるかを判断するのに役立つ。次の図は、これら 2 つのベクトルの間の関係を示している。

システムは、この値をスポットライトの内部および外部コーンの角度の余弦と比較する。スポットライトの D3DLIGHT8 構造体の Theta および Phi メンバは、内部および外部コーンの角度の合計を表す。減衰は、全コーン角度にわたってではなく、ライティングの中心から頂点が離れることによって生じるため、Direct3D はコーン角度を半分に割ってから余弦を計算する。

ベクトル L と D の内積が外部コーンの角度の余弦以下の場合、頂点は外部コーンの外側に存在し、ライティングで照らされない。L と D の内積が内部コーン角度の余弦より大きい場合、頂点は内部コーンの内側に存在し、最大量のライティングで照らされる (ただし、距離の増加による減衰を考慮する)。頂点が 2 つの領域の間にある場合、Direct3D は次の公式を使用して頂点におけるライティングのフォールオフを計算する。

この公式では、If はライティングの当たる頂点におけるフォールオフ後の光の強度、a はベクトル L と D がなす角度、f は外部コーンの角度の半分の角度、q は内部コーンの角度の半分の角度、p はスポットライトのフォールオフ プロパティ (D3DLIGHT8 構造体の Falloff) である。この公式では、頂点における光の強度を定める 0.0 ～ 1.0 の値を求めて、ライトのフォールオフを示す。ライティングから頂点までの距離の係数として減衰も適用される。p 値は、D3DLIGHT8 構造体の Falloff メンバに対応し、フォールオフ カーブの形状を制御する。次の図は、Falloff 値によってフォールオフ カーブがどのように変化するかを示している。

Falloff 値が変化しても実際のライティングに与える影響はわずかであり、Falloff 値が 1.0 以外のときに形成されるフォールオフ カーブで若干のパフォーマンス低下が生じるのみである。これらの理由により、通常、この値は 1.0 に設定される。

詳細については、「距離の増加によるライトの減衰」を参照すること。


ビューポートとクリッピング

ここでは、ジオメトリ パイプラインの最後の段階のクリッピングについて説明する。説明するトピックは、次のとおりである。

  • ビューポートとは
  • ビューポート矩形
  • クリッピング ボリューム
  • ビューポートのスケーリング
  • ビューポートの使い方

Microsoft® Direct3D® では、ビューポート パラメータのセットを使用することで、デバイスにクリッピングを実装する。


ビューポートとは

概念上、ビューポートとは 3D シーンが射影される 2D 矩形である。Microsoft® Direct3D® の場合、この矩形は、レンダリング ターゲットとして使用される Direct3D サーフェス内の座標として存在する。射影トランスフォームは、ビューポートに使用される座標系に頂点をトランスフォームする。

Direct3D でビューポートを使用して、アプリケーションで次の機能を指定する。

  • レンダリングが限定されるスクリーン空間ビューポート
  • シーンがレンダリングされるレンダリング ターゲット サーフェスの深度値の範囲 (通常は 0.0 ～ 1.0)


ビューポート矩形

C++ のビューポート矩形は、D3DVIEWPORT8 構造体を使用して定義する。D3DVIEWPORT8 構造体は、IDirect3DDevice8 インターフェイスが公開する次のビューポート操作メソッドで使用される。

  • IDirect3DDevice8::GetViewport
  • IDirect3DDevice8::SetViewport

D3DVIEWPORT8 構造体には X、Y、Width、および Height の 4 つのメンバがある。これらを使用して、シーンがレンダリングされるレンダリング ターゲット サーフェス領域を定義する。これらの値は、次の図に示すように、転送先の矩形、つまりビューポート矩形に対応する。

D3DVIEWPORT8 構造体の X、Y、Width、および Height メンバに指定する値は、レンダリング ターゲット サーフェスの左上角からのスクリーン座標である。この構造体は、シーンがレンダリングされる深度範囲を示す 2 つの追加メンバ MinZ および MaxZ を定義する。

Microsoft® Direct3D® では、ビューポートのクリッピング ボリュームの範囲は、X 方向については -1.0 ～ 1.0、Y 方向については 1.0 ～ -1.0 と想定している。この値は、過去のアプリケーションで最もよく使用された設定値である。射影トランスフォームの際、クリッピングを行う前にビューポートのアスペクト比を調整することができる。このタスクについては、「射影トランスフォーム」で説明する。

注 D3DVIEWPORT8 構造体の MinZ および MaxZ メンバは、シーンがレンダリングされる深度範囲を示し、クリッピングには使用されない。ほとんどのアプリケーションでは、このメンバを 0.0 と 1.0 に設定して、深度バッファ内の深度値の全範囲にレンダリングしている。場合によっては、別の深度範囲を使用して特殊効果を得ることもできる。たとえば、ゲームのヘッドアップ ディスプレイをレンダリングする場合、両方の値を 0.0 に設定してフォアグラウンドのシーン内のオブジェクトを強制的にレンダリングしたり、両方の値を 1.0 に設定して常にバックグラウンドに存在する必要があるオブジェクトをレンダリングできる。


クリッピング ボリューム

射影行列の結果によって、射影空間でのクリッピング ボリュームが決まる。Microsoft® Direct3D® は、次のようにして、射影空間のクリッピング ボリュームを定義する。

この式では、Xc、Yc、Zc、および Wc は、射影トランスフォームの適用後の頂点座標を表す。クリッピングが有効な場合 (デフォルト設定)、これらの範囲外に x、y、または z 要素を持つ頂点がクリッピングされる。

頂点バッファを除き、アプリケーションでは、D3DRS_CLIPPING レンダリング ステートを使用してクリッピングを有効または無効にする。頂点バッファのクリッピング情報は処理中に生成される。詳細については、「頂点の処理」を参照すること。

Direct3D は頂点バッファのプリミティブのトランスフォームされた頂点をクリッピングしない。ただし、IDirect3DDevice8::ProcessVertices によるものは除く。独自のトランスフォームを実行する際に、Direct3D でクリッピングを行う必要がある場合は、頂点バッファを使用するべきではない。この場合、アプリケーションがデータをトラバースしてトランスフォームし、Direct3D が再度データをトラバースしてクリッピングした後、ドライバがデータをレンダリングするので、効率的ではない。したがって、アプリケーションがデータをトランスフォームする場合は、データのクリッピングも行うべきである。


ビューポートのスケーリング

ビューポート用の D3DVIEWPORT8 構造体の x、y、Width、および Height メンバに寸法を指定して、レンダリング ターゲット サーフェスのビューポートの位置座標および大きさを定義する。これらの値は、レンダリング ターゲット サーフェスの左上角からのスクリーン座標である。

Microsoft® Direct3D® では、ビューポートの位置座標と寸法を使用して頂点をスケーリングし、レンダリングするシーンをターゲット サーフェス上の適切な位置座標に配置する。内部的には、Direct3D は、各頂点に適用される行列にこれらの値を挿入している。

この行列は、ビューポートの寸法および指定の深度範囲に従って頂点をスケーリングし、その頂点をレンダリング ターゲット サーフェスの適切な位置座標に平行移動する。また、この行列は、y が下方に増加する左上角のスクリーン原点を反映するために y 座標を反転する。この行列を適用した後も、頂点は同次である。つまり、頂点は依然として [x,y,z,w] 頂点として存在するので、ラスタライザに送る前に頂点を非同次にトランスフォームしなければならない。これは、「ラスタ化」で説明するように、単純な除算によって行う。

注 ビューポート スケーリング行列は、頂点をスケーリングする D3DVIEWPORT8 構造体の MinZ および MaxZ メンバを組み込んで深度範囲 [MinZ, MaxZ] を合わせる。これは、これらのメンバがクリッピングに使用されていた旧リリースの Microsoft DirectX のセマンティクスとは異なる。

詳細については、「ビューポート矩形」および「クリッピング ボリューム」を参照すること。アプリケーションでは、通常、MinZ および MaxZ をそれぞれ 0.0 および 1.0 に設定して深度範囲全体へのレンダリングを実行する。ただし、別の値を設定して何らかのエフェクトを得ることもできる。両方の値を 0.0 に設定してすべてのオブジェクトを強制的にフォアグラウンドにレンダリングしたり、両方の値を 1.0 に設定してすべてのオブジェクトをバックグラウンドにレンダリングすることができる。


ビューポートの使い方

ここでは、ビューポートの操作について詳しく説明する。説明するトピックは、次のとおりである。

  • ビューポート クリッピング ボリュームの設定
  • ビューポートのクリア
  • 頂点のマニュアル トランスフォーム


ビューポート クリッピング ボリュームの設定

レンダリング デバイスに対してビューポート パラメータを設定するための条件は、ビューポートのクリッピング ボリュームを設定することだけである。このためには、クリッピング ボリュームとレンダリング ターゲット サーフェス用のクリッピング値を初期化および設定する。ビューポートは、一般には、レンダリング ターゲット サーフェスの全領域にレンダリングするように設定されるが、必ずしもそうする必要はない。

C++ でこれを実現するには、D3DVIEWPORT8 構造体のメンバを次のように設定する。

D3DVIEWPORT8 viewData = { 0, 0, width, height, 0.0f, 1.0f };

D3DVIEWPORT8 構造体に値を設定した後、IDirect3DDevice8::SetViewport メソッドを呼び出してデバイスにビューポート パラメータを適用する。次のコードは、この呼び出しを示している。

HRESULT hr;

hr = pd3dDevice->SetViewport(&viewData);
if(FAILED(hr))
    return hr;

この呼び出しが成功すると、ビューポート パラメータが設定され、次回レンダリング メソッドを呼び出したときにこのビューポート パラメータが有効になる。ビューポート パラメータは、D3DVIEWPORT8 構造体の値を更新して、再度 SetViewport を呼び出すだけで変更できる。

注 D3DVIEWPORT8 構造体の MinZ および MaxZ メンバは、シーンがレンダリングされる深度範囲を示し、クリッピングには使用されない。ほとんどのアプリケーションでは、このメンバを 0.0 と 1.0 に設定して、深度バッファ内の深度値の全範囲にレンダリングしている。場合によっては、別の深度範囲を使用して特殊効果を得ることもできる。たとえば、ゲームのヘッドアップ ディスプレイをレンダリングする場合、両方の値を 0.0 に設定してフォアグラウンドのシーン内のオブジェクトを強制的にレンダリングしたり、両方の値を 1.0 に設定して常にバックグラウンドに存在する必要があるオブジェクトをレンダリングすることができる。


ビューポートのクリア

ビューポートをクリアすると、レンダリング ターゲット サーフェス上のビューポート矩形の内容と、深度バッファ サーフェスおよびステンシル バッファ サーフェス (指定されている場合) の矩形の内容がリセットされる。通常は、新しいフレームをレンダリングする前にビューポートをクリアして、ゴミを表示せずに、グラフィックスなどのデータが新しいレンダリング オブジェクトを受け入れる準備を整える。

C++ では、ビューポートをクリアする、IDirect3DDevice8 インターフェイスの IDirect3DDevice8::Clear メソッドを使用できる。このメソッドは、クリアするサーフェス上の領域を定義する 1 つまたは複数の矩形を受け取る。レンダリングするシーンにビューポート矩形全体の移動が含まれている場合 (たとえば、対面型の遠近法を使用するゲーム)、各フレームのビューポート全体をクリアすることができる。この場合は、Count パラメータを 1 に設定し、pRects パラメータをビューポート領域全体に及ぶ単一の矩形のアドレスに設定する。より便利な方法として、pRects パラメータを NULL に設定し、Count パラメータを 0 に設定して、ビューポート矩形全体のクリアを示すことができる。

Clear メソッドはさまざまな使用方法があり、深度バッファ内のステンシル ビットをクリアすることもできる。Flags パラメータは、レンダリング ターゲットおよび関係する深度バッファまたはステンシル バッファのクリア方法を指定する 3 つのフラグを受け取る。このパラメータに D3DCLEAR_TARGET フラグを指定すると、このメソッドは Color パラメータで指定した任意の RGBA 色 (マテリアル カラーではない) を使用してビューポートをクリアする。D3DCLEAR_ZBUFFER フラグを指定すると、このメソッドは z パラメータで指定した任意の深度に従って深度バッファをクリアする。0.0 は最も近い距離を表し、1.0 は最も遠い距離を表す。D3DCLEAR_STENCIL フラグを指定すると、このメソッドはステンシル ビットを Stencil パラメータで指定した値にリセットする。指定できる値は 0 ～ 2n-1 までの整数である。ここで、n はステンシル バッファのビット深度を示す。

注 Microsoft® DirectX® 5.0 では、背景マテリアルは関連付けられたテクスチャを持つことができたので、ビューポートをクリアした後、単純な色ではなくテクスチャを表示できた。この機能はほとんど使用されることがなく、特に効果的でもなかった。DirectX 6.0 以降のインターフェイスは、テクスチャ ハンドルを受け取らなくなり、ビューポートをクリアした後にテクスチャを表示することはできない。したがって、アプリケーションでは手動で背景を描画しなければならない。その結果、レンダリング ターゲット サーフェスのビューポートをクリアする必要はほとんどなくなった。アプリケーションで深度バッファをクリアするだけで、レンダリング ターゲット サーフェス上のすべてのピクセルが上書きされる。

場合によっては、レンダリング ターゲット サーフェスと深度バッファ サーフェスの一部にのみレンダリングすることがある。クリア メソッドは、1 回の呼び出しでサーフェスの複数の領域をクリアすることもできる。これを行うには、Count パラメータにクリアする矩形の数を指定し、pRects パラメータに矩形の配列内の最初の要素のアドレスを指定する。


頂点のマニュアル トランスフォーム

Microsoft® Direct3D® アプリケーションでは、3 種類の頂点を使用できる。頂点フォーマットの詳細については、「頂点フォーマット」を参照すること。

未トランスフォーム 未ライティングの頂点
アプリケーションでライティングとトランスフォームを適用しない頂点。ライティング パラメータやトランスフォーム行列を指定しても、これらの値は Direct3D が計算する。
未トランスフォーム ライティング済みの頂点
アプリケーションでライティングは適用するが、トランスフォームは適用しない頂点。
トランスフォーム済み ライティング済みの頂点
アプリケーションでライティングとトランスフォームの両方を適用する頂点。

頂点バッファを使用して、単純な頂点タイプを複雑な頂点タイプに変えることができる。頂点バッファとは、高速なレンダリングを実行するために頂点をまとめて格納してバッチ処理するためのオブジェクトで、プロセッサ固有の機能を利用するように最適化できる。頂点トランスフォームを実行するには、IDirect3DDevice8::ProcessVertices メソッドを使用する。ProcessVertices は未トランスフォームの頂点のみ受け取るが、オプションとして頂点へのライティングの適用とクリッピングが可能である。ライティングは ProcessVertices を呼び出したときに適用されるが、クリッピングが実行されるのはレンダリングのときである。

頂点を処理した後、特別なレンダリング メソッドを使用して頂点をレンダリングしたり、頂点バッファ メモリをロックして頂点に直接アクセスすることができる。頂点バッファの使用の詳細については、「頂点バッファ」を参照すること。


ラスタ化

Microsoft® Direct3D® ジオメトリ パイプラインでの処理が終了すると、頂点はレンダリング ターゲット サーフェスのビューポートに適合するようにトランスフォーム、クリッピング、およびスケーリングされ、スクリーン上に描画するためにラスタライザに送る準備がほぼ完了したことになる。しかし、この時点ではまだ頂点は同次であり、ラスタライザは頂点を x、y、z の位置座標と同次 W の逆数 (RHW) という形で受け取ろうとする。Direct3D は x、y、z 座標を w 座標で除算することにより、この同次頂点を非同次頂点に変換する。その後、次の式に示すように、w 座標を反転することで RHW 値を算出する。

算出した値は、表示のためにラスタライザに渡される。ラスタライザは x 座標と y 座標を頂点のスクリーン座標として使用し、z バッファリングが可能な場合は z 座標を深度バッファの深度比較に使用する。RHW 値は、フォグ計算、パースペクティブ補正テクスチャ マッピング、および w バッファリング (深度バッファリングの別の方法) に使用される。


プログラム可能な頂点処理とピクセル処理

Microsoft® DirectX® 8.0 には、高度なプログラム可能性を持つ、新しいグラフィックス パイプラインが用意されている。次の図に、プログラム可能な頂点およびピクセル パイプラインの主なコンポーネントおよびデータ フローを示す。トランスフォームおよびライティング エンジンと DirectX 6.0 および 7.0 のマルチテクスチャリング モジュールは、プログラム可能なパイプラインにおいて頂点およびピクセル シェーダによって置き換えられる。

このパイプラインの最初の新しい部分は、高次プリミティブ モジュールで、ベジェおよび B スプラインなどの高次プリミティブをテッセレートする。頂点シェーダは、頂点データに対してジオメトリ演算を実行するために使用されるプログラム可能モジュールである。頂点シェーダは、標準的なトランスフォームやライティングなど、さまざまな機能を実行できる。ピクセル シェーダは、プログラム可能なピクセル プロセッサである。ピクセル シェーダは、色およびアルファ ブレンディング処理およびテクスチャ アドレッシング処理を制御する。

プログラム可能なシェーダの概要については、「プロシージャ シェーダの概要」を参照すること。

DirectX 8.0 と以前のバージョンの Microsoft Direct3D® パイプラインの比較については、「ジオメトリ パイプラインへの頂点シェーダの組み込み」を参照すること。

パイプラインのプログラム可能ではない (DirectX 6.0 および 7.0 から変更されていない) 部分については、「ビューポートとクリッピング」および「ラスタ化」を参照すること。


プロシージャ シェーダの概要

Microsoft® Direct3D® for Microsoft DirectX® 8.0 では、頂点トランスフォームおよびライティング パイプラインと、ピクセル テクスチャ ブレンディング パイプラインの動作を指定するためにプロシージャ モデルを使用する。プログラム モデル ベースの構文を使ってハードウェアの動作を指定することには、多くの利点がある。

まず、プロシージャ モデルでは、より一般的な構文を使って共通の操作を指定できる。固定機能 API では、プログラム可能とは対照的に、表現する必要がある数多くの処理についてモード、フラグなどを定義しなければならない。さらに、ハードウェアの能力が向上すると (色、テクスチャ、頂点ストリームなどが増加すると)、データ入力数と乗算された操作のトークン空間が複雑になる。一方、プログラム可能なモデルでは、適切な色および適切なテクスチャをライティング モデルの適切な部分に適用するなどの簡単な処理を、直接的な方法で実行できる。使用可能なすべてのモードを検索する必要がなく、マシンのアーキテクチャを理解し、実行する適切なアルゴリズムを指定するだけで済む。

たとえば、次のような既知の機能をサポートできる。

  • 基本的なジオメトリ トランスフォーム
  • 単純なライティング モデル
  • スキニング用の頂点ブレンディング
  • 頂点モーフィング (トゥイーニング)
  • テクスチャ トランスフォーム
  • テクスチャ生成
  • 環境マッピング

次に、プロシージャ モデルは、新しい処理を開発するための簡単なメカニズムを提供する。実行する必要のある処理の多くが、現在の API ではサポートされていないことがある。多くの場合、これはハードウェアの能力の制限によるものではなく、API の制限によるものである。一般的に、これらの処理は、固定機能の API を API の設計者が予想していない方法で無理やり使って、同じ動作を抽出するよりも、単純であり、高速である。

一般的に実装されることが予想される新しい機能には、次のようなものがある。

  • 行列パレットのスキニング。メッシュあたり 8 ～ 10 のボーンを使ったキャラクタ アニメーション。
  • 異方性ライティング。現在、参照テーブルのテクスチャのコストだけで実行できるライティング。
  • Membrane シェーダ。風船、皮膚などのシェーダ (1/cos(視点と法線の内積))。
  • Kubelka-Munk シェーダ。サーフェスを貫通するライトを考慮するシェーダ。
  • プロシージャ ジオメトリ。プロシージャ ジオメトリ (球) を使ってメッシュ合成して、皮膚の下の筋肉をシミュレートする。
  • ディスプレースメント マッピング。並べたり、反復できる波のパターンやこぶを使ってメッシュを変更する。

第 3 に、プロシージャ モデルはスケーラビリティと発展性を提供する。ハードウェアの能力は急速に発展し続けており、プログラムによる表現は非常にスケーラブルなので、同じ API によるプログラムがその発展にあわせて高層化が可能である。次の処理によって、新しい機能および能力を簡単に公開して、追加することができる。

  • 新しい命令を追加する
  • 新しいデータ入力を追加する
  • 固定機能からパイプラインのプログラム可能な部分に新しい機能を追加する

コードは、複雑な処理を表現するための最適なスケーリング プロパティを持つ表現である。さらに、プログラム可能なシェーダに追加された新しい機能について、Direct3D 内部で変更しなければならないコードは非常に少ない。

第 4 に、プロシージャ モデルは親しみやすい。ソフトウェア開発者にとっては、ハードウェアよりもプログラミングの方が理解しやすい。ソフトウェア開発者の要求を満たす API は、ハードウェアの機能をコード パラダイムにマッピングするべきである。

第 5 に、プロシージャ モデルは、フォトリアル レンダリングの遺産を受け継いでいる。ハイエンドのフォトリアル レンダリングでは、長年にわたって、プログラム可能なシェーダが使用されてきた。一般的に、この分野はパフォーマンスの制約を受けないので、プログラム可能なシェーダによって、レンダリング技術の妥協のない、究極の目標が表現される。

最後に、プロシージャ モデルによって、ハードウェアへの直接的なマッピングが可能になる。最新の 3D ハードウェアは、少なくとも頂点処理ステージでは、実際にはかなりプログラム可能である。API によるプログラム可能性によって、アプリケーションが直接このハードウェアにマッピングできるようにする。これにより、要件に応じてハードウェア リソースを管理できる。実行できるレジスタや命令が制限されている場合、そのすべての機能を持つ固定機能の実装を個別に有効にすることは困難である。共有リソースを必要とする多くの機能を一度に有効にすると、予期しない方法で動作を停止する場合がある。プログラム可能な API モデルでは、DirectX の伝統に従い、アプリケーション開発者が直接ハードウェアを操作し、このような制限を意識せずに済むようにして、この問題を回避している。


ジオメトリ パイプラインへの頂点シェーダの組み込み

処理中に、プログラム可能な頂点シェーダは、Microsoft® Direct3D® ジオメトリ パイプラインのトランスフォームおよびライティング モジュールを置き換える。実質的に、トランスフォームおよびライティング処理に関するステート情報は無視される。ただし、頂点シェーダが無効で、固定機能による処理に戻った場合は、現在のステート設定がすべて適用される。

高次プリミティブのテッセレーションはすべて、頂点シェーダの実行前に行う必要がある。シェーダの処理の後にサーフェス テッセレーションを実行する実装環境では、アプリケーションおよびシェーダ コードにわからない方法で実行しなければならない。セマンティクス情報は、通常、シェーダの前には提供されないので、特殊なトークンを使用して、ほかのすべてのコンポーネントが相対的に補間されるベース位置を表す入力ストリーム コンポーネントを識別する。補間できないデータ チャネルはサポートされない。

出力では、頂点シェーダは同次クリップ空間に頂点の位置座標を生成しなければならない。生成できる追加データには、テクスチャ座標、色、フォグ係数などがある。

標準的なグラフィックス パイプラインは、次のタスクを含めて、シェーダごとに頂点出力を処理する。

  • プリミティブ アセンブリ
  • 視錐台およびクリップ面に対するクリッピング
  • 同次除算
  • ビューポートのスケーリング
  • 背面およびビューポートのカリング
  • 三角形のセットアップ
  • ラスタ化

DirectX 8.0 頂点シェーダのクリッピング空間は、DirectX 7.0 および DirectX 8.0 の固定機能による頂点処理と同じである。詳細については、「クリッピング ボリューム」を参照すること。

プログラム可能なジオメトリは、Direct3D アプリケーション プログラミング インターフェイス (API) 内のモードである。有効になっている場合、頂点パイプラインを部分的に置き換える。無効になっている場合、API は DirectX 6.0 および 7.0 での動作と同じ通常の制御を行う。頂点シェーダの実行は、内部の Direct3D ステートを変更せず、Direct3D ステートはシェーダでは使用できない。

pFunction パラメータを NULL にした IDirect3DDevice8::CreateVertexShader の呼び出しは、固定機能によるパイプラインのシェーダを作成するために使用される。pFunction が NULL ではない場合は、シェーダはプログラム可能になる。IDirect3DDevice8::SetVertexShader の呼び出しは、現在のアクティブ シェーダを設定し、レンダリング パイプラインがプログラムによる頂点処理と固定機能頂点処理のいずれを使用するかを定義する。


頂点プロセッサへの頂点データの提示

次のいずれかのフォーマットを使用して、頂点データを頂点プロセッサに提示できる。

  • 従来の FVF フォーマット
  • プログラム可能なストリーム モデル

注 選択する頂点データ形式は、使用される頂点処理方法 (固定機能とプログラム可能) とは独立しており、いずれの組み合わせも可能である。たとえば、固定機能トランスフォームとライティング パイプラインでストリームを使用し、プログラム可能な頂点シェーダで FVF 頂点を使用できる。


従来の FVF フォーマット

従来の FVF フォーマットを使用するには、次のサンプル コードに示すように、IDirect3DDevice8::SetVertexShader メソッドを呼び出すときに、ハンドルではなく FVF を使用する。

g_d3dDevice->SetVertexShader( CUSTOM_FVF );

ここでは、従来の FVF フォーマットのタイプについて説明する。

  • Vertex 型レガシ タイプ
  • LVertex 型レガシ タイプ
  • TLVertex 型レガシ タイプ


Vertex 型レガシ タイプ

ここでは、位置、法線、およびテクスチャ座標を持つ頂点を初期化および使用するために必要なステップについて説明する。

最初のステップでは、次のサンプル コードに示すように、カスタム頂点タイプと FVF を定義する。

struct Vertex
{
    FLOAT x, y, z;
    FLOAT nx, ny, nz;
    FLOAT tu, tv;
};

const DWORD VertexFVF = ( D3DFVF_XYZ | D3DFVF_NORMAL | D3DFVF_TEX1 );

次のステップでは、IDirect3DDevice8::CreateVertexBuffer メソッドを呼び出して、4 つの頂点を収めるのに十分な領域を確保した頂点バッファを作成する。これを、次のサンプル コードに示す。

g_d3dDevice->CreateVertexBuffer(
                 4*sizeof(Vertex), VertexFVF,
                 D3DUSAGE_WRITEONLY,
                 D3DPOOL_DEFAULT, &pBigSquareVB);

次のステップでは、各頂点の値を処理する。これを、次のサンプル コードに示す。

Vertex * v;
pBigSquareVB->Lock( 0, 0, (BYTE**)&v, 0 );

v[0].x  = 0.0f;  v[0].y  = 10.0;  v[0].z  = 10.0f;
v[0].nx = 0.0f;  v[0].ny = 1.0f;  v[0].nz = 0.0f;
v[0].tu = 0.0f;  v[0].tv = 0.0f;

v[1].x  = 0.0f;  v[1].y  = 0.0f;  v[1].z  = 10.0f;
v[1].nx = 0.0f;  v[1].ny = 1.0f;  v[1].nz = 0.0f;
v[1].tu = 0.0f;  v[1].tv = 0.0f;

v[2].x  = 10.0f; v[2].y  = 10.0f; v[2].z  = 10.0f;
v[2].nx = 0.0f;  v[2].ny = 1.0f;  v[2].nz = 0.0f;
v[2].tu = 0.0f;  v[2].tv = 0.0f;

v[3].x  = 0.0f; v[3].y  = 10.0f;  v[3].z = 10.0f;
v[3].nx = 0.0f; v[3].ny = 1.0f;   v[3].nz = 0.0f;
v[3].tu = 0.0f; v[3].tv = 0.0f;

pBigSquareVB->Unlock();

頂点バッファは初期化され、レンダリングする準備ができている。次のサンプル コードは、レガシ FVF を使用して正方形を描画する方法を示している。

g_d3dDevice->SetVertexShader( VertexFVF );
g_d3dDevice->SetStreamSource( 0, pBigSquareVB, 4*sizeof(Vertex) );
g_d3dDevice->DrawPrimitive( D3DPT_TRIANGLESTRIP, 0 ,2);

FVF を IDirect3DDevice8::SetVertexShader メソッドに渡して、レガシ FVF が使用されること、およびストリーム 0 だけが有効なストリームであることを Direct3D に指示する。


LVertex 型レガシ タイプ

ここでは、位置、ディフューズ色、スペキュラ色、およびテクスチャ座標を持つ頂点を初期化および使用するために必要なステップについて説明する。

最初のステップでは、次のサンプル コードに示すように、カスタム頂点タイプと FVF を定義する。

struct LVertex
{
    FLOAT    x, y, z;
    D3DCOLOR specular, diffuse;
    FLOAT    tu, tv;
};

const DWORD VertexFVF = (D3DFVF_XYZ | D3DFVF_DIFFUSE |
                         D3DFVF_SPECULAR | D3DFVF_TEX1 );

次のステップでは、IDirect3DDevice8::CreateVertexBuffer メソッドを呼び出して、4 つの頂点を収めるのに十分な領域を確保した頂点バッファを作成する。これを、次のサンプル コードに示す。

g_d3dDevice->CreateVertexBuffer(
                 4*sizeof(LVertex), VertexFVF,
                 D3DUSAGE_WRITEONLY,
                 D3DPOOL_DEFAULT, &pBigSquareVB);

次のステップでは、各頂点の値を処理する。これを、次のサンプル コードに示す。

LVertex * v;
pBigSquareVB->Lock( 0, 0, (BYTE**)&v, 0 );

v[0].x  = 0.0f;  v[0].y  = 10.0;  v[0].z  = 10.0f;
v[0].diffuse  = 0xffff0000;
v[0].specular = 0xff00ff00;
v[0].tu = 0.0f;  v[0].tv = 0.0f;

v[1].x  = 0.0f;  v[1].y  = 0.0f;  v[1].z  = 10.0f;
v[1].diffuse  = 0xff00ff00;
v[1].specular = 0xff00ffff;
v[1].tu = 0.0f;  v[1].tv = 0.0f;

v[2].x  = 10.0f; v[2].y  = 10.0f; v[2].z  = 10.0f;
v[2].diffuse  = 0xffff00ff;
v[2].specular = 0xff000000;
v[2].tu = 0.0f;  v[2].tv = 0.0f;

v[3].x  = 0.0f; v[3].y  = 10.0f;  v[3].z = 10.0f;
v[3].diffuse  = 0xffffff00;
v[3].specular = 0xffff0000;
v[3].tu = 0.0f; v[3].tv = 0.0f;

pBigSquareVB->Unlock();

頂点バッファは初期化され、レンダリングする準備ができている。次のサンプル コードは、レガシ FVF を使用して正方形を描画する方法を示している。

g_d3dDevice->SetVertexShader( VertexFVF );
g_d3dDevice->SetStreamSource( 0, pBigSquareVB, 4*sizeof(LVertex) );
g_d3dDevice->DrawPrimitive( D3DPT_TRIANGLESTRIP, 0 ,2);

FVF を IDirect3DDevice8::SetVertexShader メソッドに渡して、レガシ FVF が使用されること、およびストリーム 0 だけが有効なストリームであることを Direct3D に指示する。


TLVertex 型レガシ タイプ

ここでは、トランスフォーム済み位置、ディフューズ色、スペキュラ色、およびテクスチャ座標を持つ頂点を初期化および使用するために必要なステップについて説明する。

最初のステップでは、次のサンプル コードに示すように、カスタム頂点タイプと FVF を定義する。

struct TLVertex
{
    FLOAT    x, y, z, rhw;
    D3DCOLOR specular, diffuse;
    FLOAT    tu, tv;
};

const DWORD VertexFVF = (D3DFVF_XYZRHW | D3DFVF_DIFFUSE |
                         D3DFVF_SPECULAR | D3DFVF_TEX1 );

次のステップでは、IDirect3DDevice8::CreateVertexBuffer メソッドを呼び出して、4 つの頂点を収めるのに十分な領域を確保した頂点バッファを作成する。これを、次のサンプル コードに示す。

g_d3dDevice->CreateVertexBuffer(
                 4*sizeof(TLVertex), VertexFVF,
                 D3DUSAGE_WRITEONLY,
                 D3DPOOL_DEFAULT, &pBigSquareVB);

次のステップでは、各頂点の値を処理する。これを、次のサンプル コードに示す。

TLVertex * v;
pBigSquareVB->Lock( 0, 0, (BYTE**)&v, 0 );

v[0].x  = 0.0f;  v[0].y  = 10.0;  v[0].z  = 10.0f; v[0].rhw = 1.0f;
v[0].diffuse  = 0xffff0000;
v[0].specular = 0xff00ff00;
v[0].tu = 0.0f;  v[0].tv = 0.0f;

v[1].x  = 0.0f;  v[1].y  = 0.0f;  v[1].z  = 10.0f; v[1].rhw = 1.0f;
v[1].diffuse  = 0xff00ff00;
v[1].specular = 0xff00ffff;
v[1].tu = 0.0f;  v[1].tv = 0.0f;

v[2].x  = 10.0f; v[2].y  = 10.0f; v[2].z  = 10.0f; v[2].rhw = 1.0f;
v[2].diffuse  = 0xffff00ff;
v[2].specular = 0xff000000;
v[2].tu = 0.0f;  v[2].tv = 0.0f;

v[3].x  = 0.0f; v[3].y  = 10.0f;  v[3].z = 10.0f; v[3].rhw = 1.0f;
v[3].diffuse  = 0xffffff00;
v[3].specular = 0xffff0000;
v[3].tu = 0.0f; v[3].tv = 0.0f;

pBigSquareVB->Unlock();

頂点バッファは初期化され、レンダリングする準備ができている。次のサンプル コードは、レガシ FVF を使用して正方形を描画する方法を示している。

g_d3dDevice->SetVertexShader( VertexFVF );
g_d3dDevice->SetStreamSource( 0, pBigSquareVB, 4*sizeof(TLVertex) );
g_d3dDevice->DrawPrimitive( D3DPT_TRIANGLESTRIP, 0 ,2);

FVF を IDirect3DDevice8::SetVertexShader メソッドに渡して、レガシ FVF が使用されること、およびストリーム 0 だけが有効なストリームであることを Direct3D に指示する。


プログラム可能なストリーム モデル

ここでは、プログラム可能なストリーム モデルで使用できるシェーダについて説明する。

  • カラー頂点シェーダ
  • シングルテクスチャ シェーダ
  • マルチテクスチャ シェーダ


カラー頂点シェーダ

ここでは、位置とディフィーズ色を持つ単純な頂点シェーダを初期化および使用するために必要なステップについて説明する。

最初のステップでは、位置と色を格納する構造体を宣言する。これを、次のサンプル コードに示す。

struct XYZBuff
{
    FLOAT x, y, z;
    D3DCOLOR color;
};

struct ColBuf
{
    D3DCOLOR color;
};

#define XYZBUFF (D3DFVF_XYZ)
#define COLBUFF (D3DFVF_DIFFUSE)

次のステップでは、頂点シェーダ宣言を作成する。これを、次のサンプル コードに示す。

DWORD decl[] =
{
    D3DVSD_STREAM(0),
    D3DVSD_REG( D3DVSDE_POSITION, D3DVSDT_FLOAT3 ),
    D3DVSD_STREAM(1),
    D3DVSD_REG( D3DVSDE_DIFFUSE, D3DVSDT_D3DCOLOR),
    D3DVSD_END()
};

次のステップでは、IDirect3DDevice8::CreateVertexShader メソッドを呼び出して頂点シェーダを作成する。

g_d3dDevice->CreateVertexShader( decl, NULL, &vShader, 0);

CreateVertexShader の第 2 パラメータに NULL を渡して、この頂点シェーダで固定機能パイプラインを使用することを Direct3D に指示する。

頂点バッファと頂点シェーダは、作成後はいつでも使用できる。次のサンプル コードは、頂点シェーダの設定方法、ストリーム ソースの設定方法、および新しい頂点シェーダを使用する三角形リストの描画方法を示している。

g_d3dDevice->SetVertexShader( &vShader );
g_d3dDevice->SetStreamSource( 0, xyzbuf, 4 * sizeof(FLOAT));
g_d3dDevice->SetStreamSource( 1, colbuf, 2 * sizeof(FLOAT));
g_d3dDevice->SetIndices( pIB, 0 );
g_d3dDevice->DrawIndexedPrimitive( D3DPT_TRIANGLELIST, 0, max - min + 1, 0, count / 3 );


シングルテクスチャ シェーダ

ここでは、位置とテクスチャ座標を持つ単純な頂点シェーダを初期化および使用するために必要なステップについて説明する。

最初のステップでは、位置とテクスチャ座標を格納する構造体を宣言する。これを、次のサンプル コードに示す。

struct XYZBuff
{
    D3DVALUE x, y, z;
};

struct TEX0Buff
{
    D3DVALUE tu, tv;
};

#define XYZBUFF  (D3DFVF_XYZ)
#define TEX0BUFF (D3DFVF_TEX1)

次のステップでは、頂点シェーダ宣言を作成する。これを、次のサンプル コードに示す。

DWORD decl[] =
{
    D3DVSD_STREAM(0),
    D3DVSD_REG( D3DVSDE_POSITION, D3DVSDT_FLOAT3 ),
    D3DVSD_STREAM(1),
    D3DVSD_REG( D3DVSDE_TEXCOORD0, D3DVSDT_FLOAT2 ),
    D3DVSD_END()
};

次のステップでは、IDirect3DDevice8::CreateVertexShader メソッドを呼び出して頂点シェーダを作成する。

g_d3dDevice->CreateVertexShader( decl, NULL, &vShader, 0);

CreateVertexShader の第 2 パラメータに NULL を渡して、この頂点シェーダで固定機能パイプラインを使用することを Direct3D に指示する。

頂点バッファと頂点シェーダは、作成後はいつでも使用できる。次のサンプル コードは、頂点シェーダの設定方法、ストリーム ソースの設定方法、および新しい頂点シェーダを使用する三角形リストの描画方法を示している。

g_d3dDevice->SetVertexShader( &vShader );
g_d3dDevice->SetStreamSource( 0, xyzbuf, 4 * sizeof(FLOAT));
g_d3dDevice->SetStreamSource( 1, tex0buf, 2 * sizeof(FLOAT));
g_d3dDevice->SetIndices( pIB, 0 );
g_d3dDevice->DrawIndexedPrimitive( D3DPT_TRIANGLELIST, 0, max - min + 1, 0, count / 3 );


マルチテクスチャ シェーダ

ここでは、位置と複数のテクスチャ座標を持つ単純な頂点シェーダを初期化および使用するために必要なステップについて説明する。

最初のステップでは、位置と色を格納する構造体を宣言する。これを、次のサンプル コードに示す。

struct XYZBuff
{
    D3DVALUE x, y, z;
};

struct Tex0Buff
{
    D3DVALUE tu, tv;
};

struct Tex1Buff
{
    D3DVALUE tu2, tv2;
};

#define XYZBUFF (D3DFVF_XYZ)
#define TEX0BUFF (D3DFVF_TEX1)
#define TEX1BUFF (D3DFVF_TEX1)

次のステップでは、頂点シェーダ宣言を作成する。これを、次のサンプル コードに示す。

DWORD decl[] =
{
    D3DVSD_STREAM(0),
    D3DVSD_REG( D3DVSDE_POSITION, D3DVSDT_FLOAT3 ),
    D3DVSD_STREAM(1),
    D3DVSD_REG( D3DVSDE_TEXCOORD0, D3DVSDT_FLOAT2),
    D3DVSD_STREAM(2),
    D3DVSD_REG( D3DVSDE_TEXCOORD1, D3DVSDT_FLOAT2),
    D3DVSD_END()
};

次のステップでは、IDirect3DDevice8::CreateVertexShader メソッドを呼び出して頂点シェーダを作成する。

g_d3dDevice->CreateVertexShader( decl, NULL, &vShader, 0);

CreateVertexShader の第 2 パラメータに NULL を渡して、この頂点シェーダで固定機能パイプラインを使用することを Direct3D に指示する。

頂点バッファと頂点シェーダは、作成後はいつでも使用できる。次のサンプル コードは、頂点シェーダの設定方法、ストリーム ソースの設定方法、および新しい頂点シェーダを使用する三角形リストの描画方法を示している。

g_d3dDevice->SetVertexShader( &vShader );
g_d3dDevice->SetStreamSource( 0, xyzbuf, 4 * sizeof(FLOAT));
g_d3dDevice->SetStreamSource( 1, tex0buf, 2 * sizeof(FLOAT));
g_d3dDevice->SetStreamSource( 2, tex1buf, 2 * sizeof(FLOAT));
g_d3dDevice->SetIndices( pIB, 0 );
g_d3dDevice->DrawIndexedPrimitive( D3DPT_TRIANGLELIST, 0, max - min + 1, 0, count / 3 );


DirectX Graphics の使い方

ここでは、アプリケーション開発における Microsoft® Direct3D® および Direct3DX のAPI の使用方法について説明する。

説明するトピックは、次のとおりである。

  • Direct3D オブジェクト
  • Direct3D デバイス
  • Direct3D リソース
  • サーフェス
  • ライト
  • マテリアル
  • 頂点フォーマット
  • テクスチャ
  • 深度バッファ
  • ステンシル バッファ
  • 頂点バッファ
  • インデックス バッファ
  • テクノロジと特殊効果

概要については、「DirectX Graphics の基礎知識」を参照すること。

データ フローの一般的メカニズムや構成の詳細については、「DirectX Graphics について」を参照すること。

プログラム可能なシェーダなど高度な機能については、「DirectX Graphics の高度なトピック｣を参照すること。


Direct3D オブジェクト

ここでは、Microsoft® Direct3D® オブジェクトについて説明する。

  • Direct3D オブジェクトとは
  • Direct3D へのアクセス


Direct3D オブジェクトとは

Microsoft® Direct3D® は、COM オブジェクトとインターフェイスによって実装される。C++ で記述されたアプリケーションからはこれらのインターフェイスとオブジェクトに直接アクセスできるが、Microsoft Visual Basic® アプリケーションの場合は、Visual Basic アプリケーションから DirectX ランタイムにデータを配置する、Microsoft DirectX® for Visual Basic クラスとして現れるコード レイヤとの相互処理を行う。

Direct3D オブジェクトは、アプリケーションで最初に作成され、最後に解放されるオブジェクトである。Direct3D デバイスの能力を列挙および取得する関数には、Direct3D オブジェクトを介してアクセスできる。したがって、アプリケーションはデバイスを作成しないでもデバイスの選択が可能である。


Direct3D へのアクセス

C++ で記述された Microsoft® Direct3D® アプリケーションでは、起動時に、Direct3D の機能を利用するために IDirect3D8 インターフェイスへのポインタを取得しなければならない。

次のコードは、Direct3DCreate8 関数による Direct3D インターフェイスへのポインタの取得方法を示している。

LPDIRECT3D8 g_pD3D = NULL;

    if( NULL == (g_pD3D = Direct3DCreate8(D3D_SDK_VERSION)))
        return E_FAIL;

Direct3DDevice オブジェクトから、デバイスを作成した Direct3D オブジェクトに移動するには、IDirect3DDevice8::GetDirect3D メソッドを使用する。


Direct3D デバイス

ここでは、Microsoft® Direct3D® デバイスの概要について説明する。説明するトピックは、次のとおりである。

  • Direct3D デバイスとは
  • デバイスの種類
  • デバイスでサポートされるプリミティブの種類
  • デバイスの使い方
  • デバイス ステート
  • 消失したデバイス


Direct3D デバイスとは

Microsoft® Direct3D® デバイスとは、Direct3D のレンダリング コンポーネントである。これはレンダリング ステートをカプセル化して保存する。さらに、Direct3D デバイスは、トランスフォーム & ライティング処理を実行し、サーフェスに画像をラスタライズする。次の図に示すように、Direct3D デバイスのアーキテクチャは、トランスフォーム、ライティング、およびラスタ化モジュールから構成される。

Direct3D デバイスのトランスフォーム & ライティング モジュールを使用せずに、アプリケーション独自のトランスフォーム & ライティング モデルを使用することもできる。詳細については、「頂点シェーダ」を参照すること。


デバイスの種類

ここでは、Microsoft® Direct3D® デバイス、およびデバイスの各タイプについて説明する。説明するトピックは、次のとおりである。

  • デバイスの種類について
  • HAL デバイス
  • リファレンス デバイス
  • プラグ可能なソフトウェア デバイス
  • デバイスの動作


デバイスの種類について

Microsoft® Direct3D® が現在サポートしている Direct3D の主要デバイスは、主に 3 種類に分けられる。ハードウェア アクセラレーションによるラスタ化とシェーディング、ハードウェアとソフトウェア両方による頂点処理を行う、ハードウェア アブストラクション レイヤ (HAL) デバイス、リファレンス デバイス、そしてソフトウェアによるラスタ化を提供するプラグ可能なソフトウェア デバイスの 3 種類である。

これら 3 つのデバイスは、3 つの別個のドライバと見なすことができる。ソフトウェア デバイスとリファレンス デバイスは、ソフトウェア ドライバで表され、HAL デバイスは、ハードウェア ドライバで表される。これらのデバイスを有効活用する最も一般的な方法は、HAL デバイスを出荷用アプリケーションに使用し、リファレンス デバイスを機能テストに使用することである。このようなリファレンス ドライバは、サード パーティによって提供され、特定のデバイス (たとえば、まだリリースされていない開発中のハードウェア) をエミュレートする。

アプリケーションが作成する Direct3D デバイスは、アプリケーションが動作するハードウェアの機能に対応していなければならない。Direct3D では、コンピュータにインストールされている 3D ハードウェアにアクセスするか、ソフトウェアで 3D ハードウェア機能をエミュレートするかのいずれかの方法で、レンダリング機能を利用する。したがって、Direct3D は、ハードウェア アクセス用およびソフトウェア エミュレーション用の両方のデバイスを備えている。

ハードウェア アクセラレーション デバイスは、ソフトウェア エミュレーション デバイスよりもさらに高いパフォーマンスを実現する。HAL デバイスは、Direct3D をサポートするすべてのグラフィック アダプタで使用できる。ほとんどの場合、アプリケーションが対象とするのは、何らかのハードウェア アクセラレーションを備え、ソフトウェア エミュレーションによってローエンド コンピュータの機能を使用できるコンピュータである。

リファレンス デバイスを除き、ソフトウェア デバイスは、常にハードウェア デバイスと同じ機能をサポートしているわけではない。アプリケーションは、デバイス機能を調べて、サポートされている機能を確認する必要がある。

Microsoft DirectX® 8.0 によって提供されるソフトウェア デバイスおよびリファレンス デバイスの動作は HAL デバイスの動作と同じであり、HAL デバイス用に作成されたアプリケーション コードは、修正なしでそのまま使用できる。提供されるソフトウェア デバイスおよびリファレンス デバイスの動作は HAL デバイスの動作と同じであるが、デバイスの能力は異なる。また、特定のソフトウェア デバイスでは、わずかな機能セットしか実装できないこともあるので注意すること。


HAL デバイス

プライマリ デバイスはハードウェア アブストラクション レイヤ (HAL) デバイスであり、このデバイスは、ハードウェア アクセラレーションによるラスタ化と、ソフトウェアおよびハードウェアの両方による頂点処理をサポートする。アプリケーションが動作するコンピュータに、Microsoft® Direct3D® をサポートするディスプレイ アダプタが装着されている場合、アプリケーションではそのアダプタを 3D 処理に使用する必要がある。Direct3D の HAL デバイスは、ハードウェアのトランスフォーム、ライティング、およびラスタ化モジュールをすべてまたはその一部を実装する。

アプリケーションは、3D カードに直接アクセスするわけではない。アプリケーションは、Direct3D 関数およびメソッドを呼び出す。Direct3D は、HAL を介してハードウェアにアクセスする。アプリケーションが動作するコンピュータが HAL に対応している場合は、HAL デバイスを使用することで最高のパフォーマンスを実現できる。

C++ で HAL デバイスを作成するには、IDirect3D8::CreateDevice メソッドを呼び出し、デバイス タイプとして定数 D3DDEVTYPE_HAL を渡す。詳細については、「デバイスの作成」を参照すること。

注 : ハードウェア デバイスは 8 ビットのレンダリング ターゲット サーフェスにはレンダリングできない。


リファレンス デバイス

Microsoft® Direct3D® は、リファレンス デバイスまたはリファレンス ラスタライザと呼ばれる追加デバイスをサポートしている。ソフトウェア デバイスとは異なり、リファレンス ラスタライザはあらゆる Direct3D 機能をサポートしている。これらの機能は処理速度よりも精度を重視してソフトウェアに実装されているため、結果が得られるまでには時間がかかる。リファレンス ラスタライザは、利用可能な場合は特別な CPU 命令を十分に利用するが、市販アプリケーションは対象としていない。リファレンス ラスタライザは、機能テストやデモンストレーションにのみ使用する。

C++ でリファレンス デバイスを作成するには、IDirect3D8::CreateDevice メソッドを呼び出し、デバイス タイプとして定数 D3DDEVTYPE_REF を渡す。詳細については、「デバイスの作成」を参照すること。


プラグ可能なソフトウェア デバイス

ユーザーのコンピュータが 3D 操作用の特別なハードウェア アクセラレーションを備えていない場合、アプリケーションはソフトウェアで 3D ハードウェアをエミュレートできる。ソフトウェア ラスタ化デバイスは、ソフトウェアで カラー 3D ハードウェアの機能をエミュレートする。ソフトウェア デバイスはソフトウェア エミュレーションなので、ハードウェア アブストラクション レイヤ (HAL) デバイスよりも実行速度が遅い。ただし、ソフトウェア デバイスは、ユーザーの CPU でサポートされている特別な命令を利用してパフォーマンスを向上させる。サポートされる命令セットには、いくつかの AMD プロセッサの AMD 3D-Now! 命令セットや、多くの Intel プロセッサでサポートされる MMX 命令セットなどがある。Microsoft® Direct3D では、3D-Now! 命令セットを使用してトランスフォーム & ライティング処理を高速化し、MMX 命令セットを使用してラスタ化を高速化する。

Direct3D® のソフトウェア ラスタ化は、プラグ可能なソフトウェア デバイスによって提供される。このデバイスは、Direct3D インターフェイスを介して各種ソフトウェア ラスタライザへのアクセスを可能にする。ソフトウェア デバイスは、アプリケーションによってロードされて、Direct3D オブジェクトに登録される。この時点で、ソフトウェア デバイスを使ってレンダリングを実行する Direct3DDevice オブジェクトを作成できる。

Direct3D ソフトウェア デバイスは、ハードウェア デバイス ドライバ インタフェース (DDI) に類似するインターフェイスを介して Direct3D と通信する。

Direct3D DDK には、プラグ可能なソフトウェア デバイスを開発するためのドキュメントとヘッダーが用意されている。


デバイスの動作

Microsoft® Direct3D® では、デバイスの種類に加えて、デバイスの動作も指定できる。IDirect3D8::CreateDevice メソッドでは、1 つまたは複数の動作フラグを組み合わせて Direct3D デバイスのグローバルな動作を制御できる。これらの動作によって Direct3D のランタイム部分で保持されるものと保持されないものが指定され、デバイスの種類によって使用するドライバが指定される。デバイス動作の組み合わせの中には有効でないものもあるが、すべてのデバイスの種類ですべてのデバイスの動作を使用できる。たとえば、D3DCREATE_PUREDEVICE で作成されたデバイスに D3DDEVTYPE_SW を指定できる。


デバイスでサポートされるプリミティブの種類

Microsoft® Direct3D® デバイスでは、以下のタイプのプリミティブを作成および操作できる。

  • ポイント リスト
  • 線リスト
  • 線ストリップ
  • 三角形リスト
  • 三角形ストリップ
  • 三角形ファン

C++ アプリケーションのプリミティブは、IDirect3DDevice8 インターフェイスのレンダリング メソッドを使用してレンダリングできる。詳細については、「レンダリング」を参照すること。

インデックス付きプリミティブ レンダリング メソッドを使用して、ポイント リストをレンダリングすることはできない。


ポイント リスト

ポイント リストとは、個々のポイントとしてレンダリングされる頂点の集合である。アプリケーションでは、星のフィールドまたはポリゴンのサーフェス上の点線に、3D シーンのポイント リストを使用できる。

次の図は、レンダリングされるポイント リストを示している。

ポイント リストにはマテリアルとテクスチャを適用できる。マテリアルまたはテクスチャの色は、描画されたポイントでのみ表示され、ポイントとポイントの間には表示されない。

次のコードは、ポイント リストに対して頂点を作成する方法を示している。

struct CUSTOMVERTEX
{
    float x,y,z;
};

CUSTOMVERTEX Vertices[] =
{
    {-5.0, -5.0, 0.0},
    { 0.0,  5.0, 0.0},
    { 5.0, -5.0, 0.0},
    {10.0,  5.0, 0.0},
    {15.0, -5.0, 0.0},
    {20.0,  5.0, 0.0}
};

次のコードは、IDirect3DDevice8::DrawPrimitive を使用して、ポイント リストをレンダリングする方法を示している。

//
// d3dDevice は、IDirect3DDevice8 インターフェイスへの
// 有効なポインタであると仮定している。
//
d3dDevice->DrawPrimitive( D3DPT_POINTLIST, 0, 6 );


線リスト

線リストとは、個々の直線の線分のリストである。線リストは、3D シーンでみぞれや大雨を表現するときなどに便利である。アプリケーションでは、頂点の配列に値を設定することで線リストを作成する。線リストの頂点の数は、2 以上の偶数でなければならない。

次の図は、レンダリングされる線リストを示している。

線リストにはマテリアルとテクスチャを適用できる。マテリアルまたはテクスチャの色は、描画された線に沿ってのみ表示され、線と線の間には表示されない。

次のコードは、線リストに対して頂点を作成する方法を示している。

struct CUSTOMVERTEX
{
    float x,y,z;
};

CUSTOMVERTEX Vertices[] =
{
    {-5.0, -5.0, 0.0},
    { 0.0,  5.0, 0.0},
    { 5.0, -5.0, 0.0},
    {10.0,  5.0, 0.0},
    {15.0, -5.0, 0.0},
    {20.0,  5.0, 0.0}
};

次のコードは、IDirect3DDevice8::DrawPrimitive を使用して、線リストをレンダリングする方法を示している。

//
// d3dDevice は、IDirect3DDevice8 インターフェイスへの
// 有効なポインタであると仮定している。
//
d3dDevice->DrawPrimitive( D3DPT_LINELIST, 0, 3 );


線ストリップ

線ストリップとは、線分どうしを結合したものから構成されるプリミティブである。線ストリップを使用して、閉じていないポリゴンを作成できる。閉じたポリゴンとは、最後の頂点が最初の頂点と線分で結合されているポリゴンである。線ストリップに基づいてポリゴンを作成する場合、そのポリゴンの頂点が同一平面上にあるとは限らない。

次の図は、レンダリングされる線ストリップを示している。

次のコードは、線ストリップに対して頂点を作成する方法を示している。

struct CUSTOMVERTEX
{
    float x,y,z;
};

CUSTOMVERTEX Vertices[] =
{
    {-5.0, -5.0, 0.0},
    { 0.0,  5.0, 0.0},
    { 5.0, -5.0, 0.0},
    {10.0,  5.0, 0.0},
    {15.0, -5.0, 0.0},
    {20.0,  5.0, 0.0}
};

次のコードは、IDirect3DDevice8::DrawPrimitive を使用して、線ストリップをレンダリングする方法を示している。

//
// d3dDevice は、IDirect3DDevice8 インターフェイスへの
// 有効なポインタであると仮定している。
//
d3dDevice->DrawPrimitive( D3DPT_LINESTRIP, 0, 5 );


三角形リスト

三角形リストとは、個々の三角形のリストである。三角形は互いに隣接していても離れていてもよい。三角形リストには、少なくとも 3 つの頂点が必要である。頂点の総数は 3 の倍数でなければならない。

独立した要素から構成されるオブジェクトの作成には、三角形リストを使用する。たとえば、3D ゲームで電磁力界壁を作成するには、単独の小さな三角形を多数集めたリストを指定する。次に、この三角形リストにマテリアルやテクスチャを適用して、光を発しているように見せる。壁の三角形それぞれが輝いて見えるようになる。プレーヤーが電磁力界とはこう見えるだろうと期待するとおりに、壁の背後のシーンが三角形の間の隙間を通して部分的に見えるようになる。

また、三角形リストは、グーロー シェーディングで陰影を付けた、鋭いエッジを持つプリミティブを作成するときに便利である。「面法線ベクトルと頂点法線ベクトル」を参照すること。

次の図は、レンダリングされる三角形リストを示している。

次のコードは、三角形リストに対して頂点を作成する方法を示している。

struct CUSTOMVERTEX
{
    float x,y,z;
};

CUSTOMVERTEX Vertices[] =
{
    {-5.0, -5.0, 0.0},
    { 0.0,  5.0, 0.0},
    { 5.0, -5.0, 0.0},
    {10.0,  5.0, 0.0},
    {15.0, -5.0, 0.0},
    {20.0,  5.0, 0.0}

};

次のコードは、IDirect3DDevice8::DrawPrimitive を使用して、三角形リストをレンダリングする方法を示している。

//
// d3dDevice は、IDirect3DDevice8 インターフェイスへの
// 有効なポインタであると仮定している。
//
d3dDevice->DrawPrimitive( D3DPT_TRIANGLELIST, 0, 2 );


三角形ストリップ

三角形ストリップとは、一連の結合された三角形である。三角形は結合されているため、各三角形に対して 3 つの頂点すべてをアプリケーションで繰り返し指定する必要はない。たとえば、次の三角形ストリップを定義する場合、必要となるのは 7 つの頂点だけである。

システムでは、頂点の v1、v2、v3 を使用して最初の三角形を、v2、v4、v3 を使用して 2 番目の三角形を、v3、v4、v5 を使用して 3 番目の三角形を、v4、v6、v5 を使用して 4 番目の三角形を、という手順で描画していく。2 番目と 4 番目の三角形の頂点が順序どおりでないことに注意する。これは、すべての三角形が時計回りの向きに描画されることを保証するために必要である。

3D シーンのほとんどのオブジェクトは三角形ストリップで構成されている。これは、三角形ストリップを使用して複雑なオブジェクトを指定すると、メモリを効率的に利用して処理時間を短縮できるからである。

次の図は、レンダリングされる三角形ストリップを示している。

次のコードは、三角形ストリップに対して頂点を作成する方法を示している。

struct CUSTOMVERTEX
{
    float x,y,z;
};

CUSTOMVERTEX Vertices[] =
{
    {-5.0, -5.0, 0.0},
    { 0.0,  5.0, 0.0},
    { 5.0, -5.0, 0.0},
    {10.0,  5.0, 0.0},
    {15.0, -5.0, 0.0},
    {20.0,  5.0, 0.0}
};

次のコードは、IDirect3DDevice8::DrawPrimitive を使用して、三角形ストリップをレンダリングする方法を示している。

//
// d3dDevice は、IDirect3DDevice8 インターフェイスへの
// 有効なポインタであると仮定している。
//
d3dDevice->DrawPrimitive( D3DPT_TRIANGLESTRIP, 0, 5 );


三角形ファン

三角形ファンとは、次の図に示すように、すべての三角形が 1 つの頂点を共有するという点を除いては、三角形ストリップに類似したものである。

システムでは、頂点 v2、v3、v1 を使用して最初の三角形を、v3、v4、v1 を使用して 2 番目の三角形を、v4、v5、v1 を使用して 3 番目の三角形を、という手順で描画していく。フラット シェーディングが有効な場合、三角形は最初の頂点の色でシェーディングされる。

次の図は、レンダリングされる三角形ファンを示している。

次のコードは、三角形ファンに対して頂点を作成する方法を示している。

struct CUSTOMVERTEX
{
    float x,y,z;
};

CUSTOMVERTEX Vertices[] =
{
    { 0.0, 0.0, 0.0},
    {-5.0, -5.0, 0.0},
    {-3.0,  7.0, 0.0},
    { 0.0, 10.0, 0.0},
    { 3.0,  7.0, 0.0},
    { 5.0,  5.0, 0.0},
};

次のコードは、IDirect3DDevice8::DrawPrimitive を使用して、三角形ファンをレンダリングする方法を示している。

//
// d3dDevice は、IDirect3DDevice8 インターフェイスへの
// 有効なポインタであると仮定している。
//
d3dDevice->DrawPrimitive( D3DPT_TRIANGLEFAN, 0, 4 );


デバイスの使い方

ここでは、アプリケーションにおける Microsoft® Direct3D® デバイスの使用方法について説明する。説明するトピックは、次のとおりである。

  • ハードウェア サポートの判定
  • デバイスの選択
  • デバイスの作成
  • トランスフォームの設定
  • 頂点データの処理
  • マウス カーソルの操作
  • レンダリング


ハードウェア サポートの判定

Direct3D では、次の機能によってハードウェア サポートを判定する。

IDirect3D8::CheckDeviceFormat
サーフェス フォーマットが、テクスチャとして使用できるかどうか、テクスチャとレンダリング ターゲットとして使用できるかどうか、および深度ステンシル バッファとして使用できるかどうかを検証するために使用する。さらに、深度バッファ フォーマット サポートと深度ステンシル バッファ フォーマット サポートを検証する場合にも、このメソッドを使用する。
IDirect3D8::CheckDeviceType
デバイスが、ハードウェア アクセラレーションを実行できるかどうか、プレゼンテーションのスワップ チェーンを作成できるかどうか、現在のディスプレイ フォーマットにレンダリングできるかどうかを検証するために使用する。
IDirect3D8::CheckDepthStencilMatch
深度ステンシル バッファ フォーマットがレンダリング ターゲット フォーマットと互換性があるかどうかを検証するために使用する。このメソッドを呼び出す前に、アプリケーションから深度ステンシルとレンダリング ターゲットの両方のフォーマットに対して CheckDeviceFormat を呼び出す必要があることに注意すること。


デバイスの選択

アプリケーションは、サポートされている Microsoft® Direct3D® デバイス タイプをハードウェアに照会して検出できる。ここでは、ディスプレイ アダプタの列挙と Direct3D デバイスの選択に関わる基本タスクについて説明する。

アプリケーションは、適切な Direct3D デバイスを選択するための一連のタスクを実行する必要がある。以下のステップは、フルスクリーン アプリケーションのタスクである。多くの場合、ウィンドウ アプリケーションではこれらのステップの大部分を省略できる。

  1. 最初に、アプリケーションはシステム上のディスプレイ アダプタを列挙する必要がある。アダプタは、ハードウェアの物理的部品である。デュアル ヘッド ディスプレイの場合と同様、グラフィックス カードに複数のアダプタが搭載されている場合もあるので注意すること。マルチモニタ サポートに関連しないアプリケーションでは、このステップを無視し、ステップ 2 で IDirect3D8::EnumAdapterModes メソッドに D3DADAPTER_DEFAULT を渡す。
  2. アプリケーションは、アダプタごとに EnumAdapterModes を呼び出して、そのアダプタがサポートするディスプレイ モードを列挙する。
  3. 必要に応じて、IDirect3D8::CheckDeviceType を呼び出し、列挙された各ディスプレイ モードにハードウェア アクセラレーションが存在するかどうかをチェックする。これについては、次のコードに示す。これは CheckDeviceType で使用できる方法の 1 つにすぎない。詳細については、「ハードウェア サポートの判定」を参照すること。
    D3DPRESENT_PARAMETERS Params;
// D3DPRESENT_PARAMETERS メンバの値を初期化する。

Params.BackBufferFormat = D3DFMT_X1R5G5B5;

if(FAILED(m_pD3D->CheckDeviceType(Device.m_uAdapter,
                                  Device.m_DevType,
                                  Params.BackBufferFormat, Params.BackBufferFormat,
                                  FALSE)))
        return E_FAIL;
  4. アプリケーションは IDirect3D8::GetDeviceCaps メソッドを呼び出し、このアダプタのデバイスに必要なレベルの能力があるかチェックする。このメソッドによって、必要な能力をサポートしていないデバイスが選択対象から外される。GetDeviceCaps によって返されるデバイス能力は、CheckDeviceType で検証されたすべてのディスプレイ モードにおいて、デバイスごとに一定であることが保証されている。
  5. デバイスは常に、そのデバイスがサポートするフォーマットとして列挙されたディスプレイ モードのフォーマットを持つサーフェスにレンダリングする。異なるフォーマットのサーフェスにレンダリングする場合は、IDirect3D8::CheckDeviceFormat を呼び出す。デバイスがそのフォーマットにレンダリングできる場合は、GetDeviceCaps が返すすべての能力が適用可能であることが保証される。
  6. 最後に、IDirect3D8::CheckDeviceMultiSampleType メソッドを使って、レンダリング フォーマットでフルシーン アンチエイリアシングなどのマルチサンプリング テクニックがサポートされているかどうかを判定できる。

上記のステップを完了すると、アプリケーションでは、処理できるディスプレイ モードのリストが完成する。最後のステップでは、デバイスがアクセス可能なメモリに、必要な数のバッファとアンチエイリアシングを確保できるスペースがあるかどうかを検証する。このテストを必要とする理由は、モードとマルチサンプルの組み合わせによって消費されるメモリ量が、実際に検証する以外の方法では予測不可能だからである。さらに、ディスプレイ アダプタのアーキテクチャによっては、一定量のデバイス アクセス可能なメモリが用意されていないことがある。つまり、フルスクリーン モードに移行するときにビデオ メモリ障害が発生した場合は、アプリケーションがレポートする必要がある。一般には、アプリケーションがユーザーに提供するモード リストからフルスクリーン モードを削除するか、または使用するバック バッファの数を少なくしたり、メモリ消費の少ないマルチサンプル テクニックを使用して、メモリ消費量の削減を図る。

ウィンドウ アプリケーションでも同様の一連のタスクを実行する。

  1. ウィンドウのクライアント領域に合うデスクトップ矩形を決定する。
  2. アダプタを列挙し、クライアント領域に合うモニタを使用するアダプタを探す。クライアント領域が複数のアダプタによって所有されている場合は、各アダプタを個別に駆動する方法か、1 つのアダプタを駆動して、プレゼンテーション時には Direct3D によってデバイスからデバイスにピクセルを転送する方法かを選択できる。また前述の 2 つのステップを無視して、D3DADAPTER_DEFAULT をアダプタを使用する方法もある。この方法では、ウィンドウがセカンダリ モニタ上に配置されると処理速度が遅くなる場合がある。
  3. アプリケーションは、デスクトップ モード中に CheckDeviceType を呼び出して、デバイスが指定されたフォーマットのバック バッファへのレンダリングをサポートできるかどうかを判定しなければならない。次のコードに示すように、IDirect3D8::GetAdapterDisplayMode を使用して、デスクトップのディスプレイ フォーマットを判定することができる。
    D3DPRESENT_PARAMETERS Params;
// D3DPRESENT_PARAMETERS メンバの値を初期化する。

// 現在のディスプレイ モードを使用する。
D3DDISPLAYMODE mode;

if(FAILED(m_pD3D->GetAdapterDisplayMode(Device.m_uAdapter , &mode)))
        return E_FAIL;

Params.BackBufferFormat = mode.Format;

if(FAILED(m_pD3D->CheckDeviceType(Device.m_uAdapter, Device.m_DevType,
Params.BackBufferFormat, Params.BackBufferFormat, FALSE)))
       return E_FAIL;


デバイスの作成

注 指定の Microsoft® Direct3D® オブジェクトによって作成されたレンダリング デバイスは、すべて同じ物理リソースを共有する。単一の Direct3D オブジェクトから複数のレンダリング デバイスを作成することは可能であるが、これらはすべて同じハードウェアを共有するため、パフォーマンスが大きく低下する。

C++ アプリケーションで Direct3D デバイスを作成するには、「Direct3D へのアクセス｣で説明するように、まず Direct3D オブジェクトを作成する必要がある。

まず、Direct3D デバイスの作成に使用する D3DPRESENT_PARAMETERS 構造体の値を初期化する。次のコードは、VSYNC でのみバック バッファがフロント バッファにフリップされるウィンドウ アプリケーションを指定する。

LPDIRECT3DDEVICE8 d3dDevice = NULL;

D3DPRESENT_PARAMETERS d3dpp;

ZeroMemory( &d3dpp, sizeof(d3dpp) );
d3dpp.Windowed   = TRUE;
d3dpp.SwapEffect = D3DSWAPEFFECT_COPY_VSYNC;

次に、Direct3D デバイスを作成する。次の IDirect3D8::CreateDevice 呼び出しは、デフォルト アダプタ、ハードウェア アブストラクション レイヤ (HAL) デバイス、およびソフトウェア頂点処理を指定する。

if( FAILED( g_pD3D->CreateDevice( D3DADAPTER_DEFAULT, D3DDEVTYPE_HAL, hWnd,
                                  D3DCREATE_SOFTWARE_VERTEXPROCESSING,
                                      &d3dpp, &d3dDevice ) ) )
    return E_FAIL;

デバイスの作成、解放、またはリセットのための呼び出しは、フォーカス ウィンドウのウィンドウ プロシージャと同じスレッドでのみ行うよう注意すること。

デバイス作成後は、そのステートを設定する。


トランスフォームの設定

C++ では、Direct3DDevice8.SetTransform メソッドを呼び出してトランスフォームを適用する。たとえば、ビュー トランスフォームを設定するには、次のようなコードを使用する。

HRESULT    hr;
D3DMATRIX  view;

// ビュー行列にデータを設定する。

hr = pDev->SetTransform(D3DTS_VIEW, &view);

if(FAILED(hr))
{
    // エラー処理コード。
}

SetTransform を呼び出す場合、第 １ パラメータに設定できる値はいくつかあるが、一般には、D3DTS_WORLD、D3DTS_VIEW、および D3DTS_PROJECTION を設定する。これらのトランスフォーム ステートは、D3DTRANSFORMSTATETYPE 列挙型に定義されている。この列挙には D3DTS_TEXTURE1 から D3DTS_TEXTURE7 までのステートも含まれる。これらを使用して、テクスチャ座標にトランスフォームを適用できる。


頂点データの処理

IDirect3DDevice8 インターフェイスは、ソフトウェアとハードウェア両方での頂点処理をサポートする。一般に、ソフトウェアとハードウェアの頂点処理に関するデバイス能力は同じではない。ハードウェアの能力は、ディスプレイ アダプタやドライバによって異なるが、ソフトウェアの能力は一定である。

次のフラグは、ハードウェア アブストラクション レイヤ (HAL) デバイスおよびリファレンス デバイスの頂点処理動作を制御する。

  • D3DCREATE_SOFTWARE_VERTEXPROCESSING
  • D3DCREATE_HARDWARE_VERTEXPROCESSING
  • D3DCREATE_MIXED_VERTEXPROCESSING

IDirect3D8::CreateDevice を呼び出すときは、いずれかの頂点処理動作フラグを指定する。ミックス モード フラグでは、デバイスはソフトウェアとハードウェア両方の頂点処理が可能になる。1 つのデバイスに対して、一度に 1 つの頂点処理フラグしか設定できない。ピュア デバイス (D3DCREATE_PUREDEVICE) を作成するときは、D3DCREATE_HARDWARE_VERTEXPROCESSING フラグが必要なので注意すること。

単一デバイス上に 2 つの頂点処理能力が存在しないようにするため、実行時にはハードウェア頂点処理能力のみを照会できる。ソフトウェアの頂点処理機能は固定され、実行時に照会することはできない。

デバイスのハードウェア頂点処理能力を判定するには、D3DCAPS8 構造体の VertexProcessingCaps メンバを調べる。ソフトウェア頂点処理については、以下の能力がサポートされている。

  • D3DVTXPCAPS_DIRECTIONALLIGHTS
  • D3DVTXPCAPS_LOCALVIEWER
  • D3DVTXPCAPS_MATERIALSOURCE7
  • D3DVTXPCAPS_POSITIONALLIGHTS
  • D3DVTXPCAPS_TEXGEN
  • D3DVTXPCAPS_TWEENING

また、次の表は、ソフトウェア頂点処理モードのデバイスに対して、D3DCAPS8 構造体のメンバに設定される値を示している。

メンバ | ソフトウェア頂点処理能力
MaxActiveLights | 制限なし
MaxUserClipPlanes | 6
MaxVertexBlendMatrices | 4
MaxStreams | 16
MaxVertexIndex | 0xFFFFFFFF

ソフトウェア頂点処理では、制限なしのライト数やプログラム可能な頂点シェーダなど、保証済みの頂点処理能力セットが提供される。ソフトウェア頂点処理とハードウェア頂点処理は、HAL デバイス (ハードウェア頂点処理とソフトウェア頂点処理の両方をサポートする唯一のデバイス タイプ) を使っていつでも切り替えることができる。唯一の要件として、ソフトウェア頂点処理に使用する頂点バッファは、システム メモリ内に割り当てられていなければならない。

注 ハードウェア頂点処理のパフォーマンスは、ソフトウェア頂点処理のパフォーマンスに匹敵する。このため、同一デバイス タイプ内で頂点処理のためのハードウェア エミュレーション機能とソフトウェア エミュレーション機能の両方を提供するとよい。これはラスタ化には適用されない。ラスタ化では、ホスト プロセッサによる処理速度はグラフィックス専用ハードウェアより低速である。したがって、ハードウェア エミュレーションとソフトウェア エミュレーションのラスタ化の両方を単一デバイス タイプ内で提供することはない。単一デバイス内のランタイムとハードウェア (ドライバ） に重複する機能は、ソフトウェア頂点処理のみである。したがって、ほかのデバイス能力はすべて、ドライバによって提供される潜在的に異なる機能である。


マウス カーソルの操作

マウス カーソル メソッドにより、アプリケーションは、画像を格納するサーフェスを提供することによってカラー カーソルを指定できる。アプリケーションのフレーム レートが低速の場合、このカーソルはディスプレイ レートの半分以上の間隔でシステムによって更新される。ただし、カーソルの更新頻度は、モニタのリフレッシュ レートより短くなることはない。

マウス カーソルの位置はシステム カーソルに結合されている （現在のディスプレイ モードの空間上の解像度に合わせて適宜スケーリングされる） が、アプリケーションによって明示的に移動することができる。これは、Microsoft®Win32® API サポート システム マウス カーソルの動作に類似している。Microsoft® Direct3D® アプリケーションにおけるマウス カーソルの使用方法については、以下のリファレンス トピックを参照すること。

  • IDirect3DDevice8::ShowCursor
  • IDirect3DDevice8::SetCursorPosition
  • IDirect3DDevice8::SetCursorProperties

ハードウェアの実装、または IDirect3DDevice8::Present を呼び出したときにハードウェア アクセラレーションによるブリット処理を実行する Direct3D ランタイムにより、Direct3D ではマウスをサポートしている。


レンダリング

アプリケーションでは、一連の DrawPrimitive のメソッドを使用して 3D シーンをレンダリングする。DrawPrimitive によるレンダリングについては、次のトピックに分けて説明する。

  • サーフェスのクリア
  • シーンの開始とエンディング
  • シーンのプレゼンテーション
  • プリミティブのレンダリング


サーフェスのクリア

シーンのオブジェクトをレンダリングする前に、レンダリング ターゲット サーフェスのビューポートまたはビューポートのサブセットをクリアする。ビューポートをクリアすると、システムはレンダリング ターゲット サーフェスの描画部分、およびアタッチされた深度バッファまたはステンシル バッファを指定のステートに設定する。その結果、再度レンダリングするサーフェスの領域がリセットされ、深度バッファとステンシル バッファを使用している場合は、その対応する領域がリセットされる。レンダリング ターゲット サーフェスをクリアすると、指定した領域をデフォルトの色やテクスチャに設定できる。深度バッファおよびステンシル バッファに対しては、深度およびステンシル値を設定できる。

ビューポートのクリアには、IDirect3DDevice8::Clear メソッドを使用する。

このメソッドの使用方法については、「ビューポートのクリア」を参照すること。

最適化に関する注意 レンダリング ターゲット サーフェスの全領域に及ぶシーンをレンダリングするアプリケーションで、パフォーマンスを改善するには、レンダリング ターゲットではなく、アタッチされた深度およびステンシル バッファ サーフェス (ある場合) をクリアする。この場合、深度バッファをクリアすると、Microsoft® Direct3D® は次にレンダリングするフレームにレンダリング ターゲットを再書き込みすることで、レンダリング ターゲットに対する明示的なクリア処理を冗長にする。ただし、レンダリング ターゲット サーフェスの一部にのみレンダリングする場合は、明示的なクリア処理が必要である。


シーンの開始とエンディング

C++ で記述されたアプリケーションでは、IDirect3DDevice8::BeginScene メソッドを呼び出して、Microsoft® Direct3D® にシーンのレンダリングの開始を知らせる。BeginScene を呼び出すと、システムはその内部データ構造およびレンダリング ステートの可用性と有効性をチェックする。また、シーンが進行中であることを伝える内部フラグを設定する。シーンの開始後は、さまざまなレンダリング メソッドを呼び出してプリミティブをレンダリングしたり、シーンのオブジェクトを構成する頂点を個別にレンダリングすることができる。シーンの処理中でないときにレンダリング メソッドを呼び出そうとすると失敗する。詳細については、「プリミティブのレンダリング」を参照すること。

シーンが完了したら、IDirect3DDevice8::EndScene メソッドを呼び出す。EndScene メソッドは、キャッシュされているデータをフラッシュし、レンダリング サーフェスの完全性を検証し、シーンが進行中であることを伝える内部フラグをクリアする。

レンダリング メソッドはすべて、BeginScene メソッドを呼び出してから EndScene メソッドを呼び出すまでの間に実行しなければならない。サーフェスが失われるか、または内部エラーが発生すると、シーンのメソッドはエラー値を返す。BeginScene メソッドが失敗した場合、シーンは開始されず、それに続く EndScene の呼び出しも失敗する。

これらのケースを以下にまとめる。

  • BeginScene が何らかのエラーを返した場合、シーンは正常に開始されていないため、EndScene を呼び出してはならない。
  • BeginScene は成功したがシーンのレンダリング中にエラーが発生した場合、EndScene を呼び出す必要がある。
  • 何らかの理由で EndScene が失敗した場合は、これを再度呼び出す必要はない。

たとえば、次に示すのは、単純なシーンを処理するコードである。

HRESULT hr;

if(SUCCEEDED(pDevice->BeginScene()))
{
    // シーンの開始に成功した場合のみ、
    // プリミティブをレンダリングする。

    // シーンを閉じる。
    hr = pDevice->EndScene();
    if(FAILED(hr))
        return hr;
}

シーンを埋め込むことはできない。つまり、次のシーンをレンダリングするには、現在レンダリング中のシーンを完了する必要がある。BeginScene が呼び出されていないのに EndScene を呼び出した場合、エラーが返される。同様に、前のシーンが EndScene メソッドでまだ完了していないときに BeginScene を呼び出すと、エラーが発生する。

シーンのレンダリング中 (BeginScene を呼び出してから EndScene を呼び出すまでの間)、レンダリング ターゲットやテクスチャなどの Direct3D サーフェスに対して GDI 関数を呼び出してはならない。この関数を呼び出そうとすると、GDI 操作の結果が表示されなくなる可能性がある。アプリケーションで GDI 関数を使用する場合は、シーン関数の外ですべての GDI の呼び出しを行うようにする。


シーンのプレゼンテーション

ここでは、プレゼンテーション API (アプリケーション プログラミング インターフェイス) と、ディスプレイへのシーンのプレゼンテーションに関する問題について説明する。

説明するトピックは、次のとおりである。

  • シーンのプレゼンテーションの概要
  • ウィンドウ モードのマルチビュー
  • マルチモニタ処理
  • 深度バッファの操作
  • カラー フロント バッファへのアクセス


シーンのプレゼンテーションの概要

プレゼンテーションのアプリケーション プログラミング インターフェイス (API) は、モニタ表示に影響するデバイス ステートを制御するメソッドのセットである。このようなメソッドとして、表示設定モードや、画像表示のためのフレーム単位のメソッドなどがある。

  • IDirect3DDevice8::Present
  • IDirect3DDevice8::Reset
  • IDirect3DDevice8::GetGammaRamp
  • IDirect3DDevice8::SetGammaRamp
  • IDirect3DDevice8::GetRasterStatus

プレゼンテーション API を理解するには、次の用語を知る必要がある。

  • フロント バッファ。グラフィックス アダプタによって変換され、モニタまたはほかの出力デバイスに表示されるメモリの矩形。
  • バック バッファ。サーフェスの内容がフロント バッファに送られる。
  • スワップ チェーン。バック バッファの集合体であり、順番にフロント バッファに提示される。一般的に、フルスクリーン スワップ チェーンはフリップ DDI で連続する画像を提示し、ウィンドウ スワップ チェーンはブリット DDI で画像を提示する。

Microsoft® Direct3D® for Microsoft DirectX® 8.0 は、デバイスのプロパティとして 1 つのスワップ チェーンを持つため、各デバイスには常に少なくとも 1 つのスワップ チェーンがある。IDirect3DDevice8 インターフェイスには、非明示的なスワップ チェーンを操作するメソッド セットがある。このメソッド セットは、スワップ チェーン独自のインターフェイスのコピーである。アプリケーションでは追加スワップ チェーンを作成できるが、一般の単一ウィンドウやフルスクリーンのアプリケーションでは必要ない。

Direct3D API for DirectX 8.0 では、フロント バッファに直接公開することはできない。したがって、アプリケーションは、フロント バッファをロックしたりフロント バッファにレンダリングすることはできない。詳細については、「カラー フロント バッファへのアクセス」を参照すること。

注 DirectX 7.x には、組み合わせて呼び出されるプレゼンテーション API がいくつか存在した。IDirectDraw7::SetCooperativeLevel、IDirectDraw7::SetDisplayMode、および IDirectDraw7::CreateSurface によるシーケンスはその良い例である。また、IDirectDrawSurface7::Flip メソッドと IDirectDrawSurface7::Blt メソッドの組み合わせによって、レンダリングされたフレームをモニタに転送することを知らせた。DirectX 8.0 では、これらの API グループを、Reset と Present の 2 つのメイン メソッドに分割した。Reset には、SetCooperativeLevel、SetDisplayMode、CreateSurface、そして Flip へのいくつかのパラメータが含まれている。Present には、Flip と、Blt のプレゼンテーションの使用が含まれている。

IDirect3D8::CreateDevice 呼び出しは、デバイスの非明示的なリセットを示す。DirectX 8.0 API にはプライマリ サーフェスの概念はなく、プライマリ サーフェスを表すオブジェクトを作成することはできない。プライマリ サーフェスは、デバイスの内部プロパティと見なされる。

ガンマ ランプはスワップ チェーンに関連付けられ、IDirect3DDevice8::GetGammaRamp および IDirect3DDevice8::SetGammaRamp メソッドで操作する。


ウィンドウ モードのマルチビュー

Direct3DDevice オブジェクトを介して所有し操作できるスワップ チェーンに加えて、IDirect3DDevice8::CreateAdditionalSwapChain メソッドを使って、同じデバイスから複数のビューに提示するための追加スワップ チェーンを作成できる。

一般に、アプリケーションはビューごとに 1 つのスワップ チェーンを作成し、そのスワップ チェーンを特定のビューに関連付ける。アプリケーションでは、各スワップ チェーンのバック バッファに画像をレンダリングし、IDirect3DDevice8::Present メソッドを使ってそれを 1 つずつ提示する。アダプタごとに一度に 1 つのスワップ チェーンしかフルスクリーンにできないことに注意すること。


マルチモニタ処理

フルスクリーン処理においてデバイスのリセット (IDirect3DDevice8::Reset) または作成 (IDirect3D8::CreateDevice) に成功すると、そのデバイスを作成した Microsoft® Direct3D® オブジェクトがシステム上のすべてのアダプタを所有しているものとしてマークされる。この状態は排他モードと呼ばれ、Direct3D オブジェクトは排他モードを所有している。排他モードでは、ほかの Direct3D オブジェクトによって作成されたデバイスがフルスクリーン処理を行ったりビデオ メモリを割り当てることはできない。また、ある Direct3D オブジェクトが排他モードであると見なされたとき、フルスクリーンになった以外のほかのデバイスは消失状態になる。詳細については、「消失したデバイス」を参照すること。

排他モードでは、Direct3D オブジェクトに、デバイスが使用するフォーカス ウィンドウが知らされる。その Direct3D オブジェクットが所有する最後のフルスクリーン デバイスがウィンドウ モードにリセットされるか破棄されると、排他モードは解放される。

Direct3D オブジェクトが排他モードを所有するとき、デバイスは 2 つのカテゴリに分類される。最初のカテゴリのデバイスには、以下の特性がある。

  • フルスクリーンのデバイスを作成した同じ Direct3D オブジェクトによって作成されている。
  • フルスクリーンのデバイスと同じフォーカス ウィンドウを持つ。
  • どのフルスクリーン デバイスとも異なるアダプタを表す。

このカテゴリのデバイスにはリセット処理や作成処理に関する制限はなく、消失状態にならない。このカテゴリのデバイスは、フルスクリーン モードにすることもできる。

最初のカテゴリに入らないデバイス (別の Direct3D オブジェクトによって作成され、別のフォーカス ウィンドウで作成され、既にフルスクリーンのデバイスがあるアダプタに作成されたデバイス) は、リセットできず、排他モードがなくなるまで消失状態から解放されない。結果として、マルチモニタ アプリケーションでは複数のデバイスをフルスクリーン モードにすることができるが、それは、これらのデバイスがすべて異なるアダプタのデバイスであり、同じ Direct3D オブジェクトによって作成され、しかも同じフォーカス ウィンドウを共有する場合に限られる。


深度バッファの操作

深度バッファはデバイスに関連付けられている。アプリケーションでは、レンダリング ターゲットを設定するときに深度バッファを移動する必要がある。IDirect3DDevice8::GetDepthStencilSurface および IDirect3DDevice8::SetRenderTarget メソッドは、深度バッファの操作に使用する。


カラー フロント バッファへのアクセス

フロント バッファへのアクセスは、IDirect3DDevice8::GetFrontBuffer メソッドを介して行う。ただし、メソッドは提供されていても、テスト用であることが明示されている。したがって、その機能性は保証されない。


プリミティブのレンダリング

ここでは、DrawPrimitive レンダリング メソッドについて、およびこのメソッドのアプリケーションでの使用方法について説明する。

  • 頂点データ ストリーム
  • ストリーム ソースの設定
  • 頂点バッファおよびインデックス バッファからのレンダリング
  • ユーザー メモリ ポインタからのレンダリング


頂点データ ストリーム

Microsoft® Direct3D® のレンダリング インターフェイスは、1 つ以上のデータ バッファに格納された頂点データからプリミティブをレンダリングするメソッドで構成される。頂点データは、頂点の成分を形成する頂点要素の組み合わせから成る。頂点要素は頂点の最小単位であり、位置座標、法線、色などのエンティティを表す。

頂点の成分とは、単一メモリ バッファ内に連続的に (頂点ごとにインターリーブされて) 格納された 1 つ以上の頂点要素である。完全な頂点は、各成分がそれぞれ個別のメモリ バッファにある 1 つ以上の成分から成る。プリミティブをレンダリングするため、複数の頂点の成分が読み出され、頂点処理で完全な頂点が利用できるように組み立てられる。次の図は、頂点の成分を使用してプリミティブをレンダリングする処理を示している。

プリミティブのレンダリングには、2 つのステップがある。まず、1 つ以上の頂点の成分ストリームを設定し、次に、これらのストリームからレンダリングするための DrawPrimitive メソッドを呼び出す。これらのコンポーネント ストリーム内での頂点要素の識別は、頂点シェーダによって指定される。詳細については、「頂点シェーダ」を参照すること。

DrawPrimitive メソッドは、描画を起動するたびに、ある頂点データ セット内の任意の連続するプリミティブ サブセットがレンダリングされるように、頂点データ ストリームにオフセットを指定する。これにより、同じ頂点バッファからレンダリングされるプリミティブのグループ間で、デバイス レンダリング ステートを変更できる。

インデックス付き描画メソッドと、インデックスなし描画メソッドの両方がサポートされている。詳細については、「頂点バッファおよびインデックス バッファからのレンダリング」を参照すること。

レンダリング インターフェイスのセカンダリ セットでは、頂点およびインデックス データをユーザー メモリ ポインタから直接レンダリングできる。詳細については、「ユーザー メモリ ポインタからのレンダリング」を参照すること。


ストリーム ソースの設定

IDirect3DDevice8::SetStreamSource メソッドは、頂点バッファをデバイス データ ストリームにバインドし、頂点データと、プリミティブ処理関数にデータを提供するデータ ストリーム ポートの 1 つとを関連付ける。ストリーム データへの実際の参照は、IDirect3DDevice8::DrawPrimitive, などの描画メソッドが呼び出されるまでは発生しない。

ストリームは、成分データのユニフォーム配列として定義され、各成分は、位置座標、法線、色などの単一エンティティを表す 1 つ以上の要素で構成される。Stride パラメータは、成分のサイズをバイト単位で指定する。


頂点バッファおよびインデックス バッファからのレンダリング

Microsoft® Direct3D® は、インデックス付きとインデックスなしの両方の描画メソッドをサポートする。インデックス付きメソッドは、すべての頂点の成分へのインデックス セットを 1 つ使用する。頂点データは、頂点バッファ内の Direct3D API に提示され、インデックス付き描画メソッドのインデックス データは、インデックス バッファ内に提示される。詳細については、以下のリファレンス トピックを参照すること。

  • IDirect3DDevice8::DrawPrimitive
  • IDirect3DDevice8::DrawIndexedPrimitive

これらのメソッドは、データ入力ストリームのカレント セットからプリミティブを描画する。インデックス バッファへのカレント インデックス配列の設定については、「IDirect3DDevice8::SetIndices メソッド」を参照すること。


ユーザー メモリ ポインタからのレンダリング

レンダリング インターフェイスのセカンダリ セットでは、頂点およびインデックス データをユーザー メモリ ポインタから直接レンダリングできる。これらのインターフェイスは、頂点データのみの単一ストリームをサポートする。詳細については、以下のリファレンス トピックを参照すること。

  • IDirect3DDevice8::DrawPrimitiveUP
  • IDirect3DDevice8::DrawIndexedPrimitiveUP

これらのメソッドは、頂点やインデックス バッファではなく、ユーザー メモリ ポインタによって指定されたデータを使ってレンダリングを行う。


デバイス ステート

Microsoft® Direct3D® デバイスはステート マシンである。つまり、アプリケーションでライティング、レンダリング、およびトランスフォーム モジュールのステートを設定し、レンダリング時にそれらのモジュールを介してデータを渡す。

ここでは、レンダリング ステート、および Direct3D で使用する各レンダリング ステートについて詳しく説明する。また、デバイス ステートのグループを 1 回の呼び出しで処理できるデバイス ステート ブロックについても説明する。説明するトピックは、次のとおりである。

  • レンダリング ステート
  • テクスチャ ステージ ステート
  • ステート ブロック


レンダリング ステート

ここでは、レンダリング ステートの概要と、各レンダリング ステートの詳細について説明する。説明するトピックは、次のとおりである。

  • レンダリング ステートについて
  • アルファ ブレンディング ステート
  • アルファ テスティング ステート
  • アンビエント ライト ステート
  • アンチエイリアシング ステート
  • カリング ステート
  • 深度バッファリング ステート
  • フォグ ステート
  • ライティング ステート
  • アウトラインおよび塗りつぶしステート
  • 頂点単位のカラー ステート
  • プリミティブ クリッピング ステート
  • シェーディング ステート
  • ステンシル バッファ ステート
  • テクスチャ ラッピング ステート


レンダリング ステートについて

デバイス レンダリング ステートは、Microsoft® Direct3D® デバイスのラスタ化モジュールの動作を制御する。レンダリング ステートの属性、使用するシェーディング タイプ、フォグ属性、その他のラスタ化処理を変更することによって、このような動作を制御する。

C++ で記述されたアプリケーションでは、IDirect3DDevice8::SetRenderState メソッドを呼び出して、レンダリング ステートのその他の特性を制御する。D3DRENDERSTATETYPE 列挙型は、可能なレンダリング ステートをすべて指定する。アプリケーションでは、D3DRENDERSTATETYPE 列挙からの値を第 1 パラメータとして SetRenderState メソッドに渡す。

固定機能による頂点処理は、SetRenderState メソッドと以下のデバイス レンダリング ステートによって制御される。プログラムされた頂点シェーダを使用しても、これらの制御の多くは何も影響を受けない。

  • D3DRS_SPECULARENABLE
  • D3DRS_FOGSTART
  • D3DRS_FOGEND
  • D3DRS_FOGDENSITY
  • D3DRS_RANGEFOGENABLE
  • D3DRS_LIGHTING
  • D3DRS_AMBIENT
  • D3DRS_FOGVERTEXMODE
  • D3DRS_COLORVERTEX
  • D3DRS_LOCALVIEWER
  • D3DRS_NORMALIZENORMALS
  • D3DRS_DIFFUSEMATERIALSOURCE
  • D3DRS_SPECULARMATERIALSOURCE
  • D3DRS_AMBIENTMATERIALSOURCE
  • D3DRS_EMISSIVEMATERIALSOURCE
  • D3DRS_VERTEXBLEND

また、固定機能頂点処理パイプラインでは、以下のメソッドを使用して、トランスフォーム、マテリアル、およびライティングを設定する。

  • IDirect3DDevice8::SetTransform
  • IDirect3DDevice8::SetMaterial
  • IDirect3DDevice8::SetLight
  • IDirect3DDevice8::LightEnable

注 ピクセル パイプライン内でのスペキュラ色の追加は、D3DRS_SPECULARENABLE が制御する。D3DRS_FOGSTART、D3DRS_FOGEND、おおよび D3DRS_FOGDENSITY は、ピクセル フォグ濃度計算の開始、終了、および濃度を制御する。


アルファ ブレンディング ステート

色のアルファ値は透明度を制御する。アルファ ブレンディングを有効にすると、あるサーフェスの色、マテリアル、およびテクスチャを透明度とブレンドして、ほかのサーフェスに適用できる。

詳細については、「アルファ テクスチャ ブレンディング」および「マルチ テクスチャ ブレンディング」を参照すること。

C++ で記述されたアプリケーションでは、D3DRS_ALPHABLENDENABLE レンダリング ステートを使用してアルファ透明ブレンディングを有効にする。Microsoft® Direct3D® API では、さまざまな種類のアルファ ブレンディングを使用できる。ただし、ユーザーの 3D ハードウェアが Direct3D で可能なブレンディング ステートのすべてに対応するとは限らないので注意が必要である。

実行されるアルファ ブレンディングの種類は、D3DRS_SRCBLEND および D3DRS_DESTBLEND レンダリング ステートによって異なる。転送元および転送先のブレンディング ステートはペアで使用する。次のコードは、転送元のブレンディング ステートを D3DBLEND_SRCCOLOR に設定し、転送先のブレンディング ステートを D3DBLEND_INVSRCCOLOR に設定する方法を示している。

// このサンプル コードでは、d3dDevice は IDirect3DDevice8 インターフェイスへの
// 有効なポインタであると仮定している。

// 転送元のブレンディング ステートを設定する。
d3dDevice->SetRenderState(D3DRS_SRCBLEND, D3DBLEND_SRCCOLOR);

// 転送先のブレンディング ステートを設定する。
d3dDevice->SetRenderState(D3DRS_DESTBLEND, D3DBLEND_INVSRCCOLOR);

上のサンプル コードに示す呼び出しの結果、Direct3D は転送元カラー (現在の位置でレンダリングされるプリミティブの色) と転送先カラー (フレーム バッファ内の現在の位置の色) の間で線形ブレンディングを実行する。この処理によって、色合いを持つガラスのような外観になる。転送先オブジェクトの色の一部は、転送元オブジェクトから伝わったように見える。その他の色は吸収されたように見える。

転送元および転送先のブレンディング ステートの設定を変えると、霧やほこりの中でオブジェクトが輝いているような外観になる。たとえば、アプリケーションで、炎、電磁力界、プラズマ光線、またはぼんやりした中で輝いているようなオブジェクトをモデリングする場合、転送元および転送先のブレンディング ステートを D3DBLEND_ONE に設定する。

また、アルファ ブレンディングは 3D シーンのライティングを制御する。これはライト マッピングと呼ばれることもある。転送元のブレンディング ステートを D3DBLEND_ZERO に設定し、転送先のブレンディング ステートを D3DBLEND_SRCALPHA に設定すると、転送元のアルファ情報に従ってシーンが暗くなる。転送元のプリミティブは、フレーム バッファの内容をスケーリングするライト マップとして使用され、必要に応じてシーンを暗くする。これによって、モノクロのライト マッピングが生成される。

カラー ライト マッピングは、転送元のアルファ ブレンディング ステートを D3DBLEND_ZERO に設定し、転送先のブレンディング ステートを D3DBLEND_SRCCOLOR に設定することで実現できる。


アルファ テスティング ステート

C++ アプリケーションでは、アルファ テスティングを使用して、いつピクセルをレンダリング ターゲット サーフェスに書き込むかを制御する。D3DRS_ALPHATESTENABLE レンダリング ステートを使用することにより、アプリケーションでは、アルファ テスト関数に基づいて各ピクセルをテストできるように現在の Microsoft® Direct3D® デバイスを設定する。テストが成功すると、ピクセルがサーフェスに書き込まれる。テストが失敗すると、ピクセルは無視される。アルファ テスト関数は、D3DRS_ALPHAFUNC レンダリング ステートで選択する。D3DRS_ALPHAREF レンダリング ステートを使用することにより、アプリケーションでは、比較するすべてのピクセルに参照アルファ値を設定する。

アルファ テスティングは、通常、透明に近いオブジェクトをラスタ化する際のパフォーマンスを改善するために使用する。ラスタ化するカラー データが指定のピクセル (D3DPCMPCAPS_GREATEREQUAL) よりも不透明に近い場合、ピクセルが書き込まれる。そうでない場合は、ラスタライザはピクセルを無視し、2 色のブレンドに必要な処理を省略する。次のサンプル コードは、指定された比較関数がサポートされているかどうかを調べている。サポートされている場合は、レンダリングのパフォーマンス改善に必要な比較関数のパラメータを設定する。

// このサンプル コードでは、pCaps は、
// 前の IDirect3D8::GetDeviceCaps への呼び出しによって格納された
// D3DCAPS8 構造体であると仮定している。
if (pCaps.AlphaCmpCaps & D3DPCMPCAPS_GREATEREQUAL)
{
    dev->SetRenderState(D3DRS_ALPHAREF, (DWORD)0x00000001);
    dev->SetRenderState(D3DRS_ALPHATESTENABLE, TRUE);
    dev->SetRenderState(D3DRS_ALPHAFUNC, D3DCMP_GREATEREQUAL);
}

// 比較関数がサポートされていない場合にもレンダリングを実行する。
// ただし、パフォーマンスは改善されない。

すべてのハードウェアがアルファ テスティング機能をサポートしているわけではない。デバイス機能を調べるには、IDirect3D8::GetDeviceCaps メソッドを呼び出す。デバイス機能を取得した後、使用する比較関数の関連する D3DCAPS8 構造体の AlphaCmpCaps メンバを調べる。AlphaCmpCaps メンバが D3DPCMPCAPS_ALWAYS 能力のみ、または D3DPCMPCAPS_NEVER 能力のみ含んでいる場合、ドライバはアルファ テストをまったくサポートしていない。


アンビエント ライト ステート

アンビエント ライトとは、全方向から照射する環境光である。

Microsoft® Direct3D® のアンビエント ライトの使用に関する特定の情報については、「ダイレクト ライトとアンビエント ライトの比較」および「Direct3D のライティングにおける数学的計算」を参照すること。

C++ アプリケーションでアンビエント ライトの色を設定するには、IDirect3DDevice8::SetRenderState メソッドを呼び出し、第 1 パラメータとして列挙値 D3DRS_AMBIENT を渡す。第 2 パラメータはカラー値である。デフォルト値はゼロである。

// このサンプル コードでは、d3dDevice は IDirect3DDevice8 インターフェイスへの
// 有効なポインタであると仮定している。

// アンビエント ライトを設定する。
d3dDevice->SetRenderState(D3DRS_AMBIENT, 0x00202020);


アンチエイリアシング ステート

アンチエイリアスとは、線とエッジをスクリーン上でより滑らかに表示する方法である。Microsoft® Direct3D® がサポートするアンチエイリアシングには、エッジ アンチエイリアシングおよびフルシーン アンチエイリアシングの 2 種類がある。

これらのテクニックの詳細については、「アンチエイリアシング」を参照すること。

デフォルトでは、Direct3D はアンチエイリアシングを実行しない。エッジ アンチエイリアシング (第 2 レンダリング パスが必要) を有効にするには、D3DRS_EDGEANTIALIAS レンダリング ステートを TRUE に設定する。エッジ アンチエイリアシングを無効にするには、D3DRS_EDGEANTIALIAS を FALSE に設定する。

フルシーン アンチエイリアシングを有効にするには、D3DRS_MULTISAMPLEANTIALIAS レンダリング ステートを TRUE に設定する。フルシーン アンチエイリアシングを無効にするには、D3DRS_MULTISAMPLEANTIALIAS を FALSE に設定する。


カリング ステート

Microsoft® Direct3D® は、プリミティブをレンダリングするときにプリミティブの背面をカリングする。

C++ アプリケーションでカリング モードを設定するには、D3DCULL 列挙型のメンバを設定できる D3DRS_CULLMODE レンダリング ステートを使用する。デフォルトでは、反時計回りの頂点を持つ背面をカリングする。

次のサンプル コードは、時計回りの頂点を持つ背面をカリングするカリング モードを設定する処理を示している。

// このサンプル コードでは、d3dDevice は IDirect3DDevice8 インターフェイスへの
// 有効なポインタであると仮定している。

// カリング ステートを設定する。
d3dDevice->SetRenderState(D3DRS_CULLMODE, D3DCULL_CW);


深度バッファリング ステート

深度バッファリングとは、隠線および隠面を削除する方法である。デフォルトでは、Microsoft® Direct3D® で深度バッファリングは使用されない。

深度バッファの概要については、「深度バッファとは」を参照すること。

C++ アプリケーションでは、D3DZBUFFERTYPE 列挙のメンバのいずれかを使用して新しいステート値を指定することで、D3DRS_ZENABLE レンダリング ステートで深度バッファリング ステートを更新する。

Direct3D による深度バッファへの書き込みを防止する必要がある場合は、D3DRS_ZWRITEENABLE 列挙値を使用し、IDirect3DDevice8::SetRenderState の呼び出しの第 2 パラメータとして D3DZB_FALSE を指定する。

次のコードは、z バッファリングが有効になるように深度バッファ ステートを設定する方法を示している。

// このコード例では、d3dDevice は IDirect3DDevice8 インターフェイスへの
// 有効なポインタであると仮定している。

// z バッファリングを有効にする。
d3dDevice->SetRenderState(D3DRS_ZENABLE, D3DZB_TRUE);

アプリケーションでは、また、D3DRS_ZFUNC レンダリング ステートを使用して、深度バッファリングの実行時に Direct3D で使用する比較関数を制御できる。

z バイアスとは、互いの深度値が同じであっても、一方のサーフェスを他方のサーフェスより手前に表示する方法である。このテクニックは、さまざまなエフェクトを期待できる。一般的な例として、壁に影を付ける場合を考える。影も壁も深度値は同じである。しかし、どうしても壁に影を付けようとする場合がある。このような場合、影に z バイアスを適用することで、壁の上に影を適切に表示できる (「D3DRS_ZBIAS」を参照すること)。


フォグ ステート

フォグ エフェクトを使用すると、3D シーンを一層リアルに表現できる。フォグ エフェクトは、霧のシミュレーション以外にも使用できる。フォグ エフェクトで遠くの景色をぼかすことができる。これは実際のことを表現している。つまり、オブジェクトは遠く離れるにしたがって、その細部が不明瞭になっていく。

アプリケーションでのフォグの使用の詳細については、「フォグ」を参照すること。

C++ アプリケーションでは、デバイス レンダリング ステートを介してフォグを制御する。D3DRENDERSTATETYPE 列挙型には、ピクセル (テーブル) または頂点フォグのいずれが使用されているか、その色、システムが適用するフォグ公式、その公式のパラメータなどを制御するステートが含まれる。

フォグを有効にするには、D3DRS_FOGENABLE レンダリング ステートを TRUE に設定する。フォグ カラーは、D3DRS_FOGCOLOR レンダリング ステートを使用することによって、任意のカラー値に設定できる (フォグ カラーのアルファ成分は無視される)。

D3DRS_FOGTABLEMODE および D3DRS_FOGVERTEXMODE レンダリング ステートは、フォグの計算に適用されるフォグ公式を制御し、適用されるフォグの種類を間接的に制御する。この両方のレンダリング ステートは、D3DFOGMODE 列挙型のメンバのいずれかに設定できる。レンダリング ステートのいずれかを D3DFOG_NONE に設定すると、それに応じてピクセルまたは頂点フォグが無効になる。両方のレンダリング ステートが有効なモードに設定されている場合は、ピクセル フォグ エフェクトのみ適用される。

D3DRS_FOGSTART および D3DRS_FOGEND レンダリング ステートは、D3DFOG_LINEAR モード用のフォグ公式パラメータを制御する。D3DRS_FOGDENSITY レンダリング ステートは、指数フォグ モードのフォグ濃度を制御する。

詳細については、「フォグ パラメータ」を参照すること。


ライティング ステート

Microsoft® Direct3D® のジオメトリ パイプラインを使用するアプリケーションでは、ライティング計算を有効または無効にできる。頂点法線を含む頂点にのみライティングが正しく適用される。頂点法線がない場合は、すべてのライティング計算で 0 の内積が使用される。したがって、法線を使用しない頂点にはライティングが適用されない。

詳細については、「Direct3D のライティングにおける数学的計算」を参照すること。

アプリケーションで Direct3D のライティングを有効にするには、D3DRS_LIGHTING レンダリング ステートを TRUE (デフォルト設定) に設定し、Direct3D のライティングを無効にするには FALSE に設定する。

ライティング レンダリング ステートは、頂点バッファ内の頂点で可能なライティング計算にはまったく依存しない。IDirect3DDevice8::ProcessVertices メソッドは、頂点処理の際にライティング計算を制御する、独自のフラグを受け取る。


アウトラインおよび塗りつぶしステート

テクスチャが適用されていないプリミティブは、マテリアルによって指定される色、または頂点に指定された色があれば、そのいずれかでレンダリングされる。プリミティブを塗りつぶす方法は、D3DFILLMODE 列挙型で定義される値を D3DRS_FILLMODE レンダリング ステートに指定して選択できる。

アプリケーションでディザリングを有効にするには、第 1 パラメータとして D3DRS_DITHERENABLE 列挙値を IDirect3DDevice8::SetRenderState に渡す必要がある。ディザリングを有効にするには第 2 パラメータを TRUE に設定し、無効にするには FALSE に設定する。

線の最後のピクセルを描画すると周囲のプリミティブと重なり、見た目が悪くなることがある。これは、D3DRS_LASTPIXEL 列挙値を使用して制御できる。ただし、この設定を変更するときは注意が必要である。場合によっては、最後のピクセルを描画しないようにするとプリミティブ間に隙間が生じ、見苦しくなることがある。

デフォルトでは、Microsoft®Direct3D® デバイスは、プリミティブに実線のアウトラインを使用する。アウトライン パターンは、D3DLINEPATTERN 構造体を使用して変更できる。詳細については、「D3DRS_LINEPATTERN レンダリング ステート」を参照すること。


頂点単位のカラー ステート

柔軟な頂点フォーマット (FVF) を使用すると、頂点は色情報と法線情報の両方を持てる。Microsoft® Direct3D® では、この情報を使用してライティング計算が実行される (デフォルト)。アプリケーションで頂点カラー ライティング情報の使用を無効にするには、IDirect3DDevice8::SetRenderState を呼び出し、第 1 パラメータとして D3DRS_COLORVERTEX を渡す。第 2 パラメータを FALSE に設定すると頂点カラー ライティングが無効になり、TRUE に設定すると有効になる。

頂点単位のカラーが有効なっている場合、アプリケーションでは、頂点の色情報の情報ソースを設定できる。D3DRS_AMBIENTMATERIALSOURCE、D3DRS_DIFFUSEMATERIALSOURCE、D3DRS_EMISSIVEMATERIALSOURCE、および D3DRS_SPECULARMATERIALSOURCE レンダリング ステートは、それぞれ、アンビエント、ディフューズ、エミッション、および スペキュラ色の色成分ソースを制御する。これらの各レンダリング ステートは、D3DMATERIALCOLORSOURCE 列挙型のメンバに設定できる。この列挙型は、現在のマテリアル、ディフューズ色、またはスペキュラ色を、指定された色成分のソースとして使用するようシステムに知らせる定数を定義する。


プリミティブ クリッピング ステート

Microsoft® Direct3D® では、ビューポート外で部分的にレンダリングするプリミティブをクリッピングすることができる。C++ の場合、Direct3D クリッピングは D3DRS_CLIPPING レンダリング ステートで制御する。このレンダリング ステートを TRUE (デフォルト値) に設定すると、プリミティブ クリッピングが有効になる。レンダリング ステートを FALSE に設定すると、Direct3D のクリッピング サービスは無効になる。

プリミティブ クリッピング レンダリング ステートは、頂点バッファ内の頂点で可能なクリッピング処理にはまったく依存しない。IDirect3DDevice8::ProcessVertices メソッドは、頂点処理の際にプリミティブ クリッピングを制御する、独自のフラグを受け取る。


シェーディング ステート

Microsoft® Direct3D® では、フラット シェーディングとグーロー シェーディングの両方をサポートしている。デフォルトではグーロー シェーディングが設定される。現在のシェーディング モードを制御するため、C++ アプリケーションでは D3DSHADEMODE 列挙型のメンバを D3DRS_SHADEMODE レンダリング ステートに指定する。

次の C++ コードは、シェーディング ステートをフラット シェーディング モードに設定する処理を示している。

// このサンプル コードでは、d3dDevice は IDirect3DDevice8 インターフェイスへの
// 有効なポインタであると仮定している。

// シェーディング ステートを設定する。
d3dDevice->SetRenderState(D3DRS_SHADEMODE, D3DSHADE_FLAT);


ステンシル バッファ ステート

アプリケーションは、ステンシル バッファを使用して、レンダリング ターゲット サーフェスにピクセルを書き込むかどうかを決める。

詳細については、「ステンシル バッファ」を参照すること。

C++ で記述されたアプリケーションで、ステンシル処理を有効または無効にするには、IDirect3DDevice8::SetRenderState メソッドを呼び出す。第 1 パラメータの値として D3DRS_STENCILENABLE を渡す。ステンシル処理を有効にするには第 2 パラメータの値を TRUE に設定し、無効にするには FALSE に設定する。

Microsoft® Direct3D® のステンシル テストで使用する比較関数は、SetRenderState を呼び出して設定する。第 1 パラメータの値を D3DRS_STENCILFUNC に設定する。第 2 パラメータの値として D3DCMPFUNC 列挙型のメンバを渡す。

ステンシル参照値とは、ステンシル関数がテストに使用する、ステンシル バッファ内の値である。デフォルトではステンシル参照値はゼロである。アプリケーションでは、SetRenderState を呼び出してこの値を設定できる。第 1 パラメータの値として D3DRS_STENCILREF を渡す。第 2 パラメータの値を新しい参照値に設定する。

Direct3D モジュールは、ピクセルに対するステンシル テストを実行する前に、ステンシル参照値とステンシル マスク値のビット積を計算する。その結果は、ステンシル比較関数によってステンシル バッファの内容と比較される。アプリケーションでは、SetRenderState を呼び出してステンシル マスクを設定できる。第 1 パラメータの値として D3DRS_STENCILMASK を渡す。第 2 パラメータを新しいステンシル マスクに設定する。

ステンシル テストが失敗したときの Direct3D の処理を設定するには、SetRenderState を呼び出し、第 1 パラメータとして D3DRS_STENCILFAIL を渡す。第 2 パラメータは D3DSTENCILOP 列挙型のメンバでなければならない。

また、ステンシル テストは成功したが z バッファ テストが失敗したときの Direct3D の処理もアプリケーションで制御できる。SetRenderState を呼び出し、第 1 パラメータとして D3DRS_STENCILZFAIL を渡し、第 2 パラメータに D3DSTENCILOP 列挙型のメンバを設定する。

さらに、アプリケーションでは、ステンシル テストと ｚ バッファ テストの両方が成功したときの Direct3D の処理も制御できる。SetRenderState を呼び出し、第 1 パラメータとして D3DRS_STENCILPASS を渡す。この場合も、第 2 パラメータは D3DSTENCILOP 列挙型のメンバでなければならない。


テクスチャ ラッピング ステート

D3DRS_WRAP0 ～ D3DRS_WRAP7 レンダリング ステートは、デバイスのマルチ テクスチャ カスケードの各種テクスチャに対して、u および v ラッピングを有効または無効にする。これらのレンダリング ステートを D3DWRAPCOORD_0、D3DWRAPCOORD_1、D3DWRAPCOORD_2、および D3DWRAPCOORD_3 フラグの組み合わせに設定して、テクスチャの第 1、第 2、第 3、および第 4 方向でのラッピングを有効にできる。ゼロを設定すると、ラッピングはすべて無効になる。デフォルトでは、テクスチャ ラッピングは、すべてのテクスチャ ステージの全方向で無効になっている。

概要については、「テクスチャ ラッピング」を参照すること。


テクスチャ ステージ ステート

ここでは、テクスチャ ステージ ステートの概念と、各テクスチャ ステージ ステートの詳細について説明する。説明するトピックは、次のとおりである。

  • テクスチャ ステージ ステートについて
  • テクスチャ アドレッシング ステート
  • テクスチャ境界ステート
  • テクスチャ フィルタリング ステート
  • テクスチャ ブレンディング ステート


テクスチャ ステージ ステートについて

テクスチャ ステージ ステートは、テクスチャのスタイルおよびテクスチャ フィルタリングの方法を制御する。

C++ で記述されたアプリケーションでは、IDirect3DDevice8::SetTextureStageState メソッドを呼び出して、テクスチャ関連レンダリング ステートの特性を制御する。D3DTEXTURESTAGESTATETYPE 列挙型は、可能なすべてのテクスチャ関連レンダリング ステートを指定する。アプリケーションでは、D3DTEXTURESTAGESTATETYPE 列挙からの値を第 1 パラメータとして SetTextureStageState メソッドに渡す。

アプリケーションでは、IDirect3DDevice8::SetTexture メソッドを呼び出してステージのテクスチャを設定する。


テクスチャ アドレッシング ステート

C++ アプリケーションでは、D3DTSS_ADDRESSU、D3DTSS_ADDRESSV、および D3DTSS_ADDRESSW テクスチャ ステージ ステートを使用してテクスチャ アドレッシングを設定する。


テクスチャ境界ステート

C++ アプリケーションでは、D3DTSS_BORDERCOLOR テクスチャ ステージ ステートを使用して境界色テクスチャ アドレッシングを設定する。

詳細については、「境界色テクスチャ アドレッシング モード」を参照すること。


テクスチャ フィルタリング ステート

C++ アプリケーションでは、D3DTSS_MAGFILTER、D3DTSS_MINFILTER、および D3DTSS_MIPFILTER テクスチャ ステージ ステートを使用して、テクスチャ フィルタリングを制御する必要がある。


テクスチャ ブレンディング ステート

C++ アプリケーションでは、D3DTSS_COLOROP で定義されたテクスチャ ブレンディング ステートと D3DTSS_ALPHAOP テクスチャ ステージ ステートを使用して、テクスチャ ブレンディングを制御する。

詳細については、「マルチ テクスチャ ブレンディング」を参照すること。


ステート ブロック

ここでは、デバイス ステート ブロックの主要な概念について、およびアプリケーションでの使用方法について説明する。説明するトピックは、次のとおりである。

  • ステート ブロックについて
  • ステート ブロックの記録
  • ステート ブロックの取得
  • ステート ブロックの適用
  • 事前定義するステート ブロックの作成
  • ステート ブロックの削除


ステート ブロックについて

Microsoft® Direct3D® のステート ブロックとは、デバイス ステートのグループである。これには、レンダリング ステート、ライティングおよびマテリアル パラメータ、トランスフォーム ステート、テクスチャ ステージ ステート、およびカレント テクスチャ情報がある。ステート ブロックは、デバイスの現在のステートのスナップショットとして処理されるか、または明示的に記録される。スナップショットは、1 回の呼び出しでデバイスに適用することができる。デバイス ステート ブロックは、アプリケーションで必要となる共通した一連のステート変更を高速化するために、レンダリング デバイスで最適化することができる。また、デバイス ステート ブロックの使用により、デバイス ステートの適用を単純化することもできる。

C++ では、ステート ブロック ハンドルを受け取るのは、IDirect3DDevice8::EndStateBlock メソッドを呼び出してステート ブロックの記録を終了したとき、および IDirect3DDevice8::CreateStateBlock メソッドを呼び出して事前定義されているデバイス ステート データ セットを取得したときである。


ステート ブロックの記録

IDirect3DDevice8 インターフェイスには、アプリケーションからデバイス ステートの要求があったときにそのデバイス ステートをステート ブロックに記録する IDirect3DDevice8::BeginStateBlock メソッドがある。BeginStateBlock メソッドは、デバイス ステートの変更をデバイスに適用するのではなく、デバイス ステートの変更をステート ブロックに記録し始める。BeginStateBlock を呼び出した後、次のメソッドの呼び出しはすべてデバイス ステート ブロックに記録される。

  • IDirect3DDevice8::LightEnable
  • IDirect3DDevice8::SetClipPlane
  • IDirect3DDevice8::SetLight
  • IDirect3DDevice8::SetMaterial
  • IDirect3DDevice8::SetRenderState
  • IDirect3DDevice8::SetTexture
  • IDirect3DDevice8::SetTextureStageState
  • IDirect3DDevice8::SetTransform
  • IDirect3DDevice8::SetViewport

ステート ブロックの記録が終了したら、IDirect3DDevice8::EndStateBlock メソッドを呼び出して記録の停止をシステムに知らせる。EndStateBlock メソッドは、ステート ブロックのハンドルを変数に格納する。この変数のアドレスは pToken パラメータに渡す。アプリケーションでは、このハンドルを使用して、必要に応じてステート ブロックをデバイスに適用したり、新しいステート データをブロックに記録したり、不要になったステート ブロックを削除することができる。

パフォーマンスに関する注意 最良の結果を得るためには、BeginStateBlock および EndStateBlock のペア間でのすべてのステート変更をグループ化する。

EndStateBlock メソッドが返すエラー コードをチェックすることが大切である。このメソッドが失敗した場合、その原因の多くはディスプレイ モードが変更されたことであると考えられる。アプリケーションのサーフェスを作成し直し、再度ステート ブロックを記録することで、このような障害からアプリケーションが回復するように設計する。


ステート ブロックの取得

IDirect3DDevice8::CaptureStateBlock メソッドは、既存のステート ブロック内の値を更新してデバイスの現在のステートに反映する。このメソッドは、Token パラメータを 1 つだけ受け取る。このパラメータは、呼び出しが成功した場合にデバイスの現在のステートの取り込み先となるステート ブロックを識別する。

アプリケーションで記録済みのステート ブロックを更新して若干異なるステート設定を含める場合は、CaptureStateBlock メソッドが特に便利である。これを行うには、次のサンプル コードのように、既存のステート ブロックを適用し、必要な設定変更を行い、システムのステートをステート ブロックに取り込む。

// 変数 token には、以前に記録されたデバイス ステート セットの
// デバイス ステート ブロックへのハンドルが格納されている。

// 現在のステート ブロックを設定する。
d3dDevice->ApplyStateBlock(token);

// 必要に応じてデバイス ステート を変更する。
.
.
.

// 修正したデバイス ステート データを既存のブロックに取り込む。
d3dDevice->CaptureStateBlock(token);

CaptureStateBlock メソッドは、デバイスのステート全体を取り込むのではなく、ステート ブロック内の既存のステート値を更新するのみである。たとえば、次のコード例のように、2 つの処理が記録されたステート ブロックがあるとする。

d3dDevice->SetRenderState(D3DRS_SHADEMODE, D3DSHADE_GOURAUD);
d3dDevice->SetTexture(0, pTexture);

ステート ブロックが初めに記録されて以降、2 つの設定のいずれかを変更した場合、CaptureStateBlock メソッドは、ブロック内で変更されたステートのみ新しい値に更新する。


ステート ブロックの適用

IDirect3DDevice8::ApplyStateBlock メソッドは、既存のステート ブロックをデバイスに適用する。ApplyStateBlock メソッドは、Token パラメータを 1 つだけ受け取る。このパラメータは、適用するステート ブロックを識別する。

注 ステート ブロックの記録中 (つまり、IDirect3DDevice8::BeginStateBlock から IDirect3DDevice8::EndStateBlock の呼び出しの間)、別のステート ブロックを適用することはできない。これを実行しようとすると失敗する。


事前定義するステート ブロックの作成

IDirect3DDevice8::CreateStateBlock メソッドは、デバイス ステート セットの全体を含むか、あるいは頂点またはピクセル処理に関するデバイス ステートのみ含む新しいステート ブロックを作成する。CreateStateBlock メソッドは 2 つのパラメータを受け取る。第 1 パラメータは、新しいステート ブロックに取り込むステート情報の種類を識別する。第 2 パラメータは、呼び出しが成功したときに有効なステートブロック ハンドルを受け取る変数のアドレスである。

第 1 パラメータの有効値は、D3DSTATEBLOCKTYPE 列挙型で定義される。これに含まれるメンバを使用して、デバイス ステート セットの全体 (D3DSBT_ALL)、あるいは点またはピクセル処理 (D3DSBT_VERTEXSTATE または D3DSBT_PIXELSTATE) に関するステートのみ取り込むことができる。次の一覧は、D3DSBT_VERTEXSTATE または D3DSBT_PIXELSTATE 値を渡したときにシステムによって取り込まれるステートを示している。

  • 頂点関連のステート (D3DSBT_VERTEXSTATE)
  • すべてのライティングのステート (有効または無効)
  • トランスフォーム行例
  • ユーザー定義クリップ面
    これらの値は、次のレンダリング ステートに対して設定される。
    D3DRS_AMBIENT

    D3DRS_AMBIENTMATERIALSOURCE

    D3DRS_CLIPPING

    D3DRS_CLIPPLANEENABLE

    D3DRS_COLORVERTEX

    D3DRS_CULLMODE

    D3DRS_DIFFUSEMATERIALSOURCE

    D3DRS_EMISSIVEMATERIALSOURCE

    D3DRS_FOGCOLOR

    D3DRS_FOGDENSITY

    D3DRS_FOGENABLE

    D3DRS_FOGEND

    D3DRS_FOGSTART

    D3DRS_FOGTABLEMODE

    D3DRS_FOGVERTEXMODE

    D3DRS_INDEXEDVERTEXBLENDENABLE

    D3DRS_LIGHTING

    D3DRS_LOCALVIEWER

    D3DRS_NORMALIZENORMALS

    D3DRS_POINTSCALE_A

    D3DRS_POINTSCALE_B

    D3DRS_POINTSCALE_C

    D3DRS_POINTSIZE

    D3DRS_POINTSIZE_MAX

    D3DRS_POINTSIZE_MIN

    D3DRS_POINTSCALEENABLE

    D3DRS_POINTSPRITEENABLE

    D3DRS_PATCHEDGESTYLE

    D3DRS_PATCHSEGMENTS

    D3DRS_RANGEFOGENABLE

    D3DRS_SHADEMODE

    D3DRS_SOFTWAREVERTEXPROCESSING

    D3DRS_SPECULARENABLE

    D3DRS_SPECULARMATERIALSOURCE

    D3DRS_TWEENFACTOR

    D3DRS_VERTEXBLEND

    これらの値は、次のテクスチャステージ ステートに対して設定される。
    D3DTSS_TEXCOORDINDEX

    D3DTSS_TEXTURETRANSFORMFLAGS

  • ピクセル関連のステート (D3DSBT_PIXELSTATE)
    これらの値は、次のレンダリング ステートに対して設定される。
    D3DRS_ALPHABLENDENABLE

    D3DRS_ALPHAFUNC

    D3DRS_ALPHAREF

    D3DRS_ALPHATESTENABLE

    D3DRS_COLORWRITEENABLE

    D3DRS_DESTBLEND

    D3DRS_DITHERENABLE

    D3DRS_EDGEANTIALIAS

    D3DRS_FILLMODE

    D3DRS_FOGDENSITY

    D3DRS_FOGEND

    D3DRS_FOGSTART

    D3DRS_LASTPIXEL

    D3DRS_LINEPATTERN

    D3DRS_MULTISAMPLEANTIALIAS

    D3DRS_MULTISAMPLEMASK

    D3DRS_SHADEMODE

    D3DRS_SRCBLEND

    D3DRS_STENCILENABLE

    D3DRS_STENCILFAIL

    D3DRS_STENCILFUNC

    D3DRS_STENCILMASK

    D3DRS_STENCILPASS

    D3DRS_STENCILREF

    D3DRS_STENCILWRITEMASK

    D3DRS_STENCILZFAIL

    D3DRS_TEXTUREFACTOR

    D3DRS_WRAP0 ～ D3DRS_WRAP7

    D3DRS_ZBIAS

    D3DRS_ZENABLE

    D3DRS_ZFUNC

    D3DRS_ZWRITEENABLE

    これらの値は、次のテクスチャステージ ステートに対して設定される。
    D3DTSS_ADDRESSU

    D3DTSS_ADDRESSV

    D3DTSS_ADDRESSW

    D3DTSS_ALPHAARG1

    D3DTSS_ALPHAARG2

    D3DTSS_ALPHAOP

    D3DTSS_BORDERCOLOR

    D3DTSS_BUMPENVLOFFSET

    D3DTSS_BUMPENVLSCALE

    D3DTSS_BUMPENVMAT00

    D3DTSS_BUMPENVMAT01

    D3DTSS_BUMPENVMAT10

    D3DTSS_BUMPENVMAT11

    D3DTSS_COLORARG1

    D3DTSS_COLORARG2

    D3DTSS_COLOROP

    D3DTSS_MAGFILTER

    D3DTSS_MAXANISOTROPY

    D3DTSS_MAXMIPLEVEL

    D3DTSS_MINFILTER

    D3DTSS_MIPFILTER

    D3DTSS_MIPMAPLODBIAS

    D3DTSS_TEXCOORDINDEX

    D3DTSS_TEXTURETRANSFORMFLAGS

注 CreateStateBlock メソッドが返すエラー コードをチェックすることが大切である。このメソッドが失敗した場合、その原因の多くはディスプレイ モードが変更されたことであると考えられる。アプリケーションのサーフェスを作成し直してステート ブロックを記録することで、このような障害からアプリケーションが回復するように設計する。


ステート ブロックの削除

IDirect3DDevice8::DeleteStateBlock は、既存のステート ブロックを削除して、このステート ブロックで使用したメモリの割り当てを解除する。DeleteStateBlock メソッドは、そのパラメータでのみ削除するステート ブロックへのハンドルを受け取る。ステート ブロックを削除すると、そのステート ブロックへのハンドルは無効になり、以後使用することはできない。


消失したデバイス

ここでは、Microsoft® Direct3D® で消失したデバイスについて説明する。説明するトピックは、次のとおりである。

  • 消失したデバイスとは
  • 消失したデバイスへの応答
  • 消失したデバイスとロック処理
  • 消失したデバイスとリソース
  • 消失したデバイスと取得データ


消失したデバイスとは

Microsoft® Direct3D® デバイスの状態には、処理可能状態と消失状態がある。処理可能状態はデバイスの通常の状態であり、すべてのレンダリングが予測どおりに実行され表示される。フルスクリーン アプリケーションでキーボード フォーカスが消失するなどのイベントが発生してレンダリングできなくなると、デバイスは消失状態になる。消失状態の特性は、表面には何も現れずにすべてのレンダリング処理が失敗することである。つまり、レンダリング処理は失敗しているのに、レンダリング メソッドは成功コードを返すことがある。このような場合、IDirect3DDevice8::Present によってエラー コード D3DERR_DEVICELOST が返される。

設計では、デバイスが消失するようなすべてのシナリオが想定されているわけではない。一般的な例としては、ユーザーが Alt + Tab キーを押したときなど、つまりシステム ダイアログが初期化されたときにフォーカスが消失する。また、電力管理イベントによって、ほかのアプリケーションがフルスクリーン処理を行うときにも発生することがある。さらに、IDirect3DDevice8::Reset が失敗すると、デバイスは消失状態となる。


消失したデバイスへの応答

デバイスが消失すると、アプリケーションはそのデバイスに対して、処理可能状態に復元できるかどうかを問い合わせる。復元できない場合は、デバイスが復元できるまでアプリケーションは待機する。

復元できる場合、アプリケーションはすべてのビデオ メモリ リソースとスワップ チェーンを破棄して、デバイスの復元に備える。次に、アプリケーションは IDirect3DDevice8::Reset メソッドを呼び出す。Reset は、デバイスが消失状態のときに有効な唯一のメソッドであり、アプリケーションがデバイスを消失状態から処理可能状態に戻すことができる唯一のメソッドである。IDirect3DDevice8::CreateRenderTarget や IDirect3DDevice8::CreateDepthStencilSurface で作成されたリソースなど、D3DPOOL_DEFAULT で割り当てられたすべてのリソースをアプリケーションが解放しない限り、Reset は失敗する。

ほとんどの場合、Microsoft® Direct3D® を頻繁に呼び出してもデバイスが消失しているかどうかに関する情報は返らない。アプリケーションは、消失したデバイスの通知を受け取らなくても、IDirect3DDevice8::DrawPrimitive などのレンダリング メソッドの呼び出しを続行できる。内部的には、これらの処理は、デバイスが処理可能状態にリセットされるまで破棄される。

アプリケーションは、デバイスが消失したときの処理を判定するために IDirect3DDevice8::TestCooperativeLevel メソッドの戻り値を照会する。

  • メソッドが D3D_OK を返す場合、デバイスは処理可能である。
  • デバイスが消失し復元できない場合、戻り値は D3DERR_DEVICELOST になる。これは、ユーザーが Alt + Tab キーを押し、フルスクリーン デバイスのフォーカスが失われたケースである。アプリケーションの応答としては、デバイスがリセットできるまで一時停止しなければならない。TestCooperativeLevel からのリターン コードが D3DERR_DEVICENOTRESET であれば、リセットできる状態であることを示す。
  • デバイスが消失していて復元できる場合、TestCooperativeLevel からのリターン コードは D3DERR_DEVICENOTRESET である。IDirect3DDevice8::Present メソッドからのリターン コードはまだ D3DERR_DEVICELOST であることに注意すること。

いずれの場合も、Reset の呼び出しにはビデオ メモリ リソースの破棄が前提条件となる。これは、デバイスが消失していない場合も同様である。


消失したデバイスとロック処理

内部的には、Microsoft® Direct3D® ではデバイスが消失してもロック処理は成功するように機能する。しかし、ロック処理時にはビデオメモリ リソースのデータが正確かどうかは保証されない。エラー コードが返らないことは保証されている。したがって、アプリケーションの記述にあたっては、ロック処理時のデバイスの消失については考慮しなくてよい。

詳細については、「消失したデバイスと取得データ」を参照すること。


消失したデバイスとリソース

リソースはビデオ メモリを消費する。消失したデバイスは、アダプタが所有するビデオ メモリから接続解除されるため、デバイスが消失したときのビデオ メモリの割り当てを保証することはできない。そのため、すべてのリソース作成メソッドは、D3D_OK が返ると成功するが実際にはダミーのシステム メモリのみを割り当てるように実装されている。すべてのビデオ メモリ リソースは、デバイスをサイズ変更する前に破棄する必要があるため、ビデオ メモリの過剰割り当ては発生しない。このようなダミー サーフェスにより、アプリケーションが IDirect3DDevice8::Present を呼び出してデバイスの消失を検出するまで、ロック処理やコピー処理が正常に機能しているように見える。

ドライバが消失状態から処理可能状態に復元される前に、すべてのビデオ メモリが解放されなければならない。つまり、アプリケーションは IDirect3DDevice8::CreateAdditionalSwapChain によって作成されたすべてのスワップ チェーンや D3DPOOL_DEFAULT メモリ クラスに配置されているすべてのリソースを解放しなければならないということである。アプリケーションは、D3DPOOL_MANAGED メモリ クラスや D3DPOOL_SYSTEMMEM メモリ クラスに配置されているリソースは解放する必要がない。ほかの状態データは、処理可能状態へのトランジションによって自動的に破棄される。

アプリケーションの開発にあたっては、デバイスの消失に対して 1 つのコード パスで対応することを推奨する。このコード パスは、スタートアップ時にデバイスの初期化に使用したコード パスと同一ではなくても類似するものとする。


消失したデバイスと取得データ

Microsoft® Direct3D® によってアプリケーションは、生成された画像 (または以前に描かれた画像) を、ビデオ メモリ リソースから不揮発性のシステム メモリ リソースにコピーすることができる。このような転送では転送元画像はいつでも失われる可能性があるため、Direct3D では、デバイスが消失したときはコピー処理を失敗させることができる。

このトピックは IDirect3DDevice8::UpdateTexture には適用しない。

コピー処理 IDirect3DDevice8::UpdateTexture および IDirect3DDevice8::CopyRects は、転送元オブジェクトが揮発性メモリ (D3DPOOL_DEFAULT) にあるときと転送先オブジェクトが不揮発性メモリ (D3DPOOL_SYSTEMMEM または D3DPOOL_MANAGED) にあるときは、D3DERR_DEVICELOST を返す。別のコピー処理 IDirect3DDevice8::GetFrontBuffer は、プライマリ サーフェスからデータを取得することによって失敗する場合がある。上記のケースは、IDirect3DDevice8::Present、IDirect3DDevice8::TestCooperativeLevel、および IDirect3DDevice8::Reset の外部で D3DERR_DEVICELOST を使用する唯一の例であることに注意すること。


Direct3D リソース

ここでは、リソースについて、またアプリケーションでのリソース使用の概要について説明する。説明するトピックは、次のとおりである。

  • リソースとは
  • リソース プロパティ
  • リソースの相互関係
  • リソースの使い方


リソースとは

リソースとは、シーンのレンダリングに使用されるテクスチャおよびバッファである。アプリケーションは、リソースを作成、ロード、コピー、および使用する必要がある。ここでは、リソースの概要と、リソースの操作手順およびメソッドについて説明する。各リソース タイプについては、「テクスチャ」、「頂点バッファ」、および 「インデックス バッファ」を参照すること。

ジオメトリ リソース IDirect3DIndexBuffer8 および IDirect3DVertexBuffer8 を含むすべてのリソースは、IDirect3DResource8 インターフェイスから継承する。テクスチャ リソース IDirect3DCubeTexture8、IDirect3DTexture8、および IDirect3DVolumeTexture8 は、IDirect3DBaseTexture8 インターフェイスからも継承する。


リソース プロパティ

すべてのリソースは、以下のプロパティを共有する。

  • 使用。テクスチャ、レンダリング ターゲットとして使用するなど、リソースの使用方法。
  • フォーマット。2D サーフェスのピクセル フォーマットなど、データのフォーマット。
  • プール。リソースが割り当てられるメモリ タイプ。
  • タイプ。頂点バッファ、レンダリング ターゲットなど、リソースのタイプ

リソースの使用は強制される。特定の処理にリソースを使用するアプリケーションは、リソース作成時にその処理を指定する必要がある。リソースには、以下の使用方法が定義されている。

  • D3DUSAGE_DEPTHSTENCIL
  • D3DUSAGE_DONOTCLIP
  • D3DUSAGE_DYNAMIC
  • D3DUSAGE_RTPATCHES
  • D3DUSAGE_NPATCHES
  • D3DUSAGE_POINTS
  • D3DUSAGE_RENDERTARGET
  • D3DUSAGE_SOFTWAREPROCESSING
  • D3DUSAGE_WRITEONLY

D3DUSAGE_RTPATCHES フラグ、D3DUSAGE_NPATCHES フラグ、および D3DUSAGE_POINTS フラグは、これらのバッファ内のデータがそれぞれ、三角形またはグリッドのパッチ、N パッチ、ポイント スプライト用に使用される可能性があることをドライバに示す。ホスト処理がないとハードウェアがこれらの処理を実行できない場合に、これらのフラグが提供される。したがって、CPU からアクセスできるように、ドライバはこれらのサーフェスをシステム メモリに割り当てることを希望することになる。ドライバがこれらの処理を完全にハードウェア内で行うことができれば、これらのサーフェスをビデオまたは /AGP メモリに割り当てられるので、ホストにコピーしなくて済み、パフォーマンスも 2 倍以上向上する。これらのフラグによって提供される情報が絶対に必要というわけではない。ドライバは、データに対してそのような処理が行われていることを検出でき、以降のフレームのためにバッファをシステム メモリに戻す。

利用フラグとそのフラグか関連付けられているリソースの詳細については、各リソース作成メソッドのリファレンス ページを参照すること。

リソースのサーフェス フォーマットの詳細については、「D3DFORMAT 列挙型」を参照すること。

リソースのバッファを保持するメモリ クラスをプールと呼ぶ。プール値は、D3DPOOL 列挙型で定義される。単一リソース (つまり、ミップマップのミップ レベル) 内に異なるオブジェクトが格納されている場合、プールをミックスすることはできない。また、リソースのプールを選択した後で変更することはできない。

リソース タイプは、アプリケーションが実行時に IDirect3DDevice8::CreateCubeTexture などのリソース作成メソッドを呼び出したとき、非明示的に設定される。リソース タイプは、D3DRESOURCETYPE 列挙型で定義される。アプリケーションでは、実行時にこれらのタイプを照会できるが、ほとんどのシナリオでは実行時のタイプ チェックは必要としない。


リソースの相互関係

次の図は、特定のリソースとその内容に対して、構文的に可能な処理を示している。リソースの使用方法については、「リソースの操作」を参照すること。

左から右への矢印は、ターゲット タイプがそのメソッドによって作成されたことを示し、右から左への矢印は、それらのリソースが引数としてそのメソッドに渡せることを示している。


リソースの使い方

ここでは、リソースを処理する際にアプリケーションが実行する一般的なタスクについて説明する。

  • リソースの管理
  • アプリケーション管理リソースおよび割り当て方法
  • リソースの操作
  • リソースのロック


リソースの管理

リソース管理は、リソースをシステム メモリ ストレージからデバイスがアクセス可能なストレージに移し、デバイスがアクセス可能なストレージから破棄するプロセスである。Microsoft® Direct3D® ランタイムには、LRU (least-recently-used) 優先方式に基づく独自の管理アルゴリズムがある。1 つのフレーム (IDirect3DDevice8::BeginScene 呼び出しと IDirect3DDevice8::EndScene 呼び出しの間) 内で、デバイスがアクセス可能なメモリに共存できるリソース数より多くのリソースが検出されると、most-recently-used 優先方式に切り替わる。

管理リソースを指定するには、作成時に D3DPOOL_MANAGED フラグを使用する。管理リソースは、デバイスの消失状態と処理可能状態との間のトランジションでも保持される。デバイスは、IDirect3DDevice8::Reset 呼び出しによって復元でき、このようなリソースはアートワークに再ロードしなくても正常に機能し続ける。ただし、デバイスを破棄して作成し直す必要がある場合、D3DPOOL_MANAGED を使用して作成されたリソースはすべて作成し直す必要がある。

リソースをデフォルトのプールに配置することを指定するには、作成時に D3DPOOL_DEFAULT フラグを使用する。デフォルトのプール内のリソースは、デバイスの消失状態と処理可能状態間のトランジションでは保持されない。これらのリソースは Reset を呼び出す前に解放し、その後で作成し直す必要がある。

デバイスの消失状態の詳細については、「消失したデバイス」を参照すること。

リソース管理は、すべてのタイプおよび使用に対してサポートされているわけではないので注意すること。たとえば、D3DUSAGE_RENDERTARGET フラグで作成されたオブジェクトはサポートされていない。また、高い頻度で内容が変更されるオブジェクトに対しては、リソース管理は奨励しない。たとえば、すべてのフレームを変更する管理頂点バッファの場合、何らかのハードウェアのパフォーマンスを大きく低下させることがある。ただし、これはテクスチャ リソースに関する問題ではない。


アプリケーション管理リソースおよび割り当て方法

管理頂点バッファ リソースまたはインデックス バッファ リソースは、作成時に D3DUSAGE_DYNAMIC を指定しても、動的として宣言することはできない。このためには、頂点バッファの内容に加える変更ごとに追加コピーが必要となる。動的頂点バッファは、BSP ツリーまたはその他の可視データ構造から取得したデータだけでなく、動的ジオメトリのレンダリングで使用できる。これは、目的のフォーマットのバッファを事前に割り当てることで実現する。その後、これらのリソースは、アプリケーションのニーズをサポートするために、アプリケーションのリソース マネージャによって分割される。アプリケーションが同時に使用する異なる頂点ストライドはごくわずかしかなく、異なる頂点バッファは一意の各ストライドに対してのみ必要なので、動的頂点バッファの総数は少ない。このようにして動的リソースを管理するときは、リソースへの高頻度な要求によってアプリケーションのパフォーマンスが低下しないようにすることが大切である。

D3D 管理リソースとアプリケーション管理リソースの両方を同時に使用するときは、管理リソースを作成する前に、すべてのアプリケーション管理リソースを D3DPOOL_DEFAULT メモリに割り当てる必要がある。D3DPOOL_MANAGED メモリにリソースを割り当てた後で D3DPOOL_DEFAULT メモリにリソースを割り当てると、D3D メモリ リソースは使用可能メモリの不正確なアカウントを指定する。


リソースの操作

アプリケーションは、シーンをレンダリングするために、リソースを操作する。最初に、アプリケーションは次のメソッドを使ってテクスチャ リソースを作成する。

  • IDirect3DDevice8::CreateCubeTexture
  • IDirect3DDevice8::CreateTexture
  • IDirect3DDevice8::CreateVolumeTexture

テクスチャ作成メソッドによって返されるテクスチャ オブジェクトは、サーフェスまたはボリュームのコンテナであり、これらのコンテナを一般にバッファと呼ぶ。リソースが所有するバッファは、リソースの使用、フォーマット、およびプールは継承するが、型は独自の型になる。詳細については、「リソース プロパティ」を参照すること。

アプリケーションでは (アートワークをロードするため)、以下のメソッドを呼び出して、格納されたサーフェスへのアクセスを取得する。詳細については、「リソースのロック」を参照すること。

  • IDirect3DCubeTexture8::LockRect
  • IDirect3DTexture8::LockRect
  • IDirect3DVolumeTexture8::LockBox

ロック メソッドは、格納されたサーフェス (たとえば、テクスチャのミッピマップ サブレベルまたはキューブ面) およびピクセルへのリターン ポインタを指定する引数を取る。一般的なアプリケーションでは、サーフェス オブジェクトを直接使用することはない。

さらにアプリケーションは、次のメソッドを呼び出して、ジオメトリ指向のリソースを作成する。

  • IDirect3DDevice8::CreateIndexBuffer
  • IDirect3DDevice8::CreateVertexBuffer

アプリケーションは、次のメソッドを呼び出して、バッファ リソースをロックし、データを設定する。

  • IDirect3DIndexBuffer8::Lock
  • IDirect3DVertexBuffer8::Lock

これらのリソースを Microsoft® Direct3D® ランタイムで管理しているアプリケーションの場合、リソースの作成プロセスはここで終了する。それ以外のアプリケーションでは、IDirect3DDevice8::UpdateTexture を呼び出して、システム メモリ リソースのデバイス アクセス可能なリソース (ハードウェア アクセラレータが使用できる) への移動を管理する。

リソースからレンダリングした画像を提示するため、アプリケーションにはカラー バッファと深度ステンシル バッファも必要である。一般的なアプリケーションの場合、カラー バッファはデバイスのスワップ チェーン (バック バッファ サーフェスの集合体) が所有し、デバイスによって非明示的に作成される。深度ステンシル サーフェスは暗黙のうちに作成されるか、IDirect3DDevice8::CreateDepthStencilSurface メソッドを使用して明示的に作成される。アプリケーションは IDirect3DDevice8::SetRenderTarget を呼び出し、デバイスとその深度およびカラー バッファとを関連付ける。

最終的画像の提示については、「シーンのプレゼンテーション」を参照すること。


リソースのロック

リソースをロックすると、ストレージへの CPU アクセスが許可される。リソースには、次のロッキング メソッドが定義されている。

  • D3DLOCK_DISCARD
  • D3DLOCK_READONLY
  • D3DLOCK_NOOVERWRITE
  • D3DLOCK_NOSYSLOCK
  • D3DLOCK_NO_DIRTY_UPDATE

ロッキング フラグおよびロッキング フラグと特定のリソースとの関係については、各リソース ロッキング メソッドのリファレンス ページを参照すること。アプリケーション開発者は、D3DLOCK_DISCARD、D3DLOCK_READONLY、および D3DLOCK_NOOVERWRITE フラグは単なるヒントにすぎないことに注意すること。ランタイムでは、アプリケーションがこれらのフラグに指定されている機能に従っているかどうかのチェックは行われない。D3DLOCK_READONLY を指定しながらリソースに書き込みを行った場合、予期できない結果が発生する。D3DUSAGE_WRITEONLY を指定した後でリソースから読み込みを行った場合、パフォーマンスが大きく低下することが予想される。一般に、ロッキング利用フラグを含めロッキング フラグに対する処理が、将来使用できるかは保証されず、現在においても今後においてもパフォーマンスの大幅な低下をもたらす可能性がある。

ロック処理の後にはロック解除処理を行う。たとえば、テクスチャをロックした後、アプリケーションはロックされたテクスチャのロックを解除して、そのテクスチャへの直接アクセスを放棄する。プロセッサ アクセスを許可するだけでなく、ロック持続中は、そのリソースにかかわるほかのすべての処理が順番に並べられる。オーバーラップしない領域であっても、リソースに対して 1 つのロックのみが許可され、サーフェス上にロック処理が行われている間は、そのサーフェスでのアクセラレータ処理は実行できない。

各リソース インターフェイスには、格納されているバッファをロックするためのメソッドがある。また、各テクスチャ リソースは、リソースのサブポーションをロックできる。2 次元リソース (サーフェス) では、サブ矩形をロックすることができ、ボリューム リソースでは、サブボリュームまたはボックスをロックすることができる。各ロッキング メソッドは、リソースを戻すストレージへのポインタと、データの行間隔または平面間隔 (リソース タイプによって異なる) を表す値を返す。詳細については、リソース インターフェイスのメソッド リストを参照すること。返されるポインタは、常に、ロックされたサブリージョンの左上のバイトを指す。

インデックス バッファや頂点バッファを操作する場合は、複数のロック呼び出しが行えるが、ロック呼び出しの数とロック解除呼び出しの数が一致している必要がある。

符号化された 4 × 4 ブロックにピクセルを格納する圧縮したテクスチャ フォーマットの DXT セットは、4 × 4 の境界でのみロックすることができる。


サーフェス

ここでは、Microsoft® Direct3D® サーフェイスについて説明する。説明するトピックは、次のとおりである。

  • サーフェスの基本概念
  • ガンマ コントロール
  • サーフェス メモリへの直接アクセス
  • プライベート サーフェス データ


サーフェスの基本概念

ここでは、Microsoft® Direct3D® サーフェスに関する基本概念について説明する。説明するトピックは、次のとおりである。

  • サーフェス インターフェイス
  • 幅とピッチ
  • サーフェス フォーマット
  • フリッピング サーフェス
  • サーフェスへのコピー


サーフェス インターフェイス

サーフェスは、ディスプレイ メモリの線形領域を表している。通常、サーフェスはディスプレイ カードのディスプレイ メモリに常駐しているが、システム メモリに存在することもできる。サーフェス オブジェクトは、IDirect3DSurface8 インターフェイス内に含まれている。

IDirect3DSurface8 インターフェイスを取得するには、次のいずれかのメソッドを呼び出す。

  • IDirect3DCubeTexture8::GetCubeMapSurface
  • IDirect3DDevice8::CreateDepthStencilSurface
  • IDirect3DDevice8::CreateImageSurface
  • IDirect3DDevice8::CreateRenderTarget
  • IDirect3DDevice8::GetBackBuffer
  • IDirect3DDevice8::GetDepthStencilSurface
  • IDirect3DDevice8::GetFrontBuffer
  • IDirect3DDevice8::GetRenderTarget
  • IDirect3DSwapChain8::GetBackBuffer
  • IDirect3DTexture8::GetSurfaceLevel

IDirect3DSurface8 インターフェイスでは、IDirect3DDevice8::CopyRects メソッドによって間接的にメモリにアクセスできる。このメソッドでは、ピクセルの矩形領域を、ある IDirect3DSurface8 インターフェイスから別の IDirect3DSurface8 インターフェイスにコピーすることができる。さらに、サーフェス インターフェイスにはディスプレイ メモリに直接アクセスするメソッドもある。たとえば、IDirect3DSurface8::LockRect メソッドを使用して、ディスプレイ メモリの矩形領域をロックすることができる。重要なことは、サーフェス上のロックした矩形領域を操作した後で、IDirect3DSurface8::UnlockRect を呼び出すことである。


幅とピッチ

幅とピッチという単語からある程度想像できるが、非常に重要な、そして明らかに異なる意味がある。したがって、その意味と Microsoft®Direct3D® で幅とピッチの記述に使用する値の判断方法を理解する必要がある。

Direct3D では、D3DSURFACE_DESC 構造体を使ってサーフェスを記述する情報を伝達する。ほかにも、このディメンジョンのメモリ内での表示方法と同様に、この構造体はサーフェスのディメンジョンの情報を含むために定義される。この構造体では Height メンバと Width メンバを使い、サーフェスの論理的なディメンジョンを記述する。両方のメンバはピクセル単位で測定される。そのため、640 × 480 のサーフェスに対する Height 値と Width 値は、8 ビットのサーフェスか 24 ビットの RGB サーフェスかに関係なく同じになる。

IDirect3DSurface8::LockRect メソッドを使ってサーフェスをロックすると、このメソッドはサーフェスのピッチとロックされたビットへのポインタを含む D3DLOCKED_RECT 構造体にデータを設定する。Pitch メンバの値は、サーフェスのメモリ ピッチ (または、ストライドと呼ばれる) を記述する。ピッチは、2 つのメモリ アドレス間 (あるビットマップ ラインの始点と次のビットマップ ラインの始点) の距離であり、単位はバイトである。ピッチはピクセルではなくバイト単位で測定されるために、640 × 480 × 8 のサーフェスは、異なるピクセル フォーマットの同じディメンジョンのサーフェスよりも非常に異なるピッチの値を持つ。さらに、ピッチの値は Direct3D がキャッシュとして確保するバイトを反映することもあるので、単にピッチをピクセル単位のバイト数を掛けた幅であると仮定することはできない。次の図は、幅とピッチの違いを示している。

上記の図では、フロント バッファとバック バッファはどちらも 640 × 480 × 8 で、キャッシュは 384 × 480 × 8 である。

サーフェス メモリに直接アクセスする場合のみ、ピッチの値が役立つ。たとえば、LockRect メソッドを呼び出した後に、関連付けられた D3DLOCKED_RECT 構造体の pBits メンバには、そのサーフェスのロックされた領域の左上ピクセルのアドレスが含まれ、Pitch メンバはサーフェス ピッチとなる。ピクセル単位のバイト数により、サーフェス ポインタをインクリメントしたりデクリメントすることで、左右にピクセルにアクセスできる。また、ピッチの値を現在のサーフェス ポインタに追加したり、またはそのポインタから減じたりすると、上下に移動できる。

サーフェスに直接アクセスする場合、サーフェスのディメンジョンに対して割り当てられたメモリの範囲内に置くことと、キャッシュに対して確保されたあらゆるメモリの外に置くことに注意する。さらに、サーフェスのポインタだけをロックする場合、サーフェスをロックするときに指定する矩形の範囲内に置かなくてはならない。これに従わないと、予測不可能な結果が生じる。サーフェス メモリに直接レンダリングするときは、LockRect メソッドが返すピッチを常に使用する。単に、ディスプレイ モードに基づくピッチを仮定して使用してはならない。ほかの原因により正常に動作しなくなったいくつかのディスプレイ アダプタ上でアプリケーションが動作する場合、問題が生じる可能性がある。

詳細については、「サーフェス メモリへの直接アクセス」を参照すること。


サーフェス フォーマット

サーフェス フォーマットは、サーフェス メモリ内の各ピクセルのデータをどのように判断するかを指示する。Microsoft® Direct3D® は、D3DSURFACE_DESC 構造体の D3DFORMAT メンバを使用してサーフェス フォーマットを記述する。IDirect3DSurface8::GetDesc メソッドを呼び出すことによって、既存のサーフェスのフォーマットを取得することができる。


フリッピング サーフェス

Microsoft® Direct3D® アプリケーションは、通常、バック バッファにアニメーションのフレームを生成し、連続して提示することで、アニメーションを表示する。バック バッファはスワップ チェーンに分割される。スワップ チェーンとは、スクリーンに順に “フリップ” する一連のバッファのことである。このスワップ チェーンを使用すると、メモリ内のあるシーンをレンダリングし、レンダリングが完了したらそのシーンをスクリーンにフリップできる。これで、テアリングと呼ばれる現象を防ぎ、より滑らかなアニメーションが得られる。

Direct3D で作成された各デバイスは、スワップ チェーンを少なくとも 1 つは持っている。最初の Direct3D デバイスを初期化するときに、スワップ チェーン内にあるバック バッファの数を Direct3D に指示する D3DPRESENT_PARAMETERS 構造体の BackBufferCount メンバを設定する。IDirect3D8::CreateDevice を呼び出し、次に、Direct3D デバイスおよび対応するスワップ チェーンを作成する。

IDirect3DDevice8::Present メソッドを用いてサーフェス フリッピング処理を要求する場合、フロント バッファとバック バッファに対するサーフェス メモリへのポインタはスワップされる。フリッピングは、サーフェス メモリをコピーすることではなく、メモリを参照するためにディスプレイ デバイスの使用するポインタを切り替えることで実行される。フリッピング チェーンにフロント バッファと 1 つ以上のバック バッファがある場合、次の図に示すように、ポインタは循環的パターンで切り替えられる。

デバイスの追加スワップ チェーンを作成するには、IDirect3DDevice8::CreateAdditionalSwapChain を呼び出す。アプリケーションはビューごとに 1 つのスワップ チェーンを作成し、そのスワップ チェーンを特定のウィンドウに関連付ける。アプリケーションでは、各スワップ チェーンのバック バッファに画像をレンダリングし、次にそれを個別に提示する。CreateAdditionalSwapChain が受け取る 2 つのパラメータは、D3DPRESENT_PARAMETERS 構造体へのポインタと IDirect3DSwapChain8 インターフェイスへのポインタのアドレスである。次に、IDirect3DSwapChain8::Present を使用して、次のバック バッファの内容をフロント バッファに表示する。各デバイスはフルスクリーン スワップ チェーンを 1 つしか持てないことに注意すること。

特定のバック バッファへアクセスするには、IDirect3DDevice8::GetBackBuffer メソッドまたは IDirect3DSwapChain8::GetBackBuffer メソッドを呼び出す。これらのメソッドは、返されるバック バッファ サーフェスを表す IDirect3DSurface8 インターフェイスへのポインタを返す。このメソッドを呼び出すと、IDirect3DDevice8 インターフェイスの内部参照カウントが増えるので、このサーフェスを使用した後は、必ず IUnknown::Release を呼び出すよう注意すること。呼び出さないと、メモリ リークが起こる。

Direct3D は、サーフェス自体をスワップするのではなく、スワップ チェーン内のサーフェス メモリ ポインタをスワップすることで、サーフェスのフリッピングを行うことを思い出すこと。つまり、次に表示されるバック バッファに対して常にレンダリングするということである。

ディスプレイ アダプタ ドライバによって行われる "フリッピング処理" と、D3DSWAPEFFECT_FLIP を使用して作成されたスワップ チェーンに適用される "Present" 処理には、明らかな違いがあることに注意することが大切である。

一般に "フリップ" という用語は、ディスプレイ アダプタがその出力信号を生成するために使用するビデオ メモリのアドレス範囲を変更する処理のことであり、これによって隠しバック バッファの内容が表示される。DirectX 8 の場合、この用語は、D3DSWAPEFFECT_FLIP スワップ エフェクトで作成されたスワップ チェーンにおけるバック バッファのプレゼンテーションのことを表すために、より一般的に使用される。

スワップ チェーンがフルスクリーンの場合に "Present" 処理がほとんど常にフリップ処理によって実装されるとき、これらの処理はスワップ チェーンがウィンドウの際に必ずコピー処理によって実装される。さらに、ディスプレイ アダプタ ドライバは、D3DSWAPEFFECT_DISCARD、D3DSWAPEFFECT_COPY、および D3DSWAPEFFECT_COPY_VSYNC スワップ チェーンに基づくフルスクリーン スワップ チェーンに対して Present 処理を実装するためにフリッピングを使用できる。

これまでの説明は、D3DSWAPEFFECT_FLIP で作成されたフルスクリーン スワップ チェーンを使用する一般的なケースに適用される。

ウィンドウ スワップ チェーンおよびフルスクリーン スワップ チェーンの異なるスワップ エフェクトの一般的な説明については、「D3DSWAPEFFECT」を参照すること。


サーフェスへのコピー

IDirect3DDevice8::CopyRects メソッドを使用するときは、転送元サーフェス上の矩形の配列または NULL を渡して、サーフェス全体を指定する。また、転送元イメージの各矩形の左上隅がコピーされる転送先サーフェス上のポイントの配列を渡す。このメソッドはクリッピングをサポートしていない。すべての転送元矩形および対応する転送先矩形が、それぞれ転送元および転送先サーフェス内に完全に含まれていない場合には、このメソッドが失敗する。このメソッドは、アルファ ブレンディング、カラー キー、およびフォーマット変換はサポートしていない。転送先サーフェスと転送元サーフェスは異ならなければならない点に注意すること。

CopyRects の例

次に示す例では、2 つの矩形が転送元サーフェスから転送先サーフェスにコピーされる。最初の矩形は、転送元サーフェス上の (0, 0, 50, 50) から転送先サーフェス上の同じ位置にコピーされ、2 番目の矩形は、転送元サーフェス上の (50, 50, 100, 100) から転送先サーフェス上の (150 ,150, 200, 200) にコピーされる。

//このコードでは、
//-d3dDevice は有効な Direct3DDevice8 オブジェクトであり、
//-pSource と pDest は有効な IDirect3DSurface8 ポインタであると仮定している。

RECT  rcSource[] = {  0,  0,  50,  50,
                     50, 50, 100, 100 };
POINT ptDest[]   = {  0,  0, 150, 150 };

d3dDevice->CopyRect( pSource, rcSource, 2, pDest, ptDest);

C++/C では、Microsoft® Direct3D® サーフェスにイメージをコピーする場合に、次のメソッドも使用できる。

  • D3DXLoadSurfaceFromFileA
  • D3DXLoadSurfaceFromFileInMemory
  • D3DXLoadSurfaceFromFileW
  • D3DXLoadSurfaceFromMemory
  • D3DXLoadSurfaceFromResourceA
  • D3DXLoadSurfaceFromResourceW
  • D3DXLoadSurfaceFromSurface
  • IDirect3DDevice8::CopyRects


ガンマ コントロール

ここでは、Microsoft® Direct3D® で使用されるガンマ コントロールについて説明する。説明するトピックは、次のとおりである。

  • ガンマ コントロールとは
  • ガンマ コントロールの使い方


ガンマ コントロールとは

ガンマ コントロールでは、サーフェス自体のコンテンツに影響を与えることなく、システムがサーフェスのコンテンツを表示する方法を変更できる。これらのコントロールは、Microsoft® Direct3D® がスクリーン上でレンダリングされる前にサーフェスを残すのと同様、データに適用する非常に単純なフィルタと考えられる。

ガンマ コントロールは、スワップ チェーンの単なるプロパティにすぎない。ガンマ コントロールは、システムが表示する実際のレベルにサーフェスの赤、緑、および青のレベル マップを動的に変更できる。ガンマ レベルを設定することで、エフェクトを付けるフレーム バッファに新しいイメージをコピーせずに、ユーザーのスクリーンにフラッシュ カラー (ユーザーのキャラクタを出すときの赤、キャラクタが新しいアイテムを取得するときの緑など) を適用できる。または、カラー レベルを調節して、バック バッファのイメージにカラー バイアスを適用できる。

Microsoft® Direct3D® for Microsoft DirectX® 8.0 はデバイスのプロパティとして 1 つのスワップ チェーンを持っているため、各デバイスに対して、常に少なくとも 1 つのスワップ チェーン (非明示的なスワップ チェーン) が存在する。ガンマ ランプはスワップ チェーンのプロパティなので、スワップ チェーンをウィンドウにするときはガンマ ランプを適用できる。ガンマ ランプは直ちに有効になる。VSYNC を待機することはできない。

ガンマ コントロールの使用方法の詳細については、「ガンマ コントロールの使い方」を参照すること。


ガンマ コントロールの使い方

IDirect3DDevice8::SetGammaRamp メソッドと IDirect3DDevice8::GetGammaRamp メソッドでは、ディスプレイに対するデジタル-アナログ コンバータ (DAC) にピクセルが送られる前に、サーフェスからピクセルの赤、緑、および青の色成分に影響を与えるランプ レベルを操作できる。

ここでは、ランプ レベルの一般的な概念と、これらのレベルの処理について説明する。説明するトピックは、次のとおりである。

  • ガンマ ランプ レベルについて
  • ガンマ ランプ サポートの検出
  • ガンマ ランプ レベルの設定と取得


ガンマ ランプ レベルについて

Microsoft® Direct3D® では、ガンマ ランプという用語は一連の値のことを表す。この一連の値は、フレーム バッファのすべてのピクセルに対して、ディスプレイに対するデジタル アナログ コンバータ (DAC) により受け取られる新しいレベルに、特定の色成分 (赤、緑、および青) のレベルをマップする値である。再マッピングは、3 つの参照テーブル (個々の色成分に対して 1 つ) により実行される。

ここではその方法について説明する。Direct3D はフレーム バッファからピクセルを取得し、その固有の赤、緑、および青の色成分でピクセルを取得する。個々のコンポーネントは 0 から 65535 までの値で表される。Direct3D は元の値を取得し、その値を使用して 256 要素配列 (ランプ) のインデックスを付ける。この配列には、個々の要素を元の要素と置き換える値を含む。Direct3D では、フレーム バッファ内の各ピクセルの各色成分に対して "参照と置き換え" のプロセスを実行し、スクリーン上のすべてのピクセルに対する最終的な色を変更する。

ランプ値のグラフを作成すると、視覚化されて容易に理解できる。次に、2 つのグラフを示す。左側のグラフは色がまったく変更されないランプを示す。右側のグラフは負のバイアスを適用する色成分に置くランプを示す。

左側のグラフの配列要素には、それらのインデックスと等しい値 (インデックス 0 には要素 0、およびインデックス 255 には 65535) が含まれる。これらの値が表示される前の入力値は変更できないため、ランプのこのタイプがデフォルトとなる。右側のグラフは、より大きな変動を示す。このランプには、最初の要素 0 から最後の要素 32768 までの値が、中間の比較的一様な範囲の値で含まれる。このエフェクトは、このランプを使用する色成分がディスプレイ上で音を消して表示される。線形グラフの利用だけに限らない。つまり、必要に応じて、アプリケーションで任意のマッピングを割り当てることができる。さらに、入力をすべてゼロに設定すると、ディスプレイから色成分を削除できる。


ガンマ ランプ サポートの検出

デバイスがスワップ チェーンの現在のプレゼンテーション モード (フルスクリーンまたはウィンドウ) においてガンマ ランプをサポートしていない場合でも、エラー値が返ることはない。アプリケーションでは、D3DCAPS8 型の Caps2 メンバの D3DCAPS2_FULLSCREENGAMMA 能力ビットおよび D3DCAPS2_CANCALIBRATEGAMMA 能力ビットを調べて、デバイスの能力および口径測定器がインストールされているかどうかを判断できる。


ガンマ ランプ レベルの設定と取得

ガンマ ランプ レベルは効果的な参照テーブルであり、Microsoft®Direct3D® が表示される新しいレベルにフレーム バッファ色成分をマップするために使用する。詳細については、「ガンマ ランプ レベルについて」を参照すること。IDirect3DDevice8::SetGammaRamp メソッドおよび IDirect3DDevice8::GetGammaRamp メソッドを呼び出すことにより、プライマリ サーフェスに対するランプ レベルを設定し、取得できる。SetGammaRamp は 2 つのパラメータを受け取り、GetGammaRamp は 1 つのパラメータを受け取る。SetGammaRamp の第 1 パラメータは、D3DSGR_CALIBRATE か D3DSGR_NO_CALIBRATION のいずれかである。第 2 パラメータ pRamp は、D3DGAMMARAMP 構造体へのポインタである。D3DGAMMARAMP 構造体には、WORD の 256 要素配列を 3 つ (1 つの配列ごとに赤、緑、青のガンマ ランプ) 含む。GetGammaRamp には、現在のガンマ ランプを格納する D3DGAMMARAMP 型へのポインタを受け取るパラメータが 1 つある。

SetGammaRamp の第 1 パラメータに DDSGR_CALIBRATE 値を含むと、新しいガンマ レベルを設定するときに口径測定器を起動できる。ガンマ ランプをキャリブレーションするといくらかオーバーヘッドがあるので、頻繁には使えない。調整されたガンマ ランプの設定は、ディスプレイ アダプタおよびモニタにかかわらず、一貫性のある完全なガンマ値を提供する。

すべてのシステムがガンマ キャリブレーションをサポートするわけではない。ガンマ キャリブレーションをサポートするかどうかを判定するには、IDirect3DDevice8::GetDeviceCaps を 呼び出して、メソッドが戻った後に関連付けられた D3DCAPS8 構造体の Caps2 メンバを調べる。D3DCAPS2_CANCALIBRATEGAMMA 能力フラグが存在すると、ガンマ キャリブレーションはサポートされる。

新しいランプ レベルを設定する場合、その配列に設定したレベルはアプリケーションがフルスクリーン (排他モード) の場合にだけ使用される。アプリケーションがノーマル モードに変更されると、常にランプ レベルは側に設定され、アプリケーションがフルスクリーン モードに復帰されるときに再び取得される。


サーフェス メモリへの直接アクセス

サーフェス メモリに直接アクセスするには、IDirect3DSurface8::LockRect メソッドを使う。このメソッドを呼び出す場合、pRect パラメータは、直接アクセスしようとするサーフェス上の矩形を記述する RECT 構造体へのポインタとする。サーフェス全体をロックするには、pRect を NULL に設定する。また、サーフェスの一部だけをカバーする RECT を指定することもできる。2 つの矩形が重ならなければ、2 つのスレッドまたは 2 つのプロセスは、サーフェスの複数の矩形を同時にロックすることができる。マルチサンプル バック バッファはロックできないことに注意すること。

LockRect メソッドは、サーフェス メモリに正しくアクセスするために必要となるすべての情報を、D3DLOCKED_RECT 構造体に格納する。この構造体には、ピッチに関する情報が含まれており、ロックされているビットへのポインタがある。サーフェス メモリへのアクセスが終了すると、IDirect3DSurface8::UnlockRect メソッドを呼び出して、ロックを解除する。

サーフェスをロックしている間、そのコンテンツを直接操作することができる。サーフェス メモリを直接レンダリングするときの一般的な問題を避けるためのヒントを、以下のリストで示す。

  • 一定のディスプレイ ピッチを仮定しない。常に、LockRect メソッドが返すピッチ情報を調べること。このピッチは、サーフェス メモリの位置、ディスプレイ カードのタイプ、Microsoft® Direct3D® ドライバのバージョンなど、さまざまな理由によって変化する。詳細については、「幅とピッチ」を参照すること。
  • ロックを解除されたサーフェスへのコピーを確認する。Direct3D コピー メソッドは、ロックされたサーフェスで呼び出されると、失敗する。
  • サーフェスがロックされている間、アプリケーションのアクティビティは制限される。
  • ディスプレイ メモリに対して連続するデータを常にコピーする Microsoft® Windows® 95 および Windows 98 では、ページ フォールト ハンドラ Vflatd.386 を使用して、バンクスイッチ メモリを使ったディスプレイ カードに対する仮想フラットフレーム バッファを実装する。このハンドラにより、これらのディスプレイ デバイスは Direct3D に連続したフレーム バッファを渡すことができる。ディスプレイ メモリに対して不連続のデータをコピーすると、コピーがメモリ バンクにスパンする場合に、システムが一時停止を起こす可能性がある。
  • D3DPOOL_DEFAULT メモリ プールに割り当てられたリソースに属するサーフェスは、ロックされない場合がある。バック バッファ サーフェス (IDirect3DDevice8::GetBackBuffer および IDirect3DSwapChain8::GetBackBuffer メソッドを使用してアクセスできる) をロックできるのは、スワップ チェーンが D3DPRESENTFLAG_LOCKABLE_BACKBUFFER を含めるように D3DPRESENT_PARAMETERS 構造体の Flags メンバを使用して作成されている場合だけである。


プライベート サーフェス データ

サーフェスと共にあらゆる種類のアプリケーション固有データを格納できる。たとえば、ゲームのマップを示すサーフェスには、地域情報を含む場合がある。

サーフェスでは、1 つ以上のプライベート データ バッファを所有できる。各バッファは、サーフェスにデータをアタッチする際に指定する GUID で識別される。

プライベート サーフェス データを格納するには、IDirect3DSurface8::SetPrivateData メソッドを使用する。このメソッドは、転送元バッファ、データのサイズ、データ用にアプリケーションで定義した GUID へのポインタを渡す。随意に、転送元データは COM オブジェクトのフォームに存在できる。この場合、オブジェクトの IUnknown インターフェイス ポインタにポインタを渡し、D3DSPD_IUNKNOWNPOINTER フラグを設定する。

SetPrivateData はデータに対して内部バッファを割り当て、データをコピーする。その後で、転送元バッファまたはオブジェクトを安全に解放できる。内部バッファまたはインターフェイス参照は、IDirect3DSurface8::FreePrivateData の呼び出し時に解放される。サーフェスが解放されると、この処理は自動的に発生する。

サーフェスに対するプライベートデータを取得するには、正確なサイズのバッファを割り当て、SetPrivateData でデータに割り当てられた GUID を渡す IDirect3DSurface8::GetPrivateData メソッドを呼び出さなくてはならない。このバッファを使用するあらゆる動的メモリの解放については、各自で責任を持つ。データが COM オブジェクトの場合、このメソッドは Iunknown ポインタを取得する。

割り当てるバッファのサイズがわからない場合は、最初に SizeOfData にゼロを代入して GetPrivateData を呼び出す。このメソッドが D3DERR_MOREDATA で失敗した場合、バッファに必要なバイト数を SizeOfData に返す。


ライト

ライトは、シーンのオブジェクトを照らすために使用する。ここでは、ライティング、および Microsoft® Direct3D® アプリケーションでのライトの使用方法について説明する。説明するトピックは、次のとおりである。

  • ライティングとマテリアルの概要
  • Direct3D のライティング モデルと自然光の比較
  • ライティングとマテリアルのカラー値
  • ダイレクト ライトとアンビエント ライトの比較
  • ライト オブジェクト
  • ライト プロパティ
  • ライトの使い方


ライティングとマテリアルの概要

ライティングが有効になっているとき、Microsoft® Direct3D® はレンダリングの最終段階としてシーンをラスタライズする際、シーンの光源によって生成されるライティングの色と強度や、シーンのアンビエント ライト レベルのほかにも、現在のマテリアル カラーおよび関連付けられたテクスチャ マップのテクセル、頂点のディフューズ色とスペキュラ色 (指定されている場合) の組み合わせに基づいて、レンダリングする各ピクセルの色を決める。Direct3D のライティングとマテリアルを使用するときは、Direct3D で自動的にライティングの詳細を制御するようにできる。経験を積んだユーザーであれば、必要に応じて自分でライティングを実行できる。

ライティングとマテリアルの処理方法によって、レンダリングしたシーンの表示は大きく異なる。マテリアルは、サーフェスからの反射光の状態を定義する。ダイレクト ライトとアンビエント ライト レベルは、反射光を定義する。ライティングが有効のときは、マテリアルを使用してシーンをレンダリングしなければならない。ライティングはシーンのレンダリングにおいては必須ではないが、ライティングなしでレンダリングしたシーンの細部は見えない。ライティングのないシーンをレンダリングした場合は、シーンのオブジェクトのシルエットが表示される程度である。細部は十分に表示されない。


Direct3D のライティング モデルと自然光の比較

自然界では、光源から放射された光は、何千や何百万ではないにしても、何百もの物体に反射した末にわたしたちの目に届く。光は反射するたびに、その一部が物体の表面に吸収されたり、周囲に拡散し、その残りがほかの表面や私たちに達する。この過程は、光が減衰して消えてなくなるか、またはわたしたちが光が届いたことを知覚するまで繰り返される。

自然光の動きを完全にシミュレートする計算には、あまりにも膨大な時間がかかるため、リアルタイム 3D グラフィックスで使用できないことは明白である。そこで、速度を考慮して、Microsoft® Direct3D® のライティング モデルでは自然光の動きを大まかにシミュレートする。Direct3D では、最終的な色を作成する色成分、赤、緑、および青によって光を描く。詳細については、「ライティングとマテリアルのカラー値」を参照すること。

Direct3D では、光がサーフェスに反射したとき、光の色とサーフェス自体を数学的に処理することで、最終的にスクリーンに描画される色を作成する。Direct3D で使用するアルゴリズムに関する特定の情報については、「Direct3D のライティングにおける数学的計算」を参照すること。

Direct3D のライティング モデルは、大きく分けてアンビエント ライトとダイレクト ライトの 2 つがある。これらは互いに異なる属性を持ち、サーフェスのマテリアルとの相互作用も異なる。アンビエント ライトは、方向も光源も持たず、環境内を散乱している光で、環境光とも言われる。アンビエント ライトの強度は、どの位置座標においても下位レベルに保たれる。アンビエント ライトの適切な例としては、カメラマンが使用する間接照明がある。Direct3D のアンビエント ライトには、自然光と同様、実際の方向や光源はない。あるのは色と強度のみである。実際、アンビエント ライトのレベルは、シーン内の光を発するオブジェクトとはまったく関係しない。アンビエント ライトはスペキュラ反射を起こさない。

ダイレクト ライトは、シーン内の光源が生成する光である。ダイレクト ライトには常に色と強度があり、特定の方向に進む。ダイレクト ライトは、サーフェスのマテリアルと相互作用してスペキュラ ハイライトを生み、その方向はグーロー シェーディングなどのシェーディング アルゴリズムで係数として使用される。ダイレクト ライトの反射は、シーンのアンビエント ライトのレベルに影響を与えない。シーン内のダイレクト ライトを生成する光源にはさまざまな特性があり、それによってシーンをどのように照らすかが異なる。詳細については、「ライト」を参照すること。

さらに、ポリゴンのマテリアルには、ポリゴンが光をどのように反射するかを決める特性がある。マテリアルがどのようにアンビエント ライトを反射するかを示す単一の反射特性を設定し、マテリアルのスペキュラ反射率およびディフューズ反射率を決める個々の特性を設定する。詳細については、「マテリアル」を参照すること。


ライティングとマテリアルのカラー値

Microsoft® Direct3D® には、色を記述する 4 つの成分 (赤、緑、青、およびアルファ) があり、これらを組み合わせて最終的な色が生成される。C++ の D3DCOLORVALUE 構造体は、これらの各成分を格納するように定義される。各メンバは、通常 0.0 と 1.0 を含む 0.0 ～ 1.0 の範囲の浮動小数点値である。ライティングとマテリアルでは、共に同じ構造体を使用して色を記述するが、構造体内で使用する値は互いに少しずつ異なる。

光源のカラー値は、光源が発する特定の光の成分の量を表す。ライティングではアルファ成分は使用しないため、赤、緑、および青成分のみ関連がある。これらの 3 つの成分は、プロジェクション モニタの赤色、緑色、および青色のレンズに例えることができる。各レンズをオフにしたり (対応するメンバに 0.0 を設定)、できるだけ明るくしたり (1.0 を設定)、その間のレベルを設定することができる。各レンズからの色を組み合わせて、最終的なライティングの色を作成する。R:1.0、G:1.0、B:1.0 の組み合わせの場合、白色光になり、R:0.0、G:0.0、B:0.0 の場合は光をまったく放射しないライティングになる。色成分を 1 つだけ放射するライティングを作成して、純粋な赤色、緑色、または青色のライティングを作ることができる。また、色成分の組み合わせによっては、黄色や紫色などの色を放射するライティングを作成することもできる。色成分値を負にして、シーンから明かりをなくすような "暗色光" を作成できる。また、成分に 1.0 より大きな値を設定して、極端に明るいライティングを作成することもできる。

一方、マテリアルの場合、カラー値はそのマテリアルを使用するサーフェスがどのくらい光の成分を反射するかを表す。マテリアルの色成分が R:1.0、G:1.0、B:1.0、A:1.0 の場合、マテリアルはすべての光を反射する。同様に、R:0.0、G:1.0、B:0.0、A:1.0 の場合は、緑色の光をすべて反射する。マテリアルに複数の反射率を指定して、さまざまなエフェクトを作成できる。詳細については、「マテリアル プロパティ」を参照すること。

アンビエント ライトのカラー値は、ダイレクト ライト光源とマテリアルに使用するカラー値とは異なる。詳細については、「ダイレクト ライトとアンビエント ライトの比較」を参照すること。


ダイレクト ライトとアンビエント ライトの比較

ダイレクト ライトとアンビエント ライトは、ともにシーン内のオブジェクトを照らすが、両者は互いに影響し合うことはなく、それぞれが持つエフェクトは大きく異なるもので、これらの操作方法についてもまったく異っている。

ダイレクト ライトは、文字どおり、ダイレクトである。ダイレクト ライトは常に方向と色を持ち、これはグーロー シェーディングなどのシェーディング アルゴリズムの係数として使用される。ライティングの種類が異なれば、ダイレクト ライトの放射も異なり、それぞれ特別な減衰エフェクトを生み出す。ダイレクト ライトのライティング パラメータ セットは、IDirect3DDevice8::SetLight メソッドを呼び出して作成する。詳細については、「ライト」を参照すること。

アンビエント ライトは、シーン内のどの位置座標にもエフェクトを及ぼす。アンビエント ライトは、オブジェクトやオブジェクトのシーン内の位置座標にかかわらず、シーン全体を同じ強度の光で照らすライティングと考えることができる。アンビエント ライトはあらゆる位置に存在し、色と強度を持つのみで、位置座標や方向は持たない。アンビエント ライト レベルを設定するには、IDirect3DDevice8::SetRenderState メソッドを呼び出し、State パラメータとして D3DRS_AMBIENT を指定し、Value パラメータとして目的の RGBA 色を指定する。

アンビエント ライトの色は、RGBA 値の形をとり、各成分は 0 ～ 255 の整数値である。これは、Microsoft® Direct3D® のほとんどのカラー値とは異なる。詳細については、「ライティングとマテリアルのカラー値」を参照すること。

D3DCOLOR_RGBA マクロを使用して RGBA 値を生成できる。赤、緑、および青成分を組み合わせて、アンビエント ライトの最終的な色を作成する。アルファ成分は色の透明度を制御する。ハードウェア アクセラレーションまたは RGB エミュレーションを使用するときは、アルファ成分は無視される。


ライト オブジェクト

Microsoft® Direct3D® では、ポイント ライト、スポットライト、およびディレクショナル ライトの 3 種類のライトを使用する。ライト プロパティ セットを作成するときに、使用するライトの種類を選択する。ライト プロパティとそれに伴う計算上のオーバーヘッドは、ライティングの種類によって異なる。Direct3D ライティング モジュールでサポートされる、以下の光源について説明する。

  • ポイント ライト
  • スポットライト
  • ディレクショナル ライト

これらの光源とアンビエント ライト レベルを混同しないこと。詳細については、「ダイレクト ライトとアンビエント ライトの比較」、「ライト プロパティ」、および「ライトの使い方」を参照すること。


ポイント ライト

ポイント ライトは、シーン内で色と位置座標を持つが、単一の方向は持たない。次の図に示すように、ポイント ライトはすべての方向に均等に光を放つ。

ポイント ライトの例としては電球がある。ポイント ライトは減衰と範囲の影響を受け、頂点ごとにメッシュを照らす。ライティングの実行中、Microsoft® Direct3D® は、ワールド空間でのポイント ライトの位置座標とライティングする頂点の座標を使用して、ライトの方向を表すベクトルと光が進んだ距離を取得する。頂点法線に加えて、このベクトルと距離の両方を使用して、サーフェスにどのくらい光が当っているかを計算する。


スポットライト

スポットライトは、色、位置座標、および光を放射する方向を持つ。スポットライトから放射される光は、明るい内部コーンとこれより大きな外部コーンで構成される。次の図に示すように、光の強度は 2つのコーン間で減少する。

スポットライトは、フォールオフ、減衰、および範囲の影響を受ける。これらの要因は、光が各頂点まで進む距離と同様、シーン内のオブジェクトへのライティング エフェクトを計算するときに考慮に入れる。各頂点に対するこれらのエフェクトを計算する場合、Microsoft Direct3D® のすべてのライトの中でコンピュータへの負荷が最も大きいのはスポットライトである。


ディレクショナル ライト

ディレクショナル ライトは、色と方向を持ち、位置座標は持たない。これは平行な光を放射する。つまり、ディレクショナル ライトで生成された光はすべてシーン内で同じ方向に進む。ディレクショナル ライトは、太陽のような遠く離れた光源に例えることができる。ディレクショナル ライトは減衰と範囲の影響を受けないので、Microsoft® Direct3D® では指定された色と方向のみ考慮して、頂点の色を計算する。ライティング係数の個数が少ないため、ディレクショナル ライトはコンピュータへの負荷が最も軽いライトである。


ライト プロパティ

ライト プロパティは、光源の種類と色を決める。使用するライトの種類によって、ライトは減衰と範囲のプロパティやスポットライト エフェクトのプロパティを持つことができる。しかし、ライトの種類によっては使用できないプロパティもある。Microsoft® Direct3D® では、D3DLIGHT8 構造体にすべての種類の光源のライト プロパティに関する情報を保持する。ここでは、すべてのライト プロパティについて説明する。説明するトピックは、次のとおりである。

  • ライトの種類
  • ライトの色
  • 頂点色
  • ライトの位置座標、範囲、および減衰
  • ライトの方向
  • スポットライト プロパティ

ライト プロパティは、光源がシーン内のオブジェクトをどのように照らすかに影響する。

詳細については、「ライトの使い方」、「ライト プロパティの設定」、および「Direct3D のライティングにおける数学的計算」を参照すること。


ライトの種類

ライトの種類プロパティは、使用する光源の種類を定義する。C++ の場合、ライトの種類は、ライトの D3DLIGHT8 構造体の Type メンバに D3DLIGHTTYPE 列挙からの値を使用して設定する。Microsoft® Direct3D® には、ポイント ライト、スポットライト、およびディレクショナル ライトの 3 種類のライトがある。ライトの種類ごとに、シーン内のオブジェクトの照らし方が異なり、計算におけるオーバーヘッドのレベルも異なる。各ライトの作用に関する一般的な情報については、「ライト オブジェクト」を参照すること。


ライトの色

Microsoft® Direct3D® のライトは、システムによるライティング計算で独立して使用される、ディフューズ色、アンビエント色、およびスペキュラ色の 3 つの色を放射する。それぞれの色は、Direct3D ライティング モジュールによって組み込まれ、現在のマテリアルの色と相互作用し、最終的にレンダリングで使用される色が生成される。ディフューズ色は現在のマテリアルのディフューズ プロパティと相互作用し、スペキュラ色はマテリアルのスペキュラ属性と相互作用する、という具合に処理される。 Direct3D でのこれらの色の適用方法については、「Direct3D のライティングにおける数学的計算」を参照すること。

C++ アプリケーションの場合、D3DLIGHT8 構造体にこれらの色を表す 3 つのメンバ Diffuse、Ambient、および Specular が含まれる。各メンバは、放射する色を定義する D3DCOLORVALUE 構造体である。

システムの計算負荷が比較的大きいのは、ディフューズ色である。最も一般的なディフューズ色は白色 (R:1.0 G:1.0 B:1.0) であるが、目的のエフェクトを出すために必要に応じて色を作成できる。たとえば、暖炉に赤色のライトを使用したり、"Go" になった交通信号に緑色を使用することができる。

一般には、ライトの色成分を 0.0 と 1.0 を含む 0.0 ～ 1.0 の値に設定するが、これ以外の値に設定することもできる。たとえば、すべての成分を 2.0 に設定して、"白色よりも明るい" ライトを作成できる。このような設定は、定数以外の減衰設定を使用するときには特に便利である。

Direct3D ではライトに RGBA 値を使用するが、アルファ成分は使用しない。詳細については、「ライティングとマテリアルのカラー値」を参照すること。


頂点色

一般に、マテリアル カラーがライティングに使用される。しかし、マテリアル カラー (エミッション、アンビエント、ディフューズ、およびスペキュラ) を、ディフューズ頂点カラーまたはスペキュラ頂点カラーで置き換えるよう指定できる。この指定を行うには、IDirect3DDevice8::SetRenderState を呼び出して、次の表に示すデバイス ステート変数を設定する。

デバイス ステート変数 | 意味 | 型 | デフォルト
D3DRS_AMBIENTMATERIALSOURCE | アンビエント マテリアル カラーを取得する場所を定義する。 | D3DMATERIALCOLORSOURCE | D3DMCS_MATERIAL
D3DRS_DIFFUSEMATERIALSOURCE | ディフューズ マテリアル カラーを取得する場所を定義する。 | D3DMATERIALCOLORSOURCE | D3DMCS_COLOR1
D3DRS_SPECULARMATERIALSOURCE | スペキュラ マテリアル カラーを取得する場所を定義する。 | D3DMATERIALCOLORSOURCE | D3DMCS_COLOR2
D3DRS_EMISSIVEMATERIALSOURCE | エミッション マテリアル カラーを取得する場所を定義する。 | D3DMATERIALCOLORSOURCE | D3DMCS_MATERIAL
D3DRS_COLORVERTEX | 頂点カラーの使用を有効/無効にする。 | BOOL | TRUE

アルファ/透明値は常に、ディフューズ色のアルファ チャネルからのみ得られる。

フォグ値は常に、スペキュラ色のアルファ チャネルからのみ得られる。

D3DMATERIALCOLORSOURCE には、以下の値を指定することができる。

  • D3DMCS_MATERIAL – マテリアル カラーをソースとして使用
  • D3DMCS_COLOR1 - ディフューズ頂点カラーをソースとして使用
  • D3DMCS_COLOR2 – スペキュラ頂点カラーをソースとして使用


ライトの位置座標、範囲、および減衰

位置座標、範囲、および減衰プロパティは、ワールド空間でのライトの位置座標、およびライトが放射する光が距離の増加に伴ってどのように変化するかを定義する。C++ で使用するすべてのライト プロパティと同様、これらのプロパティはライトの D3DLIGHT8 構造体に含まれる。

位置座標

ライトの位置座標は、D3DLIGHT8 構造体の Position メンバに D3DVECTOR 構造体を使用して指定する。x、y、z 座標はワールド空間にあると仮定する。ディレクショナル ライトは、位置座標プロパティを使用しない唯一のライトである。

範囲

ライトの範囲プロパティは、オブジェクトが放射した光をシーン内のメッシュが受け取れなくなるまでの、ワールド空間での距離を決める。Range メンバには、ワールド空間でのライトの最大範囲を表す浮動小数点値が含まれる。ディレクショナル ライトでは範囲プロパティは使用しない。

減衰

減衰は、範囲プロパティで指定した最大距離に近づくにつれてライトの強度がどのように減少するかを制御する。ライトの減衰は、3 つの D3DLIGHT8 構造体のAttenuation0、Attenuation1、および Attenuation2 メンバで表す。これらのメンバには、ライトの減衰を制御する 0.0 ～ 無限大の浮動小数点値が含まれる。アプリケーションによっては、Attenuation1 メンバを 1.0 に設定し、その他のメンバを 0.0 に設定することで、ライトの強度が 1 / D として変化するようにする。ここで、D は光源から頂点までの距離である。光源ではライトの強度が最大で、そこから離れるに従って 1 / (ライトの範囲) に減少する。通常、アプリケーションでは Attenuation0 を 0.0 に設定し、Attenuation1 を定数に設定し、Attenuation2 を 0.0 に設定する。

減衰値を組み合わせて、より複雑な減衰エフェクトを出すことができる。また、減衰値を通常の範囲外の値に設定して、さらに珍しい減衰エフェクトを出すことができる。たとえば、負の減衰値を設定すると、距離が増加するに従ってライトが明るくなる。

Microsoft® Direct3D® で減衰の計算に使用する数学モデルの詳細については、「距離の増加によるライトの減衰」を参照すること。範囲プロパティと同様、ディレクショナル ライトでは減衰プロパティは使用しない。


ライトの方向

ライトの方向プロパティは、オブジェクトの放射する光がワールド空間内を進む方向を決める。方向は、ディレクショナル ライトとスポットライトでのみ使用し、ベクトルで定義する。

C++ アプリケーションでは、ライトの D3DLIGHT8 構造体の Direction メンバにライトの方向を設定する。Direction メンバは、D3DVECTOR 型である。方向ベクトルは、シーン内のライトの位置座標とは無関係に、論理原点からの距離として記述する。したがって、シーンにまっすぐに入射する (z 軸の正方向に沿って) スポットライトの方向ベクトルは、その位置座標がどこに定義されていても <0,0,1> である。同様に、シーンを真上から照らす太陽光をシミュレートするには、方向が <0,-1,0> のディレクショナル ライトを使用すればよい。必ずしも座標軸に沿って照らすライトを作成する必要がないことは明らかである。値を組み合わせたり、揃えたりして、面白い角度からライトを照らすことができる。

注 ライトの方向ベクトルを正規化する必要はないが、必ずベクトルのマグニチュードを指定すること。つまり、<0,0,0> の方向ベクトルは使用しない。


スポットライト プロパティ

C++ の D3DLIGHT8 構造体には、スポットライトでのみ使用する 3 つのメンバが含まれている。これらのメンバ (Falloff、Theta、および Phi) は、スポットライト オブジェクトの内部コーンと外部コーンの大きさを制御し、両方のコーンの間でライトがどのように減少するかを制御する。これらの特性の一般的な説明については、「スポットライト」を参照すること。

Theta 値はスポットライトの内部コーンのラジアン角度を表し、Phi 値は外部コーンのラジアン角度を表す。Falloff 値は、内部コーンの外側エッジと外部コーンの内側エッジとの間で、ライトの強度がどのように減少するかを制御する。ほとんどのアプリケーションでは、Falloff を 1.0 に設定して 2 つのコーン間でフォールオフが一様に生じるようにするが、必要に応じてこれ以外の値を設定することもできる。

フォールオフの計算において Microsoft® Direct3D® が使用する数学的モデルの詳細については、「スポットライト フォールオフ モデル」を参照すること。

次の図は、メンバの値の間にある関係と、これらの値がスポットライトの内部コーンと外部コーンに与える影響を示している。


ライトの使い方

ここでは、Microsoft® Direct3D® アプリケーションでのライトの使用方法について説明する。説明するトピックは、次のとおりである。

  • ライト プロパティの設定
  • ライトの有効/無効
  • ライト プロパティの取得


ライト プロパティの設定

C++ アプリケーションでライト プロパティを設定するには、D3DLIGHT8 構造体を用意し、次に IDirect3DDevice8::SetLight メソッドを呼び出す。SetLight メソッドは、デバイスがライト プロパティ セットをデバイス内部のライト プロパティのリストに配置する際のインデックスと、そのライト プロパティを定義する D3DLIGHT8 構造体のアドレスを受け取る。ライト プロパティの更新が必要なときは、新しい情報で SetLight を呼び出すことができる。

プロパティを割り当てられていないインデックスで SetLight メソッドを呼び出すたびに、システムはライト プロパティ セットを格納するためのメモリを割り当てる。アプリケーションでは、割り当てられているライトのサブセットを一度に有効にして、数多くのライトを設定できる。デバイスがサポートするアクティブなライトの最大数を決定するためにデバイス能力を取得するときは、D3DCAPS8 構造体の MaxActiveLights メンバをチェックする。ライトを使用する必要がなくなった場合は、そのライトを無効にするか、新しいライト プロパティ セットで上書きすることができる。

次の C++ のサンプル コードは、距離の増加によって減衰しない、白色のポイント ライトのプロパティを準備および設定する。

/*
* このコードでは、変数 g_pd3dDev は、IDirect3DDevice8 インターフェイスへの
* 有効なポインタであると仮定している。
 */
D3DLIGHT8 d3dLight;
HRESULT   hr;

// 構造体を初期化する。
ZeroMemory(&d3dLight, sizeof(D3DLIGHT8));

// 白色のポイント ライトの設定を行う。
d3dLight.Type = D3DLIGHT_POINT;
d3dLight.Diffuse.r  = 1.0f;
d3dLight.Diffuse.g  = 1.0f;
d3dLight.Diffuse.b  = 1.0f;
d3dLight.Ambient.r  = 1.0f;
d3dLight.Ambient.g  = 1.0f;
d3dLight.Ambient.b  = 1.0f;
d3dLight.Specular.r = 1.0f;
d3dLight.Specular.g = 1.0f;
d3dLight.Specular.b = 1.0f;

// ポイント ライトをシーンの上部でビューアの背後に配置する。
// これらの座標はワールド空間のものである。
// ユーザーはワールド空間内のどの位置座標にでも存在できる。
// このコードでは、
// ユーザーはワールド空間の原点にいると仮定している。
d3dLight.Position.x = 0.0f;
d3dLight.Position.y = 1000.0f;
d3dLight.Position.z = -100.0f;

// 減衰させない。
d3dLight.Attenuation0 = 1.0f;
d3dLight.dvRange      = 1000.0f;

// 最初のライトのプロパティ情報を設定する。
hr = d3dDevice->SetLight(0, &d3dLight);
if (FAILED(hr))
{
    // エラー処理コード。
}

ライト プロパティ セットは、再度 SetLight を呼び出していつでも更新できる。更新するライト プロパティ セットのインデックスと、新しいプロパティを含む D3DLIGHT8 構造体のアドレスを指定するだけである。

注 ライト プロパティ セットをデバイスに割り当てても、追加されるプロパティを持つ光源が有効になるわけではない。光源を有効にするには、デバイスに対して IDirect3DDevice8::LightEnable メソッドを呼び出す。


ライトの有効/無効

シーン内の光源のライト プロパティ セットをいったん割り当てると、デバイスに対して IDirect3DDevice8::LightEnable メソッドを呼び出すことで、その光源をアクティブにすることができる。新しく割り当てた光源は、デフォルトでは無効になっている。LightEnable メソッドは、2 つのパラメータを受け取る。第 1 パラメータには、メソッドで処理する光源のインデックス (0 から始まる) を設定する。第 2 パラメータには、ライトを有効にする場合は TRUE、無効にする場合は FALSE を設定する。

次のコードは、LightEnable メソッドを使用して、デバイスの光源プロパティのリスト内の最初の光源を有効にする方法を示している。

/*
* このコードでは、変数 d3dDevice は、IDirect3DDevice8 インターフェイスへの
* 有効なポインタであると仮定している。
 */
HRESULT hr;

hr = pd3dDevice->LightEnable(0, TRUE);
if (FAILED(hr))
{
    // エラー処理コード。
}

IDirect3Ddevice8::SetLight で設定するプロパティがないライトを有効または無効にする場合、LightEnable メソッドは以下の表のプロパティを持つ光源を作成し、その光源を有効または無効にする。

メンバ | デフォルト
Type | D3DLIGHT_DIRECTIONAL
Diffuse | (R:1, G:1, B:1, A:0)
Specular | (R:0, G:0, B:0, A:0)
Ambient | (R:0, G:0, B:0, A:0)
Position | (0, 0, 0)
Direction | (0, 0, 1)
Range | 0
Falloff | 0
Attenuation0 | 0
Attenuation1 | 0
Attenuation2 | 0
Theta | 0
Phi | 0


ライト プロパティの取得

C++ で、既存の光源のプロパティをすべて取得するには、デバイスに対して IDirect3DDevice8::GetLight メソッドを呼び出す。GetLight メソッドを呼び出すとき、プロパティを取得する光源の 0 から始まるインデックスを第 1 パラメータに渡し、D3DLIGHT8 構造体のアドレスを第 2 パラメータに渡す。デバイスは、D3DLIGHT8 構造体に値を設定して、指定されたインデックスの光源でそのデバイスが使用するライト プロパティを記述する。

次のサンプル コードは、この処理を示している。

/*
* このコードでは、変数 pd3dDevice は、IDirect3DDevice8 インターフェイスへの
* 有効なポインタであると仮定している。
 */
HRESULT hr;
D3DLIGHT8 light;

// 最初のライトについてのプロパティ情報を取得する。
hr = pd3dDevice->GetLight(0, &light);
if (FAILED(hr))
{
    // エラー処理コード。
}

デバイス内で割り当てられている光源の範囲外のインデックスを指定すると、GetLight メソッドは失敗し、D3DERR_INVALIDCALLを返す。


マテリアル

ここでは、マテリアルと Microsoft® Direct3D® アプリケーションでのマテリアルの使用方法について説明する。説明するトピックは、次のとおりである。

  • マテリアルとは
  • マテリアル プロパティ
  • マテリアルの使い方

デフォルトのマテリアル プロパティに関する注意 アプリケーションで、レンダリング処理にマテリアル プロパティが指定されていない場合は、デフォルトのマテリアルが使用される。デフォルトのマテリアルは、すべてのディフューズ ライト (白色など) を反射するが、アンビエント反射またはスペキュラ反射は生じず、エミッション色がない。


マテリアルとは

マテリアルは、3D シーンでポリゴンが光をどのように反射するか、またはどのように光を放射するように見えるかを指定する。本質的には、マテリアルは、Microsoft® Direct3D® がレンダリングするポリゴンについて次の情報を Direct3D に指示するプロパティの集合である。

  • ポリゴンによるアンビエント ライトとディフューズ ライトの反射方法
  • ポリゴンからのスペキュラ ハイライトの状態
  • ポリゴンが光を発しているように見せるかどうか

C++ で記述された、Direct3D アプリケーションでは、D3DMATERIAL8 構造体を使用してマテリアル プロパティを定義する。詳細については、「マテリアル プロパティ」を参照すること。


マテリアル プロパティ

マテリアル プロパティは、マテリアルのディフューズ、アンビエント反射、エミッション、およびスペキュラ ハイライト特性を詳細に指定する。Microsoft® Direct3D® は、D3DMATERIAL8 構造体にすべてのマテリアル プロパティ情報を保持する。マテリアル プロパティは、そのマテリアルを使用するポリゴンをラスタ化するときに Direct3D が使用する色に影響する。スペキュラ属性を除き、各プロパティは、マテリアルが所定の種類のライトの赤、緑、および青成分をどのくらい反射するかを表す RGBA 色と、アルファ ブレンディング係数 (RGBA 色のアルファ成分) として指定する。マテリアルのスペキュラ属性は、色および強度で指定する。詳細については、「ライティングとマテリアルのカラー値」を参照すること。

ディフューズ反射とアンビエント反射

D3DMATERIAL8 型の Diffuse および Ambient メンバは、シーン内でマテリアルがアンビエント ライトとディフューズ ライトをどのように反射するかを指定する。ほとんどのシーンでは、アンビエント ライトよりもディフューズ ライトの方がずっと多く使用されるため、色の決定においてはディフューズ反射が最も大きく影響する。さらに、ディフューズ ライトは向きを持っているため、その入射角は反射の全体的な強度に影響を与える。ディフューズ反射は、ライトが頂点法線と平行に頂点に当るときが最も強い。入射角が大きくなるにつれて、ディフューズ反射のエフェクトは減少する。次に示すように、反射光の量は入射光と頂点法線がなす角度の余弦である。

アンビエント ライトと同様、アンビエント反射は向きを持たない。アンビエント反射は、レンダリングしたオブジェクトの見かけの色への影響は少ないが、全体の色に影響し、マテリアルから反射するディフューズ ライトがまったくないか、ほんのわずかであるときに最も目立つ。マテリアルのアンビエント反射は、D3DRS_AMBIENT フラグを指定して IDirect3DDevice8::SetRenderState メソッドを呼び出すことでシーンに設定したアンビエント ライトの影響を受ける。

ディフューズ反射およびアンビエント反射は、ともに作用してオブジェクトで知覚される色を決める。これらは通常は同じ値である。たとえば、青色の水晶オブジェクトをレンダリングするには、ディフューズ ライトとアンビエント ライトの青成分のみ反射するマテリアルを作成する。この水晶を白色光で照らされた部屋に置くと青色に見える。しかし、赤色光しかない部屋では、同じ水晶でも黒く見える。これは、水晶のマテリアルが赤色光を反射しないためである。

エミッション

マテリアルを使用して、レンダリングしたオブジェクト自体が光を発しているように見せることができる。D3DMATERIAL8 構造体の Emissive メンバを使用して、エミッション光の色および透明度を指定する。エミッションはオブジェクトの色に影響する。たとえば、暗いマテリアルを明るくし、発光色の一部になることができる。

マテリアルのエミッション属性を使用して、オブジェクトが光を発しているように見せることができる。この方法では、シーンにライトを追加する際のオーバーヘッドが発生しない。青色の水晶の例で、シーン内のほかのオブジェクトにはライトを照らさずに、水晶だけが輝いているように見せる場合は、エミッション属性を使用するとよい。エミッション属性を持つマテリアルが発する光は、シーン内のほかのオブジェクトで反射できる光ではないので注意すること。この反射光を得るには、シーン内に追加のライトを配置する必要がある。

スペキュラ反射

スペキュラ反射はオブジェクト上にハイライトを作成し、オブジェクトが輝いているように見せる。D3DMATERIAL8 構造体には、スペキュラ ハイライト色とマテリアルの全体的な輝きを指定する 2 つのメンバが含まれる。Specular メンバを目的の RGBA 色 (最も一般的な色は白色または明るいグレーである) に設定して、スペキュラ ハイライトの色を決める。Power メンバに設定する値は、スペキュラ エフェクトのシャープさを制御する。

スペキュラ ハイライトを使用すると、すばらしいエフェクトが得られる。再び青色の水晶を例として考える。Power の値が大きいほど鮮明なスペキュラ ハイライトになり、水晶の輝きが増す。この値が小さいほどエフェクトの及ぶ領域は拡大するが、反射が鈍くなり水晶が霜で覆われたように見える。まったく光沢のないオブジェクトにするには、Power メンバをゼロに設定し、Specular の色を黒に設定する。思いどおりのリアルな表示になるように、さまざまな反射レベルを試してみる。次の図は、2 つの同じモデルを示している。左側のモデルではスペキュラ反射強度を 10 に設定し、右側のモデルではスペキュラ反射を設定していない。


マテリアルの使い方

ここでは、Microsoft® Direct3D® アプリケーションでのマテリアルの使用方法について説明する。説明するトピックは、次のとおりである。

  • マテリアル プロパティの設定
  • マテリアル プロパティの取得


マテリアル プロパティの設定

Microsoft® Direct3D® レンダリング デバイスでは、一度に 1 つのマテリアル プロパティのセットでレンダリングできる。

C++ アプリケーションの場合、システムで使用するマテリアル プロパティを設定するには、D3DMATERIAL8 構造体を用意し、次に IDirect3DDevice8::SetMaterial メソッドを呼び出す。

D3DMATERIAL8 構造体を用意するには、この構造体にプロパティ情報を設定して、レンダリングでの目的のエフェクトを作成する。次のコードは、シャープな白色のスペキュラ ハイライトがある、紫色のマテリアル用の D3DMATERIAL8 構造体を設定する。

D3DMATERIAL8 mat;

// ディフューズ反射を表す RGBA を設定する。
mat.Diffuse.r = 0.5f;
mat.Diffuse.g = 0.0f;
mat.Diffuse.b = 0.5f;
mat.Diffuse.a = 1.0f;

// アンビエント反射を表す RGBA を設定する。
mat.Ambient.r = 0.5f;
mat.Ambient.g = 0.0f;
mat.Ambient.b = 0.5f;
mat.Ambient.a = 1.0f;

// スペキュラ ハイライトの色とシャープさを設定する。
mat.Specular.r = 1.0f;
mat.Specular.g = 1.0f;
mat.Specular.b = 1.0f;
mat.Specular.a = 1.0f;
mat.Power = 50.0f;

// RGBA エミッション色を設定する。
mat.Emissive.r = 0.0f;
mat.Emissive.g = 0.0f;
mat.Emissive.b = 0.0f;
mat.Emissive.a = 0.0f;

D3DMATERIAL8 構造体を用意したら、レンダリング デバイスの IDirect3DDevice8::SetMaterial メソッドを呼び出してこのプロパティを適用する。このメソッドには、用意した D3DMATERIAL8 構造体のアドレスを唯一のパラメータとして指定する。デバイスのマテリアル プロパティの更新が必要なときは、新しい情報で SetMaterial を呼び出すことができる。以上の処理を次のサンプル コードに示す。

// このコードでは、このトピックの前の例で変数 mat に対して定義した
// マテリアル プロパティを使用する。pd3dDev は IDirect3DDevice8 インターフェイスへの
// 有効なポインタであると仮定する。
HRESULT hr;
hr = pd3dDev->SetMaterial(&mat);
if(FAILED(hr))
{
    // エラー処理コード。
}

Direct3D デバイスを作成する場合は、以下の表に示すように現在のマテリアルは自動的にデフォルトに設定される。

メンバ | 値
Diffuse | (R:1, G:1, B:1, A:0)
Specular | (R:0, G:0, B:0, A:0)
Ambient | (R:0, G:0, B:0, A:0)
Emissive | (R:0, G:0, B:0, A:0)
Power | (0.0)


マテリアル プロパティの取得

デバイスに対して IDirect3DDevice8::GetMaterial メソッドを呼び出して、レンダリング デバイスで現在使用しているマテリアル プロパティを取得する。IDirect3DDevice8::SetMaterial メソッドの場合とは異なり、GetMaterial では準備は必要ない。GetMaterial メソッドには、D3DMATERIAL8 構造体のアドレスを指定する。このメソッドは、終了前にこの構造体に現在のマテリアル プロパティの情報を書き込む。

// このコードでは、変数 pd3dDev は IDerect3DDevice8 インターフェイスへの
// 有効なポインタであると仮定する。
HRESULT hr;
D3DMATERIAL8 mat;

hr = pd3dDev->GetMaterial(&mat);
if(FAILED(hr))
{
    // エラー処理コード。
}


頂点フォーマット

ここでは、Microsoft® Direct3D® で頂点を指定するために理解しておく必要がある概念について説明し、頂点を宣言するためにアプリケーションで使用できる各種フォーマットの情報について説明する。説明するトピックは、次のとおりである。

  • 頂点フォーマットについて
  • 未トランスフォーム 未ライティングの頂点
  • 未トランスフォーム ライティング済みの頂点
  • トランスフォーム済み ライティング済みの頂点
  • トランスフォーム済み ライティング済みの頂点の機能
  • 柔軟な頂点フォーマットと頂点シェーダ


頂点フォーマットについて

柔軟な頂点フォーマット (FVF) のコードは、インターリーブされて格納される頂点の内容を単一データ ストリームに記述する。一般に、固定機能頂点処理パイプラインで処理されるデータを指定する。

Microsoft® Direct3D® アプリケーションでは、複数の方法でモデルの頂点を定義できる。柔軟な頂点定義 ("柔軟な頂点フォーマット" または "柔軟な頂点フォーマット コード" とも呼ぶ) がサポートされていることから、必要な頂点の成分のみアプリケーションで使用し、使用しない頂点の成分は削除できる。必要な頂点の成分のみ使用できるので、アプリケーションでメモリを節約でき、モデルのレンダリングに必要な処理帯域幅を最小限に抑えることができる。柔軟な頂点フォーマット フラグを組み合わせて使用して、頂点のフォーマット方法を指定する。

FVF 仕様にはポイント サイズのフォーマットも含まれ、D3DFVF_PSIZE によって指定する。このサイズは、非 TL 頂点についてはカメラ空間単位で、TL 頂点についてはデバイス空間単位で表される。

C++ アプリケーションでは、IDirect3DDevice8 インターフェイスのレンダリング メソッドにより、これらのフラグの組み合わせを受け取るメソッドを使用でき、その組み合わせを使用してプリミティブのレンダリング方法を決める。基本的には、これらのフラグは、アプリケーションでどの頂点の成分 (位置座標、頂点ブレンディング ウェイト、法線、色、およびテクスチャ座標の数とフォーマット) を使用するかをシステムに知らせ、また、Direct3D でレンダリング パイプラインのどの部分を頂点の成分に適用するかを間接的に知らせる。さらに、特定の頂点フォーマット フラグの有無によって、メモリに存在する頂点の成分フィールドと、省略した頂点の成分をシステムに知らせる。

デバイスの制限を調べるには、D3DFVFCAPS_DONOTSTRIPELEMENTS および D3DFVFCAPS_TEXCOORDCOUNTMASK 柔軟な頂点フォーマット フラグについてデバイスを問い合わせる。詳細については、D3DCAPS8 構造体の「FVFCaps メンバ」を参照すること。

頂点のフォーマット方法に関するシステム条件の中で重要なのは、データの表示順序である。次の図は、メモリ内のすべての頂点の成分の順序とそれに関係するデータ型を示している。

注 テクスチャ座標はさまざまなフォーマットで宣言でき、最少 1 要素の座標、最大 4 要素のテクスチャ座標 (2D 射影テクスチャ座標の場合) を使用してテクスチャを処理できる。詳細については、「テクスチャ座標フォーマット」を参照すること。マクロの D3DFVF_TEXCOORDSIZEn セットを使用して、頂点フォーマットで使用するテクスチャ座標フォーマットを識別するためのビット パターンを作成する。

アプリケーションがすべてのコンポーネントを使用するとは限らない。同次 W の逆数 (RHW) と頂点法線フィールドは互いに排他的である。また、ほとんどのアプリケーションで 8 つのテクスチャ座標セットをすべて使用するとも限らない。しかし、Direct3D にはこのような柔軟性がある。あるフラグを別のフラグと併用する場合には、いくつかの制限がある。たとえば、D3DFVF_XYZ フラグと D3DFVF_XYZRHW フラグは併用できない。この場合、未トランスフォームの頂点とトランスフォーム済みの頂点の両方を使用して、1 つの頂点の位置座標を定義することになるからである。

インデックス頂点ブレンディングを使用するには、D3DFVF_LASTBETA_UBYTE4 フラグは FVF の最後に置く必要がある。このフラグを指定すると、5 番目のブレンディング ウェイトは、フロートではなく DWORD として処理される。詳細については、「インデックス付き頂点ブレンディング」を参照すること。

次のコードは、D3DFVF_LASTBETA_UBYTE4 フラグを使用する FVF コードと、このフラグを使用しない FVF コードとの違いを示している。次に定義する FVF は、D3DFVF_LASTBETA_UBYTE4 フラグを使用していない。4 つのブレンディング インデックスを使用する場合は、フラグ D3DFVF_XYZ3 が存在する。これは、4 番目のブレンディング インデックスに対して、常に (1 - 最初の 3 つの合計) を使用するからである。

#define D3DFVF_BLENDVERTEX (D3DFVF_XYZB3|D3DFVF_NORMAL|D3DFVF_TEX1)

struct BLENDVERTEX
{
    D3DXVECTOR3 v;       // 頂点シェーダで v0 として参照される。
    FLOAT       blend1;  // 頂点シェーダで v1.x として参照される。
    FLOAT       blend2;  // 頂点シェーダで v1.y として参照される。
    FLOAT       blend3;  // 頂点シェーダで v1.z として参照される。
                         // v1.w = 1.0 - (v1.x + v1.y + v1.z)
    D3DXVECTOR3 n;       // 頂点シェーダで v3 として参照される。
    FLOAT       tu, tv;  // 頂点シェーダで v7 として参照される。
};

次に定義する FVF は、D3DFVF_LAST_UBYTE4 フラグを使用している。

#define D3DFVF_BLENDVERTEX (D3DFVF_XYZB4 | D3DFVF_LASTBETA_UBYTE4 |D3DFVF_NORMAL|D3DFVF_TEX1)

struct BLENDVERTEX
{
    D3DXVECTOR3 v;       // 頂点シェーダで v0 として参照される。
    FLOAT       blend1;  // 頂点シェーダで v1.x として参照される。
    FLOAT       blend2;  // 頂点シェーダで v1.y として参照される。
    FLOAT       blend3;  // 頂点シェーダで v1.z として参照される。
                         // v1.w = 1.0 - (v1.x + v1.y + v1.z)
    DWORD       indices; // 頂点シェーダで v2.xyzw として参照される。
    D3DXVECTOR3 n;       // 頂点シェーダで v3 として参照される。
    FLOAT       tu, tv;  // 頂点シェーダで v7 として参照される。
};

詳細については、「柔軟な頂点フォーマット フラグ」を参照すること。


未トランスフォーム 未ライティングの頂点

レンダリング メソッドに渡す頂点記述に D3DFVF_XYZ または D3DFVF_XYZBn フラグのいくつか、および D3DFVF_NORMAL フラグがある場合は、「未トランスフォーム 未ライティングの頂点」タイプとして識別される。「未トランスフォーム 未ライティングの頂点」を使用すると、アプリケーションは Microsoft® Direct3D® にその内部アルゴリズムを使用してすべてのトランスフォーム & ライティング処理を実行するよう効率的に要求できるD3DRS_LIGHTING レンダリング ステートを FALSE に設定して、レンダリングするプリミティブに対して Direct3D ライティング エンジンを無効にできる。

この頂点タイプは、アプリケーションで独自のトランスフォーム & ライティング エンジンを実装する必要がないので、ほとんどのアプリケーションで使用される。ただし、システムによって自動的に計算が実行されるため、各頂点に対していくらかの情報を指定しておく必要がある。

  • 未トランスフォームのモデル座標に頂点を指定することが求められる。次に、システムは、ワールド トランスフォーム、ビュー トランスフォーム、および射影トランスフォームをモデル座標に適用してシーン内に頂点を配置し、頂点の画面上での最終位置座標を決定する。
  • よりリアルなライティング エフェクトを出すために、頂点法線を含めることができる。頂点法線を含んでいない頂点をライティングで照らす場合、その頂点は 0 の内積を使用する。つまり、これらの頂点は入射光を受けないものとして処理される。システムは、カレント マテリアルに加えて、頂点法線を使用してライティング計算を実行する。詳細については、「面法線ベクトルと頂点法線ベクトル」、「ライト」、「マテリアル」、および「Direct3D のライティングにおける数学的計算」を参照すること。

これらの条件以外では、その他の頂点の成分を柔軟に使用または無視できる。たとえば、ディフューズ色またはスペキュラ色を未トランスフォームの頂点に含めることができる。これは Microsoft DirectX® 6.0 以前ではできなかった。各頂点に個々の色を含めると、マテリアル カラーのみ使用したライティング計算を実行するよりも、繊細で柔軟なシェーディング エフェクトが得られる。ただしこの場合、D3DRS_COLORVERTEX レンダリング ステートを使用して個々の頂点単位のカラーを有効にする必要がある。また、未トランスフォーム 未ライティングの頂点には、最大 8 つまでテクスチャ座標セットを含めることができる。

独自の頂点フォーマットを定義するときは、どの頂点の成分がアプリケーションで必要であるかに注意し、必ず正しく順序付けた構造体を宣言して、必要な順序で頂点の成分が表示されるようにしなければならない。次のサンプル コードは、位置座標、頂点法線、ディフューズ色、および 2 つのテクスチャ座標セットを含む有効な頂点フォーマット構造体を宣言する。

//
// この頂点の頂点フォーマット記述は、
// (D3DFVF_XYZ | D3DFVF_NORMAL |  D3DFVF_DIFFUSE | D3DFVF_TEX2) になる。
//
typedef struct _UNLITVERTEX
{
    float x, y, z;     // 位置座標
    float nx, ny, nz;  // 法線
    DWORD Diffuse;     // ディフューズ色
    float tu1, tv1;    // テクスチャ座標
    float tu2, tv2;
  tv2;
} UNLITVERTEX, *LPUNLITVERTEX;

この構造体の頂点記述は、柔軟な頂点フォーマット フラグ D3DFVF_XYZ、D3DFVF_NORMAL、D3DFVF_DIFFUSE、および D3DFVF_TEX2 の組み合わせになる。

詳細については、「頂点フォーマットについて」を参照すること。


未トランスフォーム ライティング済みの頂点

Microsoft® Direct3D® レンダリング メソッドで使用する頂点フォーマット記述に D3DFVF_XYZ フラグを含め、D3DFVF_NORMAL フラグを含めていない場合、その頂点は「未トランスフォーム ライティング済みの頂点」として識別される。フラグの依存および排他関係の詳細については、「柔軟な頂点フォーマット フラグ」を参照すること。

「未トランスフォーム ライティング済みの頂点」を使用すると、アプリケーションは Direct3D に頂点に対するライティング計算を実行しないように要求するが、Direct3D は以前に設定されたワールド行列、ビュー行列、および射影行列を使用して頂点をトランスフォームする。ライティング計算は実行されないので、頂点法線は必要ない。システムは、各頂点のディフューズ成分とスペキュラ成分をシェーディングに使用する。これらの色は任意に指定しても、独自のライティング公式を使用して計算してもよい。ディフューズ成分またはスペキュラ成分を含めない場合は、デフォルト カラーが使用される。ディフューズ色のデフォルト値は 0xFFFFFFFF で、スペキュラ色のデフォルト値は 0x0 である。

位置座標といくらかの色情報を含めるという点を除いては、その他の頂点タイプと同様、未ライティングの頂点フォーマットにテクスチャ座標セットを含めたり、無視することができる。

独自の頂点フォーマットを定義するときは、どの頂点の成分がアプリケーションで必要であるかに注意し、必ず正しく順序付けた構造体を宣言して、必要な順序で頂点の成分が表示されるようにしなければならない。次のサンプル コードは、ディフューズ頂点カラー、スペキュラ頂点カラー、および 3 つのテクスチャ座標セットを持つ、未トランスフォームでライティング済みの有効な頂点を宣言する。

//
// この頂点の頂点フォーマット記述は、
// (D3DFVF_XYZ | D3DFVF_DIFFUSE |  D3DFVF_SPECULAR | D3DFVF_TEX3) になる。
//
typedef struct _LITVERTEX {
    float x, y, z;   // 位置座標
    DWORD Diffuse;   // ディフューズ色
    DWORD Specular;  // スペキュラ色
    float tu1, tv1;  // テクスチャ座標
    float tu2, tv2;
    float tu3, tv3;
} LITVERTEX, *LPLITVERTEX;

この構造体の頂点記述は、柔軟な頂点フォーマット フラグ D3DFVF_XYZ、D3DFVF_DIFFUSE、D3DFVF_SPECULAR、および D3DFVF_TEX3 の組み合わせになる。

詳細については、「頂点フォーマットについて」を参照すること。


トランスフォーム済み ライティング済みの頂点

頂点フォーマット記述に D3DFVF_XYZRHW フラグを含めた場合、アプリケーションで「トランスフォーム済み ライティング済みの頂点」を使用することがシステムに通知される。これは、Microsoft® Direct3D® でワールド行列、ビュー行列、または射影行列を使用して頂点をトランスフォームせず、ライティング計算も実行しないことを意味している。つまり、Direct3D は、アプリケーションでこれらの処理が実行済みであると見なしている。これにより、既存の 3D アプリケーションを Direct3D に移植するとき、トランスフォーム済み ライティング済みの頂点がそのまま使える。要するに、Direct3D は、「トランスフォーム済み ライティング済みの頂点」をまったく変更しない。ドライバに直接渡してラスタ化を実行する。

未トランスフォームの頂点とライティングに関連付けられている頂点フォーマット フラグ (D3DFVF_XYZ と D3DFVF_NORMAL) は、D3DFVF_XYZRHW がある場合は使用できない。フラグの依存および排他関係の詳細については、「柔軟な頂点フォーマット フラグ」を参照すること。

頂点位置座標を指定するときは、トランスフォーム済みのものを指定しなければならない。x と y の値はスクリーン座標内に存在している必要があり、z は Z バッファで使用されるピクセルの深度値でなければならない。z 値は 0.0 ～ 1.0 の値である。0.0 はユーザーに最も近い位置座標で、1.0 は可視領域内の最も遠い位置座標である。「トランスフォーム済み ライティング済みの頂点」は、位置座標のすぐ後に RHW 値 (同次 W の逆数) を含んでいなければならない。RHW は、射影空間内で頂点が存在する同次ポイント (x、y、z、w) からの W 座標の逆数である。この値は、z 軸に沿った、視点から頂点までの距離になることが多い。

位置座標と RHW の条件を除けば、この頂点フォーマットは、「未トランスフォーム ライティング済みの頂点」と同じである。これまでの説明を以下にまとめる。

  • このフォーマットの場合、ライティング計算は実行されないので、頂点法線は必要ない。
  • ディフューズ色またはスペキュラ色を指定できる。これを指定しない場合は、0x0 がスペキュラ色に、0xFFFFFFFF がディフューズ色に使用される。
  • テクスチャ座標セットは、最大 8 つまで使用できる。また、使用しなくてもよい。

独自の頂点フォーマットを定義するときは、どの頂点の成分がアプリケーションで必要であるかに注意し、必ず正しく順序付けた構造体を宣言して、必要な順序で頂点の成分が表示されるようにしなければならない。次のサンプル コードは、ディフューズ頂点カラー、スペキュラ頂点カラー、およびテクスチャ座標セットを 1 つだけ持つ、トランスフォーム済みでライティングのある有効な頂点を宣言する。

//
// この頂点の頂点フォーマット記述は、
// (D3DFVF_XYZRHW | D3DFVF_DIFFUSE |  D3DFVF_SPECULAR | D3DFVF_TEX1) になる。
//
typedef struct _TRANSLITVERTEX {
    float x, y;      // スクリーン座標
    float z;         // Z バッファ深度
    float rhw;       // 同次 W の逆数
    DWORD Diffuse;   // ディフューズ色
    DWORD Specular;  // スペキュラ色
    float tu1, tv1;  // テクスチャ座標
} TRANSLITVERTEX, *LPTRANSLITVERTEX;

この構造体の頂点記述は、柔軟な頂点フォーマット フラグ D3DFVF_XYZRHW、D3DFVF_DIFFUSE、D3DFVF_SPECULAR、および D3DFVF_TEX1 の組み合わせになる。

詳細については、「頂点フォーマットについて」を参照すること。


トランスフォーム済み ライティング済みの頂点の機能

柔軟な頂点フォーマット (FVF) コードで指定された頂点データは、トランスフォーム済みまたは未トランスフォームのいずれかのプロパティを持つ。FVF 指定のトランスフォーム済み頂点は、TL (transformed and lit) 頂点と呼ばれる。Microsoft® Direct3D® for Microsoft DirectX® 8.0 では、前リリースと同様、TL 頂点データがサポートされている。しかし、TL 頂点は、未トランスフォームの頂点には適用されないいくつかの条件に影響される。

TL 頂点データは、FVF コードで指定された頂点に対してのみ有効であり、プログラム可能な頂点シェーダの入力としては使用できない。プログラム可能な頂点シェーダは、各種フォームのトランスフォーム済み頂点データを使用できる柔軟性があるが、変換はシェーダの一部であって頂点データのプロパティではないため、FVF の TL 頂点データとは異なっている。TL 頂点データは、FVF コードによって定義されているため、継承的に単一ストリームでもある。

TL 頂点データが Direct3D でクリッピングされるかどうかは保証がないため、TL 頂点プリミティブを Direct3D に送ってレンダリングするには、事前にクリッピングする必要がある。x 値と y 値は、ビューポートに対して、またはデバイス ガードバンドがあればそれに対して、クリッピングする必要がある。TL 頂点の z 値は、0 と 1 の間でなければならない (0 と 1 を含む)。また RHW 値は、[0 < 1/D3DCAPS8.MaxVertexW] の範囲内でなければならない。RHW 要件は、w 値がハードウェア ラスタ化デバイスのサポート範囲内に収まるようにすることである。頂点の w および RHW 範囲がパースペクティブ射影トランスフォームの結果である場合、射影行列のすべての値にスケールを適用して修正できる。

注 D3DPMISCCAPS_CLIPTLVERTS が設定されている場合、デバイスはトランスフォーム後の頂点データを z および (x, y) ビューポートの限界に対してクリッピングする。ユーザー定義のクリップ面に対するクリッピングは、トランスフォーム後の頂点データについてはサポートされていない。D3DPMISCCAPS_CLIPTLVERTS 能力が設定されていない場合、アプリケーションがこれらのプリミティブを z 境界と少なくとも x と y のガードバンドの範囲に対してクリッピングする必要がある。一方、トランスフォーム前の頂点についてのクリッピングは、続けて別の描画呼び出しが行われるような、転送先頂点バッファに対する描画呼び出しと頂点処理呼び出しの両方で十分にサポートされている。このサポートには、z と (x, y) ビューポート限界に加えてユーザー定義のクリップ面も含まれる。

TL 頂点データは、常に、ドライバに直接渡されてレンダリングされる。TL 頂点データを持つ頂点バッファを使用すると、ドライバがこれらの頂点バッファを AGP またはビデオ メモリに割り当てる処理速度がかなり向上する。TL 頂点バッファの割り当ては、非 TL 頂点データ (FVF または非 FVF のいずれか) がドライバによって割り当てられない場合でも、ドライバによって割り当てることができる。これは、トランスフォームおよびライティングをサポートしないハードウェア デバイス上で動作する場合と同様である。

詳細については、「トランスフォーム済み ライティング済みの頂点」を参照すること。


柔軟な頂点フォーマットと頂点シェーダ

Microsoft® Direct3D® for Microsoft DirectX® 8.0 は、単一入力ストリームの固定機能頂点処理パイプラインを使用するためのプログラミング モデルを簡素化し、これまでの DirectX リリースと同様の機能を提供する。この場合、頂点シェーダは、現在の頂点シェーダを設定するときに頂点シェーダ ハンドルの代わりとして渡された柔軟な頂点フォーマット (FVF) コードから成る。頂点シェーダのハンドル空間はランタイム ライブラリによって管理され、この用途のために、有効な FVF コードのハンドルが予約されている。

FVF コードを現在の頂点シェーダとして設定すると、頂点処理はストリーム ゼロからのみロードされ、頂点要素は FVF コードの定義に従って変換される。

次のサンプル コードは、C++ アプリケーションにおける FVF コードの頂点シェーダとしての使用方法を示している。

まず最初に、カスタム頂点タイプの構造体を定義し、頂点を初期化する。この例では、三角形をレンダリングするため、3 つの頂点が初期化される。

// このサンプル コードで、d3dDevice は、
// IDirect3DDevice8 インターフェイスへの有効なポインタであるとする。

struct CUSTOMVERTEX
{
    FLOAT x, y, z, rhw; // 頂点のトランスフォーム後の位置座標。
    DWORD color;        // 頂点カラー。
};

#define D3DFVF_CUSTOMVERTEX (D3DFVF_XYZRHW|D3DFVF_DIFFUSE)

CUSTOMVERTEX g_Vertices[] =
{
    { 150.0f,  50.0f, 0.5f, 1.0f, 0xffff0000, }, // x, y, z, rhw, color
    { 250.0f, 250.0f, 0.5f, 1.0f, 0xff00ff00, },
    {  50.0f, 250.0f, 0.5f, 1.0f, 0xff00ffff, },
};

次に、ストリーム ゼロを使用してプリミティブをレンダリングする。

d3dDevice->SetStreamSource( 0, g_pVB, sizeof(CUSTOMVERTEX) );
d3dDevice->SetVertexShader( D3DFVF_CUSTOMVERTEX );
d3dDevice->DrawPrimitive( D3DPT_TRIANGLELIST, 0, 1 );

詳細については、「頂点シェーダ」を参照すること。


テクスチャ

テクスチャは、コンピュータでリアルな 3D 画像を生成するための強力なツールである。Microsoft® Direct3D® では、多彩なテクスチャ機能をサポートしており、高度なテクスチャ技術を簡単に利用できる。ここでは、Direct3D でのテクスチャの用途とその使用方法について説明する。説明するトピックは、次のとおりである。

  • 基本的なテクスチャ処理の概念
  • テクスチャ座標
  • テクスチャ リソース
  • テクスチャ フィルタリング
  • テクスチャ ラッピング
  • テクスチャ ブレンディング
  • 圧縮したテクスチャ リソース
  • ボリューム テクスチャ リソース
  • 自動テクスチャ管理
  • テクスチャ処理におけるハードウェアによる制約


基本的なテクスチャ処理の概念

ここでは、Microsoft® Direct3D® でのテクスチャ処理の理解に必要な最も基本的な概念について説明する。説明するトピックは、次のとおりである。

  • テクスチャとは
  • テクスチャ アドレッシング モード
  • テクスチャのダーティー領域
  • テクスチャ パレット


テクスチャとは

これまではコンピュータで生成する 3D 画像は、当時としては一般に高度なものではあったが、プラスチックが光っているように見える傾向があった。当時の 3D 画像には、傷、ひび、指紋、汚れなどを 3D オブジェクトでリアルに表現する方法がなかった。近年、開発者の間では、コンピュータでよりリアルな 3D 画像を生成するためのツールとして、テクスチャが広く使用されるようになっている。

テクスチャという用語は、普通、オブジェクトの滑らかさや粗さをいう。しかし、コンピュータ グラフィックス分野におけるテクスチャとは、オブジェクトをテクスチャのように見せるピクセル カラーのビットマップのことである。

Microsoft® Direct3D® のテクスチャはビットマップであるため、ビットマップでさえあれば Direct3D プリミティブに適用できる。たとえば、アプリケーションでは、木目模様に見えるオブジェクトを作成して操作することができる。丘を形成する 3D プリミティブ セットに、芝生、土、岩を適用できる。その結果、本物のような丘の斜面ができあがる。テクスチャ処理では、また、道路脇の標識、崖の岩層などのエフェクトを作成したり、大理石の床を作成することもできる。

さらに、Direct3D は、テクスチャ ブレンディング (透明度あり/なし) やライト マッピングなど、より高度なテクスチャ技法もサポートしている。詳細については、「テクスチャ ブレンディング」および「テクスチャによるライト マッピング」を参照すること。

アプリケーションで、ハードウェア アブストラクション レイヤ (HAL) デバイス、またはソフトウェア デバイス (「デバイスの種類」を参照すること) を作成する場合は、8 ビット、16 ビット、24 ビット、または 32 ビットのテクスチャを使用できる。


テクスチャ アドレッシング モード

ここでは、Microsoft® Direct3D® テクスチャ アドレッシング モードの用途およびその使用方法について説明する。説明するトピックは、次のとおりである。

  • テクスチャ アドレッシング モードとは
  • ラップ テクスチャ アドレッシング モード
  • ミラー テクスチャ アドレッシング モード
  • クランプ テクスチャ アドレッシング モード
  • 境界色テクスチャ アドレッシング モード
  • テクスチャ アドレッシング モードの設定と取得
  • テクスチャ アドレッシング モードとテクスチャ ラッピング
  • テクスチャ アドレッシングにおけるデバイス制限


テクスチャ アドレッシング モードとは

Microsoft® Direct3D® アプリケーションでは、どのプリミティブのどの頂点にもテクスチャ座標を割り当てることができる。詳細については、「テクスチャ座標」を参照すること。通常、頂点に割り当てるテクスチャ座標 u および v の範囲は、0.0 と 1.0 を含む 0.0 ～ 1.0 である。しかし、この範囲外のテクスチャ座標を割り当てて、特殊なテクスチャ エフェクトを作成することもできる。

テクスチャ アドレッシング モードを設定することで、[0.0, 1.0] の範囲外のテクスチャ座標で Direct3D が行う処理を制御できる。たとえば、アプリケーションでテクスチャ アドレッシング モードを設定して、プリミティブ全体にテクスチャをタイルのように張ることができる。次のトピックでさらに詳しく説明する。

  • ラップ テクスチャ アドレッシング モード
  • ミラー テクスチャ アドレッシング モード
  • クランプ テクスチャ アドレッシング モード
  • 境界色テクスチャ アドレッシング モード


ラップ テクスチャ アドレッシング モード

D3DTEXTUREADDRESS 列挙型の D3DTADDRESS_WRAP メンバで指定するラップ テクスチャ アドレッシング モードでは、Microsoft® Direct3D® はすべての整数接合でテクスチャを繰り返し適用する。たとえば、アプリケーションで正方形プリミティブを作成し、テクスチャ座標 (0.0,0.0)、(0.0,3.0)、(3.0,3.0)、および (3.0,0.0) を指定する場合を考える。テクスチャ アドレッシング モードを D3DTADDRESS_WRAP に設定すると、u および v の両方向でテクスチャが 3 回適用される。

次の図にこれを示す。

このテクスチャ アドレッシング モードのエフェクトは、ミラー モードのエフェクトに類似する部分がある。詳細については、「ミラー テクスチャ アドレッシング モード」を参照すること。


ミラー テクスチャ アドレッシング モード

D3DTEXTUREADDRESS 列挙型の D3DTADDRESS_MIRROR メンバで指定するミラー テクスチャ アドレッシング モードでは、Microsoft® Direct3D® はすべての整数境界でテクスチャをミラーリングする。たとえば、アプリケーションで正方形プリミティブを作成し、テクスチャ座標 (0.0,0.0)、(0.0,3.0)、(3.0,3.0)、および (3.0,0.0) を指定する場合を考える。テクスチャ アドレッシング モードを D3DTADDRESS_MIRROR に設定すると、u および v の両方向でテクスチャが 3 回適用される。テクスチャが適用されるその他のすべての行と列は、直前の行または列の鏡像になる。

次の図にこれを示す。

このテクスチャ アドレッシング モードのエフェクトは、ラップ モードのエフェクトに類似する部分がある。詳細については、「ラップ テクスチャ アドレッシング モード」を参照すること。


クランプ テクスチャ アドレッシング モード

D3DTEXTUREADDRESS 列挙型の D3DTADDRESS_CLAMP メンバで指定するクランプ テクスチャ アドレッシング モードでは、Microsoft® Direct3D® はテクスチャ座標を [0.0, 1.0] の範囲に制限する。つまり、テクスチャを 1 回適用し、次に、エッジのピクセルの色を塗り付けていく。たとえば、アプリケーションで正方形プリミティブを作成し、テクスチャ座標 (0.0,0.0)、(0.0,3.0)、(3.0,3.0)、および (3.0,0.0) をそのプリミティブの頂点に割り当てる場合を考える。テクスチャ アドレッシング モードを D3DTADDRESS_CLAMP に設定すると、テクスチャが 1 回適用される。最初の列と最後の行のピクセル カラーが、プリミティブの上と右にそれぞれ広がっていく。

次の図にこれを示す。


境界色テクスチャ アドレッシング モード

D3DTEXTUREADDRESS 列挙型の D3DTADDRESS_BORDER メンバで指定する境界色テクスチャ アドレッシング モードでは、Microsoft® Direct3D® は 0.0 と 1.0 を含む 0.0 ～ 1.0 の範囲外のすべてのテクスチャ座標に対して、境界色と呼ばれる任意の色を使用する。

次の図は、この処理を示している。この図では、アプリケーションは赤色の境界色を使用してテクスチャをプリミティブに適用するように指定している。

アプリケーションでは、IDirect3DDevice8::SetTextureStageState を呼び出して境界色を設定する。これを呼び出すときの第 1 パラメータには目的のテクスチャ ステージ識別子を設定し、第 2 パラメータには D3DTSS_BORDERCOLOR ステージ ステート値を設定し、第 3 パラメータには新しい RGBA 境界色を設定する。


テクスチャ アドレッシング モードの設定と取得

IDirect3DDevice8::SetTextureStageState メソッドを呼び出して、各テクスチャ ステージにテクスチャ アドレッシング モードを設定できる。第 1 パラメータに目的のテクスチャ ステージ識別子を指定する。第 2 パラメータに D3DTSS_ADDRESSU、D3DTSS_ADDRESSV、または D3DTSS_ADDRESSW 値を設定して、u、v、または w アドレッシング モードを個別に更新する。SetTextureStageState に渡す第 3 パラメータは、設定されているモードを判別する。これには、D3DTEXTUREADDRESS 列挙型のいずれのメンバを指定してもかまわない。テクスチャ ステージの現在のテクスチャ アドレッシング モードを取得するには、IDirect3DDevice8::GetTextureStageState を呼び出し、D3DTEXTURESTAGESTATETYPE 列挙の D3DTSS_ADDRESSU、D3DTSS_ADDRESSV、または D3DTSS_ADDRESSW メンバを使用して、情報の取得対象のアドレッシング モードを識別する。


テクスチャ アドレッシング モードとテクスチャ ラッピング

Direct3D を使用して、アプリケーションではテクスチャ ラッピングを実行できる。テクスチャ アドレッシング モードを D3DTADDRESS_WRAP に設定することと、テクスチャ ラッピングを実行することとは同じではないことに注意すること。テクスチャ アドレッシング モードを D3DTADDRESS_WRAP に設定すると、現在のプリミティブに適用される転送元テクスチャのコピーが複数生成される。テクスチャ ラッピングを有効にすると、テクスチャ処理されたポリゴンをシステムがラスタ処理する際の方法が変更される。詳細については、「テクスチャ ラッピング」を参照すること。

テクスチャ ラッピングを効果的に有効にすると、[0.0, 1.0] 外にあるテクスチャ座標を無効にでき、このような不適切なテクスチャ座標のラスタ化の動作を未定義にできる。テクスチャ ラッピングが有効になっていると、テクスチャ アドレッシング モードは使用されない。テクスチャ ラッピングが有効になっている場合には、アプリケーションで指定するテクスチャ座標が0.0 より小さく、または 1.0 より大きくならないように注意すること。


テクスチャ アドレッシングにおけるデバイス制限

一般に、システムでは 0.0 ～ 1.0 (0.0 と 1.0 を含む) の範囲外にあるテクスチャ座標でも使用できるが、多くの場合、その許容範囲はハードウェア制限によって影響される。デバイス能力を取得すると、レンダリング デバイスはこの制限を D3DCAPS8 構造体の MaxTextureRepeat メンバに知らせる。このメンバ内の値は、デバイスで使用可能なテクスチャ座標の全範囲を示す。たとえば、この値が 128 の場合、入力テクスチャ座標は -128.0 ～ +128.0 の範囲内になければならない。この範囲外のテクスチャ座標を持つ頂点を渡すと無効になる。自動テクスチャ座標生成およびテクスチャ座標トランスフォームの結果として生成されたテクスチャ座標に対しても、これと同じ制限が適用される。

MaxTextureRepeat の解釈も D3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZE 能力ビットによって変わる。このビットを設定すると、D3DCAPS8 の MaxTextureRepeat メンバの値が定義どおりに正確に使用される。ただし、D3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZE が設定されていない場合は、テクスチャ反復制限は、テクスチャ座標によってインデックス化されたテクスチャのサイズに依存する。この場合、有効なテクスチャ座標の範囲を計算するために、MaxTextureRepeat は、現在のテクスチャ サイズによって最大詳細レベルでスケーリングされる必要がある。たとえば、テクスチャの寸法が 32 で、MaxTextureRepeat 値が 512 の場合、実際の有効なテクスチャ座標範囲は 512/32 = 16 となる。したがって、このデバイスでは -16.0 ～ +16.0 の範囲内にテクスチャ座標が存在する必要がある。


テクスチャのダーティー領域

アプリケーションでは、テクスチャ上にダーティー領域を指定して、テクスチャのどのサブセットをコピーするかを最適化できる。ダーティーとしてマークされ領域のみが、IDirect3DDevice8::UpdateTexture 呼び出しによってコピーされる。ただし、ダーティー領域はアライメントを最適化するために拡大されることがある。テクスチャ作成時には、テクスチャ全体がダーティーと見なされる。ダーティー状態のテクスチャに影響を与える処理は、以下の 4 つである。

  • テクスチャにダーティー領域を追加する。
  • テクスチャ内のバッファのいくつかをロックする。この処理では、ロックされた領域をダーティー領域として追加する。アプリケーションでは、実際のダーティー領域がよくわかっていれば、このダーティー領域の自動更新はオフにできる。
  • IDirect3DDevice8::CopyRects の転送先にテクスチャを使用すると、テクスチャ全体がダーティーとしてマークされる。
  • UpdateTexture の転送元にテクスチャを使用すると、転送元テクスチャのダーティー領域がすべてクリアされる。

ダーティー領域はミップマップ テクスチャの最上位レベルに設定され、UpdateTexture は、ダーティー領域をミップ チェーンまで拡大して各サブレベルでコピーされるバイト数を最小限に抑えることができる。サブレベル ダーティー領域の座標は外側に丸められる、つまり小数部分はテクスチャに最も近接するエッジに丸められることに注意すること。

テクスチャ タイプによってダーティー領域のタイプも異なるため、テキスチャ タイプごとにメソッドがある。2D テクスチャはダーティー矩形を、ボリューム テクスチャはボックスを使用する。

  • IDirect3DCubeTexture8::AddDirtyRect
  • IDirect3DTexture8::AddDirtyRect
  • IDirect3DVolumeTexture8::AddDirtyBox

上記メソッドの pDirtyRect または pDirtyBox パラメータに NULL を渡すと、ダーティー領域が拡大してテクスチャ全体を覆う。

各ロッキング メソッドは D3DLOCK_NO_DIRTY_UPDATE を取り、これによって、テクスチャのダーティー状態が変更されるのを防ぐことができる。詳細については、「リソースのロック」を参照すること。

アプリケーションは、ロック処理使用可能時に、領域のトゥルー セットに関する詳細情報が変更されたときは、D3DLOCK_NO_DIRTY_UPDATE を使用する。(最上位レベルまでロックまたはコピーしないで) テクスチャのサブレベルのみをロックまたはコピーしても、そのテクスチャのダーティー領域は更新されないことに注意すること。アプリケーションでも、最上位レベルをロックせずに下位レベルをロックしても、ダーティー領域は更新されない。


テクスチャ パレット

Microsoft® Direct3D® for Microsoft DirectX® 8.0 は、IDirect3DDevice8 オブジェクトに関連付けられた 256 エントリのパレット セットによるパレット テクスチャをサポートする。パレットをカレントにするには、IDirect3DDevice8::SetCurrentTexturePalette メソッドを呼び出す。カレント パレットは、すべてのアクティブ テクスチャ ステージのすべてのパレット テクスチャに使用される。IDirect3DDevice8::SetPaletteEntries は、パレットの 256 エントリをすべて更新する。各エントリは、フォーマット D3DFMT_A8R8G8B8 の PALETTEENTRY 構造体である。すべてのエントリはデフォルトで 0xFFFFFFFF に設定される。DirectX 8.0 の時点では、PALLETTEENTRY 構造体の peFlags メンバは、Microsoft Platform Software Development Kit (SDK) で説明されているようには動作しないことに注意すること。peFlags メンバは今後、8 ビットのパレット化されたフォーマットのアルファ チャネルである。

IDirect3DDevice8 パレットは、アルファ チャネルを含む。このアルファ チャネルは、デバイスがパレットからのアルファ チャネルをサポートすることを示す D3DPTEXTURECAPS_ALPHAPALETTE デバイス能力フラグが設定されているときに使用できる。パレット アルファ チャネルは、テクスチャ フォーマットにアルファ チャネルがない場合に使用する。デバイスがパレットからのアルファをサポートせず、テクスチャ フォーマットにアルファ チャネルがない場合は、0xFF の値がアルファに使用される。

最大で 16,384 のパレットがある。パレット セットに関連付けられるメモリ リソースは、アプリケーションが参照するパレットの最大数に比例するため、パレット番号には、ゼロから始まる連続する数を使用しなければならない。


テクスチャ座標

ここでは、テクスチャ座標の概念、テクスチャ座標フォーマット、およびテクスチャ座標フォーマットを操作する Microsoft® Direct3D® のサービスについて説明する。説明するトピックは、次のとおりである。

  • テクスチャ座標について
  • テクセルとピクセル間の直接マッピング
  • テクスチャ座標フォーマット
  • テクスチャ座標処理


テクスチャ座標について

ほとんどのテクスチャは、ビットマップ同様、カラー値の 2 次元配列である。ただし、キューブ環境マップ テクスチャは除く。詳細については、「キューブ環境マップ」を参照すること。個々のカラー値は、テクスチャ要素またはテクセルと呼ばれる。各テクセルは、テクスチャ内の一意のアドレスを持つ。このアドレスは、それぞれ u と v で表される行と列の番号であると考えることができる。

テクスチャ座標はテクスチャ空間にある。つまり、テクスチャ座標は、テクスチャ内の (0,0) を基準にした相対位置座標に存在する。テクスチャを 3D 空間のプリミティブに適用するとき、そのテクセル アドレスをオブジェクト座標にマッピングしなければならない。その後、このアドレスをスクリーン座標、つまりピクセル位置座標に平行移動する必要がある。

Microsoft® Direct3D® は、テクスチャ空間のテクセルをスクリーン空間のピクセルに直接マッピングする。これにより、中間の手順が省略され、効率が高まる。このマッピング処理は、実際は逆マッピングである。つまり、スクリーン空間の各ピクセルについて、テクスチャ空間の対応するテクセル位置座標が計算される。このポイントまたはこの周囲でテクスチャ カラーがサンプリングされる。このサンプリング処理は、テクスチャ フィルタリングと呼ばれる。詳細については、「テクスチャ フィルタリング」を参照すること。

テクスチャの各テクセルは、テクセル座標で指定できる。しかし、テクセルをプリミティブにマッピングするためには、Direct3D は、すべてのテクスチャのすべてのテクセルに対して同一のアドレス範囲を必要とする。したがって、すべてのテクセル アドレスが 0.0 ～ 1.0 の範囲にある包括的アドレス指定スキームが使用される。2D デカルト座標が x、y 座標で指定されるのと同様、Direct3D アプリケーションでは u と v の値でテクスチャ座標を指定する。実際には、0.0 ～ 1.0 の範囲外のテクスチャ座標を処理することも可能で、テクスチャ アドレッシングで設定するパラメータを使用してこの処理を行う。詳細については、「テクスチャ アドレッシング モード」を参照すること。

この結果、同一のテクスチャ アドレスを異なるテクスチャの異なるテクセルにマッピングできる。次の図では、テクスチャ アドレス (0.5,1.0) を使用している。しかし、これらのテクスチャはサイズが異なるため、テクスチャ アドレスは異なるテクセルにマッピングされる。左側のテクスチャ 1 は 5x5 である。テクスチャ アドレス (0.5,1.0) はテクセル (2,4) にマッピングされる。右側のテクスチャ 2 は 7x7 である。テクスチャ アドレス (0.5,1.0) はテクセル (3,6) にマッピングされる。

次の図は、簡単なテクセル マッピング処理を示している実際、これは非常に単純な例である。詳細については、「テクセルとピクセル間の直接マッピング」を参照すること。

この例では、図の左側のピクセルを観念化して色付きの正方形で示す。このピクセルの 4 つの角のアドレスは、オブジェクト空間の 3D プリミティブにマッピングされる。ピクセルの形状は、3D 空間のプリミティブの形状と表示角度が原因で歪むことが多い。次に、ピクセルの角に対応する、プリミティブ上のサーフェス領域の角が、テクスチャ空間にマッピングされる。このマッピング処理によってピクセルの形状が再び歪むが、これが一般的である。ピクセルの最終的なカラー値は、ピクセルがマッピングされる領域のテクセルから計算される。テクスチャ フィルタリング メソッドを設定するときに Direct3D がピクセル カラーを得るために使用するメソッドを決める。詳細については、「テクスチャ フィルタリング」を参照すること。

アプリケーションは、テクスチャ座標を直接頂点に割り当てることができる。この機能によって、プリミティブにマッピングするテクスチャの部分を決めることができる。たとえば、次の図のテクスチャとまったく同じサイズの矩形プリミティブを作成する場合を考える。この例では、アプリケーションでテクスチャ全体を壁全体にマッピングする。アプリケーションがプリミティブの頂点に割り当てるテクスチャ座標は、(0.0,0.0)、(1.0,0.0)、(1.0,1.0)、および (0.0,1.0) である。

壁の高さを 1/2 だけ小さくする場合は、小さな壁に合わせてテクスチャを歪めるか、Direct3D がテクスチャの下半分を使用するようにテクスチャ座標を割り当てることができる。

小さな壁に合わせてテクスチャを歪めたり、スケーリングしたりする場合、使用するテクスチャ フィルタリング メソッドによって画質が変わる。詳細については、「テクスチャ フィルタリング」を参照すること。

Direct3D で小さな壁に対してテクスチャの下半分を使用するようにテクスチャ座標を割り当てる場合、アプリケーションがこのプリミティブの頂点に割り当てるテクスチャ座標は、(0.0,0.0)、(1.0,0.0)、(1.0,0.5)、および (0.0,0.5) になる。Direct3D は、テクスチャの下半分を壁に適用する。

頂点のテクスチャ座標が 1.0 を超えていてもかまわない。0.0 ～ 1.0 の範囲外のテクスチャ座標を頂点に割り当てるときは、テクスチャ アドレッシング モードも設定しなければならない。詳細については、「テクスチャ アドレッシング モード」を参照すること。


テクセルとピクセル間の直接マッピング

スクリーン上のピクセルにテクセルを直接マッピングするなど、アプリケーションでは通常、シーン内のジオメトリにテクスチャを適用する必要がある。たとえば、テクスチャ内のテキストをシーン内のオブジェクトに表示する必要があるアプリケーションを考える。テクスチャ内のテキスト情報をはっきりと表示するには、テクスチャを施すジオメトリが、テクスチャ フィルタリングによって崩れていないテクセルを確実に受け取るための何らかの方法が必要である。これが行われないと、ぼんやりした画像になったり、ポイント サンプル テクスチャ フィルタリングの場合にはエッジが粗くなる可能性がある。

Microsoft® Direct3D® では、画像とテクスチャのフィルタリングをサポートする一方で、ピクセルとテクスチャのサンプリング ルールは、ピクセルとテクスチャのサンプリングを単一化するように慎重に定義されているため、テクスチャのテクセルを取得してスクリーン上のピクセルに直接マッピングする処理は重要で、困難な作業になることが多い。そのため、頂点に対する浮動小数点テクスチャ座標が、ラスタライザで使用する整数ピクセル座標にどのようにマッピングされるかについて十分に理解しておく必要がある。

Direct3D では、次の計算を実行して、浮動小数点テクスチャ座標をテクセル アドレスにマッピングする。

これらの公式では、Tx と Ty は水平方向と垂直方向の出力テクセル座標、u と v は頂点に対して提供される水平方向と垂直方向のテクスチャ座標である。Mx と My 要素は、現在のミップマップ レベルでの水平方向と垂直方向のテクセル数を表す。説明の後半では、テクセルとピクセル間の水平方向マッピングについて解説する。垂直方向マッピングは水平方向にマッピングする場合と同じである。

テクスチャ座標の上限と下限の 0.0 と 1.0 をこれらの公式に代入すると、テクスチャ座標 0.0 は反復テクスチャ マップの最初と最後のテクセル間の中間点にマッピングされる。テクスチャ座標 1.0 は、現在の補間テクスチャ マップの最後のテクセルと次の補間テクスチャ マップ間の中間点にマッピングされる。テクセル幅が 4 の反復テクスチャで、ミップマップ レベルが 0 の場合、座標 0.0 と 1.0 は、次の図に示すようにマッピングされる。

マッピングについて理解しておくと、単純なバイアスをスクリーン空間のジオメトリ座標に適用して、各テクセルを対応するピクセルに強制的にマッピングすることができる。たとえば、4 つの辺があるポリゴンで、前のテクスチャの各テクセルをスクリーン上の 1 つだけのピクセルにマッピングする場合、ジオメトリ座標でピクセルを強制的にオーバーラップして、各テクセルの中心を各ピクセルの中心に効果的に配置する必要がある。この結果、アプリケーションで多くの場合必要な 1 対 1 マッピングになる。

テクセル幅が 4 のテクスチャをピクセル座標 0 ～ 3 にマッピングするには、それぞれスクリーン空間座標 –0.5 ～ 3.5 とテクスチャ座標 0.0 ～1.0 を持つ 4 辺から成るポリゴンを、2 つの三角形を基に描画する。たとえば、スクリーン座標 0.0 にあるピクセルを例として考える。0.0 は最初の頂点 (-0.5) から 0.5 ピクセルだけ離れた位置座標にあり、合計幅が 4.0 であることから、補間テクスチャの座標は 0.125 になる。これをテクスチャ サイズ 4 を基にスケーリングすると、座標は 0.5 になる。バイアスを 0.5 だけ減じるとテクスチャ アドレスが 0.0 になる。これは、マップ内の最初のテクセルに完全に対応する。

要約すると、テクスチャ座標はテクスチャ マップを両側で均等にオーバーラップする。次の図は、テクセル幅が 4 のテクスチャのマッピングを示している。

ピクセル座標は、テクセルの場合と同様に正規化される。したがって、頂点がレンダリング先のピクセルをオーバーラップし、その頂点でテクスチャ座標 0.0 と 1.0 を使用する場合、ピクセルとテクセルが一列に並ぶ。両方のサイズがほぼ同じで適切に整列していれば、次の図に示すように、これらはテクセルとピクセル間で正確に対応する。


テクスチャ座標フォーマット

Microsoft® Direct3D® のテクスチャ座標には、1、2、3、または 4 つの浮動小数点要素を含めて、さまざまな大きさのテクスチャを処理できる。1D テクスチャ (大きさが 1 x n のテクスチャ サーフェス) の場合は、1 つのテクスチャ座標で処理される。最も一般的な 2D テクスチャの場合は、通常 u と v と呼ばれる 2 つのテクスチャ座標によって処理される。Direct3D では、キューブ環境マップという 3D テクスチャを 1 種類のみサポートしている。キューブ環境マップは、実際には 3D ではないが、3 要素ベクトルによって処理される。詳細については、「キューブ環境マップ」を参照すること。

「頂点フォーマットについて」で説明するように、アプリケーションでは頂点フォーマット内のテクスチャ座標をエンコードする。頂点フォーマットにはテクスチャ座標の複数のセットを含めることができる。D3DFVF_TEX0 ～ D3DFVF_TEX8 柔軟な頂点フォーマット フラグを使用して、テクスチャ座標を含めないか、最大 8 つのセットまで含めることを指定する。

各テクスチャ座標セットには、1 ～4 つの要素を含めることができる。D3DFVF_TEXTUREFORMAT1 ～ D3DFVF_TEXTUREFORMAT4 フラグは、テクスチャ座標セット内にある要素の個数を記述するが、これらのフラグは単独では使用しない。その代わり、これらのフラグは、頂点フォーマットの特定のテクスチャ座標セットで使用される要素の個数を記述するビット パターンの作成のために、マクロの D3DFVF_TEXCOORDSIZEn セットで使用する。これらのマクロは、要素数を定義する座標セットのインデックスを識別するパラメータを 1 つ受け取る。次の図は、これらのマクロの使用方法を示している。

// この頂点フォーマットには、2 つのテクスチャ座標セットが含まれている。
// 1 つ目のセット (インデックス 0) には 2 つの要素があり、2 つ目のセットには
// 1 つの要素がある。' この頂点フォーマットは次のように記述される。
//     dwFVF = D3DFVF_XYZ  | D3DFVF_NORMAL | D3DFVF_DIFFUSE | D3DFVF_TEX2 |
//             D3DFVF_TEXCOORDSIZE2(0) | D3DFVF_TEXCOORDSIZE1(1);
typedef struct CVF
{
    D3DVECTOR position;
    D3DVECTOR normal;
    D3DCOLOR  diffuse;
    float     u, v;   // 1 つ目のセット、2D
    float     t;      // 2 つ目のセット、1D
} CustomVertexFormat;

注 キューブ環境マップを除き、ラスタライザでは 3 つ以上の要素を使用してテクスチャを処理することはできない。アプリケーションではテクスチャ座標に最大 3 つまで要素を指定できるが、これが可能なのは、テクスチャがキューブ マップの場合か、D3DTTFF_PROJECTED テクスチャ トランスフォーム フラグが使用されている場合のみである。D3DTTFF_PROJECTED フラグが使用されている場合、ラスタライザは最初の 2 つの要素を 3 つ目 (または n つ目) の要素で除算する。詳細については、「テクスチャ座標トランスフォーム」を参照すること。


テクスチャ座標処理

ここでは、Microsoft® Direct3D® でサポートするテクスチャ座標処理について説明する。説明するトピックは、次のとおりである。

  • テクスチャ座標処理の流れ
  • テクスチャ座標の自動生成
  • テクスチャ座標トランスフォーム
  • テクスチャ座標処理の使い方


テクスチャ座標処理の流れ

次の図は、テクスチャ座標が処理を通してラスタライザに送られるまでの流れを示している。

システムでは、2 つのソースからテクスチャ座標を描画できる。所定のテクスチャ ステージでは、頂点フォーマット (D3DFVF_TEX1 ～ D3DFVF_TEX8) に含まれるテクスチャ座標を使用するか、Microsoft® Direct3D® で自動生成したテクスチャ座標を使用できる。後者の詳細については、「テクスチャ座標の自動生成」を参照すること。現在のテクスチャ ステージの D3DTSS_TEXTURETRANSFORMFLAGS テクスチャ ステージ ステートを D3DTTFF_DISABLE (デフォルト設定) に設定すると、入力座標はトランスフォームされない。D3DTSS_TEXTURETRANSFORMFLAGS を別の値に設定すると、そのステージのトランスフォーム行列が入力座標に適用される。

D3DTEXTURETRANSFORMFLAGS 列挙型は、D3DTSS_TEXTURETRANSFORMFLAGS テクスチャ ステージ ステートに有効な値を定義する。テクスチャ座標トランスフォームを実行しない D3DTTFF_DISABLE フラグを除き、この列挙に定義される値は、システムによってラスタライザに渡される出力座標の個数を設定する。D3DTTFF_COUNT1 ～ D3DTTFF_COUNT4 フラグの場合、1、2、3、または 4 つの要素が出力座標からラスタライザに渡される。現在 1D テクスチャ座標はサポートされていない。

D3DTTFF_PROJECTED フラグは特別なフラグである。このフラグは、テクスチャ座標が射影テクスチャ用のものであることをシステムに知らせる。D3DTTFF_PROJECTED フラグと D3DTEXTURETRANSFORMFLAGS の別のメンバを組み合わせることで、すべての要素を最後の要素で除算してからラスタ化を実行するようにラスタライザに知らせる。たとえば、3 要素のテクスチャ座標、または、トランスフォーム後の 3 要素のテクスチャ座標を明示的に使用するとき、D3DTTFF_COUNT3 および D3DTTFF_PROJECTED フラグを組み合わせて使用すると、ラスタライザで最初の 2 つの要素を最後の要素で除算して、2D テクスチャの処理に必要な 2D テクスチャ座標を生成できる。

注 キューブ環境マップを除き、ラスタライザでは 3 つ以上の要素を使用してテクスチャを処理することはできない。カレント テクスチャを処理するために使用できる要素数よりも多くの要素をテクスチャ ステージに指定した場合、無関係な要素は無視される。これは、1D テクスチャに対して 2D テクスチャ座標を使用するときにもあてはまる。


テクスチャ座標の自動生成

Microsoft® Direct3D® では、頂点に対してテクスチャ座標を自動的に生成できる。ここでは、システムが提供する機能とその使用方法について詳しく説明する。説明するトピックは、次のとおりである。

  • テクスチャ座標の自動生成について
  • テクスチャ座標の自動生成の構成


テクスチャ座標の自動生成について

システムでは、トランスフォーム後のカメラ空間位置座標または頂点の法線をテクスチャ座標として使用できる。また、キューブ環境マップを実行するための 3 要素ベクトルを計算することも可能である。頂点で明示的に指定するテクスチャ座標と同様、自動生成されたテクスチャ座標は、テクスチャ座標トランスフォーム用の入力として使用できる。

テクスチャ座標の自動生成では、頂点フォーマットでの明示的なテクスチャ座標の必要性を排除することで、ジオメトリ データで必要となる帯域幅を大幅に削減できる。多くの場合、システムで生成されたテクスチャ座標は、特殊効果を生み出すトランスフォームと共に使用できる。もちろん、この機能は特殊な用途に使用されるものであり、明示的なテクスチャ座標を使用するケースも多くある。


テクスチャ座標の自動生成の構成

C++ の場合、(D3DTEXTURESTAGESTATETYPE 列挙型からの) D3DTSS_TEXCOORDINDEX テクスチャ ステージ ステートを使用して、テクスチャ座標の生成方法を制御する。

通常、このステートは、頂点フォーマットで符号化された特定のテクスチャ座標セットを使用するようシステムに知らせる。このステートに割り当てる値の中に、D3DTSS_TCI_CAMERASPACENORMAL、D3DTSS_TCI_CAMERASPACEPOSITION、または D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR フラグを含めた場合、システムで実行される処理は大きく異なってくる。これらのフラグのいずれかでも存在しているとき、テクスチャ ステージは頂点フォーマットのテクスチャ座標を無視し、システムが生成する座標を優先する。各フラグの意味は、次のとおりである。

D3DTSS_TCI_CAMERASPACENORMAL
頂点法線を入力テクスチャ座標として使用する。頂点法線はカメラ空間にトランスフォームされる。
D3DTSS_TCI_CAMERASPACEPOSITION
頂点位置座標を入力テクスチャ座標として使用する。頂点位置座標がカメラ空間にトランスフォームされる。
D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR
反射ベクトルを入力テクスチャ座標として使用する。反射ベクトルがカメラ空間にトランスフォームされる。反射ベクトルは、入力頂点位置座標と法線ベクトルから計算される。

これらのフラグは互いに排他的である。これらのフラグのいずれかを使用する場合は、テクスチャ ラッピング モードを決定するためにシステムで使用するインデックス値を指定できる。

次のコードは、C++ でのこれらのフラグの使用方法を示している。

/*
* このコードでは、変数 d3dDevice は、IDirect3DDevice8 インターフェイスへの
* 有効なポインタであると仮定している。
 *
* このテクスチャ ステージの入力テクスチャ座標として
* 頂点位置座標 (カメラ空間) を使用し、
* D3DRENDERSTATE_WRAP1 レンダリング ステートのラップ モード セットを使用する。
 */
d3dDevice->SetTextureStageState( 0, D3DTSS_TEXCOORDINDEX,
                                   D3DTSS_TCI_CAMERASPACEPOSITION | 1 );

注 自動生成されたテクスチャ座標は、テクスチャ座標トランスフォームの入力値として非常に便利であり、またキューブ環境マップの 3 要素ベクトルを計算する必要がないという点でも便利である。

参照

テクスチャ座標トランスフォーム、キューブ環境マップ


テクスチャ座標トランスフォーム

ここでは、Microsoft® Direct3D® 直接モードで提供されるテクスチャ座標トランスフォーム機能の操作について説明する。説明するトピックは、次のとおりである。

  • テクスチャ座標トランスフォームについて
  • テクスチャ座標トランスフォームの設定と取得
  • テクスチャ座標トランスフォームを有効にする


テクスチャ座標トランスフォームについて

Microsoft® Direct3D® デバイスでは、4×4 行列を適用して、頂点のテクスチャ座標をトランスフォームできる。システムは、テクスチャ座標に対して、ジオメトリの場合と同様にトランスフォームを適用する。適用可能なトランスフォームには、スケーリング、回転、平行移動、射影、せん断、またはこれらの組み合わせなど、4×4 行列で可能なあらゆるトランスフォームがある。

注 Direct3D では、「トランスフォーム済み ライティング済みの頂点」は修正されない。したがって、「トランスフォーム済み ライティング済みの頂点」を使用するアプリケーションでは、Direct3D によって頂点のテクスチャ座標をトランスフォームすることはできない。

ハードウェア アクセラレーションによるトランスフォーム & ライティング処理をサポートするデバイス (TnLHAL デバイス) では、テクスチャ座標トランスフォームも高速処理される。ハードウェア アクセラレーションによるトランスフォームが利用できない場合は、Direct3D ジオメトリ パイプラインのプラットフォーム固有の最適化によってテクスチャ座標トランスフォームが実行される。

テクスチャ座標トランスフォームは、ジオメトリのテクスチャ座標を直接変更しないで特殊効果を出そうとする場合に便利である。単純な平行移動行列や回転行列を使用して、オブジェクト上のテクスチャをアニメーションしたり、Direct3D によって自動生成されるテクスチャ座標をトランスフォームすることで、射影テクスチャや動的ライト マッピングなど高度なエフェクトを単純化し、高速処理することも可能である。また、テクスチャ座標トランスフォームを使用して、テクスチャ座標の単一セットを複数のテクスチャ ステージでのさまざまな目的のために再利用できる。

詳細については、「テクスチャ座標処理の使い方」を参照すること。


テクスチャ座標トランスフォームの設定と取得

アプリケーションでジオメトリに使用する行列と同様、IDirect3DDevice8::SetTransform および IDirect3DDevice8::GetTransform メソッドを呼び出してテクスチャ座標トランスフォームを設定および取得できる。これらのメソッドは、テクスチャ ステージ 0 ～ 7 のトランスフォーム行列をそれぞれ識別する、D3DTRANSFORMSTATETYPE 列挙型の D3DTS_TEXTURE0 ～ D3DTS_TEXTURE7 メンバを受け取る。

次のコードは、テクスチャ ステージ 0 のテクスチャ座標に適用される行列を設定する。

// この例では、変数 d3dDevice は
// IDirect3DDevice8 インターフェイスへの有効なポインタを格納している。
//
D3DMATRIX matTrans = D3DXMatrixIdentity( NULL );

// 目的のトランスフォーム用の行列を設定する。
d3dDevice->SetTransform( D3DTS_TEXTURE0, &matTrans );


テクスチャ座標トランスフォームを有効にする

D3DTSS_TEXTURETRANSFORMFLAGS テクスチャ ステージ ステートは、テクスチャ座標トランスフォームの適用を制御する。このテクスチャ ステージ ステートの値は、D3DTEXTURETRANSFORMFLAGS 列挙型で定義される。

D3DTSS_TEXTURETRANSFORMFLAGS が D3DTTFF_DISABLE (デフォルト値) に設定されているときは、テクスチャ座標トランスフォームは無効である。テクスチャ座標トランスフォームがステージ 0 に対して有効な場合、次のコードはこれを無効にする。

// この例では、変数 d3dDevice には
// IDirect3DDevice8 インターフェイスへの有効なポインタが格納されている。

D3dDevice->SetTextureStageState( 0, D3DTSS_TEXTURETRANSFORMFLAGS, D3DTTFF_DISABLE );

D3DTEXTURETRANSFORMFLAGS に定義されているその他の値は、テクスチャ座標トランスフォームを有効にするため、また、結果として生成されるテクスチャ座標の要素のうち、ラスタライザに渡す個数を制御するために使用する。例として次のコードを考える。

// この例では、変数 d3dDevice には
// IDirect3DDevice8 インターフェイスへの有効なポインタが格納されている。

D3dDevice->SetTextureStageState( 0, D3DTSS_TEXTURETRANSFORMFLAGS, D3DTTFF_COUNT2 );

D3DTTFF_COUNT2 値は、テクスチャ ステージ 0 用のトランスフォーム行列セットを適用し、トランスフォーム後のテクスチャ座標の最初の 2 つの要素をラスタライザに渡すようシステムに指示する。

D3DTTFF_PROJECTED テクスチャ トランスフォーム フラグは、射影されるテクスチャの座標を示す。このフラグが指定されている場合、ラスタライザはトランスフォーム対象の要素を最後の要素で除算する。例として次のコードを考える。

// この例では、変数 d3dDevice には
// IDirect3DDevice8 インターフェイスへの有効なポインタが格納されている。

d3dDevice->SetTextureStageState( 0, D3DTSS_TEXTURETRANSFORMFLAGS,
                                   D3DTTFF_COUNT3 | D3DTTFF_PROJECTED );

この例では、3 つのテクスチャ座標要素をラスタライザに渡すようにシステムに知らせる。ラスタライザでは、最初の 2 つの要素を 3 つ目の要素で除算して、テクスチャの処理に必要な 2D テクスチャ座標を生成する。


テクスチャ座標処理の使い方

次に示すのは、テクスチャ座標処理によって特殊なテクスチャ エフェクトを出す方法である。

モデル上でテクスチャをアニメーションする (平行移動または回転を利用)

  • 2D テクスチャ座標を頂点フォーマットに定義する。
    // 2D テクスチャ座標を持つ単一のテクスチャを使用する。このビット パターンは、
// 必要に応じて、位置座標、法線、および色情報を追加できるように
// 拡張する必要がある。
DWORD dwFVFTex = D3FVF_TEX1 | D3DFVF_TEXCOORDSIZE2(0);
  • 2D テクスチャ座標を使用するようにラスタライザを設定する。
    SetTextureStageState(0, D3DTSS_TEXTURETRANSFORMFLAGS, D3DTTFF_COUNT2);
  • 適切なテクスチャ座標トランスフォーム行列を定義して設定する。
    // M は、U および V 方向のテクスチャ座標を平行移動するための
// D3DMATRIX である。
//      1   0  0  0
//      0   1  0  0
//      du dv  1  0 (du および dv は各フレームを変更する)
//      0   0  0  1

D3DMATRIX M = D3DXMatrixIdentity(); // d3dutil.h に宣言される。
M._31 = du;
M._32 = dv;

モデルのカメラ空間位置座標の線形関数としてテクスチャ座標を作成する

  • D3DTSS_TCI_CAMERASPACEPOSITION フラグを使用して、カメラ空間の頂点位置座標を入力としてテクスチャ トランスフォームに渡す。
    // 入力頂点にはテクスチャ座標がなく、
// 帯域幅が節約されている。3 つのテクスチャ座標は、カメラ空間 (x, y, z) の頂点位置座標を使用して
// 生成される。
SetTextureStageState(0, D3DTSS_TEXCOORDINDEX, D3DTSS_TCI_CAMERASPACEPOSITION);
  • ラスタライザで 2D テクスチャ座標を評価する。
    // 2 つの出力座標を使用する。
SetTextureStageState(0, D3DTSS_TEXTURETRANSFORMFLAGS, D3DTTFF_COUNT2);
  • 線形関数を適用する行列を定義して設定する。
    // 次に示すように、
// テクスチャ座標を線形関数として生成する。
//      u = Ux*x + Uy*x + Uz*x + Uw
//      v = Vx*x + Vy*x + Vz*x + Vw
// この場合、行列 M は次のようになる。
//      Ux  Vx  0  0
//      Uy  Vy  0  0
//      Uz  Vz  0  0
//      Uw  Vw  0  0

SetTransform(D3DTS_TEXTURE0, &M);

キューブ環境マップによる環境マッピングを実行する

  • D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR フラグを使用して、キューブ マップ用の反射ベクトルとしてテクスチャ座標を自動的に生成する。
    SetTextureStageState(0, D3DTSS_TEXCOORDINDEX, D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR);
  • ラスタライザに、3 つの要素を持つテクスチャ座標を使用するよう指示する。
    SetTextureStageState(0, D3DTSS_TEXTURETRANSFORMFLAGS, D3DTTFF_COUNT3);

射影テクスチャを実行する

  • D3DTSS_TCI_CAMERASPACEPOSITION フラグを使用して、テクスチャ トランスフォームに頂点位置座標を入力として渡す。
    SetTextureStageState(0, D3DTSS_TEXCOORDINDEX, D3DTSS_TCI_CAMERASPACEPOSITION);
  • テクスチャ射影行列を作成して適用する。これはドキュメントの対象外であり、その他の市販製品で扱う内容である。
  • ラスタライザに 3 つの要素を持つ射影テクスチャ座標を使用するよう指示する。
    // 2 つの出力座標を使用する。
SetTextureStageState(0, D3DTSS_TEXTURETRANSFORMFLAGS, D3DTTF_PROJECTED | D3DTTFF_COUNT3);


テクスチャ リソース

ここでは、テクスチャ インターフェイス ポインタによる作成およびレンダリングについて説明する。説明するトピックは、次のとおりである。

  • テクスチャ サーフェス オブジェクトの取得
  • テクスチャ リソースを使用したレンダリング


テクスチャ サーフェス オブジェクトの取得

テクスチャ リソースは、IDirect3DTexture8 インターフェイスに実装されている。テクスチャ インターフェイスへのポインタを取得するには、IDirect3DDevice8::CreateTexture メソッドか、次のいずれかの D3DX 関数を呼び出す。

  • D3DXCreateTexture
  • D3DXCreateTextureFromFileA
  • D3DXCreateTextureFromFileExA
  • D3DXCreateTextureFromFileExW
  • D3DXCreateTextureFromFileInMemory
  • D3DXCreateTextureFromFileInMemoryEx
  • D3DXCreateTextureFromFileW
  • D3DXCreateTextureFromResourceA
  • D3DXCreateTextureFromResourceExA
  • D3DXCreateTextureFromResourceExW
  • D3DXCreateTextureFromResourceW

次のコードでは、D3DXCreateTextureFromFileA を使用して、Tiger.bmp というファイルからテクスチャをロードする。

// 次のコードでは、d3dDevice は IDirect3DDevice8 インターフェイスへの
// 有効なポインタであると仮定している。

LPDIRECT3DTEXTURE8 pTexture;

D3DXCreateTextureFromFile( d3dDevice, "tiger.bmp", &pTexture);

D3DXCreateTextureFromFile が受け取る第 1 パラメータは、IDirect3DDevice8 インターフェイスへのポインタである。第 2 パラメータは、ロードするテクスチャが入っているファイル名を Microsoft® Direct3D® に指示する。第 3 パラメータは、作成されたテクスチャ オブジェクトを表す IDirect3DTexture8 インターフェイスへのポインタのアドレスとする。


テクスチャ リソースを使用したレンダリング

Microsoft® Direct3D® では、テクスチャ ステージという概念を用いてマルチ テクスチャ ブレンディングをサポートする。テクスチャ ステージごとに、テクスチャとそのテクスチャで実行可能な処理がある。テクスチャ ステージのテクスチャは、カレント テクスチャの集まりを形成する。詳細については、「マルチ テクスチャ ブレンディング」を参照すること。各テクスチャのステートは、そのテクスチャ ステージにカプセル化される。

C++ アプリケーションでは、各テクスチャのステートは IDirect3DDevice8::SetTextureStageState メソッドで設定する必要がある。第 1 パラメータの値としてステージ番号 (0 ～ 7) を渡す。第 2 パラメータの値には、D3DTEXTURESTAGESTATETYPE 列挙型のメンバを設定する。最後のパラメータは、特定のテクスチャ ステートについてのステート値である。

テクスチャ インターフェイス ポインタを使用して、最大 8 つのテクスチャのブレンドをレンダリングできる。IDirect3DDevice8::SetTexture メソッドを呼び出してカレント テクスチャを設定する。Direct3D は、レンダリングするプリミティブに対して、カレント テクスチャをすべてブレンドする。

注 SetTexture メソッドは、割り当てられるテクスチャ サーフェスの参照カウントをインクリメントする。テクスチャが不要になった場合、該当するステージのテクスチャを NULL に設定する必要がある。これを行わないと、サーフェスが解放されずメモリ リークが発生する。

IDirect3DDevice8::SetRenderState メソッドを呼び出して、カレント テクスチャのテクスチャ ラッピング ステートを設定できる。第 1 パラメータの値として、D3DRS_WRAP0 ～ D3DRR_WRAP7 から値を 1 つ渡す。また、D3DWRAPCOORD_0、D3DWRAPCOORD_1、D3DWRAPCOORD_2、および D3DWRAPCOORD_3 フラグの組み合わせを使用して、u、v、または w 方向のラッピングを有効にする。

また、テクスチャ パースペクティブ ステートとテクスチャ フィルタリング ステートを設定することもできる。「テクスチャ フィルタリング」および「テクスチャ フィルタリング ステート」を参照すること。


テクスチャ フィルタリング

Microsoft® Direct3D® はプリミティブをレンダリングするとき、3D プリミティブを 2D スクリーンにマッピングする。プリミティブがテクスチャを持っている場合、Direct3D はそのテクスチャを使用して、プリミティブの 2D レンダリング画像の各ピクセルの色を生成しなければならない。プリミティブのスクリーン上の画像のすべてのピクセルに対して、テクスチャからカラー値を取得しなければならない。この処理をテクスチャ フィルタリングと呼ぶ。

テクスチャ フィルタリング処理を実行するとき、使用するテクスチャは通常拡大または縮小される。つまり、テクスチャは、それ自体よりも大きなまたは小さなプリミティブ画像にマッピングされる。テクスチャの拡大によって、多数のピクセルが 1 つのテクセルにマッピングされることがある。この結果、画像が粗くなることがある。テクスチャの縮小では、多くの場合、単一のピクセルが多数のテクセルにマッピングされる。この結果、画像が不鮮明になったり、ぎざぎざができることがある。これらの問題を解決するには、ピクセルの色になるようにテクセル色のブレンディングを実行する必要がある。

Direct3D では、テクスチャ フィルタリングの複雑な処理を簡素化する。Direct3D では、線形フィルタリング、異方性フィルタリング、およびミップマップ フィルタリングの 3 種類のテクスチャ フィルタリングを使用できる。テクスチャ フィルタリングを選択しない場合、Direct3D では最近ポイント サンプリングという方法を使用する。

それぞれのテクスチャ フィルタリングには、長所と短所がある。たとえば、線形テクスチャ フィルタリングを使用した場合、最終的な画像でエッジがぎざぎざになったり、画質が粗くなることがある。しかし、このフィルタリングはオーバーヘッドが少ない。ミップマップによるフィルタリングを使用すると、通常は最良の結果が得られる。特に、異方性フィルタリングと組み合わせて使用した場合はそうである。しかし、このフィルタリングは、Direct3D がサポートする方法の中で最もメモリを必要とするものである。

テクスチャ インターフェイス ポインタを使用するアプリケーションでは、IDirect3Ddevice8::SetTextureStageState メソッドを呼び出して現在のテクスチャ フィルタリング方法を設定する必要がある。第 1 パラメータの値を、テクスチャ フィルタリング方法を選択するテクスチャの整数インデックス番号 (0 ～ 7) に設定する。第 2 パラメータとして D3DTEXTUREMAGFILTER、D3DTEXTUREMINFILTER、または D3DTEXTUREMIPFILTER を渡して、拡大、縮小、またはミップマップ フィルタを設定する。第 3 パラメータの値として D3DTEXTUREFILTERTYPE 列挙型のメンバを渡して、拡大、縮小、またはミップマップ フィルタを設定する。

ここでは、Direct3D でサポートするテクスチャ フィルタリング方法について説明する。説明するトピックは、次のとおりである。

  • 最近点サンプリング
  • 線形テクスチャ フィルタリング
  • 異方性テクスチャ フィルタリング
  • ミップマップによるテクスチャ フィルタリング

注 D3DRENDERSTATETYPE 列挙型にあるテクスチャ フィルタリング ステートは、テクスチャ ステージ ステートに置き換えられているが、このレンダリング ステートを使用しても、IDirect3DDevice2 バージョンとは対照的に IDirect3DDevice8::SetRenderState の実行が失敗することはない。その代わり、システムでは、このレンダリング ステートのエフェクトをマルチ テクスチャ カスケードの最初のステージ (ステージ 0) にマッピングする。アプリケーションでは、従来のレンダリング ステートをそれと対応するテクスチャ ステージ ステートと併用しないこと。予期せぬ結果が生じるおそれがある。


最近点サンプリング

アプリケーションでは、このテクスチャ フィルタリングを使用する必要はない。Microsoft® Direct3D® は、テクセル アドレスを計算 (このアドレスは整数でないことが多い) したり、この値に最も近い整数アドレスを持つテクセルの色を単にコピーするように設定できる。この処理を最近点サンプリングと呼ぶ。テクスチャのサイズがスクリーン上のプリミティブの画像のサイズとほぼ同じ場合には、この方法によってテクスチャは高速で効率的に処理できる。両方のサイズの差が大きい場合は、テクスチャを拡大したり、縮小する必要がある。このような処理を実行した結果、画像が粗くなったり、ぎざぎざができたり、不鮮明になることがある。

C++ アプリケーションでは、IDirect3DDevice8::SetTextureStageState メソッドを呼び出して最近点サンプリングを選択できる。第 1 パラメータの値を、テクスチャ フィルタリング方法を選択するテクスチャの整数インデックス番号 (0 ～ 7) に設定する。第 2 パラメータとして D3DTEXTUREMAGFILTER、D3DTEXTUREMINFILTER、または D3DTEXTUREMIPFILTER を渡して、拡大、縮小、またはミップマップ フィルタを設定する。第 3 パラメータの値として D3DTEXTUREFILTERTYPE 列挙型のメンバを渡して、拡大、縮小、またはミップマップ フィルタを設定する。

詳細については、「テクスチャ フィルタリング ステート」を参照すること。

最近点サンプリングは注意して使用すること。2 つのテクセル間の境界でテクスチャがサンプリングされる際、場合によっては不自然なグラフィックス効果が生じることがある。この境界とは、サンプリング対象のテクセルが次のテクセルに移るときの、テクスチャに沿った位置座標 (u または v) である。ポイント サンプリングを使用するとき、システムではサンプル テクセルを 1 つ選択するか、別のテクセルを選択する。これにより、境界が交差している際は結果がテクセル間で不意に変化することがある。この影響から、表示されるテクスチャの中に、好ましくない不自然なグラフィックス エフェクトが現れることがある。線形フィルタリングを使用した場合、結果テクセルは隣接テクセル間で計算され、テクスチャ インデックスが境界に沿って移るのに従って滑らかにブレンドされる。

このようなエフェクトは、非常に小さなテクスチャを非常に大きなポリゴンにマッピングする (多くの場合 "拡大" と呼ぶ) ときに発生する可能性がある。たとえば、チェッカー盤のようなテクスチャでポイント サンプリングを使用すると、チェッカー盤は拡大されてエッジが際立つ。対照的に、線形テクスチャ フィルタリングを使用した場合は、チェッカー盤の色がポリゴン全体にわたって滑らかに変化した画像ができあがる。

ほとんどの場合、最良の結果を得るためには、最近点サンプリングの使用をできるだけ避けるようにする。最近のハードウェアのほとんどは、線形フィルタリング用に最適化されているため、パフォーマンスが低下することはない。ただし、テクスチャを使用して読みやすいテキスト文字を表示する場合など、目的のエフェクトを出すためにどうしても最近点サンプリングを使用しなければならない場合は、テクセル境界でサンプリングを行わないように心がけ、思わぬエフェクトが生じないよう細心の注意を払う必要がある。次の図は、不自然なグラフィックス効果がどのようなものであるかを示している。

グループ内の右上にある 2 つの四角形が隣接する四角形とは異なることに注意する。これらには対角オフセットがある。このような不自然なグラフィックス効果を避けるためには、まず最近点フィルタリングに関する Direct3D テクスチャ サンプリング ルールについて理解する必要がある。Direct3D では、[0.0, 1.0] (0.0 ～ 1.0 まで含む) の範囲内の浮動小数点テクスチャ座標を、[–0.5, n – 0.5] の範囲内の整数テクセル空間値にマッピングする。ここで、n はテクスチャの所定の大きさでのテクセル数である。結果のテクスチャ インデックスは、最も近い整数に丸められる。このマッピングにより、テクスチャ境界ではサンプリングの誤差が生じる場合がある。

簡単な例として、D3DTADDRESS_WRAP テクスチャ アドレッシング モードでポリゴンをレンダリングする場合を考えてみる。Direct3D のマッピングを使用すると、u テクスチャ インデックスは、4 テクセル幅のテクスチャに対して、次のようにマッピングされる。

この図で、テクスチャ座標 0.0 と 1.0 は、テクセル間の境界上に正確に位置する。Direct3D のマッピング用のメソッドを使用すると、テクスチャ座標は [–0.5, 4 – 0.5] の範囲内にマッピングされる。ここで、4 はテクスチャの幅である。この場合、サンプリングされるのは、テクスチャ インデックス 1.0 の 0 番目のテクセルである。ただし、テクスチャ座標が 1.0 よりもわずかに少ない場合には、サンプリングされるのは 0 番目のテクセルではなく、n 番目のテクセルになる。

これは、つまり、テクスチャ座標 0.0 と 1.0 を持つ小さなテクスチャを、スクリーン空間に配列された三角形上で最近点フィルタリングによって拡大すると、その結果、テクスチャ マップがテクセル間の境界でサンプリングされる際の対象となるピクセルになる、という意味である。テクスチャ座標の計算の誤差がわずかな場合であっても、テクスチャ マップのテクセル エッジに対応する、レンダリング画像の領域に沿って不自然な効果が現れる。

このように浮動小数点テクスチャ座標を整数テクセルに完璧に正確にマッピングするのは、困難な作業であり、計算負荷も大きいが、このような処理を一般には行う必要はない。ほとんどのハードウェア実装では、三角形内の各ピクセル位置座標におけるテクスチャ座標の計算に反復処理を用いる。この方法を使用すると、補間処理間で誤差が均等に累積されていくため、これらの誤差がいくらかは目立たなくなる。

Direct3D リファレンス ラスタライザでは、各ピクセル位置座標でのテクスチャ インデックスの計算に直接評価法を用いる。直接評価は反復処理とは異なり、処理上の誤差がよりランダムなエラー分布を示す。この結果、境界上ではより顕著なサンプリング エラーが発生する。これは、リファレンス ラスタライザによってこの処理が正確に実行されないためである

最近点フィルタリングは、必要な場合にのみ使用するとよい。これを使用する必要がある場合は、テクスチャ座標を境界位置座標から少しだけオフセットして不自然な効果の発生を防ぐことが推奨される。


線形テクスチャ フィルタリング

Microsoft® Direct3D® では、バイリニア フィルタリングと呼ばれる線形テクスチャ フィルタリングを使用する。最近点サンプリングと同様、バイリニア テクスチャ フィルタリングでは最初にテクセル アドレスを計算するが、通常、この値が整数アドレスになることはない。バイリニア フィルタリングでは、計算したアドレスに最も近い整数アドレスを持つテクセルが検索される。さらに、Direct3D レンダリング モジュールでは、サンプリングした最近点の上下左右にあるテクセルの加重平均を計算する。

IDirect3DDevice8::SetTextureStageState メソッドを呼び出して、バイリニア テクスチャ フィルタリングを選択する。第 1 パラメータの値を、テクスチャ フィルタリング方法を選択するテクスチャの整数インデックス番号 (0 ～ 7) に設定する。第 2 パラメータとして D3DTEXTUREMAGFILTER、D3DTEXTUREMINFILTER、または D3DTEXTUREMIPFILTER を渡して、拡大、縮小、またはミップマップ フィルタを設定する。第 3 パラメータを D3DTEXF_LINEAR に設定する。詳細については、「テクスチャ フィルタリング ステート」を参照すること。


異方性テクスチャ フィルタリング

異方性とは、スクリーン平面に対して角度をなして位置したサーフェスを持つ 3D オブジェクトのテクセルの可視的なゆがみである。異方性プリミティブからのピクセルをテクセルにマッピングするとき、プリミティブの形状がゆがむ。Microsoft® Direct3D® では、テクスチャ空間に逆マッピングされるスクリーン ピクセルの伸長度 (長さ÷幅) としてピクセルの異方性を測定する。

異方性テクスチャ フィルタリングは、線形テクスチャ フィルタリングまたはミップマップ テクスチャ フィルタリングと併用することで、レンダリング結果を向上させることができる。IDirect3DDevice8::SetTextureStageState メソッドを呼び出して、異方性テクスチャ フィルタリングを有効にする。第 1 パラメータの値を、テクスチャ フィルタリング方法を選択するテクスチャの整数インデックス番号 (0 ～ 7) に設定する。第 2 パラメータとして D3DTEXTUREMAGFILTER、D3DTEXTUREMINFILTER、または D3DTEXTUREMIPFILTER を渡して、拡大、縮小、またはミップマップ フィルタを設定する。第 3 パラメータを D3DTEXF_ANISOTROPIC に設定する。詳細については、「テクスチャ フィルタリング ステート」を参照すること。

また、異方性の度合いをゼロより大きな値に設定する必要がある。これを設定するには、IDirect3DDevice8::SetTextureStageState メソッドを呼び出す。第 1 パラメータには、異方性の度合いを設定するテクスチャの整数インデックス番号 (0 ～ 7) を設定する。第 2 パラメータには、D3DTSS_MAXANISOTROPY を渡す。最後のパラメータは、異方性の度合いでなければならない。

異方性の度合いを 1 に設定すると、異方性フィルタリングが無効になり、1 より大きな値を設定すると、異方性フィルタリングが有効になる。異方性の度合いとして設定可能な値の範囲を判別するには、D3DCAPS8 構造体の MaxAnisotropy フラグをチェックする。


ミップマップによるテクスチャ フィルタリング

ミップマップ テクスチャは、シーンのレンダリングに必要な時間を短縮するために 3D シーンで使用される。また、ミップマップ テクスチャを使用すると、シーンのリアリティが増す。しかし、ミップマップ テクスチャを使用するにはメモリが大量に必要となることが多い。

ここでは、3D シーンでのミップマップ テクスチャの使用に関する基本事項について説明する。説明するトピックは、次のとおりである。

  • ミップマップとは
  • ミップマップ セットの作成
  • ミップマップの選択と表示


ミップマップとは

ミップマップとは連続したテクスチャで、各テクスチャは同じ画像を徐々に低解像度にしたものである。ミップマップでの各画像の高さと幅、つまりレベルは、直前のレベルよりも 2 の累乗だけ小さい。ミップマップは正方形である必要はない。

ユーザーに近いオブジェクトには、高解像度ミップマップ画像が使用される。オブジェクトが遠ざかるに従って、低解像度のミップマップ画像が使用される。ミップマップ処理により、レンダリングしたテクスチャの品質が向上するが、使用するメモリは増加する。

Microsoft® Direct3D® では、ミップマップはアタッチされたサーフェスのチェーンとして表される。このチェーンの先頭には最高解像度のテクスチャがあり、その後には次のミップマップ レベルのテクスチャが続く。このレベルの後には次のレベルのミップマップが続く、という順に最低解像度のミップマップになるまで続いていく。

次の図は、これらのレベルの例を示している。ビットマップ テクスチャは、対面型のゲームの 3D コンテナの側面にある記号を表している。ミップマップとして作成すると、最高解像度のテクスチャがこのセットの先頭にくる。このミップマップ セットの連続する各テクスチャは、高さと幅が 2 の累乗ずつ小さくなっていく。この場合、最高解像度のミップマップは 256x256 ピクセルである。次のテクスチャは 128x128 である。最後のテクスチャは 64x64 である。

この記号は可視範囲内の最大距離にある。この記号から遠く離れた位置からゲームを開始する場合、ミップマップ チェーンの中で最小のテクスチャ (この場合 64x64 テクスチャ) が表示される。

ユーザーの視点がこの記号に近づくにつれて、徐々に高解像度のテクスチャが使用される。次の図の解像度は 128x128 である。

最高解像度のテクスチャが使用されるのは、プレーヤーの視点がこの記号に最も近づいたときである。

これは、テクスチャのパースペクティブをシミュレートする方法の中ではオーバーヘッドが低い方法である。1 つのテクスチャを多くの解像度でレンダリングするよりも、さまざまな解像度で複数のテクスチャを使用する方が高速である。

Direct3D では、ミップマップ セットの中でどのテクスチャが最も目的出力に近い解像度であるかを評価し、ピクセルをそのテクセル空間にマッピングできる。最終的な画像の解像度がミップマップ セット内のテクスチャ間にある場合、Direct3D では両方のミップマップのテクセルを調べ、そのカラー値をブレンドする。

ミップマップを使用するには、アプリケーションでミップマップのセットを作成する必要がある。詳細については、「ミップマップ セットの作成」を参照すること。アプリケーションでは、ミップマップ セットをカレント テクスチャ セットの最初のテクスチャとして選択して、ミップマップを適用する。詳細については、「マルチ テクスチャ ブレンディング」を参照すること。

次に、Direct3D でテクセルのサンプリングに使用するフィルタリング方法を設定しなければならない。最も処理が速いミップマップ フィルタリングは、Direct3D で最も近いテクセルを選択する方法である。これ選択するには、D3DTFP_POINT 列挙値を使用する。Direct3D では、D3DTFP_LINEAR 列挙値を使用すると、より高品質なフィルタリング結果が得られる。このフィルタリングでは、最も近いミップマップが選択され、次に現在のピクセルがマッピングされる、テクスチャ内の位置座標の周辺テクセルの加重平均が計算される。


ミップマップ セットの作成

次の例は、IDirect3DDevice8::CreateTexture メソッドを呼び出して、サイズ 256 × 256、128 × 128、64 × 64、32 × 32、および 16 × 16 の 5 つのミップマップ レベルのチェーンを作成する方法を示している。

// このサンプル コードでは、変数 d3dDevice は IDirect3DDevice8 インターフェイスへの
// 有効なポインタであると仮定している。

IDirect3DTexture8 * pMipMap;

d3dDevice->CreateTexture(256, 256, 5, 0, D3DFMT_R8G8B8, D3DPOOL_MANAGED, &pMipMap);

CreateTexture が受け取る最初の 2 つのパラメータは、最上位テクスチャのサイズと幅である。第 3 パラメータには、テクスチャのレベル数を指定する。このパラメータをゼロに設定すると、Microsoft® Direct3D® はサーフェスのチェーンを作成する。各サーフェスは、直前のサーフェスよりも 2 の累乗ずつ小さくなり、最終的に 1 × 1 の最小サイズになる。第 4 パラメータには、このリソースの使用方法を指定する。ここではゼロが指定されているので、リソースには特定の使用方法はないことを示す。第 5 パラメータには、テクスチャのサーフェス フォーマットを指定する。このパラメータには、D3DFORMAT 列挙型の値を使用する。第 6 パラメータには、作成したリソースを配置するメモリ クラスを示す D3DPOOL 列挙型のメンバを指定する。動的テクスチャを使用しているのでなければ、D3DPOOL_MANAGED を勧める。最後のパラメータは、IDirect3DTexture8 インターフェイスへのポインタのアドレスとする。

注 ミップマップ チェーンの各サーフェスの大きさは、直前のサーフェスの半分になる。最上位ミップマップの大きさが 256 × 128 の場合、2 番目のレベルのミップマップの大きさは 128 × 64 になり、3 番目のレベルは 64 × 32 という順にミップマップの大きさは小さくなり、最終的には 1 × 1 になる。Levels でミップマップ レベルの数を指定することはできない。Levels では、チェーンのミップマップの幅または高さのいずれかが 1 より小さくなることがある。4 × 2 を最上位ミップマップ サーフェスとする単純なケースでは、Levels の最大値は 3 になる。最上位の大きさは 4 × 2 で、次のレベルの大きさは 2 × 1 で、その次のレベルの大きさは 1 × 1 である。Levels の値が 3 より大きいと、第 2 レベルのミップマップの高さは分数になる。したがって、これは許可されない。


ミップマップの選択と表示

IDirect3DDevice8::SetTexture メソッドを呼び出して、カレント テクスチャの一覧内の先頭のテクスチャとしてミップマップ テクスチャを設定する。詳細については、「マルチ テクスチャ ブレンディング」を参照すること。

ミップマップ テクスチャ セットを選択した後、D3DTEXTUREFILTERTYPE 列挙型からの値を D3DTSS_MIPFILTER テクスチャ ステージ ステートに割り当てなければならない。Microsoft® Direct3D® ではミップマップ テクスチャ フィルタリングを自動的に実行する。次のサンプル コードでは、ミップマップ テクスチャ フィルタリングが有効にされている。

d3dDevice->SetTexture(0, pMipMap);
d3dDevice->SetTextureStageState(0, D3DTSS_MIPFILTER, D3DTEXF_POINT);

また、IDirect3DTexture8::GetSurfaceLevel メソッドを使用し、取得するミップマップ レベルを指定することで、ミップマップ サーフェスのチェーンを手動でトラバースできる。次の例では、最高解像度から最低解像度までミップマップ チェーンをトラバースする。

IDirect3DSurface8 * pSurfaceLevel;

for (int iLevel = 0; iLevel < pMipMap->GetLevelCount(); iLevel++)
{
    pMipMap->GetSurfaceLevel(iLevel, &pSurfaceLevel);

    //このレベルを処理する。

    pSurfaceLevel->Release();
}

チェーンのミップマップ サーフェスの各サーフェスにビットマップ データをロードするために、アプリケーションではミップマップ チェーンを手動でトラバースする必要がある。通常、この理由からチェーンをトラバースする。アプリケーションは、IDirect3DBaseTexture8::GetLevelCount を呼び出して、ミップマップに格納されているレベルの数を取得できる。


テクスチャ ラッピング

ここでは、3D プリミティブへのテクスチャ ラッピングについて説明する。説明するトピックは、次のとおりである。

  • テクスチャ ラッピングとは
  • テクスチャ ラッピングの使い方

注 テクスチャ ラッピングと、類似した名前のテクスチャ アドレッシング モードを混同しないこと。詳細については、「テクスチャ アドレッシング モードとテクスチャ ラッピング」および「テクスチャ アドレッシング モード」を参照すること。


テクスチャ ラッピングとは

簡単に言えば、テクスチャ ラッピングとは、Microsoft® Direct3D® で各頂点に対して指定されたテクスチャ座標を使用して、テクスチャ処理したポリゴンをラスタ化する際の基本的な方法を変更する処理である。ポリゴンのラスタ化中に、システムはポリゴンの各頂点のテクスチャ座標の間を補間して、ポリゴンのすべてのピクセルに使用するテクセルを決める。通常、システムはテクスチャを 2D 平面として扱い、テクスチャ内のポイント A から ポイント B までの最短経路をとることで新しいテクセルを補間する。ポイント A が u, v 位置座標 (0.8, 0,1) で、ポイント B が (0.1,.9) の場合、補間の線は次の図のようになる。

上の図では、AB 間の最短距離がテクスチャのほぼ中央を通っている。u または v のテクスチャ座標のラッピングを有効にすると、u および v 方向でのテクスチャ座標間の最短経路を Direct3D が認識する方法が変化する。定義では、0.0 と 1.0 が同じ位置座標を占めると仮定して、テクスチャ ラッピングによってラスタライザがテクスチャ座標間の最短経路をとる。最後のビットは扱いにくいが、次のように考えるとわかりやすい。一方向のテクスチャ ラッピングを有効にすると、システムはテクスチャがあたかも円柱の周囲に巻き付いているかのようにテクスチャを扱う。たとえば、次の図を考える。

上の図は、u 方向のラッピングによって、システムによるテクスチャ座標の補間方法がどのように変化するかを示している。この例で使用した同じ点を、正常なまたは巻き付けていないテクスチャに使用すると、点 A と B の最短距離がテクスチャの中心にないことがわかる。この場合、最短距離は 0.0 と 1.0 が共に位置する境界を通っている。v 方向のラッピングも同様である。ただし、側面が下になっている円柱の周囲にテクスチャが巻き付いている。u および v の両方向のラッピングの場合はさらに複雑である。この場合は円環、つまりドーナツを想像するとよい。

テクスチャ ラッピングを実際に使用した最も一般的なアプリケーションは、環境マッピングの実行である。通常、環境マッピングでテクスチャ処理したオブジェクトは非常に反射的であり、シーンのオブジェクトの周囲に画像が反映する。これを説明するため、四方が壁で囲まれた部屋を考える。壁にはそれぞれ R、G、B、および Y という文字が付けてあり、それに対応する赤色、緑色、青色、および黄色で塗られている。このような単純な部屋の環境マッピングであれば、次のようになる。

この部屋の天井が、4 面からなる非常に反射しやすい柱で支えられているとする。この柱に環境マッピングを実行するのは非常に簡単である。しかし、壁の文字と色が柱に反射しているように見せるのは簡単なことではない。次の図は、上方の頂点の近くのテクスチャ座標を適用した、柱のワイヤ フレームを示している。ラッピングがこのテクスチャのエッジを横切る「継ぎ目」は、点線で示す。

u 方向でラッピングが有効になっているので、テクスチャ処理した柱には、環境マッピングからの色とシンボルが正しく表示されており、テクスチャの前面の継ぎ目では、ラスタライザがテクスチャ座標間の最短経路を正しく選択している (u 座標 0.0 と 1.0 が同じ位置を占めるという前提)。テクスチャを適用した柱は、次の図に示すようになる。

テクスチャ ラッピングが有効でない場合、ラスタライザは、実物のように反射した画像を生成するために必要な方向に補間を行わない。逆に、柱の前面部分では、u 座標の 0.175 および 0.875 間のテクセルが、テクスチャの中心を通るときに水平方向で圧縮され、ラップ エフェクトは崩れる。


テクスチャ ラッピングの使い方

テクスチャ ラッピングを有効にするには、次のサンプル コードに示すように、IDirect3DDevice8::SetRenderState メソッドを呼び出す。

d3dDevice->SetRenderState(D3DRS_WRAP0, D3DWRAPCOORD_0);

SetRenderState が受け取る第 1 パラメータは、設定するレンダリング ステートである。ラッピングを設定するテクスチャ レベルを指定する D3DRS_WRAP0 ～ D3DRS_WRAP7 の列挙値のいずれかを指定する。第 2 パラメータに D3DWRAPCOORD_0 ～ D3DWRAPCOORD_3 フラグを指定して、対応する方向のテクスチャ ラッピングを有効にするか、これらのフラグを組み合わせて複数の方向のラッピングを有効にする。フラグを省略すると、対応する方向でのテクスチャ ラッピングが無効になる。テクスチャ座標のセットに対してテクスチャ ラッピングを無効にするには、対応するレンダリング ステートの値を 0 に設定する。


テクスチャ ブレンディング

Microsoft® Direct3D® では、テクスチャをプリミティブの色とブレンドして透明エフェクトを生成できる。また、複数のテクスチャを 1 つのプリミティブにブレンドすることもできる。ここでは、テクスチャ ブレンディングの実行方法について説明する。説明するトピックは、次のとおりである。

  • アルファ テクスチャ ブレンディング
  • マルチパス テクスチャ ブレンディング
  • マルチ テクスチャ ブレンディング
  • テクスチャによるライト マッピング

テクスチャ ブレンディングを使用する場合、ユーザーのハードウェアがテクスチャ ブレンディングをサポートしているかどうかを最初に調べる必要がある。これらの情報は、D3DCAPS8 構造体の TextureCaps メンバに保持されている。テクスチャ ブレンディング機能についてユーザーのハードウェアに問い合わせる方法の詳細については、「IDirect3DDevice8::GetDeviceCaps」を参照すること。


アルファ テクスチャ ブレンディング

Microsoft® Direct3D® では、プリミティブをレンダリングするとき、プリミティブのマテリアルまたはその頂点の色、およびライティング情報に基づいてプリミティブの色を生成する。詳細については、「ライティングとマテリアルの概要」を参照すること。アプリケーションでテクスチャ ブレンディングが有効になっている場合、Direct3D は処理されたポリゴンのピクセル カラーの値を、既にフレーム バッファに格納されているピクセルと組み合わせなければならない。Direct3D では、次の公式を使用して、プリミティブの画像の各ピクセルに対する最終色を決める。

FinalColor = TexelColor × SourceBlendFactor + PixelColor × DestBlendFactor

この公式で、FinalColor は、ターゲット レンダリング サーフェスに出力される最後のピクセル カラーである。TexelColor は、カレント ピクセルに対応する入力カラー値 (テクスチャ フィルタリング後) を表す。Direct3D でテクセルをピクセルにマッピングする方法の詳細については、「テクスチャ フィルタリング」を参照すること。SourceBlendFactor は、最後に適用する入力カラー値の割合を決めるために Direct3D が使用する計算値である。PixelColor は、プリミティブの画像内に現在格納されているピクセルの色である。DestBlendFactor は、最後にレンダリングされるピクセルで使用されるカレント ピクセルの色の割合を表す。SourceBlendFactor と DestBlendFactor の値は、0.0 と 1.0 を含む 0.0 ～ 1.0 である。

上の公式からわかるように、SourceBlendFactor が D3DBLEND_ONE で DestBlendFactor が D3DBLEND_ZERO の場合、最後にレンダリングされるピクセルは透明度がないものとしてレンダリングされる。SourceBlendFactor が D3DBLEND_ZERO で DestBlendFactor が D3DBLEND_ONE の場合は、テクスチャは完全に透明になる。これらの係数に上記以外の値を設定した場合は、最後にレンダリングされるピクセルはある程度の透明性のある色とブレンドされる。

テクスチャ フィルタリング後は、すべてのピクセル カラー値は、赤色、緑色、および青色のカラー値を持っている。デフォルトでは、Direct3D は D3DBLEND_SRCALPHA を SourceBlendFactor として、D3DBLEND_INVSRCALPHA を DestBlendFactor として使用する。したがって、アプリケーションでは、テクスチャのアルファ値を設定することで処理されたピクセルの透明度を制御できる。

C++ で開発するアプリケーションでは、D3DRS_SRCBLEND および D3DRS_DESTBLEND レンダリング ステートを使用してブレンディング係数を制御する。IDirect3DDevice8::SetRenderState メソッドを呼び出し、第 1 パラメータの値としてレンダリング ステート値のいずれかを渡す。第 2 パラメータは、D3DBLEND 列挙型のメンバでなければならない。


マルチパス テクスチャ ブレンディング

Microsoft® Direct3D® アプリケーションでは、マルチ レンダリング パスでプリミティブに各種テクスチャを適用して、数多くの特殊効果を実現できる。この処理は一般にマルチパス テクスチャ ブレンディングと呼ばれる。マルチパス テクスチャ ブレンディングの一般的な用途は、いくつかの異なるテクスチャから複数の色を適用して、複雑なライティングおよびシェーディング モデルのエフェクトをエミュレートすることである。これをライト マッピングと呼ぶ。詳細については、「テクスチャによるライト マッピング」を参照すること。

注 デバイスによっては、単一のパスで、複数のテクスチャをプリミティブに適用できる場合もある。詳細については、「マルチ テクスチャ ブレンディング」を参照すること。

ユーザーのハードウェアでマルチ テクスチャ ブレンディングがサポートされていない場合でも、アプリケーションでは、マルチパス テクスチャ ブレンディングを使用して同じ視覚エフェクトを実現できる。ただし、マルチ テクスチャ ブレンディングを使用した場合には、アプリケーションは可能なフレーム レートを維持できない。

C++ アプリケーションでマルチ テクスチャ ブレンディングを実行するには

  1. IDirect3DDevice8::SetTexture メソッドを呼び出して、テクスチャ ステージ 0 にテクスチャを設定する。
  2. IDirect3DDevice8::SetTextureStageState メソッドを使用して、目的の色およびアルファ ブレンディング引数と処理を選択する。マルチパス テクスチャ ブレンディング用の最適な設定はデフォルト設定である。
  3. シーン内の適切なオブジェクトをレンダリングする。
  4. 次のテクスチャをテクスチャ ステージ 0 に設定する。
  5. D3DRS_SRCBLEND および D3DRS_DESTBLEND レンダリング ステートを設定して、ブレンド元およびブレンド先のブレンディング係数を必要に応じて調整する。これらのパラメータに基づいて、新しいテクスチャがレンダリング ターゲット サーフェス内の既存のピクセルでブレンドされる。
  6. 必要に応じて、ほかのテクスチャに対して手順 3、4、および 5 を繰り返す。


マルチ テクスチャ ブレンディング

Microsoft® Direct3D® では、単一のパスで、最大 8 つのテクスチャをプリミティブにブレンドできる。マルチ テクスチャ ブレンディングを使用すれば、Direct3D アプリケーションのフレーム レートを大幅に上げることができる。アプリケーションは、マルチ テクスチャ ブレンディングを採用して、テクスチャ、影、スペキュラ ライト、ディフューズ ライトなどの特殊効果を単一パスで適用できる。

マルチ テクスチャをブレンドするには、アプリケーションでそれらのテクスチャをカレント テクスチャ セットに割り当て、次にブレンディング ステージを作成する。以下のトピックでは、これらの手順の実行方法について説明する。

  • テクスチャ ステージとテクスチャ ブレンディング カスケード
  • テクスチャ ブレンディング処理と引数
  • カレント テクスチャの割り当て
  • ブレンディング ステージの作成


テクスチャ ステージとテクスチャ ブレンディング カスケード

Microsoft® Direct3D® は、テクスチャ ステージを使用して、シングルパスのマルチ テクスチャ ブレンディングをサポートしている。テクスチャ ステージには 2 つの引数を受け取り、ブレンディング処理を行い、後続の処理またはラスタ化に結果を渡す。テクスチャ ステージは、次の図のように図式化できる。

上の図に示すように、テクスチャ ステージは指定のオペレータを使用して 2 つの引数をブレンドする。一般的な操作には、引数の色またはアルファ要素の単純変調や加算があるが、20 以上の操作がサポートされている。ステージの引数は、関連付けられたテクスチャ、補間色または補間アルファ (グーロー シェーディング中の補間)、任意の色とアルファ、または以前のテクスチャ ステージからの結果である。詳細については、「テクスチャ ブレンディング処理と引数」を参照すること。

注 Direct3D では、カラー ブレンディングとアルファ ブレンディングを区別する。アプリケーションでは、色とアルファに対して個別にブレンディング処理と引数を設定し、これらの設定が互いの結果に影響することはない。

マルチ ブレンディング ステージで使用される引数と処理の組み合わせは、単純なフローを基本とするブレンディング言語を定義する。1 つのステージの結果は別のステージに流れ、次にそのステージの結果が次のステージに流れ、以下同様に続く。ステージからステージへの流れが最終的にポリゴン上でラスタ化される概念を、通常、テクスチャ ブレンディング カスケードと呼ぶ。次の図は、個別のテクスチャ ステージがどのようにテクスチャ ブレンディング カスケードを構成するかを示している。

デバイス内の各ステージは、0 から始まるインデックスを持つ。Direct3D では、最大 8 つのブレンディング ステージを利用できる。ただし、現在のハードウェアでサポートされるステージ数を判断するために、デバイス機能を調べる必要がある。第 1 ブレンディング ステージはインデックス 0 にあり、第 2 ステージはインデックス 1 にあり、以下インデックス 7 まで同様である。システムは、インデックスの昇順にステージをブレンドする。

必要な数だけのステージを使用する。使用しないブレンディング ステージはデフォルトで無効になる。アプリケーションが最初の 2 つのステージだけを使用する場合は、ステージ 0 と 1 についてだけ設定操作と引数が必要である。システムは 2 つのステージをブレンドし、無効なステージを無視する。

最適化に関する注意 オブジェクトによっては 4 つのステージを使用したり、2 つのステージを使用するなど、状況に応じてアプリケーションで使用するステージの数が変わる場合は、以前に使用したすべてのステージを明示的に無効にしなくてもよい。最初の未使用のステージに対してカラー処理を無効にしても、それよりインデックスが大きいステージでは無効にならない。カラー処理を最初のテクスチャ ステージ (ステージ 0) に設定すると、すべてのテクスチャ マッピングを無効にできる。


テクスチャ ブレンディング処理と引数

アプリケーションでは、ブレンディング ステージをカレント テクスチャ セットの各テクスチャに関連付ける。「テクスチャ ステージとテクスチャ ブレンディング カスケード」で説明するように、Microsoft® Direct3D® では、セットの最初のテクスチャから順に 8 番目のテクスチャまで各ブレンディング ステージを評価する。

Direct3D では、カレント テクスチャ セットの各テクスチャの情報を、関連付けられているブレンディング ステージに適用する。アプリケーションでは、IDirect3DDevice8::SetTextureStageState を呼び出して、所定のテクスチャ ステージからどの情報を使用するかを制御する。カラー チャネルとアルファ チャネルの処理は、個別に設定することができる。各処理では 2 つの引数を使用する。カラー チャネル処理を指定するには、D3DTSS_COLOROP ステージ ステートを使用し、アルファ処理を指定するには、D3DTSS_ALPHAOP ステージ ステートを使用する。これらのステージ ステートは共に D3DTEXTUREOP 列挙型からの値を使用する。

テクスチャ ブレンディング引数には、D3DTEXTURESTAGESTATETYPE 列挙型の D3DTSS_COLORARG1、D3DTSS_COLORARG2、D3DTSS_ALPHARG1、および D3DTSS_ALPHARG2 メンバを使用する。対応する引数は、テクスチャ引数フラグを使用して識別する。

注 あるテクスチャ ステージのカラー処理を D3DTOP_DISABLE に設定することで、そのテクスチャ ステージと、それに続くカスケード内のテクスチャ ブレンディング ステージを無効にすることができる。カラー処理を無効すると、アルファ処理も同様に無効になる。カラー処理が有効のときに、アルファ処理を無効にすることはできない。カラー ブレンディングが有効のときにアルファ処理を D3DTOP_DISABLE に設定すると、その動作は不定である。

デバイスでサポートされているテクスチャ ブレンディング処理を調べるには、D3DCAPS8 構造体の TextureCaps メンバに問い合わせる。


カレント テクスチャの割り当て

Microsoft® Direct3D® は、最大 8 つのカレント テクスチャによるリストを利用できる。Direct3D では、レンダリングするすべてのプリミティブに、これらのテクスチャをブレンドする。テクスチャ インターフェイス ポインタとして作成したテクスチャのみ、カレント テクスチャ セットで使用できる。

アプリケーションでは、IDirect3DDevice8::SetTexture メソッドを呼び出してカレント テクスチャ セットにテクスチャを割り当てる。第 1 パラメータは、0 ～ 7 の範囲の数値でなければならない。第 2 パラメータとして、テクスチャ インターフェイス ポインタを渡す。

次の C++ コードは、テクスチャをカレント テクスチャ セットに割り当てる方法を示している。

// このサンプル コードでは、
// 変数 lpd3dDev は IDirect3DDevice8 インターフェイスへの有効なポインタであり、
// pTexture は IDirect3DBaseTexture8 インターフェイスへの有効なポインタであると仮定している。

// 3 番目のテクスチャを設定する。
d3dDevice->SetTexture(2, pTexture);

注 ソフトウェア デバイスでは、テクスチャを一度に複数のテクスチャ ステージに割り当てることはできない。


ブレンディング ステージの作成

ブレンディング ステージとは、テクスチャのブレンディング方法を定義する、一連のテクスチャ処理と引数である。ブレンディング ステージを作成するとき、C++ アプリケーションでは IDirect3DDevice8::SetTextureStageState メソッドを呼び出す。最初の呼び出しは、実行する処理を指定する。さらに 2 回の呼び出しを行って、処理を適用する引数を定義する。次のサンプル コードは、ブレンディング ステージの作成方法を示している。

// この例では、lpD3DDev が IDirect3DDevice8 インターフェイスへの
// 有効なポインタであると仮定している。

// 最初のテクスチャの処理を設定する。
d3dDevice->SetTextureStageState(0, D3DTSS_COLOROP, D3DTOP_ADD);

// 引数 1 をテクスチャ カラーに設定する。
d3dDevice->SetTextureStageState(0, D3DTSS_COLORARG1, D3DTA_TEXTURE);

// 引数 2 を補間するディフューズ色に設定する。
d3dDevice->SetTextureStageState(0, D3DTSS_COLORARG2, D3DTA_DIFFUSE);

テクスチャのテクセル データには、カラー値とアルファ値が含まれる。アプリケーションでは、単一のブレンディング ステージでカラー値とアルファ値の両方を定義できる。カラー処理とアルファ処理には、それぞれ独自の引数がある。詳細については、「D3DTEXTURESTAGESTATETYPE」を参照すること。

Microsoft® Direct3D® API に含まれてはないが、次のマクロをアプリケーションに挿入して、テクスチャ ブレンディング ステージの作成に必要なコードを短縮することができる。

#define SetTextureColorStage( dev, i, arg1, op, arg2 )     \
   dev->SetTextureStageState( i, D3DTSS_COLOROP, op);      \
   dev->SetTextureStageState( i, D3DTSS_COLORARG1, arg1 ); \
   dev->SetTextureStageState( i, D3DTSS_COLORARG2, arg2 );

#define SetTextureAlphaStage( dev, i, arg1, op, arg2 )     \
   dev->SetTextureStageState( i, D3DTSS_ALPHAOP, op);      \
   dev->SetTextureStageState( i, D3DTSS_ALPHARG1, arg1 );  \
   dev->SetTextureStageState( i  D3DTSS_ALPHARG2, arg2 );


テクスチャによるライト マッピング

3D シーンをリアルにレンダリングするには、光源がシーンの表示に与えるエフェクトを考慮しなければならない。フラット シェーディングやグーロー シェーディングなどの技術はこの点で貴重なツールであるが、これらの技術だけでは不十分である。Microsoft® Direct3D® は、マルチパスのマルチ テクスチャ ブレンディングをサポートしている。これらの能力を使用することで、シェーディング手法だけでレンダリングするよりも、よりリアルなシーンをレンダリングできる。1 つまたは複数のライト マップを利用すれば、プリミティブにライティングと影の領域をマップできる。

ライト マップとは、3D シーンのライティングについての情報を含むテクスチャまたはテクスチャ グループのことである。このライティング情報をライト マップのアルファ値、カラー値、またはその両方に格納できる。

マルチパス テクスチャ ブレンディングを使用してライト マッピングを実現する場合は、最初のパスでプリミティブにライト マップをレンダリングする必要がある。また、第 2 のパスを使用して、ベース テクスチャをレンダリングする必要がある。ただし、スペキュラ ライト マッピングは除く。スペキュラ ライト マップの場合は、最初にベース テクスチャをレンダリングし、次にライト マップを追加する。

マルチ テクスチャ ブレンディングによって、1 つのパスでライト マップとベース テクスチャをレンダリングできる。ユーザーのハードウェアでマルチ テクスチャ ブレンディングがサポートされている場合は、ライト マッピングを行うときにこのブレンディングを利用するようにする。これにより、アプリケーションのパフォーマンスが大幅に向上する。

ライト マップを使用すれば、Direct3D アプリケーションでは、プリミティブをレンダリングするときにさまざまなライティング エフェクトを生成できる。モノクロ ライティングやカラー ライティングをシーンにマッピングできるほか、スペキュラ ハイライトやディフューズ ライトなどの細かなエフェクトも追加できる。

Direct3D テクスチャ ブレンディングを使用してライト マッピングを実行する方法については、以下のトピックで説明する。

  • モノクロ ライト マップ
  • カラー ライティング マップ
  • スペキュラ ライト マップ
  • ディフューズ ライト マップ


モノクロ ライト マップ

一部の古い 3D アクセラレータ ボードでは、転送先ピクセルのアルファ値を使用するテクスチャ ブレンディングをサポートしていない場合がある。詳細については、「アルファ テクスチャ ブレンディング」を参照すること。これらのアダプタでは、一般にマルチ テクスチャ ブレンディングもサポートしていない。このようなアダプタでアプリケーションを実行する場合は、マルチパス テクスチャ ブレンディングを使用してモノクロ ライト マッピングを実行できる。

モノクロ ライト マッピングを実行するには、アプリケーションでライティング情報をライト マップ テクスチャのアルファ データに格納する。アプリケーションは、Microsoft® Direct3D® のテクスチャ フィルタリング能力を使用して、プリミティブの画像の各ピクセルからライト マップの対応するテクセルへのマッピングを実行する。プログラムで、転送元ブレンディング係数を対応するテクセルのアルファ値に設定する。

次の C++ コードは、アプリケーションでテクスチャをモノクロ ライト マップとして使用する方法を示している。

// この例では、d3dDevice は IDirect3DDevice8 インターフェイスへの有効なポインタであり、
// lptexLightMap はモノクロ ライト マップ データを含むテクスチャへの
// 有効なポインタであると仮定している。

// ライト マップ テクスチャをカレント テクスチャとして設定する。
d3dDevice->SetTexture(0, lptexLightMap);

// カラー処理を設定する。
d3dDevice->SetTextureStageState(0, D3DTSS_COLOROP, D3DTOP_SELECTARG1);

// 引数 1 をカラー処理に設定する。
d3dDevice->SetTextureStageState(0, D3DTSS_COLORARG1,
       D3DTA_TEXTURE | D3DTA_ALPHAREPLICATE);

転送先アルファ ブレンディングをサポートしていないディスプレイ アダプタは、通常マルチ テクスチャ ブレンディングをサポートしていないので、この例では、すべての 3D アクセラレータ カードで使用できるライト マップを最初のテクスチャとして設定している。また、この例では、テクスチャのブレンディング ステージに対するカラー処理を設定して、テクスチャ データをプリミティブの既存の色とブレンドしている。その次に、入力データとして最初のテクスチャとプリミティブの既存の色を選択している。


カラー ライティング マップ

一般に、カラー ライティング マップを使用すれば、3D シーンをよりリアルにレンダリングできる。カラー ライティング マップは、ライティング情報としてライト マップのRGB データを使用する。

次の C++ コードは、RGB カラー データを使用したライト マッピングを示している。

// この例では、d3dDevice は IDirect3DDevice8 インターフェイスへの有効なポインタであり、
// lptexLightMap は RGB ライト マップ データを含むテクスチャへの
// 有効なポインタであると仮定している。

// ライト マップ テクスチャを最初のテクスチャとして設定する。
d3dDevice->SetTexture(0, lptexLightMap);

d3dDevice->SetTextureStageState( 0,D3DTSS_COLOROP, D3DTOP_MODULATE );
d3dDevice->SetTextureStageState( 0,D3DTSS_COLORARG1, D3DTA_TEXTURE );
d3dDevice->SetTextureStageState( 0,D3DTSS_COLORARG2, D3DTA_DIFFUSE );

この例では、ライト マップを最初のテクスチャとして設定している。その次に、最初のブレンディング ステージのステートを設定して、入力テクスチャ データを乗算している。また、最初のテクスチャとプリミティブのカレント カラーを乗算処理用の引数として使用している。


スペキュラ ライト マップ

光源で照らしたときに輝くオブジェクト (反射性の高いマテリアルを使用するオブジェクト) は、スペキュラ ハイライトを受け取る。場合によっては、ライティング モジュールで生成されたスペキュラ ハイライトは正確でない場合もある。より効果的なハイライトを生成するために、多くの Microsoft® Direct3D® アプリケーションではプリミティブにスペキュラ ライト マップを適用する。

スペキュラ ライト マッピングを実行するには、まずスペキュラ ライト マップをプリミティブの既存のテクスチャに合わせて乗算する。次に、モノクロまたは RGB ライト マップを追加する。

次のサンプル コードは、C++ でのこの処理を示している。

// この例では、d3dDevice は IDirect3DDevice8 インターフェイスへの
// 有効なポインタであると仮定している。
// lptexBaseTexture は、テクスチャへの有効なポインタである。
// lptexSpecLightMap は、RGB スペキュラ ライト マップ データを含む
// テクスチャへの有効なポインタである。
// lptexLightMap は、RGB ライト マップ データを含む
// テクスチャへの有効なポインタである。

// ベース テクスチャを設定する。
d3dDevice->SetTexture(0, lptexBaseTexture );

// ベース テクスチャ処理と引数を設定する。
d3dDevice->SetTextureStageState(0, D3DTSS_COLOROP, D3DTOP_MODULATE );
d3dDevice->SetTextureStageState(0, D3DTSS_COLORARG1, D3DTA_TEXTURE );
d3dDevice->SetTextureStageState(0, D3DTSS_COLORARG2, D3DTA_DIFFUSE );

// スペキュラ ライト マップを設定する。
d3dDevice->SetTexture(1, lptexSpecLightMap);

// スペキュラ ライト マップ処理と引数を設定する。
d3dDevice->SetTextureStageState(1, D3DTSS_COLOROP, D3DTOP_ADD );
d3dDevice->SetTextureStageState(1, D3DTSS_COLORARG1, D3DTA_TEXTURE );
d3dDevice->SetTextureStageState(1, D3DTSS_COLORARG2, D3DTA_CURRENT );

// RGB ライト マップを設定する。
d3dDevice->SetTexture(2, lptexLightMap);

// RGB ライト マップ処理と引数を設定する。
d3dDevice->SetTextureStageState(2,D3DTSS_COLOROP, D3DTOP_MODULATE);
d3dDevice->SetTextureStageState(2,D3DTSS_COLORARG1, D3DTA_TEXTURE );
d3dDevice->SetTextureStageState(2,D3DTSS_COLORARG2, D3DTA_CURRENT );


ディフューズ ライト マップ

光源で照らしたとき、光沢のないサーフェスはディフューズ ライトを放つ。ディフューズ ライトの輝きは、光源からの距離、およびサーフェス法線と光源の方向ベクトルとの角度によって異なる。ライティング計算によってシミュレートするディフューズ ライトのエフェクトは一般的なものである。

テクスチャ ライト マップを使用してディフューズ ライトをシミュレートできる。これを行うには、次の C++ コードで示すように、ディフューズ ライト マップをベース テクスチャに追加する。

// この例では、d3dDevice は IDirect3DDevice8 インターフェイスへの
// 有効なポインタであると仮定している。
// lptexBaseTexture は、テクスチャへの有効なポインタである。
// lptexDiffuseLightMap は、RGB ディフューズ ライト マップ データを含む
// テクスチャへの有効なポインタである。

// ベース テクスチャを設定する。
d3dDevice->SetTexture(0,lptexBaseTexture );

// ベース テクスチャ処理と引数を設定する。
d3dDevice->SetTextureStageState(0,D3DTSS_COLOROP,
       D3DTOP_MODULATE );
d3dDevice->SetTextureStageState(0,D3DTSS_COLORARG1, D3DTA_TEXTURE );
d3dDevice->SetTextureStageState(0,D3DTSS_COLORARG2, D3DTA_DIFFUSE );

// ディフューズ ライト マップを設定する。
d3dDevice->SetTexture(1,lptexDiffuseLightMap );

// ブレンディング ステージを設定する。
d3dDevice->SetTextureStageState(1, D3DTSS_COLOROP, D3DTOP_MODULATE );
d3dDevice->SetTextureStageState(1, D3DTSS_COLORARG1, D3DTA_TEXTURE );
d3dDevice->SetTextureStageState(1, D3DTSS_COLORARG2, D3DTA_CURRENT );


圧縮したテクスチャ リソース

Microsoft® Direct3D® は、3D モデルのテクスチャ処理に使用するサーフェス圧縮機能を備えている。ここでは、圧縮テクスチャ サーフェスのデータの作成および操作について説明する。

説明するトピックは、次のとおりである。

  • 圧縮したテクスチャとは
  • 圧縮したテクスチャ フォーマット
  • 圧縮したテクスチャの使い方


圧縮したテクスチャとは

テクスチャ マップとは、3D の形状の上に描画して細部を加えるデジタル画像のことである。テクスチャ マップは、ラスタ化の実行中にこのような形状にマッピングされる。このプロセスは、システム バスとメモリの両方を大量に使用する場合がある。テクスチャで消費されるメモリ容量を減らすために、Microsoft® Direct3D® ではテクスチャ サーフェスの圧縮をサポートしている。いくつかの Direct3D デバイスは、圧縮したテクスチャ サーフェスをネイティブにサポートする。このようなデバイスで圧縮したサーフェスを作成し、そのデバイスにデータをロードしてしまえば、ほかのテクスチャ サーフェスと同様に Direct3D でサーフェスを使用できる。テクスチャが 3D サーフェス オブジェクトにマップされる場合、Direct3D は圧縮の復元を処理する。


圧縮したテクスチャ フォーマット

ここでは、圧縮したテクスチャ フォーマットの内部組織について説明する。圧縮フォーマット間の変換には D3DX 関数を使用するため、これらの情報を詳しく知る必要はない。ただし、圧縮したサーフェス データを直接処理する場合は、この情報が役立つ。

Direct3D では、テクスチャ マップを 4 × 4 のテクセル ブロックに分割するために圧縮フォーマットを使用する。テクスチャに透過性が含まれない場合 (不透明)、または透過性が 1 ビット アルファで指定される場合、8 バイト ブロックがテクスチャ マップ ブロックを表す。テクスチャ マップに透過型テクセルが含まれない場合、アルファ チャネルを使用して 16 バイト ブロックがテクスチャ マップ ブロックを表す。

  • 不透明と 1 ビット アルファ テクスチャ
  • アルファ チャネルによるテクスチャ
  • ストレージの効率とテクスチャ圧縮について
  • 単一テクスチャ内でのフォーマットの組み合わせ

注 あらゆる単一のテクスチャでは、16 テクセルのグループごとに 64 ビットまたは 128 ビットとして格納されるデータを指定しなくてはならない。64 ビット ブロック (つまり、フォーマット DXT1) がテクスチャ用に使用される場合、いくつかのテクスチャのブロックごとに不透明と 1 ビット アルファ フォーマットを組み合わせることができる。つまり、色 0 と色 1 の符号なし整数のマグニチュードの比較は、16 テクセルの各ブロックごとに実行される。

128 ビット ブロックを使用する場合、テクスチャ全体にアルファ チャネルを明示的 (フォーマット DXT2 または DXT3) に、または補間したモード (フォーマット DXT4 または DXT5) で指定しなくてはならない。色の場合と同様、補間したモードを選択すると、8 つの補間したアルファか、ブロック単位で使用できる 6 つの補間したアルファ モードのいずれかを使用できる。さらに、アルファ 0 とアルファ 1 の大きさの比較は、ブロックごとに行われる。

DXTn フォーマットのピッチは、DirectX 7 で返されていたものとは異なっている。今後は、ブロック 1 行のピッチのことである。たとえば、幅が 16 とすると、ピッチは 4 ブロック (DXT1 は 4*8、DXT2 ～ 5 は 4*16) となる。


不透明と 1 ビット アルファ テクスチャ

テクスチャ フォーマット DXT1 は、不透明または単一の透過型色のあるテクスチャ用である。

各不透明または 1 ビット アルファ ブロックのために、2 つの 16 ビット値 (RGB 5:6:5 フォーマット) とピクセル単位の 2 ビットの 4 × 4 ビットマップが格納される。これは、16 テクセルに対して合計 64 ビット、つまり 4 ビット/テクセルとなる。ブロック ビットマップには、4 色間を選択するテクセルごとに 2 ビットがある。4 色のうち 2 色は、符号化されたデータに格納される。ほかの 2 色は、線形補間で格納される色から派生する。次の図は、このレイアウトを示している。

1 ビット アルファ フォーマットは、ブロックに格納される 16 ビットカラー値を比較することにより、不透明フォーマットと区別される。これらは、符号なしの整数として処理される。最初の色が次の色よりも大きい場合は、不透明テクセルだけが定義されていることを意味する。つまり、テクセルを表すのに 4 色が使用される。4 色の符号化には 2 つの派生した色があり、全 4 色は RGB 色空間に等しく配布される。このフォーマットは、RGB 5:6:5 フォーマットに類似している。ほかの点では、1 ビット アルファ透過性用にこれらの色は使用され、4 番目の色は透過型テクセルを表すために確保される。

3 つの色の符号化には 1 つの派生した色があり、4 番目の 2 ビット コードは透過型テクセル (アルファ情報) を含むために確保される。このフォーマットは、アルファ マスクを符号化するために使用される最後のビットのある RGBA 5:5:5:1 に類似している。

次のサンプル コードは、3 色または 4 色の符号化を選択するかどうかを決定するためのアルゴリズムを示す。

if (color_0 > color_1)
{
    // 4 色ブロック :ほかの 2 色を派生する。
    // 00 = 色 0、01 = 色 1、10 = 色 2、11 = 色 3
    // 64 ビット ブロックに格納された
    // 2 ビット フィールドに対応する 2 ビット コード。
    color_2 = (2 * color_0 + color_1 + 1) / 3;
    color_3 = (color_0 + 2 * color_1 + 1) / 3;
}
else
{
    // 3 色ブロック :ほかの色を派生する。
    // 00 = 色 0、01 = 色 1、10 = 色 2、
    // 11 = 透過型。
    // 64 ビット ブロックに格納された
    // 2 ビット フィールドに対応する 2 ビット コード。
     color_2 = (color_0 + color_1) / 2;
     color_3 = transparent;

}

透過型ピクセルの RGBA コンポーネントは、ブレンディング前にゼロに設定しておくことを勧める。

8 バイト ブロック用のメモリ層を次の表に示す。最初のインデックスが y 軸、2 番目のインデックスが x 軸に対応すると考える。たとえば、テクセル [1][2] は (x,y) = (2,1) でテクスチャ マップ ピクセルを参照する。

次の表は、8 バイト (64 ビット) ブロック用のメモリ レイアウトを示している。

単語アドレス | 16 ビット単語
0 | 色 _0
1 | 色 _1
2 | ビットマップ単語 _0
3 | ビットマップ単語 _1

色 0 と色 1 (2 極値での色) の配置を次に示す。

ビット | 色
04:00 (LSB) | 青色成分
10:5 | 緑色成分
15:11 | 赤色成分

ビットマップ word_0 の配置

ビット | テクセル
01:00 (LSB) | テクセル [0][0]
3:2 | テクセル [0][1]
5:4 | テクセル [0][2]
7:6 | テクセル [0][3]
9:8 | テクセル [1][0]
11:10 | テクセル [1][1]
13:12 | テクセル [1][2]
15:14 (MSB) | テクセル [1][3]

ビットマップ word_1 の配置

ビット | テクセル
01:00 (LSB) | テクセル [2][0]
3:2 | テクセル [2][1]
5:4 | テクセル [2][2]
7:6 | テクセル [2][3]
9:8 | テクセル [3][0]
11:10 | テクセル [3][1]
13:12 | テクセル [3][2]
15:14 (MSB) | テクセル [3][3]

不透明色符号の例

不透明符号の例として、赤と黒が極値であると仮定する。赤は色 _0、黒は色 _1 とする。一様に傾度を互いに分割したフォームの補間した 4 色がある。4 × 4 ビットマップの値を決定するには、次に示す計算式を使用する。

00 ? color_0
01 ? color_1
10 ? 2/3 color_0 + 1/3 color_1
11 ? 1/3 color_0 + 2/3 color_1

このビットマップは、次のようになる。

このビットマップは次のような一連の色となる。

1 ビット アルファ符号の例

符号なし 16 ビット整数 (色 _0) が符号なし 16 ビット整数 (色 _1) より小さい場合、このフォーマットが選択される。このフォーマットは、青空を背景にした木の葉などに使用できる。いくつかのテクセルは、3 色の緑の影が葉に対して使用される間に透過型として記される。これら 2 色は極値に適合し、3 番目の色は補間した色となる。

そのような画像の例を次に示す。

上の図で、白色で示す画像では、テクセルは透過型として符号化されることに注意すること。また、透過型テクセルの RGBA コンポーネントは、ブレンディング前にゼロに設定するよう注意すること。

色と透過性に対するビットマップ符号は、次の計算式を使用して決定される。

00 ? color_0
01 ? color_1
10 ? 1/2 color_0 + 1/2 color_1
11   ?   Transparent

ビットマップは、次のようになる。


アルファ チャネルによるテクスチャ

より複雑な透過性を示すテクスチャ マップの符号化には、2 とおりの方法がある。どちらの場合も、透過性を記述するブロックは既に記述されている 64 ビット ブロックより先に起こる。透過性はピクセル単位に 4 ビットの 4 × 4 ビットマップ (明示的な符号化)、またはそれ以下のビットのビットマップのどちらかであり、線形補間は色符号化で使用されることと類似する。

透過性ブロックと色ブロックの配置は、次の表に示すとおりである。

単語アドレス | 64 ビット ブロック
3:0 | 透過性ブロック
7:4 | 既に記述された 64 ビット ブロック

明示的なテクスチャ符号化

明示的なテクスチャ符号化 (DXT2 と DXT3 フォーマット) のために、透過性を記述するテクセルのアルファ成分は、テクセルごとに 4 ビットの 4 × 4 ビットマップで符号化される。これらの 4 ビットは、アルファ データで 4 つの最上位ビットをディザリングしたり、それらを単に使用するなど、さまざまな方法で達成できる。ただし、作成されると、あらゆる補間のフォームがないとそれだけでしか使用できない。

次の図は、64 ビットの透過性ブロックを示している。

注 Microsoft® Direct3D® の圧縮メソッドでは、4 つの最上位ビットを使用する。

次の表は、アルファ情報が各 16 ビット単語用に配置される方法について示している。

単語 0 用の配置は、次のとおりである。

ビット | アルファ
3:0 (LSB) | [0][0]
7:4 | [0][1]
11:8 | [0][2]
15:12 (MSB) | [0][3]

単語 1 用の配置は、次のとおりである。

ビット | アルファ
3:0 (LSB) | [1][0]
7:4 | [1][1]
11:8 | [1][2]
15:12 (MSB) | [1][3]

単語 2 用の配置は、次のとおりである。

ビット | アルファ
3:0 (LSB) | [2][0]
7:4 | [2][1]
11:8 | [2][2]
15:12 (MSB) | [2][3]

単語 3 用の配置は、次のとおりである。

ビット | アルファ
3:0 (LSB) | [3][0]
7:4 | [3][1]
11:8 | [3][2]
15:12 (MSB) | [3][3]

DXT2 と DXT3 の違いは、DXT2 フォーマットではカラー データはあらかじめアルファを掛けれられていることを前提としている。DXT3 フォーマットでは、カラー データはあらかじめアルファを掛けれられていないことを前提としている。これらの 2 つのフォーマットが必要とされる理由は、テクスチャが使用される大部分の場合、データをただ調べるだけではカラー値にアルファが掛かっているかどうかを判断できないからである。このような情報が実行時に必要なので、2 つの FOURCC コードを使用してこれらの場合を区別している。ただし、これらの 2 つのフォーマットに使用されるデータと補間のメソッドは同じである。

テクセルが透過型かどうかを判定するために DXT1 で使用される色比較は、このフォーマットでは使用されない。色比較なしでは、カラー データは常に 4 色モードとして処理されることを前提としている。つまり、DXT1 コードの先頭の if 文は次のようになる。

if ((color_0 > color_1) OR !DXT1) {

3 ビット線形アルファ補間

DXT4 および DXT5 フォーマットに対する透過性の符号は、色に使用される線形符号と類似する概念が基となる。2 つの 8 ビット アルファ値とピクセル単位に 3 ビットの 4 × 4 ビットマップは、ブロックの最初の 8 バイトに格納される。典型的なアルファ値は、中間アルファ値を補間するために使用される。追加情報は、2 つのアルファ値を格納する方法で利用できる。アルファ _0 がアルファ _1 より大きい場合、6 つの中間アルファ値が補間により作成される。また、4 つの中間アルファ値が指定されるアルファ極値間で補間される。2 つの追加の明示的なアルファ値は、0 (完全に透過型) と 255 (完全に不透明) となる。

次のサンプル コードは、このアルゴリズムを示している。

// 8 アルファ ブロックか 6 アルファ ブロックか。
if (alpha_0 > alpha_1) {
    // 8 アルファ ブロック :ほかの 6 つのアルファを派生する。
    // ビット コード 000 = アルファ 0、001 = アルファ 1、その他は補間される。
    alpha_2 = (6 * alpha_0 + 1 * alpha_1 + 3) / 7;    // ビット コード 010
    alpha_3 = (5 * alpha_0 + 2 * alpha_1 + 3) / 7;    // ビット コード 011
    alpha_4 = (4 * alpha_0 + 3 * alpha_1 + 3) / 7;    // ビット コード 100
    alpha_5 = (3 * alpha_0 + 4 * alpha_1 + 3) / 7;    // ビット コード 101
    alpha_6 = (2 * alpha_0 + 5 * alpha_1 + 3) / 7;    // ビット コード 110
    alpha_7 = (1 * alpha_0 + 6 * alpha_1 + 3) / 7;    // ビット コード 111
}
else {
    // 6 アルファ ブロック。
    // ビット コード 000 = アルファ 0、001 = アルファ 1、その他は補間される。
    alpha_2 = (4 * alpha_0 + 1 * alpha_1 + 2) / 5;    // ビット コード 010
    alpha_3 = (3 * alpha_0 + 2 * alpha_1 + 2) / 5;    // ビット コード 011
    alpha_4 = (2 * alpha_0 + 3 * alpha_1 + 2) / 5;    // ビット コード 100
    alpha_5 = (1 * alpha_0 + 4 * alpha_1 + 2) / 5;    // ビット コード 101
    alpha_6 = 0;                                      // ビット コード 110
    alpha_7 = 255;                                    // ビット コード 111
}

アルファ ブロックのメモリ層を次に示す。

バイト | アルファ
0 | アルファ _0
1 | アルファ _1
2 | [0][2] (2 LSBs) , [0][1], [0][0]
3 | [1][1] (1 LSB) , [1][0], [0][3], [0][2] (1 MSB)
4 | [1][3], [1][2], [1][1] (2 MSBs)
5 | [2][2] (2 LSBs) , [2][1], [2][0]
6 | [3][1] (1 LSB) , [3][0], [2][3], [2][2] (1 MSB)
7 | [3][3], [3][2], [3][1] (2 MSBs)

DXT4 と DXT5 の違いは、DXT4 フォーマットではカラー データはあらかじめアルファを掛けれられていることを前提としている。DXT5 フォーマットでは、カラー データはあらかじめアルファを掛けれられていないことを前提としている。これらの 2 つのフォーマットが必要とされる理由は、テクスチャが使用される大部分の場合、データをただ調べるだけではカラー値にアルファが掛かっているかどうかを判断できないからである。このような情報が実行時に必要なので、2 つの FOURCC コードを使用してこれらの場合を区別している。ただし、これらの 2 つのフォーマットに使用されるデータと補間のメソッドは同じである。

テクセルが透過型かどうかを判定するために DXT1 で使用される色比較は、これらのフォーマットでは使用されない。色比較なしでは、カラー データは常に 4 色モードとして処理されることを前提としている。つまり、DXT1 コードの先頭の if 文は次のようになる。

if ((color_0 > color_1) OR !DXT1) {


ストレージの効率とテクスチャ圧縮について

すべてのテクスチャ圧縮フォーマットは、2 の累乗である。これは、テクスチャが必ずしも正方形であるということではないが、X と Y が両方とも 2 の累乗であるということである。たとえば、テクスチャが初めは 512 × 128 バイトだとすると、次のミップマップ処理では 256 × 64 というように、各レベルが 2 の累乗ずつ減っていく。さらにレベルが小さくなり、テクスチャが 16 × 2 および 8 × 1 までフィルタリング処理されると、不用ビットができる。これは、圧縮ブロックが常に 4 × 4 のテクセル ブロックだからである。ブロックの未使用部分はパディングされる。最小レベルでは不用ビットがあるものの、全体的に得られるものは依然として重要である。理論的に最悪の場合とは、2K × 1 テクスチャ (2 の 0 乗) である。この場合、1 ブロックにつき 1 ピクセル行だけしか符号化されず、ブロックの残りの部分は未使用となる。


単一テクスチャ内でのフォーマットの組み合わせ

重要な点は、あらゆる単一のテクスチャでは、16 テクセルのグループごとに 64 ビットまたは 128 ビットとして格納されるデータを指定するよう注意するという点である。64 ビット ブロック (つまり、フォーマット DXT1) がテクスチャ用に使用される場合、いくつかのテクスチャのブロックごとに不透明と 1 ビット アルファ フォーマットを組み合わせることができる。つまり、色 0 と色 1 の符号なし整数のマグニチュードの比較は、16 テクセルの各ブロックごとに実行される。

128 ビット ブロックを使用する場合、テクスチャ全体にアルファ チャネルを明示的 (フォーマット DXT2 または DXT3) に、または補間したモード (フォーマット DXT4 または DXT5) で指定しなくてはならない。色の場合と同様、補間したモード (フォーマット DXT4 および DXT5) を選択する場合、8 つの補間したアルファか、ブロック単位で使用できる 6 つの補間したアルファ モードのいずれかを使用できることに注意すること。さらに、アルファ 0 とアルファ 1 のマグニチュードの比較は、ブロックごとに行われる。


圧縮したテクスチャの使い方

ここでは、Microsoft® Direct3D® アプリケーションで圧縮したテクスチャを使用する方法について説明する。

説明するトピックは、次のとおりである。

  • 圧縮したテクスチャのサポートの判定
  • 圧縮したテクスチャの作成
  • 圧縮したテクスチャの復元


圧縮したテクスチャのサポートの判定

アプリケーションでレンダリング デバイスを作成する前に、IDirect3D8::CheckDeviceFormat メソッドを呼び出して、圧縮テクスチャ サーフェスからのテクスチャ処理をデバイスがサポートするかどうかを調べることができる。このメソッドは、アダプタを表すデバイス上でサーフェス フォーマットがテクスチャとして使用できるかどうかを判定する。アダプタをテストするには、DXT1、DXT2、DXT3、DXT4、または DXT5 の FOURCC コードを使用するピクセル フォーマットのいずれかを指定する。CheckDeviceFormat が D3D_OK を返した場合、デバイスはそのフォーマットを使用する圧縮テクスチャ サーフェスから直接テクスチャを得ることができる。この場合、IDirect3DDevice8::SetTexture メソッドを呼び出して、Microsoft®Direct3D® で圧縮テクスチャ サーフェスを直接使用できる。次のコードは、アダプタが D3DFMT_DXT1 圧縮テクスチャ フォーマットをサポートするかどうかを判定する方法を示している。

BOOL IsCompressedTextureFormatOk( D3DFORMAT TextureFormat,
                                  D3DFORMAT AdapterFormat ) {
    HRESULT hr = pD3D->CheckDeviceFormat( D3DADAPTER_DEFAULT,
                                          D3DDEVTYPE_HAL,
                                          AdapterFormat,
                                          0,
                                          D3DRTYPE_TEXTURE,
                                          D3DFMT_DXT1);

    return SUCCEEDED( hr );
}

デバイスが圧縮テクスチャ サーフェスからのテクスチャ処理をサポートしない場合でも、テクスチャ データを圧縮フォーマット サーフェス内に格納できる。ただし、圧縮テクスチャをテクスチャとして使用する前に、サポートされるフォーマットに変換しなければならない。


圧縮したテクスチャの作成

アダプタで圧縮テクスチャ フォーマットをサポートできるデバイスを作成した後、圧縮テクスチャ リソースを作成できる。IDirect3DDevice8::CreateTexture を呼び出して、Format パラメータに圧縮テクスチャ フォーマットを指定する。

テクスチャ オブジェクトに画像をロードする前に、IDirect3DTexture8::GetSurfaceLevel メソッドを呼び出して、テクスチャ サーフェスへのポインタを取得する。

これで、D3DXLoadSurface で始まる D3DX 関数を使用して、GetSurfaceLevel で取得したサーフェスに画像をロードできる。これらの関数は、圧縮テクスチャ フォーマット間の変換を処理する。

SDK で提供される DXTex ツールを使用すると、圧縮したテクスチャ (DDS) ファイルの作成と変換を行うことができる。独自の DDS ファイルを作成することもできる。

この動作の利点は、アプリケーションで、特定のフォーマットで特定の幅と高さを持つサーフェスに必要なストレージ容量を計算しなくても圧縮したサーフェスのコンテンツをファイルにコピーできることである。

圧縮したテクスチャの 5 つのタイプを以下の表に示す。データの保存方法の詳細については、「圧縮したテクスチャ フォーマット」を参照すること。次の情報は、独自の圧縮ルーチンを記述する場合に必要である。

FOURCC | 説明 | アルファ値事前掛け算済み
DXT1 | 不透明/1 ビット アルファ | N/A
DXT2 | 明示的なアルファ | Yes
DXT3 | 明示的なアルファ | No
DXT4 | 補間したアルファ | Yes
DXT5 | 補間したアルファ | No

注 値事前掛け算済みではないフォーマットから値事前掛け算済みのフォーマットにデータを転送する場合、Direct3D はアルファ値を基に色をスケーリングする。値事前掛け算済みのファーマットから値事前掛け算済みではないフォーマットへのデータ転送はサポートされない。値事前掛け算済みのアルファ転送元から値事前掛け算済みではないアルファ転送先へのデータ転送を試すと、メソッドは D3DERR_INVALIDCALL を返す。値事前掛け算済みのアルファ転送元からアルファがない転送先にデータを転送すると、アルファでスケーリングされる転送元色成分はそのままコピーされる。


圧縮したテクスチャの復元

テクスチャ サーフェスの圧縮と同様、圧縮したテクスチャの復元は Microsoft®Direct3D® コピー サービスによって行うことができる。

ドライバがビデオ メモリ サーフェスの作成をサポートする場合は、圧縮したビデオ メモリ サーフェスから圧縮していないビデオやシステム メモリ サーフェスへのコピーにおける圧縮の復元も行う。

圧縮したシステム メモリ サーフェスから圧縮していないビデオ メモリ サーフェスへのコピーは多くの場合サポートされず、ドライバが圧縮したテクスチャをサポートする場合でもサポートされない。これは、圧縮したシステム メモリ サーフェスの圧縮の復元と、ビデオ メモリ サーフェスへのコンテンツの移動が不可能であることを示しているわけではない。単に、追加のステップを必要とするだけである。

ビデオ メモリへのシステム メモリ サーフェスの圧縮を復元するには

  1. 必要なディメンジョンとピクセル フォーマットのシステム メモリに、圧縮していないオフスクリーン プレーン サーフェスを作成する。
  2. 圧縮したシステム メモリ サーフェスから圧縮していないシステム メモリ サーフェスにコピーする
  3. 圧縮していないサーフェスから圧縮していないビデオ メモリ サーフェスにコピーする。


ボリューム テクスチャ リソース

以下のトピックでは、ボリューム テクスチャについて説明する。

  • ボリューム テクスチャとは
  • ボリューム テクスチャの使い方


ボリューム テクスチャとは

ボリューム テクスチャとは、三角形や線などの 2D プリミティブの描画に使用できるピクセル (テクセル) の 3D の集まりのことである。立体でテクスチャ処理されるプリミティブの各頂点には、3 要素のテクスチャ座標が必要である。プリミティブを描画する場合、各プリミティブに含まれるピクセルには、2D テクスチャの場合と同じような規則に従って、立体内のピクセルのカラー値が設定される。立体でペイントできる 3D プリミティブがないため、立体は直接レンダリングされない。

ボリューム テクスチャは、まだらなフォグ、爆発などの特殊効果に使用できる。

立体はスライスにまとめられ、幅 × 高さの 2D サーフェスがスタックされて、幅 × 高さ × 奥行きの立体を構成すると考えることができる。各スライスは、単一行である。立体は後続レベルを持つことができる。各レベルの大きさは、直前レベルの半分の大きさに切り捨てられる。次の図は、複数レベルを持つボリューム テクスチャを示している。


ボリューム テクスチャの使い方

次のコードは、ボリューム テクスチャを使用するために必要な手順を示している。

まず、各頂点に対して 3 つのテクスチャ座標を持つカスタム頂点タイプを指定する。次のコードに例を示す。

struct VOLUMEVERTEX
{
    FLOAT x, y, z;
    DWORD color;
    FLOAT tu, tv, tw;
};

#define D3DFVF_VOLUMEVERTEX (D3DFVF_XYZ|D3DFVF_DIFFUSE|
                             D3DFVF_TEX1|D3DFVF_TEXCOORDSIZE3(0))

次に、頂点にデータを設定する。

VOLUMEVERTEX g_vVertices[4] =
{
    { 1.0f, 1.0f, 0.0f, 0xffffffff, 1.0f, 1.0f, 0.0f },
    {-1.0f, 1.0f, 0.0f, 0xffffffff, 0.0f, 1.0f, 0.0f },
    { 1.0f,-1.0f, 0.0f, 0xffffffff, 1.0f, 0.0f, 0.0f },
    {-1.0f,-1.0f, 0.0f, 0xffffffff, 0.0f, 0.0f, 0.0f }
};

次に、頂点バッファを作成し、頂点のデータを設定する。

次の手順は、IDirect3DDevice8::CreateVolumeTexture メソッドを使用して、ボリューム テクスチャを作成することである。次のコードに例を示す。

LPDIRECT3DVOLUMETEXTURE8 volTexture;

d3dDevice->CreateVolumeTexture( 8, 4, 4, 1, 0, D3DFMT_R8G8B8,
                                D3DPOOL_MANAGED, &volTexture );

プリミティブをレンダリングする前に、カレント テクスチャを前の手順で作成したボリューム テクスチャに設定する。次のコードは、三角形のストリップのレンダリング プロセス全体を示している。

if( SUCCEEDED( d3dDevice->BeginScene() ) )
{
    // ボリューム テクスチャで四角形を描画する。
    d3dDevice->SetTexture( 0, pVolumeTexture );
    d3dDevice->SetVertexShader( D3DFVF_VOLUMEVERTEX );
    d3dDevice->SetStreamSource( 0, pVB, sizeof(VOLUMEVERTEX) );
    d3dDevice->DrawPrimitive( D3DPT_TRIANGLESTRIP, 0, 2);

   // シーンを終了する。
   d3dDevice->EndScene();
}


自動テクスチャ管理

テクスチャ管理とは、ある時点においてどのテクスチャがレンダリングに必要であるかを判断し、それらのテクスチャをビデオ メモリに確実にロードする処理である。ほかのアルゴリズムと同様、テクスチャ管理スキームもその複雑さはさまざまであるが、どのようなアプローチでテクスチャ管理を行う場合であっても、以下に示すタスクが重要である。

  • 使用可能なテクスチャ メモリの量の追跡
  • レンダリングに必要なテクスチャと不要なテクスチャの計算
  • 既存のテクスチャ リソースのうち、ほかのテクスチャ画像に再ロードできるテクスチャ リソースの判断、また破棄する必要があるサーフェス、および新しいテクスチャ リソースで置き換える必要があるサーフェスの判断

Microsoft® Direct3D® では、システムによるテクスチャ管理が実装されており、テクスチャはパフォーマンス最適化のために確実にロードされる。Direct3D が管理するテクスチャ リソースを管理下のテクスチャと呼ぶ。

テクスチャ マネージャは、テクスチャの最終使用時を示すタイムスタンプを利用してテクスチャを追跡する。次に、LRU (least-recently-used) アルゴリズムを用いて、削除する必要があるテクスチャを判断する。メモリから削除するテクスチャが 2 つある場合、テクスチャの優先度に基づいてテクスチャが削除される。2 つのテクスチャの優先度が同じ場合は、最終使用時が新しい方のテクスチャが削除される。ただし、2 つのテクスチャでタイムスタンプが同じ場合は、優先度の低いテクスチャが先に削除される。

テクスチャを作成するときに、そのテクスチャの自動テクスチャ管理を要求する。C++ アプリケーションで管理下のテクスチャを取得するには、IDirect3DDevice8::CreateTexture を呼び出し、Pool パラメータに D3DPOOL_MANAGED を指定して、テクスチャ リソースを作成する。ただし、テクスチャの作成場所を指定することはできない。管理下のテクスチャを作成するときには、D3DPOOL_DEFAULT または D3DPOOL_SYSTEMMEM フラグは使用できない。管理下のテクスチャを作成した後、IDirect3DDevice8::SetTexture メソッドを呼び出して、その管理下のテクスチャをレンダリング デバイスのテクスチャ カスケードのステージに設定できる。

テクスチャ サーフェスに対して IDirect3DResource8::SetPriority メソッドを呼び出して、管理下のテクスチャに優先度を割り当てることができる。

Direct3D では、必要に応じてテクスチャをビデオ メモリに自動的にダウンロードできるシステムは、非ローカル ビデオ メモリやその他の要素が使用可能であるかどうかによって、管理下のテクスチャをローカルまたは非ローカル ビデオ メモリにキャッシュする。管理下のテクスチャがキャッシュされる場所は、アプリケーションに通知されない。自動テクスチャ管理を利用する際に、この情報は必要ない。アプリケーションで使用するテクスチャがビデオ メモリに収まらないほどある場合、Direct3D はビデオ メモリから古いテクスチャを削除して、新しいテクスチャ用の領域を確保する。削除したテクスチャを再度使用する場合、システムはオリジナル システムメモリ テクスチャ サーフェスを使用して、テクスチャをビデオメモリ キャッシュに再ロードする。テクスチャの再ロードが必要であるが、これを行うとアプリケーションのパフォーマンスが低下する。

テクスチャ リソースを更新またはロックすることで、テクスチャのオリジナル システム メモリ コピーを動的に変更できる。ダーティー サーフェスが検出された場合 (更新の完了後、またはサーフェスのロック解除時)、テクスチャ マネージャはテクスチャのビデオ メモリ コピーを自動的に更新する。このときのパフォーマンスは、削除されたテクスチャを再ロードする場合と同様である。

ゲームで新しいレベルに移る際、アプリケーションでビデオ メモリからすべての管理下のテクスチャをフラッシュしなければならないときがある。すべての管理下のテクスチャを削除するよう明示的に要求するには、IDirect3DDevice8::ResourceManagerDiscardBytes メソッドを呼び出して、Bytes パラメータに 0 の値を指定する。このメソッドを呼び出すと、キャッシュされているローカルまたは非ローカル ビデオメモリ テクスチャが Direct3D によって破棄されるが、オリジナル システムメモリ コピーはそのまま残る。

リソース管理の詳細については、「リソースの管理」を参照すること。


テクスチャ処理におけるハードウェアによる制約

現在のハードウェアが、Microsoft® Direct3D® インターフェイスによって可能になる機能をすべて実装しているとは限らない。アプリケーションでユーザーのハードウェアをテストし、それに応じてレンダリング方法を調整する必要がある。

3D アクセラレータ カードの多くは、ブレンディング ユニットへの引数としてディフューズ補間値をサポートしていない。ただし、テクスチャ ブレンディングを実行する際は、アプリケーションで補間色データを導入できる。

3D ハードウェアによっては、ブレンディング ステージを最初のテクスチャに関連付けることができない場合もある。このようなアダプタの場合、アプリケーションではカレント テクスチャ セットの 2 番目および 3 番目のステージでブレンディングを実行する必要がある。

現時点では多くのハードウェアで制約があるため、IDirect3DDevice8 が提供するマルチ テクスチャ ブレンディング インターフェイスによるトライリニア ミップマップ補間を実行できるディスプレイ アダプタは少数である。特に、D3DTSS_MIPFILTER テクスチャ ステージ ステートを D3DTEXF_LINEAR に設定できるものはほとんどない。アプリケーションでマルチパス テクスチャ ブレンディングを使用して同じエフェクトを得るか、広くサポートされている D3DTEXF_POINT ミップマップ フィルタ モードを使用するとよい。


深度バッファ

ここでは、深度バッファを使用して隠線と隠面を消す方法について説明する。説明するトピックは、次のとおりである。

  • 深度バッファとは
  • 深度バッファの使い方


深度バッファとは

z バッファまたは w バッファと呼ばれる深度バッファとは、Microsoft® Direct3D® で使用する奥行き情報を格納するデバイスのプロパティである。Direct3D が 3D シーンをターゲット サーフェスにレンダリングするとき、アタッチされた深度バッファ サーフェスのメモリを作業空間として使用して、ラスタ化したポリゴンのピクセルが互いにどのように覆い合うのかを判定できる。Direct3D は、オフスクリーン Direct3D サーフェスを、最終的なカラー値を書き込むターゲットとして使用する。レンダリング ターゲット サーフェスに関連する深度バッファ サーフェスは、シーンでの可視的ピクセルそれぞれの深さを Direct3D に知らせる深度情報の格納に使用する。

深度バッファリングを有効にして 3D シーンをラスタ化するとき、レンダリング サーフェス上の各ポイントが調べられる。深度バッファの値は、ポイントの z 座標または同次 w 座標 (射影空間のポイントの (x,y,z,w) 位置座標の) でありうる。z 値を使用する深度バッファは Z バッファと呼ばれ、w 値を使用する深度バッファは W バッファと呼ばれる。どの種類の深度バッファにも利点と欠点があるが、これについては後で説明する。

テストの最初に、深度バッファの深度値をシーンで可能な最大値に設定する。レンダリング サーフェス上のカラー値は、背景のカラー値またはそのポイントの背景テクスチャのカラー値に設定する。シーンの各ポリゴンを調べて、レンダリング サーフェス上のカレント座標 (x,y) に当たるかどうかを確かめる。交差する場合、現在のポイントでの深度値 (Z バッファの Z 座標または W バッファの W 座標) をテストして、深度バッファに既に格納されている深度値よりも小さいかどうかを確認する。ポリゴンの深度値の方が小さければ、その値が深度バッファに格納され、そのポリゴンからのカラー値がレンダリング サーフェス上の現在のポイントに書き込まれる。そのポイントでのポリゴンの深度値の方が大きければ、リストの次のポリゴンが調べられる。次の図に、この処理を示す。

注 ほとんどのアプリケーションではこの機能を使用しないが、深度バッファに入る値とレンダリング ターゲット サーフェスを判定するために Direct3D が使用するこの比較を変更できる。これを行うには、D3DRS_ZFUNC レンダリング ステートの値を変更すること。

現在では、市販のほとんどすべての 3D アクセラレータが、z バッファリングをサポートしており、Z バッファが最も一般的な深度バッファの種類になっている。しかし、Z バッファにも欠点がある。使用する数学的処理が原因で、Z バッファに生成される z 値は、Z バッファの範囲 (通常 0.0 から 1.0) 全体に均等に分散されない傾向がある。特に、遠くのクリップ面と近くのクリップ面の間の比率は、z 値の不均一な分散に強い影響を与える。近くの平面の距離に対する遠くの平面の距離の比率を 100% とした場合、深度バッファ範囲の 90% がシーンの深度範囲の最初の 10% に費やされる。娯楽や風景のシミュレーション用の典型的なアプリケーションでは、比率 (遠くの平面 / 近くの平面) がどこでも 1000 から 10000 の間である必要がある。比率が 1000 の場合、深度バッファ範囲の98% が深度範囲の最初の 2% に費やされ、比率が高くなるにつれて分散状態が悪くなる。これによって、遠くのオブジェクトでサーフェス ディテールが隠れてしまうことがある。これは、特に 16 ビット深度 (最も一般的なビット深度) バッファを使用する場合に顕著である。

一方、W 深度バッファでは、Z バッファの場合よりも、近くのクリップ面と遠くのクリップ面の間の分散がより均等である。したがって、遠くのクリップ面と近くのクリップ面の距離の比率が問題にならないという利点がある。これによって、アプリケーションは大きな最大範囲をサポートできる。ただし、視点に近い正確な深度バッファリングといっても相対的なものである。W 深度バッファは完璧ではなく、近くのオブジェクトのサーフェス ディテールが隠れることがある。もう 1 つの欠点は、ハードウェア サポートに関係することである。つまり、w バッファリングはハードウェアで z バッファリングほど広くはサポートされていない。

z バッファリングには、レンダリングのときにオーバーヘッドがある。Z バッファを使用するときに、レンダリングを最適化するために使用できるさまざまな技術がある。詳細については、「Z バッファのパフォーマンス」を参照すること。

注 深度値の実際の解釈は、3D レンダラによって異なる。


深度バッファの使い方

ここでは、一般的な深度バッファの使用方法について説明する。

  • 深度バッファのサポート状況の問い合わせ
  • 深度バッファの作成
  • 深度バッファリングを有効にする
  • 深度バッファの取得
  • 深度バッファのクリア
  • 深度バッファへの書き込みアクセスの変更
  • 深度バッファ比較関数の変更
  • Z バイアスの使い方

参照

深度バッファとは


深度バッファのサポート状況の問い合わせ

ほかの機能でも同様だが、アプリケーションで使用するドライバがあらゆる種類の深度バッファリングをサポートしているとは限らない。常にドライバの機能を調べる必要がある。z ベースの深度バッファリングはほとんどのデバイスでサポートされているが、w ベースの深度バッファリングは一部のデバイスでしかサポートされていない。サポートされていないスキームを有効にしても、ドライバは失敗しない。ドライバは別の深度バッファリングに頼ったり、場合によってはすべての深度バッファリングを無効にし、その結果、レンダリング後のシーンに深度ソートによる不自然な効果が現れることがある。

Direct3D デバイスを作成する前にアプリケーションで使用するディスプレイ デバイスについて Microsoft® Direct3D® に問い合わせることで、深度バッファのサポートを調べることができる。Direct3D オブジェクトから深度バッファリングをサポートしているとの報告があれば、この Direct3D オブジェクトから作成するハードウェア デバイスは z バッファリングをサポートする。

C++ アプリケーションで一般的な深度バッファリングのサポート状況を照会するには

深度バッファリングのサポート状況を問い合わせるには、IDirect3D8::CheckDeviceFormat メソッドを使用する。次のコードは、その例を示している。

// 次の例では、pCaps は初期化された D3DCAPS8 構造体への
// 有効なポインタであると仮定している。
    if( FAILED( m_pD3D->CheckDeviceFormat( pCaps->AdapterOrdinal,
                                           pCaps->DeviceType, Format,
                                           D3DUSAGE_DEPTHSTENCIL,
                                           D3DRTYPE_SURFACE,
                                           D3DFMT_D16 ) ) )
        return E_FAIL;

CheckDeviceFormat では、該当するデバイスの能力に基づいて、作成するデバイスを選択できる。この場合、16 ビットの深度バッファをサポートしないデバイスは拒否される。

また、IDirect3D8::CheckDepthStencilMatch を使用して、サポートされている深度ステンシル フォーマットがディスプレイ モードでレンダリング ターゲットのフォーマットと互換性があるかどうか、特に、深度フォーマットがレンダリング ターゲットのフォーマットと等しいかどうかを調べることができる。

次のコードに示すように、CheckDepthStencilMatch を使用して、深度ステンシルがレンダリング ターゲットと互換性があるかどうかを調べる。

// バック バッファが RTF フォーマットで、
// 深度ステンシル バッファが少なくとも 8 ビットのステンシルである一方で、
// RTF フォーマットのレンダリング ターゲットを作成できないデバイスは拒否する。
if( FAILED( m_pD3D->CheckDepthStencilMatch( pCaps->AdapterOrdinal,
                                            pCaps->DeviceType,
                                            AdapterFormat,
                                            RTFormat,
                                            D3DFMT_D24S8 ) ) )
        return E_FAIL;

ドライバで深度バッファがサポートされていることがわかったら、次は w バッファのサポート状況を調べることができる。深度バッファはすべてのソフトウェア ラスタライザでサポートされているが、w バッファはリファレンス ラスタライザでしかサポートされていない。これでは、実際のアプリケーションでの使用に適さない。アプリケーションで使用するデバイスがどのような種類でも、w ベース深度バッファリングを有効にする前に、w バッファのサポート状況を調べる必要がある。

C++ アプリケーションで w バッファのサポート状況を調べるには

  1. デバイスを作成した後、IDirect3DDevice8::GetDeviceCaps メソッドを呼び出して、初期化した D3DCAPS8 構造体を渡す。
  2. この呼び出しの後、プリミティブのレンダリングに関するドライバのサポートの情報が LineCaps メンバに入る。
  3. この構造体の RasterCaps メンバに D3DPRASTERCAPS_WBUFFER フラグが含まれている場合、ドライバは当該のプリミティブ タイプに対する W 深度バッファリングをサポートする。

深度バッファリングの一般情報については、「深度バッファとは」を参照すること。


深度バッファの作成

深度バッファはデバイスのプロパティである。Microsoft® Direct3D® によって管理される深度バッファを作成するには、D3DPRESENT_PARAMETERS 構造体の適切なメンバを設定する。次のコードは、その例を示している。

    D3DPRESENT_PARAMETERS d3dpp;

    ZeroMemory( &d3dpp, sizeof(d3dpp) );
    d3dpp.Windowed               = TRUE;
    d3dpp.SwapEffect             = D3DSWAPEFFECT_COPY_VSYNC;
    d3dpp.EnableAutoDepthStencil = TRUE;
    d3dpp.AutoDepthStencilFormat = D3DFMT_D16;

EnableAutoDepthStencil メンバを TRUE に設定して、アプリケーションの深度バッファを管理するよう Direct3D に指示する。AutoDepthStencilFormat は有効な深度バッファ フォーマットに設定すること。D3DFMT_D16 フラグは、16 ビットの深度バッファが使用できる場合は、それを指定する。

次の IDirect3D8::CreateDevice メソッドの呼び出しによって、深度バッファを作成するデバイスを作成する。

if( FAILED( g_pD3D->CreateDevice( D3DADAPTER_DEFAULT, D3DDEVTYPE_HAL, hWnd,
                                  D3DCREATE_SOFTWARE_VERTEXPROCESSING,
                                  &d3dpp, &d3dDevice ) ) )
    return E_FAIL;

深度バッファは、デバイスのレンダリング ターゲットとして自動的に設定される。デバイスがリセットされると、深度バッファは自動的に破棄され、新しいサイズで再作成される。

新しい深度バッファ サーフェスを作成するには、IDirect3DDevice8::CreateDepthStencilSurface メソッドを使用する。

デバイスの新しい深度バッファ サーフェスを設定するには、IDirect3DDevice8::SetRenderTarget メソッドを使用する

アプリケーションで深度バッファを使用するためには、深度バッファを有効にする必要がある。詳細については、「深度バッファリングを有効にする」を参照すること。


深度バッファリングを有効にする

「深度バッファの作成」で説明したように深度バッファを作成した後、IDirect3DDevice8::SetRenderState メソッドを呼び出して深度バッファリングを有効にする。D3DRS_ZENABLE レンダリング ステートを設定して深度バッファを有効にする。z バッファリングを有効にするには D3DZBUFFERTYPE 列挙型の D3DZB_TRUE メンバ (または TRUE) を、w バッファリングを有効にするには D3DZB_USEW を、深度バッファリングを無効にするには D3DZB_FALSE (または FALSE) をそれぞれ設定する。

注 w バッファリングを使用するには、アプリケーションで Microsoft® Direct3D® トランスフォーム パイプラインを使用しない場合であっても、対応する射影行列を設定しなければならない。適切な射影行列の設定については、「W バッファに有効な射影行列」を参照すること。「射影トランスフォームとは」で説明する射影行列は適切なものである。


深度バッファの取得

次のサンプル コードは、IDirect3DDevice8::GetDepthStencilSurface メソッドを使用して、デバイスが所有する深度バッファ サーフェスへのポインタを取得する方法を示している。

    LPDIRECT3DSURFACE8 pZBuffer;

    m_d3dDevice->GetDepthStencilSurface( &pZBuffer );


深度バッファのクリア

多くの C++ アプリケーションは、新しいフレームをレンダリングする前に深度バッファをクリアする。IDirect3DDevice8::Clear を呼び出して Flags パラメータに D3DCLEAR_ZBUFFER を指定することにより、Microsoft® Direct3D® で深度バッファを明示的にクリアできる。Clear メソッドでは、Z パラメータに任意の深度値を指定できる。


深度バッファへの書き込みアクセスの変更

デフォルトでは、Microsoft® Direct3D® システムは深度バッファへの書き込みが許されている。ほとんどのアプリケーションでは深度バッファへの書き込みを有効にしたままであるが、Direct3D システムによる深度バッファへの書き込みを禁止することによって、特殊効果を生成することができる。

C++ で深度バッファへの書き込みを無効にするには、State パラメータを D3DRS_ZWRITEENABLE に設定し、Value パラメータを 0 に設定して IDirect3DDevice8::SetRenderState メソッドを呼び出す。


深度バッファ比較関数の変更

デフォルトでは、レンダリング サーフェスの深度テストを行うとき、Microsoft® Direct3D® システムは、各ポイントに対応する深度値 (z または w) が深度バッファの既存の値より小さい場合、レンダリングターゲット サーフェスを更新する。C++ アプリケーションで、システムによる深度値の比較方法を変更するには、State パラメータを D3DRS_ZFUNC に設定して IDirect3DDevice8::SetRenderState メソッドを呼び出す。Value パラメータには、D3DCMPFUNC 列挙型の値を設定する必要がある。


Z バイアスの使い方

3D 空間で同一平面上にあるポリゴンは、それぞれのポリゴンに Z バイアスを追加することで、あたかも同一平面上にないように表示することができる。この技術は、シーン内の影を正しく表示するために使用されることが多い。たとえば、壁上の影の深度値が壁の深度値と同じになる可能性がある。最初に壁をレンダリングし、次に影をレンダリングすると、影が見えないか、または深度による不自然な効果が見える。同一平面上のオブジェクトのレンダリング順を逆にすると、これとは逆のエフェクトが得られるが、深度による不自然な効果が残ったままであることが多い。

C++ アプリケーションでは、同一平面上のポリゴン セットをレンダリングする際にシステムが使用する z 値にバイアスを追加することで、同一平面上のポリゴンを正しくレンダリングできる。z バイアスをポリゴン セットに追加するには、レンダリングの直前に IDirect3DDevice8::SetRenderState メソッドを呼び出す。このとき、State パラメータを D3DRS_ZBIAS に設定し、Value パラメータを 0 と 16 を含む 0 ～ 16 の値に設定する。z バイアス値が高いほど、同一平面上のほかのポリゴンと共に表示するとき、レンダリングするポリゴンが見える可能性が高くなる。


ステンシル バッファ

ここでは、ステンシル バッファの目的と使用方法について説明する。説明するトピックは、次のとおりである。

  • ステンシル バッファとは
  • ステンシル バッファの動作
  • ステンシル バッファのカスタマイズ


ステンシル バッファとは

ステンシル バッファは、レンダリング ターゲット サーフェスのピクセル単位の描画を有効または無効にする。このバッファの最も基本的なレベルでは、アプリケーションがレンダリングした画像の部分をマスクで覆うことが可能になり、その画像が表示されない。アプリケーションはディゾルブ、デカーリング、およびアウトライニングなどの特殊効果のためにステンシル バッファを使用することが多い。詳細については、「ステンシル バッファ技術」を参照すること。

ステンシル バッファ情報は、Z バッファ データに埋め込まれている。IDirect3D8::CheckDeviceFormat メソッドを使用して、ハードウェアがステンシルをサポートしているかどうかを調べることができる。次のコードに例を示す。

// 8 ビットのステンシル バッファリングを実行できないデバイスは拒否する。
// 次の例では、pCaps は初期化された D3DCAPS8 構造体への
// 有効なポインタであると仮定している。

if( FAILED( m_pD3D->CheckDeviceFormat( pCaps->AdapterOrdinal,
                                       pCaps->DeviceType,
                                       Format,
                                       D3DUSAGE_DEPTHSTENCIL,
                                       D3DRTYPE_SURFACE,
                                       D3DFMT_D24S8 ) ) )
        return E_FAIL;

CheckDeviceFormat では、該当するデバイスの能力に基づいて、作成するデバイスを選択できる。この場合、8 ビットのステンシル バッファをサポートしないデバイスは拒否される。これは CheckDeviceFormat で使用できる方法の 1 つにすぎない。詳細については、「ハードウェア サポートの判定」を参照すること。

デバイスでのステンシル バッファ制限を調べるには、サポートされているステンシル バッファ処理について D3DCAPS8 構造体の StencilCaps メンバに問い合わせる。


ステンシル バッファの動作

Microsoft® Direct3D® は、ステンシル バッファの内容をピクセル単位に調べる。ステンシル バッファの対応する値、ステンシル参照値、およびステンシル マスク値を使用して、ターゲット サーフェスの各ピクセルに対するテストを行う。テストにパスすると、Direct3D はアクションを実行する。このテストは次の手順で実行される。

  1. ステンシル参照値とステンシル マスクのビット積を計算する。
  2. カレント ピクセルに対するステンシル バッファ値とステンシル マスクのビット積を計算する。
  3. 比較関数を使用して、手順 1 と手順 2 の結果を比較する。

これらのステップを次の例で示す。

(StencilRef & StencilMask) CompFunc (StencilBufferValue & StencilMask)

ここで、StencilBufferValue は、カレント ピクセルに対するステンシル バッファの内容である。このコードでは、アンパサンド (&) 記号はビット積演算を表している。StencilMask はステンシル マスク、StencilRef はステンシル参照値を表している。CompFunc は比較関数である。

このステンシル テストにパスすると、カレント ピクセルはターゲット サーフェスに書き込まれるが、失敗した場合は無視される。デフォルトの比較処理では、各ビット演算の結果に関係なく、ピクセルが書き込まれる (D3DCMP_ALWAYS)。この動作を変更するには、目的の比較関数を指定する D3DCMPFUNC 列挙型のメンバを渡して、D3DRS_STENCILFUNC レンダリング ステートの値を変更する。


ステンシル バッファのカスタマイズ

アプリケーションでは、ステンシル バッファの処理をカスタマイズできる。アプリケーションでは、比較関数、ステンシル マスク、およびステンシル参照値を設定できる。また、ステンシル テストにパスした場合または失敗した場合に実行する Microsoft® Direct3D® の処理を制御することもできる。詳細については、「ステンシル バッファ ステート」を参照すること。


頂点バッファ

ここでは、Microsoft® Direct3D® アプリケーションにおいて頂点バッファを理解し、使用するのに必要な概念を説明する。説明するトピックは、次のとおりである。

  • 頂点バッファとは
  • 頂点バッファの記述
  • 頂点バッファのプールと使用
  • FVF 頂点バッファ
  • デバイスの種類と頂点処理の要件
  • 頂点バッファの使い方


頂点バッファとは

頂点バッファとは、IDirect3DVertexBuffer8 インターフェイスで表される、頂点データを含むメモリ バッファである。頂点バッファは、トランスフォーム済みの頂点、未トランスフォームの頂点、ライティング済みの頂点、未ライティングの頂点など、IDirect3DDevice8 インターフェイスの頂点バッファ レンダリング メソッドでレンダリング可能なあらゆる種類の頂点を含むことができる。頂点バッファ内の頂点を処理して、トランスフォーム、ライティング、クリッピング フラグの生成などの処理を実行できる トランスフォームは常に実行される。

頂点バッファは柔軟なので、トランスフォームされたジオメトリを再使用するための理想的なステージ ポイントとなる。単一の頂点バッファを作成して、頂点をトランスフォーム、ライティングを適用、およびその頂点バッファに頂点を切り取り、たとえインタリーブされたレンダリング ステートが変化した場合でも、シーンのモデルを何度も再トランスフォームせずにレンダリングできる。これは、マルチ テクスチャを使用するモデルのレンダリングの際に便利である。ジオメトリを一度トランスフォームすれば、要求されたテクスチャの変更に合わせてインタリーブして、必要に応じてその一部をレンダリングできる。頂点を処理した後で変更したレンダリング ステートは、次に頂点を処理するときに有効になる。詳細については、「頂点の処理」を参照すること。


頂点バッファの記述

頂点バッファの記述は、能力について行う。頂点バッファは、システム メモリ内にだけ存在できるのか、書き込み操作だけに使用されるのか、頂点バッファが含むことができる頂点の種類と数などを記述する。これらの特性はすべて D3DVERTEXBUFFER_DESC 構造体の中に保持される。

頂点バッファの記述によって、アプリケーションは、既存バッファが作成された方法および作成後に最適化されたかどうかを知ることができる。システムが作成済み頂点バッファの能力を書き込めるように、空白の記述構造体を用意する。このタスクの詳細については、「頂点バッファの記述の取得」を参照すること。

Format メンバは、頂点バッファであることを示す D3DFMT_VERTEXDATA に設定される。Type は、頂点バッファのリソース タイプを識別する。Usage 構造体のメンバは、一般的な能力フラグを格納する。D3DUSAGE_SOFTWAREPROCESSING フラグは、その頂点バッファがソフトウェア頂点処理に使用されることを示す。Usage に D3DUSAGE_WRITEONLY フラグがある場合は、頂点バッファ メモリは書き込み処理のみに使用される。これによりドライバは解放され、高速処理と高速レンダリングを可能にする最適なメモリ位置に頂点データが配置される。D3DUSAGE_WRITEONLY フラグが使用されていない場合、ドライバは、読み出し処理に効率の悪い位置にデータを配置しないようにする。これにより、処理速度やレンダリング速度が多少犠牲になる。このフラグが使用されていない場合、アプリケーションは、頂点バッファ内のデータで読み書きの処理を実行すると見なされる。

Pool は、頂点バッファに割り当てられるメモリ クラスを指定する。D3DPOOL_SYSTEMMEM フラグは、システムがシステム メモリ内に頂点バッファを作成したことを示す。

Size メンバは、単に頂点バッファ データのサイズをバイト数で格納する。FVF メンバは、バッファが格納する頂点のタイプを識別する柔軟な頂点フォーマット フラグの組み合わせを格納する。


頂点バッファのプールと使用

頂点バッファは、IDirect3DDevice8::CreateVertexBuffer メソッドで作成し、このメソッドはプール (メモリ クラス) パラメータと使用パラメータを取る。CreateVertexBuffer は、固定機能頂点処理またはプロセス頂点の出力として使用するため、柔軟な頂点フォーマット (FVF) コードを指定して作成することもできる。詳細については、「FVF 頂点バッファ」および「転送先頂点バッファの FVF 使用設定」を参照すること。

D3DUSAGE_SOFTWAREPROCESSING フラグは、そのデバイスに対してミックス モードまたはソフトウェア頂点処理 (D3DCREATE_MIXED_VERTEXPROCESSING / D3DCREATE_SOFTWARE_VERTEXPROCESSING) が有効になっているときに設定できる。D3DUSAGE_SOFTWAREPROCESSING はミックス モードでのソフトウェア頂点処理に使用するバッファに設定し、ミックス モードでのハードウェア頂点処理 (D3DCREATE_HARDWARE_VERTEXPROCESSING) 時に最高のパフォーマンスを得たいときは設定してはならない。ただし、単一のバッファがハードウェアおよびソフトウェア頂点処理の両方で使用される場合、D3DUSAGE_SOFTWAREPROCESSING を設定する以外のオプションはない。D3DUSAGE_SOFTWAREPROCESSING は、ソフトウェア デバイスだけでなくミックスにも設定することができる。

頂点処理がハードウェアで実行される場合でも、D3DPOOL_SYSTEMMEM を指定すれば、頂点バッファとインデックス バッファをシステム メモリ内に強制的に配置することができる。これは、ドライバによってこれらのバッファが AGP メモリに入れられたときに、ページ ロックされるメモリが多くなりすぎないようにする方法である。


FVF 頂点バッファ

有効な FVF コードで IDirect3DDevice8::CreateVertexBuffer の FVF パラメータをゼロ以外の値に設定すると、バッファの内容は FVF コードによって特性付けられる。FVF コードで作成された頂点バッファを、FVF 頂点バッファという。IDirect3DDevice8 のメソッドや使用によっては、FVF 頂点バッファを必要とする場合と非 FVF 頂点バッファを必要とする場合がある。FVF 頂点バッファは、IDirect3DDevice8::ProcessVertices の転送先頂点バッファ引数として必要である。

FVF 頂点バッファは、任意のストリーム番号の転送元データ ストリームにバインドできる。ただし、FVF 頂点バッファは、プログラムされた頂点シェーダへの入力として使用することはできない。

FVF 頂点バッファに D3DFVF_XYZRHW コンポーネントがある場合は、そのバッファ内の頂点が処理されていることを示す。ProcessVertices 転送先頂点バッファに使用される頂点バッファは、処理後の頂点バッファでなければならない。固定機能シェーダの入力に使用される頂点バッファは、処理前でも処理後でもかまわない。頂点バッファが処理後の場合には、シェーダはバイパスされ、プリミティブ クリッピングおよびセットアップ モジュールに直接データが渡される。

FVF 頂点バッファは、頂点シェーダと共に使用することができる。また、頂点ストリームは、非 FVF 頂点バッファが表すことのできる頂点フォーマットと同じ頂点フォーマットを表すことができる。別の頂点バッファからのデータを入力するために使用する必要はない。新しい頂点ストリームが持つ柔軟性により、データを別に維持する必要のあるアプリケーションでは、より高速な処理が行えるようになるが、これは必須ではない。アプリケーションがあらかじめインターリーブされたデータを保持できる場合は、パフォーマンスが向上する。アプリケーションが各レンダリング呼び出しの前にデータをインターリーブするだけの場合は、アプリケーション プログラミング インターフェイス (API) またはハードウェアに複数のストリームでこの処理を行わせなければならない。

頂点のパフォーマンスで最も重要なことは、32 バイトの頂点を使用し、良いキャッシュ順を保持することである。


デバイスの種類と頂点処理の要件

トランスフォームやライティングなどの頂点処理のパフォーマンスは、頂点バッファのメモリ内での位置座標と、使用されるレンダリング デバイスの種類に大きく依存する。頂点バッファを作成すると、アプリケーションはその頂点バッファへのメモリ割り当てを制御できる。D3DPOOL_SYSTEMMEM メモリ フラグが設定されているときは、システム メモリ内に頂点バッファが作成される。D3DPOOL_DEFAULT メモリ フラグを使用すると、頂点バッファ用のメモリの最良の割り当て場所をデバイス ドライバが決定し、このようにして決定されたメモリのことを多くの場合ドライバ最適化メモリと呼ぶ。ドライバ最適化メモリとしては、ローカル ビデオ メモリ、非ローカル ビデオ メモリ、またはシステム メモリが指定される。

D3DUSAGE_SOFTWAREPROCESSING 動作フラグを設定して IDirect3DDevice8::CreateVertexBuffer メソッドを呼び出すと、頂点バッファはソフトウェア頂点処理に使用される。このフラグは、混合頂点処理モードにおけるソフトウェア頂点処理で必要である。このフラグは、ソフトウェア頂点処理モードでは使用できるが、ハードウェア頂点処理モードでは使用できない。ソフトウェア頂点処理に使用される頂点バッファを次に示す。

  • IDirect3DDevice8::ProcessVertices のすべての入力ストリーム。
  • ソフトウェア頂点処理における、IDirect3DDevice8::DrawPrimitive および IDirect3DDevice8::DrawIndexedPrimitive のすべての入力ストリーム。詳細については、「D3DRS_SOFTWAREVERTEXPROCESSING」を参照すること。

頂点バッファがシステム メモリにあるか、ドライバ最適化メモリにあるかを調べる必要があるのは、テクスチャの場合と同じ理由からである。ハードウェアにおける頂点処理 (トランスフォームやライティングなど) に最適なのは、ドライバ最適化メモリに割り当てられた頂点バッファで、ソフトウェアでの頂点処理に最適なのは、システム メモリに割り当てられた頂点バッファである。テクスチャの場合、ハードウェア ラスタ化には、ドライバ最適化メモリに割り当てられたテクスチャが最適で、ソフトウェア ラスタ化には、システム メモリに割り当てられたテクスチャが最適である。

注 Microsoft® Direct3D® for Microsoft DirectX® 8.0 は、ProcessVertices メソッドでプリミティブをレンダリングしないスタンドアロン頂点処理をサポートする。このスタンドアロン頂点処理は、常にホスト プロセッサ上のソフトウェアで実行される。このため、IDirect3DDevice8::SetStreamSource の転送元として設定される頂点バッファは、D3DUSAGE_SOFTWAREPROCESSING フラグで作成する必要がある。ProcessVertices の機能は、IDirect3DDevice8::DrawPrimitive メソッドおよび IDirect3DDevice8::DrawIndexedPrimitive メソッドがソフトウェア頂点処理において提供する機能と同じである。詳細については、「頂点の処理」を参照すること。

アプリケーションが独自の頂点処理を実行する、また、トランスフォーム済みで、ライティングが適用され、クリッピングされた頂点を頂点バッファ レンダリング メソッドに渡す場合、アプリケーションはドライバ最適化メモリに割り当てられた頂点バッファに頂点を直接書き込むことができる。この方法により、以降の冗長なコピー処理を防止する。ただし、ドライバ最適化メモリからホストによって実行される読み取り処理は、非常に処理速度が遅いことがあるため、アプリケーションが頂点バッファからデータを読み返す場合には、この方法はうまく機能しない。したがって、アプリケーションで処理中に読み取り、またはバッファへのデータ書き込みを不規則に実行する必要がある場合は、システム メモリに頂点バッファを割り当てるとよい。

Direct3D 頂点処理機能を使用する場合 (未トランスフォームの頂点を頂点バッファ レンダリング メソッドに渡して)、デバイスの種類とデバイス作成フラグに応じて、ハードウェアまたはソフトウェアのいずれかで処理が実行される。最終的にあらゆる場合において最善のパフォーマンスを得られるように、頂点バッファはプール D3DPOOL_DEFAULT に割り当てることを推奨する。デバイスがハードウェア頂点処理を使用する場合は、フラグ D3DUSAGE_DYNAMIC および D3DUSAGE_WRITEONLY に基づいて実行できる追加の最適化機能がいくつかある。これらのフラグの使用方法の詳細については、「IDirect3DDevice8::CreateVertexBuffer」を参照すること。


頂点バッファの使い方

ここでは、頂点バッファ処理でアプリケーションが実行する一般的なタスクについて説明する。説明するトピックは、次のとおりである。

  • 頂点バッファの作成
  • 頂点バッファの内容へのアクセス
  • 頂点の処理
  • 頂点バッファからのレンダリング
  • 頂点バッファの記述の取得


頂点バッファの作成

5 つのパラメータを受け取る IDirect3DDevice8::CreateVertexBuffer メソッドを呼び出して、頂点バッファ オブジェクトを作成する。第 1 パラメータは、頂点バッファの長さをバイト数で指定する。頂点フォーマットのサイズをバイト単位で判定するには、sizeof 演算子を使用する。次に、カスタム頂点フォーマットの例を示す。

struct CUSTOMVERTEX {
        FLOAT x, y, z;
        FLOAT rhw;
        DWORD color;
        FLOAT tu, tv;   // テクスチャ座標。
};

// カスタム頂点構造体を記述するカスタム FVF。
#define D3DFVF_CUSTOMVERTEX (D3DFVF_XYZRHW | D3DFVF_DIFFUSE | D3DFVF_TEX1)

4 つの CUSTOMVERTEX 構造体を保持する頂点バッファを作成するには、Length パラメータに [4*sizeof(CUSTOMVERTEX)] を指定する。

第 2 パラメータは、使用コントロール セットである。特に、この値は、頂点バッファが表示領域外の頂点のクリッピング情報を (クリップ フラグ形式で) 保持することができるかどうかを指定する。クリップ フラグを格納できない頂点バッファを作成するには、Usage パラメータに D3DUSAGE_DONOTCLIP フラグを含める。D3DUSAGE_DONOTCLIP フラグは、頂点バッファがトランスフォーム済みの頂点を保持するように指示した場合、つまり、D3DFVF_XYZRHW フラグが FVF メンバに含まれる場合のみ適用される。未トランスフォームの頂点 (D3DFVF_XYZ フラグ) をバッファに含めるよう指示した場合、CreateVertexBuffer メソッドは D3DUSAGE_DONOTCLIP フラグを無視する。クリッピング フラグは追加メモリを占有するため、クリッピング可能な頂点バッファは、クリッピング フラグを含めない頂点バッファよりも若干大きくなる。リソースは頂点バッファが作成されるときに割り当てられるため、クリッピング可能な頂点バッファは先に要求しておかなければならない。

第 3 パラメータ FVF は、柔軟な頂点フォーマット フラグの組み合わせによって、頂点バッファの頂点フォーマットを記述する。このパラメータに 0 を指定した場合、頂点バッファは非 FVF 頂点バッファとなる。詳細については、「FVF 頂点バッファ」を参照すること。第 4 パラメータは、頂点バッファを格納するメモリ クラスを指定する。

CreateVertexBuffer が受け取る最後のパラメータは、呼び出しが成功したときに頂点バッファ オブジェクトの新しい IDirect3DVertexBuffer8 インターフェイスへのポインタが格納される変数のアドレスである。

注 クリップ フラグをサポートしないで作成された頂点バッファにクリップ フラグを生成することはできない。

次のコードは、C++ で頂点バッファを作成する方法を示している。

    // この例では、変数 d3dDevice は、
    // Direct3DDevice オブジェクトによって公開される IDirect3DDevice8 インターフェイスへのアドレスであり、
    // g_pVB は、LPDIRECT3DVERTEXBUFFER8 型の変数である。

// カスタムの頂点タイプ。
struct CUSTOMVERTEX {
        FLOAT x, y, z;
        FLOAT rhw;
        DWORD color;
        FLOAT tu, tv;   // テクスチャ座標。
};

#define D3DFVF_CUSTOMVERTEX (D3DFVF_XYZRHW | D3DFVF_DIFFUSE | D3DFVF_TEX1)

    // クリッピング可能な頂点バッファを作成する。3 つの CUSTOMVERTEX 構造体を保持するのに十分なメモリを
    // デフォルトのメモリ プールに割り当てる。

    if( FAILED( d3dDevice->CreateVertexBuffer( 3*sizeof(CUSTOMVERTEX),
                                                  0 /* 使用 */, D3DFVF_CUSTOMVERTEX,
                                                  D3DPOOL_DEFAULT, &g_pVB ) ) )
        return E_FAIL;


頂点バッファの内容へのアクセス

頂点バッファ オブジェクトを使うと、頂点データに割り当てられたメモリにアプリケーションが直接アクセスできる。IDirect3DVertexBuffer8::Lock メソッドを呼び出して頂点バッファ メモリへのポインタを取得し、次に必要に応じてメモリにアクセスして新しい頂点データをバッファに設定するか、既に設定されているデータを読み出す。Lock メソッドは 4 つのパラメータを受け取る。第 1 パラメータ OffsetToLock は、頂点データへのオフセットである。第 2 パラメータは頂点データのサイズをバイト数で示す。Lock メソッドが受け取る第 3 パラメータ ppbData は、呼び出しが成功した場合に、頂点データをポイントする BYTE ポインタのアドレスである。

最後のパラメータ Flags は、メモリのロック方法をシステムに知らせる。このパラメータを使って、バッファ内のデータにアプリケーションがどのようにアクセスするかを示すことができる。アプリケーションが頂点データにアクセスする方法に応じて、Flags パラメータに定数を指定する。これにより、ドライバはメモリをロックして、要求されているアクセス タイプで、最高のパフォーマンスを提供する。アプリケーションが頂点バッファ メモリから読み出しのみを行う場合は、D3DLOCK_READONLY フラグを使用する。このフラグを含めると、Microsoft® Direct3D® が内部手順を最適化するので効率が上がる。ただし、メモリへのアクセスは読み出し専用になる。

頂点データの設定または読み出しが終了したら、IDirect3DVertexBuffer8::Unlock メソッドを呼び出す。次のコードに例を示す。

// このコード例では、g_pVB は LPDIRECT3DVERTEXBUFFER8 型の変数であり、
// g_Vertices は頂点に正しく
// 初期化されているものと仮定している。

// 頂点バッファにデータを設定するには、頂点への
// アクセスを取得するため、バッファをロックする必要がある。これは、頂点バッファがデバイス メモリに存在している可能性があるために
// 必要となるメカニズムである。
VOID* pVertices;

if( FAILED( g_pVB->Lock( 0,                  // バッファの先頭から
                                             // 値を格納する。
                         sizeof(g_Vertices), // ロードするデータのサイズ。

                         (BYTE**)&pVertices, // 返される頂点データ。
                         0 ) ) )             // ロックにデフォルト フラグを送る。

    return E_FAIL;

memcpy( pVertices, g_Vertices, sizeof(g_Vertices) );
g_pVB->Unlock();

パフォーマンスの注意 D3DUSAGE_WRITEONLY フラグで頂点バッファを作成した場合、D3DLOCK_READONLY ロッキング フラグは使用できない。アプリケーションが頂点バッファ メモリから読み出しのみを行う場合は、D3DLOCK_READONLY フラグを使用する。このフラグを含めると、Direct3D が内部手順を最適化するので効率が上がる。ただし、メモリへのアクセスは読み出し専用になる。

Lock メソッドの Flags パラメータに D3DLOCK_DISCARD または D3DLOCK_NOOVERWRITE を使用する方法の詳細については、「動的な頂点およびインデックス バッファの使い方」を参照すること。

C++ では、頂点バッファに割り当てられているメモリに直接アクセスするので、アプリケーションが目的のメモリに正しくアクセスするよう注意すること。そうでないと、不正なメモリがレンダリングされるおそれがある。アプリケーションで使用する頂点フォーマットのストライドを利用して、割り当てられているバッファの頂点から次の頂点に移動する。頂点バッファ メモリは、柔軟な頂点フォーマットで指定された頂点の単純な配列である。定義する任意の頂点フォーマット構造体のストライドを使用する。頂点バッファの記述に含まれる柔軟な頂点フォーマット フラグを調べることで、実行時に各頂点のストライドを計算できる。次の表は、各頂点の成分のサイズを示している。

頂点フォーマット フラグ | サイズ
D3DFVF_DIFFUSE | sizeof(DWORD)
D3DFVF_NORMAL | sizeof(float) × 3
D3DFVF_SPECULAR | sizeof(DWORD)
D3DFVF_TEXn | sizeof(float) × n × t
D3DFVF_XYZ | sizeof(float) × 3
D3DFVF_XYZRHW | sizeof(float) × 4

頂点フォーマットに存在するテクスチャ座標の数は、D3DFVF_TEXn フラグで記述される (n は 0 ～ 8 の値)。その数だけあるテクスチャ座標で必要となるメモリを計算するには、テクスチャ座標セットの数にテクスチャ座標 1 セット分 (1 ～ 4 つの浮動小数) のサイズを乗ずる。

特定の頂点にアクセスするには、合計頂点ストライドを使用して、メモリ ポインタを必要なだけインクリメントまたはデクリメントする。


頂点の処理

頂点バッファでの頂点処理は、デバイスの現在のトランスフォーム行列に適用できる。オプションで、ライティング、クリップ フラグの生成、範囲の更新などの頂点処理も適用できる。説明するトピックは、次のとおりである。

  • 固定機能による頂点処理
  • プログラムによる頂点処理


固定機能による頂点処理

ここでは、固定機能による頂点処理について説明する。説明するトピックは、次のとおりである。

  • 固定機能による頂点処理について
  • 転送先頂点バッファの FVF 使用設定


固定機能による頂点処理について

固定機能頂点パイプラインでは、頂点バッファでの頂点処理は、デバイスの現在のトランスフォーム行列に適用できる。オプションで、ライティング、クリップ フラグの生成、範囲の更新などの頂点処理も適用できる。固定機能による頂点処理を使用する場合、転送先頂点バッファの要素の修正処理は D3DPV_DONOTCOPYDATA フラグによって制御される。このフラグは、固定機能による頂点処理のみに適用できる。IDirect3DDevice8インターフェイスは、頂点処理用の IDirect3DDevice8::ProcessVertices メソッドを公開する。頂点シェーダの頂点を入力データ ストリーム セットに処理し、ProcessVertices メソッドを呼び出して 1 つのインターリーブされた頂点データのストリームを生成する。このメソッドは、メソッドがターゲットとする頂点の位置と量、転送先頂点バッファ、および処理オプションを記述する 5 つのパラメータを受け取る。呼び出し後、処理された頂点データは転送先バッファに格納される。

第1 パラメータ SrcStartIndex、第 2 パラメータ DestIndex、第 3 パラメータ VertexCount は、それぞれ、最初にロードされる頂点のインデックス、頂点が配置される転送先頂点バッファのインデックス、処理して転送先バッファに配置する頂点の総数を示す。第 4 パラメータ pDestBuffer には、転送元頂点を受け取る頂点バッファ オブジェクトの IDirect3DVertexBuffer8 のアドレスを設定する。SrcStartIndex は、メソッドが頂点の処理を開始するインデックスを指定する。

最後のパラメータ Flags は、メソッドの特殊な処理オプションを指定する。このパラメータを 0 に設定すると、デフォルトの頂点処理が実行され、D3DPV_DONOTCOPYDATA を設定すると、何らかの状況において処理が最適化される。Flags を 0 に設定したときは、頂点処理の影響を受けない転送先頂点バッファの頂点フォーマットの頂点の成分は、頂点シェーダからコピーするか、0 に設定される。ただし、D3DPV_DONOTCOPYDATA を使用すると、Microsoft® Direct3D® によって色および座標情報が生成されない限り、ProcessVertices によって色および座標情報は上書きされない。ライティングが有効、つまり D3DRS_LIGHTING が TRUE のときは、ディフューズ色が生成される。ライティングが有効でスペキュラが有効、つまり D3DRS_SPECULARENABLE および D3DRS_LIGHTING が TRUE のときは、スペキュラ色が生成される。スペキュラ色は、フォグが有効のときも生成される。テクスチャ座標は、テクスチャ トランスフォームまたはテクスチャ生成が有効のときに生成される。ProcessVertices は、現在のレンダリング ステートを使用して、実行する頂点処理を決定する。

デバイスによる頂点処理の制限を判定するには、D3DCAPS8 構造体の VertexProcessingCaps メンバに、サポートする頂点処理能力を問い合わせる。


転送先頂点バッファの FVF 使用設定

IDirect3DDevice8::ProcessVertices メソッドでは、転送先頂点バッファの柔軟な頂点フォーマット フラグに対して特殊な設定が必要となる。柔軟な頂点フォーマット (FVF) の使用設定には、頂点処理の現在の設定との互換性がなければならない。

固定機能による頂点処理の場合、ProcessVertices は以下のような FVF 設定を必要とする。

  • 位置座標のタイプは常に D3DFVF_XYZRHW であり、D3DFVF_XYZ および D3DFVF_XYZB1 ～ D3DFVF_XYZB5 は無効である。
  • D3DFVF_NORMAL、D3DFVF_RESERVED0、および D3DFVF_RESERVED2 フラグは設定しない。
  • 以下の条件の OR 演算子が TRUE を返す場合、D3DFVF_DIFFUSE フラグを設定する必要がある。
    • ライティングが有効、つまり D3DRS_LIGHTING が TRUE である。
    • ライティングが無効であり、入力頂点ストリームにディフューズ色があり、D3DPV_DONOTCOPYDATA が設定されていない。
  • 以下の条件の OR 演算子が TRUE を返す場合、D3DFVF_SPECULAR フラグを設定する必要がある。
    • ライティングが有効でスペキュラ色が有効、つまり D3DRS_SPECULARENABLE が TRUE である。
    • ライティングが無効であり、入力頂点ストリームにスペキュラ色が存在し、D3DPV_DONOTCOPYDATA が設定されていない。
    • 頂点フォグが有効、つまり が D3DFOG_NONE に設定されていない。

また、テクスチャ座標のカウント数は、以下の方法で設定する。

  • すべてのアクティブ テクスチャ ステージに対して、テクスチャ トランスフォームとテクスチャ生成が無効の場合、D3DPV_DONOTCOPYDATA は設定されず、出力テクスチャ座標の数およびタイプは、入力テクスチャ座標の数およびタイプと一致しなければならない。D3DPV_DONOTCOPYDATA が設定されていて、テクスチャ トランスフォームとテクスチャ生成が無効な場合、出力テクスチャ座標は無視される。
  • いずれかのアクティブ テクスチャ ステージに対して、テクスチャ トランスフォームまたはテクスチャ生成が有効になっている場合、出力される頂点は入力された頂点よりも多くのテクスチャ座標を必要とすることがある。これは、テクスチャ生成によって生成されたりテクスチャ トランスフォームによって派生したテクスチャ座標による、テクスチャ座標の増殖によるものである。DrawPrimitive 呼び出しでも同様の増殖が発生するが、この場合はアプリケーション プログラマからは見えないことに注意すること。このケースでは、Microsoft® Direct3D® によって新しいテクスチャ座標セットが生成される。テクスチャ ステージが進み、テクスチャ生成、テクスチャ トランスフォーム、テクスチャ座標インデックスの設定を分析して、そのステージに固有のテクスチャ座標セットが必要かどうかを判定するにつれて、新しいテクスチャ座標セットが生成される。新しいセットが必要になるたびに、追加された順に割り当てられる。最大の、そして一般的な必要数は 1 ステージあたり 1 セットであるが、D3DTSS_TEXCOORDINDEX を介して未トランスフォームのテクスチャ座標を共有することによって、これより少ない場合もある。

つまり、テクスチャがそのステージにバインドされていて、以下の条件のいずれかが TRUE の場合、各テクスチャ ステージには、新しいテクスチャ座標セットが生成される。

  • そのステージのテクスチャ生成が有効である。
  • そのステージのテクスチャ トランスフォームが有効である。
  • 未トランスフォームの入力テクスチャ座標が、D3DTSS_TEXCOORDINDEX を介して初めて参照される。

Direct3D がテクスチャ座標を生成するとき、アプリケーションは以下のアクションを実行する必要がある。

  1. 適切な FVF 使用で転送先頂点バッファを使用する。
  2. 処理後のテクスチャ座標の配置に応じて、テクスチャ ステージの D3DTSS_TEXCOORDINDEX を再プログラムする。処理された頂点バッファを、その後の IDirect3DDevice8::DrawPrimitive 呼び出しや IDirect3DDevice8::DrawIndexedPrimitive 呼び出しで使用すると、D3DTSS_TEXCOORDINDEX 設定が再プログラムされることに注意すること。

最後に、テクスチャ座標のサイズ (D3DFVF_TEX0 ～ D3DFVF_TEX8) は、以下のように設定しなければならない。

  • 各テクスチャ座標セットに対するテクスチャ トランスフォームおよびテクスチャ生成が無効の場合、出力テクスチャ座標のサイズは入力と一致しなければならない。テクスチャ トランスフォームが有効の場合、出力のサイズは D3DTTFF_COUNT1、D3DTTFF_COUNT2、D3DTTFF_COUNT3、または D3DTTFF_COUNT4 によって定義されるカウントと一致しなければならない。テクスチャ トランスフォームが無効でテクスチャ生成が有効の場合、出力のサイズは、テクスチャ生成モードの設定に一致しなければならない。現在のところ、すべてのモードで 3 つの float 型の値が生成される。

転送先頂点バッファの FVF コードと互換性がないために ProcessVertices が失敗した場合、デバッグ出力に互換性を持つコードが出力される (デバッグ ビルドのみ)。


プログラムによる頂点処理

プログラムされた頂点シェーダを使用するときは、転送先頂点バッファで更新された要素は、シェーダ関数プログラムによって制御される。アプリケーションが転送先頂点のいずれかのレジスタに書き込みを行うと、転送先頂点バッファの各頂点内の対応する要素が更新される。アプリケーションが書き込みを行わなかった転送先頂点バッファ内の要素は、修正されない。アプリケーションが転送先頂点バッファに存在しない要素に書き込みを行うと、IDirect3DDevice8::ProcessVertices は失敗する。


頂点バッファからのレンダリング

頂点バッファから頂点データをレンダリングするには、いくつかのステップが必要である。まず、IDirect3DDevice8::SetStreamSource メソッドを呼び出して、ストリーム ソースを設定する必要がある。次のコードに例を示す。

d3dDevice->SetStreamSource( 0, g_pVB, sizeof(CUSTOMVERTEX) );

SetStreamSource の第 1 パラメータは、Microsoft® Direct3D® にデバイス データ ストリームのソースを知らせる。第 2 パラメータは、データ ストリームにバインドする頂点バッファである。第 3 パラメータは、成分のサイズをバイト単位で指定する。上のサンプル コードでは、CUSTOMVERTEX のサイズが成分のサイズに使用される。

次のステップでは、IDirect3DDevice8::SetVertexShader メソッドを呼び出して、使用する頂点シェーダを Direct3D に知らせる。次のサンプル コードでは、FVF コードを頂点シェーダに設定している。これにより、処理する頂点のタイプを Direct3D に知らせる。

d3dDevice->SetVertexShader( D3DFVF_CUSTOMVERTEX );

ストリーム ソースおよび頂点シェーダを設定した後、描画メソッドで頂点バッファを使用する。次のコードは、IDirect3DDevice8::DrawPrimitive メソッドを使用して、頂点バッファから頂点をレンダリングする方法を示している。

d3dDevice->DrawPrimitive( D3DPT_TRIANGLELIST, 0, 1 );

DrawPrimitive が受け取る第 2 パラメータは、ロードする頂点バッファにある最初のベクトルのインデックスである。


頂点バッファの記述の取得

IDirect3DVertexBuffer8::GetDesc メソッドを呼び出して、頂点バッファに関する情報を取得できる。このメソッドは、頂点バッファに関する情報を D3DVERTEXBUFFER_DESC 構造体のメンバに格納する。


インデックス バッファ

ここでは、Microsoft® Direct3D® アプリケーションにおいてインデックス バッファを理解し、使用するのに必要な概念を説明する。説明するトピックは、次のとおりである。

  • インデックス バッファとは
  • インデックス バッファの記述
  • インデックス バッファのプールと使用
  • デバイスの種類とインデックス処理の要件
  • インデックス バッファの使い方


インデックス バッファとは

インデックス バッファとは、IDirect3DIndexBuffer8 インターフェイスで表される、インデックス データを保持するメモリ バッファである。インデックス データ、つまりインデックスは、頂点バッファへの整数オフセットであり、IDirect3DDevice8::DrawIndexedPrimitive メソッドを呼び出すと、プリミティブをレンダリングするために使用される。


インデックス バッファの記述

インデックス バッファは、能力の点から記述される。インデックス バッファは、システム メモリ内にだけ存在できるのか、書き込み操作だけに使用されるのか、インデックス バッファが含むことができる頂点の種類と数などが記述される。これらの特性はすべて D3DINDEXBUFFER_DESC 構造体に保持される。

インデックス バッファの記述によって、既存バッファが作成された方法がアプリケーションに知らされる。システムが作成済みインデックス バッファの能力を書き込めるように、空白の記述構造体を用意する。このタスクの詳細については、「インデックス バッファの記述の取得」を参照すること。

Format メンバは、インデックス バッファ データのサーフェス フォーマットを記述する。

Type は、インデックス バッファのリソース タイプを識別する。

Usage 構造体のメンバは、一般的な能力フラグを格納する。D3DUSAGE_SOFTWAREPROCESSING フラグは、そのインデックス バッファがソフトウェア頂点処理に使用されることを示す。Usage に D3DUSAGE_WRITEONLY フラグを指定すると、インデックス バッファ メモリは書き込み処理のみに使用される。これによりドライバは解放され、高速処理と高速レンダリングを可能にする最適なメモリ位置にインデックス データが配置される。D3DUSAGE_WRITEONLYフラグが使用されていない場合、ドライバは読み出し処理に効率の悪い位置にデータを配置しなくなる。これにより、処理速度やレンダリング速度が多少犠牲になる。このフラグが指定されていない場合、アプリケーションはインデックス バッファ内のデータで読み書き処理を実行すると見なされる。

Pool は、インデックス バッファに割り当てられるメモリ クラスを指定する。D3DPOOL_SYSTEMMEM フラグは、システムがシステム メモリ内にインデックス バッファを作成したことを示す。

Size メンバは、単に頂点バッファ データのサイズをバイト数で格納する。


インデックス バッファのプールと使用

インデックス バッファは、IDirect3DDevice8::CreateIndexBuffer メソッドで作成する。このメソッドはプール (メモリ クラス) パラメータと使用パラメータを取る。

D3DUSAGE_SOFTWAREPROCESSING フラグは、そのデバイスに対してミックス モードまたはソフトウェア頂点処理 (D3DCREATE_MIXED_VERTEXPROCESSING / D3DCREATE_SOFTWARE_VERTEXPROCESSING) が有効になっているときに設定できる。D3DUSAGE_SOFTWAREPROCESSING は、ミックス モードでのソフトウェア頂点処理に使用するバッファに設定し、ミックス モードでのハードウェア頂点処理 (D3DCREATE_HARDWARE_VERTEXPROCESSING) 時に最高のパフォーマンスを得ようとするときには設定してはならない。ただし、単一のバッファをハードウェアおよびソフトウェア頂点処理の両方に使用する場合は、D3DUSAGE_SOFTWAREPROCESSING を設定することが唯一のオプションである。D3DUSAGE_SOFTWAREPROCESSING は、ミックスおよびソフトウェア デバイスで使用できる。

インデックス処理がハードウェアで実行される場合でも、D3DPOOL_SYSTEMMEM を指定すれば、頂点バッファとインデックス バッファをシステム メモリ内に強制的に配置することができる。これは、ドライバによってこれらのバッファが AGP メモリに入れられたときに、ページ ロックされるメモリが多くなりすぎないようにする方法である。


デバイスの種類とインデックス処理の要件

インデックス処理のパフォーマンスは、インデックス バッファのメモリ内での位置と、使用されるレンダリング デバイスの種類に大きく依存する。インデックス バッファを作成すると、アプリケーションはそのインデックス バッファへのメモリ割り当てを制御する。D3DPOOL_SYSTEMMEM メモリ フラグが設定されているときは、システム メモリ内にインデックス バッファが作成される。D3DPOOL_DEFAULT メモリ フラグを使用すると、インデックス バッファ用のメモリの最良の割り当て場所をデバイス ドライバが決定し、このようにして決定されたメモリのことを多くの場合、ドライバ最適化メモリと呼ぶ。ドライバ最適化メモリとしては、ローカル ビデオ メモリ、非ローカル ビデオ メモリ、またはシステム メモリが指定される。

IDirect3DDevice8::CreateIndexBuffer メソッドを呼び出すときに、D3DUSAGE_SOFTWAREPROCESSING 動作フラグを設定すると、インデックス バッファはソフトウェア頂点処理に使用される。ソフトウェア頂点処理を使用する場合、このフラグはミックス モードの頂点処理 (D3DCREATE_MIXED_VERTEXPROCESSING) で必要となる。

アプリケーションは、ドライバ最適化メモリに割り当てられたインデックス バッファに頂点を直接書き込むことができる。この方法により、以降の冗長なコピー処理を防止する。ただし、ドライバ最適化メモリからホストによって実行される読み取り処理は低速な場合があるため、アプリケーションがインデックス バッファからデータを読み返すときには、この方法はうまく機能しない。したがって、アプリケーションで処理中に読み取り、またはバッファへのデータ書き込みを不規則に実行する必要がある場合は、システム メモリにインデックス バッファを割り当てるとよい。

注 ドライバが頂点バッファまたはインデックス バッファを AGP メモリに配置する場合に、ビデオ メモリまたは大量のページロック RAM を拡張しないときを除いては、常に D3DPOOL_DEFAULT を使用する。


インデックス バッファの使い方

ここでは、インデックス バッファを処理する際にアプリケーションが実行する一般的なタスクについて説明する。説明するトピックは、次のとおりである。

  • インデックス バッファの作成
  • インデックス バッファの内容へのアクセス
  • インデックス バッファからのレンダリング
  • インデックス バッファの記述の取得


インデックス バッファの作成

IDirect3DDevice8::CreateIndexBufferメソッドを呼び出して、インデックス バッファ オブジェクトを作成する。このメソッドは、5 つのパラメータを受け取る。第 1 パラメータは、インデックス バッファの長さをバイト単位で指定する。

第 2 パラメータは、使用コントロール セットである。特に、この値は、インデックスによって参照される頂点がクリッピング情報を格納できるかどうかを指定する。パフォーマンスを向上させるには、クリッピングの必要がないときに D3DUSAGE_DONOTCLIP を指定する。

第 3 パラメータは、各インデックスのサイズを指定する D3DFORMAT 列挙型の D3DFMT_INDEX16 または D3DFMT_INDEX32 メンバのいずれかである。

第 4 パラメータは、新しいインデックス バッファをメモリ内のどの位置に配置するかを指示する D3DPOOL 列挙型のメンバである。

CreateIndexBuffer が受け取る最後のパラメータは、呼び出しが成功したときに頂点バッファ オブジェクトの新しい IDirect3DIndexBuffer8 インターフェイスへのポインタが格納される変数のアドレスである。

次の C++ サンプル コードは、インデックス バッファの作成方法を示している。

/*
* この例では、変数 d3dDevice は
* Direct3DDevice オブジェクトによって公開される IDirect3DDevice8 インターフェイスへのアドレスであり、
 * g_IB は LPDIRECT3DINDEXBUFFER8 型の変数である。

 */

if( FAILED( d3dDevice->CreateIndexBuffer( 16384 *sizeof(WORD),
                                            D3DUSAGE_WRITEONLY, D3DFMT_INDEX16,
                                            D3DPOOL_DEFAULT, &g_IB ) ) )
    return E_FAIL;


インデックス バッファの内容へのアクセス

インデックス バッファ オブジェクトを使用すると、アプリケーションはインデックス データに割り当てられたメモリに直接アクセスできる。IDirect3DIndexBuffer8::Lock メソッドを呼び出してインデックス バッファ メモリへのポインタを取得し、次に、必要に応じてメモリにアクセスして新しいインデックス データをバッファに設定するか、既に設定されているデータを読み出す。Lock メソッドは 4 つのパラメータを受け取る。第 1 パラメータ OffsetToLock は、インデックス データへのオフセットである。第 2 パラメータは、インデックス データのサイズをバイト単位で指定する。第 3 パラメータは、Lock メソッドによって受け取られる。ppbData は、呼び出しが成功した場合に、インデックス データへのポインタが格納される BYTE ポインタのアドレスである。

最後のパラメータ Flags は、メモリのロック方法をシステムに知らせる。このパラメータを使って、バッファ内のデータにアプリケーションがどのようにアクセスするかを示すことができる。アプリケーションがインデックス データにアクセスする方法に応じて、Flags パラメータに定数を指定する。これにより、ドライバはメモリをロックして、要求されているアクセス タイプでの最高のパフォーマンスを提供する。アプリケーションがインデックス バッファ メモリから読み出しのみを行う場合は、D3DLOCK_READONLY フラグを使用する。このフラグを含めると、Microsoft® Direct3D® が内部手順を最適化するので効率が上がる。ただし、メモリへのアクセスは読み出し専用になる。

インデックス データを設定または読み出した後、IDirect3DIndexBuffer8::Unlock メソッドを呼び出す。次のコードに例を示す。

// このサンプル コードでは、IB は LPDIRECT3DINDEXBUFFER8 型の変数であり、
// g_Indices は
// インデックスで正しく初期化されていると仮定している。

// インデックス バッファにデータを格納するには、バッファをロックして
// インデックスへのアクセスを取得する。これは、インデックス バッファがデバイス メモリに存在する
// 可能性があるために必要となるメカニズムである。

VOID* pIndices;

if( FAILED( IB->Lock( 0,                 // バッファの最初からデータを格納する。
                      sizeof(g_Indices), // ロードするデータのサイズ。
                      (BYTE**)&pIndices, // 返されるインデックス データ。
                      0 ) ) )            // デフォルト フラグをロックに送る。
    return E_FAIL;

memcpy( pIndices, g_Indices, sizeof(g_Vertices) );
IB->Unlock();

注 D3DUSAGE_WRITEONLY フラグでインデックス バッファを作成した場合、D3DLOCK_READONLY ロッキング フラグは使用できない。アプリケーションがインデックス バッファ メモリから読み出しのみを行う場合は、D3DLOCK_READONLY フラグを使用する。このフラグを含めると、Direct3D が内部手順を最適化するので効率が上がる。ただし、メモリへのアクセスは読み出し専用になる。

Lock メソッドの Flags パラメータに D3DLOCK_DISCARD または D3DLOCK_NOOVERWRITE を使用する方法の詳細については、「動的な頂点およびインデックス バッファの使い方」を参照すること。

C++ では、インデックス バッファに割り当てられているメモリに直接アクセスするので、アプリケーションが目的のメモリに正しくアクセスするよう注意すること。そうでないと、不正なメモリがレンダリングされるおそれがある。アプリケーションで使用するインデックス フォーマットのストライドを利用して、割り当てられているバッファのインデックスから次のインデックスに移動する。


インデックス バッファからのレンダリング

インデックス バッファのインデックス データをレンダリングするには、いくつかのステップが必要である。まず、IDirect3DDevice8::SetStreamSource メソッドを呼び出して、ストリーム ソースを設定する必要がある。

d3dDevice->SetStreamSource( 0, VB, sizeof(CUSTOMVERTEX) );

SetStreamSource の第 1 パラメータは、Microsoft® Direct3D® にデバイス データ ストリームのソースを知らせる。第 2 パラメータは、データ ストリームにバインドする頂点バッファである。第 3 パラメータは、成分のサイズをバイト単位で指定する。上のサンプル コードでは、CUSTOMVERTEX のサイズが成分のサイズに使用されている。

次のステップでは、IDirect3DDevice8::SetIndices メソッドを呼び出してインデックス データのソースを設定する。

d3dDevice->SetIndices( IB, 0 );

SetIndices が受け取る最初のパラメータは、設定するインデックス バッファのアドレスである。第 2 パラメータは、頂点ストリームの開始点である。

ストリームおよびインデックス ソースを設定した後、IDirect3DDevice8::DrawIndexedPrimitive メソッドを使用して、インデックス バッファからインデックスを使用する頂点をレンダリングする。

d3dDevice->DrawIndexedPrimitive( D3DPT_TRIANGLELIST, 0,
                                   dwVertices, 0, dwIndices / 3);

DrawPrimitive が受け取る第 2 パラメータは、この呼び出しの間に使用される頂点群に対する最小の頂点インデックスである。第 3 パラメータは、この呼び出しで使用されるインデックスの数である (BaseVertexIndex + MinIndex から始まる)。第 4 パラメータは、インデックス配列におけるインデックスの読み出し開始位置である。DrawPrimitive が受け取る最後のパラメータは、レンダリングするプリミティブの個数である。このパラメータは、プリミティブ カウントおよびプリミティブ タイプの関数である。上のコードでは、三角形を使用している。したがって、レンダリングするプリミティブの個数は、3 で割り切れるインデックス数となる。


インデックス バッファの記述の取得

IDirect3DIndexBuffer8::GetDesc メソッドを呼び出して、インデックス バッファに関する情報を取得する。このメソッドは、D3DINDEXBUFFER_DESC 構造体のメンバに頂点バッファに関する情報を設定する。


テクノロジと特殊効果

Microsoft® Direct3D® は、3D シーンをよりリアルに表示するための強力なツール セットを提供する。ここでは、Direct3D で生成できる一般的な特殊効果について説明する。使用できる効果は、ここに掲載するものに限らない。説明するトピックは、次のとおりである。

  • アルファ ブレンディング
  • アンチエイリアシング
  • バンプ マッピング
  • 環境マッピング
  • フォグ
  • ジオメトリ ブレンディング
  • インデックス付き頂点ブレンディング
  • ステンシル バッファ技術
  • 頂点トゥイーニング
  • カラー ライティング


アルファ ブレンディング

アルファ ブレンディングは、透明または半透明ピクセルを含む画像を表示するために使用される。赤、緑、および青のカラー チャネルのほか、アルファ ビットマップ内の各ピクセルには、アルファ チャネルと呼ばれる透明成分がある。アルファ チャネルには、一般的にカラー チャネルと同じ数だけのビットが含まれる。たとえば、8 ビット アルファ チャネルの場合、0 (ピクセル全体が透明) ～ 255 (ピクセル全体が不透明) まで、256 レベルの透明を表現できる。次の一覧は、アルファ ブレンディングを使用して作成できる特殊効果のいくつかを示している。

  • ビルボーディング
  • 雲、煙、蒸気
  • 火、炎、爆発


ビルボーディング

3D シーンを作成するとき、2D オブジェクトを 3D オブジェクトであるかのように表示することによってパフォーマンスを向上できることがある。この考え方が、ビルボード処理技術の基になっている。

通常の意味でのビルボードは、道路沿いの掲示板のことである。Microsoft® Direct3D® アプリケーションでは、矩形ソリッドを定義してテクスチャを適用することで、このようなビルボードを簡単に作成およびレンダリングできる。3D グラフィックスでの特殊な意味でのビルボードは、これを拡張したものである。この意味でのビルボード処理の目的は、2D オブジェクトを 3D オブジェクトのように見せることである。この手法では、オブジェクトのイメージを保持するテクスチャを矩形プリミティブに適用する。このプリミティブは、正面が常にユーザーの方を向くように回転される。このプリミティブは、正面が常にビューアの方を向くように回転される。このオブジェクトの画像は矩形でなくても問題ない。ビルボードの部分を透明にして、表示したくないビルボード画像の部分を不可視にすることができる。

多くのゲームでは、アニメーションしたスプライトにビルボード処理を使用している。たとえば、ユーザーが 3D の迷路を移動するとき、収集できる武器や褒美が表示される。これらは、矩形プリミティブにテクスチャを適用した典型的な 2D 画像である。ビルボード処理は、ゲームで木、潅木、および雲の画像をレンダリングするために使用されることが多い。

ビルボードに画像を適用するときは、最初に、正面がユーザーの方を向くように矩形プリミティブを回転しなければならない。次に、このプリミティブを配置場所に平行移動しなければならない。その後、このプリミティブにテクスチャを適用できる。

ビルボード処理は、対称的なオブジェクト、特に垂直軸に対して対称的なオブジェクトの処理に最適である。また、ビルボード処理には、視点の高さがあまり上がらないことが必要である。ユーザーがビルボードを上から見ることが許されている場合、そのオブジェクトが 3D ではなく 2D であることがすぐにわかってしまう。


雲、煙、蒸気

雲、煙、蒸気のたなびきもすべて、ビルボード処理技術を拡張して作成できる。詳細については、「ビルボーディング」を参照すること。1 つの軸ではなくて 2 つの軸を中心にビルボードを回転することで、ユーザーがビルボードをどの角度からでも見ることができる。通常、アプリケーションでは水平軸と垂直軸を中心にビルボードを回転する。

簡単な雲を作成するには、プリミティブの面がユーザーの方を向くように 1 つまたは 2 つの軸を中心に矩形プリミティブを回転させる。次に、雲のようなテクスチャを透明度と共にこのプリミティブに適用する。透明度のあるテクスチャのプリミティブへの適用の詳細については、「テクスチャ ブレンディング」を参照すること。雲をアニメーションするには、一連のテクスチャを時間の経過につれて適用する。

プリミティブのグループで雲を作れば、さらに複雑な雲を作成できる。この場合、雲の各部分が矩形プリミティブになる。これらのプリミティブをそれぞれ独立して連続的に移動して、動的な霧のように見せることができる。次の図にこれを示す。

煙は、雲と同様の方法で表示する。通常、煙では複雑な雲のように複数のビルボードが必要である。煙は時間と共にうねったり上昇するので、立ち昇る煙を形成するビルボードを移動させる必要がある。煙が上昇したり消散するときは、ビルボードの追加が必要な場合もある。

蒸気のたなびきは、上昇しない煙のようなものである。ただし、蒸気は煙のように徐々に消散する。次の図は、蒸気のたなびきをシミュレートするためにビルボードを使用する技術を示している。


火、炎、爆発

Microsoft® Direct3D® を使用して、エネルギーを発する自然現象をシミュレーションできる。たとえば、炎のようなテクスチャをビルボード セットに適用して、火を表現できる。これが特に効果的なのは、火のテクスチャを連続的に使用して、燃えるビルボードそれぞれの上の炎をアニメーションする場合である。ビルボードごとにアニメーション再生の速度を変えると、炎のリアリティが増す。混じり合った 3D の炎に見せるには、ビルボードを重ね合わせ、ビルボード上のテクスチャを重ね合わせればよい。

炎や閃光は、シーン内のすべてのプリミティブに対して、徐々に明るくなるライト マップを適用することでシミュレーションできる。これはオーバーヘッドの高い技術であるが、局所的な炎や閃光のシミュレーションは可能である。つまり、炎や閃光を発するシーンを最初に明るくすることができる。

ほかの技術としては、レンダリング ターゲット領域全体を覆うようにシーンの前面にビルボードを配置する方法がある。アプリケーションで、連続的に白くなるテクスチャをビルボードに適用し、徐々に透明度を減少させる。時間と共にシーン全体が白くなる。これは、炎を作成する方法としてはオーバーヘッドの低い方法である。しかし、この技術を使用すると、単一のポイント ライトの光源から明るい閃光を表現することが困難になることがある。

爆発は、火、閃光、および炎で使用したような 3D シーンの作成方法によって表示できる。たとえば、アプリケーションでビルボードを使用して、爆発の衝撃波や噴煙を表示できる。同時に、ビルボード セットを使用して炎をシミュレートできる。さらに、シーンの前面に単一のビルボードを配置して、シーン全体に閃光を追加できる。

エネルギー ビームは、ビルボードを使用してシミュレーションできる。また、線リストまたは線ストリップとして定義したプリミティブを使用してもこのビームを表示できる。詳細については、「線リスト」および「線ストリップ」を参照すること。

ビルボードや三角形リストとして定義したプリミティブを使用して、電磁力界を作成できる。三角形リストから電磁力界を作成するには、電磁力界の範囲と同じ空間を占める三角形リストにある分離した三角形のセットを定義すること。ユーザーは、三角形どうしの隙間から三角形の背後のシーンを見ることができ、あたかも電磁力界を見ているかのように感じられる。三角形がエネルギーで輝いているように見せるテクスチャを三角形リストに適用する。詳細については、「三角形リスト」を参照すること。


アンチエイリアシング

アンチエイリアシングとは、正確に水平または垂直でない線を描いたときに現れる階段状のピクセルを減らすための技法である。3 次元シーンの場合、この不自然な効果は異なる色のポリゴン間の境界線上でもっとも目立つ。アンチエイリアシングは、ピクセルを効果的に境界線上でブレンドして、シーンの外観をより自然にする。

Microsoft® Direct3D® がサポートするアンチエイリアシングの方法には、エッジ アンチエイリアシングおよびフルシーン アンチエイリアシングの 2 種類がある。どちらのアンチエイリアシングがアプリケーションによいかは、パフォーマンスと視覚的品質の要件に依存する。

  • エッジ アンチエイリアシング
  • フルシーン アンチエイリアシング

次のトピックでは、特殊効果を使ってシミュレートする方法またはアンチエイリアシングの使用方法について説明する。

  • モーション ブラー


エッジ アンチエイリアシング

エッジ アンチエイリアシングでは、シーンをレンダリングした後、オブジェクトの凸状シルエットを再レンダリングして、線にアンチエイリアシングする。システムは辺を再描画し、ぼかして、不自然な効果を減らす。

まず、IDirect3DDevice8::GetDeviceCaps メソッドを呼び出して、Microsoft® Direct3D® デバイスがアンチエイリアシングをサポートしているかどうかを調べる。デバイスがエッジ アンチエイリアシングをサポートしている場合は、GetDeviceCaps が D3DCAPS8 構造体の D3DPRASTERCAPS_ANTIALIASEDGES 能力フラグを TRUE に設定する。

デバイスがアンチエイリアシングをサポートしている場合は、D3DRS_EDGEANTIALIAS レンダリング ステートを TRUE に設定する。次のコードに例を示す。

d3dDevice->SetRenderState( D3DRS_EDGEANTIALIAS, TRUE );

次に、IDirect3DDevice8::DrawPrimitive、および D3DPT_LINESTRIP または D3DPT_LINELIST プリミティブ タイプのいずれかを使用して、シーン内のエッジのみ再描画する。エッジ アンチエイリアシングの動作は、線以外のプリミティブについては定義されていないため、アンチエイリアシングが完了したら、D3DRS_EDGEANTIALIAS を FALSE に設定して機能を確実に無効にする。

シーンの中のすべてのエッジを再描画すると、大きな不自然な効果を生じさせずに済むが、計算量が膨大になる。また、この方法ではどのエッジをアンチエイリアシングするべきか判断が困難なこともある。再描画するのにもっとも重要なエッジは、非常に異なる色の領域の間のエッジ (たとえば影のエッジ)、または非常に異なるマテリアルの間の境界である。ほぼ同じ色の 2 つのポリゴンの間のエッジをアンチエイリアシングすることに意味はないが、計算量は膨大である。このような理由により、現在のハードウェアがフルシーン アンチエイリアシングをサポートしているのであれば、これが好ましいことが多い。詳細については、「フルシーン アンチエイリアシング」を参照すること。


フルシーン アンチエイリアシング

フルシーン アンチエイリアシングとは、シーン内の各ポリゴンのエッジをシングル パスでラスタライズしてぼかすことを指す。2 つ目のパスは必要ない。フルシーン アンチエイリアシングは、サポートされている場合は三角形および三角形のグループにのみ影響する。Microsoft® Direct3D® サービスを使用して線にアンチエイリアシングを適用することはできない。Direct3D では、フルシーン アンチエイリアシングを実行するには、各ピクセルにマルチサンプリングを使用する。マルチサンプリングが有効な場合、ピクセルのすべてのサブサンプルが 1 つのパスで更新されるが、複数のレンダリング パスを含むほかのエフェクトに使用される場合は、アプリケーションでサブサンプルの一部だけが指定のレンダリング パスに影響を受けるよう指定できる。この後者のアプローチによって、モーション ブラー、フィールド フォーカス エフェクトの深度、反射ブラーなどをシミュレートすることができる。

どちらの場合も、ピクセルごとに記録されたさまざまなサンプルがブレンドされ、スクリーンに出力される。このようなアプローチを使用すると、アンチエイリアシングやほかのエフェクトのイメージ品質が向上する。

IDirect3D8::CreateDevice でデバイスを作成する前に、フルシーン アンチエイリアシングがサポートされているかどうかを調べる必要がある。調べるには、IDirect3D8::CheckDeviceMultiSampleType メソッドを呼び出す。次のコードに例を示す。

/*
* このコードでは、pD3D は IDirect3D8 インターフェイスへの
* 有効なポインタであると仮定している。
 */

if( SUCCEEDED(pD3D->CheckDeviceMultiSampleType( D3DADAPTER_DEFAULT,
                                                D3DDEVTYPE_HAL , D3DFMT_R8G8B8,
                                                FALSE, D3DMULTISAMPLE_2_SAMPLES ) ) )
    // フルシーン アンチエイリアシングがサポートされている。ここで有効にする。

CheckDeviceMultiSampleType が受け取る第 1 パラメータは、問い合わせるディスプレイ アダプタを示す序数である。この例では、D3DADAPTER_DEFAULT を使用してプライマリ ディスプレイ アダプタを指定する。第 2 パラメータは D3DDEVTYPE 列挙型の値で、デバイスの種類を指定する。第 3 パラメータには、サーフェスのフォーマットを指定する。第 4 パラメータは、フルウィンドウ マルチサンプリング (TRUE) またはフルスクリーン アンチエイリアシング (FALSE) を問い合わせるかどうかを Direct3D に知らせる。この例では FALSE を使用して、フルシーン アンチエイリアシングについて問い合わせることを Direct3D に指示している。最後のパラメータには、テストするマルチサンプリング テクニックを指定する。D3DMULTISAMPLE_TYPE 列挙型の値を使用する。この例では、2 つのレベルのマルチサンプリングがサポートされているかどうかをテストする。

デバイスが使用したい 2 つのレベルのマルチサンプリングをサポートしている場合、次の手順は、マルチサンプルのレンダリング サーフェスを作成するために、D3DPRESENT_PARAMETERS 構造体の適切なメンバにデータを設定して、プレゼンテーション パラメータを設定することである。設定した後は、デバイスを作成することができる。次のサンプル コードは、マルチサンプリングのレンダリング サーフェスでデバイスを設定する方法を示している。

/*
* この例では、pD3D は IDirect3D8 インターフェイスへの有効なポインタであり、
 * d3dDevice は IDirect3DDevice8 インターフェイスへのポインタ、
* hWnd はウィンドウへの
* 有効なハンドルであると仮定している。
 */

D3DPRESENT_PARAMETER d3dPP
ZeroMemory( &d3dPP, sizeof( d3dPP ) );
d3dPP.Windowed        = FALSE
d3dPP.SwapEffect      = D3DSWAPEFFECT_DISCARD;
d3dPP.MultiSampleType = D3DMULTISAMPLE_2_SAMPLES;
pD3D->CreateDevice(D3DADAPTER_DEFAULT, D3DDEVTYPE_HAL, hWnd,
                   D3DCREATE_SOFTWARE_VERTEXPROCESSING,
                   &d3dpp, &d3dDevice)

注 マルチサンプリングを使用するには、D3DPRESENT_PARAMETER の SwapEffect メンバを D3DSWAPEFFECT_DISCARD に設定する必要がある。

最後の手順は、IDirect3DDevice8::SetRenderState メソッドを呼び出して D3DRS_MULTISAMPLEANTIALIAS を TRUE に設定することによって、マルチサンプリングのアンチエイリアシングを有効にすることである。この値に TRUE を設定した後は、レンダリングには必ずマルチサンプリングが適用される。レンダリング対象に応じて、マルチサンプリングの有効/無効を切り替えることもできる。


モーション ブラー

3D シーンのオブジェクトの知覚速度は、オブジェクトをぼかし、オブジェクトの背後にオブジェクト画像のぼんやりとした跡を残すことで高めることができる。Microsoft® Direct3D® アプリケーションは、フレームごとにオブジェクトを複数回レンダリングして、これを実現する。

通常、Direct3D アプリケーションはシーンをオフスクリーン バッファにレンダリングすることを思い出してほしい。バッファの内容は、アプリケーションでIDirect3DDevice8::Present メソッドを呼び出したときにスクリーンに表示される。Direct3D アプリケーションは、スクリーンにフレームを表示する前にオブジェクトをシーンに複数回レンダリングできる。

アプリケーションで DrawPrimitive メソッドへの呼び出しを複数回行い、同じ 3D オブジェクトを繰り返し渡す。それぞれの呼び出しの前に、オブジェクトの位置座標を少し更新し、ターゲット レンダリング サーフェス上に一連の不鮮明なオブジェクト画像を生成する。オブジェクトが 1 つまたは複数のテクスチャを持っている場合、テクスチャすべてをほとんど透明にしてオブジェクトの最初の画像をレンダリングすると、モーション ブラー エフェクトを高めることができる。オブジェクトをレンダリングするたびに、オブジェクトのテクスチャの透明度が減少する。最終位置座標でオブジェクトをレンダリングするときは、透明度なしでオブジェクトをレンダリングすること。例外は、テクスチャの透明度を必要とするほかのエフェクトにモーション ブラーを追加する場合である。どの場合でも、フレームのオブジェクトの最初の画像が最も透明でなければならない。最後の画像の透明度が最も低くなければならない。

ターゲット レンダリング サーフェスに一連のオブジェクト画像をレンダリングし、残りのシーンもレンダリングしたら、Present メソッドを呼び出してスクリーンにフレームを表示する。

ユーザーがシーンを高速で移動するエフェクトをシミュレーションする場合は、スクリーン全体にモーション ブラーを追加できる。この場合、アプリケーションは、フレームごとにシーン全体を複数回レンダリングする。シーンをレンダリングするたびに、視点を少し移動しなければならない。シーンが非常に複雑な場合、フレームごとのシーンのレンダリング回数が増えるので、高速に移動するシーンほどパフォーマンスが低下するのがユーザーにわかる。


バンプ マッピング

ここでは、Microsoft® Direct3D® で実行するバンプ マッピングについて説明する。以下のトピックでは、バンプ マッピングを紹介し、その主要な概念を特定および定義し、アプリケーションでのバンプ マッピングの使用方法について説明する。

  • バンプ マッピングとは
  • バンプ マップ ピクセル フォーマット
  • バンプ マッピングの公式
  • バンプ マッピングの使い方


バンプ マッピングとは

バンプ マッピングは、少数のポリゴンだけできれいにテッセレーションされたオブジェクトの反射状態をシミュレートする、特殊なスペキュラまたはディフューズ環境マッピングである。次の画像は、BumpEarth サンプルに基づいてバンプ マッピングのエフェクトを示している。

左側の地球は、地球の表面の画像でテクスチャ処理され、スペキュラ環境マップが適用されている。右側の地球もまったく同じであるが、バンプ マップが適用されている。2 つ目の地球の画像のポリゴン数は、1 つ目の画像のポリゴン数と変わらない。

Microsoft® Direct3D® のバンプ マッピングでは、開発者はデルタ値による輪郭線の情報を提供することから、バンプ マッピングは、正確にはスペキュラまたはディフューズ環境マップのピクセル単位のテクスチャ座標の補正と記述できる。輪郭線の情報は、システムによって次のテクスチャ ステージの環境マップの u および v テクスチャ座標に適用される。デルタ値は、バンプ マップ サーフェスのピクセル フォーマットで符号化される。詳細については、「バンプ マップ ピクセル フォーマット」を参照すること。

BumpEarth サンプルでは、高度マップを使用して輪郭線データを格納する。サンプルを開始すると、高度マップ内のピクセルが処理されて適切な u および v が計算される。これは、隣接する 4 つのピクセルを基準にした、各ピクセルの相対高度に基づく。

本来、Direct3D では高度マップをサポートしていない。高度マップは、輪郭線データを格納および視覚化するのに便利なフォーマットであるにすぎない。前の画像は高度マップに基づいて作成されたもので、BumpEarth サンプルではこの高度マップを使用して、Direct3D に提供するバンプ マップを生成している。この画像は説明を目的に示したものである。アプリケーションでは輪郭線情報をどのようなフォーマットでも格納でき、また、BumpWaves サンプルのように個々のバンプ マップを生成することもできる。

次は、BumpEarth サンプルで使用する高度マップ画像である。このサンプルでは、これを使用して、バンプ マップ テクスチャのピクセル フォーマットでエンコードされるデルタ値を計算する。

バンプ マッピングは、複数のテクスチャ ブレンディング サービスに完全に依存しており、デバイスは少なくとも 2 つのブレンディング ステージ (1 つはバンプ マップ用、もう 1 つは環境マップ用) をサポートしている必要がある。ベース テクスチャ マップを適用するには、最も一般的な場合、最低 3 つのテクスチャ ブレンディング ステージが要求される。次の図は、テクスチャ ブレンディング カスケードにおける、ベース テクスチャ、バンプ マップ、および環境マップ間の関係を示している。

テクスチャ ステージを適切に用意し、バンプ マッピングを有効にする必要がある。このタスクについては、「バンプ マッピング パラメータの設定」で説明する。


バンプ マップ ピクセル フォーマット

バンプ マップとは、特殊なピクセル フォーマットを使用する IDirect3DTexture8 オブジェクトである。赤、緑、および青の色成分を格納するのではなく、バンプ マップの各ピクセルは、u および v のデルタ値 (Du および Dv) を格納し、輝度 L. を格納するときもある。これらの値は、「バンプ マッピングの公式」で説明するように、システムによって適用される。

バンプ マップ ピクセル フォーマットを指定するには、D3DFORMAT 列挙型を以下のバンプ マップ ピクセル フォーマットのいずれかに設定する。

フォーマット | 説明
D3DFMT_V8U8 | 16 ビットのバンプマップ フォーマット。
D3DFMT_L6V5U5 | 輝度付きの 16 ビット バンプマップ フォーマット。
D3DFMT_X8L8V8U8 | 輝度付きの 32 ビット バンプマップ フォーマットで、8 ビットは各要素のために確保されている。
D3DFMT_Q8W8V8U8 | 32 ビットのバンプマップ フォーマット。
D3DFMT_V16U16 | 32 ビットのバンプマップ フォーマット。
D3DFMT_W11V11U10 | 32 ビットのバンプマップ フォーマット。

ピクセルの Du および Dv コンポーネントは、-1.0 ～ +1.0 の範囲の符号付きの値である。輝度コンポーネントが使用されている場合、この値は 0 ～ 255 の範囲の符号なし整数値である。

注 バンプ マップ ピクセル フォーマットを選択する前に、特定のフォーマットがサポートされているかどうかを調べる必要がある。詳細については、「バンプ マッピングのサポートの検出」を参照すること。


バンプ マッピングの公式

Microsoft® Direct3D® では、各バンプ マップ ピクセルの Du および Dv コンポーネントに次の公式を適用する。

この公式では、変数 Du および Dv はバンプ マップ ピクセルから直接取得され、出力デルタ値 Du' および Dv' を生成するために 2 × 2 行列でトランスフォームされる。システムでは、この出力値を使用して、次のテクスチャ ステージの環境マップを処理するテクスチャ座標を修正する。トランスフォーム行列の係数は、D3DTSS_BUMPENVMAT00、D3DTSS_BUMPENVMAT10、D3DTSS_BUMPENVMAT01、および D3DTSS_BUMPENVMAT11 テクスチャ ステージ ステートで設定する。

u および v デルタ値のほかにも、システムでは、次のブレンディング ステージの環境マップの色の乗算に使用する輝度を計算できる。

この公式では、L' は計算される出力輝度である。変数 L はバンプ マップ ピクセルから取得される輝度値であり、スケーリング係数 S で乗算され、変数 O の値でオフセットされる。D3DTSS_BUMPENVLSCALE および D3DTSS_BUMPENVLOFFSET テクスチャ ステージ ステートは、公式の変数 S および O の値を制御する。この公式が適用されるのは、バンプ マップを含むステージのテクスチャ ブレンディング処理が D3DTOP_BUMPENVMAPLUMINANCE に設定されている場合のみである。D3DTOP_BUMPENVMAP を使用するときは、L' の値に 1.0 が使用される。

出力デルタ値 Du' および Dv' の計算後、システムでは、これらの値を次のテクスチャ ステージのテクスチャ座標に追加し、選択されている色の輝度を乗算して、ポリゴンに適用する色を生成する。


バンプ マッピングの使い方

ここでは、Microsoft® Direct3D® のバンプ マッピングを使用する際に、アプリケーションで実行する最も一般的なタスクについて説明する。説明するトピックは、次のとおりである。

  • バンプ マッピングのサポートの検出
  • バンプ マップ テクスチャの作成
  • バンプ マッピング パラメータの設定


バンプ マッピングのサポートの検出

Microsoft® Direct3D® デバイスが D3DTOP_BUMPENVMAP または D3DTOP_BUMPENVMAPLUMINANCE のいずれかのテクスチャ ブレンディング処理をサポートしている場合、そのデバイスではバンプ マッピングを実行できる。また、アプリケーションではデバイス能力を調べることで、そのアプリケーションで適切なブレンディング ステージ数 (通常は 3 つ以上) がサポートされ、少なくとも 1 つのバンプ マッピング ピクセル フォーマットが公開されていることを確認する必要がある。

次のコードは、指定された条件によってデバイス機能を調べて、現在のデバイスでのバンプ マッピングのサポートを検出する。

BOOL SupportsBumpMapping()
{
    D3DCAPS8 d3dCaps;

    d3dDevice->GetDeviceCaps( &d3dCaps );

    // このデバイスが 2 つのバンプ マッピング ブレンド処理をサポートしているかどうか。
    if ( 0 == d3dCaps.TextureOpCaps & ( D3DTEXOPCAPS_BUMPENVMAP |
                                         D3DTEXOPCAPS_BUMPENVMAPLUMINANCE ))
        return FALSE;

    // このデバイスが最大 3 つのブレンディング ステージをサポートしているかどうか。
    if( d3dCaps.MaxTextureBlendStages < 3 )
        return FALSE;
}


バンプ マップ テクスチャの作成

ほかのテクスチャの場合と同様に、バンプ マップ テクスチャを作成する。アプリケーションでバンプ マッピングのサポートを確認し、有効なピクセル フォーマットを取得したら (「バンプ マッピングのサポートの検出」で説明するように)、バンプ マップ テクスチャ サーフェスを作成できる。テクスチャの作成については、「テクスチャ サーフェス オブジェクトの取得」を参照すること。

サーフェスの作成後は、適切なデルタ値を持つ各ピクセルと、輝度 (サーフェス フォーマットに輝度が含まれる場合) をロードできる。各ピクセル コンポーネントの値については、「バンプ マップ ピクセル フォーマット」で説明する。


バンプ マッピング パラメータの設定

アプリケーションでバンプ マップの作成と各ピクセルの内容の設定が完了したら、バンプ マッピング パラメータを設定してレンダリングの準備を行うことができる。バンプ マッピング パラメータには、必要なテクスチャとそのブレンディング処理や、バンプ マップ自体に対するトランスフォームと輝度の制御などを設定する。

C++ でバンプ マッピング パラメータを設定するには

  1. ベース テクスチャ マップ (使用されている場合)、バンプ マップ、および環境マップ テクスチャをテクスチャ ブレンディング ステージに設定する。
  2. 各テクスチャ ステージの色およびアルファ ブレンディング処理を設定する。
  3. バンプ マップ トランスフォーム行列を設定する。
  4. 必要に応じて、輝度スケール値およびオフセット値を設定する。

次のコードでは、ベース テクスチャ マップ、バンプ マップ、およびスペキュラ環境マップの 3 つのテクスチャを、適切なテクスチャ ブレンディング ステージに設定する。

    // 3 つのテクスチャを設定する。
    d3dDevice->SetTexture( 0, d3dBaseTexture );
    d3dDevice->SetTexture( 1, d3dBumpMap );
    d3dDevice->SetTexture( 2, d3dEnvMap );

テクスチャをブレンディング ステージに設定した後、次のコードで、各ステージのブレンディング処理および引数を準備する。

    // カラー処理および引数を設定してバンプ マッピング
    // を準備する。

    // ステージ 0:ベース テクスチャ。
    d3dDevice->SetTextureStageState( 0, D3DTSS_COLOROP, D3DTOP_MODULATE );
    d3dDevice->SetTextureStageState( 0, D3DTSS_COLORARG1, D3DTA_TEXTURE );
    d3dDevice->SetTextureStageState( 0, D3DTSS_COLORARG2, D3DTA_DIFFUSE );
    d3dDevice->SetTextureStageState( 0, D3DTSS_ALPHAOP, D3DTOP_SELECTARG1 );
    d3dDevice->SetTextureStageState( 0, D3DTSS_ALPHAARG1, D3DTA_TEXTURE );
    d3dDevice->SetTextureStageState( 0, D3DTSS_TEXCOORDINDEX, 1 );

    // ステージ 1:バンプ マップ - この例では輝度を使用する。
    d3dDevice->SetTextureStageState( 1, D3DTSS_TEXCOORDINDEX, 1 );
    d3dDevice->SetTextureStageState( 1, D3DTSS_COLOROP, D3DTOP_BUMPENVMAPLUMINANCE);
    d3dDevice->SetTextureStageState( 1, D3DTSS_COLORARG1, D3DTA_TEXTURE );
    d3dDevice->SetTextureStageState( 1, D3DTSS_COLORARG2, D3DTA_CURRENT );

    // ステージ 2:スペキュラ環境マップ。
    d3dDevice->SetTextureStageState( 2, D3DTSS_TEXCOORDINDEX, 0 );
    d3dDevice->SetTextureStageState( 2, D3DTSS_COLOROP, D3DTOP_ADD );
    d3dDevice->SetTextureStageState( 2, D3DTSS_COLORARG1, D3DTA_TEXTURE );
    d3dDevice->SetTextureStageState( 2, D3DTSS_COLORARG2, D3DTA_CURRENT );

ブレンディング処理および引数を設定した後、次のコードで、D3DTSS_BUMPENVMAT00 および D3DTSS_BUMPENVMAT11 テクスチャ ステージ ステートを 1.0 に設定して、2×2 バンプ マッピング行列を単位行列に設定する。行列を単位行列に設定すると、システムでは未修正のバンプ マップのデルタ値が使用されるようになるが、これは必ずしも必要ではない。

    // バンプ マッピング行列を設定する。
    //
    // 注
    //    これらの呼び出しは、以下のインライン ショートカット関数に依存する。
    //       inline DWORD F2DW( FLOAT f ) { return *((DWORD*)&f); }
    d3dDevice->SetTextureStageState( 1, D3DTSS_BUMPENVMAT00, F2DW(1.0f) );
    d3dDevice->SetTextureStageState( 1, D3DTSS_BUMPENVMAT01, F2DW(0.0f) );
    d3dDevice->SetTextureStageState( 1, D3DTSS_BUMPENVMAT10, F2DW(0.0f) );
    d3dDevice->SetTextureStageState( 1, D3DTSS_BUMPENVMAT11, F2DW(1.0f) );

バンプ マッピング処理に輝度 (D3DTOP_BUMPENVMAPLUMINANCE) を含める場合は、輝度制御を設定する必要がある。輝度制御により、次のステージのテクスチャから色を調整する前にシステムが行う輝度の計算方法を設定する。詳細については、「バンプ マッピングの公式」を参照すること。

    // 輝度制御を設定する。この設定が必要となるのは、
    // 輝度を含むバンプ マップを使用する場合、および
    // D3DTOP_BUMPENVMAPLUMINANCE テクスチャ ブレンディング処理が使用される場合だけである。
    //
    //
    // 注
    //    これらの呼び出しは、以下のインライン ショートカット関数に依存する。
    //       inline DWORD F2DW( FLOAT f ) { return *((DWORD*)&f); }
    d3dDevice->SetTextureStageState( 1, D3DTSS_BUMPENVLSCALE, F2DW(0.5f) );
    d3dDevice->SetTextureStageState( 1, D3DTSS_BUMPENVLOFFSET, F2DW(0.0f) );

アプリケーションでバンプ マッピング パラメータを設定した後は、通常どおりにレンダリングを実行でき、レンダリングされるポリゴンにバンプ マッピング エフェクトが適用される。

注 この例では、パラメータはスペキュラ環境マッピング用に設定されている。ディフューズ ライト マッピングを行う場合は、最後のステージのテクスチャ ブレンディング処理を D3DTOP_MODULATE に設定する。詳細については、「ディフューズ ライト マップ」を参照すること。


環境マッピング

ここでは、Microsoft® Direct3D® の一般的な 2 種類の環境マッピングの実行について説明する。グラフィックス業界では多種多様な環境マッピングが使用されているが、以下のトピックでは、最も一般的なキューブ環境マップおよび球状環境マッピングについて説明する。

  • 環境マッピングとは
  • キューブ環境マップ
  • 球状環境マッピング


環境マッピングとは

環境マッピングとは、反射性の高いサーフェスをレイ トレーシングを使用せずにシミュレートする方法である。実際、環境マッピングでは、オブジェクトの周囲の景色を含む特殊なテクスチャ マップがそのオブジェクト自体に適用される。その結果、反射性を持つサーフェスには、十分に人の目をごまかせる程度に周囲の景色が映り込む。レイ トレーシングを実行した場合に生じる計算負荷も発生しない。

次の画像は、SphereMap サンプルのものである。名前からわかるように、このサンプルでは球状環境マッピングと呼ばれる環境マッピングを使用している。詳細については、「球状環境マッピング」を参照すること。

このティーポットは周囲の景色を反射しているように見えるが、実際にはテクスチャが適用されている。環境マッピングは、テクスチャ (特殊な計算で求めたテクスチャ座標を組み合わせたもの) を使用するため瞬時に実行される。


キューブ環境マップ

キューブ環境マップでは、オブジェクトの周囲の空間またはライティングのエフェクトがそのオブジェクトの表面に沿って適用される。これは立方体の内部の 6 つの面によって表現される。説明するトピックは、次のとおりである。

  • キューブ環境マップとは
  • キューブ環境マップ サーフェスの作成
  • キューブ環境マップ サーフェスへのアクセス
  • キューブ環境マップのミップマップ化
  • キューブ環境マップへのレンダリング
  • キューブ環境マップのテクスチャ座標


キューブ環境マップとは

キューブ環境マップ (キューブ マップとも呼ばれる) とは、オブジェクトの周囲のシーンをオブジェクトが立方体の中心にあるかのように表現した画像データを含むテクスチャである。キューブ環境マップの各面は、水平方向と垂直方向の 90°の視野を対象とし、1 つのキューブ マップには 6 つの面がある。各面の向きは、次の図に示すとおりである。

立方体の各面は、ワールド空間の x/y、y/z、または x/z 平面に垂直に位置座標する。次の図は、各平面と面の対応を示している。

キューブ環境マップは、一連のテクスチャ オブジェクトとして実装される。アプリケーションでは、キューブ環境マップに静的な画像を使用したり、キューブ マップの面にレンダリングを行うことで動的な環境マッピングを実行することができる。この場合、キューブ マップ サーフェスは有効なレンダリング ターゲット サーフェスでなければならず、D3DUSAGE_RENDERTARGET フラグ セットで作成されている必要がある。

キューブ マップの各面には、周囲のシーンが緻密にレンダリングされる必要はない。ほとんどの場合、環境マップは湾曲サーフェスに適用される。大部分のアプリケーションで使用する湾曲の度合いが与えられたとすると、結果としてひずんだ画像が生成されるため、環境マップの緻密さはメモリの点からもレンダリングのオーバーヘッドの点からも無駄になる。


キューブ環境マップ サーフェスの作成

キューブ環境マップ テクスチャを作成するには、IDirect3DDevice8::CreateCubeTexture メソッドを呼び出す。キューブ環境マップ テクスチャは矩形でなければならず、その大きさは 2 の累乗である。

次のコードは、C++ アプリケーションで単純なキューブ環境マップを作成する方法を示している。

/*
** この例では、m_d3dDevice は IDirect3DDevice8 インターフェイスへの
* 有効なポインタであると仮定している。
 */

LPDIRECT3DCUBETEXTURE8 m_pCubeMap;

m_d3dDevice->CreateCubeTexture( 256, 1, D3DUSAGE_RENDERTARGET, D3DFMT_R8G8B8,
                                D3DPOOL_MANAGED, &m_pCubeMap );


キューブ環境マップ サーフェスへのアクセス

IDirect3DCubeTexture8::GetCubeMapSurface メソッドを使用してキューブ環境マップのサーフェスからサーフェスに移動できる。

次のコードは、GetCubeMapSurface を使用して、正方向の y 面 (サーフェス 2) のキューブ マップ サーフェスを取得する。

/*
* この例では、m_pCubeMap は IDirect3DCubeTexture8 インターフェイスへの
* 有効なポインタである。
 */
LPDIRECT3DSURFACE8 pFace2;

m_pCubeMap->GetCubeMapSurface( D3DCUBEMAP_FACE_POSITIVE_Y, 0, &pFace2);

GetAttachedSurface が受け取る第 1 パラメータは、このメソッドで取得する必要があるアタッチされたサーフェスを記述する D3DCUBEMAP_FACES 列挙型である。第 2 パラメータは、取得するミップマップ化キューブ テクスチャのレベルを Microsoft® Direct3D® に指示する。第 3 パラメータは、返されるキューブ テクスチャ サーフェスを表す IDirect3DSurface8 インターフェイスのアドレスである。この場合、このキューブ マップはミップマップ化されていないので、0 が使用される。

注 このメソッドを呼び出した後は、IDirect3DSurface8 インターフェイスの内部参照カウントが増える。このサーフェスを使用した後は、必ず IDirect3DSurface8 インターフェイスに対して IUnknown::Release メソッドを呼び出すこと。呼び出さないと、メモリ リークとなる。


キューブ環境マップのミップマップ化

キューブ環境マップはミップマップ化できる。DDSCAPS_MIPMAP 能力を含めると、アタッチされたミップマップ サーフェスのある各サーフェスが作成される。これらのサーフェスの形状は、次の図に示すようになる。

ミップマップ化キューブ環境マップを作成するアプリケーションで各サーフェスにアクセスするには、IDirect3DCubeTexture8::GetCubeMapSurface メソッドを呼び出す。D3DCUBEMAP_FACES 列挙型から適切な値を設定して開始する。これについては、「キューブ環境マップ サーフェスへのアクセス」で説明する。次に、Level パラメータを目的のミップマップ レベルに設定して、取得するレベルを選択する。0 は最上位画像に対応することを思い出すこと。


キューブ環境マップへのレンダリング

キューブ マップの個々のサーフェスへは、その他のテクスチャやサーフェス オブジェクトと同じように画像をコピーすることができる。このレンダリングを行う前に実行する最も大切なことは、カメラを正しく配置し、そのサーフェスに対して正しい方向を向くようにトランスフォーム行列を設定することである。正しい方向とは、前方 (+z)、後方 (-z)、左 (-x)、右 (+x)、上方 (+y)、または下方 (-y) である。

次の C++ コードは、レンダリングするサーフェスに応じてビュー行列を用意して設定する。

/*
* この例では、pCubeMap は IDirect3DCubeTexture8 インターフェイスへの有効なポインタであり、
* d3dDevice は IDirect3DDevice8 インターフェイスへの
* 有効なポインタである。
 */
void RenderFaces()
{
    // デバイスのトランスフォーム行列を保存する。
    D3DXMATRIX matProjSave, matViewSave;
    d3dDevice->GetTransform( D3DTS_VIEW,       &matViewSave );
    d3dDevice->GetTransform( D3DTS_PROJECTION, &matProjSave );

    // 現在のバック バッファと z バッファを格納する。
    LPDIRECT3DSURFACE8 pBackBuffer, pZBuffer;
    d3dDevice->GetRenderTarget( &pBackBuffer );
    d3dDevice->GetDepthStencilSurface( &pZBuffer );

キューブ環境マップの各サーフェスには 90°の視野が含まれることを思い出すこと。アプリケーションで特殊効果などのために視野の角度を変更しない限り、この角度に応じて射影行列を設定するよう注意が必要である。

次のコードは、最も一般的に使用する射影行列を作成および設定する。

    // 90°の視野を射影に使用する。
    D3DMATRIX matProj;
    D3DXMatrixPerspectiveFovLH( matProj, D3DX_PI/2, 1.0f, 0.5f, 1000.0f );
    d3dDevice->SetTransform( D3DTS_PROJECTION, &matProj );

    // キューブ マップの 6 つのサーフェスに対してループ処理を実行する。
    for( DWORD i=0; i<6; i++ )
    {
        // 以下のように、標準ビューをオーバーライドする。
        D3DVECTOR vEnvEyePt = D3DVECTOR( 0.0f, 0.0f, 0.0f );
        D3DVECTOR vLookatPt, vUpVec;

        switch( i )
        {
            case D3DCUBEMAP_FACE_POSITIVE_X:
                vLookatPt = D3DVECTOR( 1.0f, 0.0f, 0.0f );
                vUpVec    = D3DVECTOR( 0.0f, 1.0f, 0.0f );
                break;
            case D3DCUBEMAP_FACE_NEGATIVE_X:
                vLookatPt = D3DVECTOR(-1.0f, 0.0f, 0.0f );
                vUpVec    = D3DVECTOR( 0.0f, 1.0f, 0.0f );
                break;
            case D3DCUBEMAP_FACE_POSITIVE_Y:
                vLookatPt = D3DVECTOR( 0.0f, 1.0f, 0.0f );
                vUpVec    = D3DVECTOR( 0.0f, 0.0f,-1.0f );
                break;
            case D3DCUBEMAP_FACE_NEGATIVE_Y:
                vLookatPt = D3DVECTOR( 0.0f,-1.0f, 0.0f );
                vUpVec    = D3DVECTOR( 0.0f, 0.0f, 1.0f );
                break;
            case D3DCUBEMAP_FACE_POSITIVE_Z:
                vLookatPt = D3DVECTOR( 0.0f, 0.0f, 1.0f );
                vUpVec    = D3DVECTOR( 0.0f, 1.0f, 0.0f );
                break;
            case D3DCUBEMAP_FACE_NEGATIVE_Z:
                vLookatPt = D3DVECTOR( 0.0f, 0.0f,-1.0f );
                vUpVec    = D3DVECTOR( 0.0f, 1.0f, 0.0f );
                break;
        }

        D3DMATRIX matView;
        D3DXMatrixLookAtLH( matView, vEnvEyePt, vLookatPt, vUpVec );
        d3dDevice->SetTransform( D3DTS_VIEW, &matView );

カメラを正しく配置し、射影行列を設定すると、シーンをレンダリングできる。シーンの各オブジェクトは、通常配置するとおりに配置する。次のコードでは、処理全体がわかるように、このタスクの概略を示す。

        //レンダリングするサーフェスへのポインタを取得する。
        LPDIRECT3DSURFACE8 pFace;
        pCubeMap->GetCubeMapSurface( (D3DCUBEMAP_FACES)i, 0, &pFace );
        d3dDevice->SetRenderTarget ( pFace , pZBuffer );
        pFace->Release();

        d3dDevice->BeginScene();
        // ここで、シーンをレンダリングする。
        d3dDevice->EndScene();
    }

    // レンダリング ターゲットをメイン バック バッファに戻す。
    d3dDevice->SetRenderTarget( pBackBuffer, pZBuffer );
    pBackBuffer->Release();
    pZBuffer->Release();

    // 元のトランスフォーム行列をリストアする。
    d3dDevice->SetTransform( D3DTS_VIEW,       &matViewSave );
    d3dDevice->SetTransform( D3DTS_PROJECTION, &matProjSave );
}

IDirect3DDevice8::SetRenderTarget メソッドの呼び出しには注意すること。キューブ マップ サーフェスにレンダリングするときは、そのサーフェスをカレント レンダリング ターゲット サーフェスとして割り当てる必要がある。深度バッファを使用するアプリケーションでは、そのレンダリング ターゲットに明示的に深度バッファを作成したり、既存の深度バッファをレンダリング ターゲット サーフェスに再割り当てすることができる。上のコードでは、後者の方法を使用している。


キューブ環境マップのテクスチャ座標

キューブ環境マップを指し示すテクスチャ座標は、標準テクスチャを適用する際に使用する単純な u、v スタイルの座標とは異なる。実際、キューブ環境マップではテクスチャ座標を使用しない。テクスチャ座標セットの代わりに、キューブ環境マップでは 3D ベクトルが必要である。適切な頂点フォーマットを指定することが大切である。また、システムにアプリケーションで使用するテクスチャ座標のセット数を知らせるほかにも、各セット内の要素数についての情報を知らせる必要がある。Microsoft®Direct3D® は、これを行うためにマクロの D3DFVF_TEXCOORDSIZEn セットを用意している。これらのマクロにはパラメータが 1 つあり、サイズが記述されるテクスチャ座標セットのインデックスを識別する。3D ベクトルの場合は、D3DFVF_TEXCOORDSIZE3 マクロで作成するビット パターンを含める。次のコードは、このマクロの使用方法を示している。

/*
* 頂点の柔軟な頂点フォーマット記述子を作成する。
* これには、位置座標、法線、および
* 3D テクスチャ座標のセットが 1 つ含まれる。
 */
DWORD dwFVF = D3DFVF_XYZ | D3DFVF_NORMAL | D3DFVF_TEX1 | D3DFVF_TEXCOORDSIZE3(0);

ディフューズ ライト マッピングなどの場合には、ベクトルにカメラ空間の頂点法線を使用する。スペキュラ環境マッピングなどの場合には、反射ベクトルを使用するトランスフォーム済み頂点法線については広く理解されているため、ここでは反射ベクトルの計算について詳しく説明する。

独自に反射ベクトルを計算するには、各頂点の位置座標と、ビューポートからその頂点へのベクトルを知っている必要がある。Direct3D ではジオメトリの反射ベクトルを自動的に計算できる。この機能を使用すれば、環境マップのテクスチャ座標を含める必要がないので、メモリを節約できる。さらに、帯域幅が減少し、TnLHAL デバイスの場合は、アプリケーションで独自に計算するよりもはるかに速く計算を実行できる。この機能を利用するには、キューブ環境マップを含むテクスチャ ステージにおいて、D3DTSS_TEXCOORDINDEX テクスチャ ステージ ステートを、D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR フラグの組み合わせとテクスチャ座標セットのインデックスに設定する。ディフューズ ライト マッピングの場合などには、D3DTSS_TCI_CAMERASPACENORMAL フラグを使用して、システムにカメラ空間のトランスフォーム済み頂点法線をテクスチャのアドレッシング ベクトルとして使用することを知らせることができる。インデックスは、システムがテクスチャのラッピング モードを決定するためにのみ使用する。

次のコードは、この値の使用方法を示している。

/*
* 変数 m_d3dDevice は、IDirect3DDevice8 インターフェイスへの
* 有効なポインタである。
 *
* ステージ 2 に対してテクスチャ座標を自動生成する。
* ここでは、ステージ 2 にキューブ マップが割り当てられているとする。
* インデックス 1 のテクスチャ座標セットからのラップ モードを使用する。
 */
m_d3dDevice->SetTextureStageState( 2, D3DTSS_TEXCOORDINDEX,
                                   D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR | 1);

自動テクスチャ座標生成を有効にすると、2 つの公式のいずれかを使用して各頂点の反射ベクトルが計算される。D3DRS_LOCALVIEWER レンダリング ステートを TRUE に設定すると、次の公式が使用される。

この公式では、R は計算する反射ベクトル、E は位置座標から視点までの正規化されたベクトル、N はカメラ空間の頂点法線である。

D3DRS_LOCALVIEWER レンダリング ステートを FALSE に設定すると、次の公式が使用される。

この公式では、R および N 要素については前の公式と同じである。Nz 要素は頂点法線のワールド空間 z、I は無限大距離にあるビューポートのベクトル (0,0,1) である。システムでは、いずれかの公式で求めた反射ベクトルを使用して、キューブ マップの適切なサーフェスを選択および処理する。

注 ほとんどの場合、アプリケーションでは頂点法線の自動正規化を有効にする必要がある。これを有効にするには、D3DRS_NORMALIZENORMALS を TRUE に設定する。このレンダリング ステートを有効にしていない場合、環境マップの外観が期待とは大きく異なるものになる。


球状環境マッピング

球状環境マッピング (球状マッピングと呼ばれることが多い) は、オブジェクトの周囲の空間の画像またはライティングのエフェクトを、そのオブジェクトの表面に沿って貼り付けていく。このとき、オブジェクトの周囲の空間は、特殊なフォーマットのテクスチャ マップにコード化される。以下のトピックでは、球状マッピングの概念について、および Microsoft Direct3D アプリケーションでの球状マッピングの使用方法について説明する。

  • 球状環境マップとは
  • 球状環境マップのテクスチャ座標
  • 球状環境マップの適用


球状環境マップとは

球状環境マップ、または球状マップは、オブジェクトの周りのシーンの画像またはオブジェクトの周りのライティング エフェクトを含む特殊なテクスチャである。キューブ環境マップとは異なり、球状マップはオブジェクトの周囲の様子を直接表現するわけではない。「環境マッピングとは」のトピックのティーポットの画像は、球状マッピングで実現できる反射エフェクトを示している。

球状マップは、オブジェクトの周囲の 360°の視界を、魚眼レンズで見たように 2D 表現したものである。次の図は、SphereMap サンプルで使用する球状マップを示している。


球状環境マップのテクスチャ座標

環境マッピングの対象となる各頂点に指定するテクスチャ座標は、テクスチャを湾曲したサーフェスに映るゆがみの関数として処理する必要がある。アプリケーションでは、各頂点のテクスチャ座標を計算して、目的のエフェクトを実現しなければならない。テクスチャ座標を簡単かつ効果的に生成する方法は、頂点法線を入力として使用することである。方法には何種類かあるが、次の公式は、球状マップによる環境マッピングを実行するアプリケーションで共通の公式である。

この公式では、u および v は計算するテクスチャ座標、Nx および Ny はカメラ空間の頂点法線の x および y 要素である。この公式は単純で有効である。法線に正方向の x 要素がある場合、法線は右方向を指しており、u 座標はテクスチャを適切に処理できるように調整される。v 座標も同様、正方向の y は、法線が上方向を指していることを示す。各成分の負の値に対しては、この反対が成り立つ。

法線が直接カメラを指している場合、結果の座標にはゆがみが生じない。両方の座標に +0.5 バイアスを加えると、ゆがみのないポイントは球状マップの中央に配置され、(0, 0, z) の頂点法線によってこのポイントが処理される。この公式では、法線の z 要素は考慮されない。ただし、この公式を使用するアプリケーションでは、正方向の z 要素のある法線を持つ頂点を省略することで計算を最適化できる。このような処理が行われるのは、カメラ空間で法線がカメラから離れる方向 (z の正方向) を指している場合、オブジェクトのレンダリング時に頂点がカリングされるためである。


球状環境マップの適用

環境マップをオブジェクトに適用するときは、その他のテクスチャの場合と同様、IDirect3DDevice8::SetTexture メソッドで適切なテクスチャ ステージにテクスチャを設定する。第 1 パラメータには、目的のテクスチャ ステージのインデックスを設定し、第 2 パラメータには、環境マップのキューブ マップ テクスチャの作成時に返された IDirect3DcubeTexture8 インターフェイスのアドレスを設定する。必要に応じて色およびアルファ ブレンディング処理と引数を設定して、目的のテクスチャ ブレンディング エフェクトを得ることができる。


フォグ

ここでは、フォグ機能を紹介し、Microsoft® Direct3D® アプリケーションでの各種フォグ機能の使用方法について説明する。説明するトピックは、次のとおりである。

  • フォグの概要
  • フォグ公式
  • フォグ パラメータ
  • フォグ ブレンディング
  • フォグ カラー
  • ピクセル フォグ
  • 頂点フォグ

フォグ ブレンディングは、レンダリング ステートで制御される。プログラム可能なピクセル パイプラインの一部ではない。


フォグの概要

3D シーンにフォグを追加することにより、よりリアルな情景を表現したり、雰囲気を出したり、遠くの景色をぼかすことができる。Microsoft® Direct3D® は、ピクセル フォグと頂点フォグという 2 つのフォグ モデルをサポートする。この 2 つは、それぞれ固有の機能とプログラミング インターフェイスを持つ。

フォグは、基本的には、シーン内のオブジェクトの深度または視点からの距離に基づき、シーン内のオブジェクトの色と選択したフォグ カラーをブレンドして実現する。オブジェクトが遠ざかるに従い、元の色とフォグ カラーのブレンドが増し、シーンに浮かぶ小さい粒子によってオブジェクトの表示がぼけていく。次の画面は、フォグなしでレンダリングしたシーンと、フォグを有効にしてレンダリングした同じシーンを示している。

上の図で、左側のシーンには明瞭な水平線があり、その向こうには実世界では見えるはずの風景が見えない。右側のシーンでは背景色と同一のフォグ カラーを使用して水平線がぼかされ、ポリゴンが遠方では消えるように見える。個別のフォグ エフェクトとクリエイティブなシーン デザインとを組み合わせると、シーン内のオブジェクトの色を和らげ、雰囲気を増すことができる。

Direct3D では、ピクセル フォグと頂点フォグという 2 つの方法でシーンにフォグを追加できる。それぞれの名前は、そのフォグ効果の適用方法を表している。詳細については、「ピクセル フォグ」および「頂点フォグ」を参照すること。簡単に言えば、ピクセル フォグ (テーブル フォグともいう) はデバイス ドライバで実装され、頂点フォグは Direct3D ライティング エンジンで実装される。

注 頂点フォグおよびピクセル フォグのいずれを使用する場合でも、アプリケーションではフォグ エフェクトが正しく適用されるよう適切な射影行列を用意する必要がある。この制約は、Direct3D トランスフォーム & ライティング エンジンを使用しないアプリケーションにも当てはまる。適切な行列の作成方法の詳細については、「W バッファに有効な射影行列」を参照すること。


フォグ公式

C++ アプリケーションでは、Microsoft® Direct3D® で距離に応じてフォグ エフェクトの計算を変更することにより、フォグがシーンのオブジェクトの色に与える影響を制御できる。D3DFOGMODE 列挙型には、3 つのフォグ公式を識別するメンバが含まれている。すべての式は、アプリケーションが設定するパラメータを与えられ、距離の関数としてフォグ係数を計算する。距離がどのように計算されるかは、範囲ベースのフォグが有効であるかどうかと、射影行列により変化する。詳細については、「視点からの相対深度 対 Z ベースの深度」および「範囲ベースのフォグ」を参照すること。

D3DFOG_LINEAR

この線形公式で、start はフォグ エフェクトが始まる距離、end はフォグ エフェクトがそれ以上増加しなくなる距離、d はシーンの範囲内での深度または視点からの距離を表す。オブジェクトが遠方になるに従って d の値が増加する。線形公式と指数公式は、ピクセル フォグと頂点フォグの両方でサポートされている。

D3DFOG_EXP

D3DFOG_EXP2

上の 2 つの指数公式で、e は自然対数の底 (約 2.71828)、density は 0.0 から 1.0 の範囲の任意のフォグ密度、d はシーンの範囲内での深度、つまり視点からの距離である。

注 システムは、頂点のスペキュラ色のアルファ成分にフォグ係数を格納する。アプリケーションで独自のトランスフォーム & ライティングを実行する場合は、フォグ係数を手動で挿入しておくと、レンダリング時にシステムがそのフォグ係数を適用する。

次の図では、公式のパラメータに共通の値を使用して、これらの公式をグラフに示している。

Direct3D がフォグ エフェクトを計算するときは、上の等式の 1 つのフォグ係数を次に示すブレンディング公式で使用する。

この公式は、現在のポリゴン Ci の色をフォグ係数 f により効果的にスケーリングし、その積を、フォグ係数のビット反転によりスケーリングしたフォグ カラー Cf に加算する。結果として得られるカラー値は、フォグ カラーと元の色のブレンドであり、距離の係数でもある。この公式は、Microsoft DirectX® 7.0 およびそれ以降がサポートするすべてのデバイスに適用される。従来からのランプ デバイスに対しては、フォグ係数はディフューズ色成分とスペキュラ色成分をスケーリングし、0.0 から 1.0 の範囲内 (0.0 と 1.0 を含む) に収める。フォグ係数は、通常、前方クリップ面を 1.0 として始まり、後方クリップ面を 0.0 として減少する。


フォグ パラメータ

フォグ パラメータは、デバイス レンダリング ステートによって制御される。ピクセル フォグおよび頂点フォグではともに、「フォグ公式」で説明するフォグ公式をすべてサポートしている。D3DFOGMODE 列挙型は、Microsoft® Direct3D® で使用するフォグ公式を識別する定数を定義する。D3DRS_FOGTABLEMODE レンダリング ステートは、Direct3D がピクセル フォグに使用するフォグ モードを制御し、D3DRS_FOGVERTEXMODE レンダリング ステートは頂点フォグのモードを制御する。

線形フォグ公式を使用するときは、D3DRS_FOGSTART および D3DRS_FOGEND レンダリング ステートを使用して開始距離およびエンディング距離を設定する。これらの値をシステムがどのように解釈するかは、アプリケーションでピクセル フォグおよび頂点フォグのどちらを使用しているかによって異なる。ピクセル フォグを使用している場合は、z ベースまたは w ベースの深度が使用される。z ベースおよび w ベースの深度の詳細については、「視点からの相対深度 対 Z ベースの深度」を参照すること。フォグの種類およびフォグの開始単位と終了単位を以下の表にまとめる。

フォグの種類 | フォグの開始/終了単位
ピクセル (Z) | デバイス空間 [0.0,1.0]
ピクセル (W) | カメラ空間
頂点 | カメラ空間

D3DRS_FOGDENSITY レンダリング ステートは、指数フォグ公式が有効なときに適用されるフォグ密度を制御する。フォグ密度は、本質的には加重係数であり、指数の距離値を 0.0 から 1.0 (0.0 と 1.0 を含む) にスケーリングする。

システムがフォグ ブレンディングに使用する色は、D3DRS_FOGCOLOR デバイス レンダリング ステートを使用して制御する。詳細については、「フォグ カラー」および「フォグ ブレンディング」を参照すること。


フォグ ブレンディング

フォグ ブレンディングとは、「フォグ公式」で説明するように、シーンに表示する最終色を生成するために、フォグおよびオブジェクトの色にフォグ係数を適用することである。D3DRS_FOGENABLE レンダリング ステートは、フォグ ブレンディングを制御する。次のコードで示すように、このレンダリング ステートを TRUE に設定すると、フォグ ブレンディングが有効になる。デフォルトは FALSE である。

//
// この例では、g_pDevice は IDirect3DDevice8 インターフェイスへの
// 有効なポインタである。
HRESULT hr;
hr = g_pDevice->SetRenderState(
                     D3DRS_FOGENABLE,
                     TRUE);
if FAILED(hr)
    return hr;

フォグ ブレンディングは、ピクセル フォグと頂点フォグの両方に対して有効にしなければならない。これらの種類のフォグの使用方法については、「ピクセル フォグ」および「頂点フォグ」を参照すること。


フォグ カラー

ピクセル フォグおよび頂点フォグの両方のフォグ カラーは、D3DRS_FOGCOLOR レンダリング ステートを使用して設定する。レンダリング ステート値は、RGBA 色として指定する任意の RGB 色である。アルファ成分は無視される。

次の C++ コードは、フォグ カラーを白に設定する。

/* この例では、変数 d3dDevice は IDirect3DDevice8 インターフェイスへの
* 有効なポインタである。
 */
HRESULT hr;

hr = d3dDevice->SetRenderState(
                    D3DRS_FOGCOLOR,
                    0x00FFFFFF); // 上位 8 ビットは使用されない。

if(FAILED(hr))
    return hr;


ピクセル フォグ

ここでは、ピクセル フォグの概念を紹介し、ピクセル フォグの Microsoft® Direct3D® アプリケーションでの使用方法について説明する。説明するトピックは、次のとおりである。

  • ピクセル フォグについて
  • 視点からの相対深度 対 Z ベースの深度
  • ピクセル フォグの使い方


ピクセル フォグについて

ピクセル フォグという名前は、デバイス ドライバでピクセル単位に計算が実行されることから付けられた名前である。これに対して頂点フォグでは、トランスフォーム & ライティングを実行する際にフォグ エフェクトが計算される。ピクセル フォグは、ドライバによっては、ブレンディング計算に適用するフォグ係数 (各ピクセルの深度を使用) を決定するために事前に計算されたルックアップ テーブルを使用するため、テーブル フォグと呼ばれることもある。

ピクセル フォグは、D3DFOGMODE 列挙型のメンバによって識別されるフォグ公式のいずれかを使用して適用する。ピクセル フォグ公式の実装はドライバ固有であり、ドライバが複雑なフォグ公式をサポートしていない場合は、あまり複雑でない公式を使用すること。

注 「範囲ベースのフォグ」で説明するように、ピクセル フォグは範囲ベースのフォグの計算をサポートしない。


視点からの相対深度 対 Z ベースの深度

深度バッファ内での z 値の不均等なばらつきによって生じる、フォグの不自然なグラフィックス効果を抑えるために、ほとんどのハードウェア デバイスでは、ピクセル フォグに z ベース深度値ではなく視点からの相対深度を使用する。視点からの相対深度とは、本質的には同次座標セットからの w 要素である。Microsoft® Direct3D® は、デバイス空間座標から RHW 要素の逆数を取得して真の w を再生成する。デバイスが視点との相対フォグをサポートしている場合、IDirect3DDevice8::GetDeviceCaps メソッドを呼び出すと、そのデバイスは D3DCAPS8 構造体の RasterCaps メンバに D3DPRASTERCAPS_WFOG フラグを設定する。

注 リファレンス ラスタライザを除き、ソフトウェア デバイスは常に z を使用してピクセル フォグ エフェクトを計算する。

視点との相対フォグがサポートされているとき、設定された射影行列でデバイス空間の w 値に対応する、ワールド空間の z 値を生成する場合、システムは z ベース深度よりも視点からの相対深度を優先して自動的に使用する。射影行列を設定するには、IDirect3DDevice8::SetTransform メソッドを呼び出し、D3DTS_PROJECTION 値を使用し、目的の行列を表す D3DMATRIX 構造体を渡す。射影行列がこの要件に対応していない場合は、フォグ エフェクトが正しく適用されない。適切な行列の生成の詳細については、「W バッファに有効な射影行列」を参照すること。「射影トランスフォームとは」で説明するパースペクティブ射影行列は、適切な射影行列を生成する。

Direct3D では、現在設定されている射影行列を使用して w ベース深度の計算を実行する。したがって、アプリケーションで Direct3D トランスフォーム パイプラインを使用しない場合であっても、目的の w ベース機能を取得するために適切な射影行列を設定しておく必要がある。

Direct3D は射影行列の第 4 列を調べる。係数が [0,0,0,1] (アフィン射影) の場合には、システムは z ベースの深度値をフォグに使用する。この場合、デバイス空間の線形フォグ エフェクトの開始距離および終了距離を指定する必要もある。この範囲は、ユーザーに最も近いポイントを 0.0 とし、最も遠いポイントを 1.0 とした範囲である。


ピクセル フォグの使い方

アプリケーションでピクセル フォグを有効にするには、次の手順を実行する。

C++ アプリケーションでピクセル フォグを有効にするには

  1. D3DRS_FOGENABLE レンダリング ステートを TRUE に設定して、フォグ ブレンディングを有効にする。
  2. D3DRS_FOGCOLOR レンダリング ステートで、目的のフォグ カラーを設定する。
  3. D3DRS_FOGTABLEMODE レンダリング ステートを D3DFOGMODE 列挙型の対応するメンバに設定して、使用するフォグ公式を選択する。
  4. 選択したフォグ モードに必要なフォグ パラメータを、関連するレンダリング ステートに設定する。線形フォグの開始距離と終了距離、指数フォグのフォグ密度も含む。

次のサンプル コードは、これらの手順を示している。

// 簡単にするために、この例では、呼び出しの後で
// エラー値をチェックしない。実際のアプリケーションでは、
// エラー値を正しくチェックすること。
//
// この例では、g_pDevice は IDirect3DDevice8 インターフェイスへの
// 有効なポインタであると仮定している。
void SetupPixelFog(DWORD Color, DWORD Mode)
{
    float Start = 0.5f,    // 線形モード用。
          End   = 0.8f,
          Density = 0.66;  // 指数モード用。

    // フォグ ブレンディングを有効にする。
    g_pDevice->SetRenderState(D3DRS_FOGENABLE, TRUE);

    // フォグ カラーを設定する。
    g_pDevice->SetRenderState(D3DRS_FOGCOLOR, Color);

    // フォグ パラメータを設定する。
    if(D3DFOG_LINEAR == Mode)
    {
        g_pDevice->SetRenderState(D3DRS_FOGTABLEMODE, Mode);
        g_pDevice->SetRenderState(D3DRS_FOGSTART, *(DWORD *)(&Start));
        g_pDevice->SetRenderState(D3DRS_FOGEND,   *(DWORD *)(&End));
    }
    else
    {
        g_pDevice->SetRenderState(D3DRS_FOGTABLEMODE, Mode);
        g_pDevice->SetRenderState(D3DRS_FOGDENSITY, *(DWORD *)(&Density));
    }

}

注 IDirect3DDevice8::SetRenderState メソッドは、第 2 パラメータに DWORD 値だけを受け取るが、浮動小数点のフォグ パラメータが要求されることもある。上の例では浮動小数点の値を SetRenderState に渡すために、データを平行移動するのではなく、浮動小数点変数のアドレスを DWORD ポインタにキャストして、次にそれを参照している。


頂点フォグ

ここでは、頂点フォグを紹介し、頂点フォグの Microsoft® Direct3D® アプリケーションでの使用方法について詳しく説明する。説明するトピックは、次のとおりである。

  • 頂点フォグについて
  • 範囲ベースのフォグ
  • 頂点フォグの使い方


頂点フォグについて

システムは頂点フォグを実行するとき、ポリゴンの各頂点にフォグ計算を適用し、次に、ラスタライズの際、ポリゴンの面に結果を補間する。頂点フォグのエフェクトは、Microsoft® Direct3D® のライティング & トランスフォーム エンジンによって計算される。詳細については、「フォグ パラメータ」を参照すること。

アプリケーションで Direct3D を使用しないでトランスフォーム & ライティングを実行する場合は、アプリケーションで独自にフォグ計算を行う必要がある。この場合、アプリケーションはフォグ係数を計算して、各頂点のスペキュラ色のアルファ成分に置く。公式には、範囲ベースの公式、体積を利用する公式など、どのようなものでも使用できる。Direct3D は与えられたフォグ係数を使用して、各ポリゴンの面を補間する。Direct3D のトランスフォーム & ライティングを使用しないアプリケーションでは、頂点フォグ パラメータを設定する必要はないが、フォグを有効にし、関連するレンダリング ステートによってフォグ カラーを設定しなければならない。詳細については、「フォグ パラメータ」を参照すること。

注 アプリケーションで独自のトランスフォーム & ライティングを実行する場合は、それ独自のフォグ計算を実行する必要がある。したがって、そのようなアプリケーションでは、「フォグ ブレンディング」および「フォグ カラー」で説明するように、フォグ ブレンディングを有効にして、関連するレンダリング ステートによってフォグ カラーを設定するだけでよい。


範囲ベースのフォグ

注 Microsoft® Direct3D® では、Direct3D のトランスフォーム & ライティング エンジンで頂点フォグを使用するときのみ、範囲ベースのフォグの計算を実行する。これは、ピクセル フォグはデバイス ドライバに実装され、現在のところ、ピクセル単位の範囲ベースのフォグをサポートするハードウェアは存在しないためである。アプリケーションで独自のトランスフォーム & ライティングを実行する場合は、範囲ベースの計算かその他の計算による独自のフォグ計算を行う必要がある。

フォグを使用すると、オブジェクトがフォグ カラーと直感的でない方法でブレンドされる不自然なグラフィックス効果が生じることがある。たとえば、2 つのオブジェクトが見えていて、一方はフォグの影響を受けるくらいに遠くにあり、他方は影響されないくらいに近くにあるというシーンを想定する。表示領域が同じ場所で回転した場合、オブジェクトが静止していたとしても、現れるフォグ エフェクトは変化することがある。次の図は、こうした状況を見下ろしたステートを示している。

範囲ベースのフォグは、フォグ エフェクトをより正確に決定する方法である。範囲ベースのフォグでは、Direct3D は視点から頂点までの実際の距離をフォグの計算に使用する。シーンの範囲内での頂点の深度ではなく 2 点間の距離の増加に従ってフォグのエフェクトが増加されるため、不自然な回転効果が回避される。

現在のデバイスが範囲ベースのフォグをサポートしている場合、IDirect3DDevice8::GetDeviceCaps メソッドを呼び出したときに、デバイスは D3DCAPS8 構造体の RasterCaps メンバに D3DPRASTERCAPS_FOGRANGE 能力フラグを設定する。範囲ベースのフォグを有効にするには、D3DRS_RANGEFOGENABLE レンダリング ステートを TRUE に設定する。

範囲ベースのフォグは、Direct3D により、トランスフォーム & ライティングの間に計算される。「頂点フォグについて」で説明したように、Direct3D トランスフォーム & ライティング エンジンを使用しないアプリケーションは、独自に頂点フォグの計算も行わなければならない。この場合、範囲ベースのフォグ係数を、各頂点のスペキュラ成分のアルファ成分に設定する。


頂点フォグの使い方

アプリケーションで頂点フォグを有効にするには、次の手順を実行する。

C++ アプリケーションで頂点フォグを有効にするには

  1. D3DRS_FOGENABLE を TRUE に設定して、フォグ ブレンディングを有効にする。
  2. D3DRS_FOGCOLOR レンダリング ステートで、必要なフォグ カラーを設定する。
  3. D3DRS_FOGVERTEXMODE レンダリング ステートを D3DFOGMODE 列挙型のメンバに設定して、目的のフォグ公式を選択する。
  4. 選択したフォグ公式で必要なフォグ パラメータをレンダリング ステートに設定する。

次の C++ サンプル コードは、これらの手順を示している。

// 簡単にするために、この例では、呼び出しの後で
// エラー値をチェックしない。実際のアプリケーションでは、
// エラー値を正しくチェックすること。
//
// この例では、g_pDevice は IDirect3DDevice8 インターフェイスへの
// 有効なポインタであると仮定している。
void SetupVertexFog(DWORD Color, DWORD Mode, BOOL UseRange, FLOAT Density)
{
    float Start = 0.5f,    // 線形フォグ距離。
          End   = 0.8f;

    // フォグ ブレンディングを有効にする。
    g_pDevice->SetRenderState(D3DRS_FOGENABLE, TRUE);

    // フォグ カラーを設定する。
    g_pDevice->SetRenderState(D3DRS_FOGCOLOR, Color);

    // フォグ パラメータを設定する。
    if(D3DFOG_LINEAR == Mode)
    {
        g_pDevice->SetRenderState(D3DRS_FOGVERTEXMODE, Mode);
        g_pDevice->SetRenderState(D3DRS_FOGSTART, *(DWORD *)(&Start));
        g_pDevice->SetRenderState(D3DRS_FOGEND,   *(DWORD *)(&End));
    }
    else
    {
        g_pDevice->SetRenderState(D3DRS_FOGVERTEXMODE, Mode);
        g_pDevice->SetRenderState(D3DRS_FOGDENSITY, *(DWORD *)(&Density));
    }

    // 必要に応じて、範囲ベースのフォグを有効にする
    // (頂点フォグでのみサポートされる)。この例では、ドライバが D3DPRASTERCAPS_FOGRANGE 能力を公開する場合にのみ、
    // UseRange は
    // ゼロ以外の値に設定されるとする。
    // 注  この方が、範囲に基づかないフォグよりも
    //       若干パフォーマンスがよい。
    if(UseRange)
        g_pDevice->SetRenderState(
                       D3DRS_RANGEFOGENABLE,
                       TRUE);
}

IDirect3DDevice8::SetRenderState メソッドは、第 2 パラメータに DWORD 値だけを受け取るが、浮動小数点のフォグ パラメータが要求されることもある。この例では、浮動小数点の値をデータの平行移動なしでメソッドに渡すために、浮動小数点変数のアドレスを DWORD ポインタとしてキャストし、次にそれを参照から解除している。


ジオメトリ ブレンディング

ここでは、ジオメトリ ブレンディングについて説明する。説明するトピックは、次のとおりである。

  • ジオメトリ ブレンディングについて
  • ブレンディング トランスフォームとレンダリング ステート
  • ブレンディングの重み
  • ジオメトリ ブレンディングの使い方


ジオメトリ ブレンディングについて

Microsoft® Direct3D® では、ジョイント部が滑らかにブレンドされているセグメント化されたポリゴン オブジェクト、特にキャラクタをレンダリングすることで、シーンを一層リアルに表現することができる。これらのエフェクトを一般にスキニングと呼ぶ。このエフェクトは、追加のワールド トランスフォーム行列を頂点の単一セットに適用し、その結果生成される複数のトランスフォーム後の頂点間で線形ブレンドを実行してレンダリング用のジオメトリの単一セットを生成することで実現される。次のバナナのイラストは、この例を示している。

この画像は、ジオメトリ ブレンディングの処理がどのようなものであるかを示している。1 回のレンダリングの呼び出しで、システムはバナナの頂点を取得し、この頂点に対して回転しないトランスフォームと単純な回転のトランスフォームを 1 回ずつ実行して、その結果曲がったバナナを生成する。システムは、ライティングが有効な場合に、頂点法線だけでなく頂点位置座標もブレンドする。アプリケーションは 2 つのブレンディング方法に限定されるわけではない。Direct3D は、最大 4 つのワールド行列 (標準ワールド行列の D3DTS_WORLD など) 間でジオメトリをブレンドできる。

注 ライティングが有効になっている場合、頂点法線が、対応するワールド ビュー行列の逆行列によってトランスフォームされる。この際、重み付けは、頂点位置座標の計算の場合と同様に行われる。D3DRS_NORMALIZENORMALS レンダリング ステートが TRUE に設定されている場合は、結果の法線ベクトルがシステムによって正規化される。

可動結合部のあるモデルの場合、ジオメトリ ブレンディングを使用せずに部分ごとにレンダリングされることが多い。たとえば、人間の腕の 3D モデルを考える。最も単純にして、腕には身体につながる上腕と手につながる下腕がある。2 本の腕はともに肘につながっており、下腕はこの位置座標で回転する。アプリケーションで腕をレンダリングする場合、上腕と下腕の頂点データは保持され、それぞれに個別のワールド トランスフォーム行列が適用される。次のサンプル コードは、これを示している。

typedef struct _Arm {
    VERTEX upper_arm_verts[200];
    D3DMATRIX matWorld_Upper;

    VERTEX lower_arm_verts[200];
    D3DMATRIX matWorld_Lower;
} ARM, *LPARM;

ARM MyArm; // これは初期化する必要がある。

腕をレンダリングするには、次のコードで示すように、レンダリングの呼び出しを 2 回実行する。

// 上腕をレンダリングする。
d3dDevice->SetTransform( D3DTS_WORLD, &MyArm.matWorld_Upper );
d3dDevice->DrawPrimitive( D3DPT_TRIANGLELIST, 0, numFaces );

// 下腕をレンダリングして、腕を関節でつなぐワールド行列を更新する。
// 肘で pi/4 ラジアン (45°) ずつ回転するようにする。
MyArm.matWorld_Lower = RotateMyArm(MyArm.matWorld, pi/4);
d3dDevice->SetTransform( D3DTS_WORLD, &MyArm.matWorld_Lower );
d3dDevice->DrawPrimitive( D3DPT_TRIANGLELIST, 0, numFaces );

次の画像は、このテクニックを使ってバナナを修正したものである。

ブレンドされたジオメトリと、ブレンドされていないジオメトリの違いは明らかである。この例でもその違いははっきりわかる。実際のアプリケーションでは、各モデルをジョイントしても、それほどジョイント部が目立つことはない。しかし、ジョイント部が見苦しく表示されることもある。これは、モデル デザイナにとっては常に課題である。

Direct3D のジオメトリ ブレンディングでは、従来のセグメント モデル シナリオを使用することもできる。しかし、分割されている個々のオブジェクトの表示品質を上げるには、レンダリング時のブレンディング計算が必要となる。これらの追加処理による影響を最小限に抑えるために、Direct3D ジオメトリ パイプラインは、可能な限りオーバーヘッドを発生させないでジオメトリをブレンドできるように最適化される。アプリケーションでは Direct3D のジオメトリ ブレンディング サービスを有効に使用することで、パフォーマンスへの深刻な影響を避けながら、キャラクタをより本物らしく表現することができる。


ブレンディング トランスフォームとレンダリング ステート

IDirect3DDevice8::SetTransform メソッドは、D3DTS_WORLD マクロおよび D3DTS_WORLDn マクロを認識するが、これらのマクロは D3DTS_WORLDMATRIX マクロによって定義される値に対応する。これらのマクロを使用して、ジオメトリがブレンドされる際の行列を識別する。

D3DRENDERSTATETYPE 列挙型には、ジオメトリ ブレンディングを有効にして制御する D3DRS_VERTEXBLEND レンダリング ステートが含まれる。このレンダリング ステートの有効値は、D3DVERTEXBLENDFLAGS 列挙型によって定義される。ジオメトリ ブレンディンが有効になっている場合、頂点フォーマットにはブレンディングの適切な加重値が含まれていなければならない。

参照

ブレンディング行列の設定、ジオメトリ ブレンディングを有効にする、ブレンディングの重み


ブレンディングの重み

ブレンディングの重み (ベータの重みと呼ぶときもある) は、指定されたワールド行列によって頂点が受ける影響の範囲を制御する。ブレンディングの重みとは、0.0 ～ 1.0 の範囲の浮動小数点値であり、頂点フォーマットでエンコードされる。値が 0.0 の場合、頂点はその行列でブレンドされない。値が 1.0 の場合、頂点は行列の影響をすべて受ける。

ジオメトリ ブレンディングの重みは、頂点フォーマットでエンコードされ、「頂点フォーマットについて」で説明するように、各頂点の位置座標のすぐ後に現れる。Microsoft® Direct3D® レンダリング メソッドに指定する頂点記述に D3DFVF_XYZB1 ～ D3DFVF_XYZB5 の柔軟な頂点フォーマット フラグのいずれかを含めることで、頂点フォーマットにブレンディングの重みを指定する。

重み付けされたブレンド行列間で、システムによって線形ブレンドが実行される。次に、正式なブレンディング公式を示す。

前記の公式では、vBlend は出力頂点であり、v 要素は適用後のワールド行列 (D3DTS_WORLDn) によって生成される頂点である。W 要素は、頂点フォーマット内の対応する重みである。n 個の行列間でブレンドされる頂点は、n–1 個のブレンディングの重みを持つことができる (最後のブレンディング行列を除き、各ブレンディング行列に 1 つの重み)。最後のワールド行列の重みは、この公式では Σ で表すように、重みの合計が 1.0 になるようシステムによって自動的に生成される。この公式は、Direct3D がサポートしているケースに合わせて簡略化できる。

これらの公式は、正式なブレンディング公式を、2、3、および 4 つのブレンド行列のケースに合わせて簡略化したものである。

注 Direct3D では、最大 5 つのブレンディングの重みを持つ頂点を定義する柔軟な頂点フォーマット記述子を含めることができるが、このリリースの Microsoft DirectX® では 3 つまでしか使用できない。


ジオメトリ ブレンディングの使い方

ここでは、アプリケーションでのジオメトリ ブレンディングの使用方法について説明する。説明するトピックは、次のとおりである。

  • ブレンディング用の頂点の定義
  • ブレンディング行列の設定
  • ジオメトリ ブレンディングを有効にする


ブレンディング用の頂点の定義

次のユーザー定義構造体は、2 つの行列間でブレンドする頂点に使用できる。

//
// この頂点の柔軟な頂点フォーマット記述子は次のとおりである。
//
//     FVF = D3DFVF_XYZB1 | D3DFVF_NORMAL | D3DFVF_TEX1;
//
struct D3DBLENDVERTEX {
    D3DVECTOR v;
    FLOAT     blend;
    D3DVECTOR n;
    FLOAT     tu, tv;
};

「ブレンディングの重み」で説明するように、ブレンドの重みは柔軟な頂点フォーマット内の位置座標および RHW データの後ろで、かつ頂点法線の前になければならない。

前の頂点フォーマットには、ブレンディングの重みが 1 つしかないことに注意する。これは、D3DTS_WORLDMATRIX(0) および D3DTS_WORLDMATRIX(1) トランスフォーム ステートで定義される 2 つのワールド行列があるためである。これら 2 つの行列間でそれぞれの頂点が、1 つの重みを使用してブレンドされる。行列が 3 つある場合、重みは 2 つ必要である。

注 スキンの重みは簡単に定義できる。ジョイントするオブジェクト間の距離の線形関数を使用するとよいが、より滑らかな S 字関数を使用するとさらによい。スキンの重み分布関数を選択すると、必要に応じてジョイント部に鮮明なしわを付けることができる (短い距離間でスキンの重みの変化を大きくする)。

参照

頂点フォーマットについて、柔軟な頂点フォーマット フラグ


ブレンディング行列の設定

IDirect3DDevice8::SetTransform メソッドを呼び出して、システムがブレンドする際のトランスフォーム行列を設定する。第 1 パラメータに D3DTS_WORLDMATRIX マクロで定義される値を設定し、第 2 パラメータには設定する行列のアドレスを設定する。

次の C++ コード例は、2 つのワールド行列を設定する。これらの行列間でジオメトリをブレンドしてジョイントされた腕のイリュージョンを作成する。

// この例では、変数 d3dDevice は
// 初期化済みの IDirect3DDevice8 インターフェイスへの
// 有効なポインタであると仮定している。
float     BendAngle = 3.1415926f / 4.0f; // 45°
D3DMATRIX matUpperArm, matLowerArm;

// 上腕は動かない。単位行列を使用する。
D3DXMatrixIdentity( matUpperArm );
d3dDevice->SetTransform( D3DTS_WORLDMATRIX(0), &matUpperArm );

// 下腕は x 軸を中心に回転する。これは上腕につなげる。
D3DXMatrixRotationX( matLowerArm, -BendAngle );
d3dDevice->SetTransform( D3DTS_WORLDMATRIX(1), &matLowerArm );

ブレンディング行列を設定しても、システムはその行列を後で使用できるように単にキャッシュするだけで、頂点のブレンドを開始するわけではない。詳細については、「ジオメトリ ブレンディングを有効にする」を参照すること。


ジオメトリ ブレンディングを有効にする

デフォルトでは、ジオメトリ ブレンディングは無効である。ジオメトリ ブレンディングを有効にするには、IDirect3DDevice8::SetRenderState メソッドを呼び出して D3DRS_VERTEXBLEND レンダリング ステートを D3DVERTEXBLENDFLAGS 列挙型からの値に設定する。次のコードは、2 つのワールド行列間でブレンドするための、レンダリング ステートの設定を示している。

d3dDevice->SetRenderState( D3DRS_VERTEXBLEND, D3DVBF_1WEIGHTS );

D3DRS_VERTEXBLEND が D3DVBF_DISABLE 以外の値に設定されている場合は、頂点フォーマットに適切な個数のブレンディングの重みが含まれていると見なされる。適切な頂点フォーマットを作成すること、およびそのフォーマットの正しい記述を Microsoft® Direct3D® レンダリング メソッドに提供することは開発者の責任である。詳細については、「ブレンディング用の頂点の定義」を参照すること。

ジオメトリ ブレンディングが有効になっている場合、DrawPrimitive レンダリング メソッドでレンダリングされるすべてのオブジェクトに対してジオメトリ ブレンディングが実行される。


インデックス付き頂点ブレンディング

ここでは、Microsoft® Direct3D® 固定機能頂点パイプラインのインデックス付き頂点ブレンディングについて説明する。説明するトピックは、次のとおりである。

  • インデックス付き頂点ブレンディングについて
  • インデックス付き頂点ブレンディング トランスフォームとレンダリング ステート
  • インデックス付き頂点ブレンディングの使い方


インデックス付き頂点ブレンディングについて

インデックス付き頂点ブレンディングは、Microsoft® Direct3D® の頂点ブレンディング サポートを拡張して、行列をブレンディングに使用できるようにしたものである。これらの行列は、行列のインデックスを使用して示される。これらのインデックスは、頂点ごとに提供され、最大 256 個の行列のパレットを参照する。各インデックスは 8 ビットで、各頂点には最大 4 つまでのインデックスを持たせることができるため、1 つの頂点につき 4 つの行列をブレンドすることができる。インデックスは、DWORD にパックされる。インデックスは頂点ごとに指定されるので、最大 12 個の行列が単一の三角形に影響を与えることができ、パレット内の任意の行列が 1 つの描画呼び出しの頂点に影響を与えることができる。このアプローチには、次のような長所がある。

  • 単一の三角形に対して、より多くの行列が影響を与えるようにすることができる。
  • より多くのブレンドされた三角形を、同一の描画呼び出しに渡すことができる。
  • 頂点ブレンディングを三角形インデックスとは独立したものにする。このため、プログレッシブ メッシュを頂点ブレンディングと共に動作させることができる。

この方法の弱点は、頂点処理の前にテッセレーションが行われると、曲面サーフェス プリミティブを処理しないことである。

次の図は、頂点が 4 つの行列によって影響を受ける様子を示している。各頂点は最大 4 つまでのインデックスを持つことができるので、頂点ごとに 4 つの行列をブレンドすることができる。次の図では、0、2、5、および 6 とインデックスを付けられた行列を使用する。

次の図は、1 つの三角形が最高 12 の行列によって影響を受ける様子を示している。頂点ごとに指定されるインデックスを使用して、最大 12 個の行列が単一の三角形に影響を与えることができる。

次の公式は、行列が頂点に与える効果についての一般的な場合を決定する。

Vmodel は、入力モデル空間での頂点の位置座標である。Index0..Index3 は、DWORD にパックされた頂点ごとの行列のインデックスである。M[] は、インデックスを付けるワールド行列の配列で、b0..b2 はブレンド ウェイトである。Vworld は、出力ワールド空間での頂点の位置座標である。


インデックス付き頂点ブレンディング トランスフォームとレンダリング ステート

256 ～ 511 の範囲のトランスフォーム ステートは、8 ビットのインデックスを使ってインデックス付けできる最大 256 個の行列を格納するために確保されている。D3DTS_WORLDMATRIX マクロを使用して、インデックス 0 ～ 255 を対応するトランスフォーム ステートにマッピングする。次のコードは、IDirect3DDevice8::SetTransform メソッドを使用してトランスフォーム ステート番号 256 の行列を単位行列に設定する方法を示している。

D3DMATRIX matBlend1;

D3DXMatrixIdentity( &matBlend1 );
d3dDevice->SetTransform( D3DTS_WORLDMATRIX(0), &matBlend );

インデックス付き頂点ブレンディングの有効と無効を切り替えるには、D3DRS_INDEXEDVERTEXBLENDENABLE レンダリング ステートを TRUE に設定する。このレンダリング ステートが有効になっている場合は、頂点ごとにパック DWORD で行列インデックスを渡さなければならない。このレンダリング ステートを無効にし、頂点ブレンディングを有効にすることは、すべての頂点について行列インデックス 0、1、2、3 を指定することに等しい。以下のコードは、IDirect3DDevice8::SetRenderState メソッドを使用して、インデックス付き頂点ブレンディングを有効にする。

d3dDevice->SetRenderState( D3DRS_INDEXEDVERTEXBLENDENABLE, TRUE );

頂点ブレンディングの有効と無効を切り替えるには、D3DRS_VERTEXBLEND レンダリング ステートを D3DVERTEXBLENDFLAGS 列挙型の D3DRS_DISABLE 以外の値に設定する。このレンダリング ステートが D3DRS_DISABLE に設定されていない場合は、各頂点に必要な加重値を渡さなければならない。次のコードは、SetRenderState を使用して、各頂点対して 3 つの重みで頂点ブレンディングを有効にする。

d3dDevice->SetRenderState( D3DRS_VERTEXBLEND, D3DVBF_3WEIGHTS );


インデックス付き頂点ブレンディングの使い方

ここでは、以下のトピックについて説明する。

  • インデックス付き頂点ブレンディングのサポートの判定
  • Direct3D に対する行列インデックスの受け渡し


インデックス付き頂点ブレンディングのサポートの判定

インデックス付き頂点ブレンディング行列の最大サイズを判定するには、D3DCAPS8 構造体の MaxVertexBlendMatrix メンバを調べる。次のコードは、IDirect3DDevice8::GetDeviceCaps メソッドを使用して、このサイズを取得する。

D3DCAPS8 d3dCaps;

d3dDevice->GetDeviceCaps( &d3dCaps );
IndexedMatrixMaxSize = d3dCaps.MaxVertexBlendMatrixIndex;

MaxVertexBlendMatrix に設定された値が 0 の場合、デバイスはインデックス付きの行列をサポートしていない。

注 ソフトウェア頂点処理が使われている場合は、法線ブレンディングがあってもなくても、256 個の行列をインデックス付き頂点ブレンディングに使用できる。


Direct3D に対する行列インデックスの受け渡し

ワールド行列インデックスは、従来の頂点シェーダ (FVF) か宣言のどちらかを使って、Microsoft® Direct3D® に渡すことができる。

次のコードは、従来の頂点シェーダを使用する方法を示している。

struct VERTEX
{
    float x,y,z;
    float weight;
    DWORD matrixIndices;
    float normal[3];
};

#define D3DFVF_CUSTOMVERTEX (D3DFVF_XYZB2 | D3DFVF_LASTBETA_UBYTE4 |
                             D3DFVF_NORMAL);

従来の頂点シェーダを使用する場合、行列インデックスは D3DFVF_XYZBn フラグを使用して頂点位置座標と共に渡される。行列インデックスは DWORD 内のバイトとして渡され、最後の頂点加重の直後に存在しなければならない。頂点加重も D3DFVF_XYZBn を使用して渡される。パック DWORD は、index3、index2、index1、および index0 を保持し、index0 は DWORD の最下位バイトにある。使用されるワールド行列インデックスの数は、D3DRS_VERTEXBLEND によって定義されるブレンディングに使用される行列の数に渡される数値に等しい。

宣言を使用する場合は、D3DVSDE_BLENDINDICES が行列インデックスを取得する入力頂点レジスタを定義する。行列インデックスは、D3DVSDT_PACKEDBYTE として渡す必要がある。

次のコードは、宣言の使用方法を示している。固定機能による頂点シェーダを使用しない限り、コンポーネントの順序はまったく重要ではない点に注意すること。

struct VERTEX
{
    float x,y,z;
    float weight;
    DWORD matrixIndices;
    float normal[3];
}

DWORD decl[] =
{
    D3DVSD_STREAM(0),
    D3DVSD_REG(D3DVSDE_POSITION, D3DVSDT_FLOAT3),
    D3DVSD_REG(D3DVSDE_BLENDWEIGHT, D3DVSDT_FLOAT1),
    D3DVSD_REG(D3DVSDE_BLENDINDICES, D3DVSDT_UBYTE),
    D3DVSD_REG(D3DVSDE_NORMAL, D3DVSDT_FLOAT3),
    D3DVSD_END()
};


ステンシル バッファ技術

アプリケーションでステンシル バッファを使用して、画像のピクセルをマスクする。このマスクは、ピクセルを描画するかどうかを制御する。ステンシル バッファの詳細については、「ステンシル バッファ」を参照すること。

Microsoft® Direct3D® アプリケーションは、ステンシル バッファを使用して広範な特殊効果を生み出すことができる。ここでは、頻繁に使用される以下のエフェクトについて説明する。

  • ディゾルブ、フェード、およびワイプ
  • デカーリング
  • 合成
  • アウトラインとシルエット


ディゾルブ、フェード、およびワイプ

ディゾルブ、ワイプ、およびフェードなどの映画やビデオでよく使われる特殊効果をアプリケーションで利用することが増えている。

ディゾルブでは、フレームが徐々に変わることによってある画像が別の画像にスムーズに移行する。Microsoft® Direct3D® では、マルチ テクスチャ ブレンディングを使用する方法でこのエフェクトを作成できるが、ディゾルブにステンシル バッファを使用するアプリケーションは、ディゾルブの実行中にテクスチャ ブレンディング機能をほかのエフェクトに利用できる。

ディゾルブを実行するとき、アプリケーションは 2 つの異なる画像をレンダリングしなければならない。アプリケーションはステンシル バッファを使用して、レンダリング ターゲット サーフェスに各画像のどのピクセルを描画するのかを制御する。一連のステンシル マスクを定義して、連続するフレームのステンシル バッファにこれらのマスクをコピーできる。別の方法として、最初のフレーム用の基本ステンシル マスクを定義し、このマスクをインクリメントして変更することもできる。

ディゾルブを開始した時点で、アプリケーションは、開始時の画像のピクセルのほとんどがステンシル テストをパスするようにステンシル関数とステンシル マスクを設定する。最後の画像のほとんどのピクセルは、ステンシル テストに失敗することになる。フレームが続くにつれて、最初の画像のピクセルでテストにパスするピクセルが徐々に少なくなるように、ステンシル マスクを更新する。フレームが続くにつれて、最後の画像のピクセルでテストに失敗するピクセルが徐々に少なくなる。このように、任意のディゾルブ パターンを使用してディゾルブを実行できる。

フェード インまたはフェード アウトは、ディゾルブの特殊なケースである。フェード インするときは、ステンシル バッファを使用して、黒色または白色の画像から 3D シーンのレンダリングにディゾルブする。フェード アウトはこれと逆で、3D シーンのレンダリングから始まって、黒色または白色の画像にディゾルブする。フェードには、どのようなパターンでも使用できる。

Direct3D アプリケーションは、ワイプにも同様な技術を使用する。たとえば、左から右へのワイプを実行する場合、最後の画像が最初の画像の上に徐々にスライドするように左から右に移動する。ディゾルブの場合と同様、連続フレームのステンシル バッファにロードする一連のステンシル マスクを定義するか、最初のステンシル マスクを連続的に修正する必要がある。このステンシル マスクは、最初の画像のピクセルの書き込みを無効にし、最後の画像のピクセルの書き込みを有効にするために使用する。

ワイプの順序とは逆の順序で最後の画像のピクセルを読み出さなければならないという点で、ワイプはディゾルブよりも少し複雑である。つまり、ワイプが左から右に移動する場合、アプリケーションは最後の画像のピクセルを右から左に読み出さなければならない。


デカーリング

Microsoft® Direct3D® アプリケーションは、デカーリング技術を使用して、特定のプリミティブ画像のどのピクセルをレンダリング ターゲット サーフェスに描画するかを制御する。アプリケーションは、デカールをプリミティブの画像に適用して、同一平面上のポリゴンが正しくレンダリングされるようにする。

たとえば、タイヤの跡と黄色の線を道路に適用するとき、この跡は直接道路の上に表示しなければならない。しかし、この跡と道路の z 値は同一である。したがって、深度バッファでは、両者をはっきりと区別できない。背後のプリミティブのピクセルが前面のプリミティブ上にレンダリングされたり、その逆のレンダリングが行われる場合がある。この結果、画像はフレームごとに揺れる。このエフェクトをZ ファイティングまたはフリマリングと呼ぶ。

この問題を解決するには、ステンシルを使用して、デカールが表示される背面プリミティブの部分をマスクする。z バッファリングをオフにして、レンダリング ターゲット サーフェスのマスクで覆っている領域に前面プリミティブの画像をレンダリングする。

マルチ テクスチャ ブレンディングを使用してこの問題を解決することもできるが、この方法を使用すると、アプリケーションで生成できるほかの特殊効果の数が制限される。ステンシル バッファを使用してデカールを適用すると、ほかのエフェクトに対するテクスチャ ブレンディング ステージの制限が解放される。


合成

アプリケーションでステンシル バッファを使用して、2D または 3D 画像を 3D シーンに合成できる。ステンシル バッファのマスクを使用して、レンダリング ターゲット サーフェスの領域を遮蔽する。次に、テキストやビットマップなどの格納 2D 情報を遮蔽領域に書き込むことができる。別の方法として、追加 3D プリミティブをレンダリング ターゲット サーフェスのステンシル マスクされた領域にレンダリングできる。この場合、シーン全体をレンダリングすることもできる。

ゲームでは、複数の 3D シーンを合成することが多い。たとえば、運転ゲームでは通常バックミラーを表示する。バックミラーには、運転者の背後の 3D シーンの表示が含まれる。したがって、バックミラーは、本質的には運転者の前方の風景と合成された 第 2 の 3D シーンと言える。


アウトラインとシルエット

ステンシル バッファは、アウトラインやシルエットなどのより抽象的なエフェクトに使用することもできる。

プログラムで、プリミティブと同じ形状であるが少し小さいステンシル マスクをプリミティブの画像に適用すると、画像はプリミティブのアウトラインだけになる。次に画像のステンシル マスクをした領域を均一の色で塗りつぶし、プリミティブが浮き上がって見えるようにすることができる。

レンダリングするプリミティブとステンシル マスクが同じサイズで同じ形状の場合、本来プリミティブが存在する場所に穴ができる。この穴を黒く塗りつぶすと、プリミティブのシルエットを生成できる。


頂点トゥイーニング

ここでは、複数ストリームを使用した頂点トゥイーニングについて説明する。説明するトピックは、次のとおりである。

  • 頂点トゥイーニングについて
  • 頂点トゥイーニングのアルゴリズム
  • 頂点トゥイーニングの使い方


頂点トゥイーニングについて

頂点トゥイーニングは、2 つのユーザー指定の位置座標間または法線ストリームをブレンドするために使用される。頂点トゥイーニングは、宣言によってのみ使用できる。トゥイーニングを有効にするには、D3DRS_VERTEXBLEND を D3DVBF_TWEENING に設定する。加重を使用した頂点ブレンディングと頂点ブレンディング トゥイーニングは、互いに排他的である。

C++ の「DolphinVS サンプル」は、頂点トゥイーニングによる、イルカが水中を移動しているように見えるアニメーションである。以下の画像は、2 つの異なる点におけるイルカを示している。右側の画像のイルカの方が、尾の位置が上から下に下がっており、鼻もより下向きになっている点に注意すること。

宮bmc dolphin1.gif}�


頂点トゥイーニングのアルゴリズム

トゥイーニングは、ライティングやクリッピングの前に行われる。最終的な頂点の位置座標 (法線) は、次のように計算される。

POSITION = POSITION1 * (1.0 - TWEENFACTOR) + POSITION2 * TWEENFACTOR。法線の場合も同様である。


頂点トゥイーニングの使い方

説明するトピックは、次のとおりである。

  • 頂点トゥイーニングのサポートの判定
  • 頂点の宣言の設定
  • 固定機能によるトゥイーニング
  • 頂点シェーダによるトゥイーニング


頂点トゥイーニングのサポートの判定

Microsoft® Direct3D® が頂点トゥイーニングをサポートしているかどうかを調べるには、D3DCAPS8 構造体の VertexProcessingCaps メンバの D3DVTXPCAPS_TWEENING フラグを調べる。次のコードは、IDirect3DDevice8::GetDeviceCaps メソッドを使用して、トゥイーニングがサポートされているかどうかを判定する。

//
// この例では、m_d3dDevice は IDirect3DDevice8 インターフェイスへの
// 有効なポインタであると仮定している。
//

D3DCAPS8 d3dCaps;

m_d3dDevice->GetDeviceCaps( &d3dCaps );
if( 0 != d3dCaps.VertexProcessingCaps & D3DVTXPCAPS_TWEENING )
    // 頂点トゥイーニングはサポートされている。


頂点の宣言の設定

ベクトル トゥイーニングを使用するには、最初に、2 番目の法線または 2 番目の位置座標を使用するカスタム頂点タイプを設定しなければならない。次のコードは、2 番目の法線と 2 番目の位置座標の両方を含む宣言の例を示している。

struct TEX_VERTEX
{
    D3DVECTOR position;
    D3DVECTOR normal;
    D3DVECTOR position2;
    D3DVECTOR normal2;
};

// タイプが TEX_VERTEX の頂点バッファを作成する。

次の手順は、現在の宣言を設定することである。次のサンプル コードは、この設定方法を示している。

DWORD decl[]
{
    D3DVSD_STREAM(0),
    D3DVSD_REG( D3DVSDE_POSITION, D3DVSDT_FLOAT3 ) // 位置座標 1
    D3DVSD_REG( D3DVSDE_NORMAL, D3DVSDT_FLOAT3 )   // 法線 1
    D3DVSD_REG( D3DVSDE_POSITION2, D3DVSDT_FLOAT3) // 位置座標 2
    D3DVSD_REG( D3DVSDE_NORMAL2, D3DVSDT_FLOAT3 )  // 法線 2
    D3DVSD_END()
};

カスタム頂点タイプと頂点バッファの作成の詳細については、「頂点バッファの作成」を参照すること。

頂点シェーダの宣言の作成の詳細については、「頂点シェーダ宣言」を参照すること。

注 頂点トゥイーニングが有効になっている場合、2 番目の位置座標または 2 番目の法線は現在の宣言の中に存在しなければならない。


固定機能によるトゥイーニング

次のサンプル コードは、頂点タイプと宣言を設定した後で、固定機能による頂点トゥイーニングを実現する方法を示している。

//この例で使用される変数。
DWORD handle;
float TweenFactor = 0.3f;

最初の手順は、次のコードに示すように、IDirect3DDevice8::CreateVertexShader メソッドを使用して頂点シェーダを作成することである。

m_d3dDevice->CreateVertexShader( decl, NULL, &handle, 0 );

CreateVertexShader が受け取る第 1 パラメータは、ベクトル シェーダ宣言へのポインタである。この例では、「頂点の宣言の設定」で宣言した宣言が使用されている。第 2 パラメータは、頂点シェーダ関数の配列へのポインタとなる。この例では、頂点シェーダ関数は使用しないので、このパラメータには NULL を設定する。第 3 パラメータは、返される頂点を表す頂点シェーダ ハンドルへのポインタとなる。第 4 パラメータには、頂点シェーダの使用コントロールを指定する。D3DUSAGE_SOFTWAREPROCESSING フラグを使用して、頂点シェーダがソフトウェア頂点処理を使用する必要があることを指示することができる。この例では、このパラメータをゼロに設定して、頂点処理はハードウェアで行う必要があることを指示している。

次の手順は、次のコードに示すように、IDirect3DDevice8::SetVertexShader メソッドを呼び出して、現在の頂点シェーダを設定することである。

m_d3dDevice->SetVertexShader( handle );

SetVertexShader は、頂点シェーダへのハンドルを受け取る。このパラメータの値として、CreateVertexShader から返るハンドルまたは FVF コードを使用できる。この例では、最後の手順で呼び出される CreateVertexShader から返されるハンドルを使用する。

次の手順は、現在のレンダリング ステートを設定して頂点トゥイーニングを有効にし、トゥイーン係数を設定し、ストリーム ソースを設定することである。次のコードでは、IDirect3DDevice8::SetRenderState および IDirect3DDevice8::SetStreamSource を使用してこの手順を実行している。

m_d3dDevice->SetRenderState( D3DRS_VERTEXBLEND, D3DVBF_TWEENING );
m_d3dDevice->SetRenderState( D3DRS_TWEENFACTOR, *(DWORD*) &TweenFactor );
m_d3dDevice->SetStreamSource( 0 ,vb, 12*sizeof(float));

現在の頂点シェーダに対して複数のストリームを指定した場合は、トゥイーニング エフェクトに使用されるストリームごとに SetStreamSource を呼び出す必要がある。この時点で、頂点トゥイーニングが有効になる。レンダリング関数を呼び出すと、自動的に頂点トゥイーニングが適用される。


頂点シェーダによるトゥイーニング

頂点シェーダによるトゥイーニングを使用するコードは、固定機能によるトゥイーニングのコードとよく似ている。唯一違う点は、次に示すように IDirect3DDevice8::CreateVertexShader 呼び出しだけである。

m_d3dDevice->CreateVertexShader( decl, &vsFunction, &handle, 0 );

CreateVertexShader の第 2 パラメータは、頂点シェーダ関数のトークン配列へのポインタである。この関数は、以下の関数のいずれかを呼び出して作成することもできる。

  • D3DXAssembleShader
  • D3DXAssembleShaderFromFileA
  • D3DXAssembleShaderFromFileW

次のサンプル コードでは、AppTween.vsh ファイルから頂点シェーダを組み立てる。

D3DXAssembleShaderFromFile( "AppTween.vsh", 0, NULL, &vsFunction, NULL );

頂点シェーダ関数の作成の詳細については、「頂点シェーダ関数」を参照すること。


カラー ライティング

D3DLIGHT8 構造体 (Diffuse、Specular、Ambient) の色に関連するメンバは、D3DCOLORVALUE 構造体である。これらの構造体で定義する色は、一般には 0.0 ～ 1.0 の範囲の RGBA 値であり、0.0 が黒に相当する。たいていは光色がこの範囲になるようにするが、特殊効果をねらうときには、この範囲外の値を使用することもできる。たとえば、大きな値の色を設定して、シーンを台なしにするほど強い光を作ることができる。また、色を負の値に設定して、暗色光を作ることができる。暗い光は、シーンで劇的な影を強めたりその他のエフェクトに有用である。


DirectX Graphics の高度なトピック

ここでは、Microsoft® Direct3D® および Direct3DX API の高度な使い方について説明する。ここでの内容は、「DirectX Graphics の使い方」の内容より詳しい。

説明するトピックは、次のとおりである。

  • エフェクトとテクニック
  • 高次プリミティブ
  • 行列スタック
  • ピクセル シェーダ
  • ポイント スプライト
  • 頂点シェーダ
  • X ファイル


エフェクトとテクニック

ここでは、エフェクトとテクニックについて説明し、アプリケーション内での使用方法を解説する。説明するトピックは、次のとおりである。

  • エフェクトとテクニックについて
  • エフェクト ファイルの構成要素
  • エフェクトとテクニックの使い方


エフェクトとテクニックについて

Microsoft® Direct3D® のエフェクトを使うと、アプリケーションで 1 つのエフェクトに対して多数の異なるテクニックを定義できる。各エフェクトには 1 つ以上のテクニックがあり、そのエフェクトのレンダリングを制御する。各テクニックでは、現在のデバイスがそのテクニックをサポートしているかどうかが確認される。現在のデバイスがテクニックをサポートしていない場合は、別のテクニックを使用できる。

レンダリングするエフェクトの複雑さの制御には、別のテクニックを使用できる。たとえば、泉にさざ波が立ち、光を反射している場合を考える。1 つのテクニックを使って、複数のテクスチャとライティングがあるシーン全体を 1 つのパスでレンダリングすると同時に、別のテクニックを使って、マルチパス レンダリングを行うことができる。このような操作が行えるので、シングルパス レンダリングをサポートしていないビデオ カードでもエフェクトをレンダリングすることができる。

また、細部をどのくらい細かく表現するかに基づいて、エフェクトを調整できる。遠方に表示されるエフェクトにはより単純なテクニックを使うことで、複雑なテクニックをレンダリングする際に発生するコンピュータのオーバーヘッドを減らすことができる。

エフェクトを使う利点はほかにもあり、ソース アプリケーションを再コンパイルすることなく、エフェクト ファイルを変更することができる。このため、最新のビデオ カードを最大限に利用する製品をリリースできる。また、今後のビデオ カードを利用できるように、エフェクト ファイルを更新することも可能である。


エフェクト ファイルの構成要素

エフェクト ファイルは、使用するテクニックを定義する。エフェクト ファイルの定義は、基本的には 1 つまたは複数の宣言で始まり、その後にエフェクトの各テクニックの定義を続ける。次に示すサンプルは、2 つのテクスチャおよび 2 つのテクニックを定義するエフェクト ファイルである。

エフェクト ファイルは、エフェクトに使用する 2 つのテクスチャの宣言で始まっている。

texture tex0; // 1 番目のテクスチャ
texture tex1; // 2 番目のテクスチャ

1 番目のテクスチャでは、1 つのパスを使ってシーンをレンダリングする。

technique t0
{
    pass p0
    {
        Texture[0] = <tex0>;
        Texture[1] = <tex1>;

        ColorOp[0] = SelectArg1;
        ColorArg1[0] = Texture;

        ColorOp[1] = Add;
        ColorArg1[0] = Texture;
        ColorArg2[0] = Current;

        ColorOp[2] = Disable;
    }
}

2 番目のテクニックでは、複数のパスを使ってシーンをレンダリングする。このテクニックは、現在のデバイスが複数のテクスチャに対するシングルパス レンダリングをサポートしていない場合に使う。

technique t1
{
    pass p0
    {
        Texture[0] = <tex0>;

        ColorOp[0] = SelectArg1;
        ColorArg1[0] = Texture;
        ColorOp[1] = Disable;
    }

    pass p1
    {
        AlphaBlendEnable = True;
        SrcBlend = One;
        DestBlend = One;

        Texture[1] = <tex1>;

        ColorOp[1] = SelectArg1;
        ColorArg1[1] = Texture;
        ColorOp[1] = Disable;
    }
}

このエフェクト ファイルにより、デバイスが 2 つのテクスチャに対するシングルパス レンダリングをサポートしていない場合には、複数のパスを使ってテクスチャをレンダリングできる。エフェクト ファイルの詳細については、「エフェクト ファイル形式」を参照すること。


エフェクトとテクニックの使い方

ここでは、アプリケーションでのエフェクトとテクニックの作成方法および使用方法について説明する。

  • エフェクトの作成
  • テクニックの妥当性確認
  • テクニックを使用したレンダリング
  • エフェクトとテクニックの記述の読み出し
  • エフェクト ファイルのサンプル


エフェクトの作成

エフェクトを作成する最初の手順は、エフェクトのコンパイルである。次の関数を使って、エフェクトをコンパイルできる。

  • D3DXCompileEffect
  • D3DXCompileEffectFromFileA
  • D3DXCompileEffectFromFileW

次のサンプル コードでは、D3DXCompileEffectFromFileA 関数を使って、ファイル Water.sha に定義されたエフェクトをロードしてコンパイルしている。

LPD3DXBUFFER pCompiledEffect;
D3DXCompileEffectFromFile( "Water.sha", &pCompiledEffect, NULL );

D3DXCompileEffectFromFileA の 1 番目のパラメータは、エフェクトが定義されたファイルを指定する ANSI 文字列へのポインタである。2 番目のパラメータは、ID3DXBuffer インターフェイスへのポインタのアドレスである。このバッファには、コンパイルされたエフェクトが格納される。D3DXCompileEffectFromFileA の最後のパラメータは、ID3DXBuffer インターフェイスへのポインタのアドレスである。このバッファには、返された ASCII エラー メッセージが格納される。この例では、エラーを無視し、このパラメータに NULL を設定している。

エフェクトをコンパイルした後は、次の例に示すように、D3DXCreateEffect 関数を使って ID3DXEffect インターフェイスへのポインタを取得する。

ID3DXEffect * pEffect;
D3DXCreateEffect( g_d3dDevice, pCompiledEffect->GetBufferPointer(),
                  pCompiledEffect->GetBufferSize(), 0, &pEffect);
pCompiledEffect->Release();

この関数が成功すると、pEffect に ID3DXEffect インターフェイスへの有効なポインタが格納される。コンパイル済みのエフェクトを格納した ID3DXBuffer によって終了した後、必ず IUnknown::Release メソッドを呼び出してメモリ リークを防ぐ。


テクニックの妥当性確認

テクニックを使う前に、デバイスがそのテクニックをサポートしていることを確認する。テクニックの妥当性を確認するには、次のサンプル コードに示すように、ID3DXTechnique::Validate メソッドを使う。

LPD3DXTECHNIQUE pTechnique;
pEffect->GetTechnique(0, &pTechnique);
if ( pTechnique->Validate() != D3D_OK)
    // テクニックが現在のデバイスでは有効でない。

注 テクニックを使う前に、その妥当性を確認することを強く勧める。無効なテクニックを使うと、不明なエフェクトが含まれる。


テクニックを使用したレンダリング

次の例は、アプリケーションでのテクニックのレンダリング方法を示している。有効なテクニックを検出した後、次のサンプル コードに示すように、アプリケーションでは ID3DXTechnique::Begin メソッドを呼び出して、テクニックの適用を開始する。

UINT uPasses;
pTechnique->Begin(&uPasses);

Begin の唯一のパラメータは、符号なし整数のアドレスである。Begin が呼び出された後、この値にはテクニックで使用されるパスの数が格納される。

次の手順として、各パスの個別のレンダリングを行う。パスをレンダリングするには、ID3DXTechnique::Pass メソッドを呼び出す。次のサンプル コードでは、ループを使って、テクニックに必要なすべてのパスをレンダリングしている。

for(UINT uPass = 0; uPass < uPasses; uPass++)
{
    pTechnique->Pass(uPass);
    g_d3dDevice->SetStreamSource( 0, pvbVertices, sizeof(WATER_VERTEX) );
    g_d3dDevice->SetIndices( pIB, 0 );
    g_d3dDevice->DrawIndexedPrimitive( D3DPT_TRIANGLESTRIP, 0,
                                       uVertices, 0, uIndices -2 );
}

Pass を呼び出すことで、シーンのレンダリングに必要なステートを設定している。

注 ID3DXTechnique::Begin は、IDirect3DDevice8::BeginScene / IDirect3DDevice8::EndScene ブロック内で呼び出す必要がある。


エフェクトとテクニックの記述の読み出し

エフェクトに関する情報を読み出すには、ID3DXEffect::GetDesc メソッドを使って、パラメータに D3DXEFFECT_DESC 構造体を渡す。D3DXEFFECT_DESC 構造体には、エフェクトを記述するメンバが含まれる。

テクニックに関する情報を読み出すには、ID3DXTechnique::GetDesc メソッドを使って、パラメータに D3DXTECHNIQUE_DESC 構造体を渡す。D3DXTECHNIQUE_DESC 構造体には、テクニックを記述するメンバが含まれる。


エフェクト ファイルのサンプル

次のエフェクト ファイルは、Water サンプルに使用するものである。

このファイルには、最初にこのエフェクトで使用する 2 つの行列、3 つのテクスチャ、および頂点シェーダが宣言されている。

matrix mID;     // 単位トランスフォーム
matrix mENV;    // 環境マップ トランスフォーム

texture tFLR;   // フロア テクスチャ
texture tCAU;   // コースティック テクスチャ
texture tENV;   // キューブ環境マップ

vertexshader vs =  decl { fvf xyz | normal | diffuse | tex1; };

最初のテクニックでは、フロア テクスチャとコースティック テクスチャを使って、水のシーンをレンダリングする。水とフロアには光が反射する。このテクニックでは、単一のパスと 4 つのテクスチャ ステージ ステートを使用する。

technique T0
{
    vertexshader = <vs>;

    pass P0
    {
        Lighting       = True;
        SpecularEnable = True;

        // ステージ 0
        ColorOp[0]   = SelectArg1;
        ColorArg1[0] = Texture;
        AlphaOp[0]   = SelectArg2;
        AlphaArg2[0] = Current;

        MinFilter[0] = Linear;
        MagFilter[0] = Linear;
        MipFilter[0] = Point;

        Texture[0] = <tFLR>;
        TextureTransform[0] = <mID>;
        TextureTransformFlags[0] = Count2;

        // ステージ 1
        ColorOp[1]   = Add;
        ColorArg1[1] = Texture;
        ColorArg2[1] = Current;
        AlphaOp[1]   = SelectArg2;
        AlphaArg2[1] = Current;

        MinFilter[1] = Linear;
        MagFilter[1] = Linear;
        MipFilter[1] = Point;

        Texture[1] = <tCAU>;
        TextureTransform[1] = <mID>;
        TextureTransformFlags[1] = Count2;

        // ステージ 2
        ColorOp[2]   = BlendCurrentAlpha;
        ColorArg1[2] = Texture;
        ColorArg2[2] = Current;
        AlphaOp[2]   = Disable;

        MinFilter[2] = Linear;
        MagFilter[2] = Linear;
        MipFilter[2] = Point;

        Texture[2] = <tENV>;
        TextureTransform[2] = <mENV>;
        TextureTransformFlags[2] = Count3;
        TexCoordIndex[2] = CameraSpaceReflectionVector;

        // ステージ 3
        ColorOp[3] = Disable;
        AlphaOp[3] = Disable;
    }
}

2 番目のテクニックでは、フロア テクスチャとコースティック テクスチャを使って、水のシーンレンダリングする。フロアと水には光が反射する。このテクニックでは、2 つのパスを使ってシーンをレンダリングする。

technique T1
{
    vertexshader = <vs>;

    pass P0
    {
        // ステージ 0
        ColorOp[0]   = SelectArg1;
        ColorArg1[0] = Texture;
        AlphaOp[0]   = Disable;

        MinFilter[0] = Linear;
        MagFilter[0] = Linear;
        MipFilter[0] = Point;

        Texture[0] = <tFLR>;
        TextureTransform[0] = <mID>;
        TextureTransformFlags[0] = Count2;

        // ステージ 1
        ColorOp[1]   = Add;
        ColorArg1[1] = Texture;
        ColorArg2[1] = Current;
        AlphaOp[1]   = Disable;

        MinFilter[1] = Linear;
        MagFilter[1] = Linear;
        MipFilter[1] = Point;

        Texture[1] = <tCAU>;
        TextureTransform[1] = <mID>;
        TextureTransformFlags[1] = Count2;

        // ステージ 2
        ColorOp[2] = Disable;
        AlphaOp[2] = Disable;
    }

    pass P1
    {
        SrcBlend  = One;
        DestBlend = InvSrcAlpha;

        Lighting         = True;
        SpecularEnable   = True;
        AlphaBlendEnable = True;

        // ステージ 0
        ColorOp[0]   = BlendDiffuseAlpha;
        ColorArg1[0] = Texture;
        ColorArg2[0] = Diffuse;
        AlphaOp[0]   = SelectArg2;
        AlphaArg2[0] = Diffuse;

        MinFilter[0] = Linear;
        MagFilter[0] = Linear;
        MipFilter[0] = Point;

        Texture[0] = <tENV>;
        TextureTransform[0] = <mENV>;
        TextureTransformFlags[0] = Count3;
        TexCoordIndex[0] = CameraSpaceReflectionVector;

        // ステージ 1
        ColorOp[1] = Disable;
        AlphaOp[1] = Disable;
    }
}

3 番目のテクニックでは、フロア テクスチャとコースティック テクスチャを使って、水のシーンをレンダリングする。水面には光が反射する。このエフェクトでは、3 つのパスを使ってシーンをレンダリングする。

technique T2
{
    vertexshader = <vs>;

    pass P0
    {
        // ステージ 0
        ColorOp[0]   = SelectArg1;
        ColorArg1[0] = Texture;
        AlphaOp[0]   = Disable;

        MinFilter[0] = Linear;
        MagFilter[0] = Linear;
        MipFilter[0] = Point;

        Texture[0] = <tFLR>;
        TextureTransform[0] = <mID>;
        TextureTransformFlags[0] = Count2;

        // ステージ 1
        ColorOp[1] = Disable;
        AlphaOp[1] = Disable;
    }

    pass P1
    {
        SrcBlend  = One;
        DestBlend = One;

        Lighting         = False;
        SpecularEnable   = True;
        AlphaBlendEnable = True;

        // ステージ 0
        ColorOp[0]   = Add;
        ColorArg1[0] = Texture;
        ColorArg2[0] = Current;
        AlphaOp[0]   = Disable;

        MinFilter[0] = Linear;
        MagFilter[0] = Linear;
        MipFilter[0] = Point;

        Texture[0] = <tCAU>;
        TextureTransform[0] = <mID>;
        TextureTransformFlags[0] = Count2;

        // ステージ 1
        ColorOp[1] = Disable;
        AlphaOp[1] = Disable;
    }

    pass P2
    {
        SrcBlend  = One;
        DestBlend = InvSrcAlpha;

        Lighting         = True;
        SpecularEnable   = True;
        AlphaBlendEnable = True;

        // ステージ 0
        ColorOp[0]   = BlendDiffuseAlpha;
        ColorArg1[0] = Texture;
        ColorArg2[0] = Diffuse;
        AlphaOp[0]   = SelectArg2;
        AlphaArg2[0] = Diffuse;

        MinFilter[0] = Linear;
        MagFilter[0] = Linear;
        MipFilter[0] = Point;

        Texture[0] = <tENV>;
        TextureTransform[0] = <mENV>;
        TextureTransformFlags[0] = Count3;
        TexCoordIndex[0] = CameraSpaceReflectionVector;

        // ステージ 1
        ColorOp[1] = Disable;
        AlphaOp[1] = Disable;
    }
}

4 番目のテクニックでは、フロア テクスチャとコースティック テクスチャを使って、水のシーンをレンダリングする。このエフェクトでは、単一のパスを使ってシーンをレンダリングする。

technique T3
{
    vertexshader = <vs>;

    pass P0
    {
        Lighting       = True;
        SpecularEnable = True;

        // ステージ 0
        ColorOp[0]   = SelectArg1;
        ColorArg1[0] = Texture;
        AlphaOp[0]   = Disable;

        MinFilter[0] = Linear;
        MagFilter[0] = Linear;
        MipFilter[0] = Point;

        Texture[0]   = <tFLR>;

        // ステージ 1
        ColorOp[1]   = Add;
        ColorArg1[1] = Texture;
        ColorArg2[1] = Current;
        AlphaOp[1]   = Disable;

        MinFilter[1] = Linear;
        MagFilter[1] = Linear;
        MipFilter[1] = Point;

        Texture[1]   = <tCAU>;

        // ステージ 2
        ColorOp[2]   = Disable;
        AlphaOp[2]   = Disable;
    }
}

5 番目のテクニックでは、フロア テクスチャとコースティック テクスチャを使って、水のシーンをレンダリングする。このテクニックでは反射は使用しない。このエフェクトでは、2 つのパスを使ってシーンをレンダリングする。

technique T4
{
    vertexshader = <vs>;

    pass P0
    {
        // ステージ 0
        ColorOp[0]   = SelectArg1;
        ColorArg1[0] = Texture;
        ColorArg2[0] = Diffuse;

        AlphaOp[0]   = SelectArg1;
        AlphaArg1[0] = Texture;
        AlphaArg2[0] = Diffuse;

        MinFilter[0] = Linear;
        MagFilter[0] = Linear;
        MipFilter[0] = Point;

        Texture[0]   = <tFLR>;

        // ステージ 1
        ColorOp[1]   = Disable;
        AlphaOp[1]   = Disable;
    }

    pass P1
    {
        SrcBlend  = One;
        DestBlend = One;

        Lighting         = True;
        SpecularEnable   = True;
        AlphaBlendEnable = True;

        // ステージ 0
        ColorOp[0]   = SelectArg1;
        ColorArg1[0] = Texture;
        ColorArg2[0] = Current;

        AlphaOp[0]   = SelectArg1;
        AlphaArg1[0] = Texture;
        AlphaArg2[0] = Current;

        MinFilter[0] = Linear;
        MagFilter[0] = Linear;
        MipFilter[0] = Point;

        Texture[0]   = <tCAU>;

        // ステージ 1
        ColorOp[1]   = Disable;
        AlphaOp[1]   = Disable;
    }
}

6 番目および最後のテクニックでは、フロア テクスチャだけを使って、水のシーンをレンダリングする。このテクニックでは反射は使用しない。このエフェクトでは、単一のパスを使ってシーンをレンダリングする。

technique T5
{
    vertexshader = <vs>;

    pass P0
    {
        Lighting       = True;
        SpecularEnable = True;

        // ステージ 0
        ColorOp[0]   = SelectArg1;
        ColorArg1[0] = Texture;
        ColorArg2[0] = Current;

        AlphaOp[0]   = SelectArg1;
        AlphaArg1[0] = Texture;
        AlphaArg2[0] = Current;

        MinFilter[0] = Linear;
        MagFilter[0] = Linear;
        MipFilter[0] = None;

        Texture[0]   = <tFLR>;

        // ステージ 1
        ColorOp[1]   = Disable;
        AlphaOp[1]   = Disable;
    }
}


高次プリミティブ

ここでは、高次プリミティブについて説明し、アプリケーション内での使用方法を解説する。説明するトピックは、次のとおりである。

  • 高次プリミティブとは
  • 分割度増加による品質向上
  • スプラインベースのツールからの直接マッピング
  • 高次プリミティブの使い方


高次プリミティブとは

Microsoft® Direct3D® for Microsoft DirectX® 8.0 では、ポイント、ライン、三角形、およびグリッド プリミティブをサポートしている。これらは、線形補間を超える高次補間をサポートするために拡張された。三角形や線は空間的な広がりがあるにもかかわらず、これまでは線形補間を使ってレンダリングされていた。DirectX 8.0 では、Direct3D が、高次 (最大 5 次までの) 補間を使用するこれらのプリミティブ タイプのレンダリングをサポートしている。また、新しい四辺形プリミティブ タイプがサポートされている。この新しいタイプも高次補間を使ってレンダリングされる。これらの機能は、本来はアニメーションやキャラクタのレンダリングの必要性から追加された。しかし、地形や水面といったサーフェスにも応用できる。

高次プリミティブは、リスト、ストライプ、ファン、またはインデックス化されたメッシュとしてアプリケーション プログラミング インターフェイス (API) に転送されるときに、高次補間をサポートする。これは、頂点自体にエンコードされた追加情報を使って実行される。たとえば、三次補間を有効にするために、法線ベクトルを使って頂点位置の接面を定義することができる。ほとんどの実装では、平面の三角形へのテッセレーションによって高次補間をサポートする。テッセレーションのステップは、論理的に頂点シェーダ ステージの前に適用される。頂点シェーダ API は入力データにセマンティクスを適用しないため、座標位置およびオプションで法線ベクトルを表す頂点ストリーム成分を識別するための特別なメカニズムが用意されている。その他すべての成分はそれ相応に補間される。


分割度増加による品質向上

現在のプリミティブは、滑らかなサーフェスを表現するのに最適なものとは言えない。曲面のレンダリングでは、三次多項式などの高次補間テクニックを使うと、より正確な計算を行うことができる。これにより、シルエットの縁やスペキュラ サーフェス ライティングに現れる不自然な効果を削減または解消し、よりリアルな表現が可能になる。さらに、チップ上でテッセレーションが行われる際、テッセレートされた三角形は、バスの帯域幅に影響を与えない。多くの場合、少量のテッセレーションにより、パフォーマンスにあまり影響を与えることなく、イメージの品質を向上させることができる。

Microsoft® Direct3D® for Microsoft DirectX® 8.0 では、既存のポリゴン指向のツールやアート パイプラインで作成されたコンテンツの分割度を、簡単な方法で向上させることができる。アプリケーションがすべきことは、必要なレベルのテッセレーションを提供することと、法線ベクトルを含む標準的な三角形構文を使ってデータを転送することだけである。


スプラインベースのツールからの直接マッピング

現在、多くのオーサリング ツールが高次プリミティブをサポートしており、通常の平面三角形メッシュよりも強力なモデリング処理を実現している。このようなツールは、妥当な数のパッチが生成されるような効率的な使い方をすれば、アプリケーション プログラミング インターフェイス (API) で直接レンダリングできるようなコンテンツを作成できる。この要件を満たすため、入ってくる頂点データ ストリームを制御ポイントの 2D 配列として解釈し、必要な解像度にテッセレートする、新しいエントリ ポイントが追加された。


高次プリミティブの使い方

ここでは、アプリケーションで高次プリミティブを使用する方法について説明する。

  • 高次プリミティブ サポートの確認
  • パッチの描画


高次プリミティブ サポートの確認

D3DCAPS8 の DevCaps メンバを照会して、高次プリミティブに関する処理のサポート レベルを確認することができる。次の表は、Microsoft® DirectX® 8.0での高次プリミティブに関連するデバイス機能を示している。

デバイス機能 | 説明
D3DDEVCAPS_NPATCHES | デバイスは、N パッチをサポートしている。
D3DDEVCAPS_QUINTICRTPATCHES | デバイスは、5 次ベジェおよび B スプラインをサポートしている。
D3DDEVCAPS_RTPATCHES | デバイスは、四角形および三角形 (RT) パッチをサポートしている。
D3DDEVCAPS_RTPATCHHANDLEZERO | RT パッチは、ハンドル ゼロを使うと効率的に描画できる。


パッチの描画

Microsoft® DirectX® 8.0 では、2 種類の高次プリミティブ、つまりパッチがサポートされている。これらは N パッチおよび Rect/Tri パッチと呼ばれる。N パッチは、D3DRS_PATCHSEGMENTS に 1.0 より大きな値を設定することで、三角形レンダリング呼び出しを使ってレンダリングできる。Rect/Tri パッチは、次の明示的なエントリ ポイントを使ってレンダリングする必要がある。

次のメソッドを使って、Microsoft Direct3D® for DirectX でパッチを描画できる。

  • IDirect3DDevice8::DrawRectPatch
  • IDirect3DDevice8::DrawTriPatch

DrawRectPatch は、現在設定されているストリームを使って、pRectPatchInfo パラメータで指定された四角形高次パッチを描画する。Handle パラメータは、パッチとハンドルを関連付けるために使用される。このため、次にパッチが描画される際は、pRectPatchInfo を指定し直す必要がない。これにより、順方向差異係数またはその他の情報を事前に計算してキャッシュすることができ、その結果、同じハンドルを使ったその後の DrawRectPatch への呼び出しが効率的に実行される。

静的パッチについては、アプリケーションが頂点シェーダと適切なストリームを設定し、pRectPatchInfo パラメータ内にパッチ情報を提供し、ハンドルを指定することで、Direct3D が情報をキャプチャしキャッシュできるようにされている。アプリケーションはその後 pRectPatchInfo が NULL に設定された状態で DrawRectPatch を呼び出すことにより、パッチを効率的に描画できる。キャッシュされたパッチを描画するときは、現在設定されているストリームは無視される。ただし、pNumSegs に新しい値を設定することで、キャッシュされた pNumSegs を上書きすることもできる。また、キャッシュされたパッチをレンダリングする場合は、そのパッチがキャッシュされたときと同じ頂点シェーダを設定する必要がある。

動的パッチについては、パッチのレンダリングごとにパッチ データが変化するため、情報をキャッシュすることは効率的ではない。アプリケーションは、Handle を 0 に設定することで、この情報を Direct3D に伝えることができる。この場合、Direct3D は、現在設定されているストリームおよび pNumSegs 値を使ってパッチを描画し、情報のキャッシュを行わない。Handle を 0 に設定した状態で pPatch を NULL に設定すると無効になる。

同じハンドルに pRectPatchInfo を指定し直すことで、アプリケーションは前回キャッシュした情報を上書きすることができる。

pNumSegs が NULL に設定されている場合は、テッセレータは D3DRS_PATCHSEGMENTS を使ってテッセレーションの量を制御する。この場合は、当然、すべての辺に同じテッセレーションが使用される。N パッチには特別なメソッドはない。テッセレーションは、D3DRS_PATCHSEGMENTS によって制御される。法線を指定する必要がある。

DrawTriPatch は DrawRectPatch に似ているが、三角形高次パッチを描画する点が異なる。


行列スタック

Direct3DX ユーティリティ ライブラリは、COM オブジェクトを使った行列スタックを提供している。

説明するトピックは、次のとおりである。

  • 行列スタックとは
  • シーンの階層の実装


行列スタックとは

Direct3DX ユーティリティ ライブラリは、ID3DXMatrixStack インターフェイスを備えている。このインターフェイスは、行列を行列スタックにプッシュしたり、行列スタックからポップ オフしたりするためのメカニズムを提供する。行列スタックを実装すると、トランスフォーム階層内を移動する際に、行列を効率よく管理することができる。

Direct3DX ユーティリティ ライブラリは、行列スタックを使ってトランスフォームを行列として格納する。ID3DXMatrixStack インターフェイスの各種メソッドを使って、現在の行列 (行列の最上部にある行列) を操作することができる。カレント行列をクリアするには、ID3DXMatrixStack::LoadIdentity メソッドを使用する。特定の行列をカレント トランスフォーム行列としてロードするよう明示的に指定するには、ID3DXMatrixStack::LoadMatrix メソッドを使用する。その後 ID3DXMatrixStack::MultMatrix メソッドまたは ID3DXMatrixStack::MultMatrixLocal メソッドを呼び出して、現在の行列を指定した行列で乗算することができる。

ID3DXMatrixStack::Pop メソッドを使用すると、前のトランスフォーム行列に戻り、ID3DXMatrixStack::Push メソッドを使用すると、スタックにトランスフォーム行列が追加される。

行列スタック上の個々の行列は、Direct3DX ユーティリティ ライブラリの D3DXMATRIX 構造体によって定義された 4 × 4 同次行列として表現される。


シーンの階層の実装

一連の単純なオブジェクトから複雑なオブジェクトが構築される階層モデルは、行列スタックを使用することで簡単に構築できるようになる。

シーンやトランスフォームでは、階層は通常ツリー データ構造として表現される。ツリー データ構造内の各ノードには行列が含まれる。特定の行列は、ノードの親からノードへの座標系の変化を表す。たとえば、人間の腕をモデリングしている場合、次のような階層を実装する場合がある。

この階層では、Body 行列が胴体をワールド内に配置する。UpperArm 行列には肩の回転、LowerArm 行列にはひじの回転、Hand 行列には手首の回転がそれぞれ含まれる。手がどこでワールドと関連するかを決定するには、Body から Hand までの行列をすべて乗算する。

前の階層は、各ノードに子が 1 つずつしかなかったので、非常に単純であった。より詳細に手をモデリングする場合は、指を追加することになる。5 本の指はすべて、Hand の子として階層に追加できる。

腕の完全なグラフ内を深度優先の順序 (単一のパスをできるだけ深く移動してから次のパスに移る) で移動する場合は、分断された一連のレンダリングを実行することになる。たとえば、手と指をレンダリングする場合は、次の手順を実行する。

  1. Hand 行列を行列スタックにプッシュする。
  2. 手を描画する。
  3. Thumb 行列を行列スタックにプッシュする。
  4. 親指を描画する。
  5. Thumb 行列をスタックからポップ オフする。
  6. Finger 1 行列を行列スタックにプッシュする。
  7. 最初の指を描画する。
  8. Finger 1 行列をスタックからポップ オフする。
  9. Finger 2 行列を行列スタックにプッシュする。すべての指がレンダリングされるまで、この手順を繰り返す。

指のレンダリングが終わったら、Hand 行列をスタックからポップ オフする。

次の例を使って、この基本的なプロセスをコード内で実行できる。ツリー データ構造の深度優先検索中にノードが見つかったら、行列を行列スタックの最上部にプッシュする。

MatrixStack->Push();
MatrixStack->MultMatrix(pNode->matrix);

ノードの操作が終了したら、行列を行列スタックの最上部からポップ オフする。

MatrixStack->Pop();

つまり、スタックの最上部にある行列は、常に現在のノードのワールド トランスフォームを表す。このため、各ノードの描画前に、Microsoft® Direct3D® 行列を設定する必要がある。

pD3DDevice->SetTransform(D3DTS_WORLDMATRIX(0), *MatrixStack->GetTop());

Direct3DX 行列スタックで実行できる各種メソッドに関する詳細は、「ID3DXMatrixStack」を参照すること。


ピクセル シェーダ

ここでは、Microsoft® DirectX® 8.0 でサポートされるピクセル処理の最新機能であるピクセル シェーダについて解説し、Microsoft Direct3D® アプリケーションでの使用方法を説明する。説明するトピックは、次のとおりである

  • ピクセル シェーダとは
  • ピクセル シェーダの基本
  • ピクセル シェーダの適用範囲
  • ピクセル シェーダのデータ フロー
  • ピクセル シェーダの使い方
  • ピクセル シェーダの例

このドキュメントで使用されるすべてのピクセル シェーダ コードおよび構文は、Direct3DX ピクセル シェーダ アセンブラに基づくもので、互換性がある。このセクションを読む前に、「ピクセル シェーダ アセンブラ リファレンス」を読み、ピクセル シェーダ アセンブラについての知識を取得しておく必要がある。


ピクセル シェーダとは

次の例は、ピクセル シェーダの簡単な使用方法と、Direct3DX ピクセル シェーダ アセンブラが解釈可能な構文を示している。

ps.1.0          // DirectX8 バージョン。
tex t0          // テクスチャを宣言する。
tex t1          // ライト マップを宣言する。

mov r0, t0
mul r0, r0, t1  // ライト マップを乗算する。
mul r0, r0, v0  // ディフューズを乗算する。
add r0, r0, v1  // スペキュラを追加する。

このピクセル シェーダは、ライト マップ、ディフューズ色、およびスペキュラの追加と共にベース テクスチャを宣言している。

ピクセル シェーダは、色およびアルファ ブレンディング処理およびテクスチャ アドレッシング処理を制御する。Microsoft® Direct3D® for Microsoft DirectX® 8.0 は、ピクセル処理およびテクスチャ ブレンディング処理を定義するためのプロシージャル パラダイムを定義する。このモデルには、仮想マシン アーキテクチャの定義、およびその動作を定義する一連の命令と修飾子が含まれる。このパラダイムは、プロセッサベースの実装である必要はない。

ピクセル シェーダは、次の方法で、DirectX 6.0 および 7.0 のマルチテクスチャ機能を拡張および標準化する。

  • 一般的な読み書きレジスタのセットが追加されたため、D3DTA_CURRENT だけを使用するシリアル カスケードによるサポートよりも柔軟な式を使用できる。これにより、個別の結果レジスタ引数の指定が各ステージで必要となる。
  • D3DTOP_MODULATE2X および D3DTOP_MODULATE4X テクスチャ処理が、どの命令に対しても適用できる個別の修飾子として分割された (両方は不可)。これにより、個別の D3DTOP_MODULATE および D3DTOP_MODULATE2X 処理の必要性がなくなった。
  • バイアス処理修飾子および非バイアス テクスチャ処理修飾子が適用可能になった (両方は不可)。これにより、個別の追加およびバイアス追加処理の必要性がなくなった。
  • 追加を乗算するためにオプションの 3 番目の引数が追加されたため、プロシージャル ピクセル シェーダが arg1 * arg2 + arg0 を実行できるようになっている。これにより、D3DTOP_MODULATEALPHA_ADDCOLOR および D3DTOP_MODULATECOLOR_ADDALPHA テクスチャ処理がなくなった。また、ブレンド処理にもオプションの 3 番目の引数が追加されたため、プロシージャル ピクセル シェーダは arg1 と arg2 の間のブレンド比率として arg0 を使用できるようになった。これにより、D3DTOP_BLENDDIFFUSEALPHA、D3DTOP_BLENDTEXTUREALPHA、D3DTOP_BLENDFACTORALPHA、D3DTOP_BLENDTEXTUREALPHAPM、および D3DTOP_BLENDCURRENTALPHA テクスチャ処理がなくなった。
  • カラー処理およびアルファ処理から、D3DTOP_BUMPENVMAP などのテクスチャ アドレス修正処理が発生し、特にテクスチャ アドレス上で処理を行うための 3 番目の処理タイプとして定義された。

このように拡張された柔軟性をより効率的にサポートするため、アプリケーション プログラミング インターフェイス (API) 構文が DWORD ペアから ASCII アセンブル コード構文に変更された。これにより、プロシージャル ピクセル シェーダによって提供される機能を公開することができる。

注 ピクセル シェーダを使用する場合、スペキュラの追加はレンダリング ステートによって特に制御されなくなり、必要に応じて実装するのはピクセル シェーダの役割となる。しかし、フォグ ブレンディングは固定機能構文によって適用される。

Direct3DX ピクセルシェーダ アセンブラの使用方法についての詳細は、「ピクセル シェーダ アセンブラ リファレンス」を参照すること。


ピクセル シェーダの基本

ここでは、ピクセル シェーダを使用するにあたって必要な基本的情報について説明する。

  • ピクセル シェーダの演算論理単位
  • ピクセル シェーダの命令のペア
  • ピクセル シェーダの処理順序
  • ピクセル シェーダのテクスチャ宣言
  • ピクセル シェーダのテクスチャ アドレッシング
  • ピクセル シェーダのライティング


ピクセル シェーダの演算論理単位

次の図は、ピクセル シェーダの演算論理単位 (ALU) を示している。


ピクセル シェーダの命令のペア

ピクセル シェーダを実行するプロセッサは、2 つのパラレル パイプラインを持っている。1 つはベクトル処理 (RGB) 用で、もう 1 つはスカラー処理 (アルファ) 用である。これらのパイプラインをパラレルで使用することにより、必要なクロック サイクルの合計数が削減され、プロセッサの利用効率とパフォーマンスが非常に向上する。これは、基本的にはピクセルの塗りつぶし速度に影響する。

出力マスクによって 2 つのパイプラインの割り当て方法に影響を与えることはできるが、明示的にペア設定の構文が使用されない限り、処理順序は不明確になる。次の表は、出力マスクおよび関連付けられたパイプを示している。

出力マスク | パイプ
.a | 処理はスカラー パイプにある。
.rgb | 処理はベクトル パイプにある。
.rgba | 処理はスカラー パイプとベクトル パイプの両方にある。これは既にペアと見なされている。

ペアの 2 番目の命令の先頭には + 記号が付けられている。

  mul r0.rgb, t0, v0    // 色成分は乗算。
+ add r0.a,   t0, v0    // ただし、アルファ成分は加算。

内積の命令は特別なケースである。これらはベクトル処理であり、常にベクトル パイプライン内で実行される。このため、スカラー パイプ内で異なる命令を指定しても、次のピクセル シェーダ コード例のようにペアにすることができる。

dp3 r0.rgb, t0, v0
mul r0.a,   t0, v0

ベクトル命令としての内積処理なしに、内積処理をスカラー命令として指定することはできない。


ピクセル シェーダの処理順序

ピクセルの命令と修飾子の処理順序は次のようになる。1) 入力または引数修飾子が適用される。2) 中心となる命令が実行される。3) 出力または命令修飾子が適用される。4) 出力書き込みマスクについて結果が書き込まれる。

入力または引数修飾子については、次のような順序になる。1) バイアスが適用される。2) スケーリングが適用される。3) 正負の反転または補足ステップが実行される。アルファ複製もこのステージで実行される。出力または命令修飾子の場合は、スケール/シフト演算子は彩度ステップよりも優先される。

最終的な処理順序は、次のようになる。

  1. 引数修飾子が適用される。
  2. 中心となる命令が実行される。
  3. 命令修飾子が適用される。
  4. 出力書き込みマスクが適用される。


ピクセル シェーダのテクスチャ宣言

テクスチャ宣言 (テクスチャ アドレッシング命令) は、カラー ブレンディングやアルファ ブレンディングなどの命令とは区別される、個別のピクセル シェーダ命令セットである。これらの命令は、ピクセル シェーダの先頭になければならず、また事前に定義された値しか使用できない。テクスチャ アドレッシング命令は、処理を実行することができる。たとえば、これらの命令を使って、サンプリング ステージがアドレスとして使用しているテクスチャ座標を修正したり、補正特殊効果を有効にしたりできる。

詳細については、「テクスチャ アドレッシング命令」を参照すること。


ピクセル シェーダのテクスチャ アドレッシング

次の図は、ピクセル シェーダのテクスチャ アドレッシングのメカニズムを示している。

テクスチャ処理と関連して、テクスチャ座標を使用し、4 つの入力テクスチャをサンプリングすることで、テクスチャ レジスタ t0、t1、t2、および t3 が結果として得られる。テクスチャ座標とテクスチャ レジスタのマッピングは、D3DTSS_TEXCOORDINDEX テクスチャ ステージ ステートによって制御される。デフォルトでは、すべてのテクスチャ ステージは座標セット 0 からテクスチャ座標を受け取る。命令は以前のテクスチャ レジスタからの結果しか使用できないため、適切な順序で配置する必要がある。

依存テクスチャを使用する場合は、任意のテクスチャを、それより大きい番号のテクスチャの座標補正に使用できる (t1 を使って t2 の座標を補正するなど)。

Direct3DX のピクセル シェーダ アセンブラは、テクスチャ アドレス演算子と修飾子の両方を提供する。詳細については、「ピクセル シェーダ アセンブラ リファレンス」を参照すること。

次のピクセル シェーダ コードは、ライティング ベースのテクスチャ上にバンプ環境マップをプログラミングしたテクスチャ アドレス シェーダを示している。

ps.1.0              // DirectX8 バージョン。
tex t0              // テクスチャを宣言する。
tex t1              // バンプ マップを宣言する。
texbem t3, t1       // 摂動、次に
                    // 環境マップをサンプリングする。
mul r0, v0, t0      // ディフューズを乗算する。
add r0, r0, t3      // バンプ スペキュラ環境マップを追加する。


ピクセル シェーダのライティング

次の図は、ピクセル シェーダのライティングのメカニズムを示している。

たとえば、3D バンプ環境マップの場合、法線マップをサンプリングし、テクスチャ座標を行として使ってポリゴン上に 3 × 3 行列演算を補間する。その後、ディフューズ輝度キューブ マップにトランスフォームおよびインデックスするか、またはスペキュラ環境キューブ マップに反射およびインデックスすることができる。前のパスからベースに適用する。


ピクセル シェーダの適用範囲

ピクセル シェーダは、Microsoft® DirectX® 6.0 および 7.0 のマルチテクスチャ アプリケーション プログラミング インターフェイス (API) で定義されているピクセル ブレンディング機能、特に D3DTSS_COLOROP、D3DTSS_COLORARG1、D3DTSS_COLORARG2、D3DTSS_ALPHAOP、D3DTSS_ALPHAARG1、および D3DTSS_ALPHAARG2 テクスチャ ステージ ステートによって定義される処理、および関連する引数と修飾子に完全に代わるものである。プロシージャル ピクセル シェーダが設定されると、これらのステートは無視される。

ピクセル シェーダの適用範囲についての詳細は、次の各トピックに記述されている。

  • ピクセル シェーダとテクスチャ ステージ ステート
  • ピクセル シェーダとテクスチャ サンプリング
  • シェーダ後のピクセル処理


ピクセル シェーダとテクスチャ ステージ ステート

ピクセル シェーダが処理されているとき、次のテクスチャ ステージ ステートは引き続き保持される。

  • D3DTSS_ADDRESSU
  • D3DTSS_ADDRESSV
  • D3DTSS_ADDRESSW
  • D3DTSS_BUMPENVMAT00
  • D3DTSS_BUMPENVMAT01
  • D3DTSS_BUMPENVMAT10
  • D3DTSS_BUMPENVMAT11
  • D3DTSS_BORDERCOLOR
  • D3DTSS_MAGFILTER
  • D3DTSS_MINFILTER
  • D3DTSS_MIPFILTER
  • D3DTSS_MIPMAPLODBIAS
  • D3DTSS_MAXMIPLEVEL
  • D3DTSS_MAXANISOTROPY
  • D3DTSS_BUMPENVLSCALE
  • D3DTSS_BUMPENVLOFFSET
  • D3DTSS_TEXCOORDINDEX
  • D3DTSS_TEXTURETRANSFORMFLAGS

これらのテクスチャ ステージ ステートはピクセル シェーダの一部ではないため、シェーダのコンパイル時には使用できず、ドライバはそれらについていかなる想定もできない。たとえば、ドライバはその時点では、バイリニア フィルタリングとトライリニア フィルタリングを区別できない。アプリケーションは、現在バインドされているシェーダを再生成しなくても、これらのステートを自由に変更できる。

さらに、使用されるイメージ データを変更するために IDirect3DDevice8::SetTexture メソッドを呼び出しても、ピクセル シェーダは無効にならないため、ビット深度に関するテクスチャの形式は自由に変更できる。D3DFMT_A8L8 や D3DFMT_V8U8 といった 2 チャネル テクスチャ フォーマットでの SetTexture の呼び出しも、3 番目のチャネルが 0 に設定されているかのように、引き続き使用できる。


ピクセル シェーダとテクスチャ サンプリング

縮小、拡大、ミップ フィルタリング、およびラップ アドレッシング モードについては、テクスチャ サンプリングおよびフィルタリング処理は標準テクスチャ ステージ ステートによって制御される。詳細については、「テクスチャ ステージ ステート」を参照すること。

この情報はシェーダのコンパイル時にドライバに提供されないため、このステートが変わってもシェーダは処理を続行できる。テクスチャ タイプ (テクスチャ、キューブ テクスチャ、またはボリューム テクスチャ) は、シェーダの構文に明示的に指定する。アプリケーションは、シェーダの実行中に正しいタイプのテクスチャだけを設定しなければならない。シェーダの実行中に間違ったタイプのテクスチャを設定すると、予期しない結果が発生することがある。


シェーダ後のピクセル処理

Microsoft® DirectX® 8.0 では、フォグ ブレンディング、ステンシル処理、レンダリング ターゲット ブレンディングといったピクセル処理は、シェーダの実行後に行う。レンダリング ターゲット ブレンディングの構文は、このトピックで解説するように、新しい機能をサポートするために更新されている。

ピクセル シェーダ入力

DirectX 8.0 では、テクスチャ レジスタに宣言されるすべての色 (ディフューズ色およびスペキュラ色) は、シェーダで使う前に、シェーダへの有効入力の範囲の 0 から 1 の範囲にある (固定されている) と見なされる。位置座標は、ピクセル シェーダの実行前にクリップされていると見なされる。

ピクセル シェーダは、すべての補間値は補間されたパースペクティブ補正であると見なすが、これはすべてのハードウェアで保証されているものではない。アドレス シェーダによってテクスチャ座標として生成された色は、常にパースペクティブ補正の方法で補間される。しかし、これらは補間の間に 0 ～ 1 の範囲に固定される。

ピクセル シェーダ出力

ピクセル シェーダによって出力される結果は、レジスタ r0 のコンテンツである。シェーダの処理が終了した時点でこのレジスタに格納されているデータは、常にフォグ ステージおよびレンダリング ターゲット ブレンダに送信される。


ピクセル シェーダのデータ フロー

ここでは、ピクセル シェーダの仮想マシンへ転送され、また仮想マシンから転送されるデータ フローについて解説する。以下のトピックは、ピクセル シェーダの開発およびその基礎となる仮想マシンについて詳細に理解することを目的として記述されている。

  • ピクセル シェーダ仮想マシンについて
  • ピクセル データの処理


ピクセル シェーダ仮想マシンについて

次の図は、ピクセル シェーダ仮想マシン内での論理データ フローを示している。

各三角形で補間されたデータは、上の図に示したように仮想マシンに転送される。テクスチャ座標およびカラー値は、各ピクセルごとに補間される。テクスチャ座標のマッピングは、D3DTSS_TEXCOORDINDEX テクスチャ ステージ ステートを設定して制御する。たとえば、頂点シェーダからの oD0 データ出力が三角形上で補間され、個々のピクセルの結果がピクセル シェーダの v0 レジスタに設定されるなどである。


ピクセル データの処理

ピクセル データが仮想マシンによってどのように処理されるかを理解するため、オレンジの球体を想像し、それをバンプ マップして、ライトがサーフェスを照らすような環境の中に置くとする。この単純なシナリオで、オレンジの色が、球体を形成する三角形を使って補間されるとする。オレンジの色は、頂点シェーダの oD0 チャネルに渡されたデータから補間されるため、各ピクセルは v0 レジスタを使ってピクセル シェーダに提示される。

次のトピックでは、バンプ マップおよび環境マップのデータを使って、オレンジの球体の最終イメージをレンダリングするために必要なステップを解説する。

  • ピクセル シェーダ仮想マシン用のデータを準備する
  • ピクセル シェーダ仮想マシンを使ってデータを送信する
  • ピクセル シェーダ パイプラインの処理順序

ここでは、特定の例を使ってピクセル シェーダ仮想マシンがデータを処理する方法を示すが、その原則と手順は、各種のピクセル シェーダの開発に応用できる。


ピクセル シェーダ仮想マシン用のデータを準備する

オレンジの球体をバンプ マップと環境マップのデータでレンダリングする前に、バンプ マップおよび環境マップをロードする必要がある。その後各テクスチャ処理ユニットに該当するテクスチャ ステージ ステートを設定する。これには、D3DTSS_BUMPENVMAT00、D3DTSS_BUMPENVMAT01、D3DTSS_BUMPENVMAT10、D3DTSS_BUMPENVMAT11、および D3DTSS_TEXCOORDINDEX テクスチャ ステージ ステートの設定が含まれる。ただし、D3DTSS_COLOROP によって定義されるカラー処理は設定する必要がない。これは、ピクセル単位に実行される処理の定義に、ピクセル シェーダ コードが使用されるためである。一般に、三角形、オブジェクト、またはフレームをレンダリングしている間に一定の状態を維持するテクスチャ ステージ ステートは、ピクセル シェーダ仮想マシンを呼び出す前に設定される。これには、2 × 2 バンプ マッピング行列値が含まれる。ただし、各ピクセルのシェードに使用されるデータは、ピクセル シェーダ言語を使って指定される。

この例では、頂点シェーダ内で発生するフロント エンド処理については触れていない。その代わり、フロント エンドがテクスチャ補間を設定することにより、バンプ データが頂点シェーダの oT0 チャネルを介して渡されると前提する。これは、オレンジの球体の例では、バンプ データへのアクセスに使用されるバンプ マップ アドレスが、ピクセル シェーダの最初のテクスチャ座標レジスタ (t0) に設定されることを意味する。同様に、ライト マップ アドレスは、テクスチャ処理ユニットで変更が行われる前に、頂点シェーダの oT1 チャネルから t1 を介してピクセル シェーダに渡される。


ピクセル シェーダ仮想マシンを使ってデータを送信する

ステージ 0 のテクスチャ処理に使用されるアドレスは、最初のテクスチャ座標レジスタ (t0) を介して提示されるバンプ マップ アドレスとなる。処理は、次のピクセル シェーダ コードに示すように、バンプ データの単純な参照である。

tex t0

ステージ 1 のテクスチャ処理はより複雑である。この場合には、2 × 2 行列がロードされるようにテクスチャ ステージ ステートを設定する必要がある。ここで、視点と光源の間の変更をシミュレートするためにロードできる 2 × 2 行列があることに注目する。これにより、シーン内で視点が移動する際、バンプ マップおよび環境マップを再利用することができる。このため、環境マップへのアドレスは、2 番目のテクスチャ座標である t1 を介して提示されたベース アドレスが、視点調整およびローカル バンプ値によって乗算されたものとなる。より正確には、環境マップへの u 座標は u = t1.r + mat00 * t0.r + mat01 * t0.g であり、環境マップへの v 座標は v = t1.g + mat10 * t0.r + mat11 * t0.g となる。t0.r および t0.g レジスタ成分の値は、実際には du および dv の値であり、ステージ 0 でのバンプ データ参照を表し、レジスタ t0 に格納される。

注 u および v アドレスの計算には、実際のピクセル シェーダ コード内に 2 つのスロットを要する場合がある。これは、ほとんどのハードウェアが、u のロジックを再利用し、その後 v アドレス計算を再利用するためである。現在のハードウェアでは、アドレスをパラレルで計算することはできない。

次の例では、このことをピクセル シェーダ コード内で実行する方法を示している。

ps.1.0         // DirectX8 バージョン。
tex t0         // テクスチャ (バンプ データ) を宣言する。
texbem t1, t0  // 環境マップを宣言し、t0 からデータを取得する。
mov r0, v0     // ディフューズ色のオレンジ色が
               // 各ピクセルのレジスタ v0 を介してピクセル シェーダに
               // 渡されているという仮定に注意すること。
add r0, r0, t1 // スペキュラ環境データを追加する。

これは非常に単純な例であり、多くの場合に適用できるものではない。通常は、バンプ環境マッピングの実行前にベース テクスチャがオブジェクトに適用される。たとえば、テクスチャ データを適用するためのベースとして、白い球体などを送る。これは、サーフェス上のある部分では明るく、ある部分ではやや暗いディフューズ ライトである。この場合、ステージからバンプ環境マッピング処理を外し、ベース テクスチャをディフューズ ライトによって乗算する。次の例では、このことをピクセル シェーダ コード内で実行する方法を示している。

ps.1.0         // DirectX8 バージョン
tex t0         // ベース テクスチャを宣言する。大理石、木材、その他のサーフェス マテリアルなど、
               // 任意のものを宣言できる。
tex t1         // テクスチャ (バンプ データ) を宣言する。
texbem t2, t1  // 環境マップを宣言する。
mul r0, v0, t0 // ディフィーズ ライトでベース テクスチャを乗算する。
add r0, r0, t2 // スペキュラ環境データを追加する。

従来のテクスチャ マッピング (1 ステージ) を使用し、スペキュラを補間し、ピクセル シェーダ仮想マシンのレジスタ v1 を介して利用できるようにすることが推奨される。その他の複雑なピクセル シェーダは、定数レジスタ (c0～c7) に格納されている一連の固定定数を使って構築できる。また、テクスチャ レジスタは多くの場合テクスチャ ステージと共に使用されるが、ピクセル演算論理単位 (ALU) への読み書きである。このためピクセル シェーダは、テクスチャ レジスタをテンポラリ レジスタとして使用できる。また、r0 および r1 は ALU への読み書きであるが、r0 に格納される結果は、深度およびステンシル ロジックに出力できる唯一の結果である。事実、結果をストリームに渡す唯一の方法は、r0 レジスタを使用することである。


ピクセル シェーダ パイプラインの処理順序

ピクセル シェーダ パイプラインのステートは、レンダリング ステートおよびテクスチャ ステージ ステートを設定して、IDirect3DDevice8::SetTexture、IDirect3DDevice8::SetTextureStageState、IDirect3DDevice8::SetPixelShader、および IDirect3Ddevice8::SetPixelShaderConstant メソッドを呼び出すことで、その実行時全体にわたって制御できる。これらのステートおよび関数は、ピクセル シェーダの制御フロー、およびピクセル シェーダ パイプラインの各ステップのステートを指定する。次の図は、これらのステップの順序、および各ステップを直接制御する設定を示している。

SetPixelShader に渡されるハンドルの値に応じて、固定機能またはピクセル シェーダ パイプラインのいずれかが 1 つのインスタンスで使用されるが、その両方が使用されることはない。数値によって示される時間になる前に、深度ステンシル テストが行われることがあるが、これによってカラー パイプラインの結果に影響が出ることはない。シェーディング アルゴリズムで処理を進める中、値を固定できる各種パイプライン処理が存在することに注意する。


ピクセル シェーダの使い方

ここでは、アプリケーション内でのピクセル シェーダの使用方法について説明する。

  • ピクセル シェーダ サポートの確認
  • ピクセル シェーダ テクスチャ入力の設定
  • ピクセル シェーダ定数レジスタの設定
  • ピクセル シェーダのコンパイル
  • ピクセル シェーダの作成


ピクセル シェーダ サポートの確認

D3DCAPS8 のメンバを照会して、ピクセル シェーダに関する処理のサポート レベルを確認することができる。次の表は、Microsoft® DirectX® 8.0でのプログラム可能なピクセル処理に関連するデバイス機能を示している。

デバイス機能 | 説明
MaxPixelShaderValue | ピクセル シェーダの算術コンポーネントの最大値。
MaxSimultaneousTextures | サポートされるテクスチャ宣言命令の数。
MaxTextureBlendStages | サポートされる命令の数。
PixelShaderVersion | ピクセル シェーダのサポート レベル。

MaxSimultaneousTextures および MaxTextureBlendStages 能力は、固定機能ピクセル ブレンディング (マルチテクスチャを使用) にのみ適用される。

PixelShaderVersion 機能は、ピクセル シェーダのサポート レベルを示す。IDirect3DDevice8::CreatePixelShader メソッドを呼び出したとき、この値以下のバージョン番号を持つピクセル シェーダのみ正常に作成される。主なバージョン番号は、PixelShaderVersion のセカンド バイトにエンコードされる。下位バイトには、マイナー バージョンの番号が含まれる。ピクセル シェーダのバージョンは、各シェーダの最初のトークンによって示される。

ピクセル シェーダ アプリケーションは、MaxSimultaneousTextures および MaxTextureBlendStages デバイス能力をチェックする必要がない。

各実装は、完全にサポートできる最大のピクセル シェーダ バージョンを示す PixelShaderVersion メンバを設定する。このため、PixelShaderVersion によって提示されたバージョン以下のシェーダの作成が失敗することはない。

次の表は、サポートされているピクセル シェーダのバージョン、および関連する機能レベルとレジスタ カウントを示している。

バージョン | 機能 | tn | rn | cn | vn
1.0 | DirectX 8.0 | 4 | 2 | 8 | 2
1.1 | DirectX 8.0 | 4 | 2 | 8 | 2

バージョン 1.0 は、ピクセル シェーダのリファレンスの「命令」に記載されるすべての処理をサポートしている。最大 4 つのテクスチャ アドレス処理、および合計 8 つの命令がサポートされる。このバージョンの場合、テクスチャ レジスタの tn は読み取り専用であり、指定された命令内ではこのテクスチャ レジスタのみ使用できる。

バージョン 1.1 では、最大 4 つのアドレス処理、および 8 つのブレンディング処理をサポートしている。このバージョンの場合、テクスチャ レジスタは読み/書き可能であり、その 2 つを単一の命令内で入力として使用できる。


ピクセル シェーダ テクスチャ入力の設定

入力レジスタ色とテクスチャ ステージの間には、直接マッピングが存在する。Direct3DX ピクセル シェーダ アセンブラのテンポラリ レジスタは、対応するテクスチャ ステージからのテクスチャ カラーと共にプリロードされる。これに対し、テクスチャは、IDirect3DDevice8::SetTexture メソッドを呼び出すことによってテンポラリ レジスタに直接バインドされる。

またテクスチャ座標は、直接マップされ、テクスチャ宣言によって定義される。


ピクセル シェーダ定数レジスタの設定

次のメソッドを使って、ピクセル シェーダ定数レジスタに対する値の設定および読み出しを行うことができる。

  • IDirect3DDevice8::GetPixelShaderConstant
  • IDirect3DDevice8::SetPixelShaderConstant

また、def Direct3DX アセンブラ命令を使って、ピクセル シェーダの定数レジスタを設定することもできる。


ピクセル シェーダのコンパイル

Direct3DX ユーティリティ ライブラリには、ピクセル シェーダをコンパイルするための一連の関数が用意されている。使用できる関数は次のとおりである。

  • D3DXAssembleShader
  • D3DXAssembleShaderFromFileA
  • D3DXAssembleShaderFromFileW


ピクセル シェーダの作成

Microsoft® DirectX® 8.0 でピクセル シェーダを作成するには、IDirect3DDevice8::CreatePixelShader メソッドを使用する。このメソッドには、ブレンディング処理を定義する宣言を渡す。Microsoft Direct3D® は、シェーダのハンドルを返す。シェーダは、CreatePixelShader が呼び出されるときに妥当性が検証される。

DirectX 8.0 ハードウェア モデルの制限により、指定されたシェーダの作成に失敗することもある。


ピクセル シェーダの例

ここでは、ピクセル シェーダ コードに実装されている一般的なエフェクトについて説明する。説明するトピックは、次のとおりである。

  • ディフューズ ライティング
  • スペキュラ マッピング
  • ディフューズ ライティングとスペキュラ マッピング
  • 内積ライティング
  • ピクセル シェーダのサンプル


ディフューズ ライティング

次のシェーダは、ピクセル単位のディフューズ ライティングを実行する。ディフューズ強度を計算するには、dp3 命令を使用する。

ps.1.0                      // DirectX8 バージョン。
tex t0                      // 法線マップを宣言する。
texm3x3pad t1, t0_bx2       // 1 行目トランスフォーム。
texm3x3pad t2, t0_bx2       // 2 行目トランスフォーム。
texm3x3tex t3, t0_bx2       // 3 行目トランスフォーム。
dp3_sat r0, t3_bx2, v0_bx2


スペキュラ マッピング

次のシェーダは、ピクセル単位のスペキュラ マッピングを実行する。

ps.1.0                   // DirectX8 バージョン。
tex t0                   // 法線マップを宣言する。
texm3x3pad   t1, t0      // 1 行目トランスフォーム。
texm3x3pad   t2, t0      // 2 行目トランスフォーム。
texm3x3spec  t3, t0, c0  // 3 行目トランスフォーム。次に空間を反射させ、
                         // キューブ マップをサンプリングする。

mov r0, t3               // フレーム バッファ ブレンダに送る。
                         // これはフレーム バッファの内容に追加される。


ディフューズ ライティングとスペキュラ マッピング

次のシェーダの組み合わせは、ピクセル単位のディフューズ ライティングとスペキュラ マッピングを実行する。

ps.1.0                // DirectX8 バージョン。
tex t0                // 法線マップを宣言する。
texm3x3pad  t1, t0    // 1 行目トランスフォーム。
texm3x3pad  t2, t0    // 2 行目トランスフォーム。
texm3x3spec t3, t0    // 3 行目トランスフォーム。ディフューズ キューブ マップを t2 に、
                      // スペキュラ キューブ マップを t3 にサンプリングする。
mov r0, t3            // スペキュラ色を出力する。


内積ライティング

内積には符号付きデータが必要なため、_bx2 引数修飾子を使って入力データを変換する必要がある。ライティングは、_sat 命令修飾子を使って負の値を固定する。

// ディフィーズはライトの方向である。

ps.1.0      // DirectX8 バージョン。
tex t0      // 法線マップ。
dp3_sat r0, t0_bx2, v0_bx2


ピクセル シェーダのサンプル

MFCPixelShader サンプルは、異なるピクセル シェーダがレンダリング対象のシーンに使用するエフェクトを示す。このサンプルには、あらかじめ定義されている 6 つのシェーダがあり、これらの中から選択してピクセル シェーダを変更することで、異なる結果を得ることができる。


ポイント スプライト

ここでは、ポイント スプライトについて説明する。説明するトピックは、次のとおりである。

  • ポイント スプライトとは
  • ポイント プリミティブのレンダリング制御
  • ポイント サイズの計算
  • ポイント レンダリング


ポイント スプライトとは

Microsoft® Direct3D® for Microsoft DirectX® 8.0 では、ポイント スプライトがサポートされているため、ポイント (粒子システム) の高性能レンダリングが可能である。ポイント スプライトとは、任意の形状をテクスチャで定義されたようにレンダリングできるようにする、一般化された汎用ポイントである。

ポイント スプライトは、固定機能ジオメトリ パイプラインではサポートされていない。ポイント スプライトを使用するには、プログラム可能な頂点処理を使う必要がある。


ポイント プリミティブのレンダリング制御

Microsoft® Direct3D® for Microsoft DirectX® 8.0 は、ポイント スプライト (ポイント プリミティブ) のレンダリングを制御するための追加パラメータをサポートしている。これらのパラメータにより、ポイントに可変サイズを設定でき、テクスチャ マップ全体を適用することができる。各ポイントのサイズは、アプリケーションで指定されたサイズと、Direct3D が計算する距離ベースの関数を組み合わせて決定される。アプリケーションは、ポイント サイズを頂点ごとに設定することもでき、また、頂点ごとには設定を行わず、D3DRS_POINTSIZE を設定してポイントに適用することもできる。ポイント サイズはカメラ空間単位で表現される。ただし、アプリケーションがトランスフォーム後の柔軟な頂点フォーマット (FVF) 頂点を渡しているときは、距離ベースの関数は適用されず、ポイント サイズはレンダリング ターゲット上のピクセルの単位で表現される。

ポイントのレンダリング時に計算され使用されるテクスチャ座標は、D3DRS_POINTSPRITEENABLE の設定によって異なる。この値が TRUE に設定されている場合は、各ポイントがテクスチャ全体を表示するようにテクスチャ座標が設定される。これは一般に、ポイントが 1 ピクセルより非常に大きい場合のみに使用する。D3DRS_POINTSPRITEENABLE が FALSE に設定されている場合は、各ポイントの頂点テクスチャ座標がポイント全体に使用される。


ポイント サイズの計算

ポイント サイズは D3DRS_POINTSCALEENABLE によって決定される。この値が FALSE に設定されている場合は、アプリケーションで指定されたサイズがスクリーン空間 (トランスフォーム後) サイズとして使用される。スクリーン空間で Microsoft® Direct3D® に渡される頂点は、ポイント サイズが計算されず、指定されたポイント サイズがスクリーン空間のサイズとして解釈される。

D3DRS_POINTSCALEENABLE が TRUE の場合は、Direct3D が、次の式に従ってスクリーン空間のポイント サイズを計算する。アプリケーションで指定されたポイント サイズは、カメラ空間単位で表現される。

Ss = Vh * Si * sqrt(1/(A + B*De + C*(De2)))

この式の中の入力ポイント サイズ Si は、頂点ごとの値か、または D3DRS_POINTSIZE レンダリング ステートの値である。ポイント スケール係数 D3DRS_POINTSCALE_A、D3DRS_POINTSCALE_B、および D3DRS_POINTSCALE_C は、ポイント A、B、および C によって表される。ビューポート Vh の高さは、ビューポートを表す D3DVIEWPORT8 構造体の Height メンバである。視点から位置座標への距離 (原点の目) De は、ポイント (Xe, Ye, Ze) の視点空間位置を取り、次の処理を実行することによって計算される。

De = sqrt (Xe2 + Ye2 + Ze2)

最大ポイント サイズ Pmax は、D3DCAPS8 の MaxPointSize メンバまたは D3DRS_POINTSIZE_MAX レンダリング ステートのどちらか小さい方を取って決定される。最小ポイント サイズ Pmin は、D3DRS_POINTSIZE_MIN の値を調べることによって決定される。つまり、最終的なスクリーン空間ポイント サイズ S は次の規則に従って決定される。

  • Ss > Pmax なら S = Pmax
  • Ss < Pmin なら S = Pmin
  • それ以外の場合は S = Ss


ポイント レンダリング

スクリーン空間サイズ S のスクリーン空間ポイント

P = (X, Y, Z, W)

は、次の 4 つの頂点を持つ四辺形としてラスタ化される。

((X+S/2, Y+S/2, Z, W), (X+S/2, Y-S/2, Z, W), (X-S/2, Y-S/2, Z, W), (X-S/2, Y+S/2, Z, W))

頂点カラー属性は頂点それぞれで複製されるため、各ポイントは常にコンスタント カラーでレンダリングされる。

テクスチャ インデックスの割り当ては、D3DRS_POINTSPRITEENABLE レンダリング ステート設定によって制御される。D3DRS_POINTSPRITEENABLE が FALSE に設定されている場合は、頂点テクスチャ座標は頂点それぞれで複製される。D3DRS_POINTSPRITEENABLE が TRUE に設定されている場合は、4 つの頂点のテクスチャ座標は次の値に設定される。

(0.F, 0.F), (0.F, 1.F), (1.F, 0.F), (1.F, 1.F)

これを次の図に示す。

クリッピングが有効にされている場合は、次の規則に従ってポイントがクリッピングされる。シーンがレンダリングされる深度の範囲 (D3DVIEWPORT8 構造体の MinZ および MaxZ) を頂点が超えている場合、ポイントは視錐台の外に存在し、レンダリングされない。ポイント サイズを考えに入れて、ポイントが完全に X および Y のビューポートの外に存在する場合、そのポイントはレンダリングされず、残りのポイントはレンダリングされる。ポイントの位置が X または Y のビューポートの外にあっても、部分的に表示できる場合がある。

ポイントは、ユーザー定義クリップ面に正しくクリップされる場合もあり、そうでない場合もある。D3DCAPS8 の PrimitiveMiscCaps メンバ内で D3DPMISCCAPS_CLIPPLANESCALEDPOINTS が設定されていない場合、ポイントは、頂点位置だけに基づき、ポイント サイズは無視して、ユーザー定義クリップ面にクリップされる。このとき、スケーリングされたポイントは、頂点位置がクリップ面の中にある場合は完全にレンダリングされ、頂点位置がクリップ面の外にある場合は破棄される。アプリケーションでは、最大ポイント サイズと同じ大きさの境界ジオメトリをクリップ面に追加することで、不自然な効果の発生を防ぐことができる。

D3DPMISCCAPS_CLIPPLANESCALEDPOINTS ビットが設定されている場合は、スケーリングされたポイントは、ユーザー定義クリップ面に正確にクリップされる。

ハードウェア頂点処理は、ポイント サイズをサポートしている場合もあり、そうでない場合もある。たとえば、D3DCAPS8 構造体の MaxPointSize メンバが 1.0 または 0.0 に設定されている、HAL デバイス (D3DDEVTYPE_HAL) 上の D3DCREATE_HARDWARE_VERTEXPROCESSING でデバイスを作成すると、すべてのポイントは単一ピクセルになる。1.0 より小さなピクセル ポイント スプライトをレンダリングするには、柔軟な頂点フォーマット (FVF)TL (トランスフォーム済みライティング済み) 頂点、またはソフトウェア頂点処理 (D3DCREATE_SOFTWARE_VERTEXPROCESSING) を使用する必要があり、この場合 Microsoft® Direct3D® ランタイムがポイント スプライト レンダリングをエミュレートする。FVF TL 頂点の詳細については、「トランスフォーム済み ライティング済みの頂点の機能」を参照すること。

頂点処理を実行し (MaxPointSize が1.0f より大きな値に設定された) ポイント スプライトをサポートするハードウェア デバイスは、トランスフォームされないスプライトのサイズ計算に必要であり、また TL 頂点の頂点ごとまたは D3DRS_POINTSIZE の設定を正しく行うためにも必要である。


頂点シェーダ

ここでは、頂点シェーダについて解説し、Microsoft® Direct3D® アプリケーション内での使用方法を説明する。説明するトピックは、次のとおりである

  • 頂点シェーダとは
  • 頂点シェーダの構成要素
  • 頂点シェーダの使い方
  • 頂点シェーダのテクニックとアプリケーション
  • 頂点シェーダの例

このドキュメント内で使用されているすべての頂点シェーダ コードおよび構文は、Direct3DX 頂点シェーダ アセンブラに基いており、互換性がある。このセクションを読む前に、「頂点シェーダ アセンブラ リファレンス」を読み、頂点シェーダ アセンブラについての知識を取得しておく必要がある。


頂点シェーダとは

頂点シェーダは、頂点のロードと処理を制御する。Microsoft® Direct3D® for Microsoft DirectX® 8.0 では、プログラム可能な頂点処理および固定機能頂点処理の 2 種類の頂点処理をサポートしている。DirectX 8.0 のドキュメントでは、「頂点シェーダ」というと主にプログラム可能なモードに適用されるが、頂点シェーダ API 機構では、どちらのタイプも使用できる。頂点シェーダは、作成の際に、プログラム可能な頂点処理を使用するかまたは固定機能頂点処理を使用するか定義される。作成後は、頂点シェーダ自身のハンドルによって参照される。頂点シェーダを編集することはできない。頂点シェーダを変更するには、いったん破棄して作り直す必要がある。

各頂点シェーダには関数が 1 つ含まれており、これによって各頂点に適用する処理が定義される。また宣言も 1 つ含まれており、これによって、入力データ ストリーム内の頂点要素がシェーダによってどのように使用されるかなど、シェーダへの入力が定義される。

頂点シェーダによって実行される頂点処理には、単一の頂点に適用される処理のみが含まれる。頂点処理手順によって得られる出力は、個々の頂点ごとに定義され、それぞれに、クリップ空間位置 (x,y,z,w)、色、テクスチャ座標、フォグ強度、およびポイント サイズ情報が含まれる。これらの位置座標からビューポートへの射影とマッピング、複数の頂点からプリミティブへのアセンブル、およびプリミティブのクリッピングは、後の処理段階によって実行され、頂点シェーダの制御下にはない。

固定機能頂点処理は、トランスフォーム、ライティング、頂点ブレンディング、テクスチャ座標生成を含め、Direct3D for DirectX 7.0 と同じ機能を提供する。プログラム可能な頂点シェーダでは、頂点に適用される処理がシェーダ内で定義されるのに対し、固定機能頂点処理は、ライトやトランスフォームなどを設定する IDirect3DDevice8 のメソッドによって設定されたデバイス ステートによって制御される。しかし、機能が固定され共有されている場合でも、宣言は変更できるため、複数の固定機能頂点シェーダを使用することも有用である。これにより、固定機能シェーダに、異なるマルチストリーム入力のレイアウトを提供することができる。

固定機能頂点処理の入力頂点要素のセマンティクスは固定されている。このため、宣言タグによって、入力頂点要素が、座標、法線、色などとして指定される。固定機能頂点シェーダの頂点出力には常に、ピクセル処理のための現在のデバイス ステート設定で必要とされる、座標、ディフューズ色、スペキュラ色、複数のテクスチャ座標が含まれる。

プログラム可能な頂点シェーダには、各頂点に適用される命令の配列によって定義された関数が 1 つ含まれる。入力頂点要素からプログラム可能な頂点シェーダの頂点入力レジスタへのマッピングは、シェーダ宣言で定義されるが、入力頂点要素は、その使用について特定のセマンティクスを持たない。入力頂点要素の解釈は、シェーダの命令に従う。プログラム可能な頂点シェーダの頂点出力は、シェーダ関数内の命令によって明示的に書き込まれる。

Direct3DX 頂点シェーダ アセンブラの詳細については、「頂点シェーダ アセンブラ リファレンス」を参照すること。


頂点シェーダの構成要素

ここでは、頂点シェーダの構成要素について説明する。説明するトピックは、次のとおりである。

  • 頂点シェーダ宣言
  • 頂点シェーダ関数


頂点シェーダ宣言

頂点シェーダの宣言部分では、シェーダの静的な外部インターフェイスを定義している。頂点シェーダ宣言には次の情報が含まれる。

  • 頂点シェーダ入力レジスタに対するストリーム データのバインド。この情報により、各データ ストリーム内の各要素のタイプと頂点入力レジスタ割り当てが定義される。このタイプにより、算術データ型およびディメンション (値 1、2、3、4) が指定される。4 個より少ない値のストリーム データ要素は、0 個、1 個、または複数個の 0.F 値と 1 個の 1.F 値によって 4 個の値に拡張される。
  • 頂点シェーダ入力レジスタから、プリミティブ テッセレータの非明示的データへのバインド。これにより、ストリームからロードされるのでなく、頂点シェーダの前に行われるプリミティブのテッセレーション中に生成される頂点データのロードが制御される。
  • シェーダが現在のシェーダとして設定されるときの定数メモリのデータのロード。各トークンは、1 つまたは複数の連続する 4-DWORD 定数レジスタの値を指定する。これにより、シェーダは、定数メモリの任意のサブセットを更新し、定数メモリの現在の値を格納しているデバイス ステートを上書きすることができる。これらの値は、シェーダが IDirect3DDevice8::SetVertexShaderConstant メソッドを介してデバイスにバインドされているときに、DrawPrimitive 呼び出しの間に上書きできる。

宣言配列は、それぞれが 1 つまたは複数の DWORD であるトークンが複数集まって構成された DWORD の 1 次元配列である。1-DWORD トークン値 0xFFFFFFFF は、宣言配列の末尾を表す特別なトークンである。1-DWORD トークン値 0x00000000 は、パディング トークンであり、宣言の解析時には無視される。このパディング トークンによって、宣言内でより複雑な編集を実行できる。複数語のトークンの第 1 DWORD に続く DWORD に対して 0x00000000 は有効な値である。

次のサンプル コードでは、宣言を記述している。この例では、単純な構造を使って頂点を定義する方法を示している。

struct Vertex
{
    D3DXVECTOR3 Position;
    D3DXVECTOR3 Normal;
    D3DCOLOR    Diffuse;
    D3DXVECTOR2 TexCoord0;
};

次のサンプル コードは、上記の同じ頂点構造を宣言子として定義する方法を示している。

DWORD dwDecl[] =
{
    D3DVSD_STREAM( 0 ),
    D3DVSD_REG( D3DVSDE_POSITION,  D3DVSDT_FLOAT3 ),
    D3DVSD_REG( D3DVSDE_NORMAL,    D3DVSDT_FLOAT3 ),
    D3DVSD_REG( D3DVSDE_DIFFUSE,   D3DVSDT_D3DCOLOR ),
    D3DVSD_REG( D3DVSDE_TEXCOORD0, D3DVSDT_FLOAT2 ),
    D3DVSD_END()
};

DWORD dwFvf = D3DFVF_POSITION | D3DFVF_NORMAL | D3DFVF_DIFFUSE |
              D3DFVF_TEX0 | D3DFVF_TEXCOORDSIZE2(0);

宣言子はデータ ストリームを 0 に設定し、3 つの float 型の値で構成される位置座標と法線ベクトルを定義し、4 成分符号なしバイトで構成されるディフューズ成分を定義し、2 つの float 型の値で構成されるテクスチャ座標の組を定義する。

固定機能頂点シェーダを使用する際、頂点入力レジスタのマッピングは固定される。これにより、位置座標や法線といった特定の頂点要素は頂点入力メモリ内の特定のレジスタ位置に置かれる必要がある。これらの割り当ては、FVF コードが IDirect3DDevice8::SetVertexShader に渡されるときに自動的に実行される。明示的なシェーダ宣言を使用する場合は、D3DVSDE プリプロセッサ マクロが、特定の要素のロード先となる頂点入力位置を定義する。宣言トークン配列の生成に使用するマクロの定義については、D3d8types.h を参照すること。

シェーダ宣言トークン タイプとビット定義については、「頂点シェーダ宣言子マクロ」を参照すること。

注 固定機能頂点シェーダを使うときは、IDirect3DDevice8::SetStreamSource の頂点ストライド セットと頂点サイズが同じサイズでなければならない。宣言を使用する頂点シェーダの場合は、ストリーム ストライドは宣言ストライドより大きくてもかまわない。


頂点シェーダ関数

頂点シェーダの関数部分では、各頂点に適用される処理を定義している。シェーダ関数は、プログラム可能な頂点シェーダにしかない。宣言と同様、シェーダ関数も DWORD の 1 次元配列であり、各頂点に対して実行する命令の順序付きリストを形成している。各命令は複数の DWORD で構成される。

Direct3DX ユーティリティ ライブラリには、ドライバに転送される標準 DWORD トークンを生成するための一連の関数が用意されている。詳細については、「頂点シェーダのコンパイル」を参照すること。


頂点シェーダの使い方

ここでは、アプリケーション内での頂点シェーダの定義方法および使用方法を説明し、頂点シェーダを使って得られるエフェクトについて解説する。

  • 頂点シェーダ サポートの確認
  • 頂点シェーダ定数レジスタの設定
  • 頂点シェーダのコンパイル
  • 頂点シェーダの作成


頂点シェーダ サポートの確認

D3DCAPS8 のメンバを照会して、頂点シェーダに関する処理のサポート レベルを確認することができる。次の表は、Microsoft® DirectX® 8.0 でのプログラム可能な頂点処理に関連するデバイス機能を示している。

デバイス機能 | 説明
MaxPrimitiveCount | DrawPrimitive の各呼び出しの最大プリミティブ数。
MaxVertexIndex | ハードウェア頂点処理に対してサポートされるインデックスの最大サイズ。
MaxStreams | 同時データ ストリームの最大数。
MaxStreamStride | ストライドに対する最大データ ストリーム。
MaxVertexShaderConst | 頂点シェーダの定数レジスタの数。
VertexShaderVersion | 頂点シェーダのサポート レベル。

VertexShaderVersion 機能は、頂点シェーダのサポート レベルを示す。IDirect3DDevice8::CreateVertexShader メソッドを呼び出したとき、この値以下のバージョン番号を持つ頂点シェーダのみ正常に作成される。CreateVertexShader に対する頂点シェーダのレベルの指定は、シェーダ トークン ストリームの第 1 トークンで行われる。

次の表は、サポートされている頂点シェーダのバージョンを示している。

バージョン | 機能
0.0 | DirectX 7.0。
1.0 | DirectX 8.0。アドレス レジスタ A0 なし。
1.1 | DirectX 8.0 アドレス レジスタ A0 あり。

サポート レベルの 1.0 と 1.1 の唯一の違いは、A0 レジスタのサポートの有無である。


頂点シェーダ定数レジスタの設定

次のメソッドを使って、頂点シェーダ定数レジスタに対する値の設定および読み出しを行うことができる。

  • IDirect3DDevice8::GetVertexShaderConstant
  • IDirect3DDevice8::SetVertexShaderConstant

また、def Direct3DX アセンブラ命令を使って、頂点シェーダの定数レジスタを設定することもできる。


頂点シェーダのコンパイル

Direct3DX ユーティリティ ライブラリには、頂点シェーダをコンパイルするための一連の関数が用意されている。使用できる関数は次のとおりである。

  • D3DXAssembleShader
  • D3DXAssembleShaderFromFileA
  • D3DXAssembleShaderFromFileW


頂点シェーダの作成

頂点シェーダは、シェーダの宣言と機能を指定する 2 つのトークン配列によって定義される。トークン配列は、1 つ以上の DWORD トークンで構成されており、配列の末尾は値 0xFFFFFFFF のトークンで示される。

シェーダの宣言はシェーダの静的な外部インターフェイスを定義しており、頂点レジスタ入力に対するストリーム データのバインドや、シェーダの定数メモリにロードされる値などが含まれる。シェーダ関数は、シェーダの処理を命令の配列として定義する。これらの命令は、シェーダがデバイスにバインドされているときに処理される各頂点に対して、適切な順序で実行される。機能配列を指定しないでシェーダを作成すると、そのシェーダがカレント シェーダのときには、固定機能頂点処理が適用される。

Microsoft® DirectX® 8.0 で頂点シェーダを作成するには、IDirect3DDevice8::CreateVertexShader メソッドを使用する。このメソッドには、使用されるパラレル DMA ストリームを定義する宣言、およびブレンディング処理を定義する関数を渡す。Direct3D は、シェーダのハンドルを返す。シェーダは、CreateVertexShader が呼び出されるときに妥当性が検証される。


頂点シェーダのテクニックとアプリケーション

ここでは、頂点シェーダに実装されている一般的なテクニックについて説明する。説明するトピックは、次のとおりである。

  • 行列パレットのスキニング
  • プロシージャル ジオメトリ
  • 波のモデリング


行列パレットのスキニング

8 ～ 10 の行列で構成されるセットを、パレットとして定数レジスタにロードすることができる。その後、処理された各頂点は、これらの行列のサブセットによってトランスフォームされ、頂点レベルの重み値を使って最終結果にブレンドされる。有用な実装の 1 つとして挙げられるのは、パックされた 4 バイト整数配列を使って、頂点に影響を与えている 4 つの行列の行列パレット アドレスを格納することである。Microsoft® DirectX® 7.0 テクスチャ座標セットなど、標準的な 4D 成分には、これらの行列のブレンドに使用する 4 つの重み値を含むことができる。


プロシージャル ジオメトリ

皮膚の下で筋肉が動くようすは、球体から計算した楕円と、3 つの軸に沿ったスケーリングによってシミュレートできる。これは、入ってくるメッシュ頂点の位置を補正するために評価および使用できる。筋肉の楕円は、相対位置とスケール係数が格納された定数レジスタを更新することによってスケールおよび平行移動できる。


波のモデリング

二次双曲面のような形は、単位矩形内で生成し、入ってくるジオメトリ上に繰り返しマップすることができる。これを実行するには、frc マクロを使って入力頂点 (x, y) 値を単位矩形にマップし、ローカルの双曲面の上昇を計算して、入力頂点 z 値に加算する。これを利用して、海の波などをシミュレートできる。


頂点シェーダの例

ここでは、頂点シェーダ コードに実装されている一般的なエフェクトについて説明する。説明するトピックは、次のとおりである。

  • トランスフォームと定数シェーディング
  • ディレクショナル ライト
  • その他の頂点シェーダのサンプル


トランスフォームと定数シェーディング

次のシェーダは、コンスタント カラーで単一行列のトランスフォームを実行する。入力頂点レジスタ v0 は位置であり、同一と見なされる。トランスフォーム行列は、定数レジスタ (c[0] ～ c[3]) の中にある。ディフューズ色は c[4] にロードされる。

dp4 r0.x, v0, c[0]
dp4 r0.y, v0, c[1]
dp4 r0.z, v0, c[2]
dp4 r0.w, v0, c[3]
mov oD0, c[4]         ; コンスタント カラー
mov oPos, r0          ; 出力

このシェーダは、6 クロック サイクル内に実行される。


ディレクショナル ライト

次のシェーダは、「トランスフォームと定数シェーディング」で示した頂点シェーダの例に、ディレクショナル ライトの光源を追加することで作成できる。

; ディレクショナル光源
dp3 r1.x, v1, c[8]   ; N と L の内積
max r1, r1.x, c[0000]   ; 0 以上にクランプ

; diffuse = dot*diffuse + ambient
mad oD0, r1.x, c[5], c[6]


その他の頂点シェーダのサンプル

SDK のいくつかのサンプルでは、頂点シェーダ ファイルを使用している。拡張子 .vsh が付いたファイルを \Samples\Multimedia\Media ディレクトリで探すこと。


X ファイル

ここでは、Microsoft® DirectX®(.x) ファイルの構造について説明し、アプリケーション内での使用方法を解説する。

説明するトピックは、次のとおりである。

  • X ファイルについて
  • X ファイル インターフェイス階層
  • X ファイル アーキテクチャ
  • X ファイルの使い方


X ファイルについて

.x ファイル フォーマットは、Microsoft® DirectX® 2.0 から採用された。このフォーマットのバイナリ バージョンは、DirectX 3.0 と共にリリースされた。これについてもこのリファレンスで詳しく解説している。その後、DirectX バージョン 6.0 では、DirectX (.x) ファイルに対して読み書きを実行するためのインターフェイスおよびメソッドが採用された。

.x ファイル フォーマットは、詳細な設定が可能な、テンプレート指向のフォーマットであり、メッシュ、テクスチャ、アニメーション、ユーザー定義可能なオブジェクトなどを格納できる。アニメーション セットをサポートしているため、リアルタイムで再生するために事前定義されたパスを格納することができる。インスタンスと階層もサポートされている。インスタンスを使用することで、1 ファイルにつきデータを 1 度しか格納しなくても、メッシュのような、1 つのオブジェクトに対する複数の参照を実行できる。階層は、データ レコードどうしの関係を表現するために使用される。

.x ファイル フォーマットは、下位レベルのデータ プリミティブを提供する。アプリケーションは、テンプレートを使って、この上に高次レベルのプリミティブを定義する。


X ファイル インターフェイス階層

次の図は、.x ファイル インターフェイスどうしの関係を示している。


X ファイル アーキテクチャ

The Microsoft® DirectX® (.x) ファイル フォーマットは、アーキテクチャにもコンテキストにも依存しないテンプレート指向のフォーマットであり、使用方法についての知識は必要ない。また、あらゆるクライアント アプリケーションで使用できる。

次の各トピックで、X ファイル フォーマットの内容と構文について説明する。このファイル フォーマットは、DirectX ソフトウェア開発キット (SDK) で使用する場合は拡張子 .x を使用する。

  • 予約語、ヘッダー、コメント
  • テンプレート
  • データ
  • コンマとセミコロンの使用法


予約語、ヘッダー、コメント

次の表は予約語を示している。予約語を使用することはできない。

  • ARRAY
  • DWORD
  • UCHAR
  • BINARY
  • FLOAT
  • ULONGLONG
  • BINARY_RESOURCE
  • SDWORD
  • UNICODE
  • CHAR
  • STRING
  • WORD
  • CSTRING
  • SWORD
  • DOUBLE
  • TEMPLATE

可変長ヘッダーは必須で、データ ストリームの先頭になければならない。ヘッダーには次のデータが含まれる。

型 | サイズ | 内容 | 意味
マジック番号 (必須) | 4 バイト | "xof" |
バージョン番号 (必須) | 2 バイト | 03 | メジャー バージョン 3
 | 2 バイト | 02 | メジャー バージョン 2
フォーマット タイプ (必須) | 4 バイト | "txt" | テキスト ファイル
 |  | "bin" | バイナリ ファイル
 |  | "tzip" | MSZip 圧縮テキスト ファイル
 |  | "bzip" | MSZip 圧縮バイナリ ファイル
浮動小数点サイズ (必須) | 4 バイト | 0064 | 64 ビット浮動小数点
 |  | 0032 | 32 ビット浮動小数点

次に有効なヘッダーの例を示す。

xof 0302txt 0064

コメントは、テキスト ファイルでのみ使用でき、データ ストリーム内のどこにでも挿入できる。コメントの開始記号は、C++ 形式のダブルスラッシュ (//) か、または番号記号 (#) を使用する。コメントは、複数行にわたることができる。次に有効なコメントの例を示す。

#  This is a comment.
// これもコメントである。


テンプレート

テンプレートは、データ ストリームの解釈方法を定義する。つまり、テンプレートの定義によってデータが乗算される。ここでは、テンプレートのさまざまな側面について説明し、最後にテンプレートの例を紹介する。

  • テンプレートの形式、名前、UUID
  • テンプレートのメンバ
  • テンプレートの限定使用
  • テンプレートの例

テンプレートの中には、ヘッダー テンプレートという特殊なテンプレートが 1 つある。バージョン情報といったアプリケーション固有の情報を定義するために、各アプリケーションにつき 1 つずつのヘッダー テンプレートを定義することが推奨される。このテンプレートが存在する場合、このヘッダーは .x ファイル フォーマット API によって読み込まれる。flags メンバがある場合は、それ以降のデータの解釈方法の決定に使用される。flags メンバが定義されている場合は、DWORD である。現在、ビット 0 の 1 ビットが定義されている。このビットがクリアの場合、ファイル内の以降のデータはバイナリである。設定されている場合は、それ以降のデータはテキストである。複数のヘッダー データ オブジェクトを使って、ファイル内でバイナリとテキストを切り替えることができる。


テンプレートの形式、名前、UUID

テンプレートの形式は次のようになる。

template <template-name> {
<UUID>
<member 1>;
...
<member n>;
[restrictions]
}

テンプレート名には、英数字およびアンダースコア (_) を使用できる。ただし、先頭の文字に数字は使用できない。UUID は、Open Software Foundation の分散コンピューティング環境標準の書式に従うユニバーサル ユニーク識別子であり、山型かっこ (< >) で囲む。例 : <3D82AB43-62DA-11cf-AB39-0020AF71E433>。


テンプレートのメンバ

テンプレート メンバは、名前付きデータ型の後に、オプションの名前、または名前付きデータ型の配列が続くという構成になる。有効なプリミティブ データ型を次の表に示す。

型 | サイズ
WORD | 16 ビット
DWORD | 32 ビット
FLOAT | IEEE 浮動小数点
DOUBLE | 64 ビット
CHAR | 8 ビット
UCHAR | 8 ビット
BYTE | 8 ビット
STRING | NULL 終端文字列
CSTRING | フォーマットされた C 文字列 (サポートされていない)
UNICODE | Unicode™ 文字列 (サポートされていない)

追加のデータ型も、テンプレート内でデータ ストリームの前に定義されていれば、テンプレート定義内で参照できる。前方参照は実行できない。

有効なデータ型はすべてテンプレート定義内で配列として表現できる。基本的な構文の例を次に示す。

array <data-type> <name>[<dimension-size>];

<dimension-size> は、整数か、またはほかのテンプレート メンバへの名前付き参照である。名前付き参照の場合は、参照先の値が代入される。使用できる配列は n 次元である。ここで n とは、定義文の後に付けられた角かっこのペアの数である。次に例を示す。

array DWORD FixedHerd[24];
array DWORD Herd[nCows];
array FLOAT Matrix4x4[4][4];


テンプレートの限定使用

テンプレートは、開くまたは閉じる、あるいは限定使用できる。これにより、テンプレートに定義されたデータ オブジェクトの直接階層で表示されるデータ型を決定できる。開かれたテンプレートには制約はなく、閉じられたテンプレートはすべてのデータ型を拒否する。限定使用テンプレートでは、指定したデータ型を使うことができる。

テンプレートが開かれていることを示す構文は、3 つのピリオドを角かっこで囲んだものである。

[ ... ]

テンプレートが限定使用されることを示す構文は、名前付きデータ型 (オプションで角かっこ内に UUID 付き) をコンマで区切って並べたものである。

[ { data-type [ UUID ] , } ... ]

これらのどちらも指定されていない場合は、テンプレートが閉じていることを示す。


テンプレートの例

次にテンプレートの例を示す。

template Mesh {
<3D82AB44-62DA-11cf-AB39-0020AF71E433>
DWORD nVertices;
array Vector vertices[nVertices];
DWORD nFaces;
array MeshFace faces[nFaces];
 [ ... ]                // 開かれたテンプレート
}
template Vector {
<3D82AB5E-62DA-11cf-AB39-0020AF71E433>
FLOAT x;
FLOAT y;
FLOAT z;
}                        // 閉じられたテンプレート
template FileSystem {
<UUID>
STRING name;
[ Directory <UUID>, File <UUID> ]    // 限定使用されるテンプレート
}


データ

データ オブジェクトには、実際のデータか、またはそのデータへの参照が含まれる。各データ オブジェクトにはそれぞれ、データ型を定義するテンプレートがある。次の各トピックで、データ オブジェクトの形式と構成要素について説明する。

  • 形式、識別子、名前
  • データ メンバ


形式、識別子、名前

データ オブジェクトの形式は次のようになる。

<Identifier> [name] { [<UUID>]
<member 1>;
...
<member n>;
}

識別子は必須で、事前に定義されたデータ型またはプリミティブに一致しなければならない。名前はオプションである。メンバの詳細については、「データ メンバ」を参照すること


データ メンバ

データ メンバとは、データ オブジェクト、データ参照、整数リスト、浮動小数点リスト、または文字列リストのいずれかである。

データ オブジェクトとは、ネストされたデータ オブジェクトである。これにより、ファイル フォーマットの階層構造的性質を表現できる。階層構造の中で使用できるネストされたデータ オブジェクトのタイプは制限することができる。詳細については「テンプレート」を参照すること。

データ参照とは、前に存在するデータ オブジェクトへの参照である。次に例を示す。

{
  name |
  UUID |
  name UUID
}

整数リストとは、セミコロンで区切られた整数のリストである。次に例を示す。

1; 2; 3;

浮動小数点リストとは、セミコロンで区切られた浮動小数点のリストである。次に例を示す。

1.0; 2.0; 3.0;

文字列リストとは、セミコロンで区切られた文字列のリストである。次に例を示す。

"Moose"; "Goats"; "Sheep";


コンマとセミコロンの使用法

ファイル フォーマットの構文で最も複雑なのは、コンマとセミコロンの使用法である。これらの使用法は厳密に規定されている。コンマは、配列のメンバの区切りを表す。セミコロンは、各データ項目の終わりを表す。

たとえば、テンプレートが次のように定義されている場合、

template mytemp {
DWORD myvar;
}

このテンプレートのインスタンスは次のようになる。

mytemp dataTemp {
1;
}

ほかのテンプレートを含むテンプレートが次のように定義されている場合、

template mytemp {
DWORD myvar;
DWORD myvar2;
}
template container {
FLOAT aFloat;
mytemp aTemp;
}

このテンプレートのインスタンスは次のようになる。

container dataContainer {
1.1;
2; 3;;
}

container の中の mytemp を表す 2 行目の終わりには、セミコロンが 2 つ付けられている。最初のセミコロンはコンテナ内のデータ項目 aTemp の終わりを表し、2 番目のセミコロンは container の終わりを表している。

配列が次のように定義されている場合、

Template mytemp {
array DWORD myvar[3];
}

このインスタンスは次のようになる。

mytemp aTemp {
1, 2, 3;
}

配列の例では、コンマで表されているため、データ項目をセミコロンで区切る必要はない。最後にセミコロンが付けられている場合は、配列の終わりを表す。

次のような、テンプレートによって定義されたデータ項目の配列を含むテンプレートの場合、

template mytemp {
DWORD myvar;
DWORD myvar2;
}
template container {
DWORD count;
array mytemp tempArray[count];
}

このインスタンスは次のようになる。

container aContainer {
3;
1;2;,3;4;,5;6;;
}


X ファイルの使い方

ここでは、Microsoft® Direct3D® アプリケーション内での .x ファイルの使用方法について説明する。説明するトピックは、次のとおりである。

  • X ファイルのロード
  • X ファイルへの保存
  • キューブの作成
  • 3D モデルから X ファイルへの変換とエクスポート


X ファイルのロード

x. ファイルをロードするには、次の手順を実行する。

  1. DirectXFileCreate 関数を使って IDirectXFile オブジェクトを作成する。
  2. ロードする Microsoft® DirectX® ファイルにテンプレートがある場合は、IDirectXFile::RegisterTemplates メソッドを使ってそれらのテンプレートを登録する。
  3. IDirectXFile::CreateEnumObject メソッドを使って IDirectXFileEnumObject 列挙オブジェクトを作成する。
  4. ファイル内のオブジェクトをループする。各オブジェクトに対して、次の手順を実行する。
    1. IDirectXFileEnumObject::GetNextDataObject メソッドを使って各 IDirectXFileData オブジェクトを取得する。
    2. IDirectXFileData::GetType メソッドを使ってデータの型を取得する。
    3. IDirectXFileData::GetData メソッドを使ってデータをロードする。
    4. オブジェクトにオプションのメンバがある場合は、IDirectXFileData::GetNextObject メソッドを呼び出してオプションのメンバを取得する。
    5. IDirectXFileData オブジェクトを解放する。
  5. IDirectXFileEnumObject オブジェクトを解放する。
  6. IDirectXFile オブジェクトを解放する。


X ファイルへの保存

.x ファイル テンプレートとデータを .x ファイルに保存するには、次の手順を実行する。

  1. DirectXFileCreate 関数を使って IDirectXFile オブジェクトを作成する。
  2. IDirectXFile::RegisterTemplates メソッドを使って、使用するすべてのテンプレートについて Microsoft® DirectX® ファイル システムに情報を与える。
  3. IDirectXFile::CreateSaveObject メソッドを使って IDirectXFileSaveObject オブジェクトを作成する。
  4. 必要に応じて、IDirectXFileSaveObject::SaveTemplates メソッドを使ってテンプレートを保存する。
  5. 保存するオブジェクトをループする。各最上位レベルのオブジェクトに対して、次の手順を実行する。
    1. IDirectXFileSaveObject::CreateDataObject メソッドを使って、ファイル内の最上位オブジェクトとして IDirectXFileData オブジェクトを作成する。最上位データ オブジェクトにオプションの子オブジェクトがある場合は、次のステップで定義されているように適切なメソッドを使ってオブジェクトに追加する。
    2. テンプレートによって許可されていれば、各 IDirectXFileData オブジェクトはオプションの子オブジェクトを持つことができる。子オブジェクトのタイプは、IDirectXFileData、IDirectXFileDataReference、または IDirectXFileBinary の 3 種類のいずれでも可能である。後の手順で示すような、それぞれのタイプに適した方法で各オプションの子メンバをオブジェクト リストに追加しながら、保存するオブジェクトをループする。オブジェクト タイプが Data の場合は、IDirectXFileSaveObject::CreateDataObject メソッドを呼び出して IDirectXFileData オブジェクトを作成し、その後 IDirectXFileData::AddDataObject メソッドを呼び出して、オブジェクトの子として追加する。オブジェクト タイプが Data Reference の場合は、IDirectXFileData::AddDataReference メソッドを呼び出して、オブジェクトの子としてデータ参照オブジェクトを作成および追加する。オブジェクト タイプが Binary の場合は、IDirectXFileData::AddBinaryObject メソッドを呼び出して、オブジェクトの子としてバイナリ オブジェクトを作成および追加する。
    3. IDirectXFileSaveObject::SaveData メソッドを呼び出して、データ オブジェクトと子を保存する。
    4. IDirectXFileData オブジェクトを解放する。
  6. IDirectXFileSaveObject オブジェクトを解放する。
  7. IDirectXFile オブジェクトを解放する。


キューブの作成

ここでは、単純なキューブについて説明し、テクスチャ、フレーム、およびアニメーションの追加方法について解説する。

  • 単純なキューブの定義
  • テクスチャの追加
  • フレームとアニメーションの追加


単純なキューブの定義

次のファイルは、4 本の赤い辺と 2 本の緑の辺を持つ単純なキューブを定義する。このファイルでは、オプションの情報を使って、Mesh テンプレートで定義されたデータ オブジェクトに情報を追加している。

Material RedMaterial {
1.000000;0.000000;0.000000;1.000000;;    // R = 0.0, G = 1.0, B = 0.0
0.000000;
0.000000;0.000000;0.000000;;
0.000000;0.000000;0.000000;;
}
Material GreenMaterial {
0.000000;1.000000;0.000000;1.000000;;     // R = 0.0, G = 1.0, B = 0.0
0.000000;
0.000000;0.000000;0.000000;;
0.000000;0.000000;0.000000;;
}
// 8 つの頂点と 12 の面 (三角形) を持つメッシュを定義する。
// メッシュ内のオプションのデータ オブジェクトを使って、
// マテリアル、法線、およびテクスチャ座標を指定する。
Mesh CubeMesh {
8;                                // 8 個の頂点。
1.000000;1.000000;-1.000000;,     // 頂点 0。
-1.000000;1.000000;-1.000000;,    // 頂点 1。
-1.000000;1.000000;1.000000;,     // 同様に続く。
1.000000;1.000000;1.000000;,
1.000000;-1.000000;-1.000000;,
-1.000000;-1.000000;-1.000000;,
-1.000000;-1.000000;1.000000;,
1.000000;-1.000000;1.000000;;

12;                      // 12 個の面。
3;0,1,2;,                // 面 0 には 3 個の頂点がある。
3;0,2,3;,                // 同様に続く。
3;0,4,5;,
3;0,5,1;,
3;1,5,6;,
3;1,6,2;,
3;2,6,7;,
3;2,7,3;,
3;3,7,4;,
3;3,4,0;,
3;4,7,6;,
3;4,6,5;;

// すべての必須データが定義された。ここで、ファイル フォーマットの
// 階層構造的性質を使ってオプションのデータを定義する。
MeshMaterialList {
2;                    // 使用されるマテリアルの数。
12;                   // 各面のマテリアル。
0,                    // 面 0 は最初のマテリアルを使用する。
0,
0,
0,
0,
0,
0,
0,
1,                    // 面 8 は 2 番目のマテリアルを使用する。
1,
1,
1;;
{RedMaterial}         // マテリアル 0 および 1 の
{GreenMaterial}       // 定義への参照。
}
MeshNormals {
8;                    // 8 個の法線を定義する。
0.333333;0.666667;-0.666667;,
-0.816497;0.408248;-0.408248;,
-0.333333;0.666667;0.666667;,
0.816497;0.408248;0.408248;,
0.666667;-0.666667;-0.333333;,
-0.408248;-0.408248;-0.816497;,
-0.666667;-0.666667;0.333333;,
0.408248;-0.408248;0.816497;;
12;                   // 12 個の面に対して法線を定義する。
3;0,1,2;,
3;0,2,3;,
3;0,4,5;,
3;0,5,1;,
3;1,5,6;,
3;1,6,2;,
3;2,6,7;,
3;2,7,3;,
3;3,7,4;,
3;3,4,0;,
3;4,7,6;,
3;4,6,5;;
}
MeshTextureCoords {
8;                        // 各頂点に対してテクスチャ座標を定義する。
0.000000;1.000000;
1.000000;1.000000;
0.000000;1.000000;
1.000000;1.000000;
0.000000;0.000000;
1.000000;0.000000;
0.000000;0.000000;
1.000000;0.000000;;
}
}


テクスチャの追加

テクスチャを追加するには、ファイル フォーマットの階層構造的な性質を使って、オプションの TextureFilename データ オブジェクトを Material データ オブジェクトに追加する。Material オブジェクトは次のようになる。

Material RedMaterial {
1.000000;0.000000;0.000000;1.000000;;    // R = 0.0, G = 1.0, B = 0.0
0.000000;
0.000000;0.000000;0.000000;;
0.000000;0.000000;0.000000;;
TextureFilename {
"tex1.ppm";
}
}
Material GreenMaterial {
0.000000;1.000000;0.000000;1.000000;;     // R = 0.0, G = 1.0, B = 0.0
0.000000;
0.000000;0.000000;0.000000;;
0.000000;0.000000;0.000000;;
TextureFilename {
"win95.ppm";
}
}


フレームとアニメーションの追加

ここでは、単純なキューブにフレームとアニメーションを追加する方法を説明する。

  • フレームの操作
  • AnimationSets とアニメーションの操作


フレームの操作

フレームは、次の構造を持たなければならない。

Frame Aframe {        // わかりやすいフレーム名を付ける。
FrameTransformMatrix {
...transform data...
}
[ Meshes ] and/or [ More frames]
}

定義済みのキューブ メッシュをフレーム内に置き、正規行列でトランスフォームする。その後、このフレームにアニメーションを適用する。

Frame CubeFrame {
FrameTransformMatrix {
1.000000, 0.000000, 0.000000, 0.000000,
0.000000, 1.000000, 0.000000, 0.000000,
0.000000, 0.000000, 1.000000, 0.000000,
0.000000, 0.000000, 0.000000, 1.000000;;
}
{CubeMesh}        // メッシュをインラインに置くこともできるが、
                  // ここではオブジェクト参照を使用する。
}


AnimationSets とアニメーションの操作

アニメーションは、一連のキーで定義する。キーとは、スケーリング処理、向き、または位置に関連付けられた、時間の値である。

Animation Animation0 {        // わかりやすい名前を付ける。
{ Frame that it applies to&em;normally a reference }
AnimationKey {
...animation key data...
}
{ ...more animation keys... }
}

アニメーションはその後 AnimationSets にグループ化される:

AnimationSet AnimationSet0 { // わかりやすい名前を付ける。
{ an animation?could be inline or a reference }
{ ... more animations ... }
}

ここで、アニメーション内でキューブを移動する。

AnimationSet AnimationSet0 {
Animation Animation0 {
{CubeFrame}    // キューブを含むフレームを使用する。
AnimationKey {
2;             // 位置座標キー。
9;             // 9 キー。
10; 3; -100.000000, 0.000000, 0.000000;;,
20; 3; -75.000000, 0.000000, 0.000000;;,
30; 3; -50.000000, 0.000000, 0.000000;;,
40; 3; -25.500000, 0.000000, 0.000000;;,
50; 3; 0.000000, 0.000000, 0.000000;;,
60; 3; 25.500000, 0.000000, 0.000000;;,
70; 3; 50.000000, 0.000000, 0.000000;;,
80; 3; 75.500000, 0.000000, 0.000000;;,
90; 3; 100.000000, 0.000000, 0.000000;;;
}
}
}

詳細については、Animation および AnimationSet テンプレートを参照すること。


3D モデルから X ファイルへの変換とエクスポート

Microsoft® Direct3D® は、3D モデルから .x ファイル フォーマットへ変換およびエクスポートするために次のツールを提供している。

  • Conv3ds.exe
  • XSkinExp.dle


Conv3ds.exe

Conv3ds.exe ユーティリティは、Autodesk 3-D Studio などのモデリング パッケージで作成した 3 次元 (3D) モデルを、Microsoft® DirectX® のファイル フォーマットに変換する。このユーティリティは、デフォルトではテンプレートなしでバイナリの .x ファイルを作成する。

説明するトピックは次のとおりである。

  • Conv3ds.exe の実行
  • Conv3ds.exe のオプション引数の指定
  • Lightwave オブジェクトからの 3DS ファイルの作成
  • ヒントとコツ


Conv3ds.exe の実行

Conv3ds.exe をオプションなしで実行すると、フレームの階層を含む .x ファイルが作成される。たとえば、次のコマンドを実行すると、.3ds ファイルから File.x という名前の .x ファイルが作成される。

conv3ds File.3ds

オプションを指定して Conv3ds.exe を実行する場合については、「Conv3ds.exe のオプション引数の指定」を参照すること。


Conv3ds.exe のオプション引数の指定

.3ds ファイルにキー フレーム データが含まれている場合は、-A オプションを使用すると、アニメーション セットを含む .x ファイルが作成される。コマンドの例を次に示す。

conv3ds -A File.3ds

File.3ds パラメータは、変換するファイルの名前である。

-m オプションを使用すると、.3ds ファイル内のすべてのオブジェクトから作成された 1 つのメッシュを含む x. ファイルが作成される。

conv3ds -m File.3ds

-T オプションを使用すると、すべてのオブジェクトとフレーム階層が 1 つの最上位フレーム内にラップされる。このオプションを使用することで、.3ds ファイル内のすべてのフレームとオブジェクトを 1 つの呼び出しでロードできる。.x ファイル内の、最初の最上位フレーム階層がロードされる。ほかのすべてのフレームとメッシュを含むフレームは、.3ds 拡張子なしで「x3ds_filename」と呼ばれる。-T オプションは、-m オプションと一緒に使った場合は効力がない。

-s オプションを使うと、.3ds ファイル内で変換されるすべてのオブジェクトのスケーリング係数を指定できる。たとえば、次のコマンドを実行すると、すべてのオブジェクトが 10 倍の大きさになる。

conv3ds -s10 File.3ds

次のコマンドを実行すると、すべてのオブジェクトが 10 分の 1 の大きさになる。

conv3ds -s0.1 File.3ds

-r オプションを使用すると、.3ds ファイルが変換されるときの面のワインディング順序が逆になる。.3ds ファイルを変換して Microsoft® Direct3D® で表示したときにオブジェクトが裏返しに表示される場合は、-r オプションを使って変換し直さなければならない。.3ds ファイルとしてエクスポートされた Lightwave モデルはすべてこのオプションを使って変換する必要がある。詳細については、「Lightwave オブジェクトからの 3DS ファイルの作成」を参照すること。

-v オプションを使用すると、冗長出力モードがオンになる。このオプションには整数を指定する。次の表は、現在サポートされている整数を示している。

オプション | 動作
-v0 | デフォルト。冗長モード オフ。
-v1 | 不正オブジェクトに関する警告を印刷し、コンバータの動作の一般的な情報も印刷する。
-v2 | 基本的なキー フレーム情報、変換処理に含まれるオブジェクト、および保存されるオブジェクトに関する情報を印刷する。
-v3 | 非常に冗長なモード。デバッグ情報を利用する際に最も有用。

-e オプションを使用すると、次の例に示すように、テクスチャ マップ ファイルの拡張子を変更できる。

conv3ds -e"ppm" File.3ds

File.3ds にテクスチャ マップ ファイル Brick.gif を参照するオブジェクトが含まれている場合、.x ファイルはテクスチャ マップ ファイル Brick.ppm を参照する。コンバータはテクスチャ マップ ファイルを変換しない。変換後の .x ファイルがロードされる際、テクスチャ マップ ファイルは D3DPATH に存在していなければならない。D3DPath は、デフォルトの検索パスを設定する環境変数である。

-x オプションを使用すると、バイナリ .x ファイルでなくテキスト .x ファイルが作成される。テキスト ファイルの方がサイズが大きくなるが、手作業で簡単に編集できる。

-X オプションを使用すると、ファイル内に .x ファイル テンプレートが強制的に含まれる。デフォルトでは、テンプレートは含まれない。

-t オプションを使用すると、変換後の .x ファイルにテクスチャ情報が含まれない。

-N オプションを使用すると、変換後の .x ファイルに法線ベクトル情報が含まれない。いずれかのロードの呼び出しを行うと、.x ファイル内に法線ベクトルを持たないオブジェクトの法線ベクトルが生成される。

-c オプションを使用すると、変換後の .x ファイルにテクスチャ座標が含まれない。.3ds オブジェクトがテクスチャ座標を持たない場合、デフォルトでは、-m オプションを使用すると、出力されるメッシュには (0,0) uv テクスチャ座標が含まれる。

-f オプションを使用すると、変換後の .x ファイルにフレーム トランスフォーム行列が含まれない。

-z および -Z オプションを使用すると、.x ファイル内のオブジェクトによって参照されているすべてのマテリアルのアルファ面カラー値を調整することができる。たとえば次のコマンドを実行すると、0.2 未満のすべてのアルファ値に 0.1 が加算される。

conv3ds -z0.1 -Z0.2 File.3ds

次のコマンドを実行すると、すべてのアルファについて、アルファ値から 0.2 が減算される。

conv3ds-z"-0.2" -z1 File.3ds

-o オプションを使用すると、変換後の .x ファイルの名前を指定できる。

-h オプションを使用すると、通常キー フレーマーによって作成される、.3ds ファイル内のいずれの階層情報も解決されない。その代わり、-m オプションが使用されない場合は、すべてのオブジェクトが最上位レベルのフレーム内に出力される。


Lightwave オブジェクトからの 3DS ファイルの作成

Lightwave の Trans3d プラグインによってエクスポートされた .3ds ファイルについては、いくつかの注意点がある。このようなファイルを最適な状態で変換するには、次の Conv3ds.exe コマンドを使用する。

conv3ds -r -N -f -h -T|m trans3dfile.3ds

Trans3d および Lightwave オブジェクト エディタによって作成された .3ds オブジェクトはすべて、ワインディング順序を逆にする必要がある。そうしないと、表示したときに裏返しの状態になる。これらのファイルには、サーフェス法線ベクトル情報は含まれていない。


ヒントとコツ

Conv3ds.exe によって作成されたオブジェクトをロードしても表示されない場合は、スケール オプション -s に約 100 のスケール係数を指定する。これにより、.x ファイル内でオブジェクトのスケールが増加する。

オブジェクトをビューア内にロードして、フラット シェーディングからグーロー シェーディングに切り替えたときに、オブジェクトが濃い灰色に変わった場合は、-N オプションを使って変換し直す。

オブジェクトの変換後に、テクスチャがロードされない場合は、オブジェクトが -e オプションを使って .ppm または .bmp ファイルを参照していないかどうか確認する。また、テクスチャの幅および高さが 2 の累乗になっていることを確認する。さらに、テクスチャが D3DPATH のディレクトリに格納されていることを確認する。

現在、Conv3ds.exe は .3ds アニメーションで使われるダミー フレームをサポートしていないため、ダミー フレームは無視される。ただし、子オブジェクトはすべて変換される。


XSkinExp.dle

XSkinExp.dle は extras ディレクトリにある。これは 3dsmax のエクスポータとして使用される。使用方法については、XSkinExp.dle に付属する readme ファイルを参照すること。


プログラミングのヒントおよびツール

ここでは、Microsoft® DirectX® Graphics アプリケーションを効率的に開発するための情報を記述する。説明するトピックは、次のとおりである。

  • トラブルシューティング
  • パフォーマンスの最適化
  • マルチスレッド処理の問題
  • デバイス ウィンドウの処理
  • 以前のドライバの処理
  • マルチモニタ システムの処理
  • ウィンドウ モードのマルチビュー


トラブルシューティング

ここでは、Microsoft® Direct3D® アプリケーションの開発中に発生する可能性がある問題を一般的なカテゴリ別に示し、その回避方法について説明する。

  • デバイスの作成
  • ライティング済み頂点の使い方
  • 何も表示されない
  • デバッグ
  • ボーランド浮動小数点初期化
  • パラメータの妥当性検査


デバイスの作成

デバイスの作成中にアプリケーションが異常終了した場合、次の共通のエラーを調べる。

  • デバイス能力、特にレンダリング深度を調べる。
  • エラー コードを調べる。D3DERR_OUTOFVIDEOMEMORY にエラーがあると考えられる。
  • デバッグ DirectX DLL を使用して、デバッガに表示される出力メッセージを確認する。


ライティング済み頂点の使い方

ライティング済み頂点を使用するアプリケーションの場合、D3DRS_LIGHTING レンダリング ステートを FALSE に設定して、Microsoft® Direct3D® ライティング エンジンを無効にする必要がある。デフォルトでは、ライティングは有効になっており、入力頂点にゼロ以外のカラー値が含まれていても、システムは法線ベクトルを含んでいない頂点の色を 0 (黒) に設定する。本来、ライティング済み頂点には頂点法線が含まれないので、ライティング エンジンが有効になっていると、Direct3D に渡される色情報はレンダリングの際にすべて失われる。

独自のラインティングを実行するアプリケーションにとって、頂点カラーが重要であることは言うまでもない。システムによるデフォルト値の使用を回避するために、D3DRS_LIGHTING を FALSE に設定すること。


何も表示されない

アプリケーションを実行しても何も表示されない場合、次の共通のエラーを調べる。

  • 三角形がなくなっていないことを確認する。
  • 三角形がカリングされていないことを確認する。
  • トランスフォームが内部的に一貫していることを確認する。
  • ビューポートの設定を調べて、三角形の表示が可能になっていることを確認する。


デバッグ

Microsoft® Direct3D® アプリケーションのデバッグは困難を伴うことがある。すべての戻り値 (Direct3D プログラミングにおいて特に重要な要素であるが、ハードウェアの実装によって大きく異なる) を調べるほか、次の手法を試してみる。

  • デバッグ DLL に切り替える。
  • ソフトウェア専用デバイスを強制的に使用し、ハードウェア アクセラレーションが使用可能であってもオフにする。
  • サーフェスを強制的にシステム メモリに配置する。
  • ウィンドウで実行するオプションを作成して、統合デバッガを使用できるようにする。

この一覧の 2 つ目と 3 つ目のオプションは、デバッガをハングさせることがある Win16 ロックを防止する。

また、次のエントリを Win.ini に追加してみる。

[Direct3D]
debug=3
[DirectDraw]
debug=3


ボーランド浮動小数点初期化

ボーランドのコンパイラは、Microsoft® Direct3D® との互換性がない方法で浮動小数点例外を報告する。この問題を解決するには、次に示すように、_matherr 例外ハンドラを含める。

// ボーランド浮動小数点初期化。
#include <math.h>
#include <float.h>

void initfp(void)
{
    // 浮動小数点例外を無効にする。
    _control87(MCW_EM,MCW_EM);
}

int _matherr(struct _exception  *e)
{
    e;               // 警告をキャッシュするダミー参照。
    return 1;        // エラー処理が完了。
}


パラメータの妥当性検査

パフォーマンス上の理由から、Microsoft® Direct3D® ランタイムのデバッグ バージョンでは、リテール バージョンの場合より多くのパラメータの妥当性検査を行う。リテール バージョンでは、妥当性検査がまったく行われないこともある。これを使用することで、アプリケーションでは低速なデバッグ ランタイム コンポーネントによって安定したデバッギングを実行でき、その後で高速なリテール バージョンを使用してパフォーマンスを調整し、最終的なリリースに備えることができる。

Direct3D のいくつかのメソッドでは、使用できる値に制限があるが、この制限は Direct3D ランタイムのデバッグ バージョンによってチェックされて実施されるだけであることが多い。アプリケーションはこの制限に従う必要がある。これに従っていないと、Direct3D のリテール バージョンで実行したときに、予想外の好ましくない結果が生じる可能性がある。たとえば、IDirect3Ddevice8::DrawPrimitive メソッドでは、このメソッドでレンダリングするプリミティブの個数を示すパラメータ (PrimitiveCount) を使用する。このメソッドで使用できる値の範囲は 0 ～ D3DMAXNUMPRIMITIVES である。Direct3D のデバッグ バージョンで、D3DMAXNUMPRIMITIVES 個より多くのプリミティブを渡した場合、メソッドは異常終了し、エラー ログにエラー メッセージを出力して、アプリケーションにエラー値を返す。逆に、ランタイムのリテール バージョンで実行している場合にアプリケーションで同じエラーが発生したときは、動作は不定である。パフォーマンス上の理由から、メソッドはパラメータの妥当性検査を行わない。したがって、パラメータが有効でない場合には、その状況に依存した予想外の動作が生じる。場合によっては、呼び出しが行われることもある。また、場合によっては、その呼び出しに起因して Direct3D でメモリ障害が発生することもある。無効な呼び出しが特定のハードウェア構成と DirectX のバージョンで一貫して機能したとしても、ほかのハードウェアや DirectX の今後のリリースで機能することは保証されない。

リテール Direct3D ランタイム ファイルでアプリケーションを実行している場合に、説明できない障害が発生したときは、デバッグ バージョンに対してテストを行い、アプリケーションで無効なパラメータを渡している箇所がないかどうかを慎重に調べること。


パフォーマンスの最適化

3D グラフィックスを使用するリアルタイム アプリケーションの開発者にとって、パフォーマンスの最適化は関心事の 1 つである。ここでは、最高のパフォーマンスが得られるコードを記述するにあたってのガイドラインについて説明する。

次のトピックで説明するガイドラインは、すべての Microsoft® Direct3D® アプリケーションに対して使用できる。

  • パフォーマンスに関する一般的なヒント
  • データベースおよびカリング
  • プリミティブのバッチ処理
  • ライティングに関するヒント
  • テクスチャ サイズ
  • 動的な頂点およびインデックス バッファの使い方
  • メッシュの使い方
  • Z バッファのパフォーマンス
  • 頂点シェーダの最適化


パフォーマンスに関する一般的なヒント

いくつかの一般的なガイドラインに従って、アプリケーションのパフォーマンスを向上させることができる。

  • クリア処理は必要なときにだけ行う。
  • ステートの変更は最小限に抑える。
  • パースペクティブ補正は必要なときにだけ使用する。
  • できるだけ小さなテクスチャを使用する。
  • システム リソースの共有のバランスを崩すような特殊効果はなるべく使用しない。
  • アプリケーションのパフォーマンスを絶えずテストする。
  • ハードウェア アクセラレーションとソフトウェア エミュレーションの両方でアプリケーションが正常に実行されることを確認する。


データベースおよびカリング

Microsoft® Direct3D® の優れたパフォーマンスを実現するための鍵となるのは、ワールド内のオブジェクトを収める信頼性あるデータベースを構築することである。これはラスタ化やハードウェアの改善より重要なことである。

ポリゴンの個数は、管理できる範囲内で最小限に抑える必要がある。ポリゴンの個数を少なくするには、最初からその個数が少なくて済むようなモデルを構築する。ポリゴンの追加は、開発段階の後半で、パフォーマンスを犠牲にせずに追加できる場合に行う。最速のポリゴンは描画しないポリゴンであることを覚えておく。


プリミティブのバッチ処理

実行時に最高のレンダリング パフォーマンスを得るには、プリミティブをバッチ処理し、レンダリングステートの変更回数をできるだけ少なくする。たとえば、1 つのオブジェクトで 2 つのテクスチャを使用している場合、最初のテクスチャを使用する三角形をグループ化し、必要なレンダリング ステートをその三角形に付加してテクスチャを変更する。次に、もう 1 つのテクスチャを使用する三角形をすべてグループ化する。Microsoft® Direct3D® の最も単純なハードウェア サポートは、Hardware Abstraction Layer (HAL) を介して、レンダリング ステートのバッチおよびプリミティブのバッチによって呼び出される。命令のバッチ処理を効率的に行えば、実行時の HAL の呼び出し回数が減少する。


ライティングに関するヒント

ライトを適用した場合、レンダリングされる各フレームに頂点ごとの負荷が加わる。したがって、アプリケーションでライトを慎重に使用すれば、パフォーマンスの大幅な向上が見込める。次のヒントのほとんどは、最速のコードは呼び出されないコードであるという考えに基づく。

  • 光源は必要最小限で使用する。全体的なライティング レベルを増加させることだけが必要な場合は、新しい光源を追加するのではなく、アンビエント ライトを使用する。負担がずっと軽くなる。
  • ディレクショナル ライトは、ポイント ライトやスポットライトより負担が軽い。ディレクショナル ライトの場合、光の方向が固定されているため、頂点ごとに計算する必要がない。
  • スポットライトは、ポイント ライトより負担が軽い。光のコーンの外側の領域の計算はすばやく行われるためである。スポットライトの負担が軽いかどうかは、スポットライトでシーンを照らす量によって異なる。
  • 範囲パラメータを使用して、必要な部分にだけライトを照らす。範囲外にあるすべてのライトのタイプはすぐに終了する。
  • スペキュラ ハイライトは、負担がおよそ 2 倍になるため、必要なときにだけ使用する。D3DRS_SPECULARENABLE レンダリング ステートには、できるだけデフォルト値 0 を設定する。マテリアルを定義するときは、スペキュラ強度値をゼロに設定して、そのマテリアルに対するスペキュラ ハイライトをオフにする。単にスペキュラ色を 0,0,0 に設定するだけでは不十分である。


テクスチャ サイズ

テクスチャ マッピングのパフォーマンスは、メモリの速度に大きく依存する。アプリケーションのテクスチャをキャッシュする際のパフォーマンスを最大限に高める方法がいくつかある。

  • テクスチャは小さくする。テクスチャが小さければ、メイン CPU の 2 次キャッシュに格納される可能性が高くなる。
  • プリミティブごとにテクスチャを変更しない。ポリゴンは使用するテクスチャの順にグループ化する。
  • できるだけ正方形テクスチャを使用する。寸法が 256 × 256 のテクスチャが最速である。たとえば、アプリケーションで 128 × 128 の 4 つのテクスチャを使用する場合、これらのテクスチャで同じパレットを使い、すべてのテクスチャを 256 × 256 の 1 つのテクスチャに配置する。この方法を使用すると、テクスチャのスワップ量も減少する。もちろん、上で説明したように、テクスチャはできるだけ小さくする必要があるので、アプリケーションで 256 × 256 のテクスチャが必要な場合を除いては、そのようなテクスチャを使用してはならない。


動的な頂点およびインデックス バッファの使い方

動的な頂点およびインデックス バッファには、サイズと使用方法に基づいてパフォーマンスに違いがある。次の使用方法を参考に、Lock メソッドの Flags パラメータに D3DLOCK_DISCARD を使用するか、または D3DLOCK_NOOVERWRITE を使用するかを判断する。

使用方法 1 :

for loop()
{
    pBuffer->Lock(...D3DLOCK_DISCARD...); // 新しいポインタを返して、
                                          // ハードウェアが機能停止しないことを
                                          // 保証する。
    Fill data (optimally 1000s of vertices/indices, no fewer) in pBuffer.
    pBuffer->Unlock()
    Change state(s).
    DrawPrimitive() or DrawIndexedPrimitive()
}

使用方法 2 :

for loop()
{
    pVB->Lock(...D3DLOCK_DISCARD...);//新しいポインタが返ることによって
                                      //ハードウェアがストールしない
                                      //ようにする。
    Fill data (optimally 1000s of vertices/indices, no fewer) in pBuffer.
    pBuffer->Unlock
    for loop( 100s of times )
    {
        Change State
        DrawPrimitive() or DrawIndexPrimitives() //Tens of primitives
    }
}

使用方法 3 :

for loop()
{
    If there is space in the Buffer
    {
        // 頂点やインデックスを追加する。
        pBuffer->Lock(�D3DLOCK_NOOVERWRITE�);
    }
    Else
    {
        // 先頭に戻る。
        pBuffer->Lock(�D3DLOCK_DISCARD�);
    }
    Fill few 10s of vertices/indices in pBuffer
    pBuffer->Unlock
    Change State
    DrawPrimitive() or DrawIndexedPrimitive() // 数個のプリミティブ。

}

使用方法 1 は、使用方法 2 または 3 より処理は速いが、一般的には実用に向かない。アプリケーションで各 Lock に対して平均 2、3000 個の頂点やインデックスを追加する場合、使用方法 2 の方が使用方法 3 より処理が速い。平均より少ない場合には、使用方法 3 の方が速い。どの Lock メソッドが高速であるかに関しては確かな答えはなく、いろいろな方法を試すことで最善の方法を見つける。


メッシュの使い方

メッシュを最適化するには、Microsoft® Direct3D® のインデックス付き三角形ストリップではなく、インデックス付き三角形を使用する。ハードウェアは、連続する三角形の 95% が実際にストリップを形成しているものとして検出し、それに応じて調整を行う。多くのドライバは、レガシー ハードウェアに対してもこのような処理を行う。

以下に、メッシュのさまざまな属性について示す。

属性 ID

属性 ID は、面のグループを属性グループに関連付ける値である。この ID は、DrawSubset で描画する面のサブセットを記述する。属性 ID は、属性バッファ内の面に対して指定される。属性 ID の実際の値は、32 ビットに適合すればどのような値でもかまわないが、一般には 0 ～ n (属性数) を使用する。

属性バッファ

属性バッファは、各面が属する属性グループを指定する DWORD (各面に 1 つ) の配列である。このバッファは、メッシュの作成時にゼロに初期化されるが、ロード ルーチンによって値を指定するか、ID 0 の属性が複数個必要な場合にはユーザーによって指定するかのいずれかの必要がある。このバッファには、Optimize で属性に基づいてメッシュをソートするために使用する情報が格納される。属性テーブルが提示されていない場合、DrawSubset はこのバッファを調べて、描画する指定の属性の面を選択する。

属性テーブル

属性テーブルは、メッシュによって所有および保持される構造体である。これを生成するには、属性ソート機能または最適化の強化機能を有効にして Optimize を呼び出す必要がある。属性テーブルは、プリミティブを描画する単一の呼び出しを DrawSubset にすばやく初期化するために使用される。また、プログレッシブ メッシュもこの構造体を保持するので、現在の詳細レベル (LOD) でアクティブな面と頂点を表示することができる。


Z バッファのパフォーマンス

シーンが前から後にレンダリングされるように、z バッファリングを使用してテクスチャ処理を行うと、アプリケーションのパフォーマンスを向上させることができる。テクスチャを適用し、z バッファを使用したプリミティブは、走査線単位で z バッファについて事前にテストされる。前にレンダリングされたポリゴンによって走査線が隠れている場合は、そのポリゴンがシステムによってすばやく効率的に除去される。z バッファリングによってパフォーマンスは向上するが、この手法はシーンでオーバードローを何度も行うときに最も有効である。オーバードローとは、スクリーン ピクセルの平均書き込み回数である。オーバードローを正確に計算するのは難しいが、近似値を求めることはできる。オーバードローの平均が 2 より小さい場合には、z バッファリングをオフにし、シーンを後から前にレンダリンすると、最高のパフォーマンスが得られる。

高速なパーソナル コンピュータの場合、ソフトウェアによるシステム メモリへのレンダリングの方が、ビデオ メモリへのレンダリングより高速であることが多い。ただし、この場合、ダブル バッファリングやハードウェア アクセラレーションによるクリア処理は使用できない。アプリケーションでシステム メモリまたはビデオ メモリのいずれにもレンダリングでき、どちらが高速であるかをテストするルーチンがあれば、現在のシステムで最適な方法を利用することができる。Microsoft® Direct3D® の SDK に収録されるサンプル コードでは、この方法を示している。速度をテストする方法がほかにないため、両方の方法を実装する必要がある。速度はコンピュータ間で大きく異なり、メインメモリ アーキテクチャや、使用するグラフィックス アダプタの種類に依存する。


頂点シェーダの最適化

頂点シェーダを最適化するには、次に示すようにいくつかの方法がある。

  • 頂点バッファのスイッチを最小化すること。
  • 可能なら静的頂点バッファを使うこと。
  • オブジェクトごとではなく、静的オブジェクトに対して FVF ごとに 1 つの大きな頂点バッファを使うこと。
  • シェーダ内で必要でないなら、出力レジスタをコピーしない。

たとえば、

       mad r1,c[2],c[3]
       mov oD0, r1

ではなく、次のようにする。

       mad oD0, r1, c[2], c[3]


マルチスレッド処理の問題

フルスクリーンの Microsoft® Direct3D® アプリケーションは、Direct3D ランタイムにウィンドウ ハンドルを提供する。このウィンドウはランタイムによってフックされる。これは、アプリケーションのウィンドウ メッセージ プロシージャに渡されたすべてのメッセージが、まず、Direct3D ランタイム独自のメッセージ処理プロシージャによって調べられたことを意味する。

ディスプレイ モードの変更は、下位のオペレーティング システムに組み込まれたサポート ルーチンによってもたらされる。モードが変更されると、システムは複数のメッセージをすべてのアプリケーションにある要素を全要素にコピーする。Direct3D アプリケーションでは、メッセージはウィンドウ プロシージャ スレッドで受信される。このスレッドは、IDirect3DDevice8::Reset または IDirect3D8::CreateDevice (またはディスプレイ モードを変更する場合がある IDirect3DDevice8 の最後の IUnknown::Release) を呼び出したスレッドと必ずしも同じではない。Direct3D ランタイムは、複数のクリティカル セクションを内部で保持する。少なくとも 1 つのクリティカル セクションが、Reset または CreateDevice によるモード切り替えの後も保持されるので、これらのクリティカル セクションは、アプリケーションがモード変更に関連するウィンドウ メッセージを受信した後も保持される。

この設計は、暗にマルチスレッド アプリケーションを意図している。特に、アプリケーションはウィンドウ メッセージ処理スレッドを Direct3D スレッドから完全に分離しなければならない。1 つのスレッドでモード変更を行いながら、別のスレッドで Direct3D の呼び出しを行うアプリケーションは、デッドロックの危険性がある。

このような理由から、Direct3D では、Reset、CreateDevice、TestCoorperativeLevel、または IDirect3DDevice8 の最後の Release の各メソッドは、ウィンドウ メッセージを処理するスレッドと同じスレッドからのみ呼び出すことができるように設計されている。


デバイス ウィンドウの処理

ここでは、Microsoft® Direct3D® アプリケーションでデバイス ウィンドウを処理する際に発生する可能性がある問題について説明する。

  • Direct3D は、Direct3D メッセージ処理関数を使って、デバイス ウィンドウではなく、フォーカス ウィンドウだけをフックし、フォーカス ウィンドウ メッセージだけを処理する。したがって、フォーカス ウィンドウは、すべてのデバイス ウィンドウの親でなければならない。
  • すべてのアプリケーション (マルチ モニタまたはシングル モニタ) で、少なくとも 1 つのデバイス ウィンドウがフォーカス ウィンドウでなければならない。これは、実質的に、シングル モニタ システムでフォーカス ウィンドウの子ウィンドウをデバイス ウィンドウとして使用できないことを意味する。親フォーカス ウィンドウを、フォーカス ウィンドウおよびデバイス ウィンドウの両方として使用する必要がある。マルチ モニタ システムの場合、少なくとも 1 つのモニタがフォーカス ウィンドウをデバイス ウィンドウとして使用する必要がある。


以前のドライバの処理

ここでは、DirectX 8.0 以前のバージョンの DirectX 用に作成されたドライバ上で Microsoft® DirectX® 8.0 を処理する場合に発生する可能性のある問題を示す。

  • TnLHAL デバイスを処理する場合、フォグの強度は計算されるが、この値に絶対値演算は適用されない。計算結果が負の場合、値は負のままである。このような状況を回避する最善の方法は、トランスフォームを正しく設定することである。次善の策としては、フォグの開始値とフォグの終了値を負になるようにする方法がある。

D3DCAPS8 の MaxStream メンバを照会することで、ドライバが DirectX 8.0 用に作成されていないことを検出できる。この値が 0 である場合、ドライバは DirectX 8.0 ドライバではない。


マルチモニタ システムの処理

排他的なフルスクリーン モードの概念が Microsoft® DirectX® 8.0 には保持されているが、IDirect3D8::CreateDevice および IDirect3DDevice8::Reset メソッドの呼び出しでは完全に非明示的に保持される。フルスクリーン処理でデバイスのリセットまたは作成が正常に行われると、そのデバイスを作成した Microsoft® Direct3D® オブジェクトがシステム上のすべてのアダプタを所有しているものとしてマークされる。この状態は排他モードと呼ばれ、この時点で Direct3D8 オブジェクトは排他モードを所有している。排他モードでは、ほかの Direct3D8 オブジェクトによって作成されたデバイスがフルスクリーン処理を行ったりビデオ メモリを割り当てることはできない。また、Direct3D8 オブジェクトが排他モードであると見なしたときには、フルスクリーンになったデバイス以外のデバイスはすべて消失状態になる。消失したデバイスを処理する方法については、「消失したデバイス」を参照すること。

排他モードでは、その Direct3D8 オブジェクトに、デバイスが使用するフォーカス ウィンドウが通知される。その Direct3D8 オブジェクトが所有する最後のフルスクリーン デバイスがウィンドウ モードにリセットされるか破壊されると、排他モードは解放される。

Direct3D8 オブジェクトが排他モードを所有するとき、デバイスは 2 つのカテゴリに分類される。最初のカテゴリのデバイスは、既にフルスクリーンであるデバイスを作成したものと同じ Direct3D8 オブジェクトによって作成され、既にフルスクリーンであるデバイスと同じフォーカス ウィンドウを持ち、ほかのフルスクリーン デバイスとは別のアダプタを表す。このカテゴリのデバイスは、制限なく Reset または作成でき、消失状態になることはない。このカテゴリのデバイスは、フルスクリーン モードにすることもできる。

このカテゴリに入らないデバイス (別の Direct3D8 オブジェクトによって作成されたか、別のフォーカス ウィンドウで作成されたか、既にフルスクリーンのデイバイスがあるアダプタに作成されたデバイス) はリセットできず、排他モードがなくなるまで消失状態のままになる。

実際には、マルチモニタ アプリケーションでは複数のデバイスをフルスクリーン モードにすることができるが、それは、これらのデバイスがすべて異なるアダプタのデバイスであり、同じ Direct3D8 オブジェクトによって作成され、しかも同じフォーカス ウィンドウを共有する場合に限られる。


ウィンドウ モードのマルチビュー

IDirect3DDevice8 インターフェイスを介して所有し操作できるスワップ チェーンに加えて、同じデバイスから複数のビューに提示するための追加スワップ チェーンを作成できる。アプリケーションは、一般的に、IDirect3DDevice8::CreateAdditionalSwapChain メソッドを使用してビューごとに 1 つのスワップ チェーンを作成し、そのスワップ チェーンを特定のウィンドウに関連付ける。アプリケーションは、各スワップ チェーンのバック バッファにイメージをレンダリングした後、個々に提示する。

各アダプタでは一度に 1 つのスワップ チェーンしかフルスクリーンにできない。


DirectX Graphics C/C++ チュートリアル

このチュートリアルでは、C/C++ アプリケーションで Microsoft® Direct3D® および Direct3DX を使用して、共通のタスクを行う方法を説明する。各タスクは、必要なステップに分かれている。理解しやすくするために、ステップがさらに細かいステップに分かれているチュートリアルもある。

次のチュートリアルを記述する。

  • チュートリアル 1 : デバイスの作成
  • チュートリアル 2 : 頂点のレンダリング
  • チュートリアル 3 : 行列の使い方
  • チュートリアル 4 : ライトの作成および使い方
  • チュートリアル 5 : テクスチャ マップの使い方
  • チュートリアル 6 : メッシュの使い方

注 これらのチュートリアルのサンプル コードはソース プロジェクトに含まれており、その場所は各チュートリアルに示されている。

各チュートリアルのサンプル ファイルは C++ で記述されている。C コンパイラを使用している場合、サンプル ファイルに適切な変更を加えて、エラーなくコンパイルできるようにしなければならない。少なくとも、インターフェイス メソッドには、vtable ポインタと this ポインタを追加する必要がある。

添付されているサンプル コード中のコメントには、Microsoft Platform Software Development Kit (SDK) のソース ファイルとは異なるものもある。変更は、サンプル コードの動作が変わるのを避けるため、コメントだけに限定し、簡潔にするためだけに行っている。

参照

DirectX Graphics C/C++ サンプル


チュートリアル 1 : デバイスの作成

Microsoft® Direct3D® を使用するには、まず、アプリケーション ウィンドウを作成した後、Direct3D オブジェクトを作成して初期化する。ユーザーは、オブジェクトが実装している COM インターフェイスを使用してオブジェクトを処理し、シーンのレンダリングに必要な従属オブジェクトを生成する。このチュートリアルで使用するサンプル プロジェクト CreateDevice では、Direct3D デバイスを作成し、青い画面をレンダリングすることによって、このタスクを示す。

このチュートリアルでは、次のステップで、Direct3D を初期化し、シーンをレンダリングして、最後にシャット ダウンを行う。

  • ステップ 1 : ウィンドウの作成
  • ステップ 2 : Direct3D の初期化
  • ステップ 3 : システム メッセージの処理
  • ステップ 4 : シーンのレンダリングおよび表示
  • ステップ 5 : シャット ダウン

注 CreateDevice サンプル プロジェクトのパスは次のとおりである。

(SDK ルート)\Samples\Multimedia\Direct3D\Tutorials\Tut01_CreateDevice


ステップ 1 : ウィンドウの作成

どの Microsoft® Windows® アプリケーションでも、実行時に、まず行わなければならないことは、アプリケーション ウィンドウを作成し、ユーザーに表示することである。このために、CreateDevice サンプル プロジェクトでは、まず WinMain 関数の実行から開始する。次のサンプル コードは、ウィンドウを初期化する。

INT WINAPI WinMain( HINSTANCE hInst, HINSTANCE, LPSTR, INT )
{
    // ウィンドウ クラスを登録する。
    WNDCLASSEX wc = { sizeof(WNDCLASSEX), CS_CLASSDC, MsgProc, 0L, 0L,
                      GetModuleHandle(NULL), NULL, NULL, NULL, NULL,
                      "D3D Tutorial", NULL };
    RegisterClassEx( &wc );

    // アプリケーションのウィンドウを作成する。
    HWND hWnd = CreateWindow( "D3D Tutorial", "D3D Tutorial 01: CreateDevice",
                              WS_OVERLAPPEDWINDOW, 100, 100, 300, 300,
                              GetDesktopWindow(), NULL, wc.hInstance, NULL );

上記のサンプル コードは、標準的な Windows プログラミングである。このサンプルでは、まず、"D3D Tutorial" と呼ばれるウィンドウ クラスを定義して、登録している。クラスを登録した後、そのクラスを使用する基本的な最上位レベルのウィンドウを作成する。このウィンドウには、幅 300 ピクセル、高さ 300 ピクセルのクライアント領域がある。このウィンドウにはメニューと子ウィンドウはない。このサンプルでは、WS_OVERLAPPEDWINDOW ウィンドウ スタイルを使用して、ウィンドウ アプリケーションに共通する最小化、最大化、および閉じるボタンの付いたウィンドウを作成する。サンプルをフルスクリーン モードで実行する場合は、ウィンドウ スタイルに WS_EX_TOPMOST を使用するとよい。このスタイルでは、作成したウィンドウはほかのすべてのウィンドウよりも手前に表示され、このウィンドウを非アクティブにしても最も手前に表示される。このウィンドウが作成されると、サンプル コードは Microsoft Win32® 標準関数を呼び出して、ウィンドウの表示と更新を行う。

アプリケーション ウィンドウが準備できると、Microsoft Direct3D® の主要オブジェクトの設定を開始できる。これについては、「ステップ 2 : Direct3D の初期化」で説明する。


ステップ 2 : Direct3D の初期化

CreateDevice サンプル プロジェクトでは、ウィンドウの作成後、WinMain から呼び出されるアプリケーション定義関数 InitD3D で Microsoft® Direct3D® の初期化を実行する。アプリケーション ウィンドウを作成すると、シーンのレンダリングに使用する Direct3D オブジェクトの初期化を開始できる。この処理には、Direct3D オブジェクトの作成、プレゼンテーション パラメータの設定、および Direct3D デバイスの作成が含まれる。

Direct3D オブジェクトを作成した後、IDirect3D8::CreateDevice メソッドを使用して Direct3D デバイスを作成できる。また、Direct3D オブジェクトを使って、デバイス、タイプ、モードなどを列挙することもできる。次のサンプル コードでは、Direct3DCreate8 関数を使用して Direct3D オブジェクトを作成している。

if( NULL == ( g_pD3D = Direct3DCreate8( D3D_SDK_VERSION ) ) )
    return E_FAIL;

Direct3DCreate8 に渡されるパラメータは、常に D3D_SDK_VERSION だけである。これによって、使用する正しいヘッダー ファイルが Direct3D に通知される。ヘッダーまたはほかの変更によりアプリケーションのリビルドが必要になるたびに、この値はインクリメントされる。バージョンが一致しない場合、Direct3DCreate8 は失敗する。

次のステップでは、IDirect3D8::GetAdapterDisplayMode メソッドを使用して現在のディスプレイ モードを検出する。次のサンプル コードにそれを示す。

D3DDISPLAYMODE d3ddm;
if( FAILED( g_pD3D->GetAdapterDisplayMode( D3DADAPTER_DEFAULT, &d3ddm ) ) )
    return E_FAIL;

Direct3D デバイスを作成するときは、D3DDISPLAYMODE 構造体の Format メンバが使用される。ウィンドウ モードで実行する場合は、アダプタの現在のモードと一致するバック バッファを作成するために Format メンバが使用される。

D3DPRESENT_PARAMETERS のフィールドに入力することによって、3D アプリケーションの動作を指定できる。CreateDevice サンプル プロジェクトでは、Windowed メンバに TRUE、SwapEffect メンバに D3DSWAPEFFECT_DISCARD、および BackBufferFormat メンバに d3ddm.Format を設定している。

D3DPRESENT_PARAMETERS d3dpp;
ZeroMemory( &d3dpp, sizeof(d3dpp) );
d3dpp.Windowed   = TRUE;
d3dpp.SwapEffect = D3DSWAPEFFECT_DISCARD;
d3dpp.BackBufferFormat = d3ddm.Format;

最後のステップは、次のサンプル コードに示されているように、IDirect3D8::CreateDevice メソッドを使って Direct3D デバイスを作成することである。

if( FAILED( g_pD3D->CreateDevice( D3DADAPTER_DEFAULT, D3DDEVTYPE_HAL, hWnd,
                                  D3DCREATE_SOFTWARE_VERTEXPROCESSING,
                                  &d3dpp, &g_pd3dDevice ) ) )

上記のサンプル コードでは、D3DADAPTER_DEFAULT フラグを使って、デフォルトのアダプタを指定してデバイスを作成している。システムに複数のグラフィックス ハードウェア カードがインストールされていない限り、ほとんどの場合、システムのアダプタは 1 つだけである。ハードウェア デバイスをソフトウェア デバイスよりも優先することを指定するには、DeviceType パラメータに D3DDEVTYPE_HAL を指定する。このサンプル コードでは、D3DCREATE_SOFTWARE_VERTEXPROCESSING を使って、ソフトウェア頂点処理を使用することをシステムに指示している。D3DCREATE_HARDWARE_VERTEXPROCESSING を指定してハードウェア頂点処理を使用することをシステムに指示した場合、ハードウェア頂点処理をサポートするビデオ カードではパフォーマンスが大幅に向上することに注意すること。

Direct3D が初期化されたので、次のステップでは、システム メッセージを処理するメカニズムを作成する。これについては、「ステップ 3 : システム メッセージの処理」で説明する。


ステップ 3 : システム メッセージの処理

アプリケーション ウィンドウを作成し、Microsoft® Direct3D® を初期化したら、シーンのレンダリングを開始できる。通常、Microsoft Windows® アプリケーションはメッセージ ループのシステム メッセージを監視し、キューにメッセージがなければいつでもフレームのレンダリングを行う。ただし、CreateDevice サンプル プロジェクトでは、キューに WM_PAINT メッセージが入れられるまで待機する。このメッセージは、ウィンドウの全体または一部を再描画する必要があることをアプリケーションに通知する。

// メッセージ ループ。
MSG msg;
while( GetMessage( &msg, NULL, 0, 0 ) )
{
    TranslateMessage( &msg );
    DispatchMessage( &msg );
}

ループが実行されるたびに、DispatchMessage は MsgProc を呼び出して、キュー内のメッセージを処理する。WM_PAINT がキューに入れられると、アプリケーションは、ウィンドウを再描画するアプリケーション定義関数 Render を呼び出す。次に、Microsoft Win32® 関数 ValidateRect が呼び出されて、クライアント領域全体が検証される。

このメッセージ処理関数のサンプル コードを以下に示す。

LRESULT WINAPI MsgProc( HWND hWnd, UINT msg, WPARAM wParam, LPARAM lParam )
{
    switch( msg )
    {
        case WM_DESTROY:
            PostQuitMessage( 0 );
            return 0;

        case WM_PAINT:
            Render();
            ValidateRect( hWnd, NULL );
            return 0;
    }

    return DefWindowProc( hWnd, msg, wParam, lParam );
}

アプリケーションでシステム メッセージを処理するようになったので、次のステップでは、ディスプレイをレンダリングする。これについては、「ステップ 4 : シーンのレンダリングおよび表示」で説明する。


ステップ 4 : シーンのレンダリングおよび表示

シーンをレンダリングおよび表示するために、このステップのサンプル コードでは、バック バッファを青色にクリアし、バック バッファの内容をフロント バッファに転送して、フロント バッファを画面に表示している。

シーンをクリアするには、IDirect3DDevice8::Clear メソッドを呼び出す。

// バック バッファを青色にクリアする。
g_pd3dDevice->Clear( 0, NULL, D3DCLEAR_TARGET, D3DCOLOR_XRGB(0,0,255), 1.0f, 0 );

Clear が受け取る最初の 2 つのパラメータは、Microsoft® Direct3D® に、クリアする矩形の配列のサイズとアドレスを通知する。矩形の配列は、レンダリング ターゲット サーフェス上のクリアする領域を記述する。

通常、レンダリング ターゲット全体を覆う 1 つの矩形を使用する。これを行うには、最初のパラメータを 0 に、2 番目のパラメータを NULL に設定する。3 番目のパラメータは、メソッドの動作を決定する。レンダリング ターゲット サーフェス、関連深度バッファ、ステンシル バッファ、またはこの 3 つの任意の組み合わせをクリアすることができる。このチュートリアルでは、深度バッファを使用しないので、D3DCLEAR_TARGET 以外のフラグは使用しない。最後の 3 つのパラメータは、レンダリング ターゲット、深度バッファ、ステンシル バッファのクリア値を反映するように設定する。CreateDevice サンプル プロジェクトでは、レンダリング ターゲット サーフェスのクリア カラーを青 (D3DCOLOR_XRGB(0,0,255)) に設定している。最後の 2 つのパラメータは、対応するフラグが存在しないので、Clear メソッドで無視される。

ビューポートをクリアした後、CreateDevice サンプル プロジェクトは、次のサンプル コードに示すように、レンダリングの開始およびレンダリングの終了を Direct3D に通知する。

// シーンを開始する。
g_pd3dDevice->BeginScene();

// ここで、シーンのオブジェクトをレンダリングする。

// シーンを終了する。
g_pd3dDevice->EndScene();

IDirect3DDevice8::BeginScene および IDirect3DDevice8::EndScene メソッドは、レンダリングの開始時および終了時をそれぞれシステムに通知する。レンダリング メソッドは、この 2 つのメソッドの呼び出しの間でしか呼び出すことができない。レンダリング メソッドが正常に終了しなかった場合でも、BeginScene を再度呼び出す前に、EndScene を呼び出す必要がある。

シーンをレンダリングしたら、IDirect3DDevice8::Present メソッドを使ってシーンを表示する。

g_pd3dDevice->Present( NULL, NULL, NULL, NULL );

Present が受け取る最初の 2 つのパラメータは、転送元矩形と転送先矩形である。このステップのサンプル コードでは、この 2 つのパラメータを NULL に設定して、バック バッファ全体をフロント バッファに表示する。3 番目のパラメータは、このプレゼンテーションの転送先ウィンドウを設定する。このパラメータは NULL に設定されているので、D3DPRESENT_PARAMETERS の hWndDeviceWindow メンバが使用される。4 番目のパラメータは DirtyRegion パラメータで、ほとんどの場合 NULL に設定する必要がある。

このチュートリアルの最後のステップでは、アプリケーションをシャット ダウンする。これについては、「ステップ 5 : シャット ダウン」で説明する。


ステップ 5 : シャット ダウン

アプリケーションは、実行中のある時点で、シャット ダウンしなければならない。Microsoft® DirectX® アプリケーションをシャット ダウンするとは、アプリケーション ウィンドウを破棄するだけでなく、アプリケーションが使用しているすべての DirectX オブジェクトの割り当てを解除し、オブジェクトへのポインタを無効にすることを意味する。CreateDevice サンプル プロジェクトでは、WM_DESTROY メッセージを受け取ったときに、この処理を行うアプリケーション定義関数 Cleanup を呼び出す。

VOID Cleanup()
{
    if( g_pd3dDevice != NULL)
        g_pd3dDevice->Release();
    if( g_pD3D != NULL)
        g_pD3D->Release();
}

上記の関数は、各オブジェクトに対して IUnknown::Release メソッドを呼び出して、アプリケーションが使用している DirectX オブジェクトの割り当てを解除している。このチュートリアルは COM の規則に従っているため、ほとんどのオブジェクトに対する参照カウントはゼロになり、自動的にメモリから削除されるはずである。

シャット ダウンするとき以外にも、ユーザーがデスクトップ解像度や色深度を変更したときなどの通常の実行時に、使用中の Microsoft Direct3D® オブジェクトを破棄して再作成する必要が生じることもある。したがって、アプリケーションのクリーンアップ コードを作成しておき、必要な場合に呼び出すとよい。

このチュートリアルでは、デバイスの作成方法を示した。「チュートリアル 2 : 頂点のレンダリング」では、頂点を使用してジオメトリ形状を描画する方法を示す。


チュートリアル 2 : 頂点のレンダリング

Microsoft® Direct3D® で作成された作成されたアプリケーションでは、頂点を使ってジオメトリ形状を描画する。各 3D シーンには、このようなジオメトリ形状が 1 つまたは複数含まれる。Vertices サンプル プロジェクトでは、最も単純な図形である三角形を作成し、ディスプレイにレンダリングする。

このチュートリアルでは、次のステップで、頂点を使って三角形を作成する方法を示す。

  • ステップ 1 : カスタム頂点タイプの定義
  • ステップ 2 : 頂点バッファの設定
  • ステップ 3 : ディスプレイのレンダリング

注 Vertices サンプル プロジェクトのパスは次のとおりである。

(SDK ルート)\Samples\Multimedia\Direct3D\Tutorials\Tut02_Vertices

Vertices プロジェクトのサンプル コードは、CreateDevice プロジェクトのサンプル コードとほぼ同じである。このチュートリアルでは、頂点に固有のコードのみに注目し、Direct3D の初期化、Microsoft Windows® メッセージの処理、レンダリング、またはシャット ダウンについては説明しない。これらのタスクについては、「チュートリアル 1 : デバイスの作成」を参照すること。


ステップ 1 : カスタム頂点タイプの定義

Vertices サンプル プロジェクトでは、3 つの頂点を使って 2D の三角形をレンダリングする。ここでは、頂点を格納およびレンダリングするために使用される Microsoft® Direct3D® オブジェクトである、頂点バッファの概念を導入している。頂点は、カスタム頂点構造体および対応するカスタム FVF (柔軟な頂点フォーマット) を指定することによって、多くの方法で定義できる。Vertices サンプル プロジェクトの頂点のフォーマットを、次のサンプル コードに示す。

struct CUSTOMVERTEX
{
    FLOAT x, y, z, rhw; // 頂点のトランスフォーム後の位置座標。
    DWORD color;        // 頂点カラー。
};

上記の構造体は、カスタム頂点タイプのフォーマットを指定する。次のステップは、頂点バッファ内の頂点の内容を記述する FVF を定義することである。次のサンプル コードでは、上で作成したカスタム頂点タイプに対応する FVF を定義している。

#define D3DFVF_CUSTOMVERTEX (D3DFVF_XYZRHW|D3DFVF_DIFFUSE)

柔軟な頂点フォーマット フラグは、使用するカスタム頂点のタイプを指定する。上記のサンプル コードでは、D3DFVF_XYZRHW および D3DFVF_DIFFUSE フラグを使用して、カスタム頂点タイプがトランスフォームされた頂点と色成分を持つことを頂点バッファに通知している。

カスタム頂点フォーマットおよび FVF が指定されたので、次のステップでは、頂点バッファに頂点を入力する。これについては、「ステップ 2 : 頂点バッファの設定」で説明する。

注 Vertices サンプル プロジェクトの頂点はトランスフォームされている。つまり、頂点は既に 2D ウィンドウ座標で表されている。これは、ポイント (0,0) が左上隅であり、正の x 軸が右方向、正の y 軸が下方向であることを意味する。これらの頂点にライトを当てることもできる。これは、頂点は Direct3D ライティングを使用していないが、独自の色を持っていることを意味する。


ステップ 2 : 頂点バッファの設定

カスタム頂点フォーマットが定義されたので、次は頂点を初期化する。Vertices サンプル プロジェクトでは、この処理を行うために、必要な Microsoft® Direct3D® オブジェクトを作成した後、アプリケーション定義関数 InitVB を呼び出している。次のサンプル コードでは、3 つのカスタム頂点の値を初期化している。

CUSTOMVERTEX g_Vertices[] =
{
    { 150.0f,  50.0f, 0.5f, 1.0f, 0xffff0000, }, // x, y, z, rhw, color
    { 250.0f, 250.0f, 0.5f, 1.0f, 0xff00ff00, },
    {  50.0f, 250.0f, 0.5f, 1.0f, 0xff00ffff, },
};

上記のサンプル コードでは、3 つの頂点に三角形のポイントを設定し、各頂点が放射する色を指定する。最初のポイントは (150, 50) にあり、赤色 (0xffff0000) を放射する。2 番目のポイントは (250, 250) にあり、緑色 (0xff00ff00) を放射する。3 番目のポイントは (50, 250) にあり、青緑色 (0xff00ffff) を放射する。3 つのポイントの深度値は 0.5 で、RHW は 1.0 である。この頂点フォーマットの詳細については、「トランスフォーム済み ライティング済みの頂点」を参照すること。

次のステップは、次のサンプル コードのように、IDirect3DDevice8::CreateVertexBuffer を呼び出して頂点バッファを作成することである。

if( FAILED( g_pd3dDevice->CreateVertexBuffer( 3*sizeof(CUSTOMVERTEX),
                                              0 /* 使用 */, D3DFVF_CUSTOMVERTEX,
                                              D3DPOOL_DEFAULT, &g_pVB ) ) )
    return E_FAIL;

CreateVertexBuffer の最初の 2 つのパラメータは、新しい頂点バッファの必要なサイズと使用方法を Direct3D に指示する。次の 2 つのパラメータは、新しいバッファのベクトル フォーマットおよびメモリ領域を指定する。ベクトル フォーマットは、このサンプル コードで以前に指定された FVF である D3DFVF_CUSTOMVERTEX である。D3DPOOL_DEFAULT フラグは、頂点バッファを、このバッファに最も適したメモリ割り当てを行って作成するよう Direct3D に指示する。最後のパラメータは、作成する頂点バッファのアドレスである。

頂点バッファを作成すると、次のサンプル コードのように、このバッファにカスタム頂点のデータが設定される。

VOID* pVertices;
if( FAILED( g_pVB->Lock( 0, sizeof(g_Vertices), (BYTE**)&pVertices, 0 ) ) )
    return E_FAIL;
memcpy( pVertices, g_Vertices, sizeof(g_Vertices) );
g_pVB->Unlock();

頂点バッファは、まず、IDirect3DVertexBuffer8::Lock を呼び出すことによってロックされる。最初のパラメータは、ロックする頂点データへのバイト単位のオフセットである。第 2 パラメータは、ロックする頂点データのサイズをバイト数で示す。第 3 パラメータは、頂点データへのポインタを格納する BYTE ポインタのアドレスである。第 4 のパラメータは、頂点バッファにデータのロック方法を指示する。

頂点は、memcpy を使って頂点バッファにコピーされる。頂点が頂点バッファに格納された後、IDirect3DVertexBuffer8::Unlock を呼び出して、頂点バッファがアンロックされる。このロックとアンロックのメカニズムは、頂点バッファがデバイス メモリに存在する場合があるため必要になる。

頂点バッファに頂点が格納されたので、次はディスプレイをレンダリングする。これについては、「ステップ 3 : ディスプレイのレンダリング」で説明する。


ステップ 3 : ディスプレイのレンダリング

頂点バッファに頂点が格納されたので、次はディスプレイをレンダリングする。ディスプレイのレンダリングでは、まずバック バッファを青色にクリアした後、BeginScene を呼び出す。

g_pd3dDevice->Clear( 0, NULL, D3DCLEAR_TARGET, D3DCOLOR_XRGB(0,0,255), 1.0f, 0L );
g_pd3dDevice->BeginScene();

頂点バッファの頂点をレンダリングするには、いくつかのステップが必要である。まず、ストリーム ソースを設定する。この場合は、ストリーム 0 を使用する。ストリームのソースは、IDirect3DDevice8::SetStreamSource を呼び出して指定する。

g_pd3dDevice->SetStreamSource( 0, g_pVB, sizeof(CUSTOMVERTEX) );

SetStreamSource の最初のパラメータは、Microsoft® Direct3D® にデバイス データ ストリームのソースを指示する。2 番目のパラメータは、データ ストリームにバインドする頂点バッファである。3 番目のパラメータは、コンポーネントのサイズをバイト単位で指定する。上記のサンプル コードでは、CUSTOMVERTEX のサイズがコンポーネントのサイズとして使用されている。

次のステップは、IDirect3DDevice8::SetVertexShader を呼び出して、使用する頂点シェーダを Direct3D に通知することである。完全なカスタム頂点シェーダは高度なトピックであるが、ほとんどの場合、頂点シェーダに送られるのは単なる FVF コードである。これによって、処理する頂点のタイプが Direct3D に通知される。次のサンプル コードでは、頂点シェーダを設定している。

g_pd3dDevice->SetVertexShader( D3DFVF_CUSTOMVERTEX );

SetVertexShader のパラメータは、使用する頂点シェーダへのハンドルだけである。このパラメータの値として、IDirect3DDevice8::CreateVertexShader から返るハンドルまたは FVF コードを使用できる。ここでは、D3DFVF_CUSTOMVERTEX によって定義された FVF コードを使用している。

頂点シェーダの詳細については、「頂点シェーダ」を参照すること。

次のステップは、次のサンプル コードのように、IDirect3DDevice8::DrawPrimitive を使って頂点バッファの頂点をレンダリングすることである。

g_pd3dDevice->DrawPrimitive( D3DPT_TRIANGLELIST, 0, 1 );

DrawPrimitive が受け取る最初のパラメータは、描画するプリミティブのタイプを Direct3D に指示するフラグである。このサンプルでは、D3DPT_TRIANGLELIST フラグを使って、三角形のリストを指定している。2 番目のパラメータは、ロードする最初の頂点のインデックスである。3 番目のパラメータは、描画するプリミティブの数を指定する。このサンプルでは、三角形を 1 つだけ描画するので、この値は 1 に設定される。

さまざまなプリミティブの詳細については、「3D プリミティブ」を参照すること。

最後のステップは、シーンを終了し、バック バッファをフロント バッファに表示することである。次のサンプル コードにその処理を示す。

g_pd3dDevice->EndScene();
g_pd3dDevice->Present( NULL, NULL, NULL, NULL );

バック バッファをフロント バッファに表示すると、クライアント ウィンドウに 3 種類の色の点を持つ三角形が表示される。

このチュートリアルでは、頂点を使ってジオメトリ形状をレンダリングする方法を示した。「チュートリアル 3 : 行列の使い方」では、行列の概念とその使用方法について説明する。


チュートリアル 3 : 行列の使い方

このチュートリアルでは、行列の概念とその使用方法を示す。Vertices サンプル プロジェクトでは、2D の頂点をレンダリングして三角形を描画した。ここでは、3D の頂点のトランスフォームを処理する。行列は、カメラとビューポートの設定にも使用される。トランスフォーム行列の処理の詳細については、「3D トランスフォーム」を参照すること。

Matrices サンプル プロジェクトでは、ジオメトリをレンダリングする前に、3D の三角形のレンダリングに使用する行列トランスフォームを作成および設定するアプリケーション定義関数 SetupMatrices を呼び出す。通常、3D シーンには 3 つのタイプのトランスフォームが設定される。この一般的なトランスフォームを作成するステップを、以下に示す。

  • ステップ 1 : ワールド トランスフォーム行列の定義
  • ステップ 2 : ビュー トランスフォーム行列の定義
  • ステップ 3 : 射影トランスフォーム行列の定義

行列およびトランスフォームの詳細については、「行列」を参照すること。

3D トランスフォームの詳細については、「3D トランスフォーム」を参照すること。

注 Matrices サンプル プロジェクトのパスは次のとおりである。

(SDK ルート)\Samples\Multimedia\Direct3D\Tutorials\Tut03_Matrices

トランスフォーム行列を作成する順序は、シーン内のオブジェクトのレイアウトには影響しない。ただし、Direct3D では、(1) ワールド、(2) ビュー、(3) 射影の順序で、シーンに行列が適用される。

Matrices プロジェクトのサンプル コードは、Vertices プロジェクトのサンプル コードとほぼ同じである。このチュートリアルでは、行列に固有のコードのみに注目し、Direct3D の初期化、Microsoft Windows® メッセージの処理、レンダリング、またはシャット ダウンについては説明しない。これらのタスクについては、「チュートリアル 1 : デバイスの作成」を参照すること。

このチュートリアルでは、カスタム頂点および頂点バッファを使用してジオメトリを表示する。カスタム頂点タイプの選択および頂点バッファの実装の詳細については、「チュートリアル 2 : 頂点のレンダリング」を参照すること。


ステップ 1 : ワールド トランスフォーム行列の定義

ワールド トランスフォーム行列は、3D モデル空間でジオメトリを平行移動、スケーリング、および回転する方法を定義する。

次のサンプル コードでは、三角形を y 軸上で回転させた後、Microsoft® Direct3D® デバイスに現在のワールド トランスフォームを設定している。

D3DXMATRIX matWorld;
D3DXMatrixRotationY( &matWorld, timeGetTime()/150.0f );
g_pd3dDevice->SetTransform( D3DTS_WORLD, &matWorld );

最初のステップは、D3DXMatrixRotationY メソッドを呼び出して、Y 軸を中心に三角形を回転させることである。最初のパラメータは、処理の結果となる D3DXMATRIX へのポインタである。2 番目のパラメータは、ラジアン単位の回転の角度である。

次のステップでは、IDirect3DDevice8::SetTransform を呼び出して、Direct3D デバイスにワールド トランスフォームを設定する。SetTransform が受け取る最初のパラメータは、設定するトランスフォームを Direct3D に指示する。このサンプルでは、D3DTS_WORLD マクロを使用して、ワールド トランスフォームを指定する。2 番目のパラメータは、現在のトランスフォームとして設定する行列へのポインタである。

ワールド トランスフォームの詳細については、「ワールド トランスフォーム」を参照すること。

シーンのワールド トランスフォームを定義した後、ビュー トランスフォーム行列を準備できる。ここでも、トランスフォームを定義する順序は重要ではないことに注意すること。ただし、Direct3D では、(1) ワールド、(2) ビュー、(3) 射影の順序で、シーンに行列が適用される。

ビュー トランスフォーム行列の定義については、「ステップ 2 : ビュー トランスフォーム行列の定義」で説明する。


ステップ 2 : ビュー トランスフォーム行列の定義

ビュー トランスフォーム行列は、ビューの位置および回転を定義する。ビュー行列はシーンのカメラである。

次のサンプル コードでは、ビュー トランスフォーム行列を作成した後、Microsoft® Direct3D® デバイスに現在のビュー トランスフォームを設定している。

D3DXMATRIX matView;
D3DXMatrixLookAtLH( &matView, &D3DXVECTOR3( 0.0f, 3.0f,-5.0f ),
                              &D3DXVECTOR3( 0.0f, 0.0f, 0.0f ),
                              &D3DXVECTOR3( 0.0f, 1.0f, 0.0f ) );
g_pd3dDevice->SetTransform( D3DTS_VIEW, &matView );

最初のステップは、D3DXMatrixLookAtLH を呼び出してビュー行列を定義することである。最初のパラメータは、処理の結果となる D3DXMATRIX 構造体へのポインタである。第 2、第 3、第 4 のパラメータは、視点、注視点、および "上" 方向を定義する。ここでは、視点は z 軸方向に -5 単位、上方向に 3 単位の位置に、注視点は原点に、"上" 方向は y 軸方向に定義されている。

次のステップでは、IDirect3DDevice8::SetTransform を呼び出して、ビュー トランスフォームを Direct3D デバイスに適用する。SetTransform が受け取る最初のパラメータは、設定するトランスフォームを Direct3D に指示する。このサンプルでは、D3DTS_VIEW フラグを使用して、ビュー トランスフォームを指定する。2 番目のパラメータは、現在のトランスフォームとして設定する行列へのポインタである。

ビュー トランスフォームの詳細については、「ビュー トランスフォーム」を参照すること。

シーンのワールド トランスフォームを定義した後、射影トランスフォーム行列を準備できる。ここでも、トランスフォームを定義する順序は重要ではないことに注意すること。ただし、Direct3D では、(1) ワールド、(2) ビュー、(3) 射影の順序で、シーンに行列が適用される。

射影トランスフォーム行列の定義については、「ステップ 3 : 射影トランスフォーム行列の定義」で説明する。


ステップ 3 : 射影トランスフォーム行列の定義

射影トランスフォーム行列は、3D ビュー空間から 2D ビューポート空間にジオメトリをトランスフォームする方法を定義する。

次のサンプル コードでは、射影トランスフォーム行列を作成した後、Microsoft® Direct3D® デバイスに現在の射影トランスフォームを設定している。

D3DXMATRIX matProj;
D3DXMatrixPerspectiveFovLH( &matProj, D3DX_PI/4, 1.0f, 1.0f, 100.0f );
g_pd3dDevice->SetTransform( D3DTS_PROJECTION, &matProj );

最初のステップは、D3DXMatrixPerspectiveFovLH を呼び出して射影行列を設定することである。最初のパラメータは、処理の結果となる D3DXMATRIX 構造体へのポインタである。2 番目のパラメータは視野を定義する。これによって、遠くにあるオブジェクトがどのように小さくなるかを指示する。標準的な視野は 1/4 pi であり、このサンプルでもこの値が使用されている。3 番目のパラメータはアスペクト比を定義する。サンプルで使用する標準のアスペクト比は 1 である。4 番目と 5 番目のパラメータは、近くのクリップ面と遠くのクリップ面を定義する。これは、ジオメトリがレンダリングされなくなる距離を決定する。Matrices サンプル プロジェクトでは、近くのクリップ面は 1 に、遠くのクリップ面は 100 に設定されている。

次のステップは、IDirect3DDevice8::SetTransform を呼び出して、トランスフォームを Direct3D デバイスに適用することである。SetTransform が受け取る最初のパラメータは、設定するトランスフォームを Direct3D に指示する。このサンプルでは、D3DTS_PROJECTION フラグを使用して、射影トランスフォームを指定する。2 番目のパラメータは、現在のトランスフォームとして設定する行列へのポインタである。

射影トランスフォームの詳細については、「射影トランスフォーム」を参照すること。

このチュートリアルでは、行列の使い方を示した。「チュートリアル 4 : ライトの作成および使い方」では、シーンにライトを追加して、一層リアルにする方法を示す。


チュートリアル 4 : ライトの作成および使い方

Microsoft® Direct3D® ライトによって、3D オブジェクトは一層リアルになる。ライトを使用すると、シーン内の各ジオメトリ オブジェクトは、使用するライトの位置およびタイプに基づいてライトが当てられる。このチュートリアルのサンプル コードでは、ライトおよびマテリアルについて説明する。

このチュートリアルでは、次のステップでマテリアルおよびライトを作成する。

  • ステップ 1 : シーンのジオメトリの初期化
  • ステップ 2 : マテリアルおよびライトの設定

注 Lights サンプル プロジェクトのパスは次のとおりである。

(SDK ルート)\Samples\Multimedia\Direct3D\Tutorials\Tut04_Lights

Lights プロジェクトのサンプル コードは、Matrices プロジェクトのサンプル コードとほぼ同じである。このチュートリアルでは、ライトの作成と使用に固有のコードのみに注目し、Direct3D の設定、Microsoft Windows メッセージの処理、レンダリング、またはシャット ダウンについては説明しない。これらのタスクについては、「チュートリアル 1 : デバイスの作成」を参照すること。

このチュートリアルでは、カスタム頂点および頂点バッファを使用してジオメトリを表示する。カスタム頂点タイプの選択および頂点バッファの実装の詳細については、「チュートリアル 2 : 頂点のレンダリング」を参照すること。

このチュートリアルでは、行列を使用してジオメトリをトランスフォームする。行列およびトランスフォームの詳細については、「チュートリアル 3 : 行列の使い方」を参照すること。


ステップ 1 : シーンのジオメトリの初期化

ライトを使用するための条件の 1 つは、各サーフェスが法線を持っていることである。これを処理するために、Lights サンプル プロジェクトでは別のカスタム頂点タイプを使用する。新しいカスタム頂点フォーマットには、3D 位置座標とサーフェスの法線が含まれる。サーフェスの法線は、Microsoft® Direct3D® によって内部的にライティングの計算に使用される。

struct CUSTOMVERTEX
{
    D3DXVECTOR3 position; // 頂点の 3D 位置座標。
    D3DXVECTOR3 normal;   // 頂点のサーフェスの法線。
};

// カスタム FVF。
#define D3DFVF_CUSTOMVERTEX (D3DFVF_XYZ|D3DFVF_NORMAL)

これで正しいベクトル フォーマットが定義されたので、Lights サンプル プロジェクトではアプリケーション定義関数 InitGeometry を呼び出して円柱を作成する。最初のステップは、次のサンプル コードのように、円柱のポイントを格納する頂点バッファを作成することである。

// 頂点バッファを作成する。
if( FAILED( g_pd3dDevice->CreateVertexBuffer( 50*2*sizeof(CUSTOMVERTEX),
                                              0 /* 使用 */, D3DFVF_CUSTOMVERTEX,
                                              D3DPOOL_DEFAULT, &g_pVB ) ) )
    return E_FAIL;

次のステップは、頂点バッファに円柱の点を設定することである。次のサンプル コードでは、各ポイントが位置座標と法線によって定義されていることに注意すること。

for( DWORD i=0; i<50; i++ )
{
    FLOAT theta = (2*D3DX_PI*i)/(50-1);
    pVertices[2*i+0].position = D3DXVECTOR3( sinf(theta),-1.0f, cosf(theta) );
    pVertices[2*i+0].normal   = D3DXVECTOR3( sinf(theta), 0.0f, cosf(theta) );
    pVertices[2*i+1].position = D3DXVECTOR3( sinf(theta), 1.0f, cosf(theta) );
    pVertices[2*i+1].normal   = D3DXVECTOR3( sinf(theta), 0.0f, cosf(theta) );
}

上記のサンプル コードで頂点バッファに円柱の頂点を設定したら、頂点バッファをレンダリングすることができる。ただし、円柱をレンダリングする前に、このシーンのマテリアルとライトを設定しなければならない。これについては、「ステップ 2 : マテリアルおよびライトの設定」で説明する。


ステップ 2 : マテリアルおよびライトの設定

Microsoft® Direct3D® でライティングを使用するには、1 つまたは複数のライトを作成しなければならない。ジオメトリ オブジェクトが反射する色を決定するには、ジオメトリ オブジェクトのレンダリングに使用するマテリアルを作成する。Lights サンプル プロジェクトでは、シーンをレンダリングする前に、1 つのマテリアルと 1 つのディレクショナル ライトを設定するアプリケーション定義関数 SetupLights を呼び出す。この関数は、次のステップでマテリアルおよびライトを作成する。

  • ステップ 2.1 : マテリアルの作成
  • ステップ 2.2 : ライトの作成


ステップ 2.1 : マテリアルの作成

マテリアルは、ジオメトリ オブジェクトにライトが当たったときに、ジオメトリ オブジェクトのサーフェスから反射される色を定義する。次のサンプル コードでは、D3DMATERIAL8 構造体を使って、黄色のマテリアルを作成している。

D3DMATERIAL8 mtrl;
ZeroMemory( &mtrl, sizeof(D3DMATERIAL8) );
mtrl.Diffuse.r = mtrl.Ambient.r = 1.0f;
mtrl.Diffuse.g = mtrl.Ambient.g = 1.0f;
mtrl.Diffuse.b = mtrl.Ambient.b = 0.0f;
mtrl.Diffuse.a = mtrl.Ambient.a = 1.0f;
g_pd3dDevice->SetMaterial( &mtrl );

このマテリアルのディフューズ色およびアンビエント色は黄色に設定される。IDirect3DDevice8::SetMaterial メソッドの呼び出しによって、シーンのレンダリングに使用される Microsoft® Direct3D® デバイスにマテリアルが適用される。SetMaterial が受け取るパラメータは、設定するマテリアルのアドレスだけである。この呼び出しが行われた後、別のマテリアルを指定する SetMaterial の次の呼び出しが行われるまで、このマテリアルを使って各プリミティブがレンダリングされる。

これでシーンにマテリアルが適用されたので、次のステップはライトを作成することである。これについては、「ステップ 2.2 : ライトの作成」で説明する。


ステップ 2.2 : ライトの作成

Microsoft® Direct3D® で使用できるライトには、ポイント ライト、ディレクショナル ライト、およびスポットライトの 3 種類がある。サンプル コードでは、光が 1 方向に進むディレクショナル ライトを作成し、ライトの方向を変化させている。

次のサンプル コードでは、D3DLIGHT8 構造体を使って、ディレクショナル ライトを作成する。

D3DXVECTOR3 vecDir;
D3DLIGHT8 light;
ZeroMemory( &light, sizeof(D3DLIGHT8) );
light.Type       = D3DLIGHT_DIRECTIONAL;

次のサンプル コードでは、このライトのディフューズ色を白に設定している。

light.Diffuse.r  = 1.0f;
light.Diffuse.g  = 1.0f;
light.Diffuse.b  = 1.0f;

次のサンプル コードでは、ライトの方向を円弧で回転させている。

vecDir = D3DXVECTOR3(cosf(timeGetTime()/360.0f),
                     0.0f,
                     sinf(timeGetTime()/360.0f) );
D3DXVec3Normalize( (D3DXVECTOR3*)&light.Direction, &vecDir );

D3DXVec3Normalize の呼び出しによって、ライトの方向を決定するための方向ベクトルを正規化する。

範囲を指定して、ライトのエフェクトが届く範囲を Direct3D に指示できる。このメンバは、ディレクショナル ライトには影響しない。次のサンプル コードでは、このライトに 1000 単位の範囲を割り当てている。

light.Range       = 1000.0f;

次のサンプル コードでは、IDirect3DDevice8::SetLight を呼び出して、Direct3D デバイスにライトを割り当てている。

g_pd3dDevice->SetLight( 0, &light );

SetLight が受け取る最初のパラメータは、このライトが割り当てられるインデックスである。ライトが既にその位置に存在する場合、新しいライトによって上書きされることに注意すること。2 番目のパラメータは、ライトを定義する light 構造体へのポインタである。Lights サンプル プロジェクトでは、このライトをインデックス 0 に配置する。

次のサンプル コードでは、IDirect3DDevice8::LightEnable を呼び出してライトを有効にしている。

g_pd3dDevice->LightEnable( 0, TRUE);

LightEnable が受け取る最初のパラメータは、有効にするライトのインデックスである。2 番目のパラメータは、ライトをオンにする (TRUE) か、オフにする (FALSE) かを指定するブール値である。上記のサンプル コードでは、インデックス 0 にあるライトがオンになっている。

次のサンプル コードでは、IDirect3DDevice8::SetRenderState を呼び出して、ライトをレンダリングするように Direct3D に指示している。

g_pd3dDevice->SetRenderState( D3DRS_LIGHTING, TRUE );

SetRenderState が受け取る最初の 2 つのパラメータは、変更するデバイス ステート変数と、その変数に設定する値である。このサンプル コードでは、D3DRS_LIGHTING デバイス変数を TRUE に設定している。これは、ライトのレンダリングを有効にする効果がある。

このサンプル コードの最後のステップは、もう一度 SetRenderState を呼び出して、アンビエント ライトをオンにすることである。

g_pd3dDevice->SetRenderState( D3DRS_AMBIENT, 0x00202020 );

上記のサンプル コードでは、D3DRS_AMBIENT デバイス変数をライト グレー (0x00202020) に設定している。アンビエント ライトは、すべてのオブジェクトを指定された色でライトアップする。

ライティングの詳細については、「Direct3D のライティングにおける数学的計算」を参照すること。

このチュートリアルでは、ライトとマテリアルの使い方を示した。「チュートリアル 5 : テクスチャ マップの使い方」では、サーフェスにテクスチャを追加する方法を示す。


チュートリアル 5 : テクスチャ マップの使い方

ライトとマテリアルによって、シーンは一層リアルになるが、最もリアルさが増すのはサーフェスにテクスチャを追加したときである。テクスチャは、サーフェスに縮小ラップされた壁紙であると考えることができる。たとえば、木のテクスチャを立方体に貼り付けることによって、その立方体が木でできているように見せることができる。Texture サンプル プロジェクトでは、「チュートリアル 4 : ライトの作成および使い方」で作成した円柱にバナナの皮のテクスチャを追加する。このチュートリアルでは、テクスチャのロード、頂点の設定、およびテクスチャを使ったオブジェクトの表示方法を説明する。

このチュートリアルでは、次のステップでテクスチャを実装する。

  • ステップ 1 : カスタム頂点フォーマットの定義
  • ステップ 2 : 画面のジオメトリの初期化
  • ステップ 3 : シーンのレンダリング

注 Texture サンプル プロジェクトのパスは次のとおりである。

(SDK ルート)\Samples\Multimedia\Direct3D\Tutorials\Tut05_Textures

Texture プロジェクトのサンプル コードは、Lights プロジェクトのサンプル コードとほぼ同じである。ただし、Texture サンプル プロジェクトではマテリアルやライトを作成しない点が異なる。このチュートリアルでは、テクスチャに固有のコードのみに注目し、Microsoft® Direct3D® の初期化、Microsoft Windows® メッセージの処理、レンダリング、またはシャット ダウンについては説明しない。これらのタスクについては、「チュートリアル 1 : デバイスの作成」を参照すること。

このチュートリアルでは、カスタム頂点および頂点バッファを使用してジオメトリを表示する。カスタム頂点タイプの選択および頂点バッファの実装の詳細については、「チュートリアル 2 : 頂点のレンダリング」を参照すること。

このチュートリアルでは、行列を使用してジオメトリをトランスフォームする。行列およびトランスフォームの詳細については、「チュートリアル 3 : 行列の使い方」を参照すること。


ステップ 1 : カスタム頂点フォーマットの定義

テクスチャを使用するには、テクスチャ座標を含むカスタム頂点フォーマットを定義しなければならない。テクスチャ座標によって、プリミティブ内の各ベクトルについてテクスチャを配置する場所を Microsoft® Direct3D® に指示する。テクスチャ座標の範囲は 0.0 から 1.0 までで、(0.0, 0.0) はテクスチャの左上を表し、(1.0, 1.0) はテクスチャの右下を表す。

次のサンプル コードは、Texture サンプル プロジェクトで、テクスチャ座標を含めるカスタム頂点フォーマットの設定方法を示している。

struct CUSTOMVERTEX
{
    D3DXVECTOR3 position; // 位置座標。
    D3DCOLOR    color;    // 色。
    FLOAT       tu, tv;   // テクスチャ座標。
};

// カスタム頂点構造体を記述するカスタム FVF。
#define D3DFVF_CUSTOMVERTEX (D3DFVF_XYZ|D3DFVF_DIFFUSE|D3DFVF_TEX1)

テクスチャ座標の詳細については、「テクスチャ座標」を参照すること。

カスタム頂点タイプが定義されたので、次のステップでは、テクスチャをロードし、円柱を作成する。これについては、「ステップ 2 : 画面のジオメトリの初期化」で説明する。


ステップ 2 : 画面のジオメトリの初期化

レンダリングを行う前に、Texture サンプル プロジェクトでは、テクスチャを作成し、円柱のジオメトリを初期化するアプリケーション定義関数 InitGeometry を呼び出している。

テクスチャはファイル ベースのイメージから作成される。次のサンプル コードでは、D3DXCreateTextureFromFile を使って、Banana.bmp から円柱のサーフェスを覆うためのテクスチャを作成している。

if( FAILED( D3DXCreateTextureFromFile( g_pd3dDevice, "Banana.bmp",
                                       &g_pTexture ) ) )
    return E_FAIL;

D3DXCreateTextureFromFile が受け取る最初のパラメータは、テクスチャをレンダリングするために使用される Microsoft® Direct3D® デバイスへのポインタである。2 番目のパラメータは、作成するテクスチャの元のファイル名を指定する ANSI 文字列へのポインタである。このサンプルでは、Banana.bmp を指定して、このファイルからイメージをロードする。3 番目のパラメータは、テクスチャ オブジェクトへのポインタのアドレスである。

バナナのテクスチャがロードされ、使用する準備ができたら、次のステップは円柱を作成することである。次のサンプル コードでは、頂点バッファに円柱のデータを設定している。各ポイントはテクスチャ座標 (tu, tv) を持つことに注意すること。

for( DWORD i=0; i<50; i++ )
{
    FLOAT theta = (2*D3DX_PI*i)/(50-1);

    pVertices[2*i+0].position = D3DXVECTOR3( sinf(theta),-1.0, cosf(theta) );
    pVertices[2*i+0].color    = 0xffffffff;
    pVertices[2*i+0].tu       = ((FLOAT)i)/(50-1);
    pVertices[2*i+0].tv       = 1.0f;

    pVertices[2*i+1].position = D3DXVECTOR3( sinf(theta), 1.0, cosf(theta) );
    pVertices[2*i+1].color    = 0xff808080;
    pVertices[2*i+1].tu       = ((FLOAT)i)/(50-1);
    pVertices[2*i+1].tv       = 0.0f;
}

各頂点には、位置座標、色、およびテクスチャ座標が含まれる。上記のサンプル コードでは、テクスチャが円柱の周囲をなめらかに覆うように、各ポイントのテクスチャ座標を設定している。

テクスチャがロードされ、頂点バッファをレンダリングする準備ができたので、次はディスプレイをレンダリングする。これについては、「ステップ 3 : シーンのレンダリング」で説明する。


ステップ 3 : シーンのレンダリング

シーンのジオメトリが初期化されたら、シーンをレンダリングする。テクスチャを持つオブジェクトをレンダリングするには、そのテクスチャが現在のテクスチャの 1 つとして設定されていなければならない。次のステップは、テクスチャ ステージ ステートの値を設定することである。テクスチャ ステージ ステートによって、テクスチャをレンダリングする動作を定義できる。たとえば、複数のテクスチャを 1 つにブレンディングすることができる。

Texture サンプル プロジェクトでは、まず、使用するテクスチャを設定する。次のサンプル コードでは、IDirect3DDevice8::SetTexture を使って、Microsoft® Direct3D® デバイスがレンダリングするテクスチャを設定している。

g_pd3dDevice->SetTexture( 0, g_pTexture );

SetTexture が受け取る最初のパラメータは、テクスチャを設定するステージ識別子である。1 つのデバイスで最大 8 つのテクスチャを持つため、最大値は 7 である。Texture サンプル プロジェクトでは 1 つだけテクスチャがあり、ステージ 0 に配置している。2 番目のパラメータは、テクスチャ オブジェクトへのポインタである。Texture サンプル プロジェクトでは、アプリケーション定義関数 InitGeometry で作成したテクスチャ オブジェクトを使用する。

次のサンプル コードでは、IDirect3DDevice8::SetTextureStageState メソッドを呼び出すことによって、テクスチャ ステージ ステートの値を設定している。

g_pd3dDevice->SetTextureStageState( 0, D3DTSS_COLOROP,   D3DTOP_MODULATE );
g_pd3dDevice->SetTextureStageState( 0, D3DTSS_COLORARG1, D3DTA_TEXTURE );
g_pd3dDevice->SetTextureStageState( 0, D3DTSS_COLORARG2, D3DTA_DIFFUSE );
g_pd3dDevice->SetTextureStageState( 0, D3DTSS_ALPHAOP,   D3DTOP_DISABLE );

SetTextureState が受け取る最初のパラメータは、設定するステート変数のステージ インデックスである。このサンプル コードでは、ステージ 0 のテクスチャの値を変更するので、ここでは 0 を指定している。次のパラメータは、設定するテクスチャ ステートである。有効なすべてのテクスチャ ステートおよびその意味の一覧については、「D3DTEXTURESTAGESTATETYPE」を参照すること。次のパラメータは、テクスチャ ステートに設定する値である。ここに指定する値は、変更するテクスチャ ステージ ステートの値に基づいている。

各テクスチャ ステージ ステートに適切な値を設定すると、円柱をレンダリングすることができ、テクスチャがサーフェスに追加される。

テクスチャ座標のもう 1 つの使い方は、自動的にテクスチャ座標を生成する方法である。この方法では、テクスチャ座標インデックス (TCI) を使用する。TCI では、テクスチャ行列を使って、(x,y,z) TCI 座標を (tu, tv) テクスチャ座標にトランスフォームする。Texture サンプル プロジェクトでは、カメラ空間での頂点の位置座標を使って、テクスチャ座標を生成している。

最初のステップは、次のサンプル コードに示されているように、トランスフォームに使用する行列を作成することである。

D3DXMATRIX mat;
mat._11 = 0.25f; mat._12 = 0.00f; mat._13 = 0.00f; mat._14 = 0.00f;
mat._21 = 0.00f; mat._22 =-0.25f; mat._23 = 0.00f; mat._24 = 0.00f;
mat._31 = 0.00f; mat._32 = 0.00f; mat._33 = 1.00f; mat._34 = 0.00f;
mat._41 = 0.50f; mat._42 = 0.50f; mat._43 = 0.00f; mat._44 = 1.00f;

行列を作成したら、次のサンプル コードのように、IDirect3DDevice8::SetTransform を呼び出して設定しなければならない。

g_pd3dDevice->SetTransform( D3DTS_TEXTURE0, &mat );

D3DTS_TEXTURE0 フラグは、テクスチャ ステージ 0 のテクスチャにトランスフォームを適用するよう Direct3D に指示する。このサンプルの次のステップでは、目的の効果をだすために、さらにテクスチャ ステージ ステート値を設定する。この処理は、次のサンプル コードで行われる。

g_pd3dDevice->SetTextureStageState( 0, D3DTSS_TEXTURETRANSFORMFLAGS, D3DTTFF_COUNT2 );
g_pd3dDevice->SetTextureStageState( 0, D3DTSS_TEXCOORDINDEX, D3DTSS_TCI_CAMERASPACEPOSITION );

テクスチャ座標が設定されたので、シーンをレンダリングすることができる。円柱の座標は自動的に作成されることに注意すること。この設定では、ジオメトリ形状がレンダリングされた後、レンダリング画面にテクスチャを重ねるエフェクトが適用される。

テクスチャの詳細については、「テクスチャ」を参照すること。

このチュートリアルでは、サーフェスのテクスチャの使い方を示した。「チュートリアル 6 : メッシュの使い方」では、メッシュを含む複雑なジオメトリ形状の使用方法を示す。


チュートリアル 6 : メッシュの使い方

複雑なジオメトリは通常 3D モデリング ソフトウェアを使ってモデリングされ、ファイルに保存される。たとえば、.x ファイル フォーマットなどがある。Microsoft® Direct3D® では、メッシュを使ってこれらのファイルからオブジェクトをロードする。メッシュは少し複雑であるが、D3DX にはメッシュを容易に使用できるようにする関数が含まれている。Meshes サンプル プロジェクトでは、メッシュに関するトピックを説明し、メッシュのロード、レンダリング、アンロードの方法を示す。

このチュートリアルでは、次のステップで、メッシュをロード、レンダリング、およびアンロードする方法を示す。

  • ステップ 1 : メッシュ オブジェクトのロード
  • ステップ 2 : メッシュ オブジェクトのレンダリング
  • ステップ 3 : メッシュ オブジェクトのアンロード

注 Meshes サンプル プロジェクトのパスは次のとおりである。

(SDK ルート)\Samples\Multimedia\Direct3D\Tutorials\Tut06_Meshes

Meshes プロジェクトのサンプル コードは、Lights プロジェクトのサンプル コードとほぼ同じである。ただし、Meshes サンプル プロジェクトのコードではマテリアルやライトを作成しない点が異なる。このチュートリアルでは、メッシュに固有のコードのみに注目し、Direct3D の設定、Microsoft Windows® メッセージの処理、レンダリング、またはシャット ダウンについては説明しない。これらのタスクについては、「チュートリアル 1 : デバイスの作成」を参照すること。

このチュートリアルでは、カスタム頂点および頂点バッファを使用してジオメトリを表示する。カスタム頂点タイプの選択および頂点バッファの実装の詳細については、「チュートリアル 2 : 頂点のレンダリング」を参照すること。

このチュートリアルでは、行列を使用してジオメトリをトランスフォームする。行列およびトランスフォームの詳細については、「チュートリアル 3 : 行列の使い方」を参照すること。

このチュートリアルでは、テクスチャを使用してメッシュのサーフェスを覆う。テクスチャのロードおよび使い方の詳細については、「チュートリアル 5 : テクスチャ マップの使い方」を参照すること。


ステップ 1 : メッシュ オブジェクトのロード

Microsoft® Direct3D® アプリケーションでメッシュを使用するには、まずメッシュをロードしなければならない。Meshes サンプル プロジェクトでは、必要な Direct3D オブジェクトをロードした後、アプリケーション定義関数 InitGeometry を呼び出して、トラのメッシュをロードする。

メッシュには、使用するすべてのマテリアルおよびテクスチャを格納するマテリアル バッファが必要である。この関数は、次のサンプル コードに示すように、最初にマテリアル バッファを宣言する。

LPD3DXBUFFER pD3DXMtrlBuffer;

次のサンプル コードでは、D3DXLoadMeshFromX メソッドを使って、メッシュをロードしている。

// 指定したファイルからメッシュをロードする。
if( FAILED( D3DXLoadMeshFromX( "tiger.x", D3DXMESH_SYSTEMMEM,
                               g_pd3dDevice, NULL,
                               &pD3DXMtrlBuffer, &g_dwNumMaterials,
                               &g_pMesh ) ) )
    return E_FAIL;

D3DXLoadMeshFromX が受け取る最初のパラメータは、ロードする Microsoft DirectX® ファイルの名前を指示する文字列へのポインタである。このサンプルでは、Tiger.x からトラのメッシュをロードする。

2 番目のパラメータはメッシュの作成方法を Direct3D に指示する。このサンプルでは D3DXMESH_SYSTEMMEM フラグを使用している。これは、D3DXMESH_VB_SYSTEMMEM と D3DXMESH_IB_SYSTEMMEM の両方を指定していることと同じである。この 2 つのフラグは、メッシュのインデックス バッファおよび頂点バッファをシステム メモリに配置するよう Direct3D に指示する。

3 番目のパラメータは、メッシュのレンダリングに使用する Direct3D デバイスへのポインタである。

4 番目のパラメータは、ID3DXBuffer オブジェクトへのポインタである。このオブジェクトには、各面の隣接する面に関する情報が格納される。このサンプルでは、この情報は必要ないので、このパラメータは NULL に設定されている。

5 番目のパラメータも ID3DXBuffer オブジェクトへのポインタを取る。このメソッドが終了した後、このオブジェクトにはメッシュの D3DXMATERIAL 構造体が格納される。

6 番目のパラメータは、このメソッドが返った後、ppMaterials 配列に配置される D3DXMATERIAL 構造体の数へのポインタである。

7 番目のパラメータは、ロードされるメッシュを表す、メッシュ オブジェクトへのポインタのアドレスである。

メッシュ オブジェクトおよびマテリアルの情報がロードされた後、マテリアル バッファからマテリアルのプロパティおよびテクスチャ名を抽出する必要がある。

Meshes サンプル プロジェクトでは、まずマテリアル バッファへのポインタを取得することによって、この処理を行う。次のサンプル コードでは、ID3DXBuffer::GetBufferPointer メソッドを使って、このポインタを取得している。

D3DXMATERIAL* d3dxMaterials = (D3DXMATERIAL*)pD3DXMtrlBuffer->GetBufferPointer();

次のサンプル コードでは、メッシュのマテリアルの合計数に基づいて、新しいメッシュおよびテクスチャ オブジェクトを作成している。

g_pMeshMaterials = new D3DMATERIAL8[g_dwNumMaterials];
g_pMeshTextures  = new LPDIRECT3DTEXTURE8[g_dwNumMaterials];

メッシュ内の各マテリアルについて、次の処理が行われる。

最初のステップは、次のサンプル コードに示されているように、マテリアルをコピーすることである。

g_pMeshMaterials[i] = d3dxMaterials[i].MatD3D;

第 2 のステップは、次のサンプル コードに示されているように、マテリアルのアンビエント色を設定することである。

g_pMeshMaterials[i].Ambient = g_pMeshMaterials[i].Diffuse;

最後のステップは、次のサンプル コードに示されているように、マテリアルのテクスチャを作成することである。

// テクスチャを作成する。
if( FAILED( D3DXCreateTextureFromFile( g_pd3dDevice,
                                       d3dxMaterials[i].pTextureFilename,
                                       &g_pMeshTextures[i] ) ) )
    g_pMeshTextures[i] = NULL;
}

各マテリアルをロードした後、マテリアル バッファが必要ではなくなったら、IUnknown::Release を呼び出して解放する必要がある。

pD3DXMtrlBuffer->Release();

メッシュ、および対応するマテリアルとテクスチャがロードされる。これでメッシュをディスプレイにレンダリングできる。これについては、「ステップ 2 : メッシュ オブジェクトのレンダリング」で説明する。


ステップ 2 : メッシュ オブジェクトのレンダリング

ステップ 1 でメッシュをロードしたので、メッシュをレンダリングする準備ができている。メッシュは、メッシュについてロードされた各マテリアルのサブセットに分割される。各サブセットをレンダリングするために、メッシュはループでレンダリングされる。ループの最初のステップは、次のサンプル コードに示されているように、サブセットのマテリアルを設定することである。

g_pd3dDevice->SetMaterial( &g_pMeshMaterials[i] );

ループの 2 番目のステップは、次のサンプル コードに示されているように、サブセットのテクスチャを設定することである。

g_pd3dDevice->SetTexture( 0, g_pMeshTextures[i] );

マテリアルとテクスチャを設定した後、次のサンプル コードに示されているように、ID3DXBaseMesh::DrawSubset メソッドを使ってサブセットが描画される。

g_pMesh->DrawSubset( i );

DrawSubset メソッドは、描画するメッシュのサブセットを指定する DWORD を取る。このサンプルでは、ループを実行するたびにインクリメントされる値を使用する。

メッシュを使用した後、メッシュをメモリから正しく削除する必要がある。これについては、「ステップ 3 : メッシュ オブジェクトのアンロード」で説明する。


ステップ 3 : メッシュ オブジェクトのアンロード

Microsoft® DirectX® プログラムが終了したら、使用した DirectX オブジェクトの割り当てを解除し、そのオブジェクトへのポインタを無効にする必要がある。このサンプルで使用したメッシュ オブジェクトも割り当てを解除する必要がある。Meshes サンプル プロジェクトでは、WM_DESTROY メッセージを受け取ったときに、この処理を行うアプリケーション定義関数 Cleanup を呼び出す。

次のサンプル コードでは、マテリアル リストを削除している。

if( g_pMeshMaterials )
    delete[] g_pMeshMaterials;

次のサンプル コードでは、ロードされた各テクスチャの割り当てを解除し、テクスチャ リストを削除している。

if( g_pMeshTextures )
{
    for( DWORD i = 0; i < g_dwNumMaterials; i++ )
    {
        if( g_pMeshTextures[i] )
            g_pMeshTextures[i]->Release();
    }
delete[] g_pMeshTextures;

次のサンプル コードでは、メッシュ オブジェクトの割り当てを解除している。

Delete the mesh object
if( g_pMesh )
    g_pMesh->Release();

このチュートリアルでは、メッシュのロードとレンダリングの方法を示した。このセクションのチュートリアルはこれで終わりである。標準的な Direct3D アプリケーションの作成方法については、「DirectX Graphics C/C++ サンプル」を参照すること。


DirectX Graphics C/C++ サンプル

次のサンプル アプリケーションには、Microsoft® Direct3D® および Direct3DX アプリケーション プログラミング インターフェイスの使い方と機能が示されている。

  • Billboard サンプル
  • BumpEarth サンプル
  • BumpLens サンプル
  • BumpUnderwater サンプル
  • BumpWaves サンプル
  • DotProduct3 サンプル
  • Emboss サンプル
  • ClipMirror サンプル
  • DolphinVS サンプル
  • DXTex ツール
  • EnhancedMesh サンプル
  • CubeMap サンプル
  • FishEye サンプル
  • SphereMap サンプル
  • MFCFog サンプル
  • MFCPixelShader サンプル
  • MFCTex サンプル
  • OptimizedMesh サンプル
  • Pick サンプル
  • PointSprites サンプル
  • ProgressiveMesh サンプル
  • RTPatch サンプル
  • SkinnedMesh サンプル
  • ShadowVolume サンプル
  • StencilDepth サンプル
  • StencilMirror サンプル
  • Text3D サンプル
  • VertexBlend サンプル
  • VertexShader サンプル
  • VolumeTexture サンプル
  • Water サンプル

Microsoft DirectX® サンプルには Microsoft Visual C++® プロジェクト ワークスペース ファイルが含まれているが、読者の開発環境で正しくコンパイルできるかどうかを確認する必要がある。詳細については、「DirectX のサンプルおよびその他の DirectX アプリケーションのコンパイル」を参照すること。

参照

DirectX Graphics C/C++ チュートリアル


Billboard サンプル

説明

Billboard サンプルでは、ビルボーディングの手法を示している。ポリゴン数の多い木のモデルなど、複雑な 3D モデルをレンダリングする代わりに、モデルの 2D イメージをレンダリングし、常に視点に向くように回転させる。この手法は、木、雲、煙、爆発などをレンダリングするために、一般的に使用される。詳細については、「ビルボーディング」を参照すること。

このサンプルでは、カメラは木で覆われた丘の 3D シーンを飛行する。木は 3D オブジェクトのように見えるが、実際には、視点に向かって回転する 2D ビルボード イメージである。丘の地形およびスカイボックス (空のテクスチャを含む立方体) は、.x ファイルからロードされるオブジェクトである。これらは視覚効果のために使用され、ビルボーディング手法とは無関係である。

パス

ソース :(SDK ルート)\Samples\Multimedia\Direct3D\Billboard

実行可能ファイル :(SDK ルート)\Samples\Multimedia\Direct3D\Bin

ユーザーズ ガイド

次の表は実装されているキーを示している。メニュー コマンドを使って同じ操作を行うことができる。

キー | アクション
Enter | シーンを開始および停止する。
Space | シーンを少しずつ進める。
F2 | 新しいレンダリング デバイスまたはディスプレイ モードを選択するようユーザーに指示する。
Alt + Enter | フルスクリーン モードとウィンドウ モードを切り替える。
Esc | アプリケーションを終了する。

プログラミング上の注意

このサンプルでは、ビルボーディング手法に重点を置いている。カメラは各フレームで移動し、それに従って視点も変化する。視点が変化すると、ビルボードが新しい視点の方を向くように、y 軸に沿ってビルボードを回転させる回転行列が生成される。ビルボード行列の計算は FrameMove 関数で行われる。ビルボードには通常透明なピクセルが含まれているので、適切なアルファ ブレンディングを行うために、木もこの関数に格納される。木は、DrawTrees 関数で頂点バッファからレンダリングされる。

このサンプルのビルボードは、y 軸に沿ってのみ回転するように制限されている。このようにしないと、木の幹が地面に固定されていないように見える。3D フライト シミュレータやスペース シューティング ゲームの爆発などの効果では、ビルボードは通常 1 つの軸に制約されない。

このサンプルでは、ヘルパー関数などのプログラミング要素から構成される共通の Microsoft® DirectX® コードを使用している。このコードは DirectX SDK のほかのサンプルと共有されている。ソース コードは、(SDK ルート)\Samples\Multimedia\VBSamples にある。


BumpEarth サンプル

説明

BumpEarth サンプルでは、Microsoft® Direct3D® のバンプ マッピング機能を示す。バンプ マッピングは、粗い凹凸のあるサーフェスの外観をレンダリングするテクスチャ ブレンディング手法である。このサンプルでは、回転する、バンプ マッピング処理された地球をレンダリングする。

バンプ マッピング手法の一部の機能しかサポートしていないカードもある。一部のハードウェアでは、バンプ マッピングをサポートしていない場合や、一部しかサポートしていない場合がある。バンプ マッピングの詳細については、「バンプ マッピング」を参照すること。

パス

ソース :(SDK ルート)\Samples\Multimedia\Direct3D\BumpMapping\BumpEarth

実行可能ファイル :(SDK ルート)\Samples\Multimedia\Direct3D\Bin

ユーザーズ ガイド

次の表は実装されているキーを示している。メニュー コマンドを使って同じ操作を行うことができる。

キー | アクション
Enter | シーンを開始および停止する。
Space | シーンを少しずつ進める。
F2 | 新しいレンダリング デバイスまたはディスプレイ モードを選択するようユーザーに指示する。
Alt + Enter | フルスクリーン モードとウィンドウ モードを切り替える。
Esc | アプリケーションを終了する。

プログラミング上の注意

バンプ マップは摂動データを保存するテクスチャである。バンプ マッピングは 2 つのテクスチャを必要とする。1 つは環境マップで、シーン内で表示されるライトが含まれる。もう 1 つは実際のバンプ マッピングであり、環境マップのテクスチャ座標をバンプするために使用される値 (du および dv) が含まれる。一部のバンプ マップでは、特定のテクセルの輝きを制御する輝度の値も含まれる。

このサンプルでは、ヘルパー関数などのプログラミング要素から構成される共通の DirectX コードを使用している。このコードは DirectX SDK のほかのサンプルと共有されている。共通のヘッダーおよびソース コードは、(SDK ルート)\Samples\Multimedia\Common にある。


BumpLens サンプル

説明

BumpLens サンプルでは、バンプ マッピングを使って実現できるレンズのエフェクトを示す。バンプ マッピングは、粗い凹凸のあるサーフェスの外観をレンダリングするマルチテクスチャ ブレンディング手法であるが、ここに示すように、ほかのエフェクトにも使用できる。

バンプ マッピング手法の一部の機能しかサポートしていないカードもある。一部のハードウェアでは、バンプ マッピングをサポートしていない場合や、一部しかサポートしていない場合がある。バンプ マッピングの詳細については、「バンプ マッピング」を参照すること。

パス

ソース :(SDK ルート)\Samples\Multimedia\Direct3D\BumpMapping\BumpLens

実行可能ファイル :(SDK ルート)\Samples\Multimedia\Direct3D\Bin

ユーザーズ ガイド

次の表は実装されているキーを示している。メニュー コマンドを使って同じ操作を行うことができる。

キー | アクション
Enter | シーンを開始および停止する。
Space | シーンを少しずつ進める。
F2 | 新しいレンダリング デバイスまたはディスプレイ モードを選択するようユーザーに指示する。
Alt + Enter | フルスクリーン モードとウィンドウ モードを切り替える。
Esc | アプリケーションを終了する。

プログラミング上の注意

バンプ マップは摂動データを保存するテクスチャである。バンプ マッピングは 2 つのテクスチャを必要とする。1 つは環境マップで、シーン内で表示されるライトが含まれる。もう 1 つは実際のバンプ マッピングであり、環境マップのテクスチャ座標をバンプするために使用される値 (du および dv) が含まれる。一部のバンプ マップでは、特定のテクセルの輝きを制御する輝度の値も含まれる。

このサンプルでは、従来の方法とは異なる方法でバンプ マッピングを使用する。バンプ マッピングは環境マップを摂動するので、ほかのエフェクトにも使用できる。ここでは、バックグラウンド イメージを摂動して (その場でレンダリングできる)、レンズのエフェクトを作成している。

このサンプルでは、ヘルパー関数などのプログラミング要素から構成される共通の DirectX コードを使用している。このコードは DirectX SDK のほかのサンプルと共有されている。共通のヘッダーおよびソース コードは、次の場所にある。(SDK ルート)\Samples\Multimedia\Common


BumpUnderwater サンプル

説明

BumpLens サンプルでは、バンプ マッピングを使って実現できる水中のエフェクトを示す。バンプ マッピングは、粗い凹凸のあるサーフェスの外観をレンダリングするマルチテクスチャ ブレンディング手法であるが、ここに示すように、ほかのエフェクトにも使用できる。

バンプ マッピング手法の一部の機能しかサポートしていないカードもある。一部のハードウェアでは、バンプ マッピングをサポートしていない場合や、一部しかサポートしていない場合がある。バンプ マッピングの詳細については、「バンプ マッピング」を参照すること。

パス

ソース :(SDK ルート)\Samples\Multimedia\Direct3D\BumpMapping\BumpUnderWater

実行可能ファイル :(SDK ルート)\Samples\Multimedia\Direct3D\Bin

ユーザーズ ガイド

次の表は実装されているキーを示している。メニュー コマンドを使って同じ操作を行うことができる。

キー | アクション
Enter | シーンを開始および停止する。
Space | シーンを少しずつ進める。
F2 | 新しいレンダリング デバイスまたはディスプレイ モードを選択するようユーザーに指示する。
Alt + Enter | フルスクリーン モードとウィンドウ モードを切り替える。
Esc | アプリケーションを終了する。

プログラミング上の注意

バンプ マップは摂動データを保存するテクスチャである。バンプ マッピングは 2 つのテクスチャを必要とする。1 つは環境マップで、シーン内で表示されるライトが含まれる。もう 1 つは実際のバンプ マッピングであり、環境マップのテクスチャ座標をバンプするために使用される値 (du および dv) が含まれる。一部のバンプ マップでは、特定のテクセルの輝きを制御する輝度の値も含まれる。

このサンプルでは、従来の方法とは異なる方法でバンプ マッピングを使用する。バンプ マッピングは環境マップを摂動するので、ほかのエフェクトにも使用できる。ここでは、バックグラウンド イメージを摂動して (その場でレンダリングできる)、水中のエフェクトを作成している。

このサンプルでは、ヘルパー関数などのプログラミング要素から構成される共通の DirectX コードを使用している。このコードは DirectX SDK のほかのサンプルと共有されている。共通のヘッダーおよびソース コードは、(SDK ルート)\Samples\Multimedia\Common にある。


BumpWaves サンプル

説明

BumpWave サンプルでは、Microsoft® Direct3D® のバンプ マッピング機能を示す。バンプ マッピングは、粗い凹凸のあるサーフェスの外観をレンダリングするマルチテクスチャ ブレンディング手法である。このサンプルでは、4 つの三角形だけで水辺のシーンをレンダリングしている。シーン内の波はすべてバンプ マップを使って作成されている。

バンプ マッピング手法の一部の機能しかサポートしていないカードもある。一部のハードウェアでは、バンプ マッピングをサポートしていない場合や、一部しかサポートしていない場合がある。バンプ マッピングの詳細については、Microsoft DirectX® SDK のマニュアルを参照すること。

このサンプルでは、射影テクスチャと呼ばれるテクスチャ座標生成手法も使用するが、このサンプルの中心ではない。テクスチャ座標の生成の詳細については、「バンプ マッピング」を参照すること。

パス

ソース :(SDK ルート)\Samples\Multimedia\Direct3D\BumpMapping\BumpWaves

実行可能ファイル :(SDK ルート)\Samples\Multimedia\Direct3D\Bin

ユーザーズ ガイド

次の表は実装されているキーを示している。メニュー コマンドを使って同じ操作を行うことができる。

キー | アクション
Enter | シーンを開始および停止する。
Space | シーンを少しずつ進める。
F2 | 新しいレンダリング デバイスまたはディスプレイ モードを選択するようユーザーに指示する。
Alt + Enter | フルスクリーン モードとウィンドウ モードを切り替える。
Esc | アプリケーションを終了する。

プログラミング上の注意

バンプ マップは摂動データを保存するテクスチャである。バンプ マッピングは 2 つのテクスチャを必要とする。1 つは環境マップで、シーン内で表示されるライトが含まれる。もう 1 つは実際のバンプ マッピングであり、環境マップのテクスチャ座標をバンプするために使用される値 (du および dv) が含まれる。一部のバンプ マップでは、特定のテクセルの輝きを制御する輝度の値も含まれる。

このサンプルでは、バンプ マッピングを使ってシーン内の波を生成している。背景は環境マップの射影テクスチャとして使用されているので、波で反射する。波自体は、多くのポリゴンを使って生成されたように見える。しかし、それは 1 つの大きな四角形である。

このサンプルでは、ヘルパー関数などのプログラミング要素から構成される共通の Microsoft DirectX コードを使用している。このコードは DirectX SDK のほかのサンプルと共有されている。共通のヘッダーおよびソース コードは、(SDK ルート)\Samples\Multimedia\Common にある。


DotProduct3 サンプル

説明

DotProduct3 サンプルでは、Microsoft® Direct3D® のバンプ マッピングの別のアプローチを示す。この手法は、ライトのベクトルとサーフェスの法線を組み合わせる数学的な処理にちなんで名前が付けられている。サーフェスの法線は、RGBA フォーマットでテクスチャ マップ (この手法では法線マップと呼ばれる) に保存される従来の (x,y,z) ベクトルである。

すべてのカードが DotProduct3 ブレンディング テクスチャ ステージをサポートしているわけではなく、すべてのカードが Direct3D バンプ マッピングをサポートしているわけでもない。

パス

ソース :(SDK ルート)\Samples\Multimedia\Direct3D\BumpMapping\DotProduct3

実行可能ファイル :(SDK ルート)\Samples\Multimedia\Direct3D\Bin

ユーザーズ ガイド

次の表は実装されているキーを示している。メニュー コマンドを使って同じ操作を行うことができる。

キー | アクション
Enter | シーンを開始および停止する。
Space | シーンを少しずつ進める。
F2 | 新しいレンダリング デバイスまたはディスプレイ モードを選択するようユーザーに指示する。
Alt + Enter | フルスクリーン モードとウィンドウ モードを切り替える。
Esc | アプリケーションを終了する。

プログラミング上の注意

バンプ マッピングをシミュレートするライティングの方程式では、サーフェスの法線とライティングのベクトルの内積を使用する。ライティングのベクトルはテクスチャ係数に渡され、法線はテクスチャ マップにエンコードされる。ブレンディング ステージは次のようになる。

SetTextureStageState( 0, D3DTSS_COLOROP, D3DTOP_DOTPRODUCT3 );
SetTextureStageState( 0, D3DTSS_COLORARG1, D3DTA_TEXTURE );
SetTextureStageState( 0, D3DTSS_COLORARG2, D3DTA_TFACTOR );

次の手順は、法線をテクスチャに保存することである。これを行うために、ベクトルの要素 (XYZW) はそれぞれ、32 ビット浮動小数点数値から符号付き 8 ビット整数に変換され、テクスチャ カラー (RGBA) にパックされる。コードでは、独自に生成した法線マップ、およびバンプ マッピング テクスチャ イメージから構築された法線マップを使って、これを行う方法を示している。

バンプ マッピング手法の一部の機能しかサポートしていないカードもある。一部のハードウェアでは、バンプ マッピングをサポートしていない場合や、一部しかサポートしていない場合がある。バンプ マッピングの詳細については、Microsoft® DirectX® SDK のマニュアルを参照すること。

このサンプルでは、ヘルパー関数などのプログラミング要素から構成される共通の DirectX コードを使用している。このコードは DirectX SDK のほかのサンプルと共有されている。共通のヘッダーおよびソース コードは、(SDK ルート)\Samples\Multimedia\Common にある。


Emboss サンプル

説明

Emboss サンプルでは、Microsoft® Direct3D® のバンプ マッピングの別のアプローチを示す。エンボスは自分自身から高さマップを取り出し、少し変更されたテクスチャ座標を持つことによって行われる。

Direct3D のバンプ マッピングをサポートしていないカードもある。詳細については、Microsoft DirectX® SDK のマニュアルを参照すること。

パス

ソース :(SDK ルート)\Samples\Multimedia\Direct3D\Emboss

実行可能ファイル :(SDK ルート)\Samples\Multimedia\Direct3D\Bin

ユーザーズ ガイド

次の表は実装されているキーを示している。メニュー コマンドを使って同じ操作を行うことができる。

キー | アクション
Enter | シーンを開始および停止する。
Space | シーンを少しずつ進める。
F2 | 新しいレンダリング デバイスまたはディスプレイ モードを選択するようユーザーに指示する。
Alt + Enter | フルスクリーン モードとウィンドウ モードを切り替える。
Esc | アプリケーションを終了する。
Ctrl-E | エンボス エフェクトのオン/オフを切り替える。

プログラミング上の注意

バンプ マップは摂動データを保存するテクスチャである。バンプ マッピングは 2 つのテクスチャを必要とする。1 つは環境マップで、シーン内で表示されるライトが含まれる。もう 1 つは実際のバンプ マッピングであり、環境マップのテクスチャ座標をバンプするために使用される値 (du および dv) が含まれる。一部のバンプ マップでは、特定のテクセルの輝きを制御する輝度の値も含まれる。

このサンプルでは、バンプ マップはトラの表皮のエンボスに使用されている。

このサンプルでは、ヘルパー関数などのプログラミング要素から構成される共通の DirectX コードを使用している。このコードは DirectX SDK のほかのサンプルと共有されている。共通のヘッダーおよびソース コードは、(SDK ルート)\Samples\Multimedia\Common にある。


ClipMirror サンプル

説明

ClipMirror サンプルでは、独自に定義したクリップ面の使い方を示す。3D シーンは通常どおりレンダリングされ、2 回目のパスで平面の鏡に反射されたようにレンダリングされる。クリップ面は、反射されたシーンを鏡のエッジで切り取るために使用する。

パス

ソース :(SDK ルート)\Samples\Multimedia\Direct3D\ClipMirror

実行可能ファイル :(SDK ルート)\Samples\Multimedia\Direct3D\Bin

ユーザーズ ガイド

次の表は実装されているキーを示している。メニュー コマンドを使って同じ操作を行うことができる。

キー | アクション
Enter | シーンを開始および停止する。
Space | シーンを少しずつ進める。
F2 | 新しいレンダリング デバイスまたはディスプレイ モードを選択するようユーザーに指示する。
Alt + Enter | フルスクリーン モードとウィンドウ モードを切り替える。
Esc | アプリケーションを終了する。

このサンプルでは、マウスを使って視点の位置を制御できる。

プログラミング上の注意

このサンプルの主な特徴は、クリップ面の使い方である。矩形の鏡には 4 つのエッジがあるので、4 つのクリップ面が使用される。各クリップ面は、視点と鏡の 1 つのエッジの 2 つの頂点によって定義される。クリップ面を配置すると、ビュー行列は鏡の平面で反射され、シーンのジオメトリ (ティーポット オブジェクト) は通常どおりレンダリングできる。その後、鏡自体を表す半透明の矩形が描画される。

このサンプルでは、ヘルパー関数などのプログラミング要素から構成される共通の DirectX コードを使用している。このコードは DirectX SDK のほかのサンプルと共有されている。共通のヘッダーおよびソース コードは、(SDK ルート)\Samples\Multimedia\Common にある。


DolphinVS サンプル

説明

DolphinVS サンプルでは、イルカと海底にコースティク エフェクトを適用した、イルカが泳ぐ水中のシーンを示す。イルカはトゥイーニングと呼ばれる手法を使ってアニメーションされる。水中のエフェクトにはフォグを使用し、ウォーター コースティクスにはテクスチャのアニメーション セットを使用している。これらのエフェクトは、頂点シェーダを使って実現されている。

パス

ソース :(SDK ルート)\Samples\Multimedia\Direct3D\DolphinVS

実行可能ファイル :(SDK ルート)\Samples\Multimedia\Direct3D\Bin

ユーザーズ ガイド

次の表は実装されているキーを示している。メニュー コマンドを使って同じ操作を行うことができる。

キー | アクション
Enter | シーンを開始および停止する。
Space | シーンを少しずつ進める。
F2 | 新しいレンダリング デバイスまたはディスプレイ モードを選択するようユーザーに指示する。
Alt + Enter | フルスクリーン モードとウィンドウ モードを切り替える。
Esc | アプリケーションを終了する。

プログラミング上の注意

このサンプルでは、複数の処理が行われている。

  • 2 つの頂点シェーダが使用されている。1 つはイルカに、もう 1 つは海底に使用されている。頂点シェーダは、DolphinTween.vsh と SeaFloor.vsh の 2 つのファイルからアセンブルされるアセンブリ命令である。
  • イルカにはトゥイーニング (モーフィングの一種) が適用される。これを行うために、複数の頂点ストリームで 3 種類のイルカが渡される。頂点シェーダは、各メッシュの重み付けされた座標位置を使って、出力位置を生成する。次に、頂点がライティングされ、テクスチャ座標が計算され、フォグが追加される。
  • 海底も同様に処理されるが、トゥイーニングの必要はない。コースティク エフェクトは、32 のテクスチャのセットをアニメーションして、別のアルファ ブレンディング パスで追加される。コースティクスのテクスチャ座標は頂点シェーダで生成され、TEXCOORDINDEX ステージ 1 として保存される。

このサンプルでは、ヘルパー関数などのプログラミング要素から構成される共通の Microsoft® DirectX® コードを使用している。このコードは DirectX SDK のほかのサンプルと共有されている。共通のヘッダーおよびソース コードは、(SDK ルート)\Samples\Multimedia\Common にある。


DXTex ツール

説明

DXTex ツールを使うと、DirectX SDK ユーザーは新しい DXTn 圧縮フォーマットを使ってテクスチャ マップを作成できる。DXTn で圧縮されたテクスチャの作成は難しくない。ただし、Direct3D では IDirect3DTexture8 インターフェイスを使うと、自動的にこの変換を行うことができる。知識のある開発者であれば、特定の用途に合った独自のツールを作成することもできるが、DXTex ツールには役に立つ基本的な機能が用意されている。

機能

  • .bmp および DirectDrawSurface (DDS) ファイルを開く。詳細については、後の「DDS ファイル フォーマット」を参照すること。
  • .bmp ファイルを明示的または非明示的にアルファ チャネルとして開く (<filename>_a.bmp の命名規則を使用)。
  • テクスチャを DDS フォーマットで保存する。
  • 5 つの DXTn 圧縮フォーマットすべてへの変換をサポートする。
  • ミップマップの生成をサポートする (ボックス フィルタを使用)。
  • グレースケール イメージまたはユーザーが選択可能な背景色によってアルファ チャネルの視覚化をサポートする。
  • フォーマットごとの画質を視覚的に容易に比較できる。

パス

ソース :(SDK ルート)\Samples\Multimedia\Direct3D\DXTex

実行可能ファイル :(SDK ルート)\bin\dxutils

ユーザー インターフェイス

DxTex では、各テクスチャ マップはドキュメントであり、複数のドキュメントを一度に開くことができる、一般的なユーザー インターフェイス (UI) を使用している。ただし、ドキュメントを DxTex で開いている間は、各ドキュメントでは 1 つまたは 2 つのフォーマットでテクスチャを保持できる。たとえば、.bmp ファイルをインポートし、自動的に 32 ビット ARGB テクスチャを作成できる。次に、このテクスチャを DXT1 フォーマットに変換する。この時点で、ドキュメントにはイメージが 2 つのフォーマットで開かれている。フォーマットを切り替えるには、ウィンドウをクリックするか、[View] メニューの [Original View] または [New View] をクリックする。この方法を使用すると、イメージ圧縮によって生じる不自然な効果を確認でき、イメージを段階的に劣化させることなく別の圧縮形式を試すことができる。たとえば、この方法を使用せずに、イメージを ARGB から DXT1 に変換すると、アルファの 1 ビットを除くすべてのビットが失われる。

その後、DXT2 に変換しても、アルファ レベルは 2 つしか存在しないことになる。DxTex システムでは、この 2 回目の変換は元の ARGB フォーマットから行われ、変換された DXT2 イメージには、DXT2 がサポートする 16 レベルのアルファがすべて含まれる。このイメージを保存すると、元のフォーマットは破棄されて新しいフォーマットのみが保存される。

DxTex インターフェイスを使うときには、次の点に注意すること。

  • ファイルが開かれてからフォーマットの変換がまったく要求されなかった場合、その 1 つのフォーマットが元のフォーマットとなり、ファイルを保存するときにはそのフォーマットでイメージが書き込まれる。
  • ファイルが開かれてからフォーマットの変換が要求された場合、変換されたフォーマットが新しいフォーマットとなり、ファイルを保存するとそのフォーマットでイメージが書き込まれる。
  • 2 回目の変換が要求された場合、最初の変換で作成された「新しい」フォーマットが第 2 のフォーマットに置き換えられる。元のフォーマットは変更されない。
  • ミップマップの生成は、両方のフォーマットに同時に適用される。
  • 元のフォーマットに複数のミップマップがあり、新しいフォーマットへの変換が要求された場合、新しいフォーマットにも自動的に複数のミップマップが存在することになる。

パフォーマンス

DxTex では、3D ハードウェアが使用可能かどうかに関係なく、Microsoft Direct3D® リファレンス ラスタライザを使ってテクスチャを描画する。したがって、テクスチャが大きい (256x256 ピクセルを超える) 場合、アプリケーションは CPU の速度に応じて若干遅くなることがある。

DSS ファイル フォーマット

DxTex ネイティブ ファイル フォーマットは、DirectDrawSurface に情報をカプセル化するので、DDS ファイル フォーマットと呼ばれる。DDS ファイルのフォーマットは、次のとおりである。

DWORD dwMagic (0x20534444, または "DDS")
DDSURFACEDESC2 ddsd (サーフェス フォーマットに関する情報を提供する)
BYTE bData1[] (メイン サーフェスのサーフェス データ)
[BYTE bData2[]...] (アタッチされるサーフェスのサーフェス データ)

このフォーマットは読み書きが簡単で、DXTn 圧縮だけでなく、アルファやマルチ ミップ レベルなどの機能もサポートする。DirectX SDK の Compress サンプル アプリケーションでは、DDS ファイルを正しくインポートする方法を示している。

DXTn 圧縮したテクスチャを使用するために DDS フォーマットを使う必要はなく、その逆の場合も同様であるが、これら 2 つは連携している。

ミップマップ

ミップマップは、複数の解像度であらかじめフィルタ処理されたテクスチャ イメージを提供することによって、画質を向上させ、テクスチャ メモリの帯域幅を減少させる手法である。

DxTex のミップマップを生成するには、ソース イメージの幅と高さが共に 2 の累乗になっている必要がある。このミップマップを生成するには、[Format] メニューの [Generate Mip Maps] をクリックする。フィルタリングは、単純なボックス フィルタで実行される。つまり、最も近い 4 つのピクセルが平均化されて目的のピクセルが作成される。

アルファ

多くのテクスチャ フォーマットには、各ピクセルの不透明度の情報を提供するアルファ チャネルが含まれている。DxTex はテクスチャにおけるアルファを完全サポートする。.bmp ファイルをインポートする場合に、サイズが同じ 2 つのファイルが存在し、その一方のファイル名が "_a" で終わるときには (Sample.bmp および Sample_a.bmp など)、"_a" で終わるファイルがアルファ チャネルとしてロードされる。この 2 つ目の .bmp の青のチャネルがアルファ チャネルに格納される。ファイルを開いた後は、[File] メニューの [Open As Alpha Channel] をクリックして、明示的に .bmp ファイルをアルファ チャネルとしてロードできる。

アルファ チャネルを RGB チャネルなしで直接表示するには、[View] メニューの [Alpha Channel Only] をクリックする。アルファ チャネルがグレースケール イメージとして表示される。アルファ チャネルがロードされていない場合、すべてのピクセルでアルファ チャネルは 100 パーセントとなり、[Alpha Channel Only] を選択するとイメージが白く塗りつぶされる。アルファ チャネルを非表示にするには、[Alpha Channel Only] をもう一度クリックする。

通常のビューではアルファ チャネルの効果が目に見えるが、これは、ウィンドウがバックグラウンド カラーで塗りつぶされており、アルファ チャネルが 100 パーセント未満のテクスチャでは、その色が透けて見えるからである。バックグラウンド カラーを変更するには、[View] メニューの [Change Background Color] をクリックする。この選択を実行しても、テクスチャそのもの、またはファイルを保存するときに書き込まれるデータには影響しない。

DXT2 フォーマットおよび DXT4 フォーマットでは、あらかじめ計算されたアルファが使用される。つまり、サーフェスに格納される赤、緑、および青の値には、対応するアルファ値が既に乗算されている。Direct3D では、あらかじめ計算されたアルファが含まれるサーフェスからあらかじめ計算されていないアルファが含まれるサーフェスにコピーすることはできない。したがって、DxTex の一部の処理 (アルファ チャネルとして開く、DXT3 への変換、および DXT5 への変換) は、DXT2 および DXT4 フォーマットでは実行できない。DXTn テクスチャをサポートしない Direct3D デバイス では、これらのフォーマットを使用したテクスチャをサポートすることは難しい。これは、Direct3D ではこれらのフォーマットを従来のARGB サーフェスへもコピーできないためである。ARGB サーフェスでもあらかじめ計算されたアルファが使用されている場合はコピーできるが、このようなことはまれである。このような理由から、可能であれば DXT2 よりも DXT3 を、DXT4 よりも DXT5 を使用する方が簡単である。

コマンド ライン オプション

コマンドライン オプションを使って、入力ファイル、出力ファイル名、および処理オプションを DxTex に渡すことができる。出力ファイル名を指定した場合は、その出力ファイルを書き込んだ後にアプリケーションが自動終了し、ユーザー インターフェイスは表示されない。

dxtex [infilename] [-a alphaname] [-m] [DXT1|DXT2|DXT3|DXT4|DXT5] [outfilename]

infilename:               ロードするファイルの名前。
                          .bmp または DDS ファイルが可能。

-a alphaname:             次のパラメータはアルファ チャネルとして
                          ロードする .bmp ファイルの名前。
                          アルファ ファイル名を指定しないと、DxTex は
                          Infilename_a.bmp. という名のファイルを探し、
                          アルファ チャネルとして使用することに
                          注意すること。

-m:                       ミップマップが生成される。

DXT1|DXT2|DXT3|DXT4|DXT5: 圧縮フォーマット。フォーマットを指定しないと
                          イメージは ARGB-8888 となる。

outfilename:              出力ファイル名。  このオプションを指定しないと
                          ユーザー インターフェイスは現在のファイルと
                          すべての必要な操作を表示する。
                          出力ファイル名を指定すると、
                          アプリケーションはセーブ後、
                          ユーザー インターフェイスを表示せずに
                          終了する。


EnhancedMesh サンプル

説明

EnhancedMesh サンプルでは、D3DX を使ってメッシュをロードしてサブディビジョンする方法を示す。メッシュは、頂点カウントを増やすことによってサブディビジョンされる。

パス

ソース :(SDK ルート)\Samples\Multimedia\Direct3D\EnhancedMesh

実行可能ファイル :(SDK ルート)\Samples\Multimedia\Direct3D\Bin

ユーザーズ ガイド

次の表は実装されているキーを示している。メニュー コマンドを使って同じ操作を行うことができる。

キー | アクション
Enter | シーンを開始および停止する。
Space | シーンを少しずつ進める。
F2 | 新しいレンダリング デバイスまたはディスプレイ モードを選択するようユーザーに指示する。
Alt + Enter | フルスクリーン モードとウィンドウ モードを切り替える。
Esc | アプリケーションを終了する。

プログラミング上の注意

このサンプルでは、ヘルパー関数などのプログラミング要素から構成される共通の Microsoft® DirectX® コードを使用している。このコードは DirectX SDK のほかのサンプルと共有されている。共通のヘッダーおよびソース コードは、(SDK ルート)\Samples\Multimedia\Common にある。


CubeMap サンプル

説明

CubeMap サンプルでは、キューブ マッピングと呼ばれる環境マッピングの手法を示す。環境マッピングは、3D オブジェクトの周囲の環境 (ライトなど) をテクスチャ マップに配置し、ライティングの計算を行わずにオブジェクトに複雑なライティング エフェクトを適用できる手法である。

環境マッピングの手法 (キューブ マッピングや射影テクスチャなど) の一部の機能しかサポートしていないカードもある。環境マッピング、キューブ マッピング、および射影テクスチャの詳細については、Microsoft® DirectX® SDK のマニュアルを参照すること。

パス

ソース :(SDK ルート)\Samples\Multimedia\Direct3D\EnvMapping\CubeMap

実行可能ファイル :(SDK ルート)\Samples\Multimedia\Direct3D\Bin

ユーザーズ ガイド

次の表は実装されているキーを示している。メニュー コマンドを使って同じ操作を行うことができる。

キー | アクション
Enter | シーンを開始および停止する。
Space | シーンを少しずつ進める。
F2 | 新しいレンダリング デバイスまたはディスプレイ モードを選択するようユーザーに指示する。
Alt + Enter | フルスクリーン モードとウィンドウ モードを切り替える。
Esc | アプリケーションを終了する。

プログラミング上の注意

キューブ マッピングは、6 面のテクスチャを使用する手法である。この手法のエフェクトを視覚化するには、壁紙を貼った部屋にある、壁紙で縮小ラップされたオブジェクトを考えてみるとよい。キューブ マッピングは球体マッピングよりも優れている。これは、球体マッピングが本質的にビューに依存するからである (球体マップは特定の視点を念頭に置いて作成される)。また、キューブ マップではジオメトリの歪みが生じないので、キューブ マップの 6 面すべてについて、IDirect3DDevice8::SetRenderTarget を使ってその場で生成できる。

キューブ マッピングは、Microsoft Direct3D® のテクスチャ座標生成でも使用できる。D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR を設定することによって、Direct3D は頂点の反射ベクトルからキューブ マップのテクスチャ座標を生成するので、この手法を使うと、環境がオブジェクトで反射される場合の環境マッピング エフェクトを容易に作成できる。

このサンプルでは、ヘルパー関数などのプログラミング要素から構成される共通の DirectX コードを使用している。このコードは DirectX SDK のほかのサンプルと共有されている。共通のヘッダーおよびソース コードは、(SDK ルート)\Samples\Multimedia\Common にある。


FishEye サンプル

説明

FishEye サンプルでは、キューブ マップを使って実現できる魚眼レンズのエフェクトを示す。

パス

ソース :(SDK ルート)\Samples\Multimedia\Direct3D\EnvMapping\FishEye

実行可能ファイル :(SDK ルート)\Samples\Multimedia\Direct3D\Bin

ユーザーズ ガイド

次の表は実装されているキーを示している。メニュー コマンドを使って同じ操作を行うことができる。

キー | アクション
Enter | シーンを開始および停止する。
Space | シーンを少しずつ進める。
F2 | 新しいレンダリング デバイスまたはディスプレイ モードを選択するようユーザーに指示する。
Alt + Enter | フルスクリーン モードとウィンドウ モードを切り替える。
Esc | アプリケーションを終了する。

プログラミング上の注意

FishEye サンプルのシーンは、バック バッファではなく、キューブ マップのサーフェスにレンダリングされる。次に、このキューブ マップを、ジオメトリを少し歪めてシーンを反射する環境マップとして使用する。ここでは、一部のジオメトリが魚眼レンズのようになる。キューブ マッピングの詳細については、「CubeMap サンプル」を参照すること。

このサンプルでは、ヘルパー関数などのプログラミング要素から構成される共通の Microsoft DirectX® コードを使用している。このコードは DirectX SDK のほかのサンプルと共有されている。共通のヘッダーおよびソース コードは、(SDK ルート)\Samples\Multimedia\Common にある。


SphereMap サンプル

説明

SphereMap サンプルでは、球体マッピングと呼ばれる環境マッピングの手法を示す。環境マッピングは、3D オブジェクトの周囲の環境 (ライトなど) をテクスチャ マップに配置し、ライティングの計算を行わずにオブジェクトに複雑なライティング エフェクトを適用できる手法である。

環境マッピングの手法 (キューブ マッピングや射影テクスチャなど) の一部の機能しかサポートしていないカードもある。環境マッピング、キューブ マッピング、および射影テクスチャの詳細については、Microsoft® DirectX® SDK のマニュアルを参照すること。

パス

ソース :(SDK ルート)\Samples\Multimedia\Direct3D\EnvMapping\SphereMap

実行可能ファイル :(SDK ルート)\Samples\Multimedia\Direct3D\Bin

ユーザーズ ガイド

次の表は実装されているキーを示している。メニュー コマンドを使って同じ操作を行うことができる。

キー | アクション
Enter | シーンを開始および停止する。
Space | シーンを少しずつ進める。
F2 | 新しいレンダリング デバイスまたはディスプレイ モードを選択するようユーザーに指示する。
Alt + Enter | フルスクリーン モードとウィンドウ モードを切り替える。
Esc | アプリケーションを終了する。

プログラミング上の注意

球体マッピングでは、モデリング時にあらかじめ計算された、クロームの球体によって反射された環境全体を含むテクスチャ マップを使用する。この手法では、各頂点について、その法線を計算し、その法線がクロームの球体上で一致する位置を見つけて、そのテクスチャ座標を頂点に割り当てる。

マッチングは複雑ではないが、各フレームの各頂点について計算が必要である。Direct3D には、このために使用できるテクスチャ座標生成機能がある。関連するレンダリング ステート処理は D3DTSS_TCI_CAMERASPACENORMAL で、カメラ空間での頂点の法線を使用し、テクスチャ トランスフォームによって変形し、テクスチャ座標を生成する。次に、テクスチャ行列を設定して残りの処理を行う。この単純なケースでは、行列は、カメラ空間 (-1, +1) からテクスチャ空間 (0,1) を取得するために、テクスチャ座標をスケーリングして、平行移動するだけである。

このサンプルでは、ヘルパー関数などのプログラミング要素から構成される共通の DirectX コードを使用している。このコードは DirectX SDK のほかのサンプルと共有されている。共通のヘッダーおよびソース コードは、(SDK ルート)\Samples\Multimedia\Common にある。


MFCFog サンプル

説明

MFCFog サンプルでは、CFormView を使用して、Microsoft® Direct3D® を Microsoft Foundation Classes (MFC) と共に使う方法を示す。さまざまなコントロールを使って、3D シーンのフォグ パラメータを制御する。

パス

ソース :(SDK ルート)\Samples\Multimedia\Direct3D\MFCFog

実行可能ファイル :(SDK ルート)\Samples\Multimedia\Direct3D\Bin

ユーザーズ ガイド

このサンプルでのユーザーの操作はすべて、表示可能な MFC コントロール (スライダ、ラジオ ボタンなど) によって実装される。ユーザーはコントロールを操作して、レンダリングした 3D シーンでさまざまなエフェクトを表示できる。

プログラミング上の注意

すべての MFC コードは、CFormView クラスの派生メンバ関数と共に格納されている。MFC コードおよび D3D 初期化コードは、D3dapp.cpp ソース ファイルに記述されている。このファイルは、フォグ関連のコードを取り出して、ほかのアプリケーションで動作するように移植できる。

Direct3D のフォグ コードは Fog.cpp に記述されている。このファイルには、シーンを初期化、アニメーション、レンダリング、およびクリーン アップするための関数もある。

このサンプルでは、ヘルパー関数などのプログラミング要素から構成される共通の Microsoft DirectX® コードを使用している。このコードは DirectX SDK のほかのサンプルと共有されている。共通のヘッダーおよびソース コードは、(SDK ルート)\Samples\Multimedia\Common にある。


MFCPixelShader サンプル

説明

MFCFog サンプルでは、CFormView を使用して、Microsoft® Direct3D® を Microsoft Foundation Classes (MFC) と共に使う方法を示す。さまざまなコントロールを使用して、3D シーン用のピクセル シェーダを制御する。

パス

ソース :(SDK ルート)\Samples\Multimedia\Direct3D\MFCPixelShader

実行可能ファイル :(SDK ルート)\Samples\Multimedia\Direct3D\Bin

ユーザーズ ガイド

このサンプルでのユーザーの操作はすべて、表示可能な MFC コントロール (スライダ、ラジオ ボタンなど) によって実装される。ユーザーはコントロールを操作して、レンダリングした 3D シーンでさまざまなエフェクトを表示できる。

プログラミング上の注意

すべての MFC コードは、CFormView クラスの派生メンバ関数と共に格納されている。MFC コードおよび D3D 初期化コードは、D3dapp.cpp ソース ファイルに記述されている。このファイルは、フォグ関連のコードを取り出して、ほかのアプリケーションで動作するように移植できる。

このサンプルでは、ヘルパー関数などのプログラミング要素から構成される共通の Microsoft DirectX® コードを使用している。このコードは DirectX SDK のほかのサンプルと共有されている。共通のヘッダーおよびソース コードは、(SDK ルート)\Samples\Multimedia\Common にある。


MFCTex サンプル

説明

MFCTex サンプルでは、CFormView を使用して、Microsoft® Direct3D® を Microsoft Foundation Classes (MFC) と共に使う方法を示す。さまざまなコントロールを使用して、テクスチャの外観を制御する。

パス

ソース :(SDK ルート)\Samples\Multimedia\Direct3D\MFCTex

実行可能ファイル :(SDK ルート)\Samples\Multimedia\Direct3D\Bin

ユーザーズ ガイド

このサンプルでのユーザーの操作はすべて、表示可能な MFC コントロール (スライダ、ラジオ ボタンなど) によって実装される。ユーザーはコントロールを操作して、レンダリングした 3D シーンでさまざまなエフェクトを表示できる。

プログラミング上の注意

すべての MFC コードは、CFormView クラスの派生メンバ関数と共に格納されている。MFC コードおよび D3D 初期化コードは、D3dapp.cpp ソース ファイルに記述されている。このファイルは、フォグ関連のコードを取り出して、ほかのアプリケーションで動作するように移植できる。

このサンプルでは、ヘルパー関数などのプログラミング要素から構成される共通の Microsoft DirectX® コードを使用している。このコードは DirectX SDK のほかのサンプルと共有されている。共通のヘッダーおよびソース コードは、(SDK ルート)\Samples\Multimedia\Common にある。


OptimizedMesh サンプル

説明

OptimizedMesh サンプルでは、D3DX メッシュ ユーティリティ関数を使って、ファイル ベースのメッシュをロードして最適化する方法を示す。

D3DX の詳細については、Microsoft® DirectX® SDK のマニュアルを参照すること。

パス

ソース :(SDK ルート)\Samples\Multimedia\Direct3D\OptimizedMesh

実行可能ファイル :(SDK ルート)\Samples\Multimedia\Direct3D\Bin

ユーザーズ ガイド

次の表は実装されているキーを示している。メニュー コマンドを使って同じ操作を行うことができる。

キー | アクション
Enter | シーンを開始および停止する。
Space | シーンを少しずつ進める。
F2 | 新しいレンダリング デバイスまたはディスプレイ モードを選択するようユーザーに指示する。
Alt + Enter | フルスクリーン モードとウィンドウ モードを切り替える。
Esc | アプリケーションを終了する。
Ctrl-O | メッシュ ファイルを開く。
Ctrl-M | 最も効果的なメッシュを切り替える。

プログラミング上の注意

DirectX SDK に含まれる多くの Microsoft Direct3D® のサンプルでは、ファイル ベースのメッシュが使用されている。OptimizedMesh サンプルは、メッシュをロードするのに必要な基本的なコードの良い例である。D3DX メッシュ ロード機能は、.x ファイルのフレーム階層を 1 つのメッシュにまとめる。

ほかのサンプルでは、純粋な D3DX メッシュ機能は共通クラス CD3DMesh にラップされている。フレーム階層を保持する場合は、共通クラス CD3DFile を使用できる。

このサンプルでは、ヘルパー関数などのプログラミング要素から構成される共通の DirectX コードを使用している。このコードは DirectX SDK のほかのサンプルと共有されている。共通のヘッダーおよびソース コードは、(SDK ルート)\Samples\Multimedia\Common にある。


Pick サンプル

説明

Pick サンプルでは、ピッキングを実装する方法を示す。ピッキングとは、メッシュ内のどの三角形がレイに当たるかを見つけることである。ここでは、レイはマウス座標で指定する。

パス

ソース :(SDK ルート)\Samples\Multimedia\Direct3D\Pick

実行可能ファイル :(SDK ルート)\Samples\Multimedia\Direct3D\Bin

ユーザーズ ガイド

次の表は実装されているキーを示している。メニュー コマンドを使って同じ操作を行うことができる。

キー | アクション
Enter | シーンを開始および停止する。
Space | シーンを少しずつ進める。
F2 | 新しいレンダリング デバイスまたはディスプレイ モードを選択するようユーザーに指示する。
Alt + Enter | フルスクリーン モードとウィンドウ モードを切り替える。
Esc | アプリケーションを終了する。

マウスを使ってメッシュ内の任意のスポットをピックすると、その三角形が表示される。

プログラミング上の注意

マウスをクリックすると、カーソルのスクリーン座標が読み取られる。これらの座標は、射影行列およびビュー行列によって変換されて、視点からスクリーン上のクリックした位置を通ってシーンに達するレイに変わる。このレイは、ロードされたモデルの各三角形と共に IntersectTriangle に渡され、どの三角形がレイに当たるかが決定される。当たる三角形のテクスチャ座標も決定される。

このサンプルでは、ヘルパー関数などのプログラミング要素から構成される共通の Microsoft® DirectX® コードを使用している。このコードは DirectX SDK のほかのサンプルと共有されている。共通のヘッダーおよびソース コードは、(SDK ルート)\Samples\Multimedia\Common にある。


PointSprites サンプル

説明

PointSprites サンプルでは、Microsoft® Direct3D® の新しいポイント スプライト機能の使い方を示す。ポイント スプライトとは、(x,y,z) 位置座標によってのみ参照される前向きの、テクスチャ処理された四角形である。ポイント スプライトは、粒子システムおよび関連エフェクトでよく使用される。

ポイント スプライトの一部の機能しかサポートしていないカードもある。ポイント スプライトの詳細については、Microsoft DirectX® SDK のマニュアルを参照すること。

パス

ソース :(SDK ルート)\Samples\Multimedia\Direct3D\PointSprites

実行可能ファイル :(SDK ルート)\Samples\Multimedia\Direct3D\Bin

ユーザーズ ガイド

次の表は実装されているキーを示している。メニュー コマンドを使って同じ操作を行うことができる。

キー | アクション
Enter | シーンを開始および停止する。
Space | シーンを少しずつ進める。
W、S | 前後に移動する。
E、Q | 左右に移動する。
A、Z | 上下に回転する。
矢印キー | 上下左右にスライドする。
F1 | ヘルプまたは使用可能なコマンドを表示する。
F2 | 新しいレンダリング デバイスまたはディスプレイ モードを選択するようユーザーに指示する。
F3 | エミッタをアニメーションする。
F4 | 色を変更する。
Alt + Enter | フルスクリーン モードとウィンドウ モードを切り替える。
Esc | アプリケーションを終了する。

プログラミング上の注意

Direct3D サポートを使用しない場合は、ポイント スプライトは各フレームをビルボードと同様に視点の方に向ける 4 つの頂点を使って実装できる。Direct3D を使用する場合は、ポイント スプライトの中心位置と半径によって、各ポイント スプライトを参照できる。これによって、プロセッサの計算時間と、頂点情報をグラフィックス カードにアップロードするための帯域幅を節約できる。

このサンプルでは、各パーティクルは、複数のアルファ ブレンディングされたポイント スプライトを使用し、パーティクルにモーション ブラー エフェクトを与えて実現されている。

このサンプルでは、ヘルパー関数などのプログラミング要素から構成される共通の DirectX コードを使用している。このコードは DirectX SDK のほかのサンプルと共有されている。共通のヘッダーおよびソース コードは、(SDK ルート)\Samples\Multimedia\Common にある。


ProgressiveMesh サンプル

説明

ProgressiveMesh サンプルでは、D3DX メッシュ ユーティリティ関数を使って、ファイル ベースのメッシュをロードして最適化する方法を示す。プログレッシブ メッシュでは、頂点情報が特殊なツリーに保存され、任意の数の頂点を指定してメッシュをレンダリングするためにアクセスできる。この処理は高速なので、プログレッシブ メッシュは、遠くにあるオブジェクトが少ないポリゴンでレンダリングされる詳細レベルを使用する場合に適している。

D3DX の詳細については、Microsoft® DirectX® SDK のマニュアルを参照すること。

パス

ソース :(SDK ルート)\Samples\Multimedia\Direct3D\ProgressiveMesh

実行可能ファイル :(SDK ルート)\Samples\Multimedia\Direct3D\Bin

ユーザーズ ガイド

次の表は実装されているキーを示している。メニュー コマンドを使って同じ操作を行うことができる。

キー | アクション
Enter | シーンを開始および停止する。
Space | シーンを少しずつ進める。
F1 | ヘルプまたは使用可能なコマンドを表示する。
F2 | 新しいレンダリング デバイスまたはディスプレイ モードを選択するようユーザーに指示する。
Alt + Enter | フルスクリーン モードとウィンドウ モードを切り替える。
Esc | アプリケーションを終了する。
↑ | プログレッシブ メッシュに頂点を 1 つ追加する。
↓ | プログレッシブ メッシュから頂点を 1 つ減らす。
PageUp | プログレッシブ メッシュに頂点を 100 個追加する。
PageDown | プログレッシブ メッシュから頂点を 100 個減らす。
Home | プログレッシブ メッシュに使用可能な頂点をすべて表示する。
End | プログレッシブ メッシュの最低限の頂点を表示する。

プログラミング上の注意

DirectX SDK に含まれる多くの Microsoft Direct3D® のサンプルでは、ファイル ベースのメッシュが使用されている。ProgressiveMesh サンプルは、メッシュをロードするのに必要な基本的なコードの良い例である。D3DX メッシュ ロード機能は、.x ファイルのフレーム階層を 1 つのメッシュにまとめる。

プログレッシブ メッシュを使用する第 1 の理由は、メッシュについて ID3DXPMesh::SetNumVertices を呼び出すことである。

ほかのサンプルでは、基本的な D3DX メッシュ機能は共通クラス CD3DMesh にラップされている。フレーム階層を保持する場合は、共通クラス CD3DFile を使用できる。

このサンプルでは、ヘルパー関数などのプログラミング要素から構成される共通の DirectX コードを使用している。このコードは DirectX SDK のほかのサンプルと共有されている。共通のヘッダーおよびソース コードは、(SDK ルート)\Samples\Multimedia\Common にある。


RTPatch サンプル

説明

RTPatch サンプルは、Direct3D でパッチを使用する方法を示す。

パス

ソース :(SDK ルート)\Samples\Multimedia\Direct3D\RTPatch

実行可能ファイル :(SDK ルート)\Samples\Multimedia\Direct3D\Bin

ユーザーズ ガイド

次の表は実装されているキーを示している。メニュー コマンドを使って同じ操作を行うことができる。

キー | アクション
Enter | シーンを開始および停止する。
Space | シーンを少しずつ進める。
F1 | ヘルプまたは使用可能なコマンドを表示する。
F2 | 新しいレンダリング デバイスまたはディスプレイ モードを選択するようユーザーに指示する。
Alt + Enter | フルスクリーン モードとウィンドウ モードを切り替える。
Esc | アプリケーションを終了する。
↑ | セグメントあたりのパッチ数を増やす。
↓ | セグメントあたりのパッチ数を減らす。
W | ワイヤフレームを切り替える。

プログラミング上の注意

このサンプルでは、ヘルパー関数などのプログラミング要素から構成される共通の DirectX コードを使用している。このコードは DirectX SDK のほかのサンプルと共有されている。共通のヘッダーおよびソース コードは、(SDK ルート)\Samples\Multimedia\Common にある。


SkinnedMesh サンプル

説明

SkinnedMesh サンプルは、スキン メッシュのロード方法およびレンダリング方法を示す。

パス

ソース :(SDK ルート)\Samples\Multimedia\Direct3D\SkinnedMesh

実行可能ファイル :(SDK ルート)\Samples\Multimedia\Direct3D\Bin

ユーザーズ ガイド

次の表は実装されているキーを示している。メニュー コマンドを使って同じ操作を行うことができる。

キー | アクション
Enter | シーンを開始および停止する。
Space | シーンを少しずつ進める。
F2 | 新しいレンダリング デバイスまたはディスプレイ モードを選択するようユーザーに指示する。
Alt + Enter | フルスクリーン モードとウィンドウ モードを切り替える。
Esc | アプリケーションを終了する。

プログラミング上の注意

このサンプルでは、ヘルパー関数などのプログラミング要素から構成される共通の DirectX コードを使用している。このコードは DirectX SDK のほかのサンプルと共有されている。共通のヘッダーおよびソース コードは、(SDK ルート)\Samples\Multimedia\Common にある。


ShadowVolume サンプル

説明

ShadowVolume サンプルでは、ステンシル バッファを使って、リアルタイムの影を実現している。このサンプルでは、複雑なオブジェクトがレンダリングされて、影をキャストするオブジェクトとして使用され、そのオブジェクト自体およびその下の地形にリアルタイムの影をキャストしている。

ステンシル バッファは、ジオメトリをレンダリングするときに更新できる深度バッファの手法で、ほかのジオメトリを描画するためのマスクとして再度使用できる。一般的なエフェクトには、鏡、(高度な手法としての) 影、ディゾルブなどがある。

ステンシル バッファ手法の一部の機能しかサポートしていないカードもある。一部のハードウェアでは、ステンシルバッファをサポートしていない場合や、一部しかサポートしていない場合がある。ステンシル バッファの詳細については、Microsoft® DirectX® SDK のマニュアルを参照すること。

パス

ソース :(SDK ルート)\Samples\Multimedia\Direct3D\StencilBuffer\ShadowVolume

実行可能ファイル :(SDK ルート)\Samples\Multimedia\Direct3D\Bin

ユーザーズ ガイド

次の表は実装されているキーを示している。メニュー コマンドを使って同じ操作を行うことができる。

キー | アクション
Enter | シーンを開始および停止する。
Space | シーンを少しずつ進める。
F2 | 新しいレンダリング デバイスまたはディスプレイ モードを選択するようユーザーに指示する。
Alt + Enter | フルスクリーン モードとウィンドウ モードを切り替える。
Esc | アプリケーションを終了する。

プログラミング上の注意

リアルタイムの影の作成はかなり高度な手法である。各フレームで、つまりシーン内のジオメトリまたはライトが移動するときに、シャドウ ボリュームと呼ばれるオブジェクトが計算される。シャドウ ボリュームは、光源から押し出されたときの、影をキャストするオブジェクトのシルエットである 3D オブジェクトである。

このサンプルでは、影をキャストする 3D オブジェクトは複葉機である。飛行機のシルエットは各フレームで計算される。この手法では、エッジ検出アルゴリズムを使用して、シルエットのエッジを検出する。隣接するポリゴンの法線には光のベクトルに関して、反対方向に伸びる法線があるため、このようなエッジ検出が可能である。検出されたエッジ リスト (シルエット) は、光源から離れるように押し出されて 3D オブジェクトになる。この 3D オブジェクトは、このボリュームの内側にあるすべてのポイントが影の中にあるので、シャドウ ボリュームと呼ばれる。

次に、シャドウ ボリュームは、ステンシル バッファに 2 回レンダリングされる。最初は前向きのポリゴンだけがレンダリングされ、ステンシル バッファ値が毎回インクリメントされる。次に、シャドウ ボリュームの後ろ向きのポリゴンが描画され、ステンシル バッファの値がデクリメントされる。通常、インクリメントされた値とデクリメントされた値はすべて互いに打ち消し合う。しかし、シーンは既に法線ジオメトリ (この場合は平面と地形) を使ってレンダリングされているので、一部のピクセルはシャドウ ボリュームをレンダリングするときに Z バッファ テストに合格しない。ステンシル バッファに残った値が、影の中のピクセルに対応する。

最後に、すべてを含む大きな四角形をシーンにアルファ ブレンディングするときに、この残ったステンシル バッファの内容がマスクとして使用される。ステンシル バッファをマスクとして使用することによって、影の中のピクセルだけが暗くなる。

このサンプルでは、ヘルパー関数などのプログラミング要素から構成される共通の Microsoft DirectX® コードを使用している。このコードは DirectX SDK のほかのサンプルと共有されている。共通のヘッダーおよびソース コードは、(SDK ルート)\Samples\Multimedia\Common にある。


StencilDepth サンプル

説明

StencilDepth サンプルでは、ステンシル バッファを使って、シーンの深度構造を表示する。シーンの深度構造は、各ピクセルの平均レンダリング回数として定義される。

ステンシル バッファは、ジオメトリをレンダリングするときに更新できる深度バッファの手法で、ほかのジオメトリを描画するためのマスクとして再度使用できる。一般的なエフェクトには、鏡、(高度な手法としての) 影、ディゾルブなどがある。

パス

ソース :(SDK ルート)\Samples\Multimedia\Direct3D\StencilBuffer\StencilDepth

実行可能ファイル :(SDK ルート)\Samples\Multimedia\Direct3D\Bin

ユーザーズ ガイド

次の表は実装されているキーを示している。メニュー コマンドを使って同じ操作を行うことができる。

キー | アクション
Enter | シーンを開始および停止する。
Space | シーンを少しずつ進める。
F2 | 新しいレンダリング デバイスまたはディスプレイ モードを選択するようユーザーに指示する。
Alt + Enter | フルスクリーン モードとウィンドウ モードを切り替える。
Esc | アプリケーションを終了する。

プログラミング上の注意

深度構造の表示は、シーンのパフォーマンスを分析するための重要なツールである。オーバードローの多いシーンでは、ジオメトリを前から順に並べ替えるなど、シーンの最適化によってパフォーマンスが向上する場合がある。

ステンシルバッファ手法の一部の機能しかサポートしていないカードもある。一部のハードウェアでは、ステンシルバッファをサポートしていない場合や、一部しかサポートしていない場合がある。ステンシル バッファの詳細については、Microsoft® DirectX® SDK のマニュアルを参照すること。

このサンプルでは、ヘルパー関数などのプログラミング要素から構成される共通の DirectX コードを使用している。このコードは DirectX SDK のほかのサンプルと共有されている。共通のヘッダーおよびソース コードは、(SDK ルート)\Samples\Multimedia\Common にある。


StencilMirror サンプル

説明

StencilMirror サンプルでは、ステンシル バッファを使って、鏡のエフェクトを実現している。このサンプルでは、水に覆われた地形のシーンが、上空を飛行するヘリコプターを反射する水を使ってレンダリングされている。

ステンシル バッファは、ジオメトリをレンダリングするときに更新できる深度バッファの手法で、ほかのジオメトリを描画するためのマスクとして再度使用できる。一般的なエフェクトには、鏡、(高度な手法としての) 影、ディゾルブなどがある。

ステンシルバッファ手法の一部の機能しかサポートしていないカードもある。一部のハードウェアでは、ステンシルバッファをサポートしていない場合や、一部しかサポートしていない場合がある。ステンシル バッファの詳細については、Microsoft® DirectX® SDK のマニュアルを参照すること。

パス

ソース :(SDK ルート)\Samples\Multimedia\Direct3D\StencilBuffer\StencilMirror

実行可能ファイル :(SDK ルート)\Samples\Multimedia\Direct3D\Bin

ユーザーズ ガイド

次の表は実装されているキーを示している。メニュー コマンドを使って同じ操作を行うことができる。

キー | アクション
Enter | シーンを開始および停止する。
Space | シーンを少しずつ進める。
F2 | 新しいレンダリング デバイスまたはディスプレイ モードを選択するようユーザーに指示する。
Alt + Enter | フルスクリーン モードとウィンドウ モードを切り替える。
Esc | アプリケーションを終了する。

プログラミング上の注意

このサンプルでは、ステンシル バッファを使って、水面からの反射のエフェクトを作成している。水のジオメトリはステンシル バッファにレンダリングされる。次に、このステンシル バッファがシーンを再度レンダリングするためのマスクとして使用される。このとき、ジオメトリが上下逆に平行移動されてレンダリングされるので、鏡に反射されているように見える。

このサンプルでは、ヘルパー関数などのプログラミング要素から構成される共通の DirectX コードを使用している。このコードは DirectX SDK のほかのサンプルと共有されている。共通のヘッダーおよびソース コードは、(SDK ルート)\Samples\Multimedia\Common にある。


Text3D サンプル

説明

Text3D サンプルでは、3D シーン内に 2D テキストを描画する方法を示す。これは、統計情報やゲームのメニューなどを表示するときに便利である。

パス

ソース :(SDK ルート)\Samples\Multimedia\Direct3D\Text3D

実行可能ファイル :(SDK ルート)\Samples\Multimedia\Direct3D\Bin

ユーザーズ ガイド

次の表は実装されているキーを示している。メニュー コマンドを使って同じ操作を行うことができる。

キー | アクション
Enter | シーンを開始および停止する。
Space | シーンを少しずつ進める。
F2 | 新しいレンダリング デバイスまたはディスプレイ モードを選択するようユーザーに指示する。
Alt + Enter | フルスクリーン モードとウィンドウ モードを切り替える。
Esc | アプリケーションを終了する。

プログラミング上の注意

このサンプルでは、共通クラス CD3DFont を使って、3D シーン内に 2D テキストを表示する。このクラスのソース コードは、このサンプルで最も興味深い点である。このクラスは、GDI を使ってフォントをロードし、各文字をビットマップとして出力する。次に、このビットマップを使って、テクスチャが作成される。

CD3DFont クラスの DrawText 関数が呼び出されると、頂点バッファに、上で作成されたフォント テクスチャを使ってテクスチャ処理されたポリゴンが格納される。ポリゴンは、2D オーバーレイとして描画することもできる。統計情報の出力などには便利である。また、ポリゴンは、3D シーンに完全に統合することもできる。

このサンプルでは、ヘルパー関数などのプログラミング要素から構成される共通の Microsoft® DirectX® コードを使用している。このコードは DirectX SDK のほかのサンプルと共有されている。共通のヘッダーおよびソース コードは、(SDK ルート)\Samples\Multimedia\Common にある。


VertexBlend サンプル

説明

VertexBlend サンプルでは、頂点ブレンディングと呼ばれる手法 (サーフェス スキニングとも呼ばれる) を示す。このサンプルでは、さまざまなスポットで曲がるように作成されたファイル ベースのオブジェクトを表示する。

頂点ブレンディングは、なめらかな結合部や、キャラクタ アニメーションでの肉付けけなどのエフェクトを作成するために使用される。

頂点ブレンディングの一部の機能しかサポートしていないカードもある。頂点ブレンディングの詳細については、Microsoft® DirectX® SDK のマニュアルを参照すること。

パス

ソース :(SDK ルート)\Samples\Multimedia\Direct3D\VertexBlend

実行可能ファイル :(SDK ルート)\Samples\Multimedia\Direct3D\Bin

ユーザーズ ガイド

次の表は実装されているキーを示している。メニュー コマンドを使って同じ操作を行うことができる。

キー | アクション
Enter | シーンを開始および停止する。
Space | シーンを少しずつ進める。
F2 | 新しいレンダリング デバイスまたはディスプレイ モードを選択するようユーザーに指示する。
Alt + Enter | フルスクリーン モードとウィンドウ モードを切り替える。
Esc | アプリケーションを終了する。
Ctrl-V | カスタム頂点シェーダと Direct3D 頂点ブレンディングを切り替える。

プログラミング上の注意

頂点ブレンディングでは、各頂点にブレンドの重みを関連付ける必要がある。複数のワールド トランスフォームが SetTransformState を使って設定され、ブレンドの重みによって、各頂点を配置するときに各ワールド行列にどの程度影響するかを決定する。

このサンプルでは、共通ヘルパー コードを使ってメッシュがロードされる。独自の頂点および独自の FVF がどのように宣言され、メッシュの構築に使用されているかに注意すること。メッシュ オブジェクトについては、SetFVF の呼び出しを参照すること。メッシュ ヘルパー コードを使用しない場合も、この手法は同じである。ブレンドの重みを持つ頂点を格納する頂点バッファを作成し、適切な FVF を使用する。

このサンプルでは、ヘルパー関数などのプログラミング要素から構成される共通の DirectX コードを使用している。このコードは DirectX SDK のほかのサンプルと共有されている。共通のヘッダーおよびソース コードは、(SDK ルート)\Samples\Multimedia\Common にある。


VertexShader サンプル

説明

VertexShader サンプルでは、頂点シェーダを使って実現できるいくつかのエフェクトを示す。頂点シェーダは一連の命令を使用する。この命令は、3D デバイスによって頂点ごとに実行され、興味深い方法で頂点のプロパティ (位置、法線、色、テクスチャ座標など) に影響を与える。

頂点シェーダの一部の機能しかサポートしていないカードもある。頂点シェーダの詳細については、Microsoft® DirectX® SDK のマニュアルを参照すること。

パス

ソース :(SDK ルート)\Samples\Multimedia\Direct3D\VertexShader

実行可能ファイル :(SDK ルート)\Samples\Multimedia\Direct3D\Bin

ユーザーズ ガイド

次の表は実装されているキーを示している。メニュー コマンドを使って同じ操作を行うことができる。

キー | アクション
Enter | シーンを開始および停止する。
Space | シーンを少しずつ進める。
W、S | 前後に移動する。
E、Q | 左右に移動する。
A、Z | 上下に回転する。
矢印キー | 上下左右にスライドする。
F1 | ヘルプまたは使用可能なコマンドを表示する。
F2 | 新しいレンダリング デバイスまたはディスプレイ モードを選択するようユーザーに指示する。
Alt + Enter | フルスクリーン モードとウィンドウ モードを切り替える。
Esc | アプリケーションを終了する。

プログラミング上の注意

頂点シェーダのプログラミングは簡単な作業ではない。詳細については、Microsoft DirectX® SDK のマニュアルを参照すること。

このサンプルでは、ヘルパー関数などのプログラミング要素から構成される共通の DirectX コードを使用している。このコードは DirectX SDK のほかのサンプルと共有されている。共通のヘッダーおよびソース コードは、(SDK ルート)\Samples\Multimedia\Common にある。


VolumeTexture サンプル

説明

VolumeTexture サンプルでは、Microsoft® Direct3D® の新しいボリューム テクスチャの使い方を示す。通常、テクスチャは 2D イメージであると考えられ、幅と高さを持ち、そのテクセルは 2 つの座標 tu と tv で指定される。ボリューム テクスチャはこれを 3D にしたもので、幅、高さ、および奥行きを持ち、3 つの座標 tu、tv、tw で指定される。

ボリューム テクスチャは、寄せ集めのフォグ、爆発などのおもしろいエフェクトに使用できる。

ボリューム テクスチャの一部の機能しかサポートしていないカードもある。ボリューム テクスチャの詳細については、Microsoft DirectX® SDK のマニュアルを参照すること。

パス

ソース :(SDK ルート)\Samples\Multimedia\Direct3D\VolumeTexture

実行可能ファイル :(SDK ルート)\Samples\Multimedia\Direct3D\Bin

ユーザーズ ガイド

次の表は実装されているキーを示している。メニュー コマンドを使って同じ操作を行うことができる。

キー | アクション
Enter | シーンを開始および停止する。
Space | シーンを少しずつ進める。
F2 | 新しいレンダリング デバイスまたはディスプレイ モードを選択するようユーザーに指示する。
Alt + Enter | フルスクリーン モードとウィンドウ モードを切り替える。
Esc | アプリケーションを終了する。

プログラミング上の注意

ボリューム テクスチャは、3D テクスチャよりも使い方が難しい。このサンプルのソース コードでは、頂点の宣言 (第 3 のテクスチャ座標を持つ)、テクスチャの作成 (奥行きのディメンジョンを持つ)、およびテクスチャのロック (これも第 3 のディメンジョンを持つ) に注意すること。3D ラスタライザは、2D テクスチャの場合と同様に、テクセル値を補間する。

このサンプルでは、ヘルパー関数などのプログラミング要素から構成される共通の DirectX コードを使用している。このコードは DirectX SDK のほかのサンプルと共有されている。共通のヘッダーおよびソース コードは、(SDK ルート)\Samples\Multimedia\Common にある。


Water サンプル

説明

Water サンプルでは、シェーダ ファイルに保存されている D3DX 手法の使い方を示す。

このサンプルでは、ウォーター コースティクスを含む、さざなみのエフェクトを使った、建物内の四角い池を示す。

パス

ソース :(SDK ルート)\Samples\Multimedia\Direct3D\Water

実行可能ファイル :(SDK ルート)\Samples\Multimedia\Direct3D\Bin

ユーザーズ ガイド

次の表は実装されているキーを示している。メニュー コマンドを使って同じ操作を行うことができる。

キー | アクション
Enter | シーンを開始および停止する。
Space | シーンを少しずつ進める。
W、S | 前後に移動する。
E、Q | 左右に移動する。
A、Z | 上下に回転する。
矢印キー | 上下左右にスライドする。
D | 水の滴下を開始する。
PageDown | 次の手法を表示する。
PageUp | 前の手法を表示する。
Shift + PageDown | 有効性の確認をせずに、次の手法を表示する。
Shift + PageUp | 有効性の確認をせずに、前の手法を表示する。
F1 | ヘルプまたは使用可能なコマンドを表示する。
F2 | 新しいレンダリング デバイスまたはディスプレイ モードを選択するようユーザーに指示する。
Alt + Enter | フルスクリーン モードとウィンドウ モードを切り替える。
Esc | アプリケーションを終了する。

プログラミング上の注意

このサンプルでは、D3DX シェーダの手法に重点を置いている。

このサンプルでは、ヘルパー関数などのプログラミング要素から構成される共通の Microsoft® DirectX® コードを使用している。このコードは DirectX SDK のほかのサンプルと共有されている。共通のヘッダーおよびソース コードは、(SDK ルート)\Samples\Multimedia\Common にある。


Direct3D C/C++ リファレンス

ここでは、Microsoft® Direct3D® が提供する API 要素のリファレンス情報を記述する。リファレンス情報は次のカテゴリに分類されている。

  • インターフェイス
  • 関数
  • マクロ
  • 頂点シェーダ宣言子マクロ
  • 構造体
  • 列挙型
  • その他の型
  • テクスチャ引数フラグ
  • 柔軟な頂点フォーマット フラグ
  • FOURCC コード
  • 戻り値


インターフェイス

ここでは、Microsoft® Direct3D® が提供する COM インターフェイスのリファレンス情報を記述する。Direct3D では、次のインターフェイスが使用される。

  • IDirect3D8
  • IDirect3DBaseTexture8
  • IDirect3DCubeTexture8
  • IDirect3DDevice8
  • IDirect3DIndexBuffer8
  • IDirect3DResource8
  • IDirect3DSurface8
  • IDirect3DSwapChain8
  • IDirect3DTexture8
  • IDirect3DVertexBuffer8
  • IDirect3DVolume8
  • IDirect3DVolumeTexture8


IDirect3D8

Microsoft® Direct3D® オブジェクトを作成し、オブジェクトの環境をセットアップするには、IDirect3D8 インターフェイスのメソッドを使用する。このインターフェイスには、デバイスの能力を列挙および取得するためのメソッドが含まれる。

IDirect3D8 インターフェイスを取得するには、Direct3DCreate8 関数を呼び出す。

IDirect3D8 インターフェイスのメソッドは、以下のグループにまとめることができる。

作成 | CreateDevice
列挙 | EnumAdapterModes
情報 | GetAdapterCount
 | GetAdapterDisplayMode
 | GetAdapterIdentifier
 | GetAdapterModeCount
 | GetAdapterMonitor
 | GetDeviceCaps
登録 | RegisterSoftwareDevice
検査 | CheckDepthStencilMatch
 | CheckDeviceFormat
 | CheckDeviceMultiSampleType
 | CheckDeviceType

すべての COM インターフェイスと同様、IDirect3D8 インターフェイスは IUnknown インターフェイスのメソッドを継承する。IUnknown インターフェイスは、次の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECT3D8 および PDIRECT3D8 型は、IDirect3D8 インターフェイスへのポインタとして定義される。

typedef struct IDirect3D8 *LPDIRECT3D8, *PDIRECT3D8;

動作環境

ヘッダー : D3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

Direct3DCreate8


IDirect3D8::CheckDepthStencilMatch

深度ステンシル フォーマットが、特定のディスプレイ モードでのレンダリング ターゲット フォーマットと互換性があるかどうかを調べる。

HRESULT CheckDepthStencilMatch(
  UINT Adapter,
  D3DDEVTYPE DeviceType,
  D3DFORMAT AdapterFormat,
  D3DFORMAT RenderTargetFormat,
  D3DFORMAT DepthStencilFormat
);

パラメータ

Adapter
[in] 照会するディスプレイ アダプタを示す序数。D3DADAPTER_DEFAULT は常にプライマリ ディスプレイ アダプタである。
DeviceType
[in] デバイス タイプを識別する D3DDEVTYPE 列挙型のメンバ。
AdapterFormat
[in] アダプタで使用されるディスプレイ モードのフォーマットを識別する、D3DFORMAT 列挙型のメンバ。
RenderTargetFormat
[in] D3DFORMAT 列挙型のメンバ。テストするレンダリング ターゲット サーフェスのフォーマットを指定する。
DepthStencilFormat
[in] D3DFORMAT 列挙型のメンバ。テストする深度ステンシル サーフェスのフォーマットを指定する。

戻り値

深度ステンシル フォーマットが、ディスプレイ モードのターゲット レンダリング フォーマットと互換性がある場合、このメソッドは D3D_OK を返す。

パラメータの 1 つ以上が無効な場合は、D3DERR_INVALIDCALL が返される場合がある。深度ステンシル フォーマットが、ディスプレイ モードのターゲット レンダリング フォーマットと互換性がない場合、このメソッドは D3DERR_NOTAVAILABLE を返す。

注意

このメソッドは、特定の深度フォーマットが特定のレンダリング ターゲット フォーマットでのみ機能するハードウェア レンダリングでアプリケーションが機能できるようにするために用意されている。

次のコードは、CheckDeviceFormat を使用して深度ステンシル フォーマットを検証する方法を示している。

BOOL IsDepthFormatOk( D3DFORMAT DepthFormat, D3DFORMAT AdapterFormat,
                      D3DFORMAT BackBufferFormat ) {
    // 深度フォーマットが存在することを確認する。
    HRESULT hr = pD3D->CheckDeviceFormat( D3DADAPTER_DEFAULT,
                                          D3DDEVTYPE_HAL,
                                          AdapterFormat,
                                          D3DUSAGE_DEPTHSTENCIL,
                                          D3DRTYPE_SURFACE,
                                          DepthFormat);

    if( FAILED( hr ) ) return FALSE;

    // 深度フォーマットに互換性があることを確認する。
    hr = pD3D->CheckDepthStencilMatch( D3DADAPTER_DEFAULT,
                                       D3DDEVTYPE_HAL,
                                       AdapterFormat,
                                       BackBufferFormat,
                                       DepthFormat);
    return SUCCEEDED( hr );
}

上の呼び出しは、DepthFormat が AdapterFormat および BackBufferFormat と組み合わせて使用できない場合、FALSE を返す。

動作環境

ヘッダー : D3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3D8::CheckDeviceFormat

サーフェスのフォーマットが、指定したリソース タイプとして利用できるかどうか、およびこのアダプタを使用するデバイスでテクスチャ、深度ステンシル バッファ、レンダリング ターゲットのいずれか、またはこれら 3 つの組み合わせとして使用できるかどうかを調べる。

HRESULT CheckDeviceFormat(
  UINT Adapter,
  D3DDEVTYPE DeviceType,
  D3DFORMAT AdapterFormat,
  DWORD Usage,
  D3DRESOURCETYPE RType,
  D3DFORMAT CheckFormat
);

パラメータ

Adapter
[in] 照会するディスプレイ アダプタを示す序数。D3DADAPTER_DEFAULT は常にプライマリ ディスプレイ アダプタである。この値がシステムのディスプレイ アダプタの数以上の場合、このメソッドは D3DERR_INVALIDCALL を返す。
DeviceType
[in] デバイス タイプを識別する D3DDEVTYPE 列挙型のメンバ。
AdapterFormat
[in] アダプタで使用されるディスプレイ モードのフォーマットを識別する、D3DFORMAT 列挙型のメンバ。
Usage
[in] CheckFormat のサーフェスに対して要求する使用方法。次のフラグのどちらか一方または両方を指定できる。
D3DUSAGE_DEPTHSTENCIL
深度ステンシル サーフェスとして使用できるサーフェスであることを示す。
D3DUSAGE_RENDERTARGET
レンダリング ターゲットとして使用できるサーフェスであることを示す。RType パラメータの値が明確に特定の用途を示唆している場合、アプリケーションは Usage パラメータを 0 にしておくことができる。
RType
[in] D3DRESOURCETYPE 列挙型のメンバ。調査するフォーマットと共に使用することを要求するリソース タイプを指定する。
CheckFormat
[in] D3DFORMAT 列挙型のメンバ。Usage で指定した方法で使用するサーフェスのフォーマットを示す。

戻り値

指定したフォーマットが、指定したデバイスおよび使用方法と互換性がある場合、このメソッドは D3D_OK を返す。

Adapter の値がシステムのディスプレイ アダプタの数と等しいか、それより大きい場合、または DeviceType がサポートされていないタイプの場合は、D3DERR_INVALIDCALL を返す。指定したデバイスおよび使用方法では認められないフォーマットの場合は、D3DERR_NOTAVAILABLE を返す。

注意

CheckDeviceFormat の一般的な用途は、特定の深度ステンシル サーフェス フォーマットが存在するかどうかを確認することである。列挙処理の詳細については、「デバイスの選択」を参照すること。次のコードは、CheckDeviceFormat を使用して深度ステンシル フォーマットの有無を確認する方法を示している。

BOOL IsDepthFormatExisting( D3DFORMAT DepthFormat, D3DFORMAT AdapterFormat ) {
    HRESULT hr = pD3D->CheckDeviceFormat( D3DADAPTER_DEFAULT,
                                          D3DDEVTYPE_HAL,
                                          AdapterFormat,
                                          D3DUSAGE_DEPTHSTENCIL,
                                          D3DRTYPE_SURFACE,
                                          DepthFormat);

    return SUCCEEDED( hr );
}

上の呼び出しは、システムに DepthFormat が存在しない場合は FALSE を返す。

CheckDeviceFormat のもう 1 つの一般的な用途は、特定のサーフェス フォーマットに存在するテクスチャを、現在のディスプレイ モードでレンダリングできるかどうかを確認することである。次のコードは、CheckDeviceFormat を使用して、テクスチャ フォーマットが特定のバック バッファ フォーマットと互換性があるかどうかを確認する方法を示している。

BOOL IsTextureFormatOk( D3DFORMAT TextureFormat, D3DFORMAT AdapterFormat ) {
    HRESULT hr = pD3D->CheckDeviceFormat( D3DADAPTER_DEFAULT,
                                          D3DDEVTYPE_HAL,
                                          AdapterFormat,
                                          0,
                                          D3DRTYPE_TEXTURE,
                                          TextureFormat);

    return SUCCEEDED( hr );
}

上の呼び出しは、アダプタ サーフェス フォーマットが AdapterFormat であるときに、TextureFormat を使ってテクスチャをレンダリングできない場合、FALSE を返す。

動作環境

ヘッダー : D3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3D8::CheckDeviceMultiSampleType

このデバイスでマルチサンプリング テクニックを利用できるかどうかを調べる。

HRESULT CheckDeviceMultiSampleType(
  UINT Adapter,
  D3DDEVTYPE DeviceType,
  D3DFORMAT SurfaceFormat,
  BOOL Windowed,
  D3DMULTISAMPLE_TYPE MultiSampleType
);

パラメータ

Adapter
[in] 照会するディスプレイ アダプタを示す序数。D3DADAPTER_DEFAULT は常にプライマリ ディスプレイ アダプタである。この値がシステムのディスプレイ アダプタの数以上の場合、このメソッドは FALSE を返す。「注意」を参照すること。
DeviceType
[in] デバイス タイプを識別する D3DDEVTYPE 列挙型のメンバ。
SurfaceFormat
[in] D3DFORMAT 列挙型のメンバ。サーフェスに対して要求するマルチサンプリング タイプのセットを指定する。「注意」を参照すること。
Windowed
[in] ブール値。ウィンドウ マルチサンプリングについて問い合わせるときは TRUE を指定し、フルスクリーン マルチサンプリングについて問い合わせるときは FALSE を指定する。
MultiSampleType
[in] D3DMULTISAMPLE_TYPE 列挙型のメンバ。検査するマルチサンプリング テクニックを識別する。

戻り値

指定したマルチサンプリング方式をデバイスが実行できる場合は、D3D_OK を返す。

Adapter または MultiSampleType パラメータが無効な場合は、D3DERR_INVALIDCALL を返す。照会したマルチサンプリング テクニックをこのデバイスがサポートしていない場合は、D3DERR_NOTAVAILABLE を返す。DeviceType がこのアダプタに該当しない場合は、D3DERR_INVALIDDEVICE を返す。

注意

このメソッドは、レンダリングターゲットおよび深度ステンシル サーフェスの両方で使用する。この 2 つを共に使用する場合、マルチサンプリングされた両方のサーフェスを作成する必要があるからである。

次のコードは、CheckDeviceMultiSampleType を使って、デバイスが特定のマルチサンプリング方式をサポートしていることを確認する方法を示している。

if( SUCCEEDED(pDevice->CheckDeviceMultiSampleType( pCaps->AdapterOrdinal,
                                pCaps->DeviceType, pMode->Format,
                                FALSE, D3DMULTISAMPLE_3_SAMPLES ) ) )
    return S_OK;

上のコードでは、デバイスがフルスクリーン D3DMULTISAMPLE_3_SAMPLES マルチサンプリング方式およびサーフェス フォーマットをサポートしている場合、S_OK を返す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3D8::CheckDeviceType

このアダプタで特定のデバイス タイプを使用して、特定のフォーマットを使ったハードウェア アクセラレーションを期待できるかどうかを確認する。

HRESULT CheckDeviceType(
  UINT Adapter,
  D3DDEVTYPE CheckType,
  D3DFORMAT DisplayFormat,
  D3DFORMAT BackBufferFormat,
  BOOL Windowed
);

パラメータ

Adapter
[in] 列挙するディスプレイ アダプタを示す序数。D3DADAPTER_DEFAULT は常にプライマリ ディスプレイ アダプタである。この値がシステムのディスプレイ アダプタの数以上の場合、このメソッドは D3DERR_INVALIDCALL を返す。
CheckType
[in] D3DDEVTYPE 列挙型のメンバ。検査するデバイス タイプを示す。
DisplayFormat
[in] D3DFORMAT 列挙型のメンバ。デバイス タイプを検査するアダプタ ディスプレイ モードのフォーマットを示す。たとえば、デバイスによっては、ピクセル単位の 16 ビットのモードでのみ動作する。
BackBufferFormat
[in] D3DFORMAT 列挙型のメンバ。テストするバック バッファのフォーマットを示す。
Windowed
[in] デバイス タイプがフルスクリーン モードとウィンドウ モードのいずれで使用されるかを示す値。TRUE を設定した場合、ウィンドウ アプリケーションの照会が実行される。それ以外の場合は、この値に FALSE を設定することが望ましい。

戻り値

そのアダプタでデバイスを使用できる場合は、D3D_OK を返す。

Adapter の値がシステムのディスプレイ アダプタの数と等しいか、それより大きい場合は、D3DERR_INVALIDCALL を返す。CheckType が存在しないデバイスを指定していた場合、このメソッドは D3DERR_INVALIDDEVICE を返す。サーフェス フォーマットがサポートされていないか、指定されたフォーマットでハードウェア アクセラレーションが使用できない場合は、D3DERR_NOTAVAILABLE を返す。

注意

使用できない可能性のある最も重要なデバイス タイプは D3DDEVTYPE_HAL である。D3DDEVTYPE_HAL にはハードウェア アクセラレーションが必要である。アプリケーションでは、CheckDeviceType を使って、必要なハードウェアとドライバがシステムにあるかどうかを確認する必要がある。使用できない可能性のあるもう 1 つのデバイスは D3DDEVTYPE_SW である。このデバイス タイプは、IDirect3D8::RegisterSoftwareDevice を使って登録されたプラグ可能なソフトウェア デバイスを表す。

アプリケーションでは、アルファ チャネルを含む DisplayFormat を指定すべきではない。この場合、呼び出しは失敗する。アルファ チャネルはバック バッファに存在している場合があるが、2 つのディスプレイ フォーマットはほかのすべての面で同じでなければならない。たとえば、DisplayFormat が D3DFMT_X1R5G5B5 である場合、BackBufferFormat の有効な値には D3DFMT_X1R5G5B5 および D3DFMT_A1R5G5B5 は含まれるが、D3DFMT_R5G6B5 は除外される。

次のコードは、CheckDeviceType を使って、特定のデバイス タイプをそのアダプタで使用できるかどうかを確認する方法を示している。

if(SUCCEEDED(pD3Device->CheckDeviceType(D3DADAPTER_DEFAULT,
                                        D3DDEVTYPE_HAL,
                                        DisplayFormat,
                                        BackBufferFormat,
                                        bIsWindowed)))
     return S_OK;

// このアダプタには、このレンダリング ターゲット フォーマットを使用する HAL がない。
// 別のフォーマットを使って再度試みる。

デバイスがデフォルトのアダプタ上で、指定されたサーフェス フォーマットで使用できる場合、上のコードは S_OK を返す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3D8::CreateDevice

ディスプレイ アダプタを表すためのデバイスを作成する。

HRESULT CreateDevice(
  UINT Adapter,
  D3DDEVTYPE DeviceType,
  HWND  hFocusWindow,
  DWORD BehaviorFlags,
  D3DPRESENT_PARAMETERS* pPresentationParameters,
  IDirect3DDevice8** ppReturnedDeviceInterface
);

パラメータ

Adapter
[in] ディスプレイ アダプタを示す序数。D3DADAPTER_DEFAULT は常にプライマリ ディスプレイ アダプタである。
DeviceType
[in] D3DDEVTYPE 列挙型のメンバ。目的のデバイス タイプを示す。目的のデバイス タイプが使用できない場合、このメソッドは失敗する。
hFocusWindow
[in] この Microsoft® Direct3D® デバイスでフォーカスを設定するウィンドウ ハンドル。指定するウィンドウは、フルスクリーンの最上位ウィンドウでなければならない。
BehaviorFlags
[in] Direct3D デバイスの全体的な動作を制御する 1 つ以上のフラグの組み合わせ。
D3DCREATE_FPU_PRESERVE
アプリケーションで倍精度 FPU または FPU 例外有効が必要であることを示す。Direct3D は、呼び出されるたびに FPU の状態を設定する。このフラグを設定すると、Direct3D のパフォーマンスが低下する。
D3DCREATE_HARDWARE_VERTEXPROCESSING
ハードウェア頂点処理を指定する。「注意」を参照すること。
D3DCREATE_MIXED_VERTEXPROCESSING
混合 (ソフトウェアとハードウェア両方) の頂点処理を指定する。「注意」を参照すること。
D3DCREATE_MULTITHREADED
アプリケーションが Direct3D にマルチスレッドでの安全性を要求することを示す。Direct3D はグローバル クリティカル セクションをいっそう頻繁に取得するようになり、パフォーマンスが低下する可能性がある。
D3DCREATE_PUREDEVICE
Direct3D が、ステート ブロックに格納できる内容に対する Get* の呼び出しをサポートしないことを指定する。また、頂点処理のエミュレーション サービスを提供しないことを Direct3D に指示する。これは、デバイスが頂点処理をサポートしていない場合、アプリケーションではトランスフォーム後の頂点しか使用できないことを意味する。
D3DCREATE_SOFTWARE_VERTEXPROCESSING
ソフトウェア頂点処理を指定する。「注意」を参照すること。
pPresentationParameters
[in, out] D3DPRESENT_PARAMETERS 構造体へのポインタ。作成するデバイスのプレゼンテーション パラメータが記述されている。CreateDevice を呼び出すと、D3DPRESENT_PARAMETERS の BackBufferCount メンバの値が変更される場合がある。バック バッファ カウントは、バック バッファの正しい数を反映して変更される。
ppReturnedDeviceInterface
[out, retval] 返される IDirect3DDevice8 インターフェイスへのポインタのアドレス。作成されたデバイスを表している。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY

注意

このメソッドからは、要求したディスプレイ モード (またはウィンドウ) に設定されて、適切なバック バッファが割り当てられた、完全に動作するデバイス インターフェイスが返る。アプリケーションは、必要に応じて深度バッファを作成して設定するだけで、レンダリングを開始できる。

このメソッドは、WM_CREATE の処理中に実行すべきではない。したがって、アプリケーションは、WM_CREATE の処理中に Direct3D にウィンドウ ハンドルを渡してはならない。DirectX 8.0 アプリケーションでは、この呼び出しの実行中 (つまり、この呼び出しが返る前) はアプリケーションにメッセージが送信されることを期待できる。アプリケーションは、このときに Direct3D を呼び出さないための警告を受け取る。また、デバイスの作成、解放、またはリセットの呼び出しは、フォーカス ウィンドウのウィンドウ プロシージャと同じスレッドでのみ行われることに注意すること。

D3DCREATE_HARDWARE_VERTEXPROCESSING、D3DCREATE_MIXED_VERTEXPROCESSING、および D3DCREATE_SOFTWARE_VERTEXPROCESSING は相互に排他的なフラグであり、CreateDevice を呼び出すときは、この頂点処理フラグの少なくとも 1 つを必ず指定しなければならない。

デバイスの一部として作成されたバック バッファは、プレゼンテーション パラメータで D3DPRESENTFLAG_LOCKABLE_BACKBUFFER が指定されている場合にのみロック可能である。マルチサンプル バック バッファおよび深度サーフェスはロックできない。

メソッドの IDirect3DDevice8::Reset、Release、および IDirect3DDevice8::TestCooperativeLevel は、CreateDevice を使用してデバイスを作成した同じスレッドから呼び出す必要がある。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

Direct3DCreate8、IDirect3DDevice8::Reset、D3DDEVICE_CREATION_PARAMETERS


IDirect3D8::EnumAdapterModes

アダプタのディスプレイ モードを列挙する。

HRESULT EnumAdapterModes(
  UINT Adapter,
  UINT Mode,
  D3DDISPLAYMODE* pMode
);

パラメータ

Adapter
[in] 照会するディスプレイ アダプタを示す序数。D3DADAPTER_DEFAULT は常にプライマリ ディスプレイ アダプタである。
Mode
[in] 列挙するモードを示す順序数。D3DCURRENT_DISPLAY_MODE はアダプタの現在のデスクトップ ディスプレイ モードを示す特別な値であり、このメソッドでは指定できない。「注意」を参照すること。
pMode
[in, out] D3DDISPLAYMODE 構造体へのポインタ。指定したモードを記述する情報が格納される。エラーの場合はゼロが設定される。

戻り値

成功した場合は、D3D_OK を返す。

Adapter または Mode が範囲外の値の場合、または pMode が無効な値の場合は、D3DERR_INVALIDCALL を返す。

注意

一部のディスプレイ ドライバには、モード数を大幅に増加させるリフレッシュ レート情報を含んでいる。古いドライバでは、D3DADAPTER_DEFAULT のリフレッシュ レートだけが列挙される。Direct3D では、モニタの能力に応じて、ディスプレイ モードおよびリフレッシュ レートを制限しようとしているが、列挙されたモードがシステムのモニタでサポートされていない可能性がある。Microsoft® Windows® のディスプレイ コントロール パネル ユーティリティで使用されるものと同様のディスプレイ モード テスト ユーティリティを実装できる。

IDirect3D8::GetAdapterModeCount を使って、システムでサポートされているモードの総数を調べる。Mode パラメータの有効な値は、0 からモードの総数 - 1 までの範囲である。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3D8::GetAdapterModeCount


IDirect3D8::GetAdapterCount

システムにあるアダプタの数を返す。

UINT GetAdapterCount();

パラメータ

なし。

戻り値

この IDirect3D8 インターフェイスがインスタンス化された時点でシステムに存在しているアダプタの数を示す UINT の値。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3D8::GetAdapterIdentifier


IDirect3D8::GetAdapterDisplayMode

アダプタの現在のディスプレイ モードを取得する。

HRESULT GetAdapterDisplayMode(
  UINT Adapter,
  D3DDISPLAYMODE* pMode
);

パラメータ

Adapter
[in] 照会するディスプレイ アダプタを示す序数。D3DADAPTER_DEFAULT は常にプライマリ ディスプレイ アダプタである。
pMode
[in, out] D3DDISPLAYMODE 構造体へのポインタ。アダプタの現在のモードを記述する情報が格納される。

戻り値

成功した場合は、D3D_OK を返す。

Adapter が範囲外の値の場合、または pMode が無効な値の場合は、D3DERR_INVALIDCALL を返す。

注意

アダプタを表すデバイスが特定のモードにリセットされている場合があるが、これはアダプタの実際のモードではない可能性があることに注意する。特定のモードへのデバイス リセットが失われていて、アダプタの現在のモードを判定できない可能性がある。この関数からは、デバイスに対して要求されている特定のモードではなく、アダプタのモードが返る。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3D8::GetAdapterIdentifier

IDirect3D8 インターフェイスがインスタンス化された時点でシステムに存在していた物理的なディスプレイ アダプタを記述する。

HRESULT GetAdapterIdentifier(
  UINT Adapter,
  DWORD Flags,
  D3DADAPTER_IDENTIFIER8* pIdentifier
);

パラメータ

Adapter
[in] ディスプレイ アダプタを示す序数。D3DADAPTER_DEFAULT は常にプライマリ ディスプレイ アダプタである。このパラメータの最小値は 0 で、最大値は IDirect3D8::GetAdapterCount で返される値から 1 を引いた値である。
Flags
[in] 通常はゼロに設定するパラメータ。ただし、次の値を指定することもできる。
D3DENUM_NO_WHQL_LEVEL
D3DADAPTER_IDENTIFIER8 構造体の WHQLLevel メンバを強制的にゼロにする。これにより、WHQL の認証期日に対する情報が返らなくなる。このフラグを設定すると、WHQL の認証期日を確認する際に発生する 1、2 秒の遅れを避けることができる。
pIdentifier
[in, out] D3DADAPTER_IDENTIFIER8 構造体へのポインタ。指定したアダプタを記述する情報が格納される。システムにあるアダプタの数以上の値を Adapter で指定すると、この構造体にはゼロが設定される。

戻り値

成功した場合は、D3D_OK を返す。

Adapter の値が範囲外の場合、Flags が認識不可能なパラメータの場合、または pIdentifier が NULL または書き込み不可能なメモリを指している場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3D8::GetAdapterCount


IDirect3D8::GetAdapterModeCount

アダプタで利用可能なディスプレイ モードの数を返す。

UINT GetAdapterModeCount(
  UINT Adapter
);

パラメータ

Adapter
[in] ディスプレイ アダプタを示す序数。D3DADAPTER_DEFAULT は常にプライマリ ディスプレイ アダプタである。

戻り値

Adapter の値がシステム上のアダプタの数以上の場合は、このアダプタのディスプレイ モードの数、またはゼロを返す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3D8::EnumAdapterModes


IDirect3D8::GetAdapterMonitor

Microsoft® Direct3D® オブジェクトに関連付けられているモニタのハンドルを返す。

HMONITOR GetAdapterMonitor(
  UINT Adapter
);

パラメータ

Adapter
[in] ディスプレイ アダプタを示す序数。D3DADAPTER_DEFAULT は常にプライマリ ディスプレイ アダプタである。

戻り値

Direct3D オブジェクトに関連付けられたモニタのハンドル。

注意

次のコード例は、指定されたデバイスに関連付けられたモニタのハンドルを取得する方法を示している。この例のように、IDirect3DDevice8::GetDirect3D を使って、デバイスから Direct3D 列挙型を返し、IDirect3DDevice8::GetCreationParameters を使って、Adapter の値を取得する。

    if( FAILED( pDevice->GetCreationParameters(  &Parameters ) ) )
        return E_INVALIDCALL;

    if( FAILED( pDevice->GetDirect3D(&pD3D) ) )
        return E_INVALIDCALL;

    hMonitor = pD3D->GetAdapterMonitor(Parameters.AdapterOrdinal);

    pD3D->Release();

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::GetCreationParameters、IDirect3DDevice8::GetDirect3D


IDirect3D8::GetDeviceCaps

デバイスについてのデバイス固有の情報を取得する。

HRESULT GetDeviceCaps(
  UINT Adapter,
  D3DDEVTYPE DeviceType,
  D3DCAPS8* pCaps
);

パラメータ

Adapter
[in] ディスプレイ アダプタを示す序数。D3DADAPTER_DEFAULT は常にプライマリ ディスプレイ アダプタである。
DeviceType
[in] D3DDEVTYPE 列挙型のメンバ。デバイスのタイプを示す。
pCaps
[out] D3DCAPS8 構造体へのポインタ。デバイスの能力を記述した情報が格納される。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DERR_INVALIDDEVICE
D3DERR_OUTOFVIDEOMEMORY

注意

アプリケーションで、Microsoft® Direct3D® デバイス オブジェクト全体における頂点処理能力の持続性を仮定してはならない。物理デバイスが公開する特定の能力は、IDirect3D8::CreateDevice に指定されるパラメータによって異なる。たとえば、このような能力は、ハードウェア頂点処理を有効にして Direct3D デバイス オブジェクトを作成する前後で、異なる頂点処理能力を提供できる。詳細については、「D3DCAPS8」を参照すること。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3D8::RegisterSoftwareDevice

プラグ可能なソフトウェア デバイスをMicrosoft® Direct3D® に登録する。

HRESULT RegisterSoftwareDevice(
  void* pInitializeFunction
);

パラメータ

pInitializeFunction
[in] 登録するソフトウェア デバイスの初期化関数へのポインタ。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

注意

Direct3D に対するソフトウェア ラスタ化は、プラグ可能なソフトウェア デバイスによって提供される。これにより、アプリケーションは、Direct3D インターフェイスを通してさまざまなソフトウェア ラスタライザにアクセスできる。ソフトウェア デバイスは、アプリケーションによってロードされて、Direct3D オブジェクトに登録される。この時点で、ソフトウェア デバイスを使ってレンダリングを実行する Direct3DDevice オブジェクトを作成できる。

Direct3D ソフトウェア デバイスは、ハードウェア デバイス ドライバ インタフェース (DDI) に類似するインターフェイスを介して Direct3D と通信する。

Direct3D DDK には、プラグ可能なソフトウェア デバイスを開発するためのドキュメントとヘッダーが用意されている。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3DBaseTexture8

キューブ テクスチャ、ボリューム テクスチャなどのテクスチャ リソースを操作するには、IDirect3DBaseTexture8 インターフェイスのメソッドを使用する。

デバイスの特定のステージに割り当てられている IDirect3DBaseTexture8 インターフェイスを取得するには、IDirect3DDevice8::GetTexture メソッドを呼び出す。

IDirect3DBaseTexture8 インターフェイスは、次のようなグループに分類できる IDirect3DResource8 メソッドを継承する。

デバイス | GetDevice
情報 | GetType
プライベート サーフェス データ | FreePrivateData
 | GetPrivateData
 | SetPrivateData
リソース管理 | GetPriority
 | PreLoad
 | SetPriority

IDirect3DBaseTexture8 インターフェイスのメソッドは、以下のグループにまとめることができる。

詳細 | GetLOD
 | SetLOD
情報 | GetLevelCount

すべての COM インターフェイスと同様、IDirect3DBaseTexture8 インターフェイスは IUnknown インターフェイスのメソッドを継承する。IUnknown インターフェイスは、次の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECT3DBASETEXTURE8 および PDIRECT3DBASETEXTURE8 型は、IDirect3DBaseTexture8 インターフェイスへのポインタとして定義される。

typedef struct IDirect3DBaseTexture8 *LPDIRECT3DBASETEXTURE8, *PDIRECT3DBASETEXTURE8;

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3DBaseTexture8::GetLevelCount

マルチレベル テクスチャのテクスチャ レベルの数を返す。

DWORD GetLevelCount();

パラメータ

なし。

戻り値

マルチレベル テクスチャのテクスチャ レベルの数を示す DWORD の値。

対象

このメソッドは、IDirect3DBaseTexture8 を継承する次のインターフェイスに適用される。

  • IDirect3DCubeTexture8
  • IDirect3DTexture8
  • IDirect3DVolumeTexture8

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3DBaseTexture8::GetLOD

管理下のテクスチャに設定されている最大詳細レベル (LOD) に制限された値を返す。

DWORD GetLOD();

パラメータ

なし。

戻り値

最大 LOD 値に制限された DWORD 値 (レベルの総数から 1 を引いた値)。

対象

このメソッドは、IDirect3DBaseTexture8 を継承する次のインターフェイスに適用される。

  • IDirect3DCubeTexture8
  • IDirect3DTexture8
  • IDirect3DVolumeTexture8

注意

GetLOD を使って、管理下のテクスチャの LOD 制御を行う。このメソッドは、非管理下のテクスチャに対して 0 を返す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DBaseTexture8::SetLOD


IDirect3DBaseTexture8::SetLOD

管理下のテクスチャに最大詳細レベル (LOD) を設定する。

DWORD SetLOD(
  DWORD LODNew
);

パラメータ

LODNew
[in] ミップマップ チェーンに設定する最大 LOD の値。

戻り値

最大 LOD 値に制限された DWORD 値 (レベルの総数から 1 を引いた値)。以降のこのメソッドの呼び出しでは、以前に設定された LOD 値ではなく、制限された値が返される。

対象

このメソッドは、IDirect3DBaseTexture8 を継承する次のインターフェイスに適用される。

  • IDirect3DCubeTexture8
  • IDirect3DTexture8
  • IDirect3DVolumeTexture8

注意

SetLOD は、管理下のテクスチャの LOD 制御のために使われる。このメソッドは、非管理下のテクスチャに対して 0 を返す。

SetLOD は、ローカル ビデオ メモリにロードするチェーンの中で最も詳細なミップマップを Microsoft® Direct3D® テクスチャ マネージャに通知する。たとえば、5 レベルのミップマップ チェーンにおいて LODNew で 2 を指定すると、テクスチャ マネージャはある時点でレベル 2 から 4 のミップマップだけをローカル ビデオ メモリにロードする。

さらに具体的に説明すると、256 × 256 のディメンジョンでテクスチャが作成されている場合、最大詳細レベルを 0 に設定すると利用可能な最大のミップマップが 256 × 256 であることを示し、最大詳細レベルを 1 に設定すると利用可能な最大ミップマップが 128 × 128 であることを示す。このようにして、チェーンの最大ミップ レベル (最も小さいテクスチャ サイズ) まで同様に示される。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DBaseTexture8::GetLOD


IDirect3DCubeTexture8

キューブ テクスチャ リソースを操作するには、IDirect3DCubeTexture8 インターフェイスのメソッドを使用する。

IDirect3DCubeTexture8 インターフェイスを取得するには、IDirect3DDevice8::CreateCubeTexture メソッドを呼び出す。

IDirect3DCubeTexture8 インターフェイスは、次のようなグループに分類できる IDirect3DResource8 メソッドを継承する。

デバイス | GetDevice
情報 | GetType
プライベート サーフェス データ | FreePrivateData
 | GetPrivateData
 | SetPrivateData
リソース管理 | GetPriority
 | PreLoad
 | SetPriority

IDirect3DCubeTexture8 インターフェイスは、次のようなグループに分類できる IDirect3DBaseTexture8 メソッドを継承する。

詳細 | GetLOD
 | SetLOD
情報 | GetLevelCount

IDirect3DCubeTexture8 インターフェイスのメソッドは、以下のグループにまとめることができる。

情報 | GetLevelDesc
サーフェスのロック | LockRect
 | UnlockRect
その他 | AddDirtyRect
 | GetCubeMapSurface

すべての COM インターフェイスと同様、IDirect3DCubeTexture8 インターフェイスは IUnknown インターフェイスのメソッドを継承する。IUnknown インターフェイスは、次の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECT3DCUBETEXTURE8 および PDIRECT3DCUBETEXTURE8 型は、IDirect3DCubeTexture8 インターフェイスへのポインタとして定義される。

typedef struct IDirect3DCubeTexture8 *LPDIRECT3DCUBETEXTURE8, *PDIRECT3DCUBETEXTURE8;

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::CreateCubeTexture


IDirect3DCubeTexture8::AddDirtyRect

キューブ テクスチャ リソースにダーティー領域を追加する。

HRESULT AddDirtyRect(
  D3DCUBEMAP_FACES FaceType,
  CONST RECT* pDirtyRect
);

パラメータ

FaceType
[in] D3DCUBEMAP_FACES 列挙型のメンバ。キューブ マップのサーフェスを指定する。
pDirtyRect
[in] RECT 構造体へのポインタ。ダーティー領域を指定する。NULL を指定すると、キューブ テクスチャ全体を覆うようにダーティー領域が拡大する。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

パフォーマンスの理由によって、ダーティーな範囲はテクスチャのレベル ゼロに対して記録されるのみである。サブレベルについては、対応する (スケールされた) 矩形またはボックスもダーティーであると仮定される。D3DLOCK_NO_DIRTY_UPDATE または D3DLOCK_READONLY なしで LockRect か LockBox が呼び出されたとき、ダーティーな範囲は自動的に記録される。また CopyRects 呼び出しの宛先サーフェスはダーティーとしてマークされる。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DCubeTexture8::GetLevelDesc、IDirect3DCubeTexture8::LockRect、IDirect3DCubeTexture8::UnlockRect


IDirect3DCubeTexture8::GetCubeMapSurface

キューブ テクスチャ マップのサーフェスを取得する。

HRESULT GetCubeMapSurface(
  D3DCUBEMAP_FACES FaceType,
  UINT Level,
  IDirect3DSurface8** ppCubeMapSurface
);

パラメータ

FaceType
[in] キューブ マップ サーフェスを識別する D3DCUBEMAP_FACES 列挙型のメンバ。
Level
[in] ミップマップ キューブ テクスチャのレベルを指定する。
ppCubeMapSurface
[out, retval] IDirect3DSurface8 インターフェイスへのポインタのアドレス。返されたキューブ テクスチャ マップのサーフェスを表している。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3DCubeTexture8::GetLevelDesc

指定したキューブ テクスチャ レベルの記述を取得する。

HRESULT GetLevelDesc(
  UINT Level,
  D3DSURFACE_DESC* pDesc
);

パラメータ

Level
[in] ミップマップ キューブ テクスチャのレベルを指定する。
pDesc
[out] 指定したキューブ テクスチャ レベルを記述している D3DSURFACE_DESC 構造体へのポインタ。

戻り値

成功した場合は、D3D_OK を返す。

引数の 1 つ以上が無効な場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DCubeTexture8::AddDirtyRect、IDirect3DCubeTexture8::LockRect、IDirect3DCubeTexture8::UnlockRect


IDirect3DCubeTexture8::LockRect

キューブ テクスチャ リソース上の矩形をロックする。

HRESULT LockRect(
  D3DCUBEMAP_FACES FaceType,
  UINT Level,
  D3DLOCKED_RECT* pLockedRect,
  CONST RECT* pRect,
  DWORD Flags
);

パラメータ

FaceType
[in] キューブ マップ サーフェスを識別する D3DCUBEMAP_FACES 列挙型のメンバ。
Level
[in] ミップマップ キューブ テクスチャのレベルを指定する。
pLockedRect
[out] ロックする領域を記述する D3DLOCKED_RECT 構造体へのポインタ。
pRect
[in] ロックする矩形へのポインタ。RECT 構造体へのポインタによって指定される。このパラメータに NULL を指定すると、キューブ テクスチャ全体を覆うようにダーティー領域が拡大する。
Flags
[in] 実行するロックのタイプを記述する、0 個以上のロッキング フラグの組み合わせ。
D3DLOCK_NO_DIRTY_UPDATE
デフォルトでは、リソースのロックはダーティー領域をそのリソースに追加する。このフラグは、リソースのダーティー状態への変更を防ぐ。ロック処理の間に変更される実際の領域群についての追加情報をアプリーションが持っていて、その情報を IDirect3DCubeTexture8::AddDirtyRect に渡すことができる場合は、アプリケーションでこのフラグを使用しなければならない。
D3DLOCK_NOSYSLOCK
ビデオ メモリ ロックのデフォルトの動作では、システム全体のクリティカル セクションが確保されて、ロックの期間中はディスプレイ モードが変化しないことが保証される。このフラグは、システムワイドなクリティカル セクションがロックの間保持されないようにする。

ロック処理で使用されるメモリは若干増えるが、システムは、マウス カーソルの移動といったほかの動作を実行できる。このフラグは、ソフトウェア レンダリングのバックバッファのロックのように、ロックが長時間に及び、システムの応答性に悪影響を与えてしまうようなロックに対して有効である。

D3DLOCK_READONLY
アプリケーションはバッファに書き込みを行わない。これによって、ネイティブでないフォーマットで格納されたリソースが、アンロック時に再圧縮手順を保存できる。

戻り値

成功した場合は、D3D_OK を返す。

引数の 1 つ以上が無効な場合は、D3DERR_INVALIDCALL を返す。

注意

POOL_DEFAULT を指定して作成されたキューブ テクスチャはロックできない。

深度ステンシル サーフェスのロック可能なフォーマットは、D3DFMT_D16_LOCKABLE だけである。

マルチサンプル バック バッファはロックできない。

パフォーマンスの理由によって、ダーティーな範囲はテクスチャのレベルゼロに対して記録されるのみである。D3DLOCK_NO_DIRTY_UPDATE または D3DLOCK_READONLY なしで LockRect か LockBox が呼び出されたとき、ダーティーな範囲は自動的に記録される。詳細については、「IDirect3DDevice8::UpdateTexture」を参照すること。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DCubeTexture8::AddDirtyRect、IDirect3DCubeTexture8::GetLevelDesc、IDirect3DCubeTexture8::UnlockRect


IDirect3DCubeTexture8::UnlockRect

キューブ テクスチャ リソース上の矩形をアンロックする。

HRESULT UnlockRect(
  D3DCUBEMAP_FACES FaceType,
  UINT Level
);

パラメータ

FaceType
[in] キューブ マップ サーフェスを識別する D3DCUBEMAP_FACES 列挙型のメンバ。
Level
[in] ミップマップ キューブ テクスチャのレベルを指定する。

戻り値

成功した場合は、D3D_OK を返す。

引数の 1 つ以上が無効な場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DCubeTexture8::AddDirtyRect、IDirect3DCubeTexture8::LockRect


IDirect3DDevice8

DrawPrimitive ベースのレンダリング、リソースの作成、システムレベル変数の処理、ガンマ ランプ レベルの調整、パレットの処理、およびシェーダの作成を行うには、IDirect3DDevice8 インターフェイスのメソッドを使用する。

IDirect3DDevice8 インターフェイスを取得するには、IDirect3D8::CreateDevice メソッドを呼び出す。

IDirect3DDevice8 インターフェイスのメソッドは、以下のグループにまとめることができる。

カーソル | SetCursorPosition
 | SetCursorProperties
 | ShowCursor
作成 | CreateAdditionalSwapChain
 | CreateCubeTexture
 | CreateDepthStencilSurface
 | CreateImageSurface
 | CreateIndexBuffer
 | CreateRenderTarget
 | CreateTexture
 | CreateVertexBuffer
 | CreateVolumeTexture
デバイス ステート | ApplyStateBlock
 | BeginStateBlock
 | CaptureStateBlock
 | CreateStateBlock
 | DeleteStateBlock
 | EndStateBlock
 | GetClipStatus
 | GetDisplayMode
 | GetRenderState
 | GetRenderTarget
 | GetTransform
 | SetClipStatus
 | SetRenderState
 | SetRenderTarget
 | SetTransform
ガンマ ランプ | GetGammaRamp
 | SetGammaRamp
高次プリミティブ | DeletePatch
 | DrawRectPatch
 | DrawTriPatch
インデックス データ | GetIndices
 | SetIndices
情報 | GetAvailableTextureMem
 | GetCreationParameters
 | GetDeviceCaps
 | GetDirect3D
 | GetInfo
 | GetRasterStatus
ライティングとマテリアル | GetLight
 | GetLightEnable
 | GetMaterial
 | LightEnable
 | SetLight
 | SetMaterial
その他 | CopyRects
 | GetFrontBuffer
 | MultiplyTransform
 | ProcessVertices
 | ResourceManagerDiscardBytes
 | TestCooperativeLevel
パレット | GetCurrentTexturePalette
 | GetPaletteEntries
 | SetCurrentTexturePalette
 | SetPaletteEntries
ピクセル シェーダ | CreatePixelShader
 | DeletePixelShader
 | GetPixelShader
 | GetPixelShaderConstant
 | GetPixelShaderFunction
 | SetPixelShader
 | SetPixelShaderConstant
プレゼンテーション | Present
 | Reset
レンダリング | DrawIndexedPrimitive
 | DrawIndexedPrimitiveUP
 | DrawPrimitive
 | DrawPrimitiveUP
 | DrawRectPatch
 | DrawTriPatch
シーン | BeginScene
 | EndScene
ストリーム データ | GetStreamSource
 | SetStreamSource
サーフェス | GetBackBuffer
 | GetDepthStencilSurface
テクスチャ | GetTexture
 | GetTextureStageState
 | SetTexture
 | SetTextureStageState
 | UpdateTexture
 | ValidateDevice
ユーザー定義クリップ面 | GetClipPlane
 | SetClipPlane
ビューポート | Clear
 | GetViewport
 | SetViewport
頂点シェーダ | CreateVertexShader
 | DeleteVertexShader
 | GetVertexShader
 | GetVertexShaderConstant
 | GetVertexShaderDeclaration
 | GetVertexShaderFunction
 | SetVertexShader
 | SetVertexShaderConstant

すべての COM インターフェイスと同様、IDirect3DDevice8 インターフェイスは IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは、次の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECT3DDEVICE8 および PDIRECT3DDEVICE8 型は、IDirect3DDevice8 インターフェイスへのポインタとして定義される。

typedef struct IDirect3DDevice8 *LPDIRECT3DDEVICE8, *PDIRECT3DDEVICE8;

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3D8::CreateDevice


IDirect3DDevice8::ApplyStateBlock

既存のデバイス ステート ブロックをレンダリング デバイスに適用する。

HRESULT ApplyStateBlock(
  DWORD Token
);

パラメータ

Token
[in] 実行するデバイス ステート ブロックへのハンドル。これは前に呼び出した IDirect3DDevice8::EndStateBlock メソッドによって返される。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

値 0xFFFFFFFF は、無効なステート ブロック ハンドルである。

アプリケーションで別のブロックを記録しているときに、デバイス ステート ブロックを適用することはできない。

レンダリング デバイスのステートに影響するすべての処理と同様、ステート ブロックの適用は、シーンのレンダリング中、つまり IDirect3DDevice8::BeginScene メソッドを呼び出してから IDirect3DDevice8::EndScene を呼び出すまでの間に行うことを推奨する。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::BeginStateBlock、IDirect3DDevice8::EndStateBlock、IDirect3DDevice8::CaptureStateBlock、IDirect3DDevice8::CreateStateBlock、IDirect3DDevice8::DeleteStateBlock


IDirect3DDevice8::BeginScene

シーンを開始する。

HRESULT BeginScene();

パラメータ

なし。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

アプリケーションでは、レンダリングを実行する前には必ずこのメソッドを呼び出し、レンダリングの終了時および再度 BeginScene を呼び出す前には、必ず IDirect3DDevice8::EndScene を呼び出す。

BeginScene メソッドが失敗すると、デバイスはシーンを開始できないため、IDirect3DDevice8::EndScene メソッドを呼び出す必要はない。実際、その前の BeginScene の呼び出しが失敗すると、EndScene の呼び出しも失敗する。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::EndScene


IDirect3DDevice8::BeginStateBlock

Microsoft® Direct3D® にデバイス ステート ブロックの記録を開始するように知らせる。

HRESULT BeginStateBlock();

パラメータ

なし。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

注意

アプリケーションでは、このメソッドを呼び出す前に IDirect3DDevice8::ValidateDevice メソッドを呼び出して、記録するすべてのステートが有効であることを確認できる。

BeginStateBlock を呼び出してから IDirect3DDevice8::EndStateBlock を呼び出すまでにステート ブロックに記録できるメソッドは、次のとおりである。

  • IDirect3DDevice8::LightEnable
  • IDirect3DDevice8::SetClipPlane
  • IDirect3DDevice8::SetIndices
  • IDirect3DDevice8::SetLight
  • IDirect3DDevice8::SetMaterial
  • IDirect3DDevice8::SetPixelShader
  • IDirect3DDevice8::SetPixelShaderConstant
  • IDirect3DDevice8::SetRenderState
  • IDirect3DDevice8::SetStreamSource
  • IDirect3DDevice8::SetTexture
  • IDirect3DDevice8::SetTextureStageState
  • IDirect3DDevice8::SetTransform
  • IDirect3DDevice8::SetViewport
  • IDirect3DDevice8::SetVertexShader
  • IDirect3DDevice8::SetVertexShaderConstant

ステート ブロック内では、ステート変更の順序は保証されない。ステート ブロックで同じステートが複数回指定された場合、使用されるのは最後の値のみである。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::ApplyStateBlock、IDirect3DDevice8::EndStateBlock、IDirect3DDevice8::CaptureStateBlock、IDirect3DDevice8::CreateStateBlock、IDirect3DDevice8::DeleteStateBlock


IDirect3DDevice8::CaptureStateBlock

既存のステート ブロック内の値を、デバイスに設定されている値に更新する。

HRESULT CaptureStateBlock(
  DWORD Token
);

パラメータ

Token
[in] デバイス ステートを取り込むステート ブロックへのハンドル。

戻り値

成功した場合は、D3D_OK を返す。

ステート ブロックが現在記録中である場合、メソッドは失敗し、D3DERR_INVALIDCALL を返す。

注意

値 0xFFFFFFFF は、無効なステート ブロック ハンドルである。

このメソッドは、既存のステート ブロックに含まれるステートの更新後の値を取り込む。デバイス全体のステートは取り込まない。

CaptureStateBlock は、ステートブロックの作成後に、明示的または非明示的に作成されたライトの情報を取り込まない。たとえば、現在のステートを D3DSBT_ALL 型のステートブロックに取り込んでも、取り込み後に作成されたライトの情報は保存されない。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::ApplyStateBlock、IDirect3DDevice8::BeginStateBlock、IDirect3DDevice8::CreateStateBlock、IDirect3DDevice8::EndStateBlock、IDirect3DDevice8::DeleteStateBlock


IDirect3DDevice8::Clear

ビューポートまたはビューポート内の矩形セットを指定した RGBA 色にクリアし、深度バッファをクリアし、ステンシル バッファを削除する。

HRESULT Clear(
  DWORD Count,
  CONST D3DRECT* pRects,
  DWORD Flags,
  D3DCOLOR Color,
  float Z,
  DWORD Stencil
);

パラメータ

Count
[in] pRects の配列にある矩形の数。pRects を NULL に設定する場合は、このパラメータを 0 に設定する。
pRects
[in] クリアする矩形を記述する D3DRECT 構造体の配列へのポインタ。矩形をレンダリング ターゲットの寸法に設定すると、サーフェス全体がクリアされる。各矩形は、レンダリング ターゲット サーフェス上の点に対応するスクリーン座標を使用する。座標はビューポートの矩形の境界でクリップされる。このパラメータを NULL に設定すると、ビューポート矩形全体をクリアすることになる。
Flags
[in] クリアするサーフェスを示すフラグ。このパラメータでは、次のフラグの任意の組み合わせを指定できるが、少なくとも 1 つのフラグを使わなければならない。
D3DCLEAR_STENCIL
ステンシル バッファをクリアして、Stencil パラメータの値にする。
D3DCLEAR_TARGET
レンダリング ターゲットをクリアして、Color パラメータの色にする。
D3DCLEAR_ZBUFFER
深度バッファをクリアして、Z パラメータの値にする。
Color
[in] レンダリング ターゲット サーフェスをクリアする 32 ビット ARGB カラー値。
Z
[in] このメソッドが深度バッファに保存する新しい z 値。このパラメータには 0.0 から 1.0 までの値を使用できる (Z ベースまたは W ベースの深度バッファの場合)。0.0 はビューアに最も近い距離、1.0 は最も遠い距離を表す。
Stencil
[in] 各ステンシル バッファのエントリに保存する整数値。このパラメータには 0 から 2n-1 までの値を使用できる。n はステンシル バッファのビット深度。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

このメソッドは、レンダリング ターゲットに深度バッファがアタッチされていないときに D3DCLEAR_ZBUFFER または D3DCLEAR_STENCIL フラグを指定すると失敗する。同様に、深度バッファ フォーマットにステンシル バッファ情報が含まれていない場合、D3DCLEAR_STENCIL フラグを指定すると、このメソッドは失敗する。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3DDevice8::CopyRects

あるサーフェスから別のサーフェスに、ピクセルの矩形サブセットをコピーする。

HRESULT CopyRects(
  IDirect3DSurface8* pSourceSurface,
  CONST RECT* pSourceRectsArray,
  UINT cRects,
  IDirect3DSurface8* pDestinationSurface,
  CONST POINT* pDestPointsArray
);

パラメータ

pSourceSurface
[in] 転送元サーフェスを表す IDirect3DSurface8 インターフェイスへのポインタ。このパラメータは、pDestinationSurface と異なるサーフェスを示していなければならない。
pSourceRectsArray
[in] RECT 構造体の配列へのポインタ。転送する矩形を表している。各矩形は転送先のサーフェスに転送されて、矩形の左上角は pDestPointsArray の対応する要素で示されている位置になる。このパラメータに NULL を指定すると、サーフェス全体がコピーされる。
cRects
[in] pSourceRectsArray に格納されている RECT 構造体の数。
pDestinationSurface
[in] 転送先サーフェスを表す IDirect3DSurface8 インターフェイスへのポインタ。このパラメータは、pSourceSurface と異なるサーフェスを示していなければならない。
pDestPointsArray
[in] POINT 構造体の配列へのポインタ。pSourceRectsArray に格納されている各矩形の左上角の位置を示す。このパラメータが NULL の場合、RECT の矩形は転送元の矩形と同じオフセット (左上角の位置が同じ) にコピーされる。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

このメソッドは、拡大、カラー キー、アルファ ブレンド、フォーマット変換、および転送元または転送先矩形のいずれかのクリッピングをサポートしていない。すべての転送元矩形および対応する転送先矩形が、それぞれ転送元および転送先サーフェス内に完全に含まれていない場合には、このメソッドが失敗することに注意する。2 つのサーフェスのフォーマットは一致していなければならないが、サイズは異なっていてもかまわない。

サーフェスのフォーマットが深度ステンシル フォーマットの場合、このメソッドは適用できない。

POINT 構造体では、左上角の x 座標と y 座標を定義する。POINT の詳細については、Microsoft® Platform Software Development Kit (SDK) を参照すること。

宛先サーフェスがテクスチャのレベルゼロなら、それはダーティーとマークされる。詳細については、「IDirect3DDevice8::UpdateTexture」および「IDirect3DTexture8::AddDirtyRect」を参照すること。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3DDevice8::CreateAdditionalSwapChain

複数のビューをレンダリングするための追加スワップ チェーンを作成する。

HRESULT CreateAdditionalSwapChain(
  D3DPRESENT_PARAMETERS* pPresentationParameters,
  IDirect3DSwapChain8** ppSwapChain
);

パラメータ

pPresentationParameters
[in] 新しいスワップ チェーンのプレゼンテーション パラメータを表す D3DPRESENT_PARAMETERS 構造体へのポインタ。この値は NULL にできない。
ppSwapChain
[out, retval] 追加スワップ チェーンを表す IDirect3DSwapChain8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY
E_OUTOFMEMORY

注意

Microsoft® Direct3D® for Microsoft DirectX 8.0® はデバイスのプロパティとして 1 つのスワップ チェーンを持っているため、各デバイスに対して、常に少なくても 1 つのスワップ チェーン (非明示的なスワップ チェーン) が存在する。

どのようなデバイスでも、サポートできるフルスクリーン スワップ チェーンは 1 つだけである。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

ウィンドウ モードのマルチビュー


IDirect3DDevice8::CreateCubeTexture

キューブ テクスチャ リソースを作成する。

HRESULT CreateCubeTexture(
  UINT EdgeLength,
  UINT Levels,
  DWORD Usage,
  D3DFORMAT Format,
  D3DPOOL Pool,
  IDirect3DCubeTexture8** ppCubeTexture
);

パラメータ

EdgeLength
[in] キューブ テクスチャのすべての最高次レベル サーフェスのエッジのサイズ。ミップマップ レベルが下のピクセル ディメンジョンは、1 つ上のレベルのピクセル ディメンジョンを (単純に) 1/2 した値である。それぞれの大きさは、1 ピクセルのサイズに収められる。したがって、2 で除算した結果が 0 の場合、代わりに 1 が使用される。
Levels
[in] キューブ テクスチャの各サーフェスのレベルの数。0 を指定すると、Microsoft® Direct3D® は、ミップマップ化キューブ テクスチャをサポートするハードウェアに対して、各面の 1 × 1 ピクセルまでのすべてのキューブ テクスチャ サブレベルを生成する。その他の値を指定した場合は、1 レベルを生成する。IDirect3DBaseTexture8::GetLevelCount を呼び出して、生成されたレベル数を確認する。
Usage
[in] このリソースの使用方法を記述する、次の 1 つ以上のフラグの組み合わせ。
D3DUSAGE_DEPTHSTENCIL
サーフェスが深度ステンシル サーフェスとして使用されることを示す。リソースは、IDirect3DDevice8::SetRenderTarget メソッドの pNewDepthStencil パラメータに渡すことができる。「注意」を参照すること。
D3DUSAGE_RENDERTARGET
サーフェスがレンダリング ターゲットとして使用されることを示す。リソースは、SetRenderTarget メソッドの pRenderTarget パラメータに渡すことができる。「注意」を参照すること。

D3DUSAGE_RENDERTARGET または D3DUSAGE_DEPTHSTENCIL のいずれかが指定された場合は、アプリケーションで IDirect3D8::CheckDeviceFormat を呼び出して、デバイスがこれらの処理をサポートするかどうかを確認しなければならない。

Format
[in] D3DFORMAT 列挙型のメンバ。キューブ テクスチャの全サーフェスの全レベルのフォーマットを示す。
Pool
[in] D3DPOOL 列挙型のメンバ。キューブ テクスチャを格納するメモリ クラスを示す。
ppCubeTexture
[out, retval] 作成されたキューブ テクスチャ リソースを表す IDirect3DCubeTexture8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY
E_OUTOFMEMORY

注意

キューブ テクスチャは、サーフェスの集合である点がほかのサーフェスと異なる。キューブ テクスチャを指定して SetRenderTarget を呼び出すには、IDirect3DCubeTexture8::GetCubeMapSurface を使って特定のサーフェスを選択してから、それを SetRenderTarget に渡さなければならない。

テクスチャ (ミップマップ) は、連続してダウンサンプリングされた (ミップマップ化された) サーフェスの集合である。一方、CreateCubeTexture で作成されるキューブ テクスチャは、サーフェスごとに 1 つずつ、全部で 6 つのテクスチャ (ミップマップ) の集合である。すべてのサーフェスは、キューブ テクスチャに存在していなければならない。また、キューブ マップ サーフェスは、3 つのディメンジョン (x、y、および z) がすべて同じピクセル サイズでなければならない。

DirectX® 8.0 では、リソースの使用法が強制される。特定の処理にリソースを使用するアプリケーションは、リソース作成時にその処理を指定する必要がある。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3DDevice8::CreateDepthStencilSurface

深度ステンシル リソースを作成する。

HRESULT CreateDepthStencilSurface(
  UINT Width,
  UINT Height,
  D3DFORMAT Format,
  D3DMULTISAMPLE_TYPE MultiSample,
  IDirect3DSurface8** ppSurface
);

パラメータ

Width
[in] 深度ステンシル サーフェスの幅 (ピクセル単位)。
Height
[in] 深度ステンシル サーフェスの高さ (ピクセル単位)。
Format
[in] D3DFORMAT 列挙型のメンバ。深度ステンシル サーフェスのフォーマットを示す。この値は、そのデバイスに対して列挙された深度ステンシル フォーマットの 1 つでなければならない。
MultiSample
[in] マルチサンプリング バッファ タイプを記述する D3DMULTISAMPLE_TYPE 列挙型のメンバ。この値は、使用できるマルチサンプリング タイプの 1 つでなければならない。このサーフェスを SetRenderTarget に渡すときは、マルチサンプリング タイプがレンダリング ターゲットのものと同じでなければならない。
ppSurface
[out, retval] 作成された深度ステンシル サーフェス リソースを表す IDirect3DSurface8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

注意

深度ステンシル バッファのメモリ クラスは、常に D3DPOOL_DEFAULT である。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::CopyRects、IDirect3DDevice8::SetRenderTarget


IDirect3DDevice8::CreateImageSurface

イメージ サーフェスを作成する。

HRESULT CreateImageSurface(
  UINT Width,
  UINT Height,
  D3DFORMAT Format,
  IDirect3DSurface8** ppSurface
);

パラメータ

Width
[in] イメージ サーフェスの幅 (ピクセル単位)。
Height
[in] イメージ サーフェスの高さ (ピクセル単位)。
Format
[in] D3DFORMAT 列挙型のメンバ。イメージ サーフェスのフォーマットを示す。
ppSurface
[out, retval] 作成されたイメージ サーフェスを表す IDirect3DSurface8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY
E_OUTOFMEMORY

注意

イメージ サーフェスはプレース ホルダであり、ロック処理と IDirect3DDevice8::CopyRects 以外のすべての Microsoft® Direct3D® 操作では使用できない。

イメージ サーフェスは、D3DPOOL_SYSTEMMEM メモリ クラスに格納される。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3DDevice8::CreateIndexBuffer

インデックス バッファを作成する。

HRESULT CreateIndexBuffer(
  UINT Length,
  DWORD Usage,
  D3DFORMAT Format,
  D3DPOOL Pool,
  IDirect3DIndexBuffer8** ppIndexBuffer
);

パラメータ

Length
[in] インデックス バッファのサイズ (バイト単位)。
Usage
[in] このリソースの使用方法の制御情報を記述する、次の 1 つ以上のフラグの組み合わせ。
D3DUSAGE_DONOTCLIP
インデックス バッファの内容が決してクリッピングを要求しないことを示す。
D3DUSAGE_DYNAMIC
頂点またはインデックス バッファが動的なメモリの使用を必要とすることを示す。これを使用すると、ドライバが配置場所を決定できるので、ドライバにとって有効である。一般的に、静的な頂点バッファはビデオ メモリに配置され、動的な頂点バッファは AGP メモリに配置される。静的な使用方法だけを分離できないことに注意すること。D3DUSAGE_DYNAMIC を指定しないと、頂点バッファは静的に作成される。D3DUSAGE_DYNAMIC は、D3DLOCK_DISCARD および D3DLOCK_NOOVERWRITE ロッキング フラグによって厳密に強制される。この結果、D3DLOCK_DISCARD および D3DLOCK_NOOVERWRITE は、D3DUSAGE_DYNAMIC を指定して作成された頂点およびインデックス バッファでのみ有効である。これらは、静的な頂点バッファでは有効なフラグではない。

D3DUSAGE_DYNAMIC は、管理下の頂点およびインデックス バッファでは指定できないことに注意すること。詳細については、「リソースの管理」を参照すること。

D3DUSAGE_RTPATCHES
高次プリミティブの描画にインデックス バッファを使用するとき設定する。
D3DUSAGE_NPATCHES
N パッチの描画にインデックス バッファを使用するとき設定する。
D3DUSAGE_POINTS
ポイント スプライトまたはインデックス付きポイント リストの描画に、インデックス バッファを使用するとき設定する。
D3DUSAGE_SOFTWAREPROCESSING
バッファがソフトウェア処理で使用されることを示す。
D3DUSAGE_WRITEONLY
インデックス バッファへの書き込み操作しか実行できないことをシステムに通知する。このフラグを使用すると、ドライバは最適なメモリ領域を選択して効率的に書き込み操作やレンダリングを実行できる。この能力を使用して作成されたインデックス バッファからの読み込みを試みると、パフォーマンスが低下する場合がある。
Format
[in] D3DFORMAT 列挙型のメンバ。インデックス バッファのフォーマットを示す。有効な設定は次のとおりである。
D3DFMT_INDEX16
インデックスはそれぞれ 16 ビットである。
D3DFMT_INDEX32
インデックスはそれぞれ 32 ビットである。

「注意」を参照すること。

Pool
[in] D3DPOOL 列挙型のメンバ。リソースが配置される有効なメモリ クラスを記述する。
ppIndexBuffer
[out, retval] 作成されたインデックス バッファ リソースを表す IDirect3DIndexBuffer8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

注意

インデックス バッファは、インデックスを保持するために使われるメモリ リソースであり、サーフェス バッファおよび頂点バッファに似ている。インデックス バッファを使うことで、Microsoft® Direct3D® では、データの不必要なコピー処理を避けることができ、意図されている使用方法に最適なメモリ タイプにバッファを格納することができる。

インデックス バッファを使用するには、インデックス バッファを作成し、それをロックして、インデックスを格納する。次に、そのインデックス バッファをアンロックし、IDirect3DDevice8::SetIndices に渡し、頂点と頂点シェーダを設定し、IDirect3DDevice8::DrawIndexedPrimitive を呼び出してレンダリングを行う。

D3DCAPS8 構造体の MaxVertexIndex メンバは、レンダリングで有効なインデックス バッファのタイプを示す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ :D3d8.lib を使用。

参照

IDirect3DIndexBuffer8::GetDesc


IDirect3DDevice8::CreatePixelShader

ピクセル シェーダを作成する。

HRESULT CreatePixelShader(
  CONST DWORD* pFunction,
  DWORD* pHandle
);

パラメータ

pFunction
[in] ブレンディング処理を指定するピクセル シェーダ関数のトークン配列へのポインタ。この値は NULL にできない。
pHandle
[out, retval] 返されるピクセル シェーダのハンドルへのポインタ。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY
E_OUTOFMEMORY

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::DeletePixelShader、D3DXAssembleShader、D3DXAssembleShaderFromFileA、D3DXAssembleShaderFromFileW


IDirect3DDevice8::CreateRenderTarget

レンダリング ターゲット サーフェスを作成する。

HRESULT CreateRenderTarget(
  UINT Width,
  UINT Height,
  D3DFORMAT Format,
  D3DMULTISAMPLE_TYPE MultiSample,
  BOOL Lockable,
  IDirect3DSurface8** ppSurface
);

パラメータ

Width
[in] レンダリング ターゲット サーフェスの幅 (ピクセル単位)。
Height
[in] レンダリング ターゲット サーフェスの高さ (ピクセル単位)。
Format
[in] D3DFORMAT 列挙型のメンバ。レンダリング ターゲットのフォーマットを示す。
MultiSample
[in] マルチサンプリング バッファ タイプを記述する D3DMULTISAMPLE_TYPE 列挙型のメンバ。このパラメータは、作成するレンダリング ターゲットのアンチエイリアシング タイプを指定するものである。このタイプは、両方のバッファを SetRenderTarget に渡すときの深度ステンシル バッファのものと同じでなければならない。
Lockable
[in] アプリケーションが Lockable に TRUE を指定しない限り、レンダリング ターゲットはロックできない。ロック可能なレンダリング ターゲットによって、一部のグラフィック ハードウェアではパフォーマンスのコストが向上することに注意すること。
ppSurface
[out, retval] IDirect3DSurface8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY
E_OUTOFMEMORY

注意

レンダリング ターゲット サーフェスは、D3DPOOL_DEFAULT メモリ クラスに格納される。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3DDevice8::CreateStateBlock

すべてのデバイス ステート、頂点関連のステート、またはピクセル関連のステートの値を含む新しいステート ブロックを作成する。

HRESULT CreateStateBlock(
  D3DSTATEBLOCKTYPE Type,
  DWORD* pToken
);

パラメータ

Type
[in] メソッドで取り込むステート データの種類。このパラメータには、D3DSTATEBLOCKTYPE 列挙型で定義されている値を設定できる。
pToken
[out, retval] メソッドが成功した場合にステート ブロックのハンドルを格納する DWORD 値へのポインタ。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY
E_OUTOFMEMORY

注意

値 0xFFFFFFFF は、無効なステート ブロック ハンドルである。

頂点関連のデバイス ステートとは、一般にはシステムの頂点の処理方法に影響するステートをいう。ピクセル関連のステートとは、ラスタ化におけるシステムのピクセルまたは深度バッファの処理方法に影響するデバイス ステートをいう。ステートによっては両方に属する場合もある。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::ApplyStateBlock、IDirect3DDevice8::BeginStateBlock、IDirect3DDevice8::CaptureStateBlock、IDirect3DDevice8::EndStateBlock、IDirect3DDevice8::DeleteStateBlock


IDirect3DDevice8::CreateTexture

テクスチャ リソースを作成する。

HRESULT CreateTexture(
  UINT Width,
  UINT Height,
  UINT  Levels,
  DWORD Usage,
  D3DFORMAT Format,
  D3DPOOL Pool,
  IDirect3DTexture8** ppTexture
);

パラメータ

Width
[in] 最上位のテクスチャの幅 (ピクセル単位)。ミップマップ レベルが下のピクセル ディメンジョンは 1 つ上のレベルのピクセル ディメンジョンを (単純に) 1/2 した値である。それぞれの大きさは、1 ピクセルのサイズに収められる。したがって、2 で除算した結果が 0 の場合、代わりに 1 が使用される。
Height
[in] 最上位のテクスチャの高さ (ピクセル単位)。ミップマップ レベルが下のピクセル ディメンジョンは 1 つ上のレベルのピクセル ディメンジョンを (単純に) 1/2 した値である。それぞれの大きさは、1 ピクセルのサイズに収められる。したがって、2 で除算した結果が 0 の場合、代わりに 1 が使用される。
Levels
[in] テクスチャにあるレベルの数。0 を指定すると、MIP マップ化テクスチャをサポートするハードウェアに対し、Microsoft® Direct3D® は、1 × 1 ピクセルまでのすべてのテクスチャ サブレベルを生成する。その他の値を指定した場合は、1 レベルを生成する。IDirect3DBaseTexture8::GetLevelCount を呼び出して、生成されたレベル数を確認する。
Usage
[in] このリソースの使用方法を記述する、次の 1 つ以上のフラグの組み合わせ。
D3DUSAGE_DEPTHSTENCIL
サーフェスが深度ステンシル サーフェスとして使用されることを示す。リソースは、IDirect3DDevice8::SetRenderTarget メソッドの pNewZStencil パラメータに渡すことができる。
D3DUSAGE_RENDERTARGET
サーフェスがレンダリング ターゲットとして使用されることを示す。リソースは、SetRenderTarget のpRenderTarget パラメータに渡すことができる。

D3DUSAGE_RENDERTARGET または D3DUSAGE_DEPTHSTENCIL のいずれかが指定された場合は、アプリケーションで IDirect3D8::CheckDeviceFormat を呼び出して、デバイスがこれらの処理をサポートするかどうかを確認しなければならない。

Format
[in] D3DFORMAT 列挙型のメンバ。テクスチャの全レベルのフォーマットを示す。
Pool
[in] D3DPOOL 列挙型のメンバ。テクスチャを格納するメモリ クラスを示す。
ppTexture
[out, retval] 作成されたテクスチャ リソースを表す IDirect3DTexture8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY
E_OUTOFMEMORY

注意

テクスチャを指定して IDirect3DDevice8::SetRenderTarget を呼び出すには、IDirect3DTexture8::GetSurfaceLevel を使ってレベルを選択してから、そのサーフェスを SetRenderTarget に渡さなければならない。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3DDevice8::CreateVertexBuffer

頂点バッファを作成する。

HRESULT CreateVertexBuffer(
  UINT Length,
  DWORD Usage,
  DWORD FVF,
  D3DPOOL Pool,
  IDirect3DVertexBuffer8** ppVertexBuffer
);

パラメータ

Length
[in] 頂点バッファのサイズ (バイト単位)。柔軟な頂点フォーマット (FVF) 頂点バッファの場合は、Length は少なくとも 1 つの頂点を格納できる大きさでなければならないが、頂点サイズの倍数である必要はない。Length は非 FVF バッファについては検証されない。「注意」を参照すること。
Usage
[in] このリソースの使用方法の制御情報を記述する、次の 1 つ以上のフラグの組み合わせ。
D3DUSAGE_DONOTCLIP
頂点バッファの内容が決してクリッピングを要求しないことを示す。このフラグが設定されたバッファを使ってレンダリングする場合は、D3DRS_CLIPPING レンダリング ステートが FALSE に設定されていなければならない。
D3DUSAGE_DYNAMIC
頂点またはインデックス バッファが動的なメモリの使用を必要とすることを示す。これを使用すると、ドライバが配置場所を決定できるので、ドライバにとって有効である。一般的に、静的な頂点バッファはビデオ メモリに配置され、動的な頂点バッファは AGP メモリに配置される。静的な使用方法だけを分離できないことに注意すること。D3DUSAGE_DYNAMIC を指定しないと、頂点バッファは静的に作成される。D3DUSAGE_DYNAMIC は、D3DLOCK_DISCARD および D3DLOCK_NOOVERWRITE ロッキング フラグによって厳密に強制される。この結果、D3DLOCK_DISCARD および D3DLOCK_NOOVERWRITE は、D3DUSAGE_DYNAMIC を指定して作成された頂点およびインデックス バッファでのみ有効である。これらは、静的な頂点バッファでは有効なフラグではない。

動的な頂点バッファの使用方法の詳細については、「動的な頂点およびインデックス バッファの使い方」を参照すること。

D3DUSAGE_DYNAMIC は、管理下の頂点およびインデックス バッファでは指定できないことに注意すること。詳細については、「リソースの管理」を参照すること。

D3DUSAGE_RTPATCHES
高次プリミティブの描画に頂点バッファを使用するとき設定する。
D3DUSAGE_NPATCHES
N パッチの描画に頂点バッファを使用するとき設定する。
D3DUSAGE_POINTS
ポイント スプライトまたはインデックス付きポイント リストの描画に、頂点バッファを使用するとき設定する。
D3DUSAGE_SOFTWAREPROCESSING
ソフトウェア頂点処理で使用する頂点バッファであることを示す。
D3DUSAGE_WRITEONLY
頂点バッファへの書き込み操作しか実行しないことをシステムに知らせる。このフラグを使用することにより、ドライバは最適なメモリ領域を選択して効率的に書き込み操作やレンダリングを実行する。この能力を使用して作成された頂点バッファからの読み出しは失敗する。
FVF
[in] 柔軟な頂点フォーマット フラグの組み合わせ。バッファ内の頂点の頂点フォーマットを記述する使用方法の指定子。このパラメータに有効な FVF コードを設定すると、FVF 頂点バッファが作成される (「注意」を参照)。ゼロを設定すると、頂点バッファは非 FVF 頂点バッファになる。
Pool
[in] D3DPOOL 列挙型のメンバ。リソースが配置される有効なメモリ クラスを記述する。
ppVertexBuffer
[out, retval] 作成された頂点バッファ リソースを表す IDirect3DVertexBuffer8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY
E_OUTOFMEMORY

注意

IDirect3DDevice8 インターフェイスは、頂点バッファ オブジェクトに格納された頂点データを使用するプリミティブのレンダリングをサポートしている。頂点バッファは IDirect3DDevice8 インターフェイスから作成されて、頂点バッファの基になっている IDirect3DDevice8 オブジェクトでのみ使用できる。

FVF パラメータにゼロ以外の値を設定するときは、有効な FVF コードでなければならず、これはバッファの内容が FVF コードによって特徴付けられることを示している。FVF コードで作成された頂点バッファを、FVF 頂点バッファという。詳細については、「FVF 頂点バッファ」を参照すること。

D3DUSAGE_SOFTWAREPROCESSING フラグは、頂点バッファがソフトウェア頂点処理で使われるものであることを示している。詳細については、「デバイスの種類と頂点処理の要件」を参照すること。

非 FVF バッファを使用して、マルチパス レンダリングまたはシングル パスのマルチテクスチャ レンダリングで、データをインターリーブすることができる。これを行うには、1 つのバッファにはジオメトリ データを格納し、もう 1 つのバッファにはレンダリングする各テクスチャのテクスチャ座標を格納する。レンダリング時には、テクスチャ座標を格納する各バッファと共に、ジオメトリ データを格納するバッファがインターリーブされる。代わりに FVF バッファを使用した場合、各バッファに、レンダリングする各テクスチャに固有のテクスチャ座標データに加えて、同じジオメトリ データを格納する必要がある。これは、使用するストラテジにもよるが、スピードまたはメモリの面でマイナスとなる。テクスチャ座標の詳細については、「テクスチャ座標について」を参照すること。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DVertexBuffer8::GetDesc、IDirect3DDevice8::ProcessVertices


IDirect3DDevice8::CreateVertexShader

頂点シェーダを作成し、作成が成功した場合は、そのシェーダをカレント シェーダとして設定する。

HRESULT CreateVertexShader(
  CONST DWORD* pDeclaration,
  CONST DWORD* pFunction,
  DWORD* pHandle,
  DWORD Usage
);

パラメータ

pDeclaration
[in, out] 頂点シェーダ宣言トークン配列へのポインタ。このパラメータではシェーダへの入力を定義し、入力データ ストリーム中の頂点要素のシェーダによる使用方法も指定する。
pFunction
[in, out] 頂点シェーダ機能トークン配列へのポインタ。このパラメータでは、各頂点に適用する操作を定義する。このパラメータを NULL にすると、固定機能パイプライン用のシェーダが作成される。pDeclaration で示されているパラメータ宣言が現在の宣言になり、その後 IDirect3DDevice8::SetVertexShader の呼び出しでハンドル ポインタを指定する場合は、このパラメータ宣言を設定できる。

このパラメータを NULL 以外にすると、シェーダはプログラム可能になる。

pHandle
[in, out] 返される頂点シェーダのハンドルへのポインタ。この値は NULL に設定できない。
Usage
[in] 頂点シェーダに対する使用方法の制御情報。次のフラグを設定できる。
D3DUSAGE_SOFTWAREPROCESSING
ソフトウェア頂点処理で使用する頂点シェーダであることを示す。D3DRENDERSTATETYPE 列挙型の D3DRS_SOFTWAREVERTEXPROCESSING メンバが TRUE のときに使用する頂点シェーダに対しては D3DUSAGE_SOFTWAREPROCESSING フラグを設定しなければならず、D3DRS_SOFTWAREVERTEXPROCESSING が FALSE のときの頂点シェーダに対してはこのフラグを設定してはならない。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY
E_OUTOFMEMORY

注意

頂点シェーダは、シェーダの宣言と機能を指定する 2 つのトークン配列によって定義される。トークン配列は、1 つ以上の DWORD トークンで構成されており、配列の末尾は特殊な値 0xFFFFFFFF のトークンで示される。

シェーダの宣言はシェーダの静的な外部インターフェイスを定義しており、頂点レジスタ入力に対するストリーム データのバインドや、シェーダの定数メモリにロードされる値などが含まれる。シェーダの機能では、シェーダがデバイスにバインドされている間に各頂点に対する処理のために実行される命令の配列として、シェーダの動作が定義されている。機能配列を指定しないでシェーダを作成すると、そのシェーダがカレント シェーダのときには、固定機能の頂点処理が適用される。

宣言のトークン配列を生成するために使用するマクロの定義については、d3d8types.h を参照すること。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::DeleteVertexShader、D3DXAssembleShader、D3DXAssembleShaderFromFileA、D3DXAssembleShaderFromFileW、D3DXDeclaratorFromFVF


IDirect3DDevice8::CreateVolumeTexture

ボリューム テクスチャ リソースを作成する。

HRESULT CreateVolumeTexture(
  UINT Width,
  UINT Height,
  UINT Depth,
  UINT Levels,
  DWORD Usage,
  D3DFORMAT Format,
  D3DPOOL Pool,
  IDirect3DVolumeTexture8** ppVolumeTexture
);

パラメータ

Width
[in] 最上位のボリューム テクスチャの幅 (ピクセル単位)。この値は 2 の累乗でなければならない。ミップマップ レベルが下のピクセル ディメンジョンは 1 つ上のレベルのピクセル ディメンジョンを (単純に) 1/2 した値である。それぞれの大きさは、1 ピクセルのサイズに収められる。したがって、2 で除算した結果が 0 の場合、代わりに 1 が使用される。
Height
[in] 最上位のボリューム テクスチャの高さ (ピクセル単位)。この値は 2 の累乗でなければならない。ミップマップ レベルが下のピクセル ディメンジョンは 1 つ上のレベルのピクセル ディメンジョンを (単純に) 1/2 した値である。それぞれの大きさは、1 ピクセルのサイズに収められる。したがって、2 で除算した結果が 0 の場合、代わりに 1 が使用される。
Depth
[in] 最上位のボリューム テクスチャの深度 (ピクセル単位)。この値は 2 の累乗でなければならない。ミップマップ レベルが下のピクセル ディメンジョンは 1 つ上のレベルのピクセル ディメンジョンを (単純に) 1/2 した値である。それぞれの大きさは、1 ピクセルのサイズに収められる。したがって、2 で除算した結果が 0 の場合、代わりに 1 が使用される。
Levels
[in] テクスチャにあるレベルの数。0 を指定すると、ミップマップ化ボリューム テクスチャをサポートするハードウェアに対し、Microsoft® Direct3D® は、1 × 1 × 1 ピクセルまでのすべてのテクスチャ サブレベルを生成する。その他の値を指定した場合は、1 レベルを生成する。IDirect3DBaseTexture8::GetLevelCount を呼び出して、生成されるレベル数を確認する。
Usage
[in] 現在は使用されていない。0 に設定される。
Format
[in] D3DFORMAT 列挙型のメンバ。ボリューム テクスチャの全レベルのフォーマットを示す。
Pool
[in] D3DPOOL 列挙型のメンバ。ボリューム テクスチャを格納するメモリ クラスを示す。
ppVolumeTexture
[out, retval] 作成されたボリューム テクスチャ リソースを表す IDirect3DVolumeTexture8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY
E_OUTOFMEMORY

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3DDevice8::DeletePixelShader

指定されたハンドルで参照されているピクセル シェーダを削除する。

HRESULT DeletePixelShader(
  DWORD Handle
);

パラメータ

Handle
[in] ピクセル シェーダのハンドル。内部エントリから削除するピクセル シェーダを示す。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::CreatePixelShader


IDirect3DDevice8::DeleteStateBlock

以前に記録していたデバイス ステート ブロックを削除する。

HRESULT DeleteStateBlock(
  DWORD Token
);

パラメータ

Token
[in] 削除するデバイス ステート ブロックへのハンドル。これは前に呼び出した IDirect3DDevice8::EndStateBlock メソッドによって返される。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

値 0xFFFFFFFF は、無効なステート ブロック ハンドルである。

別のステート ブロックの記録中に、デバイス ステート ブロックを削除することはできない。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::ApplyStateBlock、IDirect3DDevice8::BeginStateBlock、IDirect3DDevice8::CaptureStateBlock、IDirect3DDevice8::CreateStateBlock、IDirect3DDevice8::EndStateBlock


IDirect3DDevice8::DeletePatch

キャッシュされていた高次パッチを解放する。

HRESULT DeletePatch(
  UINT Handle
);

パラメータ

Handle
[in] 削除するキャッシュされていた高次パッチのハンドル。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::DrawRectPatch、IDirect3DDevice8::DrawTriPatch、パッチの描画


IDirect3DDevice8::DeleteVertexShader

指定されたハンドルで参照されている頂点シェーダを削除し、関連するリソースを解放する。

HRESULT DeleteVertexShader(
  DWORD Handle
);

パラメータ

Handle
[in] 頂点シェーダのハンドル。削除する頂点シェーダを示す。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::CreateVertexShader


IDirect3DDevice8::DrawIndexedPrimitive

頂点の配列へのインデックスに基づいて、指定されたジオメトリ プリミティブをレンダリングする。

HRESULT DrawIndexedPrimitive(
  D3DPRIMITIVETYPE Type,
  UINT MinIndex,
  UINT NumVertices,
  UINT StartIndex,
  UINT PrimitiveCount
);

パラメータ

Type
[in] D3DPRIMITIVETYPE 列挙型のメンバ。レンダリングするプリミティブの種類を記述する。「注意」を参照すること。
MinIndex
[in] この呼び出しの間に使用される頂点群に対する最小の頂点インデックス。
NumVertices
[in] この呼び出しで使用される頂点の数 (BaseVertexIndex + MinIndex から始まる)。
StartIndex
[in] インデックス配列の中で頂点の読み取りを開始する位置。
PrimitiveCount
[in] レンダリングするプリミティブの数。使用される頂点の数は、プリミティブ カウントの機能とプリミティブの種類である。プリミティブの許容最大数は、D3DCAPS8 構造体の MaxPrimitiveCount メンバをチェックして決定される。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

このメソッドは、現在のデータ入力ストリームの集合からインデックス付きプリミティブを描画する。

MinIndex、およびインデックス ストリームのすべての頂点は、IDirect3DDevice8::SetIndices の呼び出し時に設定される BaseVertexIndex に関連する。

minIndex パラメータと NumVertices パラメータで、DrawIndexedPrimitive の呼び出しごとに使用する頂点インデックスの範囲を指定する。この 2 つのパラメータを使って、インデックス付けする前の頂点群のシーケンシャルな範囲を処理することで、インデックス付きプリミティブの頂点処理を最適化する。呼び出しの間に使われるインデックスがこの範囲外の頂点を参照することは無効である。

インデックス配列が設定されていない場合、DrawIndexedPrimitive は失敗する。

D3DPRIMITIVETYPE 列挙型の D3DPT_POINTLIST メンバはサポートされていないので、Type として指定すべきではない。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::DrawPrimitive、IDirect3DDevice8::SetStreamSource、プリミティブのレンダリング


IDirect3DDevice8::DrawIndexedPrimitiveUP

ユーザー メモリ ポインタで指定されているデータで、指定されているジオメトリ プリミティブをレンダリングする。

HRESULT DrawIndexedPrimitiveUP(
  D3DPRIMITIVETYPE PrimitiveType,
  UINT MinIndex,
  UINT NumVertices,
  UINT PrimitiveCount,
  CONST void* pIndexData,
  D3DFORMAT IndexDataFormat,
  CONST void* pVertexStreamZeroData,
  UINT VertexStreamZeroStride
);

パラメータ

PrimitiveType
[in] D3DPRIMITIVETYPE 列挙型のメンバ。レンダリングするプリミティブの種類を記述する。
MinIndex
[in] この呼び出しの間に使用される頂点群に対する、0 (pIndexData の開始位置) を基準とする最小の頂点インデックス。
NumVertices
[in] この呼び出しで使用される頂点の数 (MinIndex. から始まる)。
PrimitiveCount
[in] レンダリングするプリミティブの数。使用されるインデックスの数は、プリミティブ カウントの機能とプリミティブの種類である。プリミティブの許容最大数は、D3DCAPS8 構造体の MaxPrimitiveCount メンバをチェックして決定される。
pIndexData
[in] インデックス データに対するユーザー メモリ ポインタ。
IndexDataFormat
[in] インデックス データのフォーマットを示す D3DFORMAT 列挙型のメンバ。有効な設定は次のとおりである。
D3DFMT_INDEX16
インデックスはそれぞれ 16 ビットである。
D3DFMT_INDEX32
インデックスはそれぞれ 32 ビットである。
pVertexStreamZeroData
[in] 頂点ストリームをゼロにするために使用する頂点データのユーザー メモリ ポインタ。
VertexStreamZeroStride
[in] 各頂点のデータ間のストライド (バイト単位)。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

このメソッドは、頂点データを頂点バッファに格納できないアプリケーションで使用する。このメソッドは単一の頂点ストリームのみをサポートする。この呼び出しは、頂点ストリームに提供された頂点データのポインタとストライドをゼロにする。ストリーム ゼロ以外の頂点ストリームを参照するカレント頂点シェーダを宣言することはできない (or を宣言するとエラーとなる)。

DrawIndexedPrimitiveUP の呼び出しの後、IDirect3DDevice8::GetStreamSource で参照されるストリーム ゼロの設定は、NULL に設定される。また、IDirect3DDevice8::SetIndices に対するインデックス バッファの設定も、NULL に設定される。

DrawIndexPrimitiveUP に渡される頂点データは呼出し後に存続する必要はない。Direct3D は呼び出しから戻った時点でそのデータへのアクセスを完了している。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::DrawPrimitiveUP、IDirect3DDevice8::SetStreamSource、プリミティブのレンダリング


IDirect3DDevice8::DrawPrimitive

現在のデータ入力ストリーム セットから、指定されたタイプの非インデックス付きジオメトリ プリミティブのシーケンスをレンダリングする。

HRESULT DrawPrimitive(
  D3DPRIMITIVETYPE PrimitiveType,
  UINT StartVertex,
  UINT PrimitiveCount
);

パラメータ

PrimitiveType
[in] D3DPRIMITIVETYPE 列挙型のメンバ。レンダリングするプリミティブの種類を記述する。
StartVertex
[in] ロードする最初の頂点のインデックス。StartVertex を先頭に、正しい頂点数が頂点バッファから読み取られる。
PrimitiveCount
[in] レンダリングするプリミティブの数。プリミティブの許容最大数は、D3DCAPS8 構造体の MaxPrimitiveCount メンバをチェックして決定される。PrimitiveCount は、プリミティブ タイプで指定されたプリミティブの数である。プリミティブ タイプが線リストの場合、各プリミティブは 2 つの頂点を持つ。プリミティブ タイプが三角形リストの場合は、各プリミティブは 3 つの頂点を持つ。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

一度に 1 つの三角形を指定して DrawPrimitive を呼び出すべきではない。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::DrawIndexedPrimitive、IDirect3DDevice8::SetStreamSource、プリミティブのレンダリング


IDirect3DDevice8::DrawPrimitiveUP

ユーザー メモリ ポインタで指定されたデータを、指定されたタイプのジオメトリ プリミティブのシーケンスとしてレンダリングする。

HRESULT DrawPrimitiveUP(
  D3DPRIMITIVETYPE PrimitiveType,
  UINT PrimitiveCount,
  CONST void* pVertexStreamZeroData,
  UINT VertexStreamZeroStride
);

パラメータ

PrimitiveType
[in] D3DPRIMITIVETYPE 列挙型のメンバ。レンダリングするプリミティブの種類を記述する。
PrimitiveCount
[in] レンダリングするプリミティブの数。プリミティブの許容最大数は、D3DCAPS8 構造体の MaxPrimitiveCount メンバをチェックして決定される。
pVertexStreamZeroData
[in] 頂点ストリームをゼロにするために使用する頂点データのユーザー メモリ ポインタ。
VertexStreamZeroStride
[in] 各頂点のデータ間のストライド (バイト単位)。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

このメソッドは、頂点データを頂点バッファに格納できないアプリケーションで使用する。このメソッドは単一の頂点ストリームのみをサポートする。この呼び出しは、頂点ストリームに提供された頂点データのポインタとストライドをゼロにする。ストリーム ゼロ以外の頂点ストリームを参照するカレント頂点シェーダを宣言することはできない (or を宣言するとエラーとなる)。

DrawPrimitiveUP の呼び出しの後、IDirect3DDevice8::GetStreamSource で参照されるストリーム ゼロの設定は、NULL に設定される。

DrawPrimitiveUP に渡される頂点データは呼出し後に存続する必要はない。Direct3D は呼び出しから戻った時点でそのデータへのアクセスを完了している。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::DrawIndexedPrimitiveUP、IDirect3DDevice8::SetStreamSource、プリミティブのレンダリング


IDirect3DDevice8::DrawRectPatch

現在設定されているストリームを使って、矩形の高次パッチを描画する。

HRESULT DrawRectPatch(
  UINT Handle,
  CONST float* pNumSegs,
  CONST D3DRECTPATCH_INFO* pRectPatchInfo
);

パラメータ

Handle
[in] 描画する矩形の高次パッチへのハンドル。
pNumSegs
[in, out] テッセレーションするときに高次プリミティブの各エッジを分割するセグメントの数を示す浮動小数点値へのポインタ。
pRectPatchInfo
[in, out] D3DRECTPATCH_INFO 構造体へのポインタ。描画する矩形の高次パッチを記述する。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::DeletePatch、パッチの描画


IDirect3DDevice8::DrawTriPatch

現在設定されているストリームを使って、三角形の高次パッチを描画する。

HRESULT DrawTriPatch(
  UINT Handle,
  CONST float* pNumSegs,
  CONST D3DTRIPATCH_INFO* pTriPatchInfo
);

パラメータ

Handle
[in] 描画する三角形の高次パッチへのハンドル。
pNumSegs
[in, out] テッセレーションするときに高次プリミティブの各エッジを分割するセグメントの数を示す浮動小数点値へのポインタ。
pTriPatchInfo
[in, out] D3DTRIPATCH_INFO 構造体へのポインタ。描画する三角形の高次パッチを記述する。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::DeletePatch、パッチの描画


IDirect3DDevice8::EndScene

IDirect3DDevice8::BeginScene メソッドの呼び出しによって開始されたシーンを終了する。

HRESULT EndScene();

パラメータ

なし。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

このメソッドが成功すると、シーンがレンダリングされ、レンダリング後のシーンがデバイス サーフェスに保持される。

シーンのレンダリングが正常に開始している場合、別のシーンのレンダリングを開始するために IDirect3DDevice8::BeginScene メソッドを呼び出すには、その前にこのメソッドを呼び出す必要があるBeginScene メソッドの呼び出しが失敗している場合はシーンのレンダリングは開始していないため、このメソッドを呼び出す必要はない。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::BeginScene


IDirect3DDevice8::EndStateBlock

デバイス ステート ブロックの記録を停止してステート ブロックのハンドルを取得するように Microsoft® Direct3D® に指示する。

HRESULT EndStateBlock(
  DWORD* pToken
);

パラメータ

pToken
[out, retval] 記録を終了するデバイス ステート ブロックのハンドルを格納する変数へのポインタ。この値は、IDirect3DDevice8::ApplyStateBlock メソッドおよび IDirect3DDevice8::DeleteStateBlock メソッドで使用される。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

注意

値 0xFFFFFFFF は、無効なステート ブロック ハンドルである。

参照

IDirect3DDevice8::ApplyStateBlock、IDirect3DDevice8::BeginStateBlock、IDirect3DDevice8::CaptureStateBlock、IDirect3DDevice8::CreateStateBlock、IDirect3DDevice8::DeleteStateBlock


IDirect3DDevice8::GetAvailableTextureMem

使用可能なテクスチャ メモリの量の推定値を返す。

UINT GetAvailableTextureMem();

パラメータ

なし。

戻り値

この関数は、使用可能なテクスチャ メモリの推定値を返す。

注意

返される値は、最も近い MB に丸められる。このような処理が行われるのは、特定のリソースによるビデオ メモリの消費に影響を与えるアラインメントやほかの問題により、ビデオ メモリの推定値を正確に求めることができないためである。アプリケーションでは、この値を使って、利用できるメモリの大まかな量を推定し、割り当てようとするミップマップのレベル数のようなリソースに関する巨視的な決定を下すことはできるが、別のリソースを割り当てるのに十分なメモリが残っているかどうかといった小さなスケールの決定に使用することはできない。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3DDevice8::GetBackBuffer

デバイスのスワップ チェーンからバック バッファを取得する。

HRESULT GetBackBuffer(
  UINT BackBuffer,
  D3DBACKBUFFER_TYPE Type,
  IDirect3DSurface8** ppBackBuffer
);

パラメータ

BackBuffer
[in] 返されるバック バッファ オブジェクトのインデックス。バック バッファは 0 からバック バッファの総数 - 1 までナンバリングされる。0 の戻り値は最初のバック バッファを示し、フロント バッファではない。このメソッドを使用してフロント バッファにアクセスすることはできない。
Type
[in] DirectX 8.0 ではステレオ ビューはサポートされていないので、このパラメータの有効な値は D3DBACKBUFFER_TYPE_MONO だけである。
ppBackBuffer
[out, retval] 返されるバック バッファ サーフェスを表す IDirect3DSurface8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、D3D_OK を返す。

BackBuffer がバック バッファの総数以上の場合、関数は失敗し、D3DERR_INVALIDCALL を返す。

注 このメソッドを呼び出すと、IDirect3DSurface8 インターフェイスについての内部参照カウントが増加する。この IDirect3DSurface8 インターフェイスの使用を終了したときに IUnknown::Release の呼び出しが失敗すると、メモリ リークが発生する。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3DDevice8::GetClipPlane

デバイスのユーザー定義クリップ面の係数を取得する。

HRESULT GetClipPlane(
  DWORD Index,
  float* pPlane
);

パラメータ

Index
[in] 平面方程式の係数を取得するクリップ面のインデックス。
pPlane
[out] 一般平面方程式においてクリップ面の係数を表す値の、4 要素で構成される配列へのポインタ。「注意」を参照すること。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。このエラーは、Index の値がデバイスでサポートされる最大クリップ面インデックスを超えているか、pPlane の配列が 4 つの浮動小数点値を格納するほど大きくないことを示す。

注意

このメソッドで取得する係数は、一般平面方程式の形をとる。pPlane の配列の値が配列内での順に A、B、C、および D とラベル付けされている場合、これらの値は一般平面方程式が Ax + By + Cz + Dw = 0 になるように適用される。Ax + By + Cz + Dw >= 0 である場合、同次座標 (x, y, z, w) のポイントは平面で切り取られた半分の空間に表示される。クリップ面上または背後に存在するポイントはシーンからクリッピングされる。

このメソッドで使用される平面方程式はワールド空間に存在し、その前に呼び出す IDirect3DDevice8::SetClipPlane メソッドによって設定される。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::SetClipPlane


IDirect3DDevice8::GetClipStatus

クリップ ステータスを取得する。

HRESULT GetClipStatus(
  D3DCLIPSTATUS8* pClipStatus
);

パラメータ

pClipStatus
[out] クリップ ステータスを記述する D3DCLIPSTATUS8 構造体へのポインタ。

戻り値

成功した場合は、D3D_OK を返す。

この引数が無効な場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::SetClipStatus


IDirect3DDevice8::GetCreationParameters

デバイスの作成パラメータを取得する。

HRESULT GetCreationParameters(
  D3DDEVICE_CREATION_PARAMETERS* pParameters
);

パラメータ

pParameters
[out] デバイスの作成パラメータが記述された D3DDEVICE_CREATION_PARAMETERS 構造体へのポインタ。

戻り値

成功した場合は、D3D_OK を返す。

この引数が無効な場合は、D3DERR_INVALIDCALL を返す。

注意

このデバイスで表されているアダプタの番号を取得するには、返される D3DDEVICE_CREATION_PARAMETERS 構造体の AdapterOrdinal メンバを参照する。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3DDevice8::GetCurrentTexturePalette

現在のテクスチャ パレットを取得する。

HRESULT GetCurrentTexturePalette(
  UINT* pPaletteNumber
);

パラメータ

pPaletteNumber
[out, retval] 返される現在のテクスチャ パレットを示す値へのポインタ。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::SetCurrentTexturePalette、テクスチャ パレット


IDirect3DDevice8::GetDepthStencilSurface

Direct3DDevice オブジェクトが所有する深度ステンシル サーフェスを取得する。

HRESULT GetDepthStencilSurface(
  IDirect3DSurface8** ppZStencilSurface
);

パラメータ

ppZStencilSurface
[out, retval] 返される深度ステンシル サーフェスを表す IDirect3DSurface8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注 このメソッドを呼び出すと、IDirect3DSurface8 インターフェイスについての内部参照カウントが増加する。この IDirect3DSurface8 インターフェイスの使用を終了したときに IUnknown::Release の呼び出しが失敗すると、メモリ リークが発生する。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::SetRenderTarget、IDirect3DDevice8::CopyRects


IDirect3DDevice8::GetDeviceCaps

レンダリング デバイスの能力を取得する。

HRESULT GetDeviceCaps(
  D3DCAPS8* pCaps
);

パラメータ

pCaps
[out] 返されるデバイスを記述する D3DCAPS8 構造体へのポインタ。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

GetDeviceCaps は、デバイスがソフトウェア頂点処理モードで使用されているときに、ソフトウェア頂点パイプライン能力を取得する。デバイスが D3DCREATE_SOFTWAREVERTEXPROCESSING を指定して作成されている場合、またはデバイスが D3DCREATE_MIXEDVERTEXPROCESSING を指定して作成され、D3DRS_SOFTWAREVERTEXPROCESSING が TRUE に設定されている場合、ソフトウェア頂点処理モードが選択される。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3DDevice8::GetDirect3D

デバイスを作成したMicrosoft® Direct3D® オブジェクトのインスタンスへのインターフェイスを返す。

HRESULT GetDirect3D(
  IDirect3D8** ppD3D8
);

パラメータ

ppD3D8
[out, retval] IDirect3D8 インターフェイスへのポインタのアドレス。デバイスを作成した Direct3D オブジェクトのインターフェイスを表す。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

GetDirect3D を呼び出すとそのインターフェイスに対する参照カウントが増えるので、インターフェイスの使用が終了したら、このポインタを通して IUnknown::Release を呼び出す必要がある。

注 このメソッドを呼び出すと、IDirect3D8 インターフェイスについての内部参照カウントが増加する。この IDirect3D8 インターフェイスの使用を終了したときに IUnknown::Release の呼び出しが失敗すると、メモリ リークが発生する。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3DDevice8::GetDisplayMode

ディスプレイ モードの空間解像度、色解像度、およびリフレッシュ周波数を取得する。

HRESULT GetDisplayMode(
  D3DDISPLAYMODE* pMode
);

パラメータ

pMode
[out] アダプタのディスプレイ モードについてのデータを格納する D3DDISPLAYMODE 構造体へのポインタ。デバイスのディスプレイ モードとは反対に、デバイスでフルスクリーン モードが使用できない場合は、このディスプレイ モードはアクティブにできない。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3DDevice8::GetFrontBuffer

デバイスのフロント バッファのコピーを生成し、アプリケーションが提供するシステム メモリ バッファにそのコピーを格納する。

HRESULT GetFrontBuffer(
  IDirect3DSurface8* pDestSurface
);

パラメータ

pDestSurface
[in] フロント バッファの内容のコピーを受け取る IDirect3DSurface8 インターフェイスへのポインタ。データは、デバイスの出力の一番上の行から始めて一番下の行まで、間にスペースを挟まない連続した行として返される。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_DEVICELOST
D3DERR_INVALIDCALL

注意

pDestSurface で示されるバッファには、フロント バッファの表示を標準の 32bpp フォーマットである D3DFMT_A8R8G8B8 に変換したものが格納される。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3DDevice8::GetGammaRamp

スワップ チェーンのガンマ修正ランプを取得する。

void GetGammaRamp(
  D3DGAMMARAMP* pRamp
);

パラメータ

pRamp
[in, out] アプリケーションが提供する D3DGAMMARAMP 構造体へのポインタ。ガンマ修正ランプが格納される。

戻り値

なし。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DSwapChain8、IDirect3DDevice8::SetGammaRamp


IDirect3DDevice8::GetIndices

インデックス データを取得する。

HRESULT GetIndices(
  IDirect3DIndexBuffer8** ppIndexData,
  UINT* pBaseVertexIndex
);

パラメータ

ppIndexData
[out] 返されるインデックス データを表す IDirect3DIndexBuffer8 インターフェイスへのポインタのアドレス。
pBaseVertexIndex
[out] 返される頂点インデックスのベース値を格納する UINT 値へのポインタ。この値は、頂点データを参照する前にすべてのインデックスに追加され、頂点ストリームの開始位置を定義する。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

インデックス リストの値は、レンダリングするジオメトリを作成するときの頂点リストへのインデックス付けに使われる。

pBaseVertexIndex パラメータに返される値は、インデックスのベース値を示している。このベース値は、頂点データ ストリームを参照する前にすべてのインデックスに追加される。その結果、頂点データ ストリームの開始位置が設定される。ベースとなる頂点インデックスによって、頂点データ内に配置されている対応するプリミティブの場所に基づいてインデックスを再計算せずに、複数のインデックス付きプリミティブを単一の頂点データのセットにパックすることができる。

注 このメソッドを呼び出すと、IDirect3DIndexBuffer8 インターフェイスについての内部参照カウントが増加する。この IDirect3DIndexBuffer8 インターフェイスの使用を終了したときに IUnknown::Release の呼び出しが失敗すると、メモリ リークが発生する。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::SetIndices


IDirect3DDevice8::GetInfo

レンダリング デバイスについての情報を取得する。

HRESULT GetInfo(
  DWORD DevInfoID,
  VOID* pDevInfoStruct,
  DWORD DevInfoStructSize
);

パラメータ

DevInfoID
[in] pDevInfoStruct に返される情報を識別するために使用される値。
pDevInfoStruct
[in, out] 呼び出しが成功した場合に、指定したデバイスの情報を受け取る構造体へのポインタ。
DevInfoStructSize
[in] pDevInfoStruct の構造体のサイズ (バイト単位)。

戻り値

成功した場合は、D3D_OK を返す。このメソッドは、Microsoft® DirectX® のリテール ビルドでは S_FALSE を返す (「注意」を参照)。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

このメソッドが返す情報は、基本となるデバイス ドライバに関連するものである。このメソッドを使用すると、ドライバで特定の種類の情報およびそれに対応する構造体を宣言できるようになる。これらについては、この SDK では説明されていない。

このメソッドは同期して実行されるが、実行速度が遅い場合は、アプリケーションのパフォーマンスが低下することがある。シーンのレンダリング中 (IDirect3DDevice8::BeginScene を呼び出してから IDirect3DDevice8::EndScene を呼び出すまで) は、このメソッドを呼び出してはならない。

このメソッドは、製品開発時のパフォーマンス追跡およびデバッグに使用する (DirectX のデバッグ バージョン)。このメソッドが成功して S_FALSE を返しても、デバイス データを取得していないときがある。ホスト システムに DirectX ランタイムのリテール バージョンがインストールされている場合、このようなことが起こる。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3DDevice8::GetLight

このデバイスで使用する一連のライト プロパティを取得する。

HRESULT GetLight(
  DWORD Index,
  D3DLIGHT8* pLight
);

パラメータ

Index
[in] 取得するライト プロパティ セットのゼロから始まるインデックス。
pLight
[out] 取得したライティング パラメータ セットを格納する D3DLIGHT8 構造体へのポインタ。

戻り値

成功した場合は、D3D_OK を返す。

pLight パラメータが無効な場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::SetLight、IDirect3DDevice8::GetLightEnable、IDirect3DDevice8::LightEnable


IDirect3DDevice8::GetLightEnable

デバイス内のライティング パラメータ セットのアクティビティ ステータス (有効/無効) を取得する。

HRESULT GetLightEnable(
  DWORD Index,
  BOOL* pEnable
);

パラメータ

Index
[in] このメソッドの対象となるライティング パラメータ セットのゼロから始まるインデックス。
pEnable
[out, retval] 指定したライティング パラメータのステータスを格納する変数へのポインタ。呼び出しの後、このアドレスの値がゼロ以外の場合は、指定したライティング パラメータが有効であることを示し、0 の場合は無効であることを示す。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::GetLight、IDirect3DDevice8::LightEnable、IDirect3DDevice8::SetLight


IDirect3DDevice8::GetMaterial

デバイスに対する現在のマテリアルのプロパティを取得する。

HRESULT GetMaterial(
  D3DMATERIAL8*pMaterial
);

パラメータ

pMaterial
[out] 現在設定されているマテリアルのプロパティを格納する D3DMATERIAL8 構造体へのポインタ。

戻り値

成功した場合は、D3D_OK を返す。

pMaterial パラメータが無効な場合は、D3DERR_INVALIDCALL になる。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::SetMaterial


IDirect3DDevice8::GetPaletteEntries

パレット エントリを取得する。

HRESULT GetPaletteEntries(
  UINT PaletteNumber,
  PALETTEENTRY* pEntries
);

パラメータ

PaletteNumber
[in] 取得する特定のパラメータを識別する序数値。
pEntries
[in, out] 返されるパレット エントリを表す PALETTEENTRY 構造体へのポインタ。「注意」を参照すること。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

PALETTEENTRY の詳細については、Microsoft® Platform Software Development Kit (SDK) を参照すること。DirectX 8.0 では、PALETTEENTRY 構造体の peFlags メンバは、Platform SDK に説明されているようには機能しない。peFlags メンバは、現在、8 ビット パレット化フォーマットのアルファ チャネルである。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::GetCurrentTexturePalette、IDirect3DDevice8::SetCurrentTexturePalette、IDirect3DDevice8::SetPaletteEntries、テクスチャ パレット


IDirect3DDevice8::GetPixelShader

現在設定されているピクセル シェーダを取得する。

HRESULT GetPixelShader(
   DWORD* pHandle
);

パラメータ

pHandle
[out, retval] 返されるピクセル シェーダを表すピクセル シェーダ ハンドルへのポインタ。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::SetPixelShader


IDirect3DDevice8::GetPixelShaderConstant

ピクセル シェーダ定数配列中の値を取得する。

HRESULT GetPixelShaderConstant(
   DWORD Register,
   void* pConstantData,
   DWORD ConstantCount
);

パラメータ

Register
[in] ピクセル シェーダ定数配列からのデータの取得を開始する位置のレジスタ アドレス。
pConstantData
[in, out] ピクセル シェーダ定数配列から取得した値を格納するデータ ブロックへのポインタ。データ ブロックのサイズは、ConstantCount * 4 * sizeof(float) である。
ConstantCount
[in] ピクセル シェーダ定数配列から取得取得する定数の数。各定数は、4 つの浮動小数点値から成る。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

このメソッドは、ピクセル シェーダ アセンブラの定数レジスタにある値を取得するために使用する。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::SetPixelShaderConstant


IDirect3DDevice8::GetPixelShaderFunction

ピクセル シェーダの機能を取得する。

HRESULT GetPixelShaderFunction(
   DWORD Handle,
   void* pData,
   DWORD* pSizeOfData
);

パラメータ

Handle
[in] 参照するピクセル シェーダへのハンドル。
pData
[out] 呼び出しが成功した場合に要求したピクセル シェーダ ハンドルに関連付けられているコードを格納する、以前に割り当てられていたバッファへのポインタ。このメソッドを呼び出すアプリケーションは、このバッファの割り当てと解放に責任を負う。
pSizeOfData
[in, out] DWORD 値へのポインタ。pData のバッファ サイズをバイト単位で示す。この値が 0 などのように、実際のデータ サイズよりも小さい場合、メソッドはこのパラメータを必要なバッファ サイズに設定し、D3DERR_MOREDATA を返す。バッファが NULL の場合、このパラメータには必要なサイズが指定され、D3D_OK が返される。

戻り値

成功した場合は、D3D_OK を返す。

Handle がピクセル シェーダへの無効なハンドルである場合は、D3DERR_INVALIDCALL を返す。

注意

ピクセル シェーダの機能は、ブレンディング処理を示している。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::GetPixelShader


IDirect3DDevice8::GetRasterStatus

スワップ チェーンが表示されているモニタのラスタを記述する情報を返す。

HRESULT GetRasterStatus(
  D3DRASTER_STATUS* pRasterStatus
);

パラメータ

pRasterStatus
[out] このアダプタによって駆動されるモニタ上のラスタの位置やその他のステータスについての情報が格納される D3DRASTER_STATUS 構造体へのポインタ。

戻り値

成功した場合は、D3D_OK を返す。

pRasterStatus が無効である場合、またはデバイスが現在の走査線からの読み取りをサポートしていない場合は、D3DERR_INVALIDCALL を返す。デバイスが走査線からの読み取りをサポートしているかどうかは、D3DCAPS8 の Caps メンバの D3DCAPS_READ_SCANLINE フラグをチェックして調べることができる。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

D3DRASTER_STATUS


IDirect3DDevice8::GetRenderState

デバイスに対するレンダリング ステートの値を取得する。

HRESULT GetRenderState(
  D3DRENDERSTATETYPE State,
  DWORD* pValue
);

パラメータ

State
[in] 調査対象のデバイス ステート変数。このパラメータには、D3DRENDERSTATETYPE 列挙型の任意のメンバを指定できる。
pValue
[out, retval] メソッドから戻ったときに、照会したレンダリング ステート変数の値を受け取る変数へのポインタ。

戻り値

成功した場合は、D3D_OK を返す。

引数のいずれかが無効な場合は、D3DERR_INVALIDCALL になる。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::SetRenderState


IDirect3DDevice8::GetRenderTarget

レンダリング ターゲットとして使われる Microsoft® Direct3D® サーフェスへのポインタを取得する。

HRESULT GetRenderTarget(
  IDirect3DSurface8** ppRenderTarget
);

パラメータ

ppRenderTarget
[out, retval] IDirect3DSurface8 インターフェイスへのポインタのアドレス。返されるこのデバイスのレンダリング ターゲット サーフェスを表す。

戻り値

成功した場合は、D3D_OK を返す。

引数のいずれかが無効な場合は、D3DERR_INVALIDCALL になる。

注 このメソッドを呼び出すと、IDirect3DSurface8 インターフェイスについての内部参照カウントが増加する。この IDirect3DSurface8 インターフェイスの使用を終了したときに IUnknown::Release の呼び出しが失敗すると、メモリ リークが発生する。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::SetRenderTarget


IDirect3DDevice8::GetStreamSource

指定されたデータ ストリームにバインドされている頂点バッファを取得する。

HRESULT GetStreamSource(
   UINT StreamNumber
   IDirect3DVertexBuffer8** ppStreamData,
   UINT* pStride
);

パラメータ

StreamNumber
[in] 0 からストリームの最大数 - 1 までの範囲のデータ ストリームを指定する。
ppStreamData
[in, out] 指定したデータ ストリームにバインドされている頂点バッファを表す IDirect3DVertexBuffer8 インターフェイスへのポインタのアドレス。
pStride
[in, out] 返されたコンポーネントのストライド (バイト単位) へのポインタ。「注意」を参照すること。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

ストリームはコンポーネント データの一様な配列として定義されており、各コンポーネントは、位置、法線、色などの単一エンティティを表す 1 つ以上の要素で構成されている。

注 このメソッドを呼び出すと、IDirect3DVertexBuffer8 インターフェイスについての内部参照カウントが増加する。この IDirect3DVertexBuffer8 インターフェイスの使用を終了したときに IUnknown::Release の呼び出しが失敗すると、メモリ リークが発生する。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::SetStreamSource


IDirect3DDevice8::GetTexture

デバイスのステージに割り当てられているテクスチャを取得する。

HRESULT GetTexture(
  DWORD Stage,
  IDirect3DBaseTexture8** ppTexture
);

パラメータ

Stage
[in] 取得するテクスチャのステージ識別子。ステージ識別子は 0 から始まる。デバイスは最大 8 セットまでテクスチャを持つことができるので、Stage に指定できる最大値は 7 である。
ppTexture
[out, retval] 返されるテクスチャを表す IDirect3DBaseTexture8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注 このメソッドを呼び出すと、IDirect3DTexture8 インターフェイスについての内部参照カウントが増加する。この IDirect3DTexture8 インターフェイスの使用を終了したときに IUnknown::Release の呼び出しが失敗すると、メモリ リークが発生する。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::SetTexture、IDirect3DDevice8::GetTextureStageState、IDirect3DDevice8::SetTextureStageState


IDirect3DDevice8::GetTextureStageState

割り当てられているテクスチャのステート値を取得する。

HRESULT GetTextureStageState(
  DWORD Stage,
  D3DTEXTURESTAGESTATETYPE Type,
  DWORD* pValue
);

パラメータ

Stage
[in] ステートを取得する対象となるテクスチャのステージ識別子。ステージ識別子は 0 から始まる。デバイスは最大 8 セットまでテクスチャを持つことができるので、Stage に指定できる最大値は 7 である。
Type
[in] 取得するテクスチャのステート。このパラメータには、D3DTEXTURESTAGESTATETYPE 列挙型の任意のメンバを指定できる。
pValue
[out, retval] 取得したステート値を格納する変数へのポインタ。取得された値の意味は Type パラメータで決まる。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::SetTextureStageState、IDirect3DDevice8::GetTexture、IDirect3DDevice8::SetTexture


IDirect3DDevice8::GetTransform

トランスフォーム ステートを記述する行列を取得する。

HRESULT GetTransform(
  D3DTRANSFORMSTATETYPE State,
  D3DMATRIX* pMatrix
);

パラメータ

State
[in] 変更対象のデバイス ステート変数。このパラメータには、D3DTRANSFORMSTATETYPE 列挙型の任意のメンバまたは D3DTS_WORLDMATRIX マクロを指定できる。
pMatrix
[out] 返されるトランスフォーム ステートを表す D3DMATRIX 構造体へのポインタ。

戻り値

成功した場合は、D3D_OK を返す。

引数のいずれかが無効な場合は、D3DERR_INVALIDCALL になる。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::SetTransform


IDirect3DDevice8::GetVertexShader

現在設定されている頂点シェーダを取得する。

HRESULT GetVertexShader(
   DWORD* pHandle
);

パラメータ

pHandle
[out, retval] 返される頂点シェーダを表す頂点シェーダ ハンドルへのポインタ。

戻り値

成功した場合は、D3D_OK を返す。

pHandle が無効な場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::SetVertexShader


IDirect3DDevice8::GetVertexShaderConstant

頂点シェーダ定数配列中の値を取得する。

HRESULT GetVertexShaderConstant(
   DWORD Register,
   void* pConstantData,
   DWORD ConstantCount
);

パラメータ

Register
[in] 頂点シェーダ定数配列からのデータの取得を開始する位置のレジスタ アドレス。
pConstantData
[out] 頂点シェーダ定数配列から取得した値を格納するデータ ブロックへのポインタ。データ ブロックのサイズは、ConstantCount * 4 * sizeof(float) である。
ConstantCount
[in] 頂点シェーダ定数配列から取得取得する定数の数。各定数は、4 つの浮動小数点値から成る。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

このメソッドは、頂点シェーダ アセンブラの定数レジスタにある値を取得するために使用する。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::SetVertexShaderConstant


IDirect3DDevice8::GetVertexShaderDeclaration

頂点シェーダの宣言トークン配列を取得する。

HRESULT GetVertexShaderDeclaration(
   DWORD Handle,
   void* pData,
   DWORD* pSizeOfData
);

パラメータ

Handle
[in] 頂点シェーダを参照するハンドル。
pData
[in] それまで割り当てられていたバッファへのポインタ。呼び出しが成功した場合、要求した頂点シェーダ ハンドルに関連付けられている宣言が格納される。このメソッドを呼び出すアプリケーションは、このバッファの割り当てと解放に責任を負う。
pSizeOfData
[in, out] DWORD 値へのポインタ。pData のバッファ サイズをバイト単位で示す。この値が 0 などのように、実際のデータ サイズよりも小さい場合、メソッドはこのパラメータを必要なバッファ サイズに設定し、D3DERR_MOREDATA を返す。バッファが NULL の場合、このパラメータには必要なサイズが指定され、D3D_OK が返される。

戻り値

成功した場合は、D3D_OK を返す。

Handle が頂点シェーダへの無効なハンドルである場合は、D3DERR_INVALIDCALL を返す。

注意

頂点シェーダの宣言トークン配列ではシェーダへの入力が定義されており、入力データ ストリーム中の頂点要素をシェーダが使用する方法も含まれる。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::GetVertexShader


IDirect3DDevice8::GetVertexShaderFunction

頂点シェーダの機能を取得する。

HRESULT GetVertexShaderFunction(
   DWORD Handle,
   void* pData,
   DWORD* pSizeOfData
);

パラメータ

Handle
[in] 頂点シェーダを参照するハンドル。
pData
[out] それまで割り当てられていたバッファへのポインタ。呼び出しが成功した場合、要求した頂点シェーダ ハンドルに関連付けられているコードが格納される。このメソッドを呼び出すアプリケーションは、このバッファの割り当てと解放に責任を負う。
pSizeOfData
[in, out] DWORD 値へのポインタ。pData のバッファ サイズをバイト単位で示す。この値が 0 などのように、実際のデータ サイズよりも小さい場合、メソッドはこのパラメータを必要なバッファ サイズに設定し、D3DERR_MOREDATA を返す。バッファが NULL の場合、このパラメータには必要なサイズが指定され、D3D_OK が返される。

戻り値

成功した場合は、D3D_OK を返す。

Handle が頂点シェーダへの無効なハンドルである場合は、D3DERR_INVALIDCALL を返す。

注意

頂点シェーダの機能では、各頂点に適用される操作が定義されている。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::GetVertexShader


IDirect3DDevice8::GetViewport

デバイスに現在設定されているビューポート パラメータを取得する。

HRESULT GetViewport(
  D3DVIEWPORT8* pViewport
);

パラメータ

pViewport
[out] 返されるビューポート パラメータを表す D3DVIEWPORT8 構造体へのポインタ。

戻り値

成功した場合は、D3D_OK を返す。

pViewport パラメータが無効な場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::SetViewport


IDirect3DDevice8::LightEnable

デバイス内のライティング パラメータ セットを有効または無効にする。

HRESULT LightEnable(
  DWORD LightIndex,
  BOOL bEnable
);

パラメータ

LightIndex
[in] このメソッドの対象となるライティング パラメータ セットのゼロから始まるインデックス。
bEnable
[in] ライティング パラメータ セットが有効または無効のいずれであるかを示す値。このパラメータに TRUE を設定すると、指定されたインデックスのパラメータのライトが有効になり、FALSE を設定すると無効になる。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

デバイス内で割り当てられているライト プロパティ セットの範囲外の値を LightIndex に設定すると、LightEnable メソッドは D3DLIGHT8 構造体で表される光源を以下のプロパティで作成し、有効なステートを bEnable で指定された値に設定する。

メンバ | デフォルト
Type | D3DLIGHT_DIRECTIONAL
Diffuse | (R:1, G:1, B:1, A:0)
Specular | (R:0, G:0, B:0, A:0)
Ambient | (R:0, G:0, B:0, A:0)
Position | (0, 0, 0)
Direction | (0, 0, 1)
Range | 0
Falloff | 0
Attenuation0 | 0
Attenuation1 | 0
Attenuation2 | 0
Theta | 0
Phi | 0

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::GetLight、IDirect3DDevice8::GetLightEnable、IDirect3DDevice8::SetLight


IDirect3DDevice8::MultiplyTransform

デバイスのワールド行列、ビュー行列、または射影行列に、指定された行列を乗算する。

HRESULT MultiplyTransform(
  D3DTRANSFORMSTATETYPE State,
  CONST D3DMATRIX* pMatrix
);

パラメータ

State
[in] 変更するデバイス行列を指定する D3DTRANSFORMSTATETYPE 列挙型のメンバ、または D3DTS_WORLDMATRIX マクロ。最も一般的な設定は D3DTS_WORLDMATRIX(0) で、ワールド行列を変更するが、必要であれば、ビュー行列や射影行列を変更するように指定することもできる。
pMatrix
[in] 現在のトランスフォームを変更する D3DMATRIX 構造体へのポインタ。

戻り値

成功した場合は、D3D_OK を返す。

引数のいずれかが無効な場合は、D3DERR_INVALIDCALL になる。

注意

乗算の順序は、State × pMatrix である

アプリケーションが、トランスフォームの階層構造を使って動作するために、MultiplyTransform メソッドを使用することも考えられる。たとえば、腕を表すジオメトリとトランスフォームは、以下の階層で構成することもある。

shoulder_transformation
    upper_arm geometry
    elbow transformation
        lower_arm geometry
        wrist transformation
            hand geometry

アプリケーションでは、この階層をレンダリングするために以下の一連の呼び出しを行うことができる。このコードでは一部のパラメータのみ示す。

IDirect3DDevice8::SetTransform(D3DTS_WORLDMATRIX(0),
    shoulder_transform)
IDirect3DDevice8::DrawPrimitive(upper_arm)
IDirect3DDevice8::MultiplyTransform(D3DTS_WORLDMATRIX(0),
    elbow_transform)
IDirect3DDevice8::DrawPrimitive(lower_arm)
IDirect3DDevice8::MultiplyTransform(D3DTS_WORLDMATRIX(0),
    wrist_transform)
IDirect3DDevice8::DrawPrimitive(hand)

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::DrawPrimitive、IDirect3DDevice8::SetTransform、D3DTS_WORLD、D3DTS_WORLDn、D3DTS_WORLDMATRIX


IDirect3DDevice8::Present

デバイスが所有するバック バッファのシーケンスの中で次のコンテンツを提示する。

HRESULT Present(
  CONST RECT* pSourceRect,
  CONST RECT* pDestRect,
  HWND hDestWindowOverride,
  CONST RGNDATA* pDirtyRegion
);

パラメータ

pSourceRect
[in] スワップ チェーンが D3DSWAPEFFECT_COPY または D3DSWAPEFFECT_COPY_VSYNC で作成されている場合を除き、NULL を指定しなければならない値へのポインタ。pSourceRect は、転送元矩形を含む RECT 構造体へのポインタである。NULL の場合は、転送元サーフェス全体が表示される。矩形が転送元サーフェスを超えた場合、矩形は転送元サーフェスにクリッピングされる。
pDestRect
[in] スワップ チェーンが D3DSWAPEFFECT_COPY または D3DSWAPEFFECT_COPY_VSYNC で作成されていない限り、NULL を指定しなければならない値へのポインタ。PDestRect はウィンドウのクライアント座標に転送先矩形を含む RECT 構造体へのポインタである。NULL の場合は、クライアント領域全体が格納される。矩形が転送先のクライアント領域を越えた場合、矩形は転送先のクライアント領域にクリッピングされる。
hDestWindowOverride
[in] クライアント領域がこのプレゼンテーションの対象として扱われる転送先ウィンドウへのポインタ。このパラメータが NULL の場合は、D3DPRESENT_PARAMETERS の hWndDeviceWindow メンバが使用される。
pDirtyRegion
[in] このパラメータは未使用なため、NULL に設定する必要がある。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DERR_DEVICELOST

注意

必要に応じて、転送元矩形内のピクセルをターゲット ウィンドウのクライアント領域の転送先矩形に転送するために拡大処理が適用される。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::Reset


IDirect3DDevice8::ProcessVertices

頂点シェーダで定義されている頂点処理を一連の入力データ ストリームに適用し、インターリーブされた頂点データの単一ストリームを生成して転送先頂点バッファに格納する。

HRESULT ProcessVertices(
  UINT SrcStartIndex,
  UINT DestIndex,
  UINT VertexCount,
  IDirect3DVertexBuffer8* pDestBuffer,
  DWORD Flags
);

パラメータ

SrcStartIndex
[in] ロードする最初の頂点のインデックス。
DestIndex
[in] 結果を格納する転送先頂点バッファ内の最初の頂点のインデックス。
VertexCount
[in] 処理する頂点の数。
pDestBuffer
[in] IDirect3DVertexBuffer8 インターフェイスへのポインタ。インターリーブされた頂点データのストリームを表す転送先頂点バッファである。
Flags
[in] 処理オプション。デフォルト処理に対してはこのパラメータを 0 に設定する。D3DPV_DONOTCOPYDATA に設定すると、頂点の処理に無関係な頂点データをコピー先バッファにコピーするのを防ぐことができる。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

転送先頂点バッファ pDestBuffer は、ゼロ以外の FVF パラメータを指定して作成しなければならない。IDirect3DDevice8::CreateVertexBuffer メソッドの呼び出しにおいて指定する FVF コードは、転送先頂点バッファに格納される頂点要素を指定している。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

デバイスの種類と頂点処理の要件


IDirect3DDevice8::Reset

スワップ チェーンのタイプ、サイズ、およびフォーマットをリセットする。

HRESULT Reset(
  D3DPRESENT_PARAMETERS* pPresentationParameters
);

パラメータ

pPresentationParameters
[in] 新しいプレゼンテーション パラメータを記述する D3DPRESENT_PARAMETERS 構造体へのポインタ。この値は NULL にできない。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY
E_OUTOFMEMORY

注意

Reset の呼び出しが失敗すると、デバイスは "消失" 状態 (IDirect3DDevice::TestCooperativeLevel の呼び出しからの戻り値 D3DERR_DEVICELOST が示す) になる。ただし、デバイスが既に "非リセット" 状態 (IDirect3DDevice8::TestCooperativeLevel の呼び出しからの戻り値 D3DERR_DEVICENOTRESET が示す) の場合は除く。消失したデバイスのコンテキストにおける Reset の使い方の詳細については、「IDirect3DDevice8::TestCooperativeLevel」および「消失したデバイス」を参照すること。

リセットを呼び出すと、すべてのテクスチャ メモリ サーフェスが失われて、管理下のテクスチャがビデオ メモリからフラッシュされて、すべてのステート情報がクリアされる。デバイスに対して Reset メソッドを呼び出す前に、アプリケーションでは明示的なレンダリング ターゲット、深度ステンシル サーフェス、追加スワップ チェーン、およびデバイスに関連付けられている D3DPOOL_DEFAULT リソースを解放する必要がある。

スワップ チェーンのタイプには、フルスクリーンとウィンドウがある。新しいスワップ チェーンがフルスクリーンの場合、アダプタは新しいサイズに合ったディスプレイ モードに設定される。

DirectX 8.0 アプリケーションでは、この呼び出し中 (たとえば、この呼び出しが返る前) はアプリケーションにメッセージが送信されることを期待できる。アプリケーションは、このときに Direct3D を呼び出さないための警告を受け取る。また、Reset が失敗した場合、呼び出すことができる有効なメソッドは Reset、IDirect3DDevice8::TestCooperativeLevel、およびさまざまな Release メンバ関数だけである。その他のメソッドを呼び出すと、例外になる場合がある。

リセットするデバイスを作成したスレッドとは別のスレッドで Reset を呼び出すと、この呼び出しは失敗する。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

D3DSWAPEFFECT、D3DPRESENT_PARAMETERS、IDirect3DDevice8::Present


IDirect3DDevice8::ResourceManagerDiscardBytes

リソース マネージャを呼び出して、メモリを解放する。

HRESULT ResourceManagerDiscardBytes(
  DWORD Bytes
);

パラメータ

Bytes
[in] 破棄の対象となるバイト数。0 を指定すると、リソース マネージャは全バイトを破棄する。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

リソース マネージャは、目標のバイト数に達するまで、メモリ割り当ての解放を行う。リソース マネージャは、最低使用頻度方式 (LRU) の優先順位決定技法に従う。

解放されるバイト数が連続的であるとは保証されない。したがって、このメソッドを呼び出した後に、Bytes で指定されるバイト数のリソースを作成できない場合もある。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3DDevice8::SetClipPlane

デバイスのユーザー定義クリップ面の係数を設定する。

HRESULT SetClipPlane(
  DWORD Index,
  CONST float* pPlane
);

パラメータ

Index
[in] 平面方程式の係数を設定するクリップ面のインデックス。
pPlane
[in] 設定する一般平面方程式形式のクリップ面係数を表す値の、4 要素で構成される配列のアドレスへのポインタ。「注意」を参照すること。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。このエラーは、Index の値がデバイスでサポートされる最大クリップ面インデックスを超えているか、pPlane の配列が 4 つの浮動小数点値を格納するほど大きくないことを示す。

注意

このメソッドで設定する係数は、一般平面方程式の形をとる。pPlane の配列の値が配列内での順に A、B、C、および D とラベル付けされている場合、これらの値は一般平面方程式が Ax + By + Cz + Dw = 0 になるように適用される。Ax + By + Cz + Dw >= 0 である場合、同次座標 (x, y, z, w) のポイントは平面で切り取られた半分の空間に表示される。クリップ面上または背後に存在するポイントはシーンからクリッピングされる。

固定機能パイプラインが使用される場合、平面方程式はワールド空間にあると仮定される。プログラム可能なパイプラインが使用される場合、平面方程式はクリップ空間 (出力頂点と同じ空間) にあると仮定される。

このメソッドは、設定されたクリップ面の平面方程式を有効にはしない。クリップ面を有効にするには、D3DRS_CLIPPLANEENABLE レンダリング ステートに適用する DWORD 値の対応するビットを設定する。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::GetClipPlane


IDirect3DDevice8::SetClipStatus

クリップ ステータスを設定する。

HRESULT SetClipStatus(
  CONST D3DCLIPSTATUS8* pClipStatus
);

パラメータ

pClipStatus
[in] 設定するクリップ ステータスを記述する D3DCLIPSTATUS8 構造体へのポインタ。

戻り値

成功した場合は、D3D_OK を返す。

引数のいずれかが無効な場合は、D3DERR_INVALIDCALL になる。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::GetClipStatus


IDirect3DDevice8::SetCurrentTexturePalette

現在のテクスチャ パレットを設定する。

HRESULT SetCurrentTexturePalette(
  UINT PaletteNumber
);

パラメータ

PaletteNumber
[in] 現在のテクスチャ パレットとして設定するテクスチャ パレットを指定する値。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

単一の論理パレットがデバイスに関連付けられ、すべてのテクスチャ ステージで共有される。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::GetCurrentTexturePalette、テクスチャ パレット


IDirect3DDevice8::SetCursorPosition

カーソルの位置と更新オプションを設定する。

void SetCursorPosition(
  UINT XScreenSpace,
  UINT YScreenSpace,
  DWORD Flags
);

パラメータ

XScreenSpace
[in] スクリーン空間座標で表したカーソルの新しい x 位置。「注意」を参照すること。
YScreenSpace
[in] スクリーン空間座標で表したカーソルの新しい y 位置。「注意」を参照すること。
Flags
[in] カーソルの更新オプションを指定する。現在、定義されているフラグは 1 つだけである。
D3DCURSOR_IMMEDIATE_UPDATE
リフレッシュ レートでカーソルを更新する。

このフラグを指定した場合、システムは最低ディスプレイのリフレッシュ レートの半分の速度でカーソルを更新することを保証するが、ディスプレイのリフレッシュ レートより頻繁に更新することはない。このフラグを指定しない場合、このメソッドはカーソルの更新を次の IDirect3DDevice8::Present の呼び出しまで遅延させる。このデフォルトの動作は、通常、フラグを設定した場合よりもパフォーマンスが向上する。ただし、Present の呼び出しの頻度が高く、ユーザーがカーソルの動きに大きな遅延を感じるようであれば、アプリケーションでこのフラグを設定する必要がある。

戻り値

なし。

注意

フルスクリーン モードで実行している場合、スクリーン空間座標はバック バッファ座標に変換されて、現在のディスプレイ モードに合わせて適切にスケーリングされる。ウィンドウ モードで実行している場合は、スクリーン空間座標はデスクトップ座標に変換される。カーソル イメージは、指定した位置から IDirect3DDevice8::SetCursorProperties メソッドで指定されているホットスポット オフセットの値を引いた位置に描画される。

カーソルが IDirect3DDevice8::ShowCursor で隠されている場合、カーソルは描画されない。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::SetCursorProperties、IDirect3DDevice8::ShowCursor


IDirect3DDevice8::SetCursorProperties

カーソルのプロパティを設定する。

HRESULT SetCursorProperties(
  UINT XHotSpot,
  UINT YHotSpot,
  IDirect3DSurface8* pCursorBitmap
);

パラメータ

XHotSpot
[in] カーソルの左上角を基準としてカーソルの内部に向かう X 座標オフセット (ピクセル単位)。カーソルの中心と見なされる。カーソルが新しい位置に指定された場合、イメージは、この新しい位置からのオフセットに描かれる。この新しい位置は、その位置からホット スポットの座標を引くことによって決定された位置である。
YHotSpot
[in] カーソルの左上角を基準としてカーソルの内部に向かう Y 座標オフセット (ピクセル単位)。カーソルの中心と見なされる。カーソルが新しい位置に指定された場合、イメージは、この新しい位置からのオフセットに描かれる。この新しい位置は、その位置からホット スポットの座標を引くことによって決定された位置である。
pCursorBitmap
[in] IDirect3DSurface8 インターフェイスへのポインタ。このパラメータは、8888 ARGB サーフェス (フォーマットは D3DFORMAT_A8R8G8B8) をポイントしていなければならない。このサーフェスのコンテンツは、カーソルの表示に使われる内部バッファにコピーされて、同時にフォーマット変換が行われる場合がある。このサーフェスのディメンジョンはディスプレイ モードのディメンジョンより小さくなければならず、各方向とも 2 の累乗でなければならない。ただし、両方向が同じ大きさでなくてもかまわない。アルファ チャネルは、0.0 または 1.0 でなければならない。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

Microsoft® Direct3D® のカーソル関数では、ハードウェアに応じて、GDI カーソルまたはソフトウェア エミュレーションのいずれかを使用する。ユーザーは通常、WM_SETCURSOR メッセージに応じる。たとえば、ユーザーはメッセージ ハンドラを次のように記述できる。

case WM_SETCURSOR:
    // ウィンドウ カーソルをオフにする。
    SetCursor( NULL );
    m_pd3dDevice->ShowCursor( TRUE );
    return TRUE; // Windows がカーソルをウィンドウ クラス カーソルに設定しないようにする。
break;

また、カーソルを変更する場合は、ユーザーは IDirect3DDevice8::SetCursorProperties メソッドを呼び出すことができる。詳細については、Microsoft DirectX® Graphics C/C++ サンプルのサンプル コードを参照すること。

アプリケーションでは、D3DCAPS8 構造体の適切なメンバを調べることで、カーソルで利用可能なハードウェア サポートを確認できる。一般に、ハードウェアがサポートするのは 32 × 32 のカーソルだけである。さらに、ウィンドウ モードでは、システムがサポートできるのも 32 × 32 のカーソルだけである。その場合でも SetCursorProperties は成功するが、カーソルはこのサイズに縮小されて、ホットスポットは適切にスケーリングされる可能性がある。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::SetCursorPosition、IDirect3DDevice8::ShowCursor、D3DCAPS8


IDirect3DDevice8::SetGammaRamp

非明示的なスワップ チェーンのガンマ修正ランプを設定する。

void SetGammaRamp(
  DWORD Flags,
  CONST D3DGAMMARAMP* pRamp
);

パラメータ

Flags
[in] 修正を適用するかどうかを指定する。ガンマ修正を行うといっそう一貫性のある表示が得られるが、処理オーバーヘッドが発生する可能性があるので、頻繁に使用すべきではない。全画面を赤くフラッシュさせるような短時間のエフェクトは調整しない方がよいが、長時間のガンマ変化は調整する必要がある。次のフラグのいずれかを設定できる。
D3DSGR_CALIBRATE
ガンマ口径測定器がインストールされている場合は、システムおよびモニタの応答カーブに合わせて、デバイスに送信される前にランプが調整される。

口径測定器がインストールされていない場合は、ランプはデバイスに直接渡される。

D3DSGR_NO_CALIBRATION
ガンマ修正を適用しない。提供されているガンマ テーブルが、デバイスに直接転送される。
pRamp
[in] D3DGAMMARAMP 構造体へのポインタ。非明示的なスワップ チェーンに設定するガンマ修正ランプを示す。

戻り値

なし。

注意

Microsoft® Direct3D® for Microsoft DirectX 8.0® はデバイスのプロパティとして 1 つのスワップ チェーンを持っているため、各デバイスに対して、常に少なくても 1 つのスワップ チェーン (非明示的なスワップ チェーン) が存在する。

ガンマ ランプはスワップ チェーンのプロパティなので、スワップ チェーンをウィンドウ化するときは、ガンマ ランプを適用できる。

ガンマ ランプは直ちに有効になる。VSYNC の待機は発生しない。

デバイスがスワップ チェーンの現在のプレゼンテーション モード (フルスクリーンまたはウィンドウ) においてガンマ ランプをサポートしていない場合でも、エラーが返ることはない。アプリケーションでは、D3DCAPS8 構造体の Caps2 メンバの D3DCAPS2_FULLSCREENGAMMA 能力ビットおよび D3DCAPS2_CANCALIBRATEGAMMA 能力ビットを調べて、デバイスの能力および口径測定器がインストールされているかどうかを判断できる。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DSwapChain8、IDirect3DDevice8::GetGammaRamp


IDirect3DDevice8::SetIndices

インデックス データを設定する。

HRESULT SetIndices(
  IDirect3DIndexBuffer8* pIndexData
  UINT BaseVertexIndex
);

パラメータ

pIndexData
[in] 設定するインデックス データを表す IDirect3DIndexBuffer8 インターフェイスへのポインタ。
BaseVertexIndex
[in] 頂点インデックスのベース値。この値は、頂点データを参照する前にすべてのインデックスに追加され、頂点ストリームの開始位置を定義する。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

SetIndices メソッドは、インデックス バッファに現在のインデックス配列を設定する。単一のインデックス セットを使って、すべてのストリームにインデックスが付けられる。

BaseVertexIndex パラメータでは、インデックスに対するベース値を指定する。このベース値は、頂点データ ストリームを参照する前にすべてのインデックスに追加される。その結果、頂点データ ストリームの開始位置が設定される。ベースとなる頂点インデックスによって、頂点データ内に配置されている対応するプリミティブの場所に基づいてインデックスを再計算せずに、複数のインデックス付きプリミティブを単一の頂点データのセットにパックすることができる。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::GetIndices


IDirect3DDevice8::SetLight

このデバイスに一連のライト プロパティを割り当てる。

HRESULT SetLight(
  DWORD Index,
  CONST D3DLIGHT8* pLight
);

パラメータ

Index
[in] 設定するライト プロパティ セットのゼロから始まるインデックス。インデックスにライト プロパティ セットが存在する場合は、pLight で指定した新しいプロパティで上書きされる。
pLight
[in] 設定するライティング パラメータが格納されている D3DLIGHT8 構造体へのポインタ。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::GetLight、IDirect3DDevice8::GetLightEnable、IDirect3DDevice8::LightEnable


IDirect3DDevice8::SetMaterial

デバイスにマテリアル プロパティを設定する。

HRESULT SetMaterial(
   CONST D3DMATERIAL8* pMaterial
);

パラメータ

pMaterial
[in] 設定するマテリアル プロパティが記述されている D3DMATERIAL8 構造体へのポインタ。

戻り値

成功した場合は、D3D_OK を返す。

pMaterial パラメータが無効な場合は、D3DERR_INVALIDCALL になる。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::GetMaterial


IDirect3DDevice8::SetPaletteEntries

パレット エントリを設定する。

HRESULT SetPaletteEntries(
  UINT PaletteNumber,
  CONST PALETTEENTRY* pEntries
);

パラメータ

PaletteNumber
[in] 実行する処理の対象となる特定のパラメータを識別する序数値。
pEntries
[in] 設定するパレット エントリを表す PALETTEENTRY 構造体へのポインタ。pEntries がポイントする PALETTEENTRY 構造体の数は 256 であると仮定されている。「注意」を参照すること。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

単一の論理パレットがデバイスに関連付けられ、すべてのテクスチャ ステージで共有される。

PALETTEENTRY の詳細については、Microsoft® Platform Software Development Kit (SDK) を参照すること。Microsoft DirectX® 8.0 では、PALETTEENTRY 構造体の peFlags メンバは、Platform SDK に説明されているようには機能しない。peFlags メンバは、現在、8 ビット パレット化フォーマットのアルファ チャネルである。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::GetCurrentTexturePalette、IDirect3DDevice8::GetPaletteEntries、IDirect3DDevice8::SetCurrentTexturePalette、テクスチャ パレット


IDirect3DDevice8::SetPixelShader

以前作成したピクセル シェーダを現在のピクセル シェーダとして設定する。

HRESULT SetPixelShader(
  DWORD Handle
);

パラメータ

Handle
[in] 設定するピクセル シェーダを指定するピクセル シェーダへのハンドル。このパラメータの値として、IDirect3DDevice8::CreatePixelShader から返るハンドルを使用できる。

ハンドルが NULL の場合は、従来のピクセル パイプラインが使われる。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::GetPixelShader


IDirect3DDevice8::SetPixelShaderConstant

ピクセル定数配列に値を設定する。

HRESULT SetPixelShaderConstant(
  DWORD Register,
  CONST void* pConstantData,
  DWORD ConstantCount
);

パラメータ

Register
[in] ピクセル定数配列へのデータのロードを開始するレジスタ アドレス。
pConstantData
[in] ピクセル定数配列にロードする値が格納されているデータ ブロックへのポインタ。データ ブロックのサイズは、ConstantCount * 4 * sizeof(float) である。
ConstantCount
[in] ピクセル定数配列にロードする定数の数。各定数は、4 つの浮動小数点値から成る。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

このメソッドは、ピクセル シェーダ アセンブラの定数レジスタに値をロードするために使用する。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::GetPixelShaderConstant


IDirect3DDevice8::SetRenderState

単一デバイスのレンダリング ステート パラメータを設定する。

HRESULT SetRenderState(
  D3DRENDERSTATETYPE State,
  DWORD Value
);

パラメータ

State
[in] 変更対象のデバイス ステート変数。このパラメータには、D3DRENDERSTATETYPE 列挙型の任意のメンバを指定できる。
Value
[in] デバイスのレンダリング ステートに設定する新しい値。このパラメータの意味は、State の指定値に依存する。たとえば、State が D3DRS_SHADEMODE の場合、第 2 パラメータは D3DSHADEMODE 列挙型のメンバのいずれかになる。

戻り値

成功した場合は、D3D_OK を返す。

引数の 1 つが無効な場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::GetRenderState、IDirect3DDevice8::SetTransform


IDirect3DDevice8::SetRenderTarget

デバイスに新しいカラー バッファと深度バッファの一方または両方を設定する。

HRESULT SetRenderTarget(
  IDirect3DSurface8* pRenderTarget,
  IDirect3DSurface8* pNewZStencil
);

パラメータ

pRenderTarget
[in] 新しいカラー バッファへのポインタ。NULL の場合は、既存のカラー バッファがそのまま使われる。このパラメータが NULL でない場合は、新しいレンダリング ターゲットの参照カウントがインクリメントされる。デバイスには、常に、カラー バッファが関連付けられていなければならない。

新しいレンダリング ターゲットのサーフェスには、少なくとも D3DUSAGE_RENDERTARGET が指定されていなければならない。

pNewZStencil
[in] 新しい深度ステンシル バッファへのポインタ。既存の深度ステンシル バッファがある場合は、そのバッファが解放される。このパラメータが NULL でない場合は、新しい深度ステンシル バッファ サーフェスの参照カウントがインクリメントされる。IDirect3DDevice8::GetDepthStencilSurface の ppZStencilSurface パラメータを渡すと、深度バッファを変更しないでレンダリング ターゲットを変更できる。

新しい深度ステンシル サーフェスには、少なくとも D3DUSAGE_DEPTHSTENCIL と D3DPOOL_DEFAULT が指定されていなければならない。

戻り値

成功した場合は、D3D_OK を返す。

pRenderTarget または pNewZStencil が NULL 以外で無効な値の場合、あるいは新しい深度バッファが新しいカラー バッファまたは引き続き使われるカラー バッファより小さい場合は、D3DERR_INVALIDCALL を返す。

注意

このメソッドを使ってカラー バッファと深度ステンシル サーフェスを同じデバイスに関連付けることを、両者をペアにするという。

デバイスは、SetRenderTarget に NULL 以外のサーフェスが渡されるたびに、AddRef を呼び出す。その後、デバイスは以前に設定されているカラー バッファに対して Release を呼び出す。

SetRenderTarget を呼び出して以前の深度ステンシル サーフェスとデバイスの関連を切断した後でも、前の深度ステンシル サーフェスのコンテンツは保持される。そのサーフェスをデバイスと再び関連付けると、新しい深度ステンシル サーフェスとペアにされているカラー バッファのサイズとフォーマットが、深度ステンシル サーフェスと最後にペアになっていたカラー バッファと同じならば、サーフェスのコンテンツは変更されない。

このメソッドを呼び出すと、デバイスの現在のビューポートは、現在のレンダリング ターゲットのサイズにリセットされる。この処理は、Z バッファだけが変更されるかどうかに関係なく行われる。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::CreateDepthStencilSurface、IDirect3DDevice8::GetDepthStencilSurface


IDirect3DDevice8::SetStreamSource

頂点バッファをデバイスのデータ ストリームにバインドする。

HRESULT SetStreamSource(
  UINT StreamNumber,
  IDirect3DVertexBuffer8* pStreamData,
  UINT Stride
);

パラメータ

StreamNumber
[in] 0 からストリームの最大数 - 1 までの範囲のデータ ストリームを指定する。
pStreamData
[in] IDirect3DVertexBuffer8 インターフェイスへのポインタ。指定したデータ ストリームにバインドする頂点バッファを示す。
Stride
[in] コンポーネントのストライド (バイト単位)。「注意」を参照すること。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

このメソッドは、割り当てられるストリームの参照カウントをインクリメントする。テクスチャが不要になった場合は、該当するステージのテクスチャを NULL に設定しなければならない。これを行わなかった場合、サーフェスは解放されず、メモリ リークが発生する。

柔軟な頂点フォーマット (FVF) 頂点シェーダを使用する場合、SetStreamSource のストリーム頂点ストライドは、FVF から計算された頂点サイズと一致していなければならない。この宣言を使用する場合、SetStreamSource のストリーム頂点ストライドは、宣言から計算されたストリーム サイズ以上でなければならない。

SetStreamSource メソッドは、頂点バッファをデバイスのデータ ストリームにバインドする。詳細については、「ストリーム ソースの設定」を参照すること。

テクスチャが必要なくなったとき、適切なステージでそのテクスチャを NULL に設定すること。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::DrawIndexedPrimitive、IDirect3DDevice8::DrawIndexedPrimitiveUP、IDirect3DDevice8::DrawPrimitive、IDirect3DDevice8::DrawPrimitiveUP、IDirect3DDevice8::GetStreamSource


IDirect3DDevice8::SetTexture

テクスチャをデバイスのステージに割り当てる。

HRESULT SetTexture(
  DWORD Stage,
  IDirect3DBaseTexture8* pTexture
);

パラメータ

Stage
[in] テクスチャを設定するステージ識別子。ステージ識別子は 0 から始まる。デバイスは最大 8 セットまでテクスチャを持つことができるので、Stage に指定できる最大値は 7 である。
pTexture
[in] 設定するテクスチャを表す IDirect3DBaseTexture8 インターフェイスへのポインタ。ミップマップ テクスチャやキューブ テクスチャなどのように複雑なテクスチャの場合、このパラメータはトップレベルのサーフェスをポイントしていなければならない。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

このメソッドは、割り当てられているテクスチャ サーフェスの参照カウントをインクリメントし、以前に選択されたテクスチャがある場合にはその参照カウントをデクリメントする。テクスチャが不要になった場合は、該当するステージのテクスチャを NULL に設定しなければならない。この処理を行わないと、メモリ リークが発生する。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::GetTexture、IDirect3DDevice8::GetTextureStageState、IDirect3DDevice8::SetTextureStageState


IDirect3DDevice8::SetTextureStageState

現在割り当てられているテクスチャにステート値を設定する。

HRESULT SetTextureStageState(
  DWORD Stage,
  D3DTEXTURESTAGESTATETYPE Type,
  DWORD Value
);

パラメータ

Stage
[in] ステート値を設定するテクスチャのステージ識別子。ステージ識別子は 0 から始まる。デバイスは最大 8 セットまでテクスチャを持つことができるので、Stage に指定できる最大値は 7 である。
Type
[in] 設定するテクスチャのステート。このパラメータには、D3DTEXTURESTAGESTATETYPE 列挙型の任意のメンバを指定できる。
Value
[in] 設定するステート値。この値の意味は Type パラメータで決まる。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::GetTextureStageState、IDirect3DDevice8::GetTexture、IDirect3DDevice8::SetTexture


IDirect3DDevice8::SetTransform

単一デバイスのトランスフォーム関連ステートを設定する。

HRESULT SetTransform(
  D3DTRANSFORMSTATETYPE State,
  CONST D3DMATRIX* pMatrix
);

パラメータ

State
[in] 変更対象のデバイス ステート変数。このパラメータには、D3DTRANSFORMSTATETYPE 列挙型の任意のメンバまたは D3DTS_WORLDMATRIX マクロを指定できる。
pMatrix
[in] 現在のトランスフォームを変更する D3DMATRIX 構造体へのポインタ。

戻り値

成功した場合は、D3D_OK を返す。

引数の 1 つが無効な場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::GetTransform、IDirect3DDevice8::SetRenderState、D3DTS_WORLD、D3DTS_WORLDn、D3DTS_WORLDMATRIX


IDirect3DDevice8::SetVertexShader

以前に作成した頂点シェーダ、または柔軟な頂点フォーマット (FVF) の固定機能シェーダに、現在の頂点シェーダを設定する。

HRESULT SetVertexShader(
  DWORD Handle
);

パラメータ

Handle
[in] 設定する頂点シェーダを指定する頂点シェーダへのハンドル。このパラメータの値として、IDirect3DDevice8::CreateVertexShader から返るハンドルまたは FVF コードを使用できる。FVF コードは柔軟な頂点フォーマット フラグの組み合わせである。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

ハンドルとして FVF コードを使用すると、固定機能の頂点シェーダが有効になり、ストリーム ゼロから読み込まれる FVF コードのコンテンツと一致する非明示的な宣言が使われる。FVF 指定のシェーダをデバイスにバインドすると、ストリーム ゼロだけが参照される。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::GetVertexShader


IDirect3DDevice8::SetVertexShaderConstant

頂点定数配列に値を設定する。

HRESULT SetVertexShaderConstant(
  DWORD Register,
  CONST void* pConstantData,
  DWORD  ConstantCount
);

パラメータ

Register
[in] 頂点定数配列へのデータのロードを開始するレジスタ アドレス。
pConstantData
[in] 頂点定数配列にロードする値が格納されているデータ ブロックへのポインタ。データ ブロックのサイズは、ConstantCount * 4 * sizeof(float) である。
ConstantCount
[in] 頂点定数配列にロードする定数の数。各定数は、4 つの浮動小数点値から成る。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

このメソッドは、頂点シェーダ アセンブラの定数レジスタに値をロードするために使用する。トランスフォーム行列をロードするときは、アプリケーションはその行と列を転置してから、連続した定数レジスタにロードする必要がある。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::GetVertexShaderConstant


IDirect3DDevice8::SetViewport

デバイスにビューポート パラメータを設定する。

HRESULT SetViewport(
  CONST D3DVIEWPORT8* pViewport
);

パラメータ

pViewport
[in] 設定するビューポート パラメータを示す D3DVIEWPORT8 構造体へのポインタ。

戻り値

成功した場合は、D3D_OK を返す。

pViewport パラメータが無効な場合は、D3DERR_INVALIDCALL になる。

D3DVIEWPORT8 構造体で記述するビューポート パラメータが、レンダリング ターゲット サーフェス内に存在できない領域を記述している場合、メソッドは失敗し、D3DERR_INVALIDCALL を返す。

注意

IDirect3DDevice8::BeginScene と IDirect3DDevice8::EndScene の間での SetViewPort の呼び出しは、ジオメトリを描画する前に行わなければならない。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::GetViewport


IDirect3DDevice8::ShowCursor

カーソルを表示または隠蔽する。

BOOL ShowCursor(
  BOOL bShow
);

パラメータ

bShow
[in] TRUE を指定すると、カーソルが表示される。FALSE を指定すると、カーソルが隠蔽される。

戻り値

呼び出し前にカーソルが表示されていたかどうかを示す値。カーソルが表示されていた場合は TRUE 、カーソルが表示されていなかった場合は FALSE を返す。

注意

Microsoft® Direct3D® のカーソル関数では、ハードウェアに応じて、GDI カーソルまたはソフトウェア エミュレーションのいずれかを使用する。ユーザーは通常、WM_SETCURSOR メッセージに応じる。たとえば、ユーザーはメッセージ ハンドラを次のように記述できる。

case WM_SETCURSOR:
    // ウィンドウ カーソルをオフにする。
    SetCursor( NULL );
    m_pd3dDevice->ShowCursor( TRUE );
    return TRUE; // Windows がカーソルをウィンドウ クラス カーソルに設定しないようにする。
break;

また、カーソルを変更する場合は、ユーザーは IDirect3DDevice8::SetCursorProperties メソッドを呼び出すことができる。詳細については、Microsoft DirectX® Graphics C/C++ サンプルのサンプル コードを参照すること。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::SetCursorPosition、IDirect3DDevice8::SetCursorProperties


IDirect3DDevice8::TestCooperativeLevel

ウィンドウ アプリケーションまたはフルスクリーン アプリケーションに対する Microsoft® Direct3D® デバイスの現在の協調レベル ステータスを報告する。

HRESULT TestCooperativeLevel();

パラメータ

なし。

戻り値

成功した場合は、D3D_OK を返す。この戻り値は、デバイスが動作しており、呼び出し側アプリケーションが続行できることを示す。

失敗した場合は、次のいずれかの値を返す (「注意」を参照)。

D3DERR_DEVICELOST
D3DERR_DEVICENOTRESET

注意

デバイスが失われたにもかかわらず、現時点で復元できない場合、IDirect3DDevice8::TestCooperativeLevel は D3DERR_DEVICELOST 戻りコードを返す。たとえば、フルスクリーン デバイスがフォーカスを失ったような場合である。アプリケーションで消失したデバイスを検出した場合、アプリケーションは中断して TestCooperativeLevel を定期的に呼び出し、戻り値 D3DERR_DEVICENOTRESET を受け取るまで待機する必要がある。その後で、IDirect3DDevice8::Reset を呼び出してデバイスをリセットする。これに成功した場合は、必要なリソースを復元し、通常の処理を再開する。デバイスの状態が "消失" または "非リセット" のいずれかの場合は、IDirect3DDevice8::Present は D3DERR_DEVICELOST を返すことに注意する。

リセットするデバイスを作成したスレッドとは別のスレッドで呼び出すと、TestCooperative Level の呼び出しは失敗する。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3DDevice8::UpdateTexture

テクスチャのダーティー部分を更新する。

HRESULT UpdateTexture(
  IDirect3DBaseTexture8* pSourceTexture,
  IDirect3DBaseTexture8* pDestinationTexture
);

パラメータ

pSourceTexture
[in] 転送元テクスチャを表す IDirect3DBaseTexture8 インターフェイスへのポインタ。転送元テクスチャはシステム メモリ内 (D3DPOOL_SYSTEMMEM) になければならない。
pDestinationTexture
[in] 転送先テクスチャを表す IDirect3DBaseTexture8 インターフェイスへのポインタ。転送先テクスチャは D3DPOOL_DEFAULT メモリ プールになければならない。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

テクスチャの一部分をダーティーにするには、その部分をロックするか、または次のいずれかのメソッドを呼び出す。

  • IDirect3DCubeTexture8::AddDirtyRect
  • IDirect3DTexture8::AddDirtyRect
  • IDirect3DVolumeTexture8::AddDirtyBox
  • IDirect3DDevice8::CopyRects

UpdateTexture は、最後の更新操作以降に累積された操作を計算することで、テクスチャのダーティー部分を取得する。

転送元と転送先のテクスチャのタイプが異なる場合、両方のテクスチャの最下位バッファのサイズが異なる場合、および一致レベルが一致しない場合、このメソッドは失敗する。たとえば、次のようなディメンジョンの 6 つのレベルの転送元テクスチャがあるとする。

32x16, 16x8, 8x4, 4x2, 2x1, 1x1

この 6 つのレベルの転送元テクスチャは、次の 1 つのレベルの転送先の転送元になる。

1x1

2 つのレベルの転送先の場合。

2x1, 1x1

または、4 つのレベルの転送先の場合。

4x2, 2x1, 1x1

また、テクスチャのフォーマットが異なる場合、このメソッドは失敗する。転送先テクスチャのレベル数が転送元より少ない場合は、一致するレベルだけがコピーされる。

転送元テクスチャにダーティー領域がある場合は、コピーをその領域だけに限定することで、コピー処理を最適化できる。ダーティーとしてマークされているバイトだけがコピーされるという保証はない。

パフォーマンスの理由によって、ダーティーな範囲はテクスチャのレベルゼロに対して記録されるのみである。サブレベルについては、対応する ( スケールされた ) 矩形、またはボックスもダーティーであると仮定される。D3DLOCK_NO_DIRTY_UPDATE または D3DLOCK_READONLY なしで LockRect か LockBox が呼び出されたとき、ダーティーな範囲は自動的に記録される。また CopyRects 呼び出しの宛先サーフェイスはダーティーとしてマークされる。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3D8::CreateDevice


IDirect3DDevice8::ValidateDevice

現在のテクスチャのブレンディング処理と引数をデバイスが 1 回の処理でレンダリングできる能力を報告する。

HRESULT ValidateDevice(
  DWORD* pNumPasses
);

パラメータ

pNumPasses
[out, retval] マルチパス レンダリングによって目的のエフェクトを完成するために必要なレンダリング パスの数を格納する DWORD 値へのポインタ。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_CONFLICTINGTEXTUREFILTER
D3DERR_CONFLICTINGTEXTUREPALETTE
D3DERR_TOOMANYOPERATIONS
D3DERR_UNSUPPORTEDALPHAARG
D3DERR_UNSUPPORTEDALPHAOPERATION
D3DERR_UNSUPPORTEDCOLORARG
D3DERR_UNSUPPORTEDCOLOROPERATION
D3DERR_UNSUPPORTEDFACTORVALUE
D3DERR_UNSUPPORTEDTEXTUREFILTER
D3DERR_WRONGTEXTUREFORMAT

注意

ValidateDevice メソッドは、ほかの能力が付属しているシナリオを検証する場合にのみ使用しなければならない。たとえば、マルチステージ テクスチャリングのシナリオでは、D3DCAPS8 構造体の MaxTextureBlendStages メンバと MaxSimultaneousTextures メンバを調べることで、そのデバイスでマルチステージ テクスチャリングが可能かどうかを判断できる。

現在のハードウェアが、必ずしも操作と引数の可能なすべての組み合わせを実装している必要はない。与えられた引数で特定のブレンディング処理を実行できるかどうかは、目的のブレンディング処理を設定し、ValidateDevice メソッドを呼び出すことにより確認できる。

ValidateDevice メソッドは、現在のレンダリング ステート、テクスチャ、テクスチャ ステージのステートを使って、呼び出された時点での確認を行う。この呼び出しの後でこれらの要素に変更があると、それまでの確認結果は無効になるので、シーンのレンダリングをする前にこのメソッドを再度呼び出さなければならない。

ディフューズ補間値の引数または操作 (D3DTA_DIFFUSE または D3DTOP_BLENDDIFFUSEALPHA) としての使用は、現在のハードウェアではほとんどサポートされていない。ほとんどのハードウェアでは、直前のテクスチャ処理ステージにおいて補間色データの値を導入している程度である。

各ステージのテクスチャ (D3DTA_TEXTURE) は、第 2 引数ではなく第 1 引数として指定するようにする。

多くのカードは、任意のテクスチャ ステージにおけるディフューズ値やスカラー値の使用はサポートしていない。これらは、最初または最後のテクスチャ ブレンディング ステージでのみ使用できることが多い。

最初のテクスチャに関連付けられたブレンディング ユニットで、アルファ チャネルからカラー チャネルへの複製や入力反転など以上の能力を持つものを備えたカードは少ない。したがって、アプリケーションでは、可能な場合、2 つ目のテクスチャ ステージのみ使用しなければならないときがある。このようなハードウェアでは、最初のユニットはデフォルト ステートにあると仮定され、D3DTOP_SELECTARG1 処理における第 1 カラー引数には D3DTA_TEXTURE が設定される。

出力されるアルファ値に対する操作で、カラー処理より複雑なもの、またはカラー処理と本質的に異なるものをサポートするハードウェアは、さらに少ない。

ハードウェアによっては、D3DTA_TFACTOR と D3DTA_DIFFUSE の同時使用をサポートしていない場合もある。

また多くのカードは、マルチテクスチャとミップマップ トライリニア フィルタリングの同時使用をサポートしていない。マルチ テクスチャ ブレンディング処理におけるテクスチャに対してトライリニア フィルタリングが要求された場合、妥当性検証が失敗すると、トライリニア フィルタリングはオフになり再検証が行われる。このような場合には、代わりにマルチパス レンダリングを実行することができる。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::GetTextureStageState、IDirect3DDevice8::SetTextureStageState


IDirect3DIndexBuffer8

インデックス バッファ リソースを操作するには、IDirect3DIndexBuffer8 インターフェイスのメソッドを使用する。

IDirect3DIndexBuffer8 インターフェイスを取得するには、IDirect3DDevice8::CreateIndexBuffer メソッドを呼び出す。

IDirect3DIndexBuffer8 インターフェイスは、次のようなグループに分類できる IDirect3DResource8 メソッドを継承する。

デバイス | GetDevice
情報 | GetType
プライベート サーフェス データ | FreePrivateData
 | GetPrivateData
 | SetPrivateData
リソース管理 | GetPriority
 | PreLoad
 | SetPriority

IDirect3DIndexBuffer8 インターフェイスのメソッドは、以下のグループにまとめることができる。

情報 | GetDesc
ロック | Lock
 | Unlock

すべての COM インターフェイスと同様、IDirect3DIndexBuffer8 インターフェイスは IUnknown インターフェイスのメソッドを継承する。IUnknown インターフェイスは、次の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECT3DINDEXBUFFER8 および PDIRECT3DINDEXBUFFER8 型は、IDirect3DIndexBuffer8 インターフェイスへのポインタとして定義される。

typedef struct IDirect3DIndexBuffer8 *LPDIRECT3DINDEXBUFFER8, *PDIRECT3DINDEXBUFFER8;

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::CreateIndexBuffer


IDirect3DIndexBuffer8::GetDesc

インデックス バッファ リソースの記述を取得する。

HRESULT GetDesc(
  D3DINDEXBUFFER_DESC* pDesc
);

パラメータ

pDesc
[out] 返されるインデックス バッファを記述している D3DINDEXBUFFER_DESC 構造体へのポインタ。

戻り値

成功した場合は、D3D_OK を返す。

この引数が無効な場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3DIndexBuffer8::Lock

インデックス データの範囲をロックし、インデックス バッファ メモリへのポインタを取得する。

HRESULT Lock(
  UINT OffsetToLock,
  UINT SizeToLock,
  BYTE** ppbData,
  DWORD Flags
);

パラメータ

OffsetToLock
[in] ロックするインデックス データへのオフセット (バイト単位)。
SizeToLock
[in] ロックするインデックス データのサイズ (バイト単位)。
ppbData
[out] 返されるインデックス データが格納される BYTE 値配列へのポインタのアドレス。
Flags
[in] 0 個以上のロッキング フラグの組み合わせ。インデックス バッファ メモリをロックする方法を示す。
D3DLOCK_DISCARD
アプリケーションは、書き込み専用処理でインデックス バッファ全体を上書きする。これにより、Direct3D は新しいメモリ領域へのポインタを返すことができるので、ダイナミック メモリ アクセス (DMA) と古い領域からのレンダリングが機能停止することはない。
D3DLOCK_NOOVERWRITE
フレームの開始以降、またはこのフラグが指定されていない最後のロック以降に描画処理の呼び出しの中で参照されたインデックスは、ロック中に変更されないことを示す。インデックス バッファへのデータの追加だけを行う場合は、このフラグにより処理を最適化できる。
D3DLOCK_NOSYSLOCK
ビデオ メモリ ロックのデフォルトの動作は、システムのクリティカル セクションを確保することで、ロック中にディスプレイ モードの変更が行われないことを保証する。このフラグは、システムワイドなクリティカル セクションがロックの間保持されないようにする。

ロック処理は若干負荷が高くなるが、マウス カーソルの移動など、システムでほかの処理を実行することが可能になる。このフラグは、ソフトウェア レンダリングのバックバッファのロックのように、ロックが長時間に及び、システムの応答性に悪影響を与えてしまうようなロックに対して有効である。

D3DLOCK_READONLY
アプリケーションはバッファに書き込みを行わない。これにより、いくらかの最適化が実現する。D3DLOCK_READONLY は D3DLOCK_DISCARD と共に指定することはできない。また、D3DUSAGE_WRITEONLY で作成された頂点バッファに指定することもできない。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

インデックス バッファの処理では、ロックの呼び出しを複数回行える。ただし、ロックの呼び出し回数とアンロックの呼び出し回数が一致している必要がある。現在設定しているインデックス バッファでロック カウントが残っている場合、DrawPrimitive の呼び出しは失敗する。

D3DLOCK_DISCARD および D3DLOCK_NOOVERWRITE フラグは、D3DUSAGE_DYNAMIC で作成されたバッファに対してのみ有効である。

D3DLOCK_DISCARD または D3DLOCK_NOOVERWRITE を Lock メソッドの Flags パラメータで使用する方法については、「動的な頂点およびインデックス バッファの使い方」を参照すること。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DIndexBuffer8::Unlock


IDirect3DIndexBuffer8::Unlock

インデックス データをアンロックする。

HRESULT Unlock();

パラメータ

なし。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DIndexBuffer8::Lock


IDirect3DResource8

リソースの照会および準備を行うには、IDirect3DResource8 インターフェイスのメソッドを使用する。

次のいずれかのメソッドを呼び出すことで、テクスチャ リソースを作成できる。

  • IDirect3DDevice8::CreateCubeTexture
  • IDirect3DDevice8::CreateTexture
  • IDirect3DDevice8::CreateVolumeTexture

次のいずれかのメソッドを呼び出すことで、ジオメトリ指向のリソースを作成できる。

  • IDirect3DDevice8::CreateIndexBuffer
  • IDirect3DDevice8::CreateVertexBuffer

IDirect3DResource8 インターフェイスのメソッドは、以下のグループにまとめることができる。

デバイス | GetDevice
情報 | GetType
プライベート サーフェス データ | FreePrivateData
 | GetPrivateData
 | SetPrivateData
リソース管理 | GetPriority
 | PreLoad
 | SetPriority

すべての COM インターフェイスと同様、IDirect3DResource8 インターフェイスは IUnknown インターフェイスのメソッドを継承する。IUnknown インターフェイスは、次の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECT3DRESOURCE8 および PDIRECT3DRESOURCE8 型は、IDirect3DResource8 インターフェイスへのポインタとして定義される。

typedef struct IDirect3DResource8 *LPDIRECT3DRESOURCE8, *PDIRECT3DRESOURCE8;

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3DResource8::FreePrivateData

このリソースに関連付けられている指定されたプライベート データを解放する。

HRESULT FreePrivateData(
  REFGUID refguid
);

パラメータ

refguid
[in] 解放するプライベート データを識別するグローバル ユニーク識別子への参照 (C++) またはアドレス (C)。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DERR_NOTFOUND

対象

このメソッドは、次のインターフェイス (IDirect3DResource8 から継承) に適用される。

  • IDirect3DBaseTexture8
  • IDirect3DCubeTexture8
  • IDirect3DIndexBuffer8
  • IDirect3DTexture8
  • IDirect3DVertexBuffer8
  • IDirect3DVolumeTexture8

注意

Microsoft® Direct3D® は、リソースが解放されると自動的にこのメソッドを呼び出す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DResource8::GetPrivateData、IDirect3DResource8::SetPrivateData


IDirect3DResource8::GetDevice

リソースに関連付けられているデバイスを取得する。

HRESULT GetDevice(
  IDirect3DDevice8** ppDevice
);

パラメータ

ppDevice
[out, retval] 照会が成功した場合に、デバイスのポインタが格納される IDirect3DDevice8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

対象

このメソッドは、次のインターフェイス (IDirect3DResource8 から継承) に適用される。

  • IDirect3DBaseTexture8
  • IDirect3DCubeTexture8
  • IDirect3DIndexBuffer8
  • IDirect3DTexture8
  • IDirect3DVertexBuffer8
  • IDirect3DVolumeTexture8

注意

このメソッドを使用すると、所有しているデバイス オブジェクトに移動することができる。

注 このメソッドを呼び出すと、IDirect3DDevice8 インターフェイスについての内部参照カウントが増加する。この IDirect3DDevice8 インターフェイスの使用を終了したときに IUnknown::Release の呼び出しが失敗すると、メモリ リークが発生する。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3DResource8::GetPriority

このリソースに対する優先順位を取得する。

DWORD GetPriority();

パラメータ

なし。

戻り値

リソースの優先順位を示す DWORD 値を返す。

対象

このメソッドは、次のインターフェイス (IDirect3DResource8 から継承) に適用される。

  • IDirect3DBaseTexture8
  • IDirect3DCubeTexture8
  • IDirect3DIndexBuffer8
  • IDirect3DTexture8
  • IDirect3DVertexBuffer8
  • IDirect3DVolumeTexture8

注意

GetPriority を使って、管理下のリソースの優先順位を制御する。管理下にないリソースに対しては 0 が返る。

優先順位を使用して、管理下のリソースをメモリからいつ削除するかを決定できる。優先順位が低いリソースは、優先順位が高いリソースより先に削除される。2 つのリソースの優先順位が同じ場合は、最終使用時が新しい方のリソースがメモリに保持され、もう一方のリソースが削除される。管理下のリソースのデフォルトの優先順位は 0 である。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DResource8::SetPriority


IDirect3DResource8::GetPrivateData

リソースに関連付けられたプライベート データを提供されたバッファにコピーする。

HRESULT GetPrivateData(
  REFGUID refguid,
  void* pData,
  DWORD* pSizeOfData
);

パラメータ

refguid
[in] 取得するプライベート データを識別するグローバル ユニーク識別子への参照 (C++) またはアドレス (C)。
pData
[out] 呼び出しが成功した場合に、要求したプライベート データを格納する割り当て済みバッファへのポインタ。このメソッドを呼び出すアプリケーションは、このバッファの割り当てと解放に責任を負う。
pSizeOfData
[in, out] pData のバッファ サイズ (バイト単位) へのポインタ。この値が実際のプライベート データのサイズより小さい (0 など) 場合、メソッドは必要なバッファ サイズをこのパラメータに設定し、D3DERR_MOREDATA を返す。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DERR_MOREDATA
D3DERR_NOTFOUND

対象

このメソッドは、次のインターフェイス (IDirect3DResource8 から継承) に適用される。

  • IDirect3DBaseTexture8
  • IDirect3DCubeTexture8
  • IDirect3DIndexBuffer8
  • IDirect3DTexture8
  • IDirect3DVertexBuffer8
  • IDirect3DVolumeTexture8

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DResource8::FreePrivateData、IDirect3DResource8::SetPrivateData


IDirect3DResource8::GetType

リソースのタイプを返す。

D3DRESOURCETYPE GetType();

パラメータ

なし。

戻り値

リソースのタイプを示す D3DRESOURCETYPE 列挙型のメンバを返す。

対象

このメソッドは、次のインターフェイス (IDirect3DResource8 から継承) に適用される。

  • IDirect3DBaseTexture8
  • IDirect3DCubeTexture8
  • IDirect3DIndexBuffer8
  • IDirect3DTexture8
  • IDirect3DVertexBuffer8
  • IDirect3DVolumeTexture8

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3DResource8::PreLoad

管理下のリソースをプリロードする。

void PreLoad();

パラメータ

なし。

戻り値

なし。

対象

このメソッドは、次のインターフェイス (IDirect3DResource8 から継承) に適用される。

  • IDirect3DBaseTexture8
  • IDirect3DCubeTexture8
  • IDirect3DIndexBuffer8
  • IDirect3DTexture8
  • IDirect3DVertexBuffer8
  • IDirect3DVolumeTexture8

注意

このメソッドを呼び出すことは、この管理下のリソースがアプリケーションにおいて間もなく必要になることを意味する。管理下にないリソースに対してはどのような影響も及ぼさない。

PreLoad は、各フレームで使用するリソースが、ビデオ メモリ内に同時に収容できる量を超えている "スラッシング" 状態を検出する。そのような状況下では、Preload は何も処理を行わない。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3DResource8::SetPriority

このリソースにリソース管理の優先順位を割り当てる。

DWORD SetPriority(
  DWORD PriorityNew
);

パラメータ

PriorityNew
[in] リソースに対する新しいリソース管理優先順位を示す DWORD 値。

戻り値

以前リソースに割り当てられていた優先順位の値を返す。

対象

このメソッドは、次のインターフェイス (IDirect3DResource8 から継承) に適用される。

  • IDirect3DBaseTexture8
  • IDirect3DCubeTexture8
  • IDirect3DIndexBuffer8
  • IDirect3DTexture8
  • IDirect3DVertexBuffer8
  • IDirect3DVolumeTexture8

注意

SetPriority を使って、管理下のリソースの優先順位を制御する。管理下にないリソースに対しては 0 が返る。

優先順位を使用して、管理下のリソースをメモリからいつ削除するかを決定できる。優先順位が低いリソースは、優先順位が高いリソースより先に削除される。2 つのリソースの優先順位が同じ場合は、最終使用時が新しい方のリソースがメモリに保持され、もう一方のリソースが削除される。管理下のリソースのデフォルトの優先順位は 0 である。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DResource8::GetPriority


IDirect3DResource8::SetPrivateData

Microsoft® Direct3D® ではなく、アプリケーションでの使用が意図されているリソースとデータを関連付ける。データは値で渡され、複数のデータ セットを単一のリソースと関連付けることができる。

HRESULT SetPrivateData(
  REFGUID refguid,
  CONST void* pData,
  DWORD SizeOfData,
  DWORD Flags
);

パラメータ

refguid
[in] 設定するプライベート データを識別するグローバル ユニーク識別子への参照 (C++) またはアドレス (C)。
pData
[in] リソースに関連付けるデータが格納されているバッファへのポインタ。
SizeOfData
[in] pData のバッファ サイズ (バイト単位)。
Flags
[in] 渡されるデータ型を記述する値、またはリソースが変更された場合にデータを無効にする必要があることをアプリケーションに示す値。
(none)
フラグを指定しない場合、Direct3D® はバッファ内のデータを保持するメモリを割り当て、新しいバッファにデータをコピーする。Direct3D によって割り当てられるバッファは、適宜自動的に解放される。
D3DSPD_IUNKNOWN
pData のデータは IUnknown インターフェイスへのポインタである。SizeOfData は、IUnknown インターフェイス (sizeof(IUnknown*)) へのポインタのサイズに設定する必要がある。Direct3D は pData を介して IUnknown::AddRef を、プライベート データが破棄される場合は IUnknown::Release を自動的に呼び出す。次に同じ GUID で SetPrivateData を呼び出すと、または次に IDirect3DResource8::FreePrivateData を呼び出すと、または Direct3D8 オブジェクトが解放されると、プライベート データは破棄される。詳細については、「注意」を参照すること。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

対象

このメソッドは、次のインターフェイス (IDirect3DResource8 から継承) に適用される。

  • IDirect3DBaseTexture8
  • IDirect3DCubeTexture8
  • IDirect3DIndexBuffer8
  • IDirect3DTexture8
  • IDirect3DVertexBuffer8
  • IDirect3DVolumeTexture8

注意

Direct3D は pData でメモリを管理しない。このバッファが動的に割り当てられた場合は、呼び出し側の責任でメモリを解放する。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DResource8::FreePrivateData、IDirect3DResource8::GetPrivateData


IDirect3DSurface8

サーフェスの照会および準備を行うには、IDirect3DSurface8 インターフェイスのメソッドを使用する。

IDirect3DSurface8 インターフェイスのメソッドは、以下のグループにまとめることができる。

デバイス | GetDevice
情報 | GetContainer
 | GetDesc
サーフェスのロック | LockRect
 | UnlockRect
プライベート サーフェス データ | FreePrivateData
 | GetPrivateData
 | SetPrivateData

すべての COM インターフェイスと同様、IDirect3DSurface8 インターフェイスは IUnknown インターフェイスのメソッドを継承する。IUnknown インターフェイスは、次の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECT3DSURFACE8 および PDIRECT3DSURFACE8 型は、IDirect3DSurface8 インターフェイスへのポインタとして定義される。

typedef struct IDirect3DSurface8 *LPDIRECT3DSURFACE8, *PDIRECT3DSURFACE8;

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

サーフェス インターフェイス


IDirect3DSurface8::FreePrivateData

このサーフェスに関連付けられている指定されたプライベート データを解放する。

HRESULT FreePrivateData(
  REFGUID refguid
);

パラメータ

refguid
[in] 解放するプライベート データを識別するグローバル ユニーク識別子への参照 (C++) またはアドレス (C)。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DERR_NOTFOUND

注意

Microsoft® Direct3D® は、サーフェスが解放されると自動的にこのメソッドを呼び出す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DSurface8::GetPrivateData、IDirect3DSurface8::SetPrivateData


IDirect3DSurface8::GetContainer

このサーフェスがキューブ テクスチャまたはミップマップの子レベルである場合、親のキューブ テクスチャまたはテクスチャ (ミップマップ) オブジェクトへのアクセスを提供する。

HRESULT GetContainer(
  REFIID riid
  void** ppContainer
);

パラメータ

riid
[in] 要求するコンテナの参照識別子。
ppContainer
[out] 照会が成功した場合にコンテナ ポインタが格納されるポインタのアドレス。「注意」を参照すること。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

サーフェスが IDirect3DDevice8::CreateImageSurface、IDirect3DDevice8::CreateRenderTarget、または IDirect3DDevice8::CreateDepthStencilSurface を使って作成されている場合、サーフェスはスタンド アロンであると見なされる。この場合、GetContainer は、サーフェスの作成に使用した Direct3D デバイスを返す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3DSurface8::GetDevice

サーフェスに関連付けられているデバイスを取得する。

HRESULT GetDevice(
  IDirect3DDevice8** ppDevice
);

パラメータ

ppDevice
[out, retval] 照会が成功した場合に、デバイスのポインタが格納される IDirect3DDevice8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

このメソッドを使用すると、所有しているデバイス オブジェクトに移動することができる。

注 このメソッドを呼び出すと、IDirect3DDevice8 インターフェイスについての内部参照カウントが増加する。この IDirect3DDevice8 インターフェイスの使用を終了したときに IUnknown::Release の呼び出しが失敗すると、メモリ リークが発生する。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3DSurface8::GetPrivateData

サーフェスに関連付けられたプライベート データを提供されたバッファにコピーする。

HRESULT GetPrivateData(
  REFGUID refguid,
  void* pData,
  DWORD* pSizeOfData
);

パラメータ

refguid
[in] 取得するプライベート データを識別するグローバル ユニーク識別子への参照 (C++) またはアドレス (C)。
pData
[in, out] 呼び出しが成功した場合に、要求したプライベート データを格納する割り当て済みバッファへのポインタ。このメソッドを呼び出すアプリケーションは、このバッファの割り当てと解放に責任を負う。
pSizeOfData
[in, out] pData のバッファ サイズ (バイト単位) へのポインタ。この値が実際のプライベート データのサイズより小さい (0 など) 場合、メソッドは必要なバッファ サイズをこのパラメータに設定し、D3DERR_MOREDATA を返す。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DERR_MOREDATA
D3DERR_NOTFOUND

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DSurface8::FreePrivateData、IDirect3DSurface8::SetPrivateData


IDirect3DSurface8::GetDesc

サーフェスの記述を取得する。

HRESULT GetDesc(
  D3DSURFACE_DESC* pDesc
);

パラメータ

pDesc
[out] サーフェスを記述している D3DSURFACE_DESC 構造体へのポインタ。

戻り値

成功した場合は、D3D_OK を返す。

この引数が無効な場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3DSurface8::LockRect

サーフェス上の矩形をロックする。

HRESULT LockRect(
  D3DLOCKED_RECT* pLockedRect,
  CONST RECT* pRect,
  DWORD Flags
);

パラメータ

pLockedRect
[out] ロック済みの領域を記述する D3DLOCKED_RECT 構造体へのポインタ。
pRect
[in] ロックする矩形へのポインタ。RECT 構造体へのポインタによって指定される。このパラメータに NULL を指定すると、サーフェス全体を覆うようにダーティー領域が拡大する。
Flags
[in] 実行するロックのタイプを記述する、0 個以上のロッキング フラグの組み合わせ。
D3DLOCK_NO_DIRTY_UPDATE
デフォルトでは、リソースのロックはダーティー領域をそのリソースに追加する。このフラグは、リソースのダーティー状態への変更を防ぐ。ロック処理の間に変更される実際の領域群についての追加情報をアプリーションが持つ場合は、アプリケーションでこのフラグを使用しなければならない。
D3DLOCK_NOSYSLOCK
ビデオ メモリ ロックのデフォルトの動作は、システムのクリティカル セクションを確保することで、ロック中にディスプレイ モードの変更が行われないことを保証する。このフラグは、システムワイドなクリティカル セクションがロックの間保持されないようにする。

ロック処理は若干負荷が高くなるが、マウス カーソルの移動など、システムでほかの処理を実行することが可能になる。このフラグは、ソフトウェア レンダリングのバックバッファのロックのように、ロックが長時間に及び、システムの応答性に悪影響を与えてしまうようなロックに対して有効である。

D3DLOCK_READONLY
アプリケーションはバッファに書き込みを行わない。これによって、ネイティブでないフォーマットで格納されたリソースが、アンロック時に再圧縮手順を保存できる。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

深度ステンシル サーフェスのロック可能なフォーマットは、D3DFMT_D16_LOCKABLE だけである。

マルチサンプル バック バッファはロックできない。

パフォーマンスの理由によって、ダーティーな範囲はテクスチャのレベルゼロに対して記録されるのみである。D3DLOCK_NO_DIRTY_UPDATE または D3DLOCK_READONLY なしで LockRect か LockBox が呼び出されたとき、ダーティーな範囲は自動的に記録される。また CopyRects 呼び出しの宛先サーフェイスはダーティーとしてマークされる。詳細については、「IDirect3DDevice8::UpdateTexture」を参照すること。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DSurface8::UnlockRect


IDirect3DSurface8::SetPrivateData

Microsoft® Direct3D® ではなく、アプリケーションでの使用が意図されているサーフェスとデータを関連付ける。

HRESULT SetPrivateData(
  REFGUID refguid,
  void* pData,
  DWORD SizeOfData,
  DWORD Flags
);

パラメータ

refguid
[in] 設定するプライベート データを識別するグローバル ユニーク識別子への参照 (C++) またはアドレス (C)。
pData
[in] サーフェスと関連付けるデータが格納されているバッファへのポインタ。
SizeOfData
[in] pData のバッファ サイズ (バイト単位)。
Flags
[in] 渡されるデータ型を記述する値、またはリソースが変更された場合にデータを無効にする必要があることをアプリケーションに示す値。
(none)
フラグを指定しない場合、Direct3D はバッファ内のデータを保持するメモリを割り当て、新しいバッファにデータをコピーする。Direct3D によって割り当てられるバッファは、適宜自動的に解放される。
D3DSPD_IUNKNOWN
pData のデータは IUnknown インターフェイスへのポインタである。SizeOfData は、IUnknown インターフェイス (sizeof(IUnknown*)) へのポインタのサイズに設定する必要がある。Direct3D は pData を介して IUnknown::AddRef を、プライベート データが破棄される場合は IUnknown::Release を自動的に呼び出す。次に同じ GUID で SetPrivateData を呼び出すと、または次に IDirect3DSurface8::FreePrivateData を呼び出すと、または Direct3D8 オブジェクトが解放されると、プライベート データは破棄される。詳細については、「注意」を参照すること。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

注意

Direct3D は pData でメモリを管理しない。このバッファが動的に割り当てられた場合は、呼び出し側の責任でメモリを解放する。

データは値で渡され、複数のデータ セットを単一のサーフェスと関連付けることができる。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DSurface8::FreePrivateData、IDirect3DSurface8::GetPrivateData


IDirect3DSurface8::UnlockRect

サーフェス上の矩形をアンロックする。

HRESULT UnlockRect();

パラメータ

なし。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DSurface8::LockRect


IDirect3DSwapChain8

スワップ チェーンを操作するには、IDirect3DSwapChain8 インターフェイスのメソッドを使用する。

各デバイスには、少なくとも 1 つのスワップ チェーンが常に存在しており、非明示的なスワップ チェーンと呼ばれる。ただし、IDirect3DDevice8::CreateAdditionalSwapChain メソッドを呼び出すことで、同じデバイスから複数のビューをレンダリングするための追加スワップ チェーンを作成できる。

IDirect3DSwapChain8 インターフェイスのメソッドは、以下のグループにまとめることができる。

プレゼンテーション | Present
サーフェス管理 | GetBackBuffer

すべての COM インターフェイスと同様、IDirect3DSwapChain8 インターフェイスは IUnknown インターフェイスのメソッドを継承する。IUnknown インターフェイスは、次の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECT3DSWAPCHAIN8 および PDIRECT3DSWAPCHAIN8 型は、IDirect3DSwapChain8 インターフェイスへのポインタとして定義される。

typedef struct IDirect3DSwapChain8 *LPDIRECT3DSWAPCHAIN8, *PDIRECT3DSWAPCHAIN8;

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::CreateAdditionalSwapChain


IDirect3DSwapChain8::GetBackBuffer

デバイスのスワップ チェーンからバック バッファを取得する。

HRESULT GetBackBuffer(
  UINT  BackBuffer,
  D3DBACKBUFFER_TYPE Type,
  IDirect3DSurface8** ppBackBuffer
);

パラメータ

BackBuffer
[in] 返されるバック バッファ オブジェクトのインデックス。バック バッファは 0 からバック バッファの総数 - 1 までナンバリングされる。0 の戻り値は最初のバック バッファを示し、フロント バッファではない。このメソッドを使用してフロント バッファにアクセスすることはできない。
Type
[in] DirectX 8.0 ではステレオ ビューはサポートされていないので、このパラメータの有効な値は D3DBACKBUFFER_TYPE_MONO だけである。
ppBackBuffer
[out, retval] 返されるバック バッファ サーフェスを表す IDirect3DSurface8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、D3D_OK を返す。

BackBuffer がバック バッファの総数以上の場合、関数は失敗し、D3DERR_INVALIDCALL を返す。

注 このメソッドを呼び出すと、IDirect3DSurface8 インターフェイスについての内部参照カウントが増加する。この IDirect3DSurface8 インターフェイスの使用を終了したときに IUnknown::Release の呼び出しが失敗すると、メモリ リークが発生する。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3DSwapChain8::Present

スワップ チェーンが所有するバック バッファのシーケンスの中で次のコンテンツを提示する。

HRESULT Present(
  CONST RECT* pSourceRect,
  CONST RECT* pDestRect,
  HWND hDestWindowOverride,
  CONST RGNDATA* pDirtyRegion
);

パラメータ

pSourceRect
[in] 転送元矩形を含む RECT 構造体へのポインタ。この値は、スワップ チェーンが D3DSWAPEFFECT_COPY または D3DSWAPEFFECT_COPY_VSYNC で作成されていない限り、NULL でなければならない。NULL の場合は、転送元サーフェス全体が表示される。矩形が転送元サーフェスを超えた場合、矩形は転送元サーフェスにクリッピングされる。
pDestRect
[in] ウィンドウのクライアント座標で転送先矩形を含む RECT 構造体へのポインタ。この値は、スワップ チェーンが D3DSWAPEFFECT_COPY または D3DSWAPEFFECT_COPY_VSYNC で作成されていない限り、NULL でなければならない。NULL の場合は、クライアント領域全体が格納される。矩形が転送先のクライアント領域を越えた場合、矩形は転送先のクライアント領域にクリッピングされる。
hDestWindowOverride
[in] クライアント領域がこのプレゼンテーションの対象として扱われる転送先ウィンドウ。このパラメータが NULL の場合は、D3DPRESENT_PARAMETERS の hWndDeviceWindow メンバが使用される。
pDirtyRegion
[in] このパラメータは未使用なため、NULL に設定する必要がある。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY
E_OUTOFMEMORY

注意

このメソッドの動作は、IDirect3DDevice8::Present メソッドとまったく同じである。

必要に応じて、転送元矩形内のピクセルをターゲット ウィンドウのクライアント領域の転送先矩形に転送するために拡大処理が適用される。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::Reset


IDirect3DTexture8

テクスチャ リソースを操作するには、IDirect3DTexture8 インターフェイスのメソッドを使う。

IDirect3DTexture8 インターフェイスを取得するには、IDirect3DDevice8::CreateTexture メソッドを呼び出す。

IDirect3DTexture8 インターフェイスは、次のようなグループに分類できる IDirect3DResource8 メソッドを継承する。

デバイス | GetDevice
情報 | GetType
プライベート サーフェス データ | FreePrivateData
 | GetPrivateData
 | SetPrivateData
リソース管理 | GetPriority
 | PreLoad
 | SetPriority

IDirect3DTexture8 インターフェイスは、次のようなグループに分類できる IDirect3DBaseTexture8 メソッドを継承する。

詳細 | GetLOD
 | SetLOD
情報 | GetLevelCount

IDirect3DTexture8 インターフェイスのメソッドは、以下のグループにまとめることができる。

情報 | GetLevelDesc
サーフェスのロック | LockRect
 | UnlockRect
その他 | AddDirtyRect
 | GetSurfaceLevel

すべての COM インターフェイスと同様、IDirect3DTexture8 インターフェイスは IUnknown インターフェイスのメソッドを継承する。IUnknown インターフェイスは、次の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECT3DTEXTURE8 および PDIRECT3DTEXTURE8 型は、IDirect3DTexture8 インターフェイスへのポインタとして定義される。

typedef struct IDirect3DTexture8 *LPDIRECT3DTEXTURE8, *PDIRECT3DTEXTURE8;

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::CreateTexture


IDirect3DTexture8::AddDirtyRect

テクスチャ リソースにダーティー領域を追加する。

HRESULT AddDirtyRect(
  CONST RECT* pDirtyRect
);

パラメータ

pDirtyRect
[in] RECT 構造体へのポインタ。追加するダーティー領域を指定する。NULL を指定すると、ダーティー領域が拡大してテクスチャ全体を覆う。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

リソースのダーティー領域を指定することで、コピーされるリソースのサブセットを最適化できる。

パフォーマンスの理由によって、ダーティーな範囲はテクスチャのレベルゼロに対して記録されるのみである。サブレベルについては、対応する ( スケールされた ) 矩形またはボックスもダーティーであると仮定される。D3DLOCK_NO_DIRTY_UPDATE または D3DLOCK_READONLY なしで LockRect か LockBox が呼び出されたとき、ダーティーな範囲は自動的に記録される。また CopyRects 呼び出しの宛先サーフェイスはダーティーとしてマークされる。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3DTexture8::GetLevelDesc

テクスチャ サーフェスのレベル記述を取得する。

HRESULT GetLevelDesc(
  UINT Level,
  D3DSURFACE_DESC* pDesc
);

パラメータ

Level
[in] テクスチャのリソースのレベルを識別する。このメソッドは、このパラメータで指定されたレベルに対するサーフェスの記述を返す。
pDesc
[out] 返されるレベルが記述されている D3DSURFACE_DESC 構造体へのポインタ。

戻り値

成功した場合は、D3D_OK を返す。

引数の 1 つが無効な場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3DTexture8::GetSurfaceLevel

指定されたテクスチャ サーフェスのレベルを取得する。

HRESULT GetSurfaceLevel(
  UINT Level,
  IDirect3DSurface8** ppSurfaceLevel
);

パラメータ

Level
[in] テクスチャのリソースのレベルを識別する。このメソッドは、このパラメータで指定されたレベルに対するサーフェスを返す。トップレベルのサーフェスは 0 で示される。
ppSurfaceLevel
[out, retval] 返されるサーフェスを表す IDirect3DSurface8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注 このメソッドを呼び出すと、IDirect3DSurface8 インターフェイスについての内部参照カウントが増加する。この IDirect3DSurface8 インターフェイスの使用を終了したときに IUnknown::Release の呼び出しが失敗すると、メモリ リークが発生する。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3DTexture8::LockRect

テクスチャ リソース上の矩形をロックする。

HRESULT LockRect(
  UINT Level,
  D3DLOCKED_RECT* pLockedRect,
  CONST RECT* pRect,
  DWORD Flags
);

パラメータ

Level
[in] ロックするテクスチャ リソースのレベルを指定する。
pLockedRect
[out] ロック済みの領域を記述する D3DLOCKED_RECT 構造体へのポインタ。
pRect
[in] ロックする矩形へのポインタ。RECT 構造体へのポインタによって指定される。このパラメータに NULL を指定すると、テクスチャ全体を覆うようにダーティー領域が拡大する。
Flags
[in] 実行するロックのタイプを記述する、0 個以上のロッキング フラグの組み合わせ。
D3DLOCK_NO_DIRTY_UPDATE
デフォルトでは、リソースのロックはダーティー領域をそのリソースに追加する。このフラグは、リソースのダーティー状態への変更を防ぐ。ロック処理の間に変更される実際の領域群についての追加情報をアプリケーションが持っていて、その情報を IDirect3DTexture8::AddDirtyRect に渡すことができる場合は、アプリケーションでこのフラグを使用しなければならない。
D3DLOCK_NOSYSLOCK
ビデオ メモリ ロックのデフォルトの動作は、システムのクリティカル セクションを確保することで、ロック中にディスプレイ モードの変更が行われないことを保証する。このフラグは、システムワイドなクリティカル セクションがロックの間保持されないようにする。

ロック処理は若干負荷が高くなるが、マウス カーソルの移動など、システムでほかの処理を実行することが可能になる。このフラグは、ソフトウェア レンダリングのバックバッファのロックのように、ロックが長時間に及び、システムの応答性に悪影響を与えてしまうようなロックに対して有効である。

D3DLOCK_READONLY
アプリケーションはバッファに書き込みを行わない。これによって、ネイティブでないフォーマットで格納されたリソースが、アンロック時に再圧縮手順を保存できる。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

D3DPOOL_DEFAULT で作成されたテクスチャはロックできない。

深度ステンシル サーフェスのロック可能なフォーマットは、D3DFMT_D16_LOCKABLE だけである。

マルチサンプル バック バッファはロックできない。ビデオ メモリ テクスチャはロックできないが、IDirect3Ddevice8::CopyRects または IDirect3Ddevice8::UpdateTexture を呼び出して修正する必要がある。Microsoft® DirectX® 8.0 が認識しない、一部のメーカーのドライバのピクセル フォーマットは例外である。これらはロックできる。

パフォーマンスの理由によって、ダーティーな範囲はテクスチャのレベルゼロに対して記録されるのみである。D3DLOCK_NO_DIRTY_UPDATE または D3DLOCK_READONLY なしで LockRect か LockBox が呼び出されたとき、ダーティーな範囲は自動的に記録される。詳細については、「IDirect3DDevice8::UpdateTexture」を参照すること。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DTexture8::UnlockRect


IDirect3DTexture8::UnlockRect

テクスチャ リソース上の矩形をアンロックする。

HRESULT UnlockRect(
  UINT Level
);

パラメータ

Level
[in] アンロックするテクスチャ リソースのレベルを指定する。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DTexture8::LockRect


IDirect3DVertexBuffer8

頂点バッファ リソースを操作するには、IDirect3DVertexBuffer8 インターフェイスのメソッドを使用する。

IDirect3DVertexBuffer8 インターフェイスを取得するには、IDirect3DDevice8::CreateVertexBuffer メソッドを呼び出す。

IDirect3DVertexBuffer8 インターフェイスは、次のようなグループに分類できる IDirect3DResource8 メソッドを継承する。

デバイス | GetDevice
情報 | GetType
プライベート サーフェス データ | FreePrivateData
 | GetPrivateData
 | SetPrivateData
リソース管理 | GetPriority
 | PreLoad
 | SetPriority

IDirect3DVertexBuffer8 インターフェイスのメソッドは、以下のグループにまとめることができる。

情報 | GetDesc
ロック | Lock
 | Unlock

すべての COM インターフェイスと同様、IDirect3DVertexBuffer8 インターフェイスは IUnknown インターフェイスのメソッドを継承する。IUnknown インターフェイスは、次の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECT3DVERTEXBUFFER8 および PDIRECT3DVERTEXBUFFER8 型は、IDirect3DVertexBuffer8 インターフェイスへのポインタとして定義される。

typedef struct IDirect3DVertexBuffer8 *LPDIRECT3DVERTEXBUFFER8, *PDIRECT3DVERTEXBUFFER8;

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::CreateVertexBuffer


IDirect3DVertexBuffer8::GetDesc

頂点バッファ リソースの記述を取得する。

HRESULT GetDesc(
  D3DVERTEXBUFFER_DESC* pDesc
);

パラメータ

pDesc
[out] 返される頂点バッファが記述されている D3DVERTEXBUFFER_DESC 構造体へのポインタ。

戻り値

成功した場合は、D3D_OK を返す。

この引数が無効な場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3DVertexBuffer8::Lock

頂点データの範囲をロックし、頂点バッファ メモリへのポインタを取得する。

HRESULT Lock(
  UINT OffsetToLock,
  UINT SizeToLock,
  BYTE** ppbData,
  DWORD Flags
);

パラメータ

OffsetToLock
[in] ロックする頂点データへのオフセット (バイト単位)。
SizeToLock
[in] ロックする頂点データのサイズ (バイト単位)。0 を指定すると、頂点バッファ全体がロックされる。
ppbData
[out] 返される頂点データが格納される BYTE 値配列へのポインタのアドレス。
Flags
[in] 頂点バッファ メモリをロックする方法を示す、0 個以上のロッキング フラグの組み合わせ。
D3DLOCK_DISCARD
アプリケーションは、書き込み専用処理でインデックス バッファ全体を上書きする。これにより、Direct3D は新しいメモリ領域へのポインタを返すことができるので、ダイナミック メモリ アクセス (DMA) と古い領域からのレンダリングが機能停止することはない。「注意」を参照すること。
D3DLOCK_NOOVERWRITE
フレームの開始以降、またはこのフラグが指定されていない最後のロック以降に描画処理の呼び出しの中で参照された頂点は、ロック中に変更されないことを示す。頂点バッファにのみデータを追加する場合は、このフラグにより処理を最適化できる。「注意」を参照すること。
D3DLOCK_NOSYSLOCK
ビデオ メモリ ロックのデフォルトの動作は、システムのクリティカル セクションを確保することで、ロック中にディスプレイ モードの変更が行われないことを保証する。このフラグは、システムワイドなクリティカル セクションがロックの間保持されないようにする。

ロック処理は若干負荷が高くなるが、マウス カーソルの移動など、システムでほかの処理を実行することが可能になる。このフラグは、ソフトウェア レンダリングのバックバッファのロックのように、ロックが長時間に及び、システムの応答性に悪影響を与えてしまうようなロックに対して有効である。

D3DLOCK_READONLY
アプリケーションはバッファに書き込みを行わない。これにより、いくらかの最適化が実現する。D3DLOCK_READONLY は D3DLOCK_DISCARD と共に指定することはできない。また、D3DUSAGE_WRITEONLY で作成された頂点バッファに指定することもできない。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

頂点バッファを操作する場合、複数のロック呼び出しを行うことができる。ただし、ロック呼び出しの数とアンロック呼び出しの数は一致していなければならない。現在設定している頂点バッファでロック カウントが残っている場合、DrawPrimitive の呼び出しは失敗する。

D3DLOCK_DISCARD および D3DLOCK_NOOVERWRITE フラグは、D3DUSAGE_DYNAMIC で作成されたバッファに対してのみ有効である。

D3DLOCK_DISCARD または D3DLOCK_NOOVERWRITE を Lock メソッドの Flags パラメータで使用する方法については、「動的な頂点およびインデックス バッファの使い方」を参照すること。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DVertexBuffer8::Unlock


IDirect3DVertexBuffer8::Unlock

頂点データをアンロックする。

HRESULT Unlock();

パラメータ

なし。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DVertexBuffer8::Lock


IDirect3DVolume8

ボリューム リソースを操作するには、IDirect3DVolume8 インターフェイスのメソッドを使用する。

IDirect3DVolume8 インターフェイスを取得するには、IDirect3DVolumeTexture8::GetVolumeLevel メソッドを呼び出す。

IDirect3DVolume8 インターフェイスのメソッドは、以下のグループにまとめることができる。

デバイス | GetDevice
情報 | GetContainer
 | GetDesc
ロッキング ボリューム | LockBox
 | UnlockBox
プライベート ボリューム データ | FreePrivateData
 | GetPrivateData
 | SetPrivateData

すべての COM インターフェイスと同様、IDirect3DVolume8 インターフェイスは IUnknown インターフェイスのメソッドを継承する。IUnknown インターフェイスは、次の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECT3DVOLUME8 および PDIRECT3DVOLUME8 型は、IDirect3DVolume8 インターフェイスへのポインタとして定義される。

typedef struct IDirect3DVolume8 *LPDIRECT3DVOLUME8, *PDIRECT3DVOLUME8;

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3DVolume8::FreePrivateData

このボリュームに関連付けられている指定されたプライベート データを解放する。

HRESULT FreePrivateData(
  REFGUID refguid
);

パラメータ

refguid
[in] 解放するプライベート データを識別するグローバル ユニーク識別子への参照 (C++) またはアドレス (C)。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DERR_NOTFOUND

注意

Microsoft® Direct3D® は、ボリュームが解放されると自動的にこのメソッドを呼び出す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DVolume8::GetPrivateData、IDirect3DVolume8::SetPrivateData


IDirect3DVolume8::GetContainer

このサーフェスがボリューム テクスチャの子レベルである場合、親のボリューム テクスチャ オブジェクトへのアクセスを提供する。

HRESULT GetContainer(
  REFIID riid,
  void** ppContainer
);

パラメータ

riid
[in] 要求するボリュームの参照識別子。
ppContainer
[out, retval] 照会が成功した場合にコンテナ ポインタが格納されるポインタのアドレス。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3DVolume8::GetDevice

ボリュームに関連付けられているデバイスを取得する。

HRESULT GetDevice(
  IDirect3DDevice8** ppDevice
);

パラメータ

ppDevice
[out, retval] 照会が成功した場合に、デバイスのポインタが格納される IDirect3DDevice8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

このメソッドを使用すると、所有しているデバイス オブジェクトに移動することができる。

注 このメソッドを呼び出すと、IDirect3DDevice8 インターフェイスについての内部参照カウントが増加する。この IDirect3DDevice8 インターフェイスの使用を終了したときに IUnknown::Release の呼び出しが失敗すると、メモリ リークが発生する。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3DVolume8::GetPrivateData

ボリュームに関連付けられたプライベート データを提供されたバッファにコピーする。

HRESULT GetPrivateData(
  REFGUID refguid,
  void* pData,
  DWORD* pSizeOfData
);

パラメータ

refguid
[in] 取得するプライベート データを識別するグローバル ユニーク識別子への参照 (C++) またはアドレス (C)。
pData
[in, out] 呼び出しが成功した場合に、要求したプライベート データを格納する割り当て済みバッファへのポインタ。このメソッドを呼び出すアプリケーションは、このバッファの割り当てと解放に責任を負う。
pSizeOfData
[in, out] pData のバッファ サイズ (バイト単位) へのポインタ。この値が実際のプライベート データのサイズより小さい (0 など) 場合、メソッドは必要なバッファ サイズをこのパラメータに設定し、D3DERR_MOREDATA を返す。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DERR_MOREDATA
D3DERR_NOTFOUND

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DVolume8::FreePrivateData、IDirect3DVolume8::SetPrivateData


IDirect3DVolume8::GetDesc

ボリュームの記述を取得する。

HRESULT GetDesc(
  D3DVOLUME_DESC* pDesc
);

パラメータ

pDesc
[out] ボリュームが記述されている D3DVOLUME_DESC 構造体へのポインタ。

戻り値

成功した場合は、D3D_OK を返す。

この引数が無効な場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3DVolume8::LockBox

ボリューム リソース上のボックスをロックする。

HRESULT LockBox(
  D3DLOCKED_BOX* pLockedVolume,
  CONST D3DBOX* pBox,
  DWORD Flags
);

パラメータ

pLockedVolume
[out] ロックされた領域を記述する D3DLOCKED_BOX 構造体へのポインタ。
pBox
[in] ロックするボックスへのポインタ。D3DBOX 構造体へのポインタで指定される。このパラメータに NULL を指定すると、ボリューム全体がロックされる。
Flags
[in] 実行するロックのタイプを記述する、0 個以上のロッキング フラグの組み合わせ。
D3DLOCK_NO_DIRTY_UPDATE
デフォルトでは、リソースのロックはダーティー領域をそのリソースに追加する。このフラグは、リソースのダーティー状態への変更を防ぐ。アプリケーションでは、ロック処理中に変更される実際のボリューム セットについての追加情報を持っている場合は、このフラグを使用しなければならない。
D3DLOCK_NOSYSLOCK
ビデオ メモリ ロックのデフォルトの動作は、システムのクリティカル セクションを確保することで、ロック中にディスプレイ モードの変更が行われないことを保証する。このフラグは、システムワイドなクリティカル セクションがロックの間保持されないようにする。

ロック処理は若干負荷が高くなるが、マウス カーソルの移動など、システムでほかの処理を実行することが可能になる。このフラグは、ソフトウェア レンダリングのバックバッファのロックのように、ロックが長時間に及び、システムの応答性に悪影響を与えてしまうようなロックに対して有効である。

D3DLOCK_READONLY
アプリケーションはバッファに書き込みを行わない。これによって、ネイティブでないフォーマットで格納されたリソースが、アンロック時に再圧縮手順を保存できる。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

パフォーマンスの理由によって、ダーティーな範囲はテクスチャのレベルゼロに対して記録されるのみである。D3DLOCK_NO_DIRTY_UPDATE または D3DLOCK_READONLY なしで LockRect か LockBox が呼び出されたとき、ダーティーな範囲は自動的に記録される。詳細については、「IDirect3DDevice8::UpdateTexture」を参照すること。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DVolume8::UnlockBox


IDirect3DVolume8::SetPrivateData

Microsoft® Direct3D® ではなく、アプリケーションでの使用が意図されているボリュームとデータを関連付ける。

HRESULT SetPrivateData(
  REFGUID refguid,
  void* pData,
  DWORD SizeOfData,
  DWORD Flags
);

パラメータ

refguid
[in] 設定するプライベート データを識別するグローバル ユニーク識別子への参照 (C++) またはアドレス (C)。
pData
[in] ボリュームと関連付けるデータが格納されているバッファへのポインタ。
SizeOfData
[in] pData のバッファ サイズ (バイト単位)。
Flags
[in] 渡されるデータ型を記述する値、またはリソースが変更された場合にデータを無効にする必要があることをアプリケーションに示す値。
(none)
フラグを指定しない場合、Direct3D はバッファ内のデータを保持するメモリを割り当て、新しいバッファにデータをコピーする。Direct3D によって割り当てられるバッファは、適宜自動的に解放される。
D3DSPD_IUNKNOWN
pData のデータは IUnknown インターフェイスへのポインタである。SizeOfData は、IUnknown インターフェイス (sizeof(IUnknown*)) へのポインタのサイズに設定する必要がある。Direct3D は pData を介して IUnknown::AddRef を、プライベート データが破棄される場合は IUnknown::Release を自動的に呼び出す。次に同じ GUID で SetPrivateData を呼び出すと、または次に IDirect3DVolume8::FreePrivateData を呼び出すと、または Direct3D8 オブジェクトが解放されると、プライベート データは破棄される。詳細については、「注意」を参照すること。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

注意

Direct3D は pData でメモリを管理しない。このバッファが動的に割り当てられた場合は、呼び出し側の責任でメモリを解放する。

データは値で渡され、複数のデータ セットを単一のボリュームと関連付けることができる。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DVolume8::FreePrivateData、IDirect3DVolume8::GetPrivateData


IDirect3DVolume8::UnlockBox

ボリューム リソース上のボックスをアンロックする。

HRESULT UnlockBox();

パラメータ

なし。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DVolume8::LockBox


IDirect3DVolumeTexture8

ボリューム テクスチャ リソースを操作するには、IDirect3DVolumeTexture8 インターフェイスのメソッドを使う。

IDirect3DVolumeTexture8 インターフェイスを取得するには、IDirect3DDevice8::CreateVolumeTexture メソッドを呼び出す。

IDirect3DVolumeTexture8 インターフェイスは、次のようなグループに分類できる IDirect3DResource8 メソッドを継承する。

デバイス | GetDevice
情報 | GetType
プライベート サーフェス データ | FreePrivateData
 | GetPrivateData
 | SetPrivateData
リソース管理 | GetPriority
 | PreLoad
 | SetPriority

IDirect3DVolumeTexture8 インターフェイスは、次のようなグループに分類できる IDirect3DBaseTexture8 メソッドを継承する。

詳細 | GetLOD
 | SetLOD
情報 | GetLevelCount

IDirect3DVolumeTexture8 インターフェイスのメソッドは、以下のグループにまとめることができる。

情報 | GetLevelDesc
ロッキング ボリューム | LockBox
 | UnlockBox
その他 | AddDirtyBox
 | GetVolumeLevel

すべての COM インターフェイスと同様、IDirect3DVolumeTexture8 インターフェイスは IUnknown インターフェイスのメソッドを継承する。IUnknown インターフェイスは、次の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECT3DVOLUMETEXTURE8 および PDIRECT3DVOLUMETEXTURE8 型は、IDirect3DVolumeTexture8 インターフェイスへのポインタとして定義される。

typedef struct IDirect3DVolumeTexture8 *LPDIRECT3DVOLUMETEXTURE8, *PDIRECT3DVOLUMETEXTURE8;

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DDevice8::CreateVolumeTexture


IDirect3DVolumeTexture8::AddDirtyBox

ボリューム テクスチャ リソースにダーティー領域を追加する。

HRESULT AddDirtyBox(
  CONST D3DBOX* pDirtyBox
);

パラメータ

pDirtyBox
[in] D3DBOX 構造体へのポインタ。追加するダーティー領域を指定する。NULL を指定すると、ダーティー領域が拡大してボリューム テクスチャ全体を覆う。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

リソースのダーティー領域を指定することで、コピーされるリソースのサブセットを最適化できる。ただし、ダーティー領域はアライメントを最適化するために拡大されることがある。

パフォーマンスの理由によって、ダーティーな範囲はテクスチャのレベルゼロに対して記録されるのみである。サブレベルについては、対応する ( スケールされた ) 矩形またはボックスもダーティーであると仮定される。D3DLOCK_NO_DIRTY_UPDATE または D3DLOCK_READONLY なしで LockRect か LockBox が呼び出されたとき、ダーティーな範囲は自動的に記録される。また CopyRects 呼び出しの宛先サーフェイスはダーティーとしてマークされる。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3DVolumeTexture8::GetLevelDesc

ボリューム テクスチャ サーフェスのレベル記述を取得する。

HRESULT GetLevelDesc(
  UINT Level,
  D3DVOLUME_DESC* pDesc
);

パラメータ

Level
[in] ボリューム テクスチャ リソースのレベルを識別する。このメソッドは、このパラメータで指定されたレベルに対するボリュームの記述を返す。
pDesc
[out] 返されるボリューム テクスチャ レベルが記述されている D3DVOLUME_DESC 構造体へのポインタ。

戻り値

成功した場合は、D3D_OK を返す。

引数の 1 つ以上が無効な場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3DVolumeTexture8::GetVolumeLevel

指定されたボリューム テクスチャ レベルを取得する。

HRESULT GetVolumeLevel(
  UINT Level,
  IDirect3DVolume8** ppVolumeLevel
);

パラメータ

Level
[in] ボリューム テクスチャ リソースのレベルを識別する。このメソッドは、このパラメータで指定されたレベルに対するボリュームを返す。
ppVolumeLevel
[out, retval] 返されるボリューム レベルを表す IDirect3DVolume8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注 このメソッドを呼び出すと、IDirect3DVolume8 インターフェイスについての内部参照カウントが増加する。この IDirect3DVolume8 インターフェイスの使用を終了したときに IUnknown::Release の呼び出しが失敗すると、メモリ リークが発生する。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


IDirect3DVolumeTexture8::LockBox

ボリューム テクスチャ リソース上のボックスをロックする。

HRESULT LockBox(
  UINT Level,
  D3DLOCKED_BOX* pLockedVolume,
  CONST D3DBOX* pBox,
  DWORD Flags
);

パラメータ

Level
[in] ロックするボリューム テクスチャ リソースのレベルを指定する。
pLockedVolume
[out] ロックされた領域を記述する D3DLOCKED_BOX 構造体へのポインタ。
pBox
[in] ロックするボリュームへのポインタ。このパラメータは、D3DBOX 構造体へのポインタで指定される。このパラメータに NULL を指定すると、ボリューム レベル全体がロックされる。
Flags
[in] 実行するロックのタイプを記述する、0 個以上のロッキング フラグの組み合わせ。
D3DLOCK_NO_DIRTY_UPDATE
デフォルトでは、リソースのロックはダーティー領域をそのリソースに追加する。このフラグは、リソースのダーティー状態への変更を防ぐ。アプリケーションは、ロック処理の間に変更される実際のボリューム セットについての追加情報を保持していて、その情報を IDirect3DVolumeTexture8::AddDirtyBox に渡すことができるときは、このフラグを使用しなければならない。
D3DLOCK_NOSYSLOCK
ビデオ メモリ ロックのデフォルトの動作は、システムのクリティカル セクションを確保することで、ロック中にディスプレイ モードの変更が行われないことを保証する。このフラグは、システムワイドなクリティカル セクションがロックの間保持されないようにする。

ロック処理は若干負荷が高くなるが、マウス カーソルの移動など、システムでほかの処理を実行することが可能になる。このフラグは、ソフトウェア レンダリングのバックバッファのロックのように、ロックが長時間に及び、システムの応答性に悪影響を与えてしまうようなロックに対して有効である。

D3DLOCK_READONLY
アプリケーションはバッファに書き込みを行わない。これによって、ネイティブでないフォーマットで格納されたリソースが、アンロック時に再圧縮手順を保存できる。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

パフォーマンスの理由によって、ダーティーな範囲はテクスチャのレベル ゼロに対して記録されるのみである。D3DLOCK_NO_DIRTY_UPDATE または D3DLOCK_READONLY なしで LockRect か LockBox が呼び出されたとき、ダーティーな範囲は自動的に記録される。詳細については、「IDirect3DDevice8::UpdateTexture」を参照すること。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DVolumeTexture8::UnlockBox


IDirect3DVolumeTexture8::UnlockBox

ボリューム テクスチャ リソース上のボックスをアンロックする。

HRESULT UnlockBox(
  UINT Level
);

パラメータ

Level
[in] アンロックするボリューム テクスチャ リソースのレベルを指定する。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : d3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。

参照

IDirect3DVolumeTexture8::LockBox


関数

ここでは、Microsoft® Direct3D® を使用する場合に使用する必要がある関数のリファレンス情報を記述する。次の関数が実装されている。

  • Direct3DCreate8


Direct3DCreate8

Direct3D8 オブジェクトのインスタンスを作成する。

IDirect3D8* Direct3DCreate8(
  UINT SDKVersion
);

パラメータ

SDKVersion
このパラメータの値は D3D_SDK_VERSION でなければならない。「注意」を参照すること。

戻り値

成功した場合は、IDirect3D8 インターフェイスへのポインタを返す。それ以外の場合は、NULL ポインタを返す。

注意

この関数は、列挙をサポートする Direct3D8 オブジェクトを作成する。また、この関数を使用して Direct3DDevice8 オブジェクトを作成できる。

アプリケーションが正しいヘッダー ファイルに対してビルドされていることを確認するため、Direct3DCreate8 には D3D_SDK_VERSION 識別子を渡す。ヘッダーまたはほかの変更によりアプリケーションのリビルドが必要になるたびに、この値はインクリメントされる。バージョンが一致しない場合、Direct3DCreate8 は失敗する。

この関数を呼び出すと、現在のアクティブ ディスプレイ アダプタ セットがサンプリングされる。デスクトップにデバイスを追加したり、ラップトップをホットドッキングして、動的にアダプタを追加した場合、この Direct3D8 オブジェクトの有効期間の間、そのようなデバイスは列挙されない。新しい Direct3D8 オブジェクトを作成すると、新しいデバイスが公開される。

動作環境

ヘッダー : D3d8.h で宣言。
インポート ライブラリ : D3d8.lib を使用。


マクロ

ここでは、Microsoft® Direct3D® が提供するマクロのリファレンス情報を記述する。

  • D3DCLIPPLANEn
  • D3DCOLOR_ARGB
  • D3DCOLOR_COLORVALUE
  • D3DCOLOR_RGBA
  • D3DCOLOR_XRGB
  • D3DFVF_TEXCOORDSIZEn
  • D3DTS_WORLD
  • D3DTS_WORLDn
  • D3DTS_WORLDMATRIX


D3DCLIPPLANEn

ユーザー定義クリップ面を有効にするビット パターンを定義する。これらのマクロは、D3DRS_CLIPPLANEENABLE レンダリング ステート値の設定を簡素化するために定義されている。

D3DCLIPPLANE0 (1 << 0)
D3DCLIPPLANE1 (1 << 1)
D3DCLIPPLANE2 (1 << 2)
D3DCLIPPLANE3 (1 << 3)
D3DCLIPPLANE4 (1 << 4)
D3DCLIPPLANE5 (1 << 5)

パラメータ

なし。

注意

ユーザー定義クリップ面は、D3DRS_CLIPPLANEENABLE レンダリング ステートに設定される DWORD 値で 1 つ以上のビットが設定されている (つまり 0 ではない) 場合に有効になる。レンダリング ステート値の DWORD に重要性はなく、システムはその値を番号として解釈しない。その代わり、DWORD を解析し、対応するビットが設定されているクリップ面を有効にする。ビット 0 は最初のクリップ面 (インデックス 0) を制御し、ビット 1 は 2 番目の平面を制御する、というように各クリップ面が制御される。

これらのマクロで作成するビット パターンは、論理和演算子で結合することで、同時に複数のクリップ面を有効にできる。この組み合わせからマクロのいずれかを省くだけで、そのインデックスのクリップ面を簡単に無効にできる。

動作環境

ヘッダー : D3d8types.h で宣言。


D3DCOLOR_ARGB

指定されたアルファ、赤、緑、および青の各値で、色を初期化する。

D3DCOLOR_ARGB(a,r,g,b) \
    ((D3DCOLOR)((((a)&0xff)<<24)|(((r)&0xff)<<16)|(((g)&0xff)<<8)|((b)&0xff)))

パラメータ

a、r、g、および b
色のアルファ (alpha)、赤 (red)、緑 (green)、および青 (blue) の成分。これらの値の範囲は、0 ～ 255 でなければならない。

戻り値

指定された ARGB 値に対応する D3DCOLOR 値を返す。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

D3DCOLOR_RGBA、D3DCOLOR_XRGB


D3DCOLOR_COLORVALUE

指定された赤、緑、青、およびアルファの各浮動小数点値で、色を初期化する。

D3DCOLOR_COLORVALUE(r,g,b,a) \
    D3DCOLOR_RGBA((DWORD)((r)*255.f),(DWORD)((g)*255.f),(DWORD)((b)*255.f),(DWORD)((a)*255.f))

パラメータ

r、g、b、および a
色の赤 (red)、緑 (green)、青 (blue)、およびアルファ (alpha) の成分。これらの値は 0.0 から 1.0 の範囲にある浮動小数点値でなければならない。

戻り値

指定された RGBA 値に対応する D3DCOLOR 値を返す。

動作環境

ヘッダー : D3d8types.h で宣言。


D3DCOLOR_RGBA

指定された赤、緑、青、およびアルファの各値で、色を初期化する。

D3DCOLOR_RGBA(r,g,b,a) D3DCOLOR_ARGB(a,r,g,b)

パラメータ

r、g、b、および a
色の赤 (red)、緑 (green)、青 (blue)、およびアルファ (alpha) の成分。これらの値の範囲は、0 ～ 255 でなければならない。

戻り値

指定された RGBA 値に対応する D3DCOLOR 値を返す。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

D3DCOLOR_ARGB、D3DCOLOR_XRGB


D3DCOLOR_XRGB

指定された赤、緑、および青の各値で、色を初期化する。

D3DCOLOR_XRGB(r,g,b) D3DCOLOR_ARGB(0xff,r,g,b)

パラメータ

r、g、および b
色の赤 (red)、緑 (green)、および青 (blue) の成分。これらの値の範囲は、0 ～ 255 でなければならない。

戻り値

指定された RGB 値に対応する D3DCOLOR 値を返す。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

D3DCOLOR_ARGB、D3DCOLOR_RGBA


D3DFVF_TEXCOORDSIZEn

柔軟な頂点フォーマットの記述内でテクスチャ座標フォーマットの識別に使用されるビット パターンを作成する。このマクロの結果は、論理和演算子を使用して柔軟な頂点フォーマット内で結合できる。

D3DFVF_TEXCOORDSIZE1(CoordIndex) (D3DFVF_TEXTUREFORMAT1 << (CoordIndex*2 + 16))
D3DFVF_TEXCOORDSIZE2(CoordIndex) (D3DFVF_TEXTUREFORMAT2)
D3DFVF_TEXCOORDSIZE3(CoordIndex) (D3DFVF_TEXTUREFORMAT3 << (CoordIndex*2 + 16))
D3DFVF_TEXCOORDSIZE4(CoordIndex) (D3DFVF_TEXTUREFORMAT4 << (CoordIndex*2 + 16))

パラメータ

CoordIndex
テクスチャ座標サイズ (1、2、3、または 4 次元) が適用されるテクスチャ座標セットを識別する値。

注意

D3DFVF_TEXCOORDSIZEn マクロでは、次の定数が使われる。

#define D3DFVF_TEXTUREFORMAT1 3         // 1 つの浮動小数点値
#define D3DFVF_TEXTUREFORMAT2 0         // 2 つの浮動小数点値
#define D3DFVF_TEXTUREFORMAT3 1         // 3 つの浮動小数点値
#define D3DFVF_TEXTUREFORMAT4 2         // 4 つの浮動小数点値

以下の柔軟な頂点フォーマットの記述は、位置、法線、ディフューズ色、スペキュラ色、および 2 つのテクスチャ座標セットを持つ頂点フォーマットを示している。1 つ目のテクスチャ座標セットには単一の要素が含まれ、2 つ目のセットには 2 つの要素が含まれる。

DWORD dwFVF = D3DFVF_XYZ | D3DFVF_NORMAL | D3DFVF_DIFFUSE |
              D3DFVF_SPECULAR | D3DFVF_TEX2 |
              D3DFVF_TEXCOORDSIZE1(0) |  \\ Uses 1-D texture coordinates for
                                         \\ texture coordinate set 1 (index 0).
              D3DFVF_TEXCOORDSIZE2(1);   \\ And 2-D texture coordinates for
                                         \\ texture coordinate set 2 (index 1).

動作環境

ヘッダー : D3d8types.h で宣言。

参照

柔軟な頂点フォーマット フラグ


D3DTS_WORLD

ワールド トランスフォーム行列として設定されるトランスフォーム行列を識別する。

D3DTS_WORLD  D3DTS_WORLDMATRIX(0)

パラメータ

なし。

注意

このマクロは、既存アプリケーションの Microsoft® DirectX® 8.0 への移植を容易にするために提供されている。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

IDirect3DDevice8::SetTransform、D3DTS_WORLDMATRIX


D3DTS_WORLDn

頂点フォーマットで指定された対応する行列およびブレンディング (ベータ) 加重値を用いる頂点ブレンディングに使用される、以降のトランスフォーム行列を識別する。

D3DTS_WORLD1 D3DTS_WORLDMATRIX(1)
D3DTS_WORLD2 D3DTS_WORLDMATRIX(2)
D3DTS_WORLD3 D3DTS_WORLDMATRIX(3)

パラメータ

なし。

注意

これらのマクロは、既存アプリケーションの Microsoft® DirectX® 8.0 への移植を容易にするために提供されている。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

IDirect3DDevice8::SetTransform、D3DTS_WORLDMATRIX


D3DTS_WORLDMATRIX

0 ～ 255 の範囲のインデックスを対応するトランスフォーム ステートにマップする。

D3DTS_WORLDMATRIX(index) (D3DTRANSFORMSTATETYPE)(index + 256)

パラメータ

index
0 ～ 255 の範囲のインデックス値。

注意

256 ～ 511 の範囲のトランスフォーム ステートは、8 ビットのインデックスを使ってインデックス指定できる最大 256 個の行列を格納するために確保されている。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

IDirect3DDevice8::SetTransform


頂点シェーダ宣言子マクロ

ここでは、頂点シェーダ宣言子の DWORD 配列を作成するために使用されるビット アセンブリ マクロについて説明する。

  • D3DVSD_CONST
  • D3DVSD_END
  • D3DVSD_NOP
  • D3DVSD_REG
  • D3DVSD_SKIP
  • D3DVSD_STREAM
  • D3DVSD_STREAM_TESS
  • D3DVSD_TESSNORMAL
  • D3DVSD_TESSUV


D3DVSD_CONST

頂点シェーダ定数メモリにデータをロードする。

D3DVSD_CONST( _ConstantAddress, _Count ) \
            (D3DVSD_MAKETOKENTYPE(D3DVSD_TOKEN_CONSTMEM) | \
            ((_Count) << D3DVSD_CONSTCOUNTSHIFT) | (_ConstantAddress))

パラメータ

_ConstantAddress
データの格納を開始する定数配列のアドレス。指定可能な値の範囲は、0 ～ 95 である。
_Count
各データにつき 4 DWORD とそれに続いて 4*_Count DWORD をロードする定数ベクトルの数。「注意」を参照すること。

注意

次のサンプル コードは、このマクロの使い方を示している。

D3DVALUE diffuse[] = {1, 1, 1.0f/255.0f, 1};
        DWORD decl[] =
        {
            D3DVSD_CONST(8, 1),
            *(DWORD*)&diffuse[0],
            *(DWORD*)&diffuse[1],
            *(DWORD*)&diffuse[2],
            *(DWORD*)&diffuse[3],
            D3DVSD_STREAM(0),
            D3DVSD_REG( 0, D3DVSDT_FLOAT3),
            D3DVSD_REG( 2, D3DVSDT_D3DCOLOR),
            D3DVSD_STREAM(1),
            D3DVSD_REG( 1, D3DVSDT_FLOAT1),
            D3DVSD_STREAM(2),
            D3DVSD_REG( 3, D3DVSDT_FLOAT2),
            D3DVSD_END()
        };

動作環境

ヘッダー : D3d8types.h で宣言。

参照

IDirect3DDevice8::CreateVertexShader


D3DVSD_END

END トークンを生成する。

#define D3DVSD_END()

パラメータ

なし。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

IDirect3DDevice8::CreateVertexShader


D3DVSD_NOP

NOP トークンを生成する。

#define D3DVSD_NOP()

パラメータ

なし。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

IDirect3DDevice8::CreateVertexShader


D3DVSD_REG

単一の頂点レジスタを頂点ストリームからの頂点要素にバインドする。

D3DVSD_REG( _VertexRegister, _Type ) \
          (D3DVSD_MAKETOKENTYPE(D3DVSD_TOKEN_STREAMDATA) | \
          ((_Type) << D3DVSD_DATATYPESHIFT) | (_VertexRegister))

パラメータ

_VertexRegister
頂点レジスタのアドレス。指定可能な値の範囲は、0 ～ 15 である。固定機能パイプラインの場合、入力レジスタは以下の固定マッピングを備えている。
D3DVSDE_POSITION
レジスタ 0。
D3DVSDE_BLENDWEIGHT
レジスタ 1。
D3DVSDE_NORMAL
レジスタ 2。
D3DVSDE_PSIZE
レジスタ 3。
D3DVSDE_DIFFUSE
レジスタ 4。
D3DVSDE_SPECULAR
レジスタ 5。
D3DVSDE_TEXCOORD0
レジスタ 6。
D3DVSDE_TEXCOORD1
レジスタ 7。
D3DVSDE_TEXCOORD2
レジスタ 8。
D3DVSDE_TEXCOORD3
レジスタ 9。
D3DVSDE_TEXCOORD4
レジスタ 10。
D3DVSDE_TEXCOORD5
レジスタ 11。
D3DVSDE_TEXCOORD6
レジスタ 12。
D3DVSDE_TEXCOORD7
レジスタ 13。
_Type
寸法および算術データ型を指定する。以下の値が定義されている。
D3DVSDT_D3DCOLOR
0.0 ～ 1.0 の範囲にマップされる 4D のパックされた符号なしバイト。ダブル ワード形式では、これは ARGB であり、バイト オーダーでは、B、G、R、A である。
D3DVSDT_FLOAT1
(value, 0.0, 0.0, 1.0) に展開される 1D float。
D3DVSDT_FLOAT2
(value, value, 0.0, 1.0) に展開される 2D float。
D3DVSDT_FLOAT3
(value, value, value, 1.0) に展開される 3D float。
D3DVSDT_FLOAT4
4D float。
D3DVSDT_UBYTE4
4D 符号なしバイト。ダブル ワード形式では、これは ABGR であり、バイト オーダーでは、R、G、B、A である。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

IDirect3DDevice8::CreateVertexShader


D3DVSD_SKIP

頂点内でスキップする DWORD の数を指定する。

D3DVSD_SKIP( _DWORDCount ) \
           (D3DVSD_MAKETOKENTYPE(D3DVSD_TOKEN_STREAMDATA) | 0x10000000 | \
           ((_DWORDCount) << D3DVSD_SKIPCOUNTSHIFT))

パラメータ

_DWORDCount
頂点内でスキップする DWORD の数。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

IDirect3DDevice8::CreateVertexShader


D3DVSD_STREAM

カレント ストリームを設定する。

D3DVSD_STREAM( _StreamNumber ) \
             (D3DVSD_MAKETOKENTYPE(D3DVSD_TOKEN_STREAM) | (_StreamNumber))

パラメータ

_StreamNumber
データの取得元のストリームを指定する。指定可能な値の範囲は、0 ～ dwMaxStreams から 1 引いた値である。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

IDirect3DDevice8::CreateVertexShader


D3DVSD_STREAM_TESS

テッセレータ ストリームを設定する。

D3DVSD_STREAM_TESS( ) \
      (D3DVSD_MAKETOKENTYPE(D3DVSD_TOKEN_STREAM) | (D3DVSD_STREAMTESSMASK))

パラメータ

なし。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

IDirect3DDevice8::CreateVertexShader


D3DVSD_TESSNORMAL

テッセレータで生成される法線を有効にする。

D3DVSD_TESSNORMAL( _VertexRegisterIn, _VertexRegisterOut ) \
                 (D3DVSD_MAKETOKENTYPE(D3DVSD_TOKEN_TESSELLATOR) | \
                 ((_VertexRegisterIn) << D3DVSD_VERTEXREGINSHIFT) | \
                 ((0x02) << D3DVSD_DATATYPESHIFT) | (_VertexRegisterOut))

パラメータ

_VertexRegisterIn
入力ストリームが法線の計算に使用される頂点レジスタのアドレス。指定可能な値の範囲は、0 ～ 15 である。
_VertexRegisterOut
法線を出力する頂点レジスタのアドレス。指定可能な値の範囲は、0 ～ 15 である。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

IDirect3DDevice8::CreateVertexShader


D3DVSD_TESSUV

テッセレータで生成されるサーフェス パラメータを有効にする。

D3DVSD_TESSUV( _VertexRegister ) \
             (D3DVSD_MAKETOKENTYPE(D3DVSD_TOKEN_TESSELLATOR) | 0x10000000 | \
             ((0x01) << D3DVSD_DATATYPESHIFT) | (_VertexRegister))

パラメータ

_VertexRegister
パラメータを出力する頂点レジスタのアドレス。指定可能な値の範囲は、0 ～ 15 である。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

IDirect3DDevice8::CreateVertexShader


構造体

ここでは、Microsoft® Direct3D® で使用する以下の構造体について説明する。

  • D3DADAPTER_IDENTIFIER8
  • D3DBOX
  • D3DCAPS8
  • D3DCLIPSTATUS8
  • D3DCOLORVALUE
  • D3DDEVICE_CREATION_PARAMETERS
  • D3DDISPLAYMODE
  • D3DGAMMARAMP
  • D3DINDEXBUFFER_DESC
  • D3DLIGHT8
  • D3DLINEPATTERN
  • D3DLOCKED_BOX
  • D3DLOCKED_RECT
  • D3DMATERIAL8
  • D3DMATRIX
  • D3DPRESENT_PARAMETERS
  • D3DRANGE
  • D3DRASTER_STATUS
  • D3DRECT
  • D3DRECTPATCH_INFO
  • D3DSURFACE_DESC
  • D3DTRIPATCH_INFO
  • D3DVECTOR
  • D3DVERTEXBUFFER_DESC
  • D3DVIEWPORT8
  • D3DVOLUME_DESC


D3DADAPTER_IDENTIFIER8

アダプタについての情報を保持する。

typedef struct _D3DADAPTER_IDENTIFIER8 {
    char            Driver[MAX_DEVICE_IDENTIFIER_STRING];
    char            Description[MAX_DEVICE_IDENTIFIER_STRING];

#ifdef _WIN32
    LARGE_INTEGER   DriverVersion;            /* 32 ビット コンポーネント用に定義される */
#else
    DWORD           DriverVersionLowPart;     /* 16 ビット コンポーネント用に定義される */
    DWORD           DriverVersionHighPart;
#endif

    DWORD           VendorId;
    DWORD           DeviceId;
    DWORD           SubSysId;
    DWORD           Revision;

    GUID            DeviceIdentifier;

    DWORD           WHQLLevel;
} D3DADAPTER_IDENTIFIER8;

メンバ

Driver および Description
ユーザーに提示するために使用される。ベンダーが異なる同じデバイスおよびドライバに対して多くの異なる文字列が関連付けられている可能性があるため、特定のドライバを識別するためにこれらの値を使用するべきではない。
DriverVersion、DriverVersionLowPart、および DriverVersionHighPart
Microsoft® Direct3D® ドライバのバージョンを識別する。64 ビットの符号付き整数値として大小比較を行っても問題はない。ただし、この要素を使用して疑わしいドライバを識別する場合は、注意して行うこと。この値ではなく、DeviceIdentifier を使うことが望ましい。

次の疑似コードの例は、このメンバに符号化されるバージョンのフォーマットを示したものである。

Product = HIWORD(DriverVersion.HighPart)
Version = LOWORD(DriverVersion.HighPart)
SubVersion = HIWORD(DriverVersion.LowPart)
Build = LOWORD(DriverVersion.LowPart)

HIWORD マクロ、LOWORD マクロ、および LARGE_INTEGER 構造体の詳細については、Microsoft Platform Software Development Kit (SDK) を参照すること。

VendorId
特定のチップ セットの識別に使用できる。メーカーを識別するには、このメンバを調べる。不明な場合、この値は 0 になる場合がある。
DeviceId
特定のチップ セットの識別に使用できる。チップ セットの種類を識別するには、このメンバを調べる。不明な場合、この値は 0 になる場合がある。
SubSysId
特定のチップ セットの識別に使用できる。サブシステムを識別するには、このメンバを調べる。一般に、サブシステムとは特定のボードを指す。不明な場合、この値は 0 になる場合がある。
Revision
特定のチップ セットの識別に使用できる。チップ セットのリビジョン レベルを識別するには、このメンバを調べる。不明な場合、この値は 0 になる場合がある。
DeviceIdentifier
このメンバを調べると、ドライバおよびチップ セットの変更を確認できる。GUID は、ドライバとチップ セットのペアに対する一意な識別子である。ドライバおよびチップセットへの変更を追跡し、グラフィックス サブシステムの新しいプロファイルを作成する場合は、このメンバを参照する。このメンバは、特定の疑わしいドライバを識別するためにも使用できる。
WHQLLevel
このデバイスとドライバのペアの Windows Hardware Quality Lab (WHQL) 認証レベルを特定するために使用する。DWORD にはパック形式のデータ構造が格納されており、ドライバが合格した最新の WHQL テストのリリース日が定義されている。この値に対して大小比較演算を実行しても問題はない。次は日付のフォーマットである。
Bits
31-16:    The year, a decimal number from 1999 upwards.
15-8:     The month, a decimal number from 1 to 12.
7-0:      The day, a decimal number from 1 to 31.

次の値も使用される。

0
認証されていない。
1
WHQL の認証は受けているが、利用できる日付情報はない。

注意

定数 MAX_DEVICE_IDENTIFIER_STRING は、次のように定義されている。

#define MAX_DEVICE_IDENTIFIER_STRING        512

VendorId、DeviceId、SubSysId、および Revision の各メンバを組み合わせて使うことで、特定のチップ セットを識別できる。ただし、これらのメンバを使うときは注意が必要である。

動作環境

ヘッダー : D3d8types.h で宣言。


D3DBOX

ボリュームを定義する。

typedef struct _D3DBOX {
    UINT                Left;
    UINT                Top;
    UINT                Right;
    UINT                Bottom;
    UINT                Front;
    UINT                Back;
} D3DBOX;

メンバ

Left、Top、Right、Bottom、Front、および Back
ボックスのディメンジョン。

注意

D3DBOX には左側面、上面、および前面のエッジは含まれるが、右側面、底面、および背面のエッジは含まれない。たとえば、100 単位の幅で 0 から始まるボックス (つまり、最大 99 までのポイントを含む) は、0 という値の Left メンバと 100 という値の Right メンバで表される。Right メンバの値が 99 ではないことに注意すること。

D3DBOX で示される面の順序の規則は、左から右、上から下、および前から後である。

動作環境

ヘッダー : D3d8types.h で宣言。


D3DCAPS8

Microsoft® Direct3D® オブジェクトが公開するハードウェアの能力を表す。

typedef struct _D3DCAPS8 {
    D3DDEVTYPE          DeviceType;
    UINT                AdapterOrdinal;

    DWORD               Caps;
    DWORD               Caps2;
    DWORD               Caps3;
    DWORD               PresentationIntervals;

    DWORD               CursorCaps;

    DWORD               DevCaps;

    DWORD               PrimitiveMiscCaps;
    DWORD               RasterCaps;
    DWORD               ZCmpCaps;
    DWORD               SrcBlendCaps;
    DWORD               DestBlendCaps;
    DWORD               AlphaCmpCaps;
    DWORD               ShadeCaps;
    DWORD               TextureCaps;
    DWORD               TextureFilterCaps;
    DWORD               CubeTextureFilterCaps;
    DWORD               VolumeTextureFilterCaps;
    DWORD               TextureAddressCaps;
    DWORD               VolumeTextureAddressCaps;

    DWORD               LineCaps;

    DWORD               MaxTextureWidth, MaxTextureHeight;
    DWORD               MaxVolumeExtent;

    DWORD               MaxTextureRepeat;
    DWORD               MaxTextureAspectRatio;
    DWORD               MaxAnisotropy;
    float               MaxVertexW;

    float               GuardBandLeft;
    float               GuardBandTop;
    float               GuardBandRight;
    float               GuardBandBottom;

    float               ExtentsAdjust;
    DWORD               StencilCaps;

    DWORD               FVFCaps;
    DWORD               TextureOpCaps;
    DWORD               MaxTextureBlendStages;
    DWORD               MaxSimultaneousTextures;

    DWORD               VertexProcessingCaps;
    DWORD               MaxActiveLights;
    DWORD               MaxUserClipPlanes;
    DWORD               MaxVertexBlendMatrices;
    DWORD               MaxVertexBlendMatrixIndex;

    float               MaxPointSize;

    DWORD               MaxPrimitiveCount;
    DWORD               MaxVertexIndex;
    DWORD               MaxStreams;
    DWORD               MaxStreamStride;

    DWORD               VertexShaderVersion;
    DWORD               MaxVertexShaderConst;

    DWORD               PixelShaderVersion;
    float               MaxPixelShaderValue;
} D3DCAPS8;

メンバ

DeviceType
D3DDEVTYPE 列挙型のメンバ。この Direct3DDevice オブジェクトが作成された対象のデバイスのタイプ。
AdapterOrdinal
この Direct3DDevice オブジェクトが作成されたアダプタ。この序数は、この Direct3DDevice オブジェクトを作成した IDirect3D8 インターフェイスのメソッドに渡す場合にのみ有効である。IDirect3D8 インターフェイスは、常に、IDirect3DDevice8::GetDirect3D を呼び出すことで取得できる。
Caps
以下に、ドライバ固有の能力を示す。
D3DCAPS_READ_SCANLINE
ディスプレイ ハードウェアは、現在の走査線を返すことができる。
Caps2
以下に、ドライバ固有の能力を示す。
D3DCAPS2_CANCALIBRATEGAMMA
システムには自動的にガンマ ランプを調整できる口径測定器がインストールされているので、口径測定器がある全システムにおいて結果は同じである。新しいガンマ レベルを設定するときに口径測定器を起動するには、IDirect3DDevice8::SetGammaRamp メソッドを呼び出す際に D3DSGR_CALIBRATE フラグを使用する。ガンマ ランプのキャリブレーションを行うと処理オーバーヘッドが発生するので、頻繁に使用すべきではない。
D3DCAPS2_CANRENDERWINDOWED
ドライバは、ウィンドウ モードのレンダリングができる。
D3DCAPS2_FULLSCREENGAMMA
ドライバは、フルスクリーン モードでのダイナミック ガンマ ランプ調整をサポートしている。
D3DCAPS2_NO2DDURING3DSCENE
ドライバによって D3DCAPS2_NO2DDURING3DSCENE 能力が設定されている場合、IDirect3DDevice8::BeginScene と IDirect3DDevice8::EndScene の呼び出しの間では 2D 処理を実行できないことを意味する。

通常、この能力は、シーンをパーティション化し、シーン内の各パーティションをレンダリングするハードウェアによって設定される。パーティション化はドライバによって実行され、ハードウェアはイメージ パーティションのサイズに対応する小さな色および深度バッファを格納する。このタイプのレンダリング ハードウェアでは、通常、イメージの各部分がレンダリングされると、 カラー バッファ内のデータはビデオ メモリに書き込まれ、深度バッファの内容は破棄される。また、3D レンダリングは EndScene が検出されるまで開始されないことに注意すること。次に、シーンがリージョンごとに処理される。この場合、処理の順序は保証されない。たとえば、処理される最初のリージョン (通常はウィンドウの左上隅) が、フレームの最後の三角形を含んでいる場合がある。従来のグラフィックス システムの場合、各コマンドは送信された順に処理される。その点でこれまでのシステムと異なる。2D 処理は、処理のある特定の時点で行われることが想定されている。D3DCAPS2_NO2DDURING3DSCENE が設定されたシステムでは、処理の順序は保証されない。したがって、ディスプレイ アダプタは、3D レンダリングの際に発生する 2D 処理を破棄することがある。

一般的には、BeginScene と EndScene のペアの外側で 2D 処理を実行することを推奨する。2D 処理がBeginScene と EndScene のペアの間で実行される場合は、D3DCAPS2_NO2DDURING3DSCENE 能力をチェックする必要がある。この能力が設定されている場合、アプリケーションでは、BeginScene と EndScene の間にある 2D 処理は破棄されると考えなければならない。D3DCAPS2_NO2DDURING3DSCENE を設定するシステム用のアプリケーション作成の詳細については、「注意」を参照すること。

D3DCAPS2_RESERVED
予約済み。使用されない。
Caps3
以下に、ドライバ固有の能力を示す。
D3DCAPS3_RESERVED
予約済み。使用されない。
PresentationIntervals
利用可能なプレゼンテーション スワップ間隔を示す値のビット マスク。ウィンドウ モードの場合、この値は 0 でなければならない。それ以外の場合、この値は、D3DCAPS8 の PresentationIntervals メンバで列挙される値のいずれかでなければならない。
D3DPRESENT_INTERVAL_IMMEDIATE
ドライバは、直接プレゼンテーション スワップ間隔をサポートしている。
D3DPRESENT_INTERVAL_ONE
ドライバは、スクリーン リフレッシュごとにプレゼンテーション スワップ間隔をサポートしている。
D3DPRESENT_INTERVAL_TWO
ドライバは、2 回目のスクリーン リフレッシュごとにプレゼンテーション スワップ間隔をサポートしている。
D3DPRESENT_INTERVAL_THREE
ドライバは、3 回目のスクリーン リフレッシュごとにプレゼンテーション スワップ間隔をサポートしている。
D3DPRESENT_INTERVAL_FOUR
ドライバは、4 回目のスクリーン リフレッシュごとにプレゼンテーション スワップ間隔をサポートしている。
CursorCaps
カーソルに対して利用できるハードウェア サポートを示すビット マスク。
D3DCURSORCAPS_COLOR
ハードウェアは、フルカラー カーソルをサポートしている。具体的には、このフラグは、ドライバが高解像度モード (走査線が 400 以上) で、少なくともハードウェア カラー カーソルをサポートしていることを示す。
D3DCURSORCAPS_LOWRES
ハードウェアは、フルカラー カーソルをサポートしている。具体的には、このフラグは、ドライバが高解像度モードと低解像度モード (走査線が 400 未満) の両方で、ハードウェア カラー カーソルをサポートしていることを示す。

Direct3D for Microsoft DirectX® 8.0 では、アルファ ブレンディング カーソルの能力は定義されていない。

DevCaps
デバイスの能力を示すフラグ。
D3DDEVCAPS_CANBLTSYSTONONLOCAL
デバイスは、システムメモリ テクスチャから非ローカル ビデオメモリ テクスチャへのブリットをサポートする。
D3DDEVCAPS_CANRENDERAFTERFLIP
デバイスは、ページ フリップの後で、レンダリング コマンドをキューに入れることができる。このフラグはアプリケーションの動作を変えるものではない。単にデバイスが比較的高速であることを示すものである。
D3DDEVCAPS_DRAWPRIMTLVERTEX
デバイスは、DrawPrimitive 対応のハードウェア アブストラクション レイヤ (HAL) をエクスポートする。
D3DDEVCAPS_EXECUTESYSTEMMEMORY
デバイスは、システム メモリにある実行バッファを使用できる。
D3DDEVCAPS_EXECUTEVIDEOMEMORY
デバイスは、ビデオ メモリにある実行バッファを使用できる。
D3DDEVCAPS_HWRASTERIZATION
デバイスには、シーンのラスタ化用のハードウェア アクセラレーションがある。
D3DDEVCAPS_HWTRANSFORMANDLIGHT
デバイスは、ハードウェアでトランスフォーム & ライティングをサポートできる。
D3DDEVCAPS_NPATCHES
デバイスは、N パッチをサポートする。
D3DDEVCAPS_PUREDEVICE
デバイスは、ハードウェアでラスタ化、トランスフォーム、ライティング、およびシェーディングをサポートできる。
D3DDEVCAPS_QUINTICRTPATCHES
デバイスは、5 次ベジェおよび B スプラインをサポートしている。
D3DDEVCAPS_RTPATCHES
デバイスは、矩形および三角形パッチをサポートしている。
D3DDEVCAPS_RTPATCHHANDLEZERO
このデバイス能力が設定されている場合、ハードウェア アーキテクチャで情報をキャッシュする必要がなく、キャッシュされていないパッチ (ハンドル 0) は、キャッシュされたパッチと同様、効率的に描画される。D3DDEVCAPS_RTPATCHHANDLEZERO の設定はハンドル 0 のパッチが描画できることを意味するのではないことに注意すること。ハンドル 0 のパッチは、この能力が設定されているかどうかに関係なく、常に描画できる。
D3DDEVCAPS_SEPARATETEXTUREMEMORIES
デバイスは、独立したメモリ プールからテクスチャ処理を行っている。
D3DDEVCAPS_TEXTURENONLOCALVIDMEM
デバイスは、非ローカル ビデオ メモリからテクスチャを取得できる。
D3DDEVCAPS_TEXTURESYSTEMMEMORY
デバイスは、システム メモリからテクスチャを取得できる。
D3DDEVCAPS_TEXTUREVIDEOMEMORY
デバイスは、デバイス メモリからテクスチャを取得できる。
D3DDEVCAPS_TLVERTEXSYSTEMMEMORY
デバイスは、トランスフォーム済みライティング済みの頂点用に、システム メモリのバッファを使用できる。
D3DDEVCAPS_TLVERTEXVIDEOMEMORY
デバイスは、トランスフォーム済みライティング済みの頂点用に、ビデオ メモリのバッファを使用できる。
PrimitiveMiscCaps
このプリミティブの総体的な能力。このメンバには、次の 1 つ以上のフラグを設定できる。
D3DPMISCCAPS_BLENDOP
デバイスは、D3DBLENDOP 列挙型で定義されているアルファ ブレンディング処理をサポートしている。
D3DPMISCCAPS_CLIPPLANESCALEDPOINTS
デバイスは、正確に、1.0 より大きいサイズのスケーリングされたポイントを、ユーザー定義クリップ面にクリップする。
D3DPMISCCAPS_CLIPTLVERTS
デバイスは、トランスフォーム後の頂点プリミティブをクリップする。
D3DPMISCCAPS_COLORWRITEENABLE
デバイスは、D3DRS_COLORWRITEENABLE ステートを使用して、レンダリング ターゲットのカラー バッファへのチャネルごとの書き込みをサポートする。
D3DPMISCCAPS_CULLCCW
ドライバは、D3DRS_CULLMODE ステートを使用して反時計回りのカリングをサポートする (これは三角形プリミティブにのみ適用される)。このフラグは、D3DCULL 列挙型の D3DCULL_CCW メンバに対応する。
D3DPMISCCAPS_CULLCW
ドライバは、D3DRS_CULLMODE ステートを使用して時計回りのカリングをサポートする(これは三角形プリミティブにのみ適用される)。このフラグは、D3DCULL 列挙型の D3DCULL_CW メンバに対応する。
D3DPMISCCAPS_CULLNONE
ドライバは、三角形カリングを実行しない。これは、D3DCULL 列挙型の D3DCULL_NONE メンバに対応する。
D3DPMISCCAPS_LINEPATTERNREP
ドライバは、D3DLINEPATTERN 構造体の wRepeatFactor メンバで 1 以外の値を処理できる (これは線描画プリミティブにのみ適用される)。
D3DPMISCCAPS_MASKZ
デバイスは、ピクセル処理における深度バッファの変更の有効/無効を切り替えることができる。
D3DPMISCCAPS_TSSARGTEMP
デバイスは、テンポラリ レジスタ用の D3DTA_TEMP をサポートする。
RasterCaps
ラスタ描画能力についての情報。このメンバには、次の 1 つ以上のフラグを設定できる。
D3DPRASTERCAPS_ANISOTROPY
デバイスは、異方性フィルタリングをサポートする。
D3DPRASTERCAPS_ANTIALIASEDGES
デバイスは、オブジェクトの輪郭線を凸状にするアンチエイリアス線を描画できる。詳細については、「D3DRS_EDGEANTIALIAS」を参照すること。
D3DPRASTERCAPS_COLORPERSPECTIVE
デバイスは、色のパースペクティブ補正を補間する。
D3DPRASTERCAPS_DITHER
デバイスは、ディザリングを使用して良質な色を再現できる。
D3DPRASTERCAPS_FOGRANGE
デバイスは、範囲ベースのフォグをサポートする。範囲ベースのフォグでは、シーンにおけるオブジェクトの深さ (z 座標) ではなく、ビューアからのオブジェクトの距離でフォグ エフェクトを計算する。
D3DPRASTERCAPS_FOGTABLE
デバイスは、ピクセルの深さを指すフォグ値を含む参照テーブルと照合して、フォグ値を算出する。
D3DPRASTERCAPS_FOGVERTEX
デバイスは、ライティング処理の際にフォグ値を計算し、ラスタ化の際にフォグ値を補間する。
D3DPRASTERCAPS_MIPMAPLODBIAS
デバイスは、詳細レベル (LOD) バイアス調整をサポートする。これらのバイアス調整により、ミップマップを普通よりもすっきりとまたはあまり鋭くなく見せることができる。ミップマップの LOD バイアスの詳細については、「D3DTSS_MIPMAPLODBIAS」を参照すること。
D3DPRASTERCAPS_PAT
ドライバは、照会されているプリミティブに対し、D3DRS_LINEPATTERN を使った線や塗りつぶしのパターン描画を実行できる。
D3DPRASTERCAPS_STRETCHBLTMULTISAMPLE
デバイスは、blt メソッドの拡大を実装することで、制限されたマルチサンプルのサポートを提供する。この能力が設定されている場合、シーンの途中で D3DRS_MULTISAMPLEANTIALIAS のオンとオフを切り替えることはできない。このフラグが設定されている場合、マルチサンプル マスキングは実行できない。
D3DPRASTERCAPS_WBUFFER
デバイスは、w を使用する深度バッファリングをサポートする。
D3DPRASTERCAPS_WFOG
デバイスは、w ベースのフォグをサポートする。W ベースのフォグは、パースペクティブ射影行列が指定された場合に使用されるが、アフィン射影では現在でも Z ベースのフォグが使用される。[3][4] 要素にゼロ以外の値がある射影行列が、パースペクティブ射影行列と見なされる。
D3DPRASTERCAPS_ZBIAS
デバイスは、z バイアス値をサポートする。これらはポリゴンに割り当てられた整数値であり、物理的に同一平面上にあるポリゴンを別のものに見せることができる。詳細については、「D3DRS_ZBIAS」を参照すること。
D3DPRASTERCAPS_ZBUFFERLESSHSR
デバイスは、隠れサーフェスの除去 (HRS) を実行でき、このとき、ポリゴンのソートや深度バッファの割り当てを必要としない。これにより、より多くのビデオ メモリをテクスチャ用に使うことができる。HSR を実行するために使用するメソッドはハードウェアの機能に依存し、アプリケーションに対しては透過的である。

Z バッファなしの HRS が実行されるのは、深度バッファ サーフェスがレンダリング ターゲット サーフェスに関連付けられておらず、かつ深度バッファの比較テストが有効になっている場合 (つまり、D3DRS_ZENABLE 列挙定数に関連付けられたステート値が TRUE に設定されている場合) である。

D3DPRASTERCAPS_ZFOG
デバイスは、z ベースのフォグをサポートする。
D3DPRASTERCAPS_ZTEST
デバイスは、z テスト処理を実行できる。この値は、効果的にプリミティブをレンダリングし、Z ピクセルがレンダリングされたかどうかを示す。
ZCmpCaps
Z バッファ比較能力。このメンバには、次の 1 つ以上のフラグを設定できる。
D3DPCMPCAPS_ALWAYS
常に Z テストをパスする。
D3DPCMPCAPS_EQUAL
新規の Z が現在の Z と等しい場合、Z テストをパスする。
D3DPCMPCAPS_GREATER
新規の Z が現在の Z より大きい場合、Z テストをパスする。
D3DPCMPCAPS_GREATEREQUAL
新規の Z が現在の Z より大きいか等しい場合、Z テストをパスする。
D3DPCMPCAPS_LESS
新規の Z が現在の Z より 小さい場合、Z テストをパスする。
D3DPCMPCAPS_LESSEQUAL
新規の Z が現在の Z より小さいか等しい場合、Z テストをパスする。
D3DPCMPCAPS_NEVER
常に Z テストを失敗する。
D3DPCMPCAPS_NOTEQUAL
新規の Z が現在の Z と等しくない場合、Z テストをパスする。
SrcBlendCaps
ソース ブレンディング能力。このメンバには、次の 1 つ以上のフラグを設定できる。(ソースおよびデスティネーションの RGBA 値は、添字の s および d. で示される)。
D3DPBLENDCAPS_BOTHINVSRCALPHA
ソースのブレンディング計数は (1-As, 1-As, 1-As, 1-As) で、デスティネーションのブレンディング係数は (As, As, As, As) である。デスティネーションのブレンディングの選択は無効になる。
D3DPBLENDCAPS_BOTHSRCALPHA
ドライバは D3DBLEND_BOTHSRCALPHA ブレンディング モードをサポートする(このブレンディング モードは廃止されている。詳細については、「D3DBLEND」を参照すること)。
D3DPBLENDCAPS_DESTALPHA
ブレンディング係数は (Ad, Ad, Ad, Ad)。
D3DPBLENDCAPS_DESTCOLOR
ブレンディング係数は (Rd, Gd, Bd, Ad)。
D3DPBLENDCAPS_INVDESTALPHA
ブレンディング計数は (1-Ad, 1-Ad, 1-Ad, 1-Ad)。
D3DPBLENDCAPS_INVDESTCOLOR
ブレンディング計数は (1-Rd, 1-Gd, 1-Bd, 1-Ad)。
D3DPBLENDCAPS_INVSRCALPHA
ブレンディング計数は (1-As, 1-As, 1-As, 1-As)。
D3DPBLENDCAPS_INVSRCCOLOR
ブレンディング計数は (1-Rd, 1-Gd, 1-Bd, 1-Ad)。
D3DPBLENDCAPS_ONE
ブレンディング係数は (1, 1, 1, 1)。
D3DPBLENDCAPS_SRCALPHA
ブレンディング係数は (As, As, As, As)。
D3DPBLENDCAPS_SRCALPHASAT
ブレンディング係数は (f, f, f, 1)、f = min(As, 1-Ad)。
D3DPBLENDCAPS_SRCCOLOR
ブレンディング係数は (Rs, Gs, Bs, As)。
D3DPBLENDCAPS_ZERO
ブレンディング係数は (0, 0, 0, 0)。
DestBlendCaps
デスティネーション ブレンディング能力。このメンバは、SrcBlendCaps メンバで定義された能力情報と同じである。
AlphaCmpCaps
アルファ テスト比較能力。このメンバは、ZCmpCaps メンバで定義された能力フラグを含む。このメンバが D3DPCMPCAPS_ALWAYS 能力だけ、または D3DPCMPCAPS_NEVER 能力だけしか持っていない場合、ドライバはアルファ テストをサポートしない。それ以外の場合、このフラグはアルファ テストをサポートする個々の比較を示す。
ShadeCaps
シェーディング処理能力。一般に、デバイスが指定されたコマンドをサポートしている場合、そのデバイスは D3DSHADE_FLAT モード (D3DSHADEMODE 列挙型で指定される) をサポートすると見なされる。このフラグは、ドライバがグーロー シェーディングもサポートできるかどうか、およびアルファ成分がサポートされているかどうかを示す。アルファ成分がサポートされない場合、生成された色のアルファ値は暗黙で 255 になる。この数値が、アルファの最大値 (アルファ成分が最強) である。

三角形の色、スペキュラ ハイライト、フォグ、およびアルファの各補間要素にはそれぞれ能力フラグがあり、アプリケーションはそのフラグを使用して、デバイス ドライバがそれらをどのように実装しているかを知ることができる。

このメンバには、次の 1 つ以上のフラグを設定できる。

D3DPSHADECAPS_ALPHAGOURAUDBLEND
デバイスは、グーロー ブレンドによる透明化 (D3DSHADEMODE 列挙型の D3DSHADE_GOURAUD ステート) に対するアルファ成分をサポートできる。このモードでは、プリミティブのアルファ成分は頂点で与えられ、ほかの色成分と共に面に沿って補間される。
D3DPSHADECAPS_COLORGOURAUDRGB
デバイスは、RGB カラー モデルでカラー グーロー シェーディングをサポートできる。このモードでは、プリミティブに対する色成分は頂点で与えられ、ほかの色成分と共に面に沿って補間される。RGB ライティング モデルでは、赤、緑、および青の各成分が補間される。
D3DPSHADECAPS_FOGGOURAUD
デバイスは、グーロー シェーディング モードでフォグをサポートできる。
D3DPSHADECAPS_SPECULARGOURAUDRGB
デバイスは、RGB カラー モデルのグーロー シェーディングにおいてスペキュラ ハイライトをサポートできる。
TextureCaps
その他のテクスチャ マッピング能力。このメンバには、次の 1 つ以上のフラグを設定できる。
D3DPTEXTURECAPS_ALPHA
テクスチャ ピクセルにおいてアルファがサポートされる。
D3DPTEXTURECAPS_ALPHAPALETTE
デバイスは、テクスチャ パレットからアルファを描画できる。
D3DPTEXTURECAPS_CUBEMAP
キューブ テクスチャをサポートする。
D3DPTEXTURECAPS_CUBEMAP_POW2
デバイスでは、キューブ テクスチャ マップのディメンジョンは 2 の累乗で指定されなければならない。
D3DPTEXTURECAPS_MIPCUBEMAP
デバイスは、ミップマップ化キューブ テクスチャをサポートする。
D3DPTEXTURECAPS_MIPMAP
デバイスは、ミップマップ化テクスチャをサポートする。
D3DPTEXTURECAPS_MIPVOLUMEMAP
デバイスは、ミップマップ化ボリューム テクスチャをサポートする。
D3DPTEXTURECAPS_NONPOW2CONDITIONAL
場合によっては、ディメンジョンが 2 の累乗でないテクスチャの使用をサポートする。以下の条件をすべて満たす場合、この能力を公開するデバイスではこのようなテクスチャを使用できる。
  • テクスチャ ステージのテクスチャ アドレッシング モードが、D3DTADDRESS_CLAMP に設定されている。
  • テクスチャ ステージのテクスチャ ラッピングが無効になっている (D3DRS_WRAPn を 0 に設定)。
  • ミップマッピングが使用されていない (拡大フィルタのみを使用)。
D3DPTEXTURECAPS_PERSPECTIVE
パースペクティブ補正のテクスチャリングがサポートされる。
D3DPTEXTURECAPS_POW2
すべてのテクスチャの幅と高さは、2 の累乗で指定されていなければならない。この条件は、キューブ テクスチャまたはボリューム テクスチャには適用されない。
D3DPTEXTURECAPS_PROJECTED
D3DTTFF_PROJECTED テクスチャ トランスフォーム フラグをサポートする。この能力が適用されている場合、デバイスはトランスフォーム済みテクスチャ座標を最後のテクスチャ座標で除算する。この能力が設定されている場合、ピクセル単位に射影除算が行われる。この能力が設定されていない場合に、射影除算が必要なときは、Direct3D ランタイムによって頂点ごとに行われる。
D3DPTEXTURECAPS_SQUAREONLY
テクスチャは、すべて正方形でなければならない。
D3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZE
テクスチャ インデックスは、補間実行前には、テクスチャ サイズに合わせてスケーリングされない。
D3DPTEXTURECAPS_VOLUMEMAP
デバイスは、ボリューム テクスチャをサポートする。
D3DPTEXTURECAPS_VOLUMEMAP_POW2
デバイスでは、ボリューム テクスチャ マップのディメンジョンは 2 の累乗で指定されなければならない。
TextureFilterCaps
Direct3DTexture オブジェクトのテクスチャ フィルタリング能力。ステージ単位のフィルタリング能力は、IDirect3DDevice8 インターフェイスでマルチテクスチャ ブレンディングを実行する際にテクスチャ ステージでサポートされるフィルタリング モードを示している。このメンバは、次に示すステージ単位のテクスチャ フィルタリング フラグを任意に組み合わせたものである。
D3DPTFILTERCAPS_MAGFAFLATCUBIC
デバイスは、ステージごとに、テクスチャを拡大する平面 3 次フィルタリングをサポートする。平面 3 次拡大フィルタは、D3DTEXTUREFILTERTYPE 列挙型の D3DTEXF_FLATCUBIC メンバで表される。
D3DPTFILTERCAPS_MAGFANISOTROPIC
デバイスは、ステージごとに、テクスチャを拡大する異方性フィルタリングをサポートする。異方性拡大フィルタは、D3DTEXTUREFILTERTYPE 列挙型の D3DTEXF_ANISOTROPIC メンバで表される。
D3DPTFILTERCAPS_MAGFGAUSSIANCUBIC
デバイスは、ステージごとに、テクスチャを拡大するガウス 3 次フィルタリングをサポートする。ガウス 3 次拡大フィルタは、D3DTEXTUREFILTERTYPE 列挙型の D3DTEXF_GAUSSIANCUBIC メンバで表される。
D3DPTFILTERCAPS_MAGFLINEAR
デバイスは、ステージごとに、テクスチャを拡大するバイリニア補間フィルタリングをサポートする。バイリニア補間拡大フィルタは、D3DTEXTUREFILTERTYPE 列挙型の D3DTEXF_LINEAR メンバで表される。
D3DPTFILTERCAPS_MAGFPOINT
デバイスは、ステージごとに、テクスチャを拡大するポイントサンプル フィルタリングをサポートする。ポイントサンプル拡大フィルタは、D3DTEXTUREFILTERTYPE 列挙型の D3DTEXF_POINT メンバで表される。
D3DPTFILTERCAPS_MINFANISOTROPIC
デバイスは、ステージごとに、テクスチャを縮小する異方性フィルタリングをサポートする。異方性縮小フィルタは、D3DTEXTUREFILTERTYPE 列挙型の D3DTEXF_ANISOTROPIC メンバで表される。
D3DPTFILTERCAPS_MINFLINEAR
デバイスは、ステージごとに、テクスチャを縮小するバイリニア補間フィルタリングをサポートする。バイリニア縮小フィルタは、D3DTEXTUREFILTERTYPE 列挙型の D3DTEXF_LINEAR メンバで表される。
D3DPTFILTERCAPS_MINFPOINT
デバイスは、ステージごとに、テクスチャを縮小するポイントサンプル フィルタリングをサポートする。ポイントサンプル縮小フィルタは、D3DTEXTUREFILTERTYPE 列挙型の D3DTEXF_POINT メンバで表される。
D3DPTFILTERCAPS_MIPFLINEAR
デバイスは、ステージごとに、ミップマップのためのトライリニア補間フィルタリングをサポートする。トライリニア補間ミップマップ フィルタは、D3DTEXTUREFILTERTYPE 列挙型の D3DTEXF_LINEAR メンバで表される。
D3DPTFILTERCAPS_MIPFPOINT
デバイスは、ステージ単位に、ミップマップを行うポイントサンプル フィルタリングをサポートする。ポイントサンプル ミップマップ フィルタは、D3DTEXTUREFILTERTYPE 列挙型の D3DTEXF_POINT メンバで表される。
CubeTextureFilterCaps
Direct3DCubeTexture オブジェクトのテクスチャ フィルタリング能力。ステージ単位のフィルタリング能力は、IDirect3DDevice8 インターフェイスでマルチテクスチャ ブレンディングを実行する際にテクスチャ ステージでサポートされるフィルタリング モードを示している。このメンバは、TextureFilterCaps 用に定義されたステージ単位のテクスチャ フィルタリング フラグを任意に組み合わせたものである。
VolumeTextureFilterCaps
Direct3DVolumeTexture オブジェクトのテクスチャ フィルタリング能力。ステージ単位のフィルタリング能力は、IDirect3DDevice8 インターフェイスでマルチテクスチャ ブレンディングを実行する際にテクスチャ ステージでサポートされるフィルタリング モードを示している。このメンバは、TextureFilterCaps 用に定義されたステージ単位のテクスチャ フィルタリング フラグを任意に組み合わせたものである。
TextureAddressCaps
Direct3DTexture オブジェクトのテクスチャ アドレッシング能力。このメンバには、次の 1 つ以上のフラグを設定できる。
D3DPTADDRESSCAPS_BORDER
デバイスは、D3DTSS_BORDERCOLOR テクスチャ ステージ ステートで指定される境界色を、[0.0, 1.0] の範囲外の座標に設定できる。
D3DPTADDRESSCAPS_CLAMP
デバイスは、テクスチャをアドレスに固定できる。
D3DPTADDRESSCAPS_INDEPENDENTUV
デバイスは、テクスチャの U 座標と V 座標のテクスチャ アドレッシング モードを分離できる。この能力は、D3DTSS_ADDRESSU および D3DTSS_ADDRESSV レンダリング ステート値に対応する。
D3DPTADDRESSCAPS_MIRROR
デバイスは、テクスチャをアドレスに反映させることができる。
D3DPTADDRESSCAPS_MIRRORONCE
デバイスは、テクスチャ座標の絶対値を取得し (0 を中心にミラーリングされ)、最大値に制限できる。
D3DPTADDRESSCAPS_WRAP
デバイスは、テクスチャの張り付けが可能である。
VolumeTextureAddressCaps
Direct3DVolumeTexture オブジェクトのテクスチャ アドレッシング能力。このメンバには、TextureAddressCaps メンバ用に定義された 1 つ以上のフラグを設定できる。
LineCaps
線描画プリミティブの能力を定義する。
D3DLINECAPS_ALPHACMP
アルファ テスト比較をサポートする。
D3DLINECAPS_BLEND
ソース ブレンディングをサポートする。
D3DLINECAPS_FOG
フォグをサポートする。
D3DLINECAPS_TEXTURE
テクスチャ マッピングをサポートする。
D3DLINECAPS_ZTEST
Z バッファ比較をサポートする。
MaxTextureWidth および MaxTextureHeight
このデバイスの最大のテクスチャの幅と高さ。
MaxVolumeExtent
最大ボリューム範囲。
MaxTextureRepeat
正規化した後のテクスチャ インデックスの整数ビットの全範囲。D3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZE ビットが設定されている場合、デバイスは、テクスチャ アドレッシング モードが適用されるまでテクスチャ サイズによるスケーリングを行わない。このビットが設定されていない場合は、デバイスはテクスチャ サイズ (最大詳細レベル) によるテクスチャ インデックスのスケーリングを実行してから補間を行う。

D3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZE が設定されている場合、テクスチャをラップできる回数は MaxTextureRepeat である。D3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZE が設定されていない場合、テクスチャをラップできる回数はMaxTextureRepeat × テクスチャ サイズである。たとえば、デバイスが D3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZE を設定し、MaxTextureRepeat が 32k で、最大テクスチャ サイズが 4k であるとする。このデバイスは、27 の整数ビット (および 32 ビット符号付き整数の場合は 5 つの小数ビット) を使用するので、4k のテクスチャを 32k 回ラップするのに十分である (テクスチャ座標が、正と負のテクスチャ座標の範囲に等しく広がっていると仮定した場合)。一方、デバイスが D3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZE を設定できない場合は、MaxTextureRepeat を 2**27 に設定する。

MaxTextureAspectRatio
ハードウェアによってサポートされる、テクスチャの最大アスペクト比。通常は 2 の累乗。
MaxAnisotropy
D3DTSS_MAXANISOTROPY テクスチャステージ ステートの最大有効値。
MaxVertexW
デバイスがサポートする最大 W ベース深度値。
GuardBandLeft、GuardBandTop、GuardBandRight、および GuardBandBottom
ガードバンド クリッピング領域の画面空間座標。この矩形内にあり、かつビューポート矩形の外側にある座標は、自動的にクリッピングされる。
ExtentsAdjust
アンチエイリアス カーネルが収まるように矩形の外辺を調節するためのピクセル数。
StencilCaps
サポートされているステンシル バッファ処理を指定するフラグ。ステンシル処理は、3 種類のステンシル バッファ処理レンダリング ステート (D3DRS_STENCILFAIL、D3DRS_STENCILPASS、D3DRS_STENCILFAILZFAIL) のすべてに対して、有効であると見なされる。
D3DSTENCILCAPS_DECR
D3DSTENCILOP_DECR 処理をサポートする。
D3DSTENCILCAPS_DECRSAT
D3DSTENCILOP_DECRSAT 処理をサポートする。
D3DSTENCILCAPS_INCR
D3DSTENCILOP_INCR 処理をサポートする。
D3DSTENCILCAPS_INCRSAT
D3DSTENCILOP_INCRSAT 処理をサポートする。
D3DSTENCILCAPS_INVERT
D3DSTENCILOP_INVERT 処理をサポートする。
D3DSTENCILCAPS_KEEP
D3DSTENCILOP_KEEP 処理をサポートする。
D3DSTENCILCAPS_REPLACE
D3DSTENCILOP_REPLACE 処理をサポートする。
D3DSTENCILCAPS_ZERO
D3DSTENCILOP_ZERO 処理をサポートする。

詳細については、「D3DSTENCILOP 列挙型」を参照すること。

FVFCaps
柔軟な頂点フォーマットの能力。
D3DFVFCAPS_DONOTSTRIPELEMENTS
頂点要素は削除しない方がよい。つまり、頂点フォーマットが現在のレンダリング ステートで使用されない要素を含んでいても、頂点を再度生成する必要はない。この能力フラグが指定されていない場合、頂点フォーマットから不要な要素を削除すると、パフォーマンスが向上する。
D3DFVFCAPS_PSIZE
D3DFVFCAPS_PSIZE がない場合、デバイスはトランスフォーム前の頂点について D3DFVF_PSIZE をサポートしていないことを示す。この場合、基本ポイント サイズは常に D3DRS_POINTSIZE から利用される。この能力は、ソフトウェアの固定機能頂点処理にのみ適用される。ソフトウェア頂点処理を行う場合、D3DFVF_PSIZE は常にサポートされる。

頂点シェーダによって書き込まれる出力ポイント サイズは常にサポートされる。頂点シェーダの場合、入力はすべて出力ポイント サイズによる。

トランスフォーム後の頂点については、D3DFVF_PSIZE は常にサポートされる。

D3DFVFCAPS_TEXCOORDCOUNTMASK
FVFCaps の下位 WORD をマスクする。このビットは、WORD データ型にキャストされ、デバイスが複数のテクスチャ ブレンディングに同時に使用できるテクスチャ座標セットの総数を示す (どの頂点に対しても最大 8 つのテクスチャ座標セットを使用できるが、デバイスでは指定された個数のテクスチャ座標セットのみブレンディングできる)。
TextureOpCaps
このデバイスがサポートするテクスチャ処理を示すフラグの組み合わせ。以下のフラグが定義されている。
D3DTEXOPCAPS_ADD
D3DTOP_ADD テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_ADDSIGNED
D3DTOP_ADDSIGNED テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_ADDSIGNED2X
D3DTOP_ADDSIGNED2X テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_ADDSMOOTH
D3DTOP_ADDSMOOTH テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_BLENDCURRENTALPHA
D3DTOP_BLENDCURRENTALPHA テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_BLENDDIFFUSEALPHA
D3DTOP_BLENDDIFFUSEALPHA テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_BLENDFACTORALPHA
D3DTOP_BLENDFACTORALPHA テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_BLENDTEXTUREALPHA
D3DTOP_BLENDTEXTUREALPHA テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_BLENDTEXTUREALPHAPM
D3DTOP_BLENDTEXTUREALPHAPM テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_BUMPENVMAP
D3DTOP_BUMPENVMAP テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_BUMPENVMAPLUMINANCE
D3DTOP_BUMPENVMAPLUMINANCE テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_DISABLE
D3DTOP_DISABLE テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_DOTPRODUCT3
D3DTOP_DOTPRODUCT3 テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_LERP
D3DTOP_LERP テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_MODULATE
D3DTOP_MODULATE テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_MODULATE2X
D3DTOP_MODULATE2X テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_MODULATE4X
D3DTOP_MODULATE4X テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_MODULATEALPHA_ADDCOLOR
D3DTOP_MODULATEALPHA_ADDCOLOR テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_MODULATECOLOR_ADDALPHA
D3DTOP_MODULATECOLOR_ADDALPHA テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_MODULATEINVALPHA_ADDCOLOR
D3DTOP_MODULATEINVALPHA_ADDCOLOR テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_MODULATEINVCOLOR_ADDALPHA
D3DTOP_MODULATEINVCOLOR_ADDALPHA テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_MULTIPLYADD
D3DTOP_MULTIPLYADD テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_PREMODULATE
D3DTOP_PREMODULATE テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_SELECTARG1
D3DTOP_SELECTARG1 テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_SELECTARG2
D3DTOP_SELECTARG2 テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_SUBTRACT
D3DTOP_SUBTRACT テクスチャ ブレンディング処理がサポートされる。
MaxTextureBlendStages
サポートされるテクスチャ ブレンディング ステージの最大数。この値は、使用可能なブレンダの数である。DirectX 8.0 のプログラム可能ピクセル パイプラインでは、これは、この特定の実装のピクセル シェーダによってサポートされている命令数に対応する。
MaxSimultaneousTextures
テクスチャ ブレンディング ステージに同時にバインドできるテクスチャの最大数。この値は、シングル パスで使用できるテクスチャの数である。DirectX 8.0 のプログラム可能ピクセル シェーダでは、これは特定のハードウェアのピクセル シェーダによってサポートされるテクスチャ レジスタの数、および使用できるテクスチャ宣言命令の数を示す。
VertexProcessingCaps
頂点の処理能力。任意の物理デバイスの場合、この能力は、IDirect3D8::CreateDevice に指定されたパラメータに応じて、Direct3D Device Object 間で異なることがある。
D3DVTXPCAPS_DIRECTIONALLIGHTS
デバイスはディレクショナル ライトをサポートする。
D3DVTXPCAPS_LOCALVIEWER
デバイスはローカル ビューアをサポートする。
D3DVTXPCAPS_MATERIALSOURCE7
デバイスは選択可能な頂点カラー ソースをサポートする。
D3DVTXPCAPS_POSITIONALLIGHTS
デバイスは局部ライト (ポイント ライト、スポット ライトなど) をサポートする。
D3DVTXPCAPS_TEXGEN
デバイスはテクスチャ座標を生成できる。
D3DVTXPCAPS_TWEENING
デバイスは頂点トゥイーニングをサポートする。
D3DVTXPCAPS_NO_VSDT_UBYTE4
デバイスは、D3DVSDT_UBYTE4 頂点宣言タイプをサポートしない。
MaxActiveLights
同時にアクティブにできるライトの最大数。任意の物理デバイスの場合、この能力は、IDirect3D8::CreateDevice に指定されたパラメータに応じて、Direct3D Device Object 間で異なることがある。
MaxUserClipPlanes
サポートされるユーザー定義クリップ面の最大数。このメンバは 0 から D3DMAXUSERCLIPPLANES までの範囲になる。任意の物理デバイスの場合、この能力は、IDirect3D8::CreateDevice に指定されたパラメータに応じて、Direct3D Device Object 間で異なることがある。
MaxVertexBlendMatrices
複数の行列による頂点ブレンディングを実行する際にデバイスが適用できる行列の最大数。任意の物理デバイスの場合、この能力は、IDirect3D8::CreateDevice に指定されたパラメータに応じて、Direct3D Device Object 間で異なることがある。
MaxVertexBlendMatrixIndex
頂点単位のインデックスを使ってインデックス付けできる最大の行列インデックスを示す DWORD 値。行列の数は MaxVertexBlendMatrixIndex + 1 で、これは行列パレットのサイズである。ライティングにブレンディングする必要のある頂点データに法線が存在する場合、行列の数は、この能力フラグで示されている数の半分になる。MaxVertexBlendMatrixIndex に 0 が設定されている場合、ドライバはインデックス付き頂点ブレンディングをサポートしていない。この値が 0 でない場合、インデックスの有効な範囲は 0 から MaxVertexBlendIndexedMatrices までである。

MaxVertexBlendMatrixIndex の値が 0 の場合は、ドライバがインデックス付き行列をサポートしていないことを示す。

ソフトウェア頂点処理が使われている場合は、法線ブレンディングがあってもなくても、256 個の行列をインデックス付き頂点ブレンディングに使用できる。

任意の物理デバイスの場合、この能力は、IDirect3D8::CreateDevice に指定されたパラメータに応じて、Direct3D Device Object 間で異なることがある。

MaxPointSize
ポイント プリミティブの最大サイズ。1.0f に設定されている場合、デバイスはポイント サイズの制御をサポートしていない。範囲は 1.0f 以上である。
MaxPrimitiveCount
DrawPrimitive の各呼び出しの最大プリミティブ数。
MaxVertexIndex
ハードウェア頂点処理に対してサポートされるインデックスの最大サイズ。D3DFMT_INDEX32 を指定して 32 ビット インデックス バッファを作成できる。ただし、この値が 0x0000FFFF よりも大きくない場合は、インデックス バッファを使ってレンダリングできない。
MaxStreams
IDirect3DDevice8::SetStreamSource に対する同時データ ストリームの最大数。有効範囲は 1 ～ 16 である。この値が 0 の場合、DirectX 8.0 ドライバではないことに注意する。
MaxStreamStride
IDirect3DDevice8::SetStreamSource の最大ストライド。
VertexShaderVersion
頂点シェーダのバージョン。デバイスがサポートする頂点シェーダのレベルを示す。IDirect3DDevice8::CreateVertexShader の呼び出しは、このメンバの値以下のバージョン番号の頂点シェーダを指定した場合にのみ成功する。CreateVertexShader に対するシェーダ レベルの指定は、頂点シェーダ トークン ストリームの第 1 トークンで行われる。
  • DirectX 7.0 機能は 0。
  • DirectX 8.0 機能は 01。

主なバージョン番号は、セカンド バイトにエンコードされる。下位バイトには、サブバージョンの番号が含まれる。

MaxVertexShaderConst
頂点シェーダの定数レジスタの数。
PixelShaderVersion
ピクセル シェーダのバージョン。デバイスがサポートするピクセル シェーダのレベルを示す。IDirect3DDevice8::CreatePixelShader の呼び出しは、このメンバの値以下のバージョン番号のピクセル シェーダを指定した場合にのみ成功する。
  • DirectX 8.0 機能は 01。

主なバージョン番号は、セカンド バイトにエンコードされる。下位バイトには、サブバージョンの番号が含まれる。

MaxPixelShaderValue
ピクセル シェーダの算術コンポーネントの最大値。この値は、ピクセル カラー ブレンディング処理でサポートされる値の内部範囲を示す。レポートされる範囲内では、データが変更 (制限) されずにピクセル処理に渡される必要がある。通常、このメンバの値は絶対値である。たとえば、1.0 は -1.0 ～ 1 の範囲を示し、8.0 は -8.0 ～ 8.0 の範囲を示す。この値が 0.0 の場合、符号付きの範囲がサポートされていないことを示し、範囲は DirectX 6.0 および 7.0 と同様に 0 ～ 1.0 になる。

注意

MaxTextureBlendStages メンバと MaxSimultaneousTextures メンバは同じもののように見えるが、互いに異なる情報を含んでいる。MaxTextureBlendStages メンバは、現在のデバイスでサポートされるテクスチャ ブレンディング ステージの総数を示し、MaxSimultaneousTextures メンバは、IDirect3DDevice8::SetTexture メソッドを使ってこれらのステージのうち何個のステージでテクスチャをバインドできるかを示す。

ドライバがこの構造体に値を設定する場合、能力の取得に使用するインターフェイス (IDirect3DDevice8 など) が実行バッファをサポートしていなくても、実行バッファ能力の値が設定される場合がある。

D3DCAPS2_NO2DDURING3DSCENE 能力フラグを設定するシステムの場合は、テクスチャを使用し、シーン中に変更するとパフォーマンスの問題が発生することがある。これはすべてのハードウェアに該当するが、D3DCAPS2_NO2DDURING3DSCENE 能力を公開するハードウェアでより深刻である。ハードウェアに D3DCAPS2_NO2DDURING3DSCENE が存在する場合、アプリケーション ベースのテクスチャ管理では、現在の BeginScene と EndScene ブロック内で使用されているテクスチャが、本当に必要でない限り、除外されないようにしなければならない。シーンでテクスチャを多用している場合、結果は不定である。これは、シーンで使用したテクスチャを変更する場合に、利用可能なテクスチャ メモリが不足すると発生する。このようなシステムでは、Z バッファの内容は EndScene で無効になる。アプリケーションは、このタイプのハードウェア上では、BeginScene と EndScene の間で、バック バッファへの、またはバック バッファからの IDirect3DDevice8::CopyRects を呼び出すべきではない。さらに、D3DPRASTERCAPS_ZBUFFERLESSHSR 能力フラグが設定されている場合、アプリケーションは Z バッファにアクセスすべきではない。最後に、アプリケーションは BeginScene と EndScene のペアの間で、バック バッファまたは Z バッファをロックすべきではない。

次に示すミップマップ テクスチャ関連のフラグは、DirectX 8.0 ではサポートされていない。

  • D3DPTFILTERCAPS_NEAREST
  • D3DPTFILTERCAPS_LINEAR
  • D3DPTFILTERCAPS_MIPNEAREST
  • D3DPTFILTERCAPS_MIPLINEAR
  • D3DPTFILTERCAPS_LINEARMIPNEAREST
  • D3DPTFILTERCAPS_LINEARMIPLINEAR

動作環境

ヘッダー : D3d8caps.h で宣言。

参照

IDirect3D8::GetDeviceCaps、IDirect3DDevice8::GetDeviceCaps


D3DCLIPSTATUS8

現在のクリップ ステータスを記述する。

typedef struct _D3DCLIPSTATUS8 {
   DWORD ClipUnion;
   DWORD ClipIntersection;
} D3DCLIPSTATUS8;

メンバ

ClipUnion
現在のクリップ ステータスを示すクリップ結合フラグ。このメンバには、次の 1 つ以上のフラグを設定できる。
D3DCS_ALL
すべてのクリップ フラグの組み合わせ。
D3DCS_BACK
すべての頂点を視錐台の背面でクリッピングする。
D3DCS_BOTTOM
すべての頂点を視錐台の底面でクリッピングする。
D3DCS_FRONT
すべての頂点を視錐台の前面でクリッピングする。
D3DCS_LEFT
すべての頂点を視錐台の左側面でクリッピングする。
D3DCS_RIGHT
すべての頂点を視錐台の右側面でクリッピングする。
D3DCS_TOP
すべての頂点を視錐台の上面でクリッピングする。
D3DCS_PLANE0 through D3DCS_PLANE5
アプリケーションで定義されているクリップ面。
ClipIntersection
現在のクリップ ステータスを示すクリップ交点フラグ。このメンバの値は、ClipUnion と同じフラグである。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

IDirect3DDevice8::GetClipStatus、IDirect3DDevice8::SetClipStatus


D3DCOLORVALUE

カラー値を記述する。

typedef struct _D3DCOLORVALUE {
    float r;
    float g;
    float b;
    float a;
} D3DCOLORVALUE;

メンバ

r、g、b、および a
色の赤、緑、青、およびアルファの各成分を指定する浮動小数点値。一般に、これらの値は 0.0 から 1.0 までの値で、0.0 は黒である。

注意

特殊なエフェクトを出すために、この構造体のメンバを 0 から 1 の範囲外の値に設定することができる。1 より大きい値は、シーンを洗い流すような強い光を生む。マイナスの値は暗い光を生み、実際には光をシーンから除いてしまう。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

ライティングとマテリアルのカラー値


D3DDEVICE_CREATION_PARAMETERS

デバイスの作成パラメータを記述する。

typedef struct _D3DDEVICE_CREATION_PARAMETERS {
    UINT          AdapterOrdinal;
    D3DDEVTYPE    DeviceType;
    DWORD         hFocusWindow;
    HWND          BehaviorFlags;
} D3DDEVICE_CREATION_PARAMETERS;

メンバ

AdapterOrdinal
ディスプレイ アダプタを示す序数。D3DADAPTER_DEFAULT は常にプライマリ ディスプレイ アダプタである。

任意の IDirect3D8 メソッドの Adapter パラメータには、この序数を使用する。Direct3D8 オブジェクトのインスタンスが異なると使用する序数が異なる場合があることに注意する。たとえば、ユーザーがマルチ モニタ システムにモニタを追加したりシステムからモニタを外したために、またはラップトップをホット スワップしたために、アダプタがシステムに加えられたり除かれたりする場合がある。したがって、この序数は有効であることがわかっている Direct3D8 においてのみ使用しなければならない。有効な Direct3D8 インスタンスは、この IDirect3DDevice8 インターフェイスを作成した Direct3D8 と、この IDirect3DDevice8 インターフェイスを介して呼び出されたときに IDirect3DDevice8::GetDirect3D から返される Direct3D8 の 2 つのみである。

DeviceType
D3DDEVTYPE 列挙型のメンバ。このデバイスに対してエミュレートされるすべての機能を示す。このパラメータの値には、このデバイスを作成した IDirect3D8::CreateDevice の呼び出しに渡された値がそのまま示される。
hFocusWindow
この Microsoft® Direct3D® デバイスでフォーカスを設定するウィンドウ ハンドル。このパラメータの値には、このデバイスを作成した IDirect3D8::CreateDevice の呼び出しに渡された値がそのまま示される。
BehaviorFlags
Microsoft® Direct3D® デバイスの全体的な動作を制御する次のフラグの組み合わせ。
D3DCREATE_FPU_PRESERVE
呼び出し側アプリケーションは、アプリケーションから認識できるような方法で Direct3D が FPU の状態を変更することを望まない。このモードでは、Direct3D は、FPU の状態を変更する必要があるたびに、FPU の状態を保存および復元する。
D3DCREATE_HARDWARE_VERTEXPROCESSING
ハードウェア頂点処理を指定する。
D3DCREATE_MIXED_VERTEXPROCESSING
混合 (ソフトウェアとハードウェア両方) の頂点処理を指定する。
D3DCREATE_MULTITHREADED
マルチスレッドの確実な動作を要求する。これにより、Direct3D は頻繁にグローバルクリティカル セックションを取得するようになる。
D3DCREATE_PUREDEVICE
ハードウェアのラスタ化、トランスフォーム、ライティング、およびシェーディングを指定する。
D3DCREATE_SOFTWARE_VERTEXPROCESSING
ソフトウェア頂点処理を指定する。

このパラメータの値には、このデバイスを作成した IDirect3D8::CreateDevice の呼び出しに渡された値がそのまま示される。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

IDirect3DDevice8::GetCreationParameters、IDirect3D8::CreateDevice


D3DDISPLAYMODE

ディスプレイ モードを記述する。

typedef struct _D3DDISPLAYMODE {
    UINT            Width;
    UINT            Height;
    UINT            RefreshRate;
    D3DFORMAT       Format;
} D3DDISPLAYMODE;

メンバ

Width
ピクセル単位で表したスクリーンの幅。
Height
ピクセル単位で表したスクリーンの高さ。
RefreshRate
リフレッシュ レート。この値が 0 の場合、アダプタ デフォルトを示す。
Format
D3DFORMAT 列挙型のメンバ。ディスプレイ モードのサーフェス フォーマットを示す。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

IDirect3D8::EnumAdapterModes、IDirect3D8::GetAdapterDisplayMode、IDirect3DDevice8::GetDisplayMode


D3DGAMMARAMP

赤、緑、青の各ランプのデータを格納する。

typedef struct _D3DGAMMARAMP {
    WORD                red  [256];
    WORD                green[256];
    WORD                blue [256];
} D3DGAMMARAMP;

メンバ

red、green、および blue
赤、緑、および青のガンマ ランプを記述する 256 WORD 要素の配列。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

IDirect3DDevice8::GetGammaRamp、IDirect3DDevice8::SetGammaRamp


D3DINDEXBUFFER_DESC

インデックス バッファを記述する。

typedef struct _D3DINDEXBUFFER_DESC {
    D3DFORMAT           Format;
    D3DRESOURCETYPE     Type;
    DWORD               Usage;
    D3DPOOL             Pool;
    UINT                Size;
} D3DINDEXBUFFER_DESC;

メンバ

Format
D3DFORMAT 列挙型のメンバ。インデックス バッファ データのサーフェス フォーマットを示す。
Type
インデックス バッファとしてのこのリソースを識別する D3DRESOURCETYPE 列挙型のメンバ。
Usage
このリソースの使用方法を指定する、次の 1 つ以上のフラグの組み合わせ。
D3DUSAGE_DONOTCLIP
インデックス バッファの内容が決してクリッピングを要求しないことを示す。
D3DUSAGE_RTPATCHES
高次プリミティブの描画にインデックス バッファを使用するとき設定する。
D3DUSAGE_NPATCHES
N パッチの描画にインデックス バッファを使用するとき設定する。
D3DUSAGE_POINTS
ポイント スプライトまたはインデックス付きポイント リストの描画に、インデックス バッファを使用するとき設定する。
D3DUSAGE_SOFTWAREPROCESSING
バッファがソフトウェア処理で使用されることを示す。
D3DUSAGE_WRITEONLY
インデックス バッファへの書き込み操作しか実行できないことをシステムに通知する。このフラグを使用することにより、ドライバは最適なメモリ領域を選択して効率的に書き込み操作やレンダリングを実行する。この能力を使用して作成されたインデックス バッファからの読み込みを試みると、パフォーマンスが低下する場合がある。
Pool
D3DPOOL 列挙型のメンバ。このインデックス バッファに割り当てられているメモリのクラスを示す。
Size
インデックス バッファのサイズ (バイト単位)。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

IDirect3DIndexBuffer8::GetDesc


D3DLIGHT8

一連のライト プロパティを定義する。

typedef struct _D3DLIGHT8 {
    D3DLIGHTTYPE    Type;
    D3DCOLORVALUE   Diffuse;
    D3DCOLORVALUE   Specular;
    D3DCOLORVALUE   Ambient;
    D3DVECTOR       Position;
    D3DVECTOR       Direction;
    float           Range;
    float           Falloff;
    float           Attenuation0;
    float           Attenuation1;
    float           Attenuation2;
    float           Theta;
    float           Phi;
} D3DLIGHT8;

メンバ

Type
光源の型。この値は D3DLIGHTTYPE 列挙型のメンバのいずれかである。
Diffuse
光源が放出するディフューズ色。このメンバは D3DCOLORVALUE 構造体である。
Specular
光源が放出するスペキュラ色。このメンバは D3DCOLORVALUE 構造体である。
Ambient
光源が放出するアンビエント色。このメンバは D3DCOLORVALUE 構造体である。
Position
ワールド空間内での光源の位置。D3DVECTOR 構造体で指定される。このメンバは、ディレクショナル ライトにおいては意味がなく無視される。
Direction
ワールド空間で光が指す方向。D3DVECTOR 構造体で指定される。このメンバは、ディレクショナル ライトおよびスポット ライトの場合にのみ意味を持つ。このベクトルは正規化する必要はないが、ゼロでない長さを持たねばならない。
Range
光源の有効距離。このメンバの最大許容値は FLT_MAX の平方根である。このメンバはディレクショナル ライトには影響しない。
Falloff
スポット ライトの内部コーン (Thetaで指定される角度) と外部コーンの外側エッジ (Phi で指定される角度) との間で輝度がフォールオフする。

ライティングに対するフォールオフの影響は微妙である。さらに、フォールオフ カーブを描くと多少の性能上のロスを被る。これらの理由により、開発者の多くはこの値を 1.0 に設定する。

Attenuation0、Attenuation1、および Attenuation2

光の輝度が距離によってどのように変化するかを指定する値。 ディレクショナル ライトの場合、減衰値は無視される。これらのメンバは減衰定数を表す。減衰については、「距離の増加によるライトの減衰」を参照すること。これらのメンバに有効な値の範囲は 0.0 から無限大である。ディレクショナル ライト以外の場合、3 つの減衰値すべてを同時に 0.0 に設定してはならない。

Theta
スポット ライトの内部コーン、つまり十分に光で照らされているスポット ライト コーンの角度をラジアン単位で表す。この値は、0 から Phi による指定値の範囲になければならない。
Phi
スポット ライトの外円錐の外側のエッジを定義する角度をラジアン単位で表す。この円錐の外側にある点はスポット ライトでライティングされない。この値は 0 から pi の範囲になければならない。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

IDirect3DDevice8::GetLight、IDirect3DDevice8::SetLight


D3DLINEPATTERN

線パターンを記述する。

typedef struct _D3DLINEPATTERN {
    WORD    wRepeatFactor;
    WORD    wLinePattern;
} D3DLINEPATTERN;

メンバ

wRepeatFactor
wLinePattern メンバで指定する連続した 1 および 0 を繰り返す回数。これにより、アプリケーションでは線パターンを伸縮できる。
wLinePattern
線パターンを指定するビット。たとえば、次の値は点線を生成する。 1100110011001100.

注意

これらの値は、D3DRENDERSTATETYPE 列挙型の D3DRS_LINEPATTERN レンダリング ステートで使用される。

線パターンは線の描き方を指定する。線パターンは、起点の位置に関係なく常に同じである (これは点描とは異なる。点描はオブジェクトのレンダリング方法、つまり透過性の表現方法に影響する)。

線パターンでは、線に沿った 16 個のピクセルのオン/オフ パターンを指定する。wRepeatFactor メンバでは、wLinePattern の各エントリに対して繰り返すピクセルの数を指定する。

動作環境

ヘッダー : D3d8types.h で宣言。


D3DLOCKED_BOX

ロックされたボックス (ボリューム) を記述する。

typedef struct _D3DLOCKED_BOX {
    INT                 RowPitch;
    INT                 SlicePitch;
    void*               pBits;
} D3DLOCKED_BOX;

メンバ

RowPitch
ある行の左端から次の行の左端までのバイト オフセット。
SlicePitch
あるスライスの左上から次の最も深いスライスの左上までのバイト オフセット。
pBits
ボリューム ボックスの先頭へのポインタ。D3DBOX が LockRect の呼び出しに提供されている場合、pBits はボリュームの先頭から適切にオフセットされる。

注意

幅 × 高さの 2D サーフェスのスライスを積み重ねて、幅 × 高さ × 深さのボリュームを作成することで、ボリュームは視覚化することができる。詳細については、「ボリューム テクスチャ リソース」を参照すること。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

IDirect3DVolume8::LockBox、IDirect3DVolumeTexture8::LockBox


D3DLOCKED_RECT

ロックされた矩形領域を記述する。

typedef struct _D3DLOCKED_RECT {
    INT                 Pitch;
    void*               pBits;
} D3DLOCKED_RECT;

メンバ

Pitch
バイト単位で表したサーフェス ピッチ。
pBits
ロック済みビットへのポインタ。RECT が LockRect の呼び出しに提供されている場合、pBits はサーフェスの先頭から適切にオフセットされる。

注意

DXTn フォーマットのピッチは、DirectX 7.0 で返されるものとは異なる。現在は、ブロックの行を指す。たとえば、幅が 16 である場合、ピッチは 4 ブロックになる (DXT1 の場合は 4*8、DXT2-5 の場合は 4*16)。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

IDirect3DCubeTexture8::LockRect、IDirect3DSurface8::LockRect、IDirect3DTexture8::LockRect


D3DMATERIAL8

マテリアル プロパティを指定する。

typedef struct _D3DMATERIAL8 {
    D3DCOLORVALUE   Diffuse;
    D3DCOLORVALUE   Ambient;
    D3DCOLORVALUE   Specular;
    D3DCOLORVALUE   Emissive;
    float           Power;
} D3DMATERIAL8;

メンバ

Diffuse、Ambient、Specular、および Emissive
それぞれ、マテリアルのディフューズ色、アンビエント色、スペキュラ色、エミッション色を指定する値。これらの値は D3DCOLORVALUE 構造体である。
Power
スペキュラ ハイライトの鮮明度を指定する浮動小数点値。マテリアルのスペキュラ ハイライトをオフにするには、このメンバを 0.0 に設定する。スペキュラ色成分を 0 に設定するだけでは不十分である。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

IDirect3DDevice8::GetMaterial、IDirect3DDevice8::SetMaterial


D3DMATRIX

行列を記述する。

typedef struct _D3DMATRIX {
    union {
        struct {
            float        _11, _12, _13, _14;
            float        _21, _22, _23, _24;
            float        _31, _32, _33, _34;
            float        _41, _42, _43, _44;

        };
        float m[4][4];
    };
} D3DMATRIX;

注意

Microsoft® Direct3D® では、射影行列の _34 要素は負にできない。ここで負の値を使用する必要がある場合は、代わりに射影行列全体を -1 でスケールする。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

IDirect3DDevice8::GetTransform、IDirect3DDevice8::MultiplyTransform、IDirect3DDevice8::SetTransform


D3DPRESENT_PARAMETERS

プレゼンテーション パラメータを記述する。

typedef struct _D3DPRESENT_PARAMETERS_ {
    UINT                    BackBufferWidth;
    UINT                    BackBufferHeight;
    D3DFORMAT               BackBufferFormat;
    UINT                    BackBufferCount;

    D3DMULTISAMPLE_TYPE     MultiSampleType;

    D3DSWAPEFFECT           SwapEffect;
    HWND                    hDeviceWindow;
    BOOL                    Windowed;
    BOOL                    EnableAutoDepthStencil;
    D3DFORMAT               AutoDepthStencilFormat;
    DWORD                   Flags;

    UINT                    FullScreen_RefreshRateInHz;
    UINT                    FullScreen_PresentationInterval;

} D3DPRESENT_PARAMETERS;

メンバ

BackBufferWidth および BackBufferHeight
新しいスワップ チェーンのバック バッファの幅と高さ (ピクセル単位)。Windowed が FALSE の場合 (プレゼンテーションはフルスクリーン)、これらの値は、IDirect3D8::EnumAdapterModes によって列挙されたディスプレイ モードのいずれかの幅および高さと一致していなければならない。Windowed が TRUE で、これらの値のいずれかが 0 の場合は、hDeviceWindow (または hDeviceWindow が NULL の場合はフォーカス ウィンドウ) のクライアント領域の対応するディメンジョンが使用される。
BackBufferFormat
D3DFORMAT 列挙型のメンバ。この値は、IDirect3D8::CheckDeviceType で検証されたレンダリング ターゲットのフォーマットのいずれかでなければならない。

Windowed を TRUE に設定する場合、BackBufferFormat の設定は、現在のディスプレイ モードのフォーマットと一致している必要がある。IDirect3DDevice8::GetDisplayMode を使用して、現在のフォーマットを取得する。

BackBufferCount
この値には、0、1、2、または 3 を設定できる。0 は 1 として処理されることに注意する。バック バッファの数を作成できない場合、ランタイムはメソッドの呼び出しに失敗し、作成できたバック バッファ数をこの値に設定する。したがって、アプリケーションは同じ D3DPRESENT_PARAMETERS 構造体を指定してメソッドを 2 回呼び出すことができ、2 回目には呼び出しが成功するものと予想される。

バック バッファの数の最小値は 1 と想定されている。バック バッファを 1 つも作成できない場合、メソッドの呼び出しは失敗する。BackBufferCount の値は、使用可能なスワップ エフェクトのセットに影響を与える。特に、D3DSWAPEFFECT_COPY スワップ エフェクトでは、存在するバック バッファが厳密に 1 つでなければならない。

MultiSampleType
D3DMULTISAMPLE_TYPE 列挙型のメンバ。SwapEffect に D3DSWAPEFFECT_DISCARD が設定されていない場合、この値は D3DMULTISAMPLE_NONE でなければならない。マルチサンプリングは、スワップ エフェクトが D3DSWAPEFFECT_DISCARD の場合にのみサポートされる。
SwapEffect
D3DSWAPEFFECT 列挙型のメンバ。ランタイムは、バッファ スワップ動作に関して指定されているセマンティクスを保証する。したがって、Windowed が TRUE で、SwapEffect が D3DSWAPEFFECT_FLIP に設定されている場合、ランタイムは 1 つ余分にバック バッファを作成し、プレゼンテーション時にフロント バッファになるものをすべてコピーする。

D3DSWAPEFFECT_COPY および D3DSWAPEFFECT_COPY_VSYNC の場合は、BackBufferCount に 1 が設定されていなければならない。

デバッグ ランタイムにおいては、提示した後のバッファにノイズを格納することで、D3DSWAPEFFECT_DISCARD を強制する。

hDeviceWindow
フルスクリーン モードの場合、これはカバー ウィンドウである。ウィンドウ モードの場合、これは IDirect3DDevice8::Present に対するデフォルトのターゲット ウィンドウである。この値が NULL の場合は、フォーカス ウィンドウが使用される。マルチモニタ システムなど、複数のフルスクリーン デバイスを使用するアプリケーションの場合は、正確に 1 つのデバイスがデバイス ウィンドウとしてフォーカス ウィンドウを使用しなければならない。その他のすべてのウィンドウは、一意のデバイス ウィンドウを持つ。それ以外の場合は、動作は定義されておらず、アプリケーションは期待どおりに動作しない。

ランタイムはユーザーによるウィンドウ サイズの変更を反映しようとしないことに、注意する必要がある。このウィンドウがリセットされても、バック バッファが暗黙的にリセットされることはない。ただし、Present メソッドは、ウィンドウ位置の変化を自動的に追跡する。

Windowed
アプリケーションがウィンドウ モードで動作する場合は TRUE で、フルスクリーン モードで動作する場合は FALSE である。
EnableAutoDepthStencil
この値が TRUE の場合、Microsoft® Direct3D® はアプリケーションに対する深度バッファを管理する。デバイスは、作成されると、深度ステンシル バッファを作成する。深度ステンシル バッファは、自動的に、デバイスのレンダリング ターゲットとして設定される。デバイスがリセットされると、深度ステンシル バッファは自動的に破棄されて、新しいサイズで再度作成される。

EnableAutoDepthStencil が TRUE の場合、AutoDepthStencilFormat は有効な深度ステンシル フォーマットでなければならない。

AutoDepthStencilFormat
D3DFORMAT 列挙型のメンバ。デバイスが作成する自動深度ステンシル サーフェスのフォーマットである。EnableAutoDepthStencil が TRUE でない場合、このメンバは無視される。
Flags
このメンバは、0 または次のフラグに設定できる。
D3DPRESENTFLAG_LOCKABLE_BACKBUFFER
アプリケーションがバック バッファを直接ロックする必要がある場合は、このフラグを設定する。IDirect3D8::CreateDevice または IDirect3DDevice8::Reset を呼び出す際に、D3DPRESENTFLAG_LOCKABLE_BACKBUFFER を指定していない場合は、バック バッファはロックできないことに注意する。ロック可能なバック バッファによって、一部のグラフィックス ハードウェア構成ではパフォーマンスのコストが向上する。

ロック可能なバック バッファでロック処理を実行すると (または読み書きに IDirect3DDevice8::CopyRects を使用すると)、多くのカードでパフォーマンスが低下する。この場合、テクスチャ化した三角形を使用してデータをバック バッファに移動することを検討する必要がある。

FullScreen_RefreshRateInHz
ディスプレイ アダプタによるスクリーンのリフレッシュ レート。ウィンドウ モードの場合、この値は 0 でなければならない。それ以外の場合、この値は、IDirect3D8::EnumAdapterModes が返すリフレッシュ レートのいずれか、または次の値のいずれかでなければならない。
D3DPRESENT_RATE_DEFAULT
ランタイムはプレゼンテーション速度を選択する。ウィンドウ モードの場合は、現在の速度を使用する。
D3DPRESENT_RATE_UNLIMITED
プレゼンテーション速度は、ハードウェアがフレームを提供できる速さで動作する。
FullScreen_PresentationInterval
スワップ チェーンのバック バッファをプレゼンテーションできる最大レート。ウィンドウ スワップ チェーンの場合、この値は D3DPRESENT_INTERVAL_DEFAULT (0) でなければならない。フルスクリーン スワップ チェーンの場合は、D3DPRESENT_INTERVAL_DEFAULT、または D3DCAPS8 の PresentationIntervals メンバに列挙されるフラグに対応する値を設定できる。
D3DPRESENT_INTERVAL_IMMEDIATE
プレゼンテーション処理に直接影響する場合がある。ドライバは垂直帰線間隔を待たない。
D3DPRESENT_INTERVAL_ONE
ドライバは垂直帰線間隔を待つ。プレゼンテーション処理への影響は、スクリーン リフレッシュほど頻繁ではない。
D3DPRESENT_INTERVAL_TWO
ドライバは垂直帰線間隔を待つ。プレゼンテーション処理への影響は、スクリーン リフレッシュ (1 回おき) ほど頻繁ではない。
D3DPRESENT_INTERVAL_THREE
ドライバは垂直帰線間隔を待つ。プレゼンテーション処理への影響は、スクリーン リフレッシュ (2 回おき) ほど頻繁ではない。
D3DPRESENT_INTERVAL_FOUR
ドライバは垂直帰線間隔を待つ。プレゼンテーション処理への影響は、スクリーン リフレッシュ (3 回おき) ほど頻繁ではない。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

IDirect3D8::CreateDevice、IDirect3DDevice8::CreateAdditionalSwapChain、IDirect3DDevice8::Present、IDirect3DDevice8::Reset


D3DRANGE

範囲を定義する。

typedef struct _D3DRANGE {
    UINT                Offset;
    UINT                Size;
} D3DRANGE;

メンバ

Offset
バイト単位で表したオフセット。
Size
バイト単位で表したサイズ。

動作環境

ヘッダー : D3d8types.h で宣言。


D3DRASTER_STATUS

ラスタ ステータスを記述する。

typedef struct _D3DRASTER_STATUS {
    BOOL            InVBlank;
    UINT            ScanLine;
} D3DRASTER_STATUS;

メンバ

InVBlank
ラスタが垂直帰線消去間隔にある場合は TRUE である。ラスタが垂直帰線消去間隔にない場合は FALSE である。
ScanLine
InVBlank が FALSE の場合、この値は、ラスタによって描画された現在の走査線にほぼ対応する整数値である。走査線には、Microsoft® Direct3D® のサーフェス座標と同じ方法で番号が付けられている。つまり、0 はプライマリ サーフェスの上端であり、ディスプレイ下端の値 (サーフェスの高さ - 1) に達するまで増加する。

InVBlank が TRUE の場合は、この値は 0 に設定されて無視できる。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

IDirect3DDevice8::GetRasterStatus


D3DRECT

矩形を定義する。

typedef struct _D3DRECT {
    LONG x1;
    LONG y1;
    LONG x2;
    LONG y2;
} D3DRECT;

メンバ

x1 および y1
矩形の左上隅の座標。
x2 および y2
矩形の右下隅の座標。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

IDirect3DDevice8::Clear


D3DRECTPATCH_INFO

矩形の高次パッチを記述する。

typedef struct _D3DRECTPATCH_INFO {
    UINT                StartVertexOffsetWidth;
    UINT                StartVertexOffsetHeight;
    UINT                Width;
    UINT                Height;
    UINT                Stride;
    D3DBASISTYPE        Basis;
    D3DORDERTYPE        Order;
} D3DRECTPATCH_INFO;

メンバ

StartVertexOffsetWidth
頂点の数で表した、開始頂点オフセットの幅。
StartVertexOffsetHeight
頂点の数で表した、開始頂点オフセットの高さ。
Width
頂点の数で表した、各頂点の幅。
Height
頂点の数で表した、各頂点の高さ。
Stride
頂点の数で表した、セグメント間のストライド。
Basis
矩形の高次パッチの基本タイプを定義する D3DBASISTYPE 列挙型のメンバ。
Order
高次パッチのオーダー タイプを定義する D3DORDERTYPE 列挙型のメンバ。

注意

個々の矩形パッチのストリーム (非モザイク) をレンダリングするには、ジオメトリを細く長い (1 × N) 矩形パッチとして解釈しなければならない。このようなストリップ (立方体ベジェ) の D3DRECTPATCH_INFO 構造体は、次のように設定される。

D3DRECTPATCH_INFO RectInfo;

RectInfo.Width = 4;
RectInfo.Height= 4;
RectInfo.Stride= 4;
RectInfo.Basis =  D3DBASIS_BEZIER;
RectInfo.Order =  D3DORDER_CUBIC;
RectInfo.StartVertexOffsetWidth = 0;
RectInfo.StartVertexOffsetHeight = 4*i;  // 変数 i はレンダリングするパッチのインデックスである。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

IDirect3DDevice8::DrawRectPatch


D3DSURFACE_DESC

サーフェスを記述する。

typedef struct _D3DSURFACE_DESC {
    D3DFORMAT           Format;
    D3DRESOURCETYPE     Type;
    DWORD               Usage;
    D3DPOOL             Pool;
    UINT                Size;
    D3DMULTISAMPLE_TYPE MultiSampleType;
    UINT                Width;
    UINT                Height;
} D3DSURFACE_DESC;

メンバ

Format
サーフェス フォーマットを示す D3DFORMAT 列挙型のメンバ。
Type
サーフェスとしてのこのリソースを示す D3DRESOURCETYPE 列挙型のメンバ。
Usage
このリソースの使用方法を指定する、次の 1 つ以上のフラグの組み合わせ。
D3DUSAGE_DEPTHSTENCIL
サーフェスが深度ステンシル サーフェスとして使用されることを示す。
D3DUSAGE_RENDERTARGET
サーフェスがレンダリング ターゲットとして使用されることを示す。
Pool
このサーフェスに割り当てられているメモリのクラスを指定する D3DPOOL 列挙型のメンバ。
Size
バイト単位で表されたサーフェスのサイズ。
MultiSampleType
D3DMULTISAMPLE_TYPE 列挙型のメンバ。サーフェスがサポートするフルシーン マルチサンプリングのレベルを指定する。
Width
ピクセル単位で表したサーフェスの幅。
Height
ピクセル単位で表したサーフェスの高さ。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

IDirect3DCubeTexture8::GetLevelDesc、IDirect3DSurface8::GetDesc、IDirect3DTexture8::GetLevelDesc


D3DTRIPATCH_INFO

三角形の高次パッチを記述する。

typedef struct _D3DTRIPATCH_INFO {
    UINT                StartVertexOffset;
    UINT                NumVertices;
    D3DBASISTYPE        Basis;
    D3DORDERTYPE        Order;
} D3DTRIPATCH_INFO;

メンバ

StartVertexOffset
頂点の数で表した、開始頂点オフセット。
NumVertices
頂点の数。
Basis
三角形の高次パッチの基本タイプを定義する D3DBASISTYPE 列挙型のメンバ。
Order
三角形の高次パッチのオーダー タイプを定義する D3DORDERTYPE 列挙型のメンバ。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

IDirect3DDevice8::DrawTriPatch


D3DVECTOR

ベクトルを定義する。

typedef struct _D3DVECTOR {
    float x;
    float y;
    float z;
} D3DVECTOR;

メンバ

x、y および z
ベクトルを記述する浮動小数点値。

動作環境

ヘッダー : D3d8types.h で宣言。


D3DVERTEXBUFFER_DESC

頂点バッファを記述する。

typedef struct _D3DVERTEXBUFFER_DESC {
    D3DFORMAT           Format;
    D3DRESOURCETYPE     Type;
    DWORD               Usage;
    D3DPOOL             Pool;
    UINT                Size;
    DWORD               FVF;
} D3DVERTEXBUFFER_DESC;

メンバ

Format
頂点バッファ データのサーフェス フォーマットを示す D3DFORMAT 列挙型のメンバ。
Type
頂点バッファとしてのこのリソースを識別する D3DRESOURCETYPE 列挙型のメンバ。
Usage
このリソースの使用方法を指定する、次の 1 つ以上のフラグの組み合わせ。
D3DUSAGE_DONOTCLIP
頂点バッファの内容が決してクリッピングを要求しないことを示す。
D3DUSAGE_RTPATCHES
高次プリミティブの描画に頂点バッファを使用するとき設定する。
D3DUSAGE_NPATCHES
N パッチの描画に頂点バッファを使用するとき設定する。
D3DUSAGE_POINTS
ポイント スプライトまたはインデックス付きポイント リストの描画に、頂点バッファを使用するとき設定する。
D3DUSAGE_SOFTWAREPROCESSING
ソフトウェア頂点処理で使用する頂点バッファであることを示す。
D3DUSAGE_WRITEONLY
頂点バッファへの書き込み操作しか実行しないことをシステムに知らせる。このフラグを使用することにより、ドライバは最適なメモリ領域を選択して効率的に書き込み操作やレンダリングを実行する。この能力を利用して作成した頂点バッファから読み出しを行おうとすると、パフォーマンスが低下することがある。
Pool
この頂点バッファに割り当てられているメモリのクラスを指定する D3DPOOL 列挙型のメンバ。
Size
頂点バッファのサイズ (バイト単位)。
FVF
このバッファ内の頂点の頂点フォーマットを示す柔軟な頂点フォーマット フラグの組み合わせ。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

IDirect3DVertexBuffer8::GetDesc


D3DVIEWPORT8

3D ボリュームが射影されるレンダリング ターゲット サーフェスのウィンドウの大きさを定義する。

typedef struct _D3DVIEWPORT8 {
    DWORD       X;
    DWORD       Y;
    DWORD       Width;
    DWORD       Height;
    float       MinZ;
    float       MaxZ;
} D3DVIEWPORT8;

メンバ

X および Y
レンダリング ターゲット サーフェス上のビューポートの左上隅を表すピクセル座標。サーフェスのサブセットにレンダリングするのでなければ、これらのメンバは 0 に設定できる。
Width および Height
レンダリング ターゲット サーフェス上のビューポートのディメンジョン (ピクセル単位)。サーフェスのサブセットに限定してレンダリングするのでなければ、これらのメンバにはレンダリング ターゲット サーフェスのディメンジョンを設定する。
MinZ および MaxZ
シーンをレンダリングする深度値の範囲を示す値。クリップ ボリュームの最小値と最大値。ほとんどのアプリケーションでは、これらの値をそれぞれ 0.0 および 1.0 に設定する。射影行列の適用後にクリッピングが行われる。

注意

X、Y、Width、および Height の各メンバは、レンダリング ターゲット サーフェス上のビューポートの位置とディメンジョンを記述する。通常、アプリケーションはターゲット サーフェス全体にレンダリングするので、640 x 480 のサーフェスにレンダリングするとき、これらのメンバはそれぞれ 0、0、640、480 になる。一般に、MinZ および MaxZ は 0.0 および 1.0 に設定されるが、ほかの値を設定して特殊効果を出すこともできる。たとえば、両方の値を 0.0 に設定すると、シーンのフォアグラウンドにオブジェクトがレンダリングされる。また、両方の値を 1.0 に設定すると、オブジェクトがバックグラウンドにレンダリングされる。

デバイスのビューポート パラメータを変更すると (IDirect3DDevice8::SetViewport メソッドの呼び出しにより)、ドライバは新しいトランスフォーム行列を作成する。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

IDirect3DDevice8::GetViewport、IDirect3DDevice8::SetViewport


D3DVOLUME_DESC

ボリュームを記述する。

typedef struct _D3DVOLUME_DESC {
    D3DFORMAT           Format;
    D3DRESOURCETYPE     Type;
    DWORD               Usage;
    D3DPOOL             Pool;
    UINT                Size;
    UINT                Width;
    UINT                Height;
    UINT                Depth;
} D3DVOLUME_DESC;

メンバ

Format
ボリュームのサーフェス フォーマットを示す D3DFORMAT 列挙型のメンバ。
Type
ボリュームとしてのこのリソースを識別する D3DRESOURCETYPE 列挙型のメンバ。
Usage
現在は使用されていない。常に 0 が返される。
Pool
このボリュームに割り当てられているメモリのクラスを指定する D3DPOOL 列挙型のメンバ。
Size
バイト単位で表されたボリュームのサイズ。
Width
ピクセル単位で表されたボリュームの幅。
Height
ピクセル単位で表されたボリュームの高さ。
Depth
ピクセル単位で表されたボリュームの深度。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

IDirect3DVolume8::GetDesc、IDirect3DVolumeTexture8::GetLevelDesc


列挙型

ここでは、Microsoft® Direct3D® で使用される以下の列挙型について記述する。

  • D3DBACKBUFFER_TYPE
  • D3DBLEND
  • D3DBLENDOP
  • D3DCMPFUNC
  • D3DCUBEMAP_FACES
  • D3DCULL
  • D3DDEBUGMONITORTOKENS
  • D3DDEVTYPE
  • D3DFILLMODE
  • D3DFOGMODE
  • D3DFORMAT
  • D3DBASISTYPE
  • D3DLIGHTTYPE
  • D3DMATERIALCOLORSOURCE
  • D3DMULTISAMPLE_TYPE
  • D3DORDERTYPE
  • D3DPATCHEDGESTYLE
  • D3DPOOL
  • D3DPRIMITIVETYPE
  • D3DRENDERSTATETYPE
  • D3DRESOURCETYPE
  • D3DSHADEMODE
  • D3DSTATEBLOCKTYPE
  • D3DSTENCILOP
  • D3DSWAPEFFECT
  • D3DTEXTUREADDRESS
  • D3DTEXTUREFILTERTYPE
  • D3DTEXTUREOP
  • D3DTEXTURESTAGESTATETYPE
  • D3DTEXTURETRANSFORMFLAGS
  • D3DTRANSFORMSTATETYPE
  • D3DVERTEXBLENDFLAGS
  • D3DZBUFFERTYPE


D3DBACKBUFFER_TYPE

バック バッファのタイプを記述する定数を定義する。

typedef enum _D3DBACKBUFFER_TYPE {
    D3DBACKBUFFER_TYPE_MONO         = 0,
    D3DBACKBUFFER_TYPE_LEFT         = 1,
    D3DBACKBUFFER_TYPE_RIGHT        = 2,

    D3DBACKBUFFER_TYPE_FORCE_DWORD  = 0x7fffffff
} D3DBACKBUFFER_TYPE;

定数

D3DBACKBUFFER_TYPE_MONO
非ステレオ スワップ チェーンを指定する。
D3DBACKBUFFER_TYPE_LEFT
スワップ チェーンのステレオ ペアの左側を指定する。
D3DBACKBUFFER_TYPE_RIGHT
スワップ チェーンのステレオ ペアの右側を指定する。
D3DBACKBUFFER_TYPE_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

注意

DirectX 8.0 ではステレオ ビューはサポートされていないので、この列挙型の D3DBACKBUFFER_TYPE_LEFT および D3DBACKBUFFER_TYPE_RIGHT の値は Direct3D では使用されない。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

IDirect3DDevice8::GetBackBuffer、IDirect3DSwapChain8::GetBackBuffer


D3DBLEND

サポートされているブレンディング モードを定義する。

typedef enum _D3DBLEND {
    D3DBLEND_ZERO               =  1,
    D3DBLEND_ONE                =  2,
    D3DBLEND_SRCCOLOR           =  3,
    D3DBLEND_INVSRCCOLOR        =  4,
    D3DBLEND_SRCALPHA           =  5,
    D3DBLEND_INVSRCALPHA        =  6,
    D3DBLEND_DESTALPHA          =  7,
    D3DBLEND_INVDESTALPHA       =  8,
    D3DBLEND_DESTCOLOR          =  9,
    D3DBLEND_INVDESTCOLOR       = 10,
    D3DBLEND_SRCALPHASAT        = 11,
    D3DBLEND_BOTHSRCALPHA       = 12,
    D3DBLEND_BOTHINVSRCALPHA    = 13,

    D3DBLEND_FORCE_DWORD        = 0x7fffffff
} D3DBLEND;

定数

D3DBLEND_ZERO
ブレンディング係数は (0, 0, 0, 0)。
D3DBLEND_ONE
ブレンディング係数は (1, 1, 1, 1)。
D3DBLEND_SRCCOLOR
ブレンディング係数は (Rs, Gs, Bs, As)。
D3DBLEND_INVSRCCOLOR
ブレンディング係数は (1-Rs, 1-Gs, 1-Bs, 1-As)。
D3DBLEND_SRCALPHA
ブレンディング係数は (As, As, As, As)。
D3DBLEND_INVSRCALPHA
ブレンディング計数は (1-As, 1-As, 1-As, 1-As)。
D3DBLEND_DESTALPHA
ブレンディング係数は (Ad, Ad, Ad, Ad)。
D3DBLEND_INVDESTALPHA
ブレンディング計数は (1-Ad, 1-Ad, 1-Ad, 1-Ad)。
D3DBLEND_DESTCOLOR
ブレンディング係数は (Rd, Gd, Bd, Ad)。
D3DBLEND_INVDESTCOLOR
ブレンディング計数は (1-Rd, 1-Gd, 1-Bd, 1-Ad)。
D3DBLEND_SRCALPHASAT
ブレンディング係数は、(f, f, f, 1)、f = min(As, 1-Ad)。
D3DBLEND_BOTHSRCALPHA
廃止されている。Microsoft® DirectX® 6.0 以降では、転送元および転送先のブレンディング係数に D3DBLEND_SRCALPHA と D3DBLEND_INVSRCALPHA をそれぞれ別の呼び出しで設定することにより、同じ効果を得ることができる。
D3DBLEND_BOTHINVSRCALPHA
転送元のブレンディング係数は (1-As, 1-As, 1-As, 1-As) で、転送先のブレンディング係数は (As, As, As, As) である。転送先のブレンディングの選択は無効になる。このブレンディング モードは、D3DRS_SRCBLEND レンダリング ステートに対してのみサポートされる。
D3DBLEND_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

注意

前述のメンバの説明では、転送元および転送先の RGBA 値は添字 s および d によって示される。

この列挙型の値は、D3DRS_DESTBLEND レンダリング ステートによって使用される。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

D3DRENDERSTATETYPE


D3DBLENDOP

サポートされているブレンディング処理を定義する。

typedef enum _D3DBLENDOP {
    D3DBLENDOP_ADD              = 1,
    D3DBLENDOP_SUBTRACT         = 2,
    D3DBLENDOP_REVSUBTRACT      = 3,
    D3DBLENDOP_MIN              = 4,
    D3DBLENDOP_MAX              = 5,

    D3DBLENDOP_FORCE_DWORD      = 0x7fffffff
} D3DBLENDOP;

定数

D3DBLENDOP_ADD
結果は転送元に転送先が加算される。

結果 = 転送元 + 転送先

D3DBLENDOP_SUBTRACT
結果は転送元から転送先が減算される。

結果 = 転送元 - 転送先

D3DBLENDOP_REVSUBTRACT
結果は転送先から転送元が減算される。

結果 = 転送先 - 転送元

D3DBLENDOP_MIN
結果は転送元と転送先の最小値である。

結果 = MIN(転送元, 転送先)

D3DBLENDOP_MAX
結果は転送元と転送先の最大値である。

結果 = MAX(転送元, 転送先)

D3DBLENDOP_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

注意

この列挙型は、D3DRS_BLENDOP レンダリング ステートで使用される値を定義する。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

D3DPRIMCAPS8、D3DRENDERSTATETYPE


D3DCMPFUNC

サポートされる比較関数を定義する。

typedef enum _D3DCMPFUNC {
    D3DCMP_NEVER                = 1,
    D3DCMP_LESS                 = 2,
    D3DCMP_EQUAL                = 3,
    D3DCMP_LESSEQUAL            = 4,
    D3DCMP_GREATER              = 5,
    D3DCMP_NOTEQUAL             = 6,
    D3DCMP_GREATEREQUAL         = 7,
    D3DCMP_ALWAYS               = 8,

    D3DCMP_FORCE_DWORD          = 0x7fffffff
} D3DCMPFUNC;

定数

D3DCMP_NEVER
テストは常に失敗する。
D3DCMP_LESS
新しいピクセル値が、現在のピクセル値より小さいときに応じる。
D3DCMP_EQUAL
新しいピクセル値が、現在のピクセル値と等しいときに応じる。
D3DCMP_LESSEQUAL
新しいピクセル値が、現在のピクセル値以下のときに応じる。
D3DCMP_GREATER
新しいピクセル値が、現在のピクセル値より大きいときに応じる。
D3DCMP_NOTEQUAL
新しいピクセル値が、現在のピクセル値と等しくないときに応じる。
D3DCMP_GREATEREQUAL
新しいピクセル値が、現在のピクセル値以上のときに応じる。
D3DCMP_ALWAYS
テストは常にパスする。
D3DCMP_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

注意

この列挙型の値は、D3DRS_ZFUNC、D3DRS_ALPHAFUNC、および D3DRS_STENCILFUNC の各レンダリング ステートに対してサポートされる比較関数を定義するものである。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

D3DRENDERSTATETYPE


D3DCUBEMAP_FACES

キューブマップの面を定義する。

typedef enum _D3DCUBEMAP_FACES {
    D3DCUBEMAP_FACE_POSITIVE_X     = 0,
    D3DCUBEMAP_FACE_NEGATIVE_X     = 1,
    D3DCUBEMAP_FACE_POSITIVE_Y     = 2,
    D3DCUBEMAP_FACE_NEGATIVE_Y     = 3,
    D3DCUBEMAP_FACE_POSITIVE_Z     = 4,
    D3DCUBEMAP_FACE_NEGATIVE_Z     = 5,

    D3DCUBEMAP_FACE_FORCE_DWORD    = 0xffffffff
} D3DCUBEMAP_FACES;

定数

D3DCUBEMAP_FACE_POSITIVE_X
キューブマップの正方向の x 面。
D3DCUBEMAP_FACE_NEGATIVE_X
キューブマップの負方向の x 面。
D3DCUBEMAP_FACE_POSITIVE_Y
キューブマップの正方向の y 面。
D3DCUBEMAP_FACE_NEGATIVE_Y
キューブマップの負方向の y 面。
D3DCUBEMAP_FACE_POSITIVE_Z
キューブマップの正方向の z 面。
D3DCUBEMAP_FACE_NEGATIVE_Z
キューブマップの負方向の z 面。
D3DCUBEMAP_FACE_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

IDirect3DCubeTexture8::AddDirtyRect、IDirect3DCubeTexture8::GetCubeMapSurface、IDirect3DCubeTexture8::LockRect、IDirect3DCubeTexture8::UnlockRect


D3DCULL

サポートするカリング モードを定義する。

typedef enum _D3DCULL {
    D3DCULL_NONE                = 1,
    D3DCULL_CW                  = 2,
    D3DCULL_CCW                 = 3,

    D3DCULL_FORCE_DWORD         = 0x7fffffff
} D3DCULL;

定数

D3DCULL_NONE
背面のカリングはしない。
D3DCULL_CW
背面を右回りにカリングする。
D3DCULL_CCW
背面を左回りにカリングする。
D3DCULL_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

注意

この列挙型の値は、D3DRS_CULLMODE レンダリング ステートによって使用される。カリング モードは、ジオメトリをレンダリングするときの背面のカリング方法を定義する。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

D3DPRIMCAPS8、D3DRENDERSTATETYPE


D3DDEBUGMONITORTOKENS

デバッグ モニタ トークンを定義する。

typedef enum _D3DDEBUGMONITORTOKENS {
    D3DDMT_ENABLE          = 0,
    D3DDMT_DISABLE         = 1,

    D3DDMT_FORCE_DWORD     = 0x7fffffff
} D3DDEBUGMONITORTOKENS;

定数

D3DDMT_ENABLE
デバッグ モニタを有効にする。
D3DDMT_DISABLE
デバッグ モニタを無効にする。
D3DDMT_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

注意

この列挙型の値は、D3DRS_DEBUGMONITORTOKEN レンダリング ステートでのみ使用され、デバッグ ビルドにのみ関連する。

動作環境

ヘッダー : d3d8types.h で宣言。

参照

D3DRENDERSTATETYPE


D3DDEVTYPE

デバイスの種類を定義する。

typedef enum _D3DDEVTYPE {
    D3DDEVTYPE_HAL         = 1,
    D3DDEVTYPE_REF         = 2,
    D3DDEVTYPE_SW          = 3,

    D3DDEVTYPE_FORCE_DWORD = 0xffffffff
} D3DDEVTYPE;

定数

D3DDEVTYPE_HAL
ラスタ化とシェーディングはハードウェアで行い、トランスフォームとライティングにはソフトウェア、ハードウェア、またはその両方を使用する。
D3DDEVTYPE_REF
Microsoft® Direct3D® の機能はソフトウェアに実装されている。ただし、リファレンス ラスタライザは、利用可能な場合は常に、特別な CPU 命令を利用する。
D3DDEVTYPE_SW
IDirect3D8::RegisterSoftwareDevice を使用して Direct3D に登録されたプラグ可能なソフトウェア デバイス。
D3DDEVTYPE_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

IDirect3D8::CheckDeviceFormat、IDirect3D8::CheckDeviceMultiSampleType、IDirect3D8::CheckDeviceType、IDirect3D8::CreateDevice、IDirect3D8::GetDeviceCaps、D3DDEVICE_CREATION_PARAMETERS


D3DFILLMODE

塗りつぶしモードを記述する定数を定義する。

typedef enum _D3DFILLMODE {
    D3DFILL_POINT               = 1,
    D3DFILL_WIREFRAME           = 2,
    D3DFILL_SOLID               = 3,

    D3DFILL_FORCE_DWORD         = 0x7fffffff
} D3DFILLMODE;

定数

D3DFILL_POINT
点で塗りつぶす。
D3DFILL_WIREFRAME
ワイヤフレームで塗りつぶす。現在、この塗りつぶしモードは、DrawPrimitive メソッドの使用時、クリップされたプリミティブでは動作しない。
D3DFILL_SOLID
面で塗りつぶす。
D3DFILL_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

注意

この列挙型の値は、D3DRS_FILLMODE レンダリング ステートによって使用される。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

D3DRENDERSTATETYPE


D3DFOGMODE

フォグ モードを記述する定数を定義する。

typedef enum _D3DFOGMODE {
    D3DFOG_NONE                 = 0,
    D3DFOG_EXP                  = 1,
    D3DFOG_EXP2                 = 2,
    D3DFOG_LINEAR               = 3,

    D3DFOG_FORCE_DWORD          = 0x7fffffff
} D3DFOGMODE;

定数

D3DFOG_NONE
フォグ エフェクトはない。
D3DFOG_EXP
次の方程式の指数で、フォグ エフェクトが増す。

D3DFOG_EXP2
次の方程式の指数の 2 乗で、フォグ エフェクトが増す。

D3DFOG_LINEAR
次の方程式の始点と終点の間で線形にフォグ エフェクトが増す。

これは、現在サポートされている唯一のフォグ モードである。

D3DFOG_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

注意

この列挙型の値は、D3DRS_FOGTABLEMODE および D3DRS_FOGVERTEXMODE のレンダリング ステートによって使用される。

フォグは、透明度を表す基準である。この場合、フォグの方程式によって生成されるフォグの値が小さいほど、オブジェクトは見えにくくなる。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

D3DRENDERSTATETYPE


D3DFORMAT

さまざまな種類のサーフェス フォーマットを定義する。

typedef enum _D3DFORMAT {
    D3DFMT_UNKNOWN              =   0,

    D3DFMT_R8G8B8               =  20,
    D3DFMT_A8R8G8B8             =  21,
    D3DFMT_X8R8G8B8             =  22,
    D3DFMT_R5G6B5               =  23,
    D3DFMT_X1R5G5B5             =  24,
    D3DFMT_A1R5G5B5             =  25,
    D3DFMT_A4R4G4B4             =  26,
    D3DFMT_R3G3B2               =  27,
    D3DFMT_A8                   =  28,
    D3DFMT_A8R3G3B2             =  29,
    D3DFMT_X4R4G4B4             =  30,

    D3DFMT_A8P8                 =  40,
    D3DFMT_P8                   =  41,

    D3DFMT_L8                   =  50,
    D3DFMT_A8L8                 =  51,
    D3DFMT_A4L4                 =  52,

    D3DFMT_V8U8                 =  60,
    D3DFMT_L6V5U5               =  61,
    D3DFMT_X8L8V8U8             =  62,
    D3DFMT_Q8W8V8U8             =  63,
    D3DFMT_V16U16               =  64,
    D3DFMT_W11V11U10            =  65,

    D3DFMT_UYVY                 =  MAKEFOURCC('U', 'Y', 'V', 'Y'),
    D3DFMT_YUY2                 =  MAKEFOURCC('Y', 'U', 'Y', '2'),
    D3DFMT_DXT1                 =  MAKEFOURCC('D', 'X', 'T', '1'),
    D3DFMT_DXT2                 =  MAKEFOURCC('D', 'X', 'T', '2'),
    D3DFMT_DXT3                 =  MAKEFOURCC('D', 'X', 'T', '3'),
    D3DFMT_DXT4                 =  MAKEFOURCC('D', 'X', 'T', '4'),
    D3DFMT_DXT5                 =  MAKEFOURCC('D', 'X', 'T', '5'),

    D3DFMT_D16_LOCKABLE         =  70,
    D3DFMT_D32                  =  71,
    D3DFMT_D15S1                =  73,
    D3DFMT_D24S8                =  75,
    D3DFMT_D16                  =  80,
    D3DFMT_D24X8                =  77,
    D3DFMT_D24X4S4              =  79,

    D3DFMT_VERTEXDATA           = 100,
    D3DFMT_INDEX16              = 101,
    D3DFMT_INDEX32              = 102,

    D3DFMT_FORCE_DWORD          = 0xFFFFFFFF
} D3DFORMAT;

定数

D3DFMT_UNKNOWN
サーフェス フォーマットは不明である。
D3DFMT_R8G8B8
24 ビットの RGB ピクセル フォーマット。
D3DFMT_A8R8G8B8
アルファ付きの 32 ビット ARGB ピクセル フォーマット。
D3DFMT_X8R8G8B8
32 ビットの RGB ピクセル フォーマットで、そのうち 8 ビットは各色のために確保されている。
D3DFMT_R5G6B5
16 ビットの RGB ピクセル フォーマット。
D3DFMT_X1R5G5B5
16 ビットのピクセル フォーマットで、そのうち 5 ビットは各色のために確保されている。
D3DFMT_A1R5G5B5
16 ビットのピクセル フォーマットで、各色に 5 ビットが、アルファ (透過型テクセル) に 1 ビットが、それぞれ確保されている。
D3DFMT_A4R4G4B4
16 ビットの ARGB ピクセル フォーマット。
D3DFMT_R3G3B2
8 ビットの RGB テクスチャ フォーマット。
D3DFMT_A8
8 ビットのアルファのみ。
D3DFMT_A8R3G3B2
16 ビットの ARGB テクスチャ フォーマット。
D3DFMT_X4R4G4B4
16 ビットの RGB ピクセル フォーマットで、そのうち 4 ビットは各色のために確保されている。
D3DFMT_A8P8
サーフェスは、8 ビットのアルファが付いた 8 ビットのカラー インデックス付き。
D3DFMT_P8
サーフェスは、8 ビットのカラー インデックス付き。
D3DFMT_L8
8 ビットの輝度のみ。
D3DFMT_A8L8
16 ビットのアルファ輝度。
D3DFMT_A4L4
8 ビットのアルファ輝度。
D3DFMT_V8U8
16 ビットのバンプマップ フォーマット。
D3DFMT_L6V5U5
輝度の付いた 16 ビットのバンプマップ フォーマット。
D3DFMT_X8L8V8U8
輝度付きの 32 ビット バンプマップ フォーマットで、8 ビットは各要素のために確保されている。
D3DFMT_Q8W8V8U8
32 ビットのバンプマップ フォーマット。
D3DFMT_V16U16
32 ビットのバンプマップ フォーマット。
D3DFMT_W11V11U10
32 ビットのバンプマップ フォーマット。
D3DFMT_UYVY
UYVY フォーマット (PC98 準拠)。
D3DFMT_YUY2
YUY2 フォーマット (PC98 準拠)。
D3DFMT_DXT1
DXT1 圧縮テクスチャ フォーマット。
D3DFMT_DXT2
DXT2 圧縮テクスチャ フォーマット。
D3DFMT_DXT3
DXT3 圧縮テクスチャ フォーマット。
D3DFMT_DXT4
DXT4 圧縮テクスチャ フォーマット。
D3DFMT_DXT5
DXT5 圧縮テクスチャ フォーマット。
D3DFMT_D16_LOCKABLE
16 ビットの Z バッファ ビット深度。これはアプリケーションでロック可能なサーフェス フォーマットである。
D3DFMT_D32
32 ビットの Z バッファ ビット深度。
D3DFMT_D15S1
16 ビットの Z バッファ ビット深度で、15 ビットが深度チャネルに、1 ビットがステンシル チャネルに確保されている。
D3DFMT_D24S8
32 ビットの Z バッファ ビット深度で、24 ビットが深度チャネルに、8 ビットがステンシル チャネルに確保されている。
D3DFMT_D16
16 ビットの Z バッファ ビット深度。
D3DFMT_D24X8
32 ビットの Z バッファ ビット深度で、24 ビットが深度チャネルに確保されている。
D3DFMT_D24X4S4
32 ビットの Z バッファ ビット深度で、24 ビットが深度チャネルに、4 ビットがステンシル チャネルに確保されている。
D3DFMT_VERTEXDATA
頂点バッファ サーフェスを記述する。
D3DFMT_INDEX16
16 ビットのインデックス バッファのビット深度。
D3DFMT_INDEX32
32 ビットのインデックス バッファのビット深度。
D3DFMT_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

注意

レンダリング ターゲット フォーマットはD3DFMT_X1R5G5B5、D3DFMT_R5G6B5、D3DFMT_X8R8G8B8、および D3DFMT_A8R8G8B8 に制限されていることに注意すること。

ビット オーダーは、最上位ビット (MSB) が先頭である。したがって、D3DFMT_A8L8 は、この 2 バイト フォーマットの上位バイトがアルファであることを示している。D3DFMT_D16 は、16 ビットの整数値で、アプリケーションでロック可能なサーフェスを示す。

D3DFMT_D16_LOCKABLEを除くすべての深度ステンシル フォーマットは、ピクセル単位に特定のビット オーダーを指定せず、アプリケーションでロックできないので、ドライバは深度チャネルで指定されたビット数より多くのビットを使用できる (ただし、ステンシル チャネルでは使用できない)。

ピクセル フォーマットは、不透明 DWORD 識別子によって示される。このような DWORD のフォーマットが選択されているのは、IHV で定義されている拡張フォーマットの表現を可能にし、確立されている FOURCC 方式を取り入れるためである。Microsoft® Direct3D® ランタイムが認識するフォーマット群は、D3DFORMAT で定義されている。

IHV で提供されるフォーマットおよび多くの FOURCC コードは、D3DFORMAT 列挙型の一覧には示されていないことに注意する必要がある。この列挙型のフォーマットは、ランタイムによって認められている点がほかのフォーマットと異なる。つまり、リファレンス ラスタライザは、これらの型のすべてで動作する。IHV 提供のフォーマットは、カード単位に個々の IHV によってサポートされる。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

IDirect3D8::CheckDeviceFormat、FOURCC コード


D3DBASISTYPE

高次パッチ サーフェスの基本タイプを定義する。

typedef enum _D3DBASISTYPE{
   D3DBASIS_BEZIER        = 0,
   D3DBASIS_BSPLINE       = 1,
   D3DBASIS_INTERPOLATE   = 2,

   D3DBASIS_FORCE_DWORD   = 0x7fffffff
} D3DBASISTYPE;

定数

D3DBASIS_BEZIER
入力頂点は、一連のベジェ パッチとして扱われる。指定する頂点の数は、3 + 1 で割りきれる数でなければならない。この条件を満たさないメッシュ部分はレンダリングされない。各呼び出しによってレンダリングされるサーフェスの内側にあるサブパッチの間は、完全に連続しているものと想定されている。作成されるサーフェス上にあることが保証されているのは、各サブパッチの隅にある頂点だけである。
D3DBASIS_BSPLINE
入力頂点は、B スプライン サーフェスの制御ポイントとして扱われる。レンダリングされる開口部の数は、その方向の開口部の数より 2 つ少ない。一般に、指定されている制御頂点は、生成されるサーフェスに含まれていない。
D3DBASIS_INTERPOLATE
指定されているすべての入力頂点をサーフェスが通過するよう、補間基準によってサーフェスが定義される。
D3DBASIS_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

注意

D3DBASISTYPE のメンバは、テッセレーションの間に行われる高次パッチ サーフェス プリミティブの評価において使われる式を規定している。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

D3DRECTPATCH_INFO、D3DTRIPATCH_INFO


D3DLIGHTTYPE

ライトの種類を定義する。

typedef enum _D3DLIGHTTYPE {
    D3DLIGHT_POINT          = 1,
    D3DLIGHT_SPOT           = 2,
    D3DLIGHT_DIRECTIONAL    = 3,

    D3DLIGHT_FORCE_DWORD    = 0x7fffffff
} D3DLIGHTTYPE;

定数

D3DLIGHT_POINT
ライトはポイント ライトである。ライトは空間内の点を持ち、全方向に光を照射する。
D3DLIGHT_SPOT
ライトはスポット ライトである。このライトは、照射がコーン内に制限される点を除いては、ポイント ライトに類似する。このライト タイプには、方向、およびコーンの形状を決めるその他のパラメータがいくつかある。これらのパラメータについては、「D3DLIGHT8 構造体」を参照すること。
D3DLIGHT_DIRECTIONAL
ライトはディレクショナル ライトである。これは無限大の距離でポイント ライトを用いることに等しい。
D3DLIGHT_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

注意

ディレクショナル ライトはポイント ライトより処理は多少速いが、結果についてはポイント ライトの方が上である。スポット ライトは面白い視覚エフェクトを出すが、計算上負荷が高い。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

D3DLIGHT8


D3DMATERIALCOLORSOURCE

ライティング計算のために参照しなければならない色または色成分の場所を定義する。

typedef enum _D3DMATERIALCOLORSOURCE {
    D3DMCS_MATERIAL         = 0,
    D3DMCS_COLOR1           = 1,
    D3DMCS_COLOR2           = 2,

    D3DMCS_FORCE_DWORD      = 0x7fffffff
} D3DMATERIALCOLORSOURCE;

定数

D3DMCS_MATERIAL
現在のマテリアルの色を使用する。
D3DMCS_COLOR1
ディフューズ頂点色を使用する。
D3DMCS_COLOR2
スペキュラ頂点色を使用する。
D3DMCS_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

注意

これらのフラグは、D3DRENDERSTATETYPE 列挙型で次のレンダリング ステートの値を設定するために使用する。

  • D3DRS_DIFFUSEMATERIALSOURCE
  • D3DRS_SPECULARMATERIALSOURCE
  • D3DRS_AMBIENTMATERIALSOURCE
  • D3DRS_EMISSIVEMATERIALSOURCE

動作環境

ヘッダー : d3d8types.h で宣言。

参照

D3DRENDERSTATETYPE


D3DMULTISAMPLE_TYPE

デバイスが対応するフルシーン マルチサンプリングのレベルを定義する。

typedef enum _D3DMULTISAMPLE_TYPE {
    D3DMULTISAMPLE_NONE            =  0,
    D3DMULTISAMPLE_2_SAMPLES       =  2,
    D3DMULTISAMPLE_3_SAMPLES       =  3,
    D3DMULTISAMPLE_4_SAMPLES       =  4,
    D3DMULTISAMPLE_5_SAMPLES       =  5,
    D3DMULTISAMPLE_6_SAMPLES       =  6,
    D3DMULTISAMPLE_7_SAMPLES       =  7,
    D3DMULTISAMPLE_8_SAMPLES       =  8,
    D3DMULTISAMPLE_9_SAMPLES       =  9,
    D3DMULTISAMPLE_10_SAMPLES      = 10,
    D3DMULTISAMPLE_11_SAMPLES      = 11,
    D3DMULTISAMPLE_12_SAMPLES      = 12,
    D3DMULTISAMPLE_13_SAMPLES      = 13,
    D3DMULTISAMPLE_14_SAMPLES      = 14,
    D3DMULTISAMPLE_15_SAMPLES      = 15,
    D3DMULTISAMPLE_16_SAMPLES      = 16,

    D3DMULTISAMPLE_FORCE_DWORD     = 0xffffffff
} D3DMULTISAMPLE_TYPE;

定数

D3DMULTISAMPLE_NONE
いずれのレベルのフルシーン マルチサンプリングも利用できない。
D3DMULTISAMPLE_2_SAMPLES ～ D3DMULTISAMPLE_16_SAMPLES
そのレベルのフルシーン マルチサンプリングを利用できる。
D3DMULTISAMPLE_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

注意

IDirect3DDevice8::Reset の呼び出し時にフルシーン マルチサンプリングを有効にできるだけでなく、さまざまな機能のオンまたはオフをきめ細かいレベルで設定するレンダリング ステートが用意されている。

マルチサンプリングは、D3DSWAPEFFECT_DISCARD スワップ エフェクトで作成またはリセットしているスワップ チェーンでのみ有効である。

動作環境

ヘッダー : d3d8types.h で宣言。

参照

IDirect3D8::CheckDeviceMultiSampleType、IDirect3DDevice8::CreateDepthStencilSurface、IDirect3DDevice8::CreateRenderTarget、D3DPRESENT_PARAMETERS、D3DSURFACE_DESC


D3DORDERTYPE

高次サーフェスのオーダー タイプを定義する。

typedef enum _D3DORDERTYPE {
   D3DORDER_LINEAR      = 1,
   D3DORDER_CUBIC       = 3,
   D3DORDER_QUINTIC     = 5,

   D3DORDER_FORCE_DWORD = 0x7fffffff
} D3DORDERTYPE;

定数

D3DORDER_LINEAR
線形タイプ。
D3DORDER_CUBIC
3 次タイプ。
D3DORDER_QUINTIC
5 次タイプ。
D3DORDER_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

D3DRECTPATCH_INFO、D3DTRIPATCH_INFO


D3DPATCHEDGESTYLE

現在のテッセレーション モードが個別または連続のいずれであるかを定義する。

typedef enum _D3DPATCHEDGESTYLE {
   D3DPATCHEDGE_DISCRETE    = 0,
   D3DPATCHEDGE_CONTINUOUS  = 1,

   D3DPATCHEDGE_FORCE_DWORD = 0x7fffffff,
} D3DPATCHEDGESTYLE;

定数

D3DPATCHEDGE_DISCRETE
個別エッジ スタイル。個別モードでは、浮動小数点数のテッセレーションを指定できるが、整数に切り詰められる。
D3DPATCHEDGE_CONTINUOUS
連続エッジ スタイル。連続モードでは、テッセレーションは浮動小数点数値として指定され、なめらかに変化させて不自然な効果「ポッピング」を減少させることができる。
D3DPATCHEDGE_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

注意

連続テッセレーションでは、テッセレーションの値が同じでも、個別テッセレーションとはまったく異なるテッセレーション パターンが生成されることに注意すること (これはワイヤフレーム モードでより顕著になる)。したがって、連続モードの 4.0 は個別モードの 4 と同じではない。

動作環境

ヘッダー : D3d8types.h で宣言。


D3DPOOL

リソースのバッファを保持するメモリ クラスを定義する。

typedef enum _D3DPOOL {
    D3DPOOL_DEFAULT                 = 0,
    D3DPOOL_MANAGED                 = 1,
    D3DPOOL_SYSTEMMEM               = 2,

    D3DPOOL_FORCE_DWORD             = 0x7fffffff
} D3DPOOL;

定数

D3DPOOL_DEFAULT
リソースは、リソースに対して要求された使用方法に最も適したメモリ プールに置かれる。通常、これは、ローカル ビデオ メモリと AGP メモリの両方を含む、ビデオ メモリである。D3DPOOL_DEFAULT プールは、D3DPOOL_MANAGED および D3DPOOL_SYTEMMEM から独立しており、リソースがデバイス アクセス用の優先メモリに配置されることを指定する。D3DPOOL_DEFAULT は、このリソースのメモリ プール タイプとして D3DPOOL_MANAGED または D3DPOOL_SYSTEMMEM のいずれかを選択しなければならないことを示しているのではないことに注意すること。D3DPOOL_DEFAULT プールに配置されたテクスチャは、ロックできないので、直接アクセスできない。代わりに、IDirect3DDevice8::CopyRects や IDirect3DDevice8::UpdateTexture などの関数を使用しなければならない。D3DPOOL_MANAGED は、ほとんどのアプリケーションで D3DPOOL_DEFAULT よりも適している場合が多い。Direct3D ランタイムでは未知の、ドライバ独自のピクセル フォーマットで作成されたテクスチャの一部はロックできることに注意すること。また、テクスチャとは異なり、スワップチェーン バックバッファ、レンダリング ターゲット、頂点バッファ、およびインデックス バッファがロックできることにも注意する。

デバイスが消失した場合は、D3DPOOL_DEFAULT を使って作成したリソースは、IDirect3DDevice8::Reset を呼び出す前に解放しなければならない。詳細については、「消失したデバイス」を参照すること。

D3DPOOL_MANAGED
リソースは、必要に応じて、デバイスからアクセスできるメモリに自動的にコピーされる。管理リソースは、システム メモリにバックアップされるので、デバイスが消失したときに作成し直す必要がない。詳細については、「リソースの管理」を参照すること。管理リソースはロックできる。システム メモリのコピーだけが直接変更される。Direct3D は、必要に応じて、ドライバがアクセス可能なメモリに変更内容をコピーする。
D3DPOOL_SYSTEMMEM
通常、3D デバイスによってアクセスできないメモリ。システム RAM を使用するが、ページング可能な RAM が減ることはない。これらのリソースは、デバイスが消失しても作成し直す必要がない。このプールのリソースはロックすることができ、D3DPOOL_DEFAULT を使って作成されたメモリ リソースに対する IDirect3DDevice8::CopyRects または IDirect3DDevice8::UpdateTexture 処理の転送元として使用できる。
D3DPOOL_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

注意

1 つのリソース (ミップマップのミップ レベル) に含まれる異なるオブジェクトに対して複数のプールを混在させることはできず、いったん選択したプールは変更できない。

アプリケーションでは、ほとんどの静的リソースに対して D3DPOOL_MANAGED を使う必要がある。これにより、消失したデバイスを処理する必要がなくなる。管理リソースはランタイムによって復元される。これは、特に UMA システムで有効である。また、ダイナミック テクスチャ リソースに対しても、その変更頻度の多さにかかわらず、D3DPOOL_MANAGED を使う。それ以外の動的リソースに対しては、D3DPOOL_MANAGED はあまり使わない。実際、D3DPOOL_MANAGED と D3DUSAGE_DYNAMIC をともに使って、インデックス バッファおよび頂点バッファを作成することはできない。

ダイナミック テクスチャの場合、ビデオ メモリとシステム メモリのテクスチャのペアを使用して、D3DPOOL_DEFAULT を使ってビデオ メモリを、D3DPOOL_SYSTEMMEM を使ってシステム メモリを割り当てることがある。ロッキング メソッドを使って、システム メモリ テクスチャのビットをロックおよび変更できる。その後、IDirect3DDevice8::UpdateTexture を使って、ビデオ メモリ テクスチャを更新することができる。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

IDirect3DDevice8::CreateCubeTexture、IDirect3DDevice8::CreateIndexBuffer、IDirect3DDevice8::CreateTexture、IDirect3DDevice8::CreateVolumeTexture、IDirect3DDevice8::CreateVertexBuffer、D3DINDEXBUFFER_DESC、D3DSURFACE_DESC、D3DVERTEXBUFFER_DESC、D3DVOLUME_DESC


D3DPRIMITIVETYPE

Microsoft® Direct3D® がサポートするプリミティブを定義する。

typedef enum _D3DPRIMITIVETYPE {
    D3DPT_POINTLIST             = 1,
    D3DPT_LINELIST              = 2,
    D3DPT_LINESTRIP             = 3,
    D3DPT_TRIANGLELIST          = 4,
    D3DPT_TRIANGLESTRIP         = 5,
    D3DPT_TRIANGLEFAN           = 6,

    D3DPT_FORCE_DWORD           = 0x7fffffff
} D3DPRIMITIVETYPE;

定数

D3DPT_POINTLIST
頂点を別個の点の集合としてレンダリングする。
D3DPT_LINELIST
別個の線分のリストとして頂点をレンダリングする。このプリミティブ タイプを使用する呼び出しは、カウントが 2 より小さいか、奇数の場合は失敗する。
D3DPT_LINESTRIP
頂点を単一のポリラインとしてレンダリングする。このプリミティブ タイプを使用する呼び出しは、カウントが 2 より小さい場合は失敗する。
D3DPT_TRIANGLELIST
別個の三角形の連続として指定の頂点をレンダリングする。各 3 頂点のグループは個別に三角形を定義する。

背面のカリングは、現在のカリング モード レンダリング ステートの影響を受ける。

D3DPT_TRIANGLESTRIP
頂点を三角形の展開図としてレンダリングする。背面カリング フラグは、偶数番号の三角形で自動的に反転する。
D3DPT_TRIANGLEFAN
頂点を三角形の扇形としてレンダリングする。
D3DPT_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

注意

三角形ストリップまたは三角形ファンを使うと複製される頂点の数が少ないため、効率的であることが多い。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

IDirect3DDevice8::DrawIndexedPrimitive、IDirect3DDevice8::DrawIndexedPrimitiveUP、IDirect3DDevice8::DrawPrimitive、IDirect3DDevice8::DrawPrimitiveUP


D3DRENDERSTATETYPE

デバイスのレンダリング ステートを定義する。

typedef enum _D3DRENDERSTATETYPE {
    D3DRS_ZENABLE                   =   7,
    D3DRS_FILLMODE                  =   8,
    D3DRS_SHADEMODE                 =   9,
    D3DRS_LINEPATTERN               =  10,
    D3DRS_ZWRITEENABLE              =  14,
    D3DRS_ALPHATESTENABLE           =  15,
    D3DRS_LASTPIXEL                 =  16,
    D3DRS_SRCBLEND                  =  19,
    D3DRS_DESTBLEND                 =  20,
    D3DRS_CULLMODE                  =  22,
    D3DRS_ZFUNC                     =  23,
    D3DRS_ALPHAREF                  =  24,
    D3DRS_ALPHAFUNC                 =  25,
    D3DRS_DITHERENABLE              =  26,
    D3DRS_ALPHABLENDENABLE          =  27,
    D3DRS_FOGENABLE                 =  28,
    D3DRS_SPECULARENABLE            =  29,
    D3DRS_ZVISIBLE                  =  30,
    D3DRS_FOGCOLOR                  =  34,
    D3DRS_FOGTABLEMODE              =  35,
    D3DRS_FOGSTART                  =  36,
    D3DRS_FOGEND                    =  37,
    D3DRS_FOGDENSITY                =  38,
    D3DRS_EDGEANTIALIAS             =  40,
    D3DRS_ZBIAS                     =  47,
    D3DRS_RANGEFOGENABLE            =  48,

    D3DRS_STENCILENABLE             =  52,
    D3DRS_STENCILFAIL               =  53,
    D3DRS_STENCILZFAIL              =  54,
    D3DRS_STENCILPASS               =  55,
    D3DRS_STENCILFUNC               =  56,
    D3DRS_STENCILREF                =  57,
    D3DRS_STENCILMASK               =  58,
    D3DRS_STENCILWRITEMASK          =  59,
    D3DRS_TEXTUREFACTOR             =  60,

    D3DRS_WRAP0                     = 128,
    D3DRS_WRAP1                     = 129,
    D3DRS_WRAP2                     = 130,
    D3DRS_WRAP3                     = 131,
    D3DRS_WRAP4                     = 132,
    D3DRS_WRAP5                     = 133,
    D3DRS_WRAP6                     = 134,
    D3DRS_WRAP7                     = 135,
    D3DRS_CLIPPING                  = 136,
    D3DRS_LIGHTING                  = 137,
    D3DRS_AMBIENT                   = 139,
    D3DRS_FOGVERTEXMODE             = 140,
    D3DRS_COLORVERTEX               = 141,
    D3DRS_LOCALVIEWER               = 142,
    D3DRS_NORMALIZENORMALS          = 143,
    D3DRS_DIFFUSEMATERIALSOURCE     = 145,
    D3DRS_SPECULARMATERIALSOURCE    = 146,
    D3DRS_AMBIENTMATERIALSOURCE     = 147,
    D3DRS_EMISSIVEMATERIALSOURCE    = 148,
    D3DRS_VERTEXBLEND               = 151,
    D3DRS_CLIPPLANEENABLE           = 152,

    D3DRS_SOFTWAREVERTEXPROCESSING  = 153,

    D3DRS_POINTSIZE                 = 154,
    D3DRS_POINTSIZE_MIN             = 155,
    D3DRS_POINTSPRITEENABLE         = 156,

    D3DRS_POINTSCALEENABLE          = 157,
    D3DRS_POINTSCALE_A              = 158,
    D3DRS_POINTSCALE_B              = 159,
    D3DRS_POINTSCALE_C              = 160,

    D3DRS_MULTISAMPLEANTIALIAS      = 161,
    D3DRS_MULTISAMPLEMASK           = 162,

    D3DRS_PATCHEDGESTYLE            = 163,
    D3DRS_PATCHSEGMENTS             = 164,

    D3DRS_DEBUGMONITORTOKEN         = 165,
    D3DRS_POINTSIZE_MAX             = 166,
    D3DRS_INDEXEDVERTEXBLENDENABLE  = 167,
    D3DRS_COLORWRITEENABLE          = 168,
    D3DRS_TWEENFACTOR               = 170,
    D3DRS_BLENDOP                   = 171,

    D3DRS_FORCE_DWORD               = 0x7fffffff
} D3DRENDERSTATETYPE;

定数

D3DRS_ZENABLE
D3DZBUFFERTYPE 列挙型の 1 つのメンバとしての深度バッファ ステート。Z バッファリングを有効にするには D3DZB_TRUE、w バッファリングを有効にするには D3DZB_USEW、深度バッファリングを無効にするには D3DZB_FALSE を、それぞれ設定する。

D3DPRESENT_PARAMETERS 構造体の EnableAutoDepthStencil メンバに TRUE を設定して深度ステンシルがスワップ チェーンと共に作成されている場合、このレンダリング ステートのデフォルト値は TD3DZB_TRUE、そうでない場合は D3DZB_FALSE である。

D3DRS_FILLMODE
D3DFILLMODE 列挙型のメンバのいずれかまたは複数。デフォルト値は D3DFILL_SOLID である。
D3DRS_SHADEMODE
D3DSHADEMODE 列挙型のメンバのいずれかまたは複数。デフォルト値は D3DSHADE_GOURAUD である。
D3DRS_LINEPATTERN
D3DLINEPATTERN 構造体。デフォルト値は wRepeatPattern が 0 で、wLinePattern が 0 である。
D3DRS_ZWRITEENABLE
アプリケーションによる深度バッファへの書き込みを有効にするには、TRUE を設定する。デフォルト値は TRUE である。アプリケーションはこのメンバを利用することにより、システムが新しい深度値で深度バッファを更新してしまうのを防ぐことができる。FALSE の場合は、レンダリング ステート D3DRS_ZFUNC (深度バッファリングが行われていると仮定) に従って深度比較が実行されるが、深度値はバッファに書き込まれない。
D3DRS_ALPHATESTENABLE
アルファ テストを可能にするには、TRUE を設定する。デフォルト値は FALSE である。このメンバを使用すると、アルファ値に基づいてピクセルを受け取るか拒否するかを判断するテストをオフにできる。

入ってくるアルファ値は、D3DRS_ALPHAFUNC レンダリング ステートにより提供される比較関数を用いて参照アルファ値と比較される。このモードが可能になると、テストが成功した場合に限り、アルファ ブレンディングが起きる。

D3DRS_LASTPIXEL
直線や三角形の最後のピクセルを描画可能にするには、FALSE を設定する。デフォルト値は TRUE である。
D3DRS_SRCBLEND
D3DBLEND 列挙型のメンバのいずれかである。デフォルト値は D3DBLEND_ONE である。
D3DRS_DESTBLEND
D3DBLEND 列挙型のメンバのいずれかである。デフォルト値は D3DBLEND_ZERO である。
D3DRS_CULLMODE
背面の三角形をカリングする場合に、その方法を指定する。D3DCULL 列挙型のメンバのいずれかを設定できる。デフォルト値は D3DCULL_CCW である。
D3DRS_ZFUNC
D3DCMPFUNC 列挙型のメンバのいずれかである。デフォルト値は D3DCMP_LESSEQUAL である。このメンバは、アプリケーションにカメラからの距離を基準とするピクセルの受け取りや受け取り拒否を許可する。

ピクセルの深度値を深度バッファの値と比較する。ピクセルの深度値が比較関数で許可された場合にピクセルが書き込まれる。

深度値が深度バッファに書き込まれるのは、レンダリング ステートが TRUE の場合だけである。

この深度テストに失敗した方が、ソフトウェアによるラスタ化や多くのハードウェア アクセラレータの処理は速くなる。これは、ピクセルのレンダリング処理を行わない場合に、テクスチャをフィルタ処理したり乗算したりする必要がなくなるためである。

D3DRS_ALPHAREF
アルファ テストが有効に設定されている場合に、ピクセルをテストするための基準アルファ値を指定する値。これは、DWORD レンダリング ステート値の下位 8 ビットにあたる 8 ビット値である。値は 0x00000000 から 0x000000FF の範囲内である。
D3DRS_ALPHAFUNC
D3DCMPFUNC 列挙型のメンバのいずれかである。デフォルト値は、D3DCMP_ALWAYS である。このメンバは、アプリケーションにアルファ値を基準とするピクセルの受け取りや受け取り拒否を許可する。
D3DRS_DITHERENABLE
ディザリングを可能にするには、TRUE を設定する。デフォルト値は FALSE である。
D3DRS_ALPHABLENDENABLE
アルファ ブレンドによる透明化を有効にするには、TRUE を設定する。デフォルト値は FALSE である。

アルファ ブレンディングのタイプは、D3DRS_SRCBLEND と D3DRS_DESTBLEND のレンダリング ステートによって決定される。

アプリケーションでは D3DCAPS8 構造体の DevCaps メンバの D3DDEVCAPS_DRAWPRIMTLVERTEX フラグを調べて、このレンダリング ステートがサポートされているかどうかをチェックする。

D3DRS_FOGENABLE
フォグ ブレンディングを可能にするには、TRUE を設定する。デフォルト値は FALSE である。フォグ ブレンディングの詳細については、「フォグ」を参照すること。
D3DRS_SPECULARENABLE
スペキュラ ハイライトを可能にするには、TRUE を設定する。デフォルト値は FALSE である。

スペキュラ ハイライトは、光の当たっているオブジェクトの各頂点がそのオブジェクトの原点にあるかのように算出される。これによって、オブジェクトが原点の周囲でモデル化され、光源とオブジェクト間の距離が比較的大きい場合に限り、結果を予測することができる。それ以外の場合は、結果は不定である。

このメンバを TRUE に設定すると、テクスチャ カスケード後、アルファ ブレンディング前に、ベース カラーにスペキュラ色が追加される。

D3DRS_ZVISIBLE
サポートされない。
D3DRS_FOGCOLOR
D3DCOLOR 型の値。デフォルト値は 0 である。フォグ カラーの詳細については、「フォグ カラー」を参照すること。
D3DRS_FOGTABLEMODE
ピクセル フォグに使用されるフォグ式。D3DFOGMODE 列挙型のメンバのいずれかを設定する。デフォルト値は D3DFOG_NONE である。ピクセル フォグの詳細については、「ピクセル フォグ」を参照すること。
D3DRS_FOGSTART
線形フォグ モードにおける、ピクセルまたは頂点フォグ エフェクトの開始深度。頂点フォグの場合、深度はワールド空間で指定される。ピクセル フォグの場合は、デバイス空間 [0.0, 1.0] またはワールド空間のいずれかで指定される。ピクセル フォグでは、フォグ計算に Z が使用される場合、これらの値はデバイス空間にあり、視点との相対フォグ (W フォグ) が使用される場合はワールド空間にある。詳細については、「フォグ パラメータ」および「視点からの相対深度 対 Z ベースの深度」を参照すること。

このレンダリング ステートの値は浮動小数点値である。IDirect3DDevice8::SetRenderState メソッドは DWORD 値を使用するため、次のコードに示すように、アプリケーションでは値を格納した変数をキャストしなければならない。

pd3dDevice8->SetRenderState(D3DRS_TWEENFACTOR, *((DWORD*)&TweenFactor));
D3DRS_FOGEND
線形フォグ モードにおける、ピクセルまたは頂点フォグ エフェクトの終了深度。頂点フォグの場合、深度はワールド空間で指定される。ピクセル フォグの場合は、デバイス空間 [0.0, 1.0] またはワールド空間のいずれかで指定される。ピクセル フォグでは、フォグ計算に Z が使用される場合、これらの値はデバイス空間にあり、視点との相対フォグ (W フォグ) が使用される場合はワールド空間にある。詳細については、「フォグ パラメータ」および「視点からの相対深度 対 Z ベースの深度」を参照すること。

このレンダリング ステートの値は浮動小数点値である。IDirect3DDevice8::SetRenderState メソッドは DWORD 値を使用するため、次のコードに示すように、アプリケーションでは値を格納した変数をキャストしなければならない。

pd3dDevice8->SetRenderState(D3DRS_FOGEND, *((DWORD*) (&fFogEnd)));
D3DRS_FOGDENSITY
指数フォグ モード (D3DFOG_EXP および D3DFOG_EXP2) で使用するピクセルまたは頂点フォグのフォグ密度。有効な密度は 0.0 から 1.0 の範囲内である。デフォルト値は 1.0 である。詳細については、「フォグ パラメータ」を参照すること。

このレンダリング ステートの値は浮動小数点値である。IDirect3DDevice8::SetRenderState メソッドは DWORD 値を使用するため、次のコードに示すように、アプリケーションでは値を格納した変数をキャストしなければならない。

pd3dDevice8->SetRenderState(D3DRS_FOGDENSITY, *((DWORD*) (&fFogDensity)));
D3DRS_EDGEANTIALIAS
オブジェクトの凸面の輪郭を形成する線をアンチエイリアスするには、TRUE を設定する。デフォルト値は FALSE である。TRUE の場合、レンダリングの対象となるのは線のみで、シーン内のポリゴンの外側エッジに限定される。このレンダリング ステートが設定されていて、三角形または点が描画されると、その動作は不定である。アンチエイリアシングは、隣接ピクセルの値の平均値を取ることによって実行される。アンチエイリアシングを行うのは最良のやり方ではないが、効率的ではある。この種の処理をサポートするハードウェアは普及しつつある。

エッジ アンチエイリアシングは、D3DPRASTERCAPS_ANTIALIASEDGES 能力を公開するデバイスに限り、有効にすることができる。エッジ アンチエイリアシングの詳細については、「エッジ アンチエイリアシング」および「アンチエイリアシング ステート」を参照すること。

D3DRS_ZBIAS
物理的には同一面上にあるポリゴンが別々に存在するように見せる、0 から 16 までの範囲の整数値。Z バイアス値が高いポリゴンは、Z バイアス値が低いポリゴンより手前に表示されるため、描画順序を決めるソートを実行する必要はない。たとえば、値 1 を持つポリゴンは、値 0 のポリゴンよりも手前に見える。デフォルト値は 0 である。詳細については、「深度バッファの使い方」を参照すること。
D3DRS_RANGEFOGENABLE
範囲ベースの頂点フォグを有効にするには、TRUE を設定する。デフォルト値は FALSE である。この場合は深度ベースのフォグが使用される。範囲ベースのフォグでは、シーンにおけるオブジェクトの深さ (z 座標) ではなく、ビューアからのオブジェクトの距離でフォグ エフェクトを計算する。範囲ベースのフォグでは、通常のすべてのフォグ メソッドが機能するが、深度ではなく範囲を使って計算を行う点だけが異なる。

範囲はフォグ計算に使用する適切な要素であるが、範囲は計算の点で負荷が高く、深度は通常計算済みなので、代わりに深度が広く使われる。深度を使用してフォグを計算すると、周辺オブジェクトのフォグ エフェクトが視点の移動と共に変化するという好ましくない影響が出る。この場合、深度は変化するが範囲は一定のままである。

現在のところ、ピクセル単位の範囲ベースのフォグをサポートするハードウェアは存在しないため、範囲補正は頂点フォグでのみ行われる。

詳細については、「範囲ベースのフォグ」および「頂点フォグ」を参照すること。

D3DRS_STENCILENABLE
ステンシル処理を可能にするには TRUE、無効にするには FALSE を設定する。デフォルト値は FALSE である。

詳細については、「ステンシル バッファ」を参照すること。

D3DRS_STENCILFAIL
ステンシル テストに失敗したときに実行するステンシル処理。これには D3DSTENCILOP 列挙型のメンバのいずれかを設定できる。デフォルト値は D3DSTENCILOP_KEEP である。

詳細については、「ステンシル バッファ」を参照すること。

D3DRS_STENCILZFAIL
ステンシル テストにパスし、深度テスト (Z テスト) に失敗した場合に実行するステンシル処理。これには D3DSTENCILOP 列挙型のメンバのいずれかを設定できる。デフォルト値は D3DSTENCILOP_KEEP である。
D3DRS_STENCILPASS
ステンシル テストおよび深度 (Z) テストの両方にパスした場合に実行するステンシル処理。これには D3DSTENCILOP 列挙型のメンバのいずれかを設定できる。デフォルト値は D3DSTENCILOP_KEEP である。
D3DRS_STENCILFUNC
ステンシル テストのための比較関数。これには D3DCMPFUNC 列挙型のメンバのいずれかを設定できる。デフォルト値は、D3DCMP_ALWAYS である。

比較関数は、ステンシル バッファの要素を基準値と比較するために使われる。この比較は、基準値のビットと、ステンシル マスク (D3DRS_STENCILMASK レンダリング ステートにより設定) に設定されたステンシル バッファ要素にのみ適用される。TRUE の場合は、ステンシル テストにパスする。

D3DRS_STENCILREF
ステンシル テストのための整数基準値。デフォルト値は 0 である。
D3DRS_STENCILMASK
基準値と、それぞれのステンシル バッファ要素に適用し、ステンシル テストのための有効ビットを決定するマスク。デフォルト マスクは 0xFFFFFFFF である。
D3DRS_STENCILWRITEMASK
ステンシル バッファに書き込む値に適用する書き込みマスク。デフォルト マスクは 0xFFFFFFFF である。
D3DRS_TEXTUREFACTOR
D3DTA_TFACTOR テクスチャ ブレンディング引数、または D3DTOP_BLENDFACTORALPHA テクスチャ ブレンディング処理を用いたマルチテクスチャ ブレンディングで使用される色。関連する値は D3DCOLOR 変数である。
D3DRS_WRAP0 ～ D3DRS_WRAP7
複数のテクスチャ座標セットに対するテクスチャラッピング動作。これらのレンダリング ステートの有効値として、D3DWRAPCOORD_0 (または D3DWRAP_U)、D3DWRAPCOORD_1 (または D3DWRAP_V)、D3DWRAPCOORD_2 (または D3DWRAP_W)、および D3DWRAPCOORD_3 の各フラグを組み合わせることができる。これらの値を設定すると、指定されたテクスチャに対して 1、2、3、および 4 次元方向 (s、ｔ、ｒ、および q 方向と呼ばれる場合もある) のラッピングが実行される。これらのレンダリング ステートのデフォルト値は 0 である (全方向のラッピングが無効)。
D3DRS_CLIPPING
Microsoft® Direct3D® によるプリミティブのクリッピングを有効にするには TRUE、無効にするには FALSE を設定する。デフォルト値は TRUE である。
D3DRS_LIGHTING
Direct3D のライティングを有効にするには TRUE、無効にするには FALSE を設定する。デフォルト値は TRUE である。頂点法線を含む頂点のみ正しくライトが当てられ、法線を含まない頂点ではすべてのライティング計算で 0 の内積が使用される。
D3DRS_AMBIENT
アンビエント ライトの色。この値は D3DCOLOR 型である。デフォルト値は 0 である。
D3DRS_FOGVERTEXMODE
頂点フォグ用のフォグ式。D3DFOGMODE 列挙型のメンバのいずれかを設定する。デフォルト値は D3DFOG_NONE である。
D3DRS_COLORVERTEX
頂点単位のカラーを有効にするには TRUE、無効にするには FALSE を設定する。デフォルト値は TRUE である。頂点単位のカラーを有効にすると、個々の頂点に定義された色がライティング計算に含まれるようになる。

詳細については、以下のレンダリング ステートを参照すること。

  • D3DRS_DIFFUSEMATERIALSOURCE
  • D3DRS_SPECULARMATERIALSOURCE
  • D3DRS_AMBIENTMATERIALSOURCE
  • D3DRS_EMISSIVEMATERIALSOURCE
D3DRS_LOCALVIEWER
カメラとの相対角度に依存したスペキュラ ハイライトを有効にするには、TRUE を設定する。直行スペキュラ ハイライトを使用するには、FALSE を設定する。デフォルト値は TRUE である。正射影を使用するアプリケーションでは FALSE を設定すること。
D3DRS_NORMALIZENORMALS
頂点法線の自動正規化を有効にするには TRUE、無効にするには FALSE を設定する。デフォルト値は FALSE である。この機能を有効にすると、頂点がカメラ空間にトランスフォームされた後で頂点法線が正規化されるが、計算負荷が大きい。
D3DRS_DIFFUSEMATERIALSOURCE
ライティング計算に使用されるディフューズ色のソース。有効値は、D3DMATERIALCOLORSOURCE 列挙型のメンバである。デフォルト値は D3DMCS_COLOR1 である。このレンダリング ステートの値が使用されるのは、D3DRS_COLORVERTEX レンダリング ステートが TRUE に設定されている場合だけである。
D3DRS_SPECULARMATERIALSOURCE
ライティング計算に使用されるスペキュラ色のソース。有効値は、D3DMATERIALCOLORSOURCE 列挙型のメンバである。デフォルト値は D3DMCS_COLOR2 である。
D3DRS_AMBIENTMATERIALSOURCE
ライティング計算に使用されるアンビエント色のソース。有効値は、D3DMATERIALCOLORSOURCE 列挙型のメンバである。デフォルト値は D3DMCS_COLOR2 である。
D3DRS_EMISSIVEMATERIALSOURCE
ライティング計算に使用されるエミッション色のソース。有効値は、D3DMATERIALCOLORSOURCE 列挙型のメンバである。デフォルト値は D3DMCS_MATERIAL である。
D3DRS_VERTEXBLEND
ジオメトリがある場合、ジオメトリ ブレンディングを実行するために使用する行列の個数。有効値は D3DVERTEXBLENDFLAGS 列挙型のメンバである。デフォルト値は D3DVBF_DISABLE である。
D3DRS_CLIPPLANEENABLE
ユーザー定義クリップ面を有効または無効にする。有効値は、各ビットのステータス (設定の有無) によって対応するユーザー定義クリップ面をアクティブにするステートを切り替える、任意の DWORD である。最下位ビット (ビット 0) はインデックス 0 の最初のクリップ面を制御し、後続ビットはそれより上位のインデックスのクリップ面をアクティブにすることを制御する。ビットが設定されている場合、シーンのレンダリング中に適切なクリップ面が適用される。デフォルト値は 0 である。

クリップ面を簡単に有効にできるよう、D3DCLIPPLANEn マクロが定義されている。

D3DRS_SOFTWAREVERTEXPROCESSING
ハードウェア頂点処理またはソフトウェア頂点処理の設定をアプリケーションから照会および選択できるようにする BOOL 値。デバイスの種類が D3DDEVTYPE_SW の場合、この値は TRUE の固定である。デバイスの種類が D3DDEVTYPE_REF の場合は、アプリケーションでこの値を設定できる。デバイスの種類が D3DDEVTYPE_HAL の場合は、D3DDEVCAPS_HWTRANSFORMANDLIGHT が設定されているときに限り、アプリケーションでこの値を設定できる。それ以外の場合、このフラグは TRUE に固定される。アプリケーションでの設定が可能な場合、デフォルト値は FALSE である。

両方の頂点処理が可能なモードにおいて、頂点処理のレンダリング ステートを変更すると、カレント ストリーム、インデックス、および頂点シェーダは、デフォルト値の NULL または 0 にリセットされる。

D3DRS_POINTSIZE
各頂点に対してポイント サイズが指定されていない場合に、ポイント サイズ計算で使用するサイズを指定する浮動小数点値。頂点がポイント サイズを含んでいる場合、この値は使用されない。この値は、D3DRS_POINTSCALEENABLE が FALSE の場合はスクリーン空間単位で指定する。それ以外の場合は、ワールド空間単位で指定する。デフォルト値は 1.0f である。この値の範囲は、0.0f 以上である。IDirect3DDevice8::SetRenderState メソッドは DWORD 値を使用するため、次のコードに示すように、アプリケーションでは値を格納した変数をキャストしなければならない。
pd3dDevice8->SetRenderState(D3DRS_PATCHSEGMENTS, *((DWORD*)&PointSize));
D3DRS_POINTSIZE_MIN
ポイント プリミティブの最小サイズを指定する浮動小数点値。レンダリングの間、ポイント プリミティブはこのサイズに固定される。1.0 より小さい値を設定すると、ポイントにピクセルの中心が含まれずにアンチエイリアシングが無効になっている場合はポイントが表示されなくなり、アンチエイリアシングが有効になっている場合は低い輝度でレンダリングされる。デフォルト値は 1.0f である。この値の範囲は、0.0f 以上である。IDirect3DDevice8::SetRenderState メソッドは DWORD 値を使用するため、次のコードに示すように、アプリケーションでは値を格納した変数をキャストしなければならない。
pd3dDevice8->SetRenderState(D3DRS_PATCHSEGMENTS, *((DWORD*)&PointSizeMin));
D3DRS_POINTSPRITEENABLE
BOOL 値。TRUE を設定すると、テクスチャ全体が各ポイントにマッピングされるように、ポイント プリミティブのテクスチャ座標が設定される。FALSE を設定すると、頂点のテクスチャ座標がポイント全体に対して使用される。デフォルト値は FALSE である。D3DRS_POINTSCALEENABLE に FALSE (デフォルト値) を設定し、D3DRS_POINTSIZE に 1.0 (デフォルト値) を設定することで、DirectX 7 スタイルのシングルピクセル ポイントを実現できる。
D3DRS_POINTSCALEENABLE
ポイント プリミティブに対するサイズの計算を制御する BOOL 値。TRUE を設定すると、ポイント サイズは、カメラ空間の値として解釈され、距離関数および視錐台によってビューポートの Y 軸のスケーリングになるように調整されて、最終的なスクリーン空間のポイント サイズが計算される。FALSE を設定すると、ポイント サイズはスクリーン空間の値と解釈されて、そのまま使われる。デフォルト値は FALSE である。
D3DRS_POINTSCALE_A
ポイント プリミティブに対する距離ベースのサイズの減衰を制御する浮動小数点値。D3DRS_POINTSCALEENABLE が TRUE の場合にのみ有効である。デフォルト値は 1.0f である。この値の範囲は、0.0f 以上である。IDirect3DDevice8::SetRenderState メソッドは DWORD 値を使用するため、次のコードに示すように、アプリケーションでは値を格納した変数をキャストしなければならない。
pd3dDevice8->SetRenderState(D3DRS_PATCHSEGMENTS, *((DWORD*)&PointScaleA));
D3DRS_POINTSCALE_B
ポイント プリミティブに対する距離ベースのサイズの減衰を制御する浮動小数点値。D3DRS_POINTSCALEENABLE が TRUE の場合のみ有効である。デフォルト値は 0.0f である。この値の範囲は、0.0f 以上である。IDirect3DDevice8::SetRenderState メソッドは DWORD 値を使用するため、次のコードに示すように、アプリケーションでは値を格納した変数をキャストしなければならない。
pd3dDevice8->SetRenderState(D3DRS_PATCHSEGMENTS, *((DWORD*)&PointScaleB));
D3DRS_POINTSCALE_C
ポイント プリミティブに対する距離ベースのサイズの減衰を制御する浮動小数点値。D3DRS_POINTSCALEENABLE が TRUE の場合のみ有効である。デフォルト値は 0.0f である。この値の範囲は、0.0f 以上である。IDirect3DDevice8::SetRenderState メソッドは DWORD 値を使用するため、次のコードに示すように、アプリケーションでは値を格納した変数をキャストしなければならない。
pd3dDevice8->SetRenderState(D3DRS_PATCHSEGMENTS, *((DWORD*)&PointScaleC));
D3DRS_MULTISAMPLEANTIALIAS
マルチサンプル レンダリングのターゲット バッファを使うときの、個々のサンプルの計算方法を決定する BOOL 値。TRUE を設定すると、複数サンプルのそれぞれについて異なるサンプリング位置でサンプリングすることでフルシーン アンチエイリアシングを実行するように、複数のサンプルが計算される。FALSE を設定すると、複数のサンプルはすべて同じサンプリング値 (ピクセルの中心でサンプリングされた値) で記述される。これにより、マルチサンプル バッファに対する非アンチエイリアシング レンダリングが可能になる。シングル サンプル バッファへのレンダリング時、このレンダリング ステートはエフェクトを持たない。デフォルト値は TRUE である。
D3DRS_MULTISAMPLEMASK
LSB を先頭とするこのマスクの各ビットは、マルチサンプル レンダリング ターゲットのサンプルの 1 つについての変更を制御する。したがって、8 サンプルのレンダリング ターゲットの場合は、8 つのサンプルのそれぞれに対する 8 つの書き込み許可情報が、下位バイトに格納されている。シングル サンプル バッファへのレンダリング時、このレンダリング ステートはエフェクトを持たない。デフォルト値は 0xFFFFFFFF である。

このレンダリング ステートを使うと、マルチサンプル バッファを蓄積バッファとして使い、各パスがサンプルのサブセットを更新するジオメトリのマルチパス レンダリングを行うことができる。

D3DRS_PATCHEDGESTYLE
パッチ エッジが浮動小数点数スタイルのテッセレーションを使用するかどうかを設定する。設定可能な値は、D3DPATCHEDGESTYLE 列挙型で定義される。
D3DRS_PATCHSEGMENTS
パッチを描画するときに、セグメント数を各エッジの浮動小数点数値として設定する。IDirect3DDevice8::SetRenderState メソッドは DWORD 値を使用するため、次のコードに示すように、アプリケーションでは値を格納した変数をキャストしなければならない。
pd3dDevice8->SetRenderState(D3DRS_PATCHSEGMENTS, *((DWORD*)&NumSegments));
D3DRS_DEBUGMONITORTOKEN
モニタをデバッグする場合にのみ設定する。設定可能な値は、D3DDEBUGMONITORTOKENS 列挙型で定義される。D3DRS_DEBUGMONITORTOKEN が設定されている場合、この呼び出しはデバッグ モニタへのトークンの受け渡しとして処理されることに注意すること。たとえば、D3DDMT_ENABLE または D3DDMT_DISABLE を D3DRS_DEBUGMONITORTOKEN に渡した後、ほかのトークンの値が渡された場合、デバッグ モニタのステート (有効または無効) は変化しない。

このステートは、デバッグ ビルドでのみ有用である。デバッグ モニタのデフォルトは D3DDMT_ENABLE である。

D3DRS_POINTSIZE_MAX
ポイント スプライトが制限される最大サイズを指定する浮動小数点数値。値は、D3DCAPS8 の MaxPointSize メンバ以下で、D3DRS_POINTSIZE_MIN 以上でなければならない。IDirect3DDevice8::SetRenderState メソッドは DWORD 値を使用するため、次のコードに示すように、アプリケーションでは値を格納した変数をキャストしなければならない。
pd3dDevice8->SetRenderState(D3DRS_PONTSIZE_MAX, *((DWORD*)&PointSizeMax));
D3DRS_INDEXEDVERTEXBLENDENABLE
インデックス付きの頂点ブレンディングを有効または無効にする BOOL 値。TRUE を設定すると、インデックス付き頂点ブレンディングが有効になる。FALSE を設定すると、インデックス付き頂点ブレンディングは無効になる。このレンダリング ステートを有効にする場合は、頂点ごとにパック DWORD で行列インデックスを渡さなければならない。このレンダリング ステートを無効にし、D3DRS_VERTEXBLEND ステートを使って頂点ブレンディングを有効にするのは、すべての頂点について行列インデックス 0, 1, 2, 3 を指定することと等しい。
D3DRS_COLORWRITEENABLE
レンダリング ターゲットのカラー バッファに対するチャネルごとの書き込みを有効にする UINT 値。ビットを設定すると、3D レンダリングの間にカラー チャネルが更新される。ビットをクリアすると、カラー チャネルは更新されない。デバイスに対する D3DCAPS8 構造体の PrimitiveMiscCaps メンバで D3DPMISCCAPS_COLORWRITEENABLE 能力ビットを設定すると、この機能を利用できるようになる。このレンダリング ステートは、クリア処理には影響を与えない。デフォルト値は 0x0000000F である。

このレンダリング ステートに対する有効な値は、D3DCOLORWRITEENABLE_ALPHA、D3DCOLORWRITEENABLE_BLUE、D3DCOLORWRITEENABLE_GREEN、および D3DCOLORWRITEENABLE_RED の各フラグの任意の組み合わせである。

D3DRS_TWEENFACTOR
トゥイーン係数を制御する浮動小数点数値。IDirect3DDevice8::SetRenderState メソッドは DWORD 値を使用するため、次のコードに示すように、アプリケーションでは値を格納した変数をキャストしなければならない。
pd3dDevice8->SetRenderState(D3DRS_PATCHSEGMENTS, *((DWORD*)&TweenFactor));
D3DRS_BLENDOP
アルファ ブレンディング レンダリング ステート D3DRS_ALPHABLENDENABLE が TRUE に設定されているときに適用される算術演算を選択するために使用する値。有効値は、D3DBLENDOP 列挙型で定義される。デフォルト値は D3DBLENDOP_ADD である。

D3DPMISCCAPS_BLENDOP デバイス能力がサポートされていない場合は、D3DBLENDOP_ADD が実行される。

D3DRS_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

注意

Direct3D は、アプリケーションでの便宜を考慮して、(D3DRS_WRAPn ステート値の 1 つを明示的に使用する代わりに) 定数 D3DRENDERSTATE_WRAPBIAS を定義し、テクスチャ座標セットのゼロから始まる整数値に基づいて、テクスチャ ラッピングを有効にしたり、無効にしたりする。次の例のように、D3DRENDERSTATE_WRAPBIAS 値をテクスチャ座標セットのゼロ始点インデックスに加算して、そのインデックスに対応する D3DRS_WRAPn 値を計算する。

// 変数 dwIndex のインデックスに対応するテクスチャ座標セットを
// 使用するテクスチャに対して、U/V ラッピングを有効にする。
HRESULT hr = pd3dDevice->SetRenderState(
    dwIndex + D3DRENDERSTATE_WRAPBIAS,
    D3DWRAPCOORD_0 | D3DWRAPCOORD_1);

// dwIndexが 3 の場合、加算の結果の値は、
// D3DRS_WRAP3 (131) に等しくなる。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

IDirect3DDevice8::GetRenderState、IDirect3DDevice8::SetRenderState


D3DRESOURCETYPE

リソースの種類を定義する。

typedef enum _D3DRESOURCETYPE {
    D3DRTYPE_SURFACE                =  1,
    D3DRTYPE_VOLUME                 =  2,
    D3DRTYPE_TEXTURE                =  3,
    D3DRTYPE_VOLUMETEXTURE          =  4,
    D3DRTYPE_CUBETEXTURE            =  5,
    D3DRTYPE_VERTEXBUFFER           =  6,
    D3DRTYPE_INDEXBUFFER            =  7,

    D3DRTYPE_FORCE_DWORD            = 0x7fffffff
} D3DRESOURCETYPE;

定数

D3DRTYPE_SURFACE
サーフェス リソース。
D3DRTYPE_VOLUME
ボリューム リソース。
D3DRTYPE_TEXTURE
テクスチャ リソース。
D3DRTYPE_VOLUMETEXTURE
ボリューム テクスチャ リソース。
D3DRTYPE_CUBETEXTURE
キューブ テクスチャ リソース。
D3DRTYPE_VERTEXBUFFER
頂点バッファ リソース。
D3DRTYPE_INDEXBUFFER
インデックス バッファ リソース。
D3DRTYPE_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

IDirect3DResource8::GetType


D3DSHADEMODE

サポートされているシェーディング モードを記述する定数を定義する。

typedef enum _D3DSHADEMODE {
    D3DSHADE_FLAT               = 1,
    D3DSHADE_GOURAUD            = 2,
    D3DSHADE_PHONG              = 3,

    D3DSHADE_FORCE_DWORD        = 0x7fffffff
} D3DSHADEMODE;

定数

D3DSHADE_FLAT
フラット シェーディング モード。三角形の最初の頂点の色が、表面の色を決定するために使われる。この色は三角形全体にわたってむらなく適用される。つまり、補間されない。スペキュラ アルファは補間される。「注意」を参照すること。
D3DSHADE_GOURAUD
グーロー シェーディング モード。表面の色は、三角形の 3 つの頂点間で、線形補間により決定される。
D3DSHADE_PHONG
サポートされない。
D3DSHADE_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

注意

フラット シェーディング モードの三角形の最初の頂点は、次のように定義される。

  • 三角形リストの場合、三角形 i の最初の頂点は i * 3 である。
  • 三角形ストリップの場合、三角形 i の最初の頂点は頂点 i である。
  • 三角形ファンの場合、三角形 i の最初の頂点は頂点 i + 1 である。

この列挙型のメンバは、D3DRS_SHADEMODE レンダリング ステートの値を定義する。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

D3DRENDERSTATETYPE


D3DSTATEBLOCKTYPE

デバイス ステートの論理グループを定義する。

typedef enum _D3DSTATEBLOCKTYPE {
    D3DSBT_ALL           = 1,
    D3DSBT_PIXELSTATE    = 2,
    D3DSBT_VERTEXSTATE   = 3,

    D3DSBT_FORCE_DWORD   = 0xffffffff
} D3DSTATEBLOCKTYPE;

定数

D3DSBT_ALL
次のすべてのデバイス ステートを取り込む。
現在のすべてのレンダリング ステート | 現在のすべてのクリップ面
現在のすべてのテクスチャ ステージ ステート | 現在のマテリアル
現在のすべてのテクスチャ | 現在のすべてのライトおよび有効なライト パラメータ
現在のパレット | 現在のピクセル シェーダ
現在のすべてのストリーム | 現在のピクセル シェーダ定数
現在のビューポート | 現在の頂点シェーダ
現在のすべてのトランスフォーム | 現在の頂点シェーダ定数

D3DSBT_PIXELSTATE
現在のピクセル シェーダ、ピクセル シェーダ定数、および次のピクセル関連デバイス ステートをすべて取り込む。

レンダリング ステート
D3DRS_ALPHABLENDENABLE D3DRS_ALPHAFUNC
D3DRS_ALPHAREF D3DRS_ALPHATESTENABLE
D3DRS_BLENDOP D3DRS_COLORWRITEENABLE
D3DRS_DESTBLEND D3DRS_DITHERENABLE
D3DRS_EDGEANTIALIAS D3DRS_FILLMODE
D3DRS_FOGDENSITY D3DRS_FOGEND
D3DRS_FOGSTART D3DRS_LASTPIXEL
D3DRS_LINEPATTERN D3DRS_SHADEMODE
D3DRS_SRCBLEND D3DRS_STENCILENABLE
D3DRS_STENCILFAIL D3DRS_STENCILFUNC
D3DRS_STENCILMASK D3DRS_STENCILPASS
D3DRS_STENCILREF D3DRS_STENCILWRITEMASK
D3DRS_STENCILZFAIL D3DRS_TEXTUREFACTOR
D3DRS_WRAP0 ～ D3DRS_WRAP7 D3DRS_ZBIAS
D3DRS_ZENABLE D3DRS_ZFUNC
D3DRS_ZWRITEENABLE

テクスチャ ステージ ステート
D3DTSS_ADDRESSU D3DTSS_ADDRESSV
D3DTSS_ADDRESSW D3DTSS_ALPHAARG0
D3DTSS_ALPHAARG1 D3DTSS_ALPHAARG2
D3DTSS_ALPHAOP D3DTSS_BORDERCOLOR
D3DTSS_BUMPENVLOFFSET D3DTSS_BUMPENVLSCALE
D3DTSS_BUMPENVMAT00 D3DTSS_BUMPENVMAT01
D3DTSS_BUMPENVMAT10 D3DTSS_BUMPENVMAT11
D3DTSS_COLORARG0 D3DTSS_COLORARG1
D3DTSS_COLORARG2 D3DTSS_COLOROP
D3DTSS_MAGFILTER D3DTSS_MAXANISOTROPY
D3DTSS_MAXMIPLEVEL D3DTSS_MINFILTER
D3DTSS_MIPFILTER D3DTSS_MIPMAPLODBIAS
D3DTSS_RESULTARG D3DTSS_TEXCOORDINDEX
D3DTSS_TEXTURETRANSFORMFLAGS

D3DSBT_VERTEXSTATE
現在のすべてのライト、現在の頂点シェーダと頂点シェーダ定数、および D3DTSS_TEXCOORDINDEX と D3DTSS_TEXTURETRANSFORMFLAG で指定されるテクスチャ ステージ ステートを取り込む。また、このフラグは、次の頂点関連デバイス ステートをすべて取り込む。

レンダリング ステート
D3DRS_AMBIENT D3DRS_AMBIENTMATERIALSOURCE
D3DRS_CLIPPING D3DRS_CLIPPLANEENABLE
D3DRS_COLORVERTEX D3DRS_DIFFUSEMATERIALSOURCE
D3DRS_EMISSIVEMATERIALSOURCE D3DRS_FOGDENSITY
D3DRS_FOGEND D3DRS_FOGSTART
D3DRS_FOGTABLEMODE D3DRS_FOGVERTEXMODE
D3DRS_INDEXEDVERTEXBLENDENABLE D3DRS_LIGHTING
D3DRS_LOCALVIEWER D3DRS_MULTISAMPLEANTIALIAS
D3DRS_MULTISAMPLEMASK D3DRS_NORMALIZENORMALS
D3DRS_PATCHEDGESTYLE D3DRS_PATCHSEGMENTS
D3DRS_POINTSCALE_A D3DRS_POINTSCALE_B
D3DRS_POINTSCALE_C D3DRS_POINTSCALEENABLE
D3DRS_POINTSIZE D3DRS_POINTSIZE_MAX
D3DRS_POINTSIZE_MIN D3DRS_POINTSPRITEENABLE
D3DRS_RANGEFOGENABLE D3DRS_SOFTWAREVERTEXPROCESSING
D3DRS_SPECULARMATERIALSOURCE D3DRS_TWEENFACTOR
D3DRS_VERTEXBLEND

D3DSBT_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

注意

D3DSBT_PIXELSTATE および D3DSBT_VERTEXSTATE 値は、異なる論理グループのデバイス ステートをそれぞれ識別するが、ステートによっては両方のグループに共通するものもある。D3DSBT_PIXELSTATE および D3DSBT_VERTEXSTATE の組み合わせは D3DSBT_ALL と同等ではない。D3DSBT_PIXELSTATE および D3DSBT_VERTEXSTATE 値を使うことで、IDirect3DDevice8::DrawPrimitive の呼び出しの間に頻繁に変更されるステートを取り込むことができ、ステート全体を取り込むことによるパフォーマンスへの悪影響はない。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

IDirect3DDevice8::CreateStateBlock


D3DSTENCILOP

ステンシル処理を定義する。

typedef enum _D3DSTENCILOP {
    D3DSTENCILOP_KEEP           = 1,
    D3DSTENCILOP_ZERO           = 2,
    D3DSTENCILOP_REPLACE        = 3,
    D3DSTENCILOP_INCRSAT        = 4,
    D3DSTENCILOP_DECRSAT        = 5,
    D3DSTENCILOP_INVERT         = 6,
    D3DSTENCILOP_INCR           = 7,
    D3DSTENCILOP_DECR           = 8,

    D3DSTENCILOP_FORCE_DWORD    = 0x7fffffff
} D3DSTENCILOP;

定数

D3DSTENCILOP_KEEP
ステンシル バッファ内の項目を更新しない。これがデフォルト値である。
D3DSTENCILOP_ZERO
ステンシル バッファ内の項目を 0 に設定する。
D3DSTENCILOP_REPLACE
ステンシル バッファ内の項目を基準値で置き換える。
D3DSTENCILOP_INCRSAT
ステンシル バッファ内の項目の値を、最大値に達するまで増加させる。ステンシル バッファの最大値については、「注意」を参照すること。
D3DSTENCILOP_DECRSAT
ステンシル バッファ内の項目の値を 0 になるまで減少させる。
D3DSTENCILOP_INVERT
ステンシル バッファ内の項目のビットを反転する。
D3DSTENCILOP_INCR
ステンシル バッファ内の項目の値を増加させ、その値が最大値を超えると 0 に戻す。ステンシル バッファの最大値については、「注意」を参照すること。
D3DSTENCILOP_DECR
ステンシル バッファ内の項目の値を減少させ、その値が 0 より小さくなると最大値に戻す。
D3DSTENCILOP_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

注意

ステンシル バッファの項目は 0 から 2n -1 までの範囲の整数値である。n はステンシル バッファのビット深度である。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

D3DRENDERSTATETYPE


D3DSWAPEFFECT

スワップ エフェクトを定義する。

typedef enum _D3DSWAPEFFECT {
    D3DSWAPEFFECT_DISCARD         = 1,
    D3DSWAPEFFECT_FLIP            = 2,
    D3DSWAPEFFECT_COPY            = 3,
    D3DSWAPEFFECT_COPY_VSYNC      = 4,

    D3DSWAPEFFECT_FORCE_DWORD     = 0xFFFFFFFF
} D3DSWAPEFFECT;

定数

D3DSWAPEFFECT_DISCARD
スワップ エフェクトの D3DSWAPEFFECT_FLIP、D3DSWAPEFFECT_COPY、または D3DSWAPEFFECT_COPY_VSYNC を使ってスワップ チェーンを作成した場合、ランタイムは IDirect3DDevice8::Present 処理がバック バッファの内容に一切影響しないことを保証する。ただし、ウィンドウ スワップ チェーンのフリップ セマンティクスや、フルスクリーン スワップ チェーンのコピー セマンティクスを実装する際などには、この保証を満たすためにかなりのビデオ メモリのオーバーヘッドや処理のオーバーヘッドが伴うことがある。アプリケーションでは D3DSWAPEFFECT_DISCARD スワップ エフェクトを使うことで、これらのオーバーヘッドを回避することができ、最も効率的なスワップ チェーンの表現方法をディスプレイ ドライバ側で選択できる。また、これは、D3DPRESENT_PARAMETERS の MultiSampleType メンバに D3DMULTISAMPLE_NONE 以外の値を指定した際に使用できる唯一のスワップ エフェクトである。

D3DSWAPEFFECT_FLIP を使用するスワップ チェーンと同様、D3DSWAPEFFECT_DISCARD を使用するスワップ チェーンは複数のバック バッファを含んでいることがあり、これらのバッファには IDirect3DDevice8::GetBackBuffer または IDirect3DSwapChain8::GetBackBuffer を使ってアクセスできる。スワップ チェーンは待ち行列として見なすことができ、この待ち行列の中では、次の Present 処理で表示されるバック バッファに常にインデックス 0 が付き、いったん表示されたバッファは待ち行列から破棄される。

このスワップ エフェクトを使用するアプリケーションでは、破棄されるバック バッファの内容を推測することはできないため、バック バッファ全体を更新した後で Present 処理を呼び出す必要がある。これは強制的なことではないが、デバッグ バージョンのランタイムは、破棄されるバック バッファの内容を任意のデータで上書きできるので、開発者はアプリケーションがバック バッファ サーフェス全体を正しく更新していることを確認できる。

フルスクリーン スワップ チェーンの場合、デバイスまたはスワップ チェーンの作成時に D3DPRESENT_PARAMETERS 構造体の FullScreen_PresentationInterval メンバに割り当てられた値によってプレゼンテーション レートが決まる。この値が D3DPRESENT_INTERVAL_IMMEDIATE でない場合、プレゼンテーションはモニタの垂直同期と同期される。ウィンドウ スワップ チェーンの場合、プレゼンテーションはコピー処理によって実装されて、常に即座に実行される。

D3DSWAPEFFECT_FLIP
スワップ チェーンには複数のバック バッファが含まれることがあり、フロント バッファを含む巡回待ち行列として見なすことができる。この待ち行列の中では、バック バッファに常に 0 から N -1 (N はバック バッファの数) までの連続した数字が付けられる。したがって、0 はプレゼンテーションされる最も古いバッファを示す。Present が呼び出されると、待ち行列が「循環」されて、フロント バッファがバック バッファ (N - 1) になり、バック バッファ 0 が新しいフロント バッファになる。

フルスクリーン スワップ チェーンの場合、デバイスまたはスワップ チェーンの作成時に D3DPRESENT_PARAMETERS 構造体の FullScreen_PresentationInterval メンバに割り当てられた値によってプレゼンテーション レートが決まる。この値が D3DPRESENT_INTERVAL_IMMEDIATE でない場合、プレゼンテーションはモニタの垂直同期と同期される。ウィンドウ スワップ チェーンの場合、フリッピングはコピー処理によって実装され、プレゼンテーションは常に即座に実行される。

D3DSWAPEFFECT_COPY
スワップ エフェクトは、単一のバック バッファを構成するスワップ チェーンに対してのみ指定できる。ウィンドウ スワップ チェーンの場合もフルスクリーン スワップ チェーンの場合も、ランタイムはコピーベースの Present 処理によるセマンティクスを保証する。つまり、バック バッファの内容が変更されることはなく、フリップベースの Present 処理で行われるようにフロント バッファの内容で置き換えられることはない。

ウィンドウ スワップ チェーンの場合、Present 処理によってバック バッファの内容がターゲット ウィンドウのクライアント領域に即座にコピーされる。コピー内容とディスプレイ アダプタの垂直帰線間隔との同期処理は行われないため、「テアリング」効果が現れることがある。ウィンドウ アプリケーションでは、そのようなテアリング効果を消したり最小限に抑えるために、D3DSWAPEFFECT_COPY_VSYNC を使うことができる。

フルスクリーン スワップ チェーンの場合、ランタイムはフリップ処理とコピー処理の組み合わせ (必要に応じて、隠しバック バッファでサポートされる) を使って Present 処理を行う。したがって、プレゼンテーションはディスプレイ アダプタの垂直帰線と同期され、そのレートは選択されたプレゼンテーション間隔によって制御される。ただし、D3DPRESENT_INTERVAL_IMMEDIATE フラグで指定されたスワップ チェーンは例外である。(D3DPRESENT_PARAMETERS 構造体の FullScreen_PresentationInterval メンバの説明を参照すること)。この場合、Present 処理は垂直帰線を待機せずに、バック バッファの内容をフロント バッファに直接コピーする。

D3DSWAPEFFECT_COPY_VSYNC
D3DSWAPEFFECT_COPY と同様、このスワップ エフェクトは、単一のバック バッファで構成されるスワップ チェーンでのみ使用できる。上の D3DSWAPEFFECT_COPY で説明したように、スワップ チェーンに適用される Present 処理がコピー セマンティクスを提示することが保証される。

ウィンドウ スワップ チェーンの場合、Present 処理によってバック バッファの内容がターゲット ウィンドウのクライアント領域に即座にコピーされる。アダプタがディスプレイ上の転送先の矩形内でスキャンしている間、ランタイムはコピー処理を避けてテアリング効果を排除しようとする。また、ランタイムは、アダプタのリフレッシュ間隔の間にコピー処理をせいぜい 1 回実行して、プレゼンテーションの頻度を制限する。ただし、アダプタがラスタ ステータスの報告機能をサポートしていない場合には、スワップ チェーンは D3DSWAPEFFECT_COPY スワップ エフェクトで作成されたかのような働きをする。(D3DCAPS8 の Caps メンバについては、D3DCAPS_READ_SCANLINE フラグ値の説明を参照すること)。

フルスクリーン スワップ チェーンの場合、D3DSWAPEFFECT_COPY_VSYNC は D3DSWAPEFFECT_COPY と同じである。ただし、D3DPRESENT_INTERVAL_IMMEDIATE フラグは、D3DSWAPEFFECT_COPY_VSYNC と共に使用した場合には何も効果がない。(D3DPRESENT_PARAMETERS 構造体の FullScreen_PresentationInterval メンバの説明を参照すること)。

D3DSWAPEFFECT_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

注意

Present を呼び出した後のバック バッファの状態は、各スワップ エフェクトによって明確に定義されており、Microsoft®Direct3D® デバイスがフルスクリーン スワップ チェーンとウィンドウ スワップ チェーンのどちらで作成されたかによって、この状態が影響を受けることはない。特に、D3DSWAPEFFECT_FLIP スワップ エフェクトはウィンドウでもフルスクリーンでも同じように動作し、Direct3D ランタイムは外部バッファを作成することでこれを保証している。結果として、そのような悪影響を回避できる場合には、常にアプリケーションで D3DSWAPEFFECT_DISCARD を使うことを推奨する。メモリの消費およびパフォーマンスの点において、このスワップ チェーンは常に最も効率的であることが理由である。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

IDirect3DDevice8::Reset、D3DPRESENT_PARAMETERS


D3DTEXTUREADDRESS

サポートされているテクスチャ アドレッシング モードを記述する定数を定義する。

typedef enum _D3DTEXTUREADDRESS {
    D3DTADDRESS_WRAP            = 1,
    D3DTADDRESS_MIRROR          = 2,
    D3DTADDRESS_CLAMP           = 3,
    D3DTADDRESS_BORDER          = 4,
    D3DTADDRESS_MIRRORONCE      = 5,

    D3DTADDRESS_FORCE_DWORD     = 0x7fffffff
} D3DTEXTUREADDRESS;

定数

D3DTADDRESS_WRAP
すべての整数接合点でテクスチャを貼り合わせる。たとえば、u の値が 0 から 3 までの場合、テクスチャは 3 回繰り返され、ミラーリングは行われない。
D3DTADDRESS_MIRROR
すべての整数接合点でテクスチャのフリッピングが起こることを除けば、D3DTADDRESS_WRAP と同様である。たとえば、u の値が 0 から 1 の範囲にある場合、テクスチャの処理は通常どおりに行われるが、1 から 2 の範囲にある場合はフリップ (ミラー化) が行われ、2 から 3 の範囲の場合は再び通常の処理が行われる。以後、このパターンが繰り返される。
D3DTADDRESS_CLAMP
範囲 [0.0, 1.0] の外側のテクスチャ座標が、それぞれ、0.0 と 1.0 のテクスチャ カラーに設定される。
D3DTADDRESS_BORDER
範囲 [0.0, 1.0] の外側のテクスチャ座標は、境界色に設定される。
D3DTADDRESS_MIRRORONCE
D3DTADDRESS_MIRROR および D3DTADDRESS_CLAMP に類似している。テクスチャ座標の絶対値を取得し (0 を中心にミラーリングされ)、最大値に制限する。最も一般的な用途はボリューム テクスチャで使用することである。ボリューム テクスチャでは、完全な D3DTADDRESS_MIRRORONCE テクスチャアドレッシング モードは必要ないが、データは 1 つの軸に沿って対称である。
D3DTADDRESS_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

D3DTEXTURESTAGESTATETYPE


D3DTEXTUREFILTERTYPE

テクスチャ ステージに対するテクスチャ フィルタリング モードを定義する。

typedef enum _D3DTEXTUREFILTERTYPE {
    D3DTEXF_NONE            = 0,
    D3DTEXF_POINT           = 1,
    D3DTEXF_LINEAR          = 2,
    D3DTEXF_ANISOTROPIC     = 3,
    D3DTEXF_FLATCUBIC       = 4,
    D3DTEXF_GAUSSIANCUBIC   = 5,

    D3DTEXF_FORCE_DWORD     = 0x7fffffff
} D3DTEXTUREFILTERTYPE;

定数

D3DTEXF_NONE
ミップマップ処理を無効にする。ラスタライザは代わりに拡大フィルタを使用する。
D3DTEXF_POINT
テクスチャの拡大フィルタまたは縮小フィルタとして使われる点フィルタリング。希望のピクセル値に最も近い座標を持つテクセルを使用する。

ミップマップ レベル間で使われるテクスチャ フィルタは、最近点ミップマップ フィルタである。ラスタライザは最も近いミップマップ テクスチャのテクセルからの色を使用する。

D3DTEXF_LINEAR
テクスチャの拡大フィルタまたは縮小フィルタとして使われるバイリニア補間フィルタリング。希望のピクセルを囲む 2 x 2 領域のテクセルの重み付き平均を使用する。

ミップマップ レベル間で使われるテクスチャ フィルタは、トライリニア ミップマップ補間である。ラスタライザは、最も近いミップマップ テクスチャ 2 点からのテクセルを使用してピクセル色を線形補間する。

D3DTEXF_ANISOTROPIC
テクスチャの拡大フィルタまたは縮小フィルタとして使われる異方性テクスチャ フィルタリング。テクスチャ ポリゴンとスクリーン平面間の角度の相違により起こる歪みを補正する。
D3DTEXF_FLATCUBIC
テクスチャ拡大フィルタとして使われる平面キューブ フィルタリング。
D3DTEXF_GAUSSIANCUBIC
テクスチャ拡大フィルタとして使われるガウス キューブ フィルタリング。
D3DTEXF_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

注意

デバイスの有効なフィルタリング モードがすべてボリューム マップに適用されるわけではない。一般的に、ボリューム マップでは、D3DTEXF_POINT および D3DTEXF_LINEAR 拡大フィルタがサポートされている。D3DPTEXTURECAPS_MIPVOLUMEMAP が設定されている場合、ボリュームマップでは、D3DTEXF_POINT ミップマップ フィルタと、D3DTEXF_POINT および D3DTEXF_LINEAR 縮小フィルタがサポートされる。デバイスは、ボリューム マップの D3DTEXF_LINEAR ミップマップ フィルタをサポートする場合と、しない場合がある。DirectX 8 デバイスが 2D マップの異方性フィルタリングをサポートしている場合には、必ずしもボリューム マップの異方性フィルタリングをサポートしている必要はない。ただし、異方性フィルタリングがサポートされていない場合、異方性フィルタリングを使用するアプリケーションでは、最も有効なフィルタリング (線形など) を受け取る。

テクスチャ ステージの拡大フィルタを設定するには、IDirect3DDevice8::SetTextureStageState メソッドを呼び出し、第 2 パラメータとして D3DTSS_MAGFILTER 値を指定し、第 3 パラメータとしてこの列挙のメンバのいずれかを指定する。

テクスチャ ステージの縮小フィルタを設定するには、SetTextureStageState メソッドを呼び出し、第 2 パラメータとして D3DTSS_MINFILTER 値を指定し、第 3 パラメータとしてこの列挙のメンバのいずれかを指定する。

ミップマップ レベル間で使用するテクスチャ フィルタを設定するには、SetTextureStageState メソッドを呼び出し、第 2 パラメータとして D3DTSS_MIPFILTER 値を指定し、第 3 パラメータとしてこの列挙のメンバのいずれかを指定する。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

D3DTEXTURESTAGESTATETYPE


D3DTEXTUREOP

ステージごとのテクスチャ ブレンディング処理を定義する。

typedef enum _D3DTEXTUREOP {
    D3DTOP_DISABLE                   =  1,
    D3DTOP_SELECTARG1                =  2,
    D3DTOP_SELECTARG2                =  3,
    D3DTOP_MODULATE                  =  4,
    D3DTOP_MODULATE2X                =  5,
    D3DTOP_MODULATE4X                =  6,
    D3DTOP_ADD                       =  7,
    D3DTOP_ADDSIGNED                 =  8,
    D3DTOP_ADDSIGNED2X               =  9,
    D3DTOP_SUBTRACT                  = 10,
    D3DTOP_ADDSMOOTH                 = 11,
    D3DTOP_BLENDDIFFUSEALPHA         = 12,
    D3DTOP_BLENDTEXTUREALPHA         = 13,
    D3DTOP_BLENDFACTORALPHA          = 14,
    D3DTOP_BLENDTEXTUREALPHAPM       = 15,
    D3DTOP_BLENDCURRENTALPHA         = 16,
    D3DTOP_PREMODULATE               = 17,
    D3DTOP_MODULATEALPHA_ADDCOLOR    = 18,
    D3DTOP_MODULATECOLOR_ADDALPHA    = 19,
    D3DTOP_MODULATEINVALPHA_ADDCOLOR = 20,
    D3DTOP_MODULATEINVCOLOR_ADDALPHA = 21,
    D3DTOP_BUMPENVMAP                = 22,
    D3DTOP_BUMPENVMAPLUMINANCE       = 23,
    D3DTOP_DOTPRODUCT3               = 24,
    D3DTOP_MULTIPLYADD               = 25,
    D3DTOP_LERP                      = 26,

    D3DTOP_FORCE_DWORD               = 0x7fffffff,
} D3DTEXTUREOP;

定数

制御メンバ
D3DTOP_DISABLE
このテクスチャ ステージ、およびより高いインデックスを持つステージからの出力をすべて無効にする。テクスチャ マッピングを無効にするには、これを最初のテクスチャ ステージ (ステージ 0) のカラー処理として設定する。カラー処理が有効になっているときは、アルファ処理を無効にすることはできない。カラー ブレンディングが有効な場合、アルファ処理を D3DTOP_DISABLE に設定すると、不定の動作が生じる。
D3DTOP_SELECTARG1
このテクスチャ ステージの最初の色、またはアルファ引数を変更せずに出力として使用する。この処理は、D3DTSS_COLOROP テクスチャ ステージ ステートで使用すると色引数に影響を与え、D3DTSS_ALPHAOP で使用した場合にはアルファ引数に影響を与える。

D3DTOP_SELECTARG2
このテクスチャ ステージの 2 番目の色、またはアルファ引数を変更せずに出力として使用する。この処理は、D3DTSS_COLOROP テクスチャ ステージ ステートで使用すると色引数に影響を与え、D3DTSS_ALPHAOP で使用した場合にはアルファ引数に影響を与える。

乗算メンバ
D3DTOP_MODULATE
引数の成分を乗算する。

D3DTOP_MODULATE2X
引数の成分を乗算し、その積を左に 1 ビットだけシフト (2 で乗算するのと同じ) して明るくする。

D3DTOP_MODULATE4X
引数の成分を乗算し、その積を左に 2 ビットだけシフト (4 で乗算するのと同じ) して明るくする。

加減算メンバ
D3DTOP_ADD
引数の成分を加算する。

D3DTOP_ADDSIGNED
バイアス値 -0.5 を引数の成分に加算し、値の有効範囲を -0.5 から 0.5 にする。

D3DTOP_ADDSIGNED2X
バイアス値 -0.5 を引数の成分に加算し、その積を左に 1 ビットだけシフトする。

D3DTOP_SUBTRACT
第 1 引数の成分から、対応する第 2 引数の成分を減算する。

D3DTOP_ADDSMOOTH
第 1 および第 2 引数を加算し、次にその積を合計から減算する。

線形アルファ ブレンディング メンバ
D3DTOP_BLENDDIFFUSEALPHA、D3DTOP_BLENDTEXTUREALPHA、D3DTOP_BLENDFACTORALPHA、および D3DTOP_BLENDCURRENTALPHA
各頂点からの補間アルファ (D3DTOP_BLENDDIFFUSEALPHA)、このステージのテクスチャからのアルファ (D3DTOP_BLENDTEXTUREALPHA)、D3DRS_TEXTUREFACTOR レンダリング ステートで設定されるスカラー アルファ (D3DTOP_BLENDFACTORALPHA)、または前のテクスチャ ステージからのアルファ (D3DTOP_BLENDCURRENTALPHA) を使用して、このステージの線形ブレンディングを行う。

D3DTOP_BLENDTEXTUREALPHAPM
あらかじめ乗算されたアルファを使用するテクスチャ ステージの線形ブレンディングを実行する。

スペキュラ マッピング メンバ
D3DTOP_PREMODULATE
現在のテクスチャ ステージと次のテクスチャ ステージの間で乗算を行う。
D3DTOP_MODULATEALPHA_ADDCOLOR
第 1 引数のアルファを使用して第 2 引数のカラーを調整し、その結果を第 1 引数に加算する。この処理は、カラー処理 (D3DTSS_COLOROP) でのみサポートされる。

D3DTOP_MODULATECOLOR_ADDALPHA
引数を調整し、第 1 引数のアルファを加算する。この処理は、カラー処理 (D3DTSS_COLOROP) でのみサポートされる。

D3DTOP_MODULATEINVALPHA_ADDCOLOR
D3DTOP_MODULATEALPHA_ADDCOLOR に類似しているが、第 1 引数のアルファの逆数を使用する。この処理は、カラー処理 (D3DTSS_COLOROP) でのみサポートされる。

D3DTOP_MODULATEINVCOLOR_ADDALPHA
D3DTOP_MODULATECOLOR_ADDALPHA に類似しているが、第 1 引数の色の逆数を使用する。この処理は、カラー処理 (D3DTSS_COLOROP) でのみサポートされる。

バンプマッピング メンバ
D3DTOP_BUMPENVMAP
次のテクスチャ ステージの環境マップ (輝度なし) による、ピクセル単位のバンプ マッピングを実行する。この処理は、カラー処理 (D3DTSS_COLOROP) でのみサポートされる。
D3DTOP_BUMPENVMAPLUMINANCE
次のテクスチャ ステージの環境マップ (輝度あり) による、ピクセル単位のバンプ マッピングを実行する。この処理は、カラー処理 (D3DTSS_COLOROP) でのみサポートされる。
D3DTOP_DOTPRODUCT3
各引数の要素を (符号付要素として) 乗算して積を加算し、得られた合計値をすべてのカラー チャネルに、アルファを含めて複製する。この処理がサポートされるのはカラー処理とアルファ処理に対してである。

DirectX 6.0 および 7.0 のマルチテクスチャ処理では、上記の入力は、符号付きデータをシミュレートするため、使用する前にすべて 0.5 シフトされ (y = x - 0.5)、結果のスカラーは正の値に制限され、3 つの出力チャネルすべてに複製される。また、カラー処理としては、rgb 成分を更新したアルファを更新しないことに注意すること。

ただし、DirectX 8.0 シェーダでは、出力を .rgb または .a コンポーネント、またはその両方 (デフォルト) にルーティングすることを指定できる。アルファ チャネルで個別のスカラー処理を指定することもできる。

三項テクスチャ ブレンディング メンバ
D3DTOP_MULTIPLYADD
積和演算を実行する。最後の 2 つの引数を取り、これらを乗算し、残りの入力/ソース引数に加算し、これを結果に配置する。

SRGBA = Arg1 + Arg2 * Arg3

D3DTOP_LERP
第 1 ソース引数で指定された割合で、第 2 および第 3 ソース引数の間を線形補間する。

SRGBA = (Arg1) * Arg2 + (1-Arg1) * Arg3.

その他のメンバ
D3DTOP_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

注意

この列挙型のメンバは、D3DTSS_COLOROP または D3DTSS_ALPHAOP 値で IDirect3DDevice8::SetTextureStageState メソッドを呼び出してカラー処理またはアルファ処理を設定する際に使用される。

上の式では、SRGBA はテクスチャ処理で作成される RGBA 色、Arg1、Arg2、および Arg3 はテクスチャ引数の完全 RGBA 色である。引数の個々の要素は、添字を付けて表記される。たとえば、引数 1 のアルファ要素は Arg1A として表される。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

D3DTEXTURESTAGESTATETYPE


D3DTEXTURESTAGESTATETYPE

テクスチャ ステージ ステートを定義する。

typedef enum _D3DTEXTURESTAGESTATETYPE {
    D3DTSS_COLOROP               =  1,
    D3DTSS_COLORARG1             =  2,
    D3DTSS_COLORARG2             =  3,
    D3DTSS_ALPHAOP               =  4,
    D3DTSS_ALPHAARG1             =  5,
    D3DTSS_ALPHAARG2             =  6,
    D3DTSS_BUMPENVMAT00          =  7,
    D3DTSS_BUMPENVMAT01          =  8,
    D3DTSS_BUMPENVMAT10          =  9,
    D3DTSS_BUMPENVMAT11          = 10,
    D3DTSS_TEXCOORDINDEX         = 11,
    D3DTSS_ADDRESSU              = 13,
    D3DTSS_ADDRESSV              = 14,
    D3DTSS_BORDERCOLOR           = 15,
    D3DTSS_MAGFILTER             = 16,
    D3DTSS_MINFILTER             = 17,
    D3DTSS_MIPFILTER             = 18,
    D3DTSS_MIPMAPLODBIAS         = 19,
    D3DTSS_MAXMIPLEVEL           = 20,
    D3DTSS_MAXANISOTROPY         = 21,
    D3DTSS_BUMPENVLSCALE         = 22,
    D3DTSS_BUMPENVLOFFSET        = 23,
    D3DTSS_TEXTURETRANSFORMFLAGS = 24,
    D3DTSS_ADDRESSW              = 25,
    D3DTSS_COLORARG0             = 26,
    D3DTSS_ALPHAARG0             = 27,
    D3DTSS_RESULTARG             = 28,

    D3DTSS_FORCE_DWORD           = 0x7fffffff
} D3DTEXTURESTAGESTATETYPE;

定数

D3DTSS_COLOROP
テクスチャ ステージ ステートはテクスチャ カラー ブレンディング処理であり、D3DTEXTUREOP 列挙型のメンバにより識別される。最初のテクスチャ ステージ (ステージ 0) のデフォルト値は D3DTOP_MODULATE であり、それ以外のすべてのステージのデフォルト値は D3DTOP_DISABLE である。
D3DTSS_COLORARG1
テクスチャ ステージ ステートは、そのステージに対する最初の色引数であり、テクスチャ引数フラグにより識別される。デフォルトの引数は D3DTA_TEXTURE である。

読み書き用のテンポラリ レジスタの色を選択するには、D3DTA_TEMP を指定する。D3DTA_TEMP は、D3DPMISCCAPS_TSSARGTEMP デバイス能力が存在する場合にサポートされる。このレジスタのデフォルト値は、(0.0, 0.0, 0.0, 0.0) である。

D3DTSS_COLORARG2
テクスチャ ステージ ステートは、そのステージに対する 2 番目の色引数であり、テクスチャ引数フラグにより識別される。デフォルトの引数は D3DTA_CURRENT である。

読み書き用のテンポラリ レジスタの色を選択するには、D3DTA_TEMP を指定する。D3DTA_TEMP は、D3DPMISCCAPS_TSSARGTEMP デバイス能力が存在する場合にサポートされる。このレジスタのデフォルト値は、(0.0, 0.0, 0.0, 0.0) である。

D3DTSS_ALPHAOP
テクスチャ ステージ ステートは、テクスチャ アルファ ブレンディング処理であり、D3DTEXTUREOP 列挙型のメンバによって識別される。最初のテクスチャ ステージ (ステージ 0) のデフォルト値は D3DTOP_SELECTARG1 であり、それ以外のすべてのステージのデフォルト値は D3DTOP_DISABLE である。
D3DTSS_ALPHAARG1
テクスチャ ステージ ステートは、そのステージに対する最初のアルファ引数であり、テクスチャ引数フラグにより識別される。デフォルトの引数は D3DTA_TEXTURE である。ステージにテクスチャが設定されていない場合は、D3DTA_DIFFUSE がデフォルトの引数となる。

読み書き用のテンポラリ レジスタの色を選択するには、D3DTA_TEMP を指定する。D3DTA_TEMP は、D3DPMISCCAPS_TSSARGTEMP デバイス能力が存在する場合にサポートされる。このレジスタのデフォルト値は、(0.0, 0.0, 0.0, 0.0) である。

D3DTSS_ALPHAARG2
テクスチャ ステージ ステートは、ステージの 2 番目のアルファ引数であり、テクスチャ引数フラグにより識別される。デフォルトの引数は D3DTA_CURRENT である。

読み書き用のテンポラリ レジスタの色を選択するには、D3DTA_TEMP を指定する。D3DTA_TEMP は、D3DPMISCCAPS_TSSARGTEMP デバイス能力が存在する場合にサポートされる。このレジスタのデフォルト値は、(0.0, 0.0, 0.0, 0.0) である。

D3DTSS_BUMPENVMAT00
テクスチャ ステージ ステートは、バンプ マッピング行列の [0][0] 係数に対する浮動小数点値である。デフォルト値は 0.0 である。
D3DTSS_BUMPENVMAT01
テクスチャ ステージ ステートは、バンプ マッピング行列の [0][1] 係数に対する浮動小数点値である。デフォルト値は 0.0 である。
D3DTSS_BUMPENVMAT10
テクスチャ ステージ ステートは、バンプ マッピング行列の [1][0] 係数に対する浮動小数点値である。デフォルト値は 0.0 である。
D3DTSS_BUMPENVMAT11
テクスチャ ステージ ステートは、バンプ マッピング行列の [1][1] 係数に対する浮動小数点値である。デフォルト値は 0.0 である。
D3DTSS_TEXCOORDINDEX
このテクスチャ ステージで使用するために設定されたテクスチャ座標インデックス。このフラグは、固定機能頂点処理でのみ使用する。たとえば、頂点シェーダでは使用しない。頂点シェーダを使ってレンダリングするときは、各ステージのテクスチャ インデックスをデフォルト値に設定する必要がある。各ステージのデフォルトのインデックスは、ステージ インデックスと同じである。このステートには、テクスチャ ステージで使用する、各頂点の座標セットのゼロから始まるインデックスを設定する。頂点 1 個に対して最大 8 組までのテクスチャ座標を設定できる。頂点が、指定されたインデックスのテクスチャ座標セットを含んでいない場合は、u および v 座標 (0,0) がデフォルトで使用される。

また、アプリケーションでは、(設定されるインデックスとの論理和として) 以下のフラグのいずれかを設定して、テクスチャ トランスフォーム用の入力テクスチャ座標を自動的に生成するようMicrosoft® Direct3D® に要求できる。ゼロに解決される D3DTSS_TCI_PASSTHRU を除いて、設定されるインデックスと以下のフラグのいずれかを使用すると、テクスチャ ラッピング モードの決定にインデックスが厳密に使用される。このフラグは環境マッピングを行う場合には特に有効である。

D3DTSS_TCI_PASSTHRU
頂点フォーマット内の指定されたテクスチャ座標を使用する。この値はゼロに解決される。
D3DTSS_TCI_CAMERASPACENORMAL
このステージのテクスチャ トランスフォームの入力テクスチャ座標として、カメラ空間にトランスフォームされた頂点法線を使用する。
D3DTSS_TCI_CAMERASPACEPOSITION
このステージのテクスチャ トランスフォームの入力テクスチャ座標として、カメラ空間にトランスフォームされた頂点位置座標を使用する。
D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR
このステージのテクスチャ トランスフォームの入力テクスチャ座標として、カメラ空間にトランスフォームされた反射ベクトルを使用する。反射ベクトルは入力頂点位置座標と法線ベクトルから計算される。
D3DTSS_ADDRESSU
D3DTEXTUREADDRESS 列挙型のメンバ。u 座標で使用するテクスチャ アドレッシング方法を選択する。デフォルト値は D3DTADDRESS_WRAP である。
D3DTSS_ADDRESSV
D3DTEXTUREADDRESS 列挙型のメンバ。v 座標で使用するテクスチャ アドレッシング方法を選択する。デフォルト値は D3DTADDRESS_WRAP である。
D3DTSS_BORDERCOLOR
[0.0,1.0] の範囲の外にあるテクスチャ座標のラスタ化を実行するときに使用する色を記述する D3DCOLOR 値。デフォルト色は 0x00000000 である。
D3DTSS_MAGFILTER
テクスチャをプリミティブにレンダリングするときに使用するテクスチャ拡大フィルタを示す D3DTEXTUREFILTERTYPE 列挙型のメンバ。デフォルト値は D3DTEXF_POINT である。
D3DTSS_MINFILTER
D3DTEXTUREFILTERTYPE 列挙型のメンバで、テクスチャをプリミティブ上へレンダリングするときに使用するテクスチャ縮小フィルタを示す。デフォルト値は D3DTEXF_POINT である。
D3DTSS_MIPFILTER
D3DTEXTUREFILTERTYPE 列挙型のメンバで、ミップマップ レベル間で使用するテクスチャ フィルタを示す。デフォルト値は D3DTEXF_NONE である。
D3DTSS_MIPMAPLODBIAS
ミップマップ詳細バイアスのレベル。これを利用すると、テクスチャに質量感を与えたり、ぼやけた感じを与えることができる。デフォルト値は 0 である。このステートの値は浮動小数点値である。IDirect3DDevice8::SetTextureStageState および IDirect3DDevice8::GetTextureStageState は DWORD 値を使用するため、以下のコード例で示すように、値を格納した変数をキャストしなければならない。
pd3dDevice->SetTextureStageState(D3DTSS_MIPMAPLODBIAS, *((LPDWORD) (&fBias)));

バイアスの各単位 (+/-1.0) は、正確に 1 ミップマップ レベルごとに選択範囲を変更する。負のバイアスは、使用するミップマップ レベルを大きくする。結果はシャープになるが、ぎざぎざしたイメージになる。正のバイアスは、使用するミップマップ レベルを小さくする。結果はぼやけたイメージになる。また、正のバイアスを指定すると、参照されるテクスチャ データが少なくなり、システムによってはパフォーマンスが向上する場合がある。

D3DTSS_MAXMIPLEVEL
アプリケーションで許容する最大ミップマップ詳細レベル ミップマップ チェーンの先頭を始点とするインデックスとして表現される。低い値の方が、ミップマップ チェーン内の高い詳細レベルを表す。0 がデフォルト値で、全レベルが使用可能であることを示す。0 以外の値は、指定されたインデックスより高い詳細レベルのミップマップを表示できないことを示す。
D3DTSS_MAXANISOTROPY
異方性レベルの最大値。デフォルト値は 1 である。
D3DTSS_BUMPENVLSCALE
バンプマップ輝度に使用する浮動小数点数のスケール値。デフォルト値は 0.0 である。
D3DTSS_BUMPENVLOFFSET
バンプマップ輝度に使用する浮動小数点数のオフセット。デフォルト値は 0.0 である。
D3DTSS_TEXTURETRANSFORMFLAGS
テクスチャ ステージのテクスチャ座標のトランスフォームを制御する D3DTEXTURETRANSFORMFLAGS 列挙型のメンバ。デフォルトは D3DTTFF_DISABLE である。
D3DTSS_ADDRESSW
D3DTEXTUREADDRESS 列挙型のメンバ。w 座標で使用するテクスチャ アドレッシング方法を選択する。デフォルト値は D3DTADDRESS_WRAP である。
D3DTSS_COLORARG0
三項演算 (積和および線形補間) の 3 番目の色オペランドの設定。テクスチャ引数フラグによって識別される。この設定は、D3DTEXOPCAPS_MULTIPLYADD または D3DTEXOPCAPS_LERP デバイス能力が存在する場合にサポートされる。

読み書き用のテンポラリ レジスタの色を選択するには、D3DTA_TEMP を指定する。D3DTA_TEMP は、D3DPMISCCAPS_TSSARGTEMP デバイス能力が存在する場合にサポートされる。このレジスタのデフォルト値は、(0.0, 0.0, 0.0, 0.0) である。

D3DTSS_ALPHAARG0
三項演算 (積和および線形補間) のアルファ チャネル セレクタ オペランドの設定。テクスチャ引数フラグによって識別される。この設定は、D3DTEXOPCAPS_MULTIPLYADD または D3DTEXOPCAPS_LERP デバイス能力が存在する場合にサポートされる。

読み書き用のテンポラリ レジスタの色を選択するには、D3DTA_TEMP を指定する。D3DTA_TEMP は、D3DPMISCCAPS_TSSARGTEMP デバイス能力が存在する場合にサポートされる。このレジスタのデフォルト値は、(0.0, 0.0, 0.0, 0.0) である。

D3DTSS_RESULTARG
このステージの結果のデスティネーション レジスタを選択するための設定。テクスチャ引数フラグによって識別される。この値は、D3DTA_CURRENT (デフォルト値) または D3DTA_TEMP に設定できる。D3DTA_TEMP は、入力引数として以降のステージに読み込むことができる単一のテンポラリ レジスタである。フォグ ブレンダおよびフレーム バッファに渡される最終的な色は D3DTA_CURRENT から取得されるので、最後にアクティブなテクスチャ ステージ ステートはカレントへの書き込みに設定しなければならない。

この設定は、D3DPMISCCAPS_TSSARGTEMP デバイス能力が存在する場合にサポートされる。

D3DTSS_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

注意

この列挙型のメンバは、テクスチャ ステート値を取得および設定するために IDirect3DDevice8::GetTextureStageState メソッドおよび IDirect3DDevice8::SetTextureStageState メソッドで使用する。

D3DTSS_BUMPENVMAT00、D3DTSS_BUMPENVMAT01、D3DTSS_BUMPENVMAT10、および D3DTSS_BUMPENVMAT11 バンプ マッピング行列係数の有効範囲は、-8.0 以上 8.0 未満である。この範囲は、数学的には [-8.0,8.0] と表記する。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

IDirect3DDevice8::GetTextureStageState、IDirect3DDevice8::SetTextureStageState


D3DTEXTURETRANSFORMFLAGS

テクスチャ ステージ ステートの値を定義する。

typedef enum _D3DTEXTURETRANSFORMFLAGS {
    D3DTTFF_DISABLE         =   0,
    D3DTTFF_COUNT1          =   1,
    D3DTTFF_COUNT2          =   2,
    D3DTTFF_COUNT3          =   3,
    D3DTTFF_COUNT4          =   4,
    D3DTTFF_PROJECTED       = 256,

    D3DTTFF_FORCE_DWORD     = 0x7fffffff
} D3DTEXTURETRANSFORMFLAGS;

定数

D3DTTFF_DISABLE
テクスチャ座標はラスタライザに直接渡される。
D3DTTFF_COUNT1
ラスタライザは 1D テクスチャ座標を想定する。
D3DTTFF_COUNT2
ラスタライザは 2D テクスチャ座標を想定する。
D3DTTFF_COUNT3
ラスタライザは 3D テクスチャ座標を想定する。
D3DTTFF_COUNT4
ラスタライザは 4D テクスチャ座標を想定する。
D3DTTFF_PROJECTED
テクスチャ座標は、ラスタライザに渡される前に最後の要素ですべて分割される。たとえば、このフラグが D3DTTFF_COUNT3 と共に指定されている場合、1 番目および 2 番目のテクスチャ座標は、ラスタライザに渡される前に、3 番目の座標で分割される。
D3DTTFF_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

注意

これらのフラグは、D3DTSS_TEXTURETRANSFORMFLAGS テクスチャ ステージ ステートの値を D3DTEXTURESTAGESTATETYPE 列挙型に設定するために使われる。

動作環境

ヘッダー : d3d8types.h で宣言。

参照

D3DTEXTURESTAGESTATETYPE


D3DTRANSFORMSTATETYPE

トランスフォーム ステートの値を記述する定数を定義する。

typedef enum _D3DTRANSFORMSTATETYPE {
    D3DTS_VIEW            =  2,
    D3DTS_PROJECTION      =  3,
    D3DTS_TEXTURE0        = 16,
    D3DTS_TEXTURE1        = 17,
    D3DTS_TEXTURE2        = 18,
    D3DTS_TEXTURE3        = 19,
    D3DTS_TEXTURE4        = 20,
    D3DTS_TEXTURE5        = 21,
    D3DTS_TEXTURE6        = 22,
    D3DTS_TEXTURE7        = 23,

    D3DTS_FORCE_DWORD     = 0x7fffffff
} D3DTRANSFORMSTATETYPE;

定数

D3DTS_VIEW
ビュー トランスフォーム行列として設定されるトランスフォーム行列を識別する。デフォルト値は NULL である (単位行列)。
D3DTS_PROJECTION
射影トランスフォーム行列として設定されるトランスフォーム行列を識別する。デフォルト値は NULL である (単位行列)。
D3DTS_TEXTURE0 ～ D3DTS_TEXTURE7
指定されたテクスチャ ステージに設定されるトランスフォーム行列を識別する。
D3DTS_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

マクロ

D3DTS_WORLD
D3DTS_WORLDMATRIX(0) と同等。
D3DTS_WORLDMATRIX(index)
index のワールド行列を設定するトランスフォーム行列を識別する。頂点ブレンディングに対してのみ、複数のワールド行列が使用される。それ以外の場合は、D3DTS_WORLD のみ使用される。

注意

256 ～ 511 の範囲のトランスフォーム ステートは予約済みであり、D3DTS_WORLDMATRIX および D3DTS_WORLD マクロを使ってインデックス指定できるワールド行列が、最大 256 個まで格納される。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

IDirect3DDevice8::GetTransform、IDirect3DDevice8::MultiplyTransform、IDirect3DDevice8::SetTransform、D3DTS_WORLD、D3DTS_WORLDn、D3DTS_WORLDMATRIX


D3DVERTEXBLENDFLAGS

複数の行列による頂点ブレンディングの際に適用される数値または行列を制御するためのフラグを定義する。

typedef enum _D3DVERTEXBLENDFLAGS {
    D3DVBF_DISABLE  =   0,
    D3DVBF_1WEIGHTS =   1,
    D3DVBF_2WEIGHTS =   2,
    D3DVBF_3WEIGHTS =   3,
    D3DVBF_TWEENING = 255,
    D3DVBF_0WEIGHTS = 256
} D3DVERTEXBLENDFLAGS;

定数

D3DVBF_DISABLE
頂点ブレンディングを無効にする。D3DTS_WORLDMATRIX マクロによって設定されたワールド行列のみを適用する。トランスフォーム ステートに対するインデックス値は 0 である。
D3DVBF_1WEIGHTS
D3DTS_WORLDMATRIX マクロによって設定された 2 つの行列間の頂点ブレンディングを有効にする。トランスフォーム ステートに対するインデックス値は、0 および 1 である。
D3DVBF_2WEIGHTS
D3DTS_WORLDMATRIX マクロによって設定された 3 つの行列間の頂点ブレンディングを有効にする。トランスフォーム ステートに対するインデックス値は、0、1、および 2 である。
D3DVBF_3WEIGHTS
D3DTS_WORLDMATRIX マクロによって設定された 4 つの行列間の頂点ブレンディングを有効にする。トランスフォーム ステートに対するインデックス値は、0、1、2、および 3 である。
D3DVBF_TWEENING
頂点ブレンディングは、D3DRS_TWEENFACTOR に割り当てられた値を使って行われる。
D3DVBF_0WEIGHTS
1.0 の重みで単一の行列を使用する。

注意

この型のメンバは、D3DRS_VERTEXBLEND レンダリング ステートで使用される。

ジオメトリ ブレンディング (複数の行列による頂点ブレンディング) では、各頂点のブレンディング (ベータ) 加重値を持つ頂点フォーマットを使用しなければならない。

動作環境

ヘッダー : D3d8types.h で宣言。

参照

D3DRENDERSTATETYPE、D3DTS_WORLD、D3DTS_WORLDn、D3DTS_WORLDMATRIX,


D3DZBUFFERTYPE

深度バッファ フォーマットを記述する定数を定義する。

typedef enum _D3DZBUFFERTYPE {
    D3DZB_FALSE                 = 0,
    D3DZB_TRUE                  = 1,
    D3DZB_USEW                  = 2,

    D3DZB_FORCE_DWORD           = 0x7fffffff
} D3DZBUFFERTYPE;

定数

D3DZB_FALSE
深度バッファの使用を無効にする。
D3DZB_TRUE
z バッファの使用を可能にする。
D3DZB_USEW
w バッファの使用を可能にする。
D3DZB_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

注意

この列挙型のメンバは、D3DRS_ZENABLE レンダリング ステートで使用される。

動作環境

ヘッダー : d3d8types.h で宣言。

参照

D3DRENDERSTATETYPE


その他の型

ここでは、構造体でも列挙型でもない以下のMicrosoft® Direct3D® 型について記述する。

  • D3DCOLOR


D3DCOLOR

Microsoft® Direct3D® の基本的なカラー タイプを定義する。

typedef DWORD D3DCOLOR;

動作環境

ヘッダー : D3d8types.h で宣言。


テクスチャ引数フラグ

デバイスに対応するそれぞれのテクスチャ ステージは 2 つのテクスチャ引数を持つことができ、これらの引数はテクスチャの色とアルファ チャネルに影響を与える。

テクスチャ引数を取得または設定するには、IDirect3DDevice8::SetTextureStageState メソッドまたは IDirect3DDevice8::GetTextureStageState メソッドを呼び出し、D3DTEXTURESTAGESTATETYPE 列挙型の D3DTSS_COLORARG0、D3DTSS_COLORARG1、D3DTSS_COLORARG2、D3DTSS_ALPHAARG0、D3DTSS_ALPHAARG1、D3DTSS_ALPHAARG2、または D3DTSS_RESULTARG メンバを指定する。

次に示すフラグ (引数と修飾子にまとめられている) をテクスチャ ステージの色とアルファ引数と共に使用することができる。引数フラグと修飾子を組み合わせることはできるが、2 つの引数フラグを組み合わせることはできない。

引数フラグ
D3DTA_CURRENT
テクスチャ引数は前のブレンディング ステージの結果である。最初のテクスチャ ステージ (ステージ 0) の場合、この引数は D3DTA_DIFFUSE と同等である。前のブレンディング ステージがバンプマップ テクスチャ (D3DTOP_BUMPENVMAP 処理) を使用している場合、バンプマップ テクスチャの前のステージからテクスチャが選択される。s が現在のテクスチャ ステージを表し、s – 1 にバンプマップ テクスチャがある場合、この引数はテクスチャ ステージ s – 2 からの結果出力になる。読み書きが許可される。
D3DTA_DIFFUSE
テクスチャ引数は、グーロー シェーディング処理中に頂点の成分から補間して得られたディフューズ色である。頂点がディフューズ色を含まない場合のデフォルト色は 0xFFFFFFFF である。許可は読み取り専用である。
D3DTA_SELECTMASK
すべての引数に対応するマスク値。テクスチャ引数の設定には使用しない。
D3DTA_SPECULAR
テクスチャ引数は、グーロー シェーディング処理中に頂点の成分から補間されたスペキュラ色である。頂点がスペキュラ色を含んでいない場合、デフォルト色は 0xFFFFFFFF である。許可は読み取り専用である。
D3DTA_TEMP
このテクスチャ引数は、読み書き用のテンポラリ レジスタの色である。D3DTA_TEMP は、D3DPMISCCAPS_TSSARGTEMP デバイス能力が存在する場合にサポートされる。このレジスタのデフォルト値は、(0.0, 0.0, 0.0, 0.0) である。許可は読み書きである。
D3DTA_TEXTURE
テクスチャ引数は、このテクスチャ ステージのテクスチャ カラーである。許可は読み取り専用である。
D3DTA_TFACTOR
テクスチャ引数は、D3DRS_TEXTUREFACTOR レンダリング ステートを使用して前回 IDirect3DDevice8::SetRenderState を呼び出したときのテクスチャ係数セットである。許可は読み取り専用である。
修正子フラグフラグ
D3DTA_ALPHAREPLICATE
処理が完了する前に、アルファ情報をすべてのカラー チャネルに複製する。これは読み取り修飾子である。
D3DTA_COMPLEMENT
引数の逆数を取る。たとえば、引数の結果が変数 x によって参照される場合、その値は 1.0 - x になる。これは読み取り修飾子である。


柔軟な頂点フォーマット フラグ

柔軟な頂点フォーマット (FVF) は、単一のデータ ストリームにインターリーブされて格納されている頂点のコンテンツを記述するために使われる。FVF コードは、通常、固定機能の頂点処理によって処理されるデータを指定するために使われる。

頂点のフォーマットは、次のフラグによって記述される。頂点フォーマットについては、「頂点フォーマットについて」を参照すること。

柔軟な頂点フォーマット (FVF) フラグ
D3DFVF_DIFFUSE
頂点フォーマットがディフューズ色成分を含む。
D3DFVF_NORMAL
頂点フォーマットが頂点法線ベクトルを含む。このフラグを、D3DFVF_XYZRHW と共に使用することはできない。
D3DFVF_PSIZE
頂点フォーマットはポイント サイズで指定されている。このサイズは、トランスフォーム済みでもライティング済みでもない頂点に対するカメラ空間単位、およびトランスフォーム済みでライティング済みの頂点に対するデバイス空間単位で表されている。
D3DFVF_SPECULAR
頂点フォーマットがスペキュラ色成分を含む。
D3DFVF_XYZ
頂点フォーマットが未トランスフォーム頂点の位置座標を含む。このフラグを、D3DFVF_XYZRHW と共に使用することはできない。
D3DFVF_XYZRHW
頂点フォーマットが、トランスフォームされた頂点の位置座標を含む。このフラグを D3DFVF_XYZ または D3DFVF_NORMAL フラグと同時に使用することはできない。
D3DFVF_XYZB1 ～ D3DFVF_XYZB5
頂点フォーマットは、位置座標データ、および複数の行列による頂点ブレンディング処理用の加重 (ベータ) 値の対応数を含む。現在、Microsoft® Direct3D® では最大 3 つの加重値および 4 つのブレンディング行列でブレンディングが可能である。ブレンディング行列の使い方の詳細については、「インデックス付き頂点ブレンディング」を参照すること。
テクスチャ関連 FVF フラグ
D3DFVF_TEX0 ～ D3DFVF_TEX8
この頂点に対応するテクスチャ座標セットの番号。これらのフラグに対応する数字は連続番号になっていない。
D3DFVF_TEXTUREFORMAT1 ～ D3DFVF_TEXTUREFORMAT4
テクスチャ座標セットを定義する値の番号。D3DFVF_TEXTUREFORMAT1 は 1 次元座標を示し、D3DFVF_TEXTUREFORMAT2 は 2 次元座標を示し、という順に以下続く。このフラグが単独で使用されることはまれで、D3DFVF_TEXCOORDSIZEn マクロと共に使用される。
マスク値
D3DFVF_POSITION_MASK
位置座標ビットを抽出するマスク。
D3DFVF_RESERVED0 および D3DFVF_RESERVED2
柔軟な頂点フォーマットの予約ビットを抽出するためのマスク値。使用不可。
D3DFVF_TEXCOUNT_MASK
テクスチャ フラグ ビットを抽出するためのマスク値。
その他
D3DFVF_LASTBETA_UBYTE4
インデックス付き頂点ブレンディングと固定機能 FVF 頂点シェーダを使用する場合は、頂点シェーダにこのフラグを指定しなければならない。
D3DFVF_TEXCOUNT_SHIFT
頂点のテクスチャ座標数を識別する整数値を何ビット分シフトするかを示す数。この値は、たとえば次のように使用する。
    DWORD dwNumTextures = 1;  // 頂点には座標セットが
// 1 つだけある。

    // FVF の組み合わせを作るときに、値をシフトさせて使用する。
    dwFVF = dwNumTextures<<D3DFVF_TEXCOUNT_SHIFT;

    /*
* シフト後の値を使い、ここで FVF の組み合わせを作成する。
     */

よく使われるフラグの組み合わせ例を次に示す。

    // ライティングされ、テクスチャの付かない、グーローシェーディングされたコンテンツのための、
    // 軽い未トランスフォーム頂点。
    dwFVF = ( D3DFVF_XYZ | D3DFVF_DIFFUSE );

    // ライティングなし、テクスチャなし、グーロー シェーディングあり。
    // 頂点ごとにディフーズ マテリアル色が指定されている未トランスフォーム頂点。
    dwFVF = ( D3DFVF_XYZ | D3DFVF_NORMAL | D3DFVF_DIFFUSE );

    // ライト マップ ベースのライティングに対する未トランスフォーム頂点。
    dwFVF = ( D3DFVF_XYZ | D3DFVF_TEX2 );

    // ライト マップ ベースのライティングに対するトランスフォーム済み頂点。
    // 共有 rhw あり。
    dwFVF = ( D3DFVF_XYZRHW | D3DFVF_TEX2 );

    // 2 つのテクスチャ座標セットを備えた、
    // 未ライティングで、色付きのコンテンツに対する重い頂点。
    dwFVF = ( D3DFVF_XYZ | D3DFVF_NORMAL | D3DFVF_DIFFUSE |
              D3DFVF_SPECULAR | D3DFVF_TEX2 );

参照

頂点フォーマットについて、ジオメトリ ブレンディング


FOURCC コード

Microsoft® Direct3D® および Direct3DX ユーティリティ ライブラリでは、4 文字の長さの特殊なコード セットが使用される。これらのコードは、4 文字コードまたは FOURCC と呼ばれ、ビットマップ イメージ、サウンド、ビデオなどのマルチメディア データを格納するファイルのファイル ヘッダーに保存される。FOURCC は、マルチメディア データを生成するために使用されたソフトウェア テクノロジを示す。また、暗に、データ自体のフォーマットも表す。

Direct3D アプリケーションは、イメージの色やフォーマットの変換に FOURCC を使用する。

FOURCC は、個々のマルチメディア ソフトウェア テクノロジのベンダーによって、Microsoft に登録される。次の一覧は、一般的な FOURCC の一部を示している。

FOURCC | 会社名 | テクノロジ名
AUR2 | AuraVision Corporation | AuraVision Aura 2:YUV 422
AURA | AuraVision Corporation | AuraVision Aura 1:YUV 411
CHAM | Winnov, Inc. | MM_WINNOV_CAVIARA_CHAMPAGNE
CVID | Supermac | Cinepak by Supermac
CYUV | Creative Labs, Inc. | Creative Labs YUV
DXT1 | Microsoft Corporation | DirectX Texture Compression Format 1
DXT2 | Microsoft Corporation | DirectX Texture Compression Format 2
DXT3 | Microsoft Corporation | DirectX Texture Compression Format 3
DXT4 | Microsoft Corporation | DirectX Texture Compression Format 4
DXT5 | Microsoft Corporation | DirectX Texture Compression Format 5
FVF1 | Iterated Systems, Inc. | Fractal Video Frame
IF09 | Intel Corporation | Intel Intermediate YUV9
IV31 | Intel Corporation | Indeo 3.1
JPEG | Microsoft Corporation | Still Image JPEG DIB
MJPG | Microsoft Corporation | Motion JPEG DIB Format
MRLE | Microsoft Corporation | Run Length Encoding
MSVC | Microsoft Corporation | Video 1
PHMO | IBM Corporation | Photomotion
RT21 | Intel Corporation | Indeo 2.1
ULTI | IBM Corporation | Ultimotion
V422 | Vitec Multimedia | 24-bit YUV 4:2:2
V655 | Vitec Multimedia | 16-bit YUV 4:2:2
VDCT | Vitec Multimedia | Video Maker Pro DIB
VIDS | Vitec Multimedia | YUV 4:2:2 CCIR 601 for V422
YU92 | Intel Corporation | YUV
YUV8 | Winnov, Inc. | MM_WINNOV_CAVIAR_YUV8
YUV9 | Intel Corporation | YUV9
YUYV | Canopus, Co., Ltd. | BI_YUYV, Canopus
ZPEG | Metheus | Video Zipper


戻り値

エラーは負の値で表されるので、組み合わせることはできない。このリストは、Microsoft® Direct3D® メソッドが返すことのできる値をまとめたものである。各メソッドが返す値の一覧については、各メソッドについての説明を参照すること。これらのリストは必ずしも包括的なものとは限らない。

D3D_OK
エラーは発生していない。
D3DERR_CONFLICTINGRENDERSTATE
現在設定されているレンダリング ステートは一緒に使用できない。
D3DERR_CONFLICTINGTEXTUREFILTER
現在のテクスチャ フィルタは一緒に使用できない。
D3DERR_CONFLICTINGTEXTUREPALETTE
現在のテクスチャは同時に使用できない。一般にマルチテクスチャ デバイスにおいて、同時に有効にされたパレット化テクスチャで同じパレットを共有する必要がある場合に発生する。
D3DERR_DEVICELOST
デバイスが失われていて、現時点では復元できないため、レンダリングは不可能である。
D3DERR_DEVICENOTRESET
デバイスはリセットできない。
D3DERR_DRIVERINTERNALERROR
内部ドライバ エラー。
D3DERR_INVALIDCALL
メソッドの呼び出しが無効である。たとえば、メソッドのパラメータに無効な値が設定されている場合など。
D3DERR_INVALIDDEVICE
要求されたデバイスの種類が有効でない。
D3DERR_MOREDATA
指定されたバッファ サイズに保持できる以上のデータが存在する。
D3DERR_NOTAVAILABLE
このデバイスは、照会されたテクニックをサポートしていない。
D3DERR_NOTFOUND
要求された項目が見つからなかった。
D3DERR_OUTOFVIDEOMEMORY
Direct3D が処理を行うのに十分なディスプレイ メモリがない。
D3DERR_TOOMANYOPERATIONS
デバイスがサポートしている以上のテクスチャ フィルタリング処理を、アプリケーションが要求している。
D3DERR_UNSUPPORTEDALPHAARG
アルファ チャネルに対して指定されているテクスチャ ブレンディング引数を、デバイスがサポートしていない。
D3DERR_UNSUPPORTEDALPHAOPERATION
アルファ チャネルに対して指定されているテクスチャ ブレンディング処理を、デバイスがサポートしていない。
D3DERR_UNSUPPORTEDCOLORARG
カラー値に対して指定されているテクスチャ ブレンディング引数を、デバイスがサポートしていない。
D3DERR_UNSUPPORTEDCOLOROPERATION
カラー値に対して指定されているテクスチャ ブレンディング処理を、デバイスがサポートしていない。
D3DERR_UNSUPPORTEDFACTORVALUE
デバイスが指定されたテクスチャ係数値をサポートしていない。
D3DERR_UNSUPPORTEDTEXTUREFILTER
デバイスが指定されたテクスチャ フィルタをサポートしていない。
D3DERR_WRONGTEXTUREFORMAT
テクスチャ サーフェスのピクセル フォーマットが有効でない。
E_FAIL
Direct3D サブシステム内で原因不明のエラーが発生した。
E_INVALIDARG
無効なパラメータが戻ってくる関数に渡された。
E_INVALIDCALL
メソッドの呼び出しが無効である。たとえば、メソッドのパラメータに無効な値が設定されている場合など。
E_OUTOFMEMORY
Direct3D が呼び出しを完了するための十分なメモリを割り当てることができなかった。
S_OK
エラーは発生していない。


Direct3DX C/C++ リファレンス

ここでは、Direct3DX ユーティリティ ライブラリが提供する API 要素のリファレンス情報を記述する。リファレンス情報は、次のカテゴリに分類される。

  • インターフェイス
  • 関数
  • マクロ
  • 構造体
  • C++ 固有の機能
  • 戻り値


インターフェイス

ここでは、Direct3DX ユーティリティ ライブラリが提供する COM インターフェイスのリファレンス情報を記述する。Direct3DX ユーティリティ ライブラリでは次のインターフェイスが使用される。

  • ID3DXBaseMesh
  • ID3DXBuffer
  • ID3DXEffect
  • ID3DXFont
  • ID3DXMatrixStack
  • ID3DXMesh
  • ID3DXPMesh
  • ID3DXRenderToSurface
  • ID3DXSkinMesh
  • ID3DXSPMesh
  • ID3DXSprite
  • ID3DXTechnique


ID3DXBaseMesh

アプリケーションは、ID3DXBaseMesh インターフェイスのメソッドを使用して、メッシュ オブジェクトやプログレッシブ メッシュ オブジェクトの操作および照会を行う。

ID3DXBaseMesh インターフェイスのメソッドは、以下のグループにまとめることができる。

バッファ | GetIndexBuffer
 | GetVertexBuffer
 | LockIndexBuffer
 | LockVertexBuffer
 | UnlockIndexBuffer
 | UnlockVertexBuffer
コピー | CloneMesh
 | CloneMeshFVF
面 | GetNumFaces
情報 | GetDevice
 | GetOptions
レンダリング | DrawSubset
 | GetAttributeTable
頂点 | GetDeclaration
 | GetFVF
 | GetNumVertices

ID3DXBaseMesh インターフェイスは、すべての COM インターフェイスと同じように、IUnknown インターフェイスのメソッドを継承している。IUnknown インターフェイスでは、次の 3 つのメソッドがサポートされている。

IUnknown | AddRef
 | QueryInterface
 | Release

メッシュとは、ポリゴンの面のセットで構成されるオブジェクトである。メッシュは、頂点のセットおよび面のセットを定義する (面は、メッシュの頂点と法線によって定義される)。

LPD3DXBASEMESH 型は、ID3DXBaseMesh インターフェイスへのポインタとして定義されている。

typedef struct ID3DXBaseMesh *LPD3DXBASEMESH;

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXMesh、ID3DXPMesh


ID3DXBaseMesh::CloneMesh

宣言子を使用してメッシュのコピーを作成する。

HRESULT CloneMesh(
  DWORD Options,
  CONST DWORD* pDeclaration,
  LPDIRECT3DDEVICE8 pD3DDevice,
  LPD3DXMESH* ppCloneMesh
);

パラメータ

Options
[in] メッシュの作成オプションを指定する 1 つ以上のフラグの組み合わせ。次のフラグが定義されている。
D3DXMESH_32BIT
メッシュに、16 ビットではなく 32 ビットのインデックスを作成する。32 ビットのメッシュは、最大 2^32-1 の面と頂点を含むことができる。このフラグはサポートされていないため、使用すべきではない。
D3DXMESH_DONOTCLIP
頂点バッファおよびインデックス バッファに D3DUSAGE_DONOTCLIP 利用フラグを使用する。
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC と D3DXMESH_IB_DYNAMIC の両方を指定したことになる。
D3DXMESH_RTPATCHES
頂点バッファおよびインデックス バッファに D3DUSAGE_RTPATCHES 利用フラグを使用する。
D3DXMESH_NPATCHES
このフラグを指定すると、メッシュの頂点バッファおよびインデックス バッファが D3DUSAGE_NPATCHES フラグを使用して作成されることになる。これは、Microsoft® Direct3D® の N パッチ拡張機能を使用してメッシュ オブジェクトをレンダリングする場合に必要となる。
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED と D3DXMESH_IB_MANAGED の両方を指定したことになる。
D3DXMESH_POINTS
頂点バッファおよびインデックス バッファに D3DUSAGE_POINTS 利用フラグを使用する。
D3DXMESH_IB_DYNAMIC
インデックス バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_IB_MANAGED
インデックス バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_IB_SYSTEMMEM
インデックス バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_IB_WRITEONLY
インデックス バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM と D3DXMESH_IB_SYSTEMMEM の両方を指定したことになる。
D3DXMESH_VB_DYNAMIC
頂点バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_VB_MANAGED
頂点バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_VB_SHARE
コピーしたメッシュに頂点バッファを共有させる。これらのメッシュは、共有する頂点バッファにインデックス付けする個別のインデックス バッファを備える。
D3DXMESH_VB_SYSTEMMEM
頂点バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_VB_WRITEONLY
頂点バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY と D3DXMESH_IB_WRITEONLY の両方を指定したことになる。
pDeclaration
[in] 出力メッシュに含まれる頂点の頂点フォーマットを記述する宣言子を表す、DWORD 値の配列へのポインタ。このパラメータは FVF に直接マップしなければならない。
pD3DDevice
[in] メッシュに関連付けられているデバイス オブジェクトを表す IDirect3DDevice8 インターフェイスへのポインタ。
ppCloneMesh
[out, retval] コピーされたメッシュを表す ID3DXMesh インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

対象

このメソッドは、ID3DXBaseMesh を継承する次のインターフェイスに適用される。

  • ID3DXMesh
  • ID3DXPMesh

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXBaseMesh::GetDeclaration、D3DXDeclaratorFromFVF


ID3DXBaseMesh::CloneMeshFVF

柔軟な頂点フォーマット (FVF) コードを使用してメッシュのコピーを作成する。

HRESULT CloneMeshFVF(
  DWORD Options,
  DWORD FVF,
  LPDIRECT3DDEVICE8 pD3DDevice,
  LPD3DXMESH* ppCloneMesh
);

パラメータ

Options
[in] メッシュの作成オプションを指定する 1 つ以上のフラグの組み合わせ。次のフラグが定義されている。
D3DXMESH_32BIT
メッシュに、16 ビットではなく 32 ビットのインデックスを作成する。32 ビットのメッシュは、最大 2^32-1 の面と頂点を含むことができる。このフラグはサポートされていないため、使用すべきではない。
D3DXMESH_DONOTCLIP
頂点バッファおよびインデックス バッファに D3DUSAGE_DONOTCLIP 利用フラグを使用する。
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC と D3DXMESH_IB_DYNAMIC の両方を指定したことになる。
D3DXMESH_RTPATCHES
頂点バッファおよびインデックス バッファに D3DUSAGE_RTPATCHES 利用フラグを使用する。
D3DXMESH_NPATCHES
このフラグを指定すると、メッシュの頂点バッファおよびインデックス バッファが D3DUSAGE_NPATCHES フラグを使用して作成されることになる。これは、Microsoft® Direct3D® の N パッチ拡張機能を使用してメッシュ オブジェクトをレンダリングする場合に必要となる。
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED と D3DXMESH_IB_MANAGED の両方を指定したことになる。
D3DXMESH_POINTS
頂点バッファおよびインデックス バッファに D3DUSAGE_POINTS 利用フラグを使用する。
D3DXMESH_IB_DYNAMIC
インデックス バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_IB_MANAGED
インデックス バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_IB_SYSTEMMEM
インデックス バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_IB_WRITEONLY
インデックス バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM と D3DXMESH_IB_SYSTEMMEM の両方を指定したことになる。
D3DXMESH_VB_DYNAMIC
頂点バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_VB_MANAGED
頂点バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_VB_SHARE
コピーしたメッシュに頂点バッファを共有させる。これらのメッシュは、共有する頂点バッファにインデックス付けする個別のインデックス バッファを備える。
D3DXMESH_VB_SYSTEMMEM
頂点バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_VB_WRITEONLY
頂点バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY と D3DXMESH_IB_WRITEONLY の両方を指定したことになる。
FVF
[in] 出力メッシュに含まれる頂点の頂点フォーマットを指定する柔軟な頂点フォーマット フラグの組み合わせ。
pD3DDevice
[in] メッシュに関連付けられているデバイス オブジェクトを表す IDirect3DDevice8 インターフェイスへのポインタ。
ppCloneMesh
[out, retval] コピーされたメッシュを表す ID3DXMesh インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

対象

このメソッドは、ID3DXBaseMesh を継承する次のインターフェイスに適用される。

  • ID3DXMesh
  • ID3DXPMesh

注意

CloneMeshFVF を使用して、メッシュを 1 つの FVF から別の FVF に変換できる。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXBaseMesh::GetFVF、D3DXFVFFromDeclarator


ID3DXBaseMesh::DrawSubset

メッシュのサブセットを描画する。

HRESULT DrawSubset(
  DWORD AttribId
);

パラメータ

AttribId
[in] 描画するメッシュのサブセットを指定する DWORD。この値は、メッシュ内の面を、1 つ以上の属性グループに属しているとして区別するために使用される。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

対象

このメソッドは、ID3DXBaseMesh を継承する次のインターフェイスに適用される。

  • ID3DXMesh
  • ID3DXPMesh

注意

属性テーブルは、異なるテクスチャ、レンダリング ステート、マテリアルなどによって描画する必要があるメッシュの領域を識別するために使用される。さらにアプリケーションは、属性テーブルを使用し、フレームの描画時に所定の属性識別子 (AttribId) を描画しないことによって、メッシュの一部を隠すことができる。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXBaseMesh::GetAttributeTable


ID3DXBaseMesh::GetAttributeTable

メッシュの属性テーブル、またはメッシュの属性テーブルに格納されているエントリの数を取得する。

HRESULT GetAttributeTable(
  D3DXATTRIBUTERANGE* pAttribTable,
  DWORD* pAttribTableSize
);

パラメータ

pAttribTable
[in, out] メッシュの属性テーブルに格納されているエントリを表す、D3DXATTRIBUTERANGE 構造体の配列へのポインタ。NULL を指定して pAttribTableSize の値を取得する。
pAttribTableSize
[in, out] pAttribTable に格納されているエントリ数、またはメッシュの属性テーブルに格納されているエントリ数で埋める値のどちらかへのポインタ。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

対象

このメソッドは、ID3DXBaseMesh を継承する次のインターフェイスに適用される。

  • ID3DXMesh
  • ID3DXPMesh

注意

属性テーブルは ID3DXMesh::Optimize によって作成され、D3DXMESHOPT_ATTRSORT を Flags パラメータに渡す。

属性テーブルは、異なるテクスチャ、レンダリング ステート、マテリアルなどによって描画する必要があるメッシュの領域を識別するために使用される。さらにアプリケーションは、属性テーブルを使用し、フレームの描画時に所定の属性識別子を描画しないことによって、メッシュの一部を隠すことができる。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXBaseMesh::GetDeclaration

メッシュに含まれる頂点を記述する宣言を取得する。

HRESULT GetDeclaration(
  DWORD Declaration[MAX_FVF_DECL_SIZE]
);

パラメータ

Declaration
[in, out] 照会されたメッシュに含まれる頂点の頂点フォーマットを記述する返された配列。この宣言子の配列の上限は MAX_FVF_DECL_SIZE で、宣言子を 15 DWORD の最大数に制限する。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

対象

このメソッドは、ID3DXBaseMesh を継承する次のインターフェイスに適用される。

  • ID3DXMesh
  • ID3DXPMesh

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXBaseMesh::GetFVF


ID3DXBaseMesh::GetDevice

メッシュに関連付けられているデバイスを取得する。

HRESULT GetDevice(
  LPDIRECT3DDEVICE8* ppDevice

パラメータ

ppDevice
[out, retval] メッシュに関連付けられている Microsoft® Direct3D® デバイス オブジェクトを表す、IDirect3DDevice8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

対象

このメソッドは、ID3DXBaseMesh を継承する次のインターフェイスに適用される。

  • ID3DXMesh
  • ID3DXPMesh

注 このメソッドを呼び出すと、IDirect3DDevice8 インターフェイスの内部参照カウントが増加する。この IDirect3DDevice8 の処理が終了したら、必ず IUnknown::Release を呼び出す必要がある。そうしないと、メモリ リークが発生する。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXBaseMesh::GetFVF

メッシュに含まれる頂点の柔軟な頂点フォーマットを取得する。

DWORD GetFVF();

パラメータ

なし。

戻り値

照会されたメッシュに含まれる頂点の柔軟な頂点フォーマットを記述する、柔軟な頂点フォーマット フラグの組み合わせを返す。

対象

このメソッドは、ID3DXBaseMesh を継承する次のインターフェイスに適用される。

  • ID3DXMesh
  • ID3DXPMesh

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXBaseMesh::GetDeclaration


ID3DXBaseMesh::GetIndexBuffer

インデックス バッファ内のデータを取得する。

HRESULT GetIndexBuffer(
  LPDIRECT3DINDEXBUFFER8* ppIB
);

パラメータ

ppIB
[out, retval] メッシュに関連付けられているインデックス バッファ オブジェクトを表す、IDirect3DIndexBuffer8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

対象

このメソッドは、ID3DXBaseMesh を継承する次のインターフェイスに適用される。

  • ID3DXMesh
  • ID3DXPMesh

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXBaseMesh::GetNumFaces

メッシュに含まれる面の数を取得する。

DWORD GetNumFaces();

パラメータ

なし。

戻り値

メッシュに含まれる面の数を返す。

対象

このメソッドは、ID3DXBaseMesh を継承する次のインターフェイスに適用される。

  • ID3DXMesh
  • ID3DXPMesh

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXBaseMesh::GetNumVertices

メッシュに含まれる頂点の数を取得する。

DWORD GetNumVertices();

パラメータ

なし。

戻り値

メッシュに含まれる頂点の数を返す。

対象

このメソッドは、ID3DXBaseMesh を継承する次のインターフェイスに適用される。

  • ID3DXMesh
  • ID3DXPMesh

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXBaseMesh::GetOptions

このメッシュの作成時に有効になっているメッシュ オプションを取得する。

DWORD GetOptions();

パラメータ

なし。

戻り値

このメッシュの作成時に有効になっているオプションを示す、次の 1 つ以上のフラグの組み合わせを返す。

D3DXMESH_32BIT
メッシュに、16 ビットではなく 32 ビットのインデックスを作成する。32 ビットのメッシュは、最大 2^32-1 の面と頂点を含むことができる。このフラグはサポートされていないため、使用すべきではない。
D3DXMESH_DONOTCLIP
頂点バッファおよびインデックス バッファに D3DUSAGE_DONOTCLIP 利用フラグを使用する。
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC と D3DXMESH_IB_DYNAMIC の両方を指定したことになる。
D3DXMESH_RTPATCHES
頂点バッファおよびインデックス バッファに D3DUSAGE_RTPATCHES 利用フラグを使用する。
D3DXMESH_NPATCHES
このフラグを指定すると、メッシュの頂点バッファおよびインデックス バッファが D3DUSAGE_NPATCHES フラグを使用して作成されることになる。これは、Microsoft® Direct3D® の N パッチ拡張機能を使用してメッシュ オブジェクトをレンダリングする場合に必要となる。
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED と D3DXMESH_IB_MANAGED の両方を指定したことになる。
D3DXMESH_POINTS
頂点バッファおよびインデックス バッファに D3DUSAGE_POINTS 利用フラグを使用する。
D3DXMESH_IB_DYNAMIC
インデックス バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_IB_MANAGED
インデックス バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_IB_SYSTEMMEM
インデックス バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_IB_WRITEONLY
インデックス バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM と D3DXMESH_IB_SYSTEMMEM の両方を指定したことになる。
D3DXMESH_VB_DYNAMIC
頂点バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_VB_MANAGED
頂点バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_VB_SYSTEMMEM
頂点バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_VB_WRITEONLY
頂点バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY と D3DXMESH_IB_WRITEONLY の両方を指定したことになる。

対象

このメソッドは、ID3DXBaseMesh を継承する次のインターフェイスに適用される。

  • ID3DXMesh
  • ID3DXPMesh

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXBaseMesh::GetVertexBuffer

頂点バッファ内のデータを取得する。

HRESULT GetVertexBuffer(
  LPDIRECT3DVERTEXBUFFER8* ppVB
);

パラメータ

ppVB
[out, retval] メッシュに関連付けられている頂点バッファ オブジェクトを表す、IDirect3DVertexBuffer8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

対象

このメソッドは、ID3DXBaseMesh を継承する次のインターフェイスに適用される。

  • ID3DXMesh
  • ID3DXPMesh

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXBaseMesh::LockIndexBuffer

インデックス バッファをロックし、インデックス バッファ メモリへのポインタを取得する。

HRESULT LockIndexBuffer(
  DWORD Flags,
  BYTE** ppData
);

パラメータ

Flags
[in] インデックス バッファ メモリをどのようにロックするかを記述する、1 つ以上のロッキング フラグの組み合わせ。
D3DLOCK_DISCARD
アプリケーションは、ロックされている領域内のすべての場所を、書き込み専用処理で上書きする。これにより、非ネイティブ フォーマットで格納されているリソースは圧縮解除ステップを省略できる。
D3DLOCK_NOOVERWRITE
フレームの開始以降、またはこのフラグを持たない最新のロック以降、描画呼び出しの中で参照されるインデックスのうち、ロック時に修正されるインデックスがないことを表す。これにより、アプリケーションがインデックス バッファにデータを追加するだけの場合に最適化を有効にできる。
D3DLOCK_NOSYSLOCK
ビデオ メモリ ロックのデフォルトの動作は、システム全体のクリティカル セクションを確保し、ロックの期間中はディスプレイ モードが変化しないことを保証するというものである。このフラグを指定すると、システム全体のクリティカル セクションはロックの間保持されない。

ロック処理は若干負荷が高くなるが、システムは、マウス カーソルの移動といったほかの動作を実行できる。このフラグは、それを行わないとシステムの応答に悪影響を及ぼすソフトウェア レンダリングに対するバック バッファのロックのような、長期間のロックに役立つ。

D3DLOCK_READONLY
アプリケーションはバッファに書き込まない。これにより、非ネイティブ フォーマットで格納されているリソースは、アンロック時に再圧縮ステップを省略できる。
ppData
[out, retval] BYTE 値の配列へのポインタのアドレス。戻り値のインデックス データが入力される。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

対象

このメソッドは、ID3DXBaseMesh を継承する次のインターフェイスに適用される。

  • ID3DXMesh
  • ID3DXPMesh

注意

インデックス バッファを操作する場合は、複数のロック呼び出しを行うことができる。ただし、ロック呼び出しの数とアンロック呼び出しの数は一致していなければならない。現在設定されているインデックス バッファでロック カウントが残っている場合、DrawPrimitive の呼び出しは失敗する。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXBaseMesh::UnlockIndexBuffer


ID3DXBaseMesh::LockVertexBuffer

頂点バッファをロックし、頂点バッファ メモリへのポインタを取得する。

HRESULT LockVertexBuffer(
  DWORD Flags,
  BYTE** ppData
);

パラメータ

Flags
[in] 頂点バッファ メモリをどのようにロックするかを表す、1 つ以上のロッキング フラグの組み合わせ。
D3DLOCK_DISCARD
アプリケーションは、ロックされている領域内のすべての場所を、書き込み専用処理で上書きする。これにより、非ネイティブ フォーマットで格納されているリソースは圧縮解除ステップを省略できる。
D3DLOCK_NOOVERWRITE
フレームの開始以降、またはこのフラグを持たない最新のロック以降、描画呼び出しの中で参照される頂点のうち、ロック時に修正される頂点がないことを表す。頂点バッファへのデータの追加だけを行う場合は、このフラグにより処理を最適化できる。
D3DLOCK_NOSYSLOCK
ビデオ メモリ ロックのデフォルトの動作は、システム全体のクリティカル セクションを確保し、ロックの期間中はディスプレイ モードが変化しないことを保証するというものである。このフラグを指定すると、システム全体のクリティカル セクションはロックの間保持されない。

ロック処理は若干負荷が高くなるが、システムは、マウス カーソルの移動といったほかの動作を実行できる。このフラグは、それを行わないとシステムの応答に悪影響を及ぼすソフトウェア レンダリングに対するバック バッファのロックのような、長期間のロックに役立つ。

D3DLOCK_READONLY
アプリケーションはバッファに書き込まない。これにより、非ネイティブ フォーマットで格納されているリソースは、アンロック時に再圧縮ステップを省略できる。
ppData
[out, retval] BYTE 値の配列へのポインタのアドレス。戻り値の頂点データが入力される。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

対象

このメソッドは、ID3DXBaseMesh を継承する次のインターフェイスに適用される。

  • ID3DXMesh
  • ID3DXPMesh

注意

頂点バッファを操作するときは、複数のロック呼び出しを実行できる。ただし、ロック呼び出しの数とロック解除呼び出しの数を一致させる必要がある。現在設定されている頂点バッファでロック カウントが残っている場合、DrawPrimitive の呼び出しは失敗する。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXBaseMesh::UnlockVertexBuffer


ID3DXBaseMesh::UnlockIndexBuffer

インデックス バッファのロックを解除する。

HRESULT UnlockIndexBuffer();

パラメータ

なし。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

対象

このメソッドは、ID3DXBaseMesh を継承する次のインターフェイスに適用される。

  • ID3DXMesh
  • ID3DXPMesh

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXBaseMesh::LockIndexBuffer


ID3DXBaseMesh::UnlockVertexBuffer

頂点バッファのロックを解除する。

HRESULT UnlockVertexBuffer();

パラメータ

なし。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

対象

このメソッドは、ID3DXBaseMesh を継承する次のインターフェイスに適用される。

  • ID3DXMesh
  • ID3DXPMesh

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXBaseMesh::LockVertexBuffer


ID3DXBuffer

ID3DXBuffer インターフェイスはデータ バッファとして使用され、メッシュの最適化およびロードの操作時に、頂点、隣接性、およびマテリアルに関する情報を格納する。バッファ オブジェクトは、任意の長さのデータを返すために使用される。

さらにバッファ オブジェクトは、頂点シェーダとピクセル シェーダを組み立てるメソッドに含まれるオブジェクト コードとエラー メッセージを返すために使用される。

ID3DXBuffer インターフェイスは、D3DXCreateBuffer 関数を呼び出して取得する。

ID3DXBuffer インターフェイスのメソッドは、以下のグループにまとめることができる。

情報 | GetBufferPointer
 | GetBufferSize

ID3DXBuffer インターフェイスは、すべての COM インターフェイスと同じように、IUnknown インターフェイスのメソッドを継承している。IUnknown インターフェイスでは、次の 3 つのメソッドがサポートされている。

IUnknown | AddRef
 | QueryInterface
 | Release

LPD3DXBUFFER 型は、ID3DXBuffer インターフェイスへのポインタとして定義されている。

typedef struct ID3DXBuffer *LPD3DXBUFFER;

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXBuffer::GetBufferPointer

バッファ内のデータに対するポインタを取得する。

LPVOID GetBufferPointer();

パラメータ

なし。

戻り値

バッファ内のデータに対するポインタを返す。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXBuffer::GetBufferSize

バッファ内のデータの合計サイズを取得する。

DWORD GetBufferSize();

パラメータ

なし。

戻り値

バッファ内のデータの合計サイズを返す (バイト単位)。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXEffect

ID3DXEffect インターフェイスは、エフェクトの設定と照会、およびテクニックの選択に使用する。エフェクト オブジェクトには、同じエフェクトをレンダリングする複数のテクニックを格納できる。

  • ID3DXEffect インターフェイスは、D3DXCreateEffect を呼び出すことにより取得される。

ID3DXEffect インターフェイスのメソッドは、以下のグループにまとめることができる。

コピー | CloneEffect
エフェクト | SetDword
 | SetFloat
 | SetMatrix
 | SetPixelShader
 | SetTexture
 | SetVector
 | SetVertexShader
エフェクト情報 | GetDword
 | GetFloat
 | GetMatrix
 | GetParameterDesc
 | GetPixelShader
 | GetTexture
 | GetVector
 | GetVertexShader
情報 | GetDesc
 | GetDevice
テクニック | GetTechnique
 | GetTechniqueDesc

ID3DXEffect インターフェイスは、すべての COM インターフェイスと同じように、IUnknown インターフェイスのメソッドを継承している。IUnknown インターフェイスでは、次の 3 つのメソッドがサポートされている。

IUnknown | AddRef
 | QueryInterface
 | Release

LPD3DXEFFECT 型は、ID3DXEffect インターフェイスへのポインタとして定義されている。

typedef struct ID3DXEffect *LPD3DXEFFECT;

動作環境

ヘッダー : D3dx8effect.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXCreateEffect、D3DXCompileEffect、D3DXCompileEffectFromFileA、D3DXCompileEffectFromFileW


ID3DXEffect::CloneEffect

エフェクトのコピーを作成する。

STDMETHODIMP CloneEffect(
  LPDIRECT3DDEVICE8 pDevice,
  DWORD             Usage,
  LPD3DXEFFECT*     ppEffect
)

パラメータ

pDevice
[in] エフェクトに関連付けられているデバイスを表すIDirect3DDevice8 インターフェイスへのポインタ。
Usage
[in] このエフェクトの使用方法の制御情報。次のフラグを設定できる。
D3DUSAGE_SOFTWAREPROCESSING
エフェクトがソフトウェア処理を使用してレンダリングされることを示す。
ppEffect
[out, retval] コピーされたエフェクトを格納する ID3DXEffect インターフェイスへのポインタ。

戻り値

成功した場合は、S_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

動作環境

ヘッダー : D3dx8effect.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXEffect::GetDesc

エフェクトの説明を取得する。

HRESULT GetDesc(
  D3DXEFFECT_DESC* pDesc
)

パラメータ

pDesc
[in, retval] 返された記述を格納する D3DXEFFECT_DESC 構造体へのポインタ。

戻り値

成功した場合は、S_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : D3dx8effect.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXEFFECT_DESC


ID3DXEffect::GetDevice

エフェクトに関連付けられているデバイスを取得する。

HRESULT GetDevice(
  IDirect3DDevice8** ppDevice
)

パラメータ

ppDevice
[out, retval] エフェクトに関連付けられているデバイスを表す、IDirect3DDevice8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、S_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注 このメソッドを呼び出すと、IDirect3DDevice8 インターフェイスの内部参照カウントが増加する。この IDirect3DDevice8 インターフェイスの処理が終了したら、必ず IUnknown::Release を呼び出す必要がある。そうしないと、メモリ リークが発生する。

動作環境

ヘッダー : D3dx8effect.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXEffect::GetDword

エフェクトに関連付けられている DWORD 値を取得する。

HRESULT GetDword(
  DWORD  Name,
  DWORD* pdw
)

パラメータ

Name
[in] DWORD 値を取得するパラメータの名前。このパラメータは FOURCC コードでなければならない。「注意」を参照すること。
pdw
[out, retval] 返された DWORD を格納する DWORD へのポインタ。

戻り値

成功した場合は、S_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

FOURCC コードは、長さが 4 文字の文字列である。詳細については、「FOURCC コード」を参照すること。

動作環境

ヘッダー : D3dx8effect.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXEffect::SetDword


ID3DXEffect::GetFloat

エフェクトに関連付けられている浮動小数点値を取得する。

HRESULT GetFloat(
  UINT   Name,
  FLOAT* pf
);

パラメータ

Name
[in] 浮動小数点値を取得するパラメータの名前。このパラメータは FOURCC コードでなければならない。「注意」を参照すること。
pf
[out, retval] 返された浮動小数点値を格納する FLOAT へのポインタ。

戻り値

成功した場合は、S_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

FOURCC コードは、長さが 4 文字の文字列である。詳細については、「FOURCC コード」を参照すること。

動作環境

ヘッダー : D3dx8effect.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXEFFECT_DESC 、 ID3DXEffect::SetFloat


ID3DXEffect::GetMatrix

エフェクトに関連付けられている行列を取得する。

HRESULT GetMatrix(
  UINT       Name,
  D3DMATRIX* pMat
);

パラメータ

Name
[in] 行列を取得するパラメータの名前。このパラメータは FOURCC コードでなければならない。「注意」を参照すること。
pMatrix
[out, retval] 返された行列を格納する D3DMATRIX 構造体へのポインタ。

戻り値

成功した場合は、S_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

FOURCC コードは、長さが 4 文字の文字列である。詳細については、「FOURCC コード」を参照すること。

動作環境

ヘッダー : D3dx8effect.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXEFFECT_DESC 、 ID3DXEffect::SetMatrix


ID3DXEffect::GetParameterDesc

特定のエフェクト パラメータに関する情報を取得する。

HRESULT GetParameterDesc(
  UINT                Index,
  D3DXPARAMETER_DESC* pDesc
)

パラメータ

Index
[in] 情報を取得するパラメータのインデックス。
pDesc
[out, retval] パラメータに関する情報を格納する D3DXPARAMETER_DESC 構造体へのポインタ。

戻り値

成功した場合は、S_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : D3dx8effect.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXEffect::GetPixelShader

エフェクトに関連付けられているピクセル シェーダを取得する。

HRESULT GetPixelShader(
  DWORD  Name,
  DWORD* pHandle
)

パラメータ

Name
[in] ピクセル シェーダを取得するパラメータの名前。このパラメータは FOURCC コードでなければならない。「注意」を参照すること。
pHandle
[out, retval] 返されたピクセル シェーダを格納する DWORD へのポインタ。

戻り値

成功した場合は、S_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

FOURCC コードは、長さが 4 文字の文字列である。詳細については、「FOURCC コード」を参照すること。

動作環境

ヘッダー : D3dx8effect.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXEffect::SetPixelShader


ID3DXEffect::GetTechnique

エフェクトに関連付けられているテクニックを取得する。

HRESULT GetTechnique(
  UINT            Name,
  ID3DXTechnique* ppTechnique
);

パラメータ

Name
[in] 取得するテクニックの名前。このパラメータは FOURCC コードでなければならない。「注意」を参照すること。
ppTechnique
[out, retval] 返されたテクニックを格納する ID3DXTechnique インターフェイスへのポインタ。

戻り値

成功した場合は、S_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

FOURCC コードは、長さが 4 文字の文字列である。詳細については、「FOURCC コード」を参照すること。

動作環境

ヘッダー : D3dx8effect.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXTECHNIQUE_DESC 、 ID3DXEffect::GetTechniqueDesc


ID3DXEffect::GetTechniqueDesc

エフェクトに関連付けられているテクニックの説明を取得する。

HRESULT GetTechniqueDesc(
  UINT                Index,
  D3DXTECHNIQUE_DESC* pDesc
)

パラメータ

Index
[in] 取得するテクニック記述の名前。
pDesc
[out, retval] 返された記述を格納する D3DXTECHNIQUE_DESC へのポインタ。

戻り値

成功した場合は、S_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : D3dx8effect.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXTECHNIQUE_DESC 、 ID3DXEffect::GetTechnique


ID3DXEffect::GetTexture

エフェクトに関連付けられているテクスチャを取得する。

HRESULT GetTexture(
  UINT                   Name,
  IDirect3DBaseTexture8* pTex
);

パラメータ

Name
[in] テクスチャを取得するパラメータの名前。このパラメータは FOURCC コードでなければならない。「注意」を参照すること。
pTex
[out, retval] 返されたテクスチャを格納する IDirect3DBaseTexture8 インターフェイスへのポインタ。

戻り値

成功した場合は、S_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

FOURCC コードは、長さが 4 文字の文字列である。詳細については、「FOURCC コード」を参照すること。

注 このメソッドを呼び出すと、IDirect3DBaseTexture8 インターフェイスの内部参照カウントが増加する。この IDirect3DTexture8 インターフェイスの処理が終了したら、必ず IUnknown::Release を呼び出す必要がある。そうしないと、メモリ リークが発生する。

動作環境

ヘッダー : D3dx8effect.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXEffect::SetTexture


ID3DXEffect::GetVector

エフェクトに関連付けられているベクトルを取得する。

HRESULT GetVector(
  UINT         Name,
  D3DXVECTOR4* pVec
);

パラメータ

Name
[in] ベクトルを取得するパラメータの名前。このパラメータは FOURCC コードでなければならない。「注意」を参照すること。
pVec
[out, retval] 返されたベクトルを格納する D3DXVECTOR4 構造体へのポインタ。

戻り値

成功した場合は、S_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

FOURCC コードは、長さが 4 文字の文字列である。詳細については、「FOURCC コード」を参照すること。

動作環境

ヘッダー : D3dx8effect.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXEFFECT_DESC 、 ID3DXEffect::GetVector


ID3DXEffect::GetVertexShader

エフェクトに関連付けられている頂点シェーダを取得する。

HRESULT GetVertexShader(
  DWORD  Name,
  DWORD* pHandle
)

パラメータ

Name
[in] 頂点シェーダを取得するパラメータの名前。このパラメータは FOURCC コードでなければならない。「注意」を参照すること。
pHandle
[out, retval] 返された頂点シェーダを格納する DWORD へのポインタ。

戻り値

成功した場合は、S_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

FOURCC コードは、長さが 4 文字の文字列である。詳細については、「FOURCC コード」を参照すること。

動作環境

ヘッダー : D3dx8effect.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXEFFECT_DESC 、 ID3DXEffect::SetVertexShader


ID3DXEffect::SetDword

エフェクトの DWORD 値を設定する。

HRESULT SetDword(
  UINT  Name,
  DWORD dw
);

パラメータ

Name
[in] 設定するエフェクト パラメータの名前を識別する。このパラメータは FOURCC コードでなければならない。「注意」を参照すること。
dw
[in] Name に割り当てる DWORD 値を指定する。

戻り値

成功した場合は、S_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

FOURCC コードは、長さが 4 文字の文字列である。詳細については、「FOURCC コード」を参照すること。

動作環境

ヘッダー : D3dx8effect.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXEFFECT_DESC 、 ID3DXEffect::GetDword


ID3DXEffect::SetFloat

エフェクトの浮動小数点値を設定する。

HRESULT SetFloat(
  UINT  Name,
  FLOAT f
);

パラメータ

Name
[in] 設定するエフェクト パラメータの名前を識別する。このパラメータは FOURCC コードでなければならない。「注意」を参照すること。
f
[in] Name に割り当てる浮動小数点値を指定する。

戻り値

成功した場合は、S_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

FOURCC コードは、長さが 4 文字の文字列である。詳細については、「FOURCC コード」を参照すること。

動作環境

ヘッダー : D3dx8effect.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXEFFECT_DESC 、 ID3DXEffect::GetFloat


ID3DXEffect::SetMatrix

エフェクトの行列を設定する。

HRESULT SetMatrix(
  UINT Name,
  D3DMATRIX* pMat
);

パラメータ

Name
[in] 設定するエフェクト パラメータの名前を識別する。このパラメータは FOURCC コードでなければならない。「注意」を参照すること。
pMat
[in] Name に割り当てる D3DMATRIX 構造体へのポインタ。

戻り値

成功した場合は、S_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

FOURCC は、長さが 4 文字の文字列である。詳細については、「FOURCC コード」を参照すること。

動作環境

ヘッダー : D3dx8effect.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXEFFECT_DESC 、 ID3DXEffect::GetMatrix


ID3DXEffect::SetPixelShader

エフェクトのピクセル シェーダを設定する。

HRESULT SetPixelShader(
  DWORD Name,
  DWORD Handle
)

パラメータ

Name
[in] 設定するエフェクト パラメータの名前を識別する。このパラメータは FOURCC コードでなければならない。「注意」を参照すること。
Handle
[in] Name に割り当てるピクセル シェーダを指定する。

戻り値

成功した場合は、S_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

FOURCC コードは、長さが 4 文字の文字列である。詳細については、「FOURCC コード」を参照すること。

動作環境

ヘッダー : D3dx8effect.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXEFFECT_DESC 、 ID3DXEffect::GetPixelShader


ID3DXEffect::SetTexture

エフェクトのテクスチャを設定する。

HRESULT SetTexture(
  UINT                  Name,
  IDirect3DBaseTexture8 pTexture
);

パラメータ

Name
[in] 設定するエフェクト パラメータの名前を識別する。このパラメータは FOURCC コードでなければならない。「注意」を参照すること。
pTexture
[in] Name に割り当てるテクスチャを指定する、IDirect3DBaseTexture8 インターフェイスへのポインタ。

戻り値

成功した場合は、S_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

FOURCC コードは、長さが 4 文字の文字列である。詳細については、「FOURCC コード」を参照すること。

注 このメソッドを呼び出すと、IDirect3DBaseTexture8 インターフェイスの内部参照カウントが増加する。この IDirect3BaseTexture8 インターフェイスの処理が終了したら、必ず IUnknown::Release を呼び出す必要がある。そうしないと、メモリ リークが発生する。

動作環境

ヘッダー : D3dx8effect.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXEFFECT_DESC 、 ID3DXEffect::GetTexture


ID3DXEffect::SetVector

エフェクトのベクトルを設定する。

HRESULT SetVector(
  UINT         Name,
  D3DXVECTOR4* pVec
);

パラメータ

Name
[in] 設定するエフェクト パラメータの名前を識別する。このパラメータは FOURCC コードでなければならない。「注意」を参照すること。
pVector
[in] Name に割り当てるベクトルを指定する D3DXVECTOR4 構造体へのポインタ。

戻り値

成功した場合は、S_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

FOURCC コードは、長さが 4 文字の文字列である。詳細については、「FOURCC コード」を参照すること。

動作環境

ヘッダー : D3dx8effect.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXEFFECT_DESC 、 ID3DXEffect::SetVector


ID3DXEffect::SetVertexShader

エフェクトの頂点シェーダを設定する。

HRESULT SetVertexShader(
  DWORD Name,
  DWORD Handle
)

パラメータ

Name
[in] 設定するエフェクト パラメータの名前を識別する。このパラメータは FOURCC コードでなければならない。「注意」を参照すること。
Handle
[in] Name に割り当てる頂点シェーダへのハンドル。

戻り値

成功した場合は、S_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

FOURCC は、長さが 4 文字の文字列である。詳細については、「FOURCC コード」を参照すること。

動作環境

ヘッダー : D3dx8effect.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXEFFECT_DESC 、 ID3DXEffect::SetVertexShader


ID3DXFont

ID3DXFont インターフェイスは、特定デバイス上の特定のフォントをレンダリングするために必要なテクスチャとリソースをカプセル化するために使用する。

ID3DXFont インターフェイスは、D3DXCreateFont または D3DXCreateFontIndirect 関数を呼び出して取得する。

ID3DXFont インターフェイスのメソッドは、以下のグループにまとめることができる。

描画 | Begin
 | DrawTextA
 | DrawTextW
 | End
情報 | GetDevice
 | GetLogFont

ID3DXFont インターフェイスは、すべての COM インターフェイスと同じように、IUnknown インターフェイスのメソッドを継承している。IUnknown インターフェイスでは、次の 3 つのメソッドがサポートされている。

IUnknown | AddRef
 | QueryInterface
 | Release

LPD3DXFONT 型は、ID3DXFont インターフェイスへのポインタとして定義されている。

typedef interface ID3DXFont *LPD3DXFONT;

動作環境

ヘッダー : D3dx8core.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXFont::Begin

テキストを描画できるようにデバイスを準備する。

HRESULT Begin();

パラメータ

なし。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

注意

このメソッドはオプションである。DrawText メソッドが Begin と ID3DXFont::End の対の外側で呼び出された場合、Microsoft® Direct3D® により Begin と End が呼び出される。

動作環境

ヘッダー : D3dx8core.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXFont::End


ID3DXFont::DrawTextA

Microsoft® Direct3D® デバイス上に、整形した ANSI テキストを描画する。

INT DrawTextA(
  LPCSTR pString,
  INT Count,
  LPRECT pRect,
  DWORD Format,
  D3DCOLOR Color
);

パラメータ

pString
[in] 描画する ANSI 文字列へのポインタ。Count パラメータが -1 の場合、文字列は NULL で終わる必要がある。

Format に DT_MODIFYSTRING が含まれている場合は、この関数で最大 4 文字まで文字を追加できる。文字列を保持するバッファは、これらの余分な文字を適応できるように十分な容量がなければならない。

Count
[in] 文字列の文字数を指定する。Count が -1 の場合、パラメータの pString は末尾が Null の文字列へのポインタと見なされ、DrawTextA により文字列カウントが自動的に計算される。
pRect
[in] テキストがフォーマットされる論理座標に矩形を保持する RECT 構造体へのポインタ。
Format
[in] テキストをフォーマットするメソッドを指定する。次の値を任意に組み合わせることができる。
DT_BOTTOM
矩形の底部でテキストを両端揃えにする。この値は DT_SINGLELINE と組み合わせて使用しなければならない。
DT_CALCRECT
矩形の幅と高さを算出する。テキストが複数行ある場合、DrawTextA は pRect パラメータが参照する四角形の幅を使用し、テキストの最後の行が含まれるよう四角形の底辺を延長する。テキストが 1 行だけの場合、DrawTextA は行の最後の文字が収まるよう四角形の右側の辺の位置を修正する。どちらの場合も、DrawTextA は整形されたテキストの高さを返すが、テキストは描画しない。
DT_CENTER
矩形内でテキストを水平方向で中央揃えにする。
DT_EDITCONTROL
マルチライン エディット コントロールのテキスト表示特性を複製する。特に、平均の文字幅はエディット コントロールと同じ方法で計算され、部分的に見える最後の行は表示されない。
DT_END_ELLIPSIS または DT_PATH_ELLIPSIS
省略記号を追加せずに文字列を切り捨て、指定した矩形に収まるようにする。DT_MODIFYSTRING フラグが指定されている場合を除き、文字列は修正されない。

DT_END_ELLIPSIS は文字列の最後で文字を切り捨てるために指定する。DT_PATH_ELLIPSIS は文字列の中間で文字を切り捨てるために指定する。文字列にバックスラッシュ (\) が含まれている場合、DT_PATH_ELLIPSIS は最後のバックスラッシュより後ろにあるテキストをできるだけ多く保持する。

DT_EXPANDTABS
タブ文字を拡張する。タブごとのデフォルトの文字数は 8 字である。DT_WORD_ELLIPSIS、DT_PATH_ELLIPSIS、および DT_END_ELLIPSIS は DT_EXPANDTABS と同時に使用することはできない。
DT_EXTERNALLEADING
行の高さにフォントの外部余白を含める。通常、外部余白は、テキストの行の高さには含まれない。
DT_HIDEPREFIX
Windows 2000 では次のようになる。テキストに含まれるアンパサンド (&) プレフィクス文字を無視する。アンパサンドに続く文字に下線は付かないが、ほかのニーモニックプレフィクス文字はそのまま処理される。

例 :

入力文字列 :"A&bc&&d"

標準 :"Abc&d"

HIDEPREFIX:"Abc&d"

DT_NOPREFIX と DT_PREFIXONLY と比較すること。

DT_INTERNAL
システム フォントを使用してテキスト メトリクスを計算する。
DT_LEFT
テキストを左揃えにする。
DT_MODIFYSTRING
文字列を修正して表示されたテキストに合わせる。DT_END_ELLIPSIS または DT_PATH_ELLIPSIS が指定されている場合のみ、このフラグは有効となる。
DT_NOCLIP
クリッピングせずに描画する。DrawTextA は、DT_NOCLIP を使用するとやや高速である。
DT_NOFULLWIDTHCHARBREAK
Windows 98、Windows 2000 の場合、DBCS (double-wide character string) で改行されないようにする。これにより改行ルールは SBCS の設定と同じになる。たとえば、韓国語版 Windows でアイコン ラベルを読みやすくするために使用される。DT_WORDBREAK が指定されている場合のみ有効である。
DT_NOPREFIX
プレフィクス文字の処理をオフにする。通常、DrawTextA はニーモニック プレフィクス文字の & を、その後に続く文字に下線を付ける命令として解釈し、ニーモニック プレフィクス文字が && と 2 つ続いた場合は、& を 1 つ出力する命令として解釈する。DT_NOPREFIX を指定することにより、この処理はオフになる。「DT_HIDEPREFIX」および「DT_PREFIXONLY」を参照すること。
DT_PREFIXONLY
Windows 2000 では次のようになる。アンパサンド (&) プレフィクス文字に続く文字の位置で、下線のみを描画する。文字列に含まれる文字は描画しない。

例 :

入力文字列 :"A&bc&&d"

標準 :"Abc&d"

PREFIXONLY:

DT_NOPREFIX および DT_HIDEPREFIX と比較すること。

DT_RIGHT
テキストを右端揃えにする。
DT_RTLREADING
ヘブライ語またはアラビア語のフォントが選択されている場合、読みの順序が双方向のテキストについて右から左の順に読むようテキストを表示する。デフォルトの読みの順序は、すべてのテキストで左から右となっている。
DT_SINGLELINE
1 行のみにテキストを表示する。改行と行送りで新しい行に移らない。
DT_TABSTOP
タブ ストップを設定する。Format パラメータのビット 15-8 (低位語の高次バイト) により各タブの文字数を指定する。タブごとのデフォルトの文字数は 8 字である。DT_CALCRECT、DT_EXTERNALLEADING、DT_INTERNAL、DT_NOCLIP、および DT_NOPREFIX は DT_TABSTOP と同時に使用することはできない。
DT_TOP
先頭行のテキストを両端揃えにする (1 行のみ)。
DT_VCENTER
上下方向でテキストを中央揃えにする (1 行のみ)。
DT_WORDBREAK
語を分割する。語が pRect パラメータで指定した矩形の端を超える場合、語と語の間で自動的に改行される。改行/行送りのシーケンスも改行となる。
DT_WORD_ELLIPSIS
矩形に収まらないテキストを切り捨て、省略記号を追加する。
Color
[in] テキストの色を指定する D3DCOLOR 型。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DXERR_INVALIDDATA

注意

DrawText は、#define UNICODE スイッチが含まれているかどうかに応じて、DrawTextA または ID3DXFont::DrawTextW のどちらかをマップする。#define UNICODE スイッチを挿入または除外して、アプリケーションで Unicode または ANSI 文字列のどちらを使用するかを指定する。次のコードは、DrawText の定義方法を示している。

#ifndef DrawText
#ifdef UNICODE
#define DrawText DrawTextW
#else
#define DrawText DrawTextA
#endif
#endif

DrawTextA メソッドは、デバイス コンテキストで選択されたフォント、テキスト カラー、バックグラウンド カラーを使用してテキストを描画する。DT_NOCLIP フォーマットが使用される場合を除き、DrawTextA は指定された四角形の外側にテキストがはみ出ないようテキストをクリップする。DT_SINGLELINE フォーマットが指定されている場合を除き、整形処理では複数行が対象であると見なされる。

選択したフォントが大きすぎて四角形に収まらない場合、DrawTextA メソッドは小さいフォントで置き換える処理を行わない。

DrawTextA メソッドは、escapement と orientation の両方がゼロのフォントのみサポートする。

動作環境

ヘッダー : D3dx8core.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXFont::DrawTextW


ID3DXFont::DrawTextW

Microsoft® Direct3D® デバイス上に、整形した Unicode™ テキストを描画する。

INT DrawTextW(
  LPCWSTR pString,
  INT Count,
  LPRECT pRect,
  DWORD Format,
  D3DCOLOR Color
);

パラメータ

pString
[in] 描画する Unicode 文字列へのポインタ。Count パラメータが -1 の場合、文字列は NULL で終わる必要がある。

Format に DT_MODIFYSTRING が含まれている場合は、この関数で最大 4 文字まで文字を追加できる。文字列を保持するバッファは、これらの余分な文字を適応できるように十分な容量がなければならない。

Count
[in] 文字列の文字数を指定する。Count が -1 の場合、パラメータの pString は末尾が Null の文字列へのポインタと見なされ、DrawTextW により文字列カウントが自動的に計算される。
pRect
[in] テキストがフォーマットされる論理座標に矩形を保持する RECT 構造体へのポインタ。
Format
[in] テキストをフォーマットするメソッドを指定する。次の値を任意に組み合わせることができる。
DT_BOTTOM
矩形の底部でテキストを両端揃えにする。この値は DT_SINGLELINE と組み合わせて使用しなければならない。
DT_CALCRECT
矩形の幅と高さを算出する。テキストが複数行ある場合、DrawTextW は pRect パラメータが参照する四角形の幅を使用し、テキストの最後の行が含まれるよう四角形の底辺を延長する。テキストが 1 行だけの場合、DrawTextW は行の最後の文字が収まるよう四角形の右側の辺の位置を修正する。どちらの場合も、DrawTextW は整形されたテキストの高さを返すが、テキストは描画しない。
DT_CENTER
矩形内でテキストを水平方向で中央揃えにする。
DT_EDITCONTROL
マルチライン エディット コントロールのテキスト表示特性を複製する。特に、平均の文字幅はエディット コントロールと同じ方法で計算され、部分的に見える最後の行は表示されない。
DT_END_ELLIPSIS または DT_PATH_ELLIPSIS
省略記号を追加せずに文字列を切り捨て、指定した矩形に収まるようにする。DT_MODIFYSTRING フラグが指定されている場合を除き、文字列は修正されない。

DT_END_ELLIPSIS は文字列の最後で文字を切り捨てるために指定する。DT_PATH_ELLIPSIS は文字列の中間で文字を切り捨てるために指定する。文字列にバックスラッシュ (\) が含まれている場合、DT_PATH_ELLIPSIS は最後のバックスラッシュより後ろにあるテキストをできるだけ多く保持する。

DT_EXPANDTABS
タブ文字を拡張する。タブごとのデフォルトの文字数は 8 字である。DT_WORD_ELLIPSIS、DT_PATH_ELLIPSIS、および DT_END_ELLIPSIS は DT_EXPANDTABS と同時に使用することはできない。
DT_EXTERNALLEADING
行の高さにフォントの外部余白を含める。通常、外部余白は、テキストの行の高さには含まれない。
DT_HIDEPREFIX
Windows 2000 では次のようになる。テキストに含まれるアンパサンド (&) プレフィクス文字を無視する。アンパサンドに続く文字に下線は付かないが、ほかのニーモニックプレフィクス文字はそのまま処理される。

例 :

入力文字列 :"A&bc&&d"

標準 :"Abc&d"

HIDEPREFIX:"Abc&d"

DT_NOPREFIX および DT_PREFIXONLY と比較すること。

DT_INTERNAL
システム フォントを使用してテキスト メトリクスを計算する。
DT_LEFT
テキストを左揃えにする。
DT_MODIFYSTRING
文字列を修正して表示されたテキストに合わせる。DT_END_ELLIPSIS または DT_PATH_ELLIPSIS が指定されている場合のみ、このフラグは有効となる。
DT_NOCLIP
クリッピングせずに描画する。DrawTextW は、DT_NOCLIP を使用するとやや高速である。
DT_NOFULLWIDTHCHARBREAK
Windows 98、Windows 2000 の場合、DBCS (double-wide character string) で改行されないようにする。これにより改行ルールは SBCS の設定と同じになる。たとえば、韓国語版 Windows でアイコン ラベルを読みやすくするために使用される。DT_WORDBREAK が指定されている場合のみ有効である。
DT_NOPREFIX
プレフィクス文字の処理をオフにする。通常、DrawTextW はニーモニック プレフィクス文字の & を、その後に続く文字に下線を付ける命令として解釈し、ニーモニック プレフィクス文字が && と 2 つ続いた場合は、& を 1 つ出力する命令として解釈する。DT_NOPREFIX を指定することにより、この処理はオフになる。「DT_HIDEPREFIX」および「DT_PREFIXONLY」を参照すること。
DT_PREFIXONLY
Windows 2000 では次のようになる。アンパサンド (&) プレフィクス文字に続く文字の位置で、下線のみを描画する。文字列に含まれる文字は描画しない。

例 :

入力文字列 :"A&bc&&d"

標準 :"Abc&d"

PREFIXONLY:

DT_NOPREFIX および DT_HIDEPREFIX と比較すること。

DT_RIGHT
テキストを右端揃えにする。
DT_RTLREADING
ヘブライ語またはアラビア語のフォントが選択されている場合、読みの順序が双方向のテキストについて右から左の順に読むようテキストを表示する。デフォルトの読みの順序は、すべてのテキストで左から右となっている。
DT_SINGLELINE
1 行のみにテキストを表示する。改行と行送りで新しい行に移らない。
DT_TABSTOP
タブ ストップを設定する。Format パラメータのビット 15-8 (低位語の高次バイト) により各タブの文字数を指定する。タブごとのデフォルトの文字数は 8 字である。DT_CALCRECT、DT_EXTERNALLEADING、DT_INTERNAL、DT_NOCLIP、および DT_NOPREFIX は DT_TABSTOP と同時に使用することはできない。
DT_TOP
先頭行のテキストを両端揃えにする (1 行のみ)。
DT_VCENTER
上下方向でテキストを中央揃えにする (1 行のみ)。
DT_WORDBREAK
語を分割する。語が pRect パラメータで指定した矩形の端を超える場合、語と語の間で自動的に改行される。改行/行送りのシーケンスも改行となる。
DT_WORD_ELLIPSIS
矩形に収まらないテキストを切り捨て、省略記号を追加する。
Color
[in] テキストの色を指定する D3DCOLOR 型。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DXERR_INVALIDDATA

注意

DrawText は、#define UNICODE スイッチが含まれているかどうかに応じて、DrawTextW または ID3DXFont::DrawTextA のどちらかをマップする。#define UNICODE スイッチを挿入または除外して、アプリケーションで Unicode または ANSI 文字列のどちらを使用するかを指定する。次のコードは、DrawText の定義方法を示している。

#ifndef DrawText
#ifdef UNICODE
#define DrawText DrawTextW
#else
#define DrawText DrawTextA
#endif
#endif

DrawTextW メソッドは、デバイス コンテキストで選択されたフォント、テキスト カラー、バックグラウンド カラーを使用してテキストを描画する。DT_NOCLIP フォーマットが使用される場合を除き、DrawTextW は指定された四角形の外側にテキストがはみ出ないようテキストをクリップする。DT_SINGLELINE フォーマットが指定されている場合を除き、整形処理では複数行が対象であると見なされる。

選択したフォントが大きすぎて四角形に収まらない場合、DrawTextW メソッドは小さいフォントで置き換える処理を行わない。

DrawTextW メソッドは、escapement と orientation の両方がゼロのフォントのみサポートする。

動作環境

ヘッダー : D3dx8core.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXFont::DrawTextA


ID3DXFont::End

ID3DXFont::Begin が呼び出された時点のデバイスの状態を復元する。

HRESULT End();

パラメータ

なし。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

動作環境

ヘッダー : D3dx8core.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXFont::Begin


ID3DXFont::GetDevice

フォント オブジェクトに関連付けられている Microsoft® Direct3D® デバイスを取得する。

HRESULT GetDevice(
  LPDIRECT3DDEVICE8* ppDevice
);

パラメータ

ppDevice
[out, retval] フォント オブジェクトに関連付けられている Direct3D デバイス オブジェクトを表す、IDirect3DDevice8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、D3D_OK を返す。

パラメータが無効な場合は、D3DERR_INVALIDCALL を返す。

注 このメソッドを呼び出すと、IDirect3DDevice8 インターフェイスの内部参照カウントが増加する。この IDirect3DDevice8 インターフェイスの処理が終了したら、必ず IUnknown::Release を呼び出す必要がある。そうしないと、メモリ リークが発生する。

動作環境

ヘッダー : D3dx8core.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXFont::GetLogFont

フォントの属性を取得する。

HRESULT GetLogFont(
  LOGFONT* pLogFont
);

パラメータ

pLogFont
[in, out] フォントの属性を記述する、返された LOGFONT 構造体へのポインタ。

戻り値

成功した場合は、D3D_OK を返す。

パラメータが無効な場合は、D3DERR_INVALIDCALL を返す。

注意

LOGFONT 構造体の詳細については、Microsoft® Platform Software Development Kit (SDK) を参照すること。

動作環境

ヘッダー : D3dx8core.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXMatrixStack

アプリケーションは、行列スタックを使用するとき、ID3DXMatrixStack インターフェイスのメソッドを使用する。

ID3DXMatrixStack インターフェイスは、D3DXCreateMatrixStack 関数を呼び出して取得する。

ID3DXMatrixStack インターフェイスのメソッドは、以下のグループにまとめることができる。

行列操作 | MultMatrix
 | MultMatrixLocal
その他 | GetTop
 | LoadIdentity
 | LoadMatrix
 | Pop
 | Push
回転 | RotateAxis
 | RotateAxisLocal
 | RotateYawPitchRoll
 | RotateYawPitchRollLocal
スケーリング | Scale
 | ScaleLocal
平行移動 | Translate
 | TranslateLocal

ID3DXMatrixStack インターフェイスは、すべての COM インターフェイスと同じように、IUnknown インターフェイスのメソッドを継承している。IUnknown インターフェイスでは、次の 3 つのメソッドがサポートされている。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXMatrixStack::GetTop

スタックの一番上にある現在の行列を取得する。

D3DXMATRIX* GetTop();

パラメータ

なし。

戻り値

現在の行列を表す D3DXMATRIX 構造体へのポインタを返す。

注意

このメソッドにより返される D3DXMATRIX ポインタは、それ以降のスタック操作でも有効であるとは保証されていない。

このメソッドは、スタックの一番上から現在の行列を削除しないで、ただ返すだけである。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXMatrixStack::Pop、ID3DXMatrixStack::Push


ID3DXMatrixStack::LoadIdentity

現在の行列に単位行列をロードする。

HRESULT LoadIdentity();

パラメータ

なし。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

単位行列は、[1,1][2,2][3,3][4,4] 係数に 1.0 が設定されていることを除いて、すべての係数が 0.0 の行列である。単位行列は、頂点に適用されてもそれらが変更されないという点で特別である。単位行列は、頂点値を変更して回転、平行移動、および 4 × 4 行列で表現できるその他の変換を行う行列の起点として使用される。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXMatrixStack::LoadMatrix


ID3DXMatrixStack::LoadMatrix

指定された行列を現在の行列にロードする。

HRESULT LoadMatrix(
  CONST D3DXMATRIX* pMat
);

パラメータ

pMat
[in] 現在の行列にロードされる D3DXMATRIX 構造体へのポインタ。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

このメソッドは、スタックに項目を追加するのではなく、現在の行列を指定された行列に置き換える。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXMatrixStack::LoadIdentity


ID3DXMatrixStack::MultMatrix

現在の行列と指定された行列との積を算出する。

HRESULT MultMatrix(
  CONST D3DXMATRIX* pMat
);

パラメータ

pMat
[in] 現在の行列に積算する D3DXMATRIX 構造体へのポインタ。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

このメソッドは、現在の行列に指定された行列を積算する (変換は現在のワールド原点を中心として行われる)。

    m_stack[m_currentPos] = m_stack[m_currentPos] * *pMat;

このメソッドは、スタックに項目を追加するのではなく、現在の行列を、現在の行列と指定された行列の積算に置き換える。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXMatrixStack::MultMatrixLocal


ID3DXMatrixStack::MultMatrixLocal

指定された行列と現在の行列との積を算出する。

HRESULT MultMatrixLocal(
  CONST D3DXMATRIX* pMat
);

パラメータ

pMat
[in] 現在の行列に積算する D3DXMATRIX 構造体へのポインタ。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

このメソッドは、指定された行列に現在の行列を積算する (変換はオブジェクトのローカル原点を中心として行われる)。

    m_stack[m_currentPos] = *pMat * m_stack[m_currentPos];

このメソッドは、スタックに項目を追加するのではなく、現在の行列を、指定された行列と現在の行列の積算に置き換える。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXMatrixStack::MultMatrix


ID3DXMatrixStack::Pop

スタックの一番上から現在の行列を削除する。

HRESULT Pop();

パラメータ

なし。

戻り値

成功した場合は、D3D_OK を返す。

注意

このメソッドは、スタックの一番上から現在の行列を削除して、行列をスタックの一番上に進めて、スタックの項目カウントを 1 だけ減らす。スタックの現在の項目カウントが 0 の場合、このメソッドは何も処理を行わずに戻る。スタックの現在の項目カウントが 1 の場合、このメソッドはスタックを空にする。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXMatrixStack::GetTop、ID3DXMatrixStack::Push


ID3DXMatrixStack::Push

行列をスタックに追加する。

HRESULT Push();

パラメータ

なし。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

このメソッドは、現在の行列を複写して、スタックの項目カウントを 1 だけ増やす。項目がもっと追加されると、スタックは動的に拡大される。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXMatrixStack::GetTop、ID3DXMatrixStack::Pop


ID3DXMatrixStack::RotateAxis

現在の行列と、算出された回転行列との積を算出する。

HRESULT RotateAxis(
  CONST D3DXVECTOR3* pV,
  FLOAT Angle
);

パラメータ

pV
[in] 軸の角度を指定する D3DXVECTOR3 構造体へのポインタ。
Angle
[in] 回転の角度 (ラジアン単位)。角度は、回転軸から原点に向かって時計回りに計測される。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

このメソッドは、現在の行列に算出された回転行列を積算する。 これは、指定した軸に対して反時計回りに指定した角度だけ回転させる (回転は、現在のワールド原点を中心として行われる)。

    D3DXMATRIX tmp;

    D3DXMatrixRotationAxis( &tmp, pV, angle );
    m_stack[m_currentPos] = m_stack[m_currentPos] * tmp;

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXMatrixStack::RotateAxisLocal、ID3DXMatrixStack::RotateYawPitchRoll、ID3DXMatrixStack::RotateYawPitchRollLocal


ID3DXMatrixStack::RotateAxisLocal

算出された回転行列と、現在の行列との積を算出する。

HRESULT RotateAxisLocal(
  CONST D3DXVECTOR3* pV,
  FLOAT Angle
);

パラメータ

pV
[in] 軸の角度を指定する D3DXVECTOR3 構造体へのポインタ。
Angle
[in] 回転の角度 (ラジアン単位)。角度は、回転軸から原点に向かって時計回りに計測される。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

このメソッドは、算出された回転行列に現在の行列を積算する。 これは、指定した軸に対して反時計回りに指定した角度だけ回転させる (回転は、オブジェクトのローカル原点を中心として行われる)。

    D3DXMATRIX tmp;

    D3DXMatrixRotationAxis( &tmp, pV, angle );
    m_stack[m_currentPos] = tmp * m_stack[m_currentPos];

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXMatrixStack::RotateAxis、ID3DXMatrixStack::RotateYawPitchRoll、ID3DXMatrixStack::RotateYawPitchRollLocal


ID3DXMatrixStack::RotateYawPitchRoll

現在の行列と算出された回転行列 (指定されたヨー、ピッチ、およびロールにより構成される) の積を算出する。

HRESULT RotateYawPitchRoll(
  FLOAT Yaw,
  FLOAT Pitch,
  FLOAT Roll
);

パラメータ

Yaw
[in] y 軸のヨー (ラジアン単位)。
Pitch
[in] x 軸のピッチ (ラジアン単位)。
Roll
[in] z 軸のロール (ラジアン単位)。

戻り値

成功した場合は、D3D_OK を返す。

注意

このメソッドは、現在の行列に算出された回転行列を積算する。すべての角度は反時計回りであり、回転は現在のワールド原点を中心として行われる。

    D3DXMATRIX tmp;

    D3DXMatrixRotationYawPitchRoll( &tmp, yaw, pitch, roll );
    m_stack[m_currentPos] = m_stack[m_currentPos] * tmp;

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXMatrixStack::RotateAxis、ID3DXMatrixStack::RotateAxisLocal、ID3DXMatrixStack::RotateYawPitchRollLocal


ID3DXMatrixStack::RotateYawPitchRollLocal

算出された回転行列 (指定されたヨー、ピッチ、およびロールにより構成される) と現在の行列との積を算出する。

HRESULT RotateYawPitchRollLocal(
  FLOAT Yaw,
  FLOAT Pitch,
  FLOAT Roll
);

パラメータ

Yaw
[in] y 軸のヨー (ラジアン単位)。
Pitch
[in] x 軸のピッチ (ラジアン単位)。
Roll
[in] z 軸のロール (ラジアン単位)。

戻り値

成功した場合は、D3D_OK を返す。

注意

このメソッドは、算出された回転行列に現在の行列を積算する。すべての角度は反時計回りであり、回転はオブジェクトのローカル原点を中心として行われる。

    D3DXMATRIX tmp;

    D3DXMatrixRotationYawPitchRoll( &tmp, yaw, pitch, roll );
    m_stack[m_currentPos] = tmp * m_stack[m_currentPos];

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXMatrixStack::RotateAxis、ID3DXMatrixStack::RotateAxisLocal、ID3DXMatrixStack::RotateYawPitchRoll


ID3DXMatrixStack::Scale

現在の行列と算出されたスケール行列 (指定されたポイント (x、y、z) から構成される) の積を算出する。

HRESULT Scale(
  FLOAT x,
  FLOAT y,
  FLOAT z
);

パラメータ

x
[in] x 方向のスケーリング コンポーネント。
y
[in] y 方向のスケーリング コンポーネント。
z
[in] z 方向のスケーリング コンポーネント。

戻り値

成功した場合は、D3D_OK を返す。

注意

このメソッドは、現在の行列に算出されたスケール行列を積算する (変換は現在のワールド原点を中心として行われる)。

    D3DXMATRIX tmp;

    D3DXMatrixScaling( &tmp, x, y, z );
    m_stack[m_currentPos] = m_stack[m_currentPos] * tmp;

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXMatrixStack::ScaleLocal


ID3DXMatrixStack::ScaleLocal

算出されたスケール行列 (指定されたポイント (x、y、z) から構成される) と現在の行列の積を算出する。

HRESULT Scale(
  FLOAT x,
  FLOAT y,
  FLOAT z
);

パラメータ

x
[in] x 方向のスケーリング コンポーネント。
y
[in] y 方向のスケーリング コンポーネント。
z
[in] z 方向のスケーリング コンポーネント。

戻り値

成功した場合は、D3D_OK を返す。

注意

このメソッドは、算出されたスケール行列に現在の行列を積算する (変換はオブジェクトのローカル原点を中心として行われる)。

    D3DXMATRIX tmp;

    D3DXMatrixScaling( &tmp, x, y, z );
    m_stack[m_currentPos] = tmp * m_stack[m_currentPos];

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXMatrixStack::Scale


ID3DXMatrixStack::Translate

現在の行列と算出された平行移動行列 (指定された係数 (x、y、z) により決定される) の積を算出する。

HRESULT Translate(
  FLOAT x,
  FLOAT y,
  FLOAT z
);

パラメータ

x
[in] x 方向の平行移動係数。
y
[in] y 方向の平行移動係数。
z
[in] z 方向の平行移動係数。

戻り値

成功した場合は、D3D_OK を返す。

注意

このメソッドは、現在の行列に算出された平行移動行列を積算する (変換は、現在のワールド原点を中心として行われる)。

    D3DXMATRIX tmp;

    D3DXMatrixTranslation( &tmp, x, y, z );
    m_stack[m_currentPos] = m_stack[m_currentPos] * tmp;

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXMatrixStack::TranslateLocal


ID3DXMatrixStack::TranslateLocal

算出された平行移動行列 (指定された係数 (x、y、z) により決定される) と現在の行列の積を算出する。

HRESULT TranslateLocal(
  FLOAT x,
  FLOAT y,
  FLOAT z
);

パラメータ

x
[in] x 方向の平行移動係数。
y
[in] y 方向の平行移動係数。
z
[in] z 方向の平行移動係数。

戻り値

成功した場合は、D3D_OK を返す。

注意

このメソッドは、算出された平行移動行列に現在の行列を積算する (変換は、オブジェクトのローカル原点を中心として行われる)。

    D3DXMATRIX tmp;

    D3DXMatrixTranslation( &tmp, x, y, z );
    m_stack[m_currentPos] = tmp * m_stack[m_currentPos];

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXMatrixStack::Translate


ID3DXMesh

アプリケーションは、ID3DXMesh インターフェイスのメソッドを使用してメッシュ オブジェクトを操作する。

ID3DXMesh インターフェイスは、D3DXCreateMesh 関数または D3DXCreateMeshFVF 関数のどちらかを呼び出して取得する。

ID3DXMesh インターフェイスは、次に示す ID3DXBaseMesh メソッドを継承する。メソッドは以下のグループにまとめることができる。

バッファ | GetIndexBuffer
 | GetVertexBuffer
 | LockIndexBuffer
 | LockVertexBuffer
 | UnlockIndexBuffer
 | UnlockVertexBuffer
コピー | CloneMesh
 | CloneMeshFVF
面 | GetNumFaces
情報 | GetDevice
 | GetOptions
レンダリング | DrawSubset
 | GetAttributeTable
頂点 | GetFVF
 | GetNumVertices

ID3DXMesh インターフェイスのメソッドは、以下のグループにまとめることができる。

ロック | LockAttributeBuffer
 | UnlockAttributeBuffer
その他 | ConvertAdjacencyToPointReps
 | ConvertPointRepsToAdjacency
 | GenerateAdjacency
最適化 | Optimize
 | OptimizeInplace

ID3DXMesh インターフェイスは、すべての COM インターフェイスと同じように、IUnknown インターフェイスのメソッドを継承している。IUnknown インターフェイスでは、次の 3 つのメソッドがサポートされている。

IUnknown | AddRef
 | QueryInterface
 | Release

LPD3DXMESH 型は、ID3DXMesh インターフェイスへのポインタとして定義されている。

typedef struct ID3DXMesh *LPD3DXMESH;

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

メッシュ関数


ID3DXMesh::ConvertAdjacencyToPointReps

メッシュのポイント表現を生成する。

HRESULT ConvertAdjacencyToPointReps(
  CONST DWORD* pAdjacency,
  DWORD* PointRep
);

パラメータ

pAdjacency
[in] メッシュの面隣接性配列へのポインタ。面隣接性は、配列の配列として格納される。最も内側の配列は、隣接する三角形の 3 つのインデックスで、外側の配列は、メッシュ内の三角形ごとの面隣接性の 1 セットである。
PointRep
[in, out] メッシュのポイント表現に使用する転送先バッファへのポインタ。ポイント表現は、頂点ごとに 1 つの要素を伴うインデックスの配列として格納される。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_INVALIDMESH
E_OUTOFMEMORY

注意

ポイント表現は、異なる放線座標、u 座標と v 座標、カラー データなどを使用するのではなく、同じ x 座標、y 座標、z 座標で 2 つの頂点を融合することにより、メッシュの隣接性を記述する方法である。完全になめらかな (しわ、境界、または穴がない) メッシュでは、ポイント表現は冗長である。その場合、ハッシュ テーブルを使用して頂点インデックスを共有するエッジを検索することによって、隣接する三角形を計算することができる。しわおよびテクスチャ境界の場合は、メッシュ内の頂点を構成するともに配置されている頂点グループのハッシュ テーブルで使用する一意の頂点インデックスを指定するために、ポイント表現が必要となる。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXMesh::ConvertPointRepsToAdjacency


ID3DXMesh::ConvertPointRepsToAdjacency

Microsoft® DirectX® (.x) ファイルに格納されているポイント表現データを面隣接性情報に変換する。面隣接性情報は、最適化および単純化の操作においてより優れた柔軟性をもたらす。

HRESULT ConvertPointRepsToAdjacency(
  CONST DWORD* pPRep,
  DWORD* pAdjacency
);

パラメータ

pPRep
[in] メッシュを表すポイント表現へのポインタ。ポイント表現は、頂点ごとに 1 つの要素を伴うインデックスの配列として格納される。
pAdjacency
[in, out] メッシュの面隣接性配列に使用する転送先バッファへのポインタ。面隣接性は、配列の配列として格納される。最も内側の配列は、隣接する三角形の 3 つのインデックスで、外側の配列は、メッシュ内の三角形ごとの面隣接性の 1 セットである。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

注意

ポイント表現は、異なる放線座標、u 座標と v 座標、カラー データなどを使用するのではなく、同じ x 座標、y 座標、z 座標で 2 つの頂点を融合することにより、メッシュの隣接性を記述する方法である。完全になめらかな (しわ、境界、または穴がない) メッシュでは、ポイント表現は冗長である。その場合、ハッシュ テーブルを使用して頂点インデックスを共有するエッジを検索することによって、隣接する三角形を計算することができる。しわおよびテクスチャ境界の場合は、メッシュ内の頂点を構成するともに配置されている頂点グループのハッシュ テーブルで使用する一意の頂点インデックスを指定するために、ポイント表現が必要となる。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXMesh::ConvertAdjacencyToPointReps


ID3DXMesh::GenerateAdjacency

Epsilon 値を使用して面隣接性情報を生成する。面隣接性情報は、最適化および単純化の操作においてより優れた柔軟性をもたらす。

HRESULT GenerateAdjacency(
  FLOAT Epsilon,
  DWORD* pAdjacency
);

パラメータ

Epsilon
[in] 頂点を結合する間隔を示す距離。このパラメータは現在無視され、0.0 の Epsilon が使用される。
pAdjacency
[in, out] メッシュの面隣接性配列に使用する転送先バッファへのポインタ。面隣接性は、配列の配列として格納される。最も内側の配列は、隣接する三角形の 3 つのインデックスで、外側の配列は、メッシュ内の三角形ごとの面隣接性の 1 セットである。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

注意

このメソッドは、頂点を論理的に結合するだけで、メッシュに対する変更は行わない。メッシュを変更する場合は、このメソッドの後、D3DXWeldVertices を呼び出す必要がある。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXMesh::LockAttributeBuffer

属性バッファをロックし、属性バッファ メモリへのポインタを取得する。

HRESULT LockAttributeBuffer(
  DWORD Flags,
  DWORD** ppData
);

パラメータ

Flags
[in] 属性バッファ メモリをどのようにロックするかを表す、1 つ以上のロッキング フラグの組み合わせ。
D3DLOCK_DISCARD
アプリケーションは、ロックされている領域内のすべての場所を、書き込み専用処理で上書きする。これにより、非ネイティブ フォーマットで格納されているリソースは圧縮解除ステップを省略できる。
D3DLOCK_NOOVERWRITE
フレームの開始以降、またはこのフラグを持たない最新のロック以降、描画呼び出しの中で参照される情報のうち、ロック時に修正される情報がないことを表す。頂点バッファへのデータの追加だけを行う場合は、このフラグにより処理を最適化できる。
D3DLOCK_NOSYSLOCK
ビデオ メモリ ロックのデフォルトの動作は、システム全体のクリティカル セクションを確保し、ロックの期間中はディスプレイ モードが変化しないことを保証するというものである。このフラグを指定すると、システム全体のクリティカル セクションはロックの間保持されない。

ロック処理は若干負荷が高くなるが、システムは、マウス カーソルの移動といったほかの動作を実行できる。このフラグは、それを行わないとシステムの応答に悪影響を及ぼすソフトウェア レンダリングに対するバック バッファのロックのような、長期間のロックに役立つ。

D3DLOCK_READONLY
アプリケーションはバッファに書き込まない。これにより、非ネイティブ フォーマットで格納されているリソースは、アンロック時に再圧縮ステップを省略できる。
ppData
[out, retval] DWORD 値の配列へのポインタのアドレス。戻り値の属性バッファ データが入力される。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXMesh::UnlockAttributeBuffer、D3DXATTRIBUTERANGE


ID3DXMesh::Optimize

メッシュの面および頂点の順番変更を制御し、パフォーマンスを最適化して、出力メッシュを生成する。

HRESULT Optimize(
  DWORD Flags,
  CONST DWORD* pAdjacencyIn,
  DWORD* pAdjacencyOut,
  DWORD* pFaceRemap,
  LPD3DXBUFFER* ppVertexRemap,
  LPD3DXMESH* ppOptMesh
);

パラメータ

Flags
[in] 実行する最適化の種類を指定する、1 つ以上のフラグの組み合わせ。次のフラグが定義されている。
D3DXMESHOPT_ATTRSORT
属性バンドル ステートの変更を少なくし、ID3DXBaseMesh::DrawSubset のパフォーマンスを強化するため、面の順番を変更して最適化を行う。
D3DXMESHOPT_COMPACT
面の順番を変更し、使用されていない頂点と綿を削除する。
D3DXMESHOPT_IGNOREVERTS
面のみを最適化し、頂点は最適化しない。
D3DXMESHOPT_SHAREVB
頂点バッファを共有する。
D3DXMESHOPT_STRIPREORDER
面の順番を変更し、隣接する三角形の長さを最大にする。
D3DXMESHOPT_VERTEXCACHE
面の順番を変更し、頂点キャッシュのキャッシュ ヒット率を向上させる。

最適化フラグの D3DXMESHOPT_STRIPREORDER および D3DXMESHOPT_VERTEXCACHE はそれぞれ相互に排他的である。

pAdjacencyIn
[in, out] ソース メッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの DWORD の配列へのポインタ。
pAdjacencyOut
[in, out] 最適化されたメッシュの面隣接性配列に使用する転送先バッファへのポインタ。面隣接性は、配列の配列として格納される。最も内側の配列は、隣接する三角形の 3 つのインデックスで、外側の配列は、メッシュ内の三角形ごとの面隣接性の 1 セットである。
pFaceRemap
[in, out] 各面の新しいインデックスを格納している転送先バッファへのポインタ。
ppVertexRemap
[out] 各頂点の新しいインデックスを格納する、ID3DXBuffer インターフェイスへのポインタのアドレス。
ppOptMesh
[out] 最適化されたメッシュを表す、ID3DXMesh インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

注意

このメソッドは、メッシュの新しいコピーの生成中に最適化を実行できる点を除いて、ID3DXBaseMesh::CloneMesh メソッドとほぼ同様である。

出力メッシュは、入力メッシュのすべての作成パラメータを継承する。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXMesh::OptimizeInplace

メッシュの面および頂点の順番変更を制御し、パフォーマンスを最適化する。

HRESULT OptimizeInplace(
  DWORD Flags,
  CONST DWORD* pAdjacencyIn,
  DWORD* pAdjacencyOut,
  DWORD* pFaceRemap,
  LPD3DXBUFFER* ppVertexRemap
);

パラメータ

Flags
[in] 実行する最適化の種類を指定する、1 つ以上のフラグの組み合わせ。次のフラグが定義されている。
D3DXMESHOPT_ATTRSORT
属性バンドル ステートの変更を少なくし、ID3DXBaseMesh::DrawSubset のパフォーマンスを強化するため、面の順番を変更して最適化を行う。
D3DXMESHOPT_COMPACT
面の順番を変更し、使用されていない頂点と綿を削除する。
D3DXMESHOPT_IGNOREVERTS
面のみを最適化し、頂点は最適化しない。
D3DXMESHOPT_STRIPREORDER
面の順番を変更し、隣接する三角形の長さを最大にする。
D3DXMESHOPT_VERTEXCACHE
面の順番を変更し、頂点キャッシュのキャッシュ ヒット率を向上させる。

最適化フラグの D3DXMESHOPT_STRIPREORDER および D3DXMESHOPT_VERTEXCACHE はそれぞれ相互に排他的である。

pAdjacencyIn
[in] ソース メッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの DWORD の配列へのポインタ。
pAdjacencyOut
[out] 最適化されたメッシュの面隣接性配列に使用する転送先バッファへのポインタ。面隣接性は、配列の配列として格納される。最も内側の配列は、隣接する三角形の 3 つのインデックスで、外側の配列は、メッシュ内の三角形ごとの面隣接性の 1 セットである。
pFaceRemap
[out] 各面の新しいインデックスを格納している転送先バッファへのポインタ。
ppVertexRemap
[out] 各頂点の新しいインデックスを格納する、ID3DXBuffer インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_CANNOTATTRSORT
E_OUTOFMEMORY

注 このメソッドは、メッシュが頂点バッファをほかのメッシュと共有している場合、失敗する。ただし、Flags パラメータに D3DXMESHOPT_IGNOREVERTS フラグが設定されている場合を除く。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXMesh::UnlockAttributeBuffer

属性バッファのロックを解除する。

HRESULT UnlockAttributeBuffer();

パラメータ

なし。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXMesh::LockAttributeBuffer


ID3DXPMesh

アプリケーションは、ID3DXPMesh インターフェイスのメソッドを使用してプログレッシブ メッシュ オブジェクトを操作する。プログレッシブ メッシュにより、メッシュ オブジェクトのプログレッシブ リファインが可能となる。

ID3DXPMesh インターフェイスは、D3DXGeneratePMesh 関数を呼び出して取得する。

ID3DXPMesh インターフェイスは、次に示す ID3DXBaseMesh メソッドを継承する。メソッドは以下のグループにまとめることができる。

バッファ | GetIndexBuffer
 | GetVertexBuffer
 | LockIndexBuffer
 | LockVertexBuffer
 | UnlockIndexBuffer
 | UnlockVertexBuffer
コピー | CloneMesh
 | CloneMeshFVF
面 | GetNumFaces
情報 | GetDevice
 | GetOptions
レンダリング | DrawSubset
 | GetAttributeTable
頂点 | GetFVF
 | GetNumVertices

ID3DXPMesh インターフェイスのメソッドは、以下のグループにまとめることができる。

コピー | ClonePMesh
 | ClonePMeshFVF
面 | GetMaxFaces
 | GetMinFaces
 | SetNumFaces
その他 | GetAdjacency
 | Save
最適化 | Optimize
頂点 | GetMaxVertices
 | GetMinVertices
 | SetNumVertices

ID3DXPMesh インターフェイスは、すべての COM インターフェイスと同じように、IUnknown インターフェイスのメソッドを継承している。IUnknown インターフェイスでは、次の 3 つのメソッドがサポートされている。

IUnknown | AddRef
 | QueryInterface
 | Release

LPD3DXPMESH 型は、ID3DXPMesh インターフェイスへのポインタとして定義されている。

typedef struct ID3DXPMesh *LPD3DXPMESH;

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

メッシュ関数


ID3DXPMesh::ClonePMesh

宣言子を使用してプログレッシブ メッシュのコピーを作成する。

HRESULT ClonePMesh(
  DWORD Options,
  CONST DWORD* pDeclaration,
  LPDIRECT3DDEVICE8 pDevice,
  LPD3DXPMESH* ppCloneMesh
);

パラメータ

Options
[in] メッシュの作成オプションを指定する 1 つ以上のフラグの組み合わせ。次のフラグが定義されている。
D3DXMESH_32BIT
メッシュに、16 ビットではなく 32 ビットのインデックスを作成する。32 ビットのメッシュは、最大 2^32-1 の面と頂点を含むことができる。このフラグはサポートされていないため、使用すべきではない。
D3DXMESH_DONOTCLIP
頂点バッファおよびインデックス バッファに D3DUSAGE_DONOTCLIP 利用フラグを使用する。
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC と D3DXMESH_IB_DYNAMIC の両方を指定したことになる。
D3DXMESH_RTPATCHES
頂点バッファおよびインデックス バッファに D3DUSAGE_RTPATCHES 利用フラグを使用する。
D3DXMESH_NPATCHES
このフラグを指定すると、メッシュの頂点バッファおよびインデックス バッファが D3DUSAGE_NPATCHES フラグを使用して作成されることになる。これは、Microsoft® Direct3D® の N パッチ拡張機能を使用してメッシュ オブジェクトをレンダリングする場合に必要となる。
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED と D3DXMESH_IB_MANAGED の両方を指定したことになる。
D3DXMESH_POINTS
頂点バッファおよびインデックス バッファに D3DUSAGE_POINTS 利用フラグを使用する。
D3DXMESH_IB_DYNAMIC
インデックス バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_IB_MANAGED
インデックス バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_IB_SYSTEMMEM
インデックス バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_IB_WRITEONLY
インデックス バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM と D3DXMESH_IB_SYSTEMMEM の両方を指定したことになる。
D3DXMESH_VB_DYNAMIC
頂点バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_VB_MANAGED
頂点バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_VB_SHARE
コピーしたメッシュに頂点バッファを共有させる。これらのメッシュは、共有する頂点バッファにインデックス付けする個別のインデックス バッファを備える。
D3DXMESH_VB_SYSTEMMEM
頂点バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_VB_WRITEONLY
頂点バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY と D3DXMESH_IB_WRITEONLY の両方を指定したことになる。
pDeclaration
[in] 出力メッシュに含まれる頂点の頂点フォーマットを記述する宣言を表す、DWORD 値の配列へのポインタ。このパラメータは FVF に直接マップしなければならない。
pDevice
[in] メッシュに関連付けられているデバイス オブジェクトを表す IDirect3DDevice8 インターフェイスへのポインタ。
ppCloneMesh
[out, retval] コピーされたプログレッシブ メッシュを表す ID3DXPMesh インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXBaseMesh::GetDeclaration、D3DXDeclaratorFromFVF


ID3DXPMesh::ClonePMeshFVF

柔軟な頂点フォーマット (FVF) コードを使用して、プログレッシブ メッシュのコピーを作成する。

HRESULT ClonePMeshFVF(
  DWORD Options,
  DWORD FVF,
  LPDIRECT3DDEVICE8 pDevice,
  LPD3DXPMESH* ppCloneMesh
);

パラメータ

Options
[in] メッシュの作成オプションを指定する 1 つ以上のフラグの組み合わせ。次のフラグが定義されている。
D3DXMESH_32BIT
メッシュに、16 ビットではなく 32 ビットのインデックスを作成する。32 ビットのメッシュは、最大 2^32-1 の面と頂点を含むことができる。このフラグはサポートされていないため、使用すべきではない。
D3DXMESH_DONOTCLIP
頂点バッファおよびインデックス バッファに D3DUSAGE_DONOTCLIP 利用フラグを使用する。
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC と D3DXMESH_IB_DYNAMIC の両方を指定したことになる。
D3DXMESH_RTPATCHES
頂点バッファおよびインデックス バッファに D3DUSAGE_RTPATCHES 利用フラグを使用する。
D3DXMESH_NPATCHES
このフラグを指定すると、メッシュの頂点バッファおよびインデックス バッファが D3DUSAGE_NPATCHES フラグを使用して作成されることになる。これは、Microsoft® Direct3D® の N パッチ拡張機能を使用してメッシュ オブジェクトをレンダリングする場合に必要となる。
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED と D3DXMESH_IB_MANAGED の両方を指定したことになる。
D3DXMESH_POINTS
頂点バッファおよびインデックス バッファに D3DUSAGE_POINTS 利用フラグを使用する。
D3DXMESH_IB_DYNAMIC
インデックス バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_IB_MANAGED
インデックス バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_IB_SYSTEMMEM
インデックス バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_IB_WRITEONLY
インデックス バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM と D3DXMESH_IB_SYSTEMMEM の両方を指定したことになる。
D3DXMESH_VB_DYNAMIC
頂点バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_VB_MANAGED
頂点バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_VB_SHARE
コピーしたメッシュに頂点バッファを共有させる。これらのメッシュは、共有する頂点バッファにインデックス付けする個別のインデックス バッファを備える。
D3DXMESH_VB_SYSTEMMEM
頂点バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_VB_WRITEONLY
頂点バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY と D3DXMESH_IB_WRITEONLY の両方を指定したことになる。
FVF
[in] 出力メッシュに含まれる頂点の頂点フォーマットを指定する柔軟な頂点フォーマット フラグの組み合わせ。
pDevice
[in] メッシュに関連付けられているデバイス オブジェクトを表す IDirect3DDevice8 インターフェイスへのポインタ。
ppCloneMesh
[out, retval] コピーされたプログレッシブ メッシュを表す ID3DXPMesh インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

注意

ClonePMeshFVF を使用して、プログレッシブ メッシュを 1 つの FVF から別の FVF に変換できる。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXBaseMesh::GetFVF、D3DXFVFFromDeclarator


ID3DXPMesh::GetAdjacency

メッシュの面隣接性配列を返す。

HRESULT GetAdjacency(
  DWORD* pAdjacency
);

パラメータ

pAdjacency
[in] 返されたメッシュの面隣接性配列へのポインタ。面隣接性は、配列の配列として格納される。最も内側の配列は、隣接する三角形の 3 つのインデックスで、外側の配列は、メッシュ内の三角形ごとの面隣接性の 1 セットである。隣接性配列のサイズは、面の数の最大値に 3 を乗算したものである。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXPMesh::GetMaxFaces


ID3DXPMesh::GetMaxFaces

プログレッシブ メッシュがサポートする面の数の最大値を取得する。

DWORD GetMaxFaces();

パラメータ

なし。

戻り値

プログレッシブ メッシュがサポートする面の数の最大値を返す。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXPMesh::GetMaxVertices

プログレッシブ メッシュがサポートする頂点の数の最大値を取得する。

DWORD GetMaxVertices();

パラメータ

なし。

戻り値

プログレッシブ メッシュがサポートする頂点の数の最大値を返す。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXPMesh::GetMinFaces

プログレッシブ メッシュがサポートする面の数の最小値を取得する。

DWORD GetMinFaces();

パラメータ

なし。

戻り値

プログレッシブ メッシュがサポートする面の数の最小値を返す。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXPMesh::GetMinVertices

プログレッシブ メッシュがサポートする頂点の数の最小値を取得する。

DWORD GetMinVertices();

パラメータ

なし。

戻り値

プログレッシブ メッシュがサポートする頂点の数の最小値を返す。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXPMesh::Optimize

メッシュの面および頂点の順番変更を制御し、パフォーマンスを最適化して、出力メッシュを生成する。

HRESULT Optimize(
  DWORD Flags,
  DWORD* pAdjacencyOut,
  DWORD* pFaceRemap,
  LPD3DXBUFFER* ppVertexRemap,
  LPD3DXMESH* ppOptMesh
);

パラメータ

Flags
[in] 実行する最適化の種類を指定する、1 つ以上のフラグの組み合わせ。次のフラグが定義されている。
D3DXMESHOPT_ATTRSORT
属性バンドル ステートの変更を少なくし、ID3DXBaseMesh::DrawSubset のパフォーマンスを強化するため、面の順番を変更して最適化を行う。
D3DXMESHOPT_COMPACT
面の順番を変更し、使用されていない頂点と綿を削除する。
D3DXMESHOPT_IGNOREVERTS
面のみを最適化し、頂点は最適化しない。
D3DXMESHOPT_SHAREVB
頂点バッファを共有する。
D3DXMESHOPT_STRIPREORDER
面の順番を変更し、隣接する三角形の長さを最大にする。
D3DXMESHOPT_VERTEXCACHE
面の順番を変更し、頂点キャッシュのキャッシュ ヒット率を向上させる。

最適化フラグの D3DXMESHOPT_STRIPREORDER および D3DXMESHOPT_VERTEXCACHE はそれぞれ相互に排他的である。

pAdjacencyOut
[out] 最適化されたメッシュの面隣接性配列に使用する転送先バッファへのポインタ。面隣接性は、配列の配列として格納される。最も内側の配列は、隣接する三角形の 3 つのインデックスで、外側の配列は、メッシュ内の三角形ごとの面隣接性の 1 セットである。この配列のサイズは、面の数の最大値に 3 を乗算したものである。
pFaceRemap
[out] 各面の新しいインデックスを格納している転送先バッファへのポインタ。
ppVertexRemap
[out] 各頂点の新しいインデックスを格納する、ID3DXBuffer インターフェイスへのポインタのアドレス。
ppOptMesh
[out] 最適化されたメッシュを表す、ID3DXMesh インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXPMesh::Save

指定したストリーム オブジェクトにプログレッシブ メッシュを保存する。

HRESULT Save(
  IStream* pStream,
  LPD3DXMATERIAL pMaterials,
  DWORD NumMaterials
);

パラメータ

pStream
[in] ファイル データの書き込み先となるストリーム オブジェクトを表す、IStream インターフェイスへのポインタ。
pMaterials
[in] ストリーム オブジェクトに保存されるマテリアル情報を格納する、D3DXMATERIAL 構造体の配列へのポインタ。
NumMaterials
[in] pMaterials array 内の D3DXMATERIAL 構造体の数。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

注意

IStream インターフェイスの詳細については、Microsoft® Platform Software Development Kit (SDK) を参照すること。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXPMesh::SetNumFaces

現在の LOD (Level of Detail) を、指定した面の数にできる限り近づけて設定する。

HRESULT SetNumFaces(
  DWORD Faces
);

パラメータ

Faces
[in] 面の数を指定する。この値は LOD (Level of Detail) 変更の希望値を指定する。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

面の数が面の数の最大値より大きい場合、ID3DXPMesh::GetMaxFaces が返す面の数の最大値が上限となる。面の数が面の数の最小値より小さい場合は、ID3DXPMesh::GetMinFaces が返す面の数の最小値が下限となる。

この呼び出しの後の面の数は、1 つ少なくなる場合がある。これは、エッジの折りたたみが発生したり、それによって 1 つまたは 2 つの面が削除される場合があるためである。たとえば、面の数として 4 や 6 の値が設定可能な場合に、中間の 5 を設定しようとした場合、常に結果は 4 となる。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXPMesh::SetNumVertices

現在の LOD (Level of Detail) を、指定した頂点の数にできる限り近づけて設定する。

HRESULT SetNumVertices(
  DWORD Vertices
);

パラメータ

Vertices
[in] 頂点の数を指定する。この値は LOD (Level of Detail) 変更の希望値を指定する。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

頂点の数が頂点の数の最大値より大きい場合、ID3DXPMesh::GetMaxVertices が返す頂点の数の最大値が上限となる。頂点の数が頂点の数の最小値より小さい場合、ID3DXPMesh::GetMinVertices が返す頂点の数の最小値が下限となる。

この呼び出しの後の頂点の数は、1 つ少なくなる場合がある。これは、エッジの折りたたみが発生したり、それによって 1 つまたは 2 つの頂点が削除される場合があるためである。たとえば、頂点の数として 4 や 6 の値が設定可能な場合に、中間の 5 を設定しようとした場合、常に結果は 4 となる。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXRenderToSurface

ID3DXRenderToSurface インターフェイスは、サーフェスへのレンダリングのプロセスを汎用化するために使用する。サーフェスがレンダリング ターゲットではない場合、互換性のあるレンダリング ターゲットが使用され、シーンの終わりで結果がサーフェスにコピーされる。

ID3DXRenderToSurface インターフェイスは、D3DXCreateRenderToSurface 関数を呼び出して取得する。

ID3DXRenderToSurface インターフェイスのメソッドは、以下のグループにまとめることができる。

情報 | GetDesc
 | GetDevice
レンダリング | BeginScene
 | EndScene

ID3DXRenderToSurface インターフェイスは、すべての COM インターフェイスと同じように、IUnknown インターフェイスのメソッドを継承している。IUnknown インターフェイスでは、次の 3 つのメソッドがサポートされている。

IUnknown | AddRef
 | QueryInterface
 | Release

LPD3DXRENDERTOSURFACE 型は、ID3DXRenderToSurface インターフェイスへのポインタとして定義されている。

typedef interface ID3DXRenderToSurface* LPD3DXRENDERTOSURFACE;

動作環境

ヘッダー : D3dx8core.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXRenderToSurface::BeginScene

シーンを開始する。

HRESULT BeginScene(
  LPDIRECT3DSURFACE8 pSurface,
  CONST D3DVIEWPORT8* pViewport
);

パラメータ

pSurface
[in] レンダリング サーフェスを表す IDirect3DSurface8 インターフェイスへのポインタ。
pViewport
[in] シーンのビューポートを記述する D3DVIEWPORT8 構造体へのポインタ。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

動作環境

ヘッダー : D3dx8core.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXRenderToSurface::EndScene


ID3DXRenderToSurface::EndScene

シーンを終了する。

HRESULT EndScene();

パラメータ

なし。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

動作環境

ヘッダー : D3dx8core.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXRenderToSurface::BeginScene


ID3DXRenderToSurface::GetDesc

レンダリング サーフェスのパラメータを取得する。

HRESULT GetDesc(
  D3DXRTE_DESC* pParameters
);

パラメータ

pParameters

[out] レンダリング サーフェスのパラメータを記述する D3DXRTS_DESC 構造体へのポインタ。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : D3dx8core.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXRenderToSurface::GetDevice

レンダリング サーフェスに関連付けられている Microsoft® Direct3D® デバイスを取得する。

HRESULT GetDevice(
  LPDIRECT3DDEVICE8* ppDevice
);

パラメータ

ppDevice
[out] レンダリング サーフェスに関連付けられている Direct3D デバイス オブジェクトを表す、IDirect3DDevice8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注 このメソッドを呼び出すと、IDirect3DDevice8 インターフェイスの内部参照カウントが増加する。この IDirect3DDevice8 インターフェイスの処理が終了したら、必ず IUnknown::Release を呼び出す必要がある。そうしないと、メモリ リークが発生する。

動作環境

ヘッダー : D3dx8core.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXSkinMesh

アプリケーションは、ID3DXSkinMesh インターフェイスのメソッドを使用してスキン メッシュ オブジェクトを操作する。

ID3DXSkinMesh インターフェイスは、次に示す関数のいずれかを呼び出して取得する。

  • D3DXCreateSkinMesh
  • D3DXCreateSkinMeshFromMesh
  • D3DXCreateSkinMeshFVF

Microsoft® DirectX® (.x) ファイル データ オブジェクトからスキン メッシュをロードするには、D3DXLoadSkinMeshFromXof 関数を使用する。

スキニングは、メッシュの異なる複数の頂点を複数のトランスフォーム行列によりトランスフォームするテクニックであり、個々の行列で頂点をトランスフォームした結果をブレンドし、最終的なトランスフォームされた頂点を取得する。

このプロセスは一般にスキニングと呼ばれ、ボーンのスケルトンのアニメーションに基づいて、キャラクタのスキンを定義するメッシュを変形させるために使用される。厳密なアニメーションの最も単純なケースでは、キャラクタ メッシュの異なる複数のパーツをスケルトンの一意な 1 個のボーンに関連付け、そのボーンのトランスフォームを使用して頂点をトランスフォームする。

スキニングを説明するうえで役に立つ用語の意味を次に示す。

  • スキン。変形を利用してレンダリングされる三角形メッシュ。役に立つポーズのキャラクタのモデルであることが多い。
  • ボーン。スキンの 1つ以上の頂点に影響を与えるトランスフォーム行列。
  • スケルトン。スキン メッシュに影響を与えるすべてのボーンからなる階層。
  • ポーズ。ボーン トランスフォームのセット。特定のスキン メッシュに影響を与えるすべてのボーンのトランスフォームを完全に定義する。
  • 初期ポーズ。メッシュがスケルトンに関連付けられたポーズ。スケルトンがこのポーズのときは、変形されたメッシュと元の未変形のメッシュは等しい。
  • ボーン空間トランスフォーム。メッシュを特定のボーンのローカル空間にトランスフォームする。
  • ボーン ウェイト。特定の頂点に対するボーンの影響の度合い。ウェイト 1 は、頂点に影響を与えるボーンがそのボーンだけであることを意味し、0 はそのボーンが頂点に影響を与えないことを意味する。すべての頂点について、1 つの頂点に影響を与えるすべてのボーンのウェイトの合計は 1 になる。

スキニングされたキャラクタは、メッシュのセットと、メッシュの頂点に影響を与えるボーンのセットによって定義される。ボーンはトランスフォーム階層として表現される。メッシュごとに、そのメッシュに影響を与えるすべてのボーンに適用する行列があり、その行列によってメッシュがボーンのローカル座標空間にトランスフォームされる。この行列は、メッシュのボーンのボーン空間トランスフォームである。この行列は、オーサリング プロセスでスケルトンをメッシュに関連付けるときに定義される。

ID3DXSkinMesh インターフェイスのメソッドは、以下のグループにまとめることができる。

バッファ | GetIndexBuffer
 | GetVertexBuffer
変換 | ConvertToBlendedMesh
 | ConvertToIndexedBlendedMesh
情報 | GetBoneInfluence
 | GetDevice
 | GetMaxFaceInfluences
 | GetMaxVertexInfluences
 | GetNumBoneInfluences
 | GetNumBones
 | GetOptions
面 | GetNumFaces
ロック | LockAttributeBuffer
 | LockIndexBuffer
 | LockVertexBuffer
 | UnlockAttributeBuffer
 | UnlockIndexBuffer
 | UnlockVertexBuffer
その他 | GenerateSkinnedMesh
 | GetOriginalMesh
 | SetBoneInfluence
 | UpdateSkinnedMesh
頂点 | GetDeclaration
 | GetFVF
 | GetNumVertices

ID3DXSkinMesh インターフェイスは、すべての COM インターフェイスと同じように、IUnknown インターフェイスのメソッドを継承している。IUnknown インターフェイスでは、次の 3 つのメソッドがサポートされている。

IUnknown | AddRef
 | QueryInterface
 | Release

LPD3DXSKINMESH 型は、ID3DXSkinMesh インターフェイスへのポインタとして定義されている。

typedef struct ID3DXSkinMesh* LPD3DXSKINMESH;

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXSkinMesh::ConvertToBlendedMesh

ブレンドされたメッシュを返す。

HRESULT ConvertToBlendedMesh(
  DWORD Options,
  CONST LPDWORD pAdjacencyIn,
  LPDWORD pAdjacencyOut,
  DWORD* pNumBoneCombinations,
  LPD3DXBUFFER* ppBoneCombinationTable,
  LPD3DXMESH* ppMesh
);

パラメータ

Options
[in] メッシュの作成オプションを指定する 1 つ以上のフラグの組み合わせ。次のフラグが定義されている。
D3DXMESH_32BIT
メッシュに、16 ビットではなく 32 ビットのインデックスを作成する。32 ビットのメッシュは、最大 2^32-1 の面と頂点を含むことができる。このフラグはサポートされていないため、使用すべきではない。
D3DXMESH_DONOTCLIP
頂点バッファおよびインデックス バッファに D3DUSAGE_DONOTCLIP 利用フラグを使用する。
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC と D3DXMESH_IB_DYNAMIC の両方を指定したことになる。
D3DXMESH_RTPATCHES
頂点バッファおよびインデックス バッファに D3DUSAGE_RTPATCHES 利用フラグを使用する。
D3DXMESH_NPATCHES
このフラグを指定すると、メッシュの頂点バッファおよびインデックス バッファが D3DUSAGE_NPATCHES フラグを使用して作成されることになる。これは、Microsoft® Direct3D® の N パッチ拡張機能を使用してメッシュ オブジェクトをレンダリングする場合に必要となる。
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED と D3DXMESH_IB_MANAGED の両方を指定したことになる。
D3DXMESH_POINTS
頂点バッファおよびインデックス バッファに D3DUSAGE_POINTS 利用フラグを使用する。
D3DXMESH_IB_MANAGED
インデックス バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_IB_DYNAMIC
インデックス バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_IB_SYSTEMMEM
インデックス バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_IB_WRITEONLY
インデックス バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM と D3DXMESH_IB_SYSTEMMEM の両方を指定したことになる。
D3DXMESH_USEHWONLY
ハードウェア処理のみを使用する。このフラグは、ハードウェア処理デバイスに対してのみ指定する。混合モードのデバイスに対してこのフラグを指定すると、システムはハードウェアのみを使用するか、ハードウェアに処理能力がない場合は、ソフトウェアの能力を使用して概算する。
D3DXMESH_VB_DYNAMIC
頂点バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_VB_MANAGED
頂点バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_VB_SYSTEMMEM
頂点バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_VB_WRITEONLY
頂点バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY と D3DXMESH_IB_WRITEONLY の両方を指定したことになる。
pAdjacencyIn
[in] ソース メッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの DWORD の配列へのポインタ。
pAdjacencyOut
[in, out] 最適化されたメッシュの面隣接性配列に使用する転送先バッファへのポインタ。面隣接性は、配列の配列として格納される。最も内側の配列は、隣接する三角形の 3 つのインデックスで、外側の配列は、メッシュ内の三角形ごとの面隣接性の 1 セットである。
pNumBoneCombinations
[in, out] エントリの数。
ppBoneCombinationTable
[in, out] D3DXBONECOMBINATION 構造体の配列へのポインタのアドレス。構造体のカウントは pNumBoneCombinations である。それぞれのボーン組み合わせ表に、一度に描画できる 4 つのボーンが定義される。
ppMesh
[in, out] ブレンドされたメッシュを表す ID3DXMesh インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、E_OUTOFMEMORY を返す。

注意

このメソッドは、スキン メッシュを受け取り、ブレンドされたメッシュ (ボーンの影響を受けるメッシュ) に変換する。変換には、Microsoft® DirectX® 7.x で利用可能になった Microsoft® Direct3D® 頂点ブレンディング機能を使用する。詳細については、「ジオメトリ ブレンディング」を参照すること。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXSkinMesh::ConvertToIndexedBlendedMesh

インデックス付きのブレンドされたメッシュを返す。

HRESULT ConvertToIndexedBlendedMesh(
  DWORD Options,
  CONST LPDWORD pAdjacencyIn,
  DWORD PaletteSize,
  LPDWORD pAdjacencyOut,
  DWORD* pNumBoneCombinations
  LPD3DXBUFFER* ppBoneCombinationTable
  LPD3DXMESH* ppMesh,
);

パラメータ

Options
[in] メッシュの作成オプションを指定する 1 つ以上のフラグの組み合わせ。次のフラグが定義されている。
D3DXMESH_32BIT
メッシュに、16 ビットではなく 32 ビットのインデックスを作成する。32 ビットのメッシュは、最大 2^32-1 の面と頂点を含むことができる。このフラグはサポートされていないため、使用すべきではない。
D3DXMESH_DONOTCLIP
頂点バッファおよびインデックス バッファに D3DUSAGE_DONOTCLIP 利用フラグを使用する。
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC と D3DXMESH_IB_DYNAMIC の両方を指定したことになる。
D3DXMESH_RTPATCHES
頂点バッファおよびインデックス バッファに D3DUSAGE_RTPATCHES 利用フラグを使用する。
D3DXMESH_NPATCHES
このフラグを指定すると、メッシュの頂点バッファおよびインデックス バッファが D3DUSAGE_NPATCHES フラグを使用して作成されることになる。これは、Microsoft® Direct3D® の N パッチ拡張機能を使用してメッシュ オブジェクトをレンダリングする場合に必要となる。
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED と D3DXMESH_IB_MANAGED の両方を指定したことになる。
D3DXMESH_POINTS
頂点バッファおよびインデックス バッファに D3DUSAGE_POINTS 利用フラグを使用する。
D3DXMESH_IB_DYNAMIC
インデックス バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_IB_MANAGED
インデックス バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_IB_SYSTEMMEM
インデックス バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_IB_WRITEONLY
インデックス バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM と D3DXMESH_IB_SYSTEMMEM の両方を指定したことになる。
D3DXMESH_VB_DYNAMIC
頂点バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_VB_MANAGED
頂点バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_VB_SYSTEMMEM
頂点バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_VB_WRITEONLY
頂点バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY と D3DXMESH_IB_WRITEONLY の両方を指定したことになる。
pAdjacencyIn
[in] ソース メッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの DWORD の配列へのポインタ。
PaletteSize
[in] パレット サイズ。
pAdjacencyOut
[in, out] 最適化されたメッシュの面隣接性配列に使用する転送先バッファへのポインタ。面隣接性は、配列の配列として格納される。最も内側の配列は、隣接する三角形の 3 つのインデックスで、外側の配列は、メッシュ内の三角形ごとの面隣接性の 1 セットである。
pNumBoneCombinations
[in, out] エントリの数。
ppBoneCombinationTable
[in, out] D3DXBONECOMBINATION 構造体の配列へのポインタのアドレス。構造体のカウントは pNumBoneCombinations である。それぞれのボーン組み合わせ表に、一度に描画できる 4 つのボーンが定義される。
ppMesh
[in, out] インデックス付きのブレンドされたメッシュを表す ID3DXMesh インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

このメソッドは、スキン メッシュを受け取り、インデックス付きのブレンドされたメッシュに変換する。変換には、Microsoft DirectX® 8.0 で利用可能になった Microsoft® Direct3D® インデックス付き頂点ブレンディング機能を使用する。インデックス付き頂点ブレンディングでは、インデックスを使用して、行列パレットへのインデックスを作成する。詳細については、「ジオメトリ ブレンディング」を参照すること。スキン メッシュからインデックス付きのブレンドされたメッシュに変換すると、単一の描画呼び出しの中でメッシュをレンダリングできる。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXSkinMesh::GenerateSkinnedMesh

スキニングによってメッシュを生成する。

HRESULT GenerateSkinnedMesh(
  DWORD Options,
  FLOAT minWeight,
  CONST LPDWORD pAdjacencyIn,
  LPDWORD pAdjacencyOut,
  LPD3DXMESH* ppMesh
);

パラメータ

Options
[in] メッシュの作成オプションを指定する 1 つ以上のフラグの組み合わせ。次のフラグが定義されている。
D3DXMESH_32BIT
メッシュに、16 ビットではなく 32 ビットのインデックスを作成する。32 ビットのメッシュは、最大 2^32-1 の面と頂点を含むことができる。このフラグはサポートされていないため、使用すべきではない。
D3DXMESH_DONOTCLIP
頂点バッファおよびインデックス バッファに D3DUSAGE_DONOTCLIP 利用フラグを使用する。
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC と D3DXMESH_IB_DYNAMIC の両方を指定したことになる。
D3DXMESH_RTPATCHES
頂点バッファおよびインデックス バッファに D3DUSAGE_RTPATCHES 利用フラグを使用する。
D3DXMESH_NPATCHES
このフラグを指定すると、メッシュの頂点バッファおよびインデックス バッファが D3DUSAGE_NPATCHES フラグを使用して作成されることになる。これは、Microsoft® Direct3D® の N パッチ拡張機能を使用してメッシュ オブジェクトをレンダリングする場合に必要となる。
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED と D3DXMESH_IB_MANAGED の両方を指定したことになる。
D3DXMESH_POINTS
頂点バッファおよびインデックス バッファに D3DUSAGE_POINTS 利用フラグを使用する。
D3DXMESH_IB_DYNAMIC
インデックス バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_IB_MANAGED
インデックス バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_IB_SYSTEMMEM
インデックス バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_IB_WRITEONLY
インデックス バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM と D3DXMESH_IB_SYSTEMMEM の両方を指定したことになる。
D3DXMESH_VB_DYNAMIC
頂点バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_VB_MANAGED
頂点バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_VB_SYSTEMMEM
頂点バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_VB_WRITEONLY
頂点バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY と D3DXMESH_IB_WRITEONLY の両方を指定したことになる。
minWeight
[in] 最小ウェイト固定値を設定する。
pAdjacencyIn
[in, out] ソース メッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの DWORD の配列へのポインタ。
pAdjacencyOut
[in, out] 最適化されたメッシュの面隣接性配列に使用する転送先バッファへのポインタ。面隣接性は、配列の配列として格納される。最も内側の配列は、隣接する三角形の 3 つのインデックスで、外側の配列は、メッシュ内の三角形ごとの面隣接性の 1 セットである。
ppMesh
[out, retval] スキニングによって生成されたメッシュを表す、ID3DXMesh インターフェイスへのポインタ。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

このメソッドにより生成されるメッシュは、スケルトン トランスフォームが変更されるたびに、ID3DXSkinMesh::UpdateSkinnedMesh に指定する必要があるメッシュである。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXSkinMesh::UpdateSkinnedMesh


ID3DXSkinMesh::GetBoneInfluence

ボーンがスキン メッシュにどのように影響を与えるかを示す値の一覧を返す。

HRESULT GetBoneInfluence(
  DWORD Bone,
  DWORD* pVertices,
  FLOAT* pWeights
);

パラメータ

Bone
[in] 照会するボーン。
pVertices
[in, out] ボーンが影響を与える頂点の一覧への参照。
pWeights
[in, out] ボーンが影響を与える頂点の一覧に含まれる各頂点に関連付けられたウェイトの一覧。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXSkinMesh::GetBoneInfluence

Built on 2000年11月18日


ID3DXSkinMesh::GetDeclaration

メッシュに含まれる頂点を記述する宣言を取得する。

HRESULT GetDeclaration(
  DWORD Declaration[MAX_FVF_DECL_SIZE]
);

パラメータ

Declaration
[out] 照会されたメッシュに含まれる頂点の頂点フォーマットを記述する返された配列。この宣言子の配列の上限は MAX_FVF_DECL_SIZE で、宣言子を 15 DWORD の最大数に制限する。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXSkinMesh::GetFVF


ID3DXSkinMesh::GetDevice

スキン メッシュに関連付けられているデバイスを取得する。

HRESULT GetDevice(
  LPDIRECT3DDEVICE8* ppDevice

パラメータ

ppDevice
[out, retval] スキン メッシュに関連付けられている Microsoft® Direct3D® デバイス オブジェクトを表す、IDirect3DDevice8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : d3dx8mesh.h で宣言。
インポート ライブラリ : d3dx8.lib を使用。


ID3DXSkinMesh::GetFVF

スキン メッシュに含まれる頂点の柔軟な頂点フォーマットを取得する。

DWORD GetFVF();

パラメータ

なし。

戻り値

スキン メッシュに含まれる頂点の柔軟な頂点フォーマットを記述する、柔軟な頂点フォーマット フラグの組み合わせを返す。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXSkinMesh::GetDeclaration


ID3DXSkinMesh::GetIndexBuffer

インデックス バッファ内のデータを取得する。

HRESULT GetIndexBuffer(
  LPDIRECT3DINDEXBUFFER8* ppIB
);

パラメータ

ppIB
[out, retval] スキン メッシュに関連付けられているインデックス バッファ オブジェクトを表す、IDirect3DIndexBuffer8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXSkinMesh::GetMaxFaceInfluences

面の影響の数の最大値を返す。

HRESULT GetMaxFaceInfluences(
  DWORD* maxFaceInfluences
);

パラメータ

maxFaceInfluences
[out, retval] スキン メッシュの任意の 1 面に影響を与える、影響の数の最大値。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

各面に n 個のボーンが影響を与える。次に示す図では、1 つの面に 6 つのボーン (面の各頂点に影響を与えるボーンの合計) が影響を与える。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXSkinMesh::GetMaxVertexInfluences

頂点の影響の数の最大値を返す。

HRESULT GetMaxVertexInfluences(
  DWORD* maxVertexInfluences
);

パラメータ

maxVertexInfluences
[out, retval] スキン メッシュの任意の 1 つの頂点に影響を与える、影響の数の最大値。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

各頂点に n 個のボーンが影響を与える。このメソッドで 17 という値が返された場合、スキン メッシュの 1 つの頂点に影響を与えるボーンの最大数は 17 である。したがって、その頂点には 17 の別個のウェイトが存在し、ウェイトの合計は 1 になる。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXSkinMesh::GetNumBoneInfluences

特定のボーンに対する影響 (ウェイト) の数を返す。

DWORD GetNumBoneInfluences(
  DWORD Bone
);

パラメータ

Bone
[in] 照会するボーン。

戻り値

特定のボーンに対するウェイトの数を返す。Bone が無効なボーン数である場合、GetNumBoneInfluences は 0 を返す。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXSkinMesh::GetNumBones

スキン メッシュに含まれるボーンの数を返す。

DWORD GetNumBones();

パラメータ

なし。

戻り値

スキン メッシュに含まれるボーンの数。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXSkinMesh::GetNumFaces

スキン メッシュに含まれる面の数を取得する。

DWORD GetNumFaces();

パラメータ

なし。

戻り値

スキン メッシュに含まれる面の数を返す。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXSkinMesh::GetNumVertices

スキン メッシュに含まれる頂点の数を取得する。

DWORD GetNumVertices();

パラメータ

なし。

戻り値

スキン メッシュに含まれる頂点の数を返す。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXSkinMesh::GetOptions

このスキン メッシュの作成時に有効になっているメッシュ オプションを取得する。

DWORD GetOptions();

パラメータ

なし。

戻り値

このメッシュの作成時に有効になっているオプションを示す、次の 1 つ以上のフラグの組み合わせを返す。

D3DXMESH_32BIT
メッシュに、16 ビットではなく 32 ビットのインデックスを作成する。32 ビットのメッシュは、最大 2^32-1 の面と頂点を含むことができる。このフラグはサポートされていないため、使用すべきではない。
D3DXMESH_DONOTCLIP
頂点バッファおよびインデックス バッファに D3DUSAGE_DONOTCLIP 利用フラグを使用する。
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC と D3DXMESH_IB_DYNAMIC の両方を指定したことになる。
D3DXMESH_RTPATCHES
頂点バッファおよびインデックス バッファに D3DUSAGE_RTPATCHES 利用フラグを使用する。
D3DXMESH_NPATCHES
このフラグを指定すると、メッシュの頂点バッファおよびインデックス バッファが D3DUSAGE_NPATCHES フラグを使用して作成されることになる。これは、Microsoft® Direct3D® の N パッチ拡張機能を使用してメッシュ オブジェクトをレンダリングする場合に必要となる。
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED と D3DXMESH_IB_MANAGED の両方を指定したことになる。
D3DXMESH_POINTS
頂点バッファおよびインデックス バッファに D3DUSAGE_POINTS 利用フラグを使用する。
D3DXMESH_IB_DYNAMIC
インデックス バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_IB_MANAGED
インデックス バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_IB_SYSTEMMEM
インデックス バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_IB_WRITEONLY
インデックス バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM と D3DXMESH_IB_SYSTEMMEM の両方を指定したことになる。
D3DXMESH_USEHWONLY
ハードウェア処理のみを使用する。このフラグは、ハードウェア処理デバイスに対してのみ指定する。混合モードのデバイスに対してこのフラグを指定すると、システムはハードウェアのみを使用するか、ハードウェアに処理能力がない場合は、ソフトウェアの能力を使用して概算する。
D3DXMESH_VB_DYNAMIC
頂点バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_VB_MANAGED
頂点バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_VB_SHARE
コピーしたメッシュに頂点バッファを共有させる。
D3DXMESH_VB_SYSTEMMEM
頂点バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_VB_WRITEONLY
頂点バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY と D3DXMESH_IB_WRITEONLY の両方を指定したことになる。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXSkinMesh::GetOriginalMesh

元の (デフォルト) ポーズのスキン メッシュを返す。

HRESULT GetOriginalMesh(
  LPD3DXMESH* ppMesh
);

パラメータ

ppMesh
[out, retval] メソッドが戻ったときに元のメッシュを格納する、ID3DXMesh インターフェイスへのポインタ。このメソッドが戻ると、返されたメッシュの参照カウントがインクリメントされることに注意すること。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注 このメソッドを呼び出すと、ID3DXMesh インターフェイスの内部参照カウントが増加する。この ID3DXMesh インターフェイスの処理が終了したら、必ず IUnknown::Release を呼び出す必要がある。そうしないと、メモリ リークが発生する。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXSkinMesh::GetVertexBuffer

頂点バッファ内のデータを取得する。

HRESULT GetVertexBuffer(
  LPDIRECT3DVERTEXBUFFER8* ppVB
);

パラメータ

ppVB
[out, retval] スキン メッシュに関連付けられている頂点バッファ オブジェクトを表す、IDirect3DVertexBuffer8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXSkinMesh::LockAttributeBuffer

属性バッファをロックし、属性バッファ メモリへのポインタを取得する。

HRESULT LockAttributeBuffer(
  DWORD Flags,
  DWORD** ppData
);

パラメータ

Flags
[in] 属性バッファ メモリをどのようにロックするかを表す、1 つ以上のロッキング フラグの組み合わせ。
D3DLOCK_DISCARD
アプリケーションは、ロックされている領域内のすべての場所を、書き込み専用処理で上書きする。これにより、非ネイティブ フォーマットで格納されているリソースは圧縮解除ステップを省略できる。
D3DLOCK_NOOVERWRITE
フレームの開始以降、またはこのフラグを持たない最新のロック以降、描画呼び出しの中で参照される情報のうち、ロック時に修正される情報がないことを表す。頂点バッファへのデータの追加だけを行う場合は、このフラグにより処理を最適化できる。
D3DLOCK_NOSYSLOCK
ビデオ メモリ ロックのデフォルトの動作は、システム全体のクリティカル セクションを確保し、ロックの期間中はディスプレイ モードが変化しないことを保証するというものである。このフラグを指定すると、システム全体のクリティカル セクションはロックの間保持されない。

ロック処理は若干負荷が高くなるが、システムは、マウス カーソルの移動といったほかの動作を実行できる。このフラグは、それを行わないとシステムの応答に悪影響を及ぼすソフトウェア レンダリングに対するバック バッファのロックのような、長期間のロックに役立つ。

D3DLOCK_READONLY
アプリケーションはバッファに書き込まない。これにより、非ネイティブ フォーマットで格納されているリソースは、アンロック時に再圧縮ステップを省略できる。
ppData
[out, retval] DWORD 値の配列へのポインタのアドレス。戻り値の属性バッファ データが入力される。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXSkinMesh::UnlockAttributeBuffer


ID3DXSkinMesh::LockIndexBuffer

インデックス バッファをロックし、インデックス バッファ メモリへのポインタを取得する。

HRESULT LockIndexBuffer(
  DWORD Flags,
  BYTE** ppData
);

パラメータ

Flags
[in] インデックス バッファ メモリをどのようにロックするかを記述する、1 つ以上のロッキング フラグの組み合わせ。
D3DLOCK_DISCARD
アプリケーションは、ロックされている領域内のすべての場所を、書き込み専用処理で上書きする。これにより、非ネイティブ フォーマットで格納されているリソースは圧縮解除ステップを省略できる。
D3DLOCK_NOOVERWRITE
フレームの開始以降、またはこのフラグを持たない最新のロック以降、描画呼び出しの中で参照されるインデックスのうち、ロック時に修正されるインデックスがないことを表す。これにより、アプリケーションがインデックス バッファにデータを追加するだけの場合に最適化を有効にできる。
D3DLOCK_NOSYSLOCK
ビデオ メモリ ロックのデフォルトの動作は、システム全体のクリティカル セクションを確保し、ロックの期間中はディスプレイ モードが変化しないことを保証するというものである。このフラグを指定すると、システム全体のクリティカル セクションはロックの間保持されない。

ロック処理は若干負荷が高くなるが、システムは、マウス カーソルの移動といったほかの動作を実行できる。このフラグは、それを行わないとシステムの応答に悪影響を及ぼすソフトウェア レンダリングに対するバック バッファのロックのような、長期間のロックに役立つ。

D3DLOCK_READONLY
アプリケーションはバッファに書き込まない。これにより、非ネイティブ フォーマットで格納されているリソースは、アンロック時に再圧縮ステップを省略できる。
ppData
[out, retval] BYTE 値の配列へのポインタのアドレス。戻り値のインデックス データが入力される。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

インデックス バッファを操作するときは、複数のロック呼び出しを実行できる。ただし、ロック呼び出しの数とロック解除呼び出しの数を一致させる必要がある。現在設定されているインデックス バッファでロック カウントが残っている場合、DrawPrimitive の呼び出しは失敗する。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXSkinMesh::UnlockIndexBuffer


ID3DXSkinMesh::LockVertexBuffer

頂点バッファをロックし、頂点バッファ メモリへのポインタを取得する。

HRESULT LockVertexBuffer(
  DWORD Flags,
  BYTE** ppData
);

パラメータ

Flags
[in] 頂点バッファ メモリをどのようにロックするかを表す、1 つ以上のロッキング フラグの組み合わせ。
D3DLOCK_DISCARD
アプリケーションは、ロックされている領域内のすべての場所を、書き込み専用処理で上書きする。これにより、非ネイティブ フォーマットで格納されているリソースは圧縮解除ステップを省略できる。
D3DLOCK_NOOVERWRITE
フレームの開始以降、またはこのフラグを持たない最新のロック以降、描画呼び出しの中で参照される頂点のうち、ロック時に修正される頂点がないことを表す。頂点バッファへのデータの追加だけを行う場合は、このフラグにより処理を最適化できる。
D3DLOCK_NOSYSLOCK
ビデオ メモリ ロックのデフォルトの動作は、システム全体のクリティカル セクションを確保し、ロックの期間中はディスプレイ モードが変化しないことを保証するというものである。このフラグを指定すると、システム全体のクリティカル セクションはロックの間保持されない。

ロック処理は若干負荷が高くなるが、システムは、マウス カーソルの移動といったほかの動作を実行できる。このフラグは、それを行わないとシステムの応答に悪影響を及ぼすソフトウェア レンダリングに対するバック バッファのロックのような、長期間のロックに役立つ。

D3DLOCK_READONLY
アプリケーションはバッファに書き込まない。これにより、非ネイティブ フォーマットで格納されているリソースは、アンロック時に再圧縮ステップを省略できる。
ppData
[out, retval] BYTE 値の配列へのポインタのアドレス。戻り値の頂点データが入力される。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

頂点バッファを操作するときは、複数のロック呼び出しを実行できる。ただし、ロック呼び出しの数とロック解除呼び出しの数を一致させる必要がある。現在設定されている頂点バッファに未処理のロック カウントがある場合、DrawPrimitive 呼び出しは成功しない。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXSkinMesh::UnlockVertexBuffer


ID3DXSkinMesh::SetBoneInfluence

スキン メッシュに含まれるボーンに対して、ボーンの影響を設定する。

HRESULT SetBoneInfluence(
  DWORD Bone,
  DWORD numInfluences,
  CONST DWORD* pVertices,
  CONST FLOAT* pWeights
);

パラメータ

Bone
[in] 影響を設定するボーン。
numInfluences
[in] ボーンに対して設定する影響の数。
pVertices
[in] 影響 (ウェイト) の設定に使用する頂点の一覧へのポインタ。
pWeights
[in] 指定された頂点に対して設定するウェイトの一覧へのポインタ。これらの値は、スキン メッシュのスキニング情報をプログラムに基づいて格納するために使用される。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、E_OUTOFMEMORY を返す。

注意

このメソッドは、特定のボーンが特定の頂点にどのように影響を与えるかを指定するしくみを提供する。このメソッドは、メッシュに影響を与える各ボーンに対して呼び出す必要がある。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXSkinMesh::UnlockAttributeBuffer

属性バッファのロックを解除する。

HRESULT UnlockAttributeBuffer();

パラメータ

なし。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXSkinMesh::LockAttributeBuffer


ID3DXSkinMesh::UnlockIndexBuffer

インデックス バッファのロックを解除する。

HRESULT UnlockIndexBuffer();

パラメータ

なし。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXSkinMesh::LockIndexBuffer


ID3DXSkinMesh::UnlockVertexBuffer

頂点バッファのロックを解除する。

HRESULT UnlockVertexBuffer();

パラメータ

なし。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXSkinMesh::LockVertexBuffer


ID3DXSkinMesh::UpdateSkinnedMesh

スキン メッシュを更新する。

HRESULT UpdateSkinnedMesh(
  CONST D3DXMATRIX* pBoneTransforms,
  LPD3DXMESH pMesh
);

パラメータ

pBoneTransforms
[in] 新しいボーン トランスフォームを表す、D3DXMATRIX 構造体の配列へのポインタ。この配列の長さは、スキン メッシュに含まれるすべてのボーンのカウントである。
pMesh
[out, retval] 更新されたスキニングされたメッシュを表す、ID3DXMesh インターフェイスへのポインタ。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

このメソッドは、新しいボーン トランスフォームとブレンドされた頂点を更新する。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXSkinMesh::GenerateSkinnedMesh


ID3DXSPMesh

アプリケーションは、ID3DXSPMesh インターフェイスのメソッドを使用して単純化メッシュ オブジェクトを操作する。単純化メッシュは、指定したメッシュを単純化し、面の数を減らすために使用する。

ID3DXSPMesh インターフェイスは、D3DXCreateSPMesh 関数を呼び出して取得する。

ID3DXSPMesh インターフェイスのメソッドは、以下のグループにまとめることができる。

コピー | CloneMesh
 | CloneMeshFVF
 | ClonePMesh
 | ClonePMeshFVF
面 | GetMaxFaces
 | GetNumFaces
 | ReduceFaces
情報 | GetDevice
 | GetOptions
頂点 | GetDeclaration
 | GetFVF
 | GetMaxVertices
 | GetNumVertices
 | ReduceVertices

ID3DXSPMesh インターフェイスは、すべての COM インターフェイスと同じように、IUnknown インターフェイスのメソッドを継承している。IUnknown インターフェイスでは、次の 3 つのメソッドがサポートされている。

IUnknown | AddRef
 | QueryInterface
 | Release

LPD3DXSPMESH 型は、ID3DXSPMesh インターフェイスへのポインタとして定義されている。

typedef struct ID3DXSPMesh *LPD3DXSPMESH;

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

メッシュ関数


ID3DXSPMesh::CloneMesh

宣言子を使用してメッシュのコピーを作成する。

HRESULT CloneMesh(
  DWORD Options,
  CONST DWORD* pDeclaration,
  LPDIRECT3DDEVICE8 pD3DDevice,
  DWORD* pAdjacency,
  DWORD* pVertexRemap,
  LPD3DXMESH* ppCloneMesh
);

パラメータ

Options
[in] メッシュの作成オプションを指定する 1 つ以上のフラグの組み合わせ。次のフラグが定義されている。
D3DXMESH_32BIT
メッシュに、16 ビットではなく 32 ビットのインデックスを作成する。32 ビットのメッシュは、最大 2^32-1 の面と頂点を含むことができる。このフラグはサポートされていないため、使用すべきではない。
D3DXMESH_DONOTCLIP
頂点バッファおよびインデックス バッファに D3DUSAGE_DONOTCLIP 利用フラグを使用する。
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC と D3DXMESH_IB_DYNAMIC の両方を指定したことになる。
D3DXMESH_RTPATCHES
頂点バッファおよびインデックス バッファに D3DUSAGE_RTPATCHES 利用フラグを使用する。
D3DXMESH_NPATCHES
このフラグを指定すると、メッシュの頂点バッファおよびインデックス バッファが D3DUSAGE_NPATCHES フラグを使用して作成されることになる。これは、Microsoft® Direct3D® の N パッチ拡張機能を使用してメッシュ オブジェクトをレンダリングする場合に必要となる。
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED と D3DXMESH_IB_MANAGED の両方を指定したことになる。
D3DXMESH_POINTS
頂点バッファおよびインデックス バッファに D3DUSAGE_POINTS 利用フラグを使用する。
D3DXMESH_IB_DYNAMIC
インデックス バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_IB_MANAGED
インデックス バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_IB_SYSTEMMEM
インデックス バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_IB_WRITEONLY
インデックス バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM と D3DXMESH_IB_SYSTEMMEM の両方を指定したことになる。
D3DXMESH_VB_DYNAMIC
頂点バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_VB_MANAGED
頂点バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_VB_SHARE
コピーしたメッシュに頂点バッファを共有させる。これらのメッシュは、共有する頂点バッファにインデックス付けする個別のインデックス バッファを備える。
D3DXMESH_VB_SYSTEMMEM
頂点バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_VB_WRITEONLY
頂点バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY と D3DXMESH_IB_WRITEONLY の両方を指定したことになる。
pDeclaration
[in] 出力メッシュに含まれる頂点の頂点フォーマットを記述する宣言子を表す、DWORD 値の配列へのポインタ。このパラメータは FVF に直接マップしなければならない。
pD3DDevice
[in] メッシュに関連付けられているデバイス オブジェクトを表す IDirect3DDevice8 インターフェイスへのポインタ。
pAdjacency
[in] ソース メッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの DWORD の配列へのポインタ。
pVertexRemap
[in] 各頂点のインデックスを格納する配列へのポインタ。
ppCloneMesh
[out, retval] コピーされたメッシュを表す ID3DXPMesh インターフェイスへのポインタ。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXSPMesh::GetDeclaration、D3DXDeclaratorFromFVF


ID3DXSPMesh::CloneMeshFVF

柔軟な頂点フォーマット (FVF) コードを使用してメッシュのコピーを作成する。

HRESULT CloneMeshFVF(
  DWORD Options,
  DWORD FVF,
  LPDIRECT3DDEVICE8 pDevice,
  DWORD* pAdjacency,
  DWORD* pVertexRemap,
  LPD3DXMESH* ppCloneMesh
);

パラメータ

Options
[in] メッシュの作成オプションを指定する 1 つ以上のフラグの組み合わせ。次のフラグが定義されている。
D3DXMESH_32BIT
メッシュに、16 ビットではなく 32 ビットのインデックスを作成する。32 ビットのメッシュは、最大 2^32-1 の面と頂点を含むことができる。このフラグはサポートされていないため、使用すべきではない。
D3DXMESH_DONOTCLIP
頂点バッファおよびインデックス バッファに D3DUSAGE_DONOTCLIP 利用フラグを使用する。
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC と D3DXMESH_IB_DYNAMIC の両方を指定したことになる。
D3DXMESH_RTPATCHES
頂点バッファおよびインデックス バッファに D3DUSAGE_RTPATCHES 利用フラグを使用する。
D3DXMESH_NPATCHES
このフラグを指定すると、メッシュの頂点バッファおよびインデックス バッファが D3DUSAGE_NPATCHES フラグを使用して作成されることになる。これは、Microsoft® Direct3D® の N パッチ拡張機能を使用してメッシュ オブジェクトをレンダリングする場合に必要となる。
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED と D3DXMESH_IB_MANAGED の両方を指定したことになる。
D3DXMESH_POINTS
頂点バッファおよびインデックス バッファに D3DUSAGE_POINTS 利用フラグを使用する。
D3DXMESH_IB_DYNAMIC
インデックス バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_IB_MANAGED
インデックス バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_IB_SYSTEMMEM
インデックス バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_IB_WRITEONLY
インデックス バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM と D3DXMESH_IB_SYSTEMMEM の両方を指定したことになる。
D3DXMESH_VB_DYNAMIC
頂点バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_VB_MANAGED
頂点バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_VB_SHARE
コピーしたメッシュに頂点バッファを共有させる。これらのメッシュは、共有する頂点バッファにインデックス付けする個別のインデックス バッファを備える。
D3DXMESH_VB_SYSTEMMEM
頂点バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_VB_WRITEONLY
頂点バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY と D3DXMESH_IB_WRITEONLY の両方を指定したことになる。
FVF
[in] 出力メッシュに含まれる頂点の頂点フォーマットを指定する柔軟な頂点フォーマット フラグの組み合わせ。
pDevice
[in] メッシュに関連付けられているデバイス オブジェクトを表す IDirect3DDevice8 インターフェイスへのポインタ。
pAdjacency
[in] ソース メッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの DWORD の配列へのポインタ。
pVertexRemap
[in] 各頂点のインデックスを格納する配列へのポインタ。
ppCloneMesh
[out, retval] コピーされたメッシュを表す ID3DXPMesh インターフェイスへのポインタ。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

注意

CloneMeshFVF を使用して、メッシュを 1 つの FVF から別の FVF に変換できる。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXSPMesh::GetFVF、D3DXFVFFromDeclarator


ID3DXSPMesh::ClonePMesh

宣言子を使用してプログレッシブ メッシュのコピーを作成する。

HRESULT ClonePMesh(
  DWORD Options,
  CONST DWORD* pDeclaration,
  LPDIRECT3DDEVICE8 pDevice,
  DWORD* pVertexRemap,
  LPD3DXPMESH* ppCloneMesh
);

パラメータ

Options
[in] メッシュの作成オプションを指定する 1 つ以上のフラグの組み合わせ。次のフラグが定義されている。
D3DXMESH_32BIT
メッシュに、16 ビットではなく 32 ビットのインデックスを作成する。32 ビットのメッシュは、最大 2^32-1 の面と頂点を含むことができる。このフラグはサポートされていないため、使用すべきではない。
D3DXMESH_DONOTCLIP
頂点バッファおよびインデックス バッファに D3DUSAGE_DONOTCLIP 利用フラグを使用する。
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC と D3DXMESH_IB_DYNAMIC の両方を指定したことになる。
D3DXMESH_RTPATCHES
頂点バッファおよびインデックス バッファに D3DUSAGE_RTPATCHES 利用フラグを使用する。
D3DXMESH_NPATCHES
このフラグを指定すると、メッシュの頂点バッファおよびインデックス バッファが D3DUSAGE_NPATCHES フラグを使用して作成されることになる。これは、Microsoft® Direct3D® の N パッチ拡張機能を使用してメッシュ オブジェクトをレンダリングする場合に必要となる。
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED と D3DXMESH_IB_MANAGED の両方を指定したことになる。
D3DXMESH_POINTS
頂点バッファおよびインデックス バッファに D3DUSAGE_POINTS 利用フラグを使用する。
D3DXMESH_IB_DYNAMIC
インデックス バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_IB_MANAGED
インデックス バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_IB_SYSTEMMEM
インデックス バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_IB_WRITEONLY
インデックス バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM と D3DXMESH_IB_SYSTEMMEM の両方を指定したことになる。
D3DXMESH_VB_DYNAMIC
頂点バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_VB_MANAGED
頂点バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_VB_SHARE
コピーしたメッシュに頂点バッファを共有させる。これらのメッシュは、共有する頂点バッファにインデックス付けする個別のインデックス バッファを備える。
D3DXMESH_VB_SYSTEMMEM
頂点バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_VB_WRITEONLY
頂点バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY と D3DXMESH_IB_WRITEONLY の両方を指定したことになる。
pDeclaration
[in] 出力メッシュに含まれる頂点の頂点フォーマットを記述する宣言子を表す、DWORD 値の配列へのポインタ。このパラメータは FVF に直接マップしなければならない。
pDevice
[in] メッシュに関連付けられているデバイス オブジェクトを表す IDirect3DDevice8 インターフェイスへのポインタ。
pVertexRemap
[in] 各頂点のインデックスを格納する配列へのポインタ。
ppCloneMesh
[out, retval] コピーされたプログレッシブ メッシュを表す ID3DXPMesh インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_CANNOTATTRSORT
E_OUTOFMEMORY

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXSPMesh::GetDeclaration、D3DXDeclaratorFromFVF


ID3DXSPMesh::ClonePMeshFVF

柔軟な頂点フォーマット (FVF) コードを使用して、プログレッシブ メッシュのコピーを作成する。

HRESULT ClonePMeshFVF(
  DWORD Options,
  DWORD FVF,
  LPDIRECT3DDEVICE8 pDevice,
  DWORD* pVertexRemap,
  LPD3DXPMESH* ppCloneMesh
);

パラメータ

Options
[in] メッシュの作成オプションを指定する 1 つ以上のフラグの組み合わせ。次のフラグが定義されている。
D3DXMESH_32BIT
メッシュに、16 ビットではなく 32 ビットのインデックスを作成する。32 ビットのメッシュは、最大 2^32-1 の面と頂点を含むことができる。このフラグはサポートされていないため、使用すべきではない。
D3DXMESH_DONOTCLIP
頂点バッファおよびインデックス バッファに D3DUSAGE_DONOTCLIP 利用フラグを使用する。
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC と D3DXMESH_IB_DYNAMIC の両方を指定したことになる。
D3DXMESH_RTPATCHES
頂点バッファおよびインデックス バッファに D3DUSAGE_RTPATCHES 利用フラグを使用する。
D3DXMESH_NPATCHES
このフラグを指定すると、メッシュの頂点バッファおよびインデックス バッファが D3DUSAGE_NPATCHES フラグを使用して作成されることになる。これは、Microsoft® Direct3D® の N パッチ拡張機能を使用してメッシュ オブジェクトをレンダリングする場合に必要となる。
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED と D3DXMESH_IB_MANAGED の両方を指定したことになる。
D3DXMESH_POINTS
頂点バッファおよびインデックス バッファに D3DUSAGE_POINTS 利用フラグを使用する。
D3DXMESH_IB_DYNAMIC
インデックス バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_IB_MANAGED
インデックス バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_IB_SYSTEMMEM
インデックス バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_IB_WRITEONLY
インデックス バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM と D3DXMESH_IB_SYSTEMMEM の両方を指定したことになる。
D3DXMESH_VB_DYNAMIC
頂点バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_VB_MANAGED
頂点バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_VB_SHARE
コピーしたメッシュに頂点バッファを共有させる。これらのメッシュは、共有する頂点バッファにインデックス付けする個別のインデックス バッファを備える。
D3DXMESH_VB_SYSTEMMEM
頂点バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_VB_WRITEONLY
頂点バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY と D3DXMESH_IB_WRITEONLY の両方を指定したことになる。
FVF
[in] 出力メッシュに含まれる頂点の頂点フォーマットを指定する柔軟な頂点フォーマット フラグの組み合わせ。
pDevice
[in] メッシュに関連付けられているデバイス オブジェクトを表す IDirect3DDevice8 インターフェイスへのポインタ。
pVertexRemap
[in] 各頂点のインデックスを格納する配列へのポインタ。
ppCloneMesh
[out, retval] コピーされたプログレッシブ メッシュを表す ID3DXPMesh インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_CANNOTATTRSORT
E_OUTOFMEMORY

注意

ClonePMeshFVF を使用して、プログレッシブ メッシュを 1 つの FVF から別の FVF に変換できる。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXSPMesh::GetFVF、D3DXFVFFromDeclarator


ID3DXSPMesh::GetDeclaration

メッシュに含まれる頂点を記述する宣言を取得する。

HRESULT GetDeclaration(
  DWORD Declaration[MAX_FVF_DECL_SIZE]
);

パラメータ

Declaration
[out] 照会されたメッシュに含まれる頂点の頂点フォーマットを記述する返された配列。この宣言子の配列の上限は MAX_FVF_DECL_SIZE で、宣言子を 15 DWORD の最大数に制限する。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

対象

このメソッドは、ID3DXBaseMesh を継承する次のインターフェイスに適用される。

  • ID3DXMesh
  • ID3DXPMesh

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXSPMesh::GetFVF


ID3DXSPMesh::GetDevice

単純化メッシュに関連付けられているデバイス オブジェクトを取得する。

HRESULT GetDevice(
  LPDIRECT3DDEVICE8* ppDevice

パラメータ

ppDevice
[out, retval] 単純化メッシュに関連付けられている Microsoft® Direct3D® デバイス オブジェクトを表す、IDirect3DDevice8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注 このメソッドを呼び出すと、IDirect3DDevice8 インターフェイスの内部参照カウントが増加する。この IDirect3DDevice8 インターフェイスの処理が終了したら、必ず IUnknown::Release を呼び出す必要がある。そうしないと、メモリ リークが発生する。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXSPMesh::GetFVF

単純化メッシュに含まれる頂点の柔軟な頂点フォーマットを取得する。

DWORD GetFVF();

パラメータ

なし。

戻り値

単純化メッシュに含まれる頂点の柔軟な頂点フォーマットを記述する、柔軟な頂点フォーマット フラグの組み合わせを返す。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXSPMesh::GetDeclaration


ID3DXSPMesh::GetMaxFaces

単純化メッシュがサポートする面の数の最大値を取得する。

DWORD GetMaxFaces();

パラメータ

なし。

戻り値

元のメッシュに含まれる面の最大数を返す。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXSPMesh::GetMaxVertices

単純化メッシュがサポートする頂点の数の最大値を取得する。

DWORD GetMaxVertices();

パラメータ

なし。

戻り値

元のメッシュに含まれる頂点の最大数を返す。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXSPMesh::GetNumFaces

単純化メッシュに含まれる面の数を取得する。

DWORD GetNumFaces();

パラメータ

なし。

戻り値

単純化メッシュに含まれる面の数を返す。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXSPMesh::GetNumVertices

単純化メッシュに含まれる頂点の数を取得する。

DWORD GetNumVertices();

パラメータ

なし。

戻り値

単純化メッシュに含まれる頂点の数を返す。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXSPMesh::GetOptions

この単純化メッシュの作成時に有効になっているメッシュ オプションを取得する。

DWORD GetOptions();

パラメータ

なし。

戻り値

このメッシュの作成時に有効になっているオプションを示す、次の 1 つ以上のフラグの組み合わせを返す。

D3DXMESH_32BIT
メッシュに、16 ビットではなく 32 ビットのインデックスを作成する。32 ビットのメッシュは、最大 2^32-1 の面と頂点を含むことができる。このフラグはサポートされていないため、使用すべきではない。
D3DXMESH_DONOTCLIP
頂点バッファおよびインデックス バッファに D3DUSAGE_DONOTCLIP 利用フラグを使用する。
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC と D3DXMESH_IB_DYNAMIC の両方を指定したことになる。
D3DXMESH_RTPATCHES
頂点バッファおよびインデックス バッファに D3DUSAGE_RTPATCHES 利用フラグを使用する。
D3DXMESH_NPATCHES
このフラグを指定すると、メッシュの頂点バッファおよびインデックス バッファが D3DUSAGE_NPATCHES フラグを使用して作成されることになる。これは、Microsoft® Direct3D® の N パッチ拡張機能を使用してメッシュ オブジェクトをレンダリングする場合に必要となる。
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED と D3DXMESH_IB_MANAGED の両方を指定したことになる。
D3DXMESH_POINTS
頂点バッファおよびインデックス バッファに D3DUSAGE_POINTS 利用フラグを使用する。
D3DXMESH_IB_DYNAMIC
インデックス バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_IB_MANAGED
インデックス バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_IB_SYSTEMMEM
インデックス バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_IB_WRITEONLY
インデックス バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM と D3DXMESH_IB_SYSTEMMEM の両方を指定したことになる。
D3DXMESH_VB_DYNAMIC
頂点バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_VB_MANAGED
頂点バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_VB_SHARE
コピーしたメッシュに頂点バッファを共有させる。
D3DXMESH_VB_SYSTEMMEM
頂点バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_VB_WRITEONLY
頂点バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY と D3DXMESH_IB_WRITEONLY の両方を指定したことになる。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXSPMesh::ReduceFaces

単純化メッシュに含まれる面の数を減らす。

HRESULT ReduceFaces(
  DWORD Faces
);

パラメータ

Faces
[in] プリミティブ カウントを減らした後の面の数。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

このメソッドは、エッジの折りたたみを行い、Faces で指定した値までプリミティブの数を減らす。特定の制限があるため、メッシュを要求された値まで常に減らせるわけではない。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXSPMesh::ReduceVertices

単純化メッシュに含まれる頂点の数を減らす。

HRESULT ReduceVertices(
  DWORD Vertices
);

パラメータ

Vertices
[in] プリミティブ カウントを減らした後の頂点の数。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

このメソッドは、エッジの折りたたみを行い、Vertices で指定した値までプリミティブの数を減らす。特定の制限があるため、メッシュを要求された値まで常に減らせるわけではない。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXSprite

ID3DXSprite インターフェイスは、Microsoft® Direct3D® を使用してスプライトを描画するプロセスを単純化するメソッドのセットを提供する。

ID3DXSprite インターフェイスは、D3DXCreateSprite 関数を呼び出して取得する。

ID3DXSprite インターフェイスのメソッドは、以下のグループにまとめることができる。

描画 | Begin
 | Draw
 | DrawTransform
 | End
情報 | GetDevice

ID3DXSprite インターフェイスは、すべての COM インターフェイスと同じように、IUnknown インターフェイスのメソッドを継承している。IUnknown インターフェイスでは、次の 3 つのメソッドがサポートされている。

IUnknown | AddRef
 | QueryInterface
 | Release

LPD3DXSPRITE 型は、ID3DXSprite インターフェイスへのポインタとして定義されている。

typedef interface ID3DXSprite *LPD3DXSPRITE;

動作環境

ヘッダー : D3dx8core.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXSprite::Begin

スプライトを描画できるようにデバイスを準備する。

HRESULT Begin();

パラメータ

なし。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

注意

Begin の呼び出しは省略できる。Begin/End シーケンスの外側で描画関数を呼び出すと、内部で Begin とEnd が呼び出される。余分なオーバーヘッドを回避するには、複数の描画関数を続けて呼び出す場合に、このメソッドを使用する必要がある。

IDirect3DDevice8::BeginScene または ID3DXRenderToSurface::BeginScene の代わりとして ID3DXSprite::Begin を使用することはできない。

動作環境

ヘッダー : D3dx8core.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXSprite::End


ID3DXSprite::Draw

スクリーン空間に単純なスプライトを描画する。

HRESULT Draw(
  LPDIRECT3DTEXTURE8 pSrcTexture,
  CONST RECT* pSrcRect,
  CONST D3DXVECTOR2* pScaling,
  CONST D3DXVECTOR2* pRotationCenter,
  FLOAT Rotation,
  CONST D3DVECTOR2* pTranslation,
  D3DCOLOR Color
);

パラメータ

pSrcTexture
[in] スプライトに使用するソース イメージを表す IDirect3DTexture8 インターフェイスへのポインタ。
pSrcRect
[in] ソース テクスチャのどの部分をスプライトに使用するかを示す RECT 構造体へのポインタ。このパラメータを NULL にすると、ソース イメージ全体がスプライトに使用される。ただし、ソース イメージの部分的な矩形を指定することもできる。この RECT 構造体の左と上および右と下のパラメータを入れ替えると、x と y のミラーリングを簡単に指定できる。

トランスフォームの前に、スプライトのサイズが pSrcRect により左上隅を始点 (0,0) として定義される。

pScaling
[in] スケーリング ベクトルである D3DXVECTOR2 構造体へのポインタ。この引数が NULL の場合は、スケーリングしないと見なされる。
pRotationCenter
[in] 回転の中心を識別するポイントである D3DVECTOR2 構造体へのポインタ。この引数が NULL の場合は、テクスチャの左上隅を表すポイント (0,0) であると見なされる。
Rotation
[in] 回転を指定する値。
pTranslation
[in] 平行移動を表す D3DXVECTOR2 構造体へのポインタ。この引数が NULL の場合は、平行移動しないと見なされる。
Color
[in] D3DCOLOR 型。この値によりカラー チャネルとアルファ チャネルが乗算される。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

ID3DXSprite::Begin が呼び出されていない場合、このメソッドは内部で Begin と ID3DXSprite::End を呼び出す。ID3DXSprite::Draw または ID3DXSprite::DrawTransform あるいはその両方を続けて呼び出す場合は、必ず Begin を呼び出し、Draw および DrawTransform が毎回内部で Begin と End を呼び出す余分なオーバーヘッドを回避する必要がある。

動作環境

ヘッダー : D3dx8core.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXSprite::DrawTransform


ID3DXSprite::DrawTransform

指定した行列によってトランスフォームしたスプライトを描画するためのしくみを提供する。

HRESULT DrawTransform(
  LPDIRECT3DTEXTURE8 pSrcTexture,
  CONST RECT* pSrcRect,
  CONST D3DXMATRIX* pTransform,
  D3DCOLOR Color
);

パラメータ

pSrcTexture
[in] スプライトに使用するソース イメージを表す IDirect3DTexture8 インターフェイスへのポインタ。
pSrcRect
[in] ソース テクスチャのどの部分をスプライトに使用するかを示す RECT 構造体へのポインタ。このパラメータを NULL にすると、ソース イメージ全体がスプライトに使用される。ただし、ソース イメージの部分的な矩形を指定することもできる。この RECT 構造体の左と上および右と下のパラメータを入れ替えると、x と y のミラーリングを簡単に指定できる。

トランスフォームの前に、スプライトのサイズが pSrcRect により左上隅を始点 (0,0) として定義される。

pTransform
[in] 適用するトランスフォームを指定する D3DXMATRIX 構造体へのポインタ。
Color
[in] D3DCOLOR 型。この値によりカラー チャネルとアルファ チャネルが乗算される。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

ID3DXSprite::Begin が呼び出されていない場合、このメソッドは内部で Begin と ID3DXSprite::End を呼び出す。ID3DXSprite::Draw または ID3DXSprite::DrawTransform あるいはその両方を続けて呼び出す場合は、必ず Begin を呼び出し、Draw および DrawTransform が毎回内部で Begin と End を呼び出す余分なオーバーヘッドを回避する必要がある。

動作環境

ヘッダー : D3dx8core.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXSprite::Draw


ID3DXSprite::End

ID3DXSprite::Begin が呼び出された時点のデバイスの状態を復元する。

HRESULT End();

パラメータ

なし。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

注意

IDirect3DDevice8::EndScene または ID3DXRenderToSurface::EndScene の代わりとして ID3DXSprite::End を使用することはできない。

動作環境

ヘッダー : D3dx8core.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXSprite::Begin


ID3DXSprite::GetDevice

スプライト オブジェクトに関連付けられている Microsoft® Direct3D® デバイスを取得する。

HRESULT GetDevice(
  LPDIRECT3DDEVICE8* ppDevice
);

パラメータ

ppDevice
[out, retval] スプライト オブジェクトに関連付けられている Direct3D デバイス オブジェクトを表す、IDirect3DDevice8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注 このメソッドを呼び出すと、IDirect3DDevice8 インターフェイスの内部参照カウントが増加する。この IDirect3DDevice8 インターフェイスの処理が終了したら、必ず IUnknown::Release を呼び出す必要がある。そうしないと、メモリ リークが発生する。

動作環境

ヘッダー : D3dx8core.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXTechnique

ID3DXTechnique インターフェイスは、テクニックの照会、検証、および適用に使用する。

ID3DXTechnique インターフェイスは、ID3DXEffect::GetTechnique メソッドを呼び出すことによって取得する。

ID3DXTechnique インターフェイスのメソッドは、以下のグループにまとめることができる。

エフェクト | IsParameterUsed
情報 | GetDevice
 | GetDesc
 | GetPassDesc
検証 | Validate
テクニック適用 | Begin
 | End
 | Pass

ID3DXTechnique インターフェイスは、すべての COM インターフェイスと同じように、IUnknown インターフェイスのメソッドを継承している。IUnknown インターフェイスでは、次の 3 つのメソッドがサポートされている。

IUnknown | AddRef
 | QueryInterface
 | Release

LPD3DXTECHNIQUE 型は、ID3DXTechnique インターフェイスへのポインタとして定義されている。

typedef struct ID3DXTechnique* LPD3DXTECHNIQUE;

動作環境

ヘッダー : D3dx8effect.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXTechnique::Begin

テクニックのアプリケーションを開始する。

HRESULT Begin(
  UINT* pPasses
);

パラメータ

pPasses
[out, retval] テクニックのレンダリングに必要となるパス数を示す値へのポインタ。

戻り値

常に S_OK を返す。

注意

このメソッドは、テクニックのレンダリングに必要なパス数を返す。エフェクトを適用する必要のあるジオメトリを描画するため、アプリケーションはパスごとに値を増やして ID3DXTechnique::Pass を呼び出さなければならない。すべてのパスのレンダリングが終了したら、ID3DXTechnique::End を呼び出さなければならない。

動作環境

ヘッダー : D3dx8effect.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXTechnique::End、ID3DXTechnique::Pass


ID3DXTechnique::End

テクニックのアプリケーションを終了する。

HRESULT End();

パラメータ

なし。

戻り値

常に S_OK を返す。

動作環境

ヘッダー : D3dx8effect.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXTechnique::Begin、ID3DXTechnique::Pass


ID3DXTechnique::GetDevice

テクニックに関連付けられているデバイスを取得する。

HRESULT GetDevice(
  IDirect3DDevice8** ppDevice
);

パラメータ

ppDevice
IDirect3DDevice8 インターフェイスへのポインタのアドレス。テクニックに関連付けられているデバイスを表す。

戻り値

常に S_OK を返す。

注 このメソッドを呼び出すと、IDirect3DDevice8 インターフェイスの内部参照カウントが増加する。この IDirect3DDevice8 インターフェイスの処理が終了したら、必ず IUnknown::Release を呼び出す必要がある。そうしないと、メモリ リークが発生する。

動作環境

ヘッダー : D3dx8effect.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXTechnique::GetDesc

テクニックの説明を取得する。

HRESULT GetDesc(
  D3DXTECHNIQUE_DESC* pDesc
);

パラメータ

pDesc
[out, retval] D3DXTECHNIQUE_DESC 構造体。テクニックの説明。

戻り値

成功した場合は、S_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : D3dx8effect.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXTechnique::GetPassDesc

エフェクトのパスに関する情報を取得する。

HRESULT GetPassDesc(
  UINT           Index,
  D3DXPASS_DESC* pDesc
)

パラメータ

Index
情報を取得するパスのインデックス。
pDesc
[out, retval] パスの説明を格納する D3DXPASS_DESC 構造体へのポインタ。

戻り値

成功した場合は、S_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : D3dx8effect.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXTechnique::IsParameterUsed

テクニックがパラメータを使用しているかどうかを判別する。

BOOL IsParameterUsed(
  DWORD Name
)

パラメータ

Name
調べるパラメータのインデックス。このパラメータは FOURCC コードでなければならない。「注意」を参照すること。

戻り値

パラメータが使用されている場合は TRUE を返す。パラメータが使用されていない場合は FALSE を返す。

注意

FOURCC コードは、長さが 4 文字の文字列である。詳細については、「FOURCC コード」を参照すること。

動作環境

ヘッダー : D3dx8effect.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


ID3DXTechnique::Pass

指定したテクニックのパスに対し、ステートの設定を適用する。

HRESULT Pass(
  UINT Index
);

パラメータ

Pass
[in] 適用するパスを指定する。

戻り値

成功した場合は、S_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

注意

Pass を呼び出した後、アプリケーションは、エフェクトが設定されるデバイスに対してジオメトリを描画しなければならない。

動作環境

ヘッダー : D3dx8effect.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXTechnique::Begin、ID3DXTechnique::End


ID3DXTechnique::Validate

テクニックを検証する。

HRESULT Validate();

戻り値

成功した場合は、S_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

動作環境

ヘッダー : D3dx8effect.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


関数

ここでは、Direct3DX ユーティリティ ライブラリを使用する際に実装する必要のある関数のリファレンス情報を記述する。次の関数が実装されている。

  • エフェクト関数
  • 汎用関数
  • 算術関数
  • メッシュ関数
  • シェーダ関数
  • 形状描画関数
  • テクスチャ関数


エフェクト関数

Direct3DX では次のエフェクト関数が用意されている。

  • D3DXCompileEffect
  • D3DXCompileEffectFromFileA
  • D3DXCompileEffectFromFileW
  • D3DXCreateEffect


D3DXCompileEffect

エフェクトの ASCII 記述を、D3DXCreateEffect で使用できるバイナリ形式にコンパイルする。

HRESULT WINAPI D3DXCompileEffect(
  LPCVOID       pSrcData,
  UINT          SrcDataSize,
  LPD3DXBUFFER* ppCompiledEffect,
  LPD3DXBUFFER* ppCompilationErrors
);

パラメータ

pSrcData
[in] コンパイルするエフェクトを表すソース データへのポインタ。
SrcDataSize
[in] ソース データのサイズ (バイト単位)。
ppCompiledEffect
[out, retval] コンパイルされたエフェクトを格納する、ID3DXBuffer インターフェイスへのポインタのアドレス。
ppCompilationErrors
[out, retval] 返された ASCII エラー メッセージを格納する、ID3DXBuffer インターフェイスへのポインタのアドレス。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

注意

エフェクトをコンパイルした後、D3DXCreateEffect を使用して ID3DXEffect インターフェイスへのポインタを取得すること。

動作環境

ヘッダー : D3dx8effect.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXCompileEffectFromFileA 、 D3DXCompileEffectFromFileW 、 D3DXCreateEffect


D3DXCompileEffectFromFileA

ANSI 文字列で指定したファイルを元にしてエフェクトをコンパイルする。

HRESULT WINAPI D3DXCompileEffectFromFileA(
  LPCSTR        pSrcFile,
  LPD3DXBUFFER* ppCompiledEffect,
  LPD3DXBUFFER* ppCompilationErrors
);

パラメータ

pSrcFile
[in] エフェクト作成の元となるファイルを指定する ANSI 文字列へのポインタ。
ppCompiledEffect
[out, retval] コンパイルされたエフェクトを格納する、ID3DXBuffer インターフェイスへのポインタのアドレス。
ppCompilationErrors
[out, retval] 返された ASCII エラー メッセージを格納する、ID3DXBuffer インターフェイスへのポインタのアドレス。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

注意

エフェクトをコンパイルした後、D3DXCreateEffect を使用して ID3DXEffect インターフェイスへのポインタを取得すること。

D3DXCompileEffectFromFile は、#define UNICODE スイッチが含まれているかどうかに応じて、D3DXCompileEffectFromFileA または D3DXCompileEffectFromFileW のどちらかをマップする。#define UNICODE スイッチを挿入または除外して、アプリケーションで Unicode または ANSI 文字列のどちらを使用するかを指定する。次のコードは、D3DXCompileEffectFromFile の定義方法を示している。

#ifdef UNICODE
#define D3DXCompileEffectFromFile D3DXCompileEffectFromFileW
#else
#define D3DXCompileEffectFromFile D3DXCompileEffectFromFileA
#endif

動作環境

ヘッダー : D3dx8effect.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXCompileEffect 、 D3DXCompileEffectFromFileW 、 D3DXCreateEffect


D3DXCompileEffectFromFileW

Unicode 文字列で指定したファイルを元にしてエフェクトをコンパイルする。

HRESULT WINAPI D3DXCompileEffectFromFileW(
  LPCWSTR       pSrcFile,
  LPD3DXBUFFER* ppCompiledEffect,
  LPD3DXBUFFER* ppCompilationErrors
);

パラメータ

pSrcFile
[in] エフェクト作成の元となるファイルを指定する Unicode 文字列へのポインタ。
ppCompiledEffect
[out, retval] コンパイルされたエフェクトを格納する、ID3DXBuffer インターフェイスへのポインタのアドレス。
ppCompilationErrors
[out, retval] 返された ASCII エラー メッセージを格納する、ID3DXBuffer インターフェイスへのポインタのアドレス。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

注意

エフェクトをコンパイルした後、D3DXCreateEffect を使用して ID3DXEffect インターフェイスへのポインタを取得すること。

D3DXCompileEffectFromFile は、#define UNICODE スイッチが含まれているかどうかに応じて、D3DXCompileEffectFromFileA または D3DXCompileEffectFromFileW のどちらかをマップする。#define UNICODE スイッチを挿入または除外して、アプリケーションで Unicode または ANSI 文字列のどちらを使用するかを指定する。次のコードは、D3DXCompileEffectFromFile の定義方法を示している。

#ifdef UNICODE
#define D3DXCompileEffectFromFile D3DXCompileEffectFromFileW
#else
#define D3DXCompileEffectFromFile D3DXCompileEffectFromFileA
#endif

動作環境

ヘッダー : D3dx8effect.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXCompileEffect 、 D3DXCompileEffectFromFileA 、 D3DXCreateEffect


D3DXCreateEffect

コンパイル済みのソース データを使用してエフェクトを作成する。

HRESULT WINAPI D3DXCreateEffect(
  LPDIRECT3DDEVICE8 pDevice,
  LPCVOID           pCompiledEffect,
  UINT              CompiledEffectSize,
  DWORD             Usage,
  LPD3DXEFFECT*     ppEffect
);

パラメータ

pDevice
[in] エフェクトに関連付けられているデバイスを表す IDirect3DDevice8 インターフェイスへのポインタ。
pCompiledEffect
[in] エフェクト作成の元になるコンパイル済みのソース データへのポインタ。
CompiledEffectSize
[in] コンパイル済みのデータのサイズ (バイト単位)。
Usage
[in] このエフェクトの使用方法の制御情報。次のフラグを設定できる。
D3DUSAGE_SOFTWAREPROCESSING
エフェクトがソフトウェア処理を使用してレンダリングされることを示す。
ppEffect
[out, retval] 作成されたエフェクトを表す、ID3DXEffect インターフェイスへのポインタのアドレス。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

注意

CreateEffect を使用する前に、次のいずれかの関数を使用してエフェクトをコンパイルしなければならない。

  • D3DXCompileEffect
  • D3DXCompileEffectFromFileA
  • D3DXCompileEffectFromFileW

動作環境

ヘッダー : D3dx8effect.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXCompileEffect 、 D3DXCompileEffectFromFileA 、 D3DXCompileEffectFromFileW


汎用関数

Direct3DX では次の汎用関数が用意されている。

  • D3DXCreateFont
  • D3DXCreateFontIndirect
  • D3DXCreateRenderToSurface
  • D3DXCreateSprite
  • D3DXGetErrorStringA
  • D3DXGetErrorStringW
  • D3DXGetFVFVertexSize


D3DXCreateFont

デバイスとフォント用のフォント オブジェクトを作成する。

HRESULT D3DXCreateFont(
  LPDIRECT3DDEVICE8 pDevice,
  HFONT hFont,
  LPD3DXFONT* ppFont
);

パラメータ

pDevice
[in] フォント オブジェクトに関連付けられるデバイスである、IDirect3DDevice8 インターフェイスへのポインタ。
hFont
[in] フォント オブジェクトへのハンドル。
ppFont
[out] 作成されたフォント オブジェクトを表す、ID3DXFont インターフェイスへのポインタを返す。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

動作環境

ヘッダー : D3dx8core.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXCreateFontIndirect

デバイスとフォント用のフォント オブジェクトを間接的に作成する。

HRESULT D3DXCreateFontIndirect(
  LPDIRECT3DDEVICE8 pDevice,
  CONST LOGFONT* pLogFont,
  LPD3DXFONT* ppFont
);

パラメータ

pDevice
[in] フォント オブジェクトに関連付けられるデバイスである、IDirect3DDevice8 インターフェイスへのポインタ。
pLogFont
[in] 作成するフォント オブジェクトの属性を記述する、LOGFONT 構造体へのポインタ。
ppFont
[out] 作成されたフォント オブジェクトを表す、ID3DXFont インターフェイスへのポインタを返す。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

注意

LOGFONT 構造体の詳細については、Microsoft® Platform Software Development Kit (SDK) を参照すること。

動作環境

ヘッダー : D3dx8core.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXCreateRenderToSurface

レンダリング サーフェスを作成する。

HRESULT D3DXCreateRenderToSurface(
  LPDIRECT3DDEVICE8 pDevice,
  UINT Width,
  UINT Height,
  D3DFORMAT Format,
  BOOL DepthStencil,
  D3DFORMAT DepthStencilFormat,
  LPD3DXRENDERTOSURFACE* ppRenderToSurface
);

パラメータ

pDevice
[in] レンダリング サーフェスに関連付けられるデバイスである、IDirect3DDevice8 インターフェイスへのポインタ。
Width
[in] レンダリング サーフェスの幅 (ピクセル単位)。
Height
[in] レンダリング サーフェスの高さ (ピクセル単位)。
Format
[in] レンダリング サーフェスのピクセル フォーマットを記述する、D3DFORMAT 列挙型のメンバ。
DepthStencil
[in] TRUE の場合、レンダリング サーフェスは深度ステンシル サーフェスをサポートする。そうでない場合、このメンバは FALSE に設定される。
DepthStencilFormat
[in] DepthStencil が TRUE に設定される場合、このパラメータは、レンダリング サーフェスの深度ステンシル フォーマットを記述する D3DFORMAT 列挙型のメンバである。
ppRenderToSurface
[out] 作成されたレンダリング サーフェスを表す、ID3DXRenderToSurface インターフェイスへのポインタのアドレス。

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

動作環境

ヘッダー : D3dx8core.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXCreateSprite

スプライト オブジェクトを作成する。

HRESULT D3DXCreateSprite(
  LPDIRECT3DDEVICE8 pDevice,
  LPD3DXSPRITE* ppSprite
);

パラメータ

pDevice
[in] スプライトに関連付けられるデバイスである、IDirect3DDevice8 インターフェイスへのポインタ。
ppSprite
[out] 作成されたスプライトを表す ID3DXSprite インターフェイスへのポインタのアドレス。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

動作環境

ヘッダー : D3dx8core.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXGetErrorStringA

HRESULT について ANSI エラー文字列を返す。

HRESULT D3DXGetErrorStringA(
  HRESULT hr,
  LPSTR pBuffer,
  UINT BufferLen
);

パラメータ

hr
[in] 解読対象の指定された HRESULT エラー コード。
pBuffer
[out] ANSI エラー文字列で埋めるバッファへのポインタ。
BufferLen
[in] バッファ内の文字数。この値より長いエラーメッセージは切り捨てられる。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

D3DXGetErrorString は、#define UNICODE スイッチが含まれているかどうかに応じて、D3DXGetErrorStringA または D3DXGetErrorStringW のどちらかをマップする。#define UNICODE スイッチを挿入または除外して、アプリケーションで Unicode または ANSI 文字列のどちらを使用するかを指定する。次のコードは、D3DXGetErrorString の定義方法を示している。

#ifdef UNICODE
#define D3DXGetErrorString D3DXGetErrorStringW
#else
#define D3DXGetErrorString D3DXGetErrorStringA
#endif

この関数は、すべての Microsoft® Direct3D® HRESULTS を解析する。

動作環境

ヘッダー : D3dx8core.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXGetErrorStringW


D3DXGetErrorStringW

HRESULT について Unicode エラー文字列を返す。

HRESULT D3DXGetErrorStringW(
  HRESULT hr,
  LPWSTR pBuffer,
  UINT BufferLen
);

パラメータ

hr
[in] 解読対象の指定された HRESULT エラー コード。
pBuffer
[out] Unicode エラー文字列で埋めるバッファへのポインタ。
BufferLen
[in] バッファ内の文字数。この値より長いエラーメッセージは切り捨てられる。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

注意

この関数は、すべての Microsoft® Direct3D® HRESULTS を解析する。

D3DXGetErrorString は、#define UNICODE スイッチが含まれているかどうかに応じて、D3DXGetErrorStringA または D3DXGetErrorStringW のどちらかをマップする。#define UNICODE スイッチを挿入または除外して、アプリケーションで Unicode または ANSI 文字列のどちらを使用するかを指定する。次のコードは、D3DXGetErrorString の定義方法を示している。

#ifdef UNICODE
#define D3DXGetErrorString D3DXGetErrorStringW
#else
#define D3DXGetErrorString D3DXGetErrorStringA
#endif

動作環境

ヘッダー : D3dx8core.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXGetErrorStringA


D3DXGetFVFVertexSize

柔軟な頂点フォーマット用に頂点のサイズを返す。

UINT D3DXGetFVFVertexSize(
  DWORD FVF
);

パラメータ

FVF
[in] 照会対象の柔軟な頂点フォーマット。柔軟な頂点フォーマット フラグの組み合わせ。

戻り値

柔軟な頂点フォーマットの頂点のサイズ (バイト単位)。

動作環境

ヘッダー : D3dx8core.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


算術関数

Direct3DX ユーティリティ ライブラリにより提供されている算術ライブラリには、基本的な算術演算と複雑な 3D 算術演算の両方を計算する関数がある。

3D 算術アプリケーション関数は、以下のグループにまとめることができる。

カラー | D3DXColorAdd
 | D3DXColorAdjustContrast
 | D3DXColorAdjustSaturation
 | D3DXColorLerp
 | D3DXColorModulate
 | D3DXColorNegative
 | D3DXColorScale
 | D3DXColorSubtract
作成 | D3DXCreateMatrixStack
平面 | D3DXPlaneDot
 | D3DXPlaneDotCoord
 | D3DXPlaneDotNormal
 | D3DXPlaneIntersectLine
 | D3DXPlaneFromPointNormal
 | D3DXPlaneNormalize
 | D3DXPlaneFromPoints
 | D3DXPlaneTransform
クオータニオン | D3DXQuaternionBaryCentric
 | D3DXQuaternionConjugate
 | D3DXQuaternionDot
 | D3DXQuaternionExp
 | D3DXQuaternionIdentity
 | D3DXQuaternionInverse
 | D3DXQuaternionIsIdentity
 | D3DXQuaternionLength
 | D3DXQuaternionLengthSq
 | D3DXQuaternionLn
 | D3DXQuaternionMultiply
 | D3DXQuaternionNormalize
 | D3DXQuaternionRotationAxis
 | D3DXQuaternionRotationMatrix
 | D3DXQuaternionRotationYawPitchRoll
 | D3DXQuaternionSlerp
 | D3DXQuaternionSquad
 | D3DXQuaternionToAxisAngle
2D ベクトル | D3DXVec2Add
 | D3DXVec2BaryCentric
 | D3DXVec2CatmullRom
 | D3DXVec2CCW
 | D3DXVec2Dot
 | D3DXVec2Hermite
 | D3DXVec2Length
 | D3DXVec2LengthSq
 | D3DXVec2Lerp
 | D3DXVec2Maximize
 | D3DXVec2Minimize
 | D3DXVec2Normalize
 | D3DXVec2Scale
 | D3DXVec2Subtract
 | D3DXVec2Transform
 | D3DXVec2TransformCoord
 | D3DXVec2TransformNormal
3D ベクトル | D3DXVec3Add
 | D3DXVec3BaryCentric
 | D3DXVec3CatmullRom
 | D3DXVec3Cross
 | D3DXVec3Dot
 | D3DXVec3Hermite
 | D3DXVec3Length
 | D3DXVec3LengthSq
 | D3DXVec3Lerp
 | D3DXVec3Maximize
 | D3DXVec3Minimize
 | D3DXVec3Normalize
 | D3DXVec3Project
 | D3DXVec3Scale
 | D3DXVec3Subtract
 | D3DXVec3Transform
 | D3DXVec3TransformCoord
 | D3DXVec3TransformNormal
 | D3DXVec3Unproject
4D 行列 | D3DXMatrixAffineTransformation
 | D3DXMatrixfDeterminant
 | D3DXMatrixIdentity
 | D3DXMatrixInverse
 | D3DXMatrixIsIdentity
 | D3DXMatrixLookAtRH
 | D3DXMatrixLookAtLH
 | D3DXMatrixMultiply
 | D3DXMatrixOrthoRH
 | D3DXMatrixOrthoLH
 | D3DXMatrixOrthoOffCenterRH
 | D3DXMatrixOrthoOffCenterLH
 | D3DXMatrixPerspectiveRH
 | D3DXMatrixPerspectiveLH
 | D3DXMatrixPerspectiveFovRH
 | D3DXMatrixPerspectiveFovLH
 | D3DXMatrixPerspectiveOffCenterRH
 | D3DXMatrixPerspectiveOffCenterLH
 | D3DXMatrixReflect
 | D3DXMatrixRotationAxis
 | D3DXMatrixRotationQuaternion
 | D3DXMatrixRotationX
 | D3DXMatrixRotationY
 | D3DXMatrixRotationYawPitchRoll
 | D3DXMatrixRotationZ
 | D3DXMatrixScaling
 | D3DXMatrixShadow
 | D3DXMatrixTransformation
 | D3DXMatrixTranslation
 | D3DXMatrixTranspose
4D ベクトル | D3DXVec4Add
 | D3DXVec4BaryCentric
 | D3DXVec4CatmullRom
 | D3DXVec4Cross
 | D3DXVec4Dot
 | D3DXVec4Hermite
 | D3DXVec4Length
 | D3DXVec4LengthSq
 | D3DXVec4Lerp
 | D3DXVec4Maximize
 | D3DXVec4Minimize
 | D3DXVec4Normalize
 | D3DXVec4Scale
 | D3DXVec4Subtract
 | D3DXVec4Transform

注 すべての算術関数は、入力パラメータと出力パラメータの両方で同じオブジェクトを使用できる。また、出力パラメータは通常戻り値として返されるので、ある算術関数の出力を別の算術関数のパラメータとして使用できる。


D3DXColorAdd

2 種類のカラー値を加算して、新しいカラー値を作成する。

D3DXCOLOR* D3DXColorAdd(
  D3DXCOLOR* pOut,
  CONST D3DXCOLOR* pC1,
  CONST D3DXCOLOR* pC2
);

パラメータ

pOut
[in, out] 演算結果である D3DXCOLOR 構造体へのポインタ。
pC1
[in] 処理の基になる D3DXCOLOR 構造体へのポインタ。
pC2
[in] 処理の基になる D3DXCOLOR 構造体へのポインタ。

戻り値

2 つのカラー値の合計である D3DXCOLOR 構造体へのポインタを返す。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXColorAdd 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXColorModulate、D3DXColorSubtract


D3DXColorAdjustContrast

カラーのコントラストを調節する。

D3DXCOLOR* D3DXColorAdjustContrast(
  D3DXCOLOR* pOut,
  D3DXCOLOR* pC,
  FLOAT c
);

パラメータ

pOut
[in, out] 演算結果である D3DXCOLOR 構造体へのポインタ。
pC
[in] 処理の基になる D3DXCOLOR 構造体へのポインタ。
c
[in] コントラスト値。このパラメータは、50% グレーと指定カラー pC の間で線形補間する。c 値に制限値はない。このパラメータが 0 の場合、返される色は 50% グレーである。このパラメータが 1 の場合、返される色はオリジナル カラーである。

戻り値

この関数は、コントラスト調整結果の D3DXCOLOR 構造体へのポインタを返す。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXColorAdjustContrast 関数を別の関数のパラメータとして使用できる。

次の例で示すように、この関数は 50% グレーと指定コントラスト値の間で D3DXCOLOR 構造体の赤 (red)、緑 (green)、青 (blue) の色成分を補間する。

    pOut->r = 0.5f + c * (pC->r - 0.5f);

c が 0 より大きく 1 未満の場合、コントラストは小さくなる。c が 1 より大きい場合、コントラストは大きくなる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXColorAdjustSaturation


D3DXColorAdjustSaturation

カラーの彩度値を調節する。

D3DXCOLOR* D3DXColorAdjustSaturation(
  D3DXCOLOR* pOut,
  D3DXCOLOR* pC,
  FLOAT s
);

パラメータ

pOut
[in, out] 演算結果である D3DXCOLOR 構造体へのポインタ。
pC
[in] 処理の基になる D3DXCOLOR 構造体へのポインタ。
s
[in] 彩度値。このパラメータは、グレー スケールに変換された色とオリジナル カラー pC の間で線形補間する。s 値に制限値はない。s が 0 の場合、返される色はグレー スケールの色である。s が 1 の場合、返される色はオリジナル カラーである。

戻り値

この関数は、彩度調整結果の D3DXCOLOR 構造体へのポインタを返す。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXColorAdjustSaturation 関数を別の関数のパラメータとして使用できる。

次に示す例のように、この関数は未飽和色とあるカラーの間で D3DXCOLOR 構造体の赤 (red)、緑 (green)、青 (blue) の色成分を補間する。

    // 輝度に対する各成分の係数の適切な値。
    // ITU-R 勧告 BT.709 に記載された NTSC 標準に基づく。
    FLOAT grey = pC->r * 0.2125f + pC->g * 0.7154f + pC->b * 0.0721f;

    pOut->r = grey + s * (pC->r - grey);

s が 0 より大きく 1 未満の場合、彩度は小さくなる。s が 1 より大きい場合、彩度は大きくなる。

グレースケール カラーは次のようにして計算される。r = g = b = 0.2125*r + 0.7154*g + 0.0721*b

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXColorAdjustContrast


D3DXColorLerp

線形補間を使用してカラー値を作成する。

D3DXCOLOR* D3DXColorLerp(
  D3DXCOLOR* pOut,
  CONST D3DXCOLOR* pC1,
  CONST D3DXCOLOR* pC2,
  FLOAT s
);

パラメータ

pOut
[in, out] 演算結果である D3DXCOLOR 構造体へのポインタ。
pC1
[in] 処理の基になる D3DXCOLOR 構造体へのポインタ。
pC2
[in] 処理の基になる D3DXCOLOR 構造体へのポインタ。
s
[in] pC1 と pC2 の 2 つの色を両方とも 4D ベクトルとして処理し、それらの間で線形補間するパラメータ。s 値に制限値はない。

戻り値

この関数は、線形補間結果の D3DXCOLOR 構造体へのポインタを返す。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXColorLerp 関数を別の関数のパラメータとして使用できる。

次に示す例のように、この関数は 2 つの色の間で D3DXCOLOR 構造体の赤 (red)、緑 (green)、青 (blue) の色成分とアルファ成分を補間する。

    pOut->r = pC1->r + s * (pC2->r - pC1->r);

A カラーと B カラーの間で線形補間する場合に、s が 0 のとき、結果カラーは A となる。 s が 1 のとき、結果カラーは B となる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXColorModulate、D3DXColorNegative、D3DXColorScale


D3DXColorModulate

2 種類のカラーをブレンドする。

D3DXCOLOR* D3DXColorModulate(
  D3DXCOLOR* pOut,
  CONST D3DXCOLOR* pC1,
  CONST D3DXCOLOR* pC2
);

パラメータ

pOut
[in, out] 演算結果である D3DXCOLOR 構造体へのポインタ。
pC1
[in] 処理の基になる D3DXCOLOR 構造体へのポインタ。
pC2
[in] 処理の基になる D3DXCOLOR 構造体へのポインタ。

戻り値

この関数は、ブレンド結果である D3DXCOLOR 構造体へのポインタを返す。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXColorModulate 関数を別の関数のパラメータとして使用できる。

次の例に示すように、この関数は対応する 2 つの色成分の積を求めて 2 種類のカラーをブレンドする。

    pOut->r = pC1->r * pC2->r;

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXColorLerp、D3DXColorNegative、D3DXColorScale


D3DXColorNegative

あるカラー値の負の色を作成する。

D3DXCOLOR* D3DXColorNegative(
  D3DXCOLOR* pOut,
  CONST D3DXCOLOR* pC
);

パラメータ

pOut
[in, out] 演算結果である D3DXCOLOR 構造体へのポインタ。
pC
[in] 処理の基になる D3DXCOLOR 構造体へのポインタ。

戻り値

この関数は、カラー値の負の色である D3DXCOLOR 構造体へのポインタを返す。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXColorNegative 関数を別の関数のパラメータとして使用できる。

次の例に示すように、この関数は D3DXCOLOR 構造体の色成分から 1.0 を減算することで、負のカラー値を返す。

    pOut->r = 1.0f - pC->r;

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXColorLerp、D3DXColorModulate、D3DXColorScale


D3DXColorScale

カラー値をスケーリングする。

D3DXCOLOR* D3DXColorScale(
  D3DXCOLOR* pOut,
  CONST D3DXCOLOR* pC,
  FLOAT s
);

パラメータ

pOut
[in, out] 演算結果である D3DXCOLOR 構造体へのポインタ。
pC
[in] 処理の基になる D3DXCOLOR 構造体へのポインタ。
s
[in] スケーリング係数。色を 4D ベクトルのように処理して、それをスケーリングする。s 値に制限値はない。s が 1 の場合、返される色はオリジナル カラーである。

戻り値

この関数は、スケーリングされたカラー値である D3DXCOLOR 構造体へのポインタを返す。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXColorScale 関数を別の関数のパラメータとして使用できる。

次の例に示すように、この関数は、D3DXCOLOR 構造体の色成分に指定されたスケーリング係数を乗算することで、スケーリングしたカラー値を算出する。

    pOut->r = pC->r * s;

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXColorLerp、D3DXColorModulate、D3DXColorNegative


D3DXColorSubtract

2 種類のカラー値の間で減算を行って、新しいカラー値を作成する。

D3DXCOLOR* D3DXColorSubtract(
  D3DXCOLOR* pOut,
  CONST D3DXCOLOR* pC1,
  CONST D3DXCOLOR* pC2
);

パラメータ

pOut
[in, out] 演算結果である D3DXCOLOR 構造体へのポインタ。
pC1
[in] 処理の基になる D3DXCOLOR 構造体へのポインタ。
pC2
[in] 処理の基になる D3DXCOLOR 構造体へのポインタ。

戻り値

この関数は、2 つのカラー値の差分である D3DXCOLOR 構造体へのポインタを返す。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXColorSubtract 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXColorAdd


D3DXCreateMatrixStack

ID3DXMatrixStack インターフェイスのインスタンスを作成する。

HRESULT D3DXCreateMatrixStack(
  DWORD Flags,
  ID3DXMatrixStack** ppStack
);

パラメータ

Flags
[in] 実装されていない。0 を指定すること。
ppStack
[out] 関数が成功した場合は、ID3DXMatrixStack インターフェイス ポインタが設定されるポインタのアドレス。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXMatrixAffineTransformation

アフィン変換行列を作成する。

D3DXMATRIX* D3DXMatrixAffineTransformation(
  D3DXMATRIX* pOut,
  FLOAT scaling,
  CONST D3DXVECTOR3* pRotationCenter,
  CONST D3DXQUATERNION* pRotation,
  CONST D3DXVECTOR3* pTranslation
);

パラメータ

pOut
[in, out] 演算結果である D3DXMATRIX 構造体へのポインタ。
scaling
[in] スケーリング係数。
pRotationCenter
[in] 回転の中心を識別するポイントである D3DXVECTOR3 構造体へのポインタ。この引数が NULL の場合は、回転しないと見なされる。
pRotation
[in] 回転を指定する D3DXQUATERNION 構造体へのポインタ。この引数が NULL の場合は、回転しないと見なされる。
pTranslation
[in] 平行移動を表す D3DXVECTOR3 構造体へのポインタ。この引数が NULL の場合は、平行移動しないと見なされる。

戻り値

アフィン変換行列である D3DXMATRIX 構造体へのポインタ。

注意

D3DXMatrixAffineTransformation 関数は、Ms * Mrc-1 * Mr * Mrc * Mt 式によりアフィン変換行列を算出する。ここで、Ms はスケール行列、Mrc は回転行列の中心、Mr は回転行列、Mt は平行移動行列である。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixAffineTransformation 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXMatrixfDeterminant

行列の行列式を返す。

FLOAT D3DXMatrixfDeterminant(
  CONST D3DXMATRIX* pM
);

パラメータ

pM
[in] 処理の基になる D3DXMATRIX 構造体へのポインタ。

戻り値

行列の値、行列式。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXMatrixIdentity

単位行列を作成する。

D3DXMATRIX* D3DXMatrixIdentity(
  D3DXMATRIX* pOut
);

パラメータ

pOut
[in, out] 演算結果である D3DXMATRIX 構造体へのポインタ。

戻り値

単位行列である D3DXMATRIX 構造体へのポインタ。

注意

単位行列は、[1,1][2,2][3,3][4,4] 係数に 1 が設定されていることを除いて、すべての係数が 0 の行列である。 単位行列は、頂点に適用されてもそれらが変更されないという点で特別である。単位行列は、頂点値を変更して回転、平行移動、および 4 × 4 行列で表現できるその他の変換を行う行列の起点として使用される。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixIdentity 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXMatrixIsIdentity


D3DXMatrixInverse

行列の逆元を算出する。

D3DXMATRIX* D3DXMatrixInverse(
  D3DXMATRIX* pOut,
  FLOAT* pDeterminant,
  CONST D3DXMATRIX* pM
);

パラメータ

pOut
[in, out] 演算結果である D3DXMATRIX 構造体へのポインタ。
pDeterminant
[in, out] この関数が戻った後の、指定された行列 pM の行列値である FLOAT 値に対するポインタ。
pM
[in] 処理の基になる D3DXMATRIX 構造体へのポインタ。

戻り値

行列の逆元である D3DXMATRIX 構造体へのポインタ。

注意

この関数では、任意の行列を使用できる。

行列の逆変換が失敗すると、D3DXMatrixInverse 関数から NULL が返される。pDeterminant パラメータが NULL 以外の場合は pM の行列値が返される。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixInverse 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXMatrixIsIdentity

行列が単位行列であるかどうかを判定する。

BOOL D3DXMatrixIsIdentity(
  CONST D3DXMATRIX* pM
);

パラメータ

pM
[in] 単位行列であるかどうかを判定する D3DXMATRIX 構造体へのポインタ。

戻り値

行列が単位行列である場合、この関数は TRUE を返す。それ以外の場合は、FALSE を返す。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXMatrixIdentity


D3DXMatrixLookAtRH

右手座標系ビュー行列を作成する。

D3DXMATRIX* D3DXMatrixLookAtRH(
  D3DXMATRIX* pOut,
  CONST D3DXVECTOR3* pEye,
  CONST D3DXVECTOR3* pAt,
  CONST D3DXVECTOR3* pUp
);

パラメータ

pOut
[in, out] 演算結果である D3DXMATRIX 構造体へのポインタ。
pEye
[in] 視点を定義した D3DXVECTOR3 構造体へのポインタ。この値は、平行移動に使用される。
pAt
[in] カメラの注視対象を定義した D3DXVECTOR3 構造体へのポインタ。
pUp
[in] カレント ワールドの上方、一般には [0, 1, 0] を定義した D3DXVECTOR3 構造体へのポインタ。

戻り値

右手座標系ビュー行列である D3DXMATRIX 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixLookAtRH 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXMatrixLookAtLH


D3DXMatrixLookAtLH

左手座標系ビュー行列を作成する。

D3DXMATRIX* D3DXMatrixLookAtLH(
  D3DXMATRIX* pOut,
  CONST D3DXVECTOR3* pEye,
  CONST D3DXVECTOR3* pAt,
  CONST D3DXVECTOR3* pUp
);

パラメータ

pOut
[in, out] 演算結果である D3DXMATRIX 構造体へのポインタ。
pEye
[in] 視点を定義した D3DXVECTOR3 構造体へのポインタ。この値は、平行移動に使用される。
pAt
[in] カメラの注視対象を定義した D3DXVECTOR3 構造体へのポインタ。
pUp
[in] カレント ワールドの上方、一般には [0, 1, 0] を定義した D3DXVECTOR3 構造体へのポインタ。

戻り値

左手座標系ビュー行列である D3DXMATRIX 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixLookAtLH 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXMatrixLookAtRH


D3DXMatrixMultiply

2 つの行列の積を算出する。

D3DXMATRIX* D3DXMatrixMultiply(
  D3DXMATRIX* pOut,
  CONST D3DXMATRIX* pM1,
  CONST D3DXMATRIX* pM2
);

パラメータ

pOut
[in, out] 演算結果である D3DXMATRIX 構造体へのポインタ。
pM1
[in] 処理の基になる D3DXMATRIX 構造体へのポインタ。
pM2
[in] 処理の基になる D3DXMATRIX 構造体へのポインタ。

戻り値

2 つの行列の積である D3DXMATRIX 構造体へのポインタ。

注意

結果は、変換 M1 後の変換 M2 の結果を表す (Out = M1 * M2)。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixMultiply 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXQuaternionMultiply


D3DXMatrixOrthoRH

右手座標系正射影行列を作成する。

D3DXMATRIX* D3DXMatrixOrthoRH(
  D3DXMATRIX* pOut,
  FLOAT w,
  FLOAT h,
  FLOAT zn,
  FLOAT zf
);

パラメータ

pOut
[in, out] 演算結果である D3DXMATRIX 構造体へのポインタ。
w
[in] ビュー ボリュームの幅。
h
[in] ビュー ボリュームの高さ。
zn
[in] ビュー ボリュームの最小 z 値。
zf
[in] ビュー ボリュームの最大 z 値。

戻り値

右手座標系正射影行列である D3DXMATRIX 構造体へのポインタ。

注意

正射影行列は反転可能な行列である。その行列の反転は、行列の転置に等しい。

D3DXMatrixOrthoRH 関数のパラメータはすべて、カメラ空間の距離である。このパラメータは、ビュー ボリュームのディメンジョンを記述する。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixOrthoRH 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXMatrixOrthoLH、D3DXMatrixOrthoOffCenterRH、D3DXMatrixOrthoOffCenterLH


D3DXMatrixOrthoLH

左手座標系正射影行列を作成する。

D3DXMATRIX* D3DXMatrixOrthoLH(
  D3DXMATRIX* pOut,
  FLOAT w,
  FLOAT h,
  FLOAT zn,
  FLOAT zf
);

パラメータ

pOut
[in, out] 演算結果である D3DXMATRIX 構造体へのポインタ。
w
[in] ビュー ボリュームの幅。
h
[in] ビュー ボリュームの高さ。
zn
[in] ビュー ボリュームの最小 z 値。
zf
[in] ビュー ボリュームの最大 z 値。

戻り値

左手座標系正射影行列である D3DXMATRIX 構造体へのポインタ。

注意

正射影行列は反転可能な行列である。その行列の反転は、行列の転置に等しい。

D3DXMatrixOrthoLH 関数のパラメータはすべて、カメラ空間の距離である。このパラメータは、ビュー ボリュームのディメンジョンを記述する。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixOrthoLH 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXMatrixOrthoRH、D3DXMatrixOrthoOffCenterRH、D3DXMatrixOrthoOffCenterLH


D3DXMatrixOrthoOffCenterRH

カスタマイズした右手座標系正射影行列を作成する。

D3DXMATRIX* D3DXMatrixOrthoOffCenterRH(
  D3DXMATRIX* pOut,
  FLOAT l,
  FLOAT r,
  FLOAT t,
  FLOAT b,
  FLOAT zn,
  FLOAT zf
);

パラメータ

pOut
[in, out] 演算結果である D3DXMATRIX 構造体へのポインタ。
l
[in] ビュー ボリュームの最小 x 値。
r
[in] ビュー ボリュームの最大 x 値。
t
[in] ビュー ボリュームの最小 y 値。
b
[in] ビュー ボリュームの最大 y 値。
zn
[in] ビュー ボリュームの最小 z 値。
zf
[in] ビュー ボリュームの最大 z 値。

戻り値

カスタマイズした右手座標系正射影行列である D3DXMATRIX 構造体へのポインタ。

注意

正射影行列は反転可能な行列である。その行列の反転は、行列の転置に等しい。

D3DXMatrixOrthoRH 関数は、D3DXMatrixOrthoOffCenterRH 関数の特殊なケースである。D3DXMatrixOrthoOffCenterRH を使用して同じ射影を作成するには、l = -w/2、r = w/2、b = -h/2、t = h/2 という値を使用すること。

D3DXMatrixOrthoOffCenterRH 関数のパラメータはすべて、カメラ空間の距離である。このパラメータは、ビュー ボリュームのディメンジョンを記述する。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixOrthoOffCenterRH 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXMatrixOrthoRH、D3DXMatrixOrthoLH、D3DXMatrixOrthoOffCenterLH


D3DXMatrixOrthoOffCenterLH

カスタマイズした左手座標系正射影行列を作成する。

D3DXMATRIX* D3DXMatrixOrthoOffCenterLH(
  D3DXMATRIX* pOut,
  FLOAT l,
  FLOAT r,
  FLOAT t,
  FLOAT b,
  FLOAT zn,
  FLOAT zf
);

パラメータ

pOut
[in, out] 演算結果である D3DXMATRIX 構造体へのポインタ。
l
[in] ビュー ボリュームの最小 x 値。
r
[in] ビュー ボリュームの最大 x 値。
t
[in] ビュー ボリュームの最小 y 値。
b
[in] ビュー ボリュームの最大 y 値。
zn
[in] ビュー ボリュームの最小 z 値。
zf
[in] ビュー ボリュームの最大 z 値。

戻り値

カスタマイズした左手座標系正射影行列である D3DXMATRIX 構造体へのポインタ。

注意

正射影行列は反転可能な行列である。その行列の反転は、行列の転置に等しい。

D3DXMatrixOrthoLH 関数は、D3DXMatrixOrthoOffCenterLH 関数の特殊なケースである。D3DXMatrixOrthoOffCenterLH を使用して同じ射影を作成するには、l = -w/2、r = w/2、b = -h/2、t = h/2 という値を使用すること。

D3DXMatrixOrthoOffCenterLH 関数のパラメータはすべて、カメラ空間の距離である。このパラメータは、ビュー ボリュームのディメンジョンを記述する。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixOrthoOffCenterLH 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXMatrixOrthoRH、D3DXMatrixOrthoLH、D3DXMatrixOrthoOffCenterRH


D3DXMatrixPerspectiveRH

右手座標系パースペクティブ射影行列を作成する。

D3DXMATRIX* D3DXMatrixPerspectiveRH(
  D3DXMATRIX* pOut,
  FLOAT w,
  FLOAT h,
  FLOAT zn,
  FLOAT zf
);

パラメータ

pOut
[in, out] 演算結果である D3DXMATRIX 構造体へのポインタ。
w
[in] 近くのビュー プレーンでのビュー ボリュームの幅。
h
[in] 近くのビュー プレーンでのビュー ボリュームの高さ。
zn
[in] 近くのビュー プレーンの z 値。
zf
[in] 遠くのビュー プレーンの z 値。

戻り値

右手座標系パースペクティブ射影行列である D3DXMATRIX 構造体へのポインタ。

注意

D3DXMatrixPerspectiveRH 関数のパラメータはすべて、カメラ空間の距離である。このパラメータは、ビュー ボリュームのディメンジョンを記述する。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixPerspectiveRH 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXMatrixPerspectiveLH、D3DXMatrixPerspectiveFovRH、D3DXMatrixPerspectiveFovLH、D3DXMatrixPerspectiveOffCenterRH、D3DXMatrixPerspectiveOffCenterLH


D3DXMatrixPerspectiveFovLH

視野 (FOV) に基づいて、左手座標系パースペクティブ射影行列を作成する。

D3DXMATRIX* D3DXMatrixPerspectiveFovLH(
  D3DXMATRIX* pOut,
  FLOAT fovy,
  FLOAT Aspect,
  FLOAT zn,
  FLOAT zf
);

パラメータ

pOut
[in, out] 演算結果である D3DXMATRIX 構造体へのポインタ。
fovy
[in] 視野 (ラジアン単位)。
Aspect
[in] アスペクト比。
zn
[in] 近くのビュー プレーンの z 値。
zf
[in] 遠くのビュー プレーンの z 値。

戻り値

左手座標系パースペクティブ射影行列である D3DXMATRIX 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixPerspectiveFovLH 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXMatrixPerspectiveRH、D3DXMatrixPerspectiveLH、D3DXMatrixPerspectiveFovRH、D3DXMatrixPerspectiveOffCenterRH、D3DXMatrixPerspectiveOffCenterLH


D3DXMatrixPerspectiveFovRH

視野 (FOV) に基づいて、右手座標系パースペクティブ射影行列を作成する。

D3DXMATRIX* D3DXMatrixPerspectiveFovRH(
  D3DXMATRIX* pOut,
  FLOAT fovy,
  FLOAT Aspect,
  FLOAT zn,
  FLOAT zf
);

パラメータ

pOut
[in, out] 演算結果である D3DXMATRIX 構造体へのポインタ。
fovy
[in] 視野 (ラジアン単位)。
Aspect
[in] アスペクト比。
zn
[in] 近くのビュー プレーンの z 値。
zf
[in] 遠くのビュー プレーンの z 値。

戻り値

右手座標系パースペクティブ射影行列である D3DXMATRIX 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixPerspectiveFovRH 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXMatrixPerspectiveRH、D3DXMatrixPerspectiveLH、D3DXMatrixPerspectiveFovLH、D3DXMatrixPerspectiveOffCenterRH、D3DXMatrixPerspectiveOffCenterLH


D3DXMatrixPerspectiveLH

左手座標系パースペクティブ射影行列を作成する。

D3DXMATRIX* D3DXMatrixPerspectiveLH(
  D3DXMATRIX* pOut,
  FLOAT w,
  FLOAT h,
  FLOAT zn,
  FLOAT zf
);

パラメータ

pOut
[in, out] 演算結果である D3DXMATRIX 構造体へのポインタ。
w
[in] 近くのビュー プレーンでのビュー ボリュームの幅。
h
[in] 近くのビュー プレーンでのビュー ボリュームの高さ。
zn
[in] 近くのビュー プレーンの z 値。
zf
[in] 遠くのビュー プレーンの z 値。

戻り値

左手座標系パースペクティブ射影行列である D3DXMATRIX 構造体へのポインタ。

注意

D3DXMatrixPerspectiveLH 関数のパラメータはすべて、カメラ空間の距離である。このパラメータは、ビュー ボリュームのディメンジョンを記述する。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixPerspectiveLH 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXMatrixPerspectiveRH、D3DXMatrixPerspectiveFovRH、D3DXMatrixPerspectiveFovLH、D3DXMatrixPerspectiveOffCenterRH、D3DXMatrixPerspectiveOffCenterLH


D3DXMatrixPerspectiveOffCenterRH

カスタマイズした右手座標系パースペクティブ射影行列を作成する。

D3DXMATRIX* D3DXMatrixPerspectiveOffCenterRH(
  D3DXMATRIX* pOut,
  FLOAT l,
  FLOAT r,
  FLOAT t,
  FLOAT b,
  FLOAT zn,
  FLOAT zf
);

パラメータ

pOut
[in, out] 操作結果の D3DXMATRIX 構造体へのポインタ。
l
[in] ビュー ボリュームの最小 X 値。
r
[in] ビュー ボリュームの最大 X 値。
t
[in] ビュー ボリュームの最小 Y 値。
b
[in] ビュー ボリュームの最大 Y 値。
zn
[in] ビュー ボリュームの最小 Z 値。
zf
[in] ビュー ボリュームの最大 Z 値。

戻り値

右手座標系パースペクティブ射影行列である D3DXMATRIX 構造体へのポインタ。

注意

D3DXMatrixPerspectiveOffCenterRH 関数のパラメータはすべて、カメラ空間の距離である。このパラメータは、ビュー ボリュームのディメンジョンを記述する。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixPerspectiveOffCenterRH 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXMatrixPerspectiveRH、D3DXMatrixPerspectiveLH、D3DXMatrixPerspectiveFovRH、D3DXMatrixPerspectiveFovLH、D3DXMatrixPerspectiveOffCenterLH


D3DXMatrixPerspectiveOffCenterLH

カスタマイズした左手座標系パースペクティブ射影行列を作成する。

D3DXMATRIX* D3DXMatrixPerspectiveOffCenterLH(
  D3DXMATRIX* pOut,
  FLOAT l,
  FLOAT r,
  FLOAT t,
  FLOAT b,
  FLOAT zn,
  FLOAT zf
);

パラメータ

pOut
[in, out] 操作結果の D3DXMATRIX 構造体へのポインタ。
l
[in] ビュー ボリュームの最小 X 値。
r
[in] ビュー ボリュームの最大 X 値。
t
[in] ビュー ボリュームの最小 Y 値。
b
[in] ビュー ボリュームの最大 Y 値。
zn
[in] ビュー ボリュームの最小 Z 値。
zf
[in] ビュー ボリュームの最大 Z 値。

戻り値

左手座標系パースペクティブ射影行列である D3DXMATRIX 構造体へのポインタ。

注意

D3DXMatrixPerspectiveOffCenterLH 関数のパラメータはすべて、カメラ空間の距離である。このパラメータは、ビュー ボリュームのディメンジョンを記述する。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixPerspectiveOffCenterLH 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXMatrixPerspectiveRH、D3DXMatrixPerspectiveLH、D3DXMatrixPerspectiveFovRH、D3DXMatrixPerspectiveFovLH、D3DXMatrixPerspectiveOffCenterRH


D3DXMatrixReflect

平面の座標系を反転した行列を作成する。

D3DXMATRIX* D3DXMatrixReflect(
  D3DXMATRIX* pOut,
  CONST D3DXPLANE* pPlane
);

パラメータ

pOut
[in, out] 演算結果である D3DXMATRIX 構造体へのポインタ。
pPlane
[in] 処理の基になる D3DXPLANE 構造体へのポインタ。

戻り値

ソースの平面の座標系を反転した D3DXMATRIX 構造体へのポインタ。

注意

この関数は、平面方程式を正規化してから、反転する行列を作成する。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixReflect 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXMatrixRotationAxis

任意の軸を回転軸として回転した行列を作成する。

D3DXMATRIX* D3DXMatrixRotationAxis(
  D3DXMATRIX* pOut,
  CONST D3DXVECTOR3* pV,
  FLOAT Angle
);

パラメータ

pOut
[in, out] 演算結果である D3DXMATRIX 構造体へのポインタ。
pV
[in] 軸の角度を識別する D3DXVECTOR3 構造体へのポインタ。
Angle
[in] 回転の角度 (ラジアン単位)。角度は、回転軸から原点に向かって時計回りに計測される。

戻り値

指定された軸を回転軸として回転した D3DXMATRIX 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixRotationAxis 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXMatrixRotationQuaternion、D3DXMatrixRotationX、D3DXMatrixRotationY、D3DXMatrixRotationYawPitchRoll、D3DXMatrixRotationZ


D3DXMatrixRotationQuaternion

クオータニオンから行列を作成する。

D3DXMATRIX* D3DXMatrixRotationQuaternion(
  D3DXMATRIX* pOut,
  CONST D3DXQUATERNION* pQ
);

パラメータ

pOut
[in, out] 演算結果である D3DXMATRIX 構造体へのポインタ。
pQ
[in] 処理の基になる D3DXQUATERNION 構造体へのポインタ。

戻り値

ソースのクオータニオンから構築された D3DXMATRIX 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixRotationQuaternion 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXMatrixRotationAxis、D3DXMatrixRotationX、D3DXMatrixRotationY、D3DXMatrixRotationYawPitchRoll、D3DXMatrixRotationZ


D3DXMatrixRotationX

x 軸を回転軸として回転した行列を作成する。

D3DXMATRIX* D3DXMatrixRotationX(
  D3DXMATRIX* pOut,
  FLOAT Angle
);

パラメータ

pOut
[in, out] 演算結果である D3DXMATRIX 構造体へのポインタ。
Angle
[in] 回転の角度 (ラジアン単位)。角度は、回転軸から原点に向かって時計回りに計測される。

戻り値

x 軸を回転軸として回転した D3DXMATRIX 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixRotationX 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXMatrixRotationAxis、D3DXMatrixRotationQuaternion、D3DXMatrixRotationY、D3DXMatrixRotationYawPitchRoll、D3DXMatrixRotationZ


D3DXMatrixRotationY

y 軸を回転軸として回転した行列を作成する。

D3DXMATRIX* D3DXMatrixRotationY(
  D3DXMATRIX* pOut,
  FLOAT Angle
);

パラメータ

pOut
[in, out] 演算結果である D3DXMATRIX 構造体へのポインタ。
Angle
[in] 回転の角度 (ラジアン単位)。角度は、回転軸から原点に向かって時計回りに計測される。

戻り値

y 軸を回転軸として回転した D3DXMATRIX 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixRotationY 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXMatrixRotationAxis、D3DXMatrixRotationQuaternion、D3DXMatrixRotationX、D3DXMatrixRotationYawPitchRoll、D3DXMatrixRotationZ


D3DXMatrixRotationYawPitchRoll

ヨー、ピッチ、およびロールを指定して行列を作成する。

D3DXMATRIX* D3DXMatrixRotationYawPitchRoll(
  D3DXMATRIX* pOut,
  FLOAT Yaw,
  FLOAT Pitch,
  FLOAT Roll,
);

パラメータ

pOut
[in, out] 演算結果である D3DXMATRIX 構造体へのポインタ。
Yaw
[in] y 軸のヨー (ラジアン単位)。
Pitch
[in] x 軸のピッチ (ラジアン単位)。
Roll
[in] z 軸のロール (ラジアン単位)。

戻り値

指定されたヨー、ピッチ、およびロールを持つ D3DXMATRIX 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixRotationYawPitchRoll 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXMatrixRotationAxis、D3DXMatrixRotationQuaternion、D3DXMatrixRotationX、D3DXMatrixRotationY、D3DXMatrixRotationZ


D3DXMatrixRotationZ

z 軸を回転軸として回転した行列を作成する。

D3DXMATRIX* D3DXMatrixRotationZ(
  D3DXMATRIX* pOut,
  FLOAT Angle
);

パラメータ

pOut
[in, out] 演算結果である D3DXMATRIX 構造体へのポインタ。
Angle
[in] 回転の角度 (ラジアン単位)。角度は、回転軸から原点に向かって時計回りに計測される。

戻り値

z 軸を回転軸として回転した D3DXMATRIX 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixRotationZ 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXMatrixRotationAxis、D3DXMatrixRotationQuaternion、D3DXMatrixRotationX、D3DXMatrixRotationY、D3DXMatrixRotationYawPitchRoll


D3DXMatrixScaling

x 軸、y 軸、z 軸に沿ってスケーリングした行列を作成する。

D3DXMATRIX* D3DXMatrixScaling(
  D3DXMATRIX* pOut,
  FLOAT sx,
  FLOAT sy,
  FLOAT sz,
);

パラメータ

pOut
[in, out] 演算結果である D3DXMATRIX 構造体へのポインタ。
sx
[in] x 軸に沿って適用されるスケーリング係数。
sy
[in] y 軸に沿って適用されるスケーリング係数。
sz
[in] z 軸に沿って適用されるスケーリング係数。

戻り値

スケーリングされた行列である D3DXMATRIX 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixScaling 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXMatrixShadow

ジオメトリを平面に射影する行列を作成する。

D3DXMATRIX* D3DXMatrixShadow(
  D3DXMATRIX* pOut,
  CONST D3DXVECTOR4* pLight,
  CONST D3DXPLANE* pPlane
);

パラメータ

pOut
[in, out] 演算結果である D3DXMATRIX 構造体へのポインタ。
pLight
[in] ライトの位置を記述した D3DXVECTOR4 構造体へのポインタ。
pPlane
[in] 処理の基になる D3DXPLANE 構造体へのポインタ。

戻り値

ジオメトリを平面に射影する D3DXMATRIX 構造体へのポインタ。

注意

D3DXMatrixShadow 関数は、ライトから影を射影するように、ジオメトリを平面に射影する。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixShadow 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXMatrixTransformation

トランスフォーム行列を作成する。

D3DXMATRIX* D3DXMatrixTransformation(
  D3DXMATRIX* pOut,
  CONST D3DXVECTOR3* pScalingCenter,
  CONST D3DXQUATERNION* pScalingRotation,
  CONST D3DXVECTOR3* pScaling,
  CONST D3DXVECTOR3* pRotationCenter,
  CONST D3DXQUATERNION* pRotation,
  CONST D3DXVECTOR3* pTranslation,
);

パラメータ

pOut
[in, out] 演算結果である D3DXMATRIX 構造体へのポインタ。
pScalingCenter
[in] スケーリングの中心点を識別する D3DXVECTOR3 構造体へのポインタ。この引数が NULL の場合は、スケールしないと見なされる。
pScalingRotation
[in] スケーリングの回転を指定する D3DXQUATERNION 構造体へのポインタ。 この引数が NULL の場合は、スケールしないと見なされる。
pScaling
[in] スケーリング ベクトルである D3DXVECTOR3 構造体へのポインタ。この引数が NULL の場合は、スケールしないと見なされる。
pRotationCenter
[in] 回転の中心を識別する D3DXVECTOR3 構造体へのポインタ。この引数が NULL の場合は、回転しないと見なされる。
pRotation
[in] 回転を指定する D3DXQUATERNION 構造体へのポインタ。この引数が NULL の場合は、回転しないと見なされる。
pTranslation
[in] 平行移動を表す D3DXVECTOR3 構造体へのポインタ。この引数が NULL の場合は、平行移動しないと見なされる。

戻り値

トランスフォーム行列である D3DXMATRIX 構造体へのポインタ。

注意

D3DXMatrixTransformation 関数は、Msc-1 * Msr-1 * Ms * Msr * Msc * Mrc-1 * Mr * Mrc * Mt という式によりトランスフォーム行列を計算する。 ただし、Msc は中心のスケーリング行列、Msr はスケーリング回転行列、Ms はスケーリング行列、Mrc は回転行列の中心、Mr は回転行列、Mt は平行移動行列である。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixTransformation 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXMatrixAffineTransformation


D3DXMatrixTranslation

オフセットを指定して行列を作成する。

D3DXMATRIX* D3DXMatrixTranslation(
  D3DXMATRIX* pOut,
  FLOAT x,
  FLOAT y,
  FLOAT z,
);

パラメータ

pOut
[in, out] 演算結果である D3DXMATRIX 構造体へのポインタ。
x
[in] x 座標のオフセット。
y
[in] y 座標のオフセット。
z
[in] z 座標のオフセット。

戻り値

平行移動された行列である D3DXMATRIX 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixTranslation 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXMatrixTranspose

行列の転置行列を返す。

D3DXMATRIX* D3DXMatrixTranspose(
  D3DXMATRIX* pOut,
  CONST D3DXMATRIX* pM
);

パラメータ

pOut
[in, out] 演算結果である D3DXMATRIX 構造体へのポインタ。
pM
[in] 処理の基になる D3DXMATRIX 構造体へのポインタ。

戻り値

行列の転置行列である D3DXMATRIX 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXMatrixTranspose 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXPlaneDot

平面と 4D ベクトルの内積を算出する。

FLOAT D3DXPlaneDot(
  CONST D3DXPLANE* pP,
  CONST D3DXVECTOR4* pV
);

パラメータ

pP
[in] 処理の基になる D3DXPLANE 構造体へのポインタ。
pV
[in] D3DXVECTOR4 構造体へのポインタ。

戻り値

平面と 4D ベクトルの内積。

注意

平面 (a, b, c, d) と 4D ベクトル (x, y, z, w) を指定した場合、この関数の戻り値は a*x + b*y + c*z + d*w となる。 D3DXPlaneDot 関数は、平面と同次座標の関係を判断するときに有用である。たとえば、この関数を使用すれば、特定の座標が特定の平面上にあるかどうか、または特定の座標が特定の平面のどちら側にあるかを判断できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXPlaneDotCoord、D3DXPlaneDotNormal


D3DXPlaneDotCoord

平面と 3D ベクトルの内積を算出する。ベクトルの w パラメータは、1 であると見なされる。

FLOAT D3DXPlaneDotCoord(
  CONST D3DXPLANE* pP,
  CONST D3DXVECTOR3* pV
);

パラメータ

pP
[in] 処理の基になる D3DXPLANE 構造体へのポインタ。
pV
[in] 処理の基になる D3DXVECTOR3 構造体へのポインタ。

戻り値

平面と 3D ベクトルの内積。

注意

平面 (a, b, c, d) と 3D ベクトル (x, y, z) を指定した場合、この関数の戻り値は a*x + b*y + c*z + d*1 となる。 D3DXPlaneDotCoord 関数は、平面と 3D 空間の座標の関係を判断するときに有用である。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXPlaneDot、D3DXPlaneDotNormal


D3DXPlaneDotNormal

平面と 3D ベクトルの内積を算出する。ベクトルの w パラメータは、0 であると見なされる。

FLOAT D3DXPlaneDotNormal(
  CONST D3DXPLANE* pP,
  CONST D3DXVECTOR3* pV
);

パラメータ

pP
[in] 処理の基になる D3DXPLANE 構造体へのポインタ。
pV
[in] 処理の基になる D3DXVECTOR3 構造体へのポインタ。

戻り値

平面と 3D ベクトルの内積。

注意

平面 (a, b, c, d) と 3D ベクトル (x, y, z) を指定した場合、この関数の戻り値は a*x + b*y + c*z + d*0 となる。 D3DXPlaneDotNormal 関数は、平面の法線と別の平面の角度を計算するときに有用である。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXPlaneDot、D3DXPlaneDotCoord


D3DXPlaneFromPointNormal

ポイントと法線から平面を作成する。

D3DXPLANE* D3DXPlaneFromPointNormal(
  D3DXPLANE* pOut,
  CONST D3DXVECTOR3* pPoint,
  CONST D3DXVECTOR3* pNormal
);

パラメータ

pOut
[in, out] 演算結果である D3DXPLANE 構造体へのポインタ。
pPoint
[in] 平面の作成に使用するポイントを定義する D3DXVECTOR3 構造体へのポインタ。
pNormal
[in] 平面の作成に使用する法線を定義する D3DXVECTOR3 構造体へのポインタ。

戻り値

ポイントと法線から作成した D3DXPLANE 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXPlaneFromPointNormal 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXPlaneFromPoints


D3DXPlaneFromPoints

3 つの点から平面を作成する。

D3DXPLANE* D3DXPlaneFromPoints(
  D3DXPLANE* pOut,
  CONST D3DXVECTOR3* pV1,
  CONST D3DXVECTOR3* pV2,
  CONST D3DXVECTOR3* pV3
);

パラメータ

pOut
[in, out] 演算結果である D3DXPLANE 構造体へのポインタ。
pV1
[in] 平面の作成に使用する点のうちの 1 つを定義する D3DXVECTOR3 構造体へのポインタ。
pV2
[in] 平面の作成に使用する点のうちの 1 つを定義する D3DXVECTOR3 構造体へのポインタ。
pV3
[in] 平面の作成に使用する点のうちの 1 つを定義する D3DXVECTOR3 構造体へのポインタ。

戻り値

指定された点から作成した D3DXPLANE 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXPlaneFromPoints 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXPlaneFromPointNormal


D3DXPlaneIntersectLine

平面と直線の交点を検索する。

D3DXVECTOR3* D3DXPlaneIntersectLine(
  D3DXVECTOR3* pOut,
  CONST D3DXPLANE* pP,
  CONST D3DXVECTOR3* pV1,
  CONST D3DXVECTOR3* pV2
);

パラメータ

pOut
[in, out] 指定された平面と直接の交点を識別する D3DXVECTOR3 構造体へのポインタ。
pP
[in] 処理の基になる D3DXPLANE 構造体へのポインタ。
pV1
[in] 起点を定義した、処理の基になる D3DXVECTOR3 構造体へのポインタ。
pV2
[in] 終点を定義した、処理の基になる D3DXVECTOR3 構造体へのポインタ。

戻り値

指定された平面と直線の交点である D3DXVECTOR3 構造体へのポインタ。

注意

直線が平面に対して平行の場合、NULL が返される。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXPlaneIntersectLine 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXPlaneNormalize

正規化した平面を返す。

D3DXPLANE* D3DXPlaneNormalize(
  D3DXPLANE* pOut,
  CONST D3DXPLANE* pP
);

パラメータ

pOut
[in, out] 演算結果である D3DXPLANE 構造体へのポインタ。
pP
[in] 処理の基になる D3DXPLANE 構造体へのポインタ。

戻り値

平面の法線を表す D3DXPLANE 構造体へのポインタ。

注意

D3DXPlaneNormalize は、|a,b,c| == 1 となるように平面を正規化する。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXPlaneNormalize 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXPlaneTransform

行列を指定して平面をトランスフォームする。

D3DXPLANE* D3DXPlaneTransform(
  D3DXPLANE* pOut,
  CONST D3DXPLANE* pP,
  CONST D3DXMATRIX* pM
);

パラメータ

pOut
[in, out] 演算結果である D3DXPLANE 構造体へのポインタ。
pP
[in] 処理の基になる D3DXPLANE 構造体へのポインタ。
pM
[in] 処理の基になる D3DXMATRIX 構造体へのポインタ。

戻り値

変換された平面を表す D3DXPLANE 構造体へのポインタ。

注意

行列 pM は、アフィン変換でなければならない。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXPlaneTransform 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXQuaternionBaryCentric

重心座標のクオータニオンを返す。

D3DXQUATERNION* D3DXQuaternionBaryCentric(
  D3DXQUATERNION* pOut,
  CONST D3DXQUATERNION* pQ1,
  CONST D3DXQUATERNION* pQ2,
  CONST D3DXQUATERNION* pQ3,
  CONST D3DXQUATERNION* pQ4,
  FLOAT f,
  FLOAT g
);

パラメータ

pOut
[in, out] 演算結果である D3DXQUATERNION 構造体へのポインタ。
pQ1
[in] 処理の基になる D3DXQUATERNION 構造体へのポインタ。
pQ2
[in] 処理の基になる D3DXQUATERNION 構造体へのポインタ。
pQ3
[in] 処理の基になる D3DXQUATERNION 構造体へのポインタ。
pQ4
[in] 処理の基になる D3DXQUATERNION 構造体へのポインタ。
f
[in] 加重係数。「注意」を参照すること。
g
[in] 加重係数。「注意」を参照すること。

戻り値

重心座標の D3DXQUATERNION 構造体へのポインタ。

注意

重心座標を計算するため、D3DXQuaternionBaryCentric 関数は次に示す球状線形補間演算子を実装する。Slerp(Slerp(Q1, Q2, f+g), Slerp(Q1, Q3, f+g), g/(f+g))

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXQuaternionBaryCentric 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXQuaternionConjugate

クオータニオンの共役を返す。

D3DXQUATERNION* D3DXQuaternionConjugate(
  D3DXQUATERNION* pOut,
  CONST D3DXQUATERNION* pQ
);

パラメータ

pOut
[in, out] 演算結果である D3DXQUATERNION 構造体へのポインタ。
pQ
[in] 処理の基になる D3DXQUATERNION 構造体へのポインタ。

戻り値

クオータニオンの共役である D3DXQUATERNION 構造体へのポインタ。

注意

クオータニオン (x, y, z, w) が指定された場合、D3DXQuaternionConjugate 関数はクオータニオン (-x, -y, -z, w) を返す。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXQuaternionConjugate 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXQuaternionInverse


D3DXQuaternionDot

2 つのクオータニオンの内積を返す。

FLOAT D3DXQuaternionDot(
  D3DXQUATERNION* pQ1,
  CONST D3DXQUATERNION* pQ2
);

パラメータ

pQ1
[out] 処理の基になる D3DXQUATERNION 構造体へのポインタ。
pQ2
[in] 処理の基になる D3DXQUATERNION 構造体へのポインタ。

戻り値

2 つのクオータニオンの内積。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXQuaternionExp

指数関数の計算を行う。

D3DXQUATERNION* D3DXQuaternionExp(
  D3DXQUATERNION* pOut,
  CONST D3DXQUATERNION* pQ
);

パラメータ

pOut
[in, out] 演算結果である D3DXQUATERNION 構造体へのポインタ。
pQ
[in] 処理の基になる D3DXQUATERNION 構造体へのポインタ。

戻り値

指数関数である D3DXQUATERNION 構造体へのポインタ。

注意

D3DXQuaternionExp 関数は、w == 0 の単一クオータニオンでのみ機能する。

この関数は、次のように実装される。

q = (0, theta * v)
exp(q) = (cos(theta), sin(theta) * v)

D3DXQuaternionExp 関数と D3DXQuaternionLn 関数は、D3DXQuaternionSquad 関数を使用するときに有用である。次の例で示すように、クオータニオン キー セット (q0, q1, q2, ..., qn) を指定すると、隣接セグメントをまたいで接線を連続させるために、次のように内部四角形の点 (a1, a2, a3, ..., an-1) を計算できる。

        a1    a2    a3
  q0    q1    q2    q3    q4

a[i] = q[i] * exp( -(ln(inv(q[i])*q[i+1]) + ln(inv(q[i])*q[i-1])) / 4 )

(a1, a2, a3, ...) が計算されたら、この結果を使用し、カーブに沿って補間できる。

qt = Squad(t, q[i], a[i], a[i+1], q[i+1])

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXQuaternionExp 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXQuaternionLn、D3DXQuaternionSquad


D3DXQuaternionIdentity

単位クオータニオンを返す。

D3DXQUATERNION* D3DXQuaternionIdentity(
  D3DXQUATERNION* pOut
);

パラメータ

pOut
[in, out] 演算結果である D3DXQUATERNION 構造体へのポインタ。

戻り値

単位クオータニオンである D3DXQUATERNION 構造体へのポインタ。

注意

クオータニオン (x, y, z, w) を指定した場合、D3DXQuaternionIdentity 関数はクオータニオン (0, 0, 0, 1) を返す。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXQuaternionIdentity 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXQuaternionIsIdentity


D3DXQuaternionInverse

クオータニオンを共役して、再正規化する。

D3DXQUATERNION* D3DXQuaternionInverse(
  D3DXQUATERNION* pOut,
  CONST D3DXQUATERNION* pQ
);

パラメータ

pOut
[in, out] 演算結果である D3DXQUATERNION 構造体へのポインタ。
pQ
[in] 処理の基になる D3DXQUATERNION 構造体へのポインタ。

戻り値

クオータニオンの逆クオータニオンである D3DXQUATERNION 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXQuaternionInverse 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXQuaternionConjugate、D3DXQuaternionNormalize


D3DXQuaternionIsIdentity

クオータニオンが単位クオータニオンであるかどうかを判定する。

BOOL D3DXQuaternionIsIdentity(
  CONST D3DXQUATERNION* pQ
);

パラメータ

pQ
[in] 単位クオータニオンであるかどうかを判定する D3DXQUATERNION 構造体へのポインタ。

戻り値

クオータニオンが単位クオータニオンの場合、この関数は TRUE を返す。それ以外の場合は、FALSE を返す。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXQuaternionIdentity


D3DXQuaternionLength

クオータニオンの長さを返す。

FLOAT D3DXQuaternionLength(
  CONST D3DXQUATERNION* pQ
);

パラメータ

pQ
[in] 処理の基になる D3DXQUATERNION 構造体へのポインタ。

戻り値

クオータニオンの長さ。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXQuaternionLengthSq


D3DXQuaternionLengthSq

クオータニオンの長さの 2 乗を返す。

FLOAT D3DXQuaternionLengthSq(
  CONST D3DXQUATERNION* pQ
);

パラメータ

pQ
[in] 処理の基になる D3DXQUATERNION 構造体へのポインタ。

戻り値

クオータニオンの長さの 2 乗。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXQuaternionLength


D3DXQuaternionLn

自然対数を計算する。

D3DXQUATERNION* D3DXQuaternionLn(
  D3DXQUATERNION* pOut,
  CONST D3DXQUATERNION* pQ
);

パラメータ

pOut
[in, out] 演算結果である D3DXQUATERNION 構造体へのポインタ。
pQ
[in] 処理の基になる D3DXQUATERNION 構造体へのポインタ。

戻り値

自然対数である D3DXQUATERNION 構造体へのポインタ。

注意

D3DXQuaternionLn 関数は、正規化されたクオータニオンでのみ機能する。

この関数は、次のように実装される。

q = (cos(theta), sin(theta) * v)
|v| = 1
ln(q) = (0, theta * v)

D3DXQuaternionExp 関数と D3DXQuaternionLn 関数は、D3DXQuaternionSquad 関数を使用するとき有用である。クオータニオン キー セット (q0, q1, q2, ..., qn) を指定すると、隣接セグメントをまたいで接線を連続させるために、次のように内部四角形の点 (a1, a2, a3, ..., an-1) を計算できる。

        a1    a2    a3
  q0    q1    q2    q3    q4

a[i] = q[i] * exp( -(ln(inv(q[i])*q[i+1]) + ln(inv(q[i])*q[i-1])) / 4 )

(a1, a2, a3, ...) が計算されたら、この結果を使用し、カーブに沿って補間できる。

qt = Squad(t, q[i], a[i], a[i+1], q[i+1])

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXQuaternionLn 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXQuaternionExp、D3DXQuaternionSquad


D3DXQuaternionMultiply

2 つのクオータニオンの積を求める。

D3DXQUATERNION* D3DXQuaternionMultiply(
  D3DXQUATERNION* pOut,
  CONST D3DXQUATERNION* pQ1,
  CONST D3DXQUATERNION* pQ2
);

パラメータ

pOut
[in, out] 演算結果である D3DXQUATERNION 構造体へのポインタ。
pQ1
[in] 処理の基になる D3DXQUATERNION 構造体へのポインタ。
pQ2
[in] 処理の基になる D3DXQUATERNION 構造体へのポインタ。

戻り値

2 つのクオータニオンの積である D3DXQUATERNION 構造体へのポインタ。

注意

結果は、回転 Q1 の後に回転 Q2 を実行した結果を示している (Out = Q2 * Q1)。実際の出力は Q2*Q1 である (Q1*Q2 ではない)。このようにすると、回転行列を表すまた別の方法として正規化されたクオータニオンを見なすことができるので、D3DXQuaternionMultiply 関数は D3DXMatrixMultiply と同じセマンティクスを保持する。

D3DXQuaternionMultiply 関数と D3DXMatrixMultiply 関数の両方とも、同じ順序で変換が結合される。たとえば、mX と mY が qX と qY と同じ回転を表しているものと仮定すると、m と q は両方とも同じ回転を表すことになる。

D3DXMatrixMultiply(&m, &mX, &mY);

D3DXQuaternionMultiply(&q, &qX, &qY);

クオータニオンの積算は、可換性がない。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXQuaternionMultiply 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXMatrixMultiply


D3DXQuaternionNormalize

正規化されたクオータニオンを返す。

D3DXQUATERNION* D3DXQuaternionNormalize(
  D3DXQUATERNION* pOut,
  CONST D3DXQUATERNION* pQ
);

パラメータ

pOut
[in, out] 演算結果である D3DXQUATERNION 構造体へのポインタ。
pQ
[in] 処理の基になる D3DXQUATERNION 構造体へのポインタ。

戻り値

正規化されたクオータニオンである D3DXQUATERNION 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXQuaternionNormalize 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXQuaternionInverse


D3DXQuaternionRotationAxis

指定した軸を中心にしてクオータニオンを回転させる。

D3DXQUATERNION* D3DXQuaternionRotationAxis(
  D3DXQUATERNION* pOut,
  CONST D3DXVECTOR3* pV,
  FLOAT Angle
);

パラメータ

pOut
[in, out] 演算結果である D3DXQUATERNION 構造体へのポインタ。
pV
[in] 軸の角度を識別する D3DXVECTOR3 構造体へのポインタ。
Angle
[in] 回転の角度 (ラジアン単位)。角度は、回転軸から原点に向かって時計回りに計測される。

戻り値

指定された軸を回転軸として回転した D3DXQUATERNION 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXQuaternionRotationAxis 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXQuaternionRotationMatrix、D3DXQuaternionRotationYawPitchRoll


D3DXQuaternionRotationMatrix

回転行列からクオータニオンを作成する。

D3DXQUATERNION* D3DXQuaternionRotationMatrix(
  D3DXQUATERNION* pOut,
  CONST D3DXMATRIX* pM
);

パラメータ

pOut
[in, out] 演算結果である D3DXQUATERNION 構造体へのポインタ。
pM
[in] 処理の基になる D3DXMATRIX 構造体へのポインタ。

戻り値

回転行列から作成された D3DXQUATERNION 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXQuaternionRotationMatrix 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXQuaternionRotationAxis、D3DXQuaternionRotationYawPitchRoll


D3DXQuaternionRotationYawPitchRoll

ヨー、ピッチ、およびロールを指定してクオータニオンを作成する。

D3DXQUATERNION* D3DXQuaternionRotationYawPitchRoll(
  D3DXQUATERNION* pOut,
  FLOAT Yaw,
  FLOAT Pitch,
  FLOAT Roll
);

パラメータ

pOut
[in, out] 演算結果である D3DXQUATERNION 構造体へのポインタ。
Yaw
[in] y 軸のヨー (ラジアン単位)。
Pitch
[in] x 軸のピッチ (ラジアン単位)。
Roll
[in] z 軸のロール (ラジアン単位)。

戻り値

ヨー、ピッチ、およびロールを持つ D3DXQUATERNION 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXQuaternionRotationYawPitchRoll 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXQuaternionRotationAxis、D3DXQuaternionRotationMatrix


D3DXQuaternionSlerp

球状線形補間を使用して、2 つのクオータニオン間を補間する。

D3DXQUATERNION* D3DXQuaternionSlerp(
  D3DXQUATERNION* pOut,
  CONST D3DXQUATERNION* pQ1,
  CONST D3DXQUATERNION* pQ2,
  FLOAT t
);

パラメータ

pOut
[in, out] 演算結果である D3DXQUATERNION 構造体へのポインタ。
pQ1
[in] 処理の基になる D3DXQUATERNION 構造体へのポインタ。
pQ2
[in] 処理の基になる D3DXQUATERNION 構造体へのポインタ。
t
[in] クオータニオン間を補間する範囲を指定するパラメータ。

戻り値

補間結果である D3DXQUATERNION 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXQuaternionSlerp 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXQuaternionSquad

球状平方補間を使用して、クオータニオン間を補間する。

D3DXQUATERNION* D3DXQuaternionSquad(
  D3DXQUATERNION* pOut,
  CONST D3DXQUATERNION* pQ1,
  CONST D3DXQUATERNION* pQ2,
  CONST D3DXQUATERNION* pQ3,
  CONST D3DXQUATERNION* pQ4,
  FLOAT t
);

パラメータ

pOut
[in, out] 演算結果である D3DXQUATERNION 構造体へのポインタ。
pQ1
[in] 処理の基になる D3DXQUATERNION 構造体へのポインタ。
pQ2
[in] 処理の基になる D3DXQUATERNION 構造体へのポインタ。
pQ3
[in] 処理の基になる D3DXQUATERNION 構造体へのポインタ。
pQ4
[in] 処理の基になる D3DXQUATERNION 構造体へのポインタ。
t
[in] クオータニオン間を補間する範囲を指定するパラメータ。

戻り値

球状平方補間の結果である D3DXQUATERNION 構造体へのポインタ。

注意

この関数は、次に示す球状線形補間演算を使用する。Slerp(Slerp(Q1, Q4, t), Slerp(Q2, Q3, t), 2t(1-t))

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXQuaternionSquad 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXQuaternionExp、D3DXQuaternionLn


D3DXQuaternionToAxisAngle

クオータニオンの回転軸と回転角度を計算する。

void D3DXQuaternionToAxisAngle(
  CONST D3DXQUATERNION* pQ,
  D3DXVECTOR3* pAxis,
  FLOAT* pAngle
);

パラメータ

pQ
[in, out] 処理の基になる D3DXQUATERNION 構造体へのポインタ。
pAxis
[in, out] この関数が戻る場合、クオータニオンの回転軸を識別する D3DXVECTOR3 構造体へのポインタ。
pAngle
[in, out] この関数が戻る場合、クオータニオンの回転角度 (ラジアン単位) を識別する FLOAT 値へのポインタ。

戻り値

なし。

注意

この関数は、正規化されたクオータニオンが渡されるものと仮定している。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXVec2Add

2 つの 2D ベクトルを加算する。

D3DXVECTOR2* D3DXVec2Add(
  D3DXVECTOR2* pOut,
  CONST D3DXVECTOR2* pV1,
  CONST D3DXVECTOR2* pV2
);

パラメータ

pOut
[in, out] 演算結果である D3DXVECTOR2 構造体へのポインタ。
pV1
[in] 処理の基になる D3DXVECTOR2 構造体へのポインタ。
pV2
[in] 処理の基になる D3DXVECTOR2 構造体へのポインタ。

戻り値

2 つのベクトルの合計である D3DXVECTOR2 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec2Add 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXVec2Subtract、D3DXVec2Scale


D3DXVec2BaryCentric

指定された 2D ベクトルを使用して重心座標のポイントを返す。

D3DXVECTOR2* D3DXVec2BaryCentric(
  D3DXVECTOR2* pOut,
  CONST D3DXVECTOR2* pV1,
  CONST D3DXVECTOR2* pV2,
  D3DXVECTOR2* pV3,
  FLOAT f,
  FLOAT g
);

パラメータ

pOut
[in, out] 演算結果である D3DXVECTOR2 構造体へのポインタ。
pV1
[in] 処理の基になる D3DXVECTOR2 構造体へのポインタ。
pV2
[in] 処理の基になる D3DXVECTOR2 構造体へのポインタ。
pV3
[in] 処理の基になる D3DXVECTOR2 構造体へのポインタ。
f
[in] 加重係数。「注意」を参照すること。
g
[in] 加重係数。「注意」を参照すること。

戻り値

重心座標の D3DXVECTOR2 構造体へのポインタ。

注意

D3DXVec2BaryCentric 関数は、三角形の実際の位置とは関係なく、三角形の内部や周辺のポイントを理解する方法を提供している。この関数は、次の式を使用して結果であるポイントを返す。V1 + f(V2-V1) + g(V3-V1)

平面 V1V2V3 のポイントはいずれも、重心座標 (f,g) で表すことができる。パラメータ f は、V2 の結果に対する加重を制御し、パラメータ g は、V3 の結果に対する加重を制御する。最後に、1-f-g は V1 の結果に対する加重を制御する。

次の関係に注意すること。

  • (f>=0 && g>=0 && 1-f-g>=0) の場合、ポイントは三角形 V1V2V3 内にある。
  • (f==0 && g>=0 && 1-f-g>=0) の場合、ポイントは直線 V1V3 上にある。
  • (f>=0 && g==0 && 1-f-g>=0) の場合、ポイントは直線 V1V2 上にある。
  • (f>=0 && g>=0 && 1-f-g==0) の場合、ポイントは直線 V2V3 上にある。

重心座標は、一般的な座標の形式である。ここで重心座標を使用するときは、単に座標系の変更を表している。デカルト座標で真のものは、重心座標でも真である。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec2BaryCentric 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXVec2CatmullRom

指定された 2D ベクトルを使用して、Catmull-Rom 補間を実行する。

D3DXVECTOR2* D3DXVec2CatmullRom(
  D3DXVECTOR2* pOut,
  CONST D3DXVECTOR2* pV1,
  CONST D3DXVECTOR2* pV2,
  CONST D3DXVECTOR2* pV3,
  CONST D3DXVECTOR2* pV4,
  FLOAT s
);

パラメータ

pOut
[in, out] 演算結果である D3DXVECTOR2 構造体へのポインタ。
pV1
[in] 位置ベクトルを示す、処理の基になる D3DXVECTOR2 構造体へのポインタ。
pV2
[in] 位置ベクトルを示す、処理の基になる D3DXVECTOR2 構造体へのポインタ。
pV3
[in] 位置ベクトルを示す、処理の基になる D3DXVECTOR2 構造体へのポインタ。
pV4
[in] 位置ベクトルを示す、処理の基になる D3DXVECTOR2 構造体へのポインタ。
s
[in] 加重係数。「注意」を参照すること。

戻り値

Catmull-Rom 補間の結果である D3DXVECTOR2 構造体へのポインタ。

注意

D3DXVec2CatmullRom 関数は、Catmull-Rom 補間を使用して、位置 V1 (s が 0 の場合) の間と、位置 V2 (s が 1 の場合) の間の補間を行う。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXVec2CCW

2 つの 2D ベクトルの外積を算出して z 要素を返す。

FLOAT D3DXVec2CCW(
  CONST D3DXVECTOR2* pV1,
  CONST D3DXVECTOR2* pV2
);

パラメータ

pV1
[in] 処理の基になる D3DXVECTOR2 構造体へのポインタ。
pV2
[in] 処理の基になる D3DXVECTOR2 構造体へのポインタ。

戻り値

z 要素。

注意

この関数は、式 ((x1,y1,0) cross (x2,y2,0)) に基づいて外積を算出し、z 要素を判定する。((x1,y1,0) cross (x2,y2,0)).また、次のコードを使用して判定することもできる。

pV1->x * pV2->y - pV1->y * pV2->x

z 要素の値が正の場合、V2 は V1 に対して反時計回りである。この情報は、背面のカリングで役に立つ。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXVec2Dot


D3DXVec2Dot

2 つの 2D ベクトルの内積を算出する。

FLOAT D3DXVec2Dot(
  CONST D3DXVECTOR2* pV1,
  CONST D3DXVECTOR2* pV2
);

パラメータ

pV1
[in] 処理の基になる D3DXVECTOR2 構造体へのポインタ。
pV2
[in] 処理の基になる D3DXVECTOR2 構造体へのポインタ。

戻り値

内積。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXVec2CCW


D3DXVec2Hermite

指定された 2D ベクトルを使用して、エルミートのスプライン補間を実行する。

D3DXVECTOR2* D3DXVec2Hermite(
  D3DXVECTOR2* pOut,
  CONST D3DXVECTOR2* pV1,
  CONST D3DXVECTOR2* pT1,
  CONST D3DXVECTOR2* pV2,
  CONST D3DXVECTOR2* pT2,
  FLOAT s
);

パラメータ

pOut
[in, out] 演算結果である D3DXVECTOR2 構造体へのポインタ。
pV1
[in] 位置ベクトルを示す、処理の基になる D3DXVECTOR2 構造体へのポインタ。
pT1
[in] 接線ベクトルを示す、処理の基になる D3DXVECTOR2 構造体へのポインタ。
pV2
[in] 位置ベクトルを示す、処理の基になる D3DXVECTOR2 構造体へのポインタ。
pT2
[in] 接線ベクトルを示す、処理の基になる D3DXVECTOR2 構造体へのポインタ。
s
[in] 加重係数。「注意」を参照すること。

戻り値

エルミートのスプライン補間の結果である D3DXVECTOR2 構造体へのポインタ。

注意

D3DXVec2Hermite 関数は、エルミートのスプライン補間を使用して (positionA, tangentA) から (positionB, tangentB) へ補間する。この関数は、位置 V1 と接線 T1 の間 (s が 0 の場合) と、位置 V2 と接線 T2 の間 (s が 1 の場合) を補間する。

エルミートのスプラインは、カーブがすべての制御ポイントを通過するので、アニメーションを制御する場合に便利である。また、位置や接線が各セグメントの終点で明示的に指定されているので、起点と接線が最終セグメントの終点の値に一致するようにしている限り、C2 連続カーブを簡単に作成できる。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec2Hermite 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXVec2Length

2D ベクトルの長さを返す。

FLOAT D3DXVec2Length(
  CONST D3DXVECTOR2* pV
);

パラメータ

pV
[in] 処理の基になる D3DXVECTOR2 構造体へのポインタ。

戻り値

ベクトルの長さ。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXVec2LengthSq


D3DXVec2LengthSq

2D ベクトルの長さの 2 乗を返す。

FLOAT D3DXVec2LengthSq(
  CONST D3DXVECTOR2* pV
);

パラメータ

pV
[in] 処理の基になる D3DXVECTOR2 構造体へのポインタ。

戻り値

ベクトルの長さの 2 乗。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXVec2Length


D3DXVec2Lerp

2 つの 2D ベクトル間の線形補間を実行する。

D3DXVECTOR2* D3DXVec2Lerp(
  D3DXVECTOR2* pOut,
  CONST D3DXVECTOR2* pV1,
  CONST D3DXVECTOR2* pV2,
  FLOAT s
);

パラメータ

pOut
[in, out] 演算結果である D3DXVECTOR2 構造体へのポインタ。
pV1
[in] 処理の基になる D3DXVECTOR2 構造体へのポインタ。
pV2
[in] 処理の基になる D3DXVECTOR2 構造体へのポインタ。
s
[in] ベクトル間を線形補間するパラメータ。

戻り値

線形補間の結果である D3DXVECTOR2 構造体へのポインタ。

注意

この関数は、次の式に基づいて線形補間を実行する。V1 + s(V2-V1)

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec2Lerp 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXVec2Maximize

2 つの 2D ベクトルの各要素の最大値から作成された 2D ベクトルを返す。

D3DXVECTOR2* D3DXVec2Maximize(
  D3DXVECTOR2* pOut,
  CONST D3DXVECTOR2* pV1,
  CONST D3DXVECTOR2* pV2
);

パラメータ

pOut
[in, out] 演算結果である D3DXVECTOR2 構造体へのポインタ。
pV1
[in] 処理の基になる D3DXVECTOR2 構造体へのポインタ。
pV2
[in] 処理の基になる D3DXVECTOR2 構造体へのポインタ。

戻り値

2 つのベクトルの最大値から作成した D3DXVECTOR2 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec2Maximize 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXVec2Minimize


D3DXVec2Minimize

2 つの 2D ベクトルの各要素の最小値から作成された 2D ベクトルを返す。

D3DXVECTOR2* D3DXVec2Minimize(
  D3DXVECTOR2* pOut,
  CONST D3DXVECTOR2* pV1,
  CONST D3DXVECTOR2* pV2
);

パラメータ

pOut
[in, out] 演算結果である D3DXVECTOR2 構造体へのポインタ。
pV1
[in] 処理の基になる D3DXVECTOR2 構造体へのポインタ。
pV2
[in] 処理の基になる D3DXVECTOR2 構造体へのポインタ。

戻り値

2 つのベクトルの最小値から作成した D3DXVECTOR2 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec2Minimize 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXVec2Maximize


D3DXVec2Normalize

2D ベクトルの正規化したベクトルを返す。

D3DXVECTOR2* D3DXVec2Normalize(
  D3DXVECTOR2* pOut,
  CONST D3DXVECTOR2* pV
);

パラメータ

pOut
[in, out] 演算結果である D3DXVECTOR2 構造体へのポインタ。
pV
[in] 処理の基になる D3DXVECTOR2 構造体へのポインタ。

戻り値

正規化したベクトルの D3DXVECTOR2 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec2Normalize 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXVec2Scale

2D ベクトルをスケーリングする。

D3DXVECTOR2* D3DXVec2Scale(
  D3DXVECTOR2* pOut,
  CONST D3DXVECTOR2* pV,
  FLOAT s
);

パラメータ

pOut
[in, out] 演算結果である D3DXVECTOR2 構造体へのポインタ。
pV
[in] 処理の基になる D3DXVECTOR2 構造体へのポインタ。
s
[in] スケーリング値。

戻り値

スケーリングされたベクトルである D3DXVECTOR2 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec2Scale 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXVec2Add、D3DXVec2Subtract


D3DXVec2Subtract

2 つの 2D ベクトルを減算する。

D3DXVECTOR2* D3DXVec2Subtract(
  D3DXVECTOR2* pOut,
  CONST D3DXVECTOR2* pV1,
  CONST D3DXVECTOR2* pV2
);

パラメータ

pOut
[in, out] 演算結果である D3DXVECTOR2 構造体へのポインタ。
pV1
[in] 処理の基になる D3DXVECTOR2 構造体へのポインタ。
pV2
[in] 処理の基になる D3DXVECTOR2 構造体へのポインタ。

戻り値

2 つのベクトルの差分である D3DXVECTOR2 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec2Subtract 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXVec2Add、D3DXVec2Scale


D3DXVec2Transform

指定された行列により 2D ベクトルをトランスフォームする。

D3DXVECTOR4* D3DXVec2Transform(
  D3DXVECTOR4** pOut,
  CONST D3DXVECTOR2* pV,
  CONST D3DXMATRIX* pM
);

パラメータ

pOut
[in, out] 演算結果である D3DXVECTOR4 構造体へのポインタ。
pV
[in] 処理の基になる D3DXVECTOR2 構造体へのポインタ。
pM
[in] 処理の基になる D3DXMATRIX 構造体へのポインタ。

戻り値

トランスフォームされたベクトルの D3DXVECTOR4 構造体へのポインタ。

注意

この関数は、ベクトル pV (x, y, 0, 1) を行列 pM によりトランスフォームする。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec2Transform 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXVec2TransformCoord、D3DXVec2TransformNormal


D3DXVec2TransformCoord

指定された行列により 2D ベクトルをトランスフォームし、その結果を w = 1 に射影する。

D3DXVECTOR2* D3DXVec2TransformCoord(
  D3DXVECTOR2* pOut,
  CONST D3DXVECTOR2* pV,
  CONST D3DXMATRIX* pM
);

パラメータ

pOut
[in, out] 演算結果である D3DXVECTOR2 構造体へのポインタ。
pV
[in] 処理の基になる D3DXVECTOR2 構造体へのポインタ。
pM
[in] 処理の基になる D3DXMATRIX 構造体へのポインタ。

戻り値

トランスフォームされたベクトルの D3DXVECTOR2 構造体へのポインタ。

注意

この関数は、ベクトル pV (x, y, 0, 1) を行列 pM によりトランスフォームし、その結果を w=1 に射影する。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec2TransformCoord 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXVec2Transform、D3DXVec2TransformNormal


D3DXVec2TransformNormal

指定された行列により 2D ベクトルを w = 0 でトランスフォームする。

D3DXVECTOR2* D3DXVec2TransformNormal(
  D3DXVECTOR2* pOut,
  CONST D3DXVECTOR2* pV,
  CONST D3DXMATRIX* pM
);

パラメータ

pOut
[in, out] 演算結果である D3DXVECTOR2 構造体へのポインタ。
pV
[in] 処理の基になる D3DXVECTOR2 構造体へのポインタ。
pM
[in] 処理の基になる D3DXMATRIX 構造体へのポインタ。

戻り値

トランスフォームされたベクトルの D3DXVECTOR2 構造体へのポインタ。

注意

この関数は、ベクトル pV のベクトル法線 (x, y, 0, 0) を行列 pM によりトランスフォームする。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec2TransformNormal 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXVec2Transform、D3DXVec2TransformCoord


D3DXVec3Add

2 つの 3D ベクトルを加算する。

D3DXVECTOR3* D3DXVec3Add(
  D3DXVECTOR3* pOut,
  CONST D3DXVECTOR3* pV1,
  CONST D3DXVECTOR3* pV2
);

パラメータ

pOut
[in, out] 演算結果である D3DXVECTOR3 構造体へのポインタ。
pV1
[in] 処理の基になる D3DXVECTOR3 構造体へのポインタ。
pV2
[in] 処理の基になる D3DXVECTOR3 構造体へのポインタ。

戻り値

2 つの 3D ベクトルの合計である D3DXVECTOR3 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec3Add 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXVec3Subtract、D3DXVec3Scale


D3DXVec3BaryCentric

指定された 3D ベクトルを使用して重心座標のポイントを返す。

D3DXVECTOR3* D3DXVec3BaryCentric(
  D3DXVECTOR3* pOut,
  CONST D3DXVECTOR3* pV1,
  CONST D3DXVECTOR3* pV2,
  D3DXVECTOR3* pV3,
  FLOAT f,
  FLOAT g
);

パラメータ

pOut
[in, out] 演算結果である D3DXVECTOR3 構造体へのポインタ。
pV1
[in] 処理の基になる D3DXVECTOR3 構造体へのポインタ。
pV2
[in] 処理の基になる D3DXVECTOR3 構造体へのポインタ。
pV3
[in] 処理の基になる D3DXVECTOR3 構造体へのポインタ。
f
[in] 加重係数。「注意」を参照すること。
g
[in] 加重係数。「注意」を参照すること。

戻り値

重心座標の D3DXVECTOR3 構造体へのポインタ。

注意

D3DXVec3BaryCentric 関数は、三角形の実際の位置とは関係なく、三角形の内部や周辺のポイントを理解する方法を提供している。この関数は、次の式を使用して結果であるポイントを返す。V1 + f(V2-V1) + g(V3-V1)

平面 V1V2V3 の任意のポイントは、重心座標 (f,g) で表すことができる。パラメータ f は V2 の結果に対する加重を制御し、パラメータ g は V3 の結果に対する加重を制御する。最後に、1-f-g は V1 の結果に対する加重を制御する。

次の関係に注意すること。

  • (f>=0 && g>=0 && 1-f-g>=0) の場合、ポイントは三角形 V1V2V3 内にある。
  • (f==0 && g>=0 && 1-f-g>=0) の場合、ポイントは直線 V1V3 上にある。
  • (f>=0 && g==0 && 1-f-g>=0) の場合、ポイントは直線 V1V2 上にある。
  • (f>=0 && g>=0 && 1-f-g==0) の場合、ポイントは直線 V2V3 上にある。

重心座標は、一般的な座標の形式である。ここで重心座標を使用するときは、単に座標系の変更を表している。デカルト座標で真のものは、重心座標でも真である。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec3BaryCentric 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXVec3CatmullRom

指定された 3D ベクトルを使用して、Catmull-Rom 補間を実行する。

D3DXVECTOR3* D3DXVec3CatmullRom(
  D3DXVECTOR3* pOut,
  CONST D3DXVECTOR3* pV1,
  CONST D3DXVECTOR3* pV2,
  CONST D3DXVECTOR3* pV3,
  CONST D3DXVECTOR3* pV4,
  FLOAT s
);

パラメータ

pOut
[in, out] 演算結果である D3DXVECTOR3 構造体へのポインタ。
pV1
[in] 位置ベクトルを示す、処理の基になる D3DXVECTOR3 構造体へのポインタ。
pV2
[in] 位置ベクトルを示す、処理の基になる D3DXVECTOR3 構造体へのポインタ。
pV3
[in] 位置ベクトルを示す、処理の基になる D3DXVECTOR3 構造体へのポインタ。
pV4
[in] 位置ベクトルを示す、処理の基になる D3DXVECTOR3 構造体へのポインタ。
s
[in] 加重係数。「注意」を参照すること。

戻り値

Catmull-Rom 補間の結果である D3DXVECTOR3 構造体へのポインタ。

注意

D3DXVec3CatmullRom 関数は、Catmull-Rom 補間を使用して、位置 V1 (s が 0 の場合) の間と、位置 V2 (s が 1 の場合) の間の補間を行う。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXVec3Cross

2 つの 3D ベクトルの外積を算出する。

D3DXVECTOR3* D3DXVec3Cross(
  D3DXVECTOR3* pOut,
  CONST D3DXVECTOR3* pV1,
  CONST D3DXVECTOR3* pV2
);

パラメータ

pOut
[in, out] 演算結果である D3DXVECTOR3 構造体へのポインタ。
pV1
[in] 処理の基になる D3DXVECTOR3 構造体へのポインタ。
pV2
[in] 処理の基になる D3DXVECTOR3 構造体へのポインタ。

戻り値

2 つの 3D ベクトルの外積である D3DXVECTOR3 構造体へのポインタ。

注意

この関数は、次のコードを使用して外積を算出する。

    D3DXVECTOR3 v;

    v.x = pV1->y * pV2->z - pV1->z * pV2->y;
    v.y = pV1->z * pV2->x - pV1->x * pV2->z;
    v.z = pV1->x * pV2->y - pV1->y * pV2->x;

    *pOut = v;

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec3Cross 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXVec3Dot


D3DXVec3Dot

2 つの 3D ベクトルの内積を算出する。

FLOAT D3DXVec3Dot(
  CONST D3DXVECTOR3* pV1,
  CONST D3DXVECTOR3* pV2
);

パラメータ

pV1
[in] 処理の基になる D3DXVECTOR3 構造体へのポインタ。
pV2
[in] 処理の基になる D3DXVECTOR3 構造体へのポインタ。

戻り値

内積。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXVec3Cross


D3DXVec3Hermite

指定された 3D ベクトルを使用して、エルミートのスプライン補間を実行する。

D3DXVECTOR3* D3DXVec3Hermite(
  D3DXVECTOR3* pOut,
  CONST D3DXVECTOR3* pV1,
  CONST D3DXVECTOR3* pT1,
  CONST D3DXVECTOR3* pV2,
  CONST D3DXVECTOR3* pT2,
  FLOAT s
);

パラメータ

pOut
[in, out] 演算結果である D3DXVECTOR3 構造体へのポインタ。
pV1
[in] 位置ベクトルを示す、処理の基になる D3DXVECTOR3 構造体へのポインタ。
pT1
[in] 接線ベクトルを示す、処理の基になる D3DXVECTOR3 構造体へのポインタ。
pV2
[in] 位置ベクトルを示す、処理の基になる D3DXVECTOR3 構造体へのポインタ。
pT2
[in] 接線ベクトルを示す、処理の基になる D3DXVECTOR3 構造体へのポインタ。
s
[in] 加重係数。「注意」を参照すること。

戻り値

エルミートのスプライン補間の結果である D3DXVECTOR3 構造体へのポインタ。

注意

D3DXVec3Hermite 関数は、エルミートのスプライン補間を使用して (positionA, tangentA) から (positionB, tangentB) へ補間する。この関数は、位置 V1 と接線 T1 の間 (s が 0 の場合) と、位置 V2 と接線 T2 の間 (s が 1 の場合) を補間する。

エルミートのスプラインは、カーブがすべての制御ポイントを通過するので、アニメーションを制御する場合に便利である。また、位置や接線が各セグメントの終点で明示的に指定されているので、起点と接線が最終セグメントの終点の値に一致するようにしている限り、C2 連続カーブを簡単に作成できる。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec3Hermite 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXVec3Length

3D ベクトルの長さを返す。

FLOAT D3DXVec3Length(
  CONST D3DXVECTOR3* pV
);

パラメータ

pV
[in] 処理の基になる D3DXVECTOR3 構造体へのポインタ。

戻り値

ベクトルの長さ。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXVec3LengthSq


D3DXVec3LengthSq

3D ベクトルの長さの 2 乗を返す。

FLOAT D3DXVec3LengthSq(
  CONST D3DXVECTOR3* pV
);

パラメータ

pV
[in] 処理の基になる D3DXVECTOR3 構造体へのポインタ。

戻り値

ベクトルの長さの 2 乗。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXVec3Length


D3DXVec3Lerp

2 つの 3D ベクトル間の線形補間を実行する。

D3DXVECTOR3* D3DXVec3Lerp(
  D3DXVECTOR3* pOut,
  CONST D3DXVECTOR3* pV1,
  CONST D3DXVECTOR3* pV2,
  FLOAT s
);

パラメータ

pOut
[in, out] 演算結果である D3DXVECTOR3 構造体へのポインタ。
pV1
[in] 処理の基になる D3DXVECTOR3 構造体へのポインタ。
pV2
[in] 処理の基になる D3DXVECTOR3 構造体へのポインタ。
s
[in] ベクトル間を線形補間するパラメータ。

戻り値

線形補間の結果である D3DXVECTOR3 構造体へのポインタ。

注意

この関数は、次の式に基づいて線形補間を実行する。V1 + s(V2-V1)

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec3Lerp 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXVec3Maximize

2 つの 3D ベクトルの各要素の最大値から作成された 3D ベクトルを返す。

D3DXVECTOR3* D3DXVec3Maximize(
  D3DXVECTOR3* pOut,
  CONST D3DXVECTOR3* pV1,
  CONST D3DXVECTOR3* pV2
);

パラメータ

pOut
[in, out] 演算結果である D3DXVECTOR3 構造体へのポインタ。
pV1
[in] 処理の基になる D3DXVECTOR3 構造体へのポインタ。
pV2
[in] 処理の基になる D3DXVECTOR3 構造体へのポインタ。

戻り値

指定された 2 つのベクトルの各要素の最大値から作成された D3DXVECTOR3 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec3Maximize 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXVec3Minimize


D3DXVec3Minimize

2 つの 3D ベクトルの各要素の最小値から作成された 3D ベクトルを返す。

D3DXVECTOR3* D3DXVec3Minimize(
  D3DXVECTOR3* pOut,
  CONST D3DXVECTOR3* pV1,
  CONST D3DXVECTOR3* pV2
);

パラメータ

pOut
[in, out] 演算結果である D3DXVECTOR3 構造体へのポインタ。
pV1
[in] 処理の基になる D3DXVECTOR3 構造体へのポインタ。
pV2
[in] 処理の基になる D3DXVECTOR3 構造体へのポインタ。

戻り値

指定された 2 つのベクトルの最小値から作成された D3DXVECTOR3 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec3Minimize 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXVec3Maximize


D3DXVec3Normalize

3D ベクトルの正規化したベクトルを返す。

D3DXVECTOR3* D3DXVec3Normalize(
  D3DXVECTOR3* pOut,
  CONST D3DXVECTOR3* pV
);

パラメータ

pOut
[in, out] 演算結果である D3DXVECTOR3 構造体へのポインタ。
pV
[in] 処理の基になる D3DXVECTOR3 構造体へのポインタ。

戻り値

指定された正規化したベクトルの D3DXVECTOR3 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec3Normalize 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXVec3Project

オブジェクト空間からスクリーン空間にベクトルを射影する。

D3DXVECTOR3* D3DXVec3Project(
  D3DXVECTOR3* pOut,
  CONST D3DXVECTOR3* pV
  CONST D3DVIEWPORT8* pViewport,
  CONST D3DXMATRIX* pProjection
  CONST D3DXMATRIX* pView,
  CONST D3DXMATRIX* pWorld
);

パラメータ

pOut
[in, out] 演算結果である D3DXVECTOR3 構造体へのポインタ。
pV
[in] 処理の基になる D3DXVECTOR3 構造体へのポインタ。
pViewport
[in] ビューポートを表す D3DVIEWPORT8 構造体へのポインタ。
pProjection
[in] 射影行列を表す D3DXMATRIX 構造体へのポインタ。
pView
[in] ビュー行列を表す D3DXMATRIX 構造体へのポインタ。
pWorld
[in] ワールド行列を表す D3DXMATRIX 構造体へのポインタ。

戻り値

オブジェクト空間からスクリーン空間に射影されたベクトルである、D3DXVECTOR3 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec3Project 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXVec3Unproject


D3DXVec3Scale

3D ベクトルをスケーリングする。

D3DXVECTOR3* D3DXVec3Scale(
  D3DXVECTOR3* pOut,
  CONST D3DXVECTOR3* pV,
  FLOAT s
);

パラメータ

pOut
[in, out] 演算結果である D3DXVECTOR3 構造体へのポインタ。
pV
[in] 処理の基になる D3DXVECTOR3 構造体へのポインタ。
s
[in] スケーリング値。

戻り値

スケーリングされたベクトルである D3DXVECTOR3 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec3Scale 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXVec3Add、D3DXVec3Subtract


D3DXVec3Subtract

2 つの 3D ベクトルを減算する。

D3DXVECTOR3* D3DXVec3Subtract(
  D3DXVECTOR3* pOut,
  CONST D3DXVECTOR3* pV1,
  CONST D3DXVECTOR3* pV2
);

パラメータ

pOut
[in, out] 演算結果である D3DXVECTOR3 構造体へのポインタ。
pV1
[in] 処理の基になる D3DXVECTOR3 構造体へのポインタ。
pV2
[in] 処理の基になる D3DXVECTOR3 構造体へのポインタ。

戻り値

2 つのベクトルの差分である D3DXVECTOR3 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec3Subtract 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXVec3Add、D3DXVec3Scale


D3DXVec3Transform

指定された行列により 3D ベクトルをトランスフォームする。

D3DXVECTOR4* D3DXVec3Transform(
  D3DXVECTOR4* pOut,
  CONST D3DXVECTOR3* pV,
  CONST D3DXMATRIX* pM
);

パラメータ

pOut
[in, out] 演算結果である D3DXVECTOR4 構造体へのポインタ。
pV
[in] 処理の基になる D3DXVECTOR3 構造体へのポインタ。
pM
[in] 処理の基になる D3DXMATRIX 構造体へのポインタ。

戻り値

トランスフォームされたベクトルの D3DXVECTOR4 構造体へのポインタ。

注意

この関数は、ベクトル pV (x, y, z, 1) を行列 pM によりトランスフォームする。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec3Transform 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXVec3TransformCoord、D3DXVec3TransformNormal


D3DXVec3TransformCoord

指定された行列により 3D ベクトルをトランスフォームし、その結果を w = 1 に射影する。

D3DXVECTOR3* D3DXVec3TransformCoord(
  D3DXVECTOR3* pOut,
  CONST D3DXVECTOR3* pV,
  CONST D3DXMATRIX* pM
);

パラメータ

pOut
[in, out] 演算結果である D3DXVECTOR3 構造体へのポインタ。
pV
[in] 処理の基になる D3DXVECTOR3 構造体へのポインタ。
pM
[in] 処理の基になる D3DXMATRIX 構造体へのポインタ。

戻り値

トランスフォームされたベクトルの D3DXVECTOR3 構造体へのポインタ。

注意

この関数は、ベクトル pV (x, y, z, 1) を行列 pM によりトランスフォームし、その結果を w=1 に射影する。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec3TransformCoord 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXVec3Transform、D3DXVec3TransformNormal


D3DXVec3TransformNormal

指定された行列により 3D ベクトルを w = 0 でトランスフォームする。

D3DXVECTOR3* D3DXVec3TransformNormal(
  D3DXVECTOR3* pOut,
  CONST D3DXVECTOR3* pV,
  CONST D3DXMATRIX* pM
);

パラメータ

pOut
[in, out] 演算結果である D3DXVECTOR3 構造体へのポインタ。
pV
[in] 処理の基になる D3DXVECTOR3 構造体へのポインタ。
pM
[in] 処理の基になる D3DXMATRIX 構造体へのポインタ。

戻り値

トランスフォームされたベクトルの D3DXVECTOR3 構造体へのポインタ。

注意

この関数は、ベクトル pV のベクトル法線 (x, y, z, 0) を行列 pM によりトランスフォームする。

アフィン行列以外の行列で法線をトランスフォームする場合、この関数に渡す行列は、座標のトランスフォームに使用する行列の反転の転置とする必要がある。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec3TransformNormal 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXVec3Unproject

スクリーン空間からオブジェクト空間にベクトルを逆変換する。

D3DXVECTOR3* D3DXVec3Unproject(
  D3DXVECTOR3* pOut,
  CONST D3DXVECTOR3* pV
  CONST D3DVIEWPORT8* pViewport,
  CONST D3DXMATRIX* pProjection
  CONST D3DXMATRIX* pView,
  CONST D3DXMATRIX* pWorld
);

パラメータ

pOut
[in, out] 演算結果である D3DXVECTOR3 構造体へのポインタ。
pV
[in] 処理の基になる D3DXVECTOR3 構造体へのポインタ。
pViewport
[in] ビューポートを表す D3DVIEWPORT8 構造体へのポインタ。
pProjection
[in] 射影行列を表す D3DXMATRIX 構造体へのポインタ。
pView
[in] ビュー行列を表す D3DXMATRIX 構造体へのポインタ。
pWorld
[in] ワールド行列を表す D3DXMATRIX 構造体へのポインタ。

戻り値

スクリーン空間からスクリーン オブジェクトに射影されたベクトルである、D3DXVECTOR3 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec3Unproject 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXVec3Project


D3DXVec4Add

2 つの 4D ベクトルを加算する。

D3DXVECTOR4* D3DXVec4Add(
  D3DXVECTOR4* pOut,
  CONST D3DXVECTOR4* pV1,
  CONST D3DXVECTOR4* pV2
);

パラメータ

pOut
[in, out] 演算結果である D3DXVECTOR4 構造体へのポインタ。
pV1
[in] 処理の基になる D3DXVECTOR4 構造体へのポインタ。
pV2
[in] 処理の基になる D3DXVECTOR4 構造体へのポインタ。

戻り値

指定された 2 つのベクトルの合計である D3DXVECTOR4 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec4Add 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXVec4Subtract、D3DXVec4Scale


D3DXVec4BaryCentric

指定された 4D ベクトルを使用して重心座標のポイントを返す。

D3DXVECTOR4* D3DXVec4BaryCentric(
  D3DXVECTOR4* pOut,
  CONST D3DXVECTOR4* pV1,
  CONST D3DXVECTOR4* pV2,
  CONST D3DXVECTOR4* pV3,
  FLOAT f,
  FLOAT g
);

パラメータ

pOut
[in, out] 演算結果である D3DXVECTOR4 構造体へのポインタ。
pV1
[in] 処理の基になる D3DXVECTOR4 構造体へのポインタ。
pV2
[in] 処理の基になる D3DXVECTOR4 構造体へのポインタ。
pV3
[in] 処理の基になる D3DXVECTOR4 構造体へのポインタ。
f
[in] 加重係数。「注意」を参照すること。
g
[in] 加重係数。「注意」を参照すること。

戻り値

重心座標の D3DXVECTOR4 構造体へのポインタ。

注意

D3DXVec4BaryCentric 関数は、三角形の実際の位置とは関係なく、三角形の内部や周辺のポイントを理解する方法を提供している。この関数は、次の式を使用して結果であるポイントを返す。V1 + f(V2-V1) + g(V3-V1)

平面 V1V2V3 の任意のポイントは、重心座標 (f,g) で表すことができる。パラメータ f は V2 の結果に対する加重を制御し、パラメータ g は V3 の結果に対する加重を制御する。最後に、1-f-g は V1 の結果に対する加重を制御する。

次の関係に注意すること。

  • (f>=0 && g>=0 && 1-f-g>=0) の場合、ポイントは三角形 V1V2V3 内にある。
  • (f==0 && g>=0 && 1-f-g>=0) の場合、ポイントは直線 V1V3 上にある。
  • (f>=0 && g==0 && 1-f-g>=0) の場合、ポイントは直線 V1V2 上にある。
  • (f>=0 && g>=0 && 1-f-g==0) の場合、ポイントは直線 V2V3 上にある。

重心座標は、一般的な座標の形式である。ここで重心座標を使用するときは、単に座標系の変更を表している。デカルト座標で真のものは、重心座標でも真である。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec4BaryCentric 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXVec4CatmullRom

指定された 4D ベクトルを使用して、Catmull-Rom 補間を実行する。

D3DXVECTOR4* D3DXVec4CatmullRom(
  D3DXVECTOR4* pOut,
  CONST D3DXVECTOR4* pV1,
  CONST D3DXVECTOR4* pV2,
  CONST D3DXVECTOR4* pV3,
  CONST D3DXVECTOR4* pV4,
  FLOAT s
);

パラメータ

pOut
[in, out] 演算結果である D3DXVECTOR4 構造体へのポインタ。
pV1
[in] 位置ベクトルを示す、処理の基になる D3DXVECTOR4 構造体へのポインタ。
pV2
[in] 位置ベクトルを示す、処理の基になる D3DXVECTOR4 構造体へのポインタ。
pV3
[in] 位置ベクトルを示す、処理の基になる D3DXVECTOR4 構造体へのポインタ。
pV4
[in] 位置ベクトルを示す、処理の基になる D3DXVECTOR4 構造体へのポインタ。
s
[in] 加重係数。「注意」を参照すること。

戻り値

Catmull-Rom 補間の結果である D3DXVECTOR4 構造体へのポインタ。

注意

D3DXVec4CatmullRom 関数は、Catmull-Rom 補間を使用して、位置 V1 (s が 0 の場合) の間と、位置 V2 (s が 1 の場合) の間の補間を行う。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXVec4Cross

4 次元空間における外積を算出する。

D3DXVECTOR4* D3DXVec4Cross(
  D3DXVECTOR4* pOut,
  CONST D3DXVECTOR4* pV1,
  CONST D3DXVECTOR4* pV2,
  CONST D3DXVECTOR4* pV3
);

パラメータ

pOut
[in, out] 演算結果である D3DXVECTOR4 構造体へのポインタ。
pV1
[in] 処理の基になる D3DXVECTOR4 構造体へのポインタ。
pV2
[in] 処理の基になる D3DXVECTOR4 構造体へのポインタ。
pV3
[in] 処理の基になる D3DXVECTOR4 構造体へのポインタ。

戻り値

外積である D3DXVECTOR4 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec4Cross 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXVec4Dot


D3DXVec4Dot

2 つの 4D ベクトルの内積を算出する。

FLOAT D3DXVec4Dot(
  CONST D3DXVECTOR4* pV1,
  CONST D3DXVECTOR4* pV2
);

パラメータ

pV1
[in] 処理の基になる D3DXVECTOR4 構造体へのポインタ。
pV2
[in] 処理の基になる D3DXVECTOR4 構造体へのポインタ。

戻り値

内積。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXVec4Cross


D3DXVec4Hermite

指定された 4D ベクトルを使用して、エルミートのスプライン補間を実行する。

D3DXVECTOR4* D3DXVec4Hermite(
  D3DXVECTOR4* pOut,
  CONST D3DXVECTOR4* pV1,
  CONST D3DXVECTOR4* pT1,
  CONST D3DXVECTOR4* pV2,
  CONST D3DXVECTOR4* pT2,
  FLOAT s
);

パラメータ

pOut
[in, out] 演算結果である D3DXVECTOR4 構造体へのポインタ。
pV1
[in] 位置ベクトルを示す、処理の基になる D3DXVECTOR4 構造体へのポインタ。
pT1
[in] 接線ベクトルを示す、処理の基になる D3DXVECTOR4 構造体へのポインタ。
pV2
[in] 位置ベクトルを示す、処理の基になる D3DXVECTOR4 構造体へのポインタ。
pT2
[in] 接線ベクトルを示す、処理の基になる D3DXVECTOR4 構造体へのポインタ。
s
[in] 加重係数。「注意」を参照すること。

戻り値

エルミートのスプライン補間の結果である D3DXVECTOR4 構造体へのポインタ。

注意

D3DXVec4Hermite 関数は、エルミートのスプライン補間を使用して (positionA, tangentA) から (positionB, tangentB) へ補間する。この関数は、位置 V1 と接線 T1 の間 (s が 0 の場合) と、位置 V2 と接線 T2 の間 (s が 1 の場合) を補間する。

エルミートのスプラインは、カーブがすべての制御ポイントを通過するので、アニメーションを制御する場合に便利である。また、位置や接線が各セグメントの終点で明示的に指定されているので、起点と接線が最終セグメントの終点の値に一致するようにしている限り、C2 連続カーブを簡単に作成できる。

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec4Hermite 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXVec4Length

4D ベクトルの長さを返す。

FLOAT D3DXVec4Length(
  CONST D3DXVECTOR4* pV
);

パラメータ

pV
[in] 処理の基になる D3DXVECTOR4 構造体へのポインタ。

戻り値

ベクトルの長さ。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXVec4LengthSq


D3DXVec4LengthSq

4D ベクトルの長さの 2 乗を返す。

FLOAT D3DXVec4LengthSq(
  CONST D3DXVECTOR4* pV
);

パラメータ

pV
[in] 処理の基になる D3DXVECTOR4 構造体へのポインタ。

戻り値

ベクトルの長さの 2 乗。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXVec4Length


D3DXVec4Lerp

2 つの 4D ベクトル間の線形補間を実行する。

D3DXVECTOR4* D3DXVec4Lerp(
  D3DXVECTOR4* pOut,
  CONST D3DXVECTOR4* pV1,
  CONST D3DXVECTOR4* pV2,
  FLOAT s
);

パラメータ

pOut
[in, out] 演算結果である D3DXVECTOR4 構造体へのポインタ。
pV1
[in] 処理の基になる D3DXVECTOR4 構造体へのポインタ。
pV2
[in] 処理の基になる D3DXVECTOR4 構造体へのポインタ。
s
[in] ベクトル間を線形補間するパラメータ。

戻り値

線形補間の結果である D3DXVECTOR4 構造体へのポインタ。

注意

この関数は、次の式に基づいて線形補間を実行する。V1 + s(V2-V1)

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec4Lerp 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXVec4Maximize

2 つの 4D ベクトルの各要素の最大値から作成された 4D ベクトルを返す。

D3DXVECTOR4* D3DXVec4Maximize(
  D3DXVECTOR4* pOut,
  CONST D3DXVECTOR4* pV1,
  CONST D3DXVECTOR4* pV2
);

パラメータ

pOut
[in, out] 演算結果である D3DXVECTOR4 構造体へのポインタ。
pV1
[in] 処理の基になる D3DXVECTOR4 構造体へのポインタ。
pV2
[in] 処理の基になる D3DXVECTOR4 構造体へのポインタ。

戻り値

指定された 2 つのベクトルの最大値から作成した D3DXVECTOR4 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec4Maximize 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXVec4Minimize


D3DXVec4Minimize

2 つの 4D ベクトルの各要素の最小値から作成された 4D ベクトルを返す。

D3DXVECTOR4* D3DXVec4Minimize(
  D3DXVECTOR4* pOut,
  CONST D3DXVECTOR4* pV1,
  CONST D3DXVECTOR4* pV2
);

パラメータ

pOut
[in, out] 演算結果である D3DXVECTOR4 構造体へのポインタ。
pV1
[in] 処理の基になる D3DXVECTOR4 構造体へのポインタ。
pV2
[in] 処理の基になる D3DXVECTOR4 構造体へのポインタ。

戻り値

指定された 2 つのベクトルの最小値から作成した D3DXVECTOR4 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec4Minimize 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXVec4Maximize


D3DXVec4Normalize

4D ベクトルの正規化したベクトルを返す。

D3DXVECTOR4* D3DXVec4Normalize(
  D3DXVECTOR4* pOut,
  CONST D3DXVECTOR4* pV
);

パラメータ

pOut
[in, out] 演算結果である D3DXVECTOR4 構造体へのポインタ。
pV
[in] 処理の基になる D3DXVECTOR4 構造体へのポインタ。

戻り値

指定された正規化したベクトルの D3DXVECTOR4 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec4Normalize 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXVec4Scale

4D ベクトルをスケーリングする。

D3DXVECTOR4* D3DXVec4Scale(
  D3DXVECTOR4* pOut,
  CONST D3DXVECTOR4* pV,
  FLOAT s
);

パラメータ

pOut
[in, out] 演算結果である D3DXVECTOR4 構造体へのポインタ。
pV
[in] 処理の基になる D3DXVECTOR4 構造体へのポインタ。
s
[in] スケーリング値。

戻り値

スケーリングされたベクトルである D3DXVECTOR4 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec4Scale 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXVec4Add、D3DXVec4Subtract


D3DXVec4Subtract

2 つの 4D ベクトルを減算する。

D3DXVECTOR4* D3DXVec4Subtract(
  D3DXVECTOR4* pOut,
  CONST D3DXVECTOR4* pV1,
  CONST D3DXVECTOR4* pV2
);

パラメータ

pOut
[in, out] 演算結果である D3DXVECTOR4 構造体へのポインタ。
pV1
[in] 処理の基になる D3DXVECTOR4 構造体へのポインタ。
pV2
[in] 処理の基になる D3DXVECTOR4 構造体へのポインタ。

戻り値

2 つのベクトルの差分である D3DXVECTOR4 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec4Subtract 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXVec3Add、D3DXVec3Scale


D3DXVec4Transform

指定された行列により 4D ベクトルをトランスフォームする。

D3DXVECTOR4* D3DXVec4Transform(
  D3DXVECTOR4* pOut,
  CONST D3DXVECTOR4* pV,
  CONST D3DXMATRIX* pM
);

パラメータ

pOut
[in, out] 演算結果である D3DXVECTOR4 構造体へのポインタ。
pV
[in] 処理の基になる D3DXVECTOR4 構造体へのポインタ。
pM
[in] 処理の基になる D3DXMATRIX 構造体へのポインタ。

戻り値

トランスフォームされた 4D ベクトルの D3DXVECTOR4 構造体へのポインタ。

注意

この関数の戻り値は、pOut パラメータの戻り値と同じである。このように、D3DXVec4Transform 関数を別の関数のパラメータとして使用できる。

動作環境

ヘッダー : D3dx8math.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


メッシュ関数

Direct3DX では次のメッシュ関数が用意されている。

  • D3DXBoxBoundProbe
  • D3DXCleanMesh
  • D3DXComputeBoundingBox
  • D3DXComputeBoundingSphere
  • D3DXComputeNormals
  • D3DXCreateBuffer
  • D3DXCreateMesh
  • D3DXCreateMeshFVF
  • D3DXCreatePMeshFromStream
  • D3DXCreateSkinMesh
  • D3DXCreateSkinMeshFromMesh
  • D3DXCreateSkinMeshFVF
  • D3DXCreateSPMesh
  • D3DXDeclaratorFromFVF
  • D3DXFVFFromDeclarator
  • D3DXGeneratePMesh
  • D3DXIntersect
  • D3DXLoadMeshFromX
  • D3DXLoadMeshFromXof
  • D3DXLoadSkinMeshFromXof
  • D3DXSaveMeshToX
  • D3DXSimplifyMesh
  • D3DXSphereBoundProbe
  • D3DXTesselateMesh
  • D3DXValidMesh
  • D3DXWeldVertices


D3DXBoxBoundProbe

レイがボックスの境界ボックスのボリュームに当たるかどうかを判定する。

BOOL D3DXBoxBoundProbe(
  CONST D3DXVECTOR3* pMin,
  CONST D3DXVECTOR3* pMax,
  D3DXVECTOR3* pRayPosition,
  D3DXVECTOR3* pRayDirection
);

パラメータ

pMin
[out] 境界ボックスの左下隅を記述する、D3DXVECTOR3 構造体へのポインタ。「注意」を参照すること。
pMax
[out] 境界ボックスの右上隅を記述する、D3DXVECTOR3 構造体へのポインタ。「注意」を参照すること。
pRayPosition
[in] レイの始点座標を指定する D3DXVECTOR3 構造体へのポインタ。
pRayDirection
[in] レイの方向を指定する D3DXVECTOR3 構造体へのポインタ。

戻り値

レイがボックスの境界ボックスのボリュームに当たる場合は、TRUE を返す。それ以外の場合は、FALSE を返す。

注意

D3DXBoxBoundProbe は、レイがボックスのサーフェスだけではなく、ボックスの境界ボックスのボリュームに当たるかどうかを判定する。

D3DXBoxBoundProbe に渡される D3DXVECTOR3 の値は、xmin、xmax、ymin、ymax、zmin、zmax である。したがって、境界ボックスの角の定義は次のようになる。

xmax, ymax, zmax
xmax, ymax, zmin
xmax, ymin, zmax
xmax, ymin, zmin
xmin, ymax, zmax
xmin, ymax, zmin
xmin, ymin, zmax
xmin, ymin, zmin

境界ボックスの深度は、z 方向が zmax - zmin、y 方向が ymax - ymin、そして x 方向が xmax - xmin である。たとえば、最小ベクトルが min (-1, -1, -1)、最大ベクトルが (1, 1, 1) の場合、境界ボックスの定義は次のようになる。

 1,  1,  1
 1,  1, -1
 1, -1,  1
 1, -1, -1
-1,  1,  1
-1,  1, -1
-1, -1,  1
-1, -1, -1

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXComputeBoundingBox


D3DXCleanMesh

単純化の準備として、メッシュのクリーニングを行う。

HRESULT D3DXCleanMesh(
  LPD3DXMESH pMeshIn,
  CONST DWORD* pAdjacency,
  LPD3DXMESH* ppMeshOut
);

パラメータ

pMeshIn
[in] クリーニングするメッシュを表す、ID3DXMesh インターフェイスへのポインタ。
pAdjacency
[in] クリーニングするメッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの DWORD の配列へのポインタ。
ppMeshOut
[out] クリーニングされたメッシュを表す、ID3DXMesh インターフェイスへのポインタのアドレス。クリーニングの必要がない場合は、渡したメッシュと同じメッシュが返される。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

注意

このメソッドは、2 つの三角形ファンが同じ頂点を共有している場合に、頂点を追加することによってメッシュのクリーニングを行う。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXComputeBoundingBox

境界ボックスを算出する。

HRESULT D3DXComputeBoundingBox(
  PVOID pPointsFVF,
  DWORD NumVertices,
  DWORD FVF,
  D3DXVECTOR3* pMin,
  D3DXVECTOR3* pMax
);

パラメータ

pPointsFVF
[in] 境界ボックスの算出に使用する頂点データを格納するバッファへのポインタ。
NumVertices
[in] 頂点の数。
FVF
[in] 頂点フォーマットを記述する柔軟な頂点フォーマット フラグの組み合わせ。
pMin
[out] 境界ボックスの左下隅を記述する、D3DXVECTOR3 構造体へのポインタ。「注意」を参照すること。
pMax
[out] 境界ボックスの右上隅を記述する、D3DXVECTOR3 構造体へのポインタ。「注意」を参照すること。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、1 つの D3DERR_INVALIDCALL を返す。

注意

D3DXComputeBoundingBox が返す D3DXVECTOR3 の値は、xmin、xmax、ymin、ymax、zmin、zmax である。したがって、境界ボックスの角の定義は次のようになる。

xmax, ymax, zmax
xmax, ymax, zmin
xmax, ymin, zmax
xmax, ymin, zmin
xmin, ymax, zmax
xmin, ymax, zmin
xmin, ymin, zmax
xmin, ymin, zmin

境界ボックスの深度は、z 方向が zmax - zmin、y 方向が ymax - ymin、そして x 方向が xmax - xmin である。たとえば、最小ベクトルが min (-1, -1, -1)、最大ベクトルが (1, 1, 1) の場合、境界ボックスの定義は次のようになる。

 1,  1,  1
 1,  1, -1
 1, -1,  1
 1, -1, -1
-1,  1,  1
-1,  1, -1
-1, -1,  1
-1, -1, -1

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXComputeBoundingSphere

境界球を算出する。

HRESULT D3DXComputeBoundingSphere(
  PVOID pvPointsFVF,
  DWORD NumVertices,
  DWORD FVF,
  D3DXVECTOR3* pCenter,
  FLOAT* pRadius
);

パラメータ

pvPointsFVF
[in] 境界球の算出に使用する頂点データを格納するバッファへのポインタ。
NumVertices
[in] 頂点の数。
FVF
[in] 頂点フォーマットを記述する柔軟な頂点フォーマット フラグの組み合わせ。
pCenter
[out] 境界球の座標の中心を定義する、D3DXVECTOR3 構造体。
pRadius
[out] 境界球の半径。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、1 つの D3DERR_INVALIDCALL を返す。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXComputeNormals

メッシュに含まれる各頂点の法線を算出する。

HRESULT D3DXComputeNormals(
  LPD3DXBASEMESH pMesh
);

パラメータ

pMesh
[in, out] 正規化されたメッシュ オブジェクトを表す、ID3DXBaseMesh インターフェイスへのポインタ。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、1 つの D3DERR_INVALIDCALL を返す。

注 入力メッシュの FVF に D3DFVF_NORMAL フラグが指定されている必要がある。

頂点の法線は、その頂点を共有するすべての面の法線を平均することにより、生成される。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXCreateBuffer

バッファ オブジェクトを作成する。

HRESULT D3DXCreateBuffer(
  DWORD NumBytes,
  LPD3DXBUFFER* ppBuffer
);

パラメータ

NumBytes
[in] 作成するバッファのサイズ (バイト単位)。
ppBuffer
[out] 作成されたバッファ オブジェクトを表す、ID3DXBuffer インターフェイスへのポインタのアドレス。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、1 つの E_OUTOFMEMORY を返す。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXCreateMesh

宣言子を使用してメッシュ オブジェクトを作成する。

HRESULT D3DXCreateMesh(
  DWORD NumFaces,
  DWORD NumVertices,
  DWORD Options,
  CONST DWORD* pDeclaration,
  LPDIRECT3DDEVICE8 pDevice,
  LPD3DXMESH* ppMesh
);

パラメータ

NumFaces
[in] メッシュの面の数。このパラメータは 1 以上でなければならない。
NumVertices
[in] メッシュの頂点の数。このパラメータは 1 以上でなければならない。
Options
[in] メッシュに対するオプションを指定する、1 つ以上のフラグの組み合わせ。次のフラグが定義されている。
D3DXMESH_32BIT
メッシュに、16 ビットではなく 32 ビットのインデックスを作成する。32 ビットのメッシュは、最大 2^32-1 の面と頂点を含むことができる。このフラグはサポートされていないため使用できない。
D3DXMESH_DONOTCLIP
頂点バッファおよびインデックス バッファに D3DUSAGE_DONOTCLIP 利用フラグを使用する。
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC と D3DXMESH_IB_DYNAMIC の両方を指定したことになる。
D3DXMESH_RTPATCHES
頂点バッファおよびインデックス バッファに D3DUSAGE_RTPATCHES 利用フラグを使用する。
D3DXMESH_NPATCHES
このフラグを指定すると、メッシュの頂点バッファとインデックス バッファが D3DUSAGE_NPATCHES フラグを指定して作成される。これは、メッシュ オブジェクトを N パッチ エンハンスメントを使って Microsoft® Direct3D® でレンダリングする場合に必要となる。
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED と D3DXMESH_IB_MANAGED の両方を指定したことになる。
D3DXMESH_POINTS
頂点バッファおよびインデックス バッファに D3DUSAGE_POINTS 利用フラグを使用する。
D3DXMESH_IB_DYNAMIC
インデックス バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_IB_MANAGED
インデックス バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_IB_SYSTEMMEM
インデックス バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_IB_WRITEONLY
インデックス バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM と D3DXMESH_IB_SYSTEMMEM の両方を指定したことになる。
D3DXMESH_VB_DYNAMIC
頂点バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_VB_MANAGED
頂点バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_VB_SYSTEMMEM
頂点バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_VB_WRITEONLY
頂点バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY と D3DXMESH_IB_WRITEONLY の両方を指定したことになる。
pDeclaration
[in] 返されたメッシュの頂点フォーマットを記述する宣言子を表す、DWORD 値へのポインタ。このパラメータは FVF を直接マップする必要がある。
pDevice
[in] メッシュに関連付けられているデバイス オブジェクトを表す IDirect3DDevice8 インターフェイスへのポインタ。
ppMesh
[out] 作成されたメッシュ オブジェクトを表す ID3DXMesh インターフェイスへのポインタのアドレス。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXDeclaratorFromFVF


D3DXCreateMeshFVF

柔軟な頂点フォーマット (FVF) コードを使用してメッシュ オブジェクトを作成する。

HRESULT D3DXCreateMeshFVF(
  DWORD NumFaces,
  DWORD NumVertices,
  DWORD Options,
  DWORD FVF,
  LPDIRECT3DDEVICE8 pDevice,
  LPD3DXMESH* ppMesh
);

パラメータ

NumFaces
[in] メッシュの面の数。このパラメータは 1 以上でなければならない。
NumVertices
[in] メッシュの頂点の数。このパラメータは 1 以上でなければならない。
Options
[in] メッシュの作成オプションを指定する 1 つ以上のフラグの組み合わせ。次のフラグが定義されている。
D3DXMESH_32BIT
メッシュに、16 ビットではなく 32 ビットのインデックスを作成する。32 ビットのメッシュは、最大 2^32-1 の面と頂点を含むことができる。このフラグはサポートされていないため使用できない。
D3DXMESH_DONOTCLIP
頂点バッファおよびインデックス バッファに D3DUSAGE_DONOTCLIP 利用フラグを使用する。
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC と D3DXMESH_IB_DYNAMIC の両方を指定したことになる。
D3DXMESH_RTPATCHES
頂点バッファおよびインデックス バッファに D3DUSAGE_RTPATCHES 利用フラグを使用する。
D3DXMESH_NPATCHES
このフラグを指定すると、メッシュの頂点バッファとインデックス バッファが D3DUSAGE_NPATCHES フラグを指定して作成される。これは、メッシュ オブジェクトを N パッチ エンハンスメントを使って Microsoft® Direct3D® でレンダリングする場合に必要となる。
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED と D3DXMESH_IB_MANAGED の両方を指定したことになる。
D3DXMESH_POINTS
頂点バッファおよびインデックス バッファに D3DUSAGE_POINTS 利用フラグを使用する。
D3DXMESH_IB_DYNAMIC
インデックス バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_IB_MANAGED
インデックス バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_IB_SYSTEMMEM
インデックス バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_IB_WRITEONLY
インデックス バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM と D3DXMESH_IB_SYSTEMMEM の両方を指定したことになる。
D3DXMESH_VB_DYNAMIC
頂点バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_VB_MANAGED
頂点バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_VB_SYSTEMMEM
頂点バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_VB_WRITEONLY
頂点バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY と D3DXMESH_IB_WRITEONLY の両方を指定したことになる。
FVF
[in] メッシュの頂点フォーマットを記述する、柔軟な頂点フォーマット フラグの組み合わせ。
pDevice
[in] メッシュに関連付けられているデバイス オブジェクトを表す IDirect3DDevice8 インターフェイスへのポインタ。
ppMesh
[out] 作成されたメッシュ オブジェクトを表す ID3DXMesh インターフェイスへのポインタのアドレス。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXFVFFromDeclarator


D3DXCreatePMeshFromStream

ストリーム オブジェクトからプログレッシブ メッシュを作成する。

HRESULT D3DXCreatePMeshFromStream(
  IStream* pStream,
  DWORD Options,
  LPDIRECT3DDEVICE8 pD3DDevice,
  LPD3DXBUFFER* ppMaterials,
  DWORD* pNumMaterials,
  LPD3DXPMESH* ppPMesh
);

パラメータ

pStream
[in] プログレッシブ メッシュ作成の元となるストリーム オブジェクトを表す IStream インターフェイスへのポインタ。このストリームのデータは、ID3DXPMesh::Save メソッドで生成されている。
Options
[in] メッシュの作成オプションを指定する 1 つ以上のフラグの組み合わせ。次のフラグが定義されている。
D3DXMESH_32BIT
メッシュに、16 ビットではなく 32 ビットのインデックスを作成する。32 ビットのメッシュは、最大 2^32-1 の面と頂点を含むことができる。このフラグはサポートされていないため使用できない。
D3DXMESH_DONOTCLIP
頂点バッファおよびインデックス バッファに D3DUSAGE_DONOTCLIP 利用フラグを使用する。
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC と D3DXMESH_IB_DYNAMIC の両方を指定したことになる。
D3DXMESH_RTPATCHES
頂点バッファおよびインデックス バッファに D3DUSAGE_RTPATCHES 利用フラグを使用する。
D3DXMESH_NPATCHES
このフラグを指定すると、メッシュの頂点バッファとインデックス バッファが D3DUSAGE_NPATCHES フラグを指定して作成される。これは、メッシュ オブジェクトを N パッチ エンハンスメントを使って Microsoft® Direct3D® でレンダリングする場合に必要となる。
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED と D3DXMESH_IB_MANAGED の両方を指定したことになる。
D3DXMESH_POINTS
頂点バッファおよびインデックス バッファに D3DUSAGE_POINTS 利用フラグを使用する。
D3DXMESH_IB_DYNAMIC
インデックス バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_IB_MANAGED
インデックス バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_IB_SYSTEMMEM
インデックス バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_IB_WRITEONLY
インデックス バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM と D3DXMESH_IB_SYSTEMMEM の両方を指定したことになる。
D3DXMESH_VB_DYNAMIC
頂点バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_VB_MANAGED
頂点バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_VB_SYSTEMMEM
頂点バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_VB_WRITEONLY
頂点バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY と D3DXMESH_IB_WRITEONLY の両方を指定したことになる。
pD3DDevice
[in] プログレッシブ メッシュに関連付けられるデバイス オブジェクトである、IDirect3DDevice8 インターフェイスへのポインタ。
ppMaterials
[out] ID3DXBuffer インターフェイスへのポインタのアドレス。メソッドが返ると、このパラメータには、ストリーム オブジェクトに保存された情報を格納する D3DXMATERIAL 構造体の配列が入力される。
pNumMaterials
[out] メソッドが戻ったときの ppMaterials 配列内の D3DXMATERIAL 構造体の数へのポインタ。
ppPMesh
[out] 作成されたプログレッシブ メッシュを表す、ID3DXPMesh インターフェイスへのポインタのアドレス。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

注意

IStream インターフェイスの詳細については、Microsoft Platform Software Development Kit (SDK) を参照すること。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXPMesh::Save


D3DXCreateSkinMesh

宣言子を使用して空のスキン メッシュ オブジェクトを作成する。

HRESULT D3DXCreateSkinMesh(
  DWORD numFaces,
  DWORD numVertices,
  DWORD numBones,
  DWORD Options,
  CONST DWORD* pDeclaration,
  LPDIRECT3DDEVICE8 pDevice,
  LPD3DXSKINMESH* ppSkinMesh
);

パラメータ

numFaces
[in] スキン メッシュの面の数。
numVertices
[in] スキン メッシュの頂点の数。
numBones
[in] スキン メッシュのボーンの数。
Options
[in] メッシュの作成オプションを指定する 1 つ以上のフラグの組み合わせ。次のフラグが定義されている。
D3DXMESH_32BIT
メッシュに、16 ビットではなく 32 ビットのインデックスを作成する。32 ビットのメッシュは、最大 2^32-1 の面と頂点を含むことができる。このフラグはサポートされていないため使用できない。
D3DXMESH_DONOTCLIP
頂点バッファおよびインデックス バッファに D3DUSAGE_DONOTCLIP 利用フラグを使用する。
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC と D3DXMESH_IB_DYNAMIC の両方を指定したことになる。
D3DXMESH_RTPATCHES
頂点バッファおよびインデックス バッファに D3DUSAGE_RTPATCHES 利用フラグを使用する。
D3DXMESH_NPATCHES
このフラグを指定すると、メッシュの頂点バッファとインデックス バッファが D3DUSAGE_NPATCHES フラグを指定して作成される。これは、メッシュ オブジェクトを N パッチ エンハンスメントを使って Microsoft® Direct3D® でレンダリングする場合に必要となる。
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED と D3DXMESH_IB_MANAGED の両方を指定したことになる。
D3DXMESH_POINTS
頂点バッファおよびインデックス バッファに D3DUSAGE_POINTS 利用フラグを使用する。
D3DXMESH_IB_DYNAMIC
インデックス バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_IB_MANAGED
インデックス バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_IB_SYSTEMMEM
インデックス バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_IB_WRITEONLY
インデックス バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM と D3DXMESH_IB_SYSTEMMEM の両方を指定したことになる。
D3DXMESH_VB_DYNAMIC
頂点バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_VB_MANAGED
頂点バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_VB_SYSTEMMEM
頂点バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_VB_WRITEONLY
頂点バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY と D3DXMESH_IB_WRITEONLY の両方を指定したことになる。
pDeclaration
[in] 返されたスキン メッシュの頂点フォーマットを記述する宣言子を表す、DWORD 値へのポインタ。
pDevice
[in] スキン メッシュに関連付けられるデバイス オブジェクトである、IDirect3DDevice8 インターフェイスへのポインタ。
ppSkinMesh
[out, retval] 作成されたスキン メッシュ オブジェクトを表す ID3DXSkinMesh インターフェイスへのポインタのアドレス。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、E_OUTOFMEMORY を返す。

注意

このメソッドで返される空のスキン メッシュ オブジェクトにデータを代入するには、ID3DXSkinMesh::SetBoneInfluence を使用する。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXSkinMesh::SetBoneInfluence


D3DXCreateSkinMeshFromMesh

別のメッシュからスキン メッシュを作成する。

HRESULT D3DXCreateSkinMeshFromMesh(
  LPD3DXMESH pMesh,
  DWORD numBones,
  LPD3DXSKINMESH* ppSkinMesh
);

パラメータ

pMesh
[in] スキン メッシュ作成の元となるメッシュである ID3DXMesh オブジェクトへのポインタ。
numBones
[in] スキン メッシュのボーンの数。
ppSkinMesh
[out, retval] 作成されたスキン メッシュ オブジェクトを表す ID3DXSkinMesh インターフェイスへのポインタのアドレス。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、E_OUTOFMEMORY を返す。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXCreateSkinMeshFVF

柔軟な頂点フォーマット (FVF) コードを使用して空のスキン メッシュ オブジェクトを作成する。

HRESULT D3DXCreateSkinMeshFVF(
  DWORD numFaces,
  DWORD numVertices,
  DWORD numBones,
  DWORD Options,
  DWORD FVF,
  LPDIRECT3DDEVICE8 pDevice,
  LPD3DXSKINMESH* ppSkinMesh
);

パラメータ

numFaces
[in] スキン メッシュの面の数。
numVertices
[in] スキン メッシュの頂点の数。
numBones
[in] スキン メッシュのボーンの数。
Options
[in] メッシュの作成オプションを指定する 1 つ以上のフラグの組み合わせ。次のフラグが定義されている。
D3DXMESH_32BIT
メッシュに、16 ビットではなく 32 ビットのインデックスを作成する。32 ビットのメッシュは、最大 2^32-1 の面と頂点を含むことができる。このフラグはサポートされていないため使用できない。
D3DXMESH_DONOTCLIP
頂点バッファおよびインデックス バッファに D3DUSAGE_DONOTCLIP 利用フラグを使用する。
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC と D3DXMESH_IB_DYNAMIC の両方を指定したことになる。
D3DXMESH_RTPATCHES
頂点バッファおよびインデックス バッファに D3DUSAGE_RTPATCHES 利用フラグを使用する。
D3DXMESH_NPATCHES
このフラグを指定すると、メッシュの頂点バッファとインデックス バッファが D3DUSAGE_NPATCHES フラグを指定して作成される。これは、メッシュ オブジェクトを N パッチ エンハンスメントを使って Microsoft® Direct3D® でレンダリングする場合に必要となる。
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED と D3DXMESH_IB_MANAGED の両方を指定したことになる。
D3DXMESH_POINTS
頂点バッファおよびインデックス バッファに D3DUSAGE_POINTS 利用フラグを使用する。
D3DXMESH_IB_DYNAMIC
インデックス バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_IB_MANAGED
インデックス バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_IB_SYSTEMMEM
インデックス バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_IB_WRITEONLY
インデックス バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM と D3DXMESH_IB_SYSTEMMEM の両方を指定したことになる。
D3DXMESH_VB_DYNAMIC
頂点バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_VB_MANAGED
頂点バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_VB_SYSTEMMEM
頂点バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_VB_WRITEONLY
頂点バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY と D3DXMESH_IB_WRITEONLY の両方を指定したことになる。
FVF
[in] スキン メッシュの頂点フォーマットを記述する、柔軟な頂点フォーマット フラグの組み合わせ。
pDevice
[in] スキン メッシュに関連付けられるデバイス オブジェクトである、IDirect3DDevice8 インターフェイスへのポインタ。
ppSkinMesh
[out, retval] 作成されたスキン メッシュ オブジェクトを表す ID3DXSkinMesh インターフェイスへのポインタのアドレス。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

注意

このメソッドで返される空のスキン メッシュ オブジェクトにデータを代入するには、ID3DXSkinMesh::SetBoneInfluence を使用する。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

ID3DXSkinMesh::SetBoneInfluence


D3DXCreateSPMesh

単純化メッシュを作成する。

HRESULT D3DXCreateSPMesh(
  LPD3DXMESH pMesh,
  CONST DWORD* pAdjacency,
  CONST LPD3DXATTRIBUTEWEIGHTS pVertexAttributeWeights,
  CONST FLOAT* pVertexWeights,
  LPD3DXSPMESH* ppSMesh
);

パラメータ

pMesh
[in] 単純化するメッシュを表す、ID3DXMesh インターフェイスへのポインタ。
pAdjacency
[in] 作成された単純化メッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの DWORD の配列へのポインタ。
pVertexAttributeWeights
[in] 各頂点の成分に対する加重を格納する D3DXATTRIBUTEWEIGHTS 構造体へのポインタ。このパラメータを NULL に設定すると、デフォルトの構造体が使用される。「注意」を参照すること。
pVertexWeights
[in] 頂点加重の配列へのポインタ。このパラメータを NULL に設定すると、すべての頂点加重は 1.0 に設定される。指定された頂点の頂点加重が大きいほど、単純化しにくいことに注意する。
ppSMesh
[out] 作成された単純化メッシュを表す、ID3DXSPMesh インターフェイスへのポインタのアドレス。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DXERR_CANNOTATTRSORT
D3DERR_INVALIDCALL
E_OUTOFMEMORY

注意

単純化メッシュは、メッシュを単純化して、三角形と面の数を減らすために使用する。

pVertexAttributeWeights を NULL に設定した場合、次に示す値がデフォルトの D3DXATTRIBUTEWEIGHTS 構造体に割り当てられる。

D3DXATTRIBUTEWEIGHTS AttributeWeights;

AttributeWeights.Position  = 1.0;
AttributeWeights.Boundary =  1.0;
AttributeWeights.Normal   =  1.0;
AttributeWeights.Diffuse  =  0.0;
AttributeWeights.Specular =  0.0;
AttributeWeights.Tex[8]   =  {0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0};

通常のアプリケーションでは、このデフォルトの構造体を使用すべきである。理由は、この構造体がジオメトリと法線の調整のみを目的としているからである。その他のメンバ フィールドを修正する必要があるのは、特別な場合のみである。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXDeclaratorFromFVF

柔軟な頂点フォーマット (FVF) コードから宣言子を返す。

HRESULT D3DXDeclaratorFromFVF(
  DWORD FVF,
  DWORD Declaration[MAX_FVF_DECL_SIZE]
);

パラメータ

FVF
[in] 宣言子の配列を生成する元となる FVF を記述する、柔軟な頂点フォーマット フラグの組み合わせ。
Declaration
[out] 照会されたメッシュに含まれる頂点の頂点フォーマットを記述する返された配列。この宣言子の配列の上限は MAX_FVF_DECL_SIZE で、宣言子を 15 DWORD の最大数に制限する。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、1 つのD3DXERR_INVALIDMESH を返す。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXFVFFromDeclarator


D3DXFVFFromDeclarator

宣言子から柔軟な頂点フォーマット (FVF) コードを返す。

HRESULT D3DXFVFFromDeclarator(
  CONST DWORD* pDeclarator,
  DWORD* pFVF
);

パラメータ

pDeclarator
[in] FVF コードを生成する元となる宣言子を表す、DWORD 値へのポインタ。
pFVF
[out] 宣言子から返される頂点フォーマットを記述する柔軟な頂点フォーマット フラグの組み合わせを表す、DWORD 値へのポインタ。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注 この関数は、FVF を直接マップしない宣言子では失敗する。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXDeclaratorFromFVF


D3DXGeneratePMesh

プログレッシブ メッシュを生成する。

HRESULT D3DXGeneratePMesh(
  LPD3DXMESH pMesh,
  CONST DWORD* pAdjacency,
  CONST LPD3DXATTRIBUTEWEIGHTS pVertexAttributeWeights,
  CONST FLOAT* pVertexWeights,
  DWORD MinValue,
  DWORD Options,
  LPD3DXPMESH* ppPMesh
);

パラメータ

pMesh
[in] ソース メッシュを表す ID3DXMesh インターフェイスへのポインタ。
pAdjacency
[in] 作成されたプログレッシブ メッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの DWORD の配列へのポインタ。
pVertexAttributeWeights
[in] 各頂点の成分に対する加重を格納する D3DXATTRIBUTEWEIGHTS 構造体へのポインタ。このパラメータを NULL に設定すると、デフォルトの構造体が使用される。「注意」を参照すること。
pVertexWeights
[in] 頂点加重の配列へのポインタ。このパラメータを NULL に設定すると、すべての頂点加重は 1.0 に設定される。頂点加重が大きいほど、単純化されにくいことに注意する。
MinValue
[in] Options パラメータに設定されているフラグに応じた頂点または面の数。これによって、ソース メッシュが単純化される。
Options
[in] メッシュに対して単純化オプションを指定する。次のいずれかのフラグを設定できる。
D3DXMESHSIMP_FACE
MinValue パラメータに指定した数の面でメッシュが単純化される。
D3DXMESHSIMP_VERTEX
MinValue パラメータに指定した数の頂点でメッシュが単純化される。
ppPMesh
[out] 作成されたプログレッシブ メッシュを表す、ID3DXPMesh インターフェイスへのポインタのアドレス。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DXERR_CANNOTATTRSORT
D3DERR_INVALIDCALL
E_OUTOFMEMORY

注意

この関数は、LOD (Level of Detail) を現在の値から MinValue まで調節可能な場合にメッシュを生成する。

単純化プロセスによってメッシュを MinValue まで減らすことができない場合でも呼び出しは継続される。これは、MinValue が絶対的な最小値ではなく、希望の最小値であるからである。

pVertexAttributeWeights を NULL に設定した場合、次に示す値がデフォルトの D3DXATTRIBUTEWEIGHTS 構造体に割り当てられる。

D3DXATTRIBUTEWEIGHTS AttributeWeights;

AttributeWeights.Position  = 1.0;
AttributeWeights.Boundary =  1.0;
AttributeWeights.Normal   =  1.0;
AttributeWeights.Diffuse  =  0.0;
AttributeWeights.Specular =  0.0;
AttributeWeights.Tex[8]   =  {0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0};

通常のアプリケーションでは、このデフォルトの構造体を使用すべきである。理由は、この構造体がジオメトリと法線の調整のみを目的としているからである。その他のメンバ フィールドを修正する必要があるのは、特別な場合のみである。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXIntersect

レイがメッシュに当たるかどうかを判定する。

HRESULT D3DXIntersect(
  LPD3DXBASEMESH pMesh,
  CONST D3DXVECTOR3* pRayPos,
  CONST D3DXVECTOR3* pRayDir,
  BOOL* pHit,
  DWORD* pFaceIndex,
  FLOAT* pU,
  FLOAT* pV,
  FLOAT* pDist
);

パラメータ

pMesh
[in] 検証するメッシュを表す、ID3DXBaseMesh インターフェイスへのポインタ。
pRayPos
[in] レイの始点座標を指定する D3DXVECTOR3 構造体へのポインタ。
pRayDir
[in] レイの方向を指定する D3DXVECTOR3 構造体へのポインタ。
pHit
[out] BOOL へのポインタ。レイがメッシュの三角形の面に当たる場合、この値は TRUE に設定される。それ以外の場合、この値は FALSE に設定される。
pFaceIndex
[out] pHit が TRUE の場合、レイの始点に最も近い面のインデックス値へのポインタ。
pU
[out] 重心ヒット座標へのポインタ。
pV
[out] 重心ヒット座標へのポインタ。
pDist
[out] レイの始点から交点までの距離へのポインタ。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、E_OUTOFMEMORY を返す。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXLoadMeshFromX

Microsoft® DirectX® (.x) ファイルからメッシュをロードする。

HRESULT D3DXLoadMeshFromX(
  LPSTR pFilename,
  DWORD Options,
  LPDIRECT3DDEVICE8 pDevice,
  LPD3DXBUFFER* ppAdjacency,
  LPD3DXBUFFER* ppMaterials,
  PDWORD pNumMaterials,
  LPD3DXMESH* ppMesh
);

パラメータ

pFilename
[in] ロードする DirectX ファイルの名前を指定する文字列へのポインタ。
Options
[in] メッシュの作成オプションを指定する 1 つ以上のフラグの組み合わせ。次のフラグが定義されている。
D3DXMESH_32BIT
メッシュに、16 ビットではなく 32 ビットのインデックスを作成する。32 ビットのメッシュは、最大 2^32-1 の面と頂点を含むことができる。このフラグはサポートされていないため使用できない。
D3DXMESH_DONOTCLIP
頂点バッファおよびインデックス バッファに D3DUSAGE_DONOTCLIP 利用フラグを使用する。
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC と D3DXMESH_IB_DYNAMIC の両方を指定したことになる。
D3DXMESH_RTPATCHES
頂点バッファおよびインデックス バッファに D3DUSAGE_RTPATCHES 利用フラグを使用する。
D3DXMESH_NPATCHES
このフラグを指定すると、メッシュの頂点バッファとインデックス バッファが D3DUSAGE_NPATCHES フラグを指定して作成される。これは、メッシュ オブジェクトを N パッチ エンハンスメントを使って Microsoft® Direct3D® でレンダリングする場合に必要となる。
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED と D3DXMESH_IB_MANAGED の両方を指定したことになる。
D3DXMESH_POINTS
頂点バッファおよびインデックス バッファに D3DUSAGE_POINTS 利用フラグを使用する。
D3DXMESH_IB_DYNAMIC
インデックス バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_IB_MANAGED
インデックス バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_IB_SYSTEMMEM
インデックス バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_IB_WRITEONLY
インデックス バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM と D3DXMESH_IB_SYSTEMMEM の両方を指定したことになる。
D3DXMESH_VB_DYNAMIC
頂点バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_VB_MANAGED
頂点バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_VB_SYSTEMMEM
頂点バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_VB_WRITEONLY
頂点バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY と D3DXMESH_IB_WRITEONLY の両方を指定したことになる。
pDevice
[in] メッシュに関連付けられているデバイス オブジェクトを表す IDirect3DDevice8 インターフェイスへのポインタ。
ppAdjacency
[out] ID3DXBuffer インターフェイスへのポインタのアドレス。メソッドが返ると、このパラメータには、メッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの DWORD の配列が入力される。
ppMaterials
[out] ID3DXBuffer インターフェイスへのポインタのアドレス。メソッドが返ると、このパラメータには、Microsoft® DirectX® ファイルに保存された情報を格納する D3DXMATERIAL 構造体の配列が入力される。
pNumMaterials
[out] メソッドが戻ったときの ppMaterials 配列内の D3DXMATERIAL 構造体の数へのポインタ。
ppMesh
[out] ロードされたメッシュを表す ID3DXMesh インターフェイスへのポインタのアドレス。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

注 ファイル内のすべてのメッシュが 1 つの出力メッシュにまとめられる。ファイルにフレーム階層が格納されている場合、すべてのトランスフォームがメッシュに適用される。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXLoadMeshFromXof

Microsoft® DirectX® (.x) ファイル データ オブジェクトからメッシュをロードする。

HRESULT D3DXLoadMeshFromXof(
  LPDIRECTXFILEDATA pXofObjMesh,
  DWORD Options,
  LPDIRECT3DDEVICE8 pD3DDevice,
  LPD3DXBUFFER* ppAdjacency,
  LPD3DXBUFFER* ppMaterials,
  PDWORD pNumMaterials,
  LPD3DXMESH* ppMesh
);

パラメータ

pXofObjMesh
[in] ロードする Microsoft® DirectX® ファイル データ オブジェクトを表す、IDirectXFileData インターフェイスへのポインタ。
Options
[in] メッシュの作成オプションを指定する 1 つ以上のフラグの組み合わせ。次のフラグが定義されている。
D3DXMESH_32BIT
メッシュに、16 ビットではなく 32 ビットのインデックスを作成する。32 ビットのメッシュは、最大 2^32-1 の面と頂点を含むことができる。このフラグはサポートされていないため使用できない。
D3DXMESH_DONOTCLIP
頂点バッファおよびインデックス バッファに D3DUSAGE_DONOTCLIP 利用フラグを使用する。
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC と D3DXMESH_IB_DYNAMIC の両方を指定したことになる。
D3DXMESH_RTPATCHES
頂点バッファおよびインデックス バッファに D3DUSAGE_RTPATCHES 利用フラグを使用する。
D3DXMESH_NPATCHES
このフラグを指定すると、メッシュの頂点バッファとインデックス バッファが D3DUSAGE_NPATCHES フラグを指定して作成される。これは、メッシュ オブジェクトを N パッチ エンハンスメントを使って Microsoft® Direct3D® でレンダリングする場合に必要となる。
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED と D3DXMESH_IB_MANAGED の両方を指定したことになる。
D3DXMESH_POINTS
頂点バッファおよびインデックス バッファに D3DUSAGE_POINTS 利用フラグを使用する。
D3DXMESH_IB_DYNAMIC
インデックス バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_IB_MANAGED
インデックス バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_IB_SYSTEMMEM
インデックス バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_IB_WRITEONLY
インデックス バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM と D3DXMESH_IB_SYSTEMMEM の両方を指定したことになる。
D3DXMESH_VB_DYNAMIC
頂点バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_VB_MANAGED
頂点バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_VB_SYSTEMMEM
頂点バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_VB_WRITEONLY
頂点バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY と D3DXMESH_IB_WRITEONLY の両方を指定したことになる。
pD3DDevice
[in] メッシュに関連付けられているデバイス オブジェクトを表す IDirect3DDevice8 インターフェイスへのポインタ。
ppAdjacency
[in, out] ID3DXBuffer インターフェイスへのポインタのアドレス。メソッドが返ると、このパラメータには、メッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの DWORD の配列が入力される。
ppMaterials
[in, out] ID3DXBuffer インターフェイスへのポインタのアドレス。メソッドが返ると、このパラメータには D3DXMATERIAL 構造体の配列が入力される。
pNumMaterials
[in, out] メソッドが戻ったときの ppMaterials 配列内の D3DXMATERIAL 構造体の数へのポインタ。
ppMesh
[out, retval] ロードされたメッシュを表す ID3DXMesh インターフェイスへのポインタのアドレス。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXLoadSkinMeshFromXof

Microsoft® DirectX® (.x) ファイル データ オブジェクトからスキン メッシュをロードする。

HRESULT D3DXLoadSkinMeshFromXof(
  LPDIRECTXFILEDATA pXofObjMesh,
  DWORD Options,
  LPDIRECT3DDEVICE8 pD3DDevice,
  LPD3DXBUFFER* ppAdjacency,
  LPD3DXBUFFER* ppMaterials,
  PDWORD pMatOut,
  LPD3DXBUFFER* ppBoneNames,
  LPD3DXBUFFER* ppBoneTransforms,
  LPD3DXSKINMESH* ppMesh
);

パラメータ

pXofObjMesh
[in] ロードする DirectX ファイル データ オブジェクトを表す、IDirectXFileData インターフェイスへのポインタ。
Options
[in] メッシュの作成オプションを指定する 1 つ以上のフラグの組み合わせ。次のフラグが定義されている。
D3DXMESH_32BIT
メッシュに、16 ビットではなく 32 ビットのインデックスを作成する。32 ビットのメッシュは、最大 2^32-1 の面と頂点を含むことができる。このフラグはサポートされていないため使用できない。
D3DXMESH_DONOTCLIP
頂点バッファおよびインデックス バッファに D3DUSAGE_DONOTCLIP 利用フラグを使用する。
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC と D3DXMESH_IB_DYNAMIC の両方を指定したことになる。
D3DXMESH_RTPATCHES
頂点バッファおよびインデックス バッファに D3DUSAGE_RTPATCHES 利用フラグを使用する。
D3DXMESH_NPATCHES
このフラグを指定すると、メッシュの頂点バッファとインデックス バッファが D3DUSAGE_NPATCHES フラグを指定して作成される。これは、メッシュ オブジェクトを N パッチ エンハンスメントを使って Microsoft® Direct3D でレンダリングする場合に必要となる。
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED と D3DXMESH_IB_MANAGED の両方を指定したことになる。
D3DXMESH_POINTS
頂点バッファおよびインデックス バッファに D3DUSAGE_POINTS 利用フラグを使用する。
D3DXMESH_IB_DYNAMIC
インデックス バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_IB_MANAGED
インデックス バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_IB_SYSTEMMEM
インデックス バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_IB_WRITEONLY
インデックス バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM と D3DXMESH_IB_SYSTEMMEM の両方を指定したことになる。
D3DXMESH_VB_DYNAMIC
頂点バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_VB_MANAGED
頂点バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_VB_SYSTEMMEM
頂点バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_VB_WRITEONLY
頂点バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY と D3DXMESH_IB_WRITEONLY の両方を指定したことになる。
pD3DDevice
[in] メッシュに関連付けられているデバイス オブジェクトを表す IDirect3DDevice8 インターフェイスへのポインタ。
ppAdjacency
[in, out] ID3DXBuffer インターフェイスへのポインタのアドレス。メソッドが返ると、このパラメータには、メッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの DWORD の配列が入力される。
ppMaterials
[in, out] ID3DXBuffer インターフェイスへのポインタのアドレス。メソッドが返ると、このパラメータには D3DXMATERIAL 構造体の配列が入力される。
pMatOut
[in, out] メソッドが戻ったときの ppMaterials 配列内の D3DXMATERIAL 構造体の数へのポインタ。
ppBoneNames
[in, out] ボーン名を格納する ID3DXBuffer インターフェイスへのポインタのアドレス。
ppBoneTransforms
[in, out] ボーン トランスフォームを格納する ID3DXBuffer インターフェイスへのポインタのアドレス。
ppMesh
[out, retval] ロードされたメッシュを表す ID3DXSkinMesh インターフェイスへのポインタのアドレス。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

注意

このメソッドは、.x ファイル内の内部オブジェクトへのポインタを受け取り、フレーム階層をロードできる。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXSaveMeshToX

メッシュを Microsoft® DirectX® (.x) ファイルに保存する。

HRESULT D3DXSaveMeshToX(
  LPSTR pFilename,
  LPD3DXMESH pMesh,
  CONST DWORD* pAdjacency,
  CONST LPD3DXMATERIAL pMaterials,
  DWORD NumMaterials,
  DWORD Format
);

パラメータ

pFilename
[in] メッシュが保存されている DirectX ファイルの名前を指定する文字列へのポインタ。
pMesh
[in] DirectX ファイルへ保存するメッシュを表す、ID3DXMesh インターフェイスへのポインタ。
pAdjacency
[in] メッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの DWORD の配列へのポインタ。
pMaterials
[in] DirectX ファイルに保存されているマテリアル情報を格納する、D3DXMATERIAL 構造体の配列へのポインタ。
NumMaterials
[in] rgMaterials array 内の D3DXMATERIAL 構造体の数。
Format
[in] DirectX ファイルの保存に使用するフォーマットを指定する。詳細については、「注意」を参照すること。
DXFILEFORMAT_BINARY
バイナリ ファイルを指定する。
DXFILEFORMAT_COMPRESSED
圧縮ファイルを指定する。
DXFILEFORMAT_TEXT
テキスト ファイルを指定する。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

ファイル フォーマットのデフォルト値は、DXFILEFORMAT_BINARY である。ファイル フォーマットの値は、論理和を使用して組み合わせることが可能で、圧縮済みテキスト ファイルや圧縮済みバイナリ ファイルを作成できる。ファイルがバイナリ (0) とテキスト (1) の両方で指定されている場合、テキスト ファイルで保存される。これは、0 + 1 = 1 となることからテキスト ファイル フォーマットの値と区別が付かないためである。ファイル フォーマットをテキストと圧縮の両方として指定した場合、ファイルはまずテキストとして出力されてから圧縮される。ただし、圧縮済みテキスト ファイルはバイナリ テキスト ファイルほど効率は良くない。そのため、通常はバイナリと圧縮を指定すればよい。フォーマットを指定せずにファイルを圧縮するよう設定すると、バイナリの圧縮ファイルとなる。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXSimplifyMesh

メッシュを単純化する。

HRESULT D3DXSimplifyMesh(
  LPD3DXMESH pMesh,
  CONST DWORD* pAdjacency,
  CONST LPD3DXATTRIBUTEWEIGHTS pVertexAttributeWeights,
  CONST FLOAT* pVertexWeights,
  DWORD MinValue,
  DWORD* Options,
  LPD3DXMESH* ppMesh
);

パラメータ

pMesh
[in] ソース メッシュを表す ID3DXMesh インターフェイスへのポインタ。
pAdjacency
[in] 単純化するメッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの DWORD の配列へのポインタ。
pVertexAttributeWeights
[in] 各頂点の成分に対する加重を格納する D3DXATTRIBUTEWEIGHTS 構造体へのポインタ。このパラメータを NULL に設定すると、デフォルトの構造体が使用される。「注意」を参照すること。
pVertexWeights
[in] 頂点加重の配列へのポインタ。このパラメータを NULL に設定すると、すべての頂点加重は 1.0 に設定される。
MinValue
[in] Options パラメータに設定されているフラグに応じた頂点または面の数。これによって、ソース メッシュが単純化される。
Options
[in] メッシュに対して単純化オプションを指定する。次のいずれかのフラグを設定できる。
D3DXMESHSIMP_FACE
MinValue パラメータに指定した数の面でメッシュが単純化される。
D3DXMESHSIMP_VERTEX
MinValue パラメータに指定した数の頂点でメッシュが単純化される。
ppMesh
[out] 単純化メッシュを表す、ID3DXMesh インターフェイスへのポインタのアドレス。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

注意

この関数は、minValue の頂点または面を持つメッシュを生成する。

単純化プロセスによってメッシュを minValue まで減らすことができない場合でも呼び出しは継続される。これは、minValue が絶対的な最小値ではなく、希望の最小値だからである。

pVertexAttributeWeights を NULL に設定した場合、次に示す値がデフォルトの D3DXATTRIBUTEWEIGHTS 構造体に割り当てられる。

D3DXATTRIBUTEWEIGHTS AttributeWeights;

AttributeWeights.Position  = 1.0;
AttributeWeights.Boundary =  1.0;
AttributeWeights.Normal   =  1.0;
AttributeWeights.Diffuse  =  0.0;
AttributeWeights.Specular =  0.0;
AttributeWeights.Tex[8]   =  {0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0};

通常のアプリケーションでは、このデフォルトの構造体を使用すべきである。理由は、この構造体がジオメトリと法線の調整のみを目的としているからである。その他のメンバ フィールドを修正する必要があるのは、特別な場合のみである。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXSphereBoundProbe

レイが境界球のボリュームに当たるかどうかを判定する。

BOOL D3DXSphereBoundProbe(
  CONST D3DXVECTOR3* pCenter,
  FLOAT Radius,
  D3DXVECTOR3* pRayPosition,
  D3DXVECTOR3* pRayDirection
);

パラメータ

pCenter
[in] 球の中心座標を指定する D3DXVECTOR3 構造体へのポインタ。
Radius
[in] 球の半径。
pRayPosition
[in] レイの始点座標を指定する D3DXVECTOR3 構造体へのポインタ。
pRayDirection
[in] レイの方向を指定する D3DXVECTOR3 構造体へのポインタ。

戻り値

レイが境界球のボリュームに当たる場合は、TRUE を返す。それ以外の場合は、FALSE を返す。

注意

D3DXSphereBoundProbe は、レイが球のサーフェスだけではなく、境界球のボリュームに当たるかどうかを判定する。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXTesselateMesh

メッシュをテッセレートする。

HRESULT D3DXTesselateMesh(
  LPD3DXMESH pMeshIn,
  CONST DWORD* pAdjacency,
  FLOAT NumSegs,
  BOOL bQuadraticNormals
  LPD3DXMESH* ppMeshOut
);

パラメータ

pMeshIn
[in] テッセレートするメッシュを表す、ID3DXMesh インターフェイスへのポインタ。
pAdjacency
[in] ソース メッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの DWORD の配列へのポインタ。
NumSegs
[in] テッセレートするエッジあたりのセグメント数。
bQuadraticNormals
[in] 法線に対して二次補間を使用する場合は、TRUE に設定する。線形補間を使用する場合は、FALSE に設定する。
ppMeshOut
[out] テッセレーションされたメッシュを表す、ID3DXMesh インターフェイスへのポインタのアドレス。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

注 この関数は、N パッチ アルゴリズムを使ってテッセレートする。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXValidMesh

メッシュを検証する。

HRESULT D3DXValidMesh(
  LPD3DXMESH pMeshIn,
  CONST DWORD* pAdjacency
);

パラメータ

pMeshIn
[in] 検証するメッシュを表す、ID3DXMesh インターフェイスへのポインタ。
pAdjacency
[in] 検証するメッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの DWORD の配列へのポインタ。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DXERR_INVALIDMESH
D3DERR_INVALIDCALL
E_OUTOFMEMORY

注意

このメソッドは、2 つの三角形ファンが同じ頂点を共有する場合に無効なインデックスの有無を確認し、別の頂点を追加することにより、メッシュを検証する。

エラー情報はデバッグ時の出力から入手できる。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXWeldVertices

複製された、等しい属性を持つ頂点を結合する。

HRESULT D3DXValidMesh(
  CONST LPD3DXMESH pMesh,
  float fEpsilon,
  CONST DWORD* pAdjacencyIn,
  DWORD* pAdjacencyOut,
  DWORD* pFaceRemap,
  LPD3DXBUFFER* ppVertexRemap
);

パラメータ

pMesh
[in] 頂点結合の元となるメッシュである ID3DXMesh オブジェクトへのポインタ。
fEpsilon
[in] 頂点が結合される、頂点属性の差。
pAdjacencyIn

[in] ソース メッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの DWORD の配列へのポインタ。このパラメータが NULL の場合、ID3DXMesh::GenerateAdjacency が呼び出されて、論理隣接性情報が作成される。

pAdjacencyOut
[in, out] 最適化されたメッシュの面隣接性配列に使用する転送先バッファへのポインタ。面隣接性は、配列の配列として格納される。最も内側の配列は、隣接する三角形の 3 つのインデックスで、外側の配列は、メッシュ内の三角形ごとの面隣接性の 1 セットである。
pFaceRemap
[out] 各面の新しいインデックスを格納している転送先バッファへのポインタ。
ppVertexRemap
[out] 各頂点の新しいインデックスを格納する、ID3DXBuffer インターフェイスへのポインタのアドレス。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

注意

このメソッドは、与えられた隣接性情報を使って、複製するポイントを指定する。このメソッドは、Epsilon の比較によって頂点を結合する。等しい位置を持つ頂点があらかじめ計算され、ポイント表現データによって表されている必要がある。

このメソッドは論理的に結合された頂点を取得し、同様の成分を持つ頂点を結合する。fEpsilon 内の法線または fEpsilon 内のテクスチャ座標などである。

動作環境

ヘッダー : D3dx8mesh.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


シェーダ関数

Direct3DX では次のシェーダ関数が用意されている。

  • D3DXAssembleShader
  • D3DXAssembleShaderFromFileA
  • D3DXAssembleShaderFromFileW

アセンブラは、アセンブリ開始時にバージョン トークンを検出しない限り、頂点シェーダ (バージョン 1.0) をアセンブルすると想定する。Direct3DX の頂点シェーダおよびピクセル シェーダのアセンブラについては、「Direct3DX シェーダ アセンブラ リファレンス」を参照すること。


D3DXAssembleShader

シェーダのソースがメモリ内にある場合に、シェーダの ASCII 記述をバイナリ形式にアセンブルする。

HRESULT D3DXAssembleShader(
  LPCVOID pSrcData,
  UINT SrcDataLen,
  DWORD Flags,
  LPD3DXBUFFER* ppConstants,
  LPD3DXBUFFER* ppCompiledShader,
  LPD3DXBUFFER* ppCompilationErrors
);

パラメータ

pSrcData
[in] ソース コードへのポインタ。
SrcDataLen
[in] ソース コードのサイズ (バイト単位)。
Flags
[in] アセンブリ オプションを指定する、次のフラグの組み合わせ。
D3DXASM_DEBUG
アセンブルされたシェーダに、デバッグ情報をコメントとして挿入する。
D3DXASM_SKIPVALIDATION
生成されたコードに対して既知の能力および制約の検証をしない。このオプションは、動作することがわかっているシェーダをアセンブルする場合 (つまり、前にこのオプションを使用せずにシェーダをアセンブルしたことがある場合) にのみ使用することを勧める。
ppConstants
[out] 返された定数宣言を表す、ID3DXBuffer インターフェイスへのポインタを返す。これらの定数は、頂点シェーダ宣言子フラグメントとして返される。アプリケーションは、このバッファの内容を定数宣言に挿入する必要がある。ピクセル シェーダの場合、定数宣言はアセンブルされたシェーダに含まれるため、このパラメータは意味を成さない。このパラメータが NULL の場合は無視される。
ppCompiledShader
[out] 返されたコンパイル済みのオブジェクト コードを表す、ID3DXBuffer インターフェイスへのポインタを返す。このパラメータが NULL の場合は無視される。
ppCompilationErrors
[out] 返された ASCII エラー メッセージを表す、ID3DXBuffer インターフェイスへのポインタを返す。このパラメータが NULL の場合は無視される。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

動作環境

ヘッダー : D3dx8core.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXAssembleShaderFromFileA

ソース ファイルのファイル名が ANSI 文字列である場合に、シェーダの ASCII 記述をバイナリ形式にアセンブルする。

HRESULT D3DXAssembleShaderFromFileA(
  LPCSTR pSrcFile,
  DWORD Flags,
  LPD3DXBUFFER* ppConstants,
  LPD3DXBUFFER* ppCompiledShader,
  LPD3DXBUFFER* ppCompilationErrors
);

パラメータ

pSrcFile
[in] ソース ファイル名 (ANSI 形式) へのポインタ。
Flags
[in] アセンブリ オプションを指定する、次のフラグの組み合わせ。
D3DXASM_DEBUG
アセンブルされたシェーダに、デバッグ情報をコメントとして挿入する。
D3DXASM_SKIPVALIDATION
生成されたコードに対して既知の能力および制約の検証をしない。このオプションは、動作することがわかっているシェーダをアセンブルする場合 (つまり、前にこのオプションを使用せずにシェーダをアセンブルしたことがある場合) にのみ使用することを勧める。
ppConstants
[out] 返された定数宣言を表す、ID3DXBuffer インターフェイスへのポインタを返す。これらの定数は、頂点シェーダ宣言子フラグメントとして返される。アプリケーションは、このバッファの内容を定数宣言に挿入する必要がある。ピクセル シェーダの場合、定数宣言はアセンブルされたシェーダに含まれるため、このパラメータは意味を成さない。このパラメータが NULL の場合は無視される。
ppCompiledShader
[out] 返されたコンパイル済みのオブジェクト コードを表す、ID3DXBuffer インターフェイスへのポインタを返す。このパラメータが NULL の場合は無視される。
ppCompilationErrors
[out] 返された ASCII エラー メッセージを表す、ID3DXBuffer インターフェイスへのポインタを返す。このパラメータが NULL の場合は無視される。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

注意

D3DXAssembleShaderFromFile は、#define UNICODE スイッチが含まれているかどうかに応じて、D3DXAssembleShaderFromFileA または D3DXAssembleShaderFromFileW のどちらかをマップする。#define UNICODE スイッチを挿入または除外して、アプリケーションで Unicode または ANSI 文字列のどちらを使用するかを指定する。

次のコードは、D3DXAssembleShaderFromFile の定義方法を示している。

#ifdef UNICODE
#define D3DXAssembleShaderFromFile D3DXAssembleShaderFromFileW
#else
#define D3DXAssembleShaderFromFile D3DXAssembleShaderFromFileA
#endif

次のラッパー関数 PreprocessAndAssembleShaderFromFile の例は、頂点シェーダ コードに対して C プリプロセッサを呼び出した後、D3DXAssembleShaderFromFile を使用してアセンブラを呼び出す方法を示している。

HRESULT PreprocessAndAssembleShaderFromFile(
        LPCSTR          szFile,
        DWORD           Flags,
        LPD3DXBUFFER*   ppConstants,
        LPD3DXBUFFER*   ppCode,
        LPD3DXBUFFER*   ppErrors)
{
    char szPath[_MAX_PATH];
    char szTemp[_MAX_PATH];
    char szCmd [_MAX_PATH];

    GetTempPath(sizeof(szPath), szPath);
    GetTempFileName(szPath, "vsa", 0, szTemp);

    _snprintf(szCmd, sizeof(szCmd), "cl /nologo /E %s > %s", szFile, szTemp);

    if(0 != system(szCmd))
        return D3DERR_INVALIDCALL;

    return D3DXAssembleShaderFromFile(szTemp, Flags, ppConstants, ppCode, ppErrors);
}

この関数が機能するためには、Microsoft®Visual C++® がインストールされていて、環境のセットアップにより Cl.exe のパスが設定されている必要がある。

動作環境

ヘッダー : D3dx8core.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXAssembleShaderFromFileW


D3DXAssembleShaderFromFileW

ソース ファイルのファイル名が Unicode 文字列である場合に、シェーダの ASCII 記述をバイナリ形式にアセンブルする。

HRESULT D3DXAssembleShaderFromFileW(
  LPCWSTR pSrcFile,
  DWORD Flags,
  LPD3DXBUFFER* ppConstants,
  LPD3DXBUFFER* ppCompiledShader,
  LPD3DXBUFFER* ppCompilationErrors
);

パラメータ

pSrcFile
[in] ソース ファイル名 (Unicode 形式) へのポインタ。
Flags
[in] アセンブリ オプションを指定する、次のフラグの組み合わせ。
D3DXASM_DEBUG
アセンブルされたシェーダに、デバッグ情報をコメントとして挿入する。
D3DXASM_SKIPVALIDATION
生成されたコードに対して既知の能力および制約の検証をしない。このオプションは、動作することがわかっているシェーダをアセンブルする場合 (つまり、前にこのオプションを使用せずにシェーダをアセンブルしたことがある場合) にのみ使用することを勧める。
ppConstants
[out] 返された定数宣言を表す、ID3DXBuffer インターフェイスへのポインタを返す。これらの定数は、頂点シェーダ宣言子フラグメントとして返される。アプリケーションは、このバッファの内容を定数宣言に挿入する必要がある。ピクセル シェーダの場合、定数宣言はアセンブルされたシェーダに含まれるため、このパラメータは意味を成さない。このパラメータが NULL の場合は無視される。
ppCompiledShader
[out] 返されたコンパイル済みのオブジェクト コードを表す、ID3DXBuffer インターフェイスへのポインタを返す。このパラメータが NULL の場合は無視される。
ppCompilationErrors
[out] 返された ASCII エラー メッセージを表す、ID3DXBuffer インターフェイスへのポインタを返す。このパラメータが NULL の場合は無視される。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

注意

D3DXAssemblePixelShaderFromFile は、#define UNICODE スイッチが含まれているかどうかに応じて、 D3DXAssembleShaderFromFileA または D3DXAssembleShaderFromFileW のどちらかをマップする。#define UNICODE スイッチを挿入または除外して、アプリケーションで Unicode または ANSI 文字列のどちらを使用するかを指定する。

次のコードは、D3DXAssembleShaderFromFile の定義方法を示している。

#ifdef UNICODE
#define D3DXAssembleShaderFromFile D3DXAssembleShaderFromFileW
#else
#define D3DXAssembleShaderFromFile D3DXAssembleShaderFromFileA
#endif

次のラッパー関数 PreprocessAndAssembleShaderFromFile の例は、頂点シェーダ コードに対して C プリプロセッサを呼び出した後、D3DXAssembleShaderFromFile を使用してアセンブラを呼び出す方法を示している。

HRESULT
    PreprocessAndAssembleShaderFromFile(
        LPCSTR          szFile,
        DWORD           Flags,
        LPD3DXBUFFER*   ppConstants,
        LPD3DXBUFFER*   ppCode,
        LPD3DXBUFFER*   ppErrors)
{
    char szPath[_MAX_PATH];
    char szTemp[_MAX_PATH];
    char szCmd [_MAX_PATH];

    GetTempPath(sizeof(szPath), szPath);
    GetTempFileName(szPath, "vsa", 0, szTemp);

    _snprintf(szCmd, sizeof(szCmd), "cl /nologo /E %s > %s", szFile, szTemp);

    if(0 != system(szCmd))
        return D3DERR_INVALIDCALL;

    return D3DXAssembleShaderFromFile(szTemp, Flags, ppConstants, ppCode, ppErrors);
}

この関数が機能するためには、Microsoft®Visual C++® がインストールされていて、環境のセットアップにより Cl.exe のパスが設定されている必要がある。

動作環境

ヘッダー : D3dx8core.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXAssembleShaderFromFileA


形状描画関数

Direct3DX では次の形状描画関数が用意されている。

  • D3DXCreateBox
  • D3DXCreateCylinder
  • D3DXCreatePolygon
  • D3DXCreateSphere
  • D3DXCreateTeapot
  • D3DXCreateTextA
  • D3DXCreateTextW
  • D3DXCreateTorus

すべての形は、メッシュ オブジェクトとして返される。

上に示した関数は、左手座標系または右手座標系で使用できる。


D3DXCreateBox

左手座標系を使用し、軸に沿ったボックスのメッシュを作成する。

HRESULT D3DXCreateBox(
  LPDIRECT3DDEVICE8 pDevice,
  FLOAT Width,
  FLOAT Height,
  FLOAT Depth,
  LPD3DXMESH* ppMesh,
  LPD3DXBUFFER* ppAdjacency
);

パラメータ

pDevice
[in] 作成されるボックス メッシュに関連付けられるデバイスを表すIDirect3DDevice8 インターフェイスへのポインタ。
Width
[in] x 軸方向のボックスの幅。
Height
[in] y 軸方向のボックスの高さ。
Depth
[in] z 軸方向のボックスの深度。
ppMesh
[out] ID3DXMesh インターフェイスの出力形状へのポインタのアドレス。
ppAdjacency
[out] ID3DXBuffer インターフェイスへのポインタのアドレス。メソッドが返ると、このパラメータには、メッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの DWORD の配列が入力される。NULL を指定できる。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

注意

作成されるボックスの中心は原点となる。

動作環境

ヘッダー : D3dx8shape.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXCreateCylinder

左手座標系を使用し、円柱のメッシュを作成する。

HRESULT D3DXCreateCylinder(
  LPDIRECT3DDEVICE8 pDevice,
  FLOAT Radius1,
  FLOAT Radius2,
  FLOAT Length,
  UINT Slices,
  UINT Stacks,
  LPD3DXMESH* ppMesh,
  LPD3DXBUFFER* ppAdjacency
);

パラメータ

pDevice
[in] 作成される円柱メッシュに関連付けられるデバイスを表す IDirect3DDevice8 インターフェイスへのポインタ。
Radius1
[in] z 軸の負の側の面の半径。値は 0.0f 以上である必要がある。
Radius2
[in] z 軸の正の側の面の半径。値は 0.0f 以上である必要がある。
Length
[in] z 軸方向の円柱の長さ。
Slices
[in] 主軸を回転軸としたスライスの数。
Stacks
[in] 主軸に沿ったスタック数。
ppMesh
[out] ID3DXMesh インターフェイスの出力形状へのポインタのアドレス。
ppAdjacency
[out] ID3DXBuffer インターフェイスへのポインタのアドレス。メソッドが返ると、このパラメータには、メッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの DWORD の配列が入力される。NULL を指定できる。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

注意

作成される円柱は、中心が原点となり、軸は z 軸方向となる。

動作環境

ヘッダー : D3dx8shape.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXCreatePolygon

左手座標系を使用し、n 面のポリゴンのメッシュを作成する。

HRESULT D3DXCreatePolygon(
  LPDIRECT3DDEVICE8 pDevice,
  FLOAT Length,
  UINT Sides,
  LPD3DXMESH* ppMesh,
  LPD3DXBUFFER* ppAdjacency
);

パラメータ

pDevice
[in] 作成されるポリゴン メッシュに関連付けられるデバイスを表す IDirect3DDevice8 インターフェイスへのポインタ。
Length
[in] 各面の長さ。
Sides
[in] ポリゴンの面数。値は 3 以上である必要がある。
ppMesh
[out] ID3DXMesh インターフェイスの出力形状へのポインタのアドレス。
ppAdjacency
[out] ID3DXBuffer インターフェイスへのポインタのアドレス。メソッドが返ると、このパラメータには、メッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの DWORD の配列が入力される。NULL を指定できる。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

注意

作成されるポリゴンの中心は原点となる。

動作環境

ヘッダー : D3dx8shape.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXCreateSphere

左手座標系を使用し、球のメッシュを作成する。

HRESULT D3DXCreateSphere(
  LPDIRECT3DDEVICE8 pDevice,
  FLOAT Radius,
  UINT Slices,
  UINT Stacks,
  LPD3DXMESH* ppMesh,
  LPD3DXBUFFER* ppAdjacency
);

パラメータ

pDevice
[in] 作成される球メッシュに関連付けられるデバイスを表す IDirect3DDevice8 インターフェイスへのポインタ。
Radius
[in] 球の半径。この値は 0.0f 以上である必要がある。
Slices
[in] 主軸を回転軸としたスライスの数。
Stacks
[in] 主軸に沿ったスタック数。
ppMesh
[out] ID3DXMesh インターフェイスの出力形状へのポインタのアドレス。
ppAdjacency
[out] ID3DXBuffer インターフェイスへのポインタのアドレス。メソッドが返ると、このパラメータには、メッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの DWORD の配列が入力される。NULL を指定できる。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

注意

作成される球は、中心が原点となり、軸は z 軸方向となる。

動作環境

ヘッダー : D3dx8shape.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXCreateTeapot

左手座標系を使用し、ティーポットのメッシュを作成する。

HRESULT D3DXCreateTeapot(
  LPDIRECT3DDEVICE8 pDevice,
  LPD3DXMESH* ppMesh,
  LPD3DXBUFFER* ppAdjacency
);

パラメータ

pDevice
[in] 作成されるティーポット メッシュに関連付けられるデバイスを表す IDirect3DDevice8 インターフェイスへのポインタ。
ppMesh
[out] ID3DXMesh インターフェイスの出力形状へのポインタのアドレス。
ppAdjacency
[out] ID3DXBuffer インターフェイスへのポインタのアドレス。メソッドが返ると、このパラメータには、メッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの DWORD の配列が入力される。NULL を指定できる。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

動作環境

ヘッダー : D3dx8shape.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXCreateTextA

デバイス コンテキストに関連付けられているフォントを使用し、指定した ANSI テキストのメッシュを作成する。

HRESULT D3DXCreateTextA(
  LPDIRECT3DDEVICE8 pDevice,
  HDC hDC,
  LPCSTR pText,
  FLOAT Deviation,
  FLOAT Extrusion,
  LPD3DXMESH* ppMesh,
  LPGLYPHMETRICSFLOAT pGlyphMetrics
);

パラメータ

pDevice
[in] 作成されたテキスト メッシュに関連付けられているデバイスを表す IDirect3DDevice8 インターフェイスへのポインタ。
hDC
[in] 出力用のフォントを格納しているデバイスのコンテキスト。デバイスのコンテキストによって選択されるフォントは、TrueType フォントでなければならない。
pText
[in] 生成するテキストを指定する ANSI 文字列へのポインタ。
Deviation
[in] TRUE フォント アウトラインからの最大コード偏差。
Extrusion
[in] z 軸の負の方向に押し出されるテキストの量。
ppMesh
[out] ID3DXMesh インターフェイスの出力形状へのポインタのアドレス。
pGlyphMetrics
[out] グリフ メトリック データを受け取る GLYPHMETRICSFLOAT 構造体の配列へのポインタ。配列内の各 GLYPHMETRICSFLOAT 構造体には、文字列内の対応するグリフの、配置と向きに関する情報が格納される。配列内の要素の数は、文字列の文字数と等しくなければならない。各構造体内の始点は、文字列全体に対して相対的ではなく、その文字セルに対して相対的である。境界ボックス全体の演算を行うには、文字列をトラバースする間グリフごとに増分を追加する。

グリフ サイズを考慮する必要がない場合は、pGlyphMetrics に NULL を渡すことができる。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

注意

D3DXCreateText は、#define UNICODE スイッチが含まれているかどうかに応じて、D3DXCreateTextA または D3DXCreateTextW のどちらかをマップする。#define UNICODE スイッチを挿入または除外して、アプリケーションで Unicode または ANSI 文字列のどちらを使用するかを指定する。次のコードは、D3DXCreateText の定義方法を示している。

#ifdef UNICODE
#define D3DXCreateText D3DXCreateTextW
#else
#define D3DXCreateText D3DXCreateTextA
#endif

GLYPHMETRICSFLOAT 構造体の詳細については、Microsoft® Platform Software Development Kit (SDK) を参照すること。

動作環境

ヘッダー : D3dx8shape.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXCreateTextW


D3DXCreateTextW

デバイス コンテキストに関連付けられているフォントを使用し、指定した Unicode テキストのメッシュを作成する。

HRESULT D3DXCreateTextW(
  LPDIRECT3DDEVICE8 pDevice,
  HDC hDC,
  LPCSTR pText,
  FLOAT Deviation,
  FLOAT Extrusion,
  LPD3DXMESH* ppMesh,
  LPGLYPHMETRICSFLOAT pGlyphMetrics
);

パラメータ

pDevice
[in] 作成されたテキスト メッシュに関連付けられているデバイスを表す IDirect3DDevice8 インターフェイスへのポインタ。
hDC
[in] 出力用のフォントを格納しているデバイスのコンテキスト。デバイスのコンテキストによって選択されるフォントは、TrueType フォントでなければならない。
pText
[in] 生成するテキストを指定する Unicode 文字列へのポインタ。
Deviation
[in] TRUE フォント アウトラインからの最大コード偏差。
Extrusion
[in] z 軸の負の方向に押し出されるテキストの量。
ppMesh
[out] ID3DXMesh インターフェイスの出力形状へのポインタのアドレス。
pGlyphMetrics
[out] グリフ メトリック データを受け取る GLYPHMETRICSFLOAT 構造体の配列へのポインタ。配列内の各 GLYPHMETRICSFLOAT 構造体には、文字列内の対応するグリフの、配置と向きに関する情報が格納される。配列内の要素の数は、文字列の文字数と等しくなければならない。各構造体内の始点は、文字列全体に対して相対的ではなく、その文字セルに対して相対的である。境界ボックス全体の演算を行うには、文字列をトラバースする間グリフごとに増分を追加する。

グリフ サイズを考慮する必要がない場合は、pGlyphMetrics に NULL を渡すことができる。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

注意

D3DXCreateText は、#define UNICODE スイッチが含まれているかどうかに応じて、D3DXCreateTextA または D3DXCreateTextW のどちらかをマップする。#define UNICODE スイッチを挿入または除外して、アプリケーションで Unicode または ANSI 文字列のどちらを使用するかを指定する。次のコードは、D3DXCreateText の定義方法を示している。

#ifdef UNICODE
#define D3DXCreateText D3DXCreateTextW
#else
#define D3DXCreateText D3DXCreateTextA
#endif

GLYPHMETRICSFLOAT 構造体の詳細については、Microsoft® Platform Software Development Kit (SDK) を参照すること。

動作環境

ヘッダー : D3dx8shape.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXCreateTextA


D3DXCreateTorus

左手座標系を使用し、トーラスのメッシュを作成する。

HRESULT D3DXCreateTorus(
  LPDIRECT3DDEVICE8 pDevice,
  FLOAT InnerRadius,
  FLOAT OuterRadius,
  UINT Sides,
  UINT Rings,
  LPD3DXMESH* ppMesh,
  LPD3DXBUFFER* ppAdjacency
);

パラメータ

pDevice
[in] 作成されるトーラス メッシュに関連付けられるデバイスを表す IDirect3DDevice8 インターフェイスへのポインタ。
InnerRadius
[in] トーラスの内部の半径。値は 0.0f 以上である必要がある。
OuterRadius
[in] トーラスの外部の半径。値は 0.0f 以上である必要がある。
Sides
[in] 横断面の辺の数。値は 3 以上である必要がある。
Rings
[in] トーラスを構成する環の数。値は 3 以上である必要がある。
ppMesh
[out] ID3DXMesh インターフェイスの出力形状へのポインタのアドレス。
ppAdjacency
[out] ID3DXBuffer インターフェイスへのポインタのアドレス。メソッドが返ると、このパラメータには、メッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの DWORD の配列が入力される。NULL を指定できる。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

注意

D3DXCreateTorus 関数は、中心が (0, 0, 0) で軸が z 軸方向のドーナツ型の図形 (トーラス) を描画する。このトーラスの内部の半径は横断面の半径 (小さい方の半径)、外部の半径は中央の穴の半径である。

この関数は、後でアプリケーションにより描画したり、操作するときに使用できるメッシュを返す。

動作環境

ヘッダー : D3dx8shape.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


テクスチャ関数

Direct3DX では次のテクスチャ関数が用意されている。

  • D3DXCheckCubeTextureRequirements
  • D3DXCheckTextureRequirements
  • D3DXCheckVolumeTextureRequirements
  • D3DXCreateCubeTexture
  • D3DXCreateCubeTextureFromFileA
  • D3DXCreateCubeTextureFromFileExA
  • D3DXCreateCubeTextureFromFileExW
  • D3DXCreateCubeTextureFromFileInMemory
  • D3DXCreateCubeTextureFromFileInMemoryEx
  • D3DXCreateCubeTextureFromFileW
  • D3DXCreateTexture
  • D3DXCreateTextureFromFileA
  • D3DXCreateTextureFromFileExA
  • D3DXCreateTextureFromFileExW
  • D3DXCreateTextureFromFileInMemory
  • D3DXCreateTextureFromFileInMemoryEx
  • D3DXCreateTextureFromFileW
  • D3DXCreateTextureFromResourceA
  • D3DXCreateTextureFromResourceExA
  • D3DXCreateTextureFromResourceExW
  • D3DXCreateTextureFromResourceW
  • D3DXCreateVolumeTexture
  • D3DXFilterCubeTexture
  • D3DXFilterTexture
  • D3DXFilterVolumeTexture
  • D3DXLoadSurfaceFromFileA
  • D3DXLoadSurfaceFromFileInMemory
  • D3DXLoadSurfaceFromFileW
  • D3DXLoadSurfaceFromMemory
  • D3DXLoadSurfaceFromResourceA
  • D3DXLoadSurfaceFromResourceW
  • D3DXLoadSurfaceFromSurface
  • D3DXLoadVolumeFromMemory
  • D3DXLoadVolumeFromVolume


D3DXCheckCubeTextureRequirements

キューブ テクスチャ作成パラメータを確認する。

HRESULT D3DXCheckCubeTextureRequirements(
  LPDIRECT3DDEVICE8 pDevice,
  UINT* pSize,
  UINT* pNumMipLevels,
  DWORD Usage,
  D3DFORMAT* pFormat,
  D3DPOOL Pool
);

パラメータ

pDevice
[in] キューブ テクスチャに関連付けられるデバイスを表すIDirect3DDevice8 インターフェイスへのポインタ。
pSize
[in, out] 要求される幅と高さ (ピクセル単位) へのポインタ、または NULL。訂正後のサイズを返す。
pNumMipLevels
[in, out] 要求されるミップマップ レベルの数へのポインタ、または NULL。訂正後のミップマップ レベルの数を返す。
Usage
[in] 0 または D3DUSAGE_RENDERTARGET。このフラグを D3DUSAGE_RENDERTARGET に設定すると、そのサーフェスはレンダリング ターゲットとして使用されることを示す。リソースは、SetRenderTarget メソッドの pNewRenderTarget パラメータに渡すことができる。D3DUSAGE_RENDERTARGET を指定する場合、アプリケーションは IDirect3D8::CheckDeviceFormat を呼び出して、デバイスがこれらの処理をサポートしていることを確認する必要がある。
pFormat
[in, out] D3DFORMAT 列挙型のメンバへのポインタ。要求されるピクセル フォーマットまたは NULL を指定する。訂正後のフォーマットを返す。
Pool
[in] テクスチャの配置先となるメモリ クラスを記述する、D3DPOOL 列挙型のメンバ。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_NOTAVAILABLE
D3DERR_INVALIDCALL

注意

この関数のパラメータが無効の場合、この関数は修正したパラメータを返す。

キューブ テクスチャは、サーフェスのコレクションである点でほかのサーフェスとは異なる。キューブ テクスチャを指定して SetRenderTarget を呼び出すには、IDirect3DCubeTexture8::GetCubeMapSurface を使用して個々の面を選択し、結果サーフェスを SetRenderTarget に渡す必要がある。

動作環境

ヘッダー : D3dx8tex.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXCheckTextureRequirements

テクスチャ作成パラメータを確認する。

HRESULT D3DXCheckTextureRequirements(
  LPDIRECT3DDEVICE8 pDevice,
  UINT* pWidth,
  UINT* pHeight,
  UINT* pNumMipLevels,
  DWORD Usage,
  D3DFORMAT* pFormat,
  D3DPOOL Pool
);

パラメータ

pDevice
[in] テクスチャに関連付けられているデバイスを表す IDirect3DDevice8 インターフェイスへのポインタ。
pWidth
[in, out] 要求される幅 (ピクセル単位) へのポインタ、または NULL。訂正後のサイズを返す。
pHeight
[in, out] 要求される高さ (ピクセル単位) へのポインタ、または NULL。訂正後のサイズを返す。
pNumMipLevels
[in, out] 要求されるミップマップ レベルの数へのポインタ、または NULL。訂正後のミップマップ レベルの数を返す。
Usage
[in] 0 または D3DUSAGE_RENDERTARGET。このフラグを D3DUSAGE_RENDERTARGET に設定すると、そのサーフェスはレンダリング ターゲットとして使用されることを示す。リソースは、SetRenderTarget メソッドの pNewRenderTarget パラメータに渡すことができる。D3DUSAGE_RENDERTARGET を指定する場合、アプリケーションは IDirect3D8::CheckDeviceFormat を呼び出して、デバイスがこれらの処理をサポートしていることを確認する必要がある。
pFormat
[in, out] D3DFORMAT 列挙型のメンバへのポインタ。要求されるピクセル フォーマットまたは NULL を指定する。訂正後のフォーマットを返す。
Pool
[in] テクスチャの配置先となるメモリ クラスを記述する、D3DPOOL 列挙型のメンバ。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_NOTAVAILABLE
D3DERR_INVALIDCALL

注意

この関数のパラメータが無効の場合、この関数は修正したパラメータを返す。

動作環境

ヘッダー : D3dx8tex.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXCheckVolumeTextureRequirements

ボリューム テクスチャ作成パラメータを確認する。

HRESULT D3DXCheckVolumeTextureRequirements(
  LPDIRECT3DDEVICE8 pDevice,
  UINT* pWidth,
  UINT* pHeight,
  UINT* pDepth,
  UINT* pNumMipLevels,
  DWORD Usage,
  D3DFORMAT* pFormat,
  D3DPOOL Pool
);

パラメータ

pDevice
[in] ボリューム テクスチャに関連付けられるデバイスを表す IDirect3DDevice8 インターフェイスへのポインタ。
pWidth
[in, out] 要求される幅 (ピクセル単位) へのポインタ、または NULL。訂正後のサイズを返す。
pHeight
[in, out] 要求される高さ (ピクセル単位) へのポインタ、または NULL。訂正後のサイズを返す。
pDepth
[in, out] 要求される深度 (ピクセル単位) へのポインタ、または NULL。訂正後のサイズを返す。
pNumMipLevels
[in, out] 要求されるミップマップ レベルの数へのポインタ、または NULL。訂正後のミップマップ レベルの数を返す。
Usage
[in] 現時点では未使用なので 0 を設定しておく。
pFormat
[in, out] D3DFORMAT 列挙型のメンバへのポインタ。要求されるピクセル フォーマットまたは NULL を指定する。訂正後のフォーマットを返す。
Pool
[in] ボリューム テクスチャの配置先となるメモリ クラスを記述する、D3DPOOL 列挙型のメンバ。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_NOTAVAILABLE
D3DERR_INVALIDCALL

注意

この関数のパラメータが無効の場合、この関数は修正したパラメータを返す。

動作環境

ヘッダー : D3dx8tex.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXCreateCubeTexture

必要に応じて呼び出しパラメータを調整し、空のキューブ テクスチャを作成する。

HRESULT D3DXCreateCubeTexture(
  LPDIRECT3DDEVICE8 pDevice,
  UINT Size,
  UINT MipLevels,
  DWORD Usage,
  D3DFORMAT Format,
  D3DPOOL Pool,
  LPDIRECT3DCUBETEXTURE8* ppCubeTexture
);

パラメータ

pDevice
[in] テクスチャに関連付けられているデバイスを表す IDirect3DDevice8 インターフェイスへのポインタ。
Size
[in] キューブ テクスチャの幅と高さ (ピクセル単位)。たとえば、キューブ テクスチャが 8x8 ピクセルのキューブの場合、このパラメータの値は 8 となる。
MipLevels
[in] 要求されるミップ レベルの数。この値が 0 または D3DX_DEFAULT の場合は、完全なミップマップ チェーンが作成される。
Usage
[in] 0 または D3DUSAGE_RENDERTARGET。このフラグに D3DUSAGE_RENDERTARGET を設定すると、そのサーフェスはレンダリング ターゲットとして使用されることを示す。リソースは、SetRenderTarget メソッドの pNewRenderTarget パラメータに渡すことができる。D3DUSAGE_RENDERTARGET を指定する場合、アプリケーションは IDirect3D8::CheckDeviceFormat を呼び出して、デバイスがこれらの処理をサポートしていることを確認する必要がある。
Format
[in] キューブ テクスチャに対して要求されたピクセル フォーマットを記述する、D3DFORMAT 列挙型のメンバ。返されるキューブ テクスチャのフォーマットは、Format で指定されたフォーマットと異なる場合がある。アプリケーションは、返されたキューブ テクスチャのフォーマットを確認する必要がある。
Pool
[in] キューブ テクスチャの配置先となるメモリ クラスを記述する、D3DPOOL 列挙型のメンバ。
ppCubeTexture
[out] 作成されたキューブ テクスチャ オブジェクトを表す、IDirect3DCubeTexture8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
E_OUTOFMEMORY

注意

キューブ テクスチャは、サーフェスのコレクションである点でほかのサーフェスとは異なる。キューブ テクスチャを指定して SetRenderTarget を呼び出すには、IDirect3DCubeTexture8::GetCubeMapSurface を使用して個々の面を選択し、結果サーフェスを SetRenderTarget に渡す必要がある。

D3DXCreateCubeTexture は、内部で D3DXCheckCubeTextureRequirements を使用して呼び出しパラメータを調整する。したがって、IDirect3Ddevice8::CreateCubeTexture の呼び出しが失敗する場合でも、D3DXCreateCubeTexture の呼び出しは成功することが多い。

動作環境

ヘッダー : D3dx8tex.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXCreateCubeTextureFromFileA

ANSI 文字列で指定したファイルを元にしてキューブ テクスチャを作成する。

D3DXCreateCubeTextureFromFile は、#define UNICODE スイッチが含まれているかどうかに応じて、D3DXCreateCubeTextureFromFileA または D3DXCreateCubeTextureFromFileW のどちらかをマップする。「注意」を参照すること。

HRESULT D3DXCreateCubeTextureFromFileA(
  LPDIRECT3DDEVICE8 pDevice,
  LPCSTR pSrcFile,
  LPDIRECT3DCUBETEXTURE8* ppCubeTexture
);

パラメータ

pDevice
[in] キューブ テクスチャに関連付けられるデバイスを表す IDirect3DDevice8 インターフェイスへのポインタ。
pSrcFile
[in] キューブ テクスチャの作成に使用するファイルを指定する ANSI 文字列へのポインタ。「注意」を参照すること。
ppCubeTexture
[out] 作成されたキューブ テクスチャ オブジェクトを表す、IDirect3DCubeTexture8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

注意

#define UNICODE スイッチを挿入または除外して、アプリケーションで Unicode または ANSI 文字列のどちらを使用するかを指定する。次のコードは、D3DXCreateCubeTextureFromFile の定義方法を示している。

#ifdef UNICODE
#define D3DXCreateCubeTextureFromFile D3DXCreateCubeTextureFromFileW
#else
#define D3DXCreateCubeTextureFromFile D3DXCreateCubeTextureFromFileA
#endif

この関数を使用して作成したリソースは、D3DPOOL_MANAGED で示されるメモリ クラスに配置される。

D3DXCreateCubeTextureFromFileA は、DirectDrawSurface (DDS) ファイル フォーマットを使用する。DXTex ツールによって、ほかのファイル フォーマットからキューブ マップを生成し、それを DDS ファイル フォーマットで保存することができる。

動作環境

ヘッダー : d3dx8mesh.h で宣言。

参照

D3DXCreateCubeTextureFromFileW


D3DXCreateCubeTextureFromFileExA

ANSI 文字列で指定したファイルを元にしてキューブ テクスチャを作成する。これは、D3DXCreateCubeTextureFromFileA よりも高度な関数である。

D3DXCreateCubeTextureFromFileEx は、#define UNICODE スイッチが含まれているかどうかに応じて、D3DXCreateCubeTextureFromFileExA または D3DXCreateCubeTextureFromFileExW のどちらかをマップする。「注意」を参照すること。

HRESULT D3DXCreateCubeTextureFromFileExA(
  LPDIRECT3DDEVICE8 pDevice,
  LPCSTR pSrcFile,
  UINT Size,
  UINT MipLevels,
  DWORD Usage,
  D3DFORMAT Format,
  D3DPOOL Pool,
  DWORD Filter,
  DWORD MipFilter,
  D3DCOLOR ColorKey,
  D3DXIMAGE_INFO* pSrcInfo,
  PALETTEENTRY* pPalette,
  LPDIRECT3DCUBETEXTURE8* ppCubeTexture
);

パラメータ

pDevice
[in] キューブ テクスチャに関連付けられるデバイスを表す IDirect3DDevice8 インターフェイスへのポインタ。
pSrcFile
[in] キューブ テクスチャの作成に使用するファイルを指定する ANSI 文字列へのポインタ。「注意」を参照すること。
Size
[in] キューブ テクスチャの幅と高さ (ピクセル単位)。たとえば、キューブ テクスチャが 8x8 ピクセルのキューブの場合、このパラメータの値は 8 となる。この値が 0 または D3DX_DEFAULT の場合、ディメンジョンはファイルから取得される。
MipLevels
[in] 要求されるミップ レベルの数。この値が 0 または D3DX_DEFAULT の場合は、完全なミップマップ チェーンが作成される。
Usage
[in] 0 または D3DUSAGE_RENDERTARGET。このフラグに D3DUSAGE_RENDERTARGET を設定すると、そのサーフェスはレンダリング ターゲットとして使用されることを示す。リソースは、SetRenderTarget メソッドの pNewRenderTarget パラメータに渡すことができる。D3DUSAGE_RENDERTARGET を指定する場合、アプリケーションは IDirect3D8::CheckDeviceFormat を呼び出して、デバイスがこれらの処理をサポートしていることを確認する必要がある。
Format
[in] キューブ テクスチャに対して要求されたピクセル フォーマットを記述する、D3DFORMAT 列挙型のメンバ。返されるキューブ テクスチャのフォーマットは、Format で指定されたフォーマットと異なる場合がある。アプリケーションは、返されたキューブ テクスチャのフォーマットを確認する必要がある。Format の値が D3DFMT_UNKNOWN の場合、フォーマットはファイルから取得される。
Pool
[in] キューブ テクスチャの配置先となるメモリ クラスを記述する、D3DPOOL 列挙型のメンバ。
Filter
[in] イメージをフィルタリングする方法を制御する 1 つ以上のフラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_TRIANGLE | D3DX_FILTER_DITHER を指定することと等しい。

有効なそれぞれのフィルタに、次のフラグの 1 つが含まれていなければならない。

D3DX_FILTER_BOX
各ピクセルは、ソース イメージ内の 2 × 2 (× 2) のサイズのボックスに含まれるピクセルの平均を算出することにより計算される。このフィルタは、ミップマップを使用する場合のように、転送先のディメンジョンがソースの半分の場合のみ機能する。
D3DX_FILTER_LINEAR
各転送先ピクセルは、最も近い 4 つのピクセルをソース イメージからサンプリングすることにより計算される。このフィルタは、両軸のスケールが 2 未満の場合に最も効率よく機能する。
D3DX_FILTER_NONE
スケーリングまたはフィルタリングを行わない。ソース イメージの境界の外側にあるピクセルは透明な黒であると見なされる。
D3DX_FILTER_POINT
各転送先ピクセルは、最も近いピクセルをソース イメージからサンプリングすることにより計算される。
D3DX_FILTER_TRIANGLE
ソース イメージ内の各ピクセルが、転送先イメージに等しく反映される。これは、最も処理に時間のかかるフィルタである。

さらに、OR 演算子を使用して、有効なフィルタと共に次に示すオプションのフラグを 0 個以上指定できる。内部的には、常に D3DX_FILTER_MIRROR フラグが使用される。

D3DX_FILTER_MIRROR
このフラグを指定すると、D3DX_FILTER_MIRROR_U、D3DX_FILTER_MIRROR_V、および D3DX_FILTER_MIRROR_W フラグを指定したことになる。このフラグは、この関数では常に内部的に使用される。
D3DX_FILTER_MIRROR_U
u 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_V
v 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_W
w 軸のテクスチャのエッジから離れているピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_DITHER
結果として作成されたイメージを、4x4 の順序付きディザ アルゴリズムを使ってディザリングする必要がある。
MipFilter
[in] イメージをフィルタリングする方法を制御する 1 つ以上のフラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_BOX を指定することと等しい。

有効なそれぞれのフィルタに、次のフラグの 1 つが含まれていなければならない。

D3DX_FILTER_BOX
各ピクセルは、ソース イメージ内の 2 × 2 (× 2) のサイズのボックスに含まれるピクセルの平均を算出することにより計算される。このフィルタは、ミップマップを使用する場合のように、転送先のディメンジョンがソースの半分の場合のみ機能する。
D3DX_FILTER_LINEAR
各転送先ピクセルは、最も近い 4 つのピクセルをソース イメージからサンプリングすることにより計算される。このフィルタは、両軸のスケールが 2 未満の場合に最も効率よく機能する。
D3DX_FILTER_NONE
スケーリングまたはフィルタリングを行わない。ソース イメージの境界の外側にあるピクセルは透明な黒であると見なされる。
D3DX_FILTER_POINT
各転送先ピクセルは、最も近いピクセルをソース イメージからサンプリングすることにより計算される。
D3DX_FILTER_TRIANGLE
ソース イメージ内の各ピクセルが、転送先イメージに等しく反映される。これは、最も処理に時間のかかるフィルタである。

さらに、OR 演算子を使用して、有効なフィルタと共に次に示すオプションのフラグを 0 個以上指定できる。内部的には、常に D3DX_FILTER_MIRROR フラグが使用される。

D3DX_FILTER_MIRROR
このフラグを指定すると、D3DX_FILTER_MIRROR_U、D3DX_FILTER_MIRROR_V、および D3DX_FILTER_MIRROR_W フラグを指定したことになる。このフラグは、この関数では常に内部的に使用される。
D3DX_FILTER_MIRROR_U
u 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_V
v 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_W
w 軸のテクスチャのエッジから離れているピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_DITHER
結果として作成されたイメージを、4x4 の順序付きディザ アルゴリズムを使ってディザリングする必要がある。
ColorKey
[in] 透明となる D3DCOLOR の値。カラーキーを無効にする場合は 0 を指定する。ソース イメージのフォーマットとは関係なく、これは常に 32 ビットの ARGB カラーである。アルファが有意であり、通常はカラーキーを不透明にする場合は FF を指定する。したがって、不透明な黒の場合、値は 0xFF000000 となる。
pSrcInfo
[in, out] ソース イメージ ファイル内のデータの記述を格納する D3DXIMAGE_INFO 構造体へのポインタ、または NULL。
pPalette
[out] 格納する 256 色パレットを表す PALETTEENTRY 構造体へのポインタ、または NULL。「注意」を参照すること。
ppCubeTexture
[out] 作成されたキューブ テクスチャ オブジェクトを表す、IDirect3DCubeTexture8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

注意

キューブ テクスチャは、サーフェスのコレクションである点でほかのサーフェスとは異なる。キューブ テクスチャを指定して SetRenderTarget を呼び出すには、IDirect3DCubeTexture8::GetCubeMapSurface を使用して個々の面を選択し、結果サーフェスを SetRenderTarget に渡す必要がある。

PALETTEENTRY の詳細については、Microsoft® Platform Software Development Kit (SDK) を参照すること。Microsoft DirectX 8.0® の時点で、PALLETTEENTRY 構造体の peFlags メンバは、Platform SDK に説明されているようには機能しない。peFlags メンバは現在、8 ビットのパレット化されたフォーマット用のアルファ チャネルである。

#define UNICODE スイッチを挿入または除外して、アプリケーションで Unicode または ANSI 文字列のどちらを使用するかを指定する。次のコードは、D3DXCreateCubeTextureFromFileEx の定義方法を示している。

#ifdef UNICODE
#define D3DXCreateCubeTextureFromFileEx D3DXCreateCubeTextureFromFileExW
#else
#define D3DXCreateCubeTextureFromFileEx D3DXCreateCubeTextureFromFileExA
#endif

D3DXCreateCubeTextureFromFileExA は、DirectDrawSurface (DDS) ファイル フォーマットを使用する。DXTex ツールによって、ほかのファイル フォーマットからキューブ マップを生成し、それを DDS ファイル フォーマットで保存することができる。

動作環境

ヘッダー : d3dx8mesh.h で宣言。

参照

D3DXCreateCubeTextureFromFileExW


D3DXCreateCubeTextureFromFileExW

Unicode 文字列で指定されたファイルからキューブ テクスチャを作成する。これは、D3DXCreateCubeTextureFromFileW よりも高度な関数である。

D3DXCreateCubeTextureFromFileEx は、#define UNICODE スイッチが含まれているかどうかに応じて、D3DXCreateCubeTextureFromFileExA または D3DXCreateCubeTextureFromFileExW のどちらかをマップする。「注意」を参照すること。

HRESULT D3DXCreateCubeTextureFromFileExW(
  LPDIRECT3DDEVICE8 pDevice,
  LPCWSTR pSrcFile,
  UINT Size,
  UINT MipLevels,
  DWORD Usage,
  D3DFORMAT Format,
  D3DPOOL Pool,
  DWORD Filter,
  DWORD MipFilter,
  D3DCOLOR ColorKey,
  D3DXIMAGE_INFO* pSrcInfo,
  PALETTEENTRY* pPalette,
  LPDIRECT3DCUBETEXTURE8* ppCubeTexture
);

パラメータ

pDevice
[in] キューブ テクスチャに関連付けられるデバイスを表す IDirect3DDevice8 インターフェイスへのポインタ。
pSrcFile
[in] キューブ テクスチャの作成に使用するファイルを指定する Unicode 文字列へのポインタ。「注意」を参照すること。
Size
[in] キューブ テクスチャの幅と高さ (ピクセル単位)。たとえば、キューブ テクスチャが 8x8 ピクセルのキューブの場合、このパラメータの値は 8 となる。この値が 0 または D3DX_DEFAULT の場合、ディメンジョンはファイルから取得される。
MipLevels
[in] 要求されるミップ レベルの数。この値が 0 または D3DX_DEFAULT の場合は、完全なミップマップ チェーンが作成される。
Usage
[in] 0 または D3DUSAGE_RENDERTARGET。このフラグに D3DUSAGE_RENDERTARGET を設定すると、そのサーフェスはレンダリング ターゲットとして使用されることを示す。リソースは、SetRenderTarget メソッドの pNewRenderTarget パラメータに渡すことができる。D3DUSAGE_RENDERTARGET を指定する場合、アプリケーションは IDirect3D8::CheckDeviceFormat を呼び出して、デバイスがこれらの処理をサポートしていることを確認する必要がある。「注意」を参照すること。
Format
[in] キューブ テクスチャに対して要求されたピクセル フォーマットを記述する、D3DFORMAT 列挙型のメンバ。返されるキューブ テクスチャのフォーマットは Format で指定されたフォーマットと異なる場合がある。アプリケーションは、返されたキューブ テクスチャのフォーマットを確認する必要がある。Format が D3DFMT_UNKNOWN の場合、フォーマットはファイルから取得される。
Pool
[in] キューブ テクスチャの配置先となるメモリ クラスを記述する、D3DPOOL 列挙型のメンバ。
Filter
[in] イメージをフィルタリングする方法を制御する 1 つ以上のフラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_TRIANGLE | D3DX_FILTER_DITHER を指定することと等しい。

有効なそれぞれのフィルタに、次のフラグの 1 つが含まれていなければならない。

D3DX_FILTER_BOX
各ピクセルは、ソース イメージ内の 2 × 2 (× 2) のサイズのボックスに含まれるピクセルの平均を算出することにより計算される。このフィルタは、ミップマップを使用する場合のように、転送先のディメンジョンがソースの半分の場合のみ機能する。
D3DX_FILTER_LINEAR
各転送先ピクセルは、最も近い 4 つのピクセルをソース イメージからサンプリングすることにより計算される。このフィルタは、両軸のスケールが 2 未満の場合に最も効率よく機能する。
D3DX_FILTER_NONE
スケーリングまたはフィルタリングを行わない。ソース イメージの境界の外側にあるピクセルは透明な黒であると見なされる。
D3DX_FILTER_POINT
各転送先ピクセルは、最も近いピクセルをソース イメージからサンプリングすることにより計算される。
D3DX_FILTER_TRIANGLE
ソース イメージ内の各ピクセルが、転送先イメージに等しく反映される。これは、最も処理に時間のかかるフィルタである。

さらに、OR 演算子を使用して、有効なフィルタと共に次に示すオプションのフラグを 0 個以上指定できる。内部的には、常に D3DX_FILTER_MIRROR フラグが使用される。

D3DX_FILTER_MIRROR
このフラグを指定すると、D3DX_FILTER_MIRROR_U、D3DX_FILTER_MIRROR_V、および D3DX_FILTER_MIRROR_W フラグを指定したことになる。このフラグは、この関数では常に内部的に使用される。
D3DX_FILTER_MIRROR_U
u 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_V
v 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_W
w 軸のテクスチャのエッジから離れているピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_DITHER
結果として作成されたイメージを、4x4 の順序付きディザ アルゴリズムを使ってディザリングする必要がある。
MipFilter
[in] イメージをフィルタリングする方法を制御する 1 つ以上のフラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_BOX を指定することと等しい。

有効なそれぞれのフィルタに、次のフラグの 1 つが含まれていなければならない。

D3DX_FILTER_BOX
各ピクセルは、ソース イメージ内の 2 × 2 (× 2) のサイズのボックスに含まれるピクセルの平均を算出することにより計算される。このフィルタは、ミップマップを使用する場合のように、転送先のディメンジョンがソースの半分の場合のみ機能する。
D3DX_FILTER_LINEAR
各転送先ピクセルは、最も近い 4 つのピクセルをソース イメージからサンプリングすることにより計算される。このフィルタは、両軸のスケールが 2 未満の場合に最も効率よく機能する。
D3DX_FILTER_NONE
スケーリングまたはフィルタリングを行わない。ソース イメージの境界の外側にあるピクセルは透明な黒であると見なされる。
D3DX_FILTER_POINT
各転送先ピクセルは、最も近いピクセルをソース イメージからサンプリングすることにより計算される。
D3DX_FILTER_TRIANGLE
ソース イメージ内の各ピクセルが、転送先イメージに等しく反映される。これは、最も処理に時間のかかるフィルタである。

さらに、OR 演算子を使用して、有効なフィルタと共に次に示すオプションのフラグを 0 個以上指定できる。内部的には、常に D3DX_FILTER_MIRROR フラグが使用される。

D3DX_FILTER_MIRROR
このフラグを指定すると、D3DX_FILTER_MIRROR_U、D3DX_FILTER_MIRROR_V、および D3DX_FILTER_MIRROR_W フラグを指定したことになる。このフラグは、この関数では常に内部的に使用される。
D3DX_FILTER_MIRROR_U
u 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_V
v 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_W
w 軸のテクスチャのエッジから離れているピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_DITHER
結果として作成されたイメージを、4x4 の順序付きディザ アルゴリズムを使ってディザリングする必要がある。
ColorKey
[in] 透明となる D3DCOLOR の値。カラーキーを無効にする場合は 0 を指定する。ソース イメージのフォーマットとは関係なく、これは常に 32 ビットの ARGB カラーである。アルファが有意であり、通常はカラーキーを不透明にする場合は FF を指定する。したがって、不透明な黒の場合、値は 0xFF000000 となる。
pSrcInfo
[in, out] ソース イメージ ファイル内のデータの記述を格納する D3DXIMAGE_INFO 構造体へのポインタ、または NULL。
pPalette
[out] 格納する 256 色パレットを表す PALETTEENTRY 構造体へのポインタ、または NULL。「注意」を参照すること。
ppCubeTexture
[out] 作成されたキューブ テクスチャ オブジェクトを表す、IDirect3DCubeTexture8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

注意

キューブ テクスチャは、サーフェスのコレクションである点でほかのサーフェスとは異なる。キューブ テクスチャを指定して SetRenderTarget を呼び出すには、IDirect3DCubeTexture8::GetCubeMapSurface を使用して個々の面を選択し、結果サーフェスを SetRenderTarget に渡す必要がある。

PALETTEENTRY の詳細については、Microsoft® Platform Software Development Kit (SDK) を参照すること。Microsoft DirectX® 8.0 の時点で、PALLETTEENTRY 構造体の peFlags メンバは、Platform SDK に説明されているようには機能しない。peFlags メンバは現在、8 ビットのパレット化されたフォーマット用のアルファ チャネルである。

#define UNICODE スイッチを挿入または除外して、アプリケーションで Unicode または ANSI 文字列のどちらを使用するかを指定する。次のコードは、D3DXCreateCubeTextureFromFileEx の定義方法を示している。

#ifdef UNICODE
#define D3DXCreateCubeTextureFromFileEx D3DXCreateCubeTextureFromFileExW
#else
#define D3DXCreateCubeTextureFromFileEx D3DXCreateCubeTextureFromFileExA
#endif

D3DXCreateCubeTextureFromFileExW は、DirectDrawSurface (DDS) ファイル フォーマットを使用する。DXTex ツールによって、ほかのファイル フォーマットからキューブ マップを生成し、それを DDS ファイル フォーマットで保存することができる。

動作環境

ヘッダー : d3dx8mesh.h で宣言。

参照

D3DXCreateCubeTextureFromFileExA


D3DXCreateCubeTextureFromFileInMemory

メモリ内のファイルからキューブ テクスチャを作成する。

HRESULT D3DXCreateCubeTextureFromFileInMemory(
  LPDIRECT3DDEVICE8 pDevice,
  LPCVOID pSrcData,
  UINT SrcDataSize,
  LPDIRECT3DCUBETEXTURE8* ppCubeTexture
);

パラメータ

pDevice
[in] キューブ テクスチャに関連付けられるデバイスを表す IDirect3DDevice8 インターフェイスへのポインタ。
pSrcData
[in] キューブマップの作成に使用するメモリ内のファイルへのポインタ。「注意」を参照すること。
SrcDataSize
[in] メモリ内のファイルのサイズ (バイト単位)。
ppCubeTexture
[out] 作成されたキューブ テクスチャ オブジェクトを表す、IDirect3DCubeTexture8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

注意

この関数を使用して作成したリソースは、D3DPOOL_MANAGED で示されるメモリ クラスに配置される。

このメソッドは、アプリケーション定義のリソース (未加工データ) である、RT_RCDATA として格納されたイメージ ファイルをロードするために使用するように設計されている。それ以外の目的に使用すると、このメソッドは失敗する。

D3DXCreateCubeTextureFromFileInMemory は、DirectDrawSurface (DDS) ファイル フォーマットを使用する。DXTex ツールによって、ほかのファイル フォーマットからキューブ マップを生成し、それを DDS ファイル フォーマットで保存することができる。

動作環境

ヘッダー : d3dx8mesh.h で宣言。


D3DXCreateCubeTextureFromFileInMemoryEx

メモリ内のファイルからキューブ テクスチャを作成する。これは、D3DXCreateCubeTextureFromFileInMemory よりも高度な関数である。

HRESULT D3DXCreateCubeTextureFromFileInMemoryEx(
  LPDIRECT3DDEVICE8 pDevice,
  LPCVOID pSrcData,
  UINT SrcDataSize,
  UINT Size,
  UINT MipLevels,
  DWORD Usage,
  D3DFORMAT Format,
  D3DPOOL Pool,
  DWORD Filter,
  DWORD MipFilter,
  D3DCOLOR ColorKey,
  D3DXIMAGE_INFO* pSrcInfo,
  PALETTEENTRY* pPalette,
  LPDIRECT3DCUBETEXTURE8* ppCubeTexture
);

パラメータ

pDevice
[in] キューブ テクスチャに関連付けられるデバイスを表す IDirect3DDevice8 インターフェイスへのポインタ。
pSrcData
[in] キューブ テクスチャの作成に使用するメモリ内のファイルへのポインタ。「注意」を参照すること。
SrcDataSize
[in] メモリ内のファイルのサイズ (バイト単位)。
Size
[in] 幅と高さ (ピクセル単位)。この値が 0 または D3DX_DEFAULT の場合、ディメンジョンはファイルから取得される。
MipLevels
[in] 要求されるミップ レベルの数。この値が 0 または D3DX_DEFAULT の場合は、完全なミップマップ チェーンが作成される。
Usage
[in] 0 または D3DUSAGE_RENDERTARGET。このフラグに D3DUSAGE_RENDERTARGET を設定すると、そのサーフェスはレンダリング ターゲットとして使用されることを示す。リソースは、SetRenderTarget メソッドの pNewRenderTarget パラメータに渡すことができる。D3DUSAGE_RENDERTARGET を指定する場合、アプリケーションは IDirect3D8::CheckDeviceFormat を呼び出して、デバイスがこれらの処理をサポートしていることを確認する必要がある。「注意」を参照すること。
Format
[in] キューブ テクスチャに対して要求されたピクセル フォーマットを記述する、D3DFORMAT 列挙型のメンバ。返されるテクスチャのフォーマットは Format で指定されたフォーマットと異なる場合がある。アプリケーションは、返されたテクスチャのフォーマットを確認する必要がある。Format が D3DFMT_UNKNOWN の場合、フォーマットはファイルから取得される。
Pool
[in] キューブ テクスチャの配置先となるメモリ クラスを記述する、D3DPOOL 列挙型のメンバ。
Filter
[in] イメージをフィルタリングする方法を制御する 1 つ以上のフラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_TRIANGLE | D3DX_FILTER_DITHER を指定することと等しい。

有効なそれぞれのフィルタに、次のフラグの 1 つが含まれていなければならない。

D3DX_FILTER_BOX
各ピクセルは、ソース イメージ内の 2 × 2 (× 2) のサイズのボックスに含まれるピクセルの平均を算出することにより計算される。このフィルタは、ミップマップを使用する場合のように、転送先のディメンジョンがソースの半分の場合のみ機能する。
D3DX_FILTER_LINEAR
各転送先ピクセルは、最も近い 4 つのピクセルをソース イメージからサンプリングすることにより計算される。このフィルタは、両軸のスケールが 2 未満の場合に最も効率よく機能する。
D3DX_FILTER_NONE
スケーリングまたはフィルタリングを行わない。ソース イメージの境界の外側にあるピクセルは透明な黒であると見なされる。
D3DX_FILTER_POINT
各転送先ピクセルは、最も近いピクセルをソース イメージからサンプリングすることにより計算される。
D3DX_FILTER_TRIANGLE
ソース イメージ内の各ピクセルが、転送先イメージに等しく反映される。これは、最も処理に時間のかかるフィルタである。

さらに、OR 演算子を使用して、有効なフィルタと共に次に示すオプションのフラグを 0 個以上指定できる。内部的には、常に D3DX_FILTER_MIRROR フラグが使用される。

D3DX_FILTER_MIRROR
このフラグを指定すると、D3DX_FILTER_MIRROR_U、D3DX_FILTER_MIRROR_V、および D3DX_FILTER_MIRROR_W フラグを指定したことになる。このフラグは、この関数では常に内部的に使用される。
D3DX_FILTER_MIRROR_U
u 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_V
v 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_W
w 軸のテクスチャのエッジから離れているピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_DITHER
結果として作成されたイメージを、4x4 の順序付きディザ アルゴリズムを使ってディザリングする必要がある。
MipFilter
[in] イメージをフィルタリングする方法を制御する 1 つ以上のフラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_BOX を指定することと等しい。

有効なそれぞれのフィルタに、次のフラグの 1 つが含まれていなければならない。

D3DX_FILTER_BOX
各ピクセルは、ソース イメージ内の 2 × 2 (× 2) のサイズのボックスに含まれるピクセルの平均を算出することにより計算される。このフィルタは、ミップマップを使用する場合のように、転送先のディメンジョンがソースの半分の場合のみ機能する。
D3DX_FILTER_LINEAR
各転送先ピクセルは、最も近い 4 つのピクセルをソース イメージからサンプリングすることにより計算される。このフィルタは、両軸のスケールが 2 未満の場合に最も効率よく機能する。
D3DX_FILTER_NONE
スケーリングまたはフィルタリングを行わない。ソース イメージの境界の外側にあるピクセルは透明な黒であると見なされる。
D3DX_FILTER_POINT
各転送先ピクセルは、最も近いピクセルをソース イメージからサンプリングすることにより計算される。
D3DX_FILTER_TRIANGLE
ソース イメージ内の各ピクセルが、転送先イメージに等しく反映される。これは、最も処理に時間のかかるフィルタである。

さらに、OR 演算子を使用して、有効なフィルタと共に次に示すオプションのフラグを 0 個以上指定できる。内部的には、常に D3DX_FILTER_MIRROR フラグが使用される

D3DX_FILTER_MIRROR
このフラグを指定すると、D3DX_FILTER_MIRROR_U、D3DX_FILTER_MIRROR_V、および D3DX_FILTER_MIRROR_W フラグを指定したことになる。このフラグは、この関数では常に内部的に使用される。
D3DX_FILTER_MIRROR_U
u 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_V
v 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_W
w 軸のテクスチャのエッジから離れているピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_DITHER
結果として作成されたイメージを、4x4 の順序付きディザ アルゴリズムを使ってディザリングする必要がある。
ColorKey
[in] 透明となる D3DCOLOR の値。カラーキーを無効にする場合は 0 を指定する。ソース イメージのフォーマットとは関係なく、これは常に 32 ビットの ARGB カラーである。アルファが有意であり、通常はカラーキーを不透明にする場合は FF を指定する。したがって、不透明な黒の場合、値は 0xFF000000 となる。
pSrcInfo
[in, out] ソース イメージ ファイル内のデータの記述を格納する D3DXIMAGE_INFO 構造体へのポインタ、または NULL。
pPalette
[out] 格納する 256 色パレットを表す PALETTEENTRY 構造体へのポインタ、または NULL。「注意」を参照すること。
ppCubeTexture
[out] 作成されたキューブ テクスチャ オブジェクトを表す、IDirect3DCubeTexture8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

注意

キューブ テクスチャは、サーフェスのコレクションである点でほかのサーフェスとは異なる。キューブ テクスチャを指定して SetRenderTarget を呼び出すには、IDirect3DCubeTexture8::GetCubeMapSurface を使用して個々の面を選択し、結果サーフェスを SetRenderTarget に渡す必要がある。

このメソッドは、アプリケーション定義のリソース (未加工データ) である、RT_RCDATA として格納されたイメージ ファイルをロードするために使用するように設計されている。それ以外の目的に使用すると、このメソッドは失敗する。

PALETTEENTRY の詳細については、Microsoft® Platform Software Development Kit (SDK) を参照すること。Microsoft DirectX® 8.0 の時点で、PALLETTEENTRY 構造体の peFlags メンバは、Platform SDK に説明されているようには機能しない。peFlags メンバは現在、8 ビットのパレット化されたフォーマット用のアルファ チャネルである。

D3DXCreateCubeTextureFromFileInMemoryEx は、DirectDrawSurface (DDS) ファイル フォーマットを使用する。DXTex ツールによって、ほかのファイル フォーマットからキューブ マップを生成し、それを DDS ファイル フォーマットで保存することができる。

動作環境

ヘッダー : d3dx8mesh.h で宣言。


D3DXCreateCubeTextureFromFileW

Unicode 文字列で指定されたファイルからキューブ テクスチャを作成する。

D3DXCreateCubeTextureFromFile は、#define UNICODE スイッチが含まれているかどうかに応じて、D3DXCreateCubeTextureFromFileA または D3DXCreateCubeTextureFromFileW のどちらかをマップする。

HRESULT D3DXCreateCubeTextureFromFileW(
  LPDIRECT3DDEVICE8 pDevice,
  LPCWSTR pSrcFile,
  LPDIRECT3DCUBETEXTURE8* ppCubeTexture
);

パラメータ

pDevice
[in] キューブ テクスチャに関連付けられるデバイスを表す IDirect3DDevice8 インターフェイスへのポインタ。
pSrcFile
[in] キューブ テクスチャの作成に使用するファイルを指定する Unicode 文字列へのポインタ。「注意」を参照すること。
ppCubeTexture
[out] 作成されたキューブ テクスチャ オブジェクトを表す、IDirect3DCubeTexture8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

注意

#define UNICODE スイッチを挿入または除外して、アプリケーションで Unicode または ANSI 文字列のどちらを使用するかを指定する。次のコードは、D3DXCreateCubeTextureFromFile の定義方法を示している。

#ifdef UNICODE
#define D3DXCreateCubeTextureFromFile D3DXCreateCubeTextureFromFileW
#else
#define D3DXCreateCubeTextureFromFile D3DXCreateCubeTextureFromFileA
#endif

この関数を使用して作成したリソースは、D3DPOOL_MANAGED で示されるメモリ クラスに配置される。

D3DXCreateCubeTextureFromFileInMemoryW は、DirectDrawSurface (DDS) ファイル フォーマットを使用する。DXTex ツールによって、ほかのファイル フォーマットからキューブ マップを生成し、それを DDS ファイル フォーマットで保存することができる。

動作環境

ヘッダー : d3dx8mesh.h で宣言。

参照

D3DXCreateCubeTextureFromFileA


D3DXCreateTexture

必要に応じて呼び出しパラメータを調整し、空のテクスチャを作成する。

HRESULT D3DXCreateTexture(
  LPDIRECT3DDEVICE8 pDevice,
  UINT Width,
  UINT Height,
  UINT MipLevels,
  DWORD Usage,
  D3DFORMAT Format,
  D3DPOOL Pool,
  LPDIRECT3DTEXTURE8* ppTexture
);

パラメータ

pDevice
[in] テクスチャに関連付けられているデバイスを表す IDirect3DDevice8 インターフェイスへのポインタ。
Width
[in] 幅 (ピクセル単位)。この値は 0 以外である必要がある。
Height
[in] 高さ (ピクセル単位)。この値は 0 以外である必要がある。
MipLevels
[in] 要求されるミップ レベルの数。この値が 0 または D3DX_DEFAULT の場合は、完全なミップマップ チェーンが作成される。
Usage
[in] 0 または D3DUSAGE_RENDERTARGET。このフラグに D3DUSAGE_RENDERTARGET を設定すると、そのサーフェスはレンダリング ターゲットとして使用されることを示す。リソースは、SetRenderTarget メソッドの pNewRenderTarget パラメータに渡すことができる。D3DUSAGE_RENDERTARGET を指定する場合、アプリケーションは IDirect3D8::CheckDeviceFormat を呼び出して、デバイスがこれらの処理をサポートしていることを確認する必要がある。
Format
[in] テクスチャに対して要求されたピクセル フォーマットを記述する D3DFORMAT 列挙型のメンバ。返されるテクスチャのフォーマットは Format で指定されたフォーマットと異なる場合がある。アプリケーションは、返されたテクスチャのフォーマットを確認する必要がある。
Pool
[in] テクスチャの配置先となるメモリ クラスを記述する、D3DPOOL 列挙型のメンバ。
ppTexture
[out] 作成されたテクスチャ オブジェクトを表す、IDirect3DTexture8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DERR_INVALIDCALL
E_OUTOFMEMORY

注意

D3DXCreateTexture は、内部で D3DXCheckTextureRequirements を使用して呼び出しパラメータを調整する。したがって、IDirect3Ddevice8::CreateTexture の呼び出しが失敗する場合でも、D3DXCreateTexture の呼び出しは成功することが多い。

動作環境

ヘッダー : D3dx8tex.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXCreateTextureFromFileA

ANSI 文字列で指定したファイルを元にしてテクスチャを作成する。

HRESULT D3DXCreateTextureFromFileA(
  LPDIRECT3DDEVICE8 pDevice,
  LPCSTR pSrcFile,
  LPDIRECT3DTEXTURE8* ppTexture
);

パラメータ

pDevice
[in] テクスチャに関連付けられているデバイスを表す IDirect3DDevice8 インターフェイスへのポインタ。
pSrcFile
[in] テクスチャの作成に使用するファイルを指定する ANSI 文字列へのポインタ。
ppTexture
[out] 作成されたテクスチャ オブジェクトを表す、IDirect3DTexture8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

注意

ミップマップされたテクスチャの各レベルには、ロードされたテクスチャが自動的に格納される。

ミップマップされたテクスチャにイメージをロードするとき、デバイスによっては、1x1 のイメージに変換できず、関数が失敗することがある。このような場合は、イメージを手動でロードする必要がある。

D3DXCreateTextureFromFile は、#define UNICODE スイッチが含まれているかどうかに応じて、D3DXCreateTextureFromFileA または D3DXCreateTextureFromFileW のどちらかをマップする。#define UNICODE スイッチを挿入または除外して、アプリケーションで Unicode または ANSI 文字列のどちらを使用するかを指定する。次のコードは、D3DXCreateTextureFromFile の定義方法を示している。

#ifdef UNICODE
#define D3DXCreateTextureFromFile D3DXCreateTextureFromFileW
#else
#define D3DXCreateTextureFromFile D3DXCreateTextureFromFileA
#endif

この関数を使用して作成したリソースは、D3DPOOL_MANAGED で示されるメモリ クラスに配置される。

動作環境

ヘッダー : D3dx8tex.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXCreateTextureFromFileExA、D3DXCreateTextureFromFileExW、D3DXCreateTextureFromFileW


D3DXCreateTextureFromFileExA

ANSI 文字列で指定したファイルを元にしてテクスチャを作成する。これは、D3DXCreateTextureFromFileA よりも高度な関数である。

HRESULT D3DXCreateTextureFromFileExA(
  LPDIRECT3DDEVICE8 pDevice,
  LPCSTR pSrcFile,
  UINT Width,
  UINT Height,
  UINT MipLevels,
  DWORD Usage,
  D3DFORMAT Format,
  D3DPOOL Pool,
  DWORD Filter,
  DWORD MipFilter,
  D3DCOLOR ColorKey,
  D3DXIMAGE_INFO* pSrcInfo,
  PALETTEENTRY* pPalette,
  LPDIRECT3DTEXTURE8* ppTexture
);

パラメータ

pDevice
[in] テクスチャに関連付けられているデバイスを表す IDirect3DDevice8 インターフェイスへのポインタ。
pSrcFile
[in] テクスチャの作成に使用するファイルを指定する ANSI 文字列へのポインタ。
Width
[in] 幅 (ピクセル単位)。この値が 0 または D3DX_DEFAULT の場合、ディメンジョンはファイルから取得される。
Height
[in] 高さ (ピクセル単位)。この値が 0 または D3DX_DEFAULT の場合、ディメンジョンはファイルから取得される。
MipLevels
[in] 要求されるミップ レベルの数。この値が 0 または D3DX_DEFAULT の場合は、完全なミップマップ チェーンが作成される。
Usage
[in] 0 または D3DUSAGE_RENDERTARGET。このフラグに D3DUSAGE_RENDERTARGET を設定すると、そのサーフェスはレンダリング ターゲットとして使用されることを示す。リソースは、SetRenderTarget メソッドの pNewRenderTarget パラメータに渡すことができる。D3DUSAGE_RENDERTARGET を指定する場合、Pool に D3DPOOL_DEFAULT を設定し、アプリケーションは IDirect3D8::CheckDeviceFormat を呼び出して、デバイスがこれらの処理をサポートしていることを確認する必要がある。
Format
テクスチャに対して要求されたピクセル フォーマットを記述する、D3DFORMAT 列挙型のメンバ。返されるテクスチャのフォーマットは Format で指定されたフォーマットと異なる場合がある。アプリケーションは、返されたテクスチャのフォーマットを確認する必要がある。Format が D3DFMT_UNKNOWN の場合、フォーマットはファイルから取得される。
Pool
[in] テクスチャの配置先となるメモリ クラスを記述する、D3DPOOL 列挙型のメンバ。
Filter
[in] イメージをフィルタリングする方法を制御する 1 つ以上のフラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_TRIANGLE | D3DX_FILTER_DITHER を指定することと等しい。

有効なそれぞれのフィルタに、次のフラグの 1 つが含まれていなければならない。

D3DX_FILTER_BOX
各ピクセルは、ソース イメージ内の 2 × 2 (× 2) のサイズのボックスに含まれるピクセルの平均を算出することにより計算される。このフィルタは、ミップマップを使用する場合のように、転送先のディメンジョンがソースの半分の場合のみ機能する。
D3DX_FILTER_LINEAR
各転送先ピクセルは、最も近い 4 つのピクセルをソース イメージからサンプリングすることにより計算される。このフィルタは、両軸のスケールが 2 未満の場合に最も効率よく機能する。
D3DX_FILTER_NONE
スケーリングまたはフィルタリングを行わない。ソース イメージの境界の外側にあるピクセルは透明な黒であると見なされる。
D3DX_FILTER_POINT
各転送先ピクセルは、最も近いピクセルをソース イメージからサンプリングすることにより計算される。
D3DX_FILTER_TRIANGLE
ソース イメージ内の各ピクセルが、転送先イメージに等しく反映される。これは、最も処理に時間のかかるフィルタである。

さらに、OR 演算子を使用して、有効なフィルタと共に次に示すオプションのフラグを 0 個以上指定できる。

D3DX_FILTER_MIRROR
このフラグを指定すると、D3DX_FILTER_MIRROR_U、D3DX_FILTER_MIRROR_V、および D3DX_FILTER_MIRROR_W フラグを指定したことになる。
D3DX_FILTER_MIRROR_U
u 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_V
v 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_W
w 軸のテクスチャのエッジから離れているピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_DITHER
結果として作成されたイメージを、4x4 の順序付きディザ アルゴリズムを使ってディザリングする必要がある。
MipFilter
[in] イメージをフィルタリングする方法を制御する 1 つ以上のフラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_BOX を指定することと等しい。

有効なそれぞれのフィルタに、次のフラグの 1 つが含まれていなければならない。

D3DX_FILTER_BOX
各ピクセルは、ソース イメージ内の 2 × 2 (× 2) のサイズのボックスに含まれるピクセルの平均を算出することにより計算される。このフィルタは、ミップマップを使用する場合のように、転送先のディメンジョンがソースの半分の場合のみ機能する。
D3DX_FILTER_LINEAR
各転送先ピクセルは、最も近い 4 つのピクセルをソース イメージからサンプリングすることにより計算される。このフィルタは、両軸のスケールが 2 未満の場合に最も効率よく機能する。
D3DX_FILTER_NONE
スケーリングまたはフィルタリングを行わない。ソース イメージの境界の外側にあるピクセルは透明な黒であると見なされる。
D3DX_FILTER_POINT
各転送先ピクセルは、最も近いピクセルをソース イメージからサンプリングすることにより計算される。
D3DX_FILTER_TRIANGLE
ソース イメージ内の各ピクセルが、転送先イメージに等しく反映される。これは、最も処理に時間のかかるフィルタである。

さらに、OR 演算子を使用して、有効なフィルタと共に次に示すオプションのフラグを 0 個以上指定できる。

D3DX_FILTER_MIRROR
このフラグを指定すると、D3DX_FILTER_MIRROR_U、D3DX_FILTER_MIRROR_V、および D3DX_FILTER_MIRROR_W フラグを指定したことになる。
D3DX_FILTER_MIRROR_U
u 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_V
v 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_W
w 軸のテクスチャのエッジから離れているピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_DITHER
結果として作成されたイメージを、4x4 の順序付きディザ アルゴリズムを使ってディザリングする必要がある。
ColorKey
[in] 透明となる D3DCOLOR の値。カラーキーを無効にする場合は 0 を指定する。ソース イメージのフォーマットとは関係なく、これは常に 32 ビットの ARGB カラーである。アルファが有意であり、通常はカラーキーを不透明にする場合は FF を指定する。したがって、不透明な黒の場合、値は 0xFF000000 となる。
pSrcInfo
[in, out] ソース イメージ ファイル内のデータの記述を格納する D3DXIMAGE_INFO 構造体へのポインタ、または NULL。
pPalette
[out] 格納する 256 色パレットを表す PALETTEENTRY 構造体へのポインタ、または NULL。「注意」を参照すること。
ppTexture
[out] 作成されたテクスチャ オブジェクトを表す、IDirect3DTexture8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

注意

ミップマップされたテクスチャの各レベルには、ロードされたテクスチャが自動的に格納される。

ミップマップされたテクスチャにイメージをロードするとき、デバイスによっては、1x1 のイメージに変換できず、関数が失敗することがある。このような場合は、イメージを手動でロードする必要がある。

PALETTEENTRY の詳細については、Microsoft® Platform Software Development Kit (SDK) を参照すること。Microsoft DirectX® 8.0 の時点で、PALLETTEENTRY 構造体の peFlags メンバは、Platform SDK に説明されているようには機能しない。peFlags メンバは現在、8 ビットのパレット化されたフォーマット用のアルファ チャネルである。

D3DXCreateTextureFromFileEx は、#define UNICODE スイッチが含まれているかどうかに応じて、D3DXCreateTextureFromFileExA または D3DXCreateTextureFromFileExW のどちらかをマップする。#define UNICODE スイッチを挿入または除外して、アプリケーションで Unicode または ANSI 文字列のどちらを使用するかを指定する。次のコードは、D3DXCreateTextureFromFileEx の定義方法を示している。

#ifdef UNICODE
#define D3DXCreateTextureFromFileEx D3DXCreateTextureFromFileExW
#else
#define D3DXCreateTextureFromFileEx D3DXCreateTextureFromFileExA
#endif

動作環境

ヘッダー : D3dx8tex.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXCreateTextureFromFileA、D3DXCreateTextureFromFileExW、D3DXCreateTextureFromFileW


D3DXCreateTextureFromFileExW

Unicode 文字列で指定されたファイルからテクスチャを作成する。これは、D3DXCreateTextureFromFileW よりも高度な関数である。

HRESULT D3DXCreateTextureFromFileExW(
  LPDIRECT3DDEVICE8 pDevice,
  LPCWSTR pSrcFile,
  UINT Width,
  UINT Height,
  UINT MipLevels,
  DWORD Usage,
  D3DFORMAT Format,
  D3DPOOL Pool,
  DWORD Filter,
  DWORD MipFilter,
  D3DCOLOR ColorKey,
  D3DXIMAGE_INFO* pSrcInfo,
  PALETTEENTRY* pPalette,
  LPDIRECT3DTEXTURE8* ppTexture
);

パラメータ

pDevice
[in] テクスチャに関連付けられているデバイスを表す IDirect3DDevice8 インターフェイスへのポインタ。
pSrcFile
[in] テクスチャの作成に使用するファイルを指定する Unicode 文字列へのポインタ。
Width
[in] 幅 (ピクセル単位)。この値が 0 または D3DX_DEFAULT の場合、ディメンジョンはファイルから取得される。
Height
[in] 高さ (ピクセル単位)。この値が 0 または D3DX_DEFAULT の場合、ディメンジョンはファイルから取得される。
MipLevels
[in] 要求されるミップ レベルの数。この値が 0 または D3DX_DEFAULT の場合は、完全なミップマップ チェーンが作成される。
Usage
[in] 0 または D3DUSAGE_RENDERTARGET。このフラグに D3DUSAGE_RENDERTARGET を設定すると、そのサーフェスはレンダリング ターゲットとして使用されることを示す。リソースは、SetRenderTarget メソッドの pNewRenderTarget パラメータに渡すことができる。D3DUSAGE_RENDERTARGET を指定する場合、Pool に D3DPOOL_DEFAULT を設定し、アプリケーションは IDirect3D8::CheckDeviceFormat を呼び出して、デバイスがこの処理をサポートしていることを確認する必要がある。
Format
[in] テクスチャに対して要求されたピクセル フォーマットを記述する D3DFORMAT 列挙型のメンバ。返されるテクスチャのフォーマットは Format で指定されたフォーマットと異なる場合がある。アプリケーションは、返されたテクスチャのフォーマットを確認する必要がある。Format が D3DFMT_UNKNOWN の場合、フォーマットはファイルから取得される。
Pool
[in] テクスチャの配置先となるメモリ クラスを記述する、D3DPOOL 列挙型のメンバ。
Filter
[in] イメージをフィルタリングする方法を制御する 1 つ以上のフラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_TRIANGLE | D3DX_FILTER_DITHER を指定することと等しい。

有効なそれぞれのフィルタに、次のフラグの 1 つが含まれていなければならない。

D3DX_FILTER_BOX
各ピクセルは、ソース イメージ内の 2 × 2 (× 2) のサイズのボックスに含まれるピクセルの平均を算出することにより計算される。このフィルタは、ミップマップを使用する場合のように、転送先のディメンジョンがソースの半分の場合のみ機能する。
D3DX_FILTER_LINEAR
各転送先ピクセルは、最も近い 4 つのピクセルをソース イメージからサンプリングすることにより計算される。このフィルタは、両軸のスケールが 2 未満の場合に最も効率よく機能する。
D3DX_FILTER_NONE
スケーリングまたはフィルタリングを行わない。ソース イメージの境界の外側にあるピクセルは透明な黒であると見なされる。
D3DX_FILTER_POINT
各転送先ピクセルは、最も近いピクセルをソース イメージからサンプリングすることにより計算される。
D3DX_FILTER_TRIANGLE
ソース イメージ内の各ピクセルが、転送先イメージに等しく反映される。これは、最も処理に時間のかかるフィルタである。

さらに、OR 演算子を使用して、有効なフィルタと共に次に示すオプションのフラグを 0 個以上指定できる。

D3DX_FILTER_MIRROR
このフラグを指定すると、D3DX_FILTER_MIRROR_U、D3DX_FILTER_MIRROR_V、および D3DX_FILTER_MIRROR_W フラグを指定したことになる。
D3DX_FILTER_MIRROR_U
u 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_V
v 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_W
w 軸のテクスチャのエッジから離れているピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_DITHER
結果として作成されたイメージを、4x4 の順序付きディザ アルゴリズムを使ってディザリングする必要がある。
MipFilter
[in] イメージをフィルタリングする方法を制御する 1 つ以上のフラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_BOX を指定することと等しい。

有効なそれぞれのフィルタに、次のフラグの 1 つが含まれていなければならない。

D3DX_FILTER_BOX
各ピクセルは、ソース イメージ内の 2 × 2 (× 2) のサイズのボックスに含まれるピクセルの平均を算出することにより計算される。このフィルタは、ミップマップを使用する場合のように、転送先のディメンジョンがソースの半分の場合のみ機能する。
D3DX_FILTER_LINEAR
各転送先ピクセルは、最も近い 4 つのピクセルをソース イメージからサンプリングすることにより計算される。このフィルタは、両軸のスケールが 2 未満の場合に最も効率よく機能する。
D3DX_FILTER_NONE
スケーリングまたはフィルタリングを行わない。ソース イメージの境界の外側にあるピクセルは透明な黒であると見なされる。
D3DX_FILTER_POINT
各転送先ピクセルは、最も近いピクセルをソース イメージからサンプリングすることにより計算される。
D3DX_FILTER_TRIANGLE
ソース イメージ内の各ピクセルが、転送先イメージに等しく反映される。これは、最も処理に時間のかかるフィルタである。

さらに、OR 演算子を使用して、有効なフィルタと共に次に示すオプションのフラグを 0 個以上指定できる。

D3DX_FILTER_MIRROR
このフラグを指定すると、D3DX_FILTER_MIRROR_U、D3DX_FILTER_MIRROR_V、および D3DX_FILTER_MIRROR_W フラグを指定したことになる。
D3DX_FILTER_MIRROR_U
u 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_V
v 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_W
w 軸のテクスチャのエッジから離れているピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_DITHER
結果として作成されたイメージを、4x4 の順序付きディザ アルゴリズムを使ってディザリングする必要がある。
ColorKey
[in] 透明となる D3DCOLOR の値。カラーキーを無効にする場合は 0 を指定する。ソース イメージのフォーマットとは関係なく、これは常に 32 ビットの ARGB カラーである。アルファが有意であり、通常はカラーキーを不透明にする場合は FF を指定する。したがって、不透明な黒の場合、値は 0xFF000000 となる。
pSrcInfo
[in, out] ソース イメージ ファイル内のデータの記述を格納する D3DXIMAGE_INFO 構造体へのポインタ、または NULL。
pPalette
[out] 格納する 256 色パレットを表す PALETTEENTRY 構造体へのポインタ、または NULL。「注意」を参照すること。
ppTexture
[out] 作成されたテクスチャ オブジェクトを表す、IDirect3DTexture8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

注意

ミップマップされたテクスチャの各レベルには、ロードされたテクスチャが自動的に格納される。

ミップマップされたテクスチャにイメージをロードするとき、デバイスによっては、1x1 のイメージに変換できず、関数が失敗することがある。このような場合は、イメージを手動でロードする必要がある。

PALETTEENTRY の詳細については、Microsoft® Platform Software Development Kit (SDK) を参照すること。Microsoft DirectX® 8.0 の時点で、PALLETTEENTRY 構造体の peFlags メンバは、Platform SDK に説明されているようには機能しない。peFlags メンバは現在、8 ビットのパレット化されたフォーマット用のアルファ チャネルである。

D3DXCreateTextureFromFileEx は、#define UNICODE スイッチが含まれているかどうかに応じて、D3DXCreateTextureFromFileExA または D3DXCreateTextureFromFileExW のどちらかをマップする。#define UNICODE スイッチを挿入または除外して、アプリケーションで Unicode または ANSI 文字列のどちらを使用するかを指定する。次のコードは、D3DXCreateTextureFromFileEx の定義方法を示している。

#ifdef UNICODE
#define D3DXCreateTextureFromFileEx D3DXCreateTextureFromFileExW
#else
#define D3DXCreateTextureFromFileEx D3DXCreateTextureFromFileExA
#endif

動作環境

ヘッダー : D3dx8tex.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXCreateTextureFromFileA、D3DXCreateTextureFromFileExA、D3DXCreateTextureFromFileW


D3DXCreateTextureFromFileInMemory

メモリ内のファイルからテクスチャを作成する。

HRESULT D3DXCreateTextureFromFileInMemory(
  LPDIRECT3DDEVICE8 pDevice,
  LPCVOID pSrcData,
  UINT SrcData,
  LPDIRECT3DTEXTURE8* ppTexture
);

パラメータ

pDevice
[in] テクスチャに関連付けられているデバイスを表す IDirect3DDevice8 インターフェイスへのポインタ。
pSrcData
[in] テクスチャの作成に使用するメモリ内のファイルへのポインタ。
SrcData
[in] メモリ内のファイルのサイズ (バイト単位)。
ppTexture
[out] 作成されたテクスチャ オブジェクトを表す、IDirect3DTexture8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

注意

この関数を使用して作成したリソースは、D3DPOOL_MANAGED で示されるメモリ クラスに配置される。

このメソッドは、アプリケーション定義のリソース (未加工データ) である、RT_RCDATA として格納されたイメージ ファイルをロードするために使用するように設計されている。それ以外の目的に使用すると、このメソッドは失敗する。

動作環境

ヘッダー : D3dx8tex.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXCreateTextureFromFileInMemoryEx


D3DXCreateTextureFromFileInMemoryEx

メモリ内のファイルからテクスチャを作成する。これは、D3DXCreateTextureFromFileInMemory よりも高度な関数である。

HRESULT D3DXCreateTextureFromFileInMemoryEx(
  LPDIRECT3DDEVICE8 pDevice,
  LPCVOID pSrcData,
  UINT SrcData,
  UINT Width,
  UINT Height,
  UINT MipLevels,
  DWORD Usage,
  D3DFORMAT Format,
  D3DPOOL Pool,
  DWORD Filter,
  DWORD MipFilter,
  D3DCOLOR ColorKey,
  D3DXIMAGE_INFO* pSrcInfo
  PALETTEENTRY* pPalette,
  LPDIRECT3DTEXTURE8* ppTexture
);

パラメータ

pDevice
[in] テクスチャに関連付けられているデバイスを表す IDirect3DDevice8 インターフェイスへのポインタ。
pSrcData
[in] テクスチャの作成に使用するメモリ内のファイルへのポインタ。
SrcData
[in] メモリ内のファイルのサイズ (バイト単位)。
Width
[in] 幅 (ピクセル単位)。この値が 0 または D3DX_DEFAULT の場合、ディメンジョンはファイルから取得される。
Height
[in] 高さ (ピクセル単位)。この値が 0 または D3DX_DEFAULT の場合、ディメンジョンはファイルから取得される。
MipLevels
[in] 要求されるミップ レベルの数。この値が 0 または D3DX_DEFAULT の場合は、完全なミップマップ チェーンが作成される。
Usage
[in] 0 または D3DUSAGE_RENDERTARGET。このフラグに D3DUSAGE_RENDERTARGET を設定すると、そのサーフェスはレンダリング ターゲットとして使用されることを示す。リソースは、SetRenderTarget メソッドの pNewRenderTarget パラメータに渡すことができる。D3DUSAGE_RENDERTARGET を指定する場合、Pool に D3DPOOL_DEFAULT を設定し、アプリケーションは IDirect3D8::CheckDeviceFormat を呼び出して、デバイスがこの処理をサポートしていることを確認する必要がある。
Format
[in] テクスチャに対して要求されたピクセル フォーマットを記述する D3DFORMAT 列挙型のメンバ。返されるテクスチャのフォーマットは Format で指定されたフォーマットと異なる場合がある。アプリケーションは、返されたテクスチャのフォーマットを確認する必要がある。Format が D3DFMT_UNKNOWN の場合、フォーマットはファイルから取得される。
Pool
[in] テクスチャの配置先となるメモリ クラスを記述する、D3DPOOL 列挙型のメンバ。
Filter
[in] イメージをフィルタリングする方法を制御する 1 つ以上のフラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_TRIANGLE | D3DX_FILTER_DITHER を指定することと等しい。

有効なそれぞれのフィルタに、次のフラグの 1 つが含まれていなければならない。

D3DX_FILTER_BOX
各ピクセルは、ソース イメージ内の 2 × 2 (× 2) のサイズのボックスに含まれるピクセルの平均を算出することにより計算される。このフィルタは、ミップマップを使用する場合のように、転送先のディメンジョンがソースの半分の場合のみ機能する。
D3DX_FILTER_LINEAR
各転送先ピクセルは、最も近い 4 つのピクセルをソース イメージからサンプリングすることにより計算される。このフィルタは、両軸のスケールが 2 未満の場合に最も効率よく機能する。
D3DX_FILTER_NONE
スケーリングまたはフィルタリングを行わない。ソース イメージの境界の外側にあるピクセルは透明な黒であると見なされる。
D3DX_FILTER_POINT
各転送先ピクセルは、最も近いピクセルをソース イメージからサンプリングすることにより計算される。
D3DX_FILTER_TRIANGLE
ソース イメージ内の各ピクセルが、転送先イメージに等しく反映される。これは、最も処理に時間のかかるフィルタである。

さらに、OR 演算子を使用して、有効なフィルタと共に次に示すオプションのフラグを 0 個以上指定できる。

D3DX_FILTER_MIRROR
このフラグを指定すると、D3DX_FILTER_MIRROR_U、D3DX_FILTER_MIRROR_V、および D3DX_FILTER_MIRROR_W フラグを指定したことになる。
D3DX_FILTER_MIRROR_U
u 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_V
v 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_W
w 軸のテクスチャのエッジから離れているピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_DITHER
結果として作成されたイメージを、4x4 の順序付きディザ アルゴリズムを使ってディザリングする必要がある。
MipFilter
[in] イメージをフィルタリングする方法を制御する 1 つ以上のフラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_BOX を指定することと等しい。

有効なそれぞれのフィルタに、次のフラグの 1 つが含まれていなければならない。

D3DX_FILTER_BOX
各ピクセルは、ソース イメージ内の 2 × 2 (× 2) のサイズのボックスに含まれるピクセルの平均を算出することにより計算される。このフィルタは、ミップマップを使用する場合のように、転送先のディメンジョンがソースの半分の場合のみ機能する。
D3DX_FILTER_LINEAR
各転送先ピクセルは、最も近い 4 つのピクセルをソース イメージからサンプリングすることにより計算される。このフィルタは、両軸のスケールが 2 未満の場合に最も効率よく機能する。
D3DX_FILTER_NONE
スケーリングまたはフィルタリングを行わない。ソース イメージの境界の外側にあるピクセルは透明な黒であると見なされる。
D3DX_FILTER_POINT
各転送先ピクセルは、最も近いピクセルをソース イメージからサンプリングすることにより計算される。
D3DX_FILTER_TRIANGLE
ソース イメージ内の各ピクセルが、転送先イメージに等しく反映される。これは、最も処理に時間のかかるフィルタである。

さらに、OR 演算子を使用して、有効なフィルタと共に次に示すオプションのフラグを 0 個以上指定できる。

D3DX_FILTER_MIRROR
このフラグを指定すると、D3DX_FILTER_MIRROR_U、D3DX_FILTER_MIRROR_V、および D3DX_FILTER_MIRROR_W フラグを指定したことになる。
D3DX_FILTER_MIRROR_U
u 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_V
v 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_W
w 軸のテクスチャのエッジから離れているピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_DITHER
結果として作成されたイメージを、4x4 の順序付きディザ アルゴリズムを使ってディザリングする必要がある。
ColorKey
[in] 透明となる D3DCOLOR の値。カラーキーを無効にする場合は 0 を指定する。ソース イメージのフォーマットとは関係なく、これは常に 32 ビットの ARGB カラーである。アルファが有意であり、通常はカラーキーを不透明にする場合は FF を指定する。したがって、不透明な黒の場合、値は 0xFF000000 となる。
pSrcInfo
[in, out] ソース イメージ ファイル内のデータの記述を格納する D3DXIMAGE_INFO 構造体へのポインタ、または NULL。
pPalette
[out] 格納する 256 色パレットを表す PALETTEENTRY 構造体へのポインタ、または NULL。「注意」を参照すること。
ppTexture
[out] 作成されたテクスチャ オブジェクトを表す、IDirect3DTexture8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

注意

このメソッドは、アプリケーション定義のリソース (未加工データ) である、RT_RCDATA として格納されたイメージ ファイルをロードするために使用するように設計されている。それ以外の目的に使用すると、このメソッドは失敗する。

PALETTEENTRY の詳細については、Microsoft® Platform Software Development Kit (SDK) を参照すること。Microsoft DirectX® 8.0 の時点で、PALLETTEENTRY 構造体の peFlags メンバは、Platform SDK に説明されているようには機能しない。peFlags メンバは現在、8 ビットのパレット化されたフォーマット用のアルファ チャネルである。

動作環境

ヘッダー : D3dx8tex.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXCreateTextureFromFileInMemory


D3DXCreateTextureFromFileW

Unicode 文字列で指定されたファイルからテクスチャを作成する。

HRESULT D3DXCreateTextureFromFileW(
  LPDIRECT3DDEVICE8 pDevice,
  LPCWSTR pSrcFile,
  LPDIRECT3DTEXTURE8* ppTexture
);

パラメータ

pDevice
[in] テクスチャに関連付けられているデバイスを表す IDirect3DDevice8 インターフェイスへのポインタ。
pSrcFile
[in] テクスチャの作成に使用するファイルを指定する Unicode 文字列へのポインタ。
ppTexture
[out] 作成されたテクスチャ オブジェクトを表す、IDirect3DTexture8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

注意

ミップマップされたテクスチャの各レベルには、ロードされたテクスチャが自動的に格納される。

ミップマップされたテクスチャにイメージをロードするとき、デバイスによっては、1x1 のイメージに変換できず、関数が失敗することがある。このような場合は、イメージを手動でロードする必要がある。

D3DXCreateTextureFromFile は、#define UNICODE スイッチが含まれているかどうかに応じて、D3DXCreateTextureFromFileA または D3DXCreateTextureFromFileW のどちらかをマップする。#define UNICODE スイッチを挿入または除外して、アプリケーションで Unicode または ANSI 文字列のどちらを使用するかを指定する。次のコードは、D3DXCreateTextureFromFile の定義方法を示している。

#ifdef UNICODE
#define D3DXCreateTextureFromFile D3DXCreateTextureFromFileW
#else
#define D3DXCreateTextureFromFile D3DXCreateTextureFromFileA
#endif

この関数を使用して作成したリソースは、D3DPOOL_MANAGED で示されるメモリ クラスに配置される。

動作環境

ヘッダー : D3dx8tex.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXCreateTextureFromFileA、D3DXCreateTextureFromFileExA、D3DXCreateTextureFromFileExW


D3DXCreateTextureFromResourceA

ANSI 文字列で指定したリソースを元にしてテクスチャを作成する。

HRESULT D3DXCreateTextureFromResourceA(
  LPDIRECT3DDEVICE8 pDevice,
  HMODULE hSrcModule,
  LPCSTR pSrcResource,
  LPDIRECT3DTEXTURE8* ppTexture
);

パラメータ

pDevice
[in] テクスチャに関連付けられているデバイスを表す IDirect3DDevice8 インターフェイスへのポインタ。
hSrcModule
[in] リソースを特定しているモジュールへのハンドル。または、オペレーティング システムが現在のプロセスに使用するイメージに関連付けられているモジュールの場合は NULL。
pSrcResource
[in] テクスチャの作成に使用するリソースを指定する ANSI 文字列へのポインタ。
ppTexture
[out] 作成されたテクスチャ オブジェクトを表す、IDirect3DTexture8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

注意

ロードされるリソースはビットマップ リソース (RT_BITMAP) でなければならない。

D3DXCreateTextureFromResource は、#define UNICODE スイッチが含まれているかどうかに応じて、D3DXCreateTextureFromResourceA または D3DXCreateTextureFromResourceW のどちらかをマップする。#define UNICODE スイッチを挿入または除外して、アプリケーションで Unicode または ANSI 文字列のどちらを使用するかを指定する。次のコードは、D3DXCreateTextureFromResource の定義方法を示している。

#ifdef UNICODE
#define D3DXCreateTextureFromResource D3DXCreateTextureFromResourceW
#else
#define D3DXCreateTextureFromResource D3DXCreateTextureFromResourceA
#endif

この関数を使用して作成したリソースは、D3DPOOL_MANAGED で示されるメモリ クラスに配置される。

動作環境

ヘッダー : D3dx8tex.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXCreateTextureFromResourceExA、D3DXCreateTextureFromResourceExW、D3DXCreateTextureFromResourceW


D3DXCreateTextureFromResourceExA

ANSI 文字列で指定したリソースを元にしてテクスチャを作成する。これは、D3DXCreateTextureFromResourceA よりも高度な関数である。

HRESULT D3DXCreateTextureFromResourceExA(
  LPDIRECT3DDEVICE8 pDevice,
  HMODULE hSrcModule,
  LPCSTR pSrcResource,
  UINT Width,
  UINT Height,
  UINT MipLevels,
  DWORD Usage,
  D3DFORMAT Format,
  D3DPOOL Pool,
  DWORD Filter,
  DWORD MipFilter,
  D3DCOLOR ColorKey,
  D3DXIMAGE_INFO* pSrcInfo,
  PALETTEENTRY* pPalette,
  LPDIRECT3DTEXTURE8* ppTexture
);

パラメータ

pDevice
[in] テクスチャに関連付けられているデバイスを表す IDirect3DDevice8 インターフェイスへのポインタ。
hSrcModule
[in] リソースを特定しているモジュールへのハンドル。または、オペレーティング システムが現在のプロセスに使用するイメージに関連付けられているモジュールの場合は NULL。
pSrcResource
[in] テクスチャの作成に使用するリソースを指定する ANSI 文字列へのポインタ。
Width
[in] 幅 (ピクセル単位)。この値が 0 または D3DX_DEFAULT の場合、ディメンジョンはファイルから取得される。
Height
[in] 高さ (ピクセル単位)。この値が 0 または D3DX_DEFAULT の場合、ディメンジョンはファイルから取得される。
MipLevels
[in] 要求されるミップ レベルの数。この値が 0 または D3DX_DEFAULT の場合は、完全なミップマップ チェーンが作成される。
Usage
[in] 0 または D3DUSAGE_RENDERTARGET。このフラグに D3DUSAGE_RENDERTARGET を設定すると、そのサーフェスはレンダリング ターゲットとして使用されることを示す。リソースは、SetRenderTarget メソッドの pNewRenderTarget パラメータに渡すことができる。D3DUSAGE_RENDERTARGET を指定する場合、Pool に D3DPOOL_DEFAULT を設定し、アプリケーションは IDirect3D8::CheckDeviceFormat を呼び出して、デバイスがこの処理をサポートしていることを確認する必要がある。
Format
[in] テクスチャに対して要求されたピクセル フォーマットを記述する D3DFORMAT 列挙型のメンバ。返されるテクスチャのフォーマットは Format で指定されたフォーマットと異なる場合がある。アプリケーションは、返されたテクスチャのフォーマットを確認する必要がある。Format が D3DFMT_UNKNOWN の場合、フォーマットはファイルから取得される。
Pool
[in] テクスチャの配置先となるメモリ クラスを記述する、D3DPOOL 列挙型のメンバ。
Filter
[in] イメージをフィルタリングする方法を制御する 1 つ以上のフラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_TRIANGLE | D3DX_FILTER_DITHER を指定することと等しい。

有効なそれぞれのフィルタに、次のフラグの 1 つが含まれていなければならない。

D3DX_FILTER_BOX
各ピクセルは、ソース イメージ内の 2 × 2 (× 2) のサイズのボックスに含まれるピクセルの平均を算出することにより計算される。このフィルタは、ミップマップを使用する場合のように、転送先のディメンジョンがソースの半分の場合のみ機能する。
D3DX_FILTER_LINEAR
各転送先ピクセルは、最も近い 4 つのピクセルをソース イメージからサンプリングすることにより計算される。このフィルタは、両軸のスケールが 2 未満の場合に最も効率よく機能する。
D3DX_FILTER_NONE
スケーリングまたはフィルタリングを行わない。ソース イメージの境界の外側にあるピクセルは透明な黒であると見なされる。
D3DX_FILTER_POINT
各転送先ピクセルは、最も近いピクセルをソース イメージからサンプリングすることにより計算される。
D3DX_FILTER_TRIANGLE
ソース イメージ内の各ピクセルが、転送先イメージに等しく反映される。これは、最も処理に時間のかかるフィルタである。

さらに、OR 演算子を使用して、有効なフィルタと共に次に示すオプションのフラグを 0 個以上指定できる。

D3DX_FILTER_MIRROR
このフラグを指定すると、D3DX_FILTER_MIRROR_U、D3DX_FILTER_MIRROR_V、および D3DX_FILTER_MIRROR_W フラグを指定したことになる。
D3DX_FILTER_MIRROR_U
u 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_V
v 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_W
w 軸のテクスチャのエッジから離れているピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_DITHER
結果として作成されたイメージを、4x4 の順序付きディザ アルゴリズムを使ってディザリングする必要がある。
MipFilter
[in] イメージをフィルタリングする方法を制御する 1 つ以上のフラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_BOX を指定することと等しい。
D3DX_FILTER_BOX

有効なそれぞれのフィルタに、次のフラグの 1 つが含まれていなければならない。

D3DX_FILTER_BOX
各ピクセルは、ソース イメージ内の 2 × 2 (× 2) のサイズのボックスに含まれるピクセルの平均を算出することにより計算される。このフィルタは、ミップマップを使用する場合のように、転送先のディメンジョンがソースの半分の場合のみ機能する。
D3DX_FILTER_LINEAR
各転送先ピクセルは、最も近い 4 つのピクセルをソース イメージからサンプリングすることにより計算される。このフィルタは、両軸のスケールが 2 未満の場合に最も効率よく機能する。
D3DX_FILTER_NONE
スケーリングまたはフィルタリングを行わない。ソース イメージの境界の外側にあるピクセルは透明な黒であると見なされる。
D3DX_FILTER_POINT
各転送先ピクセルは、最も近いピクセルをソース イメージからサンプリングすることにより計算される。
D3DX_FILTER_TRIANGLE
ソース イメージ内の各ピクセルが、転送先イメージに等しく反映される。これは、最も処理に時間のかかるフィルタである。

さらに、OR 演算子を使用して、有効なフィルタと共に次に示すオプションのフラグを 0 個以上指定できる。

D3DX_FILTER_MIRROR
このフラグを指定すると、D3DX_FILTER_MIRROR_U、D3DX_FILTER_MIRROR_V、および D3DX_FILTER_MIRROR_W フラグを指定したことになる。
D3DX_FILTER_MIRROR_U
u 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_V
v 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_W
w 軸のテクスチャのエッジから離れているピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_DITHER
結果として作成されたイメージを、4x4 の順序付きディザ アルゴリズムを使ってディザリングする必要がある。
ColorKey
[in] 透明となる D3DCOLOR の値。カラーキーを無効にする場合は 0 を指定する。ソース イメージのフォーマットとは関係なく、これは常に 32 ビットの ARGB カラーである。アルファが有意であり、通常はカラーキーを不透明にする場合は FF を指定する。したがって、不透明な黒の場合、値は 0xFF000000 となる。
pSrcInfo
[in, out] ソース イメージ ファイル内のデータの記述を格納する D3DXIMAGE_INFO 構造体へのポインタ、または NULL。
pPalette
[out] 格納する 256 色パレットを表す PALETTEENTRY 構造体へのポインタ、または NULL。「注意」を参照すること。
ppTexture
[out] 作成されたテクスチャ オブジェクトを表す、IDirect3DTexture8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

注意

ロードされるリソースはビットマップ リソース (RT_BITMAP) でなければならない。

PALETTEENTRY の詳細については、Microsoft® Platform Software Development Kit (SDK) を参照すること。Microsoft DirectX® 8.0 の時点で、PALLETTEENTRY 構造体の peFlags メンバは、Platform SDK に説明されているようには機能しない。peFlags メンバは現在、8 ビットのパレット化されたフォーマット用のアルファ チャネルである。

D3DXCreateTextureFromResourceEx は、#define UNICODE スイッチが含まれているかどうかに応じて、D3DXCreateTextureFromResourceExA または D3DXCreateTextureFromResourceExW のどちらかをマップする。#define UNICODE スイッチを挿入または除外して、アプリケーションで Unicode または ANSI 文字列のどちらを使用するかを指定する。次のコードは、D3DXCreateTextureFromResourceEx の定義方法を示している。

#ifdef UNICODE
#define D3DXCreateTextureFromResourceEx D3DXCreateTextureFromResourceExW
#else
#define D3DXCreateTextureFromResourceEx D3DXCreateTextureFromResourceExA
#endif

動作環境

ヘッダー : D3dx8tex.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXCreateTextureFromResourceA、D3DXCreateTextureFromResourceW、 D3DXCreateTextureFromResourceExW


D3DXCreateTextureFromResourceExW

Unicode 文字列で指定したリソースを元にしてテクスチャを作成する。これは、D3DXCreateTextureFromResourceW よりも高度な関数である。

HRESULT D3DXCreateTextureFromResourceExW(
  LPDIRECT3DDEVICE8 pDevice,
  HMODULE hSrcModule,
  LPCWSTR pSrcResource,
  UINT Width,
  UINT Height,
  UINT MipLevels,
  DWORD Usage,
  D3DFORMAT Format,
  D3DPOOL Pool,
  DWORD Filter,
  DWORD MipFilter,
  D3DCOLOR ColorKey,
  D3DXIMAGE_INFO* pSrcInfo,
  PALETTEENTRY* pPalette,
  LPDIRECT3DTEXTURE8* ppTexture
);

パラメータ

pDevice
[in] テクスチャに関連付けられているデバイスを表す IDirect3DDevice8 インターフェイスへのポインタ。
hSrcModule
[in] リソースを特定しているモジュールへのハンドル。または、オペレーティング システムが現在のプロセスに使用するイメージに関連付けられているモジュールの場合は NULL。
pSrcResource
[in] テクスチャの作成に使用するリソースを指定する Unicode 文字列へのポインタ。
Width
[in] 幅 (ピクセル単位)。この値が 0 または D3DX_DEFAULT の場合、ディメンジョンはファイルから取得される。
Height
[in] 高さ (ピクセル単位)。この値が 0 または D3DX_DEFAULT の場合、ディメンジョンはファイルから取得される。
MipLevels
[in] 要求されるミップ レベルの数。この値が 0 または D3DX_DEFAULT の場合は、完全なミップマップ チェーンが作成される。
Usage
[in] 0 または D3DUSAGE_RENDERTARGET。このフラグに D3DUSAGE_RENDERTARGET を設定すると、そのサーフェスはレンダリング ターゲットとして使用されることを示す。リソースは、SetRenderTarget メソッドの pNewRenderTarget パラメータに渡すことができる。D3DUSAGE_RENDERTARGET を指定する場合、Pool に D3DPOOL_DEFAULT を設定し、アプリケーションは IDirect3D8::CheckDeviceFormat を呼び出して、デバイスがこの処理をサポートしていることを確認する必要がある。
Format
[in] テクスチャに対して要求されたピクセル フォーマットを記述する D3DFORMAT 列挙型のメンバ。返されるテクスチャのフォーマットは Format で指定されたフォーマットと異なる場合がある。アプリケーションは、返されたテクスチャのフォーマットを確認する必要がある。Format が D3DFMT_UNKNOWN の場合、フォーマットはファイルから取得される。
Pool
[in] テクスチャの配置先となるメモリ クラスを記述する、D3DPOOL 列挙型のメンバ。
Filter
[in] イメージをフィルタリングする方法を制御する 1 つ以上のフラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_TRIANGLE | D3DX_FILTER_DITHER を指定することと等しい。

有効なそれぞれのフィルタに、次のフラグの 1 つが含まれていなければならない。

D3DX_FILTER_BOX
各ピクセルは、ソース イメージ内の 2 × 2 (× 2) のサイズのボックスに含まれるピクセルの平均を算出することにより計算される。このフィルタは、ミップマップを使用する場合のように、転送先のディメンジョンがソースの半分の場合のみ機能する。
D3DX_FILTER_LINEAR
各転送先ピクセルは、最も近い 4 つのピクセルをソース イメージからサンプリングすることにより計算される。このフィルタは、両軸のスケールが 2 未満の場合に最も効率よく機能する。
D3DX_FILTER_NONE
スケーリングまたはフィルタリングを行わない。ソース イメージの境界の外側にあるピクセルは透明な黒であると見なされる。
D3DX_FILTER_POINT
各転送先ピクセルは、最も近いピクセルをソース イメージからサンプリングすることにより計算される。
D3DX_FILTER_TRIANGLE
ソース イメージ内の各ピクセルが、転送先イメージに等しく反映される。これは、最も処理に時間のかかるフィルタである。

さらに、OR 演算子を使用して、有効なフィルタと共に次に示すオプションのフラグを 0 個以上指定できる。

D3DX_FILTER_MIRROR
このフラグを指定すると、D3DX_FILTER_MIRROR_U、D3DX_FILTER_MIRROR_V、および D3DX_FILTER_MIRROR_W フラグを指定したことになる。
D3DX_FILTER_MIRROR_U
u 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_V
v 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_W
w 軸のテクスチャのエッジから離れているピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_DITHER
結果として作成されたイメージを、4x4 の順序付きディザ アルゴリズムを使ってディザリングする必要がある。
MipFilter
[in] イメージをフィルタリングする方法を制御する 1 つ以上のフラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_BOX を指定することと等しい。

有効なそれぞれのフィルタに、次のフラグの 1 つが含まれていなければならない。

D3DX_FILTER_BOX
各ピクセルは、ソース イメージ内の 2 × 2 (× 2) のサイズのボックスに含まれるピクセルの平均を算出することにより計算される。このフィルタは、ミップマップを使用する場合のように、転送先のディメンジョンがソースの半分の場合のみ機能する。
D3DX_FILTER_LINEAR
各転送先ピクセルは、最も近い 4 つのピクセルをソース イメージからサンプリングすることにより計算される。このフィルタは、両軸のスケールが 2 未満の場合に最も効率よく機能する。
D3DX_FILTER_NONE
スケーリングまたはフィルタリングを行わない。ソース イメージの境界の外側にあるピクセルは透明な黒であると見なされる。
D3DX_FILTER_POINT
各転送先ピクセルは、最も近いピクセルをソース イメージからサンプリングすることにより計算される。
D3DX_FILTER_TRIANGLE
ソース イメージ内の各ピクセルが、転送先イメージに等しく反映される。これは、最も処理に時間のかかるフィルタである。

さらに、OR 演算子を使用して、有効なフィルタと共に次に示すオプションのフラグを 0 個以上指定できる。

D3DX_FILTER_MIRROR
このフラグを指定すると、D3DX_FILTER_MIRROR_U、D3DX_FILTER_MIRROR_V、および D3DX_FILTER_MIRROR_W フラグを指定したことになる。
D3DX_FILTER_MIRROR_U
u 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_V
v 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_W
w 軸のテクスチャのエッジから離れているピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_DITHER
結果として作成されたイメージを、4x4 の順序付きディザ アルゴリズムを使ってディザリングする必要がある。
pSrcInfo
[in, out] ソース イメージ ファイル内のデータの記述を格納する D3DXIMAGE_INFO 構造体へのポインタ、または NULL。
ColorKey
[in] 透明となる D3DCOLOR の値。カラーキーを無効にする場合は 0 を指定する。ソース イメージのフォーマットとは関係なく、これは常に 32 ビットの ARGB カラーである。アルファが有意であり、通常はカラーキーを不透明にする場合は FF を指定する。したがって、不透明な黒の場合、値は 0xFF000000 となる。
pPalette
[out] 格納する 256 色パレットを表す PALETTEENTRY 構造体へのポインタ、または NULL。「注意」を参照すること。
ppTexture
[out] 作成されたテクスチャ オブジェクトを表す、IDirect3DTexture8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

注意

ロードされるリソースはビットマップ リソース (RT_BITMAP) でなければならない。

PALETTEENTRY の詳細については、Microsoft® Platform Software Development Kit (SDK) を参照すること。Microsoft DirectX® 8.0 の時点で、PALLETTEENTRY 構造体の peFlags メンバは、Platform SDK に説明されているようには機能しない。peFlags メンバは現在、8 ビットのパレット化されたフォーマット用のアルファ チャネルである。

D3DXCreateTextureFromResourceEx は、#define UNICODE スイッチが含まれているかどうかに応じて、D3DXCreateTextureFromResourceExA または D3DXCreateTextureFromResourceExW のどちらかをマップする。#define UNICODE スイッチを挿入または除外して、アプリケーションで Unicode または ANSI 文字列のどちらを使用するかを指定する。次のコードは、D3DXCreateTextureFromResourceEx の定義方法を示している。

#ifdef UNICODE
#define D3DXCreateTextureFromResourceEx D3DXCreateTextureFromResourceExW
#else
#define D3DXCreateTextureFromResourceEx D3DXCreateTextureFromResourceExA
#endif

動作環境

ヘッダー : D3dx8tex.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXCreateTextureFromResourceA、D3DXCreateTextureFromResourceExA、D3DXCreateTextureFromResourceW


D3DXCreateTextureFromResourceW

Unicode 文字列で指定したリソースを元にしてテクスチャを作成する。

HRESULT D3DXCreateTextureFromResourceW(
  LPDIRECT3DDEVICE8 pDevice,
  HMODULE hSrcModule,
  LPCWSTR pSrcResource,
  LPDIRECT3DTEXTURE8* ppTexture
);

パラメータ

pDevice
[in] テクスチャに関連付けられているデバイスを表す IDirect3DDevice8 インターフェイスへのポインタ。
hSrcModule
[in] リソースを特定しているモジュールへのハンドル。または、オペレーティング システムが現在のプロセスに使用するイメージに関連付けられているモジュールの場合は NULL。
pSrcResource
[in] テクスチャの作成に使用するリソースを指定する Unicode 文字列へのポインタ。
ppTexture
[out] 作成されたテクスチャ オブジェクトを表す、IDirect3DTexture8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

注意

ロードされるリソースはビットマップ リソース (RT_BITMAP) でなければならない。

D3DXCreateTextureFromResource は、#define UNICODE スイッチが含まれているかどうかに応じて、D3DXCreateTextureFromResourceA または D3DXCreateTextureFromResourceW のどちらかをマップする。#define UNICODE スイッチを挿入または除外して、アプリケーションで Unicode または ANSI 文字列のどちらを使用するかを指定する。次のコードは、D3DXCreateTextureFromResource の定義方法を示している。

#ifdef UNICODE
#define D3DXCreateTextureFromResource D3DXCreateTextureFromResourceW
#else
#define D3DXCreateTextureFromResource D3DXCreateTextureFromResourceA
#endif

この関数を使用して作成したリソースは、D3DPOOL_MANAGED で示されるメモリ クラスに配置される。

動作環境

ヘッダー : D3dx8tex.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXCreateTextureFromResourceA、D3DXCreateTextureFromResourceExA、D3DXCreateTextureFromResourceExW


D3DXCreateVolumeTexture

必要に応じて呼び出しパラメータを調整し、空のボリューム テクスチャを作成する。

HRESULT D3DXCreateVolumeTexture(
  LPDIRECT3DDEVICE8 pDevice,
  UINT Width,
  UINT Height,
  UINT Depth,
  UINT MipLevels,
  DWORD Usage,
  D3DFORMAT Format,
  D3DPOOL Pool,
  LPDIRECT3DVOLUMETEXTURE8* ppVolumeTexture
);

パラメータ

pDevice
[in] ボリューム テクスチャに関連付けられるデバイスを表す IDirect3DDevice8 インターフェイスへのポインタ。
Width
[in] 幅 (ピクセル単位)。この値は 0 以外である必要がある。
Height
[in] 高さ (ピクセル単位)。この値は 0 以外である必要がある。
Depth
[in] 深度 (単位ピクセル)。この値は 0 以外である必要がある。
MipLevels
[in] 要求されるミップ レベルの数。この値が 0 または D3DX_DEFAULT の場合は、完全なミップマップ チェーンが作成される。
Usage
[in] 現時点では未使用なので 0 を設定しておく。
Format
[in] ボリューム テクスチャに対して要求されたピクセル フォーマットを記述する、D3DFORMAT 列挙型のメンバ。返されるボリューム テクスチャのフォーマットは Format で指定されたフォーマットと異なる場合がある。アプリケーションは、返されたボリューム テクスチャのフォーマットを確認する必要がある。
Pool
[in] ボリューム テクスチャの配置先となるメモリ クラスを記述する、D3DPOOL 列挙型のメンバ。
ppVolumeTexture
[out] 作成されたボリューム テクスチャ オブジェクトを表す IDirect3DVolumeTexture8 インターフェイスへのポインタのアドレス。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DERR_INVALIDCALL
E_OUTOFMEMORY

注意

D3DXCreateVolumeTexture は、内部で D3DXCheckVolumeTextureRequirements を使用して呼び出しパラメータを調整する。したがって、IDirect3Ddevice8::CreateVolumeTexture の呼び出しが失敗する場合でも、D3DXCreateVolumeTexture の呼び出しは成功することが多い。

動作環境

ヘッダー : D3dx8tex.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXFilterCubeTexture

キューブ テクスチャ マップのミップマップ レベルをフィルタリングする。

HRESULT D3DXFilterCubeTexture(
  LPDIRECT3DCUBETEXTURE8 pCubeTexture,
  CONST PALETTEENTRY* pPalette,
  UINT SrcLevel,
  DWORD MipFilter
);

パラメータ

pCubeTexture
[in] フィルタリングするキューブ テクスチャ オブジェクトを表す、IDirect3DCubeTexture8 インターフェイスへのポインタ。
pPalette
[out] 格納する 256 色パレットを表す PALETTEENTRY 構造体へのポインタ、または NULL。パレットが指定されていない場合、デフォルトの Microsoft® Direct3D® パレット (完全に不透明な白のパレット) が提供される。「注意」を参照すること。
SrcLevel
[in] 下のレベルを生成するためにイメージを使用するレベル。このパラメータに D3DX_DEFAULT を指定することは、0 を指定することと等しい。
MipFilter
[in] ミップマップをフィルタリングする方法を制御する 1 つ以上のフラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_BOX | D3DX_FILTER_DITHER を指定することと等しい。

有効なそれぞれのフィルタに、次のフラグの 1 つが含まれていなければならない。

D3DX_FILTER_BOX
各ピクセルは、ソース イメージ内の 2 × 2 (× 2) のサイズのボックスに含まれるピクセルの平均を算出することにより計算される。このフィルタは、ミップマップを使用する場合のように、転送先のディメンジョンがソースの半分の場合のみ機能する。
D3DX_FILTER_LINEAR
各転送先ピクセルは、最も近い 4 つのピクセルをソース イメージからサンプリングすることにより計算される。このフィルタは、両軸のスケールが 2 未満の場合に最も効率よく機能する。
D3DX_FILTER_NONE
スケーリングまたはフィルタリングを行わない。ソース イメージの境界の外側にあるピクセルは透明な黒であると見なされる。
D3DX_FILTER_POINT
各転送先ピクセルは、最も近いピクセルをソース イメージからサンプリングすることにより計算される。
D3DX_FILTER_TRIANGLE
ソース イメージ内の各ピクセルが、転送先イメージに等しく反映される。これは、最も処理に時間のかかるフィルタである。

さらに、OR 演算子を使用して、有効なフィルタと共に次に示すオプションのフラグを 0 個以上指定できる。

D3DX_FILTER_MIRROR
このフラグを指定すると、D3DX_FILTER_MIRROR_U、D3DX_FILTER_MIRROR_V、および D3DX_FILTER_MIRROR_W フラグを指定したことになる。
D3DX_FILTER_MIRROR_U
u 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_V
v 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_W
w 軸のテクスチャのエッジから離れているピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_DITHER
結果として作成されたイメージを、4x4 の順序付きディザ アルゴリズムを使ってディザリングする必要がある。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

注意

キューブ テクスチャの各面について、各レベルで再帰的にボックスフィルタを適用して次のレベルを生成する。

デフォルトのプール (D3DPOOL_DEFAULT) に作成されたキューブ テクスチャを D3DXFilterCubeTexture と共に使用することはできない。オブジェクトに対するロック処理が必要なためである。デフォルト プール内のテクスチャに対するロックは禁止されている。

PALETTEENTRY の詳細については、Microsoft® Platform Software Development Kit (SDK) を参照すること。Microsoft DirectX® 8.0 の時点で、PALLETTEENTRY 構造体の peFlags メンバは、Platform SDK に説明されているようには機能しない。peFlags メンバは現在、8 ビットのパレット化されたフォーマット用のアルファ チャネルである。

非レベルゼロへの書き込みはアップデートすべきダーティーな矩形とはならない。D3DXFilterCubeTexture が呼び出され、サーフェイスが既にダーティーではなかった (これは通常の使用シナリオにはない) なら、アプリケーションは明示的にそのサーフェイスに IDirect3DTexture8::AddDirtyRect を呼び出す必要がある。

動作環境

ヘッダー : D3dx8tex.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXFilterTexture

テクスチャのミップマップ レベルをフィルタリングする。

HRESULT D3DXFilterTexture(
  LPDIRECT3DTEXTURE8 pTexture,
  CONST PALETTEENTRY* pPalette,
  UINT SrcLevel,
  DWORD MipFilter
);

パラメータ

pTexture
[in] フィルタリングするテクスチャ オブジェクトを表す、IDirect3DTexture8 インターフェイスへのポインタ。
pPalette
[out] 格納する 256 色パレットを表す PALETTEENTRY 構造体へのポインタ、または非パレット形式の場合は NULL。パレットが指定されていない場合、デフォルトの Microsoft® Direct3D® パレット (完全に不透明な白のパレット) が提供される。「注意」を参照すること。
SrcLevel
[in] 下のレベルを生成するためにイメージを使用するレベル。このパラメータに D3DX_DEFAULT を指定することは、0 を指定することと等しい。
MipFilter
[in] ミップマップをフィルタリングする方法を制御する 1 つ以上のフラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_BOX | D3DX_FILTER_DITHER を指定することと等しい。

有効なそれぞれのフィルタに、次のフラグの 1 つが含まれていなければならない。

D3DX_FILTER_BOX
各ピクセルは、ソース イメージ内の 2 × 2 (× 2) のサイズのボックスに含まれるピクセルの平均を算出することにより計算される。このフィルタは、ミップマップを使用する場合のように、転送先のディメンジョンがソースの半分の場合のみ機能する。
D3DX_FILTER_LINEAR
各転送先ピクセルは、最も近い 4 つのピクセルをソース イメージからサンプリングすることにより計算される。このフィルタは、両軸のスケールが 2 未満の場合に最も効率よく機能する。
D3DX_FILTER_NONE
スケーリングまたはフィルタリングを行わない。ソース イメージの境界の外側にあるピクセルは透明な黒であると見なされる。
D3DX_FILTER_POINT
各転送先ピクセルは、最も近いピクセルをソース イメージからサンプリングすることにより計算される。
D3DX_FILTER_TRIANGLE
ソース イメージ内の各ピクセルが、転送先イメージに等しく反映される。これは、最も処理に時間のかかるフィルタである。

さらに、OR 演算子を使用して、有効なフィルタと共に次に示すオプションのフラグを 0 個以上指定できる。

D3DX_FILTER_MIRROR
このフラグを指定すると、D3DX_FILTER_MIRROR_U、D3DX_FILTER_MIRROR_V、および D3DX_FILTER_MIRROR_W フラグを指定したことになる。
D3DX_FILTER_MIRROR_U
u 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_V
v 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_W
w 軸のテクスチャのエッジから離れているピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_DITHER
このフラグは、結果として作成されたイメージを、4x4 の順序付きディザ アルゴリズムを使ってディザリングすることを示す。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

注意

各テクスチャ レベルで再帰的にボックスフィルタを適用して次のテクスチャ レベルを生成する。

デフォルトのプール (D3DPOOL_DEFAULT) に作成されたテクスチャを D3DXFilterTexture と共に使用することはできない。オブジェクトに対するロック処理が必要なためである。デフォルト プール内のテクスチャに対するロックは禁止されている。

PALETTEENTRY の詳細については、Microsoft® Platform Software Development Kit (SDK) を参照すること。Microsoft DirectX® 8.0 の時点で、PALLETTEENTRY 構造体の peFlags メンバは、Platform SDK に説明されているようには機能しない。peFlags メンバは現在、8 ビットのパレット化されたフォーマット用のアルファ チャネルである。

非レベルゼロへの書き込みはアップデートすべきダーティーな矩形とはならない。D3DXFilterTexture が呼び出され、サーフェイスが既にダーティーではなかった (これは通常の使用シナリオにはない) なら、アプリケーションは明示的にそのサーフェイスに IDirect3DTexture8::AddDirtyRect を呼び出す必要がある。

動作環境

ヘッダー : D3dx8tex.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXFilterVolumeTexture

ボリューム テクスチャのミップマップ レベルをフィルタリングする。

HRESULT D3DXFilterVolumeTexture(
  LPDIRECT3DVOLUMETEXTURE8 pVolumeTexture,
  CONST PALETTEENTRY* pPalette,
  UINT SrcLevel,
  DWORD MipFilter
);

パラメータ

pVolumeTexture
[in] フィルタリングするボリューム テクスチャ オブジェクトを表す、IDirect3DVolumeTexture8 インターフェイスへのポインタ。
pPalette
[out] 格納する 256 色パレットを表す PALETTEENTRY 構造体へのポインタ、または非パレット形式の場合は NULL。パレットが指定されていない場合、デフォルトの Microsoft® Direct3D® パレット (完全に不透明な白のパレット) が提供される。「注意」を参照すること。
SrcLevel
[in] 下のレベルを生成するためにイメージを使用するレベル。このパラメータに D3DX_DEFAULT を指定することは、0 を指定することと等しい。
MipFilter
[in] ミップマップをフィルタリングする方法を制御する 1 つ以上のフラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_BOX | D3DX_FILTER_DITHER を指定することと等しい。

有効なそれぞれのフィルタに、次のフラグの 1 つが含まれていなければならない。

D3DX_FILTER_BOX
各ピクセルは、ソース イメージ内の 2 × 2 (× 2) のサイズのボックスに含まれるピクセルの平均を算出することにより計算される。このフィルタは、ミップマップを使用する場合のように、転送先のディメンジョンがソースの半分の場合のみ機能する。
D3DX_FILTER_LINEAR
各転送先ピクセルは、最も近い 4 つのピクセルをソース イメージからサンプリングすることにより計算される。このフィルタは、両軸のスケールが 2 未満の場合に最も効率よく機能する。
D3DX_FILTER_NONE
スケーリングまたはフィルタリングを行わない。ソース イメージの境界の外側にあるピクセルは透明な黒であると見なされる。
D3DX_FILTER_POINT
各転送先ピクセルは、最も近いピクセルをソース イメージからサンプリングすることにより計算される。
D3DX_FILTER_TRIANGLE
ソース イメージ内の各ピクセルが、転送先イメージに等しく反映される。これは、最も処理に時間のかかるフィルタである。

さらに、OR 演算子を使用して、有効なフィルタと共に次に示すオプションのフラグを 0 個以上指定できる。

D3DX_FILTER_MIRROR
このフラグを指定すると、D3DX_FILTER_MIRROR_U、D3DX_FILTER_MIRROR_V、および D3DX_FILTER_MIRROR_W フラグを指定したことになる。
D3DX_FILTER_MIRROR_U
u 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_V
v 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_W
w 軸のテクスチャのエッジから離れているピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_DITHER
結果として作成されたイメージを、4x4 の順序付きディザ アルゴリズムを使ってディザリングする必要がある。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、D3DERR_INVALIDCALL を返す。

注意

各テクスチャ レベルで再帰的にボックスフィルタを適用して次のテクスチャ レベルを生成する。

デフォルトのプール (D3DPOOL_DEFAULT) に作成されたボリューム テクスチャを D3DXFilterVolumeTexture と共に使用することはできない。オブジェクトに対するロック処理が必要なためである。デフォルト プール内のテクスチャに対するロックは禁止されている。

PALETTEENTRY の詳細については、Microsoft® Platform Software Development Kit (SDK) を参照すること。Microsoft DirectX® 8.0 の時点で、PALLETTEENTRY 構造体の peFlags メンバは、Platform SDK に説明されているようには機能しない。peFlags メンバは現在、8 ビットのパレット化されたフォーマット用のアルファ チャネルである。

非レベルゼロへの書き込みはアップデートすべきダーティーな矩形とはならない。D3DXFilterVolumeTexture が呼び出され、サーフェイスが既にダーティーではなかった (これは通常の使用シナリオにはない) なら、アプリケーションは明示的にそのサーフェイスに IDirect3DTexture8::AddDirtyRect を呼び出す必要がある。

動作環境

ヘッダー : D3dx8tex.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXLoadSurfaceFromFileA

ANSI 文字列で指定したファイルからサーフェスをロードする。

HRESULT D3DXLoadSurfaceFromFileA(
  LPDIRECT3DSURFACE8 pDestSurface,
  CONST PALETTEENTRY* pDestPalette,
  CONST RECT* pDestRect,
  LPCSTR pSrcFile,
  CONST RECT* pSrcRect,
  DWORD Filter,
  D3DCOLOR ColorKey,
  D3DXIMAGE_INFO* pSrcInfo
);

パラメータ

pDestSurface
[in] IDirect3DSurface8 インターフェイスへのポインタ。転送先のサーフェスを指定する。このサーフェスがイメージを受け取る。
pDestPalette
[in] 256 色の転送先パレットである PALETTEENTRY 構造体へのポインタ、または NULL。「注意」を参照すること。
pDestRect
[in] RECT 構造体へのポインタ。転送先矩形を指定する。このパラメータに NULL を設定して、サーフェス全体を指定する。
pSrcFile
[in] ソース イメージのファイル名を指定する ANSI 文字列へのポインタ。
pSrcRect
[in] RECT 構造体へのポインタ。転送元矩形を指定する。このパラメータに NULL を設定して、イメージ全体を指定する。
Filter
[in] イメージをフィルタリングする方法を制御する 1 つ以上のフラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_TRIANGLE | D3DX_FILTER_DITHER を指定することと等しい。

有効なそれぞれのフィルタに、次のフラグの 1 つが含まれていなければならない。

D3DX_FILTER_BOX
各ピクセルは、ソース イメージ内の 2 × 2 (× 2) のサイズのボックスに含まれるピクセルの平均を算出することにより計算される。このフィルタは、ミップマップを使用する場合のように、転送先のディメンジョンがソースの半分の場合のみ機能する。
D3DX_FILTER_LINEAR
各転送先ピクセルは、最も近い 4 つのピクセルをソース イメージからサンプリングすることにより計算される。このフィルタは、両軸のスケールが 2 未満の場合に最も効率よく機能する。
D3DX_FILTER_NONE
スケーリングまたはフィルタリングを行わない。ソース イメージの境界の外側にあるピクセルは透明な黒であると見なされる。
D3DX_FILTER_POINT
各転送先ピクセルは、最も近いピクセルをソース イメージからサンプリングすることにより計算される。
D3DX_FILTER_TRIANGLE
ソース イメージ内の各ピクセルが、転送先イメージに等しく反映される。これは、最も処理に時間のかかるフィルタである。

さらに、OR 演算子を使用して、有効なフィルタと共に次に示すオプションのフラグを 0 個以上指定できる。

D3DX_FILTER_MIRROR
このフラグを指定すると、D3DX_FILTER_MIRROR_U、D3DX_FILTER_MIRROR_V、および D3DX_FILTER_MIRROR_W フラグを指定したことになる。
D3DX_FILTER_MIRROR_U
u 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_V
v 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_W
w 軸のテクスチャのエッジから離れているピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_DITHER
結果として作成されたイメージを、4x4 の順序付きディザ アルゴリズムを使ってディザリングする必要がある。
ColorKey
[in] 透明となる D3DCOLOR の値。カラーキーを無効にする場合は 0 を指定する。ソース イメージのフォーマットとは関係なく、これは常に 32 ビットの ARGB カラーである。アルファが有意であり、通常はカラーキーを不透明にする場合は FF を指定する。したがって、不透明な黒の場合、値は 0xFF000000 となる。
pSrcInfo
[in, out] ソース イメージ ファイル内のデータの記述を格納する D3DXIMAGE_INFO 構造体へのポインタ、または NULL。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

注意

PALETTEENTRY の詳細については、Microsoft® Platform Software Development Kit (SDK) を参照すること。Microsoft DirectX® 8.0 の時点で、PALLETTEENTRY 構造体の peFlags メンバは、Platform SDK に説明されているようには機能しない。peFlags メンバは現在、8 ビットのパレット化されたフォーマット用のアルファ チャネルである。

D3DXLoadSurfaceFromFile は、#define UNICODE スイッチが含まれているかどうかに応じて、D3DXLoadSurfaceFromFileA または D3DXLoadSurfaceFromFileW のどちらかをマップする。#define UNICODE スイッチを挿入または除外して、アプリケーションで Unicode または ANSI 文字列のどちらを使用するかを指定する。次のコードは、D3DXLoadSurfaceFromFile の定義方法を示している。

非レベルゼロへの書き込みはアップデートすべきダーティーな矩形とはならない。D3DXLoadSurfaceFromFileA が呼び出され、サーフェイスが既にダーティーではなかった (これは通常の使用シナリオにはない) なら、アプリケーションは明示的にそのサーフェイスに IDirect3DTexture8::AddDirtyRect を呼び出す必要がある。

#ifdef UNICODE
#define D3DXLoadSurfaceFromFile D3DXLoadSurfaceFromFileW
#else
#define D3DXLoadSurfaceFromFile D3DXLoadSurfaceFromFileA
#endif

動作環境

ヘッダー : D3dx8tex.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXLoadSurfaceFromFileW


D3DXLoadSurfaceFromFileInMemory

メモリ内にあるファイルからサーフェスをロードする。

HRESULT D3DXLoadSurfaceFromFileInMemory(
  LPDIRECT3DSURFACE8 pDestSurface,
  CONST PALETTEENTRY* pDestPalette,
  CONST RECT* pDestRect,
  LPCVOID pSrcData,
  UINT SrcData,
  CONST RECT* pSrcRect,
  DWORD Filter,
  D3DCOLOR ColorKey,
  D3DXIMAGE_INFO* pSrcInfo
);

パラメータ

pDestSurface
[in] IDirect3DSurface8 インターフェイスへのポインタ。転送先のサーフェスを指定する。このサーフェスがイメージを受け取る。
pDestPalette
[in] 256 色の転送先パレットである PALETTEENTRY 構造体へのポインタ、または NULL。「注意」を参照すること。
pDestRect
[in] RECT 構造体へのポインタ。転送先矩形を指定する。このパラメータに NULL を設定して、サーフェス全体を指定する。
pSrcData
[in] ロードするサーフェスのあるメモリ内にあるファイルへのポインタ。
SrcData
[in] メモリ内のファイルのサイズ (バイト単位)。
pSrcRect
[in] RECT 構造体へのポインタ。転送元矩形を指定する。このパラメータに NULL を設定して、イメージ全体を指定する。
Filter
[in] イメージをフィルタリングする方法を制御する 1 つ以上のフラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_TRIANGLE | D3DX_FILTER_DITHER を指定することと等しい。

有効なそれぞれのフィルタに、次のフラグの 1 つが含まれていなければならない。

D3DX_FILTER_BOX
各ピクセルは、ソース イメージ内の 2 × 2 (× 2) のサイズのボックスに含まれるピクセルの平均を算出することにより計算される。このフィルタは、ミップマップを使用する場合のように、転送先のディメンジョンがソースの半分の場合のみ機能する。
D3DX_FILTER_LINEAR
各転送先ピクセルは、最も近い 4 つのピクセルをソース イメージからサンプリングすることにより計算される。このフィルタは、両軸のスケールが 2 未満の場合に最も効率よく機能する。
D3DX_FILTER_NONE
スケーリングまたはフィルタリングを行わない。ソース イメージの境界の外側にあるピクセルは透明な黒であると見なされる。
D3DX_FILTER_POINT
各転送先ピクセルは、最も近いピクセルをソース イメージからサンプリングすることにより計算される。
D3DX_FILTER_TRIANGLE
ソース イメージ内の各ピクセルが、転送先イメージに等しく反映される。これは、最も処理に時間のかかるフィルタである。

さらに、OR 演算子を使用して、有効なフィルタと共に次に示すオプションのフラグを 0 個以上指定できる。

D3DX_FILTER_MIRROR
このフラグを指定すると、D3DX_FILTER_MIRROR_U、D3DX_FILTER_MIRROR_V、および D3DX_FILTER_MIRROR_W フラグを指定したことになる。
D3DX_FILTER_MIRROR_U
u 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_V
v 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_W
w 軸のテクスチャのエッジから離れているピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_DITHER
結果として作成されたイメージを、4x4 の順序付きディザ アルゴリズムを使ってディザリングする必要がある。
ColorKey
[in] 透明となる D3DCOLOR の値。カラーキーを無効にする場合は 0 を指定する。ソース イメージのフォーマットとは関係なく、これは常に 32 ビットの ARGB カラーである。アルファが有意であり、通常はカラーキーを不透明にする場合は FF を指定する。したがって、不透明な黒の場合、値は 0xFF000000 となる。
pSrcInfo
[in, out] ソース イメージ ファイル内のデータの記述を格納する D3DXIMAGE_INFO 構造体へのポインタ、または NULL。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

注意

PALETTEENTRY の詳細については、Microsoft® Platform Software Development Kit (SDK) を参照すること。Microsoft DirectX® 8.0 の時点で、PALLETTEENTRY 構造体の peFlags メンバは、Platform SDK に説明されているようには機能しない。peFlags メンバは現在、8 ビットのパレット化されたフォーマット用のアルファ チャネルである。

非レベルゼロへの書き込みはアップデートすべきダーティーな矩形とはならない。D3DXLoadSurfaceFromFileInMemory が呼び出され、サーフェイスが既にダーティーではなかった (これは通常の使用シナリオにはない) なら、アプリケーションは明示的にそのサーフェイスに IDirect3DTexture8::AddDirtyRect を呼び出す必要がある。

動作環境

ヘッダー : D3dx8tex.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXLoadSurfaceFromFileW

Unicode 文字列で指定されたファイルからサーフェスをロードする。

HRESULT D3DXLoadSurfaceFromFileW(
  LPDIRECT3DSURFACE8 pDestSurface,
  CONST PALETTEENTRY* pDestPalette,
  CONST RECT* pDestRect,
  LPCWSTR pSrcFile,
  CONST RECT* pSrcRect,
  DWORD Filter,
  D3DCOLOR ColorKey,
  D3DXIMAGE_INFO* pSrcInfo
);

パラメータ

pDestSurface
[in] IDirect3DSurface8 インターフェイスへのポインタ。転送先のサーフェスを指定する。このサーフェスがイメージを受け取る。
pDestPalette
[in] 256 色の転送先パレットである PALETTEENTRY 構造体へのポインタ、または NULL。「注意」を参照すること。
pDestRect
[in] RECT 構造体へのポインタ。転送先矩形を指定する。このパラメータに NULL を設定して、サーフェス全体を指定する。
pSrcFile
[in] ソース イメージのファイル名を指定する Unicode 文字列へのポインタ。
pSrcRect
[in] RECT 構造体へのポインタ。転送元矩形を指定する。このパラメータに NULL を設定して、イメージ全体を指定する。
Filter
[in] イメージをフィルタリングする方法を制御する 1 つ以上のフラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_TRIANGLE | D3DX_FILTER_DITHER を指定することと等しい。

有効なそれぞれのフィルタに、次のフラグの 1 つが含まれていなければならない。

D3DX_FILTER_BOX
各ピクセルは、ソース イメージ内の 2 × 2 (× 2) のサイズのボックスに含まれるピクセルの平均を算出することにより計算される。このフィルタは、ミップマップを使用する場合のように、転送先のディメンジョンがソースの半分の場合のみ機能する。
D3DX_FILTER_LINEAR
各転送先ピクセルは、最も近い 4 つのピクセルをソース イメージからサンプリングすることにより計算される。このフィルタは、両軸のスケールが 2 未満の場合に最も効率よく機能する。
D3DX_FILTER_NONE
スケーリングまたはフィルタリングを行わない。ソース イメージの境界の外側にあるピクセルは透明な黒であると見なされる。
D3DX_FILTER_POINT
各転送先ピクセルは、最も近いピクセルをソース イメージからサンプリングすることにより計算される。
D3DX_FILTER_TRIANGLE
ソース イメージ内の各ピクセルが、転送先イメージに等しく反映される。これは、最も処理に時間のかかるフィルタである。

さらに、OR 演算子を使用して、有効なフィルタと共に次に示すオプションのフラグを 0 個以上指定できる。

D3DX_FILTER_MIRROR
このフラグを指定すると、D3DX_FILTER_MIRROR_U、D3DX_FILTER_MIRROR_V、および D3DX_FILTER_MIRROR_W フラグを指定したことになる。
D3DX_FILTER_MIRROR_U
u 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_V
v 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_W
w 軸のテクスチャのエッジから離れているピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_DITHER
結果として作成されたイメージを、4x4 の順序付きディザ アルゴリズムを使ってディザリングする必要がある。
ColorKey
[in] 透明となる D3DCOLOR の値。カラーキーを無効にする場合は 0 を指定する。ソース イメージのフォーマットとは関係なく、これは常に 32 ビットの ARGB カラーである。アルファが有意であり、通常はカラーキーを不透明にする場合は FF を指定する。したがって、不透明な黒の場合、値は 0xFF000000 となる。
pSrcInfo
[in, out] ソース イメージ ファイル内のデータの記述を格納する D3DXIMAGE_INFO 構造体へのポインタ、または NULL。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

注意

PALETTEENTRY の詳細については、Microsoft® Platform Software Development Kit (SDK) を参照すること。Microsoft DirectX® 8.0 の時点で、PALLETTEENTRY 構造体の peFlags メンバは、Platform SDK に説明されているようには機能しない。peFlags メンバは現在、8 ビットのパレット化されたフォーマット用のアルファ チャネルである。

D3DXLoadSurfaceFromFile は、#define UNICODE スイッチが含まれているかどうかに応じて、D3DXLoadSurfaceFromFileA または D3DXLoadSurfaceFromFileW のどちらかをマップする。#define UNICODE スイッチを挿入または除外して、アプリケーションで Unicode または ANSI 文字列のどちらを使用するかを指定する。次のコードは、D3DXLoadSurfaceFromFile の定義方法を示している。

非レベルゼロへの書き込みはアップデートすべきダーティーな矩形とはならない。D3DXLoadSurfaceFromFileW が呼び出され、サーフェイスが既にダーティーではなかった (これは通常の使用シナリオにはない) なら、アプリケーションは明示的にそのサーフェイスに IDirect3DTexture8::AddDirtyRect を呼び出す必要がある。

#ifdef UNICODE
#define D3DXLoadSurfaceFromFile D3DXLoadSurfaceFromFileW
#else
#define D3DXLoadSurfaceFromFile D3DXLoadSurfaceFromFileA
#endif

動作環境

ヘッダー : D3dx8tex.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXLoadSurfaceFromFileA


D3DXLoadSurfaceFromMemory

メモリからサーフェスをロードする。

HRESULT D3DXLoadSurfaceFromMemory(
  LPDIRECT3DSURFACE8 pDestSurface,
  CONST PALETTEENTRY* pDestPalette,
  CONST RECT* pDestRect,
  LPCVOID pSrcMemory,
  D3DFORMAT SrcFormat,
  UINT SrcPitch,
  CONST PALETTEENTRY* pSrcPalette,
  CONST RECT* pSrcRect,
  DWORD Filter,
  D3DCOLOR ColorKey
);

パラメータ

pDestSurface
[in] IDirect3DSurface8 インターフェイスへのポインタ。転送先のサーフェスを指定する。このサーフェスがイメージを受け取る。
pDestPalette
[in] 256 色の転送先パレットである PALETTEENTRY 構造体へのポインタ、または NULL。「注意」を参照すること。
pDestRect
[in] RECT 構造体へのポインタ。転送先矩形を指定する。このパラメータに NULL を設定して、サーフェス全体を指定する。
pSrcMemory
[in] メモリ内にあるソース イメージの左上隅へのポインタ。
SrcFormat
[in] ソース イメージのピクセル フォーマットである、D3DFORMAT 列挙型のメンバ。
SrcPitch
[in] 転送元のイメージのピッチ (バイト単位)。DXT フォーマットの場合、この数値はセルで構成される 1 つの行の幅 (バイト単位) を表す。
pSrcPalette
[in] 256 色の転送元パレットである PALETTEENTRY 構造体へのポインタ、または NULL。「注意」を参照すること。
pSrcRect
[in] RECT 構造体へのポインタ。メモリ内のソース イメージのディメンジョンを指定する。NULL を指定することはできない。
Filter
[in] イメージをフィルタリングする方法を制御する 1 つ以上のフラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_TRIANGLE | D3DX_FILTER_DITHER を指定することと等しい。

有効なそれぞれのフィルタに、次のフラグの 1 つが含まれていなければならない。

D3DX_FILTER_BOX
各ピクセルは、ソース イメージ内の 2 × 2 (× 2) のサイズのボックスに含まれるピクセルの平均を算出することにより計算される。このフィルタは、ミップマップを使用する場合のように、転送先のディメンジョンがソースの半分の場合のみ機能する。
D3DX_FILTER_LINEAR
各転送先ピクセルは、最も近い 4 つのピクセルをソース イメージからサンプリングすることにより計算される。このフィルタは、両軸のスケールが 2 未満の場合に最も効率よく機能する。
D3DX_FILTER_NONE
スケーリングまたはフィルタリングを行わない。ソース イメージの境界の外側にあるピクセルは透明な黒であると見なされる。
D3DX_FILTER_POINT
各転送先ピクセルは、最も近いピクセルをソース イメージからサンプリングすることにより計算される。
D3DX_FILTER_TRIANGLE
ソース イメージ内の各ピクセルが、転送先イメージに等しく反映される。これは、最も処理に時間のかかるフィルタである。

さらに、OR 演算子を使用して、有効なフィルタと共に次に示すオプションのフラグを 0 個以上指定できる。

D3DX_FILTER_MIRROR
このフラグを指定すると、D3DX_FILTER_MIRROR_U、D3DX_FILTER_MIRROR_V、および D3DX_FILTER_MIRROR_W フラグを指定したことになる。
D3DX_FILTER_MIRROR_U
u 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_V
v 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_W
w 軸のテクスチャのエッジから離れているピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_DITHER
結果として作成されたイメージを、4x4 の順序付きディザ アルゴリズムを使ってディザリングする必要がある。
ColorKey
[in] 透明となる D3DCOLOR の値。カラーキーを無効にする場合は 0 を指定する。ソース イメージのフォーマットとは関係なく、これは常に 32 ビットの ARGB カラーである。アルファが有意であり、通常はカラーキーを不透明にする場合は FF を指定する。したがって、不透明な黒の場合、値は 0xFF000000 となる。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

注意

PALETTEENTRY の詳細については、Microsoft® Platform Software Development Kit (SDK) を参照すること。Microsoft DirectX® 8.0 の時点で、PALLETTEENTRY 構造体の peFlags メンバは、Platform SDK に説明されているようには機能しない。peFlags メンバは現在、8 ビットのパレット化されたフォーマット用のアルファ チャネルである。

非レベルゼロへの書き込みはアップデートすべきダーティーな矩形とはならない。D3DXLoadSurfaceFromMemory が呼び出され、サーフェイスが既にダーティーではなかった (これは通常の使用シナリオにはない) なら、アプリケーションは明示的にそのサーフェイスに IDirect3DTexture8::AddDirtyRect を呼び出す必要がある。

動作環境

ヘッダー : D3dx8tex.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXLoadSurfaceFromResourceA

ANSI 文字列で指定したリソースからサーフェスをロードする。

HRESULT D3DXLoadSurfaceFromResourceA(
  LPDIRECT3DSURFACE8 pDestSurface,
  CONST PALETTEENTRY* pDestPalette,
  CONST RECT* pDestRect,
  HMODULE hSrcModule,
  LPCSTR pSrcResource,
  CONST RECT* pSrcRect,
  DWORD Filter,
  D3DCOLOR ColorKey,
  D3DXIMAGE_INFO* pSrcInfo
);

パラメータ

pDestSurface
[in] IDirect3DSurface8 インターフェイスへのポインタ。転送先のサーフェスを指定する。このサーフェスがイメージを受け取る。
pDestPalette
[in] 256 色の転送先パレットである PALETTEENTRY 構造体へのポインタ、または NULL。「注意」を参照すること。
pDestRect
[in] RECT 構造体へのポインタ。転送先矩形を指定する。このパラメータに NULL を設定して、サーフェス全体を指定する。
hSrcModule
[in] リソースを特定しているモジュールへのハンドル。または、オペレーティング システムが現在のプロセスに使用するイメージに関連付けられているモジュールの場合は NULL。
pSrcResource
[in] ソース イメージのリソース名を指定する ANSI 文字列へのポインタ。
pSrcRect
[in] RECT 構造体へのポインタ。転送元矩形を指定する。このパラメータに NULL を設定して、サーフェス全体を指定する。
Filter
[in] イメージをフィルタリングする方法を制御する 1 つ以上のフラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_TRIANGLE | D3DX_FILTER_DITHER を指定することと等しい。

有効なそれぞれのフィルタに、次のフラグの 1 つが含まれていなければならない。

D3DX_FILTER_BOX
各ピクセルは、ソース イメージ内の 2 × 2 (× 2) のサイズのボックスに含まれるピクセルの平均を算出することにより計算される。このフィルタは、ミップマップを使用する場合のように、転送先のディメンジョンがソースの半分の場合のみ機能する。
D3DX_FILTER_LINEAR
各転送先ピクセルは、最も近い 4 つのピクセルをソース イメージからサンプリングすることにより計算される。このフィルタは、両軸のスケールが 2 未満の場合に最も効率よく機能する。
D3DX_FILTER_NONE
スケーリングまたはフィルタリングを行わない。ソース イメージの境界の外側にあるピクセルは透明な黒であると見なされる。
D3DX_FILTER_POINT
各転送先ピクセルは、最も近いピクセルをソース イメージからサンプリングすることにより計算される。
D3DX_FILTER_TRIANGLE
ソース イメージ内の各ピクセルが、転送先イメージに等しく反映される。これは、最も処理に時間のかかるフィルタである。

さらに、OR 演算子を使用して、有効なフィルタと共に次に示すオプションのフラグを 0 個以上指定できる。

D3DX_FILTER_MIRROR
このフラグを指定すると、D3DX_FILTER_MIRROR_U、D3DX_FILTER_MIRROR_V、および D3DX_FILTER_MIRROR_W フラグを指定したことになる。
D3DX_FILTER_MIRROR_U
u 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_V
v 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_W
w 軸のテクスチャのエッジから離れているピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_DITHER
結果として作成されたイメージを、4x4 の順序付きディザ アルゴリズムを使ってディザリングする必要がある。
ColorKey
[in] 透明となる D3DCOLOR の値。カラーキーを無効にする場合は 0 を指定する。ソース イメージのフォーマットとは関係なく、これは常に 32 ビットの ARGB カラーである。アルファが有意であり、通常はカラーキーを不透明にする場合は FF を指定する。したがって、不透明な黒の場合、値は 0xFF000000 となる。
pSrcInfo
[in, out] ソース イメージ ファイル内のデータの記述を格納する D3DXIMAGE_INFO 構造体へのポインタ、または NULL。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

注意

ロードされるリソースはビットマップ リソース (RT_BITMAP) でなければならない。

PALETTEENTRY の詳細については、Microsoft® Platform Software Development Kit (SDK) を参照すること。Microsoft DirectX® 8.0 の時点で、PALLETTEENTRY 構造体の peFlags メンバは、Platform SDK に説明されているようには機能しない。peFlags メンバは現在、8 ビットのパレット化されたフォーマット用のアルファ チャネルである。

D3DXLoadSurfaceFromResource は、#define UNICODE スイッチが含まれているかどうかに応じて、D3DXLoadSurfaceFromResourceA または D3DXLoadSurfaceFromResourceW のどちらかをマップする。#define UNICODE スイッチを挿入または除外して、アプリケーションで Unicode または ANSI 文字列のどちらを使用するかを指定する。

非レベルゼロへの書き込みはアップデートすべきダーティーな矩形とはならない。D3DXLoadSurfaceFromResourceA が呼び出され、サーフェイスが既にダーティーではなかった (これは通常の使用シナリオにはない) なら、アプリケーションは明示的にそのサーフェイスに IDirect3DTexture8::AddDirtyRect を呼び出す必要がある。

次のコードは、D3DXLoadSurfaceFromResource の定義方法を示している。

#ifdef UNICODE
#define D3DXLoadSurfaceFromResource D3DXLoadSurfaceFromResourceW
#else
#define D3DXLoadSurfaceFromResource D3DXLoadSurfaceFromResourceA
#endif

動作環境

ヘッダー : D3dx8tex.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXLoadSurfaceFromResourceW


D3DXLoadSurfaceFromResourceW

Unicode 文字列で指定されたリソースからサーフェスをロードする。

HRESULT D3DXLoadSurfaceFromResourceW(
  LPDIRECT3DSURFACE8 pDestSurface,
  CONST PALETTEENTRY* pDestPalette,
  CONST RECT* pDestRect,
  HMODULE hSrcModule,
  LPCWSTR pSrcResource,
  CONST RECT* pSrcRect,
  DWORD Filter,
  D3DCOLOR ColorKey,
  D3DXIMAGE_INFO* pSrcInfo
);

パラメータ

pDestSurface
[in] IDirect3DSurface8 インターフェイスへのポインタ。転送先のサーフェスを指定する。このサーフェスがイメージを受け取る。
pDestPalette
[in] 256 色の転送先パレットである PALETTEENTRY 構造体へのポインタ、または NULL。「注意」を参照すること。
pDestRect
[in] RECT 構造体へのポインタ。転送先矩形を指定する。このパラメータに NULL を設定して、サーフェス全体を指定する。
hSrcModule
[in] リソースを特定しているモジュールへのハンドル。または、オペレーティング システムが現在のプロセスに使用するイメージに関連付けられているモジュールの場合は NULL。
pSrcResource
[in] ソース イメージのリソース名を指定する Unicode 文字列へのポインタ。
pSrcRect
[in] RECT 構造体へのポインタ。転送元矩形を指定する。このパラメータに NULL を設定して、サーフェス全体を指定する。
Filter
[in] イメージをフィルタリングする方法を制御する 1 つ以上のフラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_TRIANGLE | D3DX_FILTER_DITHER を指定することと等しい。

有効なそれぞれのフィルタに、次のフラグの 1 つが含まれていなければならない。

D3DX_FILTER_BOX
各ピクセルは、ソース イメージ内の 2 × 2 (× 2) のサイズのボックスに含まれるピクセルの平均を算出することにより計算される。このフィルタは、ミップマップを使用する場合のように、転送先のディメンジョンがソースの半分の場合のみ機能する。
D3DX_FILTER_LINEAR
各転送先ピクセルは、最も近い 4 つのピクセルをソース イメージからサンプリングすることにより計算される。このフィルタは、両軸のスケールが 2 未満の場合に最も効率よく機能する。
D3DX_FILTER_NONE
スケーリングまたはフィルタリングを行わない。ソース イメージの境界の外側にあるピクセルは透明な黒であると見なされる。
D3DX_FILTER_POINT
各転送先ピクセルは、最も近いピクセルをソース イメージからサンプリングすることにより計算される。
D3DX_FILTER_TRIANGLE
ソース イメージ内の各ピクセルが、転送先イメージに等しく反映される。これは、最も処理に時間のかかるフィルタである。

さらに、OR 演算子を使用して、有効なフィルタと共に次に示すオプションのフラグを 0 個以上指定できる。

D3DX_FILTER_MIRROR
このフラグを指定すると、D3DX_FILTER_MIRROR_U、D3DX_FILTER_MIRROR_V、および D3DX_FILTER_MIRROR_W フラグを指定したことになる。
D3DX_FILTER_MIRROR_U
u 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_V
v 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_W
w 軸のテクスチャのエッジから離れているピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_DITHER
結果として作成されたイメージを、4x4 の順序付きディザ アルゴリズムを使ってディザリングする必要がある。
ColorKey
[in] 透明となる D3DCOLOR の値。カラーキーを無効にする場合は 0 を指定する。ソース イメージのフォーマットとは関係なく、これは常に 32 ビットの ARGB カラーである。アルファが有意であり、通常はカラーキーを不透明にする場合は FF を指定する。したがって、不透明な黒の場合、値は 0xFF000000 となる。
pSrcInfo
[in, out] ソース イメージ ファイル内のデータの記述を格納する D3DXIMAGE_INFO 構造体へのポインタ、または NULL。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

注意

ロードされるリソースはビットマップ リソース (RT_BITMAP) でなければならない。

PALETTEENTRY の詳細については、Microsoft® Platform Software Development Kit (SDK) を参照すること。Microsoft DirectX® 8.0 の時点で、PALLETTEENTRY 構造体の peFlags メンバは、Platform SDK に説明されているようには機能しない。peFlags メンバは現在、8 ビットのパレット化されたフォーマット用のアルファ チャネルである。

D3DXLoadSurfaceFromResource は、#define UNICODE スイッチが含まれているかどうかに応じて、D3DXLoadSurfaceFromResourceA または D3DXLoadSurfaceFromResourceW のどちらかをマップする。#define UNICODE スイッチを挿入または除外して、アプリケーションで Unicode または ANSI 文字列のどちらを使用するかを指定する。

非レベルゼロへの書き込みはアップデートすべきダーティー矩形とはならない。D3DXLoadSurfaceFromResourceW が呼び出され、サーフェイスが既にダーティーではなかった (これは通常の使用シナリオにはない) なら、アプリケーションは明示的にそのサーフェイスに IDirect3DTexture8::AddDirtyRect を呼び出す必要がある。

次のコードは、D3DXLoadSurfaceFromResource の定義方法を示している。

#ifdef UNICODE
#define D3DXLoadSurfaceFromResource D3DXLoadSurfaceFromResourceW
#else
#define D3DXLoadSurfaceFromResource D3DXLoadSurfaceFromResourceA
#endif

動作環境

ヘッダー : D3dx8tex.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。

参照

D3DXLoadSurfaceFromResourceA


D3DXLoadSurfaceFromSurface

カラー変換を行いながら、別のサーフェスからサーフェスをロードする。

HRESULT D3DXLoadSurfaceFromSurface(
  LPDIRECT3DSURFACE8 pDestSurface,
  CONST PALETTEENTRY* pDestPalette,
  CONST RECT* pDestRect,
  LPDIRECT3DSURFACE8 pSrcSurface,
  CONST PALETTEENTRY* pSrcPalette,
  CONST RECT* pSrcRect,
  DWORD Filter,
  D3DCOLOR ColorKey
);

パラメータ

pDestSurface
[in] IDirect3DSurface8 インターフェイスへのポインタ。転送先のサーフェスを指定する。このサーフェスがイメージを受け取る。
pDestPalette
[in] 256 色の転送先パレットである PALETTEENTRY 構造体へのポインタ、または NULL。「注意」を参照すること。
pDestRect
[in] RECT 構造体へのポインタ。転送先矩形を指定する。このパラメータに NULL を設定して、サーフェス全体を指定する。
pSrcSurface
[in] 転送元サーフェスを表す IDirect3DSurface8 インターフェイスへのポインタ。
pSrcPalette
[in] 256 色の転送元パレットである PALETTEENTRY 構造体へのポインタ、または NULL。「注意」を参照すること。
pSrcRect
[in] RECT 構造体へのポインタ。転送元矩形を指定する。このパラメータに NULL を設定して、サーフェス全体を指定する。
Filter
[in] イメージをフィルタリングする方法を制御する 1 つ以上のフラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_TRIANGLE | D3DX_FILTER_DITHER を指定することと等しい。

有効なそれぞれのフィルタに、次のフラグの 1 つが含まれていなければならない。

D3DX_FILTER_BOX
各ピクセルは、ソース イメージ内の 2 × 2 (× 2) のサイズのボックスに含まれるピクセルの平均を算出することにより計算される。このフィルタは、ミップマップを使用する場合のように、転送先のディメンジョンがソースの半分の場合のみ機能する。
D3DX_FILTER_LINEAR
各転送先ピクセルは、最も近い 4 つのピクセルをソース イメージからサンプリングすることにより計算される。このフィルタは、両軸のスケールが 2 未満の場合に最も効率よく機能する。
D3DX_FILTER_NONE
スケーリングまたはフィルタリングを行わない。ソース イメージの境界の外側にあるピクセルは透明な黒であると見なされる。
D3DX_FILTER_POINT
各転送先ピクセルは、最も近いピクセルをソース イメージからサンプリングすることにより計算される。
D3DX_FILTER_TRIANGLE
ソース イメージ内の各ピクセルが、転送先イメージに等しく反映される。これは、最も処理に時間のかかるフィルタである。

さらに、OR 演算子を使用して、有効なフィルタと共に次に示すオプションのフラグを 0 個以上指定できる。

D3DX_FILTER_MIRROR
このフラグを指定すると、D3DX_FILTER_MIRROR_U、D3DX_FILTER_MIRROR_V、および D3DX_FILTER_MIRROR_W フラグを指定したことになる。
D3DX_FILTER_MIRROR_U
u 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_V
v 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_W
w 軸のテクスチャのエッジから離れているピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_DITHER
結果として作成されたイメージを、4x4 の順序付きディザ アルゴリズムを使ってディザリングする必要がある。
ColorKey
[in] 透明となる D3DCOLOR の値。カラーキーを無効にする場合は 0 を指定する。ソース イメージのフォーマットとは関係なく、これは常に 32 ビットの ARGB カラーである。アルファが有意であり、通常はカラーキーを不透明にする場合は FF を指定する。したがって、不透明な黒の場合、値は 0xFF000000 となる。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

注意

PALETTEENTRY の詳細については、Microsoft® Platform Software Development Kit (SDK) を参照すること。Microsoft DirectX® 8.0 の時点で、PALLETTEENTRY 構造体の peFlags メンバは、Platform SDK に説明されているようには機能しない。peFlags メンバは現在、8 ビットのパレット化されたフォーマット用のアルファ チャネルである。

非レベルゼロへの書き込みはアップデートすべきダーティーな矩形とはならない。D3DXLoadSurfaceFromSurface が呼び出され、サーフェイスが既にダーティーではなかった (これは通常の使用シナリオにはない) なら、アプリケーションは明示的にそのサーフェイスに IDirect3DTexture8::AddDirtyRect を呼び出す必要がある。

動作環境

ヘッダー : D3dx8tex.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXLoadVolumeFromMemory

メモリからボリュームをロードする。

HRESULT D3DXLoadVolumeFromMemory(
  LPDIRECT3DVOLUME8 pDestVolume,
  CONST PALETTEENTRY* pDestPalette,
  CONST D3DBOX* pDestBox,
  LPCVOID pSrcMemory,
  D3DFORMAT SrcFormat,
  UINT SrcRowPitch,
  UINT SrcSlicePitch,
  CONST PALETTEENTRY* pSrcPalette,
  CONST D3DBOX* pSrcBox,
  DWORD Filter,
  D3DCOLOR ColorKey
);

パラメータ

pDestVolume
[in] IDirect3DVolume8 インターフェイスへのポインタ。イメージを受け取る転送先のボリュームを指定する。
pDestPalette
[in] 256 色の転送先パレットである PALETTEENTRY 構造体へのポインタ、または NULL。「注意」を参照すること。
pDestBox
[in] D3DBOX 構造体へのポインタ。転送先のボックスを指定する。このパラメータに NULL を設定してボリューム全体を指定する。
pSrcMemory
[in] メモリ内にあるソース ボリュームの左上隅へのポインタ。
SrcFormat
[in] ソース ボリュームのピクセル フォーマットである、D3DFORMAT 列挙型のメンバ。
SrcRowPitch
[in] 転送元のイメージのピッチ (バイト単位)。DXT フォーマット (圧縮されたテクスチャ フォーマット) の場合、この数値はセルで構成される 1 つの行のサイズ (バイト単位) を表す。
SrcSlicePitch
[in] 転送元のイメージのピッチ (バイト単位)。DXT フォーマット (圧縮されたテクスチャ フォーマット) の場合、この数値はセルで構成される 1 つのスライスのサイズ (バイト単位) を表す。
pSrcPalette
[in] 256 色の転送元パレットである PALETTEENTRY 構造体へのポインタ、または NULL。「注意」を参照すること。
pSrcBox
[in] D3DBOX 構造体へのポインタ。転送元のボックスを指定する。NULL は無効な値である。
Filter
[in] イメージをフィルタリングする方法を制御する 1 つ以上のフラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_TRIANGLE | D3DX_FILTER_DITHER を指定することと等しい。

有効なそれぞれのフィルタに、次のフラグの 1 つが含まれていなければならない。

D3DX_FILTER_BOX
各ピクセルは、ソース イメージ内の 2 × 2 (× 2) のサイズのボックスに含まれるピクセルの平均を算出することにより計算される。このフィルタは、ミップマップを使用する場合のように、転送先のディメンジョンがソースの半分の場合のみ機能する。
D3DX_FILTER_LINEAR
各転送先ピクセルは、最も近い 4 つのピクセルをソース イメージからサンプリングすることにより計算される。このフィルタは、両軸のスケールが 2 未満の場合に最も効率よく機能する。
D3DX_FILTER_NONE
スケーリングまたはフィルタリングを行わない。ソース イメージの境界の外側にあるピクセルは透明な黒であると見なされる。
D3DX_FILTER_POINT
各転送先ピクセルは、最も近いピクセルをソース イメージからサンプリングすることにより計算される。
D3DX_FILTER_TRIANGLE
ソース イメージ内の各ピクセルが、転送先イメージに等しく反映される。これは、最も処理に時間のかかるフィルタである。

さらに、OR 演算子を使用して、有効なフィルタと共に次に示すオプションのフラグを 0 個以上指定できる。

D3DX_FILTER_MIRROR
このフラグを指定すると、D3DX_FILTER_MIRROR_U、D3DX_FILTER_MIRROR_V、および D3DX_FILTER_MIRROR_W フラグを指定したことになる。
D3DX_FILTER_MIRROR_U
u 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_V
v 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_W
w 軸のテクスチャのエッジから離れているピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_DITHER
結果として作成されたイメージを、4x4 の順序付きディザ アルゴリズムを使ってディザリングする必要がある。
ColorKey
[in] 透明となる D3DCOLOR の値。カラーキーを無効にする場合は 0 を指定する。ソース イメージのフォーマットとは関係なく、これは常に 32 ビットの ARGB カラーである。アルファが有意であり、通常はカラーキーを不透明にする場合は FF を指定する。したがって、不透明な黒の場合、値は 0xFF000000 となる。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

注意

PALETTEENTRY の詳細については、Microsoft® Platform Software Development Kit (SDK) を参照すること。Microsoft DirectX® 8.0 の時点で、PALLETTEENTRY 構造体の peFlags メンバは、Platform SDK に説明されているようには機能しない。peFlags メンバは現在、8 ビットのパレット化されたフォーマット用のアルファ チャネルである。

非レベルゼロへの書き込みはアップデートすべきダーティーな矩形とはならない。D3DXLoadVolumeFromMemory が呼び出され、サーフェイスが既にダーティーではなかった (これは通常の使用シナリオにはない) なら、アプリケーションは明示的にそのサーフェイスに IDirect3DTexture8::AddDirtyRect を呼び出す必要がある。

動作環境

ヘッダー : D3dx8tex.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


D3DXLoadVolumeFromVolume

別のボリュームからボリュームをロードする。

HRESULT D3DXLoadVolumeFromVolume(
  LPDIRECT3DVOLUME8 pDestVolume,
  CONST PALETTEENTRY* pDestPalette,
  CONST D3DBOX* pDestBox,
  LPDIRECT3DVOLUME8 pSrcVolume,
  CONST PALETTEENTRY* pSrcPalette,
  CONST D3DBOX* pSrcBox,
  DWORD Filter,
  D3DCOLOR ColorKey
);

パラメータ

pDestVolume
[in] IDirect3DVolume8 インターフェイスへのポインタ。イメージを受け取る転送先のボリュームを指定する。
pDestPalette
[in] 256 色の転送先パレットである PALETTEENTRY 構造体へのポインタ、または NULL。「注意」を参照すること。
pDestBox
[in] D3DBOX 構造体へのポインタ。転送先のボックスを指定する。このパラメータに NULL を設定してボリューム全体を指定する。
pSrcVolume
[in] IDirect3DVolume8 インターフェイスへのポインタ。ソース ボリュームを指定する。
pSrcPalette
[in] 256 色の転送元パレットである PALETTEENTRY 構造体へのポインタ、または NULL。「注意」を参照すること。
pSrcBox
[in] D3DBOX 構造体へのポインタ。転送元のボックスを指定する。このパラメータに NULL を設定してボリューム全体を指定する。
Filter
[in] イメージをフィルタリングする方法を制御する 1 つ以上のフラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_TRIANGLE | D3DX_FILTER_DITHER を指定することと等しい。

有効なそれぞれのフィルタに、次のフラグの 1 つが含まれていなければならない。

D3DX_FILTER_BOX
各ピクセルは、ソース イメージ内の 2 × 2 (× 2) のサイズのボックスに含まれるピクセルの平均を算出することにより計算される。このフィルタは、ミップマップを使用する場合のように、転送先のディメンジョンがソースの半分の場合のみ機能する。
D3DX_FILTER_LINEAR
各転送先ピクセルは、最も近い 4 つのピクセルをソース イメージからサンプリングすることにより計算される。このフィルタは、両軸のスケールが 2 未満の場合に最も効率よく機能する。
D3DX_FILTER_NONE
スケーリングまたはフィルタリングを行わない。ソース イメージの境界の外側にあるピクセルは透明な黒であると見なされる。
D3DX_FILTER_POINT
各転送先ピクセルは、最も近いピクセルをソース イメージからサンプリングすることにより計算される。
D3DX_FILTER_TRIANGLE
ソース イメージ内の各ピクセルが、転送先イメージに等しく反映される。これは、最も処理に時間のかかるフィルタである。

さらに、OR 演算子を使用して、有効なフィルタと共に次に示すオプションのフラグを 0 個以上指定できる。

D3DX_FILTER_MIRROR
このフラグを指定すると、D3DX_FILTER_MIRROR_U、D3DX_FILTER_MIRROR_V、および D3DX_FILTER_MIRROR_W フラグを指定したことになる。
D3DX_FILTER_MIRROR_U
u 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_V
v 軸のテクスチャのエッジから離れたピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_MIRROR_W
w 軸のテクスチャのエッジから離れているピクセルを、ラッピングせずにミラーリングするよう指定する。
D3DX_FILTER_DITHER
結果として作成されたイメージを、4x4 の順序付きディザ アルゴリズムを使ってディザリングする必要がある。
ColorKey
[in] 透明となる D3DCOLOR の値。カラーキーを無効にする場合は 0 を指定する。ソース イメージのフォーマットとは関係なく、これは常に 32 ビットの ARGB カラーである。アルファが有意であり、通常はカラーキーを不透明にする場合は FF を指定する。したがって、不透明な黒の場合、値は 0xFF000000 となる。

戻り値

成功した場合は D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

注意

PALETTEENTRY の詳細については、Microsoft® Platform Software Development Kit (SDK) を参照すること。Microsoft DirectX® 8.0 の時点で、PALLETTEENTRY 構造体の peFlags メンバは、Platform SDK に説明されているようには機能しない。peFlags メンバは現在、8 ビットのパレット化されたフォーマット用のアルファ チャネルである。

非レベルゼロへの書き込みはアップデートすべきダーティーな矩形とはならない。D3DXLoadVolumeFromVolume が呼び出され、サーフェイスが既にダーティーではなかった (これは通常の使用シナリオにはない) なら、アプリケーションは明示的にそのサーフェイスに IDirect3DTexture8::AddDirtyRect を呼び出す必要がある。

動作環境

ヘッダー : D3dx8tex.h で宣言。
インポート ライブラリ : D3dx8.lib を使用。


マクロ

ここでは、Direct3DX ユーティリティ ライブラリが提供するマクロのリファレンス情報を記述する。

  • D3DXToDegree
  • D3DXToRadian


D3DXToDegree

ラジアンを度に変換する。

D3DXToDegree( radian ) ((radian) * (180.0f / D3DX_PI))

パラメータ

radian
度数に変換する値 (ラジアン単位)。

戻り値

マクロは、ラジアン値を度数で返す。

注意

定数 D3DX_PI は次の定義と共に宣言される。

#define D3DX_PI    ((FLOAT)  3.141592654f)

動作環境

ヘッダー : d3dx8math.h で宣言。

参照

D3DXToRadian


D3DXToRadian

度をラジアンに変換する。

D3DXToRadian( degree ) ((degree) * (D3DX_PI / 180.0f))

パラメータ

degree
ラジアンに変換する値 (度数単位)。

戻り値

マクロは、度数値をラジアン単位で返す。

注意

定数 D3DX_PI は次の定義と共に宣言される。

#define D3DX_PI    ((FLOAT)  3.141592654f)

動作環境

ヘッダー : d3dx8math.h で宣言。

参照

D3DXToDegree


構造体

ここでは、Direct3DX ユーティリティ ライブラリに含まれる構造体に関する情報を記述する。

  • D3DXATTRIBUTERANGE
  • D3DXATTRIBUTEWEIGHTS
  • D3DXBONECOMBINATION
  • D3DXCOLOR
  • D3DXEFFECT_DESC
  • D3DXIMAGE_INFO
  • D3DXMATERIAL
  • D3DXMATRIX
  • D3DXPASS_DESC
  • D3DXPARAMETER_DESC
  • D3DXPLANE
  • D3DXQUATERNION
  • D3DXTECHNIQUE_DESC
  • D3DXVECTOR2
  • D3DXVECTOR3
  • D3DXVECTOR4
  • D3DXRTS_DESC


D3DXATTRIBUTERANGE

テーブルの属性値を格納する。

typedef struct _D3DXATTRIBUTERANGE {
    DWORD AttribId;
    DWORD FaceStart;
    DWORD FaceCount;
    DWORD VertexStart;
    DWORD VertexCount;
} D3DXATTRIBUTERANGE;

メンバ

AttribId
属性テーブルの識別子。
FaceStart
開始面。
FaceCount
面の数。
VertexStart
開始頂点。
VertexCount
頂点の数。

注意

属性テーブルは、異なるテクスチャ、レンダリング ステート、マテリアルなどによって描画する必要があるメッシュの領域を識別するために使用される。さらにアプリケーションは、属性テーブルを使用し、フレームの描画時に所定の属性識別子 (AttribId) を描画しないことによって、メッシュの一部を隠すことができる。

LPD3DXATTRIBUTERANGE は D3DXATTRIBUTERANGE 構造体へのポインタとして定義される。

typedef D3DXATTRIBUTERANGE* LPD3DXATTRIBUTERANGE;

動作環境

ヘッダー : d3dx8mesh.h で宣言。

参照

ID3DXBaseMesh::DrawSubset


D3DXATTRIBUTEWEIGHTS

頂点の成分の重み付けを指定する。

typedef struct _D3DXATTRIBUTEWEIGHTS {
    FLOAT Position;
    FLOAT Boundary;
    FLOAT Normal;
    FLOAT Diffuse;
    FLOAT Specular;
    FLOAT Tex[8];
} D3DXATTRIBUTEWEIGHTS;

メンバ

Position
位置成分の加重。
Boundary
境界成分の加重。
Normal
法線成分の加重。
Diffuse
ディフューズ成分の加重。
Specular
スペキュラ成分の加重。
Tex
テクスチャ座標の加重。

注意

この構造体は、エッジをたたむ間の相対コストを計算する場合に、単純化の操作が頂点データを扱う方法を記述する。たとえば、Normal フィールドが 0.0 の場合、単純化の操作ではエッジをたたむことに関するエラーを計算する際に頂点法線成分が無視される。ただし、Normal フィールドが 1.0 の場合は、単純化の操作で頂点法線成分が使用される。Normal フィールドが 2.0 の場合は、エラーの数が 2 倍になり、Normal フィールドが 4.0 の場合はエラーの数が 4 倍になる。以下同様に続く。

LPD3DXATTRIBUTEWEIGHTS 型は D3DXATTRIBUTEWEIGHTS 構造体へのポインタとして定義される。

typedef D3DXATTRIBUTEWEIGHTS* LPD3DXATTRIBUTEWEIGHTS;

動作環境

ヘッダー : d3dx8mesh.h で宣言。

参照

D3DXCreateSPMesh、D3DXGeneratePMesh、D3DXSimplifyMesh


D3DXBONECOMBINATION

属性とボーンの組み合わせが同じメッシュのサブセットを記述する。

typedef struct _D3DXBONECOMBINATION {
    DWORD AttribId;
    DWORD FaceStart;
    DWORD FaceCount;
    DWORD VertexStart;
    DWORD VertexCount;
    DWORD* BoneId;
} D3DXBONECOMBINATION, *LPD3DXBONECOMBINATION;

メンバ

AttribId
属性テーブルの識別子。
FaceStart
開始面。
FaceCount
面の数。
VertexStart
開始頂点。
VertexCount
頂点の数。
BoneId
1 回の描画呼び出しで描画できる各ボーンを識別する値の配列へのポインタ。この配列は、ID3DXSkinMesh::ConvertToIndexedBlendedMesh の可変長ボーン組み合わせを格納する可変長になることができることに注意すること。

注意

D3DXBONECOMBINATION で記述したメッシュのサブセットは単一の描画呼び出しでレンダリング可能である。

動作環境

ヘッダー : d3dx8mesh.h で宣言。


D3DXCOLOR

カラー値を記述する。

typedef struct D3DXCOLOR {
  FLOAT r, g, b, a;
} D3DXCOLOR;

メンバ

r
色の赤成分。
g
色の緑成分。
b
色の青成分。
a
色のアルファ成分。

注意

C++ プログラマは、演算子のオーバーロード機能や型変換機能を利用できる。D3DXCOLOR 構造体を C++ で実装すると、オーバーロードされたコンストラクタやオーバーロードされた代入演算子、単項演算子、および 2 項演算子 (等価演算子を含む) が実装される。詳細については、「C++ 固有の機能」を参照すること。

動作環境

ヘッダー : d3dx8math.h で宣言。


D3DXEFFECT_DESC

エフェクト オブジェクトを記述する。

typedef struct _D3DXEFFECT_DESC
{
    UINT  Parameters;
    UINT  Techniques;
    DWORD Usage;

} D3DXEFFECT_DESC;

メンバ

Parameters
エフェクトに使用されるパラメータの数。
Techniques
エフェクトをレンダリング可能なテクニックの数。
Usage
このエフェクトに対する使用方法の制御情報。このメンバには、次のフラグ セットを指定できる。
D3DUSAGE_SOFTWAREPROCESSING
エフェクトがソフトウェア処理を使用することを示す。

注意

エフェクト オブジェクトには、同じエフェクトの複数のレンダリング テクニックおよびパラメータを格納することが可能である。

動作環境

ヘッダー : d3dx8effect.h で宣言。

参照

ID3DXEffect::GetDesc


D3DXIMAGE_INFO

イメージ ファイルのオリジナルの内容の記述を返す。

typedef struct _D3DXIMAGE_INFO {
    UINT Width;
    UINT Height;
    UINT Depth;
    UINT MipLevels;
    D3DFORMAT Format;
} D3DXIMAGE_INFO;

メンバ

Width
オリジナル イメージの幅 (ピクセル単位)。
Height
オリジナル イメージの高さ (ピクセル単位)。
Depth
オリジナル イメージの深度 (ピクセル単位)。
MipLevels
オリジナル イメージのミップ レベルの数。
Format
オリジナル イメージのデータを最も厳密に記述する D3DFORMAT 列挙型からの値。

動作環境

ヘッダー : d3dx8mesh.h で宣言。


D3DXMATERIAL

Microsoft® DirectX® (.x) ファイルに保存されているマテリアル情報を返す。

struct D3DXMATERIAL {
    D3DMATERIAL8  MatD3D;
    LPSTR         pTextureFilename;
};

メンバ

MatD3D
マテリアルのプロパティを記述する D3DMATERIAL8 構造体。
pTextureFilename
テクスチャのファイル名を指定する文字列へのポインタ。

注意

D3DXLoadMeshFromX および D3DXLoadMeshFromXof は、メッシュ内の各マテリアルのカラーとテクスチャの名前を指定する D3DXMATERIAL 構造体の配列を返す。アプリケーションは、さらにテクスチャをロードする必要がある。

LPD3DXMATERIAL 型は D3DXMATERIAL 構造体へのポインタとして定義される。

typedef struct D3DXMATERIAL *LPD3DXMATERIAL;

動作環境

ヘッダー : d3dx8mesh.h で宣言。

参照

D3DXLoadMeshFromX、D3DXLoadMeshFromXof


D3DXMATRIX

行列を記述する。

typedef struct D3DXMATRIX : public D3DMATRIX {
public:
    D3DXMATRIX() {};
    D3DXMATRIX( CONST FLOAT * );
    D3DXMATRIX( CONST D3DMATRIX& );
    D3DXMATRIX( FLOAT _11, FLOAT _12, FLOAT _13, FLOAT _14,
                FLOAT _21, FLOAT _22, FLOAT _23, FLOAT _24,
                FLOAT _31, FLOAT _32, FLOAT _33, FLOAT _34,
                FLOAT _41, FLOAT _42, FLOAT _43, FLOAT _44 );

    // アクセス許可
    FLOAT& operator () ( UINT Row, UINT Col );
    FLOAT  operator () ( UINT Row, UINT Col ) const;

    // 演算子のキャスティング
    operator FLOAT* ();
    operator CONST FLOAT* () const;

    // 代入演算子
    D3DXMATRIX& operator *= ( CONST D3DXMATRIX& );
    D3DXMATRIX& operator += ( CONST D3DXMATRIX& );
    D3DXMATRIX& operator -= ( CONST D3DXMATRIX& );
    D3DXMATRIX& operator *= ( FLOAT );
    D3DXMATRIX& operator /= ( FLOAT );

    // 単項演算子
    D3DXMATRIX operator + () const;
    D3DXMATRIX operator - () const;

    // 2 項演算子
    D3DXMATRIX operator * ( CONST D3DXMATRIX& ) const;
    D3DXMATRIX operator + ( CONST D3DXMATRIX& ) const;
    D3DXMATRIX operator - ( CONST D3DXMATRIX& ) const;
    D3DXMATRIX operator * ( FLOAT ) const;
    D3DXMATRIX operator / ( FLOAT ) const;

    friend D3DXMATRIX operator * ( FLOAT, CONST D3DXMATRIX& );

    BOOL operator == ( CONST D3DXMATRIX& ) const;
    BOOL operator != ( CONST D3DXMATRIX& ) const;

} D3DXMATRIX, *LPD3DXMATRIX;

注意

この構造体は D3DMATRIX 構造体のメンバを継承する。C のプログラマは D3DXMATRIX 構造体を使用できない。C のプログラマは D3DMATRIX 構造体を使用する必要がある。

Direct3DX で射影行列の _34 要素には、負の値を設定できない。アプリケーションは、この要素で負の値を使用しなければならない場合、その代わりに射影行列全体を –1 によりスケーリングする。

C++ プログラマは、演算子のオーバーロード機能や型変換機能を利用できる。D3DXMATRIX 構造体を C++ で実装すると、オーバーロードされたコンストラクタやオーバーロードされた代入演算子、単項演算子、および 2 項演算子 (等価演算子を含む) が実装される。詳細については、「C++ 固有の機能」を参照すること。

動作環境

ヘッダー : d3dx8math.h で宣言。


D3DXPARAMETER_DESC

エフェクト オブジェクトに使用されるパラメータを記述する。

typedef struct _D3DXPARAMETER_DESC
{
    DWORD             Name;
    D3DXPARAMETERTYPE Type;

} D3DXPARAMETER_DESC;

メンバ

Name
パラメータの名前である FOURCC コード。
Type
このパラメータに使用される変数の型を記述する。このメンバは、次のいずれかの定数である。
D3DXPT_DWORD
パラメータは DWORD 値である。
D3DXPT_FLOAT
パラメータは浮動小数点値である。
D3DXPT_VECTOR
パラメータはベクトルである。
D3DXPT_MATRIX
パラメータは 4 × 4 行列である。
D3DXPT_TEXTURE
パラメータはテクスチャである。
D3DXPT_VERTEXSHADER
パラメータは頂点シェーダである。
D3DXPT_PIXELSHADER
パラメータはピクセル シェーダである。
D3DXPT_CONSTANT
パラメータは定数値である。
D3DXPT_FORCE_DWORD
この列挙型を強制的に 32 ビット サイズにコンパイルする。この値は使用されていない。

注意

FOURCC コードは、長さが 4 文字の文字列である。詳細については、「FOURCC コード」を参照すること。

動作環境

ヘッダー : d3dx8effect.h で宣言。

参照

ID3DXEffect::GetParameterDesc


D3DXPASS_DESC

エフェクト オブジェクトに対するパスを記述する。

typedef struct _D3DXPASS_DESC
{
    DWORD Name;

} D3DXPASS_DESC;

メンバ

Name
パスの名前に使用される FOURCC コード。

注意

FOURCC コードは、長さが 4 文字の文字列である。詳細については、「FOURCC コード」を参照すること。

動作環境

ヘッダー : d3dx8effect.h で宣言。

参照

ID3DXTechnique::GetPassDesc


D3DXPLANE

平面を記述する。

typedef struct D3DXPLANE {
  FLOAT a, b, c, d;
} D3DXPLANE;

メンバ

a、b、c、および d
a、b、c、および d はそれぞれ、一般平面方程式のクリップ面の係数である。「注意」を参照すること。

注意

D3DXPLANE 構造体のメンバは、一般平面式の形式をとる。メンバは、ax + by + cz + dw = 0 といった一般平面式に適合する。

C++ プログラマは、演算子のオーバーロード機能や型変換機能を利用できる。D3DXPLANE 構造体を C++ で実装すると、オーバーロードされたコンストラクタやオーバーロードされた単項演算子や 2 項演算子が実装される。詳細については、「C++ 固有の機能」を参照すること。

動作環境

ヘッダー : d3dx8math.h で宣言。


D3DXQUATERNION

クォータニオンを記述する。

typedef struct D3DXQUATERNION {
  FLOAT x, y, z, w;
} D3DXQUATERNION;

メンバ

x
x 要素。
y
y 要素。
z
z 要素。
w
w 要素。

注意

クオータニオンは、ベクトルを定義した [x, y, z] 値に第 4 元を追加し、任意の 4D ベクトルを生成する。次に、単位クオータニオンの各元が軸/角度の回転にどのように関係しているかを示す (ただし、q は単位クオータニオン (x, y, z, w) を表し、axis は正規化され、theta は軸を回転軸とした CCW 回転である)。

q.x = sin(theta/2) * axis.x
q.y = sin(theta/2) * axis.y
q.z = sin(theta/2) * axis.z
q.w = cos(theta/2)

C++ プログラマは、演算子のオーバーロード機能や型変換機能を利用できる。D3DXQUATERNION 構造体を C++ で実装すると、オーバーロードされたコンストラクタやオーバーロードされた代入演算子、単項演算子、および 2 項演算子 (等価演算子を含む) が実装される。詳細については、「C++ 固有の機能」を参照すること。

動作環境

ヘッダー : d3dx8math.h で宣言。


D3DXTECHNIQUE_DESC

テクニック オブジェクトを記述する。

typedef struct _D3DXTECHNIQUE_DESC
{
    DWORD Name;
    UINT  Passes;
} D3DXTECHNIQUE_DESC;

メンバ

Name
このテクニック オブジェクトの名前に使用される FOURCC コード。
Passes
テクニックが要求するレンダリング パスの数。「注意」を参照すること。

注意

ビデオ カードの中には、単一のパスで 2 つのテクスチャをレンダリングできるものもある。ただし、カードがこの能力を備えていない場合は、たいてい 2 つのパスで同じエフェクトをレンダリングできる。このとき、各パスに対して 1 つのテクスチャを使用する。

FOURCC コードは、長さが 4 文字の文字列である。詳細については、「FOURCC コード」を参照すること。

動作環境

ヘッダー : d3dx8effect.h で宣言。

参照

ID3DXTechnique::GetDesc


D3DXVECTOR2

D3DXVECTOR2 構造体は、2 次元 (2D) 空間のベクトルを記述する。

typedef struct D3DXVECTOR2 {
  FLOAT x, y;
} D3DXVECTOR2;

メンバ

x
x 要素。
y
y 要素。

注意

C++ プログラマは、演算子のオーバーロード機能や型変換機能を利用できる。D3DXVECTOR2 構造体を C++ で実装すると、オーバーロードされたコンストラクタやオーバーロードされた代入演算子、単項演算子、および 2 項演算子 (等価演算子を含む) が実装される。詳細については、「C++ 固有の機能」を参照すること。

動作環境

ヘッダー : d3dx8math.h で宣言。


D3DXVECTOR3

D3DXVECTOR3 構造体は、3 次元 (3D) 空間のベクトルを記述する。

typedef struct D3DXVECTOR3 : public D3DVECTOR {
public:
    D3DXVECTOR3() {};
    D3DXVECTOR3( CONST FLOAT * );
    D3DXVECTOR3( CONST D3DVECTOR& );
    D3DXVECTOR3( FLOAT x, FLOAT y, FLOAT z );

    // キャスティング
    operator FLOAT* ();
    operator CONST FLOAT* () const;

    // 代入演算子
    D3DXVECTOR3& operator += ( CONST D3DXVECTOR3& );
    D3DXVECTOR3& operator -= ( CONST D3DXVECTOR3& );
    D3DXVECTOR3& operator *= ( FLOAT );
    D3DXVECTOR3& operator /= ( FLOAT );

    // 単項演算子
    D3DXVECTOR3 operator + () const;
    D3DXVECTOR3 operator - () const;

    // 2 項演算子
    D3DXVECTOR3 operator + ( CONST D3DXVECTOR3& ) const;
    D3DXVECTOR3 operator - ( CONST D3DXVECTOR3& ) const;
    D3DXVECTOR3 operator * ( FLOAT ) const;
    D3DXVECTOR3 operator / ( FLOAT ) const;

    friend D3DXVECTOR3 operator * ( FLOAT, CONST struct D3DXVECTOR3& );

    BOOL operator == ( CONST D3DXVECTOR3& ) const;
    BOOL operator != ( CONST D3DXVECTOR3& ) const;

} D3DXVECTOR3, *LPD3DXVECTOR3;

メンバ

x
x 要素。
y
y 要素。
z
z 要素。

注意

この構造体は、D3DVECTOR 構造体のメンバ x、y、z を継承する。C のプログラマは D3DXVECTOR3 構造体を使用できない。C のプログラマは D3DVECTOR 構造体を使用する必要がある。

C++ プログラマは、演算子のオーバーロード機能や型変換機能を利用できる。D3DXVECTOR3 構造体を C++ で実装すると、オーバーロードされたコンストラクタやオーバーロードされた代入演算子、単項演算子、および 2 項演算子 (等価演算子を含む) が実装される。詳細については、「C++ 固有の機能」を参照すること。

動作環境

ヘッダー : d3dx8math.h で宣言。


D3DXVECTOR4

D3DXVECTOR4 構造体は、4 次元 (4D) 空間のベクトルを記述する。

typedef struct D3DXVECTOR4 {
  FLOAT x, y, z, w;
} D3DXVECTOR4;

メンバ

x
x 要素。
y
y 要素。
z
z 要素。
w
w 要素。

注意

C++ プログラマは、演算子のオーバーロード機能や型変換機能を利用できる。D3DXVECTOR4 構造体を C++ で実装すると、オーバーロードされたコンストラクタやオーバーロードされた代入演算子、単項演算子、および 2 項演算子 (等価演算子を含む) が実装される。詳細については、「C++ 固有の機能」を参照すること。

動作環境

ヘッダー : d3dx8math.h で宣言。


D3DXRTS_DESC

レンダリング サーフェスを記述する。

typedef struct _D3DXRTS_DESC {
    UINT                Width;
    UINT                Height;
    D3DFORMAT           Format;
    BOOL                DepthStencil;
    D3DFORMAT           DepthStencilFormat;

} D3DXRTS_DESC;

メンバ

Width
レンダリング サーフェスの幅 (ピクセル単位)。
Height
レンダリング サーフェスの高さ (ピクセル単位)。
Format
レンダリング サーフェスのピクセル フォーマットを記述する、D3DFORMAT 列挙型のメンバ。
DepthStencil
TRUE の場合、レンダリング サーフェスは深度ステンシル サーフェスをサポートする。それ以外の場合、このメンバは FALSE に設定される。
DepthStencilFormat
DepthStencil が TRUE の場合、このパラメータはレンダリング サーフェスの深度ステンシル フォーマットを記述する D3DFORMAT 列挙型のメンバである。

動作環境

ヘッダー : D3dx8core.h で宣言。

参照

ID3DXRenderToSurface::GetDesc


C++ 固有の機能

C++ プログラマは、Direct3DX ユーティリティ ライブラリにより提供されているコンストラクタのオーバーロード機能、演算子のオーバーロード機能、型変換の拡張機能を利用できる。次の構造体には、拡張機能が実装されている。

  • D3DXCOLOR 拡張機能
  • D3DXMATRIX 拡張機能
  • D3DXPLANE 拡張機能
  • D3DXQUATERNION 拡張機能
  • D3DXVECTOR2 拡張機能
  • D3DXVECTOR3 拡張機能
  • D3DXVECTOR4 拡張機能


D3DXCOLOR 拡張機能

D3DXCOLOR 構造体で、次の演算子オーバーロードとタイプ キャストを使用可能にする。

#ifdef __cplusplus
public:
    D3DXCOLOR() {}
    D3DXCOLOR( DWORD argb );
    D3DXCOLOR( CONST FLOAT * );
    D3DXCOLOR( CONST D3DCOLORVALUE& );
    D3DXCOLOR( FLOAT r, FLOAT g, FLOAT b, FLOAT a );

    // キャスティング
    operator DWORD () const;

    operator FLOAT* ();
    operator CONST FLOAT* () const;

    operator D3DCOLORVALUE* ();
    operator CONST D3DCOLORVALUE* () const;

    operator D3DCOLORVALUE& ();
    operator CONST D3DCOLORVALUE& () const;

    // 代入演算子
    D3DXCOLOR& operator += ( CONST D3DXCOLOR& );
    D3DXCOLOR& operator -= ( CONST D3DXCOLOR& );
    D3DXCOLOR& operator *= ( FLOAT );
    D3DXCOLOR& operator /= ( FLOAT );

    // 単項演算子
    D3DXCOLOR operator + () const;
    D3DXCOLOR operator - () const;

    // 2 項演算子
    D3DXCOLOR operator + ( CONST D3DXCOLOR& ) const;
    D3DXCOLOR operator - ( CONST D3DXCOLOR& ) const;
    D3DXCOLOR operator * ( FLOAT ) const;
    D3DXCOLOR operator / ( FLOAT ) const;

    friend D3DXCOLOR operator * (FLOAT, CONST D3DXCOLOR& );

    BOOL operator == ( CONST D3DXCOLOR& ) const;
    BOOL operator != ( CONST D3DXCOLOR& ) const;

#endif //__cplusplus

動作環境

ヘッダー : D3dx8math.h で宣言。


D3DXMATRIX 拡張機能

D3DXMATRIX 構造体で、次の演算子オーバーロードとタイプ キャストを使用可能にする。

#ifdef __cplusplus
typedef struct D3DXMATRIX : public D3DMATRIX
{
public:
    D3DXMATRIX() {};
    D3DXMATRIX( CONST FLOAT * );
    D3DXMATRIX( CONST D3DMATRIX& );
    D3DXMATRIX( FLOAT _11, FLOAT _12, FLOAT _13, FLOAT _14,
                FLOAT _21, FLOAT _22, FLOAT _23, FLOAT _24,
                FLOAT _31, FLOAT _32, FLOAT _33, FLOAT _34,
                FLOAT _41, FLOAT _42, FLOAT _43, FLOAT _44 );

    // アクセス許可
    FLOAT& operator () ( UINT Row, UINT Col );
    FLOAT  operator () ( UINT Row, UINT Col ) const;

    // 演算子のキャスティング
    operator FLOAT* ();
    operator CONST FLOAT* () const;

    // 代入演算子
    D3DXMATRIX& operator *= ( CONST D3DXMATRIX& );
    D3DXMATRIX& operator += ( CONST D3DXMATRIX& );
    D3DXMATRIX& operator -= ( CONST D3DXMATRIX& );
    D3DXMATRIX& operator *= ( FLOAT );
    D3DXMATRIX& operator /= ( FLOAT );

    // 単項演算子
    D3DXMATRIX operator + () const;
    D3DXMATRIX operator - () const;

    // 2 項演算子
    D3DXMATRIX operator * ( CONST D3DXMATRIX& ) const;
    D3DXMATRIX operator + ( CONST D3DXMATRIX& ) const;
    D3DXMATRIX operator - ( CONST D3DXMATRIX& ) const;
    D3DXMATRIX operator * ( FLOAT ) const;
    D3DXMATRIX operator / ( FLOAT ) const;

    friend D3DXMATRIX operator * ( FLOAT, CONST D3DXMATRIX& );

    BOOL operator == ( CONST D3DXMATRIX& ) const;
    BOOL operator != ( CONST D3DXMATRIX& ) const;

} D3DXMATRIX, *LPD3DXMATRIX;

#else //!__cplusplus

動作環境

ヘッダー : D3dx8math.h で宣言。


D3DXPLANE 拡張機能

D3DXPLANE 構造体で、次の演算子オーバーロードとタイプ キャストを使用可能にする。

#ifdef __cplusplus
public:
    D3DXPLANE() {}
    D3DXPLANE( CONST FLOAT* );
    D3DXPLANE( FLOAT a, FLOAT b, FLOAT c, FLOAT d );

    // キャスティング
    operator FLOAT* ();
    operator CONST FLOAT* () const;

    // 単項演算子
    D3DXPLANE operator + () const;
    D3DXPLANE operator - () const;

    // 2 項演算子
    BOOL operator == ( CONST D3DXPLANE& ) const;
    BOOL operator != ( CONST D3DXPLANE& ) const;

#endif //__cplusplus

動作環境

ヘッダー : D3dx8math.h で宣言。


D3DXQUATERNION 拡張機能

D3DXQUATERNION 構造体で、次の演算子オーバーロードとタイプ キャストを使用可能にする。

#ifdef __cplusplus
public:
    D3DXQUATERNION() {}
    D3DXQUATERNION( CONST FLOAT * );
    D3DXQUATERNION( FLOAT x, FLOAT y, FLOAT z, FLOAT w );

    // キャスティング
    operator FLOAT* ();
    operator CONST FLOAT* () const;

    // 代入演算子
    D3DXQUATERNION& operator += ( CONST D3DXQUATERNION& );
    D3DXQUATERNION& operator -= ( CONST D3DXQUATERNION& );
    D3DXQUATERNION& operator *= ( CONST D3DXQUATERNION& );
    D3DXQUATERNION& operator *= ( FLOAT );
    D3DXQUATERNION& operator /= ( FLOAT );

    // 単項演算子
    D3DXQUATERNION  operator + () const;
    D3DXQUATERNION  operator - () const;

    // 2 項演算子
    D3DXQUATERNION operator + ( CONST D3DXQUATERNION& ) const;
    D3DXQUATERNION operator - ( CONST D3DXQUATERNION& ) const;
    D3DXQUATERNION operator * ( CONST D3DXQUATERNION& ) const;
    D3DXQUATERNION operator * ( FLOAT ) const;
    D3DXQUATERNION operator / ( FLOAT ) const;

    friend D3DXQUATERNION operator * (FLOAT, CONST D3DXQUATERNION& );

    BOOL operator == ( CONST D3DXQUATERNION& ) const;
    BOOL operator != ( CONST D3DXQUATERNION& ) const;

#endif //__cplusplus

動作環境

ヘッダー : D3dx8math.h で宣言。


D3DXVECTOR2 拡張機能

D3DXVECTOR2 構造体で、次の演算子オーバーロードとタイプ キャストを使用可能にする。

#ifdef __cplusplus
public:
    D3DXVECTOR2() {};
    D3DXVECTOR2( CONST FLOAT * );
    D3DXVECTOR2( FLOAT x, FLOAT y );

    // キャスティング
    operator FLOAT* ();
    operator CONST FLOAT* () const;

    // 代入演算子
    D3DXVECTOR2& operator += ( CONST D3DXVECTOR2& );
    D3DXVECTOR2& operator -= ( CONST D3DXVECTOR2& );
    D3DXVECTOR2& operator *= ( FLOAT );
    D3DXVECTOR2& operator /= ( FLOAT );

    // 単項演算子
    D3DXVECTOR2 operator + () const;
    D3DXVECTOR2 operator - () const;

    // 2 項演算子
    D3DXVECTOR2 operator + ( CONST D3DXVECTOR2& ) const;
    D3DXVECTOR2 operator - ( CONST D3DXVECTOR2& ) const;
    D3DXVECTOR2 operator * ( FLOAT ) const;
    D3DXVECTOR2 operator / ( FLOAT ) const;

    friend D3DXVECTOR2 operator * ( FLOAT, CONST D3DXVECTOR2& );

    BOOL operator == ( CONST D3DXVECTOR2& ) const;
    BOOL operator != ( CONST D3DXVECTOR2& ) const;

public:
#endif //__cplusplus

動作環境

ヘッダー : D3dx8math.h で宣言。


D3DXVECTOR3 拡張機能

D3DXVECTOR3 構造体で、次の演算子オーバーロードとタイプ キャストを使用可能にする。

#ifdef __cplusplus
typedef struct D3DXVECTOR3 : public D3DVECTOR
{
public:
    D3DXVECTOR3() {};
    D3DXVECTOR3( CONST FLOAT * );
    D3DXVECTOR3( CONST D3DVECTOR& );
    D3DXVECTOR3( FLOAT x, FLOAT y, FLOAT z );

    // キャスティング
    operator FLOAT* ();
    operator CONST FLOAT* () const;

    // 代入演算子
    D3DXVECTOR3& operator += ( CONST D3DXVECTOR3& );
    D3DXVECTOR3& operator -= ( CONST D3DXVECTOR3& );
    D3DXVECTOR3& operator *= ( FLOAT );
    D3DXVECTOR3& operator /= ( FLOAT );

    // 単項演算子
    D3DXVECTOR3 operator + () const;
    D3DXVECTOR3 operator - () const;

    // 2 項演算子
    D3DXVECTOR3 operator + ( CONST D3DXVECTOR3& ) const;
    D3DXVECTOR3 operator - ( CONST D3DXVECTOR3& ) const;
    D3DXVECTOR3 operator * ( FLOAT ) const;
    D3DXVECTOR3 operator / ( FLOAT ) const;

    friend D3DXVECTOR3 operator * ( FLOAT, CONST struct D3DXVECTOR3& );

    BOOL operator == ( CONST D3DXVECTOR3& ) const;
    BOOL operator != ( CONST D3DXVECTOR3& ) const;

} D3DXVECTOR3, *LPD3DXVECTOR3;

#else //!__cplusplus

動作環境

ヘッダー : D3dx8math.h で宣言。


D3DXVECTOR4 拡張機能

D3DXVECTOR4 構造体で、次の演算子オーバーロードとタイプ キャストを使用可能にする。

#ifdef __cplusplus
public:
    D3DXVECTOR4() {};
    D3DXVECTOR4( CONST FLOAT* );
    D3DXVECTOR4( FLOAT x, FLOAT y, FLOAT z, FLOAT w );

    // キャスティング
    operator FLOAT* ();
    operator CONST FLOAT* () const;

    // 代入演算子
    D3DXVECTOR4& operator += ( CONST D3DXVECTOR4& );
    D3DXVECTOR4& operator -= ( CONST D3DXVECTOR4& );
    D3DXVECTOR4& operator *= ( FLOAT );
    D3DXVECTOR4& operator /= ( FLOAT );

    // 単項演算子
    D3DXVECTOR4 operator + () const;
    D3DXVECTOR4 operator - () const;

    // 2 項演算子
    D3DXVECTOR4 operator + ( CONST D3DXVECTOR4& ) const;
    D3DXVECTOR4 operator - ( CONST D3DXVECTOR4& ) const;
    D3DXVECTOR4 operator * ( FLOAT ) const;
    D3DXVECTOR4 operator / ( FLOAT ) const;

    friend D3DXVECTOR4 operator * ( FLOAT, CONST D3DXVECTOR4& );

    BOOL operator == ( CONST D3DXVECTOR4& ) const;
    BOOL operator != ( CONST D3DXVECTOR4& ) const;

public:
#endif //__cplusplus

動作環境

ヘッダー : D3dx8math.h で宣言。


戻り値

エラーは負の値で表され、組み合わされることはない。以下は、Direct3DX ユーティリティ ライブラリに含まれるメソッドが返す可能性のある値を示している。メソッドから返される値については、それぞれの説明を参照すること。これらのリストは必ずしも包括的なものとは限らない。

D3DXERR_CANNOTATTRSORT
最適化テクニックとして属性のソート (D3DXMESHOPT_ATTRSORT) はサポートされていない。
D3DXERR_CANNOTMODIFYINDEXBUFFER
インデックス バッファを変更できない。
D3DXERR_INVALIDMESH
メッシュが無効である。
D3DXERR_SKINNINGNOTSUPPORTED
スキニングはサポートされていない。
D3DXERR_TOOMANYINFLUENCES
指定された影響が多すぎる。
D3DXERR_INVALIDDATA
データが無効である。


Direct3DX シェーダ アセンブラ リファレンス

ここでは、Direct3DX ユーティリティ ライブラリが提供する頂点シェーダ アセンブラおよびピクセル シェーダ アセンブラのリファレンス情報を記述する。

  • 頂点シェーダ アセンブラ リファレンス
  • ピクセル シェーダ アセンブラ リファレンス

このマニュアルで使用されている構文の例はすべて、Direct3DX 頂点シェーダ アセンブラおよびピクセル シェーダ アセンブラを使用する場合のシェーダの記述方法を示すためのものである。


頂点シェーダ アセンブラ リファレンス

ここでは、頂点シェーダ アセンブラについてのリファレンス情報を記述する。リファレンス情報は次のカテゴリに分類されている。

  • レジスタ
  • 命令
  • 修飾子

頂点シェーダ アセンブラは、一連のレジスタおよびそのレジスタ上で実行できる処理群で構成されている。処理は、演算子と 1 つ以上の引数 (オペランド) で構成される命令として表現されている。


レジスタ

ここでは、Direct3DX 頂点シェーダ アセンブラが実装する入力および出力レジスタについてのリファレンス情報を記述する。説明するトピックは、次のとおりである。

  • 入力レジスタ
  • 出力レジスタ

すべてのレジスタは 4 成分浮動小数点ベクトルである。このマニュアルでは、ベクトルの要素は、x、y、z および w として指定するが、セマンティクスは指定されていない。


入力レジスタ

次の表は、Microsoft® DirectX® 8.0 の頂点シェーダが利用できる最低限の入力レジスタの一覧である。この表は、バージョン 1.0 のピクセル シェーダに適用される。

名前 | 数 | I/O 許可 | 命令あたりの使用可能数
an | 1 スカラー | 書き込み/使用専用 | バージョン 1.0 では 0。バージョン 1.1 では 1。
c[n] | 96 ベクトル | 読み取り専用 | 1
rn | 12 ベクトル | 読み書き可能 | 3
vn | 16 ベクトル | 読み取り専用 | 1


an

これらはアドレス レジスタである。これらのレジスタは、Microsoft® DirectX® 8.0 の頂点シェーダ バージョン 1.0 では使用できず、バージョン 1.1 では単一のレジスタのみ使用できる。a0.x と表されるアドレス レジスタは、定数レジスタ ファイルに対する相対アドレス指定における符号付き整数オフセットとして使用できる。

c[a0.x + n]

有効範囲外からの読み取りに対しては、(0.0, 0.0, 0.0, 0.0) が返る。アドレス レジスタは、mov 命令に対してのみデスティネーションになることができる。頂点シェーダは、アドレス レジスタの値を読み取ることはできず、定数レジスタ ファイルの相対アドレス指定で使用することだけができる。サポートされている定数レジスタの範囲の外側のアドレスが指定されている場合、それによる読み取りからは予測不可能な結果が返る。

アドレス レジスタを使用するバージョン 1.0 の頂点シェーダでは、頂点シェーダを作成する Microsoft Direct3D® API の呼び出しが失敗する。バージョン 1.1 の頂点シェーダも、アドレス レジスタを設定せずに使用を試みると失敗する。


c[n]

これらは定数レジスタである。定数レジスタ ファイルを構成するのは、最低 96 個の 4 成分浮動小数点値ベクトルである。定数レジスタは、絶対位置または相対位置で指定できる。

    c[n]            ; 絶対位置
    c[a0.x + n]     ; 相対位置

したがって、定数レジスタは、絶対アドレスを使って読み取ることも、アドレス レジスタを介して相対的にアドレス指定することもできる。レジスタの範囲外から読み取りを行うと、(0.0, 0.0, 0.0, 0.0) が返る。

頂点シェーダから見ると、定数レジスタ ファイルは読み取り専用である。1 回の命令でアクセスできる定数レジスタは 1 つだけである。ただし、その命令に含まれる各ソースは読み取ったベクトルを個別に入れ換えたり正負を反転したりできる。

D3DCAPS8 の MaxVertexShaderConst メンバは、使用可能な定数レジスタの個数を示す。Microsoft® DirectX® 8.0 のシェーダは、少なくとも 96 個の定数をサポートする。

定数レジスタ ファイルのデータは、頂点シェーダの定数レジスタを設定する Microsoft Direct3D® API 関数を呼び出すとロードされる。代わりに、シェーダを作成するときに、IDirect3DDevice8::SetVertexShader の呼び出しによって、C++ アプリケーションでロードする定数を指定できる。


rn

これらはテンポラリ レジスタである。テンポラリ レジスタは、12 個の4D 浮動小数点値ベクトルにグループ化されている。各テンポラリ レジスタに対しては、1 回の書き込みアクセスと 3 回の読み取りアクセスを同時に行うことができる。したがって、1 つの命令は、入力ソース オペランドのセットとしてテンポラリ レジスタを 3 つまで使うことができる。

頂点シェーダによる前回の呼び出し後に残っているテンポラリ レジスタの中の値を使うことはできない。書き込みが行われる前のテンポラリ レジスタから頂点シェーダが読み込みを行うと、その頂点シェーダを作成する Microsoft® Direct3D® API の呼び出しは失敗する。


vn

これらは頂点入力レジスタである。1 つ以上の入力頂点ストリームからの各頂点は、頂点シェーダが実行される前に、頂点入力レジスタにロードされる。頂点入力レジスタは、16 個の 4 成分浮動小数点値ベクトルで構成されているレジスタ ファイルで、v0 から v15 と示される。これらのレジスタは読み取り専用である。

1 回の命令でアクセスできる頂点入力レジスタは 1 つだけである。ただし、その命令に含まれる各ソースは読み取ったベクトルを個別に入れ換えたり、正負を反転させたりできる。

頂点シェーダを作成するために Microsoft® Direct3D® API 呼び出しに渡される宣言では、ソース頂点ストリームと頂点入力レジスタの間のマッピングが定義されている。固定機能パイプラインの場合、入力レジスタは次の表に示されている固定マッピングを持つ。

ベクトル コンポーネント | レジスタ
位置座標 | 0
ブレンドの重み | 1
ブレンド識別子 | 2
法線 | 3
ポイント サイズ | 4
ディフューズ | 5
スペキュラ | 6
テクスチャ座標 | 7
テクスチャ座標 1 | 8
テクスチャ座標 2 | 9
テクスチャ座標 3 | 10
テクスチャ座標 4 | 11
テクスチャ座標 5 | 12
テクスチャ座標 6 | 13
テクスチャ座標 7 | 14
位置座標 2 | 15
法線 2 | 16


出力レジスタ

出力レジスタは、ラスタライザへの入力と定義される。生成されたデータは出力レジスタ ファイルに書き込まれるが、これは書き込み専用のアクセスである。

出力レジスタはラスタ シェーダのレジスタ モデルによって定義されており、次の最低個数をサポートしなければならない。

名前 | I/O 許可 | 数
oDn | 書き込み専用 | 2 つの 4D ベクトル
oFog | 書き込み専用 | 1 スカラー フロート
oPos | 書き込み専用 | 4D ベクトル 1 個
oPts | 書き込み専用 | 1 スカラー フロート
oTn | 書き込み専用 | 4 つの 4D ベクトル

示されていないデスティネーション レジスタへの書き込み処理は無視される。

レジスタ名の前に付いている小文字の o は、出力レジスタが書き込み専用であることを示している。

Microsoft® DirectX® 6.0 または 7.0 のピクセル処理モデルのみをサポートしている実装環境、つまりピクセル シェーダのない実装環境で頂点シェーダを使うときは、次の出力レジスタを利用できる。

名前 | I/0 許可 | 数 | 説明
oDn | 書き込み専用 | 2 ベクトル | 出力カラー データ。ディフューズ色およびスペキュラ色のために必要。
oPos | 書き込み専用 | 1 ベクトル | 出力座標。クリッピングのために必要。
oTn | 書き込み専用 | 2 ベクトル | 出力テクスチャ座標。テクスチャ ブレンディング ステージに同時にバインドできるテクスチャの最大数のために必要。


oDn

出力データ レジスタ。頂点カラー データを出力するために使用される。具体的には、補間されてピクセル シェーダに直接転送される出力データ レジスタの配列である。通常、これらのレジスタは色の処理に使用される。


oFog

出力フォグ値レジスタ。この値は、補間された後フォグ テーブルに転送されるフォグ係数である。フォグのスカラー x 要素だけが使われる。


oPos

出力位置レジスタ。この値は、同次クリッピング空間内の位置座標である。この値は、頂点シェーダが書き込まなければならない。


oPts

出力位置座標サイズ レジスタ。ポイント サイズのスカラー x 要素だけが使われる。


oTn

出力テクスチャ座標レジスタ。具体的には、補間されて、ピクセル シェーダに送られるサンプリング ステージの転送データによってテクスチャ座標として使用される出力データ レジスタの配列である。


命令

ここでは、Direct3DX 頂点シェーダ アセンブラが実装する命令についてのリファレンス情報を記述する。説明するトピックは、次のとおりである。

  • 一般命令
  • バージョンおよび定数定義命令
  • マクロ命令
  • 修飾子

頂点シェーダ プログラムは 128 個までの命令で構成することができ、命令は最大で 3 つの入力引数 (ソース レジスタ オペランド) を持つことができる。


一般命令

Direct3DX 頂点シェーダ アセンブラでは、次の一般的な命令がサポートされている。

add | 加算
dp3 | 3 要素の内積
dp4 | 4 要素の内積
dst | 距離ベクトル
expp | 指数 10 ビット精度
lit | ライティング係数
logp | 対数 10 ビット精度
mad | 乗算と加算
max | 最大
min | 最小
mov | 移動
mul | 乗算
rcp | 逆数
rsq | 逆数平方根
sge | 以上
slt | 未満
sub | 減算

各ソース オペランドは、ある要素を全要素にコピーしたり複製など、読み取り時に自由に入れ換えできる。各ソース オペランドは正負を反転できる。

デスティネーション レジスタへの書き込みには、個々の要素のマスキングを含めることができる。つまり、特定の成分 (x、y、z、または w) だけが更新される。書き込み時の入れ換えや正負の反転はサポートされていない。したがって、出力マスクは、x、y、z、そして w の順序でなければならない。

ソフトウェア エミュレーション フロントエンドは、出力レジスタ書き込みでのマスクを使って、出力頂点の中でシェーダが変更した部分を検出し、それに従って、ラスタ化のみの使用のためにハードウェアに送信するための、出力の柔軟な頂点フォーマット (FVF) を計算する。

ピクセル シェーダ言語とは異なり、頂点シェーダ言語では線形補間ブレンディング命令はサポートされておらず、dp3 演算子は自動的に負の結果を 0.0 に制限しないことに注意すること。

参照

マクロ命令


add

ソースを加算する。

add   vDest, vSrc0, vSrc1

レジスタ

vDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。
vSrc1
入力引数を指定するソース レジスタ。

処理

次のコードは、add 命令によって実行される処理とデスティネーションへの結果の書き込みを示している。

    SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1);

    m_TmpReg.x = m_Source[0].x + m_Source[1].x;
    m_TmpReg.y = m_Source[0].y + m_Source[1].y;
    m_TmpReg.z = m_Source[0].z + m_Source[1].z;
    m_TmpReg.w = m_Source[0].w + m_Source[1].w;

    WriteResult();

注意

次の例は、add 命令の使い方を示している。

add r0, v0,c2
add r1.xyz, r0.xyz, v1.xyz


dp3

ソースの 3 要素による内積を計算する。

dp3   vDest, vSrc0, vSrc1

レジスタ

vDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。
vSrc1
入力引数を指定するソース レジスタ。

処理

次のコードは、dp3 命令によって実行される処理とデスティネーションへの結果の書き込みを示している。

    SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1);

    m_TmpReg.x =
    m_TmpReg.y =
    m_TmpReg.z =
    m_TmpReg.w = m_Source[0].x * m_Source[1].x +
                 m_Source[0].y * m_Source[1].y +
                 m_Source[0].z * m_Source[1].z;

    WriteResult();

注意

次の例は、dp3 命令の使い方を示している。

dp3 r2, r0, r1
dp3 r2.x, r0, r1


dp4

ソースの 4 要素による内積を計算する。

dp4   vDest, vSrc0, vSrc1

レジスタ

vDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。
vSrc1
入力引数を指定するソース レジスタ。

処理

次のコードは、dp4 命令によって実行される処理とデスティネーションへの結果の書き込みを示している。

    SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1);

    m_TmpReg.x =
    m_TmpReg.y =
    m_TmpReg.z =
    m_TmpReg.w = m_Source[0].x * m_Source[1].x +
                 m_Source[0].y * m_Source[1].y +
                 m_Source[0].z * m_Source[1].z +
                 m_Source[0].w * m_Source[1].w;

    WriteResult();

注意

次の例は、dp4 命令の使い方を示している。

dp4 r2, r0, r1
dp4 r2.w, r0, r1


dst

距離関連のデータを計算する。

dst   vDest, vSrc0, vSrc1

レジスタ

vDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。
vSrc1
入力引数を指定するソース レジスタ。

処理

次のコードは、dst 命令によって実行される処理とデスティネーションへの結果の書き込みを示している。

    SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1);

    m_TmpReg.x = 1;
    m_TmpReg.y = m_Source[0].y * m_Source[1].y;
    m_TmpReg.z = m_Source[0].z;
    m_TmpReg.w = m_Source[1].w;

    WriteResult();

注意

第 1 のソース オペランドはベクトル (無視, d*d, d*d, 無視) と見なされて、第 2 のソース オペランドはベクトル (無視, 1/d, 無視, 1/d) と見なされる。デスティネーションは、結果のベクトル (1, d, d*d, 1/d) である。

次の例は、dst 命令の使い方を示している。

dst r4, r0, r1


expp

指数 2x の部分サポートを提供する。

expp   vDest, vSrc0

レジスタ

vDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。

処理

次のコードは、expp 命令によって実行される処理とデスティネーションへの結果の書き込みを示している。

    SetDestReg();
    SetSrcReg(0);

    float w = m_Source[0].w;
    float v = (float)floor(m_Source[0].w);

    m_TmpReg.x = (float)pow(2, v);
    m_TmpReg.y = w - v;
    // 低精度指数
    float tmp = (float)pow(2, w);
    DWORD tmpd = *(DWORD*)&tmp & 0xffffff00;
    m_TmpReg.z = *(float*)&tmpd;
    m_TmpReg.w = 1;

    WriteResult();

注意

指数に負の数を指定した場合、expp 命令は不定の結果を生成する。

この命令は、2 を底とする指数の部分精度を計算する。vDest.z には近似解が生成されて、より正確な値は vDest.x*function(vDest.y) で求めることができる。function は、限られた範囲 (0.0 <= vDest.y < 1.0) の 2*vDest.y に対してユーザーが使用する近似である。

この命令ではスカラー ソースを使用し、vDest.z の評価には低精度計算が使用できる。ただし、近似エラーは、絶対エラー (10 ビット精度) の 1/(211) より小さく、0.0 <= t.y < 1.0 の範囲内になければならない。また、expp から返る w は 1.0 である。

次の例は、expp 命令の使い方を示している。

expp r5, r0


lit

ライティングの部分サポートを提供する。

lit   vDest, vSrc0

レジスタ

vDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。

処理

次のコードは、lit 命令によって実行される処理とデスティネーションへの結果の書き込みを示している。

    SetDestReg();
    SetSrcReg(0);

    m_TmpReg.x = 1;
    m_TmpReg.y = 0;
    m_TmpReg.z = 0;
    m_TmpReg.w = 1;
    float power = m_Source[0].w;
    const float MAXPOWER = 127.9961f;
    if (power < -MAXPOWER)
        power = -MAXPOWER;          // 8.8 固定小数点フォーマットに適合。
    else
    if (power > MAXPOWER)
        power = -MAXPOWER;          // 8.8 固定小数点フォーマットに適合。

    if (m_Source[0].x > 0)
    {
        m_TmpReg.y = m_Source[0].x;
        if (m_Source[0].y > 0)
        {
            // 許容される近似は EXP(power * LOG(m_Source[0].y)) である。
            m_TmpReg.z = (float)(pow(m_Source[0].y, power));
        }
    }

    WriteResult();

注意

指数に負の数を指定した場合、lit 命令は不定の結果を生成する。

この命令は、2 つの内積と 1 つの累乗からライティング係数を計算する。ソースのベクトルには、次の疑似コードに示すような値が含まれているものと想定される。

vSrc0.x = N*L        ; 法線とライト ベクトルとの内積
vSrc0.y = N*H        ; 法線と半ベクトルとの内積
vSrc0.z = ignored    ; この値は無視される
vSrc0.w = power      ; 累乗、この値は -128.0 から 128.0 の範囲でなければならない

vDest.z の評価には低精度計算が使用できる。実装では、累乗引数で少なくとも 8 つの小数ビットをサポートする必要がある。内積は正規化されたベクトルで計算されて、クランプの制限は -128 から 128 である。

エラーは logp と expp の組み合わせに対応していなければならず、つまり 8 ビットの色成分に対して最下位ビット (LSB) 約 1 つである。

次の例は、lit 命令の使い方を示している。

lit r0, r1


logp

log2(x) の部分サポートを提供する。

logp   vDest, vSrc0

レジスタ

vDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。

処理

次のコードは、logp 命令によって実行される処理とデスティネーションへの結果の書き込みを示している。

    SetDestReg();
    SetSrcReg(0);

    float v = ABSF(m_Source[0].w);
    if (v != 0)
    {
        m_TmpReg.x = m_TmpReg.y = m_TmpReg.z = m_TmpReg.w =
            (float)(log(v)/log(2));
    }
    else
    {
        m_TmpReg.x = m_TmpReg.y = m_TmpReg.z = m_TmpReg.w = MINUS_INFINITY();
    }

    WriteResult();

注意

この命令は、2 を底とする対数の部分精度を計算する。vDest.z には近似解が生成されて、より正確な値は vDest.x + function(vDest.y) で求めることができる。function は、限られた範囲 (1.0 <= vDest.y < 2.0) の log2(vDest.y) に対してユーザーが使用する近似である。

logp 命令では、符号ビットは無視されるスカラー ソースを使用し、vDest.z の評価には低精度計算が使用できる。近似エラーは、絶対エラー (10 ビット精度) の 1/(211) より小さく、1.0 <= t.y < 2.0 の範囲内になければならない。ソース引数が 0 の場合は、結果のベクトル (-infinity, 0.0, -infinity, 1.0) が生成される。

次の例は、logp 命令の使い方を示している。

logp r0,r1


mad

ソースを乗算および加算する。

mad   vDest, vSrc0, vSrc1, vSrc2

レジスタ

vDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。
vSrc1
入力引数を指定するソース レジスタ。
vSrc2
入力引数を指定するソース レジスタ。

処理

次のコードは、mad 命令によって実行される処理とデスティネーションへの結果の書き込みを示している。

    SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1);
    SetSrcReg(2);

    m_TmpReg.x = m_Source[0].x * m_Source[1].x + m_Source[2].x;
    m_TmpReg.y = m_Source[0].y * m_Source[1].y + m_Source[2].y;
    m_TmpReg.z = m_Source[0].z * m_Source[1].z + m_Source[2].z;
    m_TmpReg.w = m_Source[0].w * m_Source[1].w + m_Source[2].w;

    WriteResult();

注意

次の例は、mad 命令の使い方を示している。

mad r0,r1,r2,v3


max

ソースの最大値を計算する。

max   vDest, vSrc0, vSrc1

レジスタ

vDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。
vSrc1
入力引数を指定するソース レジスタ。

処理

次の疑似コードは、max 命令によって実行される処理とデスティネーションへの結果の書き込みを示している。

    SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1);

    m_TmpReg.x=(m_Source[0].x >= m_Source[1].x) ? m_Source[0].x : m_Source[1].x;
    m_TmpReg.y=(m_Source[0].y >= m_Source[1].y) ? m_Source[0].y : m_Source[1].y;
    m_TmpReg.z=(m_Source[0].z >= m_Source[1].z) ? m_Source[0].z : m_Source[1].z;
    m_TmpReg.w=(m_Source[0].w >= m_Source[1].w) ? m_Source[0].w : m_Source[1].w;

    WriteResult();

注意

次の例は、max 命令の使い方を示している。

max r2, r3, r4


min

ソースの最小値を計算する。

min   vDest, vSrc0, vSrc1

レジスタ

vDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。
vSrc1
入力引数を指定するソース レジスタ。

処理

次のコードは、min 命令によって実行される処理とデスティネーションへの結果の書き込みを示している。

    SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1);

    m_TmpReg.x=(m_Source[0].x < m_Source[1].x) ? m_Source[0].x : m_Source[1].x;
    m_TmpReg.y=(m_Source[0].y < m_Source[1].y) ? m_Source[0].y : m_Source[1].y;
    m_TmpReg.z=(m_Source[0].z < m_Source[1].z) ? m_Source[0].z : m_Source[1].z;
    m_TmpReg.w=(m_Source[0].w < m_Source[1].w) ? m_Source[0].w : m_Source[1].w;

    WriteResult();

注意

次の例は、min 命令の使い方を示している。

min   r2, r3, r4


mov

ソースの内容をデスティネーションに移動する。

mov   vDest, vSrc0

レジスタ

vDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。

処理

次のコードは、mov 命令によって実行される処理とデスティネーションへの結果の書き込みを示している。

    SetDestReg();
    SetSrcReg(0);

    if( m_pDest == m_reg.m_a )
    {
        float p = (float)floor(m_Source[0].x);
        *(int*)&m_pDest->x = FTOI(p);
    }
    else
    {
        m_TmpReg = m_Source[0];
        WriteResult();
    }

注意

次の例は、mov 命令の使い方を示している。

mov r1, v2
mov r1.xy, r2.zw


mul

ソースを乗算してデスティネーションに格納する。

mul   vDest, vSrc0, vSrc1

レジスタ

vDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。
vSrc1
入力引数を指定するソース レジスタ。

処理

次のコードは、mul 命令によって実行される処理とデスティネーションへの結果の書き込みを示している。

    SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1);

    m_TmpReg.x = m_Source[0].x * m_Source[1].x;
    m_TmpReg.y = m_Source[0].y * m_Source[1].y;
    m_TmpReg.z = m_Source[0].z * m_Source[1].z;
    m_TmpReg.w = m_Source[0].w * m_Source[1].w;

    WriteResult();

注意

次の例は、mul 命令の使い方を示している。

mul r4, v0, r1


rcp

ソース スカラーの逆数を計算する。

rcp   vDest, vSrc0

レジスタ

vDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。

処理

次のコードは、rcp 命令によって実行される処理とデスティネーションへの結果の書き込みを示している。

    SetDestReg();
    SetSrcReg(0);

    if( m_Source[0].w == 1.0f )
    {
        // 正確に 1.0 でなければならない。
        m_TmpReg.x = m_TmpReg.y = m_TmpReg.z = m_TmpReg.w = 1.0f;
    }
    else if( m_Source[0].w == 0 )
    {
        m_TmpReg.x = m_TmpReg.y = m_TmpReg.z = m_TmpReg.w = PLUS_INFINITY();
    }
    else
    {
        m_TmpReg.x = m_TmpReg.y = m_TmpReg.z = m_TmpReg.w = 1.0f/m_Source[0].w;
    }

    WriteResult();

注意

ソースに添字がない場合は、x 要素が使われる。入力が 1.0 の場合は、出力も 1.0 にならなければならない。

(1.0, 2.0) の範囲を超えたエラーの精度は少なくとも 1.0/(222) 絶対値である。これは、通常の実装では仮数と指数が分離されるためである。0.0 のソースは無限大である。

次の例は、rcp 命令の使い方を示している。

rcp r1, r2
rcp r1, r2.y


rsq

ソース スカラーの逆数の平方根を計算する。

rsq   vDest, vSrc0

レジスタ

vDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。

処理

次のコードは、rsq 命令によって実行される処理とデスティネーションへの結果の書き込みを示している。

    SetDestReg();
    SetSrcReg(0);

    float v = ABSF(m_Source[0].w);
    if( v == 1.0f )
    {
        m_TmpReg.x = m_TmpReg.y = m_TmpReg.z = m_TmpReg.w = 1.0f;
    }
    else if( v == 0 )
    {
        m_TmpReg.x = m_TmpReg.y = m_TmpReg.z = m_TmpReg.w = PLUS_INFINITY();
    }
    else
    {
        v = (float)(1.0f / sqrt(v));
        m_TmpReg.x = m_TmpReg.y = m_TmpReg.z = m_TmpReg.w = v;
    }

    WriteResult();

注意

ソースに添字がない場合は、x 要素が使われる。入力が 1.0 の場合は、出力も 1.0 にならなければならない。

絶対値は処理の前に取得される。つまり、符号ビットは無視される。

(1.0, 4.0) の範囲を超えたエラーの精度は少なくとも 1.0/(222) 絶対値である。これは、通常の実装では仮数と指数が分離されるためである。0.0 のソースは無限大である。

次の例は、rsq 命令の使い方を示している。

rsq r1, r2
rsq r1, r2.y


sge

第 1 ソース オペランドの値が第 2 ソース オペランドの値以上の場合は、デスティネーションに 1.0 を設定する。それ以外の場合は、デスティネーションに 0.0 を設定する。

sge   vDest, vSrc0, vSrc1

レジスタ

vDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。
vSrc1
入力引数を指定するソース レジスタ。

処理

次のコードは、sge 命令によって実行される処理とデスティネーションへの結果の書き込みを示している。

    SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1);

    m_TmpReg.x = (m_Source[0].x >= m_Source[1].x) ? 1.0f : 0.0f;
    m_TmpReg.y = (m_Source[0].y >= m_Source[1].y) ? 1.0f : 0.0f;
    m_TmpReg.z = (m_Source[0].z >= m_Source[1].z) ? 1.0f : 0.0f;
    m_TmpReg.w = (m_Source[0].w >= m_Source[1].w) ? 1.0f : 0.0f;

    WriteResult();

注意

次の例は、sge 命令の使い方を示している。

sge   r1, r2, v1


slt

第 1 ソース オペランドの値が第 2 ソース オペランドの値未満の場合は、デスティネーションに 1.0 を設定する。それ以外の場合は、デスティネーションに 0.0 を設定する。

slt   vDest, vSrc0, vSrc1

レジスタ

vDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。
vSrc1
入力引数を指定するソース レジスタ。

処理

次のコードは、slt 命令によって実行される処理とデスティネーションへの結果の書き込みを示している。

    SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1);

    m_TmpReg.x = (m_Source[0].x < m_Source[1].x) ? 1.0f : 0.0f;
    m_TmpReg.y = (m_Source[0].y < m_Source[1].y) ? 1.0f : 0.0f;
    m_TmpReg.z = (m_Source[0].z < m_Source[1].z) ? 1.0f : 0.0f;
    m_TmpReg.w = (m_Source[0].w < m_Source[1].w) ? 1.0f : 0.0f;

    WriteResult();

注意

次の例は、slt 命令の使い方を示している。

slt   r1, r2, v1


sub

ソースを減算する。

sub   tDest, tSrc0, tSrc1

レジスタ

tDest
処理の結果を保持するデスティネーション レジスタ。
tSrc0
入力引数を指定するソース レジスタ。
tSrc1
入力引数を指定するソース レジスタ。

注意

この命令は、次の公式に基づいて減算を行う。

tDest = tSrc0 - tSrc1

次の例は、この命令の使い方を示している。

sub   r2, v2, r2    ; difference


バージョンおよび定数定義命令

Direct3DX 頂点シェーダ アセンブラには、シェーダのタイプおよびバージョンを識別したり、頂点シェーダで使用する定数を定義するための命令が用意されている。

def | 定数を定義する
vs | バージョンおよびタイプ

バージョン命令は、各シェーダの先頭にある必要がある。

定数定義命令は、バージョン命令の実行後、ほかのすべての命令よりも前に実行しなければならないことに注意すること。


def

頂点シェーダで使用する定数を定義するためのメソッドを提供する。

def   vDest, fVal0, fVal1, fVal2, fVal3

レジスタ

vDest
処理の結果を保持するデスティネーション レジスタ。
fVal0
入力引数を指定するソース レジスタ。
fVal1
入力引数を指定するソース レジスタ。
fVal2
入力引数を指定するソース レジスタ。
fVal3
入力引数を指定するソース レジスタ。

注意

次の例は、def 命令の使い方を示している。

def c0, 0.0f, 0.0f, 0.0f, 1.0f
def c8, 1.0f, 2.0f, 3.0f, 4.0f

これらの定数は、シェーダの作成時に宣言に含まれる宣言の一部として返される。


vs

シェーダ コードのタイプおよびバージョンを指定するためのメソッドを提供する。

vs.mainVer.subVer

レジスタ

mainVer
頂点シェーダのメイン バージョン番号。
subVer
頂点シェーダのサブ バージョン番号。

注意

次の例は、vs 命令の使い方を示している。

vs.1.0  ; 頂点シェーダ バージョン 1.0

この命令は、すべての頂点シェーダの先頭にある必要がある。


マクロ命令

Direct3DX 頂点シェーダ アセンブラでは、共通の単純な処理を実行する際のアプリケーションの便宜のために、マクロ命令が提供されている。これらのマクロは、ドライバによって、いくつかの標準的な頂点シェーダ命令に拡張されている。詳細については、各マクロ命令のリファレンス トピックを参照すること。

exp | 2 を底とする指数の完全精度
frc | 小数部
log | 2 を底とする対数の完全精度
m3x2 | 3 × 2 ベクトル行列の乗算
m3x3 | 3 × 3 ベクトル行列の乗算
m3x4 | 3 × 4 ベクトル行列の乗算
m4x3 | 4 × 3 ベクトル行列の乗算
m4x4 | 4 × 4 ベクトル行列の乗算

命令の数の上限である 128 を超えるかどうかを判断できるようにするため、マクロ命令は、列記されている実際の命令の数を超えないことが保証されている。

マクロ命令は実際の命令と同じ方法で実装環境に渡されるので、実装環境は自由にマクロ命令を最適化できる。したがって、必要なタイミング サイクル カウントについてはいかなる想定もできない。

参照

一般命令


exp

最低 1/220 の完全精度の指数 2x を提供する。

exp   vDest, vSrc0

レジスタ

vDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。

処理

    SetDestReg();
    SetSrcReg(0);

    float v = m_Source[0].w;

    m_TmpReg.x = m_TmpReg.y = m_TmpReg.z = m_TmpReg.w = (float)pow(2, v);

    WriteResult();

展開

このマクロは 12 の命令スロットを使用する。

注意

これはスカラー演算であり、その入力を .w チャネルから取る。このチャネルは指定する必要がある。この演算は、常に 4 つのすべてのチャネルに結果を複製する。


frc

各入力要素の小数部分を返す。

frc   vDest, vSrc0

レジスタ

vDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。

処理

    SetDestReg();
    SetSrcReg(0);

    m_TmpReg.x = m_Source[0].x - (float)floor(m_Source[0].x);
    m_TmpReg.y = m_Source[0].y - (float)floor(m_Source[0].y);
    m_TmpReg.z = m_Source[0].z - (float)floor(m_Source[0].z);
    m_TmpReg.w = m_Source[0].w - (float)floor(m_Source[0].w);

    WriteResult();

展開

このマクロは 3 つの命令スロットを使用する。

注意

結果の各要素は、0.0 から 1.0 の範囲である。

このマクロは x および y 要素を記述するのみである。


log

最低 1/220 の完全浮動小数点精度で log2(x) のサポートを提供する。

log   vDest, vSrc0

レジスタ

vDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。

処理

    SetDestReg();
    SetSrcReg(0);

    float v = ABSF(m_Source[0].w);
    if (v != 0)
    {
        m_TmpReg.x = m_TmpReg.y = m_TmpReg.z = m_TmpReg.w =
            (float)(log(v)/log(2));
    }
    else
    {
        m_TmpReg.x = m_TmpReg.y = m_TmpReg.z = m_TmpReg.w = minUS_INFINITY();
    }

    WriteResult();

展開

このマクロは 12 の命令スロットを使用する。

注意

この命令では符号ビットを無視したスカラー ソース .w が受け入れられる。結果は 4 つのすべてのチャネルに複製される。

入力指数の範囲は、-128 から 128 まででなければならない。近似エラーは、絶対エラーの 1/220 より小さく、1.0 <= t.y < 2.0 の範囲内になければならない。ソースが 0 の場合は、(-infinity,-infinity,-infinity,-infinity) が生成される。


m3x2

入力ベクトルと 3 × 2 行列の積を計算する。

m3x2   rDest, vSrc0, mSrc1

レジスタ

rDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。
mSrc1
入力引数を指定するソース レジスタ。

処理

    SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1, 2);
    m_TmpReg.x = m_Source[0].x * m_Source[1].x +
                 m_Source[0].y * m_Source[1].y +
                 m_Source[0].z * m_Source[1].z;
    m_TmpReg.y = m_Source[0].x * m_Source[2].x +
                 m_Source[0].y * m_Source[2].y +
                 m_Source[0].z * m_Source[2].z;

    WriteResult();

展開

次の例は m3x2 命令の使い方を示している。

m3x2   r5, v0, c[3]

内容

dp3   r5.x, v0, c[3]
dp3   r5.y, v0, c[4]

したがって、このマクロ命令は、命令カウントから命令スロットを 2 つ消費する。c[3] および c[4] の最後の w 要素はこの計算においては無視されることに注意する。

注意

入力ベクトルは vSrc0 であり、入力の 3 × 2 行列は mSrc1 および同じレジスタ ファイル内の次のレジスタである。2D の結果が生成されて、rDest のほかの要素 (z および w) は変更されないでそのまま残る。

この処理は、一般に、2D トランスフォームに使用される。このマクロ命令は、1 対の内積として実装される。


m3x3

入力ベクトルと 3 × 3 行列の積を計算する。

m3x3   rDest, vSrc0, mSrc1

レジスタ

rDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。
mSrc1
入力引数を指定するソース レジスタ。

処理

    SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1, 3);
    m_TmpReg.x = m_Source[0].x * m_Source[1].x +
                 m_Source[0].y * m_Source[1].y +
                 m_Source[0].z * m_Source[1].z;
    m_TmpReg.y = m_Source[0].x * m_Source[2].x +
                 m_Source[0].y * m_Source[2].y +
                 m_Source[0].z * m_Source[2].z;
    m_TmpReg.z = m_Source[0].x * m_Source[3].x +
                 m_Source[0].y * m_Source[3].y +
                 m_Source[0].z * m_Source[3].z;

    WriteResult();

展開

次の例は m3x3 命令の使い方を示している。

m3x3   r5, v0, c[3]

内容

dp3   r5.x, v0, c[3]
dp3   r5.y, v0, c[4]
dp3   r5.z, v0, c[5]

したがって、このマクロ命令は、命令カウントから命令スロットを 3 つ消費する。c[3]、c[4]、および c[5] の最後の w 要素はこの計算においては無視されることに注意すること。

注意

入力ベクトルは vSrc0 であり、入力の 3 × 3 行列は mSrc1 および同じレジスタ ファイル内でこれに続く 2 つのレジスタである。

この処理は、一般に、ライティング計算の際の法線ベクトルのトランスフォームに使用される。このマクロ命令は、一連の内積として実装される。


m3x4

入力ベクトルと 3 × 4 行列の積を計算する。

m3x4   rDest, vSrc0, mSrc1

レジスタ

rDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。
mSrc1
入力引数を指定するソース レジスタ。

処理

    SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1, 4);
    m_TmpReg.x = m_Source[0].x * m_Source[1].x +
                 m_Source[0].y * m_Source[1].y +
                 m_Source[0].z * m_Source[1].z;
    m_TmpReg.y = m_Source[0].x * m_Source[2].x +
                 m_Source[0].y * m_Source[2].y +
                 m_Source[0].z * m_Source[2].z;
    m_TmpReg.z = m_Source[0].x * m_Source[3].x +
                 m_Source[0].y * m_Source[3].y +
                 m_Source[0].z * m_Source[3].z;
    m_TmpReg.w = m_Source[0].x * m_Source[4].x +
                 m_Source[0].y * m_Source[4].y +
                 m_Source[0].z * m_Source[4].z;

    WriteResult();

展開

次の例は m3x4 命令の使い方を示している。

m3x4   r5, v[0], c[3]

内容

dp3 r5.x, v[0], c[3]
dp3 r5.y, v[0], c[4]
dp3 r5.z, v[0], c[5]
dp3 r5.w, v[0], c[6]

したがって、このマクロ命令は、命令カウントから命令スロットを 4 つ消費する。c[3]、c[4]、および c[5] の最後の w 要素はこの計算においては無視されることに注意すること。

注意

入力ベクトルは vSrc0 であり、入力の 3 × 4 行列は mSrc1 および同じレジスタ ファイル内でこれに続く 2 つのレジスタである。

この処理は、一般に、射影エフェクトはあるが平行移動は行わない行列による、位置ベクトルのトランスフォームに使用される。このマクロ命令は、一連の内積として実装される。


m4x3

入力ベクトルと 4 × 3 行列の積を計算する。

m4x3   rDest, vSrc0, mSrc1

レジスタ

rDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。
mSrc1
入力引数を指定するソース レジスタ。

処理

    SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1, 3);
    m_TmpReg.x = m_Source[0].x * m_Source[1].x +
                 m_Source[0].y * m_Source[1].y +
                 m_Source[0].z * m_Source[1].z +
                 m_Source[0].w * m_Source[1].w;
    m_TmpReg.y = m_Source[0].x * m_Source[2].x +
                 m_Source[0].y * m_Source[2].y +
                 m_Source[0].z * m_Source[2].z +
                 m_Source[0].w * m_Source[2].w;
    m_TmpReg.z = m_Source[0].x * m_Source[3].x +
                 m_Source[0].y * m_Source[3].y +
                 m_Source[0].z * m_Source[3].z +
                 m_Source[0].w * m_Source[3].w;

    WriteResult();

展開

次の例は m4x3 命令の使い方を示している。

m4x3   r5, v[0], c[3]

内容

dp4   r5.x, v[0], c[3]
dp4   r5.y, v[0], c[4]
dp4   r5.z, v[0], c[5]

したがって、このマクロ命令は、命令カウントから命令スロットを 3 つ消費する。入力ベクトルの w の値が 1.0 でない限り、c[3]、c[4]、および c[5] の最後の w 要素はこの計算においては無視されることに注意すること。この w の値が 0.0 の場合は、入力ベクトルの平行移動は行われない。つまり、行列の平行移動要素は適用されない。

注意

入力ベクトルは vSrc0 であり、入力の 4 × 3 行列は mSrc1 および同じレジスタ ファイル内でこれに続く 2 つのレジスタである。

この処理は、一般に、モデル空間のトランスフォームにおいて発生する場合など、射影エフェクトのない行列による位置ベクトルのトランスフォームに使用される。このマクロ命令は、一連の内積として実装される。


m4x4

入力ベクトルと 4 × 4 行列の積を計算する。

m4x4   rDest, vSrc0, mSrc1

レジスタ

rDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。
mSrc1
入力引数を指定するソース レジスタ。

処理

   SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1, 4);
    m_TmpReg.x = m_Source[0].x * m_Source[1].x +
                 m_Source[0].y * m_Source[1].y +
                 m_Source[0].z * m_Source[1].z +
                 m_Source[0].w * m_Source[1].w;
    m_TmpReg.y = m_Source[0].x * m_Source[2].x +
                 m_Source[0].y * m_Source[2].y +
                 m_Source[0].z * m_Source[2].z +
                 m_Source[0].w * m_Source[2].w;
    m_TmpReg.z = m_Source[0].x * m_Source[3].x +
                 m_Source[0].y * m_Source[3].y +
                 m_Source[0].z * m_Source[3].z +
                 m_Source[0].w * m_Source[3].w;
    m_TmpReg.w = m_Source[0].x * m_Source[4].x +
                 m_Source[0].y * m_Source[4].y +
                 m_Source[0].z * m_Source[4].z +
                 m_Source[0].w * m_Source[4].w;

    WriteResult();

展開

次の例は m4x4 命令の使い方を示している。

m4x4   r5, v[0], c[3]

内容

dp4   r5.x, v[0], c[3]
dp4   r5.y, v[0], c[4]
dp4   r5.z, v[0], c[5]
dp4   r5.w, v[0], c[6]

したがって、このマクロは、命令カウントから 4 つの命令スロットを使用する。

注意

入力ベクトルは vSrc0 であり、入力の 4 × 4 行列は mSrc1 および同じレジスタ ファイル内でこれに続く 3 つのレジスタである。

この処理は、一般に、射影行列による位置座標のトランスフォームに使われる。このマクロ命令は、一連の内積として実装される。


修飾子

ここでは、Direct3DX 頂点シェーダ アセンブラが実装する成分修飾子についてのリファレンス情報を記述する。

次の表で示すように、成分修飾子 (x は有効なレジスタ、つまり an、c[n]、rn、vn、または出力レジスタのいずれか) は、ベクトル データの個別の成分に適用できる。

成分修飾子 | 説明
r.{x}{y}{z}{w} | デスティネーション マスク
r.[xyzw][xyzw][xyzw][xywz] | ソースの入れ換え
-r | デスティネーションの正負を反転


ピクセル シェーダ アセンブラ リファレンス

ここでは、Direct3DX ピクセル シェーダ アセンブラについてのリファレンス情報を記述する。リファレンス情報は次のカテゴリに分類されている。

  • レジスタ
  • 命令
  • 修飾子
  • 出力書き込みマスク

ピクセル シェーダ アセンブラは、一連のレジスタおよびそのレジスタ上で実行できる処理群で構成されている。処理は、演算子と 1 つ以上の引数 (オペランド) で構成される命令として表現されている。

Microsoft® DirectX® 8.0 では、すべてのサーフェス フォーマットに対して少なくとも 8 ビットの精度を維持するための中間計算が必要である。ステージ内の計算では高精度 (12 ビット) が、テクスチャ ステージ間では 8 ビットに収めることが推奨されている。修正可能な丸めモードや例外はサポートされていない。精度の損失を最小化するために、直近値丸め精度の乗算がサポートされている必要がある。


レジスタ

ここでは、Direct3DX ピクセル シェーダ アセンブラが実装するレジスタについてのリファレンス情報を記述する。

名前 | I/0 許可 | 最小カウント | 命令ごとの最大カウント | ソース
cn | 読み取り専用 | 8 | 2 | API 呼び出し
rn | 読み書き可能 | 2 | 2 | 書き込まれた
tn | 読み書き可能 | 4 | 1 | テクスチャ
vn | 読み取り専用 | 2 | 1 | 頂点カラー

「最小カウント」の列は、Microsoft® DirectX® 8.0 のシェーディング能力を公開するために実装環境がサポートしなければならないレジスタの最小個数を示している。

「命令ごとの最大カウント」の列は、1 つの命令がサポートするレジスタの最大個数を示している。これには、命令に対するソース パラメータの読み取りポートが含まれる。命令のデスティネーション パラメータに制限は適用されない。

各レジスタは 4 要素のベクトルであり、要素の範囲は -1.0 から 1.0 までで、要素ごとの精度は最低 8 ビットである。頂点シェーダ アセンブラとは異なり、ピクセル シェーダ アセンブラは出力レジスタを持たない。ピクセル シェーダは r0 だけを出力する。


cn

これらは定数レジスタである。定数 D3DRS_TEXTUREFACTOR から取得される固定要素レジスタは、IDirect3DDevice8::SetPixelShaderConstant メソッドを使ってアプリケーションによってロードされる。

固定要素レジスタは読み取り専用である。ピクセル シェーダ用に少なくとも 8 つの固定要素レジスタが定義されるが、1 つの命令で使用できるのは 2 つまでである。


rn

これらはテンポラリ レジスタである。テンポラリ レジスタは中間結果を格納するために使用できる。テンポラリ レジスタは読み書き可能で、1 つのシェーダ命令で使用できるのは 2 つまでである。デバッグ ランタイムにおけるシェーダの前処理では、前の命令で書き込まれていないテンポラリ レジスタから読み取りを行おうとするシェーダについて、IDirect3DDevice8::CreatePixelShader は失敗する。

すべてのピクセル シェーダは最終結果として r0 を書き込む必要があるため、最も単純なデカール ピクセル シェーダは 2 つの命令で構成される。

ps.1.0       // DirectX8 バージョン。
tex   t0
mov   r0, t0


tn

これらはテクスチャ レジスタである。テクスチャ レジスタの最大数は、同時にサポートされるテクスチャの数と同じである。テクスチャ レジスタは、そのステージのテクスチャ ステージ ステートによって定義されるフィルタリング モードを含む、テクスチャ サンプリング ユニットからのテクスチャ カラーを格納することで初期化される。色は、IDirect3DDevice8::SetTexture で定義されている対応するテクスチャから取得され、対応するテクスチャ座標でサンプリングされる。

テクスチャ セットを持たないすべてのテクスチャ レジスタは、不透明の黒 (0,0,0,1) としてサンプリングされる。1 つのシェーダ命令で使用できるテクスチャ レジスタは 2 つまでである。テクスチャ レジスタは、テンポラリ レジスタとしても使用できる。具体的には、テクスチャ アドレッシング命令の後で、これらのレジスタは読み書きテンポラリ レジスタとして使用できる。

ほとんどの場合、テクスチャ レジスタは、テクスチャ コマンドのデスティネーションとしてのみ有効である。ただし、テクスチャ レジスタから算術命令を読み取ることができることに注意すること。


vn

これらは頂点カラー レジスタである。入力頂点カラー レジスタには、頂点シェーダから出力されるカラー値のピクセル単位のグーロー補間によって取得されるカラー値が格納される (頂点シェーダはカラー値を頂点ストリームから受け取ることができる)。Microsoft® DirectX® 8.0 に準拠した実装では、少なくとも 2 つの入力カラー レジスタをサポートしなければならない。

入力カラー レジスタは読み取り専用で、1 つの命令ではこれらの色のうち 1 つだけ使用できる。

フラット シェーディングをシミュレートするにはコンスタント カラーの方が効果的である。ただし、シェード モードが D3DSHADE_FLAT のときは、どちらの色の補間も無効になっている。フォグは引き続き補間されなければならないことに注意する必要がある。理想的には、すべての色補間は、テクスチャ座標補間と同じ方法のパースペクティブ補正でなければならない。


命令

Direct3DX コンパイラが認識する、ピクセル シェーダに対する処理は主に 2 つに分類され、ピクセル色およびアルファ ブレンディング処理と、テクスチャ ブレンディング処理がある。アセンブラは、命令を使ってこれらの処理を提供している。ピクセル色およびアルファ ブレンディング処理はカラー データを変更するもので、テクスチャ アドレッシング処理はテクスチャの座標データを操作および処理する。ピクセル シェーダのすべての命令はピクセル単位に実行される。つまり、パイプライン内のほかのピクセルは認識されない。

  • 色およびアルファ ブレンディング命令
  • バージョンおよび定数定義命令
  • テクスチャ アドレッシング命令

ブレンディング処理は、RGB 色とスカラー アルファの個別処理に使用できる。ほとんどの場合、ピクセル ブレンディング (色またはアルファ) 処理は、色命令とアルファ命令の両方を 1 スロットでサポートできる。

準拠した実装では、最低 8 つのブレンディング命令と 4 つのアドレッシング命令のプログラムをサポートしなければならない。

テクスチャ アドレッシング処理はそれぞれ 1 スロットを使用するが、ピクセル ブレンディング (色およびアルファ) 処理は対にして、色命令とアルファ命令の両方を 1 スロットで実行できる。Microsoft® DirectX® 8.0 では、テクスチャ アドレッシング命令はカラー ブレンディング命令より先に実行しなければならない。

テクスチャ アドレス補正処理の構文は、シェーダ プログラム自体に、テクスチャ宣言の形式で含まれている。これらは、ピクセル シェーダ本体で使用するためにテンポラリ レジスタ ファイルにプリロードするときにテクスチャからサンプリングされる色の値に対して、どのようにアドレス補正処理を適用するかを制御する。


色およびアルファ ブレンディング命令

ここでは、Direct3DX ピクセル シェーダ アセンブラが実装する色およびアルファ ブレンディング命令についてのリファレンス情報を記述する。

次の表は、色およびアルファ ブレンディング命令の一覧である。これらの処理はすべてコンポーネント単位で実行される。

命令 | 説明
add | 加算
cnd | 条件
dp3 | 3 要素ベクトルの内積
lrp | 線形補間ブレンディング
mad | 乗算と加算
mov | コピー元からコピー先へのコピー
mul | 乗算
sub | ソース オペランドの 2 色の差をロードする


add

ソース オペランドの 2 つの色の合計をロードする。

add   tDest, tSrc0, tSrc1

レジスタ

tDest
処理の結果を保持するデスティネーション レジスタ。
tSrc0
入力引数を指定するソース レジスタ。
tSrc1
入力引数を指定するソース レジスタ。

注意

次の例は、この命令の使い方を示している。

add d, s1, s2    ; sum d = s1 + s2


cnd

r0.a の値を 0.5 と比較する条件演算を実行する。

cnd   tDest, tSrc0, tSrc1, tSrc2

レジスタ

tDest
処理の結果を保持するデスティネーション レジスタ。
tSrc0
入力引数を指定するソース レジスタ。
tSrc1
入力引数を指定するソース レジスタ。
tSrc2
入力引数を指定するソース レジスタ。

注意

この命令は、r0.a の値と 0.5 を比較するためにのみ使用できる。アルファ (r0.a) が 0.5 よりも大きい場合、最初のソースが結果として返される。それ以外の場合は、2 番目のソースが返される。

次の例は、この命令の使い方を示している。

cnd d, r0.a, s1, s2    ; d = ( r0.a >0.5 ? s1 : s2 )

a - (b - 0.5) = a - b + 0.5 なので、2 つの値を比較するには、次のピクセル シェーダ コードを使用できる。

sub r0, v0,   v1_bias
cnd r0, r0.a, c0, c1

前に説明したように、最初のソース引数に配置できる値は r0.a だけであり、比較値は "0.5 よりも大きく" なければならない。


dp3

ソース オペランド レジスタの 2 色の 3 要素ベクトル内積をロードする。

dp3   tDest, tSrc0, tSrc1

レジスタ

tDest
処理の結果を保持するデスティネーション レジスタ。
tSrc0
入力引数を指定するソース レジスタ。
tSrc1
入力引数を指定するソース レジスタ。

注意

この命令はスカラーの結果を生成するが、それを指定されたすべての出力チャネルに複製する。

dp3 r, s1, s2    ; s1 と s2 の内積、全てのチャンネルに複製

dp3 命令は基本的にベクトル演算であるため、常にベクトル パイプラインで実行されることに注意すること。これをアルファ複製 ny入力引数修飾子 (.a) と共に使用した場合、この入力引数修飾子は単に結果がアルファ チャネルにも伝達されることを示す。つまり、dp3 はカラー処理も行う場合にのみアルファ処理として指定でき、同じ引数を使用しなければならない。

dp3 r0.rgb, t0, v0
dp3 r0.a,   t0, v0

または、次のようにしても同じである。

dp3 r0, t0, v0

この場合、dp3 演算のグレースケールの結果が、r0 のカラー チャネルとアルファ チャネルの両方にコピーされる。

結果のアルファ チャネルでは、異なる命令を指定できる。

dp3 r0.rgb, t0, v0
mul r0.a,   t0, v0

dp3 命令は、入力引数が符号付き動的範囲に展開されていない場合、通常、入力引数に適用された符号化スケーリング入力引数修飾子 (_bx2) を利用する。ライティングについて使用する場合は、通常、次の例のように、彩度命令修飾子 (_sat) を使用して負の値を黒に制限する。

dp3_sat r0, t0_bx2, v0_bx2    ; t0 はバンプ、v0 はライトの方向ベクトル


lrp

第 1 ソース レジスタで指定された割合で、第 2 および第 3 ソース レジスタの間を線形補間する。

lrp   tDest, tSrc0, tSrc1, tSrc2

レジスタ

tDest
処理の結果を保持するデスティネーション レジスタ。
tSrc0
入力引数を指定するソース レジスタ。
tSrc1
入力引数を指定するソース レジスタ。
tSrc2
入力引数を指定するソース レジスタ。

注意

この命令は、次の公式に基づいて線形補間を行う。

tSrc0 * tSrc1 + (1-tSrc0) * tSrc2 = tSrc2 + tSrc0 * (tSrc1 - tSrc2)

次の例は、この命令の使い方を示している。

lrp d, s0, s1, s2    ; d = s0*s1 + (1-s0)*s2 = s2 + s0*(s1-s2)


mad

最後の 2 つのソース オペランド レジスタで指定されている 2 つの色の積に、第 1 ソース レジスタを追加した値をロードする。

mad   tDest, tSrc0, tSrc1, tSrc2

レジスタ

tDest
処理の結果を保持するデスティネーション レジスタ。
tSrc0
入力引数を指定するソース レジスタ。
tSrc1
入力引数を指定するソース レジスタ。
tSrc2
入力引数を指定するソース レジスタ。

注意

この命令は、複数操作の蓄積を行う。最初の 2 つの引数を掛け、それに残った入力ソース引数を足し、その結果をレジスタに書き込む。

この命令は、次の公式に基づいて乗算と加算を行う。

tSrc0 * tSrc1 + tSrc2

次の例は、この命令の使い方を示している。

mad  d, s0, s1, s2;    d = s0 * s1 + s2


mov

ソース レジスタの値をロードする。

mov   tDest, tSrc0

レジスタ

tDest
処理の結果を保持するデスティネーション レジスタ。
tSrc0
入力引数を指定するソース レジスタ。

注意

次の例は、この命令の使い方を示している。

mov   d, s    ; s を d にコピー ( d = s )


mul

デスティネーション レジスタに、ソース オペランド レジスタの 2 色の要素単位の内積をロードする。

mul   tDest, tSrc0, tSrc1

レジスタ

tDest
処理の結果を保持するデスティネーション レジスタ。
tSrc0
入力引数を指定するソース レジスタ。
tSrc1
入力引数を指定するソース レジスタ。

注意

この命令は、乗算処理を行うものである。

次の例は、この命令の使い方を示している。

mul  d, s1, s2    ; 乗算 d = s1*s2


sub

ソース オペランドの 2 つの色の差をロードする。

sub   tDest, tSrc0, tSrc1

レジスタ

tDest
処理の結果を保持するデスティネーション レジスタ。
tSrc0
入力引数を指定するソース レジスタ。
tSrc1
入力引数を指定するソース レジスタ。

注意

この命令は、次の公式に基づいて減算を行う。

tDest = tSrc0 - tSrc1

次の例は、この命令の使い方を示している。

sub   d, s1, s2    ; 差


バージョンおよび定数定義命令

Direct3DX ピクセル シェーダ アセンブラには、シェーダのタイプおよびバージョンを識別したり、ピクセル シェーダで使用する定数を定義するための命令が用意されている。

def | 定数を定義する
ps | バージョンおよびタイプ

バージョン命令は、各シェーダの先頭にある必要がある。

定数定義命令は、バージョン命令の実行後、ほかのすべての命令よりも前に実行しなければならないことに注意すること。


def

ピクセル シェーダで使用する定数を定義するためのメソッドを提供する。

def   vDest, fVal0, fVal1, fVal2, fVal3

レジスタ

vDest
処理の結果を保持するデスティネーション レジスタ。
fVal0
入力引数を指定するソース レジスタ。
fVal1
入力引数を指定するソース レジスタ。
fVal2
入力引数を指定するソース レジスタ。
fVal3
入力引数を指定するソース レジスタ。

注意

次の例は、def 命令の使い方を示している。def 命令は、ほかのシェーダの命令より前に置く必要がある。

Ps.1.0
def c0, 0.0f, 0.0f, 0.0f, 1.0f
def c7, 1.0f, 2.0f, 3.0f, 4.0f
tex t0
mov r0, t0

これらの定数は命令ストリームで定義される。


ps

シェーダ コードのタイプおよびバージョンを指定するためのメソッドを提供する。

ps.mainVer.subVer

レジスタ

mainVer
ピクセル シェーダのメイン バージョン番号。
subVer
ピクセル シェーダのサブ バージョン番号。

注意

次の例は、ps 命令の使い方を示している。

ps.1.0  ; ピクセル シェーダ バージョン 1.0.

この命令は、すべてのピクセル シェーダの先頭にある必要がある。


テクスチャ アドレッシング命令

ここでは、Direct3DX ピクセル シェーダ アセンブラが実装するテクスチャ アドレッシング命令についてのリファレンス情報を記述する。テクスチャ アドレッシング命令は、(テクスチャ カラー座標に対立するものとして) テクスチャ アドレス データを操作できるようにするために用意されている。

サンプリング ステージのテクスチャ セットは、Microsoft® Direct3D® アプリケーション プログラミング インターフェイス (API) のテクスチャ ステージ ステートによって選択されるサンプリング、フィルタリング、およびラッピング モードを使って、対応するテクスチャからサンプリングされる。テクスチャをサンプリングするときに、テクスチャのサンプリングに使用するアドレスに適用できる処理もある。これらの処理は、テクスチャ アドレッシング処理と呼ばれる。

次の表は、テクスチャ アドレッシング命令およびテクスチャ補正処理のサブセットを示している。

命令 | 説明
tex | 変更なし
texbem | バンプ環境マップ
texbeml | 輝度付きバンプ環境マップ
texcoord | テクスチャ座標
texkill | ピクセルのマスク アウト
texm3x2pad | 3 × 2 行列乗算への入力
texm3x2tex | 3 × 2 行列乗算の結果
texreg2ar | アルファ成分および赤成分の再マッピング
texreg2gb | 緑成分および青成分の再マッピング

さらに、ピクセル シェーダ API は、テクスチャからサンプリングされたベクトルについてのピクセル単位の 3 × 3 行列乗算を実行する多くのメソッドをサポートする。3 × 3 行列は、3 つの連続するテクスチャ宣言ステージのテクスチャ座標で構成されている。これらの行列乗算演算は、複数のテクスチャ アドレス処理から構築される。

次の表は、ピクセル単位の 3 × 3 行列乗算に関連する、残りのテクスチャ アドレッシング命令を示している。

命令 | 説明
texm3x3pad | 3 × 3 行列乗算への入力
texm3x3spec | スペキュラ反射と環境マッピング
texm3x3tex | 3 × 3 行列乗算の結果
texm3x3vspec | 固定視点ベクトルを含まないスペキュラ反射/環境マッピング

テクスチャ アドレス命令は、宣言/定義したテクスチャ アドレスになる出力引数 (結果) を定義する。一部の命令では、入力オペランドを指定する必要がある。この入力オペランドは、定義済みのテクスチャでなければならない。これらは、テクスチャ サンプリング ユニットによって、カラー処理/アルファ処理/ブレンディング シェーダに放出されるテクスチャ カラーの宣言と考えられる。これらのテクスチャ レジスタは、定義済みのテクスチャで宣言できるが、後のテクスチャ、またはその他のピクセル カラー レジスタとしては宣言できない。

すべてのテクスチャ アドレス処理は、テクスチャを定義した順序で宣言しなければならない。テクスチャ アドレス処理では、それより後にある別のテクスチャ (つまり、ステージ番号がより大きなテクスチャ) を参照することはできない。

パフォーマンスに関する注意 テクスチャ アドレッシング処理では、テクスチャ アドレスを表すのに十分な精度をサポートしている必要がある。たとえば、デバイスでサポートされている最大テクスチャ ディメンジョンの環境マップで、テクセルの一部に対して補正できるバンプ環境マッピング行列の要素で補正を表現するのに十分な精度でなければならない。また、これらの処理で補間されるすべての量は、パースペクティブ補正を使って補間しなければならない。


tex

テクスチャから色をサンプリングし、サンプリングに使用したアドレスは変更しないで対応するレジスタにコピーする。

tex   tDest

レジスタ

tDest
処理の結果を保持するデスティネーション レジスタ。

注意

この命令がデフォルトなので、ほかの命令によってサンプリングが指定されていないすべてのテクスチャに対しては、tex 命令の適用が想定される。

次の例は、この命令の使い方を示している。

tex r0    ; ステージ 0 でセットされているテクスチャから
          ; レジスタ 0 を宣言

この命令は、このテクスチャ ステージに対応する割り当て済みのテクスチャである無名の入力を取ることに注意すること。


texbem

入力引数で定義されている色を、DuDv 摂動データとして使用する。

texbem   tDest, tSrc0

レジスタ

tDest
処理の結果を保持するデスティネーション レジスタ。
tSrc0
入力引数を指定するテンポラリ ソース レジスタ。

注意

texbem 命令は、u 成分と v 成分を 2D バンプ環境マッピング行列でトランスフォームし、それを現在のステージのテクスチャ座標に追加し、現在のステージのテクスチャをサンプリングする。

tex    t0        ; テクスチャからサンプルするよう t0 を定義
texbem t1, t0    ; u = u1 + mat00*r0.r + mat01*r0.g, と
                 ; v = v1 + mat10*r0.r + mat11*r0.g を計算
                 ; 次に u,v でサンプル、 r0.b は無視される
mov r0, t1       ; 最終結果を出力色にコピー

この処理は常に du および dv を符号付きの数値として解釈するので、入力引数について符号化スケーリング入力修飾子 (_bx2) を入力引数として指定する必要はない。テクスチャは 2 番目のステージで設定され、最初のステージで設定されたテクスチャは無視される。

この命令は、ピクセル単位の環境マッピングやディフューズ ライト (バンプ マッピング)、環境マッティングなど、アドレス補正に基づくさまざまな技法に使用できる。

この処理は 2 つの命令のマクロである (2 ステージ/スロットを消費する)。u' = u + du*M00 + dv*M01 および v' = v + du*M10 + dv*M11 で、M00、M01、M10、および M11 は D3DTSS_BUMPENVMAT00、D3DTSS_BUMPENVMAT01、D3DTSS_BUMPENVMAT10、および D3DTSS_BUMPENVMAT11 である。

この命令は、このテクスチャ ステージに対応する割り当て済みのテクスチャである無名の入力を取ることに注意すること。


texbeml

前のステージでサンプリングされた色を、輝度情報付きの DuDvL 摂動データとして使用する。

texbeml   tDest, tSrc0

レジスタ

tDest
処理の結果を保持するデスティネーション レジスタ。
tSrc0
入力引数を指定するテンポラリ ソース レジスタ。

注意

texbeml 命令は、色の赤成分と緑成分を 2D バンプ環境マッピング行列でトランスフォームし、その成分を現在のステージのテクスチャ座標に追加し、作成された 2D アドレスでこのテクスチャをサンプリングする。次に、輝度 (L) および Microsoft® Direct3D® API 指定の輝度とバイアス テクスチャ ステージの値を使って、輝度修正を適用する。

次のピクセル シェーダでは、デスティネーション レジスタに設定される色は、ステージ 1 で設定されたテクスチャ マップから取得されて、赤チャネルと緑チャネルの値で補正されたアドレスによってインデックス付けされて、ステージ 0 で設定されたマップからサンプリングされた色として定義される。

tex     t0        ; 3 要素 DuDvL を取得するため t0 を定義
texbeml t1, t0    ; u = u1 + mat00*r0.r + mat01*r0.g と
                  ;  v = v1 + mat10*r0.r + mat11*r0.g を計算
                  ; 次に u,v でサンプル、r0.b は無視される
                  ; 次に輝度修正を適用
mov r0, t1        ; 最終結果を出力色にコピー

テクスチャは 2 番目のステージで設定され、最初のステージで設定されたテクスチャは無視される。

この処理は 2 つの命令のマクロである (2 ステージ/スロットを消費する)。u' = u + du*M00 + dv*M01 および v' = v + du*M10 + dv*M11 で、M00、M01、M10、および M11 は D3DTSS_BUMPENVMAT00、D3DTSS_BUMPENVMAT01、D3DTSS_BUMPENVMAT10、および D3DTSS_BUMPENVMAT11 である。

この命令は、このテクスチャ ステージに対応する割り当て済みのテクスチャである無名の入力を取ることに注意すること。


texcoord

このステージに対して割り当てられた補間されたテクスチャの座標を、ブレンディングで使用する色に変換する。

texcoord   tDest

レジスタ

tDest
処理の結果を保持するデスティネーション レジスタ。

注意

この命令を使うと、テクスチャ座標を追加グーロー補間 (保証されたパースペクティブ補正) 色として使用できる。

texcoord  t0    ; テクスチャ座標からカラーとして t0 を宣言

頂点シェーダは任意の量をテクスチャ座標にマッピングできるので、texcoord 命令を使うと、位置、法線、光源方向などの任意のデータをピクセル シェーダにストリームできる。

この命令は、このテクスチャ ステージに対応する割り当て済みのテクスチャである無名の入力を取ることに注意すること。


texkill

任意のテクスチャ座標が 0 より小さい場合、ピクセルをマスク アウトする。

texkill   tDest

レジスタ

tDest
処理の結果を保持するデスティネーション レジスタ。

この命令を使って、ラスタライザで任意のクリップ面を実装できる。

頂点シェーダを使用する場合、アプリケーションはパースペクティブ トランスフォームを適用する必要がある。不等形のスケーリング係数が含まれている場合、クリップ面もトランスフォームする必要があるので、任意のクリップ面では問題が発生することがある。したがって、任意クリップ面で使用するには、texkill 演算子で識別されるテクスチャ座標セットである非射影頂点位置を提供するのが最適である。

この命令は、このテクスチャ ステージに対応する割り当て済みのテクスチャである無名の入力を取ることに注意すること。


texm3x2pad

2 × 3 行列乗算を実行するために、ほかのテクスチャ アドレス処理と組み合わせて使用される。

texm3x2pad   tDest, tSrc0

レジスタ

tDest
処理の結果を保持するデスティネーション レジスタ。
tSrc0
入力引数を指定するテンポラリ ソース レジスタ。

注意

この命令は、テクスチャ座標だけが使用されるステージを表すために使用される。これらの対応するステージにはテクスチャはバインドされていないので、サンプリングは行われない。入力引数 t0 は指定する必要がある。

次の例は、texm3x2pad 命令の使い方を示している。

tex t0             ; 標準的な 3 ベクトルとして t0 を定義
texm3x2pad t1, t0  ; 行列の第 1 行の乗算を実行
texm3x2tex t2, t0  ; 行列の第 2 行の乗算を実行し、
                   ; テクスチャ 2 としてサンプルする 2 ベクトルを取得

この命令は、このテクスチャ ステージに対応する割り当て済みのテクスチャである無名の入力を取ることに注意すること。


texm3x2tex

入力色ベクトルに対して 3 × 2 行列乗算を実行する。

texm3x2tex   tDest, tSrc0

レジスタ

tDest
処理の結果を保持するデスティネーション レジスタ。
tSrc0
入力引数を指定するテンポラリ ソース レジスタ。

注意

texm3x2tex 命令は、指定された入力色を取得し、入力色とそのステージのテクスチャ座標 (u、v、および w) の内積を計算して、u 座標を生成する。次に、同じ入力色を取得し、入力色とこのステージのテクスチャ座標の内積を計算して、v 座標を得る。最後に、このステージのテクスチャを (u、v) でサンプリングして、最終的な色を生成する。前のステージではテクスチャはサンプリングされておらず、また前のステージでテクスチャを設定する必要はなく、テクスチャに割り当てられているすべての演算子はこの演算によって無効になる。

次の例は、texm3x2tex 命令の使い方を示している。

tex t0             ; 標準的な 3 ベクトルとして t0 を定義
texm3x2pad t1, t0  ; 行列の第 1 行の乗算を実行
texm3x2tex t2, t0  ; 行列の第 2 行の乗算を実行し、
                   ; テクスチャ 2 としてサンプルする 2 ベクトルを取得
mov r0, t2

バンプ (通常の) マップはステージ 0 で設定し、標準の 2D テクスチャはステージ 2 で設定する必要がある。ステージ 1 で設定されるテクスチャは、すべて無視される。たとえば、次のシェーダでは、ベース テクスチャはディフューズ バンプ マップを乗算し、指数スペキュラを追加することによってライティングされている。ステージ 0 ではベース テクスチャを設定し、ステージ 1 では法線マップを設定し、ステージ 2 ではもう一度法線マップを設定している。

ps.1.0                 ; DirectX8 バージョン
tex t0                 ; サンプル法線マップ
texm3x2pad t1, t0_bx2  ; ライト ベクトルによる内積
texm3x2tex t2, t0_bx2  ; 半ベクトルとサンプルによる内積
mov r0, t2

設定 0 のテクスチャ座標はバンプ マップに位置する。テクスチャ座標セット 1 および 2 は、行列の行である。

この命令は、このテクスチャ ステージに対応する割り当て済みのテクスチャである無名の入力を取ることに注意すること。


texm3x3pad

テクスチャがバインドされていない 3 × 3 行列乗算の行で使用される処理を表す。

texm3x3pad   tDest, tSrc0

レジスタ

tDest
処理の結果を保持するデスティネーション レジスタ。
tSrc0
入力引数を指定するテンポラリ ソース レジスタ。

注意

この命令は、ピクセル シェーダのテクスチャ宣言ステージで実行される 3 × 3 行列乗算処理の一部である。宣言済みテクスチャに対応するテクスチャ座標は行列の行として使用される。このステージでは、いずれのテクスチャもバインドすべきではない。

この宣言に対する入力引数である t0 は、以下のピクセル シェーダの例に示すように、行列の乗算に対する入力引数である tSrc0 に指定しなければならない。

tex t0             ; 標準的な 3 ベクトルとして t0 を定義
texm3x3pad t1, t0  ; 行列の第 1 行の乗算を実行
texm3x3pad t2, t1  ; 行列の第 2 行の乗算を実行
texm3x3tex t3, t2  ; 行列の第 3 行の乗算を実行し、
                   ; テクスチャ 2 としてサンプルする 3 ベクトルを取得
mov r0, t3

この命令は、このテクスチャ ステージに対応する割り当て済みのテクスチャである無名の入力を取ることに注意すること。


texm3x3spec

スペキュラ反射と環境マッピングを実行する。

texm3x3spec   tDest, tSrc0, tSrc1

レジスタ

tDest
処理の結果を保持するデスティネーション レジスタ。
tSrc0
入力引数を指定するソース レジスタ。
tSrc1
入力引数を指定するソース レジスタ。

注意

この処理は、結果として生成されるトランスフォーム後ベクトルを取得し、視線ベクトルを反映するための法線として使用する。視線ベクトルは、常にコンスタント カラー c0 である。その後、命令は、処理の結果を、そのステージで設定されているキューブ テクスチャを参照するためのアドレスとして使用する。スペキュラ環境マップはプリロードされている。

tex t0                  ; 標準的な 3 ベクトルとして t0 を定義
texm3x3pad t1, t0       ; 行列の第 1 行の乗算を実行
texm3x3pad t2, t0       ; 行列の第 2 行の乗算を実行
texm3x3spec t3, t0, c0  ; 行列の第 3 行の乗算を実行し、
                        ; 反射計算を行い、テクスチャ 3 をサンプルする
mov r0, t3              ; 最終結果を出力色としてコピー

バンプ (通常の) マップはステージ 0 で設定される必要があり、キューブ テクスチャはステージ 3 で設定される必要がある。ステージ 1 または 2 で設定されるテクスチャはいずれも無視される。

設定 0 のテクスチャ座標はバンプ マップに位置する。1、2、および 3 を設定するテクスチャ座標は 3 × 3 行列の行である。

この命令は、このテクスチャ ステージに対応する割り当て済みのテクスチャである無名の入力を取ることに注意すること。

参照

texm3x3vspec


texm3x3tex

最後の 3 × 3 行列乗算の結果を返す。

texm3x3tex   tDest, tSrc0
tDest
処理の結果を保持するデスティネーション レジスタ。
tSrc0
入力引数を指定するテンポラリ ソース レジスタ。

注意

texm3x3tex 命令は、ピクセル シェーダのテクスチャ宣言において実行される 3 × 3 行列乗算処理を表す 3 つの命令の最後のものとして使われる。この命令の結果には、命令を実行した結果生じるトランスフォームされたベクトルが含まれる。この宣言に対する入力引数には、行列の乗算に対する入力を指定しなければならない。このステージに割り当てられたテクスチャ座標は、行列の行として使用される。

3 × 3 行列は、このステージおよび前の 2 つのステージのテクスチャ座標で構成されている。結果として得られる 3 要素ベクトルを使い、このステージで割り当てられているテクスチャ (キューブ テクスチャまたはボリューム テクスチャ) にインデックスを設定して、最終的な色を生成する。前の 2 つのステージからはテクスチャ カラーはサンプリングされず、これらのステージに割り当てられていた演算子はすべて無効になる。

tex t0             ; 標準的な 3 ベクトルとして t0 を定義
texm3x3pad t1, t0  ; 行列の第 1 行の乗算を実行
texm3x3pad t2, t0  ; 行列の第 2 行の乗算を実行
texm3x3tex t3, t0  ; 行列の第 3 行の乗算を実行

dp3 r0, t0, v0     ; v0 を使ってディフューズ ライティング強度を計算

バンプ (通常の) マップはステージ 0 で設定される必要があり、キューブ テクスチャはステージ 3 で設定される必要がある。ステージ 1 または 2 で設定されるテクスチャはいずれも無視される。

設定 0 のテクスチャ座標はバンプ マップに位置する。1、2、および 3 を設定するテクスチャ座標は 3 × 3 行列の行である。

この命令は、このテクスチャ ステージに対応する割り当て済みのテクスチャである無名の入力を取ることに注意すること。


texm3x3vspec

視点ベクトルが固定していないときのスペキュラ反射および環境マッピングを行う。

texm3x3vspec   tDest, tSrc0

レジスタ

tDest
処理の結果を保持するデスティネーション レジスタ。
tSrc0
入力引数を指定するソース レジスタ。

注意

この命令はテクスチャ アドレッシングに使用する。行列の行として使われる 3 つのテクスチャ座標の w 要素から視線が取得される点を除き、この命令の動作は texm3x3spec とまったく同じである。

tex t0               ; 標準的な 3 ベクトルとして t0 を定義
texm3x3pad t1, t0    ; 行列の第 1 行の乗算を実行
texm3x3pad t2, t0    ; 行列の第 2 行の乗算を実行
texm3x3vspec t3, t0  ; 行列の第 3 行の乗算を実行し、
                     ; テクスチャ 2 をサンプルし、反射計算を行い、
                     ; テクスチャ 3 をスペキュラ マップとしてサンプル
mov r0.rgb, t3       ; スペキュラ色を結果に入れる
mov r0.a,   t3       ; ディフーズ色をアルファ チャネルに入れる

バンプ (通常の) マップはステージ 0 で設定される必要があり、キューブ テクスチャはステージ 3 で設定される必要がある。ステージ 1 または 2 で設定されるテクスチャはいずれも無視される。

設定 0 のテクスチャ座標はバンプ マップに位置する。1、2、および 3 を設定するテクスチャ座標は 3 × 3 行列の行である。

この命令は、このテクスチャ ステージに対応する割り当て済みのテクスチャである無名の入力を取ることに注意すること。

参照

texm3x3spec


texreg2ar

指定された入力色ベクトルのアルファ成分と赤成分で指定される 2D 座標で、このステージのテクスチャをサンプリングする。

texreg2ar tDest, tSrc0

レジスタ

tDest
処理の結果を保持するデスティネーション レジスタ。
tSrc0
入力引数を指定するテンポラリ ソース レジスタ。

注意

この命令は、色空間の再マッピング処理で便利である。

この命令は、このテクスチャ ステージに対応する割り当て済みのテクスチャである無名の入力を取ることに注意すること。


texreg2gb

指定された入力色ベクトルの緑成分と青成分で指定される 2D 座標で、このステージのテクスチャをサンプリングする。

texreg2gb tDest, tSrc0

レジスタ

tDest
処理の結果を保持するデスティネーション レジスタ。
tSrc0
入力引数を指定するテンポラリ ソース レジスタ。

注意

この命令は、色空間の再マッピング処理で便利である。

この命令は、このテクスチャ ステージに対応する割り当て済みのテクスチャである無名の入力を取ることに注意すること。


修飾子

Direct3DX ピクセル シェーダ アセンブラでは、次のタイプの修飾子がサポートされている。

  • 引数修飾子
  • 命令修飾子


引数修飾子

Direct3DX ピクセル シェーダ アセンブラは、命令引数 (オペランド) および命令で処理される前の入力引数に影響する修正子フラグを取ることができる。入力引数修飾子には 2 つのタイプがある。色およびアルファ ブレンディング入力引数修飾子とテクスチャ アドレッシング入力引数修飾子である。

入力引数修飾子は、次の表で定義されている。rn. は入力引数 (レジスタ) である。

命令 | 構文 | 説明
アルファ複製 | rn.a | アルファ チャネルをすべての色に複製する。
補数 | 1-rn | 補数を計算する (y = 1.0 - x)。符号なし x が必要。
正負の反転 | -rn | 値の正負を反転する (y = -x)。符号付き x が必要。
バイアス | rn_bias | 値を ｽ 下にシフトする。y = (x-0.5)。
符号化スケーリング | rn_bx2 | 値を下にシフトし、データを 2 倍にスケーリングする。y = 2*(x-0.5)。

たとえば、lrp 命令は、入力引数修飾子を使って実装できる。

; ディフューズ アルファを使って、r0 と t0 ブレンドすると、
lrp r0, v0.a, r0, t0
; (より多くのクロックを使って) 次のように書き込むことができる。
sub r0, r0, t0
mad r0, t0, v0.a, r0

頂点シェーダとは異なり、ピクセル シェーダは成分の入れ換えをサポートしていない。x、y、および z の各要素はまとめて RGB 色成分として扱われて、w 要素は個別に転送できるアルファとして扱われる。


アルファ複製

rn.a

命令を処理する前に、影響を受けるレジスタのアルファ チャネルを、すべてのカラー チャネルに複製する。

次の例は、この修飾子の使い方を示している。

mul r0, r0, r1.a    ; アルファ チャネルで乗算 (グレースケール)
                    ; 色の強度だけを変化

この演算子は補数または正負の反転演算子と組み合わせて使用できることに注意すること。この演算子の機能は、Microsoft® DirectX® 6.0 および 7.0 マルチテクスチャ構文の D3DTA_ALPHAREPLICATE フラグに似ている。

この修飾子は、色およびアルファ ブレンディング命令で使用するためのものである。


補数

1-rn

指定されたレジスタの各チャネルで色の補数を計算する。

次の例は、この修飾子の使い方を示している。

mul r0, r0, 1-r1    ; (1.0 - r1) で乗算する。

入力データが符号なしの場合、つまり 0 から 1 の範囲にある場合、この修飾子はあらかじめ定義されている結果のみ生成する。この処理は、同じ引数にその他すべての修飾子が提示された後で実行される。

この愁傷子は、符号なしデータについてのみ機能することに注意すること。この命令には、バイアス、符号化スケーリング、および正負の反転修飾子との整合性がないので、同じレジスタでこれらの修飾子と同時に使用することはできない。

この修飾子は、色およびアルファ ブレンディング命令で使用するためのものである。


正負の反転

rn

符号の反転 (y = -x) を実行する。つまり、命令で値を使用する前に正負を反転する。

次の例は、この修飾子の使い方を示している。

mul r0, r0, -v1    ; マイナスのスペキュラ色で乗算する。

この処理は、同じ引数に対するほかの修飾子の後に実行される。

補数 (1-rn)と正負の反転 (-rn) は相互に排他的であり、同じレジスタに適用することはできない。

この修飾子は、色およびアルファ ブレンディング命令で使用するためのものである。


バイアス

rn_bias

各チャネルを 1/2 下にシフトする。したがって、レジスタを処理する前に、y = (x-0.5) を実行する。

次の例は、この修飾子の使い方を示している。

add r0, r0, t0_bias    ; 0.5 シフト ダウン

この例では、add を使って、Microsoft® DirectX® 6.0 および 7.0 のマルチテクスチャ構文の D3DTOP_ADDSIGNED と同じ処理を実行する方法を示している。

この修飾子は、0 ～ 1 の範囲にあるデータを -0.5 ～ 0.5 の範囲になるように変更することと同じ効果がある。これは、一般的に詳細なテクスチャを適用するために使用される。また、入力データを符号付きの数値として処理し、範囲が -1 ～1 に制限されている実装環境でオーバーフロー クランプが発生する前に、動的範囲を保持することもできる。

この修飾子は補数と相互に排他的であるため、同じレジスタに適用することはできない。

この修飾子は、色およびアルファ ブレンディング命令で使用するためのものである。


符号化スケーリング

rn_bx2

色およびアルファ ブレンディング命令と共に使用する場合、この修飾子は、命令が実行される前に、各チャネルから 0.3 を減算し、その結果を 2.0 倍にスケーリングする。つまり、y = (x-0.5)*2 を実行する。

次の例は、この修飾子の使い方を示している。

dp3_sat r0, t1_bx2, v0_bx2    ; ディフューズ色 v0 にライト方向、
                              ; TL にバンプ法線を仮定した、パーピクセル
                              ; ライティング / バンプ マッピング

この修飾子は、0 から 1 までの範囲にあるデータを再マッピングして、-1 から 1 までの範囲にある符号付きデータにする。これにより、以降のデータ処理では実装の完全な符号付き動的範囲を使用できる。

この修飾子は、一般的に、内積命令 (dp3) への入力について使用される。

この修飾子は補数と相互に排他的であるため、同じレジスタに適用することはできない。

テクスチャ レジスタ宣言に対する入力引数では _bx2 修飾子をサポートしており、dp3、texm3x2tex、および texm3x3tex 処理の宣言/命令の実行中に行う追加の処理を指定できる。その他のテクスチャ アドレッシング演算子は、_bx2 入力引数修飾子をサポートしていない。

入力レジスタ引数を使用する前にバイアスおよびスケーリングの処理が必要があることを指定するには、入力レジスタ引数に _bx2 を追加する。

tex t0            ; テクスチャ カラーを読み込む。
dp3 t1, t0_bx2    ; このステージのテクスチャ座標で内積を計算する。

これは、入力レジスタを指定された演算子で使用する前に、入力レジスタに対して演算 y = 2(x - 0.5) を実行する。この演算は一般的に、-1 ～ 1 の範囲にある符号付きの値を含むように意図されているデータを平行移動するために使用されるが、ソースがこの演算をサポートできないので、実行しない。このようなデータ ソースには、テクスチャ (tn)、補間色 (vn)、テクスチャ座標、または固定要素レジスタ (cn) がある。

この修飾子は、色およびアルファ ブレンディング命令と、テクスチャ アドレッシング命令の両方で使用するためのものである。


命令修飾子

Direct3DX ピクセル シェーダ アセンブラは、シフト/スケーリング修正子フラグ、および生成される出力結果に影響する彩度修正子フラグをサポートしている。命令修飾子は、次の順序で命令処理と結び付く。

  1. 補数を実行する。
  2. バイアスを適用する。
  3. 結果にスケーリングを適用する。
  4. クランプを実行する。

シフト/スケーリング修飾子を使うと、結果の大きさをある範囲内で変更できる。

名前 | 修飾子
_x2 | 2 で乗算した結果
_x4 | 4 で乗算した結果
_d2 | 2 で除算した結果

さらに、色およびアルファ ブレンディング命令と、テクスチャ アドレッシング命令の両方で使用するために、彩度修飾子 (_sat) が用意されている。

色およびアルファ ブレンディング命令の場合、彩度修飾子は、この命令の結果を各成分について 0.0 ～ 1.0 の範囲にクランプする。次の例は、この修飾子の使い方を示している。

dp3_sat r0, t0_bx2, v0_bx2    ; t0 はバンブ、v0 はライト方向

この処理は、スケーリング命令修飾子の後で実行される。これは、通常、内積の結果をクランプするために使用される。ただし、フレーム バッファが常に 0 ～ 1 の範囲にあるマルチパス メソッドと、彩度が各ステージで行われるように定義されている Microsoft® DirectX 6.0 および 7.0 のマルチテクスチャ構文で、一貫性のあるエミュレーションを実行できる。

テクスチャ アドレッシング命令の場合、彩度修飾子を処理に追加し、終了時の処理の結果を 0.0 ～ 1.0 の色の範囲にクランプするように指定できる。これは、一般的に、ライティング処理で使用する必要がある。次の例は、この修飾子の使い方を示している。

ps.1.0                       ; DirectX8 バージョン
tex t0                       ; テクスチャ カラーを読み込む
dp3_sat t1, t0_bx2, v0_bx2   ; テクスチャ座標とクランプで内積を計算

次の add 命令は、ソース オペランド (s0 と s1) の 2 つの色を加えたものをデスティネーション レジスタ (d) にロードし、結果に 2 を掛けている。

add_x2   d, s0, s1

次の add 命令は、ソース オペランド (s0 と s1) の 2 つの色を加えたものをデスティネーション レジスタ (d) にロードし、結果を各成分について 0.0 ～ 1.0 の範囲にクランプしている。

add_sat   d, s0, s1

次の add 命令は、ソース オペランド (s0 と s1) の 2 つの色を加えたものをデスティネーション レジスタ (d) にロードし、結果を 2 倍してから、各成分について結果を 0.0 ～ 1.0 の範囲にクランプしている。

add_2x_sat   d, s0, s1


出力書き込みマスク

Direct3DX ピクセル シェーダ コンパイラでサポートされている出力マスクは、この結果が結果の色またはアルファ成分のいずれかを更新しなければならないかどうか、およびその処理に色またはアルファ パイプラインを使うかどうかを指定するために使用される。これらの出力マスクは、Microsoft® DirectX 6.0 および 7.0 マルチテクスチャ ブレンディングの個別の色およびアルファ処理に似ている。

これらのフラグは頂点シェーダでサポートされているフラグほど一般的ではない。これは、rgb 成分が常に 1 つのフラグにグループ化されるため、.a と .rgb の 2 種類のマスクしか存在しないからである。

次の出力書き込みマスクがサポートされている。

  • 色/ベクトル書き込みマスク
  • アルファ/スカラー書き込みマスク
  • 完全書き込みマスク

テクスチャ アドレッシング命令では、出力書き込みマスクはサポートされていないことに注意すること。これらの処理は、常にデスティネーション レジスタの 4 つの成分を更新するので、r、g、b を分割できない。

ピクセル シェーダは、任意の入れ換えをサポートしておらず、色およびアルファ処理のみサポートしている。


色/ベクトル書き込みマスク

.rgb

出力レジスタについて指定した場合、このフラグは、処理でデスティネーション レジスタの 3 つのカラー チャネルだけを更新することを指定するので、命令の色 (ベクトル) パイプラインで実行する必要がある。

次の例は、この出力書き込みマスクの使い方を示している。

mul r0.rgb,  t0, v0
add r0.a,    t1, v1


アルファ/スカラー書き込みマスク

.a

デスティネーション レジスタについて指定した場合、このフラグは、処理でデスティネーション レジスタのアルファ チャネルだけを更新することを指定するので、この命令のアルファ (スカラー) パイプラインで実行する必要がある。

次の例は、この出力書き込みマスクの使い方を示している。

mul r0.rgb,  t0, v0
add r0.a,    t1, v1


完全書き込みマスク

.rgba

色およびアルファ チャネルの両方に同じ命令を適用することを要求する。これはデフォルトであり、これと同じ結果を得るために出力マスクを指定する必要はない。

たとえば、次の命令

mul r0, t0, v0

は、次の命令と同じであり、

mul r0.rgba, t0, v0

次の命令とも同じである。

  mul r0.rgb, t0, v0
+ mul r0.a,   t0, v0

この最後の構文でも、スカラー パイプラインとベクトル パイプラインをペアにしているため、1 クロックしか使用しない。詳細については、「ピクセル シェーダの命令のペア」を参照すること。


エフェクト ファイル形式

ここでは、エフェクト ファイル形式に関するリファレンス情報について説明する。エフェクト ファイルは、パラメータ宣言と、さまざまな手法の記述によって構成される。

  • パラメータの型
  • 定数値の構文
  • 頂点シェーダ宣言の構文
  • 有効なステートの一覧
  • エフェクト ファイルのサンプル

手法は、次の構文に従って記述する。id は有効な FourCC コードでなければならないことに注意する。FourCC コードについては、「FOURCC コード.」を参照すること。

  • 各種宣言を記述した後で手法を記述する。
  • 手法の記述には 1 つ以上のパスを含める。
  • パスには 1 つ以上のステート指定を含める。
  • ステートは、定数値またはパラメータのいずれかに指定できる。
{type} {id};
{type} {id} = {const};

TECHNIQUE {id}
{
    PASS {id}
    {
        {state}      = {const};
        {state}[{n}] = {const};
        {state}      = <{id}>;
        {state}[{n}] = <{id}>;
    }
}


パラメータの型

パラメータ宣言は、次の構文に従う。type は有効な型、id は有効な FOURCC コードである。const 値をパラメータの初期値として指定する場合、その型はtype と一致している必要がある。

{type} {id};
{type} {id} = {const};

次の表は、サンプルのほか、エフェクト ファイルのパラメータ宣言で使用する有効なパラメータの型を示している。

型 サンプル
DWORD
DWORD minVertices;
FLOAT
FLOAT fRotationAdvances;
VECTOR
VECTOR vecPoint;
MATRIX
MATRIX matIndentity;
TEXTURE
TEXTURE tex1;
VERTEXSHADER
VERTEXSHADER v1;
PIXELSHADER
PIXELSHADER p1;


定数値の構文

次の表は、定数値およびサンプルの有効な構文を示している。

型 構文
DWORD
#

0x#

54573153

0xff12a1fa
FLOAT
#f

#.f
.#f
#.#f

5f

5.f
.4f
4.5f
VECTOR
(float)

(float, float)
(float, float, float)
(float, float, float, float)

( 4.5f )

( 4.5f, 1.0f )
( 4.5f, 1.0f, 2.0f )
( 4.5f, 1.0f, 2.0f, 3.4f )
MATRIX
[ float, float, float, float,

  float, float, float, float,
  float, float, float, float,
  float, float, float, float ]

[ 1.0f, 0.0f, 0.0f, 0.0f,

  0.0f, 1.0f, 0.0f, 0.0f,
  0.0f, 0.0f, 1.0f, 0.0f,
  0.0f, 0.0f, 0.0f, 1.0f ]
VERTEXSHADER
DECL { ... }

DECL { ... }, ASM { ... }

decl

{
   stream 0;
   float v0[3];
   float v3[3];
   ubyte v5[4];
   float v7[2];
}

decl
{
   stream 0;
   float v0[3];
   float v3[3];
   ubyte v5[4];
   float v7[2];
}
asm
{
   vs.1.0
   mov oPos, v0
}
PIXELSHADER
ASM { ... }

asm

{
   ps.1.0
   tex t0
   mov r0, t0
}

DECL 構文のレイアウトについては、「頂点シェーダ宣言の構文」を参照すること。

ASM 構文のレイアウトについては、「ピクセル シェーダ アセンブラ リファレンス」を参照すること。


頂点シェーダ宣言の構文

DECL
{
    STREAM n;
    SKIP n;
    FVF a|b|c;

    type v#;
    type v#[n];
}

次の表は、上の構文で使用する値の型を示している。

構文 | 説明
a|b|c | 複数の DWORD と柔軟なベクトル形式フラグから構成できる DWORD 表現。FVF を使用するには、D3DFVF_ prefix を取り除く。
Type | 次の型のいずれか。UBYTE、SHORT、FLOAT、D3DCOLOR。
v# | 有効な頂点シェーダ入力レジスタ。FVF フラグおよび対応する頂点シェーダ入力レジスタを示す、下の表を参照すること。
n | 1 から 4 までの数値。

次の表は、FVF コードおよび対応する頂点シェーダ入力レジスタを示している。

FVF | 名前 | レジスタ番号
D3DFVF_XYZ | D3DVSDE_POSITION | 0
D3DFVF_XYZRHW | D3DVSDE_BLENDWEIGHT | 1
D3DFVF_XYZB1 から D3DFVF_XYZB5 | D3DVSDE_BLENDINDICES | 2
D3DFVF_NORMAL | D3DVSDE_NORMAL | 3
D3DFVF_PSIZE | D3DVSDE_PSIZE | 4
D3DFVF_DIFFUSE | D3DVSDE_DIFFUSE | 5
D3DFVF_SPECULAR | D3DVSDE_SPECULAR | 6
D3DFVF_TEX0 | D3DVSDE_TEXCOORD0 | 7
D3DFVF_TEX1 | D3DVSDE_TEXCOORD1 | 8
D3DFVF_TEX2 | D3DVSDE_TEXCOORD2 | 9
D3DFVF_TEX3 | D3DVSDE_TEXCOORD3 | 10
D3DFVF_TEX4 | D3DVSDE_TEXCOORD4 | 11
D3DFVF_TEX5 | D3DVSDE_TEXCOORD5 | 12
D3DFVF_TEX6 | D3DVSDE_TEXCOORD6 | 13
D3DFVF_TEX7 | D3DVSDE_TEXCOORD7 | 14
 | D3DVSDE_POSITION2 | 15
 | D3DVSDE_NORMAL2 | 16


有効なステートの一覧

次のトピックでは、エフェクト ファイルを作成する際に使用できる有効なすべてのステートについて説明する。

型 DWORD のステートを設定するときは、列挙値を使用できる。たとえば、通常 SrcBlend は D3DBLEND_xxx 列挙型を使用して設定される。したがって、これらの列挙型を使用して指定することができる。次のコードに示すように、D3DBLEND_ prefix を取り除くのみである。

SrcBlend = One;

これらの値は、"OR" 式でまとめて指定することもできる。

TextureTransformFlags[0] = Count3 | Projected;

次の表は、エフェクト ファイルで使用する有効なレンダリング ステートを示している。

型 | レンダリング ステート | 有効な値
DWORD | ZEnable | D3DZB
DWORD | FillMode | D3DFILL
DWORD | ShadeMode | D3DSHADE
DWORD | LinePattern |
DWORD | ZWriteEnable | TRUE/FALSE
DWORD | AlphaTestEnable | TRUE/FALSE
DWORD | LastPixel | TRUE/FALSE
DWORD | SrcBlend | D3DBLEND
DWORD | DestBlend | D3DBLEND
DWORD | CullMode | D3DCULL
DWORD | ZFunc | D3DCMP
DWORD | AlphaRef |
DWORD | AlphaFunc | D3DCMP
DWORD | DitherEnable | TRUE/FALSE
DWORD | AlphaBlendEnable | TRUE/FALSE
DWORD | FogEnable | TRUE/FALSE
DWORD | SpecularEnable | TRUE/FALSE
DWORD | ZVisible | TRUE/FALSE
DWORD | FogColor |
DWORD | FogTableMode | D3DFOG
FLOAT | FogStart |
FLOAT | FogEnd
FLOAT | FogDensity
DWORD | EdgeAntialias | TRUE/FALSE
DWORD | Zbias |
DWORD | RangeFogEnable
DWORD | StencilEnable | TRUE/FALSE
DWORD | StencilFail | D3DSTENCILOP
DWORD | StencilZFail | D3DSTENCILOP
DWORD | StencilPass | D3DSTENCILOP
DWORD | StencilFunc | D3DCMP
DWORD | StencilRef |
DWORD | StencilMask
DWORD | StencilWriteMask
DWORD | TextureFactor
DWORD | Wrap0 | D3DWRAP
DWORD | Wrap1 | D3DWRAP
DWORD | Wrap2 | D3DWRAP
DWORD | Wrap3 | D3DWRAP
DWORD | Wrap4 | D3DWRAP
DWORD | Wrap5 | D3DWRAP
DWORD | Wrap6 | D3DWRAP
DWORD | Wrap7 | D3DWRAP
DWORD | Clipping | TRUE/FALSE
DWORD | Lighting | TRUE/FALSE
DWORD | Ambient |
DWORD | FogVertexMode
DWORD | ColorVertex | TRUE/FALSE
DWORD | LocalViewer | TRUE/FALSE
DWORD | NormalizeNormals | TRUE/FALSE
DWORD | DiffuseMaterialSource | D3DMCS
DWORD | SpecularMaterialSource | D3DMCS
DWORD | AmbientMaterialSource | D3DMCS
DWORD | EmissiveMaterialSource | D3DMCS
DWORD | VertexBlend | D3DVBF
DWORD | ClipPlaneEnable | TRUE/FALSE
DWORD | SoftwareVertexProcessing | TRUE/FALSE
FLOAT | PointSize |
FLOAT | PointSize_Min
FLOAT | PointSize_Max
DWORD | PointSpriteEnable | TRUE/FALSE
DWORD | PointScaleEnable | TRUE/FALSE
FLOAT | PointScale_A |
FLOAT | PointScale_B
FLOAT | PointScale_C
DWORD | MultiSampleAntialias | TRUE/FALSE
DWORD | MultiSampleMask |
DWORD | PatchSegments
DWORD | IndexedVertexBlendEnable | TRUE/FALSE
DWORD | ColorWriteEnable | TRUE/FALSE
FLOAT | TweenFactor |
DWORD | BlendOp | D3DBLENDOP

次の表は、エフェクト ファイルで使用する有効なテクスチャ ステージ ステートを示している。

型 | テクスチャ ステージ ステート | 有効な値
DWORD | ColorOp[8] | D3DTOP
DWORD | ColorArg0[8] | D3DTA
DWORD | ColorArg1[8] | D3DTA
DWORD | ColorArg2[8] | D3DTA
DWORD | AlphaOp[8] | D3DTOP
DWORD | AlphaArg0[8] | D3DTA
DWORD | AlphaArg1[8] | D3DTA
DWORD | AlphaArg2[8] | D3DTA
DWORD | ResultArg[8] | D3DTA
DWORD | BumpEnvMat00[8] |
DWORD | BumpEnvMat01[8]
DWORD | BumpEnvMat10[8]
DWORD | BumpEnvMat11[8]
DWORD | TexCoordIndex[8] | D3DTSS_TCI
DWORD | AddressU[8] | D3DTADDRESS
DWORD | AddressV[8] | D3DTADDRESS
DWORD | AddressW[8] | D3DTADDRESS
DWORD | BorderColor[8] |
DWORD | MagFilter[8] | D3DTEXF
DWORD | MinFilter[8] | D3DTEXF
DWORD | MipFilter[8] | D3DTEXF
DWORD | MipMapLodBias[8] |
DWORD | MaxMipLevel[8]
DWORD | MaxAnsiotropy[8]
FLOAT | BumpEnvLScale[8]
FLOAT | BumpEnvLOffset[8]
DWORD | TextureTransformFlags[8] | D3DTTFF

次の表に、エフェクト ファイルで使用するライティング ステートの一覧を示す。エフェクトにライティング ステートを設定する場合は、ライトを完全に記述するために必要なすべてのステートを設定しなければならない。D3DX は個別にライティング ステートを設定できないため、宣言に失敗したステートにはデフォルト値が設定される。

型 | ライティング ステート | 有効な値
DWORD | LightType[n] | D3DLT
VECTOR | LightDiffuse[n] |
VECTOR | LightSpecular[n]
VECTOR | LightAmbient[n]
VECTOR | LightPosition[n]
VECTOR | LightDirection[n]
FLOAT | LightRange[n]
FLOAT | LightFalloff[n]
FLOAT | LightAttenuation0[n]
FLOAT | LightAttenuation1[n]
FLOAT | LightAttenuation2[n]
FLOAT | LightTheta[n]
FLOAT | LightPhi[n]
DWORD | LightEnable[n] | TRUE/FALSE

次の表に、エフェクト ファイルで使用する有効なマテリアル ステートの一覧を示す。エフェクトにマテリアル ステートを設定する場合は、マテリアルを完全に記述するために必要なすべてのステートを設定しなければならない。D3DX は個別にマテリアル ステートを設定できないため、宣言に失敗したステートにはデフォルト値が設定される。

型 | マテリアル ステート
VECTOR | MaterialDiffuse
VECTOR | MaterialAmbient
VECTOR | MaterialSpecular
VECTOR | MaterialEmissive
FLOAT | MaterialPower

次の表は、エフェクト ファイルで使用するその他の有効なステートを示している。

型 | ステート
VERTEXSHADER | VertexShader
PIXELSHADER | PixelShader
CONSTANT | VertexShaderConstant[n]
CONSTANT | PixelShaderConstant[n]
TEXTURE | Texture[8]
MATRIX | ProjectionTransform
MATRIX | ViewTransform
MATRIX | WorldTransform[256]
MATRIX | TextureTransform[8]


エフェクト ファイルのサンプル

次に示すのは、標準的なエフェクト ファイルの基本構文およびレイアウトである。

//
// サンプル エフェクト。
// このエフェクトは、シングル パス手法またはマルチパス手法を使用して、2 つのテクスチャを追加する。
//

texture tex0;
texture tex1;

// シングル パス。

technique t0
{
    pass p0
    {
        Texture[0] = <tex0>;
        Texture[1] = <tex1>;

        ColorOp[0] = SelectArg1;
        ColorArg1[0] = Texture;

        ColorOp[1] = Add;
        ColorArg1[0] = Texture;
        ColorArg2[0] = Current;

        ColorOp[2] = Disable;
    }
}

// マルチパス。

technique t1
{
    pass p0
    {
        Texture[0] = <tex0>;

        ColorOp[0] = SelectArg1;
        ColorArg1[0] = Texture;
        ColorOp[1] = Disable;
    }

    pass p1
    {
        AlphaBlendEnable = True;
        SrcBlend = One;
        DestBlend = One;

        Texture[1] = <tex1>;

        ColorOp[1] = SelectArg1;
        ColorArg1[1] = Texture;
        ColorOp[1] = Disable;
    }
}


X ファイル C/C++ リファレンス

ここでは、Microsoft® DirectX® (.x) のファイルを扱うために使用される API 要素のリファレンス情報を記述する。

  • インターフェイス
  • 関数
  • 構造体
  • 戻り値


インターフェイス

ここでは、Microsoft® DirectX® (.x) のファイルに対する読み書きで使用される COM インターフェイスのリファレンス情報を記述する。

  • IDirectXFile
  • IDirectXFileBinary
  • IDirectXFileData
  • IDirectXFileDataReference
  • IDirectXFileEnumObject
  • IDirectXFileObject
  • IDirectXFileSaveObject


IDirectXFile

IDirectXFileEnumObject インターフェイスおよび IDirectXFileSaveObject インターフェイスのインスタンスを作成し、テンプレートを登録するには、IDirectXFile インターフェイスのメソッドを使用する。

IDirectXFile インターフェイスを取得するには、DirectXFileCreate 関数を呼び出す。

IDirectXFile インターフェイスのメソッドは、以下のグループにまとめることができる。

作成 | CreateEnumObject
 | CreateSaveObject
テンプレート | RegisterTemplates

すべての COM インターフェイスと同様、IDirectXFile インターフェイスは IUnknown インターフェイスのメソッドを継承する。IUnknown インターフェイスは、次の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

IDirectXFile インターフェイスのグローバル ユニーク識別子 (GUID) は IID_IDirectXFile である。

動作環境

ヘッダー : dxfile.h で宣言。
インポート ライブラリ : d3dxof.lib を使用。


IDirectXFile::CreateEnumObject

列挙オブジェクトを作成する。

HRESULT CreateEnumObject(
  LPVOID pvSource,
  DXFILELOADOPTIONS dwLoadOptions,
  LPDIRECTXFILEENUMOBJECT* ppEnumObj
);

パラメータ

pvSource
[out] dwLoadOptions の値によって内容が異なるデータへのポインタ。
dwLoadOptions
[in] データのソースを指定する値。この値には、次のフラグのいずれかを指定できる。
DXFILELOAD_FROMFILE
ファイルからデータを読み取ることを示す。pvSource の値はファイルの名前である。
DXFILELOAD_FROMRESOURCE
リソースからデータを読み取ることを示す。pvSource の値は DXFILELOADRESOURCE 構造体である。
DXFILELOAD_FROMMEMORY
メモリからデータを読み取ることを示す。pvSource の値は DXFILELOADMEMORY 構造体である。
DXFILELOAD_FROMSTREAM
ストリームからデータを読み取ることを示す。現在はサポートされていない。
DXFILELOAD_FROMURL
URL からデータを読み取ることを示す。pvSource の値は URL の名前である。
ppEnumObj
[out] 作成された列挙オブジェクトを表す IDirectXFileEnumObject インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、DXFILE_OK を返す。

失敗した場合は、次のいずれかの値を返す。

DXFILEERR_BADALLOC
DXFILEERR_BADFILEFLOATSIZE
DXFILEERR_BADFILETYPE
DXFILEERR_BADFILEVERSION
DXFILEERR_BADRESOURCE
DXFILEERR_BADVALUE
DXFILEERR_FILENOTFOUND
DXFILEERR_RESOURCENOTFOUND
DXFILEERR_URLNOTFOUND

注意

このメソッドを使用した後は、IDirectXFileEnumObject メソッドの 1 つを使用し、データ オブジェクトを取得する。

動作環境

ヘッダー : dxfile.h で宣言。
インポート ライブラリ : d3dxof.lib を使用。

参照

IDirectXFileEnumObject


IDirectXFile::CreateSaveObject

保存オブジェクトを作成する。

HRESULT CreateSaveObject(
  LPCSTR szFileName,
  DXFILEFORMAT dwFileFormat,
  LPDIRECTXFILESAVEOBJECT* ppSaveObj
);

パラメータ

szFileName
[in] データを保存するために使用するファイルの名前へのポインタ。
dwFileFormat
[in] Microsoft® DirectX® のファイルを保存するときに使用するフォーマットを指定する。詳細については、「注意」を参照すること。
DXFILEFORMAT_BINARY
バイナリ ファイルを示す。
DXFILEFORMAT_COMPRESSED
圧縮ファイルを示す。
DXFILEFORMAT_TEXT
テキスト ファイルを示す。
ppSaveObj
[out, retval] 作成された保存オブジェクトを表す IDirectXFileSaveObject インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、DXFILE_OK を返す。

失敗した場合は、次のいずれかの値を返す。

DXFILEERR_BADALLOC
DXFILEERR_BADFILE
DXFILEERR_BADVALUE

注意

このメソッドを使用した後は、IDirectXFileSaveObject インターフェイスのメソッドを使用してデータ オブジェクトを作成し、テンプレートまたはデータを保存する。

ファイル フォーマットのデフォルト値は DXFILEFORMAT_BINARY である。ファイル フォーマットの値を論理和で結合し、圧縮テキスト ファイルまたは圧縮バイナリ ファイルを作成できる。バイナリ (0) とテキスト (1) の両方を指定した場合は、テキスト ファイル フォーマットの値と区別がつかないため (0 + 1 = 1)、テキスト ファイルとして保存される。ファイル フォーマットとしてテキストかつ圧縮を指定すると、ファイルは最初にテキストとして書き込まれた後、圧縮される。ただし、圧縮テキスト ファイルはバイナリ テキスト ファイルほど効率がよくないので、ほとんどの場合は、バイナリかつ圧縮を指定する必要がある。フォーマットを指定しないでファイルを圧縮するように設定すると、バイナリ圧縮ファイルが作成される。

動作環境

ヘッダー : dxfile.h で宣言。
インポート ライブラリ : d3dxof.lib を使用。

参照

IDirectXFileSaveObject


IDirectXFile::RegisterTemplates

カスタム テンプレートを登録する。

HRESULT RegisterTemplates(
  LPVOID pvData,
  DWORD cbSize
);

パラメータ

pvData
[in] テンプレートを含むテキスト フォーマットまたはバイナリ フォーマットの Microsoft® DirectX® ファイルを構成するバッファへのポインタ。
cbSize
[in] pvData によって示されるバイト単位のバッファ サイズ。

戻り値

成功した場合は、DXFILE_OK を返す。

失敗した場合は、次のいずれかの値を返す。

DXFILEERR_BADFILEFLOATSIZE
DXFILEERR_BADFILETYPE
DXFILEERR_BADFILEVERSION
DXFILEERR_BADVALUE
DXFILEERR_PARSEERROR

注意

次のサンプル コードは、RegisterTemplates メソッドの呼び出し、および pvData が示すバッファの内容の例である。

TIDirectXFile * pDXFile;

char *szTemplates = "xof 0303txt 0032\
    template SimpleData { \
        <2b934580-9e9a-11cf-ab39-0020af71e433> \
        DWORD item1;DWORD item2;DWORD item3;} \
    template ArrayData { \
        <2b934581-9e9a-11cf-ab39-0020af71e433> \
        DWORD cItems; array DWORD aItem[2][cItems]; [...] } \
    template RestrictedData { \
        <2b934582-9e9a-11cf-ab39-0020af71e433> \
        DWORD item; [SimpleData]}";

hr = pDXFile->RegisterTemplates(szTemplates, strlen(szTemplates));

テンプレートはすべて、名前とユニバーサル ユニーク識別子 (UUID) を指定しなければならない。

動作環境

ヘッダー : dxfile.h で宣言。
インポート ライブラリ : d3dxof.lib を使用。


IDirectXFileBinary

バイナリ データを読み取ったり、バイナリ データについての情報を取得したりするには、IDirectXFileBinary インターフェイスのメソッドを使用する。

IDirectXFileBinary インターフェイスは、次のようなグループに分類できる IDirectXFileObject のメソッドを継承する。

情報 | GetId
 | GetName

IDirectXFileBinary インターフェイスのメソッドは、以下のグループにまとめることができる。

情報 | GetMimeType
 | GetSize
データの読み取り | Read

すべての COM インターフェイスと同様、IDirectXFileBinary インターフェイスは IUnknown インターフェイスのメソッドを継承する。IUnknown インターフェイスは、次の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

IDirectXFileBinary インターフェイスのグローバル ユニーク識別子 (GUID) は IID_IDirectXFileBinary である。

動作環境

ヘッダー : dxfile.h で宣言。
インポート ライブラリ : d3dxof.lib を使用。


IDirectXFileBinary::GetMimeType

バイナリ データの MIME (Multipurpose Internet Mail Extensions) タイプを取得する。

HRESULT GetMimeType(
  LPCSTR* pszMimeType
);

パラメータ

pszMimeType
[out, retval] MIME タイプの文字列を受け取るポインタのアドレス。

戻り値

成功した場合は、DXFILE_OK を返す。

失敗した場合は DXFILEERR_BADVALUE を返す。

注意

バイナリ オブジェクトに対して Microsoft® DirectX® ファイルで MIME タイプが指定されていない場合は、pszMimeType に NULL が設定される。

動作環境

ヘッダー : dxfile.h で宣言。
インポート ライブラリ : d3dxof.lib を使用。


IDirectXFileBinary::GetSize

バイナリ データのサイズを取得する。

HRESULT GetSize(
  DWORD* pcbSize
);

パラメータ

pcbSize
[out, retval] 返されるバイナリ データのサイズへのポインタ (バイト単位)。

戻り値

成功した場合は、DXFILE_OK を返す。

失敗した場合は DXFILEERR_BADVALUE を返す。

動作環境

ヘッダー : dxfile.h で宣言。
インポート ライブラリ : d3dxof.lib を使用。


IDirectXFileBinary::Read

バイナリ データを読み取る。

HRESULT Read(
  LPVOID pvData,
  DWORD cbSize,
  LPDWORD pcbRead
);

パラメータ

pvData
[out] 読み取ったデータを受け取るバッファへのポインタ。
cbSize
[in] pvData によって示されるバイト単位のバッファ サイズ。
pcbRead
[out, retval] 実際に読み取られたバイト数へのポインタ。

戻り値

成功した場合は、DXFILE_OK を返す。

失敗した場合は、次のいずれかの値を返す。

DXFILEERR_BADVALUE
DXFILEERR_NOMOREDATA

動作環境

ヘッダー : dxfile.h で宣言。
インポート ライブラリ : d3dxof.lib を使用。


IDirectXFileData

データ オブジェクトの直接階層を構築したり、直接階層にアクセスしたりするには、IDirectXFileData インターフェイスのメソッドを使用する。テンプレートの制約により階層が決まる。テンプレートによって許可されるデータ型のことを、オプション メンバと呼ぶ。オプション メンバは必須ではないが、オプション メンバがないと、オブジェクトで重要な情報が不足する場合がある。オプション メンバは、データ オブジェクトの子として保存される。子は、別のデータ オブジェクト、以前のデータ オブジェクトへの参照、またはバイナリ オブジェクトである。

IDirectXFileData インターフェイスは、次のようなグループに分類できる IDirectXFileObject のメソッドを継承する。

情報 | GetId
 | GetName

IDirectXFileData インターフェイスのメソッドは、以下のグループにまとめることができる。

データの追加 | AddBinaryObject
 | AddDataObject
 | AddDataReference
データの取得 | GetData
 | GetNextObject
 | GetType

すべての COM インターフェイスと同様、IDirectXFileData インターフェイスは IUnknown インターフェイスのメソッドを継承する。IUnknown インターフェイスは、次の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

IDirectXFileData インターフェイスのグローバル ユニーク識別子 (GUID) は IID_IDirectXFileData である。

動作環境

ヘッダー : dxfile.h で宣言。
インポート ライブラリ : d3dxof.lib を使用。


IDirectXFileData::AddBinaryObject

バイナリ オブジェクトを作成し、子オブジェクトとして追加する。

HRESULT AddBinaryObject(
  LPCSTR szName,
  const GUID* pguid,
  LPCSTR szMimeType,
  LPVOID pvData,
  DWORD cbSize
);

パラメータ

szName
[in] オブジェクトの名前へのポインタ。オブジェクトに名前が必要ない場合は、NULL を指定する。
pguid
[in] オブジェクトを表すグローバル ユニーク識別子 (GUID) へのポインタ。オブジェクトに GUID が必要ない場合は、NULL を指定する。
szMimeType
[in] オブジェクトの MIME タイプへのポインタ。
pvData
[in] オブジェクトのデータへのポインタ。
cbSize
[in] pvData によって示されるバイト単位のバッファ サイズ。

戻り値

成功した場合は、DXFILE_OK を返す。

失敗した場合は、次のいずれかの値を返す。

DXFILEERR_BADALLOC
DXFILEERR_BADVALUE

動作環境

ヘッダー : dxfile.h で宣言。
インポート ライブラリ : d3dxof.lib を使用。

参照

IDirectXFileBinary::GetMimeType


IDirectXFileData::AddDataObject

子オブジェクトとしてデータ オブジェクトを追加する。

HRESULT AddDataObject(
  LPDIRECTXFILEDATA pDataObj
);

パラメータ

pDataObj
[in] 子オブジェクトとして追加するファイル データ オブジェクトを表す IDirectXFileData インターフェイスへのポインタ。

戻り値

成功した場合は、DXFILE_OK を返す。

失敗した場合は、次のいずれかの値を返す。

DXFILEERR_BADALLOC
DXFILEERR_BADVALUE

注意

IDirectXFileSaveObject::CreateDataObject メソッドを使って IDirectXFileData オブジェクトを作成してから、このメソッドを呼び出す。

動作環境

ヘッダー : dxfile.h で宣言。
インポート ライブラリ : d3dxof.lib を使用。

参照

IDirectXFileSaveObject::CreateDataObject


IDirectXFileData::AddDataReference

データ参照オブジェクトを作成し、子オブジェクトとして追加する。

HRESULT AddDataReference(
  LPCSTR szRef,
  const GUID* pguidRef
);

パラメータ

szRef
[in] 参照されるデータ オブジェクトの名前へのポインタ。pguidRef でグローバル ユニーク識別子 (GUID) への参照を指定する場合、このパラメータに NULL を設定できる。
pguidRef
[in] データを表す GUID へのポインタ。szRef で名前への参照を指定する場合、このパラメータに NULL を設定できる。

戻り値

成功した場合は、DXFILE_OK を返す。

失敗した場合は、次のいずれかの値を返す。

DXFILEERR_BADALLOC
DXFILEERR_BADVALUE

注意

このメソッドが成功するには、パラメータ szRef と pguidRef の少なくとも一方が NULL 以外でなければならない。

動作環境

ヘッダー : dxfile.h で宣言。
インポート ライブラリ : d3dxof.lib を使用。


IDirectXFileData::GetData

オブジェクトのメンバの 1 つに対するデータ、またはすべてのメンバに対するデータを取得する。

HRESULT GetData(
  LPCSTR szMember,
  DWORD* pcbSize,
  void** ppvData
);

パラメータ

szMember
[in] データを取得するメンバの名前へのポインタ。全必須メンバのデータを取得する場合は、NULL を指定する。
pcbSize
[out] ppvData バッファのサイズを受け取るためのポインタ (バイト単位)。
ppvData
[out] szMember に関連付けられているデータを受け取るバッファへのポインタのアドレス。szMember が NULL の場合は、全必須メンバのデータが格納されている連続したメモリ ブロックのバッファへのポインタが設定される。

戻り値

成功した場合は、DXFILE_OK を返す。

失敗した場合は、次のいずれかの値を返す。

DXFILEERR_BADARRAYSIZE
DXFILEERR_BADDATAREFERENCE
DXFILEERR_BADVALUE

注意

このメソッドを使うと、データ オブジェクトの必須メンバのデータを取得できるが、オプション (子) メンバのデータは取得できない。子オブジェクトを取得するには、IDirectXFileData::GetNextObject メソッドを使用する。

動作環境

ヘッダー : dxfile.h で宣言。
インポート ライブラリ : d3dxof.lib を使用。

参照

IDirectXFileData::GetNextObject


IDirectXFileData::GetNextObject

Microsoft® DirectX® ファイル中の次の子データ オブジェクト、データ参照オブジェクト、またはバイナリ オブジェクトを取得する。

HRESULT GetNextObject(
  LPDIRECTXFILEOBJECT* ppChildObj
);

パラメータ

ppChildObj
[out, retval] IDirectXFileObject インターフェイスへのポインタのアドレス。返される子オブジェクトのファイル オブジェクト インターフェイスへのポインタが格納される。

戻り値

成功した場合は、DXFILE_OK を返す。

失敗した場合は、次のいずれかの値を返す。

DXFILEERR_BADVALUE
DXFILEERR_NOMOREOBJECTS

注意

取得されたオブジェクトの型を調べるには、QueryInterface を使って、取得されたオブジェクトが IDirectXFileData、IDirectXFileDataReference、または IDirectXFileBinary のどのインターフェイスをサポートするかを照会する。サポートされるインターフェイスが、オブジェクトの型 (データ、データ参照、またはバイナリ) を示している。

動作環境

ヘッダー : dxfile.h で宣言。
インポート ライブラリ : d3dxof.lib を使用。

参照

IDirectXFileBinary、IDirectXFileData、IDirectXFileDataReference


IDirectXFileData::GetType

オブジェクトのテンプレートのグローバル ユニーク識別子 (GUID) を取得する。

HRESULT GetType(
  const GUID** ppguid
);

パラメータ

ppguid
[out, retval] オブジェクトのテンプレートの GUID を受け取るポインタのアドレス。

戻り値

成功した場合は、DXFILE_OK を返す。

失敗した場合は DXFILEERR_BADVALUE を返す。

動作環境

ヘッダー : dxfile.h で宣言。
インポート ライブラリ : d3dxof.lib を使用。


IDirectXFileDataReference

データ参照オブジェクトをサポートするには、IDirectXFileDataReference インターフェイスのメソッドを使用する。データ参照オブジェクトは、ファイル内で既に定義されているデータ オブジェクトを参照している。データ参照オブジェクトを使うと、ファイル内で繰り返し定義しなくても、同じオブジェクトを何回でも使用できる。

IDirectXFileDataReference インターフェイスは、次のようなグループに分類できる IDirectXFileObject のメソッドを継承する。

情報 | GetId
 | GetName

すべての COM インターフェイスと同様、IDirectXFileDataReference インターフェイスは IUnknown インターフェイスのメソッドを継承する。IUnknown インターフェイスは、次の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

オブジェクトがデータ参照オブジェクトであることを判別した後、IDirectXFileDataReference::Resolve メソッドを使って、ファイル内で既に定義されている参照対象オブジェクトを取得する。

データ参照オブジェクトを識別する方法については、「IDirectXFileData インターフェイス」を参照すること。

IDirectXFileDataReference インターフェイスのグローバル ユニーク識別子 (GUID) は IID_IDirectXFileDataReference である。

動作環境

ヘッダー : dxfile.h で宣言。
インポート ライブラリ : d3dxof.lib を使用。


IDirectXFileDataReference::Resolve

データ参照を解決する。

HRESULT Resolve(
  LPDIRECTXFILEDATA* ppDataObj
);

パラメータ

ppDataObj
[out, retval] 返されるファイル データ オブジェクトを表す IDirectXFileData インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、DXFILE_OK を返す。

失敗した場合は、次のいずれかの値を返す。

DXFILEERR_BADVALUE
DXFILEERR_NOTFOUND

動作環境

ヘッダー : dxfile.h で宣言。
インポート ライブラリ : d3dxof.lib を使用。


IDirectXFileEnumObject

ファイル内のデータ オブジェクトに対する処理を繰り返し、グローバル ユニーク識別子 (GUID) または名前でデータ オブジェクトを取得するには、IDirectXFileEnumObject インターフェイスのメソッドを使用する。

IDirectXFileEnumObject インターフェイスのメソッドは、以下のグループにまとめることができる。

オブジェクトの取得 | GetDataObjectById
 | GetDataObjectByName
列挙 | GetNextDataObject

すべての COM インターフェイスと同様、IDirectXFileEnumObject インターフェイスは IUnknown インターフェイスのメソッドを継承する。IUnknown インターフェイスは、次の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

IDirectXFileEnumObject インターフェイスの GUID は、IID_IDirectXFileEnumObject である。

動作環境

ヘッダー : dxfile.h で宣言。
インポート ライブラリ : d3dxof.lib を使用。


IDirectXFileEnumObject::GetDataObjectById

指定されたグローバル ユニーク識別子 (GUID) を持つデータ オブジェクトを取得する。

HRESULT GetDataObjectById(
  REFGUID rguid,
  LPDIRECTXFILEDATA* ppDataObj
);

パラメータ

rguid
[in] 要求されたグローバル ユニーク識別子 (GUID) への参照。
ppDataObj
[out] 返されるファイル データ オブジェクトを表す IDirectXFileData インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、DXFILE_OK を返す。

失敗した場合は、次のいずれかの値を返す。

DXFILEERR_BADVALUE
DXFILEERR_NOTFOUND

動作環境

ヘッダー : dxfile.h で宣言。
インポート ライブラリ : d3dxof.lib を使用。


IDirectXFileEnumObject::GetDataObjectByName

指定された名前を持つデータ オブジェクトを取得する。

HRESULT GetDataObjectByName(
  LPCSTR szName,
  LPDIRECTXFILEDATA* ppDataObj
);

パラメータ

szName
[in] 要求する名前へのポインタ。
ppDataObj
[out] 返されるファイル データ オブジェクトを表す IDirectXFileData インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、DXFILE_OK を返す。

失敗した場合は、次のいずれかの値を返す。

DXFILEERR_BADVALUE
DXFILEERR_NOTFOUND

動作環境

ヘッダー : dxfile.h で宣言。
インポート ライブラリ : d3dxof.lib を使用。


IDirectXFileEnumObject::GetNextDataObject

Microsoft® DirectX® ファイル中にある次のトップレベル オブジェクトを取得する。

HRESULT GetNextDataObject(
  LPDIRECTXFILEDATA* ppDataObj
);

パラメータ

ppDataObj
[out] 返されるファイル データ オブジェクトを表す IDirectXFileData インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、DXFILE_OK を返す。

失敗した場合は、次のいずれかの値を返す。

DXFILEERR_BADVALUE
DXFILEERR_NOMOREOBJECTS

注意

トップレベル オブジェクトは、必ずデータ オブジェクトである。データ参照オブジェクトおよびバイナリ オブジェクトは、データ オブジェクトの子になることだけができる。

動作環境

ヘッダー : dxfile.h で宣言。
インポート ライブラリ : d3dxof.lib を使用。


IDirectXFileObject

Microsoft® DirectX® ファイル オブジェクトについての情報を取得するには、IDirectXFileObject インターフェイスのメソッドを使用する。

IDirectXFileObject インターフェイスのメソッドは、以下のグループにまとめることができる。

情報 | GetId
 | GetName

すべての COM インターフェイスと同様、IDirectXFileObject インターフェイスは IUnknown インターフェイスのメソッドを継承する。IUnknown インターフェイスは、次の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

IDirectXFileObject インターフェイスのグローバル ユニーク識別子 (GUID) は IID_IDirectXFileObject である。

動作環境

ヘッダー : dxfile.h で宣言。
インポート ライブラリ : d3dxof.lib を使用。


IDirectXFileObject::GetId

Microsoft® DirectX® ファイル オブジェクトを識別するグローバル ユニーク識別子 (GUID) へのポインタを取得する。

HRESULT GetId(
  LPGUID pGuid
);

パラメータ

pGuid
[out, retval] オブジェクトの ID を受け取るグローバル ユニーク識別子 (GUID) へのポインタ。オブジェクトが ID を持っていない場合、この関数は GUID に NULL GUID を設定する。

戻り値

成功した場合は、DXFILE_OK を返す。

失敗した場合は DXFILEERR_BADVALUE を返す。

対象

このメソッドは、IDirectXFileObject を継承する次のインターフェイスに適用される。

  • IDirectXFileBinary
  • IDirectXFileData

動作環境

ヘッダー : dxfile.h で宣言。
インポート ライブラリ : d3dxof.lib を使用。


IDirectXFileObject::GetName

Microsoft® DirectX® ファイル オブジェクトの名前へのポインタを取得する。

HRESULT GetName(
  LPSTR pstrNameBuf,
  LPDWORD pdwBufLen
);

パラメータ

pstrNameBuf
[out] Microsoft® DirectX® ファイル オブジェクトの名前がコピーされるバッファへのポインタ。バッファ長だけが必要であれば NULL を設定する。
pdwBufLen
[in, out] pstrNameBuf が指すバッファの長さを示す DWORD 値へのポインタ。pstrNameBuf が NULL の場合でも、オブジェクトの名前を格納するために必要なバッファ長が設定される。いずれの場合も、pdwBufLen の元の値がオブジェクトの名前を格納するのに必要な長さ以上の値でないときは、DXFILEERR_BADVALUE が関数から返る。

戻り値

成功した場合は、DXFILE_OK を返す。

失敗した場合は、次のいずれかの値を返す。

DXFILEERR_BADALLOC
DXFILEERR_BADVALUE

対象

このメソッドは、IDirectXFileObject を継承する次のインターフェイスに適用される。

  • IDirectXFileBinary
  • IDirectXFileData

動作環境

ヘッダー : dxfile.h で宣言。
インポート ライブラリ : d3dxof.lib を使用。


IDirectXFileSaveObject

データ オブジェクトを作成し、テンプレートとデータ オブジェクトを保存するには、IDirectXFileSaveObject インターフェイスのメソッドを使用する。テンプレートは、必ずしもすべてのファイルについて必要ではない。たとえば、DirectX ファイルごとにテンプレートを複製するのではなく、すべてのテンプレートを 1 つの Microsoft® DirectX® ファイルに収めてもかまわない。

IDirectXFileSaveObject インターフェイスを取得するには、IDirectXFile::CreateSaveObject メソッドを呼び出す。

IDirectXFileSaveObject インターフェイスのメソッドは、以下のグループにまとめることができる。

作成 | CreateDataObject
保存 | SaveData
 | SaveTemplates

すべての COM インターフェイスと同様、IDirectXFileSaveObject インターフェイスは IUnknown インターフェイスのメソッドを継承する。IUnknown インターフェイスは、次の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

IDirectXFileSaveObject インターフェイスのグローバル ユニーク識別子 (GUID) は IID_IDirectXFileSaveObject である。

動作環境

ヘッダー : dxfile.h で宣言。
インポート ライブラリ : d3dxof.lib を使用。


IDirectXFileSaveObject::CreateDataObject

データ オブジェクトを作成する。

HRESULT CreateDataObject(
  REFGUID rguidTemplate,
  LPCSTR szName,
  const GUID* pguid,
  DWORD cbSize,
  LPVOID pvData,
  LPDIRECTXFILEDATA* ppDataObj
);

パラメータ

rguidTemplate
[in] データ オブジェクトのテンプレートを表すグローバル ユニーク識別子 (GUID)。
szName
[in] データ オブジェクトの名前へのポインタ。オブジェクトに名前がない場合は、NULL を指定する。
pguid
[in] データ オブジェクトを表す GUID へのポインタ。オブジェクトに GUID がない場合は、NULL を指定する。
cbSize
[in] データ オブジェクトのサイズ (バイト単位)。
pvData
[in] 全必須メンバのデータが格納されているバッファへのポインタ。
ppDataObj
[out, retval] 作成されたファイル データ オブジェクトを表す IDirectXFileData インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、DXFILE_OK を返す。

失敗した場合は、次のいずれかの値を返す。

DXFILEERR_BADALLOC
DXFILEERR_BADVALUE

注意

データ参照オブジェクトが作成したデータ オブジェクトを参照する場合は、szName パラメータと pguid パラメータの少なくとも一方は NULL 以外の値でなければならない。

このメソッドで作成したデータを保存する前に、IDirectXFileSaveObject::SaveTemplates メソッドを使ってテンプレートを保存しなければならない。作成したデータは IDirectXFileSaveObject::SaveData メソッドを使って保存する。

オプション データを保存する必要がある場合は、このメソッドを呼び出した後、SaveData メソッドを呼び出す前に、IDirectXFileData::AddDataObject メソッドを使用して行う。子オブジェクトがある場合は、SaveData を呼び出す前に追加する。

動作環境

ヘッダー : dxfile.h で宣言。
インポート ライブラリ : d3dxof.lib を使用。

参照

IDirectXFileData::AddDataObject、IDirectXFileSaveObject::SaveData、IDirectXFileSaveObject::SaveTemplates


IDirectXFileSaveObject::SaveData

データ オブジェクトとその子を Microsoft® DirectX® ファイルに保存する。

HRESULT SaveData(
  LPDIRECTXFILEDATA pDataObj
);

パラメータ

pDataObj
[in] 保存するファイル データ オブジェクトを表す IDirectXFileData インターフェイスへのポインタ。

戻り値

成功した場合は、DXFILE_OK を返す。

失敗した場合は、次のいずれかの値を返す。

DXFILEERR_BADARRAYSIZE
DXFILEERR_BADVALUE

動作環境

ヘッダー : dxfile.h で宣言。
インポート ライブラリ : d3dxof.lib を使用。


IDirectXFileSaveObject::SaveTemplates

テンプレートを Microsoft® DirectX® ファイルに保存する。

HRESULT SaveTemplates(
  DWORD cTemplates,
  const GUID** ppguidTemplates
);

パラメータ

cTemplates
[in] 保存するテンプレートの総数。
ppguidTemplates
[in] 保存する全テンプレートのグローバル ユニーク識別子 (GUID) 配列へのポインタのアドレス。

戻り値

成功した場合は、DXFILE_OK を返す。

失敗した場合は DXFILEERR_BADVALUE を返す。

注意

次のサンプル コードは、SaveTemplates メソッドの呼び出し、および ppguidTemplates が示す配列の内容の例である。

IDirectXFileSaveObject * pDXFileSaveObject;

const GUID *aIds[] = {
    &DXFILEOBJ_SimpleData,
    &DXFILEOBJ_ArrayData,
    &DXFILEOBJ_RestrictedData};

hr = pDXFileSaveObject->SaveTemplates(3, aIds);

このメソッドを使ってテンプレートを保存した後、データ オブジェクトを作成するには、IDirectXFileSaveObject::CreateDataObject メソッドを使用する。

動作環境

ヘッダー : dxfile.h で宣言。
インポート ライブラリ : d3dxof.lib を使用。

参照

IDirectXFileSaveObject::CreateDataObject


関数

ここでは、Microsoft® DirectX® ファイルを使用する場合に実装する必要がある関数のリファレンス情報を記述する。次の関数が実装されている。

  • DirectXFileCreate


DirectXFileCreate

DirectXFile オブジェクトのインスタンスを作成する。

STDAPI DirectXFileCreate(
  LPDIRECTXFILE* lplpDirectXFile
);

パラメータ

lplpDirectXFile
作成された DirectXFile オブジェクトを表す IDirectXFile インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、DXFILE_OK を返す。

失敗した場合は、次のいずれかの値を返す。

DXFILEERR_BADALLOC
DXFILEERR_BADVALUE

注意

この関数を使用した後、テンプレートを登録するには IDirectXFile::RegisterTemplates を、列挙オブジェクトを作成するには IDirectXFile::CreateEnumObject を、保存オブジェクトを作成するには IDirectXFile::CreateSaveObject を、それぞれ使用する。

動作環境

ヘッダー : dxfile.h で宣言。
インポート ライブラリ : d3dxof.lib を使用。

参照

IDirectXFile::CreateEnumObject、IDirectXFile::CreateSaveObject、IDirectXFile::RegisterTemplates


構造体

ここでは、Microsoft® DirectX® で使用する以下の構造体について説明する。

  • DXFILELOADMEMORY
  • DXFILELOADRESOURCE


DXFILELOADMEMORY

メモリ データを示す。

typedef struct _DXFILELOADMEMORY {
    LPVOID lpMemory;
    DWORD dSize;
} DXFILELOADMEMORY, *LPDXFILELOADMEMORY;

メンバ

lpMemory
ロードするメモリ ブロックへのポインタ。
dSize
ロードするメモリ ブロックのサイズ (バイト単位)。

注意

この構造体は、アプリケーションで DXFILELOAD_FROMMEMORY を指定して IDirectXFile::CreateEnumObject メソッドを使用するとロードされるリソースを示している。

動作環境

ヘッダー : dxfile.h で宣言。

参照

IDirectXFile::CreateEnumObject


DXFILELOADRESOURCE

リソース データを示す。

typedef struct _DXFILELOADRESOURCE {
    HMODULE hModule;
    LPCTSTR lpName;
    LPCTSTR lpType;
} DXFILELOADRESOURCE, *LPDXFILELOADRESOURCE;

メンバ

hModule
ロードするリソースを含むモジュールのハンドル。このメンバが NULL の場合は、リソースは、それを使用する実行可能ファイルにアタッチされていなければならない。
lpName
ロードするリソースの名前を指定する文字列へのポインタ。たとえば、リソースがメッシュの場合は、このメンバでメッシュ ファイルの名前を指定しなければならない。
lpType
リソースを識別するユーザー定義タイプを指定する文字列へのポインタ。

注意

この構造体は、アプリケーションで DXFILELOAD_FROMRESOURCE を指定して IDirectXFile::CreateEnumObject メソッドを使用するとロードされるリソースを示している。

動作環境

ヘッダー : dxfile.h で宣言。

参照

IDirectXFile::CreateEnumObject


戻り値

Microsoft® DirectX® (.x) ファイルの処理に使用するメソッドからは、COM の標準の戻り値に加えて、次の値が返る場合がある。

DXFILE_OK
コマンドが正常に完了した。
DXFILEERR_BADALLOC
メモリの割り当てに失敗した。
DXFILEERR_BADARRAYSIZE
配列のサイズが無効である。
DXFILEERR_BADCACHEFILE
.x ファイルのデータを格納しているキャッシュ ファイルが無効である。キャッシュ ファイルには、ネットワークから取得されて、ハード ディスクにキャッシュされて、以降の要求において取得されたデータが格納されている。
DXFILEERR_BADDATAREFERENCE
参照されているデータが無効である。
DXFILEERR_BADFILE
ファイルが無効である。
DXFILEERR_BADFILECOMPRESSIONTYPE
ファイル圧縮のタイプが無効である。
DXFILEERR_BADFILEFLOATSIZE
浮動小数点のサイズが無効である。
DXFILEERR_BADFILETYPE
ファイルが DirectX (.x) ファイルではない。
DXFILEERR_BADFILEVERSION
ファイルのバージョンが無効である。
DXFILEERR_BADINTRINSICS
固有情報が無効である。
DXFILEERR_BADOBJECT
オブジェクトが無効である。
DXFILEERR_BADRESOURCE
リソースが無効である。
DXFILEERR_BADTYPE
オブジェクト タイプが無効である。
DXFILEERR_BADVALUE
パラメータが無効である。
DXFILEERR_FILENOTFOUND
ファイルが見つからない。
DXFILEERR_INTERNALERROR
内部エラーが発生した。
DXFILEERR_NOINTERNET
インターネット接続が見つからない。
DXFILEERR_NOMOREDATA
それ以上利用できるデータがない。
DXFILEERR_NOMOREOBJECTS
すべてのオブジェクトが列挙されている。
DXFILEERR_NOMORESTREAMHANDLES
ストリーム ハンドルが利用できない。
DXFILEERR_NOTDONEYET
処理が完了していない。
DXFILEERR_NOTFOUND
オブジェクトが見つからない。
DXFILEERR_PARSEERROR
ファイルを解析できない。
DXFILEERR_RESOURCENOTFOUND
リソースが見つからない。
DXFILEERR_NOTEMPLATE
テンプレートを利用できない。
DXFILEERR_URLNOTFOUND
URL が見つからない。


X ファイル フォーマット リファレンス

ここでは、Microsoft® DirectX® (.x) ファイル フォーマットのリファレンス情報を記述する。

  • X ファイル テンプレート
  • バイナリ フォーマット


X ファイル テンプレート

ここでは、次の .x ファイル テンプレートについて詳しく説明する。

  • Header
  • Vector
  • Coords2d
  • Quaternion
  • Matrix4x4
  • ColorRGBA
  • ColorRGB
  • IndexedColor
  • Boolean
  • Boolean2d
  • Material
  • TextureFilename
  • MeshFace
  • MeshFaceWraps
  • MeshTextureCoords
  • MeshNormals
  • MeshVertexColors
  • MeshMaterialList
  • Mesh
  • FrameTransformMatrix
  • Frame
  • FloatKeys
  • TimedFloatKeys
  • AnimationKey
  • AnimationOptions
  • Animation
  • AnimationSet
  • Patch
  • PatchMesh
  • VertexDuplicationIndices
  • XSkinMeshHeader
  • SkinWeights


Header

アプリケーション固有のヘッダーを定義する。

UUID

<3D82AB43-62DA-11cf-AB39-0020AF71E433>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
major | WORD |  | なし
minor | WORD |  |
flags | DWORD


Vector

ベクトルを定義する。

UUID

<3D82AB5E-62DA-11cf-AB39-0020AF71E433>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
x | FLOAT |  | なし
y | FLOAT |  |
z | FLOAT


Coords2d

メッシュのテクスチャ座標を定義するために使用する 2 次元ベクトル。

UUID

<F6F23F44-7686-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
u | FLOAT |  | なし
v | FLOAT |  |


Quaternion

現在は使用されていない。

UUID

<10DD46A3-775B-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
s | FLOAT |  | なし
v | Vector |  |


Matrix4x4

4 × 4 の行列を定義する。これはフレーム トランスフォーム行列として使用される。

UUID

<F6F23F45-7686-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
matrix | 配列 FLOAT | 16 | なし


ColorRGBA

アルファ成分を使って色オブジェクトを定義する。これは、マテリアル テンプレート定義で表面の色として使用される。

UUID

<35FF44E0-6C7C-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
red | FLOAT |  | なし
green | FLOAT |  |
blue | FLOAT
alpha | FLOAT


ColorRGB

基本的な RGB 色オブジェクトを定義する。

UUID

<D3E16E81-7835-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
red | FLOAT |  | なし
green | FLOAT |  |
blue | FLOAT


IndexedColor

インデックス パラメータと RGBA 色で構成され、メッシュ頂点カラーを定義するために使用される。インデックスは色を適用する頂点を定義する。

UUID

<1630B820-7842-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプションの配列サイズ
index | DWORD |
indexColor | ColorRGBA


Boolean

単純なブール型を定義する。このテンプレートは 0 または 1 に設定しなければならない。

UUID

<4885AE61-78E8-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
truefalse | DWORD |  | なし


Boolean2d

MeshFaceWraps テンプレートで、個々の面のテクスチャ トポロジを定義するために使用される 2 つのブール値のセットを定義する。

UUID

<4885AE63-78E8-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
u | Boolean |  | なし
v | Boolean |  |


Material

メッシュ全体またはメッシュの個々の面のいずれかに適用できる基本的なマテリアル色を定義する。累乗はマテリアルのスペキュラ指数である。アンビエント色にはアルファ成分が必要であることに注意すること。

TextureFilename は、オプションのデータ オブジェクトである。このオブジェクトが存在しない場合、面はテクスチャ処理されない。

UUID

<3D82AB4D-62DA-11cf-AB39-0020AF71E433>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
faceColor | ColorRGBA |  | 任意
power | FLOAT |  |
specularColor | ColorRGB
emissiveColor | ColorRGB


TextureFilename

メッシュまたは面に適用するテクスチャのファイル名を指定できるようにする。このテンプレートは、マテリアル オブジェクト内に存在していなければならない。

UUID

<A42790E1-7810-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
filename | STRING |  | なし


MeshFace

Mesh テンプレートで、メッシュの面を定義するために使用される。nFaceVertexIndices 配列の各要素は、面を構築するために使用されるメッシュ頂点を参照する。

UUID

<3D82AB5F-62DA-11cf-AB39-0020AF71E433>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
nFaceVertexIndices | DWORD |  | なし
faceVertexIndices | 配列 DWORD | nFaceVertexIndicies |


MeshFaceWraps

ラップ内の各面のテクスチャ トポロジを定義するために使用される。nFaceWrapValues メンバの値は、メッシュの面の数と同じでなければならない。

UUID

<4885AE62-78E8-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
nFaceWrapValues | DWORD |  | なし
faceWrapValues | Boolean2d |  |


MeshTextureCoords

メッシュのテクスチャ座標を定義する。

UUID

<F6F23F40-7686-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
nTextureCoords | DWORD |  | なし
textureCoords | 配列 Coords2d | nTextureCoords |


MeshNormals

メッシュの法線を定義する。ベクトルの最初の配列は法線ベクトル自体であり、2 番目の配列は特定の面に適用すべき法線を指定するインデックスの配列である。nFaceNormals メンバの値は、メッシュの面の数と同じでなければならない。

UUID

<F6F23F43-7686-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
nNormals | DWORD |  | なし
normals | 配列 Vector | nNormals |
nFaceNormals | DWORD |
faceNormals | 配列 MeshFace | nFaceNormals


MeshVertexColors

面ごと、またはメッシュごとにマテリアルを適用する代わりに、メッシュの頂点カラーを指定する。

UUID

<1630B821-7842-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
nVertexColors | DWORD |  | なし
vertexColors | 配列 IndexedColor | nVertexColors |


MeshMaterialList

メッシュ オブジェクトで、どのマテリアルをどの面に適用するかを指定するために使用される。nMaterials メンバは存在するマテリアルの数を指定し、materials は適用するマテリアルを指定する。

UUID

<F6F23F42-7686-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
nMaterials | DWORD |  | Material
nFaceIndexes | DWORD |  |
FaceIndexes | 配列 DWORD | nFaceIndexes


Mesh

単純なメッシュを定義する。最初の配列は頂点のリストで、2 番目の配列は頂点配列にインデックス付けすることによってメッシュの面を定義する。

UUID

<3D82AB44-62DA-11cf-AB39-0020AF71E433>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
nVertices | DWORD |  | 任意
vertices | 配列 Vector | nVertices |
nFaces | DWORD |
faces | 配列 MeshFace | nFaces

オプションのデータ要素

次のオプションのデータ要素を使用できる。

Data element | 説明
MeshFaceWraps | この要素が存在しない場合、u および v の両方のラッピングのデフォルトは FALSE になる。
MeshTextureCoords | この要素が存在しない場合、テクスチャ座標は存在しない。
MeshNormals | この要素が存在しない場合、法線は API の GenerateNormals メソッドを使って生成される。
MeshVertexColors | この要素が存在しない場合、色のデフォルトは白になる。
MeshMaterialList | この要素が存在しない場合、マテリアルのデフォルトは白になる。


FrameTransformMatrix

フレーム (およびそのすべての子オブジェクト) のローカル トランスフォームを定義する。

UUID

<F6F23F41-7686-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
frameMatrix | Matrix4x4 |  | なし


Frame

フレームを定義する。現在、フレームには Mesh および FrameTransformMatrix 型のオブジェクトを含めることができる。

UUID

<3D82AB46-62DA-11cf-AB39-0020AF71E433>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
なし |  |  | 任意

オプションのデータ要素

次のオプションの要素を使用できる。

Data element | 説明
FrameTransformMatrix | この要素が存在しない場合、フレームにローカル トランスフォームが適用されない。
Mesh | フレームの子になる任意の数のメッシュ オブジェクト。これらのオブジェクトは、インラインで、または参照によって指定できる。


FloatKeys

浮動小数点数 (float) の配列および配列内の float の数を定義する。これは、アニメーション キーのセットを定義するために使用される。

UUID

<10DD46A9-775B-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
nValues | DWORD |  | なし
values | 配列 FLOAT | nValues |


TimedFloatKeys

アニメーションで使用される浮動小数点数のセットおよび正の時間を定義する。

UUID

<F406B180-7B3B-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
time | DWORD |  | なし
tfkeys | FloatKeys |  |


AnimationKey

アニメーション キーのセットを定義する。keyType メンバは、キーが回転、スケーリング、位置、または行列キーのいずれであるかを指定する (それぞれ、整数 0、1、2、3 を使用する)。行列キーは、アニメーション データのセットをトランスフォーム行列として表す必要がある場合に便利である。

UUID

<10DD46A8-775B-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
keyType | DWORD |  | なし
nKeys | DWORD |  |
keys | 配列 TimedFloatKeys | nKeys


AnimationOptions

アニメーション オプションを設定できるようにする。openclosed メンバは閉じたアニメーションを示す 0、または開いたアニメーションを示す 1 のいずれかに設定できる。positionquality メンバは、指定された位置キーの位置の品質を設定するために使用される。スプライン位置を示す 0、またはリニア位置を示す 1 のいずれかに設定できる。デフォルトでは、アニメーションは閉じられる。

UUID

<E2BF56C0-840F-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
openclosed | DWORD |  | なし
positionquality | DWORD |  |


Animation

前のフレームを参照するアニメーションを格納する。フレームへの参照が 1 つと、少なくとも 1 セットの AnimationKey テンプレートが格納されている必要がある。AnimationOptions データ オブジェクトを格納することもできる。

UUID

<3D82AB4F-62DA-11cf-AB39-0020AF71E433>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
なし |  |  | 任意

オプションのデータ要素

次のオプションのデータ要素が使用される。

Data element | 説明
AnimationKey | すべてのアニメーションで AnimationKeys が必要とされる。
AnimationOptions | この要素が存在しない場合、アニメーションは閉じられる。


AnimationSet

1 つ以上の Animation オブジェクトを格納する。アニメーション セット内の各アニメーションは、どの時点でも同じ時間を持つ。アニメーション セットの時間を増やすと、含まれているすべてのアニメーションの時間が増加する。

UUID

<3D82AB50-62DA-11cf-AB39-0020AF71E433>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
なし |  |  | Animation


Patch

ベジェ制御パッチを定義する。この配列はパッチの制御点を定義する。

UUID

<A3EB5D44-FC22-429D-9AFB-3221CB9719A6>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
nControlIndices | DWORD |  | なし
controlIndices | 配列 DWORD | nControlIndices |

パッチのタイプは、次の表に示されているように、制御点の数によって定義される。

制御点の数 | 型
10 | 3 次ベジェ三角形パッチ
15 | 4 次ベジェ三角形パッチ
16 | 3 次ベジェ四角形 (矩形) パッチ

制御点の次数は、三角形パッチおよび矩形パッチについて次の図に示されているように、らせん形のパターンで示される。

三角形パッチでは次のパターンを使用していた。

矩形パッチでは次のパターンを使用する。


PatchMesh

ベジェ パッチによって定義されたメッシュを定義する。最初の配列は頂点のリストで、2 番目の配列は頂点配列にインデックス付けすることによってメッシュのパッチを定義する。

UUID

<D02C95CC-EDBA-4305-9B5D-1820D7704BBF>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
nVertices | DWORD |  | なし
vertices | 配列 Vector | nVertices |
nPatches | DWORD |
patches | 配列 Patch | nPatches

パッチは、各パッチの制御点として、頂点の配列内の頂点を使用する。


VertexDuplicationIndices

このテンプレートはメッシュごとにインスタンス化され、メッシュ内のどの頂点が互いに重複しているかという情報を保持する。頂点がスムージング グループまたはマテリアルの境界にある場合に重複が発生する。このテンプレートの目的は、周辺パラメータが異なるどの頂点が、実際にはモデル内の同じ頂点であるかを、ローダーが決定できるようにすることである。特定の用途 (メッシュの単純化など) で、この情報を利用できる。

UUID

<B8D65549-D7C9-4995-89CF-53A9A8B031E3>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
nIndices | DWORD |  | なし
nOriginalVertices | DWORD |  |
indices | 配列 DWORD | nIndices

重複が発生する前のメッシュ内の頂点の数は nOriginalVertices である。値 indices[n] は、重複が発生しない場合にメッシュの頂点配列内の vertex[n] が持つ頂点インデックスを保持する。したがって、この配列内のインデックスが同じである場合は、重複した頂点であることを示す。


XSkinMeshHeader

このテンプレートは、エクスポートされたスキニング情報を含むメッシュ内でのみ、メッシュごとにインスタンス化される。このテンプレートの目的は、エクスポートされたスキニング情報の性質に関する情報を提供することである。

UUID

<3CF169CE-FF7C-44ab-93C0-F78F62D172E2>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
nMaxSkinWeightsPerVertex | WORD |  | なし
nMaxSkinWeightsPerFace | WORD |  |
nBones | WORD

メッシュ内の頂点に影響するトランスフォームの最大数は nMaxSkinWeightsPerVertex である。任意の面の 3 つの頂点に影響する一意のトランスフォームの最大数は nMaxSkinWeightsPerFace である。このメッシュの頂点に影響するボーンの数は nBones である。


SkinWeights

このテンプレートはメッシュごとにインスタンス化される。メッシュ内に、このテンプレートの n 個のインスタンスのシーケンスが表示される。ここで、n はメッシュ内の頂点に影響するボーンの数 (X ファイル フォーマット) である。テンプレートの各インスタンスは、基本的に特定のボーンのメッシュへの影響を定義する。頂点インデックスのリスト、および対応する重みのリストがある。

UUID

<6F0D123B-BAD2-4167-A0D0-80224F25FABB>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
transformNodeName | STRING |  | なし
nWeights | DWORD |  |
vertexIndices | 配列 DWORD | nWeights
weights | 配列 float | nWeights
matrixOffset | Matrix4x4 |

影響を定義するボーンの名前は transformNodeName であり、nWeights はこのボーンの影響を受ける頂点の数である。このボーンの影響を受ける頂点は vertexIndices に格納されており、このボーンの影響を受ける各頂点の重みは weights に格納される。

行列 matrixOffset は、メッシュの頂点をボーンの空間にトランスフォームする。ボーンのトランスフォームと連結すると、ボーンの影響を受けるメッシュのワールド空間座標が得られる。


バイナリ フォーマット

ここでは、DirectX 3.0 のリリース以降導入された Microsoft® DirectX® (.x) ファイル フォーマットのバイナリ バージョンについて詳しく説明する。ここで説明されている内容は、「X ファイル アーキテクチャ」の説明を参照しながら読むことを推奨する。

バイナリ フォーマットは、トークン化されたテキスト フォーマットの表現である。トークンは、スタンドアロンである場合と、プリミティブ データ レコードが付属する場合がある。スタンドアロン トークンは文法的な構造を提供し、レコード生成トークンは必要なデータを提供する。

すべてのデータはリトル エンディアン フォーマットで格納されることに注意すること。有効なバイナリ データ ストリームは、ヘッダーと、それに続くテンプレートとデータ オブジェクトの両方またはいずれかで構成される。

ここでは、バイナリ ファイル フォーマットの次のコンポーネントについて説明し、テンプレートおよびバイナリ データ オブジェクトの例を示す。

  • ヘッダー
  • トークン
  • トークン レコード
  • テンプレート
  • データ
  • 例


ヘッダー

バイナリ ヘッダーを直接読み書きする場合は、次の定義を使用しなければならない。圧縮データ ストリームは現在サポートされていないので、ここでは詳しく示されていないことに注意すること。

#define XOFFILE_FORMAT_MAGIC \
  ((long)'x' + ((long)'o' << 8) + ((long)'f' << 16) + ((long)' ' << 24))

#define XOFFILE_FORMAT_VERSION \
  ((long)'0' + ((long)'3' << 8) + ((long)'0' << 16) + ((long)'2' << 24))

#define XOFFILE_FORMAT_BINARY \
  ((long)'b' + ((long)'i' << 8) + ((long)'n' << 16) + ((long)' ' << 24))

#define XOFFILE_FORMAT_TEXT   \
  ((long)'t' + ((long)'x' << 8) + ((long)'t' << 16) + ((long)' ' << 24))

#define XOFFILE_FORMAT_COMPRESSED \
  ((long)'c' + ((long)'m' << 8) + ((long)'p' << 16) + ((long)' ' << 24))

#define XOFFILE_FORMAT_FLOAT_BITS_32 \
  ((long)'0' + ((long)'0' << 8) + ((long)'3' << 16) + ((long)'2' << 24))

#define XOFFILE_FORMAT_FLOAT_BITS_64 \
  ((long)'0' + ((long)'0' << 8) + ((long)'6' << 16) + ((long)'4' << 24))


トークン

トークンはリトル エンディアン WORD として記述される。以下のトークンのリストは、レコード生成トークンとスタンドアロン トークンに分かれている。

レコード生成トークンは次のように定義される。

#define TOKEN_NAME 1
#define TOKEN_STRING 2
#define TOKEN_INTEGER 3
#define TOKEN_GUID 5
#define TOKEN_INTEGER_LIST 6
#define TOKEN_FLOAT_LIST 7

スタンドアロン トークンは次のように定義される。

#define TOKEN_OBRACE 10
#define TOKEN_CBRACE 11
#define TOKEN_OPAREN 12
#define TOKEN_CPAREN 13
#define TOKEN_OBRACKET 14
#define TOKEN_CBRACKET 15
#define TOKEN_OANGLE 16
#define TOKEN_CANGLE 17
#define TOKEN_DOT 18
#define TOKEN_COMMA 19
#define TOKEN_SEMICOLON 20
#define TOKEN_TEMPLATE 31
#define TOKEN_WORD 40
#define TOKEN_DWORD 41
#define TOKEN_FLOAT 42
#define TOKEN_DOUBLE 43
#define TOKEN_CHAR 44
#define TOKEN_UCHAR 45
#define TOKEN_SWORD 46
#define TOKEN_SDWORD 47
#define TOKEN_VOID 48
#define TOKEN_LPSTR 49
#define TOKEN_UNICODE 50
#define TOKEN_CSTRING 51
#define TOKEN_ARRAY 52


トークン レコード

ここでは、各レコード生成トークンのレコードのフォーマットについて説明する。説明するトピックは、次のとおりである。

  • TOKEN_NAME
  • TOKEN_STRING
  • TOKEN_INTEGER
  • TOKEN_GUID
  • TOKEN_INTEGER_LIST
  • TOKEN_FLOAT_LIST


TOKEN_NAME

可変長レコード。トークンの後には、name フィールドに続くバイト数を指定する count 値が続く。長さ count の ASCII 名でレコードが完了する。

フィールド | 型 | サイズ (バイト) | 内容
token | WORD | 2 | TOKEN_NAME
count | DWORD | 4 | バイト単位の name フィールドの長さ
name | BYTE 配列 | count | ASCII 名


TOKEN_STRING

可変長レコード。トークンの後には、string フィールドに続くバイト数を指定する count 値が続く。長さ count の ASCII 文字列ではレコードは継続し、終了トークンによって完了する。terminator の選択は、ほかで説明する構文の問題によって決まる。

フィールド | 型 | サイズ (バイト) | 内容
token | WORD | 2 | TOKEN_STRING
count | DWORD | 4 | バイト単位の string フィールドの長さ
string | BYTE 配列 | count | ASCII 文字列
terminator | DWORD | 4 | TOKEN_SEMICOLON または TOKEN_COMMA


TOKEN_INTEGER

固定長レコード。トークンの後には、必要な整数値が続く。

フィールド | 型 | サイズ (バイト) | 内容
token | WORD | 2 | TOKEN_INTEGER
value | DWORD | 4 | 単一の整数


TOKEN_GUID

固定長レコード。トークンの後には、OSF DCE 標準で定義されている 4 つのデータ フィールドが続く。

フィールド | 型 | サイズ (バイト) | 内容
token | WORD | 2 | TOKEN_GUID
data1 | DWORD | 4 | UUID データ フィールド 1
data2 | WORD | 2 | UUID データ フィールド 2
data3 | WORD | 2 | UUID データ フィールド 3
data4 | BYTE 配列 | 8 | UUID データ フィールド 4


TOKEN_INTEGER_LIST

可変長レコード。トークンの後には、list フィールドに続く整数の数を指定する count 値が続く。効率化のために、連続する整数のリストは単一のリストに合成することが望ましい。

フィールド | 型 | サイズ (バイト) | 内容
token | WORD | 2 | TOKEN_INTEGER_LIST
count | DWORD | 4 | list フィールドの整数の数
list | DWORD | 4 × count | 整数のリスト


TOKEN_FLOAT_LIST

可変長レコード。トークンの後には、list フィールドに続く浮動小数点数または倍精度整数の数を指定する count 値が続く。浮動小数点数値 (float または double) のサイズは、ファイル ヘッダーで指定された float のサイズの値によって決まる。効率化のために、連続する TOKEN_FLOAT_LIST は単一のリストに合成することが望ましい。

フィールド | 型 | サイズ (バイト) | 内容
token | WORD | 2 | TOKEN_FLOAT_LIST
count | DWORD | 4 | list フィールドの浮動小数点数または倍精度整数の数
list | float/double 配列 | 4 または 8 ﾗ count | float または double のリスト


テンプレート

テンプレートには、次の構文の定義がある。

template              : TOKEN_TEMPLATE name TOKEN_OBRACE
                            class_id
                            template_parts
                            TOKEN_CBRACE

template_parts        : template_members_part TOKEN_OBRACKET
                        template_option_info
                        TOKEN_CBRACKET
                      | template_members_list

template_members_part :/* 空 */
                      | template_members_list

template_option_info  : ellipsis
                      | template_option_list

template_members_list :    template_members
                      | template_members_list template_members

template_members      : primitive
                      | array
                      | template_reference

primitive             : primitive_type optional_name TOKEN_SEMICOLON

array                 : TOKEN_ARRAY array_data_type name dimension_list
                        TOKEN_SEMICOLON

template_reference    : name optional_name YT_SEMICOLON

primitive_type        : TOKEN_WORD
                      | TOKEN_DWORD
                      | TOKEN_FLOAT
                      | TOKEN_DOUBLE
                      | TOKEN_CHAR
                      | TOKEN_UCHAR
                      | TOKEN_SWORD
                      | TOKEN_SDWORD
                      | TOKEN_LPSTR
                      | TOKEN_UNICODE
                      | TOKEN_CSTRING

array_data_type       : primitive_type
                      | name

dimension_list        : dimension
                      | dimension_list dimension

dimension             : TOKEN_OBRACKET dimension_size TOKEN_CBRACKET

dimension_size        : TOKEN_INTEGER
                      | name

template_option_list  : template_option_part
                      | template_option_list template_option_part

template_option_part  : name optional_class_id

name                  : TOKEN_NAME

optional_name         :/* 空 */
                      | name

class_id              : TOKEN_GUID

optional_class_id     :/* 空 */
                      | class_id

ellipsis              : TOKEN_DOT TOKEN_DOT TOKEN_DOT


データ

データ オブジェクトには、次の構文の定義がある。

object                : identifier optional_name TOKEN_OBRACE
                            optional_class_id
                            data_parts_list
                            TOKEN_CBRACE
data_parts_list       : data_part
                      | data_parts_list data_part

data_part             : data_reference
                      | object
                      | number_list
                      | float_list
                      | string_list

number_list           : TOKEN_INTEGER_LIST

float_list            : TOKEN_FLOAT_LIST

string_list           : string_list_1 list_separator

string_list_1         : string
                      | string_list_1 list_separator string

list_separator        : comma
                      | semicolon

string                : TOKEN_STRING

identifier            : name
                      | primitive_type

data_reference        : TOKEN_OBRACE name optional_class_id TOKEN_CBRACE

バイナリ ファイルの number_list および float_list データでは、TOKEN_COMMA および TOKEN_SEMICOLON は使用されないことに注意すること。カンマおよびセミコロンは string_list データで使用される。オプションのデータ メンバとして使用できるのは data_reference だけであることにも注意すること。


例

2 つのバイナリ テンプレート定義の例およびバイナリ データ オブジェクトの例を以下に示す。データはリトル エンディアン フォーマットで格納されるが、これらの例には示されていないことに注意すること。

閉じたテンプレート RGB は UUID {55b6d780-37ec-11d0-ab39-0020af71e433} によって識別され、それぞれ float 型の 3 つのメンバ r、g、b を持つ。

TOKEN_TEMPLATE, TOKEN_NAME, 3, 'R', 'G', 'B', TOKEN_OBRACE,
TOKEN_GUID, 55b6d780, 37ec, 11d0, ab, 39, 00, 20, af, 71, e4, 33,
TOKEN_FLOAT, TOKEN_NAME, 1, 'r', TOKEN_SEMICOLON,
TOKEN_FLOAT, TOKEN_NAME, 1, 'g', TOKEN_SEMICOLON,
TOKEN_FLOAT, TOKEN_NAME, 1, 'b', TOKEN_SEMICOLON,
TOKEN_CBRACE

閉じたテンプレート Matrix4x4 は UUID {55b6d781-37ec-11d0-ab39-0020af71e433} によって識別され、float 型の matrix という名前の 2 次元配列である 1 つのメンバを持つ。

TOKEN_TEMPLATE, TOKEN_NAME, 9, 'M', 'a', 't', 'r', 'i', 'x', '4', 'x', '4', TOKEN_OBRACE,
TOKEN_GUID, 55b6d781, 37ec, 11d0, ab, 39, 00, 20, af, 71, e4, 33,
TOKEN_ARRAY, TOKEN_FLOAT, TOKEN_NAME, 6, 'm', 'a', 't', 'r', 'i', 'x',
TOKEN_OBRACKET, TOKEN_INTEGER, 4, TOKEN_CBRACKET,
TOKEN_OBRACKET, TOKEN_INTEGER, 4, TOKEN_CBRACKET,
TOKEN_CBRACE

次のバイナリ データ オブジェクトは、以前に定義した RGB テンプレートのインスタンスを示している。この例のオブジェクトは blue という名前で、その 3 つのメンバ r、g、b の値はそれぞれ 0.0、0.0、1.0 である。データはリトル エンディアン フォーマットで格納されるが、この例には示されていないことに注意すること。

TOKEN_NAME, 3, 'R', 'G', 'B', TOKEN_NAME, 4, 'b', 'l', 'u', 'e', TOKEN_OBRACE,
TOKEN_FLOAT_LIST, 3, 0.0, 0.0, 1.0, TOKEN_CBRACE


DirectX Audio

ここでは、Microsoft® DirectX® を使って、アプリケーションでサウンドを再生およびキャプチャする方法について説明する。

DirectX のほかのコンポーネントと同様に、DirectX Audio は C、C++、および Microsoft® Visual Basic® で使用できる。このヘルプ ファイルでは、C および C++ について説明する。サンプル コードには C++ の構文を使用する。

DirectX Audio のヘルプの構成については、「ロードマップ」を参照すること。


ロードマップ

DirectX Audio については、以下のトピックで説明する。

  • DirectX Audio の新機能。DirectX 8.0 のこのコンポーネントの新機能。これまでに Microsoft® DirectSound® または Microsoft® DirectMusic® を使用した経験がある場合は、DirectX 7.0 から多くの変更が行われているため、このセクションを最初に読むこと。
  • DirectX Audio の概要。DirectX Audio の概要およびアプリケーションで使用可能な機能、オーディオの再生に関連する重要なオブジェクトと手順を示す。
  • DirectX Audio について。基本的なメカニズムについて詳しく説明する。ここでは、アプリケーションでオーディオ再生およびキャプチャを実装する方法は説明しないが、アプリケーション プログラミング インターフェイス (API) の理解に役立つはずである。
  • DirectX Audio の使い方。API の使い方のガイドである。このトピックの目次を参考にして、特定の情報が必要になったときに対象となる箇所を参照できる。このトピックは、リファレンス トピックと組み合わせて使用すること。
  • DirectX Audio の高度なトピック。主に、特殊なアプリケーションまたはパフォーマンスを高度に最適化する必要のあるアプリケーションについて説明する。
  • プログラミングのヒントおよびツール。DirectX Audio アプリケーションのコンパイルおよびデバッグに関するさまざまな情報を提供する。
  • DirectX Audio C++ チュートリアル。基本的な機能を段階的に実装するチュートリアルである。実践的に DirectX Audio を理解することができる。
  • DirectX Audio C++ サンプル。必要なサンプル コードを見つけるための、SDK のサンプル アプリケーションについてのガイド。基本的機能の実装方法を説明し、DirectX Audio の特定の機能を利用したサンプルを示す。
  • DirectMusic C/C++ リファレンス。DirectMusic のヘッダー ファイルで宣言されるすべての API 要素について詳しく説明する。ここでは、DirectMusic および DirectMusic Producer で使用されるファイル形式についても説明する。
  • DirectSound C/C++ リファレンス。Dsound.h で宣言されるすべての API 要素について詳しく説明する。

DirectMusic Producer

DirectMusic Producer は、DirectX SDK に含まれている強力なオーサリング アプリケーションである。このアプリケーションを使用して、作曲者はアプリケーションに組み込むことができるダイナミックなミュージック要素を作成できる。

アプリケーション開発よりもサウンドのデザインに重点を置いている場合は、このアプリケーションと共にインストールされる DirectMusic Producer ヘルプを参照すること。

アプリケーションを開発する場合に、対象となるマテリアルの概要ついて知りたい場合は、「アレンジ用のミュージック要素」を参照すること。

オーディオ スクリプティング

作曲者やサウンドの作成者は DirectX Audio のスクリプティング機能を使用して、アプリケーションでサウンドトラックを直接的に制御することができる。スクリプト API のマニュアルは、DirectMusic Producer のヘルプに含まれている。

概要については、「オーディオ スクリプト」を参照すること。スクリプトをアプリケーションに組み込む方法については、「オーディオ スクリプトの使い方」を参照すること。


DirectX Audio の新機能

DirectX のオーディオ コンポーネントは大幅に改訂されている。さまざまなサウンドを再生するために、DirectMusic と DirectSound の API の統一が進められ、多くの新機能が追加された。

次の一覧は、主な新機能を示している。

1 つの再生メカニズムでウェーブベースとメッセージベースのサウンドを統合
ウェーブ ファイルおよびリソースを DirectMusic ローダーでロードし、DirectMusic パフォーマンスによって再生できる。アプリケーションで、ウェーブ サウンドを解析およびコピーしたり、DirectSound バッファにストリーミングする必要がなくなった。ウェーブ再生のタイミングは DirectMusic マスタ クロックに基づいており、ウェーブを音楽イベントに同期させたり、ほかのセグメントと同様にツールで処理することができる。

DirectSound API も引き続きサポートされており、DirectSound バッファを使って直接ウェーブを再生することもできる。DirectSound は、ウェーブ キャプチャおよび全二重の API である。

柔軟性を増して強化されたオーディオパス モデル
以前のバージョンの DirectMusic では、パフォーマンス チャンネルはポートにマップされ、各ポートがその出力を単一の DirectSound バッファに送信していた。新しいモデルでは、セグメントのチャンネルは、パフォーマンスから最終的な出力へのデータ フローを制御するオーディオパスにマップされる。シンセサイザからの出力を、3D ポジショニングおよびエフェクトが個別に設定されている複数の再生バッファに送信できる。オーディオパスは、アプリケーションによって動的に作成したり、セグメントにオーサリングすることができる。
ここのセグメント状態の制御
セグメントの各再生インスタンスはそれぞれオーディオパスを持つことができ、ボリューム、パン、ピッチ ベンドなどのパラメータを、各セグメント状態について個々に変更できる。
DLS2 に基づく合成
DirectMusic シンセサイザは Downloadable Sounds (DLS) Level 2 規格に基づき、高品質なサウンド合成を可能にしている。DLS2 シンセサイザの新機能には、6 段階のエンベロープ、ボイスのレイヤリング、ウェーブフォームの解放、および追加の低周波数発振器 (LFO) などがある。各ボイスには、オプションのローパス共振フィルタがある。
特殊効果
DirectX Media Object をサウンド バッファにアタッチして、エフェクトを追加することができる。ミュージック リバーブ、I3DL2 (Interactive 3-D Audio Level 2) 環境リバーブ、ディストーション、エコーなどの DirectX Audio に用意されている標準的なエフェクトのほかに、サードパーティのエフェクトを追加できる。
キューの詳細な制御
作曲者がセグメント内にセグメントの再生を開始するポイントを設定し、セグメントが拍子記号との関係を維持できるようにすることができる。プライマリ セグメントには、ほかのセグメントにキューを与える任意のポイントを含めることができ、最も近い小節、拍、またはグリッドにキューを与える場合に比べて細かい制御が可能である。新しいセグメント キュー フラグ DMUS_SEGF_SEGMENTEND によって、現在のプライマリ セグメントの再生が終了したときに、セグメントを再生することができる。
演奏がもうすぐ終了することを知らせる通知
パフォーマンス通知イベントに新しい通知タイプ DMUS_NOTIFICATION_MUSICALMOSTEND が追加された。これは、キュー内の最後のプライマリ セグメントの終わりが近いことを示す。この通知によって、アプリケーションは新しいセグメントをスケジュールすることができる。
MIDI コントローラ サポートの強化
カーブメッセージが、RPN/NRPN コントローラの変更をサポートするようになった。
セグメントの無限回の繰り返し
新しい DMUS_SEG_REPEAT_INFINITE フラグによって、セグメントを無限に再生できる。
バンドのダウンロードおよびアンロードの簡易化
簡単なメソッド呼び出しで、バンドをセグメント オブジェクトにダウンロードしたり、セグメント オブジェクトからアンロードすることができる。
トラック データの動的生成
新しいトラック構成および再生フラグによって、セグメントを再生またはループするたびに、トラックを再生成することができる。たとえば、セグメントを再生するたびに新しいコード進行が設定されるようにコードマップ トラックを構成できる。
オーディオ スクリプティング
作曲者やサウンドの作成者は、スクリプトを使用することによって、演奏を細かく制御することができる。アプリケーションは再生の詳細を処理する代わりに、スクリプトを呼び出す。たとえば、ゲーム イベントがスクリプト関数のトリガとなる。スクリプトの作成者は、この関数を変更することによって、ゲームに対するサウンドトラックの応答を容易に変更できる。
トラックの実行時制御機能の向上
アプリケーションで、再生およびパラメータの制御を無効にするように、個々のトラック構成を設定できる。トラックは、ミュージック タイムではなく、クロック タイムで演奏されるように構成できる。自己制御セグメント内のトラックは、制御またはプライマリ セグメント内のパラメータ トラックをオーバーライドするように構成できる。
コンテナ オブジェクト
DirectMusic Producer プロジェクトのすべてのコンポーネントを単一のファイルに保存でき、すべてのオブジェクトを容易に検索およびロードすることができる。コンテナをセグメントに埋め込んで、セグメントの再生に必要なものをすべてセグメント内に保存することもできる。
歌詞トラック
歌詞トラックを含むセグメントによって、タイムスタンプが指定されたテキストがパフォーマンスに送信される。
キャッシュ管理機能の向上
アプリケーションで、ほかのオブジェクトによってロードされた使用されていないオブジェクトを容易に解放できるようになった。


DirectX Audio の概要

  • DirectX Audio の機能
  • DirectX Audio 入門


DirectX Audio の機能

DirectX Audio には、サウンドの再生以外にもさまざまな機能がある。ハードウェア アクセラレーション、ダウンローダブル サウンド (DLS)、DirectX Media Object (DMO)、および高度な 3D ポジショニング エフェクトを活用するダイナミック サウンドトラックを実装するためのシステムを提供する。

アプリケーションで DirectMusic および DirectSound インターフェイスを使用することによって、次のような処理を行うことができる。

  • MIDI、ウェーブ、または DirectMusic Producer ランタイム形式のファイルまたはリソースからサウンドをロードして再生する。
  • 複数のソースを同時に再生する。
  • 高い精度でミュージック イベントのタイミングをスケジュールする。
  • テンポの変更、パッチの変更、およびその他の MIDI イベントをプログラムによって送信する。
  • ダウンローダブル サウンドを使用する。DLS シンセサイザを使用することによって、アプリケーションは、メッセージベースの曲がどのコンピュータでも同じように再生されることを保証できる。アプリケーションはさまざまな音色を再生でき、個々のノートおよおよびベロシティに応じて独自の音を生成できる。
  • 3D 環境でサウンドを特定する。
  • ピッチの変更、リバーブ、およびその他のエフェクトを簡単にサウンドに適用する。
  • 16 を超える MIDI チャンネルを使用する。DirectX Audio はチャンネル数 16 の制約を打破し、任意の数のボイスをシンセサイザの制限まで、同時に演奏することを可能にした。
  • セグメントを異なるオーディオパスで再生し、エフェクトまたは空間的な広がりを各セグメントに個々に適用する。
  • MIDI データをキャプチャしたり、あるポートから別のポートにストリーミング ("転送") する。
  • マイクまたはその他の入力からウェーブ サウンドをキャプチャする。

DirectMusic Producer または類似するアプリケーションのソース ファイルを使用する場合は、さらに次のような処理が可能である。

  • 別のバリエーションを選択したり、コード進行を変更することによって、実行時に再生のさまざまな面を制御する。
  • 繰り返すたびに若干異なる曲を再生する。
  • ウェーブ サウンドにバリエーションを付けて再生する。
  • パフォーマンス チャンネルをオーディオパスにマップすることによって、同一セグメント内で、部分によって異なるエフェクトを適用する。
  • アルゴリズムによって生成するのではなく、作曲者が指定したコンポーネントに基づいて、実行時にまったく新しい曲を作成する。
  • 既存の曲間のトランジションを動的にアレンジする。
  • トランジション、モチーフ、およびサウンド エフェクトにキューを出して、パフォーマンス内の指定したリズム ポイントで再生する。

これらの機能は、主流となっているアプリケーションで一般的に使用されている機能である。DirectX Audio は基本的なタスクを容易に使用できるように設計されているが、必要に応じて下位レベルのアクセスも提供されている。また、拡張も可能である。特殊なアプリケーションでは、次のように、事実上オーディオパスのすべての段階で新しいオブジェクトを実装できる。

  • 新しい形式または独自の形式のデータを解析するローダー。
  • 任意の種類のシーケンス化されたデータを含むトラック。
  • メッセージを処理するツール。たとえば、ノートを途中で処理して転調を適用したり、セグメント ファイルに埋め込まれた歌詞を表示するメッセージを処理する。
  • カスタム シーケンサ。
  • カスタム シンセサイザ。
  • エフェクト フィルタ。

DirectX Audio には DirectMusic Producer も含まれている。このアプリケーションによって、作曲者は DirectMusic の機能を最大限に利用するための DLS コレクション、コードマップ、スタイル、およびセグメントを作成できる。また、DirectMusic Producer によって、複数のタイムスタンプを持つウェーブを格納する、再生可能なセグメントを作成できる。これらのウェーブは、圧縮形式でも非圧縮形式でも使用でき、実行時にストリーミングするか、またはメモリ内に全体を格納できる。

アプリケーションを開発する場合、直接 DirectMusic Producer を使用することはないかもしれないが、その機能を広く理解しておくことは、サウンドのデザイン チームとの作業を効率的に進める上で重要である。アプリケーション設計者の観点から見た概要については、「アレンジ用のミュージック要素」を参照すること。詳細については、DirectMusic Producer のマニュアルを参照すること。

DirectX Audio は、Microsoft® Windows® 95、Microsoft Windows 98、Microsoft Windows Me、および Microsoft Windows 2000 において、すべての機能を発揮できる。ただし、ハードウェア シンセサイザを利用できるのは、Windows 2000 および Windows 98 Second Edition 以降のみである。


DirectX Audio 入門

初めて DirectX Audio アプリケーションを作成する場合、複雑な設定は不要である。ただし、現在のバージョンの DirectX がインストールされており、開発環境でヘッダー ファイルへのパスが設定されている必要がある。\lib フォルダ内の DirectX ライブラリ ファイルにリンクできる必要もある。ソフトウェア シンセサイザによって使用される、必要な DLL およびデフォルトの DLS コレクションは、SDK の一部としてシステム ディレクトリにインストールされる。

これ以外に必要なものは、サウンド カード、スピーカまたはヘッドフォン、およびサウンドだけである。以下のいずれかのサウンドを使用できる。

  • MIDI (.mid) ファイル。
  • ウェーブ (.wav) ファイル。
  • DirectMusic Producer のセグメント (.sgt) ファイル。サンプル ファイルは、このアプリケーションと共にインストールされる。その他のファイルは DirectX サンプル アプリケーションに含まれている。

この時点では、DirectMusic Producer によって検索されるその他の種類のファイルは無視できる。コードマップ、スタイル、バンド、および DLS ファイルは再生可能なセグメントのビルディング ブロックであり、それ自体は再生できない。セグメントは、コンテナ ファイルから取得することもできるが、セグメントを抽出するには追加の作業が必要となる。

基本的な作業の詳細については、次のトピックを参照すること。

  • DirectX Audio の基本的な概念
  • サウンド再生の基本的な手順
  • DirectX Audio プロジェクトの作成


DirectX Audio の基本的な概念

ここでは、DirectX Audio の基本的な概念およびそれを実装するオブジェクトを紹介する。

DirectX はコンポーネント オブジェクト モデル (COM) に基づいており、すべての機能はオブジェクトによって実行される。また、ソース データはオブジェクトにカプセル化される。

ここで説明するオブジェクトは、DirectSound だけを使用するアプリケーション以外の、すべての DirectX Audio アプリケーションに公開される。このほかにも多くのオブジェクトが内部で使用されており、高度なアプリケーションによってアクセスすることができるが、ここでは説明しない。

説明するトピックは、次のとおりである。

  • ローダー
  • セグメントとセグメント状態
  • パフォーマンス
  • メッセージ
  • パフォーマンス チャンネル
  • DLS シンセサイザ
  • 音色とダウンロード
  • オーディオパスおよびバッファ


ローダー

ローダー (IDirectMusicLoader8) はほかのオブジェクトを取得するオブジェクトである。一般的に、DirectX Audio アプリケーションで最初に作成されるオブジェクトの 1 つである。ローダーは、DirectMusic セグメント ファイル、DLS コレクション、MIDI ファイル、モノラルおよびステレオ両方のウェーブ ファイルなど、すべてのオーディオ コンテンツのロードに使用される。また、リソースに格納されているデータもロードできる。

ファイルまたはリソースからのデータをカプセル化するオブジェクトはすべて IDirectMusicObject8 インターフェイスをサポートしている。ローダーはこのインターフェイスを取得し、これを使用してアプリケーション内のオブジェクトにデータをストリーミングする処理を開始する。データ オブジェクトは、IPersistStream の実装によってそれ自体を解析し、全体的なロード処理は自動的に実行される。必要な処理は、オブジェクトの記述を、IDirectMusicSegment8 などの必要なインターフェイスの要求と共にローダーに渡すことだけである。


セグメントとセグメント状態

セグメントは、シーケンス化されたサウンド データをカプセル化するオブジェクトである。データには、MIDI シーケンス、ウェーブ、DirectMusic Producer のセグメント ファイルの情報のコレクション、または実行時に複数のコンポーネントからアレンジされるミュージックがある。一般的に、セグメントは、1 曲のミュージックまたは 1 つの単位として再生されるその他のサウンドである。

セグメントは、プライマリ セグメントまたはセカンダリ セグメントとして再生できる。プライマリ セグメントは、一度に 1 つだけ演奏できる。セカンダリ セグメントは、一般的に、プライマリ セグメントに重ねて再生される短いモチーフまたはサウンド エフェクトである。

MIDI またはウェーブ ファイルとして生成されたセグメントは、アプリケーションで特殊な処理をしない限り、いつも同じように再生される。一方、DirectMusic Producer でオーサリングされたセグメントには、異なるミュージック パターンや、セグメントを再生するたびにバリエーションを可能にするその他の情報を含めることができる。

セグメントでは、ウェーブ、パターン、コード変更、バンド変更、テンポ変更など、異なる種類のデータを組み合わせることができる。各種のデータはトラック オブジェクトにカプセル化される。C++ で作成されたアプリケーションでは、個々のトラックにアクセスできるが、ほとんどの場合その必要はない。またセグメントは、特殊効果など、そのセグメントを再生するオーディオパスに関する情報も格納できる。

DirectMusic Producer のセグメントには、ほかのロード可能なミュージック コンポーネントへの参照を含めることもできる。たとえば、あるバンドを使って作成されたセグメントからそのバンド オブジェクトを取得できる。

セグメントを再生するたびに、セグメント状態オブジェクトが作成される。アプリケーションでは、このオブジェクトを使用して、再生の状態および再生中のセグメントのインスタンスのオーディオパスに関する情報を取得できる。


パフォーマンス

パフォーマンス オブジェクトは、ソースからシンセサイザまでのデータ フローを管理する。通常、アプリケーションはパフォーマンスを 1 つだけ持つ。

パフォーマンスは、タイミング、データ チャンネルとオーディオパスへのマッピング、メッセージのルーティング、ツール管理、通知、およびその他の重要なタスクを処理する。


メッセージ

オーディオ データは、メッセージの形でパフォーマンスに渡される。パフォーマンス メッセージは MIDI メッセージに似ているが、より多くの、より多様な情報を含んでいる。メッセージには、ノート、ウェーブ、またはコントローラの変更に関する情報を含めることができる。また、歌詞を表示するためのテキストを含めることもできる。

多くのアプリケーションでは、セグメントの再生中にトラックによって生成されるメッセージを直接処理しない。ただし、アプリケーションでパフォーマンスにメッセージを挿入したり、実装しているツールによってメッセージを途中で処理することは可能である。

また、通知にはメッセージも使用される。アプリケーションは、パフォーマンスが特定のポイントに達するたびにイベントが通知されるように要求できる。たとえば、音楽の拍子ごとにイベントを通知できる。パフォーマンス メッセージにはそのイベントに関する情報が含まれている。


パフォーマンス チャンネル

再生中のサウンドは 1 つまたは複数のパートで構成される。パートには MIDI チャンネル、DirectMusic Producer セグメントのパート、またはウェーブがある。通常、パートは 1 つの楽器に対応する。

パフォーマンス チャンネルは、パートとオーディオパスとの間のルートである。パートに関する情報を含む各メッセージは、メッセージが正しくルーティングされるようにパートのパフォーマンス チャンネルも指定する。

パフォーマンス チャンネルは MIDI チャンネルによく似ているが、従来の MIDI 再生は 16 チャンネルに制限されていたのに対し、パフォーマンス チャンネルでは実質上無制限である。


DLS シンセサイザ

MIDI ノートなど、ウェーブ形式になっていないデータをサウンド カードで再生するには、ウェーブ形式に変換する必要がある。この変換は、シンセサイザによって行われる。

DirectX Audio は一部のオペレーティング システムで基本的な MIDI 合成をサポートしているが、多くのアプリケーションは Downloadable Sounds (DLS) Level 2 規格を実装するシンセサイザを使用する。適切なハードウェア シンセサイザがない場合は、Microsoft のソフトウェア シンセサイザが使用される。

シンセサイザは、ウェーブ サンプルに基づいてサウンドを生成する。これによって、あらゆる種類のサウンドに加え、高度なティンバーも生成できる。

注 DirectX 7 インターフェイスと共に使用される DLS Level 1 シンセサイザには、リバーブ機能が含まれており、デフォルトで有効になっている。Waves TrueVerb リバーブ テクノロジが Microsoft にライセンスされており、SimpleVerb として実装されている。

DirectX 8.0 と共に使用される DLS Level 2 シンセサイザには、組み込みのリバーブ機能は含まれていない。その代わり、リバーブは DMO として実装されている。このために Waves MaxxVerb が Microsoft にライセンスされている。


音色とダウンロード

音色を再生するために、シンセサイザはその音色がどのように聞こえるかについての情報を持っている必要がある。この情報は、ウェーブ サンプルおよびアーティキュレーション データで構成され、DLS コレクションに格納される。音色のデータは、ダウンロードすることによってシンセサイザで使用できるようになる。

通常、1 つの音色のさまざまなノートは、同じ 1 つのサンプルに各ノートのピッチを割り当てることによって生成される。ただし、DLS Level 2 を使用すると、異なるサンプルまたはサンプルの組み合せに基づいて各ノートを生成できる。ノートのベロシティをトリガとして、基本の音色の異なるサンプルを使用することもできる。

デフォルトでは、Microsoft のソフトウェア シンセサイザは Roland GM/GS コレクションの DLS データを利用する。デフォルトのコレクションには、General MIDI 規格で定義されている 128 の音色の DLS データが含まれている。カスタム コレクションには、任意の種類の音色を含めることができる。音色のウェーブ サンプルは楽器の音色に基づいている必要はない。サウンド エフェクト、演説の一部、作成済みの完全な小節など、録音された任意のサウンドを使用できる。

必要なデータはデフォルトのコレクションに含まれているか、セグメントに関連付けられたバンド オブジェクトによって参照されるので、ほとんどのアプリケーションでは直接コレクションにアクセスする必要がない。バンドは、音色とパフォーマンス チャンネルにマップされた設定とのセットである。バンドの音色を使用する前にダウンロードされるようにするには、いくつかの手法がある。

注 Roland GM/GS Sound Set を修正することはできない。「法的情報」の「著作権に関する注意」を参照すること。

ウェーブ ファイルおよびリソースも、再生するにはシンセサイザにダウンロードする必要がある。


オーディオパスおよびバッファ

各 DirectMusic セグメントは、パフォーマンスからシンセサイザへのサウンドのフローを制御するオーディオパス上で再生され、次に DirectSound バッファでエフェクトが適用され、最後にプライマリ バッファで最終的な出力がミキシングされる。

注 ここで説明されているバッファは、シンセサイザから送信された後の PCM データのストリーミングおよび処理に使用され、IDirectSoundBuffer8 インターフェイスをサポートする。IDirectMusicBuffer8 インターフェイスによって表される別の種類のバッファは、シンセサイザへのメッセージ データをシーケンス化するために使用される。2 番目の種類のバッファは、DirectMusic のパフォーマンスによって管理されるので、ほとんどのアプリケーションではアクセスする必要はない。

アプリケーションは標準オーディオパスを作成し、そのオーディオパスでセグメントを再生できる。たとえば、ミュージック リバーブが設定されたバッファで MIDI ファイルを再生するオーディオパスと、3D コントロールが設定されたバッファでウェーブ ファイルを再生するオーディオパスをアプリケーションで作成できる。

DirectMusic Producer では、さらに高度なオーディオパスの構成からセグメントを作成できる。たとえば、標準以外の構成で、セグメント内のパートを異なる DirectSound バッファに送信し、異なるエフェクトを適用することができる。

オーディオパスは、データがストリーミングされる一連のオブジェクトと見なすことができる。アプリケーションはこれらのオブジェクトのすべてにアクセスできる。たとえば、バッファ オブジェクトを取得して音源の 3D プロパティを設定したり、エフェクト DMO を取得してエフェクトのパラメータを変更できる。


サウンド再生の基本的な手順

「DirectX Audio の基本的な概念」で説明されている基本的な項目を理解したら、次にアプリケーションで基本的なサウンドトラックを実装する。簡単な手順を学習した後、必要に応じてサウンドトラックを細かく制御するための API について学習することができる。

ここでは、コーディングの詳細には触れずに、必要な手順の概要について説明する。サンプル コードについては、「チュートリアル 1 : オーディオ ファイルの再生」を参照すること。

サウンドを生成するには、アプリケーションで次の処理を行う必要がある。

1. COM の初期化

DirectMusic オブジェクトを作成するためのヘルパー関数はないので、CoInitializeEx を呼び出して COM を初期化する必要がある。

2. パフォーマンスの作成と初期化

ほとんどのアプリケーションはパフォーマンス オブジェクトを 1 つだけ使用する。パフォーマンス オブジェクトは、CoCreateInstance を呼び出して、IDirectMusicPerformance8 インターフェイスを取得することによって作成できる。次に、IDirectMusicPerformance8::InitAudio を呼び出す。このメソッドによって、デフォルトのオーディオパスを設定できる。

3. ローダーの作成

CoCreateInstance を使用して、IDirectMusicLoader8 インターフェイスを取得する。この処理は一度だけ行う必要があり、アプリケーションを終了するまで同じローダー オブジェクトを使用する必要がある。

4. セグメントのロード

ローダーがデータ ファイルを見つけることができるように、IDirectMusicLoader8::SetSearchDirectory を呼び出す。次に、IDirectMusicLoader8::GetObject を呼び出してファイルまたはリソースからセグメントをロードし、その IDirectMusicSegment8 インターフェイスを取得する。

5. バンドのダウンロード

DLS データをシンセサイザにダウンロードすると、音色を再生できる。ウェーブ ファイルもダウンロードする必要がある。最も簡単な方法は、IDirectMusicSegment8::Download を呼び出す方法である。

6. セグメントの再生

セグメント ポインタを IDirectMusicPerformance8::PlaySegmentEx に渡す。

この処理の詳細については、次のトピックを参照すること。

  • オーディオ データのロード
  • サウンドの再生

注 DirectSound インターフェイスだけを使用してウェーブ サウンドを再生することもできる。ただし、このような処理を行うには、自分でデータ ソースを解析し、バッファへのデータのストリーミングを処理する必要がある。詳細については、「DirectSound でのウェーブの再生」を参照すること。


DirectX Audio プロジェクトの作成

プロジェクトには、DirectMusic のパフォーマンス レイヤの宣言を含む Dmusici.h ヘッダー ファイルをインクルードする必要がある。このファイルをインクルードすると、3 つの重要なヘッダーもインクルードされる。

  • Dmusicc.h:DirectMusic のコア レイヤの宣言
  • Dmerr.h:DirectMusic の戻り値
  • Dsound.h:DirectSound API

Dmusicf.h にはファイル構造および定義が含まれる。このヘッダー ファイルは、ファイルを直接操作したり、DirectMusic に組み込まれているローダーにまったく依存しない、ミュージック オーサリング ツールなどのアプリケーションに対してのみ必要となる。

Dmksctrl.h には、ポート プロパティの設定で使用される IKsControl インターフェイスの宣言が含まれている。Ksproxy.h および Ks.h ファイルがある場合、このファイルは必要ない。

Dmplugin.h には、IDirectMusicTool8 および IDirectMusicTrack8 インターフェイスの宣言が含まれる。これらのインターフェイスは、特殊なメッセージ処理ツールやトラック タイプを必要とする高度なアプリケーション用のアドオンで実装される。ほとんどのアプリケーションは、DirectMusic API のこの部分を使用しない。

DirectSound API を直接使用し、DirectSoundCreate8 などのヘルパー関数を使用する場合は、Dsound.lib にリンクし、ライブラリ検索パスに適切なフォルダを含める必要がある。

また、アプリケーションが DirectX Audio で使用される GUID にアクセスできるように注意する。詳細については、「DirectX のサンプルおよびその他の DirectX アプリケーションのコンパイル」を参照すること。

DirectX Audio は、Windows 32 ビット オペレーティング システムのマルチスレッド機能を使用する。マルチスレッドを利用することによって、アプリケーションが別のタスクを実行している間に、DirectX はバックグラウンドで音楽の生成、処理、および合成を行うことができる。マルチスレッドを念頭に置いて、プロジェクトを開発する必要がある。少なくとも、マルチスレッド ライブラリとリンクすること。


DirectX Audio について

ここでは、DirectMusic および DirectSound API の詳細には触れず、DirectX Audio の基本的な処理について説明する。「DirectX Audio の基本的な概念」で示されている概念の理解を深めることを目的としている。API の使い方については、「DirectX Audio の使い方」を参照すること。

説明するトピックは、次のとおりである。

  • DirectSound と DirectMusic
  • オーディオ データの流れの概要
  • アレンジ用のミュージック要素
  • 再生中の音楽の変化
  • ミュージック値と MIDI ノート
  • ダウンローダブル サウンド
  • オーディオ スクリプト


DirectSound と DirectMusic

以前のバージョンの DirectX では、2 つの独立したコンポーネントでオーディオ機能を提供していた。DirectSound と DirectMusic である。DirectSound はデジタル サンプル (ウェーブ) を再生およびキャプチャするためのもので、DirectMusic は単純な MIDI ファイルから、DirectMusic Producer で作成されるミュージック セグメントまで、さまざまなメッセージベースのデータを再生するためのものである。DirectMusic は、DLS を使用することによって音楽以外のサウンド エフェクトを再生できたが、以前はその重点は音楽の再生機能に置かれていた。

DirectX 8 では、DirectMusic インターフェイスがすべてのサウンドのロードおよび再生の主要なメカニズムである。サウンドがウェーブ フォーマット、MIDI フォーマット、DirectMusic Producer フォーマット、またはアドオン ローダーやツールで使用可能な任意の形式のどのファイルまたはリソースとして作成されているかは関係ない。

アプリケーションではウェーブの再生に DirectSound インターフェイスを使用することができ、ウェーブ キャプチャのための API として DirectSoundCapture が残されている。ただし、ほとんどのアプリケーションでは、DirectSound は DirectMusic シンセサイザからダウンストリームの処理を行う。シンセサイザからの出力をエフェクト フィルタにルーティングし、3D エフェクトを適用し、データを出力デバイスにストリーミングする前の最終的なミキシングを行う。

以前に DirectSound を使用していた場合は、ウェーブのロードおよび再生を DirectMusic インターフェイスに切り替えることによって、次のような利点がある。

  • ファイルやリソースを解析する必要がない。この処理は DirectMusic ローダーによって行われる。
  • DirectSound でサポートされていないウェーブ フォーマットについては、自動的に Windows オーディオ圧縮マネージャ (ACM) が使用される。
  • データの自動的なストリーミング。手動でバッファを作成したり、読み書きポインタを記録する必要がない。
  • タイミング制御の向上。DirectMusic マスタ クロックを使用して正確にサウンドをスケジュールできるだけでなく、サウンド エフェクトと音楽を容易に同期化できる。
  • サウンドの複数のインスタンスを容易に管理できる。

DirectMusic Producer ファイルに組み込まれるウェーブには、さらにいくつかの利点がある。エンベロープなどの DLS アーテイキュレーション エフェクトをウェーブに追加できる。セグメントに複数のバリエーションのウェーブを含めて、再生にランダムな要素を加えることができる。

これらの利点は、DirectSound によって提供される下位レベルの制御が失われることを意味しない。DirectMusic API によって、オーディオパスの任意のオブジェクトにアクセスできる。既存のバッファのインターフェイスを取得したい場合は、容易に取得できる。フィルタやエフェクトを追加するために、DirectSound API のすべての新機能を利用することもできる。


オーディオ データの流れの概要

一般的に、DirectX Audio アプリケーションは、次に示すような 1 つまたは複数のソースからミュージック データを取得する。

  • MIDI ファイル
  • ウェーブ ファイル
  • DirectMusic Producer または類似のアプリケーションで作成されたセグメント ファイル
  • DirectMusic Producer などのアプリケーションでオーサリングされ、コンポーザ オブジェクトによって完全にアレンジされたコンポーネント ファイル

注 これらのデータ ソースは、個別のファイルではなく、リソースとしてアプリケーションに格納することができる。

これらのソースからのデータは、セグメント オブジェクトにカプセル化される。各セグメント オブジェクトは、1 つのソースからのデータを表す。パフォーマンスのある時点では、1 つのプライマリ セグメントと任意の数のセカンダリ セグメントを再生できる。ソース ファイルは混在させることができる。たとえば、ウェーブ ファイルに基づくセカンダリ セグメントを、オーサリングされたセグメント ファイルと共に演奏することができる。

1 つのセグメントには 1 つ以上のトラックが含まれ、それぞれがノートやテンポの変更など、特定の種類のタイム データを含んでいる。ほとんどのトラックは、セグメントがパフォーマンスによって再生されるときに、タイムスタンプ メッセージを生成する。一部のトラックは、パフォーマンスから問い合わせがあったときに、データだけを提供する。

まず、パフォーマンスは、アプリケーションが定義したツールにメッセージをディスパッチする。それらのツールはセグメント ツールグラフにグループ化される。セグメント ツールグラフは、特定のセグメントからのメッセージ、そのオーディオパスで再生されるすべてのセグメントからのメッセージのオーディオパス ツールグラフ、すべてのセグメントからのメッセージを受信するパフォーマンス ツールグラフのみを処理する。ツールでメッセージを変更して渡したり、削除したり、新しいメッセージを送信することができる。

最終的に、メッセージは出力ツールに到達する。出力ツールで、データは MIDI フォーマットに変換されてからシンセサイザに渡される。チャンネル固有の MIDI メッセージは、シンセサイザの適切なチャンネル グループに転送される。シンセサイザはサウンド ウェーブを作成し、シンクと呼ばれるデバイスにストリーミングする。シンクは、バスを介した DirectSound バッファへのデータの配信を管理する。

バッファには、以下の 3 つの種類がある。

  • シンクイン バッファは、シンクがデータをストリーミングする DirectSound のセカンダリ バッファである。このバッファは、必要に応じて、データ形式をプライマリ バッファのデータ形式に変換し、アプリケーションがパン、ボリューム、3D 空間の広がり、およびその他のプロパティを制御できるようにする。また、エフェクト モジュールを介してデータを渡し、リバーブやエコーなどのエフェクトを追加することもできる。生成されたウェーブフォームは、プライマリ バッファに直接渡されるか、1 つ以上のミックスイン バッファに渡される。
  • ミックスイン バッファは、ほかのバッファからデータを受け取り、エフェクトを適用し、ウェーブフォームをミキシングする。このバッファを使用して、グローバル エフェクトを適用できる。データをミックスイン バッファに送信することによって得られるエフェクトをセンドと呼ぶ。
  • プライマリ バッファは、すべてのデータの最終的なミキシングを行い、レンダリング デバイスに渡す。

注 アプリケーションでは、DirectMusic のパフォーマンスの一部であるセカンダリ バッファを介してデータをストリーミングする必要はない。アプリケーションでは、エフェクトを追加したり、プロパティを変更するために、バッファ オブジェクトを取得できるが、DirectSound API を使用してウェーブ サウンドを再生する場合のように、バッファをロックして書き込むことはできない。

次の図は、ファイルからスピーカへのデータ フローの概略図である。複数のセグメントを同時に再生できるが、ここでは 1 つのセグメントだけが示されている。セグメントは、4 つのソースのいずれかのみからデータを取り出す。使用できるソースは、ウェーブ ファイル、MIDI ファイル、DirectMusic Producer で作成したセグメント ファイル、およびコンポーザ オブジェクトによって結合されたコンポーネント ファイルのいずれかである。

注 いずれの場合も、ファイルではなく、リソースのデータを使用できる。

パフォーマンスにおけるメッセージの流れを詳細に確認するには、「DirectMusic メッセージの使い方」を参照すること。

この図に示されているプロセスの実装方法については、「オーディオ データのロード」および「サウンドの再生」を参照すること。


アレンジ用のミュージック要素

DirectX Audio を最大限に活用すると、MIDI ファイルやウェーブ ファイルの再生以外の処理も行うことができる。DirectMusic Producer などのアプリケーションでオーサリングされたミュージック要素を利用して、さまざまな方法で変更または操作できるパフォーマンスを作成できる。

注 このマニュアルでは、DirectMusic のコンポーザ オブジェクトとの混同を避けるために、ミュージック要素を作成する人間のコンポーザ (作曲者) をオーサーと表現する。同様に、ミュージック要素は、作曲ではなく、オーサリングするという。

以下に示すこれらの要素の簡単な説明とそのオーサリング方法は、アプリケーション開発者がパフォーマンスで使用されるマテリアルを理解できるようにするためのものである。詳細については、DirectMusic Producer のマニュアルを参照すること。これらの要素をアプリケーションに組み込む方法については、「アレンジ要素の使い方」を参照すること。

次のアレンジ要素について説明する。

  • スタイル
  • コードマップ
  • スタイル ベースのセグメント
  • MIDI ベースのセグメント
  • テンプレート
  • バンド


スタイル

スタイルは、ダイナミック スコアの作成に使用される音楽パターンのコレクションである。また、拍子記号やテンポを含み、1 つまたは複数のバンドを含むこともできる。

パターンは、1 小節以上の長さの音型で、各音色の基本的な一連のノート、つまりパートで構成される。これらのノートは固定されていないが、最終的には、現在のキー、コード、および演奏モードに応じて、特定のピッチに割り当てられる。パターンには、バリエーションも含まれる。

モチーフは、基本スコア上でダイナミックに演奏されるようにデザインされた、特殊なパターンである。通常、モチーフはインタラクティブ アプリケーションでイベントをマークするために使われる。

DirectMusic Producer では、オーサーはピアノ ロールに似たグリッドを使ってパターンを作成する。各パートは (パフォーマンス チャンネルに対応する) 独自の行を持ち、ノートはバーの長さ (持続時間)、太さ (ベロシティ)、縦軸方向の位置 (ピッチ)、および横軸方向の位置 (時間) で表される。

オーサーは、各パターンに対して多くのバリエーションを作成することができる。通常は、パターンをコピーして一部をわずかに変更することにより、バリエーションを作成できる。スタイルの再生メカニズムによって、実行時にバリエーションが選択される。ただし、オーサーは任意のコードに対してバリエーションを無効にすることもできる。つまり、特定のコードが演奏されているときは、あるバリエーションを決して選択しないよう指定できる。

オーサーは、パターンにグルーブ範囲を割り当てて、パターンを演奏できるグルーブ レベルを指定することもできる。

パターンは、装飾として指定することもできる。装飾には、イントロ、フィル、ブレーク、エンド、およびカスタムの 5 種類があり、これらの 1 つまたは複数のカテゴリに、パターンを割り当てることができる。音楽の演奏中に特定の装飾が呼び出されると、その種類のパターンのみが再生の候補となる。


コードマップ

現代の音楽の多く、特にポピュラー、ロック、フォーク、ジャズの特色はコード進行の概念に基づいており、特定の時間枠に演奏されるすべてのノートが特定のコードに関連付けられていること、および音楽はあるコードから別のコードへと調和的に移行することを意味する。

DirectMusic 用にオーサリングされたパターンにあるノートは、1 つのコードから派生しているか、コードと調和するよう意図されたものである。しかし実行時に、パターンはコード進行に合わせて転置する。つまりベース コードの変化に応じて、DirectMusic はノートのピッチを変更する。

コードマップは、コード進行のロード マップである。コードマップ デザイナを使って、オーサーは希望の音楽感やパーソナリティを表現できるコードを選択する。これらのコードは、タイム ラインに沿ったフローチャートに従ってアレンジされる。タイム ラインには循環という概念があるので、ミュージック セクションの演奏が続く間、最初に戻ってループを形成する。

特定の重要なコードをサインポストとして指定する。これらは、特定のポイントで演奏されなければならないコードである。音楽は、常にサインポストからサインポストへと移行する。しかし、サインポスト間のコード進行は、オーサーの指定したマップに従ってさまざまなルートをたどることもできる。

コード チャート内のルートは、コンポーザ エンジンによって実行時に選択することができる。この場合、パターン自体のバリエーションに追加してバリエーションが提供される。オーサーがセグメントを作成する際に、オーサリング ツールを使ってルートを選択することもできる。

コードマップのコードは、サブコードと呼ばれる、複数の異なるコードで構成することができる。同じコードを異なる転回で演奏して多調性を得るために、オーサーは異なるサブコードに別のパートを割り当てることができる。各サブコードは、1 つまたは複数のレベルで有効であり、スタイルのポートに割り当てられたレベルで調和する。


スタイル ベースのセグメント

スタイル ベースのセグメントは、あらかじめ作成された、音楽の大きなピースであり、オーサーは次の要素を使ってセクションを構築する。

  • スタイル。スタイルは、パターンと同様、音楽に関する一般的な情報 (拍子記号やテンポなど) で構成される。「スタイル」を参照すること。
  • コード進行。オーサリング ツールがコードマップから自動的に派生したもの (コード チャートからパスを選択する)、またはオーサーが手作業で入力したもの。
  • コマンド トラック。DirectMusic Producer のグルーブ トラックとして知られているこのトラックは、設定時の適切なパターンを選択するための一連のコマンドである。スタイル中のパターンの特徴は、装飾 (イントロ、フィル、ブレーク、およびエンド) として指定できること、およびオーサーが特定のグルーブ範囲を割り当てることができることである。セグメントのコマンド トラックは、スタイル再生エンジンに対して、イントロ パターンを選択して最初の小節で演奏し、次の 4 小節でグルーブ レベルが 25 のパターンのみを再生した後、ブレークを演奏する、などの動作を指示することができる。
  • バンド。オーサーは、音色とパフォーマンス チャンネルを、さまざまなパターンのすべてのパートに割り当てることができる。


MIDI ベースのセグメント

MIDI ベースのセグメントは、普通は MIDI ファイルをインポートして DirectMusic Producer で作成し、ここでオーサーは、ループ ポイントだけでなく、テンポ、キー、バンドの変更を追加できる。スタイル ベースのセグメントと異なり、MIDI セグメントにはパターンおよびコマンド トラックがない。これらの代わりにシーケンス トラックがあり、MIDI ノートとその他のコマンドはここに含まれる。


テンプレート

テンプレートは、サインポスト トラックとコマンド トラック (オプション) を格納できる。サインポスト トラックを使用して、そのセグメント自体またはサインポスト トラックを持たない別のセグメントの新しいコード進行を作成できる。コマンド ドラックは、グルーブ レベルおよび装飾を提供する。実行時にテンプレートを使用して、新しいマテリアルを作成することもできる。

注 DirectX 8.0 以前のバージョンの DirectMusic Producer で作成したテンプレートは、再生可能な独立したセグメントではない。これらは、ほかのセグメントをアレンジするためにだけ使用できる。

サインポスト トラックには、コード進行のバリエーションが認められるリージョンの先頭と最後をマークする一連のサインポスト マーカーが含まれる。各サインポスト マーカーは、コードマップ内の特定のグループのサインポスト コードについてのみ有効である。コンテンツのオーサーは、サインポスト マーカーおよびサインポスト コードを適切なグループに割り当てる必要がある。

DirectMusic では、サインポスト トラックを特定のスタイルおよびコードマップに適用することによってセグメントをアレンジする。テンプレート内のタイム ラインに沿ってコンポーザがサインポスト マーカー ペアを見つけるたびに、コンポーザはそのグループに所属するサインポスト コードのペアに対応するコードマップを検索する。ペアが見つかり、そのペア間の間隔が利用可能な時間に適合する場合は、エンジンはコードマップで定義されている 2 つのサインポスト コード間の固定コード進行に従う。ペア間の適切なパスが見つからない場合や、エンド サインポスト マーカーが存在しない場合は、エンジンは開始サインポスト マーカーから派生した任意のコードを演奏する。

アプリケーションでテンプレートからセグメントをアレンジする方法については、「テンプレートの使い方」を参照すること。


バンド

バンドとは一連の音色にそれぞれのパフォーマンス パラメータを組み合わせ、音楽のピース内の特定のパートを組み合わせたものである。バンドは DLS コレクションと同じではない。DLS コレクションはシンセサイザにダウンロードできる音色のセットを表し、任意のアプリケーションから利用することができる。

オーサーは DirectMusic Producerのようなツールを使って、音色をパフォーマンス チャンネルに割り当てることによりバンドを作成する。これらの音色は任意の DLS コレクションから取得することができ、別のソースの音色を 1 つのバンドに混在させることもできる。それぞれの音色には、ボリューム、パン、転調が設定される。

パフォーマンス チャンネルは、音色をパートに割り当てる。パターンがチャンネル 1 の特定のノートを呼び出す場合、このノートはチャンネル 1 に割り当てられている現在のバンドの音色で演奏される。サウンドは、バンドで設定されている音色のボリューム、パン、および転調の値で修正される。

バンドは個別のファイルに保存するか、スタイルやセグメントに含められる。


再生中の音楽の変化

DirectMusic がスタイルベースのセグメントを演奏するとき、基本的な和音とリズムに変更が加えられるので、演奏に変化が表われる。変更の一部はスクリプト化され、一部はランダムに行われる。

  • パターンの選択。一般的なスタイルには複数のパターンが含まれる。これらのパターンは、コマンド トラックからのコマンドに応じて選択される。たとえば、コマンド トラックがブレーク装飾の演奏を要求すると、スタイル再生エンジンは現在のグルーブ レベルに矛盾しないブレーク パターンを選択する (オーサーは、各パターンにふさわしいグルーブ レベルを指定する)。適切なパターンがいくつかある場合は、オーサーによってセグメントに埋め込まれたルールに従ってパターンが選択される。パターンは完全または部分的にランダムに選択されることもあれば、特定のシーケンスで選択されることもある。
  • パターン内のバリエーション。パターン内のパートには、複数のバリエーションを設定することができる。バリエーションは、オーサーが指定した順序で演奏することができる。それ以外の場合は、パターンの各繰り返しにおいて、スタイル再生エンジンがバリエーションをランダムに選択する。
  • グルーブ レベル。セグメントの現在のグルーブ レベルにより、スタイル内のどのパターンを再生用に選択できるかが決まる。現在のレベルを設定するのはコマンド トラックであるが、コマンド トラックは通常、セグメントかテンプレートの一部としてオーサリングされる。セグメントの現在のグルーブ レベルは、プログラム的に変更することができる。パフォーマンスのマスタ グルーブ レベルを設定することで、変更をすべてのセグメントに適用することができる。
  • 転調。セグメントを演奏するときに、ベース コードはコード トラックの進行に従って変化する。現在のパターンのノートは、新しいコードと調和するよう、自動的に転置される。
  • タイミングのバリエーション。再生エンジンは、個々のノートのパラメータ、つまりノートの開始時期と終了時期に、ランダムな変更を加えることができる。
  • バンド。セグメントの演奏中に、音色と音色の設定 (ボリューム、パン、および転調) の選択を、オーサリングされたセグメント内のバンド トラックで変更したり、アプリケーションで動的に変更することができる。アプリケーションでバンドを変更するには、バンド オブジェクトに基づくセカンダリ セグメントを作成してそのセグメントを演奏するか、演奏中のセグメントのバンド トラック上にパラメータを設定する。

アプリケーションはほとんどの場合、既存のセグメントを操作するのではなく、別のセグメントを演奏して音楽全体を制御する。たとえば、ゲームのインテンシティの変化を音楽に反映させるには、インテンシティ レベルに応じてオーサリングされた新しいセグメントにトランジションするだけでよい。オーサーにグルーブ範囲の異なるパターンを作成させ、ゲーム イベントに応じてグルーブ レベルを変更すると、1 つのスタイル ベースのセグメントでも同様のエフェクトを得ることができる。


ミュージック値と MIDI ノート

DirectMusic スタイル内のパターンのノートは、固定されたノートではない。これらのノートは、現在の演奏モードとサブコード レベルに応じて現在のコードに転置されたときにだけ実際のノートとなる、ミュージック値である。

ミュージック値は、ノートの意図的な役割を表すものである。たとえば、ミュージック値で、ノートをコードの 2 番目の位置、1 つ上のスケールで演奏するように指定することができる。このミュージック値が特定のコードに適用されると、そのコードの 2 番目で、1 つ上のスケールの適切な MIDI ノートに変換される。

コードに対してノートがどのように解釈されるかは、演奏モードによって異なる。たとえば、モードが DMUS_PLAYMODE_NORMALCHORD の場合、ノートはコードのルート音に基づいて、コードとスケールの音程として解釈される。モードが DMUS_PLAYMODE_FIXEDTOKEY の場合、ノートは線形な値として解釈される。

複数の並行するコード進行を使って複雑な和音を可能にするために、DirectMusic コードは複数のサブコードで構成できる。サブコード レベルは 0 ～ 31 の値で、ミュージック値の確立に使用できるコードのサブコードを決定する。各サブコードは、オーサーの定義に従って、1 つまたは複数のレベルで有効である。DirectMusic Producer は、1 つのコードに対して最高 4 つのサブコードをサポートする。

セグメントが演奏されるときに、各ノートはメッセージ構造体にカプセル化される。この構造体は、元のミュージック値および最終的な MIDI ノートと共に、転調で使用される演奏モードとサブコード レベルを指定する。ほとんどのアプリケーションはノートメッセージを直接処理しないが、ツールを使ってこのメッセージを処理し、ノートを変更することができる。たとえば、ツールは特定の演奏モードで転置されるノートを割り込んで取得したり、演奏モードを変更したり、メッセージが渡される前に新しい MIDI 値を計算することができる。

ミュージック値、演奏モード、コード、およびサブコードについては、次のトピックを参照すること。

  • DMUS_NOTE_PMSG
  • DMUS_PLAYMODE_FLAGS
  • DMUS_CHORD_PARAM
  • DMUS_CHORD_KEY
  • DMUS_SUBCHORD
  • IDirectMusicPerformance8::MIDIToMusic
  • IDirectMusicPerformance8::MusicToMIDI


ダウンローダブル サウンド

これまで、ほとんどのコンピュータ音楽は、次の 2 つの方法のいずれかで生成されていた。それぞれに利点はあるが、欠点もある。

  • 通常は .WAV ファイル、またはレッドブック オーディオ規格に従った標準的な CD トラックに記録されているデジタル サンプルからウェーブフォーム (波形) を再現する方法。デジタル サンプルではどのようなサウンドも再現可能で、どのサウンド カードを使った場合でも得られる出力は非常によく似ている。ただし、ストリーミング用に多くの記憶領域とリソースが必要となる。
  • 一般的には MIDI ファイルからのメッセージに応答して、音色のサウンドを通常はハードウェアで合成する方法。MIDI ファイルはコンパクトで、ストリーミング リソースもわずかしか必要としないが、出力は General MIDI セットのシンセサイザで利用できる音色の数に限定され、システムによっては非常に異なった音になる場合がある。

デジタル サンプリングの利点と、MIDI のコンパクトさ、および柔軟性を組み合わせる 1 つの方法が、ウェーブテーブル合成である。これは、デジタル サンプルから音色のサウンドを合成する方法である。実際の音色をレコーディングすることによってサンプルを取得し、ハードウェアに保存する。さまざまなピッチとボリュームで任意の長さのサウンドを作成するために、サンプルのループと調整が行われる。

ウェーブテーブル合成はアルゴリズムに基づく FM 合成より現実的なティンバーを作成するが、依然として固定セットの音色に限定される。さらに特定の音色のサウンドはメーカーの実装によって異なり、ハードウェアの組み合わせが異なると非常に異なったサウンドになる場合がある。

次に、MIDI Manufactures Association によって発表された、ダウンローダブル サウンド (DLS) 規格がある。DLS は、システムにハードワイアードで実装されたサンプルの代わりに、実行時に提供されるサンプルに基づいてウェーブテーブル合成を行うことができる方法である。音色を記述するデータはシンセサイザにダウンロードされ、その後はほかの MIDI 音色と同様にその音色を演奏できる。DLS はアプリケーションの一部として配信できるため、開発者はサウンドトラックをすべてのシステムで同じように演奏させることができる。また、音色の選択が制限されることもない。

DLS 音色は 1 つまたは複数のサンプルから作成され、通常はシングル ピッチを表すが、シンセサイザで変更を加えることによりその他のピッチを作成できる。広範囲のピッチで音色のサウンドを現実的にするには、複数のサンプルを使う。DLS 音色をダウンロードする際に、リージョンと呼ばれる特定のピッチ範囲が各サンプルに割り当てられる。

DLS Level 2 では、すべてのノートにそれぞれのリージョンを割り当てることができる。また、各リージョンのティンバーをレイヤと呼ばれる複数のサンプルから作成したり、ノートのベロシティに応じて異なるレイヤをトリガすることができる。これによって、1 つの音色から無数のサウンドを作成できる。

加えて、サンプルにアーティキュレーションを与えることもできる。これはサウンドを実際の音色により近づけるための特徴を定義する。アーティキュレーションには、サウンドのボリュームやピッチのエンベロープおよびビブラートやトレモロを提供する低周波数発振器 (LFO) が含まれる。

サンプルは、ループ可能にすることも、単発にすることもできる。ループ可能なサンプルは、ノートの継続時間の間、繰り返し演奏される。単発のサンプルは一度だけ演奏される。

DLS データは音色コレクションに格納され、ここからシンセサイザにダウンロードされる。

ほかの MIDI 音色の場合と同様に、DLS 音色にはパッチ番号が割り当てられ、MIDI メッセージに応答する。ただし、DLS 音色 (機器) は General MIDI セットに従う必要はない。実際、ミュージックの音色である必要はまったくない。演説の一部や作成済みの完全な小節など、どんなサウンドでも DLS 音色に関連付けることができる。

DLS コレクションと DLS 音色の作成方法の詳細については、DirectMusic Producer のドキュメントを参照すること。DLS 規格の詳細については、MIDI Manufacturers Association から入手可能な『Downloadable Sounds Level 2』を参照すること。

ほとんどのアプリケーションは音色や DLS データを直接扱う必要がない。コレクションを開いたり、音色データをダウンロードする処理は、バンド オブジェクトによって実行される。バンドをダウンロードすると、そのバンドに関連付けられているすべての音色データもダウンロードされる。詳細については、「バンドの使い方」を参照すること。


オーディオ スクリプト

オーディオ スクリプトは、アプリケーション内からアクセスできる変数とルーチンを含むファイルである。Microsoft® Visual Basic® Scripting Edition の AudioVBScript と呼ばれるサブセットで記述される。DirectMusic Producer にはスクリプトのオーサリング環境が含まれており、スクリプトはバイナリ パラメータとスクリプトのテキストを含む特殊な形式で保存される。

スクリプトは主な DirectX Audio オブジェクトのいくつかを実装し、次のような基本的な機能を実行できる。

  • オーディオパスの作成
  • オーディオパスのボリュームの設定
  • パフォーマンスのグローバル パラメータの設定
  • セグメントのロード、演奏、および停止
  • バンドのダウンロード

DirectX Audio スクリプトは、アプリケーション開発者とサウンド作成者が容易に共同で作業できるようにすることを目的としている。スクリプトによって、サウンド作成者はサウンドトラックを細かく、直接制御することができる。サウンドのロードや演奏の基本的な機能はスクリプトによって実行される。アプリケーションには、スクリプトを呼び出す一般的なコードが含まれる。

ここでは、スクリプトを使用する利点について例を挙げて説明する。

あるゲームのサウンド エフェクトが個々のウェーブ ファイルに保存されているとする。ゲームでは、武器の発射音やモンスターのうなり声などのイベントにこれらのサウンドを使用する。従来のプログラミング手法では、開発者は個々のサウンドをファイル名を指定してロードし、ゲームの適切なポイントでセカンダリ セグメントとして演奏していた。

サウンド作成者が、サウンドを変更しようとした場合を考えてみる。たとえば、モンスターのボスのうなり声を手下とは異なるうなり声に変更したいとする。サウンド作成者は必要なファイルを作成し、コードで変更を実装する開発者に渡す。サウンド作成者が新しくコンパイルされたゲームを受け取って、テストするまでには相当な時間がかかる。

同じ状況で、オーディオ スクリプトを使用する場合を考えてみる。実際のサウンドをアプリケーションにハードコーディングする代わりに、開発者はうなり声に対応する次のようなコードを記述する。ここでは、szGrunter が "Player"、"Boss" または "Minion" などの文字列定数に設定されており、pdmScript はスクリプト オブジェクトへのインターフェイスであると仮定する。

pdmScript->SetVariableVariant("Grunter", szGrunter, NULL);
pdmScript->CallRoutine("PlayGrunt", NULL);

このコードでは、スクリプト内の Grunter 変数の値を設定し、PlayGrunt スクリプト ルーチンを呼び出している。スクリプトの作成者、通常はサウンド設計チームのメンバーがルーチンの処理を決定する。たとえば、再生するサウンドを決定する前に、"Grunter" の値をテストするなどである。

ゲームの状況に対する応答を変更するには、スクリプトのテキストを変更するだけで済み、新しいルーチンを既存のアプリケーションで直ちにテストできる。

スクリプティング API は DirectMusic Producer のヘルプ ファイルで説明されている。アプリケーションでスクリプトを実装する方法については、「オーディオ スクリプトの使い方」を参照すること。

注 オーディオ スクリプトは Web ページで使用するようには設計されていない。


DirectX Audio の使い方

ここでは、アプリケーション開発における Microsoft® DirectMusic® および Microsoft® DirectSound® API の使用方法を説明する。

説明するトピックは、次のとおりである。

  • オーディオ データのロード
  • サウンドの再生
  • パフォーマンス パラメータ
  • オーディオパスの使い方
  • 3D サウンド
  • エフェクトの使い方
  • バッファ チェーン
  • アレンジ要素の使い方
  • オーディオ スクリプトの使い方
  • DirectSound でのウェーブの再生
  • サウンド キャプチャ

一般的な概要については、「DirectX Audio 入門」を参照すること。

基本的なデータ フローのメカニズムについては、「DirectX Audio について」を参照すること。

特殊なアプリケーションで使用される高度な機能については、「DirectX Audio の高度なトピック」を参照すること。


オーディオ データのロード

DirectMusic オブジェクトをパフォーマンスに組み込む前に、それらをファイルまたはリソースからロードしなければならない。IDirectMusicLoader8 インターフェイスは、これらのオブジェクトの列挙およびロードを管理するために使用される。また、キャッシュすることによってオブジェクトのロードが一度で済むようにするためにも使用される。

アプリケーションでは、既存のローダーのインスタンスを、一度に 1 つだけ使用するべきである。1 つのグローバル ローダー オブジェクトを作成し、ロードがすべて終了するまでオブジェクトを解放しないようにする。この方法により、オブジェクトが効果的に検索およびキャッシングされる。

DirectMusic における IStream の実装により、データがソースからストリームに入れられる。データの解析は、IPersistStream の実装を通して、さまざまなオブジェクト自身によって処理される。標準的な DirectMusic データだけを処理する場合は、これらのインターフェイスを直接使用する必要はない。

ほかのオブジェクトによって参照されるオブジェクトのロードは、透過的に処理される。たとえば、DirectMusic Producer からロードされるスタイルに、ほかのファイルにデータがあるバンドへの参照が含まれているとする。スタイルの IPersistStream は参照を見つけると、データ ストリームを渡した IStream から IDirectMusicGetLoader8 インターフェイスを取得する。このインターフェイスを使用して、ローダー オブジェクトへのポインタを取得する。続いて、IDirectMusicLoader8::GetObject を呼び出して、バンドをロードする。

ローダーの使用方法の詳細については、次のトピックを参照すること。

  • ローダーの検索ディレクトリの設定
  • ディレクトリでのオブジェクト検索
  • オブジェクトの列挙
  • ファイルからのオブジェクトのロード
  • リソースからのオブジェクトのロード
  • コンテナ
  • オブジェクト ディスクリプタの取得
  • キャッシュの管理
  • ガベージ コレクション
  • オブジェクトの設定

「DirectX Audio の高度なトピック」の「カスタム ロード」も参照すること。


ローダーの検索ディレクトリの設定

検索対象のオブジェクトを記述する DMUS_OBJECTDESC 構造体の wszFileName メンバがフル パスを指定していない限り、ローダーはデフォルトでカレント ディレクトリを検索する。IDirectMusicLoader8::SetSearchDirectory メソッドを使うと、IDirectMusicLoader8::GetObject、IDirectMusicLoader8::LoadObjectFromFile、および IDirectMusicLoader8::EnumObject の各メソッドで異なるデフォルト パスを設定できる。このデフォルト パスをすべてのオブジェクトに適用することも、特定のクラスのオブジェクトだけに適用することもできる。

次のサンプル コードでは、スタイル ファイルの検索パスを設定している。

HRESULT mySetLoaderPath (
    IDirectMusicLoader8 *pILoader)    // 以前に作成された。
{
    return pILoader->SetSearchDirectory(
            CLSID_DirectMusicStyle,
            L"c:\\mymusic\\funky",
            FALSE);
}

この関数を呼び出しておくと、アプリケーションは、フル パスを指定せずにファイル名だけを使ってスタイルをロードできる。


ディレクトリでのオブジェクト検索

IDirectMusicLoader8::ScanDirectory メソッドは、特定のクラスのオブジェクトを現在の検索ディレクトリで探す。サブクラスと、"*" 以外のファイル拡張子を指定することにより、検索範囲を狭められる。

このメソッドは一致するすべてのファイルから成るリストを作成し、IDirectMusicObject8::ParseDescriptor メソッドを使ってオブジェクトの GUID と名前を抽出する。これらの識別子は内部データベースに保持されるので、アプリケーションはそれ以降、ファイル名ではなく GUID や名前を使ってオブジェクトをロードできる「ファイルからのオブジェクトのロード」を参照すること。

注 DirectMusic Producer で作成したコンテンツの場合、オブジェクトをロードする前に、必ず IDirectMusicLoader8::ScanDirectory を呼び出すことを推奨する。ファイル名を明示的に指定してオブジェクトをロードする場合でも、これらのオブジェクトにはファイル名で指定されていないほかのオブジェクトへの参照が含まれている場合がある。オブジェクトが格納されている各ディレクトリに対して ScanDirectory が呼び出されていない場合、ローダーはこれらの参照されているオブジェクトを見つけることができない。

ScanDirectory メソッドの pwszScanFileName パラメータに、文字列へのポインタを含めると、その名前を持つファイルに検索結果がキャッシングされ、それ以降の検索が高速化される。キャッシュ ファイルを利用できる場合、このメソッドはタイム スタンプやサイズが変更されているファイルに限ってオブジェクト情報を更新する。

注 現在のバージョンの DirectMusic では、ScanDirectory はキャッシュ ファイルを使用しない。キャッシュ ファイルの実装は、現在でも可能である。これにより、今後のバージョンでパフォーマンスが向上する。

例については、「オブジェクトの列挙」を参照すること。


オブジェクトの列挙

IDirectMusicLoader8::EnumObject メソッドを使って、IDirectMusicLoader8::ScanDirectory または IDirectMusicLoader8::GetObject のどちらかを呼び出して内部データベースに記録した、特定のクラスまたは全クラスの全オブジェクトを補間する。見つかった各オブジェクトの説明は、DMUS_OBJECTDESC 構造体に返される。

注 全オブジェクトを確実に見つけるには、最初に ScanDirectory を呼び出しておく。EnumObject はディスク ファイルを解析するのではなく、内部データベースでオブジェクトをチェックする。

次の例では、現在の検索ディレクトリに記録されているすべてのスタイル オブジェクトを列挙し、デバッギング マクロ TRACE を使ってそれらの情報を 1 つずつ表示している。そのクラスで列挙すべきオブジェクトがなくなるまでループは続行される。

void myListStyles(
        IDirectMusicLoader *pILoader)

{
    HRESULT hr = pILoader->SetSearchDirectory(
            CLSID_DirectMusicStyle,
            L"c:\\mymusic\\wassup",
            TRUE);
    if (SUCCEEDED(hr))
    {
        hr = pILoader->ScanDirectory(
                CLSID_DirectMusicStyle,
                L"sty",
                L"stylecache");
        if (hr == S_OK)    // ファイルが見つかった場合のみ。
        {
            DWORD dwIndex;
            DMUS_OBJECTDESC Desc;
            Desc.dwSize = sizeof(DMUS_OBJECTDESC);
            for (dwIndex = 0; ;dwIndex++)
            {
                if (S_OK ==(pILoader->EnumObject(
                        CLSID_DirectMusicStyle,
                        dwIndex, &Desc)))
                {
                    TRACE("Name: %S, Category: %S, Path: %S\n",
                            Desc.wszName,
                            Desc.wszCategory,
                            Desc.wszFileName);
                }
                else break;
            }
        }
    }
}

この例では、メソッド呼び出しの結果をテストする目的で、SUCCEEDED マクロを使っていない点に注意すること。不適切なインデックス番号を指定した場合、EnumObject が成功コードの S_FALSE を返すためである。


ファイルからのオブジェクトのロード

オブジェクトをロードするには、次の例に示すように、最初に IDirectMusicLoader8 インターフェイスを取得する。

IDirectMusicLoader8* m_pLoader;

CoInitializeEx(NULL, 0);
HRESULT hr = CoCreateInstance(
    CLSID_DirectMusicLoader,
    NULL,
    CLSCTX_INPROC,
    IID_IDirectMusicLoader8,
    (void**)&m_pLoader);

次に、IDirectMusicLoader8::LoadObjectFromFile または IDirectMusicLoader8::GetObject のいずれかを使用して、ファイルからオブジェクトをロードできる。前者は、DMUS_OBJECTDESC 構造体を使用してオブジェクトを記述する必要がないので便利である。

次のサンプル コードでは、以前に IDirectMusicLoader8::SetSearchDirectory で設定されたディレクトリから 4 つのセグメントをロードしている。

IDirectMusicSegment8 * m_pSegments[4];

static WCHAR  wszNames[4][MAX_PATH] = {
    L"AudioPath1.sgt",
    L"AudioPath2.sgt",
    L"AudioPath3.wav",
    L"AudioPath4.sgt"
};

for (DWORD dwIndex = 0; dwIndex < 4; dwIndex++)
{
    hr = m_pLoader->LoadObjectFromFile(
            CLSID_DirectMusicSegment,
            IID_IDirectMusicSegment8,
            wszNames[dwIndex],
            (void**) &m_pSegments[dwIndex]);
}

次の例では、IDirectMusicLoader8::GetObject を使用してファイルからスタイル オブジェクトをロードしている。最初のパラメータは、スタイルへのポインタを受け取る。

void myLoadStyle(
    IDirectMusicStyle8 **ppStyle, IDirectMusicLoader8 *pLoader)
{
    if (pLoader)
    {
        DMUS_OBJECTDESC Desc;

        // スタイル オブジェクトのファイル名とクラス GUID を使って、
        // Desc を初期化することから開始する。

        wcscpy(Desc.wszFileName,L"c:\\mymusic\\funky\\polka.sty");
        Desc.guidClass = CLSID_DirectMusicStyle;
        Desc.dwSize = sizeof (DMUS_OBJECTDESC);
        Desc.dwValidData = DMUS_OBJ_CLASS |
                           DMUS_OBJ_FILENAME |
                           DMUS_OBJ_FULLPATH;

        pLoader->GetObject(&Desc, IID_IDirectMusicStyle8,
                (void **) ppStyle);
    }
}

この例では、ファイルをフル パス名で指定し、これを DMUS_OBJ_FULLPATH フラグを設定して指示している。

検索対象の特定のファイル オブジェクトを識別するには、DMUS_OBJECTDESC 構造体の wszName、guidObject、wszFileName の各メンバのいずれかに値を入力し、dwValidData メンバに適切な 1 つまたは複数のフラグを設定する。wszFileName ではなく wszName か guidObject を使ってファイルを識別する場合は、IDirectMusicLoader8::ScanDirectory メソッドを呼び出して、カレント ディレクトリ内の GUID と名前を利用可能にしなければならない。詳細については、「ディレクトリでのオブジェクト検索」を参照すること。

「リソースからのオブジェクトのロード」も参照すること。


リソースからのオブジェクトのロード

リソースとして格納されたオブジェクトまたはメモリ内の別の場所に格納されたオブジェクトは、ファイル オブジェクトと同様にロードされる。「ファイルからのオブジェクトのロード」を参照すること。

ただし、メモリ オブジェクトの場合、DMUS_OBJECTDESC 構造体の wszName、guidObject、および wszFileName メンバは使用しない。これらのメンバの代わりに、オブジェクトが占有しているメモリ ブロックへのポインタと、そのサイズを取得し、これらの情報をそれぞれ pbMemData および llMemLength メンバに格納する。dwFlags メンバの DMUS_OBJ_MEMORY フラグも設定しなければならない。

データを簡単にキャッシングできるように、ローダーはメモリへの内部ポインタを保持するため、一度 IDirectMusicLoader8::GetObject が呼び出されると、メモリを解放することはできない。これを消去するには、IDirectMusicLoader8::SetObject を同じ DMUS_OBJECTDESC ディスクリプタを使って呼び出す。ただし、pbMemData には NULL を設定する。リソース メモリは解放されないため、リソースからロードする場合は関係ない。

次の関数では、MIDI ファイルをリソースからセグメントにロードしている。

// m_pLoader は有効な IDirectMusicLoader8 ポインタである。

IDirectMusicSegment8* m_pSegment;

HRESULT LoadMidi(HMODULE hMod, WORD ResourceID)
{
    HRESULT              hr;
    DMUS_OBJECTDESC      ObjDesc;

    HRSRC hFound = FindResource(hMod,
            MAKEINTRESOURCE(ResourceID), RT_RCDATA);
    HGLOBAL hRes = LoadResource(hMod, hFound);

    ObjDesc.dwSize = sizeof(DMUS_OBJECTDESC);
    ObjDesc.guidClass = CLSID_DirectMusicSegment;
    ObjDesc.dwValidData = DMUS_OBJ_CLASS | DMUS_OBJ_MEMORY;
    ObjDesc.pbMemData = (BYTE *) LockResource(hRes);
    ObjDesc.llMemLength = SizeofResource(hMod, hFound);

    hr = m_pLoader->GetObject(
            &ObjDesc, IID_IDirectMusicSegment8,
            (void**) &m_pSegment );

    return hr;
}

ほかのオブジェクトによって参照されているオブジェクトは、最初にロードしなければならない。たとえば、スタイルへの参照を含むセグメントをロードする場合、セグメントを正しく演奏するには、スタイルが先にロードされていなければならない。セグメントがスタイルを見つけられるように、スタイルで IDirectMusicLoader8::SetObject を呼び出すこともできる。


コンテナ

コンテナは、さまざまなオブジェクトを含むファイルを表すオブジェクトである。コンテナ ファイルには、セグメント、スタイル、DLS コレクションなど、パフォーマンスに必要なすべてのデータが保持される場合がある。コンテナ ファイルは、通常、DirectMusic Producer で作成される。コンテナはセグメント ファイルおよびスクリプト ファイル内にも作成できる。

コンテナは、IDirectMusicLoader8::GetObject を使用して、ほかのオブジェクトと同様にロードする。このメソッドは、コンテナ内のすべてのオブジェクトをローダーに知らせ、GetObject を使って名前または GUID でオブジェクトを取得できるようにする。

IDirectMusicContainer8 インターフェイスを取得した後は、IDirectMusicContainer8::EnumObject を使ってコンテナ内のオブジェクトを列挙できる。

次のサンプル関数は、コンテナをロードし、名前によってコンテナからセグメントを取得し、IDirectMusicSegment インターフェイスを返す。実際の例を示すため、コンテナ オブジェクトは関数内で作成および解放される。オブジェクトの複製を避けるため、この処理はアプリケーション内で一度しか実行できない。

IDirectMusicSegment* LoadSegmentFromContainer (
        IDirectMusicLoader8* pLoader,
        WCHAR* wszFileName,
        WCHAR* wszSegmentName )

{
  DMUS_OBJECTDESC ObjDesc;
  IDirectMusicSegment* pSegment = NULL;
  IDirectMusicContainer8* pContainer = NULL;

// コンテナのロード。

  HRESULT hr = pLoader->LoadObjectFromFile(CLSID_DirectMusicContainer,
      IID_IDirectMusicContainer8, wszFileName, (void**)&pContainer);
  if (FAILED(hr))
        return NULL;

// セグメントを記述する。

  ZeroMemory(&objDesc, sizeof(objDesc));
  objDesc.dwSize = sizeof(objDesc);
  objDesc.dwValidData = DMUS_OBJ_CLASS | DMUS_OBJ_NAME;
  objDesc.guidClass = CLSID_DirectMusicSegment;
  wcsncpy (objDesc.wszName, wszSegmentName,
      sizeof(objDesc.wszName) - 1);
  objDesc.wszName[sizeof(objDesc.wszName) - 1] = 0;

// セグメントのロード。

  hr = pLoader->GetObject(&ObjDesc, IID_IDirectMusicSegment,
      (void**) &pSegment);

// コンテナをキャッシュから解放し、オブジェクトを破棄する。

  if (pContainer)
  {
    IDirectMusicObject *pObject = NULL;
    pContainer->QueryInterface(IID_IDirectMusicObject,
            (void **)&pObject);
    if (pObject)
    {
      pLoader->ReleaseObject(pObject);
      pObject->Release();
    }
  pContainer->Release();
  }
  if (S_OK != hr) return NULL;
  return pSegment;
}


オブジェクト ディスクリプタの取得

オブジェクトをロードした後で、そのオブジェクトの IDirectMusicObject8 インターフェイスを使って、DMUS_OBJECTDESC 構造体内の情報を取得しなければならない。

次のサンプル コードでは、IDirectMusicObject8::GetDescriptor メソッドを使ってスタイル名を取得している。

//  pStyle は IDirectMusicStyle8 インターフェイスへの有効なポインタである。

IDirectMusicObject8 *pIObject;
DMUS_OBJECTDESC Desc;

if (SUCCEEDED(pStyle->QueryInterface(IID_IDirectMusicObject8,
        (void **) &pIObject)))
{
    if (SUCCEEDED(pIObject->GetDescriptor(&Desc)))
    {
        if (Desc.dwValidData & DMUS_OBJ_NAME)
        {
            // Desc.wszName はスタイルの名前を保持する。
        }
    }
    pIObject->Release();
}


キャッシュの管理

オブジェクトをキャッシングすると、IDirectMusicLoader8::GetObject メソッドは常にオブジェクトの同じインスタンスを返すようになる。

キャッシュには、オブジェクトへのポインタが格納される。オブジェクト自体のメモリは COM によって管理され、参照カウントが 0 になるまで解放されない。キャッシュからオブジェクトを解放することと、オブジェクトに対するアプリケーションの COM 参照を解放することは異なることに注意が必要である。

ファイル ロード プロセスでは、オブジェクトへのリンクを解決するためにキャッシングが広範囲に使われる。たとえば、2 つのセグメントが同じスタイルを参照している場合を考える。最初のセグメントをロードするときに、セグメントはローダーを呼び出してスタイルを取得する。ローダーは、スタイル オブジェクトを作成してディスクからデータをロードし、スタイル オブジェクトへのポインタをキャッシュに格納して、このポインタをセグメントに返す。キャッシングが有効な場合、2 番目のセグメントがロードされるときにスタイルの問い合わせが行われ、ローダーが直ちに同じポインタを返す。2 つのセグメントは、どちらも同じスタイルを指している。キャッシングが無効な場合は、2 番目のセグメントが同じスタイルを要求したときに、同じスタイル オブジェクトがファイルからロードされて重複するので、時間とメモリを消費する。

別の例を考えてみる。バンド オブジェクトが、ローダーに General MIDI の DLS コレクションをキャッシュに置くよう要求する場合を考える。バンドが GM 音色をダウンロードする必要があるたびに、ローダーからコレクションを取得する。CLSID_DirectMusicCollection のキャッシングが無効になっている場合、MIDI ファイル内でパッチ チェンジが発生するたびに、GM コレクション全体のコピーが作成される。これは明らかに好ましくない。

デフォルトでは、すべてのオブジェクト クラスでキャッシングが有効になっている。IDirectMusicLoader8::EnableCache メソッドを使うと、1 つまたはすべてのオブジェクト クラスのキャッシングを無効にできる。このメソッドを使って、任意またはすべてのオブジェクト クラスのキャッシングを有効にすることもできる。

今後のキャッシングを無効にせずにキャッシュを消去するには、IDirectMusicLoader8::ClearCache メソッドを使う。キャッシュはローダーが解放されると自動的に消去されるので、アプリケーションを終了する前にこのメソッドを呼び出す必要はない。ClearCache が必要になるのは、まったく新しい音色やサウンド ファイルを使って、アプリケーションのサウンドトラックを完全に変更する場合だけである。

一般的なキャッシングが無効であるときに、1 つのオブジェクトをキャッシュするには、そのオブジェクトを IDirectMusicLoader8::CacheObject メソッドに渡す。

IDirectMusicLoader8::ReleaseObject または IDirectMusicLoader8::ReleaseObjectByUnknown メソッドを使ってキャッシュからオブジェクトを削除し、次にそのオブジェクトに対して GetObject を呼び出したときに、そのオブジェクトが再びロードされることを保証できる。オブジェクト、特にセグメントについて Release を呼び出す前にこれらのメソッドのいずれかを呼び出すのは良い考えである。この呼び出しを行わなかった場合、オブジェクトへの参照がキャッシュ内に残り、オブジェクトは存在し続ける。メモリを消費すると共に、オブジェクトは特定の状態情報を保持する場合がある。セグメントの場合は、今後ロードするインスタンスがキャッシュからロードされ、開始ポイントとループ ポイントが、前のインスタンスが破棄されたときの状態と同じになる。

キャッシュ管理の詳細については、「ガベージ コレクション」を参照すること。


ガベージ コレクション

ロードされたオブジェクトをキャッシングすると、アプリケーションで多くのオブジェクトをロードする場合、特にほかのオブジェクトを参照するオブジェクトをロードする場合に、メモリの浪費につながることがある。

デフォルトの場合のように、自動的なキャッシングが有効である場合、参照によってロードされるオブジェクトを含め、IDirectMusicLoader8::GetObject によってロードされる各オブジェクトはキャッシングされる。たとえば、セグメントについて GetObject を呼び出す場合、このセグメントにスクリプトへの参照が含まれていると、スクリプトもロードされてキャッシングされる。

ただし、IDirectMusicLoader8::ReleaseObject または IDirectMusicLoader8::ReleaseObjectByUnknown を呼び出した場合、GetObject によってロードされたプライマリ オブジェクトだけがキャッシュから削除される。参照されたオブジェクトは、ほかのオブジェクトによって使用中かどうかに関係なく解放されない。

使用されていないオブジェクトをクリーンアップするには、IDirectMusicLoader8::CollectGarbage を呼び出す。このメソッドは、GetObject によって直接ロードされたオブジェクト、およびそのオブジェクトによって参照されるオブジェクトを除いて、すべてのオブジェクトをキャッシュから解放する。CollectGarbage は、ローダーのオブジェクトへの COM 参照を解放することによって、キャッシュからオブジェクトを消去する。この結果、オブジェクトの参照カウントが 0 になった場合は、オブジェクトは破棄され、そのメモリは再び利用可能になる。

ロードされたオブジェクトが不要になったときにメモリ内に残らないようにするには、次の処理を行う必要がある。

  • GetObject の呼び出しの対象になったオブジェクトについて、ReleaseObject または ReleaseObjectByUnknown を呼び出す。
  • CollectGarbage を呼び出して、間接的にロードされたオブジェクトへのローダーの参照を解放する。
  • アプリケーションによって保持されているポインタについて Release を呼び出す。

オブジェクトが互いに循環参照している場合は処理が複雑になる。セグメントにスクリプト トラック経由でスクリプト オブジェクトへの参照が含まれ、スクリプトにセグメントへの参照が含まれているとする。GetObject を呼び出してセグメントを直接ロードすると、スクリプトが間接的にロードされる。次に、ReleaseObject を使用してキャッシュからセグメントを解放し、アプリケーションのセグメントへの参照について Release を呼び出す。スクリプト オブジェクトによって保持される、セグメントへの COM 参照が存在するので、このセグメントは存在し続ける。この場合、スクリプトはキャッシュ内のほかのオブジェクトによって参照されないので、ガベージになる。ただし、特殊な処理を行わない場合、CollectGarbage はローダーのスクリプトへの参照だけを解放する。このため、その参照カウントは 0 にならない。セグメントとスクリプトは互いに参照し続けるので、両方ともキャッシュから削除されているのに、メモリ内に存在し続ける。

この問題を回避するために、CollectGarbage はオブジェクトについて内部メソッドを呼び出して、そのオブジェクトがほかのオブジェクトへの参照を解放するように強制する。上の例では、スクリプトはセグメントへの参照を解放する。セグメントの参照カウントが 0 になり、セグメント自体を破棄するときに、セグメントはスクリプトへの参照を解放するので、ローダーがスクリプトへの参照を解放するときに、スクリプトはそれ自体を破棄できる。

しかし、ここでもう 1 つ問題がある。アプリケーションが、ローダーが知らないスクリプトへのインターフェイスを取得し、このポインタについての Release の呼び出しを無視したとする。スクリプトは存在し続けるが、意図したとおりに動作しない場合がある。これは、セグメントへの参照が存在しないからである。このスクリプトについてメソッドを呼び出すと、致命的なエラーが発生する場合がある。これを回避するために、CollectGarbage はスクリプトについてのすべてのメソッドが DMUS_S_GARBAGE_COLLECTED を返すことを保証している。

この状況は、ほとんどのアプリケーションに影響しない。ただし、CollectGarbage によってキャッシュから消去されたオブジェクトについてメソッドを呼び出す場合、予期した結果にならない場合があることに注意する必要がある。

次のサンプル コードでは、セグメントへの参照を含むスクリプトをロードしている。m_pLoader は IDirectMusicLoader8 インターフェイスで、m_pPerformance は IDirectMusicPerformance8 インターフェイスである。この例では、スクリプトでルーチンを呼び出した後、キャッシュからスクリプト オブジェクトを削除し、CollectGarbage を呼び出してセグメント オブジェクトを解放している。セグメントにスクリプトへの参照が含まれる場合、このスクリプトを破棄できるようにスクリプトが解放され、次にセグメントが解放されて破棄できるようになる。

// スクリプトをロードし、ルーチンを呼び出す。

IDirectMusicScript8 *pScript;

m_pLoader->GetObject(scriptdesc, IID_IDirectMusicScript8, &pScript);
pScript->Init(m_pPerformance, NULL);
pScript->CallRoutine(L"DoorSlam", NULL);

// スクリプト オブジェクトを解放し、ガベージを収集する。

pLoader->ReleaseObjectByUnknown(pScript);
pLoader->CollectGarbage();
pScript->Release();


オブジェクトの設定

後でほかのオブジェクトから参照されるオブジェクトを、参照元のオブジェクトをロードするときにローダーが取得できるように、実際にはロードせずに、その場所だけをローダーに指示することが望ましい。オブジェクトに新しい属性を与えて、ローダーが属性を使ってオブジェクトを検索できるようにすることもできる。

IDirectMusicLoader8::SetObject メソッドは、パラメータとして DMUS_OBJECTDESC 構造体を受け取る。この構造体には、2 つの主要な情報が含まれる。

  • データへのポインタ。ファイル パスまたはメモリのブロックへのポインタとなる。「ファイルからのオブジェクトのロード」および「リソースからのオブジェクトのロード」を参照すること。
  • 後で参照されたときに使用する、オブジェクトの識別子。GUID または名前となる。後から、IDirectMusicLoader8::GetObject の呼び出しで、同じ名前または GUID を使って、格納されたオブジェクトが検索される。オブジェクトに既に存在している GUID または名前を変更することはできない。

戻り値として、DMUS_OBJECTDESC 構造体に、ローダーによって収集されたオブジェクトに関する追加情報が保持される場合がある。

次の関数では、リソース内の名前の付いていないオブジェクト (MIDI ファイルなど) に名前を割り当てている。

// m_pLoader は有効な IDirectMusicLoader8 インターフェイス ポインタである。

HRESULT SetObjectFromResource(const GUID* guid, int ID,
        char* type, WCHAR* name)
{
  HRSRC hResource = NULL;
  HGLOBAL hData = NULL;
  hResource = FindResource(g_hInstance, MAKEINTRESOURCE(ID), type);
  if (hResource != NULL)
  {
    hData = LoadResource(g_hInstance, hResource);
    if (hData != NULL)
    {
      DMUS_OBJECTDESC desc;
      if(m_pLoader && (hResource != NULL) && (hData != NULL))
      {
        ZeroMemory(&desc,sizeof(desc));
        desc.pbMemData = (BYTE*) LockResource(*hData);
        desc.llMemLength = SizeofResource(g_hInstance, (*hResource));
        desc.guidClass = (*guid);
        desc.dwSize = sizeof(desc);
        desc.dwValidData = DMUS_OBJ_CLASS | DMUS_OBJ_MEMORY;
        if (name)
        {
            wcscpy(desc.wszName, name);
            desc.dwValidData |= DMUS_OBJ_NAME;
        }
        return m_pLoader->SetObject(&desc);
      }
    }
  }
  return E_FAIL;
}

次のサンプル関数は、"MIDI" タイプのリソースとして格納された MIDI ファイルに名前を割り当てるときに使用できる。

SetObjectFromResource(CLSID_DirectMusicSegment, 101,
        "MIDI", "canyon");

これ以降、オブジェクトはいつでも名前を使ってロードできる。


サウンドの再生

ここでは、DirectMusic のパフォーマンスの基本的な要素と、ソースからデータを取得して出力するために必要となる重要なメソッドを紹介する。

説明するトピックは、次のとおりである。

  • パフォーマンスの作成
  • セグメントの使い方
  • バンドの使い方
  • タイミング
  • 通知とイベントの処理


パフォーマンスの作成

パフォーマンス オブジェクトは再生全般を管理する。パフォーマンス オブジェクトは、次のタスクを実行する。

  • ポートとオーディオパスの管理
  • オーディオパスへのチャンネルのマッピング
  • セグメントの演奏と停止
  • メッセージのディスパッチ
  • ツールとタイミングの管理

ほとんどのアプリケーションは、パフォーマンス オブジェクトを 1 つだけ使用するが、マスタ テンポやボリュームなどのパラメータの異なる複数のパフォーマンスを使用することもできる。

次のサンプル コードでは、パフォーマンスを 1 つ作成して、IDirectMusicPerformance8 インターフェイスへのポインタを取得している。

IDirectMusicPerformance8* pPerf;

if (FAILED(CoCreateInstance(
        CLSID_DirectMusicPerformance,
        NULL,
        CLSCTX_INPROC,
        IID_IDirectMusicPerformance8,
        (void**)&pPerf
    )))
{
    pPerf = NULL;
}

作成したパフォーマンスは初期化しなければならない。推奨されているように、アプリケーションでオーディオパスを使用している場合は、IDirectMusicPerformance8::InitAudio メソッドを呼び出さなければならない。アプリケーションで以前のチャンネルとポートのマッピング モデルを使用している場合は、代わりに IDirectMusicPerformance8::Init を呼び出す。詳細については、「ポートからオーディオパスへの移行」を参照すること。

初期化における重要な処理は、DirectMusic オブジェクトの作成である。既存の IDirectMusic8 インターフェイス ポインタを IDirectMusicPerformance8::InitAudio に渡すこともできるが、ほとんどの場合 InitAudio で DirectMusic オブジェクトを作成する方が便利である。ポートおよびマスタ クロックに対して必要な制御の程度に応じて、IDirectMusic8 インターフェイスへのポインタを取得するかどうかを選択することもできる。ほとんどのアプリケーションでは、IDirectMusic8 のメソッドにアクセスする必要はないので、InitAudio の ppDirectMusic パラメータとして NULL を渡すことができる。

InitAudio は、既存の DirectSound オブジェクトを取ることもできる。DirectSound はシンセサイザから出力されたサウンド データを管理する。ほとんどの場合、InitAudio でこのオブジェクトを作成できる。このオブジェクトへのインターフェイスは、DirectSoundCapture オブジェクトを作成したり、DirectMusic のパフォーマンスではなくバッファ内で直接ウェーブを再生するなど、DirectSound をほかの用途にしない限り必要がない。

DMUS_AUDIOPARAMS 構造体を InitAudio に渡すことによって、アプリケーションはシンセサイザの機能を要求したり、デフォルト以外のシンセサイザを設定できる。ほとんどのアプリケーションでは、この処理の必要はない。

次のサンプル コードでは、DirectMusic および DirectSound オブジェクトへのポインタを取得せずに、パフォーマンスを初期化している。16 のパフォーマンス チャンネルと、ポート上で使用可能なすべての機能を持つ、デフォルトの標準オーディオパスを作成する。

// hWnd はアプリケーション ウィンドウ ハンドルである。

if (SUCCEEDED(pPerf->InitAudio(NULL, NULL, hWnd,
        DMUS_APATH_SHARED_STEREOPLUSREVERB, 16,
        DMUS_AUDIOF_ALL, NULL)))
{
    // パフォーマンスの初期化。
}


セグメントの使い方

セグメントは、DirectMusic のパフォーマンスで演奏可能なデータの基本単位である。セグメントは IDirectMusicSegment8 インターフェイスによって表される。

アプリケーションでは、次のいずれかの方法でセグメント オブジェクトを作成できる。

  • IDirectMusicSegment8 インターフェイスをサポートするファイルまたはリソース オブジェクトをロードする。詳細については、「オーディオ データのロード」を参照すること。
  • IDirectMusicStyle8::GetMotif メソッドを使用して、スタイルからモチーフを取得する。
  • IDirectMusicComposer8 インターフェイスのメソッドを使用して、実行時にアレンジまたはトランジションを作成する。「アレンジ用のプログラミング概要」および「トランジションの使い方」を参照すること。
  • IDirectMusicSegment8::Clone メソッドを使用して、既存のセグメントのコピーを作成する。
  • IDirectMusicBand8::CreateSegment メソッドを使用する。このメソッドにより、バンド チェンジの作成だけに使用される、特殊なセカンダリ セグメントが作成される。「プログラムによるバンド チェンジの実行」を参照すること。
  • IDirectMusicPatternTrack8::CreateSegment メソッドを使用して、パターン トラック オブジェクトからセグメントを作成する。ほとんどのアプリケーションではこの処理は必要がない。パターン トラックは、通常、最初にセグメントから作成されるからである。
  • 既存のトラックからセグメントを構築する。CoCreateInstance を呼び出してセグメント オブジェクトを作成し、次に IDirectMusicSegment8::InsertTrack を呼び出してトラックを追加する。この手法は、ほとんどのアプリケーションで使用されない。

各セグメントは 1 つまたは複数のトラックによって構成され、各トラックは IDirectMusicTrack8 インターフェイスによって表される。トラックは、セグメントのデータのほとんどを保持し、データは、ノートイベント、バンド チェンジ、テンポ チェンジ、またはその他のタイム イベントで構成される。トラックはセグメント オブジェクトを通して管理されるため、アプリケーションは一般的にこれらのインターフェイスを必要としない。詳細については、「DirectMusic トラック」を参照すること。

セグメントは、パフォーマンスで異なる役割を果たす場合がある。常に必要なプライマリ セグメントは、サウンドトラックの主な内容を提供し、通常、制御セグメントとして機能する。セカンダリ セグメントはプライマリ セグメントと共に演奏され、サウンド エフェクトや短いテーマを提供する。特殊なタイプのセカンダリ セグメントとしてモチーフがあり、常に DirectMusic スタイル オブジェクトから取得される。

さらに、特殊な役割を持つ 3 種類のセグメントがある。

  • トランジション セグメント。実行時に DirectMusic コンポーザ オブジェクトによって作成される短い音楽のトランジションで、通常、あるセグメントから別のセグメントへ、またはセグメントから無音へ移行するプライマリ セグメントとして演奏される。
  • バンド セグメント。パフォーマンス内のさまざまなチャンネル用の一連の音色および音色セグメント。アプリケーションはバンド セグメントをセカンダリ セグメントとして演奏し、音楽を演奏するバンドに変更を加えることができる。
  • テンプレート セグメント。コード進行、グルーブ レベル、および装飾などのガイドとして、実行時にスタイルやコードマップと共に組み合わされ、音楽を形成する。

セグメントの再生はパフォーマンス オブジェクトによって制御され、IDirectMusicPerformance8::PlaySegment または IDirectMusicPerformance8::PlaySegmentEx の呼び出しで開始される。

パフォーマンス内では、ただ 1 つのプライマリ セグメントを演奏できる。再生の目的でプライマリ セグメントを挿入する場合は、現在演奏されているセグメントが終わった後にそのセグメントを演奏するように指定したり、現在のプライマリ セグメントを置き換えることができる。

一方、セカンダリ セグメントはプライマリ セグメント上で演奏され、任意の数のセカンダリ セグメントを同時に演奏できる。

通常、セカンダリ セグメントはプライマリ セグメントのパフォーマンスを変更しない。たとえば、セカンダリ セグメントは、プライマリ セグメントのスタイルに影響を与えずに、別のスタイルに基づくことができる。ただし、セカンダリ セグメントを制御セグメントとして指定できる。この場合、セカンダリ セグメントは、通常プライマリ セグメントで処理される特定のタスクを実行する。

セグメントの詳細については、次のトピックを参照すること。

  • セグメントの状態
  • 制御セグメント
  • 自己制御セグメント
  • ウェーブ セグメント

「セグメントのタイミング」も参照すること。


セグメントの状態

セグメントを演奏する場合、オーディオパス、反復、開始ポイントなど、そのセグメントのパラメータは IDirectMusicSegmentState8 インターフェイスで表されるセグメント状態に格納される。パラメータは、セグメントのそのインスタンスについてのみ有効である。IDirectMusicSegment8 のメソッドを使用して、セグメントに対して行った変更は、IDirectMusicPerformance8::PlaySegment または IDirectMusicPerformance8::PlaySegmentEx の呼び出しによって作成される新しいセグメント状態に反映される。

セグメントの異なるインスタンスが異なるオーディオパスで再生されている場合、セグメント状態を使用して、3D サウンド バッファやエフェクトを取得したり、そのインスタンスにのみ適用される変更を行うことができる。たとえば、レーシング ゲームで、各自動車のサウンドを独自のオーディオパスで再生することによって、複数の自動車で同じエンジン音を使用できる。IDirectMusicAudioPath8::GetObjectInPath または IDirectMusicSegmentState8::GetObjectInPath のいずれかを使用して、各オーディオパスから IDirectSound3DBuffer8 インターフェイスを取得することによって、各自動車の 3D パラメータを個々に設定できる。


制御セグメント

制御セグメントは、トラック間で共有されるデータのソースである。次のトラックは、ほかのトラックとは異なり、メッセージを送信するのではなく、パラメータの呼び出しに応答することによって、パフォーマンスにデータを渡す。

  • コード。
  • コマンド。
  • ミュート。
  • テンポ。
  • 拍子記号。

たとえば、コード トラックはスタイル トラックからのパラメータの呼び出しに応答する。ノートを送信する前にそのノートの MIDI 値を決定するには、スタイル トラックで現在のコードを決定しなければならない。スタイル トラックは IDirectMusicPerformance8::GetParam を呼び出すことによってこの処理を行い、この呼び出しは制御セグメントのコード トラックに引き継がれる。

制御セグメントとして機能するには、セグメントに 1 つ以上の制御トラックが必要である。ミュート、コマンド、テンポ、およびコードのトラックが制御トラックである。

制御セグメントは、メッセージによって制御される再生には影響しない。制御セグメントの拍子記号が使用されるのは、拍子記号トラックがない場合だけである。これは、通常、セグメントが MIDI ファイルに基づいていない場合である。

デフォルトでは、プライマリ セグメントは制御セグメントである。ただし、DMUS_SEGF_CONTROL フラグを IDirectMusicPerformance8::PlaySegment または IDirectMusicPerformance8::PlaySegmentEx に渡すことによって、セカンダリ セグメントを制御セグメントとして指定できる。

セカンダリ セグメントが制御セグメントである場合も、プライマリ セグメントは制御データの代替ソースとして機能し続ける。たとえば、セカンダリ制御セグメントにテンポ トラックが含まれていない場合に、プライマリ セグメントに含まれている場合は、プライマリ セグメントのテンポが使用される。

詳細については、次のトピックを参照すること。

  • DMUS_SEGF_FLAGS
  • トラック構成


自己制御セグメント

自己制御セグメントは、自己制御セグメントから制御情報をコピーする制御セグメントからの制御情報を無視する。たとえば、セグメントにコマンド トラックがある場合、制御セグメントで設定されたグルーブ レベルではなく、独自のグルーブ レベルを使用できる。

セグメントは、次のように、各トラックについて制御情報を取得する場所を定義できる。

  • 制御セグメントのトラックから。これはデフォルトの動作である。
  • プライマリ セグメントのトラックから。プライマリ セグメントが制御セグメントであるかどうかは関係ない。
  • 同じセグメントのトラックから。

セグメントは、通常、オーサーによって自己制御セグメントとして構成される。ただし、アプリケーションで、IDirectMusicSegment8::SetTrackConfig または IDirectMusicSegmentState8::SetTrackConfig メソッドを使用し、次のフラグを設定またはクリアして、セグメント内の個々のトラックを構成できる。

DMUS_TRACKCONFIG_OVERRIDE_ALL
トラックは、制御セグメントやプライマリ セグメントのトラックの前に、このセグメントからパラメータを取得する。
DMUS_TRACKCONFIG_OVERRIDE_PRIMARY
トラックは、プライマリ セグメントのトラックの前に、このセグメントからパラメータを取得する。
DMUS_TRACKCONFIG_FALLBACK
セグメントは、プライマリ セグメントや制御セグメントから必要な情報が返されない場合に、このセグメントからパラメータを取得する。

次のサンプル コードでは、スタイル トラックがすべてのパラメータを同じセグメントのほかのトラックから取得するよう指示し、制御セグメントのコード、グルーブ レベル、ミュート コマンドを使用しないようにしている。pSegment は IDirectMusicSegment8 インターフェイス ポインタである。

HRESULT hr = pSegment ->SetTrackConfig(CLSID_DirectMusicStyleTrack,
        -1, DMUS_SEG_ALLTRACKS, DMUS_TRACKCONFIG_OVERRIDE_ALL, 0);

詳細については、「トラック構成」を参照すること。


ウェーブ セグメント

DirectMusic ローダーは、オーディオ圧縮マネージャ (ACM) でサポートされているフォーマットの圧縮されたウェーブフォーム オーディオ ファイル、および非圧縮ウェーブ ファイルをロードできる。

ウェーブ ファイルに基づくセグメントは、ほかのセグメントと同様に演奏される。このようなセグメントは、DMUS_WAVE_PMSG メッセージとしてパフォーマンスに渡され、常にオーディオパスのチャンネル 0 で演奏される。ウェーブについてはノートとは異なる意味の合成が行われるが、ウェーブもシンセサイザに渡されて、MIDI コントローラで操作できる。

ウェーブもまた DirectMusic Producer ファイルに埋め込んで、さまざまなバリエーションのあるスタイルのように動作させることができる。例については、AudioScripts サンプル アプリケーションを参照すること。このサンプルの ScriptDemoBaseball.spt スクリプトは、ボタンがクリックされるたびに物売りの叫び声のバリエーションを再生する。

セグメント (.sgt) ファイルのウェーブは、再生する前にダウンロードする必要がある。セグメントのバンドをダウンロードすると、これらのウェーブもダウンロードされる。詳細については、「バンドのダウンロードとアンロード」を参照すること。


バンドの使い方

バンドとは、セグメントまたはスタイル内の特定のパートに割り当てられた一連の音色である。演奏時に各音色トラックは、次の情報を保存しているパフォーマンス チャンネルにマップされる。

  • MIDI ボリューム。
  • MIDI パン。
  • 転調。この値が 0 でない場合、チャンネル上の音楽のノートは、音色に合わせて自動的に転置される。
  • 音色の MIDI パッチ番号。バンク セレクトの MSB と LSB も含まれる。
  • 音色のロード元となる DLS コレクションへの参照。デフォルトの DLS コレクションは、スタンダード General MIDI コレクションである。

セグメントとスタイルは常に、少なくともデフォルト バンドと呼ばれる 1 つのバンドによって構成される。スタイルには、追加のバンドを含めることができる。セグメントまたはスタイルをロードするときに、デフォルト バンドおよびその他のバンドは、どちらも自動的にロードされる。ただし、どんなバンドを使用する場合でも、バンドの音色用に DLS データをダウンロードしなければならない。

IDirectMusicStyle8::GetDefaultBand メソッドを使って、デフォルト バンドへのポインタを取得することができる。

スタイルにオーサリングされたその他のバンドは、IDirectMusicStyle8::EnumBand および IDirectMusicStyle8::GetBand メソッドを使って、検索および取得することができる。バンドは、ほかのスタイル ファイルやバンド ファイルからも取得できる。IDirectMusicBand8 インターフェイスを取得した後、このバンドにアクセスし、デフォルトのバンドを置き換えることもできる。

バンドは、ほかのオブジェクトと同様にロードされる。詳細については、「オーディオ データのロード」を参照すること。

バンドの詳細については、次のトピックを参照すること。

  • バンドのダウンロードとアンロード
  • プログラムによるバンド チェンジの実行
  • 確実なタイミングでのバンド チェンジ
  • カスタム音色による MIDI ファイルの演奏


バンドのダウンロードとアンロード

バンドを使用するには、まず参照する音色をパフォーマンスにダウンロードしなければならない。この手順により、音色がパフォーマンス チャンネルに割り当てられ、シンセサイザに DLS データがダウンロードされる。

デフォルトでは、使用するバンドのダウンロードはアプリケーションが行う。ただし、バンドの自動ダウンロードを有効にすることもできる。

バンドのダウンロードにより、パフォーマンスがバンドを利用できるようになるが、プログラム チェンジは行われない。プログラム チェンジは、セグメントのバンド トラックで生成されるメッセージに応じて実行される。このメッセージは、一般的にはセグメント ファイルにオーサリングされる。実行時にプログラム チェンジを行う方法については、「プログラムによるバンド チェンジの実行」を参照すること。

バンドのダウンロードとアンロードを実装する方法については、次のトピックを参照すること。

  • バンドの自動ダウンロード
  • バンドの手動ダウンロード
  • パッチの競合
  • バンドのアンロード


バンドの自動ダウンロード

自動ダウンロードが有効な場合、バンドに含まれるセグメントがキューに格納されるときに、バンドの音色がダウンロードされる。セグメントが停止されると、同じ音色を使用しているほかのセグメントを直ちにキューに入れて演奏するか、現在演奏中でない限り、音色は自動的にアンロードされる。

自動ダウンロードは、セグメントのタイミングが重要でないときにだけ使用するべきである。音色のロードとアンロードを繰り返すと時間がかかり、複雑なオーディオ環境では、重大なパフォーマンスの低下が発生する場合がある。

自動ダウンロード メカニズムの一部である自動アンロードでも、望んでいない結果となる場合がある。たとえば、チャンネルの音色を変更する短いセカンダリ セグメントを演奏する場合を考える。セカンダリ セグメントが開始されるときに、音色が自動的にダウンロードされ、既存の音色に置き換えられる。セカンダリ セグメントが終了すると、音色は自動的にアンロードされ、その結果、チャンネルに音色がなくなり、そのチャンネルは無音を再生する。

バンドの自動ダウンロードは、次のいずれかの方法で有効にできる。

  • GUID_PerfAutoDownload パラメータを使って IDirectMusicPerformance8::SetGlobalParam メソッドを呼び出す。「グローバル パラメータの設定と取得」を参照すること。
  • GUID_Enable_Auto_Download パラメータを使って、IDirectMusicSegment8::SetParam メソッドを呼び出すことによって、単一のセグメントの自動ダウンロードを有効にする。「トラック パラメータの設定と取得」を参照すること。

次のサンプル コードでは、パフォーマンス pPerf のグローバル パラメータを、バンドの自動ダウンロードが有効になるように設定している。

BOOL fAuto = TRUE;
pPerf->SetGlobalParam(GUID_PerfAutoDownload, &fAuto, sizeof(BOOL));


バンドの手動ダウンロード

次のいずれかの方法を使うと、バンドを手動でダウンロードすることができる。

  • IDirectMusicSegment8::Download を呼び出し、セグメントのバンドとウェーブをオーディオパスまたはパフォーマンスのどちらかにダウンロードする。
  • ロードされたオブジェクトから IDirectMusicBand8 インターフェイスを取得し、IDirectMusicBand8::Download メソッドを呼び出す
  • GUID_Download または GUID_DownloadToAudioPath パラメータを使って IDirectMusicSegment8::SetParam メソッドを呼び出し、セグメントの最初のバンド トラックにバンドをダウンロードする。IDirectMusicPerformance8::SetParam を使って、プライマリ セグメントでこのパラメータを設定したり、IDirectMusicTrack8::SetParamEx を使って、直接バンド トラックを設定することもできる。「トラック パラメータの設定と取得」を参照すること。

アプリケーションが複数のシンセサイザ、つまり複数のポートを使用するオーディオパスを作成する場合、パフォーマンスではなく、ここのオーディオパスにバンドをダウンロードしなければならない。ただし、ほとんどのアプリケーションではシンセサイザを 1 つだけ使用するので、すべての音色データをパフォーマンスにダウンロードしても安全である。

複数のオーディオパスは、通常同じシンセサイザを共有する。バンドをオーディオパスにダウンロードすると、音色データはそのオーディオパス上のポートにダウンロードされ、同じポートを使用するすべてのオーディオパスで利用できるようになる。データを各オーディオパスにダウンロードする必要はない。

たとえば、レーシング ゲームで車のエンジン音の DLS 音色を使用するセグメントがあるとする。レースの各自動車の 3D パラメータを個々に操作するために、複数のオーディオパスでサウンドを再生する。この音色は、一度だけダウンロードする必要がある。

同じ音色を繰り返しダウンロードしても問題は生じない。1 つのバンド内にある音色が何度も現れる場合や、複数のバンドを同時に開いてダウンロードするときに同じ音色がこれらのバンドで使用されている場合でも、その音色のデータは 1 回だけシンセサイザに送信される。

次の関数は、ディスクからバンドをロードして、そのバンドをパフォーマンスにダウンロードする。

HRESULT myDownloadBand(
    IDirectMusicLoader8 *pILoader,      // ローダー インターフェイス。
    IDirectMusicBand8 **ppBand,         // ポインタを取得するため。
    IDirectMusicPerformance8 *pPerf,    // バンドを使用するパフォーマンス。
    WCHAR *pwszFile)                    // ロードするファイル。
{
    HRESULT hr;
    DMUS_OBJECTDESC Desc;

    // バンド オブジェクトのファイル名と GUID を使って、
    // Desc を初期化することから開始する。

    wcscpy(Desc.wszFileName,pwszFile);
    Desc.dwSize = sizeof(Desc);
    Desc.guidClass = CLSID_DirectMusicBand;
    Desc.dwValidData = DMUS_OBJ_CLASS |
            DMUS_OBJ_FILENAME | DMUS_OBJ_FULLPATH;

    hr = pILoader->GetObject(&Desc, IID_IDirectMusicBand8,
            (void **) ppBand);
    if (SUCCEEDED(hr))
    {
        hr = (*ppBand)->Download(pPerf);
    }
    return hr;
}


パッチの競合

異なるセグメントのバンドを同じポートにダウンロードすると、バンド内の音色によって、以前にダウンロードしたバンドのデータが上書きされる場合がある。

たとえば、セグメント A がピアノをパッチ番号 1 に割り当てるバンドを使用し、セグメント B がバンジョーを同じパッチに割り当てるバンドを使用するとする。アプリケーションは、最初にセグメント A、次にセグメント B について IDirectMusicSegment8::Download を呼び出す。バンドが異なるオーディオパスにダウンロードされた場合でも、音色データは同じシンセサイザにダウンロードされるので、パフォーマンス チャンネルのすべてのノートは、バンジョーによって演奏されるパッチ番号 1 にマップされる。

コンテンツをオーサリングするときには、このような潜在的なパッチの競合を考慮する必要がある。複数のセグメントで、同じパッチ番号の異なる音色を使用するべきではない。


バンドのアンロード

バンドはメモリを消費するため、使用しなくなったバンドはアンロードするべきである。自動ダウンロードを有効にしている場合は、セグメントが終了したときに、セグメントに関連付けられているバンドが自動的にアンロードされる。そうでない場合は、次のいずれかの方法を使って、手動でバンドをアンロードすることができる。

  • 対応する Download メソッドでダウンロードされた音色について、IDirectMusicSegment8::Unload または IDirectMusicBand8::Unload メソッドを呼び出す。
  • GUID_Unload または GUID_UnloadFromAudioPath パラメータを使って IDirectMusicSegment8::SetParam メソッドを呼び出し、セグメントのバンド トラックにあるバンドをアンロードする。IDirectMusicPerformance8::SetParam を使って、プライマリ セグメントでこのパラメータを設定したり、IDirectMusicTrack8::SetParamEx を使って、直接バンド トラックを設定することもできる。「トラック パラメータの設定と取得」を参照すること。

IDirectMusicPerformance8::CloseDown メソッドでも、ダウンロードされた残りの音色がアンロードされる。


プログラムによるバンド チェンジの実行

通常は、ロードされたセグメントのバンド トラックによって、プログラム チェンジが実行される。ただし、手動で行うこともできる。

まず、IDirectMusicBand8::CreateSegment メソッドを呼び出して、セカンダリ セグメントを作成する。次に、IDirectMusicPerformance8::PlaySegment または IDirectMusicPerformance8::PlaySegmentEx を呼び出して、作成したセグメントを演奏する。通常は dwFlags パラメータ内の DMUS_SEGF_MEASURE または DMUS_SEGF_GRID を使って、適切な境界でバンド チェンジが有効になるよう保証する。

次のサンプル関数では、バンドからセグメントを作成し、そのセグメントを演奏している。音色がダウンロード済みであるか、自動ダウンロードが有効になっていると仮定している。

HRESULT myPlayBand(
    IDirectMusicBand8 *pBand,          // バンド オブジェクトへのポインタ。
    IDirectMusicPerformance8 *pPerf,   // バンドを使用するパフォーマンス。
    REFERENCE_TIME rfTime,             // 演奏されるタイム。
    DWORD dwFlags)                     // パフォーマンス フラグ。
{
    IDirectMusicSegment *pSegment;

// QI が必要な IDirectMusicSegment8 は必要ではない。

    HRESULT hr = pBand->CreateSegment(&pSegment);
    if (SUCCEEDED(hr))
    {
        hr = pPerf->PlaySegment(pSegment,
                dwFlags | DMUS_SEGF_SECONDARY,
                rfTime,
                NULL);
        pSegment->Release();
    }
    return hr;
}

パフォーマンスは、一度に複数のバンドの音色を演奏することができる。たとえば、アプリケーションが 1 つのバンドを使ってプライマリ セグメントを演奏しているときに、別のバンドを持つスタイルのモチーフを演奏する場合を考える。2 つのバンドの音色が異なるパフォーマンス チャンネルにマップされている限り、競合は発生しない。ただし、通常、モチーフ セグメントは独自のバンド トラックを持たない。したがって、最初にバンド セグメントを作成してから演奏しなければ、モチーフのパフォーマンス チャンネルからは音が出ない


確実なタイミングでのバンド チェンジ

バンド セグメントを演奏するときに重要な問題となるのは、スタイル トラックで演奏されるノートのタイミングのばらつきである。たとえば、小節 1 の 1 拍目のノートが、実際の拍の境界よりわずかに進んだり遅れたりする場合がある。バンド セグメントではこの状況を認識していないので、いくつかのノートが間違った音色で演奏される場合がある。

この問題を避けるために、アプリケーションはバンド セグメントを早めにキューに格納するべきである。たとえば、スタイル セグメントの pStyleSeg とバンド セグメントの pBandSeg があるときに、パフォーマンス (pPerf) の次の小節境界で、スタイル セグメントとバンド セグメントの両方を演奏する場合を考える。スタイルには、セグメントの開始タイムよりも、最大 30 ティック (ミュージック タイムで) 早く開始される可能性のあるノートが含まれていることがわかっている。次のサンプル コードでは、バンド セグメントがスタイル セグメントよりも 31 ティック前に演奏されることが保証されている。したがって、すべての音色は、ノートが演奏される前に適切に設定される。

// まず、次の小節のタイムを取得して、
// ミュージック タイムに変換する。

REFERENCE_TIME rtResolved;
MUSIC_TIME mtResolved;

pPerf->GetResolvedTime( 0, &rtResolved, DMUS_TIME_RESOLVE_MEASURE );
pPerf->ReferenceToMusicTime( rtResolved, &mtResolved );

// バンド セグメントを、小節境界の 31 ティック前に演奏する。

mtResolved -= 31;
pPerf->PlaySegment(pBandSeg, 0, mtResolved, NULL);

// スタイル セグメントを小節境界で演奏する。

pPerf->PlaySegment(pStyleSeg, DMUS_TIME_RESOLVE_MEASURE, 0, NULL);

注 セグメントで演奏されるノートにばらつきがない場合 (たとえば、MIDI ファイルからロードされたセグメントの場合) は、同時に演奏されるバンド セグメントのタイミングについて注意する必要はない。デフォルトでは、すべてのバンド セグメントは 1 ティック早く開始される。


カスタム音色による MIDI ファイルの演奏

MIDI ファイルを演奏する場合、デフォルトでは、Gm.dls ファイルに含まれる Roland GM/GS Sound Set の音色が使用される。ただし、MIDI ファイルを演奏するときに、任意の DLS コレクションの音色を使用できる。

まず、コレクションをロードして、IDirectMusicCollection8 インターフェイスへのポインタを取得する。

次の関数の例では、ファイル名を使ってコレクションをロードしている。

HRESULT LoadCollectionByName(
        IDirectMusicLoader8 *pILoader,
        char *pszFileName,
        IDirectMusicCollection8 **ppICollection)
{
    HRESULT hr;
    DMUS_OBJECTDESC Desc;             // ディスクリプタ。

    // コレクション オブジェクトのファイル名と GUID を使って、
    // Desc を初期化することから開始する。
    // ファイル名は char 文字列から始まるので、
    // Unicode に変換する。

    mbstowcs(Desc.wszFileName,pszFileName,DMUS_MAX_FILENAME);
    Desc.dwSize = sizeof(DMUS_OBJECTDESC);
    Desc.guidClass = CLSID_DirectMusicCollection;
    Desc.dwValidData = DMUS_OBJ_CLASS
            | DMUS_OBJ_FILENAME
            | DMUS_OBJ_FULLPATH;

    hr = pILoader->GetObject(&Desc,
            IID_IDirectMusicCollection8,
            (void **) ppICollection);
    return hr;
}

次に、IDirectMusicSegment8::SetParam を呼び出して、DLS データをセグメントに接続する。次のサンプル コードは、セグメントと LoadCollectionByName 関数から返されるコレクションを接続する方法を示す。

// pSegment は MIDI ファイルから作成され、
// pLoadedCollection は有効な IDirectMusicCollection8 ポインタであると仮定する。

HRESULT hr = pSegment->SetParam(GUID_ConnectToDLSCollection,
        0xFFFFFFFF, 0, 0,
        (void*)pLoadedCollection);

最後に、IDirectMusicSegment8::Download を呼び出すことによって、コレクション内の音色をパフォーマンスまたはオーディオパスにダウンロードする。

MIDI セグメントにカスタム コレクションを付加するときに、GM コレクションへの接続は切断されない。たとえば、パッチ番号が 12 の 1 つの音色を含むコレクションをロードし、これをセグメントに接続する場合、12 以外のパッチ番号を持つ MIDI チャンネルでは、GM コレクションの適切な音色を使って演奏が続けられる。

コレクションの詳細については、「音色コレクションの使い方」を参照すること。


タイミング

ここでは、DirectMusic のさまざまなタイミングの概要について説明する。説明するトピックは、次のとおりである。

  • マスタ クロック
  • クロック タイムとミュージック タイム
  • テンポの変更
  • 準備時間
  • 遅延時間とバンパー時間
  • セグメントのタイミング


マスタ クロック

正確なタイミングと受け入れ可能な短い遅延時間を保証するために、DirectMusic はマスタ クロックをカーネル モードに実装している。このクロックは、ハードウェア タイマに基づいている。DirectMusic では、システム クロックが自動的にマスタ クロックとして選択されるが、アプリケーションではサウンド カードのウェーブ出力クリスタルなどの別のクロックを選択することができる。

マスタ クロックは高分解能のタイマであり、DirectMusic を使うプロセス、デバイス、およびアプリケーションはこのクロックを共有する。このクロックは、システム内のすべてのオーディオ再生を同期化するために使われる。これは、標準的な IReferenceClock インターフェイスである。IReferenceClock::GetTime メソッドは、現在のタイムを 100 ナノ秒単位の 64 ビット整数として返す (REFERENCE_TIME 型として定義されている)。

マスタ クロックへのインターフェイスを取得するには、IDirectMusic8::GetMasterClock メソッドを使う。

アプリケーションでほかのマスタ クロックも選択できる。ただし、マスタ クロックを選択できるのは、ほかに動作中の DirectMusic アプリケーションがないときだけである。最初に IDirectMusic8::EnumMasterClock メソッドを使って、マスタ クロックの機能を果たせるすべてのデバイスの記述を取得する。マスタ クロックとして使いたいデバイスの GUID を取得した後で、その GUID を IDirectMusic8::SetMasterClock メソッドに渡す。


クロック タイムとミュージック タイム

DirectX for C++ では、マスタ クロックによって返されるタイムは、REFERENCE_TIME 型で定義される 64 ビット値である。基準タイムはおよそ 100 ナノ秒 (ns) 単位で測定されるので、クロックのティック (目盛り) は 1 秒間におよそ 10,000,000 個存在する。IReferenceClock::GetTime メソッドは、任意の開始タイム以降に経過した時間を返す。

ミュージック タイムは、MUSIC_TIME 型として定義される 32 ビット値である。これは時間の絶対的な測定値ではなく、テンポに基づく相対値である。クロックは、パフォーマンスが初期化されるときに開始され、4 分音符あたり DMUS_PPQ の時間が経過するDMUS_PPQ は、現在 768 に定義されている。

パフォーマンスが初期化されるときに、内部クロックの維持が開始される。IDirectMusicPerformance8::GetTime メソッドを使って、現在のパフォーマンス タイムを基準タイムとミュージック タイムの両方で取得することができる。

IDirectMusicPerformance8::AdjustTime メソッドを使うと、パフォーマンス タイムをわずかに変更することができる。ほとんどのアプリケーションでは、この操作を実行する必要はない。ただし、ほかのソースに同期させる場合には、この処理が役に立つ。

パフォーマンス内でこれら 2 種類のタイムを変換するには、IDirectMusicPerformance8::MusicToReferenceTime と IDirectMusicPerformance8::ReferenceToMusicTime の各メソッドを使う。これらのメソッドは、パフォーマンス開始後のすべてのテンポの変更を考慮して、パフォーマンス内のタイム オフセットを相互に変換する。

IDirectMusicPerformance8::PlaySegment または IDirectMusicPerformance8::PlaySegmentEx を呼び出して、演奏したいセグメントを挿入する際に、基準タイムを使って開始タイムを指定する。その時点でプライマリ セグメントが演奏されていない場合、このタイムは現在のテンポに従って直ちにミュージック タイムに変換される。ほかのプライマリ セグメントが演奏されている場合は、挿入されたセグメントの開始タイムに達した時点で、その開始タイムはミュージック タイムに変換される。

セグメントの演奏が開始される前にテンポが変更された場合は、実際の開始タイムが影響を受けたり、セグメントが希望した境界で開始されない場合がある。前者の状況では、直ちにミュージック タイムへの変換が行われる。テンポの速度が上昇した場合は (基準タイムでの) 開始タイムは早まり、テンポの速度が低下した場合は遅れる。後者の状況では、開始タイムに変換が行われるので、テンポの変更が発生すると、正確な分解能の境界でセグメントが始まらないことを意味する。たとえば、セグメントがある小節境界 (PlaySegment または PlaySegmentEx の dwFlags パラメータで指示) で開始される場合、基準タイムでの実際の開始タイムは、セグメントがキューに格納されるときに計算される。その後でテンポが変更されると、小節境界が計算したタイムどおりにならない可能性がある。

プライマリ セグメントが DMUS_SEGF_QUEUE フラグと共に演奏されるときに (DMUS_SEGF_FLAGS を参照)、i64StartTime パラメータは無視され、セグメントは、既に開始タイムが変換されているプライマリ セグメントの後で演奏されるように、キューに格納される。これは、基準タイムを指定して現在キューに置かれているセグメントが、DMUS_SEGF_QUEUE セグメントに割り込む可能性があることを意味する。

たとえば、3 つのセグメントがあり、それぞれの長さが 10 秒であるとする。セグメント A を、今から 5 秒後に演奏するようにキューに格納する。現在演奏されているプライマリ セグメントはないため、開始タイムは直ちにミュージック タイムに変換される。6 秒経過した時点で、セグメント B を 20 秒から演奏するようにキューに格納する。この場合、既に音楽が演奏中で、テンポが変更されている可能性があるため、ミュージック タイムへの変換はすぐには行われない。次に、DMUS_SEGF_QUEUE フラグを設定したセグメント C を、セグメント A が終了しだい、つまり 15 秒から演奏するようにキューに格納する。20 秒の時点で、セグメント B の演奏が開始され、セグメント C が中断される。


テンポの変更

パフォーマンスのテンポは、DirectMusic で使用される 2 種類のタイムの変換を指示し、音楽境界のイベントの分解能を制御する(「クロック タイムとミュージック タイム」を参照すること)。通常、制御セグメントのテンポ トラックがテンポを管理するが、アプリケーションで動的にテンポを設定することもできる。

テンポを変更する方法は 2 つある。メッセージを送信する方法と、制御セグメントにトラック パラメータを設定する方法である。

次のサンプル コードでは、メッセージを送信してテンポを変更している。

// pIDMSegment は有効な IDirectMusicSegment8 であり、
// IDMPerformance は有効な IDirectMusicPerformance8 であると仮定する。

// セグメントのテンポ トラックを無効にして、テンポをリセットしないようにする。

pIDMSegment->SetParam( GUID_DisableTempo, 0xFFFF,0,0, NULL );

DMUS_TEMPO_PMSG* pTempo;

if( SUCCEEDED(pIDMPerformance->AllocPMsg(
        sizeof(DMUS_TEMPO_PMSG), (DMUS_PMSG**)&pTempo)))
{
    // テンポ イベントをキューに格納する。
    ZeroMemory(pTempo, sizeof(DMUS_TEMPO_PMSG));
    pTempo->dwSize = sizeof(DMUS_TEMPO_PMSG);
    pTempo->dblTempo = 100;
    pTempo->dwFlags = DMUS_PMSGF_REFTIME;
    pTempo->dwType = DMUS_PMSGT_TEMPO;
    pIDMPerformance->SendPMsg((DMUS_PMSG*)pTempo);
}

次の例は、テンポ パラメータを変更する方法を示している。詳細については、「トラック パラメータの設定と取得」を参照すること。

DMUS_TEMPO_PARAM Tempo;
Tempo.dblTempo = 100;
pIDMSegment->SetParam(GUID_TempoParam, 0xFFFF, 0, 0, &Tempo);

制御セグメントによって設定されたテンポを調整するマスタ テンポを変更することもできる。「グローバル パラメータの設定と取得」を参照すること。


準備時間

セグメントを演奏するときに、パフォーマンスはセグメントのトラックを繰り返し呼び出す。この呼び出しにより、1 秒の何分のいくつかの指定された時間範囲分のメッセージが生成される。これらのメッセージは、これまでの呼び出しで生成されたメッセージの後ろに挿入される。デフォルトでは、およそ 1 秒分のメッセージが、いつでもキューにある。

パフォーマンスがメッセージを演奏するようにトラックに要求するごとに、現在のタイムに準備時間を加算して、呼び出しの終了タイムが計算される。現在のタイムが 10,000 ミリ秒 (または、等価な REFERENCE_TIME 単位) で、準備時間がデフォルトで 1000 ミリ秒である場合、終了タイムは 11,000 となる。つまり、11,000 までの演奏分の新しいメッセージをすべて準備して、キューに格納しなければならない。

キューのサイズは、IDirectMusicPerformance8::SetPrepareTime メソッドを呼び出して変更することができる。また、現在のサイズは、IDirectMusicPerformance8::GetPrepareTime を使って取得することができる。

ほとんどのアプリケーションでは、デフォルトの準備時間を変更する必要はない。ここで説明した処理は、アプリケーションからは認識されていない。ただし、アプリケーションは IDirectMusicPerformance8::PlaySegment または IDirectMusicPerformance8::PlaySegmentEx にDMUS_SEGF_AFTERPREPARETIME フラグを渡すことができるので、準備時間の概念を理解しておくと役立つ。

このフラグを使用しない場合、セグメントの開始タイムを "現在" に設定すると、パフォーマンスは現在キューに格納されているメッセージをすべて無効にする。この時点で有効なままのトラック (たとえば、新しいプライマリ セグメントの導入にかかわらず、演奏が続けられるセカンダリ セグメントのトラック) は、新しいセグメントによる環境の変化を考慮して、メッセージを再送信しなければならない。これによって、追加の処理が発生し、好ましくない結果になる場合もある。

DMUS_SEGF_AFTERPREPARETIME フラグを使用して、現在キュー内にあるすべてのメッセージが処理され、ポート バッファに渡されるまで、セグメントを演奏しないことを指定できる。タイム 10,000 までのメッセージがキューにあり、現在のタイムが 9,000 ms の場合、演奏用にキューに格納され、DMUS_SEGF_AFTERPREPARETIME フラグが設定されたセグメントは、ちょうど 10,000 ミリ秒後に演奏を開始する。

詳細については、「セグメントのタイミング」を参照すること。「遅延時間とバンパー時間」の図も参照すること。


遅延時間とバンパー時間

遅延時間とは、ポートが メッセージを受け取ってから、演奏すべき十分なウェーブが合成されるまでの遅れを意味する。IDirectMusicPerformance8::GetLatencyTime メソッドは、現在のタイムにパフォーマンスの遅延時間を加算した全体の時間を取得する。この値は、ポートの遅延時間クロックによって返される最大の値である。

バンパーとは、イベントがポート バッファに置かれてから、ポートがそのイベントの処理を開始するタイムまでの、コードを実行するために割り当てられた時間である。デフォルトでは、バンパーの長さは 50 ミリ秒 (ms) である。アプリケーションは、IDirectMusicPerformance8::SetBumperLength メソッドを使ってこの値を変更し、IDirectMusicPerformance8::GetBumperLength を呼び出して現在の値を取得できる。

ここでは、遅延時間とバンパー時間を結合する方法を示す。あるイベントが 10,000 ミリ秒の時点で演奏されると仮定する。このポートの遅延時間は 100 ミリ秒であること、およびバンパー時間の長さはデフォルトの 50 ミリ秒であることがわかっている。そのため、パフォーマンスは 9,850 ミリ秒の時点でこのメッセージをポート バッファに置く。

メッセージのタイムを変更するツールは、遅延時間とバンパー時間を考慮しなければならない。ツールが、既に遅延時間を経過したタイムをメッセージにスタンプする場合、ノートやその他のイベントは正しいタイムに演奏されない。

ポート バッファに置かれたメッセージは、もはやパフォーマンスに所属していないため、IDirectMusicPerformance8::Invalidate メソッドを使っても、セグメントを停止しても演奏を止められない点に注意すること。無効にできる最初のメッセージは、現在のタイムに遅延時間とバンパー時間を加えたタイムと同じか、それ以降のタイム スタンプを持つ。IDirectMusicPerformance8::GetQueueTime メソッドを使うと、この値を取得することができる。

次の図は、さまざまなメソッドで取得される、タイムと継続時間の関係を示している。現在のタイムは左側に示されている。右側が、メッセージの準備が完了する最終タイムである。準備時間はいつでも、キューにあるメッセージの合計の長さの近似である。


セグメントのタイミング

ここでは、セグメントの演奏のタイミングに関するさまざまな面について説明する。

セグメントのタイムとパフォーマンスのタイムとの関係を明確にするために、ここでは次の用語を使用する。

開始ポイント
セグメントの開始タイムになりうるセグメント内の最初のポイント。デフォルトの場合、この値は 0 で、セグメントの先頭を示す。ただし、この値はアプリケーションで変更できる。
セグメントの開始タイム
サウンドの生成が開始されるセグメント内のポイント。このタイムは通常開始ポイントと同じであるが、開始ポイントが意図的に過去の演奏タイムに揃えられている場合は、遅くすることもできる。
演奏タイム
新しいセグメントの開始ポイントがキューに入れられるパフォーマンス内のポイント。DirectMusic API では、このタイムは開始タイムと呼ばれることもある。
開始マーカー
セグメント内の有効な開始タイムを示すマーカー。
演奏マーカー
制御セグメント内で、別のセグメントの開始ポイントをキューに入れることができるポイントを示すマーカー。

注 開始マーカーおよび演奏マーカーは、オーサーによってセグメントのマーカー トラックに配置され、アプリケーションで変更することはできない。ただし、GUID_Valid_Start_Time および GUID_Play_Marker パラメータを使用して取得できる。

セグメントは、通常、最初から演奏される。IDirectMusicSegment8::SetStartPoint メソッドを使用して、別のポイントからセグメントを開始することもできる。新しい開始ポイントは、変更されるまで有効である。

IDirectMusicSegment8::SetRepeats を使ってリピート回数を設定した場合、IDirectMusicSegment8::SetLoopPoints を呼び出してループを定義しなければ、セグメント全体がその回数だけ反復される。

演奏タイムは、IDirectMusicPerformance8::PlaySegment または IDirectMusicPerformance8::PlaySegmentEx メソッドの 2 つのパラメータによって決定される。

  • i64StartTime パラメータは、セグメントの演奏を開始できる、最も早いタイムを設定する。i64StartTime が 0 の場合は、可能な限り早いタイムとなる。セグメントが開始される実際のタイムは、セグメントの種類によって異なる。プライマリ セグメントまたは制御セグメントの場合、最も早い演奏タイムはキュー (またはフラッシュ) 時間である。制御以外のセカンダリ セグメントの場合、最も早い演奏タイムは遅延時間後である。キュー時間と遅延時間の詳細については、「遅延時間とバンパー時間」を参照すること。
  • dwFlags パラメータは、最も早い演奏タイムの後、どれくらいすぐにセグメントの演奏を実際に開始するかを指定する。通常、新しいプライマリ セグメント、トランジション、またはモチーフを開始する前に、リズムの適切なポイント待つ。次の DMUS_SEGF_FLAGS 列挙型の 1 つ以上を設定することにより、遅延を制御する。

セグメントを過去のタイムに揃える

セグメントの開始タイムを制御セグメントの次のグリッド、拍、または小節に揃える代わりに、セグメントの演奏をすぐに開始し、現在のセグメントのリズムに合わせたい場合がある。このようにするには、セグメントの開始ポイントのキューを既に経過したリズム境界に与える。キューを与えたセグメントのリズムは、現在のセグメントに揃えられ、新しいセグメントは直ちに演奏を開始できる。

過去のセグメントにキューを与えるには、DMUS_SEGF_ALIGN フラグを使用する。適切なリズム境界でセグメントの開始ポイントにキューを与えるには、DMUS_SEGF_GRID、DMUS_SEGF_BEAT、または DMUS_SEGF_MEASURE のいずれかを追加する。この代わりに、DMUS_SEGF_MARKER を使用して、開始ポイントを制御セグメントの最後に演奏された演奏マーカーに揃えることもできる。

開始ポイントが過去である場合、セグメントの開始タイムが現在または将来になるように調整しなければならない。パフォーマンスは、次の規則に従って、セグメントの開始タイムを決定する。いずれの場合も、"次" とは "次に可能" であることを意味する。つまり、セグメントの、過去ではない部分にあるという意味である。

  • 開始マーカーが、キューを与えられたセグメントの、指定されたタイプの次の分解能境界よりも前にある場合、そのセグメントの開始タイムはそのポイントになる。
  • 有効な開始マーカーがない場合、セグメントの開始タイムはキューを与えられたセグメントの次の開始分解能境界になる。これは次のいずれかのフラグで指定される。
    DMUS_SEGF_VALID_START_BEAT
    セグメントの開始タイムを次の拍にする。
    DMUS_SEGF_VALID_START_GRID
    セグメントの開始タイムを次のグリッドにする。
    DMUS_SEGF_VALID_START_TICK
    セグメントの開始タイムを最も早いポイントにする。
  • 有効な開始マーカーがなく、開始分解能フラグが指定されていない場合、セグメントの開始タイムは次の演奏分解能境界になる。これは、DMUS_SEGF_GRID、DMUS_SEGF_BEAT、または DMUS_SEGF_MEASURE フラグで指定される。これらのフラグがいずれも存在しない場合、セグメントの開始タイムは即時になる。

演奏マーカーと開始マーカーによって、セグメント、特にモチーフに柔軟にキューを与えることができる。モチーフが、プライマリ セグメントの小節の先頭で演奏を開始するときに最適に演奏されるように作成されているとする。このモチーフに DMUS_SEGF_MEASURE フラグでキューを与えると、次の小節境界に達して、モチーフが演奏されるまでに大幅な遅延が発生する場合がある。しかし、DMUS_SEGF_ALIGN フラグを追加すると、リズムを乱すことなく、すぐにモチーフの演奏を開始できる。DMUS_SEGF_MARKER フラグを追加すると、小節、拍、またはグリッドだけでなく、制御セグメント内の適切な境界でモチーフを演奏できるようになる。

テンポの変更によってセグメントの開始タイムが受ける影響については、「クロック タイムとミュージック タイム」を参照すること。

次の図は、DMUS_SEGF_MEASURE、DMUS_SEGF_ALIGN、および DMUS_SEGF_VALID_START_BEAT の各フラグを使ってキューに入れられたセグメントのタイミングを決定する過程を示している。縦の実線は小節の境界を示し、点線は拍の境界を示す。セグメントの開始ポイントは、現在のプライマリ セグメントの前にある小節境界に揃えられる。セグメントの開始タイムは、未解決の演奏タイムの後に挿入されているセグメントの最初の拍になる。

論理的なタイムと実際のタイム

一部のイベントは、論理的なタイムと実際のタイムの両方を持っている。実際のタイムはイベントが発生するときであり、論理的なタイムはイベントが属する音楽的な位置を表す。

たとえば、セグメントは、拍の開始に属するプログラム チェンジを含む場合がある。この拍の開始は論理的なタイムである。しかし、拍のノートが演奏される前にプログラム チェンジが行われるようにしたいので、これよりも少し早い物理的なタイムを割り当てる。

セグメントが論理的なタイム (同じ拍の開始) にループする場合、プログラム チェンジも行われる。


通知とイベントの処理

アプリケーションでパフォーマンス イベントに応答しなければならない場合がある。たとえば、セグメントの終了に到達したことを知る必要がある場合や、グラフィックスを音楽の拍に同期させたい場合がある。特定のタイプのイベントが発生したときに、そのことを通知するよう DirectMusic に指示して、必要な情報を取得することができる。

注 パフォーマンス通知と DirectSound のバッファ通知を混同してはならない。DirectSound のバッファ通知は、バッファに対して直接ウェーブ データをストリーミングするアプリケーションでのみ使用される。「再生バッファの通知」および「キャプチャ バッファの通知」を参照すること。

通知を受けたい音楽イベントの種類を指定するには、イベントの種類ごとに一度だけ IDirectMusicPerformance8::AddNotificationType メソッドを呼び出す。次のサンプル コードでは、DirectMusic にセグメントに関連するイベントを設定するように指示している。実際のイベントの種類 (セグメントの開始やセグメントの終了など) は、通知メッセージから得られる。

// pPerformance は有効な IDirectMusicPerformance8 ポインタである。

GUID guid = GUID_NOTIFICATION_SEGMENT;

pPerformance->AddNotificationType(guid);

IDirectMusicSegment8::AddNotificationType メソッドを使って、特定のセグメントに対して通知タイプを追加することもできる。たとえば、特定のセグメントが演奏を停止したときに通知を受け取るような場合に、この設定を行うことができる。このメソッドを使って GUID_NOTIFICATION_PERFORMANCE 型を要求することはできない。これらの型は、パフォーマンス オブジェクトから取得しなければならない。

注 ほとんどのアプリケーションは、IDirectMusicTrack8::AddNotificationType メソッドを直接呼び出さない。

通知に関する情報は、DMUS_NOTIFICATION_PMSG メッセージ構造体で送信される。IDirectMusicPerformance8::GetNotificationPMsg メソッドを呼び出して、Windows メッセージ ループ内で保留中の通知メッセージをポーリングすることができる。また、メッセージが保留中のときに、DirectMusic に別のスレッドでイベント オブジェクトを通知させることもできる。

Windows イベント オブジェクトを使って、保留中の DirectMusic 通知メッセージを知らせたい場合は、まず Microsoft® Win32® CreateEvent 関数を呼び出して、イベント ハンドルを取得しなければならない。通常は、次のような呼び出しを行って、自動リセット イベントを作成する。

HANDLE g_hNotify = CreateEvent(NULL, FALSE, FALSE, NULL);

イベントの作成後、このハンドルを IDirectMusicPerformance8::SetNotificationHandle メソッドに渡してパフォーマンスに割り当てる。このメソッドの 2 番目のパラメータを使用して、DirectMusic で、取得されていないイベントを待機する時間を指定できる。このパラメータの値が 0 の場合は、デフォルトの時間である 2 秒が使用される。

次の例では、g_pPerf は IDirectMusicPerformance8 インターフェイスへの有効なポインタを表している。

g_pPerf->SetNotificationHandle(g_hNotify, 0);

次のサンプル関数は、独自のスレッドで繰り返し実行され、通知されたイベントを確認して、通知メッセージを取り出している。

void WaitForEvent( LPVOID lpv)
{
    DWORD dwResult;
    DMUS_NOTIFICATION_PMSG* pPmsg;
    char szCount[4];

    while (TRUE)
    {
        dwResult = WaitForSingleObject(g_hNotify, 100);
        while (S_OK == g_pPerf->GetNotificationPMsg(&pPmsg))
        {
            // 通知タイプをチェックし、それに応じて処理を行う。
            .
            .
            .
            g_pPerf->FreePMsg((DMUS_PMSG*)pPmsg);
        }
    }
}

このスレッドは次のように実行される。

_beginthread(WaitForEvent, 0, NULL);

通知が必要なくなった場合は、次のコードに示すように、スレッドをシャット ダウンし、パフォーマンスから通知ハンドルを削除し、イベント オブジェクトを破棄する。

_endthread();
g_pPerf->SetNotificationHandle(0, 0);
CloseHandle(g_hNotify);

アプリケーションのメッセージ ループで、イベントを作成して通知メッセージを取得する必要はない。AddNotificationType メソッドのいずれかを呼び出して通知を要求している場合、メッセージはパフォーマンスによって送信され、IDirectMusicPerformance8::GetNotificationPMsg の呼び出しで取得することができる。

イベントが通知される場合、またはメッセージ ループで GetNotificationPMsg を呼び出す場合は、複数のメッセージを待機することができる。すべての通知を確実に受け取るには、S_FALSE が返されるまで GetNotificationPMsg の呼び出しを繰り返す。

同じタイム スタンプを持つメッセージが複数ある場合、これらのメッセージはキューに格納されるときに特定の順序にはならない。

アプリケーションは、IDirectMusicPerformance8::FreePMsg メソッドを呼び出して、取得したメッセージを解放する必要がある。


パフォーマンス パラメータ

DirectMusic では、次の SetParam メソッドのいずれかを使って再生中にパラメータを変更し、トラックのさまざまな動作を制御することができる。

  • IDirectMusicPerformance8::SetParam は、このパフォーマンスの現在の制御セグメント内で、特定のトラックにデータを設定する。制御セグメントは、通常はプライマリ セグメントであるが、セカンダリ セグメントを演奏中に制御セグメントとして指定することができる。「制御セグメント」を参照すること。
  • IDirectMusicSegment8::SetParam は、セグメント内の特定のトラックにデータを設定する。
  • IDirectMusicTrack8::SetParam および IDirectMusicTrack8::SetParamEx は、インターフェイスによって表されるトラックにデータを設定する。アプリケーションは、通常、個々のトラックに対するインターフェイスを持たない。

IDirectMusicPerformance8::SetGlobalParam メソッドを使って、パフォーマンス全体に適用される値を設定することができる。

GetParam および GetGlobalParam メソッドは、トラックまたはパフォーマンスの現在の値を取得する。

変更されたパラメータに音楽を直ちに応答させるには、アプリケーションで IDirectMusicPerformance8::Invalidate メソッドを使って、キューからメッセージをフラッシュする。このメソッドにより、すべてのトラックは指定したポイント以降のメッセージを再送信する。

パラメータの詳細については、次のトピックを参照すること。

  • トラック パラメータの設定と取得
  • トラック パラメータの無効化と有効化
  • グローバル パラメータの設定と取得


トラック パラメータの設定と取得

トラック パラメータを設定および取得するために、以下のメソッドが使用される。

  • IDirectMusicPerformance8::GetParam
  • IDirectMusicPerformance8::SetParam
  • IDirectMusicSegment8::GetParam
  • IDirectMusicSegment8::SetParam
  • IDirectMusicTrack8::GetParam
  • IDirectMusicTrack8::SetParam
  • IDirectMusicTrack8::GetParamEx
  • IDirectMusicTrack8::SetParamEx

パフォーマンスまたはセグメントでこれらのメソッドのいずれかを呼び出すときに、dwGroupBits および dwIndex パラメータを設定して、トラックを識別することができる。ただし、通常は、DirectMusic に適切なトラックを検索させることができる。詳細については、「トラックの識別」を参照すること。

設定または取得するトラック パラメータは、メソッドの rguidType パラメータにある GUID で識別される。データを必要とする各パラメータは、特定のデータ型に関連付けられている。pParam は、この型の変数または構造体を指していなければならない。場合によっては、パラメータを取得するときにも、データ構造体の一部を初期化する必要がある。また、パラメータによっては、変更を行うタイム、またはパラメータを取得するタイムをトラック内で指定しなければならない。

標準的なパラメータ タイプに関連するデータのリファレンス情報については、「標準トラック パラメータ」を参照すること。

一部のパラメータの変更は、直ちに有効にならないように見える。たとえば、グルーブ レベルの変更は、現在のパターンの演奏が終了し、次のパターンを選択するまで変化がない。この変更を直ちに有効にするには、IDirectMusicPerformance8::Invalidate メソッドを呼び出して、現在のパターンを強制的に破棄することができる。

特定のパラメータがトラックによってサポートされているかどうかを確認するには、IDirectMusicTrack8::IsParamSupported メソッドを使用して、S_OK の結果を確認する。

詳細については、次のトピックを参照すること。

  • トラックの識別


トラックの識別

IDirectMusicTrack8::SetParamEx または IDirectMusicTrack8::GetParamEx を使ってパラメータを設定または取得するときに、パラメータはメソッドを呼び出したトラックに関連付けられる。ただし、IDirectMusicPerformance8::SetParam、IDirectMusicPerformance8::GetParam、IDirectMusicSegment8::SetParam、または IDirectMusicSegment8::GetParam を呼び出すときに、DirectMusic は適切なトラックを検索する必要がある。

通常は、目的のパラメータがどのトラックに含まれるかを、DirectMusic に決定させることができる。この場合、dwGroupBits を 0xFFFFFFFF に、dwIndex を DMUS_SEG_ANYTRACK に設定する。たとえば、次の IDirectMusicSegment8::SetParam の呼び出しでは、セグメントのループでテンポがリセットされないように、テンポ トラックをオフにしている。

pIDMSegment->SetParam(GUID_DisableTempo, 0xFFFFFFFF,
    DMUS_SEG_ALLTRACKS, 0, NULL);

ただし、トラックを識別しなければならない場合もある。一般的には、セグメントに同じタイプのトラックが 2 つ以上含まれている場合である。目的のトラックでパラメータを設定または取得するには、グループまたはインデックス値を使って、トラックを識別しなければならない。

すべてのトラックは 1 つまたは複数のグループに属し、それぞれのグループは dwGroupBits パラメータのビットで表される。dwGroupBits は、後で説明するメソッドの 1 つのパラメータである。トラックは、パフォーマンスに挿入されるときに、1 つまたは複数のグループに割り当てられる。「IDirectMusicSegment8::InsertTrack」を参照すること。ファイルからロードされるセグメントの場合、トラック グループはセグメントのオーサーによって割り当てられる。

トラックは、属しているグループそれぞれにおいて、ゼロから始まるインデックス値で識別される。インデックス値は、トラックが挿入された順序で決定される。

あるセグメントに、次の表に示すトラックが格納されていると仮定する。

トラック | グループ ビット
A | 0x1
B | 0x2
C | 0x1
D | 0x3

グループ 1 はトラック A、トラック C、およびトラック D を含み、グループ 2 はトラック B とトラック D を含む。dwGroupBits を 1、dwIndex を 0 にして設定メソッドまたは取得メソッドを呼び出すと、パラメータは、グループ 1 の最初のトラックであるトラック A から取得される。dwIndex が 1 の場合は、グループで 2 番目のトラック C からパラメータが取得される。トラック D は、グループ 1 とグループ 2 の、2 つのグループに属している。したがって、このトラックは、dwGroupBits = 1 および dwIndex =2、または dwGroupBits = 2 および dwIndex = 1 の組み合わせのどちらかで識別される。

dwGroupBits に複数のビットを設定すると、それらのすべてのビットを含む n 番目のトラックからパラメータが取得される。ここで n は dwIndex 内の値である。


トラック パラメータの無効化と有効化

トラックについて GUID_DisableTempo および GUID_DisableTimeSig パラメータを設定すると、制御セグメントによるテンポおよび拍子記号の設定を無効にすることができる。たとえば、動的にテンポを設定して、プライマリ セグメントにテンポ メッセージを送信させたくない場合などに使用できる。

このパラメータを再び有効にするには、rguidType パラメータに GUID_EnableTempo または GUID_EnableTimeSig を指定して、いずれかのパラメータ設定メソッドを呼び出す。これらのパラメータを設定して、制御セグメントでないセグメントにテンポ メッセージを送信させたり、セカンダリ セグメントに拍子記号メッセージを送信させることもできる 詳細については、「制御セグメント」を参照すること。

パラメータを設定する方法については、「トラック パラメータの設定と取得」を参照すること。

「IDirectMusicTrack8::IsParamSupported」の「注意」も参照すること。

トラックの構成フラグを設定することによって、任意のトラック パラメータを無効または有効にすることもできる。詳細については、「トラック構成」を参照すること。


グローバル パラメータの設定と取得

IDirectMusicPerformance8::SetGlobalParam および IDirectMusicPerformance8::GetGlobalParam メソッドを使うと、1 つのトラックだけでなく、パフォーマンス全体に影響するパラメータを設定および取得することができる。

設定または取得するパラメータは、メソッドの rguidType パラメータにある GUID で識別される。各パラメータは特定のデータ型に関連付けられる。データ型のサイズは、dwSize パラメータで与えられる。次の表は、定義済みの GUID とそのデータ型を示している。

パラメータ タイプの GUID (rguidType) とデータ (*pParam) | 説明
GUID_PerfAutoDownload BOOL | このパラメータは、セグメントを演奏するときに音色を自動的にダウンロードするかどうかを制御する。デフォルトではオフである。「バンドのダウンロードとアンロード」を参照すること。
GUID_PerfMasterGrooveLevel char | マスタ グルーブ レベルは、コマンド トラックで設定されるグルーブ レベルに常に加算される値である。返される値は 1 ～ 100 の範囲に収まるように必要に応じて調整される。
GUID_PerfMasterTempo float | マスタ テンポは、最終出力ツールによってテンポに適用されるスケーリング係数である。デフォルトの値は 1 である。0.5 でテンポは 2 分の 1 になり、2.0 で 2 倍のテンポになる。この値は、DMUS_MASTERTEMPO_MIN から DMUS_MASTERTEMPO_MAX の範囲で設定できる。
GUID_PerfMasterVolume long | マスタ ボリュームは、増幅または減衰の係数で、1 デシベルの 100 分の 1 の単位で表される。そのパフォーマンス全体のデフォルトのボリュームと、同じシンセサイザを使用しているほかのすべてのパフォーマンスに適用される。設定できる値の範囲はポートによって決まる。デフォルトのソフトウェア シンセサイザの場合、許容範囲は +20db ～ -200dB であるが、実用範囲は +10db ～ -100db である。ハードウェア MIDI ポートでは、マスタ ボリュームの変更はサポートされていない。

アプリケーションは、独自のタイプのグローバル パラメータを使うこともできる。新しいタイプを作成するには、GUID とそのデータ型を確定する。

パラメータを設定するときに、パフォーマンスは、GUID で識別されるリンクされた項目のリストのデータにメモリを割り当てる。データは、IDirectMusicPerformance8::GetGlobalParam を呼び出して取得できる。

注 定義済みのパラメータも、取得する前に設定しなければならない。パラメータに対して SetGlobalParam が呼び出されていない場合、GetGlobalParam は失敗する。


オーディオパスの使い方

DirectMusic パフォーマンスには 1 つ以上のオーディオパスが含まれる。オーディオパスは、さまざまなオブジェクトによってサウンド データの流れを管理する。オーディオパスには、パフォーマンス自体、セグメント、ツールグラフ、シンセサイザ、DirectSound バッファ、エフェクト DMO、および最終的なミキシングが行われるプライマリ DirectSound バッファが含まれる場合がある。

アプリケーションで 2D サウンド エフェクトや MIDI ファイルの再生以外の複雑な処理を行わない場合は、デフォルトの標準オーディオパスを設定し、そこですべての再生を行う。ただし、DirectX Audio の機能を最大限に利用するには、オーディオパスを制御する必要がある。

ここでは、オーディオパスの作成、オーディオパスでのセグメントの演奏、およびオーディオパス内のオブジェクトへのアクセスについて説明する。説明するトピックは、次のとおりである。

  • ポートからオーディオパスへの移行
  • オーディオパスの作成
  • デフォルトのオーディオパス
  • 標準オーディオパス
  • オーディオパスでのサウンドの再生
  • オーディオパスからのオブジェクトの取得


ポートからオーディオパスへの移行

DirectX 8.0 以前のバージョンの DirectMusic を使ってアプリケーションを作成していた場合、オーディオ出力へのルートの推奨される作成方法が変更されている。以前の方法で DirectMusic を使用することもできるが、エフェクト処理、個々のセグメント状態の制御、および DirectMusic Producer セグメントのカスタム オーディオパス構成などの機能を利用するには、新しい方法に従う必要がある。

オーディオ出力の以前のモデルと新しいモデルには、次のような違いがある。

  • アプリケーションは直接ポートを操作しない。DirectMusic がポートの作成およびパフォーマンス チャンネルのマッピングを処理する。IDirectMusicPerformance8::Init、IDirectMusicPerformance8::AddPort、IDirectMusicPerformance8::AssignPChannel、および IDirectMusicPerformance8::AssignPChannelBlock の各メソッドは、オーディオパス モデルでは使用されない。
  • 3D バッファを使ってサウンドを再生する場合、アプリケーションで明示的にバッファを作成し、IDirectMusicPort8::SetDirectSound を使ってバッファをポートに割り当てる必要がなくなった。バッファはオーディオパスの一部として作成され、アプリケーションは GetObjectInPath メソッドのいずれかを使用してバッファにアクセスできる。
  • オーディオパスを非アクティブにした場合とポートを非アクティブにした場合では、異なる結果が得られる。ポートを非アクティブにすると、サウンドは生成されなくなるが、パフォーマンスによってセグメントの再生は継続される。オーディオパスを非アクティブにすると、そのオーディオパスのすべての再生が停止して、何を行ってもセグメントを再生できなくなる。


オーディオパスの作成

アプリケーションでは、次の方法でオーディオパスを設定できる。

  • IDirectMusicPerformance8::CreateStandardAudioPath を使って、1 つまたは複数の標準オーディオパスを作成する。「標準オーディオパス」を参照すること。
  • IDirectMusicPerformance8::InitAudio の呼び出しで、パフォーマンスのデフォルトの標準オーディオパスを作成する。「デフォルトのオーディオパス」を参照すること。
  • DirectMusic Producer で作成されたファイルからオーディオパス構成を取得し、構成オブジェクトを IDirectMusicPerformance8::CreateAudioPath に渡す。
  • セグメントを演奏するときに、セグメントのオーディオパス構成から DirectMusic にオーディオパスを作成させる。この方法で作成されたオーディオパスは、一時的であり、アプリケーションでは認識されない。

オーディオパス構成オブジェクトは、IDirectMusicLoader8::GetObject または IDirectMusicLoader8::LoadObjectFromFile を使って、ほかのオブジェクトと同様にロードできる。セグメントに埋め込まれている構成は、IDirectMusicSegment8::GetAudioPathConfig を使って取得できる。

オーディオパス構成オブジェクトは、固有のインターフェイスやメソッドを持たないので、アプリケーションで構成を変更することはできない。このオブジェクトに対して可能な処理は、オブジェクトの IUnknown インターフェイスを使って、IDirectMusicPerformance8::CreateAudioPath に渡すことだけである。サンプル コードについては、「オーディオパスでのサウンドの再生」を参照すること。

オーディオパス構成は、標準以外のオーディオパスを作成する唯一の方法である。たとえば、複数のパフォーマンス チャンネルが複数のバッファにルーティングされる場合、このマッピングはセグメントのオーディオパス構成で指定しなければならない。


デフォルトのオーディオパス

デフォルトのオーディオパスは、セグメントが IDirectMusicPerformance8::PlaySegment を使って演奏される場合、または IDirectMusicPerformance8::PlaySegmentEx の呼び出しでオーディオパスが指定されていない場合に使用される。

オーディオパスを作成し、IDirectMusicPerformance8::InitAudio の dwDefaultPathType パラメータで標準タイプを指定することによってデフォルトのオーディオパスにすることができる。

既存のオーディオパスは、IDirectMusicPerformance8::SetDefaultAudioPath に渡すことによってデフォルトのオーディオパスにすることができる。IDirectMusicPerformance8::GetDefaultAudioPath を使うことによって、デフォルトのオーディオパスを取得する。


標準オーディオパス

オーディオパス構成オブジェクトから作成されたオーディオパス以外のオーディオパスで再生を行う場合は、1 つまたは複数の標準オーディオパスを作成する必要がある。

標準オーディオパスは、IDirectMusicPerformance8::CreateStandardAudioPath の dwType パラメータまたは IDirectMusicPerformance8::InitAudio の dwDefaultPathType パラメータで渡される値によって識別される。

DirectMusic によって定義されるオーディオパスは、標準バッファの組み合わせによってシンセサイザ出力のフローを管理する。標準バッファの一部には、エフェクト DMO が付加されている。次の表は、標準オーディオパスと、標準オーディオパスに含まれる標準的なバッファを示している。複数のオーディオパスで共有バッファを使用できる。

オーディオパスのタイプ | 標準バッファ | バッファを共有するか
DMUS_APATH_DYNAMIC_3D | 3D ドライ | いいえ
DMUS_APATH_DYNAMIC_MONO | モノラル | いいえ
DMUS_APATH_DYNAMIC_STEREO | ステレオ | いいえ
DMUS_APATH_SHARED_STEREOPLUSREVERB | ステレオ リバーブ | はい はい

標準的なバッファの特性を次の表に示す。「能力」の欄には、IDirectSoundBuffer8::GetCaps に渡される DSBCAPS 構造体の dwFlags メンバで返される値が示されている。最後の欄は、バッファ オブジェクトから常に取得できるインターフェイスを示している。また、アプリケーションは IDirectSoundBuffer8::SetFX を使ってバッファにエフェクトを追加できる。この場合、ほかのインターフェイスも使用できる。IDirectSoundBuffer8 は、すべてのバッファについて使用できる。インターフェイスの取得の詳細については、「オーディオパスからのオブジェクトの取得」を参照すること。

標準的なバッファ | 説明 | 能力 | インターフェイス
3D ドライ | モノラル 3D バッファ。 | DSBCAPS_CTRL3D DSBCAPS_CTRLFX DSBCAPS_CTRLVOLUME DSBCAPS_GLOBALFOCUS DSBCAPS_MUTE3DATMAXDISTANCE | IDirectSound3DBuffer8
モノラル | エフェクトを持たないモノラル バッファ。 | DSBCAPS_CTRLFX DSBCAPS_CTRLPAN DSBCAPS_CTRLVOLUME DSBCAPS_GLOBALFOCUS | なし。
リバーブ | ミュージック リバーブ エフェクトを持つステレオ バッファ。 | DSBCAPS_CTRLFX DSBCAPS_CTRLPAN DSBCAPS_CTRLVOLUME DSBCAPS_GLOBALFOCUS | IDirectSoundFXWavesReverb8
ステレオ | エフェクトを持たないステレオ バッファ。 | DSBCAPS_CTRLFX DSBCAPS_CTRLPAN DSBCAPS_CTRLVOLUME DSBCAPS_GLOBALFOCUS | なし。

標準オーディオパスの詳細については、次のトピックを参照すること。

  • DMUS_APATH_DYNAMIC_3D
  • DMUS_APATH_DYNAMIC_MONO
  • DMUS_APATH_DYNAMIC_STEREO
  • DMUS_APATH_SHARED_STEREOPLUSREVERB


DMUS_APATH_DYNAMIC_3D

3D ドライ タイプの非共有バッファを設定する。

アプリケーションは、dwStage を DMUS_PATH_BUFFER に、dwBuffer を 0 に設定して GetObjectInPath メソッドのいずれかを呼び出すことによって、3D ドライ バッファへのインターフェイスを取得できる。


DMUS_APATH_DYNAMIC_MONO

3D パラメータまたは特殊効果を持たないモノラル タイプの非共有バッファを設定する。

アプリケーションは、dwStage を DMUS_PATH_BUFFER に、dwBuffer を 0 に設定して GetObjectInPath メソッドのいずれかを呼び出すことによって、バッファへのインターフェイスを取得できる。


DMUS_APATH_DYNAMIC_STEREO

ステレオ タイプの非共有バッファを設定する。このオーディオパスは、ステレオ バッファ上のサウンド エフェクト用である。リバーブは使用できない。

アプリケーションは、dwStage を DMUS_PATH_BUFFER に、dwBuffer を 0 に設定して GetObjectInPath メソッドのいずれかを呼び出すことによって、バッファへのインターフェイスを取得できる。


DMUS_APATH_SHARED_STEREOPLUSREVERB

リバーブおよびステレオ タイプのバッファを設定する。

ステレオ バッファは複数のオーディオパスで共有される。これはシンクイン バッファで、ほかのバッファからではなく、シンセサイザから直接データを受け取る。

アプリケーションは、dwStage を DMUS_PATH_BUFFER に、dwBuffer を 0 に設定して GetObjectInPath メソッドのいずれかを呼び出すことによって、ステレオ バッファへのインターフェイスを取得できる。

リバーブ バッファも共有シンクイン バッファである。ステレオ バッファとは異なり、シンセサイザからのモノラル入力を受け取り、データをステレオ フォーマットに変換する。

アプリケーションは、dwStage を DMUS_PATH_BUFFER に、dwBuffer を 1 に設定して GetObjectInPath メソッドのいずれかを呼び出すことによって、リバーブ バッファへのインターフェイスを取得できる。

次のサンプル コードは、デフォルトの DMUS_APATH_SHARED_STEREOPLUSREVERB オーディオパス上にあるリバーブ バッファ内の DMO への IDirectSoundFXWavesReverb8 インターフェイスを取得する。g_pPerf は IDirectMusicPerformance8インターフェイスである。

IDirectMusicAudioPath8 * pAudioPath;
IDirectSoundFXWavesReverb8 * pEffectDMO;
HRESULT hr;

hr = g_pPerf->GetDefaultAudioPath(&pAudioPath);
if (SUCCEEDED(hr))
{
  HRESULT hr = pAudioPath->GetObjectInPath(DMUS_PCHANNEL_ALL,
        DMUS_PATH_BUFFER_DMO, 1,
        GUID_All_Objects, 0, IID_IDirectSoundFXWavesReverb8,
        (LPVOID*) &pEffectDMO);
}


オーディオパスでのサウンドの再生

アプリケーションが IDirectMusicPerformance8::InitAudio の呼び出しでデフォルトのオーディオパスを作成した場合、IDirectMusicPerformance8::PlaySegment を使ってこのパスでセグメントを演奏できる。IDirectMusicPerformance8::PlaySegmentEx の pAudioPath パラメータに NULL を渡すことによって、デフォルトのパスでセグメントを演奏することもできる。

デフォルトのオーディオパスがない場合や、セグメントを別のパスで演奏する場合は、PlaySegment ではなく、PlaySegmentEx を使用する。オーディオパスを指定するには、2 つの方法がある。

  • pAudioPath パラメータでポインタを指定する。通常、これは、オーディオパスを作成したときに受け取った IDirectMusicAudioPath8 インターフェイス ポインタである。
  • dwFlags に DMUS_SEGF_USE_AUDIOPATH を含める。このフラグを指定すると、セグメントによって、セグメント オブジェクトに埋め込まれた構成からオーディオパスが作成される。

注 DMUS_SEGF_USE_AUDIOPATH フラグを指定して作成されたオーディオパスは、セグメントの再生が停止すると直ちに解放される。オーディオパスにリバーブなどのエフェクトが含まれる場合、そのエフェクトは中断される。このような突然の中断を防ぐには、手動でオーディオパスを作成し、適切な時間をおいてから解放する。

DMUS_SEGF_USE_AUDIOPATH フラグを使って再生するセグメントについては、自動ダウンロードが有効になっていない限り、バンドはダウンロードされない。詳細については、「バンドの自動ダウンロード」を参照すること。

次のサンプル コードでは、オーディオパス構成が埋め込まれている場合はそれを使ってセグメントを再生し、そうでない場合はデフォルトのオーディオパスでセグメントを再生する。g_pPerf は IDirectMusicPerformance8 インターフェイス ポインタであり、g_pSeg はサウンド ファイルの任意のタイプへの IDirectMusicSegment8 インターフェイスである。

IDirectMusicAudioPath8 * pPath =  NULL;
IUnknown *pConfig;

if (g_pSeg)
{
  if (SUCCEEDED(g_pSeg->GetAudioPathConfig(&pConfig)))
  {
    g_pPerf->CreateAudioPath(pConfig, TRUE, &pPath);
    pConfig->Release();
  }
  g_pPerf->PlaySegmentEx(g_pSeg, NULL, NULL, 0, 0, NULL,
      NULL, pPath);
  if (pPath)
  {
      pPath->Release();
      pPath = NULL;
  }
}

オーディオパスへのインターフェイスがある場合は、IDirectMusicAudioPath8::SetVolume を使ってボリュームを変更できる。グローバル パラメータの GUID_PerfMasterVolume はそのシンセサイザで再生されるすべてのサウンドに影響するが、このメソッドは、そのオーディオパスで再生されるパフォーマンス チャンネルのボリュームだけを設定する。


オーディオパスからのオブジェクトの取得

オーディオパス内の特定のオブジェクトへのインターフェイスを取得しなければならない場合がある。このような場合の一般的な理由は次のとおりである。

  • IDirectSound3DBuffer8 インターフェイスを取得することによって、サウンドの 3D プロパティを操作するため。
  • プライマリ バッファから IDirectSound3DListener8 インターフェイスを取得することによって、グローバル 3D サウンド パラメータを設定するため。
  • IDirectSoundBuffer8 インターフェイスを取得することによって、セカンダリ バッファのエフェクトを設定するため。
  • IDirectSoundFXI3DL2Reverb8 などの DMO へのインターフェイスを取得することによって、エフェクト パラメータを設定するため。

オブジェクトは、オーディオパスで演奏中のセグメント状態について IDirectMusicSegmentState8::GetObjectInPath を呼び出すことによって、オーディオパスから取得できる。オーディオパス オブジェクト自体について IDirectMusicAudioPath8::GetObjectInPath を呼び出すこともできる。次の表では、これら 2 つのメソッドのパラメータについて説明する。

dwStage | guidObject | dwPChannel を使用するか | dwIndex を使用するか | iidInterface (標準)
DMUS_PATH_AUDIOPATH (*) | 無視される | いいえ | いいえ | IID_IDirectMusicAudioPath8
DMUS_PATH_AUDIOPATH_GRAPH | 無視される | いいえ | いいえ | IID_IDirectMusicGraph8
DMUS_PATH_AUDIOPATH_TOOL | ツール クラス ID または 列挙する GUID_All_Objects | はい | はい | IID_IDirectMusicTool8
DMUS_PATH_BUFFER | 無視される | はい | いいえ。dwBuffer によって識別する | IID_IDirectSoundBuffer8
DMUS_PATH_BUFFER_DMO | GUID_DSFX_STANDARD_GARGLE などの DMO クラス ID または 列挙する GUID_All_Objects | はい | はい。バッファ内の DMO のインデックス | IID_IDirectSoundFXGargle(**) など、標準 DMO インターフェイスの GUID
DMUS_PATH_MIXIN_BUFFER | 無視される | いいえ | いいえ。dwBuffer によって識別する | IID_IDirectSoundBuffer8
DMUS_PATH_MIXIN_BUFFER_DMO | GUID_DSFX_STANDARD_I3DL2REVERB などの DMO クラス ID または 列挙する GUID_All_Objects | いいえ | はい。バッファ内の DMO のインデックス | IID_IDirectSoundFXI3DL2Reverb(**) など、標準 DMO インターフェイスの GUID
DMUS_PATH_PERFORMANCE | 無視される | いいえ | いいえ | IID_IDirectMusicPerformance8
DMUS_PATH_PERFORMANCE_GRAPH | 無視される | いいえ | いいえ | IID_IDirectMusicGraph8
DMUS_PATH_PERFORMANCE_TOOL | ツール クラス ID または 列挙する GUID_All_Objects | はい | はい | IID_IDirectMusicTool8
DMUS_PATH_PORT | ポート クラス ID または 列挙する GUID_All_Objects | はい | はい | IID_IDirectMusicPort
DMUS_PATH_PRIMARY_BUFFER | 無視される | いいえ | いいえ | IID_IDirectSound3DListener8
DMUS_PATH_SEGMENT (*) | 無視される | いいえ | いいえ | IID_IDirectMusicSegment8
DMUS_PATH_SEGMENT_GRAPH (*) | 無視される | いいえ | いいえ | IID_IDirectMusicGraph8
DMUS_PATH_SEGMENT_TOOL (*) | ツール クラス ID または 列挙する GUID_All_Objects | はい | はい | IID_IDirectMusicTool8
DMUS_PATH_SEGMENT_TRACK (*) | トラック クラス ID または 列挙する GUID_All_Objects | いいえ | はい | IID_IDirectMusicTrack8

注 (*) この段階のオブジェクトは、IDirectMusicAudioPath8::GetObjectInPath によって取得できる。

(**) DirectX の DMO は、IMediaObject、IMediaObjectInPlace、および IMediaParams インターフェイスをサポートする。これらのインターフェイスの詳細については、DirectShow のマニュアルを参照すること。

標準的なバッファを取得するときの dwIndex の値の詳細については、「標準オーディオパス」を参照すること。

既にエフェクト バッファへのインターフェイスがある場合は、IDirectSoundBuffer8::GetObjectInPath を使って DMO インターフェイスを取得することもできる。

オーディオパスのすべてのバッファについて IDirectSoundBuffer8 インターフェイスを取得できるが、一部のメソッドは有効ではない。詳細については、「IDirectSoundBuffer8」を参照すること。


3D サウンド

DirectX Audio を使って、空間内のサウンドの位置を認識し、移動するサウンドにドップラー偏移を適用できる。

3D エフェクトは個々の DirectSound バッファに適用される。それぞれ独自のバッファを持つ複数のオーディオパスに異なるサウンドを指定できるので、異なるサウンドに容易に異なるパラメータを適用できる。

次のトピックでは、3D サウンドの基本的概念をいくつか紹介する。

  • 3D 空間の座標
  • 音源位置の認識

次のトピックでは、アプリケーション内での 3D サウンドの使い方についての情報を記述する。

  • DirectSound 3D バッファ
  • DirectSound 3D リスナー


3D 空間の座標

3D 空間での音源とリスナーの位置、速度、および向きは、デカルト座標の 3 本の座標軸、x 軸、y 軸、および z 軸の値で表される。これらの軸は、アプリケーションで確立された視点から相対的である。x 軸の値は左から右に、y 軸の値は下から上に、z 軸の値は手前から奥に行くほど大きくなる。

D3DVECTOR 構造体は、3 つの軸で位置、速度、または向きを記述する値を格納する。

慣習的に、ベクトルはかっこで囲まれ、カンマで区切られた (x, y, z) の順序の 3 つの値で表される。

位置の場合、これらの値はデフォルトでメートル単位である。アプリケーションが 3D グラフィックの測定単位としてメートル以外のものを使っている場合、距離係数を設定し、アプリケーションの使う距離単位が何メートルに相当するかを浮動小数点の値として表現する。たとえば、アプリケーションがフィート単位を使っている場合、距離係数として 0.3048 を指定するが、これは 1 フィートをメートル単位で表現したものである。詳細については、「距離係数」を参照すること。

速度の場合、ベクトルは、各軸に沿った移動速度を 1 秒あたりの単位で表す。この場合も、デフォルトの単位はメートルであるが、アプリケーションで変更できる。

向きの場合、値は任意の単位であり、互いに相対的である。3D 空間のベース ビューが北向きで、地面のレベルで、リスナーの向きが (1, 0, 0)、つまり、x 軸が正で、ほかの 2 つの軸が変わらない場合、リスナーは真東を向く。このベクトルが (1, 0, 1) の場合、リスナーの向きは北東になる。(-1, 0, 1) の場合、リスナーは北西を向く。ベクトルの値は絶対的な単位ではないので、最後の例は (-5, 0, 5) または (-0.25, 0, 0.25) と表すこともできる。

2D 空間でのベクトルのしくみは、グラフ用紙に描いてみるとわかりやすい。値が用紙の下から上、左から右に向かって大きくなるようにする。(0, 0) から (1, 1) に向かって描いた直線は、(0, 0) から (5, 5) に向かって描いた直線と、向き、つまり方向が同じである。ただし、2 番目の直線は距離、つまり速度が大きいことを示す。3D ベクトルの場合も、軸が増えるだけで、これと同様である。


音源位置の認識

現実の世界では、空間内の音源位置の認識は、複数の要素に影響される。これらの要素のすべてが音響的ではない。最も重要なものの 1 つに視覚がある。サウンド自体の手がかりには、次のようなものがある。

  • 全体的な音量。音源がリスナーから遠ざかると、認識される音量は一定速度で減少する。この現象はロールオフと呼ばれている。
  • 聴感上の強度の違い。リスナーの右方向で発生した音は、左耳より右耳の方で大きく聞こえる。
  • 到達のずれ。リスナーの右方向で発生した音は、左耳より少しだけ早く右耳に到達する。このずれの時間は、約 1 ミリ秒である。
  • 消音。耳が前向きについていることと、その形状のために、リスナーの後ろ方向で発生した音は、前で発生した音に比べてかすかに弱くなっている。さらに、右方向で音が発生した場合、左耳に届く音は、頭部に遮られることと左耳の向きによって弱まる。

人間が音の位置を識別するための手がかりはこれだけではないが、ここに挙げたのは主要なものである。そして DirectX Audio の位置決めシステムはこれらの要素を提供する。3D サウンド用に最適化されたハードウェアは、異なる方向から発せられる音の高さやタイミングに対する耳たぶのエフェクトなど、ほかの手がかりもサポートできる。このエフェクトの背景にある数学的理論を頭部伝達関数 (HRTF) と呼ぶ。

ほとんどの場合、DirectSound は 2 つのスピーカまたはヘッドフォンで仮想 3D エフェクトを作成する。ただし、ユーザーがコントロール パネルでサラウンド サウンド スピーカ構成を選択した場合は、WDM ドライバを使用する 4 チャンネル システムを利用することもできる。詳細については、「DSBUFFERDESC」を参照すること。


DirectSound 3D バッファ

3D 環境での各音源は IDirectSound3DBuffer8 インターフェイスによって表される。このインターフェイスをサポートするのは、DSBCAPS_CTRL3D フラグを指定して作成されたサウンド バッファだけである。このインターフェイスのメソッドを使用して、単一の音源のパラメータを設定および取得する。

DirectSound の 3D 能力を利用するときは、アプリケーションはモノラル音源を提供すべきである。DSBCAPS_CTRL3D フラグを指定してバッファを作成する場合、ウェーブ フォーマットに複数のチャンネルが含まれていると、エラーになる。

ここでは、アプリケーションが 3D バッファ オブジェクトを取得および管理する方法について説明する。以下のトピックについて説明する。

  • 3D バッファ オブジェクトの取得
  • 3D バッファのバッチ パラメータ
  • 最小距離と最大距離
  • 処理モード
  • バッファの位置座標と速度
  • サウンド コーン


3D バッファ オブジェクトの取得

IDirectSound3DBuffer8 インターフェイスは、DSBUFFERDESC 構造体の dwFlags メンバで DSBCAPS_CTRL3D フラグを指定して作成されたDirectSound セカンダリ バッファから取得される。

アプリケーションが DirectMusic のパフォーマンスおよびオーディオパスを使用している場合、DMUS_APATH_DYNAMIC_3D を dwType パラメータとして IDirectMusicPerformance8::CreateStandardAudioPath に渡すことによって、3D バッファを含むオーディオパスを作成できる。

構成オブジェクトから適切なオーディオパスを作成することもできる。オーディオパス構成によって、バッファの 3D パラメータを指定できる。オーディオパスを作成するときに、バッファの 3D プロパティはこれらのパラメータを使って初期化される。

オーディオパス内の 3D バッファへのインターフェイスを取得するには、dwStage を DMUS_PATH_BUFFER に設定して、IDirectMusicAudioPath8::GetObjectInPath または IDirectMusicSegmentState8::GetObjectInPath を呼び出す。

次のサンプル コードでは、標準オーディオパスを作成し、IDirectSound3DBuffer8 インターフェイスを取得している。

HRESULT                  hr;
IDirectMusicAudioPath8*  g_p3DAudioPath;
IDirectSound3DBuffer8*   g_pDS3DBuffer;

if (FAILED(hr = pPerformance->CreateStandardAudioPath(
        DMUS_APATH_DYNAMIC_3D, 64, TRUE, &g_p3DAudioPath)))
    return hr;

if (FAILED(hr = g_p3DAudioPath->GetObjectInPath(
        DMUS_PCHANNEL_ALL, DMUS_PATH_BUFFER, 0,
        GUID_NULL, 0, IID_IDirectSound3DBuffer8,
        (LPVOID*) &g_pDS3DBuffer)))
    return hr;

アプリケーションが独自の DirectSound セカンダリ バッファを作成および管理し、DirectMusic パフォーマンスを使用しない場合、次のサンプル コードのように、バッファについて IDirectSoundBuffer8:: QueryInterface メソッドを呼び出すことによって、IDirectSound3DBuffer8 インターフェイスを取得できる。

// lpDsbSecondary は、DSBCAPS_CTRL3D を指定して作成された
// 有効な IDirectSoundBuffer8 であると仮定する。

LPDIRECTSOUND3DBUFFER8 lpDs3dBuffer;

HRESULT hr = lpDsbSecondary->QueryInterface(IID_IDirectSound3DBuffer8,
                                            (LPVOID *)&lpDs3dBuffer);


3D バッファのバッチ パラメータ

アプリケーションは、3D サウンド パラメータの取得や設定を個別またはバッチ単位で実施できる。個別の値を設定するには、アプリケーションで適用可能な IDirectSound3DBuffer8 インターフェイス メソッドを使用できる。しかし、すべての値を一度に設定または取得する必要が生じることもよくある。その場合は、IDirectSound3DBuffer8::GetAllParameters と IDirectSound3DBuffer8::SetAllParameters の各メソッドを使う。

また、パラメータの変更は、それらに遅延のフラグを付けておき、その後すべてを一度に実行することでより効率的に行うことができる。詳細については、「遅延設定」を参照すること。


最小距離と最大距離

リスナーが音源に近づくにつれてサウンドが大きくなり、距離が半分になったときに音のボリュームは倍増する。しかし、特定の点を過ぎると、ボリュームが増加し続けるのは合理的ではない。これが音源の最小距離である。

アプリケーションが異なる音の絶対ボリューム レベルの差を補正しなければならない場合、最小距離は特に役立つ。たとえば、ジェット エンジンの音は蜂の羽音よりもずっと大きいが、実用上の理由でこれらの音を同程度の絶対ボリュームで録音しなければならない。アプリケーションはジェット エンジンの最小距離を 100 メートル、蜂の最小距離を 2 センチに設定することが考えられる。これらの設定では、リスナーが 200 メートル離れるとジェット エンジンは半分のボリュームになり、リスナーが 4 センチ離れると蜂の羽音は半分のボリュームになる。

サウンド バッファのデフォルトの最小距離 DS3D_DEFAULTMINDISTANCE は、1 単位、つまりデフォルトの距離係数では 1 メートルと定義されている。この値を変更しない限り、リスナーから 1 メートル離れた位置で音は最大になり、2 メートル離れると半分の大きさ、4 メートル離れると 1/4 の大きさになる。ほとんどのサウンドでは、最小距離をこれよりも大きく設定し、距離が大きくなってもサウンドが急速に消えないようにする。

音源の最大距離とは、それ以上離れても音がより小さくならない距離を意味する。DirectSound の 3D バッファのデフォルトの最大距離 (DS3D_DEFAULTMAXDISTANCE) は 10 億であり、音が聞こえなくなった後も引き続き減衰を計算しなければならないことを意味する。不必要な処理を避けるために、アプリケーションは適切な最大距離を設定し、バッファを作成する際に DSBCAPS_MUTE3DATMAXDISTANCE フラグを含めるべきである。このフラグは、オーディオパスの一部として作成された標準的な 3D バッファについては自動的に設定される。「標準オーディオパス」を参照すること。

サウンドが聞こえなくなることを防止する目的でも、最大距離を利用できる。たとえば、あるサウンドの最小距離を 100 メートルに設定し、1,000 メートル以上離れるとそのサウンドが事実上聞こえなくなると仮定する。ここで最大距離を 800 メートルに設定すると、距離にかかわりなく、そのサウンドは最大ボリュームの少なくとも 1/8 で聞こえることが保証される。もちろん、この場合は DSBCAPS_MUTE3DATMAXDISTANCE フラグを設定しない。

次の図は、距離が大きくなるにつれて、最小距離と最大距離がジェット エンジンの音と蜂の羽音の大きさにどのように影響するかを示している。

アプリケーションで最小距離値を設定および取得するには、IDirectSound3DBuffer8::SetMinDistance と IDirectSound3DBuffer8::GetMinDistance の各メソッドを使う。同様に、最大距離値を設定および取得するには IDirectSound3DBuffer8::SetMaxDistance と IDirectSound3DBuffer8::GetMaxDistance の各メソッドを使う。

デフォルトでは、距離値はメートル単位で表される。「距離係数」を参照すること。

すべてのサウンド バッファで、距離がボリュームに及ぼすエフェクトを調整するには、ロールオフ係数を変更する。


処理モード

サウンド バッファには 3 つの処理モードがある。標準、頭相対 (リスナー相対)、および無効の各モードである。

標準モードでは、音源はワールド空間内の絶対位置と絶対方向に基づいて処理される。これはデフォルトのモードである。

頭相対 (リスナー相対) モードでは、リスナーの移動と回転に応じて、バッファはワールド空間内で自動的に位置調整される。IDirectSound3DBuffer8::SetPosition、IDirectSound3DBuffer8::SetVelocity、IDirectSound3DBuffer8::GetConeOrientation などのメソッドで値の設定と取得が行えるが、これらはいずれもリスナーの現在の位置、速度、向きに対する相対的なものである。

無効モードでは 3D サウンド処理は無効になり、サウンドはリスナーの頭の中心で発生しているように聞こえる。

アプリケーションは IDirectSound3DBuffer8::SetMode メソッドを使って 3D サウンド バッファのモードを設定する。


バッファの位置座標と速度

3D サウンドには位置と速度がある。これらの値の指定は、すべてアプリケーションで行う。

位置は処理モードに基づき、ワールド空間かリスナーのどちらかを基準とした相対的なベクトルとして表される。

速度は秒あたりの距離単位で測定される。デフォルトではメートル/秒である。速度はドップラー偏移のエフェクトを計算するためにのみ使用され、音源の実際の移動側に対応している必要はない。

アプリケーションは、IDirectSound3DBuffer8::SetPosition と IDirectSound3DBuffer8::GetPosition の各メソッドを使って、3D 空間での音源の位置を設定および取得できる。

速度を設定または取得するには、IDirectSound3DBuffer8::SetVelocity と IDirectSound3DBuffer8::GetVelocity の各メソッドを使用する。


サウンド コーン

向きを持たないサウンドは、どの向きでも、距離に応じて大きさが決まる。向きのあるサウンドは、その向きに向かったときに最も大きくなる。方向のあるサウンドの大きさを表すモデルを、サウンド コーンと呼ぶ。サウンド コーンは、内部コーンと外部コーンで形成される。

内部コーン内の角度では、サウンドのボリュームは、バッファの基本的なボリューム、リスナーからの距離、リスナーの向きなどを考慮しても、コーンがない場合と同じになる。

外部コーンの外側の角度では、アプリケーションによって設定された係数によって通常のボリュームが減衰される。外部コーンのボリュームは、1/100 dB 単位の負の数で表される。デフォルトのボリュームを 0 とし、このボリュームはそこからの減衰を表すからである。

内部コーンと外部コーンの間の角度は、内部ボリュームから外部ボリュームへのトランジションである。角度が増加するにつれて、ボリュームは小さくなる。

次の図は、サウンド コーンの概念を示している。

すべての 3D サウンド バッファはサウンド コーンである。しかし、外部ボリュームは減衰せず、内部コーンと外部コーンの角度はどちらも 360 度なので、デフォルトではバッファは全方向の音源として動作する。アプリケーションがこれらの値を変更しない限り、サウンドには見かけの向きはない。

サウンド コーンを適切に設計すると、アプリケーションに劇的なエフェクトが追加される。たとえば音源を部屋の中央に置き、音源の方向を、廊下に面して開いたドアの向きに設定する。次にそのドアの幅に合わせて内部コーンの角度を設定する。外部コーンをそれより少しだけ広く設定し、外部コーンのボリュームを聴取不可能に設定する。リスナーが廊下を歩き、ドアの近くまで来るとサウンドが聞こえ始める。そして開いているドアの正面に来るとサウンドは最大になる。

アプリケーションは、IDirectSound3DBuffer8::SetConeAngles と IDirectSound3DBuffer8::GetConeAngles の各メソッドを使って、サウンド コーンを定義する角度を設定および取得する。外部コーンの角度は、常に内部コーンの角度以上でなければならない。

アプリケーションは、IDirectSound3DBuffer8::SetConeOrientation と IDirectSound3DBuffer8::GetConeOrientation の各メソッドを使って、サウンド コーンの向きを設定および取得する。

アプリケーションは、IDirectSound3DBuffer8::SetConeOutsideVolume と IDirectSound3DBuffer8::GetConeOutsideVolume の各メソッドを使って、外部コーンのボリュームを設定および取得する。


DirectSound 3D リスナー

仮想 3D 環境では、実世界と同様に、サウンドは受信ポイントとの関係でのみ存在する。DirectX Audio アプリケーションの 3D サウンド エフェクトは、サウンド バッファの位置と向きと速度だけではなく、仮想リスナーの位置と向きと速度の影響を受ける。

デフォルトでは、リスナーはすべてのベクトルが 0 の位置に静止し、Z 軸の正の方向を向き、頭を Y 軸の正の方向にしている。リスナーを表すオブジェクトを取得することによって、アプリケーションはこれらのすべての値を変更して仮想空間でのユーザーの動きと向きを反映できる。リスナー オブジェクトは、ドップラー効果の量や距離に応じたボリュームの減衰など、聴感環境の一般的なパラメータもコントロールする。

ここでは、アプリケーションがリスナーを取得し、グローバル 3D サウンド パラメータを管理する方法について説明する。説明するトピックは、次のとおりである。

  • 3D リスナーの取得
  • 3D リスナーのバッチ パラメータ
  • 遅延設定
  • 距離係数
  • リスナーの向き
  • リスナーの位置座標と速度
  • ドップラー係数
  • ロールオフ係数


3D リスナーの取得

グローバル サウンド パラメータは、IDirectSound3DListener8 インターフェイスを使って設定および取得される。このインターフェイスは、プライマリ サウンド バッファへのインターフェイスである。アプリケーションのプライマリ バッファは 1 つだけで、リスナーも 1 人だけである。

DirectMusic のパフォーマンスとオーディオパスを使って 3D サウンドを再生する場合は、IDirectMusicAudioPath8::GetObjectInPath または IDirectMusicSegmentState8::GetObjectInPath を使い、dwStage パラメータを DMUS_PATH_PRIMARY_BUFFER に設定して、オーディオパスからリスナーを取得できる。次の例では、g_p3DAudioPath は IDirectMusicAudioPath8 インターフェイスへのポインタである。

IDirectSound3DListener8* g_pDSListener;

HRESULT hr = g_p3DAudioPath->GetObjectInPath(
    DMUS_PCHANNEL_ALL, DMUS_PATH_PRIMARY_BUFFER, 0,
    GUID_NULL, 0, IID_IDirectSound3DListener8,
    (LPVOID*) &g_pDSListener));

アプリケーションが、DirectSound API を使って、独自のサウンド バッファを作成および管理する場合は、プライマリ バッファ オブジェクトを作成し、このオブジェクトからリスナー インターフェイスを取得する必要がある。

プライマリ バッファを作成するには、IDirectSound8::CreateSoundBuffer メソッドを使い、DSBUFFERDESC 構造体の dwFlags メンバで DSBCAPS_CTRL3D と DSBCAPS_PRIMARYBUFFER の各フラグを指定する。作成されたバッファに対して IDirectSoundBuffer:: QueryInterface メソッドを呼び出し、そのバッファの IDirectSound3DListener8 インターフェイスへのポインタを取得する。

次の例では、lpds は IDirectSound8 インターフェイス ポインタである。

DSBUFFERDESC           dsbd;
LPDIRECTSOUNDBUFFER    lpdsbPrimary;
LPDIRECTSOUNDLISTENER8 lp3DListener;

ZeroMemory(&dsbd, sizeof(DSBUFFERDESC));
dsbd.dwSize = sizeof(DSBUFFERDESC);
dsbd.dwFlags = DSBCAPS_CTRL3D | DSBCAPS_PRIMARYBUFFER;
if SUCCEEDED(lpds->CreateSoundBuffer(&dsbd, &lpdsbPrimary, NULL))
{
    // リスナー インターフェイスを取得する。
    if FAILED(lpdsbPrimary->QueryInterface(
            IID_IDirectSound3DListener8,
            (LPVOID *)&lp3DListener))
    {
    lpdsbPrimary->Release();
    }
}

リスナーが取得されたら、プライマリ バッファへの IDirectSoundBuffer インターフェイスは不要になり、解放できる。


3D リスナーのバッチ パラメータ

アプリケーションは、3D リスナー オブジェクト パラメータの取得や設定を個別またはバッチ単位で実施できる。個別の値を設定するには、アプリケーションで適用可能な IDirectSound3DListener8 インターフェイス メソッドを使用できる。しかし、リスナーを表現するすべての値を一度に設定または取得する必要が生じることもよくある。その場合は、IDirectSound3DListener8::GetAllParameters と IDirectSound3DListener8::SetAllParameters の各メソッドを使うと、バッチ パラメータ操作を 1 回の呼び出しで実行できる。

また、パラメータの変更は、それらに遅延のフラグを付けておき、その後すべてを一度に実行することでより効率的に行うことができる。詳細については、「遅延設定」を参照すること。


遅延設定

3D サウンド バッファとリスナーの設定を変更するたびに、再ミキシングが行われ、CPU サイクルを消費する。3D 設定の変更による処理性能への影響を最小限に抑えるには、3D 設定を変更する IDirectSound3DListener8 と IDirectSound3DBuffer8 のいずれかのメソッドの dwApply パラメータで DS3D_DEFERRED フラグを指定する。その後 IDirectSound3DListener8::CommitDeferredSettings メソッドを呼び出し、遅延されていたすべてのコマンドを 1 回で実行する。

注 遅延設定は即時設定によってオーバーライドされる。たとえば、DS3D_DEFERRED フラグを指定してリスナー速度を (1.0, 0.0, 0.0) に設定した後、DS3D_IMMEDIATE フラグを指定してリスナー速度を (2.0, 0.0, 0.0) に設定すると、速度は (2.0, 0.0, 0.0) になり、CommitDeferredSettings を呼び出しても変更されない。


距離係数

距離係数は、ベクトルの単位となるメートル数である。デフォルトの距離係数は 1.0 である。バッファの速度が (2.0, 0.0, 0.0) である場合、音源は X 軸に沿って、2 メートル/秒で移動すると見なされる。アプリケーションが 3D グラフィック ベクトルの測定単位としてメートル以外の単位を使っている場合は、その単位に応じて距離係数も変更できる。

たとえば、現在のアプリケーションが測定の基本単位としてフィート (0.3048 メートル) を使っているとする。この場合は、IDirectSound3DListener8::SetDistanceFactor メソッドを呼び出して、flDistanceFactor パラメータとして 0.3048 を指定する。それ以降、メソッドを呼び出す際にパラメータをフィート単位で指定すると、それらの値はメートル単位に自動的に換算される。

IDirectSound3DListener8::GetDistanceFactor メソッドを使うと、リスナーに対して設定されている現在の距離係数を取得できる。

距離係数は、1 秒あたり n 単位で表される実際の速度を変更することにより、主にドップラー効果に影響を及ぼす。ロールオフに直接的な影響を及ぼすことはない。距離に応じた減衰率は、この単位を使った最小距離に基づいているからである。あるサウンドの最小距離を 2 単位に設定した場合、4 単位離れるとボリュームは半分になる。距離がフィートやメートルやほかの単位であっても、これは共通である。詳細については、「最小距離と最大距離」を参照すること。


リスナーの向き

リスナーの向きは、リスナーの頭の中心を原点とする 2 つのベクトル、上方ベクトルと前方ベクトルの関係によって定義される。上方ベクトルは頭頂部を通る上向きの直線で、前方ベクトルは上方ベクトルと直角をなしてリスナーの顔を通る直線である。次の図はこれらの関係を示している。

アプリケーションは IDirectSound3DListener8::SetOrientation と IDirectSound3DListener8::GetOrientation の各メソッドを使って、リスナーの向きを設定および取得できる。

デフォルトでは、前方ベクトルが (0.0, 0.0, 1.0)、上方ベクトルが (0.0, 1.0, 0.0) である。これら 2 つのベクトルは、常に互いに対して直角でなければならない。必要に応じて、DirectSound は前方ベクトルに調整を加え、上方ベクトルに対して直角の関係を保つ。


リスナーの位置座標と速度

アプリケーションは IDirectSound3DListener8::SetPosition と IDirectSound3DListener8::GetPosition の各メソッドを使って、3D 空間におけるリスナーの位置を設定および取得できる。

DirectSound が移動するリスナーに対するドップラー効果を計算する際に使う速度値を設定または取得するには、IDirectSound3DListener8::SetVelocity と IDirectSound3DListener8::GetVelocity の各メソッドを使う。速度は秒あたりの距離単位で測定される。デフォルトではメートル/秒である。

バッファと同様、リスナーの位置と速度とは完全に独立している。リスナーの適切な速度を設定する作業は、アプリケーションに依存している。


ドップラー係数

DirectSound は、速度を持つバッファやリスナーに対して、自動的にドップラー効果を作成する。このエフェクトは累積する。リスナーとサウンド バッファの両方が移動している場合、システムは相対速度を自動的に計算し、それに従ってドップラー効果を調整する。

現実的なドップラー効果をアプリケーションに追加するには、移動しているあらゆるオブジェクトの速度を計算し、その音源またはリスナーの適切な速度を設定しなければならない。特定の状況では特殊効果をもたらすために、この値を自由に拡張または減少させてよい。ドップラー係数を変更すると、ドップラー偏移を全体的に増加または減少させられる。

ドップラー係数は、DS3D_MINDOPPLERFACTOR から DS3D_MAXDOPPLERFACTOR の範囲で変更できるが、これらはそれぞれ 0.0 と 10.0 に設定されている。値 0 は、サウンドにドップラー偏移を適用しないことを意味する。ほかの値は、実世界のドップラー偏移に対する乗数を表す。言い換えれば、値 1 (または DS3D_DEFAULTDOPPLERFACTOR) は実世界で体験するドップラー偏移をサウンドに適用すること、値 2 は実世界のドップラー偏移の 2 倍を意味する。以下同様である。

IDirectSound3DListener8::SetDopplerFactor と IDirectSound3DListener8::GetDopplerFactor の各メソッドを使うと、ドップラー係数を設定および取得できる。


ロールオフ係数

ロールオフとは、リスナーとサウンドの距離によって生じる音の減衰の度合である。DirectSound はロールオフ係数と呼ぶ変数により、ロールオフの無視、誇張、実世界と同じエフェクトの再現ができる。

ロールオフ係数は、DS3D_MINROLLOFFFACTOR から DS3D_MAXROLLOFFFACTOR の範囲で変更できるが、これらはそれぞれ 0.0 と 10.0 に設定されている。値 DS3D_MINROLLOFFFACTOR は、サウンドにロールオフを適用しないことを意味する。ほかの値は、実世界のロールオフに対する乗数を表す。言い換えれば、値 1 (DS3D_DEFAULTROLLOFFFACTOR) は実世界で体験するロールオフをサウンドに適用すること、値 2 は実世界のロールオフの 2 倍を意味する。以下同様である。

IDirectSound3DListener8::SetRolloffFactor と IDirectSound3DListener8::GetRolloffFactor の各メソッドを使うと、ロールオフ係数を設定および取得できる。

個別のサウンド バッファの距離によるエフェクトを変更するために、そのバッファの最小距離を設定できる。詳細については、「最小距離と最大距離」を参照すること。


エフェクトの使い方

DirectX Audio は、DMO (DirectX Media Object) によるサウンドのエフェクト処理をサポートしている。DMO の概要については、DirectShow のマニュアルの「DirectX Media Object の概要」を参照すること。

すべての DirectX アプリケーションで、標準エフェクトのセットを使用できる。その他の DMO はシステムに登録される。

ウェーブ リバーブ以外のすべての標準的な DMO は、DirectSound がサポートしている任意のサンプル レートで、1 つまたは 2 つのチャンネルを使用して、8 ビットまたは 16 ビットの PCM ウェーブ フォーマットのデータを処理できる。ウェーブ リバーブは 8 ビットのサンプルをサポートしていない。

次のトピックでは、エフェクトの設定と使い方について説明する。

  • バッファでのエフェクトの設定
  • エフェクト パラメータ
  • 標準エフェクト

ここでは、オーディオパスにおけるエフェクトの使い方を中心に説明するが、多くの情報は、独自の DirectSound バッファを管理するアプリケーションにも対応する。「DirectSound でのエフェクトの使い方」を参照すること。


バッファでのエフェクトの設定

DirectMusic Producer で作成したセグメントを、オーディオパス構成を使って演奏している場合、エフェクトは構成オブジェクトからオーディオパスを作成したときに設定される。標準オーディオパスにはエフェクトも保持される。ただし、実行時にカスタム オーディオパスでエフェクトを実装したり、標準オーディオパスにエフェクトを追加したい場合がある。たとえば、ウェーブまたは MIDI ファイルにエフェクトを適用できるように、標準オーディオパスにエフェクトを追加したい場合がある。

オーディオパスにエフェクトを適用するには、まずパス上のバッファへの IDirectSoundBuffer8 インターフェイスを取得する。次に、IDirectSoundBuffer8::SetFX を使って、そのバッファに 1 つまたは複数のエフェクトを設定する。

バッファ インターフェイスを取得する方法については、「オーディオパスからのオブジェクトの取得」を参照すること。GetObjectInPath の呼び出しで標準オーディオパス バッファを識別する方法については、「標準オーディオパス」のオーディオパスのタイプを参照すること。

次のサンプルコードでは、標準オーディオパスを設定し、パスからバッファを取得し、バッファ上でエコー エフェクトを設定している。

// pPerformance が有効な IDirectMusicPerformance8
// インターフェイス ポインタであると仮定する。

IDirectMusicAudioPath*  g_p3DAudioPath;
IDirectSoundBuffer8*    g_pDSBuffer;
HRESULT                 hr;

// 音源および環境リバーブ バッファを使って、
// 標準オーディオパスを作成する。パスはアクティブにしない。
// バッファが実行中の場合、SetFX は失敗する。

if( FAILED(hr = pPerformance->CreateStandardAudioPath(
    DMUS_APATH_DYNAMIC_3D, 64, FALSE, &g_p3DAudioPath)))
    return hr;

// オーディオパスのバッファを取得する。

if( FAILED(hr = g_p3DAudioPath->GetObjectInPath(DMUS_PCHANNEL_ALL,
    DMUS_PATH_BUFFER, 0, GUID_NULL, 0, IID_IDirectSoundBuffer8,
    (LPVOID*) &g_pDSBuffer)))
    return hr;

// エフェクトを記述する。

DSEFFECTDESC dsEffect;
dsEffect.dwSize = sizeof(DSEFFECTDESC);
dsEffect.dwFlags = 0;
dsEffect.guidDSFXClass = GUID_DSFX_STANDARD_ECHO;
dsEffect.dwReserved1 = 0;
dsEffect.dwReserved2 = 0;

DWORD dwResults;

// エフェクトを設定する
if (FAILED(hr = g_pDSBuffer->SetFX(1, &dsEffect, &dwResults)))
    return hr;

// ここで dwResults の値をチェックし、エフェクトが
// どのように割り当てられているかを確認できる。

// パスをアクティブにする。

g_p3DAudioPath->Activate(TRUE);


エフェクト パラメータ

サウンド エフェクトのパラメータを設定または取得するには、まず、そのエフェクトを含むバッファの適切なインターフェイスを取得する必要がある。次のインターフェイスを使って、DirectX Audio で提供される DMO のパラメータにアクセスできる。

  • IDirectSoundFXChorus8
  • IDirectSoundFXCompressor8
  • IDirectSoundFXDistortion8
  • IDirectSoundFXEcho8
  • IDirectSoundFXFlanger8
  • IDirectSoundFXGargle8
  • IDirectSoundFXI3DL2Reverb8
  • IDirectSoundFXParamEq8
  • IDirectSoundFXWavesReverb8

エフェクトのインターフェイスを取得するには、DMUS_PATH_BUFFER_DMO を dwStage パラメータとして IDirectMusicAudioPath8::GetObjectInPath または IDirectMusicSegmentState8::GetObjectInPath に渡す。オーディオパスに複数のバッファが含まれる場合、dwBuffer はバッファのインデックスでなければならない。標準オーディオパスのバッファのインデックス番号については、「標準オーディオパス」のオーディオパスのタイプを参照すること。

次のサンプル コードは、オーディオパス構成から作成されたバッファのガーグル エフェクトのインターフェイスを取得する。次に、このインターフェイスを使って、エフェクトのパラメータを変更している。

// g_p3DAudioPath は有効な IDirectMusicAudioPath8 ポインタであり、
// IDirectMusicPerformance8::CreateAudioPath から取得される。
// 例をわかりやすくするために、エラー処理は省略している。

HRESULT                  hr;
IDirectSoundFXGargle8*   pEffectDMO;
DSFXGargle               FXParams;

hr = g_p3DAudioPath->GetObjectInPath(DMUS_PCHANNEL_ALL,
        DMUS_PATH_BUFFER_DMO, 0,
        GUID_All_Objects, 0, IID_IDirectSoundFXGargle8,
        (LPVOID*) &pEffectDMO);

hr = pEffectDMO->GetAllParameters(&FXParams);
FXParams.dwRateHz  = DSFXGARGLE_RATEHZ_MIN;
hr = pEffectDMO->SetAllParameters(&FXParams);

アプリケーションが独自の DirectSound バッファを管理する場合、エフェクト パラメータの変更をすぐに実行する必要がある。効率を高めるため、DirectSound は、IDirectSoundBuffer8::Play を呼び出す前に、再生カーソルの位置から開始して 100 ミリ秒のサウンド データを処理する。この処理は、以下のいずれかの呼び出しが実行された後に行うことができる。

  • IDirectSoundBuffer8::Unlock
  • IDirectSoundBuffer8::Stop
  • IDirectSoundBuffer8::SetCurrentPosition
  • IDirectSoundBuffer8::SetFX

これらのメソッドのいずれかを呼び出した後でエフェクト パラメータを変更した場合、処理済みのデータが再生されるまで、新しいパラメータは聞こえない。これを回避するには、以下のいずれかを実行する。

  • バッファへのデータの書き込みを、パラメータの変更前ではなく変更後に行う。
  • バッファで Stop または SetCurrentPosition を呼び出し、データの処理を強制的にパラメータ設定後にする。


標準エフェクト

ここでは、DirectX Audio のサウンド エフェクトを紹介する。次のエフェクトについて説明する。

  • コーラス
  • コンプレッション
  • ディストーション
  • エコー
  • 環境リバーブ
  • フランジ
  • ガーグル
  • パラメトリック イコライザ
  • ウェーブ リバーブ


コーラス

コーラスは、元のサウンドに若干の遅延を付加してエコーをかけ、エコーの遅延を若干変調して作成される音声二重化エフェクトである。

このエフェクトは、IDirectSoundFXChorus8 インターフェイスによって表される。そのパラメータは、DSFXChorus 構造体に格納される。


コンプレッション

コンプレッションとは、特定の振幅を超えるシグナルの変動を削減することである。

このエフェクトは、IDirectSoundFXCompressor8 インターフェイスによって表される。そのパラメータは、DSFXCompressor 構造体に格納される。


ディストーション

ディストーションを実行するには、信号に和音を追加する。これによって、レベルが上がったときにウェーブフォームの最上部が四角形になるか、切り取られる。

このエフェクトは、IDirectSoundFXDistortion8 インターフェイスによって表される。そのパラメータは、DSFXDistortion 構造体に格納される。


エコー

エコー エフェクトによって、サウンド全体が固定遅延の後、繰り返される。

このエフェクトは、IDirectSoundFXEcho8 インターフェイスによって表される。そのパラメータは、DSFXEcho 構造体に格納される。


環境リバーブ

DirectX では、Interactive Audio Special Interest Group によって発行された Interactive 3-D Audio, Level 2 (I3DL2) 仕様に基づく環境リバーブをサポートしている。

DirectX 環境リバーブ エフェクトは、I3DL2 仕様のリスナー プロパティの実装である。このリリースでは、音源プロパティはサポートされていない。

リスナーに届くサウンドは、3 つの一時的なコンポーネントを持つ。

  • 直接パスは、どのサーフェスにも反射せず、音源からリスナーにまっすぐに進むオーディオ シグナルである。したがって、直接パス シグナルは 1 つしかない。
  • 初期反射音は、壁、床、天井などのサーフェスに 1、2 回反射した後、リスナーに届くオーディオ シグナルである。シグナルが、リスナーに届くまでに 1 回だけ壁に当たった音である場合、このシグナルは 1 次反射音と呼ばれる。リスナーに届くまでに壁に 2 回反射した音は、2 次反射音と呼ばれる。人間が通常個別に感知できるのは、1 次反射音または 2 次反射音だけである。
  • 後期リバーブ、または単なるリバーブは、低次反射音の組み合わせ、通常、強さが減少していく連続するエコーの重なりで構成される。

初期反射音と後期リバーブの組み合わせは、室内エフェクトと呼ばれることもある。

リバーブ プロパティには次のものがある。

  • 初期反射音および後期リバーブの減衰。
  • ロールオフ係数、つまり反射したシグナルが距離に応じて減衰する割合。直接パスのロールオフ係数は、DirectSound リスナーによって管理される。
  • 反射音の遅延。これは、直接パスのシグナルの到達と、最初の初期反射音の到達との時間差である。
  • リバーブの遅延。これは、最初の初期反射音と、後期リバーブの到達との時間差である。
  • ディケイ時間。これは、後期リバーブの到達と、その強さが 60 dB 減少する時間との時間間隔である。
  • 拡散。後期リバーブの 1 秒あたりのエコー数に比例する。実装によって、リバーブ ディケイに従って密度は変化する。DirectX では、実装による許容範囲のパーセンテージを設定することによって、アプリケーションでこのプロパティを制御できる。
  • 密度。後期リバーブの 1 Hz あたりの共振数に比例する。密度が低いほど、狭い室内の音のように、うつろな音になる。DirectX では、実装による許容範囲のパーセンテージを設定することによって、アプリケーションでこのプロパティを制御できる。

リバーブ プロパティは IDirectSoundFXI3DL2Reverb8 インターフェイスによって表され、環境のパラメータは DSFXI3DL2REVERB 構造体に含まれている。

DirectX では、山から下水管まで、さまざまなオーディオ環境のリバーブ プロパティを記述する数多くのデフォルトのパラメータ、つまりプリセット値をサポートしている。ほとんどのアプリケーションでは、IDirectSoundFXI3DL2Reverb8::SetPreset を使って、これらの環境のいずれかを簡単に選択できる。

カスタム プロパティを設定するには、IDirectSoundFXI3DL2Reverb8::SetAllParameters を使用する。IDirectSoundFXI3DL2Reverb8::GetAllParameters を使って、現在のプロパティを取得できる。


フランジ

フランジは、元のシグナルとそのエコーとの間の遅延が非常に短く、時間によって変化するエコー エフェクトである。この結果は、スイーピング サウンドと呼ばれることもある。フランジという用語は、テープ リールの縁 (flange) をつかんで回転速度を変化させていたことに由来する。

このエフェクトは、IDirectSoundFXFlanger8 インターフェイスによって表される。そのパラメータは、DSFXFlanger 構造体に格納される。


ガーグル

ガーグル エフェクトは、信号の振幅を乗算する。

このエフェクトは、IDirectSoundFXGargle8 インターフェイスによって表される。そのパラメータは、DSFXGargle 構造体に格納される。


パラメトリック イコライザ

パラメトリック イコライザは、指定された周波数のシグナルを増幅または減衰させる。

同じバッファに GUID_DSFX_STANDARD_PARAMEQ の複数のインスタンスをを設定することによって、複数のピッチのパラメトリック イコライザ エフェクトを並行して適用できる。これによって、アプリケーションでハードウェア イコライザと同様のトーン コントロールを実現できる。

このエフェクトは、IDirectSoundFXParamEq8 インターフェイスによって表される。そのパラメータは、DSFXParamEq 構造体に格納される。


ウェーブ リバーブ

ウェーブ リバーブは音楽用のエフェクトである。ウェーブ リバーブ DMO は、Microsoft にライセンスされている Waves MaxxVerb テクノロジに基づいている。

このエフェクトは、IDirectSoundFXWavesReverb8 インターフェイスによって表される。そのパラメータは、DSFXWavesReverb 構造体に格納される。


バッファ チェーン

サウンドは、必ずしも 1 つのセカンダリ サウンド バッファだけを経由しなくてもよい。オーディオパスのバッファは、ほかのセカンダリ バッファにデータを送ることができる。この処理の利点は、複数のバッファからのサウンドを共有バッファに転送し、そこで共通の 3D パラメータや特殊効果を適用できることである。バッファを共有すると、より効率が高まる。

DirectMusic Producer ファイルに埋め込まれたオーディオパス構成からオーディオパスが作成されたときは、バッファ チェーンが自動的に設定される。詳細については、「オーディオパスの使い方」を参照すること。

DirectX 8.0 は、DirectSound API によるバッファ チェーンの作成をサポートしていない。


アレンジ要素の使い方

ここで説明する内容は、動的なミュージック コンポーネントを DirectX Audio アプリケーションに組み込むためのガイドである。ここでは、コードマップやスタイルなどの要素の基本事項を理解していることを前提としている。これらについて不明な点は、「アレンジ用のミュージック要素」を参照すること。

個々のアレンジ要素を使わずに、DirectMusic Producer のファイルをアプリケーションに組み込むことも可能である。多くのアプリケーションでは、完全に作成されたセグメントのみが使用されている。しかし、個別のコンポーネントを使用することによって、実行時のパフォーマンスをさらに制御することができる。

説明するトピックは、次のとおりである。

  • アレンジ用のミュージック ファイル
  • アレンジ用のプログラミング概要
  • スタイルの使い方
  • モチーフの使い方
  • コードマップの使い方
  • テンプレートの使い方
  • トランジションの使い方


アレンジ用のミュージック ファイル

DirectMusic コンポジションをプログラミングするときは、DirectMusic Producer または同様のアプリケーションで作成されたさまざまなファイルを使用する。これらの要素を COM オブジェクトとしてアプリケーションにロードし、それらのオブジェクトへのインターフェイスを取得する「オーディオ データのロード」を参照すること。

次の表は、開発者が扱うファイル オブジェクトのタイプを示している。これらのオブジェクトはいずれも、コンテナ ファイルまたはリソースからも取得できる。

クラス GUID は、オブジェクトをロードする際に DMUS_OBJECTDESC 構造体の guidClass メンバに書き込む値である。

要素 | クラス GUID | インターフェイス | ファイル タイプ
バンド | CLSID_DirectMusicBand | IDirectMusicBand8 | bnd
コードマップ | CLSID_DirectMusicChordMap | IDirectMusicChordMap8 | cdm
DLS コレクション | CLSID_DirectMusicCollection | IDirectMusicCollection8 | dls
セグメント | CLSID_DirectMusicSegment8 | IDirectMusicSegment8 | sgt
スタイル | CLSID_DirectMusicStyle | IDirectMusicStyle8 | sty

注 バンドはスタイルの一部としてオーサリングできるが、その場合、スタイルをロードするときにそれらも自動的にロードされる。同様に、スタイルとバンドはセグメントにオーサリングできる。この場合、これらの要素を別のファイルに分ける必要ない。

ファイルには、ほかのファイルへの参照を含めることができる。スタイルにバンド ファイルへの参照が含まれている場合、ローダーがバンド ファイルを見つけることができれば、スタイルがロードされるときに自動的にバンドもロードされる。


アレンジ用のプログラミング概要

実行時にアレンジされる音楽を実装するときに、既にオーサリングされているオブジェクトをビルディング ブロックとして使用する。オーサーやほかのコンテント プロバイダと相談しながら、小さなビルディング ブロックとして取得するミュージック データを選択することにより、実行時に最も高い柔軟性やバリエーションを実現したり、音楽をより完成された形で定義するために、あらかじめ作成された要素をより多く利用できる。

最大のビルディング ブロックを使って、サウンドの再生についてパフォーマンスが指示しなければならない情報のすべてが含まれている、スタイル、MIDI ファイル、またはウェーブに基づく、高度に構造化されたセグメントをロードする。必要なのは、セクションをロードして、IDirectMusicSegment8 インターフェイスの照会を行うことだけである。このインターフェイス ポインタを IDirectMusicPerformance8::PlaySegment または IDirectMusicPerformance8::PlaySegmentEx メソッドに渡す。スタイル再生エンジンは、スタイルからパターン バリエーションを選択し、固定コード進行に従ってこれらを演奏する。また、MIDI ベースのセグメントの場合は、MIDI シーケンスを演奏する。バンド チェンジは、通常、セグメントに含まれる。

より小さなビルディング ブロックを使う場合は、次の要素を取得する。

  • コードマップ。コード進行のロード マップを表す。
  • スタイル。基本的なメロディやリズムと共に、バリエーション、モチーフ、および装飾を定義する。
  • テンプレート セグメント。構造的な計画であり、セグメントの長さ、ループの有無、グルーブ レベルの変更や装飾を配置する場所、コードマップでサインポストの役割を果たすコードのタイプを含め、再生のさまざまな側面を制御する。

IDirectMusicComposer8::ComposeSegmentFromTemplate メソッドを使って、コードマップ、スタイル、およびテンプレートを組み合わせ、セグメントを構築する。

実行時の音楽アレンジをより柔軟に行うには、IDirectMusicComposer8::ComposeSegmentFromShape メソッドを使って、テンプレートではなく定義済みのシェイプに基づくセグメントを作成する。シェイプは、コマンドおよびサインポスト トラックの作成に使用され、装飾パターン、コード進行、およびコード変更の頻度の選択を制御する。

セグメントを演奏するときに、パートの演奏に使用するバンドを制御することもできる。バンドは通常、スタイルおよびテンプレートにオーサリングされるが、個別のファイルとして提供することもできる。バンドを動的に変更するには、IDirectMusicBand8::CreateSegment メソッドを使って、バンドだけから成るセカンダリ セグメントを作成し、音色や音色の設定をプライマリ セグメントに割り当てるときに、このセカンダリ セグメントを演奏する。詳細については、「バンドの使い方」を参照すること。


スタイルの使い方

DirectMusic スタイル オブジェクトは、音楽パターンの集まりを表す。通常は、装飾とモチーフ、拍子記号、テンポ、およびバンドが含まれる。基本的なリズムと、各音色パートで演奏されるノートが定義される。

概念については、「スタイル」を参照すること。

スタイル単独では、実行時にミュージック セグメントを作成するのに十分な情報を備えていない。このため、スタイルのほかに 2 つのコンポーネントが必要となる。コードマップ (コード進行のマップ) と、演奏時にグルーブ レベルと装飾を設定するコマンド トラックである。コマンド トラックはテンプレートから取り出すか、実行時にシェイプから生成する。コードマップは、通常はコードマップ ファイルかリソースから取得する。

テンプレートに基づき、コマンド トラックを使ってセグメントを作成するには、IDirectMusicComposer8::ComposeSegmentFromTemplate メソッドを呼び出す。「テンプレートの使い方」を参照すること。

シェイプに基づいてセグメントを作成するには、IDirectMusicComposer8::ComposeSegmentFromShape メソッドを呼び出す。スタイルとコードマップへのポインタを指定する。また、コード変更の頻度を制御する和音進行のレート、およびグルーブ レベルと装飾の進行を決定するシェイプ定数も指定する。


モチーフの使い方

モチーフとは、通常はインタラクティブ イベントに応じて演奏されるもので、基本的なスタイル パターン上で演奏されることを意図した、スタイル内の特種なパターンである。モチーフには、ほかのパターンと同様の複雑さを与えることができる。また、バリエーションや複数の音色パートを備えることも可能であるが、通常はさまざまなバックグラウンド パターンと組み合わせても適切に聞こえる、短い単純な音型である。カスタム DLS 音色で演奏するサウンド エフェクトにもなる。

どのモチーフもスタイルの一部としてオーサリングされるので、スタイルをロードするとすぐにモチーフを利用できる。特定のモチーフを再生できるようにするには、IDirectMusicStyle8::GetMotif メソッドを呼び出し、次のパラメータを渡す。

  • モチーフ名。この情報はスタイルのドキュメントで確認するか、IDirectMusicStyle8::EnumMotif メソッドを使ってインデックス値から取得する。
  • メソッドが作成するセグメント オブジェクトへの IDirectMusicSegment8 インターフェイスを受け取るポインタ。

次のサンプル コードでは、pwszMotifName で名前を指定されたモチーフを取得し、演奏する。

void PlayMotif(IDirectMusicPerformance8* pPerf,
         IDirectMusicStyle8* pStyle,
         WCHAR* pwszMotifName)
{
  IDirectMusicSegment* pSeg;

  // スタイルからモチーフ セグメントを取得する。GetMotif() は、
  // モチーフを見つけられなかった場合は S_FALSE を返すので、
  // S_OK が返されることを確認する。

  if (S_OK == pStyle->GetMotif(pwszMotifName, &pSeg))
  {
    // セグメントを演奏する。

    pPerf->PlaySegment(pSeg,
                       DMUS_SEGF_BEAT | DMUS_SEGF_SECONDARY,
                       0,
                       NULL);
    pSeg->Release();
  }
}

通常、モチーフはプライマリ セグメントに重ねて演奏されるため、pSeg はセカンダリ セグメントとして演奏される点に注意すること。モチーフにはコード トラックやバンド トラックがないため、これをプライマリ セグメントとして演奏することはできない。無音の状態のときにモチーフを演奏する場合は、スタイルから空白のパターンだけを含むプライマリ セグメントを作成し、モチーフを演奏する間、このセグメントを演奏しておく。


コードマップの使い方

コードマップ オブジェクトは、基礎となる和音構造と音楽の雰囲気を提供するコードのコレクションを表す。コードマップには、多くの関連するコードによるいくつかのパスが含まれ、コンポーザ エンジンが音楽のピースのコード進行を決定する際に、さまざまな選択が可能となる。

概念については、「コードマップ」を参照すること。

オーサリングされたセグメントの場合、通常、アプリケーションはコードマップに関与する必要はない。コードマップは、固定コード進行を作成するために、オーサリングの段階で使用される。ただし、コードマップを使って、実行時にセグメントを作成したり、既存のセグメントのコード進行を変更することもできる。

スタイルの一部としてコードマップ参照をオーサリングした場合は、IDirectMusicStyle8::GetChordMap メソッドに (オーサーが割り当てた) コードマップの名前を渡して、IDirectMusicChordMap8 インターフェイスへのポインタを取得することができる。IDirectMusicStyle8::EnumChordMap メソッドを使って、特定のコードマップを検索することもできる。また、IDirectMusicStyle8::GetDefaultChordMap メソッドを使って、スタイルのデフォルト コードマップへのポインタを取得することもできる。

注 DirectMusic Producer では、スタイル ファイルへのコードマップ参照のオーサリングはサポートされていない。

IDirectMusicComposer8::ComposeSegmentFromTemplate または IDirectMusicComposer8::ComposeSegmentFromShape メソッドを使ってセグメントを作成するときに、アレンジ用のコードマップを設定する。詳細については、「スタイルの使い方」を参照すること。

セグメントを作成した後で、IDirectMusicComposer8::ChangeChordMap メソッドを呼び出して、いつでもコードマップを変更できる。これにより、基本的なリズムやメロディを変えることなく、音楽の雰囲気を変更する効果がある。

各コードマップは、24 の音程から成る基調のスケールを持つ。IDirectMusicChordMap8::GetScale メソッドを使って、スケールの音程を決定することができる。このメソッドの pdwScale パラメータで示される変数の下位 24 ビットは、対応する音程がスケールの一部になっているかどうかに応じて設定または消去される。上位 8 ビットは、スケールのルート音を、0 ～ 23 の範囲 (低い C から中間の B) の整数で設定する。


テンプレートの使い方

テンプレートは、演奏可能な音楽のセグメントを実行時にアレンジするときに使用できるセグメントである。テンプレートは、セグメントの長さとループ ポイントを設定する。コマンド トラックが提供され、グルーブ レベルの変更や、装飾パターンの選択が制御される。また、新しいコードをそれぞれどのサインポスト グループから取得するかを指定して、セグメントをアレンジするときにコードマップをどのように使用するかも指示する。

概念については、「テンプレート」を参照すること。

各テンプレートは DirectMusic セグメント オブジェクトによって表される。

テンプレートを取得する方法は 2 つある。

  • セグメント ファイルまたはリソースからテンプレートをロードする。テンプレートを DirectMusicObject としてロードし、IDirectMusicSegment8 インターフェイスの照会を行う。詳細については、「オーディオ データのロード」を参照すること。
  • IDirectMusicComposer8::ComposeTemplateFromShape メソッドを使って、シェイプからテンプレートを作成する。テンプレートの長さ、全体のシェイプ、イントロとエンドの装飾パターンを演奏するかどうか、およびエンディングの長さを選択する。IDirectMusicSegment インターフェイスへのポインタが返される。

テンプレート セグメント オブジェクトを取得した後、スタイルやコードマップへのポインタと共に、そのオブジェクトを IDirectMusicComposer8::ComposeSegmentFromTemplate メソッドに渡せる。また、コード変更の頻度を設定する和音進行も指定する。ComposeSegmentFromTemplate メソッドはセグメントを作成し、IDirectMusicSegment8 インターフェイスへのポインタを返す。このポインタを IDirectMusicPerformance8::PlaySegment または IDirectMusicPerformance8::PlaySegmentEx メソッドに渡す。


トランジションの使い方

あるセグメントを停止して次のセグメントを始める際に、耳障りな中断が突然発生することを防止するため、または音楽を終止形 (カデンツァ) へ移行するために、適切なトランジションを提供する中間または終始のセグメントを作成するようコンポーザに指示できる。

トランジション セグメントをアレンジするには、3 つの手法のいずれかを選択できる。

  • IDirectMusicPerformance8::PlaySegmentEx メソッドを使うと、pTransition パラメータでセグメントを指定できる。このセグメントは、新しくアレンジするトランジションのテンプレートとして使用される。トランジションは i64StartTime で演奏され、pSource で指定されたセグメントが演奏される。
  • IDirectMusicComposer8::AutoTransition メソッドは、パフォーマンスへのポインタを受け取り、現在演奏中のセグメントから開発者が指定した 2 番目のセグメントへのトランジションを作成する。続いて、再生の目的でトランジション セグメントと 2 番目のセグメントを自動的に挿入し、これら両方のセグメントへの IDirectMusicSegmentState インターフェイスを返す。トランジションの演奏は、直ちに、または dwFlags パラメータで指定された次の境界から開始される。オプションで、2 番目のセグメントを NULL にもできるが、その場合はトランジションを経て無音に至る。
  • IDirectMusicComposer8::ComposeTransition メソッドは、1 番目のセグメントの任意の場所から 2 番目のセグメントの先頭または無音に至るトランジションを作成し、アプリケーションがトランジションを演奏できるように IDirectMusicSegment インターフェイスへのポインタを返す。

AutoTransition と ComposeTransition のどちらのメソッドもパラメータとして、コードマップ、コマンド、および一連のフラグを受け取る。

  • コードマップは、通常どおり、セグメントのコード進行を定義するコード トラックを作成するために使用される。
  • コマンドとして、DMUS_COMMANDT_TYPES 列挙型のいずれかを指定する。コマンドは、トランジション セグメントのコマンド トラックで要求するパターンのタイプとして、通常のグルーブ パターンと装飾のどちらを使うかを決定する。セグメントを演奏する際に、スタイルから適切なパターンが選択される。
  • DMUS_COMPOSEF_FLAGS からフラグを選択し、トランジションの詳細、特にそのタイミングを定義する。DMUS_COMPOSEF_MODULATE フラグを使って、トランジションをある調性から別の調性へ円滑に移行させる。2 番目のセグメントがない場合、無音への変調は不可能なので、このフラグは利用できない。

AutoTransition およびmposeTransition によって作成されたトランジションの長さは、通常 1 小節である。ただし、DMUS_COMPOSEF_LONG フラグが含まれ、スタイル内のエンド装飾が 1 小節よりも長い場合は、1 小節よりも長くなる。また、DMUS_COMMANDT_ENDANDINTRO 型の場合は 2 小節以上になる。


トラックのアレンジ

セグメント内のほとんどのトラックは固定されており、セグメントを演奏するたびに同じデータが生成される。ただし、トラックが IDirectMusicTrack8::Compose メソッドを実装し、適切に設定されている場合、演奏の開始時やループするたびに、動的にデータを生成できる。

サインポスト トラックである単一の標準トラックは、アレンジをサポートする。サインポスト トラックは、コードマップから新しいコード トラックをアレンジする。

通常、トラック構成はオーサーによって設定されるが、次のいずれかまたは複数のフラグを IDirectMusicSegment8::SetTrackConfig または IDirectMusicSegmentState8::SetTrackConfig に渡すことによって、アプリケーションでトラックのアレンジの動作のオンとオフを切り替えることができる。

DMUS_TRACKCONFIG_COMPOSING
トラックは、IDirectMusicSegment8::Compose メソッドによってアレンジされる。
DMUS_TRACKCONFIG_LOOP_COMPOSE
トラックは、セグメントがループするたびに自動的にアレンジされる。
DMUS_TRACKCONFIG_PLAY_COMPOSE
トラックは、セグメントが開始されるたびに自動的にアレンジされる。

自動的にアレンジが行われるのは、アレンジした内容を保存するトラックがセグメントに含まれている場合だけである。サインポスト トラックをアレンジするときは、新しいコードのコード トラックが必要となる。セグメントを演奏する前に、IDirectMusicSegment8::Compose を呼び出すことによって、必要なトラックが存在することを確認できる。

すべてのアレンジを手動で行う場合は、設定する構成フラグは DMUS_TRACKCONFIG_COMPOSING だけである。ほかの 2 つのフラグがいずれも設定されていない場合、トラックは、Compose メソッドを呼び出した場合にのみアレンジされる。


オーディオ スクリプトの使い方

スクリプトは、DirectMusic Producer など、スクリプト エディタを含むアプリケーションでオーサリングされたオブジェクトである。スクリプトは主にテキストで構成されるが、スクリプト オブジェクトにはいくつかのバイナリ パラメータも含まれている。

概要については、「オーディオ スクリプト」を参照すること。

スクリプトは、IDirectMusicLoader8::GetObject メソッドを使ってロードする。IDirectMusicScript8 インターフェイスを取得し、IDirectMusicScript8::Init を呼び出して、スクリプトをパフォーマンスに関連付ける。

次のコードでは、スクリプトをロードして初期化している。m_pLoader は IDirectMusicLoader8 インターフェイスで、m_PPerformance は IDirectMusicPerformance8 インターフェイスであり、wstrFileName にはファイルの名前が格納されているとする。

IDirectMusicScript8*  pScript = NULL;
DMUS_SCRIPT_ERRORINFO errInfo;
HRESULT               hr;

if (SUCCEEDED(hr = m_pLoader->LoadObjectFromFile(
        CLSID_DirectMusicScript, IID_IDirectMusicScript8,
        wstrFileName, (LPVOID*) &pScript)))
{
    hr = pScript->Init( m_pPerformance, &errInfo);
}

Init を除いて、IDirectMusicScript8 のメソッドには、3 つの主な目的がある。

  • スクリプトで宣言された変数の値を設定および取得する。スクリプト ルーチンはパラメータを受け付けないので、変数は、スクリプトとアプリケーションで情報を交換するための唯一の方法である。
  • ルーチンを呼び出す。アプリケーション スレッドが続行するには、ルーチンの実行が完了している必要がある。
  • ルーチンと変数を列挙する。これらのメソッドは、主にスクリプト編集アプリケーションで使用される。

列挙メソッドを除く、IDirectMusicScript8 のすべてのメソッドは、DMUS_SCRIPT_ERRORINFO 構造体からエラー情報を取得する。変数が見つからなかった場合や、ルーチン内のコードが実行できなかった場合は、エラーが発生する可能性がある。

スクリプトは、アプリケーションで直接ロードまたは呼び出しを行わなくても使用できる。DirectMusic Producer で作成するセグメントにスクリプト トラックを含めて、スクリプト内のルーチンの呼び出しをトリガすることができる。


DirectSound でのウェーブの再生

ここでは、DirectMusic ローダーおよびパフォーマンス オブジェクトで提供されるサービスを使用せずに、DirectSound バッファを使ってウェーブを再生する方法について説明する。

DirectX 8.0 以降用に作成されたほとんどのアプリケーションでは、ウェーブ サウンドを再生する最適な方法は、ウェーブ サウンドをセグメントとしてロードし、パフォーマンスで再生することである。こうすることによって、コードが少なくなり、サウンド エフェクトとミュージックを密接に統合でき、3D バッファに入れる前に、オーディオパス上のサウンドをミキシングするなどの高度な機能を利用できる。ただし、ウェーブ サウンドを直接バッファで再生することもできる。

詳細については、次のトピックを参照すること。

  • DirectSound の再生の概要
  • DirectSound デバイス
  • DirectSound バッファ
  • ウェーブ データの使い方
  • DirectSound でのエフェクトの使い方


DirectSound の再生の概要

DirectSound オブジェクトはデバイスを表し、そのデバイスを管理し、サウンド バッファを作成するために使用される。

1 つのサウンド デバイスに対して複数のアプリケーションが DirectSound オブジェクトを作成することができる。入力フォーカスがあるアプリケーションからほかのアプリケーションへ移動する際に、オーディオ出力はあるアプリケーションのストリームからほかのアプリケーションのストリームへと自動的に切り替わる。したがって、入力フォーカスが移動する際に、アプリケーションはバッファの再生と停止を繰り返す必要はない。

DirectSound バッファ オブジェクトは、サウンド データを保持するバッファを表す。バッファ オブジェクトは、サウンドの再生の開始、停止、一時停止、周波数やフォーマットなどの属性を設定するために使われる。

プライマリ サウンド バッファは、リスナーが実際に聞くオーディオを保持する。各セカンダリ サウンド バッファは、1 つのサウンドまたはオーディオ ストリームを保持する。DirectSound は自動的にプライマリ バッファを作成するが、セカンダリ バッファはアプリケーションが作成しなければならない。セカンダリ バッファ内のサウンドが再生されると、DirectSound はプライマリ バッファ内でこれらをミキシングし、出力デバイスへ送り出す。DirectSound がミキシングできるバッファ数は処理時間にのみ制限され、処理時間が許す限りミキシングすることができる。

短いサウンドは全体をバッファにロードし、いつでも単純なメソッドの呼び出しによって再生できる。長いサウンドはストリーミングする必要がある。アプリケーションでは、再生カーソルの位置をポーリングしたり、再生カーソルが特定の位置に到達したときに通知を要求することによって、バッファに入れるデータをストリーミングしなければならない時期を確認できる。

データを正しい形式に整えてセカンダリ バッファに送り込むのは、開発者の責任である。DirectSound には、ウェーブ ファイルやリソースを解析する機能はない。しかし、SDK サンプル アプリケーション内に、このタスクを支援するコードが記述されている。


DirectSound デバイス

アプリケーションにDirectSound を実装する最初のステップは、サウンド デバイスを表す DirectSound オブジェクトを作成することである。

ここでは、利用可能なサウンド デバイスの列挙、デバイスに対する DirectSound オブジェクトの作成、オブジェクトのメソッドを使った協調レベルの設定、デバイス能力の取得、サウンド バッファの作成、システム スピーカの構成、ハードウェア メモリの圧縮をアプリケーションが行う方法について説明する。

  • サウンド デバイスの列挙
  • DirectSound オブジェクトの作成
  • 協調レベル
  • デバイスの能力
  • スピーカの構成
  • ハードウェア メモリの圧縮


サウンド デバイスの列挙

ユーザーが好む再生装置で単純にサウンドを再生するだけのアプリケーションでは、利用可能なデバイスを列挙する必要はない。DirectSoundCreate8 関数を呼び出して DirectSound オブジェクトを作成する場合、デフォルトのデバイスを指定できる。詳細については、「DirectSound オブジェクトの作成」を参照すること。

特定の種類のデバイスを探している場合や、ユーザーにデバイスを選択させる場合、複数のデバイスを使って動作する必要がある場合は、システム上で利用可能なデバイスを列挙しなければならない。

列挙は 3 つの目的で使われる。

  • 利用可能なハードウェアを報告。
  • 各デバイスに GUID を供給。
  • 列挙された各デバイスについて一時的な DirectSound オブジェクトを作成し、デバイスの能力をチェックできるようにする。

デバイスを列挙するには、DirectSound がデバイスを見つけるたびに呼び出すコールバック関数を最初に作成しなければならない。必要なすべての処理をこの関数内で実行し、関数に任意の名前を付けることができるが、この関数はプロトタイプである DSEnumCallback と同じ形式で宣言しなければならない。このコールバック関数は、列挙を続ける場合は TRUE、その他 (たとえば必要な能力を備えたデバイスを見つけた後など) の場合は FALSE を返さなければならない。

次のコールバック関数は、列挙された各デバイスに関する情報をコンボ ボックスに追加する。最初の 3 つのパラメータの値はデバイス ドライバによって供給されている。4 番目のパラメータは DirectSoundEnumerate 関数から引き渡される。

BOOL CALLBACK DSEnumProc(LPGUID lpGUID,
                         LPCTSTR lpszDesc,
                         LPCTSTR lpszDrvName,
                         LPVOID lpContext )
{
    HWND   hCombo = *(HWND *)lpContext;
    LPGUID lpTemp = NULL;

    if ( lpGUID != NULL )
    {
        if (( lpTemp = malloc( sizeof(GUID))) == NULL )
        return( TRUE );

        memcpy( lpTemp, lpGUID, sizeof(GUID));
    }

    ComboBox_AddString( hCombo, lpszDesc );
    ComboBox_SetItemData( hCombo,
                ComboBox_FindString( hCombo, 0, lpszDesc ),
                lpTemp );
    return( TRUE );
}

コンボ ボックスを含むダイアログを初期化する際に、列挙を行う。

if FAILED(DirectSoundEnumerate((LPDSENUMCALLBACK)DSEnumProc,
        (VOID*)&hCombo))
{
    EndDialog( hDlg, TRUE );
    return( TRUE );
}

この例では、コンボ ボックスのハンドルのアドレスは DirectSoundEnumerate に送られ、次にコールバック関数に渡される。このパラメータは、コールバック関数内でアクセスしたい任意の 32 ビットの値とすることができる。

注 列挙された最初のデバイスは常にプライマリ サウンド ドライバと呼ばれ、コールバックの lpGUID パラメータは NULL である。このデバイスは、ユーザーがコントロール パネルで設定した優先する再生デバイスを表す。アプリケーションが "プライマリ サウンド ドライバ" を一覧に追加して、ユーザーにデバイスの選択肢を提供しやすくするために、このデバイスは別に列挙される。プライマリ デバイスは、適切な名前および GUID と共に列挙される。


DirectSound オブジェクトの作成

DirectSound オブジェクトを作成する最も簡単な方法は、DirectSoundCreate8 関数を使うことである。この関数の最初のパラメータは、このオブジェクトに関連付けられるデバイスの GUID を指定する。この GUID は、サウンド デバイスの列挙で取得できる。または、次のいずれかの GUID を渡してデフォルトのデバイスを指定する。

DSDEVID_DefaultPlayback
デフォルトのシステム オーディオ デバイス。デバイスの GUID パラメータで NULL ポインタを渡すことによって、このデバイスを指定することもできる。デフォルトのデバイスは、 "プライマリ DirectSound ドライバ" として列挙される。
DSDEVID_DefaultVoicePlayback
デフォルトの音声通信デバイス。これは、通常、USB マイク付きヘッドセットなどのセカンダリ デバイスである。

デバイス ドライバが存在しない場合は、DirectSoundCreate8 の呼び出しは失敗する。

サウンド デバイスが存在しないか、VXD ドライバの場合、標準の Win32 ウェーブフォーム オーディオ関数を利用するアプリケーションがサウンド デバイスを制御している場合は、この関数はエラーを返す。アプリケーションはこの呼び出しが失敗した場合に備えて、サウンドなしでアプリケーションを続行するか、既にサウンド デバイスを使っているアプリケーションを閉じるようユーザーにプロンプトを表示するか、どちらかの準備をする必要がある。

次のコードでは、デフォルト デバイスの DirectSound オブジェクトを作成し、IDirectSound8 インターフェイスを取得している。

LPDIRECTSOUND8 lpds;
HRESULT hr = DirectSoundCreate8(NULL, &lpds, NULL));

注 DirectSoundCreate8 は CoInitialize を呼び出さない。アプリケーションがエフェクト DMO を使用する場合、アプリケーションは DirectSound オブジェクトの作成方法に関係なく、CoInitialize を呼び出す必要がある。

アプリケーションがサウンドをキャプチャして再生する場合、DirectSoundFullDuplexCreate8 関数を使って、DirectSound と DirectSoundCapture の両方のオブジェクト、および再生およびキャプチャ バッファを作成できる。

標準的な COM 関数を使って、次のように DirectSound オブジェクトを作成することもできる。

  1. アプリケーションの起動時に CoInitializeEx を呼び出して COM を初期化する。
    if FAILED(CoInitializeEx(NULL, 0))
    return FALSE;
  2. DirectSoundCreate8 関数ではなく、CoCreateInstance と IDirectSound8::Initialize の各メソッドを使って DirectSound オブジェクトを作成する。
    LPDIRECTSOUND8 lpds;
HRESULT hr = CoCreateInstance(&CLSID_DirectSound8,
                              NULL,
                              CLSCTX_INPROC_SERVER,
                              &IID_IDirectSound8,
                              &lpds);

    CLSID_DirectSound8 は DirectSound のドライバ オブジェクト クラスのクラス識別子であり、IID_IDirectSound8 はインターフェイス識別子である。lpds パラメータはインターフェイス ポインタを受け取る。

  3. IDirectSound8::Initialize メソッドを呼び出して、オブジェクトをデバイスに関連付ける。このメソッドは、DirectSoundCreate8 と同じデバイス GUID パラメータを取る。
    if SUCCEEDED(hr)
    hr = lpds->Initialize(NULL);
  4. アプリケーションを閉じる前に、次のように CoUninitialize 関数を呼び出して COM ライブラリを閉じる。
    CoUninitialize();


協調レベル

Windows はマルチタスク環境なので、複数のアプリケーションが任意の時点で同じデバイス ドライバを使って動作することがある。DirectX は協調レベルを使って、各アプリケーションが不適切な方法または不適切なタイミングでデバイスにアクセスしないことを保証する。DirectSound の各アプリケーションは、デバイスに対して認められるアクセス範囲を決定する 1 つの協調レベルを持つ。

DirectSound オブジェクトを作成した後で、サウンドを再生する前に IDirectSound8::SetCooperativeLevel メソッドを使ってデバイスの協調レベルを設定しなければならない。

次の例では、IDirectSound8 インターフェイスによって表される DirectSound デバイスの lpDirectSound での協調レベルを設定している。hwnd パラメータは、アプリケーション ウインドウへのハンドルである。

HRESULT hr = lpDirectSound->SetCooperativeLevel(hwnd, DSSCL_PRIORITY);

DirectSound では、DSSCL_NORMAL、DSSCL_PRIORITY、および DSSCL_WRITEPRIMARY の値で表される 3 つのサウンド デバイスの協調レベルを定義している。

注 DirectX 8.0 以前のバージョンで利用可能であった協調レベル DSSCL_EXCLUSIVE は廃止された。DirectX アプリケーションでほかのアプリケーションをミュートすることはできなくなった。排他的レベルを要求するアプリケーションには、代わりに優先レベルが付与される。

標準協調レベル

標準協調レベルでは、アプリケーションは、プライマリ サウンド バッファのフォーマットの設定、プライマリ バッファへの書き込み、デバイスのオンボード メモリの圧縮が行えない。この協調レベルを使うすべてのアプリケーションは、22kHz、ステレオ サウンド、8 ビット サンプリングのプライマリ バッファ フォーマットを使うので、デバイスはアプリケーション間で最も円滑に切り替えられる。

優先協調レベル

優先協調レベルで DirectSound デバイスを使うと、アプリケーションはハードウェア ミキシングなどのハードウェア リソースに対して最高の権限を確保し、プライマリ サウンド バッファのフォーマットの設定、デバイスのオンボード メモリの圧縮を行える。

ゲーム アプリケーションは、ほとんどすべての環境で優先協調レベルを使用する。このレベルは、サンプリング レートとビット深度に対するアプリケーション制御を可能にしながら、最も強力に動作する。また、優先協調レベルでは、IP テレフォニなどのほかのアプリケーションからのオーディオをゲームからのオーディオと共に聞くこともできる。

書き込み優先協調レベル

最上位の協調レベルは書き込み優先である。この協調レベルで DirectSound デバイスを使うと、アプリケーションはプライマリ サウンド バッファに直接アクセスできる。このモードでは、アプリケーションはプライマリ バッファに直接書き込みを行わなければならない。この書き込み中は、セカンダリ バッファを再生できない。

プライマリ バッファ内のオーディオ サンプルに直接書き込みのアクセスをするには、アプリケーションを書き込み優先レベルに設定しなければならない。アプリケーションがこのレベルに設定されていない場合、IDirectSoundBuffer8::Lock メソッドの呼び出しはすべて失敗する。

書き込み優先協調レベルに設定されたアプリケーションがフォアグラウンドになると、ほかのアプリケーションのすべてのセカンダリ バッファは停止され、「失われた」とマークされる。最初のアプリケーションがバックグラウンドに移ると、そのプライマリ バッファは「失われた」とマークされ、アプリケーションが再度フォアグラウンドに移るときにはこのバッファを復元しなければならない。詳細については、「バッファ管理」を参照すること。

DirectSound ドライバがユーザーのシステムに存在していない場合は、書き込み優先レベルの設定はできない。この状況に該当するかどうかを確認するには、IDirectSound8::GetCaps メソッドを呼び出して、DSCAPS 構造体の DSCAPS_EMULDRIVER フラグをチェックする。

詳細については、「プライマリ バッファへの書き込み」を参照すること。


デバイスの能力

DirectSound を使うと、アプリケーションはサウンド デバイスのハードウェア能力を取得できる。DirectSound は利用可能なハードウェア アクセラレーションを自動的に利用するので、アプリケーションでは、通常この取得を行う必要はない。しかし高性能のアプリケーションはこの情報を利用し、利用可能なハードウェアに対してサウンドの要求事項を評価できる。たとえば、ハードウェア ミキシングが利用可能な場合は、利用不可能な場合に比べて、アプリケーションがより多くのサウンドを再生できるはずである。

DirectSoundCreate8 関数を呼び出して DirectSound オブジェクトを作成した後は、IDirectSound8::GetCaps メソッドを使ってサウンド デバイスの能力を取得できる。

次の例では、IDirectSound8 インターフェイス ポインタ lpDirectSound によって表されるデバイスの能力を取得している。

DSCAPS dscaps;

dscaps.dwSize = sizeof(DSCAPS);
HRESULT hr = lpDirectSound->GetCaps(&dscaps);

DSCAPS 構造体は、サウンド デバイスの能力とリソースに関する情報を受け取るが、この中にはタイプごとの最大のリソースと現在利用可能なリソースが含まれる。このメソッドを呼び出す前に、この構造体の dwSize メンバを初期化しなければならない点に注意すること。

アプリケーションがハードウェア能力を評価する場合は、バッファ割り当てを行うたびに IDirectSound8::GetCaps メソッドを呼び出して、次のバッファを作成するのに十分なリソースがあるかどうかを確認すべきである。


スピーカの構成

DirectSound は、スピーカがリスナーに対する相対的な位置をとるスピーカ構成を使って、ユーザーのサウンド システムに合わせて 3D エフェクトを最適化する。

Windows® 98 と Windows® 2000 では、ユーザーはコントロール パネルを使ってスピーカ構成を設定できる。アプリケーションは IDirectSound8::GetSpeakerConfig を使ってこの値を取得し、IDirectSound8::SetSpeakerConfig を呼び出してその値を変更できる。

SetSpeakerConfig がすぐに有効になるという保証はなく、単にレジストリ設定を変更しただけで、コンピュータを再起動しなければ有効にならない場合もある。このメソッドを使用する代わりに、コントロール パネルを使ってスピーカ構成を変更するようユーザーにアドバイスする必要がある。

Windows 95 では、GetSpeakerConfig は単純に、デフォルトの値または SetSpeakerConfig で設定した直前の値を返す。


ハードウェア メモリの圧縮

アプリケーションは最小限の協調レベルを備えていることを前提として、IDirectSound8::Compact メソッドを使って、任意のオンボード サウンド メモリを移動して連続ブロックを形成し、フリー メモリの最大部分を使用可能にできる。


DirectSound バッファ

DirectSound バッファ オブジェクトは、ウェーブ データの入力から出力までの配信を制御する。入力には、シンセサイザ、ほかのバッファ、ファイル、またはリソースがある。ほとんどのバッファの場合、出力先はプライマリ バッファと呼ばれるミキシング エンジンである。データは、プライマリ バッファから、PCM サンプルをサウンド ウェーブに変換するハードウェアに送られる。

ここでは、以前のバージョンの DirectSound 用に作成されたアプリケーション、つまりバッファの下位レベルの制御を必要とするアプリケーションについて説明する。アプリケーションが DirectMusic パフォーマンス オブジェクトを使ってサウンドを再生する場合、バッファの作成および管理は自動的に行われる。ただし、3D エフェクトや DMO のエフェクトのパラメータへのアクセスを取得するために、バッファ オブジェクトを取得できる。詳細については、「エフェクトの使い方」および「3D サウンド」を参照すること。

DirectSound バッファの使い方については、以下のトピックで説明する。

  • バッファの基本
  • セカンダリ バッファの作成
  • バッファの複製
  • バッファ コントロール オプション
  • バッファの 3D アルゴリズム
  • スタティック バッファの書き込みと再生
  • ストリーム バッファの使い方
  • 再生のコントロール
  • 再生カーソルと書き込みカーソル
  • 再生バッファの通知
  • サウンドのミキシング
  • バッファ管理

キャプチャ バッファについては、「ウェーブのキャプチャ」を参照すること。


バッファの基本

DirectSound を初期化すると、DirectSound はサウンドのミキシングと出力デバイスへの送信をするために、プライマリ サウンド バッファの作成と管理を自動的に行う。

アプリケーションは、個々のサウンドの保存と再生をするために、少なくとも 1 つのセカンダリ サウンド バッファを作成しなければならない。この方法の詳細については、「セカンダリ バッファの作成」を参照すること。

セカンダリ バッファは、アプリケーションが動作している間常に持続することも、不要になったときに削除することもできる。セカンダリ バッファには、ゲーム中の効果音など繰り返し再生される 1 つのサウンドを格納したり、適宜新しいデータを記録することもできる。アプリケーションは、セカンダリ バッファに記憶されているサウンドを 1 つのイベント、または連続再生されるループ サウンドとして再生できる。サウンド ファイルのデータが非常に大きく、メモリに記憶しておくことが実用的ではない場合、データをストリームするためにセカンダリ バッファを利用できる。

バッファは、ハードウェアまたはソフトウェアのいずれかに配置できる。ハードウェア バッファはサウンド カードのプロセッサによってミキシングされ、ソフトウェア バッファは CPU によってミキシングされる。ソフトウェア バッファのデータは常にシステム メモリに置かれる。ハードウェア バッファのデータはシステム メモリに置くことも、アプリケーションが要求し、リソースが使用可能な場合はオンボード メモリに置くこともできる。詳細については、「ダイナミック ボイス管理」および「ISA および PCI カードでのハードウェア アクセラレーション」を参照すること。

異なるセカンダリ バッファのサウンドは、これらを同時に再生するだけでミキシングできる。処理能力の限界内であれば、任意の数のセカンダリ バッファを同時に再生できる。

通常、開発者はプライマリ バッファを意識する必要はまったくない。DirectSound が内部で管理を行う。しかし、アプリケーションが固有のミキシングを行う場合は、開発者がプライマリ バッファに直接書き込みを行う必要がある。これを行うと、セカンダリ バッファを同時には利用できない。詳細については、「プライマリ バッファへの書き込み」を参照すること。


セカンダリ バッファの作成

サウンド バッファを作成するには、IDirectSound8::CreateSoundBuffer メソッドを呼び出す。このメソッドは、IDirectSoundBuffer8 インターフェイスへのポインタを返す。アプリケーションはこのインターフェイスを使って、バッファを操作および演奏する。

次の例は、セカンダリ サウンド バッファを作成する方法を示している。

BOOL AppCreateBasicBuffer(
        LPDIRECTSOUND8 lpDirectSound,
        LPDIRECTSOUNDBUFFER *lplpDsb)
{
    PCMWAVEFORMAT pcmwf;
    DSBUFFERDESC dsbdesc;
    HRESULT hr;

    // ウェーブ フォーマット構造体を設定する。
    memset(&pcmwf, 0, sizeof(PCMWAVEFORMAT));
    pcmwf.wf.wFormatTag = WAVE_FORMAT_PCM;
    pcmwf.wf.nChannels = 2;
    pcmwf.wf.nSamplesPerSec = 22050;
    pcmwf.wf.nBlockAlign = 4;
    pcmwf.wf.nAvgBytesPerSec =
        pcmwf.wf.nSamplesPerSec * pcmwf.wf.nBlockAlign;
    pcmwf.wBitsPerSample = 16;

    // DSBUFFERDESC 構造体を設定する。

    memset(&dsbdesc, 0, sizeof(DSBUFFERDESC));
    dsbdesc.dwSize = sizeof(DSBUFFERDESC);
    dsbdesc.dwFlags =
        DSBCAPS_CTRLPAN | DSBCAPS_CTRLVOLUME | DSBCAPS_CTRLFREQUENCY;

    dsbdesc.dwBufferBytes = 3 * pcmwf.wf.nAvgBytesPerSec;
    dsbdesc.lpwfxFormat = (LPWAVEFORMATEX)&pcmwf;

    // バッファを作成する。

    hr = lpDirectSound->CreateSoundBuffer(&dsbdesc, lplpDsb, NULL);
    if SUCCEEDED(hr)
    {
        // IDirectSoundBuffer インターフェイスは *lplpDsb にある。
        // QueryInterface を使って IDirectSoundBuffer8 を取得する。
        return TRUE;
    }
    else
    {
        // 失敗した場合。
        *lplpDsb = NULL;
        return FALSE;
    }
}

この例では、3 秒間のストリーミング データを保持するのに十分な大きさのストリーム バッファを作成する。ストリーム バッファ以外のバッファは、サウンド全体を保持するのに十分な大きさで作成しなければならない。

DirectSound はハードウェア リソースを最初のバッファに割り当て、その利点を生かす。ハードウェア バッファはサウンド カード プロセッサでミキシングされるので、アプリケーション性能にほとんど影響を及ぼさない。

バッファの位置を DirectSound に決めさせずに自分で指定したい場合は、DSBUFFERDESC 構造体に DSBCAPS_LOCHARDWARE または DSBCAPS_LOCSOFTWARE のどちらかのフラグを設定する。DSBCAPS_LOCHARDWARE フラグを設定し、ハードウェア リソースが不足している場合、バッファの作成要求は失敗する。

DirectSound のボイス管理機能を利用するには、バッファの作成時に DSBCAPS_LOCDEFER フラグを指定する。このフラグは、バッファに対するリソースの割り当てを、バッファが再生されるまで遅延する。詳細については、「ダイナミック ボイス管理」を参照すること。

既存のバッファの位置を確認するには、IDirectSoundBuffer8::GetCaps メソッドを使い、DSBCAPS 構造体の dwFlags メンバをチェックして、DSBCAPS_LOCHARDWARE と DSBCAPS_LOCSOFTWARE のどちらのフラグになっているかを調べる。どちらかが必ず指定されている。

DSBCAPS_STATIC フラグを設定すると、可能な場合はバッファをオンボードのハードウェア メモリに作成すべきであることが DirectSound に通知される。ハードウェア バッファが利用できない場合でも、IDirectSound::CreateSoundBuffer メソッドは失敗しない。このフラグは、バッファ用にシステム メモリを使う最近のサウンド カードの多くには影響しない。ハードウェア スタティック バッファは、繰り返し再生される短いサウンドに対してだけ使うべきである。詳細については、「ISA および PCI カードでのボイス管理」を参照すること。

バッファ オブジェクトは、これを作成した DirectSound オブジェクトが所有する。DirectSound オブジェクトが解放されると、このオブジェクトが作成したすべてのバッファも解放され、参照できなくなる。


バッファの複製

IDirectSound8::DuplicateSoundBuffer メソッドを使って、同じデータを含む複数のセカンダリ バッファを作成できる。プライマリ サウンド バッファは複製できない。たとえ呼び出しが成功したとしても、実際に重複バッファが元のバッファとメモリを共有するとは限らないので、これらの変更がすべての重複バッファに反映されるであろうという予測のもとにバッファを変更するべきではない。


バッファ コントロール オプション

サウンド バッファを作成するときに、バッファが必要とするコントロール オプションを指定しなければならない。これには DSBUFFERDESC 構造体の dwFlags メンバを使用する。この構造体は、1 つまたは複数の DSBCAPS_CTRL* フラグを保持できる。

次のコントロールが利用できる。

  • 3D プロパティ。
  • エフェクト。
  • 周波数。
  • パン。
  • ボリューム。
  • 位置の通知。

あらゆるサウンド カードから最高の性能を得るには、アプリケーションが使うオプションだけを指定すべきである。

DirectSound はコントロール オプションを使って、サウンド バッファにハードウェア リソースを割り当てられるかどうかを決定する。たとえば、あるデバイスがハードウェア バッファをサポートしていて、それらのバッファにパン コントロールを提供していないとする。この場合、DirectSound は DSBCAPS_CTRLPAN フラグが指定されていない場合に限って、ハードウェア アクセラレーションを使う。

コントロールは、特定の組み合わせで使用できないことに注意すること。たとえば、パンと 3D を同時に使用することはできない。

バッファが備えていないコントロールを使おうとすると、メソッドは失敗する。たとえば、IDirectSoundBuffer8::SetVolume メソッドを使ってボリュームを変更しようとするとき、そのバッファの作成時に DSBCAPS_CTRLVOLUME フラグが指定されていた場合に限ってメソッドは成功する。このフラグが指定されていなかった場合はメソッドは失敗に終わり、DSERR_CONTROLUNAVAIL エラーコードが返される。

「再生のコントロール」も参照すること。


バッファの 3D アルゴリズム

DSBCAPS_CTRL3D コントロール フラグを指定してセカンダリ フバッファを作成するときに、バッファがソフトウェアで処理される場合は、サウンドの空間的な広がりを出すために使用するアルゴリズムも指定できる。デフォルトでは、HRTF 処理は実行されず、リスナーから相対的なサウンドの位置は、パンおよびボリュームによってのみ指定される。バッファに 2 つのレベルの HRTF を要求できる。

詳細については、「DSBUFFERDESC」を参照すること。


スタティック バッファの書き込みと再生

独立したサウンド全体を保持するセカンダリ バッファを、スタティック バッファという。同じバッファを異なるサウンドで再利用することもできるが、通常はデータを一度だけスタティック バッファに記述する。

スタティック バッファはストリーム バッファと同様に作成および管理される。違いはバッファの使い方だけである。スタティック バッファは一度書き込まれて演奏されるが、ストリーム バッファは演奏中に定期的にデータが更新される。

注 スタティック バッファは必ずしも、DSBCAPS_STATIC フラグをバッファ記述に設定することで作成されるわけではない。このフラグは、現在の多くのハードウェアでは使用できない、サウンド カード上でのメモリ割り当てを要求する。スタティック バッファはシステム メモリ内に置かれ、DSBCAPS_LOCHARDWARE または DSBCAPS_LOCSOFTWARE のどちらかのフラグで作成される。詳細については、「ISA および PCI カードでのボイス管理」を参照すること。

スタティック バッファへのデータのロードは、3 つのステップで行われる。

  1. IDirectSoundBuffer8::Lock を使ってバッファ全体をロックする。記述を始めるバッファ内のオフセットを指定し (通常は 0)、その位置のメモリ アドレスを返す。
  2. 標準のメモリコピー ルーチンを使って、返されたアドレスにオーディオ データを書き込む。
  3. IDirectSoundBuffer8::Unlock を使って、バッファをアンロックする。

これらのステップを次の例で示す。lpdsbStatic は IDirectSoundBuffer8 インターフェイス ポインタであり、pbData はデータ ソースのアドレスである。

LPVOID lpvWrite;
DWORD  dwLength;

if (DS_OK == lpdsbStatic->Lock(
        0,              // ロックを開始するオフセット。
        0,              // ロックのサイズ。フラグのために無視される。
        &lpvWrite,      // ロックの最初の部分のアドレスを取得する。
        &dwLength,      // ロックの最初の部分のサイズを取得する。
        NULL,           // ラップアラウンドのアドレスは必要ない。
        NULL,           // ラップアラウンドのサイズは必要ない。
        DSBLOCK_ENTIREBUFFER))  // フラグ。
{
    memcpy(lpvWrite, pbData, dwLength);
    lpdsbStatic->Unlock(
        lpvWrite,       // ロック開始のアドレス。
        dwLength,       // ロックのサイズ。
        NULL,           // ラップアラウンド位置はない。
        0);             // ラップアラウンド サイズはない。
}

バッファを再生するには、次の例のように IDirectSoundBuffer8::Play を呼び出す。

lpdsbStatic->SetCurrentPosition(0);
HRESULT hr = lpdsbStatic->Play(
        0,    // 未使用。
        0,    // ボイス管理の優先度。
        0);   // フラグ。

この例では DSBPLAY_LOOPING フラグを設定していないので、バッファは最後に到達すると自動的に停止する。また、IDirectSoundBuffer8::Stop を使うとバッファを早めに停止できる。バッファを早めに停止する場合は、再生カーソル位置がその場所にとどまる。したがって、例に示されている IDirectSoundBuffer8::SetCurrentPosition に対する呼び出しは、バッファが始めから開始することを保証するものである。


ストリーム バッファの使い方

ストリーム バッファは、一度にバッファに収まらない長いサウンドを再生する。バッファが再生されるにつれ、古いデータは定期的に新しいデータに置き換わる。

ストリーム バッファを再生するには、dwFlags パラメータに DSBPLAY_LOOPING を指定して IDirectSoundBuffer8::Play メソッドを呼び出す。

再生を停止するには、IDirectSoundBuffer8::Stop メソッドを呼び出す。このメソッドはバッファを即時に停止するので、すべてのデータが再生されたことを確認する必要がある。これを行うには、再生位置をポーリングするか、通知位置を設定する。

バッファにストリーミングするには、次のステップが必要である。

  1. IDirectSoundBuffer8::Lock を使って、バッファの一部をロックする。このメソッドは、データを記述できる 1 つ、または 2 つのアドレスを返す。
  2. この 1 つまたは 2 つのアドレスに対して、標準のメモリコピー ルーチンを使ってオーディオ データを書き込む。
  3. IDirectSoundBuffer8::Unlock を使って、バッファをアンロックする。

IDirectSoundBuffer8::Lock が 2 つのアドレスを返すことがあるのは、開始位置にかかわらず、バッファのサイズまでのバイト数をロックできるからである。必要に応じて、ロックされる部分はバッファの先頭にラップされる。ラップされる場合は、2 つの個別のメモリ コピーを実行しなければならない。

たとえば 40,000 バイトのバッファで、オフセット 20,000 で始まる 30,000 バイトをロックする場合、Lock を呼び出すと 4 つの値が返される。

  • オフセット 20,000 のアドレス。
  • バッファのその位置から最後までのロックされたバイト数 (20,000)。最初のアドレスにこのバイト数だけ記述する。
  • オフセット 0 のアドレス。
  • その位置からロックされたバイト数 (10,000)。2 番目のアドレスにこのバイト数だけ記述する。

ラップ アラウンドが必要ない場合は、最後の 2 つの値がそれぞれ NULL と 0 になる。

バッファ全体をロックすることもできるが、再生中に行うべきではない。毎回バッファの一部だけをリフレッシュすること。たとえば、再生カーソルが 2/4 に達したらすぐに、バッファの最初の 1/4 をロックして書き込むようにする。バッファの再生カーソルと書き込みカーソルの間にある部分には書き込んではならない。詳細については、「再生カーソルと書き込みカーソル」を参照すること。

次の関数は、dwOffset に渡された位置から、データをサウンド バッファに書き込む。

BOOL AppWriteDataToBuffer(
    LPDIRECTSOUNDBUFFER8 lpDsb,  // バッファ。
    DWORD dwOffset,              // 独自の書き込みカーソル。
    LPBYTE lpbSoundData,         // データの開始。
    DWORD dwSoundBytes)          // コピーするブロックのサイズ。
{
    LPVOID  lpvPtr1;
    DWORD   dwBytes1;
    LPVOID  lpvPtr2;
    DWORD   dwBytes2;
    HRESULT hr;

    // 書き込みブロックのメモリ アドレスを取得する。ブロックがラップアラウンドされる場合、
    // これは 2 つの部分になる。

    hr = lpDsb->Lock(dwOffset, dwSoundBytes, &lpvPtr1,
        &dwBytes1, &lpvPtr2, &dwBytes2, 0);

    // バッファが失われた場合、復元してロックを再試行する。

    if (DSERR_BUFFERLOST == hr)

    {
        lpDsb->Restore();
        hr = lpDsb->Lock(dwOffset, dwSoundBytes,
            &lpvPtr1, &dwBytes1, &lpvPtr2, &dwBytes2, 0);
    }
    if SUCCEEDED(hr)
    {
        // ポインタに書き込む。

        CopyMemory(lpvPtr1, lpbSoundData, dwBytes1);
        if (NULL != lpvPtr2)
        {
            CopyMemory(lpvPtr2, lpbSoundData+dwBytes1, dwBytes2);
        }

        // データを解放して DirectSound に戻す。

        hr = lpDsb->Unlock(lpvPtr1, dwBytes1, lpvPtr2,
            dwBytes2);
        if SUCCEEDED(hr)
        {
            // 成功。
            return TRUE;
        }
    }

    // ロック、アンロック、または復元が失敗した。

    return FALSE;
}

詳細については、次のトピックを参照すること。

  • 再生カーソルと書き込みカーソル
  • 再生バッファの通知
  • ウェーブ ファイルの読み込み


再生のコントロール

IDirectSoundBuffer8::GetVolume と IDirectSoundBuffer8::SetVolume の各メソッドを使うと、再生中のバッファのボリュームを取得および設定できる。プライマリ サウンド バッファのボリュームを設定すると、サウンド カードのウェーブフォーム オーディオのボリュームが変更される。

IDirectSoundBuffer8::GetFrequency と IDirectSoundBuffer8::SetFrequency の各メソッドを使うと、サンプリング オーディオの再生周波数を取得および設定できる。プライマリ バッファの周波数は変更できない。

パンを取得および設定するには、IDirectSoundBuffer8::GetPan と IDirectSoundBuffer8::SetPan の各メソッドを呼び出す。

これらのコントロールのいずれかを使うには、バッファを作成する際に適切なフラグを設定しなければならない。「バッファ コントロール オプション」を参照すること。


再生カーソルと書き込みカーソル

DirectSound はバッファへのポインタを 2 つ保持している。再生カーソルと書き込みカーソルである。これらの位置はバッファのバイト オフセットであり、メモリの絶対アドレスではない。

IDirectSoundBuffer8::Play メソッドは、常にバッファの再生カーソルの位置から再生を開始する。バッファを作成した時点で、カーソル位置は 0 に設定される。サウンドが再生されるにつれ、カーソル位置は移動し、次に出力されるデータ バイトを示す。バッファが停止したときは、カーソルは次のデータ バイトにとどまる。

バッファの書き込みカーソルより後の場所には、データを安全に書き込める。カレント プレイ ポジションとカレント ライト ポジションの間にあるブロックは、既に再生が確定していて、安全に変更することはできない。

バッファを時計の文字盤で表し、時計回りの方向にデータを書き込むと考える。再生位置と書き込み位置は、この文字盤上で同じ速度で回転する 2 本の針にたとえられ、書き込み位置は、常に再生位置の少し前方にある。再生位置が 1 を示し、書き込み位置が 2 を示している場合は、データを書き込んでも安全なのは 2 の後だけである。1 と 2 の間のデータは DirectSound が既に再生キューに入れている可能性もあるので、変更すべきではない。

書き込み位置は、バッファに書き込まれたデータではなく再生位置に合わせて移動する。データをストリーミングする場合、次に書き込みを行うデータ ブロックの位置を示すために、開発者は独自のポインタを維持する責任を負う。

アプリケーションは、IDirectSoundBuffer8::GetCurrentPosition メソッドを呼び出すことにより、再生カーソルと書き込みカーソルを取得できる。IDirectSoundBuffer8::SetCurrentPosition メソッドによって、再生カーソルを移動できる。アプリケーションは、書き込みカーソルの位置を制御しない。

再生カーソルをできるだけ正確に報告するには、セカンダリ バッファを作成する際に DSBCAPS_GETCURRENTPOSITION2 フラグを指定しなければならない。詳細については、「DSBUFFERDESC」を参照すること。


再生バッファの通知

オーディオをストリーミングする場合、再生カーソルがバッファ内のあるポイントに到達したときや、再生が停止したときに、アプリケーションへの通知を発生させたいことがある。IDirectSoundNotify8::SetNotificationPositions メソッドを使うと、イベントのシグナルを送信するポイントをバッファ内にいくつでも設定できる。ただし、バッファの再生中はイベント ポイントの設定を行うことはできない。

最初に IDirectSoundNotify8 インターフェイスへのポインタを取得しなければならない。この取得は、バッファ オブジェクトの QueryInterface メソッドを使って行う。次に C++ による例を示す。lpDsbSecondary は IDirectSoundBuffer8 インターフェイス ポインタである。

LPDIRECTSOUNDNOTIFY8 lpDsNotify;

HRESULT hr = lpDsbSecondary->QueryInterface(IID_IDirectSoundNotify8,
                                            (LPVOID *)&lpDsNotify);
if SUCCEEDED(hr)
{
    // 続行して lpDsNotify->SetNotificationPositions を使う。
}

IDirectSoundNotify8 インターフェイスは、ポインタを取得したバッファ オブジェクトに関連付けられている。インターフェイスのメソッドは自動的にこのバッファに適用される。

次に、Win32 の CreateEvent 関数を使って、イベント オブジェクトを作成する。このイベントのハンドルを DSBPOSITIONNOTIFY 構造体の hEventNotify メンバに書き込む。この構造体の dwOffset メンバで、バッファ内でイベントのシグナルを送信したい位置のオフセットを指定する。次にこの構造体のアドレスを、または複数の通知位置を設定したい場合は構造体の配列を、IDirectSoundNotify8::SetNotificationPositions メソッドに渡す。

次の例は、1 つの通知位置を設定する。ループしない条件でバッファの終了位置に到達したか、アプリケーションが IDirectSoundBuffer8::Stop メソッドを呼び出したか、どちらかの理由で再生が停止したときに、イベントのシグナルが送信される。

DSBPOSITIONNOTIFY PositionNotify;

PositionNotify.Offset = DSBPN_OFFSETSTOP;
PositionNotify.hEventNotify = hMyEvent;
// hMyEvent は CreateEvent() によって返されるハンドルである。

lpDsNotify->SetNotificationPositions(1, &PositionNotify);

ボイス管理を利用している場合は、通知位置に到達する前にバッファを終了できる。DSBPOSITIONNOTIFY の「注意」を参照すること。


サウンドのミキシング

DirectSound で複数のストリームをミキシングするのは簡単である。単純にセカンダリ サウンド バッファを作成し、各サウンドに対する IDirectSoundBuffer8 インターフェイスを取得するだけである。次にそれらのバッファを同時に再生する。DirectSound はプライマリ サウンド バッファでのミキシングを処理し、その結果を再生する。

アプリケーション内のすべてのサウンドが同じウェーブ フォーマットを使用し、ハードウェア出力フォーマットがそれらのサウンドのフォーマットと一致している場合、DirectSound ミキサは最高の品質のサウンドをもたらす。この場合、ミキサはフォーマット変換をする必要がない。

ハードウェア出力フォーマットを変更するには、プライマリ サウンド バッファ オブジェクトを作成し、IDirectSoundBuffer8::SetFormat メソッドを呼び出す。このプライマリ バッファ オブジェクトはコントロールの目的にのみ使用できる。このバッファの作成は、「プライマリ バッファへの書き込み」で説明したプライマリ バッファへの書き込みアクセスの取得と同じことを意味せず、協調レベルを DSSCL_WRITEPRIMARY に設定する必要もない。しかし、SetFormat メソッドを呼び出すために、DSSCL_PRIORITY またはそれ以上の協調レベルを設定する必要がある。アプリケーションが入力フォーカスを取得するたびに、DirectSound はハードウェア フォーマットを、前回の呼び出しで指定されたフォーマットに復元する。

セカンダリ バッファを作成する前に、プライマリ バッファのフォーマットを設定しなければならない。

注 WDM ドライバを使う場合は、プライマリ バッファのフォーマットを設定しても効果がない。フォーマットはカーネル ミキサによって決定される。詳細については、「DirectSound ドライバ モデル」を参照すること。


バッファ管理

IDirectSoundBuffer8::GetCaps メソッドは、DirectSoundBuffer オブジェクトの能力を取得する。

アプリケーションは IDirectSoundBuffer8::GetStatus メソッドを使って、バッファが再生中か停止しているかを確認できる。

IDirectSoundBuffer8::GetFormat メソッドを使うと、バッファ内のサウンド データのフォーマット情報を取得できる。また、IDirectSoundBuffer8::SetFormat を使って、プライマリ バッファ内のサウンド データのフォーマットを設定できる。詳細については、「サウンドのミキシング」を参照すること。

注 SetFormat メソッドをセカンダリ バッファについて呼び出すことはできない。セカンダリ バッファが作成された後、そのフォーマットが固定される。ほかのフォーマットを使うセカンダリ バッファが必要な場合は、そのフォーマットを指定して新しいサウンド バッファを作成しなければならない。

サウンド バッファ用のメモリは特定の状況で失われることがある。たとえば、バッファがサウンド カードのメモリに置かれていて、ほかのアプリケーションがハードウェア リソースの制御を取得した場合である。書き込み優先の協調レベルで動作するアプリケーションがフォアグラウンドに移動した場合も、メモリが失われることがある。この場合、ほかのすべてのサウンド バッファは失われるので、フォアグラウンドに移動したアプリケーションはプライマリ バッファに直接書き込める。

失われたバッファに対して IDirectSoundBuffer8::Lock、IDirectSoundBuffer8::Play メソッドのいずれかを呼び出すと、DSERR_BUFFERLOST エラーコードが返される。バッファを失わせたアプリケーションの協調レベルが書き込み優先から下がったり、そのアプリケーションがバックグラウンドに移動した場合、ほかのアプリケーションは IDirectSoundBuffer8::Restore メソッドを呼び出してバッファ メモリの再配置を試みることができる。成功した場合、このメソッドはバッファ メモリと、ボリュームやパンの設定などほかのすべての設定を復元する。しかし、復元されたバッファは有効なサウンド データを保持していない。したがって、アプリケーションは復元されたバッファにデータをもう一度書き込むべきである。


ウェーブ データの使い方

DirectSound バッファは、固定サンプリング レートのサウンドのデジタル サンプルで構成されるウェーブフォーム オーディオ データのみ再生する。アナログ シグナルを数字のシーケンスで表現することを、パルス コード変調 (PCM) と呼ぶ。

ウェーブ データは、通常、RIFF (Resource Interchange File Format) のファイルまたはリソースに保存される。このデータには、サンプリング レートや出力チャンネル数などのパラメータを含む、ウェーブ フォーマットの記述が含まれる。

サウンドの特定のフォーマットは、WAVEFORMATEX または WAVEFORMATEXTENSIBLE 構造体を使って記述できる。

この構造体の wFormatTag メンバは、Microsoft が割り当てた一意の識別子を保持する。DirectSound で有効なタグは、次のタグだけである。

  • WAVE_FORMAT_PCM。このタグは、パルス コード変調 (PCM)、非圧縮フォーマットを示す。
  • WAVE_FORMAT_EXTENSIBLE。マルチチャンネル オーディオ フォーマットで、WDM ドライバでのみ有効。詳細については、「マルチチャンネル ウェーブ フォーマット」を参照すること。

DirectSound は、圧縮ウェーブ フォーマットをサポートしていない。アプリケーションはサウンド バッファにデータを書き込む前に、Platform SDK 内の Win32 API で提供されているオーディオ圧縮マネージャ (ACM) 関数を使って、圧縮されたオーディオ データを PCM フォーマットに変換すべきである。この代わりに、DirectMusic パフォーマンスで再生するために圧縮されたウェーブをロードしたときに、自動的に ACM を利用する DirectMusic ローダーを使用することもできる。

ウェーブの詳細については、次のトピックを参照すること。

  • マルチチャンネル ウェーブ フォーマット
  • ウェーブ ファイルの読み込み
  • リソースからのウェーブ データの読み込み


マルチチャンネル ウェーブ フォーマット

WDM ドライバでは、DirectSound バッファは、5.1 などのスピーカ構成用に複数の出力チャンネルを持つウェーブ フォーマットをサポートしている。5.1 スピーカ構成では、前方左、前方中央、前方右、後方左、後方右のスピーカと、低周波数ウーファーを使用する。

WAVEFORMATEXTENSIBLE 構造体は、マルチチャンネル ウェーブ フォーマットを記述する。この構造体は、WAVEFORMATEX の cbSize メンバでサポートされている追加バイトを構成する、WAVEFORMATEX の拡張機能である。WAVEFORMATEXTENSIBLE 構造体は、DSBUFFERDESC 構造体など、WAVEFORMATEX が使用される場所で WAVEFROMATEX としてキャストすることができる。

マルチチャンネル ウェーブ ファイルで指定されたチャンネルよりも物理的なスピーカが少ない場合は、オーディオ データは適切にミキシングされ、既存のスピーカに出力される。

DirectSound は、マルチチャンネル フォーマットでのバッファのエフェクトや 3D 処理をサポートしていない。DSBCAPS_CTRL3D または DSBCAPS_CTRLFX フラグを指定してバッファを作成しようとすると、マルチチャンネル ウェーブ フォーマットは失敗する。

マルチチャンネル ウェーブ フォーマットの詳細については、http://www.microsoft.com/hwdev/audio/multichaud.htm から入手可能な『Enhanced Audio Formats for Multi-Channel Configurations and High-Bit Resolution』を参照すること。


ウェーブ ファイルの読み込み

ここでは、DirectMusic ローダーおよびパフォーマンスを使用せずに、ウェーブ ファイルのデータを DirectSound バッファにロードする方法について説明する。ほとんどのアプリケーションでは、ウェーブ データやバッファを直接処理する必要はない。ウェーブのロードや再生の優先される方法については、「オーディオ データのロード」および「サウンドの再生」を参照すること。

ウェーブ ファイルは RIFF (Resource Interchange File Format、リソース交換ファイル フォーマット) を採用しており、ヘッダー情報 (たとえばサウンド サンプルのウェーブ フォーマット) とデータ (サンプル自体) を保持する、任意の数のチャンクによって構成されている。Win32 API は、RIFF ファイルを開いたり閉じたりするための関数や、チャンクの検索関数などを提供する。これらの関数の名前はすべて "mmio" で始まる。

DirectSound API は、ウェーブ ファイルを処理するためのメソッドを備えていない。ただし、多くの SDK サンプル アプリケーションで使用される Dsutil.cpp ファイルは、次のパブリック メソッドを持つ CWaveFile クラスを実装する。

  • Open。読み込みのためにファイルを開いてウェーブ フォーマットを取得したり、書き込みのためにファイルを開いてヘッダー チャンクを書き込む。
  • GetSize。Open が呼び出された後、データ チャンクのサイズを返す。
  • Read。データ チャンクの一部をバッファにコピーし、読み込みカーソルを進める。
  • Write。バッファからデータ チャンクに書き込み、書き込みカーソルを進める。
  • ResetFile。読み込みカーソルと書き込みカーソルをデータ チャンクの先頭に設定する。
  • Close。ファイルを閉じる。

ウェーブ ファイルを読み込む最初のステップは、CWaveFile::Open メソッドを呼び出すことである。このメソッドは、ファイルが RIFF フォーマットであることを確認し、ウェーブ フォーマットに関する情報を取得する。パラメータはファイル名、フォーマットの NULL、および WAVEFILE_READ フラグである。このメソッドは HRESULT を返す。

次のコードは、ウェーブ ファイルを開く。

CWaveFile waveFile;

if (FAILED(waveFile.Open("mywave.wav", NULL, WAVEFILE_READ)))
{
    waveFile.Close();
}

これで、アプリケーションはファイルからセカンダリ バッファへのコピーを開始できる。通常は、ウェーブのフォーマットを取得するまではサウンド バッファを作成しない。次のコードは、ファイル内の全データを保持するのにちょうどよいサイズのスタティック バッファを作成する。

LPDIRECTSOUNDBUFFER  lpdsbStatic;
DSBUFFERDESC         dsbdesc;

memset(&dsbdesc, 0, sizeof(DSBUFFERDESC));
dsbdesc.dwSize = sizeof(DSBUFFERDESC);
dsbdesc.dwFlags = 0;

/* ウェーブ フォーマットとデータ チャンクのサイズは、
// CWaveFile::Open が呼び出された後、CWaveFile に格納される。

dsbdesc.dwBufferBytes = waveFile.GetSize();
dsbdesc.lpwfxFormat = waveFile.m_pwfx;

// lpds は有効な IDirectSound8 ポインタである。

if FAILED(lpds->CreateSoundBuffer(&dsbdesc, &lpdsbStatic, NULL))
{
    // エラー処理。
    .
    .
    .
}

これで、バッファにデータを書き込むことができる。この場合、アプリケーションはデータのストリーミングを行わないので、バッファ全体が先頭からロックされる。ラップアラウンド (先頭へ戻る) も発生しないので、必要なのは 1 つのポインタとバイト カウントである。

LPVOID lpvAudio1;
DWORD  dwBytes1;

if FAILED(lpdsbStatic->Lock(
        0,              // ロック開始のオフセット。
        0,              // ロックのサイズ。この場合は無視される。
        &lpvAudio1,     // ロック開始のアドレス。
        &dwBytes1,      // ロックされるバイト数。
        NULL,           // ラップアラウンドの開始。使用されない。
        NULL,           // ラップアラウンドのサイズ。使用されない。
        DSBLOCK_ENTIREBUFFER))
{
    // エラー処理。
    .
    .
    .
}

CWaveFile::Read メソッドを使って、次のようにバッファに書き込むことができる。

DWORD dwBytesRead;

waveFile.Read((BYTE*)lpvAudio1, dwBytes1, &dwBytesRead);

最後にアプリケーションはバッファをアンロックし、ウェーブ ファイルを閉じる。

lpdsbStatic->Unlock(lpvAudio1, dwBytes1, NULL, 0);
waveFile.Close();

ストリーム バッファの場合は、通常、再生カーソルの動きによって決定される一定の間隔で CWaveFile::Read を呼び出す。バッファのロックされた部分がラップ アラウンドしている場合は、ロックの各セグメントごとにこのメソッドを呼び出す。

ストリーミングの詳細については、「ストリーム バッファの使い方」および「再生バッファの通知」を参照すること。

CWaveFile クラスの使い方のその他の例については、DirectX SDK インストールに含まれるサンプル アプリケーションを参照すること。


リソースからのウェーブ データの読み込み

DirectSound API は、リソースからウェーブを読み込むメソッドを備えていない。ただし、多くの SDK サンプル アプリケーションで使用される Dsutil.cpp ファイルは、リソースとして格納されたウェーブおよびウェーブ ファイルを読み込むことができる CWaveFile クラスを実装する。

実行可能ファイルにウェーブ サウンドを保存するには、ウェーブ ファイルをリソースとしてインポートし、文字列の名前を割り当てる。CWaveFile では、これらのリソースが "WAVE" または "WAV" タイプであり、DLL ではなく実行可能モジュールに含まれていることを想定している。

次のコードは、"mywave" で識別されるリソースを開く。

CWaveFile waveFile;

if (FAILED(waveFile.Open("mywave", NULL, WAVEFILE_READ)))
{
    waveFile.Close();
}

開いたリソースは、ファイルと同様に読み込むことができる。CWaveFile クラスを使ったこの処理の詳細については、「ウェーブ ファイルの読み込み」を参照すること。


DirectSound でのエフェクトの使い方

純粋な DirectSound アプリケーションでのエフェクトの再生は、基本的には DirectMusic のパフォーマンスおよびオーディオパスを使用するアプリケーションの場合と同様に処理される。詳細については、「エフェクトの使い方」を参照すること。DirectSound アプリケーションにはオーディオパスがないので、常にバッファを直接操作する。

エフェクトを使用するには、DirectSound アプリケーションは CoInitialize を呼び出して COM を初期化する必要がある。この処理は、DirectSoundCreate8 による DirectSound オブジェクトの作成を排除しない。

バッファがあまり小さいと、エフェクトがうまく動作しない。DirectSound では、DSBSIZE_FX_MIN ミリ秒以下のデータしか保持できないエフェクト使用可能なバッファは作成できない。

DSBUFFERDESC 構造体の DSBCAPS_CTRLFX フラグを設定して、DMO を保持できるセカンダリ バッファを作成する。

セカンダリ サウンド バッファでエフェクトを実装するには、IDirectSoundBuffer8::SetFX を使う。

エフェクトのインターフェイスを取得するには、IDirectSoundBuffer8::GetObjectInPath を使う。このメソッドは、IDirectMusicAudioPath8::GetObjectInPath や IDirectMusicSegmentState8::GetObjectInPath とは異なり、dwStage パラメータを取らない。これは、バッファから取得できるオブジェクトは DMO だけだからである。


サウンド キャプチャ

ここでは、DirectMusic および DirectSoundCapture オブジェクトを使ったサウンドのキャプチャについて説明する。説明するトピックは、次のとおりである。

  • MIDI のキャプチャ
  • ウェーブのキャプチャ


MIDI のキャプチャ

キーボードなどのデバイスから MIDI メッセージをキャプチャするには、キャプチャ デバイスのポートを作成し、IDirectMusicPort8::SetReadNotificationHandle メソッドを使って、読み込むメッセージがあるときに常にイベントを通知させる。イベントに応答して、IDirectMusicPort8::Read メソッドの呼び出しを S_FALSE が返されるまで繰り返し、未処理のイベントをバッファに置く。Read が呼び出されるたびに、利用可能なだけのイベント、またはバッファに収まるだけのイベントがバッファに置かれる。少なくとも 1 つのイベントがバッファに置かれると、S_OK が返される。

バッファからイベントを取得するには、IDirectMusicBuffer8::GetNextEvent メソッドを呼び出す。S_FALSE が返されて利用可能なイベントがなくなるまで、呼び出しごとに 1 つのイベントを取得する。

次のサンプル コードは、この処理を示している。hEvent が CreateEvent によって作成され、SetReadNotificationHandle の呼び出しによってキャプチャ ポート pPort に与えられたと仮定する。また、pBuffer が IDirectMusic8::CreateMusicBuffer によって初期化されたと仮定する。

REFERENCE_TIME rt;
DWORD          dwGroup;
DWORD          cb;
BYTE          *pb;

DWORD dw = WaitForMultipleObjects(1, hEvent, FALSE, INFINITE);
for (;;)
{
    hr = pPort->Read(pBuffer);
    if (hr == S_FALSE)
      {
          break;  // これ以上バッファに読み込むメッセージがない。
      }
    pBuffer->ResetReadPtr();
    for (;;)
    {
        hr = pBuffer->GetNextEvent(&rt, &dwGroup, &cb, &pb);
        if (hr == S_OK)
        {
            // pb はメッセージのデータ構造体を指す。
            // ポインタを使って、必要な操作を実行できる。
        }
        else if (hr == S_FALSE)
        {
            break;  // バッファにはメッセージが残っていない。
        }
    }  // バッファの操作が終了。
}  // 未処理のイベントの読み込みが終了。

途中でメッセージを処理せずに、単にメッセージをポートからポートに送信する場合は、IDirectMusicThru8 インターフェイスを使用する。詳細については、「IDirectMusicThru8::ThruChannel」を参照すること。


ウェーブのキャプチャ

DrectSoundCapture オブジェクト (IDirectSoundCapture8) は、サウンド キャプチャ デバイスの能力の問い合わせや、入力ソースからオーディオをキャプチャするためのバッファの作成に使われる。DirectSoundCapture を使うと、PCM フォーマットまたは圧縮フォーマットでデータをキャプチャできる。

DirectSound キャプチャ バッファ オブジェクト (IDirectSoundCaptureBuffer8) は、入力デバイスからのデータを受け取るためのバッファを表す。再生バッファと同様、このバッファは循環という概念を採用している。入力ポインタがバッファの最後に到達すると、自動的に開始点に戻る。

IDirectSoundCaptureBuffer8 オブジェクトのメソッドを使うと、バッファのプロパティの取得、オーディオ キャプチャの開始と停止、メモリの一部のロックができるので、ファイルに保存するなどの目的でデータを安全に取得できる。エフェクトのキャプチャをサポートするオペレーティング システムでは、DMO を取得したり、エフェクトのステータスを確認するメソッドも提供する。

ウェーブのキャプチャの詳細については、次のトピックを参照すること。

  • キャプチャ デバイスの列挙
  • DirectSoundCapture オブジェクトの作成
  • キャプチャ デバイスの能力
  • キャプチャ バッファの作成
  • キャプチャ バッファの情報
  • キャプチャ バッファの通知
  • キャプチャ バッファのエフェクト
  • キャプチャ バッファの使い方
  • ウェーブ ファイルへの書き込み


キャプチャ デバイスの列挙

ユーザーが優先するキャプチャ デバイスでサウンドをキャプチャするだけのアプリケーションでは、利用可能なデバイスを列挙する必要はない。NULL または定義済みの GUID を DirectSoundCaptureCreate8 または DirectSoundFullDuplexCreate8 に渡すことによって、デフォルトのデバイスを作成できる。詳細については、「DirectSoundCapture オブジェクトの作成」を参照すること。

特定の種類のデバイスを探している場合や、複数のデバイスを使って動作する必要がある場合は、システム上で利用可能なデバイスを列挙しなければならない。

列挙は 3 つの目的で使われる。

  • 利用可能なハードウェアを報告。
  • 各デバイスに GUID を供給。
  • 各デバイスを列挙したときに、各デバイスを初期化。その結果、各デバイスの能力をチェックできる。

デバイスを列挙するには、DirectSound がデバイスを見つけるたびに呼び出すコールバック関数を最初に作成しなければならない。必要なすべての処理をこの関数内で実行し、関数に任意の名前を付けることができるが、この関数はプロトタイプである DSEnumCallback と同じ形式で宣言しなければならない。このコールバック関数は、列挙を続ける場合は TRUE、その他 (たとえば必要な能力を備えたデバイスを見つけた後など) の場合は FALSE を返さなければならない。

コールバック関数の例については、「サウンド デバイスの列挙」を参照すること。各デバイスの GUID が、この関数に渡されるパラメータの 1 つとして取得される点に注意すること。

列挙は DirectSoundCaptureEnumerate 関数を使うことにより動作に移される。

DWORD pv;  // 任意の 32 ビット型。

HRESULT hr = DirectSoundCaptureEnumerate(
        (LPDSENUMCALLBACK)DSEnumProc,
        (VOID*)&pv);


DirectSoundCapture オブジェクトの作成

DirectSoundCapture オブジェクトを作成するには、DirectSoundCaptureCreate8 または DirectSoundFullDuplexCreate8 関数を呼び出す。これらの関数はいずれも、IDirectSoundCapture8 インターフェイスへのポインタを取得する。

DirectSoundCaptureCreate に対する lpcGUID パラメータや、DirectSoundFullDuplexCreate8 に対する pcGuidRenderDevice パラメータには、列挙によって取得される GUID または次のいずれかの定義済み GUID を指定できる。

DSDEVID_DefaultCapture
デフォルトのシステム キャプチャ デバイス。デバイスの GUID パラメータで NULL ポインタを渡すことによって、このデバイスを指定することもできる。
DSDEVID_DefaultVoiceCapture
デフォルトの音声通信キャプチャ デバイス。これは、通常、USB マイク付きヘッドセットなどのセカンダリ デバイスである。

デバイス ドライバが存在しない場合は、この呼び出しは失敗する。

CoCreateInstance 関数を使ってオブジェクトを作成することもできる。その手順は、DirectSound オブジェクトを作成する手順と同様である。「DirectSound オブジェクトの作成」を参照すること。CoCreateInstance を使う場合、コントロール パネルでユーザーが選択したデフォルトのキャプチャ デバイスに対応するオブジェクトが作成される。

DirectSound オブジェクトと DirectSoundCapture オブジェクトを共存させたい場合は、DirectSoundCapture オブジェクトの作成と初期化を行う前に、DirectSound オブジェクトの作成と初期化を行うか、DirectSoundFullDuplexCreate8 を使う。

オーディオ機器によっては、デフォルトで全二重オーディオ構成になっていないものもある。DirectSound オブジェクトと DirectSoundCapture オブジェクトの作成と初期化の際に問題が発生した場合は、ユーザーに対してオーディオ デバイス プロパティのチェックと、全二重オーディオが有効になっていることの確認を求めなければならない。


キャプチャ デバイスの能力

キャプチャ デバイスの能力を取得するには、IDirectSoundCapture8::GetCaps メソッドを呼び出す。このメソッドのパラメータは、DSCCAPS 構造体へのポインタである。ほかの構造体と同様、この引数を渡す前に dwSize メンバを初期化しておかなければならない。戻り値として、この構造体はこのデバイスがサポートするチャンネル数、およびサポートされるフォーマットに関する値の組み合わせを保持する。後者の値は、Win32 ウェーブフォーム オーディオ関数で使われている WAVEINCAPS 構造体の値と同等である。

非 WDM ドライバでは、キャプチャ デバイスは一度に 1 つのアプリケーションでのみ使用できる。ドライバが、複数のアプリケーションによるデバイスの同時使用をサポートしている場合は、DSCCAPS の dwFlags メンバに DSCCAPS_MULTIPLECAPTURE が返される。各アプリケーションは、キャプチャ バッファについてそれぞれのフォーマットを設定できる。


キャプチャ バッファの作成

キャプチャ バッファを作成するには、IDirectSoundCapture8::CreateCaptureBuffer メソッドを呼び出す。

このメソッドに渡されるパラメータの 1 つは DSCBUFFERDESC 構造体であり、これは希望のバッファの特性を記述している。この構造体の最後のメンバは、WAVEFORMATEX 構造体であるが、目的のウェーブ フォーマットの詳細に従ってこの構造体を初期化しなければならない。

アプリケーションが DirectSound と DirectSoundCapture の両方を使う場合、キャプチャ バッファのフォーマットがプライマリ バッファのフォーマットと異なっていると、キャプチャ バッファの作成は失敗する。一部のカードはクロックを 1 つしか用意していないため、2 つの異なった周波数でキャプチャと再生を行えないのが原因である。

次の例では、およそ 1 秒分のデータを保持するキャプチャ バッファを設定する。

// pDSC は有効な IDirectSoundCapture8 インターフェイス ポインタである。

DSCBUFFERDESC              dscbd;
LPDIRECTSOUNDCAPTUREBUFFER pDSCB;
WAVEFORMATEX               wfx =
    {WAVE_FORMAT_PCM, 2, 44100, 176400, 4, 16, 0};

    // wFormatTag、nChannels、nSamplesPerSec、mAvgBytesPerSec、
    // nBlockAlign、wBitsPerSample、cbSize

dscbd.dwSize = sizeof(DSCBUFFERDESC);
dscbd.dwFlags = 0;
dscbd.dwBufferBytes = wfx.nAvgBytesPerSec;
dscbd.dwReserved = 0;
dscbd.lpwfxFormat = &wfx;
dscbd.dwFXCount = 0;
dscbd.lpDSCFXDesc = NULL;

pDSCB = NULL;

HRESULT hr = pDSC->CreateCaptureBuffer(&dscbd,
        &pDSCB, NULL);


キャプチャ バッファの情報

キャプチャ バッファのサイズを取得するには、IDirectSoundCaptureBuffer8::GetCaps メソッドを使う。この構造体をパラメータとして渡す前に、DSCBCAPS 構造体の dwSize メンバを初期化しておかなければならない。

バッファ作成時に設定された、バッファ内のデータ形式の情報を取得することもできる。IDirectSoundCaptureBuffer8::GetFormat メソッドを呼び出すと、このメソッドは WAVEFORMATEX 構造体を使ってフォーマット情報を返す。

lpwfxFormat パラメータで NULL を指定して GetFormat メソッドを最初に呼び出すことにより、アプリケーションが WAVEFORMATEX 構造体を通して追加のフォーマット情報を入手できる点に注意すること。この場合、lpdwSizeWritten パラメータが指す DWORD が、完全なフォーマット情報を受け取るのに必要な構造体のサイズを受け取る。

キャプチャ バッファが現在行っていることを把握するには、IDirectSoundCaptureBuffer8::GetStatus メソッドを呼び出す。このメソッドはフラグの組み合わせを変数 DWORD に書き込むが、そのフラグはバッファがキャプチャリングでビジーであるかどうか、ビジーの場合はループしているかどうか (つまり IDirectSoundCaptureBuffer8::Start を直前に呼び出した時点で DSCBSTART_LOOPING フラグを設定していたか) を示す。

最後に、IDirectSoundCaptureBuffer8::GetCurrentPosition メソッドは、バッファ内での現在の読み込みカーソルとキャプチャ カーソルのオフセットを返す。読み込みカーソルは、この時点で完全にキャプチャされてバッファに置かれたデータの最後である。キャプチャ カーソルは、現在ハードウェアからコピーされている最中のデータ ブロックの最後である。バッファから安全にコピーできるのは読み込みカーソルまでのデータのみである。


キャプチャ バッファの通知

読み込みカーソルがバッファ内のある位置または最後に達したときに、アプリケーションへの通知を発生させたいことがある。バッファ内での読み込みカーソルまでの部分は、安全にデータを読み込むことができる。IDirectSoundNotify8::SetNotificationPositions メソッドを使うと、イベントのシグナルを送信するポイントをバッファ内にいくつでも設定できる。

まず、IDirectSoundNotify8 インターフェイスへのポインタを取得する。「再生バッファの通知」で説明したとおり、キャプチャ バッファの QueryInterface メソッドを使ってこれを取得することができる。

次に、Win32 の CreateEvent 関数を使って、イベント オブジェクトを作成する。このイベントへのハンドルを DSBPOSITIONNOTIFY 構造体の hEventNotify メンバに書き込み、この構造体の dwOffset メンバで、バッファ内でイベントのシグナルを送信したい位置のオフセットを指定する。次にこの構造体のアドレスを、または複数の通知位置を設定したい場合は構造体の配列を、IDirectSoundNotify8::SetNotificationPositions メソッドに渡す。

次の例は、3 つの通知位置を設定する。1 つのイベントは読み込み位置がバッファ内の中央に達したとき、2 番目は最後の近くに達したとき、3 番目はキャプチャが停止したときに、それぞれシグナルを送信する。

#define cEvents  3

// 以下の変数は正しく初期化され、
// バッファの作成時に、バッファ記述に wfx が含まれていると
// 仮定している。
//   LPDIRECTSOUNDNOTIFY8 lpDsNotify;
//   WAVEFORMATEX          wfx;

HANDLE             rghEvent[cEvents] = {0};
DSBPOSITIONNOTIFY  rgdsbpn[cEvents];
HRESULT            hr;
int                i;

// イベントを作成する。
for (i = 0; i < cEvents; ++i)
{
    rghEvent[i] = CreateEvent(NULL, TRUE, FALSE, NULL);
    if (NULL == rghEvent[i])
    {
        hr = GetLastError();
        goto Error;
    }
}

// 通知を記述する。

rgdsbpn[0].dwOffset = (wfx.nAvgBytesPerSec/2) -1;
rgdsbpn[0].hEventNotify = rghEvent[0];

rgdsbpn[1].dwOffset = wfx.nAvgBytesPerSec - 1;
rgdsbpn[1].hEventNotify = rghEvent[1];

rgdsbpn[2].dwOffset = DSBPN_OFFSETSTOP;
rgdsbpn[2].hEventNotify = rghEvent[2];

// 通知を作成する。

hr = lpDsNotify->SetNotificationPositions(cEvents, rgdsbpn);


キャプチャ バッファのエフェクト

キャプチャ バッファのエフェクトは、現在のオペレーティング システムでは利用できない。

キャプチャ バッファのエフェクトを設定するには、IDirectSoundCapture8::CreateCaptureBuffer に渡される DSCBUFFERDESC 構造体にエフェクトを記述する。作成されたバッファの情報を取得するには、IDirectSoundCaptureBuffer8::GetFXStatus を使う。

DirectX 8.0 でサポートされているキャプチャ エフェクトのインターフェイスには次のものがあり、これらのインターフェイスを使ってパラメータを設定および取得する。

  • IDirectSoundCaptureFXAec8
  • IDirectSoundCaptureFXNoiseSuppress8

これらのインターフェイスをキャプチャ バッファ オブジェクトから取得するには、IDirectSoundCaptureBuffer8::GetObjectInPath を使う。


キャプチャ バッファの使い方

サウンドのキャプチャは、次のステップで構成される。

  1. IDirectSoundCaptureBuffer8::Start メソッドを呼び出してバッファリングを開始する。入力デバイスから得たオーディオ データを、バッファの開始位置以降に書き込む。
  2. 希望の量のデータが利用可能になるまで待つ。キャプチャ カーソルが特定の地点に達する時期を決定する方法の 1 つについては、「キャプチャ バッファの通知」を参照すること。
  3. 十分なデータが利用可能になったとき、IDirectSoundCaptureBuffer8::Lock メソッドを呼び出してキャプチャ バッファの一部をロックする。

    ロックを試みる部分が、キャプチャに使われようとしているメモリ部分と重なっていないことを確認するには、最初に IDirectSoundCaptureBuffer8::GetCurrentPosition を呼び出して現在の読み込みカーソルの位置を取得する。読み込みカーソルについては、「キャプチャ バッファの情報」を参照すること。

    Lock メソッドのパラメータとして、読み込みたいメモリ ブロックのサイズとオフセットを渡す。このメソッドは、メモリ ブロック開始位置のアドレスへのポインタと、ブロックのサイズを返す。ブロックがバッファの最後から最初へラップ アラウンドしている (先頭へ戻っている) 場合、ブロックのセクションごとに 1 つ、合計 2 つのポインタが返される。バッファのロック部分がラップ アラウンドしていない場合は、2 番目のポインタは NULL である。

  4. Lock メソッドが返したアドレスとブロック サイズを使って、バッファからデータをコピーする。
  5. IDirectSoundCaptureBuffer8::Unlock メソッドを使って、バッファをアンロックする。
  6. 全データのキャプチャが終わるまで、ステップ 2 から 5 を繰り返す。次に、IDirectSoundCaptureBuffer8::Stop メソッドを呼び出す。

通常、キャプチャ カーソルがバッファの最後に達すると、バッファはキャプチャリングを自動的に停止する。しかし、IDirectSoundCaptureBuffer8::Start メソッドに渡す dwFlags パラメータで DSCBSTART_LOOPING フラグを設定した場合は、アプリケーションが IDirectSoundCaptureBuffer8::Stop メソッドを呼び出すまでキャプチャは続行される。


ウェーブ ファイルへの書き込み

DirectSound API は、ウェーブ ファイルへの書き込みのためのメソッドを備えていない。ただし、多くの SDK サンプル アプリケーションで使用される Dsutil.cpp ファイルは、次のパブリック メソッドを持つ CWaveFile クラスを実装する。

  • Open。書き込みのためにファイルを開いてウェーブ フォーマットを取得したり、書き込みのためにファイルを開いてヘッダー チャンクを書き込む。
  • GetSize。Open または ResetFile が呼び出された後、データ チャンクのサイズを返す。
  • Read。データ チャンクの一部をバッファにコピーし、読み込みカーソルを進める。
  • Write。バッファからデータ チャンクに書き込み、書き込みカーソルを進める。
  • ResetFile。読み込みカーソルと書き込みカーソルをデータ チャンクの先頭に設定する。
  • Close。ファイルを閉じる。

ウェーブ ファイルを書き込む最初のステップは、CWaveFile::Open メソッドを呼び出すことである。このメソッドは、ファイルを作成し、ウェーブ フォーマット チャンクを書き込む。パラメータは、ファイル名、初期化された WAVEFORMATEX 構造体へのポインタ、および WAVEFILE_WRITE フラグである。このメソッドは HRESULT を返す。

次のコードは、書き込みのためにウェーブ ファイルを開く。

CWaveFile     g_pWaveFile;
WAVEFORMATEX  wfxInput;

ZeroMemory( &wfxInput, sizeof(wfxInput));
wfxInput.wFormatTag = WAVE_FORMAT_PCM;
wfxInput.nSamplesPerSec = 22050
wfxInput.wBitsPerSample =  8;
wfxInput.nChannels = 1;
wfxInput.nBlockAlign =
    wfxInput.nChannels * (wfxInput.wBitsPerSample / 8);
wfxInput.nAvgBytesPerSec =
    wfxInput.nBlockAlign * wfxInput.nSamplesPerSec;

g_pWaveFile = new CWaveFile;
if (FAILED(g_pWaveFile->Open("mywave.wav", &wfxInput,
        WAVEFILE_WRITE)))
{
    g_pWaveFile->Close();
}

これで、アプリケーションはキャプチャ バッファからファイルへのコピーを開始できる。次の関数は、読み込みカーソルが通知位置に到達するたびに呼び出される。次のグローバル変数が使用される。

  • g_pDSBCapture は、キャプチャ バッファの IDirectSoundCapture インターフェイスへのポインタである。
  • g_dwNextCaptureOffset は、ファイルにコピーされる次のデータ ブロックのバッファ オフセットを記録する。
  • g_dwCaptureBufferSize は、キャプチャ バッファのサイズであり、ラップアラウンドの計算に使用される。
HRESULT RecordCapturedData()
{
    HRESULT hr;
    VOID*   pbCaptureData    = NULL;
    DWORD   dwCaptureLength;
    VOID*   pbCaptureData2   = NULL;
    DWORD   dwCaptureLength2;
    VOID*   pbPlayData       = NULL;
    UINT    dwDataWrote;
    DWORD   dwReadPos;
    LONG lLockSize;

    if (NULL == g_pDSBCapture)
        return S_FALSE;
    if (NULL == g_pWaveFile)
        return S_FALSE;

    if (FAILED( hr = g_pDSBCapture->GetCurrentPosition(
            NULL, &dwReadPos)))
        return hr;

    // プライベート カーソルと読み込みカーソルの間を
    // すべてロックして、ラップアラウンドを可能にする。

    lLockSize = dwReadPos - g_dwNextCaptureOffset;
    if( lLockSize < 0 )
        lLockSize += g_dwCaptureBufferSize;

    if( lLockSize == 0 )
        return S_FALSE;

    if (FAILED(hr = g_pDSBCapture->Lock(
            g_dwNextCaptureOffset, lLockSize,
            &pbCaptureData, &dwCaptureLength,
            &pbCaptureData2, &dwCaptureLength2, 0L)))
    return hr;

    // データを書き込む。これは 2 つのステップで行われ、
    // ラップアラウンドが計算される。

    if (FAILED( hr = g_pWaveFile->Write( dwCaptureLength,
            (BYTE*)pbCaptureData, &dwDataWrote)))
        return hr;

    if (pbCaptureData2 != NULL)
    {
        if (FAILED(hr = g_pWaveFile->Write(
                dwCaptureLength2, (BYTE*)pbCaptureData2,
                &dwDataWrote)))
                return hr;
    }

    // キャプチャ バッファをアンロックする。

   g_pDSBCapture->Unlock( pbCaptureData, dwCaptureLength,
            pbCaptureData2, dwCaptureLength2  );

    // キャプチャ オフセットを移動する。

    g_dwNextCaptureOffset += dwCaptureLength;
    g_dwNextCaptureOffset %= g_dwCaptureBufferSize;
    g_dwNextCaptureOffset += dwCaptureLength2;
    g_dwNextCaptureOffset %= g_dwCaptureBufferSize;

    return S_OK;
}

キャプチャが終了すると、アプリケーションはウェーブ ファイルを閉じる。

g_pWaveFile->Close();

CWaveFile::Close メソッドは、ファイルを閉じる前に、チャンク サイズをファイルに書き込む。


DirectX Audio の高度なトピック

ここでは、「DirectX Audio の使い方」で記述されている機能よりも高度な機能を必要とする特殊なアプリケーションについて説明する。

説明するトピックは、次のとおりである。

  • DirectMusic トラック
  • DirectMusic メッセージの使い方
  • DirectMusic ポートの使い方
  • カスタム ロード
  • 音色コレクションの使い方
  • 下位レベル DLS
  • DirectMusic ツール
  • プロパティ セット
  • DirectSound の性能の最適化
  • プライマリ バッファへの書き込み


DirectMusic トラック

トラックはセグメントのコンポーネントで、シーケンス化されたデータが含まれる。データには、ノート、ベース コード、テンポ、パッチ チェンジ、バンド チェンジ、およびパフォーマンスがサウンドを演奏するときに知っておく必要がある、その他すべてに関する情報が含まれる。

各トラックは、IDirectMusicTrack8 インターフェイスによって表される。このインターフェイスのメソッドはパフォーマンスによって呼び出され、ほとんどのアプリケーションでは、直接使用する必要はない。このインターフェイスは、主に、独自のタイプのトラックを実装するプラグイン コンポーネントで使用する。

アプリケーションが IDirectMusicPerformance8::PlaySegment または IDirectMusicPerformance8::PlaySegmentEx を呼び出すと、DirectMusic はそのセグメントのトラックについて IDirectMusicTrack8::Play または IDirectMusicTrack8::PlayEx メソッドを呼び出す。ほとんどのトラックは、演奏されているセグメントのパートに対して有効なデータを含む、タイムスタンプ メッセージを直ちに生成する。これらのメッセージはキューに格納される。その後の動作については、「メッセージの作成と配信」を参照すること。

いくつかのトラックでは、IDirectMusicTrack8::Play や IDirectMusicTrack8::PlayEx に対して通知以外のメッセージは生成されないが、代わりにパフォーマンスやほかのトラックからの情報の要求に応答する。最も重要なものとして、コード、ミュート、およびコマンドの各トラックがある。テンポ トラックはメッセージを送信するが、パラメータの要求にも応答する。

詳細については、次のトピックを参照すること。

  • 標準トラックの種類
  • トラック構成


標準トラックの種類

次のリストは、Microsoft® DirectMusic® で実装される標準トラックの種類を示している。CLSID_DirectMusicBandTrack などのクラス識別子は、さまざまなメソッドの呼び出しでのトラックの種類を識別するために使用する。

トラックの種類 | クラス GUID | 目的
バンド | CLSID_DirectMusicBandTrack | DLS データをパフォーマンスにダウンロードする。DMUS_PATCH_PMSG、DMUS_TRANSPOSE_PMSG、DMUS_CHANNEL_PRIORITY_PMSG、および DMUS_MIDI_PMSG 型のメッセージを送信する (ボリュームおよびパン用)。MIDI ファイルおよびスタイルに基づくセグメントで使用される。
コード | CLSID_DirectMusicChordTrack | パターン内のミュージック値を、MIDI 値に変換するために使用される。DMUS_NOTIFICATION_PMSG 型のメッセージを送信する (GUID_NOTIFICATION_CHORD 通知用)。
コードマップ | CLSID_DirectMusicChordMapTrack | コード トラックを作成するために、テンプレート セグメントで使用される。
コマンド | CLSID_DirectMusicCommandTrack | テンプレート セグメントでコード トラックを作成するため、およびスタイル セグメントで演奏するパターンを決定するために使用される。GUID_NOTIFICATION_COMMAND 通知用の DMUS_NOTIFICATION_PMSG 型のメッセージを送信する。
歌詞 | CLSID_DirectMusicLyricsTrack | 単語とミュージックを同期させるために使用される。DMUS_LYRIC_PMSG 型のメッセージを生成する。
マーカー | CLSID_DirectMusicMarkerTrack | フロー制御に使用される。マーカー トラックは、セグメントの開始タイム、および新しいセグメントにキューを与えることができる演奏タイムを保持できる。詳細については、「セグメントのタイミング」を参照すること。
モチーフ | CLSID_DirectMusicMotifTrack | ほかのセグメントと共にモチーフを演奏するために使用する。DMUS_CURVE_PMSG、DMUS_NOTE_PMSG、および DMUS_NOTIFICATION_PMSG 型のメッセージを送信する (GUID_NOTIFICATION_MEASUREANDBEAT の通知用)。
ミュート | CLSID_DirectMusicMuteTrack | パフォーマンス チャンネルを再マップまたはミュートできるようにする。スタイル ベースのセグメント、または MIDI ベースのセグメントと共に使用する。
パラメータ制御 | CLSID_DirectMusicParamControlTrack | ツール、エフェクト、および IMediaParams インターフェイスをサポートするその他のオブジェクトの設定を制御する。
パターン | CLSID_DirectMusicPatternTrack | 単一のミュージック パターンを含む。パターン トラックはシーケンス トラックと似ているが、固定されたノートではなくミュージック値を含む。このトラックはさまざまなコードについてパターンのオーディションを実行できるようにし、多くの場合ミュージック オーサリング アプリケーションで使用される。伴奏を演奏するためにも使用される。このトラックは、独自のインターフェイス IDirectMusicPatternTrack8 によって表される。
スクリプト | CLSID_DirectMusicScriptTrack | オーディオ スクリプトでルーチンを呼び出す。
セグメント トリガ | CLSID_DirectMusicSegmentTriggerTrack | セグメントの再生をトリガする。このトラックを使用すると、アプリケーション開発者に委ねるのではなく、ファイルのオーサーがセグメント内からセグメントにキューを与えることができる。
シーケンス | CLSID_DirectMusicSeqTrack | DMUS_NOTE_PMSG および DMUS_MIDI_PMSG 型のシーケンス メッセージを送信する。MIDI ファイルに基づくセグメントで使用される。.sgt 形式で保存されたセグメントに対し、DMUS_CURVE_PMSG 型のメッセージを送信する。
サインポスト | CLSID_DirectMusicSignPostTrack | コード トラックを作成するために、テンプレート セグメントで使用される。
スタイル | CLSID_DirectMusicStyleTrack | スタイルに基づくセグメントの基本的なトラック。DMUS_TIMESIG_PMSG、DMUS_CURVE_PMSG、DMUS_NOTE_PMSG、および DMUS_NOTIFICATION_PMSG 型のメッセージを送信する (GUID_NOTIFICATION_MEASUREANDBEAT の通知用)。
システム エクスクルーシブ | CLSID_DirectMusicSysExTrack | DMUS_SYSEX_PMSG 型のシステム エクスクルーシブ メッセージを送信する。MIDI ファイルに基づくセグメントで使用される。
テンポ | CLSID_DirectMusicTempoTrack | パフォーマンスのテンポを制御する。
拍子記号 | CLSID_DirectMusicTimeSigTrack | GUID_NOTIFICATION_MEASUREANDBEAT 通知と同様に、DMUS_TIMESIG_PMSG 型のメッセージを送信する。拍子記号トラックは、インポートされた MIDI ファイルおよびそれを使って作成されるセグメント内に存在する。ほとんどの場合、スタイル トラックは拍子記号トラックの機能を実装する。そのため、スタイル トラックを含んでいるセグメントが拍子記号トラックも含んでいる必要はない。
ウェーブ | CLSID_DirectMusicWaveTrack | タイムスタンプ付きのウェーブ メッセージを演奏するために、DMUS_WAVE_PMSG 型のメッセージを送信する。


トラック構成

IDirectMusicSegment8::SetTrackConfig と IDirectMusicSegmentState8::SetTrackConfig の各メソッドを使って、アプリケーションでセグメント内の任意のトラックの動作を変更できる。次のような構成オプションがある。

  • 再生を有効または無効にする。
  • 制御セグメント内のトラックについてのパラメータ呼び出しを有効または無効にする。
  • 通知を有効または無効にする。
  • セカンダリ制御セグメントの通知によるプライマリ セグメントの通知をオーバーライドする。
  • トラックのアレンジを有効または無効にする。
  • トランジションのアレンジに使用されるトラック データの開始ポイントを制御する。

トラック構成フラグの一覧および標準トラックで有効なフラグの表については、「IDirectMusicSegmentState8::SetTrackConfig」を参照すること。

DMUS_TRACKCONFIG_CONTROL_PLAY と DMUS_TRACKCONFIG_CONTROL_NOTIFICATION の 2 つの構成フラグは、セカンダリ制御セグメントの機能を拡張する。通常、セカンダリ制御セグメントは、パフォーマンスによって IDirectMusicTrack8::GetParam の呼び出しから取得されたパラメータだけを管理する。ほかのセグメントと同様に、制御セグメントはメッセージを送信することによってパフォーマンスを変更することもできる。たとえば、パフォーマンスのボリュームを変更できる。このような変更はプライマリ セグメントのパラメータをオーバーライドしているように見えるが、実際のコントロールの変更とは 2 つの点で異なる。

  • 別のセグメントによって同様の変更が行われるまで有効である。制御セグメントのパラメータは、ほかのセグメントによってオーバーライドすることはできない。
  • オーバーライドされない限り、送信セグメントの演奏が終了した後も有効のままである。制御セグメントのパラメータは、別のセグメントが制御セグメントになるまで有効である。

トラックについて DMUS_TRACKCONFIG_CONTROL_PLAY または DMUS_TRACKCONFIG_CONTROL_NOTIFICATION フラグが設定されている場合、プライマリ セグメントの対応するトラックは無効になる。制御セグメントが停止すると再び有効になる。

SetTrackConfig メソッドは IDirectMusicSegmentState8 インターフェイスおよび IDirectMusicSegment8 で使用できる。パラメータは同じであるが、その動作は次のように異なる。

  • セグメントのフラグを変更した場合、以降に演奏されるセグメント状態のインスタンスは、変更されたフラグを継承する。ただし、既に演奏中のセグメント状態の動作は変更されない。
  • セグメントのフラグを変更した場合、そのセグメント状態だけは動作が直ちに変更される。

注 セグメント状態のトラック構成が、準備時間の後ではなく、直ちに変更されるようにするには、IDirectMusicPerformance8::Invalidate を呼び出す。

次のサンプル コードでは、pSegment でアドレスが指定されたセグメントのコード進行トラックを無効にしている。コード進行は、制御セグメントのパラメータとしてある要素を全要素にコピーするので、DMUS_TRACKCONFIG_CONTROL_ENABLED フラグをオフにすることによってこの処理を行う。

HRESULT hr = pSegment->SetTrackConfig(CLSID_DirectMusicChordTrack,
        -1, DMUS_SEG_ALLTRACKS, 0, DMUS_TRACKCONFIG_CONTROL_ENABLED);

次の例では、逆に、すべてのコード トラックの演奏を有効にしている。

hr = pSegment->SetTrackConfig(CLSID_DirectMusicChordTrack,
        -1, DMUS_SEG_ALLTRACKS, DMUS_TRACKCONFIG_CONTROL_ENABLED, 0);

関連情報については、次のトピックを参照すること。

  • トラックのアレンジ
  • 制御セグメント
  • 自己制御セグメント


DirectMusic メッセージの使い方

サウンド データは、メッセージの形で DirectMusic パフォーマンスに渡される。ほとんどの場合、メッセージの作成および処理は自動的に行われ、アプリケーションで直接これらの処理をする必要はない。ただし、メッセージの基本的な知識は DirectMusic のしくみを理解するのに役立ち、理解が深まるほど、メッセージを使ってパフォーマンスを細かく制御できるようになる。

DirectMusic では、2 種類のメッセージが使用される。

  • パフォーマンス メッセージ。シーケンス化されたデータはすべて、この形式でパフォーマンス エンジンに渡される。これらのメッセージには、データのタイミングおよびルーティングに関する詳細な情報が含まれている。
  • スタンダード MIDI メッセージ。これらのメッセージは、MIDI ファイルまたはデバイスから読み込まれ、ほかのデバイスに直接渡される (スルーされる) か、再生時にパフォーマンスによってパフォーマンス メッセージ形式に変換される。

アプリケーションは、MIDI メッセージを直接処理しない。セグメントを演奏する場合、そのすべてのデータはパフォーマンス メッセージ形式であり、最終的な出力ツールに渡されるまでその形式のままである。最終的な出力ツールでは、パフォーマンス メッセージを MIDI メッセージ フォーマットに変換した後、シーケンス化してシンセサイザに渡す。ただし、一部のパフォーマンス メッセージには、スタンダード MIDI メッセージと同様の情報が含まれている。このようなメッセージを理解するために、ここでは MIDI メッセージ フォーマットのいくつかの点について説明する。

注 DMUS_MIDI_PMSG 構造体は、スタンダード MIDI メッセージのデータに相当するデータを格納する。ただし、パフォーマンス メッセージである。

ほとんどのパフォーマンス メッセージは、セグメントが演奏されるときに、セグメントのトラックによって送信される。アプリケーションは、メッセージを送信して、MIDI コントローラの設定、単一のノートの演奏、テンポの変更などの処理も行うことができる。

メッセージを送信した後、アプリケーションはツールを実装する方法以外にメッセージを取得または変更できない。たとえば、DirectMusic Producer でオーサリングしたセグメントには、DMUS_LYRIC_PMSG メッセージを生成する歌詞トラックが含まれる場合がある。アプリケーションでこの歌詞を表示する方法は、その目的に合ったツールを実装する方法だけである。詳細については、「DirectMusic ツール」を参照すること。

通知は、メッセージがツールでのみ処理できるという規則の例外である。IDirectMusicPerformance8::GetNotificationPMsg メソッドによって、アプリケーションは DMUS_NOTIFICATION_PMSG メッセージを取得できる。詳細については、「通知とイベントの処理」を参照すること。

次のトピックでは、メッセージとそのルーティング方法について説明する。

  • チャンネル
  • メッセージの作成と配信
  • アプリケーションで作成されたメッセージ
  • パフォーマンス メッセージのタイプ
  • カーブ
  • MIDI メッセージ


チャンネル

チャンネルは、パフォーマンス内の 1 つのパートに固有のメッセージの送信先である。たとえばチャンネルは、音色にサウンドを発生させるノートオン メッセージを受け取ったり、パートに別の音色を割り当てるプログラム チェンジ メッセージを受け取る。「MIDI チャンネル メッセージ」を参照すること。

MIDI 1.0 規格では、16 個の MIDI チャンネルがあり、一度に 16 を超える音色は演奏できないことを意味している。DirectMusic では、この規格に対応すると同時に、アプリケーションがより多くのチャンネルを同時に利用できるように、チャンネル グループが作成される。最大 65,536 個のチャンネル グループが同時に存在し、それぞれに 16 個のチャンネルが含まれるので、チャンネル総数は 100 万以上に上る。特定のポートに、そのポートがサポートする範囲で任意の数のチャンネル グループを割り当てることができる。MIDI ハードウェア ポートには、1 つのチャンネル グループしか割り当てることができない。

システム エクスクルーシブ メッセージは、1 つのチャンネル グループ内の 16 チャンネルのすべてに対して送信できるが、ほかのチャンネル グループ宛てには送信できない。

DirectMusic パフォーマンス内のすべてのパートは、固有のパフォーマンス チャンネル、つまり P チャンネルを持つ。パフォーマンス チャンネルは、特定のポートに対する特定のグループ内の特定の MIDI チャンネルを表す。パフォーマンスがあるバンドを選択すると、そのバンド内の各音色は 1 つのパフォーマンス チャンネルにマップされ、そのチャンネルのパートはその音色で演奏される。

オーディオパスが使用されている場合は、異なるオーディオパス上の同一のパフォーマンス チャンネルが異なる出力チャンネルにマップされる。

チャンネルの優先順位

同時に演奏できるノートの数は、ポートで利用できるボイス数によって制限される。ボイスは、チャンネルで演奏される 1 つのノートまたはウェーブを合成する、リソースのセットである。利用できるボイスの数より多くのノートが演奏される場合は、シンセサイザによって、1 つまたは複数のノートが抑制されなければならない。どのノートを演奏するかは、現在ノートを演奏しているボイスの優先順位によって決定され、これはチャンネルの優先順位に基づく。デフォルトでは、チャンネルはインデックス値に基づいて順位付けされる。ただし、チャンネル 10 は MIDI パーカッション チャンネルで、優先順位は最も高くなる。

アプリケーションおよびシンセサイザでは、独自にチャンネルの優先順位を設定できる。詳細については、IDirectMusicPort8::GetChannelPriority の「注意」を参照すること。「DMUS_CHANNEL_PRIORITY_PMSG」も参照すること。


メッセージの作成と配信

セグメントが演奏されている場合、ほとんどのトラックは、再生中に発生するイベントに関する情報を含むメッセージを生成する。詳細については、「DirectMusic トラック」を参照すること。

数種類のメッセージを送信するトラックもある。たとえば、スタイル トラックはノート メッセージと拍子記号メッセージを送信する。これらの場合、アプリケーションはトラックの特定の種類のメッセージを無効にすることができる。詳細については、「トラック パラメータの無効化と有効化」を参照すること。

パフォーマンス エンジンは、各メッセージをクロック タイムでいつ処理するかを決定する。チャンネル メッセージの場合、パフォーマンスはメッセージを取得するパフォーマンス チャンネルも決定する。この情報は、メッセージ タイプ、ソース トラック、メッセージを受信する最初のツールグラフとツールへのポインタなどを保持するほかのデータと共に、メッセージ構造体に保存される。

テンポや拍子記号の変更などの特定のメッセージは、パフォーマンスによって直ちに処理され、解放される。ノートやパッチの変更など、その他のメッセージはキューに入れられ、タイム スタンプの順に処理される。

注 同じタイム スタンプのメッセージが特定の順序で処理されるという保証はない。

拍子記号メッセージは純粋な情報である。拍子記号はセグメントに組み込まれ、変更できない。

メッセージは、最初にセグメント ツールグラフ内のツール、次にオーディオパス ツールグラフ内のツール、最後にパフォーマンス ツールグラフ内のツールに送信される。

セグメント ツールグラフとパフォーマンス ツールグラフを作成し、ツールを定義するのはアプリケーションの役目である。ツールグラフの作成の詳細については、次のトピックを参照すること。

  • IDirectMusicGraph8
  • IDirectMusicPerformance8::SetGraph
  • IDirectMusicSegment8::SetGraph

オーディオパス ツールグラフは、DirectMusic Producer ファイルに含まれるオーディオパス構成のオプション コンポーネントである。アプリケーションでは、オーディオパスの作成後、オーディオパス ツールグラフの実装にかかわる必要はない。

ツールグラフ内の最初のツールはメッセージを処理し、そのメッセージをほかのツールに渡したい場合は、次のツールへのポインタと共にそのメッセージをツールグラフにスタンプ処理させる。

この時点で、ツールグラフはメッセージに配信タイプのフラグを割り当てる。このフラグに基づいて、メッセージを次のツールに配信する時期が決まる。このフラグは、ツールで予期されている、次のような配信タイプに基づいている。

  • メッセージに DMUS_PMSGF_TOOL_IMMEDIATE フラグが割り当てられている場合、即座に次のツールに配信される。
  • DMUS_PMSGF_TOOL_QUEUE フラグが割り当てられているメッセージは、遅延時間を考慮に入れた上で、演奏されると想定される時期の直前に配信される (「遅延時間とバンパー時間」を参照すること)。
  • メッセージに DMUS_PMSGF_TOOL_ATTIME フラグが割り当てられている場合、処理されるのとまったく同じ時期に配信される。通知の処理には、ほとんどまたはまったく遅延時間が発生しないので、通知メッセージにはこのフラグが割り当てられる。

ツールグラフがメッセージのスタンプ処理とフラグ割り当てを行った後で、現在のツールは配信タイプを変更することができる。

最終的に、メッセージは破棄されない限り、DirectMusic の出力ツールに到達する。このツールは受け取ったすべてのメッセージをスタンダード MIDI メッセージに変換し、それらをポート バッファ経由でシンセサイザに配信する。

解説については、「オーディオ データの流れの概要」を参照すること。


アプリケーションで作成されたメッセージ

ほとんどのメッセージはトラックによって生成されるが、アプリケーションで直接メッセージをキューに配置できる。たとえば、テンポを変更したり、DLS 音色でノートとしてサウンド エフェクトを演奏する場合に、この処理を行う。

詳細とサンプル コードについては、「IDirectMusicPerformance8::SendPMsg」を参照すること。

パフォーマンスが複数のオーディオパスを持つ場合、DirectMusic はアプリケーションが作成したメッセージを正しくルーティングできない場合がある。これは、新しいメッセージが属するオーディオパスに関する情報がメッセージに含まれていないからである。チャンネル固有のメッセージが、異なるセグメントの異なるオーディオパスにマップされるパフォーマンス チャンネルに属する場合もある。

メッセージが特定のオーディオパスに送信されるようにするには、まず IDirectMusicSegmentState8::GetObjectInPath または IDirectMusicAudioPath8::GetObjectInPath を呼び出し、オーディオパスの DMUS_PATH_AUDIOPATH_GRAPH または DMUS_PATH_SEGMENT_GRAPH ステージから IDirectMusicGraph8 インターフェイスを取得して、セグメントまたはオーディオパスのツールグラフを取得する。次に、メッセージを IDirectMusicGraph8::StampPMsg に渡す。


パフォーマンス メッセージのタイプ

メッセージは、DMUS_PMSG から派生したさまざまなタイプに保存される。C は継承をサポートしていないので、DMUS_PMSG のメンバは DMUS_PMSG_PART マクロ内の各メッセージタイプの宣言に含まれている。これらのメンバは、メッセージ タイプ、タイム スタンプ、メッセージ送信先のパフォーマンス チャンネル、メッセージ処理に使われる次のツールグラフとツールを含む、すべてのメッセージにとって共通のデータを保持している。ほかのメンバは、メッセージ タイプ固有のデータを保持している。

次の標準的なメッセージ構造体が定義されている。

構造体 | 内容
DMUS_PMSG | 追加パラメータのない単純なメッセージ。「注意」を参照すること。
DMUS_CHANNEL_PRIORITY_PMSG | チャンネル優先順位変更。「チャンネル」を参照すること。
DMUS_CURVE_PMSG | カーブ。
DMUS_LYRIC_PMSG | テキスト。
DMUS_MIDI_PMSG | 固有のメッセージ タイプを持たない MIDI メッセージ。たとえば、コントロール チェンジ。
DMUS_NOTE_PMSG | 音楽のノート (継続時間を含む。したがって、MIDI ノートオンおよびノートオフ メッセージは、このスタイルに組み合わされる)。
DMUS_NOTIFICATION_PMSG | 通知。「通知とイベントの処理」を参照すること。
DMUS_PATCH_PMSG | MIDI パッチの変更。
DMUS_SYSEX_PMSG | MIDI システム エクスクルーシブ メッセージ。
DMUS_TEMPO_PMSG | テンポの変更。
DMUS_TIMESIG_PMSG | 拍子記号の変更。
DMUS_TRANSPOSE_PMSG | 転調。
DMUS_WAVE_PMSG | ウェーブの再生。


カーブ

カーブは、MIDI コントローラの一連の変更で構成され、値がなめらかにトランジションする。たとえば、ボリュームのフェードアウトまたはフェードインがある。

DMUS_CURVE_PMSG 型の 1 つのパフォーマンス メッセージを送信することによってカーブを実行できる。この構造体を使用すると、カーブの開始時と終了時の値、期間、および形状を設定できる。オプションで、コントローラが無効の場合に返されるリセット値を設定することもできる。

このメッセージ構造体の wMeasure、nOffset、bBeat、bGrid、および mtOriginalStart メンバは、情報提供だけを目的としており、メッセージのタイミングには影響しない。これらは、DirectMusic Producer セグメントによって送信されたメッセージ内に設定され、ツールで使用される。通常、アプリケーションではこれらのメンバを 0 に設定できる。

wMergeIndex メンバは、変更が累積であるかオーバーライドであるかを示す。マージ インデックスが異なる場合、2 つのカーブ メッセージは累積される。マージ インデックスが同じ場合は、前のメッセージによる設定が新しいメッセージによって順次オーバーライドされる。

bCCData メンバは、コントローラの変更の対象となる MIDI コントローラ番号を含み、空の場合は無視される。コントローラ番号については、MIDI の仕様を参照すること。

次のサンプル コードでは、現在の値からボリュームを下げて 5 秒後に 0 になるようにしている。この時間内に、現在再生中のセグメントがほかのセグメントに置き換えられてコントローラが無効になった場合は、最大ボリュームが復元される。

DMUS_CURVE_PMSG *pCurveMsg;
HRESULT hr = g_pPerf->AllocPMsg(sizeof(DMUS_CURVE_PMSG),
        (DMUS_PMSG**) &pCurveMsg);
ZeroMemory(pCurveMsg, sizeof(DMUS_CURVE_PMSG));

pCurveMsg->dwSize = sizeof(DMUS_CURVE_PMSG);
pCurveMsg->rtTime = 0;
pCurveMsg->dwFlags = DMUS_PMSGF_DX8 | DMUS_PMSGF_REFTIME
        | DMUS_PMSGF_LOCKTOREFTIME;
pCurveMsg->dwPChannel = DMUS_PCHANNEL_BROADCAST_PERFORMANCE;
pCurveMsg->dwType = DMUS_PMSGT_CURVE;
pCurveMsg->dwGroupID = 0xFFFFFFF;
pCurveMsg->mtDuration = 5000;
pCurveMsg->nEndValue = 0;
pCurveMsg->bCurveShape = DMUS_CURVES_LINEAR;
pCurveMsg->bCCData = 7;
pCurveMsg->bFlags = DMUS_CURVE_RESET | DMUS_CURVE_START_FROM_CURRENT;
pCurveMsg->bType = DMUS_CURVET_CCCURVE ;

pCurveMsg->mtResetDuration = 0;
pCurveMsg->nResetValue = 127;

g_pPerf->SendPMsg((DMUS_PMSG*) pCurveMsg);

注 より簡単にボリュームのフェードを実装するには、IDirectMusicAudioPath8::SetVolume を使用する。このメソッドでは、常に、カーブに平行なシェイプを使用する。


MIDI メッセージ

ほとんどのアプリケーションは、MIDI メッセージを直接処理しない。ただし、アプリケーションはパフォーマンス メッセージとして MIDI コマンドを送信し、コントロール チェンジなどを行うことができる。

MIDI メッセージは、1 バイトのステータス バイトと、通常、1 バイトか 2 バイトのデータ バイトによって構成される。システム エクスクルーシブ MIDI メッセージは可変長である。

ステータス バイトはメッセージのタイプを示し、一部の状況では、そのメッセージを受け取るチャンネルを示す。ファイル中に同じ種類のイベントが続けて現れる場合は、ステータス バイトを省略できる。上位ビットが常に消去されているので、データ バイトを認識できる。ステータス バイトの上位ビットは、常に設定されている。

MIDI イベントのタイミングは、各メッセージの前にある数字で制御される。この値は、このイベントと最後のイベントの間隔を、ティック数で表している。ティックの実際の継続時間は、ファイル ヘッダーの時間の形式によって決定される。

注 MIDI メッセージが、ソース データに記述されている順序で処理されるという保証はない。DirectMusic メッセージはタイム スタンプの順に配信される。タイムが同一の MIDI メッセージが 2 つある場合は、予想と異なる順序で配信される場合がある。MIDI コンテンツをオーサリングするときに、イベントを発生させる順序が決まっている場合は、イベント間に間隔を入れるように注意する必要がある。たとえば、プログラム チェンジに依存するノートがある場合は、これらのノートとプログラム チェンジを同時に配置しない。

MIDI メッセージは、次の 2 つの主要なカテゴリに分類できる。

  • MIDI チャンネル メッセージ
  • MIDI システム メッセージ


MIDI チャンネル メッセージ

チャンネル メッセージは、音楽の 1 つのパートに対応する特定の MIDI チャンネルにアドレス指定される。

チャンネル メッセージは、モード メッセージかボイス メッセージのどちらかである。

モード メッセージは、チャンネルがそれ以降のボイス メッセージを取り扱う方法を決定する。たとえば、モード メッセージは、何か通知があるまではすべてのノートオン メッセージを無視して、無音状態を保つようチャンネルに指示することがある。

ほとんどのチャンネル メッセージはボイス メッセージである。これらはチャンネルにノートの演奏の開始または停止、何らかの方法でのノートの変更を指示し、チャンネルにほかの MIDI パッチ番号を割り当てることによりティンバーを変更する。

次の表は、ボイス メッセージの種類を示している。

ボイス メッセージ | 目的
ノートオン | ノートを演奏する。
ノートオフ | ノートの演奏を停止する。
コントロール チェンジ | ペダル、レバー、その他のデバイスからのデータを使って楽音を変更する。ボリュームやバンク セレクトなど、さまざまなコントロールにも使われる。
プログラム (パッチ) チェンジ | パッチ番号を割り当てることにより、チャンネルの音色を選択する。
アフタータッチ | キーのアフタータッチに従って、個別のノートまたはチャンネルのすべてのノートを変更する。
ピッチ ベンド チェンジ | チャンネルで演奏されるすべてのノートのピッチを変更する。

これらの説明は、スタンダード MIDI メッセージに適用され、パフォーマンス メッセージ形式に変換された MIDI データには適用されないことに注意する。たとえば、ノートの演奏を開始および停止するための 2 つの MIDI メッセージは、DirectMusic によって、ノートの継続時間を指定する 1 つのパフォーマンス メッセージに結合される。DirectMusic メッセージには、タイミングやルーティングに関する多くの追加情報も含まていれる。

MIDI ノート

ノートオン メッセージのデータ バイトは、ピッチとベロシティを表す。ほとんどの場合、ピッチの値 (キーナンバー) 0 は 2 オクターブ下の C 音 (MIDI では C0 と表記) であり、12 は 1 オクターブ下の C (MIDI の C1)、60 はピアノでいう中央の C (MIDI の C5) を意味する。ドラム キットの場合、データ バイトは特定のドラム サウンドを意味する。たとえば、GM (General MIDI) のパーカッション キー マップでは、値 60 はハイ ボンゴのサウンドを意味する。チャンネル 10 はドラム キットに予約されているので、シンセサイザはこのチャンネルでのノートオン メッセージをほかのチャンネルとは異なった方法で扱うことを知っている。

DirectMusic が MIDI ノートを変換する方法については、「ミュージック値と MIDI ノート」を参照すること。

プログラム チェンジ

プログラム チェンジとパッチ番号は、MIDI 再生と DirectMusic において重要な概念である。プログラム チェンジは特定の音色 (プログラムまたはティンバーとも呼ぶ) をチャンネルに割り当てるので、チャンネルに送信されたノートは適切なサウンドで演奏される。音色はパッチ番号によって識別される。GM 音色セットをロードする場合、パッチ番号 1 を指定するプログラム チェンジでは、チャンネルは必ずアコースティック グランド ピアノのノートで演奏される。スピーカで生成される実際のサウンドは、音色の合成方法に依存する。

バンク セレクト

プログラム チェンジの際に 1 バイトのデータ バイトを使ってパッチ番号を選択しているが、MIDI メッセージの各データ バイトで有効なのは 7 ビットだけなので、プログラム チェンジでは最大 128 の音色を選択することができる。より多くの選択肢を提供するために、MIDI 規格では最大 16,384 の音色バンクの使用が認められ、各バンクに最大 128 の音色を含めることができる。

ほかのバンクから音色を選択するには、MIDI シーケンサは最初にバンク セレクトと呼ばれるコントロール チェンジ メッセージを送信しなければならない。このメッセージのデータ バイトのうち 2 バイトを、最上位バイト (MSB) および最下位バイト (LSB) と呼び、これらを組み合わせてバンクを識別する。バンクを選択した後、それ以降のプログラム チェンジではそのバンクから音色が選択される。

DirectMusic パッチ番号

MIDI の定める 7 ビット パッチ番号とは異なり、DirectMusic の音色パッチ番号は 32 ビット値であり、その中に MIDI パッチ番号、バンク セレクトの MSB と LSB、およびドラム キット用の 1 ビット フラグが含まれている。IDirectMusicCollection8::EnumInstrument、IDirectMusicCollection8::GetInstrument、および IDirectMusicInstrument8::GetPatch の各メソッドは、この拡張番号を返す。IDirectMusicInstrument8::SetPatch メソッドを使うと、音色を変更できる。

DirectMusic でのパッチの値をまとめたものを以下に示す。

ビット | 目的
0-7 | MIDI パッチ番号 (ビット 7 は常に 0)
8-15 | LSB バンク セレクト (ビット 15 は常に 0)
16-23 | MSB バンク セレクト (ビット 23 は常に 0)
24-30 | 未使用
31 | ドラム キット用のフラグ


MIDI システム メッセージ

システム メッセージは、どのチャンネルにとっても排他的ではない。これらは次の表のように 3 種類に分類される。

メッセージ タイプ | 目的
システム共通 | さまざまなコマンドとデータ
システム エクスクルーシブ | 機器固有のコマンドとデータ
システム リアルタイム | クロックベースの MIDI 機器の同期化

ほかの MIDI メッセージとは異なり、システム エクスクルーシブ メッセージは任意の長さのデータ バイトを保持できる。データを送信した後で、シーケンサは EOX と呼ばれるシステム共通メッセージを送信し、システム エクスクルーシブ メッセージの終わりを知らせる。

DirectMusic では、DMUS_SYSEX_PMSG 構造体が、データ長とデータ バイトの配列へのポインタを保持する。


DirectMusic ポートの使い方

ここでは、オーディオパスを使用しないアプリケーションによる DirectMusic ポートへのアクセスについて説明する。推奨されているように、アプリケーションが IDirectMusicPerformance8::InitAudio を使ってパフォーマンスを初期化する場合、オーディオパスによって、ポートおよびパフォーマンス チャンネルのポートへのマッピングが管理される。

ポートは、データの送信または受信を行うデバイスである。ハードウェア デバイス、ソフトウェア シンセサイザ、ソフトウェア フィルタのいずれかを表す。

DirectMusic アプリケーション内の各ポートは、IDirectMusicPort8 インターフェイスによって表される。このインターフェイスのメソッドを使って、デバイスに関する情報の取得、デバイス内のメモリの管理、DLS 音色のダウンロードとアンロード、流入データの読み込み、再生バッファの挿入を行う。

どのパフォーマンスも少なくとも 1 つのポートを備えていなければならない。デフォルト ポート以外のポートを使う場合や、デフォルト ポートの特別なパラメータを設定する場合は、まず DMUS_PORTPARAMS8 構造体を設定する。すべてのメンバに値を入力する必要はないが、dwValidParams メンバに適切なフラグを書き込むことにより、どのメンバが有効な情報を持っているのか DirectMusic に知らせなければならない。次に、この構造体を IDirectMusic8::CreatePort メソッドに渡す。

次の C++ サンプル コードでは、デフォルトの出力ポート用のオブジェクトを作成し、ポートに 5 つのチャンネル グループを設定する方法を示している。pDirectMusic は有効な IDirectMusic8 インターフェイス ポインタであると仮定する。

IDirectMusicPort8*  pPort;
DMUS_PORTPARAMS    dmos;

ZeroMemory( &dmos, sizeof(DMUS_PORTPARAMS) );
dmos.dwSize = sizeof(DMUS_PORTPARAMS);
dmos.dwValidParams = DMUS_PORTPARAMS_CHANNELGROUPS;
dmos.dwChannelGroups = 5;
HRESULT hr = pDirectMusic->CreatePort( GUID_NULL, &dmos,
        &pPort, NULL )

設定したポートは IDirectMusic8::Activate または IDirectMusicPort8::Activate を呼び出してアクティブにし、IDirectMusicPerformance8::AddPort メソッドを使ってパフォーマンスに付加する。

ポートをパフォーマンスに付加するときに、IDirectMusicPerformance8::AssignPChannelBlock メソッドを呼び出して、P チャンネルのブロックを割り当てる。IDirectMusicPerformance8::AddPort に NULL を渡してデフォルト ポートを追加するときだけ、この処理は必要ない。この場合、P チャンネル 0-15 は、ポートの最初のグループの MIDI チャンネルに割り当てられる。

IDirectMusicPerformance8::AssignPChannelBlock および IDirectMusicPerformance8::AssignPChannel の各メソッドを使うと、これらのP チャンネルを異なった方法で割り当て、ほかの P チャンネルを追加し、P チャンネルをほかのポートに割り当てることができる。

ポートの詳細については、次のトピックを参照すること。

  • デフォルト ポート
  • DirectMusic ポートのプロパティ セット


デフォルト ポート

Windows® 95、および Windows 98 Second Edition 以前の Windows 98 において、または DLS をサポートするハードウェアを利用できない場合は、Microsoft のソフトウェア シンセサイザがデフォルト ポートになる。Windows 98 Second Edition 以降、および Windows 2000 では、ハードウェア シンセサイザがデフォルト ポートになる場合もある。

アプリケーションでデフォルト ポートを使用する場合、パフォーマンスにポートを追加する前に IDirectMusic8::CreatePort メソッドを呼び出す必要はない。代わりに、IDirectMusicPerformance8::AddPort に NULL を渡すことができる。

IDirectMusic8::GetDefaultPort を呼び出してデフォルト ポートを取得し、続いて IDirectMusicPort8::GetCaps メソッドを使って能力を確認できる。ポートがアプリケーションの要求に適合しない場合は、IDirectMusic8::EnumPort メソッドを使って、Microsoft のソフトウェア シンセサイザかその他のポートを検索する。


カスタム ロード

特殊なアプリケーションでは、ファイルやリソースからのデータをカプセル化する、独自のオブジェクト タイプを作成できる。DirectMusic ローダーに、これらのオブジェクトのロードを処理させると便利である。カスタム オブジェクトがほかのオブジェクトから参照されている場合や、カスタム オブジェクトにほかのオブジェクトへの参照が含まれている場合に、特に便利である。

DirectMusic ローダーを利用するロード メカニズムを実装するには、次の手順を実行する。

  • IDirectMusicLoader8::GetObject で検索されるように、オブジェクト クラスを登録する。
  • オブジェクトを検索およびキャッシングするために必要な情報をローダーが取得できるように、オブジェクトに IDirectMusicObject8 インターフェイスを実装する。
  • オブジェクトに IPersistStream インターフェイスを実装し、IPersistStream::Load メソッドの機能をすべて使えるようにする。これにより、DirectMusic ローダーによって渡された、IStream インターフェイス上の呼び出しを通して取得したデータを解析することができる。
  • Load の実装において、IDirectMusicGetLoader8 インターフェイスに対して IStream を照会し、次に IDirectMusicGetLoader8::GetLoader を呼び出して、ストリームを作成した DirectMusicLoader へのポインタを取得することで、ほかのオブジェクトへの参照が処理されていることを確認する。このポインタを取得したら、IDirectMusicLoader8::GetObject を呼び出して、新しいオブジェクトをロードできる。

アプリケーションが、ファイル入力そのものを管理しなければならない場合もある。たとえば、すべてのオブジェクトが、特殊な圧縮リソース ファイルに格納されている場合などである。アプリケーションは、IDirectMusicLoader8 インターフェイスをサポートするオブジェクトを作成し、IDirectMusicLoader8::GetObject メソッドを実装して、独自のローダーを作成することができる。ほかのメソッドはすべてオプションである。また、ローダーのこの実装は、IStream および IDirectMusicGetLoader8 インターフェイスの両方を持つ独自のストリーム オブジェクトを作成しなければならない。


音色コレクションの使い方

ほとんどのアプリケーションでは、DLS 音色データはバンドに関連付けられ、バンドがダウンロードされたときにシンセサイザにダウンロードされる。詳細については、「バンドの使い方」を参照すること。

独自の DLS 管理を行う特別な DirectMusic アプリケーションでは、2 つのステップを実施しなければならない。最初に音色コレクションをロードし、次に音色データをポートにダウンロードする。

次のトピックで、これらのステップについて説明する。

  • コレクションのロードとダウンロード
  • 音色の操作

音色とコレクションを編集するアプリケーションでは、より低いレベルでも DLS データを操作する必要がある。詳細については、次のトピックを参照すること。

  • 下位レベル DLS


コレクションのロードとダウンロード

コレクションは、ほかのオブジェクトと同様にロードされる。詳細については、「オーディオ データのロード」を参照すること。

標準的な GM/GS セットをロードするために、DMUS_OBJECTDESC 構造体の guidObject メンバに、ローダーへのパス GUID_DefaultGMCollection を設定する。ローダーを使ってこのオブジェクトに何度もアクセスする場合は、キャッシングが有効になっていることを確認し (デフォルトの設定)、GM コレクションを要求するたびにコピーが 1 つ作成されることを防止する。

注 GM/GS Sound Set を変更することはできない。詳細については、「法的情報」の「著作権に関する注意」を参照すること。

次のサンプル コードは、GUID によって識別されるコレクションをロードする方法を示している。

HRESULT myGetGMCollection(
        IDirectMusicLoader8 *pILoader,
        IDirectMusicCollection8 **ppICollection)
{
    HRESULT hr;
    DMUS_OBJECTDESC desc;

    desc.dwSize = sizeof(DMUS_OBJECTDESC);
    desc.guidClass = CLSID_DirectMusicCollection;
    desc.guidObject = GUID_DefaultGMCollection;
    desc.dwValidData = (DMUS_OBJ_CLASS | DMUS_OBJ_OBJECT);
    hr = pILoader->GetObject(&desc, IID_IDirectMusicCollection8,
            (void **) ppICollection);
    return hr;
}

IDirectMusicCollection8 インターフェイスへのポインタを取得すると、コレクション内のすべての音色にアクセスできる。ただし、この時点では、音色はポートにダウンロードされていない。

コレクション全体を一度にダウンロードするには、コレクションをセグメントに関連付けて、IDirectMusicSegment8::Download メソッドを呼び出す。例については、「カスタム音色による MIDI ファイルの演奏」を参照すること。

これらの手順は、デフォルト以外のコレクションを使用する場合にのみ必要となる。セグメントがコレクションを参照しない場合、通常は IDirectMusicSegment8::Download を呼び出すときに、セグメント中にオーサリングされたデフォルト コレクションの音色、または General MIDI セットの音色がポートにダウンロードされる。バンドをダウンロードするときに、そのバンドの音色で必要なすべての DLS データがダウンロードされる。「バンドの使い方」を参照すること。


音色の操作

コレクション オブジェクトを作成したり、コレクション ファイルやリソースからロードした場合、音色は特定のポートにバインドされない。異なる音色を異なるポートにダウンロードすることも、1 つの音色を複数のポートにダウンロードすることもできる。

IDirectMusicCollection8::EnumInstrument メソッドを使って、利用可能なすべての音色のパッチ番号および名前を取得できる。

次のサンプル コードは、コレクション内のすべての音色を列挙し、その名前とパッチ番号を表示している。

void myListInstruments(
        IDirectMusicCollection8 *pCollection)

{
    HRESULT hr = S_OK;
    DWORD dwPatch;
    WCHAR wszName[MAX_PATH];
    DWORD dwIndex;
    for (dwIndex = 0; hr == S_OK; dwIndex++)
    {
        hr = pCollection->EnumInstrument(
                dwIndex, &dwPatch, wszName, MAX_PATH);
        if (hr == S_OK)
        {
           printf("Patch %lx is %S\n",dwPatch,wszName);
        }
    }
}

IDirectMusicCollection8::GetInstrument メソッドに特定の音色のパッチ番号を渡して、特定の音色へのポインタを取得する。

音色を取得した後、IDirectMusicInstrument8::SetPatch メソッドを使ってパッチ番号を変更できる。

単一の音色をポートにダウンロードするには、IDirectMusicInstrument8 インターフェイス ポインタを IDirectMusicPort8::DownloadInstrument または IDirectMusicPerformance8::DownloadInstrument メソッドに渡す。この呼び出しは、ポートで DLS データを利用可能にする。音色を特定のパフォーマンスやオーディオパスに関連付けることはない。

メモリを節約するために、指定されたノートの範囲で必要なウェーブとアーティキュレーションだけがダウンロードされる。たとえば、バスーンを使う場合、低音の C から中間の B までのノート範囲に相当するデータだけをダウンロードするよう指定することがある。この範囲以外のリージョンのデータはダウンロードされない。

次のサンプル コードでは、指定されたコレクション、パッチ番号、ポート、およびノート範囲に対して、コレクションから音色を取得し、その音色をダウンロードしている。この関数は、1 つの DMUS_NOTERANGE 構造体から成る配列を作成し、この配列を IDirectMusicPort8::DownloadInstrument メソッドに渡す。一般的には、ノートの 1 つの範囲だけを指定するが、複数の範囲を指定することもできる。配列の代わりに NULL を渡すと、すべての範囲のデータがダウンロードされる。

HRESULT myDownload(
    IDirectMusicCollection8 *pCollection,    // DLS コレクション
    IDirectMusicPort8 *pPort,                // 転送先ポート
    IDirectMusicDownloadedInstrument8 **ppDLInstrument,
    DWORD dwPatch,                          // 要求された音色
    DWORD dwLowNote,                        // 範囲内の低いノート
    DWORD dwHighNote)                       // 範囲内の高いノート

{
    HRESULT hr;
    IDirectMusicInstrument8* pInstrument;
    hr = pCollection->GetInstrument(dwPatch, &pInstrument);
    if (SUCCEEDED(hr))
    {
        DMUS_NOTERANGE NoteRange[1];         // オプションのノート範囲
        NoteRange[0].dwLowNote = dwLowNote;
        NoteRange[0].dwHighNote = dwHighNote;
        hr = pPort->DownloadInstrument(pInstrument,
                ppDLInstrument,
                NoteRange,   // 範囲の配列
                1);          // 配列内の要素の数
        pInstrument->Release();
    }
    return hr;
}

DownloadInstrument メソッドは、IDirectMusicDownloadedInstrument8 インターフェイスへのポインタを返す。このポインタの目的は、それ以降に IDirectMusicPort8::UnloadInstrument メソッドを呼び出すときに音色を識別することだけであり、このメソッドは特定のポートから音色インスタンスをアンロードする。

次の関数では、音色をダウンロードした後、アンロードしている。この例は、IDirectMusicDownloadedInstrument8 ポインタの使用方法を示すだけのものである。

HRESULT myFickleDownload(
        IDirectMusicInstrument8* pInstrument,
        IDirectMusicPort8 *pPort,
        DWORD dwPatch)

{
    HRESULT hr;
    IDirectMusicDownloadedInstrument * pDLInstrument;
    hr = pPort->DownloadInstrument(
            pInstrument, &pDLInstrument,
            NULL, 0);
    if (SUCCEEDED(hr))
    {
        pPort->UnloadInstrument(pDLInstrument);
        pDLInstrument->Release();
    }
    return hr;
}


下位レベル DLS

DLS コレクションを編集するアプリケーションを作成している場合は、DirectMusic 音色オブジェクトにカプセル化することなく、音色データをシンセサイザにダウンロードできる必要がある。

DLS データを操作するには、DLS の仕様およびファイル構造についての知識が必要となる。これらの情報の詳細については、MIDI Manufactures Association に問い合わせること。

未加工の音色データをダウンロードするには、最初に、次のサンプル コードのように IDirectMusicPortDownload8 インターフェイスへのポインタを取得する必要がある。ここでは、pIPort が IDirectMusicPort8 インターフェイスへの有効なポインタであることを想定している。

IDirectMusicPortDownload **ppIDownloadPort;

HRESULT hr = pIPort->QueryInterface(IID_IDirectMusicPortDownload8,
        (void **) ppIDownloadPort);

HRESULT が S_OK ではない場合、そのポートは DLS のダウンロードをサポートしていない。

次に、準備およびダウンロードしなければならないバッファを識別する。音色をシンセサイザに送信するには、音色全体の定義を表し、すべてのリージョンとアーティキュレーションを備えた 1 つの音色バッファと、一連のウェーブ バッファを作成する。音色がリージョン用に参照する 1 つのウェーブにつき、1 つのウェーブ バッファを作成する。

各バッファには、固有の識別子を付けなければならない。これらの識別子を使ってバッファ間のリンク、特にリージョンとウェーブのリンクを解決する。ダウンロードする必要のあるバッファ数を集計し、IDirectMusicPortDownload8::GetDLId を呼び出して、識別子の範囲を割り当てる。たとえば、1 つの音色を 3 つのウェーブと共にダウンロードする場合、全部で 4 つのバッファをダウンロードしなければならないので、4 つの識別子を要求する。

バッファごとに必要なサイズを計算し、次に IDirectMusicPortDownload8::AllocateBuffer を呼び出してそのサイズを割り当てる。このメソッドは、バッファを表す IDirectMusicDownload8 インターフェイスを返す。メモリにアクセスするには、IDirectMusicDownload8::GetBuffer を呼び出す。

注 GetBuffer メソッドは 2 つある。

IDirectMusicPortDownload8::GetBuffer は、ダウンロード識別子が既知のバッファ オブジェクトに対する IDirectMusicDownload インターフェイス ポインタを返す。

IDirectMusicDownload::GetBuffer は、バッファのメモリへのポインタを返す。

今度はデータをバッファに書き込む。各バッファは DMUS_DOWNLOADINFO 構造体によって指定された場所で始まる。この構造体は、サイズとダウンロードの機能を定義する。この構造体は、次の方法で準備しなければならない。

  • dwDLType メンバを、音色の場合は DMUS_DOWNLOADINFO_INSTRUMENT2 に、ウェーブの場合は DMUS_DOWNLOADINFO_WAVE に設定する。
  • dwDLId メンバを、IDirectMusicPortDownload::GetDLId を実行して取得した、固有の識別子のいずれかに設定する。
  • dwNumOffsetTableEntries メンバを、DMUS_OFFSETTABLE 構造体内のエントリ数に設定する。
  • cbSize メンバを、DMUS_DOWNLOADINFO および DMUS_OFFSETTABLE を含む、ダウンロード チャンクのサイズに設定する。

DMUS_DOWNLOADINFO 構造体は、常に DMUS_OFFSETTABLE 構造体に従う。このオフセット テーブルを使って、データ内のすべてのリンクを管理する。データ内の構造体がほかの構造体を参照する場合はいつでも、ポインタではなく整数のインデックス番号を使う。データ内にある参照可能なすべての構造体には、一意のインデックス番号が割り当てられている。DMUS_OFFSETTABLE は、この整数インデックス番号をデータ内のバイト オフセットに平行移動する。

音色データまたはウェーブ データは、DMUS_OFFSETTABLE に従う。音色をダウンロードする場合は、DMUS_INSTRUMENT 構造体で指定された場所からデータが始まる。それ以外のものをダウンロードする場合は、DMUS_WAVE 構造体で指定された場所からデータが始まる。

DMUS_INSTRUMENT 構造体に従う音色データは、次の構造体で構成される。

  • DMUS_ARTICPARAMS
  • DMUS_ARTICULATION
  • DMUS_ARTICULATION2
  • DMUS_COPYRIGHT
  • DMUS_EXTENSIONCHUNK
  • DMUS_INSTRUMENT
  • DMUS_NOTERANGE
  • DMUS_REGION

DMUS_WAVE 構造体で示されるウェーブ データは、DMUS_WAVEDATA 構造体で構成される。

バッファすべてが準備できている場合、IDirectMusicPortDownload8::Download を使ってそれらをダウンロードする。最初にウェーブ バッファをダウンロードすること。その結果ウェーブ バッファが適切な場所に配置され、音色をダウンロードするときに参照できる。

バッファをダウンロードすると、シンセサイザは音色を演奏できる状態になる。バッファをダウンロードした後、そのバッファで使われているメモリにはアクセスできなくなる。

その後、音色の演奏が終了したら、バッファのアンロードと解放を行う。最初に音色バッファをアンロードし、次にすべてのウェーブ バッファをアンロードする。アンロードするには、IDirectMusicDownload8 ポインタを IDirectMusicPortDownload8::Unload に渡す。次に、IDirectMusicDownload8:: Release を呼び出して、各バッファを解放する。

既にダウンロードされている音色を更新する場合、ダウンロード済みのバッファの上書きはできない。代わりに、ウェーブではなく音色を置き換える。音色を置き換えるには、IDirectMusicPortDownload8::AllocateBuffer を呼び出し、適切なバッファ サイズを指定して新しい IDirectMusicDownload8 インターフェイスを割り当てる。IDirectMusicPortDownload8::GetDLId を呼び出して、バッファの新しい識別子を生成すること。新しいアーティキュレーション情報をバッファに書き込み、次にバッファをダウンロードする。次に、IDirectMusicPortDownload8::Unload を呼び出して、以前にダウンロードされていたバッファをアンロードする。

ウェーブ バッファを更新する場合は、もう 1 つステップが増える。新しいウェーブ バッファと、そのバッファを参照する更新された音色バッファの 2 つを作成する。新しいウェーブ バッファ、次いで新しい音色バッファをダウンロードする。さらに古い音色バッファ、次いで古いウェーブ バッファをアンロードする。


DirectMusic ツール

ツールとは、メッセージを途中で取得して、何らかの方法で処理するオブジェクトを意味する。ツールはメッセージに変更を加えて次のツールに渡すか、メッセージを解放するか、元のメッセージ内の情報に基づいて新しいメッセージを送信するか、いずれかの方法で処理を行うことができる。

DirectMusic には出力ツールがあり、通常はこのツールが最後にメッセージを受け取る。このツールは、パフォーマンス メッセージをスタンダード MIDI メッセージに変換し、シンセサイザへのストリームに入れる。ほかのツールは、アプリケーションによって実装するか、ライブラリから取得する。

ツールを実装するには、IDirectMusicTool8 インターフェイスをサポートするオブジェクトを作成しなければならない。IDirectMusicTool8 メソッドのオブジェクト実装により、このツールがどのメッセージを取得するか、およびそのメッセージにどのような作業を行うかを決定する。

出力ツール以外のすべてのツールは、ツールグラフにまとめられる。アプリケーションがほかのツールを 1 つしか使わない場合でも、そのツールを含むツールグラフを作成しなければならない。次に、そのツールグラフをセグメントかパフォーマンスに追加する。ツールグラフは、ツール間でメッセージを転送する際に有効なメカニズムである。

パフォーマンス エンジンがセグメントを演奏するときに、セグメント ツールグラフ内の各ツール、次いでパフォーマンス ツールグラフ内の各ツールが、各メッセージを処理できる。あるツールがメッセージを処理した後、そのツールは DMUS_PMSG 構造体の pGraph メンバから IDirectMusicGraph8 ポインタを取得し、次にそのメッセージを受け取るツールがある場合は、IDirectMusicGraph8::StampPMsg メソッドを呼び出してそのツールへのポインタをメッセージにスタンプする。

ツールは、優先順位の高いスレッドでメッセージを処理する。ツールの IDirectMusicTool8::ProcessPMsg メソッド内では、グラフィックスやファイル入出力などを行う時間のかかる関数を呼び出さないようにする。ツールがアクションをトリガする必要がある場合は、アプリケーションのメイン スレッドなどの別のスレッドに通知して実行する。

IDirectMusicTool8 のメソッドを実装するときに、親オブジェクトへの循環参照を作成しないように注意する。循環参照は、あるオブジェクトがほかのオブジェクトを作成したときに、子オブジェクトが親オブジェクトへの参照を維持している場合に発生する。たとえば、ツールが、IDirectMusicTool8::Init メソッドに渡される、ツールグラフへの新しい参照を作成する場合を考える。ツールがこの参照を解放できない場合、セグメントがツールグラフを解放しようとしたときに問題が発生する。ツールにはツールグラフへの参照が残っているため、ツールグラフが完全に解放されない。また、ツールグラフにはツールへの参照があるため、ツールも解放されない。

ツールの実装方法の例については、「MusicTool サンプル アプリケーション」を参照すること。


プロパティ セット

プロパティ セットによって、DirectX Audio はポートやサウンド カードで提供される拡張サービスをサポートできる。

ハードウェア ベンダーは新しい能力をプロパティとして定義し、そのプロパティの仕様を発表する。GUID がプロパティ セットを識別し、ULONG がセット内の特定のプロパティを識別する。たとえば、ハードウェア ベンダーがリバーブ エフェクトを作成できるカードを設計し、DSPROPERTY_REVERBPROPERTIES_HALL と DSPROPERTY_REVERBPROPERTIES_STADIUM などのプロパティを保持するプロパティ セット DSPROPSETID_ReverbProperties を定義することも考えられる。通常、番号 0 で始まる C 言語の列挙型を使ってプロパティ識別子を定義する。

個別のプロパティにパラメータを関連付けてもよい。パラメータの意味は、プロパティと共に定義される。


DirectMusic ポートのプロパティ セット

IKsControl::KsProperty メソッドを使って、プロパティが利用可能であるかどうかを確認し、プロパティの値を設定および取得する。IDirectMusicPort8:: QueryInterface メソッドを呼び出し、インターフェイス識別子として IID_IKsControl を渡すことにより、ポートに対応する IKsControl インターフェイスを取得する。

プロパティ セットは GUID によって表され、セットの各項目は 0 から始まるインデックスによって表される。GUID に対してインデックス化された項目の意味が変更されることはない。DirectMusic でサポートされるプロパティ セットのリストについては、「KSPROPERTY」を参照すること。

DirectMusic であらかじめ定義されているプロパティ セットはすべて、ただ 1 つの項目を持っており、通常、インデックス番号は 0 に設定されている。カーネルストリーミング (KS) プロパティの完全定義もサポートされており、ベンダーは任意の数の項目とインスタンス、および任意のサイズのデータを持つプロパティ セットを自由に作成できる。

プロパティ項目の要求をポートに対して送信する作業は、ポートの実装に依存する。Win32® ハンドル ベースのマルチメディア呼び出し (midiOut と midiIn の各関数) を利用して DirectMusic のエミュレーションを行っているポートでは、どのプロパティもサポートされない。

次のサンプル コードでは、IKsControl::KsProperty メソッドを使って、ポートが General MIDI サウンド セットをハードウェアでサポートしているかどうかを調べている。

BOOL IsGMSupported(IDirectMusicPort8 *pPort)
{
    HRESULT     hr;
    IKsControl  *pControl;
    KSPROPERTY  ksp;
    DWORD       dwFlags;
    ULONG       cb;
    BOOL        fIsSupported;

    // IKsControl インターフェイスの照会を行う。
    hr = pPort->QueryInterface(IID_IKsControl, (void**)&pControl);
    if (FAILED(hr))
    {
        // ポートがプロパティをサポートしていない。GM サポートがないと仮定する。
        return FALSE;
    }
    // GM について問い合わせる。
    ksp.Set   = GUID_DMUS_PROP_GM_Hardware;
    ksp.Id    = 0;
    ksp.Flags = KSPROPERTY_TYPE_BASICSUPPORT;
    hr = pControl->KsProperty(&ksp, sizeof(ksp),
            &dwFlags, sizeof(dwFlags), &cb);
    fIsSupported = FALSE;
    if (SUCCEEDED(hr) || (cb >= sizeof(dwFlags))
    {
        // セットがサポートされている。
        fIsSupported = (BOOL)(dwFlags & KSPROPERTY_TYPE_GET);
    }
    pControl->Release();
    return fIsSupported;
}


DirectSound バッファのプロパティ セット

サウンド カード上の拡張プロパティを利用するには、最初にそのドライバが IKsPropertySet インターフェイスをサポートしているかどうかを確認し、サポートしている場合はそのインターフェイスへのポインタを取得しなければならない。これを行うには、次のように、DirectSound3D バッファ オブジェクト上の既存のインターフェイスに対して QueryInterface メソッドを呼び出す。

HRESULT hr = lpDirectSound3DBuffer->QueryInterface(
        IID_IKsPropertySet,
        (void**)&lpKsPropertySet));

この例では、lpDirectSound3DBuffer はバッファのインターフェイスへのポインタであり、IKsPropertySet インターフェイスが見つかった場合は、lpKsPropertySet はそのアドレスを受け取る。IID_lpKsPropertySet は、Dsound.h 内で定義されている GUID である。

バッファがハードウェア アクセラレートされている場合に限り、この呼び出しは成功する。成功した場合は、IKsPropertySet::QuerySupport メソッドを使って特定のプロパティを検索できる。PropertySetId パラメータの値は、ハードウェア ベンダーによって定義された GUID である。

特定のプロパティに対するサポートが存在すると確認した後は、IKsPropertySet::Set メソッドによるプロパティの状態の変更と、IKsPropertySet::Get メソッドによる現在の状態の確認を行うことができる。pPropertyData パラメータを使って、プロパティの状態の設定と取得を行う。

IKsPropertySet::Set の pPropertyParams パラメータが指す構造体内のオブジェクトに、追加のプロパティ パラメータを渡してもよい。このパラメータの正確な使用方法は、プロパティ セットに関するハードウェア ベンダーの仕様書で定義されるが、プロパティ セットのインスタンスを定義するために使われるのが普通である。実際には、pPropertyParams を使うことはほとんどない。


DirectSound の性能の最適化

ここでは、DirectSound バッファで直接オーディオ データを演奏するアプリケーションの性能を向上させるためのさまざまなヒントを示す。説明するトピックは、次のとおりである。

  • バッファ フォーマットのマッチング
  • ハードウェア ミキシングの利用
  • ダイナミック ボイス管理
  • ISA および PCI カードでのハードウェア アクセラレーション
  • プライマリ バッファの連続再生
  • コントロールの変更の最少化
  • 3D バッファに関係する CPU の考慮事項


バッファ フォーマットのマッチング

DirectSound ミキサは、各セカンダリ サウンド バッファから得たデータをプライマリ サウンド バッファ用のフォーマットに変換する。この変換はデータをプライマリ バッファにミキシングする際にその場で行われ、CPU サイクルを消費する。セカンダリ バッファとプライマリ バッファで同じフォーマットを使用することで、この負荷を回避できる。通常、これは、プライマリ バッファのフォーマットを、データで使用されるウェーブ ファイルのフォーマットに設定することである。

DirectSound の採用するフォーマット変換方法では、サンプリング レートとチャンネル数を合わせるだけでよい。サンプリング サイズ (8 ビットか 16 ビットか) は関係ない。


ハードウェア ミキシングの利用

ほとんどのサウンドカードは、対応する DirectSound ドライバが存在すれば、何らかのレベルのハードウェア ミキシングをサポートする。次のヒントは、ハードウェア ミキシングをできるだけ利用するのに役立つ。

  • 実行時に IDirectSound8::GetCaps メソッドを呼び出して、サウンドアクセラレータ ハードウェアがサポートしているフォーマットを確認し、できる限りそのフォーマットを使う。
  • 最も利用の多いサウンドのサウンド バッファを最初に作成する。ハードウェアでミキシングできるバッファ数には限度がある。
  • バッファをハードウェアに必ず作成するには、DSBUFFERDESC 構造体の dwFlags メンバに DSBCAPS_LOCHARDWARE フラグを指定する。このフラグを指定し、ハードウェア ミキシングに対するリソースが利用できない場合は、IDirectSound8::CreateSoundBuffer メソッドは失敗する。
  • ボイス管理を使って、ハードウェア リソースが利用可能なときにバッファをリソースに割り当てたり、あまり重要でないバッファを強制終了させてハードウェア リソースを解放できるようにする。「ダイナミック ボイス管理」を参照すること。


ダイナミック ボイス管理

多くのサウンド カードは固有のセカンダリ バッファを維持し、3D エフェクトとそのミキシングを処理する。これらのハードウェア バッファは、呼び出しの際、通常はカード自体ではなくシステム メモリに配置される。しかし、これらはデバイスによってミキシングされるので、システム プロセッサに対する要求は、ソフトウェア バッファよりもはるかに少なくなる。したがって、ハードウェアにできる限り多くのバッファ、特に 3D バッファを割り当てることが最も効率的である。

デフォルトでは、DirectSound は可能であれば常にバッファをハードウェアに割り当てる。しかし、DirectSound はデバイスが一度に再生できるだけのハードウェア バッファしか作成できない。つまり、ハードウェア バッファ数は、利用可能なハードウェア ボイスで制限される。DirectSound は、バッファが作成されるときにハードウェア ボイスを割り当て、バッファが不要になったときだけ解放する。ボイスは、バッファが再生中でないときもフリーではない。アプリケーションが多くのバッファを作成する場合、いくつかのバッファがソフトウェアに存在する可能性がある。つまり、サウンド カードではなく CPU でバッファの管理とミキシングが行われる。

ダイナミック ボイス管理を使うと、バッファが再生されるまでボイス割り当てを遅延したり、DirectSound が優先順位の低いサウンドを早めに停止してリソースを新しいサウンドに割り当てることにより、ハードウェア リソースの利用制限を克服できる。

ハードウェア ミキシングと 3D エフェクトに対するリソースの割り当てをバッファが再生されるまで遅延するには、IDirectSound8::CreateSoundBuffer に渡される DSBUFFERDESC 構造体に DSBCAPS_LOCDEFER フラグを指定する。DSBCAPS_LOCDEFER フラグによって作成されたバッファについて IDirectSoundBuffer8::Play または IDirectSoundBuffer8::AcquireResources を呼び出す場合、DirectSound は可能であればハードウェアにバッファを配置し、それ以外の場合はソフトウェアに配置する。

Play を呼び出す場合は、次の表に示すフラグの 1 つ、または最初の 2 つのフラグのどちらかを 3 番目のフラグと組み合わせて渡すことで、バッファに対するハードウェア ボイスの解放を試みることができる。その後、DirectSound はフラグの指定する終了基準に適した再生バッファを検索する。

フラグ | 基準
DSBPLAY_TERMINATEBY_TIME | どの候補バッファよりも長く再生されているバッファを選択する。
DSBPLAY_TERMINATEBY_DISTANCE | リスナーから最も遠い 3D の候補バッファを選択する。
DSBPLAY_TERMINATEBY_PRIORITY | Play の呼び出しでの設定に基づき、候補バッファのうち最も優先度の低いバッファを選択する。このフラグをほかの 2 つのフラグのどちらかと組み合わせると、そのフラグは優先度が等しい場合だけに使われる。

適切なバッファが見つかると、DirectSound はそのバッファを停止し、使用していたボイスを新たに再生されるバッファに割り当てる。どのバッファも終了基準に適していない場合は、DSBPLAY_LOCHARDWARE フラグが指定されていなければ、新たに再生されるバッファはソフトウェアで再生される。このフラグが指定されている場合、Play に対する呼び出しは失敗する。

遅延バッファの再生時の処理についての詳細は、「IDirectSoundBuffer8::Play」を参照すること。

注 バッファの作成時は、DSBCAPS_LOCDEFER フラグを DSBCAPS_STATIC フラグと組み合わせて使わないこと。いくつかの PCI カードの場合のように、オンカード メモリが利用可能なとき、DSBCAPS_STATIC バッファはこのメモリに置かれる。DSBCAPS_LOCDEFER フラグでこのようなバッファを作成する場合、バッファ メモリはバッファが最初に再生されるまでサウンド カードにコピーされず、不適切な遅れが生じる。詳細については、「ISA および PCI カードでのボイス管理」を参照すること。


ISA および PCI カードでのハードウェア アクセラレーション

過去数年間に、サウンド カードは ISA バス カードから PCI カードに移行した。この設計の変更により、DirectSound をアクセラレートするカードがオーディオ データを処理する基本的な方法が変化した。さらに、DirectSound にボイス管理が導入され、アプリケーションは限られたハードウェア アクセラレーション リソースを効率的に使用できるようになった。

ここでは、2 種類のサウンド カードで、バッファを割り当てたり、ボイス管理を使う際の注意事項を説明する。説明するトピックは、次のとおりである。

  • ISA カード上の DirectSound バッファ
  • PCI カード上の DirectSound バッファ
  • ISA および PCI カードでのボイス管理


ISA カード上の DirectSound バッファ

DirectSound が最初に導入されたとき、すべてのオーディオ デバイスは ISA バス上で動作していた。ISA バスは、システム全体の性能に大きな影響を与えることなく、16 ビット、22 kHz ステレオ データを CPU からサウンド カードにストリーミングするには十分であった。しかし、より多くのデータを送信しようとすると、バスに過度の負荷がかかる場合があった。この制限によって、オーディオ ハードウェアの設計は大きく影響されていた。

DirectSound バッファをミキシングするために、サウンド カード上のチップで 2 とおりの処理を行うことができる。ISA バスを介してシステム メモリにアクセスするか、カード自体の専用メモリを使用するかである。ISA バスの帯域幅は限られているので、システム メモリからのオーディオ データの読み込みは現実的ではない。したがって、ISA ベースのサウンド カードで、DirectSound アクセラレーションを実行するカードは、ほとんどの場合専用のオンボード RAM を持っている。

このようなサウンド カードを使って DirectSound をアクセラレートする場合、まずサウンド データをシステム メモリから、ISA バスを介してカード上の専用メモリにコピーしなければならない。このコピーには若干時間がかかる場合がある。しかし、データをカードにコピーした後は、システムに対してサウンドの開始、停止、ミキシングの負荷はほとんどかからない。このような処理はすべて、カード上の専用メモリにアクセスするオーディオ プロセッサ チップによって処理される。

ISA ベースの DirectSound アクセラレータはカード上のスタティック バッファをサポートしているが、ストリーミング バッファはサポートしていない。これは、低速の ISA バスを介してデータをストリーミングするのは実用的ではないからである。DSBCAPS_STATIC フラグを指定して作成した DirectSound バッファは、カードにメモリが搭載されている場合、そのメモリに配置される。その他のバッファは、システム メモリに作成される。


PCI カード上の DirectSound バッファ

現在販売されているほとんどのオーディオ カードは PCI バスに接続するように設計されている。PCI バスが一般的になるに従って、システムとオーディオ カードとの間で利用可能な帯域幅が大幅に増加した。現在では、オーディオ チップが直接システム メモリにアクセスし、オーディオ データを取得してハードウェア ミキシングを行うことも現実的になった。その結果、バッファ用のオンボード メモリを持つ意味がなくなった。

PCI カードでは、スタティック バッファとストリーミング バッファは事実上同じである。すべてのバッファはシステム メモリ内に配置されるので、DSBCAPS_STATIC フラグはバッファの場所に影響しない。

注 ほとんどのサウンド カードは、オンボード RAM を持っていない場合でも、スタティック バッファを持っていると DSCAPS にレポートする。これらのカードによってレポートされるストリーミング バッファとスタティック バッファは同じバッファである場合がある。


ISA および PCI カードでのボイス管理

バッファの作成時に DSBCAPS_LOCDEFER フラグを使うことによって、バッファが再生されるときまで、ハードウェア ミキシング メモリまたはソフトウェア ミキシング メモリへのバッファの割り当てを遅延することができる。詳細については、「ダイナミック ボイス管理」を参照すること。

アプリケーションの性能に対する遅延割り当ての効果は、ユーザーのシステムでの DirectSound アクセラレータのタイプによって異なる。

PCI アクセラレータの場合を考えてみる。遅延バッファを再生するときに、DirectSound はサウンドの再生に利用できるハードウェアがあるかどうかを調べる。ハードウェアを利用できる場合、DirectSound は元の場所にあるサウンド データにアクセスできるかどうかを確認する。最後に、DirectSound は再生を開始するようにハードウェアに指示する。この処理は、効率的であり、また高速である。

注 DirectSound ボイス マネージャは、メモリではなく、ハードウェア ミキシング リソースを割り当てる。PCI カードでは、バッファはハードウェア ミキサとソフトウェア ミキサのいずれに割り当てられるかに関係なく、割り当ての前後で同じメモリを使用する。

ユーザーが ISA ベースのアクセラレータを使用する場合、状況はまったく異なる。この場合、オーディオ データをハードウェア ミキシング バッファに取り込む処理は非常に遅い。オーディオ データをミキシングするには、ISA バスを介して、サウンド カード上のメモリにデータをロードしなければならないからである。遅延バッファの場合、再生の呼び出しが行われた後、サウンドが開始される前に不適切な遅延が発生する。このような理由から、ISA ベースの DirectSound アクセラレータ カードではボイス管理の使用は推奨されていない。

ISA デバイスでアプリケーションがボイス管理を使わないようにすることは簡単である。DSBCAPS_STATIC フラグを設定しない限り、バッファはオンボード メモリに割り当てられない。したがって、DSBCAPS_STATIC と DSBCAPS_LOCDEFER を組み合わせない限り、再生時にバッファがオンボード メモリに割り当てられる危険性はない。

DSBCAPS_STATIC だけを指定すると、バッファは ISA カード上の既存のメモリを利用するが、PCI カードの場合は何の効果もない。この場合、ほかのフラグが指定されていないと、DirectSound はバッファをハードウェアの制御下に置くが、システム メモリを利用する。DSBCAPS_LOCDEFER だけを指定すると、ISA カードでは何の効果もない。バッファは常にシステム メモリに配置され、ハードウェアによって管理されないからである。

次の表に、ISA および PCI デバイス用に作成されたバッファに対する DSBCAPS_STATIC および DSBCAPS_LOCDEFER フラグの効果をまとめる。

カード | フラグ | メモリ | HW アクセラレーション
ISA | DSBCAPS_STATIC | 利用可能な場合はハードウェア。 | ハードウェア メモリにある場合は可。
PCI | DSBCAPS_STATIC | システム。 | ハードウェア ボイスが利用可能な場合は可。フラグの効果はない。
ISA | DSBCAPS_LOCDEFER | 利用可能で、DSBCAPS_STATIC が設定されている場合はハードウェア。 | ハードウェア メモリにある場合は可。ただし、最初の再生には待ち時間が発生する。
PCI | DSBCAPS_LOCDEFER | システム。 | ハードウェア ボイスが利用可能な場合は可。

遅延割り当てによる問題を回避しながら、ISA カードでアクセラレーションを利用するには、まずデバイスの能力をチェックする。カードに 1 つ以上のスタティック バッファがあり、ストリーミング バッファがないとレポートされる場合は、オンボード メモリを搭載した古い ISA カードである可能性が高い。この場合、DSBCAPS_STATIC フラグを使うことができるがDSBCAPS_LOCDEFER を使ってはならない。カードに 1 つ以上のストリーミング バッファがあるとレポートされる場合は、新しい PCI ベースのアクセラレータ カードである。この場合は、ハードウェア ボイスを最大限に利用するために、DSBCAPS_LOCDEFER を使用し、DSBCAPS_STATIC を使用しない。


プライマリ バッファの連続再生

サウンドが再生されていない場合、DirectSound はミキサ エンジンを停止し、DMA (ダイレクト メモリ アクセス) を停止させる。再生なしの状態が頻繁に発生するアプリケーションでは、サウンドを再生するたびにミキサの開始と停止を行う場合のオーバーヘッドは、ミキサを常時アクティブにする場合の DMA のオーバーヘッドより大きくなることがある。また、サウンド機器やドライバによっては、再生の頻繁な開始と停止により不要な雑音を出すこともある。

アプリケーションがほぼ連続的に再生を行い、休止時間が少ない場合は、プライマリ バッファに対して IDirectSoundBuffer8::Play メソッドを呼び出し、ミキサ エンジンを常時アクティブにもできる。

サウンドの再生がないときにミキサ エンジンを停止するデフォルトの状態に戻すには、プライマリ バッファに対して IDirectSoundBuffer8::Stop メソッドを呼び出す。


コントロールの変更の最少化

セカンダリ バッファのパン、ボリューム、周波数を変更すると性能に影響する。サウンド出力が途切れることを防止するには、DirectSound ミキサは 20ms から 100ms、またはそれ以上先行してミキシングを行わなければならない。コントロールを変更した場合は、ミキサは先行ミキシング バッファをフラッシュ (解放) し、変更後のサウンドを使って再ミキシングを行わなければならない。

送信するコントロールの変更回数を最少にすることは良い考えである。IDirectSoundBuffer8::SetVolume、IDirectSoundBuffer8::SetPan、IDirectSoundBuffer8::SetFrequency の各メソッドを使うルーチンの呼び出し回数を減らすよう努める。たとえば、アニメーションのフレームに同期して音を左スピーカから右スピーカへ動かすルーチンを使っている場合、SetPan メソッドを 1 フレームごとに 2 回ではなく 1 回呼び出すことを試みる。

注 3D コントロール (向き、位置、速度、ドップラー係数など) を変更した場合も、DirectSound ミキサは先行ミキシング バッファを再ミキシングしなければならない。しかし、3D コントロールの変更をグループ化し、再ミキシングを 1 回に削減できる。「遅延設定」を参照すること。


3D バッファに関係する CPU の考慮事項

ソフトウェアによる 3D バッファのエミュレーションは、多くの計算処理を要する。アプリケーションで、いつ、どのように 3D バッファを使用するかを決定する場合は、このことを考慮しなければならない。

3D サウンドの利用は最小限に抑え、3D エフェクトが利点とならないサウンドには 3D サウンドを適用しない。各サウンドの 3D エフェクトを簡単に有効または無効にできるようアプリケーションを設計する。任意の 3D サウンド バッファに対する 3D 処理を停止するには、DS3DMODE_DISABLE フラグを指定して IDirectSound3DBuffer8::SetMode メソッドを呼び出す。

リスナーからの距離が遠く、聞こえないバッファについても、3D 処理が停止していることを確認できる。「最小距離と最大距離」を参照すること。


DirectSound ドライバ モデル

VxD ドライバ モデルでは、DirectSound のすべてのミキシングは、仮想デバイス ドライバ Dsound.vxd で処理される。Dsound.vxd は、サウンド カードがホスト CPU からデータを受信するために使用する実際の DMA バッファへのアクセスも提供する。これは DirectSound プライマリ バッファと同じである。DirectSound アプリケーションは、サンプリング レートやビット深度など、プライマリ バッファの特定のプロパティを設定することができ、したがってハードウェア自体のプロパティも変更できる。

Windows Driver Model (WDM) では、DirectSound は、ハードウェアによってアクセラレートされたバッファの場合を除いて、サウンド バッファに直接アクセスしない。その代わりに、DirectSound はカーネル ミキサ、つまり Kmixer と通信する。Kmixer の役割は、複数のオーディオ ストリームのフォーマットを共通のフォーマットに変換し、これらをミキシングして、その結果をハードウェアに送信することである。つまり、Dsound.vxd が行っていた処理を行っている。大きな違いは、Dsound.vxd が DirectSound バッファのデータだけをミキシングするのに対して、Kmixer は、Win32 waveOut 関数を使うアプリケーションからのデータを含む、すべての Windows オーディオ データをミキシングすることである。DirectSound とウェーブフォーム オーディオ出力デバイスを同時にオープンできないという規則は、WDM ドライバを使用するシステムには当てはまらない。

Kmixer とオーディオ ハードウェアとの関係は特に重要である。Kmixer は、システム上で、ハードウェアの DMA バッファのフォームを指定できる唯一のソフトウェアである。Kmixer は、ミキシングを要求されたサウンドに基づいてフォーマットを選択する。出力フォーマットは、ミキシングを要求されたサウンドの最高品質のフォーマットか、ハードウェアでサポートされている、それに最も近いフォーマットに設定される。

これは、とても重要な意味を持っている。DirectSound では、ハードウェアの DMA バッファのフォーマットを設定できないということである。アプリケーションでは、ハードウェア フォーマットは実際に演奏されるデータに基づくことを意味する。44 kHz のファイルを再生する場合、Kmixer は最大 44 kHz のすべてのデータをミキシングし、ハードウェアが 44 kHz で実行されていることを確認する。

アプリケーション開発者は、使用されるドライバ モデルを選択しない。ドライバ モデルは、サウンド カードの種類、Windows のバージョン、ユーザーがインストールしている特定のドライバによって決まる。このような理由から、アプリケーションをテストするときに、すべての可能性を調べておくことが重要である。DirectSound は Dsound.vxd を使用する場合もあれば、Kmixer を使用する場合もあるので、アプリケーションの動作および性能がいずれの場合も許容できるものであることを確認しなければならない。


プライマリ バッファへの書き込み

セカンダリ バッファがサポートしていない特別なミキシングやほかのエフェクトを必要とするアプリケーションに対して、DirectSound はプライマリ サウンド バッファへの直接アクセスを許可する。

プライマリ バッファへの書き込みアクセスを取得すると、DirectSound のほかの機能は利用できなくなる。セカンダリ バッファのミキシングも行われないので、ハードウェア アクセラレーション ミキシングも利用できなくなる。

ほとんどのアプリケーションは、プライマリ バッファへ直接アクセスせずにセカンダリ バッファを使う。セカンダリ バッファへの書き込みは簡単に行うことができる。より大きなバッファにより、次のデータ ブロックの書き込みまでの時間が長くなり、オーディオの音が途切れる危険が最小限に抑えられる。アプリケーションが必要とするオーディオが、ミキシングを必要としない 1 つのオーディオ ストリームのような単純なものであっても、セカンダリ バッファを使ってオーディオ データを再生することにより、より高い性能が実現できる。

注 プライマリ バッファへの直接の書き込みは、WDM ドライバ モデルでは利点がない。WDM では、プライマリ バッファは、事実上、カーネル ミキサによってミキシングされるセカンダリ バッファである。WDM の詳細については、「DirectSound ドライバ モデル」を参照すること。

プライマリ バッファのサイズは指定できず、バッファを作成した後に返されるサイズを受け入れなければならない。通常、プライマリ バッファは極めて小さく、もしアプリケーションがこのようなバッファに直接書き込む場合は短い間隔でデータ ブロックを書き込み、以前のデータがもう一度再生されることを防がなければならない。

プライマリ バッファがハードウェア上に存在していない限り、そのバッファの書き込みアクセスは取得できない。これに該当するかどうかを確認するには、IDirectSoundBuffer8::GetCaps メソッドを呼び出して DSBCAPS 構造体の dwFlags メンバ内の DSBCAPS_LOCHARDWARE フラグの有無をチェックする。ソフトウェアでエミュレートしたプライマリ バッファをロックしようとすると、呼び出しは失敗する。

DSBUFFERDESC 構造体に DSBCAPS_PRIMARYBUFFER フラグを指定し、この構造体を IDirectSound8::CreateSoundBuffer メソッドに渡して、アクセス可能なプライマリ バッファを作成する。バッファに書き込みをしたい場合、協調レベルは DSSCL_WRITEPRIMARY でなければならない。

プライマリ サウンド バッファは、ループして再生しなければならない。その目的で、DSBPLAY_LOOPING フラグが設定されていることを確認する。

次の例は、プライマリ バッファへの書き込みアクセスを取得する方法を示している。プライマリ バッファは IDirectSoundBuffer インターフェイスだけをサポートし、IDirectSoundBuffer8 をサポートしていないことに注意すること。

BOOL AppCreateWritePrimaryBuffer(
    LPDIRECTSOUND8 lpDirectSound,
    LPDIRECTSOUNDBUFFER *lplpDsb,
    LPDWORD lpdwBufferSize,
    HWND hwnd)
{
    DSBUFFERDESC dsbdesc;
    DSBCAPS dsbcaps;
    HRESULT hr;
    WAVEFORMATEX wf;

    // ウェーブ フォーマット構造体を設定する。
    memset(&wf, 0, sizeof(WAVEFORMATEX));
    wf.wFormatTag = WAVE_FORMAT_PCM;
    wf.nChannels = 2;
    wf.nSamplesPerSec = 22050;
    wf.nBlockAlign = 4;
    wf.nAvgBytesPerSec =
        wf.nSamplesPerSec * wf.nBlockAlign;
    wf.wBitsPerSample = 16;

    // DSBUFFERDESC 構造体を設定する。
    memset(&dsbdesc, 0, sizeof(DSBUFFERDESC));
    dsbdesc.dwSize = sizeof(DSBUFFERDESC);
    dsbdesc.dwFlags = DSBCAPS_PRIMARYBUFFER;
    // バッファ サイズはサウンド ハードウェアによって決まる。
    dsbdesc.dwBufferBytes = 0;
    dsbdesc.lpwfxFormat = NULL; // プライマリ バッファでは NULL でなければならない。

    // 書き込み優先協調レベルを取得する。
    hr = lpDirectSound->SetCooperativeLevel(hwnd, DSSCL_WRITEPRIMARY);
    if SUCCEEDED(hr)
    {
        // バッファの作成を試みる。
        hr = lpDirectSound->CreateSoundBuffer(&dsbdesc,
                lplpDsb, NULL);
        if SUCCEEDED(hr)
        {
            // プライマリ バッファを適切なフォーマットに設定する。
            hr = (*lplpDsb)->SetFormat(&wf);
            if SUCCEEDED(hr)
            {
                // バッファ サイズを知りたい場合は、GetCaps を呼び出す。
                    dsbcaps.dwSize = sizeof(DSBCAPS);
                (*lplpDsb)->GetCaps(&dsbcaps);
                *lpdwBufferSize = dsbcaps.dwBufferBytes;
                return TRUE;
            }
        }
    }
    // 失敗。
    *lplpDsb = NULL;
    *lpdwBufferSize = 0;
    return FALSE;
}

次の例は、アプリケーションがカスタム ミキサを実装する方法を示している。サウンド デバイスがデータ ブロックの再生を繰り返さないよう、AppMixIntoPrimaryBuffer 関数を一定の間隔で呼び出さなければならない。CustomMixer 関数はアプリケーションが定義した関数であり、アプリケーションが定義した AppStreamInfo 構造体の指定に従って複数のストリームをミキシングし、次のように結果を指定のポインタに書き込む。

BOOL AppMixIntoPrimaryBuffer(
        LPAPPSTREAMINFO lpAppStreamInfo,
        LPDIRECTSOUNDBUFFER lpDsbPrimary,
        DWORD dwDataBytes,
        DWORD dwOldPos,
        LPDWORD lpdwNewPos)
{
    LPVOID lpvPtr1;
    DWORD dwBytes1;
    LPVOID lpvPtr2;
    DWORD dwBytes2;
    HRESULT hr;
    // 書き込みポインタを取得する。
    hr = lpDsbPrimary->Lock(dwOldPos, dwDataBytes,
                            &lpvPtr1, &dwBytes1,
                            &lpvPtr2, &dwBytes2, 0);

    // DSERR_BUFFERLOST が返された場合、復元してロックを再試行する。

    if (DSERR_BUFFERLOST == hr)
    {
        lpDsbPrimary->Restore();
        hr = lpDsbPrimary->Lock(dwOldPos, dwDataBytes,
                                &lpvPtr1, &dwBytes1,
                                &lpvPtr2, &dwBytes2, 0);
    }
    if SUCCEEDED(hr)
    {
        // 返されたポインタにデータをミキシングする。
        CustomMixer(lpAppStreamInfo, lpvPtr1, dwBytes1);
        *lpdwNewPos = dwOldPos + dwBytes1;
        if (NULL != lpvPtr2)
        {
            CustomMixer(lpAppStreamInfo, lpvPtr2, dwBytes2);
            *lpdwNewPos = dwBytes2; // ラップアラウンドされるからである。
        }
        // データを解放して DirectSound に戻す。
        hr = lpDsbPrimary->Unlock(lpvPtr1, dwBytes1,
                                  lpvPtr2, dwBytes2);
        if SUCCEEDED(hr)
        {
            return TRUE;
        }
    }
    // ロックまたはアンロックが失敗した。
    return FALSE;
}


プログラミングのヒントおよびツール

ここでは、DirectX Audio アプリケーションを効率的に開発するための情報を記述する。説明するトピックは、次のとおりである。

  • DirectX Audio プロジェクトのデバッグ
  • テスト用の DirectSound アクセラレーションのコントロール


DirectX Audio プロジェクトのデバッグ

DirectX ソフトウェア開発キットのデバッグ バージョンでインストールされる DirectMusic および DirectSound の DLL (ダイナミック リンク ライブラリ) は、アプリケーションの実行時に、情報をデバッグ出力ウィンドウに生成する。デフォルトでは、利用できるすべての情報が表示される。これらの DLL は、DirectX SDK のデバッグ バージョンがインストールされている場合に利用できる。DirectMusic DLLは、コントロール パネルの DirectX プロパティ シートで [Use Debug Version of DirectMusic] を選択することによって動的に選択できる。

DirectMusic DLL では、Win.ini の値を変更すると、デバッグ出力ウィンドウに表示される情報を制御することができる。DirectMusic DLL それぞれの出力は、次の例に示すように、個別に設定することができる。

[Debug]
DMBAND=1
DMCOMPOS=1
DMIME=1
DMLOADER=0
DMUSIC=1
DMSTYLE=3
DMSYNTH=5

それぞれの値は -1 ～ 5 の範囲で設定できる。-1 を設定すると、デバッグ情報は生成されず、5 を設定すると、もっとも詳細な情報が生成される。Win.ini にエントリがない場合、デバッグ出力のレベルは 0 になる。特定の DLL にほかのコンポーネントよりも低い値を設定し、その DLLの問題に注目することができる。

コントロール パネルの DirectX プロパティ シートの [DirectMusic] ページおよび [DirectSound] ページにある [Debug Output Level] スライダを使って、デバッグ レベルを 0 ～ 5 の範囲に設定することもできる。ただし、この方法ではすべての DLL に同じ値が設定される。

「DirectX アプリケーションのデバッグ」も参照すること。


テスト用の DirectSound アクセラレーションのコントロール

コントロール パネルの [サウンドとマルチメディアのプロパティ] ページで、システム上の DirectSound の性能を調整できる。[オーディオ] タブの [再生] の [詳細] をクリックする。[パフォーマンス] タブをクリックする。スライダを使って、ハードウェア アクセラレーションを次のいずれかに設定できる。

最大
IKsPropertySet 拡張機能など、すべての DirectSound アクセラレーションを有効にする。Windows 98 では、これがデフォルトの設定である。
標準
DirectSound セカンダリ バッファのアクセラレーションを有効にするが、ハードウェア固有の IKsPropertySet 拡張機能を無効にする。Windows 2000 では、これがデフォルトの設定である。
基本
DirectSound セカンダリ バッファのハードウェア アクセラレーションを無効にする。このオプションは、テスト用にアクセラレーション機能を持たないサウンド カードをエミュレーションする場合に便利である。
なし
DirectSound をエミュレーション モードにする。このモードは、システムに DirectSound 互換のドライバがないものとして機能する。すべてのミキシングは、ユーザー モードの DirectSound によって行われ、ミキシングされたデータは Win32 ウェーブフォーム オーディオ関数に送信される。通常、これによって遅延時間が大幅に増加する。


DirectX Audio C++ チュートリアル

ここでは、次のチュートリアルを使用して、C++ アプリケーションに Microsoft® DirectMusic® および Microsoft® DirectSound® を実装する方法を説明する。

  • チュートリアル 1 : オーディオ ファイルの再生
  • チュートリアル 2 : オーディオパス オブジェクトの使い方

このほかに、SDK と共に提供されるサンプル アプリケーションでは、Microsoft® DirectX® Audio のより専門的な使い方が示されている。これらのサンプルの説明については、「DirectX Audio C++ サンプル」を参照すること。


チュートリアル 1 : オーディオ ファイルの再生

このチュートリアルでは、DirectX Audio の最も基本的なタスクについてステップ バイ ステップで説明する。具体的には、DirectMusic パフォーマンスの初期化とオーディオ ファイルの再生について説明する。このチュートリアルは、次のステップから構成されている。

  • ステップ 1 : 初期化
  • ステップ 2 : ファイルのロード
  • ステップ 3 : ファイルの再生
  • ステップ 4 : 終了処理

チュートリアルで使用しているサンプル コード全体のファイルが次のフォルダにある。

\mssdk\samples\Multimedia\DirectMusic\Tutorials\Tut1

注 DirectX SDK がインストールされているルート ディレクトリが異なる場合は、パス内の "mssdk" をそのディレクトリの名前に置き換える必要がある。


ステップ 1 : 初期化

アプリケーションで DirectMusic API を使用するには、次のインクルード ファイルが必要である。Dmusici.h をインクルードすると、DirectMusic と DirectSound のその他の必要なヘッダー ファイルもインクルードされる。

#define INITGUID
#include <dmusici.h>

このチュートリアルは、3 つのインターフェイス ポインタを使用する。それらは次のように宣言される。

IDirectMusicLoader8*      g_pLoader       = NULL;
IDirectMusicPerformance8* g_pPerformance  = NULL;
IDirectMusicSegment8*     g_pSegment      = NULL;

WinMain 関数には、この簡単なアプリケーションのすべてのコードが含まれている。このアプリケーションはメイン ウィンドウを持たないため、直接、COM と 2 つのオブジェクトの作成に進む。作成するオブジェクトは、ローダーとパフォーマンスである。

INT APIENTRY WinMain( HINSTANCE hInst, HINSTANCE hPrevInst,
    LPSTR pCmdLine, INT nCmdShow )
{
    CoInitialize(NULL);

    CoCreateInstance(CLSID_DirectMusicLoader, NULL,
                     CLSCTX_INPROC, IID_IDirectMusicLoader8,
                     (void**)&g_pLoader);

    CoCreateInstance(CLSID_DirectMusicPerformance, NULL,
                     CLSCTX_INPROC, IID_IDirectMusicPerformance8,
                     (void**)&g_pPerformance );

次のステップでは、パフォーマンスとシンセサイザを初期化する。IDirectMusicPerformance8::InitAudio メソッドによって次のタスクを実行する。

  • DirectMusic オブジェクトと DirectSound オブジェクトを作成する。通常、これらのオブジェクトへのインターフェイスは必要なく、最初の 2 つのパラメータに NULL を渡す。
  • アプリケーション ウィンドウを DirectSound に関連付ける。通常、3 番目のパラメータとしてメイン アプリケーション ウィンドウのハンドルが渡されるが、このチュートリアルのアプリケーションはウィンドウを持たないため NULL を渡す。
  • 標準タイプのデフォルトのオーディオパスを設定する。このチュートリアルでは、音楽に適した DMUS_APATH_SHARED_STEREOPLUSREVERB 型のパスを要求する。
  • パフォーマンス チャンネルの数をオーディオパスに割り当てる。ウェーブ ファイルに必要なパフォーマンス チャンネルは 1 つだけである。MIDI ファイルは 16 個のチャンネルを必要とする。DirectMusic Producer で作成したセグメントは、さらに多くのチャンネルを使用する場合がある。余分のチャンネルを要求しても問題は生じない。
  • シンセサイザの機能およびリソースを指定する。これは、次の 2 つの方法で行うことができる。フラグを設定する方法と、より詳細な情報を含む DMUS_AUDIOPARAMS 構造体を渡す方法である。ほとんどのアプリケーションは、DMUS_AUDIOF_ALL フラグを設定して、DirectMusic によってデフォルトのパラメータ設定のシンセサイザが作成されるようにしている。

このチュートリアルでは、非常に簡単な方法で InitAudio を呼び出している。

    g_pPerformance->InitAudio(
        NULL,                  // IDirectMusic インターフェイスは不要。
        NULL,                  // IDirectSound インターフェイスは不要。
        NULL,                  // ウィンドウのハンドル。
        DMUS_APATH_SHARED_STEREOPLUSREVERB,  // デフォルトのオーディオパス タイプ
        64,                    // パフォーマンス チャンネルの数。
        DMUS_AUDIOF_ALL,       // シンセサイザの機能。
        NULL                   // オーディオ パラメータにはデフォルトを使用。
    );

次の「ステップ 2 : ファイルのロード」に続く。


ステップ 2 : ファイルのロード

次は、DirectMusic のパフォーマンスおよびシンセサイザでサウンド データを処理する。データを取得するには、ローダーにデータの場所を指示する必要がある。ファイルをロードするたびにフル パスを指定することもできるが、デフォルトのディレクトリを設定しておく方が便利である。これには、IDirectMusicLoader8::SetSearchDirectory メソッドを使用する。

サンプル コードでは、デフォルトの Windows メディア ディレクトリへのパスが指定されている。別のフォルダのファイルを取得するには、wstrSearchPath の値を変更する。

次のコードは、チュートリアル サンプル内の WinMain 関数の一部である。

    // Windows メディア ディレクトリを見つける。

    CHAR strPath[MAX_PATH];
    GetWindowsDirectory( strPath, MAX_PATH );
    strcat( strPath, "\\media" );

   // Unicode に変換する。

    WCHAR wstrSearchPath[MAX_PATH];
    MultiByteToWideChar( CP_ACP, 0, strPath, -1,
                         wstrSearchPath, MAX_PATH );

    // 検索ディレクトリを設定する。

    g_pLoader->SetSearchDirectory(
        GUID_DirectMusicAllTypes,   // 検索するファイルの種類。
        wstrSearchPath,             // 検索する場所。
        FALSE                       // オブジェクト データを消去しない。
    );

SetSearchDirectory の呼び出しの中で、fClear パラメータが FALSE に設定されているのは、間違ったディレクトリのオブジェクトが再ロードされる可能性はないからである。アプリケーションが別のフォルダから同じ名前のオブジェクトをロードしない限り、間違ったディレクトリのオブジェクトが再ロードされることはない。

ローダーにファイルの検索場所を指示したら、次は、ファイルを 1 つのセグメントとしてロードする。

    WCHAR wstrFileName[MAX_PATH] = L"The Microsoft Sound.wav";

    if (FAILED(g_pLoader->LoadObjectFromFile(
        CLSID_DirectMusicSegment,   // クラス識別子。
        IID_IDirectMusicSegment8,   // 目的のインターフェイスの ID。
        wstrFileName,               // ファイル名。
        (LPVOID*) &g_pSegment       // インターフェイスを受け取るポインタ。
    )))
    {
        MessageBox( NULL, "Media not found, sample will now quit.",
                          "DMusic Tutorial", MB_OK );
        return 0;
    }

次の「ステップ 3 : ファイルの再生」に続く。


ステップ 3 : ファイルの再生

このステップでは、前のステップでロードしたウェーブ ファイルを IDirectMusicSegment8 インターフェイス経由でパフォーマンスに渡す。

セグメントを再生する前に、バンドをシンセサイザにダウンロードしておく必要がある。バンドをダウンロードしない場合、このステップは、固有のバンドを使用するセグメントごとに 1 回だけ実行する。

次のコードは、サンプル内の WinMain 関数の一部である。このコードは、バンドをパフォーマンスにダウンロードする。バンドはオーディオパスにダウンロードすることもできる。使用するシンセサイザが 1 つだけの場合は、ダウンロード先としてどちらのオブジェクトを選択してもかまわない。

    g_pSegment->Download( g_pPerformance );

ファイルを再生するには、セグメントのインターフェイスを IDirectMusicPerformance8::PlaySegmentEx に渡す。このメソッドには多数の再生オプションが用意されている。ただし、デフォルトのオーディオパスで直ちにセグメントを再生するには、2 番目以降のパラメータをすべて NULL または 0 に設定する。

    g_pPerformance->PlaySegmentEx(
        g_pSegment,  // 再生するセグメント。
        NULL,        // ソングに使用するパラメータ。実装されていない。
        NULL,        // トランジションに関するパラメータ。
        0,           // フラグ。
        0,           // 開始タイム。0 は直ちに開始。
        NULL,        // セグメント状態を受け取るポインタ。
        NULL,        // 停止するオブジェクト。
        NULL         // デフォルトでない場合はオーディオパス。
    );
    MessageBox( NULL, "Click OK to Exit.", "Play Audio", MB_OK );

次の「ステップ 4 : 終了処理」に続く。


ステップ 4 : 終了処理

オーディオ アプリケーションを正常に終了するには、次の 4 つの主な手順を実行する必要がある。

  • IDirectMusicPerformance8::Stop を呼び出して再生中のセグメントをすべて停止する。
  • パフォーマンスの終了処理を行う。IDirectMusicPerformance8::CloseDown メソッドを使って、その他のクリーンアップ タスクを実行し、オブジェクトへの内部参照を解放する。
  • すべてのインターフェイスを解放する。
  • COM を閉じる。

次のサンプル コードは、チュートリアル サンプル内の WinMain 関数の一部である。ダイアログ ボックスを終了するときはこのコードが呼び出される。

    g_pPerformance->Stop(
        NULL,   // すべてのセグメントを停止する。
        NULL,   // すべてのセグメント状態を停止する。
        0,      // 直ちに実行する。
        0       // フラグ。
    );

    g_pPerformance->CloseDown();

    g_pLoader->Release();
    g_pPerformance->Release();
    g_pSegment->Release();

    CoUninitialize();

    return 0;  // WinMain の戻り値。
}              // WinMain の終了。


チュートリアル 2 : オーディオパス オブジェクトの使い方

このチュートリアルでは、DirectMusic パフォーマンスを設定する方法と、オーディオパスからオブジェクトを取得してサウンド パラメータを変更する方法についてステップ バイ ステップで説明する。チュートリアル サンプルでは、オーディオパスから 3D バッファを取得する。このチュートリアルは、次のステップから構成されている。

  • ステップ 1 : オーディオパスの作成
  • ステップ 2 : バッファの取得
  • ステップ 3 : バッファのパラメータの変更

チュートリアルで使用しているサンプル コード全体のファイルが次のフォルダにある。

\mssdk\samples\Multimedia\DirectMusic\Tutorials\Tut2

注 DirectX SDK がインストールされているルート ディレクトリが異なる場合は、パス内の "mssdk" をそのディレクトリの名前に置き換える必要がある。

このチュートリアルは、パフォーマンス オブジェクトおよびローダー オブジェクトの作成と、ファイルのロードおよび再生についての基本的な手順を理解していることを前提としている。これらの手順については「チュートリアル 1 : オーディオ ファイルの再生」で説明されている。


ステップ 1 : オーディオパスの作成

オーディオパスを作成する最も簡単な方法は、IDirectMusicPerformance8::InitAudio にフラグを渡す方法である。このチュートリアル サンプルでは、DMUS_APATH_DYNAMIC_STEREO フラグを渡し、InitAudio でステレオ サウンドをサポートするデフォルトのオーディオパスをセットアップする。

g_pPerformance->InitAudio(
    NULL,                      // IDirectMusic インターフェイスは不要。
    NULL,                      // IDirectSound インターフェイスは不要。
    NULL,                      // ウィンドウのハンドル。
    DMUS_APATH_DYNAMIC_STEREO, // デフォルトのオーディオパス タイプ。
    64,                        // パフォーマンス チャンネルの数。
    DMUS_AUDIOF_ALL,           // シンセサイザの機能。
    NULL                       // オーディオ パラメータにはデフォルトを使用。
);

デフォルトのオーディオパスは、バックグラウンド ミュージックやナレーションなど、空間内に位置する必要がないサウンドに適している。ただし、アプリケーションで 3D サウンド エフェクトを実装する場合は、それぞれのオーディオパス上で各音源が演奏されるため、3D パラメータを個別に設定できる。

次のサンプルでは、そのようなオーディオパスを 1 つ作成している。

IDirectMusicAudioPath8* p3DAudioPath = NULL;
g_pPerformance->CreateStandardAudioPath(
    DMUS_APATH_DYNAMIC_3D,      // パスの種類。
    64,                         // パフォーマンス チャンネルの数。
    TRUE,                       // ここでアクティブになる。
    &p3DAudioPath               // オーディオパスを受け取るポインタ。
);

A segment can now be played on this audiopath as follows:

g_pPerformance->PlaySegmentEx(
    g_pSegment,  // 再生するセグメント。
    NULL,        // ソングに使用するパラメータ。実装されていない。
    NULL,        // トランジションに関するパラメータ。
    0,           // フラグ。
    0,           // 開始タイム。0 は直ちに開始。
    NULL,        // セグメント状態を受け取るポインタ。
    NULL,        // 停止するオブジェクト。
    p3DAudioPath // Audiopath.
);

次の「ステップ 2 : バッファの取得」に続く。


ステップ 2 : バッファの取得

IDirectMusicAudioPath8::GetObjectInPath メソッドを使用して、パスの一部を形成するオブジェクトへのインターフェイスを取得することができる。DMUS_APATH_DYNAMIC_3D 標準オーディオパス型の場合、これらのオブジェクトには、セカンダリ バッファそのもの、プライマリ バッファ、DirectSound リスナー、またはオーディオパスの作成後にバッファ上に設定される DMO が含まれる。このチュートリアル サンプルは、バッファへの IDirectSound3DBuffer8 インターフェイスを取得する。

IDirectSound3DBuffer8* pDSB = NULL;

p3DAudioPath->GetObjectInPath(
    DMUS_PCHANNEL_ALL,        // パフォーマンス チャンネル。
    DMUS_PATH_BUFFER,         // パス内の段階。
    0,                        // チェーン内のバッファのインデックス。
    GUID_NULL,                // オブジェクトのクラス。
    0,                        // バッファ内のオブジェクトのインデックス。無視。
    IID_IDirectSound3DBuffer, // 目的のインターフェイスの GUID。
    (LPVOID*) &pDSB           // インターフェイスを受け取るポインタ。
);

IDirectMusicAudioPath8::GetObjectInPath のパラメータは、設定が少し複雑になっている。パス内の各段階のオブジェクトに対応したパラメータについては、「オーディオパスからのオブジェクトの取得」を参照すること。

チュートリアル サンプルでは、このオーディオパス上のすべてのパフォーマンス チャンネルで使用されるセカンダリ バッファを取得する。dwPChannel パラメータを DMUS_PCHANNEL_ALL に設定する。

取得するのは 1 つ目のバッファで、この場合はチェーン内に 1 つのバッファしか存在しないため、dwBuffer として 0 を渡す。DMUS_PATH_BUFFER ステージはバッファ オブジェクトだけを含み、それらのバッファに付加された DMO は含まない。このため、dwIndex は無視される。

次の「ステップ 3 : バッファのパラメータの変更」に続く。


ステップ 3 : バッファのパラメータの変更

取得した IDirectSound3DBuffer8 インターフェイスを使用して、空間内でサウンドを移動する。チュートリアル サンプル アプリケーションでは、一連のメッセージ ボックスを閉じるときにこの処理を実行する。たとえば、次のコードは、サウンドを直ちに左に移動する。

pDSB->SetPosition( -0.1f, 0.0f, 0.0f, DS3D_IMMEDIATE );

最初の 3 つのパラメータは、音源の新しい位置をデフォルトのリスナーとの相対的な位置で指定する。デフォルトのリスナーは座標 (0.0, 0.0, 0.0) にあり、正面は z 軸の正の方向を向き、頭のてっぺんは y 軸の正の方向を向いている。デフォルトの距離の単位はメートルである。x 軸の正の方向は左から右なので、サウンドの新しい位置はリスナーの左 10 cm の所になる。詳細については、「3D 空間の座標」および「リスナーの向き」を参照すること。

IDirectSound3DBuffer8::SetPosition メソッドの最後のパラメータは、変更を直ちに反映するか、すべての変更が実行されてから反映するかを指定する。詳細については、「遅延設定」を参照すること。


DirectX Audio C++ サンプル

ここで示すサンプル アプリケーションには、Microsoft® DirectX® for C++ の Microsoft® DirectMusic® および Microsoft® DirectSound® アプリケーション プログラミング インターフェイス (API) の使い方と機能が示されている。

各トピックで、次の 2 種類のサンプルについて説明する。

  • DirectMusic C++ サンプル。これらのサンプルは、DirectMusic API を使ってサウンドをロードして再生している。一部のサンプルでは、DirectSound API 要素を使用している。
  • DirectSound C++ サンプル。これらのサンプルは、DirectSound API のみを使用している。ただし、ここに示されるテクニックの多くは、DirectMusic オーディオパスから取得したバッファと共に使用することもできる。


DirectMusic C++ サンプル

次に示す実行可能アプリケーションは、DirectMusic API のみまたは DirectSound と DirectMusic の両方を使用している。これらのアプリケーションを実行するには、[スタート] メニューの [プログラム] をポイントする。次に、[Microsoft DirectX8 SDK] をポイントして、[DirectMusic Samples] をクリックする。

  • 3DAudio
  • AudioFX
  • AudioPath
  • AudioScripts
  • MusicTool
  • PlayAudio
  • PlayMotif

ソース コードは次のフォルダにある。

\mssdk\samples\Multimedia\DirectMusic

これらのサンプルのほかに、次のフォルダに、チュートリアル アプリケーションのソース ファイルがある。

\mssdk\samples\Multimedia\DirectMusic\Tutorials

詳細については、「DirectX Audio C++ チュートリアル」を参照すること。

チュートリアル以外のサンプルは、共通のソース ファイルを使用している。これらのファイルは、DirectMusic および DirectSound の基本的な機能とメディア ファイルの検索などの一般的なタスクに使用される関数およびクラスを実装している。ファイルは次の場所にある。

\mssdk\samples\Multimedia\Common\src

注 DirectX SDK がインストールされているルート ディレクトリが異なる場合は、すべてのパスで "mssdk" をそのディレクトリの名前に置き換える必要がある。


3DAudio

説明

3DAudio サンプル アプリケーションは、DirectMusic パフォーマンス内に 3D オーディオパスを作成する方法、そのパスの 3D バッファおよびリスナーへのインターフェイスを取得する方法、およびバッファとリスナーのパラメータを変更する方法を示す。

パス

ソース :(SDK ルート)\Samples\Multimedia\DirectMusic\3DAudio

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DirectMusic\Bin

ユーザーズ ガイド

[Open File] をクリックして、ウェーブ、MIDI、または DirectMusic のセグメント ファイルをロードする。セグメントを再生する。音源の位置がグラフ上に赤い点で示される。このグラフでは、x 軸が左から右に向かい、z 軸が下から上に向かっている。スライダを使って、2 本の座標軸上の移動範囲を変更する。

リスナーはグラフの中央に位置し、デフォルトの向きを向いている。デフォルトの向きは、z 軸の正の方向、つまり画面の上方向である。音源はリスナーの左右前後に移動し、上下には移動しない。

ウィンドウの中央にあるスライダは、リスナーのプロパティ、つまりグローバル サウンド プロパティを制御する。[Defer Settings] をクリックすると、変更は、次に [Apply Settings] をクリックするまで適用されない。

プログラミング メモ

ソース コード フォルダの Readme.txt を参照すること。

参照

3D サウンド、オーディオパスからのオブジェクトの取得


AudioFX

説明

AudioFX サンプルは、DirectMusic オーディオパスで DMO を使ってサウンドにエフェクトを追加する方法、およびエフェクト パラメータを設定する方法を示す。

パス

ソース :(SDK ルート)\Samples\Multimedia\DirectMusic\AudioFX

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DirectMusic\Bin

ユーザーズ ガイド

アプリケーションを実行すると、デフォルトのサウンド ファイルがロードされる。別のファイルをロードする場合は、[Open File] をクリックしてファイルを選択する。

最初は、エフェクトが有効になっていない。[Play] をクリックして、エフェクトなしでサウンドを聞く。

[Stop] をクリックして、バッファを停止する。[Enable] のチェックボックスをオンにし、1 つまたは複数のエフェクトを適用する。サウンドをもう一度再生する。

エフェクトのパラメータを調整するには、[Adjust] でオプション ボタンを選択し、ウィンドウの右側のフレームにある値を変更する。この調整は、サウンドの再生中でも、エフェクトの適用前でも実行できる。

プログラミング メモ

アプリケーションはエフェクトを管理するための CSoundFXManager クラスを実装している。CSoundFXManager::Initialize メソッドでは、オーディオパスから IDirectSoundBuffer8 インターフェイスを取得する。このインターフェイスは、CSoundFXManager::ActivateFX メソッドでバッファにエフェクトを設定するために使用される。Effect パラメータは、インターフェイスからのメッセージに応答して、OnEffectChanged 関数に設定される。

参照

エフェクトの使い方


AudioPath

説明

AudioPath サンプルは、1 つのオーディオパスで複数の異なるサウンドを再生する方法と、オーディオパスでの変更がすべてのサウンドのパラメータに与える影響を示す。

パス

ソース :(SDK ルート)\Samples\Multimedia\DirectMusic\AudioPath

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DirectMusic\Bin

ユーザーズ ガイド

[Lullaby]、[Snore]、および [Mumble] をクリックしてさまざまなサウンドを再生する。スライダを使って、3D 空間でのサウンドの位置を調整する。[Rude Awakening] をクリックすると、別の 1 つのサウンドを再生してほかのすべてのサウンドを停止することができる。

プログラミング メモ

このサンプルは、PlayAudio サンプルと形式がよく似ている。AudioPath は、オーディオパスの多様な使い方をいくつか示している。

WM_INITDIALOG で、OnInitDialog 関数は次の処理を行う。

  1. IDirectMusicPerformance8::CreateStandardAudioPath を呼び出し、DMUS_APATH_DYNAMIC_3D に渡して、IDirectMusicAudioPath8 インターフェイス g_p3DAudiopath によって示される 3D オーディオパスを作成する。
  2. CMusicManager フレームワーク クラスを使って、ファイルのリストから CMusicSegment オブジェクトを作成する。
  3. オーディオパスから IDirectSound3DListener8 インターフェイスを取得する。
  4. IDirectSound3DListener8::SetRolloffFactor を呼び出して、サウンドの振幅が距離が離れるにつれて消滅するときの割合を変更する。

3D 位置スライダが変更されると、SetPosition 関数は以下の処理を実行する。

  1. IDirectMusicAudioPath8::GetObjectInPath を呼び出して IDirectSound3DBuffer8 インターフェイスを取得する。
  2. IDirectSound3DBuffer8::SetPosition を呼び出してバッファの位置を設定する。
  3. バッファを解放する。

セグメントを再生すると、PlaySegment 関数は以下の処理を実行する。

  • [Lullaby] をクリックすると、セグメントがプライマリ セグメントとしてオーディオパス上で再生される。
  • [Snore] または [Mumble] をクリックすると、セカンダリ セグメントが再生される。
  • [Rude Awakening] をクリックすると、オーディオパスが pFrom パラメータとして IDirectMusicPerformance8::PlaySegmentEx に渡されるため、オーディオパス上のすべてのサウンドが停止される。次に、新しいプライマリ セグメントとしてアラーム サウンドが再生される。

参照

オーディオパスの使い方


AudioScripts

説明

AudioScripts サンプルは、アプリケーションと DirectMusic スクリプトの連携を示す。スクリプトはアプリケーション内の変数を読み書きし、アプリケーションはスクリプト内のセグメントを再生するルーチンを呼び出す。

このサンプルは、1 つのセグメント内のさまざまなバリエーションとしてウェーブを再生する方法も示す。

パス

ソース :(SDK ルート)\Samples\Multimedia\DirectMusic\AudioScripts

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DirectMusic\Bin

ユーザーズ ガイド

[Script File] ボックスの一覧から [ScriptDemoBasic.spt] を選択する。[Routine 1] をクリックしてセグメントを演奏する。[Routine 2] をクリックしてエンディングを演奏し、再生を停止する。セグメントを再度演奏して、[Routine 3] を複数回クリックする。[Variable 1] に、ボタンをクリックした回数が表示され、ボタンをクリックするたびに音楽が変わる。

[Script File] ボックスの一覧から [ScriptDemoBaseball.spt] を選択する。[Routine 1] をクリックして、ベンダーからのさまざまな呼び出しを再生する。[Routine 2] をクリックして、さまざまな音楽モチーフを再生する。[Variable1] ボックスおよび [Variable2] ボックスに異なる値を入力してスコアを変更する。[Routine 3] をクリックしてスコアを聞く。

プログラミング メモ

ソース コード フォルダの Readme.txt を参照すること。

参照

オーディオ スクリプトの使い方


MusicTool

説明

MusicTool サンプルは、メッセージを挿入する DirectMusic ツールを実装する方法を示す。

パス

ソース :(SDK ルート)\Samples\Multimedia\DirectMusic\MusicTool

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DirectMusic\Bin

ユーザーズ ガイド

デフォルトのセグメントを再生するか、[Open File] をクリックして別のウェーブ、MIDI、または DirectMusic セグメント ファイルを選択する。ドロップダウン リストから [Echo Tool] を選択してエコー エフェクトを適用する。

プログラミング メモ

ソース コード フォルダの Readme.txt を参照すること。

参照

DirectMusic ツール


PlayAudio

説明

PlayAudio サンプルは、セグメントをロードしてオーディオパスで再生する方法、DirectMusic 通知を使用する方法、およびグローバル パフォーマンス パラメータを変更する方法を示す。

パス

ソース :(SDK ルート)\Samples\Multimedia\DirectMusic\PlayAudio

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DirectMusic\Bin

ユーザーズ ガイド

デフォルトのセグメントを再生するか、[Open File] をクリックして別のウェーブ、MIDI、または DirectMusic セグメント ファイルをロードする。スライダを使ってテンポとボリュームを調整する。

プログラミング メモ

WM_INITDIALOG で、OnInitDialog 関数は次の処理を行う。

  1. Win32® イベント g_hDMusicMessageEvent を作成する。DirectMusic 通知を受信するたびに、DirectMusic はこのイベントを使ってアプリケーションに通知する。
  2. CMusicManager クラスのオブジェクト g_pMusicManager を作成する。
  3. CMusicManager オブジェクトを初期化する。これによって次の処理が行われる。
    • CoCreateInstance を使って IDirectMusicLoader8 を作成する。
    • CoCreateInstance を使って IDirectMusicPerformance8 を作成する。
    • IDirectMusicPerformance8::InitAudio を呼び出してパフォーマンスを初期化し、標準的なオーディオパスを作成する。
  4. IDirectMusicPerformance8::AddNotificationType を呼び出して GUID_NOTIFICATION_SEGMENT 型の通知を要求する。アプリケーションがセグメントの終了を確認できるように、DirectMusic はすべてのセグメント イベントをアプリケーションに通知する。
  5. IDirectMusicPerformance8::SetNotificationHandle を呼び出して Win32 イベント g_hDMusicMessageEvent を渡す。これを受け取った DirectMusic は、通知を利用できるときにこのイベントを通知する。

WinMain 関数は次のタスクを実行する。

  1. CreateDialog を使ってウィンドウを作成する。
  2. メッセージ ループ内で、MsgWaitForMultipleObjects を呼び出して g_hDMusicMessageEvent を渡す。これを受け取ることによって、g_hDMusicMessageEvent が通知されたことがわかる。DirectMusic は、DirectMusic 通知を受信するたびにこのイベントを通知する。
  3. WAIT_OBJECT_0 が返された場合は、ProcessDirectMusicMessages を呼び出す。
  4. WAIT_OBJECT_0 + 1 が返された場合は、Windows メッセージを利用できる。この関数は、PeekMessage を使ってメッセージの標準的な処理を行う。

[Open File] をクリックすると、OnOpenSoundFile 関数によって次のタスクが実行される。

  1. ファイル名を取得する。
  2. 以前に作成したセグメントがあれば、これを解放する。
  3. Dmutil.cpp 内の CMusicManager::CollectGarbage を呼び出す。これによって IDirectMusicLoader8::CollectGarbage が呼び出され、未使用オブジェクトが解放される。「ガベージ コレクション」を参照すること。
  4. CMusicManager::SetSearchDirectory を呼び出す。IDirectMusicLoader8::SetSearchDirectory が呼び出されて GUID_DirectMusicAllTypes とディレクトリが渡される。これによって、セグメントによって参照されるファイルの場所が DirectMusic に伝えられる。
  5. CMusicManager::CreateSegmentFromFile を呼び出して g_pMusicSegment と呼ばれる CMusicSegment を作成する。この処理は次の手順で行われる。
    • IDirectMusicLoader8::LoadObjectFromFile を呼び出して IDirectMusicSegment8 を pSegment にロードする。
    • CMusicSegment を作成して pSegment を渡す。
    • ファイルが純粋な MIDI ファイルの場合は、IDirectMusicSegment8::SetParam を呼び出して GUID_StandardMIDIFile を渡す。これによって、ファイルを正しく再生できるようになる。
    • IDirectMusicSegment8::Download を呼び出してセグメントのバンドをシンセサイザにダウンロードする。アプリケーションによっては、ダウンロードに時間がかかる場合がある。これは、ダウンロードする音色の数が多ければ多いほど、メモリの所要量も大きくなるからである。

[Play] をクリックすると、OnPlayAudio 関数によって次の処理が行われる。

  1. そのサウンドをループする場合は、CMusicSegment::SetRepeats を呼び出して DMUS_SEG_REPEAT_INFINITE を渡す。ループしない場合は、繰り返しを 0 に設定する。
  2. CMusicSegment::Play を呼び出して IDirectMusicPerformance8::PlaySegmentEx を呼び出す。

通知が行われると、ProcessDirectMusicMessages 関数はセグメントが停止されたことを示すメッセージを検索する。次のタスクが実行される。

  1. ループ内で IDirectMusicPerformance8::GetNotificationPMsg を呼び出して利用可能な各メッセージを処理する。S_OK が返される限りループは繰り返される。利用可能なメッセージがなくなると、S_FALSE が返される。
  2. DMUS_NOTIFICATION_PMSG 構造体の dwNotificationOption が DMUS_NOTIFICATION_SEGEND の場合は、punkUser メンバ上で QueryInterface を呼び出して、終了したセグメント インスタンスの IDirectMusicSegmentState8 インターフェイスを取得する。IDirectMusicSegmentState8::GetSegment を使用すると、セグメント自体が取得される。このメソッドは IDirectMusicSegment を返す。IDirectMusicSegment8 を取得するには QueryInterface を使用する必要がある。アプリケーションはこのポイントをグローバル プライマリ セグメントのポインタと比較して、それが本当に停止されたプライマリ セグメントであることを確認する。DirectMusic Producer で作成したセグメントをほかのセグメントのトリガとすることができる。このため、再生されていたのがプライマリ セグメントだけであるとは限らない。
  3. すべてのインターフェイスをクリーンアップする。


PlayMotif

説明

PlayMotif サンプルは、セカンダリ セグメントとして再生されるモチーフをプライマリ セグメントのリズムに割り当てるさまざまな方法を示す。

パス

ソース :(SDK ルート)\Samples\Multimedia\DirectMusic\PlayMotif

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DirectMusic\Bin

ユーザーズ ガイド

デフォルトのセグメントを再生するか、モチーフを含むスタイルに基づく別の DirectMusic セグメントをロードする。リスト ボックスからパターンを 1 つ選択し、[Align Option] ボタンを 1 つ選択して、[Play Motif] をクリックする。プライマリ セグメントの適切な境界に到達するまで、モチーフの再生は開始されない。

プログラミング メモ

PlayMotif サンプルは、PlayAudio サンプルと形式がよく似ている。このサンプルを基本としたノートのプログラミングの詳細については、「PlayAudio」を参照すること。

ファイルをロードする際、PlayMotif は、PlayAudio と同じ手順を実行した後、LoadSegmentFile 関数を実行する。

  1. ループ処理により、セグメントに含まれるスタイル内のモチーフを検索する。IDirectMusicSegment8::GetParam を呼び出して、GUID_IDirectMusicStyle とインクリメントするインデックスを渡し、各スタイルを取得する。このメソッドは、次に検索すべきスタイルがなくなると失敗する。
  2. 各スタイルに対して、IDirectMusicStyle8::EnumMotif を呼び出して、インクリメントするモチーフ インデックスを渡す。この呼び出しは、そのインデックスを使ってモチーフ名を取得する。S_FALSE が返された場合は、そのスタイル内にほかにモチーフがないことを意味する。

モチーフ名を IDirectMusicStyle8::GetMotif に渡して、モチーフへの IDirectMusicSegment8 インターフェイス ポインタを取得し、これをリスト ボックス内の項目と関連付けられたデータとして保存する。

[Play Motif] をクリックすると、OnPlayMotif 関数によって次のタスクが実行される。

  1. インターフェイスから目的のアライメント オプションを取得する。
  2. リスト ボックスから選択されたモチーフとその MOTIF_NODE 項目データを取得する。MOTIF_NODE 構造体は、現在再生されている演奏の回数のカウントと、モチーフの IDirectMusicSegment インターフェイスへのポインタを保持する。
  3. IDirectMusicPerformance8::PlaySegment を呼び出して、モチーフの IdirectMusicSegment、DMUS_SEGF_SECONDARY などのフラグ、およびアライメント オプションを渡す。

DirectMusic 通知は、通常、PlayAudio 内で処理される。ただし、このアプリケーションは、開始または終了するモチーフのノートを取得してMOTIF_NODE 構造体内の演奏カウントを更新する。演奏カウントが 0 よりも大きいと、ユーザー インターフェイスを更新してそのモチーフが再生中であることを示す。

参照

モチーフの使い方


DirectSound C++ サンプル

次に示す実行可能アプリケーションは DirectSound API を使用している。これらのアプリケーションを実行するには、[スタート] メニューの [プログラム] をポイントする。次に、[Microsoft DirectX8 SDK] をポイントして、[DirectSound Samples] をクリックする。

  • AdjustSound
  • AmplitudeModulation
  • CaptureSound
  • EnumDevices
  • FullDuplexFilter
  • Play3DSound
  • PlaySound
  • SoundFX
  • StreamData
  • VoiceManagement

ソース コードは次のフォルダにある。

\mssdk\samples\Multimedia\DirectSound

これらのサンプルのほかに、次のフォルダに、チュートリアル アプリケーションのソース ファイルがある。

\mssdk\samples\Multimedia\DirectSound\Tutorials

詳細については、「DirectX Audio C++ チュートリアル」を参照すること。

チュートリアル以外のサンプルは、共通のソース ファイルを使用している。これらのファイルは、DirectMusic および DirectSound の基本的な機能とメディア ファイルの検索などの一般的なタスクに使用される関数およびクラスを実装している。ファイルは次の場所にある。

\mssdk\samples\Multimedia\Common\src

注 DirectX SDK がインストールされているルート ディレクトリが異なる場合は、すべてのパスで "mssdk" をそのディレクトリの名前に置き換える必要がある。


AdjustSound

説明

AdjustSound サンプルは、DirectSound セカンダリ バッファを作成してウェーブ ファイルを再生する方法と、バッファのパラメータを変更する方法を示す。

パス

ソース :(SDK ルート)\Samples\Multimedia\DirectSound\AdjustSound

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DirectSound\Bin

ユーザーズ ガイド

[Sound File] をクリックしてウェーブ ファイルをロードする。[Focus] オプションおよび [Buffer Mixing] オプションを選択する。オプションの選択に応じて、さまざまな設定が [Expected Behavior] に表示される。[Play] をクリックする。何もサウンドが聞こえない場合は、[Status] ペインを確認する。このオプションが選択されていないと、アプリケーションがハードウェアにバッファを作成できない場合がある。

バッファの再生中に、スライダを使って周波数、パン、およびボリュームを動的に調整する。

プログラミング メモ

より少ないコントロールで簡単に DirectSound バッファを設定する方法の例については、PlaySound サンプルを参照すること。

アプリケーションは、DSBCAPS_GLOBALFOCUS または DSBCAPS_STICKYFOCUS を設定するか、そのいずれのフラグも設定せずに IDirectSound8::CreateSoundBuffer を呼び出して、バッファのフォーカスの動作を設定する。バッファのメモリの場所を設定するには、DSBCAPS_LOCHARDWARE または DSBCAPS_LOCSOFTWARE を設定するか、そのいずれのフラグも設定しない。いずれのフラグも設定しない場合は、DirectSound によってハードウェアまはたソフトウェアにバッファが作成される。

パラメータは、IDirectSoundBuffer8::SetFrequency、IDirectSoundBuffer8::SetPan、および IDirectSoundBuffer8::SetVolume を使用して設定される。

参照

DirectSound バッファ


AmplitudeModulation

説明

AmplitudeModulation サンプルは、DirectSound セカンダリ バッファにエフェクトを適用する方法と、エフェクトのパラメータを変更する方法を示す。

パス

ソース :(SDK ルート)\Samples\Multimedia\DirectSound\AmplitudeModulation

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DirectSound\Bin

ユーザーズ ガイド

デフォルトのサウンドを再生するか、[Sound File] をクリックして別のウェーブ ファイルをロードする。エフェクトのパラメータを変更するには、[Wave Form] オプションのいずれかを選択し、スライダを移動して変調の強度を変更する。

プログラミング メモ

アプリケーションは、次の手順を実行してバッファ上のエフェクトの設定とエフェクトのパラメータの変更を行う。

  1. DSBCAPS_CTRLFX フラグを使ってバッファを作成する。
  2. 目的のエフェクトの GUID に guidDSFXClass メンバを設定することによって、DSEFFECTDESC 構造体でエフェクトを記述する。
  3. バッファ記述を IDirectSoundBuffer8::SetFX に渡す。
  4. IDirectSoundBuffer8::GetObjectInPath を呼び出して、エフェクトへのインターフェイス ポインタを取得する。この例では IDirectSoundFXGargle8 を取得する。
  5. OnEffectChanged 関数で、IDirectSoundFXGargle8::SetAllParameters を使用してガーグル エフェクトのパラメータを変更する。

参照

エフェクトの使い方


CaptureSound

説明

CaptureSound アプリケーションは、ウェーブ サウンドをファイルにキャプチャする方法を示す。

パス

ソース :(SDK ルート)\Samples\Multimedia\DirectSound\CaptureSound

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DirectSound\Bin

ユーザーズ ガイド

デバイスおよびフォーマットを選択する。ファイルを作成するか、[Sound File] をクリックして既存のファイルを置き換える。[Record] をクリックしてレコーディングを開始および停止する。

プログラミング メモ

ソース コード フォルダの Readme.txt を参照すること。

参照

ウェーブのキャプチャ


EnumDevices

説明

EnumDevices サンプルは、再生デバイスとキャプチャ デバイスを列挙および作成する方法を示す。

パス

ソース :(SDK ルート)\Samples\Multimedia\DirectSound\EnumDevices

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DirectSound\Bin

ユーザーズ ガイド

ドロップダウン リストから再生デバイスとキャプチャ デバイスを選択する。[Create] をクリックする。

プログラミング メモ

ソース コード フォルダの Readme.txt を参照すること。

参照

サウンド デバイスの列挙、キャプチャ デバイスの列挙


FullDuplexFilter

説明

FullDuplexFilter アプリケーションは、サウンドのキャプチャと再生を同時に行う方法を示す。

パス

ソース :(SDK ルート)\Samples\Multimedia\DirectSound\FullDuplexFilter

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DirectSound\Bin

ユーザーズ ガイド

サウンド カードが全二重構成になっていることと、マイクが接続されていることを確認する。[Output Format] ボックスの一覧からフォーマットを選択する。[Input Format] ボックスにフォーマットの一覧が表示される。1 つを選択する。[OK] をクリックする。全二重が正しく作成されると、[Record] ボタンのある別のダイアログ ボックスが表示される。このボタンをクリックする。マイクに向かって話すと、その声がスピーカから聞こえる。

プログラミング メモ

ソース コード フォルダの Readme.txt を参照すること。


Play3DSound

説明

Play3DSound サンプルは、3D サウンド バッファを作成する方法と、そのプロパティを操作する方法を示す。3DAudio サンプルに似ているが、これは DirectSound API のみを使用する。

パス

ソース :(SDK ルート)\Samples\Multimedia\DirectSound\Play3DSound

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DirectSound\Bin

ユーザーズ ガイド

[Sound File] をクリックしてウェーブ ファイルをロードする。サウンドを再生する。音源の位置がグラフ上に赤い点で示される。このグラフでは、x 軸が左から右に向かい、z 軸が下から上に向かっている。スライダを使って、2 本の座標軸上の移動範囲を変更する。

リスナーはグラフの中央に位置し、デフォルトの向きを向いている。デフォルトの向きは、z 軸の正の方向、つまり画面の上方向である。音源はリスナーの左右前後に移動し、上下には移動しない。

ウィンドウの中央にあるスライダは、リスナーのプロパティ、つまりグローバル サウンド プロパティを制御する。[Defer Settings] をクリックすると、変更は、次に [Apply Settings] をクリックするまで適用されない。

プログラミング メモ

3D コントロールを使用せずに簡単に DirectSound バッファを設定する方法の例については、PlaySound サンプルを参照すること。

このサンプルは、次の手順で IDirectSound3DListener8 インターフェイスを取得する。

  1. DSBCAPS_CTRL3D フラグおよび DSBCAPS_PRIMARYBUFFER フラグを含む DSBUFFERDESC 構造体でバッファを記述する。
  2. バッファ記述を IDirectSound8::CreateSoundBuffer に渡す。これによって、3D 機能を持つプライマリ バッファが作成される。
  3. QueryInterface を呼び出して IDirectSound3DListener8 インターフェイスを取得する。このインターフェイスはグローバル 3D プロパティを制御する。

このサンプルは、次の手順で IDirectSound3DBuffer8 インターフェイスを取得する。

  1. DSBUFFERDESC 構造体にバッファを記述する。このとき、DSBCAPS_CTRL3D 機能のフラグと 3D 仮想化アルゴリズムを設定する。
  2. バッファ記述を IDirectSound8::CreateSoundBuffer に渡して 3D 機能を持つセカンダリ バッファを作成する。
  3. QueryInterface を呼び出して IDirectSound3DBuffer8 インターフェイスを取得する。このインターフェイスは、そのバッファを使って再生されるサウンドの 3D プロパティを制御する。

アプリケーションは、IDirectSound3DListener8::SetAllParameters を呼び出してリスナーのパラメータを設定する。リスナーのプロパティは、DS3DLISTENER 構造体に記述されている。アプリケーションは、IDirectSound3DBuffer8::SetAllParameters を呼び出して DS3DBUFFER 構造体を渡し、音源の位置を設定する。

パラメータを設定すると DS3D_DEFERRED フラグが設定される。変更は、IDirectSound3DListener8::CommitDeferredSettings が呼び出されたときに反映される。このメソッドは、バッファとリスナーの設定の反映を遅らせて、DirectSound による計算が一度で済むようにしている。

参照

3D サウンド


PlaySound

説明

PlaySound サンプルは、DirectSound のセカンダリ バッファ内のウェーブ ファイルを再生する方法を示す。

パス

ソース :(SDK ルート)\Samples\Multimedia\DirectSound\PlaySound

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DirectSound\Bin

ユーザーズ ガイド

[Sound File] をクリックしてウェーブ ファイルをロードする。繰り返し再生する場合は、[Loop Sound] を選択する。[Play] をクリックする。

プログラミング メモ

このサンプルは、DirectSound バッファ内のサウンドを再生するために必要な、次の基本的タスクを示している。

DirectSound の設定

  1. DirectSoundCreate 関数を呼び出して DirectSound オブジェクトを作成する。
  2. IDirectSound8::SetCooperativeLevel を呼び出す。
  3. プライマリ バッファ フォーマットを設定する。このサンプルは、Dsutil.cpp 内の DSUtil_SetPrimaryBufferFormat 関数を呼び出してこの処理を行う。

DirectSound バッファへのウェーブ ファイルのロード

  1. ウェーブ ファイル ヘッダーを読み込んでデータのサイズとフォーマットを取得する。
  2. ウェーブ ファイルのサイズが適切であれば、そのデータと同じフォーマットで、ファイル全体を格納できるサイズのセカンダリ バッファを作成する。ウェーブ ファイルが大きすぎる場合、データはバッファにストリーミングされる。StreamData サンプルを参照すること。
  3. バッファにデータを書き込む。IDirectSoundBuffer8::Lock を呼び出して、バッファへのポインタを取得する。バッファの再生中はデータのストリーミングは行われないので、バッファ全体をロックできる。メモリをコピーした後、IDirectSoundBuffer8::Unlock を呼び出す。

DirectSound バッファの再生

  1. バッファが失われていないかどうかを調べる。失われた場合は復元する。
  2. IDirectSoundBuffer8::Play を呼び出してバッファを再生する。

DirectSound の解放

取得したすべての DirectSound インターフェイスで Release を呼び出す。バッファを解放してから、DirectSound オブジェクトを解放する。

参照

スタティック バッファの書き込みと再生


SoundFX

説明

SoundFX サンプルは、DirectSound で DMO を使用する方法、およびエフェクト パラメータの操作方法を示す。このサンプルは AudioFX サンプルに似ているが、オーディオパスや DirectMusic インターフェイスは使用しない。

パス

ソース :(SDK ルート)\Samples\Multimedia\DirectSound\SoundFX

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DirectSound\Bin

ユーザーズ ガイド

アプリケーションを実行すると、デフォルトのサウンド ファイルがロードされる。別のファイルをロードする場合は、[Open File] をクリックして別のファイルを選択する。

最初は、エフェクトが有効になっていない。[Play] をクリックして、エフェクトなしでサウンドを聞く。

[Stop] をクリックして、バッファを停止する。[Enable] のチェックボックスをオンにし、1 つまたは複数のエフェクトを適用する。サウンドをもう一度再生する。

エフェクトのパラメータを調整するには、[Adjust] でオプション ボタンを選択し、ウィンドウの右側のフレームにある値を変更する。この調整は、サウンドの再生中でも、エフェクトの適用前でも実行できる。

プログラミング メモ

アプリケーションはエフェクトを管理するための CSoundFXManager クラスを実装している。IDirectSoundBuffer8 インターフェイスは、CSoundFXManager::ActivateFX メソッドでバッファにエフェクトを設定するために使用される。Effect パラメータは、インターフェイスからのメッセージに応答して、OnEffectChanged 関数に設定される。

参照

エフェクトの使い方、DirectSound でのエフェクトの使い方


StreamData

説明

StreamData サンプルは、ウェーブ ファイルを DirectSound セカンダリ バッファにストリーミングする方法を示す。PlaySound サンプルに似ているが、これにはストリーミングのサポートが追加されている。

パス

ソース :(SDK ルート)\Samples\Multimedia\DirectSound\StreamData

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DirectSound\Bin

ユーザーズ ガイド

[Sound File] をクリックしてウェーブ ファイルをロードする。繰り返し再生する場合は、[Loop Sound] を選択する。[Play] をクリックする。

プログラミング メモ

このサンプルは、DirectSound セカンダリ バッファ内のストリーミング サウンドを再生するために必要な基本的タスクを示している。

DirectSound の設定

  1. DirectSoundCreate8 関数を呼び出して DirectSound オブジェクトを作成する。
  2. IDirectSound8::SetCooperativeLevel を呼び出す。
  3. プライマリ バッファ フォーマットを設定する。このサンプルは、Dsutil.cpp 内の DSUtil_SetPrimaryBufferFormat 関数を呼び出してこの処理を行う。

DirectSound バッファの作成と通知の設定

  1. ウェーブ ファイル ヘッダーを読み込んでデータのサイズとフォーマットを取得する。
  2. DirectSound バッファのサイズを選択する。このサンプルでは、バッファは 3 秒間のデータを保持する。
  3. 選択したサイズで、ウェーブ ファイルと同じフォーマットの DirectSound バッファを作成する。DSBCAPS_CTRLPOSITIONNOTIFY フラグも設定する。これによって、再生がバッファ内の特定のポイントに到達するたびにバッファによって通知イベントが送信されるようになる。ハードウェア バッファが位置の通知をサポートしていないドライバでは、このフラグの使用はソフトウェア バッファに制限される。
  4. バッファから IDirectSoundNotify8 インターフェイスを取得し、IDirectSoundNotify8::SetNotificationPositions を呼び出して、バッファの通知を設定する。InitDSoundNotification 関数を参照すること。再生カーソルは、通知位置を渡すとき、Win32® イベントを通知する。

DirectSound バッファの再生

  1. バッファが失われていないかどうかを調べ、失われた場合は IDirectSoundBuffer8::Restore を呼び出す。
  2. バッファ全体にファイルのデータを書き込む。
  3. DSBPLAY_LOOPING フラグを設定して IDirectSoundBuffer8::Play を呼び出す。ループ フラグを設定すると、バッファはデータの最初のバッチを再生した後に続けて再生を行う。

通知が行われているかどうかの確認

  1. メッセージ ループで、または MsgWaitForMultipleObjects を呼び出して独立したスレッドで、通知されたイベントを探す。
  2. バッファの通知イベントを受信している場合は、バッファの最後に再生を終了したセクションをロックして、そこに新しいデータを書き込む。HandleNotification 関数を参照すること。

バッファの停止

イベント通知を処理する際は、バッファに書き込まれたデータ量を常時追跡する。ウェーブ ファイル全体がバッファに書き込まれ、その内容すべてが DirectSound によって再生されたら、バッファを手動で停止する必要がある。手動で停止しないと、バッファはループし続ける。

参照

ストリーム バッファの使い方


VoiceManagement

説明

VoiceManagement サンプルは、DirectSound セカンダリ バッファの作成時にダイナミック ボイス管理を実装する方法を示す。

パス

ソース :(SDK ルート)\Samples\Multimedia\DirectSound\VoiceManagement

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DirectSound\Bin

ユーザーズ ガイド

[Sound File] をクリックしてウェーブ ファイルをロードする。[Voice Allocation Flags]、[Buffer Priority]、および [Voice Management Flags] の各オプションを選択する。選択したオプションのエフェクトの説明が [Expected Behavior] に表示される。バッファを作成し、[Play] をクリックしてサウンドを再生する。

プログラミング メモ

ボイス管理フラグを使用するには、DSBCAPS_LOCDEFER を使ってバッファを作成する必要がある。これを使用せずに作成すると、DirectSound は、実行時にハードウェアとソフトウェアのいずれのバッファも動的に配置できなくなる。

バッファの再生時に、有効な組み合せのボイス管理フラグを設定して IDirectSoundBuffer8::Play を呼び出す。サンプルを実行して、フラグのさまざまな組み合せの結果を観察する。

参照

ダイナミック ボイス管理


DirectMusic C/C++ リファレンス

ここでは、DirectMusic が提供する API 要素のリファレンス情報を記述する。リファレンス情報は以下のカテゴリに分類される。

  • DirectMusic インターフェイス
  • DirectMusic メッセージ
  • DirectMusic 構造体
  • DLS 構造体
  • DirectMusic のファイル形式
  • DirectMusic のファイル データ構造体
  • 標準トラック パラメータ
  • DirectMusic 列挙型
  • DirectMusic 戻り値


DirectMusic インターフェイス

ここでは、DirectMusic COM インターフェイスのリファレンスを記述する。

現在のバージョンのインターフェイスは、名前の最後に "8" を付けて、宣言や定義を行う。最新バージョンのインターフェイスを確実に使用するには、ポインタの宣言時にこのサフィックスを必ず付ける。

注 IKsControl および IReferenceClock は、この規則の例外とする。

メソッドが取得するインターフェイスは、常に基本バージョンである。基本バージョンよりも新しいバージョンが存在する場合は、次の例のように、QueryInterface を呼び出してそれを取得する必要がある。lpdmBand は、IDirectMusicBand8 インターフェイス ポインタである。

IDirectMusicSegment * lpdmseg;
IDirectMusicSegment8 * lpdmseg8;

HRESULT hr = lpdmBand->CreateSegment(&lpdmseg);
if (SUCCEEDED(hr))
{
    hr = lpdmseg->QueryInterface(IID_IDirectMusicSegment8,
        (LPVOID *)&lpdmseg8);
}

インターフェイスの新しいバージョンがない場合、サフィックス 8 の付いたインターフェイス名は、ただの定義である。たとえば、IDirectMusicGraph8 は、あらゆる点で IDirectMusicGraph と等しい。このような場合、新しいインターフェイスを問い合わせる必要はないが、問い合わせをすることは何の害もない上に、DirectX の将来のバージョンに備えて、コードの保守性を高めることができる。

IN パラメータとしてインターフェイス ポインタを渡すことができる場合は、古いバージョンを受け入れるようにメソッドが宣言されていても、新しいバージョンを渡すことができる。たとえば、IDirectMusicPerformance8::PlaySegmentEx には、IDirectMusicSegment または IDirectMusicSegment8 へのポインタを渡すことができる。

このドキュメントは、インターフェイスの最新バージョンに限定した、完全なリファレンス トピックを収録している。IDirectMusicGraph8 のような定義が存在する場合、インターフェイスはその名前で記載されている。

  • IDirectMusic8
  • IDirectMusicAudioPath8
  • IDirectMusicBand8
  • IDirectMusicBuffer8
  • IDirectMusicChordMap8
  • IDirectMusicCollection8
  • IDirectMusicComposer8
  • IDirectMusicContainer8
  • IDirectMusicDownload8
  • IDirectMusicDownloadedInstrument8
  • IDirectMusicGetLoader8
  • IDirectMusicGraph8
  • IDirectMusicInstrument8
  • IDirectMusicLoader8
  • IDirectMusicObject8
  • IDirectMusicPatternTrack8
  • IDirectMusicPerformance8
  • IDirectMusicPort8
  • IDirectMusicPortDownload8
  • IDirectMusicScript8
  • IDirectMusicSegment8
  • IDirectMusicSegmentState8
  • IDirectMusicSong8
  • IDirectMusicStyle8
  • IDirectMusicThru8
  • IDirectMusicTool8
  • IDirectMusicTrack8
  • IKsControl
  • IReferenceClock


IDirectMusic8

IDirectMusic8 インターフェイスは、バッファ、ポート、マスタ クロックを管理するためのメソッドを提供する。各アプリケーションは、このインターフェイスのインスタンスを複数作成すべきではない。

IDirectMusic8 は IDirectMusic を引き継ぎ、新たに SetExternalMasterClock というメソッドを追加する。

このインターフェイスを作成するヘルパー関数は存在しない。アプリケーションは COM の CoCreateInstance 関数、IDirectMusicPerformance8::Init メソッド、または IDirectMusicPerformance8::InitAudio メソッドを使って DirectMusic オブジェクトを作成する。

IDirectMusic8 インターフェイスのメソッドは、以下のグループにまとめることができる。

アクティブにする | Activate
バッファ | CreateMusicBuffer
リンク | SetDirectSound
ポート | CreatePort
 | EnumPort
 | GetDefaultPort
タイミング | EnumMasterClock
 | GetMasterClock
 | SetExternalMasterClock
 | SetMasterClock

すべての COM インターフェイスは IUnknown インターフェイスのメソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTMUSIC8 型は、IDirectMusic8 インターフェイスへのポインタとして定義されている。

typedef IDirectMusic8 *LPDIRECTMUSIC8;

動作環境

ヘッダー : dmusicc.h で宣言。


IDirectMusic8::Activate

IDirectMusic8::Activate メソッドは、このインターフェイスによって作成されたすべてのポートをアクティブまたは非アクティブにする。

HRESULT Activate(
  BOOL fEnable
);

パラメータ

fEnable
DirectMusic のこのインスタンスで作成されたすべてのポートをアクティブ (TRUE) または非アクティブ (FALSE) にする。

戻り値

成功した場合は S_OK を返す。

失敗した場合は DSERR_NODRIVER を返し、サウンド ドライバがないことを示す。

注意

アプリケーションがバックグラウンドで音楽を再生する必要がない場合、入力フォーカスを失った段階で IDirectMusic8::Activate (FALSE) を呼び出すべきである。この結果、入力フォーカスが置かれているほかのアプリケーションはこれらのポートにアクセスできる。入力フォーカスが再びこのアプリケーションに置かれた段階で、Activate (TRUE) を呼び出し、割り当てられているすべてのポートを使用可能にすべきである。

動作環境

ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicPort8::Activate


IDirectMusic8::CreateMusicBuffer

ポートにシーケンス化されているミュージック メッセージを保持する、DirectMusicBuffer オブジェクトを作成する。ポートの追加時にバッファ管理はパフォーマンスによって処理されるため、ほとんどのアプリケーションはこのメソッドを呼び出す必要がない。

HRESULT CreateMusicBuffer(
  LPDMUS_BUFFERDESC pBufferDesc,
  LPDIRECTMUSICBUFFER *ppBuffer,
  LPUNKNOWN pUnkOuter
);

パラメータ

pBufferDesc
作成されるミュージック バッファの記述を保持する DMUS_BUFFERDESC 構造体のアドレス。ポインタを渡す前に、アプリケーションはこの構造体の dwSize メンバを初期化しなければならない。
ppBuffer
IDirectMusicBuffer8 インターフェイス ポインタを受け取る変数のアドレス。
pUnkOuter
COM 集成体の場合は、制御オブジェクトの IUnknown インターフェイスのアドレス。集成体は現在サポートされていないため、この値は NULL に設定しなければならない。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_INVALIDARG
CLASS_E_NOAGGREGATION
E_NOINTERFACE
E_OUTOFMEMORY
E_POINTER

動作環境

ヘッダー : dmusicc.h で宣言。


IDirectMusic8::CreatePort

DirectMusic ポートのオブジェクトを作成する。

HRESULT CreatePort(
  REFCLSID rclsidPort,
  LPDMUS_PORTPARAMS pPortParams,
  LPDIRECTMUSICPORT *ppPort,
  LPUNKNOWN pUnkOuter
);

パラメータ

rclsidPort
IDirectMusicPort8 インターフェイスの作成先となるポートを識別する GUID への参照 (C++) またはアドレス (C)。IDirectMusic8::EnumPort メソッドを使って GUID を取得する。このパラメータが GUID_NULL の場合は、返されるポートがデフォルト ポートになる。詳細については、「デフォルト ポート」を参照すること。
pPortParams
ポートのパラメータを保持する DMUS_PORTPARAMS8 構造体のアドレス。このメソッドを呼び出す前に、この構造体の dwSize メンバを初期化しなければならない。
ppPort
IDirectMusicPort インターフェイス ポインタを受け取る変数のアドレス。
pUnkOuter
COM 集成体の場合は、制御オブジェクトの IUnknown インターフェイスのアドレス。集成体は現在サポートされていないため、この値は NULL でなければならない。

戻り値

成功した場合は S_OK を返す。指定したパラメータが利用できない場合は S_FALSE を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_DSOUND_NOT_SET
E_INVALIDARG
CLASS_E_NOAGGREGATION
E_NOINTERFACE
E_OUTOFMEMORY
E_POINTER

注意

ポートはデフォルトで、作成時には非アクティブになっている。IDirectMusic8::Activate または IDirectMusicPort8::Activate を呼び出すことで、これをアクティブにしなければならない。

すべてのパラメータが取得できない場合は、DMUS_PORTPARAMS8 構造体を以下のように変更して、ポートの利用できるパラメータと一致させる。

エントリ内では、構造体の dwValidParams メンバによって、構造体内の有効なメンバが示される。構造体のメンバについてフラグを設定していない場合は、ポートの作成時に、そのパラメータにデフォルト値が設定される。

値が返されると、dwValidParams 内のフラグによって、どのポート パラメータが設定されたかが示される。特定のパラメータを指定せず、デフォルト値に設定した場合、そのフラグは渡されたパラメータに追加される。

指定したパラメータをポートがサポートしていても、パラメータの値が範囲外の場合は、*pPortParams 内のパラメータ値が変更される。この場合、dwValidParams 内のフラグは設定されたままであるが、S_FALSE が返され、値が変更されたことが示される。

次のサンプル コードは、アプリケーションがどのようにリバーブ機能を要求し、それを取得できたかどうかを判別する方法を示している。ポート プロパティのチェックおよび設定の別の方法については、「DirectMusic ポートのプロパティ セット」を参照すること。

DMUS_PORTPARAMS8 params;

ZeroMemory(&params, sizeof(params));
params.dwSize = sizeof(params);
params.dwValidParams = DMUS_PORTPARAMS_EFFECTS;
params.dwEffectFlags = DMUS_EFFECT_REVERB;
HRESULT hr = pDirectMusic->CreatePort(guidPort, &params,
        &port, NULL);
if (SUCCEEDED(hr))
{
    fGotReverb = TRUE;
    if (hr == S_FALSE)
    {
        if (!(params.dwValidParams & DMUS_PORTPARAMS_EFFECTS))
        {
            // デバイスはどのエフェクトもサポートしない。
            fGotReverb = FALSE;
        }
        else if (!(params.dwEffectFlags & DMUS_EFFECT_REVERB))
        {
            // デバイスはエフェクトを認識するが、
            // リバーブを割り当てることはできない。
            fGotReverb = FALSE;
        }
    }
}

動作環境

ヘッダー : dmusicc.h で宣言。


IDirectMusic8::EnumMasterClock

DirectMusic がマスタ クロックとして利用できるクロックを列挙する。このメソッドを呼び出すたびに、1 つのクロックに関する情報を取得する。

HRESULT EnumMasterClock(
  DWORD dwIndex,
  LPDMUS_CLOCKINFO lpClockInfo
);

パラメータ

dwIndex
記述を取り出したいクロックのインデックス番号。最初に呼び出すときはこのパラメータを 0 に設定し、それ以降は呼び出しのたびに 1 ずつ大きくすべきである。S_FALSE が返されるまで呼び出しを続ける。
lpClockInfo
クロックの記述を受け取る DMUS_CLOCKINFO8 構造体のアドレス。ポインタを渡す前に、アプリケーションはこの構造体の dwSize メンバを初期化しなければならない。

戻り値

成功した場合は S_OK を返す。指定したインデックス番号を持つクロックが存在しない場合は S_FALSE を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_INVALIDARG
E_NOINTERFACE
E_POINTER

注意

アプリケーションはクロックのインデックス番号を信頼したり保存すべきではない。再起動またはハードウェアの追加や削除が行われると、クロックのインデックス番号が変化する可能性がある。

動作環境

ヘッダー : dmusicc.h で宣言。

参照

IDirectMusic8::SetMasterClock、IDirectMusic8::GetMasterClock


IDirectMusic8::EnumPort

システムに接続されている DirectMusic ポートの能力を列挙および取得する。このメソッドを呼び出すたびに、1 つのポートに関する情報を取得する。

HRESULT EnumPort(
  DWORD dwIndex,
  LPDMUS_PORTCAPS pPortCaps
);

パラメータ

dwIndex
能力を取り出したいポートのインデックス番号。最初に呼び出すときはこのパラメータを 0 に設定し、それ以降は呼び出しのたびに 1 ずつ大きくすべきである。S_FALSE が返されるまで呼び出しを続ける。
pPortCaps
ポートの能力を受け取る DMUS_PORTCAPS 構造体のアドレス。ポインタを渡す前に、この構造体の dwSize メンバを初期化しなければならない。

戻り値

成功した場合は S_OK を返す。指定したインデックス値を持つポートが存在しない場合は S_FALSE を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_INVALIDARG
E_NOINTERFACE
E_POINTER

注意

アプリケーションはポートのインデックス番号を信頼したり保存すべきではない。再起動またはハードウェアの追加や削除が行われると、ポートのインデックス番号が変化する可能性がある。

動作環境

ヘッダー : dmusicc.h で宣言。


IDirectMusic8::GetDefaultPort

デフォルトの出力ポートの GUID を取得する。これは、IDirectMusic8::CreatePort に GUID_NULL を渡したときに作成されるポートである。

HRESULT GetDefaultPort(
  LPGUID pguidPort
);

パラメータ

pguidPort
デフォルト ポートの GUID を受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は E_POINTER を返す。

動作環境

ヘッダー : dmusicc.h で宣言。

参照

デフォルト ポート


IDirectMusic8::GetMasterClock

現在 DirectMusic マスタ クロックとして設定されているクロックの GUID と、IReferenceClock インターフェイスへのポインタを取得する。

HRESULT GetMasterClock(
  LPGUID pguidClock,
  IReferenceClock **ppReferenceClock
);

パラメータ

pguidClock
マスタ クロックの GUID を受け取る変数のアドレス。この値が必要ない場合、アプリケーションは NULL を渡してもよい。
ppReferenceClock
このクロックの IReferenceClock を受け取る変数のアドレス。この値が必要ない場合、アプリケーションは NULL を渡してもよい。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_NOINTERFACE
E_POINTER

注意

アプリケーションは IReferenceClock インターフェイスを使い終わった後で、このインターフェイスを解放しなければならない。

動作環境

ヘッダー : dmusicc.h で宣言。

参照

IDirectMusic8::SetMasterClock


IDirectMusic8::SetDirectSound

シンセサイザからの出力用に、DirectMusic を DirectSound オブジェクトに接続する。

ほとんどのアプリケーションはこのメソッドを使用しない。通常、DirectSound オブジェクトの作成とパフォーマンスへの接続は、IDirectMusicPerformance8::InitAudio によって行われる。

HRESULT SetDirectSound(
  LPDIRECTSOUND pDirectSound,
  HWND hWnd
);

パラメータ

pDirectSound
出力用に使う IDirectSound8 インターフェイスのアドレス。このパラメータが NULL の場合、DirectSound オブジェクトが作成され、協調レベルが設定される (「注意」を参照すること)。このパラメータに IDirectSound ポインタが含まれる場合は、アプリケーションが協調レベルを設定しなければならない。
hWnd
この呼び出しによって作成される、DirectSound オブジェクトのウィンドウ ハンドル。この値が NULL の場合、現在の前面ウィンドウがフォーカス ウィンドウとして設定される。「注意」を参照すること。

pDirectSound が有効なインターフェイスの場合、このパラメータは無視される。IDirectSound8::SetCooperativeLevel の呼び出しでは、アプリケーションが有効なウィンドウ ハンドルを提供する必要があるためである。

戻り値

成功した場合は S_OK を返す。

失敗した場合は DMUS_E_DSOUND_ALREADY_SET を返す。

注意

指定した DirectSound オブジェクトは、すべてのポート上でオーディオをレンダリングする際に使われるオブジェクトである。このデフォルト値は、IDirectMusicPort8::SetDirectSound メソッドを使って上書きできる。

IDirectMusic8::SetDirectSound メソッドを呼び出すたびに、既存の DirectSound オブジェクトは解放される。

pDirectSound が NULL の場合、DirectSound を使うポートがアクティブになるまで新しい DirectSound オブジェクトは作成されない。DirectSound オブジェクトは、それを使用している最後のポートが非アクティブになると自動的に解放される。

DirectSound オブジェクトを自分で作成した場合は、すべてのポートを非アクティブにした後で、このメソッドの pDirectSound パラメータに NULL を設定して呼び出すことによって解放できる (アクティブなポートに対して SetDirectSound を呼び出すことは誤りである)。

hWnd パラメータに NULL を渡すと、現在の前面ウィンドウのハンドルを DirectSound に渡すことができる。ただし、アプリケーション ウィンドウが初期化中に前面にあると想定しないこと。通常、最上位レベルのアプリケーション ウィンドウ ハンドルを DirectMusic および DirectSound に渡さなければならない。IDirectSound8::SetCooperativeLevel の「注意」を参照すること。

動作環境

ヘッダー : dmusicc.h で宣言。


IDirectMusic8::SetExternalMasterClock

DirectMusic マスタ クロックに既存のクロック オブジェクトを設定する。すべての DirectMusic アプリケーションは、ただ 1 つのマスタ クロックを使う。

HRESULT SetExternalMasterClock(
  IReferenceClock *pClock
);

パラメータ

pClock
クロックを指定する IReferenceClock インターフェイス ポインタ。

戻り値

成功した場合は S_OK を返す。

失敗した場合は DMUS_E_PORTS_OPEN を返す。

注意

実行中のほかのアプリケーションも DirectMusic を使っている場合、そのアプリケーションがシャットダウンするまではマスタ クロックを変更できない。

動作環境

ヘッダー : dmusicc.h で宣言。

参照

IDirectMusic8::GetMasterClock、IDirectMusic8::EnumMasterClock、IDirectMusic8::SetMasterClock


IDirectMusic8::SetMasterClock

IDirectMusic8::EnumMasterClock を呼び出した際に取得された GUID によって識別されるクロックを、DirectMusic のマスタ クロックに設定する。すべての DirectMusic アプリケーションは、ただ 1 つのマスタ クロックを使う。

HRESULT SetMasterClock(
  REFGUID rguidClock
);

パラメータ

rguidClock
DirectMusic のマスタ クロックとして設定されるクロックを識別する GUID への参照 (C++) またはアドレス (C)。このパラメータは、IDirectMusic8::EnumMasterClock メソッドが返した GUID でなければならない。

戻り値

成功した場合は S_OK を返す。

失敗した場合は DMUS_E_PORTS_OPEN を返す。

注意

実行中のほかのアプリケーションも DirectMusic を使っている場合、そのアプリケーションがシャットダウンするまではマスタ クロックを変更できない。

ほどんどのアプリケーションは SetMasterClock を呼び出す必要がない。システム クロック以外のハードウェア タイマとの厳密な同期を必要としない限り、このメソッドを呼び出すべきではない。

動作環境

ヘッダー : dmusicc.h で宣言。

参照

IDirectMusic8::SetExternalMasterClock、IDirectMusic8::GetMasterClock、IDirectMusic8::EnumMasterClock


IDirectMusicAudioPath8

IDirectMusicAudioPath8 インターフェイスは、パフォーマンスからプライマリ サウンド バッファまでのデータ フローの段階を示す。オーディオパスは、IDirectMusicPerformance8::CreateAudioPath メソッドを使って、オーディオパス構成オブジェクトから作成できる。標準オーディオパスは、IDirectMusicPerformance8::CreateStandardAudioPath を使って作成できる。また、標準デフォルト パスは、IDirectMusicPerformance8::InitAudio を使って作成でき、IDirectMusicPerformance8::GetDefaultAudioPath を使って取得できる。

IDirectMusicAudioPath8 インターフェイスを IDirectMusicPerformance8::PlaySegmentEx に渡すと、そのオーディオパス上のセグメントを演奏できる。

IDirectMusicAudioPath8 は、IDirectMusicAudioPath の型定義である。2 つのインターフェイス名は入れ替え可能である。

IDirectMusicAudioPath8 インターフェイスには次のメソッドがある。

IDirectMusicAudioPath8 | Activate
 | ConvertPChannel
 | GetObjectInPath
 | SetVolume

すべての COM インターフェイスは IUnknown インターフェイスのメソッドを継承する。このインターフェイスは、次の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicAudioPath8::Activate

オーディオパスをアクティブまたは非アクティブにする。

HRESULT Activate(
  BOOL fActivate
);

パラメータ

fActivate
パスをアクティブ (TRUE) にするか、または非アクティブ (FALSE) にするかを指定するブール値。

戻り値

成功した場合は S_OK を返す。オーディオパスが既に要求された状態になっている場合は S_FALSE を返す。

注意

このメソッドの動作は、IDirectMusicPort8::Activate の動作とは異なる。ポートを非アクティブにすると、ポートではサウンドが生成されなくなるが、パフォーマンスによってセグメントの再生を継続できる。オーディオパスを非アクティブにすると、すべての再生が停止して、セグメントを再生できなくなる。

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicAudioPath8::ConvertPChannel

セグメント内のパフォーマンス チャンネルと、オーディオパスのパフォーマンスに割り当てられた同等のチャンネルを平行移動する。アプリケーションは通常、このメソッドを必要としないが、トラックなどのコンポーネントで使用されることがある。

HRESULT ConvertPChannel(
  DWORD dwPChannelIn,
  DWORD *pdwPChannelOut
);

パラメータ

dwPChannelIn
変換するパフォーマンス チャンネルを指定する値。
pdwPChannelOut
仮想パフォーマンス チャンネルを受け取る DWORD 変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_NOT_FOUND
E_POINTER

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicAudioPath8::GetObjectInPath

オーディオパス内のオブジェクトに対してインターフェイスを取得する。

RESULT GetObjectInPath(
  DWORD dwPChannel,
  DWORD dwStage,
  DWORD dwBuffer,
  REFGUID guidObject,
  DWORD dwIndex,
  REFGUID iidInterface,
  void ** ppObject
);

パラメータ

dwPChannel
検索するパフォーマンス チャンネルまたはすべてのチャンネルを検索する DMUS_PCHANNEL_ALL。最初のチャンネルは 0 番になる。「注意」を参照すること。
dwStage
パスのステージ。次のいずれかの値を指定する。
DMUS_PATH_AUDIOPATH_GRAPH
オーディオパス ツールグラフを取得する。存在しなければ作成される。
DMUS_PATH_AUDIOPATH_TOOL
オーディオパス ツールグラフからツールを取得する。
DMUS_PATH_BUFFER
DirectSound バッファを取得する。
DMUS_PATH_BUFFER_DMO
バッファの DMO を取得する。DMO インターフェイスの詳細については、「IDirectSoundBuffer8::GetObjectInPath」を参照すること。
DMUS_PATH_MIXIN_BUFFER
グローバル ミックスイン バッファを取得する。
DMUS_PATH_MIXIN_BUFFER_DMO
グローバル ミックスイン バッファ内の DMO を取得する。
DMUS_PATH_PERFORMANCE
パフォーマンスを取得する。
DMUS_PATH_PERFORMANCE_GRAPH
パフォーマンス ツールグラフを取得する。存在しなければ作成される。
DMUS_PATH_PERFORMANCE_TOOL
パフォーマンス ツールグラフからツールを取得する。
DMUS_PATH_PORT
シンセサイザを取得する。
DMUS_PATH_PRIMARY_BUFFER
プライマリ バッファを取得する。
dwBuffer
dwStage が DMUS_PATH_BUFFER_DMO または DMUS_PATH_MIXIN_BUFFER_DMO の場合、DMO が常駐するバッファのインデックス。dwStage が DMUS_PATH_BUFFER または DMUS_PATH_MIXIN_BUFFER の場合、バッファのインデックス。それ以外の場合、0 でなければならない。
guidObject
オブジェクトのクラス識別子、または任意のクラスのオブジェクトを検索する GUID_All_Objects。dwStage によって指定されたステージに存在するオブジェクトが単一のクラスに限定されている場合は無視される。このパラメータは GUID_NULL に設定できる。
dwIndex
一致するオブジェクトのリストに含まれるオブジェクトのインデックス。0 に設定して、最初の適合オブジェクトを検索する。dwStage が DMUS_PATH_BUFFER または DMUS_PATH_MIXIN_BUFFER の場合、このパラメータは無視され、dwBuffer によってバッファ インデックスが指定される。
iidInterface
IID_IDirectMusicTool など、目的のインターフェイスの識別子。
ppObject
要求されたインターフェイスへのポインタを受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_NOT_FOUND
E_INVALIDARG
E_OUTOFMEMORY
E_NOINTERFACE
E_POINTER

注意

チャンネル固有でないステージについては、dwPChannel の値は 0 に設定しなければならない。次のステージのオブジェクトはチャンネル固有なので、dwPChannel にチャンネル番号または DMUS_PCHANNEL_ALL を設定して取得できる。

DMUS_PATH_AUDIOPATH_TOOL
DMUS_PATH_BUFFER
DMUS_PATH_BUFFER_DMO
DMUS_PATH_PERFORMANCE_TOOL
DMUS_PATH_PORT
DMUS_PATH_SEGMENT_TOOL

不必要なオブジェクトをフィルタリングによって除外するときのパラメータの優先順位は次のとおりである。

  1. dwStage。
  2. guidObject。この値が GUID_All_Objects でない場合、クラス識別子が guidObject に等しいオブジェクトだけが検索される。ただし、DMUS_PATH_AUDIOPATH_GRAPH などの、オブジェクトが単一のクラスに限定されるステージでは、このパラメータは無視される。
  3. dwPChannel。ステージがチャンネル固有で、この値が DMUS_PCHANNEL_ALL でない場合、そのチャンネルのオブジェクトだけが検索される。
  4. dwBuffer。このパラメータが使用されるのは、dwStage が DMUS_PATH_BUFFER、DMUS_PATH_MIXIN_BUFFER、DMUS_PATH_BUFFER_DMO、または DMUS_PATH_MIXIN_BUFFER_DMO の場合だけである。
  5. dwIndex。

一致するオブジェクトが見つかっても、iidInterface で指定されているインターフェイスが見つからない場合、このメソッドは失敗する。

次のサンプル コードは、オーディオパス内のバッファを列挙する方法を示している。_stprintf 関数は Tchar.h で宣言される。

void DumpAudioPathBuffers(
        IDirectMusicAudioPath *pDirectMusicAudioPath)
{
    TCHAR tcstrText[256];
    DWORD dwBuffer = 0;
    IDirectSoundBuffer *pDirectSoundBuffer;

    while(S_OK == pDirectMusicAudioPath->GetObjectInPath(
        DMUS_PCHANNEL_ALL, DMUS_PATH_BUFFER, dwBuffer,
        GUID_NULL, 0, IID_IDirectSoundBuffer,
        (void**) &pDirectSoundBuffer))
    {
        _stprintf( tcstrText, _T("Found buffer %x.\n"),
                pDirectSoundBuffer);
        OutputDebugString( tcstrText );
        dwBuffer++;
        pDirectSoundBuffer->Release();
    }

    if( dwBuffer == 0 )
    {
        OutputDebugString( _T("No buffers in audiopath.\n") );
    }
}

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegmentState8::GetObjectInPath、オーディオパスからのオブジェクトの取得


IDirectMusicAudioPath8::SetVolume

パスのオーディオ ボリュームを設定する。

HRESULT SetVolume(
  long lVolume,
  DWORD dwDuration
);

パラメータ

lVolume
減衰を指定する値。1/100 デシベル単位で指定する。この値の範囲は -9600 ～ 0 である。0 は最大ボリュームを表す。
dwDuration
どのぐらいの時間が経過すればボリューム変更が発生するかを指定する値。ミリ秒単位で指定する。この値に 0 を指定すると、即時実行が保証される。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_NOT_INIT
E_INVALIDARG

動作環境

ヘッダー : dmusici.h で宣言。で宣言。


IDirectMusicBand8

IDirectMusicBand8 インターフェイスは、DirectMusic バンド オブジェクトを表す。バンドを使って、一連のパフォーマンス チャンネルの音色の選択肢とミキサ設定を指定する。概要については、「バンドの使い方」を参照すること。バンドは、専用のファイルに保存しても、スタイルのバンド リストやセグメントのバンド トラックに埋め込んでもよい。

IDirectMusicBand8 は、IDirectMusicBand の定義である。2 つのインターフェイス名は入れ替え可能である。

DirectMusicBand オブジェクトは、自らのデータをロードするために IPersistStream と IDirectMusicObject8 の各インターフェイスもサポートしている。

IDirectMusicBand8 インターフェイスには次のメソッドがある。

セグメント作成 | CreateSegment
音色データ | Download
 | Unload

すべての COM インターフェイスは IUnknown インターフェイスのメソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicBand8::CreateSegment

バンド内でボリューム、パン、転調、およびパッチ変更コマンドを動的に実行するために、演奏可能な DirectMusicSegment オブジェクトを作成する。

HRESULT CreateSegment(
  IDirectMusicSegment** ppSegment
);

パラメータ

ppSegment
作成されたセグメントへのポインタを受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_FAIL
E_OUTOFMEMORY
E_POINTER

注意

バンドからセグメントを作成する方法の例については、「プログラムによるバンド チェンジの実行」を参照すること。

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicBand8::Download

バンド内の音色の DLS データをパフォーマンス オブジェクトにダウンロードする。

HRESULT Download(
  IDirectMusicPerformance* pPerformance
);

パラメータ

pPerformance
音色のダウンロード先のパフォーマンス。パフォーマンスはパフォーマンス チャンネルから DirectMusic ポートへのマッピングを管理する。

戻り値

成功した場合は S_OK または DMUS_S_PARTIALDOWNLOAD を返す (「注意」を参照すること)。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_NOT_INIT
E_OUTOFMEMORY
E_POINTER

注意

このメソッドは、IDirectMusicPerformance8::DownloadInstrument メソッドを呼び出すことで、バンド内でそれぞれの音色をダウンロードする。DownloadInstrument は音色のパフォーマンス チャンネルを使って適切なポートを見つけ、そのポートに対して IDirectMusicPort8::DownloadInstrument メソッドを呼び出す。

バンドのダウンロードが終わると、そのバンド内の音色は、プログラム チェンジ MIDI メッセージにより個別に選択するか、IDirectMusicBand8::CreateSegment メソッドを呼び出して作成したバンド セグメントを再生することにより一度にすべてを選択できる。

ダウンロードしたバンドはシンセサイザ リソースを使うため、必要のないときは IDirectMusicBand8::Unload メソッドを使ってアンロードしなければならない。

このメソッドは、ポートが DLS をサポートしていなくても、S_OK を返すことがある。

ダウンロードが完全に失敗した場合は、DMUS_E_NOT_INIT が返される。これは通常、初期化されたポートにパフォーマンスが正常に接続されなかったことを意味する。これは完全な失敗であるため、後で IDirectMusicBand8::Unload を呼び出す必要はない。

ダウンロードが一部成功した場合は、DMUS_S_PARTIALDOWNLOAD が返される。これは、正常にダウンロードできた音色とダウンロードできなかった音色があることを意味する。その原因は通常、パフォーマンスとポートの設定においてプログラミング エラーが発生したためである。問題を特定する最良の方法は、Dmime.dll、Dmband.dll、および Dmsynth.dll のデバッグ トレースを 1 に設定することである (「DirectX Audio プロジェクトのデバッグ」を参照すること)。

部分的なダウンロードが発生する一般的な原因を以下に示す。

  • バンドは、パフォーマンスに対して設定されていないパフォーマンス チャンネル上に音色を持っている (IDirectMusicPerformance8::AssignPChannelBlock の使用による)。
  • バンドは、ポートに割り当てられていないチャンネル グループのパフォーマンス チャンネル上に音色を持っている。
  • バンドは、音色のダウンロード先となるシンセサイザと互換性のない DLS フォーマットの音色を持っている。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicBand8::Unload


IDirectMusicBand8::Unload

IDirectMusicBand8::Download を使って以前にダウンロードしたバンド内の音色の DLS データをアンロードする。

HRESULT Unload(
  IDirectMusicPerformance* pPerformance
);

パラメータ

pPerformance
音色のアンロード元のパフォーマンス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_NOT_INIT
DMUS_E_NOT_FOUND

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPort8::UnloadInstrument


IDirectMusicBuffer8

IDirectMusicBuffer8 は、ポートによってシーケンス化される、タイム スタンプの割り当てられたデータ (通常は MIDI メッセージ形式) を含むバッファを表す。セグメントとは異なり、バッファはわずかな量のデータ (通常は 200ms 未満) を保持し、アプリケーションはイベントの微小性を制御する際にこのデータを利用する。

IDirectMusicBuffer8 は IDirectMusicBuffer の型定義である。2 つのインターフェイス名は入れ替え可能である。

アプリケーションが独自のシーケンス化を行わない限り、このインターフェイスのこのメソッドを使う必要はない。

IDirectMusicPort8::PlayBuffer メソッドか IDirectMusicPort8::Read メソッドのどちらかを呼び出してバッファをポートに渡すまでは、バッファ オブジェクトはポート オブジェクトから完全に独立している。その後アプリケーションはバッファを解放して、再利用を可能にする。

IDirectMusicBuffer8 インターフェイスのメソッドは、以下のグループにまとめることができる。

データ | Flush
 | GetNextEvent
 | GetRawBufferPtr
 | PackStructured
 | PackUnstructured
 | ResetReadPtr
パラメータ | GetBufferFormat
 | GetMaxBytes
 | GetUsedBytes
 | SetUsedBytes
時間 | GetStartTime
 | SetStartTime
 | TotalTime

すべての COM インターフェイスは IUnknown インターフェイスのメソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTMUSICBUFFER8 型は、IDirectMusicBuffer8 インターフェイスへのポインタとして定義されている。

typedef IDirectMusicBuffer8 *LPDIRECTMUSICBUFFER8;

動作環境

ヘッダー : dmusicc.h で宣言。


IDirectMusicBuffer8::Flush

バッファ内の全データを破棄する。

HRESULT Flush();

パラメータ

なし。

戻り値

常に S_OK を返す。

動作環境

ヘッダー : dmusicc.h で宣言。


IDirectMusicBuffer8::GetBufferFormat

バッファ フォーマットを表す GUID を取得する。

HRESULT GetBufferFormat(
  LPGUID pGuidFormat
);

パラメータ

pGuidFormat
バッファ フォーマットの GUID を受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は E_POINTER を返す。

注意

バッファを作成したときにフォーマットを指定しなかった場合、*pGuidFormat に KSDATAFORMAT_SUBTYPE_DIRECTMUSIC が返される。

動作環境

ヘッダー : dmusicc.h で宣言。

参照

IDirectMusic8::CreateMusicBuffer、DMUS_EVENTHEADER


IDirectMusicBuffer8::GetMaxBytes

バッファ内に保存できるバイト数を取得する。

HRESULT GetMaxBytes(
  LPDWORD pcb
);

パラメータ

pcb
バッファが保持できる最大のバイト数を含む変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は E_POINTER を返す。

動作環境

ヘッダー : dmusicc.h で宣言。


IDirectMusicBuffer8::GetNextEvent

バッファ内の以下のメッセージに関する情報を返し、読み取りポインタを先に進める。

HRESULT GetNextEvent(
  LPREFERENCE_TIME prt,
  LPDWORD pdwChannelGroup,
  LPDWORD pdwLength,
  LPBYTE* ppData
);

パラメータ

prt
メッセージのタイムを受け取る変数のアドレス。
pdwChannelGroup
メッセージのチャンネル グループを受け取る変数のアドレス。
pdwLength
メッセージの長さ (バイト単位) を受け取る変数のアドレス。
ppData
メッセージ データへのポインタを受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。ただし、バッファ内にメッセージが存在しなかった場合は S_FALSE を返す。

失敗した場合は E_POINTER を返す。

注意

項目が必要ない場合、該当するポインタとして NULL を指定してもよい。

ppData に返されたポインタは、バッファ オブジェクトの寿命の間に限って有効である。

動作環境

ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicBuffer8::ResetReadPtr


IDirectMusicBuffer8::GetRawBufferPtr

基底のバッファ データ構造体へのポインタを返す。

HRESULT GetRawBufferPtr(
  LPBYTE* ppData
);

パラメータ

ppData
バッファのデータへのポインタを受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は E_POINTER を返す。

注意

このメソッドは、バッファの raw データへのポインタを返す。このデータのフォーマットは、実装に依存する。データの寿命は、バッファ オブジェクトの寿命と同じである。そのため、次に IDirectMusicBuffer8:: Release メソッドを呼び出した後は、返されたポインタを保持すべきではない。

動作環境

ヘッダー : dmusicc.h で宣言。


IDirectMusicBuffer8::GetStartTime

バッファ内のデータの開始タイムを取得する。このタイムはマスタ クロックを基準とする。

HRESULT GetStartTime(
  LPREFERENCE_TIME prt
);

パラメータ

prt
開始タイムを受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_BUFFER_EMPTY
E_POINTER

動作環境

ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicBuffer8::SetStartTime、IDirectMusicBuffer8::TotalTime


IDirectMusicBuffer8::GetUsedBytes

バッファ内のデータのバイト数を取得する。

HRESULT GetUsedBytes(
  LPDWORD pcb
);

パラメータ

pcb
使用中のバイト数を受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は E_POINTER を返す。

動作環境

ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicBuffer8::SetUsedBytes


IDirectMusicBuffer8::PackStructured

固定長データ (通常は MIDI チャンネル メッセージ) を、タイミング情報およびルーティング情報と共にバッファ内に挿入する。

HRESULT PackStructured(
  REFERENCE_TIME rt,
  DWORD dwChannelGroup,
  DWORD dwChannelMessage
);

パラメータ

rt
メッセージの絶対タイム。「注意」を参照すること。
dwChannelGroup
データが所属するチャンネル グループ。
dwChannelMessage
パックすべきデータ (MIDI メッセージ)。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_INVALID_EVENT
E_OUTOFMEMORY

注意

バッファ内に少なくとも 32 バイト (DMUS_EVENTHEADER と dwChannelMessage の合計サイズ) の空きが存在しなければならない。

rt パラメータには、データがポートに送信される絶対タイムを設定する必要がある。メッセージを即座に演奏するには、遅延時間クロックからこのタイムを取得し、rt として使用する。「IDirectMusicPort8::GetLatencyClock」を参照すること。

同じタイムのスタンプが付いたメッセージは、バッファ内に置かれた順序と同じ順序で演奏されるとは限らない。

動作環境

ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicBuffer8::PackUnstructured


IDirectMusicBuffer8::PackUnstructured

非構造化データ (通常は MIDI システム エクスクルーシブ メッセージ) を、タイミング情報およびルーティング情報と共にバッファ内に挿入する。

HRESULT PackUnstructured(
  REFERENCE_TIME rt,
  DWORD dwChannelGroup,
  DWORD cb,
  LPBYTE lpb
);

パラメータ

rt
メッセージの絶対タイム。
dwChannelGroup
メッセージが所属するチャンネル グループ。
cb
データのサイズ (バイト単位)。
lpb
データを保持するバッファのアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_OUTOFMEMORY
E_POINTER

注意

このメソッドを使って、任意のデータをポートに送信できる。

少なくとも 28 バイト (DMUS_EVENTHEADER のサイズ) とデータのサイズを 4 バイトの倍数まで追加したサイズの空きがバッファ内に存在しなければならない。必要なバッファは DMUS_EVENT_SIZE(cb) マクロを使って取得できる。ここで cb はデータのサイズである。

rt パラメータには、データがポートに送信される絶対タイムを設定する必要がある。メッセージを即座に演奏するには、遅延時間クロックからこのタイムを取得し、rt として使用する。「IDirectMusicPort8::GetLatencyClock」を参照すること。

同じタイムのスタンプが付いたメッセージは、バッファ内に置かれた順序と同じ順序で演奏されるとは限らない。

動作環境

ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicBuffer8::PackStructured


IDirectMusicBuffer8::ResetReadPtr

読み取りポインタをバッファ内のデータの先頭に設定する。

HRESULT ResetReadPtr()

パラメータ

なし。

戻り値

常に S_OK を返す。

動作環境

ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicBuffer8::GetNextEvent


IDirectMusicBuffer8::SetStartTime

バッファ内のデータの開始タイムを設定する。このタイムはマスタ クロックを基準とする。

HRESULT SetStartTime(
  REFERENCE_TIME rt
);

パラメータ

rt
バッファの新しい開始タイム。

戻り値

常に S_OK を返す。

注意

バッファ内に既にあるイベントは、開始タイムを基準とするタイム スタンプが付けられ、新しい開始タイムからの同じオフセットから演奏する。

動作環境

ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicBuffer8::GetStartTime


IDirectMusicBuffer8::SetUsedBytes

バッファ内のデータのバイト数を設定する。

HRESULT SetUsedBytes(
  DWORD cb
);

パラメータ

cb
バッファ内の有効なデータ バイト数。

戻り値

成功した場合は S_OK を返す。

失敗した場合は DMUS_E_BUFFER_FULL を返す。

注意

このメソッドを使うと、アプリケーションはバッファを手動で再パックできる。通常、バッファ内のデータ形式が、DirectMusic の提供するデフォルトのフォーマットと異なるときにのみ、このメソッドを使うべきである。

指定したバイト数が、IDirectMusicBuffer8::GetMaxBytes メソッドの返す最大バッファ サイズを超えている場合、このメソッドは失敗する。

動作環境

ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicBuffer8::GetUsedBytes


IDirectMusicBuffer8::TotalTime

バッファ内のデータの合計時間を返す。

HRESULT TotalTime(
  LPREFERENCE_TIME prtTime
);

パラメータ

prtTime
バッファ内の合計時間 (100ns 単位) を受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は E_POINTER を返す。

動作環境

ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicBuffer8::GetStartTime


IDirectMusicChordMap8

IDirectMusicChordMap8 インターフェイスは、コード マップを表す。コード マップは、コンポーザ (IDirectMusicComposer8 によって表される) に対し、アレンジするセグメントのコード進行を作成するのに必要な情報を提供する。コード マップは、既存セグメント内のコードを変更する場合にも使用できる。

DirectMusicChordMap オブジェクトは、自らのデータをロードするために IDirectMusicObject8 と IPersistStream の各インターフェイスもサポートしている。

IDirectMusicChordMap8 は、IDirectMusicChordMap の型定義である。2 つのインターフェイス名は入れ替え可能である。

このインターフェイスは、以下のメソッドをサポートする。

IDirectMusicChordMap8 GetScale

すべての COM インターフェイスは IUnknown インターフェイスのメソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicChordMap8::GetScale

コード マップに関連付けられたスケールを取得する。

HRESULT GetScale(
  DWORD* pdwScale
);

パラメータ

pdwScale
スケールの値を受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は E_POINTER を返す。

注意

スケールは、DWORD 内のビットをスケールのパターン (下位 24 ビット) と ルート音 (上位 8 ビット) に分割して定義される。スケールのパターンは、最下位ビット (0x0001) は低いノートの C、次の上位ビット (0x0002) は C# であり、同様に 2 オクターブのスケールが定義される。上位 8 ビットは、スケールのルート音を 0 ～ 23 (低音の C から中間の B まで) の整数で表す。

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicCollection8

IDirectMusicCollection8 インターフェイスは、DLS ファイルのインスタンスを管理する。コレクションは、音色にアクセスするためのメソッドを提供し、IDirectMusicPort8 インターフェイスを使って音色をシンセサイザにダウンロードする。

IDirectMusicCollection8 は、IDirectMusicCollection の型定義である。2 つのインターフェイス名は入れ替え可能である。

DirectMusicCollection オブジェクトは、自らのデータをロードするために IDirectMusicObject8 と IPersistStream の各インターフェイスもサポートしている。

コレクションを使った作業の詳細については、「音色コレクションの使い方」を参照すること。

IDirectMusicCollection8 インターフェイスには次のメソッドがある。

音色 | EnumInstrument
 | GetInstrument

すべての COM インターフェイスは IUnknown インターフェイスのメソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

ヘッダー : dmusicc.h で宣言。


IDirectMusicCollection8::EnumInstrument

コレクション内のインデックスを使って、音色のパッチ番号と名前を取得する。

HRESULT EnumInstrument(
  DWORD dwIndex,
  DWORD* pdwPatch,
  LPWSTR pwszName,
  DWORD dwNameLen
);

パラメータ

dwIndex
コレクション内の音色のインデックス。
pdwPatch
パッチ番号を受け取る変数のアドレス。
pwszName
音色名を受け取るバッファのアドレス。名前が不要な場合は、NULL でもよい。
dwNameLen
音色名バッファに格納される WCHAR 値の数。

戻り値

成功した場合は S_OK を返す。指定されたインデックス番号を持つ音色が存在しない場合は S_FALSE を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_FAIL
E_OUTOFMEMORY
E_POINTER

注意

コレクション内のすべての音色を列挙するには、dwIndex の値を 0 から始め、EnumInstrument が S_FALSE を返すまで値を大きくする。

pdwPatch に返されるパッチ番号は、バンク セレクトの MSB と LSB の MIDI パラメータも含む、完全なパッチアドレスを記述する。詳細については、「MIDI チャンネル メッセージ」を参照すること。

列挙型の順序は DLS コレクションの 1 つのインスタンス内では整合しているが、この順序はファイル内の音色の順序、パッチ番号、音色名のいずれとも関係はない。

音色の列挙の例については、「音色の操作」を参照すること。

動作環境

ヘッダー : dmusicc.h で宣言。


IDirectMusicCollection8::GetInstrument

パッチ番号を指定して、コレクションから音色を取得する。

HRESULT GetInstrument(
  DWORD dwPatch,
  IDirectMusicInstrument** ppInstrument
);

パラメータ

dwPatch
音色のパッチ番号。
ppInstrument
IDirectMusicInstrument8 インターフェイス ポインタを受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_CORE_INVALIDPATCH
E_FAIL
E_OUTOFMEMORY
E_POINTER

注意

dwPatch で渡されたパッチ番号は、バンク セレクトの MSB と LSB の MIDI パラメータも含む、完全なパッチ アドレスを記述する。MSB は左シフトされた 16 ビットであり、LSB は左シフトされた 8 ビットである。詳細については、「MIDI チャンネル メッセージ」を参照すること。

また、音色が MIDI チャンネル 10 再生用のドラム キットの場合、上位ビット (0x80000000) が設定される。

このメソッドを使う方法の詳細については、「音色の操作」を参照すること。

動作環境

ヘッダー : dmusicc.h で宣言。


IDirectMusicComposer8

IDirectMusicComposer8 インターフェイスを使うと、コンポーザ エンジンにアクセスできる。テンプレートやコード マップから新しいセクション セグメントを構築することに加えて、このコンポーザは複数のセクション セグメント間のトランジションを作成できる。コード マップを既存のセクション セグメントにも適用できるので、セクションのコード進行と雰囲気も変更できる。

IDirectMusicComposer8 は、IDirectMusicComposer の定義である。2 つのインターフェイス名は入れ替え可能である。

IDirectMusicComposer8 インターフェイスのメソッドは、以下のグループにまとめることができる。

コード マップの変更 | ChangeChordMap
通常のセグメントのアレンジ | ComposeSegmentFromShape
 | ComposeSegmentFromTemplate
テンプレート セグメントのアレンジ | ComposeTemplateFromShape
トランジション セグメントのアレンジ | AutoTransition
 | ComposeTransition

すべての COM インターフェイスは IUnknown インターフェイスのメソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicComposer8::AutoTransition

パフォーマンスのプライマリ セグメント (または無音) からほかのセグメントへのトランジションをアレンジし、演奏の目的でそのトランジションとセカンダリ セグメントを挿入する。

HRESULT AutoTransition(
  IDirectMusicPerformance* pPerformance,
  IDirectMusicSegment* pToSeg,
  WORD wCommand,
  DWORD dwFlags,
  IDirectMusicChordMap* pChordMap,
  IDirectMusicSegment** ppTransSeg,
  IDirectMusicSegmentState** ppToSegState,
  IDirectMusicSegmentState** ppTransSegState
);

パラメータ

pPerformance
トランジションを作成するパフォーマンス。
pToSeg
移行先セクション。トランジションはこのセクションへ円滑に移行する。「注意」を参照すること。
wCommand
トランジションを作成するときに使われる装飾。これには、DMUS_COMMANDT_TYPES 列挙型の 1 つか、またはコンテント プロバイダによって定義された別の値を指定できる。この値が DMUS_COMMANDT_ENDANDINTRO の場合、メソッドは、プライマリ セグメントのエンディングと pToSeg のイントロを含むセグメントをアレンジする。
dwFlags
コンポーザ オプション。「DMUS_COMPOSEF_FLAGS」を参照すること。
pChordMap
トランジションをアレンジするときに使用されるコード マップの、IDirectMusicChordMap8 インターフェイスへのポインタ。
ppTransSeg
作成されたセグメントへのポインタを受け取る変数のアドレス。この値は NULL でもよい。その場合、ポインタは返されない。
ppToSegState
トランジション (pToSeg) の後のセグメントのパフォーマンス (pPerformance) によって作成されるセグメント状態へのポインタを受け取る変数のアドレス。「注意」を参照すること。
ppTransSegState
作成されたセグメント (ppTransSeg) のパフォーマンス (pPerformance) によって作成されるセグメント状態へのポインタを受け取る変数のアドレス。「注意」を参照すること。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_NO_MASTER_CLOCK
E_INVALIDARG
E_POINTER

注意

dwFlags が DMUS_COMPOSEF_MODULATE を含んでいない場合、pToSeg の値は NULL でもよい。pToSeg が NULL またはスタイル トラックを含んでいない場合 (MIDI ファイルに基づいている場合)、イントロの装飾は無効になる。演奏中のセグメントが NULL またはスタイル トラックを含んでいない場合は、フィル、ブレーク、エンド、およびグルーブの装飾が無効になる。演奏中のセグメントまたは pToSeg によって表されるセグメントでスタイル トラックが利用できない場合は、すべての装飾が無効になり、トランジションは行われない。その場合、ppTransSeg と ppTransSegState の両方が NULL を返すが、ポインタが NULL 以外のときメソッドは成功し、pToSeg によって表されるセグメントが挿入される。

pChordMap の値は NULL でもよい。値が NULL の場合、コード マップ トラックからコード マップを取得する試みが行われる。最初に pToSeg、次にパフォーマンスのプライマリ セグメントが試される。どのセグメントにもコード マップ トラックが含まれない場合は、現在のタイムにプライマリ セグメント内で発生するコードがトランジションのコードとして使われる。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicComposer8::ComposeTransition、トランジションの使い方


IDirectMusicComposer8::ChangeChordMap

新しいコード マップを反映して、既存のセクション セグメントのコードとスケールのパターンを変更する。

HRESULT ChangeChordMap(
  IDirectMusicSegment* pSegment,
  BOOL fTrackScale,
  IDirectMusicChordMap* pChordMap
);

パラメータ

pSegment
コード マップを変更するセグメントの、IDirectMusicSegment8 インターフェイスへのポインタ。このセグメントは、コード マップ トラックとスタイルを保持しなければならない。
fTrackScale
TRUE の場合、メソッドは、すべてのコードを新しいコード マップ スケールのルート音に相対的に転置する。ルート音をそのままの状態にしない。
pChordMap
セグメントに適用する新しいコードマップの IDirectMusicChordMap8 インターフェイスへのポインタ。

戻り値

成功した場合は S_OK を返す。

失敗した場合は E_POINTER を返す。

注意

メソッドはセグメントの演奏中に呼び出すことができる。

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicComposer8::ComposeSegmentFromShape

あらかじめ定義されたシェイプに基づいて、スタイルとコード マップからオリジナルのセクション セグメントを作成する。このシェイプは、セクション全体で時間の経過に伴ってコードと装飾を発生させる方法を表す。

HRESULT ComposeSegmentFromShape(
  IDirectMusicStyle* pStyle,
  WORD wNumMeasures,
  WORD wShape,
  WORD wActivity,
  BOOL fIntro,
  BOOL fEnd,
  IDirectMusicChordMap* pChordMap,
  IDirectMusicSegment** ppSegment
);

パラメータ

pStyle
セクション セグメントのアレンジに使うスタイル。
wNumMeasures
アレンジするセクション セグメントの長さ。小節単位で指定する。
wShape
アレンジするセクション セグメントのシェイプ。DMUS_SHAPET_TYPES 列挙型のいずれかの値を指定する。
wActivity
和音進行のレート。有効な値は 0 ～ 3 である。値が低いと、コード チェンジが増える。
fIntro
セクション セグメントのイントロをアレンジしたい場合は TRUE を設定する。
fEnd
セクション セグメントのエンディングをアレンジしたい場合は TRUE を設定する。
pChordMap
セグメント作成の元となる、コード マップの IDirectMusicChordMap8 インターフェイスへのポインタ。
ppSegment
作成されたセグメントへのポインタを受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は E_POINTER を返す。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicComposer8::ComposeSegmentFromTemplate、IDirectMusicComposer8::ComposeTemplateFromShape


IDirectMusicComposer8::ComposeSegmentFromTemplate

スタイル、コード マップ、およびテンプレートから、オリジナルのセグメントを作成する。

HRESULT ComposeSegmentFromTemplate(
  IDirectMusicStyle* pStyle,
  IDirectMusicSegment* pTemplate,
  WORD wActivity,
  IDirectMusicChordMap* pChordMap,
  IDirectMusicSegment** ppSegment
);

パラメータ

pStyle
セグメントの作成に使用するスタイルを指定する IDirectMusicStyle8 インターフェイス ポインタ。
pTemplate
セグメントの作成に使用するテンプレートを指定する IDirectMusicSegment8 インターフェイス ポインタ。
wActivity
和音進行のレート。有効な値は 0 ～ 3 である。値が低いと、コード チェンジが増える。
pChordMap
セグメントの作成に使用するコードマップを指定する IDirectMusicChordMap8 インターフェイス ポインタ。
ppSegment
作成されたセグメントへのポインタを受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_INVALIDARG
E_POINTER

注意

pStyle が NULL ではない場合、このスタイルはセグメントのアレンジに使われる。NULL の場合、pTempSeg で指定されたテンプレートから取得したスタイルをセグメントのアレンジに使う。同様に、pChordMap が NULL 以外の場合、コードマップはセグメントのアレンジに使用され、NULL の場合、コードマップはテンプレートから取得される。

pStyle が NULL でテンプレート内にスタイル トラックが存在しない場合や、pChordMap が NULL でコード マップ トラックが存在しない場合、このメソッドは E_INVALIDARG を返す。

セクション セグメントの長さは、渡されたテンプレート セクションの長さと等しくなる。

作成されたセグメントのデフォルトの開始ポイントとループ ポイントは、テンプレート セグメント内の値に関係なく 0 である。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicComposer8::ComposeSegmentFromShape、IDirectMusicComposer8::ComposeTemplateFromShape、テンプレートの使い方


IDirectMusicComposer8::ComposeTemplateFromShape

あらかじめ定義されたシェイプに基づいて新しいテンプレートを作成する。

HRESULT ComposeTemplateFromShape(
  WORD wNumMeasures,
  WORD wShape,
  BOOL fIntro,
  BOOL fEnd,
  WORD wEndLength,
  IDirectMusicSegment** ppTemplate
);

パラメータ

wNumMeasures
アレンジするセクション セグメントの長さ。小節単位で指定する。0 より大きい値でなければならない。
wShape
アレンジするセクション セグメントのシェイプ。DMUS_SHAPET_TYPES 列挙型のいずれかの値を指定する。
fIntro
セクション セグメントのイントロをアレンジしたい場合は TRUE を設定する。
fEnd
セクション セグメントのエンディングをアレンジしたい場合は TRUE を設定する。
wEndLength
エンディングを作成したい場合は、エンディングの長さ。小節単位で指定する。fEnd が TRUE の場合、この値は 0 より大きく、利用できる小節の数以下でなければならない (つまり、イントロでは使われない)。「注意」も参照すること。
ppTemplate
作成されたセクション セグメントへのポインタを受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_INVALIDARG
E_OUTOFMEMORY
E_POINTER

注意

wEndLength の値は、IDirectMusicComposer8::ComposeSegmentFromTemplate メソッドを使ってこのテンプレートに関連付けられる可能性のある任意のスタイル内で利用できる、最長のエンディングの長さを超えてはならない。エンディングは、セグメントが終わる前の wEndLength の小節で演奏を開始する。エンディングが wEndLength の小節の長さより短い場合、音楽は基本グルーブ レベルに戻る。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicComposer8::ComposeSegmentFromTemplate、テンプレートの使い方


IDirectMusicComposer8::ComposeTransition

あるセクション セグメントからほかのセクション セグメントへのトランジションをアレンジする。

HRESULT ComposeTransition(
  IDirectMusicSegment* pFromSeg,
  IDirectMusicSegment* pToSeg,
  MUSIC_TIME mtTime,
  WORD wCommand,
  DWORD dwFlags,
  IDirectMusicChordMap* pChordMap,
  IDirectMusicSegment** ppTransSeg
);

パラメータ

pFromSeg
トランジションのアレンジに使われる移行元のセクション。
pToSeg
移行先セクション。トランジションはこのセクションへ円滑に移行する。dwFlags が DMUS_COMPOSEF_MODULATE を含んでいない場合、NULL でもよい。
mtTime
pFromSeg のセクション内でトランジションのアレンジを開始するタイム。
wCommand
トランジションを作成するときに使われる装飾。これには、DMUS_COMMANDT_TYPES 列挙型の 1 つか、またはコンテント プロバイダによって定義された別の値を指定できる。この値が DMUS_COMMANDT_ENDANDINTRO の場合、メソッドは、pFromSeg のエンディングと pToSeg のイントロを含むセグメントをアレンジする。
dwFlags
コンポーザ オプション。このパラメータは、DMUS_COMPOSEF_FLAGS 列挙型の値の 1 つまたは複数を保持できる。
pChordMap
トランジションをアレンジするときに使用されるコード マップの、IDirectMusicChordMap8 インターフェイスへのポインタ。「注意」を参照すること。
ppTransSeg
作成されたセグメントへのポインタを受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_INVALIDARG
E_OUTOFMEMORY
E_POINTER

注意

pChordMap の値は NULL でもよい。値が NULL の場合、コード マップ トラックからコード マップを取得する試みが行われる。最初に pToSeg、次に pFromSeg が試される。どのセグメントにもコード マップ トラックが含まれない場合は、mtTime に pFromSeg 内で発生するコードがトランジションのコードとして使われる。

コンポーザは、最初に pFromSeg 内、次に pToSeg 内でテンポを探す。どのセグメントにもテンポ トラックがない場合、トランジション セグメントのテンポはスタイルから取得される。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicComposer8::AutoTransition、トランジションの使い方


IDirectMusicContainer8

IDirectMusicContainer8 インターフェイスを使うと、コンテナ内のオブジェクトにアクセスできる。コンテナとは、セグメントやパフォーマンスが使用するオブジェクトのコレクションである。このインターフェイスは、IDirectMusicLoader8::GetObject または IDirectMusicLoader8::LoadObjectFromFile を呼び出すことで、コンテナがロードされるときに取得できる。

コンテナ オブジェクトがロードされると、コンテナ内のすべてのオブジェクトが、ローダーから利用できるようになる。コンテナが解放されると、コンテナが参照するすべてのオブジェクトがローダーから解放される。ただし、コンテナ解放時に使用中のオブジェクトは、明示的に解放されるまでは解放されない。そのようなオブジェクトが、DLS コレクションやストリーミング ウェーブのようにストリーミングを開いたままにしている場合は、ストリームも開いたままになる。その結果、個別のウェーブ ファイルや DLS ファイルと同様に、コンテナ ファイルはロック状態にとどまる。

コンテナはセグメントに埋め込むことができる。ファイル内で、コンテナはセグメントのトラックの前に配置される。これにより、トラックがロードされる前に、コンテナが読み取られ、オブジェクトがローダーにインストールされる。トラックがロードされると、ローダーは、コンテナ内の参照オブジェクトへのリンクを設定できる。

IDirectMusicCollection8 は、IDirectMusicCollection8 の型定義である。2 つのインターフェイス名は入れ替え可能である。

IDirectMusicContainer8 インターフェイスには次のメソッドがある。

列挙 EnumObject

すべての COM インターフェイスは IUnknown インターフェイスのメソッドを継承する。このインターフェイスは、次の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

ヘッダー : dmusici.h で宣言。

参照

コンテナ


IDirectMusicContainer8::EnumObject

コンテナ内のオブジェクトに関する情報を取得する。

HRESULT EnumObject(
  REFGUID rguidClass,
  DWORD dwIndex,
  LPDMUS_OBJECTDESC pDesc,
  WCHAR* pwszAlias
);

パラメータ

rguidClass
オブジェクト クラスの一意な識別子への参照 (C++) またはアドレス (C)。任意のタイプのオブジェクトを取得する場合は GUID_DirectMusicAllTypes。標準的なローダブル クラスのリストについては、「IDirectMusicLoader8」を参照すること。
dwIndex
コンテナに含まれるオブジェクト クラス rguidClass 内のオブジェクトのインデックス。
pDesc
オブジェクトの記述を受け取る DMUS_OBJECTDESC 構造体へのポインタ。記述を必要としない場合は、このパラメータを NULL にする。「注意」を参照すること。
pwszAlias
オブジェクトのエイリアスを受け取る MAX_PATH サイズの文字列バッファのアドレス (エイリアスがある場合)。エイリアスは、オブジェクトを参照するためにスクリプトで使用される特殊な名前である。エイリアスを必要としない場合は、このパラメータを NULL にする。

戻り値

成功した場合は、次のいずれかのコードを返す。

S_OK | オブジェクトが列挙された。
S_FALSE | dwIndex のインデックスを持つオブジェクトがない。
DMUS_S_STRING_TRUNCATED | エイリアスが MAX_PATH より長い。
DMUS_S_GARBAGE_COLLECTED | 「ガベージ コレクション」を参照すること。

失敗した場合は E_POINTER を返す。

注意

メソッドに渡す前に、DMUS_OBJECTDESC 構造体の dwSize メンバを初期化する必要がある。その他のメンバは無視される。wszName メンバの値の指定などによって列挙の範囲を縮小することはできない。メソッドによって返された記述を使って、IDirectMusicLoader8::GetObject を呼び出すことで、オブジェクトを取得できる。サンプル コードについては、「コンテナ」を参照すること。

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicDownload8

連続したメモリ チャンクを表し、DLS シンセサイザ ポートへのダウンロードを行うために使われる。

IDirectMusicDownload8 は、IDirectMusicDownload の型定義である。2 つのインターフェイス名は入れ替え可能である。

IDirectMusicDownload8 インターフェイスとその中に含まれているメモリ チャンクは、IDirectMusicPortDownload8::AllocateBuffer メソッドによって作成される。その後、このインターフェイスの 1 つのメソッドを使って、このメモリにアクセスできる。

このインターフェイスは、パフォーマンス、バンド、およびセグメントの各オブジェクトに音色データをダウンロードさせるためにあるのではなく、DLS バッファに直接アクセスする必要があるアプリケーションのみが使用する。概要については、「下位レベル DLS」を参照すること。

このインターフェイスは、以下のメソッドをサポートする。

メモリ アクセス GetBuffer

すべての COM インターフェイスは IUnknown インターフェイスのメソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

ヘッダー : dmusicc.h で宣言。


IDirectMusicDownload8::GetBuffer

ダウンロードすべきデータを保持するバッファへのポインタを取得する。

HRESULT GetBuffer(
  void** ppvBuffer,
  DWORD* pdwSize
);

パラメータ

ppvBuffer
データ バッファへのポインタを受け取る変数のアドレス。
pdwSize
返されたバッファのサイズ (バイト単位) を受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_BUFFERNOTAVAILABLE
E_POINTER

注意

バッファが既にダウンロードされている場合、このメソッドは DMUS_E_BUFFERNOTAVAILABLE を返す。

動作環境

ヘッダー : dmusicc.h で宣言。


IDirectMusicDownloadedInstrument8

IDirectMusicDownloadedInstrument8 インターフェイスは、IDirectMusicPort8::DownloadInstrument メソッドまたは IDirectMusicPerformance8::DownloadInstrument メソッドで、シンセサイザにダウンロードされた音色を識別するために使用される。次にこのインターフェイス ポインタを使い、IDirectMusicPort8::UnloadInstrument を呼び出して、その音色をアンロードする。音色をアンロードしたら、インターフェイス ポインタはアプリケーションによって解放されなければならない。具体的な例については、「音色の操作」を参照すること。

IDirectMusicDownloadedInstrument8 は、IDirectMusicDownloadedInstrument の型定義である。2 つのインターフェイス名は入れ替え可能である。

IDirectMusicDownloadedInstrument8 インターフェイスは独自のメソッドを持たない。すべての COM インターフェイスと同様、このインターフェイスは IUnknown インターフェイスのメソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

ヘッダー : dmusicc.h で宣言。


IDirectMusicGetLoader8

IDirectMusicGetLoader8 インターフェイスは、ストリームを解析するオブジェクトが、ストリームにより参照される別のオブジェクトをロードする必要がある場合に使用される。ストリームがローダーをサポートしている場合、ストリームは必ず IDirectMusicGetLoader8 インターフェイスを提供している。

ストリームから IDirectMusicGetLoader8 インターフェイスを取得する方法の例については、「IDirectMusicGetLoader8::GetLoader」を参照すること。

IDirectMusicGetLoader8 は、IDirectMusicGetLoader の型定義である。2 つのインターフェイス名は入れ替え可能である。

IDirectMusicGetLoader8 インターフェイスには次のメソッドがある。

IDirectMusicGetLoader8 GetLoader

すべての COM インターフェイスは IUnknown インターフェイスのメソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicLoader8、オーディオ データのロード、カスタム ロード


IDirectMusicGetLoader8::GetLoader

ストリームを作成したローダー オブジェクトへのポインタを取得する。

HRESULT GetLoader8(
  IDirectMusicLoader ** ppLoader
);

パラメータ

ppLoader
IDirectMusicLoader インターフェイス ポインタを受け取る変数のアドレス。IDirectMusicLoader8 を取得するには、QueryInterface を使用する。このインターフェイスの参照カウントはインクリメントされる。

戻り値

成功した場合は S_OK を返す。

失敗した場合は E_NOINTERFACE を返す。

注意

次のサンプル コードは、ローダーがアクセスする必要のあるオブジェクトへの参照を見つけるファイル パーサーから抜粋したものである。

HRESULT myGetReferencedObject(
    DMUS_OBJECTDESC *pDesc,          // ディスクリプタは既に準備できている。
    IStream *pIStream,               // 解析対象のストリーム。
    IDirectMusicObject **ppIObject)  // アクセスしたいオブジェクト。
{
    IDirectMusicGetLoader *pIGetLoader;
    IDirectMusicLoader *pILoader;
    ppIObject = NULL;
    HRESULT hr = pIStream->QueryInterface(
           IID_IDirectMusicGetLoader,
           (void **) &pIGetLoader );
    if (SUCCEEDED(hr))
    {
        hr = pIGetLoader->GetLoader(&pILoader);
        if (SUCCEEDED(hr))
        {
            hr = pILoader->GetObject(pDesc, IID_DirectMusicLoader,
                  (void**) ppIObject);
            pILoader->Release();
        }
        pIGetLoader->Release();
    }
    return hr;
}

動作環境

ヘッダー : dmusici.h で宣言。

参照

カスタム ロード


IDirectMusicGraph8

IDirectMusicGraph8 インターフェイスは、ツールのロードとメッセージ フローを管理する。

グラフは、セグメントとパフォーマンスの 2 つの場所に置くことができる。パフォーマンス内のツールに対応するグラフは、性質上グローバルであり、そのためにあらゆるセグメントのメッセージを処理する。あるセグメント内のグラフは、そのセグメントの再生だけを目的として存在する。

IDirectMusicGraph8 は、IDirectMusicGraph の型定義である。2 つのインターフェイス名は入れ替え可能である。

IDirectMusicGraph8 インターフェイスには次のメソッドがある。

ルーティング | StampPMsg
ツール | GetTool
 | InsertTool
 | RemoveTool

すべての COM インターフェイスは IUnknown インターフェイスのメソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicGraph8::GetTool

指定されたインデックスのツールを取得する。

HRESULT GetTool(
  DWORD dwIndex,
  IDirectMusicTool** ppTool
);

パラメータ

dwIndex
グラフ内の希望のツールを指定する、0 から始まるインデックス。
ppTool
ツールへのポインタを受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_NOT_FOUND
E_POINTER

注意

取得したツールの解放は、アプリケーションの役目である。

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicGraph8::InsertTool

グラフにツールを挿入する。

HRESULT InsertTool(
  IDirectMusicTool * pTool,
  DWORD * pdwPChannels,
  DWORD cPChannels,
  LONG lIndex
);

パラメータ

pTool
挿入するツール。
pdwPChannels
ツールがメッセージを受け取る P チャンネルの配列のアドレス。このツールがあらゆるチャンネルでメッセージを受け取る場合は、NULL を渡す。
cPChannels
pdwPChannels が指すチャンネルの数。pdwPChannels が NULL の場合は無視される。
lIndex
ツールを置く位置。これは 0 から始まるインデックスである。値が正の場合は現在のツール リストの先頭から数えた位置を意味し、値が負の場合はリストの最後から数えた位置を意味する。lIndex が範囲外の場合、ツールはリストの先頭または最後に置かれる。ツールをリストの最後に置くには、現在のツール リスト内のツール数より大きい値を lIndex で指定する。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_ALREADY_EXISTS
E_OUTOFMEMORY
E_POINTER

注意

ツールの参照カウントはインクリメントされる。

このメソッドは IDirectMusicTool8::Init を呼び出す。

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicGraph8::RemoveTool

グラフからツールを削除する。

HRESULT RemoveTool(
  IDirectMusicTool * pTool
);

パラメータ

pTool
削除するツール。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_NOT_FOUND
E_POINTER

注意

このツールへのグラフの参照は解放される。

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicGraph8::StampPMsg

メッセージを受け取る次のツールへのポインタをメッセージにスタンプする。ツールは、メッセージを処理した後、このメソッドを呼び出さなければならない。

HRESULT StampPMsg(
  DMUS_PMSG* pPMSG
);

パラメータ

pPMSG
スタンプの対象となるメッセージを保持する構造体のアドレス。この構造体は、DMUS_PMSG の派生タイプである。

戻り値

成功した場合は S_OK または DMUS_S_LAST_TOOL を返す。「注意」を参照すること。

失敗した場合は E_POINTER を返す。

注意

エントリ時に、このメッセージ構造体の DMUS_PMSG 部に含まれる pTool メンバは現在のツールを指す。StampPMsg はこのメンバを使って、現在のツールを決定し、グラフ内の次のツールを見つける。NULL の値はグラフ内の最初のツールを表す。

pGraph メンバが指すオブジェクトは、ツールを保持するグラフを表す。StampPMsg 内部では、この値がツール自体の値と共にスタンプされる。複数のツールグラフが存在する場合、メッセージがセグメント状態からパフォーマンスへ移動する過程で、この値が変更されることがある。

dwType の値は、メッセージのメディア タイプに等しく、次のツールを見つけるのに使われる。メディア タイプとしてサポートされているのは、IDirectMusicTool8::GetMediaTypes メソッドが返す値である。

このメソッドは pTool が指す現在の IDirectMusicTool8 に対して Release を呼び出し、グラフ内の次のツールに置き換え、新しいツールに対して AddRef を呼び出す。このメソッドは、次のツールが IDirectMusicTool8::GetMsgDeliveryType メソッドで返すタイプに基づいて、メッセージに正しい引き渡しタイプ フラグも割り当てる。このフラグは、メッセージを次のツールに配信する時期を決定する。

ツールは、必ず、ほかのタスクがすべて実行されてから StampPMsg を呼び出す。オーディオパスが使用されている場合は、StampPMsg によって、メッセージ構造体の dwPChannel メンバの値が変更される場合がある。この値を使用するツールは、StampPMsg を呼び出した後、この値を使用できなくなる。

DirectMusicSegmentState と DirectMusicPerformance の各オブジェクトでのこのメソッドを実装すると、成功した場合、常に S_OK を返す。DirectMusicGraph で実装すると、メッセージの受け取りを待っている出力ツールのほかにツールがない場合、DMUS_S_LAST_TOOL を返す。

動作環境

ヘッダー : dmusici.h で宣言。

参照

DirectMusic ツール


IDirectMusicInstrument8

IDirectMusicInstrument8 インターフェイスは、DLS コレクションの個別の音色を表す。

IDirectMusicInstrument8 は、IDirectMusicInstrument の型定義である。2 つのインターフェイス名は入れ替え可能である。

DirectMusicInstrument オブジェクトを作成して、音色をダウンロードするための唯一の方法は、最初に DirectMusicCollection オブジェクトを作成し、次に IDirectMusicCollection8::GetInstrument メソッドを呼び出すことである。GetInstrument は DirectMusicInstrument オブジェクトを作成し、IDirectMusicInstrument8 インターフェイス ポインタを返す。

音色をダウンロードするには、そのインターフェイス ポインタを IDirectMusicPort8::DownloadInstrument メソッドまたは IDirectMusicPerformance8::DownloadInstrument メソッドに渡す。このメソッドが成功すると、IDirectMusicDownloadedInstrument8 インターフェイスへのポインタが返される。このインターフェイスは、音色をアンロードする場合にのみ使われる。

IDirectMusicInstrument8 のメソッドは、既にダウンロードされている音色のみに対して動作する。ポートにダウンロードされた音色のインスタンスは、IDirectMusicInstrument8::GetPatch メソッドや IDirectMusicInstrument8::SetPatch メソッドによる影響は受けない。

このインターフェイスは、以下のメソッドをサポートする。

IDirectMusicInstrument8 | GetPatch
 | SetPatch

すべての COM インターフェイスは IUnknown インターフェイスのメソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTMUSICINTRUMENT8 型は、このインターフェイスへのポインタとして定義されている。

typedef IDirectMusicInstrument8 *LPDIRECTMUSICINSTRUMENT8;

動作環境

ヘッダー : dmusicc.h で宣言。


IDirectMusicInstrument8::GetPatch

音色のパッチ番号を取得する。このパッチ番号は、バンク セレクトの MSB と LSB、および MIDI パッチ (プログラム チェンジ) 番号によって構成されたアドレスである。オプションのフラグ ビットは、音色が旋律系の音色ではなく、ドラムであることを表す。

HRESULT GetPatch(
  DWORD* pdwPatch
);

パラメータ

pdwPatch
パッチ番号を受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_NOT_INIT
E_POINTER

注意

pdwPatch に返されるパッチ番号は、バンク セレクトの MSB と LSB の MIDI パラメータも含む、完全なパッチ番号を表す。加えて、特に音色がドラム キットであり、MIDI チャンネル 10 で演奏されることを意図している場合は、上位ビットが設定される。DLS レベル 1 はドラムを必ず MIDI チャンネル 10 で演奏するため、これが DLS レベル 1 用の特別なタグである。詳細については、「MIDI チャンネル メッセージ」を参照すること。

動作環境

ヘッダー : dmusicc.h で宣言。


IDirectMusicInstrument8::SetPatch

音色のパッチ番号を取得する。DLS コレクション内の各音色はあらかじめ定義されたパッチ番号を持っているが、IDirectMusicCollection8::GetInstrument メソッドを使ってコレクションから音色を取得した後、パッチ番号を再割り当てすることもできる。DirectMusic パッチ番号の詳細については、「IDirectMusicInstrument8::GetPatch」を参照すること。

HRESULT SetPatch(
  DWORD dwPatch
);

パラメータ

dwPatch
音色に割り当てる新しいパッチ番号。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_NOT_INIT
DMUS_E_CORE_INVALIDPATCH

注意

次のサンプル コードは、コレクションから音色を取得し、音色の MSB バンクの再マップを行ってほかのバンクを選択し、その音色をダウンロードする。

HRESULT myRemappedDownload(
    IDirectMusicCollection8 *pCollection,
    IDirectMusicPort8 *pPort,
    IDirectMusicDownloadedInstrument8 **ppDLInstrument,
    BYTE bMSB,       // パッチ番号のバンク セレクト内で指定された MIDI の MSB。
    DWORD dwPatch)   // 指定されたパッチ番号。

{
    HRESULT hr;
    IDirectMusicInstrument8* pInstrument;
    hr = pCollection->GetInstrument(dwPatch, &pInstrument);
    if (SUCCEEDED(hr))
    {
        dwPatch &= 0xFF00FFFF;  // MSB を消去する。
        dwPatch |= bMSB << 16;  // 新しい MSB の値を設定する。
        pInstrument->SetPatch(dwPatch);
        hr = pPort->DownloadInstrument(pInstrument,
                ppDLInstrument,
                NULL, 0);       // すべてのリージョンをダウンロードする。
        pInstrument->Release();
    }
    return hr;
}

動作環境

ヘッダー : dmusicc.h で宣言。


IDirectMusicLoader8

IDirectMusicLoader8 インターフェイスは、オブジェクトの検索、列挙、キャッシング、およびロードに使われる。概要については、「オーディオ データのロード」を参照すること。

このインターフェイスは、IDirectMusicLoader を引き継ぎ、ガベージ コレクションのサポートを追加する。

IDirectMusicLoader8 インターフェイスのメソッドは、以下のグループにまとめることができる。

検索 | EnumObject
 | ScanDirectory
 | SetSearchDirectory
キャッシュと メモリの管理 | CacheObject
 | ClearCache
 | CollectGarbage
 | EnableCache
 | ReleaseObject
 | ReleaseObjectByUnknown
オブジェクトのロード | GetObject
 | LoadObjectFromFile
 | SetObject

すべての COM インターフェイスは IUnknown インターフェイスのメソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDMUS_LOADER 型は、IDirectMusicLoader インターフェイスへのポインタとして定義されている。

typedef IDirectMusicLoader __RPC_FAR *LPDMUS_LOADER;

次の表は、ロード可能なオブジェクトの標準タイプとそのクラス識別子 (オブジェクトを処理する各種メソッドの rguidClass パラメータ)、および通常のファイル名の拡張子のリストである。

オブジェクト タイプ | クラス | 拡張子
オーディオパス | CLSID_DirectMusicAudioPathConfig | aud
バンド | CLSID_DirectMusicBand | bnd
コンテナ | CLSID_DirectMusicContainer | con
DLS コレクション | CLSID_DirectMusicCollection | dls
コードマップ | CLSID_DirectMusicChordMap | cdm
セグメント | CLSID_DirectMusicSegment | sgt
スクリプト | CLSID_DirectMusicScript | spt
ソング* | CLSID_DirectMusicSong | sng
スタイル | CLSID_DirectMusicStyle | sty
テンプレート | CLSID_DirectMusicSegment | tpl
ツールグラフ | CLSID_DirectMusicGraph | tgr
ウェーブ | CLSID_DirectSoundWave | wav

* DirectX 8.0 では実装されていない。

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicLoader8::CacheObject

オブジェクトへの参照を維持するようローダーに指示する。この結果、オブジェクトを 2 回ロードしないことが保証される。

HRESULT CacheObject(
  IDirectMusicObject * pObject
);

パラメータ

pObject
キャッシュに入れるオブジェクトの IDirectMusicObject インターフェイスのアドレス。IDirectMusicObject8 を取得するには、QueryInterface を使用する。

戻り値

成功した場合は S_OK を返す。オブジェクトが既にキャッシュに入っている場合は S_FALSE を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_POINTER
DMUS_E_LOADER_OBJECTNOTFOUND

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicLoader8::EnableCache、IDirectMusicLoader8::ClearCache、IDirectMusicLoader8::ReleaseObject、キャッシュの管理


IDirectMusicLoader8::ClearCache

特定のタイプのオブジェクトへのすべての参照を解放するようローダーに指示する。

HRESULT ClearCache(
  REFGUID rguidClass
);

パラメータ

rguidClass
消去するオブジェクト クラスの識別子への参照 (C++) またはアドレス (C)。すべてのタイプのオブジェクトを消去する場合は GUID_DirectMusicAllTypes。標準的なローダブル クラスのリストについては、「IDirectMusicLoader8」を参照すること。

戻り値

S_OK を返す。

注意

このメソッドは現在保持されているすべてのオブジェクトを消去するが、キャッシングを無効にすることはない。自動的なキャッシングを無効にするには、IDirectMusicLoader8::EnableCache メソッドを使う。

キャッシュから 1 つのオブジェクトを消去するには、IDirectMusicLoader8::ReleaseObject メソッドを呼び出す。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicLoader8::CacheObject、キャッシュの管理


IDirectMusicLoader8::CollectGarbage

使用中でないオブジェクトをキャッシュから削除する。

CollectGarbage();

パラメータ

なし。

戻り値

なし。

注意

アプリケーションがオブジェクトに対して IDirectMusicLoader8::ReleaseObject を呼び出す場合、そのオブジェクトはキャッシュから削除され、そのオブジェクトが参照するオブジェクトは削除候補となる。IDirectMusicLoader8::CollectGarbage は、ほかのオブジェクトが使用中でないキャッシュされたオブジェクトを見つけ、キャッシュから削除し、メモリから解放する。

動作環境

ヘッダー : dmusici.h で宣言。

参照

ガベージ コレクション


IDirectMusicLoader8::EnableCache

ロードされるすべてのオブジェクトの自動的なキャッシングを有効または無効にするようローダーに指示する。デフォルトでは、すべてのクラスでキャッシングが有効になっている。

HRESULT EnableCache(
  REFGUID rguidClass,
  BOOL fEnable
);

パラメータ

rguidClass
キャッシュするオブジェクト クラスの識別子への参照 (C++) またはアドレス (C)。すべてのタイプのオブジェクトをキャッシュする場合は GUID_DirectMusicAllTypes。標準的なローダブル クラスのリストについては、「IDirectMusicLoader8」を参照すること。
fEnable
キャッシングを有効にする場合は TRUE、キャッシングを無効にして消去する場合は FALSE を設定する。

戻り値

キャッシュの状態が変更される場合は S_OK、キャッシュが既に希望の状態になっている場合は S_FALSE を返す。

注意

キャッシングを無効にせずにキャッシュを消去するには、IDirectMusicLoader8::ClearCache メソッドを呼び出す。

次のサンプル コードは、セグメント オブジェクトに限ってキャッシングを無効にするので、アプリケーションがそれらを解放した後はそれらのオブジェクトはメモリ内にとどまることはない。スタイル、コード マップ、DLS コレクションなど、共有すべきその他のオブジェクトは引き続きキャッシングされている。デフォルトですべてのオブジェクトのキャッシングは有効になっているので、EnableCache の最初の呼び出しは、通常は不要である。

void myPrepareLoader(IDirectMusicLoader8 *pILoader)

{
    pILoader->EnableCache(GUID_DirectMusicAllTypes, TRUE);
    pILoader->EnableCache(CLSID_DirectMusicSegment, FALSE);
}

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicLoader8::CacheObject、IDirectMusicLoader8::ClearCache、キャッシュの管理


IDirectMusicLoader8::EnumObject

要求されたタイプの利用可能なすべてのオブジェクトを列挙する。利用可能なオブジェクトとは、既にロードされているもの、または IDirectMusicLoader8::ScanDirectory を呼び出したときに検索ディレクトリ内に存在していたものである。

HRESULT EnumObject(
  REFGUID rguidClass,
  DWORD dwIndex,
  LPDMUS_OBJECTDESC pDesc
);

パラメータ

rguidClass
表示されるオブジェクトのクラス識別子への参照 (C++) またはアドレス (C)。標準的なローダブル クラスのリストについては、「IDirectMusicLoader8」を参照すること。
dwIndex
リストのインデックス。通常は 0 から始まって、値が順に大きくなる。
pDesc
オブジェクトに関するデータを入力するための DMUS_OBJECTDESC 構造体のアドレス。

戻り値

成功した場合は S_OK を返す。dwIndex がリストの最後を超えている場合は S_FALSE を返す。

注意

このメソッドの使い方の例については、「オブジェクトの列挙」を参照すること。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicLoader8::ScanDirectory


IDirectMusicLoader8::GetObject

指定されたオブジェクトをファイルまたはリソースから取得し、目的のインターフェイスを返す。

HRESULT GetObject(
  LPDMUS_OBJECTDESC pDesc,
  REFIID riid,
  LPVOID FAR * ppv
);

パラメータ

pDesc
オブジェクトについて記述する DMUS_OBJECTDESC 構造体のアドレス。
riid
インターフェイスの一意の識別子。Dmusici.h で定義されている IID を参照すること。標準的なインターフェイスはすべて、"IID_" とインターフェイスの名前で構成される定義済みの識別子を持つ。たとえば、IDirectMusicTrack8 の識別子は IID_IDirectMusicTrack8 である。
ppv
オブジェクトの目的のインターフェイスへのポインタを受け取る変数のアドレス。

戻り値

成功した場合は S_OK または DMUS_S_PARTIALLOAD を返す。

セグメントで参照されるスタイルなど、参照されるオブジェクトが見つからない場合は、DMUS_S_PARTIALLOAD が返される。スタイルが名前で参照され、そのスタイルに対して IDirectMusicLoader8::ScanDirectory が呼び出されていない場合、ローダーはスタイルを見つけることができない場合がある。デフォルトの音色コレクション ファイルである Gm.dls が利用できない場合にも、DMUS_S_PARTIALLOAD が返されることがある。

失敗した場合は、次のいずれかのエラー値を返す。

E_FAIL
E_INVALIDARG
E_OUTOFMEMORY
E_POINTER
DMUS_E_LOADER_NOCLASSID
DMUS_E_LOADER_FAILEDOPEN
DMUS_E_LOADER_FAILEDCREATE
DMUS_E_LOADER_FORMATNOTSUPPORTED
REGDB_E_CLASSNOTREG

注意

ファイル オブジェクトの場合は、IDirectMusicLoader8::LoadObjectFromFile メソッドを使用する方が簡単である。

DirectMusic は URL からのローディングをサポートしない。DMUS_OBJECTDESC 構造体の dwValidData メンバが DMUS_OBJ_URL を含んでいる場合、このメソッドは DMUS_E_LOADER_FORMATNOTSUPPORTED を返す。

このメソッドは、オブジェクトを取得する前に DMUS_OBJECTDESC の相当するメンバを必要とすることはない。このメソッドは次の順序で検索を行う。

  1. DMUS_OBJ_OBJECT
  2. DMUS_OBJ_MEMORY
  3. DMUS_OBJ_FILENAME と DMUS_OBJ_FULLPATH
  4. DMUS_OBJ_NAME と DMUS_OBJ_CATEGORY
  5. DMUS_OBJ_NAME
  6. DMUS_OBJ_FILENAME

言い換えると、最も優先順位が高いのは一意の GUID であり、以下は、リソース、フル パス名、内部名とカテゴリ、内部名、ローカル ファイル名の順である。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicLoader8::ReleaseObject、IDirectMusicLoader8::ScanDirectory、IDirectMusicLoader8::LoadObjectFromFile


IDirectMusicLoader8::LoadObjectFromFile

指定されたオブジェクトをファイルから取得し、目的のインターフェイスを返す。このメソッドは、オブジェクトがファイル内にあるときに、IDirectMusicLoader8::GetObject の代わりに使用することができる。

HRESULT LoadObjectFromFile(
  REFGUID rguidClassID,
  REFIID iidInterfaceID,
  WCHAR *pwzFilePath,
  void ** ppObject
);

パラメータ

rguidClassID
オブジェクト クラスの一意の識別子。標準的なローダブル クラスのリストについては、「IDirectMusicLoader8」を参照すること。
iidInterfaceID
インターフェイスの一意の識別子。Dmusici.h で定義されている IID を参照すること。標準的なインターフェイスはすべて、"IID_" とインターフェイスの名前で構成される定義済みの識別子を持つ。たとえば、IDirectMusicTrack8 の識別子は IID_IDirectMusicTrack8 である。
pwzFilePath
オブジェクトを保持するファイルの名前。フル パスか、または検索ディレクトリからの相対パスを使用できる。
ppObject
オブジェクトの目的のインターフェイスへのポインタを受け取る変数のアドレス。

戻り値

成功した場合は S_OK または DMUS_S_PARTIALLOAD を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_FAIL
E_INVALIDARG
E_OUTOFMEMORY
E_POINTER
DMUS_E_LOADER_NOCLASSID
DMUS_E_LOADER_FAILEDOPEN
DMUS_E_LOADER_FAILEDCREATE
DMUS_E_LOADER_FORMATNOTSUPPORTED
REGDB_E_CLASSNOTREG

注意

セグメントで参照されるスタイルなど、参照されるオブジェクトが見つからない場合は、DMUS_S_PARTIALLOAD が返される。スタイルが名前で参照され、そのスタイルに対して IDirectMusicLoader8::ScanDirectory が呼び出されていない場合、ローダーはスタイルを見つけることができない場合がある。デフォルトの音色コレクション ファイルである Gm.dls が利用できない場合にも、DMUS_S_PARTIALLOAD が返されることがある。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicLoader8::GetObject、IDirectMusicLoader8::SetSearchDirectory


IDirectMusicLoader8::ReleaseObject

オブジェクトへのローダーの参照を解放する。

HRESULT ReleaseObject(
  IDirectMusicObject * pObject
);

パラメータ

pObject
解放するオブジェクトの IDirectMusicObject8 インターフェイス ポインタ。

戻り値

成功した場合は S_OK を返す。オブジェクトが既に解放されているか、またはキャッシュ内で検出されない場合は、S_FALSE を返す。

失敗した場合は E_POINTER を返す。

注意

ReleaseObject は、IDirectMusicLoader8::CacheObject と対をなすメソッドである。

オブジェクトのキャッシングは、CacheObject メソッドを使って明示的に、または IDirectMusicLoader8::EnableCache メソッドを使って自動的に行うことができる。

特定のタイプのすべてのオブジェクトをフラッシュ (解放) するようローダーに指示するには、IDirectMusicLoader8::ClearCache メソッドを呼び出す。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicLoader8::ReleaseObjectByUnknown、IDirectMusicLoader8::GetObject、キャッシュの管理


IDirectMusicLoader8::ReleaseObjectByUnknown

オブジェクトへのローダーの参照を解放する。このメソッドは、IDirectMusicLoader8::ReleaseObject に類似しており、IDirectMusicObject8 インターフェイスをすぐには利用できないオブジェクトを解放するのに適している。

HRESULT ReleaseObject(
  IUnknown * pObject
);

パラメータ

pObject
解放するオブジェクトの IUnknown インターフェイス ポインタのアドレス。

戻り値

成功した場合は S_OK を返す。オブジェクトが既に解放されているか、またはキャッシュ内で検出されない場合は、S_FALSE を返す。

失敗した場合は E_POINTER を返す。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicLoader8::GetObject、キャッシュの管理


IDirectMusicLoader8::ScanDirectory

ディスク内のあるディレクトリで、指定のクラス タイプとファイル名の拡張子を持つすべてのファイルを検索する。ファイルが見つかるたびに、IDirectMusicObject8::ParseDescriptor メソッドを呼び出して、オブジェクトの GUID と名前を抽出する。この情報は内部データベースに保存される。あるディレクトリを検索した後、指定されたタイプに属するすべてのファイルは IDirectMusicLoader8::EnumObject メソッドの列挙型として利用可能になる。加えて、IDirectMusicLoader8::GetObject を使うときに、ファイル名なしでもオブジェクトが取得可能になる。

HRESULT ScanDirectory(
  REFGUID rguidClass,
  WCHAR* pwzFileExtension,
  WCHAR* pwzScanFileName
);

パラメータ

rguidClass
オブジェクトのクラス識別子への参照 (C++) またはアドレス (C)。標準的なローダブル クラスのリストについては、「IDirectMusicLoader8」を参照すること。
pwzFileExtension
検索するファイルのタイプを表すファイル名の拡張子。"*" を使って、任意の拡張子の付いたファイルまたは拡張子のないファイルを検索する。「注意」を参照すること。
pwzScanFileName
キャッシングされたファイル情報の保存と取得を行うための保存ファイル。省略可能。最初に ScanDirectory を呼び出したときにこのファイルが作成され、それ以降の呼び出しで使われる。キャッシュ ファイルが不要な場合は NULL を指定する。

戻り値

成功した場合は S_OK を返す。ファイルが見つからなかった場合は S_FALSE を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_NOT_FOUND
E_FAIL
E_OUTOFMEMORY
E_POINTER
REGDB_E_CLASSNOTREG

注意

検索の場所を設定するために、最初に IDirectMusicLoader8::SetSearchDirectory メソッドを呼び出さなければならない。

pwzScanFileName で定義されるファイルに、検索された情報を保存できる。保存を行うと、変更を加えられたファイルだけが検索されるため、それ以降の ScanDirectory の呼び出しが大幅に高速化される (キャッシュ ファイルには各オブジェクトのファイル サイズと日付が保存されるので、ファイルが変更された場合はそのことを検出できる)。

GUID_DirectMusicAllTypes は rguidClass の有効な値ではない。

ファイル タイプが複数の拡張子を持つ可能性がある場合、ファイル名の拡張子ごとに ScanDirectory を 1 回呼び出す。

動作環境

ヘッダー : dmusici.h で宣言。

参照

ディレクトリでのオブジェクト検索


IDirectMusicLoader8::SetObject

オブジェクトが、ロード中の別のオブジェクトによって後で参照されるときに、オブジェクトの検索場所をローダーに指示する。次に、オブジェクトに属性を追加することによって、属性を使ってそのオブジェクトを参照できるようにする。概要については、「オブジェクトの設定」を参照すること。

HRESULT SetObject(
  LPDMUS_OBJECTDESC pDesc
);

パラメータ

pDesc
オブジェクトについて記述する DMUS_OBJECTDESC 構造体のアドレス。エントリ時に、この構造体はオブジェクトに関してアプリケーションが持つあらゆる情報を保持する。戻り値として、この構造体は追加の情報を保持している場合がある。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_FAIL
E_INVALIDARG
E_OUTOFMEMORY
E_POINTER
DMUS_E_LOADER_NOCLASSID
DMUS_E_LOADER_FAILEDOPEN
DMUS_E_LOADER_FAILEDCREATE
DMUS_E_LOADER_FORMATNOTSUPPORTED
REGDB_E_CLASSNOTREG

注意

このメソッドを使って、オブジェクトについて現在有効でない属性を設定できる。たとえば、DMUS_OBJECTDESC 構造体の wszName メンバに値を入力し、MIDI ファイルに基づくセグメントなど、名前のないオブジェクトに内部名を割り当てることができる。ただし、既存属性を変更する目的でこのメソッドを使用することはできない。たとえば、ほとんどのオーサリングされたセグメントは既に名前を持っており、これらの名前をアプリケーションによって変更することはできない。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicLoader8::GetObject


IDirectMusicLoader8::SetSearchDirectory

オブジェクト ファイルを探すための検索パスを設定する。1 つのオブジェクト タイプ、またはすべてのファイルに対する検索パスを設定できる。

HRESULT SetSearchDirectory(
  REFGUID rguidClass,
  WCHAR* pwszPath,
  BOOL fClear
);

パラメータ

rguidClass
呼び出しに関係のあるオブジェクトのクラス識別子への参照 (C++) またはアドレス (C)。GUID_DirectMusicAllTypes は、すべてのタイプを指定する。標準的なローダブル クラスのリストについては、「IDirectMusicLoader8」を参照すること。
pwszPath
ディレクトリのファイル パス。長さが MAX_PATH 以下の有効なディレクトリ名でなければならない。フル パスか、または IDirectMusicLoader8::ScanDirectory の呼び出し時の現在ディレクトリからの相対パスである。
fClear
TRUE の場合、ディレクトリを設定する前に、オブジェクトに関するすべての情報を消去する。この結果、同じ名前を持つほかのディレクトリにあるオブジェクトへのアクセスを回避できる。ただし、それらのオブジェクトはキャッシュから削除されるわけではない。

戻り値

成功した場合は S_OK を返す。検索ディレクトリが既に pwszPath に設定されている場合は S_FALSE を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_OUTOFMEMORY
E_POINTER
DMUS_E_LOADER_BADPATH

注意

検索パスを設定した後、ローダーはファイル名を使ってオブジェクトをロードするときに、フル パス名を必要としない。この結果、オブジェクトはフル パスを把握していなくてもほかのオブジェクトを参照できる。

このメソッドが呼び出されたときに、DMUS_OBJECTDESC 構造体の dwValidData メンバに DMUS_OBJ_FULLPATH フラグが設定されていなければ、ローダーは wszFileName メンバがファイル名のみ、または検索ディレクトリからの相対パスを保持していることを想定する。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicLoader8::ScanDirectory、ローダーの検索ディレクトリの設定


IDirectMusicObject8

ファイルからロード可能なすべての DirectMusic オブジェクトは、DirectMusic ローダーで操作できるように IDirectMusicObject8 インターフェイスをサポートする。新しいタイプのオブジェクトは、このインターフェイスを実装しなければならない。詳細については、「カスタム ロード」を参照すること。

ほとんどのアプリケーションは、このインターフェイスのメソッドを直接使用しない。ただし、IDirectMusicObject8::GetDescriptor を使って、オブジェクトの名前、GUID、ファイル パス、バージョンなど、オブジェクトに関する情報を問い合わせることができる。

IDirectMusicObject8 インターフェイスは通常、別のインターフェイスの QueryInterface メソッドを呼び出すことによって取得される。CoCreateInstance を使って呼び出すことはできない。IDirectMusicObject8 インターフェイスは、IDirectMusicContainer8::EnumObject で取得することもできる。

IDirectMusicObject8 は、IDirectMusicObject の定義である。2 つのインターフェイス名は入れ替え可能である。

IDirectMusicObject8 インターフェイスには次のメソッドがある。

ディスクリプタ | GetDescriptor
 | ParseDescriptor
 | SetDescriptor

すべての COM インターフェイスは IUnknown インターフェイスのメソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDMUS_OBJECT 型は、IDirectMusicObject インターフェイスへのポインタとして定義されている。

typedef IDirectMusicObject __RPC_FAR *LPDMUS_OBJECT;

動作環境

ヘッダー : dmusici.h で宣言。

参照

オーディオ データのロード、カスタム ロード


IDirectMusicObject8::GetDescriptor

オブジェクトの内部的な記述を取得する。

HRESULT GetDescriptor(
  LPDMUS_OBJECTDESC pDesc
);

パラメータ

pDesc
オブジェクトに関するデータを入力するための DMUS_OBJECTDESC 構造体のアドレス。オブジェクトの実装と、オブジェクトをファイルからロードした方法に基づいて、GetDescriptor が標準的なパラメータの一部またはすべてを入力する。dwValidData メンバ内のフラグをチェックして、ほかの有効なメンバを確認する。

戻り値

成功した場合は S_OK または DMUS_S_GARBAGE_COLLECTED を返す。「ガベージ コレクション」を参照すること。

失敗した場合は E_POINTER を返す。

注意

具体的な例については、「オブジェクト ディスクリプタの取得」を参照すること。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicObject8::SetDescriptor


IDirectMusicObject8::ParseDescriptor

IDirectMusicObject8::ParseDescriptor メソッドはファイル ストリームを受け取り、DMUS_OBJECTDESC 構造体に保存できるデータをファイルから検索する。dwValidData 内で、供給されたメンバに対して適切なフラグを割り当てる。

このメソッドは、主にローダーがディレクトリでオブジェクトを検索する際に使われるものであり、通常はアプリケーションが直接利用することはない。ただし、アプリケーションが DirectMusic 内にオブジェクト タイプを実装する場合、そのアプリケーションはこのメソッドをサポートすべきである。

HRESULT ParseDescriptor(
  LPSTREAM pStream,
  LPDMUS_OBJECTDESC pDesc
);

パラメータ

pStream
ファイルのストリーム ソース。
pDesc
ファイルに関するデータを受け取る DMUS_OBJECTDESC 構造体のアドレス。

戻り値

成功した場合は S_OK または DMUS_S_GARBAGE_COLLECTED を返す。「ガベージ コレクション」を参照すること。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_CHUNKNOTFOUND
DMUS_E_INVALID_BAND
DMUS_E_INVALIDFILE
DMUS_E_NOTADLSCOL
E_FAIL
E_OUTOFMEMORY
E_POINTER

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicObject8::SetDescriptor


IDirectMusicObject8::SetDescriptor

オブジェクトの内部的な記述を一部またはすべてのメンバに設定する。

このメソッドは、主にローダーがオブジェクトを作成する際に使われるものであり、通常はアプリケーションが直接利用することはない。ただし、アプリケーションが DirectMusic 内にオブジェクト タイプを実装する場合、そのアプリケーションはこのメソッドをサポートすべきである。

HRESULT SetDescriptor(
  LPDMUS_OBJECTDESC pDesc
);

パラメータ

pDesc
オブジェクトに関するデータを受け取る DMUS_OBJECTDESC 構造体のアドレス。dwValidData メンバで有効と定義されているすべてのメンバにデータがコピーされる。

戻り値

成功した場合は、次のいずれかのコードを返す。

S_OK | ディスクリプタが設定された。
S_FALSE | 「注意」を参照すること。
DMUS_S_GARBAGE_COLLECTED | 「ガベージ コレクション」を参照すること。

失敗した場合は、次のいずれかのエラー値を返す。

E_INVALIDARG
E_POINTER

注意

アプリケーションは通常、標準的なオブジェクトに対してこのメソッドを呼び出すことはない。IDirectMusicObject8::GetDescriptor によって返されるオブジェクト ディスクリプタを変更することは可能であるが、新しい記述を IDirectMusicLoader8::GetObject メソッドに正常に渡すことはできない。たとえば、オブジェクトの名前を変更することはできるが、変更しても、GetObject はオブジェクトの元の名前を使ってそのオブジェクトを検索する。これは、GetObject がオブジェクト自体の SetDescriptor の実装に依存しているためである。

コピーされなかったメンバは、それまでの値を維持する。たとえば、あるオブジェクトが名前と GUID を既に内部で保存していたとする。新しい名前とファイル パスを指定して (さらに dwValidData に DMUS_OBJ_NAME | DMUS_OBJ_FILENAME を含めて) SetDescriptor メソッドを呼び出すと、名前は置き換えられ、ファイル名が提供されるが、GUID だけは元の値のままになる。

オブジェクトが 1 つまたは複数のメンバを設定できない場合、自らがサポートしているメンバだけを設定し、サポートしていないメンバに対応する dwValidData 内のフラグを消去し、S_FALSE を返す。アプリケーションによって定義されるオブジェクトは、少なくとも DMUS_OBJ_NAME と DMUS_OBJ_OBJECT をサポートすべきである。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicObject8::ParseDescriptor、IDirectMusicObject8::GetDescriptor


IDirectMusicPatternTrack8

IDirectMusicPatternTrack8 インターフェイスは、単一のパターンを保持するトラックを表す。パターン トラックは、シーケンス トラックと類似しているが、固定されたノートではなくミュージック値を保持するので、コード チェンジに対応する。

IID_DirectMusicPatternTrack をパターン トラックの IDirectMusicTrack8::QueryInterface メソッドに渡すことで、このインターフェイスを取得できる。

IDirectMusicPatternTrack8 インターフェイスには次のメソッドがある。

セグメントの作成 | CreateSegment
パターンの設定 | SetPatternByName
バリエーションの設定 | SetVariation

すべての COM インターフェイスは IUnknown インターフェイスのメソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicPatternTrack8::CreateSegment

パターン トラックを保持するセグメントを作成する。

HRESULT CreateSegment(
  IDirectMusicStyle* pStyle,
  IDirectMusicSegment** ppSegment
);

パラメータ

pStyle
セグメントを作成する際に使用するスタイル。
ppSegment
作成されたセグメントの IDirectMusicSegment インターフェイス ポインタを受け取る変数のアドレス。IDirectMusicSegment8 を取得するには、QueryInterface を使用する。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_NOT_INIT
E_OUTOFMEMORY

注意

パターン トラックは通常、ファイルやリソースからロードされたセグメント オブジェクトから取得される。この場合、アプリケーションは既に IDirectMusicSegment インターフェイスを持っている。このメソッドは、パターン トラック オブジェクトが CoCreateInstance で作成された場合に、セグメントを作成するために使用する。

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicPatternTrack8::SetPatternByName

トラックで再生されるパターンを設定する。パターンはスタイルから取得する。

HRESULT SetPatternByName(
  IDirectMusicSegmentState* pSegState,
  WCHAR* wszName,
  IDirectMusicStyle* pStyle,
  DWORD dwPatternType,
  DWORD* pdwLength
);

パラメータ

pSegState
トラックを再生しているセグメント状態の IDirectMusicSegmentState8 インターフェイスのアドレス。
wszName
設定するパターンの名前。名前は IDirectMusicStyle8::EnumPattern を使って取得できる。
pStyle
パターンを保持するスタイルの IDirectMusicStyle または IDirectMusicStyle8 インターフェイスのアドレス。
dwPatternType
パターンのタイプを指定する DMUS_STYLET_TYPES 列挙の 1 つ。
pdwLength
パターンの長さ (ミュージック タイムのティック単位) を受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_NOT_FOUND
DMUS_E_NOT_INIT
E_OUTOFMEMORY
E_POINTER

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicPatternTrack8::SetVariation

トラックで再生されるバリエーションを設定する。

HRESULT SetVariation(
  IDirectMusicSegmentState* pSegState,
  DWORD dwVariationFlags,
  DWORD dwPart
);

パラメータ

pSegState
トラックを再生しているセグメント状態の IDirectMusicSegmentState8 インターフェイスのアドレス。
dwVariationFlags
演奏されるバリエーションごとに設定されたビットに対するヒットマスク。
dwPart
バリエーションを保持するパートの識別子。これは、ミュージック オーサリング アプリケーションでパートに割り当てられた番号であり、P チャンネルに等しい。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_NOT_INIT
E_POINTER

注意

バリエーションは、一度に 1 つのパートだけに設定できる。このメソッドが呼び出されるたびに、前の呼び出しが上書きされる。

次のサンプル コードは、パフォーマンス チャンネル 1 でバリエーション 16 とバリエーション 32 を演奏する。

// pPattern は IDirectMusicPatternTrack8 ポインタである。
// pSegmentState は IDirectMusicSegmentState8 ポインタである。

#define VARIATION(v)  (1 << ((v) - 1))

HRESULT hr = pPattern->SetVariation(
    pSegmentState, VARIATION(32) | VARIATION(16), 1);

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicPerformance8

IDirectMusicPerformance8 インターフェイスは、音楽演奏全体のマネージャである。このインターフェイスは、ポートの追加と削除、パフォーマンス チャンネルのポートへのマッピング、セグメントの演奏、ツールによるメッセージの発信とルーティング、イベント通知の要求と受け取り、およびミュージック パラメータの設定と取得に使用される。また、タイミングに関する情報の取得、およびシステム間でタイムとミュージック値を変換するためのメソッドも備えている。

アプリケーションが 2 つの完全なミュージック セットを同時に演奏したい場合、複数のパフォーマンスを作成することにより、そのような演奏が行える。個別のパフォーマンスは独立したテンポ マップに従い、完全に非同期に演奏されるが、一方で 1 つのパフォーマンス内のすべてのセグメントは固定的なステップで演奏される。

IDirectMusicPerformance8 は、IDirectMusicPerformance インターフェイスを引き継ぎ、新しいメソッドを追加する。

IDirectMusicPerformance8 のメソッドは、以下のグループにまとめることができる。

オーディオパス | CreateAudioPath
 | CreateStandardAudioPath
 | GetDefaultAudioPath
 | SetDefaultAudioPath
チャンネル | AssignPChannel
 | AssignPChannelBlock
 | PChannelInfo
音色 | DownloadInstrument
メッセージ | AllocPMsg
 | ClonePMsg
 | FreePMsg
 | SendPMsg
MIDI 変換 | MIDIToMusic
 | MusicToMIDI
通知 | AddNotificationType
 | GetNotificationPMsg
 | RemoveNotificationType
 | SetNotificationHandle
パラメータ | GetGlobalParam
 | GetParam
 | GetParamEx
 | SetGlobalParam
 | SetParam
再生 | GetSegmentState
 | IsPlaying
 | PlaySegment
 | PlaySegmentEx
 | Stop
 | StopEx
ポート | AddPort
 | RemovePort
タイミング | AdjustTime
 | GetBumperLength
 | GetLatencyTime
 | GetPrepareTime
 | GetQueueTime
 | GetResolvedTime
 | GetTime
 | MusicToReferenceTime
 | ReferenceToMusicTime
 | RhythmToTime
 | SetBumperLength
 | SetPrepareTime
 | TimeToRhythm
ツール | GetGraph
 | SetGraph
その他 | CloseDown
 | Init
 | InitAudio
 | Invalidate

すべての COM インターフェイスは IUnknown インターフェイスのメソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicPerformance8::AddNotificationType

パフォーマンスに通知タイプを追加する。AddNotificationType メソッドを呼び出すと、すべてのセグメントとトラックは新しい通知によって自動的に更新される。

HRESULT AddNotificationType(
  REFGUID rguidNotificationType
);

パラメータ

rguidNotificationType
追加される通知タイプの識別子への参照 (C++) またはアドレス (C)。定義済みのタイプについては、「DMUS_NOTIFICATION_PMSG」を参照すること。アプリケーションは、カスタム トラックについて独自のタイプを定義できる。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_OUTOFMEMORY
E_POINTER

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::RemoveNotificationType、IDirectMusicSegment8::AddNotificationType、IDirectMusicTrack8::AddNotificationType、通知とイベントの処理


IDirectMusicPerformance8::AddPort

パフォーマンスにポートを割り当てる。このメソッドは、オーディオパスを使用しないパフォーマンスに対してのみ有効である。つまり、パフォーマンスは IDirectMusicPerformance8::Init を使用して初期化される。

HRESULT AddPort(
  IDirectMusicPort* pPort
);

パラメータ

pPort
追加するポートを含む変数のアドレス。NULL の場合はデフォルト ポートが追加される。「注意」を参照すること。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_NOT_INIT
DMUS_E_CANNOT_OPEN_PORT
E_OUTOFMEMORY
E_POINTER

注意

pPort に NULL を渡してデフォルト ポートが指定された場合、このデフォルト ポートには 1 つのチャンネル グループが割り当てられる。その他のポートについてパフォーマンス チャンネルが設定されていない場合、0 ～ 15 のチャンネルが、0 ～ 15 の MIDI チャンネルに割り当てられる。

pPort が NULL でない場合、ポートはそのポートが渡されたのと同じ DirectMusic オブジェクトによって作成されるか、または IDirectMusicPerformance8::Init によって作成される必要がある。 IDirectMusicPort8::Activate を呼び出してポートをアクティブにし、IDirectMusicPerformance8::AssignPChannelBlock を呼び出してチャンネル ブロックを割り当てなければならない。

このメソッドは、IDirectMusicPort8 への参照を作成する。この参照は、IDirectMusicPerformance8::RemovePort または IDirectMusicPerformance8::CloseDown によって解放される。ただし、AddPort に NULL が渡される場合、アプリケーションには RemovePort に渡す参照がないため、RemovePort でポートを削除することはできない。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::RemovePort、デフォルト ポート


IDirectMusicPerformance8::AdjustTime

パフォーマンスの内部時間を前方または後方に調整する。このメソッドはほとんどの場合、ほかのソースとの同期化を行う際にずれを補正するために使われる。

HRESULT AdjustTime(
  REFERENCE_TIME rtAmount
);

パラメータ

rtAmount
加算または減算される時間。－10,000,000 から 10,000,000 (－1 秒から +1 秒) の数値を指定する。

戻り値

成功した場合は S_OK を返す。

失敗した場合は E_INVALIDARG を返す。

注意

調整された時間は、DirectMusic によって内部的に使用される。IDirectMusicPerformance8::GetTime メソッドで取得される時間には反映されない。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::GetTime、タイミング


IDirectMusicPerformance8::AllocPMsg

パフォーマンス メッセージを割り当てる。

HRESULT AllocPMsg(
  ULONG cb,
  DMUS_PMSG** ppPMSG
);

パラメータ

cb
メッセージ構造体のサイズ。この構造体は、DMUS_PMSG の派生タイプである。
ppPMSG
割り当てられたメッセージ構造体へのポインタを受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_INVALIDARG
E_OUTOFMEMORY
E_POINTER

注意

メッセージ構造体の dwSize メンバは、cb の値に設定される。内部キャッシングのため、ほかのメンバを 0 に初期化する必要はない。

メッセージが IDirectMusicPerformance8::SendPMsg によって送信された後は、アプリケーションはメモリを確保せず、メッセージの解放も行わない。ただし、ツールは、その IDirectMusicTool8::Flush メソッドまたは IDirectMusicTool8::ProcessPMsg メソッド内でメッセージを解放できる。アプリケーションは、通知メッセージの解放も行う。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::FreePMsg、IDirectMusicPerformance8::SendPMsg、DirectMusic メッセージ


IDirectMusicPerformance8::AssignPChannel

1 つのパフォーマンス チャンネルをパフォーマンスに割り当て、このチャンネルをポート、グループ、MIDI チャンネルにマップする。

オーディオパスを通してデータを渡すアプリケーションでは、このメソッドは使用されない。

HRESULT AssignPChannel(
  DWORD dwPChannel,
  IDirectMusicPort* pPort,
  DWORD dwGroup,
  DWORD dwMChannel
);

パラメータ

dwPChannel
割り当てるパフォーマンス チャンネル。
pPort
チャンネルの割り当て先のポートを含む変数のアドレス。
dwGroup
ポート上のチャンネル グループ。
dwMChannel
グループ内のチャンネル。0 ～ 15 の範囲でなければならない。

戻り値

成功した場合は S_OK または S_FALSE を返す (「注意」を参照すること)。

失敗した場合は、次のいずれかのエラー値を返す。

E_INVALIDARG
E_POINTER

注意

dwGroup がポートの範囲外の場合、このメソッドは S_FALSE を返す。チャンネルは割り当てられるが、ポートはそのグループを演奏できない。

dwMChannel が範囲外、または IDirectMusicPerformance8::AddPort メソッドを呼び出してポートをパフォーマンスに追加する作業を行っていない場合、このメソッドは E_INVALIDARG を返す。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::AssignPChannelBlock、IDirectMusicPerformance8::PChannelInfo、チャンネル


IDirectMusicPerformance8::AssignPChannelBlock

16 のパフォーマンス チャンネルから成るブロックをパフォーマンスに割り当て、それらをポートとチャンネル グループにマップする。このメソッドは、オーディオパスを使用しないパフォーマンスに対してのみ有効である。つまり、パフォーマンスは IDirectMusicPerformance8::Init を使用して初期化される。

HRESULT AssignPChannelBlock(
  DWORD dwBlockNum,
  IDirectMusicPort* pPort,
  DWORD dwGroup
);

パラメータ

dwBlockNum
ブロック番号。0 はチャンネル 0 ～ 15、1 はチャンネル 16 ～ 31 を表す。以下同様である。
pPort
チャンネルの割り当て先のポートを含む変数のアドレス。
dwGroup
ポート上のチャンネル グループ。1 以上の値でなければならない。

戻り値

成功した場合は S_OK または S_FALSE を返す (「注意」を参照すること)。

失敗した場合は、次のいずれかのエラー値を返す。

E_INVALIDARG
E_POINTER

注意

ポートがパフォーマンスに追加されたときに、このメソッドを呼び出す必要がある。ただし、IDirectMusicPerformance8::AddPort に NULL を渡すことでデフォルト ポートが追加された場合を除く。

dwGroup がポートの範囲外の場合、このメソッドは S_FALSE を返す。チャンネルは割り当てられるが、ポートはそのグループを演奏できない。

dwMChannel が範囲外、または IDirectMusicPerformance8::AddPort メソッドを呼び出してポートをパフォーマンスに追加する作業を行っていない場合、このメソッドは E_INVALIDARG を返す。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::AssignPChannel、IDirectMusicPerformance8::PChannelInfo、チャンネル


IDirectMusicPerformance8::ClonePMsg

パフォーマンス メッセージのコピーを作成する。

HRESULT ClonePMsg(
  DMUS_PMSG* pSourcePMSG,
  DMUS_PMSG** ppCopyPMSG
);

パラメータ

pSourcePMSG
コピーするメッセージ。
ppCopyPMSG
コピーするメッセージへのポインタを受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_OUTOFMEMORY
E_POINTER

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicPerformance8::CloseDown

パフォーマンス オブジェクトを閉じる。パフォーマンス オブジェクトを作成し、そのオブジェクトに対して IDirectMusicPerformance8::Init または IDirectMusicPerformance8::InitAudio を呼び出したアプリケーションは、パフォーマンスを解放する前に CloseDown を呼び出さなければならない。

HRESULT CloseDown();

パラメータ

なし。

戻り値

S_OK を返す。

注意

CloseDown の呼び出しを忘れると、メモリ リークやプログラム障害が発生することがある。

IDirectMusicPerformance8::Init または IDirectMusicPerformance8::InitAudio により IDirectMusic8 インターフェイスの参照が作成された場合、CloseDown がその解放を処理する。アプリケーションが DirectMusic オブジェクトを明示的に作成した場合は、そのアプリケーションが参照の解放を行う必要がある。

DirectSound オブジェクトが Init または InitAudio の呼び出しで作成され、アプリケーションに参照が返されなかった場合、CloseDown は DirectSound およびすべての DirectSound バッファも解放する。アプリケーションで DirectSound バッファへのインターフェイスを取得した場合は、それらを解放してから Closedown を呼び出す。

アプリケーションが DirectSound を明示的に作成、または Init あるいは InitAudio から参照を取得した場合、DirectSound を解放する必要がある。

このメソッドは、ダウンロードしてまだアンロードしていない音色を解放する。

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicPerformance8::CreateAudioPath

パフォーマンスから DirectSound バッファへのデータ フロー内の各ステージを表す、オーディオパス オブジェクトを作成する。

HRESULT CreateAudioPath(
  IUnknown *pSourceConfig,
  BOOL fActivate,
  IDirectMusicAudioPath **ppNewPath
);

パラメータ

pSourceConfig
オーディオパス構成を表すインターフェイスのアドレス。「注意」を参照すること。
fActivate
作成時にパスをアクティブにするかどうかを指定するブール型の値。
ppNewPath
オーディオパスの IDirectMusicAudioPath8 インターフェイス ポインタを受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_NOINTERFACE
E_POINTER
DMUS_E_NOT_INIT
DMUS_E_AUDIOPATHS_NOT_VALID
DSERR_BUFFERLOST
E_OUTOFMEMORY

注意

pSourceConfig がアドレスするオブジェクトは、IDirectMusicSegment8::GetAudioPathConfig メソッドを使ってセグメントから取得するか、ファイルから直接ロードすることができる。

DirectSound が何かのアプリケーションによって書き込み優先協調レベルで初期化されていると、このメソッドは失敗して DSERR_BUFFERLOST を返す。

利用できないサウンド デバイスがオーディオパス構成で指定されていると、このメソッドは E_NOINTERFACE を返す。

動作環境

ヘッダー : dmusici.h で宣言。

参照

オーディオパスの作成


IDirectMusicPerformance8::CreateStandardAudioPath

パフォーマンスから DirectSound バッファへのデータ フロー内の各ステージを表す、オブジェクトを作成する。このメソッドを使用すると、IDirectMusicPerformance8::CreateAudioPath でソース ファイルに定義されたオーディオパスを作成する代わりに、基本的な事前定義オーディオパスを作成することができる。

HRESULT  CreateStandardAudioPath(
  DWORD dwType,
  DWORD dwPChannelCount,
  BOOL  fActivate,
  IDirectMusicAudioPath **ppNewPath
);

パラメータ

dwType
パスのタイプ。次の値が定義されている。
DMUS_APATH_DYNAMIC_3D
3D バッファに対する 1 つのバス。環境リバーブには送らない。
DMUS_APATH_DYNAMIC_MONO
モノラル バッファに対する 1 つのバス。
DMUS_APATH_SHARED_STEREOPLUSREVERB
ステレオ出力とリバーブを備えた、通常のミュージック セットアップ。
DMUS_APATH_DYNAMIC_STEREO
ステレオ バッファに対する 2 つのバス。

これらのオーディオパスの詳細については、「標準オーディオパス」を参照すること。

dwPChannelCount
パス内のパフォーマンス チャンネルの数。
fActivate
作成時にパスをアクティブにするかどうかを指定するブール型の値。
ppNewPath
オーディオパスの IDirectMusicAudioPath インターフェイス ポインタを受け取る変数のアドレス。「IDirectMusicAudioPath8」を参照すること。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_POINTER
DMUS_E_NOT_INIT
DMUS_E_AUDIOPATHS_NOT_VALID
DSERR_BUFFERLOST
E_INVALIDARG
E_OUTOFMEMORY

注意

DirectSound が何かのアプリケーションによって書き込み優先協調レベルで初期化されていると、このメソッドは失敗して DSERR_BUFFERLOST を返す。

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicPerformance8::DownloadInstrument

音色に対応する DLS データをポートにダウンロードする。

HRESULT DownloadInstrument(
  IDirectMusicInstrument* pInst,
  DWORD dwPChannel,
  IDirectMusicDownloadedInstrument** ppDownInst,
  DMUS_NOTERANGE* pNoteRanges,
  DWORD dwNumNoteRanges,
  IDirectMusicPort** ppPort,
  DWORD* pdwGroup,
  DWORD* pdwMChannel
);

パラメータ

pInst
ダウンロードする音色の IDirectMusicInstrument8 インターフェイスへのポインタ。
dwPChannel
音色の割り当て先のパフォーマンス チャンネル。
ppDownInst
ダウンロードされた音色への IDirectMusicDownloadedInstrument8 インターフェイス ポインタを受け取る変数のアドレス。
pNoteRanges
DMUS_NOTERANGE 構造体の配列のアドレス。配列内の各エントリは、音色が応答しなければならない MIDI ノートメッセージの連続範囲を指定する。音色のリージョンがダウンロードされるのは、そのリージョン内の少なくとも 1 つのノートが DMUS_NOTERANGE 構造体で指定されている場合に限られる。
dwNumNoteRanges
pNoteRanges が指す配列内の DMUS_NOTERANGE 構造体の数。この値が 0 に設定されている場合、pNoteRanges パラメータは無視され、この音色のすべてのリージョンとウェーブ データがダウンロードされる。
ppPort
音色のダウンロード先のポートへのポインタを受け取る変数のアドレス。
pdwGroup
音色の割り当て先のグループを受け取る変数のアドレス。
pdwMChannel
音色の割り当て先の MIDI チャンネルを受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_INVALIDARG
E_POINTER

注意

音色のダウンロードは通常、バンドによって処理されるため、ほとんどのアプリケーションではこのメソッドを使う必要がない。「バンドのダウンロードとアンロード」を参照すること。

パフォーマンス チャンネルがポートに割り当てられていない場合、このメソッドは E_INVALIDARG を返す。

リソースの浪費を防ぐには、音色が不要になったときに、IDirectMusicPort8::UnloadInstrument メソッドを使ってアンロードする。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPort8::DownloadInstrument、IDirectMusicPort8::UnloadInstrument、音色の操作


IDirectMusicPerformance8::FreePMsg

メッセージを解放する。

HRESULT FreePMsg(
  DMUS_PMSG* pPMSG
);

パラメータ

pPMSG
解放するメッセージを含む変数のアドレス。このメッセージは、IDirectMusicPerformance8::AllocPMsg メソッドを使って割り当てておく必要がある。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_CANNOT_FREE
E_POINTER

注意

ほとんどのメッセージは、処理されると、パフォーマンスによって自動的に解放される。また、IDirectMusicPerformance8::SendPMsg を使って送信されたメッセージに対して、IDirectMusicPerformance8::FreePMsg を呼び出してはならない。ただし、IDirectMusicPerformance8::FreePMsg は、IDirectMusicTool8::ProcessPMsg または IDirectMusicTool8::Flush の中で使うと、不要なメッセージを解放することができる。通知メッセージを解放する際にも、IDirectMusicPerformance::FreePMsg を使用しなければならない。

このメソッドは、以下の場合に DMUS_E_CANNOT_FREE を返す。

  • pPMSG が、AllocPMsg を使って割り当てたメッセージを表していない場合。
  • IDirectMusicPerformance8::SendPMsg を呼び出したために pPMSG が現在パフォーマンス キューに置かれている場合。ただし、SendPMsg は同期されていないため、アプリケーションは FreePMsg がすべての送信されたメッセージに対して DMUS_E_CANNOT_FREE を返すものと見なすことができなくなる。
  • pPMSG が既に解放されている場合。

pTool、pGraph、punkUser のいずれかのメンバ (「DMUS_PMSG」を参照) 内に値が存在する場合、参照されている各オブジェクトは解放される。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::AllocPMsg、DirectMusic メッセージ


IDirectMusicPerformance8::GetBumperLength

メッセージがポート バッファに置かれたタイムと、ポートがメッセージの処理を開始するタイムの間の時間を取得する。このトピックの概要については、「タイミング」を参照すること。

HRESULT GetBumperLength(
  DWORD* pdwMilliSeconds
);

パラメータ

pdwMilliSeconds
演奏前の時間の長さが入る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は E_POINTER を返す。

注意

デフォルトの値は 50ミリ秒 (ms) である。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::SetBumperLength


IDirectMusicPerformance8::GetDefaultAudioPath

IDirectMusicPerformance8::InitAudio または IDirectMusicPerformance8::SetDefaultAudioPath で設定された、デフォルトのオーディオパスを取得する。

HRESULT GetDefaultAudioPath(
  IDirectMusicAudioPath **ppAudioPath
);

パラメータ

ppAudioPath
デフォルト オーディオパスの IDirectMusicAudioPath8 インターフェイス ポインタを受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_POINTER
DMUS_E_AUDIOPATHS_NOT_VALID
DMUS_E_NOT_INIT

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicPerformance8::GetGlobalParam

パフォーマンスからグローバル値を取得する。

HRESULT GetGlobalParam(
  REFGUID rguidType,
  void* pParam,
  DWORD dwSize
);

パラメータ

rguidType
データ型の識別子への参照 (C++) またはアドレス (C)。
pParam
データのコピーを受け取るために割り当てられたメモリへのポインタ。pParam には正しいサイズを指定しなければならない。サイズは各データ型について一定である。このパラメータは、IDirectMusicPerformance8::SetGlobalParam メソッドに渡された情報を保持する。
dwSize
データのサイズ。rguidType ごとに一定の値である。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_INVALIDARG
E_POINTER

注意

SetGlobalParam が rguidType について一度も呼び出されたことがない場合、このパフォーマンスが現在処理しているグローバル データ リストの中に、rguidType がない可能性がある。その場合、このメソッドは E_INVALIDARG を返す。つまり、どのパラメータにも、GetGlobalParam を使って取得できるデフォルト値があると想定しないこと。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::SetGlobalParam、IDirectMusicPerformance8::GetParam、パフォーマンス パラメータ


IDirectMusicPerformance8::GetGraph

パフォーマンスのツールグラフを取得する。

HRESULT GetGraph(
  IDirectMusicGraph** ppGraph
);

パラメータ

ppGraph
ツールグラフへのポインタを受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_NOT_FOUND
E_POINTER

注意

グラフの参照カウントはインクリメントされる。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::SetGraph、IDirectMusicSegment8::GetGraph、IDirectMusicPerformance8::SendPMsg


IDirectMusicPerformance8::GetLatencyTime

現在の遅延時間を取得する。遅延時間は、スピーカから音楽が聞こえている時間に、メッセージをキューに入れて IDirectMusicPort8 にレンダリングするための所要時間を加えた長さになる。このトピックの概要については、「タイミング」を参照すること。

HRESULT GetLatencyTime(
  REFERENCE_TIME * prtTime
);

パラメータ

prtTime
現在の遅延時間を受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_POINTER
DMUS_E_NO_MASTER_CLOCK

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicPerformance8::GetNotificationPMsg

保留中の通知メッセージを取得する。

HRESULT GetNotificationPMsg(
  DMUS_NOTIFICATION_PMSG** ppNotificationPMsg
);

パラメータ

ppNotificationPMsg
DMUS_NOTIFICATION_PMSG 構造体へのポインタを受け取る変数のアドレス。このメッセージを取得するアプリケーションは、そのメッセージに対して IDirectMusicPerformance8::FreePMsg を呼び出す責任がある。

戻り値

成功した場合は S_OK を返す。返される通知イベントが存在しない場合は S_FALSE を返す。

失敗した場合は E_POINTER を返す。

動作環境

ヘッダー : dmusici.h で宣言。

参照

通知とイベントの処理


IDirectMusicPerformance8::GetParam

制御セグメント内のトラックからデータを取得する。

HRESULT GetParam(
  REFGUID rguidType,
  DWORD dwGroupBits,
  DWORD dwIndex,
  MUSIC_TIME mtTime,
  MUSIC_TIME* pmtNext,
  void* pParam
);

パラメータ

rguidType
取得されるデータ型の識別子への参照 (C++) またはアドレス (C)。「標準トラック パラメータ」を参照すること。
dwGroupBits
データの取得に使われるトラックのグループ (「注意」を参照すること)。すべてのグループを指定するには、この値を 0xFFFFFFFF に設定する。
dwIndex
データの取得に使われるグループ内で、トラックに割り当てられているインデックス。
mtTime
データを取得するタイム。パフォーマンス時間で指定する。
pmtNext
データが有効になるタイム (mtTime からの相対タイム) を受け取る変数のアドレス。この変数が値 0 を返した場合、データが常に有効になっているか、データが無効になるタイムが不明であることを意味する。この情報が不要な場合は、pmtNext を NULL に設定してもよい。「注意」を参照すること。
pParam
返されるデータの保存用に割り当てられた構造体のアドレス。返されるデータの保存用に割り当てられた構造体のアドレス。この構造体は、rguidType で識別されたデータ型にとって適切な種類とサイズを備えていなければならない。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_GET_UNSUPPORTED
DMUS_E_NO_MASTER_CLOCK
DMUS_E_NOT_FOUND
DMUS_E_TRACK_NOT_FOUND
E_POINTER

注意

通常、プライマリ セグメントは制御セグメントである。ただし、セカンダリ セグメントを演奏するときは、これを制御セグメントとして指定できる。詳細については、「制御セグメント」を参照すること。

別の制御セグメントが挿入される場合、*pParam で返されるデータは、*pmtNext で返されるタイムの前に無効になることがある。

各トラックは 1 つまたは複数のグループに所属するが、各グループは dwGroupBits 内のビットによって表されている。詳細については、「IDirectMusicSegment8::InsertTrack」および「トラックの識別」を参照すること。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::SetParam、IDirectMusicSegment8::GetParam、IDirectMusicTrack8::GetParamEx、IDirectMusicPerformance8::SetGlobalParam、IDirectMusicPerformance8::GetTime、IDirectMusicPerformance8::GetParamEx、パフォーマンス パラメータ


IDirectMusicPerformance8::GetParamEx

トラックからデータを取得する。このメソッドは、IDirectMusicPerformance8::GetParam に類似しているが、自己制御セグメントのサポートを追加する。主にツールで使用される。

HRESULT GetParamEx(
  REFGUID rguidType,
  DWORD dwTrackID,
  DWORD dwGroupBits,
  DWORD dwIndex,
  MUSIC_TIME mtTime,
  MUSIC_TIME* pmtNext,
  void* pParam
);

パラメータ

rguidType
取得されるデータ型の識別子への参照 (C++) またはアドレス (C)。「標準トラック パラメータ」を参照すること。
dwTrackID
パラメータの取得に使われるセグメント状態内のトラックの一意な識別子。トラックから取得される各パフォーマンス メッセージには、メッセージを生成したトラック インスタンスの識別子が付いている。この識別子は、メッセージ構造体の DMUS_PMSG 部分の dwVirtualTrackID メンバに保持される。この値が GetParamEx に渡されると、制御セグメントではない同じセグメント内の別のトラックからデータを取得した場合に、このトラックが自己制御しているかどうかを判断できる。
dwGroupBits
トラックが属するグループ (「注意」を参照すること)。すべてのグループを指定するには、この値を 0xFFFFFFFF に設定する。
dwIndex
グループ内のトラックのインデックス。
mtTime
データを取得するタイム。パフォーマンス時間で指定する。
pmtNext
データが有効になるタイム (mtTime からの相対タイム) を受け取る変数のアドレス。この変数が値 0 を返した場合、データが常に有効になっているか、データが無効になるタイムが不明であることを意味する。この情報が不要な場合は、pmtNext を NULL に設定してもよい。「注意」を参照すること。
pParam
返されるデータの保存用に割り当てられた構造体のアドレス。返されるデータの保存用に割り当てられた構造体のアドレス。この構造体は、rguidType で識別されたデータ型にとって適切な種類とサイズを備えていなければならない。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_GET_UNSUPPORTED
DMUS_E_NO_MASTER_CLOCK
DMUS_E_NOT_FOUND
DMUS_E_TRACK_NOT_FOUND
E_POINTER

注意

各トラックは 1 つまたは複数のグループに所属するが、各グループは dwGroupBits 内のビットによって表されている。詳細については、「IDirectMusicSegment8::InsertTrack」および「トラックの識別」を参照すること。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::SetParam、IDirectMusicSegment8::GetParam、IDirectMusicTrack8::GetParamEx、IDirectMusicPerformance8::SetGlobalParam、IDirectMusicPerformance8::GetTime、パフォーマンス パラメータ


IDirectMusicPerformance8::GetPrepareTime

トラックによってメッセージが送信されてからサウンドが聞こえるまでの間隔を取得する。この間隔は、ツールがメッセージを処理するのに十分な時間でなければならない。

HRESULT GetPrepareTime(
  DWORD* pdwMilliSeconds
);

パラメータ

pdwMilliSeconds
準備時間を受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は E_POINTER を返す。

注意

デフォルトの値は 1,000ミリ秒 (ms) である。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::SetPrepareTime、準備時間


IDirectMusicPerformance8::GetQueueTime

現在のフラッシュ タイムを取得する。フラッシュ タイムとは、キュー内のメッセージをフラッシュ (解放) できる最も早いタイムである。このタイムより早いタイム スタンプを持つメッセージは、既にポートに送信されており、無効にすることができない。

HRESULT GetQueueTime(
  REFERENCE_TIME * prtTime
);

パラメータ

prtTime
現在のフラッシュ タイムを受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_POINTER
DMUS_E_NO_MASTER_CLOCK

動作環境

ヘッダー : dmusici.h で宣言。

参照

遅延時間とバンパー時間


IDirectMusicPerformance8::GetResolvedTime

指定されたタイムを、指定された境界に調整する。

HRESULT GetResolvedTime(
  REFERENCE_TIME rtTime,
  REFERENCE_TIME* prtResolved,
  DWORD dwTimeResolveFlags
);

パラメータ

rtTime
境界に調整すべきタイム。このタイムが現在タイムより早い場合は、現在タイムが使用される。
prtResolved
解決済みのタイムを受け取る変数のアドレス。
dwTimeResolveFlags
目的の分解能を記述する 1 つまたは複数の DMUS_TIME_RESOLVE_FLAGS。

戻り値

成功した場合は S_OK を返す。

失敗した場合は E_POINTER を返す。

動作環境

ヘッダー : dmusici.h で宣言。

参照

タイミング


IDirectMusicPerformance8::GetSegmentState

現在演奏中のプライマリ セグメント状態、または特定の時点で演奏されているプライマリ セグメント状態を取得する。

HRESULT GetSegmentState(
  IDirectMusicSegmentState ** ppSegmentState,
  MUSIC_TIME mtTime
);

パラメータ

ppSegmentState
セグメント状態へのポインタを受け取る変数のアドレス。呼び出し元は、このポインタに対して Release を呼び出す責任がある。
mtTime
セグメント状態が取得されるタイム。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_NOT_FOUND
E_POINTER

注意

現在演奏中のセグメント状態を取得するには、IDirectMusicPerformance8::GetTime メソッドが返すタイムを渡す。遅延時間が存在するため、必ずしも現在演奏されているセグメント状態が現在スピーカから実際に聞こえているとは限らない。

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicPerformance8::GetTime

パフォーマンスの現在のタイムを取得する。

HRESULT GetTime(
  REFERENCE_TIME* prtNow,
  MUSIC_TIME* pmtNow
);

パラメータ

prtNow
現在のタイムを REFERENCE_TIME フォーマットで受け取る変数のアドレス。NULL でもよい。
pmtNow
現在のタイムを MUSIC_TIME フォーマットで受け取る変数のアドレス。NULL でもよい。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_NO_MASTER_CLOCK
E_POINTER

動作環境

ヘッダー : dmusici.h で宣言。

参照

タイミング


IDirectMusicPerformance8::Init

パフォーマンスを DirectMusic オブジェクトと DirectSound オブジェクトに関連付ける。アプリケーションがオーディオパスを使用していない場合は、パフォーマンスの演奏前にこのメソッドを呼び出す必要がある。

オーディオパスを使用するアプリケーションについては、このメソッドに代えて IDirectMusicPerformance8::InitAudio が使用される。

HRESULT Init(
  IDirectMusic** ppDirectMusic,
  LPDIRECTSOUND pDirectSound,
  HWND hWnd
);

パラメータ

ppDirectMusic
DirectMusic オブジェクトへのインターフェイス ポインタを指定または受け取る変数のアドレス。

ppDirectMusic が指す変数に、有効な IDirectMusic または IDirectMusic8 インターフェイス ポインタが含まれている場合は、既存のオブジェクトがパフォーマンスに割り当てられる。このインターフェイスの参照カウントはインクリメントされる。IDirectMusicPerformance8::AddPort メソッドに渡されるポートは、この DirectMusic オブジェクトから作成する必要がある。

ppDirectMusic が指す変数に NULL が含まれる場合、DirectMusic オブジェクトが作成され、IDirectMusic インターフェイス ポインタが返される。QueryInterface を使用して IDirectMusic8 を取得する。

ppDirectMusic が NULL の場合、DirectMusic オブジェクトが作成され、パフォーマンスによって内部的に使用される。

「注意」を参照すること。

pDirectSound
ウェーブ出力のデフォルトで使用される IDirectSound8 インターフェイス ポインタ。この値が NULL の場合、DirectMusic によって DirectSound オブジェクトが作成される。ただし、DirectSound オブジェクトが存在できるのは 1 つのプロセスにつき 1 つだけである。アプリケーションで DirectSound を個別に使っている場合、そのインターフェイスを pDirectSound に渡さなければならない。アプリケーションが DirectMusic オブジェクトを明示的に作成する場合は、そのインターフェイスを IDirectMusic8::SetDirectSound に渡さなければならない。
hWnd
DirectSound の作成に使うウィンドウ ハンドル。このパラメータは NULL でもよい。その場合、前面ウィンドウが使用される。「注意」を参照すること。

pDirectSound が NULL の場合、このパラメータは無視される。その場合、IDirectSound8::SetCooperativeLevel の呼び出しにおいて、アプリケーションがウィンドウ ハンドルの設定を行わなければならない。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_ALREADY_INITED
E_OUTOFMEMORY
E_POINTER

注意

このメソッドは、一度だけ呼び出すことができる。既存の IDirectMusic8 インターフェイスの取得に使用することはできない。

DirectMusic オブジェクトは、以下の方法のいずれかを使って、パフォーマンスに関連付けることができる。

  • アプリケーションが独自の DirectMusic オブジェクトを作成し、IDirectMusic8 ポインタのアドレスを ppDirectMusic に渡すことによって、そのオブジェクトをパフォーマンスに提供する。この場合、アプリケーションが IDirectMusic8::SetDirectSound を呼び出す必要があるため、pDirectSound と hWnd の各パラメータは無視される。
  • アプリケーションがパフォーマンスによる DirectMusic オブジェクトの作成を許可し、そのオブジェクトへのポインタを必要とする。この場合、エントリ時の *ppDirectMusic は NULL で、終了時には IDirectMusic ポインタを保持する。
  • アプリケーションがパフォーマンスによるそれ自身の初期化を許可し、DirectMusic オブジェクト ポインタを必要としない。この場合、ppDirectMusic は NULL である。

パフォーマンスを解放する前に、IDirectMusicPerformance8::CloseDown メソッドを使用してパフォーマンスを終了しなければならない。

hWnd パラメータに NULL を渡すと、現在の前面ウィンドウのハンドルを DirectSound に渡すことができる。ただし、アプリケーション ウィンドウが初期化中に前面にあると想定しないこと。最上位アプリケーションのウィンドウ ハンドルを渡すことが最良である。

動作環境

ヘッダー : dmusici.h で宣言。

参照

ポートからオーディオパスへの移行


IDirectMusicPerformance8::InitAudio

パフォーマンスを初期化し、オプションでデフォルトのオーディオパスをセットアップする。このメソッドは、オーディオパスを使ってパフォーマンスを演奏する前に、呼び出す必要がある。

ほとんどの場合、IDirectMusicPerformance8::Init ではなく、このメソッドを使用することが望ましい。

HRESULT InitAudio(
  IDirectMusic** ppDirectMusic,
  IDirectSound** ppDirectSound,
  HWND hWnd,
  DWORD dwDefaultPathType,
  DWORD dwPChannelCount,
  DWORD dwFlags,
  DMUS_AUDIOPARAMS *pParams
);

パラメータ

ppDirectMusic
DirectMusic オブジェクトへのインターフェイス ポインタを指定または受け取る変数のアドレス。

ppDirectMusic が指す変数に、有効な IDirectMusic または IDirectMusic8 インターフェイス ポインタが含まれている場合は、既存のオブジェクトがパフォーマンスに割り当てられる。このインターフェイスの参照カウントはインクリメントされる。

ppDirectMusic が指す変数に NULL が含まれる場合、DirectMusic オブジェクトが作成され、IDirectMusic インターフェイス ポインタが返される。QueryInterface を使用して IDirectMusic8 を取得する。

ppDirectMusic が NULL の場合、DirectMusic オブジェクトが作成され、パフォーマンスによって内部的に使用される。

「注意」を参照すること。

ppDirectSound
ウェーブ出力のデフォルトで使用する DirectSound オブジェクトの、IDirectSound インターフェイス ポインタを指定または取得する変数のアドレス。このパラメータに NULL ポインタが含まれる場合、DirectMusic によって専用の DirectSound オブジェクトが作成される。示された変数に NULL が含まれる場合、DirectMusic オブジェクトが DirectSound オブジェクトを作成し、そのインターフェイス ポインタが返される。「注意」を参照すること。
hWnd
DirectSound の作成に使うウィンドウ ハンドル。このパラメータは NULL でもよい。その場合、前面ウィンドウが使用される。「注意」を参照すること。

IDirectSound インターフェイス ポインタが ppDirectSound のメソッドに渡される場合、このパラメータは無視される。その場合、アプリケーションは、IDirectSound8::SetCooperativeLevel を使ってウィンドウ ハンドルを設定する責任がある。

dwDefaultPathType
デフォルトのオーディオパス タイプを指定する DWORD 値。デフォルト パス タイプが不要な場合は、0 を指定する。定義された値のリストについては、「IDirectMusicPerformance8::CreateStandardAudioPath」を参照すること。
dwPChannelCount
dwDefaultPathType が 0 以外である場合、パスに割り当てるパフォーマンス チャンネル数を指定する値。
dwFlags
要求された機能を指定するフラグ。pParams が NULL 以外である場合、この値は無視され、要求された機能は、DMUS_AUDIOPARAMS 構造体の dwFeatures メンバに指定される。このパラメータで使用できる値として、次の値が定義されている。
DMUS_AUDIOF_3D
3D バッファ。
DMUS_AUDIOF_ALL
すべての機能。
DMUS_AUDIOF_BUFFERS
複数のバッファ。
DMUS_AUDIOF_ENVIRON
環境モデリング。
DMUS_AUDIOF_EAX
EAX エフェクト。
DMUS_AUDIOF_STREAMING
ストリーミング ウェーブのサポート。
pParams
シンセサイザのパラメータを指定し、どのパラメータが設定されたかについての情報を受け取る DMUS_AUDIOPARAMS 構造体のアドレス。デフォルトのパラメータを使用する場合は、NULL でもよい。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_ALREADY_INITED
DSERR_BUFFERLOST
DSERR_PRIOLEVELNEEDED
DSERR_UNINITIALIZED
E_NOINTERFACE
E_OUTOFMEMORY
E_POINTER

注意

このメソッドは、一度だけ呼び出すことができる。既存の IDirectMusic8 インターフェイスの取得に使用することはできない。

DirectMusic オブジェクトは、以下の方法で、パフォーマンスに関連付けることができる。

  • アプリケーションがパフォーマンスによる DirectMusic オブジェクトの作成を許可し、そのオブジェクトへのポインタを必要とする。この場合、*ppDirectMusic はエントリ時に NULL で、終了時には IDirectMusic8 ポインタを保持する。
  • アプリケーションがパフォーマンスによるそれ自身の初期化を許可し、DirectMusic オブジェクト ポインタを必要としない。この場合、ppDirectMusic は NULL である。
  • アプリケーションが独自の DirectMusic オブジェクトを作成し、IDirectMusic8 ポインタのアドレスを ppDirectMusic に渡すことによって、そのオブジェクトをパフォーマンスに提供する。ほとんどのアプリケーションでは、この手法は使用されない。

ppDirectSound で指定するインターフェイス ポインタは、CLSID_DirectSound8 クラスのオブジェクトへのインターフェイスを指していなければならない。このクラスのオブジェクトは、IDirectSound と IDirectSound8 の両方をサポートしているが、IDirectSound インターフェイスを渡す必要がある。このクラスのオブジェクトの作成方法については、「IDirectSound8」の「注意」を参照すること。DirectSound オブジェクトは、InitAudio に渡す前に完全に初期化する必要がある。それが CoCreateInstance を使って作成されたオブジェクトである場合は、IDirectSound8::Initialize を呼び出す。IDirectSound8::SetCooperativeLevel を使って、協調レベルを DSSCL_PRIORITY に設定する。

hWnd パラメータに NULL を渡すと、現在の前面ウィンドウのハンドルを DirectSound に渡すことができる。ただし、アプリケーション ウィンドウが初期化中に前面にあると想定しないこと。最上位アプリケーションのウィンドウ ハンドルを渡すことが最良である。

dwFlags および pParams に設定されたパラメータは、デフォルトのオーディオパス、およびその後作成されたすべてのオーディオパスに適用される。

dwDefaultPathType で 0 以外の値が渡された場合、何かのアプリケーションによって DirectSound が書き込み優先協調レベルで初期化されていると、このメソッドは失敗して DSERR_BUFFERLOST を返す。

パフォーマンスを解放する前に、IDirectMusicPerformance8::CloseDown メソッドを使用してパフォーマンスを終了しなければならない。

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicPerformance8::Invalidate

指定されたタイムから前方に向かってキュー内のすべてのメッセージをフラッシュ (解放) し、指定されたタイムから前方に向かってすべてのセグメントがデータを再送するようすべてのトラックに通知する。

HRESULT Invalidate(
  MUSIC_TIME mtTime,
  DWORD dwFlags
);

パラメータ

mtTime
無効にするタイム。dwFlags によって調整を加えられる。この値を 0 に設定すると、即座に無効になる。
dwFlags
mtTime を調整して小節、拍、またはグリッドに揃えるフラグ。この値は、0 または次に示す DMUS_SEGF_FLAGS 列挙型のメンバのいずれかである。

DMUS_SEGF_MEASURE
DMUS_SEGF_BEAT
DMUS_SEGF_GRID

戻り値

成功した場合は S_OK を返す。

失敗した場合は DMUS_E_NO_MASTER_CLOCK を返す。

注意

mtTime がかなり前のタイムで、そのタイムで無効にできない場合は、利用可能な範囲で最も早いタイムを使う。

動作環境

ヘッダー : dmusici.h で宣言。

参照

準備時間、セグメントのタイミング


IDirectMusicPerformance8::IsPlaying

特定のセグメントまたはセグメント状態がスピーカから聞こえているかどうかを判別する。

HRESULT IsPlaying(
  IDirectMusicSegment* pSegment,
  IDirectMusicSegmentState* pSegState
);

パラメータ

pSegment
チェックされるセグメント。NULL の場合、pSegState だけをチェックする。
pSegState
チェックされるセグメント状態。NULL の場合、pSegment だけをチェックする。

戻り値

このメソッドが成功し、要求したセグメントとセグメント状態のどちらかが演奏されている場合は S_OK を返す。どちらも演奏されていない場合、またはどちらか 1 つだけを要求し、それが演奏されていない場合は、S_FALSE を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_POINTER
DMUS_E_NO_MASTER_CLOCK

注意

セグメントまたはセグメント状態が実際にスピーカで演奏中である場合にのみ、S_OK が返される。IDirectMusicPerformance8::PlaySegment や IDirectMusicPerformance8::PlaySegmentEx がセグメントに対して呼び出された直後でも、遅延時間があるので、S_FALSE が返される可能性がある。同様の理由で、すべてのメッセージが既に発信されている場合でも、セグメントが聞こえている間は、S_OK が返される。

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicPerformance8::MIDIToMusic

提供されるコード、サブコード レベル、および演奏モードを使って、MIDI ノートの値を DirectMusic ミュージック値に変換する。

HRESULT MIDIToMusic(
  BYTE bMIDIValue,
  DMUS_CHORD_KEY* pChord,
  BYTE bPlayMode,
  BYTE bChordLevel,
  WORD *pwMusicValue
);

パラメータ

bMIDIValue
変換する MIDI ノートの値。0 ～ 127 の範囲で指定する。
pChord
ノートの変換で使用されるコードとキーの構造に関する情報を含む DMUS_CHORD_KEY 構造体のアドレス。これには、ベース コードのスケールも含まれる。たとえば、コードが CM7 の場合、ノートはルート音 C、メジャー 7 度のコード音程に照らして解釈される。この構造体は、DMUS_MAXSUBCHORD 平行サブコードを、それぞれのコード音程、ルート音、スケール、および転回フラグと共に保持する。また、全体的なキーのルート音も保持する。
bPlayMode
ミュージック値がコードからどのように派生するかを決定する演奏モード。値のリストについては、「DMUS_PLAYMODE_FLAGS」を参照すること。
bChordLevel
使用できるサブコードを定義するサブコード レベル。「DMUS_SUBCHORD」を参照すること。
pwMusicValue
ミュージック値を受け取る変数のアドレス。この値の詳細については、「DMUS_NOTE_PMSG」を参照すること。

戻り値

成功した場合は、次のいずれかの値を返す。「注意」を参照すること。

S_OK
DMUS_S_DOWN_OCTAVE
DMUS_S_UP_OCTAVE

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_CANNOT_CONVERT
E_INVALIDARG

注意

メソッドが失敗した場合、*pwMusicValue は変更されない。

戻り値が DMUS_S_UP_OCTAVE または DMUS_DOWN_OCTAVE の場合、ノート変換では 0 未満または 128 以上のノートの値が生成されるため、0 ～ 127 の適切な MIDI 範囲に収まるように、1 または複数オクターブ分だけ上または下に移動される。これは、演奏モード DMUS_PLAYMODE_FIXEDTOCHORD および DMUS_PLAYMODE_FIXEDTOKEY を使うときに発生することがある。どちらも、MIDI 値を *pwMusicValue に返す。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::MusicToMIDI、ミュージック値と MIDI ノート


IDirectMusicPerformance8::MusicToMIDI

DirectMusic ミュージック値を MIDI ノートの値に変換する。

HRESULT MusicToMIDI(
  WORD wMusicValue,
  DMUS_CHORD_KEY* pChord,
  BYTE bPlayMode,
  BYTE bChordLevel,
  BYTE *pbMIDIValue
);

パラメータ

wMusicValue
変換するミュージック値。ミュージック値については、「DMUS_NOTE_PMSG」を参照すること。
pChord
ノートの変換で使用されるコードとキーの構造に関する情報を含む DMUS_CHORD_KEY 構造体のアドレス。これには、ベース コードのスケールも含まれる。たとえば、コードが CM7 の場合、ノートはルート音 C、メジャー 7 度のコード音程に照らして解釈される。この構造体は、DMUS_MAXSUBCHORD 平行サブコードを、それぞれのコード音程、ルート音、スケール、および転回フラグと共に保持する。また、全体的なキーのルート音も保持する。
bPlayMode
ミュージック値がコードにどのように関連するかを決定する演奏モード。値のリストについては、「DMUS_PLAYMODE_FLAGS」を参照すること。
bChordLevel
使用できるサブコードを定義するサブコード レベル。「DMUS_SUBCHORD」を参照すること。
pbMIDIValue
MIDI 値を受け取る変数のアドレス。0 ～ 127 の範囲で指定する。

戻り値

成功した場合は、次のいずれかの値を返す。「注意」を参照すること。

S_OK
DMUS_S_OVER_CHORD
DMUS_S_DOWN_OCTAVE
DMUS_S_UP_OCTAVE

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_CANNOT_CONVERT
E_INVALIDARG

注意

メソッドが失敗した場合または DMUS_S_OVER_CHORD を返す場合、*pwMIDIValue は変更されない。

ミュージック値がコードの最高音より高い位置にあるノートを持っているため、ノートが計算されない場合は、DMUS_S_OVER_CHORD を返す。これは、DMUS_PLAYMODE_NORMALCHORD 演奏モードだけに適用される。アプリケーションはノートに対して何の処理もしてはならない。ノートはこのコードに対して演奏されるものではない。

戻り値が DMUS_S_UP_OCTAVE または DMUS_DOWN_OCTAVE の場合、ノート変換では 0 未満または 128 以上のノートの値が生成されるため、0 ～ 127 の適切な MIDI 範囲に収まるように、1 または複数オクターブ分だけ上または下に移動される。これは、DMUS_PLAYMODE_FIXED 以外の演奏モードを使うときに発生することがある。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::MIDIToMusic、ミュージック値と MIDI ノート


IDirectMusicPerformance8::MusicToReferenceTime

MUSIC_TIME フォーマットのパフォーマンス タイムを REFERENCE_TIME フォーマットに変換する。

HRESULT MusicToReferenceTime(
  MUSIC_TIME mtTime,
  REFERENCE_TIME* prtTime
);

パラメータ

mtTime
変換される、MUSIC_TIME フォーマットの時間。
prtTime
REFERENCE_TIME フォーマットに変換された時間を受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_POINTER
DMUS_E_NO_MASTER_CLOCK

注意

基準タイムはミュージック タイムよりも正確であるため、基準タイムからミュージック タイムに変換し、また基準タイムに変換したタイムは、おそらく元の値とは異なる。

このメソッドは、パフォーマンスの時間ではなく、パフォーマンスの開始からのタイムのオフセットを変換する。ミュージック タイムと基準タイムの単位の比率は、テンポにより異なるので、prtTime を計算する際に、DirectMusic はパフォーマンス開始以降のあらゆるテンポの変更を考慮する。パフォーマンスについてマスタ テンポが設定されている場合は、同様に考慮される。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::ReferenceToMusicTime、クロック タイムとミュージック タイム


IDirectMusicPerformance8::PChannelInfo

指定されたパフォーマンス チャンネルのポート、グループ、および MIDI チャンネルを取得する。

HRESULT PChannelInfo(
  DWORD dwPChannel,
  IDirectMusicPort** ppPort,
  DWORD* pdwGroup,
  DWORD* pdwMChannel
);

パラメータ

dwPChannel
情報が必要とされるパフォーマンス チャンネル。
ppPort
IDirectMusicPort8 ポインタを受け取る変数のアドレス。ポインタが不要な場合は、NULL でもよい。NULL 以外のポインタが返される場合、参照カウントはインクリメントされる。ポインタに対して Release を呼び出すのはアプリケーションである。「注意」も参照すること。
pdwGroup
ポート上のグループへのポインタを受け取る変数のアドレス。この値が不要な場合は、NULL でもよい。
pdwMChannel
グループ内の MIDI チャンネルへのポインタを受け取る変数のアドレス。この値が不要な場合は、NULL でもよい。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_INVALIDARG
E_POINTER

注意

IDirectMusicPerformance8::RemovePort の呼び出しによってポートが削除された場合、*ppPort には NULL ポインタが返されるが、メソッドは成功する。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::AssignPChannel、IDirectMusicPerformance8::AssignPChannelBlock


IDirectMusicPerformance8::PlaySegment

セグメントの再生を開始する。

HRESULT PlaySegment(
  IDirectMusicSegment* pSegment,
  DWORD dwFlags,
  __int64 i64StartTime,
  IDirectMusicSegmentState** ppSegmentState
);

パラメータ

pSegment
演奏されるセグメント。
dwFlags
メソッドの動作を変更するフラグ。「DMUS_SEGF_FLAGS」を参照すること。
i64StartTime
セグメントの演奏を開始するパフォーマンス タイム。dwFlags で指定される任意の境界分解能に調整される。DMUS_SEGF_REFTIME フラグが設定されていない限り、タイムはミュージック タイムで表される。値が 0 の場合、セグメントの演奏はできる限り早く開始される。
ppSegmentState
演奏中のセグメントのインスタンスに関するセグメント状態へのポインタを受け取る変数のアドレス。このフィールドは NULL でもよい。NULL ではない場合、セグメント状態ポインタが返され、アプリケーションはこのポインタに対して Release を呼び出さなければならない。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_OUTOFMEMORY
E_POINTER
DMUS_E_NO_MASTER_CLOCK
DMUS_E_SEGMENT_INIT_FAILED
DMUS_E_TIME_PAST

注意

セグメントの長さは 250 ミリ秒 (ms) を超えている必要がある。

dwFlags の境界分解能は、プライマリ セグメントに関連するものである。

プライマリ セグメントの演奏が、別のプライマリ セグメントの演奏中にスケジュール設定されている場合、後に演奏されるセグメントに DMUS_SEGF_QUEUE フラグを設定しない限り、最初のセグメントは停止する。後に演奏されるセグメントに DMUS_SEGF_QUEUE フラグを設定した場合、そのセグメントは、最初のセグメントの演奏が終わると同時に演奏が開始される。

セグメントの正確な開始タイムの詳細については、「セグメントのタイミング」を参照すること。テンポの変更がセグメントの開始タイムに及ぼす影響については、「クロック タイムとミュージック タイム」を参照すること。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::PlaySegmentEx


IDirectMusicPerformance8::PlaySegmentEx

セグメントの再生を開始する。このメソッドは、IDirectMusicPerformance8::PlaySegment よりも高い機能を提供する。

HRESULT PlaySegmentEx(
  IUnknown* pSource,
  WCHAR *pwzSegmentName,
  IUnknown* pTransition,
  DWORD dwFlags,
  __int64 i64StartTime,
  IDirectMusicSegmentState** ppSegmentState,
  IUnknown* pFrom,
  IUnknown* pAudioPath
);

パラメータ

pSource
再生するオブジェクトの IUnknown インターフェイスのアドレス。
pwzSegmentName
DirectX 8.0 では実装されていない。NULL に設定すること。
pTransition
テンプレート セグメントのトランジションをアレンジする際に使用する、テンプレート セグメントの IUnknown インターフェイス ポインタ。NULL でもよい。「注意」を参照すること。
dwFlags
メソッドの動作を変更するフラグ。「DMUS_SEGF_FLAGS」を参照すること。
i64StartTime
セグメントの演奏を開始するパフォーマンス タイム。dwFlags で指定される任意の境界分解能に調整される。DMUS_SEGF_REFTIME フラグが設定されていない限り、タイムはミュージック タイムで表される。値が 0 の場合、セグメントの演奏はできる限り早く開始される。
ppSegmentState
演奏中セグメントのこのインスタンスを表す、IDirectMusicSegmentState インターフェイス ポインタを受け取る変数のアドレス。IDirectMusicSegmentState8 を取得するには、QueryInterface を使用する。このインターフェイスの参照カウントはインクリメントされる。セグメント状態ポインタを必要としない場合は、このパラメータを NULL にする。
pFrom
新しいセグメントの演奏を開始するときに停止するセグメント状態またはオーディオパスを指す IUnknown インターフェイス ポインタ。オーディオパスを指す場合は、そのオーディオパスで演奏中のすべてのセグメント状態が停止される。この値は NULL でもよい。
pAudioPath
再生に使うオーディオパスを表すオブジェクトの IUnknown インターフェイス ポインタ。デフォルト パスで演奏する場合は、NULL。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_AUDIOPATH_INACTIVE
DMUS_E_AUDIOPATH_NOPORT
DMUS_E_NO_MASTER_CLOCK
DMUS_E_SEGMENT_INIT_FAILED
DMUS_E_TIME_PAST
E_OUTOFMEMORY
E_POINTER

注意

セグメントの長さは 250 ミリ秒 (ms) を超えている必要がある。

dwFlags の境界分解能は、プライマリ セグメントに関連するものである。

プライマリ セグメントの演奏が、別のプライマリ セグメントの演奏中にスケジュール設定されている場合、後に演奏されるセグメントに DMUS_SEGF_QUEUE フラグを設定しない限り、最初のセグメントは停止する。後に演奏されるセグメントに DMUS_SEGF_QUEUE フラグを設定した場合、そのセグメントは、最初のセグメントの演奏が終わると同時に演奏が開始される。

セグメントの正確な開始タイムの詳細については、「セグメントのタイミング」を参照すること。テンポの変更がセグメントの開始タイムに及ぼす影響については、「クロック タイムとミュージック タイム」を参照すること。

dwFlags に DMUS_SEGF_AUTOTRANSITION が指定されているときに、i64StartTime で既に演奏中のセグメントを中断する場合、このメソッドは、2 つのセグメント間のトランジションをアレンジして、それを演奏した後に pSource を演奏する。トランジションは、pTransition で提供されるテンプレートに基づく。

このメソッドを使って、オーディオパスを使用しないパフォーマンス、つまり IDirectMusicPerformance8::Init を使って初期化されたパフォーマンスで演奏できる。この場合、pAudioPath パラメータは NULL でなければならない。

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicPerformance8::ReferenceToMusicTime

REFERENCE_TIME フォーマットのパフォーマンス タイムを MUSIC_TIME フォーマットに変換する。

HRESULT ReferenceToMusicTime(
  REFERENCE_TIME rtTime,
  MUSIC_TIME* pmtTime
);

パラメータ

rtTime
REFERENCE_TIME フォーマットの時間。
pmtTime
MUSIC_TIME フォーマットに変換された時間を受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_POINTER
DMUS_E_NO_MASTER_CLOCK

注意

ミュージック タイムは基準タイムほど正確ではないため、切り捨てが行われる。

このメソッドは、パフォーマンスの時間ではなく、パフォーマンスの開始からのタイムのオフセットを変換する。ミュージック タイムと基準タイムの単位の比率は、テンポにより異なるので、prtTime を計算する際に、DirectMusic はパフォーマンス開始以降のあらゆるテンポの変更を考慮する。パフォーマンスについてマスタ テンポが設定されている場合は、同様に考慮される。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::MusicToReferenceTime、クロック タイムとミュージック タイム


IDirectMusicPerformance8::RemoveNotificationType

以前に追加された通知タイプをパフォーマンスから削除する。RemoveNotificationType メソッドを呼び出すと、すべてのセグメントとトラックは更新される。

HRESULT RemoveNotificationType(
  REFGUID rguidNotificationType
);

パラメータ

rguidNotificationType
削除される通知タイプの識別子への参照 (C++) またはアドレス (C)。(定義済みのタイプについては、「DMUS_NOTIFICATION_PMSG」を参照すること)。この値が GUID_NULL の場合、すべての通知が削除される。

戻り値

成功した場合は S_OK または S_FALSE を返す (「注意」を参照すること)。

失敗した場合は E_POINTER を返す。

注意

rguidNotificationType がアクティブな通知ではない場合、S_FALSE が返される。

演奏を停止したセグメントに通知を追加した場合、セグメントへの参照が失われることにより、パフォーマンスはそのセグメントから通知タイプを削除できなくなる。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::AddNotificationType、IDirectMusicSegment8::RemoveNotificationType、IDirectMusicTrack8::RemoveNotificationType、通知とイベントの処理


IDirectMusicPerformance8::RemovePort

パフォーマンスからポートを削除する。このポートにマップされていたすべてのパフォーマンス チャンネルは無効になり、そのスタンプの付いたメッセージが演奏されることもない。

HRESULT RemovePort(
  IDirectMusicPort* pPort
);

パラメータ

pPort
削除されるポート。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_INVALIDARG
E_POINTER

注意

IDirectMusicPerformance8::AddPort に NULL を渡して追加されたポートは、RemovePort に NULL を渡して削除することはできない。

このメソッドは、オーディオパスを使用するアプリケーションで呼び出すことはできない。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::AddPort


IDirectMusicPerformance8::RhythmToTime

リズム タイムをミュージック タイムに変換する。

HRESULT RhythmToTime(
  WORD wMeasure,
  BYTE bBeat,
  BYTE bGrid,
  short nOffset,
  DMUS_TIMESIGNATURE *pTimeSig,
  MUSIC_TIME *pmtTime
);

パラメータ

wMeasure
変換されるタイムの小節。
bBeat
変換されるタイムの拍。
bGrid
変換されるタイムのグリッド。
nOffset
変換されるタイムのグリッドからのオフセット。ミュージック タイムのティックで表す。
pTimeSig
拍子記号に関する情報を含む DMUS_TIMESIGNATURE 構造体のアドレス。
pmtTime
ミュージック タイムを受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は E_POINTER を返す。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::TimeToRhythm


IDirectMusicPerformance8::SendPMsg

パフォーマンス メッセージを送信する。このメソッドは、トラックの演奏時に呼び出される。ツールによって呼び出され、新しいデータをパフォーマンスに挿入する場合もある。

HRESULT SendPMsg(
  DMUS_PMSG* pPMSG
);

パラメータ

pPMSG
IDirectMusicPerformance8::AllocPMsg によって割り当てられたメッセージ。この構造体は、DMUS_PMSG の派生タイプである。「DirectMusic メッセージ」を参照すること。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_NO_MASTER_CLOCK
DMUS_E_ALREADY_SENT
E_INVALIDARG
E_POINTER

注意

タイム スタンプが rtTime と mtTime のどちらになっているかに応じて、dwFlags メンバ (「DMUS_PMSG」を参照) は DMUS_PMSGF_MUSICTIME と DMUS_PMSGF_REFTIME のどちらかを含んでいなければならない。また、メッセージのタイプに応じて、dwFlags は DMUS_PMSGF_TOOL_QUEUE、DMUS_PMSGF_TOOL_ATTIME、または DMUS_PMSGF_TOOL_IMMEDIATE いずれかの適切な配信タイプを含んでいなければならない。どれも指定しない場合、デフォルトとして DMUS_PMSGF_TOOL_IMMEDIATE が使われる。

メッセージのタイムが 0 に設定され、dwFlags メンバが DMUS_PMSGF_REFTIME を含んでいる場合、このメッセージは即座に送り出すものとしてキューに挿入される。

ほとんどの場合は、SendPMsg を呼び出す前に IDirectMusicGraph8::StampPMsg メソッドをメッセージに対して呼び出すべきである。ただし、メッセージをメインの出力ツールへ直接送信する場合は、このステップを省略してもよい。パフォーマンス グラフからのみメッセージを渡す場合は、IDirectMusicPerformance8::QueryInterface を呼び出すことで、IDirectMusicGraph8 インターフェイスを取得する。それ以外の場合は、IDirectMusicSegment8::QueryInterface を呼び出すことによって、このインターフェイスを取得する。IDirectMusicPerformance8::GetGraph や IDirectMusicSegment8::GetGraph を呼び出すことで、インターフェイスを取得しようとしてはならない。これらのメソッドが返すのは、グラフ オブジェクトへのポインタであり、パフォーマンスやセグメントの IDirectMusicGraph8 インターフェイスの実装へのポインタではない。

パフォーマンスは通常、処理の終わったメッセージを解放する。詳細については、IDirectMusicPerformance8::FreePMsg の「注意」を参照すること。

次のサンプル コードは、システム エクスクルーシブ メッセージとテンポ メッセージの割り当て方法と送信方法を示している。

// pPerformance は有効な IDirectMusicPerformance8 ポインタであり、
mtTime は初期化済みの変数 MUSIC_TIME
// であると仮定する。

IDirectMusicGraph* pGraph;

// パフォーマンスからグラフ ポインタを取得する。セグメント グラフを使って
// メッセージを渡す場合は、セグメント オブジェクトの代わりに
// QueryInterface を使用する。

if ( SUCCEEDED( pPerformance->QueryInterface(
        IID_IDirectMusicGraph, (void**)&pGraph )))
{
    // 適切なサイズの DMUS_SYSEX_PMSG を割り当て、
    // システム エクスクルーシブ データをそれに読み込ませる。

    DMUS_SYSEX_PMSG* pSysEx;

    if ( SUCCEEDED( pPerformance->AllocPMsg(
            sizeof(DMUS_SYSEX_PMSG) + m_dwSysExLength,
            (DMUS_PMSG**)&pSysEx )))
    {
        ZeroMemory(pSysEx, sizeof(DMUS_NOTE_PMSG));
        pSysEx->dwSize = sizeof(DMUS_SYSEX_PMSG);
        pSysEx->dwLen = dwSysExLength;
        pSysEx->mtTime = mtTime;
        pSysEx->dwFlags = DMUS_PMSGF_MUSICTIME;
        pSysEx->dwType = DMUS_PMSGT_SYSEX;

        // m_pbSysExData は、長さが m_dwSysExLength のデータを保持する
        // 配列へのポインタであると仮定する。

        memcpy( pSysEx->abData, m_pbSysExData, m_dwSysExLength );

        pGraph->StampPMsg( (DMUS_PMSG*)pSysEx );
        if (FAILED(pPerformance->SendPMsg( (DMUS_PMSG*)pSysEx )))
        {
            pPerformance->FreePMsg( (DMUS_PMSG*)pSysEx );
        }
    }

    // タイム mtTime のテンポを 120 bpm に変更する。

    DMUS_TEMPO_PMSG* pTempo;

    if( SUCCEEDED( pPerformance->AllocPMsg(
            sizeof(DMUS_TEMPO_PMSG),
            (DMUS_PMSG**)&pTempo )))
    {
        pTempo->dwSize = sizeof(DMUS_TEMPO_PMSG);
        pTempo->dblTempo = 120;
        pTempo->mtTime = mtTime;
        pTempo->dwFlags = DMUS_PMSGF_MUSICTIME;
        pTempo->dwType = DMUS_PMSGT_TEMPO;
        pGraph->StampPMsg( (DMUS_PMSG*)pTempo );
        if (FAILED(pPerformance->SendPMsg( (DMUS_PMSG*)pTempo )))
        {
            pPerformance->FreePMsg( (DMUS_PMSG*)pTempo );
        }
    }

    pGraph->Release();
}

次のサンプル コードは、dwTrackID によって識別されるトラックに関連付けられたノートメッセージを送信する関数を示す。メッセージが DirectMusicTrack オブジェクトから生成されていない場合、仮想トラック ID は 0 でなければならない。

HRESULT CreateNotePMsg(IDirectMusicPerformance8* pPerformance,
        MUSIC_TIME mtTime, DWORD dwTrackID)
{

    // Note PMessage を割り当てる。
    DMUS_NOTE_PMSG* pNote = NULL;
    HRESULT hr = pPerformance->AllocPMsg( sizeof(DMUS_NOTE_PMSG),
            (DMUS_PMSG**) &pNote);
    if (FAILED(hr)) return hr;

    pNote->dwSize = sizeof(DMUS_NOTE_PMSG); // Note Pmessage のサイズ。
    pNote->rtTime = 0;                      // 無視される。
    pNote->mtTime = mtTime;                 // ノートの演奏タイム。
    pNote->dwFlags = DMUS_PMSGF_MUSICTIME;  // mtTime フィールドを使う。
    pNote->dwPChannel = 5;                  // PChannel 5 で演奏する。
    pNote->dwVirtualTrackID = dwTrackID;    // パラメータからのトラック ID。

    // 次の 2 つのフィールドは、メッセージを初めて送信するときに、
    // NULL に設定しなければならない。これらのフィールドは、
    // IDirectMusicGraph::StampPMsg で更新される。
    pNote->pTool = NULL;
    pNote->pGraph = NULL;
    pNote->dwType = DMUS_PMSGT_NOTE;
    pNote->dwVoiceID = 0;           // 常に 0。
    pNote->dwGroupID = 0xFFFFFFFF;  // すべてのトラック グループ。
    pNote->punkUser = NULL;         // 常に NULL。

    // 現在の拍子記号をパフォーマンスから取得し、
    // 小節と拍の情報を計算する。
    DMUS_TIMESIGNATURE TimeSig;
    MUSIC_TIME mtNext;
    hr = pPerformance->GetParam(GUID_TimeSignature, 0xFFFFFFFF,
            0, mtTime, &mtNext, &TimeSig);
    if (FAILED(hr)) return hr;

    // TimeSig.mtTime を再計算し、
    // pPerformance->TimeToRhythm が予期する値を取得する。
    TimeSig.mtTime += mtTime;

    // 現在のコードをパフォーマンスから取得し、
    // ノートの値を作成する。
    DMUS_CHORD_KEY Chord;
    hr = pPerformance->GetParam(GUID_ChordParam, 0xFFFFFFFF, 0,
            mtTime, &mtNext, &Chord);
    if (FAILED(hr)) return hr;

    // オクターブ 5、コード音 2 (5 度)、スケールを持つノートを作成する。
    // オフセット 1 (=> 6 度)、変化音なし。
    WORD wMusicValue = 0x5210;

    // DMUS_PLAYMODE_PEDALPOINT を
    // pPerformance->MusicToMIDI での演奏モードとして使う。
    BYTE bPlayModeFlags = DMUS_PLAYMODE_PEDALPOINT;

    // DMUS_NOTE_PMSG に固有なフィールドを入力する。
    pNote->wMusicValue = wMusicValue;
    hr = pPerformance->MusicToMIDI(
        wMusicValue,
        &Chord,
        bPlayModeFlags,
        0,
        &(pNote->bMidiValue));
    if (FAILED(hr)) return hr;

    hr = pPerformance->TimeToRhythm(
        TimeSig.mtTime,
        &TimeSig,
        &(pNote->wMeasure),
        &(pNote->bBeat),
        &(pNote->bGrid),
        &(pNote->nOffset));
    if (FAILED(hr)) return hr;

    pNote->mtDuration = DMUS_PPQ;       // 4 分音符の持続時間。
    pNote->bVelocity = 120;             // MIDI のベロシティ (0 ～ 127)。
    pNote->bFlags = DMUS_NOTEF_NOTEON;  // 常にこの値に設定する。
    pNote->bTimeRange = 250;            // 開始タイムを大幅にランダム化する。
    pNote->bDurRange = 5;               // 持続時間をわずかにランダム化する。
    pNote->bVelRange = 0;               // ベロシティはランダム化しない。
    pNote->bPlayModeFlags = bPlayModeFlags;
    pNote->bSubChordLevel = 0;          // ノートはサブコード レベル 0 を使う。
    pNote->cTranspose = 0;              // 転調はない。

    // メッセージにパフォーマンス グラフのスタンプを付ける。
    IDirectMusicGraph* pGraph;
    hr = pPerformance->QueryInterface( IID_IDirectMusicGraph,
            (void**)&pGraph );
    if (FAILED(hr)) return hr;

    pGraph->StampPMsg( (DMUS_PMSG*)pNote );
    pGraph->Release();

    // 最後にメッセージを送信する。
    hr = pPerformance->SendPMsg( (DMUS_PMSG*)pNote);
    if (FAILED(hr))
    {
        pPerformance->FreePMsg( (DMUS_PMSG*)pNote);
        return hr;
    }
    return S_OK;
}

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicTool8::ProcessPMsg、メッセージ、DirectMusic メッセージ、DirectMusic ツール


IDirectMusicPerformance8::SetBumperLength

レンダリングの目的でメッセージをポートに送信する場合に、ポートの遅延時間より前に置かれる緩衝時間 (バンパー時間) を設定する。このトピックの概要については、「タイミング」を参照すること。

HRESULT SetBumperLength(
  DWORD dwMilliSeconds
);

パラメータ

dwMilliSeconds
演奏前の時間の長さ (ミリ秒単位)。デフォルト値は 50 である。

戻り値

S_OK を返す。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::GetBumperLength、IDirectMusicPerformance8::SetPrepareTime


IDirectMusicPerformance8::SetDefaultAudioPath

パフォーマンスにデフォルト オーディオパスを設定してアクティブにする。

HRESULT SetDefaultAudioPath(
  IDirectMusicAudioPath *pAudioPath
);

パラメータ

pAudioPath
デフォルトのオーディオパスの IDirectMusicAudioPath8 インターフェイスへのポインタ。現在のデフォルトのオーディオパスを削除するには、NULL を指定する。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_AUDIOPATH_NOPORT
DMUS_E_AUDIOPATHS_NOT_VALID
DMUS_E_NOT_INIT
E_INVALIDARG
E_POINTER

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::GetDefaultAudioPath、IDirectMusicPerformance8::InitAudio


IDirectMusicPerformance8::SetGlobalParam

パフォーマンスのグローバル値を設定する。

HRESULT SetGlobalParam(
  REFGUID rguidType,
  void* pParam,
  DWORD dwSize
);

パラメータ

rguidType
データ型の識別子への参照 (C++) またはアドレス (C)。
pParam
パフォーマンスへのコピーと保存が行われるデータのアドレス。
dwSize
データのサイズ。rguidType ごとに一定の値である。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_FAIL
E_POINTER
E_OUTOFMEMORY

注意

パフォーマンスはすべてのデータ型を把握しているわけではないので、dwSize パラメータは必要である。必要に応じて、新しいタイプも作成できる。

DirectMusic によって定義されるパラメータ、およびそれらに関連のあるデータ型については、「グローバル パラメータの設定と取得」を参照すること。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::GetGlobalParam、IDirectMusicPerformance8::SetParam、パフォーマンス パラメータ


IDirectMusicPerformance8::SetGraph

パフォーマンスのツールグラフを置き換える。

HRESULT SetGraph(
  IDirectMusicGraph* pGraph
);

パラメータ

pGraph
設定するツールグラフ。パフォーマンスからグラフを消去するために、NULL にも設定できる。

戻り値

成功した場合は S_OK を返す。

失敗した場合は E_POINTER を返す。

注意

現在のツールグラフ内で処理中のメッセージはすべて削除される。

このメソッドはグラフの参照カウントをインクリメントするので、オリジナルの参照を解放しておくと安全である。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegment8::SetGraph、IDirectMusicPerformance8::GetGraph、IDirectMusicPerformance8::SendPMsg


IDirectMusicPerformance8::SetNotificationHandle

通知用のイベント ハンドル (Microsoft® Win32® の CreateEvent 関数によって作成される) を設定する。アプリケーションは、このハンドルに対して Win32 WaitForSingleObject 関数を適用すべきである。シグナルが送信されたときに、アプリケーションは IDirectMusicPerformance8::GetNotificationPMsg メソッドを呼び出して、通知イベントを取得すべきである。

HRESULT SetNotificationHandle(
  HANDLE hNotification,
  REFERENCE_TIME rtMinimum
);

パラメータ

hNotification
CreateEvent によって作成されたイベント ハンドル。既存のハンドルを消去する場合は、0 を指定する。
rtMinimum
パフォーマンスが古い通知イベントを破棄するまでに保持しておく最小の時間。値として 0 を指定すると、デフォルトの最小値である 20,000,000 基準タイム単位 (2 秒)、または以前にこのメソッドを呼び出したときの値を意味する。アプリケーションがまだ GetNotificationPMsg を呼び出していない場合は、このイベントは破棄されて、メモリが解放される。

戻り値

S_OK を返す。

注意

通知ハンドルが不要になった場合は、アプリケーションが通知ハンドルに対して Win32 CloseHandle 関数を呼び出さなければならない。

動作環境

ヘッダー : dmusici.h で宣言。

参照

通知とイベントの処理


IDirectMusicPerformance8::SetParam

制御セグメントのトラックにデータを設定する。

HRESULT SetParam(
  REFGUID rguidType,
  DWORD dwGroupBits,
  DWORD dwIndex,
  MUSIC_TIME mtTime,
  void* pParam
);

パラメータ

rguidType
設定されるデータ型の識別子への参照 (C++) またはアドレス (C)。「標準トラック パラメータ」を参照すること。
dwGroupBits
希望のトラックが置かれるグループ。
dwIndex
データをどこに設定するかを示す、dwGroupBits で識別されるグループ内のトラックのインデックス。パラメータを格納するグループ内のすべてのトラックにパラメータを設定するには、DMUS_SEG_ALLTRACKS を指定する。
mtTime
データの設定を行うタイム。IDirectMusicSegment8::SetParam とは異なり、このタイムはパフォーマンス タイムである。このタイムからセグメントの開始タイムを引き、その結果を IDirectMusicSegment8::SetParam に渡す。
pParam
データを保持する構造体のアドレス。この構造体は、rguidType で識別されたデータ型にとって適切な種類とサイズを備えていなければならない。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_NO_MASTER_CLOCK
DMUS_E_SET_UNSUPPORTED
DMUS_E_TRACK_NOT_FOUND
E_POINTER

注意

通常、プライマリ セグメントは制御セグメントである。ただし、セカンダリ セグメントを演奏するときは、これを制御セグメントとして指定できる。「DMUS_SEGF_FLAGS」を参照すること。

dwGroupBits と dwIndex の説明については、「トラックの識別」を参照すること。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::GetParam、IDirectMusicPerformance8::SetGlobalParam、IDirectMusicSegment8::SetParam、IDirectMusicTrack8::SetParamEx、IDirectMusicPerformance8::GetTime、パフォーマンス パラメータ


IDirectMusicPerformance8::SetPrepareTime

トラックによってメッセージが送信されてからサウンドが聞こえるまでの間隔を設定する。この間隔は、ツールがメッセージを処理するのに十分な時間である。

HRESULT SetPrepareTime(
  DWORD dwMilliSeconds
);

パラメータ

dwMilliSeconds
準備時間の長さ (ミリ秒単位)。デフォルト値は 1,000 である。

戻り値

S_OK を返す。

注意

概要については、「タイミング」を参照すること。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::GetPrepareTime、IDirectMusicPerformance8::SetBumperLength、準備時間、遅延時間とバンパー時間


IDirectMusicPerformance8::Stop

セグメントまたはセグメント状態の再生を停止する。

現在は、このメソッドに代えて IDirectMusicPerformance8::StopEx が使用されている。これを使うと、セグメント、セグメント状態、またはオーディオパスを停止できる。

HRESULT Stop(
  IDirectMusicSegment* pSegment,
  IDirectMusicSegmentState* pSegmentState,
  MUSIC_TIME mtTime,
  DWORD dwFlags
);

パラメータ

pSegment
演奏を停止するセグメント。このセグメントに基づくすべてのセグメント状態は、mtTime の時点で停止される。「注意」を参照すること。
pSegmentState
演奏を停止するセグメント状態。「注意」を参照すること。
mtTime
セグメント、セグメント状態、またはその両方を停止するタイム。このタイムが過去のタイムである場合や、値として 0 を指定した場合は、指定セグメントとセグメント状態の演奏が即座に停止される。
dwFlags
演奏の停止タイムを指定するフラグ。境界は現在のプライマリ セグメントに関連する。値のリストについては、「IDirectMusicPerformance8::StopEx」を参照すること。

戻り値

成功した場合は S_OK を返す。

失敗した場合は E_POINTER を返す。

注意

pSegment と pSegmentState の両方が NULL である場合、すべての音楽は停止し、現在キューに置かれているすべてのセグメントが解放される。pSegment と pSegmentState のどちらかが NULL ではない場合、指定されたセグメント状態がパフォーマンスから削除される。両方共 NULL ではなく、なおかつ DMUS_SEGF_DEFAULT が使われている場合、pSegment から得られたデフォルトの分解能を使う。

すべてのパラメータに NULL または 0 を設定すると、すべての演奏が即座に停止し、コントローラ リセット メッセージおよびノートオフ メッセージが、マップされたすべてのパフォーマンス チャンネルに送信される。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::PlaySegment、IDirectMusicPerformance8::PlaySegmentEx、IDirectMusicPerformance8::StopEx、DMUS_SEGF_FLAGS


IDirectMusicPerformance8::StopEx

オブジェクトの再生を停止する。

HRESULT StopEx(
  IUnknown *pObjectToStop,
  __int64 i64StopTime,
  DWORD dwFlags
);

パラメータ

pObjectToStop
停止するセグメント、セグメント状態、またはオーディオパスの IUnknown インターフェイスへのポインタ。
i64StopTime
停止するタイム。このタイムが過去のタイムである場合や、値として 0 を指定した場合は、オブジェクトの演奏が即座に停止される。
dwFlags
演奏の停止タイムを指定するフラグ。境界は現在のプライマリ セグメントに関連する。次のいずれかの値か、DMUS_SEGF_REFTIME に別のフラグを組み合わせることができる。
0
即座に停止する。
DMUS_SEGF_AUTOTRANSITION
無音へのトランジションをアレンジして演奏する。ソングを停止する場合にのみ有効である。DirectX 8.0 では実装されない。
DMUS_SEGF_BEAT
次の拍境界で、または i64StopTime の後に停止する。
DMUS_SEGF_DEFAULT
IDirectMusicSegment8::SetDefaultResolution メソッドで設定されたデフォルト境界で停止する。
DMUS_SEGF_GRID
次のグリッド境界で、または i64StopTime の後に停止する。
DMUS_SEGF_MEASURE
次の小節境界で、または i64StopTime の後に停止する。
DMUS_SEGF_REFTIME
i64StopTime の値は基準タイムである。
DMUS_SEGF_SEGMENTEND
プライマリ セグメントの最後で停止する。
DMUS_SEGF_MARKER
次のマーカーで停止する。

戻り値

成功した場合は S_OK を返す。

失敗した場合は E_POINTER を返す。

注意

セグメントを停止すると、演奏中のすべてのインスタンスが停止する。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::Stop、IDirectMusicPerformance8::PlaySegmentEx、DMUS_SEGF_FLAGS


IDirectMusicPerformance8::TimeToRhythm

ミュージック タイムをリズム タイムに変換する。

HRESULT TimeToRhythm(
  MUSIC_TIME mtTime,
  DMUS_TIMESIGNATURE *pTimeSig,
  WORD *pwMeasure,
  BYTE *pbBeat,
  BYTE *pbGrid,
  short *pnOffset
);

パラメータ

mtTime
変換されるタイム。
pTimeSig
拍子記号に関する情報を含む DMUS_TIMESIGNATURE 構造体のアドレス。
pwMeasure
タイムが属する小節を受け取る変数のアドレス。
pbBeat
タイムが属する拍を受け取る変数のアドレス。
pbGrid
タイムが属するグリッドを受け取る変数のアドレス。
pnOffset
タイムが属するグリッド (ミュージック タイムのティックで表す) からのオフセットを受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は E_POINTER を返す。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::RhythmToTime


IDirectMusicPort8

IDirectMusicPort8 インターフェイスは、DirectMusicPort オブジェクトへのアクセスを提供する。DirectMusicPort オブジェクトは、ミュージック データを送信または受信するデバイスを表す。MPU-401 の入力ポート、MPU-401 の出力ポート、Microsoft のソフトウェア シンセサイザ、IHV が提供するフィルタは、いずれもポートである。MPU-401 などの物理的なデバイスは、複数のポートを提供できる。ただし、単一のポートでは、データのキャプチャとレンダリングはできない。

IDirectMusicPort8 は、IDirectMusicPort の定義である。2 つのインターフェイス名は入れ替え可能である。

このインターフェイスは通常、IDirectMusic8::CreatePort メソッドを使って取得する。

概要については、「DirectMusic ポートの使い方」を参照すること。

IDirectMusicPort8 インターフェイスのメソッドは、以下のグループにまとめることができる。

バッファ | PlayBuffer
 | Read
 | SetReadNotificationHandle
チャンネル | GetChannelPriority
 | GetNumChannelGroups
 | SetChannelPriority
 | SetNumChannelGroups
デバイス管理 | Activate
 | DeviceIoControl
 | SetDirectSound
DLS データ | Compact
 | DownloadInstrument
 | UnloadInstrument
情報 | GetCaps
 | GetFormat
 | GetLatencyClock
 | GetRunningStats

すべての COM インターフェイスは IUnknown インターフェイスのメソッドを継承する。このインターフェイスは、次の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTMUSICPORT8 型は、IDirectMusicPort8 インターフェイスへのポインタとして定義されている。

typedef IDirectMusicPort8 *LPDIRECTMUSICPORT8;

動作環境

ヘッダー : dmusicc.h で宣言。


IDirectMusicPort8::Activate

ポートをアクティブまたは非アクティブにする。

HRESULT Activate(
  BOOL fActive
);

パラメータ

fActive
ポートをアクティブ (TRUE) または非アクティブ (FALSE) に切り替える。

戻り値

成功した場合は S_OK を返す。

失敗した場合は DSERR_NODRIVER を返し、サウンド ドライバがないことを示す。

動作環境

ヘッダー : dmusicc.h で宣言。

参照

IDirectMusic8::Activate、DirectMusic ポートの使い方


IDirectMusicPort8::Compact

DLS またはウェーブ テーブルのメモリをコンパクトにするようポートに指示する。この結果、ダウンロードされる新しい音色が、最大限に連続したメモリ チャンクを利用できる。

HRESULT Compact();

パラメータ

なし。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_FAIL
E_INVALIDARG
E_NOTIMPL
E_OUTOFMEMORY

注意

このメソッドは、独自のウェーブ テーブル メモリを管理する必要のある DLS デバイスにだけ影響する。独自のメモリを管理しないポート (ホスト システムのメモリを使用するソフトウェア シンセサイザやハードウェア シンセサイザ) に対し、このメソッドは E_NOTIMPL を返す。

動作環境

ヘッダー : dmusicc.h で宣言。


IDirectMusicPort8::DeviceIoControl

ポートを実装する基底のファイルに対して Win32 の DeviceIoControl 関数を呼び出す。

HRESULT DeviceIoControl(
  DWORD dwIoControlCode,
  LPVOID lpInBuffer,
  DWORD nInBufferSize,
  LPVOID lpOutBuffer,
  DWORD nOutBufferSize,
  LPDWORD lpBytesReturned,
  LPOVERLAPPED lpOverlapped
);

パラメータ

dwIoControlCode
実行される制御コード。
lpInBuffer
入力データを保持するバッファ。
nInBufferSize
入力バッファのサイズ。
lpOutBuffer
出力データを受け取るバッファ。
nOutBufferSize
出力バッファのサイズ。
lpBytesReturned
出力バイト数を受け取る変数のアドレス。
lpOverlapped
非同期処理用の重なった (オーバーラップ) 構造体のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_POINTER
E_NOTIMPL

注意

Windows ドライバモデル (WDM) フィルタ グラフを実装しているポートでのみ、このメソッドはサポートされている。WDM フィルタ グラフを使っている場合、ファイル ハンドルはグラフ内の最上位のピンとして利用される。

DirectMusic がフィルタ グラフに対して実行している操作と、ピンに対して定義されたカーネル ストリーミングが衝突する可能性がある場合、DirectMusic はカーネル ストリーミングの実行を拒否できる。ただし、ユーザー定義の操作は決して妨害されない。

動作環境

ヘッダー : dmusicc.h で宣言。


IDirectMusicPort8::DownloadInstrument

DLS デバイスに音色をダウンロードする。音色をダウンロードすることは、音色を構成するデータを DLS デバイスに渡すことを意味する。この中には、音色が必要とするアーティキュレーション データとすべてのウェーブが含まれる。ウェーブのスペースを節約するために、その範囲で必要とされるウェーブとアーティキュレーションだけがダウンロードされる。このメソッドは IDirectMusicDownloadedInstrument8 インターフェイス ポインタを返すが、これは後で音色をアンロードするために使われる。

HRESULT DownloadInstrument(
  IDirectMusicInstrument *pInstrument,
  IDirectMusicDownloadedInstrument **ppDownloadedInstrument,
  DMUS_NOTERANGE *pNoteRanges,
  DWORD dwNumNoteRanges;
);

パラメータ

pInstrument
ダウンロードするデータが属する音色の IDirectMusicInstrument8 インターフェイスへのポインタ。
ppDownloadedInstrument
IDirectMusicDownloadedInstrument8 インターフェイス ポインタを受け取る変数のアドレス。
pNoteRanges
DMUS_NOTERANGE 構造体の配列のアドレス。配列内の各エントリは、音色が応答しなければならない MIDI ノートメッセージの連続範囲を指定する。音色のリージョンがダウンロードされるのは、そのリージョン内の少なくとも 1 つのノートが DMUS_NOTERANGE 構造体で指定されている場合に限られる。
dwNumNoteRanges
pNoteRanges が指す配列内の DMUS_NOTERANGE 構造体の数。この値が 0 に設定されている場合、pNoteRanges パラメータは無視され、この音色のすべてのリージョンとウェーブ データがダウンロードされる。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_POINTER
E_OUTOFMEMORY
E_NOTIMPL

注意

メモリの浪費を防ぐには、音色が不要になったときに、IDirectMusicPort8::UnloadInstrument と IDirectMusicDownloadedInstrument8::Release の両方を呼び出して、アンロードしなければならない。

動作環境

ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicPort8::Compact、音色の操作


IDirectMusicPort8::GetCaps

ポートの能力を取得する。

HRESULT GetCaps(
  LPDMUS_PORTCAPS pPortCaps
);

パラメータ

pPortCaps
ポートの能力を受け取る DMUS_PORTCAPS 構造体のアドレス。このメソッドを呼び出す前に、この構造体の dwSize メンバを正しく初期化しなければならない。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_POINTER
E_INVALIDARG

動作環境

ヘッダー : dmusicc.h で宣言。


IDirectMusicPort8::GetChannelPriority

MIDI チャンネルの優先順位を取得する。概要については、「チャンネル」を参照すること。

HRESULT GetChannelPriority(
  DWORD   dwChannelGroup,
  DWORD   dwChannel,
  LPDWORD pdwPriority
);

パラメータ

dwChannelGroup
チャンネルが置かれているグループ。
dwChannel
グループ内のチャンネルのインデックス。
pdwPriority
優先順位を受け取る変数のアドレス。「注意」を参照すること。

戻り値

S_OK を返す。

注意

Dmusicc.h 内で定義されている以下の値は、それぞれ優先順位の範囲を表す。優先順位の高いものから順にリストする。

DAUD_CRITICAL_VOICE_PRIORITY
DAUD_HIGH_VOICE_PRIORITY
DAUD_STANDARD_VOICE_PRIORITY
DAUD_LOW_VOICE_PRIORITY
DAUD_PERSIST_VOICE_PRIORITY

以下の値は、DLS レベル 1 標準による、範囲内におけるチャンネルのデフォルト順位を表す。優先順位の高いものから順にリストする。パーカッション チャンネルのチャンネル 10 が、最も優先順位が高い。

DAUD_CHAN10_VOICE_PRIORITY_OFFSET
DAUD_CHAN1_VOICE_PRIORITY_OFFSET
DAUD_CHAN2_VOICE_PRIORITY_OFFSET
DAUD_CHAN3_VOICE_PRIORITY_OFFSET
DAUD_CHAN4_VOICE_PRIORITY_OFFSET
DAUD_CHAN5_VOICE_PRIORITY_OFFSET
DAUD_CHAN6_VOICE_PRIORITY_OFFSET
DAUD_CHAN7_VOICE_PRIORITY_OFFSET
DAUD_CHAN8_VOICE_PRIORITY_OFFSET
DAUD_CHAN9_VOICE_PRIORITY_OFFSET
DAUD_CHAN11_VOICE_PRIORITY_OFFSET
DAUD_CHAN12_VOICE_PRIORITY_OFFSET
DAUD_CHAN13_VOICE_PRIORITY_OFFSET
DAUD_CHAN14_VOICE_PRIORITY_OFFSET
DAUD_CHAN15_VOICE_PRIORITY_OFFSET
DAUD_CHAN16_VOICE_PRIORITY_OFFSET

チャンネルの優先順位は、範囲とオフセットを使って表す。たとえば、DAUD_STANDARD_VOICE_PRIORITY と DAUD_CHAN10_VOICE_PRIORITY を組み合わせることで、標準範囲内で最も高い優先順位を表す。標準範囲内の優先順位は、Dmusicc.h 内の DAUD_CHAN1_DEF_VOICE_PRIORITY で始まる定義で表される。

同じ優先順位値を持つチャンネルは、所属するチャンネル グループの種類に関係なく、同じ優先順位を持つ。

動作環境

ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicPort8::SetChannelPriority


IDirectMusicPort8::GetFormat

IDirectMusic8::CreatePort に渡す DMUS_PORTPARAMS8 構造体で指定されるウェーブ フォーマットに関する情報、およびウェーブ出力で使うバッファの推奨サイズに関する情報を取得する。これらの情報を使って、ポート用に互換性のある DirectSound バッファを作成できる。

HRESULT GetFormat(
  LPWAVEFORMATEX pWaveFormatEx,
  LPDWORD pdwWaveFormatExSize
  LPDWORD pdwBufferSize
);

パラメータ

pWaveFormatEx
フォーマットに関する情報を受け取る WAVEFORMATEX 構造体のアドレス。この値は NULL でもよい。「注意」を参照すること。
pdwWaveFormatExSize
構造体のサイズを指定または取得する変数のアドレス。「注意」を参照すること。
pdwBufferSize
DirectSound バッファの推奨サイズを受け取る変数のアドレス。

戻り値

戻り値は実装によって決まる。成功した場合は S_OK を返す。

失敗した場合は E_POINTER を返す。

注意

WAVEFORMATEX 構造体は、フォーマットの詳細に応じて可変長にもなる。フォーマットの記述を取得する前に、アプリケーションは、このメソッドを呼び出し、pWaveFormatEx パラメータに NULL を指定することによって、シンセサイザ オブジェクトに対してフォーマットのサイズに関する問い合わせを行わなければならない。構造体のサイズは、pdwWaveFormatExSize が指す変数に返される。次にアプリケーションは、十分なメモリを割り当て、GetFormat を再度呼び出して、フォーマットの記述を取得できる。

pWaveFormatEx が NULL でない場合、DirectMusic は、できるだけ多くの pdwWaveFormatExSize バイトを構造体に書き込む。

動作環境

ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicPort8::SetDirectSound


IDirectMusicPort8::GetLatencyClock

ポートの遅延時間クロックへの IReferenceClock インターフェイス ポインタを取得する。この遅延時間クロックは、メッセージを演奏できる、現在に最も近い将来のタイムを指定する。遅延時間クロックは、IDirectMusic8::SetMasterClock メソッドによって設定される DirectMusic マスタ クロックに基づいている。

HRESULT GetLatencyClock(
  IReferenceClock** ppClock
);

パラメータ

ppClock
遅延時間クロックの IReferenceClock インターフェイス ポインタを受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は E_POINTER を返す。

注意

COM の規則に従って、GetLatencyClock は返されたインターフェイスの参照カウントを増やす。そのため、アプリケーションは何らかの時点で IReferenceClock インターフェイスに対して Release を呼び出さなければならない。

動作環境

ヘッダー : dmusicc.h で宣言。

参照

遅延時間とバンパー時間


IDirectMusicPort8::GetNumChannelGroups

ポート上のチャンネル グループの数を取得する。

HRESULT GetNumChannelGroups(
  LPDWORD pdwChannelGroups
);

パラメータ

pdwChannelGroups
チャンネル グループの数を受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_FAIL
E_INVALIDARG
E_NOTIMPL
E_OUTOFMEMORY

動作環境

ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicPort8::SetNumChannelGroups、チャンネル


IDirectMusicPort8::GetRunningStats

シンセサイザの状態に関する情報を取得する。

HRESULT GetRunningStats(
  LPDMUS_SYNTHSTATS pStats
);

パラメータ

pStats
シンセサイザの動作統計を受け取る DMUS_SYNTHSTATS8 構造体のアドレス。このメソッドを呼び出す前に、この構造体の dwSize メンバを正しく初期化しなければならない。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_POINTER
E_INVALIDARG
E_NOTIMPL

注意

一部のハードウェア シンセサイザは、ポートが非アクティブになっていても、動作統計を報告し続けることがある。

動作環境

ヘッダー : dmusicc.h で宣言。


IDirectMusicPort8::PlayBuffer

各ポートの再生バッファへの挿入を行う。

HRESULT PlayBuffer(
  LPDIRECTMUSICBUFFER pBuffer
);

パラメータ

pBuffer
ポートの再生キューに追加されるバッファの IDirectMusicBuffer8 インターフェイス ポインタのアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_FAIL
E_INVALIDARG
E_NOTIMPL
E_OUTOFMEMORY

注意

このバッファがシステムによって使われるのはこのメソッドの持続中だけであり、このメソッドから制御が戻った後は再利用できる。

IDirectMusicBuffer8::SetStartTime メソッドによって開始タイムが設定されていない場合、IDirectMusicBuffer8::PackStructured メソッドまたは IDirectMusicBuffer8::PackUnstructured メソッドによって設定される、バッファ内の最も早いイベントのタイムが開始タイムになる。

動作環境

ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicBuffer8、IDirectMusic8::CreateMusicBuffer


IDirectMusicPort8::Read

受信した MIDI データをバッファに設定する。読み込みに利用できるデータがなくなるまで、新しいバッファ オブジェクトに対してこのメソッドを呼び出すべきである。

HRESULT Read(
  LPDIRECTMUSICBUFFER pBuffer
);

パラメータ

pBuffer
受信した MIDI データを設定するバッファ オブジェクトの IDirectMusicBuffer8 インターフェイス ポインタのアドレス。

戻り値

成功した場合は S_OK または S_FALSEを返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_POINTER
E_NOTIMPL

注意

読み込むデータが存在しない場合、このメソッドは S_FALSE を返す。

動作環境

ヘッダー : dmusicc.h で宣言。

参照

MIDI のキャプチャ


IDirectMusicPort8::SetChannelPriority

MIDI チャンネルの優先順位を設定する。概要については、「チャンネル」を参照すること。

HRESULT SetChannelPriority(
  DWORD  dwChannelGroup,
  DWORD  dwChannel,
  DWORD  dwPriority
);

パラメータ

dwChannelGroup
チャンネルが置かれているグループ。この値は 1 以上でなければならない。
dwChannel
グループ内のチャンネルのインデックス。
dwPriority
優先順位。「IDirectMusicPort8::GetChannelPriority」の「注意」を参照すること。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_FAIL
E_INVALIDARG
E_OUTOFMEMORY
E_NOTIMPL

動作環境

ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicPort8::GetChannelPriority、DMUS_CHANNEL_PRIORITY_PMSG


IDirectMusicPort8::SetDirectSound

ポートのウェーブ データがストリーム化されるデフォルトの DirectSound オブジェクトまたはバッファ、あるいはその両方を上書きするために使われる。また、DirectSound からポートの接続を解除する際にも使われる。

HRESULT SetDirectSound(
  LPDIRECTSOUND pDirectSound,
  LPDIRECTSOUNDBUFFER pDirectSoundBuffer
);

パラメータ

pDirectSound
ポートの接続先となる DirectSound オブジェクトの IDirectSound8 インターフェイスのアドレス。既存の DirectSound オブジェクトの接続を解除し、解放する場合は NULL を指定する。
pDirectSoundBuffer
ポートの接続先である IDirectSoundBuffer8 インターフェイスのアドレス。NULL でもよい。pDirectSound が NULL である場合はこの値も NULL でなければならない。ポートが DirectX 8.0 以降のバージョンの Microsoft のソフトウェア シンセサイザである場合は、このパラメータを使用しない。

戻り値

成功した場合は S_OK または DMUS_S_NOBUFFERCONTROL を返す。「注意」を参照すること。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_ALREADY_ACTIVATED
E_INVALIDARG

注意

有効なポインタが pDirectSoundBuffer に渡されると、パンやボリュームなどのバッファ内でのコントロール チェンジが DirectMusic の再生に影響しない場合、このメソッドは DMUS_S_NOBUFFERCONTROL を返す。これは、Windows ドライバ モデル (WDM) ポートだけに影響する。

ポートをアクティブにすると、必要に応じて DirectSound プライマリ バッファがアップグレードされ、このポート (IDirectMusic8::CreatePort に渡される DMUS_PORTPARAMS8 構造体で指定する) のサンプリング レートとチャンネル情報をサポートする。

pDirectSoundBuffer が指すバッファは、このポートのサンプリング レートとチャンネル情報に一致するフォーマットを持つ、セカンダリ ストリーミング バッファでなければならない。このパラメータが NULL の場合、適切な IDirectSoundBuffer インスタンスが内部的に作成される。

ポートをいったんアクティブにしたら、IDirectSound も IDirectSoundBuffer も変更できない。

動作環境

ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicPort8::Activate、IDirectMusicPort8::GetFormat


IDirectMusicPort8::SetNumChannelGroups

アプリケーションがポート上で必要とするチャンネル グループの数を変更する。

HRESULT SetNumChannelGroups(
  DWORD dwChannelGroups
);

パラメータ

dwChannelGroups
アプリケーションがこのポートに割り当てたいチャンネル グループの数。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_FAIL
E_INVALIDARG
E_NOTIMPL
E_OUTOFMEMORY

動作環境

ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicPort8::GetNumChannelGroups、チャンネル


IDirectMusicPort8::SetReadNotificationHandle

IDirectMusicPort8::Read メソッドを使って MIDI メッセージが読み込めるようになったときに設定されるイベントを指定する。新しいデータが利用可能になると、必ずイベントのシグナルが送信される。イベント通知を無効にするには、hEvent パラメータの値として NULL を指定し、SetReadNotificationHandle を呼び出す。

HRESULT SetReadNotificationHandle(
  HANDLE hEvent
);

パラメータ

hEvent
Win32 CreateEvent 関数を呼び出したときに取得したイベント ハンドル。ポートが解放されたら、アプリケーションがこのハンドルを閉じなければならない。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_DMUSIC_RELEASED
E_NOTIMPL

注意

E_NOTIMPL は、そのポートが入力ポートでないことを意味する戻り値を返す場合もある。

動作環境

ヘッダー : dmusicc.h で宣言。

参照

MIDI のキャプチャ


IDirectMusicPort8::UnloadInstrument

以前にダウンロードした DLS 音色をアンロードする。

HRESULT UnloadInstrument(
  IDirectMusicDownloadedInstrument *pDownloadedInstrument
);

パラメータ

pDownloadedInstrument
IDirectMusicPort8::DownloadInstrument メソッドを呼び出すことで、音色をダウンロードしたときに取得された、IDirectMusicDownloadedInstrument8 インターフェイスのアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_NOT_DOWNLOADED_TO_PORT
E_POINTER
E_NOTIMPL

注意

IDirectMusicPort8::DownloadInstrument によって割り当てられたメモリを解放するには、このメソッドを呼び出さなければならない。

動作環境

ヘッダー : dmusicc.h で宣言。

参照

音色の操作


IDirectMusicPortDownload8

IDirectMusicPortDownload8 インターフェイスを使うと、アプリケーションは DLS ダウンロードをサポートしているポートと直接通信し、メモリ チャンクをポートに直接ダウンロードできる。このインターフェイスが主に使われるのは、DLS 音色を直接編集するアプリケーションをオーサリングするときである。概要については、「下位レベル DLS」を参照すること。

IDirectMusicPortDownload8 を取得するには、IDirectMusicPort8:: QueryInterface メソッドを呼び出し、IID_IDirectMusicPortDownload8 をインターフェイス GUID として渡す。ポートが DLS ダウンロードをサポートしていない場合、このメソッドは失敗する。

IDirectMusicPortDownload8 インターフェイスのメソッドは、以下のグループにまとめることができる。

バッファ管理 | AllocateBuffer
 | GetAppend
 | GetBuffer
 | GetDLId
ロード | Download
 | Unload

すべての COM インターフェイスは IUnknown インターフェイスのメソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTMUSICPORTDOWNLOAD8 型は、このインターフェイスへのポインタとして定義されている。

typedef IDirectMusicPortDownload8 *LPDIRECTMUSICPORTDOWNLOAD8;

動作環境

ヘッダー : dmusicc.h で宣言。


IDirectMusicPortDownload8::AllocateBuffer

DLS データをポートへダウンロードするためのメモリ チャンクを割り当て、このバッファへのアクセスを可能にする IDirectMusicDownload8 インターフェイス ポインタを返す。

HRESULT AllocateBuffer(
  DWORD dwSize,
  IDirectMusicDownload** ppIDMDownload
);

パラメータ

dwSize
要求するバッファのサイズ。
ppIDMDownload
IDirectMusicDownload8 インターフェイス ポインタを受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_POINTER
E_INVALIDARG
E_OUTOFMEMORY

注意

バッファを割り当てた後に、そのサイズを変更することはできない。

IDirectMusicDownload8 インターフェイスを解放すると、バッファも解放される。

動作環境

ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicPortDownload8::GetBuffer、下位レベル DLS


IDirectMusicPortDownload8::Download

ウェーブまたは音色の定義をポートにダウンロードする。最初に IDirectMusicPortDownload8::AllocateBuffer メソッドを使って、メモリを割り当てなければならない。

HRESULT Download(
  IDirectMusicDownload* pIDMDownload
);

パラメータ

pIDMDownload
バッファ用の IDirectMusicDownload8 インターフェイスのアドレス。

戻り値

戻り値はポートの実装によって決まる。

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_POINTER
E_FAIL
DMUS_E_ALREADY_DOWNLOADED
DMUS_E_BADARTICULATION
DMUS_E_BADINSTRUMENT
DMUS_E_BADOFFSETTABLE
DMUS_E_BADWAVE
DMUS_E_BADWAVELINK
DMUS_E_BUFFERNOTSET
DMUS_E_NOARTICULATION
DMUS_E_NOTMONO
DMUS_E_NOTPCM
DMUS_E_UNKNOWNDOWNLOAD

注意

ダウンロードするデータの準備方法については、「下位レベル DLS」を参照すること。

メモリをダウンロードした後、それ以上何かを行うことはできない。ダウンロードを更新するには、新しいバッファを作成し、IDirectMusicPortDownload8::GetDLId メソッドを使って取得した新しいダウンロード ID を割り当て、その ID を送信しなければならない。

動作環境

ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicPortDownload8::Unload、DMUS_DOWNLOADINFO、DMUS_OFFSETTABLE


IDirectMusicPortDownload8::GetAppend

ポートがダウンロード バッファの最後に追加する必要のあるメモリの量を取得する。ポートはこの追加メモリを使って、ループ境界にまたがってデータを補間できる。

HRESULT GetAppend(
  DWORD* pdwAppend
);

パラメータ

pdwAppend
メモリが必要となる追加サンプルの数を受け取る変数のアドレス。メモリの量はウェーブ フォーマットから計算できる。

戻り値

戻り値はポートの実装によって決まる。

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_POINTER
E_NOTIMPL

動作環境

ヘッダー : dmusicc.h で宣言。


IDirectMusicPortDownload8::GetBuffer

既知の一意な識別子を指定して、バッファの IDirectMusicDownload8 インターフェイス ポインタを取得する。

HRESULT GetBuffer(
  DWORD dwDLId,
  IDirectMusicDownload** ppIDMDownload
);

パラメータ

dwDLId
バッファのダウンロード識別子。「DMUS_DOWNLOADINFO」を参照すること。
ppIDMDownload
バッファの IDirectMusicDownload8 インターフェイス ポインタを受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_POINTER
DMUS_E_INVALID_DOWNLOADID
DMUS_E_NOT_DOWNLOADED_TO_PORT

動作環境

ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicPortDownload8::GetDLId、IDirectMusicDownload8::GetBuffer、下位レベル DLS


IDirectMusicPortDownload8::GetDLId

1 つまたは複数のダウンロード バッファのシーケンシャル識別子を取得する。

シンセサイザにダウンロードされたすべてのメモリ チャンクは、自らの DMUS_DOWNLOADINFO 構造体内で一意の識別子を保持していなければならない。GetDLId メソッドは、2 つのダウンロードが同じ識別子を持っていないことを保証する。

HRESULT GetDLId(
  DWORD* pdwStartDLId,
  DWORD dwCount
);

パラメータ

pdwStartDLId
最初の識別子を受け取る変数のアドレス。
dwCount
予約される識別子の数。一連のチャンク全体を一度にダウンロードするよう計画もできる。チャンクごとに GetDLId を呼び出す代わりに、dwCount をチャンク数に設定する。GetDLId はセットの最初の ID を返し、*pdwStartDLId と dwCount までの範囲でほかの識別子が自動的に予約される。それ以降 GetDLId を呼び出すと、それまでの予約値は飛ばされる。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_POINTER
E_INVALIDARG

動作環境

ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicPortDownload8::GetBuffer、下位レベル DLS


IDirectMusicPortDownload8::Unload

以前に IDirectMusicPortDownload8::Download を使ってダウンロードされたバッファをアンロードする。

HRESULT Unload(
  IDirectMusicDownload* pIDMDownload
);

パラメータ

pIDMDownload
バッファ用の IDirectMusicDownload8 インターフェイスのアドレス。

戻り値

戻り値はポートの実装によって決まる。

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_NOINTERFACE
DMUS_E_SYNTHNOTCONFIGURED

動作環境

ヘッダー : dmusicc.h で宣言。


IDirectMusicScript8

IDirectMusicScript8 インターフェイスは、アプリケーションが設定や取得を行える変数、およびアプリケーションが呼び出すことができるルーチンを保持するスクリプトを表す。

通常、このインターフェイスは、スクリプト ファイルをロードする IDirectMusicLoader8::GetObject を使って取得される。その後、アプリケーションは IDirectMusicScript8::Init を呼び出して、実際の再生を実行する DirectMusicPerformance オブジェクトにスクリプトを関連付ける。

IDirectMusicScript8 インターフェイスのメソッドは、以下のグループにまとめることができる。

初期化 | Init
ルーチン呼び出し | CallRoutine
列挙 | EnumRoutine
 | EnumVariable
変数の取得 | GetVariableObject
 | GetVariableNumber
 | GetVariableVariant
変数の設定 | SetVariableNumber
 | SetVariableObject
 | SetVariableVariant

すべての COM インターフェイスは IUnknown インターフェイスのメソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

ヘッダー : dmusici.h で宣言。

参照

オーディオ スクリプトの使い方


IDirectMusicScript8::CallRoutine

スクリプト内のルーチンを実行する。

HRESULT CallRoutine(
  WCHAR *pwszRoutineName,
  DMUS_SCRIPT_ERRORINFO *pErrInfo
);

パラメータ

pwszRoutineName
ルーチンの名前。
pErrInfo
エラーが発生した場合に、情報を受け取る DMUS_SCRIPT_ERRORINFO 構造体のアドレス。エラー情報が必要でない場合は、このメンバに NULL を設定する。

戻り値

成功した場合は S_OK または DMUS_S_GARBAGE_COLLECTED を返す。「ガベージ コレクション」を参照すること。

失敗した場合は、次のいずれかの値を返す。

DMUS_E_NOT_INIT
DMUS_E_SCRIPT_ERROR_IN_SCRIPT
DMUS_E_SCRIPT_ROUTINE_NOT_FOUND
E_POINTER

注意

ルーチンの実行が終了するまでは、アプリケーションに制御が返らない。

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicScript8::EnumRoutine

スクリプト内のルーチンの名前を取得する。このメソッドは、スクリプト内のすべてのルーチンを列挙する必要があるミュージック オーサリング アプリケーションが使用する。

HRESULT EnumRoutine(
  DWORD dwIndex,
  WCHAR *pwszName
);

パラメータ

dwIndex
ルーチンの 0 から始まるインデックス。
pwszName
ルーチンの名前を受け取る文字列バッファへのポインタ。少なくても MAX_PATH 要素を含む必要がある。

戻り値

成功した場合は、次のいずれかのコードを返す。

S_OK | ルーチンが列挙された。
S_FALSE | 指定されたインデックス値を持つルーチンがない。
DMUS_S_GARBAGE_COLLECTED | 「ガベージ コレクション」を参照すること。
DMUS_S_STRING_TRUNCATED | 名前が MAX_PATH より長い。

失敗した場合は、次のいずれかの値を返す。

DMUS_E_NOT_INIT
E_POINTER

注意

次のサンプルは、pScript が有効な IDirectMusicScript8 インターフェイス ポインタであり、スクリプト内のすべてのルーチンのインデックスと名前を表示する。

WCHAR wszRoutineName[MAX_PATH];
int i = 0;
while (S_OK == pScript->EnumRoutine(i++, wszRoutineName))
    printf("Routine number %d is called %S\n", i, wszRoutineName);

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicScript8::EnumVariable


IDirectMusicScript8::EnumVariable

スクリプト内の変数の名前を取得する。このメソッドは、スクリプト内のすべての変数を列挙する必要があるミュージック オーサリング アプリケーションが使用する。

HRESULT EnumVariable(
  DWORD dwIndex,
  WCHAR *pwszName
);

パラメータ

dwIndex
変数の 0 から始まるインデックス。
pwszName
変数の名前を受け取る文字列バッファのアドレス。少なくとも MAX_PATH 要素を含む必要がある。

戻り値

成功した場合は、次のいずれかのコードを返す。

S_OK | ルーチンが列挙された。
S_FALSE | 指定されたインデックス値を持つルーチンがない。
DMUS_S_GARBAGE_COLLECTED | 「ガベージ コレクション」を参照すること。
DMUS_S_STRING_TRUNCATED | 名前が MAX_PATH より長い。

失敗した場合は、次のいずれかの値を返す。

DMUS_E_NOT_INIT

注意

次のサンプルは、pScript が有効な IDirectMusicScript8 インターフェイス ポインタであり、スクリプト内のすべての変数のインデックスと名前を表示する。

WCHAR wszVariableName[MAX_PATH];
int i = 0;
while (S_OK == pScript->EnumVariable(i++, wszVariableName))
    printf("Variable number %d is called %S\n", i, wszVariableName);

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicScript8::EnumRoutine


IDirectMusicScript8::GetVariableNumber

スクリプト内で宣言された変数から 32 ビットの符号付き値を取得する。

HRESULT GetVariableNumber(
  WCHAR *pwszVariableName,
  LONG *plValue,
  DMUS_SCRIPT_ERRORINFO *pErrInfo
);

パラメータ

pwszVariableName
スクリプトの変数名。
plValue
値を受け取る変数のアドレス。
pErrInfo
エラーが発生した場合に、情報を受け取る DMUS_SCRIPT_ERRORINFO 構造体のアドレス。エラー情報が必要でない場合は、このメンバに NULL を設定する。

戻り値

成功した場合は、次のいずれかのコードを返す。

S_OK | 値が取得された。
S_FALSE | スクリプトに変数が存在しない。
DMUS_S_GARBAGE_COLLECTED | 「ガベージ コレクション」を参照すること。

失敗した場合は、次のいずれかの値を返す。

DISP_E_TYPEMISMATCH (「Winerror.h」を参照すること)
DMUS_E_NOT_INIT
DMUS_E_SCRIPT_VARIABLE_NOT_FOUND
E_POINTER

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicScript8::SetVariableNumber


IDirectMusicScript8::GetVariableObject

スクリプト内で宣言された変数からオブジェクト ポインタを取得する。

HRESULT GetVariableObject(
  WCHAR *pwszVariableName,
  REFIID riid,
  LPVOID FAR *ppv,
  DMUS_SCRIPT_ERRORINFO *pErrInfo
);

パラメータ

pwszVariableName
スクリプトの変数名。
riid
インターフェイスの一意の識別子。Dmusici.h で定義されている IID を参照すること。標準的なインターフェイスはすべて、"IID_" とインターフェイスの名前で構成される定義済みの識別子を持つ。たとえば、IDirectMusicTrack8 の識別子は IID_IDirectMusicTrack8 である。
ppv
オブジェクトの目的のインターフェイスへのポインタを受け取る変数のアドレス。
pErrInfo
エラーが発生した場合に、情報を受け取る DMUS_SCRIPT_ERRORINFO 構造体のアドレス。エラー情報が必要でない場合は、このメンバに NULL を設定する。

戻り値

成功した場合は、次のいずれかのコードを返す。

S_OK | 値が取得された。
S_FALSE | スクリプトに変数が存在しない。
DMUS_S_GARBAGE_COLLECTED | 「ガベージ コレクション」を参照すること。

失敗した場合は、次のいずれかの値を返す。

DMUS_E_NOT_INIT
DMUS_E_SCRIPT_VARIABLE_NOT_FOUND
E_NOINTERFACE
E_POINTER

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicScript8::SetVariableObject


IDirectMusicScript8::GetVariableVariant

スクリプト内で宣言された変数からバリアント値を取得する。

HRESULT GetVariableVariant(
  WCHAR *pwszVariableName,
  VARIANT *pvarValue,
  DMUS_SCRIPT_ERRORINFO *pErrInfo
);

パラメータ

pwszVariableName
スクリプトの変数名。
pvarValue
値を受け取る変数のアドレス。
pErrInfo
エラーが発生した場合に、情報を受け取る DMUS_SCRIPT_ERRORINFO 構造体のアドレス。エラー情報が必要でない場合は、このメンバに NULL を設定する。

戻り値

成功した場合は、次のいずれかのコードを返す。

S_OK | 値が取得された。
S_FALSE | スクリプトに変数が存在しない。
DMUS_S_GARBAGE_COLLECTED | 「ガベージ コレクション」を参照すること。

失敗した場合は、次のいずれかの値を返す。

DMUS_E_NOT_INIT
DMUS_E_SCRIPT_CONTENT_READONLY
DMUS_E_SCRIPT_UNSUPPORTED_VARTYPE
DMUS_E_SCRIPT_VARIABLE_NOT_FOUND
E_POINTER

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicScript8::SetVariableVariant


IDirectMusicScript8::Init

サウンドを演奏するパフォーマンスにスクリプトを関連付ける。

HRESULT Init(
  IDirectMusicPerformance *pPerformance,
  DMUS_SCRIPT_ERRORINFO *pErrInfo
);

パラメータ

pPerformance
パフォーマンス オブジェクトの IDirectMusicPerformance8 インターフェイスのアドレス。
pErrInfo
エラーが発生した場合に、情報を受け取る DMUS_SCRIPT_ERRORINFO 構造体のアドレス。エラー情報が必要でない場合は、このメンバに NULL を設定する。

戻り値

成功した場合は、次のいずれかのコードを返す。

S_OK | スクリプトが初期化された。
S_FALSE | スクリプトが既に別のパフォーマンスにアタッチされている。
DMUS_S_GARBAGE_COLLECTED | 「ガベージ コレクション」を参照すること。

失敗した場合は、次のいずれかの値を返す。

DMUS_E_NOT_INIT
DMUS_E_SCRIPT_CONTENT_READONLY
DMUS_E_SCRIPT_ERROR_IN_SCRIPT
DMUS_E_SCRIPT_VARIABLE_NOT_FOUND
E_POINTER
E_NOINTERFACE

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicScript8::SetVariableNumber

スクリプト内で宣言された変数に 32 ビットの符号付き値を設定する。

HRESULT SetVariableNumber(
  WCHAR *pwszVariableName,
  LONG lValue,
  DMUS_SCRIPT_ERRORINFO *pErrInfo
);

パラメータ

pwszVariableName
スクリプトの変数名。
lValue
変数に割り当てる値。
pErrInfo
エラーが発生した場合に、情報を受け取る DMUS_SCRIPT_ERRORINFO 構造体のアドレス。エラー情報が必要でない場合は、このメンバに NULL を設定する。

戻り値

成功した場合は、次のいずれかのコードを返す。

S_OK | 値が設定された。
S_FALSE | スクリプトに変数が存在しない。
DMUS_S_GARBAGE_COLLECTED | 「ガベージ コレクション」を参照すること。

失敗した場合は、次のいずれかの値を返す。

DMUS_E_NOT_INIT
DMUS_E_SCRIPT_CONTENT_READONLY
DMUS_E_SCRIPT_VARIABLE_NOT_FOUND
E_POINTER

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicScript8::GetVariableNumber


IDirectMusicScript8::SetVariableObject

スクリプト内で宣言された変数にオブジェクト インターフェイス ポインタを設定する。

HRESULT SetVariableObject(
  WCHAR *pwszVariableName,
  IUnknown *punkValue,
  DMUS_SCRIPT_ERRORINFO *pErrInfo
);

パラメータ

pwszVariableName
スクリプトの変数名。
punkValue
変数に設定するインターフェイス ポインタ。IDirectMusicSegment8 など、スクリプト エンジンがサポートする DirectMusic オブジェクトのインターフェイス、または IDispatch インターフェイスを実装するその他のオブジェクトのインターフェイスを使用できる。
pErrInfo
エラーが発生した場合に、情報を受け取る DMUS_SCRIPT_ERRORINFO 構造体のアドレス。エラー情報が必要でない場合は、このメンバに NULL を設定する。

戻り値

成功した場合は、次のいずれかのコードを返す。

S_OK | 値が設定された。
S_FALSE | スクリプトに変数が存在しない。
DMUS_S_GARBAGE_COLLECTED | 「ガベージ コレクション」を参照すること。

失敗した場合は、次のいずれかの値を返す。

DMUS_E_NOT_INIT
DMUS_E_SCRIPT_CONTENT_READONLY
DMUS_E_SCRIPT_VARIABLE_NOT_FOUND
E_POINTER

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicScript8::GetVariableObject


IDirectMusicScript8::SetVariableVariant

スクリプト内で宣言された変数にバリアント値を設定する。

HRESULT SetVariableVariant(
  WCHAR *pwszVariableName,
  VARIANT varValue,
  BOOL fSetRef,
  DMUS_SCRIPT_ERRORINFO *pErrInfo
);

パラメータ

pwszVariableName
スクリプトの変数名。
varValue
変数に割り当てる値。
fSetRef
変数が参照により設定される場合は TRUE、値により設定される場合は FALSE。参照によって設定できるのはオブジェクトだけである。このフラグには、DirectMusic オブジェクトに対しては常に TRUE を指定し、その他の変数に対しては FALSE を指定する。
pErrInfo
エラーが発生した場合に、情報を受け取る DMUS_SCRIPT_ERRORINFO 構造体のアドレス。エラー情報が必要でない場合は、このメンバに NULL を設定する。

戻り値

成功した場合は、次のいずれかのコードを返す。

S_OK | 値が設定された。
S_FALSE | スクリプトに変数が存在しない。
DMUS_S_GARBAGE_COLLECTED | 「ガベージ コレクション」を参照すること。

失敗した場合は、次のいずれかの値を返す。

DMUS_E_NOT_INIT
DMUS_E_SCRIPT_CONTENT_READONLY
DMUS_E_SCRIPT_NOT_A_REFERENCE
DMUS_E_SCRIPT_UNSUPPORTED_VARTYPE
DMUS_E_SCRIPT_VALUE_NOT_SUPPORTED
DMUS_E_SCRIPT_VARIABLE_NOT_FOUND
E_POINTER

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicScript8::GetVariableObject


IDirectMusicSegment8

IDirectMusicSegment8 インターフェイスは、セグメント、つまり複数のトラックで構成される音楽の部品を表す。ほとんどのアプリケーションは、ミュージック データをセグメント レベルで処理する。概要については、「セグメントの使い方」を参照すること。

DirectMusicSegment オブジェクトは、自らのデータをロードするために IDirectMusicObject8 と IPersistStream の各インターフェイスもサポートしている。

IDirectMusicSegment8 は IDirectMusicSegment インターフェイスを引き継ぎ、新しいメソッドを追加する。

IDirectMusicSegment8 インターフェイスのメソッドは、以下のグループにまとめることができる。

音色 | Download
 | Unload
通知 | AddNotificationType
 | RemoveNotificationType
パラメータ | GetParam
 | SetParam
タイミングとループ | GetDefaultResolution
 | GetLength
 | GetLoopPoints
 | GetRepeats
 | GetStartPoint
 | SetDefaultResolution
 | SetLength
 | SetLoopPoints
 | SetRepeats
 | SetStartPoint
ツール | GetGraph
 | SetGraph
トラック | GetTrack
 | GetTrackGroup
 | InsertTrack
 | RemoveTrack
 | SetTrackConfig
その他 | Clone
 | Compose
 | GetAudioPathConfig
 | InitPlay
 | SetPChannelsUsed

すべての COM インターフェイスは IUnknown インターフェイスのメソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicSegment8::AddNotificationType

通知タイプを追加する。このメソッドは、セグメントが通知に応答できるようにするために、IDirectMusicPerformance8::AddNotificationType メソッドにより呼び出される。セグメントは各トラックの IDirectMusicTrack8::AddNotificationType メソッドを呼び出す。

HRESULT AddNotificationType(
  REFGUID rguidNotificationType
);

パラメータ

rguidNotificationType
追加される通知タイプの識別子への参照 (C++) またはアドレス (C)。定義済みのタイプについては、「DMUS_NOTIFICATION_PMSG」を参照すること。アプリケーションは、カスタム トラックについて独自のタイプを定義できる。

戻り値

成功した場合は S_OK を返す。

バッファの内容は DirectSound によって初期化されない。アプリケーションは、バッファに無音が含まれると想定することはできない。

ハードウェア アクセラレーションを利用できないシステムで DSBCAPS_LOCHARDWARE フラグを使ってバッファを作成しようとすると、メソッドは失敗し、Windows 95 および Windows 98 では DSERR_CONTROLUNAVAIL を返す。Windows 2000 では DSERR_INVALIDCALL を返す。

S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_POINTER
E_OUTOFMEMORY

注意

セグメントは、タイプ GUID_NOTIFICATION_PERFORMANCE の通知を生成できない。このタイプの通知を取得するには、IDirectMusicPerformance8::AddNotificationType を呼び出さなければならない。

動作環境

ヘッダー : dmusici.h で宣言。

参照

通知とイベントの処理


IDirectMusicSegment8::Clone

セグメントとその中のトラックのすべてまたはパートをコピーする。

HRESULT Clone(
  MUSIC_TIME mtStart,
  MUSIC_TIME mtEnd,
  IDirectMusicSegment** ppSegment
);

パラメータ

mtStart
コピー開始パート。0 未満の場合や、セグメントの長さを超える場合は、0 が使われる。
mtEnd
コピー終了パート。この値がセグメントの最後を超える場合は、セグメントの最後までコピーされる。0、または mtStart 未満の場合も、最後までコピーされる。
ppSegment
作成されたセグメントの IDirectMusicSegment インターフェイスへのポインタを受け取る変数のアドレス。IDirectMusicSegment8 を取得するには、QueryInterface を使用する。アプリケーションには、セグメントの終了時に Release を呼び出す責任がある。

戻り値

成功した場合は S_OK を返す。一部のトラックのコピーに失敗した場合は S_FALSE を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_OUTOFMEMORY
E_POINTER

注意

開始ポイント、ループ ポイント、反復回数、ツールグラフ、デフォルトのオーディオパスなど、オリジナルのセグメントのプロパティがクローンにコピーされる。

スタイルベースのセグメントは、mtStart が 0 より大きい場合、小節境界上になければならない。

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicSegment8::Compose

DMUS_TRACKCONFIG_COMPOSING フラグの設定されたすべてのトラックをアレンジし、アレンジ済みのトラックをこのセグメント、またはこのセグメントのクローンに配置する。

HRESULT Compose(
  MUSIC_TIME mtTime,
  IDirectMusicSegment* pFromSegment,
  IDirectMusicSegment* pToSegment,
  IDirectMusicSegment** ppComposedSegment
);

パラメータ

mtTime
トランジションをアレンジする pFromSegment の現在タイムを指定する MUSIC_TIME タイプの値。pFromSegment が NULL の場合は 0 を設定する。
pFromSegment
トランジションにつながるセグメントを指定する、IDirectMusicSegment8 インターフェイスへのポインタ。呼び出し元セグメントがトランジションでない場合は NULL。
pToSegment
トランジションに続くセグメントを指定する、IDirectMusicSegment8 インターフェイスへのポインタ。呼び出し元セグメントがトランジションでない場合、またはトランジションがエンディングである場合は NULL。
ppComposedSegment
アレンジ済みセグメントの IDirectMusicSegment8 インターフェイス ポインタを受け取る変数のアドレス。呼び出し元セグメントを再アレンジする場合は NULL。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_NOT_FOUND
E_FAIL
E_OUTOFMEMORY
E_POINTER

注意

ポインタのパラメータがすべて NULL である場合、セグメントはそのすべてのトラックに対して IDirectMusicTrack8::Compose を呼び出す。アレンジに必要な別のトラックを探しているアレンジ トラックの場合、必要なトラックが見つかると、DMUS_E_NOT_FOUND を返す。

ppComposedSegment が NULL でない場合、このメソッドは、再アレンジしたトラックを保持するオリジナル セグメントのクローンを作成する。pFromSegment または pToSegment のどちらも NULL ではない場合、呼び出し元セグメントはトランジションであると想定され、ブラケット付きのセグメントを参照するヘッダーのみを保持するトラックが含まれていると考えられる。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicTrack8::Compose、IDirectMusicSegment8::SetTrackConfig


IDirectMusicSegment8::Download

バンド データをパフォーマンスまたはオーディオパスにダウンロードする。

HRESULT Download(
  IUnknown *pAudioPath
);

パラメータ

pAudioPath
データを受け取るパフォーマンスやオーディオパスの IUnknown インターフェイスへのポインタ。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_NOT_FOUND
DMUS_E_TRACK_NOT_FOUND
E_POINTER

注意

セグメント内のすべてのバンドとウェーブ データがダウンロードされる。

セグメントを解放する前に、必ず IDirectMusicSegment8::Unload を呼び出すこと。

動作環境

ヘッダー : dmusici.h で宣言。

参照

バンドの使い方


IDirectMusicSegment8::GetAudioPathConfig

セグメントに埋め込まれたオーディオパス構成を表すオブジェクトを取得する。このオブジェクトは IDirectMusicPerformance8::CreateAudioPath に渡すことができる。

HRESULT GetAudioPathConfig(
  IUnknown ** ppAudioPathConfig
);

パラメータ

ppAudioPathConfig
オーディオパス構成オブジェクトの IUnknown インターフェイスへのポインタを受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_NO_AUDIOPATH_CONFIG
E_POINTER

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicSegment8::GetDefaultResolution

同期用のデフォルトの分解能を取得する。

HRESULT GetDefaultResolution(
  DWORD* pdwResolution
);

パラメータ

pdwResolution
デフォルトの分解能を受け取る変数のアドレス。「DMUS_SEGF_FLAGS」を参照すること。

戻り値

成功した場合は S_OK を返す。

失敗した場合は E_POINTER を返す。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegment8::SetDefaultResolution、セグメントのタイミング


IDirectMusicSegment8::GetGraph

セグメントのツールグラフを取得する。

HRESULT GetGraph(
  IDirectMusicGraph** ppGraph
);

パラメータ

ppGraph
ツールグラフへのポインタを受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_NOT_FOUND
E_POINTER

注意

セグメント内にグラフが存在しない場合、このメソッドは DMUS_E_NOT_FOUND を返す。

ツールグラフの参照カウントはインクリメントされる。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegment8::SetGraph


IDirectMusicSegment8::GetLength

セグメントの長さを取得する。

HRESULT GetLength(
  MUSIC_TIME* pmtLength
);

パラメータ

pmtLength
ミュージック タイムで表されたセグメントの長さを受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は E_POINTER を返す。

注意

ウェーブ ファイルから作成されたセグメントの場合、このメソッドは常に *pmtLength fに 1 を返す。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegment8::SetLength


IDirectMusicSegment8::GetLoopPoints

セグメント内の開始ポイントとループ ポイントを取得する。これらの 2 つのポイントの間に、IDirectMusicSegment8::SetRepeats メソッドで設定された回数だけ反復される。

HRESULT GetLoopPoints(
  MUSIC_TIME* pmtStart,
  MUSIC_TIME* pmtEnd
);

パラメータ

pmtStart
ループの開始ポイントを受け取る変数のアドレス。
pmtEnd
ループの終了ポイントを受け取る変数のアドレス。値 0 は、セグメント全体をループさせることを意味する。

戻り値

成功した場合は S_OK を返す。

失敗した場合は E_POINTER を返す。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegment8::SetLoopPoints、セグメントのタイミング


IDirectMusicSegment8::GetParam

このセグメント内部のトラックからデータを取得する。

HRESULT GetParam(
  REFGUID rguidType,
  DWORD dwGroupBits,
  DWORD dwIndex,
  MUSIC_TIME mtTime,
  MUSIC_TIME* pmtNext,
  void* pParam
);

パラメータ

rguidType
取得されるデータ型の識別子への参照 (C++) またはアドレス (C)。「標準トラック パラメータ」を参照すること。
dwGroupBits
希望のトラックが置かれているグループ。すべてのグループを指定するには、この値を 0xFFFFFFFF に設定する。詳細については、「トラックの識別」を参照すること。
dwIndex
データを取得する元となる、dwGroupBits で識別されるグループ内のトラックのインデックス。パラメータを保持する最初のトラックを見つけるには、DMUS_SEG_ANYTRACK を指定する。
mtTime
データの取得を行うタイム。
pmtNext
データが無効になるセグメント タイム (mtTime からの相対タイム) を受け取る変数のアドレス。この変数が値 0 を返した場合、データが常に有効になっているか、データが無効になるタイムが不明であることを意味する。この情報が不要な場合は、pmtNext を NULL に設定してもよい。「注意」を参照すること。
pParam
返されるデータの保存用に割り当てられた構造体のアドレス。返されるデータの保存用に割り当てられた構造体のアドレス。この構造体は、rguidType で識別されたデータ型にとって適切な種類とサイズを備えていなければならない。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_GET_UNSUPPORTED
DMUS_E_TRACK_NOT_FOUND
E_POINTER

注意

別の制御セグメントが挿入される場合、*pmtNext で返されるタイムの前にデータが無効になることがある。詳細については、「制御セグメント」を参照すること。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::GetParam、IDirectMusicSegment8::SetParam、IDirectMusicTrack8::GetParamEx、パフォーマンス パラメータ


IDirectMusicSegment8::GetRepeats

セグメントのループ部分に設定された反復回数を取得する。

HRESULT GetRepeats(
  DWORD* pdwRepeats
);

パラメータ

pdwRepeats
セグメントのループ部分に設定されている反復回数を受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は E_POINTER を返す。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegment8::SetRepeats


IDirectMusicSegment8::GetStartPoint

セグメントの演奏が開始された、またはこれから開始されるポイントを取得する。

HRESULT GetStartPoint(
  MUSIC_TIME* pmtStart
);

パラメータ

pmtStart
セグメントの演奏開始タイムを受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は E_POINTER を返す。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegment8::SetStartPoint


IDirectMusicSegment8::GetTrack

指定されたタイプ、グループ、およびインデックスに一致するトラックをトラック リストから検索し、DirectMusicTrack オブジェクトへのポインタを取得する。

HRESULT GetTrack(
  REFGUID rguidType,
  DWORD dwGroupBits,
  DWORD dwIndex,
  IDirectMusicTrack** ppTrack
);

パラメータ

rguidType
検索するトラックのクラス識別子への参照 (C++) またはアドレス (C)。値として GUID_NULL を指定すると、任意のトラックを取得する。トラック識別子については、「標準トラックの種類」を参照すること。
dwGroupBits
検索されるトラックを含むトラック グループ。値 0 は無効である。dwGroupBits 内の各ビットは、1 つのトラック グループに対応する。グループにかかわりなくすべてのトラックを検索するには、このパラメータを 0xFFFFFFFF に設定する。
dwIndex
rguidType タイプ、なおかつ dwGroupBits に一致するために返されたグループから 1 つのトラックを識別するために使われる、0 から始まるインデックス。dwGroupBits で複数のグループが選択されている場合、選択されたグループの集合の中で見つかった pCommandGuid タイプから、このインデックスは n 番目のトラックを指定する。「注意」を参照すること。
ppTrack
トラックへのポインタを受け取る変数のアドレス。トラックが見つからなかった場合、この変数は NULL に設定される。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_NOT_FOUND
E_FAIL
E_POINTER

注意

すべてのトラックを列挙するには、rguidType に GUID_NULL、dwGroupBits に 0xFFFFFFFF を指定する。最初は dwIndex を 0 に設定して GetTrack を呼び出し、メソッドが成功コードを返さなくなるまで dwIndex をインクリメントして呼び出しを続ける。

DirectMusic Producer で作成されるセグメントのトラックは、必ずしもアプリケーションと同じ順序である必要はない。特定のトラックの検索を dwIndex だけに頼らないこと。

トラック グループの詳細については、「トラックの識別」を参照すること。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegment8::InsertTrack


IDirectMusicSegment8::GetTrackGroup

セグメント内のトラックに対して設定されたグループ ビットを取得する。

HRESULT GetTrackGroup(
  IDirectMusicTrack* pTrack,
  DWORD* pdwGroupBits
);

パラメータ

pTrack
グループ ビットの検索対象となるトラック。
pdwGroupBits
グループを受け取る変数のアドレス。*pdwGroupBits 内の各ビットは、1 つのトラック グループに対応する。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_NOT_FOUND
E_INVALIDARG

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegment8::InsertTrack、トラックの識別


IDirectMusicSegment8::InitPlay

演奏状態を初期化する。このメソッドは内部的に使用されるものであり、DirectX 7.0 より後のバージョンには実装されていない。

HRESULT InitPlay(
  IDirectMusicSegmentState** ppSegState,
  IDirectMusicPerformance* pPerformance,
  DWORD dwFlags
);

パラメータ

ppSegState
IDirectMusicSegmentState8 インターフェイスへのポインタを受け取る変数のアドレス。このインターフェイスはこのメソッドを呼び出したときに作成され、状態データを保持するために使われる。参照カウントが 1 になって返されるので、Release メソッドを呼び出すと、このインターフェイスは完全に解放される。
pPerformance
IDirectMusicPerformance8 インターフェイスのアドレス。パフォーマンス オブジェクトに対してこのメソッドを呼び出すために、セグメントとセグメント状態はこのインターフェイスを必要とする。
dwFlags
トラックの動作を変更する DMUS_SEGF_FLAGS。

戻り値

DirectX 8.0 以降では E_NOTIMPL を返す。

それ以前のバージョンでは、成功した場合は S_OK を返す。失敗した場合は、次のいずれかのエラー値を返す。

E_POINTER
E_OUTOFMEMORY

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicSegment8::InsertTrack

指定されたトラックを、セグメントのトラックのリストに挿入する。

HRESULT InsertTrack(
  IDirectMusicTrack* pTrack,
  DWORD dwGroupBits
);

パラメータ

pTrack
セグメントに追加されるトラック。
dwGroupBits
トラックの挿入先となる、1 つまたは複数のグループ。この値は 0 にできない。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_NOT_INIT
E_FAIL
E_INVALIDARG
E_OUTOFMEMORY
E_POINTER

注意

トラックは互いが正しくリンクするようにグループで配置される。たとえば、セグメントには、スタイル トラックとミュート トラックがそれぞれ 2 つ含まれる場合がある。各スタイル トラックは、それらに関連付けられているミュート トラックと共に異なるグループに配置される。トラック グループの詳細については、「トラックの識別」を参照すること。

セグメントが現在演奏中の場合、新しいトラックは再生に含まれない。これは、セグメント状態の初期化の際に新しいトラックは含まれていなかったためである。

このメソッドによりトラックは初期化される。ただし、それ以降にトラック データが変更される場合、アプリケーションは IDirectMusicTrack8::Init を呼び出して、トラックを再び初期化する必要がある。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegment8::RemoveTrack、IDirectMusicSegment8::GetTrackGroup


IDirectMusicSegment8::RemoveNotificationType

通知タイプを削除する。このメソッドは、セグメントが通知を削除できるようにするために、IDirectMusicPerformance8::RemoveNotificationType メソッドにより呼び出される。セグメントは各トラックの IDirectMusicTrack8::RemoveNotificationType メソッドを呼び出す。

HRESULT RemoveNotificationType(
  REFGUID rguidNotificationType
);

パラメータ

rguidNotificationType
削除される通知タイプの識別子への参照 (C++) またはアドレス (C)。(定義済みのタイプについては、「DMUS_NOTIFICATION_PMSG」を参照すること)。この値を GUID_NULL に設定すると、すべての通知が削除される。

戻り値

成功した場合は S_OK を返し、通知タイプがこれまでに設定されていない場合は S_FALSE を返す。

失敗した場合は E_POINTER を返す。

動作環境

ヘッダー : dmusici.h で宣言。

参照

通知とイベントの処理


IDirectMusicSegment8::RemoveTrack

セグメントのトラック リストからトラックを削除する。

HRESULT RemoveTrack(
  IDirectMusicTrack* pTrack
);

パラメータ

pTrack
セグメントのトラック リストから削除されるトラック。

戻り値

成功した場合は S_OK を返す。指定されたトラックがトラック リストの中に存在しない場合は S_FALSE を返す。

失敗した場合は E_POINTER を返す。

注意

削除されたトラックは解放される。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegment8::InsertTrack


IDirectMusicSegment8::SetDefaultResolution

同期用のデフォルトの分解能を設定する。

HRESULT SetDefaultResolution(
  DWORD dwResolution
);

パラメータ

dwResolution
目的のデフォルトの分解能。この値は、0 または次に示す DMUS_SEGF_FLAGS 列挙型のメンバのいずれかである。

DMUS_SEGF_MEASURE
DMUS_SEGF_BEAT
DMUS_SEGF_GRID

戻り値

S_OK を返す。

注意

このメソッドは、主にセカンダリ セグメント (モチーフ) が自らを小節、拍、またはグリッドのどの分解能で同期させるかを定義するために使われる。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegment8::GetDefaultResolution、セグメントのタイミング


IDirectMusicSegment8::SetGraph

セグメントにツールグラフを割り当てる。

HRESULT SetGraph(
  IDirectMusicGraph* pGraph
);

パラメータ

pGraph
ツールグラフのポインタ。セグメント グラフを消去するために NULL に設定してもよい。

戻り値

成功した場合は S_OK を返す。

失敗した場合は E_POINTER を返す。

注意

現在のツールグラフ内で処理中のメッセージはすべて削除される。

このメソッドはグラフの参照カウントをインクリメントするので、オリジナルの参照を解放しておくと安全である。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::SetGraph、DirectMusic ツール


IDirectMusicSegment8::SetLength

セグメントの長さをミュージック タイム単位で設定する。通常、ローダーがファイルからセグメントの長さを取得して、その長さをセグメント オブジェクトに渡すときに、ローダーがこのメソッドを呼び出す。

HRESULT SetLength(
  MUSIC_TIME mtLength
);

パラメータ

mtLength
目的の長さ。0 より大きい値でなければならない。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_INVALIDARG
DMUS_E_OUT_OF_RANGE

注意

プライマリ セグメントの長さを設定しなかった場合は、DMUS_SEGF_QUEUE フラグを指定したほかのプライマリ セグメントをキューに挿入する際に問題が発生することがある。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegment8::GetLength


IDirectMusicSegment8::SetLoopPoints

反復するセグメントのパートの開始ポイントと終了ポイントを設定する。セグメントのパートは、IDirectMusicSegment8::SetRepeats メソッドによって設定される回数だけ反復する。

HRESULT SetLoopPoints(
  MUSIC_TIME mtStart,
  MUSIC_TIME mtEnd
);

パラメータ

mtStart
ループの開始ポイント。
mtEnd
ループの終了ポイント。値 0 は、セグメント全体をループさせることを意味する。

戻り値

成功した場合は S_OK を返す。

失敗した場合は DMUS_E_OUT_OF_RANGE を返す。

注意

セグメントの演奏時には、開始タイムから mtEnd まで演奏し、mtStart にループする。次に、ループ部分を IDirectMusicSegment8::SetRepeats によって設定される回数だけ反復し、最後まで演奏する。

デフォルト値は、最初から最後までセグメント全体をループするように設定されている。

mtStart の値がセグメントの長さ以上の場合、または mtEnd の値がセグメントの長さを超える場合、メソッドは失敗する。mtEnd が 0 の場合、mtStart も 0 でなければならない。

このメソッドは、このセグメントから作成された、現在演奏中のセグメント状態に影響を及ぼすことはない。

キャッシングされたセグメントのループ ポイントは、セグメントが解放され、再ロードされた場合でも継続される。セグメントが後でキャッシュから再ロードされないようにするには、セグメントを解放する前に、IDirectMusicLoader8::ReleaseObject を呼び出す。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegment8::GetLoopPoints、セグメントのタイミング


IDirectMusicSegment8::SetParam

このセグメント内部のトラックにデータを設定する。

HRESULT SetParam(
  REFGUID rguidType,
  DWORD dwGroupBits,
  DWORD dwIndex,
  MUSIC_TIME mtTime,
  void* pParam
);

パラメータ

rguidType
設定されるデータ型への参照 (C++) またはアドレス (C)。「標準トラック パラメータ」を参照すること。
dwGroupBits
希望のトラックが置かれているグループ。すべてのグループを指定するには、この値を 0xFFFFFFFF に設定する。詳細については、「トラックの識別」を参照すること。
dwIndex
データをどこに設定するかを示す、dwGroupBits で識別されるグループ内のトラックのインデックス。パラメータを格納するグループ内のすべてのトラックにパラメータを設定するには、DMUS_SEG_ALLTRACKS を指定する。
mtTime
データの設定を行うタイム。
pParam
データを保持する構造体のアドレス。データが必要ない場合は NULL を指定する。この構造体は、rguidType で識別されたデータ型にとって適切な種類とサイズを備えていなければならない。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_SET_UNSUPPORTED
DMUS_E_TRACK_NOT_FOUND
E_POINTER

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::SetParam、IDirectMusicSegment8::GetParam、IDirectMusicTrack8::SetParamEx、パフォーマンス パラメータ


IDirectMusicSegment8::SetPChannelsUsed

このセグメントが使うパフォーマンス チャンネルを設定する。このメソッドは通常、トラックがどのチャンネルを使っているかをセグメントに通知するために IDirectMusicTrack8::Init メソッド内でトラックによって呼び出される。

HRESULT SetPChannelsUsed(
  DWORD dwNumPChannels,
  DWORD* paPChannels
);

パラメータ

dwNumPChannels
設定される P チャンネルの数。この値は、paPChannels が指す配列内のメンバの数と等しくなければならない。
paPChannels
P チャンネルの配列へのポインタ。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_INVALIDARG
E_OUTOFMEMORY
E_POINTER

注意

このメソッドを使うと、セグメントがどのポートを使っているかをパフォーマンスに知らせることができ、その結果、パフォーマンスがワースト ケースに備える代わりに実際の遅延時間を決定できる。

動作環境

ヘッダー : dmusici.h で宣言。

参照

遅延時間とバンパー時間、チャンネル


IDirectMusicSegment8::SetRepeats

セグメントのループ部分に反復する回数を設定する。デフォルトでは、セグメント全体がループされる。

HRESULT SetRepeats(
  DWORD dwRepeats
);

パラメータ

dwRepeats
セグメントのループ部分が反復される回数。明示的に停止されるまで反復するには、DMUS_SEG_REPEAT_INFINITE を指定する。値 0 は、一度の演奏だけで反復がないことを意味する。

戻り値

S_OK を返す。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegment8::GetRepeats、IDirectMusicSegment8::SetLoopPoints、セグメントのタイミング


IDirectMusicSegment8::SetStartPoint

セグメントの演奏を開始するポイントを設定する。

HRESULT SetStartPoint(
  MUSIC_TIME mtStart
);

パラメータ

mtStart
セグメントの演奏開始ポイント。0 以上で、セグメントの長さより小さくなければならない。

戻り値

成功した場合は S_OK を返す。

失敗した場合は DMUS_E_OUT_OF_RANGE を返す。

注意

開始ポイントは、聞くことのできるセグメントの最初のポイントである。ただし、セグメントの開始ポイントが経過時間に合わせてある場合、実際に聞こえる最初のポイントは、これより遅くなる。詳細については、「セグメントのタイミング」を参照すること。

デフォルトの開始ポイントは 0 であり、セグメントの先頭から開始することを意味する。

セグメントがまだ長さを持っていない場合、このメソッドの前に IDirectMusicSegment8::SetLength を呼び出さなければならない。

このメソッドは、このセグメントから作成された、現在演奏中のセグメント状態に影響を及ぼすことはない。

キャッシングされたセグメントの開始ポイントは、セグメントが解放され、再ロードされた場合でも継続される。セグメントが後でキャッシュから再ロードされないようにするには、セグメントを解放する前に、IDirectMusicLoader8::ReleaseObject を呼び出す。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegment8::GetStartPoint、IDirectMusicSegmentState8::GetStartPoint、IDirectMusicSegment8::SetLength、IDirectMusicSegment8::SetLoopPoints、セグメントのタイミング


IDirectMusicSegment8::SetTrackConfig

トラックの構成を設定する。

HRESULT SetTrackConfig(
  REFGUID rguidTrackClassID,
  DWORD dwGroupBits,
  DWORD dwIndex,
  DWORD dwFlagsOn,
  DWORD dwFlagsOff
);

パラメータ

rguidTrackClassID
トラック クラスの識別子への参照 (C++) またはアドレス (C)。値のリストについては、「標準トラックの種類」を参照すること。
dwGroupBits
トラックが所属するグループ。
dwIndex
グループ内のトラックのインデックス、またはグループ内のすべてのトラックの構成を設定する DMUS_SEG_ALLTRACKS。
dwFlagsOn
設定する構成フラグ。「注意」を参照すること。
dwFlagsOff
クリアする構成フラグ。「注意」を参照すること。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_TRACK_NOT_FOUND
E_INVALIDARG

注意

セグメントのフラグを変更すると、セグメント状態のそれ以降のインスタンスは、変更内容を継承する。ただし、既に演奏中であるセグメント状態は動作を変更しない。

次のフラグが定義されている。

DMUS_TRACKCONFIG_COMPOSING
このトラックを使って、ほかのトラックをアレンジする。
DMUS_TRACKCONFIG_CONTROL_ENABLED
IDirectMusicTrack8::GetParamEx を有効にする。
DMUS_TRACKCONFIG_CONTROL_NOTIFICATION
制御セグメント内で演奏中の場合、プライマリ セグメント トラックの通知を上書きする。
DMUS_TRACKCONFIG_CONTROL_PLAY
制御セグメント内で演奏中の場合、プライマリ セグメント トラックの再生を上書きする。
DMUS_TRACKCONFIG_DEFAULT
DMUS_TRACKCONFIG_CONTROL_ENABLED | DMUS_TRACKCONFIG_PLAY_ENABLED | DMUS_TRACKCONFIG_NOTIFICATION_ENABLED の組み合わせ。
DMUS_TRACKCONFIG_FALLBACK
要求した情報がプライマリ セグメントおよび制御セグメントから返されない場合、トラックがこのセグメントからのパラメータの取得を試みる。
DMUS_TRACKCONFIG_LOOP_COMPOSE
トラックが反復されるたびに、データを再生成する。
DMUS_TRACKCONFIG_NOTIFICATION_ENABLED
通知を有効にする。
DMUS_TRACKCONFIG_OVERRIDE_ALL
制御セグメントおよびプライマリ セグメントの前に、トラックがこのセグメントからのパラメータの取得を試みる。
DMUS_TRACKCONFIG_OVERRIDE_PRIMARY
プライマリ セグメントの前に、トラックがこのセグメントからのパラメータの取得を試みる。
DMUS_TRACKCONFIG_PLAY_CLOCKTIME
ミュージック タイムを使わず、クロック タイムで演奏する。
DMUS_TRACKCONFIG_PLAY_COMPOSE
トラックが演奏を開始するたびに、データを再生成する。
DMUS_TRACKCONFIG_PLAY_ENABLED
トラックがメッセージを送信できるようにする。
DMUS_TRACKCONFIG_TRANS1_FROMSEGCURRENT
トランジションのアレンジで、先頭セグメントの現在の場所からトラック情報を取得する。
DMUS_TRACKCONFIG_TRANS1_FROMSEGSTART
トランジションのアレンジで、先頭セグメントの開始部分からトラック情報を取得する。
DMUS_TRACKCONFIG_TRANS1_TOSEGSTART
トランジションのアレンジで、2 番目のセグメントの開始部分からトラック情報を取得する。

次の表は、各標準トラックに対して有効な構成フラグを示している。

バンド
DMUS_TRACKCONFIG_CONTROL_ENABLED
DMUS_TRACKCONFIG_CONTROL_PLAY
DMUS_TRACKCONFIG_PLAY_CLOCKTIME
DMUS_TRACKCONFIG_PLAY_ENABLED
DMUS_TRACKCONFIG_TRANS1_FROMSEGCURRENT
DMUS_TRACKCONFIG_TRANS1_FROMSEGSTART
DMUS_TRACKCONFIG_TRANS1_TOSEGSTART

コード
DMUS_TRACKCONFIG_CONTROL_ENABLED
DMUS_TRACKCONFIG_CONTROL_NOTIFICATION
DMUS_TRACKCONFIG_NOTIFICATION_ENABLED
DMUS_TRACKCONFIG_TRANS1_FROMSEGCURRENT
DMUS_TRACKCONFIG_TRANS1_FROMSEGSTART
DMUS_TRACKCONFIG_TRANS1_TOSEGSTART

コードマップ
DMUS_TRACKCONFIG_CONTROL_ENABLED
DMUS_TRACKCONFIG_TRANS1_FROMSEGCURRENT
DMUS_TRACKCONFIG_TRANS1_FROMSEGSTART
DMUS_TRACKCONFIG_TRANS1_TOSEGSTART

コマンド
DMUS_TRACKCONFIG_CONTROL_ENABLED
DMUS_TRACKCONFIG_CONTROL_NOTIFICATION
DMUS_TRACKCONFIG_NOTIFICATION_ENABLED
DMUS_TRACKCONFIG_TRANS1_FROMSEGCURRENT
DMUS_TRACKCONFIG_TRANS1_FROMSEGSTART
DMUS_TRACKCONFIG_TRANS1_TOSEGSTART

歌詞
DMUS_TRACKCONFIG_PLAY_CLOCKTIME
DMUS_TRACKCONFIG_PLAY_ENABLED

マーカー
DMUS_TRACKCONFIG_CONTROL_ENABLED

メロディ編成。DirectX 8.0 では実装されていない。
DMUS_TRACKCONFIG_COMPOSING
DMUS_TRACKCONFIG_CONTROL_ENABLED
DMUS_TRACKCONFIG_CONTROL_NOTIFICATION
DMUS_TRACKCONFIG_CONTROL_PLAY
DMUS_TRACKCONFIG_LOOP_COMPOSE
DMUS_TRACKCONFIG_NOTIFICATION_ENABLED
DMUS_TRACKCONFIG_PLAY_COMPOSE
DMUS_TRACKCONFIG_PLAY_ENABLED
DMUS_TRACKCONFIG_TRANS1_FROMSEGCURRENT
DMUS_TRACKCONFIG_TRANS1_FROMSEGSTART
DMUS_TRACKCONFIG_TRANS1_TOSEGSTART

モチーフ
DMUS_TRACKCONFIG_CONTROL_ENABLED
DMUS_TRACKCONFIG_CONTROL_NOTIFICATION
DMUS_TRACKCONFIG_CONTROL_PLAY
DMUS_TRACKCONFIG_FALLBACK
DMUS_TRACKCONFIG_NOTIFICATION_ENABLED
DMUS_TRACKCONFIG_OVERRIDE_ALL
DMUS_TRACKCONFIG_OVERRIDE_PRIMARY
DMUS_TRACKCONFIG_PLAY_CLOCKTIME
DMUS_TRACKCONFIG_PLAY_ENABLED

ミュート
DMUS_TRACKCONFIG_CONTROL_ENABLED

パラメータ制御
DMUS_TRACKCONFIG_PLAY_CLOCKTIME
DMUS_TRACKCONFIG_PLAY_ENABLED

パターン
DMUS_TRACKCONFIG_CONTROL_ENABLED
DMUS_TRACKCONFIG_CONTROL_NOTIFICATION
DMUS_TRACKCONFIG_CONTROL_PLAY
DMUS_TRACKCONFIG_FALLBACK
DMUS_TRACKCONFIG_NOTIFICATION_ENABLED
DMUS_TRACKCONFIG_OVERRIDE_ALL
DMUS_TRACKCONFIG_OVERRIDE_PRIMARY
DMUS_TRACKCONFIG_PLAY_CLOCKTIME
DMUS_TRACKCONFIG_PLAY_ENABLED

スクリプト
DMUS_TRACKCONFIG_PLAY_CLOCKTIME
DMUS_TRACKCONFIG_PLAY_ENABLED

セグメント トリガ
DMUS_TRACKCONFIG_PLAY_CLOCKTIME
DMUS_TRACKCONFIG_PLAY_ENABLED

シーケンス
DMUS_TRACKCONFIG_CONTROL_PLAY
DMUS_TRACKCONFIG_FALLBACK
DMUS_TRACKCONFIG_OVERRIDE_ALL
DMUS_TRACKCONFIG_OVERRIDE_PRIMARY
DMUS_TRACKCONFIG_PLAY_CLOCKTIME
DMUS_TRACKCONFIG_PLAY_ENABLED

サインポスト
DMUS_TRACKCONFIG_COMPOSING
DMUS_TRACKCONFIG_CONTROL_NOTIFICATION
DMUS_TRACKCONFIG_CONTROL_PLAY
DMUS_TRACKCONFIG_LOOP_COMPOSE
DMUS_TRACKCONFIG_NOTIFICATION_ENABLED
DMUS_TRACKCONFIG_PLAY_COMPOSE
DMUS_TRACKCONFIG_PLAY_ENABLED
DMUS_TRACKCONFIG_TRANS1_FROMSEGCURRENT
DMUS_TRACKCONFIG_TRANS1_FROMSEGSTART
DMUS_TRACKCONFIG_TRANS1_TOSEGSTART

スタイル
DMUS_TRACKCONFIG_CONTROL_ENABLED
DMUS_TRACKCONFIG_CONTROL_NOTIFICATION
DMUS_TRACKCONFIG_CONTROL_PLAY
DMUS_TRACKCONFIG_FALLBACK
DMUS_TRACKCONFIG_NOTIFICATION_ENABLED
DMUS_TRACKCONFIG_OVERRIDE_ALL
DMUS_TRACKCONFIG_OVERRIDE_PRIMARY
DMUS_TRACKCONFIG_PLAY_ENABLED
DMUS_TRACKCONFIG_TRANS1_FROMSEGCURRENT
DMUS_TRACKCONFIG_TRANS1_FROMSEGSTART
DMUS_TRACKCONFIG_TRANS1_TOSEGSTART

システム エクスクルーシブ
DMUS_TRACKCONFIG_CONTROL_PLAY
DMUS_TRACKCONFIG_PLAY_CLOCKTIME
DMUS_TRACKCONFIG_PLAY_ENABLED

テンポ
DMUS_TRACKCONFIG_CONTROL_ENABLED
DMUS_TRACKCONFIG_CONTROL_PLAY
DMUS_TRACKCONFIG_PLAY_CLOCKTIME
DMUS_TRACKCONFIG_PLAY_ENABLED
DMUS_TRACKCONFIG_TRANS1_FROMSEGCURRENT
DMUS_TRACKCONFIG_TRANS1_FROMSEGSTART
DMUS_TRACKCONFIG_TRANS1_TOSEGSTART

拍子記号
DMUS_TRACKCONFIG_CONTROL_ENABLED
DMUS_TRACKCONFIG_CONTROL_NOTIFICATION
DMUS_TRACKCONFIG_CONTROL_PLAY
DMUS_TRACKCONFIG_NOTIFICATION_ENABLED
DMUS_TRACKCONFIG_PLAY_ENABLED

ウェーブ
DMUS_TRACKCONFIG_CONTROL_PLAY
DMUS_TRACKCONFIG_FALLBACK
DMUS_TRACKCONFIG_OVERRIDE_ALL
DMUS_TRACKCONFIG_OVERRIDE_PRIMARY
DMUS_TRACKCONFIG_PLAY_CLOCKTIME
DMUS_TRACKCONFIG_PLAY_ENABLED

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegmentState8::SetTrackConfig、自己制御セグメント、トラック構成


IDirectMusicSegment8::Unload

パフォーマンスやオーディオパスから音色データをアンロードする。

HRESULT Unload(
  IUnknown *pAudioPath
);

パラメータ

pAudioPath
音色データをアンロードする元である、パフォーマンスやオーディオパスの IUnknown インターフェイスへのポインタ。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_TRACK_NOT_FOUND
E_POINTER

注意

前にデータがダウンロードされていない場合でも、メソッドは成功する。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegment8::Download


IDirectMusicSegmentState8

IDirectMusicPerformance8::PlaySegment メソッドや IDirectMusicPerformance8::PlaySegmentEx メソッドを呼び出すと、パフォーマンス エンジンは演奏中のセグメント状態を追跡するセグメント状態オブジェクトを生成する。また、IDirectMusicSegmentState8 インターフェイスの形でセグメントへのハンドルをアプリケーションに提供する。このハンドルを使って、セグメントの再生ステータスを追跡できる。また、IDirectMusicPerformance8 の各メソッドと組み合わせることにより、セグメント再生の直接的な停止やパフォーマンスからのセグメントの削除にも利用できる。

IDirectMusicSegmentState8 は IDirectMusicSegmentState を引き継ぎ、新しいメソッドを追加する。

このインターフェイスは、以下のメソッドをサポートする。

情報 | GetObjectInPath
 | GetRepeats
 | GetSeek
 | GetSegment
 | GetStartPoint
 | GetStartTime
トラック構成 | SetTrackConfig

すべての COM インターフェイスは IUnknown インターフェイスのメソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicSegmentState8::GetObjectInPath

このセグメント状態が演奏されているオーディオパスに含まれるオブジェクトのインターフェイスを取得する。

HRESULT GetObjectInPath(
  DWORD dwPChannel,
  DWORD dwStage,
  DWORD dwBuffer,
  REFGUID guidObject,
  DWORD dwIndex,
  REFGUID iidInterface,
  void ** ppObject
);

パラメータ

dwPChannel
検索するパフォーマンス チャンネルまたはすべてのチャンネルを検索する DMUS_PCHANNEL_ALL。最初のチャンネルは 0 番になる。「注意」を参照すること。
dwStage
パスのステージ。次のいずれかの値を指定する。
DMUS_PATH_AUDIOPATH
セグメント状態が演奏されているオーディオパス。
DMUS_PATH_AUDIOPATH_GRAPH
オーディオパス ツールグラフ。存在しなければ作成される。
DMUS_PATH_AUDIOPATH_TOOL
オーディオパス ツールグラフ内のツール。
DMUS_PATH_BUFFER
DirectSound バッファ。
DMUS_PATH_BUFFER_DMO
バッファ内の DMO。DMO インターフェイスの詳細については、「IDirectSoundBuffer8::GetObjectInPath」を参照すること。
DMUS_PATH_MIXIN_BUFFER
グローバル ミックスイン バッファ。
DMUS_PATH_MIXIN_BUFFER_DMO
グローバル ミックスイン バッファ内の DMO。
DMUS_PATH_PERFORMANCE
パフォーマンス。
DMUS_PATH_PERFORMANCE_GRAPH
パフォーマンス ツールグラフ。存在しなければ作成される。
DMUS_PATH_PERFORMANCE_TOOL
パフォーマンス グラフ内のツール。
DMUS_PATH_PORT
シンセサイザ。
DMUS_PATH_PRIMARY_BUFFER
プライマリ バッファ。
DMUS_PATH_SEGMENT
セグメント状態を所有するセグメント。
DMUS_PATH_SEGMENT_GRAPH
セグメント ツールグラフ。存在しなければ作成される。「注意」を参照すること。
DMUS_PATH_SEGMENT_TOOL
セグメント グラフ内のツール。「注意」を参照すること。
DMUS_PATH_SEGMENT_TRACK
セグメント内のトラック。「注意」を参照すること。
dwBuffer
dwStage が DMUS_PATH_BUFFER_DMO または DMUS_PATH_MIXIN_BUFFER_DMO の場合は、DMO が常駐するバッファのインデックス。dwStage が DMUS_PATH_BUFFER または DMUS_PATH_MIXIN_BUFFER の場合は、バッファのインデックス。それ以外の場合は、0 でなければならない。
guidObject
オブジェクトのクラス識別子、または任意のクラスのオブジェクトを検索する GUID_All_Objects。dwStage によって指定されたステージに存在するオブジェクトが単一のクラスに限定されている場合は無視される。このパラメータは GUID_NULL に設定できる。
dwIndex
適合オブジェクトのリスト内のオブジェクトのインデックス。0 に設定して、最初の適合オブジェクトを検索する。dwStage が DMUS_PATH_BUFFER または DMUS_PATH_MIXIN_BUFFER の場合、このパラメータは無視され、dwBuffer によってバッファ インデックスが指定される。
iidInterface
IID_IDirectMusicGraph など、目的のインターフェイスの識別子。
ppObject
要求されたインターフェイスへのポインタを受け取る変数のアドレス。

戻り値

成功した場合は S_OK または DMUS_S_GARBAGE_COLLECTED を返す。「ガベージ コレクション」を参照すること。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_NOT_FOUND
E_INVALIDARG
E_NOINTERFACE
E_OUTOFMEMORY

注意

チャンネル固有でないステージについては、dwPChannel の値は 0 に設定しなければならない。次のステージのオブジェクトはチャンネル固有なので、dwPChannel にチャンネル番号または DMUS_PCHANNEL_ALL を設定して取得できる。

DMUS_PATH_AUDIOPATH_TOOL
DMUS_PATH_BUFFER
DMUS_PATH_BUFFER_DMO
DMUS_PATH_PERFORMANCE_TOOL
DMUS_PATH_PORT
DMUS_PATH_SEGMENT_TOOL

不必要なオブジェクトをフィルタリングによって除外するときのパラメータの優先順位は次のとおりである。

  1. dwStage。
  2. guidObject。この値が GUID_All_Objects でない場合、クラス識別子が guidObject に等しいオブジェクトだけが検索される。ただし、指定されたステージに存在できるオブジェクトのクラスが 1 つに限定されている場合、このパラメータは無視される。
  3. dwPChannel。ステージがチャンネル固有で、この値が DMUS_PCHANNEL_ALL でない場合、そのチャンネルのオブジェクトだけが検索される。
  4. dwBuffer。このパラメータが使用されるのは、dwStage が DMUS_PATH_BUFFER、DMUS_PATH_MIXIN_BUFFER、DMUS_PATH_BUFFER_DMO、または DMUS_PATH_MIXIN_BUFFER_DMO の場合だけである。
  5. dwIndex。DirectMusic Producer で作成するセグメントのトラックは、必ずしもアプリケーションと同じ順序である必要はない。ステージ DMUS_PATH_SEGMENT_TRACK では、特定のトラックの検索を dwIndex だけに頼らないこと。

一致するオブジェクトが見つかっても、iidInterface で指定されているインターフェイスが見つからない場合、このメソッドは失敗する。

dwStage に DMUS_PATH_SEGMENT_GRAPH または DMUS_PATH_SEGMENT_TOOL を指定する場合に返されるオブジェクトは、同じセグメントに基づく別のセグメント状態に返されるオブジェクトと同じではない可能性がある。セグメントが演奏される場合、そのツールグラフはコピーされ、IDirectMusicTool8::Clone メソッドをサポートするツールもすべてコピーされる。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicAudioPath8::GetObjectInPath、オーディオパスからのオブジェクトの取得


IDirectMusicSegmentState8::GetRepeats

セグメントのループ部分に設定された反復回数を取得する。

HRESULT GetRepeats(
  DWORD* pdwRepeats
);

パラメータ

pdwRepeats
反復回数を受け取る変数のアドレス。値 0 は、そのセグメント全体を 1 回だけ演奏し、反復する部分がないことを意味する。

戻り値

成功した場合は S_OK を返す。

失敗した場合は E_POINTER を返す。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegment8::SetRepeats


IDirectMusicSegmentState8::GetSeek

セグメント状態内のシーク ポインタを取得する。これは、次に IDirectMusicTrack8::Play メソッドを呼び出したときに渡される、mtStart パラメータの値である。この値はループと反復を考慮に入れていないため、セグメント状態全体が最初から反復される場合は、シーク ポインタは 0 にリセットされる。

HRESULT GetSeek(
  MUSIC_TIME* pmtSeek
);

パラメータ

pmtSeek
シーク ポインタを受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は E_POINTER を返す。

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicSegmentState8::GetSegment

このセグメント状態を保持するセグメントへのポインタを取得する。

HRESULT GetSegment(
  IDirectMusicSegment** ppSegment
);

パラメータ

ppSegment
IDirectMusicSegment インターフェイスへのポインタを受け取る変数のアドレス。IDirectMusicSegment8 インターフェイスを取得するには、QueryInterface を使用する。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_NOT_FOUND
E_POINTER

注意

ppSegment に返されるポインタは、アプリケーションが解放しなければならない。

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicSegmentState8::GetStartPoint

演奏の開始に使われる (または既に使われた) セグメントにオフセットを返す。

HRESULT GetStartPoint(
  MUSIC_TIME * pmtStart
);

パラメータ

pmtStart
セグメントの先頭から、最初に演奏された (またはこれから演奏される) セグメント状態までのオフセット (ミュージック タイム単位) を受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は E_POINTER を返す。

注意

開始ポイントは、聞くことのできるセグメントの最初のポイントである。ただし、セグメントの開始ポイントが経過時間に合わせてある場合、実際に聞こえる最初のポイントは、これより遅くなる。詳細については、「セグメントのタイミング」を参照すること。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegment8::SetStartPoint、IDirectMusicSegmentState8::GetStartTime


IDirectMusicSegmentState8::GetStartTime

セグメントの演奏が開始された、またはこれから開始される演奏タイムを取得する。

HRESULT GetStartTime(
  MUSIC_TIME* pmtStart
);

パラメータ

pmtStart
このセグメント状態に保存されているミュージック タイム単位のオフセットを受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は E_POINTER を返す。

注意

このメソッドによって取得するタイムは、セグメントの開始タイムがキューに入っているパフォーマンスでの、解決済みの演奏タイムである。詳細については、「セグメントのタイミング」を参照すること。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegment8::SetStartPoint、IDirectMusicSegment8::GetStartPoint、IDirectMusicSegmentState8::GetStartPoint


IDirectMusicSegmentState8::SetTrackConfig

トラックの構成を設定する。

HRESULT SetTrackConfig(
  REFGUID rguidTrackClassID,
  DWORD dwGroupBits,
  DWORD dwIndex,
  DWORD dwFlagsOn,
  DWORD dwFlagsOff
);

パラメータ

rguidTrackClassID
トラック クラスの識別子への参照 (C++) またはアドレス (C)。値のリストについては、「標準トラックの種類」を参照すること。
dwGroupBits
トラックが所属するグループ。
dwIndex
グループ内のトラックのインデックス、またはグループ内のすべてのトラックの構成を設定する DMUS_SEG_ALLTRACKS。
dwFlagsOn
設定する構成フラグ。値のリストについては、「IDirectMusicSegment8::SetTrackConfig」を参照すること。
dwFlagsOff
クリアする構成フラグ。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_TRACK_NOT_FOUND
E_INVALIDARG

注意

構成の変更は、準備時間後に有効になる。変更を即時に有効にするには、IDirectMusicPerformance8::Invalidate を呼び出す。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegment8::SetTrackConfig、自己制御セグメント、トラック構成


IDirectMusicSong8

DirectX 8.0 では実装されていない。

IDirectMusicSong8 インターフェイスは、ソングを表す。ソングとは、共通のソース素材に基づくセグメントのコレクションである。

このインターフェイスは、以下のメソッドをサポートする。

音色 | Download
 | Unload
セグメントの取得 | EnumSegment
 | GetSegment
その他 | Compose
 | GetAudioPathConfig
 | GetParam

すべての COM インターフェイスは IUnknown インターフェイスのメソッドを継承する。このインターフェイスは、次の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicSong8::Compose

DirectX 8.0 では実装されていない。

ソングのソース素材から演奏可能なセグメントを作成する。

HRESULT Compose();

パラメータ

なし。

戻り値

成功した場合は、次のいずれかのコードを返す。

S_OK | ソングがアレンジされた。
S_FALSE | アレンジするトラックがない。
DMUS_S_GARBAGE_COLLECTED | 「ガベージ コレクション」を参照すること。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_TRACK_NOT_FOUND
E_INVALIDARG
E_POINTER
E_OUTOFMEMORY

注意

このメソッドは、ソングの中からすべてのセグメント内のすべてのアレンジ トラックを検索し、同じ識別子とグループ ビットを持つトラックをマスタ アレンジ トラックにまとめる。次に、マスタ アレンジ トラックから優先順位に従って新しいトラックをアレンジし、これらの新しいトラックを元のトラックに対応するように分割する。そして、分割したアレンジ済みのトラックを、ソングのセグメントの適切な場所に挿入する。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegment8::Compose、IDirectMusicTrack8::Compose


IDirectMusicSong8::Download

DirectX 8.0 では実装されていない。

バンド データをパフォーマンスまたはオーディオパスにダウンロードする。

HRESULT Download(
  IUnknown *pAudioPath
);

パラメータ

pAudioPath
音色データを受け取るパフォーマンスやオーディオパスの IUnknown インターフェイスへのポインタ。

戻り値

成功した場合は S_OK または DMUS_S_PARTIALDOWNLOAD を返す詳細については、IDirectMusicBand8::Download の「注意」を参照すること。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_NOT_INIT
E_NOINTERFACE
E_OUTOFMEMORY
E_POINTER

注意

ソングのすべてのセグメント内のすべてのバンドがダウンロードされる。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSong8::Unload


IDirectMusicSong8::EnumSegment

DirectX 8.0 では実装されていない。

ソングを構成するセグメントの 1 つをインデックスで取得する。

HRESULT EnumSegment(
  DWORD dwIndex,
  IDirectMusicSegment **ppSegment
);

パラメータ

dwIndex
ソングのセグメントのインデックス。
ppSegment
一致するセグメントが見つかった場合、IDirectMusicSegment インターフェイス ポインタを受け取る変数のアドレス。IDirectMusicSegment8 を取得するには、QueryInterface を使用する。

戻り値

成功した場合は、次のいずれかのコードを返す。

S_OK | セグメントが列挙された。
S_FALSE | dwIndex にセグメントがない。
DMUS_S_GARBAGE_COLLECTED | 「ガベージ コレクション」を参照すること。

成功した場合は S_OK、dwIndex がソングのセグメントに一致しない場合は S_FALSE を返す。

失敗した場合は E_POINTER を返す。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSong8::GetSegment


IDirectMusicSong8::GetAudioPathConfig

DirectX 8.0 では実装されていない。

ソングのオーディオパス構成を表すオブジェクトを取得する。

HRESULT GetAudioPathConfig(
  IUnknown ** ppAudioPathConfig
);

パラメータ

ppAudioPathConfig
オーディオパス構成オブジェクトの IUnknown インターフェイスへのポインタを受け取る変数のアドレス。

戻り値

成功した場合は S_OK または DMUS_S_GARBAGE_COLLECTED を返す。「ガベージ コレクション」を参照すること。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_NO_AUDIOPATH_CONFIG
E_POINTER

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegment8::GetAudioPathConfig


IDirectMusicSong8::GetParam

DirectX 8.0 では実装されていない。

このソングのトラックからデータを取得する。

HRESULT GetParam(
  REFGUID rguidType,
  DWORD dwGroupBits,
  DWORD dwIndex,
  MUSIC_TIME mtTime,
  MUSIC_TIME* pmtNext,
  void* pParam
);

パラメータ

rguidType
取得されるデータ型の識別子への参照 (C++) またはアドレス (C)。「標準トラック パラメータ」を参照すること。
dwGroupBits
目的のトラックが置かれているグループ。すべてのグループを指定するには、この値を 0xFFFFFFFF に設定する。「注意」を参照すること。
dwIndex
データの取得に使われるグループ内で、トラックに割り当てられているインデックス。
mtTime
データを取得するタイム。パフォーマンス時間で指定する。
pmtNext
データが無効になるタイム (mtTime からの相対タイム) を受け取る変数のアドレス。この変数が値 0 を返した場合、データが常に有効になっているか、データが無効になるタイムが不明であることを意味する。この情報が不要な場合は、pmtNext を NULL に設定してもよい。
pParam
パラメータ データを受け取るバッファのアドレス。

戻り値

成功した場合は S_OK または DMUS_S_GARBAGE_COLLECTED を返す。「ガベージ コレクション」を参照すること。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_GET_UNSUPPORTED
DMUS_E_NOT_FOUND
DMUS_E_TRACK_NOT_FOUND
E_POINTER

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicSong8::GetSegment

DirectX 8.0 では実装されていない。

ソングを構成するセグメントの 1 つを名前で取得する。

HRESULT GetSegment(
  WCHAR pwzName,
  IDirectMusicSegment **ppSegment
);

パラメータ

pwzName
セグメントの名前。最初のセグメントを取得するには NULL を指定する。
ppSegment
一致するセグメントが見つかった場合、IDirectMusicSegment インターフェイス ポインタを受け取る変数のアドレス。IDirectMusicSegment8 を取得するには、QueryInterface を使用する。

戻り値

成功した場合は、次のいずれかのコードを返す。

S_OK | セグメントが取得された。
S_FALSE | pwzName がどのセグメントとも一致しない。
DMUS_S_GARBAGE_COLLECTED | 「ガベージ コレクション」を参照すること。

失敗した場合は E_POINTER を返す。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSong8::EnumSegment


IDirectMusicSong8::Unload

DirectX 8.0 では実装されていない。

オーディオパスから音色データをアンロードする。

HRESULT Unload(
  IUnknown *pAudioPath
);

パラメータ

pAudioPath
音色データをどこからアンロードするかを示す、オーディオパスの IUnknown インターフェイスへのポインタ。

戻り値

成功した場合は S_OK または DMUS_S_GARBAGE_COLLECTED を返す。「ガベージ コレクション」を参照すること。

失敗した場合は E_POINTER を返す。

動作環境

ヘッダー : dmusici.h で宣言。

注意

前にデータがダウンロードされていない場合でも、メソッドは成功する。

参照

IDirectMusicSong8::Download


IDirectMusicStyle8

IDirectMusicStyle8 インターフェイスは、スタイル オブジェクトへのアクセスを提供する。スタイル オブジェクトは、ミュージック パターンを演奏するときに必要になる情報をパフォーマンスに提供する。概要については、「スタイルの使い方」を参照すること。

スタイルには通常、バンドとモチーフが含まれるので、IDirectMusicStyle8 はこれらのオブジェクトにアクセスするためのメソッドを提供する。

DirectMusicStyle オブジェクトは、自らのデータをロードするために IDirectMusicObject8 と IPersistStream の各インターフェイスもサポートしている。

IDirectMusicStyle8 は IDirectMusicStyle インターフェイスを引き継ぎ、新しいメソッド EnumPattern を追加する。

IDirectMusicStyle8 インターフェイスのメソッドは、以下のグループにまとめることができる。

列挙 | EnumBand
 | EnumChordMap
 | EnumMotif
 | EnumPattern
情報 | GetBand
 | GetChordMap
 | GetDefaultBand
 | GetDefaultChordMap
 | GetEmbellishmentLength
 | GetMotif
 | GetTempo
 | GetTimeSignature

すべての COM インターフェイスは IUnknown インターフェイスのメソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicStyle8::EnumBand

指定のインデックス値に対応するバンド名を取得する。

HRESULT EnumBand(
  DWORD dwIndex,
  WCHAR * pwszName
);

パラメータ

dwIndex
スタイルのバンドリスト内の、0 から始まるインデックス。
pwszName
バンド名を受け取るバッファのアドレス。MAX_PATH のサイズを持つべきである。

戻り値

成功した場合は S_OK を返す。指定されたインデックス値を持つバンドがなければ S_FALSE、名前の長さの値が MAX_PATH より大きい場合は DMUS_S_STRING_TRUNCATED を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_TYPE_UNSUPPORTED
E_POINTER

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicStyle8::EnumChordMap

指定のインデックス値に対応するコード マップ名を取得する。

HRESULT EnumChordMap(
  DWORD dwIndex,
  WCHAR * pwszName
);

パラメータ

dwIndex
スタイルのコード マップ リスト内にある、コード マップの 0 から始まるインデックス。
pwszName
コード マップ名を受け取るバッファのアドレス。MAX_PATH のサイズを持つべきである。

戻り値

成功した場合は S_OK を返す。指定されたインデックス値を持つコード マップがなければ S_FALSE、名前の長さの値が MAX_PATH より大きい場合は DMUS_S_STRING_TRUNCATED を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_TYPE_UNSUPPORTED
E_POINTER

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicStyle8::EnumMotif

指定のインデックス値に対応するモチーフ名を取得する。

HRESULT EnumMotif(
  DWORD dwIndex,
  WCHAR* pwszName
);

パラメータ

dwIndex
スタイルのモチーフ リスト内の、0 から始まるインデックス。
pwszName
モチーフ名を受け取るバッファのアドレス。MAX_PATH のサイズを持つべきである。

戻り値

成功した場合は S_OK を返す。指定されたインデックス値を持つモチーフがなければ S_FALSE、モチーフ名の長さの値が MAX_PATH より大きい場合は DMUS_S_STRING_TRUNCATED を返す。

失敗した場合は E_POINTER を返す。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicStyle8::GetMotif、モチーフの使い方


IDirectMusicStyle8::EnumPattern

指定のインデックス値とタイプに対応するパターン名を取得する。この名前は IDirectMusicPatternTrack8::SetPatternByName メソッドに渡すことができる。

HRESULT EnumPattern(
  DWORD dwIndex,
  DWORD dwPatternType,
  WCHAR* pwszName
);

パラメータ

dwIndex
スタイルのパターン リスト内の、0 から始まるインデックス。
dwPatternType
パターンのタイプを指定する DMUS_STYLET_TYPES 列挙の 1 つ。
pwszName
パターン名を受け取るバッファのアドレス。MAX_PATH のサイズを持つべきである。

戻り値

成功した場合は S_OK を返す。指定されたインデックス値を持つパターンがなければ S_FALSE、パターン名の長さの値が MAX_PATH より大きい場合は DMUS_S_STRING_TRUNCATED を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_INVALIDARG
E_POINTER

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicStyle8::GetBand

指定されたバンドを取得する。

HRESULT GetBand(
  WCHAR* pwszName,
  IDirectMusicBand** ppBand
);

パラメータ

pwszName
取得されるバンドの名前。この名前は、スタイルの作成者によって割り当てられる。
ppBand
バンドの IDirectMusicBand8 インターフェイス ポインタを受け取る変数のアドレス。

戻り値

メソッドが成功し、バンドが返された場合は S_OK を返す。指定された名前に対応するバンドが存在しない場合は S_FALSE を返す。

失敗した場合は E_POINTER を返す。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicStyle8::GetDefaultBand、バンドの使い方


IDirectMusicStyle8::GetChordMap

指定されたコード マップを取得する。

HRESULT GetChordMap(
  WCHAR* pwszName,
  IDirectMusicChordMap** ppChordMap
);

パラメータ

pwszName
取得されるコード マップの名前。
ppChordMap
IDirectMusicChordMap8 インターフェイスへのポインタを受け取る変数のアドレス。

戻り値

メソッドが成功し、コード マップが返された場合は S_OK を返す。指定された名前に対応するコード マップが存在しない場合は S_FALSE を返す。

ppChordMap が有効なポインタではない場合は E_POINTER を返す。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicStyle8::GetDefaultChordMap、コードマップの使い方


IDirectMusicStyle8::GetDefaultBand

スタイルのデフォルトのバンドを取得する。

HRESULT GetDefaultBand(
  IDirectMusicBand ** ppBand
);

パラメータ

ppBand
デフォルト バンドの IDirectMusicBand8 インターフェイス ポインタを受け取る変数のアドレス。

戻り値

メソッドが成功し、バンドが返された場合は S_OK を返す。スタイルにデフォルトのバンドがない場合は S_FALSE を返す。

失敗した場合は E_POINTER を返す。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicStyle8::GetBand、バンドの使い方


IDirectMusicStyle8::GetDefaultChordMap

スタイルのデフォルトのコード マップを取得する。

HRESULT GetDefaultChordMap(
  IDirectMusicChordMap** ppChordMap
);

パラメータ

ppChordMap
IDirectMusicChordMap8 インターフェイスへのポインタを受け取る変数のアドレス。

戻り値

メソッドが成功し、コード マップが返された場合は S_OK を返す。スタイルにデフォルトのコード マップがない場合は S_FALSE を返す。

失敗した場合は E_POINTER を返す。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicStyle8::GetChordMap、コードマップの使い方


IDirectMusicStyle8::GetEmbellishmentLength

指定された装飾タイプとグルーブ レベルから、最短パターンの長さと最長パターンの長さを見つける。

HRESULT GetEmbellishmentLength(
  DWORD dwType,
  DWORD dwLevel,
  DWORD* pdwMin,
  DWORD* pdwMax
);

パラメータ

dwType
装飾タイプ。「DMUS_COMMANDT_TYPES」を参照すること。
dwLevel
1 ～ 100 の範囲のグルーブ レベル。dwType が DMUS_COMMANDT_GROOVE でない場合は無視される。
pdwMin
指定されたタイプとグルーブ レベルの最短パターンの長さ (小節単位) を受け取る変数のアドレス。
pdwMax
指定されたタイプとグルーブ レベルの最長パターンの長さ (小節単位) を受け取る変数のアドレス。

戻り値

成功した場合は S_OK または S_FALSE を返す。

失敗した場合は E_POINTER を返す。

注意

指定されたタイプとグルーブ レベルに対応するパターンが存在しない場合、戻り値は S_FALSE である。

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicStyle8::GetMotif

指定されたモチーフを含むセグメントを作成する。

HRESULT GetMotif(
  WCHAR* pwszName,
  IDirectMusicSegment** ppSegment
);

パラメータ

pwszName
取得されるモチーフの名前。
ppSegment
指定されたモチーフを含むセグメントへのポインタを受け取る変数のアドレス。

戻り値

成功した場合は S_OK または S_FALSEを返す。

失敗した場合は E_POINTER を返す。

注意

このメソッドは、pwszName に一致する名前を持つモチーフをスタイル リストから検索する。モチーフが見つかった場合、モチーフ トラックを含むセグメントが作成される。トラックは、スタイルをトラックの関連スタイル、モチーフをトラックのパターンとして参照する。

指定された名前を持つモチーフが存在しない場合、このメソッドは S_FALSE を返す。

動作環境

ヘッダー : dmusici.h で宣言。

参照

モチーフの使い方


IDirectMusicStyle8::GetTempo

スタイルの推奨テンポを取得する。

HRESULT GetTempo(
  double* pTempo
);

パラメータ

pTempo
スタイルの推奨テンポを受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

pTempo が有効なポインタではない場合は E_POINTER を返す。

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicStyle8::GetTimeSignature

スタイルの拍子記号を取得する。

HRESULT GetTimeSignature(
  DMUS_TIMESIGNATURE* pTimeSig
);

パラメータ

pTimeSig
データを受け取る DMUS_TIMESIGNATURE 構造体のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は E_POINTER を返す。

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicThru8

IDirectMusicThru8 インターフェイスは、ミュージック メッセージのキャプチャ ポートから別のポートへの転送をサポートする。このインターフェイスは、キャプチャ ポートの IDirectMusicPort8 インターフェイスに対して QueryInterface を呼び出すことによって取得される。具体的な例については、「IDirectMusicThru8::ThruChannel」の「注意」を参照すること。

IDirectMusicThru8 は、IDirectMusicThru の型定義である。これら 2 つのインターフェイス名は交換して使うことができる。

このインターフェイスは、以下のメソッドをサポートする。

IDirectMusicThru8 ThruChannel

すべての COM インターフェイスは IUnknown インターフェイスのメソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTMUSICTHRU8 型は、このインターフェイスへのポインタとして定義されている。

typedef IDirectMusicThru8 *LPDIRECTMUSICTHRU8;

動作環境

ヘッダー : dmusici.h で宣言。

参照

MIDI のキャプチャ


IDirectMusicThru8::ThruChannel

キャプチャ ポート上のチャンネルと別のポート上のチャンネル間での転送接続を確立または解除する。

HRESULT ThruChannel(
  DWORD dwSourceChannelGroup,
  DWORD dwSourceChannel,
  DWORD dwDestinationChannelGroup,
  DWORD dwDestinationChannel,
  LPDIRECTMUSICPORT pDestinationPort
);

パラメータ

dwSourceChannelGroup
キャプチャ ポート上のチャンネル グループ。この値は常に 1 である。
dwSourceChannel
ソース チャンネル。
dwDestinationChannelGroup
転送先ポート上のチャンネル グループ。
dwDestinationChannel
転送先チャンネル。
pDestinationPort
転送先チャンネルの IDirectMusicPort8 インターフェイスのアドレス。この値を NULL に設定すると、既存の転送接続が解除される。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_NOTIMPL
E_INVALIDARG
DMUS_E_PORT_NOT_RENDER

注意

システム エクスクルーシブ メッセージは、転送先ポートに送信されない。

Microsoft のソフトウェア シンセサイザまたは一定の遅延時間を持たないその他のシンセサイザへの転送は推奨されない。転送は、受信 MIDI イベントを受け取ると即座に行われる。ソフトウェア シンセサイザの遅延時間が比較的長いこと (ハードウェア ポートと比べた場合)、およびソフトウェア シンセサイザは複数のオーディオ ブロックを同時にレンダリングすることから、各イベントには演奏の前にわずかな遅延が発生する。この遅延の長さは、一定していない。このランダムなオフセットは、データの再生時にジッタとして発生する。その他のデバイス (MPU-401 ポートなど) の遅延時間はわずかであるため、ジッタは発生しない。

アプリケーションがソフトウェア シンセサイザに対してデータを転送する必要がある場合、受信ノート イベントのタイム スタンプにわずかなオフセットを追加して、シンセサイザのレンダリング遅延時間を補正しなければならない。

次のサンプル コードでは、IDirectMusicThru8 インターフェイスを取得し、キャプチャ ポートのグループ 1 上のすべてのチャンネルと、転送先ポート上の同等のチャンネルとの間で転送接続を確立する。

HRESULT SetupOneToOneThru(
    IDirectMusicPort8 *pCapturePort,
    IDirectMusicPort8 *pRenderPort)
{
    HRESULT hr;
    IDirectMusicThru8 *pThru;

    hr = pCapturePort->QueryInterface(IID_IDirectMusicThru8,
            (void**)&pThru);
    if (FAILED(hr))
        return hr;

    for (DWORD dwChannel = 0; dwChannel < 16; dwChannel++)
    {
        hr = pThru->ThruChannel(1, dwChannel,
            1, dwChannel, (IDirectMusicPort*)pRenderPort);
        if (FAILED(hr))
            break;
    }

    pThru->Release();
    return hr;
}

動作環境

ヘッダー : dmusici.h で宣言。


IDirectMusicTool8

IDirectMusicTool8 インターフェイスは、メッセージを処理するツール オブジェクトを表す。ツールはメッセージの変更、追加のメッセージの作成、メッセージの削除などを行える。

このインターフェイスは主に、独自のツールを作成することを考えている開発者によって利用される。このインターフェイスのメソッドは、ツールの設計者により実装され、多くの場合、パフォーマンスにより呼び出される。アプリケーションは、IDirectMusicGraph8::InsertTool を使ってメッセージ パスにツールを挿入するだけでよい。

IDirectMusicTool8 は IDirectMusicTool インターフェイスを引き継ぎ、新しいメソッドを追加する。

IDirectMusicTool8 インターフェイスのメソッドは、以下のグループにまとめることができる。

複製 | Clone
初期化 | Init
メッセージ管理 | Flush
 | GetMediaTypeArraySize
 | GetMediaTypes
 | GetMsgDeliveryType
 | ProcessPMsg

すべての COM インターフェイスは IUnknown インターフェイスのメソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

ヘッダー : dmplugin.h で宣言。

参照

メッセージの作成と配信、DirectMusic ツール


IDirectMusicTool8::Clone

ツールの新しいインスタンスを作成する。

HRESULT Clone(
  IDirectMusicTool** ppTool
);

パラメータ

ppTool
ツールの新しいインスタンスの IDirectMusicTool インターフェイスへのポインタを受け取る変数のアドレス。IDirectMusicTool8 を取得するには、QueryInterface を使用する。

戻り値

戻り値は実装によって決まる。成功した場合は S_OK を返す。失敗した場合は、E_POINTER または E_OUTOFMEMORY を返す。

動作環境

ヘッダー : dmplugin.h で宣言。


IDirectMusicTool8::Flush

パフォーマンスが停止したときに、キューからメッセージをフラッシュ (解放) するツールはこのメソッドを使って、メッセージのフラッシュ (解放) に必要なあらゆることを行える。たとえば、出力ツールはこのメソッドを使って、保留されているあらゆるノートオフ メッセージが即座に処理されるようにする。

HRESULT Flush(
  IDirectMusicPerformance* pPerf,
  DMUS_PMSG* pPMSG,
  REFERENCE_TIME rtTime
);

パラメータ

pPerf
IDirectMusicPerformance8 インターフェイスのアドレス。
pPMSG
フラッシュされるメッセージ。
rtTime
フラッシュを行うタイム。

戻り値

戻り値は実装によって決まる。成功した場合は、次のいずれかを返す。

DMUS_S_REQUEUE
DMUS_S_FREE
S_OK

失敗した場合は E_POINTER を返す。

注意

メッセージは自らの dwFlags メンバに DMUS_PMSGF_TOOL_FLUSH を設定する。「DMUS_PMSG」を参照すること。

メソッドが DMUS_S_REQUEUE を返した場合は、指定されたメッセージをツールがもう一度キューに入れようとしていることを意味する。この結果、ツールはメッセージに新しいタイム スタンプとパラメータを書き込んでもう一度キューに入れるか、メッセージにほかの配信タイプを割り当ててもう一度キューに入れられる。

戻り値が DMUS_S_FREE の場合、ツールはメッセージを自動的に解放しようとしており、メッセージをもう一度キューに入れる必要はないことを意味する。

戻り値が S_OK の場合、ツールはメッセージを自動的に解放しようとはしていない。何らかの理由でツールはメッセージを保持しているか、既に自ら解放したと考えられる。

pPerf によって表されるパフォーマンスへの循環参照は作成しないこと。詳細については、「DirectMusic ツール」を参照すること。

動作環境

ヘッダー : dmplugin.h で宣言。


IDirectMusicTool8::GetMediaTypeArraySize

IDirectMusicTool8::GetMediaTypes メソッドに渡さなければならない配列のサイズを取得する。値として 0 が返された場合、そのツールはすべてのタイプを処理するので、GetMediaTypes を呼び出す必要がないことを意味する。

HRESULT GetMediaTypeArraySize(
  DWORD* pdwNumElements
);

パラメータ

pdwNumElements
メディア タイプの数を受け取る変数のアドレス。このフィールドに 0 が返された場合、すべてのタイプがサポートされている。

戻り値

戻り値は実装によって決まる。成功した場合は S_OK を返す。失敗した場合は E_POINTER を返す。

動作環境

ヘッダー : dmplugin.h で宣言。


IDirectMusicTool8::GetMediaTypes

このツールがサポートするメッセージ タイプのリストを取得する。

HRESULT GetMediaTypes(
  DWORD** padwMediaTypes,
  DWORD dwNumElements
);

パラメータ

padwMediaTypes
DWORD の配列のアドレス。このメソッドは、ツールがサポートしているメディア タイプをこの配列に書き込む。メディア タイプについては、「DMUS_PMSGT_TYPES」を参照すること。
dwNumElements
padwMediaTypes 配列内の要素の数。この値は、IDirectMusicTool8::GetMediaTypeArraySize メソッドが返した数と一致しているべきである。dwNumElements の値がこの数より小さい場合、メソッドはサポートされているすべてのメッセージ タイプを返せない。値がこの数より大きい場合、配列内の余分の要素は 0 に設定される。

戻り値

戻り値は実装によって決まる。成功した場合は S_OK を返す。dwNumElements が小さすぎてすべての値を書き込めなかった場合は S_FALSE を返す。失敗した場合は、次のいずれかのエラー値を返す。

E_POINTER
E_INVALIDARG
E_NOTIMPL

注意

メソッドが E_NOTIMPL を返す場合、ツールはすべてのメディア タイプを処理する。

動作環境

ヘッダー : dmplugin.h で宣言。


IDirectMusicTool8::GetMsgDeliveryType

メッセージをツールに配信する時期を決定するツールの配信タイプを取得する。

HRESULT GetMsgDeliveryType(
  DWORD* pdwDeliveryType
);

パラメータ

pdwDeliveryType
配信タイプを受け取る変数のアドレス。返される値は、DMUS_PMSGF_TOOL_IMMEDIATE、DMUS_PMSGF_TOOL_QUEUE、DMUS_PMSGF_TOOL_ATTIME のいずれかでなければならない。*pdwDeliveryType の値が認識されない場合、グラフによって DMUS_PMSGF_TOOL_IMMEDIATE として扱われる。

戻り値

戻り値は実装によって決まる。成功した場合は S_OK を返す。失敗した場合は E_POINTER を返す。

注意

配信メカニズムの概要については、「メッセージの作成と配信」を参照すること。

動作環境

ヘッダー : dmplugin.h で宣言。


IDirectMusicTool8::Init

ツールを初期化する。このメソッドは、ツールをグラフに挿入したときに呼び出され、ツールが必要な初期化を行うための機会を提供する。

HRESULT Init(
  IDirectMusicGraph* pGraph
);

パラメータ

pGraph
呼び出し中のグラフ。

戻り値

戻り値は実装によって決まる。成功した場合は S_OK を返す。失敗した場合は、次のいずれかのエラー値を返す。

E_FAIL
E_NOTIMPL

注意

ツールは複数のグラフに挿入できるため、このメソッドは複数の呼び出しに対して問題なく対処できなければならない。

pGraph によって表されるパフォーマンスへの循環参照は作成しないこと。詳細については、「DirectMusic ツール」を参照すること。

動作環境

ヘッダー : dmplugin.h で宣言。

参照

IDirectMusicGraph8::InsertTool


IDirectMusicTool8::ProcessPMsg

ツールの主要なタスクを実行する。このメソッドは、IDirectMusicTool8::GetMediaTypes によって指定されるタイプと一致するすべてのメッセージに対して、パフォーマンスのリアルタイム スレッドの内部から呼び出される。

HRESULT ProcessPMsg(
  IDirectMusicPerformance* pPerf,
  DMUS_PMSG* pPMSG
);

パラメータ

pPerf
メッセージを生成しているパフォーマンス。
pPMSG
処理されるメッセージ。

戻り値

戻り値は実装によって決まる。成功した場合は、次のいずれかを返す。

DMUS_S_REQUEUE
DMUS_S_FREE
S_OK

失敗した場合は E_POINTER を返す。

注意

メソッドが DMUS_S_REQUEUE を返した場合は、指定されたメッセージをツールがもう一度キューに入れようとしていることを意味する。この結果、ツールはメッセージに新しいタイム スタンプとパラメータを書き込んでもう一度キューに入れるか、メッセージにほかの配信タイプを割り当ててもう一度キューに入れられる。

戻り値が DMUS_S_FREE の場合、ツールはメッセージを自動的に解放しようとしており、メッセージをもう一度キューに入れる必要はないことを意味する。

戻り値が S_OK の場合、ツールはメッセージを自動的に解放しようとはしていない。何らかの理由でツールはメッセージを保持しているか、既に自ら解放したと考えられる。

ツールは時間のかかる操作を実行してはならない。もしそうした場合、パフォーマンス全体に大きな影響を及ぼすためである。また、pPerf によって表されるパフォーマンスへの循環参照は作成しないこと。詳細については、「DirectMusic ツール」を参照すること。

動作環境

ヘッダー : dmplugin.h で宣言。

参照

IDirectMusicPerformance8::SendPMsg、メッセージ、メッセージの作成と配信


IDirectMusicTrack8

IDirectMusicTrack8 インターフェイスは、トラック オブジェクトを表す。セグメントの定義に関係のあるほとんどすべての内容がトラックに保存されている。このトラック メカニズムによって、セグメントは無限に拡張可能であり、セグメントは自ら使用する音楽やオーディオのテクノロジに関して何も把握していなくてもかまわない。

独自の音楽再生メカニズムを DirectMusic に実装することを計画している場合、そのメカニズムを表す DirectMusicTrack オブジェクトを作成する必要がある。DirectMusicTrack オブジェクトを作成しなかった場合、このインターフェイスのメソッドは通常、アプリケーションから直接呼び出されない。

IDirectMusicTrack8 は IDirectMusicTrack インターフェイスを引き継ぎ、新しいメソッドを追加する。

注 IDirectMusicTrack8 インターフェイスのメソッドを実装するときは、渡されるオブジェクトへの参照を保持しないこと。たとえば、IDirectMusicTrack8::Init がパラメータとして受け取る IDirectMusicSegment インターフェイスへの参照を追加する場合は、この参照が解放されるようにする。

IDirectMusicTrack8 インターフェイスには次のメソッドがある。

作成 | Clone
 | Compose
 | Join
初期化 | Init
通知 | AddNotificationType
 | RemoveNotificationType
パラメータ | GetParam
 | GetParamEx
 | IsParamSupported
 | SetParam
 | SetParamEx
再生 | EndPlay
 | InitPlay
 | Play
 | PlayEx

すべての COM インターフェイスは IUnknown インターフェイスのメソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

DirectMusicTrack オブジェクトは、自らのデータをロードするために IDirectMusicObject8 と IPersistStream の各インターフェイスもサポートしている。

動作環境

ヘッダー : dmplugin.h で宣言。

参照

DirectMusic トラック、トラック パラメータの設定と取得


IDirectMusicTrack8::AddNotificationType

トラックへのイベント通知を可能にする。IDirectMusicSegment8::AddNotificationType メソッドに似ていて、このメソッドから呼び出される。

HRESULT AddNotificationType(
  REFGUID rguidNotificationType
);

パラメータ

rguidNotificationType
追加される通知タイプの識別子への参照 (C++) またはアドレス (C)。定義済みのタイプについては、「DMUS_NOTIFICATION_PMSG」を参照すること。アプリケーションは、カスタム トラックについて独自のタイプを定義できる。

戻り値

成功した場合は S_OK を返す。トラックが通知タイプをサポートしない場合は S_FALSE を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_NOT_INIT
E_NOTIMPL

注意

トラックが通知をサポートしない場合は、E_NOTIMPL を返す。モチーフまたはスタイル トラックは、初期化されていない場合は DMUS_E_NOT_INIT を返す。

動作環境

ヘッダー : dmplugin.h で宣言。

参照

IDirectMusicTrack8::RemoveNotificationType、通知とイベントの処理


IDirectMusicTrack8::Clone

トラックのコピーを作成する。

HRESULT Clone(
  MUSIC_TIME mtStart,
  MUSIC_TIME mtEnd,
  IDirectMusicTrack** ppTrack
 );

パラメータ

mtStart
コピー開始パート。0 以上、かつトラックの長さ未満の値とすべきである。
mtEnd
コピー終了パート。mtStart より大きく、トラックの長さ未満の値とすべきである。
ppTrack
メソッドが成功した場合は、作成されたトラックへのポインタを受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_FAIL
E_INVALIDARG
E_OUTOFMEMORY
E_POINTER

注意

アプリケーションは、トラックの終了時に Release を呼び出さなければならない。

動作環境

ヘッダー : dmplugin.h で宣言。


IDirectMusicTrack8::Compose

セグメントのデータに基づいて、トラックを再アレンジする。DirectMusic はサインポスト トラックにこのメソッドを実装して、コート ドラックをアレンジする。

HRESULT Compose(
  IUnknown* pContext,
  DWORD dwTrackGroup,
  IDirectMusicTrack** ppResultTrack
 );

パラメータ

pContext
アレンジに使用するオブジェクトの IUnknown インターフェイス ポインタ。これは通常、このトラックを所有するセグメントである。
dwTrackGroup
トラックに対してグループを指定する DWORD 値。グループ ビットの詳細については、「トラックの識別」を参照すること。
ppResultTrack
アレンジ済みトラックの IDirectMusicTrack インターフェイスを受け取る変数のアドレス。QueryInterface を使用して、IDirectMusicTrack8 を取得する。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_INVALIDARG
E_POINTER

動作環境

ヘッダー : dmplugin.h で宣言。

参照

IDirectMusicSegment8::Compose


IDirectMusicTrack8::EndPlay

IDirectMusicTrack8::InitPlay を初めに呼び出したオブジェクトを削除するときに呼び出される。

HRESULT EndPlay(
  void * pStateData
);

パラメータ

pStateData
IDirectMusicTrack8::InitPlay から返される状態データへのポインタ。このデータは EndPlay メソッドで解放しなければならない。

戻り値

成功した場合は S_OK を返す。

失敗した場合は E_POINTER を返す。

動作環境

ヘッダー : dmplugin.h で宣言。


IDirectMusicTrack8::GetParam

トラックからデータをミュージック タイムで取得する。

HRESULT GetParam(
  REFGUID rguidType,
  MUSIC_TIME mtTime,
  MUSIC_TIME* pmtNext,
  void* pParam
);

パラメータ

rguidType
取得されるデータ型の識別子への参照 (C++) またはアドレス (C)。「標準トラック パラメータ」を参照すること。
mtTime
データを取得するタイム。トラック時間で指定する。
pmtNext
データが無効になるタイムを受け取る変数のアドレス。この変数が値 0 を返した場合、データが常に有効になっているか、データが無効になるタイムが不明であることを意味する。この情報が不要な場合は、pmtNext を NULL に設定してもよい。
pParam
返されるデータの保存用に割り当てられた構造体のアドレス。返されるデータの保存用に割り当てられた構造体のアドレス。この構造体は、rguidType で識別されたデータ型にとって適切な種類とサイズを備えていなければならない。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_NOT_FOUND
DMUS_E_NOT_INIT
DMUS_E_TYPE_DISABLED
DMUS_E_GET_UNSUPPORTED
E_POINTER

注意

より強い機能が必要な場合には、IDirectMusicTrack8::GetParamEx メソッドを使用できる。

動作環境

ヘッダー : dmplugin.h で宣言。

参照

IDirectMusicTrack8::SetParam、IDirectMusicTrack8::IsParamSupported、IDirectMusicPerformance8::GetParam、IDirectMusicSegment8::GetParam、パフォーマンス パラメータ


IDirectMusicTrack8::GetParamEx

トラックからデータを、ミュージック タイムまたは基準タイムで取得する。

HRESULT GetParamEx(
  REFGUID rguidType,
  REFERENCE_TIME rtTime,
  REFERENCE_TIME* prtNext,
  void * pParam
  void * pStateData,
  DWORD dwFlags
);

パラメータ

rguidType
取得されるデータ型の識別子への参照 (C++) またはアドレス (C)。「標準トラック パラメータ」を参照すること。
rtTime
データの取得を行うタイム。dwFlags に DMUS_TRACK_PARAMF_CLOCK が設定されていない場合、この値はミュージック タイムで取得される。
prtNext
データが無効になるタイムを受け取る変数のアドレス。この変数が値 0 を返した場合、データが常に有効になっているか、データが無効になるタイムが不明であることを意味する。この情報が不要な場合は、prtNext を NULL に設定してもよい。
pParam
返されるデータの保存用に割り当てられた構造体のアドレス。返されるデータの保存用に割り当てられた構造体のアドレス。この構造体は、rguidType で識別されたデータ型にとって適切な種類とサイズを備えていなければならない。
pStateData
トラック インスタンスの状態データを保持するバッファのアドレス。IDirectMusicTrack8::InitPlay から取得される。
dwFlags
0 または次のフラグを指定する。
DMUS_TRACK_PARAMF_CLOCK
rtTime の値は、クロック タイムで表される。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_NOT_FOUND
DMUS_E_NOT_INIT
DMUS_E_TYPE_DISABLED
DMUS_E_GET_UNSUPPORTED
DMUS_E_TRACK_NO_CLOCKTIME_SUPPORT
E_POINTER

動作環境

ヘッダー : dmplugin.h で宣言。

参照

IDirectMusicTrack8::GetParam、IDirectMusicTrack8::SetParamEx


IDirectMusicTrack8::Init

トラックを初期化する。トラックの追加時にセグメントにより呼び出される。

HRESULT Init(
  IDirectMusicSegment* pSegment
);

パラメータ

pSegment
このトラックが所属するセグメント。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_NOT_INIT
E_OUTOFMEMORY
E_POINTER

注意

トラックがメッセージを演奏する場合、Init メソッド内で IDirectMusicSegment8::SetPChannelsUsed を呼び出すべきである。

トラックがセグメントに挿入された後で、トラック データに変化があれば、このメソッドを必ず呼び出すようにする。

動作環境

ヘッダー : dmplugin.h で宣言。


IDirectMusicTrack8::InitPlay

トラックが演奏を開始する準備ができたときに呼び出される。このメソッドは、状態データへのポインタを返す。

HRESULT InitPlay(
  IDirectMusicSegmentState* pSegmentState,
  IDirectMusicPerformance* pPerformance,
  void** ppStateData,
  DWORD dwVirtualTrackID,
  DWORD dwFlags
);

パラメータ

pSegmentState
呼び出し元の IDirectMusicSegmentState または IDirectMusicSegmentState8 インターフェイスのアドレス。
pPerformance
呼び出し元の IDirectMusicPerformance または IDirectMusicPerformance8 インターフェイスのアドレス。
ppStateData
状態情報へのポインタを受け取るための変数のアドレス。データのフォーマットと使用方法は、トラックに固有である。データは InitPlay メソッドで作成し、IDirectMusicTrack8::EndPlay メソッドで解放しなければならない。ポインタは、IDirectMusicTrack8::Play メソッドと IDirectMusicTrack8::PlayEx メソッドに渡される。
dwVirtualTrackID
このトラック インスタンスに割り当てられた仮想トラック ID。
dwFlags
トラックの動作を制御する DMUS_SEGF_FLAGS。「注意」を参照すること。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_NOT_INIT
E_OUTOFMEMORY
E_POINTER

注意

dwFlags パラメータは、IDirectMusicPerformance8::PlaySegment または IDirectMusicPerformance8::PlaySegmentEx の呼び出しでパフォーマンスに渡されたフラグを渡す。トラックは、DMUS_SEGF_CONTROL と DMUS_SEGF_SECONDARY の各フラグに基づいて、その実行方法を決定する。たとえば、テンポ トラックは、それ自体がプライマリ セグメントまたはセカンダリ制御セグメントのパートである場合に限り、テンポの変更を自動的に演奏する (DMUS_SEGF_SECONDARY が設定されていない、または DMUS_SEGF_CONTROL が設定されている)。

トラックは ppStateData で NULL を返す場合がある。

動作環境

ヘッダー : dmplugin.h で宣言。


IDirectMusicTrack8::IsParamSupported

IDirectMusicTrack8::GetParam メソッドと IDirectMusicTrack8::SetParam メソッドで指定されたデータ型をサポートしているかどうかを判断する。

HRESULT IsParamSupported(
  REFGUID rguidType
);

パラメータ

rguidType
データ型の識別子への参照 (C++) またはアドレス (C)。「標準トラック パラメータ」を参照すること。

戻り値

メソッドが成功し、タイプがサポートされている場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_TYPE_DISABLED
DMUS_E_TYPE_UNSUPPORTED
E_POINTER
E_NOTIMPL

注意

SetParam メソッドのいずれかを使うことによってパラメータが無効になっている場合、IDirectMusicTrack8::IsParamSupported メソッドは、対応するパラメータ タイプ (GUID_TempoParam または GUID_TimeSignature) を渡されたときに DMUS_E_TYPE_DISABLED を返す。

このメソッドは、GUID_DisableTempo を渡され、そのパラメータが既に無効になっている場合、または GUID_EnableTempo を渡され、そのパラメータが現在有効になっている場合にも、DMUS_E_TYPE_DISABLED を返す。このことは、GUID_DisableTimeSig と GUID_EnableTimeSig にも当てはまる。

GUID_EnableTempo、GUID_EnableTimeSig、GUID_DisableTempo、または GUID_DisableTimeSig の各パラメータの呼び出しによって参照されるパラメータをトラックがサポートしない場合、このメソッドは DMUS_E_TYPE_UNSUPPORTED を返す。

動作環境

ヘッダー : dmplugin.h で宣言。

参照

IDirectMusicTrack8::GetParam、IDirectMusicTrack8::SetParam、パフォーマンス パラメータ


IDirectMusicTrack8::Join

トラックを別のトラックの末尾に付加する。

HRESULT Join(
  IDirectMusicTrack* pNewTrack,
  MUSIC_TIME mtJoin,
  IUnknown* pContext,
  DWORD dwTrackGroup,
  IDirectMusicTrack** ppResultTrack)
);

パラメータ

pNewTrack
このトラックの後に付加するトラックを指定する IDirectMusicTrack8 インターフェイスへのポインタ。
mtJoin
pNewTrack を開始する、このトラックでのタイム。
pContext
コンテキスト セグメントの IUnknown インターフェイス ポインタ。このオブジェクトから、サインポスト トラックなど、小節や拍を使用するトラックの拍子記号が決定される。
dwTrackGroup
新しいトラックが属する、1 つまたは複数のグループ。詳細については、「IDirectMusicSegment8::InsertTrack」および「トラックの識別」を参照すること。
ppResultTrack
連結済みトラックの IDirectMusicTrack インターフェイスを受け取る変数のアドレス。QueryInterface を使用して、IDirectMusicTrack8 を取得する。NULL の場合、新しいトラックは作成されず、現在のトラックが連結済みトラックとなる。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_POINTER
E_INVALIDARG
E_OUTOFMEMORY

注意

このメソッドは、バンド、コード マップ、テンポ、スタイル、コード、サインポスト、およびコマンドの各トラックでサポートされる。

動作環境

ヘッダー : dmplugin.h で宣言。


IDirectMusicTrack8::Play

トラックの演奏を行う。このメソッドは、メッセージの作成と送信など、セグメントの演奏時にトラックが行う必要のある任意の操作を実行する。

HRESULT Play(
  void* pStateData,
  MUSIC_TIME mtStart,
  MUSIC_TIME mtEnd,
  MUSIC_TIME mtOffset
  DWORD dwFlags,
  IDirectMusicPerformance* pPerf,
  IDirectMusicSegmentState* pSegSt,
  DWORD dwVirtualID
);

パラメータ

pStateData
IDirectMusicTrack8::InitPlay メソッドが返した状態データへのポインタ。データのフォーマットと使用方法は、トラックに固有である。
mtStart
開始タイム。
mtEnd
終了タイム。
mtOffset
IDirectMusicPerformance8::SendPMsg に渡されるすべてのメッセージに追加されるオフセット。
dwFlags
この呼び出しの状態を示すフラグ。「DMUS_TRACKF_FLAGS」を参照すること。値 0 は、Play の呼び出しによって、再生が前の呼び出しから継続されることを意味する。
pPerf
メッセージの割り当てと送信に使用されるパフォーマンス。
pSegSt
このトラックが所属するセグメント状態。IDirectMusicSegmentState8:: QueryInterface メソッドは、IDirectMusicGraph8::StampPMsg を呼び出す場合など、IDirectMusicGraph8 インターフェイスを取得するために呼び出すことができる。
dwVirtualID
トラックの仮想識別子。IDirectMusicPerformance8::SendPMsg から渡されるすべてのメッセージの dwVirtualTrackID メンバ (「DMUS_PMSG」を参照) にこの値を書き込まなければならない。

戻り値

成功した場合は S_OK または DMUS_S_END を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_NOT_INIT
E_POINTER

注意

トラックが空の場合、このメソッドは DMUS_S_END を返す。

トラックは、優先順位が中低度のスレッド内にメッセージを生成する。ファイルのデータをストリーム化するコードなど、時間のかかる関数を、トラックの Play メソッド内から呼び出すことができる。ただし、安全なマルチスレッド化のためのガイドラインに従うこと。

動作環境

ヘッダー : dmplugin.h で宣言。

参照

IDirectMusicTrack8::PlayEx


IDirectMusicTrack8::PlayEx

トラックの演奏をクロック タイムで行う。このメソッドは、メッセージの作成と送信など、セグメントの演奏時にトラックが行う必要のある任意の操作を実行する。

HRESULT PlayEx(
  void* pStateData,
  REFERENCE_TIME rtStart,
  REFERENCE_TIME rtEnd,
  REFERENCE_TIME rtOffset,
  DWORD dwFlags,
  IDirectMusicPerformance* pPerf,
  IDirectMusicSegmentState* pSegSt,
  DWORD dwVirtualID
);

パラメータ

pStateData
IDirectMusicTrack8::InitPlay メソッドが返した状態データへのポインタ。データのフォーマットと使用方法は、トラックに固有である。
rtStart
開始タイム。
rtEnd
終了タイム。
rtOffset
IDirectMusicPerformance8::SendPMsg に渡されるすべてのメッセージに追加されるオフセット。
dwFlags
この呼び出しの状態を示すフラグ。「DMUS_TRACKF_FLAGS」を参照すること。値 0 は、PlayEx の呼び出しによって、再生が前の呼び出しから継続されることを意味する。
pPerf
メッセージの割り当てと送信に使用されるパフォーマンス。
pSegSt
このトラックが所属するセグメント状態。IDirectMusicSegmentState8:: QueryInterface メソッドは、IDirectMusicGraph8::StampPMsg を呼び出す場合など、IDirectMusicGraph8 インターフェイスを取得するために呼び出すことができる。
dwVirtualID
トラックの仮想識別子。IDirectMusicPerformance8::SendPMsg から渡されるすべてのメッセージの dwVirtualTrackID メンバ (「DMUS_PMSG」を参照) にこの値を書き込まなければならない。

戻り値

成功した場合は S_OK または DMUS_S_END を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_NOT_INIT
E_POINTER

動作環境

ヘッダー : dmplugin.h で宣言。

参照

IDirectMusicTrack8::Play


IDirectMusicTrack8::RemoveNotificationType

トラックからのイベント通知を削除する。IDirectMusicSegment8::RemoveNotificationType に似ていて、このメソッドから呼び出される。

HRESULT RemoveNotificationType(
  REFGUID rguidNotificationType
);

パラメータ

rguidNotificationType
削除される通知タイプの識別子への参照 (C++) またはアドレス (C)。定義済みのタイプについては、「DMUS_NOTIFICATION_PMSG」を参照すること。

戻り値

成功した場合は S_OK を返す。トラックが通知タイプをサポートしない場合は S_FALSE を返す。

トラックが通知をサポートしない場合は、E_NOTIMPL を返す。

動作環境

ヘッダー : dmplugin.h で宣言。

参照

IDirectMusicTrack8::AddNotificationType、通知とイベントの処理


IDirectMusicTrack8::SetParam

データをトラックにミュージック タイムで設定する。

HRESULT SetParam(
  REFGUID rguidType,
  MUSIC_TIME mtTime,
  void* pParam
);

パラメータ

rguidType
設定されるデータ型の識別子への参照 (C++) またはアドレス (C)。「標準トラック パラメータ」を参照すること。
mtTime
データを設定するタイム。トラック時間で指定する。
pParam
データを保持する構造体のアドレス。データが必要ない場合は NULL を指定する。この構造体は、rguidType で識別されたデータ型にとって適切な種類とサイズを備えていなければならない。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_SET_UNSUPPORTED
DMUS_E_TYPE_DISABLED
E_OUTOFMEMORY
E_POINTER

注意

より強い機能が必要な場合には、IDirectMusicTrack8::SetParamEx メソッドを使用できる。

動作環境

ヘッダー : dmplugin.h で宣言。

参照

IDirectMusicTrack8::GetParam、IDirectMusicTrack8::IsParamSupported、IDirectMusicPerformance8::SetParam、IDirectMusicSegment8::SetParam、トラック パラメータの設定と取得


IDirectMusicTrack8::SetParamEx

データをトラックに、クロック タイムかミュージック タイムで設定する。

HRESULT SetParamEx(
  REFGUID rguidType,
  REFERENCE_TIME rtTime,
  void* pParam,
  void * pStateData,
  DWORD dwFlags
 );

パラメータ

rguidType
設定されるデータ型の識別子への参照 (C++) またはアドレス (C)。「標準トラック パラメータ」を参照すること。
rtTime
データの設定を行うタイム。dwFlags に DMUS_TRACK_PARAMF_CLOCK が設定されていない場合、これはミュージック タイムである。
pParam
データを保持する構造体のアドレス。データが必要ない場合は NULL を指定する。この構造体は、rguidType で識別されたデータ型にとって適切な種類とサイズを備えていなければならない。
pStateData
トラックの状態データを保持するバッファへのポインタ。
dwFlags
0 または次のフラグを指定する。
DMUS_TRACK_PARAMF_CLOCK
rtTime の値は、クロック タイムで表される。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_SET_UNSUPPORTED
DMUS_E_TYPE_DISABLED
E_OUTOFMEMORY
E_POINTER

動作環境

ヘッダー : dmplugin.h で宣言。

参照

IDirectMusicTrack8::GetParamEx、IDirectMusicTrack8::SetParam


IKsControl

IKsControl インターフェイスは、プロパティ、イベント、およびメソッドのサポートを取得、設定、または問い合わせるために使われる。このインターフェイスは、Windows ドライバ モデル カーネル ストリーミング アーキテクチャの一部であるが、DirectMusic によっても使用され、DirectMusic ポートのプロパティを公開する。このインターフェイスを取得するには、riid パラメータに IID_IKsControl を指定して IDirectMusicPort8::QueryInterface メソッドを呼び出す。

プロパティ項目の要求をポートに対して送信する作業は、ポートの実装に依存する。Win32 ハンドルベースのマルチメディア呼び出し (midiOut と midiIn の各関数) を利用して DirectMusic のエミュレーションを行っているポートは、どのプロパティをもサポートしない。

プラグ可能なソフトウェア シンセサイザを表すポートに対してプロパティ項目を要求すると、完全にユーザー モードで応答がなされる。このタイプのポートのトポロジは、シンク ノード (IDirectMusicSynthSinkインターフェイス) に接続されたシンセサイザ (IDirectMusicSynthインターフェイスによって表される) である。このプロパティ要求は最初にシンセサイザ ノードに割り当てられ、シンセサイザがこの要求を認識しない場合はシンク ノードに割り当てられる。

このインターフェイスは、以下のメソッドをサポートする。現在のところ、KsProperty だけが DirectMusic によってサポートされている。

IKsControl | KsProperty
 | KsEvent
 | KsMethod

すべての COM インターフェイスは IUnknown インターフェイスのメソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

ヘッダー : dmksctrl.h で宣言。

参照

DirectMusic ポートのプロパティ セット


IKsControl::KsProperty

プロパティの値を取得または設定する。概要については、「DirectMusic ポートのプロパティ セット」を参照すること。

HRESULT KsProperty(
  PKSPROPERTY pProperty,
  ULONG ulPropertyLength,
  LPVOID pvPropertyData,
  ULONG ulDataLength,
  PULONG pulBytesReturned
);

パラメータ

pProperty
プロパティ セット、項目、実行する操作を指定する KSPROPERTY 構造体のアドレス。このプロパティにインスタンス データが含まれる場合、そのデータはメモリ内で構造体のすぐ後に置かれていなければならない。
ulPropertyLength
pProperty が指すメモリの長さ。任意のインスタンス データも含む。
pvPropertyData
設定操作の場合、プロパティの新しい値を表すデータを含むメモリ バッファのアドレス。取得操作の場合、プロパティの値を十分に保持できるメモリのアドレス。基本的なサポートの問い合わせの場合、サイズが最低でも DWORD のバッファのアドレス。
ulDataLength
pvPropertyData が指すバッファの長さ。
pulBytesReturned
KSPROPERTY_TYPE_GET または KSPROPERTY_TYPE_BASICSUPPORT の呼び出しで、ポートによって pvPropertyData に返されるバイト数を受け取る変数のアドレス。

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_FAIL
E_INVALIDARG
E_NOTIMPL
E_OUTOFMEMORY
E_POINTER
DMUS_E_UNKNOWN_PROPERTY

動作環境

ヘッダー : dmksctrl.h で宣言。

参照

DirectMusic ポートのプロパティ セット


IReferenceClock

IReferenceClock インターフェイスは、システム基準タイムを表す。DirectMusic マスタ クロックとポートの遅延時間クロックは、このインターフェイスを実装する。

このインターフェイスは、以下のメソッドをサポートする。

IReferenceClock | GetTime
 | AdviseTime
 | AdvisePeriodic
 | Unadvise

すべての COM インターフェイスは IUnknown インターフェイスのメソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

ヘッダー : dmusicc.h で宣言。

参照

IDirectMusic8::GetMasterClock、IDirectMusicPort8::GetLatencyClock、タイミング


IReferenceClock::AdvisePeriodic

持続時間が経過したことを示す、非同期の定期的な通知を要求する。

HRESULT AdvisePeriodic(
  REFERENCE_TIME rtStartTime,
  REFERENCE_TIME rtPeriodTime,
  HANDLE hSemaphore,
  DWORD * pdwAdviseCookie
);

パラメータ

rtStartTime
通知が開始されるタイム。
rtPeriodTime
通知が行われる間隔。
hSemaphore
アドバイスを行うための手段となるセマフォのハンドル。
pdwAdviseCookie
要求の識別子を受け取る変数のアドレス。これを使って、将来、要求をキャンセルする場合などに、AdvisePeriodic の呼び出しを識別する。

戻り値

戻り値は実装によって決まる。成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_FAIL
E_POINTER
E_INVALIDARG
E_NOTIMPL

注意

rtStartTime によって示されるタイムに達した場合、ハンドルが hSemaphore として設定されているセマフォが解放される。それ以降、セマフォは rtPeriodTime の期間を使って反復的に解放される。

動作環境

ヘッダー : dmusicc.h で宣言。

参照

IReferenceClock::Unadvise


IReferenceClock::AdviseTime

時間が経過したことを示す、非同期の通知を要求する。

HRESULT AdviseTime(
  REFERENCE_TIME rtBaseTime,
  REFERENCE_TIME rtStreamTime,
  HANDLE hEvent,
  DWORD * pdwAdviseCookie
);

パラメータ

rtBaseTime
基本となる基準タイム。
rtStreamTime
ストリーム オフセット タイム。
hEvent
アドバイスを行うための手段となるイベントのハンドル。
pdwAdviseCookie
要求の識別子を受け取る変数のアドレス。これを使って、将来、要求をキャンセルする場合などに、AdviseTime の呼び出しを識別する。

戻り値

戻り値は実装によって決まる。成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_FAIL
E_POINTER
E_INVALIDARG
E_NOTIMPL

注意

rtBaseTime と rtStreamTime を足したタイムに達すると、ハンドルが hEvent のイベントが設定される。タイムが既に経過している場合、イベントは即座に設定される。

動作環境

ヘッダー : dmusicc.h で宣言。

参照

IReferenceClock::Unadvise


IReferenceClock::GetTime

現在のタイムを取得する。

HRESULT GetTime(
  REFERENCE_TIME * pTime
);

パラメータ

pTime
現在のタイムを受け取る変数のアドレス。

戻り値

戻り値は実装によって決まる。成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_FAIL
E_POINTER
E_INVALIDARG
E_NOTIMPL

動作環境

ヘッダー : dmusicc.h で宣言。


IReferenceClock::Unadvise

通知の要求をキャンセルする。

HRESULT Unadvise(
  DWORD dwAdviseCookie
);

パラメータ

dwAdviseCookie
IReferenceClock::AdviseTime メソッドまたは IReferenceClock::AdvisePeriodic メソッドで設定されている、キャンセルする要求の識別子。

戻り値

戻り値は実装によって決まる。成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_FAIL
E_POINTER
E_INVALIDARG
E_NOTIMPL

動作環境

ヘッダー : dmusicc.h で宣言。


DirectMusic メッセージ

DirectMusic のメッセージ構造体は、いずれも DMUS_PMSG 構造体に基づいている。C は継承をサポートしていないので、この構造体のメンバは DMUS_PMSG_PART マクロとしての各派生構造体に含まれる。

メッセージの概要については、「DirectMusic メッセージの使い方」を参照すること。

ここでは、メッセージ情報の保持に使用される以下の構造体について説明する。

  • DMUS_PMSG
  • DMUS_CHANNEL_PRIORITY_PMSG
  • DMUS_CURVE_PMSG
  • DMUS_LYRIC_PMSG
  • DMUS_MIDI_PMSG
  • DMUS_NOTE_PMSG
  • DMUS_NOTIFICATION_PMSG
  • DMUS_PATCH_PMSG
  • DMUS_SYSEX_PMSG
  • DMUS_TEMPO_PMSG
  • DMUS_TIMESIG_PMSG
  • DMUS_TRANSPOSE_PMSG
  • DMUS_WAVE_PMSG

参照

IDirectMusicPerformance8::AllocPMsg、IDirectMusicPerformance8::SendPMsg、IDirectMusicPerformance8::FreePMsg、IDirectMusicTool8::ProcessPMsg


DMUS_PMSG

すべての DirectMusic メッセージに共通する情報を保持する。C は継承をサポートしていないので、次の構文に展開される DMUS_PMSG_PART マクロを含めることにより、この構造体のメンバはすべてのメッセージ タイプ (DMUS_PMSG 自体を含む) に含まれる。

typedef struct DMUS_PMSG {
    DWORD              dwSize;
    REFERENCE_TIME     rtTime;
    MUSIC_TIME         mtTime;
    DWORD              dwFlags;
    DWORD              dwPChannel;
    DWORD              dwVirtualTrackID;
    IDirectMusicTool*  pTool;
    IDirectMusicGraph* pGraph;
    DWORD              dwType;
    DWORD              dwVoiceID;
    DWORD              dwGroupID;
    IUnknown*          punkUser;
} DMUS_PMSG;
dwSize
構造体のサイズ。バイト単位で指定する。このメンバは、IDirectMusicPerformance8::AllocPMsg で初期化される。
rtTime
メッセージの演奏を開始する基準タイム。dwFlags により変更される。DMUS_PMSGF_REFTIME が dwFlags 内にある場合にのみ使用される。
mtTime
メッセージの演奏を開始するミュージック タイム。dwFlags によって変更される。DMUS_PMSGF_MUSICTIME が dwFlags 内にある場合にのみ使用される。
dwFlags
DMUS_PMSGF_FLAGS 列挙型または DMUS_TIME_RESOLVE_FLAGS 列挙型のフラグ。DMUS_PMSGF_REFTIME または DMUS_PMSGF_MUSICTIME を保持していなければならない。
dwPChannel
パフォーマンス チャンネル (P チャンネル)。IDirectMusicPerformance8::PChannelInfo メソッドを使って、この値からポート、チャンネル グループ、および MIDI チャンネルを派生できる。テンポ メッセージなど、チャンネル固有ではないメッセージについては、この値を 0 に設定する。メッセージを複数のチャンネルに送信するには、次のいずれかの値を使用する。
DMUS_PCHANNEL_BROADCAST_AUDIOPATH
メッセージのコピーをオーディオパスのすべてのチャンネルに送信する。
DMUS_PCHANNEL_BROADCAST_GROUPS
メッセージのコピーをパフォーマンス内のそれぞれのチャンネル グループに送信する。システム エクスクルーシブ メッセージなど、メッセージを各チャンネル グループに一度だけ送信する必要がある場合に使用する。
DMUS_PCHANNEL_BROADCAST_PERFORMANCE
メッセージのコピーをパフォーマンスのすべてのチャンネルに送信する。
DMUS_PCHANNEL_BROADCAST_SEGMENT
メッセージのコピーをセグメントのすべてのチャンネルに送信する。
dwVirtualTrackID
トラックの識別子。メッセージがトラックによって送信されていない場合は、0 に設定する。
pTool
ツール インターフェイスのアドレス。IDirectMusicGraph8::StampPMsg を使用して設定できる。メッセージが出力ツール以外のツールに送られない場合は NULL に設定できる。
pGraph
ツール グラフ インターフェイスのアドレス。IDirectMusicGraph8::StampPMsg を使用して設定できる。メッセージが出力ツール以外のツールに送られない場合は NULL に設定できる。
dwType
メッセージ タイプ (「DMUS_PMSGT_TYPES」を参照)。
dwVoiceID
予約済み。0 でなければならない。
dwGroupID
メッセージがトラックによって生成されている場合、そのメッセージが所属するトラック グループまたはグループの識別子 (トラックは、IDirectMusicSegment8::InsertTrack メソッドでグループに割り当てられる)。ほとんどの目的について、この値は 0xFFFFFFF でもよい。
punkUser
アプリケーションによって提供される IUnknown インターフェイスのアドレス。このポインタは、メッセージを解放したときに常に解放される。アプリケーションでオブジェクトを保持する場合は、メッセージを解放する前に、AddRef を呼び出さなければならない。メッセージが COM ポインタを必要としない場合、この値は NULL でもよい。

注意

DMUS_PMSG 構造体は、dwType メンバに以下の値を保持するメッセージについて、それ自体によって使われる。

DMUS_PMSGT_STOP
このタイプのメッセージを送信すると、指定されたタイムにパフォーマンスが停止する。
DMUS_PMSGT_DIRTY
制御セグメントが開始または終了するとき、セグメントおよびパフォーマンス グラフ内のすべてのツールは、このタイプのメッセージを受け取る。これは、セグメント内のすべてのツールとパフォーマンス グラフが、パラメータ取得メソッドの呼び出しでデータをキャッシングする場合、同じメソッドを再度呼び出して、それぞれのデータを更新しなければならないことを意味する。このメッセージ タイプが必要なツールは、IDirectMusicTool8::GetMediaTypes の呼び出しでこれを指定しなければならない。パフォーマンス グラフ内のツールは、パフォーマンス内の各セグメントについて、メッセージのコピーを 1 部だけ受け取る。このようなツールは、同じタイム スタンプの付いた余分なメッセージを無視しても安全である。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::SendPMsg


DMUS_CHANNEL_PRIORITY_PMSG

チャンネル優先順位変更に関するメッセージ データを保持する。

typedef struct _DMUS_CHANNEL_PRIORITY_PMSG {
    DMUS_PMSG_PART
    DWORD dwChannelPriority;
} DMUS_CHANNEL_PRIORITY_PMSG;
DMUS_PMSG_PART
共通のメッセージ メンバに展開されるマクロ。「DMUS_PMSG」を参照すること。
dwChannelPriority
チャンネルの優先順位。定義済みの値のリストについては、「IDirectMusicPort8::GetChannelPriority」の「注意」を参照すること。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPort8::SetChannelPriority、IDirectMusicPerformance8::SendPMsg


DMUS_CURVE_PMSG

カーブのメッセージ データを保持する。

typedef struct DMUS_CURVE_PMSG {
    DMUS_PMSG_PART
    MUSIC_TIME mtDuration;
    MUSIC_TIME mtOriginalStart;
    MUSIC_TIME mtResetDuration;
    short      nStartValue;
    short      nEndValue;
    short      nResetValue;
    WORD       wMeasure;
    short      nOffset;
    BYTE       bBeat;
    BYTE       bGrid;
    BYTE       bType;
    BYTE       bCurveShape;
    BYTE       bCCData;
    BYTE       bFlags;
    WORD       wParamType;
    WORD       wMergeIndex;
} DMUS_CURVE_PMSG;
DMUS_PMSG_PART
共通のメッセージ メンバに展開されるマクロ。「DMUS_PMSG」を参照すること。
mtDuration
カーブの持続時間。この値は、DMUS_PMSG_PART の dwFlags メンバに DMUS_PMSGF_LOCKTOREFTIME が存在する場合を除き、ミュージック タイムで指定する。この場合の単位はミリ秒単位となり、テンポの変化によって影響を受けることはない。
mtOriginalStart
オリジナルの開始タイム。メッセージを作成するときは 0 またはカーブのオリジナルの開始タイムに設定しなければならない。
mtResetDuration
無効化に応答してリセットできる間のカーブの終わり後の時間の長さ。bFlags 内に DMUS_CURVE_RESET がない場合は無視される。この値は、DMUS_PMSG_PART の dwFlags メンバに DMUS_PMSGF_LOCKTOREFTIME が存在する場合を除き、ミュージック タイムで指定する。この場合の単位はミリ秒単位となり、テンポの変化によって影響を受けることはない。
nStartValue
カーブの開始値。
nEndValue
カーブの終了値。
nResetValue
フラッシュ (解放) または無効化を設定する値。bFlags 内に DMUS_CURVE_RESET がない場合は無視される。
wMeasure
カーブが発生する小節。
nOffset
カーブが発生するグリッドからのオフセット。ミュージック タイムで表される。
bBeat
このカーブが発生する (小節内の) 拍数。
bGrid
このカーブが発生する拍からのグリッド オフセット。
bType
カーブのタイプ。次のいずれかの値を指定できる。
DMUS_CURVET_CCCURVE
コンティニュアス コントローラ カーブ (MIDI Control Change チャンネル ボイス メッセージ。ステータス バイトは &HBn)。
DMUS_CURVET_MATCURVE
モノラル アフタータッチ カーブ (MIDI Channel Pressure チャンネル ボイス メッセージ。ステータス バイトは &HDn)。
DMUS_CURVET_PATCURVE
ポリフォニック アフタータッチ カーブ (MIDI Poly Key Pressure チャンネル ボイス メッセージ。ステータス バイトは &HDn)。
DMUS_CURVET_PBCURVE
ピッチベンド カーブ (MIDI Pitch Bend チャンネル ボイス メッセージ。ステータス バイトは &HEn)。
DMUS_CURVET_RPNCURVE
wParamType に定義されたタイプの RPN カーブ。
DMUS_CURVET_NRPNCURVE
wParamType に定義されたタイプの NRPN カーブ。
bCurveShape
カーブのシェイプ。次のいずれかの値を指定できる。
DMUS_CURVES_EXP
指数カーブシェイプ。
DMUS_CURVES_INSTANT
即時カーブシェイプ (カーブの開始と終了がほとんど同時に発生する)。
DMUS_CURVES_LINEAR
線状カーブシェイプ。
DMUS_CURVES_LOG
対数カーブシェイプ。
DMUS_CURVES_SINE
正弦カーブシェイプ。
bCCData
bType が DMUS_CURVET_CCCURVE の場合はコントローラ番号。
bFlags
0 または次の 1 つ以上の値を指定できる。
DMUS_CURVE_RESET
デフォルトのタイムに達したとき、またはトランジションが原因で無効化が発生したときは、nResetValue にこの値を設定しなければならない。フラグが設定されていない場合、カーブは新しい値に永続的にとどまる。
DMUS_CURVE_START_FROM_CURRENT
nStartValue を無視し、現在の値のカーブを開始する。ボリューム、エクスプレッション、ピッチ ベンド、フィルタ カットオフ、パン、およびモッド ホイール用に実装される。「注意」を参照すること。
wParamType
MIDI パラメータ番号。DMUS_PMSGF_DX8 がこの構造体の DMUS_PMSG 部分の dwFlags メンバの中に存在する場合のみ、この値は意味を持つ。「注意」を参照すること。
wMergeIndex
マージ インデックス。ピッチ ベンド、ボリューム、およびエクスプレッション コントローラ用にサポートされる。DMUS_PMSGF_DX8 がこの構造体の DMUS_PMSG 部分の dwFlags メンバの中に存在する場合のみ、この値は意味を持つ。「注意」を参照すること。

注意

wParamType の RPN または NRPN カーブ タイプは、7 ビットを付加した 2 バイトとして格納される。たとえば、MSB が 0x23、LSB が 0x74 である場合、wParamType の値は 0x2374 である。

nStartValue、nEndValue、および nResetValue 内のデータは 14 ビットに制限される。7 ビットのバイト 2 つで構成される MIDI データの場合、値は空いている 2 ビットを付加して、1 ワードとして格納される。

wMergeIndex に 0 が設定されたすべてのカーブは、相互にオーバーライドされる。wMergeIndex が別の値である場合、カーブが生成する値はマージ インデックス 0 の値に追加される。たとえば、アプリケーションが 0 と 3 のカーブを使用する場合、0 カーブは常に相互に入れ替わるが 3 カーブに追加される。また、3 カーブも常に相互に入れ替わるが 0 カーブに追加される。

DMUS_CURVE_START_FROM_CURRENT フラグは現在のコントローラ値をメッセージに保存しない。したがって、ツールで最終認識値を格納しない限り、ツールにこのデータへのアクセス権はない。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::SendPMsg、カーブ


DMUS_LYRIC_PMSG

文字列のメッセージ データを保持する。

typedef struct _DMUS_LYRIC_PMSG {
    DMUS_PMSG_PART
    WCHAR  wszString[1];
} DMUS_LYRIC_PMSG;
DMUS_PMSG_PART
共通のメッセージ メンバに展開されるマクロ。「DMUS_PMSG」を参照すること。
wszString
NULL で終了する Unicode 文字列。メッセージの作成時に、配列のサイズが設定される。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::SendPMsg


DMUS_MIDI_PMSG

コントロール チェンジやピッチ ベンドなど、スタンダード MIDI メッセージのデータを保持する。

typedef struct DMUS_MIDI_PMSGG {
    DMUS_PMSG_PART
    BYTE  bStatus;
    BYTE  bByte1;
    BYTE  bByte2;
    BYTE  bPad[1];
} DMUS_MIDI_PMSG;
DMUS_PMSG_PART
共通のメッセージ メンバに展開されるマクロ。「DMUS_PMSG」を参照すること。
bStatus
スタンダード MIDI のステータス バイト。
bByte1
MIDI メッセージの最初の 1 バイト。これを必要としない MIDI メッセージでは無視される。
bByte2
MIDI メッセージの 2 バイト目。これを必要としない MIDI メッセージでは無視される。
bPad
WORD 境界までの追加。

動作環境

ヘッダー : dmusici.h で宣言。

参照

MIDI メッセージ、IDirectMusicPerformance8::SendPMsg


DMUS_NOTE_PMSG

MIDI ノートのメッセージ データを保持する。

typedef struct DMUS_NOTE_PMSG {
    DMUS_PMSG_PART
    MUSIC_TIME mtDuration;
    WORD       wMusicValue;
    WORD       wMeasure;
    short      nOffset;
    BYTE       bBeat;
    BYTE       bGrid;
    BYTE       bVelocity;
    BYTE       bFlags;
    BYTE       bTimeRange;
    BYTE       bDurRange;
    BYTE       bVelRange;
    BYTE       bPlayModeFlags;
    BYTE       bSubChordLevel;
    BYTE       bMidiValue;
    char       cTranspose;
} DMUS_NOTE_PMSG;
DMUS_PMSG_PART
共通のメッセージ メンバに展開されるマクロ。「DMUS_PMSG」を参照すること。
mtDuration
ノートの持続時間。
wMusicValue
ノートの記述。ほとんどの演奏モードでは、以下に示すように、パックされた 4 ビット値の配列である。
Octave
－ 2 ～ 14 の範囲。このノートは、1 オクターブの 12 倍で上下に転置される。
Chord position
0 ～ 15 の範囲だが、3 を超えてはならない。コード内の最初の位置は 0 である。
Scale position
0 ～ 15 の範囲。通常は 0 ～ 2 の範囲だが、1 ノートのコードにし、コードの上のすべてをスケール位置として解釈することも可能。
Accidental
－ 8 ～ 7 の範囲だが、通常は － 2 ～ 2 の範囲。これは、スケールからノートを取り出すオフセットを表す。

固定演奏モードでは、ミュージック値は 0 ～ 127 の範囲にある MIDI ノートの値である。

wMeasure
ノートが発生する小節。
nOffset
ノートが発生するグリッドからのオフセット。ミュージック タイムで表される。
bBeat
このノートが発生する (小節内での) 拍。
bGrid
このノートが発生する拍からのグリッド オフセット。
bVelocity
ノートのベロシティ。
bFlags
「DMUS_NOTEF_FLAGS」を参照すること。
bTimeRange
ランダム時間の範囲。
bDurRange
持続時間をランダム化する範囲。
bVelRange
ベロシティをランダム化する範囲。
bPlayModeFlags
ミュージック値がコードとサブコードにどのように関連するかを決定する演奏モード。値のリストについては、「DMUS_PLAYMODE_FLAGS」を参照すること。
bSubChordLevel
ノートが使うサブコード レベル。「DMUS_SUBCHORD」を参照すること。
bMidiValue
wMusicValue から変換された、MIDI ノートの値。
cTranspose
wMusicValue からの変換後に bMidiValue に追加する転調。

注意

出力ツールが bFlags の DMUS_NOTEF_NOTEON でメッセージを受け取る場合は、MIDI ノートオン メッセージがシンセサイザに送られる。次に DMUS_NOTEF_NOTEON フラグを消去し、タイム スタンプに mtDuration を加え、メッセージを要求する。その結果、適切なタイムにノートは終了する。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::SendPMsg、ミュージック値と MIDI ノート


DMUS_NOTIFICATION_PMSG

通知のメッセージ データを保持する。

typedef struct DMUS_NOTIFICATION_PMSG {
    DMUS_PMSG_PART
    GUID   guidNotificationType;
    DWORD  dwNotificationOption;
    DWORD  dwField1;
    DWORD  dwField2;
} DMUS_NOTIFICATION_PMSG;
DMUS_PMSG_PART
共通のメッセージ メンバに展開されるマクロ。「DMUS_PMSG」を参照すること。
guidNotificationType
通知タイプの識別子。次のタイプが定義されている。
GUID_NOTIFICATION_CHORD
コード チェンジ。
GUID_NOTIFICATION_COMMAND
コマンド イベント。
GUID_NOTIFICATION_MEASUREANDBEAT
小節および拍イベント。
GUID_NOTIFICATION_PERFORMANCE
パフォーマンス イベント。dwNotificationOption でさらに定義される。
GUID_NOTIFICATION_RECOMPOSE
トラックは再アレンジされた。現在のバージョンでは、これは常にコード トラックである。
GUID_NOTIFICATION_SEGMENT
セグメント イベント。dwNotificationOption でさらに定義される。
dwNotificationOption
通知サブタイプの識別子。

通知タイプが GUID_NOTIFICATION_SEGMENT の場合、このメンバは次のいずれかの値を保持する。

DMUS_NOTIFICATION_SEGABORT
セグメントが途中で停止した。またはプライマリ セグメントのキューから削除された。
DMUS_NOTIFICATION_SEGALMOSTEND
セグメントが終了タイムから準備時間を引いたタイムに達した。
DMUS_NOTIFICATION_SEGEND
セグメントが終了した。
DMUS_NOTIFICATION_SEGLOOP
セグメントがループした。
DMUS_NOTIFICATION_SEGSTART
セグメントが開始した。

通知タイプが GUID_NOTIFICATION_COMMAND の場合、このメンバは次のいずれかの値を保持する。

DMUS_NOTIFICATION_GROOVE
グルーブ レベルが変化する。
DMUS_NOTIFICATION_EMBELLISHMENT
装飾コマンド (イントロ、フィル、ブレーク、またはエンド)。

通知タイプが GUID_NOTIFICATION_PERFORMANCE の場合、このメンバは次のいずれかの値を保持する。

DMUS_NOTIFICATION_MUSICALMOSTEND
現在再生中のプライマリ セグメントが、終了タイムから準備時間を引いたタイムに達したが、キューにはもう再生するプライマリ セグメントはない。
DMUS_NOTIFICATION_MUSICSTARTED
再生が開始した。
DMUS_NOTIFICATION_MUSICSTOPPED
再生が停止した。

通知タイプが GUID_NOTIFICATION_MEASUREANDBEAT の場合、このメンバは DMUS_NOTIFICATION_MEASUREBEAT を保持する。その他のサブタイプは定義されない。

通知タイプが GUID_NOTIFICATION_CHORD の場合、このメンバは DMUS_NOTIFICATION_CHORD を保持する。その他のサブタイプは定義されない。

通知タイプが GUID_NOTIFICATION_RECOMPOSE の場合、このメンバは DMUS_NOTIFICATION_RECOMPOSE を保持する。その他のサブタイプは定義されない。

dwField1
通知タイプに固有の追加データ。GUID_NOTIFICATION_MEASUREANDBEAT 通知の場合、このメンバは小節内の拍番号を返す。
dwField2
通知タイプに固有の追加データ。将来の使用またはアプリケーションによって定義される使用に備えて予約されている。

注意

ほとんどの通知について、punkUser メンバ (「DMUS_PMSG」を参照) は、セグメント状態の IUnknown ポインタを保持する。これは、コードおよびコマンドの取得に使用すると非常に便利である。その場合、IDirectMusicSegmentState8 インターフェイスを照会し、IDirectMusicSegmentState8::GetSegment を呼び出して IDirectMusicSegment8 ポインタを取得する。次に、IDirectMusicSegment8::GetParam メソッドを呼び出して、通知メッセージの mtTime メンバで指定されたタイムにコードまたはコマンドを取得する。

GUID_NOTIFICATION_PERFORMANCE タイプの通知の場合、punkUser メンバは常に NULL である。

アプリケーションは独自の通知メッセージ タイプおよびサブタイプを定義でき、それでは不足のデータについては dwField1 と dwField2 を使用できる。そのようなカスタム通知メッセージは、その他のメッセージと同様に、割り当ておよび送信できる。アプリケーションによって定義されたトラックは、GUID (guidNotificationType) が IDirectMusicTrack8::AddNotificationType に渡された後に、特定タイプのメッセージを送信できる。

動作環境

ヘッダー : dmusici.h で宣言。

参照

通知とイベントの処理、IDirectMusicPerformance8::SendPMsg


DMUS_PATCH_PMSG

MIDI プログラム チェンジのメッセージ データを保持する。

typedef struct DMUS_PATCH_PMSG {
    DMUS_PMSG_PART
    BYTE  byInstrument;
    BYTE  byMSB;
    BYTE  byLSB;
    BYTE  byPad[1];
} DMUS_PATCH_PMSG;
DMUS_PMSG_PART
共通のメッセージ メンバに展開されるマクロ。「DMUS_PMSG」を参照すること。
byInstrument
音色のパッチ番号。
byMSB
バンク セレクトの上位バイト。
byLSB
バンク セレクトの下位バイト。
byPad
WORD 境界までの追加。この値は無視される。

動作環境

ヘッダー : dmusici.h で宣言。

参照

DMUS_MIDI_PMSG、IDirectMusicPerformance8::SendPMsg、MIDI メッセージ


DMUS_SYSEX_PMSG

MIDI システム エクスクルーシブ メッセージのデータを保持する。

typedef struct DMUS_SYSEX_PMSG {
    DMUS_PMSG_PART
    DWORD dwLen;
    BYTE  abData[1];
} DMUS_SYSEX_PMSG;
DMUS_PMSG_PART
共通のメッセージ メンバに展開されるマクロ。「DMUS_PMSG」を参照すること。
dwLen
データの長さ。バイト単位で指定する。
abData
データ配列。メモリの割り当て方法およびデータをこのメンバにコピーする方法の例については、「IDirectMusicPerformance8::SendPMsg」の「注意」を参照すること。

注意

システム エクスクルーシブ メッセージのデータ部分は、システム エクスクルーシブ識別子 (0xF0) で始まり、EOX (0xF7) で終わらなければならない。

動作環境

ヘッダー : dmusici.h で宣言。

参照

DMUS_MIDI_PMSG、DMUS_PATCH_PMSG、MIDI メッセージ、IDirectMusicPerformance8::SendPMsg


DMUS_TEMPO_PMSG

パフォーマンスのテンポを制御するメッセージのデータを保持する。

typedef struct DMUS_TEMPO_PMSG {
    DMUS_PMSG_PART
    double dblTempo;
} DMUS_TEMPO_PMSG;
DMUS_PMSG_PART
共通のメッセージ メンバに展開されるマクロ。「DMUS_PMSG」を参照すること。
dblTempo
DMUS_TEMPO_MIN ～ DMUS_TEMPO_MAX の範囲にあるテンポ。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::SendPMsg


DMUS_TIMESIG_PMSG

パフォーマンスの拍子記号を制御するメッセージのデータを保持する。

typedef struct _DMUS_TIMESIG_PMSG {
    DMUS_PMSG_PART
    BYTE bBeatsPerMeasure;
    BYTE bBeat;
    WORD wGridsPerBeat;
} DMUS_TIMESIG_PMSG;
DMUS_PMSG_PART
共通のメッセージ メンバに展開されるマクロ。「DMUS_PMSG」を参照すること。
bBeatsPerMeasure
小節あたりの拍数 (拍子記号の分子 )。
bBeat
ノートが受け取る拍 (拍子記号の分母)。この値が 1 のときは全ノート、2 のときは 2 分ノート、4 のときは 4 分ノートを意味する。以下同様である。0 は 256 分ノートを意味する。
wGridsPerBeat
拍あたりのグリッド (小分割)。この値は、特定の音楽イベントのタイミング分解能を決定する。たとえば、DMUS_SEGF_GRID フラグを使用したセグメントの挿入が挙げられる (「DMUS_SEGF_FLAGS」を参照)。

注意

拍子記号メッセージは、拍子記号トラックとスタイル トラックによって生成される。通常、セグメントには、拍子記号トラックまたはスタイル トラックのどちらかが含まれるが、両方含まれることはない。MIDI ファイルを表すセグメントには拍子記号トラックが含まれるが、DirectMusic Producer などのアプリケーションを使用してオーサリングされたセグメントのほとんどには、スタイル トラックに拍子記号情報が含まれる。

デフォルトでは、プライマリ セグメントだけが拍子記号メッセージを送信する。この動作を変更する方法については、「トラック パラメータの無効化と有効化」を参照すること。

拍子記号はパフォーマンスによって使われ、DMUS_SEGF_FLAGS または DMUS_TIME_RESOLVE_FLAGS でタイムを調整できるすべてのメソッドで、タイムを小節、拍、およびグリッドの境界に解決する。また、拍子記号トラックとスタイル トラックは、拍子記号を使って、小節境界および拍境界に対する通知を生成する。「DMUS_NOTIFICATION_PMSG」を参照すること。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::SendPMsg、DMUS_TIMESIGNATURE


DMUS_TRANSPOSE_PMSG

転調のメッセージ データを保持する。

typedef struct _DMUS_TRANSPOSE_PMSG {
    DMUS_PMSG_PART
    short nTranspose;
    WORD wMergeIndex;
} DMUS_TRANSPOSE_PMSG;
DMUS_PMSG_PART
共通のメッセージ メンバに展開されるマクロ。「DMUS_PMSG」を参照すること。
nTranspose
転置される半音の数。負の値であってもよい。
wMergeIndex
マージ インデックス。同じ wMergeIndex を持つ先行メッセージの後に転置メッセージが続く場合、nTranspose の値は新規設定になる。2 番目の転置メッセージが、異なる wMergeIndex を持つ場合、nTranspose の値は前の設定に追加される。このメンバが意味を持つのは、この構造体の DMUS_PMSG 部分に含まれる dwFlags メンバに、DMUS_PMSGF_DX8 が存在する場合のみである。

注意

ノートの転調によって、スタンダード MIDI の範囲 (0 ～ 127) より外側に達した場合は、そのノートは演奏されない。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::SendPMsg


DMUS_WAVE_PMSG

ウェーブ サウンドのメッセージ データを保持する。

typedef struct _DMUS_WAVE_PMSG {
    DMUS_PMSG_PART
    REFERENCE_TIME rtStartOffset;
    REFERENCE_TIME rtDuration;
    long    lOffset;
    long    lVolume;
    long    lPitch;
    BYTE    bFlags;
} DMUS_WAVE_PMSG;
;
DMUS_PMSG_PART
共通のメッセージ メンバに展開されるマクロ。「DMUS_PMSG」を参照すること。punkUser メンバには、ウェーブに関連付けられたボイス オブジェクトの、IUnknown インターフェイスのアドレスが含まれる。
rtStartOffset
ウェーブの開始地点までのタイム。基準タイム単位のみで指定する。
rtDuration
カーブの持続時間。DMUS_PMSG_PART の dwFlags メンバに DMUS_PMSGF_LOCKTOREFTIME が存在する場合、この値の単位は基準タイムになる。それ以外の場合は、ミュージック タイム単位で表される。
lOffset
実際のタイムから論理上のタイムまでのオフセット。基準タイムまたはミュージック タイムのどちらかで指定する。
lVolume
初期ボリューム。1/100 dB (デシベル) 単位で指定する。
lPitch
転調のピッチ。1/100 半音単位で指定する。
bFlags
0 または次の値を指定する。
DMUS_WAVEF_NOINVALIDATE
このウェーブを無効にしない。
DMUS_WAVEF_OFF
このメッセージにより、ウェーブの再生が停止中である。
DMUS_WAVEF_STREAMING
ウェーブはストリームしている。

注意

IDirectMusicPerformance8::SendPMsg を使うと、アプリケーションはウェーブ オブジェクトへのポインタを取得する手段がないので、このタイプのメッセージを送信できない。ただし、ツールはウェーブ メッセージを処理できる。

動作環境

ヘッダー : dmusici.h で宣言。


DirectMusic 構造体

ここでは、DirectMusic で使用される次のランタイム構造体に関するリファレンス情報を記述する。

  • DMUS_AUDIOPARAMS
  • DMUS_BAND_PARAM
  • DMUS_BUFFERDESC
  • DMUS_CHORD_KEY
  • DMUS_CHORD_PARAM
  • DMUS_CLOCKINFO8
  • DMUS_COMMAND_PARAM
  • DMUS_COMMAND_PARAM_2
  • DMUS_CONNECTION_RULE
  • DMUS_EVENTHEADER
  • DMUS_MUTE_PARAM
  • DMUS_NOTERANGE
  • DMUS_OBJECTDESC
  • DMUS_PLAY_MARKER_PARAM
  • DMUS_PORTCAPS
  • DMUS_PORTPARAMS8
  • DMUS_RHYTHM_PARAM
  • DMUS_SCRIPT_ERRORINFO
  • DMUS_SUBCHORD
  • DMUS_SYNTHSTATS8
  • DMUS_TEMPO_PARAM
  • DMUS_TIMESIGNATURE
  • DMUS_VALID_START_PARAM
  • DMUS_VARIATIONS_PARAM
  • DMUS_VERSION
  • DMUS_WAVES_REVERB_PARAMS
  • KSPROPERTY

構造体の特別なカテゴリは、以下のトピックで説明する。

  • DirectMusic メッセージ
  • DirectMusic のファイル データ構造体
  • DLS 構造体


DMUS_AUDIOPARAMS

デフォルトのシンセサイザおよびパフォーマンスのバッファに必要なリソースを記述する。必要な機能を要求するため、およびどの要求が許可されたかに関する情報を受け取るために、IDirectMusicPerformance8::InitAudio メソッドに渡される。

typedef struct _DMUS_AUDIOPARAMS {
    DWORD  dwSize;
    BOOL   fInitNow;
    DWORD  dwValidData;
    DWORD  dwFeatures;
    DWORD  dwVoices;
    DWORD  dwSampleRate;
    CLSID  clsidDefaultSynth;
} DMUS_AUDIOPARAMS;
dwSize
構造体のサイズ。バイト単位で指定する。この構造体を使用する前に、このメンバを初期化しなければならない。
fInitNow
シンクとシンセサイザを即時に作成するかどうかを指定するブール値。 即時作成する場合は、この構造体に結果が返される。
dwValidData
この構造体のどのメンバが有効であるかを示すフラグ。構造体が渡されたときに fInitNow が TRUE であれば、どのメンバがデータを受け取ったかを示すフラグを受け取る。次の値が定義されている。
DMUS_AUDIOPARAMS_FEATURES
dwFeatures メンバがデータを保持している、または受け取った。
DMUS_AUDIOPARAMS_VOICES
dwVoices メンバがデータを保持している、または受け取った。
DMUS_AUDIOPARAMS_SAMPLERATE
dwSampleRate メンバがデータを保持している、または受け取った。
DMUS_AUDIOPARAMS_DEFAULTSYNTH
clsidDefaultSynth メンバがデータを保持している、または受け取った。このフラグが設定されていない場合は、Microsoft のソフトウェア シンセサイザがデフォルトのシンセサイザである。
dwFeatures
必要な機能を指定するフラグ。次の値が定義されている。
DMUS_AUDIOF_3D
3D バッファ。
DMUS_AUDIOF_ALL
ほかのすべてのフラグを組み合わせたもの。
DMUS_AUDIOF_BUFFERS
複数のバッファ。オーディオパスを使用する場合は、常にこのフラグを設定する。
DMUS_AUDIOF_ENVIRON
環境モデリング。
DMUS_AUDIOF_EAX
EAX エフェクト。
DMUS_AUDIOF_DMOS
追加の DMO。
DMUS_AUDIOF_STREAMING
ストリーミング ウェーブのサポート。
dwVoices
ボイスの数。デフォルト値は 64 である。
dwSampleRate
11,025 ～ 96,000 kHz の範囲のシンクおよびシンセサイザのサンプリング レート。デフォルト値は 22,050 である。
clsidDefaultSynth
デフォルトのシンセサイザのクラス識別子。これは、標準オーディオパスおよびデフォルトのシンセサイザを要求する構成から作成されたオーディオパスで使用されるシンセサイザである。

動作環境

ヘッダー : dmusicf.h で宣言。


DMUS_BAND_PARAM

トラックがバンド トラックであり、rguidType が GUID_BandParam である場合、各種のパラメータ取得メソッドやパラメータ設定メソッドを呼び出す際に、pParam パラメータとして使用される。

typedef struct _DMUS_BAND_PARAM {
    MUSIC_TIME mtTimePhysical;
    IDirectMusicBand *pBand;
} DMUS_BAND_PARAM;

メンバ

mtTimePhysical
バンド チェンジが発生する実際のタイム。「注意」を参照すること。
pBand
バンドの IDirectMusicBand8 インターフェイスのアドレス。

注意

mtTimePhysical の値は、バンド チェンジが発生する実際のタイムである。一方、パラメータ設定メソッドの mtTime パラメータの値は、拍や小節と同期した、バンド チェンジが属するパフォーマンス内のポイントである。mtTimePhysical に対して、mtTime より少し早いタイムを設定することで、バンド チェンジがループの先頭に発生する場合にも、ノートが常に正しいバンドによって演奏されることが保証される。

クロック タイム トラックの場合、mtTimePhysical はそのトラックの内部時間フォーマットで解釈される。これは、再生開始からのミリ秒数である。これは紛らわしいため、クロック タイム トラックでは GUID_BandParam を使用しないことが推奨される。

動作環境

ヘッダー : dmusicf.h で宣言。

参照

IDirectMusicPerformance8::GetParam、IDirectMusicPerformance8::SetParam、IDirectMusicSegment8::GetParam、IDirectMusicSegment8::SetParam、IDirectMusicTrack8::GetParamEx、IDirectMusicTrack8::SetParamEx、パフォーマンス パラメータ


DMUS_BUFFERDESC

IDirectMusic8::CreateMusicBuffer メソッドのバッファを記述するために使用される。

typedef struct _DMUS_BUFFERDESC {
    DWORD dwSize;
    DWORD dwFlags;
    GUID  guidBufferFormat;
    DWORD cbBuffer;
} DMUS_BUFFERDESC, *LPDMUS_BUFFERDESC;

メンバ

dwSize
構造体のサイズ。バイト単位で指定する。この構造体を使用する前に、このメンバを初期化しなければならない。
dwFlags
フラグは定義されていない。
guidBufferFormat
バッファの KS フォーマットの識別子。値 GUID_NULL は、KSDATAFORMAT_SUBTYPE_DIRECTMUSIC を表す。

guidBufferFormat が KSDATAFORMAT_SUBTYPE_DIRECTMUSIC 以外の KS フォーマットを表す場合、アプリケーションは、データを再生しているポートが指定のフォーマットを理解しているかどうか検証しなければならない。そうしなかった場合、バッファは無視される。ポートが特定の KS フォーマットをサポートしているかどうかを調べるには、IKsControl::KsProperty メソッドを使用する。

cbBuffer
メッセージの最小サイズ (バイト単位)。システムがバッファを 4 バイトの倍数に追加するため、割り当てることのできるメモリ量はわずかに増える。1 つの MIDI チャンネル メッセージを格納するには、バッファは 32 バイト以上でなければならない。システム エクスクルーシブ メッセージまたはその他の非構造化データを格納するために、バッファは最低 28 バイトとデータ サイズを合わせたサイズでなければならない。

動作環境

ヘッダー : dmusici.h で宣言。

参照

DMUS_EVENTHEADER、IDirectMusicBuffer8::PackStructured、IDirectMusicBuffer8::PackUnstructured


DMUS_CHORD_KEY

IDirectMusicPerformance8::MIDIToMusic メソッドおよび IDirectMusicPerformance8::MusicToMIDI メソッドで、コードを記述するために使用される。

typedef struct _DMUS_CHORD_KEY {
    WCHAR         wszName[16];
    WORD          wMeasure;
    BYTE          bBeat;
    BYTE          bSubChordCount;
    DMUS_SUBCHORD SubChordList[DMUS_MAXSUBCHORD];
    DWORD         dwScale;
    BYTE          bKey;
    BYTE          bFlags;
} DMUS_CHORD_KEY;

メンバ

wszName
コードの名前。
wMeasure
コードが所属する小節。
bBeat
コードが所属する拍。
bSubChordCount
コードのサブコード リスト内にあるコードの数。
SubChordList
コードを構成するコンポーネントを記述する、DMUS_SUBCHORD 構造体の配列。
dwScale
コード全体のベースとなるスケール。
bKey
コード全体のベースとなるキー。
bFlags
0 を指定できる。コードが無音である場合は DMUS_CHORDKEYF_SILENT。「注意」を参照すること。

注意

この構造体は、GUID_ChordParam トラック パラメータの設定と取得に使用される、DMUS_CHORD_PARAM 構造体としても定義される。

コードに無音コードのフラグが設定されていても、演奏パターンが選択される際には考慮されない。たとえば、1 拍目にコード チェンジ、3 拍目に無音コードがある場合でも、小節全体のコード リズムを持つパターンが演奏されることがある。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::GetParam、IDirectMusicPerformance8::SetParam、IDirectMusicSegment8::GetParam、IDirectMusicSegment8::SetParam、IDirectMusicTrack8::GetParamEx、IDirectMusicTrack8::SetParamEx、パフォーマンス パラメータ


DMUS_CHORD_PARAM

トラックがコード トラックであり、rguidType が GUID_ChordParam である場合、各種のパラメータ取得メソッドやパラメータ設定メソッドを呼び出す際に、pParam パラメータとして使用される。

typedef DMUS_CHORD_KEY DMUS_CHORD_PARAM;

「DMUS_CHORD_KEY」を参照すること。

動作環境

ヘッダー : dmusicf.h で宣言。

参照

IDirectMusicPerformance8::GetParam、IDirectMusicPerformance8::SetParam、IDirectMusicSegment8::GetParam、IDirectMusicSegment8::SetParam、IDirectMusicTrack8::GetParamEx、IDirectMusicTrack8::SetParamEx、パフォーマンス パラメータ


DMUS_CLOCKINFO8

IDirectMusic8::EnumMasterClock メソッドを使用して列挙された、クロックに関する情報を報告する。

typedef struct _DMUS_CLOCKINFO{
    DWORD           dwSize;
    DMUS_CLOCKTYPE  ctType;
    GUID            guidClock;
    WCHAR           wszDescription[DMUS_MAX_DESCRIPTION];
    DWORD           dwFlags;
} DMUS_CLOCKINFO8, *LPDMUS_CLOCKINFO8;

typedef DMUS_CLOCKINFO8 DMUS_CLOCKINFO;
typedef DMUS_CLOCKINFO *LPDMUS_CLOCKINFO;

メンバ

dwSize
構造体のサイズ。バイト単位で指定する。この構造体をメソッドに渡す前に、このメンバを初期化しなければならない。
ctType
クロックのタイプを指定する、DMUS_CLOCKTYPE 列挙型のメンバ。
guidClock
クロックの識別子。この値を IDirectMusic8::SetMasterClock メソッドに渡すと、DirectMusic のマスタ クロックを設定することができる。
wszDescription
クロックの記述。
dwFlags
フラグ。

動作環境

ヘッダー : dmusici.h で宣言。


DMUS_COMMAND_PARAM

トラックがコマンド トラックであり、rguidType パラメータが GUID_CommandParam である場合、各種のパラメータ取得メソッドやパラメータ設定メソッドを呼び出す際に、pParam パラメータとして使用される。

typedef struct {
    BYTE bCommand;
    BYTE bGrooveLevel;
    BYTE bGrooveRange;
    BYTE bRepeatMode;
} DMUS_COMMAND_PARAM;

メンバ

bCommand
コマンドのタイプ。「DMUS_COMMANDT_TYPES」を参照すること。
bGrooveLevel
コマンドのグルーブ レベル。グルーブ レベルは、1 ～ 100 の範囲で指定する値である。
bGrooveRange
グルーブ レベルをランダム化できる量。たとえば、グルーブ レベルが 35 で範囲が 4 の場合、実際のグルーブ レベルは 33 から 37 のいずれかの値になる。bGrooveRange が奇数ならば、そこから 1 が引かれる。
bRepeatMode
反復のパターンを選択する方法を指定するフラグ。「DMUS_PATTERNT_TYPES」を参照すること。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::GetParam、IDirectMusicPerformance8::SetParam、IDirectMusicSegment8::GetParam、IDirectMusicSegment8::SetParam、IDirectMusicTrack8::GetParamEx、IDirectMusicTrack8::SetParamEx


DMUS_COMMAND_PARAM_2

トラックがコマンド トラックであり、rguidType パラメータが GUID_CommandParam2 である場合、各種のパラメータ取得メソッドやパラメータ設定メソッドを呼び出す際に、pParam パラメータとして使用される。

typedef struct _DMUS_COMMAND_PARAM_2 {
    MUSIC_TIME mtTime;
    BYTE bCommand;
    BYTE bGrooveLevel;
    BYTE bGrooveRange;
    BYTE bRepeatMode;
} DMUS_COMMAND_PARAM_2;

メンバ

mtTime
コマンドのタイム。
bCommand
コマンドのタイプ。「DMUS_COMMANDT_TYPES」を参照すること。
bGrooveLevel
コマンドのグルーブ レベル。グルーブ レベルは、1 ～ 100 の範囲で指定する値である。
bGrooveRange
グルーブ レベルをランダム化できる量。たとえば、グルーブ レベルが 35 で範囲が 4 の場合、グルーブ レベルは 33 から 37 のいずれかの値になる。bGrooveRange が奇数ならば、そこから 1 が引かれる。
bRepeatMode
反復のパターンを選択する方法を指定するフラグ。「DMUS_PATTERNT_TYPES」を参照すること。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::GetParam、IDirectMusicPerformance8::SetParam、IDirectMusicSegment8::GetParam、IDirectMusicSegment8::SetParam、IDirectMusicTrack8::GetParamEx、IDirectMusicTrack8::SetParamEx


DMUS_CONNECTION_RULE

DirectX 8.0 では実装されない。

音楽の断片が次から次へとスムーズに流れるための規則を指定するために、DMUS_MELODY_FRAGMENT の ConnectionArc メンバで使用される。

typedef struct _DMUS_CONNECTION_RULE {
    DWORD       dwFlags;
    DWORD       dwIntervals;
} DMUS_CONNECTION_RULE;

メンバ

dwFlags
結合規則を指定するフラグ。0 または次の 1 つ以上の値を使用できる。
DMUS_CONNECTIONF_INTERVALS
バリエーションの最後のノートと、次のバリエーションの最初のノートの間で、dwIntervals の音程を使用する。
DMUS_CONNECTIONF_OVERLAP
2 つの断片がオーバーラップする場合、先の断片で演奏されない最初のノートが、後の断片の最初のノートと同じである。
dwIntervals
DMUS_CONNECTIONF_INTERVALS が設定されている場合、最初の断片で演奏される最後のノートと、2 番目の断片に含まれる最初のノートの間で、有効な音程のセットを指定する。下位 24 ビットのそれぞれが、2 オクターブの範囲を持つ音程である。

動作環境

ヘッダー : dmusici.h で宣言。


DMUS_EVENTHEADER

ポート バッファ内のイベントの前に置かれ、このイベントを記述する。

typedef struct _DMUS_EVENTHEADER {
    DWORD           cbEvent;
    DWORD           dwChannelGroup;
    REFERENCE_TIME  rtDelta;
    DWORD           dwFlags;
} DMUS_EVENTHEADER, *LPDMUS_EVENTHEADER;

メンバ

cbEvent
イベント内のバイト数。
dwChannelGroup
イベントが所属するグループ。
rtDelta
バッファの開始タイムからのオフセット。
dwFlags
イベントが解析可能な MIDI データの場合、DMUS_EVENT_STRUCTURED に設定される。

注意

この構造体の宣言の前には Pshpack4.h ヘッダー ファイルがインクルードされている。これによって構造体の自動整列が無効になり、データはヘッダーのすぐ後に続く (詳細については、Pshpack4.h 内のコメントを参照)。次に Poppack.h がインクルードされ、整列が有効になる。構造体全体 (ヘッダーとイベント) が 8 バイト境界まで追加される。

動作環境

ヘッダー : dmusbuff.h で宣言。

参照

IDirectMusicBuffer8::GetNextEvent、IDirectMusicBuffer8::PackStructured、IDirectMusicBuffer8::PackUnstructured


DMUS_MELODY_FRAGMENT

DirectX 8.0 では実装されない。

メロディ編成トラックの断片を記述する。メロディの断片は、メロディのアレンジを行う際に、パターンからバリエーションを選択するために使用される。

typedef struct _DMUS_MELODY_FRAGMENT {
    MUSIC_TIME  mtTime;
    DWORD  dwID;
    WCHAR  wszVariationLabel[DMUS_MAX_FRAGMENTLABEL];
    DWORD  dwVariationFlags;
    DWORD  dwRepeatFragmentID;
    DWORD  dwFragmentFlags;
    DWORD  dwPlayModeFlags;
    DWORD  dwTransposeIntervals;
    DMUS_COMMAND_PARAM   Command;
    DMUS_CONNECTION_RULE ConnectionArc;
} DMUS_MELODY_FRAGMENT;

メンバ

mtTime
断片を演奏するタイム。トラックの開始からの相対時間である。
dwID
トラックの識別子。
wszVariationLabel
予約済み。
dwVariationFlags
使用可能なバリエーションのセットを指定する DWORD 値。設定される各ビット が 1 つのバリエーションを表す。dwFragmentFlags に DMUS_FRAGMENTF_USE_REPEAT が含まれる場合は無視される。
dwRepeatFragmentID
トラック内の以前の断片の識別子。ここからバリエーションを選択する。dwFragmentFlags に DMUS_FRAGMENTF_USE_REPEAT が含まれない場合は無視される。
dwFragmentFlags
次の値のいずれかを使用できる。
DMUS_FRAGMENTF_USE_REPEAT
dwRepeatFragmentID に指定された断片を使用する。
DMUS_FRAGMENTF_REJECT_REPEAT
以前の断片の新しいバリエーションを使用する。
DMUS_FRAGMENTF_USE_LABEL
wszVariationLabel で指定されるセットを使用する。現在サポートされていない。
dwPlayModeFlags
予約済み。0 でなければならない。
dwTransposeIntervals
下位 24 ビットはそれぞれ、2 オクターブの範囲内の音程を表す。リピートする断片内のノートを、現在のコードまたはキーに合わせて転置するための基準となる、音程のセットを指定する。
Command
メロディのソースとして使用するパターンのタイプを指定する DMUS_COMMAND_PARAM 構造体。
ConnectionArc
断片が次から次へとスムーズに流れるようにするための規則を指定する DMUS_CONNECTION_RULE 構造体。

注意

それぞれの断片に対して選択されたバリエーションがメロディを形成する。断片は、任意の拍境界上に配置でき、小節境界にまたがることができる。2 つの断片がオーバーラップする場合、先行する断片で選択されたバリエーションは、後の断片のノートと衝突しないように、切り捨てられる。

それぞれのメロディ断片には、そのポイントに適したバリエーションの記述が含まれる。これは、バリエーションの範囲、リスト、または "すべてのバリエーションを使用する" ための指示である。バリエーションの選択は、前のバリエーションを参照することもできる。メロディ断片は、演奏モードを使用して構築中のメロディ内にノートを生成したり、コードの音程やスケールの音程を使用して現在のコードに揃えるバリエーションを選択したりすることができる。さらに、断片を揃えるために転置する際の基準とする音程として、音程のセットを選択することもできる。

動作環境

ヘッダー : dmusici.h で宣言。

参照

GUID_MelodyFragment


DMUS_MUTE_PARAM

トラックがミュート トラックであり、rguidType が GUID_MuteParam である場合、各種のパラメータ取得メソッドやパラメータ設定メソッドを呼び出す際に、pParam パラメータとして使用される。

typedef struct _DMUS_MUTE_PARAM {
    DWORD  dwPChannel;
    DWORD  dwPChannelMap;
    BOOL   fMute;
} DMUS_MUTE_PARAM;

メンバ

dwPChannel
ミュートまたは再マップするパフォーマンス チャンネル。構造体が get メソッドに渡される場合は、このメンバを初期化しなければならない。
dwPChannelMap
dwPChannel がマップされているチャンネル。fMute が TRUE の場合、このメンバは無視される。
fMute
dwPChannel がミュートされている場合は TRUE。

注意

P チャンネル 3 上のすべてのノートを P チャンネル 9 上で演奏したい場合は、この構造体を set メソッドのいずれかに渡す前に、dwPChannel を 3 に設定し、dwPChannelMap を 9 に設定する。P チャンネル 8 上のノートをミュートしたい場合は、dwPChannel を 8 に設定し、dwPChannelMap を 0xFFFFFFFF に設定する。

動作環境

ヘッダー : dmusicf.h で宣言。

参照

IDirectMusicPerformance8::GetParam、IDirectMusicPerformance8::SetParam、IDirectMusicSegment8::GetParam、IDirectMusicSegment8::SetParam、IDirectMusicTrack8::GetParamEx、IDirectMusicTrack8::SetParamEx


DMUS_NOTERANGE

音色が応答しなければならないノート範囲を指定する。この構造体の配列を IDirectMusicPerformance8::DownloadInstrument メソッドと IDirectMusicPort8::DownloadInstrument メソッドに渡して、音色がどのノートに応答すべきか、そのためにどの音色リージョンをダウンロードする必要があるかを指定する。

typedef struct _DMUS_NOTERANGE {
    DWORD dwLowNote;
    DWORD dwHighNote;
} DMUS_NOTERANGE, *LPDMUS_NOTERANGE;

メンバ

dwLowNote
音色が応答しなければならない MIDI ノート範囲の低い音。
dwHighNote
音色が応答しなければならない MIDI ノート範囲の高い音。

動作環境

ヘッダー : dmdls.h で宣言。


DMUS_OBJECTDESC

DirectMusic オブジェクトを記述するために使用される。この構造体を IDirectMusicLoader8::GetObject メソッドに渡して、ローダーが記憶装置から取得すべきオブジェクトを識別する。この構造体からオブジェクトに関する情報を取得するには、IDirectMusicLoader8::EnumObject メソッドと IDirectMusicObject8::GetDescriptor メソッドを使用する。

typedef struct _DMUS_OBJECTDESC {
    DWORD         dwSize;
    DWORD         dwValidData;
    GUID          guidObject;
    GUID          guidClass;
    FILETIME      ftDate;
    DMUS_VERSION  vVersion;
    WCHAR         wszName[DMUS_MAX_NAME];
    WCHAR         wszCategory[DMUS_MAX_CATEGORY];
    WCHAR         wszFileName[DMUS_MAX_FILENAME];
    LONGLONG      llMemLength;
    LPBYTE        pbMemData;
    IStream       *pStream
} DMUS_OBJECTDESC, *LPDMUS_OBJECTDESC;

メンバ

dwSize
構造体のサイズ。バイト単位で指定する。この構造体を任意のメソッドに渡す前に、このメンバを sizeof(DMUS_OBJECTDESC) に初期化しなければならない。
dwValidData
どのメンバが有効なのか記述し、いくつかのメンバに関する詳細な情報を提供するフラグ。次の値が定義されている。
DMUS_OBJ_CATEGORY
wszCategory メンバは有効である。
DMUS_OBJ_CLASS
guidClass メンバは有効である。
DMUS_OBJ_DATE
ftDate メンバは有効である。
DMUS_OBJ_FILENAME
wszFileName メンバは有効である。DMUS_OBJ_FULLPATH が設定されている場合は、このフラグがあると想定される。
DMUS_OBJ_FULLPATH
wszFileName メンバは、ファイルのフル パス、またはアプリケーション ディレクトリからの相対パスのどちらかを保持している。IDirectMusicLoader8::SetSearchDirectory で設定されたディレクトリは検索されない。このフラグが設定されない場合、wszFilename は常に、アプリケーション ディレクトリからの相対パス、またはこのオブジェクト タイプに対して SetSearchDirectory が呼び出される場合は、検索ディレクトリからの相対パスであると仮定される。
DMUS_OBJ_LOADED
オブジェクトは現在メモリ内にロードされている。
DMUS_OBJ_MEMORY
オブジェクトはメモリ内にあり、llMemLength と pbMemData は有効である。
DMUS_OBJ_NAME
wszName メンバは有効である。
DMUS_OBJ_OBJECT
guidObject メンバは有効である。
DMUS_OBJ_STREAM
pStream メンバは、データ ストリームへのポインタを保持している。
DMUS_OBJ_URL
wszFileName メンバは URL を保持している。DirectMusic ローダーは現在 URL をサポートしていない。
DMUS_OBJ_VERSION
vVersion メンバは有効である。
guidObject
このオブジェクトの一意の識別子。
guidClass
オブジェクト クラスの一意の識別子。すべての標準的なオブジェクトは、"CLSID_" とオブジェクト名で構成される定義済みの識別子を持っている。たとえば、セグメント オブジェクトは CLSID_DirectMusicSegment として識別される。Dmusici.h ヘッダー ファイル内の定義を参照すること。
ftDate
オブジェクトが最後に編集された日付。
vVersion
バージョン情報を保持する DMUS_VERSION 構造体。
wszName
オブジェクトの名前。
wszCategory
オブジェクトのカテゴリ。
wszFileName
ファイルのパス。DMUS_OBJ_FULLPATH が設定されている場合、この値はフル パスである。それ以外の場合は、ファイル名だけである。IDirectMusicLoader8::SetSearchDirectory メソッドが呼び出されていた場合は、ファイル名のみでなければならない。
llMemLength
メモリ内のデータのサイズ。
pbMemData
メモリ内のデータ。
pStream
カスタム ストリームの IStream インターフェイスのアドレス。オブジェクトをメモリにロードするために使用することができる。ほとんどの場合、この値は NULL である。「注意」を参照すること。

注意

IDirectMusicLoader8::GetObject メソッドを使用してオブジェクトを取得できるように、wszName、idGuid、および wszFileName の少なくとも 1 つに有効なデータを書き込まなければならない。

名前とカテゴリの文字列は、8 ビットの ANSI 文字ではなく、WCHAR フォーマットの 16 ビット文字を使用する。必要に応じて変換を行うよう注意すること。C ライブラリの mbstowcs 関数を使用して、マルチバイトから Unicode、wcstombs 関数を使用して Unicode からマルチバイトへの変換も行える。

オブジェクト ディスクリプタをファイル名やメモリ ポインタと共に IDirectMusicLoader8::GetObject または IDirectMusicLoader8::SetObject に渡す代わりに、アプリケーションでストリームを渡すことができる。これを行うには、dwValidData に DMUS_OBJ_STREAM フラグを設定し、pStream 内のストリームへのポインタを設定する。アプリケーションが GetObject を呼び出すと、ローダーはストリームの現在の位置を保存し、ストリームからオブジェクトを読み出し、保存した位置を復元する。アプリケーションは、GetObject への呼び出しによる影響を受けずに、ストリームからの読み出しを継続して行うことができる。

ストリームで SetObject が呼び出されると、ローダーはストリームのコピーを作成する。このコピーは、オブジェクトが後からロードされた場合に使用される。したがって、アプリケーションは SetObject を使用してローダーにストリームを渡した後、ストリームを解放したり、継続してストリームから読み出したりすることができる。

動作環境

ヘッダー : dmusici.h で宣言。


DMUS_PLAY_MARKER_PARAM

演奏マーカーに関する情報を保持する。

typedef struct _DMUS_PLAY_MARKER_PARAM {
    MUSIC_TIME mtTime;
} DMUS_PLAY_MARKER_PARAM;

メンバ

mtTime
最初の有効なセグメント演奏マーカーのタイム、または要求されたタイム。この値は要求されたタイムからのオフセットである。

動作環境

ヘッダー : dmusici.h で宣言。

参照

GUID_Play_Marker


DMUS_PORTCAPS

IDirectMusic8::EnumPort メソッドの呼び出しで列挙された、ポートに関する情報を受け取る。IDirectMusicPort8::GetCaps メソッドを通して情報を返すときも、この構造体が使用される。

typedef struct _DMUS_PORTCAPS {
    DWORD dwSize;
    DWORD dwFlags;
    GUID  guidPort;
    DWORD dwClass;
    DWORD dwType;
    DWORD dwMemorySize;
    DWORD dwMaxChannelGroups;
    DWORD dwMaxVoices;
    DWORD dwMaxAudioChannels;
    DWORD dwEffectFlags;
    WCHAR wszDescription[DMUS_MAX_DESCRIPTION];
} DMUS_PORTCAPS, *LPDMUS_PORTCAPS;

メンバ

dwSize
構造体のサイズ。バイト単位で指定する。この構造体を任意のメソッドに渡す前に、このメンバを sizeof(DMUS_PORTCAPS) に初期化しなければならない。
dwFlags
ポートのさまざまな能力を記述するフラグ。このフィールドには、次の 1 つ以上の値を含めることができる。
DMUS_PC_AUDIOPATH
オーディオパス用に複数の出力を DirectSound に接続することができる。
DMUS_PC_DIRECTSOUND
ポートは DirectSound に送るストリーミング ウェーブ データをサポートする。
DMUS_PC_DLS
ポートは DLS レベル 1 のサンプル コレクションをサポートする。
DMUS_PC_DLS2
ポートは DLS レベル 2 のサンプル コレクションをサポートする。
DMUS_PC_EXTERNAL
ポートはホストの外部にあるデバイスに接続されている。たとえば、MPU-401 のような外部 MIDI ポートを通してデバイスに接続されている。
DMUS_PC_GMINHARDWARE
シンセサイザは独自の GM 音色セットを持っている。そのため、GM 音色はダウンロードする必要がない。
DMUS_PC_GSINHARDWARE
このポートは、ハードウェア内に Roland GS サウンド セットを保持している。
DMUS_PC_MEMORYSIZEFIXED
DLS 音色で利用できるメモリは調整できない。
DMUS_PC_SHAREABLE
デバイス上にあるチャンネル グループの同じ範囲を使用するポートは複数作成できる。このビットをセットしない限り、ポートは排他モードでのみ開くことができる。排他モードでは、作成された要求への割り当てに利用できるチャンネル グループがない限り、ポートを作成する試みは失敗する。
DMUS_PC_SOFTWARESYNTH
ポートはソフトウェア シンセサイザである。
DMUS_PC_WAVE
ストリーミングおよびワンショット ウェーブがサポートされている。
DMUS_PC_XGINHARDWARE
このポートは、ハードウェア内に Yamaha XG 拡張を保持している。
guidPort
ポートの識別子。この値を IDirectMusic8::CreatePort メソッドに渡すと、ポートの IDirectMusicPort8 インターフェイスを取得することができる。
dwClass
このポートのクラス。次のクラスが定義されている。
DMUS_PC_INPUTCLASS
入力ポート。
DMUS_PC_OUTPUTCLASS
出力ポート。
dwType
このポートのタイプ。次のタイプが定義されている。
DMUS_PORT_WINMM_DRIVER
Windows マルチメディア ドライバ。
DMUS_PORT_USER_MODE_SYNTH
ユーザーモード シンセサイザ。
DMUS_PORT_KERNEL_MODE
WDM ドライバ。
dwMemorySize
DLS 音色の保存に利用できるメモリの量。ポートがシステム メモリを使用していて、利用可能なシステム メモリによりその量が制限を受ける場合、このメンバは DMUS_PC_SYSTEMMEMORY を保持する。
dwMaxChannelGroups
このポートがサポートするチャンネル グループの最大数。1 つのチャンネル グループは、16 個の MIDI チャンネルから成るセットである。
dwMaxVoices
このポートを開いたときに割り当てのできるボイスの最大数。このパラメータが返されることをドライバがサポートしていない場合、値は － 1 でもよい。
dwMaxAudioChannels
ポートによってレンダリングできるオーディオ チャンネルの最大数。このパラメータが返されることをドライバがサポートしていない場合、値は － 1 でもよい。
dwEffectFlags
ポート上でどのようなオーディオ エフェクトを利用できるのかを示すフラグ。

次のフラグが定義されている。

DMUS_EFFECT_NONE
エフェクトはサポートしていない。
DMUS_EFFECT_REVERB
ポートはリバーブをサポートする。
DMUS_EFFECT_CHORUS
ポートはコーラスをサポートする。
wszDescription
ポートの記述。L"MPU-401 Output Port [330]" のようなシステム生成の名前でも、L"Port w/ External SC-55" のようなユーザー指定のわかりやすい名前でもよい。

動作環境

ヘッダー : dmusicc.h で宣言。


DMUS_PORTPARAMS8

DirectMusic ポートを開くためのパラメータで構成されている。IDirectMusic8::CreatePort メソッドを呼び出したときに、これらのパラメータが渡される。

DMUS_PORTPARAMS という定義は DMUS_PORTPARAMS8 に解決される。この構造体は、DMUS_PORTPARAMS 以前のバージョンを引き継ぐ。以前のバージョンは現在 DMUS_PORTPARAMS7 として宣言される。

typedef struct _DMUS_PORTPARAMS8 {
    DWORD dwSize;
    DWORD dwValidParams;
    DWORD dwVoices;
    DWORD dwChannelGroups;
    DWORD dwAudioChannels;
    DWORD dwSampleRate;
    DWORD dwEffectFlags;
    DWORD fShare;
    DWORD dwFeatures;
} DMUS_PORTPARAMS8;

typedef DMUS_PORTPARAMS8 DMUS_PORTPARAMS;
typedef DMUS_PORTPARAMS *LPDMUS_PORTPARAMS;

メンバ

dwSize
構造体のサイズ。バイト単位で指定する。この構造体をメソッドに渡す前に、このメンバを sizeof(DMUS_PORTPARAMS) に初期化しなければならない。
dwValidParams
この構造体のどのメンバが有効であるかを指定する。特定のパラメータにフラグを設定することは、ポートの作成時に、メソッドの呼び出しでそのパラメータを設定したい、またはデフォルト値をオーバーライドしたいことを意味する。次のフラグが定義されている。
DMUS_PORTPARAMS_VOICES
DMUS_PORTPARAMS_CHANNELGROUPS
DMUS_PORTPARAMS_AUDIOCHANNELS
DMUS_PORTPARAMS_SAMPLERATE
DMUS_PORTPARAMS_EFFECTS
DMUS_PORTPARAMS_SHARE
DMUS_PORTPARAMS_FEATURES
dwVoices
このポートで必要なボイスの数。これは絶対的な最大値ではない。ポートは、優先順位の低いボイスを削除する必要があるときに、追加のボイスを一時的に作成し、スムーズにトランジションさせることができる。
dwChannelGroups
このポートに割り当てられるチャンネル グループの数。IDirectMusic8::EnumPort メソッドと IDirectMusicPort8::GetCaps メソッドが返した DMUS_PORTCAPS 構造体で指定されるチャンネル グループ数以下でなければならない。
dwAudioChannels
目的の出力チャンネル数。
dwSampleRate
目的のサンプリング レート。ヘルツ (Hz) 単位で指定する。
dwEffectFlags
目的の特殊効果を示すフラグ。次のフラグが定義されている。

DMUS_EFFECT_NONE
DMUS_EFFECT_REVERB
DMUS_EFFECT_CHORUS

fShare
TRUE の場合、すべてのポートが、このポートに割り当てられたチャンネル グループを使用する。FALSE の場合、ポートは排他モードで開かれ、その他のポートによる同じチャンネル グループの使用が禁止される。
dwFeatures
ポートのその他の能力。次の値が定義されている。
DMUS_PORT_FEATURE_AUDIOPATH
DirectSound バッファとのオーディオパス接続をサポートする。
DMUS_PORT_FEATURE_STREAMING
シンセサイザからのストリーミング ウェーブをサポートする。

注意

DirectX 8.0 より前のバージョンの DMUS_PORTPARAMS 構造体は、DMUS_PORTPARAMS7 として Dmusicc.h 内に維持される。

動作環境

ヘッダー : dmusicc.h で宣言。

参照

DMUS_PORTCAPS


DMUS_RHYTHM_PARAM

トラックがコード トラックであり、rguidType が GUID_RhythmParam である場合、各種のパラメータ取得メソッドを呼び出す際に、pParam パラメータとして使用される。

typedef struct {
    DMUS_TIMESIGNATURE  TimeSig;
    DWORD               dwRhythmPattern;
} DMUS_RHYTHM_PARAM;

メンバ

TimeSig
リズム パラメータの拍子記号を保持する DMUS_TIMESIGNATURE 構造体。DMUS_RHYTHM_PARAM 構造体を get メソッドに渡す前に、この構造体を初期化しなければならない。
dwRhythmPattern
コード シーケンスのリズム パターン。各ビットは 1 つまたは複数の小節内の 1 つの拍を表し、1 はその拍でコードがオンになっていること、0 はコードが存在しないことを表す。

動作環境

ヘッダー : dmusicf.h で宣言。

参照

IDirectMusicPerformance8::GetParam、IDirectMusicPerformance8::SetParam、IDirectMusicSegment8::GetParam、IDirectMusicSegment8::SetParam、IDirectMusicTrack8::GetParamEx、IDirectMusicTrack8::SetParamEx


DMUS_SCRIPT_ERRORINFO

スクリプト エラーに関する情報を保持する。

typedef struct _DMUS_SCRIPT_ERRORINFO {
    DWORD   dwSize;
    HRESULT hr;
    ULONG ulLineNumber;
    LONG ichCharPosition;
    WCHAR  wszSourceFile[DMUS_MAX_FILENAME];
    WCHAR  wszSourceComponent[DMUS_MAX_FILENAME];
    WCHAR  wszDescription[DMUS_MAX_FILENAME];
    WCHAR  wszSourceLineText[DMUS_MAX_FILENAME];
} DMUS_SCRIPT_ERRORINFO;

メンバ

dwSize
構造体のサイズ。バイト単位で指定する。この構造体を IDirectMusicScript8 の任意のメソッドに渡す前に、このメンバを初期化しなければならない。
hr
DirectMusic またはスクリプト エンジンから取得される結果コード。
ulLineNumber
エラーが発生したスクリプト内の行番号。
ichCharPosition
wszSourceLineText が文字列を保持する場合に、構文エラーが見つかった行内の場所。
wszSourceFile
スクリプトのファイル名。
wszSourceComponent
エラーを生成したコンポーネント名。たとえば、DirectMusic やスクリプト解析エンジンなど。
wszDescription
エラーの説明。
wszSourceLineText
エラーが発生したスクリプト行のテキスト。エラーが構文内にない場合は、空の文字列になる。

動作環境

ヘッダー : dmusici.h で宣言。


DMUS_SUBCHORD

DMUS_CHORD_PARAM 構造体の SubChordList メンバで使用される。

typedef struct {
    DWORD dwChordPattern;
    DWORD dwScalePattern;
    DWORD dwInversionPoints;
    DWORD dwLevels;
    BYTE  bChordRoot;
    BYTE  bScaleRoot;
} DMUS_SUBCHORD;

メンバ

dwChordPattern
サブコード内のノート。下位 24 ビットはそれぞれ 1 つの半音を表し、最下位ビットはルート音である。ビットがセットされている場合、それに対応するノートはコード内に存在する。
dwScalePattern
スケール内のノート。下位 24 ビットはそれぞれ 1 つの半音を表し、最下位ビットはルート音である。ビットがセットされている場合、それに対応するノートはスケール内に存在する。
dwInversionPoints
スケール内で転回が発生できるポイント。ビットがオフになっている場合、それに対応する音程ではノートを転回できない。たとえば、パターン 100001111111 は、陽音階 (メジャー スケール) の 5 度と 7 度を除き、どこでも転回が認められることを意味する。
dwLevels
このサブコードがサポートするレベルを示すビット フィールド。スタイル内の各パートにはレベルが割り当てられ、レベルがこのメンバに含まれるパートだけについてこのコードが使用される。
bChordRoot
サブコードのルート音。0 は範囲内の最低音の C、23 は最高音の B である。
bScaleRoot
スケールのルート音。0 は範囲内の最低音の C、23 は最高音の B である。

動作環境

ヘッダー : dmusici.h で宣言。


DMUS_SYNTHSTATS8

シンセサイザの現在の動作ステータスを取得するために、IDirectMusicPort8::GetRunningStats メソッドで使用される。

typedef struct DMUS_SYNTHSTATS {
    DWORD dwSize;
    DWORD dwValidStats;
    DWORD dwVoices;
    DWORD dwTotalCPU;
    DWORD dwCPUPerVoice;
    DWORD dwLostNotes;
    DWORD dwFreeMemory;
    long  lPeakVolume;
    DWORD   dwSynthMemUse;
} DMUS_SYNTHSTATS8;

typedef struct _DMUS_SYNTHSTATS8 *LPDMUS_SYNTHSTATS8;

メンバ

dwSize
構造体のサイズ。バイト単位で指定する。この構造体をメソッドに渡す前に、このメンバを sizeof(DMUS_SYNTHSTATS) に初期化しなければならない。
dwValidStats
シンセサイザが、この構造体内のどのフィールドに書き込みを行うかを指定するフラグ。次のフラグが定義されている。

DMUS_SYNTHSTATS_VOICES
DMUS_SYNTHSTATS_TOTAL_CPU
DMUS_SYNTHSTATS_CPU_PER_VOICE
DMUS_SYNTHSTATS_FREE_MEMORY
DMUS_SYNTHSTATS_LOST_NOTES
DMUS_SYNTHSTATS_PEAK_VOLUME

dwVoices
演奏中のボイス数の平均値。
dwTotalCPU
CPU 利用率に 100 を掛けた合計パーセンテージ。
dwCPUPerVoice
ボイスあたりの CPU 利用率に 100 を掛けたパーセンテージ。
dwLostNotes
失われたノートの数。ボイス スティーリングや過度に高い CPU 利用率が原因で、ノートが欠落することがある。
dwFreeMemory
DLS 音色を保存するために現在利用できるメモリの量。シンセサイザがシステム メモリを使用していて、利用可能なシステム メモリによりその量が制限を受ける場合、このフィールドは DMUS_SYNTHSTATS_SYSTEMMEMORY を保持する。
lPeakVolume
ピーク ボリューム。1/100dB (つまり mB) 単位で測定される。
dwSynthMemUse
シンセサイザ ウェーブ データで使用されるメモリ。

注意

dwFreeMemory を除き、動作中のすべてのステータス パラメータは 1 秒ごとに更新される。たとえば、dwLostNotes は、1 秒間に失われたノートの合計数を示す。

動作環境

ヘッダー : dmusici.h で宣言。


DMUS_TEMPO_PARAM

トラックがテンポ トラックであり、rguidType が GUID_TempoParam である場合、各種のパラメータ取得メソッドやパラメータ設定メソッドを呼び出す際に、pParam パラメータとして使用される。

typedef struct _DMUS_TEMPO_PARAM {
    MUSIC_TIME  mtTime;
    double      dblTempo;
} DMUS_TEMPO_PARAM;

メンバ

mtTime
テンポが取得された時間 (このメンバは set メソッドでは使用されず、代わりにメソッド自体の mtTime パラメータが使用される)。
dblTempo
DMUS_TEMPO_MIN ～ DMUS_TEMPO_MAX の範囲にあるテンポ。

動作環境

ヘッダー : dmusicf.h で宣言。

参照

IDirectMusicPerformance8::GetParam、IDirectMusicPerformance8::SetParam、IDirectMusicSegment8::GetParam、IDirectMusicSegment8::SetParam、IDirectMusicTrack8::GetParamEx、IDirectMusicTrack8::SetParamEx


DMUS_TIMESIGNATURE

スタイルの拍子記号に関する情報を取得するために、IDirectMusicStyle8::GetTimeSignature メソッドで使用される。この構造体は、rguidType パラメータが GUID_TimeSignature であり、トラックが拍子記号トラックまたはスタイル トラックである場合、DMUS_RHYTHM_PARAM 構造体やさまざまなパラメータ取得メソッドでも使用される。

typedef struct _DMUS_TIMESIGNATURE {
    MUSIC_TIME mtTime;
    BYTE  bBeatsPerMeasure;
    BYTE  bBeat;
    WORD  wGridsPerBeat;
} DMUS_TIMESIGNATURE;

メンバ

mtTime
この拍子記号が発生するミュージック タイム。
bBeatsPerMeasure
拍子記号の分子。
bBeat
拍子記号の分母。
wGridsPerBeat
拍あたりのグリッド (小分割)。この値は、特定の音楽イベントのタイミング分解能を決定する。たとえば、DMUS_SEGF_GRID フラグを使用したセグメントの挿入が挙げられる (「DMUS_SEGF_FLAGS」を参照)。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::GetParam、IDirectMusicPerformance8::SetParam、IDirectMusicSegment8::GetParam、IDirectMusicSegment8::SetParam、IDirectMusicTrack8::GetParamEx、IDirectMusicTrack8::SetParamEx、DMUS_TIMESIG_PMSG


DMUS_VALID_START_PARAM

rguidType が GUID_Valid_Start_Time である場合、各種のパラメータ取得メソッドを呼び出す際に pParam パラメータとして使用される。

typedef struct _DMUS_VALID_START_PARAM {
    MUSIC_TIME mtTime;
} DMUS_VALID_START_PARAM;

メンバ

mtTime
セグメントが開始できる、次の有効なポイント。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::GetParam、IDirectMusicSegment8::GetParam、IDirectMusicTrack8::GetParamEx


DMUS_VARIATIONS_PARAM

チャンネルに関連付けられたバリエーションに関する情報を保持する。GUID_Variations パラメータを取得する際に使用される。

typedef struct _DMUS_VARIATIONS_PARAM {
    DWORD   dwPChannelsUsed;
    DWORD*  padwPChannels;
    DWORD*   padwVariations;
} DMUS_VARIATIONS_PARAM;

メンバ

dwPChannelsUsed
使用中のパフォーマンス チャンネル番号を受け取る DWORD。
padwPChannels
使用中のパフォーマンス チャンネルを受け取る DWORD 値から成る配列のアドレス。
padwVariations
各チャンネルに対するエフェクトのバリエーションから成る配列。設定された各ビットがバリエーションを表す。

動作環境

ヘッダー : dmusici.h で宣言。


DMUS_VERSION

DMUS_OBJECTDESC 構造体に記述されたオブジェクトのバージョン情報を保持する。

typedef struct _DMUS_VERSION {
    DWORD  dwVersionMS;
    DWORD  dwVersionLS;
} DMUS_VERSION, FAR *LPDMUS_VERSION;

メンバ

dwVersionMS
バージョン番号の最上位 DWORD。
dwVersionLS
バージョン番号の最下位 DWORD。

動作環境

ヘッダー : dmusici.h で宣言。


DMUS_WAVES_REVERB_PARAMS

DirectX 7.0 で提供される Microsoft のソフトウェア シンセサイザのリバーブ エフェクトに関する情報を保持する。

typedef struct _DMUS_WAVES_REVERB_PARAMS {
    float  fInGain;
    float  fReverbMix;
    float  fReverbTime;
    float  fHighFreqRTRatio;
} DMUS_WAVES_REVERB_PARAMS;

メンバ

fInGain
(出力オーバーフローを防ぐための) 入力ゲイン。dB 単位で指定する。デフォルト値は 0 である。
fReverbMix
リバーブ ミックス。dB 単位で指定する。値が 0 の場合、100% ウェットなリバーブであることを意味する (ダイレクト シグナルはない)。負の値を指定すると、シグナルのウェット感は弱まる。係数が計算され、リバーブ ミックスの量に関係なく、全体的な出力レベルがほぼ一定に保たれる。デフォルト値は － 10.0 である。
fReverbTime
リバーブ ディケイ時間。ミリ秒 (ms) 単位で指定する。デフォルト値は 1,000 である。
fHighFreqRTRatio
高周波数とグローバル リバーブ時間の比率。特に明瞭なリバーブが必要でない限り、1 未満の値に設定すべきである。たとえば、fReverbTime が 1000 ms で、dHighFreqRTRatio が 0.1 の場合、高周波数のディケイ時間は 100 ms である。デフォルト値は 0.001 である。

注意

Waves 社の TrueVerb リバーブ テクノロジは、Microsoft にライセンス提供されており、Microsoft のソフトウェア シンセサイザで使用される SimpleVerb として実装されている。

DirectX 8.0 以降では、ミュージック リバーブは DMO で処理される。詳細については、「ウェーブ リバーブ」を参照すること。

動作環境

ヘッダー : dmusicc.h で宣言。


KSPROPERTY

プロパティと操作を識別するために、IKsControl::KsProperty メソッドで使用される。

KSPROPERTY は KSIDENTIFIER 構造体として定義され、次のように宣言される。

typedef struct {
    union {
        struct {
            GUID   Set;
            ULONG  Id;
            ULONG  Flags;
        };
        LONGLONG    Alignment;
    };
} KSIDENTIFIER, *PKSIDENTIFIER;

メンバ

設定
プロパティ セットの識別子。以下のプロパティセット GUID は、DirectMusic によって事前に定義されている。
GUID_DMUS_PROP_DLS1
項目 0 は、このポートが DLS レベル 1 サンプルのダウンロードをサポートするかどうかを示すブール値である。
GUID_DMUS_PROP_DLS2
項目 0 は、このポートが DLS レベル 2 サンプルのダウンロードをサポートするかどうかを示すブール値である。
GUID_DMUS_PROP_Effects
項目 0 は、DMUS_EFFECT_NONE または 1 つ以上のエフェクト フラグを含む (「DMUS_PORTCAPS」の「dwEffectFlags メンバ」を参照)。このプロパティを使用して、エフェクトの現在の状態を設定または取得する。
GUID_DMUS_PROP_GM_Hardware
項目 0 は、このポートがハードウェア内で GM をサポートするかどうかを示すブール値である。
GUID_DMUS_PROP_GS_Capable
項目 0 は、このポートが Roland GS 拡張の最低要件をサポートするかどうかを示すブール値である。
GUID_DMUS_PROP_GS_Hardware
項目 0 は、このポートがハードウェア内で Roland GS 拡張をサポートするかどうかを示すブール値である。
GUID_DMUS_PROP_INSTRUMENT2
項目 0 は、このポートが DMUS_ARTICULATION2 構造体を使用したサンプルのダウンロードをサポートするかどうかを示すブール値である。
GUID_DMUS_PROP_LegacyCaps
項目 0 は、このポートを実装している基盤の Windows マルチメディア デバイスを記述する MIDIINCAPS 構造体または MIDIOUTCAPS 構造体である。このポートの能力の構造体で dwClass が DMUS_PC_INPUTCLASS の場合、MIDIINCAPS 構造体が返される。それ以外の場合は MIDIOUTCAPS 構造体が返される。
GUID_DMUS_PROP_MemorySize
項目 0 は、このデバイス上のサンプル RAM の空きバイト数である。
GUID_DMUS_PROP_SampleMemorySize
項目 0 は、このデバイスで利用可能なサンプル RAM の空きバイト数と使用バイト数である。
GUID_DMUS_PROP_SamplePlaybackRate
項目 0 は、シンセサイザのサンプリング レートである。DLS レベル 2 ファイル形式は、条件付きチャンクをサポートするので、リージョンやアーティキュレーションをダウンロードすべきかどうかを判定できる。これにより、作成者は異なるサンプリング レートを使用することを意図したオプションのウェーブを作成できる。
GUID_DMUS_PROP_SynthSink_DSOUND
項目 0 は、このポートが DirectSound をサポートするかどうかを示すブール値である。
GUID_DMUS_PROP_SynthSink_WAVE
項目 0 は、このポートが waveOut 関数を使用してウェーブ出力をサポートするかどうかを示すブール値である。
GUID_DMUS_PROP_Volume
項目 1 (DMUS_ITEM_Volume) は、DMUS_VOLUME_MAX ～ DMUS_VOLUME_MIN の範囲の LONG 値である。符号付きの値で、1/100dB 単位で表す。この値は、すべての DLS アーティキュレーションが実行された後に、すべてのボイスのゲインに追加される。デフォルトでは、ポートをパフォーマンスに追加するとき、このプロパティはマスタ ボリュームに設定される。マスタ ボリュームについては、「グローバル パラメータの設定と取得」を参照すること。
GUID_DMUS_PROP_WavesReverb
項目 0 は、リバーブ パラメータを保持する DMUS_WAVES_REVERB_PARAMS 構造体である。
GUID_DMUS_PROP_WriteLatency
項目 0 は、ユーザーモード シンセサイザ (DMUS_PORTCAPS 構造体の dwType メンバは DMUS_PORT_USER_MODE_SYNTH) の書き込み遅延時間である。ユーザーモード シンセサイザは、その出力を DirectSound にストリーム化する。書き込み遅延時間とは、シンセサイザがサウンド バッファを作成してから、それが聞こえるまでの遅延時間を意味する。この値を調整することにより、アプリケーションはシンセサイザをより詳細にチューニングし、サウンドの分断のない最小遅延時間を設定できる。一部のコンピュータ、特に、DirectSound のハードウェア サポートのないコンピュータの場合、初期遅延時間はほかのコンピュータより非常に長くなる。そのため、値は常に最初に読み込まれるようにし、相対値を使用して調整しなければならない。書き込み遅延時間は、各ポート インスタンスについて異なる値を持つことができる。プロパティは、ポートをアクティブにするたびに設定しなければならない。アプリケーションでシンセサイザの書き込み遅延時間をオーディオパスに設定することは推奨されない。
GUID_DMUS_PROP_WritePeriod
項目 0 は、ユーザーモード シンセサイザ (DMUS_PORTCAPS 構造体の dwType メンバは DMUS_PORT_USER_MODE_SYNTH) の書き込み間隔である。ユーザーモード シンセサイザは、その出力を DirectSound にストリーム化する。書き込み間隔は、シンセサイザ シンクがシンセサイザのミキシングを許可する頻度を制御する。この値を減らすことによって、アプリケーションはシンセサイザの全体的な遅延時間を短縮できる。ただし、10 ミリ秒 (ms) より小さい値を指定すると、CPU の負荷が増加する。書き込み間隔は、標準的な DirectSound シンクを使用するすべてのポート インスタンスについて同じ値を持つ。プロパティは、ポートをアクティブにするたびに設定しなければならない。このプロパティは、オーディオパス内のポートに設定することはできない。
GUID_DMUS_PROP_XG_Capable
項目 0 は、このポートが Yamaha XG 拡張の最低要件をサポートするかどうかを示すブール値である。
GUID_DMUS_PROP_XG_Hardware
項目 0 は、このポートがハードウェア内で Yamaha XG 拡張をサポートするかどうかを示すブール値である。
Id
プロパティ セット内の項目。
フラグ
次のいずれかのフラグを使用して、操作を指定する。
KSPROPERTY_TYPE_GET
指定されたプロパティ項目の値を取得する。
KSPROPERTY_TYPE_SET
指定されたプロパティ項目の値を設定する。
KSPROPERTY_TYPE_BASICSUPPORT
プロパティ セット用に利用できるサポートのタイプを決定する。IKsControl::KsProperty が *pvPropertyData に返すデータは、KSPROPERTY_TYPE_GET と KSPROPERTY_TYPE_SET のどちらか、または両方を含む DWORD である。これは、その操作が可能であることを示す。
整列
DirectMusic では使用されない。

動作環境

ヘッダー : dmksctrl.h で宣言。

参照

DirectMusic ポートのプロパティ セット


DLS 構造体

ここでは、ダウンローダブル サウンドと共に使用される構造体のリファレンス情報について説明する。DirectMusic は、DLS コレクションのロードおよびシンセサイザへの音色のダウンロードで発生する細かい作業を処理するため、ほとんどのアプリケーションではこれらの構造体を使用する必要がない。これらの構造体は、主に DLS を編集するアプリケーション用に用意されている。

DLS データの使い方の概要については「下位レベル DLS」を参照すること。

DLS データ形式の詳細については、MMA (MIDI Manufacturers Association) の規格を参照すること。

ここでは、以下の構造体について説明する。

  • DMUS_ARTICPARAMS
  • DMUS_ARTICULATION
  • DMUS_ARTICULATION2
  • DMUS_COPYRIGHT
  • DMUS_DOWNLOADINFO
  • DMUS_EXTENSIONCHUNK
  • DMUS_INSTRUMENT
  • DMUS_LFOPARAMS
  • DMUS_MSCPARAMS
  • DMUS_OFFSETTABLE
  • DMUS_PEGPARAMS
  • DMUS_REGION
  • DMUS_VEGPARAMS
  • DMUS_WAVE
  • DMUS_WAVEARTDL
  • DMUS_WAVEDATA
  • DMUS_WAVEDL


DMUS_ARTICPARAMS

DLS レベル 1 アーティキュレーション チャンクのパラメータを記述する。アーティキュレーションに関するすべてのパラメータは 1 つのチャンクに保存されるが、このチャンクは一連の構造体によって構成されており、各構造体はアーティキュレーションの各機能分野について定義している。音色やリージョンがアーティキュレーションを利用する場合、DMUS_ARTICULATION チャンクからのインデックスを使用して、このチャンクを参照する。

typedef struct {
    DMUS_LFOPARAMS LFO;
    DMUS_VEGPARAMS VolEG;
    DMUS_PEGPARAMS PitchEG;
    DMUS_MSCPARAMS Misc;
} DMUS_ARTICPARAMS;

メンバ

LFO
低周波数発振器 (オシレータ) 用のパラメータを保持する DMUS_LFOPARAMS 構造体。
VolEG
ボリューム エンベロープ ジェネレータ用のパラメータを保持する DMUS_VEGPARAMS 構造体。
PitchEG
ピッチ エンベロープ ジェネレータ用のパラメータを保持する DMUS_PEGPARAMS 構造体。
Misc
最初のパン位置を保持する DMUS_MSCPARAMS 構造体。

注意

DLS レベル 2 アーティキュレーションは別途処理され、この構造体を使用しない。「DMUS_ARTICULATION2」を参照すること。

動作環境

ヘッダー : dmdls.h で宣言。


DMUS_ARTICULATION

DLS 音色のアーティキュレーション チャンクについて記述する。DMUS_DOWNLOADINFO 構造体の dwDLType メンバ内のフォーマット識別子が、DMUS_DOWNLOADINFO_INSTRUMENT である場合に使用される。このチャンクは、利用可能なすべてのアーティキュレーション データを 1 つのリスト内に保持できる。たとえば、DLS レベル 1 チャンクとあるメーカー固有のアーティキュレーション チャンクを保持できる。DLS チャンクは ulArt1Idx により参照され、追加のアーティキュレーション チャンクはすべて ulFirstExtCkIdx で始まるリストによって参照される。

typedef struct {
    ULONG ulArt1Idx;
    ULONG ulFirstExtCkIdx;
} DMUS_ARTICULATION;

メンバ

ulArt1Idx
DMUS_OFFSETTABLE 構造体内にある、DLS アーティキュレーション チャンクのインデックス。この値が 0 の場合、DLS アーティキュレーションは存在しない。
ulFirstExtCkIdx
最初のサードパーティ拡張チャンクのインデックス。この値が 0 の場合、このアーティキュレーションに関連するサードパーティ拡張チャンクは存在しない。

注意

アーティキュレーション チャンクは、DMUS_ARTICPARAMS 構造体から成る。

動作環境

ヘッダー : dmdls.h で宣言。

参照

DMUS_ARTICULATION2


DMUS_ARTICULATION2

DLS 音色のアーティキュレーション チャンクについて記述する。DMUS_DOWNLOADINFO 構造体の dwDLType メンバ内のフォーマット識別子が、DMUS_DOWNLOADINFO_INSTRUMENT2 である場合に使用される。DLS レベル 1 チャンクは ulArt1Idx により参照され、追加のアーティキュレーション チャンクはすべて ulFirstExtCkIdx で始まるリストによって参照される。DLS レベル 2 アーティキュレーション チャンクは、ulNextArtIdx も使用する。

typedef struct {
    ULONG ulArt1Idx;
    ULONG ulFirstExtCkIdx;
    ULONG ulNextArtIdx;
} DMUS_ARTICULATION;

メンバ

ulArt1Idx
DMUS_OFFSETTABLE 構造体内にある、DLS アーティキュレーション チャンクのインデックス。この値が 0 の場合、DLS レベル 1 またはレベル 2 アーティキュレーションは存在しない。
ulFirstExtCkIdx
最初のサードパーティ拡張チャンクのインデックス。この値が 0 の場合、このアーティキュレーションに関連するサードパーティ拡張チャンクは存在しない。DLS レベル 2 チャンクは、ここに置くこともできる。
ulNextArtIdx
DLS レベル 2 アーティキュレーションをより深くサポートするための追加のアーティキュレーション チャンクのインデックス。

注意

アーティキュレーション チャンクは、CONNECTIONLIST 構造体と、それに続く CONNECTION 構造体の配列で構成される。これらの構造体は Dls1.h で宣言される。詳細については、MMA (MIDI Manufacturers Association) が発行する DLS レベル 2 規格を参照すること。

動作環境

ヘッダー : dmdls.h で宣言。

参照

DMUS_ARTICULATION


DMUS_COPYRIGHT

DLS データ内にオプションの著作権チャンクを記述する。

typedef struct {
    ULONG cbSize;
    BYTE  byCopyright[ ];
} DMUS_COPYRIGHT;

メンバ

cbSize
データのサイズ。
byCopyright[ ]
著作権データ。

動作環境

ヘッダー : dmdls.h で宣言。


DMUS_DOWNLOADINFO

ポートにダウンロードされる DLS データのヘッダーとして使用される。この構造体はダウンロードのサイズと機能を定義し、その後には常に DMUS_OFFSETTABLE チャンクが続く。

typedef struct _DMUS_DOWNLOADINFO {
    DWORD dwDLType;
    DWORD dwDLId;
    DWORD dwNumOffsetTableEntries;
    DWORD cbSize;
} DMUS_DOWNLOADINFO;

メンバ

dwDLType
ダウンロードされるデータ タイプ。次のタイプが定義されている。
DMUS_DOWNLOADINFO_INSTRUMENT
DMUS_INSTRUMENT 構造体から始まる音色の定義。
DMUS_DOWNLOADINFO_INSTRUMENT2
DMUS_INSTRUMENT 構造体から始まる、DLS レベル 2 アーティキュレーションをサポートする音色の定義。
DMUS_DOWNLOADINFO_WAVE
DMUS_WAVE 構造体から始まる PCM ウェーブのデータ。
dwDLId
オブジェクトの一意の 32 ビット識別子。「注意」を参照すること。
dwNumOffsetTableEntries
後に続く DMUS_OFFSETTABLE 構造体内のエントリの数。
cbSize
DMUS_DOWNLOADINFO、DMUS_OFFSETTABLE、および実際のデータ チャンクの合計サイズ。

注意

dwDLId 内の識別子は、オブジェクトを接続するために使用され、IDirectMusicPortDownload8::GetDLId メソッドを使用して取得される。主に、音色内のリージョンをウェーブ チャンクに結合する。たとえば、ウェーブ ダウンロードに 3 の dwDLId を指定した場合、音色チャンクは、いずれかの DMUS_REGION 構造体の WaveLink.ulTableIndex メンバに値 3 を配置された形でダウンロードされる。これは、リージョンがウェーブ チャンクに接続されていることを示す。

動作環境

ヘッダー : dmdls.h で宣言。

参照

下位レベル DLS


DMUS_EXTENSIONCHUNK

DLS 拡張チャンクを記述する。DirectMusic にとって未知の拡張を DLS ファイル フォーマットに加えた場合、これらの拡張すべてをこの可変サイズのチャンクでダウンロードする。

typedef struct {
    ULONG  cbSize;
    ULONG  ulNextExtCkIdx;
    FOURCC ExtCkID;
    BYTE   byExtCk[ ];
} DMUS_EXTENSIONCHUNK;

メンバ

cbSize
チャンクのサイズ。
ulNextExtCkIdx
DMUS_OFFSETTABLE 構造体内にある、次の拡張チャンクのインデックス。この値が 0 の場合、サードパーティの拡張チャンクはそれ以上存在しない。
ExtCkID
チャンク識別子。
byExtCk[ ]
データ。

動作環境

ヘッダー : dmdls.h で宣言。


DMUS_INSTRUMENT

DLS ダウンロード チャンク内の音色定義を保持する。

typedef struct {
    ULONG ulPatch;
    ULONG ulFirstRegionIdx;
    ULONG ulGlobalArtIdx;
    ULONG ulFirstExtCkIdx;
    ULONG ulCopyrightIdx;
    ULONG ulFlags;
} DMUS_INSTRUMENT;

メンバ

ulPatch
音色のパッチ番号。
ulFirstRegionIdx
音色内の最初のリージョン チャンク (「DMUS_REGION」を参照) のインデックス。これは常に 1 つのリージョンとすべきであるが、将来のシンセサイザ アーキテクチャとの互換性を考慮して、このメンバの値を 0 にすることも認められる。
ulGlobalArtIdx
DMUS_OFFSETTABLE 構造体内にある、音色のグローバル アーティキュレーション チャンク (「DMUS_ARTICULATION」および「DMUS_ARTICULATION2」を参照) のインデックス。この値が 0 の場合、この音色にはグローバル アーティキュレーションがない。
ulFirstExtCkIdx
DMUS_OFFSETTABLE 構造体内にある、最初の拡張チャンク (「DMUS_EXTENSIONCHUNK」を参照) のインデックス。DirectMusic が認識していない新しいチャンクを追加するために使用される。この値が 0 の場合、この音色にはサードパーティの拡張が関連付けられていない。
ulCopyrightIdx
DMUS_OFFSETTABLE 構造体内にある、オプションの著作権チャンク (「DMUS_COPYRIGHT」を参照) のインデックス。この値が 0 の場合、この音色には著作権情報が関連付けられていない。
ulFlags
音色の追加のフラグ。次のフラグが定義されている。
DMUS_INSTRUMENT_GM_INSTRUMENT
この音色は General MIDI 標準の音色である。パッチが重複している場合、GM 音色の優先順位は必ずほかの DLS 音色より低くなる。たとえば、パッチ 0 を指定して GM 音色をダウンロードし、同じくパッチ 0 を指定して GM 以外の音色をダウンロードした場合、再生の際に必ず GM 以外の音色が選択される。

動作環境

ヘッダー : dmdls.h で宣言。


DMUS_LFOPARAMS

DLS アーティキュレーション チャンク用の低周波数発振器 (LFO) を定義する。DMUS_ARTICPARAMS 構造体で使用される。

typedef struct {
    PCENT pcFrequency;
    TCENT tcDelay;
    GCENT gcVolumeScale;
    PCENT pcPitchScale;
    GCENT gcMWToVolume;
    PCENT pcMWToPitch;
} DMUS_LFOPARAMS;

メンバ

pcFrequency
周波数。ピッチ単位で指定する。「注意」を参照すること。
tcDelay
初期のディレイ。タイムセント (time cent) 単位で指定する。「注意」を参照すること。
gcVolumeScale
トレモロを制御する出力スケール。減衰単位で指定する。「注意」を参照すること。
pcPitchScale
ビブラートを制御する LFO 出力スケール。ピッチ単位で指定する。「注意」を参照すること。
gcMWToVolume
トレモロを制御するモジュレーション ホイール範囲。減衰単位で指定する。「注意」を参照すること。
pcMWToPitch
トレモロを制御するモジュレーション ホイール範囲。減衰単位で指定する。「注意」を参照すること。

注意

DLS レベル 1 規格は、タイム セント、ピッチ セント、および減衰を 32 ビット対数値として定義する。詳細については、MMA (MIDI Manufacturers Association) の規格を参照すること。

動作環境

ヘッダー : dmdls.h で宣言。

参照

DMUS_ARTICPARAMS


DMUS_MSCPARAMS

DLS レベル 1 アーティキュレーション チャンクのパンを定義する。この構造体は、DMUS_ARTICPARAMS 構造体で使用される。

typedef struct {
    PERCENT ptDefaultPan;
} DMUS_MSCPARAMS;

メンバ

ptDefaultPan
デフォルトのパン。－ 50% ～ 50% の範囲を 0.1% 単位で指定し、16 ビット左シフトしたもの。

注意

PERCENT は long として定義される。パンの値については、MMA (MIDI Manufacturers Association) の規格を参照すること。

動作環境

ヘッダー : dmdls.h で宣言。

参照

DMUS_ARTICPARAMS


DMUS_OFFSETTABLE

ポートにダウンロード中の DLS 音色データのヘッダーで使用される。

typedef struct _DMUS_OFFSETTABLE {
    ULONG ulOffsetTable[DMUS_DEFAULT_SIZE_OFFSETTABLE];
} DMUS_OFFSETTABLE;

メンバ

ulOffsetTable
データのバイト オフセットの配列。

動作環境

ヘッダー : dmdls.h で宣言。

参照

下位レベル DLS


DMUS_PEGPARAMS

DLS レベル 1 アーティキュレーション チャンクのピッチ エンベロープを定義する。DMUS_ARTICPARAMS 構造体で使用される。

typedef struct {
    TCENT   tcAttack;
    TCENT   tcDecay;
    PERCENT ptSustain;
    TCENT   tcRelease;
    TCENT   tcVel2Attack;
    TCENT   tcKey2Decay;
    PCENT   pcRange;
} DMUS_PEGPARAMS;

メンバ

tcAttack
アタック時間。タイム セント (time cent) 単位で指定する。「注意」を参照すること。
tcDecay
ディケイ時間。タイム セント単位で指定する。「注意」を参照すること。
ptSustain
サステイン。16 ビット左シフトしたパーセント表示の 1/100 を単位として使用する。
tcRelease
リリース時間。タイム セント単位で指定する。「注意」を参照すること。
tcVel2Attack
アタック期間のベロシティ。タイム セント単位で指定する。「注意」を参照すること。
tcKey2Decay
ディケイ期間のキー。タイム セント単位で指定する。「注意」を参照すること。
pcRange
エンベロープ範囲。ピッチ単位で指定する。「注意」を参照すること。

注意

DLS レベル 1 規格は、タイム セントとピッチ セントを 32 ビット対数値として定義する。この構造体内の値については、MMA (MIDI Manufacturers Association) の規格を参照すること。

動作環境

ヘッダー : dmdls.h で宣言。

参照

DMUS_ARTICPARAMS


DMUS_REGION

DLS ダウンロード用のリージョンを定義する。1 つまたは複数のリージョンを 1 つの音色バッファに埋め込み、音色ヘッダー チャンク DMUS_INSTRUMENT によって参照できる。

typedef struct {
    RGNRANGE RangeKey;
    RGNRANGE RangeVelocity;
    USHORT   fusOptions;
    USHORT   usKeyGroup;
    ULONG    ulRegionArtIdx;
    ULONG    ulNextRegionIdx;
    ULONG    ulFirstExtCkIdx;
    WAVELINK WaveLink;
    WSMPL    WSMP;
    WLOOP    WLOOP[1];
} DMUS_REGION;

メンバ

RangeKey
このリージョンのキー範囲。
RangeVelocity
このリージョンのベロシティ範囲。
fusOptions
このリージョンの合成オプション。次のフラグが定義されている。
F_RGN_OPTION_SELFNONEXCLUSIVE
合成エンジンが同じノートの 2 回目のノートオンを受け取ると、2 番目のノートは最初のノートと同様に演奏される。デフォルトではこのオプションはオフになっているので、合成エンジンは最初のノートにノートオフを強制的に適用する。
usKeyGroup
ドラム楽器のキー グループ。キー グループの値により、同じグループに所属する 1 つのドラム楽器内で複数のリージョンを利用できる。あるキー グループを指定してあるノートを演奏しているときに、同じキー グループを指定してほかのノートを演奏するよう合成エンジンが指示を受けた場合、合成エンジンは同じキー グループの値を持つほかのすべてのノートをできるだけ早くオフにすべきである。現在、キー グループ 1 ～ 15 が有効であり、0 はキー グループが存在しないことを意味する。
ulRegionArtIdx
DMUS_OFFSETTABLE 構造体内にある、リージョンのグローバル アーティキュレーション チャンクのインデックス。この値が 0 の場合、リージョンはアーティキュレーションを保持せず、音色のグローバル アーティキュレーションに依存する。
ulNextRegionIdx
DMUS_OFFSETTABLE 構造体内にある、リージョン リスト内の次のリージョンのインデックス。この値が 0 の場合、それ以上リージョンはない。
ulFirstExtCkIdx
DMUS_OFFSETTABLE 構造体内にある、サードパーティ拡張チャンクのインデックス。この値が 0 の場合、リージョンには拡張チャンクが関連付けられていない。
WaveLink
リージョンからウェーブへのリンクを管理する、標準的な DLS 構造体 (Dls1.h ヘッダー ファイル内で宣言されている)。WAVELINK 構造体の ulTableIndex メンバは、関連付けられたウェーブ バッファのダウンロード識別子を提供する (詳細については、「DMUS_DOWNLOADINFO」と「下位レベル DLS」を参照すること)。
WSMP
ウェーブの再生を管理する、標準的な DLS 構造体 (Dls1.h 内で宣言されている )。cSampleLoops メンバが 1 の場合、続く WLOOP 構造体はループの開始ポイントと終了ポイントを保持する。
WLOOP[ ]
ループを記述する、標準的な DLS 構造体 (Dls1.h 内で宣言されている )。

動作環境

ヘッダー : dmdls.h で宣言。


DMUS_VEGPARAMS

DLS レベル 1 アーティキュレーション チャンクのボリューム エンベロープを定義する。

typedef struct {
    TCENT   tcAttack;
    TCENT   tcDecay;
    PERCENT ptSustain;
    TCENT   tcRelease;
    TCENT   tcVel2Attack;
    TCENT   tcKey2Decay;
} DMUS_VEGPARAMS;

メンバ

tcAttack
アタック時間。タイム セント (time cent) 単位で指定する。「注意」を参照すること。
tcDecay
ディケイ時間。タイム セント単位で指定する。「注意」を参照すること。
ptSustain
サステイン。16 ビット左シフトしたパーセント表示の 1/100 を単位として使用する。
tcRelease
リリース時間。タイム セント単位で指定する。「注意」を参照すること。
tcVel2Attack
アタック期間のベロシティ。タイム セント単位で指定する。「注意」を参照すること。
tcKey2Decay
ディケイ期間のキー。タイム セント単位で指定する。「注意」を参照すること。

注意

DLS レベル 1 規格は、タイム セントを 32 ビット対数値として定義する。この構造体内の値については、MMA (MIDI Manufacturers Association) の規格を参照すること。

動作環境

ヘッダー : dmdls.h で宣言。

参照

DMUS_ARTICPARAMS


DMUS_WAVE

DLS ダウンロード用のウェーブ チャンクを定義する。

typedef struct {
    ULONG  ulFirstExtCkIdx;
    ULONG  ulCopyrightIdx;
    ULONG  ulWaveDataIdx;
    WAVEFORMATEX  WaveformatEx;
} DMUS_WAVE;

メンバ

ulFirstExtCkIdx
DMUS_OFFSETTABLE 構造体内にある、サードパーティ拡張チャンクのインデックス。この値が 0 の場合、ウェーブには拡張チャンクが関連付けられていない。
ulCopyrightIdx
DMUS_OFFSETTABLE 構造体内にある、著作権チャンクのインデックス。この値が 0 の場合、ウェーブには著作権情報が関連付けられていない。
ulWaveDataIdx
DMUS_OFFSETTABLE 構造体内にある、ウェーブ データのインデックス。「DMUS_WAVEDATA」を参照すること。
WaveformatEx
チャンクのウェーブ フォーマットを指定する WAVEFORMATEX 構造体。

動作環境

ヘッダー : dmdls.h で宣言。


DMUS_WAVEARTDL

ウェーブ アーティキュレーションをダウンロードするための情報を保持する。

typedef struct _DMUS_WAVEARTDL {
    ULONG   ulDownloadIdIdx;
    ULONG   ulBus;
    ULONG   ulBuffers;
    ULONG   ulMasterDLId;
    USHORT  usOptions
}   DMUS_WAVEARTDL, *LPDMUS_WAVEARTDL;

メンバ

ulDownloadIdIdx
各バッファのダウンロード識別子。
ulBus
再生バス。
ulBuffers
バッファ。
ulMasterDLId
下位グループのマスタ音のダウンロード識別子。
usOptions
DLS 2 リージョン オプション。

動作環境

ヘッダー : dmdls.h で宣言。


DMUS_WAVEDATA

DLS ウェーブ ダウンロード用のデータ チャンクを保持する。ウェーブ データの性質は、DMUS_WAVE 構造体の WaveformatEx メンバによって定義される。

typedef struct {
    ULONG cbSize;
    BYTE byData[ ];
} DMUS_WAVEDATA;

メンバ

cbSize
データのサイズ。
byData[ ]
PCM ウェーブ データ。

動作環境

ヘッダー : dmdls.h で宣言。


DMUS_WAVEDL

シンセサイザにダウンロードされるウェーブ データに関する情報を保持する。

typedef struct _DMUS_WAVEDL {
    ULONG  cbWaveData;
}   DMUS_WAVEDL, *LPDMUS_WAVEDL;

メンバ

cbWaveData
ウェーブ データのバイト数。

動作環境

ヘッダー : dmdls.h で宣言。


DirectMusic のファイル形式

ここでは、DirectMusic Producer で作成され、IDirectMusicLoader8::GetObject または IDirectMusicLoader8::LoadObjectFromFile が呼び出されたときに DirectMusic によって読み取られる、ファイルの形式について説明する。ほとんどのアプリケーションでは、これらのファイルを直接解析することはない。このファイル形式の情報は、ミュージック オーサリング アプリケーションや DirectMusic プラグインの開発者が、データを互換性のある形式で保存したり、独自のオブジェクトにデータをロードできるようにするために提供されている。

DirectMusic データは、RIFF (Resource Interchange File Format) で保存される。以下のトピックは、RIFF ファイルに関する一般的な情報で構成される。

  • RIFF について
  • RIFF の表記法

以下のトピックでは、DirectMusic データが RIFF チャンク内でどのように編成されるかを説明する。

  • 共通のチャンク
  • オーディオパス形式
  • バンド形式
  • コード マップ形式
  • コンテナ形式
  • DirectSound バッファ構成形式
  • エフェクト形式
  • 参照リスト
  • スクリプト形式
  • セグメント形式
  • ソング形式
  • スタイル形式
  • ツール形式
  • ツールグラフ形式
  • トラック形式
  • ウェーブ ヘッダー チャンク

次のトピックは、RIFF チャンクにデータを格納するために使用される構造体のリファレンスである。

  • DirectMusic のファイル データ構造体


RIFF について

RIFF ファイルの基本的な構成単位は "チャンク" である。チャンクは、データの論理的な単位である。各チャンクには、次のフィールドが含まれている。

  • チャンク識別子を表す、4 文字のコード (FOURCC)。慣習的に、チャンク タイプの登録には大文字を使い、それ以外では小文字を使う。
  • チャンクのデータ メンバのサイズを指定する DWORD 値。
  • データ。

ほかのチャンクに含まれているチャンクを、"サブチャンク" と呼ぶ。サブチャンクを含むことができるチャンクは、チャンク識別子が RIFF または LIST のチャンクだけである。

ファイルの最初のチャンクは、RIFF として識別されなければならない。ファイル内のその他のチャンクはすべて、このチャンクのサブチャンクとなる。RIFF チャンクは、形式とも呼ばれる。

LIST チャンクは、サブチャンクをグループ化したものである。これらのサブチャンクのいくつかは繰り返し現れる場合があるが、LIST は配列ではない。用語が紛らわしいこともある。たとえば、<part-list> というラベルの付いたチャンクは、パートのリストであると予想するかもしれないが、実際には、"パート" チャンクの要素のリストであり、1 つのパートを示している。

RIFF チャンクでは、データ フィールドの最初の 4 バイトに追加フィールドが含まれる。追加フィールドでは、チャンクの形式タイプが提供される。形式タイプは、ファイルに格納されるデータの形式を識別する、4 文字のコードである。たとえば、DirectMusic のスタイルの形式タイプは DMST である。

LIST チャンクも、データ フィールドの最初の 4 バイトに追加フィールドを含んでいる。このフィールドには、フィールドの "リスト タイプ" が含まれる。リスト タイプは、リストの内容を識別する 4 文字のコードである。たとえば、DirectMusic のスタイルは、パフォーマンスの特定のパート (音色トラック) に関するデータを含む、リスト タイプが "part" の LIST チャンクを持っている。

注 DirectMusic ファイルで使用されているすべての FOURCC コードには、対応するマクロが Dmusicf.h に用意されている。たとえば、DMST の FOURCC は、DMUS_FOURCC_STYLE_FORM マクロによって返される。

一般的な RIFF ファイルの詳細については、Platform SDK ドキュメントの「Resource Interchange File Format Services」を参照すること。


RIFF の表記法

次の DirectMusic ファイルの説明は、従来の RIFF ファイルの表記法のサブセットを使用している。この表記法の主な部分を、次の表に示す。

表記法 | 説明
<element> | "element" というラベルの付いたファイル要素、または element タイプ
[ <element> ] | オプションのファイル要素
<element>... | 指定した要素の 1 つまたは複数のコピー
[<element>]... | 指定した要素の 0 以上のコピー
name、'name'、NAME、または 'NAME' | 形式タイプ、リスト タイプ、またはチャンクの FOURCC 識別子
// コメント | コメント

ラベルは表記法でのみ使用され、ファイル自体では使用されない。<cheh-ck> というラベルは、固有の FOURCC 識別子および形式を持つチャンクを参照する。この種類のチャンクが表記法に現れる場合は、同じラベルが使用される。

ラベルに関連付けられたデータまたはサブ要素は、次の例のように表される。

<cheh-ck> -> cheh( <DMUS_IO_CHORDENTRY> )

この表記法は、<cheh-ck> というラベルの付いたチャンクが、FOURCC 識別子の "cheh" と、それに続く DMUS_IO_CHORDENTRY 構造体で構成されていることを表す。

注 すべてのチャンク内のデータには、先頭に、データのサイズを示す DWORD 値が付いている。この要素は表記法では示されない。

次の例は、リスト要素を示している。FOURCC "LIST" とリスト識別子の "cmap"、および <choe-list> というラベルの付いた 1 つまたは複数の要素で構成されている。<choe-list> 要素は、ほかの場所に展開される。

<cmap-list> -> LIST( 'cmap'
    <choe-list>... )


共通のチャンク

次のチャンクは、さまざまなリスト チャンクや形式で使用される。

<guid-ck>

これは、要素の GUID 識別子である。

<guid-ck> -> guid( <GUID> )

<vers-ck>

このチャンクには、要素のバージョン情報が含まれる。

<vers-ck> -> vers( <DMUS_IO_VERSION> )

<UNFO-list>

UNFO チャンクは、RIFF INFO リストに似ている。ただし、Unicode 文字を使う点が異なっている。INFO および UNFO リストは、NULL で終了する文字列を含む、さまざまなチャンクで構成される。

<UNFO-list> -> LIST( 'UNFO'
    <unfo-text-ck>...
    )

参照

参照リスト


オーディオパス形式

次の表記法は、オーディオパス形式の編成を示している。

RIFF( 'DMAP'
    [<guid-ck>]        // パスの GUID
    [<vers-ck>]        // バージョン情報
    [<UNFO-list>]      // 名前、作者、著作権、コメント
    [<DMTG-form>]      // ツールグラフ
    [<pcsl-list>]      // ポート構成
    [<dbfl-list>]...// DirectSound バッファ ディスクリプタ
)

すべての要素が省略可能である。

<guid-ck>、<vers-ck>、<UNFO-list>

これらの 3 つのチャンクについては、「共通のチャンク」を参照すること。

<DMTG-form>

「ツールグラフ形式」を参照すること。

<pcsl-list>

このリストには、ポートの構成に関する情報が格納される。

<pcsl-list> -> LIST( 'pcsl'
    <pcfl-list>...
    )

ポート構成リストは、次の形式のリストの配列である。

LIST( 'pcfl'
    <pcfh-ck>          // ヘッダー チャンク
    <pprh-ck>          // ポートの作成に使われるポート パラメータ
    [<dbfl-list>]...// DirectSound バッファ ディスクリプタ
    [<pchl-list>]      // P チャンネルのバッファへの割り当て
    )

ポート構成リストは複数のチャンクで構成され、次のようにポート構成とパラメータを表すヘッダーが先頭に付く。

<pcfh-ck> -> pcfh( <DMUS_IO_PORTCONFIG_HEADER> )

<pprh-ck> -> pprh( <DMUS_PORTPARAMS8> )

オプションのバッファ ディスクリプタは、次の形式で各チャンク内に格納される。

<dbfl-list> -> LIST( 'dbfl'
    <ddah-ck>       // バッファ属性ヘッダー
    [<DSBC-form>]   // バッファ構成
)

バッファ記述リストの先頭には、バッファの属性を表すヘッダーが付く。

<ddah-ck> -> ( 'ddah' < DMUS_IO_BUFFER_ATTRIBUTES_HEADER > )

ヘッダーの後には、オプションの DirectSound バッファ構成形式が続く。これは標準バッファ形式には不要である。

ポート構成リストの最後のチャンクは、バッファへのパフォーマンス チャンネルの割り当て情報を格納するリストである。

pchl-list -> LIST( 'pchl'
    <pchh-ck>...
)

このリストは、それぞれがバッファへのチャンネルの 1 つの割り当てを表すチャンクの配列である。

<pchh-ck> -> pchh(
    <DMUS_IO_PCHANNELTOBUFFER_HEADER>
    <GUID>...// バッファを指定する GUID の配列
)

<dbfl-list>

オーディオパス形式の最後の部分には、オプションのバッファ ディスクリプタが、ポート構成リスト <pcsl-list> と同じ形式で格納される。


バンド形式

次の表記法は、バンド ファイルの最上位レベルのチャンクまたは形式を示している。バンド形式は、ほかのチャンクに含めることもできる。

RIFF( 'DMBD'
    [<guid-ck>]     // バンドの GUID
    [<vers-ck>]     // オプションのバージョン情報
    [<UNFO-list>]   // 名前、作者、著作権情報、コメント
    <lbil-list>     // 音色
    )

<guid-ck>、<vers-ck>、<UNFO-list>

これらの 3 つのチャンクについては、「共通のチャンク」を参照すること。

<lbil-list>

データは、リストの配列に含まれる。

<lbil-list> -> LIST( 'lbil'
    <lbin-list>...
    )

各音色は、リスト中に次の形式で記述される。

<lbin-list> -> LIST( 'lbin'
    <bins-ck>
    [<DMRF-list>]
    )

音色リスト内で、次のチャンクには音色を表すヘッダーが含まれる。

<bins-ck> -> bins( <DMUS_IO_INSTRUMENT> )

音色リストには、<DMRF-list> を含めることもできる。この場合は、DLS ファイルへの参照である。「参照リスト」を参照すること。


コード マップ形式

次の表記法は、コード マップ ファイルの最上位レベルのチャンク、または形式の構成を示している。

RIFF( 'DMPR'
    <perh-ck>       // コード マップ ヘッダー チャンク
    [ <guid-ck> ]   // GUID チャンク
    [ <vers-ck> ]   // バージョン チャンク
    [ <UNFO-list> ] // UNFO リスト
    <chdt-ck>       // コード データ チャンク
    <chpl-list>     // コード パレット
    <cmap-list>     // コード グラフ
    <spsq-list>     // サインポスト リスト
)

<perh-ck>

これは、コード マップの基本的なヘッダー情報である。

<perh-ck> -> perh( <DMUS_IO_CHORDMAP> )

<guid-ck>、<vers-ck>、<UNFO-list>

これらの 3 つのチャンクについては、「共通のチャンク」を参照すること。

<chdt-ck>

<chdt-ck> -> chdt(
    <WORD>    // DMUS_IO_CHORDMAP_SUBCHORD のサイズ
    <DMUS_IO_CHORDMAP_SUBCHORD>...
    )

<chdt-ck> チャンクには、サブコードあたりのバイト数を表す WORD 値と、固有のサブコードの配列が含まれる。このファイルのほかのパートで参照されているサブコード識別子はすべて、この配列のインデックスに直接対応する。

<chpl-list>

<chpl-list> -> LIST( 'chpl'
    <chrd-list>...
    )

このリストにはコード パレットが含まれる。このリストには 24 の項目が必要である。

<chrd-list> -> LIST( 'chrd'
    <UNAM-ck>    // コード名
    <sbcn-ck>    // サブコードのインデックス
    )

このリストには、基本的なコード情報が含まれる。この情報は、コードの名前と、準拠するサブコードの識別子のリストである。

<UNAM-ck> -> UNAM ( <WCHAR>... )

UNAM チャンクは、コードの名前を格納する。

<sbcn-ck> -> sbcn( <WORD>... )

"sbcn" チャンクには、1 つまたは複数のサブコード識別子が含まれる。これらは、<chdt-ck> にある配列のインデックスに直接対応する。最大で 4 つのコードがサポートされている。

<cmap-list>

このリストには、コード マップのコード接続グラフ全体が含まれる。コード マップの大部分のデータは、このチャンクに存在する。

<cmap-list>  ->  LIST( 'cmap'
    <choe-list>...
    )

各リストには、コード グラフの 1 つのエントリのデータと、次にコード グラフに現れるすべてのコードへのポインタが含まれる。

<choe-list> -> LIST( 'choe'
    <cheh-ck>      // コード エントリ データ
    <chrd-list>    // コード データ。上の説明を参照
    <ncsq-ck>      // 次のコード リスト
    )

<cheh-ck> -> cheh( <DMUS_IO_CHORDENTRY> )

これは、コード エントリ ヘッダーである。構造体の識別子は、コード接続グラフの識別子であり、サブコード識別子ではない。

<ncsq-ck> -> ncsq (
    <WORD>         // DMUS_IO_NEXTCHORD のサイズ
    <DMUS_IO_NEXTCHORD>...
    )

"ncsq" チャンクには、接続グラフのコードを別のコードに接続するデータが含まれる。接続グラフの各コードは、16 ビットの識別子で表される。

<spsq-list>

このチャンクには、各サインポストのデータが含まれる。

<spsq-list> -> LIST( 'spsq'
    <spst-list>...
    )

<spst-list> リストには、1 つのサインポストのデータが含まれる。データは、ヘッダー、コード情報、およびオプションのカデンツァ コードで構成される。

<spst-list>  ->  LIST( 'spst'
    <spsh-ck>
    <chrd-list>     // コード データ
    [ <cade-list> ] // カデンツァ コード
    )

<spsh-ck> リストには、サインポスト データが含まれる。

<spsh-ck> -> spsh( <DMUS_IO_CHORDMAP_SIGNPOST> )

<chrd-list> については、前に説明した <chpl-list> を参照すること。

<cade-list> チャンクには、カデンツァ コードの情報が含まれる。このリストでは 2 つまでのカデンツァ コードがサポートされている。3 つ以上のコードは無視される。

<cade-list> -> LIST( 'cade'
    <chrd-list>...
    )


コンテナ形式

コンテナ形式は、セグメントまたはスタイル形式など、ほかのチャンクを格納するチャンクである。セグメント ファイルやスクリプト ファイルに含めることができる。構造は次のとおりである。

RIFF ( 'DMCN'
    <conh-ck>       // コンテナ ヘッダー チャンク
    [<guid-ck>]     // コンテナの GUID
    [<vers-ck>]     // オプションのバージョン情報
    [<UNFO-list>]   // 名前、作者、著作権情報、コメント
    <cosl-list>     // オブジェクトのリスト
)

<conh-ck>

このチャンクには、ヘッダー構造が含まれる。

<conh-ck> -> 'conh' ( <DMUS_IO_CONTAINER_HEADER> )

<guid-ck>、<vers-ck>、<UNFO-list>

これらの 3 つのチャンクについては、「共通のチャンク」を参照すること。

<cosl-list>

コンテナ形式の最後の要素は、コンテナ内のオブジェクトを表すチャンクの配列である。

<cosl-list> -> LIST ( 'cosl'
    <cobl-list>...
    )

各オブジェクトは、次の形式で格納される。

<cobl-list> -> LIST( 'cobl'
    [<coba-ck>]
    <cobh-ck>       // 必要なヘッダー
    [<data> ] or [ DMRF-list ]

先頭の要素はエイリアス、つまり、このオブジェクトのコンテナ内で使用される別名である。

<coba-ck> -> coba( <WCHAR>...)  // Null で終わる文字列

2 番目の要素は、オブジェクトのヘッダーである。

<cobh-ck> -> cobh ( <DMUS_IO_CONTAINED_OBJECT_HEADER> )

ヘッダーの後には通常、<cobh-ck> に指定されるタイプのオブジェクト データが続く。これは、セグメント形式やスタイル形式など、RIFF チャンクの形式をとることができる。これが DMRF リストである場合は、オブジェクトへの参照である。DMRF の詳細については、「参照リスト」を参照すること。


DirectSound バッファ構成形式

次の表記法は、DirectSound バッファ構成に関する情報を格納するチャンクの構成を示している。

RIFF ( 'DSBC'
    [<guid-ck>]     // このバッファ構成の GUID 識別子
    [<vers-ck>]     // オプションのバージョン情報
    [<UNFO-list>]   // 名前、作者、著作権情報、コメント
    <dsbd-ck>       // DirectSound バッファ ディスクリプタ
    [<bsid-ck>]     // バス識別子
    [<ds3d-ck>]     // 3-D パラメータ
    [<fxls-list>]   // エフェクト ディスクリプタ
    )

<guid-ck>、<vers-ck>、<UNFO-list>

これらの 3 つのチャンクについては、「共通のチャンク」を参照すること。

<dsbd-ck>

DirectSound バッファ ディスクリプタは、次の構成を持つ。

<dsbd-ck> -> 'dsbd' (
    <DSOUND_IO_DSBUFFERDESC_dx_DSOUND_IO_DSBUFFERDESC_dxaudio>
    )

<bsid-ck>

バス識別子は、次のチャンクに格納される。

<bsid-ck> -> 'bsid' ( <DSOUND_IO_DSBUSID_dx_DSOUND_IO_DSBUSID_dxaudio> )

DSOUND_IO_DSBUSID 構造体は、サイズがチャンク サイズで指定されるバイト配列である。

<ds3d-ck>

バッファの 3D パラメータは、次のチャンクに格納される。

<ds3d-ck> -> 'ds3d'( <DSOUND_IO_3D_dx_DSOUND_IO_3D_dxaudio> )

<fxls-list>

次のリストには、バッファに関連付けられた DMO に関する情報が格納される。

<fxls-list> -> LIST ( 'fxls'
    <DSFX-form>...
    )

それぞれの DMO は、エフェクト形式で格納される。


エフェクト形式

エフェクト形式は、DMO エフェクトを表す。

RIFF ( 'DSFX'
    <fxhr-ck>
    [<data-ck>]
)

<fxhr-ck>

ヘッダー チャンクは、エフェクトを表す。

<fxhr-ck> -> fxhr ( <DSOUND_IO_DXDMO_HEADER_dx_DSOUND_IO_DXDMO_HEADER_dxaudio> )

<data-ck>

データ チャンクは、エフェクト パラメータの値が DMO の予期する形式で格納されたオプションのセットである。

<data-ck> -> data ( <DSOUND_IO_DXDMO_DATA_dx_DSOUND_IO_DXDMO_DATA_dxaudio> )


参照リスト

参照リスト チャンクには、ほかのファイルのオブジェクトへの参照に関する情報が含まれる。たとえば、バンド オブジェクトには、別のファイルにある DLS コレクションへの参照が含まれている場合がある。サブチャンクは、多くのさまざまなチャンクで使用される。

参照リストの表記法は、次のようになる。

<DMRF-list> ->LIST( 'DMRF'
    <refh-ck>       // 参照ヘッダー
    [<guid-ck>]     // オブジェクトの GUID
    [<date-ck>]     // ファイルの日付
    [<name-ck>]     // 名前
    [<file-ck>]     // ファイル名
    [<catg-ck>]     // カテゴリ名
    [<vers-ck>]     // バージョン情報
)

<refh-ck>

データは、参照されているオブジェクトに関する情報を含むヘッダーから始まる。

<refh-ck> -> refh( <DMUS_IO_REFERENCE> )

ほかのチャンクはすべてオプションである。

<guid-ck>

「共通のチャンク」を参照すること。

<date-ck>

データ チャンクには、FILETIME 構造体のデータが含まれる。

<date-ck> -> date( <FILETIME> )

<name-ck>、<file-ck>、<catg-ck>

名前、ファイル名、およびカテゴリ名は、NULL で終わる文字列である。

<name-ck> -> name( <WCHAR>... )
<file-ck> -> file( <WCHAR>...)  // Null で終わる文字列
<catg-ck> -> catg( <WCHAR>...)  // Null で終わる文字列

<vers-ck>

「共通のチャンク」を参照すること。


スクリプト形式

ここでは、DirectMusic のスクリプトに関する情報を格納するチャンクの構造について説明する。

RIFF ( 'DMSC'
    <schd-ck>       // スクリプト ヘッダー チャンク
    [<guid-ck>]     // スクリプトの GUID
    [<vers-ck>]     // オプションのバージョン情報
    [<UNFO-list>]   // 名前、作者、著作権情報、コメント
    <scve-ck>       // DirectMusic のバージョン
    <DMCN-form>     // スクリプトが参照するコンテンツのコンテナ
    <scla-ck>       // スクリプト言語
    <scsr-ck> or <DMRF> // ソース コード
)

<schd-ck>

ヘッダー チャンクには、DMUS_IO_SCRIPT_HEADER 構造体のフラグが含まれる。

<schd-ck> -> schd( <DMUS_IO_SCRIPT_HEADER> )

<guid-ck>、<vers-ck>、<UNFO-list>

これらの 3 つのチャンクについては、「共通のチャンク」を参照すること。

<scve-ck>

このチャンクは、スクリプトがオーサリングされた対象の DirectMusic のバージョンを表す。

<scve-ck> -> scve( <DMUS_IO_VERSION> )

<DMCN-form>

このチャンクについては、「コンテナ形式」を参照すること。

<scla-ck>

このチャンクは、スクリプティング言語を表す NULL で終わる文字列である。

<scla-ck> -> scla( <WCHAR>... )

<scsr-ck> または <DMRF>

最後のチャンクには、ソース コードが WCHAR 値の NULL で終わる配列として含まれる。

<scsr-ck> -> scsr( <WCHAR>... )

別の方法として、最後のチャンクは、スクリプト コードを含むテキスト ファイルを指す、参照リスト チャンクにすることもできる。このテキスト ファイルは DirectMusic オブジェクトではないので、DMUS_IO_REFERENCE の guidClassID メンバは GUID_NULL でなければならない。


セグメント形式

次の表記法は、セグメント ファイルの最上位レベルのチャンクの構成を示している。この形式は、コンテナ形式内に含めることもできる。

RIFF( 'DMSG'
    <segh-ck>       // セグメント ヘッダー チャンク
    [<guid-ck>]     // セグメントの GUID
    [<vers-ck>]     // オプションのバージョン情報
    [<UNFO-list>]   // 名前、作者、著作権情報、コメント
    [<DMCN-form>]   // ファイルに埋め込まれたオブジェクトのオプションのコンテナ
    <trkl-list>     // トラック
    [<DMTG-form>]   // オプションのツールグラフ
    [<DMAP-form>]   // オプションのオーディオパス
    )

<segh-ck>

このチャンクには、セグメントの基本的なヘッダー情報が含まれる。

<segh-ck> -> segh( <DMUS_IO_SEGMENT_HEADER> )

<guid-ck>、<vers-ck>、<UNFO-list>

「共通のチャンク」を参照すること。

<DMCN-form>

「コンテナ形式」を参照すること。

<trkl-list>

これはトラック リストである。各トラックは、トラック形式にカプセル化される。

<trkl-list> -> LIST( 'trkl'
    <DMTK-form>...
    )

<DMTG-form>

「ツールグラフ形式」を参照すること。

<DMAP-form>

「オーディオパス形式」を参照すること。


ソング形式

DirectX 8.0 では実装されない。

次の表記法は、ソング ファイルの最上位レベルのチャンクの構成を示している。この形式は、コンテナ形式内に含めることもできる。

RIFF( 'DMSO'
    <sngh-ck>       // ソング ヘッダー チャンク
    [<guid-ck>]     // ソングの GUID
    [<vers-ck>]     // オプションのバージョン情報
    [<UNFO-list>]   // 名前、作者、著作権情報、コメント
    [<DMCN-form>]   // ファイルに埋め込まれたオブジェクトのコンテナ
    <segl-list>     // セグメント
    [<tlgl-list>]   // ツールグラフ
    [<DMAP-form>]   // すべてのセグメントが共有するオーディオパス
    <srsl-list>     // セグメント参照
)

<sngh-ck>

このチャンクには、ソングの基本的なヘッダー情報が含まれる。

<sngh-ck> -> sngh ( <DMUS_IO_SONG_HEADER> )

<guid-ck>、<vers-ck>、<UNFO-list>

「共通のチャンク」を参照すること。

<DMCN-form>

「コンテナ形式」を参照すること。

<segl-list>

<segl-list> -> LIST( 'segl'
    <ssgl-list>...
    )

ソング セグメント リストにはセグメントの配列が含まれ、それぞれの配列は、次のリストに記述される。

<ssgl-list> -> LIST( 'ssgl'
    [<DMSG-form>]
    [<DMRF-list>]
    )

このリストには、セグメント形式または参照リストのいずれかが含まれる。

<tlgl-list>

<tlgl-list> -> LIST( 'tlgl'
    <DMTG-form>...
    )

ツールグラフ リストには、ツールグラフ形式の配列が含まれる。

<DMAP-form>

このチャンクは、ソングに含まれるすべてのセグメントが共有するオーディオパスを記述する。「オーディオパス形式」を参照すること。

<srsl-list>

ソング形式の最後のチャンクは、セグメント参照リストの配列であり、次のように構成される。

<srsl-list> -> LIST( 'srsl'
    <sgrl-list>...
    )

<sgrl-list> -> LIST( 'sgrl'
    <sgrh-ck>       // セグメント参照ヘッダー
    <segh-ck>       // セグメント ヘッダー
    [<UNFO-list>]   // 名前、作者、著作権、コメント
    [<strh-ck>]     // セグメント トランジション チャンク
    [<trsl-list>]   // トラック参照
    )

このリストの先頭には、セグメント参照ヘッダーが付く。

<sgrh-ck> -> ( 'sgrh' <DMUS_IO_SEGREF_HEADER> )

次はセグメント ヘッダーである。<segh-ck> チャンクの構文については、「セグメント形式」を参照すること。

<UNFO-list> については、「共通のチャンク」を参照すること。

セグメント トランジション チャンクは、ほかのセグメントからこのセグメントへの有効なトランジションを指定する。構造は次のとおりである。

<strh-ck> -> ( strh
    <DMUS_IO_TRANSITION_DEF>    // デフォルトのトランジション
    <DMUS_IO_TRANSITION_DEF>...// 追加のトランジション
    )

セグメント参照リストの最後の部分には、トラック参照が含まれる。これは、複数セグメントのトラックからセグメントを作成するために使用される。

<trsl-list> -> LIST( 'trsl'
    <tkrl-list>...
    )

このリストには、トラック参照リストの配列が含まれる。各配列は、次のように構成される。

<tkrl-list> -> ( 'tkrl'
    <tkrh-ck>       // トラック参照ヘッダー チャンク
    <trkh-ck>       // トラック ヘッダー チャンク
    [<trkx-ck>]     // トラック フラグ
    )

このリストには 3 つのチャンクが含まれる。最初のチャンクには、トラックを格納するセグメントを識別するヘッダー構造体が含まれる。

tkrh-ck -> tkrh( <DMUS_IO_TRACKREF_HEADER> )

トラック参照リストの残りの 2 つのチャンクについては、「トラック形式」を参照すること。


スタイル形式

次の表記法は、スタイル ファイルの最上位レベルのチャンクの構成を示している。この形式は、コンテナ形式内に含めることもできる。

RIFF( 'DMST'
    <styh-ck>       // スタイル ヘッダー チャンク
    <guid-ck>       // 一意の識別子
    [<UNFO-list>]   // 名前、作者、著作権情報、コメント
    [<vers-ck>]     // バージョン チャンク
    <part-list>...// パターンで使用される、スタイル中のパートの配列
    <pttn-list>...// スタイル中のパターンの配列
    <DMBD-form>...// スタイル中のバンドのリスト
    [<prrf-list>]   // スタイル中のコード マップ参照のリスト
)

<styh-ck>

このチャンクには、スタイルの基本的なヘッダー情報が含まれる。

<styh-ck> -> styh( <DMUS_IO_STYLE> )

<guid-ck>、<UNFO-list>、<vers-ck>

これらの 3 つのチャンクについては、「共通のチャンク」を参照すること。

<part-list>

スタイル内の各パートは、チャンク内に次の形式で記述される。

<part-list> -> LIST('part'
    <prth-ck>       // パート ヘッダー チャンク
    [<UNFO-list>]
    [<note-ck>]     // パート中のノート
    [<crve-ck>]     // パート中のカーブ
    [<mrkr-ck>]     // パート中のマーカー
    [<rsln-ck>]     // パート中のバリエーション分解能
    [<anpn-ck>]     // パート中の解決アンティシペーション
    )

次の表記に示すように、パート リストにはヘッダー、オプションの UNFO チャンク、および要素のリストが含まれる (UNFO リストについては、「共通のチャンク」を参照すること)。

<prth-ck> -> prth( <DMUS_IO_STYLEPART> )

<note-ck> -> note(
    < DWORD >  // DMUS_IO_STYLENOTE のサイズ
    < DMUS_IO_STYLENOTE >...
    )

<crve-ck> -> crve(
    < DWORD >  // DMUS_IO_STYLECURVE のサイズ
    < DMUS_IO_STYLECURVE >...
    )

<mrkr-ck> -> mrkr(
    < DWORD > // DMUS_IO_STYLEMARKER のサイズ
    < DMUS_IO_STYLEMARKER >...
    )

<rsln-ck> -> rsln(
    < DWORD > // DMUS_IO_STYLERESOLUTION のサイズ
    < DMUS_IO_STYLERESOLUTION >...
    )

<anpn-ck> -> anpn(
    < DWORD > Size of DMUS_IO_STYLE_ANTICIPATION
    < DMUS_IO_STYLE_ANTICIPATION >...
    )

<pttn-list>

各パターンは、チャンク内に次の形式で記述される。

<pttn-list> -> LIST( 'pttn'
    <ptnh-ck>       // パターン ヘッダー チャンク
    <rhtm-ck>       // コード マッチング用のリズムのリスト
    <swpt-ck>       // パターン スイッチ ポイントのリスト
    [<UNFO-list>]
    [<mtfs-ck>]     // モチーフ設定チャンク
    [<DMBD-form>]   // パターンに関連付けられたバンド
                    // (モチーフ用)
    <pref-list>...// パート参照 ID の配列
    )

パターン リストの最初のチャンクは、ヘッダーである。

<ptnh-ck> -> ptnh( <DMUS_IO_PATTERN> )

2 番目のチャンクは、リズム リストである。

<rhtm-ck> -> rhtm( <DWORD>... )

このチャンクは、各小節ごとに 1 つの DWORD 配列で構成され、リズム パターンを表す。ビットの配置については、DMUS_RHYTHM_PARAM の dwRhythmPattern メンバを参照すること。

パターン リストの 3 番目のチャンクは、スイッチ ポイント チャンクである。

<swpt-ck> -> swpt( <DWORD>... )

スイッチ ポイント チャンクは、各小節ごとに 1 つの DWORD 配列で構成され、パターンが開始できる有効なポイントを表す。

オプションの UNFO リストについては、「共通のチャンク」を参照すること。

パターン リストの次のチャンクは、モチーフ設定を表す。

<mtfs-ck> -> mtfs( <DMUS_IO_MOTIFSETTINGS> )

パターン リストの <DMBD-form> チャンクについては、「バンド形式」を参照すること。

パターン リストの最後のチャンクは、パート参照リストである。

<pref-list> -> LIST( 'pref'
    <prfc-ck>   // パート参照チャンク
    )

要素はパート参照のみである。

<prfc-ck> -> prfc( <DMUS_IO_PARTREF> )

<DMBD-form>

スタイル形式の次のチャンクは、バンド形式である。

<prrf-list>

最後のチャンクには、コード マップ参照の配列が含まれる。

<prrf-list> -> LIST( 'prrf'
    <DMRF-list>...
    )

<DMRF-list> の詳細については、「参照リスト」を参照すること。


ツール形式

ツール形式には、ツールに関する情報が含まれる。ツールは、ツールグラフ形式に埋め込むか、別のファイルに格納することができる。

<DMTL-form> -> RIFF( 'DMTL'
    <tolh-ck>
    [<data>]        // ツール データ
)

<tolh-ck>

これはツール ヘッダー チャンクである。

<tolh-ck> -> tolh( <DMUS_IO_TOOL_HEADER> )

<data>

<data> 要素は、DMUS_IO_TOOL_HEADER 構造体で識別されるタイプのチャンクである。このチャンクの形式は、ツールの定義によって異なり、リストまたは通常のチャンクとなる。


ツールグラフ形式

ツールグラフ チャンクは、最上位レベルの形式、またはセグメント形式やコンテナ形式のサブチャンクとして記述される。

RIFF( 'DMTG'
    [<guid-ck>]     // ツールグラフの GUID
    [<vers-ck>]     // バージョン情報
    [<UNFO-list>]   // 名前、作者、著作権情報、コメント
    <toll-list>     // ツールのリスト
)

<guid-ck>、<vers-ck>、<UNFO-list>

これらの 3 つのチャンクについては、「共通のチャンク」を参照すること。

<toll-list>

ツールグラフ チャンクの主要かつ唯一要求されるパートはツール リストである。ツール リストはツール形式の配列で構成される。

<toll-list> -> LIST( 'toll'
    <DMTL-form>...
    )

<DMTL-form> チャンクの詳細については、「ツール形式」を参照すること。


トラック形式

トラック形式には、1 つのトラックに関する情報が含まれる。この形式は、セグメント形式に埋め込むか、独自のファイルに格納することができる。

<DMTK-form> -> RIFF( 'DMTK'
    <trkh-ck>
    [<trkx-ck>]     // オプションのトラック フラグ
    [<guid-ck>]     // トラック オブジェクト インスタンスの GUID
    [<vers-ck>]     // バージョン情報
    [<UNFO-list>]   // 名前、作者、著作権情報、コメント
    [<data>]        // トラック データ
)

<trkh-ck>

最初のチャンクには、トラックの基本的なヘッダー情報が含まれる。

<trkh-ck> -> trkh( <DMUS_IO_TRACK_HEADER> )

<trkx-ck>

このオプションのチャンクには、トラックのフラグが含まれる。

<trkx-ck> -> trkx( <DMUS_IO_TRACK_EXTRAS_HEADER> )

<guid-ck>、<vers-ck>、<UNFO-list>

これらの 3 つのチャンクについては、「共通のチャンク」を参照すること。

<data>

トラック形式の最後の要素は、トラックのデータである。データで使用されるチャンクの種類は、DMUS_IO_TRACK_HEADER 構造体で識別される。標準トラック チャンクは、次のように定義されている。

  • バンド トラック形式
  • コード トラック リスト
  • コード マップ トラック リスト
  • コマンド トラック チャンク
  • 歌詞トラック リスト
  • マーカー トラック リスト
  • メロディ編成トラック リスト
  • ミュート トラック チャンク
  • パラメータ制御トラック リスト
  • パターン トラック形式
  • スクリプト トラック リスト
  • セグメント トリガ トラック リスト
  • シーケンス トラック チャンク
  • サインポスト トラック チャンク
  • スタイル トラック リスト
  • システム エクスクルーシブ トラック チャンク
  • テンポ トラック チャンク
  • 拍子記号トラック リスト
  • ウェーブ トラック リスト


バンド トラック形式

バンド トラック形式は最上位の形式にも使用できるが、トラック形式のデータ部分としても使用される。構造は次のとおりである。

RIFF( 'DMBT'
    [<bdth-ck>]     // バンド トラック ヘッダー
    [<guid-ck>]     // バンド トラックの GUID
    [<vers-ck>]     // バージョン情報
    [<UNFO-list>]   // 名前、作者、著作権情報、コメント
    <lbdl-list>     // バンド リストのリスト
    )

<bdth-ck>

このオプションのチャンクには、バンド トラックのヘッダー情報が含まれる。構造体のデータは、自動ダウンロードのフラグのみである。

<bnth-ck> -> bdth( <DMUS_IO_BAND_TRACK_HEADER> )

<guid-ck>、<vers-ck>、<UNFO-list>

これらの 3 つのチャンクについては、「共通のチャンク」を参照すること。

<lbdl-list>

最後のチャンクには、1 つまたは複数のバンドが含まれる。

<lbdl-list> -> LIST( 'lbdl'
    <lbnd-list>...
    )

各バンドは、次のリストにカプセル化される。

<lbnd-list> -> LIST( 'lbnd'
    <bdih-ck> or <bd2h-ck>
    <DMBD-form>
    )

バンド リストは次のヘッダーで始まる。従来形式のファイルでは、これは <bdih-ck> であり、新形式のファイルでは <bd2h-ck> を使用する。

<bdih-ck> -> ( <DMUS_IO_BAND_ITEM_HEADER> )

<bd2h-ck> -> ( <DMUS_IO_BAND_ITEM_HEADER2> )

ヘッダーの後にバンド形式が続き、バンドの音色に関する情報が含まれる。


コード トラック リスト

コード トラック リストには、トラック形式のコード データが含まれる。構造は次のとおりである。

<cord-list> -> LIST( 'cord'
    <crdh-ck>       // ヘッダー
    <crdb-ck>       // コード本体のチャンク
    )

<crdh-ck>

<crdh-ck> -> crdh ( <DWORD> )

ヘッダーは DWORD 値で、上位 8 ビットにコード ルート、下位 24 ビットにスケールが含まれる。これらのビットの説明については、「DMUS_IO_SUBCHORD」を参照すること。

コード トラック リストのデータ本体は、コード変更およびコンポーネント サブコードに関する情報で構成される。

<crdb-ck> -> crdb(
    <DWORD>           // DMUS_IO_CHORD のサイズ
    <DMUS_IO_CHORD>
    <DWORD>           // サブコードの数
    <DWORD>           // DMUS_IO_SUBCHORD のサイズ
    <DMUS_IO_SUBCHORD>...
    )


コード マップ トラック リスト

コード マップ トラック リストには、トラック形式のデータが含まれる。構造は次のとおりである。

<pftr-list> -> LIST('pftr'
    <pfrf-list>...
    )

データは、タイム スタンプとコード マップへの参照を含む、1 つまたは複数のリストで構成される。

<pfrf-list> -> LIST('pfrf'
    <stmp-ck>
    <DMRF-list>
    )

タイム スタンプ チャンクの表記法は、次のとおりである。

<stmp-ck> -> stmp( <DWORD> )

<DMRF-list> の詳細については、「参照リスト」を参照すること。


コマンド トラック チャンク

コマンド トラック チャンクには、トラック形式のデータが含まれる。構造は次のとおりである。

<cmnd-ck> -> cmnd(
    <DWORD>    // DMUS_IO_COMMAND のサイズ
    <DMUS_IO_COMMAND>...
    )


歌詞トラック リスト

歌詞トラック リストには、トラック形式のデータが含まれる。

<lyrt-list> -> LIST( 'lyrt'
    <lyrl-list>
    )

歌詞トラック リストの唯一のチャンクは、歌詞イベントの配列を格納するもう 1 つのリストである。

<lyrl-list> -> LIST(
    <lyre-list>...
    )

それぞれの歌詞イベントは、次のようにもう 1 つのリストに格納される。

<lyre-list> -> LIST(
    <lyrh-ck>         // イベント ヘッダー チャンク
    <lyrn-ck>         // 通知テキスト
    )

先頭のチャンクはヘッダーである。

<lyrh-ck> -> lyrh( <DMUS_IO_LYRICSTRACK_EVENTHEADER> )

2 番目のチャンクには、イベントに関連付けられたテキストが、NULL で終わる文字列として含まれる。

<lyrn-ck> -> lyrn( <WCHAR>... )


マーカー トラック リスト

マーカー トラック リストには、トラック形式のデータが含まれる。構造は次のとおりである。

<mark-list> -> LIST ( 'MARK'
    [<vals-ck>]
    [<play-ck>]
)

リストの先頭要素は、有効な開始ポイントを定義するチャンクの配列である。

<vals-ck> -> vals(
    DWORD    // DMUS_IO_VALID_START のサイズ
    <DMUS_IO_VALID_START>...
    )

2 番目の要素は、有効な演奏ポイントを定義するチャンクの配列である。

<play-ck> -> play(
    DWORD    // DMUS_IO_PLAYMARKER のサイズ
    <DMUS_IO_PLAYMARKER>...
    )


メロディ編成トラック リスト

DirectX 8.0 では実装されない。

メロディ編成トラック リストには、トラック形式のデータが含まれる。構造は次のとおりである。

<mfrm-list> -> LIST( 'mfrm'
    <mlfh-ck>    // メロディ編成ヘッダー
    <mlfb-ck>    // メロディ編成本体
    )

メロディ編成ヘッダー チャンクは次のような構成である。

<mlfb-ck> -> mlfb( <DMUS_IO_MELFORM> )

データ本体は、次のチャンクに格納される。

<mlfb-ck> -> mlfb(
    <DWORD>    // DMUS_IO_MELODY_FRAGMENT のサイズ
    <DMUS_IO_MELODY_FRAGMENT>...
    )

DMUS_IO_MELODY_FRAGMENT は、DMUS_MELODY_FRAGMENT に等しいものとして定義される。


ミュート トラック チャンク

ミュート トラック チャンクには、トラック形式のデータが含まれる。構造は次のとおりである。

<mute-ck> -> mute(
    <DWORD>    // DMUS_IO_MUTE のサイズ
    <DMUS_IO_MUTE>...
    )


パラメータ制御トラック リスト

パラメータ制御トラック リストには、トラック形式のデータが含まれる。

<prmt-list> -> LIST( 'prmt'
    <prol-list>...
    )

リストには、リストの配列が含まれる。それぞれのリストはオブジェクトを表す。

<prol-list> -> LIST( 'proh'
    <proh-ck>       // オブジェクト ヘッダー チャンク
    <prpl-list>...// パラメータの配列
    )

オブジェクト リストの最初のチャンクは、ヘッダーである。

<proh-ck> -> proh( <DMUS_IO_PARAMCONTROLTRACK_OBJECTHEADER> )

2 番目のチャンクには、次に示すように構成されたパラメータ リストが含まれる。

<prpl-list> -> LIST( 'prpl'
    <prph-ck>       // パラメータ ヘッダー
    <prcc-ck>       // カーブの配列
    )

パラメータ リストのヘッダーは、次のように表される。

<prph-ck> -> prph( <DMUS_IO_PARAMCONTROLTRACK_PARAMHEADER> )

カーブの配列は、次のチャンクで表される。

<prcc-ck> -> prcc(
    <DWORD>   // DMUS_IO_PARAMCONTROLTRACK_CURVEINFO のサイズ
   <DMUS_IO_PARAMCONTROLTRACK_CURVEINFO>...// mtTime の順にソートされたカーブ
    )


パターン トラック形式

パターン トラック形式は、最上位レベルの形式とすることもできるが、トラック形式のデータとしても使用される。構造は次のとおりである。

RIFF( 'DMPT'
    <styh-ck>       // スタイル ヘッダー チャンク
    <pttn-list>     // パターン
    )

<pttn-list> および <pttn-list> については、「スタイル形式」を参照すること。


スクリプト トラック リスト

スクリプト トラック リストには、トラック形式のデータが含まれる。

<scrt-list> -> LIST( 'scrt'
    <scrl-list>
    )

リストには、スクリプト イベントの配列を格納する別のリストが含まれる。

<scrl-list> -> LIST( 'scrl'
    <scre-list>...
    )

それぞれの <scre-list> チャンクは、次のようにイベントを表す。

<scre-list> -> LIST( 'scre'
    <scrh-ck>         // イベント ヘッダー チャンク
    <DMRF>            // 参照
    <scrn-ck>         // ルーチン名
    )

各スクリプト トラック イベントの先頭には、ヘッダーが付く。

<scrh-ck> -> 'scrh'( <DMUS_IO_SCRIPTTRACK_EVENTHEADER> )

DMRF チャンクについては、「参照リスト」を参照すること。

スクリプト トラック イベントの最後のチャンクは、NULL で終わるルーチン名である。

<scrn-ck> -> 'scrn'( <WCHAR>... )


セグメント トリガ トラック リスト

セグメント トリガ トラック リストには、トラック形式のデータが含まれる。構造は次のとおりである。

<SEGT-list> -> LIST( 'segt'
    [<sgth-ck>]     // セグメント トラック ヘッダー
    <lsgl-list>     // セグメント リストのリスト
    )

先頭のチャンクは、トラック ヘッダーである。

<sgth-ck> -> 'sgth' ( <DMUS_IO_SEGMENT_TRACK_HEADER> )

次のチャンクは、セグメントの配列を含むリストである。

<lsgl-list> -> LIST( 'lsgl'
    <lseg-list>...
    )

それぞれの "lseg" リストは、単一のセグメント項目を表す。

<lseg-list> -> LIST( 'lseg'
    <sgih-ck>
    <DMRF-list>
    [<snam-ck>]    // モチーフ名
    )

セグメント項目の最初のチャンクは、ヘッダーである。

<sgih-ck> -> ( <DMUS_IO_SEGMENT_ITEM_HEADER> )

この後には、セグメント ファイルまたはスタイル ファイルへの参照が続く。DMUS_SEGMENTTRACKF_MOTIF フラグが項目ヘッダーに存在する場合、これはスタイルへの参照である。詳細については、「参照リスト」を参照すること。

DMUS_SEGMENTTRACKF_MOTIF フラグが項目ヘッダーに存在する場合、セグメント項目の最後のチャンクには、NULL で終わるモチーフ名が含まれる。

<snam-ck> -> ( <WCHAR>... )


シーケンス トラック チャンク

シーケンス トラック チャンクには、トラック形式のデータが含まれる。構造は次のとおりである。

<seqt> -> seqt(
    <evtl-ck>
    <curl-ck>
    )

シーケンス トラック チャンクには、シーケンス項目とカーブ項目の 2 つのチャンクを含めることができる。

<evtl-ck> -> evtl(
    <DWORD>     // DMUS_IO_SEQ_ITEM のサイズ
    <DMUS_IO_SEQ_ITEM>...
    )

<curl-ck> -> curl(
    <DWORD>     // DMUS_IO_CURVE_ITEM のサイズ
    <DMUS_IO_CURVE_ITEM>...
    )

注 シーケンス トラック チャンクは、RIFF と LIST チャンクのみがサブチャンクを持つことができるという表記法には従わない。


サインポスト トラック チャンク

サインポスト トラック チャンクには、トラック形式のデータが含まれる。構造は次のとおりである。

<sgnp-list> -> sgnp(
    <DWORD>    // DMUS_IO_SIGNPOST のサイズ
    <DMUS_IO_SIGNPOST>...
    )


スタイル トラック リスト

スタイル トラック リストには、トラック形式のデータが含まれる。構造は次のとおりである。

<sttr-list> -> LIST('sttr'(
    <strf-list>...
    )

データは、タイム スタンプとスタイルへの参照を含む、1 つまたは複数のリストで構成される。

<strf-list> -> LIST('strf'(
    <stmp-ck>
    <DMRF-list>
    )

最初のチャンクには、次のようにタイム スタンプ データが含まれる。

<stmp-ck> -> stmp( <DWORD> )

<DMRF-list> の詳細については、「参照リスト」を参照すること。


システム エクスクルーシブ トラック チャンク

システム エクスクルーシブ トラック チャンクには、トラック形式のデータが含まれる。これは、システム エクスクルーシブ メッセージ項目の配列である。それぞれ、DMUS_IO_SYSEX_ITEM 構造体と、それに続く dwSysExLength メンバで指定されるバイト数で構成される。

<syex-ck> -> 'syex' (
    {
    <DMUS_IO_SYSEX_ITEM>
    <BYTE>...// データ
    }...
    )


テンポ トラック チャンク

テンポ トラック チャンクには、トラック形式のデータが含まれる。構造は次のとおりである。

<tetr-ck> -> tetr(
    <DWORD>    // DMUS_IO_TEMPO_ITEM のサイズ
    <DMUS_IO_TEMPO_ITEM>...
    )


拍子記号トラック リスト

拍子記号トラック リストには、トラック形式のデータが含まれる。構造は次のとおりである。

<tims-list> -> LIST( 'TIMS'
    <tims-ck> // 拍子記号
    )

拍子記号配列には、次のチャンクが含まれる。

<tims-ck> -> tims (
    <DWORD>  // DMUS_IO_TIMESIGNATURE_ITEM のサイズ
    <DMUS_IO_TIMESIGNATURE_ITEM>...
    )


ウェーブ トラック リスト

次の表記法は、ウェーブ トラックのデータを格納するチャンクの構成を示している。

<wavt-list> -> LIST ( 'wavt'
    <wath-ck>      // ウェーブ トラック ヘッダー
    <wavp-list>...// ウェーブ パート
    }

<wath-ck>

このチャンクには、ウェーブのヘッダー情報が含まれる。ウェーブ パートを記述するリストの配列が後に続く。

<wath-ck> -> wath( <DMUS_IO_WAVE_TRACK_HEADER> )

<wavp-list>

<wavp-list> -> LIST ( 'wavp'
    <waph-ck>       // ウェーブ パート ヘッダー
    <wavi-list>     // ウェーブ項目
    )

ウェーブ パート リストは次のヘッダーで始まる。

<waph-ck> -> 'waph' ( <DMUS_IO_WAVE_PART_HEADER> )

ウェーブ パート リストの 2 番目のパートは、ウェーブ項目の配列である。

<wavi-list> -> LIST( 'wavi'
    <wave-list>...
    )

それぞれのウェーブ項目は、次のようにリスト チャンクに記述される。

<wave-list> -> LIST( 'wave'
    <waih-ck>       // ウェーブ項目ヘッダー
    <DMRF-list>     // ウェーブ オブジェクトへの参照
    )

ウェーブ記述は次のヘッダーで始まる。

<waih-ck> -> ( <DMUS_IO_WAVE_ITEM_HEADER> )

<DMRF-list> の詳細については、「参照リスト」を参照すること。


ウェーブ ヘッダー チャンク

ウェーブ ヘッダー チャンクは、DirectMusic のウェーブ ファイルに付加される特殊なチャンクである。このチャンクは、ストリーミング機能を指定する。

<wavh-ck> -> ( <DMUS_IO_WAVE_HEADER> )


DirectMusic のファイル データ構造体

ここでは、DirectMusic ファイルで使われるデータ構造体のリファレンス情報を記述する。標準的な DirectMusic の各オブジェクトは、IPersistStream インターフェイスを使って、それ自体のデータをロードするため、ほとんどのアプリケーションでは、これらの構造体に関する知識は必要ない。これらの構造体は、DirectMusic と互換性のあるフォーマットでデータを保存する必要のあるミュージック オーサリング アプリケーション用に主に用意されている。

DirectMusic ファイルでは、以下の構造体が使われる。

  • DMUS_IO_BAND_ITEM_HEADER
  • DMUS_IO_BAND_ITEM_HEADER2
  • DMUS_IO_BAND_TRACK_HEADER
  • DMUS_IO_BUFFER_ATTRIBUTES_HEADER
  • DMUS_IO_CHORD
  • DMUS_IO_CHORDENTRY
  • DMUS_IO_CHORDMAP
  • DMUS_IO_CHORDMAP_SIGNPOST
  • DMUS_IO_CHORDMAP_SUBCHORD
  • DMUS_IO_COMMAND
  • DMUS_IO_CONTAINED_OBJECT_HEADER
  • DMUS_IO_CONTAINER_HEADER
  • DMUS_IO_CURVE_ITEM
  • DMUS_IO_INSTRUMENT
  • DMUS_IO_LYRICSTRACK_EVENTHEADER
  • DMUS_IO_MELFORM
  • DMUS_IO_MOTIFSETTINGS
  • DMUS_IO_MUTE
  • DMUS_IO_NEXTCHORD
  • DMUS_IO_PARAMCONTROLTRACK_CURVEINFO
  • DMUS_IO_PARAMCONTROLTRACK_OBJECTHEADER
  • DMUS_IO_PARAMCONTROLTRACK_PARAMHEADER
  • DMUS_IO_PARTREF
  • DMUS_IO_PATTERN
  • DMUS_IO_PCHANNELTOBUFFER_HEADER
  • DMUS_IO_PLAYMARKER
  • DMUS_IO_PORTCONFIG_HEADER
  • DMUS_IO_REFERENCE
  • DMUS_IO_SCRIPT_HEADER
  • DMUS_IO_SCRIPTTRACK_EVENTHEADER
  • DMUS_IO_SEGMENT_HEADER
  • DMUS_IO_SEGMENT_ITEM_HEADER
  • DMUS_IO_SEGMENT_TRACK_HEADER
  • DMUS_IO_SEGREF_HEADER
  • DMUS_IO_SEQ_ITEM
  • DMUS_IO_SIGNPOST
  • DMUS_IO_SONG_HEADER
  • DMUS_IO_STYLE
  • DMUS_IO_STYLE_ANTICIPATION
  • DMUS_IO_STYLECURVE
  • DMUS_IO_STYLEMARKER
  • DMUS_IO_STYLENOTE
  • DMUS_IO_STYLEPART
  • DMUS_IO_STYLERESOLUTION
  • DMUS_IO_SUBCHORD
  • DMUS_IO_SYSEX_ITEM
  • DMUS_IO_TEMPO_ITEM
  • DMUS_IO_TIMESIG
  • DMUS_IO_TIMESIGNATURE_ITEM
  • DMUS_IO_TOOL_HEADER
  • DMUS_IO_TRACK_EXTRAS_HEADER
  • DMUS_IO_TRACK_HEADER
  • DMUS_IO_TRACKREF_HEADER
  • DMUS_IO_TRANSITION_DEF
  • DMUS_IO_VALID_START
  • DMUS_IO_VERSION
  • DMUS_IO_WAVE_HEADER
  • DMUS_IO_WAVE_ITEM_HEADER
  • DMUS_IO_WAVE_PART_HEADER
  • DMUS_IO_WAVE_TRACK_HEADER
  • DSOUND_IO_3D
  • DSOUND_IO_DSBUFFERDESC
  • DSOUND_IO_DSBUSID
  • DSOUND_IO_DXDMO_DATA
  • DSOUND_IO_DXDMO_HEADER

参照

DirectMusic のファイル形式


DMUS_IO_BAND_ITEM_HEADER

バンド チェンジに関する情報を保持する。従来形式のファイルのバンド トラック形式で使用される。現在は DMUS_IO_BAND_ITEM_HEADER2 に引き継がれている。

typedef struct _DMUS_IO_BAND_ITEM_HEADER {
    MUSIC_TIME lBandTime;
} DMUS_IO_BAND_ITEM_HEADER;

メンバ

lBandTime
バンド チェンジのタイム。

動作環境

ヘッダー : dmusicf.h で宣言。


DMUS_IO_BAND_ITEM_HEADER2

バンド チェンジに関する情報を保持する。バンド トラック形式で使用される。

typedef struct _DMUS_IO_BAND_ITEM_HEADER2 {
    MUSIC_TIME lBandTimeLogical;
    MUSIC_TIME lBandTimePhysical;
} DMUS_IO_BAND_ITEM_HEADER2;

メンバ

lBandTimeLogical
バンド チェンジが関連付けられているミュージック タイム。
lBandTimePhysical
バンド チェンジがエフェクトを発生させる正確な時間。論理タイムとほぼ等しい。

動作環境

ヘッダー : dmusicf.h で宣言。

参照

セグメントのタイミング


DMUS_IO_BAND_TRACK_HEADER

バンド トラックのデフォルト動作に関する情報を保持する。バンド トラック形式で使用される。

typedef struct _DMUS_IO_BAND_TRACK_HEADER {
    BOOL bAutoDownload;
} DMUS_IO_BAND_TRACK_HEADER;

メンバ

bAutoDownload
セグメントを演奏しているときの、音色を自動ダウンロードするためのフラグ。

注意

自動ダウンロードの詳細については、「バンドの使い方」を参照すること。

動作環境

ヘッダー : dmusicf.h で宣言。


DMUS_IO_BUFFER_ATTRIBUTES_HEADER

DirectSound バッファの属性を表す。オーディオパス形式で使用される。

typedef struct _DMUS_IO_BUFFER_ATTRIBUTES_HEADER {
    GUID    guidBufferID;
    DWORD   dwFlags;
} DMUS_IO_BUFFER_ATTRIBUTES_HEADER;

メンバ

guidBufferID
バッファ構成の一意な識別子。標準バッファ タイプには次の値が定義されている。

GUID_Buffer_Reverb
GUID_Buffer_EnvReverb
GUID_Buffer_Stereo
GUID_Buffer_3D_Dry
GUID_Buffer_Mono

dwFlags
バッファを表すフラグ。次の値が定義されている。
DMUS_BUFFERF_DEFINED
標準バッファ タイプの 1 つ。
DMUS_BUFFERF_MIXIN
ミックス イン バッファ。
DMUS_BUFFERF_SHARED
オーディオパス間で共有されるバッファ。

動作環境

ヘッダー : dmusicf.h で宣言。


DMUS_IO_CHORD

コード変更に関する情報を保持する。コード トラック リストで使用される。

typedef struct _DMUS_IO_CHORD {
    WCHAR       wszName[16];
    MUSIC_TIME  mtTime;
    WORD        wMeasure;
    BYTE        bBeat;
    BYTE        bFlags
} DMUS_IO_CHORD;

メンバ

wszName
コードの名前。
mtTime
コードのタイム。
wMeasure
コードが所属する小節。
bBeat
コードが所属する拍。
bFlags
フラグ。次の値が定義されている。
DMUS_CHORDKEYF_SILENT
コードは無音である。DMUS_CHORD_KEY の「注意」を参照すること。

動作環境

ヘッダー : dmusicf.h で宣言。


DMUS_IO_CHORDENTRY

コード エントリに関する情報を保持する。コード マップ形式で使用される。

typedef struct _DMUS_IO_CHORDENTRY {
    DWORD   dwFlags;
    WORD    wConnectionID;
} DMUS_IO_CHORDENTRY;

メンバ

dwFlags
コードがコード グラフ内の開始コード (ビット 2 がセット) であるかエンディング コード (ビット 3 がセット) であるかを示すフラグ。
wConnectionID
実行時ポインタを this に置き換える。各コード エントリには、一意の接続識別子がタグ付けされる。

動作環境

ヘッダー : dmusicf.h で宣言。


DMUS_IO_CHORDMAP

コード マップに関する情報を保持する。コード マップ形式で使用される。

typedef struct _DMUS_IO_CHORDMAP {
    WCHAR   wszLoadName[20];
    DWORD   dwScalePattern;
    DWORD   dwFlags;
} DMUS_IO_CHORDMAP;

メンバ

wszLoadName
コード マップの名前。コード マップをロードするときに、オブジェクト記述の中で使われる。
dwScalePattern
コード マップに関連付けられたスケール。下位 24 ビットはそれぞれ 1 つの半音を表し、最下位ビットはルート音である。ビットがセットされている場合、それに対応するノートはスケール内に存在する。
dwFlags
フラグ。0 または次の値を使用できる。
DMUS_CHORDMAPF_VERSION8
DirectX 8.0 以降のためにコード マップが作成された。

動作環境

ヘッダー : dmusicf.h で宣言。


DMUS_IO_CHORDMAP_SIGNPOST

コード マップ内のサインポスト コードに関する情報を保持する。コード マップ形式で使用される。

typedef struct _DMUS_IO_CHORDMAP_SIGNPOST {
    DWORD   dwChords;
    DWORD   dwFlags;
} DMUS_IO_CHORDMAP_SIGNPOST;

メンバ

dwChords
このコードがサポートするサインポストのタイプ。テンプレート内の値と同じ値であるかを照合するために、これらの値が使われる。テンプレートを使うアレンジは、特に、テンプレート内でこれらの値を探し、これらの値と一致するコード マップ内の実際のコードを見つける作業から成る。次のフラグが定義されている。
DMUS_SIGNPOSTF_A
DMUS_SIGNPOSTF_B
DMUS_SIGNPOSTF_C
DMUS_SIGNPOSTF_D
DMUS_SIGNPOSTF_E
DMUS_SIGNPOSTF_F
DMUS_SIGNPOSTF_LETTER
DMUS_SIGNPOSTF_1
DMUS_SIGNPOSTF_2
DMUS_SIGNPOSTF_3
DMUS_SIGNPOSTF_4
DMUS_SIGNPOSTF_5
DMUS_SIGNPOSTF_6
DMUS_SIGNPOSTF_7
DMUS_SIGNPOSTF_ROOT
DMUS_SIGNPOSTF_CADENCE
dwFlags
このコードをカデンツァ コードの前に置くかどうかを定義するフラグ。サインポスト コードは最高 2 つのカデンツァ コードを持つことができる。その場合の値は、SPOST_CADENCE1 (最初のカデンツァ)、SPOST_CADENCE2 (2 番目のカデンツァ)、またはこれら 2 つのフラグを組み合わせたものを設定できる。

動作環境

ヘッダー : dmusicf.h で宣言。

参照

DMUS_IO_SIGNPOST


DMUS_IO_CHORDMAP_SUBCHORD

サブコードに関する情報を保持する。コード マップ形式で使用される。

typedef struct _DMUS_IO_CHORDMAP_SUBCHORD {
    DWORD   dwChordPattern;
    DWORD   dwScalePattern;
    DWORD   dwInvertPattern;
    BYTE    bChordRoot;
    BYTE    bScaleRoot;
    WORD    wCFlags;
    DWORD   dwLevels;
} DMUS_IO_CHORDMAP_SUBCHORD;

メンバ

dwChordPattern
サブコード内のノート。下位 24 ビットはそれぞれ 1 つの半音を表し、最下位ビットはルート音である。ビットがセットされている場合、それに対応するノートはコード内に存在する。
dwScalePattern
スケール内のノート。下位 24 ビットはそれぞれ 1 つの半音を表し、最下位ビットはルート音である。ビットがセットされている場合、それに対応するノートはスケール内に存在する。
dwInvertPattern
スケール内で転回が発生できるポイント。ビットがオフになっている場合、それに対応する音程ではノートを転回できない。たとえば、パターン 100001111111 は、陽音階 (メジャー スケール) の 5 度と 7 度を除き、どこでも転回が認められることを意味する。
bChordRoot
サブコードのルート音。0 は範囲内の最低音の C、23 は最高音の B である。
bScaleRoot
スケールのルート音。0 は範囲内の最低音の C、23 は最高音の B である。
wCFlags
将来の使用に備えて予約されている。
dwLevels
このサブコードがサポートするレベルを示すビット フィールド。スタイル内の各パートにはレベルが割り当てられ、レベルがこのメンバに含まれるパートだけについてこのコードが使用される。

動作環境

ヘッダー : dmusicf.h で宣言。

参照

DMUS_SUBCHORD


DMUS_IO_COMMAND

コマンド イベントに関する情報を保持する。コマンド トラック チャンクで使用される。

typedef struct _DMUS_IO_COMMAND {
    MUSIC_TIME  mtTime;
    WORD        wMeasure;
    BYTE        bBeat;
    BYTE        bCommand;
    BYTE        bGrooveLevel;
    BYTE        bGrooveRange;
    BYTE        bRepeatMode;
} DMUS_IO_COMMAND;

メンバ

mtTime
コマンドのタイム。
wMeasure
コマンドが所属する小節。
bBeat
コマンドが所属する拍。
bCommand
コマンドのタイプ。「DMUS_COMMANDT_TYPES」を参照すること。
bGrooveLevel
グルーブ レベル。コマンドがグルーブ コマンドでない場合は 0 を指定する。
bGrooveRange
グルーブ レベルをランダムに変更できる範囲のサイズ。この値が奇数ならば、グルーブ範囲は bGrooveRange から 1 を引いた値である。たとえば、グルーブ レベルが 35、bGrooveRange が 5 である場合、調整後のグルーブ範囲は 4 であり、グルーブ レベルは 33 ～ 37 のいずれかになる。
bRepeatMode
反復のパターンを選択する方法を指定するフラグ。「DMUS_PATTERNT_TYPES」を参照すること。

動作環境

ヘッダー : dmusicf.h で宣言。


DMUS_IO_CONTAINED_OBJECT_HEADER

コンテナ形式で、各オブジェクトの前に使用される。

typedef struct _DMUS_IO_CONTAINED_OBJECT_HEADER {
    GUID        guidClassID;
    DWORD       dwFlags;
    FOURCC      ckid;
    FOURCC      fccType;
} DMUS_IO_CONTAINED_OBJECT_HEADER;

メンバ

guidClassID
オブジェクトのクラス識別子。
dwFlags
0 または次のフラグを指定する。
DMUS_CONTAINED_OBJF_KEEP
コンテナの解放後、キャッシュされたオブジェクトをローダー内に保持する。
ckid
データ チャンクの識別子。この値が 0 の場合、チャンクのタイプは LIST と見なされる。その場合、fccType は有効で、0 以外の値でなければならない。
fccType
リスト タイプ。この値が 0 の場合、ckid は有効で、0 以外の値でなければならない。

動作環境

ヘッダー : dmusicf.h で宣言。


DMUS_IO_CONTAINER_HEADER

コンテナ形式で使用される。

typedef struct _DMUS_IO_CONTAINER_HEADER {
    DWORD       dwFlags;
} DMUS_IO_CONTAINER_HEADER;

メンバ

dwFlags
フラグを指定する DWORD 値。0 または次の値を指定する。
DMUS_CONTAINER_NOLOADS
コンテナのロード時に、コンテナ内の項目をロードしない。エントリはローダー内に作成されるが、明示的にロードされるまでオブジェクトを作成しない。

動作環境

ヘッダー : dmusicf.h で宣言。


DMUS_IO_CURVE_ITEM

トラック内のカーブ イベントに関する情報を保持する。シーケンス トラック チャンクで使用される。

typedef struct _DMUS_IO_CURVE_ITEM {
    MUSIC_TIME  mtStart;
    MUSIC_TIME  mtDuration;
    MUSIC_TIME  mtResetDuration;
    DWORD       dwPChannel;
    short       nOffset;
    short       nStartValue;
    short       nEndValue;
    short       nResetValue;
    BYTE        bType;
    BYTE        bCurveShape;
    BYTE        bCCData;
    BYTE        bFlags;
    WORD        wParamType;
    WORD        wMergeIndex
} DMUS_IO_CURVE_ITEM;

メンバ

mtStart
カーブの開始タイム。
mtDuration
カーブの持続時間。
mtResetDuration
リセットできる間のカーブ終了後の時間。
dwPChannel
イベントのパフォーマンス チャンネル。
nOffset
カーブが発生するグリッド境界からのオフセット。ミュージック タイムで表される。MIDI カーブはロード時に最も近いグリッドに関連付けられるため、この値は正でも負でもよい。
nStartValue
開始値。
nEndValue
終了値。
nResetValue
mtResetDuration によって設定される時間内にフラッシュ (解放) または無効化を設定するリセット値。
bType
カーブのタイプ。次のタイプが定義されている。
DMUS_CURVET_CCCURVE
コンティニュアス コントローラ カーブ (MIDI Control Change チャンネル ボイス メッセージ。ステータス バイトは &HBn。n はチャンネル番号を表す)。
DMUS_CURVET_MATCURVE
モノラル アフタータッチ カーブ (MIDI Channel Pressure チャンネル ボイス メッセージ。ステータス バイトは &HDn)。
DMUS_CURVET_PATCURVE
ポリフォニック アフタータッチ カーブ (MIDI Poly Key Pressure チャンネル ボイス メッセージ。ステータス バイトは &HDn)。
DMUS_CURVET_PBCURVE
ピッチベンド カーブ (MIDI Pitch Bend チャンネル ボイス メッセージ。ステータス バイトは &HEn)。
DMUS_CURVET_NRPNCURVE
NRPN カーブ。
DMUS_CURVET_RPNCURVE
RPN カーブ。
bCurveShape
カーブの形状。次の形状が定義されている。
DMUS_CURVES_EXP
指数カーブ形状。
DMUS_CURVES_INSTANT
即時カーブ形状 (カーブの開始と終了がほとんど同時に発生する)。
DMUS_CURVES_LINEAR
線状カーブ形状。
DMUS_CURVES_LOG
対数カーブ形状。
DMUS_CURVES_SINE
正弦カーブ形状。
bCCData
コントロール チェンジ タイプの場合は、CC 番号を指定する。
bFlags
トランジションが原因で無効化が発生したときに nResetValue を設定しなければならない場合は、DMUS_CURVE_RESET を設定する。この値を 0 に設定した場合、カーブは新しい値に永続的にとどまる。ほかのすべてのビットは予約されている。
wParamType
RPN タイプおよび NRPN タイプのパラメータ番号。
wMergeIndex
マージ インデックス。モッド ホイール、リバーブの送信、コーラスの送信、ピッチ ベンド、ボリューム、およびエクスプレッション コントローラ用にサポートされる。

動作環境

ヘッダー : dmusicf.h で宣言。

参照

DMUS_IO_SEQ_ITEM、カーブ


DMUS_IO_INSTRUMENT

音色に関する情報を保持する。バンド形式で使用される。

typedef struct _DMUS_IO_INSTRUMENT {
    DWORD  dwPatch;
    DWORD  dwAssignPatch;
    DWORD  dwNoteRanges[4];
    DWORD  dwPChannel;
    DWORD  dwFlags;
    BYTE   bPan;
    BYTE   bVolume;
    short  nTranspose;
    DWORD  dwChannelPriority;
    short  nPitchBendRange;
} DMUS_IO_INSTRUMENT;

メンバ

dwPatch
音色を定義するための MSB、LSB、およびプログラム チェンジ。
dwAssignPatch
音色のダウンロード時に割り当てる MSB、LSB、およびプログラム チェンジ。
dwNoteRanges
128 ビット。音色が演奏できなければならない各 MIDI ノートにつき 1 つ指定する。
dwPChannel
音色が演奏されるパフォーマンス チャンネル。
dwFlags
コントロール フラグ。次の値が定義されている。
DMUS_IO_INST_ASSIGN_PATCH
dwAssignPatch メンバは有効である。
DMUS_IO_INST_BANKSELECT
dwPatch メンバには、MSB と LSB の有効なバンク セレクトが含まれる。
DMUS_IO_INST_CHANNEL_PRIORITY
dwChannelPriority メンバは有効である。
DMUS_IO_INST_GM
音色は General MIDI コレクションのものである。
DMUS_IO_INST_GS
音色は Roland GS コレクションのものである。
DMUS_IO_INST_NOTERANGES
dwNoteRanges メンバは有効である。
DMUS_IO_INST_PAN
bPan メンバは有効である。
DMUS_IO_INST_PATCH
dwPatch メンバは有効である。
DMUS_IO_INST_PITCHBENDRANGE
nPitchBendRange メンバは有効である。
DMUS_IO_INST_TRANSPOSE
nTranspose メンバは有効である。
DMUS_IO_INST_USE_DEFAULT_GM_SET
デフォルトの General MIDI 音色セットは、ポートがハードウェア内に GM を持っている場合でも、ポートにダウンロードしなければならない。XG または GS がリセットされた MIDI ファイルを解析する場合、GUID_StandardMIDIFile がバンドに対して要求されたかどうかにかかわらず、バンク セレクト メッセージが送信される。つまり、GUID_StandardMIDIFile は純粋に GM ファイルだけのものである。
DMUS_IO_INST_VOLUME
bVolume メンバは有効である。
DMUS_IO_INST_XG
音色は Yamaha XG コレクションのものである。
bPan
音色のパン。
bVolume
音色のボリューム。
nTranspose
ノートを転置する半音の数。
dwChannelPriority
チャンネルの優先順位。定義済みの値のリストについては、「IDirectMusicPort8::GetChannelPriority」を参照すること。
nPitchBendRange
ピッチ ベンドによりシフトされた半音の数。

動作環境

ヘッダー : dmusicf.h で宣言。


DMUS_IO_LYRICSTRACK_EVENTHEADER

歌詞トラック リストで使用される。

typedef struct _DMUS_IO_LYRICSTRACK_EVENTHEADER {
    DWORD dwFlags;
    DWORD dwTimingFlags;
    MUSIC_TIME lTimeLogical;
    MUSIC_TIME lTimePhysical;
} DMUS_IO_LYRICSTRACK_EVENTHEADER;

メンバ

dwFlags
予約済み。0 に設定する。
dwTimingFlags
通知のタイミングを決定するフラグ。次の 1 つ以上のDMUS_PMSGF_FLAGS 列挙型のメンバを指定できる。
DMUS_PMSGF_TOOL_IMMEDIATE
タイム スタンプにかかわりなく、メッセージを即座に処理すべきである。
DMUS_PMSGF_TOOL_QUEUE
ポートの遅延時間を考慮して、タイム スタンプの直前にメッセージを処理すべきである。
DMUS_PMSGF_TOOL_ATTIME
タイム スタンプの時点でメッセージを処理すべきである。
lTimeLogical
イベントが関連付けられているミュージック タイム。
lTimePhysical
イベントがトリガされる正確なタイム。論理タイムとほぼ等しい。

動作環境

ヘッダー : dmusicf.h で宣言。

参照

論理的なタイムと実際のタイム


DMUS_IO_MELFORM

DirectX 8.0 では実装されない。

メロディ編成トラック リストで使用される。

typedef struct _DMUS_IO_MELFORM {
    DWORD  dwPlaymode;
} DMUS_IO_MELFORM;

メンバ

dwPlaymode
予約済み。0 でなければならない。

動作環境

ヘッダー : dmusicf.h で宣言。


DMUS_IO_MOTIFSETTINGS

モチーフに関する情報を保持する。スタイル形式で使用される。

typedef struct _DMUS_IO_MOTIFSETTINGS {
    DWORD       dwRepeats;
    MUSIC_TIME  mtPlayStart;
    MUSIC_TIME  mtLoopStart;
    MUSIC_TIME  mtLoopEnd;
    DWORD       dwResolution;
} DMUS_IO_MOTIFSETTINGS;

メンバ

dwRepeats
反復回数。
mtPlayStart
再生の開始ポイント。通常は 0 に設定する。
mtLoopStart
ループ部分の開始ポイント。通常は 0 に設定する。
mtLoopEnd
ループ部分の終了ポイント。mtLoopStart より大きい値でなければならない。モチーフ全体をループする場合は 0。
dwResolution
デフォルトの分解能。「DMUS_TIME_RESOLVE_FLAGS」を参照すること。

動作環境

ヘッダー : dmusicf.h で宣言。

参照

IDirectMusicSegment8::SetLoopPoints


DMUS_IO_MUTE

チャンネル上のミュート イベントに関する情報を保持する。ミュート トラック チャンクで使用される。

typedef struct _DMUS_IO_MUTE {
    MUSIC_TIME  mtTime;
    DWORD       dwPChannel;
    DWORD       dwPChannelMap;
} DMUS_IO_MUTE;

メンバ

mtTime
イベントのタイム。
dwPChannel
ミュートまたは再マップするパフォーマンス チャンネル。
dwPChannelMap
dwPChannel がマップされているチャンネル。dwPChannel をミュートする場合は 0xFFFFFFFF に設定する。

動作環境

ヘッダー : dmusicf.h で宣言。

参照

DMUS_MUTE_PARAM


DMUS_IO_NEXTCHORD

コード グラフ内の次のコードに関する情報を保持する。コード マップ形式で使用される。

typedef struct _DMUS_IO_NEXTCHORD {
    DWORD   dwFlags;
    WORD    nWeight;
    WORD    wMinBeats;
    WORD    wMaxBeats;
    WORD    wConnectionID;
} DMUS_IO_NEXTCHORD;

メンバ

dwFlags
将来の使用に備えて予約されている。
nWeight
コード グラフをトラバースするときにこのリンクが使われる可能性 (1 ～ 100 の範囲)。
wMinBeats
アレンジされたセグメント内でこのコードを演奏できる拍の最小数。
wMaxBeats
アレンジされたセグメント内でこのコードを演奏できる拍の最大数。
wConnectionID
DMUS_IO_CHORDENTRY 構造体の wConnectionID メンバを参照する。

動作環境

ヘッダー : dmusicf.h で宣言。


DMUS_IO_PARAMCONTROLTRACK_CURVEINFO

パラメータ制御トラック リストで使用される。

typedef struct _DMUS_IO_PARAMCONTROLTRACK_CURVEINFO {
    MUSIC_TIME  mtStartTime;
    MUSIC_TIME  mtEndTime;
    float       fltStartValue;
    float       fltEndValue;
    DWORD       dwCurveType;
    DWORD       dwFlags;
} DMUS_IO_PARAMCONTROLTRACK_CURVEINFO;

メンバ

mtStartTime
カーブの開始タイム。
mtEndTime
カーブの終了タイム。
fltStartValue
カーブの開始値。
fltEndValue
カーブの終了値。
dwCurveType
MP_CURVE_TYPE 列挙の項目。DirectShow ドキュメントの「MP_CURVE_TYPE」を参照すること。
dwFlags
定数 MPF_ENVLP_* の組み合わせ。DirectShow ドキュメントの「Envelope Flags」を参照すること。

動作環境

ヘッダー : dmusicf.h で宣言。


DMUS_IO_PARAMCONTROLTRACK_OBJECTHEADER

パラメータ制御トラック リストで使用される。

typedef struct _DMUS_IO_PARAMCONTROLTRACK_OBJECTHEADER {
    DWORD dwFlags;
    GUID guidTimeFormat;
    DWORD dwPChannel;
    DWORD dwStage;
    DWORD dwBuffer;
    GUID guidObject;
    DWORD dwIndex;
} DMUS_IO_PARAMCONTROLTRACK_OBJECTHEADER;

メンバ

dwFlags
予約済み。0 に設定する。
guidTimeFormat
オブジェクトに設定されるタイム形式。Medparam.h に定義されている、GUID_TIME_REFERENCE または GUID_TIME_MUSIC でなければならない。
dwPChannel
パフォーマンス チャンネル、0、または DMUS_PCHANNEL_ALL。
dwStage
パスのステージ。
dwBuffer
バッファが複数ある場合、バッファのインデックス。
guidObject
GUID_DSFX_STANDARD_CHORUS などの、オブジェクトのクラス識別子。
dwIndex
適合オブジェクトのリスト内のオブジェクトのインデックス。

注意

各メンバに設定可能な値の詳細については、「IDirectMusicSegmentState8::GetObjectInPath」を参照すること。

動作環境

ヘッダー : dmusicf.h で宣言。


DMUS_IO_PARAMCONTROLTRACK_PARAMHEADER

パラメータ制御トラック リストで使用される。

typedef struct _DMUS_IO_PARAMCONTROLTRACK_PARAMHEADER {
    DWORD dwFlags;
    DWORD dwIndex;
} DMUS_IO_PARAMCONTROLTRACK_PARAMHEADER;

メンバ

dwFlags
予約済み。0 に設定する。
dwIndex
オブジェクト上のパラメータのインデックス番号。

動作環境

ヘッダー : dmusicf.h で宣言。


DMUS_IO_PARTREF

パート参照に関する情報を保持する。スタイル形式で使用される。

typedef struct _DMUS_IO_PARTREF {
    GUID  guidPartID;
    WORD  wLogicalPartID;
    BYTE  bVariationLockID;
    BYTE  bSubChordLevel;
    BYTE  bPriority;
    BYTE  bRandomVariation;
    WORD  wPad;
    DWORD dwPChannel;
} DMUS_IO_PARTREF;

メンバ

guidPartID
パートの識別子。
wLogicalPartID
ポート上の特定の MIDI チャンネルに対応している識別子。このメンバは、dwPChannel に引き継がれ、今後は使用されない。
bVariationLockID
ロック識別子のバリエーション。このメンバ内の値と同じ値を持つパートは、常に同じバリエーションを演奏する。値 0 は、パートがバリエーションをその他のパートとは別に演奏することを意味する。
bSubChordLevel
このパートが必要とするサブコード レベル。「注意」を参照すること。
bPriority
将来の使用に備えて予約されている。
bRandomVariation
一致するバリエーションを順に演奏する場合は 0。または、DMUS_VARIATIONT_TYPES 列挙型のメンバのいずれか。
wPad
アラインメントのためのパディング。値は使用されない。
dwPChannel
パートのパフォーマンス チャンネル。

注意

bSubChordLevel メンバは、0 から始まるインデックス値を持つ。実行時には、この値によって 1 が左シフトされ、DMUS_SUBCHORD 構造体の dwLevels メンバと比較するための 1 ビット値が生成される。したがって、bSubChordLevel が 0 のパートは、dwLevels に 1 を含んでいた任意のサブコードにマップされる。

動作環境

ヘッダー : dmusicf.h で宣言。


DMUS_IO_PATTERN

パターンに関する情報を保持する。スタイル形式で使用される。

typedef struct _DMUS_IO_PATTERN {
    DMUS_IO_TIMESIG  timeSig;
    BYTE             bGrooveBottom;
    BYTE             bGrooveTop;
    WORD             wEmbellishment;
    WORD             wNbrMeasures;
    BYTE             bDestGrooveBottom;
    BYTE             bDestGrooveTop;
    DWORD            dwFlags;
} DMUS_IO_PATTERN;

メンバ

timeSig
スタイルのデフォルトの拍子記号をオーバーライドする拍子記号を保持する DMUS_IO_TIMESIG 構造体。
bGrooveBottom
グルーブ範囲の最低音。
bGrooveTop
グルーブ範囲の最高音。
wEmbellishment
装飾のタイプ。DMUS_COMMANDT_TYPES 列挙型の定数の 1 つ、またはコンテンツ プロバイダが定義する値。
wNbrMeasures
小節内のパターンの長さ。
bDestGrooveBottom
次のパターンのグルーブ範囲の最低音。
bDestGrooveTop
次のパターンのグルーブ範囲の最高音。
dwFlags
フラグ。0 または次の値を使用できる。
DMUS_PATTERNF_PERSIST_CONTROL
パターンベース トラックの状態データのバリエーション設定は、演奏終了後もトラック内で継続される。

動作環境

ヘッダー : dmusicf.h で宣言。


DMUS_IO_PCHANNELTOBUFFER_HEADER

パフォーマンス チャンネルの範囲と、接続先のバッファを定義する。オーディオパス形式のポート構成リストで使用される。

typedef struct _DMUS_IO_PCHANNELTOBUFFER_HEADER {
    DWORD  dwPChannelBase;
    DWORD  dwPChannelCount;
    DWORD  dwBufferCount;
    DWORD  dwFlags;
} DMUS_IO_PCHANNELTOBUFFER_HEADER;

メンバ

dwPChannelBase
最初のパフォーマンス チャンネル。
dwPChannelCount
パフォーマンス チャンネルの数。
dwBufferCount
チャンネルが接続するバッファの数。
dwFlags
予約済み。0 でなければならない。

動作環境

ヘッダー : dmusicf.h で宣言。


DMUS_IO_PLAYMARKER

演奏マーカーに関する情報を保持する。演奏マーカーは、新しいセグメントが演奏開始を許可されたプライマリ セグメント内のポイントである。マーカー トラック リストで使用される。

typedef struct _DMUS_IO_PLAY_MARKER {
    MUSIC_TIME mtTime;
} DMUS_IO_PLAY_MARKER;

メンバ

mtTime
有効な演奏ポイントのタイム。

動作環境

ヘッダー : dmusicf.h で宣言。


DMUS_IO_PORTCONFIG_HEADER

オーディオパス形式で使用される。

typedef struct _DMUS_IO_PORTCONFIG_HEADER {
    GUID    guidPort;
    DWORD   dwPChannelBase;
    DWORD   dwPChannelCount;
    DWORD   dwFlags;
} DMUS_IO_PORTCONFIG_HEADER;

メンバ

guidPort
ポートの一意な識別子。
dwPChannelBase
最初のパフォーマンス チャンネル。
dwPChannelCount
パフォーマンス チャンネルの数。
dwFlags
構成フラグ。次の値が定義されている。
DMUS_PORTCONFIGF_DRUMSON10
ドラムはチャンネル 10 である。
DMUS_PORTCONFIGF_USEDEFAULT
デフォルトのポートを使用する。

動作環境

ヘッダー : dmusicf.h で宣言。


DMUS_IO_REFERENCE

別のファイルに保存されている別のオブジェクトへの参照に関する情報を保持する。参照リスト チャンクで使用される。

typedef struct _DMUS_IO_REFERENCE {
    GUID    guidClassID;
    DWORD   dwValidData;
} DMUS_IO_REFERENCE;

メンバ

guidClassID
クラス識別子。
dwValidData
参照のどのデータ チャンクが存在するかを示すフラグ。値のリストについては、対応する DMUS_OBJECTDESC のメンバを参照すること。

動作環境

ヘッダー : dmusicf.h で宣言。


DMUS_IO_SCRIPT_HEADER

スクリプト形式で使用される。

typedef struct _DMUS_IO_SCRIPT_HEADER {
    DWORD  dwFlags;
} DMUS_IO_SCRIPT_HEADER;

メンバ

dwFlags
スクリプトのロード動作を指定する DWORD 値。次の 1 つ以上の値を指定できる。
DMUS_SCRIPTIOF_LOAD_ALL_CONTENT
スクリプトのコンテナ内のすべてのコンテンツをロードする。
DMUS_SCRIPTIOF_DOWNLOAD_ALL_SEGMENTS
DMUS_SCRIPTIOF_LOAD_ALL_CONTENT が設定されている場合、スクリプトのコンテナに含まれるすべてのセグメントのバンドが、スクリプトの初期化時にダウンロードされる。それ以外の場合、セグメントのバンドは、スクリプトがセグメントをロードするときにダウンロードされる。

DMUS_SCRIPTIOF_DOWNLOAD_ALL_SEGMENTS が設定されていない場合、スクリプトはセグメントのバンドのダウンロードとアンロードを手動で行わなければならない。

動作環境

ヘッダー : dmusicf.h で宣言。


DMUS_IO_SCRIPTTRACK_EVENTHEADER

スクリプト トラック リストで使用される。

typedef struct _DMUS_IO_SCRIPTTRACK_EVENTHEADER {
    DWORD dwFlags;
    MUSIC_TIME lTimeLogical;
    MUSIC_TIME lTimePhysical;
} DMUS_IO_SCRIPTTRACK_EVENTHEADER;

メンバ

dwFlags
イベントをいつ設定するかを決定するフラグ。次のいずれかの値を指定する。
DMUS_IO_SCRIPTTRACKF_PREPARE
タイム スタンプより前の、準備時間にイベントを起動する。目的の時間に音楽を変更するために十分な時間がスクリプトに残されるので、これがデフォルトである。
DMUS_IO_SCRIPTTRACKF_QUEUE
タイム スタンプ直前の、キュー時間にイベントを起動する。
DMUS_IO_SCRIPTTRACKF_ATTIME
タイム スタンプちょうどにイベントを起動する。
lTimeLogical
イベントの論理タイム。
lTimePhysical
イベントの実際のタイム。

動作環境

ヘッダー : dmusicf.h で宣言。

参照

論理的なタイムと実際のタイム


DMUS_IO_SEGMENT_HEADER

セグメントに関する情報を保持する。セグメント形式で使用される。

typedef struct _DMUS_IO_SEGMENT_HEADER {
    DWORD          dwRepeats;
    MUSIC_TIME     mtLength;
    MUSIC_TIME     mtPlayStart;
    MUSIC_TIME     mtLoopStart;
    MUSIC_TIME     mtLoopEnd;
    DWORD          dwResolution;
    REFERENCE_TIME rtLength;
    DWORD          dwFlags;
    DWORD          dwReserved;
} DMUS_IO_SEGMENT_HEADER;

メンバ

dwRepeats
反復回数。
mtLength
セグメントの長さ。
mtPlayStart
再生の開始ポイント。通常は 0 に設定する。
mtLoopStart
ループ部分の開始ポイント。通常は 0 に設定する。
mtLoopEnd
ループ部分の終了ポイント。mtPlayStart より大きい値でなければならない。セグメント全体をループする場合は 0。
dwResolution
デフォルトの分解能。「DMUS_TIME_RESOLVE_FLAGS」を参照すること。
rtLength
基準タイム内のセグメントの長さ。DMUS_SEGIOF_REFLENGTH フラグが設定されている場合に有効である。
dwFlags
0 または次のフラグを指定する。
DMUS_SEGIOF_REFLENGTH
rtLength の値が mtLength をオーバーライドする。
dwReserved
予約済み。

動作環境

ヘッダー : dmusicf.h で宣言。

参照

DMUS_IO_MOTIFSETTINGS、IDirectMusicSegment8::SetLoopPoints


DMUS_IO_SEGMENT_ITEM_HEADER

セグメント トリガ トラック リストで参照されるセグメントに関する情報を保持する。

typedef struct _DMUS_IO_SEGMENT_ITEM_HEADER{
    MUSIC_TIME      lTimeLogical;
    MUSIC_TIME      lTimePhysical;
    DWORD           dwPlayFlags;
    DWORD           dwFlags;
} DMUS_IO_SEGMENT_ITEM_HEADER;

メンバ

lTimeLogical
イベントが関連付けられているミュージック タイム。
lTimePhysical
セグメントを演奏する実際のタイム。
dwPlayFlags
IDirectMusicPerformance8::PlaySegmentEx に渡されるフラグ。「DMUS_SEGF_FLAGS」を参照すること。
dwFlags
0 または次の値を指定する。
DMUS_SEGMENTTRACKF_MOTIF
DMRF チャンクはスタイルへのリンクであり、'snam' チャンクはスタイル内のモチーフの名前である。

動作環境

ヘッダー : dmusicf.h で宣言。


DMUS_IO_SEGMENT_TRACK_HEADER

セグメント トリガ トラック リストに関する情報を保持する。

typedef struct _DMUS_IO_SEGMENT_TRACK_HEADER {
    DWORD dwFlags;
} DMUS_IO_SEGMENT_TRACK_HEADER;

メンバ

dwFlags
予約済み。0 に設定する。

動作環境

ヘッダー : dmusicf.h で宣言。


DMUS_IO_SEGREF_HEADER

DirectX 8.0 では実装されない。

ソング形式でのセグメント参照に関する情報を保持する。

typedef struct _DMUS_IO_SEGREF_HEADER {
    DWORD       dwID;
    DWORD       dwSegmentID;
    DWORD       dwToolGraphID;
    DWORD       dwFlags;
    DWORD       dwNextPlayID;
} DMUS_IO_SEGREF_HEADER;

メンバ

dwID
セグメントの一意な識別子。DMUS_SONG_MAXSEGID 以下でなければならない。
dwSegmentID
リンク先のオプションのソース セグメントの識別子。
dwToolGraphID
処理に使用するオプションのツールグラフの識別子。
dwFlags
予約済み。0 に設定する。
dwNextPlayID
ソング チェーンの次のセグメントの識別子。


DMUS_IO_SEQ_ITEM

シーケンス トラック内のデータ項目に関する情報を保持する。シーケンス トラック チャンクで使用される。

typedef struct _DMUS_IO_SEQ_ITEM {
    MUSIC_TIME  mtTime;
    MUSIC_TIME  mtDuration;
    DWORD       dwPChannel;
    short       nOffset
    BYTE        bStatus;
    BYTE        bByte1;
    BYTE        bByte2;
} DMUS_IO_SEQ_ITEM;

メンバ

mtTime
イベントの論理タイム。
mtDuration
イベントが有効な持続時間。
dwPChannel
イベントのパフォーマンス チャンネル。
nOffset
ノートが演奏される mtTime からのオフセット。ミュージック タイムで表される。
bStatus
MIDI イベント タイプ。MIDI ステータス バイトと同じだが、チャンネル情報がない。
bByte1
MIDI データの最初の 1 バイト。
bByte2
MIDI データの 2 バイト目。

動作環境

ヘッダー : dmusicf.h で宣言。

参照

DMUS_IO_CURVE_ITEM、MIDI メッセージ


DMUS_IO_SIGNPOST

コード マップ内のサインポスト コードに関連付けられた、サインポスト トラック内のサインポストに関する情報を保持する。サインポスト トラック チャンクで使用される。

typedef struct _DMUS_IO_SIGNPOST {
    MUSIC_TIME  mtTime;
    DWORD       dwChords;
    WORD        wMeasure;
} DMUS_IO_SIGNPOST;

メンバ

mtTime
サインポストのタイム。
dwChords
このサインポストに関連付けることのできるサインポスト コードのタイプ。テンプレート内の値と同じ値であるかを照合するために、これらの値が使われる。テンプレートを使うアレンジは、特に、テンプレート内でこれらの値を探し、これらの値と一致するコード マップ内の実際のコードを見つける作業から成る。次のフラグが定義されている。
DMUS_SIGNPOSTF_A
DMUS_SIGNPOSTF_B
DMUS_SIGNPOSTF_C
DMUS_SIGNPOSTF_D
DMUS_SIGNPOSTF_E
DMUS_SIGNPOSTF_F
DMUS_SIGNPOSTF_LETTER
DMUS_SIGNPOSTF_1
DMUS_SIGNPOSTF_2
DMUS_SIGNPOSTF_3
DMUS_SIGNPOSTF_4
DMUS_SIGNPOSTF_5
DMUS_SIGNPOSTF_6
DMUS_SIGNPOSTF_7
DMUS_SIGNPOSTF_ROOT
DMUS_SIGNPOSTF_CADENCE

wMeasure
サインポストが所属する小節。

動作環境

ヘッダー : dmusicf.h で宣言。

参照

DMUS_IO_CHORDMAP_SIGNPOST


DMUS_IO_SONG_HEADER

DirectX 8.0 では実装されない。

ソング形式に関する情報を保持する。

typedef struct _DMUS_IO_SONG_HEADER {
    DWORD  dwFlags;
    DWORD  dwStartSegID;
} DMUS_IO_SONG_HEADER;

メンバ

dwFlags
予約済み。
dwStartSegID
最初に演奏するセグメントの識別子。

動作環境

ヘッダー : dmusicf.h で宣言。


DMUS_IO_STYLE

スタイルの拍子記号とテンポに関する情報を保持する。スタイル形式で使用される。

typedef struct _DMUS_IO_STYLE {
    DMUS_IO_TIMESIG  timeSig;
    double           dblTempo;
} DMUS_IO_STYLE;

メンバ

timeSig
スタイルのデフォルトの拍子記号を保持する DMUS_IO_TIMESIG 構造体。
dblTempo
スタイルのテンポ。

動作環境

ヘッダー : dmusicf.h で宣言。


DMUS_IO_STYLE_ANTICIPATION

解決アンティシペーションを表す。スタイル形式で使用される。

typedef struct _DMUS_IO_STYLE_ANTICIPATION {
    MUSIC_TIME    mtGridStart;
    DWORD         dwVariation;
    short         nTimeOffset;
    BYTE          bTimeRange;
} DMUS_IO_STYLE_ANTICIPATION;

メンバ

mtGridStart
イベントが演奏されるパート内のオフセット。グリッドで表される。「注意」を参照すること。
dwVariation
バリエーション。設定された各ビットが有効なバリエーションを指定する。
nTimeOffset
mtGridStart からのタイムのオフセット。
bTimeRange
ランダム時間の範囲。「注意」を参照すること。

注意

イベントのタイムは次のように計算できる。TimeSig は、拍子記号を保持する DMUS_IO_TIMESIG 構造体である。

mtEventTime = nTimeOffset + ((mtGridStart / TimeSig.wGridsPerBeat) *
((DMUS_PPQ * 4) / TimeSig.bBeat) + (mtGridStart %
TimeSig.wGridsPerBeat) * (((DMUS_PPQ * 4)/ TimeSig.bBeat) /
TimeSig.wGridsPerBeat))

bTimeRange の値は、「DMUS_IO_STYLENOTE」の「注意」に示されている公式に従って、イベントの発生時にミュージック タイムに変換される。

動作環境

ヘッダー : dmusicf.h で宣言。


DMUS_IO_STYLECURVE

スタイル内のカーブに関する情報を保持する。スタイル形式で使用される。

typedef struct _DMUS_IO_STYLECURVE {
    MUSIC_TIME  mtGridStart;
    DWORD       dwVariation;
    MUSIC_TIME  mtDuration;
    MUSIC_TIME  mtResetDuration;
    short       nTimeOffset;
    short       nStartValue;
    short       nEndValue;
    short       nResetValue;
    BYTE        bEventType;
    BYTE        bCurveShape;
    BYTE        bCCData;
    BYTE        bFlags;
    WORD        wParamType;
    WORD        wMergeIndex;
} DMUS_IO_STYLECURVE;

メンバ

mtGridStart
カーブが発生する時点のオフセット。グリッドで表される。
dwVariation
このカーブが所属するバリエーション。各ビットは 32 あるバリエーションのいずれかに対応する。
mtDuration
カーブの持続時間。
mtResetDuration
リセットできる間のカーブ終了後の時間。
nTimeOffset
カーブが発生する mtGridStart からのオフセット。「DMUS_IO_STYLE_ANTICIPATION」の「注意」を参照すること。
nStartValue
開始値。
nEndValue
終了値。
nResetValue
mtResetDuration によって指定される時間の間にフラッシュ (解放) または無効化を設定するリセット値。
bEventType
カーブのタイプ。「DMUS_IO_CURVE_ITEM」を参照すること。
bCurveShape
カーブの形状。「DMUS_IO_CURVE_ITEM」を参照すること。
bCCData
コントロール チェンジ タイプの場合は、CC 番号を指定する。
bFlags
トランジションが原因で無効化が発生したときに nResetValue を設定しなければならない場合は、DMUS_CURVE_RESET を設定する。この値を 0 に設定した場合、カーブは新しい値に永続的にとどまる。ほかのすべてのビットは予約されている。
wParamType
RPN または NRPN のパラメータ番号。
wMergeIndex
マージ インデックス。モッド ホイール、リバーブの送信、コーラスの送信、ピッチ ベンド、ボリューム、およびエクスプレッション コントローラ用にサポートされる。

動作環境

ヘッダー : dmusicf.h で宣言。

参照

DMUS_CURVE_PMSG、DMUS_IO_CURVE_ITEM


DMUS_IO_STYLEMARKER

スタイル内のマーカーに関する情報を保持する。スタイル形式で使用される。

typedef struct _DMUS_IO_STYLEMARKER {
    MUSIC_TIME  mtGridStart;
    DWORD       dwVariation;
    WORD        wMarkerFlags;
} DMUS_IO_STYLEMARKER;

メンバ

mtGridStart
マーカーが発生する時点のオフセット。グリッドで表される。
dwVariation
このマーカーが所属するバリエーション。各ビットは 32 あるバリエーションのいずれかに対応する。
wMarkerFlags
マーカーの動作を指定するフラグ。0 または次の 1 つ以上の値を指定できる。0 の場合、動作は DirectX バージョン 7.0 と同じである。
DMUS_MARKERF_START
バリエーションを開始する。
DMUS_MARKERF_STOP
バリエーションを停止する。
DMUS_MARKERF_CHORD_ALIGN
新しいバリエーションはコードに揃える必要がある。DMUS_MARKERF_START と DMUS_MARKERF_STOP が指定されていない場合、このフラグは無視される。

動作環境

ヘッダー : dmusicf.h で宣言。


DMUS_IO_STYLENOTE

スタイル内のノートに関する情報を保持する。スタイル形式で使用される。

typedef struct _DMUS_IO_STYLENOTE {
    MUSIC_TIME  mtGridStart;
    DWORD       dwVariation;
    MUSIC_TIME  mtDuration;
    short       nTimeOffset;
    WORD        wMusicValue;
    BYTE        bVelocity;
    BYTE        bTimeRange;
    BYTE        bDurRange;
    BYTE        bVelRange;
    BYTE        bInversionID;
    BYTE        bPlayModeFlags;
    BYTE        bNoteFlags;
} DMUS_IO_STYLENOTE;

メンバ

mtGridStart
ノートが発生する時点のオフセット。グリッドで表される。
dwVariation
このノートが所属するバリエーション。各ビットは 32 あるバリエーションのいずれかに対応する。
mtDuration
ノートの持続時間。
nTimeOffset
イベントが発生する mtGridStart 後のタイム。「DMUS_IO_STYLE_ANTICIPATION」の「注意」を参照すること。
wMusicValue
スケール内の位置。
bVelocity
ノートのベロシティ。
bTimeRange
開始タイムをランダム化する範囲。「注意」を参照すること。
bDurRange
持続時間をランダム化する範囲。「注意」を参照すること。
bVelRange;
ベロシティをランダム化する範囲。
bInversionID
このノートが所属する転回グループの識別子。
bPlayModeFlags
パートの演奏モードをオーバーライドするフラグ。値のリストについては、「DMUS_PLAYMODE_FLAGS」を参照すること。
bNoteFlags
フラグ。「DMUS_NOTEF_FLAGS」を参照すること。

注意

bTimeRange および bDurRange の値は、次の関数を使用して、ノートが演奏されるときにミュージック タイムに変換される。

int StoredRangeToActualRange(BYTE bRange)
{
    int nResult = 0;
    if (0 <= bRange && bRange <= 190)
    {
        nResult = bRange;
    }
    else if (191 <= bRange && bRange <= 212)
    {
        nResult = ((bRange - 190) * 5) + 190;
    }
    else if (213 <= bRange && bRange <= 232)
    {
        nResult = ((bRange - 212) * 10) + 300;
    }
    else // bRange > 232
    {
        nResult = ((bRange - 232) * 50) + 500;
    }
    return nResult;
}

動作環境

ヘッダー : dmusicf.h で宣言。


DMUS_IO_STYLEPART

パートに関する情報を保持する。スタイル形式で使用される。

typedef struct _DMUS_IO_STYLEPART {
    DMUS_IO_TIMESIG  timeSig;
    DWORD            dwVariationChoices[32];
    GUID             guidPartID;
    WORD             wNbrMeasures;
    BYTE             bPlayModeFlags;
    BYTE             bInvertUpper;
    BYTE             bInvertLower;
    BYTE             bPad[3];
    DWORD            dwFlags;
} DMUS_IO_STYLEPART;

メンバ

timeSig
スタイルのデフォルトの拍子記号をオーバーライドする拍子記号を保持する DMUS_IO_TIMESIG 構造体。
dwVariationChoices
各要素は、32 あるバリエーションのいずれかに対応する。各要素に設定されるフラグは、そのバリエーションでサポートされるコードのタイプを示す (「注意」を参照)。また、バリエーションが DirectMusic モードと IMA モードのどちらであるかを指定するために、モード マスクの 1 つを設定しなければならない。

次のフラグが定義されている。

DMUS_VARIATIONF_MAJOR
メジャー コードのスケール内の 7 つの位置。
DMUS_VARIATIONF_MINOR
マイナー コードのスケール内の 7 つの位置。
DMUS_VARIATIONF_OTHER
その他のコードのスケール内の 7 つの位置。
DMUS_VARIATIONF_ROOT_SCALE
スケール内のコード ルート音を処理する。
DMUS_VARIATIONF_ROOT_FLAT
フラットのコード ルート音を処理する (スケール内のノートに基づく)。
DMUS_VARIATIONF_ROOT_SHARP
シャープのコード ルート音を処理する (スケール内のノートに基づく)。
DMUS_VARIATIONF_TYPE_TRIAD
3 和音の単体コードを処理する。
DMUS_VARIATIONF_TYPE_6AND7
6 と 7 の単体コードを処理する。
DMUS_VARIATIONF_TYPE_COMPLEX
複合コードを処理する。
DMUS_VARIATIONF_DEST_TO1
1 のコードへのトランジションを処理する。
DMUS_VARIATIONF_DEST_TO5
5 のコードへのトランジションを処理する。
DMUS_VARIATIONF_MODES
モード マスク。使用しない。
DMUS_VARIATIONF_MODES_EX
モード マスク。
DMUS_VARIATIONF_IMA25_MODE
モード マスク。(dwVariationChoices & DMUS_VARIATIONF_MODES_EX) == DMUS_VARIATIONF_IMA25_MODE である場合、バリエーションは IMA (Interactive Music Architecture) モードである。
DMUS_VARIATIONF_DMUS_MODE
モード マスク。dwVariationChoices にこのマスクが含まれる場合、バリエーションは DirectMusic モードである。DirectMusic Producer でオーサリングされたすべてのバリエーションは、このモードを使用する。
guidPartID
パートの一意の識別子。
wNbrMeasures
パートの長さ。小節単位で表す。
bPlayModeFlags
演奏モードを定義するフラグ。値のリストについては、「DMUS_PLAYMODE_FLAGS」を参照すること。
bInvertUpper
転回の上限。
bInvertLower
転回の下限。
bPad
未使用。
dwFlags
パートの動作を指定するフラグ。次の値を指定できる。
DMUS_PARTF_USE_MARKERS
パートはマーカー イベントを使用する。
DMUS_PARTF_ALIGN_CHORDS
パートは、コードに揃えられたマーカー上でのみ切り替えることができる。

注意

dwVariationChoices 内のフラグは、DirectMusic モードで指定したバリエーションによってサポートされるコードのタイプを決定する。最初の 7 つのフラグ (ビット 1 ～ 7) は、バリエーションがスケール位置に基づくメジャー コードをサポートする場合に設定する。たとえば、1、2、4 の各ビットが設定された場合、バリエーションは主音、2 度、4 度のスケール位置に基づくメジャー コードをサポートする。次の 7 つのフラグはマイナー コードに対して同様に機能し、その次の 7 つのフラグはメジャーおよびマイナー以外のコードに対して同様に機能する (SUS 4 コードなど)。22、23、24 の各ビットは、バリエーションがそれぞれスケールに基づくコード、スケールの音程のシャープに基づくコード、スケールの音程のフラットに基づくコードをサポートする場合に設定する。たとえば、C メジャーのスケールで C# マイナー コードをサポートするには、ビット 8 (同主マイナー) とビット 24 (シャープ) を設定する必要がある。25、26、27 の各ビットは、それぞれ 3 和音のコード、6 度または 7 度のコード、拡張されたコードを処理する。28 と 29 の各ビットは、それぞれ主音のコードと属音のコードが続くコードを処理する。

動作環境

ヘッダー : dmusicf.h で宣言。


DMUS_IO_STYLERESOLUTION

スタイル解決を表す。スタイル形式で使用される。

typedef struct _DMUS_IO_STYLERESOLUTION {
    DWORD  dwVariation;
    WORD   wMusicValue;
    BYTE   bInversionID;
    BYTE   bPlayModeFlags;
} DMUS_IO_STYLERESOLUTION;

メンバ

dwVariation
バリエーション。各ビットが有効なバリエーションを指定する。
wMusicValue
スケール内の位置。
bInversionID
このノートが所属する転回グループ。
bPlayModeFlags
演奏モード フラグ。「DMUS_PLAYMODE_FLAGS」を参照すること。

動作環境

ヘッダー : dmusicf.h で宣言。


DMUS_IO_SUBCHORD

サブコードに関する情報を保持する。コード トラック リストで使用される。

typedef struct _DMUS_IO_SUBCHORD {
    DWORD   dwChordPattern;
    DWORD   dwScalePattern;
    DWORD   dwInversionPoints;
    DWORD   dwLevels;
    BYTE    bChordRoot;
    BYTE    bScaleRoot;
} DMUS_IO_SUBCHORD;

メンバ

dwChordPattern
サブコード内のノート。下位 24 ビットはそれぞれ 1 つの半音を表し、最下位ビットはルート音である。ビットがセットされている場合、それに対応するノートはコード内に存在する。
dwScalePattern
スケール内のノート。下位 24 ビットはそれぞれ 1 つの半音を表し、最下位ビットはルート音である。ビットがセットされている場合、それに対応するノートはスケール内に存在する。
dwInversionPoints
スケール内で転回が発生できるポイント。ビットがオフになっている場合、それに対応する音程ではノートを転回できない。たとえば、パターン 100001111111 は、陽音階 (メジャー スケール) の 5 度と 7 度を除き、どこでも転回が認められることを意味する。
dwLevels
このサブコードがサポートするレベル。特定の音色を異なったレベルに割り当て (たとえばコードのサブコードだけを演奏する)、サブコードをそれらのレベルにマップする手法としてこの値を利用することもできる。
bChordRoot
サブコードのルート音。0 は範囲内の最低音の C、23 は最高音の B である。
bScaleRoot
スケールのルート音。0 は範囲内の最低音の C、23 は最高音の B である。

動作環境

ヘッダー : dmusicf.h で宣言。

参照

DMUS_SUBCHORD


DMUS_IO_SYSEX_ITEM

MIDI のシステム エクスクルーシブ メッセージに関する情報を保持する。システム エクスクルーシブ トラック チャンクで使用される。

typedef struct _DMUS_IO_SYSEX_ITEM {
    MUSIC_TIME  mtTime;
    DWORD       dwPChannel;
    DWORD       dwSysExLength;
} DMUS_IO_SYSEX_ITEM;

メンバ

mtTime
メッセージのタイム。
dwPChannel
イベントのパフォーマンス チャンネル。
dwSysExLength
データの長さ。バイト単位で指定する。

動作環境

ヘッダー : dmusicf.h で宣言。

参照

MIDI システム メッセージ


DMUS_IO_TEMPO_ITEM

トラック内のテンポの変更に関する情報を保持する。テンポ トラック チャンクで使用される。

typedef struct _DMUS_IO_TEMPO_ITEM {
    MUSIC_TIME  lTime;
    double      dblTempo;
} DMUS_IO_TEMPO_ITEM;

メンバ

lTime
テンポを変更するタイム。
dblTempo
テンポ。1 分あたりの拍数で表す。

動作環境

ヘッダー : dmusicf.h で宣言。


DMUS_IO_TIMESIG

セグメントの拍子記号に関する情報を保持する。DMUS_IO_STYLE、DMUS_IO_VERSION、および DMUS_IO_PATTERN の各構造体で使用される。

typedef struct _DMUS_IO_TIMESIG {
    BYTE  bBeatsPerMeasure;
    BYTE  bBeat;
    WORD  wGridsPerBeat;
} DMUS_IO_TIMESIG;

メンバ

bBeatsPerMeasure
小節あたりの拍数 (拍子記号の分子)。
bBeat
ノートが受け取る拍 (拍子記号の分母)。この値が 1 のときは全音符、2 のときは 2 分音符、4 のときは 4 分音符を意味する。以下同様である。0 は 256 分音符を意味する。
wGridsPerBeat
拍あたりのグリッド (小分割)。

動作環境

ヘッダー : dmusicf.h で宣言。

参照

DMUS_IO_TIMESIGNATURE_ITEM


DMUS_IO_TIMESIGNATURE_ITEM

拍子記号の変更に関する情報を保持する。拍子記号トラック リストで使用される。

typedef struct _DMUS_IO_TIMESIGNATURE_ITEM {
    MUSIC_TIME  lTime;
    BYTE        bBeatsPerMeasure;
    BYTE        bBeat;
    WORD        wGridsPerBeat;
} DMUS_IO_TIMESIGNATURE_ITEM;

メンバ

lTime
イベントのタイム。
bBeatsPerMeasure
小節あたりの拍数 (拍子記号の分子)。
bBeat
ノートが受け取る拍 (拍子記号の分母)。この値が 1 のときは全音符、2 のときは 2 分音符、4 のときは 4 分音符を意味する。以下同様である。0 は 256 分音符を意味する。
wGridsPerBeat
拍あたりのグリッド (小分割)。

動作環境

ヘッダー : dmusicf.h で宣言。

参照

DMUS_IO_TIMESIG、DMUS_TIMESIG_PMSG


DMUS_IO_TOOL_HEADER

ツールに関する情報を保持する。ツール形式で使用される。

typedef struct _DMUS_IO_TOOL_HEADER {
    GUID    guidClassID;
    long    lIndex;
    DWORD   cPChannels;
    FOURCC  ckid;
    FOURCC  fccType;
    DWORD   dwPChannels[1];
} DMUS_IO_TOOL_HEADER;

メンバ

guidClassID
ツールのクラス識別子。
lIndex
グラフ内の位置。
cPChannels
dwPChannels 配列内の項目の数。
ckid
ツールのデータ チャンクの識別子。この値が 0 の場合、チャンクのタイプは LIST と見なされる。その場合、fccType は有効で、0 以外の値でなければならない。
fccType
リスト タイプ。この値が 0 の場合、ckid は有効で、0 以外の値でなければならない。
dwPChannels
ツールが有効なパフォーマンス チャンネルの配列。

動作環境

ヘッダー : dmusicf.h で宣言。

参照

IDirectMusicGraph8::InsertTool


DMUS_IO_TRACK_EXTRAS_HEADER

トラック形式で使用される。

typedef struct _DMUS_IO_TRACK_EXTRAS_HEADER {
    DWORD  dwFlags;
} DMUS_IO_TRACK_EXTRAS_HEADER;

メンバ

dwFlags
制御トラックのフラグ。使用できる値については、「IDirectMusicSegment8::SetTrackConfig」を参照すること。

動作環境

ヘッダー : dmusicf.h で宣言。


DMUS_IO_TRACK_HEADER

トラックに関する情報を保持する。トラック形式で使用される。

typedef struct _DMUS_IO_TRACK_HEADER {
    GUID     guidClassID;
    DWORD    dwPosition;
    DWORD    dwGroup;
    FOURCC   ckid;
    FOURCC   fccType;
} DMUS_IO_TRACK_HEADER;

メンバ

guidClassID
トラックのクラス識別子。
dwPosition
トラック リスト内の位置。
dwGroup
トラックのグループ ビット。
ckid
トラックのデータ チャンクの識別子。この値が 0 の場合、チャンクのタイプは LIST と見なされる。その場合、fccType は有効で、0 以外の値でなければならない。
fccType
リスト タイプ。この値が 0 の場合、ckid は有効で、0 以外の値でなければならない。

動作環境

ヘッダー : dmusicf.h で宣言。

参照

IDirectMusicSegment8::GetTrackGroup、IDirectMusicSegment8::InsertTrack、トラック形式


DMUS_IO_TRACKREF_HEADER

DirectX 8.0 では実装されない。

ソング形式でのトラック参照に関する情報を保持する。

typedef struct _DMUS_IO_TRACKREF_HEADER {
    DWORD       dwSegmentID;
    DWORD       dwFlags;
} DMUS_IO_TRACKREF_HEADER;

メンバ

dwSegmentID
所属するセグメントの識別子。
dwFlags
予約済み。


DMUS_IO_TRANSITION_DEF

DirectX 8.0 では実装されない。

トランジションを表す。ソング形式で使用される。

typedef struct _DMUS_IO_TRANSITION_DEF {
    DWORD  dwSegmentID;
    DWORD  dwTransitionID;
    DWORD  dwPlayFlags;
} DMUS_IO_TRANSITION_DEF;

メンバ

dwSegmentID
トランジション後のセグメントまたは次の定数のいずれかになる。
DMUS_SONG_ANYSEG
任意のセグメント。
DMUS_SONG_NOFROMSEG
先行するセグメントがない。トランジションはイントロである。
DMUS_SONG_NOSEG
後続のセグメントがない。トランジションはエンディングである。
dwTransitionID
トランジションに使用するテンプレート セグメント。
dwPlayFlags
トランジションの演奏方法を制御するフラグ。「DMUS_SEGF_FLAGS」を参照すること。

注意

この構造体は、別のセグメントからこのセグメントへの有効なトランジションを表す。ソング セグメントを DMUS_SEGF_AUTOTRANSITION フラグを使用して演奏する場合は、トランジション セグメントがアレンジされて演奏される。適切なトランジション セグメントを見つけるには、パフォーマンスで現在演奏中のセグメントを確認し、ソングのセグメントかどうかを判断する。適切なセグメントである場合は、そのセグメントの ID を取得し、次に転送先セグメントのトランジション テーブルで目的のセグメントを検索する。dwSourceSegment で一致するセグメントが見つかった場合は、dwPlayFlags を使用して、パフォーマンスが dwTransitionSegment をアレンジし、演奏する。

動作環境

ヘッダー : dmusicf.h で宣言。


DMUS_IO_VALID_START

リズムに挿入される、セグメント内の有効な開始ポイントに関する情報を保持する。マーカー トラック リストで使用される。

typedef struct _DMUS_IO_VALID_START {
    MUSIC_TIME mtTime;
} DMUS_IO_VALID_START;

メンバ

mtTime
開始ポイントのタイム。

動作環境

ヘッダー : dmusicf.h で宣言。


DMUS_IO_VERSION

データのバージョン番号を保持する。さまざまなチャンクのバージョン サブチャンク内で使用される。「共通のチャンク」を参照すること。

typedef struct _DMUS_IO_VERSION {
    DWORD  dwVersionMS;
    DWORD  dwVersionLS;
} DMUS_IO_VERSION;

メンバ

dwVersionMS
バージョン番号の上位 32 ビット。
dwVersionLS
バージョン番号の下位 32 ビット。

動作環境

ヘッダー : dmusicf.h で宣言。


DMUS_IO_WAVE_HEADER

ウェーブのストリーミング特性を表す。ウェーブ ファイルのウェーブ ヘッダー チャンクで使用される。

typedef struct _DMUS_IO_WAVE_HEADER {
    REFERENCE_TIME  rtReadAhead;
    DWORD           dwFlags;
} DMUS_IO_WAVE_HEADER;

メンバ

rtReadAhead
ストリーミング ウェーブで先行して読み取るタイム。
dwFlags
フラグ。0 または次の値を指定する。
DMUS_WAVEF_STREAMING
ウェーブはストリーミング ウェーブである。

動作環境

ヘッダー : dmusicf.h で宣言。


DMUS_IO_WAVE_ITEM_HEADER

ウェーブ トラック リストのウェーブ サウンドのデータを保持する。

typedef struct _DMUS_IO_WAVE_ITEM_HEADER {
    long           lVolume;
    long           lPitch;
    DWORD          dwVariations;
    REFERENCE_TIME rtTime;
    REFERENCE_TIME rtStartOffset;
    REFERENCE_TIME rtReserved;
    REFERENCE_TIME rtDuration;
    MUSIC_TIME     mtLogicalTime;
    DWORD          dwLoopStart;
    DWORD          dwLoopEnd;
    DWORD          dwFlags;
} DMUS_IO_WAVE_ITEM_HEADER;

メンバ

lVolume
ゲイン。1/100 dB (デシベル) 単位で指定する。負の値でなければならない。
lPitch
ピッチ オフセット。1/100 半音単位で指定する。
dwVariations
バリエーション フラグ。このウェーブが所属するバリエーションごとに 1 ビットが設定される。
rtTime
開始タイム。トラックがクロック タイム形式である場合は基準タイム。それ以外の場合はミュージック タイム。
rtStartOffset
再生を開始するウェーブまでの距離。基準タイムで指定する。
rtReserved
未使用。
rtDuration
持続時間。トラックがクロック タイム形式である場合は基準タイム。それ以外の場合はミュージック タイム。
mtLogicalTime
このウェーブが所属する音楽境界。トラックがクロック タイム形式である場合は無視する。
dwLoopStart
ループ ウェーブの開始ポイント。
dwLoopEnd
ループ ウェーブの終了ポイント。
dwFlags
フラグ。0 または次のいずれかの値を指定できる。
DMUS_WAVEF_NOINVALIDATE
このウェーブは無効化しない。
DMUS_WAVEF_STREAMING
ウェーブはストリームしている。

動作環境

ヘッダー : dmusicf.h で宣言。

注意

論理的なタイムと実際のタイム


DMUS_IO_WAVE_PART_HEADER

ウェーブ トラック リストのデータを保持する。

typedef struct _DMUS_IO_WAVE_PART_HEADER {
    long   lVolume;
    DWORD  dwVariations;
    DWORD  dwPChannel;
    DWORD  dwLockToPart;
    DWORD  dwFlags;
    DWORD  dwIndex;
} DMUS_IO_WAVE_PART_HEADER;

メンバ

lVolume
このウェーブ パート内のすべてのウェーブに適用するゲイン。1/100 dB (デシベル) 単位で指定する。負の値でなければならない。
dwVariations
アクティブなバリエーション。アクティブなバリエーションごとに 1 ビットが設定される。
dwPChannel
パートのパフォーマンス チャンネル。
dwLockToPart
ロック識別子のバリエーション。このメンバ内の値と同じ値を持つパートは、常に同じバリエーションを演奏する。値 0 は、パートがバリエーションをその他のパートとは別に演奏することを意味する。
dwFlags
バリエーションの選択方法を管理するフラグ。下位 4 ビットに指定する。「DMUS_VARIATIONT_TYPES」を参照すること。
dwIndex
同一のパフォーマンス チャンネル上で複数のパートを区別するためのインデックス。


DMUS_IO_WAVE_TRACK_HEADER

ウェーブ トラック リストのウェーブ トラックのデータを保持する。

typedef struct _DMUS_IO_WAVE_TRACK_HEADER {
    long   lVolume;
    DWORD  dwFlags;
} DMUS_IO_WAVE_TRACK_HEADER;

メンバ

lVolume
すべてのウェーブに適用するゲイン。1/100 dB (デシベル) 単位で指定する。
dwFlags
フラグ。0 または次の 1 つ以上の値を指定できる。
DMUS_WAVETRACKF_SYNC_VAR
トラックは、パターン トラックからバリエーションを取得する。詳細については、「GUID_Variations」を参照すること。
DMUS_WAVETRACKF_PERSIST_CONTROL
バリエーション制御情報は、ある再生インスタンスから次のインスタンスに持続する。

動作環境

ヘッダー : dmusicf.h で宣言。


DSOUND_IO_3D

DirectSound バッファ構成形式の DirectSound バッファの 3D パラメータを保持する。

typedef struct _DSOUND_IO_3D {
    GUID guid3DAlgorithm;
    DS3DBUFFER ds3d;
} DSOUND_IO_3D;

メンバ

guid3DAlgorithm
使用する 3D アルゴリズムの一意の識別子。「DSBUFFERDESC」を参照すること。
ds3d
パラメータを保持する DS3DBUFFER 構造体。この情報は、バッファ記述に DSBCAPS_CTRL3D が設定されている場合にのみ有効である。

動作環境

ヘッダー : dmusicf.h で宣言。


DSOUND_IO_DSBUFFERDESC

DirectSound バッファを表す。DirectSound バッファ構成形式で使用される。

typedef struct _DSOUND_IO_DSBUFFERDESC {
    DWORD dwFlags;
    WORD nChannels;
    LONG lVolume;
    LONG lPan;
    DWORD dwReserved;
} DSOUND_IO_DSBUFFERDESC;

メンバ

dwFlags
バッファ作成フラグ。「DSBUFFERDESC」を参照すること。
nChannels
チャンネルの数。フォーマットのその他のパラメータは、バッファを所有するシンクによって決定される。
lVolume
初期ボリューム。dwFlags で DSBCAPS_CTRLVOLUME が指定されている場合のみ使用される。
lPan
初期のパン。dwFlags で DSBCAPS_CTRLPAN が指定されている場合のみ使用される。
dwReserved
予約済み。0 でなければならない。

動作環境

ヘッダー : dmusicf.h で宣言。


DSOUND_IO_DSBUSID

バス識別子を保持する。DirectSound バッファ構成形式で使用される。

typedef struct _DSOUND_IO_DSBUSID {
    DWORD busid[1];
} DSOUND_IO_DSBUSID;

メンバ

busid
バス識別子を保持する DWORD 値の配列。配列のサイズは、チャンクのサイズから決定することができる。

動作環境

ヘッダー : dmusicf.h で宣言。


DSOUND_IO_DXDMO_DATA

DMO のデータを保持する。

typedef struct _DSOUND_IO_DXDMO_DATA {
    DWORD data[1];
} DSOUND_IO_DXDMO_DATA;

メンバ

data
データを保持する DWORD 値の配列。配列のサイズは、チャンクのサイズから決定することができる。

動作環境

ヘッダー : dmusicf.h で宣言。


DSOUND_IO_DXDMO_HEADER

エフェクト形式の DMO チャンクのヘッダー情報を保持する。

typedef struct _DSOUND_IO_DXDMO_HEADER {
    DWORD dwEffectFlags;
    GUID guidDSFXClass;
    GUID guidReserved;
    GUID guidSendBuffer;
    DWORD dwReserved;
} DSOUND_IO_DXDMO_HEADER;

メンバ

dwEffectFlags
エフェクト作成フラグ。「DSEFFECTDESC」を参照すること。
guidDSFXClass
エフェクトのクラス識別子。
guidReserved
予約済み。GUID_NULL でなければならない。
guidSendBuffer
これがセンド エフェクトの場合は、送信するバッファの一意の識別子。
dwReserved
予約済み。0 でなければならない。

動作環境

ヘッダー : dmusicf.h で宣言。


標準トラック パラメータ

ここでは、以下のメソッドを使って設定または取得できる標準トラック パラメータについて説明する。

  • IDirectMusicPerformance8::GetParam
  • IDirectMusicPerformance8::GetParamEx
  • IDirectMusicPerformance8::SetParam
  • IDirectMusicSegment8::GetParam
  • IDirectMusicSegment8::SetParam
  • IDirectMusicTrack8::GetParam
  • IDirectMusicTrack8::GetParamEx
  • IDirectMusicTrack8::SetParam
  • IDirectMusicTrack8::SetParamEx

ここではパラメータの GUID ごとにパラメータ タイプのリストを示す。メソッド呼び出しの rGuidType パラメータには、この GUID を指定する。

各パラメータ タイプについて、以下の情報が提供される。

要素 | 説明
トラック タイプ | パラメータを適用するトラック。「標準トラックの種類」を参照すること。パラメータは常に特定のトラックに関連付けられるが、アプリケーションが通常、セグメントまたはパフォーマンスでメソッドを呼び出し、DirectMusic が適切なトラックを検索する。「トラックの識別」を参照すること。
データ タイプ | パラメータを設定または取得するメソッド呼び出しの、pParam パラメータが指すデータ タイプ。
mtTime | パラメータを設定または取得するメソッド呼び出しにおける mtTime パラメータの意味 (ある場合)。

パラメータ タイプは以下のとおりである。

  • GUID_BandParam
  • GUID_ChordParam
  • GUID_Clear_All_Bands
  • GUID_Clear_All_MelodyFragments
  • GUID_CommandParam
  • GUID_CommandParam2
  • GUID_CommandParamNext
  • GUID_ConnectToDLSCollection
  • GUID_Disable_Auto_Download
  • GUID_DisableTempo
  • GUID_DisableTimeSig
  • GUID_Download
  • GUID_DownloadToAudioPath
  • GUID_Enable_Auto_Download
  • GUID_EnableTempo
  • GUID_EnableTimeSig
  • GUID_IDirectMusicBand
  • GUID_IDirectMusicChordMap
  • GUID_IDirectMusicStyle
  • GUID_MelodyFragment
  • GUID_MuteParam
  • GUID_Play_Marker
  • GUID_RhythmParam
  • GUID_SeedVariations
  • GUID_StandardMIDIFile
  • GUID_TempoParam
  • GUID_TimeSignature
  • GUID_Unload
  • GUID_UnloadFromAudioPath
  • GUID_Valid_Start_Time
  • GUID_Variations


GUID_BandParam

バンドを設定または取得する。

トラック タイプ | バンド
データ タイプ (*pParam) | DMUS_BAND_PARAM
mtTime | どの時点でバンドを設定するかを示す論理上のタイム、またはどの時点のバンドを取得するかを示すタイム。

注意

表の説明については、「標準トラック パラメータ」を参照すること。

動作環境

ヘッダー : dmusici.h で宣言。


GUID_ChordParam

コード変更を設定または取得する。

トラック タイプ | コード
データ タイプ (*pParam) | DMUS_CHORD_PARAM
mtTime | どの時点でトラックにコードを追加するかを示すタイム。または、トラックからコードを取得するタイム、またはその直後のタイム。トラック時間で指定する。

注意

表の説明については、「標準トラック パラメータ」を参照すること。

動作環境

ヘッダー : dmusici.h で宣言。


GUID_Clear_All_Bands

トラックからすべてのバンドを消去する。このパラメータは設定できるが、取得できない。

トラック タイプ | バンド
データ タイプ (*pParam) | なし
mtTime | 未使用

注意

表の説明については、「標準トラック パラメータ」を参照すること。

動作環境

ヘッダー : dmusici.h で宣言。


GUID_Clear_All_MelodyFragments

DirectX 8.0 では実装されない。

トラックからすべてのメロディ断片を消去する。このパラメータは設定できるが、取得できない。

トラック タイプ | メロディ断片
データ タイプ (*pParam) | なし
mtTime | 未使用

注意

表の説明については、「標準トラック パラメータ」を参照すること。

動作環境

ヘッダー : dmusici.h で宣言。


GUID_CommandParam

グルーブまたは装飾コマンドを設定または取得する。

トラック タイプ | コマンド
データ タイプ (*pParam) | DMUS_COMMAND_PARAM_2
mtTime | トラックにコマンドを追加するタイム。または、トラックからコマンドを取得するタイムあるいはその直後のタイム。トラック時間で指定する。

注意

表の説明については、「標準トラック パラメータ」を参照すること。

動作環境

ヘッダー : dmusici.h で宣言。


GUID_CommandParam2

グルーブまたは装飾コマンドを設定または取得する。

トラック タイプ | コマンド
データ タイプ (*pParam) | DMUS_COMMAND_PARAM_2。この構造体の mtTime メンバは、コマンドの実際のタイムを指定する。
mtTime | トラックにコマンドを追加するタイム。または、トラックからコマンドを取得するタイムあるいはその直後のタイム。トラック時間で指定する。

注意

表の説明については、「標準トラック パラメータ」を参照すること。

動作環境

ヘッダー : dmusici.h で宣言。


GUID_CommandParamNext

コマンド トラック内のその他すべてのコマンドの先頭となる、グルーブ コマンドや装飾コマンドを設定または取得する。

トラック タイプ | コマンド
データ タイプ (*pParam) | DMUS_COMMAND_PARAM_2
mtTime | 未使用

注意

表の説明については、「標準トラック パラメータ」を参照すること。

動作環境

ヘッダー : dmusici.h で宣言。


GUID_ConnectToDLSCollection

トラック内のすべてのバンドを DLS コレクションに接続する。このパラメータは設定できるが、取得できない。

トラック タイプ | バンド
データ タイプ (*pParam) | IDirectMusicCollection8 ポインタ
mtTime | 未使用

注意

表の説明については、「標準トラック パラメータ」を参照すること。

動作環境

ヘッダー : dmusici.h で宣言。

参照

カスタム音色による MIDI ファイルの演奏


GUID_Disable_Auto_Download

音色とウェーブの自動ダウンロードを無効にする。このパラメータは設定できるが、取得できない。

トラック タイプ | バンド、ウェーブ
データ タイプ (*pParam) | なし
mtTime | 未使用

注意

表の説明については、「標準トラック パラメータ」を参照すること。

動作環境

ヘッダー : dmusici.h で宣言。

参照

バンドの使い方、GUID_Enable_Auto_Download


GUID_DisableTempo

テンポ メッセージを無効にする。このパラメータは設定できるが、取得できない。

トラック タイプ | テンポ
データ タイプ (*pParam) | なし
mtTime | 未使用

注意

表の説明については、「標準トラック パラメータ」を参照すること。

動作環境

ヘッダー : dmusici.h で宣言。

参照

トラック パラメータの無効化と有効化、GUID_EnableTempo


GUID_DisableTimeSig

拍子記号メッセージを無効にする。このパラメータは設定できるが、取得できない。

トラック タイプ | パターン、拍子記号、スタイル、モチーフ
データ タイプ (*pParam) | なし
mtTime | 未使用

注意

表の説明については、「標準トラック パラメータ」を参照すること。

動作環境

ヘッダー : dmusici.h で宣言。

参照

トラック パラメータの無効化と有効化、GUID_EnableTimeSig


GUID_Download

音色データまたはウェーブ データをダウンロードする。このパラメータは設定できるが、取得できない。

トラック タイプ | バンド、ウェーブ
データ タイプ (*pParam) | IDirectMusicPerformance8 ポインタ
mtTime | 未使用

注意

表の説明については、「標準トラック パラメータ」を参照すること。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegment8::Download


GUID_DownloadToAudioPath

音色データまたはウェーブ データをダウンロードする。このパラメータは設定できるが、取得できない。

トラック タイプ | バンド、ウェーブ
データ タイプ (*pParam) | IDirectMusicAudioPath8 ポインタ
mtTime | 未使用

注意

表の説明については、「標準トラック パラメータ」を参照すること。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicSegment8::Download


GUID_Enable_Auto_Download

音色とウェーブの自動ダウンロードを有効にする。このパラメータは設定できるが、取得できない。

トラック タイプ | バンド、ウェーブ
データ タイプ (*pParam) | なし
mtTime | 未使用

注意

表の説明については、「標準トラック パラメータ」を参照すること。

動作環境

ヘッダー : dmusici.h で宣言。

参照

バンドの使い方、GUID_Disable_Auto_Download


GUID_EnableTempo

テンポ メッセージを有効にする。このパラメータは設定できるが、取得できない。

トラック タイプ | テンポ
データ タイプ (*pParam) | なし
mtTime | 未使用

注意

表の説明については、「標準トラック パラメータ」を参照すること。

動作環境

ヘッダー : dmusici.h で宣言。

参照

トラック パラメータの無効化と有効化、GUID_DisableTempo


GUID_EnableTimeSig

拍子記号メッセージを有効にする。このパラメータは設定できるが、取得できない。

トラック タイプ | パターン、拍子記号、スタイル、モチーフ
データ タイプ (*pParam) | なし
mtTime | 未使用

注意

表の説明については、「標準トラック パラメータ」を参照すること。

動作環境

ヘッダー : dmusici.h で宣言。

参照

トラック パラメータの無効化と有効化、GUID_DisableTimeSig


GUID_IDirectMusicBand

バンドを設定する。このパラメータは設定できるが、取得できない。

トラック タイプ | バンド
データ タイプ (*pParam) | IDirectMusicBand8
mtTime | どの時点でトラックにバンドを追加するかを示すタイム。トラック時間で指定する。

注意

表の説明については、「標準トラック パラメータ」を参照すること。

このパラメータは、物理タイムを指定できる GUID_BandParam に引き継がれる。

動作環境

ヘッダー : dmusici.h で宣言。


GUID_IDirectMusicChordMap

コード マップを設定または取得する。

トラック タイプ | コードマップ
データ タイプ (*pParam) | IDirectMusicChordMap8 ポインタ。またはこのポインタを受け取る変数のアドレス。
mtTime | どの時点でトラックにコード マップを追加するかを示すタイム。または、トラックからコード マップを取得するタイム、またはその直後のタイム。トラック時間で指定する。

注意

表の説明については、「標準トラック パラメータ」を参照すること。

動作環境

ヘッダー : dmusici.h で宣言。


GUID_IDirectMusicStyle

スタイルを設定または取得する。

トラック タイプ | スタイル
データ タイプ (*pParam) | IDirectMusicStyle8 ポインタ。またはこのポインタを受け取る変数のアドレス。
mtTime | どの時点でトラックにスタイルを追加するかを示すタイム。または、トラックからスタイルを取得するタイム、またはその直後のタイム。トラック時間で指定する。

注意

表の説明については、「標準トラック パラメータ」を参照すること。

動作環境

ヘッダー : dmusici.h で宣言。


GUID_MelodyFragment

DirectX 8.0 では実装されない。

メロディ断片を設定または取得する。

トラック タイプ | メロディ断片
データ タイプ (*pParam) | DMUS_MELODY_FRAGMENT
mtTime | どの時点でトラックに断片を追加するかを示すタイム。または、トラックから断片を取得するタイム、またはその直後のタイム。トラック時間で指定する。

注意

表の説明については、「標準トラック パラメータ」を参照すること。

動作環境

ヘッダー : dmusici.h で宣言。


GUID_MuteParam

チャンネル (マッピング情報) を設定または取得する。

トラック タイプ | ミュート
データ タイプ (*pParam) | DMUS_MUTE_PARAM。この構造体を get メソッドに渡す前に、dwPChannel メンバを初期化しなければならない。
mtTime | どの時点でトラックにミュート イベントを追加するかを示すタイム。または、トラックからミュート イベントを取得するタイム、またはその直後のタイム。トラック時間で指定する。

注意

表の説明については、「標準トラック パラメータ」を参照すること。

ミュート トラックの演奏中にこのパラメータを設定しても、チャンネルのマッピングやミュートを動的に変更することはできない。ミュート トラックのパラメータは、その他のトラックから内部の GetParam を呼び出すことで取得される。アプリケーションは、このような呼び出しのタイミングに対する制御を持たない。チャンネルのマッピングやミュートの変更は、制御セグメントとして演奏されるセグメントのミュート トラックに記述するか、ツールを使って実行時に行う必要がある。

動作環境

ヘッダー : dmusici.h で宣言。


GUID_Play_Marker

現在演奏中のセグメントから、新規セグメントを開始できる次のポイントを取得する。このパラメータは取得できるが、設定できない。

トラック タイプ | マーカー
データ タイプ (*pParam) | DMUS_PLAY_MARKER_PARAM
mtTime | どの時点でマーカーのシークを開始するかを示すトラック時間。

注意

表の説明については、「標準トラック パラメータ」を参照すること。

動作環境

ヘッダー : dmusici.h で宣言。

参照

セグメントのタイミング


GUID_RhythmParam

トラックの小節に格納されている、コードのシーケンスのリズム パターンを取得する。このパラメータは取得できるが、設定できない。

トラック タイプ | コード
データ タイプ (*pParam) | DMUS_RHYTHM_PARAM。この構造体を get メソッドに渡す前に、TimeSig メンバを初期化しなければならない。
mtTime | トラックから取得するリズム パターンが含まれている小節の開始、または開始直後のタイム。トラック時間で指定する。

注意

表の説明については、「標準トラック パラメータ」を参照すること。

動作環境

ヘッダー : dmusici.h で宣言。


GUID_SeedVariations

バリエーション選択に使用するランダム値を生成する際のシードとなる。ゼロ以外の値がシートとして使用される。値がゼロの場合はデフォルトの状態に戻り、システム クロックからシードを取得する。このパラメータは設定できるが、取得できない。

トラック タイプ | パターン、スタイル、モチーフ
データ タイプ (*pParam) | Long 型
mtTime | 未使用

注意

表の説明については、「標準トラック パラメータ」を参照すること。

このパラメータにゼロ以外の値を設定すると、毎回同じ順序でランダムな数字が生成されるので、テストの際に役に立つ。パラメータは、トラックを演奏する前に一度だけ設定する。スタイルとコマンド トラックは、セグメントが演奏されるたびに、セグメントの同じ場所で同じパターンが選択されるように設計しなければならない。各ループは、前回とは異なるバリエーションで演奏されるが、セグメント全体が最初から演奏されるたびに、各ループはセグメントが最初に演奏されたときと同じように聞こえる。

動作環境

ヘッダー : dmusici.h で宣言。


GUID_StandardMIDIFile

スタンダード MIDI ファイル (DirectMusic 用に特別にオーサリングされていない MIDI ファイル) が、正しく演奏されるように保証する。このパラメータは設定できるが、取得できない。

トラック タイプ | バンド
データ タイプ (*pParam) | なし
mtTime | 未使用

注意

表の説明については、「標準トラック パラメータ」を参照すること。

このパラメータは、音色がダウンロードされる前に、MIDI ファイルに基づくセグメントで設定されなければならない。

動作環境

ヘッダー : dmusici.h で宣言。


GUID_TempoParam

テンポを設定または取得する。

トラック タイプ | テンポ
データ タイプ (*pParam) | DMUS_TEMPO_PARAM。パラメータ設定時に、構造体の mtTime メンバは無視される。パラメータ取得時に、mtTime メンバは、要求されたタイムからのテンポの変更のオフセットを受け取る。常に 0 以下である。
mtTime | どの時点でテンポを設定するかを示すタイム。または、テンポの変更を取得するタイム、またはその直後のタイム。トラック時間で指定する。

注意

表の説明については、「標準トラック パラメータ」を参照すること。

動作環境

ヘッダー : dmusici.h で宣言。


GUID_TimeSignature

拍子記号を取得する。このパラメータは取得できるが、設定できない。

トラック タイプ | 拍子記号およびスタイル
データ タイプ (*pParam) | DMUS_TIMESIGNATURE。mtTime メンバは、要求したタイムからの拍子記号の変更のオフセットを受け取る。この値は、常に 0 以下である。
mtTime | どの時点で拍子記号を設定するかを示すタイム。または、拍子記号の変更を取得するタイム、またはその直後のタイム。トラック時間で指定する。

注意

表の説明については、「標準トラック パラメータ」を参照すること。

動作環境

ヘッダー : dmusici.h で宣言。


GUID_Unload

音色データまたはウェーブ データをアンロードする。このパラメータは設定できるが、取得できない。

トラック タイプ | バンド、ウェーブ
データ タイプ (*pParam) | IDirectMusicPerformance8 ポインタ
mtTime | 未使用

注意

表の説明については、「標準トラック パラメータ」を参照すること。

参照

IDirectMusicSegment8::Unload

動作環境

ヘッダー : dmusici.h で宣言。


GUID_UnloadFromAudioPath

音色データまたはウェーブ データをアンロードする。このパラメータは設定できるが、取得できない。

トラック タイプ | バンド、ウェーブ
データ タイプ (*pParam) | IDirectMusicAudioPath8 ポインタ
mtTime | 未使用

注意

表の説明については、「標準トラック パラメータ」を参照すること。

参照

IDirectMusicSegment8::Unload

動作環境

ヘッダー : dmusici.h で宣言。


GUID_Valid_Start_Time

セグメント内で、開始できる次の有効なポイントを取得する。このパラメータは取得できるが、設定できない。

トラック タイプ | マーカー、モチーフ、パターン
データ タイプ (*pParam) | DMUS_VALID_START_PARAM
mtTime | 未使用

注意

表の説明については、「標準トラック パラメータ」を参照すること。

参照

セグメントのタイミング

動作環境

ヘッダー : dmusici.h で宣言。


GUID_Variations

パフォーマンス チャンネル全体からエフェクトのバリエーションを取得する。このパラメータは取得できるが、設定できない。

トラック タイプ | パターン
データ タイプ (*pParam) | DMUS_VARIATIONS_PARAM
mtTime | 未使用

注意

表の説明については、「標準トラック パラメータ」を参照すること。

動作環境

ヘッダー : dmusici.h で宣言。


DirectMusic 列挙型

ここでは、次の列挙型に関するリファレンス情報を記述する。

  • DMUS_CHORDKEYF_FLAGS
  • DMUS_CLOCKTYPE
  • DMUS_COMMANDT_TYPES
  • DMUS_COMPOSEF_FLAGS
  • DMUS_CURVE_FLAGS
  • DMUS_NOTEF_FLAGS
  • DMUS_PATTERNT_TYPES
  • DMUS_PLAYMODE_FLAGS
  • DMUS_PMSGF_FLAGS
  • DMUS_PMSGT_TYPES
  • DMUS_SEGF_FLAGS
  • DMUS_SHAPET_TYPES
  • DMUS_STYLET_TYPES
  • DMUS_TIME_RESOLVE_FLAGS
  • DMUS_TRACKF_FLAGS
  • DMUS_VARIATIONT_TYPES


DMUS_CHORDKEYF_FLAGS

DMUS_CHORD_KEY 構造体の bFlags メンバで使用される。

typedef enum enumDMUS_CHORDKEYF_FLAGS {
    DMUS_CHORDKEYF_SILENT  = 1,
} DMUS_CHORDKEYF_FLAGS;

定数

DMUS_CHORDKEYF_SILENT
コードは無音である。

動作環境

ヘッダー : dmusici.h で宣言。


DMUS_CLOCKTYPE

DMUS_CLOCKINFO8 構造体の ctType メンバで使用される。

typedef enum {
    DMUS_CLOCK_SYSTEM = 0,
    DMUS_CLOCK_WAVE   = 1
} DMUS_CLOCKTYPE;

定数

DMUS_CLOCK_SYSTEM
クロックはシステム クロックである。
DMUS_CLOCK_WAVE
クロックはウェーブ再生デバイス上にある。

動作環境

ヘッダー : dmusicc.h で宣言。


DMUS_COMMANDT_TYPES

IDirectMusicComposer8::AutoTransition メソッドと IDirectMusicComposer8::ComposeTransition メソッドの wCommand パラメータ、および DMUS_COMMAND_PARAM 構造体の bCommand メンバで使用される。

typedef enum enumDMUS_COMMANDT_TYPES {
    DMUS_COMMANDT_GROOVE      = 0,
    DMUS_COMMANDT_FILL        = 1,
    DMUS_COMMANDT_INTRO       = 2,
    DMUS_COMMANDT_BREAK       = 3,
    DMUS_COMMANDT_END         = 4,
    DMUS_COMMANDT_ENDANDINTRO = 5
} DMUS_COMMANDT_TYPES;

定数

DMUS_COMMANDT_GROOVE
コマンドはグルーブ コマンドである。
DMUS_COMMANDT_FILL
コマンドはフィルである。
DMUS_COMMANDT_INTRO
コマンドはイントロである。
DMUS_COMMANDT_BREAK
コマンドは変換点である。
DMUS_COMMANDT_END
コマンドはエンディングである。
DMUS_COMMANDT_ENDANDINTRO
コマンドはエンディングとイントロである。

動作環境

ヘッダー : dmusici.h で宣言。


DMUS_COMPOSEF_FLAGS

IDirectMusicComposer8::ComposeTransition メソッドと IDirectMusicComposer8::AutoTransition メソッドの dwFlags パラメータで使用される。

typedef enum enumDMUS_COMPOSEF_FLAGS {
    DMUS_COMPOSEF_NONE                =       0,
    DMUS_COMPOSEF_ALIGN               =     0x1,
    DMUS_COMPOSEF_OVERLAP             =     0x2,
    DMUS_COMPOSEF_IMMEDIATE           =     0x4,
    DMUS_COMPOSEF_GRID                =     0x8,
    DMUS_COMPOSEF_BEAT                =    0x10,
    DMUS_COMPOSEF_MEASURE             =    0x20,
    DMUS_COMPOSEF_AFTERPREPARETIME    =    0x40,
    DMUS_COMPOSEF_VALID_START_BEAT    =    0x80,
    DMUS_COMPOSEF_VALID_START_GRID    =   0x100,
    DMUS_COMPOSEF_VALID_START_TICK    =   0x200,
    DMUS_COMPOSEF_SEGMENTEND          =   0x400,
    DMUS_COMPOSEF_MARKER              =   0x800,
    DMUS_COMPOSEF_MODULATE            =  0x1000,
    DMUS_COMPOSEF_LONG                =  0x2000,
    DMUS_COMPOSEF_ENTIRE_TRANSITION   =  0x4000,
    DMUS_COMPOSEF_1BAR_TRANSITION     =  0x8000,
    DMUS_COMPOSEF_ENTIRE_ADDITION     = 0x10000,
    DMUS_COMPOSEF_1BAR_ADDITION       = 0x20000,
    DMUS_COMPOSEF_VALID_START_MEASURE = 0x40000,
    DMUS_COMPOSEF_DEFAULT             = 0x80000,
    DMUS_COMPOSEF_NOINVALIDATE       = 0x100000,
    DMUS_COMPOSEF_USE_AUDIOPATH      = 0x200000
}  DMUS_COMPOSEF_FLAGS;

定数

DMUS_COMPOSEF_NONE
フラグなし。デフォルトでは、トランジションは小節境界から開始する。
DMUS_COMPOSEF_ALIGN
トランジションを、現在演奏されているセグメントの拍子記号に揃える。
DMUS_COMPOSEF_OVERLAP
トランジションを pToSeg に重ねる (オーバーラップ)。このフラグは現在実装されていない。
DMUS_COMPOSEF_IMMEDIATE
AutoTransition のみ。ミュージック タイムまたは基準タイムの境界からトランジションを開始する。
DMUS_COMPOSEF_GRID
AutoTransition のみ。グリッド境界からトランジションを開始する。
DMUS_COMPOSEF_BEAT
AutoTransition のみ。拍の境界からトランジションを開始する。
DMUS_COMPOSEF_MEASURE
AutoTransition のみ。小節境界からトランジションを開始する。
DMUS_COMPOSEF_AFTERPREPARETIME
AutoTransition のみ。トランジションを挿入するときは、DMUS_SEGF_AFTERPREPARETIME フラグを使用する。
DMUS_COMPOSEF_VALID_START_BEAT
任意の拍で切り替えを発生できる。DMUS_COMPOSEF_ALIGN と組み合わせて使用される。
DMUS_COMPOSEF_VALID_START_GRID
任意のグリッドで切り替えを発生できる。DMUS_COMPOSEF_ALIGN と組み合わせて使用される。
DMUS_COMPOSEF_VALID_START_TICK
任意のタイムで切り替えを発生できる。DMUS_COMPOSEF_ALIGN と組み合わせて使用される。
DMUS_COMPOSEF_SEGMENTEND
現在のセグメントの最後にトランジションを演奏する。
DMUS_COMPOSEF_MARKER
現在のセグメントの次のマーカーでトランジションを演奏する。
DMUS_COMPOSEF_MODULATE
pToSeg のコードを使用して、pFromSeg から pToSeg へとスムーズに変化するトランジションをアレンジする。
DMUS_COMPOSEF_LONG
長いトランジションをアレンジする。このフラグが設定されていない場合、ComposeTransition または AutoTransition の wCommand パラメータでエンディングを指定し、スタイルに 1 小節より長いエンディングが含まれていない限り、トランジションの長さは最大でも 1 小節である。このフラグが設定されている場合、トランジションの長さは 1 小節増える。
DMUS_COMPOSEF_ENTIRE_TRANSITION
トランジション パターン全体を含める。
DMUS_COMPOSEF_1BAR_TRANSITION
トランジション パターンの 1 小節を含める。
DMUS_COMPOSEF_ENTIRE_ADDITION
追加のトランジション パターンを完全な形で含める。DMUS_COMPOSEF_LONG と組み合わせて使用される。
DMUS_COMPOSEF_1BAR_ADDITION
追加のトランジション パターンの 1 小節を含める。DMUS_COMPOSEF_LONG が指定されている場合は、これがデフォルトの動作である。
DMUS_COMPOSEF_VALID_START_MEASURE
任意の小節で切り替えを発生できる。DMUS_COMPOSEF_ALIGN と組み合わせて使用される。
DMUS_COMPOSEF_DEFAULT
セグメントのデフォルトの境界を使用する。
DMUS_COMPOSEF_NOINVALIDATE
演奏中のセグメントを無効にしない。
DMUS_COMPOSEF_USE_AUDIOPATH
セグメントに埋め込まれたオーディオパスを使用する。

動作環境

ヘッダー : dmusici.h で宣言。

参照

DMUS_SEGF_FLAGS


DMUS_CURVE_FLAGS

DMUS_CURVE_PMSG 構造体の bFlags メンバで使用される。

typedef enum enumDMUS_CURVE_FLAGS {
    DMUS_CURVE_RESET              = 1,
    DMUS_CURVE_START_FROM_CURRENT = 2,
} DMUS_CURVE_FLAGS;

定数

DMUS_CURVE_RESET
デフォルトのタイムに達したとき、またはトランジションが原因で無効化が発生したときに DMUS_CURVE_PMSG.nResetValue を設定しなければならない場合は、この値を DMUS_CURVE_RESET に設定する。フラグが設定されていない場合、カーブは新しい値に永続的にとどまる。
DMUS_CURVE_START_FROM_CURRENT
DMUS_CURVE_PMSG.nStartValue を無視し、現在の値でカーブを開始する。これは、ボリューム、エクスプレッション、およびピッチ ベンドのみに作用する。

動作環境

ヘッダー : dmusici.h で宣言。


DMUS_NOTEF_FLAGS

DMUS_NOTE_PMSG 構造体の bFlags メンバで使用される。

typedef enum enumDMUS_NOTEF_FLAGS {
    DMUS_NOTEF_NOTEON =               1,
    DMUS_NOTEF_NOINVALIDATE =         2,
    DMUS_NOTEF_NOINVALIDATE_INSCALE = 4,
    DMUS_NOTEF_NOINVALIDATE_INCHORD = 8,
    DMUS_NOTEF_REGENERATE =        0x10,
} DMUS_NOTEF_FLAGS;

定数

DMUS_NOTEF_NOTEON
MIDI ノートオン。IDirectMusicPerformance8::SendPMsg メソッドで最初に DMUS_NOTE_PMSG を指定する場合は、このフラグを設定すべきである。このフラグが設定されていない場合、メッセージはノートオフである。
DMUS_NOTEF_NOINVALIDATE
このノートを無効にしない。
DMUS_NOTEF_NOINVALIDATE_INSCALE
このノートがまだスケール内にある場合は、無効にしない。
DMUS_NOTEF_NOINVALIDATE_INCHORD
このノートがまだコード内にある場合は、無効にしない。
DMUS_NOTEF_REGENERATE
コード チェンジが発生したらノートを再生成する。ノートのミュージック値、サブコード レベル、および演奏モードの各フラグは、新しいコードとスケールに従って新しいノートを構築するために使用される。元のノートにタイミング オフセットがあった場合、これが新しいノートの開始タイムに適用される。

注意

NOINVALIDATE フラグを設定することで、ノートはメッセージが無効化されるとしても、継続時間の最後まで確実に演奏される。

動作環境

ヘッダー : dmusici.h で宣言。


DMUS_PATTERNT_TYPES

さまざまなコマンド構造体内で使用され、シーケンシャル コマンド内でのパターンの選択方法を制御する。

typedef enum enumDMUS_PATTERNT_TYPES {
    DMUS_PATTERNT_RANDOM           = 0,
    DMUS_PATTERNT_REPEAT           = 1,
    DMUS_PATTERNT_SEQUENTIAL       = 2,
    DMUS_PATTERNT_RANDOM_START     = 3,
    DMUS_PATTERNT_NO_REPEAT        = 4,
    DMUS_PATTERNT_RANDOM_ROW       = 5
} DMUS_PATTERNT_TYPES;

定数

DMUS_PATTERNT_RANDOM
一致するパターンをランダムに選択する。これは、DirectX 8.0 以前のバージョンの動作である。
DMUS_PATTERNT_REPEAT
一致する最後のパターンを繰り返す。
DMUS_PATTERNT_SEQUENTIAL
一致するパターンを、ロードされた順に最初から演奏する。
DMUS_PATTERNT_RANDOM_START
一致するパターンを、ロードされた順に、シーケンス内のランダムなポイントから演奏する。
DMUS_PATTERNT_NO_REPEAT
ランダムに演奏する。ただし、パターンは一度ずつしか演奏しない。
DMUS_PATTERNT_RANDOM_ROW
ランダムに演奏する。すべてを演奏するまではパターンを繰り返さない。

動作環境

ヘッダー : dmusicf.h で宣言。

参照

DMUS_COMMAND_PARAM、DMUS_COMMAND_PARAM_2、DMUS_IO_COMMAND、DMUS_VARIATIONT_TYPES


DMUS_PLAYMODE_FLAGS

基本的な演奏モードのさまざまな構造体で使用される。演奏モードは、ミュージック値を MIDI ノートにどのように転置するかを決定する。

typedef enum enumDMUS_PLAYMODE_FLAGS {
    DMUS_PLAYMODE_KEY_ROOT          = 1,
    DMUS_PLAYMODE_CHORD_ROOT        = 2,
    DMUS_PLAYMODE_SCALE_INTERVALS   = 4,
    DMUS_PLAYMODE_CHORD_INTERVALS   = 8,
    DMUS_PLAYMODE_NONE              = 16,
} DMUS_PLAYMODE_FLAGS;

定数

DMUS_PLAYMODE_KEY_ROOT
キーのルート音上に転置する。
DMUS_PLAYMODE_CHORD_ROOT
コードのルート音上に転置する。
DMUS_PLAYMODE_SCALE_INTERVALS
スケール パターンのスケールの音程を使用する。
DMUS_PLAYMODE_CHORD_INTERVALS
コード パターンのコードの音程を使用する。
DMUS_PLAYMODE_NONE
モードなし。親パートのモードを使用する必要があることを示す。

注意

次の定義済みの値は、演奏モード フラグの組み合わせを表している。

DMUS_PLAYMODE_ALWAYSPLAY
DMUS_PLAYMODE_SCALE_INTERVALS、DMUS_PLAYMODE_CHORD_INTERVALS、および DMUS_PLAYMODE_CHORD_ROOT の組み合わせ。コードの最高音より高いノートを演奏することが望ましい場合、このモードは、スケールの音程を使用することによってノートの位置を検索する。つまり、このモードは通常の演奏モードと旋律系の演奏モードの組み合わせであり、通常モードで失敗すると 2 度目の試行が旋律系モードで強制的に行われる。
DMUS_PLAYMODE_FIXED
ミュージック値を MIDI 値として解釈する。これは 0 として定義され、その他のフラグがないことを意味する。このフラグは、ドラム、サウンド エフェクト、およびコードまたはスケールによって転置してはならない、シーケンス化されたノートについて使用される。
DMUS_PLAYMODE_FIXEDTOCHORD
DMUS_PLAYMODE_CHORD_ROOT と同じ。ミュージック値は固定の MIDI 値であるが、コードのルート音上に転置される。
DMUS_PLAYMODE_FIXEDTOKEY
DMUS_PLAYMODE_KEY_ROOT と同じ。ミュージック値は固定の MIDI 値であるが、キーのルート音上に転置される。
DMUS_PLAYMODE_MELODIC
DMUS_PLAYMODE_CHORD_ROOT と DMUS_PLAYMODE_SCALE_INTERVALS の組み合わせ。コードのルート音は使用されるが、ノートはスケール内の音程だけを追う。キーのルート音とコードの音程は無視される。これは、コードのルート音を基準にして演奏される旋律系のラインにとって便利である。
DMUS_PLAYMODE_NORMALCHORD
DMUS_PLAYMODE_CHORD_ROOT と DMUS_PLAYMODE_CHORD_INTERVALS の組み合わせ。これは一般的な再生モードである。ノートはコード内の音程を追う。コードはコードのルート音に基づいている。ミュージック値にスケール要素がある場合、ほかの音程はスケールから取り出され、追加される。コードがミュージック値のコード要素と一致する音程を持っていない場合、ノートは無音である。
DMUS_PLAYMODE_PEDALPOINT
DMUS_PLAYMODE_KEY_ROOT と DMUS_PLAYMODE_SCALE_INTERVALS の組み合わせ。キーのルート音は使用されるが、ノートはスケール内の音程だけを追う。コードのルート音と音程は無視される。これは、キーのルート音を基準にして演奏される旋律系のラインにとって便利である。
DMUS_PLAYMODE_PEDALPOINTALWAYS
DMUS_PLAYMODE_PEDALPOINT と DMUS_PLAYMODE_PEDALPOINTCHORD の組み合わせ。可能であればコードの音程を使用する。それ以外の場合は、スケールの音程を使用する。
DMUS_PLAYMODE_PEDALPOINTCHORD
DMUS_PLAYMODE_MELODIC と DMUS_PLAYMODE_NORMALCHORD の組み合わせ。キーのルート音は使用されるが、ノートはコード内の音程だけを追う。コードのルート音とスケールの音程はまったく無視される。これは、キーのルート音を基準にして演奏されるコード系のラインにとって便利である。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::MIDIToMusic、IDirectMusicPerformance8::MusicToMIDI、DMUS_NOTE_PMSG、DMUS_IO_STYLENOTE、DMUS_IO_STYLEPART、ミュージック値と MIDI ノート


DMUS_PMSGF_FLAGS

DMUS_PMSG 構造体の dwFlags メンバで使用される。

typedef enum enumDMUS_PMSGF_FLAGS {
    DMUS_PMSGF_REFTIME        = 1,
    DMUS_PMSGF_MUSICTIME      = 2,
    DMUS_PMSGF_TOOL_IMMEDIATE = 4,
    DMUS_PMSGF_TOOL_QUEUE     = 8,
    DMUS_PMSGF_TOOL_ATTIME    = 0x10,
    DMUS_PMSGF_TOOL_FLUSH     = 0x20,
    DMUS_PMSGF_LOCKTOREFTIME  = 0x40,
    DMUS_PMSGF_DX8            = 0x80
} DMUS_PMSGF_FLAGS;

定数

DMUS_PMSGF_REFTIME
rtTime メンバは有効である。
DMUS_PMSGF_MUSICTIME
mtTime メンバは有効である。
DMUS_PMSGF_TOOL_IMMEDIATE
タイム スタンプにかかわりなく、メッセージを即座に処理すべきである。
DMUS_PMSGF_TOOL_QUEUE
ポートの遅延時間を考慮して、タイム スタンプの直前にメッセージを処理すべきである。
DMUS_PMSGF_TOOL_ATTIME
タイム スタンプの時点でメッセージを処理すべきである。
DMUS_PMSGF_TOOL_FLUSH
メッセージをフラッシュ (解放) すべきである。
DMUS_PMSGF_LOCKTOREFTIME
テンポが変更されても rtTime の値を上書きできない。
DMUS_PMSGF_DX8
メッセージは、DirectX 8.0 より前のバージョンに存在しない、有効なメンバを持っている。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::SendPMsg、IDirectMusicTool8::GetMsgDeliveryType


DMUS_PMSGT_TYPES

DMUS_PMSG 構造体の dwType メンバで使用され、メッセージのタイプを識別する。

typedef enum enumDMUS_PMSGT_TYPES {
    DMUS_PMSGT_MIDI             = 0,
    DMUS_PMSGT_NOTE             = 1,
    DMUS_PMSGT_SYSEX            = 2,
    DMUS_PMSGT_NOTIFICATION     = 3,
    DMUS_PMSGT_TEMPO            = 4,
    DMUS_PMSGT_CURVE            = 5,
    DMUS_PMSGT_TIMESIG          = 6,
    DMUS_PMSGT_PATCH            = 7,
    DMUS_PMSGT_TRANSPOSE        = 8,
    DMUS_PMSGT_CHANNEL_PRIORITY = 9,
    DMUS_PMSGT_STOP             = 10,
    DMUS_PMSGT_DIRTY            = 11,
    DMUS_PMSGT_WAVE             = 12,
    DMUS_PMSGT_LYRIC            = 13,
    DMUS_PMSGT_SCRIPTLYRIC      = 14,
    DMUS_PMSGT_USER             = 255
} DMUS_PMSGT_TYPES;

定数

DMUS_PMSGT_MIDI
MIDI チャンネル メッセージ。「DMUS_MIDI_PMSG」を参照すること。
DMUS_PMSGT_NOTE
MIDI のノート。「DMUS_NOTE_PMSG」を参照すること。
DMUS_PMSGT_SYSEX
MIDI システム エクスクルーシブ メッセージ。「DMUS_SYSEX_PMSG」を参照すること。
DMUS_PMSGT_NOTIFICATION
通知メッセージ。「DMUS_NOTIFICATION_PMSG」を参照すること。
DMUS_PMSGT_TEMPO
テンポ メッセージ。「DMUS_TEMPO_PMSG」を参照すること。
DMUS_PMSGT_CURVE
コントロール チェンジとピッチベンド カーブ。「DMUS_CURVE_PMSG」を参照すること。
DMUS_PMSGT_TIMESIG
拍子記号。「DMUS_TIMESIG_PMSG」を参照すること。
DMUS_PMSGT_PATCH
パッチの変更。「DMUS_PATCH_PMSG」を参照すること。
DMUS_PMSGT_TRANSPOSE
転調。「DMUS_TRANSPOSE_PMSG」を参照すること。
DMUS_PMSGT_CHANNEL_PRIORITY
チャンネル優先順位変更。「DMUS_CHANNEL_PRIORITY_PMSG」を参照すること。
DMUS_PMSGT_STOP
停止メッセージ。「DMUS_PMSG」を参照すること。
DMUS_PMSGT_DIRTY
制御セグメントが開始または終了した。「DMUS_PMSG」を参照すること。
DMUS_PMSGT_WAVE
ウェーブ演奏用の制御情報。「DMUS_WAVE_PMSG」を参照すること。
DMUS_PMSGT_LYRIC
歌詞メッセージ。「DMUS_LYRIC_PMSG」を参照すること。
DMUS_PMSGT_SCRIPTLYRIC
スクリプトから送信される歌詞メッセージ。「DMUS_LYRIC_PMSG」を参照すること。
DMUS_PMSGT_USER
ユーザー定義メッセージ。

動作環境

ヘッダー : dmusici.h で宣言。


DMUS_SEGF_FLAGS

IDirectMusicPerformance8 のさまざまなメソッドに渡され、セグメントに対するアクションのタイミングおよびその他の要素を制御する。

typedef enum enumDMUS_SEGF_FLAGS {
    DMUS_SEGF_REFTIME             = 1<<6,
    DMUS_SEGF_SECONDARY           = 1<<7,
    DMUS_SEGF_QUEUE               = 1<<8,
    DMUS_SEGF_CONTROL             = 1<<9,
    DMUS_SEGF_AFTERPREPARETIME    = 1<<10,
    DMUS_SEGF_GRID                = 1<<11,
    DMUS_SEGF_BEAT                = 1<<12,
    DMUS_SEGF_MEASURE             = 1<<13,
    DMUS_SEGF_DEFAULT             = 1<<14,
    DMUS_SEGF_NOINVALIDATE        = 1<<15,
    DMUS_SEGF_ALIGN               = 1<<16,
    DMUS_SEGF_VALID_START_BEAT    = 1<<17,
    DMUS_SEGF_VALID_START_GRID    = 1<<18,
    DMUS_SEGF_VALID_START_TICK    = 1<<19,
    DMUS_SEGF_AUTOTRANSITION      = 1<<20,
    DMUS_SEGF_AFTERQUEUETIME      = 1<<21,
    DMUS_SEGF_AFTERLATENCYTIME    = 1<<22,
    DMUS_SEGF_SEGMENTEND          = 1<<23,
    DMUS_SEGF_MARKER              = 1<<24,
    DMUS_SEGF_TIMESIG_ALWAYS      = 1<<25,
    DMUS_SEGF_USE_AUDIOPATH       = 1<<26,
    DMUS_SEGF_VALID_START_MEASURE = 1<<27
} DMUS_SEGF_FLAGS;

定数

DMUS_SEGF_REFTIME
タイム パラメータは基準タイムで表される。
DMUS_SEGF_SECONDARY
セカンダリ セグメント。
DMUS_SEGF_QUEUE
プライマリ セグメント キューの最後に置く。プライマリ セグメントに対してのみ有効である。
DMUS_SEGF_CONTROL
制御セグメントとして演奏する。セカンダリ セグメントに対してのみ有効である。「注意」を参照すること。
DMUS_SEGF_AFTERPREPARETIME
準備時間の後に演奏する。「IDirectMusicPerformance8::GetPrepareTime」を参照すること。
DMUS_SEGF_GRID
グリッド境界で演奏する。
DMUS_SEGF_BEAT
拍の境界で演奏する。
DMUS_SEGF_MEASURE
小節境界で演奏する。
DMUS_SEGF_DEFAULT
セグメントのデフォルトの境界を使用する。
DMUS_SEGF_NOINVALIDATE
プライマリ セグメントまたは制御セグメントについて、このフラグを IDirectMusicPerformance8::PlaySegment または IDirectMusicPerformance8::PlaySegmentEx で設定すると、新しいセグメントで無効化が発生しない。このフラグがないと無効化が発生し、演奏中のカーブやノートが途切れ、リセットされる。このフラグは DMUS_SEGF_AFTERPREPARETIME と組み合わせなければならない。そうすることによって、新しいセグメント内のノートは、古いセグメントが演奏するノートに重ねて演奏しない。
DMUS_SEGF_ALIGN
セグメントの開始を、小節や拍など、既に過ぎた境界に揃えることができる。これを実行するには、セグメント内で次の境界の前に、有効な開始ポイントがある必要がある。開始ポイントはセグメント内に定義できる。また、DMUS_SEGF_VALID_START_* フラグの 1 つを使用して、有効な開始ポイントの細分度を定義できる。DMUS_SEGF_VALID_START_* フラグは、セグメント内に有効な開始ポイントが定義されていない場合にのみ有効である。
DMUS_SEGF_VALID_START_BEAT
任意の拍で開始できる。DMUS_SEGF_ALIGN と組み合わせて使用される。
DMUS_SEGF_VALID_START_GRID
任意のグリッドで開始できる。DMUS_SEGF_ALIGN と組み合わせて使用される。
DMUS_SEGF_VALID_START_TICK
任意のタイムで開始できる。DMUS_SEGF_ALIGN と組み合わせて使用される。
DMUS_SEGF_AUTOTRANSITION
トランジション テンプレートを使用して、トランジション セグメントをアレンジおよび演奏する。
DMUS_SEGF_AFTERQUEUETIME
キュー時間の後に演奏する。これはプライマリ セグメントのデフォルトである。DMUS_SEGF_AFTERPREPARETIME も設定されている場合は無視される。
DMUS_SEGF_AFTERLATENCYTIME
遅延時間の後に演奏する。これはすべてのセグメントに当てはまるので、このフラグは現時点では何の効果もない。
DMUS_SEGF_SEGMENTEND
開始タイムで演奏中のプライマリ セグメントの最後で演奏する。現在演奏中のプライマリ セグメント後に既に挿入されているセグメントは、フラッシュ (解放) される。プライマリ セグメントが演奏されていない場合は、その他の解決フラグを使用する。
DMUS_SEGF_MARKER
プライマリ セグメント内の次のマーカーで演奏する。マーカーが存在しない場合は、その他の解決フラグを使用する。
DMUS_SEGF_TIMESIG_ALWAYS
開始タイムを現在の拍子記号に揃える。プライマリ セグメントがない場合も同様にする。
DMUS_SEGF_USE_AUDIOPATH
セグメントに埋め込まれたオーディオパスを使用する。セグメントが正しく演奏されるように、バンドの自動ダウンロードを有効にする必要がある。
DMUS_SEGF_VALID_START_MEASURE
小節の先頭から開始できる。DMUS_SEGF_ALIGN と組み合わせて使用される。

注意

プライマリ セグメントはデフォルトの制御セグメントである。DMUS_SEGF_CONTROL フラグを使用して、セカンダリ セグメントを制御セグメントにすることができる。DMUS_SEGF_CONTROL フラグを設定すると、DMUS_SEGF_SECONDARY が想定される。詳細については、「制御セグメント」を参照すること。

次の各グループの中から 2 つ以上のフラグを指定してはいけない。

境界
このフラグは、キューにあるセグメントの開始ポイントが位置する現在演奏中のプライマリ セグメントのポイントを制御する。DMUS_SEGF_MARKER と組み合わせることができる。この場合、境界フラグはプライマリ セグメント内にマーカーが存在しない場合にのみ使用される。

DMUS_SEGF_BEAT
DMUS_SEGF_DEFAULT
DMUS_SEGF_GRID
DMUS_SEGF_MEASURE
DMUS_SEGF_QUEUE
DMUS_SEGF_SEGMENTEND

整列
このフラグは、キューにあるセグメントのセグメント開始タイムを制御する。この時点で、演奏時間は過去のものとなる。DMUS_SEGF_ALIGN と組み合わせる必要がある。

DMUS_SEGF_VALID_START_BEAT
DMUS_SEGF_VALID_START_GRID
DMUS_SEGF_VALID_START_MEASURE
DMUS_SEGF_VALID_START_TICK

各グループのフラグを 1 つずつ組み合わせることは可能である。たとえば、DMUS_SEGF_MEASURE に DMUS_SEGF_ALIGN と DMUS_SEGF_VALID_START_BEAT を組み合わせると、キューにあるセグメントの開始ポイントが現在のプライマリ セグメントの小節境界に置かれる。この境界を既に過ぎている場合、キューに置かれているセグメントは、過ぎた時間に揃えられていないセグメント内の次の拍の境界から演奏を開始する。詳細については、「セグメントのタイミング」を参照すること。

動作環境

ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPerformance8::Invalidate、IDirectMusicPerformance8::PlaySegment、IDirectMusicPerformance8::PlaySegmentEx、IDirectMusicPerformance8::Stop、IDirectMusicSegment8::GetDefaultResolution、IDirectMusicSegment8::SetDefaultResolution、DMUS_TIME_RESOLVE_FLAGS


DMUS_SHAPET_TYPES

IDirectMusicComposer8::ComposeSegmentFromShape メソッドおよび IDirectMusicComposer8::ComposeTemplateFromShape メソッドの wShape パラメータで使用され、目的のグループ レベル のパターンを指定する。

typedef enum enumDMUS_SHAPET_TYPES {
    DMUS_SHAPET_FALLING  = 0,
    DMUS_SHAPET_LEVEL    = 1,
    DMUS_SHAPET_LOOPABLE = 2,
    DMUS_SHAPET_LOUD     = 3,
    DMUS_SHAPET_QUIET    = 4,
    DMUS_SHAPET_PEAKING  = 5,
    DMUS_SHAPET_RANDOM   = 6,
    DMUS_SHAPET_RISING   = 7,
    DMUS_SHAPET_SONG     = 8
} DMUS_SHAPET_TYPES;

定数

DMUS_SHAPET_FALLING
グルーブ レベルは下降する。
DMUS_SHAPET_LEVEL
グルーブ レベルは均等に保たれる。
DMUS_SHAPET_LOOPABLE
セグメントは先頭にループするよう調整されている。
DMUS_SHAPET_LOUD
グルーブ レベルは高い。
DMUS_SHAPET_QUIET
グルーブ レベルは低い。
DMUS_SHAPET_PEAKING
グルーブ レベルはピークまで上昇し、その後下降する。
DMUS_SHAPET_RANDOM
グルーブ レベルはランダムである。
DMUS_SHAPET_RISING
グルーブ レベルは上昇する。
DMUS_SHAPET_SONG
セグメントはソングの形式である。6 ～ 8 小節から成る複数の楽句をアレンジし、まとめることによって、グルーブ レベルにバリエーションのあるヴァースコーラス エフェクトが生み出される。

動作環境

ヘッダー : dmusici.h で宣言。


DMUS_STYLET_TYPES

IDirectMusicPatternTrack8::SetPatternByName メソッドおよび IDirectMusicStyle8::EnumPattern メソッドで使用され、パターンのタイプを指定する。

typedef enum enumDMUS_STYLET_TYPES {
    DMUS_STYLET_PATTERN  = 0,
    DMUS_STYLET_MOTIF    = 1,
    DMUS_STYLET_FRAGMENT = 2,
} DMUS_STYLET_TYPES;

定数

DMUS_STYLET_PATTERN
通常のパターン。
DMUS_STYLET_MOTIF
モチーフ パターン。
DMUS_STYLET_FRAGMENT
実装されていない。

動作環境

ヘッダー : dmusici.h で宣言。


DMUS_TIME_RESOLVE_FLAGS

DMUS_PMSG 構造体の dwFlags メンバおよび IDirectMusicPerformance8::GetResolvedTime メソッドの dwTimeResolveFlags パラメータで使用される。

typedef enum enumDMUS_TIME_RESOLVE_FLAGS {
    DMUS_TIME_RESOLVE_AFTERPREPARETIME =
            DMUS_SEGF_AFTERPREPARETIME,
    DMUS_TIME_RESOLVE_AFTERQUEUETIME   =
            DMUS_SEGF_AFTERQUEUETIME,
    DMUS_TIME_RESOLVE_AFTERLATENCYTIME =
            DMUS_SEGF_AFTERLATENCYTIME,
    DMUS_TIME_RESOLVE_GRID    = DMUS_SEGF_GRID,
    DMUS_TIME_RESOLVE_BEAT    = DMUS_SEGF_BEAT,
    DMUS_TIME_RESOLVE_MEASURE = DMUS_SEGF_MEASURE
    DMUS_TIME_RESOLVE_MARKER  = DMUS_SEGF_MARKER,
    DMUS_TIME_RESOLVE_SEGMENTEND = DMUS_SEGF_SEGMENTEND,
} DMUS_TIME_RESOLVE_FLAGS;

定数

DMUS_TIME_RESOLVE_AFTERPREPARETIME
準備時間の後のタイムに解決する。
DMUS_TIME_RESOLVE_AFTERQUEUETIME
キュー時間の後のタイムに解決する。
DMUS_TIME_RESOLVE_AFTERLATENCYTIME
遅延時間の後のタイムに解決する。
DMUS_TIME_RESOLVE_GRID
グリッド境界上のタイムに解決する。
DMUS_TIME_RESOLVE_BEAT
拍境界上のタイムに解決する。
DMUS_TIME_RESOLVE_MEASURE
小節境界上のタイムに解決する。
DMUS_TIME_RESOLVE_MARKER
マーカーに解決する。
DMUS_TIME_RESOLVE_SEGMENTEND
セグメントの最後に解決する。

注意

これらのフラグは、対応する DMUS_SEGF_FLAGS と交換して使用することができる。

動作環境

ヘッダー : dmusici.h で宣言。

参照

タイミング


DMUS_TRACKF_FLAGS

IDirectMusicTrack8::Play メソッドおよび IDirectMusicTrack8::PlayEx メソッドの dwFlags パラメータで使用される。

typedef enum enumDMUS_TRACKF_FLAGS {
    DMUS_TRACKF_SEEK       = 1,
    DMUS_TRACKF_LOOP       = 2,
    DMUS_TRACKF_START      = 4,
    DMUS_TRACKF_FLUSH      = 8,
    DMUS_TRACKF_DIRTY      = 0x10,
    DMUS_TRACKF_NOTIFY_OFF = 0x20,
    DMUS_TRACKF_PLAYOFF    = 0x40,
    DMUS_TRACKF_LOOPEND    = 0x80,
    DMUS_TRACKF_STOP       = 0x100,
    DMUS_TRACKF_RECOMPOSE  = 0x200,
    DMUS_TRACKF_CLOCK      = 0x400,
} DMUS_TRACKF_FLAGS;

定数

DMUS_TRACKF_SEEK
IDirectMusicTrack8::Play は、シークに対応して呼び出された。これは、mtStart パラメータが直前の呼び出しの mtEnd と同じでなくてもかまわないことを意味する。
DMUS_TRACKF_LOOP
ループに応答して Play が呼び出された。
DMUS_TRACKF_START
これが IDirectMusicTrack8::Play の初めての呼び出しである。トラックが先頭から演奏されていない場合は、DMUS_TRACKF_SEEK を設定することもできる。
DMUS_TRACKF_FLUSH
フラッシュ (解放) か無効化に応答して Play が呼び出された。これは、既に演奏された何らかのものを再演奏するようトラックに要求する。この場合、DMUS_TRACKF_SEEK も設定される。
DMUS_TRACKF_DIRTY
制御セグメントが開始または終了した。mtNext が IDirectMusicTrack8::GetParam または IDirectMusicTrack8::GetParamEx を呼び出すまで通常呼び出しを待っているトラックは、データが無効になる可能性があるため、待機せずに、即座に呼び出しを行うべきである。制御セグメントの設定方法については、「DMUS_SEGF_FLAGS」を参照すること。
DMUS_TRACKF_NOTIFY_OFF
トラックは通知を送信しない。
DMUS_TRACKF_PLAYOFF
トラックは演奏しないが、引き続き通知を送信できる。
DMUS_TRACKF_LOOPEND
範囲の最後がループの終了でもある。
DMUS_TRACKF_STOP
範囲の最後が、このセグメントの演奏の終わりでもある。
DMUS_TRACKF_RECOMPOSE
各ループについて、トラックを再アレンジする。サインポスト トラックは、異なるコード進行を使用して再アレンジされ、メロディ編成トラックは、異なるメロディ断片を使用して再アレンジされる。
DMUS_TRACKF_CLOCK
タイム パラメータは基準タイムで表される。IDirectMusicTrack8::PlayEx に対してのみ有効である。

注意

反復 (リピート) に応答して Play を呼び出した場合、DMUS_TRACKF_LOOP と DMUS_TRACKF_SEEK が設定される。

無効化をサポートするには、トラックはシークをサポートしなければならない。

動作環境

ヘッダー : dmplugin.h で宣言。


DMUS_VARIATIONT_TYPES

DMUS_IO_PARTREF 構造体で使用され、シーケンシャル コマンド内でのバリエーションの選択方法を指定する。

typedef enum enumDMUS_VARIATIONT_TYPES
{
    DMUS_VARIATIONT_SEQUENTIAL       = 0,
    DMUS_VARIATIONT_RANDOM           = 1,
    DMUS_VARIATIONT_RANDOM_START     = 2,
    DMUS_VARIATIONT_NO_REPEAT        = 3,
    DMUS_VARIATIONT_RANDOM_ROW       = 4
} DMUS_VARIATIONT_TYPES;

定数

DMUS_VARIATIONT_SEQUENTIAL
一致するバリエーションを、ロードされた順に最初から演奏する。
DMUS_VARIATIONT_RANDOM
一致するバリエーションをランダムに選択する。これは、DirectX 8.0 以前のバージョンの動作である。
DMUS_VARIATIONT_RANDOM_START
一致するバリエーションを、ロードされた順に、シーケンス内のランダムなポイントから演奏する。
DMUS_VARIATIONT_NO_REPEAT
ランダムに演奏する。ただし、バリエーションは一度ずつしか演奏しない。
DMUS_VARIATIONT_RANDOM_ROW
ランダムに演奏する。すべてを演奏するまではバリエーションを繰り返さない。

動作環境

ヘッダー : dmusicf.h で宣言。

参照

DMUS_COMMAND_PARAM、DMUS_COMMAND_PARAM_2、DMUS_IO_COMMAND、DMUS_VARIATIONT_TYPES


DirectMusic 戻り値

ここでは、DirectMusic のメソッドによって返される可能性のあるさまざまなエラー コードについて簡単に説明する。各メソッドが返す可能性のある特定のコードのリストについては、個別のメソッドの説明を参照すること。それらのリストは必ずしも包括的なものとは限らない。

エラー コードは以下のトピックに示されている。

  • DirectMusic 戻り値 (値)
  • DirectMusic 戻り値 (名前)


DirectMusic 戻り値 (値)

次の表は、16 進値で格納される DirectMusic 戻り値を示している。説明については、定数をクリックすること。

16 進値 | 定数
0x00000000 | S_OK
0x00000001 | S_FALSE
0x08781091 | DMUS_S_PARTIALLOAD
0x08781092 | DMUS_S_PARTIALDOWNLOAD
0x08781200 | DMUS_S_REQUEUE
0x08781201 | DMUS_S_FREE
0x08781202 | DMUS_S_END
0x08781210 | DMUS_S_STRING_TRUNCATED
0x08781211 | DMUS_S_LAST_TOOL
0x08781212 | DMUS_S_OVER_CHORD
0x08781213 | DMUS_S_UP_OCTAVE
0x08781214 | DMUS_S_DOWN_OCTAVE
0x08781215 | DMUS_S_NOBUFFERCONTROL
0x08781216 | DMUS_S_GARBAGE_COLLECTED
0x80004001 | E_NOTIMPL
0x80004002 | E_NOINTERFACE
0x80004003 | E_POINTER
0x80040110 | CLASS_E_NOAGGREGATION
0x80040110 | CLASS_E_NOAGGREGATION
0x80040154 | REGDB_E_CLASSNOTREG
0x8007000E | E_OUTOFMEMORY
0x80070057 | E_FAIL
0x80070057 | E_INVALIDARG
0x88781101 | DMUS_E_DRIVER_FAILED
0x88781102 | DMUS_E_PORTS_OPEN
0x88781103 | DMUS_E_DEVICE_IN_USE
0x88781104 | DMUS_E_INSUFFICIENTBUFFER
0x88781105 | DMUS_E_BUFFERNOTSET
0x88781106 | DMUS_E_BUFFERNOTAVAILABLE
0x88781108 | DMUS_E_NOTADLSCOL
0x88781109 | DMUS_E_INVALIDOFFSET
0x88781111 | DMUS_E_ALREADY_LOADED
0x88781113 | DMUS_E_INVALIDPOS
0x88781114 | DMUS_E_INVALIDPATCH
0x88781115 | DMUS_E_CANNOTSEEK
0x88781116 | DMUS_E_CANNOTWRITE
0x88781117 | DMUS_E_CHUNKNOTFOUND
0x88781119 | DMUS_E_INVALID_DOWNLOADID
0x88781120 | DMUS_E_NOT_DOWNLOADED_TO_PORT
0x88781121 | DMUS_E_ALREADY_DOWNLOADED
0x88781122 | DMUS_E_UNKNOWNDOWNLOAD
0x88781123 | DMUS_E_SET_UNSUPPORTED
0x88781124 | DMUS_E_GET_UNSUPPORTED
0x88781125 | DMUS_E_NOTMONO
0x88781126 | DMUS_E_BADARTICULATION
0x88781127 | DMUS_E_BADINSTRUMENT
0x88781128 | DMUS_E_BADWAVELINK
0x88781128 | DMUS_E_BUFFER_EMPTY
0x8878112A | DMUS_E_NOTPCM
0x8878112B | DMUS_E_BADWAVE
0x8878112C | DMUS_E_BADOFFSETTABLE
0x8878112D | DMUS_E_UNKNOWN_PROPERTY
0x8878112E | DMUS_E_NOSYNTHSINK
0x8878112F | DMUS_E_ALREADYOPEN
0x88781130 | DMUS_E_ALREADYCLOSED
0x88781131 | DMUS_E_SYNTHNOTCONFIGURED
0x88781132 | DMUS_E_SYNTHACTIVE
0x88781133 | DMUS_E_CANNOTREAD
0x88781134 | DMUS_E_DMUSIC_RELEASED
0x88781136 | DMUS_E_BUFFER_FULL
0x88781137 | DMUS_E_PORT_NOT_CAPTURE
0x88781138 | DMUS_E_PORT_NOT_RENDER
0x88781139 | DMUS_E_DSOUND_NOT_SET
0x8878113A | DMUS_E_ALREADY_ACTIVATED
0x8878113B | DMUS_E_INVALIDBUFFER
0x8878113C | DMUS_E_WAVEFORMATNOTSUPPORTED
0x8878113D | DMUS_E_SYNTHINACTIVE
0x8878113E | DMUS_E_DSOUND_ALREADY_SET
0x8878113F | DMUS_E_INVALID_EVENT
0x88781150 | DMUS_E_UNSUPPORTED_STREAM
0x88781151 | DMUS_E_ALREADY_INITED
0x88781152 | DMUS_E_INVALID_BAND
0x88781155 | DMUS_E_TRACK_HDR_NOT_FIRST_CK
0x88781156 | DMUS_E_TOOL_HDR_NOT_FIRST_CK
0x88781157 | DMUS_E_INVALID_TRACK_HDR
0x88781158 | DMUS_E_INVALID_TOOL_HDR
0x88781159 | DMUS_E_ALL_TOOLS_FAILED
0x88781160 | DMUS_E_ALL_TRACKS_FAILED
0x88781161 | DMUS_E_NOT_FOUND
0x88781162 | DMUS_E_NOT_INIT
0x88781163 | DMUS_E_TYPE_DISABLED
0x88781164 | DMUS_E_TYPE_UNSUPPORTED
0x88781165 | DMUS_E_TIME_PAST
0x88781166 | DMUS_E_TRACK_NOT_FOUND
0x88781167 | DMUS_E_TRACK_NO_CLOCKTIME_SUPPORT
0x88781170 | DMUS_E_NO_MASTER_CLOCK
0x88781170 | DMUS_E_NOARTICULATION
0x88781180 | DMUS_E_LOADER_NOCLASSID
0x88781181 | DMUS_E_LOADER_BADPATH
0x88781182 | DMUS_E_LOADER_FAILEDOPEN
0x88781183 | DMUS_E_LOADER_FORMATNOTSUPPORTED
0x88781184 | DMUS_E_LOADER_FAILEDCREATE
0x88781185 | DMUS_E_LOADER_OBJECTNOTFOUND
0x88781186 | DMUS_E_LOADER_NOFILENAME
0x88781200 | DMUS_E_INVALIDFILE
0x88781201 | DMUS_E_ALREADY_EXISTS
0x88781202 | DMUS_E_OUT_OF_RANGE
0x88781203 | DMUS_E_SEGMENT_INIT_FAILED
0x88781204 | DMUS_E_ALREADY_SENT
0x88781205 | DMUS_E_CANNOT_FREE
0x88781206 | DMUS_E_CANNOT_OPEN_PORT
0x88781207 | DMUS_E_CANNOT_CONVERT
0x88781210 | DMUS_E_DESCEND_CHUNK_FAIL
0x88781211 | DMUS_E_NOT_LOADED
0x88781213 | DMUS_E_SCRIPT_LANGUAGE_INCOMPATIBLE
0x88781214 | DMUS_E_SCRIPT_UNSUPPORTED_VARTYPE
0x88781215 | DMUS_E_SCRIPT_ERROR_IN_SCRIPT
0x88781216 | DMUS_E_SCRIPT_CANTLOAD_OLEAUT32
0x88781217 | DMUS_E_SCRIPT_LOADSCRIPT_ERROR
0x88781218 | DMUS_E_SCRIPT_INVALID_FILE
0x88781219 | DMUS_E_INVALID_SCRIPTTRACK
0x8878121A | DMUS_E_SCRIPT_VARIABLE_NOT_FOUND
0x8878121B | DMUS_E_SCRIPT_ROUTINE_NOT_FOUND
0x8878121C | DMUS_E_SCRIPT_CONTENT_READONLY
0x8878121D | DMUS_E_SCRIPT_NOT_A_REFERENCE
0x8878121E | DMUS_E_SCRIPT_VALUE_NOT_SUPPORTED
0x88781220 | DMUS_E_INVALID_SEGMENTTRIGGERTRACK
0x88781221 | DMUS_E_INVALID_LYRICSTRACK
0x88781222 | DMUS_E_INVALID_PARAMCONTROLTRACK
0x88781223 | DMUS_E_AUDIOVBSCRIPT_SYNTAXERROR
0x88781224 | DMUS_E_AUDIOVBSCRIPT_RUNTIMEERROR
0x88781225 | DMUS_E_AUDIOVBSCRIPT_OPERATIONFAILURE
0x88781226 | DMUS_E_AUDIOPATHS_NOT_VALID
0x88781227 | DMUS_E_AUDIOPATHS_IN_USE
0x88781228 | DMUS_E_NO_AUDIOPATH_CONFIG
0x88781229 | DMUS_E_AUDIOPATH_INACTIVE
0x8878122A | DMUS_E_AUDIOPATH_NOBUFFER
0x8878122B | DMUS_E_AUDIOPATH_NOPORT
0x8878122C | DMUS_E_NO_AUDIOPATH
0x8878122D | DMUS_E_INVALIDCHUNK
0x8878122E | DMUS_E_AUDIOPATH_NOGLOBALFXBUFFER
0x8878122F | DMUS_E_INVALID_CONTAINER_OBJECT


DirectMusic 戻り値 (名前)

次のリストは、すべての DirectMusic 戻り値を示している。値から定数を確認するには、「DirectMusic 戻り値 (値)」を参照すること。

CLASS_E_NOAGGREGATION
集合体はサポートしていない。LPUNKNOWN パラメータを NULL に設定しなければならない。
DMUS_E_ALL_TOOLS_FAILED
グラフ オブジェクトは、IStream オブジェクト データからすべてのツールをロードできなかった。これは、ストリーム内でエラーが発生したか、ツールがクライアント上で不正に登録されていることが原因と考えられる。
DMUS_E_ALL_TRACKS_FAILED
セグメント オブジェクトは、IStream オブジェクト データからすべてのトラックをロードできなかった。これは、ストリーム内でエラーが発生したか、トラックがクライアント上で不正に登録されていることが原因と考えられる。
DMUS_E_ALREADY_ACTIVATED
ポートは既にアクティブにされており、パラメータは変更できない。
DMUS_E_ALREADY_DOWNLOADED
バッファは既にダウンロードされている。
DMUS_E_ALREADY_EXISTS
ツールはグラフ内に既に含まれている。新しいインスタンスを作成しなければならない。
DMUS_E_ALREADY_INITED
オブジェクトは既に初期化されている。
DMUS_E_ALREADY_LOADED
DLS コレクションは既に開いている。
DMUS_E_ALREADY_SENT
メッセージは既に送信されている。
DMUS_E_ALREADYCLOSED
ポートは開いていない。
DMUS_E_ALREADYOPEN
ポートは既に開いている。
DMUS_E_AUDIOPATH_INACTIVE
オーディオパスが非アクティブである。パフォーマンスが終了していることが原因と考えられる。
DMUS_E_AUDIOPATH_NOBUFFER
要求されたバッファを作成できないため、オーディオパスを作成できない。
DMUS_E_AUDIOPATH_NOGLOBALFXBUFFER
存在しないグローバル エフェクト バッファに送信するオーディオパスを作成しようとした。
DMUS_E_AUDIOPATH_NOPORT
ポート割り当てがないため、再生にオーディオパスを使用できない。
DMUS_E_AUDIOPATHS_IN_USE
パフォーマンスがオーディオパスをセットアップしたので、パフォーマンス チャンネルを割り当てることができない。
DMUS_E_AUDIOPATHS_NOT_VALID
パフォーマンス チャンネルが IDirectMusicPerformance8::AssignPChannel を使ってセットアップされたので、パフォーマンスはオーディオパスをサポートできない。
DMUS_E_AUDIOVBSCRIPT_OPERATIONFAILURE
スクリプト外の関数を実行できなかったため、AudioVBScript で作成されたスクリプト ルーチンが失敗した。
DMUS_E_AUDIOVBSCRIPT_RUNTIMEERROR
整数をオブジェクトに追加する、または存在しないルーチンを呼び出そうとするなど、無効な演算が発生したため、AudioVBScript で作成されたスクリプト ルーチンが失敗した。
DMUS_E_AUDIOVBSCRIPT_SYNTAXERROR
AudioVBScript で許可されていないステートメントが含まれているため、AudioVBScript で作成されたスクリプト ルーチンを読み取ることができなかった。
DMUS_E_BADARTICULATION
DLS コレクション内に無効なアーティキュレーション チャンクがある。
DMUS_E_BADINSTRUMENT
DLS コレクション内に無効な音色チャンクがある。
DMUS_E_BADOFFSETTABLE
オフセット テーブルにエラーがある。
DMUS_E_BADWAVE
ウェーブ ヘッダーが壊れている。
DMUS_E_BADWAVELINK
DLS コレクション内のウェーブリンク チャンクが無効なウェーブを指している。
DMUS_E_BUFFER_EMPTY
バッファ内にデータがない。
DMUS_E_BUFFER_FULL
指定したバイト数が最大バッファ サイズを超えている。
DMUS_E_BUFFERNOTAVAILABLE
このバッファはダウンロードに利用できない。
DMUS_E_BUFFERNOTSET
データ用に準備されたバッファが存在しない。
DMUS_E_CANNOT_CONVERT
ミュージック値と MIDI 値との間で要求した変換は行われなかった。これは通常、提供された DMUS_CHORD_KEY 構造体に無効なコードまたはスケール パターンが含まれる場合に発生する。
DMUS_E_CANNOT_FREE
メッセージが割り当てられていないか、既に解放されているため、メッセージを解放できなかった。
DMUS_E_CANNOT_OPEN_PORT
デフォルトのシステム ポートを開くことができなかった。
DMUS_E_CANNOTREAD
IStream オブジェクトから読み込みを行おうとしていたときにエラーが発生した。
DMUS_E_CANNOTSEEK
IStream オブジェクトは Seek をサポートしない。
DMUS_E_CANNOTWRITE
IStream オブジェクトは Write をサポートしない。
DMUS_E_CHUNKNOTFOUND
指定されたヘッダーを持つチャンクが見つからなかった。
DMUS_E_DESCEND_CHUNK_FAIL
チャンク内に下がろうとしたが失敗した。
DMUS_E_DEVICE_IN_USE
デバイスは (おそらく DirectMusic 以外のクライアントによって) 使用中であり、再度開くことができない。
DMUS_E_DMUSIC_RELEASED
DirectMusic オブジェクトの最後のインスタンスが解放されたため、操作を実行できない。DirectMusic オブジェクトの最後の解放が終わるまで、ポートは使用できない。
DMUS_E_DRIVER_FAILED
ドライバまたはハードウェアでの障害の可能性を示す予想外のエラーがデバイス ドライバから返された。
DMUS_E_DSOUND_ALREADY_SET
DirectSound オブジェクトは既に設定されている。
DMUS_E_DSOUND_NOT_SET
DirectSound オブジェクトが指定されていないため、ポートを作成できなかった。
DMUS_E_GET_UNSUPPORTED
パラメータの取得はサポートしていない。
DMUS_E_INSUFFICIENTBUFFER
要求された操作を実行するためのバッファが十分な大きさではない。
DMUS_E_INVALID_BAND
ファイルに有効なバンドが含まれていない。
DMUS_E_INVALID_CONTAINER_OBJECT
ファイルに有効なコンテナ オブジェクトが含まれていない。
DMUS_E_INVALID_DOWNLOADID
ダウンロード バッファの作成プロセスで、無効なダウンロード識別子が使われた。
DMUS_E_INVALID_EVENT
イベントは、有効な MIDI メッセージではない、または動作ステータスを利用しておりバッファ内にパックできない。
DMUS_E_INVALID_LYRICSTRACK
ファイルに含まれる歌詞トラックが無効である。
DMUS_E_INVALID_PARAMCONTROLTRACK
ファイルに含まれるパラメータ制御トラックが無効である。
DMUS_E_INVALID_SCRIPTTRACK
ファイルに含まれるスクリプト トラックが無効である。
DMUS_E_INVALID_SEGMENTTRIGGERTRACK
ファイルに含まれるセグメント トリガ トラックが無効である。
DMUS_E_INVALID_TOOL_HDR
IStream オブジェクトのデータには、無効なツール ヘッダーが含まれているため、グラフ オブジェクトによる読み込みができない。
DMUS_E_INVALID_TRACK_HDR
IStream オブジェクトのデータには、無効なトラック ヘッダーが含まれているため、セグメント オブジェクトによる読み込みができない。
DMUS_E_INVALIDBUFFER
無効な DirectSound バッファがポートに渡された。
DMUS_E_INVALIDCHUNK
RIFF ファイル チャンクで無効なデータが見つかった。
DMUS_E_INVALIDFILE
ファイルが無効である。
DMUS_E_INVALIDOFFSET
DLS コレクション ファイル内のウェーブ チャンクが正しいオフセット上にない。
DMUS_E_INVALIDPATCH
コレクション内の音色がパッチ番号と一致しない。
DMUS_E_INVALIDPOS
DLS コレクションからウェーブ データを読み込み中にエラーが発生した。これは、不正なファイルであることを意味する。
DMUS_E_LOADER_BADPATH
ファイルパスが無効である。
DMUS_E_LOADER_FAILEDCREATE
オブジェクトが見つからなかった、または作成できなかった。
DMUS_E_LOADER_FAILEDOPEN
ファイルが存在していないかロックされているのが原因で、ファイルを開くことに失敗した。
DMUS_E_LOADER_FORMATNOTSUPPORTED
データフォーマットがサポートされていないため、オブジェクトをロードできない。
DMUS_E_LOADER_NOCLASSID
オブジェクト記述にクラス識別子が指定されていない。
DMUS_E_LOADER_NOFILENAME
オブジェクト記述にファイル名が指定されていない。
DMUS_E_LOADER_OBJECTNOTFOUND
オブジェクトが見つからなかった。
DMUS_E_NO_AUDIOPATH
存在しないオーディオパス上で再生しようとした。
DMUS_E_NO_AUDIOPATH_CONFIG
オブジェクトに、埋め込み型のオーディオパス構成が含まれていない。
DMUS_E_NO_MASTER_CLOCK
パフォーマンス内にマスタ クロックが存在しない。必ず IDirectMusicPerformance8::Init メソッドを呼び出すこと。
DMUS_E_NOARTICULATION
DLS コレクション内の音色からアーティキュレーションが見つからない。
DMUS_E_NOSYNTHSINK
シンクがシンセサイザに接続されていない。
DMUS_E_NOT_DOWNLOADED_TO_PORT
オブジェクトがポート上にないため、アンロードできない。
DMUS_E_NOT_FOUND
要求された項目はオブジェクトに含まれていない。
DMUS_E_NOT_INIT
必要なオブジェクトは初期化されていないか、初期化に失敗した。
DMUS_E_NOT_LOADED
ロードされていなかったため、このオブジェクトを使用できなかった。
DMUS_E_NOTADLSCOL
ロード中のオブジェクトは有効な DLS コレクションではない。
DMUS_E_NOTMONO
ウェーブ チャンクには複数のインターリーブ チャンネルがある。DLS フォーマットではモノラルが要求される。
DMUS_E_NOTPCM
ウェーブデータが PCM フォーマットになっていない。
DMUS_E_OUT_OF_RANGE
要求されたタイムはセグメントの範囲外である。
DMUS_E_PORT_NOT_CAPTURE
ポートはキャプチャ ポートではない。
DMUS_E_PORT_NOT_RENDER
ポートは出力ポートではない。
DMUS_E_PORTS_OPEN
システム内の任意のプロセスにインスタンス化されたポートがあるときは、要求された操作を実行できない。
DMUS_E_SCRIPT_CANTLOAD_OLEAUT32
Oleaut32.dll のロードが失敗した。ActiveX スクリプティング言語は oleaut32.dll を使用する必要がある。このファイルが存在しないプラットフォームで使用できるのは、AudioVBScript 言語のみである。
DMUS_E_SCRIPT_CONTENT_READONLY
スクリプトで参照されるコンテントまたはスクリプトに埋め込まれるコンテントのスクリプト変数が設定できない。
DMUS_E_SCRIPT_ERROR_IN_SCRIPT
スクリプトの解析中または実行中にエラーが発生した。
DMUS_E_SCRIPT_INVALID_FILE
スクリプト ファイルが無効である。
DMUS_E_SCRIPT_LANGUAGE_INCOMPATIBLE
このスクリプトの言語に対応した ActiveX スクリプティング エンジンには、DirectMusic との互換性がない。
DMUS_E_SCRIPT_LOADSCRIPT_ERROR
ロードされたスクリプトにエラーがある。
DMUS_E_SCRIPT_NOT_A_REFERENCE
オブジェクト タイプではない値への参照でスクリプトの変数を設定しようとした。
DMUS_E_SCRIPT_ROUTINE_NOT_FOUND
スクリプトに、指定された名前のルーチンが含まれていない。
DMUS_E_SCRIPT_UNSUPPORTED_VARTYPE
DirectMusic がサポートしていないタイプを持つバリアントが使用された。
DMUS_E_SCRIPT_VALUE_NOT_SUPPORTED
デフォルト値のプロパティをサポートしないオブジェクトへの値でスクリプトの変数を設定しようとした。
DMUS_E_SCRIPT_VARIABLE_NOT_FOUND
スクリプトに、指定された名前の変数が含まれていない。
DMUS_E_SEGMENT_INIT_FAILED
セグメントの初期化に失敗した。メモリで重大な問題が発生したと考えられる。
DMUS_E_SET_UNSUPPORTED
パラメータの設定はサポートしていない。
DMUS_E_SYNTHACTIVE
シンセサイザは既にアクティブにされており、パラメータは変更できない。
DMUS_E_SYNTHINACTIVE
シンセサイザはアクティブにされておらず、データを処理できない。
DMUS_E_SYNTHNOTCONFIGURED
シンセサイザは正しく構成されていないか、開いていない。
DMUS_E_TIME_PAST
要求されたタイムは過去のタイムである。
DMUS_E_TOOL_HDR_NOT_FIRST_CK
ストリーム オブジェクトのデータには最初のチャンクとしてツール ヘッダーがないため、グラフ オブジェクトによる読み込みができない。
DMUS_E_TRACK_HDR_NOT_FIRST_CK
ストリーム オブジェクトのデータには最初のチャンクとしてトラック ヘッダーがないため、セグメント オブジェクトによる読み込みができない。
DMUS_E_TRACK_NO_CLOCKTIME_SUPPORT
トラックは、クロック タイムの再生またはパラメータの取得をサポートしていない。
DMUS_E_TRACK_NOT_FOUND
要求されたタイプのトラックがない。
DMUS_E_TYPE_DISABLED
トラック パラメータは無効にされているため利用できない。
DMUS_E_TYPE_UNSUPPORTED
パラメータはこのトラック上でサポートされていない。
DMUS_E_UNKNOWN_PROPERTY
このポートにはプロパティ セットや項目が実装されていない。
DMUS_E_UNKNOWNDOWNLOAD
シンセサイザはこのタイプのダウンロードをサポートしていない。
DMUS_E_UNSUPPORTED_STREAM
IStream オブジェクトは、ロード中のオブジェクトがサポートしているデータを含んでいない。
DMUS_E_WAVEFORMATNOTSUPPORTED
無効なバッファ フォーマットがシンセサイザ シンクに渡された。
DMUS_S_DOWN_OCTAVE
ノートが 1 オクターブまたは複数オクターブ分下げられ、MIDI 値の範囲内に収まっている。
DMUS_S_END
操作に成功し、データの最後に達した。
DMUS_S_FREE
割り当てられたメモリを解放すべきである。
DMUS_S_GARBAGE_COLLECTED
オブジェクトが解放されていたため、要求された処理が実行されなかった。
DMUS_S_LAST_TOOL
グラフ内にはこれ以上のツールがない。
DMUS_S_NOBUFFERCONTROL
ポートからのオーディオ出力は、指定された DirectSound バッファと同じデバイスに転送されるが、パンやボリュームなどのバッファ コントロールは出力に影響しない。
DMUS_S_OVER_CHORD
ミュージック値がコードの最高音より高い位置にあるノートを持っているため、MIDI 値は計算されていない。
DMUS_S_PARTIALDOWNLOAD
一部の音色をポートにダウンロードできなかった。
DMUS_S_PARTIALLOAD
オブジェクトは部分的なロードしかできなかった。これは、埋め込まれたトラックやツールなどの一部のコンポーネントが正しく登録されていない場合に発生することがある。また、たとえば、セグメントでローダーの現在の検索ディレクトリにない DLS コレクションが使用されている場合など、コンテントの一部がないときに発生する場合もある。
DMUS_S_REQUEUE
メッセージを次のツールに渡すべきである。
DMUS_S_STRING_TRUNCATED
メソッドは成功したが、返された文字列は切り捨てられた。
DMUS_S_UP_OCTAVE
ノートが 1 オクターブまたは複数オクターブ分上げられ、MIDI 値の範囲内に収まっている。
E_FAIL
このメソッドは成功しなかった。
E_INVALIDARG
引数が無効である。構造体の dwSize メンバを初期化するのを忘れ、このメンバをメソッドに渡した場合にこのエラーが起こることが多い。
E_NOINTERFACE
利用可能なオブジェクト インターフェイスがない。
E_NOTIMPL
このメソッドは実装されていない。動作に必要な機能をドライバがサポートしていないために、このメソッドが返されることがある。
E_OUTOFMEMORY
メモリ不足のため、タスクを完了できない。
E_POINTER
無効なポインタ (通常は NULL) がパラメータとして渡された。
REGDB_E_CLASSNOTREG
オブジェクト クラスが登録されていない。
S_FALSE
メソッドは成功したが、すべきことが何もなかった。
S_OK
動作は完了し、成功した。


DirectSound C/C++ リファレンス

ここでは、Microsoft® DirectSound® アプリケーション プログラミング インターフェイス (API) のリファレンス情報を記述する。ここでは、DirectSound が提供する API 要素のリファレンス情報を記述する。リファレンス情報は次のカテゴリに分類される。

  • DirectSound インターフェイス
  • DirectSound コールバック関数
  • DirectSound 関数
  • DirectSound 構造体
  • DirectSound 戻り値


DirectSound インターフェイス

ここでは、次の DirectSound インターフェイスのメソッドに関するリファレンス情報を記述する。

  • IDirectSound8
  • IDirectSound3DBuffer8
  • IDirectSound3DListener8
  • IDirectSoundBuffer8
  • IDirectSoundCapture8
  • IDirectSoundCaptureBuffer8
  • IDirectSoundCaptureFXAec8
  • IDirectSoundCaptureFXNoiseSuppress8
  • IDirectSoundFullDuplex8
  • IDirectSoundFXChorus8
  • IDirectSoundFXCompressor8
  • IDirectSoundFXDistortion8
  • IDirectSoundFXEcho8
  • IDirectSoundFXFlanger8
  • IDirectSoundFXGargle8
  • IDirectSoundFXI3DL2Reverb8
  • IDirectSoundFXParamEq8
  • IDirectSoundNotify8
  • IKsPropertySet

DirectX 8.0 で、名前に番号の付いてないインターフェイスを置き換える新しいインターフェイスは、IDirectSound8、IDirectSoundBuffer8、および IDirectSoundCaptureBuffer8 だけである。名前の最後が 8 であるその他のインターフェイスは、変更のないインターフェイス、または番号の付いていない新しいインターフェイスの単なる定義である。たとえば、IDirectSoundCapture8 は IDirectSoundCapture とまったく同じである。

8 で終わる定義を持つインターフェイスはすべて、定義された名前で説明されている。コード中では、常にこの名前を使用することを推奨する。今後のバージョンにおいて再コンパイルする際に、すべての宣言で最新の番号に置換して、更新された最新バージョンのインターフェイスを使用できる。

メソッドがインターフェイス ポインタをパラメータとして受け取る場合は、古いバージョンを受け取るようにメソッドで宣言されている場合でも、新しいバージョンを渡すことができる。たとえば、IDirectSoundBuffer または IDirectSoundBuffer8 へのポインタを pDSBufferOriginal パラメータとして IDirectSound8::DuplicateSoundBuffer に渡すことができる。

ただし、メソッドがインターフェイスを返す場合は、古いインターフェイスが返されるので、QueryInterface を使用して新しいインターフェイスを取得する必要がある。たとえば、IDirectSound8::CreateSoundBuffer の ppDSBuffer は、インターフェイスを返すパラメータである。


IDirectSound8

バッファ オブジェクトの作成および環境の設定に使用する。

IDirectSound の代わりに IDirectSound8 インターフェイスが提供され、新しいメソッドが追加される。「注意」を参照すること。

DirectSoundCreate8 または DirectSoundFullDuplexCreate8 関数を使ってこのインターフェイスを取得するか、CoCreateInstance または CoCreateInstanceEx を使ってクラス CLSID_DirectSound8 のオブジェクトを作成する。

IDirectSound8 インターフェイスのメソッドは、次のグループにまとめることができる。

初期化 | Initialize
 | SetCooperativeLevel
バッファ作成 | CreateSoundBuffer
 | DuplicateSoundBuffer
デバイスの能力 | GetCaps
 | VerifyCertification
メモリ管理 | Compact
スピーカの構成 | GetSpeakerConfig
 | SetSpeakerConfig

すべての COM インターフェイスと同様、IDirectSound8 インターフェイスは IUuknown インターフェイス メソッドを継承している。IUnknown インターフェイスは次の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTSOUND8 型は、IDirectSound8 インターフェイスへのポインタとして定義されている。

typedef struct IDirectSound8    *LPDIRECTSOUND8;

注意

CLSID_DirectSound8 クラスのオブジェクトだけが、このインターフェイスをサポートする。DirectSoundCreate8 および DirectSoundFullDuplexCreate8 で作成された DirectSound オブジェクトは、すべてこのカテゴリとなる。CLSID_DirectSound クラスのオブジェクトは、DirectSoundCreate を使って作成されたすべてのオブジェクトを含めて、以前の IDirectSound インターフェイスのみをサポートする。

CLSID_DirectSound8 オブジェクトの動作は、いくつかの点で CLSID_DirectSound オブジェクトと異なる。これらの違いは、IDirectSound8 インターフェイスと同様、IDirectSound インターフェイスにも見られる。新しいオブジェクトの動作に関して、次のような相違がある。

  • IDirectSound8::CreateSoundBuffer では、非モノラル形式のバッファで DSBCAPS_CTRL3D を設定できない。また、DSBCAPS_CTRL3D を DSBCAPS_CTRLPAN と組み合わせることができない。
  • 新規バッファ作成のフラグがサポートされない。
  • 作成時にバッファに無音が設定されない。
  • IDirectSoundBuffer8 インターフェイスに対して、CreateSoundBuffer で返される IDirectSoundBuffer インターフェイスを問い合わせることができる。
  • WAVE_FORMAT_EXTENSIBLE フォーマット タグのある DSBUFFERDESC 構造体のウェーブ フォーマットでは、その有効性がより厳密に確認される。

動作環境

ヘッダー : dsound.h で宣言。


IDirectSound8::Compact

オンボード サウンド メモリに未使用部分が存在する場合、これらを移動して連続ブロックを形成し、空きメモリ領域を最大にする。

HRESULT Compact();

パラメータ

なし。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED
DSERR_UNINITIALIZED

注意

アプリケーションの DirectSound オブジェクトは、少なくとも DSSCL_PRIORITY の協調レベルを備えていなければならない。IDirectSound8::SetCooperativeLevel を参照すること。

進行中の操作がほかに 1 つでも存在すると、このメソッドは失敗する。

動作環境

ヘッダー : dsound.h で宣言。


IDirectSound8::CreateSoundBuffer

サンプリング オーディオのシーケンスを保持するための DirectSoundBuffer オブジェクトを作成する。

HRESULT CreateSoundBuffer(
  LPCDSBUFFERDESC pcDSBufferDesc,
  LPDIRECTSOUNDBUFFER * ppDSBuffer,
  LPUNKNOWN pUnkOuter
);

パラメータ

pcDSBufferDesc
作成するサウンド バッファを記述する DSBUFFERDESC 構造体のアドレス。
ppDSBuffer
新しいバッファ オブジェクトの IDirectSoundBuffer インターフェイスを受け取る変数のアドレス。IDirectSoundBuffer8 を取得するには、QueryInterface を使用する。IDirectSoundBuffer8 はプライマリ バッファには利用できない。「注意」を参照すること。
pUnkOuter
COM 集成体に対する制御オブジェクトの IUnknown インターフェイスのアドレス。NULL でなければならない。

戻り値

成功した場合は DS_OK を返す。また、要求した 3D アルゴリズムを利用できず、ステレオ パンが代用された場合は、DS_NO_VIRTUALIZATION を返す。DSBUFFERDESC の guid3DAlgorithm メンバの記述を参照すること。

失敗した場合は、次のいずれかのエラー値を返す。

DSERR_ALLOCATED
DSERR_CONTROLUNAVAIL
DSERR_BADFORMAT
DSERR_BUFFERTOOSMALL
DSERR_DS8_REQUIRED
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_NOAGGREGATION
DSERR_OUTOFMEMORY
DSERR_UNINITIALIZED
DSERR_UNSUPPORTED

注意

DirectSound は、バッファの内容を初期化しない。したがって、アプリケーションでは、バッファに無音が含まれていると想定してはならない。

アプリケーションがマルチスレッド化されている場合、バッファを作成するスレッドは、バッファの有効期間を通して存在していなければならない。WDM ドライバで作成されたバッファでは、スレッドが終了すると再生が停止する。

ハードウェア アクセラレーションを利用できないシステムで DSBCAPS_LOCHARDWARE フラグを使ってバッファを作成しようとすると、メソッドは失敗し、オペレーティング システムに応じて DSERR_CONTROLUNAVAIL または DSERR_INVALIDCALL を返す。

動作環境

ヘッダー : dsound.h で宣言。

参照

セカンダリ バッファの作成、IDirectSound8::DuplicateSoundBuffer


IDirectSound8::DuplicateSoundBuffer

新しい DirectSoundBuffer オブジェクトを作成する。このオブジェクトは、オリジナルのバッファのメモリを複製または共有する。

HRESULT DuplicateSoundBuffer(
  LPDIRECTSOUNDBUFFER pDSBufferOriginal,
  LPDIRECTSOUNDBUFFER * ppDSBufferDuplicate
);

パラメータ

pDSBufferOriginal
複製するバッファの IDirectSoundBuffer または IDirectSoundBuffer8 インターフェイスのアドレス。
ppDSBufferDuplicate
新しいバッファの IDirectSoundBuffer インターフェイス ポインタを受け取る変数のアドレス。IDirectSoundBuffer8 インターフェイスは複製バッファからは取得できない。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DSERR_ALLOCATED
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_OUTOFMEMORY
DSERR_UNINITIALIZED

注意

このメソッドは、DSBCAPS_CTRLFX フラグを使って作成したバッファには無効である。

複製直後のバッファは、オリジナル バッファと同じパラメータを持つ。ただし、アプリケーションは各バッファのパラメータを個別に変更でき、各バッファは違いに影響を及ぼすことなく再生と停止を行える。

後に残った参照側オブジェクトが解放されると、バッファ メモリは解放される。

複製バッファは同じメモリを共有する場合もあるが、常にそうであるとは限らない。バッファに格納されたデータの変更は、必ずしも複製に反映されるわけではない。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSound8::CreateSoundBuffer


IDirectSound8::GetCaps

DirectSound オブジェクトとして表されているハードウェア デバイスの能力を取得する。

HRESULT GetCaps(
  LPDSCAPS pDSCaps
);

パラメータ

pDSCaps
サウンド デバイスの能力を受け取る DSCAPS 構造体のアドレス。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DSERR_GENERIC
DSERR_INVALIDPARAM
DSERR_UNINITIALIZED

注意

DSCAPS 構造体に保持されている情報は、ハードウェア ミキシング チャンネルの数、オンボード サウンド メモリの容量など、サウンド デバイスの最大能力と、現在使用可能な能力を記述する。これらの情報を使って性能を調整し、リソースの割り当てを最適化できる。

リソースの共有が前提となっているため、ある分野で最大の能力を利用すると、ほかの分野がその影響を受けることがある。

動作環境

ヘッダー : dsound.h で宣言。


IDirectSound8::GetSpeakerConfig

スピーカの構成を取得する。

HRESULT GetSpeakerConfig(
  LPDWORD pdwSpeakerConfig
);

パラメータ

pdwSpeakerConfig
この DirectSound オブジェクト用のスピーカの構成へのポインタ。スピーカの構成は次の値のいずれかで指定される。
DSSPEAKER_5POINT1
オーディオはサブウーファ付きのサラウンド スピーカのスピーカ配置から出力される。
DSSPEAKER_HEADPHONE
オーディオはヘッドホンから出力される。
DSSPEAKER_MONO
オーディオはモノラル スピーカから出力される。
DSSPEAKER_QUAD
オーディオは 4 チャンネル ステレオ スピーカから出力される。
DSSPEAKER_STEREO
オーディオはステレオ スピーカから出力される (デフォルト値)。
DSSPEAKER_SURROUND
オーディオはサラウンド スピーカから出力される。
DSSPEAKER_STEREO は、次の値のいずれかと組み合わせて使用できる。
DSSPEAKER_GEOMETRY_WIDE
2 つのスピーカはリスナーを中心として 20 度の角度に置かれている。
DSSPEAKER_GEOMETRY_NARROW
2 つのスピーカはリスナーを中心として 10 度の角度に置かれている。
DSSPEAKER_GEOMETRY_MIN
2 つのスピーカはリスナーを中心として 5 度の角度に置かれている。
DSSPEAKER_GEOMETRY_MAX
2 つのスピーカはリスナーを中心として 180 度の角度に置かれている。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DSERR_INVALIDPARAM
DSERR_UNINITIALIZED

注意

pdwSpeakerConfig に返される値は、構成とジオメトリ情報の両方を保持するパック DWORD となることがある。DWORD をアンパックするには、次の例のように DSSPEAKER_CONFIG と DSSPEAKER_GEOMETRY の各マクロを使う。

if (DSSPEAKER_CONFIG(dwSpeakerConfig) == DSSPEAKER_STEREO)
    {
    if (DSSPEAKER_GEOMETRY(dwSpeakerConfig) ==
                      DSSPEAKER_GEOMETRY_WIDE)
       {...}
    }

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSound8::SetSpeakerConfig、スピーカの構成


IDirectSound8::Initialize

CoCreateInstance 関数を使って作成された DirectSound オブジェクトを初期化する。

HRESULT Initialize(
  LPCGUID pcGuidDevice
);

パラメータ

pcGuidDevice
DirectSound オブジェクトに割り当てられるサウンド ドライバを指定する GUID (グローバル ユニーク識別子) アドレス。プライマリ サウンド ドライバを選択するには、NULL を渡す。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DSERR_ALREADYINITIALIZED
DSERR_GENERIC
DSERR_INVALIDPARAM
DSERR_NODRIVER

注意

このメソッドは COM プロトコルに準拠して提供されている。DirectSoundCreate8 関数を使って DirectSound オブジェクトを作成した場合、このメソッドは DSERR_ALREADYINITIALIZED を返す。CoCreateInstance を使って DirectSound オブジェクトを作成するときに、IDirectSound8::Initialize を呼び出さないと、その後に呼び出したすべてのメソッドは DSERR_UNINITIALIZED を返す。

動作環境

ヘッダー : dsound.h で宣言。


IDirectSound8::SetCooperativeLevel

このサウンド デバイスのアプリケーション協調レベルを設定する。

HRESULT SetCooperativeLevel(
  HWND hwnd,
  DWORD dwLevel
);

パラメータ

hwnd
アプリケーション ウインドウへのハンドル。
dwLevel
要求される優先レベル。次の値のいずれかを指定する。
DSSCL_EXCLUSIVE
DirectX 8.0 以降のバージョンでは、DSSCL_PRIORITY と同じ効果を持つ。それ以前のバージョンでは、アプリケーションを排他レベルに設定する。つまり、入力フォーカスが置かれているアプリケーションだけが音を出せる (DSBCAPS_GLOBALFOCUS フラグが設定されているアプリケーションのサウンドは無音になる)。このレベルに設定されたアプリケーションは、DSSCL_PRIORITY レベルのすべての特権をも備えている。アプリケーションが入力フォーカスを得ると、DirectSound は前回 IDirectSoundBuffer8::SetFormat メソッドを呼び出したときに指定されたハードウェア フォーマットを復元する
DSSCL_NORMAL
アプリケーションを完全に協調可能なステータスに設定する。このレベルでは最もスムーズなマルチタスキングとリソース共有の動作が得られるが、プライマリ バッファのフォーマットの変更は行えず、出力もデフォルトの 8 ビット フォーマットに限定される。
DSSCL_PRIORITY
アプリケーションを優先レベルに設定する。この協調レベルに設定されたアプリケーションは IDirectSoundBuffer8::SetFormat と IDirectSound8::Compact の各メソッドを呼び出せる。
DSSCL_WRITEPRIMARY
これは最上位の優先レベルである。このアプリケーションはプライマリ サウンド バッファへの書き込みアクセスを保持する。セカンダリ サウンド バッファはいずれも再生できない。デバイスが DirectSound ドライバでエミュレートされている場合、つまり IDirectSound8::GetCaps メソッドが DSCAPS 構造体内に DSCAPS_EMULDRIVER フラグを返した場合、このレベルは設定できない。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DSERR_ALLOCATED
DSERR_INVALIDPARAM
DSERR_UNINITIALIZED
DSERR_UNSUPPORTED

注意

アプリケーションはバッファを再生する前に、このメソッドを呼び出して協調レベルを設定しなければならない。推奨される協調レベルは DSSCL_PRIORITY である。詳細については、「協調レベル」を参照すること。

ロックされたバッファがある場合は、このメソッドを使用してはならない。

動作環境

ヘッダー : dsound.h で宣言。


IDirectSound8::SetSpeakerConfig

DirectSound オブジェクトのスピーカの構成を指定する。

アプリケーションでこのメソッドを使用することは勧められない。「スピーカの構成」を参照すること。

HRESULT SetSpeakerConfig(
  DWORD dwSpeakerConfig
);

パラメータ

dwSpeakerConfig
DirectSound オブジェクトのスピーカの構成。このパラメータに、次の値のいずれかを指定する。
DSSPEAKER_5POINT1
オーディオはサブウーファ付きのサラウンド スピーカのスピーカ配置から出力される。
DSSPEAKER_HEADPHONE
スピーカはヘッドホンである。
DSSPEAKER_MONO
スピーカはモノラルである。
DSSPEAKER_QUAD
スピーカは 4 チャンネルである。
DSSPEAKER_STEREO
スピーカはステレオである (デフォルト値)。
DSSPEAKER_SURROUND
スピーカはサラウンド サウンドである。
DSSPEAKER_STEREO は、次の値のいずれかと組み合わせて使用できる。
DSSPEAKER_GEOMETRY_WIDE
2 つのスピーカはリスナーを中心として 20 度の角度に置かれている。
DSSPEAKER_GEOMETRY_NARROW
2 つのスピーカはリスナーを中心として 10 度の角度に置かれている。
DSSPEAKER_GEOMETRY_MIN
2 つのスピーカはリスナーを中心として 5 度の角度に置かれている。
DSSPEAKER_GEOMETRY_MAX
2 つのスピーカはリスナーを中心として 180 度の角度に置かれている。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DSERR_INVALIDPARAM
DSERR_UNINITIALIZED

注意

ジオメトリ値を使うには、DSSPEAKER_STEREO フラグと組み合わせた上で DWORD にパックしなければならない。次の C++ による例に示すように、DSSPEAKER_COMBINED マクロを使ってこのパックを行う。

lpds->SetSpeakerConfig(DSSPEAKER_COMBINED(
    DSSPEAKER_STEREO, DSSPEAKER_GEOMETRY_WIDE));

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSound8::GetSpeakerConfig


IDirectSound8::VerifyCertification

DirectSound デバイスが DirectX で認証されているかどうかを確認する。

VerifyCertification(
  LPDWORD pdwCertified
);

パラメータ

pdwCertified
次のいずれかの値を受け取る DWORD 変数のアドレス。
DS_CERTIFIED
ドライバは DirectSound で認証されている。
DS_UNCERTIFIED
ドライバは DirectSound で認証されていない。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DSERR_INVALIDPARAM
DSERR_UNSUPPORTED

注意

エミュレートされるデバイスでは、このメソッドは DSERR_UNSUPPORTED を返す。エミュレートされるデバイスは、DSCAPS の dwFlags メンバの DSCAPS_EMULDRIVER フラグで識別される。

動作環境

ヘッダー : dsound.h で宣言。


IDirectSound3DBuffer8

3D 空間におけるサウンド バッファの位置、向き、および環境を記述するパラメータの取得と設定に使用する。

IDirectSound3DBuffer8 は、IDirectSoundBuffer の定義である。2 つのインターフェイス名は入れ替え可能である。

IDirectSound3DBuffer8 インターフェイスは、IDirectSoundBuffer8:: QueryInterface メソッドを使って IDirectSoundBuffer8 インターフェイスから取得する。オーディオパスから取得することもできる。

IDirectSound3DBuffer8 インターフェイスのメソッドは、次のグループにまとめることができる。

バッチ パラメータ操作 | GetAllParameters
 | SetAllParameters
距離 | GetMaxDistance
 | GetMinDistance
 | SetMaxDistance
 | SetMinDistance
操作モード | GetMode
 | SetMode
位置 | GetPosition
 | SetPosition
サウンド プロジェクション コーン | GetConeAngles
 | GetConeOrientation
 | GetConeOutsideVolume
 | SetConeAngles
 | SetConeOrientation
 | SetConeOutsideVolume
速度 | GetVelocity
 | SetVelocity

すべての COM インターフェイスと同様、IDirectSound3DBuffer8 インターフェイスは IUuknown インターフェイス メソッドを継承している。IUnknown インターフェイスは次の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTSOUND3DBUFFER 型は、IDirectSound3DBuffer8 インターフェイスへのポインタとして定義されている。

typedef struct IDirectSound3DBuffer    *LPDIRECTSOUND3DBUFFER;

動作環境

ヘッダー : dsound.h で宣言。

参照

3D バッファ オブジェクトの取得、オーディオパスからのオブジェクトの取得


IDirectSound3DBuffer8::GetAllParameters

指定した時点でのサウンド バッファの 3D 特性に関する情報を取得する。

HRESULT GetAllParameters(
  LPDS3DBUFFER pDs3dBuffer
);

パラメータ

pDs3dBuffer
DS3DBUFFER 構造体のアドレス。この構造体はサウンド バッファの 3D 特性に関する情報を受け取る。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

動作環境

ヘッダー : dsound.h で宣言。


IDirectSound3DBuffer8::GetConeAngles

サウンド バッファのサウンド プロジェクション コーンの内部角度と外部角度を取得する。

HRESULT GetConeAngles(
  LPDWORD pdwInsideConeAngle,
  LPDWORD pdwOutsideConeAngle
);

パラメータ

pdwInsideConeAngle
サウンド プロジェクション コーンの内部角度を受け取る変数のアドレス (度単位)。この角度の内側では、サウンドは通常のボリュームである。
pdwOutsideConeAngle
サウンド プロジェクション コーンの外部角度を受け取る変数のアドレス (度単位)。この角度の外側では、サウンドは外部ボリュームである。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

注意

最小、最大、デフォルトの各コーン角度は dsound.h 内でそれぞれ DS3D_MINCONEANGLE、DS3D_MAXCONEANGLE、DS3D_DEFAULTCONEANGLE として定義される。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSound3DBuffer8::GetConeOutsideVolume、IDirectSound3DBuffer8::SetConeOutsideVolume、IDirectSound3DBuffer8::GetConeOrientation、IDirectSound3DBuffer8::SetConeOrientation


IDirectSound3DBuffer8::GetConeOrientation

サウンド バッファのサウンド プロジェクション コーンの向きを取得する。

HRESULT GetConeOrientation(
  D3DVECTOR * pvOrientation
);

パラメータ

pvOrientation
D3DVECTOR 構造体のアドレス。この構造体は、サウンド プロジェクション コーンの向きを受け取る。ベクトル情報はサウンド コーンの中心を表す。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

注意

戻り値は必ずしも IDirectSound3DBuffer8::SetConeOrientation メソッドを使って設定したのと同じ値ではない。DirectSound は向きベクトルに調整を加え、それらのマグニチュードを 1.0 以下にする。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSound3DBuffer8::SetConeOrientation、IDirectSound3DBuffer8::SetConeAngles、IDirectSound3DBuffer8::SetConeOutsideVolume


IDirectSound3DBuffer8::GetConeOutsideVolume

サウンド バッファのコーン外部ボリュームを取得する。

HRESULT GetConeOutsideVolume(
  LPLONG plConeOutsideVolume
);

パラメータ

plConeOutsideVolume
バッファのコーン外部ボリュームを受け取る変数のアドレス。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

注意

ボリューム レベルは減衰によって表される。許容される値は DSBVOLUME_MAX (減衰なし) と DSBVOLUME_MIN (無音) の間である。デフォルト値は DS3D_DEFAULTCONEOUTSIDEVOLUME (減衰なし) である。これらの値は dsound.h 内で定義されている。現在 DirectSound は増幅をサポートしていない。

コーン外部ボリュームの概念については、「サウンド コーン」を参照すること。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSound3DBuffer8::SetConeOutsideVolume、IDirectSound3DBuffer8::GetConeOrientation、IDirectSound3DBuffer8::SetConeOrientation


IDirectSound3DBuffer8::GetMaxDistance

サウンド バッファの最大距離を取得する。

HRESULT GetMaxDistance(
  D3DVALUE * pflMaxDistance
);

パラメータ

pflMaxDistance
最大距離の設定を受け取る変数のアドレス。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

注意

デフォルトの最大距離は DS3D_DEFAULTMAXDISTANCE によって定義され、実質的に無限大である。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSound3DBuffer8::GetMinDistance、IDirectSound3DBuffer8::SetMaxDistance


IDirectSound3DBuffer8::GetMinDistance

サウンド バッファの最小距離を取得する。

HRESULT GetMinDistance(
  D3DVALUE * pflMinDistance
);

パラメータ

pflMinDistance
最小距離の設定を受け取る変数のアドレス。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

注意

デフォルトでは、最小距離値は DS3D_DEFAULTMINDISTANCE であり、現在は 1.0 と定義されている (デフォルトの距離係数 1.0 を使った場合は、1 単位は 1.0 メートルに相当する)。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSound3DBuffer8::SetMinDistance、IDirectSound3DBuffer8::GetMaxDistance


IDirectSound3DBuffer8::GetMode

3D サウンド処理の操作モードを取得する。

HRESULT GetMode(
  LPDWORD pdwMode
);

パラメータ

pdwMode
モード設定を受け取る変数のアドレス。次の値のいずれかが返される。
DS3DMODE_DISABLE
3D サウンド処理は無効になる。サウンドはリスナーの頭の中心で発生しているように聞こえる。
DS3DMODE_HEADRELATIVE
サウンド パラメータ (位置、速度、向き) はリスナーのパラメータに対する相対的なものである。このモードでは、リスナーのパラメータが変化したときにサウンドの絶対パラメータは自動的に更新されるので、相対パラメータは一定に保たれる。
DS3DMODE_NORMAL
標準の処理。これはデフォルトのモードである。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

動作環境

ヘッダー : dsound.h で宣言。


IDirectSound3DBuffer8::GetPosition

サウンド バッファの位置を距離単位で取得する。距離のデフォルトの単位はメートルであるが、IDirectSound3DListener8::SetDistanceFactor メソッドを使って変更できる。

HRESULT GetPosition(
  D3DVECTOR * pvPosition
);

パラメータ

pvPosition
D3DVECTOR 構造体のアドレス。この構造体は、サウンド バッファの位置を受け取る。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

動作環境

ヘッダー : dsound.h で宣言。


IDirectSound3DBuffer8::GetVelocity

サウンド バッファの速度を取得する。速度は、秒速単位で計測される。デフォルトの単位はメートル/秒であるが、IDirectSound3DListener8::SetDistanceFactor メソッドを使って変更できる。

HRESULT GetVelocity(
  D3DVECTOR * pvVelocity
);

パラメータ

pvVelocity
D3DVECTOR 構造体のアドレス。この構造体はサウンド バッファの速度を受け取る。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

注意

速度はドップラー効果でのみ使われる。実際にバッファを移動することはない。詳細については、「ドップラー係数」を参照すること。

デフォルトの計測単位はメートル/秒であるが、IDirectSound3DListener8::SetDistanceFactor メソッドを使用して変更できる。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSound3DBuffer8::SetPosition、IDirectSound3DBuffer8::SetVelocity


IDirectSound3DBuffer8::SetAllParameters

3D サウンド バッファのパラメータをすべて設定する。

HRESULT SetAllParameters(
  LPCDS3DBUFFER pcDs3dBuffer,
  DWORD dwApply
);

パラメータ

pcDs3dBuffer
DS3DBUFFER 構造体のアドレス。この構造体はサウンド バッファの 3D 特性を記述する。
dwApply
設定が適用されるタイミングを指定する値。次の値のいずれかでなければならない。
DS3D_DEFERRED
アプリケーションが IDirectSound3DListener8::CommitDeferredSettings メソッドを呼び出すまで設定は適用されない。アプリケーションは複数の設定を変更した後、1 回の再計算でそれらを適用できる。
DS3D_IMMEDIATE
設定を即時に適用し、システムはすべての 3D サウンド バッファの 3D 座標を再計算する。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

動作環境

ヘッダー : dsound.h で宣言。


IDirectSound3DBuffer8::SetConeAngles

サウンド バッファのサウンド プロジェクション コーンの内部角度と外部角度を設定する。

HRESULT SetConeAngles(
  DWORD dwInsideConeAngle,
  DWORD dwOutsideConeAngle,
  DWORD dwApply
);

パラメータ

dwInsideConeAngle
コーンの内部角度を指定する値 (度単位)。この角度の内側では、サウンドは通常のボリュームである。
dwOutsideConeAngle
コーンの外部角度を指定する値 (度単位)。この角度の外側では、サウンドは外部ボリュームである。
dwApply
設定が適用されるタイミングを示す値。次の値のいずれかでなければならない。
DS3D_DEFERRED
アプリケーションが IDirectSound3DListener8::CommitDeferredSettings メソッドを呼び出すまで設定は適用されない。アプリケーションは複数の設定を変更した後、1 回の再計算でそれらを適用できる。
DS3D_IMMEDIATE
設定を即時に適用し、システムはすべての 3D サウンド バッファの 3D 座標を再計算する。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

注意

最小、最大、デフォルトの各コーン角度は dsound.h 内でそれぞれ DS3D_MINCONEANGLE、DS3D_MAXCONEANGLE、DS3D_DEFAULTCONEANGLE として定義される。各角度の範囲は、0° (コーンなし) から 360° (全範囲) までである。デフォルト値は 360 である。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSound3DBuffer8::SetConeOutsideVolume、IDirectSound3DBuffer8::SetConeOrientation


IDirectSound3DBuffer8::SetConeOrientation

サウンド バッファのサウンド プロジェクション コーンの向きを設定する。コーン角度とコーン ボリューム係数が既に設定されていない限り、このメソッドは何もしない。

HRESULT SetConeOrientation(
  D3DVALUE x,
  D3DVALUE y,
  D3DVALUE z,
  DWORD dwApply
);

パラメータ

x、y、および z
サウンド コーンの向きベクトルの座標を指定する値。
dwApply
設定が適用されるタイミングを指定する値。次の値のいずれかでなければならない。
DS3D_DEFERRED
アプリケーションが IDirectSound3DListener8::CommitDeferredSettings メソッドを呼び出すまで設定は適用されない。アプリケーションは複数の設定を変更した後、1 回の再計算でそれらを適用できる。
DS3D_IMMEDIATE
設定を即時に適用し、システムはすべての 3D サウンド バッファの 3D 座標を再計算する。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSound3DBuffer8::SetConeAngles、IDirectSound3DBuffer8::SetConeOutsideVolume


IDirectSound3DBuffer8::SetConeOutsideVolume

サウンド バッファのコーン外部ボリュームを設定する。

HRESULT SetConeOutsideVolume(
  LONG lConeOutsideVolume,
  DWORD dwApply
);

パラメータ

lConeOutsideVolume
サウンド バッファのコーン外部ボリュームを 100 分の 1 デシベル (dB) の単位で指定する。許容される値は DSBVOLUME_MAX (減衰なし) と DSBVOLUME_MIN (無音) の間である。これらの値は dsound.h 内で定義されている。
dwApply
設定が適用されるタイミングを指定する値。次の値のいずれかでなければならない。
DS3D_DEFERRED
アプリケーションが IDirectSound3DListener8::CommitDeferredSettings メソッドを呼び出すまで設定は適用されない。アプリケーションは複数の設定を変更した後、1 回の再計算でそれらを適用できる。
DS3D_IMMEDIATE
設定を即時に適用し、システムはすべての 3D サウンド バッファの 3D 座標を再計算する。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

注意

ボリューム レベルは減衰によって表される。許容される値は DSBVOLUME_MAX (減衰なし) と DSBVOLUME_MIN (無音) の間である。デフォルト値は DS3D_DEFAULTCONEOUTSIDEVOLUME (減衰なし) である。これらの値は dsound.h 内で定義されている。現在 DirectSound は増幅をサポートしていない。

コーン外部ボリュームの概念については、「サウンド コーン」を参照すること。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSound3DBuffer8::SetConeAngles、IDirectSound3DBuffer8::SetConeOrientation、IDirectSoundBuffer8::SetVolume


IDirectSound3DBuffer8::SetMaxDistance

最大距離値を設定する。

HRESULT SetMaxDistance(
  D3DVALUE flMaxDistance,
  DWORD dwApply
);

パラメータ

flMaxDistance
新しい最大距離値。
dwApply
設定が適用されるタイミングを指定する値。次の値のいずれかでなければならない。
DS3D_DEFERRED
アプリケーションが IDirectSound3DListener8::CommitDeferredSettings メソッドを呼び出すまで設定は適用されない。アプリケーションは複数の設定を変更した後、1 回の再計算でそれらを適用できる。
DS3D_IMMEDIATE
設定を即時に適用し、システムはすべての 3D サウンド バッファの 3D 座標を再計算する。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

注意

デフォルトの最大距離は DS3D_DEFAULTMAXDISTANCE によって定義され、実質的に無限大である。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSound3DBuffer8::GetMaxDistance、IDirectSound3DBuffer8::SetMinDistance


IDirectSound3DBuffer8::SetMinDistance

最小距離値を設定する。

HRESULT SetMinDistance(
  D3DVALUE flMinDistance,
  DWORD dwApply
);

パラメータ

flMinDistance
新しい最小距離値。
dwApply
設定が適用されるタイミングを指定する値。次の値のいずれかでなければならない。
DS3D_DEFERRED
アプリケーションが IDirectSound3DListener8::CommitDeferredSettings メソッドを呼び出すまで設定は適用されない。アプリケーションは複数の設定を変更した後、1 回の再計算でそれらを適用できる。
DS3D_IMMEDIATE
設定を即時に適用し、システムはすべての 3D サウンド バッファの 3D 座標を再計算する。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

注意

デフォルトでは、最小距離値は DS3D_DEFAULTMINDISTANCE であり、現在は 1.0 と定義されている (デフォルトの距離係数 1.0 を使った場合は、1 単位は 1.0 メートルに相当する)。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSound3DBuffer8::SetMaxDistance


IDirectSound3DBuffer8::SetMode

3D サウンド処理の操作モードを設定する。

HRESULT SetMode(
  DWORD dwMode,
  DWORD dwApply
);

パラメータ

dwMode
設定される 3D サウンド処理モードを指定するフラグ。
DS3DMODE_DISABLE
3D サウンド処理は無効になる。サウンドはリスナーの頭の中心で発生しているように聞こえる。
DS3DMODE_HEADRELATIVE
サウンド パラメータ (位置、速度、向き) はリスナーのパラメータに対する相対的なものである。このモードでは、リスナーのパラメータが変化したときにサウンドの絶対パラメータは自動的に更新されるので、相対パラメータは一定に保たれる。
DS3DMODE_NORMAL
標準の処理。これはデフォルトのモードである。
dwApply
設定が適用されるタイミングを指定する値。次の値のいずれかでなければならない。
DS3D_DEFERRED
アプリケーションが IDirectSound3DListener8::CommitDeferredSettings メソッドを呼び出すまで設定は適用されない。アプリケーションは複数の設定を変更した後、1 回の再計算でそれらを適用できる。
DS3D_IMMEDIATE
設定を即時に適用し、システムはすべての 3D サウンド バッファの 3D 座標を再計算する。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

動作環境

ヘッダー : dsound.h で宣言。


IDirectSound3DBuffer8::SetPosition

サウンド バッファの位置を距離単位で設定する。距離のデフォルトの単位はメートルであるが、IDirectSound3DListener8::SetDistanceFactor メソッドを使って変更できる。

HRESULT SetPosition(
  D3DVALUE x,
  D3DVALUE y,
  D3DVALUE z,
  DWORD dwApply
);

パラメータ

x、y、および z
位置ベクトルの座標を指定する値。浮動小数点のオーバーフローを防ぐために、DirectSound でこれらの値が調整される場合がある。
dwApply
設定が適用されるタイミングを指定する値。次の値のいずれかでなければならない。
DS3D_DEFERRED
アプリケーションが IDirectSound3DListener8::CommitDeferredSettings メソッドを呼び出すまで設定は適用されない。アプリケーションは複数の設定を変更した後、1 回の再計算でそれらを適用できる。
DS3D_IMMEDIATE
設定を即時に適用し、システムはすべての 3D サウンド バッファの 3D 座標を再計算する。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

動作環境

ヘッダー : dsound.h で宣言。


IDirectSound3DBuffer8::SetVelocity

音源の速度を設定する。

HRESULT SetVelocity(
  D3DVALUE x,
  D3DVALUE y,
  D3DVALUE z,
  DWORD dwApply
);

パラメータ

x、y、および z
速度ベクトルの座標を指定する値。浮動小数点のオーバーフローを防ぐために、DirectSound でこれらの値が調整される場合がある。
dwApply
設定が適用されるタイミングを指定する値。次の値のいずれかでなければならない。
DS3D_DEFERRED
アプリケーションが IDirectSound3DListener8::CommitDeferredSettings メソッドを呼び出すまで設定は適用されない。アプリケーションは複数の設定を変更した後、1 回の再計算でそれらを適用できる。
DS3D_IMMEDIATE
設定を即時に適用し、システムはすべての 3D サウンド バッファの 3D 座標を再計算する。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

注意

速度はドップラー効果でのみ使用される。バッファの位置を変更することはない。詳細については、「ドップラー係数」を参照すること。

デフォルトの計測単位はメートル/秒であるが、IDirectSound3DListener8::SetDistanceFactor メソッドを使用して変更できる。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSound3DBuffer8::SetPosition、IDirectSound3DBuffer8::GetVelocity


IDirectSound3DListener8

3D 空間におけるリスナーの位置、向き、および環境を記述するパラメータの取得と設定に使用する。

インターフェイスは、DSBCAPS_CTRL3D フラグで作成されたプライマリ バッファで、IDirectSoundBuffer8:: QueryInterface メソッドを呼び出すことで取得できる。オーディオパスを使用するアプリケーションは、次のサンプル コードに示すように、オーディオパスからインターフェイスを取得できる。pAudiopath は IDirectMusicAudioPath8 インターフェイス ポインタである。

IDirectSound3DListener8 *pListener;

pAudioPath->GetObjectInPath(0, DMUS_PATH_PRIMARY_BUFFER,
        0, GUID_All_Objects, 0, IID_IDirectSound3DListener,
        (void **)&pListener)));

IDirectSound3DListener8 インターフェイスのメソッドは、次のグループにまとめることができる。

バッチ パラメータ操作 | GetAllParameters
 | SetAllParameters
遅延設定 | CommitDeferredSettings
距離係数 | GetDistanceFactor
 | SetDistanceFactor
ドップラー係数 | GetDopplerFactor
 | SetDopplerFactor
方向 | GetOrientation
 | SetOrientation
位置 | GetPosition
 | SetPosition
ロールオフ係数 | GetRolloffFactor
 | SetRolloffFactor
速度 | GetVelocity
 | SetVelocity

すべての COM インターフェイスと同様、IDirectSound3DListener8 インターフェイスは IUuknown インターフェイス メソッドを継承している。IUnknown インターフェイスは次の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTSOUND3DLISTENER 型は、IDirectSound3DListener インターフェイスへのポインタとして定義されている。

typedef struct IDirectSound3DListener    *LPDIRECTSOUND3DLISTENER;

動作環境

ヘッダー : dsound.h で宣言。


IDirectSound3DListener8::CommitDeferredSettings

前回このメソッドを呼び出した後に行われた遅延設定をコミットする。

HRESULT CommitDeferredSettings();

パラメータ

なし。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

注意

最大の効率をもたらす遅延設定の使い方については、「遅延設定」を参照すること。

動作環境

ヘッダー : dsound.h で宣言。


IDirectSound3DListener8::GetAllParameters

3D ワールドとリスナーの状態を取得する。

HRESULT GetAllParameters(
  LPDS3DLISTENER pListener
);

パラメータ

pListener
DS3DLISTENER 構造体のアドレス。この構造体は 3D ワールドとリスナーの状態を受け取る。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSound3DListener8::SetAllParameters


IDirectSound3DListener8::GetDistanceFactor

ベクトル単位のメートル数で距離係数を取得する。

HRESULT GetDistanceFactor(
  D3DVALUE * pflDistanceFactor
);

パラメータ

pflDistanceFactor
距離係数の値を受け取る変数のアドレス。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSound3DListener8::SetDistanceFactor、距離係数


IDirectSound3DListener8::GetDopplerFactor

ドップラー効果係数を取得する。

HRESULT GetDopplerFactor(
  D3DVALUE * pflDopplerFactor
);

パラメータ

pflDopplerFactor
ドップラー係数の値を受け取る変数のアドレス。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

注意

ドップラー係数の範囲は、DS3D_MINDOPPLERFACTOR (ドップラー効果なし) から DS3D_MAXDOPPLERFACTOR (現在の定義では実世界の 10 倍のドップラー効果) までである。デフォルト値は DS3D_DEFAULTDOPPLERFACTOR (1.0) である。詳細については、「ドップラー係数」を参照すること。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSound3DListener8::SetDopplerFactor


IDirectSound3DListener8::GetOrientation

リスナーの向きをベクトル (前方ベクトルと上方ベクトル) で取得する。

HRESULT GetOrientation(
  D3DVECTOR * pvOrientFront,
  D3DVECTOR * pvOrientTop
);

パラメータ

pvOrientFront
D3DVECTOR 構造体のアドレス。この構造体はリスナーの前方ベクトルを受け取る。
pvOrientTop
D3DVECTOR 構造体のアドレス。この構造体はリスナーの上方ベクトルを受け取る。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

注意

前方ベクトルはリスナーの鼻の方向、上方ベクトルはリスナーの頭頂部の方向を指す。デフォルトでは、前方ベクトルは (0, 0, 1.0)、上方ベクトルは (0, 1.0, 0) である。

戻り値は必ずしも IDirectSound3DListener8::SetOrientation メソッドを使って設定したのと同じ値ではない。DirectSound は向きベクトルに調整を加えて、それらが互いに直交するようにし、両方のマグニチュードを 1.0 以下にする。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSound3DListener8::SetOrientation


IDirectSound3DListener8::GetPosition

リスナーの位置を距離単位で取得する。これらの単位のデフォルトはメートルであるが、IDirectSound3DListener8::SetDistanceFactor メソッドを呼び出して変更できる。

HRESULT GetPosition(
  D3DVECTOR * pvPosition
);

パラメータ

pvPosition
D3DVECTOR 構造体のアドレス。この構造体はリスナーの位置ベクトルを受け取る。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSound3DListener8::SetPosition


IDirectSound3DListener8::GetRolloffFactor

距離に応じた減衰率を決定するロールオフ係数を取得する。

HRESULT GetRolloffFactor(
  D3DVALUE * pflRolloffFactor
);

パラメータ

pflRolloffFactor
ロールオフ係数を受け取る変数のアドレス。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

注意

ロールオフ係数は、DS3D_MINROLLOFFFACTOR (ロールオフなし) から DS3D_MAXROLLOFFFACTOR (現在の定義では実世界の 10 倍) までの範囲をとる。デフォルト値は DS3D_DEFAULTROLLOFFFACTOR (1.0) である。詳細については、「ロールオフ係数」を参照すること。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSound3DListener8::SetRolloffFactor


IDirectSound3DListener8::GetVelocity

リスナーの速度を取得する。

HRESULT GetVelocity(
  D3DVECTOR * pvVelocity
);

パラメータ

pvVelocity
D3DVECTOR 構造体のアドレス。この構造体はリスナーの速度を受け取る。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

注意

速度はドップラー効果でのみ使用される。リスナーの位置を変更することはない。リスナーの位置を変更するには IDirectSound3DListener8::SetPosition メソッドを使う。

デフォルトの速度は (0,0,0) である。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSound3DListener8::SetVelocity


IDirectSound3DListener8::SetAllParameters

DS3DLISTENER 構造体で指定した、すべての 3D リスナー パラメータを設定する。この構造体はある瞬間のリスナーのすべての状態を記述する。

HRESULT SetAllParameters(
  LPCDS3DLISTENER pcListener,
  DWORD dwApply
);

パラメータ

pcListener
DS3DLISTENER 構造体のアドレス。この構造体は 3D リスナーのすべてのパラメータ情報を保持する。
dwApply
設定が適用されるタイミングを指定する値。次の値のいずれかでなければならない。
DS3D_DEFERRED
アプリケーションが IDirectSound3DListener8::CommitDeferredSettings メソッドを呼び出すまで設定は適用されない。アプリケーションは複数の設定を変更した後、1 回の再計算でそれらを適用できる。
DS3D_IMMEDIATE
設定を即時に適用し、システムはすべての 3D サウンド バッファの 3D 座標を再計算する。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSound3DListener8::GetAllParameters


IDirectSound3DListener8::SetDistanceFactor

ベクトル単位のメートル数で距離係数を設定する。

HRESULT SetDistanceFactor(
  D3DVALUE flDistanceFactor,
  DWORD dwApply
);

パラメータ

flDistanceFactor
距離係数を指定する値。
dwApply
設定が適用されるタイミングを指定する値。次の値のいずれかでなければならない。
DS3D_DEFERRED
アプリケーションが IDirectSound3DListener8::CommitDeferredSettings メソッドを呼び出すまで設定は適用されない。アプリケーションは複数の設定を変更した後、1 回の再計算でそれらを適用できる。
DS3D_IMMEDIATE
設定を即時に適用し、システムはすべての 3D サウンド バッファの 3D 座標を再計算する。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

注意

距離係数の範囲は、DS3D_MINDISTANCEFACTOR から DS3D_MAXDISTANCEFACTOR までである。dsound.h では、それぞれ FLT_MIN および FLT_MAX として定義されている。デフォルト値は、DS3D_DEFAULTDISTANCEFACTOR または 1.0 である。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSound3DListener8::GetDistanceFactor、距離係数


IDirectSound3DListener8::SetDopplerFactor

ドップラー効果係数を設定する。

HRESULT SetDopplerFactor(
  D3DVALUE flDopplerFactor,
  DWORD dwApply
);

パラメータ

flDopplerFactor
ドップラー係数を指定する値。
dwApply
設定が適用されるタイミングを指定する値。次の値のいずれかでなければならない。
DS3D_DEFERRED
アプリケーションが IDirectSound3DListener8::CommitDeferredSettings メソッドを呼び出すまで設定は適用されない。アプリケーションは複数の設定を変更した後、1 回の再計算でそれらを適用できる。
DS3D_IMMEDIATE
設定を即時に適用し、システムはすべての 3D サウンド バッファの 3D 座標を再計算する。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

注意

ドップラー係数の範囲は、DS3D_MINDOPPLERFACTOR (ドップラー効果なし) から DS3D_MAXDOPPLERFACTOR (現在の定義では実世界の 10 倍のドップラー効果) までである。デフォルト値は DS3D_DEFAULTDOPPLERFACTOR (1.0) である。詳細については、「ドップラー係数」を参照すること。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSound3DListener8::GetDopplerFactor


IDirectSound3DListener8::SetOrientation

2 つのベクトル (前方ベクトルと上方ベクトル) により、リスナーの向きを設定する。

HRESULT SetOrientation(
  D3DVALUE xFront,
  D3DVALUE yFront,
  D3DVALUE zFront,
  D3DVALUE xTop,
  D3DVALUE yTop,
  D3DVALUE zTop,
  DWORD    dwApply
);

パラメータ

xFront、yFront、zFront
前方ベクトルの座標を指定する値。
xTop、yTop、zTop
上方ベクトルの座標を指定する値。
dwApply
設定が適用されるタイミングを指定する値。次の値のいずれかでなければならない。
DS3D_DEFERRED
アプリケーションが IDirectSound3DListener8::CommitDeferredSettings メソッドを呼び出すまで設定は適用されない。アプリケーションは複数の設定を変更した後、1 回の再計算でそれらを適用できる。
DS3D_IMMEDIATE
設定を即時に適用し、システムはすべての 3D サウンド バッファの 3D 座標を再計算する。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

注意

前方ベクトルはリスナーの鼻の方向、上方ベクトルはリスナーの頭頂部の方向を指す。デフォルトでは、前方ベクトルは (0, 0, 1.0)、上方ベクトルは (0, 1.0, 0) である。

上方ベクトルは前方ベクトルに対して直角でなければならない。必要に応じて、DirectSound は前方ベクトルを設定した後で上方ベクトルを調整する。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSound3DListener8::GetOrientation


IDirectSound3DListener8::SetPosition

リスナーの位置を距離単位で設定する。これらの単位のデフォルトはメートルであるが、IDirectSound3DListener8::SetDistanceFactor メソッドを呼び出して変更できる。

HRESULT SetPosition(
  D3DVALUE x,
  D3DVALUE y,
  D3DVALUE z,
  DWORD dwApply
);

パラメータ

x、y、および z
リスナーの位置ベクトルの座標を指定する値。浮動小数点のオーバーフローを防止するために、DirectSound がこれらの値に調整を加える可能性がある点に注意すること。
dwApply
設定が適用されるタイミングを指定する値。次の値のいずれかでなければならない。
DS3D_DEFERRED
アプリケーションが IDirectSound3DListener8::CommitDeferredSettings メソッドを呼び出すまで設定は適用されない。アプリケーションは複数の設定を変更した後、1 回の再計算でそれらを適用できる。
DS3D_IMMEDIATE
設定を即時に適用し、システムはすべての 3D サウンド バッファの 3D 座標を再計算する。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSound3DListener8::GetPosition


IDirectSound3DListener8::SetRolloffFactor

距離に応じた減衰率を決定するロールオフ係数を設定する。

HRESULT SetRolloffFactor(
  D3DVALUE flRolloffFactor,
  DWORD dwApply
);

パラメータ

flRolloffFactor
ロールオフ係数を指定する値。
dwApply
設定が適用されるタイミングを指定する値。次の値のいずれかでなければならない。
DS3D_DEFERRED
アプリケーションが IDirectSound3DListener8::CommitDeferredSettings メソッドを呼び出すまで設定は適用されない。アプリケーションは複数の設定を変更した後、1 回の再計算でそれらを適用できる。
DS3D_IMMEDIATE
設定を即時に適用し、システムはすべての 3D サウンド バッファの 3D 座標を再計算する。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

注意

ロールオフ係数は、DS3D_MINROLLOFFFACTOR (ロールオフなし) から DS3D_MAXROLLOFFFACTOR (現在の定義では実世界の 10 倍) までの範囲をとる。デフォルト値は DS3D_DEFAULTROLLOFFFACTOR (1.0) である。詳細については、「ロールオフ係数」を参照すること。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSound3DListener8::GetRolloffFactor


IDirectSound3DListener8::SetVelocity

リスナーの速度を設定する。

HRESULT SetVelocity(
  D3DVALUE x,
  D3DVALUE y,
  D3DVALUE z,
  DWORD dwApply
);

パラメータ

x、y、および z
リスナーの速度ベクトルの座標を指定する値。浮動小数点のオーバーフローを防ぐために、DirectSound でこれらの値が調整される場合がある。
dwApply
設定が適用されるタイミングを指定する値。次の値のいずれかでなければならない。
DS3D_DEFERRED
アプリケーションが IDirectSound3DListener8::CommitDeferredSettings メソッドを呼び出すまで設定は適用されない。アプリケーションは複数の設定を変更した後、1 回の再計算でそれらを適用できる。
DS3D_IMMEDIATE
設定を即時に適用し、システムはすべての 3D サウンド バッファの 3D 座標を再計算する。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

注意

速度はドップラー効果でのみ使われる。実際にリスナーを移動することはない。リスナーの位置を変更するには IDirectSound3DListener8::SetPosition メソッドを使う。デフォルトの速度は (0,0,0) である。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSound3DListener8::GetVelocity


IDirectSoundBuffer8

サウンド バッファの管理に使用する。

IDirectSoundBuffer に代わって IDirectSoundBuffer8 インターフェイスが提供され、新しいメソッドが追加されている。

インターフェイスを取得するには、IDirectSound8::CreateSoundBuffer メソッドを使って IDirectSoundBuffer を取得し、IID_IDirectSoundBuffer8 を IDirectSoundBuffer::QueryInterface に渡す。

プライマリ サウンド バッファには、IDirectSoundBuffer インターフェイスを使用する必要がある。IDirectSoundBuffer8 は利用できない。IDirectSoundBuffer の独立した説明項目はない。説明は、対応する IDirectSoundBuffer8 メソッドを参照すること。

IDirectSoundBuffer のすべてのメソッドが、プライマリ バッファで有効であるわけではない。たとえば、SetCurrentPosition は失敗する。各メソッドについては、リファレンスのトピックを参照すること。

IDirectSoundBuffer8 インターフェイスのメソッドは、次のグループにまとめることができる。

エフェクト | GetObjectInPath
 | SetFX
情報 | GetCaps
 | GetFormat
 | GetStatus
 | SetFormat
メモリ管理 | AcquireResources
 | Initialize
 | Restore
演奏管理 | GetCurrentPosition
 | Lock
 | Play
 | SetCurrentPosition
 | Stop
 | Unlock
サウンド管理 | GetFrequency
 | GetPan
 | GetVolume
 | SetFrequency
 | SetPan
 | SetVolume

すべての COM インターフェイスは、IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは次の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

次の表は、オーディオパスから取得したバッファ オブジェクト、つまり、DirectMusic パフォーマンスで作成されたバッファでサポートされるメソッドを示している。ミックスイン バッファはその他のバッファからのセンドを受け取る。オーディオパスのほかのバッファはすべて、シンクイン バッファである。これらのバッファは、シンセサイザ シンクからだけデータを受け入れる。

IDirectSoundBuffer8 メソッド | ミックスイン | シンクイン
AcquireResources |  |
GetCaps | あり | あり
GetCurrentPosition |  |
GetFormat | あり | あり
GetFrequency |  |
GetObjectInPath | あり | あり
GetPan | あり | あり
GetStatus | あり | あり
GetVolume | あり | あり
Initialize |  |
Lock
Play | あり
Restore |
SetCurrentPosition
SetFormat
SetFrequency
SetFX | あり | あり
SetPan | あり | あり
SetVolume | あり | あり
Stop | あり |
Unlock |

LPDIRECTSOUNDBUFFER8 型は、IDirectSoundBuffer インターフェイスへのポインタとして定義されている。

typedef struct IDirectSoundBuffer8    *LPDIRECTSOUNDBUFFER8;

動作環境

ヘッダー : dsound.h で宣言。


IDirectSoundBuffer8::AcquireResources

DSBUFFERDESC 構造体の DSBCAPS_LOCDEFER フラグを使って作成したバッファにリソースを割り当てる。

HRESULT AcquireResources(
  DWORD dwFlags,
  DWORD dwEffectsCount,
  LPDWORD pdwResultCodes
);

パラメータ

dwFlags
DSBCAPS_LOCDEFER フラグを使って作成したバッファにリソースを割り当てる方法を指定するフラグ。値のリストについては、IDirectSoundBuffer8::Play のボイス管理フラグおよびボイス割り当てフラグを参照すること。
dwEffectsCount
pdwResultFlags 配列の要素の数を指定する値。pdwResultCodes が NULL の場合は 0 を指定する。
pdwResultCodes
DWORD 変数の配列のアドレス。この配列は、バッファに関連付けられたエフェクトに関する情報を受け取る。この配列には、IDirectSoundBuffer8::SetFX によってバッファに割り当てられたエフェクトそれぞれに対して、1 つの要素が含まれなければならない。各エフェクトに対して、次のいずれかの値が返される。
DSFXR_LOCHARDWARE
エフェクトはハードウェアでインスタンス化される。
DSFXR_LOCSOFTWARE
エフェクトはソフトウェアでインスタンス化される。
DSFXR_FAILED
リソースを利用できなかったため、エフェクトは作成されていない。
DSFXR_PRESENT
エフェクトは利用できるが、ほかの原因でメソッドが失敗したので、作成されていない。
DSFXR_UNKNOWN
エフェクトがシステムに登録されていないため、エフェクトは作成されていない。

結果コードが必要でない場合、このパラメータは NULL にする。

戻り値

成功した場合は、DS_OK または DS_INCOMPLETE を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DSERR_CONTROLUNAVAIL
DSERR_INVALIDCALL
DSERR_INVALIDPARAM

注意

通常、DSBCAPS_LOCDEFER で作成されたバッファは、IDirectSoundBuffer8::Play が呼び出されるまでリソースに割り当てられない。遅延バッファにリソースを割り当てるには、IDirectSoundBuffer8::AcquireResources を使う。これによって、アプリケーションは、エフェクトの処理に関する情報を取得して、バッファが演奏される前にエフェクト パラメータを設定できる。

メソッドが失敗した場合は、pdwResultCodes の値を調べて、失敗の原因となったエフェクトを特定する。

リソースを割り当てられた、まだ演奏されていないバッファは、Play メソッドに渡されたボイス管理フラグにより、早めに終了される候補とならない。

AcquireResources によって取得されたリソースは、再生が停止されたときに解放される。

メソッドが既に呼び出されたバッファで、繰り返しメソッドが呼び出された場合、エフェクトのステータスは返されるが、それ以上のリソースは割り当てられない。

この関数の dwEffectsCount パラメータは、IDirectSoundBuffer8::SetFX の呼び出しで渡されたパラメータと同じでなければならない。

ハードウェア アクセラレーションを利用できないシステムで DSBCAPS_LOCHARDWARE フラグを使ってバッファのリソースを取得しようとすると、メソッドは失敗し、オペレーティング システムに応じて DSERR_CONTROLUNAVAIL または DSERR_INVALIDCALL を返す。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSoundBuffer8::SetFX、DSBCAPS


IDirectSoundBuffer8::GetCaps

DirectSoundBuffer オブジェクトの能力を取得する。

HRESULT GetCaps(
  LPDSBCAPS pDSBufferCaps
);

パラメータ

pDSBufferCaps
DSBCAPS 構造体のアドレス。この構造体は、サウンド バッファの能力を保持している。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

注意

DSBCAPS 構造体は、IDirectSound8::CreateSoundBuffer メソッドに渡される DSBUFFERDESC 構造体と同等の情報に加えて、いくつかの追加情報を保持している。追加情報として、バッファの位置 (ハードウェアまたはソフトウェア) と、パフォーマンス測定値が挙げられる。

DSBCAPS 構造体の dwFlags メンバ内で指定されるフラグは、DSBUFFERDESC 構造体で使われるフラグと同じものである。唯一の違いは、DSBCAPS 構造体ではバッファ メモリの場所に応じて DSBCAPS_LOCHARDWARE と DSBCAPS_LOCSOFTWARE のどちらかが指定されることである。DSBUFFERDESC 構造体ではこれらのフラグはオプションであり、フラグの指定に応じて、バッファをハードウェアとソフトウェアのどちらかに強制的に配置できる。

動作環境

ヘッダー : dsound.h で宣言。

参照

DSBCAPS、DSBUFFERDESC、IDirectSound8::CreateSoundBuffer


IDirectSoundBuffer8::GetCurrentPosition

サウンド バッファ内の再生カーソルと書き込みカーソルの位置を取得する。

HRESULT GetCurrentPosition(
  LPDWORD pdwCurrentPlayCursor,
  LPDWORD pdwCurrentWriteCursor
);

パラメータ

pdwCurrentPlayCursor
再生カーソルのオフセットを受け取る変数のアドレス (バイト単位)。値が必要でない場合、このパラメータを NULL にする。
pdwCurrentWriteCursor
書き込みカーソルのオフセットを受け取る変数のアドレス (バイト単位)。値が必要でない場合、このパラメータを NULL にする。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

書き込みカーソルは、データ書き込みを安全に行える、バッファの先頭位置である。再生カーソルより後ろ、および書き込みカーソルの前方にあるバッファには、データを書き込むべきではない。詳細については、「再生カーソルと書き込みカーソル」を参照すること。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSoundBuffer8::SetCurrentPosition


IDirectSoundBuffer8::GetFormat

バッファ内のサウンド データのフォーマットに関する情報、またはフォーマットの記述を取得するのに必要なバッファ サイズを取得する。

HRESULT GetFormat(
  LPWAVEFORMATEX pwfxFormat,
  DWORD dwSizeAllocated,
  LPDWORD pdwSizeWritten
);

パラメータ

pwfxFormat
バッファ内のサウンド データに関する情報を受け取る WAVEFORMATEX 構造体のアドレス。フォーマットの記述を保持するために必要なバッファ サイズを取得するには NULL を指定する。この場合、pdwSizeWritten の変数が、データを受け取るために必要な構造体のサイズを受け取る。
dwSizeAllocated
pwfxFormat の構造体のサイズ (バイト単位)。pwfxFormat が NULL でない場合、この値は予期されるデータ サイズと同じか、それ以上でなければならない。
pdwSizeWritten
pwfxFormat の構造体に書き込まれたバイト数を受け取る変数のアドレス。このパラメータは NULL にしてもよい。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

注意

WAVEFORMATEX 構造体は、フォーマットに応じた可変長であってもよい。アプリケーションはフォーマットの記述を取得する前に、pwfxFormat パラメータに NULL を指定してこのメソッドを呼び出し、フォーマットのサイズに関して DirectSoundBuffer オブジェクトを照会する必要がある。必要な構造体のサイズは pdwSizeWritten パラメータへ返される。その後、アプリケーションは十分なメモリを割り当て、もう一度 IDirectSoundBuffer8::GetFormat を呼び出し、フォーマットの記述を取得できる。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSoundBuffer8::SetFormat


IDirectSoundBuffer8::GetFrequency

バッファの再生が行われている場所での 1 秒あたりのサンプリング回数を周波数として取得する。

HRESULT GetFrequency(
  LPDWORD pdwFrequency
);

パラメータ

pdwFrequency
オーディオ バッファが再生されている場所での周波数を受け取る変数のアドレス (Hz 単位)。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DSERR_CONTROLUNAVAIL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

ソフトウェア バッファの周波数の値は、DSBFREQUENCY_MIN から DSBFREQUENCY_MAX の範囲をとる。これらの値は、Dsound.h 内でそれぞれ 100、100,000 と定義されている。ただし、バッファはほかの値を返すことがある。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSoundBuffer8::SetFrequency


IDirectSoundBuffer8::GetObjectInPath

バッファに関連付けられたエフェクト オブジェクトのインターフェイスを取得する。

HRESULT GetObjectInPath(
  REFGUID rguidObject,
  DWORD dwIndex,
  REFGUID rguidInterface,
  LPVOID * ppObject
);

パラメータ

rguidObject
検索するオブジェクトの一意のクラス識別子を指定する REFGUID 型の値。たとえば、GUID_DSFX_STANDARD_ECHO など。任意のクラスのオブジェクトを検索する場合は、このパラメータを GUID_All_Objects に設定する。
dwIndex
パス中のクラスのオブジェクト内で、オブジェクトのインデックスを指定する値。「注意」を参照すること。
rguidInterface
目的のインターフェイスの一意の識別子を指定する値。「注意」を参照すること。
ppObject
目的のインターフェイス ポインタを受け取る変数のアドレス。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DSERR_CONTROLUNAVAIL
DSERR_INVALIDPARAM
DSERR_OBJECTNOTFOUND
E_NOINTERFACE

注意

IDirectSoundBuffer8::SetFX を使ってバッファに設定されている DMO は、リソースが割り当てられていなくても取得することができる。

以下のインターフェイスは、DirectX で提供されている各種 DMO に対して取得できる。

rguidInterface | *ppObject
IID_IDirectSoundFXGargle8 | IDirectSoundFXGargle8
IID_IDirectSoundFXChorus8 | IDirectSoundFXChorus8
IID_IDirectSoundFXFlanger8 | IDirectSoundFXFlanger8
IID_IDirectSoundFXEcho8 | IDirectSoundFXEcho8
IID_IDirectSoundFXDistortion8 | IDirectSoundFXDistortion8
IID_IDirectSoundFXCompressor8 | IDirectSoundFXCompressor8
IID_IDirectSoundFXParamEq8 | IDirectSoundFXParamEq8
IID_IDirectSoundFXWavesReverb8 | IDirectSoundFXWavesReverb8
IID_IDirectSoundFXI3DL2Reverb8 | IDirectSoundFXI3DL2Reverb8

さらに、標準の DMO では以下のインターフェイスを使用できる。これらのインターフェイスの詳細については、DirectShow のヘルプを参照すること。

rguidInterface | *ppObject
IID_IMediaObject | IMediaObject
IID_IMediaObjectInPlace | IMediaObjectInPlace
IID_IMediaParams | IMediaParams

dwIndex の値は、IDirectSoundBuffer8::SetFX に渡されたエフェクトの配列内でのオブジェクトのインデックスである。いくつかのエフェクトがまだ作成されていない場合があるため、エフェクト内の実際のオブジェクトの位置を表しているとは限らない。

オブジェクトは、rguidObject および dwIndex との一致だけに基づいて返される。rguidInterface がそのオブジェクトで使用されているインターフェイスを示しているかどうかは、アプリケーション側で確認する必要がある。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSoundFXChorus8、IDirectSoundFXCompressor8、IDirectSoundFXDistortion8、IDirectSoundFXEcho8、IDirectSoundFXFlanger8、IDirectSoundFXParamEq8、IDirectSoundFXI3DL2Reverb8


IDirectSoundBuffer8::GetPan

左右のオーディオ チャンネルの相対ボリュームを取得する。

HRESULT GetPan(
  LPLONG plPan
);

パラメータ

plPan
左右の相対ミキシング率を保持する変数のアドレス。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DSERR_CONTROLUNAVAIL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

戻り値は DSBPAN_LEFT から DSBPAN_RIGHT の範囲で、100 分の 1 デシベル (dB) 単位で測定される。現在これらの値は、Dsound.h 内でそれぞれ -10,000、10,000 と定義されている。値 DSBPAN_LEFT は右チャンネルが 100 dB 減衰していることを意味する。値 DSBPAN_RIGHT は左チャンネルが 100 dB 減衰していることを意味する。中立値は DSBPAN_CENTER であり、0 と定義されている。plPan パラメータが 0 であるときは、両方のチャンネルが最大ボリュームであることを意味する (どちらも 0 dB の減衰である)。DSBPAN_CENTER 以外の値はどれも、一方が最大ボリュームでもう一方が減衰していることを意味する。

パンの値が -2,173 のとき、左チャンネルは最大ボリュームで、右チャンネルは 21.73 dB 減衰していることを意味する。同様にパンの値が 870 のとき、左チャンネルは 8.7 dB 減衰しており、右チャンネルは最大ボリュームであることを意味する。DSBPAN_LEFT のパンは、右チャンネルが無音で、サウンドが左からのみ発生していることを意味する。一方、DSBPAN_RIGHT のパンは、左チャンネルが無音で、サウンドが右からのみ発生していることを意味する。

パン コントロールの効果は、ボリューム コントロールに累積される。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSoundBuffer8::GetVolume、IDirectSoundBuffer8::SetPan、IDirectSoundBuffer8::SetVolume


IDirectSoundBuffer8::GetStatus

サウンド バッファのステータスを取得する。

HRESULT GetStatus(
  LPDWORD pdwStatus
);

パラメータ

pdwStatus
サウンド バッファのステータスを保持する変数のアドレス。ステータスは、次のフラグの組み合わせである。
DSBSTATUS_BUFFERLOST
バッファは失われており、再生やロックを行う前に復元しなければならない。
DSBSTATUS_LOOPING
バッファはループしている。この値が設定されていない場合、バッファのサウンド データの最後に達すると再生は停止する。この値は、DSBSTATUS_PLAYING との組み合わせでのみ返される。
DSBSTATUS_PLAYING
バッファは再生中である。この値が設定されていない場合、バッファは停止している。
DSBSTATUS_LOCSOFTWARE
ソフトウェアのバッファは再生中である。DSBCAPS_LOCDEFER フラグで作成したバッファにだけ設定する。
DSBSTATUS_LOCHARDWARE
ハードウェアのバッファは再生中である。DSBCAPS_LOCDEFER フラグで作成したバッファにだけ設定する。
DSBSTATUS_TERMINATED
ボイス管理がバッファを早めに終了し、バッファは停止している。DSBCAPS_LOCDEFER フラグで作成したバッファにだけ設定する。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

動作環境

ヘッダー : dsound.h で宣言。


IDirectSoundBuffer8::GetVolume

バッファのボリュームを取得する。

HRESULT GetVolume(
  LPLONG plVolume
);

パラメータ

plVolume
減衰を 100 分の 1 デシベルの単位で受け取る変数のアドレス。「注意」を参照すること。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DSERR_CONTROLUNAVAIL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

戻り値の範囲は、DSBVOLUME_MAX から DSBVOLUME_MIN である。これらの値は、それぞれ 0 および -10,000 と定義されている。値 DSBVOLUME_MAX は、サウンド本来の未調整のボリュームを表す。値 DSBVOLUME_MIN は、オーディオのボリュームが 100 dB 減衰していることを表すが、これは実際的には無音を意味する。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSoundBuffer8::SetVolume


IDirectSoundBuffer8::Initialize

初期化されていない DirectSoundBuffer オブジェクトを初期化する。

HRESULT Initialize(
  LPDIRECTSOUND pDirectSound,
  LPCDSBUFFERDESC pcDSBufferDesc
);

パラメータ

pDirectSound
DirectSoundBuffer オブジェクトに関連付けられた DirectSound オブジェクトのアドレス。
pcDSBufferDesc
このサウンド バッファを初期化するために使われる値を保持する DSBUFFERDESC 構造体のアドレス。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DSERR_INVALIDPARAM
DSERR_ALREADYINITIALIZED

注意

IDirectSound8::CreateSoundBuffer メソッドが内部で IDirectSoundBuffer8::Initialize を呼び出すため、現在のリリースの DirectSound では必要ない。Initialize メソッドは将来の拡張性に備えて用意されている。

動作環境

ヘッダー : dsound.h で宣言。

参照

DSBUFFERDESC、IDirectSound8::CreateSoundBuffer、IDirectSoundBuffer8


IDirectSoundBuffer8::Lock

バッファの全部または一部をデータ書き込み用に準備し、データを書き込めるポインタを返す。

HRESULT Lock(
  DWORD dwOffset,
  DWORD dwBytes,
  LPVOID * ppvAudioPtr1,
  LPDWORD pdwAudioBytes1,
  LPVOID * ppvAudioPtr2,
  LPDWORD pdwAudioBytes2,
  DWORD dwFlags
);

パラメータ

dwOffset
バッファの先頭からロック開始位置までのオフセットをバイト単位で指定する値。dwFlags パラメータで DSBLOCK_FROMWRITECURSOR フラグが指定されている場合は、このパラメータは無視される。
dwBytes
ロックされるバッファ部分のサイズをバイト単位で指定する値。バッファは概念的には循環バッファであるため、この数は dwOffset からバッファの最後までの間のバイト数を上回ることができる。
ppvAudioPtr1
バッファの最初にロックされた部分へのポインタを受け取る変数のアドレス。
pdwAudioBytes1
ブロックのバイト数を ppvAudioPtr1 で受け取る変数のアドレス。この値が dwBytes より小さい場合、ロックはラップされ、ppvAudioPtr2 はバッファの先頭にある第 2 のデータ ブロックを指す。
ppvAudioPtr2
キャプチャ バッファの 2 番目にロックされた部分へのポインタを受け取る変数のアドレス。NULL が返された場合、ppvAudioPtr1 パラメータはキャプチャ バッファのロックされた部分全体を指す。
pdwAudioBytes2
ブロックのバイト数を ppvAudioPtr2 で受け取る変数のアドレス。ppvAudioPtr2 が NULL の場合、値は 0 である。
dwFlags
ロック イベントに変更を加えるフラグ。次のフラグが定義されている。
DSBLOCK_FROMWRITECURSOR
書き込みカーソルの位置でロックを開始する。dwOffset パラメータは無視される。
DSBLOCK_ENTIREBUFFER
バッファ全体をロックする。dwBytes パラメータは無視される。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DSERR_BUFFERLOST
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

このメソッドはオフセットとバイト カウントを受け取り、2 つの書き込みポインタとそれぞれに関連するサイズを返す。ロックされる部分がバッファの最後まで拡張せず、バッファの先頭にラップされない場合、2 番目のポインタである ppvAudioBytes2 は NULL を受け取る。ロックがラップされる場合、ppvAudioBytes2 はバッファの先頭へのポインタを指す。

アプリケーションが ppvAudioPtr2 パラメータおよび pdwAudioBytes2 パラメータに対して NULL を渡すと、ロックがバッファの終端を越えることはなく、ラップされない。

このメソッドで返されたポインタにデータを書き込んだら、アプリケーションは直ちに IDirectSoundBuffer8::Unlock を呼び出して、データ再生の用意ができたことを DirectSound に通知する必要がある。この通知を行わないと、サウンド デバイスの構成によっては、オーディオの分断または無音状態が発生する場合がある。

このメソッドは、書き込みポインタのみを返す。データが有効でない場合があるため、アプリケーションでこのポインタからサウンド データを読み込もうとすべきではない。たとえば、バッファがカードのメモリに配置されている場合、そのポインタはメイン システム メモリ内の一時バッファのアドレスとなっていることも考えられる。IDirectSoundBuffer8::Unlock を呼び出すと、この一時バッファの内容はカードのメモリに転送される。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSoundBuffer8::GetCurrentPosition


IDirectSoundBuffer8::Play

サウンド バッファを再生カーソルの位置から再生する。

HRESULT Play(
  DWORD dwReserved1,
  DWORD dwPriority,
  DWORD dwFlags
);

パラメータ

dwReserved1
このメンバは予約されている。0 でなければならない。
dwPriority
サウンドの優先度。この優先度は、ハードウェア ミキシング リソースを割り当てる際にボイス管理が使用する。最も低い優先度は 0、最も高い優先度は 0xFFFFFFFF である。バッファが DSBCAPS_LOCDEFER フラグで作成されていない場合、この値は 0 である。
dwFlags
バッファの再生方法を指定するフラグ。次のフラグが定義されている。
DSBPLAY_LOOPING
オーディオ バッファの最後に達すると、バッファの先頭から再生を再開する。明示的に停止するまで再生が続く。このフラグは、プライマリ サウンド バッファを再生する際に設定しなければならない。
ボイス割り当てフラグ
ボイス割り当てフラグは、バッファが DSBCAPS_LOCDEFER フラグで作成されたときのみ有効である。サウンド処理をハードウェアかソフトウェアで強制的に行うには、次のフラグのいずれかを使うこともできる。DBSPLAY_LOCHARDWARE と DBSPLAY_LOCSOFTWARE のどちらも設定されていない場合は、メソッドが呼び出されたときにリソースが利用可能かどうかによって、サウンドがソフトウェアまたはハードウェアで再生される。「注意」を参照すること。
DSBPLAY_LOCHARDWARE
ハードウェア バッファのみでボイスを再生する。ハードウェアに利用可能なボイスがなく、ボイス管理フラグも設定されていない場合、IDirectSoundBuffer8::Play に対する呼び出しは失敗する。このフラグを DSBPLAY_LOCSOFTWARE と組み合わせることはできない。
DSBPLAY_LOCSOFTWARE
ソフトウェア バッファのみでボイスを再生する。このフラグを DSBPLAY_LOCHARDWARE やボイス管理フラグのどれかと組み合わせることはできない。
ボイス管理フラグ
ボイス管理フラグは、バッファが DSBCAPS_LOCDEFER フラグで作成されたときにのみ有効であり、ハードウェアで再生するサウンドに使われる。これらのフラグは、既に使用中のハードウェア リソースに現在のサウンドが受け渡されるようにする。DSBCAPS_LOCDEFER フラグで作成されたバッファのみが、早めに終了される候補となる。「注意」を参照すること。
DSBPLAY_TERMINATEBY_TIME
ハードウェアに利用可能なボイスがない場合は、新しいバッファ用の空きを確保するために現在再生中の非ループ バッファが停止する。早めに終了されるバッファは、再生の残り時間が最も少ないバッファである。
DSBPLAY_TERMINATEBY_DISTANCE
ハードウェアに利用可能なボイスがない場合は、新しいバッファ用の空きを確保するために現在再生中のバッファが停止される。早めに終了されるバッファは、DSBCAPS_MUTE3DATMAXDISTANCE フラグが設定され、最大距離を超えているものの中から選択される。このようなバッファがない場合、メソッドは失敗する。
DSBPLAY_TERMINATEBY_PRIORITY
ハードウェアに利用可能なボイスがない場合は、新しいバッファ用の空きを確保するために現在再生中のバッファが停止される。早めに終了されるバッファは、IDirectSoundBuffer8::Play に渡される dwPriority パラメータで設定された優先度が最も低いバッファである。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DSERR_BUFFERLOST
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

IDirectSound8::SetCooperativeLevel が呼び出されていない場合でも、メソッドは DS_OK を返す。ただし、協調レベルが設定されるまでサウンドは出力されない。

このメソッドが指定したバッファが既に再生中だった場合、メソッドの呼び出しは成功し、バッファは再生を続ける。ただし最新の呼び出しで定義したフラグは、以前の呼び出しで定義されていたフラグを置き換える。

このメソッドがプライマリ バッファで呼び出された場合は、サウンド デバイスでバッファの再生が開始される。アプリケーションが DSSCL_WRITEPRIMARY の協調レベルに設定されている場合は、アプリケーションによりプライマリ バッファに置かれた任意のオーディオ データがサウンド デバイスに送られる。アプリケーションがほかの協調レベルに設定されている場合は、セカンダリ バッファが再生されていないと、プライマリ バッファは無音となる。プライマリ バッファは、DSBPLAY_LOOPING フラグで再生しなければならない。詳細については、「プライマリ バッファの連続再生」を参照すること。

このメソッドが DSBCAPS_LOCDEFER フラグで作成されていないバッファ上に設定されたボイス割り当てフラグ、またはボイス管理フラグで呼び出されると、この呼び出しは失敗し、DSERR_INVALIDPARAM が返される。

DSBPLAY_TERMINATEBY_TIME と DSBPLAY_TERMINATEBY_DISTANCE を組み合わせることはできないが、このどちらかと DSBPLAY_TERMINATEBY_PRIORITY を組み合わせることができる。この場合、DSBPLAY_TERMINATEBY_TIME または DSBPLAY_TERMINATEBY_DISTANCE フラグは、優先度が等しい場合にどのバッファを終了すべきかを決定するために使われる。

次の表は、ハードウェア ボイスの空きを利用できない場合に、ボイス割り当てフラグとボイス管理フラグの組み合わせによって決まるメソッドの動作を示している。

 | DSBPLAY_LOCHARDWARE | DSBPLAY_LOCHARDWARE と DSBPLAY_LOCSOFTWARE のどちらも使わない | DSBPLAY_LOCSOFTWARE
DSBPLAY_TERMINATEBY_TIME | 再生の残り時間が最も少ないサウンドを終了し、新しいサウンドを解放したボイスで再生する。 | 再生の残り時間が最も少ないサウンドを終了し、新しいサウンドを解放したボイスで再生する。 | 新しいサウンドをソフトウェアで再生する。
DSBPLAY_TERMINATEBY_DISTANCE | ハードウェアで現在再生中のサウンドが最大距離を超えており、DSBCAPS_MUTE3DATMAXDISTANCE フラグが設定されている場合、そのいずれかを終了し、新しいサウンドをハードウェアで再生する。それ以外の場合、この呼び出しは失敗する。 | ハードウェアで現在再生中のサウンドが最大距離を超えており、DSBCAPS_MUTE3DATMAXDISTANCE フラグが設定されている場合、そのいずれかを終了し、新しいサウンドをハードウェアで再生する。それ以外の場合は、新しいサウンドをソフトウェアで再生する。 | 新しいサウンドをソフトウェアで再生する。
DSBPLAY_TERMINATEBY_PRIORITY | 新しいサウンドの優先度がハードウェアで現在再生中のサウンドよりも高いか同じ場合、優先度の最も低いサウンドを終了し、新しいサウンドをハードウェアで再生する。それ以外の場合、この呼び出しは失敗する。 | 新しいサウンドの優先度がハードウェアで現在再生中のサウンドよりも高いか同じ場合、優先度の最も低いサウンドを終了し、新しいサウンドをハードウェアで再生する。それ以外の場合は、新しいサウンドをソフトウェアで再生する。 | 新しいサウンドをソフトウェアで再生する。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSoundBuffer8、IDirectSound8::SetCooperativeLevel


IDirectSoundBuffer8::Restore

指定された DirectSoundBuffer オブジェクトに関連付けられていた、失われたサウンド バッファへのメモリ割り当てを復元する。

HRESULT Restore();

パラメータ

なし。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DSERR_BUFFERLOST
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

アプリケーションに入力フォーカスが置かれていないと、IDirectSoundBuffer8::Restore は成功しないことがある。たとえば、入力フォーカスが置かれているアプリケーションが DSSCL_WRITEPRIMARY (書き込み優先) 協調レベルに設定されている場合、ほかのどのアプリケーションもバッファを復元できない。同様に DSSCL_WRITEPRIMARY 協調レベルのアプリケーションがプライマリ サウンド バッファを復元するには、入力フォーカスが必要である。

DirectSound がバッファ メモリを復元した後、有効なサウンド データを書き込み直す必要がある。DirectSound はメモリを復元するが、メモリの内容は復元できない。

アプリケーションはバッファを指定して IDirectSoundBuffer8::Lock または IDirectSoundBuffer8::Play の各メソッドを呼び出すと、そのバッファが失われている場合に通知を受けられる。バッファが失われている場合、これらのメソッドは DSERR_BUFFERLOST を返す。IDirectSoundBuffer8::GetStatus メソッドを使って、サウンド バッファのステータスの取得と DSBSTATUS_BUFFERLOST フラグのテストを行うこともできる。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSoundBuffer8::Lock、IDirectSoundBuffer8::Play、IDirectSoundBuffer8::GetStatus


IDirectSoundBuffer8::SetCurrentPosition

再生カーソルの位置を設定する。バッファから次のデータ バイトを読み込める位置を表す。

HRESULT SetCurrentPosition(
  DWORD dwNewPosition
);

パラメータ

dwNewPosition
バッファの先頭からの再生カーソルのオフセット (バイト単位)。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

プライマリ サウンド バッファに対しては、このメソッドを呼び出せない。

バッファが再生中の場合、カーソルは直ちに新しい位置に移動し、再生はその位置から続行される。バッファが停止している場合は、次に IDirectSoundBuffer8::Play メソッドを呼び出したときに、新しい位置から再生を開始する。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSoundBuffer8::GetCurrentPosition、IDirectSoundBuffer8::Play


IDirectSoundBuffer8::SetFormat

アプリケーション用のプライマリ サウンド バッファのフォーマットを設定する。このアプリケーションに入力フォーカスが置かれるたびに、DirectSound はプライマリ バッファを指定されたフォーマットに設定する。

プライマリ サウンド バッファは IDirectSoundBuffer8 インターフェイスをサポートしていないので、IDirectSoundBuffer でこのメソッドを呼び出す必要がある。

HRESULT SetFormat(
  LPCWAVEFORMATEX pcfxFormat
);

パラメータ

pcfxFormat
WAVEFORMATEX 構造体のアドレス。この構造体は、プライマリ サウンド バッファの新しいフォーマットを記述する。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DSERR_BADFORMAT
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_OUTOFMEMORY
DSERR_PRIOLEVELNEEDED
DSERR_UNSUPPORTED

注意

プライマリ バッファのフォーマットは、セカンダリ バッファを作成する前に設定する。

アプリケーションに DSSCL_NORMAL 協調レベルが設定されている場合、メソッドは失敗する。

アプリケーションが DSSCL_WRITEPRIMARY 協調レベルで DirectSound を使用している場合、IDirectSoundBuffer8::SetFormat を呼び出す前にバッファを停止しなければならない。フォーマットがサポートされていない場合、メソッドは失敗する。

協調レベルが DSSCL_PRIORITY または DSSCL_EXCLUSIVE である場合、DirectSound はプライマリ バッファを停止し、フォーマットを変更して、バッファを再開する。要求されたフォーマットをハードウェアがサポートしていない場合でも、メソッドは成功する。DirectSound は、バッファを要求に最も近いフォーマットに設定する。このような状況が発生しているかどうかを判断するには、アプリケーションはプライマリ バッファに対して IDirectSoundBuffer8::GetFormat メソッドを呼び出し、その結果を、SetFormat メソッドで要求したフォーマットと比較する。

このメソッドはセカンダリ サウンド バッファでは利用できない。新しいフォーマットが要求された場合、アプリケーションは新しい DirectSoundBuffer オブジェクトを作成しなければならない。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSoundBuffer8、IDirectSoundBuffer8::GetFormat


IDirectSoundBuffer8::SetFrequency

サンプリング オーディオの再生周波数を設定する。

HRESULT SetFrequency(
  DWORD dwFrequency
);

パラメータ

dwFrequency
サンプリング オーディオを再生する新しい周波数 (Hz 単位)。値の範囲は DSBFREQUENCY_MIN から DSBFREQUENCY_MAX の間でなければならない。現在これらの値は dsound.h 内で、それぞれ 100、100,000 と定義されている。

値が DSBFREQUENCY_ORIGINAL の場合、周波数はバッファ フォーマット内のデフォルト値にリセットされる。このフォーマットは IDirectSound8::CreateSoundBuffer メソッドで指定されたものである。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DSERR_CONTROLUNAVAIL
DSERR_GENERIC
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

周波数を上下させると、オーディオ データの認識ピッチが変化する。このメソッドはバッファのフォーマットには影響を及ぼさない。

このメソッドはプライマリ サウンド バッファには有効ではない。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSound8::CreateSoundBuffer、IDirectSoundBuffer8::GetFrequency、IDirectSoundBuffer8::Play、IDirectSoundBuffer8::SetFormat


IDirectSoundBuffer8::SetFX

バッファのエフェクトを有効にする。バッファは再生中であったりロッキングされていてはならない。

このメソッドを成功させるには、CoInitialize が呼び出されている必要がある。これは、IDirectMusicPerformance8::InitAudio を使って DirectSound を作成するアプリケーションでは、自動的に実行される。しかし、DirectSoundCreate8 を使って DirectSound を作成するアプリケーションでも、CoInitialize を呼び出す必要がある。

HRESULT SetFX(
  DWORD dwEffectsCount,
  LPDSEFFECTDESC pDSFXDesc,
  LPDWORD pdwResultCodes
);

パラメータ

dwEffectsCount
pDSFXDesc 配列および pdwResultCodes 配列の要素数を指定する値。この値が 0 の場合、pDSFXDesc および pdwResultCodes はどちらも NULL でなければならない。0 に設定すると、バッファのすべてのエフェクトが削除される。
pDSFXDesc
サイズが dwEffectsCount の DSEFFECTDESC 構造体の配列のアドレス。バッファのエフェクトを指定する。dwEffectsCount が 0 の場合は NULL でなければならない。
pdwResultCodes
サイズが dwEffectsCount の DWORD 要素の配列のアドレス。各要素は次のいずれかの値を受け取る。これらの値は、pDSFXDesc 配列の対応するエフェクトを作成しようとした結果を示す。
DSFXR_LOCHARDWARE
エフェクトはハードウェアでインスタンス化される。
DSFXR_LOCSOFTWARE
エフェクトはソフトウェアでインスタンス化される。
DSFXR_UNALLOCATED
ハードウェアまたはソフトウェアにまだエフェクトが設定されていない。この値が返されるのは、そのバッファが DSBUFFERDESC の DSBCAPS_LOCDEFER フラグを使って作成されている場合である。
DSFXR_FAILED
リソースを利用できなかったため、エフェクトは作成されていない。
DSFXR_PRESENT
エフェクトは利用できるが、要求されたほかのエフェクトの 1 つが作成できなかったために作成できなかった。要求されたエフェクトのうち 1 つでも作成できない場合、エフェクトはすべて作成されず、呼び出しは失敗する。
DSFXR_UNKNOWN
指定されたエフェクトはシステムに登録されてない。このため、メソッドは失敗した。

このパラメータを NULL にすると、結果の値が返されない。また、dwEffectsCount が 0 の場合は、このパラメータを NULL にしなければならない。

戻り値

成功した場合は、DS_OK または DS_INCOMPLETE を返す。

失敗した場合は、次のいずれかのエラー値を返す。

CO_E_NOTINITIALIZED
DSERR_CONTROLUNAVAIL
DSERR_GENERIC
DSERR_INVALIDPARAM
DSERR_INVALIDCALL
DSERR_NOINTERFACE
DSERR_PRIOLEVELNEEDED

また、このメソッドは、IMediaObject::SetInputType や IMediaObject::SetOutputType.などの DMO メソッドのエラー値を返す。返されるエラー値については、DirectShow のドキュメントを参照すること。

注意

失敗した場合、各エフェクトの pdwResultCodes の値は、DSFXF_PRESENT または DSFXR_UNKNOWN になる。これらの値を調べると、どのエフェクトが原因で失敗したかを特定できる。

メソッドを成功させるには、バッファが DSBCAPS_CTRLFX フラグで作成されている必要があり、また、再生中であったりロックされていてはいけない。

DSERR_NOINTERFACE またはその他の COM エラーが返された場合は、DSFXR_PRESENT または DSFXR_UNKNOWN の結果コード配列を確認し、エラーの発生原因となったエフェクトを調べる。DSERR_INVALIDPARAM が返された場合は、DSFXR_FAILED の結果コードを確認し、リソースを取得できなかったエフェクトを調べる。

バッファがオーディオパスの一部である場合、オーディオパスは非アクティブでなければならない。「IDirectMusicAudioPath8::Activate」を参照すること。

エフェクト インターフェイスを取得する前に、エフェクトをバッファに設定しなければならない。エフェクト インターフェイスを取得するには、IDirectSoundBuffer8::GetObjectInPath を使用する。

動作環境

ヘッダー : dsound.h で宣言。

参照

DSBCAPS、IDirectSoundBuffer8::AcquireResources


IDirectSoundBuffer8::SetPan

左右のチャンネルの相対ボリュームを設定する。

HRESULT SetPan(
  LONG lPan
);

パラメータ

lPan
左右のチャンネルの相対ボリューム。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DSERR_CONTROLUNAVAIL
DSERR_GENERIC
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

LPan の値は DSBPAN_LEFT から DSBPAN_RIGHT の範囲で、100 分の 1 デシベル (dB) 単位で測定される。現在これらの値は、Dsound.h 内でそれぞれ -10,000、10,000 と定義されている。値 DSBPAN_LEFT は右チャンネルが 100 dB 減衰していることを意味する。値 DSBPAN_RIGHT は左チャンネルが 100 dB 減衰していることを意味する。中立値は DSBPAN_CENTER であり、0 と定義されている。plPan パラメータが 0 であるときは、両方のチャンネルが最大ボリュームであることを意味する (どちらも 0 dB の減衰である)。DSBPAN_CENTER 以外の値はどれも、一方が最大ボリュームでもう一方が減衰していることを意味する。

パンの値が -2,173 のとき、左チャンネルは最大ボリュームで、右チャンネルは 21.73 dB 減衰していることを意味する。同様にパンの値が 870 のとき、左チャンネルは 8.7 dB 減衰しており、右チャンネルは最大ボリュームであることを意味する。DSBPAN_LEFT のパンは、右チャンネルが無音で、サウンドが左からのみ発生していることを意味する。一方、DSBPAN_RIGHT のパンは、左チャンネルが無音で、サウンドが右からのみ発生していることを意味する。

パン コントロールの効果は、ボリューム コントロールに累積される。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSoundBuffer8::GetPan、IDirectSoundBuffer8::GetVolume、IDirectSoundBuffer8::SetVolume


IDirectSoundBuffer8::SetVolume

サウンド ボリュームを設定する。

HRESULT SetVolume(
  LONG lVolume
);

パラメータ

lVolume
このサウンド バッファで要求する新しいボリューム。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DSERR_CONTROLUNAVAIL
DSERR_GENERIC
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

ボリュームは 100 分の 1 デシベル (dB) 単位で指定される。許容される値は DSBVOLUME_MAX (減衰なし) と DSBVOLUME_MIN (無音) の間である。現在これらの値は、Dsound.h 内でそれぞれ 0、-10,000 と定義されている。値 DSBVOLUME_MAX は、ストリーム本来の未調整のボリュームを表す。値 DSBVOLUME_MIN は、オーディオのボリュームが 100 dB 減衰していることを表すが、これは実際的には無音を意味する。現在、DirectSound は増幅をサポートしていない。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSoundBuffer8::GetPan、IDirectSoundBuffer8::GetVolume、IDirectSoundBuffer8::SetPan


IDirectSoundBuffer8::Stop

サウンド バッファの再生を停止する。

HRESULT Stop();

パラメータ

なし。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

セカンダリ サウンド バッファに対して IDirectSoundBuffer8::Stop を呼び出すと、再生カーソルが、直前に再生されたサンプルの直後のサンプルに設定される。これは、そのバッファに対して次に IDirectSoundBuffer8::Play メソッドを呼び出したときに、以前に再生を停止した場所から再生が再開されることを意味する。

DSSCL_WRITEPRIMARY レベルに設定されたアプリケーションがプライマリ サウンド バッファに対してこのメソッドを呼び出すと、このメソッドはバッファを停止し、再生カーソルを 0 (バッファの先頭) にリセットする。ほとんどのサウンド カードはバッファの先頭からのみ再生を行えるので、このような処理が必要である。

しかし、書き込み優先以外の協調レベルに設定されているアプリケーションが、プライマリ バッファに対して IDirectSoundBuffer8::Stop を呼び出した場合は、このメソッドは IDirectSoundBuffer8::Play とは逆のエフェクトをもたらすだけである。セカンダリ バッファが再生されていない場合は、プライマリ バッファを停止するように設定する。このアプリケーションまたはほかのアプリケーションがほかのバッファを再生している場合、それらの再生が停止するまでプライマリ バッファも実際には停止しない。たとえ振幅が 0 dB であっても、バッファがサウンド データを再生している場合は処理のオーバーヘッドが発生するので、このメソッドを使ってプライマリ バッファを停止することは役に立つ。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSoundBuffer8::Play


IDirectSoundBuffer8::Unlock

サウンド バッファをアンロックする。

HRESULT Unlock(
  LPVOID pvAudioPtr1,
  DWORD dwAudioBytes1,
  LPVOID pvAudioPtr2,
  DWORD dwAudioBytes2
);

パラメータ

pvAudioPtr1
IDirectSoundBuffer8::Lock メソッドの ppvAudioPtr1 パラメータで取得した値のアドレス。
dwAudioBytes1
バッファの pvAudioPtr1 で表される位置に書き込むバイト数を指定する値。「注意」を参照すること。
pvAudioPtr2
IDirectSoundBuffer8::Lock メソッドの ppvAudioPtr2 パラメータで取得した値のアドレス。
dwAudioBytes2
バッファの pvAudioPtr2 で表される位置に書き込むバイト数を指定する値。「注意」を参照すること。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

アプリケーションは、IDirectSoundBuffer8::Lock メソッドで返されるポインタ pvAudioPtr1 および pvAudioPtr2 の両方を渡して、IDirectSoundBuffer8::Lock と IDirectSoundBuffer8::Unlock の対を正しく指定しなければならない。たとえ 2 番目のポインタに何も書き込まれていない場合でも、2 番目のポインタは必要である。

dwAudioBytes1 および dwAudioBytes2 の値は、バッファの各部分に実際に書き込まれるバイト数を指定しなければならない。ロックのサイズより小さくなる場合がある。DirectSound はこれらの値を使用して、デバイスにコミットするデータ量を決定する。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSoundBuffer8::GetCurrentPosition、IDirectSoundBuffer8::Lock


IDirectSoundCapture8

IDirectSoundCapture8 インターフェイスのメソッドは、サウンド キャプチャ バッファを作成するために使用される。

インターフェイスは、DirectSoundCaptureCreate8 関数または DirectSoundFullDuplexCreate8 関数を使って取得するか、CoCreateInstance または CoCreateInstanceEx を使って、クラス CLSID_DirectSoundCapture8 のオブジェクトを作成する。

IDirectSoundCapture8 は、IDirectSoundCapture の定義である。2 つのインターフェイス名は入れ替え可能である。ただし、このインターフェイスをサポートしているオブジェクトは、クラスによって機能が異なる。詳細については、「DirectSoundCaptureCreate8」および「IDirectSoundCapture8::CreateCaptureBuffer」を参照すること。

IDirectSoundCapture8 インターフェイスのメソッドは、次のグループにまとめることができる。

作成 | CreateCaptureBuffer
 | Initialize
能力 | GetCaps

すべての COM インターフェイスと同様に、IDirectSoundCapture8 インターフェイスは IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは次の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTSOUNDCAPTURE 型は、IDirectSoundCapture インターフェイスへのポインタとして定義されている。

typedef struct IDirectSoundCapture   *LPDIRECTSOUNDCAPTURE;

動作環境

ヘッダー : dsound.h で宣言。


IDirectSoundCapture8::CreateCaptureBuffer

キャプチャ バッファを作成する。

HRESULT CreateCaptureBuffer(
  LPCDSCBUFFERDESC pcDSCBufferDesc,
  LPDIRECTSOUNDCAPTUREBUFFER * ppDSCBuffer,
  LPUNKNOWN pUnkOuter
);

パラメータ

pcDSCBufferDesc
DSCBUFFERDESC 構造体へのポインタ。この構造体は、作成されるキャプチャ バッファ用の値を保持している。
ppDSCBuffer
IDirectSoundCaptureBuffer インターフェイス ポインタを受け取る変数のアドレス。IDirectSoundCaptureBuffer8 を取得するには、QueryInterface を使用する。「注意」を参照すること。
pUnkOuter
COM 集成体に対する制御オブジェクトの IUnknown インターフェイスのアドレス。NULL でなければならない。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DSERR_INVALIDPARAM
DSERR_BADFORMAT
DSERR_GENERIC
DSERR_NODRIVER
DSERR_OUTOFMEMORY
DSERR_UNINITIALIZED

注意

Microsoft® Windows® 95、Windows® 98、および Windows® 2000 では、各キャプチャ デバイスが単一のバッファをサポートする。

IDirectSoundCaptureBuffer8 インターフェイスは、CLSID_DirectSoundCapture8 クラスのオブジェクトで作成されたバッファのみでサポートされる。IDirectSoundCapture8 インターフェイスを DirectSoundCaptureCreate8 から取得した場合は、IDirectSoundCaptureBuffer8 がサポートされる。IDirectSoundCapture8 を以前の DirectSoundCaptureCreate 関数から取得した場合は、IDirectSoundCaptureBuffer だけがサポートされる。

動作環境

ヘッダー : dsound.h で宣言。


IDirectSoundCapture8::GetCaps

キャプチャ デバイスの能力を取得する。

HRESULT GetCaps(
  LPDSCCAPS pDSCCaps
);

パラメータ

pDSCCaps
キャプチャ デバイスに関する情報を受け取る DSCCAPS 構造体へのポインタ。このメソッドを呼び出すには、dwSize メンバは構造体のサイズをバイト単位で指定しなければならない。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DSERR_INVALIDPARAM
DSERR_UNSUPPORTED
DSERR_NODRIVER
DSERR_OUTOFMEMORY
DSERR_UNINITIALIZED

動作環境

ヘッダー : dsound.h で宣言。


IDirectSoundCapture8::Initialize

CoCreateInstance を使用して DirectSoundCapture オブジェクトを作成した場合、オブジェクトは IDirectSoundCapture8::Initialize メソッドで初期化しなければならない。DirectSoundCaptureCreate 関数を使用してオブジェクトを作成した場合は、このメソッドを呼び出す必要はない。

HRESULT Initialize(
  LPCGUID pcGuidDevice
);

パラメータ

pcGuidDevice
DirectSoundCapture オブジェクトに結合されるサウンド ドライバを指定する GUID のアドレス。プライマリ サウンド ドライバを選択するには、NULL または GUID_NULL を指定する。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DSERR_INVALIDPARAM
DSERR_NODRIVER
DSERR_OUTOFMEMORY
DSERR_ALREADYINITIALIZED

動作環境

ヘッダー : dsound.h で宣言。


IDirectSoundCaptureBuffer8

サウンド キャプチャ バッファの操作に使用する。

IDirectSoundCaptureBuffer8 インターフェイスを取得するには、IDirectSoundCapture8::CreateCaptureBuffer メソッドを呼び出して IDirectSoundCaptureBuffer を取得し、IID_IDirectSoundCaptureBuffer8 を IDirectSoundCaptureBuffer::QueryInterface に渡す。

注 DirectSoundCaptureCreate 関数を使って IDirectSoundCapture8 インターフェイスを取得した場合は、IDirectSoundCaptureBuffer8 を取得できない。「DirectSoundCaptureCreate8」を参照すること。

このインターフェイスのメソッドは、次のグループにまとめることができる。

キャプチャ管理 | Lock
 | Start
 | Stop
 | Unlock
エフェクト | GetFXStatus
 | GetObjectInPath
初期化 | Initialize
情報 | GetCaps
 | GetCurrentPosition
 | GetFormat
 | GetStatus

すべての COM インターフェイスと同様に、このインターフェイスは IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは次の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTSOUNDCAPTUREBUFFER8 型は、IDirectSoundCaptureBuffer8 インターフェイスへのポインタとして定義されている。

typedef struct IDirectSoundCaptureBuffer8 *LPDIRECTSOUNDCAPTUREBUFFER8;

動作環境

ヘッダー : dsound.h で宣言。


IDirectSoundCaptureBuffer8::GetCaps

バッファの能力を返す。

HRESULT GetCaps(
  LPDSCBCAPS pDSCBCaps
);

パラメータ

pDSCBCaps
キャプチャ バッファに関する情報を受け取る DSCBCAPS 構造体へのポインタ。入力時に、dwSize メンバは構造体のサイズをバイト単位で指定しなければならない。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DSERR_INVALIDPARAM
DSERR_UNSUPPORTED
DSERR_OUTOFMEMORY

動作環境

ヘッダー : dsound.h で宣言。


IDirectSoundCaptureBuffer8::GetCurrentPosition

バッファ中のキャプチャ カーソルおよび読み込みカーソルを取得する。

キャプチャ カーソルは、読み込みカーソルより前方にある。読み込み位置より後でキャプチャ位置より前のデータは (キャプチャ位置を含む)、必ずしも有効なデータとは限らない。

HRESULT GetCurrentPosition(
  LPDWORD pdwCapturePosition,
  LPDWORD pdwReadPosition
);

パラメータ

pdwCapturePosition
キャプチャ カーソルのバッファの先頭からのオフセットを受け取る変数のアドレス (バイト単位)。この値が必要ない場合は、パラメータを NULL に設定できる。
pdwReadPosition
読み込みカーソルのバッファの先頭からのオフセットを受け取る変数のアドレス (バイト単位)。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DSERR_INVALIDPARAM
DSERR_NODRIVER
DSERR_OUTOFMEMORY

動作環境

ヘッダー : dsound.h で宣言。


IDirectSoundCaptureBuffer8::GetFormat

キャプチャ バッファのフォーマットを取得する。

HRESULT GetFormat(
  LPWAVEFORMATEX pwfxFormat,
  DWORD dwSizeAllocated,
  LPDWORD pdwSizeWritten
);

パラメータ

pwfxFormat
キャプチャ バッファ内のサウンド データに関する情報を受け取る WAVEFORMATEX 構造体のアドレス。フォーマットの記述を保持するために必要なバッファ サイズを取得するには NULL を指定する。この場合、pdwSizeWritten パラメータが指す DWORD で、完全なフォーマット情報を受け取るために必要な構造体のサイズを受け取る。
dwSizeAllocated
WAVEFORMATEX 構造体のサイズ (バイト単位)。DirectSoundCapture が構造体へ書き込むバイト数は、最大で dwSizeAllocated バイトである。構造体がそれより多くのメモリを必要とする場合、切り捨てが行われる。
pdwSizeWritten
WAVEFORMATEX 構造体に書き込まれたバイト数を受け取る変数のアドレス。または、pwfxFormat が NULL の場合は、情報を受け取るために必要な WAVEFORMATEX 構造体のサイズ。値が必要でない場合、このパラメータを NULL にする。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

動作環境

ヘッダー : dsound.h で宣言。


IDirectSoundCaptureBuffer8::GetFXStatus

キャプチャ バッファのエフェクトのステータスを取得する。

HRESULT GetFXStatus(
  DWORD dwFXCount,
  LPDWORD pdwFXStatus
);

パラメータ

dwFXCount
pdwFXStatus 配列の要素数を指定する値。
pdwFXStatus
各エフェクトのステータスを受け取る DWORD 変数の配列のアドレス。このパラメータには、IDirectSoundCapture8::CreateCaptureBuffer の lpDSCFXDesc パラメータで渡される配列と同じ数の要素が含まれる。各エフェクトに対して、次のいずれかのフラグが返される。
DSCFXR_LOCHARDWARE
エフェクトはハードウェアでインスタンス化される。
DSCFXR_LOCSOFTWARE
エフェクトはソフトウェアでインスタンス化される。
DSCFXR_UNALLOCATED
ハードウェアまたはソフトウェアにまだエフェクトが設定されていない。
DSCFXR_FAILED
リソースを利用できなかったため、エフェクトは作成されていない。
DSCFXR_UNKNOWN
エフェクトがシステムに登録されていないため、エフェクトは作成されていない。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

動作環境

ヘッダー : dsound.h で宣言。


IDirectSoundCaptureBuffer8::GetObjectInPath

バッファに関連付けられたエフェクト オブジェクトのインターフェイスを取得する。

HRESULT GetObjectInPath(
  REFGUID rguidObject,
  DWORD dwIndex,
  REFGUID rguidInterface,
  LPVOID * ppObject
);

パラメータ

rguidObject
検索するオブジェクトの一意のクラス識別子を指定する REFGUID 型の値。たとえば、GUID_DSCFX_CLASS_AEC など。任意のクラスのオブジェクトを検索する場合は、このパラメータを GUID_All_Objects に設定する。
dwIndex
パス中のクラスのオブジェクト内で、オブジェクトのインデックスを指定する値。「注意」を参照すること。
rguidInterface
目的のインターフェイスの一意の識別子を指定する値。たとえば、IID_IDirectSoundCaptureFXAec8 など。
ppObject
目的のインターフェイス ポインタを受け取る変数のアドレス。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DSERR_CONTROLUNAVAIL
DSERR_INVALIDPARAM
E_NOINTERFACE

注意

dwIndex の値は、IDirectSoundCapture8::CreateCaptureBuffer に渡されたエフェクトの配列内でのオブジェクトのインデックスである。いくつかのエフェクトがまだ作成されていない場合があるため、エフェクト内の実際のオブジェクトの位置を表しているとは限らない。

オブジェクトは、rguidObject および dwIndex との一致だけに基づいて返される。rguidInterface がそのオブジェクトで使用されているインターフェイスを示しているかどうかは、アプリケーション側で確認する必要がある。

動作環境

ヘッダー : dsound.h で宣言。


IDirectSoundCaptureBuffer8::GetStatus

キャプチャ バッファのステータスを取得する。

HRESULT GetStatus(
  LPDWORD pdwStatus
);

パラメータ

pdwStatus
キャプチャ バッファのステータスを受け取る変数のアドレス。ステータスとして、次の値の 1 つまたは複数を設定できる。
DSCBSTATUS_CAPTURING
バッファは現在オーディオ データをキャプチャしている。
DSCBSTATUS_LOOPING
バッファは現在ループしている。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

動作環境

ヘッダー : dsound.h で宣言。


IDirectSoundCaptureBuffer8::Initialize

初期化されていない DirectSoundCaptureBuffer オブジェクトを初期化する。

HRESULT Initialize(
  LPDIRECTSOUNDCAPTURE pDirectSoundCapture,
  LPCDSCBUFFERDESC pcDSCBufferDesc
);

パラメータ

pDirectSoundCapture
DirectSoundCaptureBuffer オブジェクトに関連付けられた DirectSoundCapture オブジェクトのアドレス。
pcDSCBufferDesc
このサウンド バッファを初期化するために使われる値を保持する DSCBUFFERDESC 構造体のアドレス。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DSERR_INVALIDPARAM
DSERR_ALREADYINITIALIZED

注意

IDirectSoundCapture8::CreateCaptureBuffer メソッドは内部で IdirectSoundCaptureBuffer8::Initialize メソッドを呼び出すので、現在のリリースの DirectSound では Initialize を明示的に呼び出す必要はない。Initialize メソッドは将来の拡張性に備えて用意されている。

動作環境

ヘッダー : dsound.h で宣言。

参照

DSBUFFERDESC、IDirectSoundCapture8::CreateCaptureBuffer


IDirectSoundCaptureBuffer8::Lock

バッファをロックする。バッファをロックすると、そのバッファへのポインタが返され、アプリケーションがそのメモリに対してオーディオ データを読み書きできるようになる。

HRESULT Lock(
  DWORD dwOffset,
  DWORD dwBytes,
  LPVOID *ppvAudioPtr1,
  LPDWORD pdwAudioBytes1,
  LPVOID *ppvAudioPtr2,
  LPDWORD pdwAudioBytes2,
  DWORD dwFlags
);

パラメータ

dwOffset
バッファの先頭からロック開始位置までのオフセットをバイト単位で指定する値。
dwBytes
ロックされるバッファ部分のサイズをバイト単位で指定する値。バッファは概念的には循環バッファであるため、この数は dwOffset からバッファの最後までの間のバイト数を上回ることができる。
ppvAudioPtr1
バッファの最初にロックされた部分へのポインタを受け取る変数のアドレス。
pdwAudioBytes1
ブロックのバイト数を ppvAudioPtr1 で受け取る変数のアドレス。この値が dwBytes より小さい場合、ロックはラップされ、ppvAudioPtr2 はバッファの先頭にある第 2 のデータ ブロックを指す。
ppvAudioPtr2
キャプチャ バッファの 2 番目にロックされた部分へのポインタを受け取る変数のアドレス。NULL が返された場合、ppvAudioPtr1 パラメータはキャプチャ バッファのロックされた部分全体を指す。
pdwAudioBytes2
ブロックのバイト数を ppvAudioPtr2 で受け取る変数のアドレス。ppvAudioPtr2 が NULL の場合、値は 0 である。
dwFlags
ロック イベントに変更を加えるフラグ。この値は NULL または次のフラグである。
DSCBLOCK_ENTIREBUFFER
dwReadBytes を無視して、キャプチャ バッファ全体をロックする。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は、次のいずれかの値を返す。

DSERR_INVALIDPARAM
DSERR_INVALIDCALL

注意

このメソッドは、オフセットとバイト カウントを受け取り、2 つの読み込みポインタとそれぞれに関連するサイズを返す。ロックされる部分がバッファの最後まで拡張せず、バッファの先頭にラップされない場合、2 番目のポインタである ppvAudioBytes2 は NULL を受け取る。ロックがラップされる場合、ppvAudioBytes2 はバッファの先頭へのポインタを指す。

アプリケーションが ppvAudioPtr2 パラメータおよび pdwAudioBytes2 パラメータに対して NULL を渡すと、ロックがバッファの終端を越えることはなく、ラップされない。

アプリケーションは、このメソッドで返されたポインタからデータを読み込んだら、直ちに IDirectSoundCaptureBuffer8::Unlock を呼び出す必要がある。サウンド バッファは、動作中にロックしたままにするべきではない。ロックしたままにすると、キャプチャ カーソルがロックされたバイト領域に達し、オーディオの問題が発生する。

動作環境

ヘッダー : dsound.h で宣言。


IDirectSoundCaptureBuffer8::Start

バッファへのデータのキャプチャリングを開始する。バッファが既にキャプチャリングしている場合、このメソッドは何もしない。

HRESULT Start(
  DWORD dwFlags
);

パラメータ

dwFlags
サウンド データをキャプチャリングするときのバッファの動作を指定するフラグ。次のフラグが定義されている。
DSCBSTART_LOOPING
バッファの最後に達したら、先頭からキャプチャを再開し、明示的に停止されるまで続行する。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DSERR_INVALIDPARAM
DSERR_NODRIVER
DSERR_OUTOFMEMORY

動作環境

ヘッダー : dsound.h で宣言。


IDirectSoundCaptureBuffer8::Stop

バッファを停止して、データのキャプチャリングを終了する。バッファがキャプチャリングしていない場合、このメソッドは何もしない。

HRESULT Stop();

パラメータ

なし。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DSERR_NODRIVER
DSERR_OUTOFMEMORY

動作環境

ヘッダー : dsound.h で宣言。


IDirectSoundCaptureBuffer8::Unlock

バッファをアンロックする。

HRESULT Unlock(
  LPVOID pvAudioPtr1,
  DWORD dwAudioBytes1,
  LPVOID pvAudioPtr2,
  DWORD dwAudioBytes2
);

パラメータ

pvAudioPtr1
IDirectSoundCaptureBuffer8::Lock メソッドの ppvAudioPtr1 パラメータで取得した値のアドレス。
dwAudioBytes1
pvAudioPtr1 パラメータから読み込むバイト数。「注意」を参照すること。
pvAudioPtr2
IDirectSoundCaptureBuffer8::Lock メソッドの ppvAudioPtr2 パラメータで取得した値のアドレス。
dwAudioBytes2
pvAudioPtr2 パラメータから読み込むバイト数。「注意」を参照すること。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は、次のいずれかの値を返す。

DSERR_INVALIDPARAM
DSERR_INVALIDCALL

注意

アプリケーションは、IDirectSoundBuffer8::Lock メソッドで返されるポインタ pvAudioPtr1 および pvAudioPtr2 の両方を渡して、IDirectSoundBuffer8::Lock と IDirectSoundBuffer8::Unlock の対を正しく指定しなければならない。たとえ 2 番目のポインタに 0 バイトが書き込まれた場合でも、2 番目のポインタは必要である。

dwAudioBytes1 および dwAudioBytes2 の値は、バッファの各部分から実際に読み込むバイト数を指定しなければならない。ロックのサイズより小さくなる場合もある。DirectSound はこれらの値を使用して、デバイスから転送するデータ量を決定する。

サウンド キャプチャ バッファのロック状態を長時間維持しないよう注意すること。

動作環境

ヘッダー : dsound.h で宣言。


IDirectSoundCaptureFXAec8

現在のオペレーティング システム上に実装されていない。

聴感エコー解除をサポートするキャプチャ バッファで、パラメータの設定および取得に使用する。

IDirectSoundCaptureFXAec8 は、IDirectSoundCaptureFXAec の定義である。インターフェイス名は入れ替え可能である。

このインターフェイスは、エフェクトをサポートするバッファ上の IDirectSoundCaptureBuffer8::GetObjectInPath を呼び出すことによって取得する。

IDirectSoundCaptureFXAec8 インターフェイスは、次のメソッドをサポートする。

パラメータ | GetAllParameters
 | SetAllParameters

すべての COM インターフェイスと同様に、IDirectSoundCaptureFXAec8 インターフェイスは IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは次の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTSOUNDCAPTUREFXAEC8 型は、IDirectSoundCaptureFXAec8 インターフェイスへのポインタとして定義されている。

typedef struct IDirectSoundCaptureFXAec8 *LPDIRECTSOUNDCAPTUREFXAEC8;

動作環境

ヘッダー : dsound.h で宣言。


IDirectSoundCaptureFXAec8::GetAllParameters

現在のオペレーティング システム上に実装されていない。

バッファの聴感エコー解除パラメータを取得する。

HRESULT GetAllParameters(
  LPDSCFXAec pDscFxAec
);

パラメータ

pDscFxAec
エフェクト パラメータを受け取る DSCFXAec 構造体のアドレス。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

動作環境

ヘッダー : dsound.h で宣言。


IDirectSoundCaptureFXAec8::SetAllParameters

現在のオペレーティング システム上に実装されていない。

バッファの聴感エコー解除パラメータを設定する。

HRESULT SetAllParameters(
  LPCDSCFXAec  pcDscFxAec
);

パラメータ

pcDscFxAec
エフェクト パラメータを指定する DSCFXAec 構造体のアドレス。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

動作環境

ヘッダー : dsound.h で宣言。


IDirectSoundCaptureFXNoiseSuppress8

現在のオペレーティング システム上に実装されていない。

ノイズ抑制をサポートするキャプチャ バッファで、パラメータの設定および取得に使用する。

IDirectSoundCaptureFXNoiseSuppress8 は IDirectSoundCaptureFXNoiseSuppress の定義である。インターフェイス名は入れ替え可能である。

このインターフェイスは、エフェクトをサポートするバッファ上の IDirectSoundCaptureBuffer8::GetObjectInPath を呼び出すことによって取得する。

IDirectSoundCaptureFXNoiseSuppress8 インターフェイスは、次のメソッドをサポートする。

パラメータ | GetAllParameters
 | SetAllParameters

すべての COM インターフェイスと同様に、IDirectSoundNoiseSuppress8 インターフェイスは IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは次の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTSOUNDNOISESUPPRESS8 型は、IDirectSoundNoiseSuppress8 インターフェイスへのポインタとして定義されている。

typedef struct IDirectSoundCaptureFXNoiseSuppress8  *LPDIRECTSOUNDCAPTUREFXNOISESUPPRESS8;

動作環境

ヘッダー : dsound.h で宣言。


IDirectSoundCaptureFXNoiseSuppress8::GetAllParameters

現在のオペレーティング システム上に実装されていない。

バッファのノイズ抑制パラメータを取得する。

HRESULT GetAllParameters(
  LPDSCFXNoiseSuppress pDsFxNoiseSuppress
);

パラメータ

pDscFxNoiseSuppress
エフェクト パラメータを受け取る DSCFXNoiseSuppress 構造体のアドレス。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

動作環境

ヘッダー : dsound.h で宣言。


IDirectSoundCaptureFXNoiseSuppress8::SetAllParameters

現在のオペレーティング システム上に実装されていない。

バッファのノイズ抑制パラメータを設定する。

HRESULT SetAllParameters(
  LPCDSCFXNoiseSuppression  pcDscFxNoiseSuppress
);

パラメータ

pcDscFxNoiseSuppress
エフェクト パラメータを受け取る DSCFXNoiseSuppress 構造体のアドレス。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

動作環境

ヘッダー : dsound.h で宣言。


IDirectSoundFullDuplex8

現在のオペレーティング システム上に実装されていない。

全二重ストリームを表す。

このインターフェイスは、DirectSoundFullDuplexCreate8 関数を使用して取得する。この関数は、DirectSound キャプチャと再生を初期化する。

インターフェイスを CoCreateInstance または CoCreateInstanceEx を使って取得し、クラス CLSID_DirectSoundFullDuplex8 のオブジェクトを作成することもできる。

IDirectSoundFullDuplex8 は IDirectSoundFullDuplex の定義である。インターフェイス名は入れ替え可能である。

このインターフェイスは、次のメソッドをサポートする。

初期化 Initialize

すべての COM インターフェイスは、IUnknown インターフェイス メソッドを継承する。このインターフェイスは次の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTSOUNDFULLDUPLEX 型は、IDirectSoundFullDuplex へのポインタとして定義されている。

typedef struct IDirectSoundFullDuplex *LPDIRECTSOUNDFULLDUPLEX;

動作環境

ヘッダー : dsound.h で宣言。


IDirectSoundFullDuplex8::Initialize

CoCreateInstance を使って作成された全二重オブジェクトを初期化する。

HRESULT Initialize(
  LPCGUID  pCaptureGuid,
  LPCGUID  pRenderGuid,
  LPCDSCBUFFERDESC  lpDscBufferDesc,
  LPCDSBUFFERDESC  lpDsBufferDesc,
  HWND  hWnd,
  DWORD  dwLevel,
  LPLPDIRECTSOUNDCAPTUREBUFFER8  lplpDirectSoundCaptureBuffer8,
  LPLPDIRECTSOUNDBUFFER8  lplpDirectSoundBuffer8
);

パラメータ

pCaptureGuid
全二重入力に対してサウンド キャプチャ デバイスを識別する GUID のアドレス。DirectSoundCaptureEnumerate が返す GUID のいずれか、デフォルトのキャプチャ デバイスを指定する NULL、または次の値のいずれかでなければならない。
DSDEVID_DefaultCapture
システムワイドなデフォルトのオーディオ キャプチャ デバイス。
DSDEVID_DefaultVoiceCapture
デフォルトの音声キャプチャ デバイス。
pRenderGuid
全二重出力に対してサウンド レンダリング デバイスを識別する GUID のアドレス。DirectSoundEnumerate が返す GUID のいずれか、またはデフォルトのレンダリング デバイスを指定する NULL でなければならない。
DSDEVID_DefaultPlayback
システムワイドなデフォルトのオーディオ再生デバイス。
DSDEVID_DefaultVoicePlayback
デフォルトの音声再生デバイス。
lpDscBufferDesc
キャプチャ バッファの特性を指定する DSCBUFFERDESC 構造体のアドレス。
lpDsBufferDesc
レンダリング バッファの特性を指定する DSBUFFERDESC 構造体のアドレス。
hWnd
アプリケーション ウインドウへのハンドル。
dwLevel
DirectSound オブジェクトの協調レベル。詳細については、「IDirectSound8::SetCooperativeLevel」を参照すること。
lplpDirectSoundCaptureBuffer8
キャプチャ バッファの IDirectSoundCaptureBuffer8 インターフェイスを受け取る変数のアドレス。
lplpDirectSoundBuffer8
レンダリング バッファの IDirectSoundBuffer8 インターフェイスを受け取る変数のアドレス。

動作環境

ヘッダー : dsound.h で宣言。


IDirectSoundFXChorus8

コーラスをサポートするバッファで、エフェクト パラメータの設定および取得に使用する。

このインターフェイスは、エフェクトをサポートするバッファ上の IDirectSoundBuffer8::GetObjectInPath を呼び出すことによって取得する。

IDirectSoundFXChorus8 インターフェイスは、次のメソッドをサポートする。

パラメータ | GetAllParameters
 | SetAllParameters

すべての COM インターフェイスは、IUnknown インターフェイス メソッドを継承する。このインターフェイスは次の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSoundBuffer8::SetFX


IDirectSoundFXChorus8::GetAllParameters

バッファのコーラス パラメータを取得する。

HRESULT GetAllParameters(
  LPDSFXChorus pDsFxChorus
);

パラメータ

pDsFxChorus
エフェクト パラメータを受け取る DSFXChorus 構造体のアドレス。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

動作環境

ヘッダー : dsound.h で宣言。


IDirectSoundFXChorus8::SetAllParameters

バッファのコーラス パラメータを設定する。

HRESULT SetAllParameters(
  LPCDSFXChorus  pcDsFxChorus
);

パラメータ

pcDsFxChorus
エフェクト パラメータを指定する DSFXChorus 構造体のアドレス。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

動作環境

ヘッダー : dsound.h で宣言。

参照

エフェクト パラメータ


IDirectSoundFXCompressor8

圧縮をサポートするバッファで、エフェクト パラメータの設定および取得に使用する。

このインターフェイスは、エフェクトをサポートするバッファ上の IDirectSoundBuffer8::GetObjectInPath を呼び出すことによって取得する。

IDirectSoundFXCompressor8 インターフェイスは、次のメソッドをサポートする。

パラメータ | GetAllParameters
 | SetAllParameters

すべての COM インターフェイスは、IUnknown インターフェイス メソッドを継承する。このインターフェイスは次の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSoundBuffer8::SetFX、コンプレッション


IDirectSoundFXCompressor8::GetAllParameters

バッファのコンプレッサ パラメータを取得する。

HRESULT GetAllParameters(
  LPDSFXCompressor pDsFxCompressor
);

パラメータ

pDsFxCompressor
エフェクト パラメータを受け取る DSFXCompressor 構造体のアドレス。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

動作環境

ヘッダー : dsound.h で宣言。


IDirectSoundFXCompressor8::SetAllParameters

バッファのコンプレッサ パラメータを設定する。

HRESULT SetAllParameters(
  LPCDSFXCompressor pcDsFxCompressor
);

パラメータ

pcDsFxCompressor
エフェクト パラメータを指定する DSFXCompressor 構造体のアドレス。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

動作環境

ヘッダー : dsound.h で宣言。

参照

エフェクト パラメータ


IDirectSoundFXDistortion8

ディストーションをサポートするバッファで、エフェクト パラメータの設定および取得に使用する。

このインターフェイスは、エフェクトをサポートするバッファ上の IDirectSoundBuffer8::GetObjectInPath を呼び出すことによって取得する。

IDirectSoundFXDistortion8 インターフェイスは、次のメソッドをサポートする。

パラメータ | GetAllParameters
 | SetAllParameters

すべての COM インターフェイスは、IUnknown インターフェイス メソッドを継承する。このインターフェイスは次の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSoundBuffer8::SetFX


IDirectSoundFXDistortion8::GetAllParameters

バッファのディストーション パラメータを取得する。

HRESULT GetAllParameters(
  LPDSFXDistortion  pDsFxDistortion
);

パラメータ

pDsFxDistortion
エフェクト パラメータを受け取る DSFXDistortion 構造体のアドレス。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

動作環境

ヘッダー : dsound.h で宣言。


IDirectSoundFXDistortion8::SetAllParameters

バッファのディストーション パラメータを設定する。

HRESULT SetAllParameters(
  LPCDSFXDistortion  pcDsFxDistortion
);

パラメータ

pcDsFxDistortion
エフェクト パラメータを指定する DSFXDistortion 構造体のアドレス。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

動作環境

ヘッダー : dsound.h で宣言。

参照

エフェクト パラメータ


IDirectSoundFXEcho8

エコーをサポートするバッファで、エフェクト パラメータの設定および取得に使用する。

このインターフェイスは、エフェクトをサポートするバッファ上の IDirectSoundBuffer8::GetObjectInPath を呼び出すことによって取得する。

IDirectSoundFXEcho8 インターフェイスは、次のメソッドをサポートする。

パラメータ | GetAllParameters
 | SetAllParameters

すべての COM インターフェイスは、IUnknown インターフェイス メソッドを継承する。このインターフェイスは次の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSoundBuffer8::SetFX


IDirectSoundFXEcho8::GetAllParameters

バッファのエコー パラメータを取得する。

HRESULT GetAllParameters(
  LPDSFXEcho pDsFxEcho
);

パラメータ

pDsFxEcho
エフェクト パラメータを受け取る DSFXEcho 構造体のアドレス。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

動作環境

ヘッダー : dsound.h で宣言。


IDirectSoundFXEcho8::SetAllParameters

バッファのエコー パラメータを設定する。

HRESULT SetAllParameters(
  LPCDSFXEcho  pcDsFxEcho
);

パラメータ

pcDsFxEcho
エフェクト パラメータを指定する DSFXEcho 構造体のアドレス。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

動作環境

ヘッダー : dsound.h で宣言。

参照

エフェクト パラメータ


IDirectSoundFXFlanger8

フランジをサポートするバッファで、エフェクト パラメータの設定および取得に使用する。

このインターフェイスは、エフェクトをサポートするバッファ上の IDirectSoundBuffer8::GetObjectInPath を呼び出すことによって取得する。

IDirectSoundFXFlanger8 インターフェイスは、次のメソッドをサポートする。

パラメータ | GetAllParameters
 | SetAllParameters

すべての COM インターフェイスは、IUnknown インターフェイス メソッドを継承する。このインターフェイスは次の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSoundBuffer8::SetFX


IDirectSoundFXFlanger8::GetAllParameters

バッファのフランジ パラメータを取得する。

HRESULT GetAllParameters(
  LPDSFXFlanger  pDsFxFlanger
);

パラメータ

pDsFxFlanger
エフェクト パラメータを受け取る DSFXFlanger 構造体のアドレス。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

動作環境

ヘッダー : dsound.h で宣言。


IDirectSoundFXFlanger8::SetAllParameters

バッファのフランジ パラメータを設定する。

HRESULT SetAllParameters(
  LPCDSFXFlanger pcDsFxFlanger
);

パラメータ

pcDsFxFlanger
エフェクト パラメータを指定する DSFXFlanger 構造体のアドレス。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

動作環境

ヘッダー : dsound.h で宣言。

参照

エフェクト パラメータ


IDirectSoundFXGargle8

振幅変調をサポートするバッファで、エフェクト パラメータの設定および取得に使用する。

このインターフェイスは、エフェクトをサポートするバッファ上の IDirectSoundBuffer8::GetObjectInPath を呼び出すことによって取得する。

IDirectSoundFXGargle8 インターフェイスは、次のメソッドをサポートする。

パラメータ | GetAllParameters
 | SetAllParameters

すべての COM インターフェイスは、IUnknown インターフェイス メソッドを継承する。このインターフェイスは次の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSoundBuffer8::SetFX


IDirectSoundFXGargle8::GetAllParameters

バッファの振幅変調パラメータを取得する。

HRESULT GetAllParameters(
  LPDSFXGargle  pDsFxGargle
);

パラメータ

pDsFxGargle
エフェクト パラメータを受け取る DSFXGargle 構造体のアドレス。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

動作環境

ヘッダー : dsound.h で宣言。


IDirectSoundFXGargle8::SetAllParameters

バッファの振幅変調パラメータを設定する。

HRESULT SetAllParameters(
  LPCDSFXGargle  pcDsFxGargle
);

パラメータ

pcDsFxGargle
エフェクト パラメータを指定する DSFXGargle 構造体のアドレス。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

動作環境

ヘッダー : dsound.h で宣言。

参照

エフェクト パラメータ


IDirectSoundFXI3DL2Reverb8

I3DL2 (Interactive 3D Audio Level 2) リバーブ エフェクトをサポートするバッファで、エフェクト パラメータの設定および取得に使用する。

このインターフェイスは、エフェクトをサポートするバッファ上の IDirectSoundBuffer8::GetObjectInPath を呼び出すことによって取得する。

IDirectSoundFXI3DL2Reverb8 インターフェイスは、次のメソッドをサポートする。

パラメータ | GetAllParameters
 | GetQuality
 | SetAllParameters
 | SetQuality
プリセット | GetPreset
 | SetPreset

すべての COM インターフェイスは、IUnknown インターフェイス メソッドを継承する。このインターフェイスは次の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSoundBuffer8::SetFX


IDirectSoundFXI3DL2Reverb8::GetAllParameters

バッファの I3DL2 環境リバーブ パラメータを取得する。

HRESULT GetAllParameters(
  LPDSFXI3DL2Reverb pDsFxI3DL2Reverb
);

パラメータ

pDsFxI3DL2Reverb
エフェクト パラメータを受け取る DSFXI3DL2Reverb 構造体のアドレス。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

動作環境

ヘッダー : dsound.h で宣言。


IDirectSoundFXI3DL2Reverb8::GetPreset

バッファの標準リバーブ パラメータの識別子を取得する。

HRESULT GetPreset(
  LPDWORD  pdwPreset
);

パラメータ

pdwPreset

プリセット識別子の 1 つを受け取る DWORD のアドレス。定義済みの値の一覧については、「IDirectSoundFXI3DL2Reverb8::SetPreset」を参照すること。

成功した場合は DS_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DSERR_INVALIDPARAM
DSERR_INVALIDCALL

動作環境

ヘッダー : dsound.h で宣言。


IDirectSoundFXI3DL2Reverb8::GetQuality

環境リバーブ エフェクトの品質を取得する。

HRESULT GetQuality(
  LONG * plQuality
);

パラメータ

plQuality
エフェクトの品質を受け取る LONG 変数のアドレス。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSoundFXI3DL2Reverb8::SetQuality


IDirectSoundFXI3DL2Reverb8::SetAllParameters

バッファの I3DL2 環境リバーブ パラメータを設定する。

HRESULT SetAllParameters(
  LPCDSFXI3DL2Reverb  pcDsFxI3DL2Reverb
);

パラメータ

pcDsFxI3DL2Reverb
エフェクト パラメータを指定する DSFXI3DL2Reverb 構造体のアドレス。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

動作環境

ヘッダー : dsound.h で宣言。

参照

エフェクト パラメータ


IDirectSoundFXI3DL2Reverb8::SetPreset

バッファの標準リバーブ パラメータを指定する。

HRESULT SetPreset(
  DWORD  dwPreset
);

パラメータ

dwPreset
プリセットを指定する値。次の定数が列挙される。あらかじめ設定された各識別子に関連するデフォルト値については、Dsound.h を参照すること。
DSFX_I3DL2_ENVIRONMENT_PRESET_DEFAULT
DSFX_I3DL2_ENVIRONMENT_PRESET_GENERIC
DSFX_I3DL2_ENVIRONMENT_PRESET_PADDEDCELL
DSFX_I3DL2_ENVIRONMENT_PRESET_ROOM
DSFX_I3DL2_ENVIRONMENT_PRESET_BATHROOM
DSFX_I3DL2_ENVIRONMENT_PRESET_LIVINGROOM
DSFX_I3DL2_ENVIRONMENT_PRESET_STONEROOM
DSFX_I3DL2_ENVIRONMENT_PRESET_AUDITORIUM
DSFX_I3DL2_ENVIRONMENT_PRESET_CONCERTHALL
DSFX_I3DL2_ENVIRONMENT_PRESET_CAVE
DSFX_I3DL2_ENVIRONMENT_PRESET_ARENA
DSFX_I3DL2_ENVIRONMENT_PRESET_HANGAR
DSFX_I3DL2_ENVIRONMENT_PRESET_CARPETEDHALLWAY
DSFX_I3DL2_ENVIRONMENT_PRESET_HALLWAY
DSFX_I3DL2_ENVIRONMENT_PRESET_STONECORRIDOR
DSFX_I3DL2_ENVIRONMENT_PRESET_ALLEY
DSFX_I3DL2_ENVIRONMENT_PRESET_FOREST
DSFX_I3DL2_ENVIRONMENT_PRESET_CITY
DSFX_I3DL2_ENVIRONMENT_PRESET_MOUNTAINS
DSFX_I3DL2_ENVIRONMENT_PRESET_QUARRY
DSFX_I3DL2_ENVIRONMENT_PRESET_PLAIN
DSFX_I3DL2_ENVIRONMENT_PRESET_PARKINGLOT
DSFX_I3DL2_ENVIRONMENT_PRESET_SEWERPIPE
DSFX_I3DL2_ENVIRONMENT_PRESET_UNDERWATER
DSFX_I3DL2_ENVIRONMENT_PRESET_SMALLROOM
DSFX_I3DL2_ENVIRONMENT_PRESET_MEDIUMROOM
DSFX_I3DL2_ENVIRONMENT_PRESET_LARGEROOM
DSFX_I3DL2_ENVIRONMENT_PRESET_MEDIUMHALL
DSFX_I3DL2_ENVIRONMENT_PRESET_LARGEHALL
DSFX_I3DL2_ENVIRONMENT_PRESET_PLATE

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

動作環境

ヘッダー : dsound.h で宣言。

参照

エフェクト パラメータ


IDirectSoundFXI3DL2Reverb8::SetQuality

環境リバーブ エフェクトの品質を設定する。高い値を設定すると、エフェクトの品質は良くなるが、処理にかかる時間が長くなる。

HRESULT SetQuality(
  LONG lQuality
);

パラメータ

lQuality
エフェクトの品質を指定する値。値の範囲は、DSFX_I3DL2REVERB_QUALITY_MIN が最小で DSFX_I3DL2REVERB_QUALITY_MAX が最大。デフォルトは 2 である。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSoundFXI3DL2Reverb8::GetQuality、エフェクト パラメータ


IDirectSoundFXParamEq8

パラメトリック イコライザ エフェクトをサポートするバッファで、エフェクト パラメータの設定および取得に使用する。

IDirectSoundFXParamEq8 インターフェイスは、次のメソッドをサポートする。

パラメータ | GetAllParameters
 | SetAllParameters

すべての COM インターフェイスは、IUnknown インターフェイス メソッドを継承する。このインターフェイスは次の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSoundBuffer8::SetFX


IDirectSoundFXParamEq8::GetAllParameters

バッファのパラメトリック イコライザのパラメータを取得する。

HRESULT GetAllParameters(
  LPDSFXParamEq pDsFxParamEq
);

パラメータ

pDsFxParamEq
エフェクト パラメータを受け取る DSFXParamEq 構造体のアドレス。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

動作環境

ヘッダー : dsound.h で宣言。


IDirectSoundFXParamEq8::SetAllParameters

バッファのパラメトリック イコライザのパラメータを設定する。

HRESULT SetAllParameters(
  LPCDSFXParamEq  pcDsFxParamEq
);

パラメータ

pcDsFxParamEq
エフェクト パラメータを指定する DSFXParamEq 構造体のアドレス。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

動作環境

ヘッダー : dsound.h で宣言。

参照

エフェクト パラメータ


IDirectSoundFXWavesReverb8

ミュージック リバーブをサポートするバッファのエフェクト パラメータの設定および取得に使用する。

このインターフェイスは、エフェクトをサポートするバッファ上の IDirectSoundBuffer8::GetObjectInPath を呼び出すことによって取得する。

IDirectSoundFXWavesReverb8 インターフェイスは、次のメソッドをサポートする。

パラメータ | GetAllParameters
 | SetAllParameters

すべての COM インターフェイスは、IUnknown インターフェイス メソッドを継承する。このインターフェイスは次の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

注意

ウェーブ リバーブ DMO は、Microsoft にライセンスされている Waves MaxxVerb テクノロジに基づいている。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSoundBuffer8::SetFX


IDirectSoundFXWavesReverb8::GetAllParameters

バッファのミュージック リバーブ パラメータを取得する。

HRESULT GetAllParameters(
  LPDSFXWavesReverb  pDsFXWavesReverb
);

パラメータ

pDsFXWavesReverb
エフェクト パラメータを受け取る DSFXWavesReverb 構造体のアドレス。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

動作環境

ヘッダー : dsound.h で宣言。


IDirectSoundFXWavesReverb8::SetAllParameters

バッファのミュージック リバーブ パラメータを設定する。

HRESULT SetAllParameters(
  LPCDSFXWavesReverb  pcDsFXWavesReverb
);

パラメータ

pcDsFXWavesReverb
エフェクト パラメータを指定する DSFXWavesReverb 構造体のアドレス。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

動作環境

ヘッダー : dsound.h で宣言。

参照

エフェクト パラメータ


IDirectSoundNotify8

再生またはキャプチャ バッファの通知イベントを設定する。

IDirectSoundNotify8 は IDirectSoundNotify の定義である。2 つのインターフェイス名は入れ替え可能である。

DirectSoundBuffer オブジェクト上の既存のインターフェイスに対して QueryInterface メソッドを呼び出して、このインターフェイスを取得する。具体的な例については、「再生バッファの通知」を参照すること。

IDirectSoundNotify インターフェイスは、次のメソッドをサポートする。

SetNotificationPositions

すべての COM インターフェイスと同様に、IDirectSoundNotify8 インターフェイスも IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは次の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTSOUNDNOTIFY 型は、IDirectSoundNotify インターフェイスへのポインタとして定義されている。

typedef struct IDirectSoundNotify    *LPDIRECTSOUNDNOTIFY;

動作環境

ヘッダー : dsound.h で宣言。


IDirectSoundNotify8::SetNotificationPositions

通知位置を設定する。キャプチャや再生の間、呼び出し側が提供した配列内の DSBPOSITIONNOTIFY 構造体のいずれかで指定されているオフセットに読み込みまたは再生カーソルが達すると、関連するイベントがシグナル送信される。

HRESULT SetNotificationPositions(
  DWORD dwPositionNotifies,
  LPCDSBPOSITIONNOTIFY pcPositionNotifies
);

パラメータ

dwPositionNotifies
DSBPOSITIONNOTIFY 構造体の数。
pcPositionNotifies
DSBPOSITIONNOTIFY 構造体から成る配列へのポインタ。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DSERR_INVALIDPARAM
DSERR_OUTOFMEMORY

注意

dwOffset メンバで値 DSBPN_OFFSETSTOP を指定すると、IDirectSoundBuffer8::Stop や IdirectSoundCaptureBuffer8::Stop メソッドを呼び出したとき、またはバッファの最後に達してループ再生を行わないときに、関連イベントをシグナル送信するよう DirectSound に指示できる。この値を使うときは、位置通知配列の最後の項目とすべきである。

位置通知配列が既に設定されている場合は、メソッドによって以前の配列が置き換えられる。

このメソッドを呼び出すときは、バッファを停止させなければならない。

動作環境

ヘッダー : dsound.h で宣言。


IKsPropertySet

ドライバはこのインターフェイスを使うことにより、API を拡張することなく利用できる拡張機能を提供できる。DirectSound は、サウンド ドライバのプロパティにアクセスできるよう、このインターフェイスをサポートする。

IKsPropertySet インターフェイスは、WDM KS (Win32® ドライバ モデルのカーネル ストリーミング) アーキテクチャの一部である。

DirectSound バッファの任意のインターフェイスの QueryInterface メソッドを呼び出して、このインターフェイスを取得する。

IKsPropertySet インターフェイスは、次のメソッドをサポートする。

IKsPropertySet | Get
 | QuerySupport
 | Set

すべての COM インターフェイスは、IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは次の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

動作環境

ヘッダー : dsound.h で宣言。


IKsPropertySet::Get

プロパティ セット内の特定の項目に対応するデータを取得する。

HRESULT Get(
  REFGUID rguidPropSet,
  ULONG ulId,
  LPVOID pInstanceData,
  ULONG ulInstanceLength,
  LPVOID pPropertyData,
  ULONG ulDataLength,
  PULONG pulBytesReturned
);

パラメータ

rguidPropSet
アクセスすべきプロパティ セットを表す GUID への参照 (C++) またはアドレス (C)。
ulId
アクセスすべきプロパティ セット内の項目。項目は 0 から始まるインデックス番号を割り当てられており、特定のプロパティ セット GUID では常に同じである。
pInstanceData
Get 呼び出しの対象となるインスタンス データ。
ulInstanceLength
pInstanceData が指すバイト数。
pPropertyData
この項目から取得されるデータ。
ulDataLength
pPropertyData が指すバイト数。
pulBytesReturned
pPropertyData に書き込まれたバイト数を受け取る変数のアドレス。

戻り値

戻り値は、プロパティ セットの設計者によって決定される。

成功した場合は S_OK を返す。

失敗すると、メソッドは 1 つの E_POINTER を返す。

注意

pInstanceData と pPropertyData の各データのフォーマットは、項目ごとに異なる。

動作環境

ヘッダー : dsound.h で宣言。


IKsPropertySet::QuerySupport

プロパティ セット内のプロパティが、ポートまたはデバイスによってサポートされているかどうかを決定する。

HRESULT QuerySupport(
  REFGUID rguidPropSet,
  ULONG ulId,
  PULONG pulTypeSupport
);

パラメータ

rguidPropSet
問い合わせるべきプロパティ セットを表す GUID への参照 (C++) またはアドレス (C)。
ulId
アクセスすべきプロパティ セット内の項目。項目は 0 から始まるインデックス番号を割り当てられており、特定のプロパティ セット GUID では常に同じである。
pulTypeSupport
プロパティのサポートに関する情報を受け取る変数のアドレス。この変数は、次のフラグのいずれかまはた両方を受け取ることができる。「注意」を参照すること。
KSPROPERTY_SUPPORT_GET
プロパティ項目は取得できる。
KSPROPERTY_SUPPORT_SET
プロパティ項目は設定できる。

戻り値

戻り値は、プロパティ セットの設計者によって決定される。

成功した場合は S_OK を返す。「注意」を参照すること。

失敗した場合は、次のいずれかのエラー値を返す。

E_NOTIMPL (「注意」を参照)
E_POINTER

注意

セット内で特定のプロパティをサポートするかどうかは、プロパティ セットの定義に依存する。関心のあるプロパティ セットについては、ハードウェア メーカーの仕様を参照すること。

ある仕様ではプロパティがサポートされていない場合に S_OK を返し、ほかの仕様では E_NOTIMPL を返す。プロパティがサポートされているかどうかを確認するには、このメソッドの戻り値と、pulTypeSupport の戻り値の両方をチェックする。S_OK が返されても、pulTypeSupport に有効なフラグが含まれていない場合は、そのプロパティはサポートされていない。

動作環境

ヘッダー : dsound.h で宣言。


IKsPropertySet::Set

プロパティ セット内の特定のプロパティの値を設定する。

HRESULT Set(
  REFGUID rguidPropSet,
  ULONG ulId,
  LPVOID pInstanceData,
  ULONG ulInstanceLength,
  LPVOID pPropertyData,
  ULONG ulDataLength
);

パラメータ

rguidPropSet
アクセスすべきプロパティ セットを表す GUID への参照 (C++) またはアドレス (C)。
ulId
アクセスすべきプロパティ セット内の項目。項目は 0 から始まるインデックス番号を割り当てられており、特定のプロパティ セット GUID では常に同じである。
pInstanceData
Set 呼び出しの対象となるインスタンス データ。この操作を実行できるオブジェクトがポート内に複数存在する場合、インスタンス データはどのオブジェクトを使うべきかを指定する。DirectMusic® API レベルでは、標準的なプロパティ セットのどの項目もインスタンス データを使っていない。しかし、ベンダーが定義した拡張では、インスタンス データを自由に使ってよい。
ulInstanceLength
pInstanceData が指すバイト数。
pPropertyData
この項目に設定されるプロパティ データ。
ulDataLength
pPropertyData が指すバイト数。

戻り値

戻り値は、プロパティ セットの設計者によって決定される。

成功した場合は S_OK を返す。

失敗すると、メソッドは 1 つの E_POINTER を返す。

注意

pInstanceData と pPropertyData の各データのフォーマットは、項目ごとに異なる。

動作環境

ヘッダー : dsound.h で宣言。


DirectSound コールバック関数

ここでは、DirectSound コールバック関数のリファレンス情報を記述する。

  • DSEnumCallback


DSEnumCallback

DirectSound ドライバを列挙するアプリケーション定義コールバック関数。アプリケーションが直前に呼び出した DirectSoundEnumerate 関数または DirectSoundCaptureEnumerate 関数に応答して、システムはこの関数を呼び出す。

BOOL CALLBACK DSEnumCallback(
  LPGUID lpGuid,
  LPCSTR lpcstrDescription,
  LPCSTR lpcstrModule,
  LPVOID lpContext
);

パラメータ

lpGuid
列挙中の DirectSound ドライバを識別する GUID のアドレス。この値を DirectSoundCreate8 関数に渡すと、ドライバの DirectSound オブジェクトを作成できる。
lpcstrDescription
DirectSound デバイスのテキスト記述を提供する、NULL で終わる文字列のアドレス。
lpcstrModule
このデバイスに対応する DirectSound ドライバのモジュール名を指定する、NULL で終わる文字列のアドレス。
lpContext
アプリケーション定義データのアドレス。これは、lpContext パラメータとして DirectSoundEnumerate または DirectSoundCaptureEnumerate に渡されるポインタである。

戻り値

ドライバの列挙が続く場合は TRUE、終了する場合は FALSE を返す。

注意

アプリケーションは lpstrDescription と lpstrModule の各パラメータに渡された文字列を、ヒープから割り当てられたメモリにコピーすることにより、これらの文字列を保存できる。文字列をこのコールバック関数へ渡すために使われたメモリは、このコールバック関数が実行中のときにのみ有効になる。

動作環境

ヘッダー : dsound.h で宣言。

参照

DirectSoundEnumerate


DirectSound 関数

ここでは、DirectSound と DirectSoundCapture の次のグローバル関数のリファレンス情報を記述する。

  • DirectSoundCaptureCreate8
  • DirectSoundFullDuplexCreate8
  • DirectSoundCaptureEnumerate
  • DirectSoundCreate8
  • DirectSoundEnumerate
  • GetDeviceID


DirectSoundCaptureCreate8

IDirectSoundCapture8 インターフェイスをサポートするオブジェクトを作成および初期化する。

この関数は、キャプチャ エフェクトをサポートするオブジェクトを作成する。以前の DirectSoundCaptureCreate 関数を使って IDirectSoundCapture8 インターフェイスを取得することもできるが、この場合、作成されたオブジェクトは IDirectSoundCaptureBuffer8 インターフェイスをサポートするキャプチャ バッファを作成するために利用できない。

HRESULT WINAPI DirectSoundCaptureCreate8(
  LPCGUID lpcGUID,
  LPDIRECTSOUNDCAPTURE8 *lplpDSC,
  LPUNKNOWN pUnkOuter
);

パラメータ

lpcGUID
サウンド キャプチャ デバイスを識別する GUID のアドレス。このパラメータの値は、DirectSoundCaptureEnumerate が返した GUID のいずれか、デフォルトのデバイスを指定する NULL、または次のいずれかの値でなければならない。
DSDEVID_DefaultCapture
システムワイドなデフォルトのオーディオ キャプチャ デバイス。
DSDEVID_DefaultVoiceCapture
デフォルトの音声キャプチャ デバイス。
lplpDSC
IDirectSoundCapture8 インターフェイス ポインタを受け取る変数のアドレス。
pUnkOuter
COM 集成体に対する制御オブジェクトの IUnknown インターフェイスのアドレス。集成体はサポートされていないため、NULL に設定しなければならない。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DSERR_ALLOCATED
DSERR_INVALIDPARAM
DSERR_NOAGGREGATION
DSERR_OUTOFMEMORY

注意

全二重をサポートしないサウンド カードでは、このメソッドは失敗し、DSERR_ALLOCATED を返す。

動作環境

ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。


DirectSoundCaptureEnumerate

システムにインストールされている DirectSoundCapture オブジェクトを列挙する。

HRESULT WINAPI DirectSoundCaptureEnumerate(
  LPDSENUMCALLBACK lpDSEnumCallback,
  LPVOID lpContext
);

パラメータ

lpDSEnumCallback
DSEnumCallback 関数のアドレス。この関数は、システムにインストールされている各 DirectSoundCapture オブジェクトに対して呼び出される。
lpContext
ユーザー定義コンテキストのアドレス。列挙型コールバック関数を呼び出すたびに、その関数にこのコンテキストが渡される。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

動作環境

ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。


DirectSoundCreate8

IDirectSound8 インターフェイスをサポートするオブジェクトを作成および初期化する。

HRESULT WINAPI DirectSoundCreate8(
  LPCGUID lpcGuidDevice,
  LPDIRECTSOUND8 * ppDS8,
  LPUNKNOWN  pUnkOuter
);

パラメータ

lpcGuidDevice
サウンド デバイスを識別する GUID のアドレス。このパラメータの値は、DirectSoundEnumerate が返した GUID のいずれか、またはデフォルトのデバイスを指定する NULL、または次のいずれかの値でなければならない。
DSDEVID_DefaultPlayback
システムワイドなデフォルトのオーディオ再生デバイス。NULL に等しい。
DSDEVID_DefaultVoicePlayback
デフォルトの音声再生デバイス。
ppDS8
IDirectSound8 インターフェイス ポインタを受け取る変数のアドレス。
pUnkOuter
COM 集成体に対する制御オブジェクトの IUnknown インターフェイスのアドレス。集成体はサポートされていないため、NULL に設定しなければならない。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DSERR_ALLOCATED
DSERR_INVALIDPARAM
DSERR_NOAGGREGATION
DSERR_NODRIVER
DSERR_OUTOFMEMORY

注意

アプリケーションは DirectSound オブジェクトを作成した直後に、IDirectSound8::SetCooperativeLevel メソッドを呼び出さなければならない。

動作環境

ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。

参照

IDirectSound8::GetCaps、IDirectSound8::SetCooperativeLevel


DirectSoundEnumerate

システムにインストールされている DirectSound ドライバを列挙する。

HRESULT WINAPI DirectSoundEnumerate(
  LPDSENUMCALLBACK lpDSEnumCallback,
  LPVOID lpContext
);

パラメータ

lpDSEnumCallback
DSEnumCallback 関数のアドレス。この関数は、システムにインストールされている各 DirectSound オブジェクトに対して呼び出される。
lpContext
ユーザー定義コンテキストのアドレス。列挙型コールバック関数を呼び出すたびに、その関数にこのコンテキストが渡される。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

動作環境

ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。


DirectSoundFullDuplexCreate8

DirectSound および DirectSoundCapture オブジェクトを作成し、IDirectSoundFullDuplex8 インターフェイスを返す。

現在のオペレーティング システムでは、IDirectSoundFullDuplex8 オブジェクトはサポートされていない。ただし、全二重操作で必要なほかのオブジェクトを設定する際に、この関数を使うと便利である。

HRESULT WINAPI DirectSoundFullDuplexCreate8(
  LPCGUID pcGuidCaptureDevice,
  LPCGUID pcGuidRenderDevice,
  LPCDSCBUFFERDESC pcDSCBufferDesc,
  LPCDSBUFFERDESC pcDSBufferDesc,
  HWND hWnd,
  DWORD dwLevel,
  LPDIRECTSOUNDFULLDUPLEX* ppDSFD,
  LPDIRECTSOUNDCAPTUREBUFFER8 *ppDSCBuffer8,
  LPDIRECTSOUNDBUFFER8 *ppDSBuffer8,
  LPUNKNOWN pUnkOuter
);

パラメータ

pcGuidCaptureDevice
全二重入力に対してサウンド キャプチャ デバイスを識別する GUID のアドレス。DirectSoundCaptureEnumerate が返す GUID のいずれか、デフォルトのキャプチャ デバイスを指定する NULL、または次の値のいずれかでなければならない。
DSDEVID_DefaultCapture
システムワイドなデフォルトのオーディオ キャプチャ デバイス。
DSDEVID_DefaultVoiceCapture
デフォルトの音声キャプチャ デバイス。
pcGuidRenderDevice
全二重出力に対してサウンド レンダリング デバイスを識別する GUID のアドレス。DirectSoundEnumerate が返す GUID のいずれか、デフォルトのレンダリング デバイスを指定する NULL、または次の値のいずれかでなければならない。
DSDEVID_DefaultPlayback
システムワイドなデフォルトのオーディオ再生デバイス。
DSDEVID_DefaultVoicePlayback
デフォルトの音声再生デバイス。
pcDSCBufferDesc
キャプチャ バッファの特性を指定する DSCBUFFERDESC 構造体のアドレス。
pcDSBufferDesc
レンダリング バッファの特性を指定する DSBUFFERDESC 構造体のアドレス。
hWnd
アプリケーション ウインドウへのハンドル。
dwLevel
DirectSound オブジェクトの協調レベル。詳細については、「IDirectSound8::SetCooperativeLevel」を参照すること。
ppDSFD
IDirectSoundFullDuplex8 インターフェイス ポインタを受け取る変数のアドレス。
ppDSCBuffer8
キャプチャ バッファの IDirectSoundCaptureBuffer8 インターフェイスを受け取る変数のアドレス。
ppDSBuffer8
レンダリング バッファの IDirectSoundBuffer8 インターフェイスを受け取る変数のアドレス。
pUnkOuter
COM 集成体に対する制御オブジェクトの IUnknown インターフェイスのアドレス。集成体はサポートされていないため、NULL に設定しなければならない。

動作環境

ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。


GetDeviceID

ユーザーがコントロール パネルの [サウンド] および [マルチメディア] で選択したデフォルトの再生デバイスおよびキャプチャ デバイスの一意のデバイス識別子を受け取る。

HRESULT GetDeviceID(
  LPCGUID pGuidSrc,
  LPGUID pGuidDest
);

パラメータ

pGuidSrc
有効なデバイス識別子を指定する GUID 型の変数のアドレス、または次の定義済みの変数のいずれかのアドレス。
DSDEVID_DefaultPlayback
システムワイドなデフォルトのオーディオ再生デバイス。
DSDEVID_DefaultCapture
システムワイドなデフォルトのオーディオ キャプチャ デバイス。
DSDEVID_DefaultVoicePlayback
デフォルトの音声再生デバイス。
DSDEVID_DefaultVoiceCapture
デフォルトの音声キャプチャ デバイス。
pGuidDest
デバイスの一意の識別子を受け取る GUID の変数のアドレス。

戻り値

成功した場合は DS_OK を返す。

失敗した場合は DSERR_INVALIDPARAM を返す。

注意

pGuidSrc が有効なデバイス識別子を指している場合は、pGuidDest に同じ値が返される。pGuidSrc が一覧に示した定数のいずれかの場合、pGuidDest は対応するデバイスの GUID のアドレスを返す。

動作環境

ヘッダー : dsound.h で宣言。
インポート ライブラリ : dsound.lib を使用。


DirectSound 構造体

ここでは、DirectSound で使用される次の構造体のリファレンス情報を記述する。

  • DS3DBUFFER
  • DS3DLISTENER
  • DSBCAPS
  • DSBPOSITIONNOTIFY
  • DSBUFFERDESC
  • DSCAPS
  • DSCBCAPS
  • DSCBUFFERDESC
  • DSCCAPS
  • DSCEFFECTDESC
  • DSCFXAec
  • DSCFXNoiseSuppress
  • DSEFFECTDESC
  • DSFXI3DL2Reverb
  • DSFXChorus
  • DSFXCompressor
  • DSFXDistortion
  • DSFXEcho
  • DSFXFlanger
  • DSFXGargle
  • DSFXParamEq
  • DSFXWavesReverb
  • WAVEFORMATEX
  • WAVEFORMATEXTENSIBLE

注 すべての DirectX 構造体用のメモリは、使用前に初期化しなければならない。加えて、dwSize メンバを保持する構造体では、使用前にそのメンバを構造体のバイト単位のサイズに設定しなければならない。次の例は、よく使われる構造体 DSCAPS に対してこれらの処理を実行する。

DSCAPS dscaps; // まだこの構造体は利用できない。

ZeroMemory(&dscaps, sizeof(dscaps));
dscaps.dwSize = sizeof(dscaps);

// これでこの構造体が利用可能になった。


DS3DBUFFER

3D サウンド バッファの位置、向き、動作を一意に記述するために必要なすべての情報を保持している。この構造体は、IDirectSound3DBuffer8::GetAllParameters と IDirectSound3DBuffer8::SetAllParameters の各メソッドと共に使われる。

typedef struct {
    DWORD      dwSize;
    D3DVECTOR  vPosition;
    D3DVECTOR  vVelocity;
    DWORD      dwInsideConeAngle;
    DWORD      dwOutsideConeAngle;
    D3DVECTOR  vConeOrientation;
    LONG       lConeOutsideVolume;
    D3DVALUE   flMinDistance;
    D3DVALUE   flMaxDistance;
    DWORD      dwMode;
} DS3DBUFFER, *LPDS3DBUFFER;

typedef const DS3DBUFFER *LPCDS3DBUFFER;

メンバ

dwSize
構造体のサイズ (バイト単位)。この構造体を使う前に、このメンバを初期化しなければならない。
vPosition
3D サウンド バッファの現在の位置を記述する D3DVECTOR 構造体。
vVelocity
3D サウンド バッファの現在の速度を記述する D3DVECTOR 構造体。
dwInsideConeAngle
内側サウンド プロジェクション コーンの角度。
dwOutsideConeAngle
外側サウンド プロジェクション コーンの角度。
vConeOrientation
この 3D サウンド バッファ プロジェクション コーンの現在の向きを記述する D3DVECTOR 構造体。
lConeOutsideVolume
コーン外部ボリューム。
flMinDistance
最小距離。
flMaxDistance
最大距離。
dwMode
設定される 3D サウンド処理モード。
DS3DMODE_DISABLE
3D サウンド処理は無効になる。サウンドはリスナーの頭の中心で発生しているように聞こえる。
DS3DMODE_HEADRELATIVE
サウンド パラメータ (位置、速度、向き) はリスナーのパラメータに対する相対的なものである。このモードでは、リスナーのパラメータが変化したときにサウンドの絶対パラメータは自動的に更新されるので、相対パラメータは一定に保たれる。
DS3DMODE_NORMAL
標準の処理。これはデフォルトのモードである。

動作環境

ヘッダー : dsound.h で宣言。


DS3DLISTENER

3D ワールド パラメータとリスナーの位置を記述する。この構造体は、IDirectSound3DListener8::GetAllParameters と IDirectSound3DListener8::SetAllParameters の各メソッドと共に使われる。

typedef struct {
    DWORD      dwSize;
    D3DVECTOR  vPosition;
    D3DVECTOR  vVelocity;
    D3DVECTOR  vOrientFront;
    D3DVECTOR  vOrientTop;
    D3DVALUE   flDistanceFactor;
    D3DVALUE   flRolloffFactor;
    D3DVALUE   flDopplerFactor;
} DS3DLISTENER, *LPDS3DLISTENER;

typedef const DS3DLISTENER *LPCDS3DLISTENER;

メンバ

dwSize
構造体のサイズ (バイト単位)。この構造体を使う前に、このメンバを初期化しなければならない。
vPosition、vVelocity、vOrientFront、vOrientTop
リスナーの位置、速度、前方、上方のそれぞれを記述する D3DVECTOR 構造体。
flDistanceFactor、flRolloffFactor、flDopplerFactor
それぞれ現在の距離係数、ロールオフ係数、ドップラー係数。

動作環境

ヘッダー : dsound.h で宣言。


DSBCAPS

DirectSound バッファ オブジェクトの能力を記述する。IDirectSoundBuffer8::GetCaps メソッドで使われる。

typedef struct {
    DWORD  dwSize;
    DWORD  dwFlags;
    DWORD  dwBufferBytes;
    DWORD  dwUnlockTransferRate;
    DWORD  dwPlayCpuOverhead;
} DSBCAPS, *LPDSBCAPS;

typedef const DSBCAPS *LPCDSBCAPS;

メンバ

dwSize
構造体のサイズ (バイト単位)。この構造体を使う前に、このメンバを初期化しなければならない。
dwFlags
バッファ オブジェクトの能力を指定するフラグ。
DSBCAPS_CTRL3D
バッファは 3D コントロール能力を備えている。
DSBCAPS_CTRLFREQUENCY
バッファは周波数コントロール能力を備えている。
DSBCAPS_CTRLFX
バッファはエフェクト処理をサポートしている。
DSBCAPS_CTRLPAN
バッファはパン コントロール能力を備えている。
DSBCAPS_CTRLVOLUME
バッファはボリューム コントロール能力を備えている。
DSBCAPS_CTRLPOSITIONNOTIFY
バッファは位置通知能力を備えている。「DSBUFFERDESC」の「注意」を参照すること。
DSBCAPS_GETCURRENTPOSITION2
IDirectSoundBuffer8::GetCurrentPosition が再生カーソルの新しい動作を使うべきであることを示す。DirectX 1 の DirectSound では、エミュレートされたサウンド カード上で再生カーソルは実際に再生されているサウンドよりはるかに前方にあり、書き込みカーソルの直後に置かれていた。現在は、DSBCAPS_GETCURRENTPOSITION2 フラグを指定すると、アプリケーションはより正確な再生カーソルを取得できる。このフラグを指定していない場合、互換性を保つ目的で過去の動作が維持される。このフラグは、エミュレートされたサウンド カードにのみ影響を及ぼす点に注意すること。DirectSound ドライバが存在する場合、DirectX のどのバージョンでも、DirectSound の再生カーソルは正確な位置を示す。
DSBCAPS_GLOBALFOCUS
このバッファはグローバルなサウンド バッファである。このフラグを設定すると、ユーザーがほかのアプリケーションにフォーカスを移動し、その新しいアプリケーションが DirectSound を使う場合でも、DirectSound を使っているアプリケーションは引き続きそのバッファを再生できる。1 つの例外は、協調レベルで DSSCL_WRITEPRIMARY フラグを設定した DirectSound アプリケーションにフォーカスを移動した場合である。この場合、ほかのアプリケーションからのグローバルなサウンドは聞こえなくなる。
DSBCAPS_LOCDEFER
再生時、または IDirectSoundBuffer8::AcquireResources が呼び出されたときに、バッファはハードウェアまたはソフトウェアのリソースに割り当てられる。
DSBCAPS_LOCHARDWARE
バッファはハードウェア ミキシングを使う。
DSBCAPS_LOCSOFTWARE
バッファはソフトウェア メモリ内にあり、ソフトウェア ミキシングを使う。
DSBCAPS_MUTE3DATMAXDISTANCE
サウンドは、最大距離で無音になる。最大距離を超えるとバッファの再生が停止するので、プロセッサ時間を消費しないで済む。
DSBCAPS_PRIMARYBUFFER
このバッファはプライマリ サウンド バッファである。
DSBCAPS_STATIC
バッファはオンボード ハードウェア メモリにある。
DSBCAPS_STICKYFOCUS
バッファはスティッキー フォーカスを備えている。ユーザーが DirectSound を使っていないほかのアプリケーションに切り替えた場合、バッファは引き続き音を出す。ただし、ユーザーがほかの DirectSound アプリケーションに切り替えた場合、バッファは無音になる。
dwBufferBytes
このバッファのサイズ (バイト単位)。
dwUnlockTransferRate
IDirectSoundBuffer8::Unlock を呼び出したときにデータをバッファ メモリに転送する速度を指定する。単位は 1 秒あたりのキロバイト (KB/s)。高性能のアプリケーションはこの値を使って、IDirectSoundBuffer8::Unlock を実行するために必要な時間を決定できる。システム メモリ内に配置されているソフトウェア バッファの場合、処理が不要なので転送速度は非常に高い。ハードウェア バッファの場合、バッファをサウンド カードにロードしなければならない可能性があるので、転送速度はより遅くなる可能性がある。その結果、転送速度が制限されることがある。
dwPlayCpuOverhead
処理のオーバーヘッドを指定する。これは、サウンド バッファをミキシングするのに必要なメイン処理サイクルのパーセンテージである。ハードウェア バッファの場合、サウンド デバイスがミキシングを行うので、このメンバは 0 である。ソフトウェア バッファの場合、このメンバの値はバッファ フォーマットとシステム プロセッサの速度に依存する。

注意

DSBCAPS 構造体は、IDirectSound8::CreateSoundBuffer メソッドに渡される DSBUFFERDESC 構造体に似た情報と、それ以外のいくつかの追加情報を保持している。追加情報として、バッファの位置 (ハードウェアまたはソフトウェア) と、いくつかのコスト測定値 (たとえば、バッファがハードウェアに配置されている場合はダウンロード時間、ソフトウェアでバッファをミキシングする場合は再生処理のオーバーヘッドなど) が挙げられる。

dwFlags メンバは、DSBUFFERDESC 構造体で使用される同じフラグを保持する。唯一の違いは、DSBCAPS 構造体ではバッファの場所に応じて DSBCAPS_LOCHARDWARE と DSBCAPS_LOCSOFTWARE のどちらかが指定されることである。DSBUFFERDESC 構造体ではこれらのフラグはオプションであり、フラグの指定に応じて、バッファをハードウェアとソフトウェアのどちらかに強制的に配置できる。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSound8::CreateSoundBuffer、IDirectSoundBuffer8::GetCaps


DSBPOSITIONNOTIFY

通知位置を記述する。IDirectSoundNotify8::SetNotificationPositions メソッドで使われる。

typedef struct {
    DWORD   dwOffset;
    HANDLE  hEventNotify;
} DSBPOSITIONNOTIFY, *LPDSBPOSITIONNOTIFY;

typedef const DSBPOSITIONNOTIFY *LPCDSBPOSITIONNOTIFY;

メンバ

dwOffset
バッファの先頭から、通知イベントがトリガされる場所までのオフセット、または DSBPN_OFFSETSTOP。
hEventNotify
指定のオフセットに達したときにシグナル送信されるイベントへのハンドル。

注意

dwOffset メンバ内で値 DSBPN_OFFSETSTOP が設定されている場合、再生またはキャプチャがバッファの最後に達した (そして再生またはキャプチャがループしていない) か、アプリケーションが IDirectSoundBuffer8::Stop または IdirectSoundCaptureBuffer8::Stop のどちらかのメソッドを呼び出したことが原因で、再生またはキャプチャが停止すると、イベントがシグナル送信される。

DSBCAPS_LOCDEFER および DSBCAPS_NOTIFY をボイス管理フラグと共に使うと、通知が設定されているが、まだ通知に達していないサウンドは、ボイス管理によって終了される場合がある。この場合、通知イベントは発生しない。

動作環境

ヘッダー : dsound.h で宣言。


DSBUFFERDESC

新しい DirectSoundBuffer オブジェクトの特性を記述する。IDirectSound8::CreateSoundBuffer メソッドで使われる。

DirectX 7 以前との互換性を保つために、この構造体の前のバージョンの DSBUFFERDESC1 も dsound.h で維持されている。

typedef struct {
    DWORD           dwSize;
    DWORD           dwFlags;
    DWORD           dwBufferBytes;
    DWORD           dwReserved;
    LPWAVEFORMATEX  lpwfxFormat;
    GUID            guid3DAlgorithm;
} DSBUFFERDESC, *LPDSBUFFERDESC;

typedef const DSBUFFERDESC *LPCDSBUFFERDESC;

メンバ

dwSize
構造体のサイズ (バイト単位)。この構造体を使う前に、このメンバを初期化しなければならない。
dwFlags
新しい DirectSoundBuffer オブジェクトを作成するときに含める能力を識別するフラグ。次のフラグが定義されている。「注意」を参照すること。
DSBCAPS_CTRL3D
バッファは 3D コントロール能力を備えている。DSBCAPS_CTRLPAN と組み合わせることはできない。また、lpwfxFormat でステレオ フォーマットを指定されているバッファには設定できない。
DSBCAPS_CTRLFREQUENCY
バッファは周波数コントロール能力を備えている。DSBCAPS_CTRLFX と組み合わせることはできない。
DSBCAPS_CTRLFX
バッファはエフェクト処理をサポートしている。DSBCAPS_CTRLFREQUENCY と組み合わせることはできない。lpwfxFormat のウェーブ フォーマットは、2 チャンネル以下の 8 ビットまたは 16 ビットの PCM フォーマットでなければならない。また、バッファには、DSBSIZE_FX_MIN ミリ秒のデータを格納できるサイズが必要である。
DSBCAPS_CTRLPAN
バッファはパン コントロール能力を備えている。DSBCAPS_CTRL3D と組み合わせることはできない。
DSBCAPS_CTRLPOSITIONNOTIFY
バッファは位置通知能力を備えている。「注意」を参照すること。
DSBCAPS_CTRLVOLUME
バッファはボリューム コントロール能力を備えている。
DSBCAPS_GETCURRENTPOSITION2
IDirectSoundBuffer8::GetCurrentPosition メソッドでは、再生カーソルの新しい動作を使用する。DirectX 1 の DirectSound では、エミュレートされたサウンド カード上で再生カーソルは実際に再生されているサウンドよりはるかに前方にあり、書き込みカーソルの直後に置かれていた。現在は、DSBCAPS_GETCURRENTPOSITION2 フラグを指定すると、アプリケーションはより正確な再生カーソルを取得できる。このフラグを指定していない場合、互換性を保つ目的で過去の動作が維持される。このフラグは、エミュレートされたサウンド カードにのみ影響を及ぼすことに注意する。DirectSound ドライバが存在する場合、どのバージョンの DirectX でも DirectSound の再生カーソルは正確な位置を示す。
DSBCAPS_GLOBALFOCUS
このバッファはグローバルなサウンド バッファである。このフラグを設定すると、ユーザーがほかのアプリケーションにフォーカスを移動し、その新しいアプリケーションが DirectSound を使う場合でも、DirectSound を使っているアプリケーションは引き続きそのバッファを再生できる。1 つの例外は、協調レベルで DSSCL_WRITEPRIMARY フラグを設定した DirectSound アプリケーションにフォーカスを移動した場合である。この場合、ほかのアプリケーションからのグローバルなサウンドは聞こえなくなる。
DSBCAPS_LOCDEFER
再生時、バッファはハードウェアまたはソフトウェアのリソースに割り当てられる。このフラグは、ボイス管理を使うバッファに設定されなければならない。
DSBCAPS_LOCHARDWARE
バッファはハードウェア ミキシングを使わなければならない。デバイスがハードウェア ミキシングをサポートしていない場合や、必要なハードウェア メモリを利用できない場合、IDirectSound8::CreateSoundBuffer メソッドの呼び出しは失敗する。アプリケーションは、このバッファがミキシング チャンネルを利用可能であると保証する必要がある。この状況は保証されていない。
DSBCAPS_LOCSOFTWARE
DSBCAPS_STATIC が指定されていて、ハードウェア リソースが利用可能であっても、バッファをソフトウェア メモリに配置して、ソフトウェア ミキシングを使わなければならない。
DSBCAPS_MUTE3DATMAXDISTANCE
サウンドは、最大距離で無音になる。最大距離を超えるとバッファの再生が停止するので、プロセッサ時間を消費しないで済む。
DSBCAPS_PRIMARYBUFFER
このバッファはプライマリ サウンド バッファである。この値を指定しない場合は、セカンダリ サウンド バッファが作成される。DSBCAPS_CTRLFX と組み合わせることはできない。
DSBCAPS_STATIC
オンボード ハードウェア メモリが利用可能な場合、バッファはそこに置かれる。このようなメモリが利用できない場合でも、エラーは発生しない。これに対して DSBCAPS_LOCHARDWARE は、バッファを強制的にハードウェア メモリ (おそらく、ドライバがバッファのミキシングに使うシステム メモリ) に置くので、このようなメモリが利用できない場合はエラーを引き起こす。このフラグは、DSBCAPS_CTRLFX と組み合わせることはできない。
DSBCAPS_STICKYFOCUS
バッファはスティッキー フォーカスを備えている。ユーザーが DirectSound を使っていないほかのアプリケーションに切り替えた場合、アプリケーションの標準バッファは無音になるが、スティッキー フォーカス バッファは引き続き音を出す。
dwBufferBytes
新しいバッファのサイズ (バイト単位)。DSBCAPS_PRIMARYBUFFER フラグを使ってバッファを作成する場合、この値は 0 でなければならない。セカンダリ バッファで許容される最小サイズと最大サイズは、dsound.h 内で定義される DSBSIZE_MIN、DSBSIZE_MAX である。
dwReserved
このメンバは予約されている。0 でなければならない。
lpwfxFormat
バッファのウェーブ フォーマットを指定する WAVEFORMATEX または WAVEFORMATEXTENSIBLE 構造体のアドレス。プライマリ バッファでは、この値は NULL でなければならない。アプリケーションは IDirectSoundBuffer8::SetFormat を使って、プライマリ バッファのフォーマットを設定できる。
guid3DAlgorithm
DirectSound3D HEL が使う二重スピーカの仮想アルゴリズムのユニーク識別子。DSBCAPS_CTRL3D が dwFlags に設定されていない場合、このメンバは GUID_NULL (DS3DALG_DEFAULT) にすべきである。「注意」を参照すること。

次のアルゴリズム識別子が定義されている。

DS3DALG_DEFAULT
DirectSound はデフォルトのアルゴリズムを使用する。通常は、DS3DALG_NO_VIRTUALIZATION である。WDM ドライバでは、コントロール パネルでサラウンド サウンドが選択されていると、サウンドは、左、中央、右、およびサラウンドの各チャンネル間でパンされる。

ソフトウェア ミキシングにのみ適用される。WDM または VxD ドライバで利用できる。

DS3DALG_NO_VIRTUALIZATION
3D 出力は、標準の左右ステレオのパンにマップされる。左に 90° のとき、サウンドは左スピーカだけから聞こえ、右に 90° のとき、サウンドは右スピーカだけから聞こえる。垂直軸では、距離によってボリュームが調節されるだけである。このバッファでは、ドップラー シフトとボリューム調節は適用されるが、3D フィルタリングは行われない。これは最も効率的なソフトウェアの実装であるが、仮想 3D オーディオ エフェクトは提供しない。DS3DALG_NO_VIRTUALIZATION フラグを指定すると、HRTF 処理は行われない。注 DS3DALG_NO_VIRTUALIZATION は標準のステレオのパンのみを使うので、このアルゴリズムで作成されたバッファは、3D ハードウェア ボイスの空きを利用できない場合、2D ハードウェア ボイスによってアクセラレートされる。

ソフトウェア ミキシングにのみ適用される。WDM または VxD ドライバで利用できる。

DS3DALG_HRTF_FULL
3D API は、高品質な 3D オーディオ アルゴリズムで処理される。このフラグは、ソフトウェア HEL のみに適用される。このアルゴリズムは最高品質の 3D オーディオ エフェクトを与えるが、CPU をより多く消費する。「注意」を参照すること。

ソフトウェア ミキシングにのみ適用される。WDM ドライバを使った、Microsoft® Windows® 98 Second Edition と Windows 2000 で利用できる。

注 サウンド バッファを HRTF アルゴリズムのいずれかを使って作成し、HRTF アルゴリズムがシステムで利用不可能な場合は (たとえば、WDM システムではない場合)、コード DS_NO_VIRTUALIZATION が返される。作成されたサウンド バッファは、代わりに DS3DALG_NO_VIRTUALIZATION を使う。これにより、アプリケーションは CreateSoundBuffer の呼び出し時に明示的に DS_OK をチェックするのではなく、SUCCEEDED マクロや FAILED マクロを使う必要がある。

DS3DALG_HRTF_LIGHT
3D API は、効率的な 3D オーディオ アルゴリズムで処理される。このフラグは、ソフトウェア HEL のみに適用される。このアルゴリズムは優れた 3D オーディオ エフェクトを与え、DS3DALG_HRTF_FULL ほど CPU に負荷をかけない。

ソフトウェア ミキシングにのみ適用される。WDM ドライバを使った、Windows 98 Second Edition と Windows 2000 で利用できる。

注 サウンド バッファを HRTF アルゴリズムのいずれかを使って作成し、HRTF アルゴリズムがシステムで利用不可能な場合は (たとえば、WDM システムではない場合)、コード DS_NO_VIRTUALIZATION が返される。作成されたサウンド バッファは、代わりに DS3DALG_NO_VIRTUALIZATION を使う。これにより、アプリケーションは CreateSoundBuffer の呼び出し時に明示的に DS_OK をチェックするのではなく、SUCCEEDED マクロや FAILED マクロを使う必要がある。

注意

プライマリ バッファを作成する際、アプリケーションは dwBufferBytes メンバを 0 に設定しなければならない。DirectSound は、使用中の特定のサウンド デバイスに対する最適なバッファ サイズを決定する。作成されたプライマリ バッファの大きさを取得するには、IDirectSoundBuffer8::GetCaps を呼び出す。

DSBCAPS_CTRLDEFAULT フラグはもうサポートされていない。このフラグは、DSBCAPS_CTRLPAN | DSBCAPS_CTRLVOLUME | DSBCAPS_CTRLFREQUENCY として定義された。必要なフラグだけを指定することにより、不必要なリソースを減らすことができる。

DSBCAPS_CTRLPOSITIONNOTIFY フラグで作成されたサウンド バッファには、通知イベントを設定すべきである。このフラグでサウンド バッファを作成し、実際には何も通知を設定しないと、動作が定義されず、サウンドが 2 回再生されることがある。

VxD ドライバの場合、DSBCAPS_CTRLPOSITIONNOTIFY を使って作成されたサウンド バッファは常にソフトウェア バッファである。これは、VxD ドライバ モデルが通知をサポートしないためである。ハードウェアが利用可能な場合は、WDM ドライバにより、通知可能なバッファがハードウェアに存在することがある。このフラグ設定で作成されたバッファの再生中は、DSBPLAY_LOCHARDWARE フラグによる IDirectSoundBuffer8::Play の呼び出しは失敗する。

DSBCAPS_LOCHARDWARE と DSBCAPS_LOCSOFTWARE の各フラグはオプションであり、互いに排他的である。DSBCAPS_LOCHARDWARE は、強制的にバッファをハードウェアに配置する。これは、バッファがサウンド カードによってミキシングされることを意味する。DSBCAPS_LOCSOFTWARE は、強制的にバッファをソフトウェアに配置する。この場合、バッファは CPU によってミキシングされる。これらのフラグは、DSBCAPS 構造体の dwFlags メンバ用にも定義されており、バッファの実際の場所を示す。

3D アルゴリズムは、ソフトウェア エミュレーション レイヤのみの選択を行う。これは、アクセラレーション用のハードウェアがない場合に使われるソフトウェア アルゴリズムである。ハードウェアの利用を最大にするために、DS3DALG_NO_VIRTUALIZATION は特別な場合として扱われる。3D ハードウェア ボイスの空きを利用できない場合、バッファは 3D API コントロールと共に 2D バッファとして扱われる。特に、サウンド バッファが DS3DALG_NO_VIRTUALIZATION で作成されている場合、またはバッファが DSBPLAY_LOCDEFER で作成されている場合は、バッファの演奏中に次の手順に従う。

  • 3D ハードウェア ボイスの空きが利用可能な場合は、その 3D ハードウェア ボイスを使う。
  • 3D ハードウェア ボイスの空きが利用不可能で、2D ハードウェア ボイスが利用可能な場合は、その 2D ハードウェア ボイスを使う。これが可能なのは、DS3DALG_NO_VIRTUALIZATION アルゴリズムが単純なステレオ パン アルゴリズムだからである。
  • 2D または 3D ハードウェア ボイスの空きが利用不可能な場合、ボイスは DS3DALG_NO_VIRTUALIZATION アルゴリズムを使ってソフトウェアで再生される。

DSSPEAKER_HEADPHONE や DSSPEAKER_STEREO 以外のスピーカ構成が有効な場合、この処理は二重スピーカ構成に対する処理と同じように行われる。

バッファを HRTF アルゴリズムのいずれかを使って作成し、HRTF アルゴリズムがシステムで利用不可能な場合は (たとえば、WDM システムではない場合)、コード DS_NO_VIRTUALIZATION が返される。作成されたサウンド バッファは、代わりに DS3DALG_NO_VIRTUALIZATION を使う。これにより、アプリケーションは CreateSoundBuffer の呼び出し時に明示的に DS_OK をチェックするのではなく、SUCCEEDED マクロや FAILED マクロを使う必要がある。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSound8::CreateSoundBuffer、DirectSound バッファ、ISA および PCI カードでのハードウェア アクセラレーション


DSCAPS

DirectSound デバイスの能力を記述する。IDirectSound8::GetCaps メソッドで使われる。

typedef {
    DWORD  dwSize;
    DWORD  dwFlags;
    DWORD  dwMinSecondarySampleRate;
    DWORD  dwMaxSecondarySampleRate;
    DWORD  dwPrimaryBuffers;
    DWORD  dwMaxHwMixingAllBuffers;
    DWORD  dwMaxHwMixingStaticBuffers;
    DWORD  dwMaxHwMixingStreamingBuffers;
    DWORD  dwFreeHwMixingAllBuffers;
    DWORD  dwFreeHwMixingStaticBuffers;
    DWORD  dwFreeHwMixingStreamingBuffers;
    DWORD  dwMaxHw3DAllBuffers;
    DWORD  dwMaxHw3DStaticBuffers;
    DWORD  dwMaxHw3DStreamingBuffers;
    DWORD  dwFreeHw3DAllBuffers;
    DWORD  dwFreeHw3DStaticBuffers;
    DWORD  dwFreeHw3DStreamingBuffers;
    DWORD  dwTotalHwMemBytes;
    DWORD  dwFreeHwMemBytes;
    DWORD  dwMaxContigFreeHwMemBytes;
    DWORD  dwUnlockTransferRateHwBuffers;
    DWORD  dwPlayCpuOverheadSwBuffers;
    DWORD  dwReserved1;
    DWORD  dwReserved2;
} DSCAPS, *LPDSCAPS;

typedef const DSCAPS *LPCDSCAPS;

メンバ

dwSize
構造体のサイズ (バイト単位)。この構造体を使う前に、このメンバを初期化しなければならない。
dwFlags
デバイスの能力を記述するフラグ。次のいずれかの値となる。
DSCAPS_CERTIFIED
このドライバは Microsoft でテストされ、認定されている。このフラグは常に WDM ドライバに対して設定される。認証されているかどうかテストするには、IDirectSound8::VerifyCertification を使用する。
DSCAPS_CONTINUOUSRATE
このデバイスは、dwMinSecondarySampleRate と dwMaxSecondarySampleRate の各メンバ値の間のすべてのサンプリング レートをサポートする。一般にこれは、実際の出力レートが要求された周波数の ±10 ヘルツ (Hz) 以内であることを意味する。
DSCAPS_EMULDRIVER
このデバイスには DirectSound ドライバがインストールされていない。ウェーブフォーム オーディオ機能を通してエミュレートされている。性能の低下が予想される。
DSCAPS_PRIMARY16BIT
このデバイスは 16 ビット サンプリングでプライマリ サウンド バッファをサポートする。
DSCAPS_PRIMARY8BIT
このデバイスは 8 ビット サンプリングでプライマリ バッファをサポートする。
DSCAPS_PRIMARYMONO
このデバイスはモノラルのプライマリ バッファをサポートする。
DSCAPS_PRIMARYSTEREO
このデバイスはステレオのプライマリ バッファをサポートする。
DSCAPS_SECONDARY16BIT
このデバイスは、16 ビット サンプリングでハードウェア ミキシングのセカンダリ サウンド バッファをサポートする。
DSCAPS_SECONDARY8BIT
このデバイスは、8 ビット サンプリングでハードウェア ミキシングのセカンダリ バッファをサポートする。
DSCAPS_SECONDARYMONO
このデバイスは、ハードウェア ミキシングのモノラル セカンダリ バッファをサポートする。
DSCAPS_SECONDARYSTEREO
このデバイスは、ハードウェア ミキシングのステレオ セカンダリ バッファをサポートする。
dwMinSecondarySampleRate、dwMaxSecondarySampleRate
このデバイスのハードウェア セカンダリ サウンド バッファがサポートする最小と最大のサンプリング レートの仕様。
dwPrimaryBuffers
サポートされているプライマリ バッファの数。この値は常に 1 である。
dwMaxHwMixingAllBuffers
ハードウェアでミキシングできるバッファの数。このメンバは dwMaxHwMixingStaticBuffers と dwMaxHwMixingStreamingBuffers の合計より小さい値を取る。リソースのトレードオフがしばしば発生する。
dwMaxHwMixingStaticBuffers
スタティック バッファの最大数。
dwMaxHwMixingStreamingBuffers
ストリーム サウンド バッファの最大数。
dwFreeHwMixingAllBuffers
未割り当てバッファの数。WDM ドライバでは、dwFreeHw3DAllBuffers となる。
dwFreeHwMixingStaticBuffers
未割り当てのスタティック バッファの数。
dwFreeHwMixingStreamingBuffers
未割り当てのストリーム バッファの数。
dwMaxHw3DAllBuffers
3D バッファの最大数。
dwMaxHw3DStaticBuffers
スタティック 3D バッファの最大数。
dwMaxHw3DStreamingBuffers
ストリーム 3D バッファの最大数。
dwFreeHw3DAllBuffers
未割り当ての 3D バッファの数。
dwFreeHw3DStaticBuffers
未割り当てのスタティック 3D バッファの数。
dwFreeHw3DStreamingBuffers
未割り当てのストリーム 3D バッファの数。
dwTotalHwMemBytes
スタティック サウンド バッファを保持するサウンド カード上のメモリ容量のサイズ (バイト単位)。
dwFreeHwMemBytes
サウンド カード上の空きメモリのサイズ (バイト単位)。
dwMaxContigFreeHwMemBytes
サウンド カード上の空きメモリのうち、最大の連続ブロックのサイズ (バイト単位)。
dwUnlockTransferRateHwBuffers
ハードウェア スタティック サウンド バッファへのデータ転送速度。単位は 1 秒あたりのキロバイト (KB/s)。この速度と転送バイト数により、IDirectSoundBuffer8::Unlock メソッドを呼び出したときの実行時間が決まる。
dwPlayCpuOverheadSwBuffers
(メイン システム メモリ内の) ソフトウェア バッファをミキシングするために必要な処理オーバーヘッドを、CPU パーセンテージで記述した値。この値は、バス タイプ、プロセッサ タイプ、クロック速度に応じて変化する。

ソフトウェア バッファのアンロック転送速度は 0 である。データをどこにも転送する必要がないからである。同様に、ハードウェア バッファの再生オーバーヘッドも、ミキシングがサウンド デバイスによって処理されるため、0 である。

dwReserved1
未使用。
dwReserved2
未使用。

注意

いくつかのオーディオ サウンド カードは、利用可能なハードウェア バッファやその空きを正確に報告できない場合がある。これはたとえば、カードが、高いサンプリング レートよりも低いサンプリング レートでより多くのサウンドを再生できるときに発生する。通常、ハードウェア バッファの空き数に関係するメンバの値が 0 以外のとき、適切なタイプのハードウェア リソースが少なくとも 1 つ利用できることを示す。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSound8::GetCaps


DSCBCAPS

キャプチャ バッファの能力を記述する。IDirectSoundCaptureBuffer8::GetCaps メソッドで使われる。

typedef struct {
    DWORD  dwSize;
    DWORD  dwFlags;
    DWORD  dwBufferBytes;
    DWORD  dwReserved;
} DSCBCAPS, *LPDSCBCAPS;

typedef const DSCBCAPS *LPCDSCBCAPS;

メンバ

dwSize
構造体のサイズ (バイト単位)。この構造体を使う前に、このメンバを初期化しなければならない。
dwFlags
デバイスの能力を指定する。0 または次のフラグを指定する。
DSCBCAPS_WAVEMAPPED
このデバイスがサポートしないフォーマットに対して、Win32 ウェーブ マッパーを使う。
dwBufferBytes
キャプチャ バッファのサイズ (バイト単位)。
dwReserved
将来の使用に備えて予約されている。

動作環境

ヘッダー : dsound.h で宣言。


DSCBUFFERDESC

キャプチャ バッファを記述する。IDirectSoundCapture8::CreateCaptureBuffer メソッドで使われる。

DirectX 7 以前との互換性を保つために、この構造体の前のバージョンの DSCBUFFERDESC1 も dsound.h で維持されている。

typedef struct {
    DWORD           dwSize;
    DWORD           dwFlags;
    DWORD           dwBufferBytes;
    DWORD           dwReserved;
    LPWAVEFORMATEX  lpwfxFormat;
    DWORD           dwFXCount;
    LPDSCEFFECTDESC lpDSCFXDesc;
} DSCBUFFERDESC, *LPDSCBUFFERDESC;

typedef const DSCBUFFERDESC *LPCDSCBUFFERDESC;

メンバ

dwSize
構造体のサイズ (バイト単位)。この構造体を使う前に、このメンバを初期化しなければならない。
dwFlags
デバイスの能力を指定する。0 か、次のフラグの 1 つまたは複数を指定できる。
DSCBCAPS_CTRLFX
バッファはエフェクトをサポートする。「注意」を参照すること。
DSCBCAPS_WAVEMAPPED
このデバイスがサポートしないフォーマットに対して、Win32 ウェーブ マッパーを使う。
dwBufferBytes
作成されるキャプチャ バッファのサイズ (バイト単位)。
dwReserved
将来の使用に備えて予約されている。
lpwfxFormat
データのキャプチャに使うフォーマットを保持する WAVEFORMATEX 構造体へのポインタ。
dwFXCount
lpDSCFXDesc で示される配列の要素数。dwFlags が DSCBCAPS_CTRLFX でない場合は、0 でなければならない。
lpDSCFXDesc
DSCEFFECTDESC 構造体の配列のアドレス。バッファに対してハードウェアでサポートされているエフェクトを記述する。ユーザー モードの DMO はサポートされない。

注意

DSCBCAPS_CTRLFX フラグは、CLSID_DirectSoundCapture8 クラスのオブジェクトで作成されたバッファでのみサポートされる。IDirectSoundCapture8 インターフェイスが DirectSoundCaptureCreate8 から取得された場合、このフラグはサポートされる。以前の DirectSoundCaptureCreate 関数から取得された場合、このフラグはサポートされない。

現在のオペレーティング システムでは、キャプチャ エフェクトはサポートされない。

動作環境

ヘッダー : dsound.h で宣言。


DSCCAPS

キャプチャ デバイスの能力を記述する。IDirectSoundCapture8::GetCaps メソッドで使われる。

typedef struct {
    DWORD  dwSize;
    DWORD  dwFlags;
    DWORD  dwFormats;
    DWORD  dwChannels;
} DSCCAPS, *LPDSCCAPS;

typedef const DSCCAPS *LPCDSCCAPS;

メンバ

dwSize
構造体のサイズ (バイト単位)。この構造体を使う前に、このメンバを初期化しなければならない。
dwFlags
デバイスの能力を指定する。0 または次のフラグを指定する。
DSCCAPS_EMULDRIVER
このデバイス用の DirectSoundCapture ドライバは存在しない。そのため、標準のウェーブ オーディオ関数が使われている。
DSCCAPS_CERTIFIED
このデバイス用のドライバは、認証済みの WDM ドライバである。
DSCCAPS_MULTIPLECAPTURE
キャプチャ デバイスは、有効なキャプチャ データを同時に受け取ることができる複数のアプリケーションで開くことができる。
dwFormats
サポートされている標準フォーマット。これらは Win32 ウェーブフォーム オーディオ関数で使われている WAVEINCAPS 構造体の値と同じものである。次に一覧を示す。
値 | 意味
WAVE_FORMAT_1M08 | 11.025kHz、モノラル、8 ビット
WAVE_FORMAT_1M16 | 11.025kHz、モノラル、16 ビット
WAVE_FORMAT_1S08 | 11.025kHz、ステレオ、8 ビット
WAVE_FORMAT_1S16 | 11.025kHz、ステレオ、16 ビット
WAVE_FORMAT_2M08 | 22.05kHz、モノラル、8 ビット
WAVE_FORMAT_2M16 | 22.05kHz、モノラル、16 ビット
WAVE_FORMAT_2S08 | 22.05kHz、ステレオ、8 ビット
WAVE_FORMAT_2S16 | 22.05kHz、ステレオ、16 ビット
WAVE_FORMAT_4M08 | 44.1kHz、モノラル、8 ビット
WAVE_FORMAT_4M16 | 44.1kHz、モノラル、16 ビット
WAVE_FORMAT_4S08 | 44.1kHz、ステレオ、8 ビット
WAVE_FORMAT_4S16 | 44.1kHz、ステレオ、16 ビット

dwChannels
デバイスがサポートするチャンネル数を指定する数値。1 はモノラル、2 はステレオを意味する。以下同様である。

動作環境

ヘッダー : dsound.h で宣言。


DSCEFFECTDESC

キャプチャ バッファに関連付けられたエフェクトのパラメータを保持する。

typedef struct _DSCEFFECTDESC {
    DWORD       dwSize;
    DWORD       dwFlags;
    GUID        guidDSCFXClass;
    GUID        guidDSCFXInstance;
    DWORD       dwReserved1;
    DWORD       dwReserved2;
} DSCEFFECTDESC, *LPDSCEFFECTDESC;

typedef const DSCEFFECTDESC *LPCDSCEFFECTDESC;

メンバ

dwSize
構造体のサイズ (バイト単位)。
dwFlags
エフェクトの目的のパラメータを指定するフラグ。この構造体を IDirectSoundCapture8::CreateCaptureBuffer に渡す場合、このメンバには 0 または次の 1 つ以上の値を指定できる。
DSCFX_LOCHARDWARE
guidDSCFXInstance で指定したエフェクトが、ハードウェアになければならない。
DSCFX_LOCSOFTWARE
guidDSCFXInstance で指定したエフェクトが、ソフトウェアになければならない。
戻り値として、このメンバには次の 1 つまたは複数の値が保持される場合がある。
DSCFXR_LOCHARDWARE
エフェクトはハードウェアで作成された。
DSCFXR_LOCSOFTWARE
エフェクトはソフトウェアで作成された。
DSCFXR_UNALLOCATED
エフェクトは作成されていない。
DSCFXR_FAILED
エフェクトの作成に失敗した。
DSCFXR_UNKNOWN
エフェクトの作成結果が不明である。
guidDSCFXClass
エフェクトのクラス識別子を指定する GUID 型の値。次の一般的な識別子が定義されている。
DSCFX_CLASS_AEC
聴感エコー解除。
DSCFX_CLASS_NS
ノイズ抑制。
guidDSCFXInstance
優先するエフェクトの一意な識別子を指定する GUID 型の値。次の一般的な識別子が定義されている。
DSCFX_MS_AEC
Microsoft の聴感エコー解除。ソフトウェアのみで利用可能。
DSCFX_MS _NS
Microsoft のノイズ抑制。ソフトウェアのみで利用可能。
DSCFX_SYSTEM_AEC
システムでデフォルトの聴感エコー解除。
DSCFX_SYSTEM_NS
システムでデフォルトのノイズ抑制。
DSCFX_NOP
エフェクトなし。

dwReserved1
このメンバは予約されている。0 でなければならない。
dwReserved2
このメンバは予約されている。0 でなければならない。

動作環境

ヘッダー : dsound.h で宣言。


DSCFXAec

キャプチャ バッファの聴感エコー解除のパラメータを保持する。

typedef struct _DSCFXAec {
    BOOL  fEnable;
    BOOL  fReset;
} DSCFXAec, *LPDSCFXAec;

typedef const DSCFXAec *LPCDSCFXAec;

メンバ

fEnable
エフェクトが有効かどうかを指定するブール型の値。
fReset
エフェクトをデフォルトの状態にリセットするかどうかを指定するブール型の値。

注意

アプリケーションでエフェクトをリセットするのは、エフェクトが不正な状態に陥った場合だけにすべきである。ユーザーの入力に応答して、必要なときだけリセットされるようにすることができる。同じエフェクトをほかのアプリケーションでも使用している可能性があるので、起動時に任意で fReset フラグが設定されるようにしてはいけない。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSoundCaptureFXAec8::GetAllParameters、IDirectSoundCaptureFXAec8::SetAllParameters


DSCFXNoiseSuppress

キャプチャ バッファのノイズ抑制のパラメータを保持する。

typedef struct _DSCFXNoiseSuppress {
    BOOL  fEnable;
    BOOL  fReset;
} DSCFXNoiseSuppress, *LPDSCFXNoiseSuppress;

typedef const DSCFXNoiseSuppress *LPCDSCFXNoiseSuppress;

メンバ

fEnable
エフェクトが有効かどうかを指定するブール型の値。
fReset
エフェクトをデフォルトの状態にリセットするかどうかを指定するブール型の値。

注意

アプリケーションでエフェクトをリセットするのは、エフェクトが不正な状態に陥った場合だけにすべきである。ユーザーの入力に応答して、必要なときだけリセットされるようにすることができる。同じエフェクトをほかのアプリケーションでも使用している可能性があるので、起動時に任意で fReset フラグが設定されるようにしてはいけない。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSoundCaptureFXNoiseSuppress8::GetAllParameters、IDirectSoundCaptureFXNoiseSuppress8::SetAllParameters


DSEFFECTDESC

バッファに関連付けられたエフェクトを記述する。

typedef struct _DSEFFECTDESC {
    DWORD  dwSize;
    DWORD  dwFlags;
    GUID   guidDSFXClass;
    DWORD  dwReserved1;
    DWORD  dwReserved2
} DSEFFECTDESC, *LPDSEFFECTDESC;

typedef const DSEFFECTDESC *LPCDSEFFECTDESC;

メンバ

dwSize
構造体のサイズ (バイト単位)。
dwFlags
フラグ。0 または次の値のいずれかを指定する。
DSFX_LOCHARDWARE
エフェクトはハードウェアになければならない。ハードウェアでそのエフェクトを利用できない場合は、IDirectSoundBuffer8::SetFX でエラーが発生する。DirectX 8.0 はエフェクトのハードウェア アクセラレーションをサポートしていないので、このフラグを使うべきではない。
DSFX_LOCSOFTWARE
ハードウェアが guidDSFXClass のアクセラレーションをサポートする場合でも、エフェクトはソフトウェアになければならない。ソフトウェアでそのエフェクトを利用できない場合は、SetFX でエラーが発生する。DirectX 8.0 では、このフラグの設定にかかわらず、すべてのエフェクトがソフトウェアに配置される。
guidDSFXClass
エフェクトのクラス識別子。次の標準エフェクト クラスが定義されている。
GUID_DSFX_STANDARD_CHORUS
GUID_DSFX_STANDARD_COMPRESSOR
GUID_DSFX_STANDARD_DISTORTION
GUID_DSFX_STANDARD_ECHO
GUID_DSFX_STANDARD_FLANGER
GUID_DSFX_STANDARD_GARGLE
GUID_DSFX_STANDARD_I3DL2REVERB
GUID_DSFX_STANDARD_PARAMEQ
GUID_DSFX_STANDARD_WAVES_REVERB
dwReserved1
将来の使用に備えて予約されている。
dwReserved2
将来の使用に備えて予約されている。

注意

dwFlags が 0 の場合、エフェクトは可能であればハードウェアに置かれる。ハードウェアがエフェクトをサポートしていない場合は、ソフトウェアが使用される。エフェクトをまったく利用できない場合、SetFX の呼び出しは失敗する。

GUID_DSFX_STANDARD_WAVES_REVERB クラスのエフェクトは、16 ビットのオーディオ フォーマットを備えるバッファ上にのみ設定できる。

動作環境

ヘッダー : dsound.h で宣言。

参照

DSBCAPS、IDirectSoundBuffer8::SetFX、エフェクトの使い方


DSFXI3DL2Reverb

I3DL2 (Interactive 3D Audio Level 2) リバーブ エフェクトのパラメータを保持する。

typedef struct _DSFXI3DL2Reverb {
    LONG    lRoom;
    LONG    lRoomHF;
    FLOAT   flRoomRolloffFactor;
    FLOAT   flDecayTime;
    FLOAT   flDecayHFRatio;
    LONG    lReflections;
    FLOAT   flReflectionsDelay;
    LONG    lReverb;
    FLOAT   flReverbDelay;
    FLOAT   flDiffusion;
    FLOAT   flDensity;
    FLOAT   flHFReference;
} DSFXI3DL2Reverb, *LPDSFXI3DL2Reverb;

typedef const DSFXI3DL2Reverb *LPCDSFXI3DL2Reverb;

メンバ

lRoom
空間エフェクトの減衰。単位はミリベル (mB)。値の範囲は DSFX_I3DL2REVERB_ROOM_MIN からDSFX_I3DL2REVERB_ROOM_MAX で、デフォルト値は DSFX_I3DL2REVERB_ROOM_DEFAULT または -1000 mB である。
lRoomHF
高周波数空間エフェクトの減衰。単位は mB。値の範囲は DSFX_I3DL2REVERB_ROOMHF_MIN から DSFX_I3DL2REVERB_ROOMHF_MAX で、デフォルト値は DSFX_I3DL2REVERB_ROOMHF_DEFAULT または 0 mB である。
flRoomRolloffFactor
反射した信号のロールオフ係数。値の範囲は DSFX_I3DL2REVERB_ROOMROLLOFFFACTOR_MIN から DSFX_I3DL2REVERB_ROOMROLLOFFFACTOR_MAX で、デフォルト値は DSFX_I3DL2REVERB_ROOMROLLOFFFACTOR_DEFAULT または 0.0 である。ダイレクト パスのロールオフ係数は、DirectSound リスナーによって制御される。
flDecayTime
ディケイ時間。単位は秒。値の範囲は DSFX_I3DL2REVERB_DECAYTIME_MIN から DSFX_I3DL2REVERB_DECAYTIME_MAX で、デフォルト値は DSFX_I3DL2REVERB_DECAYTIME_DEFAULT または 1.49 秒である。
flDecayHFRatio
高周波数のディケイ時間と低周波数のディケイタイムの比。値の範囲は DSFX_I3DL2REVERB_DECAYHFRATIO_MIN から DSFX_I3DL2REVERB_DECAYHFRATIO_MAX で、デフォルト値は DSFX_I3DL2REVERB_DECAYHFRATIO_DEFAULT または 0.83 である。
lReflections
lRoom を基準とする初期反射の減衰。単位は mB。値の範囲は DSFX_I3DL2REVERB_REFLECTIONS_MIN から DSFX_I3DL2REVERB_REFLECTIONS_MAX で、デフォルト値は DSFX_I3DL2REVERB_REFLECTIONS_DEFAULT または -2,602 mB である。
flReflectionsDelay
ダイレクト パスを基準とする初期反射の遅延時間。単位は秒。値の範囲は DSFX_I3DL2REVERB_REFLECTIONSDELAY_MIN から DSFX_I3DL2REVERB_REFLECTIONSDELAY_DEFAULT。デフォルト値は 0.007 秒である。
lReverb
lRoom を基準とする後期リバーブの減衰。単位は mB。値の範囲は DSFX_I3DL2REVERB_REVERB_MIN から DSFX_I3DL2REVERB_REVERB_MAX で、デフォルト値は DSFX_I3DL2REVERB_REVERB_DEFAULT または 200 mB である。
flReverbDelay
最初の反射時間を基準とする、初期反射と後期リバーブ間の制限時間。単位は秒。値の範囲は DSFX_I3DL2REVERB_REVERBDELAY_MIN から DSFX_I3DL2REVERB_REVERBDELAY_MAX で、デフォルト値は DSFX_I3DL2REVERB_REVERBDELAY_DEFAULT または 0.011 秒である。
flDiffusion
後期リバーブ ディケイのエコー密度。単位はパーセント。値の範囲は DSFX_I3DL2REVERB_DIFFUSION_MIN から DSFX_I3DL2REVERB_DIFFUSION_MAX で、デフォルト値は DSFX_I3DL2REVERB_DIFFUSION_DEFAULT または 100.0% である。
flDensity
後期リバーブ ディケイのモーダル密度。単位はパーセント。値の範囲は DSFX_I3DL2REVERB_DENSITY_MIN から DSFX_I3DL2REVERB_DENSITY_MAX で、デフォルト値は DSFX_I3DL2REVERB_DENSITY_DEFAULT または 100.0% である。
flHFReference
参照高周波数。単位は Hz。値の範囲は DSFX_I3DL2REVERB_HFREFERENCE_MIN から DSFX_I3DL2REVERB_HFREFERENCE_MAX で、デフォルト値は DSFX_I3DL2REVERB_HFREFERENCE_DEFAULT または 5000.0 Hz である。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSoundFXI3DL2Reverb8


DSFXChorus

コーラス エフェクトのパラメータを保持する。

typedef struct _DSFXChorus {
    FLOAT       fWetDryMix;
    FLOAT       fDepth;
    FLOAT       fFeedback;
    FLOAT       fFrequency;
    LONG        lWaveform;
    FLOAT       fDelay;
    LONG        lPhase;
} DSFXChorus, *LPDSFXChorus;

typedef const DSFXChorus *LPCDSFXChorus;

メンバ

fWetDryMix
ウェット シグナル (処理済み) とドライ シグナル (未処理) の比率。値の範囲は DSFXCHORUS_WETDRYMIX_MIN から DSFXCHORUS_WETDRYMIX_MAX (完全にウェット) である。
fDepth
低周波数発振器によって乗算される遅延時間のパーセンテージ。パーセンテージの 100 倍の値で指定する。値の範囲は DSFXCHORUS_DEPTH_MIN から DSFXCHORUS_DEPTH_MAX で、デフォルト値は 25 である。
fFeedback
エフェクトの入力にフィードバックされる出力信号のパーセンテージ。値の範囲は DSFXCHORUS_FEEDBACK_MIN から DSFXCHORUS_FEEDBACK_MAX で、デフォルト値は 0 である。
fFrequency
LFO の周波数。値の範囲は DSFXCHORUS_FREQUENCY_MIN から DSFXCHORUS_FREQUENCY_MAX で、デフォルト値は 0 である。
lWaveform
LFO のウェーブフォーム。定義されている値は DSFXCHORUS_WAVE_TRIANGLE および DSFXCHORUS_WAVE_SIN である。デフォルトでは、ウェーブフォームはサインである。
fDelay
再生される前に入力が遅延するミリ秒数。値の範囲は DSFXCHORUS_DELAY_MIN から DSFXCHORUS_DELAY_MAX で、デフォルト値は 0 ミリ秒である。
lPhase
左右の LFO の位相差。値の範囲は DSFXCHORUS_PHASE_MIN から DSFXCHORUS_PHASE_MAX である。設定可能な値は次のように定義されている。
DSFXCHORUS_PHASE_NEG_180
DSFXCHORUS_PHASE_NEG_90
DSFXCHORUS_PHASE_ZERO
DSFXCHORUS_PHASE_90
DSFXCHORUS_PHASE_180

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSoundFXChorus8、コーラス


DSFXCompressor

圧縮エフェクトのパラメータを保持する。

typedef struct _DSFXCompressor {
    FLOAT   fGain;
    FLOAT   fAttack;
    FLOAT   fRelease;
    FLOAT   fThreshold;
    FLOAT   fRatio;
    FLOAT   fPredelay;
} DSFXCompressor, *LPDSFXCompressor;

typedef const DSFXCompressor *LPCDSFXCompressor;

メンバ

fGain
圧縮後の信号の出力ゲイン。値の範囲は DSFXCOMPRESSOR_GAIN_MIN から DSFXCOMPRESSOR_GAIN_MAX で、デフォルト値は 0 dB である。
fAttack
圧縮が最大値に達するまでの時間。値の範囲は DSFXCOMPRESSOR_ATTACK_MIN から DSFXCOMPRESSOR_ATTACK_MAX で、デフォルト値は 0.01 ミリ秒である。
fRelease
入力が fThreshold 以下になった後に圧縮を停止する速度。値の範囲は DSFXCOMPRESSOR_RELEASE_MIN から DSFXCOMPRESSOR_RELEASE_MAX で、デフォルト値は 50 ミリ秒である。
fThreshold
圧縮を開始するポイント (デシベル単位)。値の範囲は DSFXCOMPRESSOR_THRESHOLD_MIN から DSFXCOMPRESSOR_THRESHOLD_MAX で、デフォルト値は -10 dB である。
fRatio
圧縮率。値の範囲は DSFXCOMPRESSOR_RATIO_MIN から DSFXCOMPRESSOR_RATIO_MAX。デフォルト値は 10 で、この値は 10:1 の圧縮を表す。
fPredelay
lThreshold に達してからアタック フェーズが開始されるまでの時間 (ミリ秒単位)。値の範囲は DSFXCOMPRESSOR_PREDELAY_MIN から DSFXCOMPRESSOR_PREDELAY_MAX で、デフォルト値は 0 ミリ秒である。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSoundFXCompressor8、コンプレッション


DSFXDistortion

ディストーション エフェクトのパラメータを保持する。

typedef struct _DSFXDistortion {
    FLOAT   fGain;
    FLOAT   fEdge;
    FLOAT   fPostEQCenterFrequency;
    FLOAT   fPostEQBandwidth;
    FLOAT   fPreLowpassCutoff;
} DSFXDistortion, *LPDSFXDistortion;

typedef const DSFXDistortion *LPCDSFXDistortion;

    メンバ

    fGain
    ディストーション後の信号変化の量。値の範囲は DSFXDISTORTION_GAIN_MIN から DSFXDISTORTION_GAIN_MAX で、デフォルト値は 0 dB である。
    fEdge
    ディストーションの強度を示すパーセンテージ。値の範囲は DSFXDISTORTION_EDGE_MIN から DSFXDISTORTION_EDGE_MAX で、デフォルト値は 50% である。
    fPostEQCenterFrequency
    加える倍音成分の中心周波数。値の範囲は DSFXDISTORTION_POSTEQCENTERFREQUENCY_MIN から DSFXDISTORTION_POSTEQCENTERFREQUENCY_MAX で、デフォルト値は 4000 Hz である。
    fPostEQBandwidth
    加える倍音成分の範囲を決定する周波数帯域の幅。値の範囲は DSFXDISTORTION_POSTEQBANDWIDTH_MIN から DSFXDISTORTION_POSTEQBANDWIDTH_MAX で、デフォルト値は 4000 Hz である。
    fPreLowpassCutoff
    高周波数倍音の減衰のフィルタ カットオフ。値の範囲は DSFXDISTORTION_PRELOWPASSCUTOFF_MIN から DSFXDISTORTION_PRELOWPASSCUTOFF_MAX で、デフォルト値は 4000 Hz である。

    注意

    fPostEQBandwidth、fPostEQCenterFrequency、および fPreLowpassCutoff の値は、バッファの周波数の 3 分の 1 を超えることはできない。

    動作環境

    ヘッダー : dsound.h で宣言。

    参照

    IDirectSoundFXDistortion8、ディストーション


DSFXEcho

エコー エフェクトのパラメータを保持する。

typedef struct _DSFXEcho {
    FLOAT   fWetDryMix;
    FLOAT   fFeedback;
    FLOAT   fLeftDelay;
    FLOAT   fRightDelay;
    LONG    lPanDelay;
} DSFXEcho, *LPDSFXEcho;

typedef const DSFXEcho *LPCDSFXEcho;

    メンバ

    fWetDryMix
    ウェット シグナル (処理済み) とドライ シグナル (未処理) の比率。DSFXECHO_WETDRYMIX_MIN から DSFXECHO_WETDRYMIX_MAX (完全にウェット) の範囲でなければならない。
    fFeedback
    入力にフィードバックされる出力のパーセンテージ。値の範囲は DSFXECHO_FEEDBACK_MIN から DSFXECHO_FEEDBACK_MAX で、デフォルト値は 0 である。
    fLeftDelay
    左チャンネルの遅延 (ミリ秒単位)。値の範囲は DSFXECHO_LEFTDELAY_MIN から DSFXECHO_LEFTDELAY_MAX で、デフォルト値は 333 ミリ秒である。
    fRightDelay
    右チャンネルの遅延 (ミリ秒単位)。値の範囲は DSFXECHO_RIGHTDELAY_MIN から DSFXECHO_RIGHTDELAY_MAX で、デフォルト値は 333 ミリ秒である。
    lPanDelay
    左右のディケイをそれぞれの連続するエコーとスワップするかどうかを指定する値。デフォルト値は 0 で、スワップしないことを意味する。可能な値は、DSFXECHO_PANDELAY_MIN (FALSE と等価) および DSFXECHO_PANDELAY_MAX (TRUE と等価) として定義される。

    動作環境

    ヘッダー : dsound.h で宣言。

    参照

    IDirectSoundFXEcho8、エコー


DSFXFlanger

フランジ エフェクトのパラメータを保持する。

typedef struct _DSFXFlanger {
    FLOAT   fWetDryMix;
    FLOAT   fDepth;
    FLOAT   fFeedback;
    FLOAT   fFrequency;
    LONG    lWaveform;
    FLOAT   fDelay;
    LONG    lPhase;
} DSFXFlanger, *LPDSFXFlanger;

typedef const DSFXFlanger *LPCDSFXFlanger;

メンバ

fWetDryMix
ウェット シグナル (処理済み) とドライ シグナル (未処理) の比率。DSFXFLANGER_WETDRYMIX_MIN から DSFXFLANGER_WETDRYMIX_MAX (完全にウェット) の範囲でなければならない。
fDepth
低周波数発振器 (LFO) によって乗算される遅延時間のパーセンテージ。パーセンテージの 100 倍の値で指定する。値は DSFXFLANGER_DEPTH_MIN から DSFXFLANGER_DEPTH_MAX の範囲でなければならない。デフォルト値は 25 である。
fFeedback
エフェクトの入力にフィードバックされる出力信号のパーセンテージ。値の範囲は DSFXFLANGER_FEEDBACK_MIN から DSFXFLANGER_FEEDBACK_MAX で、デフォルト値は 0 である。
fFrequency
LFO の周波数。値の範囲は DSFXFLANGER_FREQUENCY_MIN から DSFXFLANGER_FREQUENCY_MAX で、デフォルト値は 0 である。
lWaveform
LFO のウェーブフォーム。デフォルトでは、ウェーブフォームはサインである。値は次のように定義されている。
DSFXFLANGER_WAVE_TRIANGLE
三角波。
DSFXFLANGER_WAVE_SIN
正弦波。
fDelay
再生される前に入力が遅延するミリ秒数。値の範囲は DSFXFLANGER_DELAY_MIN から DSFXFLANGER_DELAY_MAX で、デフォルト値は 0 ミリ秒である。
lPhase
左右の LFO の位相差。値の範囲は DSFXFLANGER_PHASE_MIN から DSFXFLANGER_PHASE_MAX である。設定可能な値は次のように定義されている。
DSFXFLANGER_PHASE_NEG_180
DSFXFLANGER_PHASE_NEG_90
DSFXFLANGER_PHASE_ZERO
DSFXFLANGER_PHASE_90
DSFXFLANGER_PHASE_180

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSoundFXFlanger8、フランジ


DSFXGargle

振幅変調エフェクトのパラメータを保持する。

typedef struct _DSFXGargle {
    DWORD  dwRateHz;
    DWORD  dwWaveShape;
} DSFXGargle, *LPDSFXGargle;

typedef const DSFXGargle *LPCDSFXGargle;

メンバ

dwRateHz
変調率 (Hz 単位)。DSFXGARGLE_RATEHZ_MIN から DSFXGARGLE_RATEHZ_MAX の範囲でなければならない。
dwWaveShape
変調波の形状。次のフラグが定義されている。
DSFXGARGLE_WAVE_TRIANGLE
三角波。
DSFXGARGLE_WAVE_SQUARE
矩形波。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSoundFXGargle8、ガーグル


DSFXParamEq

パラメトリック イコライザ エフェクトのパラメータを保持する。

typedef struct _DSFXParamEq {
    FLOAT fCenter;
    FLOAT fBandwidth;
    FLOAT fGain;
} DSFXParamEq, *LPDSFXParamEq;

メンバ

fCenter
中心周波数 (Hz 単位)。値の範囲は DSFXPARAMEQ_CENTER_MIN から DSFXPARAMEQ_CENTER_MAX である。この値は、バッファの周波数の 3 分の 1 を超えることはできない。
fBandwidth
帯域幅 (半音単位)。値の範囲は DSFXPARAMEQ_BANDWIDTH_MIN から DSFXPARAMEQ_BANDWIDTH_MAX である。
fGain
ゲイン。値の範囲は DSFXPARAMEQ_GAIN_MIN から DSFXPARAMEQ_GAIN_MAX である。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSoundFXParamEq8、パラメトリック イコライザ


DSFXWavesReverb

ウェーブ リバーブ エフェクトのパラメータを保持する。

typedef struct _DSFXWavesReverb {
    FLOAT   fInGain;
    FLOAT   fReverbMix;
    FLOAT   fReverbTime;
    FLOAT   fHighFreqRTRatio;
} DSFXWavesReverb, *LPDSFXWavesReverb;

typedef const DSFXWavesReverb *LPCDSFXWavesReverb;

メンバ

fInGain
信号の入力ゲイン。単位はデシベル (dB)。値の範囲は、DSFX_WAVESREVERB_INGAIN_MIN から DSFX_WAVESREVERB_INGAIN_MAX。デフォルト値は DSFX_WAVESREVERB_INGAIN_DEFAULT または 0 dB である。
fReverbMix
リバーブのミキシング量。単位は dB。値の範囲は、DSFX_WAVESREVERB_REVERBMIX_MIN から DSFX_WAVESREVERB_REVERBMIX_MAX。デフォルト値は DSFX_WAVESREVERB_REVERBMIX_DEFAULT または 0 dB である。
fReverbTime
リバーブの時間。単位はミリ秒。値の範囲は、DSFX_WAVESREVERB_REVERBTIME_MIN から DSFX_WAVESREVERB_REVERBTIME_MAX。デフォルト値は DSFX_WAVESREVERB_REVERBTIME_DEFAULT または 1000 である。
fHighFreqRTRatio
値の範囲は、DSFX_WAVESREVERB_HIGHFREQRTRATIO_MIN から DSFX_WAVESREVERB_HIGHFREQRTRATIO_MAX。デフォルト値は DSFX_WAVESREVERB_HIGHFREQRTRATIO_DEFAULT または 0.001 である。

動作環境

ヘッダー : dsound.h で宣言。

参照

IDirectSoundFXWavesReverb8


WAVEFORMATEX

ウェーブフォーム オーディオ データのフォーマットを定義する。この構造体には、ウェーブフォーム オーディオ データ形式すべてに共通のフォーマット情報のみが含まれる。追加情報が必要なフォーマットでは、この構造体が最初のメンバとして、ほかの情報と共に別の構造体に含まれる。

この構造体は Platform SDK の一部であり、Dsound.h では宣言されない。便宜上ここで説明している。

typedef struct {
    WORD  wFormatTag;
    WORD  nChannels;
    DWORD nSamplesPerSec;
    DWORD nAvgBytesPerSec;
    WORD  nBlockAlign;
    WORD  wBitsPerSample;
    WORD  cbSize;
} WAVEFORMATEX;

メンバ

wFormatTag
ウェーブフォーム オーディオ フォーマットのタイプ。多くの圧縮アルゴリズムのフォーマット タグが、Microsoft で登録されている。フォーマット タグの完全なリストは、ヘッダー ファイル Mmreg.h に記述されている。1 チャンネルまたは 2 チャンネル PCM データの場合、この値は WAVEFORMAT_PCM となる。
nChannels
ウェーブフォーム オーディオ データのチャンネル数。モノラル データは 1 つのチャンネルを使い、ステレオ データは 2 つのチャンネルを使う。
nSamplesPerSec
サンプリング レート。1 秒あたりのサンプル数 (Hz) で表す。wFormatTag が WAVE_FORMAT_PCM の場合、nSamplesPerSec の一般的な値は 8.0 kHz、11.025 kHz、22.05 kHz、および 44.1 kHz である。PCM フォーマットでない場合、このメンバはメーカーのフォーマット タグの仕様に従って計算する必要がある。
nAvgBytesPerSec
フォーマット タグで必要な平均データ転送速度。単位は、1 秒あたりのバイト数。wFormatTag が WAVE_FORMAT_PCM である場合、nAvgBytesPerSec は nSamplesPerSec と nBlockAlign の積に等しくする。PCM フォーマットでない場合、このメンバはメーカーのフォーマット タグの仕様に従って計算する必要がある。
nBlockAlign
ブロック アライメント (バイト単位)。ブロック アライメントは、wFormatTag フォーマット タイプの最小単位である。wFormatTag が WAVE_FORMAT_PCM または WAVE_FORMAT_EXTENSIBLE である場合、nBlockAlign は nChannels と wBitsPerSample の積を 8 で割った値 (バイトあたりのビット数) に等しくなる必要がある。PCM フォーマットでない場合、このメンバはメーカーのフォーマット タグの仕様に従って計算する必要がある。

ソフトウェアは、複数の nBlockAlign バイトを、一度に処理しなければならない。デバイスに書き込むデータ、およびデバイスから読み込むデータは、常にブロックの先頭から開始しなければならない。たとえば、PCM データの再生を、サンプルの中間 (つまり、非ブロック整列の境界) で開始することは不正である。

wBitsPerSample
wFormatTag フォーマット タイプの、サンプリングあたりのビット数。wFormatTag が WAVE_FORMAT_PCM である場合、wBitsPerSample は 8 または 16 とする。wFormatTag が WAVE_FORMAT_EXTENSIBLE である場合は、任意の 8 の倍数を設定できる。
cbSize
WAVEFORMATEX 構造体の後ろに追加されるフォーマット情報のサイズ (バイト単位)。この情報を非 PCM フォーマットで使用して、wFormatTag の追加属性を格納することができる。wFormatTag で必要な追加情報がない場合、このメンバは 0 に設定しなければならない。WAVE_FORMAT_PCM フォーマットでは、このメンバは無視される。

動作環境

ヘッダー : mmreg.h で宣言。

参照

WAVEFORMATEXTENSIBLE


WAVEFORMATEXTENSIBLE

3 つ以上のチャンネルを持つフォーマットにおいて、ウェーブフォーム オーディオ データのフォーマットを決定する。

この構造体は Platform SDK の一部であり、Dsound.h では宣言されない。便宜上ここで説明している。

typedef struct {
    WAVEFORMATEX  Format;
    union {
        WORD      wValidBitsPerSample;
        WORD      wSamplesPerBlock;
        WORD      wReserved;
    } Samples;
    DWORD         dwChannelMask;
    GUID          SubFormat;
} WAVEFORMATEXTENSIBLE, *PWAVEFORMATEXTENSIBLE;

メンバ

Format
基本フォーマットを指定する WAVEFORMATEX 構造体。wFormatTag メンバは、Mmreg.h で定義された WAVE_FORMAT_EXTENSIBLE でなければならない。cbSize メンバは、少なくとも 22 でなければならない。
wValidBitsPerSample
信号中の精度のビット数。通常は WAVEFORMATEX.wBitsPerSample に等しい。
wSamplesPerBlock
圧縮された 1 ブロックのオーディオ データに保持されるサンプル数。この値が 0 の場合、各ブロックのサンプル数は可変となる。
wReserved
wValidBitsPerSample および wSamplesPerBlock がフォーマットに適用されない場合は、0 に設定する。
dwChannelMask
チャンネルを指定するビットマスク。「注意」を参照すること。
SubFormat
データのサブフォーマット。Ksmedia.h で定義されている KSDATAFORMAT_SUBTYPE_PCM でなければならない。

注意

dwChannelMask メンバは、マルチチャンネル ストリームでのチャンネルを示す。最下位ビットが左前のスピーカ、次のビットが右前のスピーカのように、各ビットが対応している。各ビットは順に、Ksmedia.h および Mmreg.h で次のように定義されている。

SPEAKER_FRONT_LEFT
SPEAKER_FRONT_RIGHT
SPEAKER_FRONT_CENTER
SPEAKER_LOW_FREQUENCY
SPEAKER_BACK_LEFT
SPEAKER_BACK_RIGHT
SPEAKER_FRONT_LEFT_OF_CENTER
SPEAKER_FRONT_RIGHT_OF_CENTER
SPEAKER_BACK_CENTER
SPEAKER_SIDE_LEFT
SPEAKER_SIDE_RIGHT
SPEAKER_TOP_CENTER
SPEAKER_TOP_FRONT_LEFT
SPEAKER_TOP_FRONT_CENTER
SPEAKER_TOP_FRONT_RIGHT
SPEAKER_TOP_BACK_LEFT
SPEAKER_TOP_BACK_CENTER
SPEAKER_TOP_BACK_RIGHT

この構造体の詳細については、http://www.microsoft.com/hwdev/audio/multichaud.htm の「Enhanced Audio Formats for Multi-Channel Configurations and High-Bit Resolution」を参照すること。

動作環境

ヘッダー : mmreg.h および ksproxy.h で宣言。


DirectSound 戻り値

ここでは、DirectSound のメソッドによって返される可能性のあるさまざまなエラー コードについて簡単に説明する。各メソッドが返す可能性のある特定のコードのリストについては、個別のメソッドの説明を参照すること。それらのリストは必ずしも包括的なものとは限らない。

エラー コードは以下のトピックに示されている。

  • DirectSound 戻り値 (値)
  • DirectSound 戻り値 (名前)


DirectSound 戻り値 (値)

次の表は、16 進値で格納される DirectSound 戻り値を示している。説明については、定数をクリックすること。

16 進値 | 定数
0x00000000 | DS_OK
0x00000007 | DSERR_OUTOFMEMORY
0x000001AE | DSERR_NOINTERFACE
0x0878000A | DS_NO_VIRTUALIZATION
0x08780014 | DS_INCOMPLETE
0x80004001 | DSERR_UNSUPPORTED
0x80004005 | DSERR_GENERIC
0x80070005 | DSERR_ACCESSDENIED
0x80070057 | DSERR_INVALIDPARAM
0x8878000A | DSERR_ALLOCATED
0x8878001E | DSERR_CONTROLUNAVAIL
0x88780032 | DSERR_INVALIDCALL
0x88780046 | DSERR_PRIOLEVELNEEDED
0x88780064 | DSERR_BADFORMAT
0x88780078 | DSERR_NODRIVER
0x88780082 | DSERR_ALREADYINITIALIZED
0x88780096 | DSERR_BUFFERLOST
0x887800A0 | DSERR_OTHERAPPHASPRIO
0x887800AA | DSERR_UNINITIALIZED
0x887810B4 | DSERR_BUFFERTOOSMALL
0x887810BE | DSERR_DS8_REQUIRED
0x88781161 | DSERR_OBJECTNOTFOUND


DirectSound 戻り値 (名前)

次のリストは、すべての DirectSound 戻り値を示している。値から定数を確認するには、「DirectSound 戻り値 (値)」を参照すること。

DS_OK
メソッドは成功した。
DS_NO_VIRTUALIZATION
バッファは作成されたが、ほかの 3D アルゴリズムが代用された。
DS_INCOMPLETE
メソッドは成功したが、得られていないオプション エフェクトもある。
DSERR_ACCESSDENIED
アクセスが拒否されたため、要求は失敗した。
DSERR_ALLOCATED
優先レベルなどのリソースがほかの呼び出しによって既に使用中であるため、要求は失敗した。
DSERR_ALREADYINITIALIZED
オブジェクトは既に初期化されている。
DSERR_BADFORMAT
指定したウェーブ フォーマットはサポートされていない。
DSERR_BUFFERLOST
バッファ メモリが失われたため、復元しなければならない。
DSERR_BUFFERTOOSMALL
バッファ サイズが不十分で、エフェクト処理を実行できない。
DSERR_CONTROLUNAVAIL
呼び出し元が要求するバッファ コントロール (ボリューム、パンなど) は利用できない。
DSERR_DS8_REQUIRED
要求された機能に対して、CLSID_DirectSound8 クラスまたはそれ以降の DirectSound オブジェクトが要求されている。詳細については、「IDirectSound8」を参照すること。
DSERR_GENERIC
DirectSound サブシステム内で不確定のエラーが発生した。
DSERR_INVALIDCALL
このオブジェクトの現在の状態では、この関数は有効ではない。
DSERR_INVALIDPARAM
無効なパラメータが関数に渡された。
DSERR_NOAGGREGATION
このオブジェクトは COM 集合化をサポートしない。
DSERR_NODRIVER
利用可能なサウンド ドライバが存在しないか、指定した GUID が有効な DirectSound デバイス ID ではない。
DSERR_NOINTERFACE
要求された COM インターフェイスは利用できない。
DSERR_OBJECTNOTFOUND
要求されたオブジェクトが見つからなかった。
DSERR_OTHERAPPHASPRIO
ほかのアプリケーションがより高い優先レベルを持っているため、この呼び出しは成功しなかった。
DSERR_OUTOFMEMORY
DirectSound サブシステムは、呼び出し元の要求を完了するための十分なメモリを割り当てられなかった。
DSERR_PRIOLEVELNEEDED
呼び出し元は、関数を成功させるために必要な優先レベルを持っていない。
DSERR_UNINITIALIZED
ほかのメソッドを呼び出す前に IDirectSound8::Initialize メソッドを呼び出さなかったか、呼び出しが成功しなかった。
DSERR_UNSUPPORTED
呼び出した関数はこの時点ではサポートされていない。


DirectInput

このセクションでは、Microsoft® DirectX® API (Application Programming Interface) の Microsoft DirectInput® コンポーネントについて説明する。DirectInput API は、キーボード、マウス、ジョイスティック、その他ゲーム コントローラからのデータの処理に使用する。

ドキュメントの概要については、「ロードマップ」を参照すること。


ロードマップ

Microsoft® DirectInput® の使用について、以下のセクションに分けて説明する。このページは、DirectInput 開発者としての経験レベルに応じたドキュメントのガイドとして利用できる。

DirectInput の新機能。Microsoft® DirectX® の今回のバージョンで追加された機能のまとめ。既に Microsoft DirectInput® を使用した経験があり、新機能を利用したい場合は、このセクションを参照する。

DirectInput の概要。DirectInput の機能とその実装手順についての高度な概要。DirectInput を初めて使用するユーザーは、このセクションから読み始めること。

DirectInput について。DirectInput のオブジェクトとインターフェイスについて、そして Microsoft Windows® メッセージ システムとの関係についての概要。DirectInput を初めて使用するユーザーは、このセクションを参照すること。

DirectInput の使い方。API (application programming interface) の説明。このセクションでは、前の 2 つのセクションより詳しい概念的な情報を説明する。また、デバイスの設定、データの取得、フォース フィードバック エフェクトの実装で使用する API 要素についても説明する。初心者の場合は、少なくとも、このセクションの内容をよく理解すること。後で必要なトピックを参照することができる。このセクションは、「DirectInput C/C++ リファレンス」とあわせて利用する。

プログラミングのヒントとツール。高度なプログラミング関連トピックと、DirectX Software Development Kit (SDK) 付属の DirectInput ツールについての説明。

DirectInput C/C++ チュートリアル。ほとんどの場合、SDK のサンプルに基づくステップ バイ ステップ方式のチュートリアル。サンプル コードを使うと理解しやすい場合は、「DirectInput の概要」と「DirectInput について」を読んだ後、このチュートリアルに進むのがよい。

DirectInput C/C++ サンプル。SDK に付属している DirectInput の C/C++ サンプル アプリケーションへのガイド。DirectInput の使用方法、機能などが説明されている。

DirectInput C/C++ リファレンス。API のリファレンス情報。インターフェイス、メソッド、構造体、マクロ、その他要素の詳細を知りたい場合は、このセクションを利用する。


DirectInput の新機能

Microsoft® DirectInput® の新機能は次のとおりである。

アクション マッピング
Microsoft DirectInput for Microsoft DirectX® 8.0 では、アクション マッピングという重要な新機能が導入された。アクション マッピングは、特定のデバイス オブジェクト (特定のボタンや軸) の存在に依存しない、入力アクションと入力デバイスとの間の接続確立を可能にする。アクション マッピングは、入力ループを簡素化し、ゲームにおけるカスタムのゲーム ドライバ、カスタムのデバイス プロファイラ、およびカスタムの環境設定ユーザー インターフェイスの必要性を軽減する。

詳細については、「アクション マッピング」を参照すること。

DirectInput オブジェクトの新機能
DirectInput オブジェクトは、IDirectInput8 インターフェイスにより表現される。新しいヘルバー関数 DirectInput8Create は、オブジェクトを作成し、このインターフェイスを取得する。IDirectInput8 には新しい CLSID があり、これまでの DirectX バージョンで使用されていたクラス CLSID_DirectInput のオブジェクトに対するインターフェイス上で QueryInterface を呼び出しても取得できない。
新しいキーボード プロパティ
2 つのキーボード プロパティが追加された。ローカライズされたキー名を取得する DIPROP_KEYNAME と、スキャン コードを取得する DIPROP_SCANCODE である。
rglSlider 配列内のジョイスティック スライダ データ
ジョイスティック スライダ データは、DirectX の前のバージョンでは DIJOYSTATE または DIJOYSTATE2 構造体の Z 軸に割り当てられていたが、今回のバージョンでは同じ構造体の rglSlider 配列内に格納される。


DirectInput の概要

Microsoft® DirectInput® は、マウス、キーボード、ジョイスティック、その他ゲーム コントローラの入力デバイスに加え、フォース フィードバック (入出力) デバイスもサポートする API である。

このセクションでは、DirectInput の能力とアプリケーションでの設定方法について、簡単な概要を説明する。以下のトピックに分けて、説明する。

  • DirectInput のパワー
  • DirectInput の基礎知識

DirectInput の機能の総合的説明については、「DirectInput について」を参照すること。

DirectInput API (application programming interface) の使用法をステップ バイ ステップ方式で説明するガイドについては、以下のトピックを参照すること。

  • DirectInput の使い方
  • DirectInput C/C++ チュートリアル


DirectInput のパワー

Microsoft® DirectInput® は、Microsoft Win32® API がサポートしていないデバイスに新しいサービスを提供することに加え、Microsoft Windows® メッセージに依存せずに、ハードウェア ドライバと直接通信することにより、入力データへのアクセスを高速化している。

DirectInput を使うと、アプリケーションがバックグラウンドにある場合でも、入力デバイスに対するアクセス権を取得できる。また、フォース フィードバックのほか、あらゆるタイプの入力デバイスを完全にサポートしている。

アクション マッピングを介して、アプリケーションは、データがどんなデバイスで生成されたかを知らなくても、入力データを取得することができる。

DirectInput の拡張サービスと性能の改善により、DirectInput は、Windows で動作するゲーム、シミュレーション、およびその他のリアルタイム対話型アプリケーションに対する有用なツールとなっている。

DirectInput では、テキスト入力にキーボードを使用したり、移動にマウスを使用するアプリケーションが有利になることはない。詳細については、「Windows との相互作用」を参照すること。


DirectInput の基礎知識

ここでは、Microsoft® DirectInput® の設定法と単純なアプリケーションでの使用に関する概要について説明する。

このステップの詳細と例については、「DirectInput の使い方」と「DirectInput C/C++ チュートリアル」を参照すること。

注 : DirectInput を理解するには、以下の用語を理解する必要がある。

  • DirectInput オブジェクト : ルートの DirectInput インターフェイス。
  • デバイス : キーボード、マウス、ジョイスティック、その他の入力デバイス。
  • DirectInputDevice オブジェクト : キーボード、マウス、ジョイスティック、その他の入力デバイスを表すコード。
  • デバイス オブジェクト : DirectInput デバイス オブジェクト上のキー、ボタン、トリガなどを表すコード。デバイス オブジェクト インスタンス とも呼ぶ。

以下のステップは、アプリケーションにおいて、どのデバイス オブジェクト (ボタン、軸など) がデータ項目を生成したかを確認するための DirectInput の単純な実装を示している。

  1. DirectInput オブジェクトを作成する。このオブジェクトのメソッドを使用して、デバイスを列挙し、DirectInput デバイス オブジェクトを作成する。
  2. デバイスを列挙する。システム マウスまたはキーボードのみを使用する場合は、このステップは必ずしも必要ではない。ユーザーのシステム上でほかにどんな入力デバイスが使用できるかを確認するには、DirectInput にデバイスを列挙させる。DirectInput は、設定基準と一致するデバイスを発見するたびに、その能力をチェックする機会を提供してくれる。また、そのデバイスを表す DirectInput デバイス オブジェクトを作成するための固有の識別子も取得する。
  3. 使用デバイスごとに DirectInputDevice オブジェクトを作成する。これには、列挙中に取得された固有の識別子が必要となる。システム マウスまたはキーボードについては、標準の GUID を使用できる。
  4. デバイスを設定する。デバイスごとに、まず協調レベルを設定し、他のアプリケーションやシステムとそのデバイスを共有する方法を指定する。また、データ パケット内で、ボタンや軸などそのデバイス オブジェクトを識別するためのデータ形式を設定する。バッファリング データを取得する場合 (ステートではなくイベントを取得する場合) は、バッファ サイズも設定する必要がある。オプションとして、この段階でデバイスに関する情報を取得し、アプリケーションの動作をそれに応じて調整する。また、ジョイスティックの軸によって返される値の範囲などのプロパテイを設定することもできる。
  5. デバイスを取得する。この段階で、DirectInput に対し、デバイスからデータを受け取る準備ができたことを通知する。
  6. データを取得する。一定の間隔で、普通はメッセージ ループまたはレンダリング ループを 1 回繰り返すたびに、各デバイスの現在の状態か前回取得後に発生したイベントの記録のいずれかを取得する。好みに応じて、イベントが発生したら DirectInput から通知させることもできる。
  7. データを処理する。アプリケーションは、ボタンや軸の状態か、キーが押されているか離されているかなどのイベントのいずれかに反応できる。
  8. DirectInput を終了する。終了する前に、アプリケーションはすべてのデバイスの取得を解除して解放し、次に DirectInput オブジェクトを解放しなければならない。

DirectInput を実装する方法は、これだけではない。現在使用されている、または将来使用されるバラエティ豊富な入力デバイスを活用するため、またユーザーの環境設定を簡素化するため、アクション マッピングを使用することができる。

デバイスにアクション マッピングを設定することにより、アプリケーションの各アクションに使用するデバイス オブジェクトを、DirectInput に決めさせることができる。たとえばレーシング ゲームで、スロットルが常に y 軸によって制御されるように指定する代わりに、AXIS_THROTTLE というアクションを作成し、デバイス上で最も適切な軸に DirectInput がアクションを割り当てるようにすることができる。イベントを取得したときは、そのイベントを生成したデバイス オブジェクトではなく、そのイベントに関連付けられているアクションによってイベントを識別する。

詳細については、「アクション マッピング」を参照すること。


DirectInput について

このセクションでは、Microsoft® DirectInput® の基本構造と、Microsoft Windows® メッセージ システムと DirectInput 間の関係について説明する。

  • DirectInput オブジェクト
  • Windows との相互作用

ここで説明する DirectInput の各要素の実装方法については、「DirectInput の使い方」を参照すること。


DirectInput オブジェクト

入力専用の Microsoft® DirectInput® の実装は、IDirectInput8 COM インターフェイスをサポートする DirectInput オブジェクトと、データを提供する入力デバイスごとの DirectInputDevice オブジェクトで構成される。そして 各 DirectInputDevice オブジェクトは、キー、ボタン、軸などの個別の制御手段またはスイッチである デバイス オブジェクト を持つ。デバイス オブジェクトは、デバイス オブジェクト インスタンスとも呼ばれる。

それぞれの DirectInputDevice オブジェクトは、マウス、キーボード、またはジョイスティックなどの入力デバイスを表すDirectInput API では、ジョイスティックという用語は、マウスやキーボード以外の入力デバイスを指す。タッチパッド付きキーボードなど、実際には異なる種類の入力デバイスを組み合わせた物理デバイスは、2 つまたはそれ以上の DirectInputDevice オブジェクトとして表される。フォースフィードバック デバイスは、入力と出力の両方を操作する 1 つのジョイスティック オブジェクトとして表される。

DirectInputDevice オブジェクトは、IDirectInputDevice8 インターフェイスをインスタンス化する。アプリケーションは、デバイス上で使用可能なオブジェクトの数とタイプを IDirectInputDevice8::EnumObjects メソッドを使って確認する。個別のデバイス オブジェクトは、コード オブジェクトとしてカプセル化されずに、DIDEVICEOBJECTINSTANCE 構造体として記述される。

フォース フィードバック エフェクトは、IDirectInputEffect インターフェイスにより表される。このインターフェイスの各メソッドを使って、エフェクトの生成、変更、開始、および停止を行う。

すべての DirectInput インターフェイスは、ANSI 版と Unicode 版で使用できる。コンパイル時に「UNICODE」が定義されている場合は、UNICODE 版が使用される。


Windows との相互作用

Microsoft® DirectInput® はデバイス ドライバに直接働きかけて動作するので、Microsoft Windows® のマウス メッセージとキーボード メッセージは抑制または無視される。DirectInput は、コントロール パネルでユーザーが行ったマウスとキーボードの設定も無視する。ただし、ジョイスティックやその他のゲーム コントローラのキャリブレーションの設定は使用する。

DirectInput は、キーボードの文字反復の設定を認識しない。バッファリング データを利用しているときは、DirectInput は、個々のキーの「押し」と「離し」を反復なしの 1 つのイベントとして解釈する。直接データを利用しているときは、DirectInput が関与するのはキーの現在の物理的状態のみであり、Windows で解釈されるキーボード イベントには関与しない。

DirectInput は、文字変換や平行移動を実行しない。たとえば Shift キーは、他のキーの修正子としてではなく、他のキーと同じように処理される。キーは、ユーザーのシステム言語設定に関係なく、同じ識別子を返す。

Windows 2000 では、排他モードでキーボードを取得すると、その後で起動されたどのアプリケーションもキーボード データを取得できなくなる。

DirectInput は直接マウス ドライバに作用するため、ウィンドウ表示アプリケーションに対してマウス データを解釈する Windows サブシステムをバイパスする。Windows カーソルを使用して移動するアプリケーションは、標準の Windows マウス メッセージおよび Microsoft® Win32® 関数を使用する。

排他モードでマウスを使用すると、DirectInput はマウス メッセージを抑制する。その結果、Windows は標準カーソルを表示できなくなる。

DirectInput は加速値やボタン機能の入れ替えなどのコントロール パネルの設定を無視する。しかし、ドライバそのもので設定を認識する。たとえば、ユーザーが 3 つボタンのマウスを持っていて、ドライバ ユーティリティ ソフトウェアを使って中央のボタンにダブルクリックのショートカットを割り当てると、DirectInput は、中央のボタンの 1 回のクリックを主ボタンの 2 回のクリックとして報告する。


DirectInput の使い方

ここでは、Microsoft® DirectInput® の実装について説明する。より幅広い概要については、「DirectInput について」を参照すること。

次のトピックについて解説する。

  • DirectInput の作成
  • DirectInput デバイスの列挙
  • DirectInput デバイス
  • DirectInput デバイス データ
  • アクション マッピング
  • フォース フィードバック


DirectInput の作成

Microsoft® DirectInput® アプリケーションでは、必ず最初に IDirectInput8 インターフェイスを取得する。これを最も簡単に行う方法は、DirectInput8Create 関数を呼び出すことである。

単一の Microsoft® DirectInput オブジェクトを作成し、アプリケーションが終了するまで解放するべきではない。


DirectInput デバイスの列挙

Microsoft® DirectInput® は、すべての使用可能な入力デバイスをシステムに問い合わせ、それらが接続されているかどうかを判定し、それらのデバイスに関する情報を返すことができる。このプロセスを列挙と呼ぶ。

標準のキーボードやマウス、またはその両方だけをアプリケーションで使っているなら、使用可能な入力デバイスを列挙する必要はない。「DirectInput デバイスの作成」で説明するように、IDirectInput8::CreateDevice メソッドを呼び出すときは、事前定義されたグローバル変数を使用できる。

ほかのすべての入力デバイス、および複数のキーボードまたはマウスを使用するシステムに関しては、IDirectInput8::EnumDevices および IDirectInput8::EnumDevicesBySemantics を呼び出して、使用可能なデバイスを列挙し、適切なデバイスを選択することができる。また、列挙して、使用可能なデバイスをユーザーが選択できるようにすることもできる。

以下は、IDirectInput8::EnumDevices メソッド実装の例である。

/* lpdi は、有効な IDirectInput8 インターフェイス ポインタである。 */

GUID KeyboardGUID = GUID_SysKeyboard;

lpdi->EnumDevices(DIDEVTYPE_KEYBOARD,
                  DIEnumDevicesCallback,
                  &KeyboardGUID,
                  DIEDFL_ATTACHEDONLY);

1 番目のパラメータは、列挙すべきデバイスのタイプを指定する。タイプに関係なくすべてのデバイスを列挙したければ、NULL とする。それ以外は、DIDEVICEINSTANCE に説明のある DIDEVTYPE_* 値の 1 つを指定する。

2 番目のパラメータは、列挙された各デバイスに対して一度ずつ呼び出されるコールバック関数へのポインタである。この関数は、どのような名前でもよいが、ここではプレースホルダ名の DIEnumDevicesCallback を使用する。

EnumDevices メソッドの 3 番目のパラメータは、コールバック関数に渡す任意の 32 ビットの値である。この例では、GUID 型の変数へのポインタであり、コールバック関数がこの変数へのキーボード インスタンス識別子を割り当てることができるように渡される。

4 番目のパラメータは、列挙対象が全デバイスか、またはアタッチされているデバイスのみ (DIEDFL_ALLDEVICES または DIEDFL_ATTACHEDONLY) かを指定するフラグである。

アプリケーションが複数の入力デバイスを使用している場合、列挙されたとおりにデバイスを初期化するには、コールバック関数を使用するのが適している (例については、「チュートリアル 3 : ジョイスティックの使い方」を参照すること)。デバイスのインスタンス GUID をコールバック関数から取得する。ここでは、デバイスの特定のサブタイプを検索したり、デバイス名をリストボックスに追加したりするなど、別の処理を実行することもできる。

以下のコードは、拡張キーボードの存在をチェックし、見つかったら列挙を停止するコードの例である。見つかったキーボードのインスタンス GUID を KeyboardGUID 変数 (前の例の EnumDevices の呼び出しで pvRef として渡される) に割り当てる。この変数は、次に IDirectInput8::CreateDevice を呼び出す際に使用できる。

BOOL  hasEnhanced;

BOOL CALLBACK DIEnumKbdCallback(LPCDIDEVICEINSTANCE lpddi,
                                LPVOID pvRef)
{
  *(GUID*) pvRef = lpddi->guidInstance;
  if (GET_DIDEVICE_SUBTYPE(lpddi->dwDevType) ==
                       DIDEVTYPEKEYBOARD_PCENH)
  {
    hasEnhanced = TRUE;
    return DIENUM_STOP;
  }
  return DIENUM_CONTINUE;
} // コールバックの終了。

1 番目のパラメータは、デバイスの情報を格納する DIDEVICEINSTANCE 構造体を指す。この構造体は、DirectInput が自動的に作成する。

2 番目のパラメータは、EnumDevices から渡されたデータを指す。この場合は、変数 KeyboardGUID へのポインタである。この変数には当初、デフォルト値が割り当てられているが、デバイスが列挙されるたびに、新しい値が割り当てられる。単一のキーボードに対してどのインスタンス GUID を使用するかは実際には重要でないが、上記のコードは、コールバック関数からインスタンス GUID を取得する技法を具体的に示している。

インスタンス GUID を保存して、後で DirectInputDevice を作成できるようにするのではなく、列挙中に DirectInput によって作成されたデバイスを保存できる。詳細については、「DirectInput デバイスの作成」を参照すること。

この場合の戻り値は、検索対象のデバイスが見つかれば列挙を停止し、そうでなければ続行することを示す。列挙は、全デバイスの列挙が終了すると直ちに自動的に停止する。

IDirectInput8::EnumDevicesBySemantics によるデバイス列挙の詳細については、「アクション マッピング」を参照すること。


DirectInput デバイス

ここでは、マウス、キーボード、ジョイスティックなどのデバイスを表すコード オブジェクトについて記述する。以下のトピックについて説明する。

  • デバイスのセットアップ
  • DirectInput デバイスの作成
  • デバイス能力
  • 協調レベル
  • デバイス オブジェクトの列挙
  • デバイス データ形式
  • デバイス プロパティ
  • デバイスの取得

デバイスからのデータの取得および解釈の方法についての情報は、「DirectInput デバイス データ」を参照すること。


デバイスのセットアップ

アプリケーションは、入力が行われるデバイスごとに Microsoft® DirectInput® デバイス オブジェクトを取得しなければならない。そのデバイスが使用できるように、最低限でもデータ形式の設定やデバイスの取得などの準備もしなければならない。ほかにも、デバイスに関する情報の収集やデバイスのプロパティの変更など、独自のタスクを実行することもある。

以下のタスクは、セットアップ手順の一部である。手順の中には必須のものもあれば、デバイスの詳細情報を必要とする場合、あるいはデフォルト値を変更しなければならない場合に限り必要となるものもある。

  1. DirectInput デバイスを作成する (必須)。「DirectInput デバイスの作成」を参照すること。
  2. デバイス能力を取得する (オプション)。
  3. デバイスのキー、ボタンおよび軸を列挙する (オプション)。「デバイス オブジェクトの列挙」を参照すること。
  4. 協調レベルを設定する (推奨)。
  5. デバイス データ形式を設定する (推奨)。
  6. デバイス プロパティを設定する (バッファリング データを取得する予定ならば、少なくともバッファ サイズを設定しなければならない)。
  7. データを読み取る用意ができたら、デバイスを取得する (必須)。「デバイスの取得」を参照すること。


DirectInput デバイスの作成

デバイスから入力データを取得するには、まずそのデバイスを表すオブジェクトを作成しなければならない。

IDirectInput8::CreateDevice メソッドを使って、IDirectInputDevice8 インターフェイスへのポインタを取得する。その後、このインターフェイスのメソッドを使って、デバイスの操作とデータの取得を行う。

次のコードは、キーボード デバイスを作成する例である。lpdi は IDirectInput8 インターフェイスへのポインタである。

LPDIRECTINPUTDEVICE8  lpdiKeyboard;
lpdi->CreateDevice(GUID_SysKeyboard, &lpdiKeyboard, NULL);

CreateDevice の最初のパラメータはインスタンス GUID であり、インターフェイスの作成対象デバイスのインスタンスを識別する。Microsoft® DirectInput® には、事前定義された 2 つの GUID (GUID_SysMouse および GUID_SysKeyboard) があり、それぞれシステム マウスとシステム キーボードを表す。これらの識別子の 1 つを CreateDevice メソッドに渡すことができる。CreateDevice メソッドのパラメータとして、グローバル変数の GUID_Joystick を使用してはならない。GUID_Joystick は製品 GUID であり、インスタンス GUID ではないからである。

注 : コンピュータに 2 つ以上のマウスがある場合は、すべてのマウスが結合されてシステムデバイスを形成する。キーボードについても同様である。

DirectInput は、このほかにも主にテストに使用する事前定義された 4 つの GUID を用意している。

  • GUID_SysKeyboardEm
  • GUID_SysKeyboardEm2
  • GUID_SysMouseEm
  • GUID_SysMouseEm2.

この GUID の 1 つを CreateDevice に渡すことで、列挙レイヤーを介して、システム キーボードやシステム マウスに対するレベル 1 またはレベル 2 のアクセス権が付与される。これらの GUID は、常にシステム マウスやシステム キーボードを表す。これらはGUID_SysKeyboard および GUID_SysMouse のエイリアスであり、DIEDFL_INCLUDEALIASES フラグが渡されなければ、IDirectInput8::EnumDevices または IDirectInput8::EnumDevicesBySemantics では列挙されない。

システム マウスまたはシステム キーボード以外のデバイスの場合は、EnumDevices または EnumDevicesBySemantics で返されるデバイスのインスタンス GUID を使用する。1 つのデバイスに対するインスタンス GUID は常に同一である。列挙したリストからユーザーに 1 つのデバイスを選択させ、その GUID を構成ファイルに保存しておくと、後のセッションでその GUID を再び使用することができる。


デバイス能力

デバイスからの入力を要求する前に、ユーザーがその能力をある程度知っておく必要がある。ジョイスティックに視点ハットが付いているか。マウスはユーザーのマシンに現在アタッチされているか。

そうした疑問点は、IDirectInputDevice8::GetCapabilities メソッドを呼び出すことにより解決することができる。このメソッドは、能力に関するデータを DIDEVCAPS 構造体に返す。Microsoft® DirectX® のほかの類似の構造体の場合と同様に、メソッドにこの構造体を渡す前に、dwSize メンバを初期化しておかなければならない。

注 : 処理速度やメモリ使用を最適化するために、より小さい DIDEVCAPS_DX3 構造体を利用することができる。構造体の詳細については、Microsoft Software Development Kit (SDK) の Dinput.h を参照すること。

以下のコードは、マウスがアタッチされているかどうか、およびマウスが第 3 軸 (通常は、ホイール) を持っているかどうかをチェックする例である。lpdiMouse は有効な Microsoft DirectInput® デバイスとする。

DIDEVCAPS  DIMouseCaps;
HRESULT    hr;
BOOLEAN    WheelAvailable;

DIMouseCaps.dwSize = sizeof(DIDEVCAPS);
hr = lpdiMouse->GetCapabilities(&DIMouseCaps);
WheelAvailable = ((DIMouseCaps.dwFlags & DIDC_ATTACHED)
        && (DIMouseCaps.dwAxes > 2));

あるボタンまたは軸が存在するかどうかをチェックするもう 1 つの方法は、そのオブジェクトに対して IDirectInputDevice8::GetObjectInfo を呼び出すことである。その呼び出しに対し DIERR_OBJECTNOTFOUND が返ってきた場合、オブジェクトは存在しない。以下のコードでは、第 3 軸ではないにしても z 軸が存在するかどうかを判断する。

DIDEVICEOBJECTINSTANCE  didoi;

didoi.dwSize = sizeof(DIDEVICEOBJECTINSTANCE);
hr = lpdiMouse->GetObjectInfo(&didoi, DIMOFS_Z, DIPH_BYOFFSET);
WheelAvailable = SUCCEEDED(hr);


協調レベル

デバイスの協調レベルは、アプリケーション間および Microsoft® Windows® システムでデバイスを共有する方法を定義する。以下の例のように、協調レベルを設定するには IDirectInputDevice8::SetCooperativeLevel メソッドを使用する。

/* hwnd は、最上位ウィンドウのハンドルである。 */
lpdiDevice->SetCooperativeLevel(hwnd,
        DISCL_NONEXCLUSIVE | DISCL_FOREGROUND)

パラメータは、デバイスに関連する最上位ウィンドウ (一般的には、アプリケーション ウィンドウ) のハンドルと、1 つまたは複数のフラグである。

DirectInput にはデフォルト設定が用意されているが、協調レベルは、明示的に設定しなければならない。これは、DirectInput にウィンドウのハンドルを与えるための唯一の方法だからである。このハンドルがないと、DirectInput は、ジョイスティックの再キャリブレーションなど、ウィンドウ メッセージが必要な状況で反応することができなくなる。

有効なフラグの組み合わせを以下の表に示す。

フラグ | メモ
DISCL_NONEXCLUSIVE DISCL_BACKGROUND | デフォルト設定
DISCL_NONEXCLUSIVE DISCL_FOREGROUND |
DISCL_EXCLUSIVE DISCL_FOREGROUND |
DISCL_EXCLUSIVE DISCL_BACKGROUND | キーボードまたはマウスには無効

キーボードの場合は、DISCL_NOWINKEY と DISCL_NONEXCLUSIVE を同時に使用することもできる。このフラグで Windows キーを無効にすることにより、ユーザーは不注意でアプリケーションを終了することがなくなる。排他モードでは、Windows キーは常に無効である。

注 : Windows キーは、アプリケーションの協調レベルで排他協調レベルを通して受動的に、または DISCL_NOWINKEY フラグを使って能動的に無効にする場合でも、デフォルトのアクション マッピング UI が表示されている間はアクティブになる。

協調レベルには 2 つの構成要素がある。デバイスをフォアグラウンドまたはバックグラウンドで使用するか、および排他または非排他に使用するかである。

フォアグラウンドとバックグラウンド

フォアグラウンド協調レベルは、アプリケーションがフォアグラウンドにある場合、すなわち、入力フォーカスを持つ場合に限り、入力デバイスが使用可能になることを意味する。アプリケーションがバックグラウンドに移ると、入力デバイスは自動的に解放されるか使用不可になる。

バックグラウンド協調レベルとは、実際には「フォアグラウンドとバックグラウンド」のことである。バックグラウンド協調レベルのデバイスは、アプリケーションからいつでも取得して使用できる。

通常は、フォアグラウンド アクセス権だけで十分なはずである。というのも、大半のアプリケーションにとって、ほかのプログラムがフォアグラウンドにある場合に発生する入力に応答するようには設計されていないからである。

アプリケーションの開発中に、条件付きコンパイルを使って、デバッグ用にバックグラウンド協調レベルを設定することは有用である。これにより、アプリケーションは、デバッグ環境への切り替えでバックグラウンドに移動するたびに、デバイスへのアクセスを失うことがなくなる。

排他と非排他

多くの場合、あるアプリケーションがデバイスを排他レベルで使用しているからといって、ほかのアプリケーションが同じデバイスからデータを取得できないということにはならない。「排他レベルで使用」とは、ほかのアプリケーションが同じデバイスを排他には取得できないということを意味する。

たとえばあるミュージック プレーヤー アプリケーションの場合、アプリケーションはバックグラウンドにあっても、ハンドヘルドのリモート コントロール デバイスから入力を受け付ける。ここで、同じリモート コントロール デバイスからの信号に応答して、映画を再生するアプリケーションを実行するとしよう。ユーザーが [Play] を押したら何が起こるだろうか。両方のプログラムが再生を開始することになる。このような結果をユーザーが望んでいるとは思えない。そうならないようにするには、各アプリケーションに DISCL_EXCLUSIVE フラグを設定し、一度にどちらかのプログラムしか実行できないようにする必要がある。

フォース フィードバック エフェクトを利用するには、アプリケーションはデバイスへの排他アクセスができなければならない。

Windows 自体には、マウスへの排他アクセスが必要である。なぜなら、アクティブでないウィンドウ上でのクリックなどのマウス イベントを使って、アプリケーションにデバイスを強制解放させることが可能であり、そのことが、入力バッファからのデータの喪失など、潜在的に有害な結果を生む可能性があるからである。このため、あるアプリケーションが IDirectInput8::CreateDevice に GUID_SysMouseを渡して作成されたシステム マウスに対する排他アクセス権を持っていると、Windows には一切のアクセスが許されず、マウス メッセージは生成されない。さらなる副作用として、カーソルが消えることもある。

あるアプリケーションがキーボードに対する排他アクセス権を持っている場合、DirectInput は一切のキーボード メッセージを抑制する。ただし、Ctrl+Alt+Del キーおよび Windows 95 や Windows 98 での Alt+Tab キーは使用できる。Windows 2000 では、排他モードの DirectInput アプリケーションに続いて起動されるアプリケーションは、キーボード データを取得できない。


デバイス オブジェクトの列挙

デバイス上でどのボタンまたは軸が使用可能であるかを、アプリケーションが確認しなければならない場合がある。この確認を行うには、デバイスを列挙する場合とほぼ同じ方法でデバイス オブジェクトを列挙する。

注 : デバイス ドライバによる制約のため、キーボードのキーおよびインジケータ ライトの列挙は信頼できない。オブジェクトが存在するかのような偽りの報告が行われる場合がある。使用可能なキーに関する基本的情報は、デバイスのサブタイプから取得できるが、メニュー キーなどの追加オブジェクトが使用可能かどうかを判定するには、ユーザーに入力を求める以外、方法はない。

IDirectInputDevice8::EnumObjects の機能は、IDirectInputDevice8::GetCapabilities と重複するところがある。どちらのメソッドも、使用可能なボタンまたは軸がいくつあるかを確認するのに使用できる。しかし、EnumObjects は、特定のオブジェクトの存在をチェックするよりも、むしろ、使用可能なオブジェクトをすべてカタログ化することを目的としたメソッドである。

EnumObjects メソッドには、IDirectInput8::EnumDevices などのようにコールバック関数があって、各オブジェクトに対してほかの処理をさせることができる。たとえば、オブジェクトをリストに追加したり、ユーザー インターフェイス上に対応する項目を作成したりすることである。

以下のコードは、各オブジェクトの名前を抽出して、文字列リストまたは配列に追加できるようにするコールバックの例である。この標準コールバックは、ドキュメントではプレースホルダ名 DIEnumDeviceObjectsCallback で表されているが、自由に名前を付けることができる。この関数は、列挙されるそれぞれオブジェクトに対して、一度ずつ呼び出されることに注意すること。

char  szName[MAX_PATH];

BOOL CALLBACK DIEnumDeviceObjectsCallback(
                      LPCDIDEVICEOBJECTINSTANCE lpddoi,
                      LPVOID pvRef)
{
  lstrcpy(szName, lpddoi->tszName);
  // szName をリストあるいは配列に追加する。
  .
  .
  .
  return DIENUM_CONTINUE;
}

1 番目のパラメータは、オブジェクトの情報を格納する構造体へのポインタである。この構造体は、Microsoft® DirectInput® により自動作成される。

2 番目のパラメータは、EnumObjects の 2 番目のパラメータと同等なデータに対するアプリケーション定義ポインタである。この例では、当パラメータは使用されていない。

この場合の戻り値は、列挙するオブジェクトが存在する限り列挙が続くことを示す。

以下は、EnumObjects メソッドを呼び出し、コールバック関数を動作させる例である。

lpdiMouse->EnumObjects(DIEnumDeviceObjectsCallback,
                       NULL, DIDFT_ALL);

1 番目のパラメータは、コールバック関数のアドレスである。2 番目のパラメータは、コールバック関数の中で、使用または変更したいデータへのポインタとして使用できる。この例では、このパラメータを使用していなので、NULL を渡している。3 番目のパラメータは、列挙の中に含めるオブジェクトのタイプ (複数可) を示すフラグである。この例では、すべてのオブジェクトを列挙することになる。列挙の範囲を限定するには、IDirectInputDevice8::EnumObjects にリストされるほかの DIDFT_* フラグを 1 つ以上使用すればよい

注 : DIDFT_* フラグの一部は、ほかのフラグを組み合わせたものである。たとえば、DIDFT_AXIS は、DIDFT_ABSAXIS | DIDFT_RELAXIS と同等である。


デバイス データ形式

アクション マッピングを使用していない場合、デバイスのデータ形式の設定は、デバイス取得およびデバイス使用を始める前に行う基本的な手順である。デバイスから直接データ (状態データ) を取得することを目的としていない場合でも、データ形式を設定しなければならない。Microsoft® DirectInput® では多くのメソッドでデータ形式を使用し、特定のデバイス オブジェクトを識別する。

デバイス オブジェクトが使用するデバイスとデータ配列の方法は、IDirectInputDevice8::SetDataFormat メソッドが DirectInput に対して指示する。

DIDATAFORMAT 構造体および DIOBJECTDATAFORMAT 構造体のリファレンス中の例には、非標準デバイスに対してカスタム データ形式を設定する方法が示されている。この設定手順は幸いにも、ジョイスティック、キーボード、およびマウスには不要である。DirectInput は、5 つのグローバル変数、すなわち c_dfDIJoystick、c_dfDIJoystick2、c_dfDIKeyboard、c_dfDIMouse、および c_dfDIMouse2 を提供している。これらの変数を SetDataFormat に渡してジョイスティック、キーボード、およびマウスに対する標準データ形式を作成することができる。

以下のサンプル コードで、lpdiMouse は、DirectInputDevice オブジェクトに対する初期化されたポインタである。

lpdiMouse->SetDataFormat(&c_dfDIMouse);

注 : 事前定義された DIDATAFORMAT グローバル変数は const 変数であるので、この中の dwFlags メンバを (たとえば、軸のプロパティを変更するために) 変更することはできない。プロパティを変更するには、データ形式を設定した後で、デバイスを取得する前に、IDirectInputDevice8::SetProperty を使用する。


デバイス プロパティ

Microsoft® DirectInput® デバイスのプロパティには、データ バッファのサイズ、軸が返す値の範囲と細分性、軸データが相対か絶対か、およびジョイスティックの物理的位置と報告データ間の関係に影響するジョイスティック軸のデッド ゾーンと飽和がある。特殊デバイスは、これ以外のプロパティを持つこともある。DirectInput によって定義されたプロパティのリストについては、「IDirectInputDevice8::GetProperty」を参照すること。

1 つの例外 (フォース フィードバック デバイスのゲイン プロパティ) を除いて、プロパティは、デバイスが解放された状態にある場合に限り変更することができる。

IDirectInputDevice8::SetProperty メソッドまたは IDirectInputDevice8::GetProperty メソッドを呼び出す前に、DIPROPHEADER 構造体とデータの 1 つ以上の要素で構成されるプロパティ構造体を設定する必要がある。入力デバイスには多くのプロパティがあるので、SetProperty はこれらのプロパティを定義するあらゆる種類の構造体に対して機能できなくてはならない。DIPROPHEADER 構造体の目的は、プロパティ構造体のサイズとデータの解釈方法を定義することである。

DirectInput は、以下の事前定義されたプロパティ構造体を含む。

  • DIPROPDWORD は、バッファ サイズなど単一の値を要求するプロパティに対して、DIPROPHEADER 構造体と DWORD データ メンバを含む構造体を定義する。
  • DIPROPRANGE はプロパティ範囲に対するもので、2 つの値 (最大値と最小値) を要求する。DIPROPHEADER 構造体と 2 つの LONG データ メンバで構成される。
  • DIPROPGUIDANDPATH は、DirectInput でサポートされていない HID (Human Interface Device) に対してアプリケーションが操作を実行できる、特殊なプロパティ構造体である。この構造体は、DIPROPHEADER 構造体と GUID、およびパスを表す Unicode 文字列で構成される。
  • DIPROPSTRING は、Unicode 文字列プロパティである。この構造体は、DIPROPHEADER 構造体と Unicode 文字列で構成される。

SetProperty の場合、プロパティ構造体のデータ メンバは、プログラマが設定する値である。GetProperty の場合は、現在の値がデータ メンバに返される。

GetProperty または SetProperty を呼び出す前に、DIPROPHEADER 構造体を以下の値で初期化しておかなければならない。

  • プロパティ構造体のサイズ。
  • DIPROPHEADER 構造体自体のサイズ。
  • オブジェクト識別子。
  • オブジェクト識別子の解釈方法を指示する値。

デバイス全体からプロパティを取得したり設定したりする場合、オブジェクト識別子 dwObj は、ゼロであり、dwHow メンバは、DIPH_DEVICE である。1 つのデバイス オブジェクト (たとえば、特定の軸) に対してプロパティを設定または取得したい場合は、dwObj と dwHow の組み合わせ値により、そのオブジェクトが識別される。詳細については、「DIPROPHEADER 構造体」を参照すること。

プロパティ構造体の設定後、取得または変更したいプロパティの識別子と共に、構造体のヘッダーのアドレスを、GetProperty または SetProperty に渡す。

SetProperty および GetProperty に渡されるプロパティを識別するために、以下の値が使用される。詳細については、「IDirectInputDevice8::GetProperty」を参照すること。

  • DIPROP_BUFFERSIZE。「バッファリング データと直接データ」も参照すること。バッファ サイズの設定には、IDirectInputDevice8::SetActionMap メソッドも使用できる。
  • DIPROP_AXISMODE。「相対座標と絶対座標」も参照すること。
  • DIPROP_CALIBRATIONMODE
  • DIPROP_GRANULARITY
  • DIPROP_FFGAIN
  • DIPROP_FFLOAD
  • DIPROP_AUTOCENTER
  • DIPROP_RANGE
  • DIPROP_DEADZONE
  • DIPROP_SATURATION

最後の 3 つのプロパティについての詳細は、「ジョイスティック軸データの解釈」も参照すること。

以下のサンプル コードでは、10 個のデータ項目を保持するようにデバイスのバッファ サイズを設定する。

DIPROPDWORD  dipdw;
HRESULT      hr;
dipdw.diph.dwSize = sizeof(DIPROPDWORD);
dipdw.diph.dwHeaderSize = sizeof(DIPROPHEADER);
dipdw.diph.dwObj = 0;
dipdw.diph.dwHow = DIPH_DEVICE;
dipdw.dwData = 10;
hr = lpdiDevice->SetProperty(DIPROP_BUFFERSIZE, &dipdw.diph);


デバイスの取得

Microsoft® DirectInput® デバイスの取得とは、アプリケーションにデバイスへのアクセスをさせることである。デバイスが取得されている限り、DirectInput は、アプリケーションがデバイスのデータを使用できるようにする。デバイスが取得されていない場合、デバイスの特性に対する操作はできるが、データは一切取得できない。

取得は永続するものではない。アプリケーションは、デバイスを何回でも取得し、解放することがある。

協調レベルによっては、アプリケーションがバックグラウンドに移行すると必ず自動的にデバイスが解放されることがある。マウスの場合、ユーザーがメニューをクリックすると自動的に解放される。クリックした時点で Microsoft Windows® がデバイスの制御を引き継ぐからである。

デバイス プロパティの変更に先立って、そのデバイスを解放する必要がある。唯一の例外として、フォース フィードバック デバイスは、取得状態にあってもゲインを変更できる。

取得の仕組みが必要な理由は、次の 2 つである。

第 1 に、DirectInput は、デバイスからのデータの流れがシステムにより中断されたときには、アプリケーションに通知できなければならない。たとえば、ユーザーが Alt+Tab を使用して別のアプリケーションに切り替え、切り替え後のアプリケーションで入力デバイスを使用した場合に、元のアプリケーションは、入力デバイスがもはや自身に属さず、バッファ状態が変化した可能性があることを知る必要がある。DISCL_FOREGROUND 協調レベルでのアプリケーションを観察してみよう。ユーザーが Shift キーを押しながら別のアプリケーションに切り替える。その後、ユーザーは Shift キーを離し、元のアプリケーションに戻る。元のアプリケーションからみれば、Shift キーは依然として押されている状態である。取得の仕組みでは、元のアプリケーションに入力が終了したことを通知して、この状態から回復させることができる。

第 2 に、アプリケーションがデバイスのプロパティを変更できるので、保護がなければユーザーがデータを取得しようとするたびに、DirectInput がプロパティをチェックしなければならなくなる。これは、かなり非効率であろう。さらに悪いことには、バッファ サイズを変更している最中に、データ バッファにアクセスするハードウェア割り込みなど、事故が発生する可能性がある。そうした理由で、DirectInput は、プロパティを変更する前に、アプリケーションに対してデバイスを解放するように要求する。デバイスを再取得すると、DirectInput はプロパティを確認して、デバイスからアプリケーションへの最適なデータ転送の方法を決定する。この処理は一度しか行われないので、データ取得の各メソッドを非常に高速にすることができる。

デバイスを喪失する最も一般的な原因は、アプリケーションがバックグラウンドに移行することである。したがって、アプリケーションがアクティブになったときには常に、デバイスを再取得することが必要になる。しかし、起動時の WM_ACTIVATE ハンドラに依存するには注意が必要である。最初の WM_ACTIVATE メッセージが到着するのは、おそらくウィンドウの初期化中で、DirectInput のセットアップ前である。起動時にデバイスを確実に取得するには、デバイスが初期化されたらすぐに IDirectInputDevice8::Acquire を呼び出すようにする。

特に標準のキーボードやマウス以外のデバイスの場合、プログラム ウィンドウがアクティブになったときにデバイスを取得しても、デバイスが解放されるすべてのケースに対応できるとは限らない。アプリケーションがデバイスを不意に解放する場合もあるので、デバイスからデータを取得しようとする前に、取得状態を確認する仕組みが必要である。Scrawl サンプル アプリケーションでは、Scrawl_OnMouseInput 関数でこの確認を行っている。この関数では、DIERR_INPUTLOST エラーが、マウスを再取得するメッセージのトリガになる(詳細については、「チュートリアル 2 : マウスの使い方」を参照すること)。

取得済みのデバイスを再取得しようとしても、害はまったくない。Acquire に対する冗長な呼び出しは無視され、デバイスは常時 Unacquire を 1 回呼び出すことで解放することができる。

Windows は、アプリケーションがマウスを排他モードで使用しているときは、マウスにアクセスしない。Windows にマウスを取得させたければ、マウスを解放しなければならない。Scrawl サンプルでは、右ボタンのクリックに反応するために、マウスを解放し、Windows カーソルを同じ点に表示し、ショートカット メニューを表示し、メニュー選択が行われるまで Windows が入力を処理するようにしている。


DirectInput デバイス データ

ここでは、Microsoft® DirectInput® デバイス データの取得に関する基本的な考え方をいくつか説明する。

  • バッファリング データと直接データ
  • タイム スタンプとシーケンス番号
  • ポーリングとイベント通知
  • 相対座標と絶対座標

出力データ、マウス、キーボードおよびジョイスティック入力データの特定事項については、以下のトピックで詳述する。

  • マウス データ
  • キーボード データ
  • ジョイスティック データ
  • データ出力

DirectInput では、デバイスから取得したデータを識別する 2 つの仕組みを提供する。従来の仕組みを使って、アプリケーションは、マウスの x 軸またはキーボードの F1 キーなどの特定のデバイス オブジェクトから入力されるデータを識別する。Microsoft DirectX® 8.0 以降の新しいシステムでは、DirectInput はアプリケーションが定義した値 (たとえば、移動やシューティングなど、特定のゲーム アクションの識別子) を最も適切な使用可能デバイス オブジェクトに関連付ける。データが取得されると、アプリケーションは、データが入力された実際のデバイスまたはデバイス オブジェクトとの関連を持たない。そのデータの意義に対してのみ動作する。

このセクションで説明する情報の大部分は、両方のメカニズムに適用される。デバイス データの新しい識別法の詳細については、「アクション マッピング」を参照すること。


バッファリング データと直接データ

Microsoft® DirectInput® は、バッファリング データと直接データの 2 種類のデータを供給する。バッファリング データは、アプリケーションが取得するまで格納されているイベントのレコードである。直接データは、デバイスの現在の状態のスナップショットである。

直接データは、デバイスの現在の状態だけに関心のあるアプリケーションで使用することが考えられる。たとえば、ジョイスティックの現在位置と、1 つ以上のボタンの状態に反応するフライト コンバット シミュレーションなどである。バッファリング データは、状態よりもイベントを重要視する場合に選択するとよい。たとえば、マウスの動きやボタンのクリックに反応するアプリケーションなどである。両方のタイプのデータを使用することもできる。たとえば、ジョイスティック軸では直接データを取得して、ボタンではバッファリング データを取得する場合などである。

注 : アクション マッピングを使用する場合、バッッファリング データ パケットには入力に関するアプリケーション定義データが含まれるため、バッファリング データを取得する必要がある。バッファリング データ パケットでは状態ではなくイベントが報告されるため、このデータを取得するには絶対軸の位置を追跡しなければならない。

アプリケーションは、IDirectInputDevice8::GetDeviceState メソッドを呼び出して直接データを取得する。名前が表すとおり、このメソッドはデバイスの現在の状態を返す。たとえば、各ボタンがアップ状態かダウン状態か、などである。このメソッドは、現在の状態と以前の状態を比較して得られる暗黙の情報を除いて、最後の呼び出し以降にデバイスに起きたイベントに関するデータは、まったく提供しない。たとえば、前回の GetDeviceState への呼び出し以降にユーザーがボタンを押して離した場合、今回の GetDeviceState への呼び出しではそれらの入力情報はアプリケーションには伝えられない。他方、ボタンを押したままにしていると、GetDeviceState は、ユーザーがボタンを離すまで「ボタン ダウン」を報告し続ける。

このデバイス状態の報告は、WM_LBUTTONDOWN のような一度限りのメッセージによる Microsoft Windows® のイベント報告とは異なる。むしろ、Microsoft Win32® の GetKeyboardState 関数の報告に類似している。GetDeviceState を使用してデバイスをポーリングする場合には、ボタン クリック、ダブルクリック、または単一のキー ストロークの区別をプログラムで判断しなければならず、また、アプリケーションがボタン ダウン状態またはキー ダウン状態に対し、不適切なタイミングで応答し続けることのないように適切に処理しなければならない。

バッファリング データの場合、イベントは、プログラムが処理を開始できる状態になるまで格納されている。ボタンやキーが押されたり、軸が移動されたりするたびに、そのイベントに対する情報がバッファ中の DIDEVICEOBJECTDATA 構造体に置かれる。バッファがオーバーフローすると、新しいデータは失われる。アプリケーションがバッファを読み出すには、IDirectInputDevice8::GetDeviceData を呼び出す。一度に任意の数の項目を読み出すことができる。

項目を読み出すと、通常は、バッファからその項目が消去されるが、消去無しピーキングも選択できる。

バッファリング データを取得するには、まず IDirectInputDevice8::SetProperty または IDirectInputDevice8::SetActionMap メソッドでバッファ サイズを設定する必要がある (「デバイス プロパティ」を参照すること)。バッファ サイズの設定は、デバイスを最初に取得する前に行う。効率上の理由から、デフォルトのバッファ サイズはゼロである。この値を変更しない限り、バッファリング データを取得することはできない。バッファ サイズはバイト単位ではなく、デバイスのタイプに対応したデータの項目単位でカウントされる。

GetDeviceData メソッドを呼び出した後は、pdwInOut パラメータ値をチェックする必要がある。バッファから取得される項目数は、この変数に返される。

注 : アナログ ジョイスティックなど、割り込みを生成しないデバイスの場合、IDirectInputDevice8::Poll メソッドが呼び出されるまで、DirectInput はいかなるデータも取得しない。詳細については、「ポーリングとイベント通知」を参照すること。

バッファリング データを取得する例については、「IDirectInputDevice8::GetDeviceData」を参照すること。

参照

  • タイム スタンプとシーケンス番号
  • マウス データ
  • キーボード データ
  • ジョイスティック データ


タイム スタンプとシーケンス番号

バッファリングされている Microsoft® DirectInput® 入力データの場合 (「バッファリング データと直接データ」を参照)、各 DIDEVICEOBJECTDATA 構造体には、イベントのタイプとそれに関連するデバイス オブジェクトだけでなく、タイム スタンプとシーケンス番号も格納される。

dwTimeStamp メンバは、イベントが発生したときのシステム時間をミリ秒単位で格納する。これは、Microsoft Win32® GetTickCount 関数によって返される値と同じか、より精度が高い値である。

dwSequence メンバは、DirectInput が割り当てたシーケンス番号を格納する。DirectInput システムは、単一のシーケンス カウンタを保持している。このカウンタは、任意のデバイスで、バッファリングされるイベントが発生するたびに随時増加する。(マウスの斜めの動きなど、同一デバイス上で同時に発生したイベントは、1 回だけカウントが増加する)。この番号を使って、異なるデバイスから発生するイベントを比較し、どちらが先かを確認することができる。DirectInput シーケンス番号の比較に使用される DISEQUENCE_COMPARE マクロは、循環性を考慮している。

注 イベントは、常に、発生時間順にバッファに入れられるので、単一デバイスからのイベントを単に順序付けするだけなら、シーケンス番号をチェックする必要はない。


ポーリングとイベント通知

入力データが発生しているかどうかを確認するには、ポーリングとイベント通知という 2 つの方法がある。

デバイスのポーリングとは、デバイス オブジェクトの現在の状態を定期的に取得すること、またはイベント バッファの内容をチェックすることを意味する。ポーリングが使用されるのは通常、決してアイドルになることがなく、常にゲームの世界を更新、レンダリングするリアルタイム ゲームである。

ポーリング

C++ アプリケーションでのポーリングは通常、メッセージ ループ内で行われる。

ジョイスティックやほかのゲーム デバイス、またはこれらのデバイス上のオブジェクトのうちいくつかは、IDirectInputDevice8::Poll メソッドを呼び出すまで、ハードウェア割り込みを生成せず、いかなるデータも返さず、いかなるイベントも送信しない (このようなバックグラウンドでのポーリングを、ここで説明するアプリケーション ポーリングと混同しないこと。Poll メソッドは、データを一切取得しないが、データを使用可能にすることがある)。

データを取得しようとするたびに Poll メソッドを呼び出す必要があるかどうかを調べるには、まずデバイスのデータ形式を設定し、IDirectInputDevice8::GetCapabilities メソッドを呼び出して、DIDEVCAPS 構造体の DIDC_POLLEDDATAFORMAT フラグをチェックする。

DIDC_POLLEDDATAFORMAT フラグと DIDC_POLLEDDEVICE フラグを混同しないこと。後者は、データ形式に関係なく、デバイス上のオブジェクトのいずれかがポーリングを必要としているときに設定される。次に、IDirectInputDevice8::GetObjectInfo メソッドを呼び出し、DIDEVICEOBJECTINSTANCE 構造体にある DIDOI_POLLED フラグをチェックすると、ポーリングを必要としているのが特定のオブジェクトであるかどうかを見分けることができる。

DIDC_POLLEDDEVICE フラグはデバイスの最悪の状態を表すのであって、デバイスの実際の状態を表すわけではない。たとえば、ソフトウェア解像度調節付きの HID (Human Interface Device) マウスでは、解像度情報を読み取るためにポーリングを要求するので、DIDC_POLLEDDEVICE フラグが設定される。デバイスの標準ボタンと軸データだけを取得したい場合は、このような条件のもとでデバイスをポーリングする必要はない。ただし、任意の入力デバイスに対して IDirectInputDevice8::Poll メソッドを読み出しても害はない。この呼び出しが不要なときは、何のエフェクトも持たずにすぐに終了する。

イベント通知

イベント通知は、Scrawl サンプルのように、何もしないで入力を待つようなアプリケーションに適している。

イベント通知を使用するには、Microsoft® Win32® CreateEvent 関数でスレッド同期オブジェクトをセットアップした後、イベントのハンドルを IDirectInputDevice8::SetEventNotification メソッドに渡すことによって、このイベントとデバイスを関係付ける。これで、デバイスの状態が変化するたびに、Microsoft DirectInput® によってイベントが通知される。アプリケーションは、WaitForSingleObject などの Win32 関数を使用して、イベントの通知を受け取った後、入力バッファをチェックして何のイベントかを確認し、応答することができる。コード例については、Scrawl サンプルと 「IDirectInputDevice8::SetEventNotification」を参照すること。


相対座標と絶対座標

軸座標は、相対値として返される場合もある。すなわち、アプリケーションが前回デバイスの状態を取得してからの変化量、バッファリング入力の場合は、直前の項目がバッファに入れられてからの変化量である。

絶対軸座標とは、デバイスの取得以来、システムが返したすべての相対座標の連続合計のことである。すなわち、ある固定点に対する軸の位置を示す。

デフォルトでは、マウスの軸は相対座標であり、ジョイスティック軸は絶対座標で報告される。プロパティを設定することで、デバイスの座標システムを変更できる。詳細については、「デバイス プロパティ」を参照すること。


マウス データ

データを取得するようにマウス デバイスを設定するには、パラメータとして c_dfDIMouse または c_dfDIMouse2 のグローバル変数を指定して、IDirectInputDevice8::SetDataFormat メソッドを呼び出す。5 つ以上のマウス ボタンをサポートする場合は、c_dfDIMouse2 を使用する。

フルスクリーン アプリケーションの性能を最大限発揮するには、協調レベルに DISCL_EXCLUSIVE | DISCL_FOREGROUND を設定する。排他を設定すると、Microsoft® Windows® カーソルが消失することに注意すること。DISCL_FOREGROUND を設定すると、デバッグ ウィンドウに切り替えたときに、アプリケーションがマウスへのアクセス権を失う。DISCL_BACKGROUND に変更すると、アプリケーションのパフォーマンスは犠牲になるが、アプリケーションのデバッグをより容易に行うことができるようになる。

以下のトピックでは、マウスの直接データとバッファリング データの取得と解釈について詳細に説明する。

  • マウスの直接データ
  • マウスのバッファリング データ
  • マウス軸データの解釈
  • 消失したマウス入力の確認

参照

デバイス データ形式、協調レベル


マウスの直接データ

マウスの現在の状態を取得するには、DIMOUSESTATE 構造体か DIMOUSESTATE2 構造体へのポインタを指定して、IDirectInputDevice8::GetDeviceState を呼び出す。どちらの構造体を使用するかは、データ形式に依存する。この構造体に返されるマウス状態には、軸データおよび各ボタンの状態が含まれる。

構造体の最初の 3 つのメンバが軸座標を保持する (「マウス軸データの解釈」を参照すること)。

rgbButtons メンバは、バイト配列である。4 つまたは 8 つの各ボタンに 1 要素が対応する。従来型のマウスの場合、一般的に、配列の 1 番目の要素が左ボタン、2 番目が右ボタン、3 番目が中央ボタンである。上位ビットは、ボタンがダウン状態の場合にセットされ、ボタンがアップ状態または存在しない場合に消去される。

参照

バッファリング データと直接データ


マウスのバッファリング データ

マウスからバッファリング データを取得するには、バッファ サイズを設定しなければならない (「デバイス プロパティ」を参照すること)。バッファのデフォルト サイズはゼロなので、この手順は不可欠である。

また、DIDEVICEOBJECTDATA 構造体の配列も宣言する必要がある。この配列は、最高でバッファ サイズと同数の要素を持つことができる。1 度の呼び出しでバッファの内容全体を取得する必要はない。配列内の 1 要素だけを保持して、バッファが空になるまで 1 つずつイベントを取得することができる。

デバイスの取得後は、IDirectInputDevice8::GetDeviceData メソッドを使っていつでもバッファ内のイベントを調べたりフラッシュしたりすることができる (「バッファリング データと直接データ」を参照すること)。返された DIDEVICEOBJECTDATA 配列中の各要素は、マウスに対する単一オブジェクトの状態の変化を表す。たとえば、ユーザーがボタン 0 を押してマウスを斜めに移動すると、GetDeviceData に渡された配列 (3 つ以上の要素を持っている場合、pdwInOut は 3 以上) は、3 つの要素が埋められる。これらの要素はそれぞれ、ボタン 0 の押下、x 軸の変化、および y 軸の変化を表す。pdwInOut は 3 に設定される。

配列中の要素がどのオブジェクトを指すかは、DIDEVICEOBJECTDATA 構造体の dwOfs メンバを、以下のマクロによって返される値と比較することで確認できる。

  • DIMOFS_BUTTON0 ～ DIMOFS_BUTTON7
  • DIMOFS_X
  • DIMOFS_Y
  • DIMOFS_Z

これらの各値は、DIMOUSESTATE 構造体または DIMOUSESTATE2 構造体中のオブジェクトに対するデータのオフセットから導かれる。たとえば、DIMOFS_BUTTON0 が返す値は、DIMOUSESTATE 構造体中の rgbButtons[0] オフセットと等しい。DIMOFS_BUTTON4 から DIMOFS_BUTTON7 までは、DIMOUSESTATE2 に対してだけサポートされている。マクロを使用して単純な比較を行い、どのデバイス オブジェクトがバッファの項目に関連しているかを決定することができる。たとえば、以下のとおりである。

DIDEVICEOBJECTDATA  *lpdidod;
int                 n;
.
.
.
/* MouseBuffer は、DIDEVICEOBJECTDATA 構造体の配列であり、
GetDeviceData への呼び出しによって設定される。
n は、配列中で埋め込まれたすべての要素を
調べるループで増加する。 */
lpdidod = &MouseBuffer[n];
if (( (int) lpdidod->dwOfs == DIMOFS_BUTTON0)
      && (lpdidod->dwData & 0x80))
{
 ;  // 左ボタン押下に応じて何らかの処理を行う。
}

デバイス オブジェクトの状態変化データは、DIDEVICEOBJECTDATA 構造体の dwData メンバに格納される。軸の場合には、座標値がこのメンバ中に返される。ボタン オブジェクトの場合は、dwData の下位バイトだけが有意である。上位ビットはボタンが押されたときに設定され、ボタンが離されたときに消去される。言い換えれば、(dwData & 0x80) がゼロでないとき、ボタンが押されていることになる。

アクション マッピングを使用している場合は、dwOfs の値を無視し、キー イベントに関連するアプリケーション定義データを uAppData メンバから取得する。

DIDEVICEOBJECTDATA 構造体のほかのメンバの詳細については、「タイム スタンプとシーケンス番号」を参照すること。


マウス軸データの解釈

マウスの x 軸および y 軸に対して返されるデータは、カーソルではなくマウス自身の動作を示す。測定単位は、マウスのハードウェアが返す値に基づくものであり、ピクセルやその他の画面測定形式とは無関係である。Microsoft® DirectInput® はマウス ドライバと直接通信するので、ユーザーがコントロール パネルで設定するマウスのスピードと加速値は、このデータに影響しない。

マウスから返される軸データは、相対でも絶対でもよい (「相対座標と絶対座標」を参照すること)。マウスは相対的なデバイスなので (ジョイスティックとは異なり、ホームポジションを持たない)、デフォルトでは、相対データが返される。

軸モードは、相対データまたは絶対データのどちらを返すかを指定するものであるが、デバイスを取得する前に変更できるプロパティである (「デバイス プロパティ」を参照すること)。軸モードを "絶対" に設定するには、rguidProp パラメータに DIPROP_AXISMODE 値を指定し、DIPROPDWORD 構造体の dwData メンバに DIPROPAXISMODE_ABS を指定して、IDirectInputDevice8::SetProperty を呼び出す。

マウスの軸モードが "相対" の場合、軸座標は、最後の値が返されて以降、軸にそってデバイスが移動した単位数を表す。負の値は、ｘ軸の場合、マウスが左方向に移動したこと、y 軸の場合、ユーザーから離れる方向にマウスが移動したこと、および z 軸 (ホイール) が手前に回転したことをそれぞれ示す。正の値はこれと反対方向の動きを示す。

軸モードが "絶対" の場合、軸座標は、単純に DirectInput が受信した相対動作のすべての累積合計となる。軸座標値は、デバイスの取得時には、特定の値に初期化されていないので、アプリケーションは、絶対値を未知の原点を基準にした相対値として扱う必要がある。デバイスを取得したときは、いつも現在の絶対位置を記録して、それを "仮想原点" として保存することができる。この仮想原点は、その後、デバイスから得られる絶対座標から減算することにより、マウスが取得時点から移動した相対距離を計算することができる。

軸座標に返されるデータは、デバイスの細分性プロパティによっても影響を受ける。マウスの x 軸と y 軸の場合、細分度は通常 1 であり、これは、値の最小変化が 1 であることを意味する。ホイールの場合、細分度が 1 より大きくなることもある。


消失したマウス入力の確認

協調レベルに DISCL_FOREGROUND を設定した状態で、フォーカスがほかのアプリケーションに切り替わる場合 (あるいは使用中のアプリケーションのほかのメニューに切り替わる場合でも)、Microsoft® Windows® がアプリケーションにマウスを強制的に解放させることがある。このため、IDirectInputDevice8::GetDeviceData または IDirectInputDevice8::GetDeviceState メソッドからの戻り値 DIERR_INPUTLOST をチェックして、必要に応じてマウスを再取得する必要がある (「デバイスの取得」を参照すること)。

注 : DIERR_NOTACQUIRED エラーを受け取った場合には、マウスの再取得を試みないようにする必要がある。そうしないと、無限ループに入るおそれがある。取得は失敗し、DIERR_NOTACQUIRED エラーを受け取るという繰り返しが永遠に続く。


キーボード データ

Microsoft® DirectInput® を使用するときは、キーボードはテキスト入力デバイスではなく、多数のボタンを備えたゲーム パッドであることを考慮すること。アプリケーションがテキスト入力を必要とするときは、DirectInput のメソッドを使ってはいけない。通常の Microsoft Windows® メッセージからデータを取得するのが最も簡単であり、文字反復、物理キーから仮想キーへの平行移動などの Windows サービスを利用することができるからである。これは、英語以外の言語を使用する場合には特に重要である。英語以外の言語ではキーの特別な解釈が必要となることがあるからである。

データを取得するようにキーボード デバイスを設定するには、パラメータに c_dfDIKeyboard グローバル変数を指定して、IDirectInputDevice8::SetDataFormat メソッドを呼び出す (「デバイス データ形式」を参照すること)。

以下のトピックでは、キーボード データの取得と解釈について詳細に説明する。

  • キーボードの直接データ
  • キーボードのバッファリング データ
  • キーボード データの解釈
  • 消失したキーボード入力の確認


キーボードの直接データ

キーボードの現在の状態を取得するには、戻り値データを保持する 256 バイトの配列へのポインタを指定して、IDirectInputDevice8::GetDeviceState メソッドを呼び出す。

GetDeviceState メソッドは、Microsoft® Win32® GetKeyboardState 関数と同様に動作する。GetDeviceState メソッドは、キーボードの現在の状態のスナップショットを返す。各キーは、256 バイトの配列内の 1 バイトによって表される。配列のアドレスは、lpvData パラメータとして渡されたものである。バイトの上位ビットが設定されていると、キーは、ダウン状態にある。配列は最も便利なように、Microsoft® DirectInput® キーボード デバイス定数によりインデックスが付けられている (「キーボード データの解釈」も参照すること)。

以下のコードは、Esc キーの押下に応じて関数を呼び出す例である。lpdiKeyboard は、取得された DirectInput デバイスとする。

BYTE  diKeys[256];
if (lpdiKeyboard->GetDeviceState(256, diKeys) == DI_OK)
{
  if (diKeys[DIK_ESCAPE] & 0x80) DoSomething();
}


キーボードのバッファリング データ

キーボードからバッファリング データを取得するには、バッファ サイズを設定しなければならない (「デバイス プロパティ」を参照すること)。この手順は、バッファのデフォルト サイズがゼロであるので不可欠である。

また、DIDEVICEOBJECTDATA 構造体の配列も宣言する必要がある。この配列は、最高でバッファ サイズと同数の要素を持つことができる。1 度の呼び出しでバッファの内容全体を取得する必要はない。配列内の 1 要素だけを保持して、バッファが空になるまで 1 つずつイベントを取得することができる。

キーボード デバイスの取得後は、IDirectInputDevice8::GetDeviceData メソッドを使っていつでもバッファを調べたりフラッシュしたりすることができる (「バッファリング データと直接データ」を参照すること)。

DIDEVICEOBJECTDATA 配列の各要素は、単一キーの状態変化、すなわち、押下または解放を表す。Microsoft® DirectInput® は、キーボードから直接データを取得するために、コントロール パネルの文字反復の設定はすべて無視する。すなわち、キーストロークは、キーが押下されている時間の長短に関係なく、1 度しかカウントされないということになる。

配列中の要素がどのキーを指すかは、DirectInput のキーボード デバイス定数と、DIDEVICEOBJECTDATA 構造体の dwOfs メンバを比較することにより確認できる (「キーボード データの解釈」も参照すること)。

アクション マッピングを使用している場合は、dwOfs の値を無視し、キー イベントに関連するアプリケーション定義データを uAppData メンバから取得する。

キーの状態変化データは、DIDEVICEOBJECTDATA 構造体の dwData メンバに格納されている。dwData の下位バイトだけが有意である。上位ビットはキーが押されたときに設定され、キーが離されたときに消去される。言い換えれば、(dwData & 0x80) がゼロでないとき、キーが押されていることになる。


キーボード データの解釈

ここでは、IDirectInputDevice8::GetDeviceState メソッドおよび IDirectInputDevice8::GetDeviceData メソッドが報告するデータのキーの識別について説明する。GetDeviceData からのデータの解釈についての詳細は、「タイム スタンプとシーケンス番号」を参照すること。

重要な点として、Microsoft® DirectInput® アプリケーションは、Microsoft Windows® とは異なる方法でキーボードを読み取る。DirectInput アプリケーションでは、キーボード データは仮想キーを指すのではなく、実際の物理的なキー、つまり、スキャン コードを指す。たとえば、DIK_ENTER はメイン キーボードの Enter キーを指すが、テンキーの Enter キーは指していない。

また、キーボードの違いにより、DirectInput アプリケーションがキーボード データを解釈する方法を変えることができる。たとえば、DirectInput は、拡張キーボード上の各キーに対する定数と共に、国際キーボード上にある追加キーも定義する。NEC キーボードは、PC 拡張キーボードとは異なるスキャン コードをサポートしているので、DirectInput は、可能な限り NEC スキャン コードを PC 拡張スキャン コードに変換する。

これら以外でキーボードに関して考慮すべき事項は、以下のとおりである。

  • また、すべての PC 拡張キーボードに、新しい Windows キー (DIK_LWIN、DIK_RWIN、DIK_APPS) があるわけではない。Windows キーが物理的に使用可能かどうかを決定する方法はない。
  • ラップトップなどの小型コンピュータは、フルセットのキーを実装していない。代わりに、一部のキー (普通はテンキー) をほかのキーと多重化し、補助モードキーによって選択するようにして、個別のスキャン コードをつくらないようにしている。
  • キーボード サブタイプが PC XT または PC AT キーボードを示している場合、DIK_F11、DIK_F12、およびすべての拡張キー (0x7F より大きい DIK_* 値を持つキー) は利用できない。さらに、PC XT キーボードには DIK_SYSRQ がない。
  • 日本語キーボード、特に NEC PC-98 キーボードは、US キーボードとは相当に異なるキー セットを含んでいる。詳細については、「DirectInput と日本語キーボード」を参照すること。


消失したキーボード入力の確認

協調レベルを DISCL_FOREGROUND に設定した状態で、フォーカスがほかのアプリケーションに切り替わる場合、Microsoft® Windows® がアプリケーションにキーボードを強制的に解放させることがある。このため、IDirectInputDevice8::GetDeviceData メソッドまたは IDirectInputDevice8::GetDeviceState メソッドからの DIERR_INPUTLOST 戻り値をチェックして、必要に応じてキーボードを再取得する必要がある (「デバイスの取得」を参照すること)。

注 : DIERR_NOTACQUIRED エラーを受け取った場合には、キーボードの再取得を試みないようにする必要がある。そうしないと、無限ループに入るおそれがある。取得は失敗し、DIERR_NOTACQUIRED エラーを受け取るという繰り返しが永遠に続く。


ジョイスティック データ

データを取得するようにジョイスティック デバイスを設定するには、パラメータに c_dfDIJoystick または c_dfDIJoystick2 グローバル変数を指定して、IDirectInputDevice8::SetDataFormat メソッドを呼び出す (「デバイス データ形式」を参照すること)。

一部のデバイス ドライバは、明示的に要求されるまで Microsoft® DirectInput® に状態の変化を通知しないことがあるので、ジョイスティックのデータを取得する前には必ず IDirectInputDevice8::Poll メソッドを呼び出さなくてはならない。詳細については、「ポーリングとイベント通知」を参照すること。

以下のトピックでは、ジョイスティックおよびゲームパッドまたは操縦桿などの入力デバイスからのデータの取得と解釈について説明する。

  • ジョイスティックの直接データ
  • ジョイスティックのバッファリング データ
  • ジョイスティック軸データの解釈
  • 消失したジョイスティック入力の確認


ジョイスティックの直接データ

ジョイスティックの現在の状態を取得するには、DIJOYSTATE 構造体または DIJOYSTATE2 構造体へのポインタを指定して IDirectInputDevice8::GetDeviceState メソッドを呼び出す。どちらの構造体を使用するかは、c_dfDIJoystick か c_dfDIJoystick2 のどちらでデータ形式が設定されたのかによる (「デバイス データ形式」を参照すること)。構造体に返されるジョイスティックの状態には、軸座標、ボタンの状態、および視点コントローラの状態などがある。

DIJOYSTATE 構造体の最初の 7 つのメンバが軸座標を保持する。このうち最後のメンバ rglSlider は 2 つの値の配列である (ジョイスティック軸データの解釈を参照すること)。

rgdwPOV メンバには、4 つまでの視点コントローラの位置が含まれている。これらは、北から時計回り (または前方) の実角度の 100 倍で表される。中心位置 (中立点) は -1 として報告される。5 つの位置しか持たないコントローラの場合、位置は以下のどれか 1 つの値を取る。

  • -1
  • 0
  • 90 * DI_DEGREES
  • 180 * DI_DEGREES
  • 270 * DI_DEGREES

中心位置として、-1 ではなく 65,535 を報告するドライバもある。POV 標識が中心位置にあるかどうかは、次のようにチェックしなければならない。

BOOL POVCentered = (LOWORD(dwPOV) == 0xFFFF);

rgbButtons メンバは、バイト配列である。データ形式によって、32 個または 128 個の各ボタンに 1 要素が対応する。各ボタンの上位ビットは、ボタンがダウン状態で設定され、アップ状態または存在しない場合に消去される

DIJOYSTATE2 構造体には、軸の速度、加速度、フォース、およびトルクについての情報を提供する追加メンバがある。

参照

バッファリング データと直接データ


ジョイスティックのバッファリング データ

ジョイスティックからバッファリング データを取得するには、まず、バッファサイズを設定し (「デバイス プロパティ」を参照すること)、DIDEVICEOBJECTDATA 構造体の配列を宣言しなければならない。この配列は、最高でバッファ サイズと同数の要素を持つことができる。一度の呼び出しでバッファの内容全体を取得する必要はない。配列内の 1 要素だけを保持して、バッファが空になるまで 1 つずつイベントを取得することができる。

デバイスの取得後は、IDirectInputDevice8::GetDeviceData メソッドを使っていつでもバッファを調べたりフラッシュしたりすることができる (「バッファリング データと直接データ」を参照すること)。

DIDEVICEOBJECTDATA 配列中の各要素は、ジョイスティックに対する単一オブジェクトの状態の変化を表す。たとえば、ユーザーがボタン 0 を押してスティックを斜めに移動すると、GetDeviceData に渡された配列 (3 つ以上の要素を持っている場合、pdwInOut は 3 以上) は、3 つの要素が埋められる。これらの要素はそれぞれ、ボタン 0 の押下、x 軸の変化、および y 軸の変化を表す。pdwInOut は 3 に設定される。

配列中の要素がどのオブジェクトを指すかは、以下の値と、DIDEVICEOBJECTDATA 構造体の dwOfs メンバを比較することにより決定できる。

  • DIJOFS_X
  • DIJOFS_Y
  • DIJOFS_Z
  • DIJOFS_Rx
  • DIJOFS_Ry
  • DIJOFS_Rz
  • DIJOFS_BUTTON0 から DIJOFS_BUTTON31 または DIJOFS_BUTTON(n)
  • DIJOFS_POV(n)
  • DIJOFS_SLIDER(n)

これらのそれぞれの値は、DIJOYSTATE 構造体中のオブジェクトに対するデータのオフセットと等しい。たとえば、DIJOFS_BUTTON0 は、DIJOYSTATE 構造体中の rgbButtons[0] オフセットと等しい。単純な比較を行うことで、どのデバイス オブジェクトがバッファ上の項目に関連しているかを確認することができる。たとえば、以下のとおりである。

DIDEVICEOBJECTDATA  *lpdidod;
int                 n;
.
.
.
/* JoyBuffer は、DIDEVICEOBJECTDATA 構造体の配列であり、
GetDeviceData への呼び出しによって設定される。
n は、配列中で埋め込まれたすべての要素を
調べるループで増加する。 */
lpdidod = &JoyBuffer[n];
if (( (int) lpdidod->dwOfs == DIJOFS_BUTTON0)
   && (lpdidod->dwData & 0x80))
{
 ;  // 主ボタンの押下に応じて、何らかの処理を行う。
}

データ形式が c_dfDIJoystick2 で設定された場合は、DIJOYSTATE 内に存在するすべてのデバイス オブジェクトに事前定義されたオフセットを使用することができる。ただし、DIJOYSTATE2 の追加メンバに表現されるデバイス オブジェクトには、独自のオフセットを設定する必要がある。

アクション マッピングを使用している場合は、dwOfs の値を無視し、キー イベントに関連するアプリケーション定義データを uAppData メンバから取得する。

デバイス オブジェクトの状態変化データは、DIDEVICEOBJECTDATA 構造体の dwData メンバに格納される。軸の場合には、座標値がこのメンバ中に返される。ボタン オブジェクトの場合は、dwData の下位バイトだけが有意である。上位ビットはボタンが押されたときに設定され、ボタンが離されたときに消去される。

ほかのメンバについては、「タイム スタンプとシーケンス番号」を参照すること。


ジョイスティック軸データの解釈

ジョイスティックの軸値は、マウスの軸値と同様である。スティックを右に動かすと x 軸の戻り値が増し、スティックを手前に引き倒すと y 軸の値が増す。

ジョイスティック軸のデータは、軸の範囲プロパティにより任意の単位に決定される。たとえば、ジョイスティックの x 軸の範囲が 0 から 10,000 までの場合には、単位はジョイスティックの左右の移動の 10,000 分の 1 となり、中心位置は 5,000 となる。軸によっては、細分度プロパティが 1 より大きい場合もあり、その場合には値は丸められる。たとえば、細分度が 10 の場合には、値は 0、10、20 などのように報告される。

軸データは、無効ゾーンという、動作が無視される中心位置の周辺領域によっても影響を受ける。無効ゾーンは、ジョイスティックの少なくとも一方の軸に対する真の中心位置からの小さなずれに対する許容範囲となる。無効ゾーン内の軸の値は、真の中心として報告される。

軸の飽和プロパティとは、範囲の最大値および最小値の許容ゾーンのことである。このゾーン内の軸値は、最小値または最大値として報告される。飽和プロパティの目的は、たとえば、ジョイスティックの頂部の左位置と底部の左位置で報告される最小 x 軸間のわずかな差違を許容することにある。

次の図は、無効ゾーンと飽和ゾーンのエフェクトを示したものである。垂直軸は、軸の戻り値を表す。ここで、min と max は報告された範囲の下限と上限であり、ctr は報告された中心である。水平軸は、ジョイスティックの物理的な位置を示す。ここで、pmin と pmax は、物理的な範囲の限界、pctr は軸の中立点、dmin と dmax は無効ゾーンの限界値、そして smin と smax は上下の飽和ゾーンの境界である。下位飽和ゾーンは pmin と smin の間に存在し、上位飽和ゾーンは smax と pmax の間に存在し、無効ゾーンは dmin と dmax の間に存在する。

ジョイスティック プロパティの詳細については、以下を参照すること。

  • IDirectInputDevice8::GetProperty
  • IDirectInputDevice8::SetProperty
  • DIPROPRANGE
  • DIACTIONFORMAT

ジョイスティックから返される軸座標は、相対でも絶対でもよい (「相対座標と絶対座標」を参照すること)。ジョイスティックは絶対デバイスなので (マウスとは異なり、軸にそって無限には移動できない)、デフォルトでは絶対データが返される。ジョイスティックの軸モードが "相対" に設定されている場合には、軸座標は、最後の値が返されてから以降の軸にそった移動の単位数を表す。

軸モードは、相対データまたは絶対データのどちらを返すかを指定するものであるが、デバイスを取得する前に変更できるプロパティである (「デバイス プロパティ」を参照すること)。軸モードを "相対" に設定するには、rguidProp パラメータに DIPROP_AXISMODE 値を指定し、DIPROPDWORD 構造体の dwData メンバに DIPROPAXISMODE_REL を指定して、IDirectInputDevice8::SetProperty メソッドを呼び出す。


CPOINT の使い方

CPOINT 構造体を使って、デバイス軸の応答カーブのセグメントをキャリブレーションする。DIPROPCPOINTS 構造体を介して、最高 8 つの CPOINT を設定できる。各 CPOINT 構造体には、ジョイスティックの軸上の位置を示す未処理のデータと論理値が格納されている。アプリケーションが未処理のデータを受け取ると、論理値を使って、実際に使用される戻り値を計算する。指定された CPOINT 未処理データの値の範囲内にある未処理値は、CPOINT と値のいずれかの端とを結ぶ線に基づいて、論理値に補間される。

次に示すのは、ジョイスティックの X 軸の応答カーブに 5 つの CPOINT を適用した例である。DIPROPCPOINTS 構造体の適用前は、この例の軸に対する応答グラフは、飽和とデッド ゾーンを含めて以下のようになる。

DIPROPCPOINTS 構造体は、物理的範囲を -500 ～ 500 とし、次のように初期化される。

DIPROPCPOINTS dipcp;

dipcp.diph.dwSize = sizeof(DIPROPCPOINTS);
dipcp.diph.dwHeaderSize = sizeof(DIPROPHEADER);
dipcp.diph.dwObj = GUID_XAxis;
dipcp.diph.dwHow = DIPH_BYID;
dipcp.dwCPointsNum = 5;
dipcp.cp[0].lP = -500
dipcp.cp[0].dwLog = 0
dipcp.cp[1].lP = -300
dipcp.cp[1].dwLog = 1000
dipcp.cp[2].lP = -100
dipcp.cp[2].dwLog = 5000
dipcp.cp[3].lP = 200
dipcp.cp[3].dwLog = 9000
dipcp.cp[4].lP = 500
dipcp.cp[4].dwLog = 10000

CPOINT 構造体の dwLog メンバの値は合計に対するパーセンテージ (全範囲内での個々の目盛りの数) として 10000 を乗算して表現されるため、実際の戻り値の最大値を知る必要はないことに注意する。たとえばこの例は、ジョイスティックの範囲を -300 ポイントとして、最大値の 10% が返されるカーブが設定されている。0.10 * 10000 = 1000 となり、この値は dwLog メンバに与えられ、対応する lP メンバには -300 が割り当てられる。

この DIPROPCPOINTS 構造体を IDirectInputDevice8::SetProperty で適用した後、カーブは次のように応答する。


消失したジョイスティック入力の確認

ジョイスティックをフォアグラウンドモードで使用する (「協調レベル」を参照すること) 場合には、フォーカスが他のアプリケーションに切り替わるときに、デバイスを喪失することがある。

IDirectInputDevice8::GetDeviceData メソッドまたは IDirectInputDevice8::GetDeviceState メソッドからの DIERR_INPUTLOST 戻り値をチェックし、必要に応じてジョイスティックを再取得することができる (「デバイスの取得」を参照すること)。

注 : DIERR_NOTACQUIRED エラーを受け取った場合には、ジョイスティックの再取得を試みないようにする必要がある。そうしないと、無限ループに入るおそれがある。取得は失敗し、DIERR_NOTACQUIRED エラーを受け取るという繰り返しが永遠に続く。

キーボードやマウスとは異なり、Microsoft® Windows® システムはジョイスティックを使用しないので、アプリケーションがバックグラウンドに移行する場合を除き、ジョイスティックへのアクセス権が失われることはない。したがって、どちらのメソッドでも、WM_ACTIVATE メッセージに応えてデバイスを再取得できる。


データ出力

ヒューマン インターフェイス デバイスは、入力の生成と同様に出力を認知することができる。IDirectInputDevice8::SendDeviceData メソッドは、データのパケットをそれらのデバイスに送る。

SendDeviceData は、反対に IDirectInputDevice8::GetDeviceData として表示することができる。SendDeviceData メソッドと同様、GetDeviceData メソッドは、データの基本単位として DIDEVICEOBJECTDATA 構造体を使用する。この場合、dwOfs メンバに含まれるのは、デバイスのデータ形式のオフセットではなく、データに関連付けられたデバイス オブジェクトのインスタンス ID である(オフセット識別子は、選択されたデータ形式での入力を提供するデバイス オブジェクトのためだけに存在するので、出力しか認めないオブジェクトは、オフセットを持つことすらない)。dwData メンバには、そのオブジェクトに適したデータが含まれる。dwTimeStamp および dwSequence メンバは使用しない。これらのメンバは、ゼロに設定しなければならない。

デバイスにデータを送るには、最初に DIDEVICEOBJECTDATA 構造体の配列を設定し、要求された数の要素をデータで埋めてから、使用されるアドレスと要素数を SendDeviceData に渡す。異なるデバイス オブジェクトのデータは、デバイスに送られる単一パケットに結合される。

データ パケットの形式は、パケット内の使用されないフィールドの処理方法と同じで、デバイスによって異なる。デバイスによっては、フィールドをオプションとして扱う。つまり、データが提供されない場合、オブジェクトの状態は前と同じである。一般的には、特にデータがフィールドに提供されない場合であっても、すべてのフィールドは重要である。たとえば、単一のキーボード LED にデータを送ると、ほかの 2 つの LED のデータはゼロで、それらの LED はオフであると仮定される。ただし、DISDD_CONTINUE フラグを使用してこの動作を無効にすることができる。この場合は、ほかの 2 つの LED のデータは、最後に送信した値となる。

デバイス オブジェクトの型の識別子は、HID 使用ページと使用コードを IDirectInputDevice8::GetObjectInfo に渡した後で DIDEVICEOBJECTINSTANCE 構造体 の dwType メンバから取得する。たとえば Scroll Lock LED の型識別子は、以下のコードを使って取得する。このコードで、pdev はキーボードを表す IDirectInputDevice8 インターフェイス ポインタである。

DIDEVICEOBJECTINSTANCE didoi;
DWORD NumLockID;

HRESULT hr = pdev->GetObjectInfo(&didoi,
        DIMAKEUSAGEDWORD(0x07,0x53), DIPH_BYUSAGE);
NumLockID = didoi.dwType;

次の例では、コードが繰り返し実行される場合、キーボード上の LED は繰り返し点滅する。LED の状態は、データ バイトの上位ビットにより決定されるものとする。DWORD の NumLockID、CapsLockID、および ScrollLockID は、すべてこの方法で取得する。

#define ARRAYSIZE 4
void FlashLEDs(void)
    {
    static int         rgiBits[] = { 1, 2, 4, 2 };
    static int         iLooper = 0;
    DWORD              cdod = 3;                  // 項目数。
    DIDEVICEOBJECTDATA rgdod[ARRAYSIZE-1];
    HRESULT            hres;

    // dwTimeStamp および dwSequence を消去する必要がある。
    ZeroMemory(rgdod, sizeof(rgdod));

    rgdod[0].dwOfs = NumLockID;
    rgdod[1].dwOfs = CapsLockID;
    rgdod[2].dwOfs = ScrollLockID;

    rgdod[0].dwData = (rgiBits[iLooper] & 1) ? 0x80 : 0;
                                           // NumLock ライトのオン/オフ
    rgdod[1].dwData = (rgiBits[iLooper] & 2) ? 0x80 : 0;
                                           // CapsLock ライトのオン/オフ
    rgdod[2].dwData = (rgiBits[iLooper] & 4) ? 0x80 : 0;
                                           // ScrollLock ライトのオン/オフ

    iLooper = (iLooper + 1) % ARRAYSIZE; // 0 から 3 までループする。

    hres = pdev->SendDeviceData(sizeof(DIDEVICEOBJECTDATA),
            rgdod, &cdod, 0);
    }


アクション マッピング

従来、アプリケーションは特定のボタンや軸に対して独自のイベント マッピングを行っていた。たとえばカーレーシング ゲームの場合、ユーザーのジョイスティックやマウスの x 軸が車の運転用コントロールに最適であると想定される。新規デバイスや特殊デバイスを組み込む唯一の方法は、ユーザーが運転用に使用する回転軸などその他の軸を指定できるように、構成オプションを提供することであった。さらに、アプリケーションは、インストールされたどのデバイスがゲームに最適であるかを知る手段はなかったので、ユーザーは通常、メニューからデバイスを選択したり、適切なデバイスだけが接続されていることを確認したりしなければならなかった。

アクション マッピングを使うと、デバイスとデバイス オブジェクトの最適な使用法に関してさまざまなことを想定する必要はなくなる。その代わりに、アプリケーションが、可能な限りアクションと仮想コントロールをバインドする。アプリケーションは、x 軸からデータを取得して車を左右に動かすのではなく、DIAXIS_DRIVINGR_STEER という仮想コントロールからデータを取得することになる。Microsoft® DirectInput® は、仮想コントロールを物理コントロール、つまりデバイス オブジェクトに割り当てる。割り当ての際には、アプリケーションのジャンル、ユーザー設定、デバイス メーカーからの情報、およびユーザーのデバイス構成が考慮される。

また、アクション マッピングを使うと、すべてのデバイスのデータが、特定のデバイスに依存しない形式で返されることにより、入力ループが簡素化される。単一のアクションを複数のデバイスにマップでき、そのアクションに対し、どのデバイスを読み取り中かにかかわらず、入力ループが同一の方法で応答することができる。

以下のトピックでは、アクション マッピングの実装に必要な手順の詳細を説明する。

  • アクション マップの準備
  • 一致するデバイスの検索
  • アクション マップの構成
  • デバイスのユーザー構成
  • アクション データの取得
  • 開発中のファイルの管理


アクション マップの準備

アクション マップとは、アプリケーションのアクションと、仮想コントロールやデバイス オブジェクトへのマッピングに関する情報を格納している DIACTIONFORMAT 構造体である。この構造体がアプリケーションと Microsoft® DirectInput® の間でやりとりされ、最終的なマッピングが確立される。ここでは、マップの初期化方法について説明する。

1. アプリケーション アクションの定義

DirectInput アクション マッピングを実装する際の第 1 ステップは、アプリケーション内のどの入力ドリブン アクションをデバイス オブジェクトにマップする必要があるかを決定することである。軸やボタンによって実行できるアクションの場合、軸とボタンの両方の入力タイプに独立したアクションを定義しなければならない。デバイスが適切な軸を持たない場合に備えて、重要な機能にはすべてボタン アクションを定義することが推奨される。

次のアクション値の列挙例は、カーレーシング ゲームにより定義されるものとする。軸アクションは "eA" で始まり、ボタン アクションは "eB" で始まる。

enum eGameActions
{
    eA_STEER,       // ハンドル
    eB_STEER_LEFT,  // ハンドルを左に切る
    eB_STEER_RIGHT, // ハンドルを右に切る
    eA_ACCELERATE,  // 速度変更
    eB_ACCELERATE,  // 加速
    eB_DECELERATE,  // 減速
    eA_BRAKE,       // ブレーキ
    eB_BRAKE,       // ブレーキ
    eB_UPSHIFT,     // 高速ギアにシフト
    eB_DOWNSHIFT,   // 低速ギアにシフト
    eB_CYCLEVIEW,   // 次のビューに転換
    eB_COURSEVIEW,  // コース ビューの切り替え
    eB_DRIVERVIEW,  // 運転席ビュー
    eB_BRAKEBIAS,   // ブレーキ バイアス
    eA_VOLUME,      // 音量
    eB_MUTE         // サウンドの切り替え
};

#define NUM_MY_ACTIONS 16

この例では、アクションは列挙値として定義されている。ただし、関数へのポインタなど、ほかの 32 ビット データ型をとることもできる。デバイス データを取得する場合、定義したアクション値はすべて取得されるので、その値を自由に処理できる。

2. ジャンルの定義

第 2 ステップは、アプリケーションの属するジャンルを決定することである。ジャンルにより、仮想コントロールのセットが定義される。適切なジャンルを選択することで、アプリケーション アクションに対して最適な仮想コントロールを取得できる。メーカーがデバイスにデフォルト マッピングを設定する場合、メーカーは DirectInput で定義されたジャンルのうち 1 つ以上をサポートしなければならない。ジャンル一覧については、「アクション マッピング定数」を参照すること。

この例のゲームの場合は、当然 DIVIRTUAL_DRIVING_RACE ジャンルを選択する。このジャンルには以下の仮想コントロールが含まれている。

優先順位 1 のコントロール

DIAXIS_DRIVINGR_STEER
DIAXIS_DRIVINGR_ACCELERATE
DIAXIS_DRIVINGR_BRAKE
DIBUTTON_DRIVINGR_SHIFTUP
DIBUTTON_DRIVINGR_SHIFTDOWN
DIBUTTON_DRIVINGR_VIEW
DIBUTTON_DRIVINGR_MENU

優先順位 2 のコントロール

DIAXIS_DRIVINGR_ACCEL_AND_BRAKE
DIHATSWITCH_DRIVINGR_GLANCE
DIBUTTON_DRIVINGR_ACCELERATE_LINK
DIBUTTON_DRIVINGR_AIDS
DIBUTTON_DRIVINGR_BOOST
DIBUTTON_DRIVINGR_BRAKE
DIBUTTON_DRIVINGR_DASHBOARD
DIBUTTON_DRIVINGR_DEVICE
DIBUTTON_DRIVINGR_GLANCE_LEFT_LINK
DIBUTTON_DRIVINGR_GLANCE_RIGHT_LINK
DIBUTTON_DRIVINGR_MAP
DIBUTTON_DRIVINGR_PAUSE
DIBUTTON_DRIVINGR_PIT
DIBUTTON_DRIVINGR_STEER_LEFT_LINK
DIBUTTON_DRIVINGR_STEER_RIGHT_LINK

優先順位 1 のコントロールと 優先順位 2 コントロールの間に機能上の差異はない。優先順位 1 のコントロールは、デバイス メーカーがデフォルト マッピングとしてサポートすることが望ましいコントロールである。ただし、どの仮想コントロールも、デバイスによりサポートされる保証はない。

3. コントロールやデバイス オブジェクトへのアクションの割り当て

アクション マップ作成の次のステップでは、それぞれのアプリケーション アクションに、該当ジャンルで定義された 1 つ以上の仮想コントロールを関連付ける。この処理を行うには、DIACTION 構造体の配列を宣言して初期化する。配列内の構造体はそれぞれ、アクション値、それに関連付けられた仮想コントロール、およびそのアクションを説明する登録名を指定する。その他のメンバはゼロとして残す。これらのメンバの値は後で DirectInput により指定される。

DIACTION 配列の要素を使って、アクションをキーボードの特定のキー、またはマウスの特定のボタン、あるいは Microsoft DirectPlay® 音声デバイスにマップすることもできる。そうすることで、仮想コントロールからの入力に限らずすべての入力で、簡略化された入力ループを利用できる。たとえば、アプリケーション定義アクション eB_UPSHIFT を DIBUTTON_DRIVINGR_SHIFTUP 仮想コントロールと、Page Up キーの両方にマップするとしよう。データを取得する場合、入力源がジョイスティック ボタンとキーボードのどちらであるかにかかわらず、eB_UPSHIFT を取得する。

以下の例は、カーレーシング ゲーム用のアクション マップを宣言している。

DIACTION rgActions[]=
{
// ジャンル定義の仮想軸。

  {eA_STEER,       DIAXIS_DRIVINGR_STEER,        0, "Steer",      },
  {eA_ACCELERATE,  DIAXIS_DRIVINGR_ACCELERATE,   0, "Accelerate", },
  {eA_BRAKE,       DIAXIS_DRIVINGR_BRAKE,        0, "Brake",      },

// ジャンル定義の仮想ボタン。

  {eB_UPSHIFT,     DIBUTTON_DRIVINGR_SHIFTUP,    0, "Upshift",    },
  {eB_DOWNSHIFT,   DIBUTTON_DRIVINGR_SHIFTDOWN,  0, "DownShift",  },
  {eB_CYCLEVIEW,   DIBUTTON_DRIVINGR_VIEW,       0, "Change View",},

// 任意のボタンや軸に割り当て可能な
// ジャンル未定義のアクション。

  {eA_VOLUME,      DIAXIS_ANY_1,                 0, "Volume",      },
  {eB_MUTE,        DIBUTTON_ANY(0),              0, "Toggle Sound",},

// 特定のキーに割り当てる必要がある
// ジャンル未定義のアクション。

  {eB_DRIVERVIEW,  DIKEYBOARD_1,                 0, "Driver View",},
  {eB_COURSEVIEW,  DIKEYBOARD_C,                 0, "Course View",},
  {eB_BRAKEBIAS,   DIKEYBOARD_B,                 0, "Brake Bias", },

// キーと仮想コントロールにマップされたアクション。

  {eB_UPSHIFT,     DIKEYBOARD_PRIOR,              0, "Upshift",    },
  {eB_DOWNSHIFT,   DIKEYBOARD_NEXT,               0, "Downshift",  },
  {eB_STEER_LEFT,  DIKEYBOARD_LEFT,               0, "Steer Left", },
  {eB_STEER_RIGHT, DIKEYBOARD_RIGHT,              0, "Steer Right",},
  {eB_ACCELERATE,  DIKEYBOARD_UP,                 0, "Accelerate", },
  {eB_DECELERATE,  DIKEYBOARD_DOWN,               0, "Decelerate", },
  {eB_BRAKE,       DIKEYBOARD_END,                0, "Brake",      },

// ボタンと仮想コントロールおよびキーにマップされたアクション。

  {eB_UPSHIFT,     DIMOUSE_BUTTON0,              0, "Upshift",   },
  {eB_DOWNSHIFT,   DIMOUSE_BUTTON1,              0, "Downshift", },
};

この例で、一部のアクションは、キーボード マッピング定数を使って実際のキーにマップされている。同様に、マウスのボタンと軸へのマッピングも、マウス マッピング定数を使って行うことができる。

DIACTION 配列は、ジャンル、アプリケーション、および軸データの適切なスケーリングに関する情報を格納する DIACTIONFORMAT 構造体の一部である。アクション マッピング プロセスの全体にわたり、この構造体の同じインスタンスを使用する。一部のメンバはすぐには使用されないが、次のステップ「一致するデバイスの検索」に移る前に、構造体全体に値を設定できる。


一致するデバイスの検索

アプリケーション アクションと、それらのアクションのマップ先である仮想コントロールやデバイス オブジェクトの定義が済んだら、次のステップでは、システム上のデバイスを列挙して、目的の仮想コントロールに最適なデバイスを検索する。

これを行うために、IDirectInput8::EnumDevicesBySemantics に DIACTIONFORMAT 構造体を渡す。このメソッドは、ほとんどの点で IDirectInput8::EnumDevices と同じように機能し、類似のコールバック関数を取る。

特定のコントロールに一致するようにユーザーが構成したデバイスは、常に最初に列挙される。たとえば、ユーザーがホイールをドライビング ゲームのプライマリ ステアリング デバイスとして構成している場合は、DIAXIS_DRIVINGR_STEER をサポートするデバイスが要求されるとホイールが最初に列挙される。DIAXIS_DRIVINGR_STEER をサポートするジョイスティックなどのほかのデバイスがあっても、ユーザーによって構成されていなければ、ホイールが優先される。それ以外の場合、利用可能なデバイスの列挙順は、要求されたコントロールに一致する度合いにより決まる。

列挙コールバックでは、各デバイスのデフォルト アクション マッピングの取得、不要なマッピングの変更、ユーザーがデバイスを再構成する機能の設定、およびアクション マップの適用を行うことができる。これらのステップについては、「アクション マップの構成」で説明する。DIEnumDevicesBySemanticsCallback に返されるフラグは、特定のデバイスが列挙された理由についての情報を提供する。これらのフラグは、デバイスが最近使用されたか、新しくインストールされたか、優先順位 1 または 優先順位 2 のコントロールのマッピングを受け付けるかどうかを示す。


アクション マップの構成

各デバイスが列挙されたら、そのデバイスへのポインタの取得、デフォルト アクション マップの取得、デフォルト マップへの変更、および最終マッピングの適用を行うことができる。

1. デバイスの取得

列挙コールバックの lpdid パラメータから、列挙された各デバイスの IDirectInputDevice8 インターフェイス ポインタを取得する。「DIEnumDevicesBySemanticsCallback」を参照すること。アプリケーションで使用できるようにデバイス インターフェイスを保存したい場合は、そのインターフェイス ポインタに対して AddRef を呼び出し、グローバル変数を割り当てる。

2. デフォルト アクション マップの取得

デバイスのデフォルト アクション マップを取得するには、IDirectInputDevice8::BuildActionMap を呼び出す。Microsoft® DirectInput® は、DIACTIONFORMAT 構造体に指定された仮想コントロールのリストを取り出し、これらのコントロールを物理デバイス オブジェクトにマップしようとする。結果は同じ構造体に返される。それぞれの DIACTION 要素の dwHow メンバを確認して、コントロールが正常にマップされたかどうかを調べる必要がある。正常ならば、ユーザーによる構成やデバイス メーカーによる構成など、オブジェクトの選択にどのような基準が使用されたかを突き止めることもできる。

3. アクション マップへの変更

この時点で、デフォルト マッピングを変更できる。ただし、変更は推奨されない。DIACTION 構造体の dwSemantic メンバを検証し、どのデバイス オブジェクトがアクションにマップされたかを確認したら、マップの値を変更できる。たとえば、DIJOFS_BUTTON9 にマップされているアクションを、トリガ ボタンにマップし直したい場合、アクション マップを適用する前に、この値を DIJOFS_BUTTON0 に変更する。

4. アクション マップの適用

DIACTIONFORMAT 構造体に含まれるデバイスのマッピングが適切であることを確認したら、IDirectInputDevice8::SetActionMap を呼び出す。それぞれの DIACTION 構造体の uAppData メンバに割り当てた値は、この時点で、dwSemantic メンバに指定されたコントロールにバインドされる。これは次に特定のデバイス オブジェクトにバインドされる。

5. 複数デバイスのマッピング

ステップ 1 から 4 までを、アプリケーションで使用するそれぞれのデバイスに対して実行する。アクションをジョイスティックとキーボードの両方にマップするとしよう。レーシング ゲームの例で、ゲームに eB_DRIVERVIEW として定義されたアクションは、DIACTION 配列の次の要素でキーボードのキーにマップされた。

{eB_DRIVERVIEW, DIKEYBOARD_1, "Driver View", },

この例では、キーボード以外のデバイスに対して BuildActionMap が呼び出されると、その要素の DIACTION 構造体の lHow メンバが DIAH_UNMAPPED に設定される。各デバイスが順に列挙されるのに従い、DIAH_UNMAPPED 以外の値が返されるまで、lHow メンバの検証を続ける。これは、現在マップされている対象のデバイスがキーボードであり、アクションが要求されたキーに正常にマップされたことを示す。

正常にマップされたアクションも、別のデバイスにマップできる。この例では、eB_UPSHIFT が次のように 2 つの DIACTION 構造体に設定される。

{eB_UPSHIFT, DIBUTTON_DRIVINGR_SHIFTUP, 0, "Upshift", },
...
{eB_UPSHIFT, DIKEYBOARD_PRIOR,          0, "Upshift", },

デバイスが列挙されるのにしたがい、eB_UPSHIFT アクションは 1 つ以上のジョイスティックやその他のゲーム コントローラの適切なボタンにマップされ、次にキーボードのキーに再びマップされる。

6. 構成の表示

ユーザーにデバイスへのアクションのマップ状況を示すには、DICD_DEFAULT フラグを IDirectInput8::ConfigureDevices に渡す。次の図に示すように、デバイスのマッピング図を含むプロパティ シートが、表示専用モードで表示される。イメージを表示するメカニズムの詳細については、「アクション マッピングの使い方」のチュートリアルを参照すること。

デバイス メーカーからデバイス イメージが提供されていない場合、マッピングは次の図のようにテキスト モードで表示される。

注 : Microsoft® Windows® キーは、アプリケーションの協調レベルで排他協調レベルを通して受動的に、または DISCL_NOWINKEY フラグを使って能動的に無効にする場合でも、デフォルトのアクション マッピング UI が表示されている間はアクティブになる。

プロパティ シートについての詳細情報は、「デバイスのユーザー構成」を参照すること。


デバイスのユーザー構成

Microsoft® DirectInput® には、アプリケーションからプロパティ シートを呼び出す機能がある。これにより、ユーザーはデバイスをそのアプリケーション用に構成し、現在の構成を見ることができる。デバイス メーカーの対応によっては、このプロパティ シートをさまざまなビューで表示できる。

ユーザー構成を有効にするには、目的のマッピングを記述した DIACTIONFORMAT 構造体へのポインタを含む DICONFIGUREDEVICESPARAMS 構造体を、DICD_EDIT フラグと共に IDirectInput8::ConfigureDevices メソッドに渡す。通常、この処理は、アプリケーションで使用されるすべてのデバイスに対して IDirectInputDevice8::BuildActionMap を呼び出した後で行う。

次の図は、編集モードの典型的なプロパティ シートを示している。

デバイス メーカーからデバイス イメージが提供されていない場合、マッピングは次の図のようにテキスト モードで表示される。

注 : Microsoft® Windows® キーは、アプリケーションの協調レベルで排他協調レベルを通して受動的に、または DISCL_NOWINKEY フラグを使って能動的に無効にする場合でも、デフォルトのアクション マッピング UI が表示されている間はアクティブになる。

デバイスのプロパティ ページには、各 DIACTION 構造体の lptszActionName メンバに指定された登録名のリストが表示される。デバイスに対して既に BuildActionMap を呼び出している場合、プロパティ ページでは、デバイスのイメージ上に、アクションがマップされたデバイス オブジェクトを指す線と、コールアウトとしてこれらの名前も表示される。

これにより、ユーザーはまずコントロールを選択し、次にメニューからアクションを選択して、ゲームのアクションを割り当て直すことができる。ユーザーがプロパティ シートを閉じると、メソッドが返り、渡した DIACTIONFORMAT 構造体に変更内容が格納される。その後、同じ構造体を IDirectInputDevice8::SetActionMap に渡すと、新しいマッピング設定を実装することができる。


アクション データの取得

アクションをマップしたデバイスからバッファ データを取得するには、マップされていないデバイスの場合と同様に、IDirectInputDevice8::GetDeviceData を呼び出す。ただし、DIDEVICEOBJECTDATA 構造体の dwOfs メンバを検証することでデバイス オブジェクトを識別するのではなく、uAppData メンバからオブジェクトに関連付けられたアクションを取得する。これは、DIACTION 構造体内のデバイスに渡したのと同じ値である。この値には、単純な識別子や、アクションの処理を目的とした関数へのポインタを使用できる。

アクションは複数のデバイスへの関連付けが可能であることに注意すること。両方のデバイスから別個にデータを取得する必要があるが、データをどこから取得するかにかかわらず、同じルーチンを使ってデータを処理できる。

次のサンプル コードは、ドライビング シミュレーションのゲーム ループの一部とする。ここでは、g_lpIdiDevices 配列内のすべてのデバイスからデータを取得する。この配列には g_nDevices 要素が格納されている。

for (int iDevice = 0x0; iDevice < g_nDevices; iDevice++)
{
    DIDEVICEOBJECTDATA didod;
    DWORD dwObjCount = 1;

    // データの有無をデバイスにポーリングする。
    g_lpDiDevices[iDevice]->Poll();

    // データを取得する。
    g_lpDiDevices[iDevice]->GetDeviceData( sizeof(didod),
                                           &didod,
                                           &dwObjCount, 0 );

    // アクションを処理する。どのデバイスから返されたかは問わない。
    switch(didod.uAppData)
    {
        case eA_STEER:
            SteerCar(didod.dwData);
            break;
        case eB_UPSHIFT
            if (didod.dwData & 0x80) ShiftGears(UPSHIFT);
            break;
        .
        .
        .

        default:
            break;
    }
}

注 : DIAXIS_DRIVINGR_STEER または DIAXIS_SPACESIM_LATERAL などの特定のジャンルの軸定数は、絶対的なジョイスティック データに対して使用される。アクション マッパーは、この仮想コントロールを絶対データを返すデバイス オブジェクトにマップする。アプリケーションでは、このデバイスから返されたデータを適切に処理する必要がある。ただし、DIMOUSE_XAXIS などのデバイス定数は、相対データを返すことが想定されている。

データを取得するときは、1 つのデバイス オブジェクが別のデバイス オブジェクトのデータを上書きしないように、各データ ソースを個別に処理する必要がある。たとえば、方向を制御する次の DIACTION 構造体はアクション マップで使用される。

{INPUT_LEFTRIGHT_ABS_AXIS, DIAXIS_SPACESIM_LATERAL, 0,   _T("Turn"),},
{INPUT_LEFTRIGHT_REL_AXIS, DIMOUSE_XAXIS,           0,   _T("Turn"),},
{INPUT_TURNLEFT,           DIKEYBOARD_LEFT,     0,  _T("Turn left"),},
{INPUT_TURNRIGHT,          DIKEYBOARD_RIGHT,    0, _T("Turn right"),},

アプリケーションの入力ループでは、次の case ステートメントでこれらのアクションのデータを処理する。

switch (adod[j].uAppData)
{
    case INPUT_LEFTRIGHT_ABS_AXIS:
        g_dwAbsLR = adod[j].dwData
        break;
    case INPUT_LEFTRIGHT_REL_AXIS:
        g_dwRelLR = adod[j].dwData;
        break;
    case INPUT_TURNLEFT:
        g_bLeft = (adod[j].dwData != 0);
        break;
    case INPUT_TURNRIGHT:
        g_bRight = (adod[j].dwData != 0)
        break;
}

データ ソースの割り当てに関して、すべてのデータ ソースが 1 つの汎用の "turn" 変数に割り当てられるのではなく、各データ ソースが個別の変数に割り当てられることに注意すること。データ ソースが汎用の変数を共有する場合、左矢印 (←) キーを押したままジョイスティックを移動すると、キーボード情報が失われる。これは、ジョイスティック データが汎用の変数を上書きするからである。

変数に対してと同様に、データに対してもさまざまな処理方法がある。どのような処理方法を使用する場合でも、予期しない情報の損失を避けるためにデータの処理には注意する必要がある。


開発中のファイルの管理

開発サイクルにおいては、頻繁なアクション マップの変更、Microsoft® DirectX® の再インストール、複数ユーザー、およびその他通常の開発状況によって、使用しない .ini ファイルや日付の古い .ini ファイルが累積する場合がある。このようなファイルが原因で、予期しないマッピングや "最新" レポート (DIEDBS_RECENTDEVICE) が、この値が返されることを予期していないデバイスに対して返される可能性がある。そのため、使用しない .ini ファイルをときどき削除することが望ましい。これらのファイルは、C:\Program Files\Common Files\DirectX\DirectInput\User Maps にある。

注 : ここに示した推奨手順は、開発サイクルにおいて、開発環境を最新の状態にするために手動で実行すべき手順である。ユーザーの優先設定を失う可能性があるため、出荷アプリケーションでは決してユーザー マップを削除してはならない。


フォース フィードバック

フォース フィードバックとは、入出力デバイス (たとえば、ジョイスティックに組み込まれているモーター) にプッシュあるいは抵抗を生成することである。Microsoft® DirectInput® では、互換性のあるドライバを持つデバイスにフォース フィードバック エフェクトを生成することができる。

以下のトピックでは、フォース フィードバックの概念を紹介する。

  • フォース フィードバックの基本概念
  • エフェクトの列挙
  • ファイルからのエフェクトの読み込み
  • サポートされるエフェクトについての情報
  • エフェクトの作成
  • エフェクトの方向
  • エンベロープとオフセット
  • エフェクトの再生
  • エフェクトのダウンロードとアンロード
  • エフェクトの変更
  • ゲイン
  • フォース フィードバック状態
  • エフェクト オブジェクトの列挙
  • エフェクトのタイプ


フォース フィードバックの基本概念

フォース フィードバックのうち特殊なインスタンスを "エフェクト" と言い、プッシュや抵抗を "フォース" と言う。多くのエフェクトは、以下のカテゴリのいずれかに属する。

  • コンスタント フォース － 単一方向の一定のフォース
  • 傾斜フォース － 一定の率で大きさが増加または減少するフォース
  • 周期的エフェクト － 定義された波形パターンで変化するフォース。
  • 条件 － 軸に沿った動きまたは動作への反応。たとえば、ジョイスティックの動作に対して抵抗を生み出す摩擦エフェクトや、ジョイスティックがある位置から動かされた後で、スティックをその位置に戻そうとするスプリング エフェクトである。

フォースの強さを "マグニチュード" という。マグニチュードは、0 (フォースなし) から 10,000 (デバイスの最大フォースで、C/C++ および Visual Basic の場合、DI_FFNOMINALMAX として定義されている) の範囲の単位で測定される。負の値は、反対の方向にあるフォースを示す。マグニチュードは比例的な単位である。たとえば、フォース 10,000 はフォース 5,000 の 2 倍の大きさである。

傾斜フォースには、初期マグニチュードと終期マグニチュードがある。周期的エフェクトでは、基本的マグニチュードは波の頂点でのフォースとなる。

フォースの "方向" はフォースが来る方向である。ある軸上の正のフォースは正から負のほうへ押す力である。

また、エフェクトには "継続時間" がある。これは、マイクロ秒単位で測定される。周期的エフェクトには、"周期" または 1 サイクルの継続時間があり、これらもマイクロ秒単位で測定される。周期的エフェクトの "フェーズ" とは、再生開始箇所の波にそって存在するポイントのことである。

次の図は、マグニチュード 5,000、つまりデバイスの最大フォースの半分での鋸歯周期的エフェクトを表す。水平軸はエフェクトの継続時間を、垂直軸はマグニチュードをそれぞれ表す。中央線よりも上のポイントは、エフェクトに定義された方向における正のフォースを、下のポイントは負のフォース、すなわち反対方向のフォースを表す。

さらにフォースは、"エンベロープ" によって形成される。エンベロープは、"アタック値" と "フェード値" を定義する。アタック値とフェード値により、始点と終点間のエフェクトのマグニチュードが変化する。アタックとフェードには継続時間がある。継続時間は、マグニチュードが "保持値" に到達するのに必要な時間、または保持値から外れるのに要する時間を決定する。保持値とは、エフェクトの中間部のマグニチュードのことである。

次の図は、エンベロープを示している。アタック レベルは 8,000、フェード レベルは 1,000 に設定されている。保持レベルは、このエンベロープを適用したフォースの基本的マグニチュードによって定義される。この例では保持レベルは 5,000 である。このケースでは、アタックの方が保持よりも大きいことに注意すること。これは、エフェクトの初期に強いキックを与えることになる。アタック レベルとフェード レベルの両方が保持レベルより大きいことも小さいこともある。

次の図は、最初の図の周期的エフェクトにエンベロープを適用した結果を示す。マグニチュードの負側では、エンベロープが鏡写しになっている。アタック値 8,000 が意味するのは、一方の方向のフォースの初期マグニチュードが、最大フォースの 80% になるということである。

周期的エフェクトと条件は、すべて、"オフセット" の追加によっても変更することができる。オフセットとは、波形を基本レベルよりも上または下にシフトする量を定義するものである。鋸歯の例に正のオフセットを適用した実際のエフェクトでは、正のフォースを強め、負のフォースを弱めることになる。すなわち、フォースの波形では、一方向への波の頂点が、他方向への波の頂点よりも高くなる。

また、エフェクトの全体的マグニチュードは、"ゲイン" によって増減可能である。ゲインとは、オーディオにおける音量コントロールに類似している。単一のゲイン値を 1 つのデバイスのすべてのエフェクトに適用できるので、これを使って、いろいろなハードウェアに対してフォースを強めたり、弱めたりする補正を加えることができる。また、ユーザーの好みに対応することもできる。


エフェクトの列挙

IDirectInputDevice8::EnumEffects メソッドは、さまざまな種類のエフェクトに関して、デバイスで提供されるサポートについての情報を返す。

"サポートされるエフェクト" と "生成されるエフェクト" ("エフェクト オブジェクト") の両者を区別することが重要である。サポートされるエフェクトは、デバイスが再生できるコンスタント フォースなどの基本的なタイプである。しかし、コンスタント フォース自体には、マグニチュード、方向、継続時間、アタックまたはフェードなどのプロパティがまったくない。これらのプロパティは、エンベロープのある未加工のエフェクト タイプを形成するか DIEFFECT 構造体の値を設定して、アプリケーションで特定のエフェクト オブジェクトを生成するときに設定される。サポートされるエフェクトは、それぞれ異なるパラメータを持つ多くのエフェクト オブジェクトによって表すことができる。たとえば、それぞれ異なる継続時間、マグニチュードおよび方向を持つ複数のコンスタント フォースによって表すことができる。

生成されたエフェクトの列挙については、「エフェクト オブジェクトの列挙」を参照すること。

ほかの Microsoft® DirectInput® 列挙と同様に、IDirectInputDevice8::EnumEffects メソッドにはコールバック関数が必要である。ドキュメントではこの関数はプレースホルダ名の DIEnumEffectsCallback で表されているが、好きな名前を付けることができる。この関数は、列挙されるエフェクトごとに呼び出される。この関数内では、それぞれのエフェクトに対する GUID を取得でき、ハードウェア サポートの範囲についての情報を取得でき、さらに、1 つまたはそれ以上のエフェクト オブジェクトを生成し、そのオブジェクトのメソッドを使用してエフェクトを操作することができる。

以下の例は、列挙を開始する。g_lpdid は、デバイスの IDirectInputDevice8 インターフェイスへの初期化されたポインタとする。

HRESULT hr = g_lpdid->EnumEffects(&DIEnumEffectsCallback,
        g_lpdid, DIEFT_ALL);

コールバックの骨格を、以下のコードに示す。このコールバック関数の pvRef パラメータは 32 ビットの任意の値を取ることができるが、この場合、このパラメータはデバイス インターフェイスへのポインタ (前の例のグローバル g_lpdid) であり、デバイスがサポートするエフェクトについての情報の取得と、エフェクト オブジェクトの生成に使用される。

BOOL CALLBACK DIEnumEffectsCallback(LPCDIEFFECTINFO pdei,
                                LPVOID pvRef)
{
    HRESULT              hr;
    LPDIRECTINPUTDEVICE8 lpdid = (LPDIRECTINPUTDEVICE8)pvRef;
// 呼び出しデバイスへのポインタ。
    LPDIRECTINPUTEFFECT  lpdiEffect;      // 生成されたエフェクトへのポインタ。
    DIEFFECT             diEffect;        // 生成されたエフェクト用のパラメータ。
    DICONSTANTFORCE      diConstantForce; // タイプ固有パラメータ。

    if (DIEFT_GETTYPE(pdei->dwEffType) == DIEFT_CONSTANTFORCE)
    {
       /* エフェクト タイプ (pdei から) のサポート情報を
抽出し、それに応じてエフェクトを適応させること
ができる。たとえば、このデバイスは、このタイプ
のエフェクトではエンベロープをサポートしない。 */
       .
       .
       .
       // 1 つまたはそれ以上のコンスタント フォース エフェクトを生成する。
       // それぞれについて、DICONSTANTFORCE と
       // DIEFFECT 構造体を初期化しなければならない。
       .
       .
       .
        hr = lpdid->CreateEffect(pdei->guid,
                                &diEffect,
                                &lpdiEffect,
                                NULL);
       .
       .
       .
    }
    // ほかのタイプのエフェクトについても同様。
   .
   .
   .

    return DIENUM_CONTINUE;
}  // コールバックの終了。

エフェクト生成の詳細な例について、およびエフェクトを初期化する方法の詳細については、「エフェクトの作成」を参照すること。


ファイルからのエフェクトの読み込み

Microsoft® DirectX® SDK で提供される Force Editor、または同じファイル フォーマットを使用する別のアプリケーションを使って、エフェクトをデザインし、ファイルに保存することができる。実行時にこれらのエフェクトを読み込むことで、任意のアプリケーションで使用することができる。

エフェクトを読み込むには、IDirectInputDevice8::EnumEffectsInFile メソッドを呼び出す。デフォルトでは、列挙は標準の Microsoft DirectInput® エフェクトに限定されるが、DIFEF_INCLUDENONSTANDARD フラグを設定することで、これ以外のエフェクトを列挙できる。また、DIFEF_MODIFYIFNEEDED フラグを設定すると、必要に応じて、エフェクトがデバイスに対して作用するように、各エフェクトのパラメータの変更を DirectInput に指示することができる(たとえば、2 つの軸に対して作成されたエフェクトを、単一軸の車のハンドルに対して作用させることができる)。

次のサンプル コードでは、最初の 3 つの標準エフェクトがファイルから読み込まれ、DirectInputEffect オブジェクトとして作成される。

// g_lpdid は、フォース フィードバック デバイスへの有効な
// IDirectInputDevice7 ポインタである。

// エフェクト ポインタの配列は、グローバルに宣言される。
LPDIRECTINPUTEFFECT pEff[3];
.
.
.
g_lpdid->EnumEffectsInFile("FEdit1.ffe",
                            EnumEffectsInFileProc,
                            NULL,
                            DIFEF_MODIFYIFNEEDED);
.
.
.

以下のコールバック関数は、DIENUM_STOP が返されるまで、エフェクト ファイル内のエフェクトごとに呼び出される。DIFEF_MODIFYIFNEEDED フラグが渡されたため、エフェクト パラメータは lpdife->lpDiEffect に変更されることに注意すること。このようにパラメータを修正したコールバックによって、エフェクトが生成される。

BOOL CALLBACK EnumEffectsInFileProc(LPCDIFILEEFFECT lpdife,
        LPVOID pvRef)

{
    HRESULT     hr;
    static int  i;

    hr = g_lpdid->CreateEffect(lpdife->GuidEffect,
                               lpdife->lpDiEffect,
                               &pEff[i],
                               NULL);
    if (FAILED(hr))
    {
        // エラー処理。
    }
    if (++i > 2) return DIENUM_STOP;
    else return DIENUM_CONTINUE;
}

Microsoft® DirectX® SDK で提供される Force Editor、または同じファイル フォーマットを使用する別のアプリケーションを使って、エフェクトをデザインし、ファイルに保存することができる。実行時にこれらのエフェクトを読み込むことで、任意のアプリケーションで使用することができる。

エフェクトを読み込むには、DirectInputDevice8.CreateEffectFromFile メソッドを呼び出す。その後、生成される DirectInputEffect オブジェクトを通常どおり使用できる。


サポートされるエフェクトについての情報

IDirectInputDevice8::GetEffectInfo メソッドを使うと、GUID が判明しているエフェクトについて、そのデバイスのサポート情報を取得できる。このメソッドは、DIEFFECTINFO 構造体で返される情報と同じ情報を列挙中に取得する。詳細については、「エフェクトの列挙」を参照すること。

次のサンプル コードは、EffectGuid 変数に GUID が格納されているエフェクトに関する情報を取得し、エフェクトを停止または再起動せずにエフェクトの方向を変更できるかどうかを調べる。

DIEFFECTINFO diEffectInfo;
diEffectInfo.dwSize = sizeof(DIEFFECTINFO);
g_lpdid->GetEffectInfo(&diEffectInfo, EffectGuid);
if (diEffectInfo.dwDynamicParams & DIEP_DIRECTION)
{
  // パラメータは動的にリセットできる。
}


エフェクトの作成

エフェクト オブジェクトを生成するには、IDirectInputDevice8::CreateEffect メソッドを使用する。次のサンプル コードで、g_lpdid はインターフェイスのインスタンスを指している。この例では、半秒間に全力でジョイスティックをユーザーから離れる方向へ引くという、非常に単純なエフェクトが生成される。

HRESULT  hr;
LPDIRECTINPUTEFFECT lpdiEffect;  // 生成されるエフェクトへのポインタを受け取る。
DIEFFECT diEffect;               // 生成されるエフェクト用のパラメータ。

DWORD    dwAxes[2] = { DIJOFS_X, DIJOFS_Y };
LONG     lDirection[2] = { 18000, 0 };

DICONSTANTFORCE diConstantForce;

diConstantForce.lMagnitude = DI_FFNOMINALMAX;   // 最大フォース。

diEffect.dwSize          = sizeof(DIEFFECT);
diEffect.dwFlags         = DIEFF_POLAR | DIEFF_OBJECTOFFSETS;
diEffect.dwDuration      = (DWORD)(0.5 * DI_SECONDS);
diEffect.dwSamplePeriod  = 0;                 // デフォルト設定。
diEffect.dwGain          = DI_FFNOMINALMAX;   // スケーリングなし。
diEffect.dwTriggerButton = DIEB_NOTRIGGER;    // ボタン応答ではない。
diEffect.dwTriggerRepeatInterval = 0;         // 利用できない。
diEffect.cAxes                   = 2;
diEffect.rgdwAxes                = &dwAxes[0];
diEffect.rglDirection            = &lDirection[0];
diEffect.lpEnvelope              = NULL;
diEffect.cbTypeSpecificParams    = sizeof(DICONSTANTFORCE);
diEffect.lpvTypeSpecificParams   = &diConstantForce;

hr = g_lpdid->CreateEffect(GUID_ConstantForce,
                           &diEffect,
                           &lpdiEffect,
                           NULL);

このメソッド呼び出しでは、最初のパラメータは、生成されるエフェクトに関連付けられたサポートされるエフェクトを表す。この例では、Dinput.h で定義済みの GUID のうちの 1 つを使用している。定義済みの GUID を使用する場合、デバイスがこのエフェクトをサポートしなければ呼び出しは失敗する。

第 2 のパラメータは、DIEFFECT 構造体に指定されているパラメータを設定する。

第 3 のパラメータは、呼び出しが成功した場合に、エフェクト オブジェクトへのポインタを受け取る。

DIEFF_POLAR フラグは、フォースの方向に使用する座標の種類を指定する (「エフェクトの方向」を参照すること)。このフラグは DIEFF_OBJECTOFFSETS と組み合わされる。これは、ほかのメンバで使用されるボタンや軸も、このデバイスの DIDATAFORMAT 構造体の中でオフセットによって識別される、ということを示す。この代わりに DIEFF_OBJECTIDS フラグを使用することができる。このフラグは、オブジェクトが IDirectInputDevice8::EnumObjects メソッドで列挙されたとき、そのオブジェクトに対して返される DIDEVICEOBJECTINSTANCE 構造体の dwType メンバによってボタンと軸が識別される、ということを意味している。

DIEFFECT 構造体のメンバの詳細については、「エフェクトの方向」を参照すること。

デバイスが満杯ではなく、排他協調レベルで取得されたなら、エフェクトは作成時にデバイスに自動的にダウンロードされる。


エフェクトの方向

1 つまたはそれ以上の軸に対して方向を定義することができる。マウスとジョイスティックの場合と同様に、x 軸は左から右へと増加し、y 軸は遠くから近くへと増加する。3 次元デバイスでは、z 軸は上方から下方へと増加する。

エフェクトの方向は、エフェクトが来る方向である。y 軸の負側に沿った方向でのエフェクトは、スティックを y 軸の正側に沿って (ユーザーに向かって) 押そうとする。エフェクトを打ち消すためにユーザーがスティックを左方向に押さなければならない場合、このエフェクトは「左」方向である。つまり、このエフェクトは x 軸の負側にある。

方向は "極" 座標、"球状" 座標、または、"デカルト" 座標で表すことができる。

極座標は、エフェクトに対して設定されたゼロポイント (真北) から時計回りに、実角度の 100 倍の単一角度で表される。通常これは負側の y 軸、すなわち、ユーザーから遠ざかる方向である。したがって、極座標 9,000 のエフェクトは通常、東の方向つまりユーザーの右側の方向を持つ。このエフェクトを打ち消すには、ユーザーは右側へ力を加えなければならない。

球状座標も実角度の 100 倍で表されるが、2 つまたはそれ以上の角度を含むことがある。それぞれの角度について、方向は次の軸の正方向に回転する。3 次元デバイスの場合は、第 1 の角度は、通常正側の x 軸から正側の y 軸に向かって (東から時計回りに) 回転し、第 2 の角度は正側の z 軸に向かって (下方へ) 回転する。したがって、方向が (0, 0) のフォースはユーザーの右側の方向であり、机面と平行になる。第 1 の角度が 27,000 で第 2 の角度が 4,500 の方向とは、ユーザーからまっすぐに離れながら (東から時計回りに 270 度)、床に向かう (机面から下方へ 45 度の角度) 方向である。この方向のフォースを打ち消すには、前方へ押し出しながら下方へ押し下げなくてはならない。

デカルト座標は 3 次元ベクトルに似ている。中心を始点 (0,0) とするグラフ用紙に直線を引くと、その直線の方向は、始点からの距離とは関係なく、交点の任意の座標により定義することができる。したがって、方向 (1, -2) と方向 (5, -10) はまったく同じものとなる。

注 : フォース フィードバック エフェクトの作成に使用する座標は方向のみを定義し、マグニチュードや距離は定義しない。

エフェクトを生成または変更するときは、DIEFFECT 構造体の cAxes、rgdwAxes、および rglDirection メンバを使用して、フォースの方向を指定する。

cAxes メンバは、エフェクトに含まれる軸の数を指定する。これは、次に続く 2 つのメンバが指す配列の要素の数でもある。

rgdwAxes が指す配列により、エフェクトが適用される軸が識別される。DIEFF_OBJECTOFFSETS フラグが設定されていれば、軸はデータ形式構造体内のオフセットによって指定される。これらのオフセットは DIJOFS_* を使って非常に簡単に指定される (これらの値については、「ジョイスティック デバイス定数」を参照すること)。

最後に、rglDirection メンバはフォースの方向を指定する。

注 : cAxes および rgdwAxes メンバは一度設定すると、変更することはできない。エフェクトは常に同一の軸リストを持つ。

デカルト座標、極座標、球状座標のどれを使用する場合でも、rgdwAxes が指す配列にある軸の数とまったく同じ数の要素を rglDirection に用意しなければならない。

極座標システムでは、「北 (ゼロ度)」はベクトル (0, -1) 上にあり、このベクトルの要素は rgdwAxes が指す軸リストの要素に対応する。通常はこれらの軸は x と y なので、北はそのまま y 軸の負側の方向になる。すなわち、ユーザーから離れる方向になる。rglDirection の最後の要素はゼロでなければならない。

「エフェクトの作成」での例では、2 次元フォースの方向は極座標で定義される。この例ではフォースは南方向、すなわちユーザーの方向から来ているので、ユーザーがフォースを打ち消すにはスティックを手前に引き寄せなくてはならない。南の方向は北から時計回りに 180 度であり、次のように割り当てることができる

LONG  lDirection[2] = { 18000, 0 };

より明確にするために、割り当ては次のように表すこともできる。

LONG  lDirection[2] = { 180 * DI_DEGREES, 0 };

球状座標については、3 軸デバイスで作業していると仮定した場合、同じ方向は次のように割り当てられる。

LONG  lDirection[3] = { 90 * DI_DEGREES, 0, 0 }

第 1 の角度は、方向 (1, 0) から方向 (0,1) へ回転した実角度の 100 倍で計測される。第 2 の角度は (0, 0, 1) へ回転する実角度の 100 倍で計測される。この場合も、ベクトル表記法の要素は rgdwAxes メンバが指す配列の要素に対応する。この配列の要素が、順に x 軸、y 軸、および z 軸を表すと仮定しよう。原点は x = 1、y = 0 である、すなわち、ユーザーの右側にある。回転の方向は、y 軸の正側 ( 0, 1) に向かう、すなわち、ユーザー側へ、または時計回りに向かう。この例におけるフォースは、右から時計回りに 90 度である、すなわち、南方向である。lDirection の第 2 の要素が 0 なので、第 3 軸上での回転はない。

デカルト座標でこれと同じことを実現するにはどうしたらよいだろうか。dwFlags メンバの DIEFF_CARTESIAN フラグを使用すると仮定すれば、次のように方向を指定することになる。

LONG  lDirection[2] = { 0, 1 };

繰り返すが、この配列の要素は rgdwAxes が指す配列にリストされている軸に対応している。この例では x 軸にゼロを設定し、y 軸に 1 を設定している。すなわち、方向は直接 y 軸の正側上、または南にある。

エフェクトの方向についての理論は、理解するのは難しいかもしれないが、実践してみればかなり容易に理解できる。サンプル コードがあるので、「エフェクト方向設定の実例」を参照すること。


エフェクト方向設定の実例

単一軸エフェクト

単一軸エフェクトの方向の設定は、実際に指定するものが何もないので、単純である。DIEFF_CARTESIAN フラグを DIEFFECT 構造体の dwFlags メンバに設定し、値がゼロの単一の LONG を指す rglDirection を設定する。

次のコードは、x 軸エフェクトの方向と軸パラメータを設定する例である。

DIEFFECT eff;
LONG     lZero  = 0;                       // 方向なし。
DWORD    dwAxis = DIJOFS_X;                // x 軸エフェクト。

ZeroMemory(&eff, sizeof(DIEFFECT));
eff.cAxes        = 1;                                     // 1 つの軸。
eff.dwFlags      = DIEFF_CARTESIAN | DIEFF_OBJECTOFFSETS; // フラグ。
eff.rglDirection = &lZero;                                // 方向。
eff.rgdwAxes     = &dwAxis;                         // エフェクトの軸。

極座標での 2 軸エフェクト

極座標 2 軸エフェクトの方向の設定は少し複雑である。DIEFF_POLAR フラグを dwFlags に設定し、2 つの LONG からなる 1 つの配列を指すように rglDirection を設定する。こうすると、この配列の第 1 の要素が、エフェクトが来る方向になる。この配列の第 2 の要素はゼロでなくてはならない。

次のコードは、東から来る 2 軸エフェクトの方向と軸パラメータを設定する例である。

DIEFFECT eff;
LONG     rglDirection[2] = { 90 * DI_DEGREES, 0 };
DWORD    rgdwAxes[2]     = { DIJOFS_X, DIJOFS_Y };   // x 軸と y 軸。

ZeroMemory(&eff, sizeof(DIEFFECT));
eff.cAxes        = 2;                                  //  2 つの軸。
eff.dwFlags      = DIEFF_POLAR | DIEFF_OBJECTOFFSETS;  // フラグ。
eff.rglDirection = rglDirection;                       // 方向。
eff.rgdwAxes     = rgdwAxes;                     // エフェクトの軸。

デカルト座標での 2 軸エフェクト

デカルト座標 2 軸エフェクトの方向の設定は少し複雑である。DIEFF_CARTESIAN フラグを dwFlags に設定し、ここでも、2 つの LONG からなる 1 つの配列を指すように rglDirection を設定する。このときの配列の第 1 要素は方向ベクトルの x 座標で、第 2 要素は y 座標である。

次のコードは、東から来る 2 軸エフェクトの方向と軸パラメータを設定する例である

DIEFFECT eff;
LONG     rglDirection[2] = { 1, 0 };            // 正値 x = 東。
DWORD    rgdwAxes[2]     = { DIJOFS_X, DIJOFS_Y };  // x 軸と y 軸。

ZeroMemory(&eff, sizeof(DIEFFECT));
eff.cAxes = 2;                                       //  2 つの軸。
eff.dwFlags = DIEFF_CARTESIAN | DIEFF_OBJECTOFFSETS; // フラグ。
eff.rglDirection = rglDirection;                     // 方向。
eff.rgdwAxes = rgdwAxes;                       // エフェクトの軸。


エンベロープとオフセット

エンベロープ とオフセットを使って、いくつかの基本的マグニチュードを変更することができる。概要については、「フォース フィードバックの基本概念」を参照すること。

エフェクトの作成または変更の際にエンベロープを適用するには、DIENVELOPE 構造体を初期化して、この構造体へのポインタを DIEFFECT 構造体の lpEnvelope メンバに設定する。

どのエフェクトがエンベロープをサポートするかを決定するのはデバイス ドライバである。通常は、コンスタント フォース、傾斜フォースおよび周期的フォースにエンベロープを適用できるが、条件には適用できない。特定のフォースがエンベロープをサポートするかどうかを判定するには、IDirectInputDevice8::GetEffectInfo メソッドを呼び出し、DIEFFECTINFO 構造体の dwStaticParams メンバにある DIEP_ENVELOPE フラグをチェックする。

オフセットを適用するには、DIEFFECT 構造体の lpvTypeSpecificParams メンバが指す DIPERIODIC 構造体または DICONDITION 構造体の lOffset メンバを設定する。周期的エフェクトの場合、オフセットの絶対値とエフェクトのマグニチュードを足した値が DI_FFNOMINALMAX を超えてはならない。

オフセットをコンスタント フォースや傾斜フォースに適用することはできない。コンスタント フォースや傾斜フォースの場合、マグニチュードを変更することによって同じエフェクトを発生させることができる。


エフェクトの再生

エフェクトの再生を開始する主な方法は 2 つある。IDirectInputEffect::Start メソッドを呼び出して手動で開始する方法と、ボタン押下への応答で自動的に開始する方法である。DIEP_START フラグを指定して IDirectInputEffect::SetParameters メソッドを呼び出すことでエフェクトを変更するときにも、再生が開始する。

dwIterations パラメータに INFINITE を渡すと、エンベロープを適用しながらエフェクトの再生を反復させることができる。エンベロープを反復することなくエフェクトを反復したいとき (たとえば、最初に強いキックをした後、動悸を静めるというような場合) は、dwIterations に 1 を設定し、次に DIEFFECT 構造体の dwDuration メンバに INFINITE をセットすればよい(これは IDirectInputDevice8::CreateEffect メソッドに渡される構造体である)。

注 : デバイスによっては、エフェクトの複数回の補間が不可能で、Start メソッドへのパラメータ dwIterations に値 1 しか認めないものもある。Start からの戻り値を常にチェックして、エフェクトが正常に再生されたかどうかを確認しなければならない。

エフェクトをボタン押下に割り付けるには、DIEFFECT 構造体の dwTriggerButton メンバを設定する。ボタンが押下されているときの再生間に遅延を加えたいならば、その遅延値を dwTriggerRepeatInterval メンバに設定する。この遅延は、1 つの再生の終了から次の再生の開始までの間隔のことで、マイクロ秒単位で表される。

注 : デバイスによっては、複数回のエフェクトを同じボタンで発生させることができないものもある。2 つ以上のエフェクトを 1 つのボタンに割り付けると、最後にダウンロードされたエフェクトが、発生するエフェクトとなる。また、トリガの反復間隔はサポートされていない。

エフェクトのトリガ ボタンへの割り付けを解除するには、IDirectInputEffect::Unload メソッドを呼び出すか、または DIEB_NOTRIGGER に設定されている dwTriggerButton に、このエフェクト用のパラメータを設定するか、どちらかの操作を行わなければならない。

割り付けたエフェクトは、ほかのすべてのエフェクトと同様に、アプリケーションがデバイスへのアクセス権を失うと失われる。再びこれらのエフェクトを有効にするには、アプリケーションがデバイスを再取得すると同時にこれらのエフェクトをダウンロードする。「エフェクトのダウンロードとアンロード」を参照すること。この処理はトリガに割り付けていないエフェクトでは不必要である。なぜなら、この種のエフェクトは、Start メソッドが呼び出されるときはいつも、必要に応じて自動的にダウンロードされるからである。

エフェクトの継続時間が有限で、エフェクトが Start メソッドへの呼び出しによって開始する場合、継続時間が過ぎるとエフェクトの再生は終了する。エフェクトの継続時間が INFINITE に設定されていた場合、再生が終了するのは、IDirectInputEffect::Stop メソッドが呼び出されたときのみである。トリガボタンに割り付けたエフェクトはそのボタンを押すと開始し、そのボタンを離すか、継続時間が過ぎるか、どちらか早い方の時点で終了する。


エフェクトのダウンロードとアンロード

エフェクトは再生する前にデバイスにダウンロードしなければならない。エフェクトのダウンロードとは、ドライバにエフェクトの再生の準備をするように通知することである。ダウンロードの方法を決定するのはまったくドライバに任せられる。一般に、ドライバはエフェクトのパラメータをハードウェア メモリに置き、デバイスとシステムの間のデータ順次転送を最小限に抑える。これにより、遅延時間が削減される。このことは、"発射" ボタンのように、トリガへの応答で機能する条件とエフェクトにとっては特に意味がある。デバイスが軸移動とボタン押下に応答するためにシステムとまったくやりとりを行う必要がない、というのが理想的だろう。

デバイスが満杯ではなくしかも排他協調レベルで取得されている場合には、エフェクトの作成時にダウンロードが自動的に行われる。エフェクトを開始、またはエフェクトのパラメータを変更するときも、ダウンロードはデフォルトで行われる。

パラメータを変更するときに DIEP_NODOWNLOAD フラグを指定すれば、引き続き IDirectInputEffect::Download メソッドを使用してエフェクトのダウンロードやアップロードを行わなければならない。

デバイスが未取得状態のとき (たとえば、デバイスが排他フォアグラウンド協調レベルで取得されていて、アプリケーションがバックグラウンドに移行するとき)、エフェクトはアンロードされているので、アプリケーションがフォアグラウンドを再取得するときに再びエフェクトをダウンロードしなければならない。エフェクトのダウンロードは、IDirectInputEffect::Start メソッドを呼び出すと自動的に行われる。しかし、デバイスを再取得すると同時にすべてのエフェクトをダウンロードするかどうかを選択することはできる。Start メソッドは通常トリガ ボタンに割り付けたエフェクトでは呼び出されないので、この種のエフェクトは必ずダウンロードする必要がある。

エフェクトのダウンロード中にアプリケーションが DIERR_DEVICEFULL エラーを受けたら、古いエフェクトをアンロードして新しいエフェクトのためのスペースを確保する必要がある。IDirectInputEffect::Unload メソッドを呼び出せば、デバイスから 1 つのエフェクトを削除することができる。また、IDirectInputDevice8::SendForceFeedbackCommand メソッドを呼び出してデバイスをリセットすれば、すべてのエフェクトを削除することもできる。

フォース フィードバック デバイスを生成すると、ハードウェアとドライバがリセットされるので、存在していたエフェクトすべてが消去される。


エフェクトの変更

エフェクトの再生中でもエフェクトのパラメータを変更することができる場合がある。これは IDirectInputEffect::SetParameters メソッドを使用して行う。

DIEFFECTINFO 構造体の dwDynamicParams メンバは、エフェクトの再生中でも変更できるエフェクトのパラメータを通知する。エフェクトの再生中には変更できないエフェクトのパラメータを変更しようとして、エフェクトが実際にまだ再生しているときは、通常、Microsoft® DirectInput® はエフェクトを停止させ、パラメータを更新し、エフェクトを再スタートさせる。この DirectInput のデフォルトの動作を無効にするには、DIEP_NORESTART フラグを渡せばよい。

次の C++ のプログラム例では、「エフェクトの作成」にあるサンプル プログラムでセットされたコンスタント フォースのマグニチュードを変更する。

DIEFFECT        diEffect;           // エフェクト用のパラメータ。
DICONSTANTFORCE diConstantForce;    // タイプ固有パラメータ。

diConstantForce.lMagnitude = 5000;
diEffect.dwSize = sizeof(DIEFFECT);
diEffect.cbTypeSpecificParams = sizeof(DICONSTANTFORCE);
diEffect.lpvTypeSpecificParams = &diConstantForce;
hr = lpdiEffect->SetParameters(&diEffect, DIEP_TYPESPECIFICPARAMS);

DIEP_TYPESPECIFICPARAMS フラグにより、DIEFFECT 構造体からのデータ転送は、関連するメンバに限られることが保証される。したがって、この構造体全体を初期化する必要がなくなり、デバイスに送信する必要のあるデータの量が最小限で済む。


ゲイン

フォースを及ぼすデバイスの種類に応じて、エフェクトのフォースの大きさに差を付けたい場合があるだろう。たとえば、ある軸に対して最大 n ニュートンのフォースを生み出すデバイスでアプリケーションのエフェクトが正しく働くと思われるときは、より多くのフォースを生み出すデバイス用にゲインを調整したいことがあるだろう (軸のフォースの最大値を増やすためにゲインを使用することはできないので、生み出すフォースが小さいデバイスに対して、適切な値を基本的エフェクト マグニチュードに設定すべきである)。

また、ゲインを使って、ハードウェアで定義されたエフェクトのマグニチュードを減少させることもできる。

軸やボタンなどのデバイス オブジェクトによって発生するフォースは、オブジェクトの列挙時に DIDEVICEOBJECTINSTANCE 構造体の dwFFMaxForce メンバに格納されて返される (「デバイス オブジェクトの列挙」を参照すること)。

IDirectInputDevice8::SetProperty メソッドを使用して、デバイス全体のゲインを設定することができる。

個別のエフェクトを作成するときは、DIEFFECT 構造体の dwGain メンバに値を設定することで、エフェクトにゲインを設定しなければならない (dwGain がゼロならば、そのエフェクトは感じられない)。この値は、dwFlags パラメータに DIEP_GAIN を指定して IDirectInputEffect::SetParameters を呼び出すことで、後から変更することができる。

デバイス ゲインを設定する目的は、アプリケーションにすべてのエフェクトのフォースを一括して制御させることである。たとえば、音響ミキサのメイン ボリューム コントローラのように、フォース フィードバック エフェクトに必要とされる強度をユーザーに指定させるスライダ コントロールをアプリケーションに付けたいと思うことがあるだろう。デバイス ゲインを設定すれば、ユーザーの好みに合わせて個別のエフェクトのゲインを、アプリケーションが調整する必要がなくなる。

1 つのゲイン値は 0 から 10,000 の範囲の値を取る。10,000 という値は、マグニチュードをスケーリングすべきでないということを示す。7,500 という値は、フォースの名目マグニチュードの 75% にフォースをスケーリングすべきであるということを意味している。その他の数値もこれに準じる。


フォース フィードバック状態

IDirectInputDevice8::SendForceFeedbackCommand メソッドを使用すれば、デバイスのアクチュエータをオフ (再生しているエフェクトすべてを無視するのに有効) にし、エフェクトの再生を中断または中止し、デバイスをリセットしてダウンロードしたすべてのエフェクトを削除することができる。

現在のフォース フィードバック状態を取得するには、IDirectInputDevice8::GetForceFeedbackState メソッドを使用する。このメソッドにより、アクチュエータが有効かどうか、再生が中断状態かどうか、およびデバイスがリセットされたかどうかという情報が返される。また、さまざまなスイッチに関する情報や、現在デバイスに電源が入っているかどうかの情報も取得される。


エフェクト オブジェクトの列挙

プログラムに生成したすべてのエフェクトの実験や操作が必要になったときは、IDirectInputDevice8::EnumCreatedEffectObjects メソッドを利用することができる。現在のところ、このメソッドにはフラグがまったく定義されていないので、特定の種類のエフェクトに列挙を絞り込むことはできない。すべてのエフェクトが列挙されてしまう。

注 : このメソッドは生成されるエフェクトは列挙するが、デバイスによってサポートされるエフェクトは列挙しない。この 2 つのエフェクトの区別について詳細は、「エフェクトの列挙」を参照すること。

Microsoft® DirectInput® のほかの列挙と同様に、EnumCreatedEffectObjects メソッドにはコールバック関数が必要である。この標準コールバック関数は、ドキュメントではプレースホルダ名 DIEnumCreatedEffectObjectsCallback で表されているが、異なる名前を付けてもよい。この関数は列挙されたエフェクトそれぞれについて呼び出される。この関数内では、どんな処理でも実行することができる。しかし、列挙の実行中は新しいエフェクトを生成しない方が安全である。

次に挙げるのは、コールバック関数の骨格を示すコード例である。コールバック関数の pvRef パラメータは、32 ビットの任意の値を取ることができる。この場合、このパラメータは IDirectInputDevice8 インターフェイスへのポインタである。

HRESULT  hr;

BOOL CALLBACK DIEnumCreatedEffectObjectsCallback(
                             LPDIRECTINPUTEFFECT peff, LPVOID pvRef);
{
    LPDIRECTINPUTDEVICE pdid = (IDirectInputDevice*)pvRef;
                                        // 呼び出しデバイスへのポインタ。
    DIEFFECT            diEffect;       // 生成されたエフェクト用のパラメータ。

    diEffect.dwSize = sizeof(DIEFFECTINFO);
    peff->GetParameters(&diEffect, DIEP_ALLPARAMS);
    // パラメータのチェックまたは設定、あるいはその他の処理。
    .
    .
    .
}   // コールバックの終了。

この呼び出しは、コールバックを始動し、DirectInputDevice ポインタ lpdid に渡す。

hr = lpdid->EnumCreatedEffectObjects(
         &DIEnumCreatedEffectObjectsCallback,
         &lpdid, 0);


エフェクトのタイプ

ここでは、以下のフォース フィードバック エフェクト タイプについて説明する。

  • コンスタント フォース
  • 傾斜フォース
  • 周期的エフェクト
  • 条件
  • カスタム フォース
  • デバイス エフェクト


コンスタント フォース

コンスタント フォースは、一定のマグニチュードと継続時間を持つフォースのことである。

エンベロープをコンスタント フォースに適用して、フォースに形を与えることができる。たとえば、2,000 の名目マグニチュードと 2 秒の継続時間を持つエフェクトがあると仮定しよう。この場合、次の値を持つエンベロープを適用する。

パラメータ | 値
アタック時間 | 0.5 秒
初期アタック レベル | 5,000
フェード時間 | 1 秒
フェード レベル | 0

エフェクトを再生すると、次の値が得られる。

経過時間 | マグニチュード
0.0 | 5,000
0.1 | 4,400
0.2 | 3,800
0.3 | 3,200
0.4 | 2,600
0.5 | 2,000
(保持の継続時間) | 2,000
1.0: | 2,000
1.1 | 1,800
1.2 | 1,600
1.3 | 1,400
1.4 | 1,200
1.5 | 1,000
1.6 | 800
1.7 | 600
1.8 | 400
1.9 | 200
2.0 | 0

コンスタント フォースにオフセットを適用することはできない。

コンスタント フォースを生成するには、GUID_ConstantForce を IDirectInputDevice8::CreateEffect メソッドに渡す。DIEFFECTINFO 構造体のメンバ dwEffType (DIEFT_GETTYPE(dwEfftype)) の下位バイトが DIEFT_CONSTANTFORCE と等しいときは、IDirectInputDevice8::EnumEffects メソッドで取得したほかの任意の GUID を渡すことができる。この方法を使えば、騒乱をシミュレーションする "コンスタント" フォース (名前は "コンスタント (定常)" だが実際にはマグニチュードがランダムに変化する) など、業者が設計したハードウェア特有のフォースを使用することができる。

コンスタント フォースは、DICONSTANTFORCE 構造体を使ってマグニチュードを定義する。負のマグニチュードには、フォースの方向を反転するエフェクトがある。


傾斜フォース

傾斜フォースは、定義済みの初期マグニチュードと終期マグニチュードおよび有限の継続時間を持つフォースのことである。傾斜フォースは、1 方向だけに延びる場合も、あるいは 1 方向に向かって強い勢いで始まり、弱まって、停止し、反対方向に強く進むという場合もある。

次の図は、マグニチュード -5,000 で始まり、マグニチュード 5,000 で終わる傾斜フォースを表している。

エンベロープ を傾斜フォースに適用して、傾斜フォースを引き伸ばすことができる。次の図は、前の図の傾斜フォースにエンベロープ (緑で表してある) を適用するエフェクトを表している。

エンベロープの維持期間部分では、エフェクトのマグニチュードはエンベロープの適用前と同じ直線を描くことに注意する。アタック と フェードの継続時間については、傾斜フォースの傾斜はアタック レベルとフェード レベルで変更される。

傾斜フォースにはオフセットを適用できない。

傾斜フォースを生成するには、GUID_RampForce を IDirectInputDevice8::CreateEffect メソッドに渡す。DIEFFECTINFO 構造体のメンバ dwEffType (DIEFT_GETTYPE(dwEfftype)) の下位バイトが DIEFT_RAMPFORCE と等しい場合は、IDirectInputDevice8::EnumEffects メソッドで取得したほかの任意の GUID を渡すこともできる。この方法を使えば、業者が設計したハードウェア特有の傾斜フォースを使用することができる。

傾斜フォースは DIRAMPFORCE 構造体を利用して、フォースの初期マグニチュードと終期マグニチュードを定義することができる。一方、その継続時間は DIEFFECT 構造体によって定義される。継続時間を決して INFINITE に設定してはいけない。


周期的エフェクト

周期的エフェクトは波形エフェクトである。Microsoft® DirectInput® では、以下の波形を定義している。

  • 正方形
  • サイン カーブ
  • コサイン カーブ
  • 三角形
  • アップ鋸歯 (SawtoothUp) － この波形は最大の正フォースに達した後、垂直に下降する。フォース フィードバックの基本概念」の例を参照すること。
  • ダウン鋸歯 (SawtoothDown) － この波形は最大の負フォースに達した後、垂直に上昇する。

周期的エフェクトにはエンベロープを適用することができる。「フォース フィードバックの基本概念」の例を参照すること。

周期的エフェクトのフェーズとは、エフェクトが始まる波形上のポイントである。フェーズは 0 から 35,999 までの範囲で、実角度の 100 倍で計測される。次の表は、選択したフェーズ値 (度単位) がさまざまな波形上のどこにあるかを示している。Max は波の最上部 (+) または最底部 (-) であり、Mid は波の中間ポイントである。これらの位置では、どちらの方向にもフォースは適用されていない。

波形 | 0 | 90 | 180 | 270
正方形 | +Max | +Max | -Max | -Max
サイン カーブ | Mid | +Max | Mid | -Max
三角形 | +Max | Mid | -Max | Mid
アップ鋸歯 | -Max | -Max/2 | Mid | +Max/2 (サイクルの反復の直前に +Max に達する)
ダウン鋸歯 | +Max | +Max/2 | Mid | -Max/2 (サイクルの反復の直前に -Max に達する)

ドライバにより、フェーズ値が直近のサポート値に丸められることがある。たとえば、ドライバによっては、サインエフェクトで 0 と 9,000 (コサインを生成するために) しかサポートせず、その他のエフェクトで 0 と 18,000 しかサポートしていないこともある。

周期的フォースを生成するには、IDirectInputDevice8::CreateEffect メソッドの rguid パラメータに次に挙げる値のどれか 1 つを渡す。

  • GUID_Square
  • GUID_Sine
  • GUID_Triangle
  • GUID_SawtoothUp
  • GUID_SawtoothDown

DIEFFECTINFO 構造体のメンバ dwEffType (DIEFT_GETTYPE(dwEfftype)) の下位バイトが DIEFT_PERIODIC に等しい場合は、IDirectInputDevice8::EnumEffects メソッドで取得したほかの任意の GUID を渡してもよい。この方法を使えば、業者が設計したハードウェア特有のフォースを使用することができる。たとえば、スティックを小さい円形に回転する周期的エフェクトをサポートしているハードウェア デバイスなどがある。

周期的エフェクトのタイプ固有構造体は DIPERIODIC である。

周期的エフェクトの "周期" (DIPERIODIC.dwPeriod) と "サンプリング間隔" (DIEFFECT.dwSamplePeriod) を混同しないように注意すること。周期は 1 つの波のサイクル全体を実行するのに要する時間である。サンプリング間隔は、すべてのエフェクトと同様に、マグニチュードを実際に調整する間隔の最小時間である。


条件

条件とは、デバイス内の現在のセンサ値に反応して適用されるフォースのことである。すなわち、条件は、ジョイスティック ハンドルの位置または速度など、デバイスに関する情報を必要とする。

一般的に、条件はゲームやその他のアプリケーションにおける個別のイベントには関連付けられていない。条件は、フライト スティックの硬さや緩さ、または直進の位置に戻すハンドルの向きなどの状態を表現する。

条件は、定義されたマグニチュードを持たない。マグニチュードは、入力オブジェクトの動作と位置によって測定される。

Microsoft® DirectInput® は、次のような条件のエフェクトを定義する。

  • 摩擦 ― 軸が移動するときに適用されるフォースで、定義済みの摩擦係数によって決まる。
  • ダンパ ― このフォースはユーザーがジョイスティックを動かす速度に比例して増加する。
  • 慣性 ― このフォースは軸の加速度に比例して増加する。
  • スプリング ― このフォースは定義されている中立ポイントからの軸の距離に比例して増加する。

ほとんどのハードウェア デバイスでは、条件にエンベロープを適用できない。

条件には次のタイプのパラメータがある。

Offset
条件の適用が始まる適切なセンサ値を読み込む、ゼロからのオフセット。スプリング エフェクトでは、中立ポイント (スプリングが静止していると考えられる軸上のポイント) は条件用のこのオフセットによって定義される。ダンパ エフェクトでは、このオフセットにより、ダンパ フォースがゼロとなる最大速度値が定義される。通常、オフセットは慣性エフェクトや摩擦エフェクトには使用しない。
Coefficient
エフェクトのスケーリングを算出する乗数。デバイスによっては、条件に関係する軸上の正方向と負方向に別の係数を設定することができる。たとえば、攻撃を受けた飛行機をコントロールする操縦桿は、左よりも右へ動かす方が容易になるというような場合である。
Saturation
フォース フィードバックでは、飽和はエフェクトを上げる最大のフォースを表している。たとえば、操縦桿が X 軸上でスプリング条件を持っていると仮定してみよう。オフセットはゼロ、係数は 10,000 であり、通常は操縦桿が中立ポイントから最も離れているときに、最大フォースが発揮される。しかし、正負 5,000 の飽和を定義していると、操縦桿が右や左に移動した後、フォースは増加しない。

飽和をサポートしていないデバイスもある。

Deadband
デッドバンドとは、条件が作用しない軸のオフセット範囲のことである。スプリングが軸の中立ポイントに静止している場合は、デッドバンドはこの静止の範囲を拡張する。

デッドバンドをサポートしていないデバイスもある。

条件に継続時間を設定することができる。しかし、継続時間を INFINITE (-1) に設定し、アプリケーションで特定のイベントに応答するときだけエフェクトを停止する方法が使用されることが多い。

条件を生成するには、IDirectInputDevice8::CreateEffect メソッドの rguid パラメータに、次に挙げる値のどれか 1 つを渡す。

  • GUID_Spring
  • GUID_Damper
  • GUID_Inertia
  • GUID_Friction

DIEFFECTINFO 構造体のメンバ dwEffType (DIEFT_GETTYPE(dwEfftype)) の下位バイトが DIEFT_CONDITION に等しい場合は、IDirectInputDevice8::EnumEffects メソッドで取得したほかの任意の GUID を渡すことができる。この方法を使えば、業者が設計したハードウェア特有の条件を使用することができる。

条件のタイプ固有構造体は DICONDITION である。複数軸の条件では、1 つの軸に対して複数の構造体からなる配列を使用するか、または特定の方向での条件を定義する 1 つの構造体を使用することができる。どちらの場合でも、DIEFFECT 構造体の cbTypeSpecificParams メンバに、使用するバイト数を設定する必要がある。すなわち、sizeof(DICONDITION) * n を設定する必要がある。ここで n は使用する構造体の数を表す。1 つあるいは複数の構造体を使用する方法の詳細については、DICONDITION 構造体の説明を参照すること。

エフェクトの係数と飽和について正と負の両方がデバイスでサポートされているかどうかを確認するには、アプリケーションで IDirectInputDevice8::GetEffectInfo メソッドまたは IDirectInputDevice8::EnumEffects メソッドを呼び出し、DIEFFECTINFO 構造体の dwEffectType メンバを調べなければならない。エフェクトが DIEFT_POSNEGCOEFFICIENTS フラグを返さなければ、lNegativeCoefficient メンバの値は無視され、lPositiveCoefficient の値が軸全体に適用される。同様に、エフェクトが DIEFT_POSNEGSATURATION フラグを返さなければ、dwNegativeSaturation の値は無視され、dwPositiveSaturation の値が負の飽和レベルとして使用される。また、エフェクトが DIEFT_SATURATION フラグを返さなければ、dwPositiveSaturation と dwNegativeSaturation の両方の値が無視され、飽和は適用されない。

また、DIEFFECTINFO.dwEffectType に DIEFT_DEADBAND フラグが設定されているかどうかをチェックすることで、デッドバンドが条件に対してサポートされているかどうかを知ることができる。サポートされていない場合、DICONDITION 構造体の lDeadBand メンバの値は無視される。

係数には負数を設定することができる。こうすると、エフェクトは反対方向のフォースを生成する。たとえばスプリング エフェクトでは、係数に負数を設定すると、スプリング エフェクトはオフセット ポイントに向かって引っ張らずに、オフセット ポイントから離れる方向へ押すことになる。


カスタム フォース

アプリケーションの作成者は、カスタム フォースを作成することによって、独自のエフェクトを作成することができる。カスタム フォースは、デバイスが再生するコンスタント フォース値の配列である。

カスタム波形エフェクトのタイプ固有構造体は、DICUSTOMFORCE である。

DICUSTOMFORCE 構造体の dwSamplePeriod メンバと DIEFFECT 構造体の dwSamplePeriod メンバには同じ値を設定しなければならない。この値はミリ秒単位の時間であり、フォースの配列の各要素が再生される時間を表す。

DIEFFECT の dwDuration メンバに設定された時間が過ぎるまで、カスタム フォースは繰り返し働く。


デバイス エフェクト

ハードウェア ドライバは、Microsoft® DirectInput® が定義するカテゴリに当てはまらない特殊効果をサポートすることができる。このようなエフェクトに対応するタイプ固有のパラメータは、ハードコーディングされていることもあれば、アプリケーションで変更できることもある。

タイプ固有のパラメータが変更可能な場合、アプリケーション開発者は、エフェクトにより要求されるデータ構造を宣言しているヘッダー ファイルを取得しなければならない。

ハードウェア ベンダーは、そのデバイス固有エフェクトを識別する GUID を提供しなければならない。またハードウェア ベンダーは、そのエフェクトに対するタイプ固有パラメータ用の特別な構造体を提供することもある。次に、アプリケーションは、DIEFFECT 構造体とそのエフェクトに対するタイプ固有構造体を、ほかのどのエフェクトでも同様だが、初期化しなければならない。次に、IDirectInputDevice8::CreateEffect メソッドを呼び出し、デバイス GUID と DIEFFECT 構造体へのポインタを渡す。

DIEFFECTINFO 構造体にデバイス エフェクトについての情報が入るが、そのメンバ dwEffType (DIEFT_GETTYPE(dwEfftype)) の下位バイトは、定義済みの DirectInput のエフェクトタイプ (コンスタント フォース、傾斜フォース、周期的エフェクト、条件) のどれにデバイス エフェクトが分類されるのかを示している。定義済みのカテゴリのどれにも分類できない場合、下位バイトの値は DIEFT_HARDWARE である。

デバイス固有のエフェクトが定義済みのいずれかの種類に分類できれば、DIEFFECT 構造体の lpvTypeSpecificParams メンバはその種類に応じて、DICONSTANTFORCE 構造体、DIRAMPFORCE 構造体、DIPERIODIC 構造体、または DICONDITION 構造体を指し、cbTypeSpecificParams メンバはその構造体のサイズと同じ値でなくてはならない。

DIEFT_GETTYPE(dwEfftype) の値が DIEFT_HARDWARE であれば、lpvTypeSpecificParams メンバおよび cbTypeSpecificParams メンバの値は、そのエフェクトが特別なタイプ固有パラメータを必要としているかどうかによって決まる。特別なパラメータを必要とするときは、この 2 つのメンバの値は、メーカーのヘッダー ファイルで定義され、各自のアプリケーションで宣言および初期化された、適切な構造体を指さなくてはならない。そのエフェクトが特別なパラメータを必要としない場合、すなわち、ハードウェア エフェクト用の DIEFFECTINFO 構造体の dwStaticParms メンバに DIEP_TYPESPECIFICPARAMS フラグがないときは、lpvTypeSpecificParams は NULL で、cbTypeSpecificParams はゼロでなければならない。

DirectInput は確認のため、GUID と DIEFFECT 構造体をデバイス ドライバに渡す。GUID が未知である場合、デバイスは DIERR_DEVICENOTREG を返す。GUID は既知でも、タイプ固有データがそのエフェクトに対して不正確である場合は、デバイスは DIERR_INVALIDPARAM を返す。


プログラミングのヒントとツール

このセクションでは、特殊なプログラミング トピックと、Microsoft® DirectX® SDK 付属ツールの概要について説明する。この情報は、DirectInput® データの理解と、フォース フィードバック エフェクトの設計に役立つ。

以下のトピックに分けて、説明する。

  • 前バージョンの DirectInput 用の設計
  • デバッグ時の応答遅延の防止
  • Force Editor


前バージョンの DirectInput 用の設計

DirectInput8Create、IDirectInput8::Initialize、IDirectInputDevice8::Initialize、および IDirectInputEffect::Initialize メソッドでは、Microsoft® DirectInput® のバージョン番号を渡す必要がある。このパラメータは、DirectInput サブシステムがどのバージョンの Microsoft DirectX® をエミュレートするかを指定する。

最新バージョンの DirectInput 用に設計されたアプリケーションは、Dinput.h で定義されている DIRECTINPUT_VERSION 値を渡す必要がある。

以前のバージョンで実行するように設計されたアプリケーションでは、設計対象の DirectInput のバージョンに対応した値、すなわち高次バイトにメイン バージョン番号をつけた値を渡す必要がある。たとえば、DirectInput 3.0 上で動作するように設計されたアプリケーションは、0x0300 を渡す必要がある。

Dinput.h ヘッダー ファイルをインクルードする前に、DIRECTINPUT_VERSION を 0x0300 と定義すると、このヘッダー ファイルは DirectInput 3.0 と互換性を持つ構造体定義を生成する。

Dinput.h ヘッダー ファイルをインクルードする前に DIRECTINPUT_VERSION を定義しないと、Dinput.h ヘッダー ファイルは DirectInput の現行バージョンと互換性のある構造体定義を生成する。しかし、DirectX 3 と互換性のある構造体も、その名前に "_DX3" を付ければ使用することができる。たとえば、DirectX 3 と互換性のある DIDEVCAPS 構造体は DIDEVCAPS_DX3 と名付けられることになる。

また、DirectInput インターフェイスと DirectInputDevice インターフェイスの適切なバージョンを使用する必要がある。DirectX 7.0 より前のバージョンの DirectX では、IDirectInput と、IDirectInputDevice または IDirectInputDevice2 のどちらかを使用する必要がある (後者は DirectX 5.0 以降のバージョンで利用可能)。


デバッグ時の応答遅延の防止

Microsoft Windows® 2000 のもと、Microsoft® DirectInput® でキーボードまたはマウスを使用する場合、デバッグ セッション中にコードを実行すると短期間の遅延が発生する場合がある。この現象はデバック モードでのみ発生する。実際のアプリケーションでは発生しない。ただし、Emulation 値を次のレジストリ キーに追加することで、デバック モードでもこの遅延が発生しないようにすることができる。

HKEY_LOCAL_MACHINE
    SOFTWARE
        Microsoft
            DirectInput

名前 | 型 | データ
Emulation | DWORD | 0x08 (マウス用) 0x10 (キーボード用) 0x18 (マウスおよびキーボード用)

これらの値を設定すると、DirectInput がデータを返す方法を変更することなく、遅延に影響されないエミュレーション モードを起動することができる。Microsoft Software Development Kit (SDK) には、Mouse and Keyboard Emulation On.reg および Mouse and Keyboard Emulation Off.reg の 2 つのレジストリ ファイルが付属していて、遅延に影響されないエミュレーション モードの起動と終了を指定することができる。これらのファイルは、(SDK ルート)\Samples\Multimedia\DirectInput\Bin に保存されている。

注 : Emulation 値は、デバイスがデバッグ モードの排他フォアグラウンド協調レベルで使用されている場合にのみサポートされる。


Force Editor

説明

Force Editor アプリケーションを使うと、フォース フィードバック エフェクトをデザインしたり、そのエフェクトを単独でテストしたり、いくつかのエフェクトを組み合わせてテストしたりすることができる。エフェクトは、ファイルに保存して、Microsoft® DirectInput® アプリケーションに読み込ませることができる。

パス

実行可能ファイル :(SDK ルート)\Bin\Dxutils\Fedit.exe

ユーザーズ ガイド

Force Editor には専用のドキュメントが添付している。Fedit.exe を起動し、F1 キーを押すとオンライン ヘルプを参照することができる。以下のファイルをダブルクリックして、オンライン ヘルプを直接起動することもできる。

(SDK ルート)\Bin\Dxutils\Fedit.chm


DirectInput C/C++ チュートリアル

ここでは、5 つのチュートリアルを使用して、Microsoft® DirectInput® の基本的な機能を C または C++ アプリケーションに実装する方法をステップ バイ ステップで説明する。

  • チュートリアル 1 : キーボードの使い方

    最初のチュートリアルは、既存のアプリケーションに DirectInput キーボード サポートを追加する手順を示す。

  • チュートリアル 2 : マウスの使い方

    2 番目のチュートリアルは、アプリケーションで DirectInput マウス サポートを実現する手順を示す。このチュートリアルは、Scrawl サンプルをベースにしており、バッファリング データに焦点を当てる。

  • チュートリアル 3 : ジョイスティックの使い方

    このチュートリアルは、システムに接続されているジョイスティックを列挙する方法、コールバック関数で DirectInput デバイス オブジェクトを作成して初期化する方法、および直接データを取得する方法を示す。サンプル コードは、Joystick サンプルがベースになっている。

  • チュートリアル 4 : フォース フィードバックの使い方

    このチュートリアルは、フォース フィードバック ジョイスティックでの単純なエフェクトの作成と操作について説明する。

  • チュートリアル 5 : アクション マッピングの使い方

    最後のチュートリアルは、アクション マップを作成して適用する方法について説明する。

注 これらのチュートリアルは、C++ スタイルの関数呼び出しを使って記述されている。C 環境における Microsoft DirectX® 関数呼び出しのプログラミングの詳細については、「C による COM オブジェクトへのアクセス」を参照すること。


チュートリアル 1 : キーボードの使い方

キーボード入力の準備を行うには、まず、Microsoft® DirectInput® オブジェクトのインスタンスを作成する。次に、IDirectInput8::CreateDevice メソッドを使用して、IDirectInputDevice8 インターフェイスのインスタンスを作成する。IDirectInputDevice8 インターフェイスの各メソッドは、デバイスの操作、デバイスの動作の設定、およびデータの取得を行うために使用する。

このチュートリアルでは、必要なタスクを以下の手順に分割している。

  • ステップ 1 : DirectInput オブジェクトの作成
  • ステップ 2 : DirectInput キーボード デバイスの作成
  • ステップ 3 : キーボードのデータ形式の設定
  • ステップ 4 : キーボードの動作の設定
  • ステップ 5 : キーボードへのアクセス権の取得
  • ステップ 6 : キーボードからのデータの取得
  • ステップ 7 : DirectInput システムの終了

DirectInput キーボード サポートをアプリケーションに追加するのは、比較的簡単なので、このチュートリアルは、完全な Keyboard サンプル アプリケーションにはなっていない。チュートリアルのすべての手順は、本文内のコードで具体的に示している。システムの初期化の関連手順は、「サンプル関数 1 : DI_Init」に集約されている。システムを終了させる必要がある場合は、もう 1 つの関数「サンプル関数 2 : DI_Term」が、呼び出される。これらの関数の内容の多くは、この後のチュートリアルでも再度使用される。


ステップ 1 : DirectInput オブジェクトの作成

Microsoft® DirectInput® システムのセットアップ手順の最初は、全体のマネージャとなる単一の DirectInput オブジェクトを作成することである。これを行うには、DirectInput8Create 関数を呼び出す。

// HINSTANCE g_hinst; // 以前に初期化済み。
HRESULT         hr;
LPDIRECTINPUT8  g_lpDI;

hr = DirectInput8Create(g_hinst, DIRECTINPUT_VERSION,
        IID_IDirectInput8, (void**)&g_lpDI, NULL);
if FAILED(hr)
{
    // DirectInput は利用可能ではない。 適切な処置をとる。
}

DirectInput8Create の第 1 パラメータは、オブジェクトを作成するアプリケーションまたは DLL のインスタンス ハンドルである。

第 2 パラメータは、どのバージョンの DirectInput システムを DirectInput オブジェクトに使用するかを指示する。以前のバージョンの DirectInput と互換性のあるアプリケーションを設計することもできる。詳細については、「前バージョンの DirectInput 用の設計」を参照すること。

第 3 パラメータは、どのインターフェイスが返されるかを指定する。ほとんどのアプリケーションは、IID_IDirectInput8 を渡すことによって最新のバージョンを取得する。

第 4 パラメータは、この呼び出しが成功した場合に、有効なインターフェイス ポインタで初期化される変数のアドレスである。

最後のパラメータには、COM 集成体で使用する制御オブジェクトの IUnknown インターフェイスのアドレスを指定する。ほとんどのアプリケーションでは集成体は使用されないため、通常の場合、このパラメータの値には NULL を設定する。

全体のマネージャとなる単一の DirectInput オブジェクトを作成したら、「ステップ 2 : DirectInput キーボード デバイスの作成」に進む。


ステップ 2 : DirectInput キーボード デバイスの作成

Microsoft® DirectInput® オブジェクトの作成後、アプリケーションはキーボード オブジェクト (デバイス) を作成し、IDirectInputDevice8 インターフェイスへのポインタを取得する必要がある。デバイスは、キーボード関連タスクの大部分を、このインターフェイスのメソッドを使って実行する。

このポインタを取得するには、「サンプル関数 1 : DI_Init」で示すように、IDirectInput8::CreateDevice メソッドを呼び出さなければならない。CreateDevice は、3 つのパラメータを取る。

第 1 パラメータは、作成するデバイスの GUID である。システム キーボードが使用されるため、アプリケーションは事前に定義されたグローバル変数を GUID_SysKeyboard に渡す。

第 2 パラメータは、呼び出しが成功した場合にインターフェイス ポインタで初期化される変数のアドレスである。

第 3 パラメータは、COM 集成体で使用する制御オブジェクトの IUnknown インターフェイスのアドレスである。ほとんどのアプリケーションでは集成体は使用されないため、通常の場合、このパラメータの値には NULL を設定する。

以下のコードは、IDirectInputDevice8 インターフェイスへのポインタを取得しようとする例である。失敗した場合には、DI_Term アプリケーション定義サンプル関数を呼び出し、既存の DirectInput オブジェクトがあればその割り当てを解除する。

注 すべての例の g_lpdi は、DirectInput オブジェクトに対する初期化されたポインタである。

HRESULT               hr;
LPDIRECTINPUTDEVICE8  g_lpDIDevice

hr = g_lpDI->CreateDevice(GUID_SysKeyboard, &g_lpDIDevice, NULL);
if FAILED(hr) {
    DI_Term();
    return FALSE;
}

DirectInput キーボード デバイスを作成したら、「ステップ 3 : キーボードのデータ形式の設定」に進む。


ステップ 3 : キーボードのデータ形式の設定

IDirectInputDevice8 ポインタを取得したら、「サンプル関数 1 : DI_Init」に示すように、アプリケーションでデバイスのデータ形式を設定する必要がある。キーボードの場合、これは非常に簡単なタスクである。Microsoft® DirectInput® に用意されているデータ形式を c_dfDIKeyboard グローバル変数に指定して、IDirectInputDevice8::SetDataFormat メソッドを呼び出す。

以下のコードは、データ形式を設定しようとする例である。失敗した場合には、DI_Term サンプル関数を呼び出し、既存の DirectInput オブジェクトがあればその割り当てを解除する。

hr = g_lpDIDevice->SetDataFormat(&c_dfDIKeyboard);

if FAILED(hr) {
    DI_Term();
    return FALSE;
}

キーボードのデータ形式を設定したら、「ステップ 4 : キーボードの動作の設定」に進む。


ステップ 4 : キーボードの動作の設定

アプリケーションでは、キーボードにアクセスする前に、IDirectInputDevice8::SetCooperativeLevel メソッドを使用して、「サンプル関数 1 : DI_Init」に示すように、デバイスの動作を設定する必要がある。このメソッドは、デバイスに関連付けられたウィンドウへのハンドルと、協調レベルを決定するフラグの組み合わせを受け取る。この場合、アプリケーションはフォアグラウンドの非排他アクセスを要求している。

以下のコードは、デバイスの協調レベルを設定しようとする例である。失敗した場合には、DI_Term アプリケーション定義サンプル関数を呼び出し、既存の Microsoft® DirectInput® オブジェクトがあればその割り当てを解除する。

// 協調レベルを設定する。
hr = g_lpDIDevice->SetCooperativeLevel(g_hwndMain,
                   DISCL_FOREGROUND | DISCL_NONEXCLUSIVE);

if FAILED(hr) {
    DI_Term();
    return FALSE;
}

キーボードの動作を設定したら、「ステップ 5 : キーボードへのアクセス権の取得」に進む。


ステップ 5 : キーボードへのアクセス権の取得

キーボードの動作を設定したら、アプリケーションは、IDirectInputDevice8::Acquire メソッドを呼び出して、デバイスに対するアクセス権を取得できる。アプリケーションは、デバイスからデータを取得する前に、デバイスを取得しなければならない。Acquire メソッドには、パラメータはない。

次のサンプル コードは、「ステップ 2 : DirectInput キーボード デバイスの作成」で作成したキーボード デバイスを取得するサンプル コードを示している。

if (g_lpDIDevice) g_lpDIDevice->Acquire();

アプリケーションがキーボードへのアクセス権を取得したら、「ステップ 6 : キーボードからのデータの取得」に進む。


ステップ 6 : キーボードからのデータの取得

デバイスを取得すれば、アプリケーションは、デバイスからのデータの取得を開始できる。データを取得する最も簡単な方法は、IDirectInputDevice8::GetDeviceState メソッドを呼び出すことである。このメソッドは、デバイスを呼び出したときの瞬間の状態を取得する。

GetDeviceState メソッドは 2 つのパラメータを取る。デバイス状態データが設定されるバッファのサイズと、そのバッファへのポインタである。キーボードの場合は、常に、符号なし 256 バイトのバッファを宣言する。

以下のコードは、キーボードの状態を取得しようとする例である。取得に失敗した場合、アプリケーション定義のサンプル関数を呼び出し、既存の Microsoft® DirectInput® オブジェクトがあれば、その割り当てを解除する。「サンプル関数 2 : DI_Term」を参照すること。

キーボードの現在の状態を取得した後、アプリケーションは、呼び出し時に押された特定のキーに応答することができる。バッファ中の各要素が 1 つのキーを表す。要素の上位ビットが 1 の場合、そのキーは、呼び出し時に押されていたことを示す。それ以外の場合は、キーは押されていない。あるキーの状態をチェックするには、DirectInput のキーボード デバイス定数を使用して、そのキーに対するバッファのインデックスを作成する。

以下のコードは、ある仮想の宇宙船ゲームのメイン ループから呼び出されるスケルトン関数である。ここでは、IDirectInputDevice8::GetDeviceState メソッドを使用してキーボードをポーリングする。次に、デバイス状態を取得したときに、左向き矢印、右向き矢印、上向き矢印、または下向き矢印の各キーが押されたかどうかをチェックする。これを行うには、この関数の本体で定義されている KEYDOWN マクロを使用する。KEYDOWN マクロは、バッファの変数名とインデックス値を受け取った後、指定インデックスに位置するバイトをチェックして上位ビットが設定されているかどうかを調べ、設定されている場合には TRUE を返す。

void WINAPI ProcessKBInput()
{
    #define KEYDOWN(name, key) (name[key] & 0x80)

    char     buffer[256];
    HRESULT  hr;

    hr = g_lpDIDevice->GetDeviceState(sizeof(buffer),(LPVOID)&buffer);
    if FAILED(hr)
    {
         // 失敗の場合、デバイスは失われている。
         // (hr == DIERR_INPUTLOST) をチェックし、
         // 再取得を試みる必要がある。
         return;
    }

    // 船を右または左に向ける。
    if (KEYDOWN(buffer, DIK_RIGHT));
        // 右に向ける。
    else if(KEYDOWN(buffer, DIK_LEFT));
        // 左に向ける。

    // 船を進める、または停止させる。
    if (KEYDOWN(buffer, DIK_UP)) ;
        // 船を前進させる。
    else if (KEYDOWN(buffer, DIK_DOWN));
        // 船を停止させる。
}

アプリケーションがキーボードからのデータを取得したら、「ステップ 7 : DirectInput システムの終了」に進む。


ステップ 7 : DirectInput システムの終了

アプリケーションを終了する直前に、すべての Microsoft® DirectInput® オブジェクトを破棄する必要がある。これは 3 段階の処理から成る。

  • すべての DirectInput デバイスのアクセス権を解放する (IDirectInputDevice8::Unacquire)
  • すべての DirectInput デバイスを解放する (IDirectInputDevice8::Release)
  • DirectInput オブジェクトを解放する (IDirectInput8::Release)

DirectInput システムを終了させる関数のサンプルについては、「サンプル関数 2 : DI_Term」を参照すること。


サンプル関数 1 : DI_Init

このアプリケーション定義サンプル関数は、Microsoft® DirectInput® オブジェクトを作成して初期化し、必要なインターフェイス ポインタを取得して、それらのポインタをグローバル変数に割り当てる。初期化が完了したら、デバイスを取得する。

初期化のどの部分で失敗しても、この関数は、DI_Term アプリケーション定義サンプル関数を呼び出し、プログラムを終了する準備として、DirectInput オブジェクトとインターフェイス ポインタの割り当てを解除する (「サンプル関数 2 : DI_Term」を参照すること。

DI_Init 関数は、DirectInput オブジェクトを作成することに加えて、以下のチュートリアル手順で説明されているタスクを実行する。

  • ステップ 2 : DirectInput キーボード デバイスの作成
  • ステップ 3 : キーボードのデータ形式の設定
  • ステップ 4 : キーボードの動作の設定
  • ステップ 5 : キーボードへのアクセス権の取得

以下は、DI_Init 関数を示している。

/ * 次の変数は初期化済みと見なされる。
HINSTANCE             g_hinst;    // アプリケーション インスタンス。
HWND                  g_hwndMain; // アプリケーション ウィンドウ。
*/

LPDIRECTINPUT8        g_lpDI;
LPDIRECTINPUTDEVICE8  g_lpDIDevice;

BOOL WINAPI DI_Init()
{
    HRESULT hr;

    // DirectInput オブジェクトを作成する。
    hr = DirectInput8Create(g_hinst, DIRECTINPUT_VERSION,
                            IID_IDirectInput8, (void**)&g_lpDI, NULL);

    if FAILED(hr) return FALSE;

    // IDirectInputDevice8 インターフェイスへのポインタを取得する。
    hr = g_lpDI->CreateDevice(GUID_SysKeyboard, &g_lpDIDevice, NULL);

    if FAILED(hr)
    {
        DI_Term();
        return FALSE;
    }

    // IDirectInputDevice8 インターフェイスを保持して、
    // 使用準備が整ったところである。

    // キーボード用 DirectInput オブジェクトが作る、事前定義された
    // キーボード データ形式を用いて、データ形式を設定する。

    hr = g_lpDIDevice->SetDataFormat(&c_dfDIKeyboard);

    if FAILED(hr)
    {
        DI_Term();
        return FALSE;
    }

    // 協調レベルを設定する。
    hr = g_lpDIDevice->SetCooperativeLevel(g_hwndMain,
                             DISCL_FOREGROUND | DISCL_NONEXCLUSIVE);
    if FAILED(hr)
    {
        DI_Term();
        return FALSE;
    }

    // 入力デバイスにアクセスする。
    hr = g_lpDIDevice->Acquire();
    if FAILED(hr)
    {
        DI_Term();
        return FALSE;
    }

    return TRUE;
}


サンプル関数 2 : DI_Term

このアプリケーション定義サンプル関数は、プログラムを終了する準備として、またはデバイスの正常な初期化が失敗した場合の処理として、既存の Microsoft® DirectInput® インターフェイス ポインタの割り当てを解除する。

/ * 次の変数は初期化済みとする。
LPDIRECTINPUT8        g_lpDI;
LPDIRECTINPUTDEVICE8  g_lpDIDevice;
*/

void WINAPI DI_Term()
{
    if (g_lpDI)
    {
        if (g_lpDIDevice)
        {
        // Release() を呼び出す前は常にデバイスを解放する。
            g_lpDIDevice->Unacquire();
            g_lpDIDevice->Release();
            g_lpDIDevice = NULL;
        }
        g_lpDI->Release();
        g_lpDI = NULL;
    }
}

その他の DirectInput チュートリアルについては、「DirectInput C/C++ チュートリアル」を参照すること。


チュートリアル 2 : マウスの使い方

このチュートリアルでは、マウス デバイスをセットアップし、入力のバッファリング データを取得する作業を順を追って説明する。この例は、Scrawl サンプルをベースにしている。

マウス入力の準備を行うには、まず、Microsoft® DirectInput® オブジェクトのインスタンスを作成する。次に、IDirectInput8::CreateDevice メソッドを使用して、IDirectInputDevice8 インターフェイスのインスタンスを作成する。IDirectInputDevice8 インターフェイスの各メソッドは、デバイスの操作、デバイスの動作の設定、およびデータの取得を行うために使用する。

DirectInput システムのセットアップの準備手順とシステムを終了する最後の手順は、どのアプリケーションでも同じであり、「チュートリアル 1 : キーボードの使い方」で説明している。

このチュートリアルでは、必要なタスクを以下の手順に分割している。

  • ステップ 1 : DirectInput マウス デバイスの作成
  • ステップ 2 : マウスのデータ形式の設定
  • ステップ 3 : マウスの動作の設定
  • ステップ 4 : マウスからのバッファリング データ入力の準備
  • ステップ 5 : マウスへのアクセス権の管理
  • ステップ 6 : マウスからのバッファリング データの取得

注 アプリケーションが排他協調レベルでマウスを取得しているとき、Microsoft Windows® はマウス ポインタを画面に表示しない。このため、アプリケーションには、簡単なスプライト エンジンが必要となる。Scrawl サンプル アプリケーションでは、Microsoft Win32® 関数の DrawIcon を使用して十字カーソルを画面に表示する。


ステップ 1 : DirectInput マウス デバイスの作成

Microsoft® DirectInput® オブジェクトを作成すると、アプリケーションは、マウス関連タスクの大半を実行するために使う IDirectInputDevice8 インターフェイスへのポインタを取得する必要がある。このポインタを取得するには、IDirectInput8::CreateDevice メソッドを呼び出す。

CreateDevice の第 1 パラメータは、アプリケーションが作成しようとしているデバイスの GUID (グローバル ユニーク識別子) 値である。この場合はシステム マウスを使用するので、アプリケーションは、事前定義されたグローバル変数の GUID_SysMouse を渡す必要がある。

第 2 パラメータは、この呼び出しが成功した場合に、有効な IDirectInputDevice8 インターフェイス ポインタで初期化される変数のアドレスである。

第 3 パラメータは、COM 集成体で使用する制御オブジェクトの IUnknown インターフェイスのアドレスである。大部分のアプリケーションでは集成体は使用されないため、通常の場合、このパラメータの値には NULL を設定する。

以下のコードは、IDirectInputDevice8 インターフェイスへのポインタを取得しようとする例である。呼び出しが失敗すれば、FALSE が返される。g_pDI は、IDirectInput8 への有効なポインタであると仮定する。

LPDIRECTINPUTDEVICE g_pMouse;
HRESULT             hr;

hr = g_pDI->CreateDevice(GUID_SysMouse, &g_pMouse, NULL);

if (FAILED(hr)) {
    return FALSE;
}

DirectInput マウス デバイスを作成したら、「ステップ 2 : マウスのデータ形式の設定」に進む。


ステップ 2 : マウスのデータ形式の設定

IDirectInputDevice8 ポインタを取得したら、デバイスのデータ形式を設定しなければならない。マウスの場合、これは非常に簡単なタスクである。作業を簡便にするため Microsoft® DirectInput® に用意されているデータ形式を、c_dfDIMouse グローバル変数に指定して IDirectInputDevice8::SetDataFormat メソッドを呼び出す。

以下は、デバイスのデータ形式を設定しようとするコードである。呼び出しが失敗すれば、FALSE が返される。

hr = g_pMouse->SetDataFormat(&c_dfDIMouse);

if (FAILED(hr)) {
    return FALSE;
}

マウスのデータ形式を設定したら、「ステップ 3 : マウスの動作の設定」に進む。


ステップ 3 : マウスの動作の設定

アプリケーションがマウスに対するアクセス権を取得できるようにするには、前もって、IDirectInputDevice8::SetCooperativeLevel メソッドを使用してマウス デバイスの動作を設定しなければならない。このメソッドは、デバイスに関連付けられたウィンドウのハンドルを受け取る。Scrawl では、DISCL_EXCLUSIVE フラグが指定されているので、マウス デバイスに対する排他アクセス権を持つのは、このアプリケーションのみであるということが保証される。Scrawl は、別のアプリケーションがフォアグラウンドにあるときはデータ入力を受け入れないため、このフラグは DISCL_FOREGROUND と組み合わせて使用する。

以下のコードは、デバイスの協調レベルを設定しようとする例である。設定に失敗すれば、FALSE が返される。hWnd は有効なウィンドウ ハンドルと仮定する。

hr = g_pMouse->SetCooperativeLevel(hWnd,
               DISCL_EXCLUSIVE | DISCL_FOREGROUND);

if (FAILED(hr)) {
    return FALSE;
}

マウスの動作を設定したら、「ステップ 4 : マウスからのバッファリング データ入力の準備」に進む。


ステップ 4 : マウスからのバッファリング データ入力の準備

Scrawl アプリケーションは、イベント通知を使用してマウスの動作を検出する方法、およびマウスからのバッファリング入力を読み取る方法を示している。この方法はどちらも、ある程度のセットアップを必要とする。それらの手順は、マウス デバイスの作成後で、マウス デバイスの取得前であればいつでも実行できる。

まず、イベントを作成し、マウス デバイスと関連付ける。これにより、新たな有効データが発生したことを示すハードウェア割り込みがあれば、いつでもマウス デバイス オブジェクトに通知するように、Microsoft® DirectInput® に指示していることになる。

以下は Scrawl での処理方法である。ここで、g_hevtMouse はグローバル HANDLE である。

g_hMouseEvent = CreateEvent(NULL, FALSE, FALSE, NULL);

if (g_hMouseEvent == NULL) {
    return FALSE;
}

hr = g_pMouse->SetEventNotification(g_hMouseEvent);

if (FAILED(hr)) {
    return FALSE;
}

この段階でバッファ サイズを設定する必要がある。これは、プログラムが入力データを参照する用意ができるまで、DirectInput があらゆる入力データを格納できるようにするためである。デフォルトのバッファ サイズはゼロであるため、バッファリング データを使用するにはこの手順が不可欠であることに注意する。

イベント通知にバッファリング データを使用する必要はない。必要であれば、イベントが送信されたときに直接データを取得することができる。

バッファ サイズを設定するには、DIPROPDWORD 構造体を、構造体自体についての情報と、設定したいプロパティについての情報で初期化する。ほとんどの値は定型的なものである。重要な値は最後の dwData であり、これはバッファが保持する項目数に初期化する。

#define SAMPLE_BUFFER_SIZE  16

DIPROPDWORD dipdw;
    // ヘッダー
    dipdw.diph.dwSize       = sizeof(DIPROPDWORD);
    dipdw.diph.dwHeaderSize = sizeof(DIPROPHEADER);
    dipdw.diph.dwObj        = 0;
    dipdw.diph.dwHow        = DIPH_DEVICE;
    // データ
    dipdw.dwData            = SAMPLE_BUFFER_SIZE;

次に、ヘッダー (DIPROPDWORD 構造体内の DIPROPHEADER 構造体) のアドレスと、変更したいプロパティの識別子を、次のように IDirectInputDevice8::SetProperty メソッドに渡す。

hr = g_pMouse->SetProperty(DIPROP_BUFFERSIZE, &dipdw.diph);

if (FAILED(hr)) {
    return FALSE;
}

これでセットアップは完了し、いつでもマウスを取得してデータの収集を始められる。

アプリケーションでのマウスからのバッファリング データ入力の準備が終わったら、「ステップ 5 : マウスへのアクセス権の管理」に進む。


ステップ 5 : マウスへのアクセス権の管理

Microsoft® DirectInput® は、デバイスのアクセス権を管理するために、IDirectInputDevice8::Acquire および IDirectInputDevice8::Unacquire メソッドを提供する。アプリケーションは、まず Acquire メソッドを呼び出し、デバイスに対するアクセス権を取得しなければならない。次に、IDirectInputDevice8::GetDeviceState メソッドと IDirectInputDevice8::GetDeviceData メソッドを使用して、マウス情報を要求する。

ほとんどの場合、アプリケーションには取得された状態のデバイスがある。しかし、フォアグラウンド アクセスしか持たない場合は、アプリケーションがバックグラウンドに移行すると必ずマウスは解放される。フォーカスが戻った場合には、確実にデバイスを再取得する必要がある。これは、WM_ACTIVATE メッセージに反応することで行うことができる。

Scrawl では、アプリケーションがフォーカスを取得するのか、または失うのかに合わせて、グローバル変数の g_bActive を設定することで、このメッセージを処理している。次に、ヘルパー関数の SetAcquire を呼び出す。このヘルパー関数は、g_bActive が TRUE の場合にマウスを取得し、そうでない場合にはマウスを解放する。

case WM_ACTIVATE:
    if (WA_INACTIVE == wParam)
        g_bActive = FALSE;
    else
        g_bActive = TRUE;

    // アクティブ状態に基づいてマウスへの排他モード アクセスを設定する。
    SetAcquire();
    return 0;

排他モードでアクセスしている場合、アプリケーションはマウスを解放し、ユーザーと Microsoft Windows® との対話 (メニューやダイアログ ボックスへのアクセスなど) を可能にする必要がある。Scrawl では、Alt キーと Space キーを同時に押すことで、ユーザーがシステム メニューを開くことができる。

Scrawl のウィンドウ プロシージャは、WM_ENTERMENULOOP に対するハンドラを持っている。このハンドラは、グローバル変数 g_bActive に FALSE を設定して SetAcquire 関数を呼び出すことで応答する。このハンドラを使うと、Windows はマウスを保持し、独自のカーソルを表示することができる。

ユーザーがメニューの使用を終了すると、Windows はアプリケーションに WM_EXITSIZEMOVE メッセージを送る。この場合、Scrawl のウィンドウ プロセスは適切に g_bActive を設定し、SetAcquire を呼び出す。

また、Scrawl は、ショートカット メニューを開く右ボタン クリックに応答して、マウスを解放する。マウスは遅れて解放されるが、WM_ENTERMENULOOP ハンドラでは、メニューが表示される前に Windows カーソルの位置を設定できるように、最初にマウスを解放している。

最後に、Scrawl は、データの取得を試みて DIERR_INPUTLOST エラーが返されたら、マウスの再取得を試みる。これは、ほかの箇所では処理されない方法によってデバイスが解放された場合への備えである。たとえば、ユーザーが Ctrl + Alt + Del キーを押した場合などである。

まとめると、アプリケーションは、マウスからデータを取得する前に、マウスを取得する必要がある。マウスの取得は、アプリケーションに強制的にマウスのアクセス権を放棄させる事態が発生しない限り、一度だけ行えば済む。排他モードでは、Windows がマウスを必要とするときに、マウスの制御を放棄しなければならない。また、マウスのアクセス権を Windows またはその他のアプリケーションに譲った後、マウスに対するアクセス権が必要になった場合は、マウスを再取得しなければならない。

アプリケーションがマウスのアクセス権を管理したら、「ステップ 6 : マウスからのバッファリング データの取得」に進む。


ステップ 6 : マウスからのバッファリング データの取得

マウスを取得すれば、アプリケーションは、マウスからのデータの取得を開始することができる。

Scrawl サンプルでは、データ取得は、通知されたイベントがトリガとなる。シグナルやメッセージがあることが MsgWaitForMultipleObjects から示されるまで、アプリケーションは、WinMain 関数の中でスリープ状態に入る。マウス関連のシグナルがあれば、OnMouseInput 関数が呼び出される。この関数は、次のプロセスで示すように、バッファリング データ入力の処理方法を示すよい例である。

まず、この関数は、元のカーソル位置が完全に消去されていることを確認する。Scrawl は独自のカーソルを維持し、その描画や消去に対して全面的に責任を持つ。

VOID OnMouseInput(HWND hWnd)
{
    /* 元のカーソルを消去するため、無効にする。*/
    InvalidateCursorRect(hWnd);

ここで、関数はループに入り、バッファの全内容に対する読み取りおよび応答を行う。データは一度に 1 項目しか取得できないので、データを保持するためには、DIDEVICEOBJECTDATA 構造体が 1 つだけあればよい。

    while (!bDone) {
        DIDEVICEOBJECTDATA od;
        DWORD dwElements = 1;   // 取得すべき項目数

注 入力処理にはこのほかにも、バッファ全体を一度に読み取った後、ループで取得項目を順に 1 つずつ応答していく方法がある。その場合は、dwElements をバッファ サイズとし、od はそのサイズに等しい数の要素を持つ配列とする。

アプリケーションは、データを取得するために IDirectInputDevice8::GetDeviceData メソッドを呼び出す。第 2 パラメータはデータを置く位置を、第 3 パラメータは必要な項目数を、Microsoft® DirectInput® にそれぞれ通知する。データをバッファに残しておく場合は、最後のパラメータを DIGDD_PEEK とする。ただし、この場合は、データを再度必要とすることはないので削除する。

        hr = g_pMouse->GetDeviceData(sizeof(DIDEVICEOBJECTDATA),
                                     &od, &dwElements, 0);

ここで、アプリケーションは、デバイスに対するアクセス権が失われているかどうかの確認チェックを行い、失われていればすぐに最初のチャンスでマウスの再取得を行おうとする。この手順は、「ステップ 5 : マウスへのアクセス権の管理」で説明する。

        if (hr == DIERR_INPUTLOST)
        {
            SetAcquire();
            break;
        }

次に、アプリケーションは、GetDeviceData メソッドの呼び出しが成功したこと、および取得するデータが実際に存在したことを確認する。GetDeviceData の呼び出し後、変数 dwElements は実際に取得した項目数を示していることに注意する。

        /* データが読めない、または利用可能データがない。*/
        if (FAILED(hr) || dwElements == 0)
        {
            break;
        }

ここまでのプロセスが終了した場合、呼び出しは成功し、バッファにはデータの項目が入っている。ここで、アプリケーションは、DIDEVICEOBJECTDATA 構造体の dwOfs メンバを調べ、デバイス上のどのオブジェクトが状態変化を報告したかを確認する。次に、ヘルパー関数を呼び出し、適切に対応する。これらの関数には dwData メンバが渡される。このメンバはデバイス オブジェクトに何が発生したかを格納する。

        /* 要素を調べて何が発生したかを確認する。*/

        switch (od.dwOfs)
        {
            // マウスの水平動作。
            case DIMOFS_X:
                UpdateCursorPosition(od.dwData, 0);
                break;

            // マウスの垂直動作。
            case DIMOFS_Y:
                UpdateCursorPosition(0, od.dwData);
                break;

            // DIMOFS_BUTTON0:右ボタンが押された、または離された。
            case DIMOFS_BUTTON0:
            // DIMOFS_BUTTON1:左ボタンが押された、または離された。
            case DIMOFS_BUTTON1:
                // 右ボタンまたはスワップされた左ボタンが押し下げられているか。
                if((g_bSwapMouseButtons &&
                               DIMOFS_BUTTON1 == od.dwOfs) ||
                   (!g_bSwapMouseButtons &&
                               DIMOFS_BUTTON0 == od.dwOfs))
                {
                    if (od.dwData & 0x80)  // 左ボタンが押されているため、
                                           // ボタン押下モードになる。
                    {
                        bDone = TRUE;
                        OnLeftButtonDown(hWnd);
                    }
                // 左ボタンまたはスワップされた右ボタンが押し下げられているか。
                if((g_bSwapMouseButtons &&
                               DIMOFS_BUTTON0 == od.dwOfs) ||
                   (!g_bSwapMouseButtons &&
                               DIMOFS_BUTTON1 == od.dwOfs))
                {
                    if(!(od.dwData & 0x80))  // ボタンが離されているため、
                                             // ショートカット メニューをチェックする。
                    {
                        bDone = TRUE;
                        OnRightButtonUp(hWnd);
                    }
                }
                break;
        }

最後に、ヘルパー関数の 1 つによってカーソルが移動された場合、OnMouseInput サンプル関数がカーソルが占有している画面の四角形を無効にする。

    // 新しいカーソルが描画されるので無効にする。
    InvalidateCursorRect(hWnd);
}

また、Scrawl は、OnLeftButtonDown 関数にあるマウス データを集める。これは、主ボタンが押下されている間、つまり、ユーザーが描画している間のマウス移動を、アプリケーションが追跡する関数である。この関数は、イベント通知には依存しないが、ボタンが離されるまで、連続的に DirectInput バッファをポーリングする。

OnLeftButtonDown 関数では、待機中のデータがすべて読み込まれるまで描画は行われないことに注意する。これは、マウスの水平方向と垂直方向の移動が、独立したイベントとして報告されるためである (ただし、両イベントのバッファへの配置は同時に行われる)。独立したそれぞれの軸移動に反応して直線が直ちに描画される場合、マウスを斜めに動かすと、直角に交わる 2 直線が描画されることになる。

アプリケーションの応答前に、両軸における移動が計算に入れられていることを確認するには、x 軸項目と y 軸項目のシーケンス番号をチェックする方法もある。番号が同一であれば、2 つのイベントが同時に発生したことになる。詳細については、「タイム スタンプとシーケンス番号」を参照すること。

その他の DirectInput チュートリアルについては、「DirectInput C/C++ チュートリアル」を参照すること。


チュートリアル 3 : ジョイスティックの使い方

このチュートリアルは、システムにアタッチされたジョイスティックを列挙し、入力に対して設定する方法を示す。サンプル コードは、Joystick サンプルがベースになっている。

Microsoft® DirectInput® システムの設定の準備手順と、システムを終了する最後の手順は、どのアプリケーションでも同じであり、「チュートリアル 1 : キーボードの使い方」で説明している。

このチュートリアルの最初の手順は、デバイスを列挙すること、つまり、使用可能なジョイスティックを確認することである。この処理の一部として、各ジョイスティック デバイスを初期化し、必要な特性を設定する。次に、IDirectInputDevice8 インターフェイス メソッドを使用して、各ジョイスティックからデータを取得する。

このチュートリアルでは、必要なタスクを以下の手順に分割している。

  • ステップ 1 : ジョイスティックの列挙
  • ステップ 2 : DirectInput ジョイスティック デバイスの作成
  • ステップ 3 : ジョイスティックのデータ形式の設定
  • ステップ 4 : ジョイスティックの動作の設定
  • ステップ 5 : ジョイスティックへのアクセス権の取得
  • ステップ 6 : ジョイスティックからのデータの取得


ステップ 1 : ジョイスティックの列挙

Microsoft® DirectInput® システムを作成した後、次のサンプル コードに示すように、IDirectInput8::EnumDevices メソッドを呼び出してジョイスティックを列挙する。

// g_pDI は、IDirectInput8 への初期化済みのポインタである。

g_pDI->EnumDevices(DI8DEVCLASS_GAMECTRL, EnumJoysticksCallback,
                       NULL, DIEDFL_ATTACHEDONLY)

定数 DI8DEVCLASS_GAMECTRL が最初のパラメータとして渡され、列挙するデバイスのクラスを指定する。

EnumJoysticksCallback は、ジョイスティックが見つかるたびに呼び出されるコールバック関数のアドレスである。「ステップ 2 : DirectInput ジョイスティック デバイスの作成」では、このアドレスで各デバイスを作成する。

第 3 パラメータは、コールバック関数が使用できる任意の 32 ビット値である。この場合は、何も送られない。

最後のパラメータの DIEDFL_ATTACHEDONLY は、列挙対象をコンピュータにアタッチされているデバイスに限定するフラグである。

ジョイスティックが列挙できたら、「ステップ 2 : DirectInput ジョイスティック デバイスの作成」に進む。


ステップ 2 : DirectInput ジョイスティック デバイスの作成

Microsoft® DirectInput® オブジェクトを作成した後は、IDirectInputDevice8 インターフェイスへのポインタを取得する必要がある。このインターフェイスは、ジョイスティック関連タスクの大半で使用される。Joystick サンプルでは、コールバック関数 EnumJoysticksCallback でこのポイントを取得する。この関数は、ジョイスティックを列挙するたびに呼び出される。

次のサンプル コードは、このコールバック関数の最初の部分である。

BOOL CALLBACK EnumJoysticksCallback(const DIDEVICEINSTANCE*
                                       pdidInstance, VOID* pContext)
{
    HRESULT hr;

    // 列挙されたジョイスティックへのインターフェイスを取得する。
    hr = g_pDI->CreateDevice(pdidInstance->guidInstance,
                                &g_pJoystick, NULL);
    if(FAILED(hr))
        return DIENUM_CONTINUE;

    return DIENUM_STOP;

EnumJoysticksCallback コールバック関数のパラメータを次に示す。

  • デバイス インスタンスへのポインタ。インスタンスは、デバイスが列挙されたときに DirectInput システムによって供給される。
  • IDirectInput8::EnumDevices にパラメータとして指定した 32 ビット値へのポインタ。このパラメータには、メソッドを使用できるインターフェイスへのポインタであれば、任意の 32 ビット値を指定することもできる。しかし、この例では NULL が渡されている。

コールバック関数の最初のタスクは、デバイスを作成することである。IDirectInput8::CreateDevice メソッドは、3 つのパラメータを取る。

第 1 パラメータは、デバイスのインスタンスのグローバル ユニーク識別子 (GUID) に対する参照値である。この場合、GUID は DirectInput がデバイスを列挙したときに与える DIDEVICEINSTANCE 構造体から取られる。

第 2 パラメータは、呼び出しが成功した場合に、有効なインターフェイス ポインタで初期化される変数のアドレスである。

第 3 パラメータは、COM 集成体で使用する制御オブジェクトの IUnknown インターフェイスのアドレスである。Joystick サンプルは集成体を使用しないため、このパラメータの値には NULL を設定する。

デバイス インターフェイスを作成できない場合は、コールバック関数から DIENUM_CONTINUE が返されることに注意する。このフラグは、列挙対象のデバイスが存在する限り、列挙を続行することを DirectInput に指示する。

ジョイスティック デバイスを作成したら、「ステップ 3 : ジョイスティックのデータ形式の設定」に進む。


ステップ 3 : ジョイスティックのデータ形式の設定

Microsoft® DirectInput® デバイスへのポインタを取得したら、IDirectInputDevice8 メソッドを呼び出して、そのデバイスを操作することができる。まず、ジョイスティックのデータ形式を設定する。この手順は不可欠である。この手順では、DirectInput に対して入力データの書式を設定する方法を指示する。

if (FAILED(hr = g_pJoystick->SetDataFormat(&c_dfDIJoystick2)))
    return hr;

IDirectInputDevice8::SetDataFormat メソッドのパラメータは、デバイスのデータのフォーマット方法に関する情報を格納する DIDATAFORMAT 構造体へのポインタのみである。ジョイスティックの場合、事前定義されたグローバル変数 c_dfDIJoystick2 を使用できる。この変数によって、データ取得のための DIJOYSTATE2 構造体の使用が有効になる。

ジョイスティックのデータ形式を設定したら、「ステップ 4 : ジョイスティックの動作の設定」に進む。


ステップ 4 : ジョイスティックの動作の設定

これまでに、ジョイスティック デバイスの作成とデバイスのデータ形式の設定が完了している。次は、デバイスの協調レベルを設定することである。前の手順と同様、g_pJoystick はデバイス インターフェイスへのポインタである。

if (FAILED(hr = g_pJoystick->SetCooperativeLevel(hDlg,
                    DISCL_EXCLUSIVE | DISCL_FOREGROUND)))
    return hr;

IDirectInputDevice8::SetCooperativeLevel の最初のパラメータはウィンドウのハンドルである。この例では、メイン プログラム ウィンドウとなるダイアログ ボックスへのハンドルが関数に渡される。

最後のパラメータは、必要な協調レベルを指定するフラグの組み合わせである。Joystick サンプルは、このサンプルがフォアグラウンド アプリケーションのときは、ジョイスティックからの入力のみを要求する。また、ジョイスティック サンプルがフォアグラウンドの場合、このアプリケーションがジョイスティックに排他的にアクセスする唯一のアプリケーションでなければならない。したがって、フラグは DISCL_EXCLUSIVE | DISCL_FOREGROUND に設定される。これらのフラグの詳細については、「協調レベル」を参照すること。

次の手順では、ジョイスティックの能力に関する情報を収集する。この情報には、軸やボタンなどのコントローラの数、フォース フィードバックのサポート、その他、ジョイスティックの動作やサポート オプションに関する詳細が含まれる。

DIDEVCAPS 構造体は、能力情報の保持に使用される。まず、DIDEVCAPS 構造体の dwSize メンバを初期化し、次にその構造体のアドレスが IDirectInputDevice8::GetCapabilities に送られる。次の例では、g_diDevCaps で以前に DIDEVCAPS 構造体が宣言されている。

g_diDevCaps.dwSize = sizeof(DIDEVCAPS);
if (FAILED(hr = g_pJoystick->GetCapabilities(&g_diDevCaps)))
    return hr;

この時点で、デバイスのデフォルトを使用することも、デバイス プロパティをカスタマイズすることもできる。Joystick サンプルは、ジョイスティックの軸を列挙し、IDirectInputDevice8::EnumObjects を呼び出して、各軸の範囲を設定する。

if (FAILED(hr = g_pJoystick->EnumObjects(EnumAxesCallback,
                                       (VOID*)hDlg, DIDFT_AXIS)))
    return hr;

EnumObjects メソッドの最初のパラメータ EnumAxesCallback は、列挙されたオブジェクトを必要に応じて処理するコールバック関数のアドレスである。

第 2 パラメータは、コールバック関数が使用できる任意の 32 ビット値である。ここでメイン ダイアログ ウィンドウへのハンドルを渡して表示を更新し、ジョイスティックにどの軸があるかを示すことができる。

最後のパラメータ DIDFT_AXIS は、コールバック関数にデバイスの軸だけを列挙するよう指定する。

サンプルでは、変更されたプロパティは、検出された軸またはスライダの範囲である (スライダは軸と見なされる) 。

範囲を設定することにより、返させたい軸の最大値と最小値が何であるかを DirectInput に指示することになる。例のように、x 軸に対して範囲 － 1,000 ～ ＋ 1,000 を設定すると、ジョイスティックが最左端にある場合には － 1,000 を、最右端にある場合には ＋ 1,000 を、中央にある場合には 0 をそれぞれ返すことを要求することになる。

次のサンプル コードは、列挙する軸の範囲を設定する。変数 pdidoi は、システムがコールバック関数に渡す DIDEVICEOBJECTINSTANCE 構造体のアドレスである。この変数には、現在列挙されようとしているオブジェクトに関する情報が格納されている。

DIPROPRANGE diprg;

diprg.diph.dwSize       = sizeof(DIPROPRANGE);
diprg.diph.dwHeaderSize = sizeof(DIPROPHEADER);
diprg.diph.dwHow        = DIPH_BYID;
diprg.diph.dwObj        = pdidoi->dwType;
diprg.lMin              = -1000;
diprg.lMax              = +1000;
.
.
hr = g_pJoystick->SetProperty(DIPROP_RANGE, &diprg.diph);
if (FAILED(hr))
    return DIENUM_STOP;

ここでは最初に、DIPROPRANGE 構造体 diprg を設定する。その構造体のアドレスは、IDirectInputDevice8::SetProperty メソッドに渡される。実際には、構造体自体のアドレスが渡されるのではなく、その最初のメンバのアドレスが渡される。最初のメンバとは、1 つの DIPROPHEADER 構造体である。詳細については、「デバイス プロパティ」を参照すること。

プロパティ ヘッダーは、以下の値で初期化される。

  • プロパティ構造体のサイズ
  • ヘッダー構造体のサイズ
  • dwObj メンバの解釈方法を示すフラグ
  • DIDEVICEOBJECTINSTANCE 構造体の dwType メンバにある値は、プロパティが変更されようとしているオブジェクトを示す。

DIPROPRANGE 構造体の lmin と lmax メンバに必要な範囲値を割り当てる。

アプリケーションは、ここで IDirectInputDevice8::SetProperty メソッドを呼び出す。最初のパラメータは、どのプロパティを変更するのかを示すフラグである。第 2 パラメータは、プロパティ構造体の DIPROPHEADER メンバのアドレスである。

ジョイスティックの動作を設定したら、「ステップ 5 : ジョイスティックへのアクセス権の取得」に進む。


ステップ 5 : ジョイスティックへのアクセス権の取得

ジョイスティックの動作を設定したら、アプリケーションは、IDirectInputDevice8::Acquire メソッドを呼び出して、デバイスに対するアクセス権を取得できる。アプリケーションは、デバイスからデータを取得する前に、デバイスを取得しなければならない。Acquire メソッドには、パラメータはない。

Joystick サンプルは、アプリケーションがアクティブになると、メッセージ ループで最初の取得を実行する。またこのループは、アプリケーションがフォーカスを失った後に再取得するときは、必ず、デバイスを自動的に再取得する。また、ジョイスティックへのアクセス権が失われた場合、またはアプリケーションが入力データを取得しようとしたときに DIERR_INPUTLOST エラーが返された場合にも、取得が実行される。これを、次のサンプル コードに示す。

hr = g_pJoystick->Poll();
if (FAILED(hr))
{
    hr = g_pJoystick->Acquire();
    while(hr == DIERR_INPUTLOST)
        hr = g_pJoystick->Acquire();
    return S_OK;
}

ジョイスティックへのアクセス権を取得できたら、「ステップ 6 : ジョイスティックからのデータの取得」に進む。


ステップ 6 : ジョイスティックからのデータの取得

アプリケーションでは、ジョイスティック軸の移動よりも、ジョイスティック軸の位置の方が重要であることが多いので、デバイスからは、バッファリング データよりも直接データを取得することがよく行われる。直接データは、IDirectInputDevice8::GetDeviceState でポーリングすることによって取得できる。デバイスの状態が変化したとき、すべてのデバイス ドライバが Microsoft® DirectInput® に通知するわけではないことに注意する。したがって、デバイスの状態を確認する前に IDirectInputDevice8::Poll メソッドを呼び出すことを勧める。

Joystick アプリケーションは、Microsoft® Windows® メッセージ ループから次の関数を呼び出す。

HRESULT UpdateInputState(HWND hDlg)
{
    HRESULT     hr;
    CHAR        strText[128]; // デバイス状態のテキスト。
    DIJOYSTATE2 js;           // Direct Input ジョイスティックの状態。
    CHAR*       str;

    if (NULL == g_pJoystick)
        return S_OK;

    // 現在の状態を読み取るデバイスをポーリングする。
    hr = g_pJoystick->Poll();
    if (FAILED(hr))
    {
        // ジョイスティックの再取得を試みる。
    }
    hr = g_pJoystick->GetDeviceState(sizeof(DIJOYSTATE2), &js);
    if (FAILED(hr))
        return hr;

GetDeviceState の呼び出しに注意する。最初のパラメータは、データが返される構造体のサイズである。第 2 のパラメータは、DIJOYSTATE2 型 であるこの構造体のアドレスである。この構造体は、最高 6 つの軸、128 のボタン、および 4 つの視点ハットを保持する。サンプル プログラムは、すべての軸とボタン、および 1 つのスライダの状態を確認する。次にこの情報が、メイン ダイアログ ウィンドウに表示される。

ジョイスティック ボタンは、キーまたはマウス ボタンとまったく同じように機能する。戻り値バイトの上位ビットが 1 の場合は、ボタンが押されていることを示す。

その他の DirectInput チュートリアルについては、「DirectInput C/C++ チュートリアル」を参照すること。


チュートリアル 4 : フォース フィードバックの使い方

このチュートリアルでは、フォース フィードバック ジョイスティックで単純なエフェクトを生成、再生、変更する手順を示す。エフェクトは、チェーンソーの動作を模している。エフェクトは、チェーンソーがぎこちなく動き始め、通常どおり動いて木を切っていく様子をシミュレートするよう作成されている。

Microsoft® DirectInput® システムの設定の準備手順と、システムを終了する最後の手順は、どのアプリケーションでも基本的に同じであり、これについては「チュートリアル 1 : キーボードの使い方」で説明している。しかし、DirectInput フォース フィードバック システムを終了するときは、生成したエフェクトを解除する手順を追加する必要がある。

このチュートリアルでは、必要なタスクを以下の手順に分割している。

  • ステップ 1 : フォース フィードバック デバイスの列挙
  • ステップ 2 : DirectInput フォース フィードバック デバイスの作成
  • ステップ 3 : サポートされるエフェクトの列挙
  • ステップ 4 : エフェクトの作成
  • ステップ 5 : 無限エフェクトの再生
  • ステップ 6 : エフェクトの変更


ステップ 1 : フォース フィードバック デバイスの列挙

最初の手順は、フォース フィードバック デバイスをシステムで利用できるようにすることである。これを行うには IDirectInput8::EnumDevices メソッドを呼び出す。次の例では、列挙が少なくとも 1 つの適合するデバイスを見つけることができた場合のみ、ゲーム デバイス インターフェイスへのグローバル ポインタが初期化される。

LPDIRECTINPUTDEVICE8  g_lpDIDevice = NULL;

hr = g_lpDI->EnumDevices(DI8DEVTYPE_GAMECTRL,
                         DIEnumDevicesProc,
                         NULL,
                         DIEDFL_FORCEFEEDBACK | DIEDFL_ATTACHEDONLY);
if (FAILED(hr))
{
  // フォース フィードバック ジョイスティックが利用できない。
}

この例では、g_lpDI は IDirectInput8 インターフェイスへの初期化済みポインタである。EnumDevices の第 1 パラメータにより、列挙対象がジョイスティック類のデバイスに限定される。第 2 パラメータは、Microsoft® DirectInput® が列挙に値するデバイスを識別したときに必ず呼び出されるコールバック関数である。第 3 パラメータは、コールバック関数に渡される、またはコールバック関数から渡されるユーザー定義データを表す。この例では使用されていない。最後に、第 4 パラメータのフラグにより、列挙対象が、フォース フィードバックをサポートするシステムに実際にアタッチされているデバイスに限定される。

コールバック関数は、デバイスが発見されるとすぐにそのデバイスを初期化するのに便利である (最初に発見されたのが使用したいデバイスであることを前提としている)。これは、「ステップ 2 : DirectInput フォース フィードバック デバイスの作成」で行うことになる。


ステップ 2 : DirectInput フォース フィードバック デバイスの作成

Microsoft® DirectInput® にデバイスを列挙させるには、DIEnumDevicesCallback と同じ型のコールバック関数を作成する。ステップ 1 では、この関数のアドレスを IDirectInput8::EnumDevices メソッドに渡している。

DirectInput は、知る必要があるデバイスについての情報を通知する DIDEVICEINSTANCE 構造体へのポインタを、第 1 パラメータとしてコールバック関数へ渡す。次の例で最も重要な構造体メンバは guidInstance であり、これは、ユーザーのシステムで特定のハードウェアを識別する唯一の手段である。この GUID は IDirectInput8::CreateDevice メソッドに渡す必要がある。

次のサンプル コードは、コールバック関数の最初の部分であり、GUID を取り出してデバイス オブジェクトを作成する。

BOOL CALLBACK DIEnumDevicesProc( LPCDIDEVICEINSTANCE lpddi,
                                 LPVOID pvRef )
{
    HRESULT hr;
    GUID DeviceGuid = lpddi->guidInstance;

    // ゲーム デバイスを生成する。

    hr = g_lpDI->CreateDevice(DeviceGuid, &g_lpDIDevice, NULL);

    if (FAILED(hr))
        // 成功または終了するまで列挙を続ける。
        return DIENUM_CONTINUE;

コールバック関数の次の手順は、入力デバイスの設定手順に類似している。注意すべきは、どのフォース フィードバック デバイスにとっても排他協調レベルが必要であるということである。

    // 協調レベルを設定する。
    hr = g_lpDIDevice->SetCooperativeLevel(g_hwndMain,
                                  DISCL_EXCLUSIVE | DISCL_FOREGROUND);
    if (FAILED(hr))
        return hr;

    // ゲーム データ形式の設定。
    hr = g_lpDIDevice->SetDataFormat(&c_dfDIJoystick);
    if (FAILED(hr))
        return hr;

最後に、デバイスの自動センタリング機能をオフにすることができる。基本的に自動センタリング機能は、モーターを使って標準ジョイスティックでスプリングをシミュレートする条件エフェクトである。この機能をオフにすると、ほかのエフェクトが妨害されなくなる。

    DIPROPDWORD DIPropAutoCenter;

    DIPropAutoCenter.diph.dwSize       = sizeof(DIPropAutoCenter);
    DIPropAutoCenter.diph.dwHeaderSize = sizeof(DIPROPHEADER);
    DIPropAutoCenter.diph.dwObj        = 0;
    DIPropAutoCenter.diph.dwHow        = DIPH_DEVICE;
    DIPropAutoCenter.dwData            = DIPROPAUTOCENTER_OFF;

    hr = g_lpDIDevice->SetProperty(DIPROP_AUTOCENTER,
                                   &DIPropAutoCenter.diph);
    if (FAILED(hr))
    {
        // 適宜失敗を処理する。
    }

    return DIENUM_STOP;   // 1 つで十分。
}   // DIEnumDevicesProc の終了。

使用前に、デバイスを取得しなければならない。取得方法の例については、「チュートリアル 3 : ジョイスティックの使い方」の「ステップ 5 : ジョイスティックへのアクセス権の取得」を参照すること。ほかのプロパティ変更とは異なり、フォース フィードバック エフェクトは取得状態でデバイスにダウンロードできることに注意する。

DirectInput フォース フィードバック デバイスを作成したら、「ステップ 3 : サポートされるエフェクトの列挙」に進む。


ステップ 3 : サポートされるエフェクトの列挙

これまでにフォース フィードバック デバイスの列挙と生成に成功したので、そのデバイスがサポートするエフェクトのタイプを列挙することができる。

どのデバイスでも利用可能な標準的エフェクトのみを生成したい場合は、エフェクトの列挙は必ずしも必要ではない。エフェクト オブジェクトを生成するとき、GUID_ConstantForceなどの定義済み GUID のうちどれか 1 つを使って、目的のエフェクト タイプを簡単に識別することができる。これらの識別子の全リストについては、「IDirectInputDevice8::CreateEffect」を参照すること。

もっと柔軟性のある方法は、特定タイプのサポートされるエフェクトを列挙し、コールバック関数からエフェクトに対する GUID を取得することである。もちろん、コールバック関数を使用して、エフェクトに対するデバイスのサポートについての詳細情報 (たとえば、デバイスがエンベロープをサポートしているかどうかについて) を得ることもできるが、このチュートリアルではエフェクト GUID だけを取得することにする。

まず、列挙されたエフェクトそれぞれについて、Microsoft® DirectInput® によって呼び出されるコールバック関数を生成する。この標準コールバックの情報については、「DIEnumEffectsCallback」を参照すること。この関数には好きな名前を付けることができる。

BOOL  EffectFound = FALSE;  // グローバル フラグ。

BOOL CALLBACK DIEnumEffectsProc(LPCDIEFFECTINFO pei, LPVOID pv)
{
    *((GUID *)pv) = pei->guid;
    EffectFound = TRUE;
    return DIENUM_STOP;  // 1 つで十分。
}

アプリケーションで定義された値 pv が指す GUID 変数には、エフェクトのために DirectInput が生成する DIEFFECTINFO 構造体へ渡される値が代入される。

エフェクト GUID を取得するために、次のように IDirectInputDevice8::EnumEffects メソッドを呼び出し、コールバックを開始する。

HRESULT  hr;
GUID     guidEffect;

hr = g_lpDIDevice->EnumEffects(
                         (LPDIENUMEFFECTSCALLBACK) DIEnumEffectsProc,
                          &guidEffect,
                          DIEFT_PERIODIC);
if (FAILED(hr))
{
    // 成功してもエフェクトが見つかったとは限らないので注意する。
    // 単に処理がスムーズに行われたことを意味する。
}

GUID 変数のアドレス guidEffect を EnumEffects メソッドに渡すことに注意すること。このアドレスは、コールバック関数に pv パラメータとして渡される。さらに、DIEFT_PERIODIC フラグを設定して、列挙対象を周期的エフェクトに限定する。

サポートされるエフェクトが列挙できたら、「ステップ 4 : エフェクトの作成」に進む。


ステップ 4 : エフェクトの作成

エフェクトの列挙後 EffectFound の値が FALSE でなければ、必要なエフェクト タイプの少なくとも 1 つに対するサポートを Microsoft® DirectInput® が発見したと見なしてよい。エフェクト GUID がわかっているので、今度はエフェクト オブジェクトを生成することができる。

IDirectInputDevice8::CreateEffect メソッドを呼び出す前に、次の配列と構造体を設定する必要がある。

  • エフェクトにかかわる軸の配列。ジョイスティックの場合、この配列は通常 x 軸と y 軸に対する識別子からなる。
  • 方向を設定する値の配列。これらの値は、軸の数と使用する座標の種類 (極座標、球状座標、デカルト座標) に応じて異なる。詳細については、「エフェクトの方向」を参照すること。
  • タイプ固有パラメータの構造体。例では、周期的エフェクトを生成しているので、構造体の型は DIPERIODIC となっている。
  • エフェクトに適用するエンベロープを定義する DIENVELOPE 構造体。
  • エフェクトの基本的パラメータを格納する DIEFFECT 構造体。

配列は、構造体と共に、宣言するときに初期化できる。

DWORD      dwAxes[2] = {DIJOFS_X, DIJOFS_Y};
LONG       lDirection[2] = {0, 0};

DIPERIODIC diPeriodic;      // タイプ固有パラメータ。
DIENVELOPE diEnvelope;      // エンベロープ。
DIEFFECT   diEffect;        // 汎用パラメータ。

次に型固有のパラメータを初期化する。この例の値は、1 秒の 20 分の 1 の周期で、フルフォースの周期的エフェクトを作成する。

diPeriodic.dwMagnitude = DI_FFNOMINALMAX;
diPeriodic.lOffset = 0;
diPeriodic.dwPhase = 0;
diPeriodic.dwPeriod = (DWORD)(0.05 * DI_SECONDS);

チェーンソーのモーターが始動しようとして、しばらく咳のような音を出し、次第にそれが収まっていくというエフェクトを得るために、エンベロープに半秒間のアタック時間と 1 秒間のフェード時間を設定する。

diEnvelope.dwSize = sizeof(DIENVELOPE);
diEnvelope.dwAttackLevel = 0;
diEnvelope.dwAttackTime = (DWORD)(0.5 * DI_SECONDS);
diEnvelope.dwFadeLevel = 0;
diEnvelope.dwFadeTime = (DWORD)(1.0 * DI_SECONDS);

次に、基本的なエフェクト パラメータを設定する。これらのパラメータには、方向とデバイス オブジェクト (ボタンと軸) の識別方法を決定するフラグ、エフェクトのサンプル周期とゲイン、およびさきほど準備した他のデータへのポインタが含まれる。さらに、ジョイスティックの発射ボタンにエフェクトを割り付けて、ボタンを押せばエフェクトが自動的に再生するようにする。

diEffect.dwSize = sizeof(DIEFFECT);
diEffect.dwFlags = DIEFF_POLAR | DIEFF_OBJECTOFFSETS;
diEffect.dwDuration = (DWORD)(2 * DI_SECONDS);

diEffect.dwSamplePeriod = 0;               // デフォルト設定。
diEffect.dwGain = DI_FFNOMINALMAX;         // スケーリングなし。
diEffect.dwTriggerButton = DIJOFS_BUTTON0;
diEffect.dwTriggerRepeatInterval = 0;
diEffect.cAxes = 2;
diEffect.rgdwAxes = dwAxes;
diEffect.rglDirection = &lDirection[0];
diEffect.lpEnvelope = &diEnvelope;
diEffect.cbTypeSpecificParams = sizeof(diPeriodic);
diEffect.lpvTypeSpecificParams = &diPeriodic;

最後に、エフェクトを作成する。

LPDIRECTINPUTEFFECT  g_lpdiEffect;  // グローバル エフェクト オブジェクト。

hr = g_lpDIDevice->CreateEffect(
                     guidEffect,     // 列挙からの GUID。
                     &diEffect,      // データの場所。
                     &g_lpdiEffect,  // インターフェイス ポインタを置く場所。
                     NULL);          // 集成体なし。
if (FAILED(hr))
{
    return hr;
}

デバイスが排他協調レベルで取得された状態にあれば、デフォルトでは、このエフェクトは生成されると同時にデバイスにダウンロードされることに注意する。これをコンパイルして実行し、発射ボタンを押すと、燃料の切れたチェーンソーがプスプスいう様子を感じることができる。

エフェクト オブジェクトを作成したら、「ステップ 5 : 無限エフェクトの再生」に進む。


ステップ 5 : 無限エフェクトの再生

前のステップで生成したエフェクトはボタン押下に応答して始動する。明示的な呼び出しに応答して再生されるエフェクトを作成するには、「ステップ 4 : エフェクトの作成」に戻り、DIEFFECT 構造体の dwTriggerButton メンバを次のように修正する。

diEffect.dwTriggerButton = DIEB_NOTRIGGER;

動作開始後、そのままの動作を続けるチェーンソーを作成するには、dwDuration メンバを次のように変更する。

diEffect.dwDuration = INFINITE;

次にエフェクトを開始する。

g_lpdiEffect->Start(1, 0);

このエフェクトは中止するまで働き続ける。

g_lpdiEffect->Stop();

前のステップで生成したエンベロープは変更する必要がないことに注意する。アタックはエフェクトが始動すると再生するが、フェード値は無視される。

アプリケーションが無限エフェクトを再生できたら、「ステップ 6 : エフェクトの変更」に進む。


ステップ 6 : エフェクトの変更

次に、エフェクトを修正し、木を切るにつれてチェーンソーのエンジンの回転が遅くなるようにする。Microsoft® DirectInput® では、再生中にエフェクトのパラメータを修正できる。

このエフェクトを変更するには、新しいDIEFFECT 構造体を設定するか、またはこのエフェクトの作成に使用した構造体にアクセスする。有効な新しい構造体をローカルに設定する場合は、dwSize メンバと、変更するデータを含むまたはそのデータを指すメンバのみを初期化すればよい。

この例では、型固有パラメータのエフェクトの周期を変更するため、エフェクトの作成に使用した DIPERIODIC 構造体へのアクセスが必要になる。すべてのメンバを初期化したローカル コピーを作成する方法もある。DIPERIODIC 構造体のアドレスが DIEFFECT 構造体のメンバ lpvTypeSpecificParams に格納されていることを確認する。

まず、エフェクトの新しい周期を設定する。

diPeriodic.dwPeriod = (DWORD)(0.08 * DI_SECONDS);

次に、IDirectInputEffect::SetParameters メソッドを呼び出して、変更を加える。

hr = g_lpdiEffect->SetParameters(&diEffect, DIEP_TYPESPECIFICPARAMS);

この変更を DIEFFECT 構造体の 1 つのメンバに限定している DIEP_TYPESPECIFICPARAMS フラグに注意すること。

ほかのフラグを使って、変更の方法を制御することができる。たとえば、DIEP_NODOWNLOAD フラグを使うと、エフェクトの始動直後にパラメータを変更できるが、IDirectInputEffect::Download メソッドを呼び出すまで実装は遅れる。さまざまな制御フラグの使用に関する詳細については、「IDirectInputEffect::SetParameters」を参照すること。

その他の DirectInput チュートリアルについては、「DirectInput C/C++ チュートリアル」を参照すること。


チュートリアル 5 : アクション マッピングの使い方

このチュートリアルでは、アクション マップの設定、修正、および適用について説明する。 この例は、宇宙戦ゲームで使用される場合を想定している。

Microsoft® DirectInput® システムの設定の準備手順と、システムを終了する最後の手順は、どのアプリケーションでも同じであり、「チュートリアル 1 : キーボードの使い方」で説明している。サンプルでは、キーボード、マウス、およびジョイスティックのすべてが使用されているため、それぞれを設定する必要がある。

このチュートリアルでは、必要なタスクを以下の手順に分割している。

  • ステップ 1 : ゲーム アクションの定義
  • ステップ 2 : アクション マップの定義
  • ステップ 3 : デバイスへのアクションのマッピング
  • ステップ 4 : アクション マップの構成と適用
  • ステップ 5 : アクション マップの表示
  • ステップ 6 : アクション マップのユーザー構成
  • ステップ 7 : アクション マッピングされたデータの取得


ステップ 1 : ゲーム アクションの定義

アクション マップ作成の最初の手順は、ゲーム アクションの定義である。これらのアクションはアプリケーション固有であり、開発者が定義する。この例では、アクションは宇宙戦シミュレータとしての必要性を考えて選択されている。これらの値は、開発者が適切と思ういろいろな方法で定義できる。アクションは、アクション マップの準備の概要に示すように列挙として定義したり、このコードのように定数として定義することができる。

#define INPUT_LEFTRIGHT_AXIS   1L
#define INPUT_UPDOWN_AXIS      2L
#define INPUT_TURNLEFT         3L
#define INPUT_TURNRIGHT        4L
#define INPUT_FORWARDTHRUST    5L
#define INPUT_REVERSETHRUST    6L
#define INPUT_FIREWEAPONS      7L
#define INPUT_ENABLESHIELD     8L
#define INPUT_DISPLAYGAMEMENU  9L
#define INPUT_QUITGAME        10L

アクションの値を定義したら、それをジャンル固有のアクション マッピング定数に割り当てる。これについては、「ステップ 2 : アクション マップの定義」で説明する。


ステップ 2 : アクション マップの定義

次に、各ゲーム アクションを、1 つの仮想コントロールまたはデバイス オブジェクトに割り当てる。これらのコントロールはアクション マッピング定数として定義され、ジャンルおよびサブジャンルによって定義される。この例では、フライト ゲーム ジャンルの宇宙戦サブジャンルを選択するのが適切である。このサブジャンルでは、以下の定数を使用できる。

優先順位 1 のコントロール

DIAXIS_SPACESIM_LATERAL
DIAXIS_SPACESIM_MOVE
DIAXIS_SPACESIM_THROTTLE
DIBUTTON_SPACESIM_FIRE
DIBUTTON_SPACESIM_MENU
DIBUTTON_SPACESIM_TARGET
DIBUTTON_SPACESIM_WEAPONS

優先順位 2 のコントロール

DIAXIS_SPACESIM_CLIMB
DIAXIS_SPACESIM_ROTATE
DIBUTTON_SPACESIM_BACKWARD_LINK
DIBUTTON_SPACESIM_DEVICE DIBUTTON_SPACESIM_DISPLAY
DIBUTTON_SPACESIM_FASTER_LINK
DIBUTTON_SPACESIM_FIRESECONDARY
DIBUTTON_SPACESIM_FORWARD_LINK
DIBUTTON_SPACESIM_GEAR
DIBUTTON_SPACESIM_GLANCE_DOWN_LINK
DIBUTTON_SPACESIM_GLANCE_LEFT_LINK
DIBUTTON_SPACESIM_GLANCE_RIGHT_LINK
DIBUTTON_SPACESIM_GLANCE_UP_LINK
DIBUTTON_SPACESIM_LEFT_LINK DIBUTTON_SPACESIM_LOWER
DIBUTTON_SPACESIM_PAUSE DIBUTTON_SPACESIM_RAISE
DIBUTTON_SPACESIM_RIGHT_LINK
DIBUTTON_SPACESIM_SLOWER_LINK
DIBUTTON_SPACESIM_TURN_LEFT_LINK
DIBUTTON_SPACESIM_TURN_RIGHT_LINK
DIBUTTON_SPACESIM_VIEW
DIHATSWITCH_SPACESIM_GLANCE

優先順位 1 のコントロールは最低限必要なコントロールで、できるだけデバイス オブジェトにマッピングする必要がある。優先順位 2 のコントロールは、基本的なゲーム操作にはそれほど重要ではなく、必要に応じてマッピングできる。

ゲーム アクションは、DIACTION 構造体の配列にあるアクション マッピング定数コントロールに割り当てられる。各 DIACTION 構造体は、最低 1 つのゲーム アクションと、それに関連するアクション マッピング定数、必要なフラグ、そして、アクションのわかりやすい名前か ID 文字列を格納している。残りの DIACTION メンバは、この時点では使用しない。次のサンプル コードは、DIACTION 構造体の配列の定義を示している。

#define NUMBER_OF_ACTIONS 18

DIACTION g_rgGameAction[NUMBER_OF_ACTIONS] =
{
    // デバイス入力は、ジャンルに応じて DInput で定義済み。
    {INPUT_LEFTRIGHT_AXIS, DIAXIS_SPACESIM_LATERAL, 0, "Turn",},
    {INPUT_UPDOWN_AXIS, DIAXIS_SPACESIM_MOVE, 0, "Move",},
    {INPUT_FIREWEAPONS, DIBUTTON_SPACESIM_FIRE, 0, "Shoot",},
    {INPUT_ENABLESHIELD, DIBUTTON_SPACESIM_GEAR, 0, "Shield",},
    {INPUT_DISPLAYGAMEMENU, DIBUTTON_SPACESIM_DISPLAY, 0, "Display",},
    {INPUT_QUITGAME, DIBUTTON_SPACESIM_MENU, 0, "Quit Game",},

    // キーボード入力マッピング。
    {INPUT_TURNLEFT, DIKEYBOARD_LEFT, 0, "Turn left", },
    {INPUT_TURNRIGHT, DIKEYBOARD_RIGHT, 0, "Turn right", },
    {INPUT_FORWARDTHRUST, DIKEYBOARD_UP, 0, "Forward thrust", },
    {INPUT_REVERSETHRUST, DIKEYBOARD_DOWN, 0, "Reverse thrust", },
    {INPUT_FIREWEAPONS, DIKEYBOARD_F, 0, "Fire weapons", },
    {INPUT_ENABLESHIELD, DIKEYBOARD_S, 0, "Enable shields", },
    {INPUT_DISPLAYGAMEMENU, DIKEYBOARD_D, DIA_APPFIXED,
                                      "Display game menu"), },
    {INPUT_QUITGAME, DIKEYBOARD_ESCAPE, DIA_APPFIXED, "Quit game", },

    // マウス入力マッピング。
    {INPUT_LEFTRIGHT_AXIS, DIMOUSE_XAXIS, 0, "Turn", },
    {INPUT_UPDOWN_AXIS, DIMOUSE_YAXIS, 0, "Move", },
    {INPUT_FIREWEAPONS, DIMOUSE_BUTTON0, 0, "Fire weapons", },
    {INPUT_ENABLESHIELD, DIMOUSE_BUTTON1, 0, "Enable shields", },
};

次に DIACTIONFORMAT 構造体が初期化され、前に定義したた DIACTION 配列 g_rgGameAction が格納される。また DIACTIONFORMAT 構造体は、ジャンル、バッファ サイズ、軸スケーリング、およびアクション マップのわかりやすい名前を定義する。g_AppGuid 値はアプリケーションで定義された GUID で、アクション マップを識別する。GUID の作成方法の詳細については、「GUID の使い方」を参照すること。

DIACTIONFORMAT diaf;
diaf.dwSize        = sizeof(DIACTIONFORMAT);
diaf.dwActionSize  = sizeof(DIACTION);
diaf.dwDataSize    = NUMBER_OF_ACTIONS * sizeof(DWORD);
diaf.dwNumActions  = NUMBER_OF_ACTIONS;
diaf.guidActionMap = g_AppGuid;
diaf.dwGenre       = DIVIRTUAL_SPACESIM;
diaf.rgoAction     = g_rgGameAction;
diaf.dwBufferSize  = 16;
diaf.lAxisMin      = -100;
diaf.lAxisMax      = 100;
diaf.tszActionMap  = "DI Test";

この DIACTIONFORMAT 構造体が列挙されたデバイスと照合され、「ステップ 3 : デバイスへのアクションのマッピング」で最適の組み合わせが調べられる。


ステップ 3 : デバイスへのアクションのマッピング

目的のマッピングが定義できたら、物理的デバイスに適用する必要がある。IDirectInput8::EnumDevicesBySemantics は、次のコードでこのプロセスを開始する。ここで、m_pDI は以前に定義された IDirectInput8 オブジェクトである。

HRESULT hr;
hr = m_pDI->EnumDevicesBySemantics(m_strUserName, &m_diaf,
                                EnumSuitableDevicesCB, this, 0L);

最初のパラメータ m_strUserName は、マッピングの設定が異なる複数のユーザーを対象とする場合に有用である。ただし、この例ではこの値には NULL を設定し、現在システムにログオンされているユーザーを示す。

第 2 パラメータは、マッピング情報を格納する DIACTIONFORMAT 構造体のアドレスである。

第 3 パラメータは、システム上でデバイスが見つかるたびに呼び出されるコールバック関数のアドレスである。サンプルで使用されている関数は、DIEnumDevicesBySemanticsCallback 関数に基づいている。

第 4 パラメータは、コールバック関数が使用できる任意の 32 ビット値である。この例では this ポインタであり、これは、MultiMapper サンプルで、いろいろなアクション マッピングの設定および操作の関数に使用されているクラス オブジェクトを指すポインタである。これによって、コールバック関数はクラスの関数へのアクセスを取得する。

最後のパラメータはフラグに使用される。この例ではフラグは使用されていない。

EnumSuitableDevicesCB コールバック関数がアプリケーション定義の関数AddDevices を呼び出し、次にこの関数が現在列挙されようとしているデバイス pdidDevice で IDirectInputDevice8::BuildActionMap 関数を呼び出す。次のコードは、この呼び出しを示している。

hr = pdidDevice->BuildActionMap( &m_diaf, m_strUserName, 0L );

ここでも最初のパラメータは、アクション マップを格納する DIACTIONFORMAT 構造体である。

第 2 パラメータも同じくユーザー名を指定できるが、ここでは NULL を指定する。

最後のパラメータは制御フラグを保持する。この例ではフラグは渡されない。

BuildActionMap は、DIACTIONFORMAT 構造体に指定されたコントロールの割り当て一覧を取得し、それを、列挙されているデバイスの指定されたデバイス オブジェクトへのマッピングを試みる。マッピングの結果は、同じ構造体に返される。渡すたびに、現在調べられている列挙デバイスの性質に応じて、異なるコントロールにマッピングされる。たとえばキーボードは、特定のキーへのマッピングを指定するコントロールをマッピングするが、ボタン、スライダ、または軸を指定するコントロールについてはマッピングしない。次にジョイスティックが列挙された場合、BuildActionMap はキーボードのキーにマッピングされたコントロールは無視するが、ボタン、スライダ、軸はジョイスティックのデバイス オブジェクトへのマッピングを試みる。

このデフォルト マッピングの結果を調べ、操作することができる。これは、「ステップ 4 : アクション マップの構成と適用」で行う。


ステップ 4 : アクション マップの構成と適用

DIACTIONFORMAT 構造体にマッピングが返されたら、操作してから IDirectInputDevice8::SetActionMap によって適用する。

この時点で、各 DIACTION 構造体の dwHow メンバを調べ、マッピングが成功したか、また各アクションがマッピングされたデバイス オブジェクトの選択基準は何であったかを判断することができる。たとえば、マッピングがハードウェア メーカーによる指定か、またはユーザーからの要求かを判断できる。

実際のマッピングそのものを変更するには、デフォルト マッピングに返された適切な DIACTION 構造体の dwSemantic メンバを編集する。このような変更は可能だが、実行は勧められない。

アクション マップの構成が終わったら、それをデバイスに適用し、物理的コントロールをゲーム アクションにバインドする必要がある。これを行うには、次に示すように SetActionMap を呼び出す。

    hr = pdidDevice->SetActionMap( &m_diaf, m_strUserName, 0L );

作成されたアクション マップはユーザーに対して表示され、簡単に変更することができる。これについては、「ステップ 5 : アクション マップの表示」で説明する。


ステップ 5 : アクション マップの表示

アクション マッピングには、開発者が特定のコントローラ ハードウェアに依存せずにゲーム アクションを定義できるという利点のほか、ユーザーによる再構成を容易にするユーザー インターフェイス (UI) が提供される利点もある。

UI は、テキストのみとグラフィックスの 2 つの形式で表示できる。また、これら 2 つのオプションを表示専用モードまたは編集モードで表示できる。

UI を表示するには、事前にいくつかの設定が必要となる。まず、DICOLORSET 構造体が宣言され、初期化される。この構造体は、その名前が示すように、UI の表示に使用するカラー セットを記述する。次のコードは、この構造体の設定を示している。

    DICOLORSET dics;
    ZeroMemory(&dics, sizeof(DICOLORSET));
    dics.dwSize = sizeof(DICOLORSET);

ZeroMemory 関数を使ってメモリ ブロックをゼロに設定すると、デフォルトのカラー スキーマを使用することを示す。これ以外には、初期化を必要とする要素は dwSize メンバのみであり、これは DICOLORSET 構造体のサイズに設定する。

DICOLORSET 構造体は、このコードに示すように、より大きな DICONFIGUREDEVICESPARAMS 構造体の一部として含まれる。

    DICONFIGUREDEVICESPARAMS dicdp;
    ZeroMemory(&dicdp, sizeof(dicdp));
    dicdp.dwSize = sizeof(dicdp);
    dicdp.dwcUsers       = 1;
    dicdp.lptszUserNames = m_strUserName;

    dicdp.dwcFormats     = 1;
    dicdp.lprgFormats    = &m_diaf;
    dicdp.hwnd           = m_hWnd;
    dicdp.lpUnkDDSTarget = NULL;

DICONFIGUREDEVICESPARAMS 構造体が宣言され、この構造体に割り当てられたメモリにゼロだけを格納するよう設定される。ここでも、dwSize メンバには構造体のサイズが設定される。この例では現在ログされているユーザーだけが使用されるため、dwcUsers は1 に設定される。変数 m_strUserName は NULL に設定されているため、ユーザー名は現在システムにログオンしているユーザーの名前になる。

アクション マップを格納する 1 つの DIACTIONFORMAT 構造体だけが渡されるため、dwcFormats は 1 に設定され、DIACTIONFORMAT 構造体のアドレスが lprgFormats として渡される。

変数 hwnd にはアプリケーション ウィンドウのハンドルを割り当て、lpUnkDDSTarget は NULL に設定して Microsoft® Windows® Graphics Device Interface (GDI) 関数を使って構成ユーザー インターフェイスのイメージを描画することを示す。

初期化された DICONFIGUREDEVICESPARAMS 構造体は、次のコードに示すように、IDirectInput8::ConfigureDevices に渡される。

    hr = m_pDI->ConfigureDevices(NULL, &dicdp, dwFlags, NULL);

最初と最後のパラメータはオプションのコールバック関数と共に使用するが、このサンプルでは使用しないため NULL が設定されている。

第 2 パラメータは、表示されるデータやその他補助情報を格納する DICONFIGUREDEVICESPARAMS 構造体のアドレスである。

第 3 パラメータは、表示が読み出し専用モードか編集モードかを決定するフラグに使用される。構成を、変更できない参照目的として表示する場合は、このパラメータに DICD_DEFAULT フラグを使用する。ただしこの例では、変数 dwFlags には既に DICD_EDIT が設定されているため、ユーザー構成が可能である。これについては、「ステップ 6 : アクション マップのユーザー構成」で説明する。


ステップ 6 : アクション マップのユーザー構成

この時点で、ユーザー構成インターフェイスが表示される。デバイス メーカーがグラフィックを提供している場合はデバイスのイメージが表示され、そのイメージのラベルには各デバイス オブジェクトに割り当てられたアクションが示されている。グラフィックがない場合、使用できるデバイス オブジェクトが関連付けられたアクションと共に、簡単なテキストによる一覧で表示される。次にグラフィックの例を示す。

ここでユーザーは、自分の判断でコントローラをアクションに再割り当てできる。変更結果は、DIACTIONFORMAT 構造体に反映される。ユーザー インターフェイスを終了すると、新しいアクション マップが IDirectInputDevice8::SetActionMap に送られ、実装される。

アクション マップのコントロールに関連付けられたデータの使い方については、「ステップ 7 : アクション マッピングされたデータの取得」で説明する。


ステップ 7 : アクション マッピングされたデータの取得

アクション マッピングはバッファリング データを念頭に置いて設計されており、ほとんどはバッファリング データで使用される。アクション マッピングされたデバイスからのデータ取得とマッピングされていないデバイスからのデータ取得では、データを取得する場所のみが異なっている。アクション マッピングがない場合は、DIDEVICEOBJECTDATA 構造体の dwOfs メンバを調べて、変更の報告があるデバイス オブジェクトを判断する。しかしアクション マッピングでは、uAppData メンバを調べる。データは dwData メンバで見つかる。

アクション マッピングされたデータの取得の詳細については、「アクション データの取得」を参照すること。


DirectInput C/C++ サンプル

以下のサンプル プログラムには、Microsoft® DirectInput® の使い方と機能が示されている。

  • DIConfig サンプル
  • FFConst サンプル
  • Joystick サンプル
  • Keyboard サンプル
  • Mouse サンプル
  • MultiMapper サンプル
  • ReadFFE サンプル
  • Scrawl サンプル

Microsoft DirectX® のサンプルには Microsoft Visual C++® プロジェクト ワークスペース ファイルが含まれているが、読者の開発環境で正しくコンパイルできるかどうかを確認する必要がある。詳細については、「DirectX のサンプルおよびその他の DirectX アプリケーションのコンパイル」を参照すること。


DIConfig サンプル

説明

DIConfig コードは、Microsoft® DirectInput® Mapper 方式に基づく構成ユーザー インターフェイスの実装方法を示している。このサンプル コードは非常に複雑であり、学習ツールというよりは参考実装として使用されることを意図している。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\DirectInput\DIConfig

実行可能ファイル :なし (「プログラミング上の注意」を参照すること)。

ユーザーズ ガイド

このサンプル コードでは実行可能ファイルが作成されないため、エンド ユーザーへの指示事項はない。

プログラミング上の注意

このコードは Diconfig.dll を生成する。このファイルは、デフォルトの Mapper UI で使用するすべての機能を格納するバイナリ ファイルである。このコードは非常に複雑であり、DirectInput ベースの構成ユーザー インターフェイスの参考実装用である。

このサンプルの詳細については、サンプル コード内のコメントを参照すること。次の主な機能をサポートする。

  • デバイス イメージの表示。
  • デバイスの再構成。
  • ほかの視角を表示する複数デバイス ビューのサポート。
  • オーバーレイをアクティブにするコントロールのサポート。
  • GetImageInfo メソッドの使用。
  • 同一コンピュータを使用するマルチユーザー アプリケーションのデバイス所有権。
  • SetActionMap メソッドにおけるユーザー設定の保持。


FFConst サンプル

説明

FFConst サンプル プログラムは、実際の動作をフォース フィードバック入力デバイスに適用し、シミュレータのようなアプリケーションで、フォース フィードバックを使って、物理エンジンで計算されたフォースを生成する方法を具体的に示す。

このアプリケーションを動作させるには、フォース フィードバック デバイスを接続しなければならない。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\DirectInput\FFConst

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DirectInput\Bin\FFConst.exe

ユーザーズ ガイド

このアプリケーションを起動すると、十字カーソルと黒いポイントがウィンドウに表示される。ウィンドウのクライアント エリア内の任意の場所でマウスをクリックすると、黒いポイントが移動する (デバイスのハンドルを動かしても何も起こらないことに注意)。FFConst は、十字カーソルからの距離に比例して、ポイントの方向からデバイスにコンスタント フォースを与える。マウスのボタンを押し続けると、ポイントを継続的に動かすこともできる。

プログラミング上の注意

このサンプル プログラムは、入力デバイスがいくつ接続されているかを列挙し、最初に検出されたフォース フィードバック デバイスを取得する。検出されなければ、メッセージを表示してプログラムを終了する。

黒いポイントを移動すると、joySetForcesXY 関数は、カーソルの座標をフォースの方向とマグニチュードに変換する。このデータは、コンスタント フォース エフェクトのパラメータを変更するのに使われる。


Joystick サンプル

説明

Joystick サンプル プログラムは、ジョイスティックのデータを取得し表示する。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\DirectInput\Joystick

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DirectInput\Bin\Joystick.exe

ユーザーズ ガイド

ジョイスティックを動かしたりひねったり、スロットル ホイールを回したり、さまざまな組み合わせでボタンを押したりしたときに、表示されたデータがどのように変化するかを観察する。

プログラミング上の注意

このアプリケーションは、ダイアログ プロシージャ内部に設定されたタイマに応答して、ジョイスティックの直接データをポーリングする。


Keyboard サンプル

説明

Keyboard サンプル プログラムでは、キーボードからデータを取得する際の、フォアグラウンド対バックグラウンド、排他協調レベル対非排他協調レベル、およびバッファリング データ対直接データの違いが示される。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\DirectInput\Keyboard

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DirectInput\Bin\Keyboard.exe

ユーザーズ ガイド

ユーザー インターフェイスを介して、協調レベルとデータ スタイルを任意に組み合わせて、その結果となるキーボードの動作を観察できる。設定を選択すると説明が行われ、デバイス作成時に予測される動作が示される。

プログラミング上の注意

直接モードでキーを押したままにすると、そのキーは無限に保持され、その後のキーボードのスナップショットは Microsoft® DirectInput® によって取得される。DirectInput は毎秒 12 回の間隔でスナップショットを取得しているため錯覚であるが、直接モードではその時点でのキーボードの状態のみが考慮され、スナップショットとスナップショットの間で発生した状態は無視されることを示している。

バッファリング モードでキーを押したままにすると、そのキーが押されたことを示すデータが短く表示され、バッファからデータがフラッシュされるとすぐにクリアされる。キーを離すと、キーが上がったという別のイベントが短く表示される。これが、直接モードとの大きな違いである。


Mouse サンプル

説明

Mouse サンプルは、マウスからデータを取得する際の、フォアグラウンド対バックグラウンド、排他協調レベル対非排他協調レベル、およびバッファリング データ対直接データの違いが示される。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\DirectInput\Mouse

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DirectInput\Bin\Mouse.exe

ユーザーズ ガイド

ユーザー インターフェイスを介して、協調レベルとデータ スタイルを任意に組み合わせて、その結果となるマウスの動作を観察できる。設定を選択すると説明が行われ、デバイス作成時に予測される動作が示される。

プログラミング上の注意

マウスを解放するには、Enter キーを押す。

直接モードでは、すべてのデバイス オブジェクトが表示され、マウスの移動に伴うデータの変化を見ることができる。Microsoft® DirectInput® は毎秒 12 回の間隔でスナップショットを取得しているため錯覚であるが、直接モードではその時点でのデバイスの状態のみが考慮され、デバイスのスナップショットとスナップショットの間で発生した状態は無視されることを示している。

バッファリング モードでボタンを押したままにすると、そのキーが押されたことを示すデータが短く表示され、バッファからデータがフラッシュされるとすぐにクリアされる。ボタンを離すと、ボタンが上がったという別のイベントが短く表示される。これが、直接モードとの大きな違いである。


MultiMapper サンプル

説明

MultiMapper サンプル プログラムは、アクション マッピング機能によるデータの設定、適用、および取得の方法を示している。また、ユーザー インターフェイスによる再マッピングの方法も説明する。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\DirectInput\MultiMapper

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DirectInput\MultiMapper.exe

ユーザーズ ガイド

まず、プレーヤーの数を割り当てる。MultiMapper サンプル プログラムでは、4 人まで設定できる。プレーヤーごとに、キーボードやマウスなど、1 つのデバイスが必要である。デバイスの数よりプレーヤーの数が多い場合、プログラムは、接続されているデバイスを基準とした最大プレーヤー数までプレーヤー数を自動的に削減する。

MultiMapper サンプル プログラムは、スペース コンバット アプリケーションの形態を模して設計されている。各プレーヤーには、回転、発射、反動推進エンジンの起動など、基本的なアクション セットが割り当てられる。次に、これらのアクションがデバイス コントロールにマップされる。コントロールがアクティブになると、表示ウィンドウのデータに反映される。

アクション マッピング ユーザー インターフェイスをアクティブにするには、D のキーを押す。各デバイスには、特定のデバイスをマッピングするための個別のタブがある。デバイス オブジェクトのラベルをダブルクリックすると、そのデバイス オブジェクトに割り当てることができるアクションの一覧がアクティブになる。アクション一覧からアクションを選択し、選択したデバイス オブジェクトにマップする。また、プレーヤー間でデバイスを再割り当てすることもできる。

プログラミング上の注意

システムにジョイスティックやホイールなどのコントローラが接続されている場合、デバイスのグラフィックに、アクションが各デバイス オブジェクトのコールアウトとして表示される。このグラフィックは、そのデバイスにビットマップがある場合に表示され、ビットマップがなければ表示されない。


ReadFFE サンプル

説明

ReadFFE サンプル プログラムは、Force Editor で作成された DirectInput エフェクト ファイルに格納されている Microsoft® DirectInput® フォース フィードバック エフェクト ファイルをすべて列挙して再生する。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\DirectInput\ReadFFE

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DirectInput\ReadFFE.exe

メディア ファイル :(SDK ルート)\Samples\Multimedia\Media\*.ffe

ユーザーズ ガイド

[Read File] をクリックして、既存の Force Feedback Effects (FFE) ファイルを開く。正常に読み出せたら、[Play Effects] をクリックして、フォースフィードバック デバイスでエフェクトを再生する。FFE は、Microsoft DirectX® SDK にパッケージングされている Force Feedback Editor ユーティリティを使って作成できる。

プログラミング上の注意

ファイルから列挙されたエフェクトのそれぞれについて、EnumAndCreateEffectsCallback 関数が IDirectInputEffect ポインタを初期化し、そのポインタをリンクされたリストに追加する。OnPlayEffects 関数がこのリストを処理し、すべてのエフェクトを再生する。


Scrawl サンプル

説明

Scrawl アプリケーションは、ウィンドウ表示アプリケーションの排他モードでのマウスの使い方を説明している。この場合のマウスは、ペイント プログラムのペンシル ツールのように機能する。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\DirectInput\Scrawl

実行可能ファイル :(SDK ルート)\Samples\Multimedia\DirectInput\Bin\Scrawl.exe

ユーザーズ ガイド

描画するには、左ボタンを押しながらマウスを動かす。右ボタンをクリックすると、ショートカット メニューが表示される。ショートカット メニューからは、クライアント ウィンドウの消去、マウス感度の設定、アプリケーションの終了を選択することができる。コントロール パネルの設定によってマウス ボタンが切り替えられると、Scrawl はこの動作を検出してそれに従う。Microsoft® DirectInput® はコントロール パネルの設定を無視するため、アプリケーション自身で切り替えを行う必要があることに注意する。

プログラミング上の注意

Scrawl サンプル プログラムは、次のような DirectInput プログラミングのさまざまな面を示している。

  • ウィンドウ表示アプリケーションの非排他モードでマウスを使用する。
  • メニューを使うために Microsoft Windows® が必要としたときにマウスを解放する。
  • Windows がマウスを必要としなくなったときに、マウスを再取得する。
  • デバイスのバッファリング データを読み取る。
  • 座標の移動が完了するまで画面表示の更新を延期する。
  • デバイスの活動状況のイベント通知を表示する。
  • 任意の範囲にカーソルの動きを制限する。
  • 使用前に、未処理のマウス座標を計測する。
  • 相対座標モードを使用する。


DirectInput C/C++ リファレンス

Microsoft® DirectInput® C/C++ アプリケーション プログラミング インターフェイス (API) のリファレンス情報は、次のように分類される。

  • インターフェイス
  • コールバック関数
  • 関数
  • マクロ
  • 構造体
  • デバイス定数
  • アクション マッピング定数
  • 戻り値


インターフェイス

ここでは、以下の Microsoft® DirectInput® インターフェイスのメソッドに関するリファレンスを提供する。

  • IDirectInput8
  • IDirectInputDevice8
  • IDirectInputEffect

注 : すべての DirectInput メソッドには、定義されている言語に応じて、C または C++ 構文に展開するマクロが用意されている。これらのマクロは Dinput.h ヘッダー ファイルにあり、独立して記述されているわけではない。


IDirectInput8

アプリケーションは、IDirectInput8 インターフェイスのメソッドを使用して、Microsoft® DirectInput® デバイスの列挙、作成、ステータスの取得、DirectInput オブジェクトの初期化、および Windows® コントロール パネルのインスタンスの起動を行う。

IDirectInput8 は、Microsoft DirectX® の以前のバージョンで使用されていた IDirectInput、IDirectInput2、および IDirectInput7 に取って代わるインターフェイスである。

IDirectInput8 はオブジェクトの新規クラスのインターフェイスであり、クラス識別子 CLSID_DirectInput8 で表される。クラス CLSID_DirectInput のオブジェクトへのインターフェイスに対して QueryInterface を呼び出しても、取得することはできない。その代わりに、DirectInput8Create 関数を使って IDirectInput8 インターフェイスを取得する。

IDirectInput8 インターフェイスのメソッドは、以下のグループにまとめることができる。

デバイス管理 | ConfigureDevices
 | CreateDevice
 | EnumDevices
 | EnumDevicesBySemantics
 | FindDevice
 | GetDeviceStatus
その他 | Initialize
 | RunControlPanel

すべての COM インターフェイスと同様に、IDirectInput インターフェイスは IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTINPUT 型は IDirectInput8 インターフェイスへのポインタとして定義される。

typedef struct IDirectInput8    *LPDIRECTINPUT8;

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


IDirectInput8::ConfigureDevices

接続された入力デバイスのプロパティ ページを表示する。ユーザーはこれを使って、アクションをデバイス コントロールにマップできる。

HRESULT IDirectInput8::ConfigureDevices(
   LPDICONFIGUREDEVICESCALLBACK lpdiCallback,
   LPDICONFIGUREDEVICESPARAMS   lpdiCDParams,
   DWORD  dwFlags,
   LPVOID pvRefData
);

パラメータ

lpdiCallback
サーフェスの内容が変更されるたびに呼び出されるコールバック関数のアドレス。「DIConfigureDevicesCallback」を参照すること。アプリケーションがプロパティ シートの表示を処理しない場合は、NULL を渡す。この場合、Microsoft® DirectInput® がプロパティ シートを表示し、ユーザーがプロパティ シートを閉じると、アプリケーションに制御を返す。コールバック ポインタを指定する場合は、DICONFIGUREDEVICESPARAMS 構造体の lpUnkDDSTarget メンバにも有効なサーフェス ポインタを指定する必要がある。
lpdiCDParams
ユーザー インターフェイスの表示方法に関する情報や、ユーザーとゲームのジャンルに関する情報を格納する DICONFIGUREDEVICESPARAMS 構造体のアドレス。
dwFlags
コントロール パネルの起動モードを指定する DWORD 値。DwFlags は次の値のいずれかでなければならない。
DICD_DEFAULT
プロパティ シートを表示専用モードで開く。
DICD_EDIT
プロパティ シートを編集モードで開く。このモードでは、ユーザーがアクションとコントロールのマッピングを変更できる。呼び出しが戻ると、アプリケーションは現在のデバイスがもう有効ではないと仮定して、デバイス インターフェイスを解放し、IDirectInput8::EnumDevicesBySemantics を呼び出してそのインターフェイスを初期化する。
pvRefData
コールバック関数に渡されるアプリケーション定義の 32 ビットの値。

戻り値

成功した場合は、DI_OK を返す。

失敗した場合は、次の戻り値のいずれかを返す。

DIERR_INVALIDPARAM
DIERR_OUTOFMEMORY

注意

ハードウェア ベンダーは、デバイスのビットマップおよびその他の表示情報を提供する。

このメソッドを呼び出す前に、DIACTION 構造体の lptszActionName メンバ内の値を変更することで、アプリケーションは各アクションに関連付けられたテキスト ラベルを変更できる。

構成は、ゲームごと、デバイスごと、ユーザーごとに格納される。情報は IDirectInputDevice8::BuildActionMap メソッドにより取得できる。

デフォルトでは、以下のピクセル フォーマットに対してアクセラレーションがサポートされている。

A1R5G5B5
16 ビットのピクセル フォーマットで、各色に 5 ビットが、アルファ (透過型テクセル) に 1 ビットが、それぞれ確保されている。
A8R8G8B8
アルファ付きの 32 ビット ARGB ピクセル フォーマット。
R9G8B8
24 ビット RGB ピクセル フォーマット。
X1R5G5B5
16 ビットのピクセル フォーマットで、そのうち 5 ビットは各色のために確保されている。
X8R8G8B8
32 ビットの RGB ピクセル フォーマットで、そのうち 8 ビットは各色のために確保されている。

上記以外のフォーマットではカラー変換が施されてしまい、フレーム レートが劇的に低下する。

注 : Microsoft Windows® キーは、アプリケーションの協調レベルで排他協調レベルを通して受動的に、または DISCL_NOWINKEY フラグを使って能動的に無効にする場合でも、デフォルトのアクション マッピング UI が表示されている間はアクティブになる。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


IDirectInput8::CreateDevice

指定の GUID に基づきデバイスのインスタンスを作成して初期化し、IDirectInputDevice8 インターフェイスを取得する。

HRESULT CreateDevice(
  REFGUID rguid,
  LPDIRECTINPUTDEVICE *lplpDirectInputDevice,
  LPUNKNOWN pUnkOuter
);

パラメータ

rguid
C++ の場合、目的の入力デバイスのインスタンス GUID に対する参照値。C の場合、この GUID のアドレス (「注意」を参照すること)。この GUID は、IDirectInput8::EnumDevices メソッドを介して取得するか、または、次の事前定義された GUID の 1 つを使用する。
GUID_SysKeyboard
デフォルトのシステム キーボード。
GUID_SysMouse
デフォルトのシステム マウス。

この GUID 値を有効にするには、アプリケーションは、ソース ファイルの先頭で、ほかのすべてのプリプロセッサ ディレクティブに先立ち、INITGUID を定義するか、あるいは DXGUID.LIB にリンクしなければならない。

lplpDirectInputDevice
成功時に IDirectInputDevice8 インターフェイス ポインタを取得する変数のアドレス。
pUnkOuter
COM 集成体に対する制御オブジェクトの IUnknown インターフェイスのアドレス。インターフェイスが集成されていない場合には NULL。普通、呼び出し側は NULL を渡す。

戻り値

成功した場合は、DI_OK を返す。

失敗した場合は、次の戻り値のいずれかを返す。

DIERR_DEVICENOTREG
DIERR_INVALIDPARAM
DIERR_NOINTERFACE
DIERR_NOTINITIALIZED
DIERR_OUTOFMEMORY

注意

punkOuter = NULL を指定してこのメソッドを呼び出すことは、CoCreateInstance(&CLSID_DirectInputDevice, NULL, CLSCTX_INPROC_SERVER, riid, lplpDirectInputDevice) を使用してオブジェクトを作成した後、Initialize を使用して初期化することと同等である。

punkOuter != NULL を指定してこのメソッドを呼び出すことは、CoCreateInstance(&CLSID_DirectInputDevice, punkOuter, CLSCTX_INPROC_SERVER, &IID_IUnknown, lplpDirectInputDevice) を使用してオブジェクトを作成することと同等である。集成したオブジェクトは手動で初期化しなければならない。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


IDirectInput8::EnumDevices

利用可能なデバイスを列挙する。

HRESULT EnumDevices(
  DWORD dwDevType,
  LPDIENUMCALLBACK lpCallback,
  LPVOID pvRef,
  DWORD dwFlags
);

パラメータ

dwDevType
デバイス タイプのフィルタ。

デバイスの型を指定してその列挙を制限するには、このパラメータに DI8DEVTYPE_* 値を設定する。「DIDEVICEINSTANCE」を参照すること。

デバイスのクラスを列挙するには、次のいずれかの値を使用する。

DI8DEVCLASS_ALL
すべてのデバイス。
DI8DEVCLASS_DEVICE
ほかのクラスに分類されないすべてのデバイス。
DI8DEVCLASS_GAMECTRL
すべてのゲーム コントローラ。
DI8DEVCLASS_KEYBOARD
すべてのキーボード。DI8DEVTYPE_KEYBOARD と同義である。
DI8DEVCLASS_POINTER
DI8DEVTYPE_MOUSE および DI8DEVTYPE_SCREENPOINTER 型のすべてのデバイス。
lpCallback
列挙されるデバイスごとに一度呼び出されるコールバック関数のアドレス。「DIEnumDevicesCallback」を参照すること。
pvRef
アプリケーション定義の 32 ビット値。列挙コールバック関数が呼ばれるたびに渡される。
dwFlags
列挙の範囲を指定するフラグ値。次のフラグを指定する。
DIEDFL_ALLDEVICES
すべてのインストール済みデバイスが列挙される。これがデフォルト モードである。
DIEDFL_ATTACHEDONLY
アタッチ状態にあり、インストール済みのデバイスだけ。
DIEDFL_FORCEFEEDBACK
フォース フィードバックをサポートするデバイスだけ。
DIEDFL_INCLUDEALIASES
ほかのデバイスのエイリアスであるデバイスを含む。
DIEDFL_INCLUDEHIDDEN
隠しデバイスを含む。隠しデバイスの詳細については、「DIDEVCAPS」を参照すること。
DIEDFL_INCLUDEPHANTOMS
仮想デバイス (プレースホルダ) を含む。

戻り値

成功した場合は、DI_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

注意

すべてのインストール済みデバイスは、たとえそれが現存していなくても列挙可能である。たとえば、操縦桿を、システムにインストールするだけしておいて、当面はコンピュータに接続しないでおくこともできる。dwFlags パラメータを設定して、アタッチ状態にあるデバイスだけを列挙するか、またはインストール済みのすべてのデバイスを列挙するかを指示する。DIEDFL_ATTACHEDONLY フラグが存在しない場合は、インストール済みの全デバイスが列挙される。

選別したいデバイス タイプを dwDevType フィルタとして渡して、そのタイプのデバイスだけを列挙することができる。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。

参照

IDirectInput8::EnumDevicesBySemantics


IDirectInput8::EnumDevicesBySemantics

アプリケーション指定のアクション マップに最も一致するデバイスを列挙する。

HRESULT EnumDevicesBySemantics(
  LPCTSTR ptszUserName,
  LPDIACTIONFORMAT lpdiActionFormat,
  LPDIENUMDEVICESBYSEMANTICSCB lpCallback,
  LPVOID pvRef,
  DWORD dwFlags
);

パラメータ

ptszUserName
現在のユーザーを識別する文字列。システムにログオンしたユーザーを指定する場合は NULL。ユーザー名はデバイスの列挙時に考慮される。ユーザー マッピングのないデバイスよりも、ユーザー マッピングを持つデバイスが優先される。デフォルトでは、ほかのユーザーが使用中のデバイスは、このユーザー用には列挙されない。
lpdiActionFormat
列挙する適切なデバイスのアクション マップを指定する DIACTIONFORMAT 構造体のアドレス。
lpCallback
列挙されるデバイスごとに一度呼び出されるコールバック関数のアドレス。「DIEnumDevicesBySemanticsCallback」を参照すること。
pvRef
アプリケーション定義の 32 ビット値。列挙コールバック関数が呼ばれるたびに渡される。
dwFlags
列挙の範囲を指定するフラグ値。次の 1 つ以上のフラグを指定する。
DIEDBSFL_ATTACHEDONLY
アタッチ状態にあり、インストール済みのデバイスだけを列挙する。
DIEDBSFL_AVAILABLEDEVICES
未所有かつインストール済みのデバイスだけを列挙する。
DIEDBSFL_FORCEFEEDBACK
フォース フィードバックをサポートするデバイスだけを列挙する。
DIEDBSFL_MULTIMICEKEYBOARDS
セカンダリ (非システム) キーボードおよびマウス デバイスのみ。
DIEDBSFL_NONGAMINGDEVICES
主要な目的がゲーム デバイスとしてではない、HID 準拠のデバイスのみ。USB スピーカなどのデバイス、および特殊なキーボード上のマルチメディア ボタンは、この値をとる。
DIEDBSFL_THISUSER
ptszUserName で識別されるユーザー用のインストール済みのすべてのデバイス、および未所有のすべてのデバイスを列挙する。

DIEDBSFL_VALID も Dinput.h に定義されているが、アプリケーションからは使用されない。

戻り値

成功した場合は、DI_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

注意

キーボードとマウスは最後に列挙される。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。

参照

IDirectInput8::EnumDevices、「アクション マッピング」


IDirectInput8::FindDevice

システムに新たにアタッチされたデバイスのインスタンス GUID を取得する。このメソッドは、Microsoft® Win32® デバイス管理通知に応答して呼び出される。

HRESULT FindDevice(
  REFGUID rguidClass,
  LPCTSTR ptszName,
  LPGUID pguidInstance
);

パラメータ

rguidClass
アプリケーションが検索するデバイス クラスの一意な識別子。アプリケーションは、デバイス到着通知からクラス GUID を取得する詳細については、Microsoft Platform Software Development Kit (SDK) の DBT_DEVICEARRIVAL イベントのトピックを参照すること。
ptszName
デバイスの名前。アプリケーションは、デバイス到着通知から名前を取得する。
pguidInstance
デバイスが見つかった場合にデバイスのインスタンス GUID を受け取る変数のアドレス。この値は IDirectInput8::CreateDevice に渡すことができる。

戻り値

成功した場合は、DI_OK を返す。

失敗した場合は DIERR_DEVICENOTREG を返す。GUID と名前が、Microsoft® DirectInput® に登録されているデバイス クラスに対応しない場合は、失敗となる。たとえば、入力デバイスではなく、記憶デバイスを参照する場合などである。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


IDirectInput8::GetDeviceStatus

指定デバイスのステータスを取得する。

HRESULT GetDeviceStatus(
  REFGUID rguidInstance
);

パラメータ

rguidInstance
C++ の場合、チェック中のステータスが属するデバイスのインスタンスを識別する GUID に対する参照値。C の場合、この GUID のアドレス。

戻り値

メソッドが成功し、デバイスがシステムとアタッチ状態にある場合は DI_OK を返し、そうでなければ DI_NOTATTACHED を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DIERR_GENERIC
DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


IDirectInput8::Initialize

Microsoft® DirectInput® オブジェクトを初期化する。アプリケーションは、通常、このメソッドを呼び出す必要はない。DirectInput8Create 関数が DirectInput オブジェクトを作成した後に、自動的に初期化を行う。

HRESULT Initialize(
  HINSTANCE hinst,
  DWORD dwVersion
);

パラメータ

hinst
DirectInput オブジェクトを作成するアプリケーションまたは DLL のインスタンス ハンドル。DirectInput は、この値を使用して、アプリケーションまたは DLL が、オブジェクト作成の資格を認められているかどうかを判断し、下位互換性のためにとるべき特別な動作を確定する。

DLL が親のアプリケーションのハンドルを渡すと、エラーとなる。たとえば、Web ページに埋め込まれていて DirectInput を使用する Microsoft ActiveX® コントロールは、Web ブラウザのハンドルではなく、それ自身のインスタンスのハンドルを渡さなければならない。これにより、DirectInput がそのコントロールを認識し、必要と思われる特別な動作をすべて有効にすることが確実になる。

dwVersion
アプリケーションの設計対象である DirectInput のバージョン番号。この値は通常、DIRECTINPUT_VERSION である。以前のバージョン番号を渡すと、DirectInput がそのバージョンをエミュレートすることになる。

戻り値

成功した場合は、DI_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DIERR_BETADIRECTINPUTVERSION
DIERR_OLDDIRECTINPUTVERSION

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


IDirectInput8::RunControlPanel

ユーザーが新しい入力デバイスをインストールしたり、構成を変更したりできるように、Windows コントロール パネルを実行する。

HRESULT RunControlPanel(
  HWND hwndOwner,
  DWORD dwFlags
);

パラメータ

hwndOwner
これ以降のユーザー インターフェイスの親ウィンドウとして使用するウィンドウのハンドル。このパラメータが NULL なら、親ウィンドウは使用されない。
dwFlags
現在は未使用なので、ゼロに設定しなければならない。

戻り値

成功した場合は、DI_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。

参照

IDirectInputDevice8::RunControlPanel


IDirectInputDevice8

アプリケーションは、IDirectInputDevice8 インターフェイスのメソッドを使用して、Microsoft® DirectInput® デバイスのアクセス権の取得と解放、デバイス プロパティと情報の管理、動作の設定、初期化の実行、フォース フィードバック エフェクトの生成と再生、およびデバイスのコントロール パネルの起動を行う。

IDirectInput8 インターフェイスは IDirectInput8::CreateDevice メソッドを使用して取得する。例については、「DirectInput デバイスの作成」を参照すること。

IDirectInputDevice8 は、これまでのバージョンの Microsoft® DirectX® で使用されていた IDirectInputDevice、IDirectInputDevice2、および IDirectInputDevice7 に取って代わるインターフェイスであるが、それらから継承はしない。以前のインターフェイスのメソッドと同名のメソッドは同様のサービスを実行するが、機能や動作がまったく同じであるとは限らない。QueryInterface を使って以前のインターフェイスを取得することはできない。

IDirectInputDevice8 インターフェイスのメソッドは、以下のグループにまとめることができる。

入力デバイスのアクセス | Acquire
 | Unacquire
アクション マッピング | BuildActionMap
 | GetImageInfo
 | SetActionMap
デバイス情報 | GetCapabilities
 | GetDeviceData
 | GetDeviceInfo
 | GetDeviceState
 | Poll
 | SetDataFormat
 | SetEventNotification
デバイス オブジェクト | EnumObjects
 | GetObjectInfo
デバイス プロパティ | GetProperty
 | SetCooperativeLevel
 | SetProperty
フォース フィードバック | CreateEffect
 | EnumCreatedEffectObjects
 | EnumEffects
 | EnumEffectsInFile
 | Escape
 | GetEffectInfo
 | GetForceFeedbackState
 | SendForceFeedbackCommand
 | WriteEffectToFile
その他 | Initialize
 | RunControlPanel
 | SendDeviceData

すべての COM インターフェイスと同様に、IDirectInputDevice8 インターフェイスは IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTINPUTDEVICE8 型は IDirectInputDevice8 インターフェイスへのポインタとして定義される。

typedef struct IDirectInputDevice8    *LPDIRECTINPUTDEVICE8;

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。

参照

IDirectInputDevice8

Built on 2000年11月18日


IDirectInputDevice8::Acquire

入力デバイスへのアクセス権を取得する。

HRESULT Acquire();

パラメータ

なし。

戻り値

成功した場合は、DI_OK を返す。デバイスが取得済みであれば S_FALSE を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED
DIERR_OTHERAPPHASPRIO

注意

デバイス取得の前に IDirectInputDevice8::SetDataFormat メソッドや IDirectInputDevice8::SetActionMap メソッドを使用して、データ形式を設定しなければならない。データ形式が設定されていない場合、Acquire は DIERR_INVALIDPARAM を返す。

デバイスに対して IDirectInputDevice8::GetDeviceState または IDirectInputDevice8::GetDeviceData メソッドを呼び出す前に、そのデバイスを取得しておかなければならない。

デバイス取得では、参照カウントを使用しない。このため、アプリケーションが IDirectInputDevice8::Acquire メソッドを 2 回呼び出し、その後 IDirectInputDevice8::Unacquire メソッドを 1 回呼び出すと、デバイスは解放される。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


IDirectInputDevice8::BuildActionMap

デバイスのアクション マップを構築し、それに関する情報を取得する。

HRESULT BuildActionMap(
  LPDIACTIONFORMAT lpdiaf,
  LPCWSTR lpszUserName
  DWORD  dwFlags
);

パラメータ

lpdiaf
アクション マップに関する情報を受け取る DIACTIONFORMAT 構造体のアドレス。
lpszUserName
どのユーザーのマッピングを要求しているかを指定する文字列へのポインタ。NULL の場合、現在のユーザーが想定される。
dwFlags
マッピングを制御するフラグ。この値は、次の値のいずれかである。
DIDBAM_DEFAULT
アプリケーション指定のマッピング (すなわち DIACTION 構造体に DIA_APPMAPPED フラグを持つマッピング) を除くすべてのマッピングを上書きする。
DIDBAM_HWDEFAULTS
アプリケーション指定のマッピングを含め、すべてのマッピングを上書きする。このフラグは DIDBAM_INITIALIZE に類似しているが、ユーザーがマップしたアクションは、デバイス ドライバまたは Microsoft® DirectInput®に指定されたデフォルト アクションで自動的に上書きされる。
DIDBAM_INITIALIZE
アプリケーション指定のマッピングを含め、すべてのマッピングを上書きする。
DIDBAM_PRESERVE
このデバイス、またはその他の構成済みデバイスに割り当てられた現在のマッピングを保存する。

戻り値

成功した場合は、DI_OK、DI_NOEFFECT または DI_WRITEPROTECT を返す。「注意」を参照すること。

失敗した場合は、次のいずれかのエラー値を返す。

DIERR_INVALIDPARAM
DIERR_MAPFILEFAIL

注意

デバイスにマッピングが作成されていない場合、このメソッドは DI_NOEFFECT を返す。たとえば、キーボードまたはマウスが、ジャンル固有アクションのマッピングを提供しない場合である。

DIERR_INVALIDPARAM が返される場合、マッピングの 1 つ以上が無効である。DIACTION 構造体の dwHow メンバには DIAH_ERROR が設定される。アプリケーションは、アクション マップの全体でエラーの検出と修正を補間することができる。

DIEFF_MAPFILEFAIL が返された場合は、ベンダーが提供するデバイス ファイルの読み込み中か、あるいはデバイスのユーザー構成ファイルの読み込みまたは書き込み中にエラーが発生したことを示す。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。

参照

IDirectInputDevice8::SetActionMap、IDirectInputDevice8::SetDataFormat


IDirectInputDevice8::CreateEffect

エフェクトの GUID によって識別されるエフェクトのインスタンスを作成、初期化する。

HRESULT CreateEffect(
  REFGUID rguid,
  LPCDIEFFECT lpeff,
  LPDIRECTINPUTEFFECT *ppdeff,
  LPUNKNOWN punkOuter
);

パラメータ

rguid
C++ の場合、作成するエフェクトを識別する GUID に対する参照値。C の場合、この GUID のアドレス。これは事前定義されたエフェクト GUID でも、あるいは IDirectInputDevice8::EnumEffects から得られる GUID でもよい。

以下の標準エフェクト GUID が定義されている。

  • GUID_ConstantForce
  • GUID_RampForce
  • GUID_Square
  • GUID_Sine
  • GUID_Triangle
  • GUID_SawtoothUp
  • GUID_SawtoothDown
  • GUID_Spring
  • GUID_Damper
  • GUID_Inertia
  • GUID_Friction
  • GUID_CustomForce
lpeff
作成されたエフェクトにパラメータを指定する DIEFFECT 構造体。このパラメータは、オプションである。NULL の場合、エフェクト オブジェクトは、パラメータなしで作成される。次に、アプリケーションはエフェクトをダウンロードする前に、IDirectInputEffect::SetParameters メソッドを呼び出し、エフェクトのパラメータを設定しなければならない。
ppdeff
成功時に IDirectInputEffect インターフェイスへのポインタを受け取る変数のアドレス。
punkOuter
COM 集成体に対する制御オブジェクトの IUnknown インターフェイスのアドレス。インターフェイスが集成されない場合、値は NULL である。普通、呼び出し側は NULL を渡す。

戻り値

成功した場合は、DI_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DIERR_DEVICEFULL
DIERR_DEVICENOTREG
DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

戻り値が S_OK である場合、エフェクトは作成済みで、エフェクトのパラメータは更新済みであるが、エフェクトは必ずしもダウンロードされていないことを示す。エフェクトをダウンロードするには、デバイスを排他モードで取得しなければならない。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


IDirectInputDevice8::EnumCreatedEffectObjects

このデバイスに現在作成されているすべてのエフェクトを列挙する。IDirectInputDevice8::CreateEffect によって作成されたエフェクトが列挙される。

HRESULT EnumCreatedEffectObjects(
  LPDIENUMCREATEDEFFECTOBJECTSCALLBACK lpCallback,
  LPVOID pvRef,
  DWORD fl
);

パラメータ

lpCallback
アプリケーション定義のコールバック関数のアドレス。Microsoft® DirectInput® は、プロトタイプ関数 DIEnumCreatedEffectObjectsCallback を提供している。
pvRef
コールバック用のリファレンス データ (コンテキスト)。
fl
フラグは現在未定義である。このパラメータは、ゼロでなければならない。

戻り値

成功した場合は、DI_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

注意

列挙の進行中に、エフェクトを作成または廃棄すると、その結果は予測できない。しかし、コールバック関数は、渡されるエフェクトを確実に解放する。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


IDirectInputDevice8::EnumEffects

デバイス上のフォース フィードバック システムがサポートするエフェクトをすべて列挙する。列挙される GUID は、デバイス メーカー独自のエフェクトに加えて、事前定義されたエフェクトも表すことができる。

HRESULT EnumEffects(
  LPDIENUMEFFECTSCALLBACK lpCallback,
  LPVOID pvRef,
  DWORD dwEffType
);

パラメータ

lpCallback
アプリケーション定義のコールバック関数のアドレス。この関数の宣言は、DIEnumEffectsCallback プロトタイプの宣言と同様に行わなければならない。
pvRef
コールバック関数に渡すアプリケーション定義の 32 ビットの値。このパラメータには、任意の 32 ビットの値を使用できる。ただし、便宜上、LPVOID と宣言されている。
dwEffType
エフェクト タイプのフィルタ。DIEFT_* 値の 1 つを使用して列挙するエフェクト タイプを指示するか、あるいは DIEFT_ALL を使用してすべてのエフェクト タイプを列挙する。これらの値のリストについては、「DIEFFECTINFO」を参照すること。

戻り値

成功した場合は、DI_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

コールバック関数が列挙を途中で停止すると、その列挙は成功したと見なされる。

注意

アプリケーションは、DIEFFECTINFO 構造体の dwEffType メンバを使用して、エフェクトのタイプ、エフェクトがサポートしているエンベロープと条件パラメータが何であるか、などエフェクトの一般的情報を取得できる。

エフェクトを最大限に利用するには、デバイス メーカーに問い合わせて、エフェクトの意味内容とそのエフェクト固有のパラメータに関する情報を入手しなければならない。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


IDirectInputDevice8::EnumEffectsInFile

Force Editor ユーティリティや、同じファイル形式を使用する別のアプリケーションで作成されたファイルに含まれる、すべてのエフェクトを列挙する。

HRESULT EnumEffectsInFile(
  LPCSTR lpszFileName,
  LPENUMEFFECTSINFILECALLBACK pec,
  LPVOID pvRef,
  DWORD dwFlags
);

パラメータ

lpszFileName
RIFF ファイルの名前。
pec
アプリケーション定義のコールバック関数のアドレス。この関数の宣言は、DIEnumEffectsInFileCallback プロトタイプの宣言と同様に行わなければならない。
pvRef
コールバック関数に渡すアプリケーション定義の 32 ビットの値。このパラメータは、32 ビットの任意の値を取ることができる。
dwFlags
DIFEF_DEFAULT (= 0) あるいは以下の値の一方または両方を使用できる。
DIFEF_INCLUDENONSTANDARD
Microsoft® DirectInput® で定義されていないエフェクト タイプを含める。
DIFEF_MODIFYIFNEEDED
現在のデバイスで再生できるように、作成したエフェクトを必要に応じて変更するように DirectInput に対して指示する。たとえば、2 つの軸に対して作成されたエフェクトは、デフォルトでは単一軸デバイスでは再生されない。このフラグを設定すると、単一軸でそのようなエフェクトが再生される。パラメータは、DIEFFECT 構造体内で変更される。この構造体は、コールバックに渡される DIFILEEFFECT 構造体の lpDiEffect メンバにより参照される。

戻り値

成功した場合は、DI_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

コールバック関数が列挙を途中で停止すると、その列挙は成功したと見なされる。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。

参照

IDirectInputDevice8::WriteEffectToFile、「ファイルからのエフェクトの読み込み」


IDirectInputDevice8::EnumObjects

デバイス上で使用可能な入出力オブジェクトを列挙する。

HRESULT EnumObjects(
  LPDIENUMDEVICEOBJECTSCALLBACK lpCallback,
  LPVOID pvRef,
  DWORD dwFlags
);

パラメータ

lpCallback
DirectInputDevice オブジェクトのコールバック関数のアドレス。Microsoft® DirectInput® は、この関数のプロトタイプを DIEnumDeviceObjectsCallback として提供している。
pvRef
コールバック用のリファレンス データ (コンテキスト)。
dwFlags
列挙するオブジェクトのタイプを指定するフラグ。次のフラグは、列挙対象を指定されたタイプのオブジェクトに制限する。
DIDFT_ABSAXIS
絶対軸。
DIDFT_ALIAS
HID (Human Interface Device) 使用エイリアスによって識別されるコントロール。このフラグは、HID 準拠の USB デバイスに対してのみ適用される。
DIDFT_ALL
すべてのオブジェクト。
DIDFT_AXIS
絶対軸、相対軸のどちらか。
DIDFT_BUTTON
プッシュ ボタンまたはトグル ボタン。
DIDFT_COLLECTION
ヒューマン インターフェイス デバイス (HID) リンク コレクション。HID リンク コレクションは、独自のデータを生成しない。
DIDFT_ENUMCOLLECTION(n)
HID リンク コレクション番号 n に属するオブジェクト。
DIDFT_FFACTUATOR
フォース フィードバック アクチュエータを含むオブジェクト。すなわち、フォースをこのオブジェクトに適用することができる。
DIDFT_FFEFFECTTRIGGER
フォース フィードバック エフェクトをトリガするために使用できるオブジェクト。
DIDFT_NOCOLLECTION
HID リンク コレクションに属さないオブジェクト。すなわち、DIDEVICEOBJECTINSTANCE 構造体の wCollectionNumber メンバが 0 であるオブジェクト。
DIDFT_NODATA
データを生成しないオブジェクト。
DIDFT_OUTPUT
IDirectInputDevice8::SendDeviceData メソッドを利用することによって、データを送ることができるオブジェクト。
DIDFT_POV
視点コントローラ。
DIDFT_PSHBUTTON
プッシュ ボタン。プッシュ ボタンは、ユーザーが押したときにダウン、ユーザーが離したときにアップと報告される。
DIDFT_RELAXIS
相対軸。
DIDFT_TGLBUTTON
トグル ボタン。トグル ボタンは、ユーザーが押したときにダウンと報告され、ユーザーが再度そのボタンを押すまでその状態に留まる。
DIDFT_VENDORDEFINED
メーカーにより定義されるタイプのオブジェクト。

戻り値

成功した場合は、DI_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

注意

dwFlags パラメータに DIDFT_FFACTUATOR および DIDFT_FFEFFECTTRIGGER フラグを指定すると、列挙対象は、この 2 つのフラグで定義されているすべての基準を満たすオブジェクトに限定される。ほかのすべてのフラグの場合は、このカテゴリに指定したフラグで定義されている基準を満たすオブジェクトが列挙される。たとえば、(DIDFT_FFACTUATOR | DIDFT_FFEFFECTTRIGGER) を指定すると、列挙対象をフォース フィードバック トリガ オブジェクトに限定する。これに対して、(DIDFT_FFEFFECTRIGGER | DIDFT_TGLBUTTON | DIDFT_PSHBUTTON) を指定すると、エフェクト トリガとして利用できる任意のボタンが列挙される。

アプリケーションは、特定のキーボードのキーやインジケータ ランプが存在するかどうかの判断を、このメソッドに依存してはならない。これらのオブジェクトは存在しないにもかかわらず列挙される可能性がある。利用可能なオブジェクトの基本セットはデバイス サブタイプから決定できるものの、メニュー キーなどの追加オブジェクトが利用できるかどうかを確実に判断できる方法はない。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


IDirectInputDevice8::Escape

ハードウェア固有のコマンドをフォース フィードバック ドライバに送信する。

HRESULT Escape(
  LPDIEFFESCAPE pesc
);

パラメータ

pesc
送信するコマンドを記述する DIEFFESCAPE 構造体。成功すると、実際に使用する出力バッファのバイト数が cbOutBuffer メンバに格納される。

戻り値

成功した場合は、DI_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DIERR_DEVICEFULL
DIERR_NOTINITIALIZED

ほかのデバイス固有エラー コードを返すこともできる。ハードウェア メーカーから詳細情報を入手すること。

注意

各ドライバは、異なるエスケープを実装しているので、正しいドライバと通信しているかどうかは、アプリケーション自体が確認しなければならない。これは、DIDEVICEINSTANCE 構造体の guidFFDriver メンバと、アプリケーションが予測している値を比較することにより確認できる。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


IDirectInputDevice8::GetCapabilities

DirectInputDevice オブジェクトの能力を取得する。

HRESULT GetCapabilities(
  LPDIDEVCAPS lpDIDevCaps
);

パラメータ

lpDIDevCaps
デバイスの能力を格納する DIDEVCAPS 構造体のアドレス。この構造体の dwSize メンバは、このメソッドを呼び出す前に初期化しておかなければならない。

戻り値

成功した場合は、DI_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED
E_POINTER

注意

Microsoft® DirectX® 3 との互換性については、sizeof(DIDEVCAPS_DX3) に初期化した dwSize メンバを含む DIDEVCAPS_DX3 構造体を渡してもよい。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


IDirectInputDevice8::GetDeviceData

デバイスからバッファリング データを取得する。

HRESULT GetDeviceData(
  DWORD cbObjectData,
  LPDIDEVICEOBJECTDATA rgdod,
  LPDWORD pdwInOut,
  DWORD dwFlags
);

パラメータ

cbObjectData
DIDEVICEOBJECTDATA 構造体のバイト単位のサイズ。
rgdod
バッファリング データを受け取るための DIDEVICEOBJECTDATA 構造体の配列。この配列の要素数は、pdwInOut パラメータの値と等しくなければならない。このパラメータが NULL の場合、バッファリング データはどこにも格納されないが、その他の副次エフェクトはすべて発生する。
pdwInOut
入力パラメータは、rgdod パラメータが指す配列の要素数である。出力パラメータは、実際に取得された要素数である。
dwFlags
データを取得する方法を制御するフラグ。ゼロまたは次のフラグを指定する。
DIGDD_PEEK
バッファから項目を削除しない。これ以降の IDirectInputDevice8::GetDeviceData 呼び出しで、同じデータを読み取ることができる。通常、データは読み取り後、バッファから削除される。

戻り値

成功した場合は、DI_OK または DI_BUFFEROVERFLOW を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTACQUIRED
DIERR_NOTBUFFERED
DIERR_NOTINITIALIZED

注意

デバイス データを取得する前に、IDirectInputDevice8::SetDataFormat メソッドと IDirectInputDevice8::SetProperty メソッド、または IDirectInputDevice8::SetActionMap メソッドでデータ形式とバッファ サイズを設定しなければならない。また、IDirectInputDevice8::Acquire メソッドでデバイスを取得しなければならない。

以下の例では、バッファリング データ要素を最高 10 個まで読み取る。デバイス バッファからは、データを読み取りながら削除している。

DIDEVICEOBJECTDATA rgdod[10];
DWORD dwItems = 10;
hres = IDirectInputDevice8_GetDeviceData(
    sizeof(DIDEVICEOBJECTDATA),
    rgdod,
    &dwItems,
    0);
if (SUCCEEDED(hres)) {
    // dwItems = 読み取られた要素数 (0 になる)。
    if (hres == DI_BUFFEROVERFLOW) {
    // バッファがオーバーフローした。
    }
}

バッファをフラッシュして、フラッシュした項目の数を取得するには、rgdod パラメータに NULL、pdwInOut パラメータに INFINITE を含む変数へのポインタをそれぞれ指定する。以下の例で、その方法を示す。

dwItems = INFINITE;
hres = IDirectInputDevice8_GetDeviceData(
            pdid,
            sizeof(DIDEVICEOBJECTDATA),
            NULL,
            &dwItems,
            0);
if (SUCCEEDED(hres)) {
    // バッファのフラッシュに成功。
    // dwItems = フラッシュした要素数。
    if (hres == DI_BUFFEROVERFLOW) {
        // バッファがオーバーフローした。
    }
}

デバイス バッファ中の要素数を調べるには、rgdod パラメータに NULL、pdwInOut パラメータに INFINITE、dwFlags に DIGDD_PEEK をそれぞれ指定する。以下の例で、その方法を示す。

dwItems = INFINITE;
hres = IDirectInputDevice8_GetDeviceData(
            pdid,
            sizeof(DIDEVICEOBJECTDATA),
            NULL,
            &dwItems,
            DIGDD_PEEK);
if (SUCCEEDED(hres)) {
    // dwItems = バッファ内の要素数。
    if (hres == DI_BUFFEROVERFLOW) {
        // バッファ オーバーフローが発生。一部のデータ
        // のキャプチャに失敗した。
    }
}

バッファ オーバーフローが発生したかどうかを調べるには、rgdod パラメータに NULL、pdwInOut パラメータにゼロを設定する。以下の例で、その方法を示す。

dwItems = 0;
hres = IDirectInputDevice8_GetDeviceData(
            pdid,
            sizeof(DIDEVICEOBJECTDATA),
            NULL,
            &dwItems,
            0);
if (hres == DI_BUFFEROVERFLOW) {
    // バッファ オーバーフローが発生。
}

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。

参照

IDirectInputDevice8::Poll、「ポーリングとイベント通知」


IDirectInputDevice8::GetDeviceInfo

デバイスの識別情報を取得する。

HRESULT GetDeviceInfo(
  LPDIDEVICEINSTANCE pdidi
);

パラメータ

pdidi
デバイスの識別情報を格納する DIDEVICEINSTANCE 構造体のアドレス。アプリケーションは、このメソッドを呼び出す前に、この構造体の dwSize メンバを初期化しておかなければならない。

戻り値

成功した場合は、DI_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED
E_POINTER

注意

Microsoft® DirectX® 3 との互換性については、sizeof(DIDEVICEINSTANCE_DX3) に初期化した dwSize メンバを含む DIDEVICEINSTANCE_DX3 構造体を渡してもよい。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


IDirectInputDevice8::GetDeviceState

デバイスから直接データを取得する。

HRESULT GetDeviceState(
  DWORD cbData,
  LPVOID lpvData
);

パラメータ

cbData
lpvData パラメータ内のバイト単位のバッファ サイズ。
lpvData
デバイスの現在の状態を受け取る構造体のアドレス。IDirectInputDevice8::SetDataFormat メソッドを呼び出す前に、データ形式を設定する。

戻り値

成功した場合は、DI_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTACQUIRED
DIERR_NOTINITIALIZED
E_PENDING

注意

デバイス データを取得する前に、IDirectInputDevice8::SetCooperativeLevel メソッドで協調レベルを設定した後、IDirectInputDevice8::SetDataFormat メソッドでデータ形式を設定し、IDirectInputDevice8::Acquire メソッドでデバイスを取得する。

次の表に示すように、5 つの定義済みデータ形式には、それぞれに対応するデバイス状態構造体が必要である。

データ形式 | 状態構造体
c_dfDIMouse | DIMOUSESTATE
c_dfDIMouse2 | DIMOUSESTATE2
c_dfDIKeyboard | 256 バイトの配列
c_dfDIJoystick | DIJOYSTATE
c_dfDIJoystick2 | DIJOYSTATE2

たとえば、c_dfDIMouse 形式を IDirectInputDevice8::SetDataFormat メソッドに渡す場合は、DIMOUSESTATE 構造体を IDirectInputDevice8::GetDeviceState メソッドに渡さなければならない。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。

参照

IDirectInputDevice8::Poll、「ポーリングとイベント通知」、「バッファリング データと直接データ」


IDirectInputDevice8::GetEffectInfo

エフェクトに関する情報を取得する。

HRESULT GetEffectInfo(
  LPDIEFFECTINFO pdei,
  REFGUID rguid
);

パラメータ

pdei
エフェクトの情報を受け取る DIEFFECTINFO 構造体。呼び出し側は、このメソッドを呼び出す前に、この構造体の dwSize メンバを初期化しておかなければならない。
rguid
C++ の場合、どのエフェクトの情報が要求されているかを識別する GUID に対する参照値。C の場合、この GUID のアドレス。

戻り値

成功した場合は、DI_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DIERR_DEVICENOTREG
DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED
E_POINTER

注 : このメソッドが非フォース フィードバック デバイスで呼び出された場合は、E_POINTER が戻される。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


IDirectInputDevice8::GetForceFeedbackState

デバイスのフォース フィードバック システムの状態を取得する。

HRESULT GetForceFeedbackState(
  LPDWORD pdwOut
);

パラメータ

pdwOut
デバイスのフォース フィードバック システムの現在の状態を表すフラグのアドレス。

この値は、以下の定数の組み合わせである。

DIGFFS_ACTUATORSOFF
デバイスのフォース フィードバック アクチュエータが無効である。
DIGFFS_ACTUATORSON
デバイスのフォース フィードバック アクチュエータが有効である。
DIGFFS_DEVICELOST
デバイスが予期しない障害を被り、不確定な状態にある。一度デバイスを解放した後で再取得するか、または DISFFC_RESET コマンドを送信するかどちらかでデバイスをリセットしなければならない。
DIGFFS_EMPTY
デバイスはダウンロードされた要素を持たない。
DIGFFS_PAUSED
すべてのアクティブなエフェクトの再生が一時停止されている。
DIGFFS_POWEROFF
フォース フィードバック システムは、現在使用できない。デバイスが電源状態を報告できなければ、DIFFS_POWERON および DIFFS_POWEROFF のどちらも返されない。
DIGFFS_POWERON
フォース フィードバック システムの電源は現在入っている。デバイスが電源状態を報告できなければ、DIFFS_POWERON および DIFFS_POWEROFF のどちらも返されない。
DIGFFS_SAFETYSWITCHOFF
安全スイッチが現在オフである。つまり、デバイスは動作できない。デバイスが安全スイッチの状態を報告できなければ、DIFFS_SAFETYSWITCHON と DIFFS_SAFETYSWITCHOFF のどちらも返されない。
DIGFFS_SAFETYSWITCHON
安全スイッチが現在オンである。つまり、デバイスは動作できる。デバイスが安全スイッチの状態を報告できなければ、DIFFS_SAFETYSWITCHON と DIFFS_SAFETYSWITCHOFF のどちらも返されない。
DIGFFS_STOPPED
再生中のエフェクトはなく、デバイスは中断状態ではない。
DIGFFS_USERFFSWITCHOFF
ユーザー フォース フィードバック スイッチが現在オフである。つまり、デバイスは動作できない。デバイスがユーザー フォース フィードバック スイッチの状態を報告できなければ、DIFFS_USERFFSWITCHON と DIFFS_USERFFSWITCHOFF のどちらも返されない。
DIGFFS_USERFFSWITCHON
ユーザー フォース フィードバック スイッチが現在オンである。つまり、デバイスは動作できる。デバイスがユーザー フォース フィードバック スイッチの状態を報告できなければ、DIFFS_USERFFSWITCHON と DIFFS_USERFFSWITCHOFF のどちらも返されない。

Microsoft® DirectInput® の将来のバージョンで、フラグが追加定義される可能性もある。アプリケーションは、現在未定義のフラグをすべて無視する必要がある。

戻り値

成功した場合は、DI_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTEXCLUSIVEACQUIRED
DIERR_NOTINITIALIZED
DIERR_UNSUPPORTED

注意

このメソッドを成功させるには、デバイスを排他協調レベルで取得しなければならない。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


IDirectInputDevice8::GetImageInfo

構成プロパティ シートで使用するデバイス イメージに関する情報を取得する。

HRESULT GetImageInfo(
  LPDIDEVICEIMAGEINFOHEADER lpdiDevImageInfoHeader
);

パラメータ

lpdiDevImageInfoHeader
デバイス イメージに関する情報を受け取る DIDEVICEIMAGEINFOHEADER 構造体のアドレス。

戻り値

成功した場合は、DI_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DIERR_INVALIDPARAM
DIERR_MAPFILEFAIL
DIERR_MOREDATA
DIERR_NOTINITIALIZED
DIERR_OBJECTNOTFOUND

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


IDirectInputDevice8::GetObjectInfo

ボタンや軸などのデバイス オブジェクトの情報を取得する。

HRESULT GetObjectInfo(
  LPDIDEVICEOBJECTINSTANCE pdidoi,
  DWORD dwObj,
  DWORD dwHow
);

パラメータ

pdidoi
オブジェクトの情報を格納する DIDEVICEOBJECTINSTANCE 構造体のアドレス。この構造体の dwSize メンバは、このメソッドを呼び出す前に初期化しておかなければならない。
dwObj
取得する情報が所属するオブジェクトを識別する値。このパラメータに設定する値は、dwHow パラメータで指定されている値に依存する。
dwHow
dwObj パラメータの解釈方法を指定する値。この値は、次のいずれか 1 つである。
値 | 意味
DIPH_BYOFFSET | dwObj パラメータは、アクセスする情報が所属するオブジェクトの現在のデータ形式に対するオフセットである。
DIPH_BYID | dwObj パラメータは、オブジェクト タイプ、またはインスタンス識別子である。この識別子は、DIDEVICEOBJECTINSTANCE 構造体の dwType メンバの中に返される。この構造体は、IDirectInputDevice8::EnumObjects メソッドに対する以前の呼び出しで返されたものである。
DIPH_BYUSAGE | dwObj パラメータは、オブジェクトの "HID 使用ページ" と "使用状況" の値である。これらの値は DIMAKEUSAGEDWORD マクロにより組み合わせられる。

戻り値

成功した場合は、DI_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED
DIERR_OBJECTNOTFOUND
E_POINTER

注意

Microsoft® DirectX® 3 との互換性については、sizeof(DIDEVICEOBJECTINSTANCE_DX3) に初期化した dwSize メンバを含む DIDEVICEOBJECTINSTANCE_DX3 構造体を渡してもよい。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


IDirectInputDevice8::GetProperty

入力デバイスに関する情報を取得する。

HRESULT GetProperty(
  REFGUID rguidProp,
  LPDIPROPHEADER pdiph
);

パラメータ

rguidProp
C++ の場合、取得するプロパティを識別する GUID に対する参照値。C の場合、この GUID のアドレス。この識別子として、事前定義された値の 1 つ、またはプロパティを識別する GUID へのポインタを使用できる。入力デバイスに対しては、次のプロパティが事前定義されている。
DIPROP_APPDATA
ゲーム内のアクションに関連するアプリケーション定義の値を DIPROPPOINTER として取得する。
DIPROP_AUTOCENTER
デバイス オブジェクトが自動センタリングを行うかどうかを指定する。返される値は DIPROPAUTOCENTER_OFF または DIPROPAUTOCENTER_ON である。詳細については、「IDirectInputDevice8::SetProperty」を参照すること。
DIPROP_AXISMODE
軸モードを取得する。取得される値は DIPROPAXISMODE_ABS または DIPROPAXISMODE_REL である。
DIPROP_BUFFERSIZE
入力バッファ サイズを取得する。

バッファ サイズは、IDirectInputDevice8::GetDeviceData メソッドの前回と今回の呼び出しの間で、バッファがデータを失うことなく保持できるデータの量を決定する。この値にゼロを設定して、アプリケーションがデバイスからバッファリング データを読み込まないように指定することもできる。DIPROPDWORD 構造体の dwData メンバ中のバッファ サイズが大きすぎてデバイスがサポートできない場合は、サポート可能な最大バッファ サイズが設定される。要求したバッファ サイズが設定されたかどうかを確認するには、バッファ サイズ プロパティを取得して、設定しようとした値とその結果を比較する。

DIPROP_CALIBRATIONMODE
アプリケーションが使用するのではなく、デバイス ドライバが使用する。
DIPROP_CPOINTS
未加工の到着データを調整するために使用するキャリブレーション ポイントを DIPROPCPOINTS 構造体として取得する。
DIPROP_DEADZONE
0 ～ 10,000 の範囲でジョイスティックのデッド ゾーンの値を取得する。ここで、0 はデッド ゾーンが存在しないこと、5,000 はデッド ゾーンが軸を中心とした物理範囲の 50 パーセントにまで広がっていること、および 10,000 は軸の物理範囲の全体が無効であることをそれぞれ示す。軸がデッド ゾーン内にあると、軸の範囲の中心にあるものと報告される。
DIPROP_FFGAIN
デバイスのゲインを取得する。詳細については、「IDirectInputDevice8::SetProperty」を参照すること。
DIPROP_FFLOAD
デバイスのメモリ ロードを取得する。この設定値は、個別のオブジェクトではなくデバイス全体に適用されるので、割り当てられた DIPROPDWORD 構造体の dwHow メンバは、DIPH_DEVICE でなければならない。取得される値は、0～100 の範囲にある。この値は、使用中のデバイス メモリのパーセント数を示す。デバイスは排他モードで取得しなければならない。排他モードでない場合、このメソッドは失敗し、戻り値 DIERR_NOTEXCLUSIVEACQUIRED が返される。
DIPROP_GETPORTDISPLAYNAME
このデバイスが接続されているポートの、人間が読める形式の表示名を取得する。アプリケーションは通常は使用しない。登録名が 1 つも返されない場合、このメソッドは S_FALSE を返す。
DIPROP_GRANULARITY
入力の細分度を取得する。細分度は、オブジェクトが移動距離を報告する際の最小量を表す。多くの軸オブジェクトの細分度は 1 であり、あらゆる値を取ることができる。軸によっては、より大きな細分度を持つものもある。たとえば、マウスのホイール軸の細分度は 20 にすることもできる。報告される位置変化はすべて、20 の倍数となる。すなわち、ユーザーがホイールをゆっくり回転させると、デバイスは位置を 0、20、40 などと報告する。これは読み取り専用プロパティである。
DIPROP_GUIDANDPATH
デバイスのクラス GUID とデバイス インターフェイス (パス) を取得する。詳細設定の可能なアプリケーションは、このプロパティを使うことで、Microsoft® DirectInput® でサポートされていない HID に対して操作を実行できる。詳細については、DIPROPGUIDANDPATH 構造体のリファレンスを参照すること。
DIPROP_INSTANCENAME
デバイスのインスタンスの登録名を取得する。詳細については、「IDirectInputDevice8::SetProperty」を参照すること。
DIPROP_JOYSTICKID
ジョイスティックのインスタンス番号を取得する。このプロパティはマウスやキーボードには実装されない。
DIPROP_KEYNAME
キーボード キーのローカライズされたキー名を DIPROPSTRING として取得する。
DIPROP_LOGICALRANGE
HID の軸から返される未加工データの範囲を取得する。デバイスはマイナス値を返すことがある。
DIPROP_PHYSICALRANGE
HID のメーカーが指定する、軸データの範囲を取得する。マイナス値が返されることもある。通常、DirectInput® は 0 ～ 0xFFFF の値を返すが、DIPROP_RANGE を使って、メーカー指定の範囲に合わせることができる。
DIPROP_PRODUCTNAME
デバイスの製品の登録名を取得する。詳細については、「IDirectInputDevice8::SetProperty」を参照すること。
DIPROP_RANGE
オブジェクトが報告できる値の範囲を取得する。一部のデバイスでは、これは読み取り専用プロパティである。
DIPROP_SATURATION
0 ～ 10,000 の範囲でジョイスティックの飽和ゾーンの値を取得する。飽和レベルとは、軸が極限位置にあるとみなされるポイントのことである。たとえば、飽和レベルが 9,500 に設定されている場合、軸の中心 (デッド ゾーン) から軸の端までの物理的距離の 95% の位置が軸の極限位置となる。
DIPROP_SCANCODE
キーボード キーのスキャン コードを DIPROPDWORD として取得する。
DIPROP_USERNAME
デバイスに現在割り当てられているユーザーのユーザー名を DIPROPSTRING として取得する。ユーザー名は IDirectInputDevice8::SetActionMap を呼び出して設定される。ユーザー名が設定されていない場合、このメソッドは S_FALSE を返す。
pdiph
メンバとして DIPROPHEADER 構造体を持つ大型プロパティ依存構造体の、DIPROPHEADER 部分のアドレス。プロパティには次の構造体が使用される。
DIPROPDWORD
単一の数値で表されるプロパティに使用される。
DIPROPGUIDANDPATH
DIPROP_GUIDANDPATH に使用される。
DIPROPRANGE
数値のペアで表されるプロパティに使用される。現在のところ、これに該当するプロパティは DIPROP_RANGE のみである。
DIPROPSTRING
文字列プロパティに使用される。

戻り値

成功した場合は、DI_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DIERR_INVALIDPARAM
DIERR_NOTEXCLUSIVEACQUIRED
DIERR_NOTINITIALIZED
DIERR_OBJECTNOTFOUND
DIERR_UNSUPPORTED

注意

以下の C コードの例は、DIPROP_BUFFERSIZE プロパティ値の取得方法を説明する。

DIPROPDWORD dipdw;  // DIPROPDWORD は DIPROPHEADER 構造体を格納する。
HRESULT hr;
dipdw.diph.dwSize       = sizeof(DIPROPDWORD);
dipdw.diph.dwHeaderSize = sizeof(DIPROPHEADER);
dipdw.diph.dwObj        = 0; // デバイス プロパティ
dipdw.diph.dwHow        = DIPH_DEVICE;

hr = IDirectInputDevice8_GetProperty(pdid, DIPROP_BUFFERSIZE, &dipdw.diph);
if (SUCCEEDED(hr)) {
    // dipdw.dwData メンバはバッファ サイズを格納する。
}

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。

参照

IDirectInputDevice8::SetProperty


IDirectInputDevice8::Initialize

DirectInputDevice オブジェクトを初期化する。IDirectInput8::CreateDevice メソッドは、デバイスの作成後、自動的にデバイスを初期化するので、アプリケーションは通常、このメソッドを呼び出す必要はない。

HRESULT Initialize(
  HINSTANCE hinst,
  DWORD dwVersion,
  REFGUID rguid
);

パラメータ

hinst
DirectInputDevice オブジェクトを作成するアプリケーションまたは DLL のインスタンス ハンドル。Microsoft® DirectInput® は、この値を使用して、アプリケーションまたは DLL が、オブジェクト作成の資格を認められているかどうかを判断し、下位互換性のために取るべき特別な動作を確定する。

DLL が親のアプリケーションのハンドルを渡すと、エラーとなる。たとえば、Web ページに埋め込まれていて DirectInput を使用する Microsoft ActiveX® コントロールは、Web ブラウザのハンドルではなく、それ自身のインスタンスのハンドルを渡さなければならない。これにより、DirectInput がそのコントロールを認識し、必要と思われる特別な動作をすべて有効にすることが確実になる。

dwVersion
アプリケーションの設計対象である DirectInput のバージョン番号。この値は通常、DIRECTINPUT_VERSION である。以前のバージョン番号を渡すと、DirectInput がそのバージョンをエミュレートすることになる。
rguid
C++ の場合、インターフェイスを関連付けるデバイスのインスタンスを識別するGUID に対する参照値。C の場合、この GUID のアドレス。IDirectInput8::EnumDevices メソッドを使うと、システムがどのインスタンス GUID をサポートしているかを確認することができる。

戻り値

成功した場合は、DI_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DIERR_ACQUIRED
DIERR_DEVICENOTREG

S_FALSE が返されれば、rGUID を介して渡されたインスタンス GUID を持つデバイスは初期化済みである。

注意

このメソッドが失敗する場合、基底のオブジェクトは不定の状態にあるものとみなし、使用前に再初期化しなければならない。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


IDirectInputDevice8::Poll

Microsoft® DirectInput® デバイス上のポーリング対象オブジェクトからデータを取得する。デバイスにポーリングが必要ないときにこのメソッドを呼び出しても、効果は一切ない。ポーリングする必要があるデバイスが定期的にポーリングされない場合、このデバイスから新しいデータは取得されない。このメソッドを呼び出すと、DirectInput はデバイス状態を更新し、バッファリング データが使用可能であれば入力イベントを生成し、通知が有効であれば通知イベントを設定する。

HRESULT Poll()

パラメータ

なし。

戻り値

成功した場合は、DI_OK を返す。デバイスがポーリングを要求しない場合は DI_NOEFFECT を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DIERR_INPUTLOST
DIERR_NOTACQUIRED
DIERR_NOTINITIALIZED

注意

デバイス データをポーリングする前に、IDirectInputDevice8::SetDataFormat または IDirectInputDevice8::SetActionMap メソッドでデータ形式を設定し、IDirectInputDevice8::Acquire メソッドでデバイスを取得しておかなければならない。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。

参照

ポーリングとイベント通知


IDirectInputDevice8::RunControlPanel

このデバイスに関連付けられた Microsoft® DirectInput® コントロール パネルを実行する。デバイスにコントロール パネルが関連付けられていない場合は、デフォルトのコントロール パネルが起動される。

HRESULT RunControlPanel(
  HWND hwndOwner,
  DWORD dwFlags
);

パラメータ

hwndOwner
親ウィンドウのハンドル。このパラメータが NULL なら、親ウィンドウは使用されない。
dwFlags
現在未使用である。ゼロだけが有効な値である。

戻り値

成功した場合は、DI_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


IDirectInputDevice8::SendDeviceData

出力を受け付けるデバイスにデータを送信する。デバイスは、取得済みの状態でなければならない。

HRESULT SendDeviceData(
  DWORD cbObjectData,
  LPCDIDEVICEOBJECTDATA rgdod,
  LPDWORD pdwInOut,
  DWORD fl
);

パラメータ

cbObjectData
単一の DIDEVICEOBJECTDATA 構造体のサイズ (バイト単位)。
rgdod
デバイスに送信するデータを格納した DIDEVICEOBJECTDATA 構造体の配列。これは、*pdwInOut 要素で構成されていなければならない。

DIDEVICEOBJECTDATA 構造体 の dwOfs フィールドには、データの送信先となるデバイス オブジェクトの識別子が含まれなければならない。この識別子は、DIDEVICEOBJECTINSTANCE 構造体 の dwType フィールドから取得される。dwTimeStamp および dwSequence メンバは、ゼロでなければならない。

pdwInOut
呼び出し時は、このパラメータが指す変数には、rgdod が指す配列の要素数が含まれる。終了時は、デバイスに送信された要素数が含まれる。
fl
データの送信方法を制御するフラグ。ゼロまたは次の値を取ることができる。
DISDD_CONTINUE
送信されるデバイス データは、以前に送信されたデバイス データに上書きされる。「注意」を参照すること。

戻り値

成功した場合は、DI_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DIERR_INPUTLOST
DIERR_NOTACQUIRED
DIERR_REPORTFULL
DIERR_UNPLUGGED

注意

個別のデータ要素が特定の順序で送信されるという保証はない。しかし、IDirectInputDevice8::SendDeviceData の呼び出しが成功した場合、送信されたデータの間に別のデータが紛れ込むことはない。また、複数のデータが 1 回の呼び出しで同じオブジェクトに送信される場合、どのデータが送信されるかは特定されない。

たとえば、データをパケット単位で送信できるデバイスがあり、各パケットは、A および B という 2 つの情報を表すとする。ここで、アプリケーションが 3 つのデータ要素 (B = 2、A = 1、B =0) を送信しようとするとどうなるだろうか。

実際のデバイスに送信されるパケットは 1 つである。パケットの A フィールドの値は 1、そしてパケットの B フィールドの値は 2 か 0 になる。

データを指定どおりにデバイスに送信する必要がある場合は、IDirectInputDevice8::SendDeviceData を 3 回呼び出し、呼び出しごとにデータ要素を 1 つずつ送信しなければならない。

最初の呼び出しに応答して、A フィールドがブランク、B フィールドの値が 2 のパケットをデバイスに送信する。

2 回目の呼び出しでは、A フィールドの値が 1、B フィールドがブランクのパケットを送信する。

最後の 3 回目の呼び出しで、A フィールドがブランク、B フィールドの値が 0 のパケットを送信する。

DISDD_CONTINUE フラグが設定されている場合、送信されたデバイス データは以前に送信されたデバイス データに上書きされる。それ以外の場合、送信されるデバイス データは、以前に送信されたデバイス データを含まない。

たとえば、Button0 および Button1 の 2 つのボタン出力をサポートするデバイスがあるとする。アプリケーションが最初に IDirectInputDevice8::SendDeviceData を呼び出して "Button0 押下" を渡すと、デバイスには、"Button0 押下、Button1 未押下" という形式のパケットが送信される。次に、アプリケーションがもう一度 SendDeviceData を呼び出して "Button1 押下" と DISDD_CONTINUE フラグを渡すと、デバイスには、"Button0 押下、Button1 押下" という形式のパケットが送信される。しかし、アプリケーションが DISDD_CONTINUE フラグを渡さなかった場合、デバイスに送信されるパケットは、"Button0 未押下 , Button1 押下" となる。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


IDirectInputDevice8::SendForceFeedbackCommand

デバイスのフォース フィードバック システムにコマンドを送信する。

HRESULT SendForceFeedbackCommand(
  DWORD dwFlags
);

パラメータ

dwFlags
目的の状態変化を示す単一の値。次のいずれか 1 つの値を取ることができる。
DISFFC_CONTINUE
中断されたすべてのアクティブなエフェクトの再生を継続する。デバイスが中断状態にないときにこのコマンドを送信すると、エラーになる。
DISFFC_PAUSE
すべてのアクティブ エフェクトの再生を中断する。このコマンドはエフェクトのクロックも停止するので、再開すると、エフェクトは継続時間を満了するまで再生が続行される。

デバイスが中断状態にある間は、新しいエフェクトを開始したり、既存のエフェクトを変更したりすることはできない。そのような操作を行うと、これ以降の DISFFC_CONTINUE コマンドが正常に機能しなくなることがある。

中断を破棄してすべてのエフェクトを停止するには、DISFFC_STOPALL または DISFCC_RESET コマンドを使用する。

DISFFC_RESET
デバイスのフォース フィードバック システムを始動状態にする。すべてのエフェクトはデバイスから削除され、有効でなくなる。これらのエフェクトを再び使用するには、再生成しなければならない。デバイスのアクチュエータは無効である。
DISFFC_SETACTUATORSOFF
デバイスのフォース フィードバック アクチュエータを無効にする。アクチュエータがオフの間も、エフェクトは引き続き再生されるが、デバイスはそれを無視する。音楽再生デバイスにたとえると、エフェクトは一時停止 (ポーズ) ではなく、消音 (ミュート) された状態である。
DISFFC_SETACTUATORSON
デバイスのフォース フィードバック アクチュエータを有効にする。
DISFFC_STOPALL
すべてのアクティブなエフェクトの再生を停止する。アクティブなエフェクトはすべてリセットされるが、デバイスには保存されており、引き続き有効である。デバイスが中断されている場合、その状態は失われる。

このコマンドは、再生中のエフェクトごとに IDirectInputEffect::Stop メソッドを呼び出すことに等しい。

戻り値

成功した場合は、DI_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTEXCLUSIVEACQUIRED
DIERR_NOTINITIALIZED
DIERR_UNSUPPORTED

注意

このメソッドを成功させるには、デバイスを排他協調レベルで取得しなければならない。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


IDirectInputDevice8::SetActionMap

デバイスのデータ形式を設定し、アプリケーション定義のアクションをデバイス オブジェクトにマップする。バッファリング データのバッファ サイズも設定する。

注 : このメソッドを呼び出す前に、デバイスを解放しておく必要がある。

HRESULT SetActionMap(
  LPCDIACTIONFORMAT lpdiActionFormat,
  LPCWSTR lptszUserName,
  DWORD dwFlags
);

パラメータ

lpdiActionFormat
適用するアクション マップに関する情報を格納する、DIACTIONFORMAT 構造体のアドレス。
lptszUserName
どのユーザーのアクション マップを設定しているかについて、ユーザー名を指定する Unicode 文字列。NULL を指定すると、現在システムにログインしているユーザーを表す。
dwFlags
アクション マップの適用方法を指定する DWORD 値。この値は、次の値のいずれかである。
DIDSAM_DEFAULT
このユーザーのアクション マップを設定する。マップが現在のマップと異なる場合、新しい設定がディスクに保存される。
DIDSAM_FORCESAVE
構成を常にディスクに保存する。
DIDSAM_NOUSER
デフォルトの構成プロパティ シートでこのデバイスのユーザー所有権をリセットする。ユーザー所有権をリセットしても、現在のアクション マップは削除されない。

戻り値

成功した場合は、次のいずれかの戻り値を返す。

DI_OK
DI_SETTINGSNOTSAVED
DI_WRITEPROTECT

失敗した場合は、次のいずれかのエラー値を返す。

DIERR_ACQUIRED
DIERR_INVALIDPARAM

注意

このメソッドを使うことで、アクションとコントロールのマッピングをデバイスのデフォルトから変更できる。アプリケーションは、このメソッドを使ってゲーム内のアクションを仮想コントロールにマップする必要がある。

このメソッドに渡されるユーザー名により、デバイスのアクション マッピングのセットが特定ユーザーにバインドされる。設定が現在適用されているマップと異なる場合は、自動的にディスクに保存される。複数のユーザーから入力を受け付けるアプリケーションは、各ユーザーのアクション マップが競合する可能性があるので、システムのマウスやキーボードにアクション マップを適用する際は注意が必要である。

このメソッドはデバイスが取得されていない場合にのみ呼び出すことができる。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。

参照

IDirectInputDevice8::BuildActionMap


IDirectInputDevice8::SetCooperativeLevel

デバイスのインスタンスに対する協調レベルを確立する。協調レベルは、このインスタンスが、同じデバイスのほかのインスタンス、およびシステムのこれ以外の部分との間で、どのように対話するかを決定する。

HRESULT SetCooperativeLevel(
  HWND hwnd,
  DWORD dwFlags
);

パラメータ

hwnd
デバイスに関連付けられているウィンドウ ハンドル。このパラメータは、このプロセスに属する最上位の有効なウィンドウ ハンドルでなければならない。デバイスに関連付けられたウィンドウは、Microsoft® DirectInput® デバイスの中でアクティブである間は、破壊してはならない。
dwFlags
デバイスに関連付ける協調レベルを表すフラグ。次のフラグが定義されている。
DISCL_BACKGROUND
アプリケーションは、バックグラウンド アクセス権を要求する。バックグラウンド アクセス権が許可されると、割り当てられたウィンドウがアクティブ ウィンドウでない場合でも、いつでもデバイスを取得できる。
DISCL_EXCLUSIVE
アプリケーションは、排他アクセス権を要求する。排他アクセス権が付与されると、デバイスが取得されている間、デバイスのほかのインスタンスは、そのデバイスの排他アクセス権を取得できない。ただし、別のアプリケーションが排他アクセス権を取得している場合でも、デバイスの非排他アクセス権は常に認められる。

アプリケーションがマウスまたはキーボード デバイスを排他モードで取得している場合は、WM_ENTERSIZEMOVE メッセージおよび WM_ENTERMENULOOP メッセージを受け取ると、常にデバイスを解放する必要がある。それ以外の場合、ユーザーはメニューを操作したり、ウィンドウを移動またはウィンドウのサイズを変更したりすることはできない。

DISCL_FOREGROUND
アプリケーションはフォアグラウンド アクセス権を要求する。フォアグラウンド アクセス権が付与されると、割り当てられたウィンドウがバックグラウンドに移動するときに、デバイスは自動的に解放される。
DISCL_NONEXCLUSIVE
アプリケーションは非排他アクセス権を要求する。デバイスに対するアクセス権は、同じデバイスにアクセスしているほかのアプリケーションの妨げにならない。
DISCL_NOWINKEY
Windows キーを無効にする。このフラグを設定すると、ユーザーは誤ってアプリケーションを終了することがなくなる。ただし、デフォルトのアクション マッピング UI が表示されている間は DISCL_NOWINKEY フラグは無効であり、また、デフォルトのアクション マッピング UI が存在している間は Microsoft Windows® キーは通常どおり機能する。

アプリケーションは、DISCL_FOREGROUND または DISCL_BACKGROUND のどちらか一方を指定しなければならない。両方指定することも、まったく指定しないこともエラーとなる。同様に、アプリケーションは、DISCL_EXCLUSIVE または DISCL_NONEXCLUSIVE のどちらか一方を指定しなければならない。

戻り値

成功した場合は、DI_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED
E_HANDLE

注意

システム マウスが排他モードで取得されると、マウス ポインタは、デバイスが解放されるまで画面から消去される。これに該当するのは、GUID_SysMouse を IDirectInput8::CreateDevice に渡して作成されたマウスのみである。

アプリケーションは、IDirectInputDevice8::Acquire メソッドでデバイスを取得する前に、このメソッドを呼び出さなければならない。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。

参照

協調レベル


IDirectInputDevice8::SetDataFormat

Microsoft® DirectInput® デバイスのデータ形式を設定する。

HRESULT SetDataFormat(
  LPCDIDATAFORMAT lpdf
);

パラメータ

lpdf
DirectInputDevice が返すべきデータ形式を記述する構造体のアドレス。アプリケーションは、独自の DIDATAFORMAT 構造体を定義することも、次の事前定義されたグローバル変数の 1 つを使用することもできる。
  • c_dfDIKeyboard
  • c_dfDIMouse
  • c_dfDIMouse2
  • c_dfDIJoystick
  • c_dfDIJoystick2

戻り値

成功した場合は、DI_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DIERR_ACQUIRED
DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

注意

IDirectInputDevice8::Acquire でデバイスを取得する前に、データ形式を設定しておかなければならない。データ形式は、一度設定するだけでよい。データ形式は、デバイスが取得されている間は変更できない。

アプリケーションがアクション マップを使用している場合は、代わりに IDirectInputDevice8::SetActionMap を呼び出すことでデータ形式が設定される。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。

参照

IDirectInputDevice8::GetDeviceState


IDirectInputDevice8::SetEventNotification

デバイス状態が変化したときに設定されるイベントを指定する。イベント通知をオフにするためにも使われる。

HRESULT SetEventNotification(
  HANDLE hEvent
);

パラメータ

hEvent
デバイス状態が変化したときに設定されるイベントのハンドル。Microsoft® DirectInput® はデバイスの状態が変化したときに、このハンドルに対して Microsoft® Win32 SetEvent 関数を使用する。hEvent パラメータを NULL にすると、通知は無効になる。

アプリケーションは、Microsoft® Win32® CreateEvent 関数を使用して、手動リセット イベントまたは自動リセット イベントとしてハンドルを作成することができる。イベントを自動リセット イベントとして作成すると、オペレーティング システムは、待ち時間が経過したときに自動的にイベントをリセットする。イベントを手動リセット イベントとして作成すると、アプリケーションは、Win32 ResetEvent 関数を呼び出してイベントをリセットしなければならない。DirectInput は、イベント通知ハンドルに対して、Win32 ResetEvent 関数を呼び出さない。アプリケーションは、通常、イベントを自動リセット イベントとして作成する。

戻り値

成功した場合は、DI_POLLEDDEVICE を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DIERR_ACQUIRED
DIERR_HANDLEEXISTS
DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

注意

デバイス状態の変更は次のいずれかに定義される。

  • 軸の位置の変更
  • ボタンの状態 (押した状態または離した状態)
  • 視点コントロールの方向の変更
  • 取得の喪失

DirectInputDevice オブジェクト中に選択されているイベントに対しては、Win32 CloseHandle 関数を呼び出してはならない。イベント ハンドルを終了する前に、hEvent パラメータに NULL を設定して、このメソッドを呼び出さなければならない。

イベント通知ハンドルは、デバイスが取得されている間は変更できない。この関数が成功すれば、アプリケーションは、ほかの Win32 イベント ハンドルと同様に、このイベント ハンドルを使用できる。

以下の例は、ハンドルが現在ブロッキングなしに設定されているかどうかをチェックする。

dwResult = WaitForSingleObject(hEvent, 0);
if (dwResult == WAIT_OBJECT_0) {
    // イベントを設定する。イベントが自動リセットで
    // 作成されていた場合は、同時にリセットされる。
}

次の例は、イベントが設定されるまで、繰り返しブロッキングを行う処理を示している。待ち時間が経過するまで、スレッドはシステムに応答できないので、この動作は厳禁である。特に、スレッドは Windows® メッセージに応答しなくなる。

dwResult = WaitForSingleObject(hEvent, INFINITE);
if (dwResult == WAIT_OBJECT_0) {
    // イベントが設定された。イベントが自動リセットで
    // 作成されていた場合は、同時にリセットされる。
}

以下の例は、2 つのイベントを使用するメッセージベースのアプリケーションの、典型的なメッセージ ループを示している。

HANDLE ah[2] = { hEvent1, hEvent2 };

while (TRUE) {

    dwResult = MsgWaitForMultipleObjects(2, ah, FALSE,
                        INFINITE, QS_ALLINPUT);
    switch (dwResult) {
    case WAIT_OBJECT_0:
        // イベント 1 が設定された。イベントが自動リセットで
        // 作成されていた場合は、同時にリセットされる。
        ProcessInputEvent1();
        break;

    case WAIT_OBJECT_0 + 1:
        // イベント 2 が設定された。イベントが自動リセットで
        // 作成されていた場合は、同時にリセットされる。
        ProcessInputEvent2();
        break;

    case WAIT_OBJECT_0 + 2:
        // Windows メッセージを受け取った。これらの
        // メッセージがなくなるまで処理を続ける。
        while(PeekMessage(&msg, NULL, 0, 0, PM_REMOVE)){
            if (msg.message == WM_QUIT) {
                goto exitapp;
            }
            TranslateMessage(&msg);
            DispatchMessage(&msg);
        }
        break;

    default:
        // 予期しないエラー。
        Panic();
        break;
    }
}

次の例は、2 つのイベントを使用する非メッセージベースのアプリケーションの、典型的なメッセージ ループを示している。

HANDLE ah[2] = { hEvent1, hEvent2 };
DWORD dwWait = 0;

while (TRUE) {

    dwResult = MsgWaitForMultipleObjects(2, ah, FALSE,
                                         dwWait, QS_ALLINPUT);
    dwWait = 0;

    switch (dwResult) {
    case WAIT_OBJECT_0:
        // イベント 1 が設定された。イベントが自動リセットで
        // 作成されていた場合は、同時に
        // リセットされる。
        ProcessInputEvent1();
        break;

    case WAIT_OBJECT_0 + 1:
        // イベント 2 が設定された。イベントが自動リセットで
        // 作成されていた場合は、同時に
        // リセットされる。
        ProcessInputEvent2();
        break;

    case WAIT_OBJECT_0 + 2:
        // Windows メッセージを受け取った。これらの
        // メッセージがなくなるまで処理を続ける。
        while(PeekMessage(&msg, NULL, 0, 0, PM_REMOVE)){
            if (msg.message == WM_QUIT) {
                goto exitapp;
            }
            TranslateMessage(&msg);
            DispatchMessage(&msg);
        }
        break;

    default:
        // 入力あるいは待機中のメッセージがない。
        // ゲームのフレームを作る。
        // ゲームがアイドル状態であれば、
        // 入力あるいはメッセージを待ち続ける。
        if (!DoGame()) {
            dwWait = INFINITE;
        }
        break;
    }
}

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。

参照

ポーリングとイベント通知


IDirectInputDevice8::SetProperty

デバイスの動作を定義するプロパティを設定する。これらのプロパティには、入力バッファ サイズや軸モードなどがある。

HRESULT SetProperty(
  REFGUID rguidProp,
  LPCDIPROPHEADER pdiph
);

パラメータ

rguidProp
C++ の場合、設定するプロパティを識別する GUID に対する参照値。C の場合、この GUID のアドレス。この識別子は、事前定義された値の 1 つでも、またはプロパティを識別する GUID へのポインタでもよい。以下のプロパティ値が入力デバイスに対して事前定義されている。
DIPROP_APPDATA
ゲーム内のアクションと結び付けられたアプリケーション定義の値を DIPROPPOINTER として設定する。
DIPROP_AUTOCENTER
デバイス オブジェクトが自動センタリングを行うかどうかを指定する。この設定値は、個別のオブジェクトではなくデバイス全体に適用されるので、割り当てられた DIPROPDWORD 構造体の dwHow メンバは、DIPH_DEVICE でなければならない。

dwData メンバは、次のいずれか 1 つの値を取ることができる。

DIPROPAUTOCENTER_OFF:ユーザーがデバイスを離しても、自動的にセンタリングを行わない。フォース フィードバックを使用するアプリケーションは、エフェクトの再生前に自動センタリングを無効にする必要がある。

DIPROPAUTOCENTER_ON:ユーザーがデバイスを離すと、自動的にセンタリングを行う。

自動センタリング機能をサポートしていないデバイスもある。

DIPROP_AXISMODE
軸モードを設定する。設定値 (DIPROPAXISMODE_ABS または DIPROPAXISMODE_REL) は、割り当てられた DIPROPDWORD 構造体の dwData メンバに指定しなければならない。詳細は pdiph パラメータの説明を参照すること。

この設定値はデバイス全体に適用されるので、割り当てられた DIPROPDWORD 構造体の dwHow メンバは、DIPH_DEVICE でなければならない

DIPROP_BUFFERSIZE
入力バッファ サイズを設定する。設定値は、割り当てられた DIPROPDWORD 構造体の dwData メンバに指定しなければならない。「注意」を参照すること。

この設定値はデバイス全体に適用されるので、割り当てられた DIPROPDWORD 構造体の dwHow メンバは、DIPH_DEVICE でなければならない

DIPROP_CALIBRATIONMODE
Microsoft® DirectInput® が取得するデータが、キャリブレーション済みかキャリブレーション前かを、アプリケーションが指定できるようにする。デフォルトでは、DirectInput はキャリブレーション済みデータを取得する。

デバイス全体に対してキャリブレーション モードを設定することは、それぞれの軸に対してキャリブレーション モードを設定することと同じ意味を持つ。

DIPROPDWORD 構造体の dwData メンバは次のいずれか１つの値を取ることができる。

DIPROPCALIBRATIONMODE_COOKED:DirectInput は、キャリブレーション情報の適用後のデータを返す。これがデフォルト モードである。

DIPROPCALIBRATIONMODE_RAW:DirectInput は、キャリブレーション前の未加工データを返す。このモードは通常、コントロール パネル型のアプリケーションでのみ使用される。未加工データにはマイナス値が含まれることもあることに注意すること。

デバイスを未加工モードに設定すると、デッド ゾーン、飽和、および範囲の設定が無視される。

DIPROP_CPOINTS
未加工の到着データを調整するために使用するキャリブレーション ポイントを設定する。設定値は、割り当てられた DIPROPCPOINTS 構造体の cp 配列内の CPOINT 型として指定しなければならない。

この設定値は個別のデバイス オブジェクトに適用されるので、割り当てられた DIPROPHEADER 構造体の dwHow メンバは、DIPH_BYID または DIPH_BYOFFSETT のいずれかに設定されなければならない。

DIPROP_DEADZONE
0 ～ 10,000 の範囲でジョイスティックのデッド ゾーンの値を設定する。ここで、0 はデッド ゾーンが存在しないこと、5,000 はデッド ゾーンが軸を中心とした物理範囲の 50 パーセントにまで広がっていること、および 10,000 は軸の物理範囲の全体が無効であることをそれぞれ示す。軸がデッド ゾーン内にあると、軸の範囲の中心にあるものと報告される。

この設定は、デバイス全体または 1 つの特定の軸のどちらかに適用できる。

DIPROP_FFGAIN
デバイスのゲインを設定する。この設定値は、個別のオブジェクトではなくデバイス全体に適用されるので、割り当てられた DIPROPDWORD 構造体の dwHow メンバは、DIPH_DEVICE でなければならない。

dwData メンバは、デバイス上に作成されたすべてのエフェクトに適用されるゲイン値を格納する。値は、0 ～ 10,000 の整数である。デバイスに対するエフェクトのマグニチュードは、この値で調整される。たとえば、10,000 は、すべてのエフェクト マグニチュードをそのまま適用することを示す。9,000 は、すべてのエフェクト マグニチュードをその名目マグニチュードの 90 パーセントに圧縮することを示す。

ゲイン値の設定は、ユーザーの好みに応じて、すべてのフォース フィードバック エフェクトを一率に減少したい場合に有効である。

ほかのプロパティとは異なり、ゲインはデバイスが取得状態にある場合に設定できる。

DIPROP_INSTANCENAME
これは、詳細設定の可能なアプリケーション用に設けられたプロパティであり、これを使ってデバイスのインスタンスの登録名を変更すると、接続されている同種のデバイスを区別することができる。インスタンスの登録名は、DIDEVICEINSTANCE 構造体の tszInstanceName メンバ内に返される。アプリケーションは通常、登録名を変更する必要はない。

この設定値はデバイス全体に適用されるので、割り当てられた DIPROPDWORD 構造体の dwHow メンバは、DIPH_DEVICE でなければならない

pdiph パラメータは、DIPROPSTRING 構造体の diph メンバへのポインタでなければならない。

DIPROP_PRODUCTNAME
これは、詳細設定の可能なアプリケーション用に設けられたプロパティであり、これを使ってデバイスの製品の登録名を変更すると、接続されている同種のデバイスを区別することができる。製品の登録名は、DIDEVICEINSTANCE 構造体の tszProductName メンバ内に返される。アプリケーションは通常、登録名を変更する必要はない。

この設定値はデバイス全体に適用されるので、割り当てられた DIPROPDWORD 構造体の dwHow メンバは、DIPH_DEVICE でなければならない

pdiph パラメータは、DIPROPSTRING 構造体の diph メンバへのポインタでなければならない。

DIPROP_RANGE
オブジェクトが報告可能な値の範囲を設定する。最小値および最大値は、割り当てられた DIPROPRANGE 構造体の lMin メンバと lMax メンバから取得される。

一部のデバイスでは、これは読み取り専用プロパティである。

範囲の大小を逆にはできない。lMax は、lMin より大きな値でなければならない。

DIPROP_SATURATION
0 ～ 10,000 の範囲でジョイスティックの飽和ゾーンの値を設定する。飽和レベルとは、軸が極限位置にあるとみなされるポイントのことである。たとえば、飽和レベルが 9,500 に設定されている場合、軸の中心 (デッド ゾーン) から軸の端までの物理的距離の 95% の位置が軸の極限位置となる。

この設定は、デバイス全体または 1 つの特定の軸のどちらかに適用できる。

pdiph
タイプ固有のプロパティ構造体に含まれる DIPROPHEADER 構造体のアドレス。

戻り値

成功した場合は、DI_OK または DI_PROPNOEFFECT を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED
DIERR_OBJECTNOTFOUND
DIERR_UNSUPPORTED

注意

バッファ サイズは、IDirectInputDevice8::GetDeviceData メソッドの前回と今回の呼び出しの間で、バッファがデータを失うことなく保持できるデータの量を決定する。この値にゼロを設定して、アプリケーションがデバイスからバッファリング データを読み込まないように指定することもできる。DIPROPDWORD 構造体の dwData メンバ中のバッファ サイズが大きすぎてデバイスがサポートできない場合は、サポート可能な最大バッファ サイズが設定される。要求したバッファ サイズが設定されたかどうかを確認するには、バッファ サイズ プロパティを取得して、設定しようとした値とその結果を比較する。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。

参照

IDirectInputDevice8::GetProperty


IDirectInputDevice8::Unacquire

入力デバイスへのアクセス権を解放する。

HRESULT Unacquire();

パラメータ

なし。

戻り値

デバイスが解放された場合は DI_OK を返し、デバイスが取得状態になかった場合は DI_NOEFFECT を返す。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


IDirectInputDevice8::WriteEffectToFile

1 つ以上のフォース フィードバック エフェクトについての情報をファイルに保存する。このファイルは、IDirectInputDevice8::EnumEffectsInFile を使って読み取ることができる。これは主に、独自のフォースを生成するアプリケーションを作成したい開発者向けのメソッドである。

HRESULT WriteEffectToFile(
  LPCSTR lpszFileName,
  DWORD dwEntries,
  LPCDIFILEEFFECT rgDiFileEft,
  DWORD dwFlags
);

パラメータ

lpszFileName
RIFF ファイルの名前。
dwEntries
rgDiFileEft 配列中の構造体の数。
rgDiFileEft
DIFILEEFFECT 構造体の配列。
dwFlags
エフェクトの記述方法を制御するフラグ。DIFEF_DEFAULT (= 0)、または次の値を取ることができる。
DIFEF_INCLUDENONSTANDARD
Microsoft® DirectInput® で定義されていないエフェクトを含める。このフラグが指定されない場合は、GUID_ConstantForce など、Dinput.h に定義された GUID を持つエフェクトのみが記述される。

戻り値

メソッドが成功した場合は、DI_OK を返す。

失敗すれば DIERR_INVALIDPARAM を返す。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。

参照

IDirectInputDevice8::EnumEffectsInFile


IDirectInputEffect

アプリケーションは、IDirectInputEffect インターフェイスのメソッドを使用して、フォース フィードバック デバイスのエフェクトを管理する。

このインターフェイスは IDirectInputDevice8::CreateEffect メソッドを使用して取得される。

IDirectInputEffect インターフェイスのメソッドは、以下のグループにまとめることができる。

エフェクトの情報 | GetEffectGuid
 | GetEffectStatus
 | GetParameters
エフェクトの操作 | Download
 | Initialize
 | SetParameters
 | Start
 | Stop
 | Unload
その他 | Escape

すべての COM インターフェイスと同様に、IDirectInputEffect インターフェイスは IUnknown インターフェイス メソッドを継承する。IUnknown インターフェイスは、以下の 3 つのメソッドをサポートする。

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTINPUTEFFECT 型は IDirectInputEffect インターフェイスへのポインタとして定義される。

typedef struct IDirectInputEffect    *LPDIRECTINPUTEFFECT;

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


IDirectInputEffect::Download

デバイスにエフェクトを設定する。同じエフェクトが既にデバイスにあれば、IDirectInputEffect::SetParameters メソッドで設定された値に適合するように、既存のエフェクトが更新される。

HRESULT Download(void);

パラメータ

なし。

戻り値

成功した場合は、DI_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DIERR_DEVICEFULL
DIERR_EFFECTPLAYING
DIERR_INCOMPLETEEFFECT
DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTEXCLUSIVEACQUIRED
DIERR_NOTINITIALIZED

S_FALSE が返された場合、そのエフェクトは既にデバイスにダウンロードされている。

注意

エフェクトの再生中にエフェクトを更新することは有効である。この操作の意味は、IDirectInputEffect::SetParameters のリファレンスの中で説明されている。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


IDirectInputEffect::Escape

ハードウェア固有のコマンドをドライバに送信する。

HRESULT Escape(
  LPDIEFFESCAPE pesc
);

パラメータ

pesc
送信するコマンドを記述する DIEFFESCAPE 構造体。成功すると、使用された出力バッファのバイト数が cbOutBuffer メンバに格納される。

戻り値

成功した場合は、DI_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DIERR_NOTINITIALIZED
DIERR_DEVICEFULL

ほかのデバイス固有エラー コードを返すこともできる。ハードウェア メーカーから詳細情報を入手すること。

注意

各ドライバは、異なるエスケープを実装しているので、正しいドライバと通信しているかどうかは、アプリケーション自体が確認しなければならない。これは、DIDEVICEINSTANCE 構造体の guidFFDriver メンバと、アプリケーションが予測している値を比較することにより確認できる。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


IDirectInputEffect::GetEffectGuid

IDirectInputEffect オブジェクトが表すエフェクトの GUID を取得する。

HRESULT GetEffectGuid(
  LPGUID pguid
);

パラメータ

pguid
このメソッドによって格納される GUID 構造体。

戻り値

成功した場合は、DI_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

注意

取得した GUID を IDirectInputDevice8::GetEffectInfo に渡すことにより、そのエフェクトに関する拡張情報を取得できる。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


IDirectInputEffect::GetEffectStatus

エフェクトのステータスを取得する。

HRESULT GetEffectStatus(
  LPDWORD pdwFlags
);

パラメータ

pdwFlags
エフェクトのステータス フラグ。ゼロ、または次のフラグを取ることができる。
DIEGES_PLAYING
エフェクトは再生中である。
DIEGES_EMULATED
エフェクトはエミュレートされている。

戻り値

成功した場合は、DI_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


IDirectInputEffect::GetParameters

エフェクトに関する情報を取得する。

HRESULT GetParameters(
  LPDIEFFECT peff,
  DWORD dwFlags
);

パラメータ

peff
エフェクト情報を受け取る DIEFFECT 構造体のアドレス。dwSize メンバは、このメソッドを呼び出す前にアプリケーションによって設定しておかなければならない。
dwFlags
エフェクト情報のどの部分を取得するかを指定するフラグ。ゼロ、または次のフラグを取ることができる。
DIEP_ALLPARAMS
ほかのすべての DIEP_* フラグの組み合わせたもので、DIEFFECT 構造体の全メンバを要求することを示す。
DIEP_ALLPARAMS_DX5
DIEP_STARTDELAY フラグを除くすべての DIEP_* フラグを組み合わせたもの。
DIEP_AXES
cAxes および rgdwAxes メンバがデータを受け取る。入力パラメータとして、cAxes は rgdwAxes が指すバッファのサイズ (DWORD 単位) を格納する。バッファが小さすぎると、このメソッドは DIERR_MOREDATA を返し、必要なバッファ サイズを cAxes に設定する。
DIEP_DIRECTION
cAxes および rglDirection メンバがデータを受け取る。入力パラメータとして、cAxes は rglDirection が指すバッファのサイズ (DWORD 単位) を格納する。バッファが小さすぎると、GetParameters メソッドは DIERR_MOREDATA を返し、必要なバッファ サイズを cAxes に設定する。

dwFlags メンバには、座標系フラグ (DIEFF_CARTESIAN、DIEFF_POLAR または DIEFF_SPHERICAL) のうち少なくとも 1 つが設定されていなければならない。Microsoft® DirectInput® は、指定された 1 つの座標系で表したエフェクトの方向を返す。その際、必要があれば座標系間で変換を行う。終了時に、dwFlags メンバには 1 つの座標系フラグが設定され、DirectInput が使用する座標系を指示する。特別に、3 つの座標系フラグすべてを渡すと、それらの座標を設定したのとまったく同じ形式で座標が取得される。

DIEP_DURATION
dwDuration メンバがデータを受け取る。
DIEP_ENVELOPE
lpEnvelope メンバは、データを受け取る DIENVELOPE 構造体を指す。エフェクトに関係するエンベロープがないときは、lpEnvelope メンバは NULL に設定される。
DIEP_GAIN
dwGain メンバがデータを受け取る。
DIEP_SAMPLEPERIOD
dwSamplePeriod メンバがデータを受け取る。
DIEP_STARTDELAY
dwStartDelay メンバがデータを受け取る。
DIEP_TRIGGERBUTTON
dwTriggerButton メンバがデータを受け取る。
DIEP_TRIGGERREPEATINTERVAL
dwTriggerRepeatInterval メンバがデータを受け取る。
DIEP_TYPESPECIFICPARAMS
lpvTypeSpecificParams メンバは、cbTypeSpecificParams メンバによりサイズが指定されるバッファを指す。リターン時、このバッファには、エフェクトに関係するタイプ固有データが格納され、cbTypeSpecificParams メンバには、コピーされたバイト数が格納される。アプリケーションで用意されたバッファが小さすぎてタイプ固有データすべてを格納できない場合、このメソッドは DIERR_MOREDATA を返し、必要とされるバッファ サイズのバイト数が cbTypeSpecificParams メンバに設定される。

戻り値

成功した場合は、DI_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DIERR_INVALIDPARAM
DIERR_MOREDATA
DIERR_NOTINITIALIZED

注意

DIERR_INVALIDPARAM エラーを発生する一般的なエラーには、DIEFFECT 構造体の dwSize メンバの未設定、無効なフラグの指定、エフェクト情報の受け取り準備上での DIEFFECT 構造体のメンバの不適正な設定、などがある。たとえば、情報が dwTriggerButton メンバに取得されるべきときは、DirectInput がボタンを記述する方法を識別できるように、dwFlags メンバには、DIEFF_OBJECTIDS または DIEFF_OBJECTOFFSETS のどちらか一方を設定しなければならない。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


IDirectInputEffect::Initialize

DirectInputEffect オブジェクトを初期化する。

HRESULT Initialize(
  HINSTANCE hinst,
  DWORD dwVersion,
  REFGUID rguid
);

パラメータ

hinst
DirectInputEffect オブジェクトを作成するアプリケーションまたは DLL のインスタンス ハンドル。Microsoft® DirectInput® は、この値を使用して、アプリケーションまたは DLL が、オブジェクト作成の資格を認められているかどうかを判断し、下位互換性のために取るべき特別な動作を確定する。DLL が親のアプリケーションのハンドルを渡すと、エラーとなる。
dwVersion
アプリケーションの設計対象である DirectInput のバージョン番号。この値は通常、DIRECTINPUT_VERSION である。以前のバージョン番号を渡すと、DirectInput がそのバージョンをエミュレートすることになる。
rguid
C++ の場合、インターフェイスが関連付けられているエフェクトを識別する GUID に対する参照値。C の場合、この GUID のアドレス。IDirectInputDevice8::EnumEffects メソッドを使用して、デバイスがどのエフェクト GUID をサポートしているかを確認できる。

戻り値

成功した場合は、DI_OK を返す。

失敗した場合は DIERR_DEVICENOTREG を返す。

注意

このメソッドが失敗する場合、基底のオブジェクトは不定の状態にあるものとみなされるので、初期化し直してからでないと以降の使用はできない。

IDirectInputDevice8::CreateEffect メソッドは、エフェクトを作成後、自動的に初期化する。アプリケーションは、通常、Initialize メソッドを呼び出す必要はない。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


IDirectInputEffect::SetParameters

エフェクトの特性を設定する。

HRESULT SetParameters(
  LPCDIEFFECT peff,
  DWORD dwFlags
);

パラメータ

peff
エフェクトの情報を格納する DIEFFECT 構造体。dwFlags パラメータの対応ビットによって指定されている任意のメンバと同様、このメソッドを呼び出す前にアプリケーションによって dwSize メンバが設定されていなければならない。
dwFlags
エフェクトの情報のどの部分を設定するかを指定し、パラメータのダウンロード処理の方法を指定するフラグ。ゼロ、または次のフラグを取ることができる。
DIEP_AXES
cAxes および rgdwAxes メンバがデータを格納する。
DIEP_DIRECTION
cAxes および rglDirection メンバがデータを格納する。dwFlags メンバが (DIEFF_CARTESIAN または DIEFF_POLAR を使用して) 値を解釈すべき座標系を指定する。
DIEP_DURATION
dwDuration メンバがデータを格納する。
DIEP_ENVELOPE
lpEnvelope メンバは、データを格納する DIENVELOPE 構造体を指す。エフェクトから既存のエンベロープを切り離すには、このフラグを渡し、lpEnvelope メンバ を NULL に設定する。
DIEP_GAIN
dwGain メンバがデータを格納する。
DIEP_NODOWNLOAD
パラメータの更新後、通常は自動実行される IDirectInputEffect::Download を抑制する。「注意」を参照すること。
DIEP_NORESTART
エフェクトの停止や再開を抑制してパラメータを変更する。「注意」を参照すること。
DIEP_SAMPLEPERIOD
dwSamplePeriod メンバがデータを格納する。
DIEP_START
パラメータの更新後、エフェクトを開始 (エフェクトが再生中であれば、再開) させる。デフォルトでは、エフェクトの再生状態は変更されない。
DIEP_STARTDELAY
dwStartDelay メンバがデータを格納する。
DIEP_TRIGGERBUTTON
dwTriggerButton メンバがデータを格納する。
DIEP_TRIGGERREPEATINTERVAL
dwTriggerRepeatInterval メンバがデータを格納する。
DIEP_TYPESPECIFICPARAMS
DIEFFECT 構造体の lpvTypeSpecificParams および cbTypeSpecificParams メンバがエフェクトのタイプ固有データのアドレスとサイズを格納する。

戻り値

成功すれば次の値のいずれかを返す。

DI_DOWNLOADSKIPPED
DI_EFFECTRESTARTED
DI_OK
DI_TRUNCATED
DI_TRUNCATEDANDRESTARTED

失敗した場合は、次のいずれかのエラー値を返す。

DIERR_NOTINITIALIZED
DIERR_INCOMPLETEEFFECT
DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_EFFECTPLAYING

注意

エフェクト用の DIEFFECTINFO 構造体の dwDynamicParams メンバは、エフェクトの再生中に動的に更新できるパラメータを指定する。

IDirectInputEffect::SetParameters メソッドは、自動的にエフェクトをダウンロードするが、この動作は、DIEP_NODOWNLOAD フラグを設定することによって抑制できる。自動ダウンロードが抑制されていれば、IDirectInputEffect::Download メソッドを起動して、エフェクトを手動でダウンロードすることができる。

エフェクトの再生中にパラメータが更新されると、エフェクトの開始時のパラメータであったかのように、新しいパラメータが有効になる。

たとえば、3 秒の継続時間を持つ周期的エフェクトが開始されていて、2 秒後に、エフェクトの方向が変更されるとする。その後、残りの 1 秒のエフェクトは、新しい方向で継続される。エンベロープ、フェーズ、振幅などのエフェクトのパラメータは、方向が変更されなかったかのように続行される。

先の例と同じ状況で、今度は 2 秒後にエフェクトの継続時間が 1.5 秒に変更されたとすると、エフェクトは停止する。

通常、ドライバが再生中のエフェクトのパラメータを更新できない場合、ドライバはそのエフェクトを停止し、パラメータを更新してからそのエフェクトを再開することができる。DIEP_NORESTART フラグを渡すと、この処理が抑制される。エフェクトの再生中にドライバがエフェクトのパラメータを更新できないときは、エラー コードの DIERR_EFFECTPLAYING が返され、パラメータは更新されない。

フラグ DIEP_NODOWNLOAD、DIEP_START、DIEP_NORESTART のうち同時に 2 つ以上を設定してはいけない(何も渡さなくてもよい)。

この 3 つのフラグは、次に示すように、ダウンロード処理と再生処理を制御する。

DIEP_NODOWNLOAD を設定すると、エフェクト パラメータは更新されるが、デバイスにダウンロードはされない。

DIEP_START フラグを設定すると、エフェクト パラメータは更新され、デバイスにダウンロードされる。そして、IDirectInputEffect::Start メソッドが dwIterations パラメータに 1 を設定し、フラグなしで呼び出された場合とまったく同じように、エフェクトが始動する。DIEP_START で更新処理を付加した方法の方が Start メソッドを呼び出す方法よりも少し高速である。これは前者の方法では、デバイスに送信する情報が少なくて済むためである。

DIEP_NODOWNLOAD と DIEP_START のどちらも設定されず、エフェクトが再生していないときは、パラメータは更新され、デバイスにダウンロードされる。

DIEP_NODOWNLOAD と DIEP_START のどちらも設定されず、エフェクトが再生中のときは、デバイスが実行中 (オンザフライ) 更新をサポートしていれば、パラメータは更新される。上記以外の場合、処理は DIEP_NORESTART フラグの状態に左右される。このフラグが設定されていれば、エラー コード DIERR_EFFECTPLAYING が返される。このフラグが設定されていなければ、エフェクトは停止し、パラメータが更新され、エフェクトが再開する。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


IDirectInputEffect::Start

エフェクトの再生を開始する。エフェクトが既に再生中ならば、最初から開始される。エフェクトがダウンロードされていないか、または前回のダウンロード以来、変更されている場合は、開始前にエフェクトがダウンロードされる。この処理はデフォルトで行われる。これを抑制するには、DIES_NODOWNLOAD フラグを渡せばよい。

HRESULT Start(
  DWORD dwIterations,
  DWORD dwFlags
);

パラメータ

dwIterations
連続してエフェクトを再生する回数。エンベロープは、補間ごとに再調整される。

エフェクトを一度だけ再生するには、1 を渡す。明示的に停止させられるまで反復再生するには、INFINITE を渡す。エンベロープを再調整しないで、明示的に停止されるまでエフェクトを再生するには、IDirectInputEffect::SetParameters メソッドを使用してエフェクト パラメータを修正した後、その dwDuration メンバを INFINITE に変更する。

dwFlags
デバイスがエフェクトをどのように再生するかを表すフラグ。値はゼロまたは次のフラグのいずれかを指定する。
DIES_SOLO
指定されたエフェクトが再生される前に、デバイス上のほかのすべてのエフェクトを停止する。このフラグを省略すると、エフェクトは、デバイス上で既に再生が始まっている既存のエフェクトと混合されることになる。
DIES_NODOWNLOAD
エフェクトの自動ダウンロードを行わない。

戻り値

成功した場合は、DI_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DIERR_INCOMPLETEEFFECT
DIERR_INVALIDPARAM
DIERR_NOTEXCLUSIVEACQUIRED
DIERR_NOTINITIALIZED
DIERR_UNSUPPORTED

注意

このメソッドを成功させるには、デバイスを排他協調レベルで取得しなければならない。

複数回の補間をサポートしないデバイスもある。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


IDirectInputEffect::Stop

エフェクトの再生を停止する。

HRESULT Stop(void);

戻り値

成功した場合は、DI_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DIERR_NOTEXCLUSIVEACQUIRED
DIERR_NOTINITIALIZED

注意

このメソッドを成功させるには、デバイスを排他協調レベルで取得しなければならない。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


IDirectInputEffect::Unload

デバイスからエフェクトを削除する。エフェクトが再生されている場合、エフェクトは、アンロードされる前に自動的に停止する。

HRESULT Unload(void);

戻り値

成功した場合は、DI_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTEXCLUSIVEACQUIRED
DIERR_NOTINITIALIZED

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


コールバック関数

次の 7 つの関数は、プロトタイプのコールバック関数であり、さまざまな列挙メソッドと共に使用する。アプリケーションではこれらのコールバック関数の 1 つを宣言できる。その際、関数の名前、定義方法は任意でよいが、パラメータのタイプと戻り値のタイプは、プロトタイプ内で同じでなくてはならない。

  • DIConfigureDevicesCallback
  • DIEnumCreatedEffectObjectsCallback
  • DIEnumDeviceObjectsCallback
  • DIEnumDevicesBySemanticsCallback
  • DIEnumDevicesCallback
  • DIEnumEffectsCallback
  • DIEnumEffectsInFileCallback


DIConfigureDevicesCallback

プロパティ シート イメージが更新されるたびに呼び出される、アプリケーション定義のコールバック関数。この関数を使用する必要があるのは、アプリケーションが独自のウィンドウにプロパティ シートを表示している場合のみである。

BOOL CALLBACK DIConfigureDevicesCallback(
  IUnknown FAR* lpDDSTarget,
  LPVOID pvRef
);

パラメータ

lpDDSTarget
IDirectInput8::ConfigureDevices に渡された DICONFIGUREDEVICESPARAMS 構造体の lpUnkDDSTarget メンバ中のサーフェスの IUnknown インターフェイスへのポインタ。
pvRef
IDirectInput8::ConfigureDevices に pvRef パラメータとして渡されるアプリケーション定義の値。

戻り値

TRUE または FALSE を返す。DirectInput® はこの戻り値を使用しない。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput8.lib を使用。


DIEnumCreatedEffectObjectsCallback

IDirectInputDevice8::EnumCreatedEffectObjects メソッドに対する呼び出し結果として DirectInputDevice エフェクトを受け取る、アプリケーション定義コールバック関数。

BOOL CALLBACK DIEnumCreatedEffectObjectsCallback(
  LPDIRECTINPUTEFFECT peff,
  LPVOID pvRef
);

パラメータ

peff
作成されたエフェクト オブジェクトへのポインタ。
pvRef
EnumCreatedEffectObjects に pvRef パラメータとして渡されるアプリケーション定義の値。

戻り値

列挙を続行する DIENUM_CONTINUE を返すか、列挙を停止する DIENUM_STOP を返す。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : ユーザー定義。


DIEnumDeviceObjectsCallback

IDirectInputDevice8::EnumObjects メソッドに対する呼び出し結果として DirectInputDevice オブジェクトを受け取る、アプリケーション定義コールバック関数。

BOOL CALLBACK DIEnumDeviceObjectsCallback(
  LPCDIDEVICEOBJECTINSTANCE lpddoi,
  LPVOID pvRef
);

パラメータ

lpddoi
列挙対象のオブジェクトを表す DIDEVICEOBJECTINSTANCE 構造体。
pvRef
EnumObjects に pvRef パラメータとして渡されるアプリケーション定義の値。

戻り値

列挙を続行する DIENUM_CONTINUE を返すか、列挙を停止する DIENUM_STOP を返す。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : ユーザー定義。


DIEnumDevicesBySemanticsCallback

IDirectInput8::EnumDevicesBySemantics メソッドに対する呼び出し結果として DirectInput® デバイスを受け取る、アプリケーション定義コールバック関数。

BOOL CALLBACK DIEnumDevicesBySemanticsCallback(
  LPCDIDEVICEINSTANCE lpddi,
  LPDIRECTINPUTDEVICE8  lpdid,
  DWORD  dwFlags,
  DWORD  dwRemaining,
  LPVOID pvRef
);

パラメータ

lpddi
デバイス インスタンスを記述する DIDEVICEINSTANCE 構造体のアドレス。
lpdid
デバイスの IDirectInputDevice8 インターフェイスへのポインタ。
dwFlags
デバイスの列挙理由に関する情報を提供するフラグ。アクション マッピング フラグの組み合わせや、1 つの利用フラグを使用できる。少なくとも 1 つのアクション マッピング フラグが常に存在する。

定義済みのアクション マッピング フラグは次のとおり。

DIEDBS_MAPPEDPRI1
優先順位 1 のアクションはデバイスにマップされるため、デバイスが列挙される。
DIEDBS_MAPPEDPRI2
優先順位 2 のアクションはデバイスにマップされるため、デバイスが列挙される。

定義済みの利用フラグは次のとおり。

DIEDBS_RECENTDEVICE
アクション マッピング フラグに指定されたコマンドが最近使用されたため、デバイスを列挙している。
DIEDBS_NEWDEVICE
デバイスが最近インストールされたため、デバイスを列挙している。このフラグに指定されたデバイスは、このゲームではこれまで使用されていない。
dwRemaining
このデバイスの後に残っている列挙対象のデバイス数。
pvRef
IDirectInput8::EnumDevicesBySemantics に pvRef パラメータとして渡されるアプリケーション定義の値。

戻り値

列挙を続行する DIENUM_CONTINUE を返すか、列挙を停止する DIENUM_STOP を返す。

注意

単一のハードウェア デバイスが、複数の DirectInput® デバイス タイプとして機能することができる場合は、サポートする各デバイス タイプごとに列挙される。たとえば、組み込みマウス付きのキーボードは、2 回列挙される。1 回は 1 つのキーボードとして、1 回は 1 つのマウスとして列挙される。ただし、製品 GUID は各デバイスに対して同じである。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : ユーザー定義。

参照

DIEnumDevicesCallback


DIEnumDevicesCallback

IDirectInput8::EnumDevices メソッドに対する呼び出し結果として DirectInput® デバイスを受け取る、アプリケーション定義コールバック関数。

BOOL CALLBACK DIEnumDevicesCallback(
  LPCDIDEVICEINSTANCE lpddi,
  LPVOID pvRef
);

パラメータ

lpddi
デバイス インスタンスを記述する DIDEVICEINSTANCE 構造体のアドレス。
pvRef
EnumDevices または EnumDevicesBySemantics に pvRef パラメータとして渡されるアプリケーション定義の値。

戻り値

列挙を続行する DIENUM_CONTINUE を返すか、列挙を停止する DIENUM_STOP を返す。

注意

単一のハードウェア デバイスが、複数の DirectInput デバイス タイプとして機能することができる場合は、サポートする各デバイス タイプごとに列挙される。たとえば、組み込みマウス付きのキーボードは、2 回列挙される。1 回は 1 つのキーボードとして、1 回は 1 つのマウスとして列挙される。ただし、製品 GUID は各デバイスに対して同じである。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : ユーザー定義。

参照

DIEnumDevicesBySemanticsCallback


DIEnumEffectsCallback

IDirectInputDevice8::EnumEffects メソッドと共に使用するアプリケーション定義コールバック関数。

BOOL CALLBACK DIEnumEffectsCallback(
  LPCDIEFFECTINFO pdei,
  LPVOID pvRef
);

パラメータ

pdei
列挙されたエフェクトを記述する DIEFFECTINFO 構造体。
pvRef
EnumEffects に pvRef パラメータとして渡されるアプリケーション定義の値。

戻り値

列挙を続行する DIENUM_CONTINUE を返すか、列挙を停止する DIENUM_STOP を返す。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : ユーザー定義。


DIEnumEffectsInFileCallback

IDirectInputDevice8::EnumEffectsInFile メソッドと共に使用するアプリケーション定義コールバック関数。

BOOL CALLBACK DIEnumEffectsInFileCallback(
  LPCDIFILEEFFECT lpDiFileEf,
  LPVOID pvRef
);

パラメータ

lpDiFileEf
列挙されたエフェクトを表す DIFILEEFFECT 構造体。
pvRef
EnumEffectsInFile に pvRef パラメータとして渡されるアプリケーション定義の値。

戻り値

列挙を続行する DIENUM_CONTINUE を返すか、列挙を停止する DIENUM_STOP を返す。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : ユーザー定義。


関数

ここでは、COM インターフェイス メソッド以外の DirectInput® 関数およびコールバック関数のリファレンスを提供する。

このカテゴリには次の関数が分類される。

  • DirectInput8Create


DirectInput8Create

DirectInput® オブジェクトを作成し、IDirectInput8 またはそれ以降のインターフェイスを返す。

HRESULT WINAPI DirectInput8Create(
  HINSTANCE hinst,
  DWORD dwVersion,
  REFIID riidltf,
  LPVOID* ppvOut,
  LPUNKNOWN punkOuter
);

パラメータ

hinst
DirectInput オブジェクトを作成するアプリケーションまたは DLL のインスタンス ハンドル。DirectInput は、この値を使用して、アプリケーションまたは DLL が、オブジェクト作成の資格を認められているかどうかを判断し、下位互換性のために取るべき特別な動作を確定する。

DLL が親のアプリケーションのハンドルを渡すと、エラーとなる。たとえば、Web ページに埋め込まれていて DirectInput を使用する ActiveX® コントロールは、Web ブラウザのハンドルではなく、それ自身のインスタンスのハンドルを渡さなければならない。これにより、DirectInput がそのコントロールを認識し、必要と思われる特別な動作をすべて有効にすることが確実になる。

dwVersion
アプリケーションの設計対象である DirectInput のバージョン番号。この値は通常、DIRECTINPUT_VERSION である。Dinput.h ファイルをインクルードする前にアプリケーションが DIRECTINPUT_VERSION を定義する場合、その値は 0x0700 以上でなければならない。以前のバージョンでは DirectInputCreateEx を使用する。これは Dinput.lib に定義されている。
riidltf
目的のインターフェイスの一意な識別子。DirectX 8.0 では、この値は IID_IDirectInput8A または IID_IDirectInput8W である。IID_IDirectInput8 定義を渡すことにより、コンパイル時に UNICODE が定義されている場合は Unicode バージョン、定義されていない場合は ANSI バージョンのインターフェイスが選択される。
ppvOut
コールの成功時にインターフェイス ポインタを受け取る変数へのポインタのアドレス。
punkOuter
COM 集成体に対する制御オブジェクトの IUnknown インターフェイスのアドレスへのポインタ。インターフェイスが集成されていない場合には NULL。普通、呼び出し側は NULL を渡す。集成が要求された場合、*ppvOut に返されるオブジェクトは、COM 集成体が要求するように、IUnknown へのポインタである。

戻り値

成功した場合は、DI_OK を返す。

失敗した場合は、次のエラー値のいずれかを返す。

DIERR_BETADIRECTINPUTVERSION
DIERR_INVALIDPARAM
DIERR_OLDDIRECTINPUTVERSION
DIERR_OUTOFMEMORY

注意

この関数が作成する DirectInput オブジェクトは、Dinput8d.dll に実装される。この実装では、DirectX 8.0 より前のバージョンのインターフェイスを取得できない。以前のバージョンを使用するには、DirectInputCreate または DirectInputCreateEx で DirectInput オブジェクトを作成する。これらは Dinput.lib にある。

punkOuter = NULL を指定してこの関数を呼び出すことは、CoCreateInstance(&CLSID_DirectInput8, punkOuter, CLSCTX_INPROC_SERVER, &IID_IDirectInput8W, lplpDirectInput) を使用してオブジェクトを作成した後、IDirectInput8::Initialize で初期化することと同等である。

punkOuter != NULL を指定してこの関数を呼び出すことは、CoCreateInstance(&CLSID_DirectInput8, punkOuter, CLSCTX_INPROC_SERVER, &IID_IUnknown, lplpDirectInput) を使用してオブジェクトを作成することと同等である。集成したオブジェクトは手動で初期化しなければならない。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。
インポート ライブラリ : dinput8.lib を使用。


マクロ

ここでは、Microsoft® DirectInput® で使用されている以下のマクロを説明する。

  • DIDFT_GETINSTANCE
  • DIDFT_GETTYPE
  • DIDFT_MAKEINSTANCE
  • DIEFT_GETTYPE
  • DIMAKEUSAGEDWORD
  • DISEQUENCE_COMPARE
  • GET_DIDEVICE_SUBTYPE
  • GET_DIDEVICE_TYPE

Dinput.h は、IDirectInput8 および IDirectInputDevice8 両インターフェイスのすべてのメソッドに対する C の呼び出しのマクロも定義する。これらのマクロを使うことで、メソッド テーブルへのポインタが不要になる。たとえば、以下は、IDirectInputDevice8::Release メソッドに対する C による呼び出しの例である。

lpdid->lpVtbl->Release(lpdid));

同等のマクロ呼び出しは、以下のような形式になる。

IDirectInputDevice8_Release(lpdid);

これらのマクロはすべて、メソッド呼び出しの場合と同一のパラメータを取る。


DIDFT_GETINSTANCE

DIDFT_GETINSTANCE マクロは、データ形式タイプからオブジェクトのインスタンス番号コードを抽出する。

DIDFT_GETINSTANCE(n) LOWORD((n) >> 8)

パラメータ

n
Microsoft® DirectInput® データ形式タイプ。このパラメータに設定可能な値は、DIOBJECTDATAFORMAT 構造体の dwType メンバの値と同じである。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。

参照

DIDFT_MAKEINSTANCE、DIDFT_GETTYPE


DIDFT_GETTYPE

DIDFT_GETTYPE マクロは、データ形式タイプからオブジェクト タイプ コードを抽出する。

DIDFT_GETTYPE(n)  LOBYTE(n)

パラメータ

n
Microsoft® DirectInput® データ形式タイプ。このパラメータに設定可能な値は、DIOBJECTDATAFORMAT 構造体の dwType メンバの値と同じである。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。

参照

DIDFT_GETINSTANCE


DIDFT_MAKEINSTANCE

DIDFT_MAKEINSTANCE マクロは、デバイス オブジェクトのインスタンス識別子を作成して、DIOBJECTDATAFORMAT 構造体の dwType メンバの中に含める。

DIDFT_MAKEINSTANCE(n) ((WORD)(n) << 8)

パラメータ

n
オブジェクトのインスタンス。たとえば、マウスのボタン 1 の場合は 1。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。

参照

DIDFT_GETINSTANCE


DIEFT_GETTYPE

DIDFT_GETTYPE マクロは、データ形式タイプからオブジェクト タイプ コードを抽出する。

DIEFT_GETTYPE(n)  LOBYTE(n)

パラメータ

n
Microsoft® DirectInput® effect format type.このパラメータが取ることができる値は、DIEFFECTINFO 構造体の dwEffType メンバの値と同じである。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


DIMAKEUSAGEDWORD

DIMAKEUSAGEDWORD マクロは、ヒューマン インターフェイス デバイスを表すデバイス オブジェクトの "使用ページ" と "使用状況" を組み合わせて、IDirectInputDevice8::GetObjectInfo メソッドに渡す。

DWORD DIMAKEUSAGEDWORD(
  WORD UsagePage,
  WORD Usage
);

パラメータ

UsagePage
デバイス オブジェクトの使用ページ。
Usage
デバイス オブジェクトの使用状況。

注意

このマクロは、Dinput.h 内で次のように宣言される。

#define DIMAKEUSAGEDWORD(UsagePage, Usage) \
        ((DWORD)MAKELONG(Usage, UsagePage))

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


DISEQUENCE_COMPARE

DISEQUENCE_COMPARE マクロは、2 つの Microsoft® DirectInput® シーケンス番号を比較して、シーケンス番号の循環を補正する。

DISEQUENCE_COMPARE(dwSequence1, cmp, dwSequence2) \
                ((int)((dwSequence1) - (dwSequence2)) cmp 0)

パラメータ

dwSequence1
比較する第 1 シーケンス番号。
cmp
比較演算子 (==、!=、<、>、<=、>=) のいずれか 1 つ。
dwSequence2
比較する第 2 シーケンス番号。

戻り値

cmp パラメータに指定され比較結果が真の場合はゼロ以外を返し、偽の場合はゼロを返す。

注意

以下の例は、dwSequence1 パラメータ値が、時間的に dwSequence2 パラメータ値に先行するかどうかをチェックする。

BOOL Sooner = (DISEQUENCE_COMPARE(dwSequence1, <, dwSequence2));

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


GET_DIDEVICE_SUBTYPE

GET_DIDEVICE_SUBTYPE マクロは、デバイス タイプ記述コードからデバイス サブタイプ コードを抽出する。

GET_DIDEVICE_SUBTYPE(dwDevType)  HIBYTE(dwDevType)

パラメータ

dwDevType
Microsoft® DirectInput® デバイス タイプ記述コード。このパラメータが取ることができる値は、DIDEVICEINSTANCE 構造体の dwDevType メンバの値と同じである。

注意

サブタイプ コードの解釈は、プライマリ タイプによって変わる。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。

参照

GET_DIDEVICE_TYPE、DIDEVICEINSTANCE


GET_DIDEVICE_TYPE

GET_DIDEVICE_TYPE マクロは、デバイス タイプ記述コードからデバイスのプライマリ タイプ コードを抽出する。

GET_DIDEVICE_TYPE(dwDevType)  LOBYTE(dwDevType)

パラメータ

dwDevType
Microsoft® DirectInput® デバイス タイプ記述コード。このパラメータが取ることができる値は、DIDEVICEINSTANCE 構造体の dwDevType メンバの値と同じである。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。

参照

GET_DIDEVICE_SUBTYPE、DIDEVICEINSTANCE


構造体

ここでは、以下の Microsoft® DirectInput® 構造体を説明する。

  • DIACTION
  • DIACTIONFORMAT
  • DICOLORSET
  • DICONDITION
  • DICONFIGUREDEVICESPARAMS
  • DICONSTANTFORCE
  • DICUSTOMFORCE
  • DIDATAFORMAT
  • DIDEVCAPS
  • DIDEVICEIMAGEINFO
  • DIDEVICEIMAGEINFOHEADER
  • DIDEVICEINSTANCE
  • DIDEVICEOBJECTDATA
  • DIDEVICEOBJECTINSTANCE
  • DIEFFECT
  • DIEFFECTINFO
  • DIEFFESCAPE
  • DIENVELOPE
  • DIFILEEFFECT
  • DIJOYSTATE
  • DIJOYSTATE2
  • DIMOUSESTATE
  • DIMOUSESTATE2
  • DIOBJECTDATAFORMAT
  • DIPERIODIC
  • DIPROPCPOINTS
  • DIPROPDWORD
  • DIPROPGUIDANDPATH
  • DIPROPHEADER
  • DIPROPPOINTER
  • DIPROPRANGE
  • DIPROPSTRING
  • DIRAMPFORCE

注 : 使用前にすべての DirectX 構造体のメモリは、ゼロに初期化されなければならない。また、dwSize メンバを含むすべての構造体は、使用前に dwSize メンバをその構造体のサイズに設定する必要がある。次の例は、DIDEVCAPS 構造体の動作を説明している。

DIDEVCAPS didevcaps; // これはまだ使用できない。

ZeroMemory(&didevcaps, sizeof(didevcaps));
didevcaps.dwSize = sizeof(didevcaps);

// これで構造体を使うことができる。


CPOINT

キャリブレーション ポイントについて説明する。DIPROPCPOINTS 構造体には、CPOINT 構造体の配列が含まれる。

typedef struct _CPOINT
{
    LONG  lP;
    DWORD dwLog;
} CPOINT, *PCPOINT;

メンバ

lP
未加工データ。
dwLog
lP 番号に関連付けられているスケーリング値。最大値に 10000 を掛けたパーセンテージ。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。

参照

CPOINT の使い方


DIACTION

ゲーム アクションとデバイス機能の 1 対 1 のマッピングを表す。DIACTIONFORMAT 構造体には、DIACTION 構造体の配列が含まれる。

typedef struct _DIACTION {
    UINT_PTR    uAppData;
    DWORD       dwSemantic;
    DWORD       dwFlags;
    union {
        LPCSTR  lptszActionName;
        UINT    uResIdString;
    };
    GUID        guidInstance;
    DWORD       dwObjID;
    DWORD       dwHow;
} DIACTION, *LPDIACTION;

typedef const DIACTION *LPCDIACTION;

メンバ

uAppData
アクションに関連付けられたコントロールの状態が変化するときに、IDirectInputDevice8::GetDeviceData がアプリケーションに返す、アプリケーション定義の UINT 値のアドレス。この値は DIDEVICEOBJECTDATA 構造体の uAppData メンバに返される。通常、この値はデバイス オブジェクトに関連付けられたアプリケーション固有のアクションの識別子であるが、関数ポインタも使用できる。
dwSemantic
ジョイスティックの場合、このアプリケーション ジャンルに定義された仮想コントロールを表すアクション マッピング定数、またはそのジャンルに定義されていないコントロールの定数。キーボード、マウス、または Microsoft® DirectPlay® 音声デバイスの場合、特定のデバイス オブジェクトを表す定数。「アクション マッピング定数」を参照すること。
dwFlags
特定の属性または処理を要求するために使用されるフラグ。ゼロ、または次のフラグを指定する。
DIA_APPFIXED
Microsoft DirectInput® でアクションのマッピングを変更することはできない。
DIA_APPMAPPED
dwObjID メンバが有効であり、IDirectInputDevice8::BuildActionMap はアプリケーション定義のマッピングを上書きしない。
DIA_APPNOMAP
このアクションをマップしない。
DIA_FORCEFEEDBACK
アクションをアクチュエータまたはトリガにマップする。
DIA_NORANGE
このアクションにはデフォルトの範囲を設定しない。このフラグは絶対軸アクションにのみ設定できる。
lptszActionName
アプリケーション定義のアクション名。この文字列は、IDirectInput8::ConfigureDevices の呼び出し時にデバイスのプロパティ シートに表示される。
uResIdString
このアクションで使用される文字列のリソース識別子。このリソースのモジュール インスタンスは、この構造体を含む DIACTIONFORMAT 構造体の hInstString メンバ内に指定される。
guidInstance
特定のデバイスが要求されている場合、デバイスのインスタンス GUID。それ以外の場合は GUID_NULL。
dwObjID
コントロール識別子。DIDFT_GETINSTANCE および DIDFT_GETTYPE マクロを使って、この値からインスタンスとタイプを取得する。
dwHow
アクションを構成するために DirectInput で使用されたマッピングの仕組みを示す値。IDirectInputDevice8::BuildActionMap がこの構造体を返すときに、このメンバが設定される。次の値が定義されている。
DIAH_APPREQUESTED
アプリケーションがマッピングを構成し、BuildActionMap の呼び出し時にデバイス (guidInstance) およびデバイス オブジェクト (dwObjID) が指定された。
DIAH_DEFAULT
ほかのマッピング情報がないため、DirectInput がマッピングを決定した。
DIAH_ERROR
エラーが発生した。アクションがデバイスのコントロールと一致しない。アクション マップの設定時に、このアクションは無視される。
DIAH_HWAPP
このゲームのハードウェア メーカーがマッピングを指定した。
DIAH_HWDEFAULT
このジャンルのハードウェア メーカーがマッピングを指定した。
DIAH_UNMAPPED
適切なデバイス オブジェクトが見つからなかった。
DIAH_USERCONFIG
ユーザーがマッピングを構成した。

アクション マップが IDirectInputDevice8::SetActionMap に渡される場合、このメンバは無視される。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。

参照

IDirectInput8::EnumDevicesBySemantics、IDirectInputDevice8::SetActionMap、IDirectInput8::ConfigureDevices、IDirectInputDevice8::BuildActionMap、アクション マッピング


DIACTIONFORMAT

呼び出し元アプリケーションに関する情報を格納し、ジャンルのアクションとコントロールのマッピングを定義する DIACTION 構造体配列のコンテナとして動作する。

typedef struct {
    DWORD              dwSize;
    DWORD              dwActionSize;
    DWORD              dwDataSize;
    DWORD              dwNumActions;
    LPDIACTION         rgoAction;
    GUID               guidActionMap;
    DWORD              dwGenre;
    DWORD              dwBufferSize;
    OPTIONAL LONG      lAxisMin;
    OPTIONAL LONG      lAxisMax;
    OPTIONAL HINSTANCE hInstString;
    FILETIME           ftTimeStamp;
    DWORD              dwCRC;
    TCHAR              tszActionMap[MAX_PATH];
} DIACTIONFORMAT;

メンバ

dwSize
DIACTIONFORMAT 構造体のサイズをバイト単位で指定する DWORD 値。
dwActionSize
DIACTION 構造体のサイズをバイト単位で指定する DWORD 値。
dwDataSize
デバイスの直接データを使用するデバイスが返す、デバイス データのサイズを、バイト単位で指定する DWORD 値。このメンバは、dwNumActions を 4 倍した値である。
dwNumActions
rgoAction 配列の要素数を指定する DWORD 値。
rgoAction
DIACTION 構造体の配列のアドレス。各構造体が、アクションと仮想コントロールまたはデバイス オブジェクトのマップ方法、およびマッピング情報のユーザーに対する表示方法を表す。
guidActionMap
アクション マップを識別する GUID。デバイス メーカーはこの値を使って特定のタイトルのマッピングを調整できる。
dwGenre
アプリケーションのジャンルを指定する DWORD 値。使用できる値については、「アクション マッピング定数」を参照すること。
dwBufferSize
アクション マップが適用される各デバイスの、バッファ内の入力データ パケット数を指定する DWORD 値。IDirectInputDevice8::GetDeviceData でデータを取得するために、バッファ サイズをゼロより大きい値に設定する必要がある。IDirectInputDevice8::SetActionMap を呼び出す前に、アプリケーションがこのメンバに目的のバッファ サイズを設定する場合、IDirectInputDevice8::SetProperty で DIPROP_BUFFERSIZE プロパティを設定する必要はない。
lAxisMin
すべての軸で取得される計測データの範囲の最小値。DIACTION.dwFlags に DIA_NORANGE フラグが設定された場合、この値は特定のアクション軸に対して無視される。

この値は、軸アクションに対してのみ有効であり、その他のすべての操作に対しては 0 に設定する必要がある。IDirectInputDevice8::SetActionMap でアクション マップを適用するときに、絶対軸に範囲プロパティを設定するために DIPROPRANGE.lMin 値として使用される。

lAxisMax
すべての軸で取得される計測データの範囲の最大値。DIACTION.dwFlags に DIA_NORANGE フラグが設定された場合、この値は特定のアクション軸に対して無視される。

この値は、軸アクションに対してのみ有効であり、その他のすべての操作に対しては 0 に設定する必要がある。IDirectInputDevice8::SetActionMap でアクション マップを適用するときに、絶対軸に範囲プロパティを設定するために DIPROPRANGE.lMax 値として使用される。

hInstString
各アクションの DIACTION 構造体の uResIdString メンバに指定された、アクション名の文字列リソースを格納するモジュールのハンドル。アクション名が各アクションの DIACTION 構造体の lptszActionName メンバに指定されている場合はゼロでよい。
ftTimeStamp
アクション マップが最後にディスクに書き込まれた時刻を受け取る FILETIME 構造体。「注意」を参照すること。
dwCRC
このマップの巡回冗長検査 (CRC)。マッピング セットをディスクに保存する時期を決定するために、Microsoft® DirectInput® が内部的に使用する。
tszActionMap
このアクション マップの登録名を指定する、最大長 MAX_PATH の NULL 終端文字列。この文字列は、デフォルト プロパティ シートのドロップダウン リスト ボックスに表示される。

注意

ftTimeStamp メンバには、新規デバイスや未使用デバイスに適用する特殊値を格納できる。新規デバイスとは、このアプリケーションでは列挙されておらず、アクション マップが適用されていないデバイスである。未使用デバイスとは、以前にこのアプリケーションで列挙されているが、アクション マップが適用されていないデバイスである。新規デバイスの場合、FILETIME 構造体の、下の DWORD と上の DWORD に、それぞれ DIAFTS_NEWDEVICELOW と DIAFTS_NEWDEVICEHIGH が常に設定されており、未使用デバイスの場合は、ここに DIAFTS_UNUSEDDEVICELOW と DIAFTS_UNUSEDDEVICEHIGH が設定されている。

アプリケーションは新規デバイスの有無をチェックするために ftTimeStamp を使用するべきではない。この方法の代わりに、列挙コールバック関数で DIEDBS_RECENTDEVICE と DIEDBS_NEWDEVICE フラグが返されたかどうかを見る必要がある。詳細については、「DIEnumDevicesBySemanticsCallback」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。

参照

IDirectInput8::EnumDevicesBySemantics、IDirectInputDevice8::SetActionMap、IDirectInput8::ConfigureDevices、IDirectInputDevice8::BuildActionMap、アクション マッピング


DICOLORSET

デバイス構成ユーザー インターフェイスを描画する配色を表す。これは DICONFIGUREDEVICESPARAMS 構造体の一部である。

typedef struct _DICOLORSET {
    DWORD    dwSize
    D3DCOLOR cTextFore;
    D3DCOLOR cTextHighlight;
    D3DCOLOR cCalloutLine;
    D3DCOLOR cCalloutHighlight;
    D3DCOLOR cBorder;
    D3DCOLOR cControlFill;
    D3DCOLOR cHighlightFill;
    D3DCOLOR cAreaFill;
} DICOLORSET, *LPDICOLORSET;

typedef const DICOLORSET *LPCDICOLORSET;

メンバ

dwSize
この構造体のバイト単位のサイズ。
cTextFore
テキストの前景色。
cTextHighlight
強調テキストの前景色。
cCalloutLine
コールアウト線の表示に使用される色。
cCalloutHighlight
コールアウト線の表示に使用される色。
cBorder
枠線の色。タブやボタンなどのコントロールを囲む線を表示するために使用される。
cControlFill
タブやボタンなどのコントロールの塗りつぶしの色。
cHighlightFill
強調テキストの塗りつぶしの色。
cAreaFill
タブやボタンなどのコントロールの外側の塗りつぶしの色。

注意

テキストの背景色は常に透明である。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。

参照

D3DCOLOR


DICONDITION

DIEFT_CONDITION としてマークされているエフェクトのタイプ固有の情報を格納する。

エフェクトに関する DICONDITION 構造体の配列へのポインタは、DIEFFECT 構造体の lpvTypeSpecificParams メンバに渡される。配列の要素数は、エフェクトに関連付けられた軸の数に等しくなければならない。

typedef struct DICONDITION {
    LONG  lOffset;
    LONG  lPositiveCoefficient;
    LONG  lNegativeCoefficient;
    DWORD dwPositiveSaturation;
    DWORD dwNegativeSaturation;
    LONG  lDeadBand;
} DICONDITION, *LPDICONDITION;

typedef const DICONDITION *LPCDICONDITION;

メンバ

lOffset
-10,000 ～ 10.000 の範囲にある、条件のオフセット。
lPositiveCoefficient
-10,000 ～ 10.000 の範囲にある、オフセットの正側の係数定数。
lNegativeCoefficient
-10,000 ～ 10.000 の範囲にある、オフセットの負側の係数定数。

デバイスが正と負に分かれた係数をサポートしていない場合、lNegativeCoefficient 値は無視され、lPositiveCoefficient 値が正負両方の係数として使用される。

dwPositiveSaturation
0 ～ 10,000 の範囲にある、オフセットの正側の最大フォース出力。

デバイスがフォースの飽和をサポートしない場合、このメンバ値は無視される。

dwNegativeSaturation
0 ～ 10,000 の範囲にある、オフセットの負側の最大フォース出力。

デバイスがフォースの飽和値をサポートしない場合、このメンバ値は無視される。

デバイスが正と負に分かれた飽和値をサポートしていない場合、dwNegativeSaturation 値は無視され、dwPositiveSaturation 値が正負両方の飽和値として使用される。

lDeadBand
0 ～ 10,000 の範囲にある、条件がアクティブでない lOffset 周辺の領域。すなわち、lOffset - lDeadBand と lOffset + lDeadBand の間では、条件はアクティブではない。

注意

条件のタイプが異なれば、パラメータの意味も異なるが、基本的な考え方は、条件に起因するフォースは、A(q - q0) に等しくなるということである。ここで、A は、スケーリング係数、q はある距離であり、q0 は、その距離に対する中立値である。

上記の単純な式は、デッドバンドにゼロ以外の値が指定された場合は調整しなければならない。距離が lOffset - lDeadBand より小さければ、生成されるフォースは、次の式で示される。

force = lNegativeCoefficient * (q - (lOffset - lDeadBand))

同様に、距離が lOffset + lDeadBand より大きければ、生成されるフォースは、次の式で示される。

force = lPositiveCoefficient * (q - (lOffset + lDeadBand))

スプリング条件は、軸の位置を距離として使用する。

ダンパ条件は、軸の速度を距離として使用する。

慣性条件は、軸の加速度を距離として使用する。

配列に含まれる DICONDITION 構造体の数が、エフェクトに対する軸の数と等しい場合、第 1 の構造体は第 1 の軸に適用され、第 2 の構造体は第 2 の軸に適用される。それ以降も同様の対応関係を保つ。たとえば、2 軸のスプリング条件で、両方の DICONDITION 構造体で lOffset がゼロに設定されていれば、ジョイスティックの自動センタリング スプリングと同じエフェクトが得られる。このように、1 つの条件がそれぞれの軸に対して定義されている場合、エフェクトは回転しない。

2 つ以上の軸を持つエフェクトに対して DICONDITION 構造体 が 1 つの場合、DICONDITION 構造体のパラメータが有効となる方向は、DIEFFECT 構造体の rglDirection フィールドに渡される方向パラメータによって決定される。たとえば、45 度 (極座標で) 回転する摩擦条件は、北東から南西への方向のジョイスティックの動きには抵抗するだろうが、北西から南東への方向のジョイスティックの動きにはなんら作用を及ぼさないだろう。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


DICONFIGUREDEVICESPARAMS

デバイス構成プロパティ シートに関する情報を格納する。IDirectInput8::ConfigureDevices メソッドで使用される。

typedef struct _DICONFIGUREDEVICESPARAMS {
    DWORD            dwSize;
    DWORD            dwcUsers;
    LPSTR            lptszUserNames;
    DWORD            dwcFormats;
    LPDIACTIONFORMAT lprgFormats;
    HWND             hwnd;
    DICOLORSET       dics;
    IUnknown FAR *   lpUnkDDSTarget;
} DICONFIGUREDEVICESPARAMS, *LPDICONFIGUREDEVICESPARAMS;

メンバ

dwSize
この構造体のバイト単位のサイズ。
dwcUsers
lptszUserNames が指すバッファに含まれるユーザー名の数。lptszUserNames が NULL である場合 (デフォルト ユーザー名が使用されることを示す)、このメンバの値は無視される。dwcUsers の値が、実際にバッファ内にあるエントリの数より大きい場合、メソッドは失敗し、DIERR_INVALIDPARAM を返す。
lptszUserNames
一連の NULL 終端名前文字列を格納するバッファへのポインタ。二重 NULL ターミネータによって指定される最後の要素である。lptszUserNames パラメータを NULL に設定し、デフォルト名の使用を指定することができる。アプリケーションが指定数以上の名前を渡す場合、指定数内の名前だけが使用される。アプリケーションが現在デバイスに割り当てられた名前とは異なる名前を指定する場合、すべてのデバイスで所有権が取り消され、一致しない名前用にデフォルト名が作成され、すべてのデバイスでインターフェイスに "(No User)" が表示される。
dwcFormats
lprgFormats が指す配列内の構造体の数。
lprgFormats
ゲームで使用される各ジャンルのアクション マッピング情報を格納する DIACTIONFORMAT 構造体の配列へのポインタ。入力時、この配列にはアクションとコントロールのマッピング、および各マッピングのコールアウトとして表示する文字列が格納される。構成インターフェイスでは、ドロップダウン リストに配列内と同じ順序でジャンルが表示される。
hwnd
呼び出し元アプリケーションの最上位ウィンドウへのハンドル。このメンバが必要なのは、アプリケーションがウィンドウ表示モードで稼働している場合のみであり、それ以外は無視される。
dics
構成ユーザー インターフェイスに適用する配色を表す DICOLORSET 構造体。ゼロで初期化された DICOLORSET 構造体を渡すと、デフォルトの配色が使用される。
lpUnkDDSTarget
構成ユーザー インターフェイスのイメージが格納される Microsoft® DirectDraw® または Microsoft Direct3D® ターゲット サーフェス オブジェクトの IUnknown インターフェイスへのポインタ。このイメージは、DIEnumDevicesBySemanticsCallback 関数が呼び出された時点におけるユーザー インターフェイスの現在の状態を表す。ターゲット サーフェスは、前の DICOLORSET 構造体の一部として渡されたアルファ情報と、ハードウェア メーカーによってデバイス イメージにエンコードされたアルファ情報を保持する。IUnknown インターフェイスが参照するターゲット サーフェス オブジェクトは、IDirect3DSurface8 または IDirectDrawSurface7 をサポートする必要がある。DirectDraw を使用するフルスクリーン アプリケーションは、DDSCAPS_SYSTEMEMORY フラグを使って作成されたターゲット サーフェスを持つ必要がある。

DirectDraw を使用しないアプリケーションと、DirectDraw を使用するが、全画面を使用するのではなくウィンドウ化して実行されるアプリケーションは、このパラメータに NULL を渡すことができる。その場合、Microsoft DirectInput® は Windows GDI (Graphics Device Interface) 関数を使用して構成ユーザー インターフェイス イメージを描画する。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


DICONSTANTFORCE

DIEFT_CONSTANTFORCE としてマークされているエフェクトのタイプ固有の情報を格納する。

この構造体は、コンスタント フォース エフェクトを表す。

エフェクトに関する単一の DICONSTANTFORCE 構造体へのポインタは、DIEFFECT 構造体の lpvTypeSpecificParams メンバに渡される。

typedef struct DICONSTANTFORCE {
    LONG lMagnitude;
} DICONSTANTFORCE, *LPDICONSTANTFORCE;

typedef const DICONSTANTFORCE *LPCDICONSTANTFORCE;

メンバ

lMagnitude
-10.000 ～ 10,000 の範囲にある、エフェクトのマグニチュード。エンベロープがこのエフェクトに適用されていれば、この値は、維持期間のマグニチュードを表す。エンベロープの適用がなければ、この値は、エフェクト全体の振幅を表す。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


DICUSTOMFORCE

DIEFT_CUSTOMFORCE としてマークされているエフェクトのタイプ固有の情報を格納する。

この構造体は、カスタムまたはユーザー定義フォースを表す。

エフェクトの DICUSTOMFORCE 構造体へのポインタは、DIEFFECT 構造体の lpvTypeSpecificParams メンバに渡される。

typedef struct DICUSTOMFORCE {
    DWORD  cChannels;
    DWORD  dwSamplePeriod;
    DWORD  cSamples;
    LPLONG rglForceData;
} DICUSTOMFORCE, *LPDICUSTOMFORCE;

typedef const DICUSTOMFORCE *LPCDICUSTOMFORCE;

メンバ

cChannels
このフォースによって影響されるチャネル (軸) の数。

1 番目のチャネルが、エフェクトに関連付けられた 1 番目の軸に適用され、2 番目のチャネルが 2 番目の軸に適用されるというように続く。軸よりもチャネルの数が少なければ、余分な軸に対する関連付けは行われない。

チャネルが 1 つしか存在しなければ、エフェクトは、DIEFFECT 構造体の rglDirection メンバが指定する方向に回転する。複数のチャネルがあると、回転できない。

カスタム エフェクトの回転をサポートしていないデバイスもある。

dwSamplePeriod
マイクロ秒単位のサンプリング間隔。
cSamples
rglForceData 内のサンプルの合計数。cChannels の整数倍でなければならない。
rglForceData
カスタム フォースを表すフォース値の配列へのポインタ。複数のチャネルが指定されていれば、値は、順番に割り当てられる。たとえば、cChannels が 3 の場合には、配列の 1 番目の要素は 1 番目のチャネルに、2 番目の要素は 2 番目のチャネルに、3 番目の要素は 3 番目のチャネルにそれぞれ属する。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


DIDATAFORMAT

デバイスのデータ形式を表す。この構造体は、IDirectInputDevice8::SetDataFormat メソッドで使用する。

typedef struct DIDATAFORMAT {
    DWORD dwSize;
    DWORD dwObjSize;
    DWORD dwFlags;
    DWORD dwDataSize;
    DWORD dwNumObjs;
    LPDIOBJECTDATAFORMAT rgodf;
} DIDATAFORMAT, *LPDIDATAFORMAT;

typedef const DIDATAFORMAT *LPCDIDATAFORMAT;

メンバ

dwSize
この構造体のバイト単位のサイズ。
dwObjSize
DIOBJECTDATAFORMAT 構造体のバイト単位のサイズ。
dwFlags
データ形式のほかの属性を表すフラグ。この値は、次のいずれか 1 つである。
DIDF_ABSAXIS
軸は絶対モードにある。データ形式にこのフラグを設定することは、IDirectInputDevice8::SetProperty メソッドを使用して軸モード プロパティを手動で設定することに等しい。この値は、DIDF_RELAXIS フラグと組み合わせることはできない。
DIDF_RELAXIS
軸は相対モードにある。データ形式にこのフラグを設定することは、IDirectInputDevice8::SetProperty メソッドを使用して軸モード プロパティを手動で設定することに等しい。この値は、DIDF_ABSAXIS フラグと組み合わせることはできない。
dwDataSize
デバイスが返すデータ パケットのバイト単位のサイズ。この値は、4 の倍数、かつデータ パケット内のオブジェクト データの最大オフセット値より大きくなければならない。
dwNumObjs
rgodf 配列中のオブジェクト数。
rgodf
DIOBJECTDATAFORMAT 構造体の配列のアドレス。各構造体は、1 つのオブジェクト データがデバイス データの中でどのように報告されるのかを記述する。典型的なエラーとしては、2 種類の情報を同じ位置に格納したり、1 種類の情報を複数の位置に格納したりするものがある。

注意

アプリケーションは、通常、DIDATAFORMAT 構造体を作成する必要はない。アプリケーションは、事前定義されたグローバル データ形式変数の c_dfDIMouse、c_dfDIMouse2、c_dfDIKeyboard、c_dfDIJoystick、c_dfDIJoystick2 のいずれかを使用できるからである。

以下の例では、2 つの軸 (絶対座標で報告される) と 2 つのボタンを必要とするアプリケーションが使用できるデータ形式を設定している。

// アプリケーションが次の構造体を使って、
// デバイス データを読み取ると仮定する。

typedef struct MYDATA {
    LONG  lX;                   // x 軸がここにくる。
    LONG  lY;                   // y 軸がここにくる。
    BYTE  bButtonA;             // 1 つのボタンがここにくる。
    BYTE  bButtonB;             // 別のボタンがここにくる。
    BYTE  bPadding[2];          // サイズは、DWORD の倍数でなければならない。
} MYDATA;

// 次のデータ形式を使用できる。

DIOBJECTDATAFORMAT rgodf[ ] = {
  { &GUID_XAxis, FIELD_OFFSET(MYDATA, lX),
    DIDFT_AXIS | DIDFT_ANYINSTANCE, 0, },
  { &GUID_YAxis, FIELD_OFFSET(MYDATA, lY),
    DIDFT_AXIS | DIDFT_ANYINSTANCE, 0, },
  { &GUID_Button, FIELD_OFFSET(MYDATA, bButtonA),
    DIDFT_BUTTON | DIDFT_ANYINSTANCE, 0, },
  { &GUID_Button, FIELD_OFFSET(MYDATA, bButtonB),
    DIDFT_BUTTON | DIDFT_ANYINSTANCE, 0, },
};
#define numObjects (sizeof(rgodf) / sizeof(rgodf[0]))

DIDATAFORMAT df = {
    sizeof(DIDATAFORMAT),       // この構造体のサイズ
    sizeof(DIOBJECTDATAFORMAT), // オブジェクト データ形式のサイズ
    DIDF_ABSAXIS,               // 絶対軸の座標
    sizeof(MYDATA),             // デバイス データのサイズ
    numObjects,                 // オブジェクト数
    rgodf,                      // その位置
};

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。

参照

DIACTIONFORMAT


DIDEVCAPS

Microsoft® DirectInput® デバイスの能力を表す。この構造体は、IDirectInputDevice8::GetCapabilities メソッドで使用される。

typedef struct DIDEVCAPS {
    DWORD dwSize;
    DWORD dwFlags;
    DWORD dwDevType;
    DWORD dwAxes;
    DWORD dwButtons;
    DWORD dwPOVs;
    DWORD dwFFSamplePeriod;
    DWORD dwFFMinTimeResolution;
    DWORD dwFirmwareRevision;
    DWORD dwHardwareRevision;
    DWORD dwFFDriverVersion;
} DIDEVCAPS, *LPDIDEVCAPS;

メンバ

dwSize
この構造体のバイト単位のサイズ。IDirectInputDevice8::GetCapabilities メソッドに呼び出す前に、アプリケーションは、このメンバを初期化しておかなければならない。
dwFlags
デバイスに関連付けられたフラグ。この値は、以下の定数の組み合わせとなる。
DIDC_ALIAS
デバイスは、別の DirectInput デバイスの複製である。別名のデバイスは、デフォルトでは IDirectInput8::EnumDevices によって列挙されない。
DIDC_ATTACHED
デバイスは、物理的にアタッチ状態にある。
DIDC_DEADBAND
デバイスは、少なくとも 1 つのフォース フィードバック条件でデッドバンドをサポートしている。
DIDC_EMULATED
このフラグが設定されると、データは HID (Human Interface Device) などのユーザー モード デバイス インターフェイスから、またはほかのリング 3 の手段により入力される。フラグが設定されない場合、データはカーネル モード ドライバから直接入力される。
DIDC_FORCEFEEDBACK
デバイスは、フォース フィードバックをサポートする。
DIDC_FFFADE
フォース フィードバック システムは、少なくとも 1 つのエフェクトに対するフェード パラメータをサポートする。デバイスがフェードをサポートしない場合、デバイスは、DIENVELOPE 構造体のフェード レベルとフェード時間の両パラメータを無視する。

IDirectInputDevice8::GetEffectInfo メソッドの呼び出し後、個別のエフェクトがフェードをサポートしていれば、DIEFT_FFFADE フラグが設定される。

DIDC_FFATTACK
フォース フィードバック システムは、少なくとも 1 つのエフェクトに対するアタック パラメータをサポートする。デバイスがアタックをサポートしない場合、デバイスは、DIENVELOPE 構造体のアタック レベルとアタック時間の両パラメータを無視する。

IDirectInputDevice8::GetEffectInfo メソッドの呼び出し後、個別のエフェクトがアタックをサポートしていれば、DIEFT_FFATTACK フラグが設定される。

DIDC_HIDDEN
デバイス ドライバがキーボード イベントやマウス イベントを生成できるように作成された仮想デバイス。そのようなデバイスは通常、IDirectInput8::EnumDevices によって列挙されたり、IDirectInput8::ConfigureDevices によって構成されたりしない。
DIDC_PHANTOM
将来存在する可能性のあるデバイス用のプレースホルダ。仮想デバイスは、デフォルトでは IDirectInput8::EnumDevices によって列挙されない。
DIDC_POLLEDDATAFORMAT
現状のデータ形式で少なくとも 1 つのオブジェクトが、割り込み駆動ではなく、ポーリングされる。これらのオブジェクトのために、アプリケーションは明示的に IDirectInputDevice8::Poll メソッドを呼び出して、データを取得しなければならない。
DIDC_POLLEDDEVICE
デバイス上の少なくとも 1 つのオブジェクトが、割り込み駆動ではなく、ポーリングされる。これらのオブジェクトのために、アプリケーションは明示的に IDirectInputDevice8::Poll メソッドを呼び出して、データを取得しなければならない。HID デバイスは、ポーリング オブジェクトと非ポーリング オブジェクトを混在して格納できる。
DIDC_POSNEGCOEFFICIENTS
フォース フィードバック システムは、少なくとも 1 つの条件に対して条件の 2 つの係数値をサポートする (一方は、軸の正移動、他方は、軸の負移動)。デバイスが一方の係数しかサポートしていない場合、DICONDITION 構造体の負の係数は無視される。

IDirectInputDevice8::GetEffectInfo メソッドの呼び出し後、個別の条件が正と負の係数を別々にサポートしていれば、その条件では、DIEFT_POSNEGCOEFFICIENTS フラグが設定される。

DIDC_POSNEGSATURATION
フォース フィードバック システムは、少なくとも 1 つの条件に対して、正負の両方のフォース出力に対する最大飽和をサポートする。デバイスが一方の飽和値しかサポートしていない場合、DICONDITION 構造体の負の飽和値は無視される。

IDirectInputDevice8::GetEffectInfo メソッドの呼び出し後、個別の条件が正と負の飽和値を別々にサポートしていれば、その条件では、DIEFT_POSNEGSATURATION フラグが設定される。

DIDC_SATURATION
フォース フィードバック システムは、少なくとも 1 つの条件に対して条件エフェクトの飽和をサポートする。デバイスが飽和をサポートしていなければ、ある条件のもとで生成されるフォースは、デバイスが生成できる最大フォースによってのみ制限される。

IDirectInputDevice8::GetEffectInfo メソッドの呼び出し後、個別の条件が飽和をサポートしていれば、その条件では DIEFT_SATURATION フラグが設定される。

DIDC_STARTDELAY
フォース フィードバック システムは、少なくとも 1 つのエフェクトに対する遅延パラメータをサポートする。デバイスが開始遅延をサポートしない場合、DIEFFECT 構造体の dwStartDelay メンバは無視される。
dwDevType
デバイス タイプ指定子。このメンバは、DIDEVICEINSTANCE 構造体の dwDevType メンバと同等な値を格納できる。
dwAxes
デバイス上で使用可能な軸の数。
dwButtons
デバイス上で使用可能なボタンの数。
dwPOVs
デバイス上で使用可能な視点コントローラの数。
dwFFSamplePeriod
未加工のフォース コマンドを連続して再生する際の間隔を表す、マイクロ秒単位の最小時間。
dwFFMinTimeResolution
マイクロ秒単位のデバイスの分解能の最小時間。デバイスは、すべての時間を最も近い増加値に丸める。たとえば、dwFFMinTimeResolution の値が 1000 の場合には、デバイスはすべての時間を最も近いミリ秒に丸める。
dwFirmwareRevision
デバイスのファームウェア リビジョン番号。
dwHardwareRevision
デバイスのハードウェア リビジョン番号。
dwFFDriverVersion
デバイス ドライバのバージョン番号。

注意

バージョン番号の付け方はデバイス メーカーによって異なる。確実なのは、新しいバージョンには以前のバージョンよりも大きい数字が付く、ということだけである。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。

参照

DIDEVICEINSTANCE


DIDEVICEIMAGEINFO

デバイス イメージを表示、またはイメージにコールアウトをオーバーレイするために必要な情報を格納する。この構造体は、DIDEVICEIMAGEINFOHEADER 構造体内の配列として IDirectInputDevice8::GetImageInfo メソッドに渡される。

typedef struct _DIDDEVICEIMAGEINFO {
    TCHAR  tszImagePath[MAX_PATH];
    DWORD  dwFlags;
    // dwFlags に DIDIFT_OVERLAY が存在する場合、
    // 次のコードは有効である。
    DWORD  dwViewID;
    RECT   rcOverlay;
    DWORD  dwObjID;
    DWORD  dwcValidPts;
    POINT  rgptCalloutLine[5];
    RECT   rcCalloutRect;
    DWORD  dwTextAlign;
} DIDEVICEIMAGEINFO, * LPDIDEVICEIMAGEINFO;

メンバ

tszImagePath
デバイスのイメージを含むファイルの完全修飾パス。ファイル フォーマットは dwFlags で指定する。デバイスで利用可能なイメージがなければ、このメンバには NULL が設定される。その場合、デバイスのコントロールの列挙と、デバイス コントロールに対するデフォルトのアクション一覧の表示は、アプリケーション側で行う必要がある (Microsoft® DirectX® 8.0 より前のほとんどのアプリケーションで使われていた方法と同様)。
dwFlags
イメージの使用目的を記述したフラグ。
DIDIFT_CONFIGURATION
ファイルは、デバイスに対するアクションの現在構成を表示するために使用される。オーバーレイ イメージの座標は、構成イメージの左上隅を起点とする相対座標である。
DIDIFT_OVERLAY
ファイル (指定されている場合) は、構成イメージのオーバーレイである。dwViewID、rcOverlay、dwObjID、rgptCalloutLine、rcCalloutRect、および dwTextAlign の各メンバは有効であり、これらに格納されたデータを使って、デバイスの単一コントロールのオーバーレイとコールアウト情報が表示される。ファイルが指定されない場合 (パス文字列が NULL)、rcOverlay 以外の関連するその他すべてのメンバが使用される。
dwViewID
デバイス ビュー イメージ (DIDIFT_CONFIGURATION) の場合、これはデバイス ビューの ID である。デバイス コントロール オーバーレイ (DIDIFT_OVERLAY) の場合、この値はデバイス ビューを ID によって参照する。デバイス ビューによって、イメージとコールアウト情報が表示される。
rcOverlay
デバイス構成イメージの左上ピクセルを原点とする相対座標を使って、オーバーレイ イメージをペイントする対象の長方形。このメンバは、dwFlags に DIDIFT_OVERLAY フラグが含まれる場合にのみ有効である。
dwObjID
このデバイスのオーバーレイ イメージが対応するコントロール識別子。DIDFT_* フラグとインスタンス値の組み合わせである。アプリケーションは DIDFT_GETINSTANCE および DIDFT_GETTYPE マクロを使って、この値から構成部分を読み取る。このメンバは、dwFlags に DIDIFT_OVERLAY フラグが含まれる場合にのみ有効である。
dwcValidPts
rgptCalloutLine が指す配列のポイント数。
rgptCalloutLine
コールアウト線を描画するポイントの座標を指定する POINT 構造体の配列。コールアウト線は、デバイス コントロールと、ゲーム アクションのキャプションを結ぶ線である。各線は、1 ～ 4 のセグメントを持つことができる。このメンバは、dwFlags に DIDIFT_OVERLAY フラグが含まれる場合にのみ有効である。
rcCalloutRect
ゲーム アクションの文字列が表示される長方形を表す RECT 構造体。文字列が長方形内に納まらない場合は、アプリケーション側でクリッピングを処理する必要がある。このメンバは、dwFlags に DIDIFT_OVERLAY フラグが含まれる場合にのみ有効である。
dwTextAlign
rcCalloutRect メンバが表す長方形内のテキストの配置を指定する DWORD 値。1 つの水平方向の配置フラグと 1 つの垂直方向の配置フラグの組み合わせでなければならない。

定義済みの水平方向配置フラグは次のとおり。

DIDAL_LEFTALIGNED
テキストを左枠線に揃える。
DIDAL_CENTERED
テキストを水平方向の中央に寄せる。
DIDAL_RIGHTALIGNED
テキストを右枠線に揃える。

定義済みの垂直方向配置フラグは次のとおり。

DIDAL_MIDDLE
テキストを垂直方向の中央に寄せる。
DIDAL_TOPALIGNED
テキストを上枠線に揃える。
DIDAL_BOTTOMALIGNED
テキストを下枠線に揃える。

このメンバは、dwFlags に DIDIFT_OVERLAY フラグが含まれる場合にのみ有効である。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


DIDEVICEIMAGEINFOHEADER

デバイス イメージに関する情報を格納する。IDirectInputDevice8::GetImageInfo メソッドで使用される。

typedef struct _DIDEVICEIMAGEINFOHEADER{
    DWORD  dwSize;
    DWORD  dwSizeImageInfo;
    DWORD  dwcViews;
    DWORD  dwcButtons;
    DWORD  dwcAxes;
    DWORD  dwcPOVs;
    DWORD  dwBufferSize;
    DWORD  dwBufferUsed;
    DIDEVICEIMAGEINFO *lprgImageInfoArray;
} DIDEVICEIMAGEINFOHEADER, * LPDIDEVICEIMAGEINFOHEADER;

メンバ

dwSize
この構造体のサイズをバイト単位で指定する DWORD 値。構造体が使用可能になる前に初期化する必要がある。
dwSizeImageInfo
DIDEVICEIMAGEINFO 構造体のサイズをバイト単位で指定する DWORD 値。この構造体が使用可能になる前に初期化する必要がある。
dwcViews
このデバイスのビュー数を受け取る DWORD 変数。
dwcButtons
このデバイスのボタン数を受け取る DWORD 変数。
dwcAxes
このデバイスの軸数を受け取る DWORD 変数。
dwcPOVs
このデバイスの視点コントローラ数を受け取る DWORD 変数。
dwBufferSize
lprgImageInfo が指すバッファのサイズをバイト単位で指定する DWORD 値。ゼロを設定すると、IDirectInputDevice8::GetImageInfo メソッドはその他すべてのメンバを無視し、すべてのイメージに関する情報の保持に必要な最小バッファ サイズを返す。
dwBufferUsed
lprgImageInfo が指すバッファのサイズをバイト単位で取得する DWORD 値。dwBufferSize にゼロが設定されると、IDirectInputDevice8::GetImageInfo メソッドは、すべてのイメージに関する情報の保持に必要な最小バッファ サイズを、このメンバに設定する。
lprgImageInfoArray
DIDEVICEIMAGEINFO 構造体の配列を受け取るバッファへのポインタ。これらの構造体は、すべてのデバイス イメージとビュー、オーバーレイ イメージ、およびコールアウト文字列座標を表す。

注意

lprgImageInfoArray が指すバッファは、必要なイメージ情報構造体をすべて保持できるだけのサイズを確保する必要がある。アプリケーションは、dwBufferSize メンバにゼロを設定して IDirectInputDevice8::GetImageInfo メソッドを呼び出すことで、必要なサイズを照会できる。呼び出し後、dwBufferUsed には修正されたメモリ量がバイト単位で格納されている。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


DIDEVICEINSTANCE

Microsoft® DirectInput® デバイスのインスタンスを表す。この構造体は、IDirectInput8::EnumDevices、IDirectInput8::EnumDevicesBySemantics、および IDirectInputDevice8::GetDeviceInfo メソッドで使用される。

typedef struct DIDEVICEINSTANCE {
    DWORD dwSize;
    GUID  guidInstance;
    GUID  guidProduct;
    DWORD dwDevType;
    TCHAR tszInstanceName[MAX_PATH];
    TCHAR tszProductName[MAX_PATH];
    GUID  guidFFDriver;
    WORD  wUsagePage;
    WORD  wUsage;
} DIDEVICEINSTANCE, *LPDIDEVICEINSTANCE;

typedef const DIDEVICEINSTANCE  *LPCDIDEVICEINSTANCE;

メンバ

dwSize
この構造体のバイト単位のサイズ。このメンバは、構造体が使われる前に初期化されなければならない。
guidInstance
デバイスのインスタンスに対する一意な識別子。アプリケーションは、このインスタンス GUID を構成ファイルに保存し、後で使用することもできる。インスタンス GUID は、コンピュータごとに固有である。1 つのコンピュータから取得されるインスタンス GUID は、ほかのコンピュータ上のインスタンス GUID とは無関係である。
guidProduct
製品の一意な識別子。この識別子は、デバイス メーカーが定める。
dwDevType
デバイス タイプ指定子。デバイス タイプ記述コードの最下位バイトは、デバイス タイプを指定する。最下位バイトから 1 つ上位のバイトは、デバイス サブタイプを指定する。この値は、HID (Human Interface Device) を指定する DIDEVTYPE_HID と組み合わせることもできる。
tszInstanceName[MAX_PATH]
インスタンスの登録名。たとえば、"Joystick 1"。
tszProductName[MAX_PATH]
製品の登録名。
guidFFDriver
フォース フィードバックに使用されるドライバの一意な識別子。ドライバのメーカーがこの識別子を設定する。
wUsagePage
デバイスが HID (Human Interface Device) デバイスであれば、このメンバには、HID 使用ページ コードが含まれる。
wUsage
デバイスが HID (Human Interface Device) デバイスであれば、このメンバには、HID 使用コードが含まれる。

注意

dwDevType メンバで使用できるように、次のデバイス タイプとサブタイプが定義されている。

DI8DEVTYPE_1STPERSON
対面型のアクション ゲーム デバイス。次のサブタイプが定義される。
DI8DEVTYPE1STPERSON_LIMITED
アクション マッピング対象のデバイス オブジェクトの最小数を指定しないデバイス。
DI8DEVTYPE1STPERSON_SHOOTER
対面型のシューティング ゲーム用に設計されたデバイス。
DI8DEVTYPE1STPERSON_SIXDOF
6 段階 (3 つの横方向軸と 3 つの回転軸) の自由を備えたデバイス。
DI8DEVTYPE1STPERSON_UNKNOWN
不明なサブタイプ。
DI8DEVTYPE_DEVICE
別のカテゴリに分類されないデバイス。
DI8DEVTYPE_DEVICECTRL
アプリケーションのコンテキストから別タイプのデバイスの制御に使用される入力デバイス。次のサブタイプが定義される。
DI8DEVTYPEDEVICECTRL_COMMSSELECTION
通信の選択に使用されるコントロール。
DI8DEVTYPEDEVICECTRL_COMMSSELECTION_HARDWIRED
デフォルトの構成を使用する必要があり、マッピングを変更できないデバイス。
DI8DEVTYPEDEVICECTRL_UNKNOWN
不明なサブタイプ。
DI8DEVTYPE_DRIVING
ステアリング用デバイス。次のサブタイプが定義される。
DI8DEVTYPEDRIVING_COMBINEDPEDALS
単一の軸からアクセルとブレーキ ペダルの値を報告するステアリング デバイス。
DI8DEVTYPEDRIVING_DUALPEDALS
別々の軸からアクセルとブレーキ ペダルの値を報告するステアリング デバイス。
DI8DEVTYPEDRIVING_HANDHELD
ハンドヘルドのステアリング デバイス。
DI8DEVTYPEDRIVING_LIMITED
アクション マッピング対象のデバイス オブジェクトの最小数を指定しないステアリング デバイス。
DI8DEVTYPEDRIVING_THREEPEDALS
別々の軸からアクセル、ブレーキ、およびクラッチ ペダルの値を報告するステアリング デバイス。
DI8DEVTYPE_FLIGHT
フライト シミュレーション用コントローラ。次のサブタイプが定義される。
DI8DEVTYPEFLIGHT_LIMITED
アクション マッピング対象のデバイス オブジェクトの最小数を指定しないフライト コントローラ。
DI8DEVTYPEFLIGHT_RC
模型飛行機のリモート コントロールに基づくフライト デバイス。
DI8DEVTYPEFLIGHT_STICK
ジョイスティック。
DI8DEVTYPEFLIGHT_YOKE
操縦輪。
DI8DEVTYPE_GAMEPAD
ゲームパッド。次のサブタイプが定義される。
DI8DEVTYPEGAMEPAD_LIMITED
アクション マッピング対象のデバイス オブジェクトの最小数を指定しないゲームパッド。
DI8DEVTYPEGAMEPAD_STANDARD
アクション マッピング対象のデバイス オブジェクトの最小数を指定しない標準ゲームパッド。
DI8DEVTYPEGAMEPAD_TILT
コントローラの姿勢から x 軸と y 軸のデータを報告するゲームパッド。
DI8DEVTYPE_JOYSTICK
ジョイスティック。次のサブタイプが定義される。
DI8DEVTYPEJOYSTICK_LIMITED
アクション マッピング対象のデバイス オブジェクトの最小数を指定しないジョイスティック。
DI8DEVTYPEJOYSTICK_STANDARD
アクション マッピング対象のデバイス オブジェクトの最小数を指定する標準ジョイスティック。
DI8DEVTYPE_KEYBOARD
キーボードまたはキーボード類似デバイス。次のサブタイプが定義される。
DI8DEVTYPEKEYBOARD_UNKNOWN
サブタイプは確定できない。
DI8DEVTYPEKEYBOARD_PCXT
IBM PC/XT 83 キー キーボード
DI8DEVTYPEKEYBOARD_OLIVETTI
Olivetti 102 キー キーボード
DI8DEVTYPEKEYBOARD_PCAT
IBM PC/AT 84 キー キーボード
DI8DEVTYPEKEYBOARD_PCENH
IBM PC 拡張 101/102 キー式キーボードまたは Microsoft ナチュラル キーボード
DI8DEVTYPEKEYBOARD_NOKIA1050
Nokia 1050 キーボード
DI8DEVTYPEKEYBOARD_NOKIA9140
Nokia 9140 キーボード
DI8DEVTYPEKEYBOARD_NEC98
日本語 NEC PC98 キーボード
DI8DEVTYPEKEYBOARD_NEC98LAPTOP
日本語 NEC PC98 ラップトップ キーボード
DI8DEVTYPEKEYBOARD_NEC98106
日本語 NEC PC98 106 キー キーボード
DI8DEVTYPEKEYBOARD_JAPAN106
日本語 106 キー キーボード
DI8DEVTYPEKEYBOARD_JAPANAX
日本語 AX キーボード
DI8DEVTYPEKEYBOARD_J3100
日本語 J3100 キーボード
DI8DEVTYPE_MOUSE
マウスまたはマウス類似デバイス (トラックボールなど)。次のサブタイプが定義される。
DI8DEVTYPEMOUSE_ABSOLUTE
絶対軸データを返すマウス。
DI8DEVTYPEMOUSE_FINGERSTICK
フィンガースティック。
DI8DEVTYPEMOUSE_TOUCHPAD
タッチパッド。
DI8DEVTYPEMOUSE_TRACKBALL
トラックボール。
DI8DEVTYPEMOUSE_TRADITIONAL
従来型マウス。
DI8DEVTYPEMOUSE_UNKNOWN
サブタイプは確定できない。
DI8DEVTYPE_REMOTE
リモート コントロール デバイス。次のサブタイプが定義される。
DI8DEVTYPEREMOTE_UNKNOWN
サブタイプは確定できない。
DI8DEVTYPE_SCREENPOINTER
スクリーン ポインタ。次のサブタイプが定義される。
DI8DEVTYPESCREENPTR_UNKNOWN
不明なサブタイプ。
DI8DEVTYPESCREENPTR_LIGHTGUN
ライト ガン。
DI8DEVTYPESCREENPTR_LIGHTPEN
ライト ペン。
DI8DEVTYPESCREENPTR_TOUCH
タッチ スクリーン。
DI8DEVTYPE_SUPPLEMENTAL
ホイールと共に使用するペダルなど、アプリケーションのメイン コントロールに適さない機能を備えた特殊デバイス。次のサブタイプが定義される。
DI8DEVTYPESUPPLEMENTAL_2NDHANDCONTROLLER
2 次的ハンドヘルド コントローラ。
DI8DEVTYPESUPPLEMENTAL_COMBINEDPEDALS
主機能として、単一の軸からアクセルとブレーキ ペダルの値を報告するデバイス。
DI8DEVTYPESUPPLEMENTAL_DUALPEDALS
主機能として、別々の軸からアクセルとブレーキ ペダルの値を報告するデバイス。
DI8DEVTYPESUPPLEMENTAL_HANDTRACKER
手の移動を追跡するデバイス。
DI8DEVTYPESUPPLEMENTAL_HEADTRACKER
頭の移動を追跡するデバイス。
DI8DEVTYPESUPPLEMENTAL_RUDDERPEDALS
方向舵ペダルを備えたデバイス。
DI8DEVTYPESUPPLEMENTAL_SHIFTER
軸からギア選択を報告するデバイス。
DI8DEVTYPESUPPLEMENTAL_SHIFTSTICKGATE
ボタン状態からギア選択を報告するデバイス。
DI8DEVTYPESUPPLEMENTAL_SPLITTHROTTLE
主機能として、2 つ以上のスロットル値を報告するデバイス。その他のコントロールを持つ場合がある。
DI8DEVTYPESUPPLEMENTAL_THREEPEDALS
主機能として、別々の軸からアクセル、ブレーキ、およびクラッチ ペダルの値を報告するデバイス。
DI8DEVTYPESUPPLEMENTAL_THROTTLE
主機能として、単一のスロットル値を報告するデバイス。その他のコントロールを持つ場合がある。
DI8DEVTYPESUPPLEMENTAL_UNKNOWN
不明なサブタイプ。

Microsoft DirectX® 8.0 より前のバージョンの DirectInput では、デバイス タイプとサブタイプの構成が一部異なる。Dinput.h の DIDEVTYPExxx 定義を参照すること。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


DIDEVICEOBJECTDATA

バッファリング デバイスの情報を格納する。この構造体は、IDirectInputDevice8::GetDeviceData および IDirectInputDevice8::SendDeviceData メソッドで使用される。

typedef struct DIDEVICEOBJECTDATA {
    DWORD    dwOfs;
    DWORD    dwData;
    DWORD    dwTimeStamp;
    DWORD    dwSequence;
    UINT_PTR uAppData;
} DIDEVICEOBJECTDATA, *LPDIDEVICEOBJECTDATA;

typedef const DIDEVICEOBJECTDATA *LPCDIDEVICEOBJECTDATA;

メンバ

dwOfs
GetDeviceData の場合、データの報告対象となっているオブジェクトの、現在のデータ形式に対するオフセット値。すなわち、IDirectInputDevice8::GetDeviceState メソッドの呼び出しによってデータが取得された場合、その dwData が格納されている位置となる。デバイスがマウス、キーボード、またはジョイスティックとしてアクセスされる場合に、この dwOfs メンバは、マウス デバイス定数、キーボード デバイス定数、またはジョイスティック デバイス定数のいずれかになる。カスタム データ形式が設定されている場合は、カスタム データ形式に関連するオフセットになる。

アクション マッピングが使用中であれば、このメンバを無視できる。その代わりに、uAppData からアクション値を取得する。

SendDeviceData の場合、データの送信先であるオブジェクトのインスタンス ID。これは DIDEVICEOBJECTINSTANCE 構造体の dwType メンバから取得される。

dwData
デバイスから取得、またはデバイスに送信されるデータ。

軸からの入力の場合、デバイスが相対軸モードにあれば、相対軸の動きが報告される。デバイスが絶対軸モードにあれば、絶対座標が報告される。

ボタンからの入力の場合、dwData の下位バイトだけが有意である。下位バイトの上位ビットは、ボタンが押されたときに設定され、離されたときに消去される。

dwTimeStamp
入力イベントが生成されたミリ秒単位のシステム時間。なお、この値は、約 50 日で循環する。「注意」を参照すること。

構造体が SendDeviceData メソッドと共に使用される場合、このメンバは必ずゼロになる。

dwSequence
このイベントに対する Microsoft® DirectInput® シーケンス番号。すべての入力イベントには、昇順のシーケンス番号が割り当てられている。これにより、異なるデバイスからのイベントを時間順にソートすることが可能になる。この値は、循環して初期値に戻るので、2 つのシーケンス番号を比較する場合には注意しなければならない。この比較を確実に行うには、DISEQUENCE_COMPARE マクロを使用すればよい。

構造体が SendDeviceData メソッドと共に使用される場合、このメンバは必ずゼロになる。

uAppData
前回の IDirectInputDevice8::SetActionMap の呼び出しで、このオブジェクトに割り当てられたアプリケーション定義のアクション値。これは、オブジェクトに関連付けられた DIACTION 構造体の uAppData メンバの値である。アクション マッピングを使用していない場合はこの値を無視する。

構造体が SendDeviceData メソッドと共に使用される場合、このメンバは必ずゼロになる。

注意

dwTimeStamp が返すシステム時間は、Microsoft® Win32® の GetTickCount または timeGetTime 関数が使用するのと同じクロックに由来するものであるが、より精密な値を表すと考えられる。たとえば、Microsoft® Windows® 95 の場合、GetTickCount タイマの更新間隔は 55 ミリ秒だが、dwTimeStamp の値の誤差は 1 ミリ秒以内である。このため、GetTickCount を呼び出して n という値が返され、n + n1 というタイムスタンプを持つイベントを受け取る場合、そのイベントが GetTickCount を呼び出してからちょうど n1 ミリ秒後に発生した、と仮定することはできない。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


DIDEVICEOBJECTINSTANCE

デバイス オブジェクトのインスタンスに関する情報を格納する。この構造体は、IDirectInputDevice8::EnumObjects メソッドで使用され、DIEnumDeviceObjectsCallback コールバック関数に対して、軸またはボタンなど、デバイスに関連付けられた特定のオブジェクトに関する情報を提供する。また、デバイス オブジェクトの情報を取得するために、IDirectInputDevice8::GetObjectInfo メソッドでも使用される。

typedef struct DIDEVICEOBJECTINSTANCE {
    DWORD dwSize;
    GUID  guidType;
    DWORD dwOfs;
    DWORD dwType;
    DWORD dwFlags;
    TCHAR tszName[MAX_PATH];
    DWORD dwFFMaxForce;
    DWORD dwFFForceResolution;
    WORD  wCollectionNumber;
    WORD  wDesignatorIndex;
    WORD  wUsagePage;
    WORD  wUsage;
    DWORD dwDimension;
    WORD  wExponent;
    WORD  wReportId;
} DIDEVICEOBJECTINSTANCE, *LPDIDEVICEOBJECTINSTANCE;

typedef const DIDEVICEOBJECTINSTANCE *LPCDIDEVICEOBJECTINSTANCE;

メンバ

dwSize
この構造体のバイト単位のサイズ。列挙の間に、アプリケーションはこの値を調べ、構造体のメンバがいくつ有効であるかを確認できる。構造体が IDirectInputDevice8::GetObjectInfo メソッドに渡されるとき、このメンバを sizeof(DIDEVICEOBJECTINSTANCE) に初期化しなければならない。
guidType
オブジェクト タイプを示す一意な識別子。このメンバはオプションである。次のいずれか 1 つの値を取ることができる。
GUID_XAxis
水平軸。たとえば、マウスの左右の動きを表すことができる。
GUID_YAxis
垂直軸。たとえば、マウスの前後の動きを表すことができる。
GUID_ZAxis
z 軸。たとえば、マウス上のホイールの回転、またはジョイスティックのスロットル制御の移動を表すことができる。
GUID_RxAxis
x 軸を中心とする回転。
GUID_RyAxis
y 軸を中心とする回転。
GUID_RzAxis
z 軸を中心とする回転 (方向舵のコントロールでよく使われる)。
GUID_Slider
スライダ軸。
GUID_Button
マウス ボタン。
GUID_Key
キーボードのキー。
GUID_POV
視点インジケータ
GUID_Unknown
確定できない。

将来、これ以外のオブジェクト タイプも定義される可能性がある。

dwOfs
データ形式内のオフセットで、このオブジェクトに報告されるデータの位置。この値は、メソッド呼び出しにおけるオブジェクトと DIPH_BYOFFSET フラグを受け取る構造体の中のオブジェクトを識別するために使用される。「注意」を参照すること。
dwType
オブジェクトを表すデバイス タイプ。オブジェクト タイプ (軸、ボタンなど) を表す DIDFT_* フラグの組み合わせであり、中央の 16 ビットには、オブジェクト インスタンス番号が格納される。オブジェクト インスタンス番号を抽出するには、DIDFT_GETINSTANCE マクロを使用する。DIDFT_* フラグについては、「IDirectInputDevice8::EnumObjects」を参照すること。
dwFlags
データ形式のほかの属性を表すフラグ。この値は、次のいずれか 1 つである。
DIDOI_ASPECTACCEL
オブジェクトは加速度情報を報告する。
DIDOI_ASPECTFORCE
オブジェクトはフォース情報を報告する。
DIDOI_ASPECTMASK
アスペクト情報を報告するためのビット。1 つのオブジェクトは最大 1 つのアスペクトしか表すことができない。
DIDOI_ASPECTPOSITION
オブジェクトは位置情報を報告する。
DIDOI_ASPECTVELOCITY
オブジェクトは速度情報を報告する。
DIDOI_FFACTUATOR
オブジェクトは、フォース フィードバック エフェクトを自身に適用させることができる。
DIDOI_FFEFFECTTRIGGER
オブジェクトは、フォース フィードバック エフェクトの再生をトリガする。
DIDOI_GUIDISUSAGE
DIOBJECTDATAFORMAT 構造体の pguid メンバには、必要な使用ページと使用状況が、パックされた DWORD 形式で格納される。「DIMAKEUSAGEDWORD」を参照すること。
DIDOI_POLLED
IDirectInputDevice8::Poll メソッドが呼び出されるまで、オブジェクトはデータを返さない。
tszName[MAX_PATH]
オブジェクトの名前。たとえば、"X-Axis" または "Right Shift" など。
dwFFMaxForce
このオブジェクトに関連付けられたアクチュエータが作り出せる最大フォースのマグニチュード。フォースは、ニュートン単位で表現され、デバイスを通常に操作している間の手の位置との関連で測定される。
dwFFForceResolution
このオブジェクトに関連付けられたアクチュエータのフォース分解能。戻り値は、フォース フィードバック システムが 0 (フォースなし) から最大フォースの範囲で表現できるフォースの段階数または下位区分の数を表す。
wCollectionNumber
オブジェクトが属する HID (Human Interface Device) リンク コレクション。
wDesignatorIndex
HID 物理記述子の指定を参照するインデックス。この数値は、デバイス オブジェクトについての追加情報を含む HID 解釈ライブラリ (Hidpi.h) の関数に渡される。
wUsagePage
オブジェクトに関連する HID (Human Interface Device) 使用ページ (判明した場合)。HID は常に使用ページを報告する。非 HID デバイスはオプションで使用ページを報告する。非 HID デバイスが報告しない場合、このパラメータの値はゼロになる。
wUsage
オブジェクトに関連する HID 使用状況 (判明した場合)。HID は常に使用状況を報告する。非 HID はオプションで使用状況を報告する。非 HID デバイスが報告しない場合、このパラメータの値はゼロになる。
dwDimension
オブジェクトの値を報告する次元単位の HID (Human Interface Device) コード (判明している場合)。不明な場合はゼロとなる。
wExponent
単位に付ける指数 (判明している場合)。次元単位は常に整数であるので、整数以外のタイプに単位を変換するには指数が必要となる。
wReportId
予約済み。

注意

デバイスにデータ形式が設定された場合、dwOfs の値は、その形式内のオブジェクト データのオフセットである。形式が設定されていない場合、値は、デバイスが返す未加工データ内のオフセットである。データ形式が設定されていない場合、アプリケーションはこの値を使う必要がある。

アプリケーションは wUsagePage および wUsage メンバを使用して、オブジェクトの設計目的についての追加情報を得ることができる。たとえば、wUsagePage の値が 0x02 (乗物のコントロール) で、wUsage の値が 0xB9 (昇降舵トリム) の場合、オブジェクトは、操縦桿の昇降舵トリム コントロールとして設計されている。フライト シミュレータ アプリケーションはこの情報を使用して、デバイス上のオブジェクトに対して、より適切なデフォルト動作を提供することができる。HID 使用コードは USB 標準委員会で定められている。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


DIEFFECT

IDirectInputDevice8::CreateEffect メソッドが、新しい IDirectInputEffect オブジェクトを初期化するために使用する。IDirectInputEffect::SetParameters および IDirectInputEffect::GetParameters メソッドによっても使用される。

typedef struct DIEFFECT {
    DWORD   dwSize;
    DWORD   dwFlags;
    DWORD   dwDuration;
    DWORD   dwSamplePeriod;
    DWORD   dwGain;
    DWORD   dwTriggerButton;
    DWORD   dwTriggerRepeatInterval;
    DWORD   cAxes;
    LPDWORD rgdwAxes;
    LPLONG  rglDirection;
    LPDIENVELOPE lpEnvelope;
    DWORD   cbTypeSpecificParams;
    LPVOID  lpvTypeSpecificParams;
    DWORD   dwStartDelay;
} DIEFFECT, *LPDIEFFECT;

typedef const DIEFFECT *LPCDIEFFECT;

メンバ

dwSize
構造体のバイト単位のサイズ。このメンバは、構造体が使われる前に初期化されなければならない。
dwFlags
エフェクトに関連付けられたフラグ。この値は、以下の値の 1 つ以上の組み合わせとなる。
DIEFF_CARTESIAN
rglDirection の値は、デカルト座標として解釈する。
DIEFF_OBJECTIDS
dwTriggerButton および rgdwAxes の値は、IDirectInputDevice8::EnumObjects によって取得されるオブジェクト識別子である。
DIEFF_OBJECTOFFSETS
dwTriggerButton および rgdwAxes の値は、データ形式のオフセットである。
DIEFF_POLAR
rglDirection の値は、極座標と解釈する。
DIEFF_SPHERICAL
rglDirection の値は、球状座標と解釈する。
dwDuration
エフェクトのマイクロ秒単位の継続時間の合計。この値が INFINITE であれば、エフェクトの継続時間は無限となる。エンベロープがエフェクトに適用されていれば、アタックも適用され、無限の維持期間も適用されることになる。
dwSamplePeriod
デバイスがエフェクトを再生すべき間隔。マイクロ秒単位。この値がゼロであれば、デフォルトの再生サンプリング速度を使用することを意味する。

デバイスが指定の速度でエフェクトを再生できなければ、指定された値に最も近い速度を選択する。

カスタム dwSamplePeriod の設定は、特殊効果に使用できる。たとえば、サイン波を意図的に大きなサンプリングレートで再生すると、ざらざらした質感をもたらす。

dwGain
エフェクトに適用されるゲイン。0 ～ 10,000 の範囲にある。ゲインとは、エフェクトの全マグニチュードとそのエンベロープに適用されるスケーリング係数である。
dwTriggerButton
エフェクトの再生をトリガするのに使用されるボタンの識別子またはオフセット。DIEFF_OBJECTIDS および DIEFF_OBJECTOFFSETS の各フラグが、この値の意味内容を決定する。このメンバに DIEB_NOTRIGGER が設定されている場合、エフェクトに関連付けられているトリガ ボタンはない。
dwTriggerRepeatInterval
ボタンの押下および押し続けによってエフェクトがトリガされたときの、1 回の再生の終了と開始の間隔を表す、マイクロ秒単位の時間。繰り返しを抑制するには、この値を INFINITE に設定する。

DIEFFECTINFO 構造体の dwStaticParams メンバに DIEP_TRIGGERREPEATINTERVAL フラグが設定されている場合は、1 つのエフェクトのトリガによる繰り返しが可能である。

cAxes
エフェクトに関連している軸の数。軸リストまたは方向リストの変更または設定時には、呼び出し側がこのメンバを設定しておかなければならない。

エフェクトの軸数は、一度設定されると変更できない。

rgdwAxes
(cAxes 要素から成る) DWORD 配列へのポインタ。この DWORD 配列は、エフェクトを適用する対象の軸を識別する識別子またはオフセットを格納する。DIEFF_OBJECTIDS および DIEFF_OBJECTOFFSETS の各フラグが、配列の値の意味内容を決定する。

エフェクトに関連付けられた軸のリストは、一度設定されると変更できない。

単一のエフェクトに関連付けられる軸の数は、32 までである。

rglDirection
デカルト座標、極座標、または球状座標を格納する (cAxes 要素から成る) LONG 配列へのポインタ。DIEFF_CARTESIAN、DIEFF_POLAR および DIEFF_SPHERICAL の各フラグが配列の値の意味内容を決定する。

デカルト座標では、rglDirection の各値は、rgdwAxes の対応する軸に関連付けられる。

極座標では、角度は、(0, -1) 方向から (1, 0) の方向に回転する実角度の 100 倍で測定される。これが意味するのは、北はユーザーの正面の方向であり、東はユーザーの右側であるということである。最後の要素は使用されない。

球状座標では、第 1 の角度は、(1,0) の方向から (0,1) の方向へ回転した実角度の 100 倍で計測される。第 2 の角度は (軸の数が 3 以上であるとき)、(0,0,1) へ向かう実角度の 100 倍で計測される。第 3 の角度は (軸の数が 4 以上であるとき)、(0,0,0,1) へ向かう実角度の 100 倍で計測される。以下も同様に解釈する。最後の要素は使用されない。

注 : rglDirection 配列は、極座標または球状座標が指定されている場合でも cAxes エントリを含まなければならない。極座標または球面座標の場合、rglDirection 配列の最後の要素は、将来の用途のために予約されているので、ゼロでなければならない。

lpEnvelope
このエフェクトが使用するエンベロープを表す DIENVELOPE 構造体へのオプション ポインタ。すべてのエフェクト タイプが、エンベロープを使用するとは限らない。エンベロープの適用がなければ、このメンバには、NULL を設定する必要がある。
cbTypeSpecificParams
対応するエフェクト タイプに関する追加のタイプ固有パラメータのバイト数。
lpvTypeSpecificParams
タイプ固有パラメータへのポインタ。タイプ固有パラメータが存在しない場合には NULL。

エフェクトが DIEFT_CONDITION 型であれば、このメンバは、条件のパラメータを定義する DICONDITION 構造体からなる配列へのポインタを持つ。1 つの構造体を使用してもよい。この場合、条件は配列 rglDirection で指定された方向に適用される。そうでない場合は、配列 rgdwAxes の軸と同じ順序で、それぞれの軸に対して 1 つの構造体が必要となる。それぞれの軸に 1 つの構造体を用意すると、エフェクトは回転しない。配列 rglDirection では次の値を使用しなければならない。

  • DIEFF_SPHERICAL: 0, 0, ...
  • DIEFF_POLAR: 9000, 0, ...
  • DIEFF_CARTESIAN: 1, 0, ...

エフェクトが DIEFT_CUSTOMFORCE 型であれば、このメンバは、カスタム フォースのパラメータを定義する DICUSTOMFORCE 構造体へのポインタを持つ。

エフェクトが DIEFT_PERIODIC 型であれば、このメンバは、エフェクトのパラメータを定義する DIPERIODIC 構造体へのポインタを持つ。

エフェクトが DIEFT_CONSTANTFORCE 型であれば、このメンバは、コンスタント フォースのパラメータを定義する DICONSTANTFORCE 構造体へのポインタを持つ。

エフェクトが DIEFT_RAMPFORCE 型であれば、このメンバは、傾斜フォースのパラメータを定義する DIRAMPFORCE 構造体へのポインタを持つ。

dwStartDelay
IDirectInputEffect::Start を呼び出してからエフェクトを再生する前に、デバイスが待機する時間 (マイクロ秒単位)。この値がゼロであれば、エフェクトの再生は直ちに開始される。このメンバは、Microsoft® DirectX® 7.0 より前のバージョンには存在しない。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


DIEFFECTINFO

デバイスでサポートされるエフェクトに関する情報を返すために、IDirectInputDevice8::EnumEffects および IDirectInputDevice8::GetEffectInfo メソッドで使用される。

typedef struct DIEFFECTINFO {
    DWORD dwSize;
    GUID  guid;
    DWORD dwEffType;
    DWORD dwStaticParams;
    DWORD dwDynamicParams;
    TCHAR tszName[MAX_PATH];
} DIEFFECTINFO, *LPDIEFFECTINFO;

typedef const DIEFFECTINFO  *LPCDIEFFECTINFO;

メンバ

dwSize
構造体のバイト単位のサイズ。列挙の間に、アプリケーションはこの値を調べ、構造体のメンバがいくつ有効であるかを確認できる。この構造体が IDirectInputDevice8::GetEffectInfo メソッドに渡される前に、この構造体のメンバを初期化しなければならない。
guid
エフェクトの識別子。
dwEffType
ゼロまたは以下の値のいずれか。
DIEFT_ALL
IDirectInputDevice8::EnumEffects に対してのみ有効。タイプに関係なくすべてのエフェクトを列挙する。このフラグは、ほかのどのフラグとも組み合せることはできない。
DIEFT_CONDITION
エフェクトは、条件を表す。条件を作成または修正する際は、DIEFFECT 構造体の lpvTypeSpecificParams メンバは DICONDITION 構造体 (各軸に 1 つ) から成る配列を指し、cbTypeSpecificParams メンバには cAxis * sizeof(DICONDITION) を設定しなければならない。

すべてのデバイスが、条件のすべてのパラメータをサポートするわけではない。エフェクトの能力フラグをチェックして、どの能力が使用可能であるかを調べる。

このフラグは、IDirectInputDevice8::EnumEffects に渡して、列挙対象を条件に制限することができる。

DIEFT_CONSTANTFORCE
エフェクトは、コンスタント フォース エフェクトを表す。コンスタント フォース エフェクトを作成または修正する際は、DIEFFECT 構造体の lpvTypeSpecificParams メンバが DICONSTANTFORCE 構造体を指し、cbTypeSpecificParams メンバには sizeof(DICONSTANTFORCE) を設定しなければならない。

このフラグは、IDirectInputDevice8::EnumEffects に渡して、列挙対象をコンスタント フォース エフェクトに制限することができる。

DIEFT_CUSTOMFORCE
エフェクトは、カスタム フォース エフェクトを表す。カスタム フォース エフェクトを作成または修正する際は、DIEFFECT 構造体の lpvTypeSpecificParams メンバが DICUSTOMFORCE 構造体を指し、cbTypeSpecificParams メンバには sizeof(DICUSTOMFORCE) を設定しなければならない。

このフラグは、IDirectInputDevice8::EnumEffects に渡して、列挙対象をカスタム フォース エフェクトに制限することができる。

DIEFT_DEADBAND
この条件エフェクトに対するエフェクト ジェネレータは、lDeadBand パラメータをサポートする。
DIEFT_FFATTACK
このエフェクトに対するエフェクト ジェネレータは、アタック エンベロープ パラメータをサポートする。エフェクト ジェネレータがアタックをサポートしていなければ、DIENVELOPE 構造体のアタック レベルとアタック時間のパラメータを、エフェクトが無視する。

DIEFT_FFATTACK と DIEFT_FFFADE が両方とも設定されていなければ、エフェクトは、エンベロープをサポートせず、指定のエンベロープは、すべて無視される。

DIEFT_FFFADE
このエフェクトに対するエフェクト ジェネレータは、フェード パラメータをサポートする。エフェクト ジェネレータがフェードをサポートしていなければ、DIENVELOPE 構造体のフェード レベルとフェード時間のパラメータを、エフェクトが無視する。

DIEFT_FFATTACK と DIEFT_FFFADE が両方とも設定されていなければ、エフェクトは、エンベロープをサポートせず、指定のエンベロープは、すべて無視される。

DIEFT_HARDWARE
エフェクトは、ハードウェア固有のエフェクトを表す。ハードウェア固有エフェクトの使用の詳細については、ハードウェアのドキュメントを参照すること。

このフラグを IDirectInputDevice8::EnumEffects メソッドに渡して、列挙対象をハードウェア固有エフェクトに制限することができる。

DIEFT_PERIODIC
エフェクトは、周期的フォース エフェクトを表す。周期的フォース エフェクトを作成または修正する際は、DIEFFECT 構造体の lpvTypeSpecificParams メンバが DIPERIODIC 構造体を指し、cbTypeSpecificParams メンバには sizeof(DIPERIODIC) を設定しなければならない。

このフラグは、IDirectInputDevice8::EnumEffects に渡して、列挙対象を周期的フォース エフェクトに制限することができる。

DIEFT_POSNEGCOEFFICIENTS
このエフェクトに対するエフェクト ジェネレータは、条件に対する 2 つの係数値、一方は正の軸移動、他方は負の軸移動に対する係数をサポートする。デバイスが一方向の係数しかサポートしない場合、DICONDITION 構造体の負の係数が無視され、正の係数が両方の方向で使用される。
DIEFT_POSNEGSATURATION
このエフェクトに対するエフェクト ジェネレータは、正負の両方のフォース出力に対する最大飽和をサポートする。デバイスが一方向の飽和値しかサポートしないのであれば、DICONDITION 構造体の負の飽和値が無視され、正の飽和値が両方の方向で使用される。
DIEFT_RAMPFORCE
エフェクトは、傾斜フォース エフェクトを表す。傾斜フォース エフェクトを作成または修正する際は、DIEFFECT 構造体の lpvTypeSpecificParams メンバが DIRAMPFORCE 構造体を指し、cbTypeSpecificParams メンバには sizeof(DIRAMPFORCE) を設定しなければならない。

このフラグは、IDirectInputDevice8::EnumEffects に渡して、列挙対象を傾斜フォース エフェクトに制限することができる。

DIEFT_SATURATION
このエフェクトに対するエフェクト ジェネレータは、条件エフェクトの飽和をサポートする。エフェクト ジェネレータが飽和をサポートしていなければ、条件が生成したフォースは、デバイスが生成できる最大フォースによってのみ制限される。
DIEFT_STARTDELAY
エフェクトは、すぐに開始されるのではなく再生までに遅延が発生する。この遅延を利用して、エフェクトが順番どおりに再生されるようにエフェクトの補正が行われる。
dwStaticParams
エフェクトがサポートするパラメータを表すゼロ以上の DIEP_* 値。たとえば、DIEP_ENVELOPE が設定されていれば、エフェクトはエンベロープをサポートする。設定可能な値の一覧については、「IDirectInputEffect::GetParameters」を参照すること。

デバイスがサポートしていないエフェクト パラメータをアプリケーションが使用しようとしても、エラーにはならない。サポートされていないパラメータは、無視されるだけである。

この情報は、アプリケーションが特定のデバイスの能力にフォース フィードバックを適合させて使えるようにするために提供されている。

dwDynamicParams
エフェクトの再生中に修正できるエフェクト パラメータを示すゼロ以上の DIEP_* 値。設定可能な値の一覧については、「IDirectInputEffect::GetParameters」を参照すること。

エフェクトの再生中にアプリケーションがパラメータを変更しようとしても、ドライバがそのエフェクトを動的に修正する機能をサポートしていない場合は、ドライバはそのエフェクトを停止して、パラメータを更新し、その後にエフェクトを再開することができる。詳細については、「IDirectInputEffect::SetParameters」を参照すること。

tszName[MAX_PATH]
エフェクトの名前。たとえば、"Sawtooth up" または "Constant Force" など。

注意

dwEffType フラグからエフェクト タイプを抽出するには、DIEFT_GETTYPE マクロを使用する。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


DIEFFESCAPE

ハードウェア データをデバイス ドライバに直接、渡すために IDirectInputDevice8::Escape および IDirectInputEffect::Escape メソッドで使用される。

typedef struct DIEFFESCAPE {
    DWORD  dwSize;
    DWORD  dwCommand;
    LPVOID lpvInBuffer;
    DWORD  cbInBuffer;
    LPVOID lpvOutBuffer;
    DWORD  cbOutBuffer;
} DIEFFESCAPE, *LPDIEFFESCAPE;

メンバ

dwSize
構造体のバイト単位のサイズ。このメンバは、構造体が使われる前に初期化されなければならない。
dwCommand
ドライバのコマンド番号。有効なコマンドの一覧については、ドライバのドキュメントを参照すること。
lpvInBuffer
操作を実行するのに必要なデータを格納しているバッファ。
cbInBuffer
lpvInBuffer バッファのバイト単位のサイズ。
lpvOutBuffer
操作の出力データが返されるバッファ。
cbOutBuffer
入力パラメータとしては、lpvOutBuffer バッファのバイト単位のサイズ。出力パラメータとしては、コマンドが実際に作成したバイト数。

注意

各ドライバは、異なるエスケープ シーケンスを実装しているので、正しいドライバと通信しているかどうかは、アプリケーション自体が確認しなければならない。これは、DIDEVICEINSTANCE 構造体の guidFFDriver メンバと、アプリケーションが期待している値を比較することにより確認できる。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


DIENVELOPE

DIEFFECT 構造体がエフェクトに対するオプションのエンベロープ パラメータを指定するために使用する。そのエンベロープの維持期間レベルは、DIPERIODIC 構造体の dwMagnitude メンバと DICONSTANTFORCE 構造体の lMagnitude メンバとが示す値である。維持時間は、DIEFFECT 構造体の dwDuration メンバが示す値である。

typedef struct DIENVELOPE {
    DWORD dwSize;
    DWORD dwAttackLevel;
    DWORD dwAttackTime;
    DWORD dwFadeLevel;
    DWORD dwFadeTime;
} DIENVELOPE, *LPDIENVELOPE;

typedef const DIENVELOPE *LPCDIENVELOPE;

メンバ

dwSize
構造体のバイト単位のサイズ。このメンバは、構造体が使われる前に初期化されなければならない。
dwAttackLevel
基線を基準とするエンベロープの始点における振幅。基線に対する相対値。0 ～ 10,000 の範囲である。エフェクトのタイプ固有データが基線を指定していなければ、振幅はゼロを基準とする。
dwAttackTime
維持期間レベルに到達するのに必要な、マイクロ秒単位の時間。
dwFadeLevel
エンベロープの終点での振幅。基線に対する相対値。0 ～ 10,000 の範囲である。エフェクトのタイプ固有データが基線を指定していなければ、振幅はゼロを基準とする。
dwFadeTime
フェード レベルに到達するのに必要なマイクロ秒単位の時間。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


DIFILEEFFECT

ファイルに保存されたフォース フィードバック エフェクトのデータを表す。この構造体は、IDirectInputDevice8::EnumEffectsInFile および IDirectInputDevice8::WriteEffectToFile メソッドで使用される。

typedef struct DIFILEEFFECT{
    DWORD       dwSize;
    GUID        GuidEffect;
    LPCDIEFFECT lpDiEffect;
    CHAR        szFriendlyName[MAX_PATH];
}DIFILEEFFECT, *LPDIFILEEFFECT;

メンバ

dwSize
構造体のバイト単位のサイズ。このメンバは、構造体が使われる前に初期化されなければならない。
GuidEffect
エフェクト タイプの一意な識別子。GUID_ConstantForce など、Dinput.h に定義された標準 GUID や、デザイナによって作成された GUID をとることができる。
lpDiEffect
エフェクトに関する情報を格納する DIEFFECT 構造体へのポインタ。
szFriendlyName
エフェクトの名前。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


DIJOYSTATE

ジョイスティック デバイスの状態を表す。この構造体は、IDirectInputDevice8::GetDeviceState メソッドで使用する。

typedef struct DIJOYSTATE {
    LONG    lX;
    LONG    lY;
    LONG    lZ;
    LONG    lRx;
    LONG    lRy;
    LONG    lRz;
    LONG    rglSlider[2];
    DWORD   rgdwPOV[4];
    BYTE    rgbButtons[32];
} DIJOYSTATE, *LPDIJOYSTATE;

メンバ

lX
通常はスティックの左右の動きを表す x 軸。
lY
通常はスティックの前後の動きを表す y 軸。
lZ
スロットル制御を表す場合がある z 軸。ジョイスティックにこの軸がなければ、値はゼロである。
lRx
x 軸回転。ジョイスティックにこの軸がなければ、値はゼロである。
lRy
y 軸回転。ジョイスティックにこの軸がなければ、値はゼロである。
lRz
z 軸回転 (方向舵と呼ばれる)。ジョイスティックにこの軸がなければ、値はゼロである。
rglSlider[2]
2 つの追加軸 (以前には u 軸と v 軸と呼ばれていた)。この値の意味はジョイスティックで異なる。これらの値の意味についての情報を取得するには、IDirectInputDevice8::GetObjectInfo メソッドを使用する。
rgdwPOV[4]
視点ハットなどの方向コントローラ。この位置は、北から (ユーザーの正面側) 時計回りの実角度の 100 倍で表される。中心位置は通常 -1 と報告されるが、これについては「注意」を参照すること。5 つの位置しか持たないインジケータの場合、コントローラの値は -1、0、9,000、18,000、27,000 のどれか 1 つの値を取る。
rgbButtons[32]
ボタンの配列。バイトの高次ビットは、対応するボタンがダウン状態にあるときに設定され、ボタンがアップ状態または存在しないときには消去される。

注意

ジョイスティック型のアクセスができるようにデバイスを準備するには、IDirectInputDevice8::SetDataFormat メソッドを呼び出し、c_dfDIJoystick グローバル データ形式変数を渡す。

軸が相対モードである場合は、適切なメンバが位置の変化量を格納する。絶対モードの場合には、同じメンバが軸の絶対位置を格納する。

POV インジケータの中心位置を 65,535 と報告するドライバもある。POV インジケータが中心位置にあるかどうかは、次のようにして確認する。

BOOL POVCentered = (LOWORD(dwPOV) == 0xFFFF);

注 : Microsoft® DirectX® 7 では、一部のジョイスティックのスライダを Z 軸に割り当て、それ以降のコードでそのメンバからデータを取得することができた。DirectX 8 では、同じスライダを rglSlider 配列に割り当てる。アプリケーションを DirectX 8 に移植する場合は、この点を考慮する必要がある。rglSlider 配列からスライダ データを取得するために必要な変更があれば行うこと。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。

参照

DIJOYSTATE2


DIJOYSTATE2

拡張機能の付いたジョイスティック デバイスの状態を表す。この構造体は、IDirectInputDevice8::GetDeviceState メソッドで使用する。

typedef struct DIJOYSTATE2 {
    LONG    lX;
    LONG    lY;
    LONG    lZ;
    LONG    lRx;
    LONG    lRy;
    LONG    lRz;
    LONG    rglSlider[2];
    DWORD   rgdwPOV[4];
    BYTE    rgbButtons[128];
    LONG    lVX;
    LONG    lVY;
    LONG    lVZ;
    LONG    lVRx;
    LONG    lVRy;
    LONG    lVRz;
    LONG    rglVSlider[2];
    LONG    lAX;
    LONG    lAY;
    LONG    lAZ;
    LONG    lARx;
    LONG    lARy;
    LONG    lARz;
    LONG    rglASlider[2];
    LONG    lFX;
    LONG    lFY;
    LONG    lFZ;
    LONG    lFRx;
    LONG    lFRy;
    LONG    lFRz;
    LONG    rglFSlider[2];
} DIJOYSTATE2, *LPDIJOYSTATE2;

メンバ

lX
通常はスティックの左右の動きを表す x 軸。
lY
通常はスティックの前後の動きを表す y 軸。
lZ
スロットル制御を表す場合がある z 軸。ジョイスティックにこの軸がなければ、値はゼロである。
lRx
x 軸回転。ジョイスティックにこの軸がなければ、値はゼロである。
lRy
y 軸回転。ジョイスティックにこの軸がなければ、値はゼロである。
lRz
z 軸回転 (方向舵と呼ばれる)。ジョイスティックにこの軸がなければ、値はゼロである。
rglSlider[2]
2 つの追加軸の値 (以前には u 軸と v 軸と呼ばれていた)。この値の意味はジョイスティックで異なる。これらの値の意味についての情報を取得するには、IDirectInputDevice8::GetObjectInfo メソッドを使用する。
rgdwPOV[4]
視点ハットなどの方向コントローラ。この位置は、北から (ユーザーの正面側) 時計回りの実角度の 100 倍で表される。中心位置は通常 -1 と報告されるが、これについては「注意」を参照すること。5 つの位置しか持たないインジケータの場合、コントローラの値は -1、0、9,000、18,000、27,000 のどれか 1 つの値を取る。
rgbButtons[128]
ボタンの配列。バイトの高次ビットは、対応するボタンがダウン状態にあるときに設定され、ボタンがアップ状態または存在しないときには消去される。
lVX
x 軸の速度。
lVY
y 軸の速度。
lVZ
z 軸の速度。
lVRx
x 軸の角速度。
lVRy
y 軸の角速度。
lVRz
z 軸の角速度。
rglVSlider[2]
追加軸の速度。
lAX
x 軸の加速度。
lAY
y 軸の加速度。
lAZ
z 軸の加速度。
lARx
x 軸の角加速度。
lARy
y 軸の角加速度。
lARz
z 軸の角加速度。
rglASlider[2]
追加軸の加速度。
lFX
x 軸のフォース。
lFY
y 軸のフォース。
lFZ
z 軸のフォース。
lFRx
x 軸のトルク。
lFRy
y 軸のトルク。
lFRz
z 軸のトルク。
rglFSlider[2]
2 つの追加軸のフォース。

注意

拡張機能付きジョイスティックのアクセス用にデバイスを準備するには、IDirectInputDevice8::SetDataFormat メソッドを呼び出し、c_dfDIJoystick2 グローバルデータ形式変数を渡す。

軸が相対モードである場合は、適切なメンバが位置の変化量を格納する。絶対モードの場合には、同じメンバが軸の絶対位置を格納する。

POV インジケータの中心位置を 65,535 と報告するドライバもある。POV インジケータが中心位置にあるかどうかは、次のようにして確認する。

BOOL POVCentered = (LOWORD(dwPOV) == 0xFFFF);

注 : Microsoft® DirectX® 7 では、一部のジョイスティックのスライダを Z 軸に割り当て、それ以降のコードでそのメンバからデータを取得することができた。DirectX 8 では、同じスライダを rglSlider 配列に割り当てる。アプリケーションを DirectX 8 に移植する場合は、この点を考慮する必要がある。rglSlider 配列からスライダ データを取得するために必要な変更があれば行うこと。

動作環境

  Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。

  Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。

  ヘッダー : dinput.h で宣言。

参照

DIJOYSTATE


DIMOUSESTATE

4 つまでのボタンを持つマウス デバイスの状態、またはマウス デバイスと同じようにアクセスされるその他のデバイスの状態を表す。この構造体は、IDirectInputDevice8::GetDeviceState メソッドで使用する。

typedef struct DIMOUSESTATE {
    LONG lX;
    LONG lY;
    LONG lZ;
    BYTE rgbButtons[4];
} DIMOUSESTATE, *LPDIMOUSESTATE;

メンバ

lX
x 軸。
lY
y 軸。
lZ
通常はホイールを表す z 軸。マウスに z 軸がなければ、この値はゼロである。
rgbButtons
ボタンの配列。バイトの高次ビットは、対応するボタンがダウン状態にあるときに設定される。

注意

マウス型のアクセスができるようにデバイスを準備するには、IDirectInputDevice8::SetDataFormat メソッドを呼び出し、c_dfDIMouse グローバル データ形式変数を渡す。

マウスは相対軸デバイスであるので、マウス軸の絶対軸位置は、単純に相対的な動きの累積として求められる。したがって、絶対軸位置は、ほかの絶対軸位置と比較する場合を除いて無意味となる。

軸が相対モードである場合は、適切なメンバが位置の変化量を格納する。絶対モードの場合には、同じメンバが軸の絶対位置を格納する。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。

参照

DIMOUSESTATE2


DIMOUSESTATE2

8 つまでのボタンを持つマウス デバイスの状態、またはマウス デバイスと同じようにアクセスされるその他のデバイスの状態を表す。この構造体は、IDirectInputDevice8::GetDeviceState メソッドで使用する。

typedef struct DIMOUSESTATE {
    LONG lX;
    LONG lY;
    LONG lZ;
    BYTE rgbButtons[8];
} DIMOUSESTATE, *LPDIMOUSESTATE;

メンバ

lX
x 軸。
lY
y 軸。
lZ
通常はホイールを表す z 軸。マウスに z 軸がなければ、この値はゼロである。
rgbButtons
ボタンの配列。バイトの高次ビットは、対応するボタンがダウン状態にあるときに設定される。

注意

マウス型のアクセスができるようにデバイスを準備するには、IDirectInputDevice8::SetDataFormat メソッドを呼び出し、c_dfDIMouse2 グローバル データ形式変数を渡す。

マウスは相対軸デバイスであるので、マウス軸の絶対軸位置は、単純に相対的な動きの累積として求められる。したがって、絶対軸位置は、ほかの絶対軸位置と比較する場合を除いて無意味となる。

軸が相対モードである場合は、適切なメンバが位置の変化量を格納する。絶対モードの場合には、同じメンバが軸の絶対位置を格納する。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。

参照

DIMOUSESTATE


DIOBJECTDATAFORMAT

IDirectInputDevice8::SetDataFormat メソッドで使用するデバイス オブジェクトのデータ形式を表す。

typedef struct DIOBJECTDATAFORMAT {
    const GUID * pguid;
    DWORD        dwOfs;
    DWORD        dwType;
    DWORD        dwFlags;
} DIOBJECTDATAFORMAT, *LPDIOBJECTDATAFORMAT;

typedef const DIOBJECTDATAFORMAT *LPCDIOBJECTDATAFORMAT;

メンバ

pguid
軸、ボタン、またはその他の入力ソースに対する一意な識別子。データ形式の要求時、このメンバを NULL にすると、あらゆるタイプのオブジェクトを許可することになる。
dwOfs
入力ソースのデータを格納するデータ パケット内のオフセット。この値は、軸など、DWORD サイズのデータに合うように、4 の倍数でなければならない。ボタンに対してはバイト整列でも構わない。
dwType
オブジェクトを表すデバイス タイプ。オブジェクト タイプ (軸、ボタンなど) を表す以下のフラグの組み合わせであり、中央の 16 ビットは、オブジェクト インスタンス番号を格納する。データ形式の要求時に、インスタンス部分に DIDFT_ANYINSTANCE を設定すると、あらゆるインスタンスを許可することができる。DIDFT_MAKEINSTANCE(n) に設定して、要求をインスタンス n に限定することもできる。「注意」を参照すること。
DIDFT_ABSAXIS
SetDataFormat メソッドによって選択されたオブジェクトは、絶対軸でなければならない。
DIDFT_AXIS
SetDataFormat メソッドによって選択されたオブジェクトは、絶対軸あるいは相対軸でなければならない。
DIDFT_BUTTON
SetDataFormat メソッドによって選択されたオブジェクトは、プッシュ ボタンあるいはトグル ボタンでなければならない。
DIDFT_FFACTUATOR
SetDataFormat メソッドによって選択されたオブジェクトは、フォース フィードバック アクチュエータを含まなければならない。すなわち、フォースをこのオブジェクトに適用することができなければならない。
DIDFT_FFEFFECTTRIGGER
SetDataFormat メソッドによって選択されたオブジェクトは、有効なフォース フィードバック エフェクト トリガでなければならない。
DIDFT_POV
SetDataFormat メソッドによって選択されたオブジェクトは、視点コントローラでなければならない。
DIDFT_PSHBUTTON
SetDataFormat メソッドによって選択されたオブジェクトは、プッシュ ボタンでなければならない。
DIDFT_RELAXIS
SetDataFormat によって選択されたオブジェクトは、相対軸でなければならない。
DIDFT_TGLBUTTON
SetDataFormat によって選択されたオブジェクトは、トグル ボタンでなければならない。
DIDFT_VENDORDEFINED
SetDataFormat によって選択されたオブジェクトは、メーカー定義のタイプでなければならない。
dwFlags
ゼロまたは以下の値のいずれか。
DIDOI_ASPECTACCEL
SetDataFormat によって選択されたオブジェクトは、加速度情報を報告しなければならない。
DIDOI_ASPECTFORCE
SetDataFormat によって選択されたオブジェクトは、フォース情報を報告しなければならない。
DIDOI_ASPECTPOSITION
SetDataFormat によって選択されたオブジェクトは、位置情報を報告しなければならない。
DIDOI_ASPECTVELOCITY
SetDataFormat によって選択されたオブジェクトは、速度情報を報告しなければならない。

注意

データ形式は、各オブジェクト (軸、ボタンなど) が 1 つずつ保有する複数の DIOBJECTDATAFORMAT 構造体で構成される。これらの構造体の配列は、IDirectInputDevice8::SetDataFormat に渡される DIDATAFORMAT 構造体に格納される。アプリケーションは、通常、DIOBJECTDATAFORMAT 構造体からなる配列を作成する必要はなく、DIOBJECTDATAFORMAT に事前定義されている設定値である c_dfDIMouse、c_dfDIMouse2、c_dfDIKeyboard、c_dfDIJoystick、または c_dfDIJoystick2 などの事前定義されたデータ形式データのいずれかを使用できる。

以下のオブジェクト データ形式は、Microsoft® DirectInput® が最初の使用可能な軸を選択し、そのデバイス データのオフセット 4 の位置にある値を DWORD で報告しなければならないということを指定している。

DIOBJECTDATAFORMAT dfAnyAxis = {
    0,                              // ワイルドカード
    4,                              // オフセット
    DIDFT_AXIS | DIDFT_ANYINSTANCE, // どの軸でもよい。
    0,                              // アスペクトを無視する。
};

以下のオブジェクト データ形式は、デバイスの x 軸をデバイス データのオフセット 12 の位置に DWORD で格納するように指定している。デバイスが複数の x 軸を持っている場合には、最初に使用可能な軸が選択される。

DIOBJECTDATAFORMAT dfAnyXAxis = {
    &GUID_XAxis,                    // X 軸を指定する。
    12,                             // オフセット
    DIDFT_AXIS | DIDFT_ANYINSTANCE, // どの X 軸でもよい。
    0,                              // アスペクトを無視する。
};

以下のオブジェクト データ形式は、DirectInput が最初に使用可能なボタンを選択して、デバイス データのオフセット 16 の位置にあるバイトの上位ビットの値を報告するように指定している。

DIOBJECTDATAFORMAT dfAnyButton = {
    0,                                // ワイルドカード
    16,                               // オフセット
    DIDFT_BUTTON | DIDFT_ANYINSTANCE, // どのボタンでもよい。
    0,                                // アスペクトを無視する。
};

以下のオブジェクト データ形式は、デバイスのボタン 0 をデバイス データのオフセット 18 の位置に格納されているバイトの上位ビットとして報告するように指定している。

デバイスにボタン 0 がなければ、このデータ形式の設定は失敗に終わる。

DIOBJECTDATAFORMAT dfButton0 = {
    0,                                    // ワイルドカード
    18,                                   // オフセット
    DIDFT_BUTTON | DIDFT_MAKEINSTANCE(0), // ボタン 0
    0,                                    // アスペクトを無視する。
};

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


DIPERIODIC

DIEFT_PERIODIC としてマークされているエフェクトのタイプ固有の情報を格納する。

この構造体は、周期的エフェクトを表す。

エフェクトを表す単一の DIPERIODIC 構造体へのポインタは、DIEFFECT 構造体の lpvTypeSpecificParams メンバに渡される。

typedef struct DIPERIODIC {
    DWORD dwMagnitude;
    LONG  lOffset;
    DWORD dwPhase;
    DWORD dwPeriod;
} DIPERIODIC, *LPDIPERIODIC;

typedef const DIPERIODIC *LPCDIPERIODIC;

メンバ

dwMagnitude
0 ～ 10,000 の範囲にある、エフェクトのマグニチュード。エンベロープがこのエフェクトに適用されていれば、この値は、維持期間のマグニチュードを表す。エンベロープの適用がなければ、この値は、エフェクト全体の振幅を表す。
lOffset
エフェクトの識別子。エフェクトが生成するフォースの範囲は、lOffset - dwMagnitude から lOffset + dwMagnitude までの間になる。lOffset メンバの値は、エフェクトに適用されるすべてのエンベロープに対する基線にもなる。
dwPhase
0 ～ 35,999 の範囲内にある周期的エフェクトの再生開始位置座標。「注意」を参照すること。
dwPeriod
マイクロ秒単位のエフェクトの間隔。

注意

デバイス ドライバは dwPhase メンバのすべての値をサポートしているとはかぎらない。サポートされていない値は、直近のサポート値に丸められる。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


DIPROPCPOINTS

現在のインスタンスにキャリブレーション ポイントを設定する。

typedef struct DIPROPCPOINTS {
    DIPROPHEADER diph;
    DWORD  dwCPointsNum;
    CPOINT cp[MAXCPOINTSNUM];
} DIPROPCPOINTS, *LPDIPROPCPOINTS;

typedef const DIPROPCPOINTS *LPCDIPROPCPOINTS;

メンバ

diph
DIPROPHEADER 構造体。次のように初期化する。
メンバ | 値
dwSize | sizeof(DIPROPCPOINTS)
dwHeaderSize | sizeof(DIPROPHEADER)
dwObj dwHow メンバが DIPH_BYID であれば、このメンバは、設定または取得されるプロパティを持つオブジェクトの識別子とする。

dwHow メンバが DIPH_ BYOFFSET であれば、このメンバは、設定または取得されるプロパティを持つオブジェクトのデータ形式オフセットとする。たとえば、c_dfDIMouse データ形式を選ぶと、このメンバは DIMOFS_* 値のうちどれか 1 つとしなければならない。

dwHow メンバが DIPH_BYUSAGE であれば、デバイスは HID (Human Interface Device) とする。デバイス オブジェクトは、パックされた形式の HID 使用ページおよび使用状況の値によって識別される。

このプロパティは個別のデバイス オブジェクトにしか適用できないので、DIPH_DEVICE は使用できない。
dwHow | dwObj メンバの解釈方法を指定する。詳細については、この表の dwObj メンバの説明を参照すること。
dwCPointsNum
格納されているキャリブレーション ポイントの数。使用できるキャリブレーション ポイントの最大数は 8 である。
cp[MAXCPOINTSNUM]
キャリブレーション ポイントの配列。


DIPROPDWORD

DWORD プロパティにアクセスするために使用される。

typedef struct DIPROPDWORD {
    DIPROPHEADER diph;
    DWORD        dwData;
} DIPROPDWORD, *LPDIPROPDWORD;

typedef const DIPROPDWORD *LPCDIPROPDWORD;

メンバ

diph
DIPROPHEADER 構造体。次のように初期化する。
メンバ | 値
dwSize | sizeof(DIPROPDWORD)
dwHeaderSize | sizeof(DIPROPHEADER)
dwObj dwHow メンバが DIPH_DEVICE であれば、このメンバはゼロとする。

dwHow メンバが DIPH_BYID であれば、このメンバは、設定または取得されるプロパティを持つオブジェクトの識別子とする。

dwHow メンバが DIPH_ BYOFFSET であれば、このメンバは、設定または取得されるプロパティを持つオブジェクトのデータ形式オフセットとする。たとえば、c_dfDIMouse データ形式を選ぶと、このメンバは DIMOFS_* 値のうちどれか 1 つとしなければならない。

dwHow メンバが DIPH_BYUSAGE であれば、デバイスは HID (Human Interface Device) とする。デバイス オブジェクトは、パックされた形式の HID 使用ページおよび使用状況の値によって識別される。

dwHow | dwObj メンバの解釈方法を指定する。詳細については、この表の dwObj メンバの説明を参照すること。

dwData
設定または取得されるプロパティ値。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。

参照

IDirectInputDevice8::GetProperty、IDirectInputDevice8::SetProperty


DIPROPGUIDANDPATH

GUID やパスを表す値を持つプロパティにアクセスするために使用される。

typedef struct DIPROPGUIDANDPATH {
    DIPROPHEADER diph;
    GUID         guidClass;
    WCHAR        wszPath[MAX_PATH];
} DIPROPGUIDANDPATH, *LPDIPROPGUIDANDPATH;

typedef const DIPROPGUIDANDPATH *LPCDIPROPGUIDANDPATH;

メンバ

diph
DIPROPHEADER 構造体。次のように初期化する。
メンバ | 値
dwSize | sizeof(DIPROPGUIDANDPATH)
dwHeaderSize | sizeof(DIPROPHEADER)
dwObj | この構造体では、このメンバはゼロに設定しなければならない。
dwHow | dwObj メンバの解釈方法を指定する。この構造体では、dwHow は DIPH_DEVICE とする。

guidClass
オブジェクトのクラス GUID。
wszPath
返されるオブジェクトのパス。これは Unicode 文字列である。

注意

DIPROPGUIDANDPATH 構造体に関連付けられた DIPROP_GUIDANDPATH プロパティを使うと、詳細設定の可能なアプリケーションは、Microsoft® DirectInput® でサポートされていない HID (Human Interface Device) に対して操作を実行できる。

アプリケーションは、rguidProp パラメータに DIPROP_GUIDANDPATH を指定して IDirectInputDevice8::GetProperty メソッドを呼び出す。デバイスのクラス GUID は、DIPROPGUIDANDPATH 構造体の guidClass メンバに返される。デバイス インターフェイスのパスは、wszPath メンバに返される。その後、アプリケーションはこのパスに対して CreateFile 関数を呼び出して、デバイスに直接アクセスすることができる。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


DIPROPHEADER

すべてのプロパティ構造体のヘッダとして機能する。

typedef struct DIPROPHEADER {
    DWORD    dwSize;
    DWORD    dwHeaderSize;
    DWORD    dwObj;
    DWORD    dwHow;
} DIPROPHEADER, *LPDIPROPHEADER;

typedef const DIPROPHEADER *LPCDIPROPHEADER;

メンバ

dwSize
包含する構造体のサイズ。このメンバは、構造体が使われる前に初期化されなければならない。
dwHeaderSize
DIPROPHEADER 構造体のサイズ。
dwObj
アクセスするプロパティが属するオブジェクト。このメンバに設定する値は、dwHow メンバに指定されている値に依存する。
dwHow
dwObj メンバの解釈方法を指定する値。この値は、次のいずれか 1 つである。
値 | 意味
DIPH_DEVICE | dwObj メンバは、ゼロとする。
DIPH_BYOFFSET | dwObj メンバは、アクセスしているプロパティが属するオブジェクトの現在のデータ形式に対するオフセットである。
DIPH_BYUSAGE | dwObj メンバは、パックされた形式の HID 使用ページおよび使用状況の値である。
DIPH_BYID | dwObj メンバは、オブジェクト タイプまたはインスタンス識別子である。この識別子は、IDirectInputDevice8::EnumObjects メソッドを前回呼び出した際の戻り値である DIDEVICEOBJECTINSTANCE 構造体の dwType メンバに返される。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


DIPROPPOINTER

UINT_PTR 型のデータ値の設定と取得に使用する。通常、この値はアクション マップのデバイス オブジェクトに関連付けられたアプリケーション固有のアクションに関連付けられた値であるが、関数ポインタも使用できる。

typedef struct DIPROPPOINTER {
    DIPROPHEADER diph;
    UINT_PTR     uData;
} DIPROPPOINTER, *LPDIPROPPOINTER;

typedef const DIPROPPOINTER *LPCDIPROPPOINTER;

メンバ

diph
DIPROPHEADER 構造体。次のように初期化する。
メンバ | 値
dwSize | sizeof(DIPROPPOINTER)
dwHeaderSize | sizeof(DIPROPHEADER)
dwObj dwHow メンバが DIPH_DEVICE であれば、このメンバはゼロとする。

dwHow メンバが DIPH_BYID であれば、このメンバは、設定または取得されるプロパティを持つオブジェクトの識別子とする。

dwHow メンバが DIPH_ BYOFFSET であれば、このメンバは、設定または取得されるプロパティを持つオブジェクトのデータ形式オフセットとする。たとえば、c_dfDIMouse データ形式を選ぶと、このメンバは DIMOFS_* 値のうちどれか 1 つとしなければならない。

dwHow メンバが DIPH_BYUSAGE であれば、デバイスは HID (Human Interface Device) とする。デバイス オブジェクトは、パックされた形式の HID 使用ページおよび使用状況の値によって識別される。

dwHow | dwObj メンバの解釈方法を指定する。詳細については、この表の dwObj メンバの説明を参照すること。
uData
UINT_PTR 型のアプリケーション定義の値であり、デバイス コントロールに関連付けられた uAppData 値 (アクション マップにある) を表す。


DIPROPRANGE

デバイス内のオブジェクトの範囲に関する情報を格納する。この構造体は、IDirectInputDevice8::GetProperty および IDirectInputDevice8::SetProperty メソッドで DIPROP_RANGE フラグを設定して使用する。

typedef struct DIPROPRANGE {
    DIPROPHEADER diph;
    LONG         lMin;
    LONG         lMax;
} DIPROPRANGE, *LPDIPROPRANGE;

typedef const DIPROPRANGE *LPCDIPROPRANGE;

メンバ

diph
DIPROPHEADER 構造体。次のように初期化する。
メンバ | 値
dwSize | sizeof(DIPROPRANGE)
dwHeaderSize | sizeof(DIPROPHEADER)
dwObj dwHow メンバが DIPH_DEVICE であれば、このメンバはゼロとする。

dwHow メンバが DIPH_BYID であれば、このメンバは、設定または取得されるプロパティを持つオブジェクトの識別子とする。

dwHow メンバが DIPH_ BYOFFSET であれば、このメンバは、設定または取得されるプロパティを持つオブジェクトのデータ形式オフセットとする。たとえば、c_dfDIMouse データ形式を選択すると、このメンバは DIMOFS_* 値のどれか 1 つとしなければならない。取得または設定するプロパティが属するオブジェクトの識別子。

dwHow メンバが DIPH_BYUSAGE であれば、デバイスは HID (Human Interface Device) とする。デバイス オブジェクトは、パックされた形式の HID 使用ページおよび使用状況の値によって識別される。

dwHow | dwObj メンバの解釈方法を指定する。詳細については、この表の dwObj メンバの説明を参照すること。

lMin
範囲の下限。デバイスの範囲に制限がなければ、IDirectInputDevice8::GetProperty メソッドが戻るとき、この値は DIPROPRANGE_NOMIN となる。
lMax
範囲の上限。デバイスの範囲に制限がなければ、IDirectInputDevice8::GetProperty メソッドが戻るとき、この値は DIPROPRANGE_ NOMAX となる。

注意

範囲に制限のないデバイスに対する範囲値は、循環する。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。

参照

IDirectInputDevice8::GetProperty、IDirectInputDevice8::SetProperty


DIPROPSTRING

プロパティを文字列として取得する。

typedef struct DIPROPSTRING {
    DIPROPHEADER diph;
    WCHAR        wsz[MAX_PATH];
} DIPROPSTRING, * LPDIPROPSTRING;;

typedef const DIPROPSTRING *LPCDIPROPSTRING;

メンバ

diph
DIPROPHEADER 構造体。次のように初期化する。
メンバ | 値
dwSize | sizeof(DIPROPSTRING)
dwHeaderSize | sizeof(DIPROPHEADER)
dwObj dwHow メンバが DIPH_DEVICE であれば、このメンバはゼロとする。

dwHow メンバが DIPH_BYID であれば、このメンバは、設定または取得されるプロパティを持つオブジェクトの識別子とする。

dwHow メンバが DIPH_ BYOFFSET であれば、このメンバは、設定または取得されるプロパティを持つオブジェクトのデータ形式オフセットとする。たとえば、c_dfDIMouse データ形式を選ぶと、このメンバは DIMOFS_* 値のうちどれか 1 つとしなければならない。

dwHow メンバが DIPH_BYUSAGE であれば、デバイスは HID (Human Interface Device) とする。デバイス オブジェクトは、パックされた形式の HID 使用ページおよび使用状況の値によって識別される。

dwHow | dwObj メンバの解釈方法を指定する。詳細については、この表の dwObj メンバの説明を参照すること。

wsz
プロパティを指定または取得する Unicode 文字列。

注意

DIPROPSTRING 構造体に関連付けられた DIPROP_INSTANCENAME および DIPROP_PRODUCTNAME プロパティを使うと、詳細設定の可能なアプリケーションは、Microsoft® DirectInput® でサポートされていない HID (Human Interface Device) に対して操作を実行できる。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


DIRAMPFORCE

DIEFT_RAMPFORCE としてマークされているエフェクトのタイプ固有の情報を格納する。この構造体は傾斜フォース エフェクトを表す。

エフェクトに関する単一の DIRAMPFORCE 構造体へのポインタは、DIEFFECT 構造体の lpvTypeSpecificParams メンバに渡される。

typedef struct DIRAMPFORCE {
    LONG lStart;
    LONG lEnd;
} DIRAMPFORCE, *LPDIRAMPFORCE;

typedef const DIRAMPFORCE *LPCDIRAMPFORCE;

メンバ

lStart
-10,000 ～ 10.000 の範囲にある、エフェクトの始点のマグニチュード。
lEnd
-10,000 ～ 10.000 の範囲にある、エフェクトの終点のマグニチュード。

注意

傾斜フォース エフェクトの dwDuration は、INFINITE にはできない。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。


デバイス定数

ここでは、キー、ボタンおよび軸に対するデータを解釈するのに使用する定数に関するリファレンスを提供する。

  • キーボード デバイス定数
  • DirectInput と日本語キーボード
  • マウス デバイス定数
  • ジョイスティック デバイス定数


キーボード デバイス定数

Dinput.h に定義されているキーボード デバイス定数は、キーボード デバイスのデータ パケット (256 バイト配列) 内でのオフセットを表す。指定のオフセット位置のデータは、キーボード キーに関連付けられている。通常、それらの値は、DIDEVICEOBJECTDATA、DIOBJECTDATAFORMAT、または DIDEVICEOBJECTINSTANCE 構造体の dwOfs メンバの中で使用されるか、あるいは配列の記法を使用して配列内のデータにアクセスするときのインデックスとして使用される。

標準キーボード デバイス定数は、以下のとおりである。

定数 | メモ
DIK_0 | メイン キーボード上
DIK_1 | メイン キーボード上
DIK_2 | メイン キーボード上
DIK_3 | メイン キーボード上
DIK_4 | メイン キーボード上
DIK_5 | メイン キーボード上
DIK_6 | メイン キーボード上
DIK_7 | メイン キーボード上
DIK_8 | メイン キーボード上
DIK_9 | メイン キーボード上
DIK_A |
DIK_ABNT_C1 | ブラジル語キーボードのテンキー上
DIK_ABNT_C2 | ブラジル語キーボードのテンキー上
DIK_ADD | テンキー上のプラス記号 (+)
DIK_APOSTROPHE |
DIK_APPS | アプリケーション キー
DIK_AT | 日本語キーボード上
DIK_AX | 日本語キーボード上
DIK_B |
DIK_BACK | BackSpace
DIK_BACKSLASH |
DIK_C |
DIK_CALCULATOR |
DIK_CAPITAL | Caps Lock
DIK_COLON | 日本語キーボード上
DIK_COMMA |
DIK_CONVERT | 日本語キーボード上
DIK_D |
DIK_DECIMAL | テンキー上のピリオド (小数点)
DIK_DELETE |
DIK_DIVIDE | テンキー上のスラッシュ (/)
DIK_DOWN | 下矢印キー
DIK_E |
DIK_END |
DIK_EQUALS | メイン キーボード上
DIK_ESCAPE |
DIK_F |
DIK_F1 |
DIK_F2 |
DIK_F3 |
DIK_F4 |
DIK_F5 |
DIK_F6 |
DIK_F7 |
DIK_F8 |
DIK_F9 |
DIK_F10 |
DIK_F11 |
DIK_F12 |
DIK_F13 | NEC PC-98 日本語キーボード上
DIK_F14 | NEC PC-98 日本語キーボード上
DIK_F15 | NEC PC-98 日本語キーボード上
DIK_G |
DIK_GRAVE | アクサン グラーブ (`) キー
DIK_H |
DIK_HOME |
DIK_I |
DIK_INSERT |
DIK_J |
DIK_K |
DIK_KANA | 日本語キーボード上
DIK_KANJI | 日本語キーボード上
DIK_L |
DIK_LBRACKET | 左角かっこ [
DIK_LCONTROL | 左 Ctrl キー
DIK_LEFT | 左矢印キー
DIK_LMENU | 左 Alt キー
DIK_LSHIFT | 左 Shift キー
DIK_LWIN | 左 Microsoft® Windows® キー
DIK_M |
DIK_MAIL |
DIK_MEDIASELECT | システムでサポートされているメディア プレーヤーの選択を表示する、メディア選択キー。
DIK_MEDIASTOP |
DIK_MINUS | メイン キーボード上
DIK_MULTIPLY | テンキー上のアスタリスク (*)
DIK_MUTE |
DIK_MYCOMPUTER |
DIK_N |
DIK_NEXT | PageDown キー
DIK_NEXTTRACK | 次のトラック
DIK_NOCONVERT | 日本語キーボード上
DIK_NUMLOCK |
DIK_NUMPAD0 |
DIK_NUMPAD1 |
DIK_NUMPAD2 |
DIK_NUMPAD3 |
DIK_NUMPAD4 |
DIK_NUMPAD5 |
DIK_NUMPAD6 |
DIK_NUMPAD7 |
DIK_NUMPAD8 |
DIK_NUMPAD9 |
DIK_NUMPADCOMMA | NEC PC-98 日本語キーボード テンキー上
DIK_NUMPADENTER |
DIK_NUMPADEQUALS | NEC PC-98 日本語キーボード テンキー上
DIK_O |
DIK_OEM_102 | 英語キーボードおよびドイツ語キーボード上
DIK_P |
DIK_PAUSE |
DIK_PERIOD | メイン キーボード上
DIK_PLAYPAUSE |
DIK_POWER |
DIK_PREVTRACK | 前のトラック、日本語キーボードのサーカムフレックス
DIK_PRIOR | PageUp キー
DIK_Q |
DIK_R |
DIK_RBRACKET | 右角かっこ ]
DIK_RCONTROL | 右 Ctrl キー
DIK_RETURN | メイン キーボード上の Enter キー
DIK_RIGHT | 右矢印キー
DIK_RMENU | 右 Alt キー
DIK_RSHIFT | 右 Shift キー
DIK_RWIN | 右 Windows キー
DIK_S |
DIK_SCROLL | ScrollLock
DIK_SEMICOLON |
DIK_SLASH | メイン キーボード上のスラッシュ (/)
DIK_SLEEP |
DIK_SPACE | スペース キー
DIK_STOP | NEC PC-98 日本語キーボード上
DIK_SUBTRACT | テンキー上のマイナス記号 (-)
DIK_SYSRQ |
DIK_T |
DIK_TAB |
DIK_U |
DIK_UNDERLINE | NEC PC-98 日本語キーボード上
DIK_UNLABELED | 日本語キーボード上
DIK_UP | 上矢印キー
DIK_V |
DIK_VOLUMEDOWN |
DIK_VOLUMEUP |
DIK_W |
DIK_WAKE |
DIK_WEBBACK |
DIK_WEBFAVORITES | Microsoft Internet Explorer の [お気に入り] リスト、Windows の [Favorites] フォルダ、または Netscape のブックマーク リストを表示する。
DIK_WEBFORWARD |
DIK_WEBHOME |
DIK_WEBREFRESH |
DIK_WEBSEARCH |
DIK_WEBSTOP |
DIK_X |
DIK_Y |
DIK_YEN | 日本語キーボード上
DIK_Z |

以下の代替名も使用可能である。

代替名 | 通常名 | メモ
DIK_BACKSPACE | DIK_BACK | BackSpace
DIK_CAPSLOCK | DIK_CAPITAL | Caps Lock
DIK_CIRCUMFLEX | DIK_PREVTRACK | 日本語キーボード上
DIK_DOWNARROW | DIK_DOWN | 矢印キーパッド上
DIK_LALT | DIK_LMENU | 左 Alt キー
DIK_LEFTARROW | DIK_LEFT | 矢印キーパッド上
DIK_NUMPADMINUS | DIK__SUBTRACT | テンキー上のマイナス記号 (-)
DIK_NUMPADPERIOD | DIK_DECIMAL | テンキー上のピリオド (小数点)
DIK_NUMPADPLUS | DIK_ADD | テンキー上のプラス記号 (+)
DIK_NUMPADSLASH | DIK__DIVIDE | テンキー上のスラッシュ (/)
DIK_NUMPADSTAR | DIK_MULTIPLY | テンキー上のアスタリスク (*)
DIK_PGDN | DIK_NEXT | 矢印キーパッド上
DIK_PGUP | DIK_PRIOR | 矢印キーパッド上
DIK_RALT | DIK_RMENU | 右 Alt キー
DIK_RIGHTARROW | DIK_RIGHT | 矢印キーパッド上
DIK_UPARROW | DIK_UP | 矢印キーパッド上

日本語キーボードについては、「DirectInput と日本語キーボード」を参照すること。


DirectInput と日本語キーボード

以下に、標準の US キーボードにはないが、日本語キーボードで使用可能な拡張キーと、US キーボードでは使用可能であるが、多くの日本語キーボードにはないキーの一覧を示す。

Microsoft® Windows® 2000 または他のオペレーティング システム上の (NEC PC-98 のような) キーボードでは、DIK_CAPSLOCK、DIK_KANJI、および DIK_KANA キーはトグル ボタンであり、プッシュ ボタンではない。これらのキーは、最初に押されたときにダウン イベントを生成し、2 回目に押されたときにアップ イベントを生成する。

日本語キーボード | 拡張キー | 欠けるキー
DOS/V 106、NEC PC-98 106 | DIK_AT、DIK_CIRCUMFLEX、DIK_COLON、DIK_CONVERT、DIK_KANA、DIK_KANJI、DIK_NOCONVERT、DIK_YEN | DIK_APOSTROPHE、DIK_EQUALS、DIK_GRAVE
NEC PC-98 | DIK_AT、DIK_CIRCUMFLEX、DIK_COLON、DIK_F13, DIK_F14、DIK_F15、DIK_KANA、DIK_KANJI、DIK_NOCONVERT、DIK_NUMPADCOMMA、DIK_NUMPADEQUALS、DIK_STOP、DIK_UNDERLINE、DIK_YEN | DIK_APOSTROPHE、DIK_BACKSLASH、DIK_EQUALS、DIK_GRAVE、DIK_NUMLOCK、DIK_NUMPADENTER、DIK_RCONTROL、DIK_RMENU、DIK_RSHIFT、DIK_SCROLL
AX | DIK_AX、DIK_CONVERT、DIK_KANJI、DIK_NOCONVERT、DIK_YEN | DIK_RCONTROL、DIK_RMENU
J-3100 | DIK_KANA、DIK_KANJI、DIK_NOLABEL、DIK_YEN | DIK_RCONTROL、DIK_RMENU


マウス デバイス定数

Dinput.h に定義されているマウス デバイス定数は、マウス デバイスのデータ パケットである DIMOUSESTATE または DIMOUSESTATE2 構造体に対するオフセットを表す。指定のオフセット位置にあるデータは、デバイス オブジェクト (ボタンまたは軸) に関連付けられている。通常、それらの値は、DIDEVICEOBJECTDATA、DIOBJECTDATAFORMAT、または DIDEVICEOBJECTINSTANCE 構造体の dwOfs メンバに使用される。

マウス デバイス定数は、以下のとおりである。

定数 | メモ
DIMOFS_BUTTON0 |
DIMOFS_BUTTON1 |
DIMOFS_BUTTON2 |
DIMOFS_BUTTON3
DIMOFS_BUTTON4 | DIMOUSESTATE2 のみ
DIMOFS_BUTTON5 | DIMOUSESTATE2 のみ
DIMOFS_BUTTON6 | DIMOUSESTATE2 のみ
DIMOFS_BUTTON7 | DIMOUSESTATE2 のみ
DIMOFS_X |
DIMOFS_Y
DIMOFS_Z |


ジョイスティック デバイス定数

ジョイスティック デバイス定数は、ジョイスティック デバイスのデータ パケットである DIJOYSTATE 構造体に対するオフセットを表す。指定のオフセットにあるデータは、デバイス オブジェクト、すなわちボタンまたは軸と関連付けられている。通常、それらの値は、DIDEVICEOBJECTDATA、DIOBJECTDATAFORMAT、または DIDEVICEOBJECTINSTANCE 構造体の dwOfs メンバに使用される。

次のマクロは、常に状態を示すデータのオフセットを返すが、そのデータは DIJOYSTATE 構造体の先頭に関連付けられた特定のボタンまたは軸によって決まる。

定数 | デバイス オブジェクト
DIJOFS_BUTTON0 から DIJOFS_BUTTON31 または DIJOFS_BUTTON(n) | ボタン
DIJOFS_POV(n) | 視点インジケータ
DIJOFS_RX | x 軸回転
DIJOFS_RY | y 軸回転
DIJOFS_RZ | z 軸回転 (方向舵)
DIJOFS_X | x 軸
DIJOFS_Y | y 軸
DIJOFS_Z | z 軸
DIJOFS_SLIDER(n) | スライダ軸


アクション マッピング定数

ここでは、アプリケーションのジャンルと各ジャンル内のアクションにマップされたコントロール用に、Dinput.h に定義された定数のリファレンスを提供する。

DIAXIS_FIGHTINGH_MOVE などのコントロール定数は、DIACTION 構造体の dwSemantic メンバの中で、コントロールをアプリケーション内のアクションに関連付けるために使用される。

DIVIRTUAL_FIGHTING_HAND2HAND などのジャンル定数は、DIACTIONFORMAT 構造体の dwGenre メンバの中で使用される。

アクション マッピング定数は、次のカテゴリのアプリケーション ジャンル用に提供されている。

  • アクション ジャンル
  • アーケード ジャンル
  • CAD ジャンル
  • コントロール ジャンル
  • ドライビング ジャンル
  • フライト ジャンル
  • スポーツ ジャンル
  • ストラテジ ジャンル

DIACTION 構造体の dwSemantic メンバを使って、アクションを仮想コントロールではなく特定のデバイス オブジェクトにマップすることができる。デバイス オブジェクト定数は、次のカテゴリに提供されている。

  • キーボード マッピング定数
  • マウス マッピング定数
  • DirectPlay 音声マッピング定数
  • 任意コントロール定数


アクション ジャンル

次のジャンルには、戦闘ゲームやアクション ゲーム用のコントロールが含まれる。

  • 格闘
  • シューティング
  • 非対面型のアクション


格闘

DIVIRTUAL_FIGHTING_HAND2HAND ジャンルには、銃を使用しない対面型の格闘ゲームのコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_FIGHTINGH_LATERAL
DIAXIS_FIGHTINGH_MOVE
DIBUTTON_FIGHTINGH_BLOCK
DIBUTTON_FIGHTINGH_CROUCH
DIBUTTON_FIGHTINGH_JUMP
DIBUTTON_FIGHTINGH_KICK
DIBUTTON_FIGHTINGH_MENU
DIBUTTON_FIGHTINGH_PUNCH
DIBUTTON_FIGHTINGH_SPECIAL1
DIBUTTON_FIGHTINGH_SPECIAL2

優先順位 2 のコントロール
DIAXIS_FIGHTINGH_ROTATE
DIBUTTON_FIGHTINGH_BACKWARD_LINK
DIBUTTON_FIGHTINGH_DEVICE
DIBUTTON_FIGHTINGH_DISPLAY
DIBUTTON_FIGHTINGH_DODGE
DIBUTTON_FIGHTINGH_FORWARD_LINK
DIBUTTON_FIGHTINGH_LEFT_LINK
DIBUTTON_FIGHTINGH_RIGHT_LINK
DIBUTTON_FIGHTINGH_PAUSE
DIBUTTON_FIGHTINGH_SELECT
DIHATSWITCH_FIGHTINGH_SLIDE


シューティング

DIVIRTUAL_FIGHTING_FPS ジャンルには、銃を使用する対面型の戦闘ゲームのコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_FPS_LOOKUPDOWN
DIAXIS_FPS_MOVE
DIAXIS_FPS_ROTATE
DIBUTTON_FPS_APPLY
DIBUTTON_FPS_CROUCH
DIBUTTON_FPS_FIRE
DIBUTTON_FPS_JUMP
DIBUTTON_FPS_MENU
DIBUTTON_FPS_SELECT
DIBUTTON_FPS_STRAFE
DIBUTTON_FPS_WEAPONS

優先順位 2 のコントロール
DIAXIS_FPS_SIDESTEP
DIBUTTON_FPS_BACKWARD_LINK
DIBUTTON_FPS_DEVICE
DIBUTTON_FPS_DISPLAY
DIBUTTON_FPS_DODGE
DIBUTTON_FPS_FIRESECONDARY
DIBUTTON_FPS_FORWARD_LINK
DIBUTTON_FPS_GLANCE_DOWN_LINK
DIBUTTON_FPS_GLANCE_UP_LINK
DIBUTTON_FPS_GLANCEL
DIBUTTON_FPS_GLANCER
DIBUTTON_FPS_PAUSE
DIBUTTON_FPS_ROTATE_LEFT_LINK
DIBUTTON_FPS_ROTATE_RIGHT_LINK
DIHATSWITCH_FPS_GLANCE


非対面型のアクション

DIVIRTUAL_FIGHTING_THIRDPERSON ジャンルには、非対面型のアクション ゲームのコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_TPS_MOVE
DIAXIS_TPS_TURN
DIBUTTON_TPS_ACTION
DIBUTTON_TPS_JUMP
DIBUTTON_TPS_MENU
DIBUTTON_TPS_RUN
DIBUTTON_TPS_SELECT
DIBUTTON_TPS_USE

優先順位 2 のコントロール
DIAXIS_TPS_STEP
DIBUTTON_TPS_BACKWARD_LINK
DIBUTTON_TPS_DEVICE
DIBUTTON_TPS_DODGE
DIBUTTON_TPS_FORWARD_LINK
DIBUTTON_TPS_GLANCE_DOWN_LINK
DIBUTTON_TPS_GLANCE_LEFT_LINK
DIBUTTON_TPS_GLANCE_RIGHT_LINK
DIBUTTON_TPS_GLANCE_UP_LINK
DIBUTTON_TPS_INVENTORY
DIBUTTON_TPS_PAUSE
DIBUTTON_TPS_STEPLEFT
DIBUTTON_TPS_STEPRIGHT
DIBUTTON_TPS_TURN_LEFT_LINK
DIBUTTON_TPS_TURN_RIGHT_LINK
DIBUTTON_TPS_VIEW
DIHATSWITCH_TPS_GLANCE


アーケード ジャンル

次のジャンルには、危険な状況の中でキャラクタを動かすことを目的とする、アーケード型ゲームのコントロールが含まれる。

  • プラットフォーム
  • サイドツーサイド


プラットフォーム

DIVIRTUAL_ARCADE_PLATFORM ジャンルには、アーケード型ゲームのコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_ARCADEP_LATERAL
DIAXIS_ARCADEP_MOVE
DIBUTTON_ARCADEP_CROUCH
DIBUTTON_ARCADEP_FIRE
DIBUTTON_ARCADEP_JUMP
DIBUTTON_ARCADEP_MENU
DIBUTTON_ARCADEP_SELECT
DIBUTTON_ARCADEP_SPECIAL

優先順位 2 のコントロール
DIBUTTON_ARCADEP_BACK_LINK
DIBUTTON_ARCADEP_DEVICE
DIBUTTON_ARCADEP_FIRESECONDARY
DIBUTTON_ARCADEP_FORWARD_LINK
DIBUTTON_ARCADEP_LEFT_LINK
DIBUTTON_ARCADEP_PAUSE
DIBUTTON_ARCADEP_RIGHT_LINK
DIBUTTON_ARCADEP_VIEW_DOWN_LINK
DIBUTTON_ARCADEP_VIEW_LEFT_LINK
DIBUTTON_ARCADEP_VIEW_RIGHT_LINK
DIBUTTON_ARCADEP_VIEW_UP_LINK
DIHATSWITCH_ARCADEP_VIEW


サイドツーサイド

DIVIRTUAL_ARCADE_SIDE2SIDE ジャンルには、アーケード型 2 次元ゲームのコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_ARCADES_LATERAL
DIAXIS_ARCADES_MOVE
DIBUTTON_ARCADES_ATTACK
DIBUTTON_ARCADES_CARRY
DIBUTTON_ARCADES_MENU
DIBUTTON_ARCADES_SELECT
DIBUTTON_ARCADES_SPECIAL
DIBUTTON_ARCADES_THROW

優先順位 2 のコントロール
DIBUTTON_ARCADES_BACK_LINK
DIBUTTON_ARCADES_DEVICE
DIBUTTON_ARCADES_FORWARD_LINK
DIBUTTON_ARCADES_LEFT_LINK
DIBUTTON_ARCADES_PAUSE
DIBUTTON_ARCADES_RIGHT_LINK
DIBUTTON_ARCADES_VIEW_DOWN_LINK
DIBUTTON_ARCADES_VIEW_LEFT_LINK
DIBUTTON_ARCADES_VIEW_RIGHT_LINK
DIBUTTON_ARCADES_VIEW_UP_LINK
DIHATSWITCH_ARCADES_VIEW


CAD ジャンル

次のジャンルには、CAD (Computer-Assisted Drafting) アプリケーション用のコントロールが含まれる。

  • 2D オブジェクト
  • 3D モデル
  • 3D ナビゲーション
  • 3D オブジェクト


2D オブジェクト

DIVIRTUAL_CAD_2DCONTROL ジャンルには、2 次元の設計環境でオブジェクトの選択、移動を行うためのコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_2DCONTROL_LATERAL
DIAXIS_2DCONTROL_MOVE
DIAXIS_2DCONTROL_INOUT
DIBUTTON_2DCONTROL_MENU
DIBUTTON_2DCONTROL_SELECT
DIBUTTON_2DCONTROL_SPECIAL
DIBUTTON_2DCONTROL_SPECIAL1
DIBUTTON_2DCONTROL_SPECIAL2

優先順位 2 のコントロール
DIAXIS_2DCONTROL_ROTATEZ
DIBUTTON_2DCONTROL_DEVICE
DIBUTTON_2DCONTROL_DISPLAY
DIBUTTON_2DCONTROL_PAUSE
DIHATSWITCH_2DCONTROL_HATSWITCH


3D モデル

DIVIRTUAL_CAD_MODEL ジャンルには、3 次元オブジェクト モデリング用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_CADM_LATERAL
DIAXIS_CADM_MOVE
DIAXIS_CADM_INOUT
DIBUTTON_CADM_MENU
DIBUTTON_CADM_SELECT
DIBUTTON_CADM_SPECIAL
DIBUTTON_CADM_SPECIAL1
DIBUTTON_CADM_SPECIAL2

優先順位 2 のコントロール
DIAXIS_CADM_ROTATEX
DIAXIS_CADM_ROTATEY
DIAXIS_CADM_ROTATEZ
DIBUTTON_CADM_DEVICE
DIBUTTON_CADM_DISPLAY
DIBUTTON_CADM_PAUSE
DIHATSWITCH_CADM_HATSWITCH


3D ナビゲーション

DIVIRTUAL_CAD_FLYBY ジャンルには、3 次元環境のフライスルー ナビゲーション用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_CADF_LATERAL
DIAXIS_CADF_MOVE
DIAXIS_CADF_INOUT
DIBUTTON_CADF_MENU
DIBUTTON_CADF_SELECT
DIBUTTON_CADF_SPECIAL
DIBUTTON_CADF_SPECIAL1
DIBUTTON_CADF_SPECIAL2

優先順位 2 のコントロール
DIAXIS_CADF_ROTATEX
DIAXIS_CADF_ROTATEY
DIAXIS_CADF_ROTATEZ
DIBUTTON_CADF_DEVICE
DIBUTTON_CADF_DISPLAY
DIBUTTON_CADF_PAUSE
DIHATSWITCH_CADF_HATSWITCH


3D オブジェクト

DIVIRTUAL_CAD_3DCONTROL ジャンルには、3 次元の設計環境でオブジェクトの選択、移動を行うためのコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_3DCONTROL_LATERAL
DIAXIS_3DCONTROL_MOVE
DIAXIS_3DCONTROL_INOUT
DIBUTTON_3DCONTROL_MENU
DIBUTTON_3DCONTROL_SELECT
DIBUTTON_3DCONTROL_SPECIAL
DIBUTTON_3DCONTROL_SPECIAL1
DIBUTTON_3DCONTROL_SPECIAL2

優先順位 2 のコントロール
DIAXIS_3DCONTROL_ROTATEX
DIAXIS_3DCONTROL_ROTATEY
DIAXIS_3DCONTROL_ROTATEZ
DIBUTTON_3DCONTROL_DEVICE
DIBUTTON_3DCONTROL_DISPLAY
DIBUTTON_3DCONTROL_PAUSE
DIHATSWITCH_3DCONTROL_HATSWITCH


コントロール ジャンル

次のジャンルには、Web ブラウザとリモートコントロール デバイスで使用されるコントロールが含まれる。

  • ブラウザ
  • リモート コントロール


ブラウザ

DIVIRTUAL_BROWSER_CONTROL ジャンルには、Web ブラウザ用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_BROWSER_LATERAL
DIAXIS_BROWSER_MOVE
DIAXIS_BROWSER_VIEW
DIBUTTON_BROWSER_MENU
DIBUTTON_BROWSER_REFRESH
DIBUTTON_BROWSER_SELECT

優先順位 2 のコントロール
DIBUTTON_BROWSER_DEVICE
DIBUTTON_BROWSER_FAVORITES
DIBUTTON_BROWSER_HISTORY
DIBUTTON_BROWSER_HOME
DIBUTTON_BROWSER_NEXT
DIBUTTON_BROWSER_PAUSE
DIBUTTON_BROWSER_PREVIOUS
DIBUTTON_BROWSER_PRINT
DIBUTTON_BROWSER_SEARCH
DIBUTTON_BROWSER_STOP


リモート コントロール

DIVIRTUAL_REMOTE_CONTROL ジャンルには、メディア プレーヤーなどの装置で使用されるリモートコントロール デバイス用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_REMOTE_SLIDER
DIBUTTON_REMOTE_CHANGE
DIBUTTON_REMOTE_CUE
DIBUTTON_REMOTE_MENU
DIBUTTON_REMOTE_MUTE
DIBUTTON_REMOTE_PLAY
DIBUTTON_REMOTE_RECORD
DIBUTTON_REMOTE_REVIEW
DIBUTTON_REMOTE_SELECT

優先順位 2 のコントロール
DIAXIS_REMOTE_SLIDER2
DIBUTTON_REMOTE_ADJUST
DIBUTTON_REMOTE_CABLE
DIBUTTON_REMOTE_CD
DIBUTTON_REMOTE_DEVICE
DIBUTTON_REMOTE_DIGIT0
DIBUTTON_REMOTE_DIGIT1
DIBUTTON_REMOTE_DIGIT2
DIBUTTON_REMOTE_DIGIT3
DIBUTTON_REMOTE_DIGIT4
DIBUTTON_REMOTE_DIGIT5
DIBUTTON_REMOTE_DIGIT6
DIBUTTON_REMOTE_DIGIT7
DIBUTTON_REMOTE_DIGIT8
DIBUTTON_REMOTE_DIGIT9
DIBUTTON_REMOTE_DVD
DIBUTTON_REMOTE_PAUSE
DIBUTTON_REMOTE_TUNER
DIBUTTON_REMOTE_TV
DIBUTTON_REMOTE_VCR


ドライビング ジャンル

次のジャンルは、プレーヤーがレーシングや戦闘で車を制御するゲームで使用される。

  • コンバット レーシング
  • ロボット戦闘
  • レーシング
  • タンク


コンバット レーシング

DIVIRTUAL_DRIVING_COMBAT ジャンルには、戦闘のある乗り物レース ゲーム用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_DRIVINGC_ACCELERATE
DIAXIS_DRIVINGC_BRAKE
DIAXIS_DRIVINGC_STEER
DIBUTTON_DRIVINGC_FIRE
DIBUTTON_DRIVINGC_MENU
DIBUTTON_DRIVINGC_TARGET
DIBUTTON_DRIVINGC_WEAPONS

優先順位 2 のコントロール
DIAXIS_DRIVINGC_ACCEL_AND_BRAKE
DIBUTTON_DRIVINGC_ACCELERATE_LINK
DIBUTTON_DRIVINGC_AIDS
DIBUTTON_DRIVINGC_BRAKE
DIBUTTON_DRIVINGC_DASHBOARD
DIBUTTON_DRIVINGC_DEVICE
DIBUTTON_DRIVINGC_FIRESECONDARY
DIBUTTON_DRIVINGC_GLANCE_LEFT_LINK
DIBUTTON_DRIVINGC_GLANCE_RIGHT_LINK
DIBUTTON_DRIVINGC_PAUSE
DIBUTTON_DRIVINGC_SHIFTDOWN
DIBUTTON_DRIVINGC_SHIFTUP
DIBUTTON_DRIVINGC_STEER_LEFT_LINK
DIBUTTON_DRIVINGC_STEER_RIGHT_LINK
DIHATSWITCH_DRIVINGC_GLANCE


ロボット戦闘

DIVIRTUAL_DRIVING_MECHA ジャンルには、ロボット戦闘ゲームにおける歩行ロボット (メック) 用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_MECHA_ROTATE
DIAXIS_MECHA_STEER
DIAXIS_MECHA_THROTTLE
DIAXIS_MECHA_TORSO
DIBUTTON_MECHA_FIRE
DIBUTTON_MECHA_JUMP
DIBUTTON_MECHA_MENU
DIBUTTON_MECHA_REVERSE
DIBUTTON_MECHA_TARGET
DIBUTTON_MECHA_WEAPONS
DIBUTTON_MECHA_ZOOM

優先順位 2 のコントロール
DIBUTTON_MECHA_BACK_LINK
DIBUTTON_MECHA_CENTER
DIBUTTON_MECHA_DEVICE
DIBUTTON_MECHA_FASTER_LINK
DIBUTTON_MECHA_FIRESECONDARY
DIBUTTON_MECHA_FORWARD_LINK
DIBUTTON_MECHA_LEFT_LINK
DIBUTTON_MECHA_PAUSE
DIBUTTON_MECHA_RIGHT_LINK
DIBUTTON_MECHA_ROTATE_LEFT_LINK
DIBUTTON_MECHA_ROTATE_RIGHT_LINK
DIBUTTON_MECHA_SLOWER_LINK
DIBUTTON_MECHA_VIEW
DIHATSWITCH_MECHA_GLANCE


レーシング

DIVIRTUAL_DRIVING_RACE ジャンルには、戦闘のない自動車レース ゲーム用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_DRIVINGR_ACCELERATE
DIAXIS_DRIVINGR_BRAKE
DIAXIS_DRIVINGR_STEER
DIBUTTON_DRIVINGR_MENU
DIBUTTON_DRIVINGR_SHIFTDOWN
DIBUTTON_DRIVINGR_SHIFTUP
DIBUTTON_DRIVINGR_VIEW

優先順位 2 のコントロール
DIAXIS_DRIVINGR_ACCEL_AND_BRAKE
DIBUTTON_DRIVINGR_ACCELERATE_LINK
DIBUTTON_DRIVINGR_AIDS
DIBUTTON_DRIVINGR_BOOST
DIBUTTON_DRIVINGR_BRAKE
DIBUTTON_DRIVINGR_DASHBOARD
DIBUTTON_DRIVINGR_DEVICE
DIBUTTON_DRIVINGR_GLANCE_LEFT_LINK
DIBUTTON_DRIVINGR_GLANCE_RIGHT_LINK
DIBUTTON_DRIVINGR_MAP
DIBUTTON_DRIVINGR_PIT
DIBUTTON_DRIVINGR_PAUSE
DIBUTTON_DRIVINGR_STEER_LEFT_LINK
DIBUTTON_DRIVINGR_STEER_RIGHT_LINK
DIHATSWITCH_DRIVINGR_GLANCE


タンク

DIVIRTUAL_DRIVING_TANK ジャンルには、戦車シミュレーション用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_DRIVINGT_ACCELERATE
DIAXIS_DRIVINGT_BARREL
DIAXIS_DRIVINGT_ROTATE
DIAXIS_DRIVINGT_STEER
DIBUTTON_DRIVINGT_FIRE
DIBUTTON_DRIVINGT_MENU
DIBUTTON_DRIVINGT_TARGET
DIBUTTON_DRIVINGT_WEAPONS

優先順位 2 のコントロール
DIAXIS_DRIVINGT_ACCEL_AND_BRAKE
DIAXIS_DRIVINGT_BRAKE
DIBUTTON_DRIVINGT_ACCELERATE_LINK
DIBUTTON_DRIVINGT_BARREL_UP_LINK
DIBUTTON_DRIVINGT_BARREL_DOWN_LINK
DIBUTTON_DRIVINGT_BRAKE
DIBUTTON_DRIVINGT_DASHBOARD
DIBUTTON_DRIVINGT_DEVICE
DIBUTTON_DRIVINGT_FIRESECONDARY
DIBUTTON_DRIVINGT_GLANCE_LEFT_LINK
DIBUTTON_DRIVINGT_GLANCE_RIGHT_LINK
DIBUTTON_DRIVINGT_PAUSE
DIBUTTON_DRIVINGT_ROTATE_LEFT_LINK
DIBUTTON_DRIVINGT_ROTATE_RIGHT_LINK
DIBUTTON_DRIVINGT_STEER_LEFT_LINK
DIBUTTON_DRIVINGT_STEER_RIGHT_LINK
DIBUTTON_DRIVINGT_VIEW
DIHATSWITCH_DRIVINGT_GLANCE


フライト ジャンル

次のジャンルは、プレーヤーが航空機や宇宙船を制御するゲームおよびシミュレーションで使用される。

  • 空中戦
  • 民間機フライト
  • ヘリコプタ戦
  • 宇宙戦


空中戦

DIVIRTUAL_FLYING_MILITARY ジャンルには、固定翼機による空中戦闘シミュレーション用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_FLYINGM_BANK
DIAXIS_FLYINGM_PITCH
DIAXIS_FLYINGM_THROTTLE
DIBUTTON_FLYINGM_FIRE
DIBUTTON_FLYINGM_MENU
DIBUTTON_FLYINGM_TARGET
DIBUTTON_FLYINGM_WEAPONS

優先順位 2 のコントロール
DIAXIS_FLYINGM_BRAKE
DIAXIS_FLYINGM_FLAPS
DIAXIS_FLYINGM_RUDDER
DIBUTTON_FLYINGM_BRAKE_LINK
DIBUTTON_FLYINGM_COUNTER
DIBUTTON_FLYINGM_DEVICE
DIBUTTON_FLYINGM_DISPLAY
DIBUTTON_FLYINGM_FASTER_LINK
DIBUTTON_FLYINGM_FIRESECONDARY
DIBUTTON_FLYINGM_FLAPSDOWN
DIBUTTON_FLYINGM_FLAPSUP
DIBUTTON_FLYINGM_GEAR
DIBUTTON_FLYINGM_GLANCE_DOWN_LINK
DIBUTTON_FLYINGM_GLANCE_LEFT_LINK
DIBUTTON_FLYINGM_GLANCE_RIGHT_LINK
DIBUTTON_FLYINGM_GLANCE_UP_LINK
DIBUTTON_FLYINGM_PAUSE
DIBUTTON_FLYINGM_SLOWER_LINK
DIBUTTON_FLYINGM_VIEW
DIHATSWITCH_FLYINGM_GLANCE


民間機フライト

DIVIRTUAL_FLYING_CIVILIAN ジャンルには、非戦闘フライト シミュレーション用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_FLYINGC_BANK
DIAXIS_FLYINGC_PITCH
DIAXIS_FLYINGC_THROTTLE
DIBUTTON_FLYINGC_DISPLAY
DIBUTTON_FLYINGC_GEAR
DIBUTTON_FLYINGC_MENU
DIBUTTON_FLYINGC_VIEW

優先順位 2 のコントロール
DIAXIS_FLYINGC_BRAKE
DIAXIS_FLYINGC_FLAPS
DIAXIS_FLYINGC_RUDDER
DIBUTTON_FLYINGC_BRAKE_LINK
DIBUTTON_FLYINGC_DEVICE
DIBUTTON_FLYINGC_FASTER_LINK
DIBUTTON_FLYINGC_FLAPSDOWN
DIBUTTON_FLYINGC_FLAPSUP
DIBUTTON_FLYINGC_GLANCE_DOWN_LINK
DIBUTTON_FLYINGC_GLANCE_LEFT_LINK
DIBUTTON_FLYINGC_GLANCE_RIGHT_LINK
DIBUTTON_FLYINGC_GLANCE_UP_LINK
DIBUTTON_FLYINGC_PAUSE
DIBUTTON_FLYINGC_SLOWER_LINK
DIHATSWITCH_FLYINGC_GLANCE


ヘリコプタ戦

DIVIRTUAL_FLYING_HELICOPTER ジャンルには、ヘリコプタ戦闘シミュレーション用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_FLYINGH_BANK
DIAXIS_FLYINGH_COLLECTIVE
DIAXIS_FLYINGH_PITCH
DIBUTTON_FLYINGH_FIRE
DIBUTTON_FLYINGH_MENU
DIBUTTON_FLYINGH_TARGET
DIBUTTON_FLYINGH_WEAPONS

優先順位 2 のコントロール
DIAXIS_FLYINGH_THROTTLE
DIAXIS_FLYINGH_TORQUE
DIBUTTON_FLYINGH_COUNTER
DIBUTTON_FLYINGH_DEVICE
DIBUTTON_FLYINGH_FASTER_LINK
DIBUTTON_FLYINGH_FIRESECONDARY
DIBUTTON_FLYINGH_GEAR
DIBUTTON_FLYINGH_GLANCE_DOWN_LINK
DIBUTTON_FLYINGH_GLANCE_LEFT_LINK
DIBUTTON_FLYINGH_GLANCE_RIGHT_LINK
DIBUTTON_FLYINGH_GLANCE_UP_LINK
DIBUTTON_FLYINGH_PAUSE
DIBUTTON_FLYINGH_SLOWER_LINK
DIBUTTON_FLYINGH_VIEW
DIHATSWITCH_FLYINGH_GLANCE


宇宙戦

DIVIRTUAL_SPACESIM ジャンルには、宇宙船戦闘シミュレーション用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_SPACESIM_LATERAL
DIAXIS_SPACESIM_MOVE
DIAXIS_SPACESIM_THROTTLE
DIBUTTON_SPACESIM_FIRE
DIBUTTON_SPACESIM_MENU
DIBUTTON_SPACESIM_TARGET
DIBUTTON_SPACESIM_WEAPONS

優先順位 2 のコントロール
DIAXIS_SPACESIM_CLIMB
DIAXIS_SPACESIM_ROTATE
DIBUTTON_SPACESIM_BACKWARD_LINK
DIBUTTON_SPACESIM_DEVICE
DIBUTTON_SPACESIM_DISPLAY
DIBUTTON_SPACESIM_FASTER_LINK
DIBUTTON_SPACESIM_FIRESECONDARY
DIBUTTON_SPACESIM_FORWARD_LINK
DIBUTTON_SPACESIM_GEAR
DIBUTTON_SPACESIM_GLANCE_DOWN_LINK
DIBUTTON_SPACESIM_GLANCE_LEFT_LINK
DIBUTTON_SPACESIM_GLANCE_RIGHT_LINK
DIBUTTON_SPACESIM_GLANCE_UP_LINK
DIBUTTON_SPACESIM_LEFT_LINK
DIBUTTON_SPACESIM_LOWER
DIBUTTON_SPACESIM_PAUSE
DIBUTTON_SPACESIM_RAISE
DIBUTTON_SPACESIM_RIGHT_LINK
DIBUTTON_SPACESIM_SLOWER_LINK
DIBUTTON_SPACESIM_TURN_LEFT_LINK
DIBUTTON_SPACESIM_TURN_RIGHT_LINK
DIBUTTON_SPACESIM_VIEW
DIHATSWITCH_SPACESIM_GLANCE


スポーツ ジャンル

次のジャンルには、スポーツ ゲームやシミュレーション用のコントロールが含まれる。

  • 野球バッティング
  • 野球フィールディング
  • 野球ピッチング
  • バスケットボール ディフェンス
  • バスケットボール オフェンス
  • フィッシング
  • フットボール ディフェンス
  • フットボール オフェンス
  • フットボール プレー
  • フットボール クォーターバック
  • ゴルフ
  • ホッケー ディフェンス
  • ホッケー ゴールキーパー
  • ホッケー オフェンス
  • ハンティング
  • マウンテン バイク
  • ラケット
  • スキー
  • サッカー ディフェンス
  • サッカー オフェンス


野球バッティング

DIVIRTUAL_SPORTS_BASEBALL_BAT ジャンルには、野球の打者用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_BASEBALLB_LATERAL
DIAXIS_BASEBALLB_MOVE
DIBUTTON_BASEBALLB_BUNT
DIBUTTON_BASEBALLB_BURST
DIBUTTON_BASEBALLB_CONTACT
DIBUTTON_BASEBALLB_MENU
DIBUTTON_BASEBALLB_NORMAL
DIBUTTON_BASEBALLB_POWER
DIBUTTON_BASEBALLB_SELECT
DIBUTTON_BASEBALLB_SLIDE
DIBUTTON_BASEBALLB_STEAL

優先順位 2 のコントロール
DIBUTTON_BASEBALLB_BOX
DIBUTTON_BASEBALLB_BACK_LINK
DIBUTTON_BASEBALLB_DEVICE
DIBUTTON_BASEBALLB_FORWARD_LINK
DIBUTTON_BASEBALLB_LEFT_LINK
DIBUTTON_BASEBALLB_NOSTEAL
DIBUTTON_BASEBALLB_PAUSE
DIBUTTON_BASEBALLB_RIGHT_LINK


野球フィールディング

DIVIRTUAL_SPORTS_BASEBALL_FIELD ジャンルには、野球の野手用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_BASEBALLF_LATERAL
DIAXIS_BASEBALLF_MOVE
DIBUTTON_BASEBALLF_BURST
DIBUTTON_BASEBALLF_DIVE
DIBUTTON_BASEBALLF_JUMP
DIBUTTON_BASEBALLF_MENU
DIBUTTON_BASEBALLF_NEAREST
DIBUTTON_BASEBALLF_THROW1
DIBUTTON_BASEBALLF_THROW2

優先順位 2 のコントロール
DIBUTTON_BASEBALLF_AIM_LEFT_LINK
DIBUTTON_BASEBALLF_AIM_RIGHT_LINK
DIBUTTON_BASEBALLF_BACK_LINK
DIBUTTON_BASEBALLF_DEVICE
DIBUTTON_BASEBALLF_FORWARD_LINK
DIBUTTON_BASEBALLF_PAUSE
DIBUTTON_BASEBALLF_SHIFTIN
DIBUTTON_BASEBALLF_SHIFTOUT


野球ピッチング

DIVIRTUAL_SPORTS_BASEBALL_PITCH ジャンルには、野球の投手用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_BASEBALLP_LATERAL
DIAXIS_BASEBALLP_MOVE
DIBUTTON_BASEBALLP_BASE
DIBUTTON_BASEBALLP_FAKE
DIBUTTON_BASEBALLP_MENU
DIBUTTON_BASEBALLP_PITCH
DIBUTTON_BASEBALLP_SELECT
DIBUTTON_BASEBALLP_THROW

優先順位 2 のコントロール
DIBUTTON_BASEBALLP_BACK_LINK
DIBUTTON_BASEBALLP_DEVICE
DIBUTTON_BASEBALLP_FORWARD_LINK
DIBUTTON_BASEBALLP_LEFT_LINK
DIBUTTON_BASEBALLP_LOOK
DIBUTTON_BASEBALLP_PAUSE
DIBUTTON_BASEBALLP_RIGHT_LINK
DIBUTTON_BASEBALLP_WALK


バスケットボール ディフェンス

DIVIRTUAL_SPORTS_BASKETBALL_DEFENSE ジャンルには、バスケットボールの守備動作用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_BBALLD_LATERAL
DIAXIS_BBALLD_MOVE
DIBUTTON_BBALLD_BURST
DIBUTTON_BBALLD_FAKE
DIBUTTON_BBALLD_JUMP
DIBUTTON_BBALLD_MENU
DIBUTTON_BBALLD_PLAY
DIBUTTON_BBALLD_PLAYER
DIBUTTON_BBALLD_SPECIAL
DIBUTTON_BBALLD_STEAL

優先順位 2 のコントロール
DIBUTTON_BBALLD_BACK_LINK
DIBUTTON_BBALLD_DEVICE
DIBUTTON_BBALLD_FORWARD_LINK
DIBUTTON_BBALLD_LEFT_LINK
DIBUTTON_BBALLD_PAUSE
DIBUTTON_BBALLD_RIGHT_LINK
DIBUTTON_BBALLD_SUBSTITUTE
DIBUTTON_BBALLD_TIMEOUT
DIHATSWITCH_BBALLD_GLANCE


バスケットボール オフェンス

DIVIRTUAL_SPORTS_BASKETBALL_OFFENSE ジャンルには、バスケットボールの試合でボールを持つプレーヤー用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_BBALLO_LATERAL
DIAXIS_BBALLO_MOVE
DIBUTTON_BBALLO_BURST
DIBUTTON_BBALLO_CALL
DIBUTTON_BBALLO_DUNK
DIBUTTON_BBALLO_FAKE
DIBUTTON_BBALLO_MENU
DIBUTTON_BBALLO_PASS
DIBUTTON_BBALLO_PLAYER
DIBUTTON_BBALLO_SHOOT
DIBUTTON_BBALLO_SPECIAL

優先順位 2 のコントロール
DIBUTTON_BBALLO_BACK_LINK
DIBUTTON_BBALLO_DEVICE
DIBUTTON_BBALLO_FORWARD_LINK
DIBUTTON_BBALLO_JAB
DIBUTTON_BBALLO_LEFT_LINK
DIBUTTON_BBALLO_PAUSE
DIBUTTON_BBALLO_PLAY
DIBUTTON_BBALLO_POST
DIBUTTON_BBALLO_RIGHT_LINK
DIBUTTON_BBALLO_SCREEN
DIBUTTON_BBALLO_SUBSTITUTE
DIBUTTON_BBALLO_TIMEOUT
DIHATSWITCH_BBALLO_GLANCE


フィッシング

DIVIRTUAL_SPORTS_FISHING ジャンルには、スポーツフィッシング シミュレーション用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_FISHING_LATERAL
DIAXIS_FISHING_MOVE
DIBUTTON_FISHING_BAIT
DIBUTTON_FISHING_BINOCULAR
DIBUTTON_FISHING_CAST
DIBUTTON_FISHING_MAP
DIBUTTON_FISHING_MENU
DIBUTTON_FISHING_TYPE

優先順位 2 のコントロール
DIAXIS_FISHING_ROTATE
DIBUTTON_FISHING_BACK_LINK
DIBUTTON_FISHING_CROUCH
DIBUTTON_FISHING_DEVICE
DIBUTTON_FISHING_DISPLAY
DIBUTTON_FISHING_FORWARD_LINK
DIBUTTON_FISHING_JUMP
DIBUTTON_FISHING_LEFT_LINK
DIBUTTON_FISHING_PAUSE
DIBUTTON_FISHING_RIGHT_LINK
DIBUTTON_FISHING_ROTATE_LEFT_LINK
DIBUTTON_FISHING_ROTATE_RIGHT_LINK
DIHATSWITCH_FISHING_GLANCE


フットボール ディフェンス

DIVIRTUAL_SPORTS_FOOTBALL_DEFENSE ジャンルには、アメリカン フットボールのディフェンス側のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_FOOTBALLD_LATERAL
DIAXIS_FOOTBALLD_MOVE
DIBUTTON_FOOTBALLD_FAKE
DIBUTTON_FOOTBALLD_JUMP
DIBUTTON_FOOTBALLD_MENU
DIBUTTON_FOOTBALLD_PLAY
DIBUTTON_FOOTBALLD_SELECT
DIBUTTON_FOOTBALLD_SUPERTACKLE
DIBUTTON_FOOTBALLD_TACKLE

優先順位 2 のコントロール
DIBUTTON_FOOTBALLD_AUDIBLE
DIBUTTON_FOOTBALLD_BACK_LINK
DIBUTTON_FOOTBALLD_BULLRUSH
DIBUTTON_FOOTBALLD_DEVICE
DIBUTTON_FOOTBALLD_FORWARD_LINK
DIBUTTON_FOOTBALLD_LEFT_LINK
DIBUTTON_FOOTBALLD_PAUSE
DIBUTTON_FOOTBALLD_RIGHT_LINK
DIBUTTON_FOOTBALLD_RIP
DIBUTTON_FOOTBALLD_SPIN
DIBUTTON_FOOTBALLD_SUBSTITUTE
DIBUTTON_FOOTBALLD_SWIM
DIBUTTON_FOOTBALLD_ZOOM


フットボール オフェンス

DIVIRTUAL_SPORTS_FOOTBALL_OFFENSE ジャンルには、アメリカン フットボールのボールキャリア用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_FOOTBALLO_LATERAL
DIAXIS_FOOTBALLO_MOVE
DIBUTTON_FOOTBALLO_JUMP
DIBUTTON_FOOTBALLO_LEFTARM
DIBUTTON_FOOTBALLO_MENU
DIBUTTON_FOOTBALLO_RIGHTARM
DIBUTTON_FOOTBALLO_SPIN
DIBUTTON_FOOTBALLO_THROW

優先順位 2 のコントロール
DIBUTTON_FOOTBALLO_BACK_LINK
DIBUTTON_FOOTBALLO_DEVICE
DIBUTTON_FOOTBALLO_DIVE
DIBUTTON_FOOTBALLO_FORWARD_LINK
DIBUTTON_FOOTBALLO_JUKE
DIBUTTON_FOOTBALLO_LEFT_LINK
DIBUTTON_FOOTBALLO_PAUSE
DIBUTTON_FOOTBALLO_RIGHT_LINK
DIBUTTON_FOOTBALLO_SHOULDER
DIBUTTON_FOOTBALLO_SUBSTITUTE
DIBUTTON_FOOTBALLO_TURBO
DIBUTTON_FOOTBALLO_ZOOM


フットボール プレー

DIVIRTUAL_SPORTS_FOOTBALL_FIELD ジャンルには、アメリカン フットボール用の一般的なコントロールが含まれる。

優先順位 1 のコントロール
DIBUTTON_FOOTBALLP_HELP
DIBUTTON_FOOTBALLP_MENU
DIBUTTON_FOOTBALLP_PLAY
DIBUTTON_FOOTBALLP_SELECT

優先順位 2 のコントロール
DIBUTTON_FOOTBALLP_DEVICE
DIBUTTON_FOOTBALLP_PAUSE


フットボール クォーターバック

DIVIRTUAL_SPORTS_FOOTBALL_QBCK ジャンルには、アメリカン フットボールのクォーターバック用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_FOOTBALLQ_LATERAL
DIAXIS_FOOTBALLQ_MOVE
DIBUTTON_FOOTBALLQ_FAKE
DIBUTTON_FOOTBALLQ_JUMP
DIBUTTON_FOOTBALLQ_MENU
DIBUTTON_FOOTBALLQ_PASS
DIBUTTON_FOOTBALLQ_SELECT
DIBUTTON_FOOTBALLQ_SLIDE
DIBUTTON_FOOTBALLQ_SNAP

優先順位 2 のコントロール
DIBUTTON_FOOTBALLQ_AUDIBLE
DIBUTTON_FOOTBALLQ_BACK_LINK
DIBUTTON_FOOTBALLQ_DEVICE
DIBUTTON_FOOTBALLQ_FAKESNAP
DIBUTTON_FOOTBALLQ_FORWARD_LINK
DIBUTTON_FOOTBALLQ_LEFT_LINK
DIBUTTON_FOOTBALLQ_MOTION
DIBUTTON_FOOTBALLQ_PAUSE
DIBUTTON_FOOTBALLQ_RIGHT_LINK


ゴルフ

DIVIRTUAL_SPORTS_GOLF ジャンルには、ゴルフ用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_GOLF_LATERAL
DIAXIS_GOLF_MOVE
DIBUTTON_GOLF_DOWN
DIBUTTON_GOLF_FLYBY
DIBUTTON_GOLF_MENU
DIBUTTON_GOLF_SELECT
DIBUTTON_GOLF_SWING
DIBUTTON_GOLF_TERRAIN
DIBUTTON_GOLF_UP

優先順位 2 のコントロール
DIBUTTON_GOLF_BACK_LINK
DIBUTTON_GOLF_DEVICE
DIBUTTON_GOLF_FORWARD_LINK
DIBUTTON_GOLF_LEFT_LINK
DIBUTTON_GOLF_PAUSE
DIBUTTON_GOLF_RIGHT_LINK
DIBUTTON_GOLF_SUBSTITUTE
DIBUTTON_GOLF_TIMEOUT
DIBUTTON_GOLF_ZOOM
DIHATSWITCH_GOLF_SCROLL


ホッケー ディフェンス

DIVIRTUAL_SPORTS_HOCKEY_DEFENSE ジャンルには、ホッケーの守備動作用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_HOCKEYD_LATERAL
DIAXIS_HOCKEYD_MOVE
DIBUTTON_HOCKEYD_BLOCK
DIBUTTON_HOCKEYD_BURST
DIBUTTON_HOCKEYD_FAKE
DIBUTTON_HOCKEYD_MENU
DIBUTTON_HOCKEYD_PLAYER
DIBUTTON_HOCKEYD_STEAL

優先順位 2 のコントロール
DIBUTTON_HOCKEYD_BACK_LINK
DIBUTTON_HOCKEYD_DEVICE
DIBUTTON_HOCKEYO_FORWARD_LINK
DIBUTTON_HOCKEYO_LEFT_LINK
DIBUTTON_HOCKEYD_PAUSE
DIBUTTON_HOCKEYO_RIGHT_LINK
DIBUTTON_HOCKEYD_STRATEGY
DIBUTTON_HOCKEYD_SUBSTITUTE
DIBUTTON_HOCKEYD_TIMEOUT
DIBUTTON_HOCKEYD_ZOOM
DIHATSWITCH_HOCKEYD_SCROLL


ホッケー ゴールキーパー

DIVIRTUAL_SPORTS_HOCKEY_GOALIE ジャンルには、ホッケーのゴールキーパー用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_HOCKEYG_LATERAL
DIAXIS_HOCKEYG_MOVE
DIBUTTON_HOCKEYG_BLOCK
DIBUTTON_HOCKEYG_MENU
DIBUTTON_HOCKEYG_PASS
DIBUTTON_HOCKEYG_POKE
DIBUTTON_HOCKEYG_STEAL

優先順位 2 のコントロール
DIBUTTON_HOCKEYG_BACK_LINK
DIBUTTON_HOCKEYG_DEVICE
DIBUTTON_HOCKEYG_FORWARD_LINK
DIBUTTON_HOCKEYG_LEFT_LINK
DIBUTTON_HOCKEYG_PAUSE
DIBUTTON_HOCKEYG_RIGHT_LINK
DIBUTTON_HOCKEYG_STRATEGY
DIBUTTON_HOCKEYG_SUBSTITUTE
DIBUTTON_HOCKEYG_TIMEOUT
DIBUTTON_HOCKEYG_ZOOM
DIHATSWITCH_HOCKEYG_SCROLL


ホッケー オフェンス

DIVIRTUAL_SPORTS_HOCKEY_OFFENSE ジャンルには、ホッケーの攻撃動作用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_HOCKEYO_LATERAL
DIAXIS_HOCKEYO_MOVE
DIBUTTON_HOCKEYO_BURST
DIBUTTON_HOCKEYO_FAKE
DIBUTTON_HOCKEYO_MENU
DIBUTTON_HOCKEYO_PASS
DIBUTTON_HOCKEYO_SHOOT
DIBUTTON_HOCKEYO_SPECIAL

優先順位 2 のコントロール
DIBUTTON_HOCKEYO_BACK_LINK
DIBUTTON_HOCKEYO_DEVICE
DIBUTTON_HOCKEYO_FORWARD_LINK
DIBUTTON_HOCKEYO_LEFT_LINK
DIBUTTON_HOCKEYO_PAUSE
DIBUTTON_HOCKEYO_RIGHT_LINK
DIBUTTON_HOCKEYO_STRATEGY
DIBUTTON_HOCKEYO_SUBSTITUTE
DIBUTTON_HOCKEYO_TIMEOUT
DIBUTTON_HOCKEYO_ZOOM
DIHATSWITCH_HOCKEYO_SCROLL


ハンティング

DIVIRTUAL_SPORTS_HUNTING ジャンルには、ハンティング シミュレーション用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_HUNTING_LATERAL
DIAXIS_HUNTING_MOVE
DIBUTTON_HUNTING_AIM
DIBUTTON_HUNTING_BINOCULAR
DIBUTTON_HUNTING_CALL
DIBUTTON_HUNTING_FIRE
DIBUTTON_HUNTING_MAP
DIBUTTON_HUNTING_MENU
DIBUTTON_HUNTING_SPECIAL
DIBUTTON_HUNTING_WEAPON

優先順位 2 のコントロール
DIAXIS_HUNTING_ROTATE
DIBUTTON_HUNTING_BACK_LINK
DIBUTTON_HUNTING_CROUCH
DIBUTTON_HUNTING_DEVICE
DIBUTTON_HUNTING_DISPLAY
DIBUTTON_HUNTING_FIRESECONDARY
DIBUTTON_HUNTING_FORWARD_LINK
DIBUTTON_HUNTING_JUMP
DIBUTTON_HUNTING_LEFT_LINK
DIBUTTON_HUNTING_PAUSE
DIBUTTON_HUNTING_RIGHT_LINK
DIBUTTON_HUNTING_ROTATE_LEFT_LINK
DIBUTTON_HUNTING_ROTATE_RIGHT_LINK
DIHATSWITCH_HUNTING_GLANCE


マウンテン バイク

DIVIRTUAL_SPORTS_BIKING_MOUNTAIN ジャンルには、マウンテン バイク用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_BIKINGM_PEDAL
DIAXIS_BIKINGM_TURN
DIBUTTON_BIKINGM_CAMERA
DIBUTTON_BIKINGM_JUMP
DIBUTTON_BIKINGM_MENU
DIBUTTON_BIKINGM_SELECT
DIBUTTON_BIKINGM_SPECIAL1
DIBUTTON_BIKINGM_SPECIAL2

優先順位 2 のコントロール
DIAXIS_BIKINGM_BRAKE
DIBUTTON_BIKINGM_BRAKE_BUTTON_LINK
DIBUTTON_BIKINGM_DEVICE
DIBUTTON_BIKINGM_FASTER_LINK
DIBUTTON_BIKINGM_LEFT_LINK
DIBUTTON_BIKINGM_PAUSE
DIBUTTON_BIKINGM_RIGHT_LINK
DIBUTTON_BIKINGM_SLOWER_LINK
DIBUTTON_BIKINGM_ZOOM
DIHATSWITCH_BIKINGM_SCROLL


ラケット

DIVIRTUAL_SPORTS_RACQUET ジャンルには、テニス、卓球、スカッシュなどのラケット ゲーム用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_RACQUET_LATERAL
DIAXIS_RACQUET_MOVE
DIBUTTON_RACQUET_BACKSWING
DIBUTTON_RACQUET_MENU
DIBUTTON_RACQUET_SELECT
DIBUTTON_RACQUET_SMASH
DIBUTTON_RACQUET_SPECIAL
DIBUTTON_RACQUET_SWING

優先順位 2 のコントロール
DIBUTTON_RACQUET_BACK_LINK
DIBUTTON_RACQUET_DEVICE
DIBUTTON_RACQUET_FORWARD_LINK
DIBUTTON_RACQUET_LEFT_LINK
DIBUTTON_RACQUET_PAUSE
DIBUTTON_RACQUET_RIGHT_LINK
DIBUTTON_RACQUET_SUBSTITUTE
DIBUTTON_RACQUET_TIMEOUT
DIHATSWITCH_RACQUET_GLANCE


スキー

DIVIRTUAL_SPORTS_SKIING ジャンルには、スキー用のコントロール、およびスノーボードやスケートボードなど類似スポーツのシミュレーション用コントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_SKIING_SPEED
DIAXIS_SKIING_TURN
DIBUTTON_SKIING_CAMERA
DIBUTTON_SKIING_CROUCH
DIBUTTON_SKIING_JUMP
DIBUTTON_SKIING_MENU
DIBUTTON_SKIING_SELECT
DIBUTTON_SKIING_SPECIAL1
DIBUTTON_SKIING_SPECIAL2

優先順位 2 のコントロール
DIBUTTON_SKIING_DEVICE
DIBUTTON_SKIING_FASTER_LINK
DIBUTTON_SKIING_LEFT_LINK
DIBUTTON_SKIING_PAUSE
DIBUTTON_SKIING_RIGHT_LINK
DIBUTTON_SKIING_SLOWER_LINK
DIBUTTON_SKIING_ZOOM
DIHATSWITCH_SKIING_GLANCE


サッカー ディフェンス

DIVIRTUAL_SPORTS_SOCCER_DEFENSE ジャンルには、サッカーの守備動作用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_SOCCERD_LATERAL
DIAXIS_SOCCERD_MOVE
DIBUTTON_SOCCERD_BLOCK
DIBUTTON_SOCCERD_FAKE
DIBUTTON_SOCCERD_MENU
DIBUTTON_SOCCERD_PLAYER
DIBUTTON_SOCCERD_SELECT
DIBUTTON_SOCCERD_SLIDE
DIBUTTON_SOCCERD_SPECIAL
DIBUTTON_SOCCERD_STEAL

優先順位 2 のコントロール
DIBUTTON_SOCCERD_BACK_LINK
DIBUTTON_SOCCERD_CLEAR
DIBUTTON_SOCCERD_DEVICE
DIBUTTON_SOCCERD_FORWARD_LINK
DIBUTTON_SOCCERD_FOUL
DIBUTTON_SOCCERD_GOALIECHARGE
DIBUTTON_SOCCERD_HEAD
DIBUTTON_SOCCERD_LEFT_LINK
DIBUTTON_SOCCERD_PAUSE
DIBUTTON_SOCCERD_RIGHT_LINK
DIBUTTON_SOCCERD_SUBSTITUTE
DIHATSWITCH_SOCCERD_GLANCE


サッカー オフェンス

DIVIRTUAL_SPORTS_SOCCER_OFFENSE ジャンルには、サッカーの攻撃動作用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_SOCCERO_BEND
DIAXIS_SOCCERO_LATERAL
DIAXIS_SOCCERO_MOVE
DIBUTTON_SOCCERO_FAKE
DIBUTTON_SOCCERO_MENU
DIBUTTON_SOCCERO_PASS
DIBUTTON_SOCCERO_PLAYER
DIBUTTON_SOCCERO_SELECT
DIBUTTON_SOCCERO_SHOOT
DIBUTTON_SOCCERO_SPECIAL1

優先順位 2 のコントロール
DIBUTTON_SOCCERO_BACK_LINK
DIBUTTON_SOCCERO_CONTROL
DIBUTTON_SOCCERO_DEVICE
DIBUTTON_SOCCERO_FORWARD_LINK
DIBUTTON_SOCCERO_HEAD
DIBUTTON_SOCCERO_LEFT_LINK
DIBUTTON_SOCCERO_PASSTHRU
DIBUTTON_SOCCERO_PAUSE
DIBUTTON_SOCCERO_RIGHT_LINK
DIBUTTON_SOCCERO_SHOOTHIGH
DIBUTTON_SOCCERO_SHOOTLOW
DIBUTTON_SOCCERO_SPRINT
DIBUTTON_SOCCERO_SUBSTITUTE
DIHATSWITCH_SOCCERO_GLANCE


ストラテジ ジャンル

次のジャンルには、ストラテジ、ロールプレイング、およびアドベンチャ ゲーム用のコントロールが含まれる。

  • ロールプレイング
  • ターンベース


ロールプレイング

DIVIRTUAL_STRATEGY_ROLEPLAYING ジャンルには、移動、問題解決、および武器や魔法による戦闘を主な活動とするロールプレイング ゲームやアドベンチャ ゲーム用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_STRATEGYR_LATERAL
DIAXIS_STRATEGYR_MOVE
DIBUTTON_STRATEGYR_APPLY
DIBUTTON_STRATEGYR_ATTACK
DIBUTTON_STRATEGYR_CAST
DIBUTTON_STRATEGYR_CROUCH
DIBUTTON_STRATEGYR_GET
DIBUTTON_STRATEGYR_JUMP
DIBUTTON_STRATEGYR_MENU
DIBUTTON_STRATEGYR_SELECT

優先順位 2 のコントロール
DIAXIS_STRATEGYR_ROTATE
DIBUTTON_STRATEGYR_BACK_LINK
DIBUTTON_STRATEGYR_DEVICE
DIBUTTON_STRATEGYR_DISPLAY
DIBUTTON_STRATEGYR_FORWARD_LINK
DIBUTTON_STRATEGYR_LEFT_LINK
DIBUTTON_STRATEGYR_MAP
DIBUTTON_STRATEGYR_PAUSE
DIBUTTON_STRATEGYR_RIGHT_LINK
DIBUTTON_STRATEGYR_ROTATE_LEFT_LINK
DIBUTTON_STRATEGYR_ROTATE_RIGHT_LINK
DIHATSWITCH_STRATEGYR_GLANCE


ターンベース

DIVIRTUAL_STRATEGY_TURN ジャンルには、ターンベースのストラテジ ゲーム用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_STRATEGYT_LATERAL
DIAXIS_STRATEGYT_MOVE
DIBUTTON_STRATEGYT_APPLY
DIBUTTON_STRATEGYT_INSTRUCT
DIBUTTON_STRATEGYT_MENU
DIBUTTON_STRATEGYT_SELECT
DIBUTTON_STRATEGYT_TEAM
DIBUTTON_STRATEGYT_TURN

優先順位 2 のコントロール
DIBUTTON_STRATEGYT_BACK_LINK
DIBUTTON_STRATEGYT_DEVICE
DIBUTTON_STRATEGYT_DISPLAY
DIBUTTON_STRATEGYT_FORWARD_LINK
DIBUTTON_STRATEGYT_LEFT_LINK
DIBUTTON_STRATEGYT_MAP
DIBUTTON_STRATEGYT_PAUSE
DIBUTTON_STRATEGYT_RIGHT_LINK
DIBUTTON_STRATEGYT_ZOOM


キーボード マッピング定数

次の定数は、アクションを物理キーにマップするために、DIACTION 構造体の dwSemantic メンバの中で使用される。

定数 | メモ
DIKEYBOARD_0 | メイン キーボード上
DIKEYBOARD_1 | メイン キーボード上
DIKEYBOARD_2 | メイン キーボード上
DIKEYBOARD_3 | メイン キーボード上
DIKEYBOARD_4 | メイン キーボード上
DIKEYBOARD_5 | メイン キーボード上
DIKEYBOARD_6 | メイン キーボード上
DIKEYBOARD_7 | メイン キーボード上
DIKEYBOARD_8 | メイン キーボード上
DIKEYBOARD_9 | メイン キーボード上
DIKEYBOARD_A |
DIKEYBOARD_ABNT_C1 | ブラジル語キーボードのテンキー上
DIKEYBOARD_ABNT_C2 | ブラジル語キーボードのテンキー上
DIKEYBOARD_ADD | テンキー上のプラス記号 (+)
DIKEYBOARD_APOSTROPHE |
DIKEYBOARD_APPS | アプリケーション キー
DIKEYBOARD_AT | 日本語キーボード上
DIKEYBOARD_AX | 日本語キーボード上
DIKEYBOARD_B |
DIKEYBOARD_BACK | BackSpace
DIKEYBOARD_BACKSLASH |
DIKEYBOARD_C |
DIKEYBOARD_CALCULATOR |
DIKEYBOARD_CAPITAL | Caps Lock
DIKEYBOARD_COLON | 日本語キーボード上
DIKEYBOARD_COMMA |
DIKEYBOARD_CONVERT | 日本語キーボード上
DIKEYBOARD_D |
DIKEYBOARD_DECIMAL | テンキー上のピリオド (小数点)
DIKEYBOARD_DELETE |
DIKEYBOARD_DIVIDE | テンキー上のスラッシュ (/)
DIKEYBOARD_DOWN | 下矢印キー
DIKEYBOARD_E |
DIKEYBOARD_END |
DIKEYBOARD_EQUALS | メイン キーボード上
DIKEYBOARD_ESCAPE |
DIKEYBOARD_F |
DIKEYBOARD_F1 |
DIKEYBOARD_F2 |
DIKEYBOARD_F3 |
DIKEYBOARD_F4 |
DIKEYBOARD_F5 |
DIKEYBOARD_F6 |
DIKEYBOARD_F7 |
DIKEYBOARD_F8 |
DIKEYBOARD_F9 |
DIKEYBOARD_F10 |
DIKEYBOARD_F11 |
DIKEYBOARD_F12 |
DIKEYBOARD_F13 | NEC PC-98 日本語キーボード上
DIKEYBOARD_F14 | NEC PC-98 日本語キーボード上
DIKEYBOARD_F15 | NEC PC-98 日本語キーボード上
DIKEYBOARD_G |
DIKEYBOARD_GRAVE | アクサン グラーブ (`) キー
DIKEYBOARD_H |
DIKEYBOARD_HOME |
DIKEYBOARD_I |
DIKEYBOARD_INSERT |
DIKEYBOARD_J |
DIKEYBOARD_K |
DIKEYBOARD_KANA | 日本語キーボード上
DIKEYBOARD_KANJI | 日本語キーボード上
DIKEYBOARD_L |
DIKEYBOARD_LBRACKET | 左角かっこ [
DIKEYBOARD_LCONTROL | 左 Ctrl キー
DIKEYBOARD_LEFT | 左矢印キー
DIKEYBOARD_LMENU | 左 Alt キー
DIKEYBOARD_LSHIFT | 左 Shift キー
DIKEYBOARD_LWIN | 左 Microsoft® Windows® キー
DIKEYBOARD_M |
DIKEYBOARD_MAIL |
DIKEYBOARD_MEDIASELECT | システムでサポートされているメディア プレーヤーの選択を表示する、メディア選択キー。
DIKEYBOARD_MEDIASTOP |
DIKEYBOARD_MINUS | メイン キーボード上
DIKEYBOARD_MULTIPLY | テンキー上のアスタリスク (*)
DIKEYBOARD_MUTE |
DIKEYBOARD_MYCOMPUTER |
DIKEYBOARD_N |
DIKEYBOARD_NEXT | PageDown キー
DIKEYBOARD_NEXTTRACK | 次のトラック
DIKEYBOARD_NOCONVERT | 日本語キーボード上
DIKEYBOARD_NUMLOCK |
DIKEYBOARD_NUMPAD0 |
DIKEYBOARD_NUMPAD1 |
DIKEYBOARD_NUMPAD2 |
DIKEYBOARD_NUMPAD3 |
DIKEYBOARD_NUMPAD4 |
DIKEYBOARD_NUMPAD5 |
DIKEYBOARD_NUMPAD6 |
DIKEYBOARD_NUMPAD7 |
DIKEYBOARD_NUMPAD8 |
DIKEYBOARD_NUMPAD9 |
DIKEYBOARD_NUMPADCOMMA | NEC PC-98 日本語キーボード テンキー上
DIKEYBOARD_NUMPADENTER |
DIKEYBOARD_NUMPADEQUALS | NEC PC-98 日本語キーボード テンキー上
DIKEYBOARD_O |
DIKEYBOARD_OEM_102 | 英語キーボードおよびドイツ語キーボード上
DIKEYBOARD_P |
DIKEYBOARD_PAUSE |
DIKEYBOARD_PERIOD | メイン キーボード上
DIKEYBOARD_PLAYPAUSE |
DIKEYBOARD_POWER |
DIKEYBOARD_PREVTRACK | 前のトラック、日本語キーボードのサーカムフレックス
DIKEYBOARD_PRIOR | PageUp キー
DIKEYBOARD_Q |
DIKEYBOARD_R |
DIKEYBOARD_RBRACKET | 右角かっこ ]
DIKEYBOARD_RCONTROL | 右 Ctrl キー
DIKEYBOARD_RETURN | メイン キーボード上の Enter キー
DIKEYBOARD_RIGHT | 右矢印キー
DIKEYBOARD_RMENU | 右 Alt キー
DIKEYBOARD_RSHIFT | 右 Shift キー
DIKEYBOARD_RWIN | 右 Windows キー
DIKEYBOARD_S |
DIKEYBOARD_SCROLL | ScrollLock
DIKEYBOARD_SEMICOLON |
DIKEYBOARD_SLASH | メイン キーボード上のスラッシュ (/)
DIKEYBOARD_SLEEP |
DIKEYBOARD_SPACE | スペース キー
DIKEYBOARD_STOP | NEC PC-98 日本語キーボード上
DIKEYBOARD_SUBTRACT | テンキー上のマイナス記号 (-)
DIKEYBOARD_SYSRQ |
DIKEYBOARD_T |
DIKEYBOARD_TAB |
DIKEYBOARD_U |
DIKEYBOARD_UNDERLINE | NEC PC-98 日本語キーボード上
DIKEYBOARD_UNLABELED | 日本語キーボード上
DIKEYBOARD_UP | 上矢印キー
DIKEYBOARD_V |
DIKEYBOARD_VOLUMEDOWN |
DIKEYBOARD_VOLUMEUP |
DIKEYBOARD_W |
DIKEYBOARD_WAKE |
DIKEYBOARD_WEBBACK |
DIKEYBOARD_WEBFAVORITES | Microsoft Internet Explorer の [お気に入り] リスト、Windows の [Favorites] フォルダ、または Netscape のブックマーク リストを表示する。
DIKEYBOARD_WEBFORWARD |
DIKEYBOARD_WEBHOME |
DIKEYBOARD_WEBREFRESH |
DIKEYBOARD_WEBSEARCH |
DIKEYBOARD_WEBSTOP |
DIKEYBOARD_X |
DIKEYBOARD_Y |
DIKEYBOARD_YEN | 日本語キーボード上
DIKEYBOARD_Z |


マウス マッピング定数

次の定数は、アクションをマウスの物理軸やボタンにマップするために、DIACTION 構造体の dwSemantic メンバの中で使用される。

DIMOUSE_BUTTON0
DIMOUSE_BUTTON1
DIMOUSE_BUTTON2
DIMOUSE_BUTTON3
DIMOUSE_BUTTON4
DIMOUSE_BUTTON5
DIMOUSE_BUTTON6
DIMOUSE_BUTTON7
DIMOUSE_WHEEL
DIMOUSE_XAXIS
DIMOUSE_YAXIS
DIMOUSE_XAXISAB
DIMOUSE_YAXISAB

注 : DIMOUSE_XAXISAB と DIMOUSE_YAXISAB は、相対軸データではなく絶対軸データを返すマウスの x 軸と y 軸を表す。


DirectPlay 音声マッピング定数

次の定数は、アクションを Microsoft® DirectPlay® の音声デバイスのチャンネルにマップするために、DIACTION 構造体の dwSemantic メンバの中で使用される。

DIVOICE_CHANNEL1
DIVOICE_CHANNEL2
DIVOICE_CHANNEL3
DIVOICE_CHANNEL4
DIVOICE_CHANNEL5
DIVOICE_CHANNEL6
DIVOICE_CHANNEL7
DIVOICE_CHANNEL8
DIVOICE_ALL
DIVOICE_TEAM
DIVOICE_PLAYBACKMUTE
DIVOICE_RECORDMUTE
DIVOICE_TRANSMIT
DIVOICE_VOICECOMMAND


任意コントロール定数

次の定数は、デバイス上で一致する任意のコントロールにアクションをマップするために、DIACTION 構造体の dwSemantic メンバの中で使用される。

定数 | デバイス オブジェクト
DIAXIS_ANY_1 | 任意の軸
DIAXIS_ANY_2 | 任意の軸
DIAXIS_ANY_3 | 任意の軸
DIAXIS_ANY_4 | 任意の軸
DIAXIS_ANY_A_1 | 任意のアクセル
DIAXIS_ANY_A_2 | 任意のアクセル
DIAXIS_ANY_B_1 | 任意のブレーキ
DIAXIS_ANY_B_2 | 任意のブレーキ
DIAXIS_ANY_C_1 | 任意のクラッチ
DIAXIS_ANY_C_2 | 任意のクラッチ
DIAXIS_ANY_R_1 | 任意の r 軸
DIAXIS_ANY_R_2 | 任意の r 軸
DIAXIS_ANY_S_1 | 任意の s 軸
DIAXIS_ANY_S_2 | 任意の s 軸
DIAXIS_ANY_U_1 | 任意の u 軸
DIAXIS_ANY_U_2 | 任意の u 軸
DIAXIS_ANY_V_1 | 任意の v 軸
DIAXIS_ANY_V_2 | 任意の v 軸
DIAXIS_ANY_X_1 | 任意の x 軸
DIAXIS_ANY_X_2 | 任意の x 軸
DIAXIS_ANY_Y_1 | 任意の y 軸
DIAXIS_ANY_Y_2 | 任意の y 軸
DIAXIS_ANY_Z_1 | 任意の z 軸
DIAXIS_ANY_Z_2 | 任意の z 軸
DIBUTTON_ANY(x) | 任意のボタン
DIPOV_ANY_1 | 任意の視点コントローラ
DIPOV_ANY_2 | 任意の視点コントローラ
DIPOV_ANY_3 | 任意の視点コントローラ
DIPOV_ANY_4 | 任意の視点コントローラ

これらの定数を使って、特定のジャンルに定義されていない仮想コントロールに、アプリケーション アクションをマップすることができる。このようなアクションは、ジャンル固有アクションの後にマップされる。マッパーがすべての一致するコントロールをジャンル固有アクションに既にマップしていた場合、任意コントロール アクションは、マップされないまま残される。

任意コントロール アクションに優先度の差はない。デバイスに 1 つの x 軸があり、アクション配列が DIAXIS_ANY_1 および DIAXIS_ANY_X_1 を指定する場合、x 軸には、アクション配列の先頭に表示されるアクションがマップされる。

DIBUTTON_ANY(x) は 0 ～ 255 までの任意の値を受け取ることができる。ただし、一度指定したインデックスを 2 回以上使用しないこと。たとえば、次の DIACTION 構造体のセットは無効である。

{eB_MUTE,    DIBUTTON_ANY(0), 0, "Toggle Sound",},
{eB_VOLUP,   DIBUTTON_ANY(0), 0, "Volume Up",   },
{eB_VOLDOWN, DIBUTTON_ANY(0), 0, "Volume Down", },

次に示すようにそれぞれ異なるインデックスを使用するのが正しい使い方である。

{eB_MUTE,    DIBUTTON_ANY(0), 0, "Toggle Sound",}
{eB_VOLUP,   DIBUTTON_ANY(1), 0, "Volume Up",   }
{eB_VOLDOWN, DIBUTTON_ANY(2), 0, "Volume Down", }


戻り値

以下は、Microsoft® DirectInput® メソッドと機能によって返される HRESULT 値の一覧である。エラーは負の値によって示され、結合することができない。

それぞれのメソッドまたは機能はエラー値を返すことができるが、詳細についてはそれぞれの説明を参照すること。本文中のエラー コードの一覧は、必然的に不完全になっている。たとえば、どんな DirectInput メソッドも DIERR_OUTOFMEMORY を返すことができるが、本文中では、このエラー コードはそのメソッドの戻り値としては明示されていない。

DI_BUFFEROVERFLOW
デバイス バッファがオーバーフローし、一部の入力が失われた。この値は、標準の COM 戻り値である S_FALSE に等しい。
DI_DOWNLOADSKIPPED
エフェクトのパラメータの更新は成功したが、このエフェクトに関連するデバイスが排他モードで取得されていないので、このエフェクトをダウンロードできない。
DI_EFFECTRESTARTED
エフェクトを停止し、そのパラメータの更新を行い、その後このエフェクトを再開した。
DI_NOEFFECT
この操作にエフェクトはない。この値は、標準の COM 戻り値である S_FALSE に等しい。
DI_NOTATTACHED
デバイスは存在するが現在はアタッチ状態にない。この値は、標準の COM 戻り値である S_FALSE に等しい。
DI_OK
操作は、完全に終了した。この値は、標準の COM 戻り値である S_OK に等しい。
DI_POLLEDDEVICE
デバイスは、ポーリング対象デバイスである。その結果、デバイス バッファリングでは、データは一切収集されず、イベントは、IDirectInputDevice8::Poll メソッドが呼び出されるまで通知されない。
DI_PROPNOEFFECT
デバイス プロパティの変更は効果がなかった。この値は、標準の COM 戻り値である S_FALSE に等しい。
DI_SETTINGSNOTSAVED
アクション マップはデバイスに適用されたが、設定情報は保存されなかった。
DI_TRUNCATED
エフェクトのパラメータの更新は成功したが、パラメータのうちデバイスの能力を超えているものがあり、それらは直近のサポート値に丸められた。
DI_TRUNCATEDANDRESTARTED
DI_EFFECTRESTARTED | DI_TRUNCATED に等しい。
DI_WRITEPROTECT
設定が変更できないことを示す成功コード。
DIERR_ACQUIRED
操作は、デバイスが取得状態の間は実行できない。
DIERR_ALREADYINITIALIZED
このオブジェクトは初期化済みである。
DIERR_BADDRIVERVER
オブジェクトは、互換性のないドライバ バージョン、あるいは不適格または不完全なドライバ コンポーネントであるために作成できなかった。
DIERR_BETADIRECTINPUTVERSION
アプリケーションは、DirectInput のサポートされていないリリース前のバージョン用に作成されたものである。
DIERR_DEVICEFULL
デバイスはフルである。
DIERR_DEVICENOTREG
デバイスまたはデバイスインスタンスが DirectInput に登録されていない。この値は、標準の COM 戻り値である REGDB_E_CLASSNOTREG に等しい。
DIERR_EFFECTPLAYING
パラメータは、メモリ内では更新されたが、デバイスにはダウンロードされなかった。デバイスが再生中のエフェクトの更新をサポートしていないためである。
DIERR_GENERIC
DirectInput サブシステムで 原因不明のエラーが発生した。この値は、標準の COM 戻り値である E_FAIL に等しい。
DIERR_HANDLEEXISTS
デバイスは、既に、自身にイベント通知の関連付けをしている。この値は、標準の COM 戻り値である E_ACCESSDENIED に等しい。
DIERR_HASEFFECTS
デバイスは、エフェクトがアタッチされているために再初期化できない。
DIERR_INCOMPLETEEFFECT
必須情報がないので、エフェクトをダウンロードできなかった。たとえば、エフェクトに関連する軸がなかったり、タイプ固有情報が与えられていない場合。
DIERR_INPUTLOST
入力デバイスのアクセス権を失った。再取得しなければならない。
DIERR_INVALIDPARAM
無効なパラメータが戻ってくる関数に渡されたか、オブジェクトがその関数を呼び出せる状態になかった。この値は、標準の COM 戻り値である E_INVALIDARG に等しい。
DIERR_MAPFILEFAIL
ベンダーが提供するデバイスのアクション マッピング ファイルの読み込み中か、あるいはデバイスのユーザー構成マッピング ファイルの読み込みまたは書き込み中にエラーが発生したことを示す。
DIERR_MOREDATA
要求情報の一部がバッファに納まらなかった。
DIERR_NOAGGREGATION
オブジェクトは、集合化をサポートしない。
DIERR_NOINTERFACE
オブジェクトは、指定されたインターフェイスをサポートしていない。この値は、標準の COM 戻り値である E_NOINTERFACE に等しい。
DIERR_NOTACQUIRED
操作は、デバイスが取得されない限り実行できない。
DIERR_NOTBUFFERED
デバイスは、バッファリングされていない。バッファリングを有効にするには DIPROP_BUFFERSIZE プロパティを設定する。
DIERR_NOTDOWNLOADED
エフェクトがダウンロードされていない。
DIERR_NOTEXCLUSIVEACQUIRED
操作は、デバイスが DISCL_EXCLUSIVE モードで取得されていなければ実行できない。
DIERR_NOTFOUND
要求されたオブジェクトは存在しない。
DIERR_NOTINITIALIZED
このオブジェクトは、初期化されていなかった。
DIERR_OBJECTNOTFOUND
要求されたオブジェクトは存在しない。
DIERR_OLDDIRECTINPUTVERSION
アプリケーションは、より新しいバージョンの DirectInput を必要とする。
DIERR_OTHERAPPHASPRIO
ほかのアプリケーションの優先レベルの方が高いので、この呼び出しの実行がうまくいかない。この値は、標準の COM 戻り値である E_ACCESSDENIED に等しい。このエラーは、アプリケーションのデバイスに対するアクセス権が、フォアグラウンドアクセス権であるにもかかわらず、バックグラウンドにいるときに、デバイスを取得しようとした場合に返される。
DIERR_OUTOFMEMORY
DirectInput サブシステムが呼び出しを完了するのに十分なメモリを割り当てることができなかった。この値は、標準の COM 戻り値である E_OUTOFMEMORY に等しい。
DIERR_READONLY
指定のプロパティは変更できない。この値は、標準の COM 戻り値である E_ACCESSDENIED に等しい。
DIERR_REPORTFULL
送られる情報の方が、デバイスに送ることができる情報よりも多い。
DIERR_UNPLUGGED
この操作は、デバイスが接続されていない可能性を示す。
DIERR_UNSUPPORTED
この関数呼び出しは、この時点ではサポートされない。この値は、標準の COM 戻り値である E_NOTIMPL に等しい。
E_HANDLE
このパラメータは、このプロセスに関係する有効な最上位のウィンドウ ハンドルでなければならない。
E_PENDING
データは、まだ使用不可である。
E_POINTER
無効なポインタ (通常は NULL) がパラメータとして渡された。


DirectPlay

Microsoft® DirectPlay® アプリケーション プログラミング インターフェイス (API) は、Microsoft DirectX® のコンポーネントであり、マルチプレーヤー ゲームなどのネットワーク アプリケーションの記述を可能にする。

DirectPlay は、DirectX のほかのコンポーネントと同じように、C、C++、および Microsoft Visual Basic® で使用できる。

DirectPlay ヘルプ全体の構成については、「ロードマップ」を参照すること。


ロードマップ

Microsoft® DirectPlay® に関する情報は、次のように構成されている。

DirectPlay の新機能。Microsoft DirectX® 8 でのこのコンポーネントの新しい機能。以前 DirectPlay を使用したことがある場合は、この項目を最初に読むこと。この技術は DirectX 7 以降に完全に再設計された。

DirectPlay の概要。DirectPlay とは何か、アプリケーションにとってどのように役立つかについて概要を示し、主要なオブジェクトとネットワーク アプリケーションを作成するために必要な手順を簡単に説明する。

DirectPlay について。基になるメカニズムを詳細に解説する。DirectPlay セッションの実装方法については説明しないが、実装の詳細を扱う時点でアプリケーション プログラミング インターフェイス (API) を理解するのに役立つ。

DirectPlay の使い方。API の使用に関する手引き。この項目にある目次で全体を把握し、具体的な情報が必要になったときに各部分を参照できる。リファレンス情報と共に使用すること。

DirectPlay C++ サンプル。SDK の C/C++ サンプル アプリケーションのガイド。

DirectPlay C/C++ リファレンス。DirectPlay C++ API の詳細情報。


DirectPlay の新機能

Microsoft® DirectX® のネットワーク コンポーネントは大きく変更された。Microsoft DirectPlay® には、新しいインターフェイス セットが導入され、ハードウェアへの直接アクセスがこれまで以上に可能になり、パフォーマンスが向上した。

DirectPlay の主な新機能を次に示す。

インターフェイスが完全に書き換えられた。
ピアツーピア セッションとクライアント/サーバー セッションを作成するインターフェイスを分離することにより、複雑なネットワーク アプリケーションの作成が容易になった。DirectPlay トランスポート セッションの作成に使用するインターフェイスを次に示す。これらのインターフェイスは Dplay8.h ヘッダー ファイルに定義されている。
IDirectPlay8Peer
ピアツーピア セッションを作成するメソッドを提供する。
IDirectPlay8Client
クライアント/サーバー アプリケーションのクライアント部分を作成するメソッドを提供する。
IDirectPlay8Server
クライアント/サーバー アプリケーションのサーバー部分を作成するメソッドを提供する。
ロビーが DirectPlay の残りの部分から切り離された。
ロビー クライアントは DirectPlay アプリケーションと共に実行する必要がなくなった。ロビー サービス プロバイダまたはアプリケーションは、相手を考慮することなく、DirectPlay を実装できるようになった。ロビーの実装は、Dplobby8.h ヘッダー ファイルに定義された、次の 2 つの簡易インターフェイスに分割された。
IDirectPlay8LobbyClient
このインターフェイスは、ロビー クライアントの管理、およびロビー対応アプリケーションの列挙と起動に使用する。
IDirectPlay8LobbiedApplication
このインターフェイスを使用し、ロビー起動可能なアプリケーションをシステムに登録し、アプリケーションをロビー起動できるようにする。また、このインターフェイスを使用すると、ロビーから接続情報を取得し、ユーザーに問い合わせずにゲームを起動することもできる。
音声転送が追加された。
DirectPlay Voice は、アプリケーションにリアルタイムの音声通信を追加する一連のインターフェイスを提供する。次のインターフェイスが Dvoice.h ヘッダー ファイルに定義されている。
IDirectPlayVoiceClient
DirectPlay Voice セッションでクライアントを作成し、管理するメソッドを提供する。
IDirectPlayVoiceServer
DirectPlay Voice セッションをホストし、管理するメソッドを提供する。
IDirectPlayVoiceTest
DirectPlay Voice のオーディオ構成のテストに使用する。
アドレス情報が GUID ベースのデータから URL ベースのデータ形式に移行された。
DirectPlay の以前のバージョンでは、実装しにくく、人間には読み取り不可能な GUID アドレスを使ったバイナリ データを使用していた。DirectX 8.0 の DirectPlay では、URL 形式のアドレス表記が導入された。Dpaddr.h に定義されている一連のインターフェイスを使用し、新しいアドレス フォーマットを作成し、操作できる。
IDirectPlay8Address
DirectPlay アドレスの作成と操作に使用する汎用アドレッシング メソッドを提供する。
IDirectPlay8AddressIP
IP プロバイダ固有のアドレッシング サービスを提供する。
さらに高い拡張性と改善されたメモリ管理が追加された。
利用者側の帯域幅の増加は、ネットワーク ゲームの設計と実装に大きな影響を与えた。DirectPlay では、スレッド プール管理が向上したため、開発者はスケーラブルでより堅牢であり、多数のマルチプレーヤー オンライン アプリケーションをサポートできるアプリケーションを簡単に作成できるようになった。
ファイアウォールのサポートが強化され、ネットワーク アドレス トランスレータが追加された。
ネットワーク アドレス トランスレータ (NAT)、ファイアウォール、およびそのほかのインターネット接続共有 (ICS) 方法を通過するネットワーク ゲームの作成は困難なことがある。特に、非保証 (UDP) トラフィックの場合、困難である。DirectPlay 8.0 ではこのような問題が考慮されているため、可能な限り NAT ソリューションがサポートされている。DirectPlay 8 の TCP/IP サービス プロバイダでは、ゲーム データ用として単一の UDP ポートを使用し、開発者はそのポートを選択できる。したがって、ファイアウォールや NAT を適切に構成できる。また、DirectPlay は UDP を利用し、クライアント/サーバー ゲームにおいて、一部の NAT が対象とするクライアントが構成を追加せずにゲームに接続できるようにする。


DirectPlay の概要

Microsoft® DirectPlay® API は、ゲームやチャット クライアントなどマルチプレーヤー アプリケーションを開発するためのツールを開発者に提供する。わかりやすくするため、このマニュアルでは、このようなアプリケーションをすべて「ゲーム」と呼ぶ。マルチプレーヤー アプリケーションには、2 つの基本的特徴がある。

  • 各自のコンピュータ上にゲーム クライアントを持つ複数の個人ユーザーがいる。
  • ユーザーのコンピュータを相互接続するための (おそらく中央サーバー経由の) ネットワーク リンクがある。

DirectPlay は、基本となるネットワークからアプリケーションを大きく隔離するレイヤを提供する。大部分の用途では、アプリケーションは単に DirectPlay API を使用し、DirectPlay がネットワーク通信の詳細を処理できるようにする。DirectPlay は、マルチプレーヤー アプリケーションのさまざまな面の実装プロセスを容易にするため、以下のような多くの機能を提供する。

  • ピアツーピア セッションとクライアント/サーバー セッションの両方を作成し管理する。
  • セッション内のユーザーとグループを管理する。
  • ネットワーク リンクやネットワーク条件が異なるセッション メンバ間でのメッセージングを管理する。
  • アプリケーションとロビーとの対話を可能にする。
  • ユーザー相互の音声通信を可能にする。

このドキュメントは、DirectPlay の能力の高度な概要を解説する。以下のトピックでは、マルチプレーヤー ゲームでの DirectPlay の使用方法の詳細を説明する。

  • セッションの作成と管理
  • DirectPlay ネットワーク通信
  • DirectPlay オブジェクトとの通信
  • DirectPlay ロビー サポート
  • DirectPlay 音声通信


セッションの作成と管理

ゲームのセッションとは、特定のマルチプレーヤー ゲームの 1 つのインスタンスである。1 つのセッションには同時にプレイする複数のユーザーがあり、それぞれが自分のコンピュータ上にゲーム クライアントを持っている。プレーヤーとは、ゲームの中のエンティティであり、各ゲームによって定義される。各ユーザーが、1 つのゲームに 1 人以上のプレーヤーを持つ場合もある。ただし、ゲーム アプリケーションは、個別の Microsoft® DirectPlay® インターフェイスまたは各プレーヤーのオブジェクトを使用して、これらのプレーヤーをアプリケーション自身で管理しなければならない。

セッション作成の最初の手順は、ユーザー グループの収集である。2 つの基本的方法がある。

  • 多くのゲーム セッションは、リモート コンピュータで実行されているロビー アプリケーションによってアレンジされている。この方法は、多くのインターネット ベースのゲームで使用されている。
  • また、各ユーザーのコンピュータを相互に通信させてゲームをアレンジすることもできる。この方法は、一般的に、参加するユーザー グループがすべて同じ LAN 上に存在するような場合に限定される。

セッションがアレンジされると、ゲームが起動し、ゲームプレーが開始される。セッションが進むにつれて、プレーヤーがセッションから消えたり、新しいプレーヤーが追加されたりする。詳細は個々のゲームによって異なる。

マルチプレーヤー ゲームでは、各ユーザーの UI は、セッション内のほかのすべてのユーザーの UI と同期することができる。したがって、マルチプレーヤー セッションの管理には、ユーザー間での継続的なメッセージのストリームが必要となる。たとえば、プレーヤーが移動するたびにメッセージが送信され、セッション内のほかのすべてのゲーム クライアント上でのそのプレーヤーの位置が更新される。DirectPlay の重要部分は、セッション内のすべてのコンピュータ間での効率的かつ柔軟なメッセージ送信をサポートする API 部分である。

セッションでのメッセージ送信のトポロジ構築には、主に 2 つの方法がある。ピアツーピアとクライアント/サーバーである。どちらのトポロジにも利点と制約があるため、どちらが自分のゲームに適しているかを評価する必要がある。

ここでは説明するトピックは、次のとおりである。

  • ピアツーピア トポロジ
  • クライアント/サーバー トポロジ


ピアツーピア トポロジ

ピアツーピアのゲームは、ネットワーク リンクで接続された各プレーヤーのコンピュータによって構成される。4 人のプレーヤーによるピアツーピア ゲームのトポロジを図解すると、次のようになる。

ゲームプレイは、各ユーザーのゲーム クライアントをほかのユーザーのクライアントと直接通信させることによって処理される。たとえば、あるユーザーが移動したとき、ゲーム クライアントは、ほかのユーザーのコンピュータ 1 台に対して 1 つずつ、合計 3 つの更新メッセージを送信しなければならない。

ピアツーピア ゲームは、ユーザーのコンピュータ上に常駐するロビー クライアント アプリケーションによってアレンジされ、起動するのが普通である。ロビー クライアントがセッションをアレンジする場合、以下のような 2 つの基本的な方法がある。

  • ロビー クライアントがほかの潜在的ユーザーのロビー クライアントと直接通信する。この方法は、たとえば同じ LAN サブネット上のユーザーにゲームをアレンジする場合に使用できる。
  • ロビー クライアントが、リモート コンピュータ上で実行されているロビー サーバー アプリケーションへのリンクとして機能する。インターネット ベースのゲームは普通はこの方法でアレンジされている。

セッションがアレンジされ起動すると、メッセージ送信の大部分またはすべてがユーザー間のメッセージになる。ロビー サーバーが関与している場合、このサーバーは、プレーヤーがゲームから離れたときにセッション メンバのリストを更新したり、新しいユーザーがセッションへの参加を要求できるようにするだけである。処理が必要ない場合は、サーバーはバックグラウンドにとどまり、一般的には送信されているメッセージもほとんど認識することはない。

サーバーは、存在しないか、少なくともゲーム プレイには直接かかわっていないため、1 人のユーザーがゲームのホストに指定される。ホストは、進行中のセッションへの新しいプレーヤーの参加など、論理的な詳細を処理する。

ピアツーピア ゲームの利点は、その単純さである。必要なものは、ゲーム クライアントを備えたプレーヤーの集団と、セッションを整理する方法のみである。ピアツーピア トポロジの最大の弱点は、スケーラビリティにある。ユーザー数が増加すると、それに比例してゲーム プレイを処理するために必要なメッセージ数も増加する。参加できるユーザーの最大数は、ゲームやネットワークの帯域幅にもよるが、一般的には 20 ～ 30 人以内である。


クライアント/サーバー トポロジ

クライアント/サーバー ゲームは、中央のサーバー コンピュータに接続された各プレーヤーのコンピュータによって構成される。4 人のプレーヤーによるクライアント/サーバー ゲームのトポロジを図解すると、次のようになる。

ゲームプレイは、各ユーザーのゲーム クライアントをサーバーと通信させることによって処理される。サーバーは、責任を持って、ほかのユーザーに情報を渡す。たとえば、あるユーザーが移動すると、メッセージがサーバーに送信される。するとサーバーは、ほかのプレーヤーにメッセージを送信して、ゲームの状態の変更を知らせる。サーバーには、いくつかの役割を割り当てることができる。

  • セッションのメッセージ送信ハブとして機能する。各コンピュータは、サーバーにメッセージを送信するだけでよい。サーバーは、ほかのすべてのユーザーを同期させるためのロジスティクスを処理する。この方法では、特に大きなゲームの場合、メッセージのトラフィックを大幅に削減することができる。
  • ゲームのホストとなる。サーバーは通常、ピアツーピアでセッション ホストが処理しなければならなかったタスクを引き受ける。
  • ゲームのいろいろな面をサポートする。サーバーは、多くの場合、ゲームのロジスティクスをサポートする以上の仕事を行う。多くのゲーム、特に大きなゲームでは、「ゲーム世界」を維持するための処理はほとんどサーバー上で実行される。ゲーム クライアントの主な仕事は、ユーザーの UI を処理することである。

普通、クライアント/サーバー ゲームは、ユーザーのコンピュータ上に常駐するロビー クライアント アプリケーションによってアレンジされ、起動する。ロビー クライアントは、ゲームをホストしているコンピュータと同じリモート コンピュータ上で実行されているロビー サーバー アプリケーションへのリンクとして機能する。ゲームが起動すると、ゲーム サーバー アプリケーションがホストとなり、新しいユーザーへの参加許可などのタスクを処理する。

クライアント/サーバー ゲームには、いくつかの利点がある。

  • 特に大規模なゲームでは、効率性が高い。特に、プレーヤーが増えてもメッセージ送信トラフィックの回線が増えるだけなので、ピアツーピアよりスケール的に優れている。大量のデータを扱うマルチプレーヤー ゲームには、クライアント/サーバー トポロジが必要である。
  • ユーザーのコンピュータの処理能力による制限を受けない。大きくて複雑な「ゲーム世界」を維持するため必要な処理の多くを 1 台の強力なコンピュータ上に配置し、ユーザーのコンピュータには UI を処理させることができる。
  • ゲームの重要な部分を中央のサイトで制御できる。たとえば、サーバー アプリケーションを変更するだけで、ゲームを更新したりバグを修正でき、多数のゲーム クライアントを更新する必要がない。

ただし、ピアツーピア ゲームは開発して出荷すれば実質上仕事が終わる。ゲーム クライアントはほとんど自己完結型である。クライアント/サーバー ゲームでは、通常のサポート サービスを提供する以外に、ユーザーに対してゲームの進行中もかかわることになる。また、ゲーム サーバー コンピュータや関連ソフトウェアと共に、すべてのメッセージ送信を処理するためのネットワーク リンクを、アプリケーションの製品寿命が続く限り、提供し、維持しなければならない。大量のデータを使用するマルチプレーヤー ゲームの場合、ほとんど、またはまったく休みなくサーバーを運用する必要があり、ユーザーのゲームプレイを中断するとユーザーを怒らせるというリスクもある。


DirectPlay ネットワーク通信

Microsoft® DirectPlay® の最大の機能は、ユーザーに、アプリケーションを基本となるネットワーク ハードウェアおよびソフトウェアから大きく隔離し、効率的で柔軟なメッセージング サポートを提供することである。状態更新を送信する必要がある場合、使用しているネットワークの種類に関係なく、ただ対応する DirectPlay API を呼び出せばよい。DirectPlay ネットワーク サービス プロバイダは、TCP/IP、IPX、モデム、シリアル リンクによる通信をサポートする。

ここでは説明するトピックは、次のとおりである。

  • DirectPlay トランスポート プロトコル
  • DirectPlay アドレス

注

DirectPlay はセキュリティによる通信はサポートしていない。

Microsoft Windows® 95 システムでモデムを使用するには、Telephony API (TAPI) のバージョン 2.0 をインストールする必要がある。TAPI 2.0 は http://www.microsoft.com/ からダウンロードできる。


DirectPlay トランスポート プロトコル

Microsoft® DirectPlay® ネットワーキング能力の中心は、DirectPlay プロトコルである。このトランスポート レイヤ プロトコルは、DirectPlay 8 用に完全にオーバーホールされ、すべてのメッセージングに使用されている。DirectPlay プロトコルは、送信中に何が起こっているかを心配する必要なく、送信側アプリケーションからターゲット アプリケーションへのデータ送信を簡単にすることに焦点を置いている。このプロトコルは、マルチプレーヤー ゲームの必要性に応じて調整された、次のような機能を提供する。

  • 信頼性の高いメッセージ配信と信頼性の低いメッセージ配信。信頼性の高いメッセージは、ターゲット アプリケーションがメッセージを受け取るまで再送信される。配信のタイプは、メッセージごとに割り当てることができる。
  • シーケンシャル メッセージ配信と非シーケンシャル メッセージ配信。シーケンシャル メッセージは、送信された順にターゲット アプリケーションに渡される。
  • メッセージの分割と再構築。メッセージ サイズがネットワークの容量を超える場合、DirectPlay は自動的にメッセージを分割して再構築する。
  • 混雑の制御。DirectPlay は、処理中のメッセージをターゲットが処理できるレベルに自動的に抑制する。この機能によって、ターゲットに処理できないほど大量のメッセージが送信されないようにする。
  • 送信の優先順位付け。重要なメッセージほど早く送信するために、DirectPlay では、メッセージに低、標準、高の優先度を割り当てることができる。優先度の高いメッセージが出力キューの正面に送信され、その後、標準優先度、優先度の低いメッセージが送信される。
  • メッセージのタイムアウト。現在処理中のメッセージ キューが、新しいメッセージによって押しやられた古いメッセージで滞ることがないように、DirectPlay では、すべてのメッセージにタイムアウト値を割り当てることができる。メッセージがタイムアウトすると、そのメッセージは、送信済みかどうかに関係なく、処理中のメッセージ キューから削除される。


DirectPlay アドレス

メッセージを配信するには、マルチプレーヤー ゲームの各参加者が一意のアドレスを持っている必要がある。アドレスは、アプリケーションを実行しているコンピュータを参照するか (デバイス アドレス)、アプリケーションが通信する必要のあるコンピュータを参照できる (ホスト アドレス)。

Microsoft® DirectPlay® アドレスは、URL 文字列の形態をとる。これらの文字列は、次に示す一般形式のスキーム、スキーム セパレータ、およびデータ文字列で構成される。

x-directplay:/[data string]

データ文字列にはいくつかの要素が含まれている。これらの要素は、発信者とターゲットが各種ネットワーク リンクを介して通信を行うために必要なものをすべて指定する。

使用にあたっては、URL 文字列は DirectPlay API メソッドとやり取りされる DirectPlay アドレス オブジェクトに埋め込まれる。URL 文字列を直接操作するか、またはアドレス オブジェクトによって公開されるメソッドを使って、データ文字列の各要素を個別に処理できる。


DirectPlay オブジェクトとの通信

Microsoft® DirectPlay® は、本質的には COM オブジェクトの 1 つのコレクションで構成されている。各オブジェクトは、DirectPlay のいろいろな面を制御するための 1 つ以上のインターフェイスを公開する。たとえば、DirectPlay ピア オブジェクト (CLSID_DirectPlay8Peer) は、ピアツーピア ゲームの管理に使用される。

DirectPlay オブジェクトと通信するには、オブジェクトのインターフェイスが公開するメソッドを呼び出す。たとえば、ピアツーピア ゲームで別のユーザーに何らかのデータを送信するには、IDirectPlay8Peer::SendTo メソッドを呼び出してメッセージを送信する。そして DirectPlay によって、ターゲットにメッセージが届けられる。

DirectPlay は、1 つまたは複数のコールバック関数を介してユーザーのアプリケーションと通信する。これらの関数は原則として、使い慣れた Window プロシージャと類似している。アプリケーションはコールバック関数を実装し、初期化時に、関数へのポインタを DirectPlay に渡す。DirectPlay がアプリケーションと通信する必要があるときは、コールバック関数を呼び出して、情報の 2 つの主要項目に渡す。

  • メッセージの型を識別するメッセージ ID。
  • 必要な詳細を提供するデータ ブロックへのポインタ、一般には構造体。

たとえば、上記の例で送信されたメッセージがターゲットに到着すると、ターゲット アプリケーションのコールバック関数は、メッセージが別のユーザーから送られたことを示す、DPNMSGID_RECEIVE メッセージ ID の付いたメッセージを受け取る。付随する構造体にはデータが格納されている。

DirectPlay メッセージングの多くはマルチスレッドで実行されるため、コールバック関数は正しく実装することが重要である。


DirectPlay ロビー サポート

ロビーは、プレーヤーがゲームに出会ったりアレンジできるようにすることを主目的とするアプリケーションである。ロビーは普通リモート コンピュータ上にあり、インターネットを介してアクセスされる。またロビー サーバーは、チャット ルームのホスティング、ニュースや情報のポスティング、商品の販売など、いろいろな機能も実行する。ロビー サーバーは便利な機能であり、マルチプレーヤー ゲームのアレンジに一般的に使用されるが、必須条件ではない。またマルチプレーヤー ゲームは、ロビー クライアントどうしの直接通信によってアレンジすることもできる。

普通、ゲームがロビーと対話できるようにするためには、3 つのコンポーネントが必要である。

  • ロビー サーバー
  • ロビー クライアント
  • ロビー対応ゲーム

Microsoft® DirectPlay® は、ロビー サーバー アプリケーションの実装方法は指定しない。代わりに、DirectPlay はロビー クライアントのサポートを提供する。ロビー クライアントは、ロビー サーバー ベンダーによって実装され、各ユーザーのシステムにインストールされるアプリケーションである。これは、ユーザーとロビーのリンクとして有用である。このような通信を直接処理することもできるが、そのためには自分のゲームを起動するすべてのロビーの実装の詳細を知っていなければならない。

ロビー クライアント アプリケーションは、適切なプロトコルを使用して、関連するロビー サーバーとの通信の詳細を処理する。ロビー クライアントは、DirectPlay インターフェイスによってユーザーやユーザーのゲーム アプリケーションと通信する。そのとき、DirectPlay はアプリケーションにメッセージを渡す。またアプリケーションは、DirectPlay インターフェイスを使ってロビー クライアントにメッセージを渡すことができる。

ロビーは、実質的にどんなアプリケーションでも起動できる。ただし、アプリケーションがロビー起動の利点をフル活用するには、いくつかの特定のロビー アウェア コンポーネントを持っている必要がある。特に、ロビー対応アプリケーションは、セッション全体を通してロビー クライアントと通信することができる。アプリケーションがロビー対応として登録されている場合、ロビー クライアントは、ホストの移行など、ゲーム状態のいろいろな変更に対する更新も自動的に受け取る。


DirectPlay 音声通信

現在の傾向はチーム ベースのマルチプレーヤー ゲームであるため、プレーヤー同士の通信がゲームプレーの不可欠な部分となっている。歴史的にプレーヤー同士の通信はテキスト ベースに制約されてきた。プレーヤーはチームメイト宛てのメッセージをキーボードから入力していた。テキストベースの通信は、スピードの遅いターンベースのゲームには適しているものの、リアルタイム ゲームでは不便でしかない。キーボード入力の遅いプレーヤーがゲームで不利になるばかりでなく、ゲームが創出しようとしているリアリティが著しく妨げられる。この問題の明白な解決策は、通信手段として音声を使用することである。この解決策は、トレーニングの必要がなく、ゲーム自体への集中を高める。

Windows プラットフォームでは、ビデオ ゲーム開発者向けに、リアルタイム音声会議の実装に必要なすべてのツールが用意されているが、ゲーム開発者の側に多大な労力が要求される。このことは、極端に帯域幅の少ない状況に対応できる圧縮技術の権利を取得する費用と困難さと共に、ゲームにおける音声使用の広がりを妨げてきた。

Microsoft® DirectPlay® 8.0 は、ゲーム開発者に、最小限の労力で使用できる堅牢なリアルタイム音声会議システムを提供する。


DirectPlay について

Microsoft® DirectPlay® ドキュメントのこのセクションでは、アプリケーションでの DirectPlay API の使い方を理解するために必要な基本的背景について説明する。

  • ピアツーピア セッション
  • クライアント/サーバー セッション
  • DirectPlay のロビー
  • ネットワーキングの基本
  • DirectPlay コールバック関数とマルチスレッドに関する問題
  • DirectPlay Voice について


ピアツーピア セッション

ピアツーピア セッションは、ネットワークで接続されたユーザーの集合から構成される。ゲームの準備と起動にはロビー サーバーを使用することがあるが、ゲームの実行に必要なメッセージングはユーザー間で直接やり取りする。ロビー サーバーとの通信は、参加者リストの更新といった限られた目的にのみ使用する。

ピアツーピアのゲームでは、ゲームの実行に必要なことがすべてクライアント ソフトウェアに属する。サーバーが関係しないため、ゲーム全体を作成し、維持するために必要な処理は、すべてクライアント アプリケーションで行わなければならない。このドキュメントでは、Microsoft® DirectPlay® によるロビー可能なピアツーピア ゲームの基本的原理を説明する。ピアツーピア アプリケーションの簡単な実例については、SDK 付属の SimplePeer アプリケーションを参照すること。

  • ピアツーピア セッションの開始
  • ピアツーピア セッションに使用するサービス プロバイダの選択
  • ピアツーピア セッションに使用するホストの選択
  • ピアツーピア セッションへの接続
  • ピアツーピア セッションの管理
  • ホストの移行
  • ピアツーピア ゲームの通常のプレー
  • ピアツーピア セッションからの離脱
  • ピアツーピア セッションの終了


ピアツーピア セッションの開始

ピアツーピア ゲームは、ユーザーが直接起動することも、ユーザーのコンピュータに常駐する "ロビー クライアント" アプリケーションから "ロビー起動" することもできる。このドキュメントでは、ロビー クライアントと通信できるロビー可能なゲームを想定して説明する。

実行すべき最初のステップの 1 つは、ゲームがロビー起動で起動されているかどうかを判断することである。これには、ロビー対象アプリケーション オブジェクト (CLSID_DirectPlay8LobbiedApplication) を作成し、初期化する。このとき、ロビー対象アプリケーションのコールバック メッセージ ハンドラへのポインタを、オブジェクトに渡す。このメッセージ ハンドラは、ロビー対象オブジェクトからは直接、ロビー クライアントおよびロビーからは間接的に、メッセージを受信する。

  • アプリケーションがロビー起動で起動されていれば、IDirectPlay8LobbiedApplication::Initialize メソッドがロビー クライアントへの接続ハンドルを返し、ロビー対象アプリケーションのメッセージ ハンドラに DPL_MSGID_CONNECT メッセージが送信される。関連する構造体の pdplConnectionSettings メンバは、セッション メンバのアドレス オブジェクトなどの接続情報が入った DPL_CONNECTION_SETTINGS 構造体を指す。
  • アプリケーションがロビー起動で起動されていなければ、接続ハンドルもメッセージも届かない。ただし、IDirectPlay8LobbiedApplication::SetAppAvailable を呼び出すと、ロビー クライアントが、ロビー対象アプリケーションのメッセージ ハンドラに DPL_MSGID_CONNECT メッセージを送信することにより、実行中のアプリケーションをセッションに後から接続することができる。

また、ピア オブジェクト (CLSID_DirectPlay8Peer) を作成し、初期化する必要もある。このオブジェクトが、Microsoft® DirectPlay® およびセッション内の残りメンバとの主な通信手段となる。セッションに複数のプレーヤーを参加させるためには、プレーヤーごとにこのオブジェクトのインスタンスを作成する必要がある。


ピアツーピア セッションに使用するサービス プロバイダの選択

この場合、使用中のネットワーク接続がサービス プロバイダとなる。TCP/IP またはモデムのサービス プロバイダを使用するゲームが多いが、Microsoft® DirectPlay® はシリアル接続と IPX 接続にも対応している。

ユーザーがロビー クライアントでセッションに接続されている場合には、DPL_MSGID_CONNECT メッセージに付属する DPL_CONNECTION_SETTINGS 構造体を調べれば、適切なサービス プロバイダを判断できる。それ以外の場合、使用するサービス プロバイダを判断するには、ユーザーに照会するなどの方法をとる必要がある。ピア オブジェクトの IDirectPlay8Peer::EnumServiceProviders メソッドを使用すると、利用可能なサービス プロバイダを列挙できる。詳細については、｢DirectPlay 列挙の使い方｣を参照すること。

サービス プロバイダを選択すると、ユーザーの DirectPlay アドレス オブジェクト (デバイス アドレス) を作成できるようになる。DirectPlay の多くのメソッドでは、このアドレスを使ってデバイスを識別する。DirectPlay アドレスとアドレス オブジェクトの詳細については、｢DirectPlay アドレシング｣を参照すること。


ピアツーピア セッションに使用するホストの選択

ピアツーピア ゲームには、個々のユーザーが直接やり取りして処理できる要素も多いが、単独のオーナーが担当すべき作業もある。これらの作業は、ゲーム ホストが行う。セッションに加わるには、セッション ホストのアドレスを知っている必要がある。通常、ホストの選択はロビー サーバーを通じて行う。この場合、ユーザーのアプリケーションがセッションに接続されると、DPL_MSGID_CONNECT メッセージと共に接続設定が届き、その接続設定にホストのアドレス オブジェクトが含まれている。セッション ホストを調べるには、以下の処理を実行する。

  • 返された DPL_CONNECTION_SETTINGS 構造体の dwFlags メンバを調べる。このメンバが DPLCONNECTSETTINGS_HOST に設定されている場合は、使用中のシステムがホストである。
  • DPLCONNECTSETTINGS_HOST フラグが設定されていない場合は、pdp8HostAddress メンバからホストのアドレスを取得できる。

また、自分がセッション ホストであることを公表して、(たとえば LAN サブネット上で) ある要素を全要素にコピーするセッションを作成することもできる。これには、IDirectPlay8Peer::SetPeerInfo を呼び出してプレーヤー名を設定してから、IDirectPlay8Peer::Host を呼び出して自分がホストの候補であることを公表する。ゲームの構成は、IDirectPlay8Peer::Host の pdnAppDesc のパラメータで渡す DPN_APPLICATION_DESC 構造体に値を割り当てて指定する。

利用可能なセッションとホストをユーザーに知らせるには、IDirectPlay8Peer::EnumHosts を呼び出せば、利用可能なホストを列挙できる。ユーザーがセッションを選択すると、接続を要求できるようになる。


ピアツーピア セッションへの接続

セッション ホストでない限り、プレーヤーをセッションに接続する必要がある。これには、セッション ホストのアドレスが必要になる。アプリケーションがロビー クライアントから接続されている場合は、IDirectPlay8LobbiedApplication::GetConnectionSettings を呼び出せば、ホストのアドレスを取得できる。ホストのアドレスは、利用可能なホストを列挙して取得することもできる。列挙から返される情報には、各ホストのアドレスと、関連するセッションを記述する DPN_APPLICATION_DESC 構造体が含まれる。

セッションへの参加を要求するには、IDirectPlay8Peer::SetPeerInfo を呼び出してプレーヤー名を設定してから、選択されたホストのアドレスを指定して IDirectPlay8Peer::Connect を呼び出すことによりセッションに接続する。

プレーヤーがセッションへの参加を試みると、ホストに DPN_MSGID_INDICATE_CONNECT メッセージが届く。プレーヤーの参加を許可する場合は、S_OK を返す。要求を拒否する場合は、それ以外の値を返す。どちらの場合も、プレーヤーには応答が入った DPN_MSGID_CONNECT_COMPLETE メッセージが届く。ホストが接続を受け付けた場合は、関連する構造体の hResultCode メンバが S_OK に設定される。拒否した場合は、hResultCode が DPNERR_HOSTREJECTEDCONNECTION に設定される。

DPN_MSGID_INDICATE_CONNECT メッセージが届いたら、ホストはプレーヤー コンテキスト値を定義できる。ただし、プレーヤー ID はまだ定義されない。プレーヤー コンテキスト値は、プレーヤー ID が入った DPN_MSGID_CREATE_PLAYER メッセージを受信してからでも定義できる。一般のプレーヤーに DPN_MSGID_INDICATE_CONNECT メッセージが届くことはない。

新しいプレーヤーが接続されると、ホストを含むセッション メンバ全員に、新しいプレーヤーを公表する DPN_MSGID_CREATE_PLAYER メッセージが届く。メッセージに関連付けられた構造体には、プレーヤーへのメッセージ送信に使用するプレーヤー ID が格納されている。ホスト以外のピアでは、このメッセージを処理するときに、プレーヤー コンテキスト値を定義する必要がある。ピアまたはホストがこのメッセージの処理から復帰すると、そのプレーヤー コンテキスト値がセッション用に設定され、変更できなくなる。プレーヤー コンテキスト値の詳細については、｢プレーヤー コンテキスト値の使い方｣を参照すること。


ピアツーピア セッションの管理

セッション ホストでは、以下のようなセッション管理を行わなければならない。

  • セッション メンバとそのネットワーク アドレスのリストを管理する。
  • 新しいユーザーのセッション参加を許すかどうかを判断する。
  • 新しいユーザーがセッションに加わったら、メンバ全員に通知し、新しいユーザーのアドレスを渡す。
  • 新しいユーザーに現在のゲームの状態を提供する。
  • ユーザーがセッションを抜けたら、ユーザー全員に通知する。

プレーヤーがセッションへの参加を試みると、ホストに DPN_MSGID_INDICATE_CONNECT メッセージが届く。プレーヤーの参加を許可する場合は、S_OK を返す。要求を拒否する場合は、それ以外の値を返す。どちらの場合も、プレーヤーには応答が入った DPN_MSGID_CONNECT_COMPLETE メッセージが届く。

ホストはプレーヤーをセッションから削除できる。これには、IDirectPlay8Peer::DestroyPeer を呼び出す。ホスト以外のメンバは、このメソッドを呼び出すと失敗する。プレーヤーがほかのプレーヤーをセッションから削除するには、Microsoft® DirectPlay® の通常のメッセージングで要求をホストに送信し、ホスト側で処理させる必要がある。


ホストの移行

ホストは、セッションの初期メンバでなければならないが、セッションの終了前に抜けてもよい。ホストがセッションを抜けると、以下のどちらかの結果になる。

  • セッションが終了する。
  • ホストが "移行" して別のユーザーがホストになる。

ホストが移行可能かどうかはセッションによって異なる。ホストの移行を有効にするには、ゲームのセットアップ時に、セッションの主催者が DPN_APPLICATION_DESC 構造体の dwFlags メンバに DPNSESSION_MIGRATE_HOST フラグを設定する必要がある。このフラグが設定されていない場合は、ホストが抜けるとセッションが終了する。

DPNSESSION_MIGRATE_HOST フラグが設定されていても、ホストは IDirectPlay8Peer::TerminateSession を呼び出してセッションを強制終了できる。

DPNSESSION_MIGRATE_HOST フラグが設定されている場合には、ホストがセッションを抜けると、Microsoft® DirectPlay® が新しいセッション ホストを選択する。残りのセッション メンバ全員に、新しいホストの ID が含まれる DPN_MSGID_HOST_MIGRATE メッセージが届く。


ピアツーピア ゲームの通常のプレー

Microsoft® DirectPlay® のメッセージは、基本的には、セッション内のメンバに送信されるゲーム関連のデータ ブロックである。DirectPlay は、データ ブロックの内容や形式を限定せずに、ユーザーどうしがデータをやり取りするためのメカニズムのみを提供する。ゲームの進行中には、通常、各セッション メンバから残りのセッション メンバ全員に対して、メッセージが間断なく送信される。これらのメッセージの主な目的は、各ユーザーのアプリケーションに同じ UI を表示するために、ゲームの状態の同期をとることにある。ただし、メッセージは、これに限らずゲーム固有の多様な目的に使用できる。

ゲーム (特に変化の速いゲーム) では、メッセージングを慎重に管理しなければならない場合が多い。DirectPlay は、流出するメッセージを、ターゲットが処理できるレベルに減速 (スロットリング) する。重要なメッセージを確実に届けるため、メッセージをあまり高速で送信しないように注意しなければならない。DirectPlay での効率的なメッセージング処理については、｢ネットワーキングの基本｣を参照すること。

ほかのセッション メンバにメッセージを送信するには、IDirectPlay8Peer::SendTo を呼び出す。そのメンバに、データが付いた DPN_MSGID_RECEIVE メッセージが届く。特定のプレーヤーにメッセージを送信するには、関連する DPN_MSGID_CREATE_PLAYER メッセージと共に受け取ったプレーヤー ID を、dpnid パラメータに設定する。また、dpnid を DPNID_ALL_PLAYERS_GROUP に設定すれば、セッション内のプレーヤー全員にメッセージを送信できる。プレーヤーのグループを定義すると、SendTo を 1 回呼び出すだけで、グループのメンバ全員にメッセージを送信できる。

注 ほかのユーザーに情報を送信するには、IDirectPlay8Peer::SetPeerInfo メソッドを使用してもよい。それらのユーザーに、その情報が付いた DPN_MSGID_PEER_INFO メッセージが届く。ただし、この送信方法はあまり効率的でないので、通常のメッセージングでは使用しないこと。

グループの使用

多くのゲームは、プレーヤーをグループ分けできるようになっている。たとえば戦略型ゲームでは、通常、プレーヤーを複数のグループに分け、グループ単位で指示を出すことができる。Microsoft® DirectPlay® でも、プレーヤーのグループを編成できる。DirectPlay のグループは、基本的にはメッセージングを簡略化する手段である。グループを定義すると、IDirectPlay8Peer::SendTo を 1 回呼び出すだけで、グループ メンバ全員にメッセージを送信できるようになる。DirectPlay のグループは、通常はゲームで定義されるグループに対応するが、グループ作成の目的が限定されているわけではない。

DirectPlay のグループを作成するには、IDirectPlay8Peer::CreateGroup を呼び出す。この結果、セッション メンバ全員に、詳細が付いた DPN_MSGID_CREATE_GROUP メッセージが届く。このメッセージには、グループにメッセージを送信するために使用するグループ ID が含まれる。

グループを作成したら、次に IDirectPlay8Peer::AddPlayerToGroup を呼び出してプレーヤーを追加する。この結果、セッション メンバに、新しくプレーヤーが追加されたグループの ID が付いた DPN_MSGID_ADD_PLAYER_TO_GROUP メッセージが届く。

グループを確立すると、そのグループにデータを送信できるようになる。これには、dpnid パラメータにグループ ID を設定して IDirectPlay8Peer::SendTo を呼び出す。この結果、グループ メンバ全員に、データが付いた DPN_MSGID_RECEIVE メッセージが届く。

グループからプレーヤーを削除するには、IDirectPlay8Peer::RemovePlayerFromGroup を呼び出す。セッション メンバに、プレーヤーの ID が付いた DPN_MSGID_DESTROY_PLAYER メッセージが届く。

最後に、グループを使い終わったら、IDirectPlay8Peer::DestroyGroup を呼び出せば破棄できる。この結果、セッション メンバ全員に、グループ ID が付いたDPN_MSGID_DESTROY_GROUP メッセージが届く。


ピアツーピア セッションからの離脱

セッションを抜けるには、IDirectPlay8Peer::Close を呼び出して接続を終了する。セッション メンバに、DPN_MSGID_DESTROY_PLAYER メッセージが通知される。

セッション ホスト自身がセッションを抜けると、セッションも終了する。ただし、セッションがホストの移行を許すように構成されている場合は例外である。詳細については、｢ホストの移行｣を参照すること。


ピアツーピア セッションの終了

使い終わったセッションは、ホストが IDirectPlay8Peer::TerminateSession を呼び出して終了しなければならない。このメソッドは、ホストの移行が有効になっていても、ホスト移行をせずにセッションを終了する。セッション メンバ全員に、DPN_MSGID_TERMINATE_SESSION メッセージが通知される。この後、必要なクリーンアップがあれば実行する。別のセッションを開始するには、IDirectPlay8Peer::Close を呼び出してから IDirectPlay8Peer::Initialize を呼び出す必要がある。

IDirectPlay8LobbiedApplication::SetAppAvailable の呼び出しにより、アプリケーションが接続可能であると登録されている場合には、ロビー クライアントは、ロビー対象アプリケーションのメッセージ ハンドラに DPL_MSGID_CONNECT メッセージを送信して、実行中のアプリケーションと新しいセッションの接続を試みることができる。この場合はまず、IDirectPlay8Peer::Close を呼び出してから IDirectPlay8Peer::Initialize を呼び出しておく必要がある。


クライアント/サーバー セッション

クライアント/サーバー セッションは、中心となるサーバーと、それに接続されたプレーヤー (つまりクライアント) の集合から構成される。Microsoft® DirectPlay® に関する限り、クライアントの情報はサーバーだけが把握し、クライアントがほかのクライアントについて知ることはない。ゲームの実行に必要なメッセージは、各クライアントとサーバーの間でやり取りされる。ピアツーピア セッションの場合と異なり、クライアント間で直接にメッセージングを行うことはできない。

クライアント/サーバー セッションでは、以下の 2 つのまったく異質なアプリケーションが必要になる。

  • リモート サーバーで動作するサーバー アプリケーション。最低限でも、中心となるメッセージング ハブおよびゲーム ホストとしての機能を持つ。サーバーは、クライアントから流入するすべてのメッセージを受信して処理し、適切なメッセージを返信する必要がある。クライアントから別のクライアントへのデータ転送は、すべてサーバー アプリケーション側で処理する必要がある。
  • 各プレーヤーのコンピュータで動作するクライアント アプリケーション。このアプリケーションの主な機能は、UI を処理し、サーバーとの間でプレーヤーのゲームの状態の同期をとることである。

セッションの一部の要素は、これらのアプリケーションの一方でしか処理できない。たとえば、プレーヤーのビデオ表示の更新は、クライアント アプリケーションでなければ実行できない。しかし、ゲーム全体を維持するために必要な処理の多くの要素は、少なくとも原則的には、どちらのアプリケーションでも実行できる。効率的なクライアント/サーバー ゲームを作成するには、個々の処理を 2 つのアプリケーションにどのように振り分けるかを、慎重に判断する必要がある。

このドキュメントでは、クライアント/サーバー ゲームの基本的な原理と、クライアント/サーバー アプリケーションの実装方法の概要を説明する。

  • クライアント/サーバー セッションの開始
  • クライアント用サービス プロバイダの選択
  • クライアント/サーバー ホストの選択
  • クライアント/サーバー セッションへの接続
  • クライアント/サーバー セッションの管理
  • クライアント/サーバー ゲームの通常のプレー
  • クライアント/サーバー セッションからの離脱
  • クライアント/サーバー セッションの終了


クライアント/サーバー セッションの開始

クライアント/サーバー ゲームは、ロビーを通じて起動することも、サーバー アプリケーションから直接起動することもできる。

サーバー アプリケーション

クライアント/サーバー ゲームは、ロビーを通じて準備されることが多い。サーバーを起動する最も直接的な方法は、サーバーを "ロビー可能" アプリケーションとして実装することである。このアプローチでは、サーバーを起動する手段が提供され、セッション進行中にサーバーとロビーが通信を行うことができる。詳細については、｢DirectPlay のロビー｣を参照すること。

サーバーを直接起動してから、そのサーバーが利用可能であることを公表し、クライアントからの接続を待つこともできる。詳細については、｢クライアント/サーバー ホストの選択｣を参照すること。

サーバー アプリケーションは、起動されたら、IDirectPlay8Server::Initialize を呼び出してアプリケーション自体を初期化しなければならない。類似する Microsoft® DirectPlay® のほかのメソッドと同様、初期化の主な目的は、DirectPlay にコールバック メッセージ ハンドラへのポインタを提供することにある。また、IDirectPlay8Server::SetServerInfo を呼び出して現在のゲームの記述も行わなければならない。このメソッドが呼び出されていないと、クライアントがサーバーに接続できない。

クライアント アプリケーション

実行すべき最初のステップの 1 つは、ゲームがロビー起動で起動されているかどうかを判断することである。これには、ロビー対象アプリケーション オブジェクト (CLSID_DirectPlay8LobbiedApplication) を作成し、初期化する。このとき、ロビー対象アプリケーションのコールバック メッセージ ハンドラへのポインタを、オブジェクトに渡す。このメッセージ ハンドラは、ロビー対象オブジェクトからは直接、ロビー クライアントおよびロビーからは間接的に、メッセージを受信する。

  • アプリケーションがロビー起動で起動されていれば、IDirectPlay8LobbiedApplication::Initialize メソッドがロビー クライアントへの接続ハンドルを返し、ロビー対象アプリケーションのメッセージ ハンドラに DPL_MSGID_CONNECT メッセージが送信される。関連する構造体の pdplConnectionSettings メンバは、サーバーのアドレス オブジェクトなどの接続情報が入った DPL_CONNECTION_SETTINGS 構造体を指す。
  • アプリケーションがロビー起動で起動されていなければ、接続ハンドルもメッセージも届かない。ただし、IDirectPlay8LobbiedApplication::SetAppAvailable を呼び出すと、ロビー クライアントが、ロビー対象アプリケーションのメッセージ ハンドラに DPL_MSGID_CONNECT メッセージを送信することにより、実行中のアプリケーションをセッションに後から接続することができる。

また、クライアント オブジェクト (CLSID_DirectPlay8Client) を作成し、初期化する必要もある。このオブジェクトが、Microsoft® DirectPlay® およびサーバーとの主な通信手段となる。セッションに複数のプレーヤーを参加させるためには、プレーヤーごとにこのオブジェクトのインスタンスを作成する必要がある。


クライアント用サービス プロバイダの選択

この場合、使用中のネットワーク接続がサービス プロバイダとなる。TCP/IP またはモデムのサービス プロバイダを使用するゲームが多いが、Microsoft® DirectPlay® はシリアル接続と IPX 接続にも対応している。

ユーザーがロビー クライアントでセッションに接続されている場合には、DPL_MSGID_CONNECT メッセージに付属する DPL_CONNECTION_SETTINGS 構造体を調べれば、適切なサービス プロバイダを判断できる。それ以外の場合、使用するサービス プロバイダを判断するには、ユーザーに照会するなどの方法をとる必要がある。クライアント オブジェクトの IDirectPlay8Client::EnumServiceProviders メソッドを使用すると、利用可能なサービス プロバイダを列挙できる。詳細については、｢DirectPlay 列挙の使い方｣を参照すること。

サービス プロバイダを選択すると、ユーザーの DirectPlay アドレス オブジェクト (デバイス アドレス) を作成できるようになる。DirectPlay の多くのメソッドでは、このアドレスを使ってデバイスを識別する。DirectPlay アドレスとアドレス オブジェクトの詳細については、｢DirectPlay アドレシング｣を参照すること。


クライアント/サーバー ホストの選択

セッションのホストは、当然、サーバー アプリケーションが担当する。セッションに加わるには、クライアント アプリケーションでホスト サーバーのアドレスを判断する必要がある。通常、ホストの選択はロビー サーバーを通じて行う。この場合、ユーザーのアプリケーションがセッションに接続されると、DPL_MSGID_CONNECT メッセージと共に接続設定が届き、その接続設定にホストのアドレス オブジェクトが含まれている。関連する構造体の pdp8HostAddress メンバは、ホストのアドレスが入ったアドレス オブジェクトを指す。

また、IP または IPX サービス プロバイダを使用しているサーバーでは、そのサーバーがセッション ホストであることを公表して、(たとえば LAN サブネット上で) "ある要素を全要素にコピーするセッション" を作成することもできる。ある要素を全要素にコピーするセッションを作成するには、IDirectPlay8Server::SetServerInfo を呼び出してサーバー情報を設定する。次に IDirectPlay8Server::Host を呼び出して、セッション自体がセッション ホストであることを公表する。ゲームの構成は、IDirectPlay8Server::Host の pdnAppDesc のパラメータで渡す DPN_APPLICATION_DESC 構造体に値を割り当てて指定する。

利用可能なセッションとホストをユーザーに知らせるには、クライアント アプリケーションで IDirectPlay8Client::EnumHosts を呼び出せば、利用可能なホストを照会できる。ユーザーがホストを選択すると、接続を要求できるようになる。


クライアント/サーバー セッションへの接続

すべてのクライアントは、ホストに接続して明示的にセッションに加わる必要がある。このことは、ロビーを通じて準備されたセッションでも同じである。接続により、クライアントがセッションのメンバになり、クライアントとの通信に必要な情報がホストに提供される。ホストでは、接続要求を受け付けることも拒否することもできる。

サーバー アプリケーション

クライアントがセッションへの参加を試みると、ホストに DPN_MSGID_INDICATE_CONNECT メッセージが届く。プレーヤーの参加を許可する場合は、S_OK を返す。要求を拒否する場合は、それ以外の値を返す。どちらの場合も、クライアントには応答が入った DPN_MSGID_CONNECT_COMPLETE メッセージが届く。ここでプレーヤー コンテキスト値を定義してもよいし、DPN_MSGID_CREATE_PLAYER メッセージが届くまで待ってもよい。プレーヤー コンテキスト値の詳細については、｢プレーヤー コンテキスト値の使い方｣を参照すること。

プレーヤーがセッションへの接続に成功すると、全クライアントとサーバーに、新しいプレーヤーの ID (DPNID) が付いた DPN_MSGID_CREATE_PLAYER メッセージが届く。プレーヤー コンテキスト値を定義する必要があり、それがまだ済んでいない場合には、メッセージ ハンドラがこのメッセージの処理から復帰するまでに、定義しなければならない。復帰すると、プレーヤー コンテキスト値を変更できなくなる。

クライアント アプリケーション

セッションに接続するには、セッション ホストのアドレスが必要になる。アプリケーションがロビー クライアントから接続されている場合は、IDirectPlay8LobbiedApplication::GetConnectionSettings を呼び出せば、ホストのアドレスを取得できる。

セッション ホストのアドレスがわからない場合、IP または IPX サービス プロバイダを使用しているなら、IDirectPlay8Client::EnumHosts を呼び出して利用可能なホストを列挙すれば、ある要素を全要素にコピーするセッションを調べることができる。ホストのアドレスは、利用可能なホストを列挙して取得することもできる。列挙から返される情報には、各ホストのアドレス、ホストとの通信に使用するデバイス、および関連付けられたセッションを記述する DPN_APPLICATION_DESC 構造体が含まれる。

セッションへの参加を要求するには、IDirectPlay8Client::SetClientInfo を呼び出してプレーヤー名を設定してから、選択されたホストのアドレスを指定して IDirectPlay8Client::Connect を呼び出すことによりセッションに接続する。

メッセージ ハンドラに、ホストの応答が付いた DPN_MSGID_CONNECT_COMPLETE メッセージが届く。ホストが接続を受け付けた場合は、関連する構造体の hResultCode メンバが S_OK に設定される。拒否した場合は、hResultCode が DPNERR_HOSTREJECTEDCONNECTION に設定される。


クライアント/サーバー セッションの管理

ホストとして、サーバーにはセッションの進行を管理する義務がある。詳細はアプリケーションの設計によって異なるが、セッション ホストが少なくとも以下の作業を行わなければならないことは共通である。

  • セッション メンバとそのネットワーク アドレスのリストを管理する。この作業の一部は Microsoft® DirectPlay® で行われるが、サーバー アプリケーションで管理しなければならないプレーヤー データは、通常、DirectPlay から提供されるデータだけではない。
  • 新しいユーザーのセッション参加を許すかどうかを判断する。
  • 新しいユーザーに現在のゲームの状態を提供する。

プレーヤーがセッションへの参加を試みると、ホストに DPN_MSGID_INDICATE_CONNECT メッセージが届く。プレーヤーの参加を許可する場合は、S_OK を返す。接続要求を拒否する場合は、それ以外の値を返す。どちらの場合も、プレーヤーには応答が入った DPN_MSGID_CONNECT_COMPLETE メッセージが届く。

ホストはプレーヤーをセッションから削除できる。これには、IDirectPlay8Server::DestroyClient を呼び出す。


クライアント/サーバー ゲームの通常のプレー

Microsoft® DirectPlay® のメッセージは、基本的には、クライアントとサーバーの間でやり取りされるゲーム関連のデータ ブロックである。DirectPlay は、データ ブロックの内容や形式を限定せずに、データをやり取りするためのメカニズムのみを提供する。ゲームの進行中には、通常、各クライアントとサーバーの間で、メッセージが間断なくやり取りされる。これらのメッセージの主な目的は、各ユーザーのアプリケーションに同じ UI を表示するために、ゲームの状態の同期をとることにある。ただし、メッセージは、これに限らずゲーム固有の多様な目的に使用できる。

ゲーム (特に変化の速いゲーム) では、メッセージングを慎重に管理しなければならない場合が多い。DirectPlay は、流出するメッセージを、ターゲットが処理できるレベルに減速 (スロットリング) する。重要なメッセージを確実に届けるため、メッセージをあまり高速で送信しないように注意しなければならない。DirectPlay での効率的なメッセージング処理については、｢ネットワーキングの基本｣を参照すること。

サーバー アプリケーション

クライアントにメッセージを送信するには、IDirectPlay8Server::SendTo を呼び出す。クライアントに、データが付いた DPN_MSGID_RECEIVE メッセージが届く。

クライアント アプリケーション

サーバーにメッセージを送信するには、IDirectPlay8Client::Send を呼び出す。サーバーに、データが付いた DPN_MSGID_RECEIVE メッセージが届く。

注 DirectPlay にはクライアント間の通信メカニズムはなく、クライアントとサーバーの間の通信メカニズムだけが用意されている。クライアント間の通信は、すべてサーバー アプリケーションで実装する必要がある。

グループの使用

多くのゲームは、プレーヤーをグループ分けできるようになっている。たとえば、チーム対戦型ゲームでは、チームのプレーヤー全員を 1 つのグループのメンバにしてもよい。DirectPlay では、クライアント/サーバー ゲームのサーバーが、プレーヤーのグループを作成できる。DirectPlay のグループは、通常はゲームで定義されるグループに対応するが、グループ作成の目的が限定されているわけではない。DirectPlay のグループは、基本的にはメッセージングを簡略化する手段である。グループを定義すると、IDirectPlay8Server::SendTo を 1 回呼び出すだけで、グループ メンバ全員にメッセージを送信できるようになる。

DirectPlay のグループを作成するには、IDirectPlay8Server::CreateGroup を呼び出す。この結果、メッセージ ハンドラに、詳細が付いた DPN_MSGID_CREATE_GROUP メッセージが届く。このメッセージには、グループにメッセージを送信するために使用するグループ ID が含まれる。グループを作成したら、次に IDirectPlay8Server::AddPlayerToGroup を呼び出してプレーヤーを追加する。

グループを確立すると、そのグループにデータを送信できるようになる。これには、dpnid パラメータにグループ ID を設定して IDirectPlay8Server::SendTo を呼び出す。この結果、グループ メンバ全員に、データが付いた DPN_MSGID_RECEIVE メッセージが届く。

グループからプレーヤーを削除するには、IDirectPlay8Server::RemovePlayerFromGroup を呼び出す。最後に、グループを使い終わったら、IDirectPlay8Server::DestroyGroup を呼び出せば破棄できる。


クライアント/サーバー セッションからの離脱

クライアントがセッションを抜けるには、IDirectPlay8Client::Close を呼び出す。この結果、サーバーに DPN_MSGID_DESTROY_PLAYER メッセージが通知される。


クライアント/サーバー セッションの終了

クライアント/サーバー セッションを終了するには、サーバーが IDirectPlay8Server::Close を呼び出す。クライアント/サーバー セッションの場合、ホストは移行しないので、このメソッドによりすべての接続が終了し、セッション自体が終了する。DPN_MSGID_TERMINATE_SESSION メッセージにより、クライアントにセッション終了が通知される。

次に、サーバー自体を含む各プレーヤーへの DPN_MSGID_DESTROY_PLAYER メッセージがサーバーに届く。IDirectPlay8Server::Close は、同期メソッドであり、DPN_MSGID_DESTROY_PLAYER メッセージがすべて処理されるまで復帰しない。IDirectPlay8Server::Close から復帰すると、サーバー アプリケーションを安全にシャットダウンできるようになる。

サーバーがセッションを閉じるとき、すべての接続されているプレーヤから DPN_MSGID_DESTROY_PLAYER を受け取る。サーバーは接続を解除していることを知っているので、これは通常の振る舞いであり、構成された構造体の dwReason メンバには DPNDESTROYPLAYERREASON_NORMAL が設定される。DPNDESTROYPLAYERREASON_SESSIONTERMINATED 値は予期せぬ接続解除の場合にのみ設定される。


DirectPlay のロビー

ロビーとは、ユーザーがマルチプレーヤー ゲームを準備できるようにすることを主な目的とするアプリケーションである。ロビーは、通常、リモート サーバー上で動作するアプリケーションである。ユーザーは、(主にインターネット経由で) ロビーにアクセスし、ゲーム セッションを設定するか、またはだれかが開始したセッションに加わる。この結果、ロビー アプリケーションがグループの各ゲーム アプリケーションを起動し、ゲームが始まる。

マルチプレーヤー ゲームの多くはロビーを通じて準備されるので、Microsoft® DirectPlay® ベースのゲームの多くは、ロビー アプリケーションと対話できなければならない。逆に、多くのロビーは DirectPlay ベースのゲームをサポートする必要があるので、ロビー アプリケーションはゲーム アプリケーションと対話できなければならない。このドキュメントでは、Microsoft DirectX® のゲームがロビーと対話できるようにする方法 (およびロビーが Microsoft DirectX® のゲームと対話できるようにする方法) を説明する。

  • DirectPlay のロビー アーキテクチャ
  • ロビー サーバー
  • ロビー クライアント
  • ロビー可能アプリケーション


DirectPlay のロビー アーキテクチャ

Microsoft® DirectPlay® に基づくマルチプレーヤー ゲームのセッションを準備し、管理するプロセスには、独立した 5 つの構成要素が関係している。ロビー サーバー アプリケーションは、通常、リモート サーバーに常駐し、インターネットを通じてアクセスされるサードパーティ アプリケーションである。残りの 4 つの構成要素は、各プレーヤーのコンピュータにインストールされる。

  • ロビー クライアント。ロビー クライアントは、ロビー サーバーと通信するサードパーティ アプリケーションである。ロビー クライアントは、DirectPlay ロビー クライアント オブジェクトを通じて、ユーザーのゲーム アプリケーションとも通信する。
  • ロビー可能ゲーム アプリケーション。ロビー可能ゲーム アプリケーションは、DirectPlay ロビー対象アプリケーション オブジェクトを使ってロビー クライアントと通信し、ロビー クライアントを通じてロビー サーバーと通信する、サードパーティ アプリケーションである。
  • DirectPlay ロビー クライアント オブジェクト。
  • DirectPlay ロビー対象アプリケーション オブジェクト。

これらの 2 つの DirectPlay オブジェクトは、ゲーム アプリケーションとロビー クライアントの間のリンクとして機能する。これらのオブジェクトは、プライベートなインターフェイスを通じてやり取りする。次のグラフィックは、これらの構成要素がリンクされ、データをやり取りする様子を示している。


ロビー サーバー

ロビー サーバーは、プレーヤーが集まってゲームを準備できるようにすることを主な目的とするアプリケーションである。通常はリモート コンピュータにあり、インターネットを通じてアクセスする。ロビー サーバーは、チャット ルームのホスト、ニュースや情報の投稿、商品の販売などといったその他のさまざまな機能を実行することが多い。

マルチプレーヤー ゲームを管理するため、通常、ロビー サーバーは以下を含む多様な作業を行う。

  • 各種のゲーム セッションおよびプレーヤーのネットワーク アドレスを管理する。
  • プレーヤーのコンピュータにある関連するゲーム アプリケーションを起動して、セッションを開始する。
  • 進行中のセッションにプレーヤーを追加する。
  • セッション内の各種コンピュータを、正しいネットワーク アドレスに接続する。
  • プレーヤーがゲームを抜ける、ゲーム ホストが移行する、といったセッションの変化を把握する。

ロビー サーバー アプリケーションの詳細は、ベンダーが提供しようとしているサービスの種類によって異なる。Microsoft® DirectPlay® では、ロビー サーバーの実装方法も、ロビー サーバーとユーザー コンピュータの通信方法も、指定されていない。ただし、ロビー ベンダーは、DirectPlay 互換のロビー クライアントを実装し、ユーザーに配布しなければならない。


ロビー クライアント

ロビー クライアントとは、ロビー サーバーのベンダーが実装し、各プレーヤーのコンピュータにインストールされるアプリケーションである。ロビー クライアントは、プレーヤーおよびゲーム アプリケーションと、ロビー サーバーの間の通信を処理する。ロビー クライアントをインストールするには、通常、サインアップ手順の一部で、ユーザーにロビー サーバーの Web サイトからロビー クライアントをダウンロードさせる。

一般的なシナリオは次のようになる。

  1. 新しいプレーヤーが Web サイトにアクセスし、サインアップする。
  2. サインアップ手順の一部で、ロビー クライアントがクライアントのコンピュータにダウンロードされる。
  3. プレーヤーが、プレーするゲームを選び、セッションへの参加を要求する。
  4. Web サイトが、プレーヤーのコンピュータにあるロビー クライアントを起動する。通常の起動メカニズムは、ロビー クライアントの実行ファイルを指す URL である。
  5. ロビー クライアントが、手順を踏んでセッションを準備してから、ユーザーのゲーム アプリケーションを起動する。
  6. そのゲームがロビー可能アプリケーションなら、ロビー クライアントは、ゲーム アプリケーションがロビー サーバーと通信できるようにする。この接続により、ロビー サーバーは、プレーヤーがゲームに加わったりゲームから抜けたりする、ホストが移行する、といったイベントを把握できる。

ロビー クライアントは、リモート サーバーにリンクされていなくてもよい。ユーザーがロビー クライアントを直接起動する、という別のシナリオもある。この場合、ロビー クライアントが、(たとえばユーザーの LAN サブネットに接続されている) 利用可能なゲームとセッションを表示する。ユーザーがゲームとセッションを選ぶと、ロビー クライアントがゲームを起動する。

ここでは、ロビー クライアントが持ついくつかの一般的な機能について説明する。ロビー クライアントとそれに関連するロビー サーバーとの通信の詳細については、｢ロビー可能ゲームとの通信｣を参照すること。

実装の詳細については、｢ロビー クライアントの実装｣または SDK 付属のサンプル アプリケーション LobbyClient を参照すること。


ロビー可能ゲームとの通信

ロビー クライアントとそれに関連するロビー サーバーとの通信は、都合のよい方法で自由に処理できる。Microsoft® DirectPlay® では、ロビー クライアントがロビー可能ゲーム アプリケーションと通信する方法だけが指定されている。

ロビー クライアントは、ゲーム アプリケーションと直接通信しない。代わりに、DirectPlay ロビー クライアント オブジェクト (CLSID_DirectPlay8LobbyClient) と、その IDirectPlay8LobbyClient インターフェイスを通じて通信する。ゲーム アプリケーションがロビー可能なら、この結果、ロビー対象アプリケーション オブジェクトがゲームにメッセージを渡す。ロビー クライアントは、IDirectPlay8LobbyClient インターフェイスを使って以下のことを実行できる。

  • ユーザーのシステムにあるロビー可能アプリケーションを列挙する。
  • 既に実行中でなければアプリケーションを起動し、セッションに接続する。
  • アプリケーションをセッションから解放し、ロビー クライアントとのリンクを閉じる。
  • ロビー クライアントから起動または接続されたロビー対象アプリケーションに、メッセージを送信する。

注 DirectPlay ロビー クライアントは、ロビー可能かどうかにかかわらず、あらゆるアプリケーションを起動できる。ただし、ゲームの進行中に DirectPlay を使ってロビー クライアントに応答できるのは、ロビー可能アプリケーションだけである。

ロビー クライアント オブジェクトは、ロビー クライアントが実装したコールバック関数を通じて、ロビー クライアントと通信する。ロビー クライアント オブジェクトには、初期化時に関数ポインタが渡される。ロビー クライアント オブジェクトは、このコールバック関数を使って、以下のような情報をロビー クライアントに送信できる。

  • 接続情報。
  • 接続の状態。
  • セッションの状態 (接続、切断、ホストの移行など)。
  • アプリケーションからロビー クライアントへのメッセージ。

アプリケーションの起動

アプリケーションには、起動時にゲーム固有のデータ ブロックを渡すことができる。ロビー クライアントからロビー可能アプリケーションが起動されると、アプリケーションはロビー対象アプリケーション オブジェクトを作成し、初期化する。情報は、この初期化メソッドを通じてゲームに渡される。

ロビー対象アプリケーション オブジェクトが初期化されると、ユーザーが接続されたことを示すメッセージがロビー クライアントに届く。このメッセージが持つ主な目的の 1 つは、アプリケーションがロビー可能であることをロビー クライアントに知らせることである。起動後にある程度の時間が経過しても、ロビー クライアントに接続メッセージが届かない場合には、ゲームがロビー可能でないので、この接続をあきらめることができる。

アプリケーションの起動後

ロビー可能ゲームが始まると、ロビー クライアントは比較的暇になる。ユーザーのメッセージの多くは、ゲーム トポロジに応じて、ほかのプレーヤーに直接送信されるか、またはゲーム サーバーに送信される。ただし、切断やホストの移行といったイベントが発生すると、DirectPlay からロビー クライアントにメッセージが送信される。これらのメッセージにより、ロビー クライアントがロビー サーバーに状態変化を渡すことが可能になる。たとえば、ホストが移行した場合、ロビー サーバーは UI に新しいホストを反映できる。

アプリケーションは、ロビー クライアントにメッセージを渡すこともできる。このメッセージには事実上あらゆるデータを格納できる。また、用途にも制限はない。ロビー クライアントは、通常、そのデータをロビー サーバーに渡して処理を任せる。たとえば、ゲームの終了時に、ロビー サーバーのハイスコア一覧を更新するため、アプリケーションからロビー サーバーにメッセージを送信してもよい。


ロビー可能アプリケーション

ロビー可能アプリケーションは、Microsoft® DirectPlay® ベースのロビー クライアントと連動するようになっている。ロビー クライアントは DirectPlay を使って任意のアプリケーションを起動できるが、ロビー可能アプリケーションには多くの利点がある。

  • ゲームの状態が変化すると、ロビー クライアントに対して最新状態が自動的に送られる。
  • ロビー クライアントは、標準 API を使ってアプリケーションと通信できる。
  • アプリケーションは、標準 API を使ってロビー クライアントと通信できる。

要するに、DirectPlay を使用すれば、ゲーム固有またはロビー クライアント固有の通信コードはほとんど必要ない。特定のゲームやロビー クライアントのための修正をほとんど (またはまったく) 行わずに、何にでも標準 API を使用できる。

ここでは、ロビー可能アプリケーションが持ついくつかの一般的な機能について説明する。詳細については、｢ロビー可能アプリケーションの起動｣を参照すること。

実装の詳細については、｢ロビー可能アプリケーションの実装｣または SDK のサンプル (SimplePeer、StagedPeer など) を参照すること。


ロビー可能アプリケーションの起動

起動された後にロビー可能アプリケーションが実行すべき作業の 1 つは、ロビー対象アプリケーション オブジェクトを作成することである。このオブジェクトの最も重要な機能は、アプリケーションがロビー起動で起動されているかどうかを判断することにある。また、ロビー対象アプリケーションは、ロビー クライアントからメッセージを受信するために、メッセージ ハンドラ コールバック関数を実装する必要もある。基本的な手順は以下のとおりである。

  • ロビー対象アプリケーション オブジェクトを作成する。
  • オブジェクトを初期化する。
  • 初期化メソッドから有効な接続ハンドルが返される場合、アプリケーションはロビー起動で起動されている。
  • 初期化メソッドから返されたユーザー コンテキスト値を調べる。この値には、ロビー クライアントからのゲーム固有の情報が入っていることがある。
  • ロビー対象アプリケーションのメッセージ ハンドラを通じて受信した接続メッセージを調べる。このメッセージには、ロビー クライアントにメッセージを送信するときに使用する ID を含む、各種の情報が付属している。

アプリケーションのロビー起動で起動が成功すると、ホストの移行などのイベントが発生したときに、Microsoft® DirectPlay® がロビー クライアントに対して最新状態を自動的に送信できるようになる。状態の自動更新を有効にするには、IDirectPlay8Peer、IDirectPlay8Client、または IDirectPlay8Server インターフェイスの RegisterLobby メソッドを呼び出す。また、ロビー対象アプリケーションのインターフェイスを使って、ロビー クライアントにメッセージを送信することもできる。

メッセージ ハンドラ関数には、初期化メソッドから復帰する前に、ロビー クライアントからのメッセージが届くことがあるので、注意が必要である。接続メッセージに加えて、ロビー クライアントが接続の設定を変更したか、または接続を切断したときにも、このコールバック関数にメッセージが届く。また、ゲーム固有の情報が入ったメッセージを、ロビー クライアントからメッセージ ハンドラに直接送信することもできる。

注 メッセージの発信元は単独スレッドとは限らない。メッセージングを適切に処理するため、ロビー対象アプリケーションのコールバック関数は、再入可能でなければならない。


ネットワーキングの基本

ここでは、Microsoft® DirectPlay® アプリケーションを作成するために理解しなければならないネットワーキング技術について、基本的な事項をいくつか説明する。ネットワーキング技術の一般的な説明については、この分野に関する標準的な文献 (Andrew Tannenbaum 著の『Computer Networks』など) を参照すること。デフォルトの DirectPlay8 TCP/IP ダイアログをオーバーライドしようとするアプリケーション開発者は、接続や列挙に使用するポートをユーザーにオーバーライドさせるソリューションをかならず実装すべきである。1 つの可能なソリューションはデフォルトの DIrectPlay8 TCP/IP ダイアログが実装しているように (つまり "host.domain.com:8090" のように)、ユーザーにコロンでホスト名にポートを追加させる方法である。もう 1 つの可能なソリューションはユーザーがポートを入力できる別の UI フィールドを追加することである。

  • DirectPlay サービス プロバイダ
  • DirectPlay アドレシング
  • DirectPlay プロトコル
  • ネットワーク使用量の最適化
  • アプリケーションにおける DirectX プロトコルの使い方


DirectPlay サービス プロバイダ

Microsoft® DirectPlay® は、アプリケーションに仮想のネットワーク接続を提供する。この仮想ネットワーク接続を使用すると、関係するネットワークの種類にかかわらず共通の方法で、ほかのコンピュータと通信することができる。このレベルの抽象化を実現するため、ネットワーク接続はサービス プロバイダを通じて行われる。サービス プロバイダを選択すると、アプリケーションが、DirectPlay の適切なメソッドを使って、セッション内のほかのコンピュータと通信するようになる。選択したネットワーク ハードウェアをとおる通信の詳細は、そのサービス プロバイダで処理される。

DirectPlay には、TCP/IP、IPX、モデム、およびシリアルの 4 種類のネットワーク接続に対応するサービス プロバイダが含まれている。サービス プロバイダの選択方法については、「DirectPlay アドレシング」を参照すること。

注 DirectPlay は、TAPI (テレフォニー API) を使ってモデム接続を処理する。この API の使用は、電話への応答に使用されるコードが、メッセージ ループのスレッド内になければならないことを意味する。Microsoft Windows® 95 システムでモデムを使用するには、TAPI のバージョン 2.0 をインストールする必要がある。TAPI 2.0 は、http://www.microsoft.com/ からダウンロードできる。


DirectPlay アドレシング

メッセージを配信するには、マルチプレーヤー ゲームの各参加者が一意のアドレスを持っている必要がある。アドレスは、アプリケーションを実行しているコンピュータを参照するか (デバイス アドレス)、アプリケーションが通信する必要のあるコンピュータを参照できる (ホスト アドレス)。デフォルトの DirectPlay8 TCP/IP ダイアログをオーバーライドしようとするアプリケーション開発者は、接続や列挙に使用するポートをユーザーにオーバーライドさせるソリューションをかならず実装すべきである。1 つの可能なソリューションはデフォルトの DIrectPlay8 TCP/IP ダイアログが実装しているように (つまり "host.domain.com:8090" のように)、ユーザーにコロンでホスト名にポートを追加させる方法である。もう 1 つの可能なソリューションはユーザーがポートを入力できる別の UI フィールドを追加することである。

Microsoft® DirectPlay® 8.0 では、アドレスを URL 文字列の形で表現する。このアドレス文字列は、さらに、IDirectPlay8Peer::Connect などのメソッドの入出力パラメータとして渡される DirectPlay アドレス オブジェクト内にカプセル化される。

ここでは、DirectPlay アドレスの 2 つ処理方法について説明する。

  • 「DirectPlay URL」は、アドレス文字列を直接構築する方法である。
  • 「DirectPlay アドレス オブジェクト」は、アドレス オブジェクトの IDirectPlay8Address インターフェイスで公開されるメソッドを使って、アドレス文字列を操作する方法である。


DirectPlay URL

Microsoft® DirectPlay® では、アドレスを URL として表現する。一般に、URL は、スキーム、スキーム セパレータ、およびデータ文字列の 3 つの基本要素が、この順序に並べられた文字列である。

すべての DirectPlay アドレスは、スキームとして "x-directplay" を使用し、スキームのセパレータとして ":/" (コロンとそれに続く順スラッシュ) を使用する。セパレータとして ":/" を使用すると、後に続くデータが不透明であることを示す。言い換えると、データ文字列はどのインターネット標準にも適合しておらず、受け取り側アプリケーションにそのまま渡す必要がある。したがって、DirectPlay のすべての URL は次の一般形式になる。

x-directplay:/[data string]

注 スキームのセパレータとして "://" (コロンとそれに続く 2 つの順スラッシュ) を使用しないこと。このセパレータは、後続のデータがインターネット標準に適合しており、その標準に従って解釈できることを示す。混乱を避けるため、DirectPlay では、"://" を含むすべての URL が無効と見なされる。

説明するトピックは、次のとおりである。

  • データ文字列
  • データ値
  • データ値の概要
  • サンプル URL


データ文字列

データ文字列には、アドレス情報が保持される。データ文字列の最初の部分は、セミコロン (;) で区切られた一連の要素 "keyname=value" から成り立っている。最後の値の後にシャープ記号 (#) を付け、アプリケーションで定義した文字列を続けると、オプションのユーザー データを含めることができる。

キー名は、データを識別し、値に入っているデータの種類を非明示的に示す小文字の文字列である。たとえば、"provider" というキー名は、Microsoft® DirectPlay® サービス プロバイダの GUID が、GUID 文字列の形で値に格納されていることを示す。以下の文字は予約済みなので、値の文字列に使用しないこと。

アンパサンド (&) | 順スラッシュ (/)
アット マーク (@) | シャープ記号 (#)
コロン (:) | 疑問符 (?)
等号 (=) | セミコロン (;)

データ文字列の最初の要素は、プロバイダでなければならない。ほかの要素は、任意の順序で続けることができる。一般的な URL は、次のようになる。

x-directplay:/provider=%provider GUID%;[keyname1=value1];[keyname2=value2][...]#[user defined string]


データ値

データ文字列に含まれていなければならない値は、サービス プロバイダによって異なる。たとえば、モデム プロバイダのアドレスには電話番号が必要だが、LAN プロバイダではポート番号が必要かもしれない。ここでは、標準のデータ値について詳しく説明する。また、文字列そのものの代わりに使用できるキー名についても触れる。Dpaddr.h には、以下の名前が定義されている。

  • Application Instance
  • Baud
  • Device
  • Flow Control
  • Host Name
  • Parity
  • Phone Number
  • Port
  • Program
  • Provider
  • Stop Bits

Application Instance

アプリケーション インスタンスを識別するオプションの GUID。接続先のゲームを指定するときには、この値が使用される。

キー名 : DPNA_KEY_APPLICATION_INSTANCE

キー文字列 : "applicationinstance"

データ型 : GUID

プロバイダ : すべて。

有効な値 : 任意の有効なアプリケーション インスタンス GUID。

Baud

ボー レート。

キー名 : DPNA_KEY_BAUD

キー文字列 : "baud"

データ型 : DWORD

プロバイダ : モデムおよびシリアル。

有効な値 :任意の有効なボー レート。この値には、適切な整数を設定してもよいし、Dpaddr.h にあらかじめ定義されている以下の値のいずれかを使用してもよい。

DPNA_BAUD_RATE_9600
DPNA_BAUD_RATE_14400
DPNA_BAUD_RATE_19200
DPNA_BAUD_RATE_38400
DPNA_BAUD_RATE_56000

Device

ローカル コンピュータ上で使用するデバイスを識別する GUID。サービス プロバイダがすべてのアダプタをサポートしていれば、デバイスを指定する必要はない。

キー名 : DPNA_KEY_DEVICE

キー文字列 : "device"

データ型 : GUID

プロバイダ : すべて。ただしデバイス アドレス専用。ホスト アドレスは除く。

有効な値 : 任意の有効なデバイス GUID。

Flow Control

使用するフロー制御の種類。

キー名 : DPNA_KEY_FLOWCONTROL

キー文字列 : "flowcontrol"

データ型 : String

プロバイダ : シリアルおよびモデム。

有効な値 : Dpaddr.h にあらかじめ定義されている以下の値のいずれか。

DPNA_FLOW_CONTROL_NONE | DPNA_FLOW_CONTROL_DTR
DPNA_FLOW_CONTROL_XONXOFF | DPNA_FLOW_CONTROL_RTSDTR
DPNA_FLOW_CONTROL_RTS |

Host Name

リモート ホスト コンピュータの名前。

キー名 : DPNA_KEY_HOSTNAME

キー文字列 : "hostname"

データ型 : String

プロバイダ : すべて。ただしホスト アドレス専用。デバイス アドレスは除く。

有効な値 : 完全に修飾されたホスト名か、またはドットが含まれるアドレス。

Parity

接続のパリティ。

キー名 : DPNA_KEY_PARITY

キー文字列 : "parity"

データ型 : String

プロバイダ : シリアルおよびモデム。

有効な値 : Dpaddr.h にあらかじめ定義されている以下の値のいずれか。

DPNA_PARITY_NONE | DPNA_PARITY_MARK
DPNA_PARITY_EVEN | DPNA_PARITY_SPACE
DPNA_PARITY_ODD |

Phone Number

電話番号。

キー名 : DPNA_KEY_PHONENUMBER

キー文字列 : "phonenumber"

データ型 : String

プロバイダ : モデム。

有効な値 : 任意の有効な電話番号。

Port

オプションのポート番号。

キー名 : DPNA_KEY_PORT

キー文字列 : "port"

データ型 : DWORD

プロバイダ : IP および IPX。

有効な値 : 任意の 16 ビット整数。値の下位 16 ビットのみが意味を持つ。ポートを指定しなかった場合は、自動的に選択される。

Program

オプションのアプリケーション GUID。

キー名 : DPNA_KEY_PROGRAM

キー文字列 : "program"

データ型 : GUID

プロバイダ : すべて。

有効な値 : 任意の有効なアプリケーション GUID。

Provider

使用する Microsoft® DirectPlay® サービス プロバイダを識別する GUID。

キー名 : DPNA_KEY_PROVIDER

キー文字列 : "provider"

データ型 : GUID

プロバイダ : すべて。

有効な値 : 任意の有効なサービス プロバイダ GUID。

Stop Bits

ストップ ビット数。

キー名 : DPNA_KEY_STOPBITS

キー文字列 : "stopbits"

データ型 : String

プロバイダ : シリアルおよびモデム。

有効な値 : Dpaddr.h にあらかじめ定義されている以下の値のいずれか。

DPNA_STOP_BITS_ONE | DPNA_STOP_BITS_TWO
DPNA_STOP_BITS_ONE_FIVE |


データ値の概要

以下の 2 つの表は、標準のデータ値の概要であり、各タイプのサービス プロバイダがホスト アドレスとデバイス アドレスの両方に使用する値を示している。

ホスト アドレス

 | IP | IPX | シリアル | モデム
Application Instance | 省略可能 | 省略可能 | 省略可能 | 省略可能
Baud | 未使用 | 未使用 | 必須 |
Device | 未使用 | 省略可能 | 必須 | 必須
Flow Control | 未使用 | 未使用 | 必須 |
Host Name | 必須 | 必須 | 省略可能 | 省略可能
Parity | 未使用 | 未使用 | 必須 |
Phone Number | 未使用 | 未使用 | 未使用 | 必須
Port | 必須 | 必須 | 未使用 | 未使用
Program | 省略可能 | 省略可能 | 省略可能 | 省略可能
Provider | 必須 | 必須 | 必須 | 必須
Stop Bits | 未使用 | 未使用 | 必須 |

デバイス アドレス

 | IP | IPX | シリアル | モデム
Application Instance | 省略可能 | 省略可能 | 省略可能 | 省略可能
Baud | 未使用 | 未使用 | 必須 | 未使用
Flow Control | 未使用 | 未使用 | 必須 | 未使用
Host Name | 省略可能 | 省略可能 | 省略可能 | 省略可能
Device | 省略可能 | 必須 | 必須 | 必須
Parity | 未使用 | 未使用 | 必須 | 未使用
Phone Number | 未使用 | 未使用 | 未使用 | 未使用
Port | 省略可能 | 必須 | 未使用 | 未使用
Program | 省略可能 | 省略可能 | 省略可能 | 省略可能
Provider | 必須 | 必須 | 必須 | 必須
Stop Bits | 未使用 | 未使用 | 必須 | 未使用


サンプル URL

以下のサンプル URL は、4 つの標準サービス プロバイダに対応する Microsoft® DirectPlay® URLの例を示している。

ローカル IP アドレス

x-directplay:/provider=%7BEBFE7BA0-628D-11D2-AE0F-006097B01411%7D;device=%7BIP ADAPTER GUID%7D;port=0000230034#IPUserData

ローカル IPX アドレス

x-directplay:/provider=%7B53934290-628D-11D2-AE0F-006097B01411%7D;device=%7BIPX ADAPTER GUID%7D;port=00230#IPXUserData

ローカル シリアル アドレス

x-directplay:/provider=%7B743B5D60-628D-11D2-AE0F-006097B01411%7D;device=%7BCOM PORT GUID%7D;baud=57600;stopbits=1;parity=NONE;flowcontrol=RTSDTR#SerialUserData

リモート モデム アドレス

x-directplay:/provider=%7B6D4A3650-628D-11D2-AE0F-006097B01411%7D;device=%7BMODEM DEVICE GUID%7D;phonenumber=555-1212#ModemUserData


アドレスの処理

IDirectPlay8Peer、IDirectPlay8Client、または IDirectPlay8Server で公開される Host、EnumHosts、または Connect メソッドを呼び出す場合は、アドレス オブジェクトをパラメータとして渡す必要がある。Microsoft® DirectPlay® に十分なアドレス情報がないと、呼び出したメソッドが失敗し、DPNERR_ADDRESSING が返される。ただし、メソッドを呼び出すときに、アドレス オブジェクト内の情報がすべて揃っている必要はない。

すべてのアドレス オブジェクトには、サービス プロバイダ GUID が設定されている必要があるが、その他のデータ値は省略可能である。

  • サービス プロバイダがすべてのアダプタをサポートしていれば、デバイスを省略できる。
  • IP および IPX サービス プロバイダでは、Host、EnumHosts、および Connect メソッドのポート番号を省略できる。ポート番号は、DirectPlay で割り当てられる。この番号は状況によって異なる。
  • OKTOQUERYFORADDRESSING フラグを設定すると、アドレスに足りない情報をユーザーにたずねるダイアログ ボックスを、サービス プロバイダが表示できる。ユーザーが十分な情報を提供しなければ、メソッドは失敗する。OKTOQUERYFORADDRESSING フラグを設定しなかった場合、このダイアログ ボックスは表示されない。メソッドに渡したアドレスが足りなければ、メソッドは失敗する。最後の 2 つの場合、返されるエラー値は DPNERR_ADDRESSING となる。

IP および IPX サービス プロバイダに関しては、重要な注意事項が 2 つある。これらの処理が適切でないと、アプリケーションが失敗する可能性がある。

  • 列挙メソッドを呼び出すときに NOBROADCASTFALLBACK フラグを設定する場合は、ホスト名を渡す必要がある。そうしないと、メソッドが失敗し、DPNERR_ADDRESSING が返される。
  • ポートを指定しない場合、DirectPlay により常に同じポート番号が選択されると考えてはならない。特定のポート番号を使用する唯一の方法は、アドレスでそのポート番号を指定することである。ポート番号を指定しない場合は、後でコマンドの進行中に実際の値を取得する必要がある。

デフォルトの DirectPlay8 TCP/IP ダイアログをオーバーライドしようとするアプリケーション開発者は、接続や列挙に使用するポートをユーザーにオーバーライドさせるソリューションをかならず実装すべきである。1 つの可能なソリューションはデフォルトの DIrectPlay8 TCP/IP ダイアログが実装しているように (つまり "host.domain.com:8090" のように)、ユーザーにコロンでホスト名にポートを追加させる方法である。もう 1 つの可能なソリューションはユーザーがポートを入力できる別の UI フィールドを追加することである。


DirectPlay アドレス オブジェクト

Microsoft® DirectPlay® では、URL 文字列を直接処理しない。代わりに、文字列を DirectPlay アドレス オブジェクト (CLSID_DirectPlayAddress) 内にカプセル化する必要がある。このオブジェクトは、IDirectPlay8Address インターフェイスを公開する。このインターフェイスを使用すると、アドレス オブジェクトに URL 情報を挿入したり、逆にアドレス オブジェクトから URL 情報を抽出したりできる。

DirectPlay アドレスを作成するには、CoCreateInstance を呼び出して DirectPlay アドレス オブジェクトを作成する必要がある。この結果、以下の 2 つの方法のどちらかでアドレスを定義できるようになる。

  • URL 文字列を直接作成する。次に、作成した文字列を IDirectPlay8Address::BuildFromURLA または IDirectPlay8Address::BuildFromURLW を使って挿入する。
  • IDirectPlay8Address メソッドを使って、文字列を構成する各種のデータをオブジェクトに直接挿入する。

アドレス オブジェクトを受け取るときにも、同様の 2 つの選択肢がある。

  • IDirectPlay8Address::GetURLA または IDirectPlay8Address::GetURLW を使って、URL 文字列全体を抽出する。次に、その文字列を解析して必要な情報を抽出する。
  • ほかの IDirectPlay8Address メソッドを使って、興味のある特定のデータをアドレス オブジェクトから抽出する。


DirectPlay プロトコル

マルチプレーヤー ゲームには、最高のパフォーマンスを提供するために、効率的で柔軟なネットワーク メッセージング サービスが必要になる。Microsoft® DirectPlay® プロトコルは、すべての DirectPlay メッセージングに使用される、トランスポート レイヤのメッセージング プロトコルである。DirectPlay 8.0 では、このプロトコルが大幅に改訂されている。新しいプロトコルは、アプリケーションがあらゆる面で円滑に動作するために必要なメッセージング サポートを提供する。DirectPlay プロトコルには、以下のメッセージング サポートが含まれる。

  • 高信頼性および低信頼性のメッセージ配信
  • シーケンシャル メッセージ配信と非シーケンシャル メッセージ配信
  • メッセージの分割と再構成
  • 混雑の制御
  • 送信の優先順位付け
  • メッセージのタイムアウト

注 DirectPlay の以前のバージョンでは、DirectPlay プロトコルはオプションであり、明示的に指定しなければらならなかった。DirectPlay 8.0 では、DirectPlay のすべてのメッセージングにこのプロトコルが使用される。

このドキュメントでは、DirectX の動作の様子、およびアプリケーションにおけるDirectX の使い方について、概要を説明する。

  • メッセージ処理の基本
  • メッセージのカテゴリ
  • 混雑の制御
  • 送信の優先順位付け
  • メッセージング統計情報の監視
  • 未処理メッセージ キューの監視


メッセージ処理の基本

メッセージという用語は、このドキュメントで使用される場合、別のコンピュータに送信する必要があるデータ ブロックを意味する。ネットワーク プロトコルは、データ ブロックにターゲットのネットワーク アドレスといった情報を保持するいくつかのビットを追加して、"パケット" を作成する。このパケットが、ネットワーク データの基本単位となる。パケットがターゲットに届くと、ターゲットのネットワーク プロトコルが、余分のビットを削除し、受け側のアプリケーションにそのデータ ブロックを渡す。

使い方は似ているが、"メッセージ" という用語と "パケット" という用語は厳密には互換でない。このドキュメントでは、Microsoft® DirectPlay® API とやり取りする情報の単位を、"メッセージ" と表現する。また、ネットワークが処理する情報の単位を、"パケット" と表現する。パケットは、DirectPlay 内部で処理される。ごく稀な例外を除き、DirectPlay アプリケーションではメッセージだけを処理すればよい。

"メッセージ" と "パケット" を区別する主な理由は、ネットワークで処理されるパケットの最大サイズが通常制限されていることにある。このサイズを、最大伝送単位 (MTU) という。メッセージが小さい場合は、メッセージが単独パケットで送信されるため、2 つの用語は事実上同義である。一方、大きいメッセージは、複数のパケットに分割して送信し、受け側で再構成しなければならないことがある。DirectPlay プロトコルでは、メッセージの分割および再構成が必要に応じて自動的に処理される。どちらの場合も、アプリケーションに関する限り、メッセージを送信し、ターゲットがそれを受け取るということは変わらない。

注 DirectPlay が配信するメッセージのサイズに制限はない。ただし、単独メッセージに必要なパケット数が増えるほど、パケットが失われ、再送信しなければならない確率が高くなる。したがって、分割および再構成が必要な大きいメッセージでは、通常、単独パケットのメッセージよりネットワークの遅延時間が大きくなる。ネットワークの遅延時間を最小限に抑える必要がある場合は、(ネットワークの損失が多い場合には特に) 大きなメッセージの送信を避けること。現在の接続で単独パケットに収容できる最大のメッセージ サイズは、IDirectPlay8Peer、IDirectPlay8Client、および IDirectPlay8Server インターフェイスで公開される GetSPCaps メソッドを呼び出して判断できる。


メッセージのカテゴリ

Microsoft® DirectPlay® プロトコルは、以下の 2 種類の基本的なネットワーク メッセージングを処理するようになっている。

  • "高信頼性" 対 "低信頼性"。ターゲット アプリケーションにメッセージが確実に配信されることを保証するかどうかが異なる。
  • "シーケンシャル" 対 "非シーケンシャル"。送信されたときと同じ順序で、メッセージがターゲットに届くかどうかが異なる。

ゲームでは、さまざまな目的でメッセージングが使用され、個々の要求も多様である。メッセージングへのこの広範な要求に対応するため、DirectPlay プロトコルでは、メッセージを以下の 4 つのカテゴリに分類できる。

  • 高信頼性でシーケンシャル
  • 低信頼性でシーケンシャル
  • 高信頼性で非シーケンシャル
  • 低信頼性で非シーケンシャル

DirectPlay プロトコルでは、メッセージごとにカテゴリを割り当てて、メッセージング方法を最適化することができる。

高信頼性メッセージングと低信頼性メッセージング

メッセージは伝送の過程で失われることがある。"高信頼性" メッセージングでは、すべてのメッセージがターゲットに届くことが保証される。データの損失が許されないときは、この種類のメッセージングが必要になる。"高信頼性" メッセージングの多くのスキームでは、ターゲットに対して各メッセージの受信確認を求める。指定されたタイムアウト時間内に受信確認が届かない場合、差出人はメッセージを再送信する。通常、メッセージが届いたことを示す受信確認を差出人が受け取るまで、この手順が繰り返される。

DirectPlay プロトコルでは、再送信の回数に上限が設定されている。再送信をある程度繰り返しても受信確認が届かない場合、DirectPlay は接続が失われたものと見なし、接続を閉じる。

低信頼性メッセージングは、最も簡単な形のネットワーク通信である。メッセージがターゲットに配信されることを保証しないため、高信頼性メッセージングより高速で通信できる。差出人がメッセージを送信する。ターゲットにメッセージが届かない場合、差出人はメッセージを再送信せず、パケットは失われる。

低信頼性メッセージングは、主に、メッセージが失われないことより速度または帯域幅を優先する場合に使用される。たとえば、高帯域幅のストリーミング メディア アプリケーションでは、低信頼性メッセージングを採用することが多い。これらのアプリケーションでは、帯域幅を受信確認や再送信に充てる余裕がなく、失われたメッセージの再送信を待つこともできない。メッセージがときどき失われることは、品質にほとんど影響しないことが多く、無視しても問題ない。

シーケンシャル メッセージングと非シーケンシャル メッセージング

メッセージは特定の順序で差出人の手を離れる。ただし、送信されたときと同じ順序でメッセージがターゲットのコンピュータに届くという保証はない。たとえば、メッセージが失われて再送信が必要になった場合、通常、そのメッセージは元の順序で後ろにあったメッセージより後に届く。

シーケンシャル メッセージングでは、メッセージに埋め込まれた順序情報を使って、メッセージが正しい順序でターゲット アプリケーションに渡される。ターゲット アプリケーションがメッセージを正しい順序で受信しなければならないときには、この種類のメッセージングが必要になる。順序どおりでないメッセージは、欠けているメッセージが届くまでバッファリングされる。

非シーケンシャル メッセージングでは、メッセージが、送信された順序に関係なく、ターゲット コンピュータに届くと同時にターゲットに渡される。非シーケンシャル メッセージングは、欠けているパケットを待つ必要がないので、メッセージが順序どおりに届くことより速度を優先する場合に使用されることが多い。順序どおりでないメッセージは無視される。

最適なメッセージ カテゴリの選択

メッセージに適したカテゴリの選択は、マルチプレーヤー ゲームを開発するうえで中心になる問題である。DirectPlay にはメッセージングを管理するためのツールが用意されているが、メッセージ カテゴリの選択は、最終的にはメッセージの意味とゲームの性質に依存する。

最適なメッセージ カテゴリを選択するための一般的なガイドラインは、以下のようになる。

  • 内容的に問題がなければ、非保証のメッセージングを使用する。たとえば、プレーヤーの最新位置を頻繁に送信する場合を考える。更新内容は互いに無関係であり、新しい情報は以前の情報すべてに取って代わる。更新内容が失われても、次回の更新でプレーヤーのゲームの状態を維持できる。メッセージが失われ、再送信されると、後続の更新メッセージより後に届く可能性がある。
  • データの損失が許されないときには、保証のあるメッセージングを使用する。たとえば、テキストベースのチャット機能では、すべての文字をそのターゲットに配信する必要がある。
  • メッセージの順序が重要なときには、シーケンシャル メッセージングを使用する。たとえば、ストリーミング メディア アプリケーションでは、通常、シーケンシャルの低信頼性メッセージングを採用する。メッセージがときどき失われることは許されるが、メッセージが順序どおりに届かないと問題が起きる可能性がある。


混雑の制御

理想的な環境では、メッセージを必要なだけ送信できる。メッセージは直ちにターゲットへ届き、即座に処理される。ゲームにかかわるすべてのコンピュータが、十分な処理能力を持ち、負荷の軽い高帯域幅のネットワーク リンクで接続されていれば、この理想的環境に近付くことができる。そのうえで、メッセージを必要なだけ送信できる。ただし、多くの要因によって "混雑" が発生し、メッセージングが理想より遅くなることがある。

  • ネットワークの遅延時間。理想的な状況でも、メッセージがネットワークを通じて差出人からターゲットに渡るには、ある程度の時間がかかる (インターネットを通る場合は特に)。受信確認、失われたパケットの再送信、または順序どおりでないパケットの再構成が行われると、この時間はさらに長くなる。
  • ネットワークの帯域幅。コンピュータがメッセージを送受信できる速度は、ネットワークの帯域幅によって制御される。ネットワーク リンクの帯域幅の範囲は広い。また、高帯域幅のネットワークであっても、トラフィックの水準が高ければ速度が落ちる可能性がある。低帯域幅の接続を使用しているプレーヤーがいる場合、それらのプレーヤーは、限られた速度でしかメッセージを送受信できない。
  • 処理速度。ネットワークの帯域幅が高く、遅延時間が少なくても、受信したメッセージをターゲット アプリケーションが処理するには、ある程度の時間がかかる。セッション内に比較的低速のコンピュータを使用しているプレーヤーがいる場合、これらのプレーヤーが受信したメッセージを処理できる速度は、メッセージの送信速度より低くなる可能性がある。

メッセージのスロットリング

メッセージの送信速度を制御しないと、大量のメッセージがターゲットに届き、処理しきれない可能性がある。この状況を避けるため、Microsoft® DirectPlay® プロトコルでは、メッセージの送信速度を "スロットリング" する。スロットリングの最終的な効果は、ターゲットがメッセージを処理できる速度によって、メッセージが送信される速度が制御されることである。

スロットリングは、"スライディング ウィンドウ" メカニズムを使って実装される。スライディング ウィンドウは、基本的には限られた数のスロットを持つキューであり、受信されていない送信済みのメッセージを保持する。流出するメッセージは、メッセージのカテゴリに関係なく、すべてこのキューに入れられる。送信済みメッセージ キューが一杯になると、キュー内のメッセージのいずれかが受信されるまで、流出するメッセージが受け付けられなくなる。

最高のパフォーマンスを提供するためには、スライディング ウィンドウのサイズを現在のネットワーク状況に合わせる必要がある。DirectPlay プロトコルでは、送信済みメッセージ キュー内のメッセージ数や総バイト数などの要素が、自動的に監視される。次に、現在のネットワーク状況に合わせてメッセージングを最適化するため、この情報を使ってスライディング ウィンドウのサイズが動的に調整される。

接続の検査

リンクが利用されていないと、DirectPlay プロトコルでは、高信頼性の空パケットを送信して繰り返し接続をテストする。再送信をある程度繰り返してもターゲットから受信確認が届かない場合、DirectPlay は接続が切断されたものと見なす。


送信の優先順位付け

メッセージの重要性は、メッセージごとに異なる。あるメッセージはタイム クリティカルで、できる限り速く配信しなければならない。また、あるメッセージは、必要に応じて遅らせることができるし、送信さえしないでよいかもしれない。混雑の制御アルゴリズムの 1 つの問題は、アプリケーションがメッセージを作成する速度が、送信可能な速度を上回る場合である。このような場合には、流出用のスロットが開くまで、未送信のメッセージをキューに保存する必要がある。未送信のメッセージをすべて単独の未処理メッセージ キューに保持すると、優先度の低いメッセージが先に送信されるまで、優先度の高いメッセージがブロックされる可能性がある。

Microsoft® DirectPlay® プロトコルでは、3 つの未処理メッセージ キュー (低優先度、中優先度、および高優先度) を用意することによって、この問題を解決する。送信済みメッセージ キューのスロットが開くと、次に送信すべきメッセージが次のように選択される。

  1. 高優先度キュー内で最も古いメッセージを送信する。
  2. 高優先度キューにメッセージがない場合は、中優先度キュー内で最も古いメッセージを送信する。
  3. 中優先度キューにメッセージがない場合は、低優先度キュー内で最も古いメッセージを送信する。

この優先度メカニズムにより、ほかのあまり重要でないメッセージが既に発行されていても、タイム クリティカルなメッセージをできる限り速く処理することができる。

送信のタイムアウト

スロットリングの 1 つの結果として、メッセージが未処理メッセージ キュー内に比較的長時間留まることがある (優先度が低い場合は特に)。場合によっては、メッセージが長時間保持されているうちに、そのメッセージに取って代わる後続メッセージが届くことがある。これらのメッセージは、もう不要である。たとえば、プレーヤーの最新位置を示すメッセージを周期的に送信する場合を考える。更新内容は互いに無関係であり、最新の情報は以前の情報すべてに取って代わる。未処理メッセージ キュー内にプレーヤーの最新位置が 2 つある場合、送信する必要があるのは最も新しいものだけである。

DirectPlay プロトコルでは、省略可能のタイムアウト値をメッセージに追加することで、古いメッセージの問題に対応できる。タイムアウト時間が過ぎたときに、まだ未処理メッセージ キューに保持されていると、そのメッセージは取り消される。

切断

アプリケーションが切断メッセージを送信すると、そのメッセージが低優先度の未処理メッセージ キューの最後に追加され、プロトコルが流出するメッセージの受け付けを停止する。この処理により、すべての未処理メッセージがリンク切断前に送信される。切断メッセージは、高信頼性のシーケンシャル メッセージとして送信され、ターゲットに届くことが保証されているが、その前にキュー内にあるほかのメッセージがすべて配信される。


メッセージング統計情報の監視

メッセージングの要素の多くは Microsoft® DirectPlay® プロトコルで自動的に処理されるが、メッセージングの動作はアプリケーションで監視しなければならない。たとえば、常時送信するメッセージの量に配信速度が追いつかないようであれば、メッセージング スキームを修正する必要があるかもしれない。

ネットワーク状況は常に変化しているので、ネットワーク動作の監視、およびその結果に応じたメッセージング スキームの調整は、定期的に行わなければならない。これには、メッセージングをサポートするすべての DirectPlay 8.0 インターフェイスで公開される GetConnectionInfo メソッドを呼び出す。GetConnectionInfo は、以下を含む各種の統計情報が入った構造体を返す。この統計情報を使ってメッセージング スキームを微調整することができる。

  • 往復時間
  • スループット
  • 送信パケット数
  • 受信パケット数
  • 再送信パケット数
  • 遺失パケット数
  • 転送メッセージ数 (優先度別)

注 メッセージング統計情報を取得するには、実際のネットワーク トラフィックを監視する。接続を初期化した直後に GetConnectionInfo を呼び出すと、データが短時間しか収集されないため、統計情報が参考にならないことがある。


未処理メッセージ キューの監視

未処理メッセージ キューは、大きくなりすぎないように監視しなければならない。IDirectPlay8Peer、IDirectPlay8Client、および IDirectPlay8Server インターフェイスは、すべて GetSendQueueInfo メソッドを公開する。このメソッドを使用すると、キュー内の現在のメッセージ数とバイト数を確認できる。デフォルトでは 3 つのキューの合計が返されるが、3 つの優先度それぞれの値を取得することもできる。


ネットワーク使用量の最適化

快適なゲーム体験の提供とは、通常、最新情報やその他の情報を、ターゲットの処理能力を超えない範囲で、できる限り速く送信することを意味する。Microsoft® DirectPlay® プロトコルと非同期メッセージングを組み合わせると、メッセージング方法を動的に最適化して、ユーザーに快適なゲーム体験を提供することができる。

メッセージングの大半では、IDirectPlay8Peer::SendTo、IDirectPlay8Client::Send、または IDirectPlay8Server::SendTo メソッドを使用する。これらのメソッドは、通常、メッセージ カテゴリに関係なく非同期に動作する。メソッドからは即座に復帰し、メッセージが実際に送信されると、メッセージ ハンドラに DPNMSG_SEND_COMPLETE メッセージが届く。一方、DPNSEND_SYNC フラグを設定すれば、メッセージを同期で送信できる。その場合、メソッドはメッセージが実際に送信されるまでブロックする。

DirectPlay プロトコルのスロットリング メカニズムでは、クライアントの処理能力を超える速度でメッセージが渡されないことが保証される。ただし、流出用のキューにメッセージが入る頻度は制御されない。このため、未送信メッセージのキューに大量のメッセージが溜まってしまうことがある。この状況はメッセージの送信頻度を抑えることによって避けることができるが、こうするとユーザーに提供されるゲーム体験の品質が不必要に低下しかねない。最もよいメッセージング方法は、ターゲットの処理能力を超えない範囲で、メッセージをできる限り速く送信することである。

メッセージング方法を最適化するためのヒントは、以下のようになる。

  • メッセージはできる限り非同期で送信する。メッセージを同期で送信すると、スロットリング メカニズムがメッセージの送信を許すまで、メソッドがブロックする。
  • 未処理メッセージ キューとネットワーク統計情報を監視する。キューにメッセージが少ないか、またはまったくない場合は、伝送速度を上げる。キューが大きいか、または急速に巨大化している場合は、伝送速度を下げ、できれば一部のメッセージを取り消す。詳細については、｢送信の優先順位付け｣にある送信タイムアウトの説明を参照すること。
  • プレーヤーごとに未処理メッセージ キューを分析する。メッセージの受信速度には、プレーヤーごとに相当な差があるかもしれない。その場合、一括の統計情報は参考にならない。グループへの送信ではなく、指名による送信を検討する。
  • 個々のメッセージに適したカテゴリを選択する。オーバーヘッドが最も大きいカテゴリは、最も重要なメッセージのために予約する。
  • メッセージに優先順位を付けて、最も重要なメッセージが、比較的重要でないメッセージのために遅れることなく、即座に送信されるようにする。
  • 未処理メッセージ キューが大きくなりすぎないようにする。未処理のメッセージが多いと、メッセージの伝送が遅れるだけでなく、メモリ リソースが大量に消費されることもある。
  • Send および SendTo メソッドのタイムアウト機能を使って、未処理メッセージ キューから古いメッセージを自動的に消去する。
  • メッセージあたりのデータ量を最小限に抑える。通常、大きいメッセージを少数送信するよりは、小さいメッセージを頻繁に送信した方がよい。
  • 未処理メッセージ キューを調べるときに、ループの間隔をあまり短くしないこと。間隔の短いループは、CPU サイクルの無駄である。代わりに、通常どの程度の時間で次の送信ができるようになるかを予想し、その時間スリープする方がよい。


アプリケーションにおける DirectX プロトコルの使い方

ここでは、アプリケーションから Microsoft® DirectPlay® プロトコルの機能をどのように使用できるかを説明する。

メッセージの送信には、5 つの DirectPlay インターフェイスを使用できる。

  • IDirectPlay8Peer
  • IDirectPlay8Client
  • IDirectPlay8Server
  • IDirectPlay8LobbyClient
  • IDirectPlay8LobbiedApplication

メッセージを送信するには、使用するインターフェイスに応じて Send または SendTo というメソッドを呼び出す。これら 5 つのメソッドの使い方はほぼ同じだが、詳細は異なる。詳細については、該当するリファレンス ページを参照すること。

Send および Sendto メソッドでは、パラメータを使って DirectPlay プロトコルが持つ多くの機能を制御できる。たとえば、IDirectPlay8Peer::SendTo の dwFlags フィールドでは以下のことを指定できる。

  • メッセージの優先度。
  • 高信頼性か低信頼性か。
  • シーケンシャルか非シーケンシャルか。

詳細については、該当するメソッドのリファレンスを参照すること。

アプリケーションにメッセージが届くと、コールバック関数に DPN_RECEIVE メッセージが届く。関連する構造体には、データ ブロックへのポインタと共に、メッセージの発信元といった情報が格納されている。


DirectPlay コールバック関数とマルチスレッドに関する問題

Microsoft® DirectPlay® と DirectPlay Voice では、DirectPlay が発行するイベントを処理するため、いくつかのコールバック関数を独自に実装する必要がある。DirectPlay はマルチスレッド化されているので、同時に複数のイベントを発行することがある。このため、重複する複数のコールバックがアプリケーションに届く可能性がある。

DirectPlay には、コールバックの指示に対応するために、スレッド プールが保持されている。コールバックは、DirectPlay が保持するプール内のスレッドから起動される。Microsoft Windows 2000 では、このスレッド プールのサイズをプロセスごとに構成できる。また、DirectPlay では、Windows 2000 上で動作するときに I/O 完了ポートを使用する。I/O 完了ポートは高度な問題であり、ここでは説明しない。この件については、MSDN (Microsoft Developer Network ) のドキュメントや、Win32 のマルチスレッドに関する現在入手可能なリファレンスを参照することを推奨する。

したがって、DirectPlay コールバックで正しく信頼性の高いデータ アクセスを行うには、同期をマルチスレッド化する手段を実装しなければならない。このことを、コールバックを "再入可能" または "スレッドセーフ" にする、と言う。

Microsoft Windows OS ファミリでは、現在、マルチスレッド環境でデータの同期をとるために、以下の 3 つの方法が用意されている。

  • ミューテックス オブジェクト
  • セマフォ オブジェクト
  • クリティカル セクション オブジェクト

クリティカル セクション オブジェクトを使って同期をとる方法は、DirectX 8.0 SDK に付属する DirectPlay の音声関連サンプルに示されている。ミューテックス オブジェクトまたはセマフォ オブジェクトを実装する場合、これらのトピックは、Microsoft Platform SDK にも、多くのリファレンス ブックにも記載されているので、参照すること。これらの同期手段は、万一何らかの問題が起きた場合、複雑で難しいデバッグ作業が必要になる。このため、いずれかを実装するには、個々の分野に関する相当進んだ知識がなければならない。

DirectPlay のスレッド モデルは、最高の効率が得られるように最適化されている。このため、"送信" 処理中、および受信メッセージを含む "指示" メッセージ中に、スレッド コンテキストが切り替わることはない。

ここでは、「DirectPlay のネットワーキング コールバック」について説明する。

詳細については、｢DirectPlay と DirectPlay Voice におけるコールバック関数の実装｣を参照すること。


DirectPlay のネットワーキング コールバック

Microsoft® DirectPlay® のネットワーキング コールバック関数は、PFNDPNMESSAGEHANDLER 型である。ネットワーキング セッションの種類に応じて、IDirectPlay8Peer::Initialize、IDirectPlay8Client::Initialize、または IDirectPlay8Server::Initialize を使ってコールバック関数のアドレスを登録する。

同期に関する問題

DirectPlay コールバックでの処理中にゲーム データの整合性を保つためには、3 つのスレッド同期オブジェクトのいずれかを採用する必要がある。

ゲーム データがどのように破損するかを説明するため、コールバックで構造体にゲーム データのパケットを挿入する場合について考える。1 番目のコールバックが完了しないうちに、ほかのスレッドからコールバックが再帰的に実行されると、このスレッドも、メモリ内の同じ場所にある構造体にアクセスし、内容を変更しようとする可能性がある。この結果、1 番目のスレッドが構造体に置いたデータが、2 番目のスレッドが構造体に置いたデータで上書きされる。これはマルチスレッドのごく簡単な例であり、スレッドが正常に同期しなくなる原因はほかにもいろいろあるので、注意が必要である。また、自作を試みる前に、マルチスレッド コールバックの実装に関する高度な知識を身に付けることも重要である。

DirectPlay ネットワーキング セッションでデータを同期させる方法の例については、｢クリティカル セクション オブジェクトを使った DirectPlay ネットワーキング コールバックの実装｣を参照すること。

ワーカー スレッド

"ワーカー スレッド" を自作するのも 1 つの方法である。ワーカー スレッドは、アプリケーションで定義されるもう 1 つのマルチスレッド コールバックであり、DirectPlay コールバックと関係なくゲーム データを処理するために作成される。この目的を達成するために、最も一般的な手段として、DirectPlay のネットワーキング コールバック スレッドでは、受け取ったデータをバッファに保存する。次に、新しいスレッドが作成され、バッファリング データを処理するように知らせるメッセージがワーカー スレッド コールバックに送信される。

マルチスレッドのパフォーマンスに関する問題と非同期処理

DirectPlay コールバック内でメッセージの処理にかける時間は、慎重に検討する必要がある。DirectPlay コールバック内で大量のデータを処理し、データをロックするメカニズムを使ってスレッドの同期をとると、ほかのスレッドがコールバックを実行するために待機するときにブロック問題が起きる。

一方、ワーカー スレッドを実装し、ゲーム データの処理を別のコールバックに任せると、自作のスレッドと DirectPlay で作成されたスレッドの間で CPU がコンテキストを切り替えるため、オーバーヘッドが大幅に増える危険性がある。この方法を採用できるのは、ゲーム データの処理に非常に時間がかかり、ゲームのリアルタイム処理にとって欠かせないデータでない場合に限られる。たとえば、プレーヤーの位置データは、ゲーム内でプレーヤーをリアルタイムに配置するために欠かせないデータなので、ワーカー スレッドで処理することは推奨されない。

コールバックから DPNSUCCESS_PENDING を返し、データ バッファへのポインタを作成し、ワーカー スレッドがそのポインタを利用できるようにすることもできる。ワーカー スレッドは、ゲーム データを処理し終わると、使用しているトポロジに応じて IDirectPlay8Peer または IDirectPlay8Client の ReturnBuffer メソッドを呼び出す。


DirectPlay Voice について

Microsoft® DirectPlay® Voice は、ネットワーク セッションおよびネットワーク転送を行う DirectPlay と統合された、フル音声通信 API である。

DirectPlay Voice は、音声の録音/再生を行うために、DirectSound とも統合されている。音声データを別々の再生バッファに振り分ける能力や、特殊オーディオ エフェクト (3D サウンド ポシショニングなど) の使用を含め、DirectSound が持つすべてのオーディオ機能が継承されている。

DirectPlay Voice のネットワーキング

DirectPlay Voice のトポロジ

音声ホストの移行

オーディオ デバイスのテスト

音声 CODEC

自動ゲイン制御

伝送制御

キャプチャ フォーカス

ジッター バッファ

ワーキング セットについてのガイドライン


DirectPlay Voice のネットワーキング

Microsoft® DirectPlay® Voice は、メディアに依存しないネットワーク転送とプレーヤー管理を行うために、DirectPlay セッションを使用する。DirectPlay Voice API のセッション制御機能は、DirectPlay とは異なっている。DirectPlay Voice が音声通信を送受信するためには、DirectPlay ネットワーク転送セッションも事前に作成されている必要がある。DirectPlay Voice は、IDirectPlay4 オブジェクトと IDirectPlay8 オブジェクトのいずれかを、ネットワーク転送に使用できる。

DirectPlay Voice をマルチプレーヤー ゲームと共に同時処理で使用している場合には、ゲーム固有のデータをやり取りするために、ゲームでも転送セッションを使用する可能性が高い。こうすると、ゲーム データと音声データの間でネットワーク リソースの使用を最適化することができる。

また、スタンドアロンの音声会議アプリケーションなどでは、音声セッション専用の転送セッションを作成して使ってもよい。


DirectPlay Voice のトポロジ

Microsoft® DirectPlay® Voice セッションは、音声通信の転送に DirectPlay ネットワーク セッションを使用する。ネットワーク セッションが作成されると、3 つのトポロジのいずれかを使用する DirectPlay Voice オブジェクトを作成できるようになる。

  • ピアツーピア音声トポロジ
  • 転送サーバー音声トポロジ
  • ミキシング サーバー セッション

選択すべきトポロジはさまざまな要素によって異なる。これらの要素については、DirectPlay Voice トポロジの各トピックで説明する。すべての音声トポロジが、あらゆる種類の DirectPlay ネットワーキング セッションを通じて転送できるとは限らないので、注意すること。


ピアツーピア音声トポロジ

ピアツーピア トポロジを採用している Microsoft® DirectPlay® Voice セッションでは、個々の音声セッション クライアントが、ほかのすべての音声セッション クライアントに、その音声オーディオ データを直接ストリームする。各クライアントは、流入する個々の音声オーディオ ストリームをすべて受け取り、受け取ったストリームをミキシングし、ミキシング済みの信号をクライアントのコンピュータで再生する。

ピアツーピア トポロジを採用する利点は、音声セッション内のコンピュータに、高い帯域幅やプロセッサ能力が要らないことにある。ただし、各クライアントのコンピュータにおける帯域幅とプロセッサの使用量は、出入りするオーディオ ストリームの数によって異なる。流出する音声オーディオ ストリームの数は、音声セッションに参加しているターゲットの数と等しい。ただし、後述するように、ネットワーク プロバイダが本来のマルチキャストを実行できる場合は例外である。流入する音声オーディオ ストリームの数は、ほかのいくつの音声セッション クライアントがそのクライアントをターゲットにしているか、およびほかのクライアントのうちいくつが話しているかによって異なる。

ゲーム設計の面から考えると、1 つの音声セッション クライアントを、6 ～ 8つを超えるクライアントがターゲットとすることは、実用的でない。6 ～ 8つのクライアントがすべて同時に話しだすと、会話が混乱し、クライアント間のやり取りが困難になる可能性がある。

DirectPlay ネットワーク セッションが本来のマルチキャストをサポートしていれば、流出する音声オーディオ ストリームの数を相当減らすことができる。全クライアントを 1 つのマルチキャスト ネットワークに含め、音声ストリームのターゲットを 1 つの DirectPlay グループにすると、流出するストリームはたった 1 つになる。

ピアツーピア音声トポロジを採用している DirectPlay 音声セッションは、IDirectPlayVoiceClient::Create3DSoundBuffer メソッドを使った音声データの 3D 空間化をサポートする。

ネットワーク転送がクライアント/サーバー セッションの場合には、音声ピアツーピア音声トポロジを採用している音声セッションを使用できないので、注意すること。


転送サーバー音声トポロジ

転送サーバー トポロジを採用している Microsoft® DirectPlay® 音声セッションでは、セッション内の 1 台のコンピュータが転送サーバーの役割をする。音声セッション内の各クライアントは、音声データを転送サーバーにストリームする。転送サーバーは、セッション内のほかのクライアントすべてに、この音声データを転送する。各クライアントが、転送サーバーから転送された流入オーディオ ストリームをすべて受け取る。最後に、各クライアントのコンピュータが、流入するストリームをミキシングして再生する。

転送サーバー トポロジを採用している音声セッションでは、流出する音声オーディオ ストリームが 1 つしかないため、個々のクライアントにおける流出帯域幅の要件は一定である。流入帯域幅とプロセッサの要件は、ピアツーピア トポロジを採用している音声セッションでの要件と同じだが、流入する音声オーディオ ストリームの数によって異なる。

転送サーバーによる DirectPlay 音声セッションでは、サーバーに個々のクライアントより大幅に高い帯域幅が必要になる。ただし、サーバー上では音声データの圧縮や圧縮解除が発生しないため、プロセッサ要件は高くない。このようにコンピュータのプロセッサへの負荷が減ることは、コンピュータ自体のパフォーマンスを悪化させることも、ゲーム サーバーや同じコンピュータで動作しているクライアント プログラムのパフォーマンスを悪化させることもなく、高い帯域幅で接続している個々のクライアントのコンピュータが、転送サーバーのホストとなれることを意味する。

ピアツーピア トポロジを採用している音声セッションでは、個々のクライアントにおける流出帯域幅の要件が、流入帯域幅の要件より大幅に高いのが普通である。したがって、流出帯域幅の要件をオーディオ ストリーム 1 つに減らせば、帯域幅の総使用量を大幅に減らすことができる。たとえば、8 人が参加している音声セッションで、全クライアントが互いの声を聞くことができる場合には、使用しているコンピュータで音声データがキャプチャおよび送信されるたびに、そのクライアントから 7 つの音声ストリームが流出する。ただし、全クライアントが同時に話すことはほとんどなく、同時に流入する音声ストリームは 2 ～ 3 つより少ないのが普通である。


ミキシング サーバー セッション

ミキシング サーバー セッションでは、セッション内の 1 台のコンピュータがミキシング サーバーの役割をする。各クライアントが、音声データをミキシング サーバーにストリームする。ミキシング サーバーは、個々の音声ストリームのターゲットを調べたうえで、適切な圧縮解除、ミキシング、および再圧縮を実行して、各クライアントに送るオーディオ データのミキシング済みストリームを生成する。各クライアントが、このミキシング済みの単独ストリームを受け取って再生する。

ミキシング サーバー セッション内のクライアントでは、個々のクライアントに、圧縮および送信すべき流出オーディオ ストリームが 1 つと、圧縮解除および再生すべき流入オーディオ ストリームが 1 つしかないため、流出帯域幅、流入帯域幅、および CPU の要件が簡単に予測できる。

ミキシング サーバーにおける帯域幅と CPU の要件は、クライアントより大幅に高い。通常、ミキシング サーバーは、1 台のコンピュータを完全に占有するか、または専用のゲーム サーバーとコンピュータを共有する。

ミキシング サーバー音声セッションは、IDirectPlayVoiceClient::Create3DSoundBuffer メソッドを使った音声データの 3D 空間化をサポートしない。

ミキシング サーバー音声セッションは、ピアツーピアまたはクライアント/サーバー転送セッションを使って実行できる。


音声ホストの移行

ピアツーピアの Microsoft® DirectPlay® ネットワーク セッションでは、ネットワーク セッション内の 1 つのクライアントがホストの役割をする。そのホストがセッションを抜けるか、または何らかの理由で応答しなくなると、セッション内のほかのクライアントがホストに選ばれる。

DirectPlay 音声セッションでは、ピアツーピア音声セッションで同様のホスト移行プロセスが発生する。ただし、音声ホストは DirectPlay ネットワーク セッションと無関係に移行する。音声ホストが移行するのは、サーバーが IDirectPlayVoiceServer::StopSession を呼び出したときか、または音声ホストが応答しなくなった場合である。音声ホストが移行すると、音声セッション内の個々のクライアントに DVMSG_HOSTMIGRATED コールバックが届く。新しいホストに渡される構造体には有効な pdvServerInterface ポインタがあり、IDirectPlayVoiceServer の呼び出しを開始できるようになっている。


オーディオ デバイスのテスト

マイクロフォンの設定は、IDirectPlayVoiceTest インターフェイスによってサポートされる。このインターフェイスには、IDirectPlayVoiceTest::CheckAudioSetup というメソッドが 1 つある。このメソッドを使用すると、テスト ウィザードを実行できる。このウィザードは、システムで全二重処理が正しくサポートされていることと、マイクロフォンと再生が適切に設定されていることを確認する。ウィザードは、選択した再生およびキャプチャ デバイスの組み合わせそれぞれにつき、1 回だけ実行する必要がある。アプリケーションでは、開始時に構成を毎回テストしなければならない。これには、dwFlags パラメータを DVFLAGS_QUERYONLY に設定して IDirectPlayVoiceTest::CheckAudioSetup を呼び出す。こうすると、直前のテスト後にデバイス構成が変化したかどうかを簡単に調べられる。デバイスがテストされていなければ、IDirectPlayVoiceTest::CheckAudioSetup をもう一度実行してウィザードを起動する。そうしないと、IDirectPlayVoiceClient::Connect が DVERR_RUNSETUP を返し、DirectPlay Voice を初期化できない。

ユーザーのサウンド カードに全二重能力がないと、音声通信を聞くことしかできない。音声通信を送信できないのは、通常、ゲームではオーディオ カードが再生モードになっているためである。問題を避けるため、DirectX 8.0 では再生とキャプチャを動的に切り替えられないようになっている。DirectX のオーディオ設定ウィザードを使用すると、システムの全二重能力に関するフィードバックが得られる。

現在でも、実際に使用されているシステムに全ニ重のサウンド カードが装備されていない場合は少なくないので、注意が必要である。全ニ重サウンド カードは 1998 年に普及したが、当時のオーディオ カード ドライバで全ニ重処理が有効なものは少ない。1999 年に新しいシステムを購入した場合や、1999 年にドライバをアップグレードした場合には、全二重能力がある可能性が高い。


音声 CODEC

Microsoft® DirectPlay® で専用に提供される圧縮/圧縮解除 (CODEC) アルゴリズムは、音声品質の CODEC である。これらのアルゴリズムは、すべて 8 kHz の 16 ビット モノラル形式に基づいている。サードパーティの CODEC はサポートされない。また、DirectPlay Voice と共に使用する独自の CODEC を作成することはできない。

帯域幅の要件が低くなると、音声データのオーディオ品質も低下するので、注意が必要である。

ゲームの音声セッション内で、CODEC を動的に切り替えることはできない。1 つの音声セッション内では、すべてのユーザーが同じ CODEC を使用する必要がある。ただし、適切なユーザー インターフェイスを作成し、そこで現在のセッションを破棄し、別の CODEC を使った新しいセッションを作成することによって、CODEC を強制的に切り替えることも可能である。ゲーム アプリケーションのユーザーが、ロビー チャットからゲームにジャンプしている場合には、この方法が適している。

ほかのすべてのゲーム設定パラメータと同様に、使用される CODEC はホストが制御しなければならない。音声セッション ホストとゲーム データのホストは、同一でなくてよい。

どのような形のネットワーク通信でも同じだが、音声通信の負荷を分析して、ゲーム データと音声データの通信に必要な帯域幅が確保できるかどうかを確認することが重要である。音声による帯域幅の使用量は、簡単に分析できる。同時に発生すると思われる音声ストリームの数を予測し、CODEC およびプロトコル オーバーヘッドに必要な帯域幅の合計を、その数に乗算する。

CODEC の選択では、CPU の消費というもう 1 つの要素も考慮する必要がある。通常、帯域幅の低い CODEC でさえ、200 MHz Pentium プロセッサであれば、音声ストリームのエンコードのためにリソースの約 8 %、デコードのためにさらに 4 % が必要である。ネットワークの帯域幅と同様に、CPU リソースの消費もストリーム数に応じて増加する。


自動ゲイン制御

Microsoft® DirectPlay® Voice には、できるだけ良好な録音入力レベルを提供するために、サウンド カード上のハードウェア入力音量を自動調整する機能が用意されている。自動ゲイン制御を有効にするには、クライアント構成を設定するときに、DVCLIENTCONFIG 構造体の dwFlags メンバに DVCLIENTCONFIG_AUTORECORDVOLUME フラグを設定する。自動ゲイン制御のアクティブ/非アクティブは、音声セッション内でいつでも切り替えることができる。

ゲーム アプリケーションでは、なるべく自動ゲイン制御を使用すること。自動ゲイン制御を使用すると、ゲーム リソースがほんの少し必要になるが、ゲーム内で録音音量を制御しないで済む。ユーザーは、わざわざレベル設定をせずに、高品質で音声を送受信することができる。


伝送制御

Microsoft® DirectPlay® Voice のパフォーマンス要件を抑えるには、ユーザーが話しているときにだけ、音声データを送信すればよい。音声データの伝送を制御するには、2 つの方法がある。使用すべき方法は、ゲームの設計要件によって異なる。

  • 音声をアクティブにする
  • プッシュツートーク


音声をアクティブにする

音声をアクティブにすることによる伝送制御では、マイク入力を常時分析することにより、ユーザーが話しているかどうかを判断する。音声をアクティブにするには 2 つの利点がある。ユーザーはマイクロフォンに話しかけるだけでよい。また、音声セッションの接続時に、DVCLIENTCONFIG 構造体の dwFlags パラメータを DVCLIENTCONFIG_AUTOVOICEACTIVATED に設定するだけで済むので、簡単にコーディングできる。


プッシュツートーク

プッシュツートーク伝送制御では、音声データを送信するタイミングを、ユーザーが積極的に選択する。この伝送制御方法を使用すると、音声以外のデータが送信される危険がない。この方法は、双方向無線機で [Talk] ボタンを押すのと同じであり、ある種のゲーム (対面型のシューティング ゲームなど) では、この機能によってリアリティが増す。この方法には、話すタイミングをユーザーが積極的に選択しなければならないため、同時に話すユーザーの数が減るという利点もある。ユーザー制御の機能が必要なため、この伝送制御は音声をアクティブにすることにより設計と開発に時間がかかる。


キャプチャ フォーカス

Microsoft® DirectPlay® Voice をサポートするロビー可能ゲーム アプリケーションとロビー アプリケーションを作成するには、フォーカスをキャプチャするという概念が不可欠である。ゲーム アプリケーションがフォーカス キャプチャを適切に実装していない場合、ロビー アプリケーションから起動されたときに、音声通信が機能しない可能性がある。

この点を説明するため、DirectPlay Voice をサポートするロビー アプリケーションで、2 人のプレーヤーが会う場合について考える。2 人のプレーヤーがゲームの開始に合意する。ゲームの開始後に、両方のプレーヤーのコンピュータでロビー アプリケーションがフォーカスを失い、ゲーム アプリケーションの各コピーがフォーカスを取得する。ゲーム アプリケーションがロビー アプリケーションから正しくフォーカスを取得しないと、ゲーム アプリケーションの実行中も、ロビー アプリケーションにフォーカスが残る可能性がある。

たとえば、ゲーム セッション実行中に、1 番目のプレーヤーのロビー アプリケーションがフォーカスを失わず、2 番目のプレーヤーのゲーム セッションがロビー アプリケーションからフォーカスを取得すると、この状況が発生する。2 番目のプレーヤーからは、1 番目のプレーヤーの音声セッションが半二重に戻ってしまったように見える。2 番目のプレーヤーには 1 番目のプレーヤーの声が聞こえるが、1 番目のプレーヤーには 2 番目のプレーヤーの声が聞こえない。1 番目のプレーヤーからは、2 番目のプレーヤーの声が聞こえないため、音声セッションが終了したように見える。また、1 番目のプレーヤーには、2 番目のプレーヤーに自分の声が聞こえていることがわからない。

この動作は、意図されたものである。同様の状況で、1 番目のプレーヤーがロビー アプリケーションからゲーム セッションを開始するときに、問題が発生してセッションを開始できない場合について考えてみよう。2 番目のプレーヤーのセッションが問題なく開始した場合には、2 番目のプレーヤーには 1 番目のプレーヤーの声が聞こえるため、1 番目のプレーヤーから 2 番目のプレーヤーにゲーム セッションの失敗を知らせることができる。そうすれば、両者ともロビーに戻り、セッションの開始をもう一度試すことができる。

キャプチャ フォーカスを適正に処理するには、ゲーム アプリケーションで、DVSOUNDDEVICECONFIG 構造体の hwndAppWindow パラメータを、ゲームの実行中にフォーカスを持つウィンドウ ハンドルに設定する必要がある。この結果、Connect を呼び出して DirectPlay Voice セッションを作成できるようになる。ゲーム アプリケーションでは次に、DVMSGID_LOSTFOCUS メッセージと DVMSGID_GAINFOCUS メッセージを処理する必要がある。

詳細については、｢フォーカス キャプチャの実装｣を参照すること。


ジッター バッファ

Microsoft® DirectPlay® Voice には、ジッター バッファという特徴的な機能がある。ジッター バッファは、最小限の遅延時間で最適な音質を提供する、柔軟なバッファリング アルゴリズムである。

混雑したネットワークでは、音声データ情報の各パケットが、ホスト コンピュータでエンコードされたときと異なった順序で届くことがある。音声データは本来連続したものなので、パケットが万一遅れても受信して順序よく再生するために、これらの流入パケットは、しばらくキューに入れておく必要がある。

音声通信の品質を最大にするようにジッター バッファを設定すると、必要な数の音声パケットが届き、再生用のキューに入るまでに、時間がかかる。このために音声が遅れ、音声通信をリアルタイムに聞くことができない。代わりに、音声データが聞こえるタイミングは、録音より数ミリ秒から数秒ほど遅れる可能性がある。プレーヤーが協力し合うゲームでは、この遅れによって問題が発生する。ゲーム内でイベントが発生したときに、プレーヤーがそれらのイベントに基づいてリアルタイムに情報をやり取りできないからである。たとえば、対面型のシューティング ゲームで、プレーヤーが背後から攻撃されそうになって仲間が警告しようとしても、攻撃されてしまうまで音声通信が聞こえない可能性がある。

遅延時間を減らすようにジッター バッファを設定すると、キューを一杯にするために必要なパケット数が少なくなる。ただしこの場合、連続パケットの一部が間に合わず、その結果、再生時にバッファ内に音声データが揃っていない可能性がある。音声通信が聞こえるタイミングは、実際の録音とほぼ一致している。ただしこの場合、音声が "こま切れ" で品質は低い。

DirectPlay ジッター バッファでは、最小限の遅延時間で最高品質の音声通信を提供する方法を、2 つの方法により判断する。最初に、ネットワークの状態を監視して、遅れや混雑状況を判断する。次に、音声の中断を最小限に抑えながら遅延時間を可能な限り短縮するため、ジッター バッファ (またはキュー) のサイズを動的に調整する。

DirectPlay Voice ジッター バッファは、ネットワークの状態に合わせて自動的に調整される (デフォルト動作の場合)。アルゴリズムでネットワークの状態をどの程度厳密に追跡するかは、DVCLIENTCONFIG 構造体の dwBufferAggressiveness メンバとdwBufferQuality メンバを使って手動で調整できる。"アグレッシブネス" のレベルを上げるほど、ネットワークの状態が厳密に監視される。通常、品質の値が高いほど、音質は上がるが遅延時間は長くなる。また、値が小さいほど、遅延時間は短くなるが音質は低下する。

アグレッシブネスのレベルは、ゲーム アプリケーション実行中のネットワーク状態に合わせて選択することが重要である。ネットワーク パフォーマンスが安定しているときに高レベルのアグレッシブネスが選択されていると、一時的な問題が誤まって解釈され、存在しないかもしれない問題が過剰に補正される可能性があるためである。


ワーキング セットについてのガイドライン

転送トポロジ、音声トポロジ、伝送制御、および CODEC の最適な構成は、開発するゲームの種類やジャンル、1 つのゲーム セッションに参加するプレーヤーの数、およびターゲットとなる接続の種類に基づいて判断する。

音声セッションに参加するプレーヤーの数は、ゲーム セッションに実際に参加するプレーヤーの数と等しいとは限らないので、注意が必要である。たとえば、対面型のシューティング ゲームを開発する場合には、ゲーム内で期限付きのパワーアップ アイテムとして提供される無線機や発信機で、音声通信を表現できる。無線機として表現すると、車内や移動しない司令部内にある無線機に、通信を制限できるという利点もある。

2 番目の例として、同時に 4 人がプレーするオンライン ブリッジ ゲームについて考えよう。ワーキング セットが小さいので、ピアツーピア ネットワーク トポロジ上でピアツーピア音声トポロジを転送する方法が適している。この小さなワーキング セットでは、伝送制御のモードとして、音声をアクティブにすることもできる。ピアツーピア音声トポロジは、実装が容易で、プレーヤーがサーバーの役割をしないでよい。4 人のプレーヤー全員が Voxware SC6 CODEC を使用すると、最大帯域幅は、CODEC のプロトコル オーバーヘッドを含め、スピーチ ストリームあたり 4.2 Kbps となる。さらに、ゲーム データに必要な帯域幅が無視できる程度に小さいとすると、話者それぞれの流出における最大の帯域幅要件は、残り 3 人へのストリーム 3 つ (つまり 12.6 Kbps) となる。また、流入における帯域幅は、どのクライアントでも 0 (残り 3 人が黙っているとき) ～ 12.6 Kbps (残り 3 人全員が話しているとき) となる。CPU は、エンコードのために 8 %、デコードのために 0 ～ 12 % が必要である。この結果、最悪の場合の要件は 25.2 Kbps となる。したがって、各プレーヤーは 14,400 ボー以上のモデムを使用する必要がある。

もう 1 つの例として、32 人までのプレーヤーが 2 チームに分かれて戦うチーム対戦型コンバット ゲームについて考える。ゲーム データには、28,800 ボーのモデムが必要なものとする。この例では、プレーヤー数が多いので、転送サーバー音声トポロジが適している。ここでも、プレーヤー全員が Voxware SC6 CODEC を使用するとすると、最大帯域幅は前述のブリッジ ゲームと同様に 4.2 Kbps となる。この例では、話しているときに 4.2 Kbps が流出し、チームからは最大 12.6 Kbps が流入する。CPU は、Pentium 200 であれば、エンコードのために 最大 8 %、受信のために最大 12 % が必要である。したがって、ゲーム データのための 28.8 Kbps と、大きくなった流入帯域幅 12.6 Kbps のために、各プレーヤーは 41,400 ボー以上のモデムを使用する必要がある。

転送サーバー自体にとって最悪のケースは、32 人が全員同時に話す場合であり、このときには 134.4 Kbps が必要になる。サーバーの CPU 使用量はごく限られている。これは、サーバーがストリームのエンコード/デコードを行わないためである。サーバーはストリームをリダイレクトするに過ぎない。通常は、16 人が同時に話すものとして、67.2 Kbps が必要になる。

ミキシング サーバー音声トポロジを選ぶ場合と、転送サーバー音声トポロジを選ぶ場合の差異を説明するため、ここでも前述のプレーヤー 32 人による対戦型コンバット ゲームについて考える。ミキシング サーバー音声トポロジを使用すると、各クライアントでは、送信のために 4.2 Kbps、受信のために 4.2 Kbps が必要になる。最悪の場合の帯域幅要件は、8.4 Kbps に下がる。また、CPU 要件は、200 MHz で動作する Pentium プロセッサの 12 % である。この結果、クライアントのモデム要件も 33,600 ボーに下がる。

サーバー側では、CPU 負荷が変わる。サーバーは、流入するストリームをすべてデコードおよび再エンコードし、必要に応じてストリームのミキシングも行う。ストリームをミキシングするための CPU 負荷は、比較的低いので無視する。最悪のケースは、同時に 32 のストリームをデコード/エンコードする場合である。この場合、音声サービス単独でも、400 MHz で動作する Pentium II プロセッサが最低限必要になる。


DirectPlay の使い方

Microsoft® DirectPlay® ドキュメントのこのセクションでは、マルチプレーヤー アプリケーションの重要な要素のいくつかを、DirectPlay API を使って実装する方法を説明する。

  • DirectPlay 列挙の使い方
  • プレーヤー コンテキスト値の使い方
  • ロビー クライアントの実装
  • ロビー可能アプリケーションの実装
  • Netmon を使った DirectPlay ネットワーク トラフィックの監視
  • DirectPlay と DirectPlay Voice におけるコールバック関数の実装
  • クリティカル セクション オブジェクトを使った DirectPlay ネットワーキング コールバックの実装
  • DirectPlay DPNSVR アプリケーションの使い方


DirectPlay 列挙の使い方

列挙とは、Microsoft® DirectPlay® がアプリケーションに情報を提供する方法の 1 つである。列挙は、いくつかの似通った要素についてデータを集めるために使用する。たとえば、セッション内の個々のプレーヤーに関する情報は、列挙を使って取得できる。列挙を実行するには、アプリケーションが DirectPlay にある種類の情報を照会し、DirectPlay が関連要素それぞれのデータ構造体を返す。通常、このデータは構造体の配列として返される。

多くのアプリケーションでは、列挙を少なくとも 1 回実行する必要があり、繰り返し実行しなければならない場合も少なくない。個々の DirectPlay インターフェイスでは、それぞれ異なる列挙セットがサポートされる。したがって、詳細はアプリケーションによって異なる。以下は、利用可能な列挙と、各種の列挙をサポートするインターフェイスの一覧である。

  • セッション ホスト (IDirectPlay8Peer、IDirectPlay8Client)
  • サービス プロバイダ (IDirectPlay8Peer、IDirectPlay8Client、IDirectPlay8Server)
  • プレーヤー (IDirectPlay8Peer、IDirectPlay8Server)
  • グループ (IDirectPlay8Peer、IDirectPlay8Server)
  • グループ メンバ (IDirectPlay8Peer、IDirectPlay8Server)
  • ローカル プログラム (IDirectPlay8LobbyClient)

詳細については、「DirectPlay 列挙の実装」を参照すること。


DirectPlay 列挙の実装

多くの Microsoft® DirectPlay® 列挙は、適切な列挙メソッドを呼び出し、返されるデータ配列を調べる、という標準パターンに従う。ホストの列挙は、このパターンに従わないので別に説明する。

データを取得するメソッドを呼び出す前に、返されるデータ ブロックを格納できるメモリを割り当てておく必要がある。ただし、事前には必要な配列の大きさがわからないことが多い。考えられるあらゆる配列を格納できるブロックを割り当てればよいが、効率的な方法ではない。代わりに、DirectPlay では、必要な配列サイズを照会してから、照会を繰り返して構造体自体を取得できる。

次の手順は、ピアツーピア ゲームのグループのメンバを列挙する方法の概要である。ホストの列挙を除き、ほかの種類の列挙もすべて同様の一般手順に従って行われる。列挙は、変化する情報のスナップショットを取得するために使用されることが多いため、ループ内で成功するまで実行しなければならない。

  1. IDirectPlay8Peer::EnumGroupMembers を呼び出す。このメソッドは、個々のグループ メンバの ID が入った整数配列を、prgdpnid パラメータに返す。pcdpnid パラメータは配列の要素数を指示するために使用する。適切な値を要求するには、pcdpnid パラメータを 0 に設定する。prgdpnid は NULL に設定する。
  2. メソッドから復帰したとき、pcdpnid は配列に格納される要素の数を指す。
  3. pcdpnid に返された値を使って使用する配列を割り当て、その配列を prgdpnid パラメータに割り当てる。
  4. pcdpnid を最初のメソッド呼び出しで返された値に設定する。
  5. もう一度 IDirectPlay8Peer::EnumGroupMembers を呼び出す。
  6. メソッドから再度復帰したら、戻り値を確認する。成功した場合、メソッドは S_OK を返し、配列にプレーヤーの ID が格納される。
  7. メソッドが再度 DPNERR_BUFFERTOOSMALL を返す場合は、直前の呼び出し以降にプレーヤー数が増えたことを示す。ステップ 3. に戻り、新しい pcdpnid 値を使って配列サイズを増やす。メモリ リークが起きないように注意すること。

メソッドが構造体の配列を返す場合もある。その場合、手順は同じだが、最初のメソッド呼び出しで返される値は、配列の要素数でなく、バイト数で表した配列サイズである。詳細については、各メソッドのリファレンスを参照すること。

詳細については、「ホストの列挙」を参照すること。


ホストの列挙

セッションを準備する 1 つの方法は、セッション ホストが利用可能になったことを本人に通知させることである。この種のセッションを、"ある要素を全要素にコピーするセッション" と言う。ピアまたはクライアントは、利用可能なホストを列挙し、1 つを選択し、接続要求を送信してそのゲームに参加することにより、参加するゲームを探すことができる。詳細については、「ピアツーピア セッション」または「クライアント/サーバー セッション」を参照すること。

ほかの列挙と異なり、利用可能なホストの要求に応答するために必要な情報は、ローカル コンピュータに記憶されていない。代わりに、クライアントまたはピアが要求を (たとえばローカル サブネット上で) 全要素にコピーし、利用可能なホストからの応答を待つ必要がある。一方、ホストは、これらの要求を待ってから適切に応答する必要がある。このように、自分がセッション メンバの候補かセッション ホストかによって、手順は微妙に異なる。

次の手順は、ピアツーピア セッションに利用可能なホストの列挙方法を示している。クライアント/サーバー セッション用の手順も、基本的にこれと同じである。IDirectPlay8Peer::EnumHosts は、列挙を開始するメソッドである。主要な設定パラメータは、pApplicationDesc、pdpaddrDeviceinfo、および pdpaddrHost である。

  1. プレーしたいゲームの GUID を DPN_APPLICATION_DESC 構造体の guidApplication メンバに割り当て、その構造体のポインタを pApplicationDesc パラメータに割り当てる。
  2. 対象のデバイスのアドレス オブジェクトを作成し、そのポインタを pdpaddrDeviceinfo に割り当てる。このオブジェクトには、ネットワーク接続の確立に必要な情報が格納されている。
  3. 利用可能なホストを特定のコンピュータに照会するには、そのコンピュータに対応するホスト アドレス オブジェクトを作成し、そのポインタを pdpaddrHost に割り当てる。このパラメータを NULL に設定すると、Microsoft® DirectPlay® は、pdpaddrDeviceinfo に格納された情報に基づいてアドレス オブジェクトを作成する。アドレス オブジェクトの詳細については、「DirectPlay アドレシング」を参照すること。通常、IP または IPX サービス プロバイダを使用している場合は、この結果、使用中のローカル サブネットへ照会はある要素を全要素にコピーする。DPNENUMHOSTS_OKTOQUERYFORADDRESSING フラグを設定すると、サービス プロバイダがユーザーにアドレス情報を要求するダイアログ ボックスを表示することがある。
  4. IDirectPlay8Peer::EnumHosts を呼び出す。
  5. この結果、コールバック メッセージ ハンドラに、応答するホストそれぞれにつき 1 つずつ一連の DPN_MSGID_ENUM_HOSTS_RESPONSE メッセージが届く。
    1. メッセージ ハンドラに返された情報を調べ、セッションを選択し、IDirectPlay8Peer::Connect を呼び出してそのセッションへの参加を要求する。

ある要素を全要素にコピーするセッションのホストとなるには、自分が利用可能なことを通知し、照会または接続要求を待つ。次の手順はピアツーピア ホストに適用されるが、クライアント/サーバー ホスト用の手順も基本的にこれと同じである。

  1. IDirectPlay8Peer::SetPeerInfo を呼び出して、プレーヤー用の静的な設定を指定する。
  2. DPN_APPLICATION_DESC 構造体に値を割り当てることにより、ゲームの構成を指定する。
  3. IDirectPlay8Peer::Host を呼び出して、自分がホストの候補であることを通知する。pdnAppDesc パラメータを、この前のステップで定義した DPN_APPLICATION_DESC 構造体に設定する。
  4. 列挙要求を待つ。列挙要求は、コールバック メッセージ ハンドラに送信される DPN_MSGID_ENUM_HOSTS_QUERY メッセージの形をとる。列挙要求に応答するには、DPN_APPLICATION_DESC の内容を設定し、S_OK を返す。その情報が付いた DPN_MSGID_ENUM_HOSTS_RESPONSE メッセージが、ピアに届く。
  5. ピアがセッションへの参加を決めると、DPN_MSGID_INDICATE_CONNECT メッセージが届く。

ゲームを準備および起動する方法の詳細については、「ピアツーピア セッション」および「クライアント/サーバー セッション」を参照すること。


プレーヤー コンテキスト値の使い方

多くのアプリケーションでは、個々のプレーヤーに何らかのデータを関連付けたいことがある。一方、プレーヤーに関連するメッセージを受信したときには、そのデータにすばやくアクセスするためにある種の手段が必要になる。プレーヤー コンテキスト値の目的は、プレーヤー データへの効率的なアクセス手段を提供することにある。

注 プレーヤー コンテキスト値を使用するのは、IDirectPlay8Peer インターフェイスおよび IDirectPlay8Server インターフェイスだけである。IDirectPlay8Client インターフェイスにプレーヤー コンテキスト値は必要ない。それは、クライアントが、ほかのクライアントとの通信ではなく、サーバーとの通信にだけこのインターフェイスを使用するからである。

  • プレーヤー コンテキスト値の定義
  • プレーヤー コンテキスト データの管理


プレーヤー コンテキスト値の定義

プレーヤー コンテキスト値を使用するには、使用中のシステムに、個々のプレーヤーに対応するデータ ブロックを、通常は構造体の形で保持する必要がある。プレーヤー コンテキスト値は、通常、各種プレーヤーのデータ ブロックを指すポインタ配列のインデックスである。プレーヤーからメッセージを受け取ったとき、テーブル内のプレーヤー ID を検索するといった時間のかかる処理をしないで済む。プレーヤー コンテキスト値に格納されたインデックスを使用すると、必要なポインタをすばやく取得できる。

プレーヤー コンテキスト値は、ゲームにプレーヤーが追加されたことを通知する DPN_MSGID_CREATE_PLAYER メッセージを処理するときに定義する。ホストも、DPN_MSGID_INDICATE_CONNECT メッセージを処理するときに、プレーヤー コンテキスト値を定義することがある。次の DPN_MSGID_CREATE_PLAYER メッセージには、そのプレーヤー コンテキスト値が設定される。ホストは、そのメッセージを処理するときに、プレーヤー コンテキスト値を変更できる。プレーヤー コンテキスト値を作成するには :

  • プレーヤーのデータを保持するための構造体を割り当てる。
  • プレーヤー データ配列にその構造体ポインタを追加する。
  • メッセージの DPNMSG_CREATE_PLAYER 構造体の pvPlayerContext メンバに、そのポインタのインデックスを割り当てる。

Microsoft® DirectPlay® では、データを取得して構造体に代入する方法が指定されていない。その問題は、個々のゲームで独自の方法により処理すること。

注 プレーヤー コンテキスト値は、DPN_MSGID_CREATE_PLAYER または DPN_MSGID_INDICATE_CONNECT メッセージ ハンドラ内でのみ定義できる。DPN_MSGID_CREATE_PLAYER メッセージ ハンドラから復帰すると、プレーヤー コンテキスト値が設定される。そのプレーヤーに関連する以降の各メッセージのプレーヤー コンテキスト値は、DPN_MSGID_CREATE_PLAYER メッセージ ハンドラが設定した値と等しい。関連するデータ構造体の内容は修正できるが、プレーヤー コンテキスト値自体は変更できない。


プレーヤー コンテキスト データの管理

プレーヤー コンテキスト値はごく簡単に取り扱えるが、注意する点がいくつかある。

プレーヤー コンテキスト値は、メッセージが届くたびにアクセスできると思われる有効なメモリ アドレスを、簡単に取得する手段である。ただし、アプリケーション内の異なった部分から、データのアクセスを同時に行わないように注意する必要がある。Microsoft® DirectPlay® では、特定のプレーヤーに関連するメッセージが逐次化されている。このため、同じプレーヤーからのメッセージを 2 つ同時に取り扱う状況は発生しない。データ構造体は、コールバック メッセージ ハンドラからアクセスする限り、安全にアクセスできる。ただし、多くのアプリケーションでは、メッセージ ハンドラ以外からプレーヤー データにアクセスする必要がある。

コールバック メッセージ ハンドラ以外からデータにアクセスするアプリケーションでは、構造体をロックするある種のグローバルなメカニズムを用意して、同時アクセスを避けなければならない。開発の初期にはそのようなロック メカニズムが必要ないとしても、必要になる場合を想定して初めから組み込んでおいた方がよい。プレーヤー コンテキスト値が配列のインデックスである場合は、その配列を安全に読み取り、更新することにも注意しなければならない。

プレーヤーのデータ構造体の割り当てを誤って早く解除しないこと。プレーヤーがゲームを抜けるときは、通常、プレーヤーのデータ構造体の割り当てを解除し、関連するメモリを解放する必要がある。ただし、DPN_MSGID_DESTROY_PLAYER メッセージを受け取ってすぐ構造体の割り当てを解放する場合には注意が必要である。コールバック メッセージ ハンドラ以外から構造体にアクセスするアプリケーションでは、メッセージが届いたときに、そのデータがまだ使用されている可能性がある。メッセージが届いたからといって、すぐに構造体の割り当てを解除すると、アプリケーションのほかの部分が失敗することがある。

誤って早く構造体の割り当てを解除することを避けるには、アプリケーションレベルのロック メカニズムを用意するだけでなく、ある種の参照カウントを実装するとよい。構造体を作成するとき、および構造体を使用するたびに、参照カウントをインクリメントする。DPN_MSGID_DESTROY_PLAYER メッセージ ハンドラを含め、構造体を使い終わるたびに、参照カウントをデクリメントする。参照カウントが 0 でない限り、構造体はアプリケーションのどこかからアクセスされている。参照カウントが 0 に戻るまで、構造体の割り当てを解除しないこと。


ロビー クライアントの実装

ロビー クライアントとは、ユーザーのコンピュータに常駐するアプリケーションである。主な役割は、ユーザーのコンピュータにあるゲーム アプリケーションと、リモート コンピュータにあるロビー サーバーをリンクすることにある。ただし、ロビー クライアントは、スタンドアロン アプリケーションとしても機能する。たとえば、特定の LAN サブネットのユーザーによるゲーム セッションは、これらを使って準備できる。

ロビー クライアントは、通常、以下の作業をする 3 つの主要コンポーネントから構成される。

  • 外部 (ロビー サーバーまたはほかのロビー クライアント) との通信。
  • ユーザーとの通信。主にグラフィカル ユーザー インタフェース (GUI) を使用する。
  • Microsoft® DirectPlay® との通信。

DirectPlay では、前の 2 項目の実装方法が指定されていない。ロビー クライアント ベンダーが、個々の製品に適した方法で実装しなければならない。DirectPlay は、DirectPlay と通信し、ユーザーのロビー可能なゲーム アプリケーションと DirectPlay を通じて通信するために、ロビー クライアントが使用できる標準 API を提供する。

ここでは、ロビー クライアントの実装に関する以下の重要な項目について説明する。

  • ロビー クライアントの初期化
  • ロビー対象アプリケーションの起動
  • ロビー クライアント メッセージ ハンドラの実装
  • ロビー対象アプリケーションとの通信
  • ロビー クライアントの終了

簡単なロビー クライアントの完全な実装例については、サンプル アプリケーション LobbyClient を参照すること。


ロビー クライアントの初期化

ロビー クライアントは、ロビー サーバーが起動するか、ユーザーが直接起動する。ロビー クライアントは、起動しても、初期化されるまでアプリケーションを起動できない。初期化には、以下の作業が必要になる。

  • CoCreateInstance を呼び出して、ロビー クライアント オブジェクト (CLSID_DirectPlay8LobbyClient) を作成する。riid パラメータを使って、IDirectPlay8LobbyClient インターフェイス (IID_IDirectPlay8LobbyClient) を要求する。
  • ロビー クライアントの IDirectPlay8LobbyClient::Initialize メソッドを呼び出す。ロビー クライアントのコールバック メッセージ ハンドラへのポインタを、メソッドに渡す。
  • IDirectPlay8LobbyClient::EnumLocalPrograms メソッドを使って、ユーザーのシステムにあるロビー可能なアプリケーションを列挙する。

前の 2 つのステップで、ロビー クライアント オブジェクトを作成し、そのオブジェクトとロビー クライアントの間に通信リンクを設定する。最後のステップで、ユーザーのシステムで利用できるロビー可能なアプリケーションを判断する。この情報は、選択されたアプリケーションを起動するために必要である。

次のサンプル コードは、ローカル アプリケーションの列挙方法を示している。これは、SDK のサンプル LobbyClient にある EnumRegisteredApplications 関数を簡略化したものである。わかりやすくするため、エラー処理およびダイアログ ボックス関連のコードが削除されている。完全なコードについては、SDK のサンプル LobbyClient を参照すること。

HRESULT EnumRegisteredApplications()
{
    HRESULT hr;
    DWORD   dwSize     = 0;
    DWORD   dwPrograms = 0;
    DWORD   iProgram;
    BYTE*   pData   = NULL;

//g_pLobbyClient は、IDirectPlay8LobbyClient インターフェイスへのポインタ。
//最初は NULL データ バッファ。必要なバッファ サイズは
//dwSize.で返される。
  hr = g_pLobbyClient->EnumLocalPrograms( NULL, pData, &dwSize, &dwPrograms, 0 );

  if( dwSize == 0 )
  {
//登録済みアプリケーションはない。
  }
//データ バッファを適切なサイズに設定する。
  pData = new BYTE[dwSize];
  hr = g_pLobbyClient->EnumLocalPrograms( NULL, pData, &dwSize, &dwPrograms, 0 )

//返されたデータを適切な構造体型にキャストする。
  DPL_APPLICATION_INFO* pAppInfo = (DPL_APPLICATION_INFO*) pData;

//登録済みアプリケーションの名前を列挙する。
  for( iProgram=0; iProgram<dwPrograms; iProgram++ )
  {
    TCHAR strAppName[MAX_PATH];
    DXUtil_ConvertWideStringToGeneric( strAppName, pAppInfo->pwszApplicationName );

  }
  SAFE_DELETE_ARRAY( pData );
  return S_OK;
}

登録済みアプリケーションのアプリケーション GUID は、アプリケーションの起動に必要なので、保存しなければならない。

ロビー クライアントの設計によっては、以下の作業のいくつかを実行する必要がある。

  • ロビー サーバーとのリンク確立など、Microsoft® DirectPlay® と関係のない初期化を実行する。
  • DirectPlay ピア オブジェクト (CLSID_DirectPlay8Peer) または DirectPlay クライアント オブジェクト (CLSID_DirectPlay8Client) を作成する。
  • ピア オブジェクトまたはクライアント オブジェクトの列挙メソッドを使って、利用可能なサービス プロバイダ、アダプタなどを列挙する。


ロビー対象アプリケーションの起動

ユーザーがアプリケーションを選択し、ユーザーのシステムにそのアプリケーションが登録されていることをロビー クライアントが確認すると、アプリケーションを起動できるようになる。これには、IDirectPlay8LobbyClient::ConnectApplication を呼び出す。最初のパラメータは、アプリケーションの起動に必要な各種の情報 (以下を含む) が格納された DPL_CONNECT_INFO 構造体である。

  • アプリケーションを識別する GUID。
  • 接続の設定 (ユーザーの Microsoft® DirectPlay® アドレスを含む)。DirectPlay アドレスの詳細については、「DirectPlay アドレシング」を参照すること。
  • アプリケーションがホストとなるかどうか。

IDirectPlay8LobbyClient::ConnectApplication メソッドは、以降のすべての通信でアプリケーションの識別に使用するアプリケーション ハンドルを返す。アプリケーションが起動し、接続の確立が成功すると、メッセージ ハンドラに DPL_MESSAGE_CONNECT メッセージが届く。

注 IDirectPlay8LobbyClient::ConnectApplication メソッドが成功コードを返して接続を確認する前に、メッセージ ハンドラに DPL_MESSAGE_CONNECT が届くことがある。メッセージ ハンドラは、メソッドから復帰していなくても、メッセージを処理できなければならない。


ロビー クライアント メッセージ ハンドラの実装

メッセージ ハンドラは、ロビー クライアント オブジェクトがロビー クライアントとの通信に使用するコールバック関数である。ロビー クライアント メッセージ ハンドラには、以下の情報を渡す 3 つのパラメータがある。

  • メッセージ タイプを示すメッセージ ID。
  • メッセージ データ ブロックへのポインタ。このパラメータは、各メッセージが使用する構造体にキャストする必要がある。
  • アプリケーションで定義されたユーザーコンテキストのデータ ブロック (省略可能) へのポインタ。

ユーザー コンテキスト値は、IDirectPlay8LobbyClient::Initialize を呼び出すときにロビー クライアントが定義する。ユーザー コンテキスト値は、別々のオブジェクトから送信されたメッセージを区別する目的などに使用できる。メッセージ ハンドラ関数の完全な記述については、「PFNDPNMESSAGEHANDLER」を参照すること。

メッセージ ハンドラは、ロビー クライアント固有の以下の 5 つのメッセージを処理できなければならない。

  • DPL_MESSAGE_CONNECT
  • DPL_MESSAGE_CONNECTION_SETTINGS
  • DPL_MESSAGE_DISCONNECT
  • DPL_MESSAGE_RECEIVE
  • DPL_MESSAGE_SESSION_STATUS

これらのメッセージの大半は、ゲームの状態が変化したとき、またはロビー クライアントが情報を要求したときに、ロビー クライアント オブジェクトが生成する。ただし、DPL_MESSAGE_RECEIVE は例外である。このメッセージは、ゲーム アプリケーションからロビー クライアントにデータを直接渡すために使用される。

注 Microsoft® DirectPlay® メッセージ ハンドラは、マルチスレッド環境で適切に動作するように書かれている必要がある。そのように書かれてないと、アプリケーションが正常に機能しない可能性がある。

DPL_MSGID_CONNECT

このメッセージは、ロビー可能なアプリケーションの起動後に、ロビー クライアントが送信する。このメッセージは、アプリケーションの接続が成功したことを示す。関連する DPL_MESSAGE_CONNECT 構造体には、以下を含む各種の情報が保持される。

  • 接続 ID。ロビー クライアントが、IDirectPlay8LobbyClient::Send でアプリケーションにデータを送信するか、または IDirectPlay8LobbyClient::ReleaseApplication で接続を解放する必要があるときは、この ID を使用する。
  • ロビー接続データ。
  • 接続コンテキスト値 (省略可能)。

DPL_MSGID_CONNECTION_SETTINGS

このメッセージは、関連付けられたロビー可能なアプリケーションから、セッションの接続を修正するために IDirectPlay8LobbiedApplication::SetConnectionSettings メソッドが呼び出されるたびに、DirectPlay が送信する。関連付けられた DPL_MESSAGE_CONNECTION_SETTINGS 構造体には、更新済みの接続情報が格納される。

DPL_MSGID_DISCONNECT

このメッセージは、ロビー可能なアプリケーションが IDirectPlay8LobbiedApplication::Close を呼び出してセッションを抜けるときに、送信される。ロビー クライアント アプリケーションでは、接続をそのリストから削除し、アプリケーションに関連付けられたデータをすべて解放しなければならない。

DPL_MSGID_RECEIVE

このメッセージを使用すると、アプリケーションからロビー クライアントにデータを渡すことができる。DirectPlay は、アプリケーションからロビー クライアントに、DPL_MESSAGE_RECEIVE 構造体を使ってデータ ブロックを渡す。このデータの処理は、ロビー クライアントが行わなければならない。

DPL_MSGID_SESSION_STATUS

このメッセージは、セッションの状態に以下の 6 つの変化のいずれかが発生するたびに、DirectPlay が送信する。

  • セッションが接続された。
  • セッションが接続できない。
  • セッションが切断された。
  • セッションが終了した。
  • セッション ホストが移行した。
  • このコンピュータがセッション ホストになった。

状態変化の種類は、関連付けられた DPL_MESSAGE_SESSION_STATUS 構造体にある dwStatus フィールドの値によって示される。

詳細については、「ロビー クライアント メッセージ ハンドラのサンプル」を参照すること。


ロビー クライアント メッセージ ハンドラのサンプル

次のコードは、SDK のサンプル LobbyClient にあるメッセージ ハンドラを簡略化したものである。わかりやすくするため、エラー処理コードが削除されている。完全なコードについては、上記サンプルを参照すること。

HRESULT WINAPI DirectPlayLobbyMessageHandler( PVOID pvUserContext,
                                              DWORD dwMessageId,
                                              PVOID pMsgBuffer )
{
  switch( dwMessageId )
  {
    case DPL_MSGID_DISCONNECT:
    {
      PDPL_MESSAGE_DISCONNECT pDisconnectMsg;
      pDisconnectMsg = (PDPL_MESSAGE_DISCONNECT)pMsgBuffer;

      // アプリケーションに関連付けられたデータをすべて解放し、
      // リストから接続を削除する。
      break;
    }
    case DPL_MSGID_RECEIVE:
    {
      PDPL_MESSAGE_RECEIVE pReceiveMsg;
      pReceiveMsg = (PDPL_MESSAGE_RECEIVE)pMsgBuffer;

      // ロビー アプリケーションがデータを送信した。データを処理し、
      // 適切に応答する。
      break;
    }
    case DPL_MSGID_SESSION_STATUS:
    {
      PDPL_MESSAGE_SESSION_STATUS pStatusMsg;
      pStatusMsg = (PDPL_MESSAGE_SESSION_STATUS)pMsgBuffer;

      switch( pStatusMsg->dwStatus )
      {
        case DPLSESSION_CONNECTED://セッションが接続された。
          break;
        case DPLSESSION_COULDNOTCONNECT://セッションが接続できない。
          break;
        case DPLSESSION_DISCONNECTED://セッションが切断された。
          break;
        case DPLSESSION_TERMINATED://セッションが終了した。
          break;
        case DPLSESSION_HOSTMIGRATED://ホストが移行した。
          break;
        case DPLSESSION_HOSTMIGRATEDHERE://ホストがここに移行した。
          break;
      }
      case DPL_MSGID_CONNECTION_SETTINGS:
      {
        PDPL_MESSAGE_CONNECTION_SETTINGS pConnectionStatusMsg;
        pConnectionStatusMsg = (PDPL_MESSAGE_CONNECTION_SETTINGS)pMsgBuffer;
        // アプリケーションが接続の設定を変更した。
        break;
      }
  }
  return S_OK;
}


ロビー対象アプリケーションとの通信

ロビー クライアントと関連するアプリケーションのやり取りの大半は、間接的に行われる。ロビー クライアントがアプリケーションに影響する何らかの処理を実行 (または逆にアプリケーションがロビー クライアントに影響する何らかの処理を実行) すると、Microsoft® DirectPlay® が適切なメッセージを送信する。たとえば、ロビー クライアントが接続の設定を変更すると、DirectPlay がアプリケーションに通知し、新しい設定内容を提供する。ただし、IDirectPlay8LobbyClient::Send メソッドを使用すれば、ロビー クライアントからアプリケーションにメッセージを直接送信することができる。DirectPlay はアプリケーションにデータをそのまま渡す。そのデータの処理は、アプリケーションが行わなければならない。

ロビー対象アプリケーションも、ロビー クライアントにデータを直接送信することができる。データは、ロビー クライアントのメッセージ ハンドラに、DPL_MSGID_RECEIVE メッセージで渡される。DirectPlay はロビー クライアントにデータをそのまま渡す。このデータの処理は、ロビー クライアントが行わなければならない。


ロビー クライアントの終了

セッションを終了する準備ができたら、IDirectPlay8LobbyClient::ReleaseApplication を呼び出してアプリケーションを切断する。アプリケーションに、DPL_MSGID_DISCONNECT メッセージが届く。

アプリケーションを解放したら、必要に応じてクリーンアップを実行し、IDirectPlay8LobbyClient::Close を呼び出してセッションを閉じる。次に、IDirectPlay8LobbyClient::Release を呼び出して、ロビー クライアント オブジェクトを解放しなければならない。


ロビー可能アプリケーションの実装

ロビー可能アプリケーションは、ロビー クライアントと正しく連動するように設計される必要がある。ロビー クライアントは任意のアプリケーションを起動できるが、Microsoft® DirectPlay® からのメッセージ、およびロビー クライアントからのメッセージを受け取れるのは、"ロビー起動" アプリケーションだけである。ロビー起動されるアプリケーションは、適切に登録されていて、DirectPlay ロビー対象アプリケーション オブジェクトを使って、DirectPlay およびロビー クライアントと通信できなければならない。

ここでは、ロビー可能アプリケーションの実装方法について説明する。

  • ロビー可能アプリケーションの登録
  • ロビー起動の取り扱い
  • ロビー対象アプリケーション コールバック メッセージ ハンドラの実装
  • ロビー クライアントとの通信
  • ロビー対象アプリケーションの終了


ロビー可能アプリケーションの登録

ロビー可能アプリケーションをロビー起動するには、事前に登録する必要がある。この登録は、1 回だけ実行される必要があり、通常はアプリケーションのセットアップ手順に含まれる。アプリケーションをロビー可能アプリケーションとして登録するため、レジストリを直接修正しようとしてはならない。代わりに、以下の処理を実行する。

  • CoCreateInstance を呼び出して、ロビー対象アプリケーション オブジェクト (CLSID_DirectPlay8LobbiedApplication) を作成する。riid パラメータを IID_IDirectPlay8LobbiedApplication に設定して、IDirectPlay8LobbiedApplication インターフェイスを要求する。
  • IDirectPlay8LobbiedApplication::RegisterProgram を呼び出す。このメソッドは、情報を受け取り、適切なレジストリのキーと値を作成する。

IDirectPlay8LobbiedApplication::RegisterProgram には、以下を含む各種の情報を提供する必要がある。

  • アプリケーションの識別に使用する GUID。
  • アプリケーションのフレンドリ名。
  • アプリケーションの実行ファイルの場所と名前。
  • "ランチャ" アプリケーション (省略可能) の場所と名前。
  • 起動時に実行ファイルに渡さなければならないコマンドライン引数。

Microsoft® DirectPlay® は、ゲーム アプリケーションではなく、ランチャ アプリケーションを起動する。次に、ランチャ アプリケーションがゲームを起動する。ランチャ アプリケーションは、たとえば違法コピー対策として使用できる。

プログラムの登録を解除するには、IDirectPlay8LobbiedApplication::UnregisterProgram を呼び出す。このメソッドは、IDirectPlay8LobbiedApplication::RegisterProgram で作成されたレジストリ エントリを削除する。


ロビー起動の取り扱い

ロビー可能アプリケーションが起動されたときにまず実行しなければならないのは、Microsoft® DirectPlay® ロビー対象アプリケーション オブジェクトの作成および初期化である。これには、以下の処理を実行する。

  • CoCreateInstance を呼び出して、ロビー対象アプリケーション オブジェクト (CLSID_DirectPlay8LobbiedApplication) を作成する。riid パラメータを IID_IDirectPlay8LobbiedApplication に設定して、IDirectPlay8LobbiedApplication インターフェイスを要求する。
  • IDirectPlay8LobbiedApplication::Initialize を呼び出して、ロビー対象アプリケーション オブジェクトを初期化する。ロビー対象アプリケーションのコールバック メッセージ ハンドラへのポインタを、オブジェクトに渡す。

次に、アプリケーションがロビー起動されたかどうかを判断する。ロビー起動されている場合は、セッションを効率よく管理するために、アプリケーションで DirectPlay との通信チャネルを設定する必要がある。アプリケーションがロビー起動されたかどうかを判断するには、以下の処理を実行する。

  • IDirectPlay8LobbiedApplication::Initialize メソッドから復帰したときに、pdpnhConnection パラメータを調べる。このパラメータが有効な接続ハンドルに設定されている場合、ゲームはロビー起動されている。
  • メッセージ ハンドラを通じて受け取った DPL_MSGID_CONNECT メッセージを調べる。このメッセージには、ロビー クライアントにメッセージを送信するときに使用する ID を含む、各種の情報が付属している。

注 IDirectPlay8LobbiedApplication::Initialize メソッドから復帰する前に、メッセージ ハンドラに DPL_MSGID_CONNECT メッセージが届くことがある。メッセージ ハンドラは、このメッセージを適切に処理する用意ができていなければならない。

アプリケーションがロビー起動されていない場合は、IDirectPlay8LobbiedApplication::SetAppAvailable を呼び出すと、ロビー クライアントからアプリケーションに接続可能であることを示すことができる。このメソッドは、通常、ユーザーがアプリケーションを起動したときに呼び出される。ただし、ユーザーが 1 つのセッションを閉じたが、アプリケーションがまだ動作していて、別のセッションで利用可能な場合にも、このメソッドを使用することができる。どちらの場合も、ロビー クライアントがアプリケーションをセッションに接続すると、メッセージ ハンドラに DPL_MSGID_CONNECT メッセージが届く。

次のサンプル コードは、ロビー対象アプリケーションの初期化方法、およびアプリケーションがロビー起動されているかどうかを判断する方法を示している。これは、SDK の SimplePeer アプリケーションで使用される InitDirectPlay 関数を簡略化したものである。完全なコードについては、上記サンプル アプリケーションを参照すること。わかりやすくするため、主にエラー処理コードが削除されている。g_bWasLobbyLaunched はグローバル変数であり、アプリケーションがロビー起動されている場合に TRUE に設定される。

HRESULT InitDirectPlay()
{
  DPNHANDLE hLobbyLaunchedConnection = NULL;
  HRESULT hr;

  // IDirectPlay8LobbiedApplication を作成する。
  hr = CoCreateInstance( CLSID_DirectPlay8LobbiedApplication, NULL,
                         CLSCTX_INPROC_SERVER,
                         IID_IDirectPlay8LobbiedApplication,
                         (LPVOID*) &g_pLobbiedApp );

  // IDirectPlay8LobbiedApplication を初期化する。
  hr = g_pLobbiedApp->Initialize( NULL,
                                  DirectPlayLobbyMessageHandler,
                                  &hLobbyLaunchedConnection,
                                  0 );
  //有効な接続ハンドルがないか調べる。NULL でない場合
  //アプリケーションはロビー起動されている。
  g_bWasLobbyLaunched = ( hLobbyLaunchedConnection != NULL );

  return S_OK;
}


ロビー対象アプリケーション コールバック メッセージ ハンドラの実装

メッセージ ハンドラは、ロビー対象アプリケーション オブジェクトがロビー対象アプリケーションとの通信に使用するコールバック関数である。ロビー対象アプリケーション メッセージ ハンドラには、以下の情報を渡す 3 つのパラメータがある。

  • メッセージ タイプを示すメッセージ ID。
  • メッセージ データ ブロックへのポインタ。このパラメータは、各メッセージが使用する構造体にキャストする必要がある。
  • アプリケーションで定義されたユーザー コンテキストのデータ ブロック (省略可能) へのポインタ。

ユーザー コンテキスト値は、IDirectPlay8LobbyClient::Initialize を呼び出すときにロビー クライアントが定義する。ユーザー コンテキスト値は、別々のオブジェクトから送信されたメッセージを区別する目的などに使用できる。メッセージ ハンドラ関数の完全な記述については、「PFNDPNMESSAGEHANDLER」を参照すること。

メッセージ ハンドラは、ロビー対象アプリケーション固有の以下の 4 つのメッセージを処理できなければならない。

  • DPL_MESSAGE_CONNECT
  • DPL_MESSAGE_CONNECTION_SETTINGS
  • DPL_MESSAGE_DISCONNECT
  • DPL_MESSAGE_RECEIVE

これらのメッセージの大半は、接続が変化したとき、またはロビー対象アプリケーションが接続情報を要求したときに、ロビー対象アプリケーション オブジェクトが生成する。ただし、DPL_MESSAGE_RECEIVE は例外である。このメッセージは、ロビー クライアントからゲーム アプリケーションにデータを直接渡すために使用される。

注 Microsoft® DirectPlay® メッセージ ハンドラは、マルチスレッド環境で適切に動作するように書かれている必要がある。そのように書かれてないと、アプリケーションが正常に機能しない可能性がある。

DPL_MSGID_CONNECT

このメッセージは、ロビー クライアントがアプリケーションをセッションに接続するために IDirectPlay8LobbyClient::ConnectApplication を呼び出したときに、ロビー対象アプリケーション オブジェクトが送信する。関連付けられた DPL_MESSAGE_CONNECT 構造体には、以下の情報が含まれる。

  • 接続 ID。アプリケーションが、IDirectPlay8LobbiedApplication::Send でロビー クライアントにデータを送信するか、または IDirectPlay8LobbiedApplication::UpdateStatus でセッションの状態を更新する必要があるときは、この ID を使用する。
  • ロビー接続データ。
  • 接続コンテキスト値 (省略可能)。

DPL_MSGID_CONNECTION_SETTINGS

DirectPlay は、関連付けられたロビー クライアントから、セッションの接続を修正するために IDirectPlay8LobbyClient::SetConnectionSettings メソッドが呼び出されるたびに、このメッセージを送信する。関連付けられた DPL_MESSAGE_CONNECTION_SETTINGS 構造体には、更新済みの接続情報が格納される。

DPL_MSGID_DISCONNECT

このメッセージは、ロビー クライアントが IDirectPlay8LobbyClient::ReleaseApplication を呼び出してアプリケーションをセッションから切断するときに、送信される。アプリケーションでは、接続をそのリストから削除し、セッションに関連付けられたデータをすべて解放しなければならない。

DPL_MSGID_RECEIVE

このメッセージを使用すると、ロビー クライアントからアプリケーションにデータを渡すことができる。DirectPlay は、ロビー クライアントからアプリケーションに、DPL_MESSAGE_RECEIVE 構造体を使ってデータ ブロックを渡す。このデータの処理は、アプリケーションが行わなければならない。

詳細については、「ロビー対象アプリケーション メッセージ ハンドラのサンプル」を参照すること。


ロビー対象アプリケーション メッセージ ハンドラのサンプル

次のコードは、SDK のサンプル SimplePeer にあるメッセージ ハンドラを簡略化したものである。わかりやすくするため、エラー処理コードが削除されている。完全なコードについては、上記サンプルを参照すること。

HRESULT WINAPI DirectPlayLobbyMessageHandler( PVOID pvUserContext,
                                              DWORD dwMessageId,
                                              PVOID pMsgBuffer )
{
  switch( dwMessageId )
  {
    case DPL_MSGID_CONNECT:
    {
      PDPL_MESSAGE_CONNECT pConnectMsg;
      pConnectMsg = (PDPL_MESSAGE_CONNECT)pMsgBuffer;

      // 接続された。セッションを開始する。
      break;
    }
    case DPL_MSGID_DISCONNECT:
    {
      PDPL_MESSAGE_DISCONNECT pDisconnectMsg;
      pDisconnectMsg = (PDPL_MESSAGE_DISCONNECT)pMsgBuffer;

      // 切断された。ロビー クライアントに関連付けられた
      // データを解放する。
      break;
    }
    case DPL_MSGID_RECEIVE:
    {
      PDPL_MESSAGE_RECEIVE pReceiveMsg;
      pReceiveMsg = (PDPL_MESSAGE_RECEIVE)pMsgBuffer;

      // ロビー クライアントがデータを送信した。データを処理し、
      // 適切に応答する。
      break;
    }

    case DPL_MSGID_CONNECTION_SETTINGS:
    {
      PDPL_MESSAGE_CONNECTION_SETTINGS pConnectionStatusMsg;
      pConnectionStatusMsg = (PDPL_MESSAGE_CONNECTION_SETTINGS)pMsgBuffer;

      // ロビー クライアントが接続の設定を変更した。
      break;
    }
  }
  return S_OK;
}


ロビー クライアントとの通信

ロビー対象アプリケーションと関連するロビー クライアントのやり取りの大半は、間接的に行われる。アプリケーションがロビー クライアントに影響する何らかの処理を実行 (または逆にロビー クライアントがアプリケーションに影響する何らかの処理を実行) すると、Microsoft® DirectPlay® が適切なメッセージを送信する。たとえば、アプリケーションが接続の設定を変更すると、DirectPlay がロビー クライアントに通知し、新しい設定内容を提供する。ただし、ロビー クライアントに情報を直接提供するため、以下の 2 つのメソッドも用意されている。IDirectPlay8LobbiedApplication::UpdateStatus および IDirectPlay8LobbiedApplication::Send。

ゲームの状態に以下の変化のいずれかが発生したときには、ロビー クライアントに通知する必要がある。

  • セッションが接続された。
  • セッションが接続できない。
  • セッションが切断された。
  • セッションが終了した。
  • セッション ホストが移行した。
  • このコンピュータがセッション ホストになった。

ロビー クライアントにこれらの状態変化のいずれかを通知するには、IDirectPlayLobbiedApplication::UpdateStatus を呼び出し、dwStatus パラメータを適切な値に設定する。状態の変化を知らせる DPL_MSGID_SESSION_STATUS メッセージが、ロビー クライアントに届く。

IDirectPlay8LobbiedApplication::Send メソッドを使用すると、アプリケーションからロビー クライアントにメッセージを直接送信することができる。DirectPlay はロビー クライアントにデータをそのまま渡す。そのデータの処理は、ロビー クライアントが行わなければならない。

ロビー クライアントも、アプリケーションにデータを直接送信することができる。データは、ロビー クライアントのメッセージ ハンドラに、DPL_MSGID_RECEIVE メッセージで渡される。DirectPlay はアプリケーションにデータをそのまま渡す。ロビー クライアントは、このデータを処理しなければならない。


ロビー対象アプリケーションの終了

セッションを閉じるには、IDirectPlay8LobbiedApplication::Close を呼び出す。切断を知らせる DPL_MSGID_DISCONNECT メッセージが、ロビー クライアントに届く。アプリケーションを引き続き実行し、別のセッションに接続するには、IDirectPlay8LobbiedApplication::SetAppAvailable を呼び出して、アプリケーションが利用可能であることを示す。それ以外の場合は、IDirectPlay8LobbiedApplication::Release を呼び出してロビー対象アプリケーション オブジェクトを解放し、アプリケーションを終了する。


Netmon を使った DirectPlay ネットワーク トラフィックの監視

ゲームの開発中 (特にバグを解析しているとき) には、Microsoft® DirectPlay® のネットワーク トラフィックを監視すると役立つことがある。ネットワーク モニタ (Netmon) は、ネットワーク トラフィックを分析するための標準ユーティリティである。DirectPlay メッセージングの 4 つのコンポーネント (サービス プロバイダ レイヤ、トランスポート レイヤ、セッション レイヤ、および音声レイヤ) を分析するため、DirectPlay には Netmon を使った一連のパーサーが用意されている。

  • Netmon と DirectPlay の連動
  • DirectPlay 向け Netmon の構成
  • DirectPlay ネットワーク トラフィックのキャプチャ
  • DirectPlay で Netmon を使用するためのヒント


Netmon と DirectPlay の連動

Microsoft® DirectPlay® のプロトコル スタックには、3 つの基本レイヤがある。

  • 音声レイヤとセッション レイヤは、スタックの最上位レベルを共有する。通常のメッセージングはセッション レイヤを通り、音声関連のメッセージングは音声レイヤを通る。
  • トランスポート レイヤは、スタックの中位にある。音声とセッションのトラフィックは、どちらもこのレイヤを通る。メッセージの分割と再構成や、消失したパケットの再転送などの作業は、このレイヤが担当する。
  • サービス プロバイダ レイヤは、スタックの一番下にある。すべてのメッセージングはこのレイヤで処理される。ネットワークとの通信は、このレイヤが担当する。たとえば、TCP/IP ネットワーキングの場合、サービス プロバイダは Winsock API を使ってネットワーク スタックと通信を行う。Netmon で解析できるネットワーク トラフィックは、IP または IPX サービス プロバイダ上を通るものに限られている。

DirectPlay パーサーをインストールすると、Netmon を使って、これら 4 つのレイヤのいずれかを通るネットワーク トラフィックを分析できる。サービス プロバイダ パーサーを選択すると、DirectPlay の全トラフィックを表示できる。また、上位レベルのパーサーのいずれかを選択すれば、興味のないトラフィックを除外することができる。

トランスポート レイヤ パーサーを使用すると、音声とセッションの全トラフィックが表示され、接続のためのハンドシェイクといった下位レベルのトラフィックは除外される。トランスポート レイヤでは、MTU (Maximum Transfer Unit) より長いメッセージが 1 つ以上の断片に分解されるので、注意すること。

セッション レイヤ パーサーと音声レイヤ パーサーを使用すると、セッション関連のトラフィックと音声関連のトラフィックを別々に分析できる。これらのパーサーは、どちらも分割を検知し、ユーザーに知らせるようになっているが、分割したパケットを分析することはできない。


DirectPlay 向け Netmon の構成

Windows 2000 Server システムを使用している場合、Netmon は既にインストールされている。Windows 2000 Professional の場合は、SMS (Systems Management Server) を購入する必要がある。Netmon の基本的な使い方については、Netmon のドキュメントを参照すること。Microsoft® DirectPlay® のトラフィックを監視するために Netmon を構成するには次の手順を実行する。

  1. 適切なフォルダに Dp8parser.dll をコピーする。Netmon のルート フォルダは、通常、\Winnt\System32 フォルダにインストールされる。SMS がインストールされている場合、ルート フォルダ名は NetMonFull となる。Windows 2000 Server の場合、ルート フォルダ名は NetMon となる。パーサー DLL を ...\NetMonFull\Parsers または ...\NetMon\parsers にコピーする。コピー先は、使用している Netmon のバージョンに依存する。
  2. Netmon を起動する。
  3. [キャプチャ] - [ネットワーク...] - [ローカル コンピュータ] で、キャプチャするアダプタを設定する。このとき、[ダイヤルアップ接続] プロパティがオフに設定されたアダプタを選択するように注意する。

これで、トラフィックのキャプチャを開始できる。


DirectPlay ネットワーク トラフィックのキャプチャ

キャプチャ処理を開始するには、[Microsoft ネットワーク モニタ] ツールバーの [キャプチャの開始] ボタンをクリックして、キャプチャ表示を開く。最初は、対象のアダプタを通るトラフィックがすべて表示される。この生のトラフィック ストリームは、興味のある一定のパケットだけに絞り込むことができる。Microsoft® DirectPlay® のパーサーをインストールすると、基本的に、DirectPlay 指向の 4 つのフィルタが Netmon に追加される。これらのフィルタを使用すると、キャプチャ表示から DirectPlay 以外のすべてのトラフィックを除外できる。

フィルタを選択するには次の手順を実行する。

  1. [Microsoft ネットワーク モニタ] ツールバーの [キャプチャ フィルタの編集] をクリックする。
  2. [Protocol == Any] をダブルクリックする。
  3. [全て無効] をクリックする。
  4. [無効なプロトコル] の [DPLAYSESSION]、[DPLAYSP]、[DPLAYTRANSPORT]、および [DPLAYVOICE] をダブルクリックする。

[OK] を 2 回クリックしてキャプチャ表示に戻る。これで、DirectPlay トラフィックの表示を開始できる。

キャプチャ表示でなく、キャプチャ処理自体にフィルタを適用することもできる。こうすると、たとえば、指定したポートから指定したポートへの IP パケットだけをキャプチャできる。詳細については、Netmon のドキュメントを参照すること。


DirectPlay で Netmon を使用するためのヒント

ここでは、Microsoft® DirectPlay® で Netmon を使用するためのヒントをいくつか紹介する。

  • デフォルトでは、最新のトラフィック 1 MB だけがキャプチャされるようになっている。この値は、10 ～ 20 MB 程度に増す必要があるかもしれない。
  • ハード ドライブへのストリームは行われないので、確認できるトラフィックは現在キャプチャ バッファ内にある内容に限られる。キャプチャ済みのトラフィックをハード ドライブにストリームするには、独自のキャプチャ処理を実装する必要がある。詳細については、MSDN を参照すること。
  • デフォルトでは、DirectPlay のパーサーは、[2302,2400]U{6073} ポート/ソケット範囲を使って、IP および IPX パケットをフィルタリングするようになっている。標準以外のポート/ソケット範囲を使用している場合には、ユーザー定義のポート/ソケット値をパーサーに認識させることができる。これには、\HKEY_CURRENT_USER\Software\Microsoft\DirectX\DirectPlay\Parsers レジストリ キーに、MinUserPort と MaxUserPort の 2 つの DWORD 値を追加する。この結果、ポート/ソケット範囲が [2302,2400]U{6073}U[MinUserPort,MaxUserPort] に拡張される。
  • DirectPlay プロトコルと RTP プロトコルは、どちらも UDP プロトコルの上位レイヤであるため、両者のパーサーが競合する可能性がある。したがって、DirectPlay トラフィックを分析するときは RTP パーサーを無効にし、RTP トラフィックを分析するときは DirectPlay パーサーを無効にしなければならない。


DirectPlay と DirectPlay Voice におけるコールバック関数の実装

Microsoft® DirectPlay® と DirectPlay Voice では、DirectPlay が発行するイベントを処理するため、いくつかのコールバック関数を独自に実装する必要がある。DirectPlay はマルチスレッド化されているので、同時に複数のイベントを発行する可能性がある。したがって、DirectPlay のコールバックで正しく信頼性の高いデータ アクセスを行うには、同期をマルチスレッド化する手段を実装しなければならない。このことを、コールバックを "再入可能" または "スレッドセーフ" にする、と言う。

コールバック関数の構造

コールバックの構造は、標準的な Microsoft Windows Win32 API プログラミング ガイドラインに従う。

HRESULT WINAPI Callback(
  PVOID pvUserContext,
  DWORD dwMessageType,
  PVOID pMessage );

pvUserContext は、DirectPlay にコールバック関数を登録するときに指定するコンテキスト値である。コールバックの登録時に DirectPlay にこの値を渡すと、DirectPlay からコールバックが起動されるときに、このコンテキスト値が返される。

dwMessageType is は、DirectPlay からコールバックに渡される ID 値のいずれかである。

pMessage には、DirectPlay から渡されたメッセージが格納される。

コールバックの登録

Microsoft DirectPlay のネットワーキング コールバック関数は、PFNDPNMESSAGEHANDLER 型である。コールバック関数のアドレスは、IDirectPlay8Peer::Initialize、IDirectPlay8Client::Initialize、または IDirectPlay8Server::Initialize を使って登録する。使用するインターフェイスは、ネットワーキング セッションの種類に依存する。DirectPlay 音声コールバック関数を登録している場合、コールバックのアドレスは、IDirectPlayVoiceClient::Initialize または IDirectPlayVoiceServer::Initialize を使って登録する。使用するインターフェイスは、作成する DirectPlay 音声セッションの種類に依存する。

次のコードは、IDirectPlay8Peer インターフェイスを使ってコールバック関数を登録する方法を示している。

HRESULT WINAPI Callback(PVOID, DWORD, PVOID);
IDirectPlay8Peer* pdp8Peer;

// サーバー インターフェイスを取得する。
hr = CoCreateInstance( CLSID_DirectPlay8Peer, ...)
...

// コールバックを登録する。
hr = pdp8Peer->Initialize(NULL, Callback, 0);


クリティカル セクション オブジェクトを使った DirectPlay ネットワーキング コールバックの実装

Microsoft® DirectPlay® のネットワーキングおよび音声コールバックは、マルチスレッド化されている。したがって、DirectPlay のコールバックで正しく信頼性の高いデータ アクセスを行うには、同期をマルチスレッド化する手段を実装しなければならない。

現時点では、マルチスレッド コールバックのデータの同期をとるために、3 つの手段がある。

  • ミューテックス オブジェクト
  • セマフォ オブジェクト
  • クリティカル セクション オブジェクト

クリティカル セクション オブジェクトを使って同期をとる方法は、DirectX 8.0 SDK に付属する DirectPlay の音声関連サンプルに示されている。クリティカル セクション オブジェクトの使い方については、以下のトピックも参考になる。ミューテックス オブジェクトまたはセマフォ オブジェクトを実装する場合、これらのトピックは、SDK (Microsoft Platform Software Development Kit) にも、多くのリファレンス ブックにも記載されているので、参照すること。これらの同期手段は、万一何らかの問題が起きた場合、複雑で難しいデバッグ作業が必要になる。このため、いずれかを実装するには、個々の分野に関する相当進んだ知識がなければならない。

CRITICAL_SECTION g_csPlayerContext;
InitializeCriticalSection(&g_csPlayerContext);

次に、DirectPlay メッセージ コールバック ハンドラを実装する。

HRESULT WINAPI DirectPlayMessageHandler( PVOID pvUserContext,
                                         DWORD dwMessageId,
                                         PVOID pMsgBuffer )
{
    switch( dwMessageId )
    {
        case DPN_MSGID_CREATE_PLAYER:
        {
             EnterCriticalSection( &g_csPlayerContext );
             //コールバックがロックされた。
             //プレーヤー データの処理をする。
             LeaveCriticalSection( &g_csPlayerContext );
        }
    }
}

最後に、アプリケーションの終了時に、DeleteCriticalSection 関数を呼び出して、クリティカル セクション オブジェクトに関連付けられたメモリを解放する必要がある。

DeleteCriticalSection( &g_csPlayerContext );


DirectPlay DPNSVR アプリケーションの使い方

Microsoft Windows では、複数プロセス間で単独の IP ポートまたは IPX ポートを共有することができない。通信ホストとして機能するアプリケーションでは、それぞれ異なるポートを使用しなければならない。この制約により、特に実行中のゲームを列挙するといった作業を実行するときに、以下のようないくつかの問題が発生する。

  • ポートの競合を避ける。ほかのアプリケーションと競合しないポートを選択する必要がある。
  • 複数の通信ホストを単独システム上で管理する。ホストは、インスタンスごとに異なったポートを使用しなければならない。一方、クライアント アプリケーションは、特定のホストが使用しているポートを判断しなければならない。
  • 既に使用中のポートを避ける。望ましいポートが使用中の場合は、別のポートを使用できなければならない。

これらの問題に、DPNSVR アプリケーションは、列挙要求の転送サービスとして機能することによって対処する。アプリケーションは、ホストを開始するとき、動作中のポートを DPNSVR に知らせる。DPNSVR は、既知のポートで待機し、システム上のすべての Microsoft® DirectPlay® ホストに、すべての列挙要求を転送する。列挙要求への応答には、ホストが接続された実際のポートが含まれる。DPNSVR により、開発者は以下の利点が得られる。

  • 特定のシステムで実行されているゲームをすべて列挙する汎用列挙ルーチンを作成できる。
  • DirectPlay を使ってホストのポートを選択できる。クライアント アプリケーションが、DPNSVR のサービスを使って既知のポートで実行中のゲームを列挙すると、ホストが接続された実際のポートを含む応答が得られる。
  • アプリケーションが要求したポートを取得できない場合を、考慮する必要がない。
  • システム上にあるほかのアプリケーションとの競合について、心配する必要がない。

多くのアプリケーションでは DPNSVR のサービスを使用するが、DPNSVR を無効にしなければならない場合もある。その例を 2 つ示す。

  • 使用すべきポートを知っているが、コンピュータ上でそのアプリケーションのインスタンスが 1 つしか実行されない場合。
  • プレーヤーがセッションを列挙する能力を制限したい場合。DPNSVR を無効にすれば、ホストが接続されたポートを知っているプレーヤーだけが、ホストを列挙できる。

詳細については、｢DPNSVR の使い方｣を参照すること。


DPNSVR の使い方

対象のサービス プロバイダが DPNSVR をサポートしているかどうかを判断するには、IDirectPlay8Peer、IDirectPlay8Client、または IDirectPlay8Server でサポートされる GetSPCaps メソッドを呼び出す。サービス プロバイダが DPNSVR をサポートしていれば、返される DPN_SP_CAPS 構造体の dwFlags メンバに DPNSPCAPS_SUPPORTSDPNSRV フラグが設定される。現時点では、IP および IPX サービス プロバイダだけが DPNSVR をサポートする。

DPNSVR はデフォルトで選択されているので、特別な操作をせずに使用できる。列挙要求をホストに転送したくない場合は、DPN_APPLICATION_DESC 構造体の dwFlags メンバに DPNSESSION_NODPNSVR フラグを設定して、DPNSVR を明示的に無効にする必要がある。

注 DPNSESSION_NODPNSVR フラグが設定されていても、動作中のポートを知っていれば、アプリケーションはいつでもホストを列挙することができる。


フォーカス キャプチャの実装

Microsoft® DirectPlay® Voice をサポートするロビー可能ゲーム アプリケーションとロビー アプリケーションを作成するには、フォーカスをキャプチャするという概念が不可欠である。ゲーム アプリケーションがフォーカス キャプチャを適切に実装していない場合、ロビー アプリケーションから起動したときに、音声通信が機能しない可能性がある。

DirectPlay 音声セッションの作成前に、以下のようにいくつかの初期化作業が完了していなければならない。

// DirectPlay 音声クライアントのインターフェイスを作成する。
hr = CoCreateInstance( CLSID_DirectPlayVoiceClient,
                       NULL,
                       CLSCTX_INPROC_SERVER,
                       IID_IDirectPlayVoiceClient,
                       (LPVOID*) &m_pVoiceClient )

// hwndAppWindow メンバを、ゲーム アプリケーション実行中に
// フォーカスのあるウィンドウに設定する。
DVSOUNDDEVICECONFIG dvSoundDeviceConfig;

dvSoundDeviceConfig.hwndAppWindow = hWnd;
// dwFlags を DVSOUNDCONFIG_STRICTFOCUS に設定する。こうすると、
// フォアグラウンドのアプリケーション ウィンドウだけがフォーカスを取得する。
dvSoundDeviceConfig.dwFlags = DVSOUNDCONFIG_STRICTFOCUS;

// 音声セッションに接続する。
hr = m_pVoiceClient->Connect( &dvSoundDeviceConfig,
                              pdvClientConfig,
                              DVFLAGS_SYNC )

アプリケーションがセッションに接続されると、DirectPlay 音声コールバックにメッセージが届く。フォーカス キャプチャを適切に実装するためには、DVMSGID_GAINFOCUS と DVMSGID_LOSTFOCUS の 2 つのメッセージを処理する必要がある。

HRESULT CALLBACK DirectPlayVoiceClientMessageHandler(
                     LPVOID lpvUserContext,
                     DWORD dwMessageType,
                     LPVOID lpMessage )
{
    switch( dwMessageType )
    {
     case DVMSGID_GAINFOCUS:
        // ゲーム アプリケーションがシステム内のフォーカスを取得した。
            break;
        case DVMSGID_LOSTFOCUS:
        // ゲーム アプリケーションがシステム内のフォーカスを失った。
            break;
    }
  ...
}

録音がミュートされると、フォーカスが失われる。DirectPlay Voice からコールバックに DVMSGID_LOSTFOCUS メッセージが届く。録音のミュートが解除されると、フォーカスが戻る。ただし、DVSOUNDCONFIG_STRICTFOCUS を使っているアプリケーションでは、アプリケーション ウィンドウがフォアグラウンドである場合にのみ、フォーカスが戻る。

DVCLIENTCONFIG dvClientConfig;
dvClientConfig.dwFlags = DVCLIENTCONFIG_RECORDMUTE;

// 録音をミュートする。DVMSGID_LOSTFOCUS が DirectPlay 音声コールバック関数
// に送信される。
m_pVoiceClient->SetClientConfig(dvClientConfig);


DirectPlay C++ サンプル

以下のサンプル アプリケーションは、C++ プログラミング言語用 Microsoft® DirectPlay® アプリケーション プログラミング インターフェイスの使い方および能力を示すものである。詳細については、個々のサンプル フォルダの Readme.txt ファイルを参照すること。サンプル フォルダは、すべて SDK ルート ディレクトリ (通常は C:\mssdk) の下にある。

  • AddressOverride
  • ChatPeer
  • DataRelay
  • LobbyClient
  • Maze
  • SimpleClientServer
  • SimplePeer
  • StagedPeer
  • VoiceClientServer
  • VoiceConnect
  • VoiceGroup
  • VoicePosition


AddressOverride

AddressOverride は、ネットワーク上の別セッションのホストとなるか、またはそのようなセッションに接続するために、Microsoft® DirectPlay® のアドレシングを無効にする方法を示す。

パス

(SDK ルート)\Samples\Multimedia\DirectPlay\AddressOverride


ChatPeer

サンプル ChatPeer は、SimplePeer に似た形をしている。プレーヤーがセッションのホストとなるか、またはセッションに接続すると、文字列の受け渡しによってプレーヤーどうしがチャットできるようになる。

パス

(SDK ルート)\Samples\Multimedia\DirectPlay\ChatPeer


DataRelay

サンプル DataRelay は、SimplePeer と似ている。ただし、ダイアログ ボックスの UI で指定されたオプションが付いたデータ パケットを、単独の相手 (または全員) に送信するようになっている。

パス

(SDK ルート)\Samples\Multimedia\DirectPlay\DataRelay


LobbyClient

LobbyClient は、簡単なロビー クライアント アプリケーションである。ローカル システム上の登録済み Microsoft® DirectPlay® アプリケーションが、すべて表示される。ユーザーは、選択したサービス プロバイダを使って、それらのアプリケーションを 1 つ以上起動できる。起動するロビー対象アプリケーションには、ゲームに参加するか、またはゲームのホストとなることを指示できる。

パス

(SDK ルート)\Samples\Multimedia\DirectPlay\LobbyClient


Maze

サンプル Maze は、Microsoft® DirectPlay® クライアント/サーバー アプリケーションである。クライアントは、コンソールベースのクライアントと D3D クライアントの 2 種類が用意されている。D3D クライアントは、スクリーン セーバーとして実行することもできる。それには、Mazeclient.exe を自分の \winnt\system32\ フォルダにコピーし、名前を Mazeclient.scr に変更する。こうすると、画面のコントロール パネル アプリケーションから検出可能なスクリーン セーバーになる。

パス

(SDK ルート)\Samples\Multimedia\DirectPlay\Maze


SimpleClientServer

サンプル SimpleClientServer は、簡単なクライアント/サーバー アプリケーションである。

パス

(SDK ルート)\Samples\Multimedia\DirectPlay\SimpleClientServer


SimplePeer

サンプル SimplePeer は、簡単なピアツーピア アプリケーションの実装方法を示す。セッションに参加するか、またはセッションを作成すると、すぐにゲームが開始する。進行中のセッションには、ほかのプレーヤーも随時参加できる。

パス

(SDK ルート)\Samples\Multimedia\DirectPlay\SimplePeer


StagedPeer

サンプル StagedPeer は、セッションへの参加またはセッションの作成に必要な接続設定をユーザーに促す 2 つのダイアログ ボックスと、プレーヤーを接続する。ユーザーがセッションに接続すると、同じセッションに接続された全プレーヤーがチャットできるマルチプレーヤー ステージが表示される。全員の準備が整い、ホストが開始を決定すると、プレーヤーが新しいゲームを開始できる。ホストは、プレーヤーを拒否したり、プレーヤーのスロットを閉じたりすることができる。

パス

(SDK ルート)\Samples\Multimedia\DirectPlay\StagedPeer


VoiceClientServer

サンプル VoiceClientServer は、Microsoft® DirectPlay® Voice ベースの簡単なクライアント/サーバー アプリケーションである。

パス

(SDK ルート)\Samples\Multimedia\DirectPlay\VoiceClientServer


VoiceConnect

サンプル VoiceConnect は、ほかのプレーヤーをネットワークして、Microsoft® DirectPlay® Voice のチャット セッションを開始する方法を示す。セッションに参加するか、またはセッションを作成すると、プレーヤーはマイクロフォンを使って会話できるようになる。進行中のセッションには、ほかのプレーヤーも随時参加できる。

パス

(SDK ルート)\Samples\Multimedia\DirectPlay\VoiceConnect


VoiceGroup

サンプル VoiceGroup は、Microsoft® DirectPlay® Voice を使って、ユーザーが特定のプレーヤー グループに話しかけることができるようにする方法を示す。

パス

(SDK ルート)\Samples\Multimedia\DirectPlay\VoiceGroup


VoicePosition

サンプル VoicePosition は、3D ポジショニングを使った Microsoft® DirectPlay® Voice の使用方法を示す。このサンプルでは、簡単な 2D グリッドによってプレイ フィールドが表現される。プレーヤーは、プレイ フィールド内を移動して、3D 空間化のエフェクトを聞くことができる。

パス

(SDK ルート)\Samples\Multimedia\DirectPlay\VoicePosition


DirectPlay C/C++ リファレンス

Microsoft® DirectPlay® C/C++ アプリケーション プログラミング インターフェイスのリファレンスは、次のように分類される。

  • インターフェイス
  • 関数
  • コールバック関数
  • システム メッセージ
  • 構造体
  • 戻り値


インターフェイス

ここでは、Microsoft® DirectPlay® の次のインターフェイスのメソッドに関するリファレンスを示す。

  • IDirectPlay8Peer
  • IDirectPlay8Client
  • IDirectPlay8Server
  • IDirectPlayVoiceClient
  • IDirectPlayVoiceServer
  • IDirectPlayVoiceTest
  • IDirectPlay8LobbyClient
  • IDirectPlay8LobbiedApplication
  • IDirectPlay8Address
  • IDirectPlay8AddressIP


IDirectPlay8Peer

アプリケーションでは、IDirectPlay8Peer インターフェイスのメソッドを使用して、ピアツーピアの Microsoft® DirectPlay® セッションを作成する。

IDirectPlay8Peer インターフェイスのメソッドは、次のように分類できる。

セッション管理 | Close
 | Connect
 | EnumHosts
 | EnumServiceProviders
 | GetApplicationDesc
 | GetCaps
 | GetConnectionInfo
 | GetSPCaps
 | Host
 | SetApplicationDesc
 | SetCaps
 | SetSPCaps
 | TerminateSession
メッセージ管理 | GetSendQueueInfo
 | Initialize
 | ReturnBuffer
 | SendTo
プレーヤー管理 | DestroyPeer
 | GetPeerInfo
 | SetPeerInfo
 | GetPlayerContext
グループ管理 | AddPlayerToGroup
 | CreateGroup
 | DestroyGroup
 | EnumPlayersAndGroups
 | EnumGroupMembers
 | GetGroupContext
 | GetGroupInfo
 | RemovePlayerFromGroup
 | SetGroupInfo
その他 | CancelAsyncOperation
 | GetLocalHostAddresses
 | GetPeerAddress
 | RegisterLobby

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Peer::AddPlayerToGroup

グループにピアを追加する。

このメソッドが呼び出されると、アプリケーションに接続されているすべてのピアは DPN_MSGID_ADD_PLAYER_TO_GROUP メッセージを受信する。

HRESULT AddPlayerToGroup(
const DPNID idGroup,
const DPNID idClient,
PVOID const pvAsyncContext,
DPNHANDLE *const phAsyncHandle,
const DWORD dwFlags
);

パラメータ

idGroup
ピアを追加するグループの識別子を指定する DPNID 型の変数。
idClient
グループに追加されるピアの識別子を指定する DPNID 型の変数。
pvAsyncContext
ユーザー指定のコンテキストへのポインタ。これは、DPN_MSGID_ASYNC_OP_COMPLETE システム メッセージの pvUserContext メンバに返される。このパラメータはオプションであり、NULL に設定できる。
phAsyncHandle
DPNHANDLE。値が返される。ただし、Microsoft® DirectPlay® 8.0 ではこの操作の取り消しは許可されていないため、値を使用することはできない。
dwFlags
このメソッドが処理される方法を制御するフラグ。このメソッドには、次のフラグを設定できる。
DPNADDPLAYERTOGROUP_SYNC
メソッドを同期をとりながら処理する。

戻り値

メソッドが同期をとりながら処理され、処理が成功した場合は S_OK を返す。デフォルトでは、このメソッドは非同期に実行され、通常の場合は DPNSUCCESS_PENDING を返す。また、次のいずれかのエラー値を返す場合もある。

DPNERR_INVALIDFLAGS
DPNERR_INVALIDGROUP

注意

ピアはそれ自体またはほかのピアを既存のグループに追加できる。ピアがグループに正しく追加されると、グループに送信されるすべてのメッセージがそのピアにも送信される。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Peer::CancelAsyncOperation

非同期の要求を取り消す。たとえば、IDirectPlay8Peer インターフェイスのいくつかのメソッドはデフォルトでは非同期に実行される。状況に応じて、要求が処理される前にその要求を取り消したい場合もある。このインターフェイスで非同期に実行できるすべてのメソッドは、hAsyncHandle パラメータを返す。

要求の hAsyncHandle をこのメソッドの hAsyncHandle パラメータに渡すことによって、特定の要求が取り消される。このメソッドを呼び出し、hAsyncHandle パラメータに NULL を、dwFlags パラメータに DPNCANCEL_ALL_OPERATIONS を指定することによって、待機中のすべての非同期処理を取り消すことができる。特定のハンドルがこのメソッドに指定された場合は、いずれのフラグも設定してはならない。

HRESULT CancelAsyncOperation(
const DPNHANDLE hAsyncHandle,
const DWORD dwFlags
);

パラメータ

hAsyncHandle
非同期処理を停止するハンドル。このハンドルは、非同期の処理をサポートするメソッドを呼び出したときに受け取る。すべての要求または特定の種類の非同期処理を停止するには、この値を NULL に設定する。その要求に特定のハンドラを指定した場合は、dwFlags パラメータを 0 にする。
dwFlags
取り消す非同期要求を指定するフラグ。次のいずれかのフラグを設定できる。
DPNCANCEL_ENUM
すべての非同期 IDirectPlay8Peer::EnumHosts 要求を取り消す。EnumHosts メソッドから返されるハンドルを指定することによって、単一の EnumHosts 要求を取り消すことができる。
DPNCANCEL_CONNECT
非同期 IDirectPlay8Peer::Connect 要求を取り消す。
DPNCANCEL_SEND
非同期 IDirectPlay8Peer::SendTo 要求を取り消す。
DPNCANCEL_ALL_OPERATIONS
非同期の Connect、Send、および SentTo の各処理をすべて取り消す。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_CANNOTCANCEL
DPNERR_INVALIDFLAGS
DPNERR_INVALIDHANDLE

注意

このメソッドを使って、IDirectPlay8Peer::Connect、IDirectPlay8Peer::SendTo、および IDirectPlay8Peer::EnumHosts メソッドの非同期処理を取り消すことができる。Microsoft® DirectPlay® 8.0 は、ほかの非同期処理の取り消しをサポートしていない。

IDirectPlay8Peer::SendTo メソッドから返されたハンドルを指定すると、送信要求を取り消すことができる。その場合も、DPN_MSGID_SEND_COMPLETE または DPN_CONNECT_COMPLETE システム メッセージは、DPNSEND_NOCOMPLETE フラグを設定せずに送信された非同期のセンド要求ごとに、アプリケーション メッセージ ハンドラに送信される。このメソッドで取り消された送信要求は、DPN_MSGID_SEND_COMPLETE メッセージの hResultCode メンバに DPNERR_USERCANCEL を返す。

dwFlags に DPNCANCEL_ALL_OPERATIONS、DPNCANCEL_CONNECT、DPNCANCEL_SEND、または DPNCANCEL_ENUM を設定した場合、DirectPlay はすべての一致する処理を取り消そうとする。このメソッドは、取り消しに失敗した処理がある場合、一部の取り消しが成功していてもエラーを返す。

注 このメソッドが値を返すまで、完了メッセージは到着しない場合がある。DPN_MSGID_SEND_COMPLETE、DPN_MSGID_CONNECT_COMPLETE、または DPN_MSGID_ASYNC_OP_COMPLETE メッセージを受け取るまで、処理が終了したと見なしてはならない。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Peer::Close

セッションにより開かれた接続を閉じる。いずれかのオブジェクトが IDirectPlay8Peer::Initialize で正常に初期化されると、このメソッドを呼び出す必要がある。

HRESULT Close(
const DWORD dwFlags
);

パラメータ

dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は S_OK を返す。それ以外の場合は、次のエラー値を返す。

DPNERR_UNINITIALIZED

注意

このメソッドは、未処理の処理があれば、それを取り消す。このメソッドは、ほかのスレッドのすべてのコールバック通知が返るまで、ブロックする。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Peer::Connect

ピアツーピア セッションで、すべてのピアへの接続を確立する。一度接続が確立すると、インターフェイス上の通信チャネルが開き、アプリケーションはメッセージの到着を待機する。接続が完了するまで、IDirectPlay8Peer::SendTo メソッドを使用してメッセージを送信できない。

このメソッドを呼び出す前に、IDirectPlay8Peer::EnumHosts を呼び出して、関連付けられているホストのアプリケーション記述とアドレスを取得できる。EnumHosts メソッドは、現在ホストされているアプリケーションごとに DPN_APPLICATION_DESC 構造体を返す。この構造体は、アプリケーションのインスタンス GUID を含め、アプリケーションを記述する。

このメソッドが非同期に呼び出され (デフォルト)、DPNSUCCESS_PENDING を返した場合、接続が完了すると、アプリケーションのメッセージ ハンドラに DPN_MSGID_CONNECT_COMPLETE メッセージが送信される。

HRESULT Connect(
const DPN_APPLICATION_DESC *const pdnAppDesc,
IDirectPlay8Address *const pHostAddr,
IDirectPlay8Address *const pDeviceInfo,
const DPN_SECURITY_DESC *const pdnSecurity,
const DPN_SECURITY_CREDENTIALS *const pdnCredentials,
const void *const pvUserConnectData,
const DWORD dwUserConnectDataSize,
void *const pvPlayerContext,
void *const pvAsyncContext,
DPNHANDLE *const phAsyncHandle,
const DWORD dwFlags
);

パラメータ

pdnAppDesc
アプリケーションを記述する DPN_APPLICATION_DESC 構造体へのポインタ。このメソッドで使用されるのは、この構造体の一部のメンバのみである。設定しなければならないメンバは、dwSize および guidApplication のみである。guidInstance、pwszPassword、および dwFlags も設定できる。
pHostAddr
IDirectPlay8Address へのポインタ。このインターフェイスは、ホストするコンピュータへの接続に使用されるアドレス情報を指定する。
pDeviceInfo
IDirectPlay8Address インターフェイスへのポインタ。このポインタは、サーバーへの接続に使用するネットワーク アダプタ (NIC、モデムなど) を指定する。
pdnSecurity
予約済み。NULL に設定しておく。
pdnCredentials
予約済み。NULL に設定しておく。
pvUserConnectData
接続を詳しく確認するためにホストまたはサーバーに提供されるアプリケーション固有のデータへのポインタ。このデータは、pvUserConnectData メンバの DPN_MSGID_INDICATE_CONNECT メッセージに送信される。このパラメータはオプションであり、ユーザー コードによる余分な接続の確認が提供されない場合は、NULL に設定することができる。
dwUserConnectDataSize
pvUserConnectData パラメータに含まれるデータのサイズを指定する DWORD 型の変数。
pvPlayerContext
ローカル プレーヤーのコンテキスト値へのポインタ。この値は、ローカル コンピュータが DPN_MSGID_CREATE_PLAYER メッセージを処理するときに事前に設定される。このパラメータはオプションであり、NULL に設定できる。
pvAsyncContext
ユーザー指定のコンテキストへのポインタ。これは、DPN_MSGID_CONNECT_COMPLETE システム メッセージの pvUserContext メンバに返される。このパラメータはオプションであり、NULL に設定できる。
phAsyncHandle
DPNHANDLE。メソッドが値を返すと、phAsyncHandle は、IDirectPlay8Peer::CancelAsyncOperation に渡して処理を取り消すことができるハンドルをポイントする。dwFlags に DPNCONNECT_SYNC フラグが設定されている場合、このパラメータは NULL に設定しなければならない。
dwFlags
接続モードを記述するフラグ。次のフラグを設定できる。
DPNCONNECT_OKTOQUERYFORADDRESSING
このフラグを設定すると、Microsoft® DirectPlay® の標準のダイアログ ボックスが表示される。十分な情報がこのメソッドに渡されていない場合は、詳細について問い合わされる。
DPNCONNECT_SYNC
接続要求を同期をとりながら処理する。その場合も、メッセージ ハンドラは DPN_MSGID_CONNECT_COMPLETE メッセージを受け取り、ホストからの接続応答を処理できる。このメッセージは、IDirectPlay8Peer::Connect が値を返すまでに受け取る。

戻り値

メソッドが同期をとりながら処理され、処理が成功した場合は S_OK を返す。デフォルトでは、このメソッドは非同期に実行され、通常の場合は、DPNSUCCESS_PENDING を返す。また、次のいずれかのエラー値を返す場合もある。

DPNERR_HOSTREJECTEDCONNECTION
DPNERR_INVALIDAPPLICATION
DPNERR_INVALIDDEVICEADDRESS
DPNERR_INVALIDFLAGS
DPNERR_INVALIDHOSTADDRESS
DPNERR_INVALIDINSTANCE
DPNERR_INVALIDINTERFACE
DPNERR_INVALIDPASSWORD
DPNERR_NOCONNECTION
DPNERR_NOTHOST
DPNERR_SESSIONFULL

注意

複数の列挙を同時に実行し、1 つの接続中に実行できるが、インターフェイスごとに 1 つの接続しか利用できない。1 つ以上のアプリケーションへの接続を確立するには、別のインターフェイスを作成しなければならない。

このメソッドが非同期に呼び出された場合 (デフォルト)、接続が完了すると、アプリケーションのメッセージ ハンドラに DPN_MSGID_CONNECT_COMPLETE メッセージが送信される。このメソッドがエラーを返した場合、完了メッセージは送信されない。

このメソッドが呼び出されると、ホストのメッセージ ハンドラに DPN_MSGID_INDICATE_CONNECT メッセージが送信される。ホストがこのメッセージを処理するときは、プレーヤーが受け取る接続応答データを DPN_MSGID_CONNECT_COMPLETE メッセージで指定することができる。ホストが接続を受け入れた場合、接続応答データにはカスタム スタートアップ情報が入っている場合がある。接続が拒否された場合、接続応答データに拒否の説明が入っている場合がある。

IDirectPlay8Peer::Close を呼び出してホストとの接続を終了する必要がある。Connect() への呼び出しが成功した後、すべての残っている列挙は DPNERR_USERCANCEL を返してキャンセルされる。

注 dwFlags に DPNCONNECT_OKTOQUERYFORADDRESSING フラグを設定した場合、サービス プロバイダは、ダイアログ ボックスを表示して、ユーザーにアドレス情報の入力を求めようとする。サービス プロバイダがダイアログボックスの表示を試みるときには、表示可能なウィンドウが存在している必要がある。ウィンドウがない場合、アプリケーションはロックする。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Peer::CreateGroup

現在のセッションにグループを作成する。グループはプレーヤーの論理的な集まりである。

注 マルチキャスティングはこのリリースではサポートされていない。

このメソッドが呼び出されると、アプリケーションに接続されているすべてのピアが DPN_MSGID_CREATE_GROUP システム メッセージを受け取る。

HRESULT CreateGroup(
const DPN_GROUP_INFO *const pdpnGroupInfo,
VOID *const pvGroupContext,
VOID *const pvAsyncContext,
DPNHANDLE *const phAsyncHandle,
const DWORD dwFlags
);

パラメータ

pdpnGroupInfo
グループの記述を保持する DPN_GROUP_INFO 構造体へのポインタ。
pvGroupContext
グループのコンテキスト値へのポインタ。この値は、ローカル アプリケーションのメッセージ ハンドラが関連する DPN_MSGID_CREATE_GROUP メッセージを受け取ったときに事前に設定される。このパラメータはオプションであり、NULL に設定できる。
pvAsyncContext
ユーザー指定のコンテキストへのポインタ。これは、DPN_MSGID_ASYNC_OP_COMPLETE システム メッセージの pvUserContext メンバに返される。このパラメータはオプションであり、NULL に設定できる。
phAsyncHandle
DPNHANDLE。値が返される。ただし、Microsoft® DirectPlay® 8.0 ではこの操作の取り消しは許可されていないため、値を使用することはできない。
dwFlags
このメソッドが処理される方法を制御するフラグ。このメソッドには、次のフラグを設定できる。
DPNCREATEGROUP_SYNC
メソッドを同期をとりながら処理する。

戻り値

メソッドが同期をとりながら処理され、処理が成功した場合は S_OK を返す。デフォルトでは、このメソッドは非同期に実行され、通常の場合、DPNSUCCESS_PENDING を返す。また、次のエラー値を返す場合もある。

DPNERR_INVALIDFLAGS

注意

Microsoft® DirectPlay® は、階層グループを保持しない。これは、これらのグループがフラット グループとグループ データの活用により簡単に実装できるためである。

このメソッドが呼び出されると、すべてのピアが DPN_MSGID_CREATE_GROUP メッセージを受け取る。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Peer::DestroyPeer

セッションからピアを削除する。

HRESULT DestroyPeer(
const DPNID dpnidClient,
void *const pDestroyInfo,
const DWORD dwDestroyInfoSize,
const DWORD dwFlags
);

パラメータ

dpnidClient
削除するピアの識別子を指定する DPNID 型の変数。
pDestroyInfo
詳細な削除データ情報を記述する値へのポインタ。
dwDestroyInfoSize
pDestroyInfo パラメータに保持されるデータのサイズを指定する DWORD 型の変数。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDPARAM
DPNERR_INVALIDPLAYER
DPNERR_NOTHOST

注意

プレーヤーを削除できるのは、セッション ホストのみである。削除されたプレーヤーは、DPN_MSGID_TERMINATE_SESSION メッセージによって通知される。メッセージに関連付けられている構造体には、pDestroyInfo パラメータによって渡されるデータが格納される。ほかのセッション メンバがこのメソッドを呼び出すと、メソッドは失敗し、DPNERR_NOTHOST を返す。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Peer::DestroyGroup

IDirectPlay8Peer::CreateGroup メソッドによって作成されたグループを削除する。このメソッドは、セッション内の任意のピアから呼び出すことができる。

HRESULT DestroyGroup(
const DPNID idGroup,
PVOID const pvAsyncContext,
DPNHANDLE *const phAsyncHandle,
const DWORD dwFlags
);

パラメータ

idGroup
DPNID 型の変数。削除するグループの識別子を設定する。
pvAsyncContext
ユーザー指定のコンテキストへのポインタ。これは、DPN_MSGID_ASYNC_OP_COMPLETE システム メッセージの pvUserContext メンバに返される。このパラメータはオプションであり、NULL に設定できる。
phAsyncHandle
A DPNHANDLE.値が返される。ただし、Microsoft® DirectPlay® 8.0 ではこの操作の取り消しは許可されていないため、値を使用することはできない。
dwFlags
このメソッドが処理される方法を制御するフラグ。このメソッドには、次のフラグを設定できる。
DPNDESTROYGROUP_SYNC
メソッドを同期をとりながら処理する。

戻り値

メソッドが同期をとりながら処理され、処理が成功した場合は S_OK を返す。デフォルトでは、このメソッドは非同期に実行され、通常の場合、DPNSUCCESS_PENDING を返す。また、次のいずれかのエラー値を返す場合もある。

DPNERR_INVALIDFLAGS
DPNERR_INVALIDGROUP

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Peer::EnumPlayersAndGroups

セッションのすべてのプレーヤーまたはグループの識別子、あるいはその両方の一覧を取得する。

HRESULT EnumPlayersAndGroups(
DPNID *const prgdpnid,
DWORD *const pcdpnid,
const DWORD dwFlags
);

パラメータ

prgdpnid
セッションのグループまたはプレーヤーの識別子、あるいはその両方がデータとして格納される配列へのポインタ。
pcdpnid
prgdpnid がポイントするバッファに格納できる識別子の数を指定する、DWORD 型の変数へのポインタ。バッファが小さすぎる場合、このメソッドは DPNERR_BUFFERTOOSMALL を返す。このパラメータには、必要なエントリの数が設定される。
dwFlags
列挙の動作を記述するフラグ。次の 1 つまたは両方のフラグを設定することができる。
DPNENUM_PLAYERS
プレーヤーの識別子のリストを返す。
DPNENUM_GROUPS
グループの識別子のリストを返す。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDFLAGS

注意

グループおよびプレーヤーの情報は頻繁に変化するため、返される必要なバッファ サイズは以降の呼び出しで変わる場合がある。メソッドが成功するまで、バッファを確認し、再割り当てする。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Peer::EnumGroupMembers

グループ内のすべてのプレーヤーの一覧を取得する。

HRESULT EnumGroupMembers(
const DPNID dpnid,
DPNID *const prgdpnid,
DWORD *const pcdpnid,
const DWORD dwFlags
);

パラメータ

dpnid
列挙するプレーヤーを保持するグループを指定する DPNID 型の変数。
prgdpnid
グループのプレーヤーの識別子を格納する配列へのポインタ。
pcdpnid
dpnid がポイントするバッファに格納できる識別子の数を指定する、DWORD 型の変数へのポインタ。バッファが小さすぎる場合、このメソッドは DPNERR_BUFFERTOOSMALL を返す。このパラメータには、必要なエントリの数が設定される。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDFLAGS
DPNERR_INVALIDGROUP

注意

プレーヤーの情報は頻繁に変化するため、返される必要なバッファ サイズは以降の呼び出しで変わる場合がある。メソッドが成功するまで、バッファを確認し、再割り当てする。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Peer::EnumHosts

Microsoft® DirectPlay® ゲームをホストするアプリケーションを列挙する。列挙基準を満たすアプリケーションが見つかると、DPN_MSGID_ENUM_HOSTS_RESPONSE システム メッセージによりアプリケーションのメッセージ ハンドラが呼び出される。メッセージには、見つかったアプリケーションを記述する DPN_APPLICATION_DESC 構造体が保持される。

任意の数の列挙を同時に実行できる。異なる複数の列挙への応答を区別するために、pvUserContext の値がメッセージ ハンドラに提供される。

列挙の処理にはさまざまな方法があるため、メディアに関して特に知識がない限り、アプリケーションでは dwEnumPeriod、dwRetryInterval、または dwTimeOut を指定してはならない。

デフォルトの列挙カウント値とタイムアウト値で、EnumHosts は適切な時間内に終了する。これらの値はサービス プロバイダによって設定され、IDirectPlay8Peer::GetSPCaps を呼び出して取得できる。非同期の列挙は、IDirectPlay8Peer::CancelAsyncOperation を呼び出すか、または dwFlags パラメータに pAsyncHandle パラメータに返されたハンドラを渡すか DPENUM_CANCEL フラグを設定すれば、いつでも停止できる。メッセージ ハンドラから S_OK 以外の値を返して、列挙を停止することもできる。

HRESULT EnumHosts(
PDPN_APPLICATION_DESC const pApplicationDesc,
IDirectPlay8Address *const pdpaddrHost,
IDirectPlay8Address *const pdpaddrDeviceInfo,
PVOID const pvUserEnumData,
const DWORD dwUserEnumDataSize,
const DWORD dwEnumCount,
const DWORD dwRetryInterval,
const DWORD dwTimeOut,
PVOID const pvUserContext,
HANDLE *const pAsyncHandle
const DWORD dwFlags,
);

パラメータ

pApplicationDesc
列挙するアプリケーションのホストを指定する DPN_APPLICATION_DESC 構造体へのポインタ。pApplicationDesc.dwSize メンバを適切な値に設定しなければならない。応答の数を減らすには、pApplicationDesc.guidApplication に検索するアプリケーションの GUID を設定する。このメンバが設定されていない場合、すべてのアプリケーションが検索対象になる。
pdpaddrHost
アプリケーションをホストしているコンピュータのアドレスを指定する IDirectPlay8Address オブジェクトへのポインタ。NULL を指定すると、DirectPlay がアドレスを作成する。デフォルトでは、DirectPlay は pdpaddrDeviceInfo パラメータからアドレスを作成する。dwFlags に DPNENUMHOSTS_OKTOQUERYFORADDRESSING フラグを設定した場合、ユーザーにアドレス情報を問い合わせることができる。
pdpaddrDeviceInfo
列挙に使用するサービス プロバイダおよびローカル デバイスの設定を指定する IDirectPlay8Address オブジェクトへのポインタ。
pvUserEnumData
列挙要求からホストに送信されるデータ ブロックへのポインタ。データのサイズは、ネットワークの種類によって制限される。正確な値を取得するには、IDirectPlay8Peer::GetSPCaps を呼び出す。
dwUserEnumDataSize
pvUserEnumData パラメータで示すデータのサイズを指定する DWORD 型の変数。
dwEnumCount
列挙データを送信する回数を指定する値。デフォルト値を使用するには、このパラメータを 0 に設定する。dwEnumCount のデフォルト値を取得するには、IDirectPlay8Peer::GetSPCaps を呼び出す。dwEnumCount に INFINITE が指定された場合、列挙は取り消されるまで続行される。
dwRetryInterval
列挙の再試行の間隔をミリ秒単位で指定する値。デフォルト値を使用するには、このパラメータを 0 に設定する。dwRetryInterval のデフォルト値を取得するには、IDirectPlay8Peer::GetSPCaps を呼び出す。
dwTimeOut
最後の列挙が送信された後、DirectPlay が応答を待つ時間 (ミリ秒) を指定する、DWORD 型の変数。デフォルト値を使用するには、このパラメータを 0 に設定する。dwTimeOut のデフォルト値を取得するには、IDirectPlay8Peer::GetSPCaps を呼び出す。INFINITE が指定された場合、列挙は取り消されるまで続行される。
pvUserContext
列挙への応答と共に呼び出された場合に、ピアのメッセージ ハンドラに提供されるコンテキスト。同時実行されている列挙の応答を区別する場合に役立つ。
pAsyncHandle
DPNHANDLE。メソッドが値を返すと、phAsyncHandle は、IDirectPlay8Peer::CancelAsyncOperation に渡して処理を取り消すことができるハンドルをポイントする。dwFlags に DPNENUMHOSTS_SYNC フラグが設定されている場合、このパラメータは NULL に設定しなければならない。
dwFlags
次のフラグを設定できる。
DPNENUMHOSTS_SYNC
メソッドを同期をとりながら処理する。
DPNENUMHOSTS_OKTOQUERYFORADDRESSING
このフラグを設定すると、DirectPlay® の標準のダイアログ ボックスが表示される。十分な情報がこのメソッドに渡されていない場合は、詳細について問い合わされる。
DPNENUMHOSTS_NOBROADCASTFALLBACK
サービス プロバイダがある要素を全要素にコピーすることをサポートしている場合、このフラグを設定するとある要素を全要素にコピーする機能が無効になる。このフラグを設定する前に DPN_SP_CAPS 構造体を調べ、ある要素を全要素にコピーすることがサポートされているかどうかを確認すること。

戻り値

メソッドが同期をとりながら処理され、処理が成功した場合は S_OK を返す。デフォルトでは、このメソッドは非同期に実行され、通常の場合、DPNSUCCESS_PENDING を返す。また、次のいずれかのエラー値を返す場合もある。

DPNERR_INVALIDDEVICEADDRESS
DPNERR_INVALIDFLAGS
DPNERR_INVALIDHOSTADDRESS
DPNERR_INVALIDPARAM
DPNERR_ENUMQUERYTOOLARGE

注意

dwFlags に DPNENUMHOSTS_OKTOQUERYFORADDRESSING フラグを設定した場合、サービス プロバイダは、ダイアログ ボックスを表示して、ユーザーにアドレス情報の入力を求めようとする。サービス プロバイダがダイアログ ボックスの表示を試みるときには、表示可能なウィンドウが存在している必要がある。ウィンドウがない場合、アプリケーションはロックする。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Peer::EnumServiceProviders

アプリケーションで使用できる登録済みサービス プロバイダをすべて列挙する。

HRESULT EnumServiceProviders(
const GUID *const pguidServiceProvider,
const GUID *const pguidApplication,
const DPN_SERVICE_PROVIDER_INFO *const pSPInfoBuffer,
DWORD *const pcbEnumData,
DWORD *const pcReturned
constDWORD dwFlags,
);

パラメータ

pguidServiceProvider
サービス プロバイダを指定する GUID 型の変数へのポインタ。このオプション パラメータは、指定したサービス プロバイダのサブデバイスを列挙させる。通常はこの値に NULL を設定して、使用できるすべてのサービス プロバイダを列挙する。
pguidApplication
アプリケーションを指定する GUID 型の変数へのポインタ。このパラメータにポインタを渡すと、そのアプリケーションで接続できるサービス プロバイダのみが列挙される。また、NULL を渡すと、システムに登録されているすべてのサービス プロバイダを列挙できる。
pSPInfoBuffer
サービス プロバイダ情報を保持する、DPN_SERVICE_PROVIDER_INFO 構造体の配列へのポインタ。
pcbEnumData
バッファが小さすぎる場合、pEnumData バッファのサイズが格納される DWORD へのポインタ。
pcReturned
pcbEnumData 配列に返される DPN_SERVICE_PROVIDER_INFO 構造体の数を指定する DWORD 型の変数へのポインタ。
dwFlags
次のフラグを指定できる。
DPNENUMSERVICEPROVIDERS_ALL
アプリケーションで使用できないプロバイダやデバイスがインストールされていないプロバイダを含め、システムに対して登録されているすべてのサービス プロバイダを列挙する。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDPARAM

注意

pguidServiceProvider パラメータに NULL を指定して最初にこのメソッドを呼び出し、システムで利用可能なベース サービス プロバイダを決定する。次に、pguidServiceProvider にサービス プロバイダ GUID へのポインタを渡すことで、サービス プロバイダ用の特定のデバイスを取得できる。これは、たとえば、Microsoft® DirectPlay® サービス プロバイダのモデム接続を使用する場合などに便利である。ダイヤルアウトにはさまざまなモデムを選択し、ホストには特定のモデムを選択できる。

pcbEnumData buffer バッファではサービス プロバイダ情報を保持する容量が不足する場合、メソッドは DPNERR_BUFFERTOOSMALL を返す。pcbEnumData パラメータには必要なバッファ サイズが含まれる。通常、一番よい方法は長さ 0 のバッファで一度メソッドを呼び出し、必要なサイズを判断することである。次に、バッファを適切なサイズにしてもう一度呼び出す。

通常の場合、このメソッドは、アプリケーションが使用できるサービス プロバイダのみを返す。たとえば、IPX ネットワーキング プロトコルがインストールされていない場合、DirectPlay は IPX サービス プロバイダを返さない。DirectPlay が、使用できないプロバイダを含め、すべてのサービス プロバイダを返すようにするには、dwFlags に DPNENUMSERVICEPROVIDERS_ALL フラグを設定する。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Peer::GetApplicationDesc

接続されているアプリケーションの完全なアプリケーション記述を取得する。

HRESULT GetApplicationDesc(
DPN_APPLICATION_DESC *const pAppDescBuffer,
DWORD *const pcbDataSize,
const DWORD dwFlags
);

パラメータ

pAppDescBuffer
アプリケーションの記述データが書き込まれる DPN_APPLICATION_DESC 構造体へのポインタ。データのサイズのみを要求するときは、このパラメータに NULL を設定する。pAppDescBuffer が NULL に設定されていない場合、pAppDescBuffer.dwSize メンバを適切な値に設定する必要がある。pcbDataSize パラメータは、データの保持に必要なサイズに設定される。
pcbDataSize
このメソッドを呼び出す前に、バッファのサイズに初期化された DWORD 型の変数へのポインタ。メソッドが戻ると、このパラメータにはセッション データのサイズがバイト単位で設定されている。バッファが小さすぎる場合、このメソッドはエラー値 DPNERR_BUFFERTOOSMALL を返す。このパラメータには、必要なバッファ サイズが設定される。このパラメータが NULL の場合、メソッドは DPNERR_INVALIDPARAM を返す。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM
DPNERR_NOCONNECTION

注意

pAppDescBuffer パラメータに NULL を渡して最初にこのメソッドを呼び出し、必要なバッファ サイズを取得する。2 回目にこのメソッドを呼び出してバッファにデータを格納するときは、構造体の dwSize メンバを適切な値に設定する。

返された DPN_APPLICATION_DESC 構造体には、guidInstance、guidApplication、および pwszSessionName メンバが設定されている。この中には、セッションに接続されているほかのクライアントに関する情報は含まれていない。このような情報は、サーバー アプリケーションのみが取得できる。特に、dwCurrentPlayers メンバは必ず 0 に設定する。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Peer::GetCaps

現在のインターフェイスの DPN_CAPS 構造体を取得する。

HRESULT GetCaps(
DPN_CAPS *const pdpnCaps,
const DWORD dwFlags
);

パラメータ

pdpnCaps
Caps 情報を受け取る DPN_CAPS 構造体へのポインタ。この構造体の dwSize メンバには適切な値を設定する必要がある。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER
DPNERR_UNINITIALIZED

注意

Initialize の呼び出しが成功した後に、このメソッドを呼び出す必要がある。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Peer::GetConnectionInfo

ローカル アプリケーションと指定されたリモート プレーヤーの接続に関する統計情報を取得する。

HRESULT GetConnectionInfo(
const DPNID dpnidEndPoint,
DPN_CONNECTION_INFO *const pdnConnectInfo,
const DWORD dwFlags
);

パラメータ

dpnidEndPoint
リモート プレーヤーの DPNID。プレーヤーの接続情報を取得する。
pdnConnectInfo
指定された接続に関する情報を取得する DPN_CONNECTION_INFO 構造体へのポインタ。この構造体の dwSize メンバには、DPN_CONNECTION_INFO 構造体のサイズを設定する必要がある。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER
DPNERR_UNINITIALIZED
DPNERR_INVALIDPLAYER

注意

Host または Connect の呼び出しが成功した後にのみ、このメソッドを呼び出すことができる。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Peer::GetGroupContext

指定されたグループのグループ コンテキスト値を取得する。

HRESULT GetGroupContext(
const DPNID dpnid,
PVOID *const ppvGroupContext,
const DWORD dwFlags
);

パラメータ

dpnid
グループの識別子を指定する DPNID 型の変数。このグループのコンテキスト データを取得する。
ppvGroupContext
グループのコンテキスト値へのポインタ。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDGROUP
DPNERR_INVALIDPARAM

注意

グループのコンテキスト値は、DPN_MSGID_CREATE_GROUP システム メッセージの pvGroupContext メンバをコンテキスト値のデータに示すことによって設定される。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Peer::GetGroupInfo

グループ名など、グループに関連付けられているデータのブロックを取得する。

通常、グループ データが変更されたことを示す DPN_MSGID_GROUP_INFO システム メッセージが受信された後、このメソッドが呼び出される。

HRESULT GetGroupInfo(
const DPNID dpnid,
DPN_GROUP_INFO *const pdpnGroupInfo,
DWORD *const pdwSize,
const DWORD dwFlags
);

パラメータ

dpnid
データ ブロックを取得するグループの識別子を指定する DPNID 型の変数。
pdpnGroupInfo
グループ データを記述する DPN_GROUP_INFO 構造体へのポインタ。pdwSize が NULL に設定されていない場合、pdpnGroupInfo.dwSize に DPN_GROUP_INFO 構造体のサイズを設定する必要がある。
pdwSize
データのサイズを pdpnGroupInfo パラメータに返す DWORD 型の変数へのポインタ。バッファが小さすぎる場合、このメソッドは DPNERR_BUFFERTOOSMALL を返す。このパラメータには、必要なサイズが設定される。
dwFlags
予約済み。0 に設定する。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDFLAGS
DPNERR_INVALIDGROUP

注意

Microsoft® DirectPlay® は DPN_GROUP_INFO 構造体と、連続するバッファにある、この構造体の pwszName メンバと pvData メンバに割り当てられたポインタを返す。この 2 つのポインタが設定される場合、構造体に加えて 2 つのポインタにも十分なメモリを割り当てておく必要がある。このメソッドを使用する最も確実な方法は、最初は pdwSize を NULL に設定してこのメソッドを呼び出すことである。メソッドが戻ると、pdwSize が正しい値をポイントしている。その値を使って構造体のメモリを再割り当てし、もう一度メソッドを呼び出して情報を取得する。

メソッドが戻ると、対応するポインタが NULL に設定されている場合でも、DPN_GROUP_INFO 構造体の dwInfoFlags メンバには常に DPNINFO_DATA フラグと DPNINFO_NAME フラグが設定されている。これらのフラグは IDirectPlay8Peer::SetGroupInfo を呼び出すときに使用され、DirectPlay に変更された値を通知する。

IDirectPlay8Peer::SetGroupInfo メソッドを使用すると処理に負担がかかるため、非静的情報は IDirectPlay8Peer::SendTo メソッドを使用して転送すること。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Peer::GetLocalHostAddresses

セッションをホストするために使用されるローカル アドレスを取得する。

HRESULT GetLocalHostAddresses(
IDirectPlay8Address **const prgpAddress,
DWORD *const pcAddress,
const DWORD dwFlags
);

パラメータ

prgpAddress
ローカル ホスト アドレスを指定する IDirectPlay8Address オブジェクトの配列へのポインタ。これらのオブジェクトは不要になったら解放しなければならない。解放しなかった場合、メモリ リークが発生する。
pcAddress
prgpAddress がポイントする配列に返すことができるアドレス オブジェクトの最大数。バッファが小さすぎる場合、このメソッドは DPNERR_BUFFERTOOSMALL を返す。このパラメータには、必要なサイズが設定される。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDOBJECT
DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER
DPNERR_UNINITIALIZED
DPNERR_NOTHOST

注意

このメソッドを使用する最も確実な方法は、最初は pcAddress を 0 に設定してこのメソッドを呼び出すことである。メソッドが戻ると、pcAddress が必要な値をポイントする。2 回目にこのメソッドを呼び出すときは、その値を使って情報を取得する。

呼び出し側がセッション ホストでない場合、メソッドは DPNERR_NOTHOST を返す。リモート プレーヤーのアドレスを取得するには、IDirectPlay8Peer::GetPeerAddress を取得する。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Peer::GetPeerAddress

セッションの指定されたプレーヤーのアドレスを取得する。

HRESULT GetPeerAddress(
const DPNID dpnid,
IDirectPlay8Address **const pAddress,
const DWORD dwFlags
);

パラメータ

dpnid
プレーヤーの識別情報を指定する DPNID 型の変数。
pAddress
ピアのアドレスを指定する IDirectPlay8Address オブジェクトへのポインタのアドレス。このオブジェクトは、不要になったら解放しなければならない。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPLAYER
DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER
DPNERR_UNINITIALIZED

注意

セッションへの接続に使用できるアドレスを取得するには、IDirectPlay8Peer::GetLocalHostAddresses を使用する。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Peer::GetPeerInfo

指定されたピアに設定されているピア情報を取得する。

HRESULT GetPeerInfo(
const DPNID dpnid,
DPN_PLAYER_INFO *const pdpnPlayerInfo,
DWORD *const pdwSize,
const DWORD dwFlags
);

パラメータ

dpnid
情報の取得対象となるピアの識別子を指定する DPNID 型の変数。
pdpnPlayerInfo
ピア情報を格納する DPN_PLAYER_INFO 構造体へのポインタ。pdwSize が NULL に設定されていない場合、pdpnPlayerInfo.dwSize に DPN_PLAYER_INFO 構造体のサイズを設定しなければならない。
pdwSize
pdpnPlayerInfo パラメータに返されるピア データのサイズを保持する DWORD 型の変数へのポインタ。バッファが小さすぎる場合、このメソッドは DPNERR_BUFFERTOOSMALL を返し、このパラメータには必要なバッファのサイズが入る。
dwFlags
予約済み。0 に設定すること。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM
DPNERR_INVALIDPLAYER

注意

ピアが情報を更新したことを表す DPN_MSGID_PEER_INFO メッセージをアプリケーションから受信した後、このメソッドを呼び出す。

Microsoft® DirectPlay® は DPN_PLAYER_INFO 構造体と、連続するバッファにある、この構造体の pwszName メンバと pvData メンバに割り当てられたポインタを返す。この 2 つのポインタが設定される場合、構造体に加えて 2 つのポインタにも十分なメモリを割り当てておく必要がある。このメソッドを使用する最も確実な方法は、最初は pdwSize を NULL に設定してこのメソッドを呼び出すことである。メソッドが戻ると、pdwSize が正しい値をポイントしている。その値を使って構造体のメモリを再割り当てし、もう一度メソッドを呼び出して情報を取得する。

メソッドが戻ると、対応するポインタが NULL に設定されている場合でも、DPN_PLAYER_INFO 構造体の dwInfoFlags メンバには常に DPNINFO_DATA フラグと DPNINFO_NAME フラグが設定されている。これらのフラグは IDirectPlay8Peer::SetPeerInfo を呼び出すときに使用され、DirectPlay に変更された値を通知する。

IDirectPlay8Peer::SetPeerInfo メソッドを使用すると処理に負担がかかるため、非静的情報は IDirectPlay8Peer::SendTo メソッドを使用して転送すること。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Peer::GetPlayerContext

指定されたピアのプレーヤーのコンテキスト値を取得する。

HRESULT GetPlayerContext(
const DPNID dpnid,
PVOID *const ppvPlayerContext,
const DWORD dwFlags
);

パラメータ

dpnid
コンテキスト データを取得するプレーヤーの識別子を指定する DPNID 型の変数。
ppvPlayerContext
ピアのコンテキスト データへのポインタ。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDPARAM
DPNERR_INVALIDPLAYER

注意

プレーヤーのコンテキスト値は、DPN_MSGID_CREATE_PLAYER システム メッセージの pvPlayerContext メンバをコンテキスト値のデータに示すことによって設定される。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Peer::GetSendQueueInfo

アプリケーションで送信キューのサイズを監視するために使用する。Microsoft® DirectPlay® は受信側コンピュータが処理できる以上の速度でメッセージを送信しない。そのため、送信元のコンピュータが、送信先が受け取れる速さよりも高速にメッセージを送信した場合、メッセージは送信側のキューに蓄積される。アプリケーションにより、送信キューのサイズが大きすぎると登録された場合は、メッセージの送信レートを低下させる必要がある。

HRESULT GetSendQueueInfo(
DWORD *const pdwNumMsgs,
DWORD *const pdwNumBytes,
const DWORD dwFlags
);

パラメータ

dpnid
送信キュー情報を取得するプレーヤーの DPNID。
pdwNumMsgs
現在キューに蓄積されているメッセージの数を保持する DWORD 型の変数へのポインタ。この値はオプションであり、NULL に設定できる。
pdwNumBytes
現在キューに蓄積されているメッセージ データの総バイト数を指定する DWORD 型の変数へのポインタ。この値はオプションであり、NULL に設定できる。
dwFlags
DPNGETSENDQUEUEINFO_PRIORITY_NORMAL、DPNGETSENDQUEUEINFO_PRIORITY_HIGH、または DPNGETSENDQUEUEINFO_PRIORITY_LOW フラグを指定して、その優先順位を持つ特定のメッセージについて問い合わせることができる。

戻り値

成功した場合は S_OK を返す。それ以外の場合は、次のエラー値を返す。

DPNERR_INVALIDPARAM

注意

pdwNumMsgs と pdwNumBytes の両方を NULL に設定することはできない。少なくともいずれか 1 つは有効なポインタに設定する必要がある。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Peer::GetSPCaps

指定されたサービス プロバイダの DPN_SP_CAPS 構造体を取得する。

HRESULT GetSPCaps(
const GUID *const pguidSP,
DPN_SP_CAPS *const pdpnSPCaps,
const DWORD dwFlags
);

パラメータ

pguidSP
情報を取得したいサービス プロバイダを指定する GUID へのポインタ。
pdpnSPCaps
指定したサービス プロバイダに関する情報を受け取る DPN_SP_CAPS 構造体へのポインタ。構造体の pdpnSPCaps.dwSize メンバを設定する必要がある。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER
DPNERR_UNINITIALIZED

注意

このメソッドは、指定したサービス プロバイダに関する情報を取得する。IDirectPlay8Peer::Initialize の呼び出しが成功した後に、このメソッドを呼び出す必要がある。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Peer::Host

ローカル コンピュータがホストする、新しいピアツーピア セッションを作成する。

HRESULT Host(
const DPN_APPLICATION_DESC *const pdnAppDesc,
IDirectPlay8Address **const prgpDeviceInfo,
const DWORD cDeviceInfo,
const DPN_SECURITY_DESC *const pdpSecurity,
const DPN_SECURITY_CREDENTIALS *const pdpCredentials,
VOID *const pvPlayerContext,
const DWORD dwFlags
);

パラメータ

pdnAppDesc
アプリケーションを記述する DPN_APPLICATION_DESC 構造体へのポインタ。
prgpDeviceInfo
アプリケーションをホストするために使用するデバイス アドレスを保持する IDirectPlay8Address オブジェクトの配列へのポインタ。これらのオブジェクトは、不要になったら解放しなければならない。
cDeviceInfo
prgpDeviceInfo が示す配列のデバイス アドレス オブジェクトの数を指定する DWORD 型の変数。
pdpSecurity
予約済み。NULL に設定しておく。
pdpCredentials
予約済み。NULL に設定しておく。
pvPlayerContext
ローカル プレーヤーのコンテキスト値へのポインタ。この値は、ローカル コンピュータが DPN_MSGID_CREATE_PLAYER メッセージを処理するときに事前に設定される。このパラメータはオプションであり、NULL に設定できる。
dwFlags
次のフラグを指定できる。
DPNHOST_OKTOQUERYFORADDRESSING
このフラグを設定すると、Microsoft® DirectPlay® の標準のダイアログ ボックスが表示される。十分な情報がこのメソッドに渡されていない場合は、詳細について問い合わされる。

戻り値

成功した場合は S_OK を返す。それ以外の場合は、次のエラー値を返す。

DPNERR_DATATOOLARGE
DPNERR_INVALIDPARAM
DPNERR_INVALIDDEVICEADDRESS

注意

dwFlags に DPNHOST_OKTOQUERYFORADDRESSING フラグを設定した場合、サービス プロバイダは、ダイアログ ボックスを表示して、ユーザーにアドレス情報の入力を求めようとする。サービス プロバイダがダイアログ ボックスの表示を試みるときには、表示可能なウィンドウが存在している必要がある。ウィンドウがない場合、アプリケーションはロックする。

DPN_APPLICATION_DESC 構造体の pvApplicationReservedData メンバに割り当てるアプリケーション データの最大サイズは、サービス プロバイダの Maximum Transmission Unit によって制限される。DPNERR_DATATOOLARGE.アプリケーション データが大きすぎる場合、メソッドは失敗し、DPNERR_DATATOOLARGE を返す。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Peer::Initialize

IDirectPlay8Peer インターフェイスおよびリモート ピアからのメッセージをすべて受信する、ピアのコード内のエントリ ポイントを登録する。このメソッドを呼び出してから、このインターフェイスのその他のメソッドを呼び出す必要がある。

HRESULT Initialize(
PVOID const pvUserContext,
const PFNDPNMESSAGEHANDLER pfn,
const DWORD dwFlags
);

パラメータ

pvUserContext
メッセージ ハンドラの呼び出しで指定される、ユーザー指定のコンテキスト値。ユーザー指定のコンテキスト値を使用すると、複数のインターフェイスから共通のメッセージ ハンドラに送信されたメッセージを区別できる。
pfn
PFNDPNMESSAGEHANDLER コールバック関数へのポインタ。リモート ピアからのすべてのメッセージおよび IDirectPlay8Peer インターフェイスからのセッション変更の通知を受け取るとき、この関数が使用される。
dwFlags
次のフラグを指定できる。
DPNINITIALIZE_DISABLEPARAMVAL
このフラグを渡すと、現在のオブジェクトに対するパラメータ妥当性の検証が無効になる。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM

注意

IDirectPlay8Peer インターフェイスを取得するには、CoCreateInstance を使用した後にこのメソッドを呼び出す。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Peer::RegisterLobby

起動したアプリケーションが、ゲーム状態を自動的にロビーに転送できるようにする。

HRESULT RegisterLobby(
const DPNHANDLE dpnHandle,
IDirectPlay8LobbiedApplication *const pIDP8LobbiedApplication,
const DWORD dwFlags
);

パラメータ

dpnHandle
IDirectPlay8LobbiedApplication::UpdateStatus を呼び出すときに使用する接続ハンドル。
pIDP8LobbiedApplication
アプリケーションを指定する IDirectPlay8LobbiedApplication オブジェクトへのポインタ。
dwFlags
次のフラグのいずれかを指定する。
DPNLOBBY_REGISTER
ロビーをアプリケーションに登録する。
DPNLOBBY_UNREGISTER
アプリケーションへのロビーの登録を解除する。

戻り値

成功した場合は S_OK を返す。それ以外の場合は、次のエラー値を返す。

DPNERR_INVALIDPARAM

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Peer::RemovePlayerFromGroup

グループからピアを削除する。

このメソッドを呼び出すと、アプリケーションに接続されているすべてのピアは DPN_MSGID_REMOVE_PLAYER_FROM_GROUP メッセージを受信する。

HRESULT RemovePlayerFromGroup(
const DPNID idGroup,
const DPNID idClient,
PVOID const pvAsyncContext,
DPNHANDLE *const phAsyncHandle,
const DWORD dwFlags
);

パラメータ

idGroup
ピアが削除されるグループの識別子を指定する DPNID 型の変数。
idClient
グループから削除されるピアの識別子を指定する DPNID 型の変数。
pvAsyncContext
ユーザー指定のコンテキストへのポインタ。これは、DPN_MSGID_ASYNC_OP_COMPLETE システム メッセージの pvUserContext メンバに返される。
phAsyncHandle
A DPNHANDLE.値が返される。ただし、Microsoft® DirectPlay® 8.0 ではこの操作の取り消しは許可されていないため、値を使用することはできない。
dwFlags
このメソッドが処理される方法を制御するフラグ。このメソッドには、次のフラグを設定できる。
DPNREMOVEPLAYERFROMGROUP_SYNC
メソッドを同期をとりながら処理する。

戻り値

メソッドが同期をとりながら処理され、処理が成功した場合は S_OK を返す。デフォルトでは、このメソッドは非同期に実行され、通常の場合は、DPNSUCCESS_PENDING を返す。また、次のいずれかのエラー値を返す場合もある。

DPNERR_INVALIDFLAGS
DPNERR_INVALIDGROUP
DPNERR_INVALIDPLAYER

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Peer::ReturnBuffer

DPN_MSGID_RECEIVE システム メッセージの pReceiveData メンバによってアプリケーションに提供されるメッセージ バッファを取得する。ユーザーのメッセージ ハンドラが RECEIVE コールバックに DPNSUCCESS_PENDING を返した場合、バッファの所有権はアプリケーションに移行したと見なされ、この呼び出しにより所有権が Microsoft® DirectPlay® に戻るまで所有権の解放や変更は行われない。

HRESULT ReturnBuffer(
const DPNHANDLE hBufferHandle,
const DWORD dwFlags
);

パラメータ

hBufferHandle
メッセージ用のバッファ ハンドルを指定する DPNHANDLE 型の変数。これは、DPN_MSGID_RECEIVE システム メッセージの hBufferHandle メンバで取得する。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDHANDLE
DPNERR_INVALIDPARAM

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Peer::SendTo

適切なメッセージ ハンドラにメッセージを送ることによって、セッション内の別のピアまたはグループにデータを送信する。メッセージは同期または非同期で送信することができる。

HRESULT SendTo(
const DPNID dpnid,
const DPN_BUFFER_DESC *const pBufferDesc,
const DWORD cBufferDesc,
const DWORD dwTimeOut,
void *const pvAsyncContext,
DPNHANDLE *const phAsyncHandle,
const DWORD dwFlags
);

パラメータ

dpnid
データを受信するピアまたはグループの識別子。セッション内のすべてのプレーヤーにメッセージを送信する場合は、このパラメータを DPNID_ALL_PLAYERS_GROUP に設定する。
pBufferDesc
送信するデータを保持する DPN_BUFFER_DESC 構造体へのポインタ。
cBufferDesc
pBufferDesc が示す DPN_BUFFER_DESC 構造体の数。このバージョンの Microsoft® DirectPlay® では、バッファは 1 つでなければならない。
dwTimeOut
メッセージの送信を待つ時間 (ミリ秒単位)。メッセージが dwTimeOut 値で送信されていない場合、メッセージは送信されない。メッセージの送信に対してタイム アウトが必要でない場合は、このパラメータを 0 に設定する。
pvAsyncContext
ユーザー指定のコンテキストへのポインタ。これは、DPN_MSGID_SEND_COMPLETE システム メッセージの pvUserContext メンバに返される。このパラメータはオプションであり、NULL に設定できる。
phAsyncHandle
DPNHANDLE。メソッドが戻ると、phAsyncHandle は、IDirectPlay8Peer::CancelAsyncOperation に渡して処理を取り消すことができるハンドルをポイントする。dwFlags に DPNSEND_SYNC フラグが設定されている場合、このパラメータは NULL に設定しなければならない。
dwFlags
送信動作を記述するフラグ。次の 1 つ以上のフラグを設定することができる。
DPNSEND_SYNC
SendTo 要求を同期をとりながら処理する。
DPNSEND_NOCOPY
DPN_BUFFER_DESC 構造体のデータを使用し、内部コピーは行わない。これは、効率的なデータ送信の方法である。しかし、受信側がメッセージを処理する前に、送信側がメッセージを変更できるため、堅牢ではなくなる。このフラグを DPNSEND_NOCOMPLETE と組み合わせることはできない。
DPNSEND_NOCOMPLETE
メッセージ ハンドラに DPN_MSGID_SEND_COMPLETE を送信しない。このフラグを DPNSEND_NOCOPY または DPNSEND_GUARANTEED と共に使用することはできない。また、このフラグを使用する場合、pvAsyncContext は NULL でなければならない。
DPNSEND_COMPLETEONPROCESS
メッセージがターゲットに配信され、メッセージの受信を示すターゲットのメッセージ ハンドラが返されるとき、DPN_MSGID_SEND_COMPLETE をメッセージ ハンドラに送信する。このフラグが設定された場合は、余分な内部メッセージのオーバーヘッドがあり、メッセージの送信処理が著しく低下する可能性がある。このフラグを設定した場合は、DPNSEND_GUARANTEED も設定する必要がある。
DPNSEND_GUARANTEED
保証付き配信方式を使用してメッセージを送信する。
DPNSEND_PRIORITY_HIGH
メッセージの優先順位を高く設定する。このフラグを DPNSEND_PRIORITY_LOW と共に使用することはできない。
DPNSEND_PRIORITY_LOW
メッセージの優先順位を低く設定する。このフラグを DPNSEND_PRIORITY_HIGH と共に使用することはできない。
DPNSEND_NONSEQUENTIAL
このフラグが設定された場合、ターゲット アプリケーションは、ユーザーのコンピュータに到着した順にメッセージを受け取る。このフラグが設定されていない場合、メッセージはシーケンシャルに配信され、ターゲット アプリケーションは送信された順にメッセージを受け取る。したがって、着信したメッセージを、欠落しているメッセージが到着するまでバッファに格納する場合がある。
DPNSEND_NOLOOPBACK
ローカル プレーヤーを含むグループに送信しているときに、メッセージ ハンドラへの DPN_MSGID_RECEIVE システム メッセージを抑制する。たとえば、セッション全体にある要素を全要素にコピーする場合は、このフラグが便利である。

戻り値

メソッドが同期をとりながら処理され、処理が成功した場合は S_OK を返す。デフォルトでは、このメソッドは非同期に実行され、通常の場合は、DPNSUCCESS_PENDING を返す。また、次のいずれかのエラー値を返す場合もある。

DPNERR_CONNECTIONLOST
DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM
DPNERR_INVALIDPLAYER
DPNERR_TIMEDOUT

注意

このメソッドは、受け取り側のメッセージ ハンドラに DPN_MSGID_RECEIVE システム メッセージを生成する。データ バッファは、関連付けられている構造体の pReceiveData メンバに保持されている。

メッセージには、低、通常、高の 3 つの優先順位のいずれかを設定できる。メッセージに低い優先順位または高い優先順位を指定するには dwFlags に適切なフラグを設定する。どちらの優先順位フラグも設定しなかった場合、メッセージは通常の優先順位になる。送信優先順位の詳細については、「ネットワーキングの基本」を参照すること。

SendTo 要求が完了すると、送信側のメッセージ ハンドラに DPN_MSGID_SEND_COMPLETE システム メッセージが送信される。要求の成功または失敗は、関連付けられた構造体の hResultCode メンバに保持される。dwFlags に DPNSEND_NOCOMPLETE フラグを設定すると、送信完了のシステム メッセージは送信されない。

通常、メッセージが送信されると直ちに、送信完了が送信元のコンピュータに送信される。言い換えると、送信完了は、メッセージがターゲット上で処理されたことを必ずしも意味しない。メッセージはまだキュー内にある可能性もある。メッセージがターゲットで処理されたことを確認するには、dwFlags にDPNSEND_COMPLETEONPROCESS フラグを設定する。このフラグを設定すると、ターゲットのメッセージ ハンドラがメッセージを処理して戻るまで、送信完了は送信されない。

アプリケーションは IDirectPlay8Client、IDirectPlay8Server、または IDirectPlay8Peer で Close を呼び出す前や最終リリースをする前に、CancelAsyncOperation を呼び出して残っている Send をキャンセルすべきである。それに失敗すると予期せぬ結果が起きる。

注 メソッドが戻るまでは、データ バッファなどのリソースが有効な状態のままであると見なしてはならない。このメソッドを非同期に呼び出す場合、呼び出しが戻る前に DPN_MSGID_SEND_COMPLETE メッセージを受け取り、メッセージ ハンドラが処理してしまうことがある。メッセージ ハンドラがデータ バッファなどのリソースを割り当て解除、または無効にした場合、メソッドが呼び出された後でリソースが無効になることがある。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Peer::SetApplicationDesc

ホストされるアプリケーションの設定を変更する。変更できるのは、いくつかの設定のみである。

HRESULT SetApplicationDesc(
const DPN_APPLICATION_DESC *const pad,
const DWORD dwFlags
);

パラメータ

pad
変更するアプリケーションの設定を記述する DPN_APPLICATION_DESC 構造体へのポインタ。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_DATATOOLARGE
DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM
DPNERR_NOTHOST

注意

このメソッドを使って、DPN_APPLICATION_DESC 構造体の以下のメンバのみを変更できる。

  • dwMaxPlayers
  • pwszSessionName
  • pwszPassword
  • pvApplicationReservedData
  • dwApplicationReservedDataSize

DPN_APPLICATION_DESC 構造体の pvApplicationReservedData メンバに割り当てるアプリケーション データの最大サイズは、サービス プロバイダの Maximum Transmission Unit によって制限される。アプリケーション データが大きすぎる場合、メソッドは失敗し、DPNERR_DATATOOLARGE を返す。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Peer::SetCaps

現在のインターフェイスの DPN_CAPS 構造体を設定する。

HRESULT SetCaps(
const DPN_CAPS *const pdpCaps,
const DWORD dwFlags
);

パラメータ

pdpCaps
現在のインターフェイスに関する情報の設定に使用される DPN_CAPS 構造体へのポインタ。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER
DPNERR_UNINITIALIZED

注意

このメソッドは、指定されたサービス プロバイダに対するパラメータを設定する。Initialize の呼び出しが成功した後に、このメソッドを呼び出す必要がある。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Peer::SetGroupInfo

グループ名など、グループに関連するデータのブロックを設定する。

このメソッドを呼び出すと、DPN_MSGID_GROUP_INFO メッセージが生成される。このメッセージは、アプリケーションに接続されているすべてのピアに送信される。

HRESULT SetGroupInfo(
const DPNID dpnid,
DPN_GROUP_INFO *const pdpnGroupInfo,
PVOID const pvAsyncContext,
DPNHANDLE *const phAsyncHandle,
const DWORD dwFlags
);

パラメータ

dpnid
データ ブロックを変更するグループの識別子を指定する DPNID 型の変数。
pdpnGroupInfo
設定するグループ データを記述する DPN_GROUP_INFO 構造体へのポインタ。pwszName または pvData メンバの値を変更するには、対応する DPNINFO_NAME フラグまたは DPNINFO_DATA フラグを dwInfoFlags メンバを設定する必要がある。
pvAsyncContext
ユーザー指定のコンテキストへのポインタ。これは、DPN_MSGID_ASYNC_OP_COMPLETE システム メッセージの pvUserContext メンバに返される。
phAsyncHandle
DPNHANDLE。値が返される。ただし、Microsoft® DirectPlay® 8.0 ではこの操作の取り消しは許可されていないため、値を使用することはできない。
dwFlags
このメソッドが処理される方法を制御するフラグ。このメソッドには、次のいずれかの値を設定できる。
DPNSETGROUPINFO_SYNC
メソッドを同期をとりながら処理する。

戻り値

メソッドが同期をとりながら処理され、処理が成功した場合は S_OK を返す。デフォルトでは、このメソッドは非同期に実行され、通常の場合、DPNSUCCESS_PENDING を返す。また、次のいずれかのエラー値を返す場合もある。

DPNERR_INVALIDFLAGS
DPNERR_INVALIDGROUP

注意

IDirectPlay8Peer::SetGroupInfo メソッドを使用すると処理に負担がかかるため、非静的情報は IDirectPlay8Peer::SendTo メソッドを使用して転送すること。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Peer::SetPeerInfo

ローカル ピアの静的設定を設定する。アプリケーションに基本的なプレーヤー情報を転送するには、接続前にこのメソッドを呼び出す。ピアが正しくアプリケーションに接続すると、ほかのプレーヤーはこのメソッドで設定された情報を IDirectPlay8Peer::GetPeerInfo メソッドを呼び出して取得できる。

HRESULT SetPeerInfo(
const DPN_PLAYER_INFO *const pdpnPlayerInfo,
PVOID const pvAsyncContext,
DPNHANDLE *const phAsyncHandle,
const DWORD dwFlags
);

パラメータ

pdpnPlayerInfo
設定するピア情報を保持する DPN_PLAYER_INFO 構造体へのポインタ。
pvAsyncContext
ユーザー指定のコンテキストへのポインタ。これは、DPN_MSGID_ASYNC_OP_COMPLETE システム メッセージの pvUserContext メンバに返される。
phAsyncHandle
DPNHANDLE。値が返される。ただし、Microsoft® DirectPlay® 8.0 ではこの操作の取り消しは許可されていないため、値を使用することはできない。
dwFlags
このメソッドが処理される方法を制御するフラグ。このメソッドには、次のフラグを設定できる。
DPNSETPEERINFO_SYNC
メソッドを同期をとりながら処理する。

戻り値

メソッドが同期をとりながら処理され、処理が成功した場合は S_OK を返す。デフォルトでは、このメソッドは非同期に実行され、通常の場合、DPNSUCCESS_PENDING を返す。また、次のいずれかのエラー値を返す場合もある。

DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM
DPNERR_NOCONNECTION

注意

このメソッドは、セッション中いつでも呼び出すことができる。

IDirectPlay8Peer::SetPeerInfo メソッドを使用すると処理に負担がかかるため、非静的情報は IDirectPlay8Peer::SendTo メソッドを使用して転送すること。

アプリケーションへの接続後、このメソッドを使用してピア情報を変更できる。接続後にこのメソッドを呼び出すと、データの更新を知らせる DPN_MSGID_PEER_INFO システム メッセージがすべてのプレーヤーに対して生成される。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Peer::SetSPCaps

指定されたサービス プロバイダの DPN_SP_CAPS 構造体を設定する。

HRESULT SetSPCaps(
const GUID *const pguidSP,
const DPN_SP_CAPS *const pdpSPCaps
);

パラメータ

pguidSP
情報を設定するサービス プロバイダを指定する GUID へのポインタ。
pdpSPCaps
指定したサービス プロバイダに関する情報を設定する DPN_SP_CAPS 構造体へのポインタ。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER
DPNERR_UNINITIALIZED

注意

このメソッドは、指定されたサービス プロバイダに対するパラメータを設定する。Initialize の呼び出しが成功した後に、このメソッドを呼び出す必要がある。現在、この呼び出しでは dwNumThreads フィールドのみ設定することができる。dwFlags フィールドは 0 でなければならない。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Peer::TerminateSession

現在の Microsoft® DirectPlay® セッションを終了する。

HRESULT TerminateSession(
void *const pvTerminateData,
const DWORD dwTerminateDataSize,
const DWORD dwFlags
);

パラメータ

pvTerminateData
終了データへのポインタ。このデータは、DPN_MSGID_TERMINATE_SESSION システム メッセージの pvTerminateData メンバにも送信される。
dwTerminateDataSize
pvTerminateData パラメータに保持されるデータのサイズ。
dwFlags
予約済み。0 に設定しておく。

注意

このメソッドはホスト プレーヤーのみ呼び出すことができる。

このメソッドが呼び出されると、セッションの各プレーヤーのメッセージ ハンドラに DPN_MSGID_TERMINATE_SESSION が送信される。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Client

アプリケーションは、IDirectPlay8Client インターフェイスのメソッドを使用して、クライアント/サーバー セッション用のクライアント アプリケーションの作成と管理を行う。

IDirectPlay8Client インターフェイスのメソッドは、次のように分類できる。

セッション管理 | Close
 | Connect
 | EnumHosts
 | EnumServiceProviders
 | GetApplicationDesc
 | GetCaps
 | GetSPCaps
 | SetCaps
 | SetSPCaps
メッセージ管理 | GetSendQueueInfo
 | Initialize
 | ReturnBuffer
 | Send
クライアント情報 | SetClientInfo
サーバー情報 | GetServerInfo
その他 | CancelAsyncOperation
 | RegisterLobby
 | GetConnectionInfo
 | GetServerAddress


IDirectPlay8Client::CancelAsyncOperation

非同期の要求を取り消す。デフォルトでは、IDirectPlay8Client インターフェイスの多くのメソッドが非同期に実行される。状況に応じて、要求が処理される前にその要求を取り消したい場合もある。このインターフェイスで非同期に実行できるすべてのメソッドは、hAsyncHandle パラメータを返す。

要求の hAsyncHandle をこのメソッドの hAsyncHandle パラメータに渡すことによって、特定の要求が取り消される。このメソッドを呼び出し、hAsyncHandle パラメータに NULL を、dwFlags パラメータに DPNCANCEL_ALL_OPERATIONS を指定することによって、待機中のすべての非同期処理を取り消すことができる。特定のハンドルがこのメソッドに指定された場合は、いずれのフラグも設定してはならない。

HRESULT CancelAsyncOperation(
const DPNHANDLE hAsyncHandle,
const DWORD dwFlags
);

パラメータ

hAsyncHandle
非同期処理を停止するハンドル。このハンドルは、非同期の処理をサポートするメソッドを呼び出したときに受け取る。すべての要求または特定の種類の非同期要求を停止するには、この値を NULL にする。特定のハンドルが指定されている場合、dwFlags パラメータは 0 に設定する必要がある。
dwFlags
取り消す非同期要求を指定するフラグ。次のいずれかのフラグを設定できる。
DPNCANCEL_ENUM
すべての非同期 IDirectPlay8Client::EnumHosts 要求を取り消す。EnumHosts メソッドから返されるハンドルを指定することによって、単一の EnumHosts 要求を取り消すことができる。
DPNCANCEL_CONNECT
非同期 IDirectPlay8Client::Connect 要求を取り消す。
DPNCANCEL_SEND
非同期 IDirectPlay8Client::Send 要求を取り消す。
DPNCANCEL_ALL_OPERATIONS
すべての非同期要求を取り消す。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_CANNOTCANCEL
DPNERR_INVALIDFLAGS
DPNERR_INVALIDHANDLE
DPNSUCCESS_PENDING

注意

このメソッドを使って、IDirectPlay8Client::Connect、IDirectPlay8Client::Send、および IDirectPlay8Client::EnumHosts メソッドの非同期処理を取り消すことができる。Microsoft® DirectPlay® 8.0 は、他の非同期処理の取り消しをサポートしていない。

IDirectPlay8Client::Send メソッドから返されたハンドルを指定すると、送信を取り消すことができる。その場合も、DPN_MSGID_SEND_COMPLETE システム メッセージは、DPNSEND_NOCOMPLETE フラグを設定せずに送信された非同期送信要求ごとに、アプリケーション メッセージ ハンドラに送信される。このメソッドで取り消された送信は、DPN_MSGID_SEND_COMPLETE メッセージの hResultCode メンバに DPNERR_USERCANCEL を返す。

dwFlags に DPNCANCEL_ALL_OPERATIONS、DPNCANCEL_CONNECT、DPNCANCEL_SEND、または DPNCANCEL_ENUM を設定した場合、DirectPlay はすべての一致する処理を取り消そうとする。このメソッドは、取り消しに失敗した処理がある場合、一部の取り消しが成功していてもエラーを返す。

注 このメソッドが戻るまで、完了メッセージが到着しない場合がある。DPN_MSGID_SEND_COMPLETE、DPN_MSGID_CONNECT_COMPLETE、または DPN_MSGID_ASYNC_OP_COMPLETE メッセージを受け取るまで、処理が終了したと見なしてはならない。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Client::Close

セッションとのオープン接続を閉じる。このメソッドは、IDirectPlay8Client::Initialize メソッドの呼び出しによって正しく初期化されたすべてのオブジェクトで呼び出す必要がある。

HRESULT Close(
const DWORD dwFlags
);

パラメータ

dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は S_OK を返す。それ以外の場合は、次のエラー値を返す。

DPNERR_UNINITIALIZED

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Client::Connect

サーバーへの接続を確立する。接続が確立すると、インターフェイス上の通信チャネルが開き、アプリケーションはメッセージの到着を待機する。接続が完了するまで、IDirectPlay8Client::Send メソッドを使用してメッセージを送信できない。

このメソッドを呼び出す前に、IDirectPlay8Client::EnumHosts を呼び出してアプリケーションの記述を取得することができる。EnumHosts メソッドは、ホストされているアプリケーションごとに DPN_APPLICATION_DESC 構造体を返す。この構造体は、アプリケーションの GUID を含め、アプリケーションを記述する。

このメソッドが非同期に呼び出される場合 (デフォルト)、接続が完了すると、アプリケーションのメッセージ ハンドラに DPN_MSGID_CONNECT_COMPLETE メッセージが送信される。

HRESULT Connect(
const DPN_APPLICATION_DESC *const pdnAppDesc,
IDirectPlay8Address *const pHostAddr,
IDirectPlay8Address *const pDeviceInfo,
const DPN_SECURITY_DESC *const pdnSecurity,
const DPN_SECURITY_CREDENTIALS *const pdnCredentials,
const void *const pvUserConnectData,
const DWORD dwUserConnectDataSize,
void *const pvAsyncContext,
DPNHANDLE *const phAsyncHandle,
const DWORD dwFlags
);

パラメータ

pdnAppDesc
アプリケーションを記述する DPN_APPLICATION_DESC 構造体へのポインタ。設定する必要があるこの構造体の唯一のメンバは、guidApplication メンバである。このメソッドで使用されるのは、この構造体の一部のメンバのみである。設定する必要がある唯一のメンバは、guidApplication である。guidInstance、pwszPassword、dwFlags、および dwSize も設定できる。
pHostAddr
IDirectPlay8Address へのポインタ。このインターフェイスは、ホストするコンピュータへの接続に使用されるアドレス情報を指定する。
pDeviceInfo
IDirectPlay8Address オブジェクトへのポインタ。このオブジェクトは、サーバーとの接続に使用するネットワーク アダプタ (NIC やモデムなど) を指定する。
pdnSecurity
予約済み。NULL に設定しておく。
pdnCredentials
予約済み。NULL に設定しておく。
pvUserConnectData
接続を詳しく確認するためにホストまたはサーバーに提供されるアプリケーション固有のデータへのポインタ。このデータは、pvUserConnectData メンバの DPN_MSGID_INDICATE_CONNECT メッセージに送信される。このパラメータはオプションであり、NULL を渡すと、ユーザー コードにより提供される接続の確認をバイパスすることができる。
dwUserConnectDataSize
pvUserConnectData に保持されるデータのサイズを指定する DWORD 型の変数。
pvAsyncContext
ユーザー指定のコンテキストへのポインタ。これは、DPN_MSGID_CONNECT_COMPLETE システム メッセージの pvUserContext メンバに返される。このパラメータはオプションであり、NULL に設定できる。
phAsyncHandle
DPNHANDLE。メソッドが戻ると、phAsyncHandle は、IDirectPlay8Client::CancelAsyncOperation に渡して処理を取り消すことができるハンドルをポイントする。dwFlags に DPNCONNECT_SYNC フラグが設定されている場合、このパラメータは NULL に設定しなければならない。
dwFlags
接続モードを記述するフラグ。次のフラグを設定できる。
DPNCONNECT_OKTOQUERYFORADDRESSING
このフラグを設定すると、Microsoft® DirectPlay® の標準のダイアログ ボックスが表示される。十分な情報がこのメソッドに渡されていない場合は、詳細について問い合わされる。
DPNCONNECT_SYNC
接続要求を同期をとりながら処理する。このフラグを設定すると、DPN_MSGID_CONNECT_COMPLETE システム メッセージは生成されない。

戻り値

メソッドが同期をとりながら処理され、処理が成功した場合は S_OK を返す。要求が非同期で処理される場合、メソッドが直ちに処理されると、S_OK を返す。デフォルトでは、このメソッドは非同期に実行され、通常は DPNSUCCESS_PENDING か、または次のいずれかのエラー値を返す。

DPNERR_HOSTREJECTEDCONNECTION
DPNERR_INVALIDAPPLICATION
DPNERR_INVALIDDEVICEADDRESS
DPNERR_INVALIDFLAGS
DPNERR_INVALIDHOSTADDRESS
DPNERR_INVALIDINSTANCE
DPNERR_INVALIDINTERFACE
DPNERR_INVALIDPASSWORD
DPNERR_NOCONNECTION
DPNERR_NOTHOST
DPNERR_SESSIONFULL
DPNERR_ALREADYCONNECTED

注意

複数の列挙を同時に実行し、1 つの接続中に実行できるが、インターフェイスごとに 1 つの接続しか利用できない。1 つ以上のアプリケーションへの接続を確立するには、別のインターフェイスを作成しなければならない。

このメソッドが呼び出されると、サーバーのメッセージ ハンドラに DPN_MSGID_INDICATE_CONNECT メッセージが送信される。このメッセージの取得時、ホストは接続応答データを Connect メソッドに渡すことがある。接続応答データは、ホストが接続を承認しないことを示すメッセージを送信することがある。その後呼び出し元アプリケーションは、この応答を適切に処理することができる。

Connect() が成功した場合、完了時の hResultCode は S_OK を示す。それ以外の場合は、エラーを示す。Host プレーヤーが DPN_MSGID_INDICATE_CONNECT メッセージから S_OK 以外を返した場合、完了のエラー コードは DPNERR_HOSTREJECTEDCONNECTION であることが多い。

接続が完了すると、アプリケーションのメッセージ ハンドラに DPN_MSGID_CONNECT_COMPLETE メッセージが送信される。

このメソッドで確立した接続を閉じるには、IDirectPlay8Client::Close メソッドを呼び出す。Connect() への呼び出しが成功した後、すべての残っている列挙は DPNERR_USERCANCEL を返してキャンセルされる。

注 dwFlags に DPNCONNECT_OKTOQUERYFORADDRESSING フラグを設定した場合、サービス プロバイダは、ダイアログ ボックスを表示して、ユーザーにアドレス情報の入力を求めようとする。サービス プロバイダがダイアログ ボックスの表示を試みるときには、表示可能なウィンドウが存在している必要がある。ウィンドウがない場合、アプリケーションはロックする。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Client::EnumHosts

Microsoft® DirectPlay® ゲームをホストするアプリケーションを列挙する。列挙基準を満たすアプリケーションが見つかると、DPN_MSGID_ENUM_HOSTS_RESPONSE システム メッセージによりアプリケーションのメッセージ ハンドラが呼び出される。メッセージには、見つかったアプリケーションを記述する DPN_APPLICATION_DESC 構造体が保持される。

任意の数の列挙を同時に実行できる。異なる複数の列挙への応答を区別するために、pvUserContext の値がメッセージ ハンドラに提供される。

列挙の処理にはさまざまな方法があるため、メディアに関して特に知識がない限り、アプリケーションでは dwEnumPeriod、dwRetryInterval、または dwTimeOut を指定しないことを推奨する。

デフォルトの列挙カウント値とタイムアウト値で、EnumHosts は適切な時間内に終了する。これらの値はサービス プロバイダによって設定され、IDirectPlay8Client::GetSPCaps を呼び出して取得できる。非同期の列挙は、IDirectPlay8Client::CancelAsyncOperation を呼び出すか、または dwFlags パラメータに pAsyncHandle パラメータに返されたハンドラを渡すか DPENUM_CANCEL フラグを設定すれば、いつでも停止できる。メッセージ ハンドラから S_OK 以外の値を返して、列挙を停止することもできる。

HRESULT EnumHosts(
PDPN_APPLICATION_DESC const pApplicationDesc,
IDirectPlay8Address *const pdpaddrHost,
IDirectPlay8Address *const pdpaddrDeviceInfo,
PVOID const pvUserEnumData,
const DWORD dwUserEnumDataSize,
const DWORD dwEnumCount,
const DWORD dwRetryInterval,
const DWORD dwTimeOut,
PVOID const pvUserContext,
HANDLE *const pAsyncHandle,
const DWORD dwFlags
);

パラメータ

pApplicationDesc
列挙するアプリケーションのホストを指定する DPN_APPLICATION_DESC 構造体へのポインタ。pApplicationDesc.dwSize メンバを適切な値に設定しなければならない。応答の数を減らすには、pApplicationDesc.guidApplication に検索するアプリケーションの GUID を設定する。このメンバが設定されていない場合、すべてのアプリケーションが検索対象になる。
pdpaddrHost
アプリケーションをホストしているコンピュータのアドレスを指定する IDirectPlay8Address オブジェクトへのポインタ。NULL を指定した場合、DirectPlay がアドレスを作成する。デフォルトでは、DirectPlay は pdpaddrDeviceInfo パラメータからアドレスを作成する。dwFlags に DPNENUMHOSTS_OKTOQUERYFORADDRESSING フラグを設定した場合、ユーザーにアドレス情報を照会することができる。
pdpaddrDeviceInfo
列挙に使用するサービス プロバイダおよびローカル デバイスの設定を指定する IDirectPlay8Address オブジェクトへのポインタ。
pvUserEnumData
列挙要求からホストに送信されるデータ ブロックへのポインタ。データのサイズは、ネットワークのタイプによって制限される。IDirectPlay8Client::GetSPCaps を呼び出して正確な値を取得する。
dwUserEnumDataSize
pvUserEnumData パラメータで示すデータのサイズを指定する DWORD 型の変数。
dwEnumCount
列挙データを送信する回数を指定する値。デフォルト値を使用するには、このパラメータを 0 に設定する。dwEnumCount のデフォルト値を取得するには、IDirectPlay8Client::GetSPCaps を呼び出す。dwEnumCount に INFINITE が指定された場合、列挙は取り消されるまで続行される。
dwRetryInterval
列挙の再試行の間隔をミリ秒単位で指定する値。デフォルト値を使用するには、このパラメータを 0 に設定する。dwRetryInterval のデフォルト値を取得するには、IDirectPlay8Client::GetSPCaps を呼び出す。
dwTimeOut
最後の列挙が送信された後、DirectPlay が応答を待つ時間 (ミリ秒) を指定する、DWORD 型の変数。デフォルト値を使用するには、このパラメータを 0 に設定する。dwTimeOut のデフォルト値を取得するには、IDirectPlay8Client::GetSPCaps を呼び出す。INFINITE が指定された場合、列挙は取り消されるまで続行される。
pvUserContext
列挙への応答と共に呼び出された場合に、クライアントのメッセージ ハンドラに提供されるコンテキスト。同時実行されている列挙の応答を区別する場合に役立つ。
pAsyncHandle
DPNHANDLE。メソッドが戻ると、phAsyncHandle は、IDirectPlay8Client::CancelAsyncOperation に渡して処理を取り消すことができるハンドルをポイントする。dwFlags に DPNENUMHOSTS_SYNC フラグが設定されている場合、このパラメータは NULL に設定しなければならない。
dwFlags
次のフラグを設定できる。
DPNENUMHOSTS_SYNC
メソッドを同期をとりながら処理する。
DPNENUMHOSTS_OKTOQUERYFORADDRESSING
このフラグを設定すると、DirectPlay の標準ダイアログ ボックスが表示される。十分な情報がこのメソッドに渡されていない場合は、詳細について問い合わされる。
DPNENUMHOSTS_NOBROADCASTFALLBACK
サービス プロバイダがある要素を全要素にコピーすることをサポートしている場合、このフラグを設定するとある要素を全要素にコピーする機能が無効になる。このフラグを設定する前に DPN_SP_CAPS 構造体を調べ、ある要素を全要素にコピーすることがサポートされているかどうかを確認すること。

戻り値

メソッドが同期をとりながら処理され、処理が成功した場合は S_OK を返す。要求が非同期で処理される場合、メソッドが直ちに処理されると、S_OK を返す場合がある。デフォルトでは、このメソッドは非同期に実行され、通常は DPNSUCCESS_PENDING か、または次のいずれかのエラー値を返す。

DPNERR_INVALIDDEVICEADDRESS
DPNERR_INVALIDFLAGS
DPNERR_INVALIDHOSTADDRESS
DPNERR_INVALIDPARAM
DPNERR_ENUMQUERYTOOLARGE

注意

dwFlags に DPNENUMHOSTS_OKTOQUERYFORADDRESSING フラグを設定した場合、サービス プロバイダは、ダイアログ ボックスを表示して、ユーザーにアドレス情報の入力を求めようとする。サービス プロバイダがダイアログ ボックスの表示を試みるときには、表示可能なウィンドウが存在している必要がある。ウィンドウがない場合、アプリケーションはロックする。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Client::EnumServiceProviders

アプリケーションで使用できる登録済みサービス プロバイダを列挙する。

HRESULT EnumServiceProviders(
const GUID *const pguidServiceProvider,
const GUID *const pguidApplication,
DPN_SERVICE_PROVIDER_INFO *const pSPInfoBuffer,
PDWORD const pcbEnumData,
PDWORD const pcReturned,
const DWORD dwFlags
);

パラメータ

pguidServiceProvider
サービス プロバイダを指定する GUID 型の変数へのポインタ。このオプション パラメータは、指定したサービス プロバイダのサブデバイスを列挙させる。通常はこの値に NULL を設定して、使用できるすべてのサービス プロバイダを列挙する。
pguidApplication
アプリケーションを指定する GUID 型の変数へのポインタ。このパラメータにポインタが渡された場合は、アプリケーションに接続できるサービス プロバイダだけが列挙される。NULL を渡して、システムに登録済みのサービス プロバイダを列挙することもできる。
pSPInfoBuffer
サービス プロバイダ情報を保持する、DPN_SERVICE_PROVIDER_INFO 構造体の配列へのポインタ。
pcbEnumData
バッファが小さすぎる場合、pEnumData バッファのサイズが格納される DWORD へのポインタ。
pcReturned
pEnumData 配列に返される DPN_SERVICE_PROVIDER_INFO 構造体の数を指定する DWORD 型の変数へのポインタ。
dwFlags
次のフラグを指定できる。
DPNENUMSERVICEPROVIDERS_ALL
アプリケーションで利用できないプロバイダや、デバイスがインストールされていないプロバイダを含め、システムに対して登録されているすべてのサービス プロバイダを列挙する。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDPARAM

注意

pguidServiceProvider パラメータに NULL を指定して最初にこのメソッドを呼び出し、システムで利用可能なベース サービス プロバイダを決定する。pguidServiceProvider にサービス プロバイダ GUID へのポインタを渡すことで、サービス プロバイダ用の特定のデバイスを取得できる。これは、たとえば、Microsoft® DirectPlay® サービス プロバイダのモデム接続を使用する場合などに便利である。ダイヤルアウトにはさまざまなモデムを選択し、ホストには特定のモデムを選択できる。

pEnumData バッファでは要求されたサービス プロバイダ情報を保持する容量が不足する場合、メソッドは DPNERR_BUFFERTOOSMALL を返す。cbEnumData パラメータには必要なバッファ サイズが含まれる。通常、一番よい方法は長さ 0 のバッファで一度メソッドを呼び出し、必要なサイズを判断することである。次に、バッファを適切なサイズにしてもう一度メソッドを呼び出す。

通常の場合、このメソッドは、アプリケーションが使用できるサービス プロバイダのみを返す。たとえば、IPX ネットワーキング プロトコルがインストールされていない場合、DirectPlay は IPX サービス プロバイダを返さない。DirectPlay が、使用できないプロバイダを含め、すべてのサービス プロバイダを返すようにするには、dwFlags に DPNENUMSERVICEPROVIDERS_ALL フラグを設定する。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Client::GetApplicationDesc

接続されているアプリケーションの完全なアプリケーション記述を取得する。

HRESULT GetApplicationDesc(
DPN_APPLICATION_DESC *const pAppDescBuffer,
DWORD *const pcbDataSize,
const DWORD dwFlags
);

パラメータ

pAppDescBuffer
アプリケーションの記述データが書き込まれる DPN_APPLICATION_DESC 構造体へのポインタ。データのサイズのみを要求するときは、このパラメータに NULL を設定する。pAppDescBuffer が NULL に設定されていない場合、pAppDescBuffer.dwSize メンバに適切な値を設定しなければならない。pcbDataSize パラメータは、データの保持に必要なサイズに設定される。
pcbDataSize
このメソッドを呼び出す前に、バッファのサイズに初期化された DWORD 型の変数へのポインタ。メソッドが戻ると、このパラメータにはセッション データのサイズがバイト単位で設定されている。バッファが小さすぎる場合、このメソッドはエラー値 DPNERR_BUFFERTOOSMALL を返す。このパラメータには、必要なバッファ サイズが設定される。このパラメータが NULL の場合、メソッドは DPNERR_INVALIDPARAM を返す。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM
DPNERR_NOCONNECTION

注意

pvData パラメータに NULL を渡して最初にこのメソッドを呼び出し、必要なバッファ サイズを取得する。2 回目にこのメソッドを呼び出してバッファにデータを格納するときは、構造体の dwSize メンバを適切な値に設定する。

返された DPN_APPLICATION_DESC 構造体には、guidInstance、guidApplication、および pwszSessionName メンバが設定されている。この中には、セッションに接続されているほかのクライアントに関する情報は含まれていない。このような情報は、サーバー アプリケーションのみが取得できる。特に、dwCurrentPlayers メンバは必ず 0 に設定する。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Client::GetCaps

現在のインターフェイスの DPN_CAPS 構造体を取得する。

HRESULT GetCaps(
DPN_CAPS *const pdpCaps,
const DWORD dwFlags
);

パラメータ

pdpnCaps
Caps 情報を受け取る DPN_CAPS 構造体へのポインタ。この構造体の dwSize メンバを、適切な値に設定しなければならない。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER
DPNERR_UNINITIALIZED

注意

Initialize の呼び出しが成功した後に、このメソッドを呼び出す必要がある。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Client::GetConnectionInfo

ローカル クライアントとサーバーとの接続に関する統計情報を取得する。

HRESULT GetConnectionInfo(
DPN_CONNECTION_INFO *const pdnConnectInfo,
const DWORD dwFlags
);

パラメータ

pdnConnectInfo
指定された接続に関する情報を取得する DPN_CONNECTION_INFO 構造体へのポインタ。この構造体の dwSize メンバを、適切な値に設定しなければならない。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER
DPNERR_UNINITIALIZED

注意

Connect の呼び出しが成功した後にのみ、このメソッドを呼び出すことができる。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Client::GetSendQueueInfo

アプリケーションで送信キューのサイズを監視するために使用する。Microsoft® DirectPlay® では、受け取り側のコンピュータの処理速度よりも高速にメッセージを送信することはない。そのため、送信元のコンピュータが、送信先が受け取れる速さよりも高速にメッセージを送信した場合、メッセージは送信側のキューに蓄積される。アプリケーションにより、送信キューのサイズが大きすぎると登録された場合は、メッセージの送信レートを低下させる必要がある。

HRESULT GetSendQueueInfo(
DWORD *const pdwNumMsgs,
DWORD *const pdwNumBytes,
const DWORD dwFlags
);

パラメータ

pdwNumMsgs
現在キューに蓄積されているメッセージの数を保持する DWORD 型の変数へのポインタ。この値はオプションであり、NULL に設定できる。
pdwNumBytes
現在キューに蓄積されているメッセージ データの総バイト数を指定する DWORD 型の変数へのポインタ。この値はオプションであり、NULL に設定できる。
dwFlags
DPNGETSENDQUEUEINFO_PRIORITY_NORMAL、DPNGETSENDQUEUEINFO_PRIORITY_HIGH、または DPNGETSENDQUEUEINFO_PRIORITY_LOW フラグを指定して、その優先順位を持つ特定のメッセージについて問い合わせることができる。

戻り値

成功した場合は S_OK を返す。それ以外の場合は、次のエラー値を返す。

DPNERR_INVALIDPARAM

注意

pdwNumMsgs と pdwNumBytes の両方を NULL に設定することはできない。少なくともいずれか 1 つは有効なポインタに設定する必要がある。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Client::GetServerAddress

セッションのサーバーのアドレスを取得する。

HRESULT GetServerAddress(
IDirectPlay8Address **const ppAddress,
const DWORD dwFlags
);

パラメータ

ppAddress
サーバーのアドレスを指定する IDirectPlay8Address オブジェクトへのポインタへのアドレス。このオブジェクトは、不要になったら解放しなければならない。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER
DPNERR_UNINITIALIZED

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Client::GetServerInfo

IDirectPlay8Server::SetServerInfo メソッドの呼び出しによって設定されたサーバーのデータ セットを取得する。

HRESULT GetServerInfo(
DPN_PLAYER_INFO *const pdpnPlayerInfo,
DWORD *const pdwSize,
const DWORD dwFlags
);

パラメータ

pdpnPlayerInfo
サーバーの情報を格納する DPN_PLAYER_INFO 構造体へのポインタ。pdwSize が NULL に設定されていない場合、pdpnPlayerInfo.dwSize に DPN_PLAYER_INFO 構造体のサイズを指定しなければならない。
pdwSize
pdpnPlayerInfo パラメータに返されるデータのサイズを保持する DWORD 型の変数へのポインタ。この値が小さすぎる場合、このメソッドはDPNERR_BUFFERTOOSMALL を返す。このパラメータには、必要なバッファ サイズが設定される。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDPARAM

注意

このメソッドは、サーバーが情報を更新したことを示す、DPN_MSGID_SERVER_INFO メッセージをクライアントが受け取った後で呼び出す。

Microsoft® DirectPlay® は DPN_PLAYER_INFO 構造体と、連続するバッファにある、この構造体の pwszName メンバと pvData メンバに割り当てられたポインタを返す。この 2 つのポインタが設定される場合、構造体に加えて 2 つのポインタにも十分なメモリを割り当てておく必要がある。このメソッドを使用する最も確実な方法は、最初は pdwSize を NULL に設定してこのメソッドを呼び出すことである。メソッドが戻ると、pcAddress が必要な値をポイントする。メソッドが戻ると、pdwSize が正しい値をポイントしている。その値を使って構造体のメモリを再割り当てし、もう一度メソッドを呼び出して情報を取得する。

メソッドが戻ると、対応するポインタが NULL に設定されている場合でも、DPN_PLAYER_INFO 構造体の dwInfoFlags メンバには常に DPNINFO_DATA フラグと DPNINFO_NAME フラグが設定されている。これらのフラグは IDirectPlay8Server::SetServerInfo を呼び出すときに使用され、DirectPlay に変更された値を通知する。

IDirectPlay8Server::SetServerInfo メソッドを使用すると処理に負担がかかるため、非静的情報は IDirectPlay8Server::SendTo メソッドを使用して転送すること。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Client::GetSPCaps

指定されたサービス プロバイダの DPN_SP_CAPS 構造体を取得する。

HRESULT GetSPCaps(
const GUID *const pguidSP,
DPN_SP_CAPS *const pdpnSPCaps,
const DWORD dwFlags
);

パラメータ

pguidSP
情報を取得したいサービス プロバイダを指定する GUID へのポインタ。
pdpnSPCaps
指定したサービス プロバイダに関する情報を受け取る DPN_SP_CAPS 構造体へのポインタ。pdpnSPCaps.dwSize メンバを DPN_SP_CAPS 構造体のサイズに設定しなければならない。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER
DPNERR_UNINITIALIZED

注意

このメソッドは、指定したサービス プロバイダに関する情報を取得する。Initialize の呼び出しが成功した後に、このメソッドを呼び出す必要がある。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Client::Initialize

IDirectPlay8Client インターフェイスおよびサーバーからメッセージを受信する、クライアントのコード内のエントリ ポイントを登録する。このメソッドを呼び出してから、このインターフェイスのその他のメソッドを呼び出す必要がある。

HRESULT Initialize(
PVOID const pvUserContext,
const PFNDPNMESSAGEHANDLER pfn,
const DWORD dwFlags
);

パラメータ

pvUserContext
メッセージ ハンドラの呼び出しで指定される、ユーザー指定のコンテキスト値。ユーザー コンテキスト値を指定すると、複数のインターフェイスから共通のメッセージ ハンドラに送信されたメッセージを区別できる。
pfn
PFNDPNMESSAGEHANDLER コールバック関数へのポインタ。この関数は、サーバーからのすべてのメッセージを受信し、IDirectPlay8Client インターフェイスからのセッションの変更通知を受信する。
dwFlags
次のフラグを指定できる。
DPNINITIALIZE_DISABLEPARAMVAL
現在のオブジェクトに対するパラメータの有効確認を無効にする。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM

注意

CoCreateInstance を使用して IDirectPlay8Client インターフェイスを取得した後、まずこのメソッドを呼び出す。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Client::RegisterLobby

起動したアプリケーションが、ゲームの状態を自動的にロビーに伝達できるようにする。

HRESULT RegisterLobby(
const DPNHANDLE dpnHandle,
IDirectPlay8LobbiedApplication *const pIDP8LobbiedApplication,
const DWORD dwFlags
);

パラメータ

dpnHandle
IDirectPlay8LobbiedApplication::UpdateStatus を呼び出すときに使用する接続ハンドル。
pIDP8LobbiedApplication
アプリケーションを指定する IDirectPlay8LobbiedApplication オブジェクトへのポインタ。
dwFlags
次のフラグのいずれかを指定する。
DPNLOBBY_REGISTER
ロビーをアプリケーションに登録する。
DPNLOBBY_UNREGISTER
アプリケーションへのロビーの登録を解除する。

戻り値

成功した場合は S_OK を返す。それ以外の場合は、次のエラー値を返す。

DPNERR_INVALIDPARAM

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Client::ReturnBuffer

DPN_MSGID_RECEIVE システム メッセージの pReceiveData メンバによってアプリケーションに提供されたメッセージ バッファを取得する。ユーザーのメッセージ ハンドラが RECEIVE コールバックに DPNSUCCESS_PENDING を返した場合、バッファの所有権はアプリケーションに移行したと見なされ、この呼び出しにより所有権が Microsoft® DirectPlay® に戻るまで所有権の解放や変更は行われない。

HRESULT ReturnBuffer(
const DPNHANDLE hBufferHandle,
const DWORD dwFlags
);

パラメータ

hBufferHandle
メッセージ用のバッファ ハンドルを指定する DPNHANDLE 型の変数。これは、DPNMSG_RECEIVE システム メッセージの hBufferHandle メンバで取得する。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDHANDLE
DPNERR_INVALIDPARAM

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Client::Send

データをサーバーに転送する。メッセージは同期または非同期で送信することができる。

HRESULT Send(
const DPN_BUFFER_DESC *const pBufferDesc,
const DWORD cBufferDesc,
const DWORD dwTimeOut,
void *const pvAsyncContext,
DPNHANDLE *const phAsyncHandle,
const DWORD dwFlags
);

パラメータ

pBufferDesc
送信するデータを記述する DPN_BUFFER_DESC 構造体へのポインタ。
cBufferDesc
pBufferDesc が示す DPN_BUFFER_DESC 構造体の数。このバージョンの Microsoft® DirectPlay® では、バッファは 1 つでなければならない。
dwTimeOut
メッセージの送信を待つ時間 (ミリ秒単位)。メッセージが dwTimeOut 値で送信されていない場合、メッセージは送信されない。メッセージの送信に対してタイム アウトが必要でない場合は、このパラメータを 0 に設定する。
pvAsyncContext
ユーザー指定のコンテキストへのポインタ。これは、DPN_MSGID_SEND_COMPLETE システム メッセージの pvUserContext メンバに返される。
phAsyncHandle
DPNHANDLE。メソッドが戻ると、phAsyncHandle は、IDirectPlay8Client::CancelAsyncOperation に渡して処理を取り消すことができるハンドルをポイントする。dwFlags に DPNSEND_SYNC フラグが設定されている場合、このパラメータは NULL に設定しなければならない。
dwFlags
送信動作を記述するフラグ。次の 1 つ以上のフラグを設定することができる。
DPNSEND_SYNC
Send 要求を同期をとりながら処理する。
DPNSEND_NOCOPY
DPN_BUFFER_DESC 構造体のデータを使用し、内部コピーは行わない。サーバーにデータを送信する方法としては効率的になることがある。しかし、受信側がメッセージを処理する前に、送信側がメッセージを変更できるため、堅牢ではなくなる。このフラグを DPNSEND_NOCOMPLETE と組み合わせることはできない。
DPNSEND_NOCOMPLETE
メッセージ ハンドラに DPN_MSGID_SEND_COMPLETE を送信しない。このフラグを DPNSEND_NOCOPY または DPNSEND_GUARANTEED と共に使用することはできない。また、このフラグを使用する場合、pvAsyncContext は NULL でなければならない。
DPNSEND_COMPLETEONPROCESS
メッセージ がターゲットに配信され、メッセージの受信を示すターゲットのメッセージ ハンドラが返されるとき、DPN_MSGID_SEND_COMPLETE をメッセージ ハンドラに送信する。このフラグが設定された場合は、余分な内部メッセージのオーバーヘッドがあり、メッセージの送信処理が著しく低下する可能性がある。このフラグを設定した場合は、DPNSEND_GUARANTEED も設定する必要がある。
DPNSEND_GUARANTEED
保証付き配信方式を使用してメッセージを送信する。
DPNSEND_PRIORITY_HIGH
メッセージの優先順位を高く設定する。このフラグは、DPNSEND_PRIORITY_LOW と共に使用することはできない。
DPNSEND_PRIORITY_LOW
メッセージの優先順位を低く設定する。このフラグは、DPNSEND_PRIORITY_HIGH と共に使用することはできない。
DPNSEND_NOLOOPBACK
自分に送信する場合、メッセージ ハンドラにDPN_MSGID_RECEIVE システム メッセージを送信しない。
DPNSEND_NONSEQUENTIAL
このフラグを設定しない場合、メッセージは送信順にターゲット アプリケーションに配信される。したがって、順序どおりでないメッセージは、欠落しているメッセージが到着するまでバッファに格納する必要がある。このフラグを設定すると、メッセージは受信順にターゲット アプリケーションに配信される。

戻り値

メソッドが同期をとりながら処理され、処理が成功した場合は S_OK を返す。デフォルトでは、このメソッドは非同期に実行され、通常は DPNSUCCESS_PENDING か、または次のいずれかのエラー値を返す。

DPNERR_INVALIDFLAGS
DPNERR_TIMEDOUT

注意

このメソッドは、サーバーのメッセージ ハンドラに DPN_MSGID_RECEIVE システム メッセージを生成する。データ バッファは、関連付けられている構造体の pReceiveData メンバに保持されている。

メッセージには、低、通常、高の 3 つの優先順位のいずれかを設定できる。dwFlags メッセージに低い優先順位または高い優先順位を指定するには dwFlags に適切なフラグを設定する。どちらの優先順位フラグも設定しなかった場合、メッセージは通常の優先順位になる。送信優先順位の詳細については、「ネットワーキングの基本」を参照すること。

Send 要求が完了すると、送信側のメッセージ ハンドラに DPN_MSGID_SEND_COMPLETE システム メッセージが送信される。要求の成功または失敗は、関連付けられた構造体の hResultCode メンバに保持される。dwflags に DPN_NOCOMPLETE フラグを設定すると、送信完了のシステム メッセージは送信されない。

通常、メッセージが送信されると直ちに、送信完了が送信元のコンピュータに送信される。言い換えると、送信完了は、メッセージがターゲット上で処理されたことを必ずしも意味しない。メッセージはまだキュー内にある可能性もある。メッセージがターゲットで処理されたことを確認するには、dwFlags にDPN_COMPLETEONPROCESS フラグを設定する。このフラグを設定すると、ターゲットのメッセージ ハンドラがメッセージを処理して戻るまで、送信完了は送信されない。

アプリケーションは IDirectPlay8Client、IDirectPlay8Server、または IDirectPlay8Peer で Close を呼び出す前や最終リリースをする前に、CancelAsyncOperation を呼び出して残っている Send をキャンセルすべきである。それに失敗すると予期せぬ結果が起きる。

注 メソッドが戻るまでは、データ バッファなどのリソースが有効な状態のままであると見なしてはならない。このメソッドを非同期に呼び出す場合、呼び出しが戻る前に DPN_MSGID_SEND_COMPLETE メッセージを受け取り、メッセージ ハンドラが処理してしまうことがある。メッセージ ハンドラがデータ バッファなどのリソースを割り当て解除、または無効にした場合、メソッドが呼び出された後でリソースが無効になることがある。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Client::SetCaps

現在のインターフェイスの DPN_CAPS 構造体を設定する。

HRESULT SetCaps(
const DPN_CAPS *const pdpCaps,
const DWORD dwFlags
);

パラメータ

pdpCaps
現在のインターフェイスに関する情報の設定に使用される DPN_CAPS 構造体へのポインタ。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPOINTER
DPNERR_INVALIDPARAM
DPNERR_UNINITIALIZED

注意

このメソッドは、指定されたサービス プロバイダに対するパラメータを設定する。Initialize の呼び出しが成功した後に、このメソッドを呼び出す必要がある。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Client::SetClientInfo

クライアントとアプリケーションとの静的設定を設定する。アプリケーションに基本的なプレーヤー情報を転送するには、接続前にこのメソッドを呼び出す。クライアントが正しくアプリケーションに接続すると、サーバーはこのメソッドで取得された情報を IDirectPlay8Server::GetClientInfo メソッドを呼び出して取得できる。

HRESULT SetClientInfo(
const DPN_PLAYER_INFO *const pdpnPlayerInfo,
PVOID const pvAsyncContext,
DPNHANDLE *const phAsyncHandle,
const DWORD dwFlags
);

パラメータ

pdpnPlayerInfo
設定するクライアント情報を保持する DPN_PLAYER_INFO 構造体へのポインタ。
pvAsyncContext
ユーザー指定のコンテキストへのポインタ。これは、DPN_MSGID_ASYNC_OP_COMPLETE システム メッセージの pvUserContext メンバに返される。
phAsyncHandle
DPNHANDLE。値が返される。ただし、Microsoft® DirectPlay® 8.0 ではこの操作の取り消しは許可されていないため、値を使用することはできない。
dwFlags
このメソッドが処理される方法を制御するフラグ。このメソッドには、次のフラグを設定できる。
DPNSETCLIENTINFO_SYNC
メソッドを同期をとりながら処理する。

戻り値

メソッドが同期をとりながら処理され、処理が成功した場合は S_OK を返す。要求が非同期で処理される場合、メソッドが直ちに処理されると、S_OK を返す場合がある。デフォルトでは、このメソッドは非同期に実行され、通常は DPNSUCCESS_PENDING か、または次のいずれかのエラー値を返す。

DPNERR_NOCONNECTION
DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM

注意

このメソッドは、セッション中いつでも呼び出すことができる。

IDirectPlay8Client::SetClientInfo メソッドを使用すると処理に負担がかかるため、非静的情報は IDirectPlay8Client::Send メソッドを使用して転送すること。

アプリケーションへの接続後、このメソッドを使用してクライアント情報を変更できる。接続後にこのメソッドを呼び出すと、データの更新を知らせる DPN_MSGID_CLIENT_INFO システム メッセージがすべてのプレーヤーに対して生成される。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Client::SetSPCaps

指定されたサービス プロバイダの DPN_SP_CAPS 構造体を設定する。

HRESULT SetSPCaps(
const GUID *const pguidSP,
constDPN_SP_CAPS *const pdpnSPCaps
);

パラメータ

pguidSP
情報を設定するサービス プロバイダを指定する GUID へのポインタ。
pdpnSPCaps
指定したサービス プロバイダに関する情報を設定する DPN_SP_CAPS 構造体へのポインタ。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER
DPNERR_UNINITIALIZED

注意

このメソッドは、指定されたサービス プロバイダに対するパラメータを設定する。Initialize の呼び出しが成功した後に、このメソッドを呼び出す必要がある。現在、この呼び出しでは dwNumThreads メンバのみ設定することができる。dwFlags は 0 でなければならない。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Server

アプリケーションは、IDirectPlay8Server インターフェイスのメソッドを使用して、Microsoft® DirectPlay® のクライアント/サーバー トランスポート セッションの作成と管理を行う。

IDirectPlay8Server インターフェイスのメソッドは、次のように分類できる。

セッション管理 | Close
 | EnumServiceProviders
 | GetApplicationDesc
 | GetCaps
 | GetSPCaps
 | GetSendQueueInfo
 | Host
 | Initialize
 | ReturnBuffer
 | SendTo
 | SetApplicationDesc
 | SetCaps
 | SetServerInfo
 | SetSPCaps
クライアント管理 | DestroyClient
 | GetClientInfo
 | GetPlayerContext
グループ管理 | AddPlayerToGroup
 | CreateGroup
 | DestroyGroup
 | EnumPlayersAndGroups
 | EnumGroupMembers
 | GetGroupContext
 | GetGroupInfo
 | RemovePlayerFromGroup
 | SetGroupInfo
その他 | CancelAsyncOperation
 | GetClientAddress
 | GetConnectionInfo
 | GetLocalHostAddresses
 | RegisterLobby

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Server::AddPlayerToGroup

グループにクライアントを追加する。クライアントがグループに正しく追加された後、グループに送信されるすべてのメッセージがクライアントに送信される。

HRESULT AddPlayerToGroup(
const DPNID idGroup,
const DPNID idClient,
PVOID const pvAsyncContext,
DPNHANDLE *const phAsyncHandle,
const DWORD dwFlags
);

パラメータ

idGroup
グループに追加するクライアントの識別子を指定する DPNID 型の変数。
idClient
グループに追加するクライアントの識別子を指定する DPNID 型の変数。
pvAsyncContext
ユーザー指定のコンテキストへのポインタ。これは、DPN_MSGID_ASYNC_OP_COMPLETE システム メッセージの pvUserContext メンバに返される。このパラメータはオプションであり、NULL に設定できる。
phAsyncHandle
DPNHANDLE。値が返される。ただし、Microsoft® DirectPlay® 8.0 ではこの操作の取り消しは許可されていないため、値を使用することはできない。
dwFlags
このメソッドが処理される方法を制御するフラグ。このメソッドには、次のフラグを設定できる。
DPNADDPLAYERTOGROUP_SYNC
メソッドを同期をとりながら処理する。

戻り値

メソッドが同期をとりながら処理され、処理が成功した場合は S_OK を返す。デフォルトでは、このメソッドは非同期に実行され、通常は DPNSUCCESS_PENDING か、または次のいずれかのエラー値を返す。

DPNERR_INVALIDFLAGS
DPNERR_INVALIDGROUP
DPNERR_INVALIDPLAYER

注意

サーバーは、サーバー自体またはクライアントを既存のグループに追加できる。プレーヤーがグループに正しく追加されると、グループに送られたすべてのメッセージをプレーヤーも受け取る。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Server::CancelAsyncOperation

非同期の要求を取り消す。デフォルトでは、IDirectPlay8Server インターフェイスの多くのメソッドが非同期に実行される。状況に応じて、要求が処理される前にその要求を取り消したい場合もある。このインターフェイスで非同期に実行できるすべてのメソッドは、hAsyncHandle パラメータを返す。

要求の hAsyncHandle をこのメソッドの hAsyncHandle パラメータに渡すことによって、特定の要求が取り消される。このメソッドを呼び出し、hAsyncHandle パラメータに NULL を、dwFlags パラメータに DPNCANCEL_ALL_OPERATIONS を指定することによって、待機中のすべての非同期処理を取り消すことができる。特定のハンドルがこのメソッドに指定された場合は、いずれのフラグも設定してはならない。

HRESULT CancelAsyncOperation(
const DPNHANDLE hAsyncHandle,
const DWORD dwFlags
);

パラメータ

hAsyncHandle
非同期処理を停止するハンドル。すべての要求または特定の種類の非同期要求を停止するには、この値を NULL にする。取り消す要求に特定のハンドルが指定されている場合、dwFlags パラメータは 0 に設定する。このハンドルは、非同期処理をサポートするメソッドを呼び出したときに受け取る。
dwFlags
取り消す非同期要求を指定するフラグ。次のいずれかのフラグを設定できる。
DPNCANCEL_SEND
非同期 IDirectPlay8Server::SendTo 要求を取り消す。
DPNCANCEL_ALL_OPERATIONS
すべての非同期要求を取り消す。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_CANNOTCANCEL
DPNERR_INVALIDFLAGS
DPNERR_INVALIDHANDLE
DPNSUCCESS_PENDING

注意

このメソッドを使用して、IDirectPlay8Server::SendTo メソッドの非同期処理を取り消すことができる。Microsoft® DirectPlay® 8.0 は、ほかの非同期処理の取り消しをサポートしていない。

IDirectPlay8Server::SendTo メソッドから返されたハンドルを指定すると、Send 要求を取り消すことができる。その場合も、DPN_MSGID_SEND_COMPLETE システム メッセージは、DPNSEND_NOCOMPLETE フラグを設定せずに送信された非同期 Send 要求ごとに、アプリケーション メッセージ ハンドラに送信される。このメソッドで取り消されたセンド要求は、DPN_MSGID_SEND_COMPLETE メッセージの hResultCode メンバに DPNERR_USERCANCEL を返す。

dwFlags に DPNCANCEL_ALL_OPERATIONS または DPNCANCEL_SEND フラグを設定した場合、DirectPlay はすべての一致する処理を取り消そうとする。このメソッドは、取り消しに失敗した処理がある場合、一部の取り消しが成功していてもエラーを返す。

注 このメソッドが値を返すまで、完了メッセージは到着しない場合がある。DPN_MSGID_SEND_COMPLETE、DPN_MSGID_CONNECT_COMPLETE、または DPN_MSGID_ASYNC_OP_COMPLETE メッセージを受け取るまで、処理が終了したと見なしてはならない。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Server::Close

セッションにより開かれた接続を閉じる。

HRESULT Close(
const DWORD dwFlags
);

パラメータ

dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は S_OK を返す。それ以外の場合は、次のエラー値を返す。

DPNERR_UNINITIALIZED

注意

このメソッドは、IDirectPlay8Server::Initialize で正常に初期化されたオブジェクトのすべてで呼び出されなくてはならない。

これは、IDirectPlay8Server::Host に対応するメソッドである。サーバーにホストされているすべてのアクティブなネットワーク接続を閉じる。このメソッドは同期メソッドであり、サーバーがすべての DPN_MSGID_DESTROY_PLAYER メッセージを処理するまで戻らない。この機能により、Close が戻ればサーバー アプリケーションを安全にシャットダウンできる。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Server::CreateGroup

現在のセッションにグループを作成する。このメソッドが呼び出されると、サーバーのメッセージ ハンドラが DPN_MSGID_CREATE_GROUP メッセージを受け取る。

注 マルチキャスティングはこのリリースではサポートされていない。

HRESULT CreateGroup(
const DPN_GROUP_INFO *const pdpnGroupInfo,
VOID *const pvGroupContext,
VOID *const pvAsyncContext,
DPNHANDLE *const phAsyncHandle,
const DWORD dwFlags
);

パラメータ

pdpnGroupInfo
グループの記述を保持する DPN_GROUP_INFO 構造体へのポインタ。
pvGroupContext
グループのコンテキスト値へのポインタ。この値は、ローカル アプリケーションのメッセージ ハンドラが DPN_MSGID_CREATE_GROUP メッセージを処理するときに事前に設定される。このパラメータはオプションであり、NULL に設定できる。
pvAsyncContext
ユーザー指定のコンテキストへのポインタ。これは、DPN_MSGID_ASYNC_OP_COMPLETE システム メッセージの pvUserContext メンバに返される。
phAsyncHandle
DPNHANDLE。値が返される。ただし、Microsoft® DirectPlay® 8.0 ではこの操作の取り消しは許可されていないため、値を使用することはできない。
dwFlags
このメソッドが処理される方法を制御するフラグ。このメソッドには、次のフラグを設定できる。
DPNCREATEGROUP_SYNC
メソッドを同期をとりながら処理する。

戻り値

メソッドが同期をとりながら処理され、処理が成功した場合は S_OK を返す。デフォルトでは、このメソッドは非同期に実行され、通常は DPNSUCCESS_PENDING か、または次のエラー値を返す。

DPNERR_INVALIDFLAGS

注意

Microsoft® DirectPlay® は、階層グループを保持しない。これは、これらのグループがフラット グループとグループ データの活用により簡単に実装できるためである。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Server::DestroyClient

セッションからクライアントを削除する。

HRESULT DestroyClient(
const DPNID dpnidClient,
const VOID *const pDestroyInfo,
const DWORD dwDestroyInfoSize,
const DWORD dwFlags
);

パラメータ

dpnidClient
削除するクライアントの識別子を指定する DPNID 型の変数。
pDestroyInfo
追加の削除データ情報を記述するポインタ。
dwDestroyInfoSize
pDestroyInfo パラメータに保持されるデータのサイズを指定する DWORD 型の変数。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDPARAM
DPNERR_INVALIDPLAYER
DPNERR_NOTHOST

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Server::DestroyGroup

IDirectPlay8Server::CreateGroup メソッドによって作成されたグループを削除する。

HRESULT DestroyGroup(
const DPNID idGroup,
PVOID const pvAsyncContext,
DPNHANDLE *const phAsyncHandle,
const DWORD dwFlags
);

パラメータ

idGroup
削除するグループの DPNID。
pvAsyncContext
ユーザー指定のコンテキストへのポインタ。これは、DPN_MSGID_ASYNC_OP_COMPLETE システム メッセージの pvUserContext メンバに返される。このパラメータはオプションであり、NULL に設定できる。
phAsyncHandle
DPNHANDLE。値が返される。ただし、Microsoft® DirectPlay® 8.0 ではこの操作の取り消しは許可されていないため、値を使用することはできない。
dwFlags
このメソッドが処理される方法を制御するフラグ。このメソッドには、次のフラグを設定できる。
DPNDESTROYGROUP_SYNC
メソッドを同期をとりながら処理する。

戻り値

メソッドが同期をとりながら処理され、処理が成功した場合は S_OK を返す。デフォルトでは、このメソッドは非同期に実行され、通常は DPNSUCCESS_PENDING か、または次のいずれかのエラー値を返す。

DPNERR_INVALIDFLAGS
DPNERR_INVALIDGROUP

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Server::EnumPlayersAndGroups

アプリケーションのすべてのプレーヤーまたはグループの識別子、あるいはその両方の識別子の一覧を取得する。

HRESULT EnumPlayersAndGroups(
DPNID *const prgdpnid,
DWORD *const pcdpnid,
const DWORD dwFlags
);

パラメータ

prgdpnid
セッションのグループまたはプレーヤーの識別子、あるいはその両方がデータとして格納される配列へのポインタ。
pcdpnid
prgdpnid パラメータに保持される識別子の数を指定する DWORD 型の変数へのポインタ。バッファが小さすぎる場合、このメソッドは DPNERR_BUFFERTOOSMALL を返す。このパラメータには、必要なエントリの数が設定される。
dwFlags
列挙の動作を記述するフラグ。次の 1 つまたは両方のフラグを設定することができる。
DPNENUM_PLAYERS
プレーヤーの識別子のリストを返す。
DPNENUM_GROUPS
グループの識別子のリストを返す。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDFLAGS

注意

グループおよびプレーヤーの情報は頻繁に変化するため、返される必要なバッファ サイズは以降の呼び出しで変わる場合がある。メソッドが成功するまで、バッファを確認し、再割り当てする。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Server::EnumGroupMembers

グループ内のすべてのプレーヤーの一覧を取得する。

HRESULT EnumGroupMembers(
const DPNID dpnid,
DPNID *const prgdpnid,
DWORD *const pcdpnid,
const DWORD dwFlags
);

パラメータ

dpnid
列挙するプレーヤーを保持するグループを指定する DPNID 型の変数。
prgdpnid
グループのプレーヤーの識別子を格納する配列へのポインタ。
pcdpnid
prgdpnid パラメータにプレーヤーの識別子の数を保持する DWORD 型の変数へのポインタ。バッファが小さすぎる場合、このメソッドは DPNERR_BUFFERTOOSMALL を返す。このパラメータには、必要なエントリの数が設定される。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDFLAGS
DPNERR_INVALIDGROUP

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Server::EnumServiceProviders

アプリケーションで利用可能な登録済みサービス プロバイダを列挙する。

HRESULT EnumServiceProviders(
const GUID *const pguidServiceProvider,
const GUID *const pguidApplication,
DPN_SERVICE_PROVIDER_INFO *const pSPInfoBuffer,
PDWORD const pcbEnumData,
PDWORD const pcReturned
const DWORD dwFlags
);

パラメータ

pguidServiceProvider
サービス プロバイダを指定する GUID 型の変数へのポインタ。このオプション パラメータは、指定したサービス プロバイダのサブデバイスを列挙させる。通常はこの値に NULL を設定し、すべての利用可能なサービス プロバイダを列挙する。
pguidApplication
アプリケーションを指定する GUID 型の変数へのポインタ。このパラメータにポインタが渡された場合は、アプリケーションに接続できるサービス プロバイダだけが列挙される。NULL を渡して、システムに登録済みのサービス プロバイダを列挙することもできる。
pSPInfoBuffer
サービス プロバイダ情報を保持する、DPN_SERVICE_PROVIDER_INFO 構造体の配列へのポインタ。
pcbEnumData
バッファが小さすぎる場合、pEnumData バッファのサイズが格納される DWORD へのポインタ。
pcReturned
pEnumData 配列に返される DPN_SERVICE_PROVIDER_INFO 構造体の数を指定する DWORD 型の変数へのポインタ。
dwFlags
次のフラグを指定できる。
DPNENUMSERVICEPROVIDERS_ALL
アプリケーションで利用できないプロバイダや、デバイスがインストールされていないプロバイダを含め、システムに対して登録されているすべてのサービス プロバイダを列挙する。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDPARAM

注意

pguidServiceProvider パラメータに NULL を指定して最初にこのメソッドを呼び出し、システムで利用可能なベース サービス プロバイダを決定する。pguidServiceProvider に特定のサービス プロバイダ GUID へのポインタを渡すことで、サービス プロバイダ用のデバイスを取得できる。これは、たとえば、Microsoft® DirectPlay® サービス プロバイダのモデム接続を使用する場合などに便利である。ダイヤルアウトにはさまざまなモデムを選択し、ホストには特定のモデムを選択できる。

pEnumData バッファでは要求されたサービス プロバイダ情報を保持する容量が不足する場合、メソッドは DPNERR_BUFFERTOOSMALL を返す。cbEnumData パラメータには必要なバッファ サイズが含まれる。通常、一番よい方法は長さ 0 のバッファで一度メソッドを呼び出し、必要なサイズを判断することである。次に、バッファを適切なサイズにしてもう一度メソッドを呼び出す。

通常の場合、このメソッドは、アプリケーションが使用できるサービス プロバイダのみを返す。たとえば、IPX ネットワーキング プロトコルがインストールされていない場合、DirectPlay は IPX サービス プロバイダを返さない。DirectPlay が、使用できないプロバイダを含め、すべてのサービス プロバイダを返すようにするには、dwFlags に DPNENUMSERVICEPROVIDERS_ALL フラグを設定する。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Server::GetApplicationDesc

接続されているアプリケーションのアプリケーション記述全体を取得する。

HRESULT GetApplicationDesc(
DPN_APPLICATION_DESC *const pAppDescBuffer,
DWORD *const pcbDataSize,
const DWORD dwFlags
);

パラメータ

pAppDescBuffer
アプリケーションの記述データが書き込まれる DPN_APPLICATION_DESC 構造体へのポインタ。データのサイズのみを要求するときは、このパラメータに NULL を設定する。pAppDescBuffer が NULL に設定されていない場合、pAppDescBuffer.dwSize メンバに適切な値を設定しなければならない。pcbDataSize パラメータは、データの保持に必要なサイズに設定される。
pcbDataSize
このメソッドを呼び出す前に、バッファのサイズに初期化された DWORD 型の変数へのポインタ。メソッドが戻ると、このパラメータにはセッション データのサイズがバイト単位で設定されている。バッファが小さすぎる場合、このメソッドはエラー値 DPNERR_BUFFERTOOSMALL を返す。このパラメータには、必要なバッファ サイズが設定される。このパラメータが NULL の場合、メソッドは DPNERR_INVALIDPARAM を返す。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM
DPNERR_NOCONNECTION

注意

pvData パラメータに NULL を渡して最初にこのメソッドを呼び出し、必要なバッファ サイズを取得する。2 回目にこのメソッドを呼び出してバッファにデータを格納するときは、構造体の dwSize メンバを適切な値に設定する。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Server::GetCaps

現在のインターフェイスの DPN_CAPS 構造体を取得する。

HRESULT GetCaps(
DPNCAPS *const pdpnCaps,
const DWORD dwFlags
);

パラメータ

pdpnCaps
Caps 情報を受け取る DPN_CAPS 構造体へのポインタ。この構造体の dwSize メンバを適切な値に設定しなければならない。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER
DPNERR_UNINITIALIZED

注意

Initialize の呼び出しが成功した後に、このメソッドを呼び出す必要がある。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Server::GetClientAddress

セッション内の指定されたプレーヤーのアドレスを取得する。

HRESULT GetClientAddress(
const DPNID dpnid,
IDirectPlay8Address **const pAddress,
const DWORD dwFlags
);

パラメータ

dpnid
プレーヤーの識別情報を指定する DPNID 型の変数。
pAddress
クライアントのアドレスを指定する IDirectPlay8Address オブジェクトへのポインタへのアドレス。このオブジェクトは、不要になったら解放しなければならない。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPARAM
DPNERR_INVALIDPLAYER
DPNERR_INVALIDPOINTER
DPNERR_UNINITIALIZED

注意

セッションへの接続に使用できるアドレスを取得するには、IDirectPlay8Server::GetLocalHostAddresses メソッドを使用する。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Server::GetClientInfo

指定されたクライアントに対して設定されているクライアント情報を取得する。

HRESULT GetClientInfo(
const DPNID dpnid,
DPN_PLAYER_INFO *const pdpnPlayerInfo,
DWORD *const pdwSize,
const DWORD dwFlags
);

パラメータ

dpnid
情報を取得するクライアントの識別子を指定する DPNID 型の変数。
pdpnPlayerInfo
クライアント情報を格納する DPN_PLAYER_INFO 構造体へのポインタ。pdwSize が NULL に設定されていない場合、pdpnPlayerInfo.dwSize に適切な値を設定しなければならない。
pdwSize
pdpnPlayerInfo パラメータに返されるクライアント データのサイズを保持する DWORD 型の変数へのポインタ。バッファが小さすぎる場合、このメソッドは DPNERR_BUFFERTOOSMALL を返し、このパラメータには要求されたバッファのサイズが入る。
dwFlags
クライアントに関して返される情報を記述するフラグ。現在、次のフラグの両方が返される。
DPNINFO_NAME
DPN_PLAYER_INFO 構造体はクライアントの名前セットを保持する。
DPNINFO_DATA
DPN_PLAYER_INFO 構造体はクライアントのデータ セットを保持する。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDPARAM
DPNERR_INVALIDPLAYER

注意

サーバーがアプリケーションから DPN_MSGID_CLIENT_INFO メッセージを受信した後、このメソッドを呼び出す。このメッセージは、クライアントが情報を更新したことを示す。

Microsoft® DirectPlay® は DPN_PLAYER_INFO 構造体と、連続するバッファにある、この構造体の pwszName メンバと pvData メンバに割り当てられたポインタを返す。この 2 つのポインタが設定される場合、構造体に加えて 2 つのポインタにも十分なメモリを割り当てておく必要がある。このメソッドを使用する最も確実な方法は、最初は pdwSize を 0 に設定してこのメソッドを呼び出すことである。メソッドが戻ると、pdwSize が正しい値をポイントしている。その値を使って構造体にメモリを割り当て、もう一度メソッドを呼び出して情報を取得する。

メソッドが戻ると、対応するポインタが NULL に設定されている場合でも、DPN_PLAYER_INFO 構造体の dwInfoFlags メンバには常に DPNINFO_DATA フラグと DPNINFO_NAME フラグが設定されている。これらのフラグは IDirectPlay8Client::SetClientInfo を呼び出すときに使用され、DirectPlay に変更された値を通知する。

IDirectPlay8Client::SetPeerInfo メソッドを使用すると処理に負担がかかるため、非静的情報は IDirectPlay8Client::Send メソッドを使用して転送すること。

プレーヤーは、IDirectPlay8Client::SetClientInfo を呼び出してその情報を設定する。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Server::GetConnectionInfo

ローカル サーバーと指定されたリモート クライアントとの接続に関する統計情報を取得する。

HRESULT GetConnectionInfo(
const DPNID dpnidEndPoint,
DPN_CONNECTION_INFO *const pdnConnectInfo,
const DWORD dwFlags
);

パラメータ

dpnidEndPoint
接続情報を取得するプレーヤーの DPNID。
pdnConnectInfo
指定された接続に関する情報を取得する DPN_CONNECTION_INFO 構造体へのポインタ。この構造体の dwSize メンバに DPN_CONNECTION_INFO 構造体のサイズを設定する必要がある。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER
DPNERR_UNINITIALIZED

注意

Host の呼び出しが成功した後にのみ、このメソッドを呼び出すことができる。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Server::GetGroupContext

グループに対するグループ コンテキスト値を取得する。

HRESULT GetGroupContext(
const DPNID dpnid,
PVOID *const ppvGroupContext,
const DWORD dwFlags
);

パラメータ

dpnid
グループの識別子を指定する DPNID 型の変数。このグループのコンテキスト データを取得する。
ppvGroupContext
グループのコンテキスト値へのポインタ。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDGROUP
DPNERR_INVALIDPARAM

注意

グループのコンテキスト値は、DPN_MSGID_CREATE_GROUP システム メッセージの pvGroupContext メンバをコンテキスト値のデータに示すことによって設定される。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Server::GetGroupInfo

グループ名など、グループに関連付けられているデータ ブロックを取得する。

通常、グループ データが変更されたことを示す DPN_MSGID_GROUP_INFO システム メッセージが受信された後、このメソッドが呼び出される。

HRESULT GetGroupInfo(
const DPNID dpnid,
DPN_GROUP_INFO *const pdpnGroupInfo,
DWORD *const pdwSize,
const DWORD dwFlags
);

パラメータ

dpnid
データ ブロックを取得するグループの識別子を指定する DPNID 型の変数。
pdpnGroupInfo
グループ データを記述する DPN_GROUP_INFO 構造体へのポインタ。pdwSize が NULL に設定されていない場合、pdpnGroupInfo.dwSize に DPN_GROUP_INFO 構造体のサイズを設定する必要がある。
pdwSize
データのサイズを pdpnGroupInfo パラメータに返す DWORD 型の変数へのポインタ。バッファが小さすぎる場合、このメソッドは DPNERR_BUFFERTOOSMALL を返す。このパラメータには、必要なサイズが設定される。
dwFlags
グループに関して返される情報を記述するフラグ。現在、次のフラグの両方が返される。
DPNINFO_NAME
DPN_PLAYER_INFO 構造体はクライアントの名前セットを保持する。
DPNINFO_DATA
DPN_PLAYER_INFO 構造体はクライアントのデータ セットを保持する。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDFLAGS
DPNERR_INVALIDGROUP

注意

Microsoft® DirectPlay® は DPN_GROUP_INFO 構造体と、連続するバッファにある、この構造体の pwszName メンバと pvData メンバに割り当てられたポインタを返す。この 2 つのポインタが設定される場合、構造体に加えて 2 つのポインタにも十分なメモリを割り当てておく必要がある。このメソッドを使用する最も確実な方法は、最初は pdwSize を NULL に設定してこのメソッドを呼び出すことである。メソッドが戻ると、pdwSize が正しい値をポイントしている。その値を使って構造体にメモリを割り当て、もう一度メソッドを呼び出して情報を取得する。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Server::GetLocalHostAddresses

セッションをホストするために使用されるローカル アドレスを取得する。

HRESULT GetLocalHostAddresses(
IDirectPlay8Address **const prgpAddress,
DWORD *const pcAddress,
constDWORD dwFlags
);

パラメータ

prgpAddress
ローカル ホスト アドレスを指定する、IDirectPlay8Address オブジェクトの配列へのポインタのアドレス。これらのオブジェクトは不要になったら解放しなければならない。解放しなかった場合、メモリ リークが発生する。
pcAddress
prgpAddress がポイントする配列に保持できるアドレス オブジェクトの最大数。バッファが小さすぎる場合、メソッドは DPNERR_BUFFERTOOSMALL を返し、pcAddress が必要な値に設定される。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDOBJECT
DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER
DPNERR_UNINITIALIZED

注意

このメソッドを使用する最も確実な方法は、最初は pcAddress を 0 に設定してこのメソッドを呼び出すことである。メソッドが戻ると、pcAddress が必要な値をポイントする。2 回目にこのメソッドを呼び出すときは、その値を使って情報を取得する。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Server::GetPlayerContext

クライアントに対するプレーヤー コンテキスト値を取得する。

HRESULT GetPlayerContext(
const DPNID dpnid,
PVOID *const ppvPlayerContext,
const DWORD dwFlags
);

パラメータ

dpnid
コンテキスト データを取得するプレーヤーの識別子を指定する DPNID 型の変数。
ppvPlayerContext
クライアントのコンテキスト データへのポインタ。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDPARAM
DPNERR_INVALIDPLAYER

注意

プレーヤーのコンテキスト値は、DPN_MSGID_CREATE_PLAYER システム メッセージの pvPlayerContext メンバをコンテキスト値のデータに示すことによって設定される。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Server::GetSendQueueInfo

アプリケーションで送信キューのサイズを監視するために使用する。Microsoft® DirectPlay® では、受け取り側のコンピュータの処理速度よりも高速にメッセージを送信することはない。そのため、送信元のコンピュータが、送信先が受け取れる速さよりも高速にメッセージを送信した場合、メッセージは送信側のキューに蓄積される。アプリケーションにより、送信キューのサイズが大きすぎると登録された場合は、メッセージの送信レートを低下させる必要がある。

HRESULT GetSendQueueInfo(
const DPNID dpnid,
DWORD *const pdwNumMsgs,
DWORD *const pdwNumBytes,
const DWORD dwFlags
);

パラメータ

dpnid
送信キュー情報を取得するプレーヤーの識別子を指定する DPNID 型の変数。
pdwNumMsgs
現在キューに蓄積されているメッセージの数を保持する DWORD 型の変数へのポインタ。この値はオプションであり、NULL に設定できる。
pdwNumBytes
現在キューに蓄積されているメッセージ データの総バイト数を指定する DWORD 型の変数へのポインタ。この値はオプションであり、NULL に設定できる。
dwFlags
DPNGETSENDQUEUEINFO_PRIORITY_NORMAL、DPNGETSENDQUEUEINFO_PRIORITY_HIGH、または DPNGETSENDQUEUEINFO_PRIORITY_LOW フラグを指定して、その優先順位を持つ特定のメッセージについて問い合わせることができる。

戻り値

成功した場合は S_OK を返す。それ以外の場合は、次のエラー値を返す。

DPNERR_INVALIDPARAM

注意

pdwNumMsgs と pdwNumBytes の両方を NULL に設定することはできない。少なくともいずれか 1 つは有効なポインタに設定する必要がある。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Server::GetSPCaps

指定されたサービス プロバイダの DPN_SP_CAPS 構造体を取得する。

HRESULT GetSPCaps(
const GUID *const pguidSP,
DPN_SP_CAPS *const pdpnSPCaps,
const DWORD dwFlags
);

パラメータ

pguidSP
情報を取得したいサービス プロバイダを指定する GUID へのポインタ。
pdpnSPCaps
指定したサービス プロバイダに関する情報を受け取る DPN_SP_CAPS 構造体へのポインタ。この構造体の pdpnSPCaps.dwSize メンバを適切な値に設定する必要がある。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER
DPNERR_UNINITIALIZED

注意

このメソッドは、指定したサービス プロバイダに関する情報を取得する。Initialize の呼び出しが成功した後に、このメソッドを呼び出す必要がある。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Server::Host

ローカル コンピュータによってホストされる、新しいクライアント/サーバー セッションを作成する。

HRESULT Host(
const DPN_APPLICATION_DESC *const pdnAppDesc,
IDirectPlay8Address **const prgpDeviceInfo,
const DWORD cDeviceInfo,
const DPN_SECURITY_DESC *const pdpSecurity,
const DPN_SECURITY_CREDENTIALS *const pdpCredentials,
VOID *const pvPlayerContext,
const DWORD dwFlags
);

パラメータ

pdnAppDesc
アプリケーションを記述する DPN_APPLICATION_DESC 構造体へのポインタ。
prgpDeviceInfo
アプリケーションをホストするために使用するデバイス アドレスを保持する、IDirectPlay8Address オブジェクトの配列へのポインタ。
cDeviceInfo
prgpDeviceInfo が示す配列のデバイス アドレス オブジェクトの数を指定する DWORD 型の変数。
pdpSecurity
予約済み。NULL に設定すること。
pdpCredentials
予約済み。NULL に設定すること。
pvPlayerContext
プレーヤーのコンテキスト値へのポインタ。この値は、ローカル コンピュータが DPN_MSGID_CREATE_PLAYER メッセージを処理するときに、事前に設定される。このパラメータはオプションであり、NULL に設定できる。
dwFlags
次のフラグを指定できる。
DPNHOST_OKTOQUERYFORADDRESSING
このフラグを設定すると、Microsoft® DirectPlay® の標準のダイアログ ボックスが表示される。十分な情報がこのメソッドに渡されていない場合は、詳細について問い合わされる。

戻り値

成功した場合は S_OK を返す。それ以外の場合は、次のいずれかのエラー値を返す。

DPNERR_DATATOOLARGE
DPNERR_INVALIDPARAM

注意

dwFlags に DPNHOST_OKTOQUERYFORADDRESSING フラグを設定した場合、サービス プロバイダは、ダイアログ ボックスを表示して、ユーザーにアドレス情報の入力を求めようとする。サービス プロバイダがダイアログ ボックスの表示を試みるときには、表示可能なウィンドウが存在している必要がある。ウィンドウがない場合、アプリケーションはロックする。

DPN_APPLICATION_DESC 構造体の pvApplicationReservedData メンバに割り当てるアプリケーション データの最大サイズは、サービス プロバイダの Maximum Transmission Unit によって制限される。アプリケーション データが大きすぎる場合、メソッドは失敗し、DPNERR_DATATOOLARGE を返す。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Server::Initialize

IDirectPlay8Server インターフェイスおよびリモート クライアントからメッセージを受信する、サーバーのコード内のエントリ ポイントを登録する。このメソッドを呼び出してから、このインターフェイスのその他のメソッドを呼び出す必要がある。

HRESULT Initialize(
PVOID const pvUserContext,
const PFNDPNMESSAGEHANDLER pfn,
const DWORD dwFlags
);

パラメータ

pvUserContext
メッセージ ハンドラの呼び出しで指定される、ユーザー指定のコンテキスト値。ユーザー指定のコンテキスト値は、複数のインターフェイスから共通のメッセージ ハンドラに送信されたメッセージを区別するのに役立つ。
pfn
PFNDPNMESSAGEHANDLER コールバック関数へのポインタ。この関数は、リモート クライアントからのすべてのメッセージおよび IDirectPlay8Server インターフェイスからのセッション変更の通知を受け取る。
dwFlags
次のフラグを指定できる。
DPNINITIALIZE_DISABLEPARAMVAL
このフラグを渡すと、現在のオブジェクトに対するパラメータ妥当性の検証が無効になる。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM

注意

IDirectPlay8Server インターフェイスを取得するには、CoCreateInstance を使用した後に、まずこのメソッドを呼び出す。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Server::RegisterLobby

起動したアプリケーションがゲームの状態を自動的にロビーに伝達できるようにする。

HRESULT RegisterLobby(
const DPNHANDLE dpnHandle,
IDirectPlay8LobbiedApplication *const pIDP8LobbiedApplication,
const DWORD dwFlags
);

パラメータ

dpnHandle
IDirectPlay8LobbiedApplication::UpdateStatus を呼び出すときに使用する接続ハンドル。
pIDP8LobbiedApplication
アプリケーションを指定する IDirectPlay8LobbiedApplication オブジェクトへのポインタ。
dwFlags
次のフラグのいずれかを指定する。
DPNLOBBY_REGISTER
ロビーをアプリケーションに登録する。
DPNLOBBY_UNREGISTER
アプリケーションへのロビーの登録を解除する。

戻り値

成功した場合は S_OK を返す。それ以外の場合は、次のエラー値を返す。

DPNERR_INVALIDPARAM

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Server::RemovePlayerFromGroup

グループからクライアントを削除する。

HRESULT RemovePlayerFromGroup(
const DPNID idGroup,
const DPNID idClient,
PVOID const pvAsyncContext,
DPNHANDLE *const phAsyncHandle,
const DWORD dwFlags
);

パラメータ

idGroup
クライアントの削除先グループの識別子を指定する DPNID 型の変数。
idClient
グループから削除するクライアントの識別子を指定する DPNID 型の変数。
pvAsyncContext
ユーザー指定のコンテキストへのポインタ。これは、DPN_MSGID_ASYNC_OP_COMPLETE システム メッセージの pvUserContext メンバに返される。
phAsyncHandle
DPNHANDLE。値が返される。ただし、Microsoft® DirectPlay® 8.0 ではこの操作の取り消しは許可されていないため、値を使用することはできない。
dwFlags
このメソッドが処理される方法を制御するフラグ。このメソッドには、次のフラグを設定できる。
DPNREMOVEPLAYERFROMGROUP_SYNC
メソッドを同期をとりながら処理する。

戻り値

メソッドが同期をとりながら処理され、処理が成功した場合は S_OK を返す。デフォルトでは、このメソッドは非同期に実行され、通常は DPNSUCCESS_PENDING か、または次のいずれかのエラー値を返す。

DPNERR_INVALIDFLAGS
DPNERR_INVALIDGROUP

注意

このメソッドが呼び出されると、サーバーのメッセージ ハンドラは、DPN_MSGID_REMOVE_PLAYER_FROM_GROUP メッセージを受け取る。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Server::ReturnBuffer

DPN_MSGID_RECEIVE システム メッセージの pReceiveData メンバによってアプリケーションに提供されたメッセージ バッファを取得する。ユーザーのメッセージ ハンドラが RECEIVE コールバックに DPNSUCCESS_PENDING を返した場合、バッファの所有権はアプリケーションに移行したと見なされ、この呼び出しにより所有権が Microsoft® DirectPlay® に戻るまで所有権の解放や変更は行われない。

HRESULT ReturnBuffer(
const DPNHANDLE hBufferHandle,
const DWORD dwFlags
);

パラメータ

hBufferHandle
メッセージ用のバッファ ハンドルを指定する DPNHANDLE 型の変数。これは、DPNMSG_RECEIVE システム メッセージの hBufferHandle メンバで取得する。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDHANDLE
DPNERR_INVALIDPARAM

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Server::SendTo

セッション内のクライアントまたはグループにデータを送信する。メッセージは同期または非同期で送信することができる。

HRESULT SendTo(
const DPNID dpnid,
const DPN_BUFFER_DESC *const pBufferDesc,
const DWORD cBufferDesc,
const DWORD dwTimeOut,
void *const pvAsyncContext,
DPNHANDLE *const phAsyncHandle,
const DWORD dwFlags
);

パラメータ

dpnid
データを受信するクライアントまたはグループの識別子。セッション内のすべてのプレーヤーにメッセージを送信する場合は、このパラメータを DPNID_ALL_PLAYERS_GROUP に設定する。
pBufferDesc
送信するデータを記述する DPN_BUFFER_DESC 構造体へのポインタ。
cBufferDesc
pBufferDesc が示す DPN_BUFFER_DESC 構造体の数。このバージョンの Microsoft® DirectPlay® では、バッファは 1 つでなければならない。
dwTimeOut
メッセージの送信を待つ時間 (ミリ秒単位)。メッセージが dwTimeOut 値で送信されていない場合、メッセージは送信されない。メッセージの送信に対してタイム アウトが必要でない場合は、このパラメータを 0 に設定する。
pvAsyncContext
ユーザー指定のコンテキストへのポインタ。これは、DPN_MSGID_SEND_COMPLETE システム メッセージの pvUserContext メンバに返される。
phAsyncHandle
DPNHANDLE。メソッドが戻ると、phAsyncHandle は、IDirectPlay8Server::CancelAsyncOperation に渡して処理を取り消すことができるハンドルをポイントする。dwFlags に DPNSEND_SYNC フラグが設定されている場合、このパラメータは NULL に設定しなければならない。
dwFlags
送信動作を記述するフラグ。次の 1 つ以上のフラグを設定することができる。
DPNSEND_SYNC
SendTo 要求を同期をとりながら処理する。
DPNSEND_NOCOPY
DPN_BUFFER_DESC 構造体のデータを使用し、内部コピーは行わない。これは、効率的なデータ送信の方法である。しかし、受信側がメッセージを処理する前に、送信側がメッセージを変更できるため、堅牢ではなくなる。このフラグを DPNSEND_NOCOMPLETE と共に使用することはできない。
DPNSEND_NOCOMPLETE
メッセージ ハンドラに DPN_MSGID_SEND_COMPLETE 構造体を送信しない。このフラグを DPNSEND_NOCOPY または DPNSEND_GUARANTEED と共に使用することはできない。また、このフラグを使用する場合、pvAsyncContext は NULL でなければならない。
DPNSEND_COMPLETEONPROCESS
メッセージがターゲットに配信され、メッセージの受信を示すターゲットのメッセージ ハンドラが返されるとき、DPN_MSGID_SEND_COMPLETE をメッセージ ハンドラに送信する。このフラグが設定された場合は、余分な内部メッセージのオーバーヘッドがあり、メッセージの送信処理が著しく低下する可能性がある。このフラグを設定した場合は、DPNSEND_GUARANTEED も設定する必要がある。
DPNSEND_GUARANTEED
保証付き配信方式を使用してメッセージを送信する。
DPNSEND_PRIORITY_HIGH
メッセージの優先順位を高く設定する。このフラグを DPNSEND_PRIORITY_LOW と共に使用することはできない。
DPNSEND_PRIORITY_LOW
メッセージの優先順位を低く設定する。このフラグを DPNSEND_PRIORITY_HIGH と共に使用することはできない。
DPNSEND_NOLOOPBACK
ローカル プレーヤーを含むグループに送信しているときに、メッセージ ハンドラへの DPN_MSGID_RECEIVE システム メッセージを抑制する。たとえば、セッション全体にある要素を全要素にコピーする場合は、このフラグが便利である。
DPNSEND_NONSEQUENTIAL
このフラグが設定された場合、ターゲット アプリケーションは、ユーザーのコンピュータに到着した順にメッセージを受け取る。このフラグが設定されていない場合、メッセージはシーケンシャルに配信され、ターゲット アプリケーションは送信された順にメッセージを受け取る。したがって、着信したメッセージを、欠落しているメッセージが到着するまでバッファに格納する場合がある。

戻り値

メソッドが同期をとりながら処理され、処理が成功した場合は S_OK を返す。デフォルトでは、このメソッドは非同期に実行され、通常は DPNSUCCESS_PENDING か、または次のいずれかのエラー値を返す。

DPNERR_CONNECTIONLOST
DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM
DPNERR_INVALIDPLAYER
DPNERR_TIMEDOUT

注意

このメソッドは、受け取り側のメッセージ ハンドラに DPN_MSGID_RECEIVE システム メッセージを生成する。データは、関連付けられている構造体の pReceiveData メンバに保持されている。

メッセージには、低、通常、高の 3 つの優先順位のいずれかを設定できる。メッセージに低い優先順位または高い優先順位を指定するには dwFlags に適切なフラグを設定する。どちらの優先順位フラグも設定しなかった場合、メッセージは通常の優先順位になる。送信優先順位の詳細については、「ネットワーキングの基本」を参照すること。

SendTo 要求が完了すると、送信側のメッセージ ハンドラに DPN_MSGID_SEND_COMPLETE システム メッセージが送信される。要求の成功または失敗は、関連付けられた構造体の hResultCode メンバに保持される。dwflags に DPNSEND_NOCOMPLETE フラグを設定すると、送信完了のシステム メッセージは送信されない。

通常、メッセージが送信されると直ちに、送信完了が送信元のコンピュータに送信される。言い換えると、送信完了は、メッセージがターゲット上で処理されたことを必ずしも意味しない。メッセージはまだキュー内にある可能性もある。メッセージがターゲットで処理されたことを確認するには、dwFlags にDPNSEND_COMPLETEONPROCESS フラグを設定する。このフラグを設定すると、ターゲットのメッセージ ハンドラがメッセージを処理して戻るまで、送信完了は送信されない。

アプリケーションは IDirectPlay8Client、IDirectPlay8Server、または IDirectPlay8Peer で Close を呼び出す前や最終リリースをする前に、CancelAsyncOperation を呼び出して残っている Send をキャンセルすべきである。それに失敗すると予期せぬ結果が起きる。

注 メソッドが戻るまでは、データ バッファなどのリソースが有効な状態のままであると見なしてはならない。このメソッドを非同期に呼び出す場合、呼び出しが戻る前に DPN_MSGID_SEND_COMPLETE メッセージを受け取り、メッセージ ハンドラが処理してしまうことがある。メッセージ ハンドラがデータ バッファなどのリソースを割り当て解除、または無効にした場合、メソッドが呼び出された後でリソースが無効になることがある。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Server::SetApplicationDesc

ホストされているアプリケーションの設定を変更する。変更できるのは、いくつかの設定のみである。

HRESULT SetApplicationDesc(
const DPN_APPLICATION_DESC *const pad,
const DWORD dwFlags
);

パラメータ

pad
変更するアプリケーションの設定を記述する DPN_APPLICATION_DESC 構造体へのポインタ。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_DATATOOLARGE
DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM

注意

このメソッドを使って変更できるのは、DPN_APPLICATION_DESC 構造体の以下のメンバのみである。

  • dwMaxPlayers
  • pwszSessionName
  • pwszPassword
  • pvApplicationReservedData
  • dwApplicationReservedDataSize

DPN_APPLICATION_DESC 構造体の pvApplicationReservedData メンバに割り当てるアプリケーション データの最大サイズは、サービス プロバイダの Maximum Transmission Unit によって制限される。アプリケーション データが大きすぎる場合、メソッドは失敗し、DPNERR_DATATOOLARGE を返す。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Server::SetCaps

現在のインターフェイスの DPN_CAPS 構造体を設定する。

HRESULT SetCaps(
const DPNCAPS *const pdpCaps,
const DWORD dwFlags
);

パラメータ

pdpCaps
現在のインターフェイスに関する情報の設定に使用される DPN_CAPS 構造体へのポインタ。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER
DPNERR_UNINITIALIZED

注意

このメソッドは、指定されたサービス プロバイダに対するパラメータを設定する。Initialize の呼び出しが成功した後に、このメソッドを呼び出す必要がある。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Server::SetGroupInfo

グループ名など、グループに関連付けられているデータ ブロックを設定する。

HRESULT SetGroupInfo(
const DPNID dpnid,
DPN_GROUP_INFO *const pdpnGroupInfo,
PVOID const pvAsyncContext,
DPNHANDLE *const phAsyncHandle,
const DWORD dwFlags
);

パラメータ

dpnid
データ ブロックを変更するグループの識別子を指定する DPNID 型の変数。
pdpnGroupInfo
設定するグループ データを記述する DPN_GROUP_INFO 構造体へのポインタ。この構造体の pwszName メンバまたは pvData メンバの値を変更するには、dwInfoFlags メンバの対応する DPNINFO_NAME OR DPNINFO_DATA フラグを設定する必要がある。
pvAsyncContext
ユーザー指定のコンテキストへのポインタ。これは、DPN_MSGID_ASYNC_OP_COMPLETE システム メッセージの pvUserContext メンバに返される。
phAsyncHandle
DPNHANDLE。値が返される。ただし、Microsoft® DirectPlay® 8.0 ではこの操作の取り消しは許可されていないため、値を使用することはできない。
dwFlags
このメソッドが処理される方法を制御するフラグ。このメソッドには、次のフラグを設定できる。
DPNSETGROUPINFO_SYNC
メソッドを同期をとりながら処理する。

戻り値

メソッドが同期をとりながら処理され、処理が成功した場合は S_OK を返す。デフォルトでは、このメソッドは非同期に実行され、通常は DPNSUCCESS_PENDING か、または次のいずれかのエラー値を返す。

DPNERR_INVALIDFLAGS
DPNERR_INVALIDGROUP

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Server::SetServerInfo

アプリケーションでサーバーの静的設定を設定する。クライアントがサーバーに正しく接続されると、クライアントは IDirectPlay8Client::GetServerInfo メソッドを呼び出すことにより、このメソッドで設定された情報を取得することができる。

HRESULT SetServerInfo(
const DPN_PLAYER_INFO *const pdpnPlayerInfo,
PVOID const pvAsyncContext,
DPNHANDLE *const phAsyncHandle,
const DWORD dwFlags
);

パラメータ

pdpnPlayerInfo
設定するサーバー情報を保持する DPN_PLAYER_INFO 構造体へのポインタ。
pvAsyncContext
ユーザー指定のコンテキストへのポインタ。これは、DPN_MSGID_ASYNC_OP_COMPLETE システム メッセージの pvUserContext メンバに返される。
phAsyncHandle
DPNHANDLE。値が返される。ただし、Microsoft® DirectPlay® 8.0 ではこの操作の取り消しは許可されていないため、値を使用することはできない。
dwFlags
このメソッドが処理される方法を制御するフラグ。このメソッドには、次のフラグを設定できる。
DPNSETSERVERINFO_SYNC
メソッドを同期をとりながら処理する。

戻り値

メソッドが同期をとりながら処理され、処理が成功した場合は S_OK を返す。要求が非同期で処理される場合、メソッドが直ちに処理されると、S_OK を返す場合がある。デフォルトでは、このメソッドは非同期に実行され、通常は DPNSUCCESS_PENDING か、または次のいずれかのエラー値を返す。

DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM
DPNERR_NOCONNECTION

注意

このメソッドは、IDirectPlayServer::Host を呼び出す前、およびセッション中はいつでも呼び出せる。

IDirectPlay8Server::SetServerInfo メソッドを使用すると処理に負担がかかるため、非静的情報は IDirectPlay8Server::SendTo メソッドを使用して転送すること。

クライアントがアプリケーションに接続した後、このメソッドを使用してサーバー情報を変更できる。接続後にこのメソッドを呼び出すと、データの更新を知らせる DPN_MSGID_SERVER_INFO システム メッセージがすべてのプレーヤーに対して生成される。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlay8Server::SetSPCaps

指定されたサービス プロバイダに対する DPN_SP_CAPS 構造体を設定する。

HRESULT SetSPCaps(
const GUID *const pguidSP,
const DPN_SP_CAPS *const pdpnSPCaps
);

パラメータ

pguidSP
情報を設定するサービス プロバイダを指定する GUID へのポインタ。
pdpnSPCaps
指定したサービス プロバイダに関する情報を設定する DPN_SP_CAPS 構造体へのポインタ。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER
DPNERR_UNINITIALIZED

注意

このメソッドは、指定されたサービス プロバイダに対するパラメータを設定する。Initialize の呼び出しが成功した後に、このメソッドを呼び出す必要がある。現在、この呼び出しでは dwNumThreads メンバのみ設定することができる。dwFlags メンバは 0 でなければならない。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


IDirectPlayVoiceClient

アプリケーションは、IDirectPlayVoiceClient インターフェイスのメソッドを使用して、音声セッションのクライアントを管理する。

IDirectPlayVoiceClient インターフェイスのメソッドは、次のように分類できる。

バッファ管理 | Create3DSoundBuffer
 | Delete3DSoundBuffer
その他 | GetCaps
 | GetCompressionTypes
 | GetSoundDeviceConfig
 | SetNotifyMask
セッション管理 | Connect
 | Disconnect
 | GetClientConfig
 | GetSessionDesc
 | GetTransmitTargets
 | Initialize
 | SetClientConfig
 | SetTransmitTargets

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。


IDirectPlayVoiceClient::Connect

クライアントを Microsoft® DirectPlay® Voice セッションに接続する。

HRESULT Connect(
PDVSOUNDDEVICECONFIG pSoundDeviceConfig,
PDVCLIENTCONFIG pdvClientConfig,
DWORD dwFlags
);

パラメータ

pSoundDeviceConfig
サウンド デバイス構成を記述する DVSOUNDDEVICECONFIG 構造体へのポインタ。
pdvClientConfig
クライアントの一般的構成を記述する DVCLIENTCONFIG 構造体へのポインタ。
dwFlags
フラグ。次のフラグを指定できる。
DVFLAGS_SYNC
処理が完了するまでメソッドは戻らない。

戻り値

メソッドが同期をとりながら処理され、処理が成功した場合は、DV_OK を返す。デフォルトでは、このメソッドは非同期に実行され、DVERR_PENDING を返す。エラーの場合は、次のいずれかの値を返す。

DVERR_ALREADYPENDING
DVERR_COMPRESSIONNOTSUPPORTED
DVERR_INCOMPATIBLEVERSION
DVERR_INVALIDBUFFER
DVERR_INVALIDDEVICE
DVERR_INVALIDFLAGS
DVERR_INVALIDOBJECT
DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER
DVERR_NOTINITIALIZED
DVERR_OUTOFMEMORY
DVERR_RUNSETUP
DVERR_SENDERROR
DVERR_SOUNDINITFAILURE
DVERR_TIMEOUT
DVERR_TRANSPORTNOPLAYER
DVERR_TRANSPORTNOSESSION
DVERR_CONNECTED
DVERR_NOVOICESESSION

注意

DirectPlay Voice セッションにクライアントを接続する前にセットアップ ウィザードを呼び出し、再生とキャプチャ用に選択したサウンド デバイスをテストする必要がある。アプリケーションの起動時には、IDirectPlayVoiceTest::CheckAudioSetup を使用してオーディオ構成を確認する。このメソッドが DVERR_RUNSETUP を返す場合、指定されたサウンド構成はテストされていない。セットアップ ウィザードは構成ごとに 1 回だけ実行する必要がある。

バッファの形式が正しくない場合、メソッドは DVERR_INVALIDBUFFER を返す。

DirectPlay Voice がバッファに書き込もうとしたときにバッファまたはバッファの一部がロックされている場合、メソッドは DVERR_INVALIDBUFFER を返し、DirectPlay Voice はセッションから接続解除される。また、DVMSGID_SESSIONLOST メッセージを受け取る。関連付けられている構造体の hResult メンバは DVERR_LOCKEDBUFFER に設定される。この後のメソッドの呼び出しは、DVERR_NOTCONNECTED エラー コードを返す。

全二重処理がサポートされていない場合、DirectPlay Voice は半二重 (聴取専用) モードに戻る。半二重モードかどうかを調べるには、接続を完了した後で、IDirectPlayVoiceClient::GetSoundDeviceConfig を呼び出す。半二重モードの場合、DVSOUNDDEVICECONFIG 構造体の dwFlags メンバに DVSOUNDCONFIG_HALFDUPLEX フラグが設定されている。

インターフェイスの取得方法とは関係なく、DirectPlayVoiceClient オブジェクトでは、IDirectPlayVoiceClient::Disconnect が呼び出されるまで、AddRef により、使用する IDirectSound インターフェイスと IdirectSoundCapture インターフェイスへの参照が維持される。Disconnect が呼び出されると、DirectPlayVoiceClient オブジェクトは両インターフェイスに対して Release を呼び出す。

DVFLAGS_SYNC フラグを設定して、同期をとってこのメソッドを呼び出した場合、メッセージ ハンドラに DVMSG_CONNECTRESULT メッセージは送信されない。この場合、接続結果はこのメソッドの戻り値によって決まる。

このメソッドが非同期に呼び出された場合 (デフォルト)、メソッド呼び出し直後に DVERR_PENDING エラー値が返され、バッググラウンドで接続要求が処理される。DirectPlay Voice クライアントが接続結果を含んだ DVMSG_CONNECTRESULT メッセージを生成するまで、接続の状態は不明である。

接続がペンディング状態になっている間に IDirectPlayVoiceClient::Connect を呼び出すと、DVERR_ALREADYPENDING が返される。また、1 度に 1 つの接続のみをペンディング状態にできる。

このメソッドを呼び出す前に、特定の DirectPlay オブジェクトに対してトランスポート セッションを開始している必要がある。IDirectPlayVoiceClient::Initialize の呼び出しが成功した後に Connect メソッドを呼び出す必要がある。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。


IDirectPlayVoiceClient::Create3DSoundBuffer

プレーヤーまたはグループに対する 3D サウンド バッファを取得する。3D サウンド バッファ オブジェクトのメソッドを使用すると、指定したグループまたはプレーヤーから受信した音声伝送の仮想 3D 位置を変更できる。

HRESULT Create3DSoundBuffer(
DVID dvID,
LPDIRECTSOUNDBUFFER lpdsSourceBuffer,
DWORD dwPriority,
DWORD dwFlags,
LPDIRECTSOUND3DBUFFER* lpUserBuffer
);

パラメータ

dvID
ユーザーがバッファを保存する対象となるプレーヤーまたはグループの識別情報を指定する DVID 型の変数。また、DVID_REMAINING を指定すると、ユーザー バッファがないすべてのプレーヤーまたはグループに対して 3D ユーザー バッファを作成できる。DVID_REMAINING を指定する場合、lpdsBufferDesc に NULL を指定し、dwPriority パラメータと dwFlags パラメータを 0 に設定する必要がある。
lpdsSourceBuffer
Microsoft® DirectPlay® Voice のメイン バッファの作成に使用する、IDirectSoundBuffer インターフェイスへのポインタ。NULL、またはユーザー作成の Microsoft DirectSound® バッファを指定できる。このメンバが NULL の場合、DirectPlay Voice がバッファを作成する。
dwPriority
ダイレクト パススルー。IDirectSoundBuffer::Play が呼び出されるとき、この値は dwPriority パラメータに渡される。詳細については、「IDirectSoundBuffer8::Play」を参照すること。lpdsMainBufferDesc が NULL の場合、このパラメータは 0 でなければならない。
dwFlags
ダイレクト パススルー。IDirectSoundBuffer::Play が呼び出されるとき、この値は dwFlags パラメータに渡される。詳細については、「IDirectSoundBuffer8::Play」を参照すること。lpdsMainBufferDesc が NULL の場合、このパラメータは 0 でなければならない。
lpUserBuffer
予約されたバッファが置かれるメモリへのポインタ。

戻り値

成功した場合は DV_OK を返す。または、次のいずれかのエラー値を返す。

DVERR_ALREADYBUFFERED
DVERR_INVALIDOBJECT
DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER
DVERR_NOTALLOWED
DVERR_NOTCONNECTED
DVERR_NOTINITIALIZED
DVERR_OUTOFMEMORY
DVERR_SESSIONLOST

注意

DirectPlay の音声セッションがミキシング サーバー セッションの場合、このメソッドは失敗し、DVERR_NOTALLOWED を返す。

3D サウンド バッファ オブジェクトのすべてのメンバ関数にアクセスできるが、DirectPlay Voice クライアントがバッファを使用して受信オーディオのストリーミングを行うため、DirectSound3Dbuffer オブジェクトの Lock、UnLock、Play の各メソッドは使用しないこと。

ここでバッファを指定した場合、DirectPlay はそのバッファをプレーヤーまたはグループのバッファとして使用する。ユーザー作成のバッファには次の制限がある。

  • バッファは、22Khz、16 ビット、モノラル フォーマットでなければならない。
  • バッファの長さは 1 秒以上でなければならない。
  • バッファは、DSBCAPS_GETCURRENTPOSITION2 および DSBCAPS_CTRL3D フラグを使用して作成されていなければならない。
  • バッファはプライマリ バッファであってはならない。
  • DirectPlay にバッファを渡すときは、バッファが再生中であってはならない。

バッファの形式が正しくない場合、メソッドは DVERR_INVALIDBUFFER を返す。

DirectPlay にバッファを渡すときは、バッファがロックされていてはならない。個々のユーザーが不必要になるか、プレーヤーが音声セッションを離れる場合、IDirectPlayVoiceClient::Delete3DSoundBuffer を呼び出し、リソースを解放する必要がある。

DirectPlay Voice がバッファに書き込もうとしたときにバッファまたはバッファの一部がロックされている場合、メソッドは DVERR_INVALIDBUFFER を返す。メソッドが返った後でバッファをロックした場合は、DVMSGID_SESSIONLOST メッセージを受け取る。関連付けられた構造体の hResult メンバに DVERR_LOCKEDBUFFER が設定される。この後のメソッドの呼び出しは、DVERR_NOTCONNECTED エラー コードを返す。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。


IDirectPlayVoiceClient::Delete3DSoundBuffer

3D サウンド バッファ オブジェクトの排他制御を Microsoft® DirectPlay® ボイス クライアント オブジェクトに返す。

HRESULT Delete3DSoundBuffer(
DVID dvID
LPDIRECTSOUND3DBUFFER* lpUserBuffer
);

パラメータ

dvID
ユーザーがバッファを削除する対象となるプレーヤーまたはグループの DVID。
lpUserBuffer
削除するユーザー バッファへのポインタ。IDirectPlayVoiceClient::Create3DSoundBuffer メソッドにより取得されたユーザー バッファを指定する必要がある。

戻り値

成功した場合は DV_OK を返す。または、次のいずれかのエラー値を返す。

DVERR_ALREADYBUFFERED
DVERR_INVALIDOBJECT
DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER
DVERR_NOTALLOWED
DVERR_NOTBUFFERED
DVERR_NOTCONNECTED
DVERR_NOTINITIALIZED
DVERR_SESSIONLOST

注意

DirectPlay Voice セッションがミキシング サーバー セッションの場合、このメソッドは失敗し、DVERR_NOTALLOWED を返す。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。


IDirectPlayVoiceClient::Disconnect

Microsoft® DirectPlay® Voice クライアントを既存の DirectPlay Voice セッションから接続解除する。

HRESULT Disconnect(
DWORD dwFlags
);

パラメータ

dwFlags
フラグ。次のフラグを指定できる。

DVFLAGS_SYNC

処理が完了するまで戻らない。

戻り値

成功した場合は DV_OK を返す。または、次のいずれかのエラー値を返す。

DVERR_ALREADYPENDING
DVERR_CONNECTABORTING
DVERR_INVALIDFLAGS
DVERR_INVALIDPARAM
DVERR_NOTCONNECTED
DVERR_NOTINITIALIZED
DVERR_PENDING
DVERR_SESSIONLOST
DVERR_TIMEOUT

注意

このメソッドを呼び出すと、録音と再生はすべて停止する。処理中の接続は、この呼び出しにより取り消される。

DVFLAGS_SYNC が指定されていない場合、メソッド呼び出し直後に DVERR_PENDING エラー値が返され、バッググラウンドで接続解除要求が処理される。DirectPlay Voice クライアントが接続解除結果を含んだ DVMSG_DISCONNECTRESULT メッセージを生成するまで、接続解除の状態は不明である。一度に 1 つの接続解除のみをペンディング状態にできる。接続解除が保留になっている間に IDirectPlayVoiceClient::Disconnect を呼び出した場合、DirectPlay は DVERR_ALREADYPENDING エラー値を返す。

DVFLAGS_SYNC フラグを設定し、同期をとってこのメソッドを呼び出した場合、Disconnect メソッドが完了するまでこのメソッドは戻らない。接続解除の結果はこのメソッドの戻り値が示す。DVMSGID_DISCONNECTRESULT メッセージは生成されない。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。


IDirectPlayVoiceClient::GetCaps

Microsoft® DirectPlay® Voice の能力を取得する。

HRESULT GetCaps(
PDVCAPS pCaps
);

パラメータ

pCaps
DirectPlayVoiceClient オブジェクトの機能を保持する DVCAPS 構造体へのポインタ。

戻り値

成功した場合は DV_OK を返す。または、次のいずれかのエラー値を返す。

DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。


IDirectPlayVoiceClient::GetClientConfig

クライアントの構成を取得する。

HRESULT GetClientConfig(
PDVCLIENTCONFIG pClientConfig
);

パラメータ

pClientConfig
ローカル クライアントの構成を保持する DVCLIENTCONFIG 構造体へのポインタ。

戻り値

成功した場合は DV_OK を返す。または、次のいずれかのエラー値を返す。

DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER
DVERR_NOTCONNECTED
DVERR_NOTINITIALIZED
DVERR_SESSIONLOST

注意

このメンバを呼び出す前に、DVCLIENTCONFIG 構造体の dwSize メンバを設定する必要がある。

このメソッドは、Microsoft® DirectPlay® Voice セッションとの接続が成功した後にのみ、呼び出すことができる。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。


IDirectPlayVoiceClient::GetCompressionTypes

システムで利用可能な圧縮のタイプを取得する。

HRESULT GetCompressionTypes(
PVOID pData,
PDWORD pdwDataSize,
PDWORD pdwNumElements,
DWORD dwFlags
);

パラメータ

pData
DVCOMPRESSIONINFO 構造体の配列を受け取るバッファへのポインタ。このオブジェクトでサポートされている圧縮タイプごとに 1 つの構造体が含まれる。
pdwDataSize
pData パラメータに渡されたバッファ サイズをバイト単位で保持する DWORD へのポインタ。
pdwNumElements
メソッドが DVCOMPRESSIONINFO 構造体の配列に返された要素の数を書き込む DWORD へのポインタ。pData で指定されたバッファの容量が、情報を保持できるサイズである場合にのみ、構造体の数が保持される。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は DP_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DVERR_BUFFERTOOSMALL
DVERR_INVALIDFLAGS
DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER

注意

渡されたバッファが小さく、圧縮タイプのリストが格納できない場合、メソッドは DVERR_BUFFERTOOSMALL を返し、最低限必要なサイズが pdwDataSize パラメータに設定される。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。


IDirectPlayVoiceClient::GetSessionDesc

セッションのプロパティを取得する。

HRESULT GetSessionDesc(
PDVSESSIONDESC pvSessionDesc
);

パラメータ

pvSessionDesc
セッションの記述を受け取る DVSESSIONDESC 構造体へのポインタ。

戻り値

成功した場合は DV_OK を返す。または、次のいずれかのエラー値を返す。

DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER
DVERR_NOTCONNECTED
DVERR_NOTINITIALIZED
DVERR_SESSIONLOST

注意

このメソッドを呼び出す前に、DVSESSIONDESC 構造体の dwSize メンバを設定する必要がある。

このメソッドは、Microsoft® DirectPlay® Voice セッションとの接続が成功した後にのみ、呼び出すことができる。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。


IDirectPlayVoiceClient::GetSoundDeviceConfig

セッションのサウンド デバイス構成を取得する。

HRESULT GetSoundDeviceConfig(
PDVSOUNDDEVICECONFIG pSoundDeviceConfig,
PDWORD pdwSize
);

パラメータ

pSoundDeviceConfig
サウンド デバイスの構成を格納する DVSOUNDDEVICECONFIG 構造体へのポインタ。
pdwSize
pSoundDeviceConfig パラメータのバッファのサイズを指定する DWORD へのポインタ。バッファが小さすぎる場合、メソッドが DVERR_BUFFERTOOSMALL を返し、必要なバッファのサイズがこのパラメータに保持される。

戻り値

成功した場合は DV_OK を返す。または、次のいずれかのエラー値を返す。

DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER
DVERR_NOTCONNECTED
DVERR_NOTINITIALIZED
DVERR_SESSIONLOST

注意

このメソッドは、Microsoft® DirectPlay® Voice セッションとの接続が成功した後にのみ、呼び出すことができる。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。


IDirectPlayVoiceClient::GetTransmitTargets

このクライアントからの音声ストリームの送信ターゲットを取得する (存在する場合)。

HRESULT GetTransmitTargets(
PDVID pdvIDTargets,
PDWORD pdwNumTargets,
DWORD dwFlags
);

パラメータ

pdvIDTargets
IDirectPlayVoiceClient::SetTransmitTargets メソッドまたは IDirectPlayVoiceServer::SetTransmitTargets メソッドにより設定されたターゲットを指定する DVID の配列を格納するメンバ。このパラメータに NULL を指定して、ターゲットの数を取得することができる。
pdwNumTargets
配列内の DVID の数。このメソッドを呼び出す場合、この値は IDirectPlayVoiceClient::SetTransmitTargets メソッドで設定されたターゲット数と一致する必要がある。呼び出しが成功すると、Microsoft® DirectPlay® は pdvIDTargets 配列に書き込まれた要素の数を返す。

pdvIDTargets が NULL である場合、0 に設定しておく。

dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は DV_OK を返す。または、次のいずれかのエラー値を返す。

DVERR_BUFFERTOOSMALL
DVERR_INVALIDFLAGS
DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER
DVERR_NOTALLOWED
DVERR_NOTCONNECTED
DVERR_NOTINITIALIZED

注意

pdvIDTargets パラメータに返される値は、プレーヤー DVID かグループ DVID、または定数 DVID_ALLPLAYERS である。

pdvIDTargets に指定されたバッファが小さく、ターゲットのリストが格納できない場合、このメソッドは DVERR_INVALIDPOINTER を返し、必要な要素数が pdwNumTargets に設定される。

ターゲットが指定されていない場合、pdwNumTargets は 0 に設定され、戻り値は DV_OK になる。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。


IDirectPlayVoiceClient::Initialize

DirectPlayVoiceClient オブジェクトを DirectPlay オブジェクトと関連付けて初期化する。また、このメソッドはメッセージ ハンドラを DirectPlayVoiceClient オブジェクトに登録する。

IDirectPlayVoiceClient::Connect メソッドを呼び出す前に、このメソッドの呼び出しが成功している必要がある。

HRESULT Initialize(
PVOID pVoid,
PDVMESSAGEHANDLER pMessageHandler,
PVOID pUserContext,
PDWORD pdwMessageMask,
DWORD dwMessageMaskElements
);

パラメータ

pVoid
この DirectPlayVoiceClient オブジェクトが使用する DirectPlay オブジェクトに対する IUnknown インターフェイスへのポインタ。
pMessageHandler
処理する DirectPlayVoiceClient メッセージがある場合に呼び出されるユーザー定義のコールバック関数。DirectPlayVoiceClient オブジェクト内のスレッドがコールバック関数を呼び出すため、プロセスのメイン スレッドのコンテキストにはコールバック関数は呼び出されない。
pUserContext
関数が呼び出されるたびにコールバック関数に渡される、アプリケーションにより定義された構造体へのポインタ。
pdwMessageMask
DirectPlay Voice がユーザーのコールバック関数に送信するメッセージ識別子を保持する DWORD の配列。メッセージ識別子をこの配列に指定しない場合、メッセージは送信されない。それぞれのメッセージ識別子は一度だけ配列に表示される。有効なメッセージ識別子だけが許可される。たとえば、DVMSGID_CONNECTRESULT はサーバーのインターフェイスには無効だが、クライアントのインターフェイスに対しては有効である。すべてのメッセージを有効にするには、この値に NULL を指定する。
dwMessageMaskElements
pdwMessageMask パラメータに指定された要素の数。pdwMessageMask が NULL である場合、0 に設定しておく。

戻り値

成功した場合は DV_OK を返す。または、次のいずれかのエラー値を返す。

DVERR_ALREADYINITIALIZED
DVERR_GENERIC
DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER
DVERR_NOCALLBACK
DVERR_TRANSPORTNOTINIT

注意

IDirectPlayVoiceClient::SetNotifyMask を呼び出して、音声セッションの進行中に通知マスクを変更することができる。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。


IDirectPlayVoiceClient::SetClientConfig

クライアント構成を設定する。

HRESULT SetClientConfig(
PDVCLIENTCONFIG pClientConfig
);

パラメータ

pClientConfig
設定する構成の記述を保持する DVCLIENTCONFIG 構造体へのポインタ。

戻り値

成功した場合は DV_OK を返す。または、次のいずれかのエラー値を返す。

DVERR_INVALIDFLAGS
DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER
DVERR_NOTCONNECTED
DVERR_NOTINITIALIZED
DVERR_SESSIONLOST

注意

このメソッドは、Microsoft® DirectPlay® Voice セッションとの接続が成功した後にのみ、呼び出すことができる。

このメソッドを呼び出すと、DVCLIENTCONFIG 構造体のすべてのパラメータが設定される。したがって、設定を変更しないようにするには、IDirectPlayVoiceClient::GetClientConfig を使用して、現在の構成を取得する必要がある。次に、パラメータを変更し、IDirectPlayVoiceClient::SetClientConfig を呼び出す。

セッションが半二重で実行されている場合、録音に関連する GetClientConfig のメンバは無視される。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。


IDirectPlayVoiceClient::SetNotifyMask

メッセージ ハンドラに送信するメッセージを指定する。

HRESULT SetNotifyMask(
PDWORD pdwMessageMask,
DWORD dwMessageMaskElements
);

パラメータ

pdwMessageMask
Microsoft® DirectPlay® Voice がユーザーのコールバック関数に送信するメッセージ識別子を保持する DWORD の配列へのポインタ。メッセージ識別子をこの配列に指定しない場合、メッセージは送信されない。それぞれのメッセージ識別子は一度だけ配列に表示される。有効なメッセージ識別子だけが許可される。たとえば、DVMSGID_CONNECTRESULT はサーバーのインターフェイスには無効だが、クライアントのインターフェイスに対しては有効である。すべてのメッセージを有効にするには、この値に NULL を指定する。
dwMessageMaskElements
pdwMessageMask パラメータに指定された要素の数。pdwMessageMask が NULL である場合、0 に設定しておく。

戻り値

成功した場合は DV_OK を返す。または、次のいずれかのエラー値を返す。

DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER
DVERR_NOCALLBACK
DVERR_NOTINITIALIZED

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。


IDirectPlayVoiceClient::SetTransmitTargets

ローカル クライアントからオーディオ送信を受け取るプレーヤーまたはグループ、あるいはその両方を指定する。

HRESULT SetTransmitTargets(
PDVID pdvIDTargets,
DWORD dwNumTargets,
DWORD dwFlags
);

パラメータ

pdvIDTargets
ターゲットを指定する DVID の配列へのポインタ。いずれのターゲットも指定しない場合は、このパラメータに NULL を渡す。さらに、このパラメータには次の値も設定することができる。
DVID_ALLPLAYERS
クライアントはセッションのすべてのプレーヤーをターゲットとする。配列内の唯一の要素である必要がある。
dwNumTargets
配列内の DVID の数。この値は 64 を超えてはならない。pdvIDTargets が NULL の場合、この値は 0 に設定する。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は DV_OK を返す。または、次のいずれかのエラー値を返す。

DVERR_INVALIDFLAGS
DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER
DVERR_INVALIDTARGET
DVERR_NOTINITIALIZED

注意

Microsoft® DirectX® 8.0 の場合、送信できる個々のターゲットの数は 64 までに制限されている。この値を超えると、メソッドは失敗し、DVERR_NOTALLOWED を返す。ただし、65 人以上のプレーヤーに送信することもできる。それには、プレーヤーをグループにまとめ、グループをターゲットとして使用する。

pdvIDTargets パラメータはプレーヤーまたはグループの DVID の配列を指定する。このパラメータには重複ターゲットを指定してはならない。また、エントリはすべて有効な DVID である必要がある。ターゲットが個々の DVID を持つプレーヤーおよびターゲットが所属するグループ内のプレーヤーを含む場合、Microsoft® DirectPlay® Voice はプレーヤーに重複音声パケットが送信されないようにする。

DVSESSION_SERVERCONTROLTARGET フラグを使用してセッションが作成された場合、このローカル クライアントにはサーバーしかターゲットを設定できない。このメソッドを呼び出すと、DVERR_NOTALLOWED が返される。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。


IDirectPlayVoiceServer

アプリケーションは、IDirectPlayVoiceServer インターフェイスのメソッドを使用して、音声セッションのホストを管理する。

IDirectPlayVoiceServer インターフェイスのメソッドは、次のように分類できる。

その他 | GetCaps
 | GetCompressionTypes
 | SetNotifyMask
セッション管理 | GetSessionDesc
 | GetTransmitTargets
 | Initialize
 | SetSessionDesc
 | SetTransmitTargets
 | StartSession
 | StopSession

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。


IDirectPlayVoiceServer::GetCaps

このシステムの Microsoft® DirectPlay® Voice サーバーの能力を取得する。

HRESULT GetCaps(
PDVCAPS pDVCaps
);

パラメータ

pDVCaps
DirectPlayVoiceServer オブジェクトの機能を保持する DVCAPS 構造体へのポインタ。

戻り値

成功した場合は DV_OK を返す。または、次のいずれかのエラー値を返す。

DVERR_INVALIDOBJECT
DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。


IDirectPlayVoiceServer::GetCompressionTypes

システムで利用可能な圧縮のタイプを取得する。

HRESULT GetCompressionTypes(
PVOID pData,
PDWORD pdwDataSize,
PDWORD pdwNumElements,
DWORD dwFlags
);

パラメータ

pData
DVCOMPRESSIONINFO 構造体の配列を受け取るバッファへのポインタ。この構造体は、このオブジェクトでサポートされている圧縮タイプを記述する。
pdwDataSize
pData パラメータに渡されたバッファ サイズをバイト単位で保持する DWORD へのポインタ。
pdwNumElements
メソッドが DVCOMPRESSIONINFO 構造体の配列に返された要素の数を書き込む DWORD へのポインタ。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は DV_OK を返す。または、次のいずれかのエラー値を返す。

DVERR_BUFFERTOOSMALL
DVERR_INVALIDFLAGS
DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER

注意

渡されたバッファが小さく、圧縮タイプのリストが格納できない場合、メソッドは DVERR_BUFFERTOOSMALL を返し、最低限必要なサイズが pdwDataSize パラメータに設定される。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。


IDirectPlayVoiceServer::GetSessionDesc

Microsoft® DirectPlay® Voice セッションの設定を取得する。

HRESULT GetSessionDesc(
PDVSESSIONDESC pvSessionDesc
);

パラメータ

pvSessionDesc
セッションの記述を受け取る DVSESSIONDESC 構造体へのポインタ。

戻り値

成功した場合は DV_OK を返す。または、次のいずれかのエラー値を返す。

DVERR_INVALIDOBJECT
DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER
DVERR_NOTHOSTING
DVERR_NOTINITIALIZED
DVERR_SESSIONLOST

注意

このメソッドを呼び出す前に、DVSESSIONDESC 構造体の dwSize メンバを設定する必要がある。

このメソッドを呼び出す前に、IDirectPlayVoiceServer::StartSession の呼び出しが成功している必要がある。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。


IDirectPlayVoiceServer::GetTransmitTargets

セッション内のプレーヤーに対する音声ストリームの送信ターゲットを取得する (存在する場合)。

HRESULT GetTransmitTargets(
DVID dvSource,
PDVID pdvIDTargets,
PDWORD pdwNumTargets,
DWORD dwFlags
);

パラメータ

dvSource
ターゲットに送信するユーザーまたはグループの DVID。
pdvIDTargets
IDirectPlayVoiceServer::SetTransmitTargets メソッドにより設定されたプレーヤーまたはグループの現在のターゲットを指定する DVID の配列。このパラメータに NULL を指定して、ターゲットの数を取得することができる。
pdwNumTargets
配列内の DVID の数。このメソッドを呼び出す場合、この値は IDirectPlayVoiceServer::SetTransmitTargets メソッドで設定されたターゲット数と一致する必要がある。呼び出しが成功すると、Microsoft® DirectPlay® は pdvIDTargets 配列内の要素の数を返す。

pdvIDTargets が NULL である場合、0 に設定しておく。

dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は DV_OK を返す。または、次のいずれかのエラー値を返す。

DVERR_BUFFERTOOSMALL
DVERR_INVALIDFLAGS
DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER
DVERR_NOTALLOWED
DVERR_NOTCONNECTED
DVERR_NOTINITIALIZED

注意

このメソッドは、DirectPlay Voice セッションの作成時に DVSESSION_SERVERCONTROLTARGET フラグが指定された場合にのみ使用できる。このフラグが指定されていない場合、メソッドは DVERR_NOTALLOWED を返す。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。


IDirectPlayVoiceServer::Initialize

DirectPlayVoiceServer オブジェクトを、DirectPlay オブジェクトに関連付けて初期化する。また、このメソッドはメッセージ ハンドラをこのインターフェイスに登録する。

HRESULT Initialize(
LPVOID lpVoid,
PDVMESSAGEHANDLER pMessageHandler,
PVOID pUserContext,
LPDWORD lpdwMessageMask,
DWORD dwMessageMaskElements
);

パラメータ

lpVoid
この DirectPlayVoiceServer オブジェクトが使用する DirectPlay オブジェクトに対する IUnknown インターフェイスへのポインタ。
pMessageHandler
処理する DirectPlayVoiceClient メッセージがある場合に呼び出されるユーザー定義のコールバック関数。DirectPlayVoiceClient オブジェクト内のスレッドがコールバック関数を呼び出すため、処理しているメイン スレッドのコンテキストにはコールバック関数は呼び出されない。
pUserContext
メソッドが呼び出されるたびにコールバック関数に渡される、アプリケーションにより定義された構造体へのポインタ。
lpdwMessageMask
DirectPlay Voice がユーザーのコールバック関数に送信するメッセージ識別子を保持する DWORD の配列。メッセージ識別子をこの配列に指定しない場合、メッセージは送信されない。それぞれのメッセージ識別子は一度だけ配列に表示される。有効なメッセージ識別子だけが許可される。たとえば、DVMSGID_CONNECTRESULT はサーバーのインターフェイスには無効だが、クライアントのインターフェイスに対しては有効である。すべてのメッセージを有効にするには、この値に NULL を指定する。
dwMessageMaskElements
lpdwMessageMask パラメータに指定された要素数。lpdwMessageMask が NULL である場合、0 に設定しておく。

戻り値

成功した場合は DV_OK を返す。または、次のいずれかのエラー値を返す。

DVERR_ALREADYINITIALIZED
DVERR_GENERIC
DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER
DVERR_NOCALLBACK
DVERR_TRANSPORTNOTINIT

注意

IDirectPlayVoiceServer::SetNotifyMask を呼び出して、音声セッションの進行中に通知マスクを変更することができる。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。


IDirectPlayVoiceServer::SetNotifyMask

メッセージ ハンドラに送信するメッセージを指定する。

HRESULT SetNotifyMask(
PDWORD pdwMessageMask,
DWORD dwMessageMaskElements
);

パラメータ

pdwMessageMask
Microsoft® DirectPlay® Voice がユーザーのコールバック関数に送信するメッセージ識別子を保持する DWORD の配列へのポインタ。メッセージ識別子をこの配列に指定しない場合、メッセージは送信されない。それぞれのメッセージ識別子は一度だけ配列に表示される。有効なメッセージ識別子だけが許可される。たとえば、DVMSGID_CONNECTRESULT はサーバーのインターフェイスには無効だが、クライアントのインターフェイスに対しては有効である。すべてのメッセージを有効にするには、この値に NULL を指定する。
dwMessageMaskElements
pdwMessageMask パラメータに指定された要素の数。pdwMessageMask が NULL である場合、0 に設定しておく。

戻り値

成功した場合は DV_OK を返す。または、次のいずれかのエラー値を返す。

DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER
DVERR_NOCALLBACK
DVERR_NOTINITIALIZED

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。


IDirectPlayVoiceServer::SetSessionDesc

セッション設定を設定する。

HRESULT SetSessionDesc(
PDVSESSIONDESC pSessionDesc
);

パラメータ

pSessionDesc
セッションの記述を保持する DVSESSIONDESC 構造体へのポインタ。

戻り値

成功した場合は DV_OK を返す。または、次のいずれかのエラー値を返す。

DVERR_INVALIDOBJECT
DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER
DVERR_NOTHOSTING
DVERR_NOTINITIALIZED
DVERR_SESSIONLOST

注意

Microsoft® DirectPlay® Voice セッションが開始されると、DVSESSIONDESC 構造体のセッション プロパティの一部は変更できない。詳細については、DVSESSIONDESC を参照すること。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。


IDirectPlayVoiceServer::SetTransmitTargets

クライアントからセッションの指定されたメンバへのオーディオの送信を制御する。

HRESULT SetTransmitTargets(
DVID dvSource,
PDVID pdvIDTargets,
DWORD dwNumTargets,
DWORD dwFlags
);

パラメータ

dvSource
ターゲットが設定されるユーザーの DVID。
pdvIDTargets
オーディオ送信のターゲットであるプレーヤー DVID またはグループ DVID のリスト。いずれのターゲットも指定しない場合は、このパラメータに NULL を渡す。さらに、このパラメータには次の値も設定することができる。
DVID_ALLPLAYERS
このクライアントはセッションのすべてのプレーヤーをターゲットとする。配列内の唯一の要素である必要がある。
dwNumTargets
配列内の DVID の数。この値は 64 を超えてはならない。pdvIDTargets が NULL の場合、この値は 0 に設定する。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は DV_OK を返す。または、次のいずれかのエラー値を返す。

DVERR_INVALIDFLAGS
DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER
DVERR_INVALIDTARGET
DVERR_NOTALLOWED
DVERR_NOTINITIALIZED

注意

Microsoft® DirectX® 8.0 の場合、転送できる個々のターゲットの数は、64 までに制限される。この値を超えると、メソッドは失敗し、DVERR_NOTALLOWED を返す。ただし、65 人以上のプレーヤーに転送することもできる。そのためには、プレーヤーをグループにまとめ、グループをターゲットとして使用する。

このパラメータには重複ターゲットを指定してはならない。また、エントリはすべて有効な DVID である必要がある。ターゲットが個々の DVID を持つプレーヤーおよびターゲットが所属するグループ内のプレーヤーを含む場合、Microsoft® DirectPlay® Voice はプレーヤーに重複音声パケットが送信されないようにする。

このメソッドは、DirectPlay Voice セッションの作成時に DVSESSION_SERVERCONTROLTARGET フラグが指定された場合にのみ使用できる。このフラグが指定されていない場合、メソッドは DVERR_NOTALLOWED を返す。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。


IDirectPlayVoiceServer::StartSession

実行中の DirectPlay トランスポート セッション内で、初期化済みの Microsoft® DirectPlay® Voice セッションを開始する。このメソッドの呼び出しが成功しないと、クライアントは音声セッションへの接続を完了できない。

HRESULT StartSession(
PDVSESSIONDESC pSessionDesc,
DWORD dwFlags
);

パラメータ

pSessionDesc
セッションの記述を保持する DVSESSIONDESC 構造体へのポインタ。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は DV_OK を返す。または、次のいずれかのエラー値を返す。

DVERR_ALREADYPENDING
DVERR_HOSTING
DVERR_INVALIDFLAGS
DVERR_INVALIDOBJECT
DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER
DVERR_NOTINITIALIZED

注意

このメソッドを呼び出す前に IDirectPlayVoiceServer::Initialize メソッドを呼び出す必要がある。音声セッションがピアツーピアである場合、音声セッションはセッションの任意のクライアントにホストできる。音声セッションがピアツーピアではない場合、アクティブなトランスポート セッションのホストであるトランスポート クライアントでホストする必要がある。

DVSESSIONDESC 構造体は開始する音声セッションのタイプを保持する。音声セッションのタイプによっては、クライアントとサーバーの CPU と帯域幅の使用について、大きな影響を与えることがある。DVSESSIONDESC の guidCT メンバを DPVCTGUID_DEFAULT に設定できる。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。


IDirectPlayVoiceServer::StopSession

Microsoft® DirectPlay® Voice セッションを停止する。

HRESULT StopSession(
DWORD dwFlags
);

パラメータ

dwFlags
フラグ。次のフラグを設定できる。
DVFLAGS_NOHOSTMIGRATE
セッションとトランスポートの設定に関係なく、ホストは移行しない。音声セッションを完全にシャット ダウンする場合は、このフラグを使用する。

戻り値

成功した場合は DV_OK を返す。または、次のいずれかのエラー値を返す。

DVERR_ALREADYPENDING
DVERR_INVALIDFLAGS
DVERR_INVALIDOBJECT
DVERR_INVALIDPARAM
DVERR_NOTHOSTING
DVERR_NOTINITIALIZED
DVERR_SESSIONLOST

注意

別のスレッドで StopSession 要求が処理されている間にこのメソッドが呼び出された場合、DVERR_ALREADYPENDING エラー値が返される。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。


IDirectPlayVoiceTest

アプリケーションは、IDirectPlayVoiceTest インターフェイスの CheckAudioSetup メソッドを使用して、Microsoft® DirectPlay® Voice のオーディオ構成をテストする。

オーディオ構成 CheckAudioSetup

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。


IDirectPlayVoiceTest::CheckAudioSetup

指定されたデバイスに対してオーディオ セットアップ ウィザードを実行する。このウィザードは、デバイスにいくつかのテストを行い、全二重オーディオを利用できるかどうかを確認する。また、マイクが接続されており、キャプチャ デバイスで正しく動作するかどうかを確認する。

HRESULT CheckAudioSetup(
const GUID * pguidPlaybackDevice,
const GUID * pguidCaptureDevice,
HWND hwndParent,
DWORD dwFlags
);

パラメータ

pguidPlaybackDevice
テストする再生デバイスを識別する GUID へのポインタ。このパラメータに NULL を渡した場合、Microsoft® DirectPlay® Voice は Microsoft® DirectSound® に定義されているシステムのデフォルト音声再生デバイスをテストする。DirectSound のデフォルト GUID の 1 つを渡すこともできる。
DSDEVID_DefaultPlayback
システムのデフォルト再生デバイス。
DSDEVID_DefaultVoicePlayback
デフォルト音声再生デバイス。
pguidCaptureDevice
テストするキャプチャ デバイスを識別する GUID へのポインタ。このパラメータに NULL を渡した場合、DirectPlay Voice は DirectSound に定義されているシステムのデフォルトの音声キャプチャ デバイスをテストする。DirectSound のデフォルト GUID の 1 つを渡すこともできる。
DSDEVID_DefaultCapture
デフォルトのシステム キャプチャ デバイス。また、デバイスの GUID パラメータに NULL ポインタを渡して、このデバイスを指定することもできる。
DSDEVID_DefaultVoiceCapture
デフォルトの通信キャプチャ デバイス。一般的に、これは マイク付きの USB ヘッドセットなどのセカンダリ デバイスである。
hwndParent
このメソッドにより呼び出されるテスト ウィザードはモーダルである。ウィザードの親ウィンドウになるウィンドウが呼び出し元のアプリケーションにある場合、そのウィンドウへのハンドルをこのパラメータで渡す必要がある。呼び出し元アプリケーションにウィンドウがない場合、NULL を渡すことができる。DVFLAGS_QUERYONLY フラグを指定した場合、このパラメータは使用されず、アプリケーションは NULL を渡すことができる。
dwFlags
フラグ。次のフラグを設定できる。
DVFLAGS_QUERYONLY
オーディオ セットアップは実行されない。その代わり、メソッドはレジストリを調べ、デバイスがテスト済みかどうかをチェックする。デバイスがテストされていない場合、メソッドは DVERR_RUNSETUP を返す。デバイスがテストされている場合、デバイスが全二重オーディオをサポートしていれば、メソッドは DV_FULLDUPLEX を返し、デバイスが全二重オーディオをサポートしていなければ、メソッドは DV_HALFDUPLEX を返す。
DVFLAGS_ALLOWBACK
このフラグを渡すと、ウィザードのウェルカム ページで [Back] ボタンが有効になる。ユーザーがウェルカム ページの [Back] ボタンをクリックすると、ウィザードは終了し、CheckAudioSetup は DVERR_USERBACK を返す。

戻り値

成功した場合は DP_OK、DV_FULLDUPLEX、または DV_HALFDUPLEX を返し、失敗した場合は次のいずれかのエラー値を返す。

DVERR_INVALIDPARAM
DVERR_RUNSETUP
DVERR_INVALIDDEVICE

注意

このメソッドはユーザー インターフェイス (UI) の要素を保持し、ダイアログ ボックスを表示する。DVFLAGS_QUERYONLY フラグを指定すると、テストは実際には実行されず、UI は起動しない。その代わり、レジストリを調べ、デバイスの以前のテスト結果を確認する。

ユーザーがウィザードを取り消すと、CheckAudioSetup は DVERR_USERCANCEL を返す。その後、呼び出し元アプリケーションは状況に応じて対処できる。たとえば、ゲーム オプション コントロール パネル アプリケーションの DirectPlay Voice 部分で、ユーザーが [Cancel] をクリックした場合、ウィザードが取り消されたため音声を使用できないことを示すメッセージをダイアログ ボックスに表示する。

指定されたデバイスが存在しない場合、このメソッドは DVERR_INVALIDDEVICE を返す。また、デフォルトのデバイスを指定してもこのメソッドがこのエラーを返す場合は、システムにサウンド デバイスがない。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。


IDirectPlay8LobbyClient

IDirectPlay8LobbyClient インターフェイスは、ロビー クライアント アプリケーションで使用し、ローカル コンピュータでロビー対応ゲーム アプリケーションの列挙と起動を行う。また、実行中のゲーム アプリケーションとの通信にも使用する。ロビー クライアントは、ロビーおよびロビーされるゲーム アプリケーションからのメッセージを処理するため、メッセージ ハンドラ ルーチンを登録する必要がある。

IDirectPlay8LobbyClient インターフェイスには、次のメソッドがある。

IDirectPlay8LobbyClient メソッド | Close
 | ConnectApplication
 | EnumLocalPrograms
 | Initialize
 | ReleaseApplication
 | Send
 | GetConnectionSettings
 | SetConnectionSettings

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplobby8.h で宣言。


IDirectPlay8LobbyClient::Close

ロビー クライアントを削除する。

HRESULT Close(
const DWORD dwFlags
);

パラメータ

dwFlags
将来の使用に備えて予約されているので、0 に設定しておく。

戻り値

成功した場合は S_OK を返す。それ以外の場合は、次のエラー値を返す。

DPNERR_UNINITIALIZED

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplobby8.h で宣言。


IDirectPlay8LobbyClient::ConnectApplication

ロビー対応アプリケーションを、DPL_CONNECT_INFO 構造体に指定されているセッションに接続する。アプリケーションが実行されていない場合、このメソッドを使用してアプリケーションを起動できる。

接続が成功すると、ロビー アプリケーションはメッセージ ハンドラに DPL_MSGID_CONNECT システム メッセージを生成する。

HRESULT ConnectApplication(
DPL_CONNECT_INFO *const pdplConnectionInfo,
const PVOID pvUserApplicationContext,
DPNHANDLE *const phApplication,
const DWORD dwTimeOut,
const DWORD dwFlags
);

パラメータ

pdplConnectionInfo
DPL_CONNECT_INFO 構造体へのポインタ。この構造体は接続先アプリケーションの GUID を含む、接続パラメータを記述する。
pvUserApplicationContext
ロビー クライアント用に定義されたコンテキスト値へのポインタ。この値は、ロビー クライアントのメッセージ ハンドラへの呼び出しで渡される。
phApplication
このメソッドが成功した場合に設定されるアプリケーション コンテキスト ハンドルを指定する DPNHANDLE へのポインタ。このハンドルは、アプリケーションとの通信に使用される。また、このハンドルは IDirectPlay8LobbyClient::ReleaseApplication メソッドの phApplication パラメータでも使用される。
dwTimeOut
接続の処理を待つ時間 (ミリ秒単位) を指定する DWORD 型の変数。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_CANTLAUNCHAPPLICATION
DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM
DPNERR_TIMEDOUT

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplobby8.h で宣言。


IDirectPlay8LobbyClient::EnumLocalPrograms

システムに登録されているロビー アプリケーションを列挙する。

HRESULT EnumLocalPrograms(
GUID *const pGuidApplication,
BYTE *const pEnumData,
DWORD *const pdwEnumData,
DWORD *const pdwItems.
const DWORD dwFlags
);

パラメータ

pGuidApplication
列挙するロビー アプリケーションを指定する GUID 型の変数へのポインタ。このパラメータはオプションである。NULL を渡すと、利用可能なすべてのロビー アプリケーションが列挙される。
pEnumData
ロビー アプリケーションの記述を格納する BYTE 型の変数へのポインタ。
pdwEnumData
pEnumData バッファに保持されるバイト数を指定する DWORD 型の変数へのポインタ。pEnumData のバッファが小さすぎる場合、このメソッドは DPNERR_BUFFERTOOSMALL を返し、必要なバッファのサイズをこのパラメータに設定する。
pdwItems
pEnumData バッファの DPL_APPLICATION_INFO 構造体の数を保持する DWORD 型の変数へのポインタ。メソッドが成功した場合にのみ、このパラメータに値が格納される。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM

注意

通常、このメソッドは 2 回呼び出される。1 回目は、必要なバッファのサイズを取得するために呼び出される。2 回目は、正しいバッファ サイズを使用して呼び出される。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplobby8.h で宣言。


IDirectPlay8LobbyClient::Initialize

起動されたアプリケーションの状態変更に関する通知を受け取るロビー クライアントのコード内のエントリ ポイントを登録する。また、メッセージ ハンドラはロビー アプリケーションからメッセージを受け取る。このメソッドを呼び出してから、このインターフェイスのその他のメソッドを呼び出す必要がある。

HRESULT Initialize(
const PVOID pvUserContext,
const PFNDPNMESSAGEHANDLER pfn,
const DWORD dwFlags
);

パラメータ

pvUserContext
メッセージ ハンドラの呼び出しで指定される、ユーザー指定のコンテキスト値へのポインタ。ユーザー指定のコンテキスト値は、複数のインターフェイスから共通のメッセージ ハンドラに送信されたメッセージを区別するのに役立つ。
pfn
IDirectPlay8LobbyClient インターフェイスからすべてのメッセージ、および IDirectPlay8LobbiedApplication インターフェイスからセッション変更の通知を取得する PFNDPNMESSAGEHANDLER コールバック関数へのポインタ。
dwFlags
次のフラグを指定できる。
DPLINITIALIZE_DISABLEPARAMVAL
パラメータ妥当性の検証を無効にする。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM

注意

IDirectPlay8LobbyClient インターフェイスを取得するには、CoCreateInstance を使用した後にこのメソッドを呼び出す。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplobby8.h で宣言。


IDirectPlay8LobbyClient::ReleaseApplication

ロビー アプリケーションを解放し、ロビー クライアントとアプリケーションの接続を終了する。ロビー クライアントがアプリケーションとのセッションを終了するごとに、このメソッドを呼び出す必要がある。

HRESULT ReleaseApplication(
const DPNHANDLE hApplication.
const DWORD dwFlags
);

パラメータ

hApplication
解放するロビー アプリケーションの DPNHANDLE。この値は、IDirectPlay8LobbyClient::ConnectApplication メソッドの phApplication パラメータに設定される。次のフラグも指定できる。
DPLHANDLE_ALLAPPLICATIONS
すべてのアプリケーション接続を解放する。
dwFlags
将来の使用に備えて予約されているので、0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDFLAGS
DPNERR_INVALIDHANDLE
DPNERR_INVALIDPARAM

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplobby8.h で宣言。


IDirectPlay8LobbyClient::Send

このロビー クライアントによって起動または接続されたロビー アプリケーションにメッセージを送信する。

このメソッドは、ターゲットのメッセージ ハンドラに DPL_MSGID_RECEIVE システム メッセージを送信する。

HRESULT Send(
const DPNHANDLE hConnection,
BYTE *const pBuffer,
const DWORD pBufferSize,
const DWORD dwFlags
);

パラメータ

hConnection
メッセージ送信のターゲットを指定する DPNHANDLE 型の変数。次のフラグも指定できる。
DPLHANDLE_ALLAPPLICATIONS
指定したメッセージが、ロビー クライアント アプリケーションに接続されているすべてのロビー アプリケーションに送信される。
pBuffer
メッセージを保持するバイトの配列へのポインタ。
pBufferSize
pBuffer パラメータにメッセージ バッファのサイズ (バイト単位) を指定する DWORD 型の変数。このパラメータは 1 バイト以上、64 KB 以下でなければならない。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDFLAGS
DPNERR_INVALIDHANDLE
DPNERR_INVALIDPARAM
DPNERR_SENDTOOLARGE

注意

バッファ サイズが 64 KB より大きい場合、メソッドは DPNERR_SENDTOOLARGE を返す。バッファ サイズが 0 に設定されている場合、メソッドは DPNERR_INVALIDPARAM を返す。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplobby8.h で宣言。


IDirectPlay8LobbyClient::GetConnectionSettings

指定された接続の接続設定セットを取得する。これらの設定は、IDirectPlay8LobbyClient::ConnectApplication、IDirectPlay8LobbyClient::SetConnectionSettings または IDirectPlay8LobbiedApplication::SetConnectionSettings メソッドを呼び出して設定できる。

接続設定を取得すると、ユーザーに返される各アドレス オブジェクトに参照が追加される。したがって、構造体の処理が終了したら、ユーザーは各アドレス オブジェクトに対して Release を呼び出す必要がある。

HRESULT GetConnectionSettings(
const DPNHANDLE hConnection,
DPL_CONNECTION_SETTINGS *const pdplConnectSettings,
DWORD*pdwDataSize,
const DWORD dwFlags
);

パラメータ

hConnection
設定を取得する接続のハンドル。
pdplConnectSettings
指定された接続の接続設定を受け取るバッファへのポインタ。
pdwDataSize
pdplConnectSettings 構造体に指定されたバッファのサイズ (バイト単位) を保持する DWORD へのポインタ。バッファが接続設定を保持できるだけの大きさではない場合、DPNERR_BUFFERTOOSMALL が返され、この値には必要なバッファ サイズが設定される。成功した場合、この値は、指定されたバッファに書き込まれたバイト数を保持する。
dwFlags
将来の使用に備えて予約されているので、0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDPARAM
DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDOBJECT
DPNERR_INVALIDFLAGS

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplobby8.h で宣言。


IDirectPlay8LobbyClient::SetConnectionSettings

指定された接続に関連付ける接続設定を設定する。このメソッドを呼び出すと、hConnection で指定したクライアントに送信する DPL_MSGID_CONNECTION_SETTINGS メッセージが生成される。

接続設定を設定すると、呼び出しに指定した各アドレス オブジェクトにロビー アプリケーションが参照を追加する。

HRESULT SetConnectionSettings(
const DPNHANDLE hConnection,
const DPL_CONNECTION_SETTINGS *const pdplConnectSettings,
const DWORD dwFlags
);

パラメータ

hConnection
設定を設定する接続のハンドル。次のフラグも指定できる。
DPLHANDLE_ALLAPPLICATIONS
接続設定が、接続しているすべてのロビー アプリケーションに対して更新される。
pdplConnectSettings
指定された接続に関連付けられた設定を保持する DPL_CONNECTION_SETTINGS 構造体へのポインタ。
dwFlags
将来の使用に備えて予約されているので、0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDPARAM
DPNERR_INVALIDOBJECT
DPNERR_INVALIDFLAGS

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplobby8.h で宣言。


IDirectPlay8LobbiedApplication

IDirectPlay8LobbiedApplication インターフェイスは、ロビーをサポートするアプリケーションで使用する。このインターフェイスを使用すると、アプリケーションがロビーで起動できるように、システムに登録できる。また、アプリケーションは、ユーザーを照会せずに、ゲームの起動に必要な接続情報を取得できる。最後に、ロビー アプリケーションはこのインターフェイスを使用して、アプリケーションを起動したロビー クライアントにメッセージと通知を送信できる。

IDirectPlay8LobbiedApplication インターフェイスには、次のメソッドがある。

IDirectPlay8LobbiedApplication メソッド | Close
 | SetAppAvailable
 | Initialize
 | RegisterProgram
 | Send
 | UnRegisterProgram
 | UpdateStatus
 | GetConnectionSettings
 | SetConnectionSettings

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplobby8.h で宣言。


IDirectPlay8LobbiedApplication::Close

ロビー アプリケーションを削除する。

HRESULT Close(
const DWORD dwFlags
);

パラメータ

dwFlags
将来の使用に備えて予約されているので、0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_UNINITIALIZED
DPNERR_INVALIDOBJECT
DPNERR_OUTOFMEMORY

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplobby8.h で宣言。


IDirectPlay8LobbiedApplication::SetAppAvailable

ロビー クライアントが接続するアプリケーションを利用できるようにしたり、利用できないようにする。通常、ロビー アプリケーションがロビー クライアントにより起動したのではなく、独立して起動した場合、このメソッドが呼び出される。また、ゲームが終了し、ほかのゲームの開始時にロビー クライアントに接続するため、ロビー アプリケーションが必要な場合も、このメソッドを呼び出す。

HRESULT SetAppAvailable(
const BOOL fAvailable,
const DWORD dwFlags
);

パラメータ

fAvailable
アプリケーションが利用できるかどうかを設定するブール値。アプリケーションが利用できることを示す場合は、この値に TRUE を設定し、利用できないことを示すには FALSE を設定する。
dwFlags
このメソッドには、次のフラグを設定できる。
DPLAVAILABLE_ALLOWMULTIPLECONNECT
このメソッドのデフォルトの動作では、最初の接続が確立された時点で、自動的にインターフェイスを利用不可とマークする。このフラグを指定すると、最初の接続の確立後にインターフェイスが自動的に利用不可とマークされることがないため、複数の接続が可能である。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDOBJECT
DPNERR_UNINITIALIZED

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplobby8.h で宣言。


IDirectPlay8LobbiedApplication::Initialize

ロビー クライアントの状態の変更に関する通知およびロビー クライアントからのメッセージを受け取るメッセージ ハンドラ関数を登録する。

HRESULT Initialize(
const PVOID pvUserContext,
const PFNDPNMESSAGEHANDLER pfn,
DPNHANDLE *const pdpnhConnection,
const DWORD dwFlags
);

パラメータ

pvUserContext
メッセージ ハンドラの呼び出しで指定される、ユーザー指定のコンテキスト値。ユーザー指定のコンテキスト値は、複数のインターフェイスから共通のメッセージ ハンドラに送信されたメッセージを区別するのに役立つ。
pfn
IDirectPlay8LobbyClient インターフェイスからすべてのメッセージ、および IDirectPlay8LobbiedApplication インターフェイスからセッション変更の通知を取得する PFNDPNMESSAGEHANDLER コールバック関数へのポインタ。
pdpnhConnection
アプリケーションがロビーで起動されたかどうかを検出するために使用する値。アプリケーションがロビーで起動されている場合、このパラメータにはロビー クライアントの接続ハンドルが設定される。プロセスがロビーで起動されていない場合、このパラメータは NULL に設定される。
dwFlags
次のフラグを指定できる。
DPLINITIALIZE_DISABLEPARAMVAL
パラメータ妥当性の検証を無効にする。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM

注意

IDirectPlay8LobbiedApplication インターフェイスを取得するには、CoCreateInstance を使用した後にこのメソッドを呼び出す。

ロビーで起動した場合、このメソッドはロビー クライアントとの接続を自動的に確立する。Initialize を呼び出し、ロビーで起動されているのに、ロビー アプリケーション インターフェイスがロビー クライアント プロセスと通信できない場合、Initialize は 4 秒後にタイムアウトする。この場合、Initialize は DPNERR_TIMEDOUT を返すが、成功である。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplobby8.h で宣言。


IDirectPlay8LobbiedApplication::RegisterProgram

ロビー アウェア アプリケーションを DirectPlay に登録する。ロビーによる起動を可能にするには、アプリケーションを登録する必要がある。

HRESULT RegisterProgram(
PDPL_PROGRAM_DESC pdplProgramDesc,
const DWORD dwFlags
);

パラメータ

pdplProgramDesc
登録するロビー対応アプリケーションを記述する DPL_PROGRAM_DESC 構造体へのポインタ。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM

注意

アプリケーションの登録は一度だけ行う必要がある。アプリケーションをアンインストールするとき、IDirectPlay8LobbiedApplication::UnRegisterProgram メソッドを呼び出して登録を解除する必要がある。

Microsoft DirectX® 8.0 では、RegisterProgram を使用する必要がある。アプリケーション情報をレジストリに手動で設定することはできない。このインターフェイスを使用しないと、アプリケーションは移植できず、DirectPlay の将来のバージョンと互換性がなくなる。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplobby8.h で宣言。


IDirectPlay8LobbiedApplication::Send

ロビー アプリケーションからロビー クライアントにメッセージを送信する。

HRESULT Send(
const DPNHANDLE hConnection,
BYTE *const pBuffer,
const DWORD pBufferSize,
const DWORD dwFlags
);

パラメータ

hConnection
メッセージの送信先ロビー クライアントを指定する DPNHANDLE 型の変数。次のフラグも指定できる。
DPLHANDLE_ALLAPPLICATIONS
指定したメッセージが、接続しているすべてのロビー クライアントに送信される。
pBuffer
メッセージ バッファを保持する BYTE 型の変数へのポインタ。
pBufferSize
pBuffer パラメータにメッセージ バッファのサイズ (バイト単位) を指定する DWORD 型の変数。このパラメータは 1 バイト以上、64 KB 以下でなければならない。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDFLAGS
DPNERR_INVALIDHANDLE
DPNERR_INVALIDPARAM
DPNERR_SENDTOOLARGE

注意

バッファ サイスが 64 KB より大きい場合、メソッドは DPNERR_SENDTOOLARGE を返す。バッファ サイズが 0 に設定されている場合、メソッドは DPNERR_INVALIDPARAM を返す。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplobby8.h で宣言。


IDirectPlay8LobbiedApplication::UnRegisterProgram

IDirectPlay8LobbiedApplication::RegisterProgram メソッドにより登録されたロビー アウェア アプリケーションの登録を解除する。

HRESULT UnRegisterProgram(
GUID* pguidApplication,
const DWORD dwFlags

);

パラメータ

pguidApplication
登録を解除するアプリケーションの GUID へのポインタ。
dwFlags
予約済み。0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplobby8.h で宣言。


IDirectPlay8LobbiedApplication::UpdateStatus

接続されているロビー クライアントの状態を更新する。

HRESULT UpdateStatus(
const DPNHANDLE hConnection,
const DWORD dwStatus,
const DWORD dwFlags
);

パラメータ

hConnection
ロビー クライアントを指定する DPNHANDLE 型の変数。次のフラグも指定できる。
DPLHANDLE_ALLAPPLICATIONS
接続されているすべてのロビー クライアントに状態の更新が送信される。
dwStatus
ロビー クライアントとロビー アプリケーション間の状態を示す次のフラグのいずれかが格納される DWORD 型の変数。
DPLSESSION_CONNECTED
ロビー クライアントとロビー アプリケーションは現在接続されている。
DPLSESSION_COULDNOTCONNECT
ロビー クライアントはロビー アプリケーションに接続できなかった。
DPLSESSION_DISCONNECTED
ロビー クライアントとロビー アプリケーションは現在接続解除されている。
DPLSESSION_TERMINATED
ロビー クライアントとロビー アプリケーションの間の接続は終了した。
DPLSESSION_HOSTMIGRATED
接続に関連付けられたピア オブジェクトは、ホストの移行が行われるセッションに関与する。ローカル クライアントは新規ホストではない。
DPLSESSION_HOSTMIGRATEDHERE
接続に関連付けられたピア オブジェクトは、ホストの移行が行われるセッションに関与する。ローカル クライアントが新規ホストになる。
dwFlags
将来の使用に備えて予約されているので、0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDHANDLE
DPNERR_INVALIDPARAM

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplobby8.h で宣言。


IDirectPlay8LobbiedApplication::GetConnectionSettings

指定された接続の接続設定セットを取得する。これらの設定は、IDirectPlay8LobbyClient::ConnectApplication、IDirectPlay8LobbyClient::SetConnectionSettings、または IDirectPlay8LobbiedApplication::SetConnectionSettings の各メソッドの呼び出しによって設定できる。

接続設定を取得すると、ユーザーに返される各アドレス オブジェクトに参照が追加される。したがって、構造体の処理が終了したら、ユーザーは各アドレス オブジェクトに対して Release を呼び出す必要がある。

HRESULT GetConnectionSettings(
const DPNHANDLE hLobbyClient,
DPL_CONNECTION_SETTINGS *const pdplSessionInfo,
DWORD* pdwInfoSize,
const DWORD dwFlags
);

パラメータ

hLobbyClient
設定を取得する接続のハンドル。
pdplSessionInfo
指定した接続の接続設定を受け取る DPL_CONNECTION_SETTINGS 構造体へのポインタ。
pdwInfoSize
pdplSessionInfo 構造体に指定されたバッファのサイズ (バイト単位) を保持する DWORD へのポインタ。バッファが接続設定を保持できるだけの大きさではない場合、DPNERR_BUFFERTOOSMALL が返される。この値には必要なバッファ サイズが設定される。成功した場合、指定されたバッファに書き込まれたバイト数がこの値に入る。
dwFlags
将来の使用に備えて予約されているので、0 に設定しておく。

戻り値

成功した場合は S_OK を返す。それ以外の場合は、次のエラー値を返す。

DPNERR_INVALIDPARAM
DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDOBJECT
DPNERR_INVALIDFLAGS

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplobby8.h で宣言。


IDirectPlay8LobbiedApplication::SetConnectionSettings

指定された接続に関連付ける接続設定を設定する。このメソッドを呼び出すと、hConnection で指定したクライアントに送信する DPL_MSGID_CONNECTION_SETTINGS が生成される。

接続設定を設定すると、呼び出しに指定した各アドレス オブジェクトにロビー アプリケーションが参照を追加する。

HRESULT SetConnectionSettings(
const DPNHANDLE hConnection,
const DPL_CONNECTION_SETTINGS *const pdplConnectSettings,
const DWORD dwFlags
);

パラメータ

hConnection
設定を設定する接続のハンドル。次のフラグも指定できる。
DPLHANDLE_ALLAPPLICATIONS
接続設定が、接続されているすべてのロビー クライアントに対して更新される。
pdplConnectSettings
指定された接続に関連付けられた設定を保持する DPL_CONNECTION_SETTINGS 構造体へのポインタ。
dwFlags
将来の使用に備えて予約されているので、0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDPARAM
DPNERR_INVALIDOBJECT
DPNERR_INVALIDFLAGS

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplobby8.h で宣言。


IDirectPlay8Address

IDirectPlay8Address インターフェイスは、Microsoft® DirectPlay® のアドレスの作成と操作に使用する汎用的なアドレス設定メソッドを備えている。このインターフェイスは、CLSID_DirectPlayAddress COM オブジェクトにより利用できるインターフェイスの 1 つである。このインターフェイスをサポートするオブジェクトを作成するには、IID_IDirectPlayAddress8 インターフェイスを指定する CLSID CLSID_DirectPlayAddress の CoCreateInstanceEx メソッドを使用する。

IDirectPlay8Address インターフェイスには、次のメソッドがある。

IDirectPlay8Address メソッド | BuildFromURLW
 | BuildFromURLA
 | Duplicate
 | SetEqual
 | IsEqual
 | Clear
 | GetURLW
 | GetURLA
 | GetSP
 | GetUserData
 | SetSP
 | SetUserData
 | GetNumComponents
 | GetComponentByName
 | GetComponentByIndex
 | AddComponent
 | GetDevice
 | SetDevice
 | BuildFromDPADDRESS

注意

メッセージを配信するには、マルチプレーヤー ゲームの各参加者が一意のアドレスを持っている必要がある。アドレスは、アプリケーションを実行しているコンピュータを参照するか (デバイス アドレス)、アプリケーションが通信する必要のあるコンピュータを参照できる (ホスト アドレス)。

DirectPlay はアドレスを URL として表す。URL は、DirectPlay API との受け渡しができるように、アドレス オブジェクトにカプセル化される。一般に、アドレス URL は、次の順序に従う 3 つの基本要素で構成される文字列である。スキーム、スキーム セパレータ、およびデータ文字列。

すべての DirectPlay アドレスは "x-directplay" をスキームとして使用し、":/" をスキーム セパレータとして使用する。セパレータとして ":/" を使用すると、後に続くデータが不透明であることを示す。言い換えると、データ文字列はどのインターネット標準にも適合しておらず、通知なしで受け取り側アプリケーションに渡す必要がある。したがって、DirectPlay のすべての URL は次の形式になる。

x-directplay:/[data string]

アドレス オブジェクトを処理するには、2 つの基本的な方法がある。

  • 通常の文字列操作方法を使用して、データ文字列を直接処理する。
  • データ文字列の個別の要素を取得または修正するには、IDirectPlay8Address で公開されるメソッドを使用する。

DirectPlay アドレスの詳細については、「DirectPlay アドレシング」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dpaddr.h で宣言。


IDirectPlay8Address::BuildFromURLW

オブジェクトを、DirectPlay 8 URL のアドレスに等しく設定する。また、オブジェクトの内容を消去する。

HRESULT BuildFromURLW(
WCHAR* pwszSourceURL
);

パラメータ

pwszSourceURL
正しくフォーマットされた DirectPlay 8 アドレスを保持する NULL で終わる Unicode 文字列へのポインタ。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDPOINTER
DPNERR_INVALIDURL
DPNERR_NOTALLOWED

注意

Dpaddr.h ヘッダー ファイルは、リテラル文字列の代わりに、URL の作成に使用できる標準文字列の数を定義する。文字列名はすべて、DPNA_XXX という形式をとる。たとえば、URL ヘッダーを L"x-directplay:/" とする代わりに、DPNA_HEADER を使用できる。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dpaddr.h で宣言。


IDirectPlay8Address::BuildFromURLA

オブジェクトを DirectPlay 8 URL に指定されているオブジェクトに等しく設定する。また、オブジェクトの内容を消去する。

HRESULT BuildFromURLA(
CHAR* pszSourceURL
);

パラメータ

pszSourceURL
正しくフォーマットされた DirectPlay 8 アドレスを保持する NULL で終わる ANSI 文字列 へのポインタ。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDPOINTER
DPNERR_INVALIDURL
DPNERR_NOTALLOWED

注意

Dpaddr.h ヘッダー ファイルは、リテラル文字列の代わりに、URL の作成に使用できる標準文字列の数を定義する。文字列名はすべて、DPNA_XXX という形式をとる。たとえば、URL ヘッダーを L"x-directplay:/" とする代わりに、DPNA_HEADER を使用できる。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dpaddr.h で宣言。


IDirectPlay8Address::Duplicate

このオブジェクトのアドレスを複製する DirectPlay Address オブジェクトを作成する。

HRESULT Duplicate(
PDIRECTPLAY8ADDRESS* ppdpaNewAddress
);

パラメータ

ppdpaNewAddress
複製オブジェクトの IDirectPlay8Address ポインタを受け取るポインタのアドレス。DirectPlay は、このインターフェイスに対する参照カウントをインクリメントする。インターフェイスが不要になったら、解放する必要がある。

戻り値

成功した場合は S_OK を返す。それ以外の場合は、次のエラー値を返す。

DPNERR_GENERIC

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dpaddr.h で宣言。


IDirectPlay8Address::SetEqual

呼び出されるオブジェクトの内容をメソッドに渡されるアドレス オブジェクトの内容に一致するように設定する。

HRESULT SetEqual(
PDIRECTPLAY8ADDRESS pdpaAddress
);

パラメータ

pdpaAddress
このオブジェクトが設定される DirectPlay8Address オブジェクトへのポインタ。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDADDRESSFORMAT
DPNERR_INVALIDOBJECT
DPNERR_INVALIDPOINTER

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dpaddr.h で宣言。


IDirectPlay8Address::IsEqual

2 つのアドレスが等しいか比較する。

HRESULT IsEqual(
PDIRECTPLAY8ADDRESS pdpaAddress
);

パラメータ

pdpaAddress
オブジェクト内に含まれるアドレスと比較するアドレス。

戻り値

成功した場合は、次のいずれかの値を返す。

DPNSUCCESS_EQUAL
2 つのアドレスは等しい。
DPNSUCCESS_NOTEQUAL
2 つのアドレスは等しくない。

失敗した場合は、次のいずれかのエラー値を返す。

DPNERR_INVALIDADDRESSFORMAT
DPNERR_INVALIDOBJECT
DPNERR_INVALIDPOINTER

注意

このメソッドは、pdpaAddress パラメータで指定されたアドレスの内容を確認し、このメソッドが呼び出されたオブジェクト内に含まれるアドレスと比較する。このメソッドは、いずれのアドレスの内容にも影響を与えない。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dpaddr.h で宣言。


IDirectPlay8Address::Clear

アドレス オブジェクトを空のアドレスにリセットする。

HRESULT Clear();

戻り値

成功した場合は S_OK を返す。それ以外の場合は、次のエラー値を返す。

DPNERR_NOTALLOWED

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dpaddr.h で宣言。


IDirectPlay8Address::GetURLW

このオブジェクトによって示される DirectPlay 8 アドレスの URL 文字列を取得する。

HRESULT GetURLW(
WCHAR* pwszURL,
PDWORD pdwNumChars
);

パラメータ

pwszURL
このオブジェクトが表す URL を受け取るポインタのアドレス。pdwNumChars が 0 を保持する DWORD を示す場合、このパラメータに NULL を指定できる。
pdwNumChars
指定したバッファが保持できる文字数 (NULL ターミネータを含む) を保持する DWORD へのポインタ。成功の場合、この値には指定したバッファに書き込まれた文字数 (NULL ターミネータを含む) が保持される。失敗の場合、この値には URL の保持に必要な文字数 (NULL ターミネータを含む) が保持され、メソッドは DPNERR_BUFFERTOOSMALL を返す。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_BUFFERTOOSMALL
DPNERR_GENERIC
DPNERR_INVALIDURL
DPNERR_OUTOFMEMORY

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dpaddr.h で宣言。


IDirectPlay8Address::GetURLA

オブジェクトによって示される Microsoft® DirectPlay® アドレスの URL 文字列を取得する。(ANSI バージョン)

HRESULT GetURLA(
CHAR* pszURL,
PDWORD pdwNumChars
);

パラメータ

pszURL
このオブジェクトが表す URL を受け取るポインタのアドレス。pdwNumChars が 0 を保持する DWORD を示す場合、このパラメータに NULL を指定できる。
pdwNumChars
指定したバッファが保持できる文字数 (NULL ターミネータを含む) を保持する DWORD へのポインタ。成功の場合、この値には指定したバッファに書き込まれた文字数 (NULL ターミネータを含む) が保持される。失敗の場合、この値には URL の保持に必要な文字数 (NULL ターミネータを含む) が保持され、メソッドは DPNERR_BUFFERTOOSMALL を返す。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_BUFFERTOOSMALL
DPNERR_GENERIC
DPNERR_INVALIDURL
DPNERR_OUTOFMEMORY

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dpaddr.h で宣言。


IDirectPlay8Address::GetSP

アドレス オブジェクトのサービス プロバイダ GUID を取得する。サービス プロバイダが指定されていない場合、このメソッドは DPNERR_DOESNOTEXIST を返す。

HRESULT GetSP(
GUID* pguidSP
);

パラメータ

pguidSP
アドレス オブジェクトのサービス プロバイダを受け取る GUID へのポインタ。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_DOESNOTEXIST
DPNERR_INVALIDPOINTER

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dpaddr.h で宣言。


IDirectPlay8Address::GetUserData

アドレス オブジェクトのユーザー データを取得する。このアドレス オブジェクトにユーザー データが存在しない場合、このメソッドは DPNERR_DOESNOTEXIST を返す。

HRESULT GetUserData(
void* pvUserData,
PDWORD pdwBufferSize
);

パラメータ

pvUserData
このアドレスからユーザー データを受け取るバッファへのポインタ。必要なサイズを取得するには、このパラメータに NULL を設定し、pdwBufferSize の DWORD を 0 に設定する。
pdwBufferSize
pvUserData が指すバッファ サイズ (バイト単位)。pvUserData が NULL の場合、このパラメータは 0 を保持する DWORD を示さなければならない。出力では、保持される DWORD はバッファに書き込まれるバイト数に設定される。失敗の場合、ここにはユーザー データの取得に必要なバイト数が保持され、メソッドは DPNERR_BUFFERTOOSMALL を返す。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_DOESNOTEXIST
DPNERR_INVALIDPOINTER

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dpaddr.h で宣言。


IDirectPlay8Address::SetSP

アドレス オブジェクトのサービス プロバイダ GUID を設定する。このアドレスにサービス プロバイダが指定されている場合、上書きされる。

HRESULT SetSP(
const GUID *const pguidSP
);

パラメータ

pguidSP
サービス プロバイダ GUID へのポインタ。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDPOINTER
DPNERR_NOTALLOWED

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dpaddr.h で宣言。


IDirectPlay8Address::SetUserData

アドレス オブジェクトにユーザー データを設定する。このアドレスにユーザー データが存在する場合は、この呼び出しで上書きされる。

HRESULT SetUserData(
const void *const pvUserData,
const DWORD dwDataSize
);

パラメータ

pvUserData
アドレスのユーザー データ セクションにあるデータを保持するバッファへのポインタ。NULL に設定して、ユーザー データを消去する。
dwDataSize
pvUserData のデータ サイズ (バイト単位)。pvUserData が NULL である場合、0 に設定しておく。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDPOINTER
DPNERR_NOTALLOWED

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dpaddr.h で宣言。


IDirectPlay8Address::GetNumComponents

アドレス内のコンポーネントの数を取得する。

HRESULT GetNumComponents(
PDWORD pdwNumComponents
);

パラメータ

pdwNumComponents
このアドレス オブジェクトのコンポーネント数を受け取る DWORD へのポインタ。

戻り値

成功した場合は S_OK を返す。それ以外の場合は、次のエラー値を返す。

DPNERR_INVALIDPOINTER

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dpaddr.h で宣言。


IDirectPlay8Address::GetComponentByName

指定されたキーのコンポーネントに関する情報を取得する。コンポーネントの値はネイティブなフォーマットで取得される。コンポーネント キーが見つからない場合、DPNERR_DOESNOTEXIST が返される。

コンポーネントの値はネイティブなフォーマットで取得される。したがって、コンポーネントの値が DWORD である場合、この呼び出しにより DWORD が取得される。つまり、バッファ サイズは 4 であり、pvBuffer は PDWORD に再設定される。

HRESULT GetComponentByName(
const WCHAR *const pwszName,
void* pvBuffer,
PDWORD pdwBufferSize,
PDWORD pdwDataType
);

パラメータ

pwszName
取得するコンポーネントの名前を指定する String。
pvBuffer
コンポーネントの値に格納されるデータを取得するバッファ。必要なサイズを取得するには、このパラメータに NULL を指定し、pdwBufferSize が指す DWORD に 0 を指定する。この場合、メソッドは DPNERR_BUFFERTOOSMALL を返す。
pdwBufferSize
入力では、pvBuffer が示す、バッファのサイズ (バイト単位) を保持する DWORD へのポインタ。出力では、成功の場合はバッファに書き込まれたバイト数、失敗の場合はデータの格納に必要なバイト数を保持する DWORD へのポインタ。
pdwDataType
このパラメータが指す DWORD。このコンポーネントに格納されるデータ型に設定される。次のいずれかに設定できる。
DPNA_DATATYPE_STRING
データは NULL 終端文字列である。
DPNA_DATATYPE_DWORD
データは DWORD である。
DPNA_DATATYPE_GUID
データは GUID である。
DPNA_DATATYPE_BINARY
データは未処理のバイナリである。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_BUFFERTOOSMALL
DPNERR_DOESNOTEXIST
DPNERR_INVALIDPARAM

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dpaddr.h で宣言。


IDirectPlay8Address::GetComponentByIndex

指定されたインデックスのコンポーネントに関する情報を取得する。コンポーネントの値はネイティブなフォーマットで取得される。コンポーネント キーが見つからない場合、メソッドは DPNERR_DOESNOTEXIST を返す。

コンポーネントの値はネイティブなフォーマットで取得される。したがって、コンポーネントの値が DWORD である場合、この呼び出しにより DWORD が取得される。つまり、バッファ サイズは 4 であり、pvBuffer は PDWORD に再設定される。

HRESULT GetComponentByIndex(
const DWORD dwComponentID,
WCHAR* pwszName,
PDWORD pdwNameLen,
void* pvBuffer,
PDWORD pdwBufferSize,
PDWORD pdwDataType
);

パラメータ

dwComponentID
取得するコンポーネントのインデックス。この値は 0 から始まり、[0..GetNumComponents()-1] の範囲にする。
pwszName
呼び出しが成功した場合にコンポーネントの名前を取得するバッファ。必要なサイズを取得するには、このパラメータに NULL を指定し、pdwNameBufferSize が示す DWORD に 0 を指定する。この場合、メソッドは DPNERR_BUFFERTOOSMALL を返す。
pdwNameLen
入力では、pwszName が示す、バッファのサイズ (文字単位、NULL ターミネータを含む) を保持する DWORD へのポインタ。出力では、成功の場合はバッファに書き込まれた文字数 (NULL ターミネータを含む)、失敗の場合はこの値の格納に必要な文字数 (NULL ターミネータを含む) を保持する DWORD へのポインタ 。
pvBuffer
コンポーネントの値に格納されるデータを取得するバッファ。必要なサイズを取得するには、このパラメータに NULL を指定し、pdwBufferSize が指す DWORD に 0 を指定する。この場合、メソッドは DPNERR_BUFFERTOOSMALL を返す。
pdwBufferSize
入力では、pvBuffer が示す、バッファのサイズ (バイト単位) を保持する DWORD へのポインタ。出力では、成功の場合はバッファに書き込まれたバイト数、失敗の場合はデータの格納に必要なバイト数を保持する DWORD へのポインタ。
pdwDataType
このパラメータが指す DWORD。このコンポーネントに格納されるデータ型に設定される。次のいずれかに設定できる。
DPNA_DATATYPE_STRING
データは NULL 終端文字列である。
DPNA_DATATYPE_DWORD
データは DWORD である。
DPNA_DATATYPE_GUID
データは GUID である。
DPNA_DATATYPE_BINARY
データは未処理のバイナリである。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_BUFFERTOOSMALL
DPNERR_DOESNOTEXIST
DPNERR_INVALIDPARAM

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dpaddr.h で宣言。


IDirectPlay8Address::AddComponent

アドレスにコンポーネントを追加する。コンポーネントがアドレスの一部である場合、この呼び出しにより新しい値に置き換わる。

この呼び出しを行うと、値はネイティブなフォーマットで指定される。したがって、lpvData パラメータは、ネイティブ フォーマットでデータを保持する変数に再設定されたポインタにする必要がある。たとえば、コンポーネントが GUID である場合、lpvData パラメータには GUID に再設定されたポインタを指定する必要がある。

このメソッドは、定義済みコンポーネント タイプが正しいフォーマットであるかどうかを確認する。

HRESULT AddComponent(
const WCHAR *const pwszName,
const void *const lpvData,
const DWORD dwDataSize,
const DWORD dwDataType
);

パラメータ

pwszName
コンポーネントのキーを保持する、NULL で終わる Unicode 文字列。
lpvData
指定されたキーに関連付けられた値を保持するバッファへのポインタ。データはネイティブ フォーマットで指定する必要がある。
dwDataSize
lpvData に保持されるバッファのデータ サイズ (バイト単位)。サイズはデータ型によって異なる。サイズが正しく指定されていない場合、このメソッドは DPNERR_INVALIDPARAM を返す。
DWORD
サイズ = sizeof( DWORD )
GUID
サイズ = sizeof( GUID )
String
サイズ = NULL ターミネータを含む文字列のサイズ (バイト単位)。
dwDataType
このキーに関連付けられた値のデータ型。データ型は、次のいずれかを使用できる。
DPNA_DATATYPE_STRING
データは NULL 終端文字列である。
DPNA_DATATYPE_DWORD
データは DWORD である。
DPNA_DATATYPE_GUID
データは GUID である。
DPNA_DATATYPE_BINARY
データは未処理のバイナリ フォーマットである。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER
DPNERR_NOTALLOWED

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dpaddr.h で宣言。


IDirectPlay8Address::GetDevice

アドレス オブジェクトのローカル デバイス GUID を取得する。デバイスが指定されていない場合、このメソッドは DPNERR_DOESNOTEXIST を返す。

HRESULT GetDevice(
GUID* pguidDevice
);

パラメータ

pguidDevice
アドレス オブジェクトのデバイスを受け取る GUID へのポインタ。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_DOESNOTEXIST
DPNERR_INVALIDPOINTER

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dpaddr.h で宣言。


IDirectPlay8Address::SetDevice

アドレス オブジェクトのローカル デバイス GUID を設定する。このアドレスにローカル デバイスが指定されている場合、上書きされる。

HRESULT SetDevice(
const GUID *const pguidDevice
);

パラメータ

pguidDevice
ローカル デバイスの GUID へのポインタ。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDPOINTER
DPNERR_NOTALLOWED

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dpaddr.h で宣言。


IDirectPlay8Address::BuildFromDPADDRESS

現在のオブジェクトの内部アドレスに、指定された DirectPlay 4 アドレスに相当する DirectPlay 8 のアドレスを設定する。このメソッドの目的は、ロビー開発者が古いロビー コードを使用して新しい Microsoft® DirectPlay® インターフェイスでゲームを起動できるようにすることにある。

このメソッドは、指定されたアドレスのアドレス コンポーネントを列挙し、対応する要素を DirectPlay 8 アドレスに追加する。

HRESULT BuildFromDPADDRESS(
LPVOID pvAddress,
DWORD dwDataSize
);

パラメータ

pvAddress
DirectPlay 8 アドレスのフォーマットに変換される DirectPlay4 アドレスへのポインタ。
dwDataSize
pvAddress パラメータに保持されるデータのサイズ。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDADDRESSFORMAT
DPNERR_INVALIDOBJECT
DPNERR_INVALIDPOINTER

注意

このメソッドは DirectPlay4 アドレスから DirectPlay 8 アドレスを作成する。このメソッドは、新しいアドレスを作成する前に、すべての要素の現行アドレスを消去する。

このメソッドには次の制限がある。

  • モデムを識別するとき、DirectPlay 4 ではモデム名を使用しているが、DirectPlay 8 では GUID を使用しているため、このメソッドで DPAID_Modem アドレス要素はマッピングできない。
  • 定義済みの DirectPlay 4 アドレス要素の一部ではない DirectPlay 4 アドレスの要素はエラーになり、戻り値は DPNERR_INVALIDADDRESSFORMAT になる。DirectPlay 4 アドレス要素の詳細なリストについては、DirectPlay 4 のドキュメントの DirectPlay アドレスに関する説明を参照すること。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dpaddr.h で宣言。


IDirectPlay8AddressIP

IDirectPlay8AddressIP は、CLSID_DirectPlayAddress COM オブジェクトから利用できるインターフェイスである。このインターフェイスは IP プロバイダ専用のアドレッシング サービスに使用される。

IDirectPlay8AddressIP インターフェイスには、次のメソッドがある。

IDirectPlay8AddressIP メソッド | BuildFromSockAddr
 | BuildAddress
 | BuildLocalAddress
 | GetSockAddress
 | GetLocalAddress
 | GetAddress

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dpaddr.h で宣言。


IDirectPlay8AddressIP::BuildFromSockAddr

有効な SOCKADDR 構造体からリモートの DirectPlay 8 IP アドレスを作成する。SOCKADDR 構造体は IP アドレスを指定する必要がある。アドレスのフォーマットが正しくない場合、DPNERR_INVALIDPARAM が返される。

呼び出しが成功した場合は、次の要素を伴う有効なリモート アドレスとなる。

  • DPNA_KEY_PROVIDER = CLSID_DP8SP_TCPIP
  • DPNA_KEY_HOSTNAME = 指定ホスト名
  • DPNA_KEY_PORT = 指定ポート

呼び出し前のオブジェクトに含まれるアドレス情報はすべて消去される。

HRESULT BuildFromSockAddr(
const SOCKADDR *const pSockAddr
);

パラメータ

pSockAddr
SOCKADDR フォームに指定された有効な UDP アドレス。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER
DPNERR_NOTALLOWED

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dpaddr.h で宣言。


IDirectPlay8AddressIP::BuildAddress

ホスト名とポートからリモートの DirectPlay 8 IP アドレスを作成する。呼び出しが成功した場合は、次の要素を伴う有効なリモート アドレスとなる。

  • DPNA_KEY_PROVIDER = CLSID_DP8SP_TCPIP
  • DPNA_KEY_HOSTNAME = 指定ホスト名
  • DPNA_KEY_PORT = 指定ポート

呼び出し前のオブジェクトに含まれるアドレス情報はすべて消去される。

HRESULT BuildAddress(
const WCHAR *const wszAddress,
const USHORT usPort
);

パラメータ

wszAddress
リモート ホスト アドレスには、ドットで区切られたインターネット アドレス (127.0.0.1 など) または有効なホスト名 (example.microsoft.com など) を指定できる。
usPort
接続先のリモート ホストのポート。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER
DPNERR_NOTALLOWED

注意

注 DPNSVR は、複数のプロセスが列挙用に単一のポートを共有できるようにする DirectPlay の機能である。デバイス アドレスを構築する場合、または接続を行う場合は、DPNA_DPNSVR_PORT フラグを使用しないこと。このフラグは列挙のみに使用する。列挙アドレスにポートの要素を追加しない場合、フラグによって表されるポートが自動的にそのアドレスに追加される。DPNSVR の詳細については、「DirectPlay DPNSVR アプリケーションの使い方」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dpaddr.h で宣言。


IDirectPlay8AddressIP::BuildLocalAddress

デバイスとポートからローカルの DirectPlay 8 IP アドレスを作成する。呼び出しが成功した場合は、次の要素を伴う有効なリモート アドレスとなる。

  • DPNA_KEY_PROVIDER = CLSID_DP8SP_TCPIP
  • DPNA_KEY_DEVICE= 指定デバイス
  • DPNA_KEY_PORT = 指定ポート

呼び出し前のオブジェクトに含まれるアドレス情報はすべて消去される。

HRESULT BuildLocalAddress(
const GUID *const pguidAdapter,
const USHORT usPort
);

パラメータ

pguidAdapter
ホストするローカル デバイスの識別子。
usPort
ホストするローカル デバイス上のポート。この値を 0 に設定すると、DirectPlay 8.0 は自動的にポートを選択できる。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER
DPNERR_NOTALLOWED

注意

注 DPNSVR は、複数のプロセスが列挙用に単一のポートを共有できるようにする DirectPlay の機能である。デバイス アドレスを構築する場合、または接続を行う場合は、DPNA_DPNSVR_PORT フラグを使用しないこと。このフラグは列挙のみに使用する。列挙アドレスにポートの要素を追加しない場合、フラグによって表されるポートが自動的にそのアドレスに追加される。DPNSVR の詳細については、「DirectPlay DPNSVR アプリケーションの使い方」を参照すること。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dpaddr.h で宣言。


IDirectPlay8AddressIP::GetSockAddress

このオブジェクトが表すアドレスを記述する SOCKADDR 構造体のリストを取得する。オブジェクトに指定されたホスト名に DNS ルックアップが必要な場合は、DNS ルックアップが実行される。したがって、DNS への問い合わせ中、このメソッドはブロックされることがある。また、ホスト名は複数のアドレスに解決されることもある。

成功するには、保持されているアドレスに少なくとも次の要素が含まれている必要がある。

  • DPNA_KEY_PROVIDER
  • DPNA_KEY_HOSTNAME
  • DPNA_KEY_PORT = 指定ポート
HRESULT GetSockAddress(
SOCKADDR* psockAddress,
PDWORD pdwAddressBufferSize
);

パラメータ

psockAddress
SOCKADDR 構造体の配列を取得するバッファへのポインタ。ホストが解決されるアドレスごとに 1 つの SOCKADDR 構造体がある。
pdwAddressBufferSize
psockAddresses に指定されるバッファのサイズ (バイト単位)。成功した場合、指定されたバッファに書き込まれたバイト数がこのパラメータに入る。失敗した場合、SOCKADDR 構造体の配列の取得に必要なバイト数がこのパラメータに入る。このパラメータを SOCKADDR 構造体のサイズで除算すると、返された配列内に存在する項目数がわかる。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dpaddr.h で宣言。


IDirectPlay8AddressIP::GetLocalAddress

DirectPlay 8 IP アドレスからローカル アドレス情報を取得する。成功するには、保持されているアドレスに少なくとも次の要素が含まれている必要がある。

  • DPNA_KEY_PROVIDER
  • DPNA_KEY_DEVICE
  • DPNA_KEY_PORT
HRESULT GetLocalAddress(
GUID* pguidAdapter,
USHORT* pusPort
);

パラメータ

pguidAdapter
このアドレスで指定されたローカル デバイスの GUID を取得する GUID へのポインタ。
pusPort
このローカル アドレスに指定されたポートを保持する USHORT へのポインタ。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dpaddr.h で宣言。


IDirectPlay8AddressIP::GetAddress

リモートの DirectPlay 8 IP アドレスからリモート アドレス情報を取得する。成功するには、保持されているアドレスに少なくとも次の要素が含まれている必要がある。

  • DPNA_KEY_PROVIDER
  • DPNA_KEY_HOSTNAME
  • DPNA_KEY_PORT = 指定ポート
HRESULT GetAddress(
WCHAR* wszAddress,
PDWORD pdwAddressLength,
USHORT* psPort
);

パラメータ

wszAddress
ホスト名を受け取るバッファへのポインタ。このパラメータを NULL にすると、必要なサイズを取得できる。
pdwAddressLength
wszAddress に指定されるバッファのサイズ (文字単位、NULL ターミネータを含む)。成功した場合、このパラメータには指定されたバッファに書き込まれた文字数が入る (NULL ターミネータを含む)。失敗した場合、このパラメータには、ホスト名の取得に必要な文字数が入る (NULL ターミネータを含む)。
psPort
このローカル アドレスに指定されたポートを保持する USHORT へのポインタ。

戻り値

成功した場合は S_OK を返し、失敗した場合は次のいずれかのエラー値を返す。

DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDPARAM
DPNERR_INVALIDPOINTER

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dpaddr.h で宣言。


関数

Microsoft® DirectPlay® の関数を次に示す。

  • DirectPlay8Create
  • DirectPlay8LobbyCreate
  • DirectPlay8AddressCreate
  • DirectPlayVoiceCreate


DirectPlay8Create

DirectPlay8Create 関数は、Dplay8.h ヘッダー ファイルで定義されるインターフェイスを作成するための外部関数である。

HRESULT WINAPI DirectPlay8Create(
  GUID* pcIID,
  void** ppvInterface,
  IUnknown* pUnknown
);

パラメータ

pcIID
作成するインターフェイス ID へのポインタ。IID_IDirectPlay8Client、IID_IDirectPlay8Server、または IID_IDirectPlay8Peer のいずれかのインターフェイス ID を指定できる。
ppvInterface
新しいインターフェイス ポインタを受け取る変数のアドレス。
pUnknown
COM 集成体の場合は、制御オブジェクトの IUnknown インターフェイスのアドレス。NULL に設定しておく。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


DirectPlay8LobbyCreate

DirectPlay8LobbyCreate 関数は、Dplobby8.h ヘッダー ファイルで定義されるロビー インターフェイスの 1 つを作成するための外部関数である。

HRESULT WINAPI DirectPlay8LobbyCreate(
  GUID* pcIID,
  void** ppvInterface,
  IUnknown* pUnknown
);

パラメータ

pcIID
作成するインターフェイス ID へのポインタ。IID_IDirectPlay8LobbiedApplication または IID_IDirectPlay8LobbyClient のいずれかのインターフェイス ID を指定できる。
ppvInterface
新しいインターフェイス ポインタを受け取る変数のアドレス。
pUnknown
COM 集成体の場合は、制御オブジェクトの IUnknown インターフェイスのアドレス。NULL に設定しておく。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplobby8.h で宣言。


DirectPlay8AddressCreate

DirectPlay8AddressCreate 関数は、Dpaddr.h ヘッダー ファイルで定義されるアドレッシング インターフェイスの 1 つを作成するための外部関数である。

HRESULT WINAPI DirectPlay8AddressCreate(
  GUID* pcIID,
  void** ppvInterface,
  IUnknown* pUnknown
);

パラメータ

pcIID
作成するインターフェイス ID へのポインタ。IID_IDirectPlay8Address または IID_IDirectPlay8AddressIP のいずれかのインターフェイス ID を指定できる。
ppvInterface
新しいインターフェイス ポインタを受け取る変数のアドレス。
pUnknown
COM 集成体の場合は、制御オブジェクトの IUnknown インターフェイスのアドレス。NULL に設定しておく。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dpaddr.h で宣言。


DirectPlayVoiceCreate

DirectPlayVoiceCreate 関数は、Dvoice.h ヘッダー ファイルで定義され、Microsoft® DirectPlay® Voice で使用されるインターフェイスの 1 つを作成するための外部関数である。

HRESULT WINAPI DirectPlayVoiceCreate(
  GUID* pcIID,
  void** ppvInterface,
  IUnknown* pUnknown
);

パラメータ

pcIID
作成するインターフェイス ID へのポインタ。IID_IDirectPlayVoiceTest、IID_IDirectPlayVoiceClient、または IID_IDirectPlayVoiceServer のいずれかのインターフェイス ID を指定できる。
ppvInterface
新しいインターフェイス ポインタを受け取る変数のアドレス。
pUnknown
COM 集成体の場合は、制御オブジェクトの IUnknown インターフェイスのアドレス。NULL に設定しておく。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。


コールバック関数

Microsoft® DirectPlay® のコールバック関数を次に示す。

  • PFNDPNMESSAGEHANDLER
  • PDVMESSAGEHANDLER


PFNDPNMESSAGEHANDLER

PFNDPNMESSAGEHANDLER は、アプリケーション定義のコールバック関数で、IDirectPlay8Peer、IDirectPlay8Client、IDirectPlay8Server、IDirectPlay8LobbyClient、およびIDirectPlay8LobbiedApplication インターフェイスを使ってメッセージを処理する。

typedef HRESULT (WINAPI *PFNDPNMESSAGEHANDLER)(
  PVOID pvUserContext,
  DWORD dwMessageType,
  PVOID pMessage
);

パラメータ

pvUserContext
このコールバック関数に渡されるアプリケーション定義構造体へのポインタ。Initialize メソッドの pvUserContext パラメータに定義される。
dwMessageType
次のメッセージ タイプのいずれか 1 つ。IDirectPlay8Peer、IDirectPlay8Client、および IDirectPlay8Server の各インターフェイスによって生成される。各インターフェイスは、有効なメッセージのうちで、それぞれ異なるサブセットを使用する。詳細については、インターフェイスのドキュメントを参照すること。
  • DPN_MSGID_ADD_PLAYER_TO_GROUP
  • DPN_MSGID_ASYNC_OP_COMPLETE
  • DPN_MSGID_CLIENT_INFO
  • DPN_MSGID_CONNECT_COMPLETE
  • DPN_MSGID_CREATE_GROUP
  • DPN_MSGID_CREATE_PLAYER
  • DPN_MSGID_DESTROY_GROUP
  • DPN_MSGID_DESTROY_PLAYER
  • DPN_MSGID_ENUM_HOSTS_QUERY
  • DPN_MSGID_ENUM_HOSTS_RESPONSE
  • DPN_MSGID_GROUP_INFO
  • DPN_MSGID_HOST_MIGRATE
  • DPN_MSGID_INDICATE_CONNECT
  • DPN_MSGID_INDICATED_CONNECT_ABORTED
  • DPN_MSGID_PEER_INFO
  • DPN_MSGID_RECEIVE
  • DPN_MSGID_REMOVE_PLAYER_FROM_GROUP
  • DPN_MSGID_RETURN_BUFFER
  • DPN_MSGID_SEND_COMPLETE
  • DPN_MSGID_SERVER_INFO
  • DPN_MSGID_TERMINATE_SESSION

    また、Microsoft® DirectPlay® のロビー機能がアプリケーションでサポートされている場合、IDirectPlay8LobbyClient インターフェイスおよびIDirectPlay8LobbiedApplication インターフェイスで生成される次のメッセージ タイプのいずれかをこのパラメータに指定できる。各インターフェイスは、有効なメッセージのうちで、それぞれ異なるサブセットを使用する。詳細については、インターフェイスのドキュメントを参照すること。

  • DPL_MSGID_CONNECT
  • DPL_MSGID_CONNECTION_SETTINGS
  • DPL_MSGID_DISCONNECT
  • DPL_MSGID_RECEIVE
  • DPL_MSGID_SESSION_STATUS
pMessage
メッセージ情報を保持する構造体。

戻り値

適切な戻り値については、各メッセージのドキュメントを参照すること。ドキュメントに記述がない場合、この関数は S_OK を返す。

注意

この関数は、複数のスレッドから再入可能な形式で呼び出される可能性があるため、スレッドセーフでなければならない。

同じプレーヤーからのコールバック メッセージは、順番に並べられる。プレーヤーからメッセージを受け取ると、そのメッセージを処理し、コールバック関数が戻されるまで別のメッセージを受け取ることはない。

メッセージ構造体の名前はメッセージ タイプ名と同じだが、"DPN_MSGID" は "DPNMSG" になる。たとえば、DPN_MSGID_CONNECTION_TERMINATED メッセージ タイプは、DPNMSG_CONNECTION_TERMINATED メッセージ構造体を使用して、実際のメッセージ情報を保持する。

このコールバック関数を実装する場合は、最初に dwMessageType パラメータに返されるメッセージ タイプを調べ、次にメッセージ構造体 (pMessage) をそのタイプに設定してメッセージ情報を取得する。メッセージの中には、パラメータがないため、定義された構造体を持たないものもある。このようなメッセージの場合、pMessage パラメータは NULL にする。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


PDVMESSAGEHANDLER

PDVMESSAGEHANDLER はアプリケーションにより定義されたコールバック関数であり、IDirectPlayVoiceClient インターフェイスおよび IDirectPlayVoiceServer インターフェイスでユーザーにメッセージを送信するときに使用される。

typedef HRESULT (FAR PASCAL *PDVMESSAGEHANDLER)(
  LPVOID pvUserContext,
  DWORD dwMessageType,
  LPVOID lpMessage
);

パラメータ

pvUserContext
このコールバック関数に渡されるアプリケーション定義構造体へのポインタ。IDirectPlayVoiceServer::Initialize メソッドおよび IDirectPlayVoiceClient::Initialize メソッドの lpUserContext パラメータで定義される。
dwMessageType
次のメッセージ タイプのいずれか 1 つ。
DVMSGID_CONNECTRESULT
DVMSGID_CREATEVOICEPLAYER
DVMSGID_DELETEVOICEPLAYER
DVMSGID_DISCONNECTRESULT
DVMSGID_GAINFOCUS
DVMSGID_HOSTMIGRATED
DVMSGID_INPUTLEVEL
DVMSGID_LOCALHOSTSETUP
DVMSGID_LOSTFOCUS
DVMSGID_OUTPUTLEVEL
DVMSGID_PLAYEROUTPUTLEVEL
DVMSGID_PLAYERVOICESTART
DVMSGID_PLAYERVOICESTOP
DVMSGID_RECORDSTART
DVMSGID_RECORDSTOP
DVMSGID_SESSIONLOST
DVMSGID_SETTARGETS
lpMessage
メッセージ情報を保持する構造体。

戻り値

適切な戻り値については、各メッセージのドキュメントを参照すること。ドキュメントに記述がない場合、この関数は S_OK を返す。

注意

このコールバック関数を実装する場合は、最初に dwMessageType パラメータに返されるメッセージ タイプを調べ、次にメッセージ構造体 (lpMessage) をそのタイプに設定してメッセージ情報を取得する必要がある。メッセージの中には、パラメータがないため、定義された構造体を持たないものもある。このようなメッセージの場合、lpMessage パラメータは NULL にする。

注 : この関数は、複数の異なるスレッドから同時に呼び出される可能性がある。このため、スレッドセーフかつ再入可能でなければならない。

すべてのメッセージ構造体の名前は対応するメッセージ タイプ名と同じだが、接頭辞は DVMSGID_ の代わりに DVMSG_ になる。たとえば、DVMSGID_RECORDSTART の構造体は DVMSG_RECORDSTART である。

メッセージ ハンドラに送信される構造体は、呼び出し処理中のみ有効である。したがって、関数に渡された情報をハンドラ関数が戻った後に使用する場合は、データをコピーする必要がある。

同じプレーヤーからのコールバック メッセージは、順番に並べられる。プレーヤーからメッセージを受け取ると、そのメッセージを処理し、コールバック関数が戻されるまで別のメッセージを受け取ることはない。

IDirectPlayVoiceClient::Initialize、IDirectPlayVoiceServer::Initialize、IDirectPlayVoiceClient::SetNotifyMask、および IDirectPlayVoiceServer::SetNotifyMask の各メソッドの呼び出しによりメッセージ マスクに指定されたメッセージのみがこのコールバック関数に送信される。

DVMSGID_GAINFOCUS メッセージ構造体および DVMSGID_LOSTFOCUS メッセージ構造体は、Microsoft® DirectPlay® のこのリリースには実装されていない。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。


システム メッセージ

Microsoft® DirectPlay® メッセージは、DirectPlay コールバック メッセージ ハンドラによって受信される。DirectPlay はこれらのメッセージを使って、システムから DirectPlay アプリケーションに情報を伝達する。

  • DirectPlay サーバー メッセージ
  • DirectPlay クライアント メッセージ
  • DirectPlay ロビー メッセージ
  • DirectPlay Voice メッセージ

DirectPlay サーバー メッセージ

すべての Microsoft® DirectPlay® サーバー コールバック メッセージ ハンドラで処理しなければならないメッセージを以下に示す。

  • DPN_MSGID_CREATE_PLAYER
  • DPN_MSGID_DESTROY_PLAYER
  • DPN_MSGID_INDICATE_CONNECT
  • DPN_MSGID_INDICATED_CONNECT_ABORTED
  • DPN_MSGID_RECEIVE
  • DPN_MSGID_RETURN_BUFFER

次に示すメッセージは、DirectPlay サーバー コールバック メッセージ ハンドラにより処理できるが、必須のメッセージではない。

  • DPN_MSGID_ADD_PLAYER_TO_GROUP
  • DPN_MSGID_ASYNC_OP_COMPLETE
  • DPN_MSGID_CLIENT_INFO
  • DPN_MSGID_CREATE_GROUP
  • DPN_MSGID_DESTROY_GROUP
  • DPN_MSGID_GROUP_INFO
  • DPN_MSGID_ENUM_HOSTS_QUERY
  • DPN_MSGID_REMOVE_PLAYER_FROM_GROUP
  • DPN_MSGID_SEND_COMPLETE
  • DPN_MSGID_SERVER_INFO

DirectPlay クライアント メッセージ

すべての DirectPlay クライアント コールバック メッセージ ハンドラが処理しなければならないメッセージを次に示す。

  • DPN_MSGID_RECEIVE
  • DPN_MSGID_TERMINATE_SESSION
  • DPN_MSGID_RETURN_BUFFER

次に示すメッセージは、DirectPlay クライアント コールバック メッセージ ハンドラにより処理できるが、必須のメッセージではない。

  • DPN_MSGID_ASYNC_OP_COMPLETE
  • DPN_MSGID_CLIENT_INFO
  • DPN_MSGID_CONNECT_COMPLETE
  • DPN_MSGID_ENUM_HOSTS_RESPONSE
  • DPN_MSGID_SEND_COMPLETE
  • DPN_MSGID_SERVER_INFO
  • DPN_MSGID_GROUP_INFO

DirectPlay ロビー メッセージ

ロビー クライアントおよびロビー アプリケーションのコールバック メッセージ ハンドラが処理するメッセージを次に示す。

  • DPL_MSGID_CONNECT
  • DPL_MSGID_CONNECTION_SETTINGS
  • DPL_MSGID_DISCONNECT
  • DPL_MSGID_RECEIVE
  • DPL_MSGID_SESSION_STATUS

DirectPlay Voice メッセージ

Microsoft® DirectPlay® 音声コールバック メッセージ ハンドラが処理するメッセージを次に示す。

  • DVMSGID_CONNECTRESULT
  • DVMSGID_CREATEVOICEPLAYER
  • DVMSGID_DELETEVOICEPLAYER
  • DVMSGID_DISCONNECTRESULT
  • DVMSGID_GAINFOCUS
  • DVMSGID_HOSTMIGRATED
  • DVMSGID_INPUTLEVEL
  • DVMSGID_LOCALHOSTSETUP
  • DVMSGID_LOSTFOCUS
  • DVMSGID_OUTPUTLEVEL
  • DVMSGID_PLAYEROUTPUTLEVEL
  • DVMSGID_PLAYERVOICESTART
  • DVMSGID_PLAYERVOICESTOP
  • DVMSGID_RECORDSTART
  • DVMSGID_RECORDSTOP
  • DVMSGID_SESSIONLOST
  • DVMSGID_SETTARGETS


DPL_MSGID_CONNECT

ロビー クライアントが IDirectPlay8LobbyClient::ConnectApplication メソッドを使用してロビー アプリケーションに接続するとき、DPL_MSGID_CONNECT メッセージが生成される。

DPL_MESSAGE_CONNECT

DPL_MESSAGE_CONNECT 構造体は、DPL_MSGID_CONNECT メッセージと共に渡される。

typedef struct _DPL_MESSAGE_CONNECT{
    DWORD     dwSize;
    DPNHANDLE hConnectId;
    PDPL_CONNECTION_SETTINGS  pdplConnectionSettings;
    PVOID     pvLobbyConnectData;
    DWORD     dwLobbyConnectDataSize;
    PVOID     pvConnectionContext;
} DPL_MESSAGE_CONNECT, *PDPL_MESSAGE_CONNECT;
dwSize
DPL_MESSAGE_CONNECT メッセージ構造体のサイズ。アプリケーションは、この構造体を使用する前に、まずこのメンバを設定する必要がある。
hConnectId
接続の識別に使用されるハンドル。このハンドルは、後で IDirectPlay8LobbyClient::Send および IDirectPlay8LobbyClient::ReleaseApplication の呼び出しに使用される。
pdplConnectionSettings
接続情報を保持する DPL_CONNECTION_SETTINGS 構造体へのポインタ。
pvLobbyConnectData
ロビー接続データへのポインタ。
dwLobbyConnectDataSize
pvLobbyConnectData メンバに保持されたデータのサイズを指定する DWORD 型の変数。
pvConnectionContext
この接続に関連付けられたコンテキスト値。ロピー アプリケーションの場合は、メッセージ ハンドラがこのメッセージを受け取ったときにこのパラメータを設定し、コンテキスト値を接続に関連付ける。NULL に設定すると、コンテキスト値を無効にすることができる。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplobby8.h で宣言。


DPL_MSGID_CONNECTION_SETTINGS

IDirectPlay8LobbyClient::SetConnectionSettings が呼び出されると、DPL_MSGID_CONNECTION_SETTINGS メッセージがロビー クライアントからロビー アプリケーションに送信される。IDirectPlay8LobbiedApplication::SetConnectionSettings が呼び出された場合にも、ロビー アプリケーションからロビー クライアントにこのメッセージが送信される。メッセージの内容は、メッセージのコールバック処理中のみ有効である。したがって、メッセージに含まれるデータを使用するためには、戻る前にコピーを作成する必要がある。さらに、アドレス オブジェクトを使用するには、アドレスごとに AddRef を呼び出し、確実に参照を保持する必要がある。

DPL_MESSAGE_CONNECTION_SETTINGS

DPL_MESSAGE_CONNECTION_SETTINGS 構造体は、DPL_MSGID_CONNECTION_SETTINGS メッセージと共に渡される。

typedef struct _DPL_MESSAGE_CONNECTION_SETTINGS{
    DWORD               dwSize;
    DPNHANDLE           hSender;
    PDPL_CONNECTION_SETTINGS   pdplConnectionSettings;
    PVOID               pvConnectionContext
} DPL_MESSAGE_CONNECTION_SETTINGS, *PDPL_MESSAGE_CONNECTION_SETTINGS;
dwSize
DPL_MESSAGE_CONNECTION_SETTINGS 構造体のサイズを保持する。sizeof( DPL_MESSAGE_CONNECTION_SETTINGS ) に設定する必要がある。
hSender
このメッセージを送信した接続のハンドルを保持する。
pdplConnectionSettings
指定された接続の接続設定を記述する DPL_CONNECTION_SETTINGS 構造体へのポインタを保持する。
pvConnectionContext
接続に対して設定されているコンテキスト値へのポインタ。

注意

ロビー アプリケーションの場合、コンテキスト値は DPL_MESSAGE_CONNECT メッセージ構造体の pvConnectionContext メンバにより設定される。メッセージ ハンドラがこのメッセージを受け取った場合は、戻る前にこのメンバに設定した値が、その接続のコンテキスト値になる。

ロビー クライアントの場合、接続が成功すると、IDirectPlay8LobbyClient::ConnectApplication メソッドの pvConnectionContext パラメータが接続のコンテキスト値として使用される。

コンテキスト値は、ロビー クライアントとロビー アプリケーションの間で共有されない。たとえば、ロビー接続のコンテキスト値を、IDirectPlay8LobbyClient インターフェイスではポインタ A に、IDirectPlay8LobbiedApplication インターフェイスではポインタ B に設定した場合、IDirectPlay8LobbyClient インターフェイスではポインタ A がコンテキスト値になり、IDirectPlay8LobbiedApplication インターフェイスではポインタ B がコンテキスト値になる。

この機能を使用する必要がない場合は、コンテキスト値を NULL に設定できる。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplobby8.h で宣言。


DPL_MSGID_DISCONNECT

ロビー クライアントが IDirectPlay8LobbyClient::ReleaseApplication メソッドを使用してロビー アプリケーションから接続解除すると、Microsoft® DirectPlay® により DPL_MSGID_DISCONNECT メッセージが生成される。

DPL_MESSAGE_DISCONNECT

DPL_MESSAGE_DISCONNECT 構造体には、DPL_MSGID_DISCONNECT システム メッセージに関する情報が保持される。

typedef struct _DPL_MESSAGE_DISCONNECT{
    DWORD     dwSize;
    DPNHANDLE hDisconnectId;
    HRESULT   hrReason;
    PVOID     pvConnectionContext;
} DPL_MESSAGE_DISCONNECT, *PDPL_MESSAGE_DISCONNECT;
dwSize
DPL_MESSAGE_DISCONNECT メッセージ構造体のサイズ。アプリケーションは、この構造体を使用する前に、まずこのメンバを設定する必要がある。
hDisconnectId
接続解除 ID を指定するハンドル。
hrReason
接続解除の理由。
S_OK
通常の接続解除。
DPNERR_CONNECTIONLOST
クライアントまたはアプリケーションを実行しているプロセスが異常終了した場合に設定される。
pvConnectionContext
接続に対して設定されているコンテキスト値。

注意

ロビー アプリケーションの場合、コンテキスト値は DPL_MESSAGE_CONNECT メッセージ構造体の pvConnectionContext メンバにより設定される。メッセージ ハンドラがこのメッセージを受け取った場合は、戻る前にこのメンバに設定した値が、その接続のコンテキスト値になる。

ロビー クライアントの場合、接続が成功すると、IDirectPlay8LobbyClient::ConnectApplication メソッドの pvConnectionContext パラメータが接続のコンテキスト値として使用される。

コンテキスト値は、ロビー クライアントとロビー アプリケーションの間で共有されない。たとえば、ロビー接続のコンテキスト値を、IDirectPlay8LobbyClient インターフェイスではポインタ A に、IDirectPlay8LobbiedApplication インターフェイスではポインタ B に設定した場合、IDirectPlay8LobbyClient インターフェイスではポインタ A がコンテキスト値になり、IDirectPlay8LobbiedApplication インターフェイスではポインタ B がコンテキスト値になる。

この機能を使用する必要がない場合は、コンテキスト値を NULL に設定できる。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplobby8.h で宣言。 で宣言。


DPL_MSGID_RECEIVE

IDirectPlay8LobbyClient::Send または IDirectPlay8LobbiedApplication::Send メソッドにより送信されたメッセージをターゲットが受け取ると、Microsoft® DirectPlay® により DPL_MSGID_RECEIVE メッセージが生成される。

DPL_MESSAGE_RECEIVE

DPL_MESSAGE_RECEIVE 構造体には、DPL_MSGID_RECEIVE システム メッセージに関する情報が保持される。

typedef struct _DPL_MESSAGE_RECEIVE{
    DWORD     dwSize;
    DPNHANDLE hSender;
    BYTE*     pBuffer;
    DWORD     dwBufferSize;
    PVOID     pvConnectionContext;
} DPL_MESSAGE_RECEIVE, *PDPL_MESSAGE_RECEIVE;
dwSize
DPL_MESSAGE_RECEIVE メッセージ構造体のサイズ。アプリケーションは、この構造体を使用する前に、まずこのメンバを設定する必要がある。
hSender
メッセージを送信したクライアントのハンドル。
pBuffer
メッセージ データへのポインタ。
dwBufferSize
pBuffer メンバに保持されたメッセージのサイズ。
pvConnectionContext
接続に対して設定されているコンテキスト値。

注意

ロビー アプリケーションの場合、コンテキスト値は DPL_MESSAGE_CONNECT メッセージ構造体の pvConnectionContext メンバにより設定される。メッセージ ハンドラがこのメッセージを受け取った場合は、戻る前にこのメンバに設定した値が、その接続のコンテキスト値になる。

ロビー クライアントの場合、接続が成功すると、IDirectPlay8LobbyClient::ConnectApplication メソッドの pvConnectionContext パラメータが接続のコンテキスト値として使用される。

コンテキスト値は、ロビー クライアントとロビー アプリケーションの間で共有されない。たとえば、ロビー接続のコンテキスト値を、IDirectPlay8LobbyClient インターフェイスではポインタ A に、IDirectPlay8LobbiedApplication インターフェイスではポインタ B に設定した場合、IDirectPlay8LobbyClient インターフェイスではポインタ A がコンテキスト値になり、IDirectPlay8LobbiedApplication インターフェイスではポインタ B がコンテキスト値になる。

この機能を使用する必要がない場合は、コンテキスト値を NULL に設定できる。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplobby8.h で宣言。 で宣言。


DPL_MSGID_SESSION_STATUS

IDirectPlay8LobbiedApplication::UpdateStatus メソッドの呼び出しによりセッションが更新されると、Microsoft® DirectPlay® により DPL_MSGID_SESSION_STATUS メッセージが生成される。

DPL_MESSAGE_SESSION_STATUS

DPL_MESSAGE_SESSION_STATUS 構造体には、DPL_MSGID_SESSION_STATUS システム メッセージに関する情報が保持される。

typedef struct _DPL_MESSAGE_SESSION_STATUS{
    DWORD dwSize;
    DPNHANDLE hSender;
    DWORD dwStatus;
    PVOID pvConnectionContext;
} DPL_MESSAGE_SESSION_STATUS, *PDPL_MESSAGE_SESSION_STATUS;
dwSize
DPL_MESSAGE_SESSION_STATUS メッセージ構造体のサイズ。アプリケーションは、この構造体を使用する前に、まずこのメンバを設定する必要がある。
hSender
状態更新メッセージを送信したアプリケーションのハンドル。
dwStatus
セッションの更新された状態。このメンバには以下のいずれかの値を設定できる。
DPLSESSION_CONNECTED
ロビー アプリケーションは現在セッションに接続されている。
DPLSESSION_COULDNOTCONNECT
ロビー アプリケーションをセッションに接続できない。
DPLSESSION_DISCONNECTED
ロビー アプリケーションは現在セッションから接続解除されている。
DPLSESSION_TERMINATED
セッション ホストとロビー アプリケーションの間の接続は終了した。
DPLSESSION_HOSTMIGRATED
ピアツーピア セッションのホストが移行された。ローカル クライアントは新しいホストではない。
DPLSESSION_HOSTMIGRATEDHERE
ピアツーピア セッションのホストが移行された。ローカル クライアントが新しいホストである。
pvConnectionContext
接続に対して設定されているコンテキスト値。

注意

ロビー アプリケーションの場合、コンテキスト値は DPL_MESSAGE_CONNECT メッセージ構造体の pvConnectionContext メンバにより設定される。メッセージ ハンドラがこのメッセージを受け取った場合は、戻る前にこのメンバに設定した値が、その接続のコンテキスト値になる。

ロビー クライアントの場合、接続が成功すると、IDirectPlay8LobbyClient::ConnectApplication メソッドの pvConnectionContext が接続のコンテキスト値として使用される。

コンテキスト値は、ロビー クライアントとロビー アプリケーションの間で共有されない。たとえば、ロビー接続のコンテキスト値を、IDirectPlay8LobbyClient インターフェイスではポインタ A に、IDirectPlay8LobbiedApplication インターフェイスではポインタ B に設定した場合、IDirectPlay8LobbyClient インターフェイスではポインタ A がコンテキスト値になり、IDirectPlay8LobbiedApplication インターフェイスではポインタ B がコンテキスト値になる。

この機能を使用する必要がない場合は、コンテキスト値を NULL に設定できる。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplobby8.h で宣言。 で宣言。


DPN_MSGID_APPLICATION_DESC

このメッセージは、アプリケーション記述が変更されたことを示す。付随する構造体はない。新しいアプリケーション記述を調べるには、IDirectPlay8Peer、IDirectPlay8Client、または IDirectPlay8Server インターフェイスによって公開される GetApplicationDesc メソッドを呼び出す。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplobby8.h で宣言。 で宣言。


DPN_MSGID_ADD_PLAYER_TO_GROUP

ピアツーピア セッションまたはクライアント/サーバー セッションのグループにプレーヤーが追加されると、Microsoft® DirectPlay® により DPN_MSGID_ADD_PLAYER_TO_GROUP メッセージが生成される。

DPNMSG_ADD_PLAYER_TO_GROUP

DPNMSG_ADD_PLAYER_TO_GROUP 構造体には、DPN_MSGID_ADD_PLAYER_TO_GROUP システム メッセージに関する情報が保持される。

typedef struct _DPNMSG_ADD_PLAYER_TO_GROUP{
    DWORD  dwSize;
    DPNID  dpnidGroup;
    PVOID  pvGroupContext;
    DPNID  dpnidPlayer;
    PVOID  pvPlayerContext;
} DPNMSG_ADD_PLAYER_TO_GROUP, *PDPNMSG_ADD_PLAYER_TO_GROUP;
dwSize
この構造体のサイズ。
dpnidGroup
プレーヤーを追加するグループの DPNID。
pvGroupContext
グループのコンテキスト値。
dpnidPlayer
グループに追加するプレーヤーの DPNID。
pvPlayerContext
プレーヤーのコンテキスト値。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


DPN_MSGID_ASYNC_OP_COMPLETE

非同期要求が完了すると、Microsoft® DirectPlay® により DPN_MSGID_ASYNC_OP_COMPLETE メッセージが生成される。

DPNMSG_ASYNC_OP_COMPLETE

DPNMSG_ASYNC_OP_COMPLETE 構造体には、DPN_MSGID_ASYNC_OP_COMPLETE システム メッセージに関する情報が保持される。

typedef struct _DPNMSG_ASYNC_OP_COMPLETE{
    DWORD      dwSize;
    DPNHANDLE  hAsyncOp;
    PVOID      pvUserContext;
    HRESULT    hResultCode;
} DPNMSG_ASYNC_OP_COMPLETE, *PDPNMSG_ASYNC_OP_COMPLETE;
dwSize
この構造体のサイズ。
hAsyncOp
非同期処理ハンドル。
pvUserContext
指定されたユーザー コンテキスト。
hResultCode
非同期処理の結果を示す HRESULT。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


DPN_MSGID_CLIENT_INFO

クライアント データがクライアント/サーバー セッションの間に変更されると、Microsoft® DirectPlay® により DPN_MSGID_CLIENT_INFO メッセージが生成される。

DPNMSG_CLIENT_INFO

DPNMSG_CLIENT_INFO 構造体には、DPN_MSGID_CLIENT_INFO システム メッセージに関する情報が保持される。

typedef struct _DPNMSG_CLIENT_INFO{
    DWORD  dwSize;
    DPNID  dpnidClient;
    PVOID  pvPlayerContext;
} DPNMSG_CLIENT_INFO, *PDPNMSG_CLIENT_INFO;
dwSize
この構造体のサイズ。
dpnidClient
クライアント情報用のクライアントの DPNID。
pvPlayerContext
プレーヤーのコンテキスト値。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


DPN_MSGID_CONNECT_COMPLETE

ピアツーピア セッションまたはクライアント/サーバー セッションで接続の試行が完了すると、Microsoft® DirectPlay® により DPN_MSGID_CONNECT_COMPLETE メッセージが生成される。接続が成功したどうかに関係なく、このメッセージは生成される。

DPNMSG_CONNECT_COMPLETE

DPNMSG_CONNECT_COMPLETE 構造体には、DPN_MSGID_CONNECT_COMPLETE システム メッセージに関する情報が保持される。

typedef struct _DPNMSG_CONNECT_COMPLETE{
    DWORD      dwSize;
    DPNHANDLE  hAsyncOp;
    PVOID      pvUserContext;
    HRESULT    hResultCode;
    PVOID      pvApplicationReplyData;
    DWORD      dwApplicationReplyDataSize;
} DPNMSG_CONNECT_COMPLETE, *PDPNMSG_CONNECT_COMPLETE;
dwSize
この構造体のサイズ。
hAsyncOp
非同期処理ハンドル。
pvUserContext
IDirectPlay8Peer::Connect または IDirectPlay8Client::Connect メソッドを呼び出したときに提供されるユーザー コンテキスト。
hResultCode
接続の結果を記述する HRESULT。詳細については、IDirectPlay8Peer::Connect メソッドまたは IDirectPlay8Client::Connect メソッドの「戻り値」を参照すること。また、プレーヤーがピアツーピア セッションに参加しようとしたときに、セッションのほかの既存プレーヤーの少なくとも 1 人がそのプレーヤーに接続できないと、DPNERR_PLAYERNOTREACHABLE が返される。
pvApplicationReplyData
ホストまたはサーバーから返された接続応答データ。
dwApplicationReplyDataSize
pvApplicationReplyData メンバのデータのサイズ (バイト単位)。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


DPN_MSGID_CREATE_GROUP

グループが作成されると、Microsoft® DirectPlay® により DPN_MSGID_CREATE_GROUP メッセージが生成される。

DPNMSG_CREATE_GROUP

DPNMSG_CREATE_GROUP 構造体には、DPN_MSGID_CREATE_GROUP システム メッセージに関する情報が保持される。

typedef struct _DPNMSG_CREATE_GROUP{
    DWORD  dwSize;
    DPNID  dpnidGroup;
    DPNID  dpnidOwner;
    PVOID  pvGroupContext;
} DPNMSG_CREATE_GROUP, *PDPNMSG_CREATE_GROUP;
dwSize
この構造体のサイズ。
dpnidGroup
作成されたグループの DPNID。
dpnidOwner
グループの所有者の DPNID。この値は、DPN_GROUP_INFO 構造体の dwGroupFlags メンバの DPNGROUP_AUTODESTRUCT フラグが設定されているグループのみに設定する。
pvGroupContext
グループのコンテキスト値。

注意

グループのコンテキスト値を設定する唯一の方法は、このシステム メッセージを使用することである。一度設定したグループのコンテキスト値は変更できない。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


DPN_MSGID_CREATE_PLAYER

ピアツーピア セッションまたはクライアント/サーバー セッションにプレーヤーが追加されると、Microsoft® DirectPlay® により DPN_MSGID_CREATE_PLAYER メッセージが生成される。

DPNMSG_CREATE_PLAYER

DPNMSG_CREATE_PLAYER 構造体には、DPN_MSGID_CREATE_PLAYER システム メッセージに関する情報が保持される。

typedef struct _DPNMSG_CREATE_PLAYER{
    DWORD  dwSize;
    DPNID  dpnidPlayer;
    PVOID  pvPlayerContext;
} DPNMSG_CREATE_PLAYER, *PDPNMSG_CREATE_PLAYER;
dwSize
この構造体のサイズ。
dpnidPlayer
セッションに追加されたプレーヤーの DPNID。
pvPlayerContext
プレーヤーのコンテキスト値。

注意

プレーヤーのコンテキスト値を設定する唯一の方法は、このシステム メッセージを使用することである。プレーヤー コンテキスト値は、このメッセージを使用して直接設定するか、DPN_MSGID_INDICATE_CONNECT を使用して間接的に設定できる。プレーヤー コンテキスト値は、一度設定すると変更できない。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。 で宣言。


DPN_MSGID_DESTROY_PLAYER

プレーヤーがピアツーピア セッションまたはクライアント/サーバー セッションを離れると、Microsoft® DirectPlay® により DPN_MSGID_DESTROY_PLAYER メッセージが生成される。

DPNMSG_DESTROY_PLAYER

DPNMSG_DESTROY_PLAYER 構造体には、DPN_MSGID_DESTROY_PLAYER システム メッセージに関する情報が保持される。

typedef struct _DPNMSG_DESTROY_PLAYER{
    DWORD  dwSize;
    DPNID  dpnidPlayer;
    PVOID  pvPlayerContext;
    DWORD  dwReason;
} DPNMSG_DESTROY_PLAYER, *PDPNMSG_DESTROY_PLAYER;
dwSize
この構造体のサイズ。
dpnidPlayer
セッションから削除されるプレーヤーの DPNID。
pvPlayerContext
プレーヤーのコンテキスト値。
dwReason
プレーヤーが破棄された理由を示す次のいずれかのフラグ。
DPNDESTROYPLAYERREASON_NORMAL
プレーヤーは通常の理由で削除される。
DPNDESTROYPLAYERREASON_CONNECTIONLOST
接続が失われたため、プレーヤーは削除される。
DPNDESTROYPLAYERREASON_SESSIONTERMINATED
セッションが終了したため、プレーヤーは削除される。
DPNDESTROYPLAYERREASON_HOSTDESTROYEDPLAYER
ホストが IDirectPlay8Peer::DestroyPeer を呼び出したため、プレーヤーは削除される。

注意

クライアント/サーバー モードでは、サーバーだけがこのメッセージを受け取る。ピアツーピア モードでは、すべてのプレーヤーがこのメッセージを受け取る。

異なる複数のスレッドで DPN_MSGID_CREATE_PLAYER メッセージと DPN_MSGID_DESTROY_PLAYER メッセージを受け取ることがある。しかし、コールバック関数が DPN_MSGID_CREATE_PLAYER メッセージの受信から戻る前に DPN_MSGID_DESTROY_PLAYER メッセージを受け取ることはない。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


DPN_MSGID_DESTROY_GROUP

ピアツーピア セッションまたはクライアント/サーバー セッションからグループが破棄されると、Microsoft® DirectPlay® により DPN_MSGID_DESTROY_GROUP メッセージが生成される。

DPNMSG_DESTROY_GROUP

DPNMSG_DESTROY_GROUP 構造体には、DPN_MSGID_DESTROY_GROUP システム メッセージに関する情報が保持される。

typedef struct _DPNMSG_DESTROY_GROUP{
    DWORD  dwSize;
    DPNID  dpnidGroup;
    PVOID  pvGroupContext;
    DWORD  dwReason;
} DPNMSG_DESTROY_GROUP, *PDPNMSG_DESTROY_GROUP;
dwSize
この構造体のサイズ。
dpnidGroup
セッションから削除されるグループの DPNID。
pvGroupContext
グループのコンテキスト値。
dwReason
プレーヤーが破棄された理由を示す次のいずれかのフラグ。
DPNDESTROYGROUPREASON_SESSIONTERMINATED
セッションが終了したため、グループは削除される。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


DPN_MSGID_ENUM_HOSTS_QUERY

ピアまたはクライアントが利用可能なホストを列挙するとき、Microsoft® DirectPlay® は DPN_MSGID_ENUM_HOSTS_QUERY メッセージをホストのメッセージ ハンドラに送信する。

DPNMSG_ENUM_HOSTS_QUERY

DPNMSG_ENUM_HOSTS_QUERY 構造体には、DPN_MSGID_ENUM_HOSTS_QUERY システム メッセージに関する情報が保持される。

typedef struct _DPNMSG_ENUM_HOSTS_QUERY{
    DWORD                dwSize;
    IDirectPlay8Address* pAddressSender;
    IDirectPlay8Address* pAddressDevice;
    PVOID                pvReceivedData;
    DWORD                dwReceivedDataSize;
    DWORD                dwMaxResponseDataSize;
    PVOID                pvResponseData;
    DWORD                dwResponseDataSize;
    PVOID                pvResponseContext;
} DPNMSG_ENUM_HOSTS_QUERY, *PDPNMSG_ENUM_HOSTS_QUERY;
dwSize
この構造体のサイズ。
pAddressSender
送信者のアドレスを指定する IDirectPlay8Address インターフェイスへのポインタ。IDirectPlay8Address::AddRef を呼び出して、インターフェイスの参照カウントをインクリメントする必要がある。インターフェイスが不要になったときは、IDirectPlay8Address::Release を呼び出す。
pAddressDevice
デバイスのアドレスを指定する IDirectPlay8Address インターフェイスへのポインタ。IDirectPlay8Address::AddRef を呼び出して、インターフェイスの参照カウントをインクリメントする必要がある。インターフェイスが不要になったときは、IDirectPlay8Address::Release を呼び出す。
pvReceivedData
列挙から受け取るデータへのポインタ。
dwReceivedDataSize
pvReceivedData メンバが示すデータのサイズ。
dwMaxResponseDataSize
許可される列挙応答の最大サイズ。
pvResponseData
列挙からの応答データへのポインタ。このデータは、コールバック メッセージ ハンドラの範囲以上で有効でなければならない。スタック ベースは使用できない。Microsoft® DirectPlay® がこのバッファの処理を終えると、DPN_MSGID_RETURN_BUFFER メッセージが送られる。
dwResponseDataSize
pvResponseData メンバが指すデータ サイズ。
pvUserContext
応答コンテキスト値へのポインタ。この値は、関連する構造体の pvUserContext メンバとして、DPN_MSGID_RETURN_BUFFER メッセージと共にホストのメッセージ ハンドラに渡される。

注意

この照会に通常の応答をすると、DirectPlay はユーザーに DPN_MSGID_RETURN_BUFFER メッセージを一度送信し、バッファは不要になる。これで、バッファを安全に解放できる。

照会を拒否するには、S_OK 以外の値を返す。ただし照会を拒否すると、DirectPlay は応答を送らず、応答バッファを必要とせず、DPN_MSGID_RETURN_BUFFER メッセージを生成しない。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


DPN_MSGID_ENUM_HOSTS_RESPONSE

Microsoft® DirectPlay® は、DPN_MSGID_ENUM_HOSTS_RESPONSE メッセージをピアまたはクライアントのメッセージ ハンドラに送信し、列挙要求に対するホストの応答を伝える。

DPNMSG_ENUM_HOSTS_RESPONSE

DPNMSG_ENUM_HOSTS_RESPONSE 構造体には、DPN_MSGID_ENUM_HOSTS_RESPONSE システム メッセージに関する情報が保持される。

typedef struct _DPNMSG_ENUM_HOSTS_RESPONSE{
    DWORD                         dwSize;
    IDirectPlay8Address*          pAddressSender;
    IDirectPlay8Address*          pAddressDevice;
    const DPN_APPLICATION_DESC*   pApplicationDescription;
    PVOID                         pvResponseData;
    DWORD                         dwResponseDataSize;
    PVOID                         pvUserContext;
    DWORD                         dwRoundTripLatencyMS;
} DPNMSG_ENUM_HOSTS_RESPONSE, *PDPNMSG_ENUM_HOSTS_RESPONSE;
dwSize
この構造体のサイズ。
pAddressSender
列挙に応答するホストのアドレスを指定する IDirectPlay8Address インターフェイスへのポインタ。IDirectPlay8Address::AddRef を呼び出して、インターフェイスの参照カウントをインクリメントする必要がある。インターフェイスが不要になったときは、IDirectPlay8Address::Release を呼び出す。
pAddressDevice
デバイスのアドレスを指定する IDirectPlay8Address インターフェイスへのポインタ。IDirectPlay8Address::AddRef を呼び出して、インターフェイスの参照カウントをインクリメントする必要がある。インターフェイスが不要になったときは、IDirectPlay8Address::Release を呼び出す。
pApplicationDescription
アプリケーションの記述を保持する DPN_APPLICATION_DESC 構造体へのポインタ。
pvResponseData
列挙からの応答データへのポインタ。
dwResponseDataSize
pvResponseData メンバが指すデータ サイズ。
pvUserContext
ユーザーのコンテキスト値へのポインタ。この値は、IDirectPlay8Peer::EnumHosts または IDirectPlay8Client::EnumHosts に渡されるユーザー コンテキスト値と同じである。
dwRoundTripLatencyMS
ミリ秒単位で表現された遅延時間。

注意

データを格納するバッファがないため、このメッセージは DPN_MSGID_RETURN_BUFFER メッセージを生成しない。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


DPN_MSGID_GROUP_INFO

グループ データがピアツーピア セッションまたはクライアント/サーバー セッションの間に変更されると、Microsoft® DirectPlay® により DPN_MSGID_GROUP_INFO メッセージが生成される。

DPNMSG_GROUP_INFO

DPNMSG_GROUP_INFO 構造体には、DPN_MSGID_GROUP_INFO システム メッセージに関する情報が保持される。

typedef struct _DPNMSG_GROUP_INFO{
    DWORD  dwSize;
    DPNID  dpnidGroup;
    PVOID  pvGroupContext;
} DPNMSG_GROUP_INFO, *PDPNMSG_GROUP_INFO;
dwSize
この構造体のサイズ。
dpnidGroup
グループ情報用のグループの DPNID。
pvGroupContext
グループのコンテキスト値。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


DPN_MSGID_HOST_MIGRATE

DPN_APPLICATION_DESC 構造体に DPNSESSION_MIGRATE_HOST フラグが設定され、ホストが移行した場合、Microsoft® DirectPlay® により DPN_MSGID_HOST_MIGRATE メッセージが生成される。

DPNMSG_HOST_MIGRATE

DPNMSG_HOST_MIGRATE 構造体には、DPN_MSGID_HOST_MIGRATE システム メッセージに関する情報が保持される。

typedef struct _DPNMSG_HOST_MIGRATE{
    DWORD  dwSize;
    DPNID  dpnidNewHost;
    PVOID  pvPlayerContext;
} DPNMSG_HOST_MIGRATE, *PDPNMSG_HOST_MIGRATE;
dwSize
この構造体のサイズ。
dpnidNewHost
セッションを現在ホストしているプレーヤーの DPNID。
pvPlayerContext
プレーヤーのコンテキスト値。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


DPN_MSGID_INDICATE_CONNECT

プレーヤーがピアツーピア セッションまたはクライアント/サーバー セッションに接続しようとすると、Microsoft® DirectPlay® により DPN_MSGID_INDICATE_CONNECT メッセージが生成される。

DPNMSG_INDICATE_CONNECT

DPNMSG_INDICATE_CONNECT 構造体には、DPN_MSGID_INDICATE_CONNECT システム メッセージに関する情報が保持される。

ホスト アプリケーションはこの構造体を利用し、ユーザー データに基づいて接続の許可または拒否を行ったり、接続元アプリケーションに応答情報を提供できる。

typedef struct {
    DWORD     dwSize;
    PVOID     pvUserConnectData;
    DWORD     dwUserConnectDataSize;
    PVOID     pvReplyData;
    DWORD     dwReplyDataSize;
    PVOID     pvReplyContext;
    PVOID     pvPlayerContext;
    IDirectPlay8Address*  pAddressPlayer;
    IDirectPlay8Address*  pAddressDevice;
} DPNMSG_INDICATE_CONNECT, *PDPNMSG_INDICATE_CONNECT;
dwSize
この構造体のサイズ。
pvUserConnectData
接続元プレーヤーのデータ。
dwUserConnectDataSize
pvUserConnectData メンバに保持されたデータのサイズ (バイト単位)。
pvReplyData
接続応答データ。このデータは、コールバック メッセージ ハンドラとはかかわりなく有効でなければならない。Microsoft® DirectPlay® がこのバッファの処理を終えると、DPN_MSGID_RETURN_BUFFER メッセージが送られる。
dwReplyDataSize
pvReplyData メンバに保持されたデータのサイズ (バイト単位)。
pvReplyContext
pvReplyData のバッファ コンテキスト。この値は、関連する構造体の pvUserContext メンバとして、DPN_MSGID_RETURN_BUFFER メッセージと共にホストのメッセージ ハンドラに渡される。
pvPlayerContext
既定のプレーヤー コンテキスト。
pAddressPlayer
接続しているプレーヤーに対する IDirectPlay8Address インターフェイスへのポインタ。IDirectPlay8Address::AddRef を呼び出して、インターフェイスの参照カウントをインクリメントする必要がある。インターフェイスが不要になったときは、IDirectPlay8Address::Release を呼び出す。
pAddressDevice
接続の試みを受信するデバイスの IDirectPlay8Address インターフェイスへのポインタ。IDirectPlay8Address::AddRef を呼び出して、インターフェイスの参照カウントをインクリメントする必要がある。インターフェイスが不要になったときは、IDirectPlay8Address::Release を呼び出す。

注意

プレーヤーにセッションへの参加を許可するには、S_OK を返す。その他の戻り値は要求された接続を拒否する。接続が成功すると、接続を要求しているプレーヤーに送信されるhResultCode DPN_MSGID_CONNECT_COMPLETE メッセージに関連する構造体の hResultCode メンバに S_OK が設定される。接続が拒否されると、hResultCode には、このメッセージから返す値ではなく DPNERR_HOSTREJECTEDCONNECTION が 設定される。

DPN_MSGID_INDICATE_CONNECT 通知がホスト プレーヤーのメッセージ ハンドラに届いた場合、スレッドを返す前に pvPlayerContext を設定すると、プレーヤーのコンテキスト値は対応する DPN_MSGID_CREATE_PLAYER 通知に事前設定される。この機能を使用して、プレーヤー コンテキスト値を DPN_MSGID_CREATE_PLAYER に渡すことができる。

プレーヤー コンテキスト値を設定した場合、その値は、それ以降の DPN_MSGID_CREATE_PLAYER メッセージが処理されるまで固まらない。そのため、DPN_MSGID_CREATE_PLAYER を処理するときにこのプレーヤー コンテキスト値を修正できる。

サーバーが DPN_MSGID_INDICATE_CONNECT メッセージを処理した後、DPN_MSGID_CREATE_PLAYER を処理する前に、クライアントが接続を削除すると、サーバーは DPN_MSGID_INDICATED_CONNECT_ABORTED メッセージを受け取る。このメッセージを受け取った場合は、DPN_MSGID_INDICATE_CONNECT を処理する間に割り当てたメモリを解放すること。DPN_MSGID_CREATE_PLAYER が処理されたら、DPN_MSGID_DESTROY_PLAYER を処理するときに、このメモリを解放する必要がある。

pvUserConnectData のデータを指定すると、その後で、バッファを安全に解放できることを知らせる DPN_MSGID_RETURN_BUFFER メッセージを受け取る。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


DPN_MSGID_INDICATED_CONNECT_ABORTED

プレーヤーの接続がホスト上で示された後、DPN_MSGID_CREATE_PLAYER を使用してセッションに追加される前に削除されると、Microsoft® DirectPlay® により DPN_MSGID_INDICATED_CONNECT_ABORTED メッセージが生成される。

DPNMSG_INDICATED_CONNECT_ABORTED

DPNMSG_INDICATED_CONNECT_ABORTED 構造体には、DPN_MSGID_INDICATED_CONNECT_ABORTED システム メッセージに関する情報が保持される。

typedef struct {
    DWORD  dwSize;
    PVOID  pvPlayerContext;
} DPNMSG_INDICATED_CONNECT_ABORTED, *PDPNMSG_INDICATED_CONNECT_ABORTED;
dwSize
この構造体のサイズ。
pvPlayerContext
プレーヤーのコンテキスト値。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。 で宣言。


DPN_MSGID_PEER_INFO

ピア データがピアツーピア セッションの間に変更されると、Microsoft® DirectPlay® により DPN_MSGID_PEER_INFO メッセージが生成される。

DPNMSG_PEER_INFO

DPNMSG_PEER_INFO 構造体には、DPN_MSGID_PEER_INFO システム メッセージに関する情報が保持される。

typedef struct {
    DWORD  dwSize;
    DPNID  dpnidPeer;
    PVOID  pvPlayerContext;
} DPNMSG_PEER_INFO, *PDPNMSG_PEER_INFO;
dwSize
この構造体のサイズ。
dpnidPeer
ピア情報用のピアの DPNID。
pvPlayerContext
プレーヤーのコンテキスト値。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


DPN_MSGID_RECEIVE

メッセージが受信側によって処理されると、Microsoft® DirectPlay® により DPN_MSGID_RECEIVE メッセージが生成される。

DPNMSG_RECEIVE

DPNMSG_RECEIVE 構造体には、DPN_MSGID_RECEIVE システム メッセージに関する情報が保持される。

typedef struct {
    DWORD      dwSize;
    DPNID      dpnidSender;
    PVOID      pvPlayerContext;
    PBYTE      pReceiveData;
    DWORD      dwReceiveDataSize;
    DPNHANDLE  hBufferHandle;
} DPNMSG_RECEIVE, *PDPNMSG_RECEIVE;
dwSize
この構造体のサイズ。
dpnidSender
メッセージを送信したプレーヤーの DPNID。
pvPlayerContext
メッセージを送信したプレーヤーのプレーヤー コンテキスト値。
pReceiveData
メッセージ データ バッファへの PBYTE ポインタ。このバッファは、通常の場合、DPN_MSGID_RECEIVE メッセージがコールバック メッセージ ハンドラによって処理されている間のみ有効である。メッセージの総処理時間が大きくならないように、このデータをコピーしてメッセージを処理する。別の方法として、コールバック メッセージ ハンドラから DPNSUCCESS_PENDING を返すこともできる。この場合は、バッファの所有権がアプリケーションに移る。DPNSUCCESS_PENDING を返す場合、バッファが不要になったら、IDirectPlay8Peer::ReturnBuffer、IDirectPlay8Client::ReturnBuffer、または IDirectPlay8Server::ReturnBuffer を呼び出す必要がある。メソッドに、hBufferHandle メンバで受け取った値を渡して、バッファを識別する。ReturnBuffer の呼び出しに失敗した場合は、メモリ リークが発生する。
dwReceiveDataSize
pReceiveData メンバのデータのサイズ (バイト単位)。
hBufferHandle
pReceiveData メンバのバッファ ハンドル。DPNSUCCESS_PENDING を返した場合、この値を ReturnBuffer に渡して、Microsoft® DirectPlay® にバッファを解放するように通知する。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


DPN_MSGID_REMOVE_PLAYER_FROM_GROUP

ピアツーピア セッションまたはクライアント/サーバー セッションのグループからプレーヤーが削除されると、Microsoft® DirectPlay® により DPN_MSGID_REMOVE_PLAYER_FROM_GROUP メッセージが生成される。

DPNMSG_REMOVE_PLAYER_FROM_GROUP

DPNMSG_REMOVE_PLAYER_FROM_GROUP 構造体には、DPN_MSGID_REMOVE_PLAYER_FROM_GROUP システム メッセージに関する情報が保持される。

typedef struct _DPNMSG_REMOVE_PLAYER_FROM_GROUP{
    DWORD  dwSize;
    DPNID  dpnidGroup;
    PVOID  pvGroupContext;
    DPNID  dpnidPlayer;
    PVOID  pvPlayerContext;
} DPNMSG_REMOVE_PLAYER_FROM_GROUP, *PDPNMSG_REMOVE_PLAYER_FROM_GROUP;
dwSize
この構造体のサイズ。
dpnidGroup
プレーヤーが削除されたグループの DPNID。
pvGroupContext
グループのコンテキスト値。
dpnidPlayer
グループから削除されるプレーヤーの DPNID。
pvPlayerContext
プレーヤーのコンテキスト値。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


DPN_MSGID_RETURN_BUFFER

DirectPlay によるユーザー バッファの処理が終了すると、Microsoft® DirectPlay® により DPN_MSGID_RETURN_BUFFER メッセージが生成される。

DPNMSG_RETURN_BUFFER

DPNMSG_RETURN_BUFFER 構造体には、DPN_MSGID_RETURN_BUFFER システム メッセージに関する情報が保持される。

typedef struct {
    DWORD      dwSize;
    HRESULT    hResultCode;
    PVOID      pvBuffer;
    PVOID      pUserContext;
} DPNMSG_RETURN_BUFFER, *PDPNMSG_RETURN_BUFFER;
dwSize
この構造体のサイズ。
hResultCode
処理の値を返す。DPN_MSGID_ENUM_HOSTS_QUERY メッセージへの応答が大きすぎる場合は、DPNERR_ENUMRESPONSETOOLARGE が設定される。
pvBuffer
返されるバッファへのポインタ。
pUserContext
バッファに関連付けられたコンテキスト値。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


DPN_MSGID_SEND_COMPLETE

送信メッセージ要求が完了すると、Microsoft® DirectPlay® により DPN_MSGID_SEND_COMPLETE メッセージが生成される。

DPNMSG_SEND_COMPLETE

DPNMSG_SEND_COMPLETE 構造体には、DPN_MSGID_SEND_COMPLETE システム メッセージに関する情報が保持される。

typedef struct {
    DWORD      dwSize;
    DPNHANDLE  hAsyncOp;
    PVOID      pvUserContext;
    HRESULT    hResultCode;
    DWORD      dwSendTime;
} DPNMSG_SEND_COMPLETE, *PDPNMSG_SEND_COMPLETE;
dwSize
この構造体のサイズ。
hAsyncOp
非同期処理ハンドル。
pvUserContext
IDirectPlay8Client::Send メソッド、IDirectPlay8Peer::SendTo メソッド、および IDirectPlay8Server::SendTo メソッドで指定されるユーザー コンテキスト。
hResultCode
送信メッセージ要求の結果を示す HRESULT。
dwSendTime
送信呼び出しから終了するまでの合計時間 (ミリ秒単位)。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


DPN_MSGID_SERVER_INFO

サーバー データがクライアント/サーバー セッションの間に変更されると、Microsoft® DirectPlay® により DPN_MSGID_SERVER_INFO メッセージが生成される。

DPNMSG_SERVER_INFO

DPNMSG_SERVER_INFO 構造体には、DPN_MSGID_SERVER_INFO システム メッセージに関する情報が保持される。

typedef struct {
    DWORD  dwSize;
    DPNID  dpnidServer;
    PVOID  pvPlayerContext;
} DPNMSG_SERVER_INFO, *PDPNMSG_SERVER_INFO;
dwSize
この構造体のサイズ。
dpnidServer
サーバー情報用のサーバーの DPNID。
pvPlayerContext
プレーヤーのコンテキスト値。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


DPN_MSGID_TERMINATE_SESSION

セッションがホストによって終了されると、Microsoft® DirectPlay® により DPN_MSGID_TERMINATE_SESSION メッセージが生成される。

DPNMSG_TERMINATE_SESSION

DPNMSG_TERMINATE_SESSION 構造体には、DPN_MSGID_TERMINATE_SESSION システム メッセージに関する情報が保持される。

typedef struct {
    DWORD   dwSize;
    HRESULT hResultCode;
    PVOID   pvTerminateData;
    DWORD   dwTerminateDataSize;
} DPNMSG_TERMINATE_SESSION, *PDPNMSG_TERMINATE_SESSION;
dwSize
この構造体のサイズ。
hResultCode
セッションがどのように終了したかを指定する。セッションがピアツーピアで、ホストが IDirectPlay8Peer::TerminateSession を呼び出した場合、このメンバは DPNERR_HOSTTERMINATEDSESSION に設定される。ホストが Close を呼び出してセッションを終了した場合、またはホストが応答を停止した場合、 hResultCode は DPNERR_CONNECTIONLOST に設定される。
pvTerminateData
終了データ。hResultCode が DPNERR_HOSTTERMINATEDSESSION に設定された場合、pvTerminateData は、ホストが IDirectPlay8Peer::TerminateSession の pvTerminateData パラメータによって渡したデータ ブロックへのポインタ。
dwTerminateDataSize
pvTerminateData によってポイントされたデータ ブロックのサイズ。pvTerminateData が NULL に設定されている場合、このメンバはゼロになる。

注意

ホストの移行が許可されるピアツーピア ゲームでは、現在のホストが Close を呼び出すか応答を停止した場合、セッションは終了しない。その代わりに、ホストが移行し、ホスト以外のすべてのプレーヤーは、ホストのプレーヤーに関する DPN_MSGID_DESTROY_PLAYER メッセージと新しいホストに関する DPN_MSGID_HOST_MIGRATE メッセージを受け取る。ホストの移行を行わないためには、ホストが IDirectPlay8Peer::TerminateSession を呼び出してセッションをシャットダウンしなければならない。ホストがこの方法でセッションを終了すると、すべてのプレーヤーが、hResultCode を DPNERR_HOSTTERMINATEDSESSION に設定した DPN_MSGID_TERMINATE_SESSION メッセージを受け取る。セッションは終了し、プレーヤー全員に対する DPN_MSGID_DESTROY_PLAYER メッセージが生成される。

ホストの移行を許可しないピアツーピア ゲームでは、ホストが IDirectPlay8Peer::Close を呼び出すか応答を停止した場合、セッションは終了する。その場合、hResultCode を DPNERR_CONNECTIONLOST に設定した DPN_MSGID_TERMINATE_SESSION がすべてのプレーヤーに送信される。セッションは終了し、プレーヤー全員に対する DPN_MSGID_DESTROY_PLAYER メッセージが生成される。

クライアント/サーバー ゲームでも、ホストが IDirectPlay8Server::Close を呼び出すか応答を停止した場合、セッションは終了する。その場合、hResultCode を DPNERR_CONNECTIONLOST に設定した DPN_MSGID_TERMINATE_SESSION が、接続しているすべてのクライアントに送信される。DPN_MSGID_DESTROY_PLAYER メッセージはクライアントには送信されない。サーバーが IDirectPlay8Server::Close を呼び出して接続を解除すると、サーバーは、サーバー自身を含むすべてのプレーヤーに関する DPN_MSGID_DESTROY_PLAYER メッセージを受け取る。それ以外の場合、サーバーはクライアントのプレーヤーに関する DPN_MSGID_DESTROY_PLAYER だけを受け取る。

注 DPN_MSGID_TERMINATE_SESSION メッセージは通常 DPN_MSGID_DESTROY_PLAYER メッセージより先に到着する。ただし、到着の順序は保証されていない。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


DVMSGID_CONNECTRESULT

IDirectPlayVoiceClient::Connect メソッドの呼び出しにより生成された接続要求が完了すると、Microsoft® DirectPlay® により DVMSGID_CONNECTRESULT メッセージが生成される。Connect メソッドが非同期に呼び出された場合にのみ、このメッセージは送信される。

DVMSG_CONNECTRESULT

DVMSG_CONNECTRESULT 構造体には、DVMSGID_CONNECTRESULT システム メッセージに関する情報が保持される。

typedef struct {
    DWORD    dwSize;
    HRESULT  hrResult;
} DVMSG_CONNECTRESULT, *LPDVMSG_CONNECTRESULT, *PDVMSG_CONNECTRESULT;
dwSize
DVMSG_CONNECTRESULT メッセージ構造体のサイズ。
hrResult
接続試行の結果。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。


DVMSGID_CREATEVOICEPLAYER

新しいプレーヤーが音声セッションに参加すると、Microsoft® DirectPlay® Voice により DVMSGID_CREATEVOICEPLAYER メッセージが生成される。

クライアントは、音声セッションに接続すると、音声セッションのプレーヤーごとにメッセージの 1 つを受信する。これらのメッセージは、ピアツーピアの音声セッションのクライアントにのみ送信される。

プレーヤーが音声セッションに参加すると、ホストはこのメッセージを受信する。

プレーヤーは、IDirectPlayVoiceClient::Connect を呼び出すまで、音声セッションに参加しない。したがって、プレーヤーがトランスポート セッションには参加し、音声セッションには参加していないことも可能である。

DVMSG_CREATEVOICEPLAYER

DVMSG_CREATEVOICEPLAYER 構造体には、DVMSGID_CREATEVOICEPLAYER システム メッセージに関する情報が保持される。

typedef struct {
    DWORD  dwSize;
    DVID   dvidPlayer;
    DWORD  dwFlags;
    PVOID  pvPlayerContext;
} DVMSG_CREATEVOICEPLAYER, *LPDVMSG_CREATEVOICEPLAYER, *PDVMSG_CREATEVOICEPLAYER;
dwSize
このメッセージ構造体のサイズ。
dvidPlayer
接続したプレーヤーの DVID。
dwFlags
プレーヤーに関する情報を指定するフラグ。
DVPLAYERCAPS_HALFDUPLEX
指定したプレーヤーが半二重モードで動作している。プレーヤーは音声の送信はできず、受信しかできない。
DVPLAYERCAPS_LOCAL
プレーヤーはローカル プレーヤーである。
pvPlayerContext
音声セッションのプレーヤーのプレーヤー コンテキスト値。この値は、このメッセージが受信されたときに、このパラメータによって設定される。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。


DVMSGID_DELETEVOICEPLAYER

クライアントの場合、プレーヤーが音声セッションを終了すると、Microsoft® DirectPlay® Voice により DVMSGID_DELETEVOICEPLAYER メッセージが生成される。このメッセージは、ピアツーピアの音声セッションのクライアントのみ利用できる。

ホストの場合、プレーヤーが音声セッションを終了すると、Microsoft® DirectPlay® Voice により DVMSGID_DELETEVOICEPLAYER メッセージが生成される。

プレーヤーが音声セッションを離れるには、IDirectPlayVoiceClient::Disconnect を呼び出すか、トランスポート セッションから接続解除する必要がある。したがって、クライアントがトランスポート セッションには参加し、音声セッションには参加しないことも可能である。

DVMSG_DELETEVOICEPLAYER

DVMSG_DELETEVOICEPLAYER 構造体には、DVMSGID_DELETEVOICEPLAYER システム メッセージに関する情報が保持される。

typedef struct {
    DWORD  dwSize;
    DVID   dvidPlayer;
    PVOID  pvPlayerContext;
} DVMSG_DELETEVOICEPLAYER, *LPDVMSG_DELETEVOICEPLAYER, *PDVMSG_DELETEVOICEPLAYER;
dwSize
DVMSG_DELETEVOICEPLAYER メッセージ構造体のサイズ。
dvidPlayer
接続解除したプレーヤーの DVID。
pvPlayerContext
プレーヤーに対して設定されたコンテキスト値へのポインタ。この値は、DVMSG_CREATEVOICEPLAYER メッセージ構造体の pvPlayerContext メンバによって設定される。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。


DVMSGID_DISCONNECTRESULT

IDirectPlayVoiceClient::Disconnect メソッドの呼び出しにより生成された接続解除要求が完了すると、Microsoft® DirectPlay® Voice により DVMSGID_DISCONNECTRESULT メッセージが生成される。Disconnect メソッドが非同期に呼び出された場合のみ、このメッセージは送信される。

DVMSG_DISCONNECTRESULT

DVMSG_DISCONNECTRESULT 構造体には、DVMSGID_DISCONNECTRESULT システム メッセージに関する情報が保持される。

typedef struct {
    DWORD   dwSize;
    HRESULT hrResult;
} DVMSG_DISCONNECTRESULT, *LPDVMSG_DISCONNECTRESULT, *PDVMSG_DISCONNECTRESULT;
dwSize
DVMSG_DISCONNECTRESULT メッセージ構造体のサイズ。
hrResult
接続解除要求の結果。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。


DVMSGID_GAINFOCUS

オーディオのキャプチャを開始したことを知らせるため、DVMSGID_GAINFOCUS メッセージが送信される。キャプチャのフォーカスを失ったアプリケーションがフォーカスを回復すると、このメッセージが送信される。このメッセージに関連付けられたデータはない。オーディオ キャプチャの詳細については、Microsoft® DirectSound® のドキュメントを参照すること。


DVMSGID_HOSTMIGRATED

音声ホストが変更されると、Microsoft® DirectPlay® Voice により DVMSGID_HOSTMIGRATED メッセージが生成される。

DVMSG_HOSTMIGRATED

DVMSG_HOSTMIGRATED 構造体には、DVMSGID_HOSTMIGRATED システム メッセージに関する情報が保持される。

typedef struct {
    DWORD                   dwSize;
    DVID                    dvidNewHostID;
    LPDIRECTPLAYVOICESERVER pdvServerInterface;
} DVMSG_HOSTMIGRATED, *LPDVMSG_HOSTMIGRATED, *PDVMSG_HOSTMIGRATED;
dwSize
DVMSG_HOSTMIGRATED メッセージ構造体のサイズ。
dvidNewHostID
新しいホストの DVID。
pdvServerInterface
ローカル クライアントが新しい音声セッション ホストになった場合、このメンバは新たに作成された IDirectPlayVoiceServer オブジェクトを示す。ローカル クライアントは、このオブジェクトを使用してホスト サービスを提供できる。ローカル クライアントが新しいホストではない場合、このメンバは NULL になる。このパラメータが IDirectPlayVoiceServer インターフェイスをポイントする場合、IDirectPlayVoiceServer::AddRef を呼び出して、インターフェイスの参照カウントをインクリメントする必要がある。インターフェイスが不要になったときは、IDirectPlayVoiceServer::Release を呼び出す。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。


DVMSGID_INPUTLEVEL

マイクからの入力レベルをユーザーに知らせるため、Microsoft® DirectPlay® Voice により DVMSGID_INPUTLEVEL メッセージが生成される。通知の期間は、DVCLIENTCONFIG 構造体の dwNotifyPeriod メンバによって設定される。通知の期間が 0 に設定された場合、このメッセージは送信されない。また、クライアントが半二重モードで動作している場合、このメッセージは利用できない。

DVMSG_INPUTLEVEL

DVMSG_INPUTLEVEL 構造体には、DVMSGID_INPUTLEVEL システム メッセージに関する情報が保持される。

typedef struct {
    DWORD dwSize;
    DWORD dwPeakLevel;
    LONG  lRecordVolume;
    PVOID pvLocalPlayerContext;
} DVMSG_INPUTLEVEL, *LPDVMSG_INPUTLEVEL, *PDVMSG_INPUTLEVEL;
dwSize
DVMSG_INPUTLEVEL メッセージ構造体のサイズ。
dwPeakLevel
現在のフレームのピーク レベルを表す整数。オーディオ ストリームの約 1/10 秒に相当する。一般に現在のフレームはリアルタイムよりも 50 ～ 200 ミリ秒遅れる。この値は 0 ～ 99 の範囲になる。0 は完全に無音、99 は可能な最大入力レベルを表す。
lRecordVolume
クライアントの現在の録音ボリューム。値の範囲は -10,000 ～ 0。このメンバは、自動ゲイン制御がアクティブなときでも使用できる。
pvLocalPlayerContext
ローカル プレーヤーに対して設定されたコンテキスト値へのポインタ。この値は、DVMSG_CREATEVOICEPLAYER メッセージ構造体の pvPlayerContext メンバによって設定される。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。


DVMSGID_LOCALHOSTSETUP

ホストの移行の間にローカル クライアントが新しい音声ホストとして選択されると、DVMSGID_LOCALHOSTSETUP メッセージが送信される。メッセージは DVMSGID_HOSTMIGRATED メッセージの前に送信され、新しいホスト オブジェクトを作成するときに使用するコールバック関数とコンテキスト値を設定する機会を開発者に与える。開発者がいずれの値も設定しない場合、新しいサーバー インターフェイスはコールバック関数を持たない。アプリケーションがこのメッセージの処理から戻ると、DVMSGID_HOSTMIGRATED メッセージを受け取る。新しいメッセージには次の構造体が関連付けられている。この構造体は、メッセージ ハンドラの void * フィールドに渡される。

DVMSG_LOCALHOSTSETUP

DVMSG_LOCALHOSTSETUP 構造体には、DVMSGID_LOCALHOSTSETUP システム メッセージに関する情報が保持される。

typedef struct {
    DWORD dwSize;
    PVOID pvContext;
    PDVMESSAGEHANDLER pMessageHandler;
} DVMSG_LOCALHOSTSETUP, *LPDVMSG_LOCALHOSTSETUP, *PDVMSG_LOCALHOSTSETUP;
dwSize
DVMSG_LOCALHOSTSETUP メッセージ構造体のサイズ。
pvContext
新しいサーバーに対して設定するコンテキスト値を設定する。
pMessageHandler
新しいサーバーに使用するコールバック関数を設定する。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。 で宣言。


DVMSGID_LOSTFOCUS

オーディオのキャプチャを停止したことを知らせるため、DVMSGID_LOSTFOCUS メッセージが送信される。キャプチャのフォーカスを持っているアプリケーションから別のアプリケーションにフォーカスが移ると、このメッセージが送信される。このメッセージに関連付けられたデータはない。オーディオ キャプチャの詳細については、Microsoft® DirectSound® の説明を参照すること。


DVMSGID_OUTPUTLEVEL

再生の出力レベルをユーザーに知らせるため、Microsoft® DirectPlay® Voice により DVMSGID_OUTPUTLEVEL メッセージが生成される。通知の期間は、DVCLIENTCONFIG 構造体の dwNotifyPeriod メンバによって設定される。通知の期間が 0 に設定された場合、このメッセージは送信されない。

DVMSG_OUTPUTLEVEL

DVMSG_OUTPUTLEVEL 構造体には、DVMSGID_OUTPUTLEVEL システム メッセージに関する情報が保持される。

typedef struct {
    DWORD  dwSize;
    DWORD  dwPeakLevel;
    LONG   lOutputVolume;
    PVOID  pvLocalPlayerContext;
} DVMSG_OUTPUTLEVEL, *LPDVMSG_OUTPUTLEVEL, *PDVMSG_OUTPUTLEVEL;
dwSize
DVMSG_OUTPUTLEVEL メッセージ構造体のサイズ。
dwPeakLevel
再生の現在の出力レベルを表す整数。この値は 0 ～ 99 の範囲になる。0 は完全に無音、99 は可能な最大入力レベルを表す。
lOutputVolume
クライアントの現在の再生ボリューム。
pvLocalPlayerContext
ローカル プレーヤーに対して設定されたコンテキスト値へのポインタ。この値は、DVMSG_CREATEVOICEPLAYER メッセージ構造体の pvPlayerContext メンバによって設定される。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。


DVMSGID_PLAYEROUTPUTLEVEL

個々のプレーヤーの音声ストリームの出力レベルをユーザーに知らせるため、Microsoft® DirectPlay® Voice により DVMSGID_PLAYEROUTPUTLEVEL メッセージが定期的に生成される。個々のプレーヤーに音声が再生されている間、このメッセージが生成される。複数のプレーヤーの音声が再生される場合、各通知期間で、プレーヤーの音声ごとに 1 つのメッセージが送信される。

通知の期間は、DVCLIENTCONFIG 構造体の dwNotifyPeriod メンバによって設定される。通知の期間が 0 に設定された場合、このメッセージは送信されない。

DVMSG_PLAYEROUTPUTLEVEL

DVMSG_PLAYEROUTPUTLEVEL 構造体には、DVMSGID_PLAYEROUTPUTLEVEL システム メッセージに関する情報が保持される。

typedef struct {
    DWORD  dwSize;
    DVID   dvidSourcePlayerID;
    DWORD  dwPeakLevel;
    PVOID  pvPlayerContext;
} DVMSG_PLAYEROUTPUTLEVEL, *LPDVMSG_PLAYEROUTPUTLEVEL, *PDVMSG_PLAYEROUTPUTLEVEL;
dwSize
DVMSG_PLAYEROUTPUTLEVEL メッセージ構造体のサイズ。
dvidSourcePlayerID
再生される音声のプレーヤーの DVID。
dwPeakLevel
プレーヤーの音声ストリームの現在の出力レベルを表す整数。この値は 0 ～ 99 の範囲になる。0 は完全に無音、99 は可能な最大入力レベルを表す。
pvPlayerContext
プレーヤーに対して設定されたコンテキスト値へのポインタ。この値は、DVMSG_CREATEVOICEPLAYER メッセージ構造体の pvPlayerContext メンバによって設定される。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。


DVMSGID_PLAYERVOICESTART

受信オーディオ ストリームが再生を開始すると、Microsoft® DirectPlay® Voice により DVMSGID_PLAYERVOICESTART メッセージが生成される。

DVMSG_PLAYERVOICESTART

DVMSG_PLAYERVOICESTART 構造体には、DVMSGID_PLAYERVOICESTART システム メッセージに関する情報が保持される。

typedef struct {
    DWORD  dwSize;
    DVID   dvidSourcePlayerID;
    PVOID  pvPlayerContext;
} DVMSG_PLAYERVOICESTART, *LPDVMSG_PLAYERVOICESTART, *PDVMSG_PLAYERVOICESTART;
dwSize
DVMSG_PLAYERVOICESTART メッセージ構造体のサイズ。
dvidSourcePlayerID
音声転送が開始されるプレーヤーの DVID。
pvPlayerContext
プレーヤーに対して設定されたコンテキスト値へのポインタ。この値は、DVMSG_CREATEVOICEPLAYER メッセージ構造体の pvPlayerContext メンバによって設定される。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。


DVMSGID_PLAYERVOICESTOP

受信オーディオ ストリームが停止すると、Microsoft® DirectPlay® Voice により DVMSGID_PLAYERVOICESTOP メッセージが生成される。

DVMSG_PLAYERVOICESTOP

DVMSG_PLAYERVOICESTOP 構造体には、DVMSGID_PLAYERVOICESTOP システム メッセージに関する情報が保持される。

typedef struct {
    DWORD  dwSize;
    DVID   dvidSourcePlayerID;
    PVOID  pvPlayerContext;
} DVMSG_PLAYERVOICESTOP, *LPDVMSG_PLAYERVOICESTOP, *PDVMSG_PLAYERVOICESTOP;
dwSize
DVMSG_PLAYERVOICESTOP メッセージ構造体のサイズ。
dvidSourcePlayerID
音声転送が開始されるプレーヤーの DVID。
pvPlayerContext
プレーヤーに対して設定されたコンテキスト値へのポインタ。この値は、DVMSG_CREATEVOICEPLAYER メッセージ構造体の pvPlayerContext メンバによって設定される。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。


DVMSGID_RECORDSTART

ローカル クライアントのオーディオ入力が開始されると、Microsoft® DirectPlay® Voice により DVMSGID_RECORDSTART メッセージが生成される。音声をアクティブにする感知レベルを超えるか、プッシュツートーク モードで有効なターゲットが指定された場合、オーディオ入力は開始される。

DVMSG_RECORDSTART

DVMSG_RECORDSTART 構造体には、DVMSGID_RECORDSTART システム メッセージに関する情報が保持される。

typedef struct {
    DWORD  dwSize;
    DWORD  dwPeakLevel;
    PVOID pvLocalPlayerContext;
} DVMSG_RECORDSTART, *LPDVMSG_RECORDSTART, *PDVMSG_RECORDSTART;
dwSize
DVMSG_RECORDSTART メッセージ構造体のサイズ。
dwPeakLevel
送信を開始する音声をアクティブにするレベル。プッシュツートーク モードでは、この値は 0 である。
pvLocalPlayerContext
ローカル プレーヤーに対して設定されたコンテキスト値へのポインタ。この値は、DVMSG_CREATEVOICEPLAYER メッセージ構造体の pvPlayerContext メンバによって設定される。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。


DVMSGID_RECORDSTOP

ローカル クライアントのオーディオ入力が停止すると、Microsoft® DirectPlay® Voice により DVMSGID_RECORDSTOP メッセージが生成される。音声をアクティブにするレベルに達しないか、プッシュツートーク モードでターゲットが削除された場合、オーディオ入力は停止する。

DVMSG_RECORDSTOP

DVMSG_RECORDSTOP 構造体には、DVMSGID_RECORDSTOP システム メッセージに関する情報が保持される。

typedef struct {
    DWORD dwSize;
    DWORD dwPeakLevel;
    PVOID pvLocalPlayerContext;
} DVMSG_RECORDSTOP, *LPDVMSG_RECORDSTOP, *PDVMSG_RECORDSTOP;
dwSize
DVMSG_RECORDSTOP メッセージ構造体のサイズ。
dwPeakLevel
送信を停止する音声をアクティブにするレベル。プッシュツートーク モードでは、この値は 0 である。
pvLocalPlayerContext
ローカル プレーヤーに対して設定されたコンテキスト値へのポインタ。この値は、DVMSG_CREATEVOICEPLAYER メッセージ構造体の pvPlayerContext メンバによって設定される。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。


DVMSGID_SESSIONLOST

音声セッションが終了すると、Microsoft® DirectPlay® Voice により DVMSGID_SESSIONLOST メッセージが生成される。

DVMSG_SESSIONLOST

DVMSG_SESSIONLOST 構造体には、DVMSGID_SESSIONLOST システム メッセージに関する情報が保持される。

typedef struct {
    DWORD   dwSize;
    HRESULT hrResult;
} DVMSG_SESSIONLOST, *LPDVMSG_SESSIONLOST, *PDVMSG_SESSIONLOST;
dwSize
DVMSG_SESSIONLOST メッセージ構造体のサイズ。
hrResult
セッションが終了した理由を示す HRESULT。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。


DVMSGID_SETTARGETS

IDirectPlayVoiceClient::SetTransmitTargets メソッドまたは IDirectPlayVoiceServer::SetTransmitTargets メソッドが呼び出されると、Microsoft® DirectPlay® Voice により DVMSGID_SETTARGETS メッセージが生成される。

DVMSG_SETTARGETS

DVMSG_SETTARGETS 構造体には、DVMSGID_SETTARGETS システム メッセージに関する情報が保持される。

typedef struct {
    DWORD dwSize;
    DWORD dwNumTargets;
    PDVID pdvidTargets;
} DVMSG_SETTARGETS, *LPDVMSG_SETTARGETS, *PDVMSG_SETTARGETS;
dwSize
DVMSG_SETTARGETS メッセージ構造体のサイズ。
dwNumTargets
pdvidTargets メンバに保持される DVID の数。
pdvidTargets
セット ターゲットを指定する DVID の配列。ターゲットがない場合、NULL にも設定できる。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice.h で宣言。


構造体

Microsoft® DirectPlay® の構造体を次に示す。

  • DPL_APPLICATION_INFO
  • DPL_CONNECT_INFO
  • DPL_CONNECTION_SETTINGS
  • DPL_PROGRAM_DESC
  • DPN_APPLICATION_DESC
  • DPN_BUFFER_DESC
  • DPN_CAPS
  • DPN_CONNECTION_INFO
  • DPN_GROUP_INFO
  • DPN_PLAYER_INFO
  • DPN_SECURITY_CREDENTIALS
  • DPN_SECURITY_DESC
  • DPN_SERVICE_PROVIDER_INFO
  • DPN_SP_CAPS
  • DVCAPS
  • DVCLIENTCONFIG
  • DVCOMPRESSIONINFO
  • DVSESSIONDESC
  • DVSOUNDDEVICECONFIG


DPL_APPLICATION_INFO

IDirectPlay8LobbyClient::EnumLocalPrograms メソッドの pEnumData パラメータで使用され、ロビー アプリケーションを記述する。

typedef struct _DPL_APPLICATION_INFO {
    GUID  guidApplication;
    PWSTR pwszApplicationName;
    DWORD dwNumRunning;
    DWORD dwNumWaiting;
    DWORD dwFlags;
} DPL_APPLICATION_INFO,  *PDPL_APPLICATION_INFO;

メンバ

guidApplication
ロビー アプリケーションを指定する GUID 型の変数。
pwszApplicationName
ロビー アプリケーションの名前を保持する WSTR 型の変数へのポインタ。
dwNumRunning
アプリケーションのインスタンス数。
dwNumWaiting
ロビー アプリケーションへの接続を待つクライアント数。
dwFlags
予約済み。0 に設定しておく。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplobby8.h で宣言。


DPL_CONNECT_INFO

IDirectPlay8LobbyClient::ConnectApplication メソッドで使用し、ロビー アプリケーションに接続するときにロビー クライアントの接続情報を指定する。

typedef struct _DPL_CONNECT_INFO {
    DWORD dwSize;
    DWORD dwFlags;
    GUID  guidApplication;
    PDPL_CONNECTION_SETTINGS pdplConnectionSettings;
    PVOID pvLobbyConnectData;
    DWORD dwLobbyConnectDataSize;
} DPL_CONNECT_INFO,  *PDPL_CONNECT_INFO;

メンバ

dwSize
DPL_CONNECT_INFO 構造体のサイズ。アプリケーションは、この構造体を使用する前に、まずこのメンバを設定する必要がある。
dwFlags
接続動作を決定する次のいずれかのフラグ。
DPLCONNECT_LAUNCHNEW
アプリケーションの新しいインスタンスを起動する。
DPLCONNECT_LAUNCHNOTFOUND
起動設定を提供できるアプリケーションが実行されていない場合にのみ、アプリケーションの新しいインスタンスを起動する。
guidApplication
アプリケーションを指定する GUID 型の変数。
pdplConnectionSettings
接続が確立したときに接続に関連付ける接続設定を保持する。
pvLobbyConnectData
ロビー アプリケーションに渡された接続データへのポインタ。
dwLobbyConnectDataSize
pvLobbyConnectData メンバのデータ バッファのサイズを指定する DWORD 型の変数。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplobby8.h で宣言。 で宣言。


DPL_CONNECTION_SETTINGS

接続に関連付ける設定を指定するために使用する。接続設定には、Microsoft® DirectPlay® オブジェクトの初期化と接続またはホストを行うために必要な、すべての情報が含まれる。

typedef struct _DPL_CONNECTION_SETTINGS {
    DWORD                   dwSize;
    DWORD                   dwFlags;
    DPN_APPLICATION_DESC    dpnAppDesc;
    IDirectPlay8Address*    pdp8HostAddress;
    IDirectPlay8Address**   ppdp8DeviceAddresses;
    DWORD                   cNumDeviceAddresses;
    PWSTR                   pwszPlayerName
} DPL_CONNECTION_SETTINGS, *PDPL_CONNECTION_SETTINGS;

メンバ

dwSize
DPL_CONNECTION_SETTINGS 構造体のサイズ。アプリケーションは、この構造体を使用する前に、このメンバを sizeof( DPL_CONNECTION_SETTINGS ) に設定する必要がある。
dwFlags
次のフラグの組み合わせ。
DPLCONNECTSETTINGS_CLIENTSERVER
アプリケーションはクライアント/サーバー セッションで起動する必要がある。
DPLCONNECTSETTINGS_HOST
アプリケーションはセッションをホストする必要がある。
dpnAppDesc
DirectPlay が初期化されるときに、Connect または Host 呼び出しに渡すアプリケーション記述へのポインタ。
pdp8HostAddress
DPLCONNECTSETTINGS_HOST が指定されていない場合、これは、クライアントが接続しなければならないセッションのアドレスである。DPLCONNECTSETTINGS_HOST を指定した場合は、このメンバは NULL でなければならない。
ppdp8DeviceAddresses
この構造体にはデバイス アドレスへのポインタの配列が保持される。DPLCONNECTSETTINGS_HOST を指定した場合、このメンバにはホストが聴取するアドレスが保持される。DPLCONNECTSETTINGS_HOST を指定しない場合、このメンバには接続時にクライアントが使用するデバイスのアドレスが保持される。
cNumDeviceAddresses
ppdp8DeviceAddresses メンバに指定されているアドレスの数。
pwszPlayerName
起動時に DirectPlay オブジェクトに使用させたいプレーヤー名を渡すことができる。このメンバは NULL に指定できる。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplobby8.h で宣言。


DPL_PROGRAM_DESC

Microsoft® DirectPlay® ロビー対応アプリケーションを記述する。

typedef struct _DPL_PROGRAM_DESC {
    DWORD dwSize;
    DWORD dwFlags;
    GUID  guidApplication;
    PWSTR pwszApplicationName;
    PWSTR pwszCommandLine;
    PWSTR pwszCurrentDirectory;
    PWSTR pwszDescription;
    PWSTR pwszExecutableFilename;
    PWSTR pwszExecutablePath;
    PWSTR pwszLauncherFilename;
    PWSTR pwszLauncherPath;
} DPL_PROGRAM_DESC, *PDPL_PROGRAM_DESC;

メンバ

dwSize
DPL_PROGRAM_DESC 構造体のサイズ。アプリケーションは、この構造体を使用する前に、まずこのメンバを設定する必要がある。
dwFlags
予約済み。0 に設定しておく。
guidApplication
アプリケーションを指定する GUID 型の変数。
pwszApplicationName
アプリケーション名へのポインタ。
pwszCommandLine
コマンド ライン引数へのポインタ。
pwszCurrentDirectory
アプリケーションの作業ディレクトリとして設定しなければならないディレクトリへのポインタ。
pwszDescription
アプリケーションの記述へのポインタ。
pwszExecutableFilename
アプリケーションの実行可能ファイル名へのポインタ。
pwszExecutablePath
アプリケーションの実行可能ファイルのパスへのポインタ。
pwszLauncherFilename
ランチャの実行可能ファイル名へのポインタ。
pwszLauncherPath
ランチャの実行可能ファイルのパスへのポインタ。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplobby8.h で宣言。


DPN_APPLICATION_DESC

Microsoft® DirectPlay® アプリケーションの設定を記述する。

typedef struct _DPN_APPLICATION_DESC{
    DWORD  dwSize;
    DWORD  dwFlags;
    GUID   guidInstance;
    GUID   guidApplication;
    DWORD  dwMaxPlayers;
    DWORD  dwCurrentPlayers;
    WCHAR* pwszSessionName;
    WCHAR* pwszPassword;
    PVOID  pvReservedData;
    DWORD  dwReservedDataSize;
    PVOID  pvApplicationReservedData;
    DWORD  dwApplicationReservedDataSize;
} DPN_APPLICATION_DESC, *PDPN_APPLICATION_DESC;

メンバ

dwSize
DPN_APPLICATION_DESC 構造体のサイズ。アプリケーションは、この構造体を使用する前に、まずこのメンバを設定する必要がある。
dwFlags
アプリケーションの動作を記述する次のいずれかのフラグ。
DPNSESSION_CLIENT_SERVER
このタイプのセッションはクライアント/サーバーである。このフラグを DPNSESSION_MIGRATE_HOST と組み合わせることはできない。
DPNSESSION_MIGRATE_HOST
ピアツーピア セッションで使用され、ホストの移行を可能にする。このフラグを DPNSESSION_CLIENT_SERVER と組み合わせることはできない。
DPNSESSION_NODPNSVR
DPNSVR からホストに列挙を転送しない。詳細については、「DirectPlay DPNSVR アプリケーションの使い方」を参照すること。
DPNSESSION_REQUIREPASSWORD
セッションをパスワードにより保護する。このフラグを設定した場合、pwszPassword に有効な文字列を指定する必要がある。
guidInstance
起動時に DirectPlay により生成され、このアプリケーションのインスタンスを表すグローバル ユニーク識別子 (GUID)。このメンバは、IDirectPlay8Peer、IDirectPlay8Client、および IDirectPlay8Server インターフェイスで公開される GetApplicationDesc メソッドを呼び出すときの [out] パラメータである。また、IDirectPlay8Peer および IDirectPlay8Client インターフェイスで公開される Connect メソッドを呼び出すときの、オプションの [in] パラメータである。IDirectPlay8Server および IDirectPlay8Peer インターフェイスで公開される SetApplicationDesc メソッドを呼び出すときは、NULL に設定する必要がある。IDirectPlay8Server::Host または IDirectPlay8Peer::Host メソッドを呼び出してこの GUID を取得することはできない。GUID は GetApplicationDesc メソッドを呼び出して取得しなければならない。
guidApplication
アプリケーション GUID。
dwMaxPlayers
セッションで使用可能なプレーヤーの最大数を指定する DWORD 型の変数。プレーヤーの数を無制限にするときは、このメンバを 0 に設定する。
dwCurrentPlayers
セッションに現在接続されているプレーヤーの数を指定する DWORD 型の変数。このメンバは、IDirectPlay8Peer、IDirectPlay8Client、および IDirectPlay8Server で公開される GetApplicationDescription メソッドによってのみ設定される [out] パラメータである。
pwszSessionName
セッションの Unicode™ 名を指定する WCHAR 型の変数へのポインタ。このメンバは、情報を伝えるだけの目的でホストまたはサーバーによって設定される。クライアントがこの名前を使用してホストまたはサーバーに接続することはできない。
pwszPassword
セッションへの接続に必要な Unicode パスワードを指定する WCHAR 型の変数へのポインタ。dwFlags メンバに DPNSESSION_REQUIREPASSWORD が設定されていない場合、この値は NULL にする必要がある。
pvReservedData
DirectPlay の予約済みデータへのポインタ。アプリケーションはこの値を変更してはならない。
dwReservedDataSize
pvReservedData メンバに保持されているデータのサイズを指定する DWORD 型の変数。アプリケーションはこの値を変更してはならない。
pvApplicationReservedData
アプリケーション固有の予約済みデータへのポインタ。この値はオプションであり、NULL に設定できる。
dwApplicationReservedDataSize
pvApplicationReservedData メンバのデータのサイズを指定する DWORD 型の変数。この値はオプションであり、NULL に設定できる。

注意

dwMaxPlayers、pvApplicationReservedData、dwApplicationReservedDataSize、pwszPassword、および pwszSessionName メンバは、IDirectPlay8Server および IDirectPlay8Peer インターフェイスで公開される Host または SetApplicationDesc メソッドを呼び出すときに設定できる。セッション中のプレーヤの現在の数より小さな値で dwMaxPlayers パラメータを設定することはできない。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


DPN_BUFFER_DESC

汎用バッファ情報に関して Microsoft® DirectPlay® により使用される。

typedef struct _BUFFERDESC{
    DWORD  dwBufferSize;
    BYTE*  pBufferData;
} BUFFERDESC, DPN_BUFFER_DESC;

メンバ

dwBufferSize
pBufferData メンバのデータ バッファのサイズを指定する DWORD 型の変数。
pBufferData
バッファのデータを保持する BYTE 型の変数へのポインタ。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


DPN_CAPS

DirectPlay 用の汎用パラメータの設定と取得に使用する。

typedef struct _DPN_CAPS{
    DWORD dwSize;
    DWORD dwFlags;
    DWORD dwConnectTimeout;
    DWORD dwConnectRetries;
    DWORD dwTimeoutUntilKeepAlive;
} DPN_CAPS, *PDPN_CAPS;

メンバ

dwSize
この値は、構造体のサイズに設定する必要がある。
dwFlags
将来の使用に備えて予約されているので、0 に設定しておく。
dwConnectTimeout
DirectPlay が接続要求を再送信するまで待機する時間 (ミリ秒単位)。
dwConnectRetries
DirectPlay が接続処理中に行う接続の再試行の回数。
dwTimeoutUntilKeepAlive
DirectPlay が、最後にエンドポイントからパケットを受け取ってからキープ アライブ メッセージを送信するまでに待機する時間 (ミリ秒単位)。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


DPN_CONNECTION_INFO

ユーザーとユーザーが接続されているリモート コンピュータとの接続に関する統計情報を取得するために使用する。

typedef struct _DPN_CONNECTION_INFO{
    DWORD   dwSize;
    DWORD   dwRoundTripLatencyMS;
    DWORD   dwThroughputBPS;
    DWORD   dwPeakThroughputBPS;
    DWORD   dwBytesSentGuaranteed;
    DWORD   dwPacketsSentGuaranteed;
    DWORD   dwBytesSentNonGuaranteed;
    DWORD   dwPacketsSentNonGuaranteed;
    DWORD   dwBytesRetried;
    DWORD   dwPacketsRetried;
    DWORD   dwBytesDropped;
    DWORD   dwPacketsDropped;
    DWORD   dwMessagesTransmittedHighPriority;
    DWORD   dwMessagesTimedOutHighPriority;
    DWORD   dwMessagesTransmittedNormalPriority;
    DWORD   dwMessagesTimedOutNormalPriority;
    DWORD   dwMessagesTransmittedLowPriority;
    DWORD   dwMessagesTimedOutLowPriority;
    DWORD   dwBytesReceivedGuaranteed;
    DWORD   dwPacketsReceivedGuaranteed;
    DWORD   dwBytesReceivedNonGuaranteed;
    DWORD   dwPacketsReceivedNonGuaranteed;
    DWORD   dwMessagesReceived;
} DPN_CONNECTION_INFO, *PDPN_CONNECTION_INFO;

メンバ

dwSize
構造体のサイズ。
dwRoundTripLatencyMS
パケットがリモート コンピュータに到達し、ローカル コンピュータに戻るまでの時間の概算値 (ミリ秒単位)。リンクの条件が変更されるため、この値はセッション全体にわたって変化する。
dwThroughputBPS
バイト/秒 (Bps) 単位で表したリンクのスループットの概算値。リンクの条件が変更されるため、この値はセッション全体にわたって変化する。この値は概算であり、自分自身の値をより正確に計算することもできる。
dwPeakThroughputBPS
ビット/秒 (bps) 単位で表したリンクのピーク スループット値。リンクの条件が変更されるため、この値はセッション全体にわたって変化する。この値は概算であり、自分自身の値をより正確に計算することもできる。
dwBytesSentGuaranteed
送信された保証付きメッセージの総数 (バイト単位)。
dwPacketsSentGuaranteed
送信された保証付きメッセージのパケットの数。
dwBytesSentNonGuaranteed
送信された保証付きでないメッセージの総数 (バイト単位)。
dwPacketsSentNonGuaranteed
送信された保証付きでないメッセージのパケットの数。
dwBytesRetried
再試行されたメッセージの総数 (バイト単位)。
dwPacketsRetried
再試行されたパケットの数。
dwBytesDropped
削除されたメッセージの総数 (バイト単位)。
dwPacketsDropped
削除されたパケットの数。
dwMessagesTransmittedHighPriority
転送された優先順位の高いメッセージの数。
dwMessagesTimedOutHighPriority
タイムアウトした優先順位の高いメッセージの数。
dwMessagesTransmittedNormalPriority
転送された通常優先順位のメッセージの数。
dwMessagesTimedOutNormalPriority
タイムアウトした通常優先順位のメッセージの数。
dwMessagesTransmittedLowPriority
転送された優先順位の低いメッセージの数。
dwMessagesTimedOutLowPriority
タイムアウトした優先順位の低いメッセージの数。
dwBytesReceivedGuaranteed
受信された保証付きメッセージの総数 (バイト単位)。
dwPacketsReceivedGuaranteed
受信された保証付きメッセージのパケットの数。
dwBytesReceivedNonGuaranteed
受信された保証付きでないメッセージの総数 (バイト単位)。
dwPacketsReceivedNonGuaranteed
受信された保証付きでないメッセージのパケットの数。
dwMessagesReceived
受信されたメッセージの数。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


DPN_GROUP_INFO

静的グループ情報を記述する。

typedef struct _DPN_GROUP_INFO{
    DWORD  dwSize;
    DWORD  dwInfoFlags;
    PWSTR  pwszName;
    PVOID  pvData;
    DWORD  dwDataSize;
    DWORD  dwGroupFlags;
} DPN_GROUP_INFO, *PDPN_GROUP_INFO;

メンバ

dwSize
構造体のサイズを記述する DWORD 型の変数。
dwInfoFlags

この構造体に含まれる型情報を指定するフラグを保持する DWORD 型の変数。GetGroupInfo メソッドが値を返すと、DPN_GROUP_INFO の dwInfoFlags メンバは、対応するポインタが NULL に設定されている場合でも、必ず両方のフラグが設定される。これらのフラグは、IDirectPlay8Peer::SetGroupInfo の呼び出しに使用され、Microsoft® DirectPlay® に変更された値を知らせる。

DPNINFO_NAME
pwszName メンバに有効なデータが含まれる。
DPNINFO_DATA
pvData メンバに有効なデータが含まれる。
pwszName
グループの Unicode 名を指定する PWSTR 型の変数へのポインタ。
pvData
グループを記述するデータへのポインタ。
dwDataSize
pvData メンバに含まれるデータ サイズを指定する DWORD 型の変数。
dwGroupFlags
次の記述フラグを設定できる DWORD 型の変数。
DPNGROUP_AUTODESTRUCT
グループの作成者がグループを離れると、グループは自動的に破棄される。

注意

IDirectPlay8Peer::GetGroupInfo メソッドと IDirectPlay8Server::GetGroupInfo メソッドでこの構造体を使用する場合、dwInfoFlags は 0 に設定する必要がある。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


DPN_PLAYER_INFO

静的プレーヤー情報を記述する。

typedef struct _DPN_PLAYER_INFO{
    DWORD  dwSize;
    DWORD  dwInfoFlags;
    PWSTR  pwszName;
    PVOID  pvData;
    DWORD  dwDataSize;
    DWORD  dwPlayerFlags;
} DPN_PLAYER_INFO, *PDPN_PLAYER_INFO;

メンバ

dwSize
構造体のサイズを記述する DWORD 型の変数。
dwInfoFlags
この構造体に含まれる型情報を指定するフラグを保持する DWORD 型の変数。GetPlayerInfo メソッドが値を返すと、DPN_PLAYER_INFO の dwInfoFlags メンバは、対応するポインタが NULL に設定されている場合でも、必ず両方のフラグが設定される。これらのフラグは、IDirectPlay8Peer::SetPeerInfo の呼び出しに使用され、Microsoft® DirectPlay® に変更された値を知らせる。
DPNINFO_NAME
pwszName メンバに有効なデータが含まれる。
DPNINFO_DATA
pvData メンバに有効なデータが含まれる。
pwszName
プレーヤーの Unicode 名を指定する PWSTR 型の変数へのポインタ。
pvData
プレーヤーを記述するデータへのポインタ。
dwDataSize
pvData メンバに含まれるデータ サイズを指定する DWORD 型の変数。
dwPlayerFlags
以下のいずれかのフラグを保持する DWORD 型の変数。
DPNPLAYER_LOCAL
この情報はローカル プレーヤー用である。
DPNPLAYER_HOST
このプレーヤーはアプリケーションのホストである。

注意

IDirectPlay8Peer::GetPeerInfo メソッドと IDirectPlay8Server::GetClientInfo メソッドでこの構造体を使用する場合、dwInfoFlags は 0 に設定する必要がある。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


DPN_SECURITY_CREDENTIALS

実装されていない。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


DPN_SECURITY_DESC

実装されていない。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


DPN_SERVICE_PROVIDER_INFO

特定のサービス プロバイダの情報を列挙する場合に使用する。

typedef struct _DPN_SERVICE_PROVIDER_INFO{
    DWORD  dwFlags;
    GUID  Guid;
    WCHAR* pwszName;
    PVOID  pvReserved;
    DWORD  dwReserved;
} DPN_SERVICE_PROVIDER_INFO, *PDPN_SERVICE_PROVIDER_INFO;

メンバ

dwFlags
予約済み。0 に設定しておく。
pGuid
サービス プロバイダの GUID。
pwszName
サービス プロバイダの名前。
pvReserved
予約済み。0 に設定しておく。
dwReserved
予約済み。0 に設定しておく。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


DPN_SP_CAPS

サービス プロバイダ用のパラメータの設定と取得に使用する。

typedef struct _DPN_SP_CAPS{
    DWORD  dwSize;
    DWORD  dwFlags;
    DWORD  dwNumThreads;
    DWORD  dwDefaultEnumCount;
    DWORD  dwDefaultEnumRetryInterval;
    DWORD  dwDefaultEnumTimeout;
    DWORD  dwMaxEnumPayloadSize;
    DWORD  dwBuffersPerThread;
    DWORD  dwSystemBufferSize;

} DPN_SP_CAPS, *PDPN_SP_CAPS;

メンバ

dwSize
この値は、構造体のサイズに設定する必要がある。
dwFlags
次のフラグを組み合わせて使用できる。
DPNSPCAPS_SUPPORTSDPNSRV
DPNSVR.EXE は特定のサービス プロバイダにポート共有を提供する。現在、このフラグは IP と IPX においてのみ利用できる。DPNSVR の詳細については、「DirectPlay DPNSVR アプリケーションの使い方」を参照すること。
DPNSPCAPS_SUPPORTSBROADCAST
IP および IPX アプリケーションで、渡されたアドレス情報が不足する場合、サービス プロバイダがある要素を全要素にコピーしてゲームを検索できる。
DPNSPCAPS_SUPPORTSALLADAPTERS
サービス プロバイダは、システム上のすべてのデバイスを使用する。デバイス要素を指定する必要はない。
dwNumThreads
サービス プロバイダがネットワーク要求のサービスに使用するスレッドの数。デフォルト値は、システムのプロセッサ数を考慮したアルゴリズムに基づいて設定される。大部分のアプリケーションではこの値を変更する必要がない。

プロセスでサービス プロバイダがアクティブになった後は、この値を増加することしかできない。この値を減少しても効果がない。設定はプロセス全体に有効であり、ユーザーの現在の DirectPlay オブジェクトと、プロセス内のほかのすべての DirectPlay オブジェクトに影響する。

EnumHosts、Connect、または Host を呼び出す前に SetSPCaps メソッドを呼び出した場合、デフォルト値より小さい値を指定できる。

dwDefaultEnumCount
デフォルトの列挙カウント。
dwDefaultEnumRetryInterval
デフォルトの再試行間隔 (ミリ秒単位)。
dwDefaultEnumTimeout
デフォルトの列挙タイムアウト値 (ミリ秒単位)。
dwMaxEnumPayloadSize
DPN_MSGID_ENUM_HOST_QUERY および DPN_MSGID_ENUM_HOST_RESPONSE メッセージを伴う構造体の pvResponseData メンバに送信できるプレイロード情報の最大サイズ。
dwBuffersPerThread
各 DirectPlay スレッドに割り当てる未処理の受信バッファの数。受信バッファの数を増加した場合、DirectPlay はオペレーティング システム バッファからより多くのデータを引き出すことができる。ただし、アプリケーションの処理速度がデータの到着する速度に追いつかない場合は、遅延時間を延長することもできる。
dwSystemBufferSize
オペレーティング システム バッファのサイズ。このバッファは、アプリケーションの処理速度がデータの到着する速度に追いつかないとき、通信デバイスからのデータを保持する。このバッファの目的は、突然に大量のデータを受け取った場合、または受信スレッドが瞬間的にストールされた場合に、データの損失を防ぐことである。アプリケーションが受信データを適切な速度で処理できない場合、dwSystemBufferSize を増加すると遅延時間が長くなることがある。dwSystemBufferSize を 0 に設定すると、オペレーティング システム バッファをなくすことができる。ただし、これを行うと、受信したデータを到着後すぐに処理できない場合に、データが失われるおそれがある。

注意

DirectX 8.0 では、IP および IPX サービス プロバイダは dwBuffersPerThread および dwSystemBufferSize メンバのみを使用する。これらのメンバのデフォルト値は、サービス プロバイダが設定する。デフォルト値を判断するには、GetSPCaps メソッドを呼び出す。大部分のアプリケーションでは、これら 2 つのメンバにデフォルト値を使用する必要がある。これらのメンバは、基本的には、大量のデータを処理するマルチプレーヤー ゲーム用サーバー アプリケーションを作成する開発者が使用する。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。


DVCAPS

Microsoft® DirectPlay® VoiceClient オブジェクトの能力を記述する。

typedef struct{
    DWORD dwSize;
    DWORD dwFlags;
} DVCAPS, *LPDVCAPS, *PDVCAPS;

メンバ

dwSize
この構造体を使用する前に、この構造体のサイズ (バイト単位) に設定する必要がある。
dwFlags
予約済み。0 に設定しておく。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice8.h で宣言。


DVCLIENTCONFIG

クライアントの実行時のパラメータを制御する。最初、IDirectPlayVoiceClient::Connect の呼び出しにこの構造体を使用し、パラメータの初期状態を設定する。接続の確立後、この構造体を取得するには IDirectPlayVoiceClient::GetClientConfig を呼び出す。この構造体を設定するには、IDirectPlayVoiceClient::SetClientConfig を使用する。

typedef struct {
    DWORD  dwSize;
    DWORD  dwFlags;
    LONG   lRecordVolume;
    LONG   lPlaybackVolume;
    DWORD  dwThreshold;
    DWORD  dwBufferQuality;
    DWORD  dwBufferAggressiveness;
    DWORD  dwNotifyPeriod;
} DVCLIENTCONFIG, *LPDVCLIENTCONFIG, *PDVCLIENTCONFIG;

メンバ

dwSize
この構造体を使用する前に、この構造体のサイズ (バイト単位) に設定する必要がある。
dwFlags
次のフラグの組み合わせ。
DVCLIENTCONFIG_AUTORECORDVOLUME
自動ゲイン制御をアクティブにする。Microsoft® DirectPlay® Voice では、自動ゲイン制御を使用して、サウンド カードでハードウェア入力ボリュームを自動調整し、入力レベルを最適にする。現在の入力ボリュームを調べるには、IDirectPlayVoiceClient::GetClientConfig を呼び出した後に lRecordVolume メンバを調べるか、DVMSG_INPUTLEVEL メッセージの lRecordVolume メンバを調べる。
DVCLIENTCONFIG_ECHOSUPPRESSION
エコー抑制モードをアクティブにする。このモードは、外部スピーカと高感度マイクによる構成で発生するエコーを減少させる。リモート プレーヤーの音声はローカル スピーカで再生されるが、マイクは自動的にミュートされる。ローカル プレーヤーが発信する場合、ローカル入力が停止するまで、リモート プレーヤーの音声の再生はバッファに格納される。ローカル入力が停止した後、再生が再開する。
DVCLIENTCONFIG_MUTEGLOBAL
メイン サウンド バッファの再生をミュートする。IDirectPlayVoiceClient::Create3DSoundBuffer を呼び出して作成されたサウンド バッファのみが再生される。
DVCLIENTCONFIG_PLAYBACKMUTE
すべての DirectPlay Voice 出力の再生をミュートし、再生を停止する。また、受信パケットの圧縮の復元も停止するため、CPU の使用量が減少する。このフラグが指定されている間、パケットは実質的に廃棄される。
DVCLIENTCONFIG_RECORDMUTE
マイクからの入力をミュートし、録音を停止する。また、圧縮も停止するため、CPU の使用量は減少する。

上記のフラグに加え、次のフラグのいずれか一方を設定するか、どちらも指定しないことで、転送方法を制御できる。

DVCLIENTCONFIG_AUTOVOICEACTIVATED
転送制御システムを自動音声をアクティブにするモードにする。このモードでは、音声をアクティブにする感度はシステムによって自動的に決定される。入力レベルは、入力信号に合わせて自動的に調整される。大部分のアプリケーションでは、この設定を使用する。このフラグは DVCLIENTCONFIG_MANUALVOICEACTIVATED フラグと互いに排他的である。
DVCLIENTCONFIG_MANUALVOICEACTIVATED
転送制御システムを手動音声をアクティブにするモードにする。このモードでは、入力レベルが dwThreshold メンバに指定されたレベルを超えると、音声の転送が開始される。入力レベルが指定レベルより下になると、転送は停止する。このフラグは DVCLIENTCONFIG_AUTOVOICEACTIVATED フラグと互いに排他的である。

DVCLIENTCONFIG_MANUALVOICEACTIVATED および DVCLIENTCONFIG_AUTOVOICEACTIVATED のどちらも指定しない場合、システムはプッシュツートーク モードで動作する。プッシュツートーク モードでは、有効なターゲットが指定されている限り、マイクからの入力は転送される。NULL ターゲットが設定されるか、現在のターゲットがセッションを離れるか、または現在のターゲットが破棄された場合、音声転送は停止する。

lRecordVolume
設定する録音のボリュームを示す値。有効な値については、「IDirectSoundBuffer8::SetVolume」メソッドを参照すること。

自動ゲイン制御が有効になっている場合、この値を DVRECORDVOLUME_LAST に設定できる。この場合、システムは、自動ゲイン制御アルゴリズムで決まった現在のボリュームを使用する。DVRECORDVOLUME_LAST 以外の値を指定して自動ゲイン制御に組み合わせた場合、指定した値でアルゴリズムが再開する。

IDirectPlayVoiceClient::GetClientConfig を呼び出すと、この値に現在の録音ボリュームが格納される。DirectPlay Voice では、録音ボリュームを調整するとき、マイクのボリューム (カード用のマイクのボリュームが存在する場合) およびマスタ録音ボリューム (カードに存在する場合) を調整する。マイクのボリュームとマスタ録音ボリュームがどちらも存在しない場合、DirectPlay Voice は録音ボリュームを調整できない。

lPlaybackVolume
設定する再生のボリュームを示す値。このボリュームを調整すると、メイン バッファとすべての 3D サウンド バッファが調整される。有効な値については、「IDirectSoundBuffer8::SetVolume」メソッドを参照すること。DVPLAYBACKVOLUME_DEFAULT を指定すると、ほとんどの状況に適したデフォルト値 (フル ボリューム) を使用できる。
dwThreshold
dwFlags メンバに DVCLIENTCONFIG_MANUALVOICEACTIVATED フラグを指定した場合に音声転送のトリガに使用される入力レベル。このフラグを指定した場合、DVTHRESHOLD_MIN から DVTHRESHOLD_MAX までの任意の値を指定できる。また、DVTHRESHOLD_DEFAULT を設定すると、デフォルト値を使用できる。

この構造体の dwFlags メンバに DVCLIENTCONFIG_MANUALVOICEACTIVATED または DVCLIENTCONFIG_AUTOVOICEACTIVATED を指定していない場合 (プッシュツートーク モードを示す)、この値は DVTHRESHOLD_UNUSED に指定する必要がある。

dwBufferQuality
適応バッファリング アルゴリズムのバッファ品質の設定。大部分のアプリケーションでは、DVBUFFERQUALITY_DEFAULT に設定する。DVBUFFERQUALITY_MIN から DVBUFFERQUALITY_MAX までの任意の値に設定できる。一般に、値が大きいほど音声の質は高くなるが、遅延時間は長くなる。値が小さいほど遅延時間は短くなるが、質は低下する。
dwBufferAggressiveness
適応バッファリング アルゴリズムのバッファの即応性の程度の設定。大部分のアプリケーションでは、DVBUFFERAGGRESSIVENESS_DEFAULT に設定できる。また、DVBUFFERAGGRESSIVENESS_MIN から DVBUFFERAGGRESSIVENESS_MAX までの任意の値に設定できる。一般に、値が大きいほど適応バッファリングは状況変化への対応が速くなる。値が小さいほど、適応バッファリングは状況変化への対応が遅くなる。
dwNotifyPeriod
DVMSGID_OUTPUTLEVEL メッセージと DVMSGID_INPUTLEVEL メッセージ (セッションが全二重である場合) を受け取る頻度を示す値。この値を 0 に設定した場合、メッセージは無効になる。メッセージ間の間隔をミリ秒単位で指定する。DVNOTIFYPERIOD_MINPERIOD を指定すると、メッセージ間で可能な最小時間が設定される。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice8.h で宣言。


DVCOMPRESSIONINFO

Microsoft® DirectPlay® Voice の特定の圧縮タイプの属性を記述する。

typedef struct{
    DWORD           dwSize;
    GUID            guidType;
    LPWSTR          lpszName;
    LPWSTR          lpszDescription;
    DWORD           dwFlags;
    DWORD           dwMaxBitsPerSecond;
} DVCOMPRESSIONINFO, *LPDVCOMPRESSIONINFO, *PDVCOMPRESSIONINFO;

メンバ

dwSize
この構造体を使用する前に、この構造体のサイズ (バイト単位) に設定する必要がある。
guidType
DirectPlay Voice がこの圧縮タイプの識別に使用する GUID。
lpszName
CODEC を記述する名前へのポインタ。
lpszDescription
CODEC の長い名前へのポインタ。
dwFlags
将来の使用に備えて予約されているので、0 に設定しておく。
dwMaxBitsPerSecond
CODEC で主張されている 1 秒あたりの最大ビット数。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice8.h で宣言。


DVSESSIONDESC

Microsoft® DirectPlay® Voice サーバーの必要なセッション設定または現在のセッション設定を記述する。音声セッション ホストは、この構造体を使用してセッションを設定する。また、セッション ホストとクライアントはこの構造体を使用して、現在のセッションに関する情報を取得する。dwFlags、dwSessionType、および guidCT の各メンバは、ホストが音声セッションを開始するときにのみ設定できる。ホストはいつでもバッファ設定を変更できる。

typedef struct {
    DWORD  dwSize;
    DWORD  dwFlags;
    DWORD  dwSessionType;
    GUID   guidCT;
    DWORD  dwBufferQuality;
    DWORD  dwBufferAggresiveness;
} DVSESSIONDESC, *LPDVSESSIONDESC, *PDVSESSIONDESC;

メンバ

dwSize
この構造体を使用する前に、この構造体のサイズ (バイト単位) に設定する必要がある。
dwFlags
次のフラグの組み合わせ。
DVSESSION_NOHOSTMIGRATION
トランスポートの設定に関係なく、音声ホストは移行しない。このフラグを指定しない場合、トランスポートのサポートがあれば、ホストは移行する。
DVSESSION_SERVERCONTROLTARGET
クライアントは音声のターゲットを制御できない。サーバー プレーヤーのみが音声のターゲットを制御できる。サーバーがこのフラグを指定しない場合、クライアントのみが音声のターゲットを制御できる。このフラグは、マルチキャストおよびミキシング セッションでのみ指定できる。
dwSessionType
実行する DirectPlay Voice セッションのタイプ。クライアント/サーバー セッションでは、DVSESSIONTYPE_PEER フラグは利用できない。ほかのすべてのフラグはすべてのセッション タイプに有効である。このメンバには次のいずれかの値を指定できる。
DVSESSIONTYPE_PEER
音声メッセージをプレーヤー間で直接送信する。
DVSESSIONTYPE_MIXING
音声セッションでミキシング サーバーを使用する。この処理モードでは、すべての音声メッセージはサーバーに送信される。サーバーはミキシングし、単一のミキシング済みストリームを各クライアントに転送する。サーバーの帯域幅と CPU の使用量が増加する代わりに、クライアントの帯域幅と CPU の使用量は大きく減少する。
DVSESSIONTYPE_FOWARDING
音声メッセージはセッション ホストを経由してルーティングされる。サーバーの帯域幅を使用する代わりにクライアントの帯域幅は節約できる。セッション ホストが高速接続している場合にのみ、このオプションは役立つ。
guidCT
セッションの圧縮タイプを指定する GUID。
dwBufferQuality
バッファの品質設定。このメンバは、ミキシング セッション以外のセッション タイプでは使用しない。ミキシング セッション以外のすべてのセッションでは、このメンバを DVBUFFERQUALITY_DEFAULT に設定する。

DVBUFFERQUALITY_MIN から DVBUFFERQUALITY_MAX までの値が使用できる。また、このメンバは次の値にも設定できる。

DVBUFFERQUALITY_DEFAULT
この値を指定すると、システムのデフォルト値が使用される。デフォルト値は、レジストリ エントリを使用して調整できる。また、コントロール パネルの [サウンド] と [マルチメディア] からも設定できる。
dwBufferAggresiveness
バッファの即応性の程度の設定。このメンバは、ミキシング セッション以外のセッション タイプでは使用しない。ミキシング セッション以外のすべてのセッションでは、このメンバを DVBUFFERAGGRESIVENESS_DEFAULT に設定する。

DVBUFFERAGGRESIVENESS _MIN から DVBUFFERAGGRESIVENESS _MAX までの値が使用できる。また、このメンバは次の値にも設定できる。

DVBUFFERAGGRESIVENESS_DEFAULT
この値を指定すると、システムのデフォルト値が使用される。デフォルト値は、レジストリ エントリを使用して調整できる。また、コントロール パネルからも設定できる。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice8.h で宣言。


DVSOUNDDEVICECONFIG

サウンド デバイス構成に関する情報の設定と取得に使用する。一度接続が確立すると、値は変更できない。接続の確立後、IDirectPlayVoiceClient::GetSoundDeviceConfig を呼び出すと、現在のサウンド デバイス設定を取得できる。

typedef struct {
    DWORD                dwSize;
    DWORD                dwFlags;
    GUID                 guidPlaybackDevice;
    LPDIRECTSOUND        lpdsPlaybackDevice;
    GUID                 guidCaptureDevice;
    LPDIRECTSOUNDCAPTURE lpdsCaptureDevice;
    HWND                 hwndAppWindow;
    LPDIRECTSOUNDBUFFER  lpdsMainBuffer;
    DWORD                dwMainBufferFlags;
    DWORD                dwMainBufferPriority;
} DVSOUNDDEVICECONFIG, *LPDVSOUNDDEVICECONFIG, *PDVSOUNDDEVICECONFIG;

メンバ

dwSize
この構造体を使用する前に、この構造体のサイズ (バイト単位) に設定する必要がある。
dwFlags
次のフラグを組み合わせて指定する。
DVSOUNDCONFIG_AUTOSELECT
このフラグを指定すると、Microsoft® DirectPlay® Voice は、指定された録音デバイスのミキサでマイク ラインを自動的に選択 (またはミュート解除) しようとする。
DVSOUNDCONFIG_HALFDUPLEX
DirectPlay Voice を半二重モードで初期化する。半二重モードでは録音は行われない。全二重モードでサウンド システムの初期化が失敗した場合、システムによってこのフラグが設定される。
DVSOUNDCONFIG_NORMALMODE
DirectPlay Voice に、Microsoft® DirectSound® の通常モードを使用して DirectSound オブジェクトを初期化するように指示する。このフラグを指定しない場合、DirectSound オブジェクトは DirectSound の優先モードで初期化される。詳細については、「IDirectSound8::SetCooperativeLevel」の説明を参照すること。lpdsPlaybackDevice メンバに有効な DirectSound オブジェクトが指定された場合、このフラグは無視される。
DVSOUNDCONFIG_SETCONVERSIONQUALITY
CPU の使用量が増加する代わりに、高品質のオーディオを使用できる。
DVSOUNDCONFIG_NORECVOLAVAILABLE
指定した録音デバイスでボリュームが制御できない場合、DirectPlay Voice によって設定される。開発者はこのフラグを設定できない。
DVSOUNDCONFIG_NOFOCUS
音声アプリケーションは決してフォーカスを失わない。言い換えると、アプリケーションは決してサウンド キャプチャ デバイスを解放しない。このフラグの使用は推奨されない。
DVSOUNDCONFIG_STRICTFOCUS
音声アプリケーションのウィンドウがフォアグラウンド ウィンドウでなくなると、音声アプリケーションはフォーカスを失う。

注 アプリケーションでは、どうしても必要な場合にのみ、DVSOUNDCONFIG_NOFOCUS または DVSOUNDCONFIG_STRICTFOCUS フラグを設定すること。通常は、いずれのフラグも設定しないデフォルトの動作を使用する。

guidPlaybackDevice
IDirectPlayVoiceClient::Connect メソッドでこの構造体を使用する場合、再生に使用するデバイスの GUID をこのメンバに指定する。lpdsPlaybackDevice メンバを使用する場合でも、この値を指定する必要がある。また、DirectSound が提供する次のデフォルト GUID を使用することもできる。
DSDEVID_DefaultPlayback
システムのデフォルト再生デバイス。
DSDEVID_DefaultVoicePlayback
デフォルト音声再生デバイス。

IDirectPlayVoiceClient::GetSoundDeviceConfig メソッドでこの構造体を使用した場合、再生に使用する実際のデバイス GUID がこのメンバに格納される。

lpdsPlaybackDevice
IDirectPlayVoiceClient::Connect メソッドでこの構造体を使用する場合、DirectPlay Voice で再生に使用する DirectSound オブジェクトを指定する。guidPlaybackDevice に指定する GUID は、このパラメータで指定したデバイスの作成に使用される GUID に一致する必要がある。DirectSound オブジェクトの作成時にデバイス指定で NULL を使用した場合、このメンバに DSDEVID_DefaultPlayback を指定する。

IDirectPlayVoiceClient::GetSoundDeviceConfig メソッドでこの構造体を使用した場合、DirectPlay Voice で使用される DirectSound オブジェクトへのポインタがこのメンバに格納される。このポインタは、Connect の呼び出しで指定されたオブジェクトへのポインタ、または新規作成され、初期化された DirectSound オブジェクトへのポインタである。この DirectSound オブジェクトを使用する場合は、ポインタを記憶し、DirectSound インターフェイスで AddRef を呼び出して参照カウントをインクリメントする必要がある。

guidCaptureDevice
IDirectPlayVoiceClient::Connect メソッドでこの構造体を使用する場合、キャプチャに使用するデバイスの GUID をこのメンバに指定する。lpdsCaptureDevice メンバを使用する場合でも、この値を指定する必要がある。DirectSoundCapture オブジェクトの作成時にデバイス指定で NULL を使用した場合、このメンバに DSDEVID_DefaultCapture を指定する。

IDirectPlayVoiceClient::GetSoundDeviceConfig メソッドでこの構造体を使用した場合、キャプチャに使用される実際のデバイス GUID がこのメンバに格納される。

lpdsCaptureDevice
IDirectPlayVoiceClient::Connect メソッドでこの構造体を使用する場合、DirectPlay Voice でキャプチャに使用する DirectSound オブジェクトをこのメンバに指定する。guidCaptureDevice に指定する GUID は、このパラメータで指定したデバイスの作成に使用される GUID に一致する必要がある。DirectPlay Voice で自動的に DirectSoundCapture オブジェクトを作成する場合は、このパラメータに NULL を指定する。

IDirectPlayVoiceClient::GetSoundDeviceConfig メソッドでこの構造体を使用した場合、DirectPlay Voice で使用される DirectSoundCapture オブジェクトへのポインタがこのメンバに格納される。このポインタは、Connect の呼び出しで指定されたオブジェクトへのポインタ、または新規作成され、初期化された DirectSoundCapture オブジェクトへのポインタである。この DirectSoundCapture オブジェクトを使用する場合は、ポインタを記憶し、IDirectSoundCapture8 インターフェイスで AddRef を呼び出して参照カウントをインクリメントする必要がある。DirectPlay Voice オブジェクトが半二重モードで動作している場合、このメンバは NULL になる。

hwndAppWindow
サウンド再生のフォーカスの決定に使用されるウィンドウのハンドルを設定する。DirectSound のフォーカスの詳細については、「IDirectSound8::SetCooperativeLevel」を参照すること。フォーカスに使用するウィンドウがない場合、GetDesktopWindow を使用してデスクトップ ウィンドウを使用する。
lpdsMainBuffer
IDirectSoundBuffer8 インターフェイスへのポインタ。このインターフェイスを使って、DirectPlay Voice のメイン バッファを作成する。NULL、またはユーザー作成の DirectSound バッファを指定できる。このメンバを NULL に設定すると、DirectPlay Voice はメイン音声バッファとして使用するバッファを作成する。ここでバッファを指定した場合、DirectPlay Voice はこのバッファをメインの音声バッファとして使用する。ユーザー作成のバッファには次の制限がある。
  • バッファは、22Khz、16 ビット、モノラル フォーマットでなければならない。
  • バッファの長さは、1 秒以上でなければならない。
  • バッファは、DSBCAPS_GETCURRENTPOSITION2 および DSBCAPS_CTRL3D フラグを使用して作成されていなければならない。
  • バッファはプライマリ バッファであってはならない。
  • バッファは、DirectPlay Voice ソフトウェアに渡されるときに再生中であってはならない。
  • バッファは、DirectPlay Voice ソフトウェアに渡されるときにロックされていてはならない。
dwMainBufferFlags
メイン バッファに対して Play を呼び出すと、IDirectSoundBuffer8::Play メソッドの dwFlags パラメータにこのメンバが直接渡される。このフィールドには、DSBPLAY_LOOPING フラグが自動的に追加される。詳細については、「IDirectSoundBuffer8::Play」の説明を参照すること。この構造体の lpdsMainBufferDesc メンバが NULL である場合、このパラメータは 0 に設定する必要がある。
dwMainBufferPriority
メイン バッファに対して Play を呼び出すと、IDirectSoundBuffer8::Play メソッドの dwPriority パラメータにこのメンバが直接渡される。詳細については、「IDirectSoundBuffer8::Play」の説明を参照すること。lpdsMainBufferDesc が NULL である場合、このメンバは 0 に設定する必要がある。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dvoice8.h で宣言。


戻り値

エラーは負の値で表され、それらを組み合わせることはできない。

次の表は、以降で示すエラー値が適用されるインターフェイスのリストである。

インターフェイス | インターフェイス
IDirectPlay8Address | IDirectPlay8Peer
IDirectPlay8AddressIP | IDirectPlay8Server
IDirectPlay8Client | IDirectPlayVoiceClient
IDirectPlay8LobbiedApplication | IDirectPlayVoiceServer
IDirectPlay8LobbyClient | IDirectPlayVoiceTest

各メソッドにより返されるエラー値については、個別のメソッドの説明を参照すること。

Microsoft® DirectPlay® のサンプルの多くには、HRESULT 値を DirectPlay エラーの文字列名に変換する GetDirectPlayErrStr 関数が含まれている。開発者は、診断トレースやエラー レポート用に各自のアプリケーションにこのコードをコピーできる。

成功コード

DPNSUCCESS_PENDING
非同期処理で、キューへの設定が成功するところまで処理が進んだ。
S_OK
操作は正常に終了した。

エラー コード

DPNERR_ABORTED
操作は、完了前に取り消された。
DPNERR_ADDRESSING
指定されたアドレスが無効である。
DPNERR_ALREADYCONNECTED
オブジェクトはすでにセッションに接続されている。
DPNERR_ALREADYCLOSING
セッションでの Close メソッド呼び出しが複数回行われた。
DPNERR_ALREADYDISCONNECTING
クライアントはすでにセッションから接続解除している。
DPNERR_ALREADYINITIALIZED
オブジェクトは既に初期化されている。
DPNERR_BUFFERTOOSMALL
指定されたバッファが、要求されたデータを格納するのに十分な大きさでない。
DPNERR_CANNOTCANCEL
操作を取り消すことができなかった。
DPNERR_CANTCREATEGROUP
新しいグループを作成できない。
DPNERR_CANTCREATEPLAYER
新しいプレーヤーを作成できない。
DPNERR_CANTLAUNCHAPPLICATION
ロビーは指定されたアプリケーションを起動できない。
DPNERR_CONNECTING
このメソッドは、ネットワークに接続中である。
DPNERR_CONNECTIONLOST
データの送信中にサービス プロバイダ接続がリセットされた。
DPNERR_DATATOOLARGE
アプリケーション データが、サービス プロバイダの MTU (Maximum Transmission Unit) に対して大きすぎる。
DPNERR_DOESNOTEXIST
要求された要素はアドレスの一部ではない。
DPNERR_ENUMQUERYTOOLARGE
指定されたクエリ データが大きすぎる。
DPNERR_ENUMRESPONSETOOLARGE
列挙クエリへの応答が大きすぎる。
DPNERR_EXCEPTION
要求処理時に例外が発生した。
DPNERR_GENERIC
未定義エラー条件が発生した。
DPNERR_GROUPNOTEMPTY
指定されたグループが空ではない。
DPNERR_HOSTREJECTEDCONNECTION
DPN_MSGID_INDICATE_CONNECT システム メッセージが、接続要求に対して S_OK 以外の値を返した。
DPNERR_HOSTTERMINATEDSESSION
ピアツーピア セッションのホスト (ホストの移行が可能) がセッションを終了した。
DPNERR_INCOMPLETEADDRESS
指定されたアドレスが不完全である。
DPNERR_INVALIDADDRESSFORMAT
アドレス フォーマットが無効である。
DPNERR_INVALIDAPPLICATION
アプリケーションに指定された GUID が無効である。
DPNERR_INVALIDCOMMAND
指定されたコマンドが無効である。
DPNERR_INVALIDDEVICEADDRESS
ローカル コンピュータまたはアダプタのアドレスが無効である。
DPNERR_INVALIDFLAGS
このメソッドに渡されたフラグが無効であった。
DPNERR_INVALIDGROUP
グループ ID が、このゲーム セッションの有効なグループ ID として認識されない。
DPNERR_INVALIDHANDLE
指定されたハンドルは無効である。
DPNERR_INVALIDHOSTADDRESS
指定されたリモート アドレスが無効である。
DPNERR_INVALIDINSTANCE
アプリケーションのインスタンスの GUID が無効である。
DPNERR_INVALIDINTERFACE
インターフェイス パラメータが無効である。接続元プレーヤーがクライアント/サーバー ゲームのクライアントまたはピアツーピア ゲームのピアではなかった場合、接続要求にこの値が返される。
DPNERR_INVALIDOBJECT
DirectPlay オブジェクト ポインタが無効である。
DPNERR_INVALIDPARAM
メソッドに渡されたパラメータのいずれかまたはいくつかが無効である。
DPNERR_INVALIDPASSWORD
パスワードが必要なセッションに参加しようとしたときに、無効なパスワードが指定された。
DPNERR_INVALIDPLAYER
プレーヤー ID がこのゲーム セッションの有効なプレーヤー ID として認識されない。
DPNERR_INVALIDPOINTER
パラメータとして指定されたポインタが無効である。
DPNERR_INVALIDPRIORITY
指定された優先順位が、許可されている優先順位の範囲 (0 以上 65535 以下) 外である。
DPNERR_INVALIDSTRING
パラメータとして指定された文字列が無効である。
DPNERR_INVALIDURL
指定された文字列が無効な DirectPlay URL である。
DPNERR_INVALIDVERSION
DirectPlay の無効なバージョンに接続しようとした。
DPNERR_NOCAPS
DirectPlay が使用しようとしている通信リンクでは、この機能を使用できない。
DPNERR_NOCONNECTION
通信リンクが確立されなかった。
DPNERR_NOHOSTPLAYER
現在、セッションのホストとして機能するプレーヤーがない。
DPNERR_NOINTERFACE
インターフェイスがサポートされていない。
DPNERR_NORESPONSE
指定されたターゲットから応答がない。
DPNERR_NOTALLOWED
オブジェクトは読み取り専用である。このオブジェクトに対してこの機能は使用できない。
DPNERR_NOTHOST
クライアントがホスト以外のコンピュータに接続しようとした。また、ホスト以外のコンピュータがアプリケーションの記述を設定しようとした場合に、このエラー値が返されることがある。
DPNERR_OUTOFMEMORY
要求された操作を実行するには、メモリが不足している。
DPNERR_PENDING
エラーではない。この戻り値は、非同期処理で、キューへの設定が成功するところまで処理が進んだことを示す。SUCCEEDED(DPNERR_PENDING) は TRUE を返す。このエラー値は、DPNERR_SUCCESS で置き換えられている。新しいアプリケーションでは、DPNERR_SUCCESS を使用すべきである。DPNERR_PENDING は、下位互換性を保つために導入されている。
DPNERR_PLAYERLOST
プレーヤーは、セッションへの接続を喪失した。
DPNERR_PLAYERNOTREACHABLE
セッション内で少なくともほかの一人の既存プレーヤーが、参加中のプレーヤーに接続できない状態のピアツーピア セッションに、プレーヤーが参加しようとした。
DPNERR_SESSIONFULL
セッションに割り当てられているプレーヤーの最大数に達したため、ホストまたはサーバーへの接続要求が失敗した。
DPNERR_TIMEDOUT
時間切れのため、操作が完了できなかった。
DPNERR_UNINITIALIZED
要求されたオブジェクトが初期化されていない。
DPNERR_UNSUPPORTED
関数または機能を、この実装やこのサービス プロバイダで使用できない。
DPNERR_USERCANCEL
ユーザーは処理を取り消した。
DV_OK
要求は正常に終了した。
DV_FULLDUPLEX
サウンド カードは全二重操作が可能である。
DV_HALFDUPLEX
サウンド カードは半二重モードでしか動作しない。
DVERR_BUFFERTOOSMALL
指定されたバッファが、要求されたデータを格納するのに十分な大きさでない。
DVERR_EXCEPTION
要求処理時に例外が発生した。
DVERR_GENERIC
未定義エラー条件が発生した。
DVERR_INVALIDFLAGS
このメソッドに渡されたフラグが無効であった。
DVERR_INVALIDOBJECT
DirectPlay オブジェクト ポインタが無効である。
DVERR_INVALIDPARAM
メソッドに渡されたパラメータのいずれかまたはいくつかが無効である。
DVERR_INVALIDPLAYER
プレーヤー ID がこのゲーム セッションの有効なプレーヤー ID として認識されない。
DVERR_INVALIDGROUP
グループ ID が、このゲーム セッションの有効なグループ ID として認識されない。
DVERR_INVALIDHANDLE
指定されたハンドルは無効である。
DVERR_OUTOFMEMORY
要求された操作を実行するには、メモリが不足している。
DVERR_PENDING
エラーではない。この戻り値は、非同期処理で、キューへの設定が成功するところまで処理が進んだことを示す。
DVERR_NOTSUPPORTED
操作がサポートされていない。
DVERR_NOINTERFACE
指定されたインターフェイスがサポートされていない。使用した DirectPlay のバージョンが間違っている可能性がある。
DVERR_SESSIONLOST
トランスポートはセッションへの接続を喪失した。
DVERR_NOVOICESESSION
指定されたセッションは音声セッションではない。
DVERR_CONNECTIONLOST
音声セッションへの接続が喪失した。
DVERR_NOTINITIALIZED
このメソッドを呼び出す前に、IDirectPlayVoiceClient::Initialize メソッドまたは IDirectPlayVoiceServer::Initialize メソッドを呼び出す必要がある。
DVERR_CONNECTED
DirectPlayVoice オブジェクトが接続されている。
DVERR_NOTCONNECTED
DirectPlayVoice オブジェクトが接続されていない。
DVERR_CONNECTABORTING
接続解除中。
DVERR_NOTALLOWED
オブジェクトには、この操作を実行する権限がない。
DVERR_INVALIDTARGET
指定されたターゲットは、この音声セッションの有効なプレーヤー ID またはグループ ID ではない。
DVERR_TRANSPORTNOTHOST
オブジェクトは音声セッションのホストではない。
DVERR_COMPRESSIONNOTSUPPORTED
指定された圧縮タイプがローカル コンピュータでサポートされていない。
DVERR_ALREADYPENDING
このタイプの非同期呼び出しが既にペンディング状態になっている。
DVERR_ALREADYINITIALIZED
オブジェクトは既に初期化されている。
DVERR_SOUNDINITFAILURE
サウンド カードの初期化に失敗した。
DVERR_TIMEOUT
指定された時間内に操作を実行できなかった。
DVERR_CONNECTABORTED
接続は、完了前に取り消された。
DVERR_NO3DSOUND
ローカル コンピュータでは 3D サウンドをサポートしていない。
DVERR_ALREADYBUFFERED
指定された ID には既にユーザー バッファがある。
DVERR_NOTBUFFERED
指定された ID にはユーザー バッファがない。
DVERR_HOSTING
オブジェクトはセッションのホストである。
DVERR_NOTHOSTING
オブジェクトはセッションのホストではない。
DVERR_INVALIDDEVICE
指定されたデバイスが無効である。
DVERR_RECORDSYSTEMERROR
録音システムにエラーが発生した。
DVERR_PLAYBACKSYSTEMERROR
再生システムにエラーが発生した。
DVERR_SENDERROR
データの送信中にエラーが発生した。
DVERR_USERCANCEL
ユーザーは処理を取り消した。
DVERR_UNKNOWN
不明なエラーが発生した。
DVERR_RUNSETUP
指定されたオーディオ構成はテストされていない。IDirectPlayVoiceTest::CheckAudioSetup メソッドを呼び出す。
DVERR_INCOMPATIBLEVERSION
クライアントは、ホストと互換性がない音声セッションに接続した。
DVERR_INITIALIZED
オブジェクトがすでに初期化されているため、Initialize メソッドが失敗した。
DVERR_INVALIDPOINTER
指定されたポインタが無効である。
DVERR_NOTRANSPORT
指定されたオブジェクトは有効なトランスポートではない。
DVERR_NOCALLBACK
コールバック関数が指定されていないため、この操作は実行できない。
DVERR_TRANSPORTNOTINIT
指定されたトランスポートはまだ初期化されていない。
DVERR_TRANSPORTNOSESSION
指定されたトランスポートは有効だが、接続されてないかホストしていない。
DVERR_TRANSPORTNOPLAYER
指定されたトランスポートは接続され、ホストしているが、ローカル プレーヤーが存在しない。


DirectShow

Microsoft® DirectShow® アプリケーション プログラミング インターフェイス (API) は、Microsoft® Windows® プラットフォーム向けのメディア ストリーミング アーキテクチャである。DirectShow を使用すると、アプリケーションで高品質なビデオやオーディオの再生とキャプチャを行うことができる。DirectShow のドキュメントは、以下のトピックに分かれている。

  • DirectShow の概要
  • ファースト ステップ ガイド
  • DirectShow について
  • DirectShow の使い方
  • デコーダの開発
  • DirectShow チュートリアル
  • DirectShow リファレンス
  • DirectShow サンプル
  • DirectX Media Object
  • メディア パラメータ
  • 付録
  • 用語集

注 : このアイコン 外部リンク は、リンク先が microsoft.com サイト以外の URL であることを示す。これらの外部リンクのほとんどは、Microsoft が管理していないサイトを示している。これらのサイトの詳細については、Microsoft の official statement を参照すること。


DirectShow の概要

Microsoft® DirectShow® は、Microsoft® Windows® プラットフォームにおけるメディア ストリーミングのアーキテクチャである。DirectShow は、マルチメディア ストリームの高品質なキャプチャと再生を実現する。サポートするフォーマットは広範囲にわたり、ASF (Advanced Streaming Format)、MPWG (Motion Picture Experts Group)、AVI (Audio-Video Interleaved)、MP3 (MPEG Audio Layer-3)、および WAV ファイルを含む。 WDM (Windows Driver Model) デバイスおよび従来の Video for Windows デバイスを使ったキャプチャをサポートする。DirectShow は、ほかの DirectX テクノロジと統合されている。DirectShow は、ビデオおよびオーディオ アクセラレーション ハードウェアが使用可能な場合にはハードウェアを自動的に検出して使用するが、アクセラレーション ハードウェアのないシステムもサポートしている。

DirectShow では、メディア再生、フォーマット変換、およびキャプチャの作業を簡単に行える。 同時に、カスタム ソリューションを必要とするアプリケーションに対し、基礎になるストリーム制御アーキテクチャへのアクセスを提供する。新しいフォーマットまたはカスタム エフェクトをサポートする独自の DirectShow コンポーネントを作成することもできる。

DirectShow を使って作成できるアプリケーションの種類の例として、DVD プレーヤー、ビデオ編集アプリケーション、AVI から ASF へのコンバータ、MP3 プレーヤー、デジタル ビデオ キャプチャ アプリケーションがある。

DirectShow は Component Object Model (COM) に基づいている。DirectShow アプリケーションを作成するには、COM クライアント プログラミングを理解している必要がある。ほとんどのアプリケーションでは、独自の COM オブジェクトを実装する必要はない。DirectShow にはユーザーが必要とするコンポーネントが用意されている。ただし、独自のコンポーネントを作成して DirectShow を拡張する場合は、コンポーネントを COM オブジェクトとして実装する必要がある。

ここでは次の内容について説明する。

  • ロードマップ
  • DirectShow の新機能
  • DirectShow でサポートされるフォーマット
  • DirectShow FAQ


ロードマップ

ここでは、Microsoft® DirectShow® のドキュメント構成について説明する。

  • これまで DirectShow を使っていた場合は、「DirectShow の新機能」を参照すること。Microsoft® DirectX® 8 で導入された新機能が説明されている。
  • 初めて DirectShow を使う場合は、「ファースト ステップ ガイド」から始めること。次に、「DirectShow の使い方」で、作成するアプリケーションの種類 (再生、キャプチャ、DVD など) に応じた箇所を読むこと。DirectShow のアーキテクチャの詳細については、「DirectShow について」を読むこと。
  • ビデオ編集アプリケーションに関心がある場合は、最初に「DirectShow 編集サービス」の概要を読み、後でドキュメントのほかの部分を読むことができる。
  • これまでは、カスタム データ変換を実装するためには DirectShow フィルタを作成する必要があった。現在は、DirectX Media Object を作成することによって、同じ作業を簡単な方法で実行できる。詳細については、「DirectX Media Object」を参照すること。DirectShow フィルタを作成することもできる。詳細については、DirectShow フィルタの開発」を参照すること。

DirectShow に関する情報は、次の項目で構成されている。

ファースト ステップ ガイド
DirectShow のアプリケーション開発の概要。基本的な概念を説明し、DirectShow プログラミングを開始できるように、簡単な一連のアプリケーションを示す。初めて DirectShow を使う場合は、この項目を読むこと。
DirectShow について
DirectShow のアーキテクチャに関するおおまかな背景情報を示すとともに、グラフの構築など、アプリケーション開発に関するトピックがある。
DirectShow の使い方
DirectShow アプリケーションを作成するために必要な情報を示す。このトピックの内容は、ビデオ キャプチャ、DVD 再生、デジタル ビデオ、ビデオ編集など、特定のアプリケーション領域に分かれている。
デコーダの開発
ソフトウェア デコーダを作成する開発者向けの情報が含まれている。
DirectShow チュートリアル
DirectShow アプリケーション プログラミングに関するステップバイステップのチュートリアル。DirectShow を作成するときに知っておく必要があるデバイス列挙などの多くの基本的な作業について説明する。
DirectShow リファレンス
DirectShow アプリケーション プログラミング インターフェイス (API) の完全なリファレンス。DirectShow で提供されているフィルタについても説明する。
DirectShow サンプル
SDK に含まれているサンプルのアプリケーションとフィルタについて説明する。
DirectX Media Object
DirectX Media Object (DMO) は、データ ストリーミング コンポーネントを作成する新しい方法である。DirectShow フィルタと同様に、DMO は入力データを受け取り、それを使用して出力データを生成する。ただし、DMO は DirectShow フィルタよりも簡単に作成、テスト、 使用できる。
メディア パラメータ
メディア パラメータは、オブジェクトのプロパティに対する実行時の変更をサポートする新しい API のセットである。メディア パラメータを使用すると、急速に変化し、高いパフォーマンスと反復性の両方が要求されるプロパティを正確に制御できる。
付録
デバッグ、C を使用した DirectShow アプリケーションの作成、国/地域コード、廃止された機能の一覧など、その他の技術情報が含まれる。
用語集
DirectShow で使用する用語と概念を定義している。


DirectShow の新機能

ここでは、Microsoft® DirectX® 8.0 での Microsoft® DirectShow® の新機能について説明する。

  • Windows Media フォーマットのサポート
  • DirectShow 編集サービス
  • 新しい DVD サポート
  • 新しい MPEG-2 トランスポートと番組ストリーム サポート
  • Microsoft TV テクノロジ (Broadcast Driver Architecture)
  • DirectX ビデオ アクセラレーション
  • 新しいフィルタ
  • フィルタ グラフの新機能
  • ビルド環境の変更点
  • GraphEdit の新機能
  • DirectX Media Object
  • メディア パラメータ

Windows Media フォーマットのサポート

2 つの新しいフィルタによって、DirectShow アプリケーションで Windows Media™ フォーマットのファイルを読み書きできる。ASF リーダー フィルタは、Windows Media フォーマット ファイルを読み取り、解析する。ASF ライタ フィルタは、Windows Media フォーマット ファイルに書き込む。また、必要なマルチプレックス化と圧縮も行う。DirectShow と Windows Media Software Development Kit は、Windows Media フォーマット ストリームの作成と再生を行うアプリケーションを作成するための補足ソリューションを提供する。詳細については、「Windows Media アプリケーション」を参照すること。

DirectShow 編集サービス

DirectShow 編集サービスはビデオ編集とシーケンス化されたビデオ再生をサポートする API である。たとえば、2-3 のメソッドを呼び出すだけで、オーディオとビデオ クリップを一緒にシーケンス化したり、エフェクトを追加したり、その結果を再生したりできる。あるいは、完全なビデオ編集システムを作成することも可能だ。DEC は DirectShow のコア アーキテクチャの上に構築されている。DES は、ノンリニア ビデオ編集専用に設計されたインターフェイスのセットを提供する。

DES はカットリストに置き換わるもので、カットリストは既にサポートされていない。

新しい DVD サポート

2 つの新しいインターフェイスである IDVDControl2 と IDVDInfo2 は、DVD ナビゲータの機能を大幅に拡張したものである。新しい MSWebDVD ActiveX® コントロールを使用すると、スクリプト ベースのアプリケーションでこの機能を使用できるようになる。新しい DVD 機能の一部として、次の機能がある。

  • Karaoke マルチチャンネル オーディオ サポート
  • S/PDIF 出力に対する AC-3 サポート
  • IBasicAudio インターフェイスによるオーディオ ボリューム コントロール
  • コマ送り操作とフレーム単位のシーク操作
  • DVD テキスト情報文字列への簡単なアクセス
  • ペアレンタル ロックの改善されたサポート

詳細については、「DVD アプリケーション」を参照すること。

新しい MPEG-2 トランスポートと番組ストリーム サポート

新しいフィルタ、MPEG-2 デマルチプレクサ は MPEG-2 トランスポート ストリームと番組ストリームのサポートをプッシュモード (ライブソースからデータを受け取る) で提供する。詳細については、「MPEG-2 デマルチプレクサ」および「デジタル TV アプリケーションを書く」を参照すること。

Microsoft® TV テクノロジ (Broadcast Driver Architecture)

Microsoft® TV テクノロジには新しい Broadcast Driver Architecture (BDA) と、Microsoft チューニング モデルのサポートが含まれる。Broadcast Driver Architecture はデジタル TV や アナログ TV を受信する様々なコンポーネント トポロジをサポートするフレームワークを定義する。それには DVB や ATSC を含む主なデジタル ＴＶ に関する、ネットワーク構成のソフトウェア コンポーネントや、デマルチプレキシング、テーブル パース、IP データ 出力が含まれる。チューニング モデルは一連のオブジェクトであり、それによってアプリケーションはシンプルで共通の方法で複数のネットワーク タイプに容易にチューン アクセスできる。詳細については、「デジタル TV アプリケーションを書く」を参照すること。

DirectX ビデオ アクセラレーション

デコーダ 開発者へ : DirectX ビデオ アクセラレーションはアプリケーション プログラミング インターフェイス (API) であり、DVD サブピクチャのようなアルファ ブレンディングのサポートによって、デジタル ビデオ デコーディング処理をハードウェア アクセラレーションするデバイス ドライバ インターフェイス (DDI) に対応している。それは MPEG-2 "メイン プロファイル" ビデオ (公式には ITU-T H.262 | ISO/IEC 13818-2) のサポートに焦点を当てたインターフェイス定義を提供するが、他のキーとなるビデオ CODEC (つまり ITU-T Recommendations H.263 と H.261、そして MPEG-1 と MPEG-4) のサポートをも行う。詳細については、「DirectX ビデオ アクセラレーション」を参照すること。

新しいフィルタ

DirectShow にはいくつかの新しいフィルタがある。

  • ASF ライタ: Windows Media フォーマット ファイルを作成する。
  • ASF リーダー: Windows Media フォーマット ファイルを読み取り、解析する。
  • MJPEG デコンプレッサ: 動画 JPEG のビデオ ストリームを未圧縮のビデオにデコードする。
  • MJPEG コンプレッサ: 動画 JPEG 圧縮を使用して未圧縮のビデオ ストリームを圧縮する。
  • MPEG-2 デマルチプレクサ: ライブ ソースからの MPEG-2 トランスポート ストリームと番組ストリームをデマルチプレクス する。
  • Null レンダラ: サンプル データを表示またはレンダリングせずにサンプルを破棄する。アプリケーションでは、このフィルタを使用してストリームからデータを破棄できる。
  • サンプル グラバ: フィルタ グラフ内を移動するメディア サンプルを取得する。アプリケーションでは、このフィルタを使用して、ポスター フレームまたはその他のメディア データを取得できる。

フィルタ グラフの新機能

フィルタ グラフ マネージャは複数の新しい機能をサポートしている。

  • 動的なグラフの構築。 フィルタ グラフの実行中にグラフに変更を加えることができるようになった。今までは、アプリケーションでフィルタを追加または削除するにはグラフを停止しなければならず、データの流れが中断されていた。詳細については、「動的グラフ作成」を参照すること。
  • ライブ ソースの同期化。 DirectShow でライブ ソースの同期化がサポートされるようになった。たとえば、ライブ オーディオ ストリームをライブ ビデオ ストリームと同期化できる。詳細については、「DirectShow のタイムとクロック」を参照すること。
  • コマ送り。 フィルタ グラフ マネージャは新しい IVideoFrameStep インターフェイスを公開する、これを使うとアプリケーションはビデオファイルで 1 度に 1 フレームステップできる。

ビルド環境の変更点

  • 従来のヘッダー ファイル Streams.h は、DShow.h という新しいヘッダー ファイルに置き換えられた。
  • フィルタ基底クラスは SDK ルート ディレクトリの下の \Samples\BaseClasses ディレクトリに格納されている。フィルタ基底クラスを使うには、基底クラス ライブラリをビルドし、プロジェクトにリンクする必要がある。詳細については、「DirectShow 基底クラスの使い方」を参照すること。

GraphEdit の新機能

GraphEdit には、テストおよびデバッグ ツールとしての用途を拡張するいくつかの新しい機能が組み込まれている。

  • "Graph Spy": GraphEdit は外部プロセスによって作成されたフィルタ グラフをロードできる。この機能を使用すると、アプリケーションにわずかなコードを追加するだけで、アプリケーションでビルドするフィルタ グラフを正確に知ることができる。この機能の詳細については、「外部プロセスからのグラフのロード」を参照すること。
  • フィルタ情報 : [Graph] メニューの [Insert Filters] をクリックすると表示されるフィルタの一覧に、利点、ピンの数、各ピンに対して登録されているメディア タイプなど、各フィルタの登録情報が示されるようになった。この情報は、ツリー表示で各フィルタの横にあるプラス (+) 記号をクリックすると表示される。

GraphEdit の詳細については、「GraphEdit によるグラフ構築のシミュレーション」を参照すること。

DirectX Media Object

DirectX Media Object (DMO) は、データ ストリーミング コンポーネントを作成する新しい方法である。DirectShow フィルタと同様に、DMO は入力データを受け取り、それを使用して出力データを生成する。ただし、DMO のアプリケーション プログラミング インターフェイス (API) は、DirectShow の API よりも非常に簡単である。そのため、DMO は DirectShow フィルタよりも簡単に作成、テスト、および使用できる。

DMO は DirectShow と完全な互換性がある。DMO は、DirectShow に提供されているグラフ同期化、インテリジェント接続、データ フローの自動処理、スレッド管理などのサービスが必要な場合に、フィルタと同じように使用できる。ただし、DMO はフィルタ グラフを必要としないため、アプリケーションでは DirectShow を使わずに DMO を使用できる。

詳細については、「DirectX Media Object」を参照すること。

メディア パラメータ

メディア パラメータは、オブジェクトのプロパティに対する実行時の変更をサポートする新しい API のセットである。メディア パラメータを使用すると、急速に変化し、高いパフォーマンスと反復性の両方が要求されるプロパティを正確に制御できる。メディア パラメータを使用すると、プロパティによって正弦波や逆矩形曲線などの厳密なカーブをリアルタイムでフォローできる。

データ変換オブジェクトは、メディア パラメータを使用して、実行時の動作を制御する標準インターフェイスをサポートできる。メディア パラメータを DMO と組み合わせて使用すると、オーディオ エフェクトの作成で便利である。たとえば、エコー エフェクトでは、ドライ (未処理の) 信号に対するウェット (処理済み) 信号の比率がスムーズなカーブをフォローするようにすることができる。このような動作は、オーディオ エンジニアリングにおいてレコーディングに不自然な効果が導入されるのを防ぐために重要である。

詳細については、「メディア パラメータ」を参照すること。


DirectShow でサポートされるフォーマット

DirectShow® はオープン アーキテクチャである。つまり、解析およびデコードを行うフィルタがある限り、どのようなフォーマットでもサポートできる。Microsoft が提供するフィルタは、DirectShow を通じて再配布されるものであっても、Windows オペレーティング システムのコンポーネントとして提供されるものであっても、以下のファイル フォーマットと圧縮フォーマットをデフォルトでサポートする。

注 アスタリスク (*) は、DirectShow アプリケーションも Windows Media Format SDK を使ってこのフォーマットをサポートしなければならないことを示す。詳細については、「Windows Media and DirectShow: Choices for Windows-based Media Applications」を参照すること。

ファイル フォーマット

  • Windows Media™ Audio (WMA)*
  • Windows Media™ Video (WMV)*
  • ASF (Advanced Streaming Format)*
  • Motion Picture Experts Group (MPEG)
  • Audio-Video Interleaved (AVI)
  • QuickTime (version 2 以前)
  • WAV
  • AIFF
  • AU
  • SND
  • MIDI

圧縮フォーマット

  • Microsoft Windows Media Video CODEC version 7.0*
  • ISO MPEG-4 video version 1.0*
  • Microsoft MPEG-4 version 3*
  • Sipro Labs ACELP*
  • Windows Media Audio*
  • MPEG Audio Layer-3 (MP3) (圧縮解除のみ)
  • Digital Video (DV)
  • MPEG-1
  • MJPEG
  • Indeo
  • Voxware*
  • Cinepak

Microsoft では、MPEG-2 デコーダを提供していない。いくつかの DirectShow 互換ハードウェアとソフトとウェアの MPEG-2 デコーダが、サード パーティーから利用可能である。

DirectShow アプリケーションで再配布するために、サード パーティーの CODEC が利用可能かどうかについては、CODEC の製造元に問い合せること。


DirectShow FAQ

ここには、Microsoft® DirectShow® に関するよくある質問の答えが集められている。内容は次のとおりである。

  • 一般的な質問
  • プログラミングに関する質問

一般的な質問

Q: DirectShow がサポートしているオペレーティング システムは?

A: DirectShow は、Microsoft® Windows® 9x、Microsoft® Windows® 2000、および Microsoft® Windows® Me をサポートしている。

Q: DirectShow プログラムするのにどのような COM 知識が必要か？

A: アプリケーション開発者にとって COM オブジェクトで処理するための基本的な理解 (インスタンス化、公開するインターフェイスへのアクセス方法、そのインターフェイスの参照カウントの正しい管理) は必要である。フィルタ開発者にはもう少し COM の知識が必要な場合がある。詳細については、このヘルプ ファイルの「DirectX 8.0 の紹介」にある「C または C++ による DirectX プログラミング」を参照すること。

Q: どのようなフォーマットを DirectShow はサポートするのか？

A: 「DirectShow でサポートされるフォーマット」を参照すること。

Q: DirectShow ハードウェア互換性リスト (HCL) は存在するのか？

A: いいえ。DirectShow は使用可能な場合は Microsoft® DirectDraw® および Microsoft® DirectSound® ハードウェア能力を使用する。専用ハードウェアが使用できない場合、DirectShow は GDI を使用してビデオを描画し、waveOut* マルチメディア API を使用してオーディオを再生する。

Q: DirectShow アプリケーションを書くにはどのような言語が使えるのか？

A: DirectShow は主に C++ 開発用に設計されている。(C を使うことも可能) Microsoft® Visual Basic® でDirectShow API のかなりのサブセットにアクセスできるが、Visual Basic のサポートは完全ではない。DirectShow はスクリプト ベースの DVD アプリケーションをサポートしている、これは Microsoft® JScript® あるいは Visual Basic Scripting Edition を使用する。DirectShow アプリケーションを Borland Delphi を使って書くことも可能だが、SDK ドキュメントはそれについては説明していない。

詳細については、以下のトピックを参照すること。

  • C によるフィルタ グラフの制御
  • Visual Basic での DirectShow の使用
  • スクリプト ベースの DVD アプリケーションの記述

Q: DirectShow での開発に必要なコンパイラは?

A: コンパイラの環境を正しく設定すれば、Component Object Model (COM) オブジェクトの生成が可能な任意のコンパイラを使用できる。Microsoft® Visual C++® 以外のコンパイラを使用する場合は、コンパイラ間の相違のため基底クラス ライブラリの再ビルドが必要なことがある。

Q: DirectShow は Microsoft® Windows Media™ とどう関連しているのか？

A: 「Windows Media アプリケーション」を参照すること。

Q: DirectShow は Microsoft® DirectX® のほかのコンポーネントとどう関連しているのか？

A: 内部的には、ハードウェアがサポートするとき、DirectShow は DirectSound と DirectDraw を使用する。(ビデオ レンダラは DirectDraw 7 のサーフェイスを使用する。新しい Microsoft® Direct3D® API は使用しない。) DirectShow アプリケーションを書くために他の DirectX API を使う必要はない、しかしそれらを組み合わせることは可能である。たとえば、「テクスチャ 3D サンプル」を参照すること。

DirectShow の前のバージョンは 6.0 であった。それはもともと DirectX Media SDK と共に出荷された。DirectX Media SDK がなくなったので、DirectShow は DirectX SDK に移った、そしてそのため DirectShow のバージョン数は 6.0 から 8.0 にジャンプした。

Q: DirectShow は Microsoft® ActiveMovie® とどう関連しているのか？

A: ActiveMovie は DirectShow のもともとの名前だった。ActiveMovie という言葉はもう使われていない。

Q: DirectShow はマルチメディア アプリケーションに限定されているのか？

A: DirectShow に含まれているデフォルトコンポーネントはマルチメディア用に設計されている。しかしDirectShow アーキテクチャは別の種類のデータストリーミング ソリューションにも有効である。

Q: GraphEdit ユーティリティのソースは公開されているか? GraphEdit は再配布できるか?

A: ソースは公開されていない。Graphedt.exe は再配布できない。

Q: DMO は DirectShow フィルタに置き替わるのか？

A: Microsoft® DirectX® メディア オブジェクト (DMO) は DirectShow アプリケーション内で使用可能である。エンコーダ、デコーダ、エフェクトについては、DirectShow フィルタの代わりに DMO を書くことを勧める。それ以外の目的では、DirectShow フィルタがより適切かもしれない。詳細については、「DirectX Media Object」を参照すること。

Q: より詳細な情報はどこで取得できるのか？

  • World Wide Web:MSDN DirectX Developer Center
  • メーリング リスト : http://discuss.microsoft.com/archives/DIRECTXAV.html。 以下はその特徴の一部である。

    このメーリングリストの基本的な機能は Microsoft の ストリーミング テクノロジ (DirectShoud、DirectMusic、DirectShow) を使っている開発者やコンテンツ クリエータたちが情報やアイデアを交換できることにある。このメーリング リストは初心者から上級開発者までのすべてのレベルの DirectX 専門知識を提供する。

    複数の Microsoft DirectX 開発チームがメーリング リストのトピックを読み、可能なコメントを書くと期待されているが、DirectXAV は Microsoft サポート フォーラムに替わるためのものではなく、Microsoft の人間が直接質問に答えることが保証されているわけではない。多くの場合、最も優れた援助は DirectXAV コミュニティの他のメンバである、彼らは過去に自分自身で同じような問題に直面してきているからだ。

    このメーリング リストに含まれるべきトピックス : DirectMusic Producer を使った作曲テクニック、オーディオ、音楽、ストーミング ビデオ プログラミング テクニック、サウンド デザイン テクニック、関係する API についての一般的な問題や情報、コードの断片、提案、ヒントとティップス、デバイス ドライバ品質、将来フィーチャーの要求、API を使った実際の経験、等。

    DirectX DEV を購読するには、メッセージ本文にsubscribe directxdev と書いて LISTSERV@discuss.microsoft.com にメールを送ること。DirectX A/V を購読するには、メッセージ本文に subscribe directxav と書いて LISTSERV@discuss.microsoft.com にメールを送ること。

  • UseNet: microsoft.public.multimedia.directx.dshow.programming

Q: アプリケーション / フィルタを開発する上で困難な問題に直面している。開発サポートはどこで受けられるのか？

A: 「マイクロソフト サポート技術情報」に連絡すること。

Q: DirectShow を説明する良い本はあるか？

A: 現在、DirectShow 専用の本はない、次のような既存の DirectX の本の中で DirectShow は少し説明されている。

  • Sams Teach Yourself DirectX in 24 Hours by Robert Dunlop, Dale Shepherd, and Mark Martin (Sams)
  • DirectX, RDX, RSX, and MMX Technology by Rohan Coelho and Maher Hawash (Addison Wesley)

DirectShow はこれらの本で少し触れられているが、最も優れた情報ソースは DirectX SDK で提供される DirectShow ドキュメントとサンプル コードである。

Q: フィードバックとバグレポートをするには、どのように Microsoft にコンタクトすれば良いのか？

A: 一般的な DirectX の問題についてのアドレスは directx@microsoft.com である。バグ レポートの送り先は dxbugs@microsoft.com である。

Q: Microsoft による DirectShow 改善方法のアイデアを持っている。

A: Microsoft は提案、質問、コメントを歓迎します。あなたの考えを教えてください。何が我々に欠けているのか？どの分野を最も改善すべきだと考えるのか？どのようなチュートリアルとサンプルが必要と考えるのか？あなたの提案が将来の作業の優先順位付けに役立つことでしょう。新しい DirectShow ドキュメントに関連する質問や提案があれば、メッセージを askdshow@microsoft.com に送ってください。

Q: Windows Media Player で AVI ファイル フォーマットを再生している。オーディオは聞こえるのだが、その代わりビデオを見ることができない、黒い画面だけが見える。何が悪いのか？

A: 多分そのファイルはあなたのシステムでサポートされていない CODEC でエンコードされている。AVI ファイル フォーマットは共通ではあるが、AVI ファイルは多くの異なった CODEC (coder/decoder) で作成し得る。AVI ファイルをサポートされていない CODEC を使用して再生すると、オーディオ コンポーネントは聞こえるかもしれないが、ビデオは黒いスクリーンが表示されるか、スクリーン コンテンツが変更できないままになる。

注 Windows Media Player は多くの場合、システムに CODEC がない場合、その CODEC をダウンロード、インストールしようとする。

Windows 2000 に含まれているいくつかの共通の CODEC は、Radius Cinepak、Duck TrueMotion、Intel Indeo、Microsoft RLE、そして Microsoft Video 1 である。Windows 2000 システムの ビデオ CODEC のリストを見るには次のようにする。

  1. コントロール パネルを開く。
  2. [サウンドとマルチメディア] をクリックする。
  3. [ハードウェア] タブをクリックする。
  4. [ビデオ CODEC] を選択する。
  5. [プロパティ] をクリックする。
  6. [プロパティ] タブをクリックする。

Q: あるメディア ファイルにどの CODEC が使われているのかを知る方法は？

A: 以下のようにすること。

  • Explorer でファイルを右クリックする。
  • [プロパティ] をクリックする。
  • [Summary] タブをクリックする。

プログラミングに関する質問

Q: どのようにアプリケーションをビルドするのか？どのライブラリ ファイルとヘッダー ファイルが必要なのか？

A: 「ビルド環境の設定」を参照すること。

Q: GraphEdit がドキュメントにない多くのフィルタを表示する。これらのフィルタは何か？

A: GraphEdit はあるフィルタ カテゴリでシステムに登録されているすべてのフィルタを列挙する。これはサードパーティ アプリケーションがインストールしたフィルタや Windows Media のような他の Microsoft テクノロジがインストールしたフィルタを含んでいる。またある DirectShow フィルタは CODEC やハードウェア デバイスのラッパーとして動作する、各 CODEC やデバイスは別のフィルタとして表示される。詳細については、「デバイスとフィルタの列挙」を参照すること。

Q: プログラム的にフィルタの追加と接続をするカスタム グラフの構築で問題がある。どのようにしてこれに対する援助を得ることができるのか？

A: 最初にすべてを Filter Graph Editor (GraphEdit) で構築すること。このツールを使えば、多くの可能性をすばやくシミュレートでき、問題を視覚的に修正することができる。GraphEdit は通常、ソース コードで構築しようとする前にグラフを構築する優れた場所である。

追加情報: ソースとビデオレンダラの間のインテリジェント接続を行っているなら、ソースとレンダラの間に正しいメディア タイプ変換を行う一連のフィルタの挿入を DirectShow に教える。そのソース フィルタはオーディオとビデオが入る 1 つの出力を持つ。それゆえ、オーディオとビデオを別のストリームにするフィルタ (デマルチプレックス) が追加されなければならない。従ってしなければならないことはオーディオ レンダラをデマルチプレクサのオーディオ ピンに接続することである。ソース メディア タイプによって、使われるデマルチプレクサは複数のフィルタのうちの 1 つとなる場合がある。AVI については、AVI スプリッタがその仕事を行う。MPEG2 では、MPEG2 スプリッタか MPEG-2 デマルチプレクサとなるであろう。スマート接続を使用しているなら、デマルチプレクサを見つけ、オーディオ ピンを見つけ。次にレンダラに接続しなければならない。

容易な方法を希望するなら :

  • ソース フィルタを追加する
  • 持っている任意のアプリケーション固有のレンダラを追加する。
  • 出力ピンで "Render" を呼び出す。

これはグラフ内にある出力ピンに対応するレンダラを持っている場合の "Connect" と等価である、しかし 1 つも持っていないならレンダラを追加するであろう。したがってオーディオもビデオも両方接続されるはずである。

Q: 特定のマシンに DirectShow がインストールされているかどうかを確認する方法は?

A: CoCreateInstance を呼び出してフィルタ グラフ マネージャのインスタンスを作成する。この呼び出しが成功した場合は、DirectShow がマシンにインストールされている。次のコードに呼び出しの方法を示す。

IGraphBuilder *pGraph;

HRESULT hr = CoCreateInstance(CLSID_FilterGraph,
    NULL, CLSCTX_INPROC_SERVER,
IID_IGraphBuilder, (void **) &pGraph);

Q: プロパティ ページを表示せずにフィルタの設定を変更する方法は?

A: ほとんどのフィルタは、フィルタのプロパティを設定するための 1 つ以上のインターフェイスを公開している。目的のフィルタのリファレンス ページを調べること (「フィルタ」を参照)。

Q: なぜ「ASF ライタ」と「ASF リーダー」フィルタが使えないのか？

A: アプリケーションをビルドするとき、ソフトウェアの認証を提供しなければならない。「DirectShow での ASF ファイルの作成」および「 Windows Media Format SDK」を参照すること。また GraphEdit 内でこれらのフィルタを使うことはできない。

Q: DirectShow は現在の再生位置を定期的にアプリケーションに通知できるか?

A: 位置のコールバック通知は行われない。タイマを使用し、IMediaSeeking::GetCurrentPosition メソッドを使って現在の位置を取得すること。

Q: フィルタを書いたが、どのようにしてインストールすればよいか?

A: 「DirectShow オブジェクトの登録方法」を参照すること。

Q: GraphEdit で自分のフィルタをテストできるか？

A: フィルタ開発中に GrapEdit はフィルタ間の接続を視覚化し、援助する。GraphEdit はフィルタ機能のクイック テストをも提供する。しかし、それは豊富なテスト プラットフォームではない。詳細については、「GraphEdit によるグラフ構築のシミュレーション」を参照すること。

Q: フィルタ内のピンの数を確認する方法は?

A: S_OK 以外の値を返すまで IBaseFilter::EnumPins メソッドを呼び出し、次に IEnumPins::Next メソッドを呼び出す。詳細については、「フィルタ グラフ内のオブジェクトの列挙」を参照すること。

Q: フィルタはどの権限リングで動作するか?

A: フィルタはリング 3 で動作する。しかし、ストリーミング デバイスを制御するフィルタはリング 0 で動作するものがある。「ハードウェア デバイスがフィルタ グラフに参加する方法」を参照すること。


ファースト ステップ ガイド

ここでは、アプリケーション開発に必要な Microsoft® DirectShow® の基本概念を説明する。DirectShow の概要紹介として読むことができる。ここに示すトピックは、プログラミングとメディアに関する一般的な知識さえあれば理解できる内容になっている。

  • DirectShow アプリケーション プログラミングの概要
  • ビルド環境の設定
  • ファイルの再生法
  • ビデオ ウィンドウの設定
  • イベントへの応答


DirectShow アプリケーション プログラミングの概要

ここでは、Microsoft® DirectShow® アプリケーションを作成するために必要な、基本的な用語と概念について説明する。DirectShow で使用される専門用語についても説明する。この内容を読むと、初めての DirectShow アプリケーションを作成する準備が整う。

ここでは次の内容について説明する。

  • フィルタ グラフ
  • DirectShow アプリケーションの作成

フィルタ グラフ

DirectShow を構成する基本要素は、フィルタと呼ばれるソフトウェア コンポーネントである。フィルタは、通常、マルチメディア ストリームに対して単一の操作を実行する。たとえば、DirectShow には次のようなフィルタがある。

  • ファイルを読む。
  • ビデオ キャプチャ デバイスからビデオを取得する。
  • MPEG-1 ビデオなどの特定のストリーム フォーマットをデコードする。
  • グラフィック カードまたはサウンド カードにデータを渡す。

フィルタは入力を受け取り、出力を生成する。たとえば、フィルタが MPEG-1 ビデオをデコードする場合、入力は MPEG でエンコードされたストリームであり、出力は圧縮されていない RGB ビデオ ストリームである。

指定されたタスクを実行するために、アプリケーションでは複数のフィルタを接続し、1 つのフィルタからの出力を別のフィルタの入力とする。接続されたフィルタの集合は、フィルタ グラフと呼ばれる。この概念を表す図として、AVI ファイルを再生するフィルタ グラフを次に示す。

AVI ファイルを再生するフィルタ グラフ

アプリケーションではフィルタ グラフの個々のフィルタを管理する必要がない。DirectShow にはフィルタ グラフ マネージャと呼ばれる上位レベルのコンポーネントが用意されている。フィルタ グラフ マネージャは、グラフを通過するデータの流れを制御する。アプリケーションでは、"Run" (グラフの開始から終わりまでデータを移動する) や "Stop" (データの流れを停止する) などの上位レベルの API 呼び出しを行う。ストリーム操作をより直接的に制御する必要がある場合は、COM インターフェイスを通してフィルタに直接アクセスすることができる。また、フィルタ グラフ マネージャはアプリケーションにイベント通知を渡す。それによって、アプリケーションでストリームの終わりなどのイベントに応答できる。

さらに、フィルタ グラフ マネージャを使用すると、フィルタ グラフを構築するプロセスが簡単になる。たとえば、ファイル名を指定すると、そのファイルを再生するグラフがフィルタ グラフ マネージャによって構築される。

DirectShow アプリケーションの作成

一般的な DirectShow アプリケーションは、次の図に示す 3 つの基本的な手順を実行する。

一般的な DirectShow アプリケーション

  1. CoCreateInstance 関数を使用してフィルタ グラフ マネージャのインスタンスを作成する。
  2. フィルタ グラフ マネージャを使用してフィルタ グラフを構築する。ほかの DirectShow ヘルパー コンポーネントを使用することもできる。
  3. フィルタ グラフを制御し、イベントに応答する。

DirectShow で作業を開始するには、「ファイルの再生法」を参照すること。ファイルを再生する簡単なコンソール アプリケーションが示されている。このアプリケーションは、従来の "Hello World" プログラムの DirectShow 版である。「ビデオ ウィンドウの設定」および「イベントへの応答」では、そのプログラムを簡単な Windows アプリケーションに拡張している。


ビルド環境の設定

このトピックでは、Microsoft® DirectShow® のアプリケーションとフィルタをビルドする方法を説明する。プロジェクトの構築は、コマンド ラインから行うことも、Microsoft® Visual C++® に同梱されている Microsoft® Visual Studio® 環境から行うこともできる。

  • DirectShow アプリケーションのビルド
  • DirectShow フィルタのビルド

DirectShow アプリケーションのビルド

ヘッダー ファイル

すべての DirectShow アプリケーションでは、次の表のヘッダー ファイルが使用される。

ヘッダー ファイル | 用途
Dshow.h | すべての DirectShow アプリケーション

DirectShow インターフェイスによっては、追加のヘッダー ファイルが必要なこともある。その詳細は、インターフェイスの説明に含まれている。

ライブラリ ファイル

DirectShow では、次の表のライブラリ ファイルが使用される。

ライブラリ ファイル | 説明
Strmiids.lib | クラス識別子 (CLSIDs) とインターフェイス識別子 (IIDs) のエクスポート。すべての DirecShow アプリケーションにはこのライブラリが必要。
Quartz.lib | AMGetErrorText 関数をエクスポート。この関数を呼び出さないなら、このライブラリは必要ない。
Strmbase.lib | DirectShow 基底クラスを使う場合のみ必要。

ビルド環境においては、SDK インクルード ディレクトリとライブラリ ディレクトリは、検索パスの最初のディレクトリとすべきである。これによってこれらのファイルの最新バージョンが使用できる。

DirectShow フィルタのビルド

DirectShow フィルタをビルドする場合には、これまでのセクションで説明したステップのほかに、以下のステップを実行する必要がある。

  • __stdcall 呼び出し規則を使用する。
  • リテール ビルドでは、プリプロセッサ フラグ RELEASE を追加する。デバッグ ビルドでは、プリプロセッサ フラグ DEBUG を追加する。
  • エントリ ポイントのシンボルを DllEntryPoint@12 に設定する。
  • フィルタを DLL として実装する場合は、DLL 関数をエクスポートする定義ファイル (.def ファイル) をインクルードする。定義ファイルの一例を以下に示す。フィルタの出力ファイルは Filter.dll と想定されている。
    LIBRARY FILTER.DLL
DESCRIPTION 'Description of my filter'
PROTMODE
EXPORTS
    DllGetClassObject
    DllCanUnloadNow
    DllRegisterServer
    DllUnregisterServer
  • フィルタで SDK のフィルタ基底クラスを使用する場合には、基底クラスを構築し、リンクする必要がある。詳細については、「DirectShow 基底クラスの使い方」を参照すること。


ファイルの再生法

このトピックでは、Microsoft® DirectShow® でメディア ファイルを再生する方法を説明し、メディア ファイルを再生する C++ のサンプル プログラムを示す。このプログラムは、古典的な "Hello World" プログラムの DirectShow 版である。

このトピックは、以下のセクションで構成される。

  • ファイルの再生
  • サンプル コード

ファイルの再生

DirectShow を使ったファイルの再生は、以下の 4 段階の処理で行われる。

  1. フィルタ グラフ マネージャのインスタンスを生成する。
  2. フィルタ グラフ マネージャを使って、フィルタ グラフを作成する。
  3. フィルタ グラフ マネージャを使って、フィルタ グラフを実行する。
  4. 再生が終了するのを待つ。

この処理には、以下の COM インターフェイスが必要である。

  • IGraphBuilder: フィルタ グラフを構築する。
  • IMediaControl: フィルタ グラフ内のメディア ストリーミングを処理する。
  • IMediaEvent: フィルタグラフ イベントのハンドル。

フィルタ グラフ マネージャはこれらのインターフェイスすべてを実装する。

COM ライブラリを初期化する CoInitialize 関数を呼び出すことによって開始する。次に CoCreateInstance 関数を呼び出し、フィルタグラフ マネージャを作成する :

IGraphBuilder *pGraph;
CoInitialize(NULL);
CoCreateInstance(CLSID_FilterGraph, NULL, CLSCTX_INPROC_SERVER,
                    IID_IGraphBuilder, (void **)&pGraph);

CoCreateInstance 関数はフィルタグラフ マネージャの IGraphBuilder インターフェイスを返す。このインターフェイス ポインタを使って、必要な 2 つのインターフェイス IMediaControl と IMediaEvent をクエリする :

IMediaControl *pMediaControl;
IMediaEvent   *pEvent;
pGraph->QueryInterface(IID_IMediaControl, (void **)&pMediaControl);
pGraph->QueryInterface(IID_IMediaEvent, (void **)&pEvent);

プログラムの中心部分にきた :

pGraph->RenderFile(L"C:\\Hello_World.avi", NULL);
pMediaControl->Run();
pEvent->WaitForCompletion(INFINITE, &evCode);

IGraphBuilder::RenderFile メソッドは、指定されたファイルを再生するフィルタ グラフを構築する。最初のパラメータは、ワイド文字 (2 バイト) の Unicode 文字列で表されたファイル名である。簡単であるため、サンプル プログラムでは、ユーザーにファイル名を選択させるのではなく、リテラル文字列を指定している。プリフィックス "L" を付けると、ASCII 文字列がワイド文字列に変換される。2 つめのパラメータは予約済みで、NULL でなければならない。

フィルタ グラフを構築すると、フィルタ グラフ マネージャは再生を開始することができる。IMediaControl::Run メソッドが、グラフを実行モードに切り換える。アプリケーションがこのメソッドを呼び出すと、メディア データはフィルタ グラフを通り始め、ビデオ、オーディオ、または両方としてレンダリングされる。

IMediaEvent::WaitForCompletion メソッドはファイルが再生されるまでブロックする。再生は別のスレッドで続けられる。実際のアプリケーションでは待ち時間を INFINITE にセットすべきではない、これは無制限にブロックしてしまうからだ。また他のフィルタグラフ イベントに対応したい場合もある。イベント ハンドリングの詳細については、「イベントへの応答」を参照すること。

更に、実際のアプリケーションでは、RenderFile の戻り値をテストしフィルタグラフの作成が成功したことを確認すべきだ。たとえば、指定したファイルがない場合、RenderFile は失敗しエラーコード VFW_E_NOT_FOUND を返す。

最終的に、すべてのインターフェイス ポインタと COM ライブラリを解放することでクリーンアップする :

pMediaControl->Release();
pEvent->Release();
pGraph->Release();
CoUninitialize();

サンプル コード

以下のサンプル コードはファイルを再生する :

#include <dshow.h>

void main(void)
{
    IGraphBuilder *pGraph;
    IMediaControl *pMediaControl;
    IMediaEvent   *pEvent;
    CoInitialize(NULL);

    // フィルタグラフマネージャを作成し、インターフェイスをクエリする。
    CoCreateInstance(CLSID_FilterGraph, NULL, CLSCTX_INPROC_SERVER,
                        IID_IGraphBuilder, (void **)&pGraph);
    pGraph->QueryInterface(IID_IMediaControl, (void **)&pMediaControl);
    pGraph->QueryInterface(IID_IMediaEvent, (void **)&pEvent);

    // グラフを作成。重要: 使用システムのファイル文字列に変更すること。
    pGraph->RenderFile(L"C:\\Hello_World.avi", NULL);

    // グラフの実行。
    pMediaControl->Run();

    // 終了を待つ。
    long evCode;
    pEvent->WaitForCompletion(INFINITE, &evCode);

    // クリーン アップ。
    pMediaControl->Release();
    pEvent->Release();
    pGraph->Release();
    CoUninitialize();
}


ビデオ ウィンドウの設定

このトピックでは、特定のウィンドウにビデオ再生をアタッチする方法を解説する。サンプル プログラムを示し、サンプルを理解するために必要な考え方を説明する。このサンプル プログラムは、「ファイルの再生法」で示したサンプルを基にしている。

このトピックは以下のセクションで構成される。

  • ビデオ ウィンドウ
  • IVideoWindow インターフェイスの使用
  • サンプル コード

ビデオ ウィンドウ

ビデオ ファイルをレンダリングするとき、フィルタ グラフにはビデオ レンダリング フィルタが含まれる。ビデオ レンダラは、圧縮されていないビデオ データを受け取り、ウィンドウ内の画面にそれをレンダリングする。指定しなければ、ビデオ再生ウィンドウは、自身の境界とタイトル バーを持つトップレベルのウィンドウになる。しかし、アプリケーションで作成した特定のウィンドウにビデオを表示することの方が多い。解決策は、レンダラのビデオ ウィンドウをアプリケーション ウィンドウの子ウィンドウにすることである。これを行うには、ビデオ ウィンドウのプロパティを設定して、ウィンドウの所有者、スタイル、および位置を指定する。

ビデオ レンダリング フィルタがサポートする IVideoWindow インターフェイスに、ビデオ ウィンドウのプロパティを設定および取得するためのメソッドが含まれている。しかし、フィルタ グラフ マネージャを使ってフィルタ グラフを構築した場合は、ビデオ レンダリング フィルタへのポインタを持っているとは限らない。そのため、フィルタ グラフ マネージャも IVideoWindow をサポートしている。フィルタ グラフ マネージャは、グラフ内で IVideoWindow を公開しているフィルタのリストを保持し、フィルタ グラフ マネージャの IVideoWindow メソッドが呼び出されると、これらのフィルタへの呼び出しを割り当てる。このようにして、アプリケーションが適切なフィルタを見つけなくても、フィルタ グラフ マネージャがそれぞれのフィルタの処理をサポートできる。

フィルタ グラフ マネージャは、これと同じ手法で IBasicVideo2 および IBasicAudio インターフェイスを公開している。これらのインターフェイスには、オーディオおよびビデオのプロパティを設定するためのメソッドが含まれる。それぞれのフィルタに対してこれらのインターフェイスを呼び出すのではなく、フィルタ グラフ マネージャに対して呼び出す。

IVideoWindow インターフェイスの使用

このセクションでは、IVideoWindow インターフェイスを使って所有者やスタイルなど、ビデオ ウィンドウのプロパティを設定する方法を説明する。

注 : このトピックのサンプル プログラムでは、コードの大部分は標準のウィンドウ処理を行うものなので、ここでは説明しない。特に、WindowProc および WinMain 関数には、Microsoft® Windows® アプリケーションの典型的なフレームワークが含まれている。アプリケーションで定義する関数、PlayFile および CleanUp については説明する。

まず、フィルタ グラフ マネージャのインスタンスを生成し、IGraphBuilder::RenderFile メソッドを呼び出してフィルタ グラフを構築する。この処理の詳細については、「ファイルの再生法」を参照すること。

次に、再生を始める前に、以下のようにビデオ ウィンドウのプロパティを設定する。

  1. ビデオ再生ウィンドウを親ウィンドウにアタッチする。これを行うには、IVideoWindow::put_Owner メソッドを呼び出して、所有者ウィンドウへのハンドルを渡す。このメソッドは OAHWND 型の変数を受け取るため、必要な場合はハンドルをこの型にキャストする。
    IVideoWindow    *pVidWin = NULL;
pGraph->QueryInterface(IID_IVideoWindow, (void **)&pVidWin);
pVidWin->put_Owner((OAHWND)g_hwnd);
  2. ビデオ ウィンドウのスタイルを子ウィンドウに変更する。これを行うには、IVideoWindow::put_WindowStyle メソッドを呼び出して、スタイル フラグの組み合わせを渡す。WS_CHILD フラグは、ウィンドウが子ウィンドウであることを指定する。WS_CLIPSIBLINGS フラグは、ウィンドウがほかの子ウィンドウの内部に描かれないようにする。
    pVidWin->put_WindowStyle(WS_CHILD | WS_CLIPSIBLINGS);
  3. ビデオ ウィンドウの位置を設定する。これには、IVideoWindow::SetWindowPosition メソッドを呼び出す。このメソッドは、ウィンドウの左端 (x-軸)、上端 (y-軸)、幅、高さを指定するデバイス座標を受け取る。サンプル プログラムでは、親ウィンドウの全体が入るようにビデオ ウィンドウを拡大している。
    RECT grc;
GetClientRect(g_hwnd, &grc);
pVidWin->SetWindowPosition(0, 0, grc.right, grc.bottom);

    GetClientRect 関数は、RECT 構造体をウィンドウのクライアント領域の座標で満たす。この座標は、クライアント領域の左上隅からのものであるため、left および top メンバは 0 で、right および bottom メンバがそれぞれ幅と高さを定義する。

アプリケーションが終了する前に、ビデオ ウィンドウの表示を False に設定することが重要である。そうしないと、ビデオ イメージが画面に残り、ユーザーはそれを除去することができない。次に、所有者を NULL にリセットする。そうしないと、間違ったウィンドウにメッセージが送信され、エラーが発生する可能性がある。

HRESULT hr = pVidWin->put_Visible(OAFALSE);
hr = pVidWin->put_Owner(NULL);

サンプル コード

以下のサンプル プログラムは、Test.avi という名前のファイルをアプリケーション ウィンドウの内部にレンダリングする。簡単であるため、以下の機能は省略している。

  • 親ウィンドウのサイズが変更されたとき、ビデオ ウィンドウのサイズを変更しない。これを行うには、親ウィンドウの WM_SIZE メッセージに応えて、IVideoWindow::SetWindowPosition をもう一度呼び出す。
  • エラー チェックは行わない。
  • ソースのアスペクト比を考慮せずに、ビデオ ウィンドウを拡大する。アスペクト比を調べるには、IBasicVideo インターフェイスを使用する。
  • エンドオブストリーム イベントは扱わない。この方法については、「イベントへの応答」を参照すること。
#include <windows.h>
#include <dshow.h>

#define CLASSNAME "VideoWindow"

IGraphBuilder   *pGraph = NULL;
IMediaControl   *pMediaControl = NULL;
IVideoWindow    *pVidWin = NULL;
HWND            g_hwnd;

void PlayFile(void)
{
    // フィルタ グラフ マネージャを生成する。
    CoCreateInstance(CLSID_FilterGraph, NULL, CLSCTX_INPROC,
        IID_IGraphBuilder, (void **)&pGraph);
    pGraph->QueryInterface(IID_IMediaControl, (void **)&pMediaControl);
    pGraph->QueryInterface(IID_IVideoWindow, (void **)&pVidWin);

    // グラフを構築する。
    pGraph->RenderFile(L"Test.avi", NULL);

    // ビデオ ウィンドウを設定する。
    pVidWin->put_Owner((OAHWND)g_hwnd);
    pVidWin->put_WindowStyle(WS_CHILD | WS_CLIPSIBLINGS);

    RECT grc;
    GetClientRect(g_hwnd, &grc);
    pVidWin->SetWindowPosition(0, 0, grc.right, grc.bottom);

// グラフを実行する。
    pMediaControl->Run();
}

void CleanUp(void)
{
    pVidWin->put_Visible(OAFALSE);
    pVidWin->put_Owner(NULL);
    pMediaControl->Release();
    pVidWin->Release();
    pGraph->Release();
}

// メッセージ ハンドラ
long FAR PASCAL WindowProc( HWND hwnd, UINT msg, UINT wParam, LONG lParam)
{
    switch (msg)
    {
        case WM_DESTROY:
            CleanUp();
            PostQuitMessage(0);
            break;
        default:
            return (DefWindowProc(hwnd, msg, wParam, lParam));
    }
    return(NULL);
}

// メイン
int PASCAL WinMain( HINSTANCE hInst, HINSTANCE hPrevInst, LPSTR  lpCmdLine,
    int nCmdShow )
{
    MSG         msg;
    WNDCLASS    wc;

    CoInitialize(NULL);

    ZeroMemory(&wc, sizeof wc);
    wc.lpfnWndProc  = WindowProc;
    wc.hInstance    = hInst;
    wc.hIcon        = LoadIcon( NULL, IDI_APPLICATION );
    wc.hCursor      = LoadCursor( NULL, IDC_ARROW );
    wc.hbrBackground = (HBRUSH)GetStockObject( BLACK_BRUSH );
    wc.lpszMenuName = NULL;
    wc.lpszClassName = CLASSNAME;
    RegisterClass( &wc );

    g_hwnd = CreateWindow(
        CLASSNAME,
        "DirectShow Sample",
        WS_OVERLAPPEDWINDOW,
        CW_USEDEFAULT,
        CW_USEDEFAULT,
        CW_USEDEFAULT,
        CW_USEDEFAULT,
NULL,
NULL,
        hInst,
        NULL);

    ShowWindow( g_hwnd, nCmdShow );
    UpdateWindow( g_hwnd );
    PlayFile();

    while( GetMessage( &msg, NULL, 0, 0 ) )
    {
        TranslateMessage( &msg );
        DispatchMessage( &msg );
    }

    CoUninitialize();
    return msg.wParam;
}


イベントへの応答

このトピックでは、Microsoft® DirectShow® アプリケーションで発生するイベントに応答する方法を解説する。ビデオ ウィンドウの設定で示したサンプルに基づくサンプル プログラムを示すが、サンプルのすべてのコードは示さず、追加が必要な約 25 行のコードについてのみ説明する。

このトピックは、以下のセクションで構成される。

  • イベント通知の動作
  • イベント通知の使い方
  • サンプル コード

イベント通知の動作

DirectShow アプリケーションの実行中は、さまざまな時点でフィルタの状態が変化する。たとえば、フィルタはポーズ状態から実行状態になったり、ストリーム内でエラーに出くわしたり、ビデオ ウィンドウの再描画を要求したりする。フィルタ グラフ マネージャに変化を知らせるために、フィルタは"イベント通知"を送信する。イベント通知は、イベントのタイプを示すイベント コードと、追加情報を与える 2 つのパラメータからなる。パラメータの意味は、イベント コードによって異なる。イベント コードとそのパラメータの完全なリストについては、「イベント通知コード」を参照すること。

フィルタ グラフ マネージャは、ビデオ ウィンドウの再描画の要求など、一部のイベントについてはアプリケーションに通知せずに処理を行い、その他のイベントはキューに入れる。アプリケーションは、キュー内のイベントを順番に取り出して処理する。DirectShow のイベント通知は、この点で Microsoft® Windows® のメッセージ キューイングと似ている。実際、新しいイベントが発生したとき、フィルタ グラフ マネージャに、指定したウィンドウに Windows メッセージを送信させることができる。アプリケーションは、この方法でウィンドウのメッセージ ループの中からイベントを処理することができる。

アプリケーションは、その目的に応じていくつかのイベント コードを扱う必要がある。ここでは、EC_COMPLETE と EC_USERABORT の 2 つに重点を置く。

  • レンダリング フィルタは、データ ストリームの終端に達すると EC_COMPLETE を通知済状態にする。フィルタ グラフには、ビデオ ストリームとオーディオ ストリームなど、複数のストリームが含まれる場合がある。各ストリームは、それぞれのレンダラに関連付けられているため、EC_COMPLETE イベントを別々に発生させる。フィルタ グラフ マネージャは、すべての EC_COMPLETE イベントをアプリケーションに転送するのではなく、グラフ内のすべてのストリームから EC_COMPLETE 通知を 1 つずつ受け取るまで待ち、すべての通知を受け取った時点で、1 つの EC_COMPLETE イベントをアプリケーションに送る。アプリケーションが EC_COMPLETE イベントを受け取ったとき、すべてのストリームは終了している。
  • EC_USERABORT イベントは、ユーザーが再生を中断したことを知らせる。ユーザーがビデオ ウィンドウを閉じると、ビデオ レンダラがこのイベントを送信する。

イベント通知の使い方

サンプル アプリケーションでは、ウィンドウのメイン メッセージ ループの中からイベントを処理する。そのために、新しいイベントが発生したとき、フィルタ グラフ マネージャにメッセージを送信させる。アプリケーションはそれに応えて、イベントを受け取り適切な処理を行う。

ウィンドウのメイン メッセージ ループの中からイベントを処理するために、新しいイベントが発生したときにアプリケーションに送信されるメッセージを定義する。以下の例に示すように、アプリケーションはプライベート メッセージとして、WM_APP ～ 0xBFFF の範囲のメッセージ番号を使用できる。

#define WM_GRAPHNOTIFY  WM_APP + 1

次に、このメッセージをアプリケーションのメイン ウィンドウに配信するように、フィルタ グラフ マネージャを設定する。

pEvent->SetNotifyWindow((OAHWND)g_hwnd, WM_GRAPHNOTIFY, 0);

IMediaEventEx::SetNotifyWindow メソッドは、指定されたウィンドウ (g_hwnd) をメッセージの受信者として指定する。フィルタ グラフを作成し、所有者ウィンドウを指定したら、グラフを実行する前にこのメソッドを呼び出す。詳細については、「サンプル コード」を参照すること。IMediaEventEx インターフェイスは、フィルタ グラフ マネージャが公開する。

アプリケーションが WM_GRAPHNOTIFY メッセージを受け取るとき、メッセージの lParam パラメータは、SetNotifyWindow に渡した 3 つめのパラメータと等しい。このパラメータを使用すれば、メッセージと共にインスタンス データを送ることができる。サンプル コードはこのデータを使用しないので、値 0 を渡す。メッセージの wParam パラメータは常に 0 である。

ウィンドウの WindowProc 関数に、WM_GRAPHNOTIFY メッセージ用の case ステートメントを追加する :

case WM_GRAPHNOTIFY:
    HandleEvent();
    break;

WM_GRAPHNOTIFY は、通常の Windows メッセージであり、DirectShow のイベント通知キューとは別に送信される。イベントのシーケンスは以下のとおりである。

  1. フィルタが、フィルタ グラフ マネージャにイベント通知を送信する。
  2. フィルタ グラフ マネージャはイベントを処理しない場合、イベントをイベント キューに入れる。
  3. フィルタ グラフ マネージャが、アプリケーション ウィンドウに WM_GRAPHNOTIFY メッセージを送信する。
  4. アプリケーションが、ウィンドウのメッセージ ループの中からメッセージに応答する。
  5. アプリケーションが、キューからイベント通知を取り出す。

イベント ハンドラ関数の中で IMediaEvent::GetEvent メソッドを呼び出して、キューからイベントを取り出す。

long evCode, param1, param2;
HRESULT hr;
while (hr = pEvent->GetEvent(&evCode, &param1, &param2, 0), SUCCEEDED(hr))
{
    hr = pEvent->FreeEventParams(evCode, param1, param2);
    if ((EC_COMPLETE == evCode) || (EC_USERABORT == evCode))
    {
        CleanUp();
        break;
    }
}

GetEvent メソッドは、イベント コードと 2 つのパラメータを取り出す。GetEvent への最後のパラメータは、このメソッドがイベントを待つ時間を指定する。アプリケーションは、WM_GRAPHNOTIFY メッセージに応えてこのメソッドを呼び出す。そのときイベントは既にキューに入っているので、タイムアウト値に 0 を指定する。

イベント通知とメッセージ ループはどちらも非同期で行われるため、アプリケーションがメッセージに応答するときまでに、キューには複数のイベントが入っている可能性がある。また、フィルタ グラフ マネージャは、イベントが無効になった場合にキューからイベントを消去することができる。そのため、キューが空であることを示す失敗コードが返されるまで GetEvent を呼び出す。

サンプル プログラムは、EC_COMPLETE または EC_USERABORT イベントを受け取ると、アプリケーションで定義された CleanUp 関数を呼び出す。この関数によって、アプリケーションは速やかに終了する。2 つのイベント パラメータ (param1 と param2) は無視される。イベントを取り出したら、IMediaEvent::FreeEventParams を呼び出して、イベント パラメータに関連するリソースを解放する。たとえば、パラメータが BSTR の場合、そのメモリはフィルタ グラフ マネージャによって割り当てられている。

EC_COMPLETE イベントが発生したとき、フィルタ グラフは自動的には停止状態に切り替わらないので、アプリケーションがグラフを停止またはポーズしなければならない。グラフが停止すると、フィルタは保持しているリソースを解放する。グラフがポーズした場合、フィルタはリソースを保持し続ける。なお、ビデオ レンダラはポーズしたとき、最新のフレームの静止画像を表示する。サンプル プログラムはグラフを停止する。

サンプル コード

以下のコードには、WinMain 関数や WindowProc 関数は含まれていない。これらの関数については、「ビデオ ウィンドウの設定」のサンプル コードを参照すること。
#include <windows.h>
#include <dshow.h>

#define WM_GRAPHNOTIFY  WM_APP + 1
#define CLASSNAME "EventNotify"

IGraphBuilder   *pGraph = NULL;
IMediaControl   *pMediaControl = NULL;
IMediaEventEx   *pEvent = NULL;
IVideoWindow    *pVidWin = NULL;
HWND            g_hwnd;

void PlayFile(void)
{
    // フィルタ グラフ マネージャを作成し、ファイルをレンダリングする。
    CoCreateInstance(CLSID_FilterGraph, NULL, CLSCTX_INPROC, IID_IGraphBuilder, (void **)&pGraph);
    pGraph->RenderFile(L"C:\\Media\\Boys.avi", NULL);

    // 所有者ウィンドウを指定する。
    pGraph->QueryInterface(IID_IVideoWindow, (void **)&pVidWin);
    pVidWin->put_Owner((OAHWND)g_hwnd);
    pVidWin->put_WindowStyle( WS_CHILD | WS_CLIPSIBLINGS);

    // イベント通知を受け取るように所有者ウィンドウを設定する。
    pGraph->QueryInterface(IID_IMediaEventEx, (void **)&pEvent);
    pEvent->SetNotifyWindow((OAHWND)g_hwnd, WM_GRAPHNOTIFY, 0);

// グラフを実行する。
    pGraph->QueryInterface(IID_IMediaControl, (void **)&pMediaControl);
    pMediaControl->Run();
}

void CleanUp(void)
{
    pVidWin->put_Visible(OAFALSE);
    pVidWin->put_Owner(NULL);

    // グラフを停止する。
    pMediaControl->Stop();

    pMediaControl->Release();
    pVidWin->Release();
    pEvent->Release();
    pGraph->Release();
    PostQuitMessage(0);
}

void HandleEvent()
{
    long evCode, param1, param2;
    HRESULT hr;
    while (hr = pEvent->GetEvent(&evCode, &param1, &param2, 0), SUCCEEDED(hr))
    {
        hr = pEvent->FreeEventParams(evCode, param1, param2);
        if ((EC_COMPLETE == evCode) || (EC_USERABORT == evCode))
        {
            CleanUp();
            break;
        }
    }
}

/* ここに WindowProc が入る。以下の case ステートメントを追加する。
        case WM_GRAPHNOTIFY:
            HandleEvent();
            break;
*/

// ここに WinMain が入る。


DirectShow について

ここでは次の内容について説明する。

  • DirectShow システムの概要
  • フィルタ グラフとそのコンポーネント
  • フィルタ グラフの構築
  • フィルタ グラフのデータ フロー
  • DirectShow でのイベント通知
  • ハードウェア デバイスがフィルタ グラフに参加する方法
  • 動的グラフ作成
  • PID


DirectShow システムの概要

マルチメディアの課題

マルチメディアを扱う作業にはいくつかの大きな課題がある。

  • マルチメディア ストリームには、非常に高速に処理しなければならない大量のデータが含まれている。
  • オーディオ、ビデオおよび任意の付加ストリームのすべてを、同時に開始して同時に停止し、同じレートで再生するように同期化する必要がある。
  • ストリームのソースは、ローカル メディア ファイル、コンピュータ ネットワーク、地上波放送、ビデオ カメラ、その他のメディア デバイスなど、多種多様である。
  • ストリームのフォーマットも、AVI (Audio-Video Interleaved)、ASF (Advanced Streaming Format)、MPEG (Motion Picture Experts Group)、DV (Digital Video)、MJPEG (Motion JPEG) など、さまざまである。
  • アプリケーションでは、エンドユーザーのシステムでどのようなハードウェア デバイスが使用されているかを知る方法はない。

DirectShow ソリューション

DirectShow は、これらの課題に対処するように設計されている。設計の主な目標は、データ転送、ハードウェアの違い、および同期化の問題をアプリケーションから切り離すことによって、Windows® プラットフォームでのマルチメディア アプリケーション作成作業を容易にすることである。

DirectShow では、ビデオおよびオーディオのストリーミングに必要なスループットを実現するために、DirectDraw® と DirectSound® を使用してシステムのサウンド カードとグラフィック カードにデータを効率よくレンダリングする。同期化は、マルチメディア データをタイム スタンプ付きのメディア サンプルにカプセル化することによって実現される。さまざまなソース、フォーマット、およびハードウェア デバイスを処理するために、DirectShow はモジュール式アーキテクチャを使用している。このアーキテクチャでは、フィルタと呼ばれるオペレーティング システム コンポーネントを組み合わせて、多くの異なるシナリオに対するサポートを提供できる。

DirectShow には、Windows Driver Model (WDM) に基づく最新のマルチメディア キャプチャおよびチューニング デバイスをサポートするフィルタと、従来の Video for Windows (VfW) キャプチャ カードやオーディオ圧縮マネージャ (ACM) およびビデオ圧縮マネージャ (VCM) のインターフェイス用に作成された古い CODEC をサポートするフィルタが含まれている。

次の図は、アプリケーション、DirectShow コンポーネント、DirectShow がサポートするハードウェア コンポーネントおよびソフトウェア コンポーネントの関係を示している。

この図が示すように、DirectShow を使用すると、ローカル ファイル、ローカルの CD および DVD ドライブ、ネットワーク上のリモート ファイル、Windows Driver Model (WDM) に基づく最近の TV チューナー カードおよびビデオ キャプチャ カード、従来の Video for Windows® ビデオ キャプチャ カードなど、さまざまなソースのファイルとストリームをアプリケーションで再生できる。DirectShow には一部のファイル フォーマット用の固有のコンプレッサとデコンプレッサがあり、多くのサード パーティ ハードウェアおよびソフトウェア デコーダは、DirecShow と互換性がある。さらに、DirectShow は、ビデオ圧縮マネージャ (VCM) およびオーディオ圧縮マネージャ (ACM) のインターフェイスに基づく従来の VfW CODEC もサポートする。再生では、ハードウェアでサポートされている場合は、DirectDraw ハードウェア アクセラレーションおよび DirectSound 機能が最大限に利用される。


フィルタ グラフとそのコンポーネント

ここでは、Microsoft® DirectShow® のフィルタ グラフを構成するコンポーネントの概要について説明する。独自のカスタム DirectShow フィルタを作成する開発者と、アプリケーションで DirectShow を使用するときに見えないところで何が起きているのかを知りたいと考えている DirectShow アプリケーション開発者を対象にしている。ただし、アプリケーションでは通常 DirectShow フィルタ グラフの内部動作を取り扱う必要はない。多くの場合、フィルタの追加、ピンの接続、同期化ソースの設定などの詳細は、フィルタ グラフ マネージャとフィルタおよびピン自身が自動的に処理する。 フィルタ開発者向けの注 : DirectShow で独自のカスタム変換またはカスタム エフェクトを使用する場合、ネイティブの DirectShow フィルタを記述する必要はない。変換を実行する DirectX Media Object (DMO) を記述し、DMO ラッパー フィルタを通してフィルタ グラフで使用できる。このため、フィルタ接続と同期化のメカニズムのすべての詳細から完全に解放される。

フィルタ グラフ

メディア ファイルまたはストリームをなんらかの方法で再生、記録、キャプチャ、ブロードキャスト、または処理する場合は、1 つ以上のフィルタがフィルタ グラフと呼ばれる構成に接続される。グラフを構築する処理は、アプリケーションで手動によって、またはグラフ ビルダまたはフィルタ グラフ マネージャによって自動的に行うことができる。いずれの場合も、プロセスは通常ソース フィルタから始まり、常に 2 つの主要な係数に基づいている。1 つは、フィルタが入力として予測しているストリームの数とストリームのメディア タイプ、もう 1 つは、フィルタが出力するストリームの数とストリームのメディア タイプである。次の図は、圧縮されたビデオが格納されている AVI ファイルを再生する簡単なフィルタ グラフを示している。

グラフ内の矢印は、データが流れる方向を示す。このソース フィルタは非同期ファイル ソースである。このフィルタは、ファイルからバイト ストリームを読み取り、ビデオ圧縮スキームを含む AVI (Audio-Video Interleaved) フォーマットを認識する AVI スプリッタ フィルタに渡す。AVI スプリッタは、データを解析してタイム スタンプ付きのメディア サンプルにし、ビデオ サンプルをダウンストリームの AVI デコンプレッサに渡す。ビデオの場合、各サンプルに 1 個のビデオ フレームが含まれる。AVI デコンプレッサは正しい CODEC を見つけてサンプルを圧縮解除し、圧縮解除したビデオ フレームをビデオ レンダリング フィルタに渡す。ビデオ レンダリング フィルタがコンピュータ画面にビデオを表示する。オーディオ サンプルは圧縮されていないため、AVI スプリッタはデフォルト DirectSound デバイスに直接接続できる。

フィルタ

フィルタは DirectShow を構成する基本要素である。DirectShow はマルチメディア データの処理を個々のステップに分割し、フィルタは 1 つ (または場合によっては複数) の処理ステップを表す。これによって、アプリケーションがフィルタを "組み合わせて"、多種多様なクラスのハードウェア デバイスおよびソフトウェア デバイスを使用しているさまざまなメディア フォーマットに対して、さまざまな操作を実行することが可能になる。たとえば、非同期ファイル ソース フィルタはディスクからファイルを読み取り、TV チューナー フィルタは TV キャプチャ カード上のチャンネルを変更し、MPEG-2 スプリッタ フィルタは MPEG ストリームのオーディオおよびビデオ データをデコードできるように解析する。これらのフィルタは、それぞれ内部的には非常に固有な動作を実行するが、アプリケーション側から見ると、ある標準的な特徴を備えた DirectShow フィルタにすぎない。その特徴とは、IBaseFilter インターフェイスのサポートと、ほかの 1 つ以上の DirectShow フィルタへの接続を表す 1 つ以上の入力ピン、出力ピン、またはその両方のサポートである。

すべての DirectShow フィルタは 3 つのカテゴリに分かれる。ソース フィルタ、変換フィルタ、およびレンダリング フィルタの 3 つである。

ソース フィルタ

ソース フィルタは処理する未処理のマルチメディア データを表す。ソース フィルタは、ハード ディスク上のファイル (上の図の非同期ファイル ソース フィルタのように) あるいは CD または DVD ドライブからデータを取得するか、テレビ受信カードやデジタル カメラに接続したキャプチャ カードなどの "ライブ" ソースからデータを取得する。これらすべてのシナリオに対応した DirectShow のソース フィルタが、Microsoft Windows 9x および Windows 2000 に付属している。パーサーまたはスプリッタ フィルタに未処理のデータを渡すだけのソース フィルタもあれば、解析ステップまで実行するソース フィルタもある。

変換フィルタ

変換フィルタは、未処理のデータまたは部分的に処理されたデータを受け取り、処理してから渡す。変換フィルタには多くの種類があり、少数の例をあげるだけでも、未処理のバイト ストリームをサンプルとフレームに分割するパーサー、コンプレッサとデコンプレッサ、フォーマット コンバータなどがある。DirectShow には多くの一般的な CODEC が含まれている。上に示した図では、AVI スプリッタと AVI デコンプレッサは両方とも変換フィルタである。DirectShow に提供されていない変換フィルタとして、MPEG-2 デコーダがある。MPEG-2 デコーダはサードパーティからハードウェアまたはソフトウェアに実装されて提供されている。

レンダリング フィルタ

レンダリング フィルタは通常完全に処理されたデータを受け取り、システムのモニタやスピーカ、あるいは外部デバイスを通して再生する。ディスクまたはその他の永続的な記憶装置にデータを保存する "ファイル ライタ" フィルタも、レンダリング フィルタのカテゴリに属する。上の図に示したように、DirectShow に付属しているビデオ レンダリング フィルタは DirectDraw を使用してビデオを表示し、デフォルトのオーディオ レンダリング フィルタは DirectSound を使用してオーディオを再生する。

DirectShow にはさまざまなメディア フォーマットの再生、変換、およびキャプチャ用のフィルタが用意されており、Windows 9x および Windows 2000 に付属している。開発者は、カスタムまたは標準のデータ フォーマットを処理するための独自のカスタム フィルタを構築することもできる。DirectX 8 では、DirectShow を使用すると、開発者は DirectX Media Object (DMO) を記述し、DMO ラッパー フィルタにすべての同期化およびピン接続の詳細を処理させることによって、"フィルタ" 開発を簡略化できる。DMO はフィルタよりも開発とテストが簡単で、DirectShow フィルタ グラフ アーキテクチャに依存しない。一度記述した DMO は、DirectShow アプリケーションかどうかにかかわらず、必要な場合はいつでも再利用できる。

ピン

前の図に示したように、フィルタ グラフ内のマルチメディア データは、ソース フィルタからゼロ個以上の中間フィルタを経由してダウンストリームに移動し、最後にレンダリング フィルタに到達する。ピンは、フィルタ間のデータ転送において低レベルの詳細を処理する。ピンは、IPin COM インターフェイスをサポートし、方向 (入力または出力) を持ち、グラフ内の特定のフィルタに関連付けられた COM オブジェクトである。ピンは別のフィルタとの接続ポイントを表す。アップストリーム フィルタの出力ピンは、ダウンストリームにある次のフィルタの入力ピンに接続する。ピンはサポートできるメディア タイプを認識し、2 つのフィルタが最初に接続するときにメディア タイプを調整する。メディア タイプを設定した後、ピンは、フィルタ グラフの実行開始後にデータを転送する方法の詳細を設定する。

メディア サンプル

ローカル ファイル、キャプチャ カードまたはその他のソースから未処理のバイト ストリームがグラフに入力された後、バイト ストリームをメディア サンプルと呼ばれる意味のある単位に解析する必要がある。ソース フィルタが解析を実行する場合もあれば、別個の解析フィルタが解析を実行する場合もある。DirectShow では、メディア サンプルは IMediaSample2 を実装する COM オブジェクトにラッピングされている。実際のマルチメディア データに加えて、オブジェクトには特定のメディア タイプおよび同期化のタイムを含む情報が含まれている。ビデオ データを含む 1 個のメディア サンプル オブジェクトには、ビデオ フレーム 1 個分のデータが格納される。オーディオの場合、1 個のメディア サンプル オブジェクトに複数のオーディオ サンプルのデータが格納される。いずれの場合も、データがグラフ内をフィルタから次のフィルタへダウンストリーム方向に移動するとき、データはメディア サンプル オブジェクトのフォーマットである。

アロケータ

2 つのフィルタが接続するとき、アップストリーム フィルタからダウンストリーム フィルタにメディア サンプル オブジェクトを転送する方法の詳細が、2 つのフィルタのピンで一致しなければならない。"接続する" とは、使用するサンプルのサイズ、場所および数を決定することを意味する。サンプルのサイズはメディアのタイプとフォーマットによって異なり、バッファの場所は、メイン メモリか、またはビデオ キャプチャ カードなどのハードウェア デバイスになる。サンプルの作成と管理はアロケータによって処理される。アロケータは、通常はそれ自身がダウンストリーム フィルタの入力ピンによって作成される COM オブジェクトである。

アロケータの作成、および接続時に入力ピンと出力ピンが実行する調整の詳細については、「DirectShow フィルタの開発」を参照すること。特定のビデオ キャプチャのシナリオでは、割り当てるバッファのサイズをアプリケーションで指定する必要がある。そのためのインターフェイスが提供されている。ほとんどの場合、バッファ割り当ての詳細はアプリケーションに対して完全に透過的である。ただし、フィルタ グラフ内のデータの "移動" は必ずしもコピー操作を伴わない。接続プロセスでは、スループットを最大化するために、ピンは可能な限りアップストリーム バッファを "再利用" する。

クロック

マルチメディアに関連するすべての操作で、ビデオ フレームを適切なレートで表示したり、オーディオ ストリームがビデオより先に来ないようにするために、サンプルを同期化することが重要である。したがって、DirectShow フィルタ グラフには常に、すべてのフィルタによってメディア サンプルのタイム スタンプの設定、処理またはレンダリングに使用されるクロックが 1 個だけ含まれる。フィルタ グラフ マネージャは、クロックを選択 (または必要な場合はクロックを指定) し、同期化ソースとしてそのクロックを用いることをすべてのフィルタに指示する。


フィルタ グラフの構築

前の「フィルタ グラフとそのコンポーネント」では、DirectShow フィルタ グラフの基本的な構成要素について説明した。ここでは、マルチメディア データの処理を開始できるように、これらの構成要素を作成および接続する方法について説明する。最初の「一般的なグラフの構築」では、フィルタ グラフの構築に関する一般的な手法について説明する。次の「キャプチャ グラフの構築」では、キャプチャ グラフの構築に用いられる別の手法について説明する。キャプチャ グラフとは、DV カムコーダ、USB カメラ、TV チューナー カードなどのビデオ キャプチャ デバイスからのデータを処理するフィルタ グラフである。

一般的なグラフの構築

フィルタ グラフを作成するには、必ず最初にフィルタ グラフ マネージャのインスタンスを作成して、次に示すように IGraphBuilder インターフェイスへのポインタを取得する。

IGraphBuilder* pIGB;
HRESULT hr;
hr = CoCreateInstance(CLSID_FilterGraph,
NULL,
CLSCTX_INPROC_SERVER,
IID_IGraphBuilder,
(void **)&pIGB);

IGraphBuilder インターフェイスは、その名のとおり、フィルタ グラフのメソッドを格納する。これらのメソッドは、次のようなグラフ構築の 3 種類のアプローチを提供する。

  1. アプリケーションがフィルタ グラフ マネージャに対してグラフ全体を自動構築するよう指示する。
  2. アプリケーションとフィルタ グラフ マネージャが、グラフ構築作業を共有する。
  3. アプリケーションが各フィルタを個別に追加および接続して、グラフ全体を構築する。

アプローチ #1:フィルタ グラフ マネージャによるグラフ全体の構築

アプローチ #1 は、AVI、MPEG、WAV、MP3 など、一部の既知のフォーマットのファイルを再生するだけの場合に向いている。この手法は、「ファイルの再生法」で具体的に示されている。DirectShow では、モニタにビデオ データを表示したり、システムのスピーカからオーディオ データを流したりする処理を表現するのに、再生よりもレンダリングという用語が使われることが多い。フィルタ グラフ マネージャに対して、指定されたファイルをレンダリングできるフィルタ グラフを自動作成するよう指示するために、アプリケーションは IGraphBuilder::RenderFile メソッドを使用する。次に、グラフを構築するためのフィルタ グラフ マネージャの基本手順について説明する。

フィルタの検索

フィルタ グラフを作成するには、まず必要なフィルタを検索してそのインスタンスを作成する。フィルタの選択処理は、主に、処理するデータのメディア タイプに基づく。これは、2 つのフィルタのピンは、両方が処理できる共通のメディア タイプを調整できない限り、接続できないからである。フィルタ グラフ マネージャは、さまざまなファイル名拡張子 (.wma、.avi、.wav など) に関連付けられたメディア タイプのレジストリを検索することで、データのメディア タイプを決定できる。拡張子との関連付けが存在しない場合、フィルタ グラフ マネージャは、ファイル内の特殊なチェック バイトを検索する。これらのチェック バイトから、フィルタ グラフ マネージャは、対応する DirectShow メディア タイプを決定し、そのメディア タイプを読み取り可能なソース フィルタの検索を開始できる。内部的には、RenderFile ロジックが IGraphBuilder::AddSourceFilter を呼び出すことで、このタスクを実行する。

すべての DirectShow フィルタは、フィルタの分類、サポートするメディア タイプ、フィルタのメリットなどに加えて、Windows レジストリ内の GUID で一意に識別される。フィルタ グラフ マネージャは、このすべての情報を検査して、どのフィルタのインスタンスを作成するかを決定する。フィルタ分類は、フィルタの一般的な機能を識別子、検索基準を最初に絞り込むために使われる。メディア タイプ情報は、フィルタが入力として受け付けることができるデータの種類、およびグラフ内の次のフィルタに出力として提供できるデータの種類を記述する。メリットの値は、グラフの自動構築処理中にフィルタが考慮されるべきかどうかを示す。システム上の 2 つのフィルタが似たメディア タイプ情報を持つ場合、フィルタ グラフ マネージャはメリット値の高い方のフィルタを選択する(一部のフィルタは、特殊なフィルタ グラフでのみの使用を目的としているので、メリット値を意図的に低くしている。そのようなフィルタは、アプリケーションによって個別にグラフに追加する必要がある)。

レジストリを検索するには、フィルタ グラフ マネージャは DirectShow フィルタ マッパー オブジェクトのインスタンスを作成し、IFilterMapper2::EnumMatchingFilters メソッドを呼び出して、検索を実行する。このメソッドは、分類やメディア タイプごとに DirectShow フィルタ (デコーダなどのハードウェア デバイスと同様) を列挙でき、検索基準に一致するすべてのフィルタおよびハードウェア デバイスまたはその一方に対するモニカを含む標準 COM IEnumMoniker オブジェクトを返す(COM モニカを使うと、このメソッドは、オブジェクトのインスタンスを実際に作成しなくてもオブジェクトを問い合わせたり、パスを作成したり、ハードウェア デバイスなど、実際は COM オブジェクトではないものを列挙したりすることができる)。

グラフへのフィルタの追加

指定されたタイプのファイルを読み取ることができるソース フィルタをモニカが見つけると、フィルタ グラフ マネージャは CoCreateInstance を使って、返された GUID を使うことでフィルタのインスタンスを作成する。大部分のファイル タイプでは、ソース フィルタはファイル ソース (非同期) フィルタとなる。次に、フィルタ グラフ マネージャは、IGraphBuilder::AddFilter メソッドを呼び出してフィルタ グラフにフィルタを追加する。フィルタがグラフに追加されたことがフィルタに通知されると、読み取るファイルのタイプ用に構成された出力ピンを 1 つまたは複数作成する。ピンが作成されたら、フィルタ グラフ マネージャは、各ピンがサポートするメディア タイプを調べ、次にその入力ピンのメディア タイプを受け入れ可能なフィルタをレジストリで再び探す。適合するフィルタが見つかると、そのフィルタをグラフに追加する。

フィルタの接続

ダウンストリーム フィルタの追加時に、フィルタはピンを構成し、前の (アップストリーム) フィルタに接続する準備が完了する。フィルタ グラフ マネージャは、各フィルタに問い合わせて適切なピンを決定し、IGraphBuilder::Connect メソッドを呼び出して、アップストリーム フィルタの出力ピンをダウンストリーム フィルタの入力ピンに接続する。次に、2 つのピンは調整プロセスを実行してデータのメディア タイプを決定し、メディア サンプル オブジェクト用のメモリを割り当てるオブジェクト、およびサンプルのデータを保持するバッファはどちらのピンが提供するかを決定する。ピン接続プロセスの詳細については、「フィルタ開発者のための DirectShow アーキテクチャ」で解説される。

グラフの完成

2 つのピンを接続したら、フィルタ グラフ マネージャは、新しいフィルタの出力ピンでサポートされるメディア タイプを調べ、そのメディア タイプを処理可能なフィルタを検索する。必要なフィルタがすべてグラフに追加されるまで、同じプロセスが繰り返される。ファイル再生グラフでは、2 番目のフィルタは通常、パーサーまたはスプリッタ フィルタとなる。これは、AVI や MPEG など未加工のデータ ストリームを読み取り、オーディオ ストリームとビデオ ストリームに分割するフィルタであり、ストリームごとに出力ピンが作成される。どちらかのストリームのデータが圧縮されている場合、各ストリームの次のフィルタはデコンプレッサ フィルタとなり、その後にレンダリング フィルタが続く。

グラフが構築されたら、アプリケーションは、フィルタ グラフ マネージャから IMediaControl インターフェイスを取得して、Run メソッドを呼び出してファイル再生を開始するだけでよい。

アプローチ #2:アプリケーションとフィルタ グラフ マネージャによるグラフ構築作業の共有

フィルタ グラフで単純にファイルをレンダリングする以外のことをする必要がある場合、少なくともグラフ構築作業の一部は、アプリケーション側で実行する必要がある。たとえば、AVI ファイルを MPEG ファイルに変換するフィルタ グラフを構築している場合、IGraphBuilder::RenderFile を呼び出すことで、引き続きフィルタ グラフ マネージャに AVI 再生グラフを作成させることもできるが、出力をモニタとスピーカではなく MPEG ファイルに送るために、後からグラフを修正する必要がある。これに伴い、ビデオおよびオーディオ レンダリング フィルタの接続を解除して削除し (IGraphBuilder::Disconnect および IGraphBuilder::RemoveFilter を使用)、MPEG ビデオおよびオーディオ コンプレッサ フィルタ、MPEG Multiplexer フィルタ、およびファイル ライタ フィルタと置き換える必要がある。

また、メディア タイプを MPEG コンプレッサが受け入れ可能なタイプに変換するために、中間フィルタを追加する必要がある。アプリケーションには、この中間フィルタを直接追加する方法と、IGraphBuilder::Connect メソッドを使う方法がある。このメソッドを呼び出すと、フィルタ グラフ マネージャは、まずフィルタに直接接続しようと試みる。そこでメディア タイプの調整が付かない場合、フィルタ グラフ マネージャは中間フィルタを検索する。フィルタ グラフ マネージャが特定のメディア タイプを処理可能なフィルタを検索するときは必ず、グラフに既に追加されているフィルタを最初に試す。フィルタ グラフ マネージャが中間フィルタを挿入しないようにするには、IGraphBuilder::ConnectDirect メソッドを使う。

前の例では、アプリケーションはグラフのダウンストリーム部分を構築した。別のシナリオでは、アプリケーションはグラフのアップストリーム部分を構築しなければならないことがある。その場合、手動で追加しなければならないフィルタを一度追加して接続したら、IGraphBuilder::Render メソッドを使って、指定された出力ピンから自動的にグラフを完成するようフィルタ グラフ マネージャに指示できる。オーディオ ピンとビデオ ピンなど、フィルタに 2 つの出力ピンがある場合、アプリケーションは各ピンに対して Render を呼び出す必要がある。

アプローチ #3:アプリケーション自体によるグラフ全体の構築

あるシナリオでは、アプリケーションが各フィルタを個別に追加および接続して、グラフ全体を構築しなければならないことがある。この場合は、どのフィルタをグラフに追加しなければならないかが明確に判明していることが多いので、Filter Mapper オブジェクトを使ってフィルタを見つける必要はない。IGraphBuilder::AddFilter メソッドを使って各フィルタをグラフに追加し、 Connect または ConnectDirect のどちらかを使ってフィルタを接続するだけである。

キャプチャ グラフの構築

独立系ハードウェア ベンダ (IHV) および家電メーカーにより提供されるキャプチャ デバイスが多岐にわたるため、ビデオ キャプチャ グラフの構築プロセスはかなり複雑になる可能性がある。アプリケーション開発者の負担を軽減するために、DirectShow は別に Capture Graph Builder というオブジェクトを用意している。ビデオ キャプチャ アプリケーションは、このオブジェクトのインスタンスを作成し、その ICaptureGraphBuilder2 インターフェイス メソッドを使って、フィルタ グラフを構築する。グラフ構築の一般原則を理解していれば、キャプチャ グラフの構築作業もほぼ同じ方法で行えることがわかる。詳細については、「キャプチャ アプリケーションの書き方」を参照すること。


フィルタ グラフのデータ フロー

ここでは、Microsoft® DirectShow® フィルタ グラフにおけるデータの流れについて説明する。内容は次のとおりである。

  • サンプルとバッファ
  • 送信のサンプル
  • 停止、ポーズ、および実行
  • ライブ キャプチャ
  • 詳細についての参照先

サンプルとバッファ

2 つのピンを接続すると、データは出力ピンから入力ピンへ移動する。出力ピンはデータを送信し、入力ピンはデータを受信する。出力から入力へというデータ フローの方向はダウンストリームと呼ばれ、その逆の方向はアップストリームと呼ばれる。

2 つのピンの間を移動するデータのタイプは、ピンの実装によって異なる。最も一般的なケースでは、ピンはメイン メモリに格納されたメディア データを使用して動作する。ただし、これ以外の配置も可能である。たとえば、2 つのフィルタがビデオ ハードウェアを制御する場合は、ハードウェアがすべてのビデオ データを処理し、ピンは制御情報を交換する。データのタイプ、およびピンの間をデータが移動する方法は、転送と呼ばれる。ここでは、メディア データがメイン メモリに格納されているローカル メモリ転送と呼ばれる転送について説明する。

ローカル メモリ転送では、データはメディア サンプルと呼ばれる圧縮された個別のオブジェクトである。メディア サンプルは、割り当てられたメモリ バッファへのポインタを格納する COM オブジェクトである。メディア サンプルは IMediaSample インターフェイスをサポートし、IMediaSample2 インターフェイスをサポートすることも可能である。

バッファの割り当てとメディア サンプルの作成を行うもう 1 つの COM オブジェクトがメモリ アロケータである。接続時、アロケータはバッファのためのメモリを予約する。さらにアロケータはメディア サンプルの集合を作成し、メモリ ブロック内のアドレスへのポインタを各サンプルに渡す。バッファが解放されるまで、アロケータはどのサンプルが使用可能かを示すリストを維持する。フィルタは、新しいサンプルが必要になると、アロケータにサンプルを要求する。サンプルは、処理された後リストに戻される。

このメカニズムではフィルタが同じバッファを再利用するため、メモリ割り当ての量が減る。また、アロケータは使用可能なサンプルのリストを保持しているため、まだ処理の済んでいないデータがフィルタによって誤ってオーバーライドされることを防止できる。さらに、グラフ内のデータ移動を効率よく実行できる。出力ピンは、サンプルを送信するとき、サンプルの IMediaSample インターフェイスへのポインタを渡す。データをコピーする必要はない。

次の図は、アロケータ、メディア サンプル、およびフィルタの関係を示している。

接続された複数のピンが 1 つのメモリ アロケータを共有する。フィルタは入力用と出力用に異なるアロケータを使用できる。これは、デコンプレッサ フィルタのように、データを展開するフィルタで一般的である。出力が入力より大きくない場合は、フィルタはデータを新しいバッファに移動せず、元の場所で処理できる。その場合、2 つ以上のピン接続で 1 つのアロケータを共有できる。

送信のサンプル

ローカル メモリをサポートする入力ピンは IMemInputPin インターフェイスを公開する。出力ピンは、入力ピンに対して IMemInputPin::Receive メソッドを呼び出すことによって、サンプルを送信する。入力ピンは次のいずれかの処理を実行する。

  • サンプルを拒否する。
  • サンプルの処理が完了するまでブロックする。
  • 直ちに戻り、別のスレッドのサンプルを処理する。

IMemInputPin::ReceiveCanBlock メソッドは、入力ピンが Receive の呼び出しをブロックするかどうかを判別する。出力ピンはこのメソッドを呼び出し、適切なスレッド処理方法を決定できる。ワーカー スレッドを作成し、ほかの作業を実行しながらバックグラウンドでサンプルを送信できるフィルタもある。あるいは、ダウンストリーム フィルタが次のサンプルを受け取る準備ができるまでブロックするフィルタもある。

また、一度に複数のサンプルを送信する IMemInputPin::ReceiveMultiple というメソッドもある。このメソッドは Receive と同様に動作するが、サンプルの配列を処理する。

停止、ポーズ、および実行

フィルタには、停止、ポーズ、および実行中という 3 つの状態がある。ほとんどのフィルタでは、ポーズと実行中は等しい。

  • 停止状態のとき、フィルタはサンプルを処理しない。アップストリーム フィルタからのサンプルは拒否される。
  • ポーズまたは実行中のとき、フィルタはサンプルを受け取って処理する。ソース フィルタは、新しいサンプルを生成し、ダウンストリームに送信する。

レンダリング フィルタは例外である。レンダリング フィルタが停止状態からポーズ状態に移る場合、メディア サンプルを 1 つ受け取った時点で移行が完了する。その時点で、レンダリング フィルタはサンプルを保留し、Receive の呼び出しをブロックする。ビデオ レンダラはサンプルを静止フレームとして描画する。オーディオ レンダラは実行状態になってからサンプルをレンダリングする。オーディオでは "静止フレーム" に相当するものは存在しない。いずれの場合も、レンダラはポーズから実行中に切り替わるまで次のサンプルを受け取らない。

フィルタ グラフ マネージャはフィルタ グラフ全体の状態を制御する。有効な状態移行として、停止とポーズ、およびポーズと実行中の間の移行がある。停止と実行中の間の移行は、ポーズを経由する必要がある。停止状態のグラフに対して IMediaControl::Run、または実行中のグラフに対して IMediaControl::Stop を呼び出すと、フィルタ グラフ マネージャは最初にグラフをポーズする。

フィルタ グラフが停止からポーズに移る場合、次の手順が実行される。

  • フィルタ グラフ マネージャは、レンダリング フィルタから開始し、アップストームの各フィルタに対して IMediaFilter::Pause を呼び出す。
  • 各フィルタは、ポーズに切り替わるとアップストリーム フィルタからサンプルを受け取ることができるようになる。各フィルタはダウンストリームにサンプルを安全に送信できる (ダウンストリーム フィルタもポーズしているため)。
  • ソース フィルタは最後にポーズする。その時点で、ソース フィルタはサンプルの送信を開始する。
  • サンプルがダウンストリームに移動するにつれて、中間フィルタがそれらのサンプルを処理する。
  • 最初のサンプルがレンダラに到着するとレンダラの状態移行が完了し、レンダラはブロックする。

これらのイベントが完了するまでの時間は一定ではない。通常は長くかからないが、圧縮解除を要するソースの場合は特に遅延が顕著なことがある。ただし、グラフはポーズ状態が終了すると、直ちにデータのレンダリングを開始できる。したがって、グラフのポーズにはデータを "挿入" する効果がある。アプリケーションでは、これをあらかじめ実行し、次にユーザーからのコマンドに応じてすばやくグラフを実行中の状態に切り替えることができる。

ライブ キャプチャ

ライブ キャプチャ フィルタは、ほかのソース フィルタと異なり、ポーズ状態のときにサンプルを送信しない。pause コマンドと run コマンドの間にどれぐらいの時間が経過するかは特定できない。pause コマンドの時点で送信されたサンプルは最新ではない可能性がある。ユーザーが run コマンドを発行するまでに 1 時間が経過した場合、1 時間前にキャプチャしたビデオ フレームではなく新しいビデオ フレームをグラフで生成する必要がある。そのため、キャプチャ フィルタは実行中のときだけサンプルを送信する。

ただし、この動作によってグラフに問題が発生する場合がある。フィルタ グラフ マネージャは、すべてのフィルタがポーズするまで待機してからグラフを実行する。しかし、レンダラはキャプチャ フィルタからのサンプルを待機するため、この移行は完了しない。この問題を回避するために、キャプチャ フィルタの IMediaFilter::GetState メソッドは VFW_S_CANT_CUE を返す。この戻りコードはフィルタ グラフ マネージャに対して、キャプチャ フィルタがサンプルを送信していないことを知らせ、レンダラを待機しないように指示する。

詳細についての参照先

データ フローの詳細については、「フィルタ開発者が使用するデータ フロー」を参照すること。


DirectShow でのイベント通知

ここでは、Microsoft® DirectShow® のフィルタ グラフでどのようにイベントが発生するか、およびアプリケーションがどのようにイベント通知を取得し、それに応答するかについて説明する。内容は次のとおりである。

  • イベント通知の概要
  • イベントの取得
  • イベント発生時の確認

イベント通知の概要

フィルタは、イベント通知を送信することによって、フィルタ グラフ マネージャにイベントを通知する。イベントは、ストリームの終わりのように予測できる場合もあれば、ストリームのレンダリング失敗のようなエラーの場合もある。フィルタ グラフ マネージャ自身が処理するフィルタ イベントもあれば、アプリケーションが処理するフィルタ イベントもある。フィルタ グラフ マネージャは、フィルタ イベントを処理しない場合、イベント通知をキューに入れる。フィルタ グラフはアプリケーションに対する独自のイベント通知をキューに入れることもできる。

アプリケーションはキューからイベントを取得し、イベントのタイプに基づいて応答する。そのため、DirectShow でのイベント通知は Microsoft® Windows® のメッセージ キューイングの仕組みに似ている。アプリケーションは、特定のイベント タイプに対するフィルタ グラフ マネージャのデフォルト動作を取り消すこともできる。この場合、フィルタ グラフ マネージャはイベントを直接キューに入れ、アプリケーションにイベントを処理させることができる。

このメカニズムによって次のことが可能になる。

  • フィルタ グラフ マネージャがアプリケーションと通信する。
  • フィルタがアプリケーションおよびフィルタ グラフ マネージャの両方と通信する。
  • アプリケーションがイベント処理にかかわる度合いを決定する。

イベントの取得

フィルタ グラフ マネージャはイベント通知をサポートする 3 つのインターフェイスを公開している。

  • IMediaEventSink は、フィルタがイベントを送信するためのメソッドを含む。
  • IMediaEvent は、アプリケーションがイベントを取得するためのメソッドを含む。
  • IMediaEventEx は、IMediaEvent インターフェイスを継承し、拡張する。

フィルタは、フィルタ グラフ マネージャに対する IMediaEventSink::Notify メソッドを呼び出すことによって、イベント通知を送信する。イベント通知は、イベントのタイプを定義するイベント コードと、付加情報を提供する 2 つの DWORD パラメータで構成される。イベント コードに応じて、パラメータにはポインタ、戻りコード、基準タイム、またはその他の情報が含まれる。すべてのイベント コードとパラメータの一覧については、「イベント通知コード」を参照すること。

キューからイベントを取得するために、アプリケーションはフィルタ グラフ マネージャに対して IMediaEvent::GetEvent メソッドを呼び出す。このメソッドは、返すイベントが発生するまで、または指定された時間が経過するまでブロックする。キュー内にイベントがあり、メソッドがイベント コードと 2 つのイベント パラメータを返したとする。アプリケーションは、GetEvent を呼び出した後必ず IMediaEvent::FreeEventParams メソッドを呼び出し、イベント パラメータに関連付けられたリソースを解放する必要がある。たとえば、パラメータは、フィルタ グラフによって割り当てられた BSTR 値である場合がある。

次のコード例は、キューからイベントを取得する方法の概要を示している。

long evCode, param1, param2;
HRESULT hr;
while (hr = pEvent->GetEvent(&evCode, &param1, &param2, 0), SUCCEEDED(hr))
{
    switch(evCode)
    {
        // 処理する各タイプのイベントに対して
        // アプリケーションで定義した関数を呼び出す。
    }

hr = pEvent->FreeEventParams(evCode, param1, param2);
}

イベントに対するフィルタ グラフ マネージャのデフォルト処理をオーバーライドするには、パラメータにイベント コードを指定した IMediaEvent::CancelDefaultHandling メソッドを呼び出す。デフォルト処理は、IMediaEvent::RestoreDefaultHandling メソッドを呼び出すことによって復元できる。フィルタ グラフが指定されたイベント コードに対してデフォルト処理を実行しない場合は、これらのメソッドを呼び出しても効果はない。

イベント発生時の確認

前の「イベントの取得」で説明したようにキューからイベント通知を取得することに加えて、アプリケーションにはイベントがキューで待機している場合にそれを検出する方法が必要である。フィルタ グラフ マネージャはそのために 2 つの方法を提供している。

  • ウィンドウ通知を使用する場合、フィルタ グラフ マネージャは、新しいイベントがあるかどうかにかかわらずアプリケーション ウィンドウに Windows メッセージを送信する。
  • イベント ハンドラを使用する場合、アプリケーションは、Windows の手動リセット イベントのハンドルを取得する。フィルタ グラフ マネージャは、キューにイベント通知があるときは手動リセット イベントを送信し、キューが空になるとそのイベントをリセットする。

以下の項目で各テクニックについて説明する。

  • ウィンドウ通知
  • イベント ハンドル

ウィンドウ通知

ウィンドウ通知をセットアップするには、IMediaEventEx::SetNotifyWindow メソッドを呼び出し、プライベート メッセージを指定する。アプリケーションでは、WM_APP から 0xBFFF までの範囲のメッセージ番号をプライベート メッセージとして使用できる。フィルタ グラフ マネージャは、新しいイベント通知をキューに入れると、指定されたウィンドウにこのメッセージを送信する。アプリケーションはウィンドウのメッセージ ループ内からメッセージに応答する。

次のコード例は、通知ウィンドウの設定方法を示している。

#define WM_GRAPHNOTIFY WM_APP + 1   // プライベート メッセージ。

pEvent->SetNotifyWindow((OAHWND)g_hwnd, WM_GRAPHNOTIFY, 0);

メッセージは通常の Windows メッセージであり、DirectShow のイベント通知キューからは独立して送信される。この方法の利点は、ほとんどのアプリケーションが既にメッセージ ループを実装しているため、多くの追加作業を必要とせずに DirectShow のイベント処理を組み込める点である。

次のコード例は、通知メッセージに応答する方法の概要を示している。完全な例については、「イベントへの応答」を参照すること。

LRESULT CALLBACK WindowProc( HWND hwnd, UINT msg, UINT wParam, LONG lParam)
{
    switch (msg)
    {
        case WM_GRAPHNOTIFY:
            HandleEvent();  // アプリケーション定義の関数。
            break;

        // ここでほかの Windows メッセージも処理する。
    }
    return (DefWindowProc(hwnd, msg, wParam, lParam));
}

イベント通知とメッセージ ループは両方とも非同期であるため、アプリケーションがメッセージに応答するときまでに、複数のイベントがキューに入っていることがある。また、イベントが無効になったときはキューからイベントがクリアされることがある。したがって、イベント処理コードでは、キューが空であることを示すエラー コードが返されるまで GetEvent を呼び出すこと。

イベント ハンドル

フィルタ グラフは、イベント キューの状態を示す手動リセット イベントを維持する。キューにペンディング状態のイベント通知が含まれている場合、フィルタ グラフは手動リセット イベントを送信する。キューが空の場合は、IMediaEvent::GetEvent メソッドを呼び出すとイベントがリセットされる。アプリケーションはこのイベントを使用してキューの状態を確認できる。

注 : ここで用語について混乱しないこと。手動リセット イベントは、Windows の CreateEvent 関数によって作成されるタイプのイベントであり、DirectShow で定義されているイベント通知とは無関係である。

IMediaEvent::GetEventHandle メソッドは、手動リセット イベントのハンドルを取得する。WaitForMultipleObjects などの関数を呼び出して、イベントが通知済になるまで待機すること。イベントが通知済になったら IMediaEvent::GetEvent メソッドを呼び出してイベント通知を取得する。

次のコード例は、この処理方法を示している。イベント ハンドルを取得し、イベントが通知済になるのを 100 ミリ秒間隔で待機する。イベントが通知済になると、GetEvent を呼び出してイベント コードとイベント パラメータをコンソール ウィンドウに出力する。再生が完了したことを示す EC_COMPLETE イベントが発生すると、ループが終了する。

HANDLE  hEvent;
long evCode, param1, param2;
BOOLEAN bDone = FALSE;
HRESULT hr = S_OK;

hr = pEvent->GetEventHandle((OAEVENT*)&hEv);

while(!bDone)
{
    if (WAIT_OBJECT_0 == WaitForSingleObject(hEvent, 100))
    {
 while (hr = pEvent->GetEvent(&evCode, &param1, &param2, 0), SUCCEEDED(hr))
        {
            printf("Event code: %#04x\n    Params: %d, %d\n", evCode, param1, param2);
hr = pEvent->FreeEventParams(evCode, param1, param2);
            bDone = (EC_COMPLETE == evCode);
        }
    }
}

フィルタ グラフが適切なときにイベントを自動的に設定またはリセットするので、アプリケーションでイベントの設定またはリセットを行うべきではない。さらに、フィルタ グラフを解放するとフィルタ グラフはイベント ハンドルを閉じる。そのため、その後はイベント ハンドルを使用しないこと。


ハードウェア デバイスがフィルタ グラフに参加する方法

ラッパー フィルタ

Microsoft® DirectShow® はすべてユーザー モード ソフトウェア コンポーネントである。DirectShow フィルタ グラフに参加するキャプチャ カード、TV チューナー、ハードウェア デコーダ、サウンドカードのようなカーネルモード ハードウェア デバイスはフィルタ グラフ内ではユーザーモード フィルタとして表現されなければならない。この機能は DirectShow が提供する特殊な「ラッパー フィルタ」が複数のタイプのデバイスに対して行っている。これらのフィルタはオーディオ キャプチャ フィルタ、VFW キャプチャ フィルタ、TV チューナー フィルタ、アナログ ビデオ クロスバー フィルタそして、TV オーディオ フィルタを含む。これらのラッパー フィルタに加えて、DirectShow は KsProxy フィルタを提供する、これは任意のタイプの Windows Driver Model® (WDM) ストリーミング デバイスを表現し、独立系ハードウェア ベンダー (IHV) のカスタム機能サポート用に拡張可能である。これは Ksproxy プラグイン によって行われ、このプラグインは KsProxy によって集成される COM オブジェクトである。

ラッパー フィルタはサポートする COM インターフェイスによって動作し、そのインターフェイスは予想されるデバイスの性能を表現する。アプリケーション ユーザーはそのインターフェイスを使ってフィルタにあるいはフィルタから情報を渡す。そのフィルタはインターフェイスの呼び出しをデバイス ドライバが理解可能な情報に翻訳する、次にフィルタはカーネルモードのデバイスへあるいはデバイスからその情報を渡す。(KsProxy は同様の方法で動作する、しかしフィルタ グラフに公開するインターフェイスは表現するデバイスによって異なる) VfW フキャプチャ フィルタやオーディオ キャプチャ フィルタのようなフィルタについては、そのインターフェイスは拡張できない。TV チューナー フィルタとアナログ ビデオ クロスバーと TYV オーディオ フィルタは KsProxy をベースにしていないけれど、IKSPropertySet インターフェイスをサポートする、これはカスタム プロパティ セットを 1 つのインターフェイス経由で扱う汎用の方法である。

アプリケーション開発者にとって、ユーザー モード フィルタとしてのラッピング ハードウェア デバイスに関する原則は、アプリケーションではその他すべての DirectShow フィルタを制御するのと同じ方法でデバイスを制御するということである。アプリケーションの側で特別なプログラミングは必要なく、カーネル モード デバイスとの通信に関係するすべての詳細はフィルタ自身の中にカプセル化される。

Video for Windows デバイス

初期の Video for Windows (VfW) キャプチャ カードをサポートするために、DirectShow は VFW キャプチャ フィルタを提供する。ターゲット システムに VfW カードがある場合は、DirectShow のシステム デバイス列挙子を使用して検出できる。列挙子は、グラフに VfW キャプチャ フィルタを追加し、追加したフィルタを検出されたカードに関連付けるためにも使用する。その後はフィルタ グラフの残りの部分を通常の方法で作成できる。詳細については、「デバイスとフィルタの列挙」を参照すること。

オーディオ キャプチャとミキシング デバイス (サウンド カード)

最近のサウンド カードは、マイクおよびその他のタイプのデバイス用の入力ジャックを備えている。また、個々の入力ごとにボリューム、高音域、および低音域を制御するオンボードのミキシング能力を備えているのが一般的である。DirectShow では、サウンド カードの入力とミキサーはオーディオ キャプチャ フィルタにラッピングされている。ローカル システムの各サウンド カードは、システム デバイス列挙子を使用して検出できる。これについては、「デバイスとフィルタの列挙」で説明している。システムのサウンド カードを表示するには、SDK と共にインストールされている GraphEdit を開き、オーディ キャプチャ ソースのカテゴリから選択する。ここに表示されるフィルタは、それぞれがオーディオ キャプチャ フィルタの別個のインスタンスである。

WDM ストリーミング デバイス

最近のハードウェア デコーダとキャプチャ カードは、Windows Driver Model (WDM) 規格に適合している。このようなデバイスは、VfW デバイスに比べて高機能であり、Windows NT/Windows 2000 と Windows 98/Me 間の移植が可能である。WDM ビデオ キャプチャ カードは、VfW では利用できない機能をサポートすることができ、キャプチャ フォーマット列挙、プログラムによるビデオ パラメータ (色相や輝度など) の制御 、プログラムによる入力選択、TVTuner サポート、VBI サポートなどが可能である。

WDM ストリーミング デバイスをサポートするために、DirectShow は KsProxy (ksproxy.ax) と呼ばれるフィルタを提供している。KsProxy は、その機能の多様さから "アーミー ナイフ フィルタ" と呼ばれてきた。また、基礎になるカーネル モード ドライバの能力に応じて、フィルタ全体および個々のピンでサポートされるピンとインターフェイスの数が異なるため、"カメレオン フィルタ" とも呼ばれる。フィルタ グラフに "KsProxy" という名前で表示されることはなく、常に、レジストリで発見された、デバイスの "フレンドリ" 名になっている。この名前はもともとドライバの .inf ファイルに指定されている名前である。システムに WDM デバイスがある場合は、 GraphEdit ユーティリティ プログラムを開き、[Graph] の [Insert Filters] をクリックし、WDM ストリーミング デバイスのノードまで下にスクロールする。システムの WDM カードが 1 つしかない場合でも、そのカードに複数のデバイスが含まれることがある。各デバイスは別個のフィルタとして表され、各フィルタは実際には KsProxy である。

アプリケーションでシステム デバイス列挙子を使用し、プログラムによってターゲット システムの WDM デバイス モニカ (たとえば TV チューナー カード) を探す場合、KsProxy (ドライバによって定義された "フレンドリ名" を使用している) は、後続の BindToObject メソッドの呼び出しでインスタンス化される。KsProxy は、すべての種類の WDM オーディオ デバイスまたはビデオ デバイスを表すことができるが、表すデバイスの種類を事前に知ることはできない。そのため、サポートされているプロパティ セットをドライバに問い合わせる必要がある。プロパティ セットは、WDM ストリーム クラス ドライバおよび MPEG-2 ソフトウェア デコーダなどの一部のユーザー モード フィルタによって使用されるデータ構造のコレクションである。次に、KsProxy は自分自身を動的に構成し、適切なインターフェイスをフィルタ グラフとアプリケーションに公開する。アプリケーションおよびその他のフィルタがこれらのインターフェイスを呼び出すと、KsProxy はメソッド パラメータをプロパティ セットに変換してドライバに送信する。IHV はプラグインを提供することによって KsProxy を拡張できる。プラグインはデバイスの特殊な能力を公開するベンダー独自のインターフェイスである。これらすべての詳細はアプリケーションに対して隠蔽されている。アプリケーションでは、KsProxy をほかの DirectShow ユーザー モード フィルタと同じように使用して、WDM デバイスからイベントを受け取り、WDM デバイスのイベントを制御する。

カーネル ストリーミング

WDM デバイスはカーネル ストリーミング モデルをサポートしている。カーネル ストリーミング モデルを使用すると、データをユーザーモードに渡すことなく、完全にカーネルモードで直接ストリーミングすることができる。カーネル モードとユーザー モードの間でデータを渡す操作は多くのコンピュータ資源を消費する。カーネル ストリーミングによって、ホスト CPU に負荷をかけずに高速なビットレートを利用できる。WDM ベースのフィルタはカーネル ストリーミングを使って、システムのメイン メモリにデータをコピーすることなく、マルチメディア データを (それが同じカードであろうとなかろうと) あるハードウェア デバイスから別のデバイスに直接渡す。

アプリケーション側から見ると、グラフ内のマルチメディア データが 1 つのユーザー モード フィルタから次のユーザー モード フィルタに移動しているように見える。実際には、データがユーザー モードに渡されることはなく、カーネル モード デバイスから別のカーネル モード デバイスへ直接ストリーミングされ、ビデオ グラフィック カードでレンダリングされる。当然、ファイルへのキャプチャの場合など、フィルタ グラフ内のある時点で実際にデータをカーネル モードからユーザー モードに渡さなければならない場合もある。しかし、ユーザー モード アクセスへの移行では、必ずしもメモリの新しい場所にデータがコピーされる必要はない。アプリケーションでは、キャプチャ グラフを構築するとき、ハードウェア デバイスから別のハードウェア デバイスへ、またはハードウェア デバイスからユーザー モード フィルタへデータが目的のパスをフォローするように、明示的に制御できる。詳細については、ビデオ キャプチャに関する項目を参照すること。

通常、アプリケーション開発者は背景情報としてしかカーネル ストリーミングの詳細を考慮する必要はない。WDM、カーネル ストリーミング、KsProxy、および関連トピックの詳細については、Microsoft DDK を参照すること。


動的グラフ作成

既存のフィルタ グラフを変更する必要がある場合は、グラフを停止し、変更を加えてから、グラフを再起動することができる。普通はこれが最良の方法だが、以下のような状況では、実行中にグラフを変更したい場合もある。

  • 再生中に、アプリケーションがビデオ エフェクト フィルタを挿入する。
  • ソース フィルタがミッドストリームのメディア タイプを切り換え、場合によっては新しいデコンプレッサ フィルタを要求する。
  • アプリケーションが、新しいビデオ ストリームをグラフに追加する。

これらはすべて"動的グラフ作成"の例である。動的グラフ作成とは、実行中にフィルタ グラフに加えられるさまざまな変更をすべて含む用語である。動的グラフ作成は、アプリケーションまたはグラフ内のフィルタによって開始される。以下の 3 種類のシナリオが考えられる。

  • 動的フォーマット変更: フィルタを削除したり置換したりしないで、2 つのフィルタ間の接続タイプを変更する。
  • 動的再接続: フィルタを追加したり削除したりして、グラフのトポロジを変更する。
  • フィルタ チェイン: フィルタのチェインを追加、削除、および制御する。

このトピックは、以下のセクションで構成される。

  • 動的フォーマット変更
  • 動的再接続
  • フィルタ チェイン

動的フォーマット変更

フィルタが出力フォーマットを切り換える場合、ピンを再接続したり、グラフをポーズまたは停止したり、フィルタを置換したりしなくても、ダウンストリーム フィルタが新しいフォーマットを受け入れられることもある。グラフの実行中に、ピンが新しいメディア タイプを受け入れられるかどうかを判定するために、フィルタ (またはアプリケーション) は、フィルタの出力ピンに接続された入力ピンの IPinConnection::DynamicQueryAccept を呼び出す。このメソッドは、IPin::QueryAccept メソッドとは異なる。QueryAccept は、フィルタが実行を開始していると、ピンがメディア タイプを受け入れることを保証しない。

現在の接続で新しいフォーマットが受け入れられない場合、次に考えられる解決方法は、以下のセクションで説明する動的再接続である。

動的再接続

動的再接続とは、グラフのトポロジを変更することである。データを失わないために、動的再接続を開始するアプリケーションまたはフィルタは、イベントのシーケンスに注意しなければならない。再設定されるグラフのセクションには、メディア データが流れていてはならない。例として、次の図のフィルタ グラフのフィルタ 2 をアプリケーションが動的に置換する場合を考えてみよう。

このフィルタを安全に削除してグラフを再接続するために、アプリケーションは以下の操作を行わなければならない。

  1. ピン A のデータ フローをブロックする。
  2. ピン B からピン D へ、未処理のデータをフィルタ グラフに送り出す。
  3. フィルタ 2 を削除し、新しいフィルタを挿入して、グラフを再設定する。
  4. データ フローが再開するように、ピン A のブロックを解除する。

3 つのインターフェイスが、これらの操作をサポートしている。

  • アップストリーム出力ピン (ピン A) の IPinFlowControl
  • ダウンストリーム入力ピン (ピン D) の IPinConnection
  • フィルタ グラフ マネージャの IGraphConfig

以下のセクションで、処理内容を詳しく説明する。

  • データ フローのブロック
  • グラフへのデータの送出
  • グラフの再設定
  • サンプル コード

データ フローのブロック

データ フローをブロックするには、アップストリームの出力ピン (ピン A) の IPinFlowControl::Block を呼び出す。このメソッドは、非同期または同期させて呼び出すことができる。

  • 非同期 : CreateEvent 関数を呼び出してイベント オブジェクトを生成し、イベント ハンドルを Block メソッドに渡す。このメソッドは直ちに返り、処理が完了するとピンがそのイベントをシグナル状態にする。WaitForSingleObject などの待機関数を呼び出してイベントを待つ。次のコードに、この処理を示す。

    HANDLE hEvent = CreateEvent(NULL, FALSE, FALSE, NULL);
pFlowControl->Block(AM_PIN_FLOW_CONTROL_BLOCK, hEvent);
WaitForSingleObject(hEvent, dwMilliseconds);
  • 同期 : イベント ハンドルの代わりに NULL 値を渡す。メソッドは処理が完了するまで戻らない。ピンがサンプルを送信できるようになるまで、メソッドは戻らないこともある。フィルタがポーズした場合、このメソッドは無限にブロックする可能性がある。そのため、アプリケーションのメイン スレッドから、同期に Block メソッドを呼び出してはならない。

グラフを再設定したら、最初のパラメータに 0 を渡して IPinFlowControl::Block を呼び出し、データ フローのブロックを解除する。

アップストリーム フィルタで再接続を開始する場合は、IPinFlowControl::Block を呼び出さなくても、データ フローを内部で制御できることがある。

グラフへのデータの送出

デフォルトでは、次のセクションで説明する IGraphConfig::Reconnect メソッドを呼び出すと、フィルタ グラフ マネージャがデータを自動的にグラフに送り出す。しかし、このメソッドを使わずに IGraphConfig::Reconfigure メソッドを使う場合などは、この処理を自分で扱わなければならない。いずれの場合も、この処理を理解しておけば役に立つ。

データをグラフに送り出すには、以下の操作を行う。

  1. ダウンストリーム入力ピン (ピン D) の IPinConnection::NotifyEndOfStream を呼び出す。このメソッドは、次にエンドオブストリーム条件が発生したときのピンからの通知を求める。ピンは、イベントをシグナル状態にして呼び出し元に通知する。
  2. すぐにアップストリーム出力ピン (ピン B) に接続されている入力ピンの IPin::EndOfStream を呼び出す。残っているデータは、中間フィルタを通じてダウンストリームに移動するので、これらのフィルタによってエンドオブストリーム通知が伝えられる。この例では、中間フィルタはフィルタ 2 だけである。
  3. イベントを待つ。ダウンストリーム入力ピン (ピン D) は、エンドオブストリーム通知を受け取るとイベントをシグナル状態にする。この時点で、未処理のデータはなく、呼び出し元がグラフを再設定しても安全である。

グラフの再設定

グラフを再設定するには、IGraphConfig::Reconnect メソッドを呼び出す。このメソッドは以下の処理を行う。

  • 中間フィルタを停止し、それらをグラフから削除する。
  • 新しい中間フィルタを追加し、それらの入力および出力ピンを接続する。
  • 新しいフィルタを起動する。

何らかの理由で IGraphConfig::Reconnect メソッドが適当でない場合は、コールバック メソッドでグラフを再設定することができる。IGraphConfigCallback インターフェイスを実装し、IGraphConfig::Reconfigure メソッドを呼び出す。これがコールバック メソッドを呼び出す。この場合は、データを自分でフィルタ グラフに送り出す必要がある。IGraphConfig::PushThroughData メソッドを呼び出す。

サンプル コード

以下の例に、ソース フィルタとレンダリング フィルタの間に変数 pFX が指すエフェクト フィルタを挿入する方法を示す。ほかのシナリオも考えられるので、IGraphConfig::Reconnect メソッドは動作を制御するパラメータをいくつか受け取る。詳細については、IGraphConfig のリファレンスを参照すること。

    // グラフが実行中と仮定する。
    IGraphConfig *pConfig;
    pGraph->QueryInterface(IID_IGraphConfig, (void **)&pConfig);

    // データ フローをブロックする。
    IPinFlowControl *pFlowControl;
    pOutPin->QueryInterface(IID_IPinFlowControl, (void **)&pFlowControl);
    pFlowControl->Block(AM_PIN_FLOW_CONTROL_BLOCK, NULL);

    // グラフを再設定する。
    pGraph->AddFilter(pFX, L"Effect Filter");
    pConfig->Reconnect(
            pOutPin,    // この出力ピンから開始する。
            NULL,       // ダウンストリーム側から適当な入力ピンを捜す。
            NULL,       // 最初の接続は指定しない。
            pFX,        // このフィルタを使用する。
            NULL,
            0);

    pFlowControl->Block(0, NULL);   // データ フローのブロックを解除する。

注 : pOutPin は、ソース フィルタの出力ピンへのポインタであると仮定されている。フィルタのピンへのポインタの取得については、「ピンの列挙」を参照すること。

アプリケーションではなくフィルタが動的再接続を行う場合は、スレッドに問題が発生する可能性がある。特に、別のプロセスがフィルタを停止しようとした場合、フィルタが停止するのをグラフが待ち、データがグラフに送り出されるのをフィルタが待っている間にデッドロックが発生することがある。前に説明したいくつかのメソッドでは、これを防ぐためにイベントへのハンドルを受け取る。フィルタは、自分の IMediaFilter::Stop メソッドへの呼び出しを受け取ると、このイベントをシグナル状態にする。詳細については、「IGraphConfig インターフェイス」および「IPinConnection インターフェイス」を参照すること。

フィルタ チェイン

"フィルタ チェイン"とは、以下の条件に合致するフィルタの集まりである。

  • チェイン内の各フィルタは、最大で、接続された入力ピンを 1 つと、接続された出力ピンを 1 つ持つ。
  • チェインの外部のフィルタを通らなくても、チェイン内のすべてのフィルタを通ることができる。

たとえば、次の図のフィルタ A–B、C–D、および F–G–H がフィルタ チェインである。F–G–H 内のサブチェイン (F–G および G–H) もフィルタ チェインである。フィルタ チェインは 1 つのフィルタで構成してもよいので、フィルタ A、B、C、D、F、G、および H も別々のフィルタ チェインである。フィルタ E には入力接続が 2 つあるので、フィルタ E を含むフィルタの集まりはフィルタ チェインではない。

フィルタ チェイン (例 1)

IFilterChain インターフェイスは、フィルタ チェインを制御するために以下のメソッドを提供している。

IFilterChain::StartChain | チェインを開始する。
IFilterChain::StopChain | チェインを停止する。
IFilterChain::PauseChain | チェインをポーズする。
IFilterChain::RemoveChain | チェインをグラフから削除する。

チェインを追加するための専用のメソッドはない。チェインを追加するには、IFilterGraph::AddFilter メソッドを使って新しいフィルタを挿入し、IGraphBuilder::Connect、IGraphBuilder::Render、または同様なメソッドを呼び出してそれらのフィルタを接続する。

グラフの実行中、フィルタ チェインは実行と停止の間で切り替わることができる。グラフがポーズしているとき、フィルタ チェインはポーズと停止の間で切り替わることができる。フィルタ チェインで可能な状態の変化はこれだけである。

フィルタ チェインのガイドライン

IFilterChain メソッドを使用するときは、グラフ内のフィルタがフィルタ チェインの操作をサポートしていることを確認しなければならない。サポートしていない場合、デッドロックやグラフ エラーが発生することがある。 チェインに接続されたフィルタは、チェインの状態が変化しても正しく機能しなければならない。

IFilterChain を使用する場合は、チェイン処理専用にデザインしたフィルタを使用するのが最良である。以下のガイドラインを使って、フィルタ チェイン処理の間にフィルタが安全であることを確実にすること。それらのポイントを次の図に示す。

フィルタ チェイン (例 2)

  • フィルタ チェインの状態が変わる前に、フィルタ チェインの境界にあるデータ処理の呼び出しがすべて完了していなければならない。この規則は、IMemInputPin::Receive、IPin::NewSegment、および IPin::EndOfStream メソッドに当てはまる。チェイン内のフィルタは、チェイン外部のフィルタによって行われたこれらのメソッドへの呼び出しから戻っていなければならず、チェイン外部のフィルタは、チェイン内のフィルタによって行われた呼び出しから戻っていなければならない。

    たとえば、上の図のフィルタ B は、フィルタ A からのデータ処理の呼び出しを完了しなければならず、フィルタ E は、フィルタ D からの呼び出しを完了しなければならない。ピンが IPinFlowControl および IPinConnection インターフェイスを公開している場合は、「動的再接続」で説明したように、IPinFlowControl::Block および IGraphConfig::PushThroughData メソッドを呼び出してデータをグラフに送り出すことができる。フィルタが、データを送り出すためのプライベート メソッドをサポートしている場合もある。

  • アップストリーム フィルタは、チェインの状態が変化することを予測していなければならない。たとえば、上の図で、チェインが停止しているのにフィルタ A が IMemInputPin::Receive を呼び出したとしよう。この呼び出しは失敗し、フィルタ A の応答はストリームを停止することである。フィルタ A がデータを流さないので、アプリケーションがチェインを再起動しても効果がない。
  • ダウンストリーム フィルタも、チェインの状態が変化することを予測していなければならない。そうでなければ、決して到着しないサンプルを待っている間に、ダウンストリーム フィルタはブロックしてしまうかもしれない。たとえば、マルチプレクサ (MUX) フィルタは、そのすべての入力ピンからのデータを必要なことが多い。ある入力ピンからのデータ フローが停止すると、ほかのストリームの処理がブロックされるかもしれない。これによって、グラフがデッドロックに陥ることがある。
  • チェイン外部のフィルタからチェイン内部のフィルタへのピン接続には、それぞれほかの接続と共有しない独自のアロケータを持たせるべきである。チェインの状態が変化したり、チェインがグラフから削除されたりすると、アロケータは関連を断たれるかもしれないからだ。ほかの接続が同じアロケータを使用していた場合、それらの接続はサンプルを処理できなくなる。
  • チェインに接続されたフィルタが動的接続解除をサポートしていないかぎり、チェインを削除してはいけない。通常、接続されたフィルタは、IPinConnection または IPinFlowControl インターフェイスをサポートする、しかしプライベート インターフェイスをサポートする場合もある。


PID

PID は、フィルタ グラフ マネージャの機能を拡張するための方法である。PID は、フィルタ グラフ マネージャが実行時に集成する COM オブジェクトである。アプリケーションは、フィルタ グラフ マネージャを通じて PID へのアクセスを取得する。

フィルタ グラフ マネージャに対して、サポートしないインターフェイスについて照会されると、次のフォーマットを使ってレジストリのキーが検索される。

HKEY_CLASSES_ROOT\Interface\IID\Distributor

IID は、インターフェイス識別子が含まれた文字列である。レジストリにエントリが存在する場合、そのエントリの値によって、インターフェイスをサポートする PID のクラス識別子 (CLSID) が定義される。フィルタ グラフ マネージャは PID を集成し、インターフェイス ポインタを返す。これによって、PID の外部 IUnknown として機能する。アプリケーションがインターフェイス上でメソッドを呼び出すときは、実際には PID 上で呼び出している。しかし、PID の存在はアプリケーションに対しては透過的である。

ディストリビュータ という用語は、PID がフィルタ グラフ マネージャのインターフェイスについて、外部 IUnknown ポインタに照会が可能なことに由来している。PID は IFilterGraph::EnumFilters メソッドを呼び出すことで、グラフのフィルタを列挙し、それらのフィルタにメソッド コールを配布できる。このようにして、PID はアプリケーションがフィルタ上でメソッドを呼び出すための、1 つのコントロール ポイントとしての役割を果たすことができる。

フィルタ グラフ マネージャが PID を集成するときは、IDistributorNotify インターフェイスについて PID に照会する。PID がこのインターフェイスをサポートしている場合、フィルタ グラフ マネージャはこのインターフェイスを使って、グラフでの変更について PID に通知する。

  • フィルタ グラフが実行、ポーズ、および停止の各状態を切り替える際には、IDistributorNotify::Run、IDistributorNotify::Pause、または IDistributorNotify::Stop を呼び出す。
  • 基準クロックが設定されると、フィルタ グラフ マネージャは IDistributorNotify::SetSyncSource を呼び出す。
  • フィルタが追加または削除されたり、ピン接続が変更されると、フィルタ グラフ マネージャは IDistributorNotify::NotifyGraphChange を呼び出す。

カスタム PID を実装するためには、集合をサポートする COM オブジェクトを作成する。このオブジェクトは、フィルタ グラフ マネージャが既にサポートしていないインターフェイスをサポートしなければならない。また、オプションで IDistributorNotify インターフェイスをサポートすることもできる。

PID がフィルタ グラフ マネージャからインターフェイス ポインタを取得する際は、それらをすぐに解放する必要がある。解放しないと、循環参照カウントが作成され、フィルタ グラフ マネージャの破壊を妨げる可能性がある。いずれの場合も、フィルタ グラフ マネージャが PID の継続時間を制御するため、フィルタ グラフ マネージャでの基準カウントの保持は不要である。

PID はフィルタ グラフ マネージャによる集成化のために設計されているので、PID のコンストラクタ メソッドでこれを設定することもできる。外部 IUnknown ポインタが NULL であるかどうかを確認し、NULL である場合は、エラー コード VFW_E_NEED_OWNER を返す。また、ほかのオブジェクトが PID を集成化しないようにするため、IGraphBuilder インターフェイスについて 外部 IUnknown ポインタに照会できる。そのオブジェクトが IGraphBuilder を公開していないなら、エラーコードを返す。


DirectShow の使い方

ここでは次の内容について説明する。

  • GraphEdit によるグラフ構築のシミュレーション
  • ファイルの再生
  • オーディオ キャプチャ
  • ビデオ キャプチャ
  • DirectShow 編集サービス
  • DVD アプリケーション
  • Windows Media アプリケーション
  • Microsoft TV テクノロジ
  • DirectShow フィルタの開発
  • DirectShow でのデバッグ
  • プログラミングのヒント


GraphEdit によるグラフ構築のシミュレーション

Microsoft® DirectX® SDK には、フィルタ グラフの作成とテストに使用する GraphEdit というデバッグ ユーティリティが提供されている。

ここでは次の内容について説明する。

  • GraphEdit の概要
  • GraphEdit の使い方
  • 外部プロセスからのグラフのロード

GraphEdit の概要

GraphEdit は、フィルタ グラフを構築するためのビジュアル ツールである。GraphEdit を使用すると、アプリケーション コードを書く前にフィルタ グラフをテストすることができる。また、アプリケーションで作成するフィルタ グラフをロードし、アプリケーションで正しいグラフが構築されることを検証できる。カスタム フィルタを開発した場合は、GraphEdit を使用してフィルタをすばやくテストできる。テストを行うには、カスタム フィルタを使ってグラフをロードし、グラフを実行するだけでよい。DirectShow を使ったことがない場合、GraphEdit は、フィルタ グラフおよび DirectShow アーキテクチャに慣れるよい方法である。

次の図は、GraphEdit で簡単なフィルタ グラフがどのように表現されるかを示している。

GraphEdit の簡単なフィルタ グラフ

各フィルタは矩形で表される。フィルタの周囲に付いている小さい四角はピンを表す。入力ピンはフィルタの左側にあり、出力ピンは右側にある。矢印はピンの間の接続を表す。

GraphEdit を使用すると、次のことができる。

  • ドラッグ アンド ドロップ式のビジュアル インターフェイスを使ってフィルタ グラフを作成、編集する。
  • IGraphBuilder::RenderFile など、グラフを構築するためのプログラムによる呼び出しをシミュレーションする。
  • グラフをラン、ポーズ、ストップ、シークする。
  • 使用しているコンピュータに登録されているフィルタを確認し、各フィルタのレジストリ情報を表示する。
  • フィルタ プロパティ ページを表示する。
  • ピン接続のメディア タイプを表示する。

GraphEdit の使い方

DirectX SDK をインストールすると、[スタート] メニューの [Microsoft DirectX 8 SDK] の下の [DX Utilities] に GraphEdit が表示される。実行モジュール ファイルは GraphEdt.exe で、デフォルトでは Mssdk\Bin\DXUtils フォルダにインストールされる。これらのどの場所からでも GraphEdit を開くことができる。

次に、GraphEdit を使って実行できることについて簡単に説明する。これらの機能 (およびその他の機能) の詳細については、GraphEdit アプリケーション ヘルプを参照すること。

ファイル再生グラフの構築

GraphEdit を使用すると、ファイルを再生するフィルタ グラフを構築できる。この機能は、アプリケーションで IGraphBuilder::RenderFile メソッドを呼び出すのと同じである。[File] メニューの [Render Media File] をクリックする。GraphEdit の [Open File] ダイアログ ボックスが表示される。マルチメディア ファイルを選択して [Open] をクリックする。選択したファイルを再生するためのフィルタ グラフが GraphEdit で構築される。

特定の URL にあるメディア ファイルをレンダリングすることもできる。[File] メニューの [Render URL] をクリックする。URL を指定するダイアログ ボックスが表示される。

カスタム フィルタ グラフの構築

GraphEdit では、システムに登録されているフィルタを使ってカスタム フィルタ グラフを構築できる。[Graph] メニューの [Insert Filters] をクリックする。システムに登録されているフィルタの一覧をフィルタ カテゴリ別に示すダイアログ ボックスが表示される。GraphEdit はレジストリの情報からこの一覧を構築する。次の図にこのダイアログ ボックスを示す。

[Which filters do you want to insert?] ダイアログ ボックス

グラフにフィルタを追加するには、フィルタの名前を選択して [Insert Filters] をクリックするか、フィルタ名をダブルクリックする。フィルタを追加した後、1 つのフィルタの出力ピンからもう 1 つのフィルタの入力ピンにマウスをドラッグすると、2 つのフィルタを接続できる。ピンが接続を受け入れると、ピンを接続する矢印が表示される。

グラフの実行

GraphEdit でフィルタ グラフを構築した後、グラフを実行し、グラフが予測どおりに動作するかどうかを確認できる。[Graph] メニューには、[Play]、[Pause]、および [Stop] のメニュー コマンドがある。これらのコマンドはそれぞれ、IMediaControl メソッドである Run、Pause、および Stop を呼び出す。 [GraphEdit] ツール バーにも、これらのコマンドを実行するボタンが表示される。

[Play]、[Pause]、および [Stop] ボタン

注 : GraphEdit の [Stop] コマンドは、最初にグラフをポーズし、タイム ゼロをシークする (グラフはシーク可能とする)。ファイルを再生するために、この動作でビデオ ウィンドウが最初にフレームにリセットされる。次に、GraphEdit は IMediaControl::Stop を呼び出す。

グラフがシーク可能な場合は、ツール バーの下に表示されるスライダ バーをドラッグすると、グラフをシークできる。スライダ バーをドラッグすると IMediaSeeking::SetPositions メソッドが呼び出される。

プロパティ ページの表示

カスタム プロパティ ページをサポートしているフィルタもある。カスタム プロパティ ページは、フィルタのプロパティを設定するためのユーザー インターフェイスを提供する。GraphEdit でフィルタのプロパティ ページを表示するには、フィルタを右クリックし、ポップアップ ウィンドウの [Properties] をクリックする。フィルタに定義されているプロパティ シートがある場合は、プロパティ シートがプロパティ ページに表示される。さらに、GraphEdit にはフィルタの各ピンのプロパティ シートが含まれている。ピン プロパティ シートは、フィルタではなく GraphEdit によって定義される。ピンが接続されている場合は、ピン プロパティ シートに接続のメディア タイプが表示される。ピンが接続されていない場合は、ピンの優先メディア タイプが表示される。

外部プロセスからのグラフのロード

GraphEdit は外部プロセスによって作成されたフィルタ グラフをロードできる。この機能を使用すると、アプリケーションにわずかなコードを追加するだけで、アプリケーションで構築するフィルタ グラフを正確に知ることができる。

アプリケーションでフィルタ グラフのインスタンスを実行中オブジェクト テーブル (ROT) に登録しなければならない。ROT は、実行中オブジェクトを追跡管理するグローバルにアクセス可能なルックアップ テーブルである。オブジェクトはモニカによって ROT に登録される。グラフに接続するために、GraphEdit は表示名が特定のフォーマットに一致するモニカを ROT で検索する。

!FilterGraph X pid Y

X と Y は、それぞれフィルタ グラフのアドレスとプロセス id を表す 16 進数である。

アプリケーションで最初にフィルタ グラフを作成するには、次の関数を呼び出す。

HRESULT AddToRot(IUnknown *pUnkGraph, DWORD *pdwRegister)
{
    IMoniker * pMoniker;
    IRunningObjectTable *pROT;
    if (FAILED(GetRunningObjectTable(0, &pROT))) {
        return E_FAIL;
    }
    WCHAR wsz[256];
    wsprintfW(wsz, L"FilterGraph %08p pid %08x", (DWORD_PTR)pUnkGraph, GetCurrentProcessId());
    HRESULT hr = CreateItemMoniker(L"!", wsz, &pMoniker);
    if (SUCCEEDED(hr)) {
        hr = pROT->Register(0, pUnkGraph, pMoniker, pdwRegister);
        pMoniker->Release();
    }
    pROT->Release();
    return hr;
}

この関数は、フィルタ グラフのモニカと新しい ROT 項目を作成する。最初のパラメータはフィルタ グラフのポインタである。2 番目のパラメータは、新しい ROT 項目を識別する値を受け取る。アプリケーションでフィルタ グラフを解放する前に、次の関数を呼び出して ROT 項目を削除する。pdwRegister パラメータは、AddToRot 関数から返される識別子である。

void RemoveFromRot(DWORD pdwRegister)
{
    IRunningObjectTable *pROT;
    if (SUCCEEDED(GetRunningObjectTable(0, &pROT))) {
        pROT->Revoke(pdwRegister);
        pROT->Release();
    }
}

次のコード例は、これらの関数を呼び出す方法を示している。この例では、ROT 項目を追加および削除するコードは条件付きでコンパイルされ、デバッグ ビルドにのみ組み込まれる。

IGraphBuilder *pGraph;
DWORD dwRegister;

// フィルタ グラフ マネージャを作成する。
CoCreateInstance(CLSID_FilterGraph, NULL, CLSCTX_INPROC_SERVER,
IID_IGraphBuilder, (void **) &pGraph);
#ifdef DEBUG
hr = AddToRot(pGraph, &dwRegister);
#endif

// アプリケーションの残りの部分 (省略)。

#ifdef DEBUG
RemoveFromRot(dwRegister);
#endif
pGraph->Release();

GraphEdit でフィルタ グラフを表示するには、アプリケーションと GraphEdit を同時に実行する。GraphEdit で [File] メニューの [Connect] をクリックする。[Connect To Graph] ダイアログ ボックスで、アプリケーションのプロセス id (pid) を選択し、[OK] をクリックする。GraphEdit はフィルタ グラフをロードし、表示する。予測できない結果になる可能性があるので、このグラフではその他の GraphEdit 機能を使用しないこと。たとえば、フィルタの追加、削除、またはグラフの停止、開始は行わないこと。GraphEdit を終了してから、アプリケーションを終了する。

注 : アプリケーションでは、終了時にさまざまなエラーが発生することがある。

次の図に [Connect To Graph] ダイアログ ボックスを示す。

[Connect To Graph] ダイアログ ボックス


ファイルの再生

ファイルを再生するために必要な基本手順については、「ファイルの再生法」を参照すること。

PlayWnd サンプル アプリケーションでは、基本手順の詳細を示すとともに、ビデオ ウィンドウのサイズと位置を管理する方法、および実行中オブジェクト テーブルにアプリケーションのフィルタ グラフを追加し、作成中のグラフを GraphEdit で "監視" できるようにする方法を示す。


オーディオ キャプチャ

Microsoft® DirectShow® を使用すると、マイクロホンやテープ プレーヤーなどのデバイスからシステムのサウンド カードによる入力を介して、オーディオ データをキャプチャできる。一般に、次のような状況での使用が考えられる。

  • ビデオ ストリームを後日ダビングする際に、ボイスオーバー ナレーションを録音
  • 従来のアナログ オーディオ コンテンツをデジタル フォーマットに変換
  • ネットワークを介した放送で、音声や音楽をキャプチャ
エンドユーザーがサウンド カードからハード ディスクにオーディオをキャプチャするにはいくつかのオプションがある。多くのサウンド カードには、オーディオ入力からミキシングや録音を行うためのアプリケーションが付属している。Microsoft® Windows® オペレーティング システムには、マイクロホンからの録音を行う単純なユーティリティ アプリケーションとして、サウンド レコーダーがある。Windows Media™ Tools には、このようなタスクを実行できるスタンドアロン アプリケーションの Windows Media Encoder がある。また、Windows Media Encoder は、DirectShow アプリケーションに Microsoft® DirectX® Media Object (DMO) として組み込むこともできる。ここでは、DirectShow を使った独自アプリケーションにオーディオ キャプチャ機能を統合する方法について説明する。

オーディオ キャプチャ フィルタ

サウンド カード上のアナログ入力からのオーディオ キャプチャは、オーディオ キャプチャ フィルタを使うことで可能になる。このフィルタでは、Microsoft® Platform SDK waveInXXX API (waveInOpen、waveInStart、waveInGetID など) を使用し、これらの API をドライバでサポートする任意のデバイスを DirectShow フィルタ グラフに追加できるようにする。オーディオ キャプチャ フィルタにより、マイクロホンやラインイン入力など、サウンド カード上のすべての入力が公開される。CD オーディオ入力からキャプチャすることもできるが、この場合、オーディオ ストリームは既にデジタル アナログ コンバータを経由しているため、オリジナルの CD と比較すると音質が低下する。CD からの直接デジタル キャプチャについては、Windows Media 7 SDK を参照すること。

各入力ピンの数、種類、性質、および名前は、サウンド カードとそのドライバにより異なる。特定のサウンド カードの機能を完全に理解して利用するには、カード製造業者からドキュメンテーションを入手する必要がある。

オーディオ キャプチャ フィルタは、サウンド カード上の入力を通常の DirectShow 入力ピンとして表す。これらのピンは、ドライバが入力ミキサー ラインとして何を公開するかを表す。これらのピンにデータは流れない。これらは各ラインのレベルを有効にして設定するための手段を提供するのみである。各ラインで利用できるコントロールの種類は、ドライバにより異なる、たとえばドライバによるサポートがあれば、入力ライン上の低音域部と高音域部を制御するためだけにピンを使うことができる。

GraphEdit ユーティリティ プログラム内のオーディオ キャプチャ フィルタを見るには、以下のようにする :

  • [Graph] メニューから、[Insert Filters] を選ぶ。
  • [Audio Capture Sources] カテゴリを展開する。
  • フィルタを選ぶ。
  • [Insert Filters] をクリックする。

システム上の各カードはフィルタの別々のインスタンスによって表現される。フィルタ上に見えるピンは違っているあるいは違った名前をもっている可能性がある、それはシステムのサウンドカードドライバに依存する。それらのピンは IAMAudioInputMixer インターフェイスをサポートする、IAMAudioInputMixer::put_Enableを使うことによってアプリケーションは入力 (複数も可) を選択できる。

入力の有効と無効を個別に切り替えることに加え、アプリケーションは低音域部、高音域部、およびボリューム レベルも個別に設定できる。複数の入力を同時にキャプチャする場合、フィルタ自体に実装されている IAMAudioInputMixer インターフェイスを通じて、ミキシング、低音域部、高音域部、およびボリューム レベル全体を制御できる。また、フィルタには IAMBufferNegotiation も実装されている。これはオーディオ プレビューにおける遅延時間制御に使用する。オーディオ キャプチャ フィルタのバッファ サイズは、既定では 0.5 秒に設定される。これはキャプチャ用に最適化されているが、ライブ オーディオをキャプチャしながらプレビューする場合は、ストリームのレンダリングに 0.5 秒の遅延が生じることになる。この遅延時間を短縮するには、IAMBufferNegotiation::SuggestAllocatorProperties メソッドを使って、ALLOCATOR_PROPERTIES 構造体の cbBuffer メンバにこれより小さいサイズを指定する。通常は 80 ミリ秒のバッファが安全であるが、30 ～ 40 ミリ秒のバッファでも十分なことが多い。バッファが小さすぎると、音質は低下する。

キャプチャに利用できるサンプリング レートとオーディオ フォーマットは、ドライバにより決定される。利用できるサンプリング レートとフォーマットを列挙するには、オーディオ キャプチャ フィルタの出力ピン上の IAMStreamConfig インターフェイスを使用する。フィルタは、出力ピンのメディア タイプを受け入れる任意のフィルタに、ダウンストリームを接続できる。その後、オーディオ データは、スピーカによるレンダリング、カスタムの変換フィルタによる変換、ファイルへの圧縮および書き込みが可能になる。

オーディオ キャプチャ フィルタ グラフ

次に、さまざまなオーディオ キャプチャ ソリューションに対して考えられるいくつかのフィルタ グラフを示す。

  • オーディオ キャプチャ > AVI Mux > ファイル ライタ (オーディオ専用 AVI ファイルを作成する場合)
  • オーディオ キャプチャ > WavDest > ファイル ライタ (WAV ファイルを作成する場合)
  • オーディオ キャプチャ > ASF ライタ (Windows Media Audio ファイルを作成する場合)

注 WaveDest フィルタはサンプルとして提供されるが、構築と登録はユーザー自身が行わなければならない。

オーディオ キャプチャ フィルタ グラフの作成

オーディオ キャプチャ フィルタ グラフを作成するには、次の 3 つの基本作業がある。

  1. グラフの構築
  2. オーディオ キャプチャ ソースの列挙
  3. ユーザーによる入力ライン選択への対応

グラフの構築

ファイルに書き込むオーディオ キャプチャ グラフの構築方法は、作成するファイルのフォーマットにより異なる。AVI フォーマットに保存する場合、Capture Graph Builder を使ってグラフを構築する。これが最も簡単なオーディオ キャプチャ方法である。結果のファイルには、1 つのオーディオ ストリームが含まれ、ビデオ ストリームは含まれない。ASF フォーマットに保存する場合も Capture Graph Builder を使用できるが、あらかじめ Windows Media SDK をインストールして、アンロックするソフトウェア キーを取得する必要がある。Capture Graph Builder の使用法の詳細については、「キャプチャ アプリケーションの書き方」を参照すること。その情報の多くは、オーディオ専用グラフにも同様に適用できる。

WAV ファイルに書き込む場合、このファイルは WaveDest フィルタを認識しないので、Capture Graph Builder を使用できない。DirectShow はこのフィルタをサンプルとしてのみ提供し、コンパイルと登録はユーザーが行う必要がある。WaveDest をローカル システムに登録したら、IFilterGraph::AddFilter メソッドでオーディオ キャプチャ フィルタ、WavDest フィルタ、およびファイル ライタ フィルタをグラフに追加し、IFilterGraph::ConnectDirect メソッドでピンを接続することでグラフを手動で構築する必要がある。

オーディオ キャプチャ ソースの列挙

フィルタ グラフ マネージャおよび Capture Graph Builder またはその一方のインスタンスを作成してから、System Device Enumerator を使って、システム上で利用できるすべてのオーディオ キャプチャ デバイスの一覧を取得する。この方法の詳細については、「デバイスとフィルタの列挙」を参照すること。返された一覧の先頭にあるデバイスは、ユーザーが 優先録音デバイスとして選択したデバイスとなる (優先デバイスを選択するには、コントロールパネルの [サウンドとマルチメディア] をクリックする)。 デバイス列挙チュートリアルもデバイスを指定するフレンドリ名文字列の取得方法を示す。するとこの文字列がリストボックスに挿入され、複数デバイスからユーザーが選択可能になる

ユーザーによる入力ライン選択への対応

オーディオ キャプチャ フィルタをグラフに追加したら、IAMAudioInputMixer インターフェイス メソッドを使って、有効にするライン、およびそのラインのボリューム、低音域部、および高音域部の設定を選択できる (ドライバでサポートされる場合)。また、フィルタのプロパティ ページを使う方法でも、ユーザーが利用できるピンから選択したり、各種レベルを設定したりすることができる。詳細については、「フィルタのプロパティ ページの表示」および「オーディオ キャプチャ フィルタ」を参照すること。そのほかに、アプリケーションのプログラミング コードでピンを列挙して、独自のユーザー インターフェイスを作成することもできる。ピンの列挙についての情報は、「ピンの列挙」を参照すること。


ビデオ キャプチャ

ここでは、Microsoft® DirectShow® を使用してビデオ キャプチャ アプリケーションを作成する方法について説明する。

  • キャプチャ アプリケーションの書き方
  • デジタル ビデオ (DV)
  • WDM ビデオ キャプチャについて
  • キャプチャ パフォーマンスの向上
  • キャプチャに関する高度なトピック


キャプチャ アプリケーションの書き方

このトピックでは、Microsoft® DirectShow® を使ってビデオ キャプチャ アプリケーションを書く方法を説明する。以下のセクションで構成される。

  • DirectShow でのキャプチャの概要
  • キャプチャ グラフの作成
  • グラフ プロパティの設定
  • キャプチャ グラフの制御
  • デバイスの削除

DirectShow でのキャプチャの概要

"キャプチャ"という用語は、ファイルへの書き込みの意味があるが、キャプチャしたデータのプレビューやその他の使用方法の意味も含んでいる。キャプチャはビデオ カメラに限定されるものではなく、テレビ チューナーなどもキャプチャ デバイスである。ここでは、オーディオおよびビデオのキャプチャについて説明するが、キャプチャ データには、クローズド キャプションや垂直同期間隔 (VBI) のデータが含まれる場合があることを覚えておいてほしい。

キャプチャ グラフ

DirectShow は、ほかのタスクと同様にフィルタ グラフを使ってキャプチャを処理する。この種類のグラフは "キャプチャ グラフ" と呼ばれる。さまざまなハードウェア デバイスやデータ フォーマットを利用できるため、キャプチャ グラフはいろいろな方法で設定できる。ほとんどのキャプチャ グラフには、以下のような共通点がある。

  • データをキャプチャするために、グラフは 1 つ以上のキャプチャ フィルタを必要とする。各キャプチャ フィルタは、ビデオ カメラなどのハードウェア デバイスを表す。
  • データをプレビューするために、グラフはオーディオおよびビデオのレンダリング フィルタを必要とする。
  • ファイル キャプチャの場合、グラフはファイルを書き出すフィルタを必要とし、場合によっては、AVI Mux フィルタ
    • などのマルチプレクサ (mux) フィルタが 1 つ以上必要になる。
  • キャプチャ デバイスが WDM (Windows Driver Model) ドライバを使用する場合、グラフにはキャプチャ フィルタからのフィルタのアップストリームが必要になることがある。これらのフィルタは、ストリーム クラス ドライバ フィルタと呼ばれ、ハードウェアが提供する追加機能をサポートする。たとえば、テレビ チューナー カードにはチャンネルを設定するための機能がある。それに対応するフィルタが、TV チューナー フィルタである。

次の図は、典型的なキャプチャ グラフでのフィルタの種類を示す。波線は、デコーダ フィルタやスプリッタ フィルタなどの追加フィルタが必要になるかもしれない部分を示している。

キャプチャ グラフの作成を簡単にするために、DirectShow はキャプチャ グラフ ビルダというコンポーネントを提供している。このコンポーネントが公開する ICaptureGraphBuilder2 インターフェイスが、キャプチャ グラフを作成して制御するためのメソッドを持っている。このトピックでは、キャプチャ アプリケーションでキャプチャ グラフ ビルダを使用することを前提にしている。

キャプチャ フィルタ

キャプチャ フィルタは、1 つ以上の出力ピンを通じてデータを配信する。出力ピンは、配信する"メディア タイプ"と"ピン カテゴリ"によって分類できる。

メディア タイプは、メジャー タイプ GUID によって表される。最も共通のメディア タイプは以下の表のとおりである。

メディア タイプ | メジャー タイプ GUID
オーディオ | MEDIATYPE_Audio
インターリーブされたデジタル ビデオ (DV) | MEDIATYPE_Interleaved
MPEG ストリーム | MEDIATYPE_Stream
ビデオ | MEDIATYPE_Video

ピン カテゴリはピンの目的と機能を示すもので、プロパティ セット GUID で表される。ピン カテゴリはいくつかあるが、ここでは以下の 2 つについて説明する。

  • PIN_CATEGORY_CAPTURE: ピンはファイル キャプチャ用データを提供する。
  • PIN_CATEGORY_PREVIEW: ピンはプレビュー用データを提供する。

すべてのピン カテゴリについては、「ピン プロパティ セット」を参照すること。

メディア タイプとピン カテゴリを、ピンに直接問い合わせることができる。メディア タイプを取得するには IPin::EnumMediaTypes メソッドを呼び出し、ピン カテゴリを取得するには IKsPropertySet::Get メソッドを呼び出す。ただし、ICaptureGraphBuilder2 メソッドを使用すれば、各ピンに問い合わせなくても、特定のメディア タイプまたはピン カテゴリに操作を限定することができる。

キャプチャ グラフの作成

キャプチャ グラフは以下の手順で作成する。

  1. 必要なコンポーネントの作成
  2. キャプチャ デバイスの選択
  3. ファイル書き込みセクションの作成
  4. ストリームのレンダリング

必要なコンポーネントの作成

キャプチャ グラフの作成では、まず空のフィルタ グラフとキャプチャ グラフ ビルダを作成する。次に、ICaptureGraphBuilder2::SetFiltergraph を呼び出して、フィルタ グラフをキャプチャ グラフ ビルダに関連付ける。以下のコードにこれらの手順を示す。

IGraphBuilder *pGraph = NULL;
ICaptureGraphBuilder2 *pBuilder = NULL;

// フィルタ グラフを作成する。
CoCreateInstance(CLSID_FilterGraph, NULL, CLSCTX_INPROC,
    IID_IGraphBuilder, (void **)&pGraph);

// キャプチャ グラフ ビルダを作成する。
CoCreateInstance(CLSID_CaptureGraphBuilder2, NULL, CLSCTX_INPROC,
    IID_ICaptureGraphBuilder2, (void **)&pBuilder);

pBuilder->SetFiltergraph(pGraph);

キャプチャ デバイスの選択

2 つめのステップは、システム デバイス 列挙子を使用したキャプチャ デバイスの選択である。詳細については、「システム デバイス列挙子の使用」を参照すること。以下のコードは、ビデオ キャプチャ デバイスを列挙し、列挙シーケンス内の最初のデバイスを選択する。

// システム デバイス列挙子を作成する。
ICreateDevEnum *pDevEnum = NULL;
CoCreateInstance(CLSID_SystemDeviceEnum, NULL, CLSCTX_INPROC,
    IID_ICreateDevEnum, (void **)&pDevEnum);

// ビデオ キャプチャ デバイスの列挙子を作成する。
IEnumMoniker *pClassEnum = NULL;
pDevEnum->CreateClassEnumerator(CLSID_VideoInputDeviceCategory, &pClassEnum, 0);

ULONG cFetched;
IMoniker *pMoniker = NULL;
IBaseFilter *pSrc = NULL;
if (pClassEnum->Next(1, &pMoniker, &cFetched) == S_OK)
{
    // 最初のモニカをフィルタ オブジェクトにバインドする。
    pMoniker->BindToObject(0, 0, IID_IBaseFilter, (void**)&pSrc);
    pMoniker->Release();
}
pClassEnum->Release();
pDevEnum->Release();

一般的には、使用可能なデバイスの名前が入ったリスト ボックスを表示して、ユーザーにデバイスを選択させるのが普通だろう。そうするには、IMoniker::BindToStorage メソッドを呼び出して、デバイス モニカのプロパティ バッグを取得し、IPropertyBag::Read メソッドを呼び出して、デバイスのフレンドリ名を取得する。詳細については、「システム デバイス列挙子の使用」を参照すること。

ここで、以下のようにキャプチャ フィルタをグラフに追加する。

// pSrc は、前のコードのキャプチャ フィルタである。
pGraph->AddFilter(pSrc, L"Video Capture");

注 : オーディオとビデオの両方をキャプチャするデバイスは、[Audio Capture Sources] と [Video Capture Sources] の 2 つのカテゴリに表示される。一方のカテゴリからデバイスを選択した後、フィルタの出力ピンのメディア タイプをチェックする。デバイスが両方のカテゴリに分類される場合は、2 つめのデバイスを追加してはいけない。これは、インターリーブされたオーディオ/ビデオを生成するデジタル ビデオ (DV) カメラの場合にも当てはまる。

ファイル書き込みセクションの作成

ファイル キャプチャを実行するために、フィルタ グラフにファイル書き込みセクションを追加する(プレビュー機能だけが必要な場合は、このステップを飛ばしてよい)。ICaptureGraphBuilder2::SetOutputFileName メソッドを使用する。このメソッドは、必要な mux フィルタとファイル書き込みフィルタをグラフに追加する。このメソッドは、出力ファイルの名前とフォーマットを指定する入力パラメータを受け取るが、フォーマットについては以下のいずれかの値を使用できる。

  • MEDIASUBTYPE_Avi: AVI ファイルを書き出す。
  • MEDIASUBTYPE_Asf: ASF ファイルを書き出す。
  • マルチプレクサ フィルタまたはファイル ライタ フィルタのクラス識別子 (CLSID)。

3 つめのオプションは、サードパーティ製のフィルタを使用するためのものである。たとえば、MPEG データを渡すキャプチャ デバイスがあるが、DirectShow には MPEG ライタ フィルタが付属していないので、MPEG ファイルを書き出すにはサードパーティ製のフィルタが必要になる。

以下の例では、出力ファイルの名前を Example.avi に設定し、フォーマットを AVI に設定している。

IBaseFilter     *ppf = NULL;
IFileSinkFilter *pSink = NULL;
pBuilder->SetOutputFileName(&MEDIASUBTYPE_Avi, L"C:\\Example.avi", &ppf, &pSink);

このメソッドは、戻ってくると "ppf" パラメータをマルチプレクサの IBaseFilter インターフェイスに設定し、"pSink" パラメータをファイル ライタの IFileSinkFilter インターフェイスに設定する。これらは同じフィルタであってもよい。たとえば、ASF ライタ フィルタはファイル書き込みとマルチプレクサ処理の両方を行う。

次の図は、AVI ファイル (左) と ASF ファイル (右) の書き込みに使用するフィルタを示す。

AVI ファイルと ASF ファイルの書き込みに使用するフィルタ

AVI Mux フィルタは IConfigAviMux インターフェイスおよび IConfigInterleaving インターフェイスを公開し、ASF ライタ フィルタは IConfigAsfWriter インターフェイスを公開する。これらのインターフェイスを使って、出力ファイルのフォーマットを設定することができる。ASF ファイルの場合は、ソフトウェア証明書も与えなければならない。詳細については、「DirectShow での ASF ファイルの作成」を参照すること。

注 : ICaptureGraphBuilder2::AllocCapFile メソッドを使って、キャプチャ ファイルを前もって割り当てておくことをお勧めする。前もって割り当てた大きなファイルにキャプチャすれば、キャプチャのパフォーマンスが向上する。

ストリームのレンダリング

キャプチャ グラフ作成の最終ステップは、グラフ内のストリームのレンダリングである。ファイル キャプチャの場合、キャプチャ ピンは、前に説明したファイル書き込みセクションに接続される。プレビューの場合、プレビュー ピンはオーディオおよびビデオ レンダラに接続される。ただし、キャプチャ フィルタにプレビュー ピンがない場合は、代わりにキャプチャ ピンを使用しなければならない。同じピンをキャプチャとプレビューに使用するためには、キャプチャ ピンはスマート ティー フィルタに接続されていなければならない。このフィルタは、データをキャプチャ ストリームとプレビュー ストリームの 2 つに分離する。

次の図は、スマート ティー フィルタを使用するグラフを示す。

ICaptureGraphBuilder2::RenderStream メソッドが、これらのタスクをすべて処理し、必要な場合は スマート ティー フィルタを追加する。このメソッドは、WDM デバイスに必要なサポート フィルタも自動的に追加する。以下のコードは、ファイル キャプチャ用のビデオ ストリームをレンダリングする。

pBuilder->RenderStream(
        &PIN_CATEGORY_CAPTURE,  // ピン カテゴリ
        &MEDIATYPE_Video,       // メディア タイプ
        pSrc,                   // キャプチャ フィルタ
        NULL,                   // 圧縮フィルタ (オプション)
        ppf                     // マルチプレクサまたはレンダリング フィルタ
    );

最初の 2 つのパラメータで、ピン カテゴリとメディア タイプを指定する。それに続く 3 つのパラメータは、以下のフィルタへのポインタである。

  • キャプチャ フィルタ。
  • ストリームを圧縮するためのオプションの圧縮フィルタ (この例では使用していない)。
  • マルチプレクサまたはレンダリング フィルタ。ファイル書き込みセクションの作成で説明したように、SetOutputFileName メソッドの "ppf" パラメータで返されるポインタを使用する。

プレビューのストリームをレンダリングするには、ピン カテゴリに PIN_CATEGORY_PREVIEW を使用し、最後の 2 つのパラメータに NULL を使用する。キャプチャ フィルタにプレビュー ピンがない場合、キャプチャ グラフ ビルダは自動的に スマート ティー フィルタを使用する。以下のコードは、ビデオ プレビュー ストリームをレンダリングする。

pBuilder->RenderStream(
        &PIN_CATEGORY_PREVIEW,
        &MEDIATYPE_Video,
        pSrc,
        NULL,   // 圧縮フィルタなし
        NULL    // デフォルトのレンダラ
    );

レンダリングするメディア タイプごとに、これらの RenderStream への呼び出しを繰り返す。

注 : DV キャプチャ フィルタの中には、インターリーブされたデータ (MEDIATYPE_Interleaved) 用に 1 つのピンを持ち、ビデオだけのデータ (MEDIATYPE_Video) 用に別のピンを持つものがある。両方ではなく、いずれか一方をレンダリングする。ビデオ専用ピンをレンダリングする場合、キャプチャ データはオーディオを持たない。

グラフ プロパティの設定

グラフ内のさまざまなフィルタやピンは、プロパティを設定および取得するためのインターフェイスを公開している場合がある。ICaptureGraphBuilder2::FindInterface メソッドを使って、それらのインターフェイスへのポインタを取得する。

アプリケーションによって異なるが、以下の表にあるインターフェイスが役に立つと思われる。

IAMAudioInputMixer | オーディオ入力プロパティを設定する。
IAMDroppedFrames | ドロップ フレーム情報を取得する。
IAMVfwCaptureDialogs | Microsoft® Video for Windows® のキャプチャ ドライバ用に提供されるダイアログ ボックスを表示する。
IAMVideoCompression | 圧縮パラメータを設定する。

以下のコードは、インターリーブされたオーディオ/ビデオ ピンから IAMDroppedFrames インターフェイスを取得する。

IAMDroppedFrames *pDropped = NULL;
pBuilder->FindInterface(&PIN_CATEGORY_CAPTURE, &MEDIATYPE_Interleaved,
    pSrc, IID_IAMDroppedFrames, (void **)&pDropped);

ただし、ビデオ再生ウィンドウを制御するためのメソッドが含まれる IVideoWindow インターフェイスを取得する場合は、FindInterface メソッドを呼び出さない。代わりに、フィルタ グラフにこのインターフェイスの有無を問い合わせる。そうしないと、画面解像度などのイベントにフィルタ グラフが正しく応答しなくなる。IVideoWindow を使用すると、プレビュー ウィンドウをアプリケーション ウィンドウの子ウィンドウにすることができる。詳細については、「ビデオ ウィンドウの設定」を参照すること。

注 : プレビュー ストリームをレンダリングしないときでも、キャプチャ グラフ ビルダはプレビュー ウィンドウを追加することがある。一部のハードウェア デバイスは、ビデオ キャプチャのためにビデオ ポート エクステンション (VPE) を使用するのでプレビュー ウィンドウが必要になる。そのため、常にフィルタ グラフに IVideoWindow の有無を問い合わせるのがよいだろう。フィルタ グラフがこのインターフェイスを公開している場合は、ビデオ ウィンドウをアプリケーション ウィンドウの子ウィンドウにする。

キャプチャ グラフの制御

フィルタ グラフの IMediaControl インターフェイスには、グラフ全体を実行、停止、およびポーズするためのメソッドがあるが、グラフに複数のストリームがある場合はそれらを独立して制御したいことがある。たとえば、キャプチャ ストリームを停止した状態でプレビュー ストリームを実行する場合や、プレビューの間はオーディオをミュートして、ファイル キャプチャの間は有効にするような場合だ。

ICaptureGraphBuilder2::ControlStream メソッドが、それぞれのストリームの開始タイムと終了タイムを設定する手段を提供する。IMediaControl::Run を呼び出す前に、このメソッドを呼び出す。Run を呼び出すと、ControlStream の呼び出しに含まれないストリームが直ちに開始される。

以下のコードは、ビデオ キャプチャ ストリームを 2 秒の位置から開始し、5 秒の位置で停止する。

IMediaControl   *pControl;
REFERENCE_TIME  rtStart = 20000000,
                rtStop = 50000000;

pBuilder->ControlStream(
        &PIN_CATEGORY_CAPTURE,
        &MEDIATYPE_Video,
        pSrc,       // ソース フィルタ
        &rtStart,   // 開始タイム
        &rtStop,    // 終了タイム
        0,          // 開始クッキー
        0           // 停止クッキー
    );
pGraph->QueryInterface(IID_IMediaControl, (void **)&pControl);
pControl->Run();

最初の 3 つのパラメータで、ピン カテゴリ、メディア タイプ、およびキャプチャ フィルタによって制御するストリームを指定する。最後の 2 つのパラメータは、開始および停止のイベントを識別するために使用できるクッキーだ。クッキーは、アプリケーションで定義する任意の値である。詳細については、「ICaptureGraphBuilder2::ControlStream」を参照すること。

複数のストリームを一度に制御する場合は、メディア タイプとソース フィルタを省略する。以下の例では、グラフ内のすべてのキャプチャ ストリームを制御している。

pBuilder->ControlStream(&PIN_CATEGORY_CAPTURE, NULL, NULL,
    &rtStart, &rtStop, 0, 0);
pControl->Run();

デバイスの削除

グラフが使用していたプラグ アンド プレイ デバイスをユーザーが削除すると、フィルタ グラフ マネージャが EC_DEVICE_LOST イベントを発行する。そのデバイスが再び使用可能になると、フィルタ グラフ マネージャはもう一度 EC_DEVICE_LOST イベントを送信する。しかし、キャプチャ グラフの前の状態は正しくなくなる。アプリケーションは、デバイスを使用するためにグラフを再作成しなければならない。詳細については、「DirectShow でのイベント通知」を参照すること。


デジタル ビデオ

このトピックでは、デジタル ビデオ (DV) アプリケーションで Microsoft® DirectShow® を使用する方法を解説する。以下の項目で構成される :

  • DirectShow でのデジタル ビデオ
  • DV カムコーダの制御


DirectShow でのデジタル ビデオ

このトピックでは、Microsoft® DirectShow® でのデジタル ビデオ (DV) の使用方法の概要について説明する。以下のセクションで構成される。

  • DV のシナリオ
  • type-1 ファイルと type-2 ファイル
  • DirectShow の DV フィルタ
  • MSDV ドライバ

DV のシナリオ

DV を扱う場合、データはデバイスからコンピュータへ移動して、またデバイスに戻るというライフサイクルをたどるのが普通だ。DirectShow は、以下の表に示されるような各段階をサポートしている。

段階 | DirectShow のサポート | 参照
カメラからファイルへのビデオのキャプチャ | ICaptureGraphBuilder2 | キャプチャ アプリケーションの書き方
ファイルの編集 | DirectShow 編集サービス |
ファイルの再生 | IGraphBuilder::RenderFile | ファイルの再生法
ファイルからテープへの送信 | WDM ビデオ キャプチャ フィルタのデバイス コントロール インターフェイス | DV カムコーダの制御

type-1 ファイルと type-2 ファイル

DV カメラは、インターリーブされたオーディオ-ビデオを生成する。ビデオの各フレームには、オーディオ データも含まれている。DV データを AVI ファイルに保存する場合、以下のオプションがある。

  • インターリーブされたネイティブ データを、データ型 ivas で、単一のストリームとして AVI ファイルに含めることができる。これを type-1 ファイルと呼ぶ。
  • DV データを、データ型 auds および vids として、別々のオーディオ ストリームとビデオ ストリームに分割できる。これを type-2 ファイルと呼ぶ。

ビデオ キャプチャの場合、最大のスループットが苦しい場面ではデータを type-1 として保存する方がよい。type-2 ファイルには冗長なデータが含まれるからだ。type-2 ファイルのビデオ ストリームには、まだオーディオ データが含まれているが、ストリームをビデオとしてラベル付けすることでオーディオ データは隠されている。また、インターリーブされたストリームを分割するために、ある程度のプロセッサ タイムが必要になる。

一方、type-1 フォーマットはリアルタイム編集の場合に問題がある。アプリケーションは、インターリーブされたストリームからオーディオ データを抽出し、編集してからもう一度データをインターリーブしなければならない。また、type-1 フォーマットは Microsoft® Video for Windows® (VfW) と互換性がない。DirectShow は、両方のタイプのファイルを扱うことができる。

DirectShow の DV フィルタ

DirectShow は、DV データの操作用に以下のフィルタを提供している。

  • DV スプリッタ: インターリーブされたストリームを、別々のオーディオ ストリームとビデオ ストリームに分割する。
  • DV Muxer: オーディオ ストリームとビデオ ストリームを、1 つのインターリーブされたストリームに結合する。
  • DV ビデオ デコーダ: DV ビデオ ストリームを非圧縮ビデオにデコードする。
  • DV ビデオ エンコーダ: 非圧縮ビデオ ストリームを DV ビデオにエンコードする。

これらのフィルタは、次の図に示すように対になって機能する。DV スプリッタが type-1 を type-2 に分割し、DV ビデオ デコーダが type-2 ビデオを非圧縮ビデオに変換する。

反対方向には、DV ビデオ エンコーダが非圧縮ビデオを type-2 ビデオに変換し、DV Muxer が type-2 ストリームを type-1 ストリームに結合する。

DV ビデオ エンコーダが公開する IDVEnc インターフェイスに、エンコード規格 (NTSC や PAL) を設定するためのメソッドが含まれている。DV ビデオ デコーダが公開する IIPDVDec インターフェイスには、デコード解像度を設定するためのメソッドが含まれている。

MSDV ドライバ

Microsoft® Windows® は、DV カムコーダ向け MSDV (Msdv.sys) という WDM ドライバを提供している。このドライバはアプリケーションに WDM ビデオ キャプチャ フィルタをエクスポートする。MSDV はそのフィルタの参照ページに記述されているインターフェイスのサブセットをサポートする。ユーザーのシステムで DV カムコーダが使用できる場合、システム デバイスを列挙すると、ビデオ キャプチャ ソース カテゴリ (CLSID_VideoInputDeviceCategory) にカムコーダが現れる。それはまたレンダリング デバイスとして表示される。そのフレンドリ名は、"Microsoft DV Camera and VCR." になる。詳細については、「デバイスとフィルタの列挙」を参照すること。

MSDV には出力ピンが 2 つある。1 つは、インターリーブされたオーディオ-ビデオ データを出力し、もう 1 つはオーディオを含まないビデオ データを出力する。MSDV には入力ピンが 1 つあり、このピンはデータをカムコーダに送信する。カムコーダはキャプチャと送信を同時に行えないので、MSDV が入出力を同時に接続することはない。

MSDV の使用上のヒント:

  • IGraphBuilder::Render メソッドを使って MSDV の出力ピンを接続することはできない。フィルタ グラフ マネージャは、出力ピンを MSDV 自体の入力ピンに接続しようとする。MSDV は接続を拒否し、メソッド呼び出しは失敗する。代わりに、IGraphBuilder::Connect または ICaptureGraphBuilder2::RenderStream を使用すること。
  • MSDV がフィルタ グラフ内にあるときは、MSDV を常にグラフの基準クロックとして機能させるべきだ。DirectX 8.0 からは、フィルタ グラフ マネージャが自動的に MSDV を基準クロックとして選択する。それより前のバージョンでは、フィルタ グラフ マネージャの IMediaFilter::SetSyncSource メソッドを呼び出さなければならない。詳細については、「DirectShow のタイムとクロック」を参照すること。


DV カムコーダの制御

このトピックでは、Microsoft® DirectShow® を使ってデジタル ビデオ (DV) カムコーダを制御する方法を説明する。以下のセクションで構成される。

  • 概要
  • デバイスの情報
  • デバイスの制御
  • 送信
  • 補足資料

DirectShow での DV の全般的な情報については、「DirectShow でのデジタル ビデオ」を参照すること。

概要

WDM ビデオ キャプチャ フィルタは、カムコーダの制御用に以下の 3 つのインターフェイスを公開している。

IAMExtDevice | 外部デバイス制御用の基本インターフェイス。
IAMExtTransport | VCR 機能を制御する。
IAMTimeCodeReader | デバイスからタイムコードを読み取る。

キャプチャ デバイスを選択し、キャプチャ フィルタのインスタンスを生成した後、フィルタにこれらのインターフェイスの有無を問い合わせる。以下の例では、インターフェイス ポインタと共に、各インターフェイスの利用可能性を示すブール値を保持するカスタム構造体を宣言している。

struct _MyDevCap
{
    IAMExtDevice       *pDevice;
    IAMExtTransport    *pTransport;
    IAMTimecodeReader  *pTimecode;
    BOOL                bHasDevice;
    BOOL                bHasTransport;
    BOOL                bHasTimecode;
} MyDevCap;

HRESULT hr;
IBaseFilter *pDVCam;  // キャプチャ フィルタへのポインタ。

// キャプチャ フィルタのインスタンスを生成する (表示されない)。

hr = pDVCam->QueryInterface(IID_IAMExtDevice, (void **)&MyDevCap.pDevice);
MyDevCap.bHasDevice = (SUCCEEDED(hr));

hr = pDVCam->QueryInterface(IID_IAMExtTransport, (void **)&MyDevCap.pTransport);
MyDevCap.bHasTransport = (SUCCEEDED(hr));

hr = pDVCam->QueryInterface(IID_IAMTimecodeReader, (void **)&MyDevCap.pTimecode);
MyDevCap.bHasTimecode = (SUCCEEDED(hr));

注 : DV カムコーダ ドライバの Msdv.sys と共にこれらのインターフェイスを使用する場合は、ヘッダー ファイル XPrtDefs.h をプロジェクトに含める。このファイルは、msdn.microsoft.com/library/techart/dvsupport.htm から入手できる。

デバイスの情報

デバイス コントロール インターフェイスを使用すると、デバイスの状態と能力を問い合わせることができる。このセクションでは、いくつかの取得可能で有益な項目について説明する。詳細については、インターフェイスのリファレンスを参照すること。

デバイス タイプ

キャプチャ デバイスに関する情報で最も重要なものは、デバイスのタイプである。デバイスが VCR 機能を持っているのか、単なるカメラなのかといった情報だ。デバイス タイプを取得するには、値 ED_DEVCAP_DEVICE_TYPE を使って IAMExtDevice::GetCapability メソッドを呼び出す。このメソッドが値 ED_DEVTYPE_VCR を返した場合、デバイスは VCR であり、ポーズ、停止、早送り、巻き戻しなどの機能を持っている。以下のコードに、デバイス タイプを問い合わせる方法を示す。

if (MyDevCap.bHasDevice)
{
    LONG lDeviceType = 0;
    MyDevCap.pDevice->GetCapability(ED_DEVCAP_DEVICE_TYPE, &lDeviceType, 0);

    if (lDeviceType == ED_DEVTYPE_VCR) {
        // デバイスは VCR である。すべての VCR 機能を有効にする。
    }
    else {
        // デバイスはカメラである。
        // 録画と録画ポーズを有効にし、その他の機能は無効にする。
    }
}

注 : 通常、カムコーダは VCR 機能とカメラ機能の間で切り替えることができ、それに応じたデバイス タイプを返す。カムコーダがオフラインになった場合、次に使用可能になったときにもう一度問い合わせる必要がある。デバイスが削除されると、フィルタ グラフ マネージャが EC_DEVICE_LOST イベントを送信する。詳細については、「キャプチャ アプリケーションの書き方」を参照すること。

デバイスの転送状態

再生、ポーズ、停止など、デバイスの現在の状態を取得するには、IAMExtTransport::get_Mode メソッドを呼び出す。このメソッドは、デバイスの状態を示す以下のような定数を取得する。

値 | デバイスの状態
ED_MODE_PLAY | 再生
ED_MODE_STOP | 停止
ED_MODE_FREEZE | ポーズ
ED_MODE_FF | 早送り
ED_MODE_REW | 巻き戻し
ED_MODE_RECORD | 録画
ED_MODE_RECORD_FREEZE | 録画ポーズ

タイムコード

DV テープが再生中、または録画ポーズ モードの間は、IAMTimecodeReader::GetTimecode メソッドを呼び出して、SMPTE タイムコードまたは絶対トラック番号を取得することができる。このメソッドは、タイムコードを記述する TIMECODE_SAMPLE 構造体へのポインタを受け取る。このメソッドを呼び出す前に、構造体の dwFlags メンバを初期化する。タイムコードを取得する場合は値 ED_DEVCAP_TIMECODE_READ を使用し、絶対トラック番号を取得する場合は値 ED_DEVCAP_ATN_READ を使用する。

TIMECODE_SAMPLE 構造体の timecode メンバが、TIMECODE 構造体である。メソッドが戻ると、TIMECODE 構造体の dwFrames メンバにタイムコードまたはトラック番号が格納されている。タイムコードの場合は、時間、分、秒、およびフレームが、hhmmssff のフォーマットで 2 進化 10 進法 (BCD) の値として DWORD にパックされている。ビットマスクを使ってそれぞれの値を取り出す。

以下の例では、タイムコードとトラック番号を取り出している。情報を表示する関数 DisplayTimecode と DisplayTrackNum は、アプリケーションで定義されているものとする。

if (MyDevCap.bHasTimecode)
{
    TIMECODE_SAMPLE TimecodeSample;
    TimecodeSample.timecode.dwFrames = 0;
    char szBuf[32];

    TimecodeSample.dwFlags = ED_DEVCAP_TIMECODE_READ;
    if (hr = MyDevCap.pTimecode->GetTimecode(&TimecodeSample), SUCCEEDED(hr))
    {
        wsprintf(szBuf, "TIMECODE %.2x : %.2x : %.2x : %.2x",
                (TimecodeSample.timecode.dwFrames & 0xFF000000) >> 24,
                (TimecodeSample.timecode.dwFrames & 0x00FF0000) >> 16,
                (TimecodeSample.timecode.dwFrames & 0x0000FF00) >> 8,
                (TimecodeSample.timecode.dwFrames & 0x000000FF));
        DisplayTimecode(szBuf);
    }

    TimecodeSample.dwFlags = ED_DEVCAP_ATN_READ;
    if (hr = MyDevCap.pTimecode->GetTimecode(&TimecodeSample), SUCCEEDED(hr))
    {
        wsprintf(szBuf, "%d", TimecodeSample.timecode.dwFrames);
        DisplayTrackNum(szBuf);
    }
}

デバイスの制御

デバイスを制御するには、IAMExtTransport::put_Mode メソッドを呼び出し、前のセクションで示した定数の 1 つを使って新しい状態を指定する。たとえば、デバイスを停止するには、以下のコードを使用する。

MyDevCap.pTransport->put_Mode(ED_MODE_STOP);

ただし、カムコーダは物理デバイスなので、コマンドを発行してからそれが完了するまでにある程度時間がかかる。そのため、アプリケーションはコマンドの完了を待つ二次スレッドを作成しておく必要がある。コマンドが完了すると、そのスレッドがユーザー インターフェイスを更新できる。状態変化が順番に行われるように、クリティカル セクションを使用する。

カムコーダの中には、デバイスの状態が変化したときにアプリケーションに通知できるものがある。デバイスがこの機能をサポートしている場合、二次スレッドはその通知を待つことができる。サポートしていない場合、アプリケーションはデバイスを定期的にポーリングしなければならない。

通知

最初に、クリティカル セクションの変数、イベント、およびスレッド ハンドルを宣言する。クリティカル セクションは、デバイスの状態を同期するために使用する。イベントは、アプリケーションが終了したときに二次スレッドを終了させるために使用する。

CRITICAL_SECTION csIssueCmd;
HANDLE           hThreadEndEvent = CreateEvent(NULL, TRUE, FALSE, NULL);
HANDLE           hThread = 0;

キャプチャ フィルタのインスタンスを生成した後、二次スレッドを作成する。

DWORD ThreadId;
hThread = CreateThread(NULL, 0, ThreadProc, 0, 0, &ThreadId);

二次スレッドの中で、IAMExtTransport::GetStatus メソッドを 2 回呼び出す。最初の呼び出しでは、値 ED_NOTIFY_HEVENT_GET を渡し、処理の完了時に通知済状態になるイベントのハンドルを取得する。

HANDLE hEvent = NULL;
hr = MyDevCap.pTransport->GetStatus(ED_NOTIFY_HEVENT_GET, (long *)&hEvent);

2 回目の呼び出しでは、デバイスの状態を受け取る変数へのポインタと共に、値 ED_MODE_CHANGE_NOTIFY を渡す。

LONG State;
hr = MyDevCap.pTransport->GetStatus(ED_MODE_CHANGE_NOTIFY, &State);

デバイスが通知をサポートしている場合、この呼び出しの戻り値は E_PENDING である。次に、イベントが通知済状態になるのを待つ。次の処理が完了すると、イベントが通知済状態になり、State の値でデバイスの新しい状態が指定される。ここで、新しい状態を反映するようにユーザー インターフェイスを更新できる。

以下のコードに、完全なスレッドの処理を示す。ユーザー インターフェイスを更新する UpdateTransportState 関数は、アプリケーションで定義されているものとする。スレッドは 2 つのイベントを待つことに注意してほしい。通知イベント (hEvent) と、スレッド終了イベント (hThreadEndEvent) である。また、デバイス状態の変数を保護するために、クリティカル セクションを使用している部分にも注意すること。

DWORD WINAPI ThreadProc(void *pParam)
{
    HRESULT hr;
    HANDLE  EventHandles[2];
    HANDLE  hEvent = NULL;
    DWORD   WaitStatus;
    LONG    State;

    // 次の処理が完了したときに通知済状態になるイベントを取得する。
    hr = MyDevCap.pTransport->GetStatus(ED_NOTIFY_HEVENT_GET, (long *) &hEvent);

    while (hThread && hEvent && hThreadEndEvent) {
        EnterCriticalSection(&csIssueCmd);
        State = 0;
        hr = MyDevCap.pTransport->GetStatus(ED_MODE_CHANGE_NOTIFY, &State);
        LeaveCriticalSection(&csIssueCmd);

        if(hr == E_PENDING) {             // デバイスは通知をサポートしている。
            EventHandles[0] = hEvent;
            EventHandles[1] = hThreadEndEvent;
            WaitStatus = WaitForMultipleObjects(2, EventHandles, FALSE, INFINITE);
            if(WAIT_OBJECT_0 == WaitStatus) {
                UpdateTransportState(State);
            }
            else {
                break;  // このスレッドを終了する。
            }
        }
        else {
            break;  // このスレッドを終了する (デバイスは通知をサポートしていない)。
        }

    } // while

    // 通知をキャンセルする。
    hr = MyDevCap.pTransport->GetStatus(ED_NOTIFY_HEVENT_RELEASE, (long *) &hEvent);
    return 1;
}

以下のように、デバイスにコマンドを発行するときにもクリティカル セクションを使用する。

// "停止" コマンドを発行する。
EnterCriticalSection(&csIssueCmd);
    if(hr = MyDevCap.pTransport->put_Mode(ED_MODE_STOP), SUCCEEDED(hr))
        UpdateTransportState(ED_MODE_STOP);
LeaveCriticalSection(&csIssueCmd);

アプリケーションが終了する前に、二次スレッドを終了させる。

if (hThread)
{
    // このイベントが通知済状態になると、スレッドが終了する。
    if (SetEvent(ThreadEndEvent)) {
        // スレッドが終了するのを待つ。
        WaitForSingleObjectEx(hThread, INFINITE, FALSE);
}
CloseHandle(hThreadEndEvent);
CloseHandle(hThread);

デバイスのポーリング

デバイスが通知をサポートしていない場合、値 ED_MODE_CHANGE_NOTIFY で IAMExtTransport::GetStatus を呼び出すと、E_PENDING 以外の値が返される。その場合は、デバイスをポーリングして状態を判定しなければならない。

ここでも、前に説明したように二次スレッドとクリティカル セクションを使用するべきである。このスレッドは、一定間隔でデバイスに状態を問い合わせる。以下の例に、スレッドの実装法の 1 つを示す。

DWORD WINAPI ThreadProc(void *pParam)
{
    HRESULT hr;
    LONG State;
    DWORD WaitStatus;

    while (hThread && hThreadEndEvent)
    {
        EnterCriticalSection(&csIssueCmd);
        State = 0;
        hr = MyDevCap.pTransport->get_Mode(&State);
        LeaveCriticalSection(&csIssueCmd);
        UpdateTransportState(State);

        // しばらくの間、またはスレッドが終了するまで待つ。
        WaitStatus = WaitForSingleObjectEx(hThreadEndEvent, 200, FALSE);
        if (WaitStatus == WAIT_OBJECT_0)
            break; // ここでスレッドを終了する。
                   // そうしなければ、待機はタイムアウトになる。もう一度、ポーリングを行う。
    }
    return 1;
}

送信

デバイス コントロール インターフェイスを使って、DV テープからコンピュータ ファイルへ送信したり、ファイルからテープへ送信したりする。

  • テープからファイルへ: テープからファイルへ送信するには、生のビデオをキャプチャする場合のようにキャプチャ グラフを作成する。キャプチャ グラフの作成方法については、「キャプチャ アプリケーションの書き方」を参照すること。フィルタ グラフを実行してから、テープを再生する。送信を停止するには、テープとフィルタ グラフを停止する。
  • ファイルからテープへ: ファイルからテープへ送信するには、Async ファイル ソース フィルタをデバイス フィルタに接続する。デバイスを録画ポーズ モードにしてから、フィルタ グラフをポーズする。ポーズ中、フィルタ グラフはビデオの最初のフレームを繰り返す連続ストリームを送る。送信を開始するには、デバイスを録画モードにしてから、フィルタ グラフを実行する。デバイスは、録画ヘッドが録画可能になるまでにある程度時間がかかるため、グラフを実行する前に 2 秒ほど待つ。こうすると、テープの開始部でいくつかのフレームが重複するが、データが失われることがなくなる。

次の図は、ファイルからテープへ送信する場合のフィルタ グラフを示す。

補足資料

『Digital Video Camcorder Support in Windows 98 and Windows 2000』 (www.microsoft.com/hwdev/vidcap/DVCam.htm) は、DV カムコーダの制御を解説したホワイト ペーパーである。


WDM ビデオ キャプチャについて

ここでは、Microsoft® Windows® ドライバ モデル (WDM) および Microsoft® DirectShow® を使用したビデオ キャプチャの概要を示す。WDM ビデオ キャプチャと DirectShow の密接な関連性について説明する。

また、ストリーム クラスと WDM 接続およびストリーミング アーキテクチャ (CSA) の密接な関連性、ビデオ キャプチャ ミニドライバ (ストリーム クラス ドライバのクライアント) について簡単に説明する。ただし、ここで説明する内容を理解するには、これらのトピックに関する基礎知識が必要である。背景情報については、http://www.microsoft.com/hwdev/desinit/ を参照すること。

ここでは次の内容について説明する。

  • Windows ビデオ キャプチャの簡単な歴史
  • WDM の概要
  • WDM ビデオ キャプチャ アーキテクチャ
  • フィルタ グラフの構成
  • WDM のキャプチャ インターフェイスとフィルタ

Windows ビデオ キャプチャの簡単な歴史

マイクロソフトは 1992 年に Windows 3.1 用の Video for Windows 1.x をリリースし、ディスクへの動画のキャプチャ用に最適化した。以降、PCI バス、バス マスタリング コントローラ、NT ストライプ セット、Fast/Wide SCSI を採用したことと、キャプチャしたビデオをアダプタ メモリからディスクに直接転送し、データ コピーを使わないようにしたことで、ビデオ キャプチャ レートは大幅に向上した。Video for Windows は現在キャプチャ レートが 20 MB/秒を超え、クライアント数も多いが、ビデオ会議の出現によって Video for Windows アーキテクチャの弱点が明らかになったことから、新しいビデオ キャプチャ技術を開発する必要が生じた。

Video for Windows アーキテクチャには、ビデオ会議、テレビ視聴、ビデオ フィールドのキャプチャや、垂直同期間隔 (VBI) などのその他のデータ ストリーム用の重要な機能が欠けている。このような制限への対応策として、ベンダー各社は製品固有の独自の拡張機能を実装して Video for Windows を拡張してきた。しかし、標準インターフェイスが存在しないため、拡張機能を利用するアプリケーションはハードウェアに依存したコードを含まざるを得ない。Video for Windows のキャプチャ ドライバとディスプレイ ドライバは密接に結合している。これは、キャプチャ ドライバを変更した場合はディスプレイ ドライバも変更しなければならないことを意味する。

さらに、Video for Windows のインターフェイスである AVICap と DirectShow の組み合わせは効率的に動作しない。理由は、AVICap がバッファを割り当てるからである。AVICap を通して DirectShow にアクセスすると、移行遷移の時点でバッファをコピーする必要があり、非常に効率が悪い。DVD、MPEG デコーダ、ビデオ デコーダおよびチューナー、ビデオ ポート エクステンション (VPE) およびオーディオ CODEC が単一のアダプタに統合されたことによって、これらすべてのデバイスをサポートし、リソースの競合を処理する統一ドライバ モデルが求められていた。

WDM の概要

WDM ビデオ キャプチャは、Video for Windows アーキテクチャに固有の問題を解決するために開発された。WDM ビデオ キャプチャの主な利点は次のとおりである。

  • 32 ビット ドライバ
  • DirectShow と CSA の協調
  • ビデオ キャプチャ デバイスと DVD/MPEG デバイスの間で共有される、ハードウェア (ビデオ ポートやチップ セットなど) 用の単一クラス ドライバ アーキテクチャ
  • テレビ チューナーと入力選択、およびフィールド、VBI、ビデオ ポート エクステンション (VPE) のサポート
  • Windows 98、Windows NT® 4.x、および Windows 2000 プラットフォームで動作する 1 種類のドライバ

Video for Windows アプリケーションには大規模なインストール ベースがあるため、主に動画のキャプチャに使用するデバイスでは Video for Windows ドライバが引き続き使用される。現在、このようなデバイスに対するオペレーティング システム サポートを提供する Video for Windows Version 1.1e が、Windows 98 に付属している。ただし、主に TV の視聴とビデオ会議に使用するキャプチャ デバイスに対しては、WDM ビデオ キャプチャ アーキテクチャによって最適なサポートが提供される。

DirectShow は、Video for Windows アプリケーションに対する下位互換性を備えており、しかも Video for Windows の不備を解決する。WDM ビデオ キャプチャの目的は、USB 会議カメラ、1394 DV デバイス、デスクトップ カメラ、TV 視聴、複数ビデオ ストリーム、および VPE キャプチャに対する追加サポートを提供することである。このサポートはカーネルベースのストリーミングによって提供される。

WDM ベースのストリーミングでは、カーネル接続を提供して DirectShow の非カーネル ストリーミングを拡張している。ストリーミング サービスは、WDM ストリーム クラス ドライバおよびほかのプロセス間システム ソフトウェア コンポーネントによって処理される。WDM ストリーム クラス ドライバは、ミニドライバの呼び出しも行う。ミニドライバは、デバイス固有のコントロールをサポートするために独立系ハードウェア ベンダー (IHV) によって提供されるハードウェア固有のダイナミック リンク ライブラリ (DLL) である。ミニドライバとマイクロソフト提供の WDM ストリーム クラス ドライバは、連携して動作し、遅延時間が最も少ないストリーミングを実行するために必要な低レベルのサービスを提供する。DirectShow は、アプリケーションに固有の上位レベルの機能を提供する。ストリーム クラスは、標準およびカスタムのデータ型を処理する統一ストリーミング モデルをサポートし、ユーザー モードへの移行が不要なカーネル ドライバ間でのデータ転送をサポートしているため、使用すると高い効率が得られるモードである。

以前の DirectShow フィルタは、圧縮解除やレンダリングなどを実行するとき、必要に応じてカーネルとのデータ転送を行っていた。ところが、そのようにユーザー モードからカーネル モードにデータ ストリームが移行するたびに、移行自体に加えて、パラメータの検証とセキュリティの検証、場合によってはデータのコピーに時間が費やされていた。

カーネル ストリーミングによって、ユーザー モードとカーネル モード間のストリームの移行が減少する。ストリームの一部または全体をカーネル モードで生成し、消費できる。ストリームをカーネル モードで処理する場合、DirectShow のフィルタは、ストリームを送信するためのコントロール メカニズムを公開するだけである。そのため、何度も繰り返されるモード移行によるオーバーヘッドを大幅に削減できる。

カーネル ストリームは、アプリケーションに応じた適切な時点でフィルタ グラフにデータを渡すことができる。次の図は、ユーザー モードへの移行を示している。

ビデオ キャプチャの実行時、ストリーム クラスは、書き込みまたはレンダリングするための圧縮されていないビデオ データをビデオ キャプチャ フィルタに渡す。また、カーネル ストリーミングは複数のストリームをサポートするため、ストリームに含まれるタイムコードやクローズ キャプションなどのほかのタイプのデータを同時に渡すことが可能である。

WDM ビデオ キャプチャ アーキテクチャ

次の図は、WDM キャプチャ アーキテクチャの 3 つの基本コンポーネントを示している。

WDM キャプチャ アーキテクチャ

WDM キャプチャ アーキテクチャは DirectShow とスムーズに統合できるように設計されているため、WDM キャプチャ フィルタを使用して DirectShow で簡単にキャプチャ グラフを構築できる。WDM キャプチャ フィルタは DirectShow からストリーミング クラスに制御メッセージを送信する。Windows 98 デバイス ドライバ キット (DDK) に含まれる Ksproxy.ax、Kstune.ax、および Ksxbar.ax フィルタを使用すると、ユニバーサル シリアル バス (USB) 会議カメラ、1394 DV デバイス、TV 視聴、デスクトップ カメラのデータなどの WDM ストリーミング データをストリーム クラスによって制御し、DirectShow キャプチャ グラフに送信することができる。次の図は、これらのコンポーネントがどのように基本アーキテクチャに統合されているかを示している。

WDM キャプチャ アーキテクチャのコンポーネント

この図では、Ksproxy.ax、Kstune.ax、Ksxbar.ax、およびその他の DirectShow フィルタが、ストリーム クラスと直接通信する。Microsoft WDM ストリーム クラスは、CSA への参加を通して、カーネル モード コンポーネント間またはカーネル モード ドライバとユーザー モード コンポーネント間で、高い帯域幅でタイム スタンプ付きの遅延時間重視データ ストリームを転送する。CSA を通して、ストリーム クラスと DirectShow の組み合わせは次の点において効率的に動作する。すなわち、メディア タイプを共有すること、類似したストリーミングの状態 (停止、ポーズ、実行) を持つこと、ピンおよび接続に関して同じ概念を共有することである。そのため、ストリーム クラスからフィルタ グラフのフィルタへ、データの移行が簡単に行える。

Ksproxy.ax、Kstune.ax、および Ksxbar.ax フィルタには、それぞれをサポートするミニドライバ (または 3 つすべてをサポートするミニドライバ) が必要である。ビデオ キャプチャ ミニドライバは、ストリーム クラスのクライアントであり、ビデオ イメージと関連データのストリームを生成するハードウェア デバイスを制御する。このミニドライバには次の機能がある。

  • 圧縮および非圧縮ビデオ ストリーム、垂直同期間隔データ、タイムコード、および付加データ ストリームのキャプチャ
  • TV チューナー、ビデオ ルーティング デバイス、TV オーディオ コントロール、ビデオ コンプレッサなど、ビデオ ストリームに関連付けられたデバイスの制御
  • WDM-CSA との互換性

ストリーム クラス ビデオ キャプチャ ドライバは、複数の圧縮および非圧縮ビデオ、タイムコード、クローズ キャプション、未処理の VBI データとデコードした VBI データ、およびカスタム データ フォーマットのストリームを複数同時にサポートできる。ドライバは、ほかのデータ タイプと同時に生成できるデータ タイプごとに新しいストリームを作成する必要がある。ストリーム クラスは各ストリームを独立した WDM-CSA ピンとして公開する。各ストリームを別の WDM-CSA カーネル フィルタに接続するか、ユーザー モードに移行させ、DirectShow ユーザー モード フィルタの出力ピンに送ることができる。各ストリーム (またはピン) は、さまざまなフォーマットをサポートできる。たとえば、単一のピンが RGB16、RGB24、YVU9、および JPEG デジタル ビデオをサポートできる。ミニドライバの詳細については、Windows 98 DDK を参照すること。

フィルタ グラフの構成

DirectShow フィルタと CSA の結び付きによって、DirectShow のフィルタは、カーネル モードのストリーム クラス ドライバからデータを操作する強力で比較的安全な方法となっている。DirectShow は柔軟なため、さまざまなフィルタ構成が可能である。次の図は、ビデオのプレビューとディスクへのキャプチャを同時に行うユーザー モード DirectShow フィルタの構成例を示している。

ユーザー モード DirectShow フィルタの構成

この図では、受信 TV 信号がチューナー フィルタを使用してチューニングされ、クロスバー フィルタを使用してルーティングされる。フィルタ グラフは、ディスクに保存するさまざまなストリームのデータをビデオまたはオーディオ キャプチャ フィルタに渡す。これには、オーディオ ストリーム、ビデオ ストリーム、および SMPTE タイムコードやクローズ キャプション データなど、さまざまなストリームのその他の付加データが含まれる。

WDM のキャプチャ インターフェイスとフィルタ

カーネル ストリーミング フィルタによって公開される WDM キャプチャ インターフェイスは、IAMTVTuner、IAMCrossbar、IAMAnalogVideoDecoder、IAMVideoProcAmp、および IAMCameraControl である。

WDM 用の Windows 98 ビデオ キャプチャ フィルタには、Ksproxy.ax、Kstune.ax、Ksxbar.ax などがある。これらのフィルタの詳細については、Windows 98 DDK を参照すること。


キャプチャ パフォーマンスの向上

キャプチャは、できる限り高速に大量の情報をディスクに保存することが要求されるハードウェア集中型操作である。キャプチャする情報はビデオおよびオーディオ データが一般的である。システムを低速化させるボトルネックの削減は、キャプチャした動画の品質向上のために非常に重要である。

ここでは、キャプチャ アプリケーションを使用するときや、キャプチャ パフォーマンスが最適化されるようにキャプチャ システムをセットアップするときに役立つ、推奨される一般的な操作方法およびヒントと助言を示す。

注 : 必ず使用しているキャプチャ カードのドキュメントを読み、キャプチャ カード固有の情報を確認すること。システムも一定ではないため、ここに示す情報のすべてが使用しているシステム構成に適用するとは限らない。

ここでは次の内容について説明する。

  • キャプチャ ビデオ データのバイト数の計算
  • キャプチャに合わせたハード ディスクの最適化
  • Windows 9x でのディスク設定
  • キャプチャに関係しないマシン活動の削減
  • キャプチャ パフォーマンス向上のためのその他のヒントと助言

キャプチャ ビデオ データのバイト数の計算

キャプチャは、キャプチャ カードからディスクへの大量のデータ転送を伴う。特定のキャプチャのシナリオにおけるデータの量と求められるデータのスループットを理解するために、次の場合を考える。

高さ 320 ピクセル、幅 240 ピクセルの動画をキャプチャ レート 30 フレーム/秒 (fps)、24 ビット カラー フォーマットでキャプチャするとする。動画に音は入っていない。

すべてのイメージ データをキャプチャして画質を維持するためには、圧縮されていないデータを毎秒何バイト転送する必要があるかを、次に示す式を使って決定する。

転送するビデオ データのバイト数 = 高さ (ピクセル単位) x 幅 (ピクセル単位) x レート (fps 単位) x 色数 (バイト単位)

このシナリオの数字をあてはめると、次の結果になる。

転送するビデオ データは 320 x 240 x 30 x 3 = 6912000 バイト

この動画を目的のサイズ、フレーム レート、および色数で 1 秒間キャプチャするには、約 690 万バイトのディスク領域が必要になる。これに 60 秒を掛けると、1 分間の数字が求められる。この場合は毎分のキャプチャに 414,720,000 バイトが必要になる。必要なデータの量を減らすには、この式のいずれかのパラメータの値を小さくする。つまり、サイズの小さいイメージをキャプチャするか、毎秒あたりのフレーム数を減らすか、色数を減らす。ただし、イメージの要求が高いためにシステムの負荷が限界に達し、毎秒あたり可能な最大メガバイト数でキャプチャすることが求められる場合は、システムをできる限り最適化する必要がある。最終的に、再生時の動画の表示に影響するのは、どのようなキャプチャ設定を用いるかということである。

前に示した数字は音のない動画の例である。ビデオと同時にオーディオもキャプチャする場合は、必要なオーディオ データの量を増やす必要がある。たとえば、44 キロヘルツ (kHz)、16 ビットのステレオで録音された CD 品質のオーディオの場合、毎秒約 172 キロバイト (KB) が必要になる。さらに、オーディオ キャプチャは非常に CPU 集中型であり、オーディオ データとビデオ データの同期化 (唇の動きと音を合わせるときなど) は遅延の原因にもなる。

選択した設定に応じた必要なデータ転送量をシステムで満たせないこともあり得る。キャプチャを実行する場合、システムがポーズする、ビデオの動きが一定でなく不安定 (スムーズでない)、一部のフレームが欠落している (ディスクに保存されていない) などの問題が起きることがある。このようなイメージを再生した品質は一般に満足できるものではない。このような問題を避けるために、キャプチャに合わせてシステムを最適化する方法がいくつかある。

ここに示す推奨事項は、キャプチャ パフォーマンスを最適化するという目標の実現に役立つ。同時に、システムはそれぞれ異なるため、あるシステムでパフォーマンスが向上しても別のシステムでは効果がない場合もあるので注意すること。

キャプチャに合わせたハード ディスクの最適化

キャプチャは多量にハードディスクを消費するので、キャプチャに使用するハード ドライブ (データ ドライブまたはデータ ディスクとも呼ばれる) 上のファイルを最適化することは、キャプチャ パフォーマンス最適化の最も重要な作業である。次の一覧は、データ ドライブ最適化の目標と、目標を実現するためのテクニックを示す。ここに示すのは推奨されるテクニックであり、特定のキャプチャ要件に対しては効果的でない場合もある。使用するテクニックは要件と資源に応じて明確に定まる。

  • キャプチャ ファイルがデータ ドライブの連続した (断片化していない) 場所に格納されていること。

    ハード ドライブのヘッドは、連続的なファイルを読み書きする方が、ディスク上の別の不連続な場所をシークせずに済むため効率的である。Microsoft® Windows® のデフラグ (Defrag.exe) のようなツールを使ってデータ ディスクを最適化する。データ ドライブとオペレーティング システム ドライブの両方を最適化する。オペレーティング システム ドライブは、ドライバ (オーディオ ドライバやビデオ ドライバなど) を使用するとき、システム キャッシュに書き込むとき、レジストリに書き込むとき、オーバーレイを使用するときなどに使われる。Windows 9x スキャンディスク ツールを実行し、データ ドライブとオペレーティング システム ドライブの完全性を確認する。

  • 保存するムービー クリップよりも大きいキャプチャ ファイルをあらかじめ割り当てる。

    ファイル領域の割り当ては時間を消費するので、キャプチャの前にファイルを割り当てる必要がある。キャプチャしたデータがキャプチャ ファイルに入りきらない場合、システムはファイルのための追加領域を割り当てなければならず、これもキャプチャ低速化の原因になる。必要に合った十分な大きさのファイルを割り当てることによって、キャプチャ実行中のファイル領域割り当てを避け、低速化を防ぐ。キャプチャしたデータを保存するには元のキャプチャ ファイルと同じ容量が必要なので、キャプチャしたファイルを別ファイルとして保存できるだけの空き領域がハード ディスクになければならない。キャプチャ ファイルも定期的に最適化すること。

  • キャプチャ ファイル用にハード ディスク全体またはディスク上のパーティションを割り当てる。

    Microsoft® Windows NT® 4.x と Windows 2000 にはスキャンディスクやデフラグ ツールが付属していないので、このテクニックが特に役に立つ。ディスク全体またはディスク パーティションをキャプチャ ファイル専用にすると、キャプチャ ファイル領域を整理された連続的な状態に保ちやすい。このようなディスクまたはパーティションは、フォーマットして再度ファイル領域の事前割り当てを行うことや、ディスクまたはパーティションのほかのファイルを気にせずに最適化を実行することができる。専用キャプチャ ドライブをフォーマットするときは、ディスク上の古いデータをそのまま残すクイック フォーマットではなく、完全フォーマットを実行してディスクを初期化する。

    データ ドライブを整理された状態に保つために、キャプチャしたイメージはデータ ドライブまたはデータ パーティションとは別のディレクトリに保存する。ドライブ全体をキャプチャ専用にすることができない場合は、キャプチャ ファイル用の領域を割り当て、ファイルを最適化してから、(Windows 9x の場合) Windows 9x スキャンディスク ツールを実行する。

  • データ ドライブの先頭 (最も外側) にキャプチャ ファイルを置く。

    キャプチャ ファイルをディスク上の唯一のファイルとして割り当てた場合、またはディスクの最初のパーティションの唯一のファイルとして割り当てた場合は、ファイルはディスクの外側から開始する。ハード ディスクの外側の部分へのアクセスは、ディスクの内側の部分へのアクセスよりも高速である。キャプチャ専用にできるハード ドライブがない場合は、ディスク ユーティリティを使ってキャプチャ ファイルをディスクの開始位置に移動できる。

キャプチャ セッションのたびに必要に応じてこれらの目標を再確認し、ディスクが最適なパフォーマンスを実現するように設定されていることを確認すること。毎回キャプチャ セッションの前にデータ ディスクを最適化し、保存したファイルを再生する前に、保存したイメージを含むドライブを最適化する。

Windows 9x でのディスク設定

Windows 9x コントロール パネルの [システム] アイコンには、キャプチャ パフォーマンスを最適化するためにオフにできるオプションがいくつかある。キャプチャのような高い帯域幅の状況では、可能な最大限のデータをドライブに書き込むことと、ソフトウェア最適化またはシステム変更のチェックに時間を消費しないことが重要である。次のオプションをオフにする。

  • CD-ROM ドライブに CD-ROM ディスクが挿入されている場合の自動検出
  • ハード ディスクの先読みによる最適化
  • すべてのドライブの遅延書き込み

Windows 9x でこれらのオプションにアクセスするには、[スタート] メニューをクリックする。[設定] の [コントロール パネル] をクリックし、[システム] アイコンをダブルクリックする。目的のタブをクリックし、次に示すように操作する。

  • [デバイス マネージャ] タブ : [CD-ROM] をクリックし、CD-ROM ドライブをクリックする。[プロパティ] をクリックし、[設定] タブをクリックする。次に [挿入の自動通知] をオフにする。
  • [パフォーマンス] タブ : [ファイル システム] をクリックし、[先読み取りによる最適化] のつまみをドラッグして [なし] にする (デフォルトは [最大])。引き続き [ファイル システムのプロパティ] ダイアログ ボックスで、[トラブルシューティング] タブをクリックし、[すべてのドライブに遅延書き込みを行わない] をオンにする。

新しい設定を有効にするには、マシンを再起動する必要がある。

注 : ほかのアプリケーションのパフォーマンスを最適化するために、キャプチャ セッション完了後は必ずこれらの設定を元の値に戻すこと。

キャプチャに関係しないマシン活動の削減

キャプチャ以外の目的でシステムに割り込む原因または CPU 時間を消費する原因となるものはすべて、キャプチャのパフォーマンスを低下させる可能性がある。次の作業を実行してシステムのパフォーマンスに影響するかどうかを確認する。

  • キャプチャ アプリケーション以外のすべてのアプリケーションを閉じる。
  • Windows 9x のタスクバーに時計を表示しないようにする。そのためには、タスクバーを右クリックし、[プロパティ] をクリックする。次に [タスク バー オプション] の [時計を表示] をオフにする。
  • スクリーン セーバーをオフにする。そのためには、デスクトップを右クリックし、[プロパティ] をクリックする。[スクリーン セーバー] タブをクリックし、[スクリーン セーバー] ボックスの一覧で "(なし)" を選択する。
  • プリンタをオフにする。
  • ネットワーク カードがある場合は無効にする。特にネットワーク上で明示的な操作を実行していなくても、ネットワークを経由したデータの送受信によってシステムに割り込みが発生する可能性がある。

キャプチャ パフォーマンス向上のためのその他のヒントと助言

ここでは、これまでに示したその他の推奨事項を実行した後に試す価値のある、キャプチャのパフォーマンスを向上させるためのさまざまなヒントと助言を示す。推奨事項はハードウェア関連とソフトウェア関連に分けられてる。

ソフトウェア

  • Windows 2000 または Windows NT 4.x でキャプチャを実行することを検討する。 NT ベースのファイル システム (NTFS) はスレッドを使用するため、一般に従来の FAT ファイル システムよりも高速である。Windows NT で動作するドライバを確認する必要がある場合は、使用しているキャプチャ カードの製造元に問い合わせる。一部が NTFS、一部が FAT というドライブではなく、完全な NTFS ドライブを使用する。FAT-32 ファイル システムは一般に FAT ファイル システムよりも高速である。
  • キャプチャ ソフトウェアを使用してさまざまな圧縮率を試し (たとえば 2:1 や 1:1) 、保存しなければならないデータの量を減らす。最初はデフォルトの圧縮率を使い、フレームの欠落が発生するまで圧縮率を上げる。3 とおりの圧縮率を試し、その中で最も効率のよいものを使用する。キャプチャしたイメージを別のドライブに保存した後、標準設定でスキャンディスクを実行し、ドライブをすばやく最適化する。
  • Windows 3.1 をインストールしたコンピュータに Windows 9x を上書きインストールした場合は、Autoexec.bat ファイルに "verify=off" を追加する。この行を追加すると、DOS で書き込み操作後にデータが正しく書き込まれたことを確認するためのデータ再読み取りが行われない。検証は書き込み操作を低速化させる。

ハードウェア

  • PCI スロット 0 にキャプチャ カードを挿入し、システムのその他のカードよりも先にキャプチャ カードが検査されるようにする。
  • データ ドライブに対してハード ドライブ キャッシュがオンになっていることを確認する。詳細については、SCSI カードのドキュメントを参照すること。
  • システム内部に熱がたまると、システム コンポーネントが消耗してキャプチャ パフォーマンスが低下する。一度に数時間連続してキャプチャを実行する場合は、システムの電源、CPU、およびコンポーネント (カード) にそれぞれ 1 つずつ、3 つのファンが付いていることを確認する。キャプチャしたイメージが最初の方では問題なく、しばらくキャプチャを続けた後に不安定になった場合は、キャプチャ カードがオーバーヒートしている可能性がある。
  • 一部のキャプチャ カードにはオーディオ カードが組み込まれている。オンボードのオーディオ カードを使用するか、独立したオーディオ カードを使用するかは、目的によって異なる。独立したオーディオ カードを使用することで必要な機能が得られる場合もあれば、オンボードのオーディオ カードで十分目的が果たせる場合もある。
  • 一部のキャプチャ カードはモニタ用の拡張接続を備えているため、キャプチャしている内容をプレビューするためにソフトウェアを使用する必要がない。 システムにプレビュー ウィンドウを表示する負荷がかからないため、この機能はパフォーマンス向上に役立つ。


キャプチャに関する高度なトピック

このトピックでは、キャプチャ アプリケーションでの Microsoft® DirectShow® 使用にかかわるいくつかの高度な側面について説明する。しかしほとんどのキャプチャ アプリケーションにはこの情報が不要である。このトピックは「キャプチャ アプリケーションの書き方」を読んだうえで参照すること。

大半のキャプチャ アプリケーションでは、ICaptureGraphBuilder2 インターフェイスを使ってキャプチャ グラフを構築できる。ほとんどのキャプチャ シナリオには、このインターフェイスで適切に対応できる。ただし、必要なグラフが極端に複雑な場合は、1 フィルタずつ手動で構築しなければならない。この場合には、ICaptureGraphBuilder2 で自動的に行われる処理を細部まで理解しておく必要がある。また、グラフを手動で構築する場合でも、ICaptureGraphBuilder2 の FindInterface メソッドや FindPin メソッドは利用できる。

このトピックは、以下のセクションで構成される :

  • 再描画イベント
  • ピン カテゴリ
  • スマート ティー フィルタの使い方
  • ビデオ ポート ピン
  • クローズド キャプション
  • VideoInfo2 フォーマット タイプ
  • WDM ストリーム クラス ドライバ フィルタ

再描画イベント

ユーザーがプレビュー ウィンドウに重ねて何かを表示し、それを消去すると、ビデオ レンダラは WM_PAINT メッセージを受け取る。デフォルトでは、ウィンドウを再表示するため、ビデオ レンダラが新しいフレームを要求する。ファイル キャプチャ中にこの状況が発生すると、キャプチャ ファイルが破損して使用できなくなる。したがって、キャプチャ グラフがファイルにデータを書き込む場合には、再描画イベントのデフォルト処理を取り消す必要がある。これには、フィルタ グラフ マネージャに IMediaEvent インターフェイスを照会し、パラメータに EC_REPAINT イベント コードを指定して IMediaEvent::CancelDefaultHandling メソッドを呼び出す。

詳細については、「DirectShow でのイベント通知」を参照すること。

ピン カテゴリ

キャプチャ フィルタには、目的の異なる複数の出力ピンを持たせることができる。たとえば、キャプチャ用とプレビュー用にそれぞれ独立したピンを持つキャプチャ フィルタがある。また、プライマリ ビデオ ストリームとは別に、クローズド キャプション データを渡すキャプチャ フィルタもある。ピンの機能は、カーネル ストリーミング プロパティ セットで識別する。ここでは、以下のピン カテゴリについて説明する。
カテゴリ GUID | 説明
PIN_CATEGORY_CAPTURE | キャプチャ ピン
PIN_CATEGORY_PREVIEW | プレビュー ピン
PIN_CATEGORY_VIDEOPORT | ビデオ ポート (VP) ピン
PIN_CATEGORY_CC | クローズド キャプション ピン
PIN_CATEGORY_VBI | 垂直同期間隔 (VBI) ピン
PIN_CATEGORY_VIDEOPORT_VBI | VBI 用のビデオ ポート ピン

キャプチャ フィルタには、キャプチャ ピンが少なくとも 1 つある。また、プレビュー ピンとビデオ ポート ピンのどちらかが付いていることもある、ただし同時に両方が付くことはない。キャプチャ ピンとプレビュー ピンは、それぞれ異なるメディア タイプを渡すために複数使用できる。このように、1 つのフィルタが、ビデオ用とオーディオ用それぞれのキャプチャ ピンと、ビデオ用とオーディオ用それぞれのプレビュー ピンを持つことがある。クローズド キャプションと VBI は、TV と DVD で使用する。

ピンのカテゴリを判断するには、IKsPropertySet::Get メソッドを呼び出す。このプロパティ セットの GUID は AMPROPSETID_Pin であり、プロパティ識別子は AMPROPERTY_PIN_CATEGORY である。以下のサンプル コードは、ピンの照会方法を示す :

IPin *pPin; // キャプチャ フィルタの出力ピンへのポインタ。
IKsPropertySet *pKs;
HRESULT hr;

hr = pPin->QueryInterface(IID_IKsPropertySet, (void **)&pKs);
if (SUCCEEDED(hr))
{
    GUID PinCategory;
    DWORD cbReturned;
    hr = pKs->Get(AMPROPSETID_Pin, AMPROPERTY_PIN_CATEGORY, NULL, 0,
                        &PinCategory, sizeof(GUID), &cbReturned);
    if (SUCCEEDED(hr))
    {
        // PinCategory にカテゴリ GUID が格納されている。
    }
    pKs->Release();
}

プロパティ セットの詳細については、Microsoft® Windows® Driver Development Kit (DDK) のドキュメントを参照すること。

スマート ティー フィルタの使い方

それぞれ独立したキャプチャ ピンとプレビュー ピンがあるフィルタでは、一方でプレビューしながら、もう一方でキャプチャすることができる。ただし、フィルタにプレビュー ピンがない場合でも、スマート ティー フィルタを使って同じことを実行できる。このフィルタは、キャプチャ ピンからのデータを、キャプチャ用とプレビュー用の同じ 2 つのストリームに分割する。

次の図は、スマート ティー フィルタがあるグラフを示す。

スマート ティー フィルタの使い方

プレビューとキャプチャを 1 つのピンでカバーするため、スマート ティー フィルタは以下の最適化を行う。

  • キャプチャのパフォーマンスに影響しないときにのみ、プレビュー データを渡す。
  • プレビュー ストリームからタイム スタンプを削除する。

2 番目の最適化については少し説明が必要である。グラフ内での遅延時間が原因となり、ライブ データはレンダリング フィルタに少し遅れて届く。プレビュー データにタイム スタンプがあると、遅れを解消するためにレンダラでフレームがドロップされることがあるが、フレームをいくらドロップしてもフレームの遅れは解消されない。タイム スタンプを削除することによって、フレームの不要なドロップを避けることができる。詳細については、「DirectShow のタイムとクロック」を参照すること。

注 : ビデオ ポート ピンは一種のプレビュー ピンとして取り扱うことができるので、VP ピンがあるフィルタにスマート ティー フィルタは必要ない。ただし、VP ピンには特殊な要件がいくつかある。次のセクションでは、これらの要件について説明する。

ビデオ ポート ピン

ハードウェア ビデオ ポートがあるキャプチャ デバイスは、Microsoft® DirectX® のビデオ ポート エクステンション (VPE) を使用できる。この場合、キャプチャ フィルタはビデオ ポート (VP) ピンを持つ。VP ピンはオーバーレイ ミキサー フィルタに接続し、オーバーレイ ミキサーはビデオ レンダリング フィルタに接続する必要がある。

VP ピンからフィルタ グラフを通じてビデオ データが渡されることはない。代わりに、ハードウェア内でビデオ フレームが生成され、ビデオ メモリに直接送られる。VP ピンを使用すると、ハードウェアにコントロール メッセージを送信できる。キャプチャ機能のみに興味がある場合でも、VP ピンは必ず接続すること。なぜなら VP ピンを接続しないと、キャプチャ グラフは動作しない。この点で、未接続でもよいプレビュー ピンとは異なる。VP ピンは必ずオーバーレイ ミキサーの入力ピン 0 に接続すること。

ビデオ レンダリング フィルタは、オーバーレイ ミキサーからビデオ データを取得しない。ただし、ビデオ ウィンドウはビデオ レンダリング フィルタによって制御されるので、フィルタ グラフにはこのフィルタを含める必要がある。フィルタ グラフ マネージャに IVideoWindow インターフェイスを照会すると、ビデオ ウィンドウをアプリケーション ウィンドウの子にすることができる。詳細については、「ビデオ ウィンドウの設定」を参照すること。

次の図は、ビデオ ポート ピンがあるキャプチャ グラフを示す。

ビデオ ポート ピンがあるフィルタ グラフ

次のサンプル コードは、オーバーレイ ミキサーにビデオ ポート ピンを接続するものである。ここでは、キャプチャ フィルタのビデオ ポート ピンとオーバーレイ ミキサーの入力ピン 0 を検索するために、ICaptureGraphBuilder2::FindPin メソッドを使用するが、代わりに IBaseFilter::EnumPins メソッドを使用することもできる。簡略化のため、このコードではエラー チェックが省略されている。

IPin *pPinOut,  // キャプチャ フィルタのビデオ ポート ピン。
     *pPinIn;   // オーバーレイ ミキサーの入力ピン。
IBaseFilter *pOvMix = NULL;

// ビデオ ポート ピンを検索する。
pCGB->FindPin(
    pCaptureFilter,           // キャプチャ フィルタへのポインタ。
    PINDIR_OUTPUT,            // 出力ピンを検索する。
    &PIN_CATEGORY_VIDEOPORT,  // ビデオ ポート ピンを検索する。
    NULL,                     // 任意のメディア タイプ。
    TRUE,                     // ピンは非接続でなければならない。
    0,                        // 一致する最初のピンを取得する。
    &pPinOut                  // ピンへのポインタのアドレス。
);

// オーバーレイ ミキサーを作成する。
CoCreateInstance(CLSID_OverlayMixer, NULL, CLSCTX_INPROC,
        IID_IBaseFilter, (void **)&pOvMix);

// それをフィルタ グラフに追加する。
pGraph->AddFilter(pOvMix, L"Overlay Mixer");

// オーバーレイ ミキサーの入力ピン 0 を取得する。
pCGB->FindPin(pOvMix, PINDIR_INPUT, NULL, NULL, TRUE, 0, &pPinIn);

// 2 つのピンを接続する。
pGraph->Connect(pPinOut, pPinIn);

オーバーレイ ミキサーをビデオ レンダラに接続するには、このようなコードを使用するか、またはオーバーレイ ミキサーの出力ピンを指定して IGraphBuilder::Render を呼び出す。

クローズド キャプション

クローズド キャプション ピンには、いくつかの種類がある。

  • クローズド キャプション ピン (PIN_CATEGORY_CC)
  • VBI ピン (PIN_CATEGORY_VBI)
  • VBI ビデオ ポート ピン (PIN_CATEGORY_VIDEOPORT_VBI)

接続の要件は、ピンの種類によって異なる。

クローズド キャプション ピン : プレビューでは、このピンをLine 21 デコーダ フィルタに接続し、そのフィルタをオーバーレイ ミキサーのピン 1 に接続する (ピン 0 はプライマリ ビデオ ストリーム用に予約されている)。IGraphBuilder::Connect を呼び出すと、フィルタ グラフ マネージャによって自動的にLine 21 デコーダが追加される。ファイル キャプチャでは、オーバーレイ ミキサーではなく、Mux フィルタに接続する。

VBI ピン : このピンは、Tee/Sink-to-Sink コンバータ フィルタ (VBI インフィニット ティーとも呼ぶ) に接続する。このフィルタによって VBI データが複数のストリームに分割される。このフィルタを CC デコーダ フィルタに接続する。プレビューでは、前に説明したように CC デコーダ フィルタをオーバーレイ ミキサーに接続する。ファイル キャプチャでは、Mux フィルタに接続する。

VBI ビデオ ポート ピン : このピンは VBI サーフェス アロケータ フィルタ (CLSID_VBISurfaces) に接続する。このフィルタは、VBI データ用の Microsoft® DirectDraw® サーフェスを処理する。フィルタに VBI ピンと VBI ビデオ ポート ピンの両方がある場合は、その両方を接続する。

プレビューでは、キャプチャ フィルタのプレビュー ピンを、オーバーレイ ミキサーのピン 0 に接続する。これは、PIN_CATEGORY_VIDEOPORT ピンだけでなく、PIN_CATEGORY_PREVIEW ピンにも適用される。オーバーレイ ミキサーによって、クローズド キャプションがプライマリ ビデオにオーバーレイされる。

次の図は、VBI ピンと VBI ビデオ ポート ピンがあるプレビュー グラフを示す。

クローズド キャプションがあるフィルタ グラフ

Tee/Sink-to-Sink コンバータ フィルタと CC デコーダ フィルタは、実際は KSProxy フィルタにラップされた WDM ミニドライバである。したがって、CoCreateInstance の呼び出しではこれらのフィルタを作成できない。代わりに、システム デバイス 列挙子を使って各フィルタのデバイス カテゴリを列挙する。

フィルタ | カテゴリ
Tee/Sink-to-Sink コンバータ | AM_KSCATEGORY_SPLITTER (WDM ストリーミング ティー/スプリッタ)
CC デコーダ | AM_KSCATEGORY_VBICODEC (WDM ストリーミング VBI CODEC)

カテゴリに含まれるそれぞれのフィルタのフレンドリ名をテストして、一致する文字列を見つける。次に、IMoniker::BindToObject を呼び出してフィルタのインスタンスを作成する。

次のサンプル コードは、Tee/Sink-to-Sink コンバータ フィルタを作成する。簡略化のため、エラー チェックは省略されている。

IBaseFilter *pFilter = NULL; // フィルタのインスタンスを受け取るポインタ。

// システム デバイス列挙子を作成する。
ICreateDevEnum *pDevEnum;
CoCreateInstance(CLSID_SystemDeviceEnum, NULL, CLSCTX_INPROC,
    IID_ICreateDevEnum, (void**)&pDevEnum);

// ティー/スプリッタ カテゴリを列挙するクラス列挙子を作成する。
IEnumMoniker *pEnum;
pDevEnum->CreateClassEnumerator(AM_KSCATEGORY_SPLITTER, &pEnum, 0);

// このカテゴリに含まれるデバイスを列挙する。
IMoniker *pMoniker;
ULONG cFetched;
while(pEnum->Next(1, &pMoniker, &cFetched) == S_OK)
{
    IPropertyBag *pBag;
    pMoniker->BindToStorage(0, 0, IID_IPropertyBag, (void **)&pBag);

    // フレンドリ名を確認する。
    VARIANT var;
    var.vt = VT_BSTR;
    pBag->Read(L"FriendlyName", &var, NULL);
    if (lstrcmpiW(var.bstrVal, L"Tee/Sink-to-Sink Converter") == 0)
    {
        // 正しいフィルタが見つかった。
        pMoniker->BindToObject(0, 0, IID_IBaseFilter, (void**)&pFilter);
        SysFreeString(var.bstrVal);
        pBag->Release();
        pMoniker->Release();
        break;
    }
    SysFreeString(var.bstrVal);
    pBag->Release();
    pMoniker->Release();
}
pEnum->Release();
pDevEnum->Release();

VideoInfo2 フォーマット タイプ

プレビュー ピンには、VIDEOINFOHEADER2 フォーマットのメディア タイプが適している場合がある。このフォーマットは、正方形以外のピクセルやインターレース ビデオ (フレーム ベースではなくフィールド ベースのビデオ) などの特殊な機能をサポートする。オーバーレイ ミキサー フィルタでは、このフォーマットがサポートされる。

これらの機能を利用するには、以下を実行する。

  1. IPin::EnumMediaTypes メソッドを使ってピンの優先メディア タイプを列挙する。
  2. 最初に列挙されるメディア タイプを確認する。
  3. formattype の GUID が FORMAT_VideoInfo2 なら、ピンをオーバーレイ ミキサーに接続する。次に、オーバーレイ ミキサーをビデオ レンダラに接続する (「ビデオ ポート ピン」参照)。

これらの機能に興味がなければ、オーバーレイ ミキサーを使用する必要はない。

WDM ストリーム クラス ドライバ フィルタ

キャプチャ デバイスで WDM (Windows Driver Model) ドライバを使用する場合には、グラフ内のキャプチャ フィルタのアップストリームに一定のフィルタが必要になることがある。これらのフィルタは、"ストリーム クラス ドライバ" フィルタまたは WDM フィルタと呼ばれる。これらのフィルタでは、ハードウェアが提供する追加機能がサポートされる。たとえば、TV チューナー カードにはチャンネルを設定するための機能がある。これに対応するフィルタは、IAMTVTuner インターフェイスを公開する TV チューナー フィルタである。アプリケーションからこの機能を利用できるようにするには、キャプチャ フィルタに TV チューナー フィルタを接続する必要がある。

ICaptureGraphBuilder2 インターフェイスは、グラフに WDM フィルタを追加するための最も簡単な手段である。グラフ構築のどこかで FindInterface または RenderStream を呼び出す。これらのメソッドは、どちらも必要な WDM フィルタを自動的に見つけてキャプチャ グラフに接続する。WDM フィルタを手動で追加する方法は、このセクションの後半で説明する。ただし、可能であれば、手動ではなく ICaptureGraphBuilder2 のメソッドを呼び出すこと。

WDM フィルタのピンは、1 つ以上の "メディア" をサポートする。メディアとは、通信の手段 (バスなど) を定義するものである。接続するピンでは、同じメディアがサポートされている必要がある。DirectShow では、REGPINMEDIUM 構造体でメディアが定義される。REGPINMEDIUM 構造体は、カーネル ストリーミング ドライバに使用される KSPIN_MEDIUM 構造体と同等である。ピンのメディアを取得するには、IKsPin::KsQueryMediums メソッドを呼び出す。このメソッドは、KSMULTIPLE_ITEM 構造体と 0 個以上の REGPINMEDIUM 構造体が連続して格納されたメモリ ブロックへのポインタを返す。REGPINMEDIUM 構造体の clsMedium メンバは、メディアのクラス識別子 (CLSID) を指定するものである。

次のヘルパー関数は、ピンのメディアを取得する。

// 呼び出し元で pMedium を割り当てる。
HRESULT GetMedium(IPin *pPin, REGPINMEDIUM *pMedium)
{
    IKsPin *pKsPin = NULL;
    PKSMULTIPLE_ITEM pmi;

    HRESULT hr = pPin->QueryInterface(IID_IKsPin, (void **)&pKsPin);
    if (FAILED(hr))
        return hr;  // ピンが IKsPin をサポートしていない。

    hr = pKsPin->KsQueryMediums(&pmi);
    pKsPin->Release();
    if (FAILED(hr))
        return hr;  // ピンがメディアをサポートしていない。

    if (pmi->Count == 0) {
        CoTaskMemFree(pmi);
        return E_FAIL;  // メディア数が 0。
    }
    else {
        // ポインタ演算を使ってメディア構造体を参照する。
        REGPINMEDIUM *pTemp = (REGPINMEDIUM*)(pmi + 1);
        memcpy(pMedium, pTemp, sizeof(REGPINMEDIUM));
        CoTaskMemFree(pmi);
        return S_OK;
    }
}

メディアの CLSID が GUID_NULL または KSMEDIUMSETID_Standard の場合には、ピンを接続しないこと。これらの CLSID は、ピンがメディアをサポートしていないことを示すデフォルト値である。

また、フィルタにそのピンが接続されたインスタンスが 1 つだけ必要な場合にのみ、ピンを接続すること。そうしないと、接続すべきではない各種のピンをアプリケーションが接続しようとし、その結果、プログラムが応答しなくなる危険性がある。必要なインスタンスの数を調べるには、次のサンプル コードのように KSPROPERTY_PIN_NECESSARYINSTANCES プロパティ セットを取得する。簡略化のため、このコードではリターン コードのテストとインターフェイスの解放が省略されているが、アプリケーションではこれらを両方とも実行しなければならない。

// ピン ファクトリ識別子を取得する。
IKsPinFactory *pPinFactory;
hr = pPin->QueryInterface(IID_IKsPinFactory, (void **)&pPinFactory);

ULONG ulFactoryId;
hr = pPinFactory->KsPinFactory(&ulFactoryId);

// フィルタから "インスタンス" プロパティを取得する。
IKsControl *pKsControl;
hr = pFilter->QueryInterface(IID_IKsControl, (void **)&pKsControl);

KSP_PIN ksPin;
ksPin.Property.Set = KSPROPSETID_Pin;
ksPin.Property.Id = KSPROPERTY_PIN_NECESSARYINSTANCES;
ksPin.Property.Flags = KSPROPERTY_TYPE_GET;
ksPin.PinId = ulFactoryId;
ksPin.Reserved = 0;

KSPROPERTY ksProp;
ULONG ulInstances, bytes;
pKsControl->KsProperty((PKSPROPERTY)&ksPin, sizeof(ksPin),
    &ulInstances, sizeof(ULONG), &bytes);

if (hr == S_OK && bytes == sizeof(ULONG))
{
    if (ulInstances == 1)
    {
        // フィルタにはこのピンのインスタンスが 1 つ必要。
        // このピンは OK。
    }
}

次の擬似コードは、WDM フィルタを検索および接続する方法について、非常に簡単な概要のみを示したものである。このコードでは、細かい処理をすべて省略し、アプリケーションで実行すべき一般的なステップだけを示す。

サポートされるフィルタを追加する :
{
    foreach 入力ピン :
        skip if (ピンが接続されている)

        ピン メディアを取得する
        skip if (メディアが GUID_NULL または KSMEDIUMSETID_Standard)

        フィルタに KSPROPERTY_PIN_NECESSARYINSTANCES プロパティを照会する
        skip if (必要なインスタンス数 != 1)

        既存のピンと比較する || 一致するフィルタを検索する
}

既存のピンと比較する :
{
    foreach グラフ内のフィルタ
        接続されていない foreach ピン
            ピン メディアを取得する
            if (メディアが一致する)
                そのピンを接続する
}

一致するフィルタを検索する :
{
    フィルタ グラフ マネージャに IFilterMapper2 を照会する。
    メディアが一致する出力ピンを持つフィルタを検索する。
    フィルタをグラフに追加する。
    ピンを接続する。
    サポートされるフィルタを追加する (再帰呼び出し)。
}


DirectShow 編集サービス

Microsoft® DirectShow® 編集サービス (DES) は、ビデオ編集をサポートするアプリケーション プログラミング インターフェイス (API) である。このセクションでは、DES の使い方を説明している。以下のトピックが含まれる。

  • DirectShow 編集サービスの紹介
  • DirectShow 編集サービスの基礎知識
  • DirectShow 編集サービスの使い方
  • DirectShow 編集サービス リファレンス


DirectShow 編集サービスの紹介

Microsoft® DirectShow® 編集サービス (DES) は、ビデオ編集に含まれるタスクを大幅に簡略化するアプリケーション プログラミング インターフェイス (API) である。DES は、コア DirectShow アーキテクチャの最上部に構築されている。DES は、DirectShow の多くを抽象化し、ビデオ編集プロジェクトの操作専用に設計されたインターフェイスのセットを提供する。アプリケーション開発者は、ビデオ編集アプリケーションの作成に最適なフレームワークの中で DirectShow の利点を活用できる。

DirectShow 自体は、ストリーム メディアを処理するための強力なアーキテクチャである。DirectShow によって、開発者がファイル圧縮などの面倒な問題を考慮しなくても、アプリケーションで多様なフォーマットのマルチメディア コンテンツを再生することができる。しかし、DES がなければ、DirectShow は非線型編集に必要な柔軟性を備えていなかった。

たとえば、あるビデオ シーケンスを作成するのに、ソース A から 4 秒、次にソース B から 10 秒、最後にソース C から 5 秒を繋ぎたいとする。これは、DirectShow API だけを使って、かなり容易に行うことができる。

しかし、ソース C を ソース B の後ではなく前に持ってきたい場合や、ソース A から 4 秒ではなく 8 秒使いたい場合、またプロダクション全体でバックグラウンドに別のオーディオ トラック再生が必要になった場合には、どうであろうか。このような小さな変更を実装することが難しいことがある。しかし、このような作業は DES ではごく簡単な編集プロジェクトであり、メソッドをいくつか呼び出すだけで行うことができる。

DES が DirectShow にもたらす主な機能を以下に示す。

  • ビデオおよびオーディオ トラックを入れ子構造のレイヤに構成し、最終プロダクションの操作を容易にするタイムライン モデル
  • その場でビデオ プロジェクトをプレビューする機能
  • XML ベースのフォーマットによるプロジェクトの持続性
  • ビデオ エフェクトとオーディオ エフェクト、およびビデオ トラック間のトランジション (フェードやワイプなど)
  • Society of Motion Picture and Television Engineers (SMPTE) によって定義されている約 100 種類の標準ワイプ
  • 色相、輝度、RGB 値、またはアルファ値に基づくキーイング
  • プロダクションで異種ソースの使用を可能にする、フレーム レートとオーディオ サンプリング レートの自動変換
  • ビデオのサイズ変更とクロッピング

DES の実際の動作を見る最も早い方法は、サンプル アプリケーションの XTLTest サンプルを実行することである。このユーティリティは、XML で記述された DES プロジェクト ファイルを解析し、画面にレンダリングする。サンプル プロジェクト ファイルを手動で編集してレンダリングし、その変化を見ることにより、XtlTest を試すことができる。


DirectShow 編集サービスの基礎知識

このセクションでは、DirectShow® 編集サービス (DES) を使い始めるために必要な基本概念を説明する。

  • DirectShow 編集サービスの基本概念
  • タイムライン モデル
  • DirectShow 編集サービスにおける時間


DirectShow 編集サービスの基本概念

ここには、以下のトピックが含まれる。

  • アーキテクチャ
  • DES および DirectShow コア API
  • 代表的なアプリケーションの構造

アーキテクチャ

次の図は、Microsoft® DirectShow® 編集サービス (DES) のアーキテクチャを示している。

  • タイムライン : ビデオ プロダクションを、入れ子構造のトラックのセットに構成される、ソース クリップ、トランジション、およびエフェクトのコレクションとして表現する。詳細については、「タイムライン モデル」を参照すること。
  • XML パーサ : タイムラインを解析して出力ファイルを生成する。または、入力ファイルを読み込んでタイムラインを生成する。DES は、XML ベースの永続性フォーマットをサポートしている。
  • レンダリング エンジン : タイムラインを、ストリーム メディアとしてレンダリングできるフォーマットに変換する。デフォルトでは、レンダリング エンジンは DirectShow フィルタ グラフを生成する (次のセクションを参照すること)。
  • メディア ロケータ : メディア要素の位置のキャッシュを保守する。メディア要素を開こうとして失敗した場合、DES はこのキャッシュを使用し、成功したオープンのヒストリに基づいて要素を検索する。

DES および DirectShow コア API

DirectShow は、フィルタと呼ばれるモジュラー コンポーネントを通してマルチメディア データのストリームを制御する。フィルタは、メディア ストリームを入力とし、それに対して何らかの処理を行い、結果を出力として渡すコンポーネントである。フィルタは、複数のストリームを結合すること、および 1 つのストリームを複数の出力ストリームへ分割することもできる。フィルタ グラフは、チェイニングされたフィルタのコレクションである。ソース フィルタは、ソース ファイルからメディア データを取り込み、それをフィルタ グラフに導入する。レンダリング フィルタは、ストリームを、ビデオやオーディオなどの最終出力のタイプとしてレンダリングする。メディア ストリームは、ソース フィルタから、通常は他のフィルタを経由してレンダリング フィルタに流れる。

DES におけるタイムラインは、ビデオ編集プロジェクトの抽象表現である。これは、プロジェクトで使用されるソース クリップ、その開始タイムと終了タイム、エフェクトとトランジションの配置などを指定する。ただし、タイムライン自体は、表現されるビデオおよびオーディオをレンダリングすることはできない。それは、レンダリング エンジンの機能である。レンダリング エンジンは、タイムラインをフィルタ グラフに変換する。フィルタ グラフを実行すると、プロジェクトがプレビューとして画面に直接レンダリングされるか、ファイルへの出力としてレンダリングされる。アプリケーションでは、扱いにくくエラーの出やすいフィルタ グラフを直接操作するのではなく、タイムラインを操作する。

代表的なアプリケーションの構造

下の表は、一般的なビデオ編集アプリケーションで行われる主要なタスクと、各タスクをサポートする DES インターフェイスの一覧である。以降のセクションで、これらのタスクとインターフェイスについて詳しく説明する。

タスク | インターフェイス
タイムラインの構築または変更 | IAMTimeline および他の IAMTimelineXXXX インターフェイス
プロジェクト ファイルの保存とロード | IXml2Dex
プロジェクトのプレビューまたはファイルへの書き込み | IRenderEngine、ISmartRenderEngine

この主要タスクのほかに、アプリケーションでは以下の 2 次的なタスクのいくつかまたは全部を行う場合がある。

タスク | インターフェイス
メディア ファイルに関する情報の取得 (ストリームの数、各ストリームのフォーマットと時間幅) | IMediaDet
トランジションとエフェクトのプロパティの設定 | IPropertySetter
レンダリング中にエラーが発生した場合の通知の受信 | IAMSetErrorLog、IAMErrorLog
ポスター フレームの抽出 | IMediaDet、ISampleGrabber


タイムライン モデル

タイムラインは、Microsof® DirectShow® 編集サービス (DES) がビデオ編集プロジェクトを表現するために使用するオブジェクトである。ここでは、タイムラインの概念について説明し、タイムラインが持っている各種オブジェクトについて解説している。

ここには以下のセクションが含まれる。

  • タイムラインの構造
  • タイムラインがレンダリングされる方法
  • トランジション
  • 合成と重なり
  • エフェクト

タイムラインの構造

ビデオ制作は、ビデオ クリップ、サウンド ファイル、スティル イメージなどの未加工のソース ファイルのコレクションから開始される。制作者やビデオ編集者は、1 つのクリップから 10 秒、別のクリップから 5 秒、さらに別のクリップから 30 秒といったように、ファイルの一部分を取り出す。次に、特定のシーケンスでそれらを配置する。

最も単純な場合、クリップは厳密に線形の順序で表示され、各クリップの後に次のクリップが続く。この基礎的な配置は、トラックとなる。したがって、単純な制作では、1 つのビデオ トラックとオーディオ トラックだけが含まれる。より複雑な制作では、いくつかのオーディオ トラックがミキシングされるなど、複数のトラックが使用される。また、トラックにはオーディオ効果が含まれ、1 つのトラックがフェード アウトするときに、別のトラックがフェード インする。ビデオの場合は、1 つのトラックはフェードやワイプを使って次のトラックにトランジションする。これが、合成の例である。ほかの例には、1 つのトラックの背景がキー アウトされ、別のトラックによって置き換わるクロマ キー処理がある。クロマ キー処理の例には、衛星写真の前面に配置された天気予報のキャスターがある。

このように、ビデオ制作には時間 (あるクリップに別のクリップが続く) と、レイヤ (あるクリップが別のクリップに重なる) で配置されたソース クリップが含まれる。DES では、ツリー構造を使ってこの配置を示す。

  • リーフ ノードは、メディア ファイルからの個々のストリーム (オーディオまたはビデオ) である。各ノードはソースである。
  • 同一のメディア タイプ (オーディオまたはビデオ) のソースのコレクションがトラックである。
  • トラックのコレクションが合成である。合成は、含まれるすべてのトラックの合成としてレンダリングされる。前の例を使えば、天気予報のキャスターと衛星写真は、同じ合成内の別々のトラックに存在している。合成には他の合成を入れることもでき、トラックの複雑な配置が可能である。
  • (同じメディア タイプを表す) 合成とトラックの最上位レベルのコレクションがグループである。
  • 1 つ以上のグループのセットがタイムラインとなる。タイムラインは、ツリーのルート ノードである。

タイムラインには、少なくとも 1 つのグループが含まれていなければならない。各グループは、最終プロダクションにおける単位のストリームを表す。代表的なプロダクションには、ビデオ グループとオーディオ グループが 1 つずつ含まれる。合成はオプションであり、必要な場合にさらに構造を提供するものである。

次の図は、タイムラインの構造を示している。この図は、ツリー内の親子関係を示しているが、時間シーケンスを表しているわけではない。

タイムラインがレンダリングされる方法

前のセクションのツリー図では、重なり合うトラックと合成がどのようにレンダリングされるかは示されていない。その目的では、タイムラインを、ノード構造ではなく時間シーケンスとしてとらえるのがよい。次の図は、2 つのビデオ トラックと 2 つのオーディオ トラックが含まれる単純なプロジェクトを示している。先頭の矢印は、ゼロから始まるタイムラインの方向を表している。

まず最初に、ビデオ グループについて考える。トラック 1 は、トラック 0 より優先順位が高い。トラック 1 にビデオ ソースが入っている場合、そのソースはトラック 0 の内容を隠蔽する。トラック 1 が空の場合は、トラック 0 が "透けて" 見える。このビデオがレンダリングされると、ソース A から始まる。そしてソース C に切り替わるが、ソース A の最後の部分とソース B の最初の部分は見えない。最後にソース C が終わるときに、ソース B に切り替わる (B はすでに進行中である)。

オーディオ グループはこれとは異なる動作をする。すべてのトラックが単純にミキシングされる。オーディオはソース D から始まり、ソース D とソース E のミックスに切り替わり、ソース D だけになって終了する。

トランジション

トランジションは、フェードやワイプなどのビジュアル エフェクトを使って、ビデオ トラックを別のビデオ トラックにすきまなく繋げる方法である。前の例では、ビデオは即座に切り替わる。こんどは、同じビデオ グループにトランジションを追加して考えてみる。

トランジションは、トラック 1 に存在する。これは、そのトラック (トラック 1) とその上のレイヤ (トラック 0) との間のトランジションを表す。トランジションの開始時には、レンダリングされた出力はすべてトラック 0 (ソース A) からのものである。終了時には、出力はすべてトラック 1 (ソース C) からのものとなる。その間では、出力はソース A からソース C へ変換する。たとえばフェードトランジションでは、1 つのソースがしだいに別のソースへとフェードする。

レンダリングされた出力は、図の一番下に図式化されている。トランジション リージョンの中では、ビデオ イメージはソース A からソース C へ変換する。ソース C からソース B へが直接切り替えとなるのは、トラックのその位置にトランジションが含まれていないためである。

トランジションには、特定の方向があることに注意すること。トランジションの開始時には、ビデオ出力はほとんどがソース A からのものである。トランジションの中間では、ビデオは 2 つのソースが混ざったものとなる。終了時には、出力はほとんどがソース B からのものとなる。デフォルトでは、トランジションは図に示したように、優先順位の低いトラックから優先順位の高いトラックへと進行する。しかし、逆の動作を指定することもできる。次の図は、その状況を示す例である。トラック 0 からトラック 1 にフェードし、トラック 1 からトラック 0 にフェードして戻る。どちらのトランジションもトラック 1 に存在する。

合成と重なり

各ビデオ トラックは、それぞれ固有のレイヤを占めるものと考えることができる。トラックのコレクションでは、最初のトラックの優先順位が最も低く (優先順位 0)、以降のトラックは優先順位が 1 レベルずつ高くなる。各レイヤでは、レイヤ内のソース クリップは、そのレイヤにトランジションが含まれていなければ、下のレイヤ内のソース クリップを隠蔽する。したがって、DES はレンダリングを行うときにいくつかのパスを作成すると考えることができる。

まず、トラック 0 をレンダリングする。トラック 0 の "下" には何もないので、空のリージョンは黒一色のイメージとしてレンダリングされる。このレイヤ内のトランジションは、黒イメージとトラック 0 の間で行われる (たとえば、ビデオ クリップが黒からフェードする)。DES は、トラック 0 の上にトラック 1 を配置し、2 つのトラックの間にトランジションを生成する。その結果は、2 つのトラックの合成となる。次に、この合成の上にトラック 2 を配置する。このレイヤ上のトランジションは、この合成とトラック 2 の間で行われる。このプロセスが、最後のトラック (最高の優先順位) が配置されるまで続けられる。

複数のトラックが合成されると、それは単一のトラックのように動作する (これは仮想トラックと呼ばれる)。DES では、合成 オブジェクトがこの動作をカプセル化している。複数のトラックを合成に挿入でき、その合成を別の合成に挿入できる (挿入される側の合成に、他のトラックまたは他の合成が含まれていてもかまわない)。このとき、最初の合成は大きい合成の中で単一のレイヤとして機能する。

このモデルでは、複雑な構成が可能である。たとえば、あるビデオ クリップが 2 番目のクリップにワイプし、同時にその合成 (その 2 つのクリップおよびワイプ) が 3 番目のクリップにフェードするといったことが可能となる。

エフェクト

トランジションと異なり、エフェクトは単一のレイヤに適用される。ビデオ エフェクトには、ビデオ イメージのブラー、カラー ビデオのモノクロへの変換、一定の軸に沿ったイメージの回転などがある。オーディオ エフェクトには、リバーブやエコーなどがある。エフェクトは、個別のソース、トラック、または合成全体に適用できる。


DirectShow 編集サービスにおける時間

ビデオを編集するためには、時間に関する重要な概念をいくつか扱わなければならない。例を示す。

  • 各クリップには、時間幅がある。
  • クリップ、トランジション、およびエフェクトは、プロジェクト内で特定の時点に開始される。
  • ビデオには、毎秒のフレーム数 (fps) で表されるフレーム レートがある。

Microsoft® DirectShow® 編集サービス (DES) には、時間やフレーム レートを扱う多数のメソッドがあり、それらの値の意味は状況によって異なる。ここでは、DES で使われるさまざまな時間の計測単位を説明する。以下のセクションが含まれる。

  • 時間の値
  • フレーム レート

時間の値

パラメータが時間を表す場合、3 とおりの意味がある。

  • タイムライン タイム : タイムラインの始点に対する時間。たとえば、あるクリップはタイムラインにおいて 2 秒の時点で始まる、あるトランジションはタイムラインにおいて 15 秒の時点で発生する、など。タイムラインによって最終的にレンダリングされるオブジェクトが決まるので、タイムライン時間を "プロジェクト時間" と考えることもできる。
  • メディア タイム : ソース ファイル内で、通常の再生において達する、ファイルの先頭に対する位置。たとえば、10 秒間のビデオ ファイルがある場合、ファイルの中間地点は、メディア時間で表すと 5 秒の位置にある。
  • 親タイム : タイムライン内のオブジェクトに対する時間。たとえば、あるオブジェクトがタイムライン上で 8 秒の位置で始まり、そのオブジェクトに含まれる別のオブジェクトがタイムライン上で 10 秒の位置で始まる場合、子オブジェクトは親に対して 2 秒の位置で始まることになる。仮想トラックはすべて、タイムラインに対して時間ゼロから始まる。したがって、仮想トラック内のオブジェクトについては、親タイムとタイムライン タイムは等しくなる。

メディア タイムは、ソース オブジェクトにのみ適用される。各ソース オブジェクトには、メディア開始タイムとメディア終了タイムがある。たとえば、10 秒間のビデオ クリップがあり、クリップの途中の 5 秒間だけを使いたい場合、クリップから最初の 2 秒と最後の 3 秒をトリミングする。このクリップをプロジェクト内で (通常の再生速度で) 20 秒の位置から開始したい場合、開始タイムと終了タイムを次のように指定することになる。

  • メディア開始タイム : 2 秒
  • メディア終了タイム : 7 秒
  • タイムライン開始タイム : 20 秒
  • タイムライン終了タイム : 25 秒

フレーム レート

フレーム レートは、メディア ストリームの "速度" であり、毎秒のフレーム数で計測される。時間値の場合と同様に、フレーム レートの意味は状況によって異なる。

  • 出力フレーム レート : 最終的にレンダリングされたプロジェクトのフレーム レート。グループによって定義される。プロジェクトをレンダリングすると、各グループはそれぞれ固有のフレーム レートを持つ個別のメディア ストリームになる。
  • ソース フレーム レート : ソース ファイルが作成されたときのフレーム レート。作成時のフレーム レートは、グループの出力フレーム レートと一致していなくてもよい。DES は、必要に応じて自動的にファイルのアップサンプルまたはダウンサンプルを行う。ほとんどのメディア フォーマットについて、DES はフォーマットを調べてフレーム レートを特定することができる。DIB シーケンスだけは例外で、そのフレーム レートはユーザーが指定しなければならない (詳細については、「ソースの操作」を参照すること)。
  • 再生フレーム レート : ソース クリップがプロジェクト内で始まるときの再生速度。たとえば、10 秒間のビデオをタイムライン上の 5 秒間に収めることができる。その場合、次の図で示すように、このクリップの速度は 2 倍になる。

    ソースの再生速度を上げる

    (オーディオ ソースの場合は、ピッチもシフトする)。ソース クリップの再生レートは、次の式によって求められる。
    再生レート = (メディア終了タイム - メディア開始タイム) / (タイムライン終了タイム - タイムライン開始タイム)

以上の 3 種類のレートは、それぞれ他とは独立している点に注意すること。

  • メディア タイムを調整することにより、クリップの速度の上げ下げができる。これは、最終出力のフレーム レートには影響しない。
  • ファイルの再生速度に影響を与えずに、出力フレーム レートを上げ下げすることができる。
  • 同じグループ内では、作成時のフレーム レートが異なるソース ファイルを混在させることができ、DES は各クリップのアップサンプルまたはダウンサンプルを行って、グループのフレーム レートに一致させる。

プロジェクトをレンダリングするときに、すべての時間は、グループのフレーム レートによって決まる最も近いフレーム境界に丸められる。たとえば、ビデオ グループのフレーム レートが 30 fps であるとする。各フレームはほぼ 33 ミリ秒 (ms) であるとする。ここで、タイムラインに対して 1.68 秒のソース クリップを追加し、このクリップは時間ゼロから始まるとする。このソースは、フレーム境界ちょうどでは終了しないので、DES は終了タイムを 1.6666 秒 (50 フレーム) に丸める。レンダリング後のプロジェクトで 1.68 秒の位置を調べた場合、実際にはソースが終了した後 (51 番目のフレーム) を調べることになる。

ただし、DES はソースの終了タイムを書き換えることはしない。後でグループのフレーム　レートを変更するか、ソースをタイムライン内の別の位置に移動した場合には、時間を丸めた結果は異なるものになる。そのため、DES はもとの終了タイムを維持し、必要なときにのみ丸めを行う。詳細については、「IAMTimelineObj::FixTimes」を参照すること。


DirectShow 編集サービスの使い方

このセクションでは、Microsoft® DirectShow® 編集サービス (DES) を使用してビデオ編集アプリケーションを開発する方法を詳細に説明する。以下のセクションが含まれる。

  • タイムライン コンポーネントの概要
  • プロジェクトのロードとプレビュー
  • タイムラインの構築
  • ソースの操作
  • エフェクトとトランジションの操作
  • プロジェクトのレンダリング
  • エラーのログ
  • ビデオ編集プロジェクトの管理
  • アルファ ブレンディング
  • カットリストのタイムラインへの変換


タイムライン コンポーネントの概要

Microsoft® DirectShow® 編集サービス (DES) のタイムラインは、COM コンポーネントである。タイムライン内のオブジェクトも、COM コンポーネントである。ここでは、さまざまなオブジェクトが公開するインターフェイスの概要について説明する。

ここには、次のトピックが含まれている。

  • タイムライン
  • タイムライン オブジェクト
  • サブオブジェクト

タイムラインの詳細については、「タイムライン モデル」を参照すること。DES のコンポーネント一覧については、「DirectShow 編集サービスのコンポーネント」を参照すること。

タイムライン

タイムラインは、IAMTimeline インターフェイスを公開する。このインターフェイスには、タイムライン上のプロパティの設定、タイムラインへのグループの追加、およびグループ、トラック、ソースなどのタイムライン オブジェクトの作成を行うためのメソッドが含まれている。新しいタイムラインを作成するには、次のように標準の CoCreateInstance 関数を呼び出す。

IAMTimeline *pTL = NULL;
hr = CoCreateInstance(CLSID_AMTimeline, NULL, CLSCTX_INPROC_SERVER,
        IID_IAMTimeline, (void**)&pTL);

新しいタイムラインは空である。この時点で、既存のプロジェクト ファイル読み込むか (詳細については「プロジェクトのロードとプレビュー」を参照)、または新しいオブジェクトを作成、挿入してタイムラインを構築できる (詳細については、「タイムラインの構築」を参照すること)。

タイムライン オブジェクト

タイムラインの各タイプのオブジェクト (ソース、トラック、エフェクトなど) は、明確な COM オブジェクトである。しかし、アプリケーションは CoCreateInstance 関数を使ってこれらのオブジェクトを作成せず、IAMTimeline::CreateEmptyNode メソッドを呼び出す。このメソッドは、要求されたタイプのオブジェクトを作成し、初期化する。次に、オブジェクトへのポインタを返す。詳細については、「タイムラインの構築」を参照すること。

各タイムライン オブジェクトは、IAMTimelineObj インターフェイスを公開する。さらに、さまざまなオブジェクト タイプが、次のような特別なインターフェイスをサポートしている。

  • ソース : IAMTimelineSrc
  • トラック : IAMTimelineTrack
  • 合成 : IAMTimelineComp
  • グループ : IAMTimelineComp、IAMTimelineGroup
  • エフェクト : IAMTimelineEffect
  • トランジション : IAMTimelineTrans

グループは合成の一種であるので、IAMTimelineComp をサポートするとともに、独自の IAMTimelineGroup インターフェイスをサポートしている。

前に示したインターフェイスに加えて、タイムライン オブジェクトはほかの二次的なインターフェイスを公開する。これらのインターフェイスによって、オブジェクト タイプ間の関係が決定される。

インターフェイス | 意味 | 公開元
IAMTimelineVirtualTrack | このオブジェクトは仮想トラックである。仮想トラックとは、トラックのように機能できる任意のオブジェクトのことである。仮想トラックは、合成内に常駐し、ほかのタイムライン オブジェクトを保持できる。 | 合成、トラック
IAMTimelineEffectable | このオブジェクトはエフェクトを持つことができる。 | 合成、トラック、ソース
IAMTimelineTransable | このオブジェクトはトランジションを持つことができる。 | 合成、トラック
IAMTimelineSplittable | このオブジェクトは、IAMTimelineSplittable::SplitAt メソッドを使って分割できる。 | トラック、ソース、エフェクト、トランジション

サブオブジェクト

ソース、エフェクト、およびトランジションは、ほかの COM オブジェクトへの内部ポインタを持っている。このポインタは、サブオブジェクトと呼ばれる。サブオブジェクトは、オブジェクトの実際の操作を実行する。ソースのサブオブジェクトは、ビデオ データまたはオーディオ データを作成するコンポーネントである。エフェクトまたはトランジションのサブオブジェクトは、データを変換するコンポーネントである。たとえば、ビデオ エフェクトでは、ビデオ ストリームで視覚的なエフェクトが作成される。

サブオブジェクトのタイプは、次のようにオブジェクトのタイプによって異なる。

  • ソース : シークをサポートし、DES がサポートするフォーマットを作成する、任意の DirectShow ソース フィルタまたはパーサー フィルタ。デコード用の DirectShow フィルタが存在する場合、圧縮フォーマットとすることができる。
  • エフェクト : ビデオでは、任意の 1 入力の Microsoft® DirectX® 2D 変換オブジェクト。オーディオでは、任意の DirectShow オーディオ エフェクト フィルタ。
  • トランジション : ビデオでは、任意の 2 入力の DirectX 2D 変換オブジェクト。オーディオはトランジションをサポートしていない。

グループ、合成、およびトラックは、サブオブジェクトを持たない。

アプリケーションは、サブオブジェクト ポインタを直接設定しない。エフェクトとトランジションの場合、アプリケーションは IAMTimelineObj::SetSubObjectGUID メソッドを呼び出し、サブオブジェクトの GUID を指定する。ソース オブジェクトの場合、アプリケーションは通常 IAMTimelineSrc::SetMediaName を呼び出し、ソース ファイルの名前を指定する。しかし、SetSubObjectGUID メソッドはソース オブジェクトにも使用して、フィルタのクラス識別子 (CLSID) を指定できる。

詳細については、「ソースの操作」および「エフェクトとトランジションの操作」を参照すること。


プロジェクトのロードとプレビュー

ここでは、Microsoft® DirectShow® 編集サービス (DES) でプロジェクトをロードしてプレビューする方法を説明している。ここでは、空のタイムラインに XML プロジェクト ファイルをロードし、タイムラインをプレビュー用にレンダリングするサンプル アプリケーションを紹介している。このサンプル アプリケーションを変更して、この SDK に付属するサンプル XML プロジェクトを扱うことができる。

ここには、以下のトピックが含まれる。

  • プロジェクト ファイルのロード
  • プロジェクトのプレビュー
  • クリーン アップ
  • サンプル コード

プロジェクト ファイルのロード

プロジェクト ファイルをロードするには 2 つのコンポーネントが必要である。XML パーサーと空のタイムラインの 2 つである。XML パーサーは、XML プロジェクト ファイルを読み込み、ファイルに定義されている各オブジェクトを作成する。そして、作成したオブジェクトをタイムラインに挿入し、デフォルトのフレーム レートなどのタイムラインの属性を設定する。次のサンプル コードは、ファイルをロードする。

HRESULT         hr;
IAMTimeline     *pTL = NULL;
IXml2Dex        *pXML = NULL;

hr = CoCreateInstance(CLSID_AMTimeline,
            NULL, CLSCTX_INPROC_SERVER,
            IID_IAMTimeline, (void**)&pTL);

hr = CoCreateInstance(CLSID_Xml2Dex,
            NULL, CLSCTX_INPROC_SERVER,
            IID_IXml2Dex, (void**)&pXML);

hr = pXML->ReadXMLFile(pTL, L"C:\\example.xtl");
pXML->Release();

パーサーは、プロジェクト ファイルのロードと保存のためのメソッドを持つ IXml2Dex インターフェイスを公開する。タイムラインは、タイムラインの操作と新しいタイムライン オブジェクトの作成のためのメソッドを持つ IAMTimeline インターフェイスを公開する。コードに示したように、CoCreateInstance 関数を呼び出して各コンポーネントを作成する。新しいインスタンスの作成によって、そのインターフェイスの参照カウントがインクリメントされることを忘れないこと。メモリ リークを回避するには、インターフェイスの使用が終わったら必ず解放する必要がある。この例では、IXml2Dex を指すポインタは必要なくなるので、このインターフェイスを解放できる。IAMTimeline を指すポインタは、タイムラインのプレビューのためにまだ必要である。

IXml2Dex::ReadXMLFile メソッドは、指定されたファイルを読み込み、そのファイルで定義されているオブジェクトをタイムラインに挿入する。ファイル名は、BSTR 値を使って指定される。例のコードを短くするために、ここではファイル名をリテラル文字列として指定している。通常は、[ファイルを開く] ダイアログ ボックスなどを使ってファイル名を取得する。

ReadXML メソッドは、動作が成功した場合は成功コードを返す。そうでない場合は、VFW_E_INVALID_FILE_FORMAT などのエラー コードを返す。エラー条件を正しく処理するためには、常に戻り値をチェックする必要がある。例のコードを短くするために、ここではエラーをチェックしていない。

プロジェクトのプレビュー

プロジェクトをプレビューするためには、タイムラインから DirectShow フィルタ グラフを構築するレンダリング エンジンと呼ばれるコンポーネントが必要である。フィルタ グラフが、プロジェクトを実際にレンダリングする。レンダリング エンジンを使って、プロジェクトのプレビューおよび最終出力ファイルの書き込みを行うことができる。

ここでは、レンダリング エンジンの詳細については説明しない。プレビューの場合は、いくつかのメソッド呼び出ししか必要としない。出力ファイルを書き込む方法などの詳細については、「プロジェクトのレンダリング」を参照すること。次のサンプル コードは、プレビュー グラフを構築する方法を示している。

IRenderEngine *pRender = NULL;
hr = CoCreateInstance(CLSID_RenderEngine,
            NULL, CLSCTX_INPROC_SERVER,
            IID_IRenderEngine, (void**) &pRender);

hr = pRender->SetTimelineObject(pTL);
hr = pRender->ConnectFrontEnd( );
hr = pRender->RenderOutputPins( );

CoCreateInstance 関数を使ってレンダリング エンジンを作成する。次に、レンダリング エンジンの IRenderEngine インターフェイスの以下のメソッドを呼び出す。

  • SetTimelineObject。使用するタイムラインを指定する。
  • ConnectFrontEnd。フィルタ グラフを構築し、タイムライン内の各グループごとに出力ピンを 1 つ設定する。
  • RenderOutputPins。各出力ピンをビデオ レンダラまたはオーディオ レンダラに接続して、プレビュー グラフの構築を完了させる。

グラフが構築されれば、DirectShow フィルタ グラフの場合と同じように、そのグラフを実行することによりプロジェクトをプレビューできる。最初に、IRenderEngine::GetFilterGraph メソッドを呼び出して、フィルタ グラフへのポインタを取得する。

IGraphBuilder   *pGraph = NULL;
hr = pRender->GetFilterGraph(&pGraph);

そのフィルタ グラフに、IMediaControl および IMediaEvent インターフェイスについて照会する。この 2 つのインターフェイスを使って、グラフを実行し、再生が完了するまで待機する。これらのインターフェイスの使い方の詳細については、「ファイルの再生法」および「イベントへの応答」を参照すること。次のコードは、これらのインターフェイスを使う方法の 1 つを示している。

IMediaControl   *pControl = NULL;
IMediaEvent     *pEvent = NULL;
long evCode;

pGraph->QueryInterface(IID_IMediaControl, (void **)&pControl);
pGraph->QueryInterface(IID_IMediaEvent, (void **)&pEvent);
hr = pControl->Run();
hr = pEvent->WaitForCompletion(INFINITE, &evCode);
pControl->Stop();

この例のコードは、IMediaEvent::WaitForCompletion メソッド呼び出しの INFINITE パラメータによって、再生が完了するまでプログラムの実行を停止させる。ただし、再生中に問題が発生した場合には、プログラムが応答できなくなる可能性がある。実際のアプリケーションでは、メッセージ ループを使って再生が完了するまで待機する。また、ユーザーに再生を中断させる方法を提供することが推奨される。

クリーン アップ

レンダリング エンジンの使用が終わったら、必ず IRenderEngine::ScrapIt メソッドを呼び出す。このメソッドは、フィルタ グラフを削除し、レンダリング エンジンが保持していたすべてのリソースを解放する。

pRender->ScrapIt();

サンプル コード

以下は、ここで説明したサンプル アプリケーション全体のコードである。

#include <dshow.h>
#include <qedit.h>

// タイムラインをプレビューする。
void PreviewTL(IAMTimeline *pTL, IRenderEngine *pRender)
{
    HRESULT hr;
    IGraphBuilder   *pGraph = NULL;
    IMediaControl   *pControl = NULL;
    IMediaEvent     *pEvent = NULL;

    // グラフを構築する。
    hr = pRender->SetTimelineObject(pTL);
    hr = pRender->ConnectFrontEnd( );
    hr = pRender->RenderOutputPins( );

    // グラフを実行する。
    hr = pRender->GetFilterGraph(&pGraph);
    pGraph->QueryInterface(IID_IMediaControl, (void **)&pControl);
    pGraph->QueryInterface(IID_IMediaEvent, (void **)&pEvent);
    hr = pControl->Run();

    long evCode;
    hr = pEvent->WaitForCompletion(INFINITE, &evCode);
    pControl->Stop();

    // クリーン アップする。
    pEvent->Release();
    pControl->Release();
    pGraph->Release();
}

void main( void )
{
    HRESULT         hr;
    IAMTimeline     *pTL = NULL;
    IRenderEngine   *pRender = NULL;
    IXml2Dex        *pXML = NULL;

    CoInitialize(NULL);
    hr = CoCreateInstance(CLSID_AMTimeline,
                NULL, CLSCTX_INPROC_SERVER,
                IID_IAMTimeline, (void**)&pTL);
    hr = CoCreateInstance(CLSID_Xml2Dex,
                NULL, CLSCTX_INPROC_SERVER,
                IID_IXml2Dex, (void**)&pXML);
    hr = CoCreateInstance(CLSID_RenderEngine,
                NULL, CLSCTX_INPROC_SERVER,
                IID_IRenderEngine, (void**)&pRender);

    // プロジェクト ファイルをロードする。
    hr = pXML->ReadXMLFile(pTL, L"C:\\example.xtl");
    pXML->Release();

    PreviewTL(pTL, pRender);

    // クリーン アップする。
    pRender->ScrapIt();
    pTL->Release();
    pRender->Release();
    CoUninitialize();
}


タイムラインの構築

ここでは、Microsoft® DirectShow® 編集サービス (DES) でタイムラインを構築する方法を説明している。タイムラインを作成してレンダリングするコンソール アプリケーションの例を紹介する。作成するタイムラインは、ソース クリップ 1 つだけの単一のビデオ グループからなる最小規模のものだが、より複雑なタイムラインの作成に必要な概念のほとんどが示されている。

ここには、以下のトピックが含まれる。

  • タイムライン オブジェクトの作成
  • グループ、合成、およびトラックの作成
  • グループ メディア タイプの設定
  • ソースの追加
  • サンプル コード

タイムライン オブジェクトの作成

ここで紹介するサンプル コードは空のタイムラインで始まるが、既存のプロジェクトをロードしてオブジェクトを追加する場合も、同じ手順が適用される。

タイムライン内に何らかの型のオブジェクトを作成するには、IAMTimeline::CreateEmptyNode メソッドを呼び出し、合成、グループ、またはトラックなど、作成するメジャー タイプを指定する。たとえば、次のコードは新しいグループを作成する。

IAMTimelineObj *pGroupObj = NULL;
pTL->CreateEmptyNode(&pGroupObj, TIMELINE_MAJOR_TYPE_GROUP);

CreateEmptyNode メソッドは、オブジェクトを作成して、そのオブジェクトの IAMTimelineObj インターフェイスを指すポインタを返す。このメソッドは、IAMTimelineObj インターフェイスの参照カウントもインクリメントするので、使用を終えたときには、このインターフェイスも解放しなければならない。CoCreateInstance 関数を呼び出してはならない。そうではなく、必ず CreateEmptyNode を使ってタイムライン オブジェクトを作成する。これは、このメソッドが、タイムラインで使用できるように新しいオブジェクトを初期化するためである。

IAMTimelineObj インターフェイスは、汎用インターフェイスである。これは、タイムライン オブジェクトのすべてのタイプに共通のメソッドを提供する。オブジェクトの各タイプは、他のインターフェイスも公開する。たとえば、グループは IAMTimelineGroup インターフェイスを公開する。他のインターフェイスを指すポインタは、QueryInterface を呼び出して取得できる。

オブジェクトを作成した段階では、まだそれはタイムラインの一部にはなっていない。オブジェクトをタイムラインに追加するメソッドは、オブジェクトのタイプによって異なる。次のセクションでは、グループ、合成、およびトラックをタイムラインに追加する方法を説明する。

グループ、合成、およびトラックの作成

グループ、合成、およびトラックは、タイムラインとソース クリップとの間の中間レイヤである。これらは、その中に入るオブジェクトのタイプによって区別される。

  • トラックには、ソース オブジェクトが入る。
  • 合成には、トラックおよび他の合成が入るが、ソース オブジェクトは入らない。
  • グループは、最上位レベルの合成である。グループには、合成とトラックが入るが、合成の中にグループを入れることはできない。
  • 仮想トラックは、合成またはグループ内に配置できる任意のオブジェクトである。これには、トラックおよび合成が含まれる。

以下のインターフェイスは、これらのオブジェクトによって公開される。

インターフェイス | インターフェイスを公開するオブジェクト
IAMTimelineTrack | トラック
IAMTimelineVirtualTrack | トラック、合成
IAMTimelineComp | 合成、グループ
IAMTimelineGroup | グループ

これらのインターフェイスには、オブジェクトをタイムラインに追加するメソッドが含まれている。

  • IAMTimeline::AddGroup : タイムラインにグループを挿入する。
  • IAMTimelineComp::VTrackInsBefore : 合成またはグループに仮想トラックを挿入する。
  • IAMTimelineTrack::SrcAdd : トラックにソースを挿入する。

たとえば、次のコードは新しいトラックをグループに挿入する。前の表に示したように、グループは合成の一種と考えられ、トラックは仮想トラックの一種と考えられる。したがって、トラックをグループに挿入するには、グループにその IAMTimelineComp インターフェイスについて照会し、IAMTimelineComp::VTrackInsBefore メソッドを呼び出さなければならない。

IAMTimelineGroup    *pGroup;
// 新しいグループを作成する (ここには示されていない)。

IAMTimelineComp     *pComp = NULL;
IAMTimelineObj      *pTrackObj = NULL;

pTL->CreateEmptyNode(&pTrackObj, TIMELINE_MAJOR_TYPE_TRACK);
pGroup->QueryInterface(IID_IAMTimelineComp, (void **)&pComp);
pComp->VTrackInsBefore(pTrackObj, 0);

VTrackInsBefore の 2 番目のパラメータは、仮想トラックの優先順位を指定する。優先順位レベルはゼロから始まる。-1 を指定した場合、仮想トラックは優先順位リストの最後に挿入される。既に仮想トラックが存在するレベルの値を指定した場合、その位置以下のすべてのオブジェクトの優先順位レベルが 1 ずつ下げられる。仮想トラックの個数より大きい優先順位レベルの仮想トラックを挿入してはならない。それを行った場合の動作は未定義となる。

タイムラインからオブジェクトを完全に削除するには、そのオブジェクトの IAMTimelineObj::RemoveAll メソッドを呼び出す。このメソッドは、オブジェクトとその子をすべて削除する。オブジェクトをタイムラインの別の場所に再挿入する目的で削除するには、代わりに IAMTimelineObj::Remove を呼び出す。RemoveAll と異なり、このメソッドはオブジェクトの子は削除しない。タイムラインからすべてを削除するには、IAMTimeline::ClearAllGroups を呼び出す。

グループ メディア タイプの設定

すべてのグループは、非圧縮のメディア タイプとしてオーディオまたはビデオを定義しなければならない。非圧縮メディア タイプは、再生時にビューアが見る、または聴くフォーマットである。通常、最終出力は非圧縮フォーマットである。詳細については、「プロジェクトのレンダリング」を参照すること。

非圧縮フォーマットを設定するには、AM_MEDIA_TYPE 構造体を作成し、そのメンバとして適切なメジャー タイプ、サブタイプ、およびフォーマット ヘッダーを設定する。ビデオの場合は、フォーマット ヘッダーに幅、高さ、およびビット深度を設定する。オーディオの場合は、フォーマット ヘッダーにサンプリング レートを設定する。メジャー タイプのみを設定した場合、DES は他の値に適切なデフォルトを設定する。実際には、出力を明示的に制御する場合には値を設定する必要がある。CMediaType 基底クラスは、AM_MEDIA_TYPE 構造体を管理する便利な方法を提供する。そうしたければ、AM_MEDIA_TYPE 構造体を直接操作することもできる。

メディア タイプ構造体を初期化した後、IAMTimelineGroup::SetMediaType メソッドを呼び出してグループのメディア タイプを設定する。

次の例は、幅 320 ピクセル、高さ 240 ピクセルの 16 ビット RGB ビデオを指定している。

AM_MEDIA_TYPE mtGroup;
mtGroup.majortype = MEDIATYPE_Video;
mtGroup.subtype = MEDIASUBTYPE_RGB555;

// フォーマット ヘッダーを設定する。
mtGroup.pbFormat = (BYTE*)CoTaskMemAlloc(sizeof(VIDEOINFOHEADER));
VIDEOINFOHEADER *pVideoHeader = (VIDEOINFOHEADER*)mtGroup.pbFormat;
ZeroMemory(pVideoHeader, sizeof(VIDEOINFOHEADER));
pVideoHeader->bmiHeader.biBitCount = 16;
pVideoHeader->bmiHeader.biWidth = 320;
pVideoHeader->bmiHeader.biHeight = 240;
pVideoHeader->bmiHeader.biPlanes = 1;
pVideoHeader->bmiHeader.biSize = sizeof(BITMAPINFOHEADER);
pVideoHeader->bmiHeader.biSizeImage = DIBSIZE(pVideoHeader->bmiHeader);

mtGroup.formattype = FORMAT_VideoInfo;
mtGroup.bFixedSizeSamples = TRUE;
mtGroup.lSampleSize = DIBSIZE(pVideoHeader->bmiHeader);

// グループのメディア タイプを設定する。
pGroup->SetMediaType( &mtGroup );

ソースの追加

ソース オブジェクトは、他のタイムライン オブジェクトと同じ方法で作成する。ただし、タイムラインに挿入する前に、少なくともソース上の以下のプロパティを指定しなければならない。

  • タイムライン相対の開始タイムと終了タイム。IAMTimelineObj::SetStartStop メソッドを呼び出す。
  • ソースとして使用するメディア ファイル。IAMTimelineSrc::SetMediaName メソッドを呼び出し、ファイルの名前を表すワイド文字列を指定する。
  • 元のファイル相対のメディア開始タイムとメディア終了タイム。IAMTimelineSrc::SetMediaTimes メソッドを呼び出す。メディア タイムの詳細については、「DirectShow 編集サービスにおける時間」を参照すること。

次の例では、ソース クリップはファイル内の 4 秒の位置から始まる。メディアの時間幅は 10 秒で、タイムラインの長さの 2 倍であり、これはソースが通常の 2 倍の速度で再生されることを意味する。定数 UNITS は、10000000 (107) として定義され、これは 1 秒に等しい。

pSourceObj->SetStartStop(0, 50000000)
pSource->SetMediaName(L"C:\\Example.avi");
pSource->SetMediaTimes(40000000, 140000000);

注 : 現在 DES は、ビデオ圧縮マネージャ (VCM) CODEC で圧縮されたソースは、同時に 75 個までしかレンダリングできない。また、そのようなソースがプロジェクト全体で 75 個を超える場合は、動的な再接続を使わなければ、DES はプロジェクトをプレビューできない。詳細については、「IRenderEngine::SetDynamicReconnectLevel」を参照すること。

ソースの詳細については、「ソースの操作」を参照すること。

サンプル コード

以下は、ここで説明したサンプル アプリケーション全体のコードである。

注 : 簡潔にするために、サンプル コードではエラー チェックを行っていない。実際のアプリケーションでは、メソッド呼び出しの戻り値をチェックして、失敗がないようにする必要がある。

#include <dshow.h>
#include <qedit.h>

// タイムラインをプレビューする。
void PreviewTL(IAMTimeline *pTL, IRenderEngine *pRender)
{
    IGraphBuilder   *pGraph = NULL;
    IMediaControl   *pControl = NULL;
    IMediaEvent     *pEvent = NULL;

    // グラフを構築する。
    pRender->SetTimelineObject(pTL);
    pRender->ConnectFrontEnd( );
    pRender->RenderOutputPins( );

    // グラフを実行する。
    pRender->GetFilterGraph(&pGraph);
    pGraph->QueryInterface(IID_IMediaControl, (void **)&pControl);
    pGraph->QueryInterface(IID_IMediaEvent, (void **)&pEvent);
    pControl->Run();

    long evCode;
    pEvent->WaitForCompletion(INFINITE, &evCode);
    pControl->Stop();

    // クリーン アップする。
    pEvent->Release();
    pControl->Release();
    pGraph->Release();
}

void main( void )
{
    // 最初に空のタイムラインを作成する。

    IAMTimeline    *pTL = NULL;
    CoInitialize(NULL);
    CoCreateInstance(CLSID_AMTimeline, NULL, CLSCTX_INPROC_SERVER,
            IID_IAMTimeline, (void**)&pTL);

    // グループ :  タイムラインにビデオ グループを追加する。
    IAMTimelineGroup    *pGroup = NULL;
    IAMTimelineObj      *pGroupObj = NULL;

    pTL->CreateEmptyNode(&pGroupObj, TIMELINE_MAJOR_TYPE_GROUP);
    pGroupObj->QueryInterface(IID_IAMTimelineGroup, (void **)&pGroup);

    // グループのメディア タイプを設定する。
    AM_MEDIA_TYPE mtGroup;
    ZeroMemory(&mtGroup, sizeof(AM_MEDIA_TYPE));
    mtGroup.majortype = MEDIATYPE_Video;
    pGroup->SetMediaType(&mtGroup);
    pTL->AddGroup(pGroupObj);
    pGroupObj->Release();

    // トラック :  グループにトラックを追加する。
    IAMTimelineObj      *pTrackObj;
    IAMTimelineTrack    *pTrack;
    IAMTimelineComp     *pComp = NULL;

    pTL->CreateEmptyNode(&pTrackObj, TIMELINE_MAJOR_TYPE_TRACK);
    pGroup->QueryInterface(IID_IAMTimelineComp, (void **)&pComp);
    pComp->VTrackInsBefore(pTrackObj, 0);
    pTrackObj->QueryInterface(IID_IAMTimelineTrack, (void **)&pTrack);

    pTrackObj->Release();
    pComp->Release();
    pGroup->Release();

    // ソース :  トラックにソースを追加する。
    IAMTimelineSrc      *pSource = NULL;
    IAMTimelineObj      *pSourceObj;
    pTL->CreateEmptyNode(&pSourceObj, TIMELINE_MAJOR_TYPE_SOURCE);
    pSourceObj->QueryInterface(IID_IAMTimelineSrc, (void **)&pSource);

    // タイムとファイル名を設定する。
    pSourceObj->SetStartStop(0, 50000000);
    pSource->SetMediaName(L"C:\\Example.avi");
    pSource->SetMediaTimes(40000000, 140000000);
    pTrack->SrcAdd(pSourceObj);

    pSourceObj->Release();
    pSource->Release();
    pTrack->Release();

    // タイムラインをプレビューする。
    IRenderEngine       *pRenderEngine = NULL;
    CoCreateInstance(CLSID_RenderEngine, NULL, CLSCTX_INPROC_SERVER,
            IID_IRenderEngine, (void**) &pRenderEngine);
    PreviewTL(pTL, pRenderEngine);

    // クリーン アップする。
    pRenderEngine->ScrapIt();
    pTL->ClearAllGroups();
    pRenderEngine->Release();
    pTL->Release();
    CoUninitialize();
}


ソースの操作

ソース オブジェクトは、ソース ファイルからの単一のメディア ストリームを表す。ソースは、プロジェクトに未加工の素材を提供する。タイムライン内のそれ以外のものは、構造 (トラック、合成、およびグループ) を提供するか、ソースを変更する (エフェクトおよびトランジション) ために存在する。

ここでは、Microsoft® DirectShow® 編集サービス (DES) のソースに関する詳細を説明している。タイムラインにソースを追加する基本的な手順については、「タイムラインの構築」を参照すること。

ここには以下のセクションが含まれる。

  • ソースのプロパティの設定
  • メディア ディテクタの使い方
  • メディア ロケータの使い方
  • スティル イメージ
  • ビデオ カラー ソース

ソースのプロパティの設定

新しいソース オブジェクトを作成するときに、設定する必要があるプロパティと、オプションで設定できるプロパティがある。以下のプロパティは設定しなければならない。

  • タイムラインの残りの部分に相対の開始タイムと終了タイム。IAMTimelineObj::SetStartStop メソッドを呼び出す。同じトラック内のソース オブジェクトで重なり合う時間を設定してはならない。そのような設定を行うと、未定義の動作を引き起こす。
  • ソース クリップとして使用するメディア ファイル。IAMTimelineSrc::SetMediaName メソッドを呼び出す。
  • 元のソース ファイル相対のメディア開始タイムとメディア終了タイム。IAMTimelineSrc::SetMediaTimes メソッドを呼び出す。例外 : ソースがスティル イメージの場合は、メディア タイムを指定してはならない。メディア タイムの詳細については、「DirectShow 編集サービスにおける時間」を参照すること。

ソース オブジェクトは親グループからメディア タイプを継承するので、メディア タイプを指定する必要はない。

オプションのプロパティは次のとおりである。

  • 伸縮モード。伸縮モードは、サイズが出力ディメンジョンと一致しないソースを Microsoft® DirectShow® 編集サービス (DES) がレンダリングする方法を指定する。デフォルトでは、DES はアスペクト比を維持せずにイメージを伸縮する。DES は、イメージを切り詰めること、およびレターボックスを作成することもできる。伸縮モードは、IAMTimelineSrc::SetStretchMode メソッドを呼び出して指定する。
  • ソース ファイルの時間幅。メディア タイムを設定する間にこのプロパティを設定した場合、DES はメディア終了タイムを検証して、ファイルの時間幅を超える場合は終了タイムを繰り上げる。これにより、後でレンダリング エラーが出るのを防ぐことができる。「メディア ディテクタの使い方」で説明しているように、メディア ディテクタを使ってファイルの時間幅を取得できる。ファイルの時間幅は、IAMTimelineSrc::SetMediaLength メソッドを呼び出して指定する。
  • ストリーム番号。デフォルトでソース オブジェクトは、ファイル内で親グループのメディア タイプに一致する最初のストリームを使用する。ファイルに同じメディア タイプが 2 つ以上ある場合は、IAMTimelineSrc::SetStreamNumber を呼び出して、使用するストリームを選択する。メディア ディテクタを使って、ストリームの個数を取得できる。

メディア ディテクタの使い方

メディア ディテクタは、ストリームの個数、タイプ、時間幅など、ファイルに関する情報を取得するためのヘルパー オブジェクトである。メディア ディテクタには、ビデオ ストリームからポスター フレームを取得するメソッドも含まれている。これは、IMediaDet インターフェイスを公開する。

メディア ディテクタが機能するモードは 2 つある。メディア ディテクタのインスタンスを作成した時点では、特定のソース ファイルにはアタッチしていない。このモードでは、複数のソース ファイルからストリーム情報を取得できる。しかし、メディア ディテクタを使ってポスター フレームを取得すると、メディア ディテクタはビットマップ捕捉モードに切り替わる。ビットマップ捕捉モードでは、メディア ディテクタは特定のビデオ ストリームにアタッチされ、ストリーム情報メソッドは機能しなくなる。また、メディア ディテクタを起動時のモードに戻す方法はない。そのため、ストリーム情報の取得はポスター フレームの取得の前に行う必要がある。そうでない場合は、ストリームごとにメディア ディテクタの新しいインスタンスを作成することになる。

ストリーム情報を取得する手順は以下のとおりである。

  1. IMediaDet::put_Filename を呼び出して、ソース ファイルの名前を指定する。
  2. IMediaDet::get_OutputStreams を呼び出して、ソース内のストリームの個数を取得する。
  3. IMediaDet::put_CurrentStream を呼び出して、ストリーム番号を指定する。以下のメソッドを 1 つ以上呼び出す。
    • IMediaDet::get_StreamType : ストリームのメディア タイプを取得する。
    • IMediaDet::get_StreamLength : ストリームの時間幅を取得する。
    • IMediaDet::get_FrameRate : ビデオ ストリームのフレーム レートを取得する。

ポスター フレームを取得するには、前の手順と同じようにしてストリーム番号を指定する。IMediaDet::GetBitmapBits を呼び出してポスター フレームをバッファにコピーするか、IMediaDet::WriteBitmapBits を呼び出してポスター フレームをファイルに保存する。

メディア ロケータの使い方

メディア ロケータは、ファイル名を検証し、ローカル ディレクトリまたはネットワーク ディレクトリで足りないファイルを検索するヘルパー オブジェクトである。メディア ロケータは、過去の検索でファイルが見つかったディレクトリ パスのキャッシュを維持する。ファイルを見つけるために、メディア ロケータはこのキャッシュ内のディレクトリを検索する。そこで見つからなかった場合、メディア ロケータは [ファイルを開く] ダイアログを表示し、ユーザーが手動でファイルを見つけられるようにする。ユーザーがファイルを見つけた場合、メディア ロケータはその新しいディレクトリをキャッシュに追加する。 メディア ロケータは IMediaLocator インターフェイスを公開する。

通常、アプリケーションでメディア ロケータのインスタンスを直接作成することはない。タイムラインおよびレンダリング エンジンは、メディア ディテクタを使ってファイル名を検証する以下のメソッドを提供している。

  • タイムラインでファイル名を検証するには、IAMTimeline::ValidateSourceNames を呼び出す。オプションで、このメソッドはソース オブジェクトを正しいファイル名で更新する。
  • プロジェクトがレンダリングされるときにファイル名を検証するには、IRenderEngine::SetSourceNameValidation を呼び出す。

どちらのメソッドも、メディア ロケータの動作を制御するフラグをパラメータにとる。たとえば、検索をローカル ディレクトリだけに限定できる。

スティル イメージ

DES は、スティル イメージに関して次のファイル フォーマットをサポートしている。

  • ビットマップ (.bmp)
  • GIF (Graphics Interchange Format)
  • JPEG (Joint Photographic Experts Group)
  • 16 ビット、24 ビット、または 32 ビットの Targa すなわち Truevision Graphics Adapter (.tga) : モード 2 (非圧縮 RGB)

これらは、スティル イメージとして使うか、またはアニメーションの作成に使用できる。ビットマップ、JPEG、および Targa ファイルに関して、ファイルをスティル イメージとして使用する場合は、IAMTimelineSrc::SetDefaultFPS メソッドを呼び出し、フレーム レートを 0 に設定する。

DIB シーケンス

一連のビットマップ、JPEG、または Targa ファイルに対して、レンダリング エンジンはデバイスに依存しないビットマップ (DIB) のシーケンスを構築できる。DIB シーケンスを作成するには、ファイル名に Image001.bmp、Image002.bmp、Image003.bmp のようなシーケンシャルな数字を付ける。このシーケンスの最初のファイルをソースとして使用し、IAMTimelineSrc::SetDefaultFPS を呼び出して、シーケンスのフレーム レートを設定する。レンダリング エンジンは、指定されたフレーム レートで、シーケンスないのイメージを順に処理する。

指定されたフレーム レートで、シーケンスが時間幅に満たない場合、時間幅の残りはブラックとなる。レンダリング中にエラーは発生しない。

GIF ソース

DES は、GIF89a 仕様の使用により、アニメーション GIF および透過 GIF を含め、GIF ソースをサポートしている。アニメーション GIF の場合は、ほかのファイル タイプとは異なり、フレーム レートを設定する必要はない。GIF ファイルは、アニメーション内の各イメージ間の遅延を指定する。

透過 GIF をサポートするために、DES はイメージ内の透過リージョンを RGB(0,0,0) の RGB トリプレットに変換する。これにより、キー トランジションを使って、RGB(0,0,0) 上のキーにキー トランジションを使用できる。

DES は、RGB(0-7,0-7,0-7) の範囲の黒のリージョンも、透過性インデックスを除いて、RGB(8,8,8) の値に変換する。この変換は、目視では確認できない。

ビデオ カラー ソース

ビデオ カラー ソース オブジェクトは、単色の連続的なビデオ イメージを作成する。このオブジェクトの 1 つの使い方には、トランジション時のレイヤ作成がある。たとえば、このオブジェクトを使えば、ビデオのフェード インやフェード アウトを作成できる。


エフェクトとトランジションの操作

ここでは、Microsoft® DirectShow® 編集サービス (DES) におけるエフェクトとトランジションの使い方を説明している。以下のセクションが含まれる。

  • エフェクトおよびトランジションオブジェクトの追加
  • エフェクトおよびトランジションのプレビュー
  • エフェクトおよびトランジションの列挙
  • エフェクトおよびトランジションのプロパティの設定
  • トランジションの方向

エフェクトおよびトランジション オブジェクトの追加

エフェクト オブジェクトまたはトランジション オブジェクトを追加するには、以下の手順を実行する。

  1. エフェクト オブジェクトまたはトランジション オブジェクトを作成する。

    IAMTimeline::CreateEmptyNode メソッドを、メジャー タイプ TIMELINE_MAJOR_TYPE_EFFECT または TIMELINE_MAJOR_TYPE_TRANSITION によって呼び出す。エフェクトは IAMTimelineEffect インターフェイスを公開し、トランジションは IAMTimelineTrans インターフェイスを公開する。詳細については、「タイムライン オブジェクトの作成」を参照すること。

  2. サブオブジェクトを設定する。

    エフェクト オブジェクトとトランジション オブジェクトは、サブオブジェクトのためのラッパーである。データ変換を実装することにより、サブオブジェクトが実際の機能を果たす。エフェクト オブジェクトまたはトランジション オブジェクトは、サブオブジェクトを使ってオーディオまたはビデオ ストリームを変換する。任意の単一入力 Microsoft® DirectX® 変換オブジェクトをエフェクトとして使用でき、任意の双入力 DirectX 変換オブジェクトをトランジションとして使用できる。DirectShow オーディオ エフェクト フィルタは、オーディオ グループ内のエフェクトとして機能できる。DES は、ボリュームの設定を行う、ボリューム エンベロープと呼ばれる特殊なオーディオ エフェクトも提供している。タイムライン内の各オブジェクトが持つことができるボリューム エンベロープ エフェクトは、最大で 1 つである。他のエフェクトについては、このような制限はない。

    エフェクトまたはトランジション オブジェクトを作成したら、サブオブジェクトのクラス識別子 (CLSID) を使って IAMTimelineObj::SetSubObjectGUID を呼び出す。ユーザーのシステム上で使用可能なエフェクトとトランジションを列挙する方法については、「エフェクトおよびトランジションの列挙」を参照すること。

  3. 開始タイムと終了タイムを設定する。

    IAMTimelineObj::SetStartStop メソッドを呼び出して、親オブジェクト相対の開始タイムと終了タイムを設定する。

  4. プロパティを設定する。

    多数のエフェクトとトランジションが、カスタム プロパティをサポートしている。これらのプロパティの設定方法については、「エフェクトおよびトランジションのプロパティの設定」を参照すること。

  5. エフェクト オブジェクトまたはトランジション オブジェクトをタイムラインに挿入する。

    親オブジェクトの、次のいずれかのメソッドを呼び出す。

    • エフェクト : IAMTimelineEffectable::EffectInsBefore
    • トランジション : IAMTimelineTransable::TransAdd

    親オブジェクトは、複数のエフェクトおよびトランジションを持つことができる。エフェクトは同じオブジェクトに重ねて使用できるが、トランジションはそのような使い方はできない。各オブジェクトごとに、そのエフェクトが、優先順位に従って、優先順位ゼロから順にレンダリングされる (優先順位レベルは、EffectInsBefore を呼び出すときに指定する)。

次のサンプル コードでは、SMPTE ワイプトランジションをトラックに追加している。ここでは、トラックはすでに作成されているものとする。

// IAMTimeline *pTL;
// IAMTimelineTrack *pTrack;

// トランジション オブジェクトを作成する。
IAMTimelineObj *pTransObj = NULL;
hr = pTL->CreateEmptyNode(&pTransObj, TIMELINE_MAJOR_TYPE_TRANSITION);

// サブオブジェクトを設定する。
hr = pTransObj->SetSubObjectGUID(CLSID_DxtJpeg);  // SMPTE ワイプ

// 開始タイムと終了タイムを設定する。
hr = pTransObj->SetStartStop(0000000, 100000000);

// トランジション オブジェクトをタイムラインに挿入する。
IAMTimelineTransable *pTransable = NULL;
hr = pTrack->QueryInterface(IID_IAMTimelineTransable, (void **)&pTransable);
hr = pTransable->TransAdd(pTransObj);
hr = pTransObj->Release();

エフェクトおよびトランジションのプレビュー

一部のエフェクトおよびトランジションは、他と比べてレンダリングに時間がかかる。プレビュー中に、これが原因でビデオが乱れたり、オーディオとの同期がくずれることがある。エフェクトまたはトランジションを無効にすることにより、プレビューの速度を上げることができる。

  • すべてのエフェクトを無効にするには、IAMTimeline::EnableEffects を呼び出す。
  • すべてのトランジションを無効にするには、IAMTimeline::EnableTransitions を呼び出す。
  • 特定のトランジションを無効にするには、IAMTimelineTrans::SetCutsOnly を呼び出す。

エフェクトが無効になると、プレビュー時にエフェクトはレンダリングされない。トランジションが無効になると、トランジションは直接切り替えとしてレンダリングされる。それでもトラック間の切り替えは行われるが、ビジュアル エフェクトはレンダリングされない。

エフェクトまたはトランジションがレンダリングできない場合、レンダリング エンジンはデフォルトのエフェクトまたはトランジションに置き換える。デフォルト エフェクトの設定は IAMTimeline::SetDefaultEffect メソッドを呼び出して行い、デフォルトのトランジションの設定は IAMTimeline::SetDefaultTransition メソッドを呼び出して行う。デフォルトを指定していない場合、または指定した内容でエラーが発生した場合は、DES 自体のデフォルトが使用される。

注 : フレーム バッファの容量を大きくすることによっても、プレビューの品質を高めることができる。詳細については、「IAMTimelineGroup::SetOutputBuffering」を参照すること。

エフェクトおよびトランジションの列挙

DirectShow は、デバイスを列挙するためのシステム デバイス列挙子を提供している。これを使って、ユーザーのシステムにインストールされているエフェクトまたはトランジションのためのモニカを取得できる。

システム デバイス列挙子は、ICreateDevEnum インターフェイスを公開する。これは、指定されたデバイス カテゴリのためのカテゴリ列挙子を返す。カテゴリ列挙子は、IEnumMoniker インターフェイスを公開し、カテゴリ内の各デバイスのモニカを返す。ICreateDevEnem の使い方の詳細については、「デバイスとフィルタの列挙」を参照すること。以下に、DirectShow 編集サービスでの使い方の要約を示す。

エフェクトまたはトランジションを列挙するには、以下の手順を実行する。

  1. システム デバイス列挙子のインスタンスを作成する。
  2. ICreateDevEnum::CreateClassEnumerator メソッドを呼び出して、カテゴリ列挙子を取得する。カテゴリは、クラス識別子 (CLSID) によって定義されている。エフェクトの場合は CLSID_VideoEffects1Category、トランジションの場合は CLSID_VideoEffects2Category を使用する。
  3. IEnumMoniker::Next を呼び出して、列挙内の各モニカを取得する。
  4. 各モニカごとに IMoniker::BindToStorage を呼び出して、関連付けられているプロパティ バッグを取得する。
  5. プロパティ バッグには、そのエフェクトまたはトランジションのフレンドリ名とグローバル ユニーク識別子 (GUID) が入っている。アプリケーションでは、フレンドリ名のリストを表示でき、対応する GUID を取得できる。

次のサンプル コードは、以上の手順を示している。

ICreateDevEnum *pCreateDevEnum;
IEnumMoniker *pEm;
CoCreateInstance(CLSID_SystemDeviceEnum, NULL, CLSCTX_INPROC_SERVER,
        IID_ICreateDevEnum, (void**)&pCreateDevEnum);

pCreateDevEnum->CreateClassEnumerator(
        CLSID_VideoEffects1Category,  // エフェクトのカテゴリ。
        &pEnumMoniker, 0);            // トランジションに CLSID_VideoEffects2Category を使用する。

ULONG cFetched;
IMoniker *pMoniker;
while(S_OK == pEnumMoniker->Next(1, &pMoniker, &cFetched))
{
    HRESULT hr;
    IPropertyBag *pBag;
    hr = pMoniker->BindToStorage(0, 0, IID_IPropertyBag, (void **)&pBag);
    if(SUCCEEDED(hr))
    {
        VARIANT var;
        var.vt = VT_BSTR;
        hr = pBag->Read(L"FriendlyName", &var, NULL);
        if (SUCCEEDED(hr))
        {
            if ( ... )  // var.bstrVal が目的の名前かどうかチェックする。
            {
                VARIANT var2;
                GUID guid;
                pBag->Read(L"guid", &var2, NULL);
                GuidFromString(var2.bstrVal, &guid);
                SysFreeString(var2.bstrVal);
                // これで GUID はエフェクトの CLSID となる。
                break;
            }
            SysFreeString(var.bstrVal);
        }
        pBag->Release();
    }
    pMoniker->Release();
}
pEnumMoniker->Release();
pCreateDevEnum->Release();

エフェクトおよびトランジションのプロパティの設定

多数のエフェクトとトランジションで、その外観を制御するプロパティがサポートされている。たとえば、ボリューム エンベロープ エフェクトには、ボリューム レベルを指定するプロパティがある。アプリケーションでは、IPropertySetter インターフェイスを使用して、時間の範囲を越えてプロパティの値を設定できる。

プロパティを設定するには、以下の手順を実行する。

  1. プロパティ セッター (CLSID_PropertySetter) のインスタンスを作成する。
  2. DEXTER_PARAM および DEXTER_VALUE 構造体に、プロパティ データを設定する。この 2 つの構造体については後で説明する。
  3. DEXTER_PARAM および DEXTER_VALUE 構造体を IPropertySetter::AddProp メソッドに渡す。
  4. 設定する各プロパティごとに、手順 2 と 3 を繰り返す。
  5. IPropertySetter インターフェイス ポインタを IAMTimelineObj::SetPropertySetter メソッドに渡す。

DEXTER_PARAM 構造体は、設定対象のプロパティを指定する。以下のメンバがある。

  • Name : プロパティの名前
  • dispID : プロパティのディスパッチ識別子 (DISPID)
  • nValues : 値の個数

プロパティの DISPID がわかっている場合は、dispID メンバに設定する。通常、このメンバはゼロに設定し、Name メンバにプロパティの名前を設定する。

DEXTER_VALUE 構造体は、所定の時点でのプロパティの値を指定する。以下のメンバがある。

  • v : プロパティの新しい値を指定する VARIANT 型。この VARIANT の vt メンバは、プロパティのデータ型を定義する。VARIANT 型の詳細については、『Platform SDK』を参照すること。
  • rt : プロパティがこの値であると見なされる、エフェクトまたはトランジションの開始タイム相対の基準タイム。エフェクトまたはトランジションの開始タイムは、その親オブジェクトの開始タイム相対である。
  • dwInterp : プロパティが前の値から新しい値にどのように変化するかを指定するフラグ。DEXTERF_JUMP フラグの場合、プロパティは指定された時点で即座に新しい値に切り替わる。DEXTERF_INTERPOLATE フラグの場合、プロパティは前の値から線形的に補間される。

vt メンバを VT_BSTR に設定した場合、プロパティ セッターは必要な変換をすべて行う。浮動小数点値の場合には、小数点の前にゼロが含まれる。たとえば、.3 ではなく 0.3 となる。

プロパティの値は時間の経過に従って変化できるので、IPropertySetter::AddProp メソッドは単一の DEXTER_PARAM 構造体と、DEXTER_VALUE 構造体の配列へのポインタをパラメータにとる。この配列は、プロパティの時間に基づく値のセットを定義する。配列のメンバは、昇順の時系列に沿っていなければならず、DEXTER_PARAM 構造体の nValues メンバは配列の長さに等しくなければならない。

次のサンプル コードは、SMPTE ワイプトランジションのプロパティ データを作成する。ここではワイプ コードを 120 に設定し、これは長円ワイプを作成する。基準タイムは、トランジションの開始時を示すゼロに設定される。

IPropertySetter     *pProp;   // プロパティ セッター
IAMTimelineObj      *pTransObj;  // トランジション オブジェクト
// SMPTE ワイプトランジション オブジェクトを作成する  (ここには示されていない)

CoCreateInstance(CLSID_PropertySetter,
    NULL, CLSCTX_INPROC_SERVER,
    IID_IPropertySetter, (void**) &pProp);

DEXTER_PARAM param;
DEXTER_VALUE *pValue = (DEXTER_VALUE *)CoTaskMemAlloc(sizeof(DEXTER_VALUE));

// パラメータを初期化する。
param.Name = SysAllocString(L"MaskNum");
param.dispID = 0;
param.nValues = 1;

// 値を初期化する。
pValue->v.vt = VT_BSTR;
pValue->v.bstrVal = SysAllocString(L"120"); // 長円
pValue->rt = 0;
pValue->dwInterp = DEXTERF_JUMP;

pProp->AddProp(param, pValue);

// 割り当てられていたリソースを解放する。
SysFreeString(param.Name);
VariantClear(&(pValue->v));
CoTaskMemFree(pValue);

// トランジションのプロパティを設定する。
pTransObj->SetPropertySetter(pProp);
pProp->Release();

トランジションの方向

トランジションは入力 A から入力 B に向かって、タイム t0 から t1 までの間に行われる。したがって、トランジションの方向は、次の 2 つのいずれかを意味する。

  • タイムライン レイヤから入力へのマッピング。
  • 継続的な進行。

前者は入力方向であり、後者は進行方向である。この両方の方向を制御できる。

  • 入力方向 : デフォルトでは、トランジションは優先順位の低いレイヤの合成から、トランジションが含まれるレイヤに向かって行われる。この方向を逆にするには、IAMTimelineTrans::SetSwapInputs メソッドを呼び出す。
  • 進行方向 : ほとんどのトランジションは標準の Progress プロパティをサポートしている。このプロパティは、所定の時点で出力に反映されるトランジションの割合を指定する。デフォルトでは、Progress プロパティの値はトランジションの時間幅に対して 0.0 から 1.0 へと変化する。この進行を逆にするには、Progress プロパティが 1.0 から 0.0 へと変化するように設定する。

次の図は、入力方向と進行方向の違いを示している。ここでは、標準の SMPTE ワイプトランジションの 4 つのバリエーションが示されている。

トランジションはトラック 1 にある。デフォルトでは、ワイプは左から右に、トラック 0 から 1 に向かって行われる。入力を切り替えると、ワイプはトラック 1 から 0 に向かって行われるが、進行方向は左から右のままである。進行方向を逆にすると、トランジションは右から左へ向かって行われる。一番左に示されているように、この両方を組み合わせることができる。

DES がトランジションをレンダリングする方法については、「タイムライン モデル」を参照すること。


プロジェクトのレンダリング

ここでは、Microsoft® DirectShow® 編集サービス (DES) でビデオ編集プロジェクトをレンダリングする方法を説明している。以下のトピックが含まれる。

  • レンダリング エンジンについて
  • プロジェクトのプレビュー
  • ファイルへのプロジェクトの書き込み


レンダリング エンジンについて

ここでは、Microsoft DirectShow 編集サービス (DES) でどのようにビデオ編集プロジェクトがレンダリングされるかについて説明する。

DES では、プロジェクトはタイムラインとして表される。タイムラインは、ソース クリップの再配置やビデオ エフェクトの追加など、ビデオ編集で最も頻繁に行われるタスクを簡略化するために役立つ。一方、DirectShow ストリームのアーキテクチャでは、フィルタ グラフが必要である。そのため、プロジェクトをレンダリングするためには、タイムラインをフィルタ グラフに変換しなければならない。この操作を行うコンポーネントが、レンダリング エンジンと呼ばれる。DirectShow では、次の 2 つのレンダリング エンジンが提供される。

  • 基本レンダリング エンジン : 非圧縮出力を提供するフィルタ グラフを構築する。
  • スマート レンダリング エンジン : 圧縮出力を提供するフィルタ グラフを構築する。

スマート レンダリング エンジンは、スマート再圧縮を使って、パフォーマンスを向上させる。スマート再圧縮では、元のファイル フォーマットが最終的な出力フォーマットと異なる場合にだけ、ソース ファイルが再圧縮される。フォーマットが一致する場合は、ソース ファイルが再圧縮されることはない。スマート再圧縮は、ビデオ圧縮用だけにサポートされ、オーディオ圧縮用にはサポートされない。

プレビューには、基本レンダリング エンジンを使用する。スマート レンダリング エンジンでもプレビューはできるが、圧縮されたストリームを圧縮解除しなければならないので、効率が悪い。ファイルの書き込みには、スマート再圧縮が必要な場合にはスマート レンダリング エンジンを使用する。それ以外の場合は、基本レンダリング エンジンを使用する。スマート再圧縮を使うと、ファイルの書き込みに必要な時間が格段に減る。

重要 : ソース ファイルに ASF ファイルが含まれていて、目的のファイルが AVI ファイルである場合は、スマート レンダリング エンジンを使用しないこと。ファイルが正しく再生しない可能性がある。基本レンダリング エンジンを使うか、または ASF ファイルの書き込みを検討する。

フィルタ グラフの構築

フィルタ グラフは、2 段階で構築される。最初の段階では、レンダリング エンジンは "フロント エンド" を作成する。これは、フィルタ グラフの一部である。次の図は、一般的なフロント エンドを示している。

フィルタ グラフのフロント エンド

サブシステムには、さまざまな特殊フィルタが含まれている。これらのフィルタは、レンダリング エンジンが自動的に組み立てる。フロント エンドには、タイムラインの各グループごとに 1 つの出力ピンが含まれている。基本レンダリング エンジンを使用する場合、出力ピンは非圧縮データを出力し、スマート レンダリング エンジンを使用する場合は圧縮データを出力する。

2 つ目の段階では、出力ピンがレンダリング フィルタに接続される。プレビューでは、レンダリング フィルタはビデオ レンダラおよびオーディオ レンダラとなる。ファイルの書き込みでは、レンダリング フィルタはマルチプレクサ (mux) フィルタおよびファイル ライタ フィルタとなる。

参照

  • プロジェクトのプレビュー
  • ファイルへのプロジェクトの書き込み


プロジェクトのプレビュー

プロジェクトをプレビューするには、CoCreateInstance 関数を呼び出して、基本レンダリング エンジンのインスタンスを作成する。クラス識別子は、CLSID_RenderEngine である。次に、レンダリング エンジンの IRenderEngine インターフェイスで、次のメソッドを呼び出す。

  • SetTimelineObject 使用するタイムラインを指定する。
  • ConnectFrontEnd グラフのフロント エンドを構築する。
  • RenderOutputPins 各出力ピンをビデオ レンダラまたはオーディオ レンダラに接続して、プレビュー グラフを完了する。

次のサンプル コードは、これらのステップを示している。

IRenderEngine *pRender = NULL;
hr = CoCreateInstance(CLSID_RenderEngine, NULL,
    CLSCTX_INPROC_SERVER, IID_IRenderEngine, (void**) &pRender);

hr = pRender->SetTimelineObject(pTL);
hr = pRender->ConnectFrontEnd( );
hr = pRender->RenderOutputPins( );

これで、フィルタ グラフを実行できるようになる。IRenderEngine::GetFilterGraph メソッドを呼び出して、グラフへのポインタを入手する。次のサンプル コードに示すように、IMediaControl インターフェイスについてグラフに照会し、IMediaControl::Run を呼び出す。

IGraphBuilder   *pGraph = NULL;
IMediaControl   *pControl = NULL;

hr = pRender->GetFilterGraph(&pGraph);
hr = pGraph->QueryInterface(IID_IMediaControl, (void **)&pControl);
hr = pControl->Run();

プロジェクト ファイルを読み込んでプレビューする完全な例については、「プロジェクトのロードとプレビュー」を参照すること。


ファイルへのプロジェクトの書き込み

ここでは、ビデオ編集プロジェクトをファイルに書き込む方法について説明する。最初に、基本レンダリング エンジンを使ってファイルを書き込む方法について説明する。次に、スマート レンダリング エンジンを使ったスマート再圧縮について説明する。ここには、次のトピックが含まれている。

  • 基本レンダリング エンジンの使用
  • スマート レンダリング エンジンの使用

Microsoft® DirectShow® 編集サービスでのプロジェクトのレンダリング概要については、「レンダリング エンジンについて」を参照すること。

基本レンダリング エンジンの使用

次のように、グラフのフロント エンドを最初に構築する。

  1. レンダリング エンジンを作成する。
  2. タイムラインを指定する。
  3. グラフのフロント エンドを構築する。

次のサンプル コードは、そのステップを示している。

IRenderEngine *pRender = NULL;
hr = CoCreateInstance(CLSID_RenderEngine, NULL, CLSCTX_INPROC,
    IID_IRenderEngine, (void**) &pRender);

hr = pRender->SetTimelineObject(pTL);
hr = pRender->ConnectFrontEnd( );

次に、フィルタ グラフにマルチプレクサおよびファイル ライタ フィルタを追加する。その最も簡単な方法は、キャプチャ グラフを構築するための DirectShow コンポーネントであるキャプチャ グラフ ビルダを書くことである。キャプチャ グラフ ビルダは、ICaptureGraphBuilder2 インターフェイスを公開する。次のステップを実行する。

  1. キャプチャ グラフ ビルダのインスタンスを作成する。
  2. グラフへのポインタを取得し、グラフ ビルダに渡す。
  3. 出力ファイルの名前とメディア タイプを指定する。このステップによって、後で必要になる mux フィルタへのポインタも取得される。

次のサンプル コードは、このステップを示している。

CoCreateInstance(CLSID_CaptureGraphBuilder2, NULL, CLSCTX_INPROC,
    IID_ICaptureGraphBuilder2, (void **)&pBuilder);

// グラフのフロント エンドへのポインタを取得する。
IGraphBuilder *pGraph;
pRender->GetFilterGraph(&pGraph);
pBuilder->SetFiltergraph(pGraph);

// ファイルの書き込みセクションを作成する。
IBaseFilter *pMux;
pBuilder->SetOutputFileName(&MEDIASUBTYPE_Avi, L"Output.avi", &pMux, NULL);

最後に、mux フィルタにフロント エンドの出力ピンを接続する。

  1. グループ数を取得する。
  2. 各ピンごとに、ピンへのポインタを取得する。
  3. オプションで、圧縮フィルタのインスタンスを作成し、ストリームを圧縮する。コンプレッサのタイプは、グループのメディア タイプによって異なる。システム デバイス列挙子を使って、利用可能な圧縮フィルタを列挙できる。詳細については、「デバイスとフィルタの列挙」を参照すること。
  4. オプションで、キー フレーム レートなどの圧縮パラメータを設定する。このステップについては、後で詳細に説明する。
  5. ICaptureGraphBuilder2::RenderStream を呼び出す。このメソッドは、ピン、圧縮 フィルタ (ある場合)、およびマルチプレクサにポインタを移動する。

次のサンプル コードは、出力ピンの接続方法を示している。

long NumGroups;
pTimeline->GetGroupCount(&NumGroups);

// グループをループし、出力ピンを取得する。
for (i = 0; i < NumGroups; i++)
{
    IPin *pPin;
    if (pRender->GetGroupOutputPin(i, &pPin) == S_OK)
    {
        IBaseFilter *pCompressor;
        // コンプレッサ フィルタを作成する (示されない)。
        // 圧縮パラメータを設定する (示されない)。

        // ピンを接続する。
        pBuilder->RenderStream(NULL, NULL, pPin, pCompressor, pMux);
        pCompressor->Release();
        pPin->Release();
    }
}

圧縮パラメータを設定する (前のステップ 4) には、IAMVideoCompression インターフェイスを使用する。このインターフェイスは、圧縮フィルタの出力ピンに公開される。圧縮フィルタのピンを列挙し、IAMVideoCompression について各出力ピンに照会する。ピン列挙の詳細については、「ピンの列挙」を参照すること。このステップにおいて取得したすべてのインターフェイス ポインタは、必ず解放する。

フィルタ グラフを構築した後は、フィルタ グラフ マネージャで IMediaControl::Run メソッドを呼び出す。フィルタ グラフは、実行されるとファイルにデータを書き込む。イベント通知を使って、再生が完了するのを待つ。詳細については、「イベントへの応答」を参照すること。再生が終了したら、IMediaControl::Stop を明示的に呼び出して、フィルタ グラフを停止しなければならない。このようにしないと、ファイルは正しく書き込まれない。

スマート レンダリング エンジンの使用

スマート再圧縮の利点を得るためには、基本レンダリング エンジンの代わりにスマート レンダリング エンジンを使用する。グラフの構築ステップは、おおよそ同じである。主な違いは、ファイルの書き込みセクションではなく、グラフのフロント エンドで圧縮が行われることである。

各ビデオ グループには、そのグループの圧縮フォーマットを指定するプロパティがある。圧縮フォーマットは、高さ、幅、ビット数、およびフレーム レートについて、グループの非圧縮フォーマットに完全に一致しなければならない。スマート レンダリング エンジンは、グラフ構築の際に圧縮フォーマットを使用する。圧縮フォーマットを設定する前に、必ず IAMTimelineGroup::SetMediaType を呼び出して、そのグループに非圧縮フォーマットを指定する。

グループの圧縮フォーマットを設定するには、IAMTimelineGroup::SetSmartRecompressFormat メソッドを呼び出す。このメソッドは、ポインタを SCompFmt0 構造体に移動する。この構造体には 2 つのメンバがある。1 つは nFormatId であり、このメンバはゼロでなくてはならない。もう 1 つは MediaType であり、これは AM_MEDIA_TYPE 構造体である。フォーマット情報を使って AM_MEDIA_TYPE 構造体を初期化する。

注 : 最終的なプロジェクトがソース ファイルの 1 つと同じフォーマットを持つようにするには、メディア ディテクタを使ってソース ファイルから直接 AM_MEDIA_TYPE 構造体を取得できる。詳細については、「IMediaDet::get_StreamMediaType」を参照すること。

次のサンプル コードに示すように、SCompFmt0 変数を long 型のポインタにキャストする。

SCompFmt0 *pFormat = new SCompFmt0;
memset(pFormat, 0, sizeof(SCompFmt0));
pFormat->nFormatId = 0;

// pFormat->MediaType を初期化する (示されない)。

pGroup->SetSmartRecompressFormat( (long*) pFormat );

スマート レンダリング エンジンは、自動的に互換性のある圧縮フィルタを検索する。ISmartRenderEngine::SetGroupCompressor を呼び出しても、グループの圧縮フィルタを指定できる。

グラフの構築

グラフを構築するには、「基本レンダリング エンジンの使用」で説明したのと同じステップを使う。その違いは、次に示すものだけである。

  • 基本レンダリング エンジンではなく、スマート レンダリング エンジンを使用する。クラス識別子は CLSID_SmartRenderEngine である。
  • フロント エンドの構築後には圧縮パラメータを設定するが、出力ピンをレンダリングする前に行う。ISmartRenderEngine::GetGroupCompressor メソッドを呼び出し、グループの圧縮フィルタへのポインタを取得する。次に、前に説明したように IAMVideoCompression インターフェイスについて照会する。
  • 出力ピンをレンダリングする際には、圧縮フィルタを挿入する必要はない。ストリームは、既に圧縮されている。


エラーのログ

Microsoft® DirectShow® 編集サービス (DES) では、DES プロジェクトの読み込み、構築、またはレンダリング時に発生するエラーを、ログに記録するための組み込みメカニズムが提供される。ここでは、XML プロジェクト ファイルを読み込んでレンダリングを試みるサンプル コンソール アプリケーションについて説明する。エラーが起きた場合、このアプリケーションはエラー メッセージをコンソール ウィンドウに表示する。ここで紹介するサンプル コードは、「プロジェクトのロードとプレビュー」に示された例に基づいて構築されている。

注 : ユーザー アプリケーションでは、エラー ログを実装する必要はない。DES は、明示的に要求しなければエラーをログに記録しない。

ここでは、ユーザーが COM クライアント プログラミングおよび DES タイムライン モデルについて理解していることを想定している。また、ユーザーは COM オブジェクト プログラミングの基本事項を理解している必要がある。DES におけるタイムラインの詳細については、「タイムライン モデル」を参照すること。

ここには以下のセクションが含まれる。

  • エラー ログの概要
  • エラー ログ クラスの作成
  • IAMErrorLog の実装
  • エラー ログの設定
  • サンプル コード

エラー ログの概要

エラー処理に関して最大の柔軟性をアプリケーションに与えるために、DES はコールバック メカニズムを使用している。ユーザー アプリケーションでは、エラー ログをとるためのメソッドを実装する。実行時にエラーが発生した場合、DES はユーザーによって提供されたメソッドを呼び出す。このメソッドは、エラーの詳細を示すパラメータをとる。メソッドがこの情報をどのように処理するかはプログラマに任せられる。ただし、プログラムの実行を妨害する可能性があるので、可能な限り早く復帰する必要がある。

エラーをログに記録するコールバック メソッドは、COM インターフェイス IAMErrorLog に含まれている。ユーザー アプリケーションは、このインターフェイスを実装しなければならない。すべての COM インターフェイスと同様に、IAMErrorLog は IUnknown インターフェイスを継承するので、ユーザー アプリケーションは、このインターフェイスも実装しなければならない。

これらの COM インターフェイスの実装には、いくつかの方法が選択できる。IUnknown メソッドの標準の実装を提供する、Active Template Library (ATL) を使用できる。DirectShow は C++ 基底クラス CUnknown も提供しており、これによって COM インターフェイスの実装が容易になる。CUnknown の使い方については、「IUnknown の実装方法」を参照すること。

後のサンプル コードでは、コード内に含まれる C++ クラスを定義している。このクラスは、IUnknown と IAMErrorLog の両方を実装する。ただし、CoCreateInstance をサポートしていないため、真の COM オブジェクトは生成されない。しかし、この手法は、サンプル コードの目的としては妥当なものである。

エラー ログ クラスの作成

最初に、エラー ログ記録を実装するクラスを宣言する。このクラスは、IAMErrorLog インターフェイスを継承する。これには、3 つの IUnknown メソッドと、IAMErrorLog の 1 つのメソッドの宣言が含まれる。このクラスの宣言を次に示す。

class CErrReporter : public IAMErrorLog
{
protected:
    long    m_lRef; // Reference count.

public:
    CErrReporter() { m_lRef = 0; }

    // IUnknown
    STDMETHOD(QueryInterface(REFIID, void**));
    STDMETHOD_(ULONG, AddRef());
    STDMETHOD_(ULONG, Release());

    // IAMErrorLog
    STDMETHOD(LogError(LONG, BSTR, LONG, HRESULT, VARIANT*));
};

このクラスの唯一のメンバ変数は、オブジェクトの参照カウントを保持する _lRef である。

次に、IUnknown のメソッドを定義する。詳細については、後のサンプル コードを参照すること。これで、COM フレームワークを使うことにより IAMErrorLog インターフェイスを実装することができる。以下では、その方法を説明している。

IAMErrorLog の実装

IAMErrorLog インターフェイスには、単一のメソッド LogError がある。このメソッドのパラメータには、発生したエラーに関する情報が含まれる。

STDMETHODIMP LogError(
    LONG Severity,                   // 予約済み。使用しないこと。
    BSTR ErrorString,                // 詳細。
    LONG ErrorCode,                  // エラー コード。
    HRESULT hresult,                 // エラーを発生させた HRESULT。
    VARIANT *pExtraInfo);            // エラーに関する追加情報。

エラー コードとエラー文字列は、DirectShow 編集サービスで定義されている。エラーの一覧については、「レンダリング エラー」を参照すること。

パラメータ pExtraInfo には、エラーに関する追加情報を保持する VARIANT 型へのポインタが入る。この VARIANT 型のデータ型と内容は、発生した個々のエラーによって異なる。

たとえば、不正なファイル名によってエラーが発生した場合、VARIANT は不正なファイル名の文字列となる。エラーには追加情報がないものがあるので、pExtraInfo が NULL であることもある。次のコードは、この VARIANT の vt メンバをテストする方法を示している。このメンバは、データ型を指定し、それに応じてメッセージの書式を設定する。

if( pExtraInfo )    // もしあれば、追加情報をレポートする。
{
    printf("\tExtra info: ");
    if( pExtraInfo->vt == VT_BSTR )      // 追加情報は BSTR である。
    {
        char szExtra[256];
        WideCharToMultiByte(CP_ACP, 0, pExtraInfo->bstrVal, -1, szExtra, 256, 0, 0);
        printf("%s\n", szExtra);
    }
    else if( pExtraInfo->vt == VT_I4 )   // 追加情報は整数である。
        printf("%d\n", pExtraInfo->lVal);

    else if( pExtraInfo->vt == VT_R8 )   // 追加情報は浮動小数点である。
        printf("%f\n", pExtraInfo->dblVal);
}

注 : pExtraInfo が指す VARIANT を解放してはならない。また、VARIANT はメソッドが復帰した後は無効になるので、後で参照してはならない。

エラー ログの設定

エラー ログ クラスを実装したら、そのクラスの新しいインスタンスを作成する。次に、タイムライン上で IAMSetErrorLog::put_ErrorLog メソッドを呼び出すことにより、そのインスタンスを指すポインタを DES に与える。タイムラインに IAMSetErrorLog インターフェイスについて照会する。すべてのエラーがログに記録されるようにするには、タイムラインの読み込み、保存、およびレンダリングを行う前に、このメソッドを呼び出す必要がある。

IAMSetErrorLog  *pSetLog = NULL;
IAMErrorLog     *pLog = new CErrReporter();

pTL->QueryInterface(IID_IAMSetErrorLog, (void **)&pSetLog);
pSetLog->put_ErrorLog(pLog);
pSetLog->Release();

エラー ログによって、アプリケーションでメソッドを呼び出すときに受け取る戻り値には影響はない。エラー ログは、通常のエラー処理手法を補完するが、置き換えるわけではない。堅牢なアプリケーションを作成するためには、常に HRESULT 値をチェックしなければならない。

サンプル コード

次のサンプル コードは、ここで説明したエラー ログ クラスを使用し、XML プロジェクト ファイルを読み込んでプレビューする、完全なコンソール アプリケーションである。プロジェクト ファイルの名前は、アプリケーションにハード コーディングされる。

コードを簡潔にするため、コンソール アプリケーションは ATL スマート ポインタを使用する。これによって、QueryInterface と Release を呼び出さなくても済む。必要な場合は、「プロジェクトのロードとプレビュー」でサンプル アプリケーションを変更できる。前に示したコードを追加するだけでよい。

#include <atlbase.h>
#include <dshow.h>
#include <qedit.h>
#include <stdio.h>

// エラー ログ クラス
class CErrReporter : public IAMErrorLog
{
protected:
    long    m_lRef; // Reference count.

public:
    CErrReporter() { m_lRef = 0; }

    // IUnknown
    STDMETHOD(QueryInterface(REFIID, void**));
    STDMETHOD_(ULONG, AddRef());
    STDMETHOD_(ULONG, Release());

    // IAMErrorLog
    STDMETHOD(LogError(LONG, BSTR, LONG, HRESULT, VARIANT*));
};

STDMETHODIMP CErrReporter::QueryInterface(REFIID riid, void **ppv)
{
    if (ppv == NULL)
        return E_POINTER;
    *ppv = NULL;

    if (riid == IID_IUnknown)
        *ppv = (IUnknown*)this;
    else if (riid == IID_IAMErrorLog)
        *ppv = (IAMErrorLog*)this;

    if (*ppv)
    {
        AddRef();
        return S_OK;
    }
    return E_NOINTERFACE;
}

STDMETHODIMP_(ULONG) CErrReporter::AddRef()
{
    return InterlockedIncrement(&m_lRef);
}

STDMETHODIMP_(ULONG) CErrReporter::Release()
{
    if (InterlockedDecrement(&m_lRef) == 0)
    {
        delete this;
        return 0;
    }
    return m_lRef;
}

STDMETHODIMP CErrReporter::LogError(
        LONG Severity,
        BSTR ErrorString,
        LONG ErrorCode,
        HRESULT hresult,
        VARIANT *pExtraInfo)
{
    char szError[256];
    WideCharToMultiByte(CP_ACP, 0, ErrorString, -1, szError, 256, 0, 0);
    printf("Error %d: %s\n", ErrorCode, szError);

    if( pExtraInfo )    // もしあれば、追加情報をレポートする。
    {
        printf("\tExtra info: ");
        if( pExtraInfo->vt == VT_BSTR )      // 追加情報は BSTR である。
        {
            char szExtra[256];
            WideCharToMultiByte(CP_ACP, 0, pExtraInfo->bstrVal, -1, szExtra, 256, 0, 0);
            printf("%s\n", szExtra);
        }
        else if( pExtraInfo->vt == VT_I4 )   // 追加情報は整数である。
            printf("%d\n", pExtraInfo->lVal);

        else if( pExtraInfo->vt == VT_R8 )   // 追加情報は浮動小数点である。
            printf("%f\n", pExtraInfo->dblVal);
    }
    return hresult;
};

void __cdecl main(void)
{
    CoInitialize(NULL);
    {
    HRESULT hr;
    CComPtr< IAMTimeline >   pTL;
    CComPtr< IRenderEngine > pRenderEngine;
    CComPtr< IXml2Dex >      pXML;
    CComPtr< IGraphBuilder > pGraph;

    hr = CoCreateInstance(CLSID_AMTimeline, NULL, CLSCTX_INPROC_SERVER,
                IID_IAMTimeline, (void**) &pTL);

    hr = CoCreateInstance(CLSID_Xml2Dex, NULL, CLSCTX_INPROC_SERVER,
                IID_IXml2Dex, (void**) &pXML);

    hr = CoCreateInstance(CLSID_RenderEngine, NULL, CLSCTX_INPROC_SERVER,
                IID_IRenderEngine, (void**) &pRenderEngine);

    // エラー ログを設定する。
    CComQIPtr<IAMSetErrorLog, &IID_IAMSetErrorLog> pSetLog(pTL);
    if (pSetLog)
    {
        IAMErrorLog *pLog = new CErrReporter;
        pSetLog->put_ErrorLog(pLog);
    }

    // プロジェクトを読み込んでプレビューする。
    hr = pXML->ReadXMLFile(pTL, L"C:\\Example.xtl");
    if (SUCCEEDED(hr))
    {
        hr = pRenderEngine->SetTimelineObject(pTL);
        hr = pRenderEngine->ConnectFrontEnd( );
        hr = pRenderEngine->RenderOutputPins( );
        hr = pRenderEngine->GetFilterGraph(&pGraph);

        CComQIPtr<IMediaControl, &IID_IMediaControl> pControl(pGraph);
        CComQIPtr<IMediaEvent, &IID_IMediaEvent> pEvent(pGraph);
        pControl->Run();

        long evCode;
        hr = pEvent->WaitForCompletion(INFINITE, &evCode);
        pControl->Stop();
    }
    // クリーン アップする。
    pRenderEngine->ScrapIt();
    }
    CoUninitialize();
}


ビデオ編集プロジェクトの管理

ここでは、Microsoft® DirectShow® 編集サービスでのプロジェクト管理に役立つヒントを示す。

タイムラインへの変更

  • フィルタ グラフを構築した後にタイムラインを変更する場合は、もう一度 IRenderEngine::ConnectFrontEnd を呼び出して、フロント エンドを再構築する。通常、グラフのほかの部分には影響はない。レンダリング エンジンがフロント エンドを再構築する前には、グラフ全体を削除しなければならないことがある。たとえば、グループの追加や削除の場合などである。ConnectFrontEnd メソッドは、S_WARN_OUTPUTRESET を返し、グラフを削除したことを通知する。この場合、アプリケーションはグラフのレンダリング部分を再構築しなければならない。
  • タイムラインからすべてのオブジェクトを完全に削除するには、IAMTimeline::ClearAllGroups メソッドを呼び出す。

クリーン アップ

  • レンダリング エンジンの使用を終了したら、IRenderEngine::ScrapIt メソッドを呼び出す。ほかの COM オブジェクトと同じように、使用を終了したら各インターフェイス ポインタを必ず解放する。
  • レンダリング エンジンは、タイムライン上に参照カウントを保持しない。使用を終了する前にタイムラインを解放してはならず、必ず最初にレンダリング エンジン上で ScrapIt を呼び出す。
  • タイムラインへのすべての参照を解放する際は、たとえタイムライン上に参照カウントを保持していたとしても、タイムラインのいずれのオブジェクトも使ってはならない。

複数のインスタンス

  • タイムライン間でタイムライン オブジェクトを移動してはならない。タイムラインのすべてのオブジェクトは、そのタイムラインによって作成される必要がある。タイムラインは、タイムラインが作成するオブジェクトに関する情報を内部キャッシュに保持している。タイムライン オブジェクトを移動すると、このキャッシュを破壊する可能性がある。
  • 複数のタイムラインを持つレンダリング エンジンの同じインスタンスは、決して使ってはならない。レンダリング エンジンは、タイムラインに関する情報をキャッシュに保持している。複数のタイムラインがあると、キャッシュが破壊され、予期しない結果が発生する。2 つのアクティブなタイムラインが必要な場合は、タイムラインごとにレンダリング エンジンの別のインスタンスを作成する。
  • タイムラインは、複数のレンダリング エンジンを使うことができるが、同時に使うことはできない。古いレンダリング エンジンを削除してから、新しいレンダリング エンジンを使用する。たとえば、プレビューのために基本レンダリング エンジンを使ってから、ファイルの書き込みのためにスマート レンダリング エンジンに切り替える場合である。

永続性

  • プロジェクトを XML ファイルに保存する際に、フィルタ グラフは永続的ではない。そのため、スマート再圧縮、圧縮フォーマット、および圧縮パラメータに関連した情報が失われる。プロジェクトを読み込んだ後にこれらのパラメータを復元するかどうかは、アプリケーション独自に決定する。


アルファ ブレンディング

ここでは、Microsoft® DirectShow® 編集サービス (DES) でアルファ ブレンディングを実行する方法について説明する。

アルファは、ピクセルまたはイメージの透明度を示す。32 ビット非圧縮 RGB ビデオでは、アルファ チャンネル (A) および 3 つのカラー コンポーネント (RGB) から成る、4 つのコンポーネントによって各ピクセルが定義される。アルファ値がゼロのピクセルは完全に透明であり、アルファ値が 255 のピクセルは不透明である。ピクセルは、これらの値の間のさまざまな透明度を持つ。

DirectShow では、32 ビット RGB ビデオ用に次の 2 つのメディア タイプが定義される。

  • MEDIASUBTYPE_ARGB32 : このビデオは、有効なアルファ チャンネルを持つ 32 ビット RGB である。
  • MEDIASUBTYPE_RGB32 : ピクセルは 32 ビットであるが、アルファ チャンネルは必ずしも有効ではない。

DES でアルファ ブレンディングを使うには、最初にグループの非圧縮メディア タイプを MEDIASUBTYPE_ARGB32 に設定する。C++ では、IAMTimelineGroup::SetMediaType メソッドを呼び出す。XTL フォーマットでは、GROUP 要素の BITDEPTH 属性を 32 に設定しても、アルファ ブレンディングを使用できる。詳細については、「XML リファレンス」を参照すること。

次に、アルファ チャンネルが含まれたビデオ データが必要である。そのためには、次のようないくつかのオプションがある。

  • 既にアルファ データと 32 ビット RGB ビデオを持っている AVI ファイルを使用できる。現在、アルファは MPEG または Microsoft® Windows Media™ Format (WMF) のソース ファイルではサポートされていない。
  • DES は、アルファ データを持つ 32 ビット ビットマップ (.bmp) および Targa (.tga) ファイルをサポートしている。
  • アルファを持つ 32 ビット RGB を作成する、カスタム ソース ファイルを書くことができる。出力メディア タイプは、MEDIASUBTYPE_ARGB32 でなくてはならない。タイムライン ソース オブジェクトで、フィルタをサブオブジェクトとして使う。詳細については、「サブオブジェクト」を参照すること。

ビデオ ソースにアルファがない場合は、アルファ データを作成するエフェクトを使用できる。アルファ セッター エフェクトを使うと、イメージ全体のアルファ チャンネルを定数値に設定できる。時間と共にアルファが変化するようにするには、IPropertySetter インターフェイスを使用する。グループの非圧縮メディア タイプが MEDIASUBTYPE_ARGB32 である限り、元のソースは 32 ビットである必要はない。また、アルファ データを作成する、ユーザー独自の Microsoft® DirectX® 変換エフェクトを作成することもできる。

注 : アルファ データが既にビデオ ソースに含まれている場合は、アルファ セッター エフェクトを使って、指定する割合で各ピクセルのアルファ値を変更できる。詳細については、「アルファ セッター」を参照すること。

最後に、アルファ ブレンディングを実行するエフェクトまたはトランジションにビデオを渡す。コンポジタ トランジションおよび SMPTE ワイプ トランジションは、どちらもアルファ ブレンディングを実行する。キー トランジションは、アルファ値によってキーイングできる。サードパーティーの DirectX 変換オブジェクトにも、アルファ ブレンディングをサポートするものがある。

次のサンプル XTL プロジェクトでは、アルファ ブレンディングを実行している。

<TIMELINE>
<GROUP TYPE="video" BITDEPTH="32" WIDTH="320" HEIGHT="240">

<TRACK>
  <CLIP START="0" STOP="6" SRC="c:\Example.avi" />
</TRACK>

<TRACK>
  <CLIP START="0" STOP="6" SRC="c:\Example2.avi">

    <!-- アルファ セッター エフェクト -->
    <EFFECT CLSID="{506D89AE-909A-44f7-9444-ABD575896E35}" START="0" STOP="6">
      <PARAM NAME="alpha" VALUE="255">
        <LINEAR TIME="6" VALUE="0" />
      </PARAM>
    </EFFECT>

  </CLIP>

  <!-- アルファ キーイングを使ったキー トランジション -->
  <TRANSITION CLSID="{C5B19592-145E-11d3-9F04-006008039E37}" START="0" STOP="6">
    <PARAM NAME="KeyType" VALUE="3" />
  </TRANSITION>
</TRACK>


カットリストのタイムラインへの変換

ここでは、既存のカットリスト アプリケーションを Microsoft® DirectShow® 編集サービス (DES) に変換する方法について説明する。

カットリストは、DirectShow の以前のバージョンの機能であり、非線形編集のために制限付きサポートを提供した。Microsoft® DirectX® 8.0 では、カットリストはサポートされていない。DES での機能から機能の変換は、簡単に実装できる必要がある。これには、少なくとも次のような利点がある。

  • 異種ソースのサポート
  • 圧縮ソースのサポート
  • フレーム レートの自動変換
  • ビデオをフレーム全体にストレッチしたり、レターボックスを作成するサポート
  • スロー モーションおよび高速モーションのオーディオとビデオのサポート
  • オーディオ ギャップ (無音) のより良いサポート

カットリストから移行すると、プロジェクトの永続性、複数のトラック、エフェクト、トランジション、ポスター フレームの合成などの機能を追加できる。

標準的なカットリスト アプリケーションは、次のようなステップを実行する。

  1. ビデオ ストリームおよびオーディオ ストリーム用に異なるカットリスト (IStandardCutList) を作成する。
  2. 各ソース ファイル用に、ビデオ ファイル クリップ、オーディオ ファイル クリップ、またはその両方 (IFileClip) を作成する。
  3. 各ファイル クリップから、1 つまたは複数のカット (IAMCutListElement) を作成し、カットリストに追加する。
  4. カットリスト グラフ ビルダ (ICutListGraphBuilder) を作成する。
  5. 各カットリストをカットリスト グラフ ビルダに追加する。
  6. オプションで、出力ファイル名を設定する。
  7. グラフをレンダリング、再生する。

次に示すのは、DES での同様のステップである。

  1. タイムライン (IAMTimeline) を作成する。
  2. 最終的なプロダクションで、各ビデオ ストリームおよびオーディオ ストリーム用に 1 つのグループ (IAMTimelineGroup) を作成する。
  3. 1 つまたは複数のトラック (IAMTimelineTrack) を各グループに追加する。
  4. ソース オブジェクト (IAMTimelineSrc) を作成し、トラックに追加する。
  5. レンダリング エンジン (IRenderEngine) を作成する。
  6. レンダリング エンジンにタイムラインを追加する。
  7. グラフをレンダリング、再生する。

次に示すのは、その主な違いである。

ファイル クリップ : DES では、ファイル クリップに相当するオブジェクトはない。ソース オブジェクトは、おおよそカットに相当する。カットでは、複数のソース オブジェクトが同じソース ファイルを参照できる。

メディア タイプ : カットリストでは、オーディオとビデオ用に 2 つの明確なファイル クリップ オブジェクトがあり、それぞれに独自のクラス識別子がある。DES では、グループのメディア タイプによってソース オブジェクトのメディア タイプが決定される。

ファイル出力 : DES には、ICutListGraphBuilder::SetOutputFileName メソッドに直接相当するものがない。DES ではファイル出力がいくらか複雑になっているが、フォーマットと圧縮タイプについては、格段に制御が向上している。詳細については、「ファイルへのプロジェクトの書き込み」を参照すること。

プロジェクトの変更 : カットリストでは新しいカットを追加できるが、カットの変更や削除はできない。DES では、ソース オブジェクトの追加、削除、再配置、または変更ができる。詳細については、「ビデオ編集プロジェクトの管理」を参照すること。


DirectShow 編集サービス リファレンス

このセクションには、Microsoft® DirectShow® 編集サービスのリファレンス情報がすべて含まれている。リファレンス情報は、以下のように分類されている。

  • インターフェイス
  • 構造体
  • 列挙型
  • 定数
  • トランジションおよびエフェクト
  • DirectShow 編集サービスのコンポーネント
  • XML リファレンス
  • レンダリング エラー


インターフェイス

このセクションには、Microsoft® DirectShow® 編集サービスのすべての COM インターフェイスおよびそのメソッドのリファレンス情報が含まれている。

  • IAMErrorLog
  • IAMSetErrorLog
  • IAMTimeline
  • IAMTimelineComp
  • IAMTimelineEffect
  • IAMTimelineEffectable
  • IAMTimelineGroup
  • IAMTimelineObj
  • IAMTimelineSplittable
  • IAMTimelineSrc
  • IAMTimelineTrack
  • IAMTimelineTrans
  • IAMTimelineTransable
  • IAMTimelineVirtualTrack
  • IFindCompressorCB
  • IMediaDet
  • IMediaLocator
  • IPropertySetter
  • IRenderEngine
  • ISmartRenderEngine
  • IXml2Dex


IAMErrorLog インターフェイス

Microsoft® DirectShow® 編集サービス (DES) におけるエラー ログのためのコールバック メソッドを提供する。

DES は、このインターフェイスを実装していない。エラー ログをとるためには、アプリケーションでこのインターフェイスを実装し、タイムラインで IAMSetErrorLog::put_ErrorLog を呼び出す。プロジェクトをレンダリングするときにエラーが発生した場合、DES はアプリケーションによって実装された IAMErrorLog::LogError メソッドを呼び出す。

DES がエラー をログに記録するのは、IRenderEngine インターフェイスを使ってプロジェクトをレンダリングするときのみである。たとえば、プロジェクトを DirectShow フィルタ グラフ (.grf フォーマット) として保存し、そのグラフ ファイルを再生する場合には、エラー ログは行われない。

このインターフェイスの使い方の詳細については、「エラーのログ」を参照すること。

要件

Qedit.h が必要である。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMErrorLog メソッド | 説明
LogError | エラーをログに記録する。

IAMErrorLog::LogError

IAMErrorLog インターフェイス

エラーをログに記録する。アプリケーションでこのメソッドを呼び出す必要はない。このメソッドは、レンダリング エラーへの応答において内部的に呼び出される。

構文

HRESULT LogError(
    LONG Severity,
    BSTR ErrorString,
    LONG ErrorCode,
    HRESULT hresult,
    VARIANT *pExtraInfo
);

パラメータ

Severity
予約済み。使用してはならない。
ErrorString
エラーのテキストを含む文字列値。
ErrorCode
エラー コード。
hresult
エラーを引き起こしたメソッド呼び出しで返された HRESULT 値。
pExtraInfo
[in] エラーに関する追加情報が含まれる VARIANT 型へのポインタ。

戻り値

HRESULT 値を返す。hresult パラメータの値を返す。

注意

このメソッドの中で、pExtraInfo が指す VARIANT を解放してはならない。また、VARIANT はメソッドが復帰した後は無効になるので、後で参照してはならない。

このメソッドの実装では、可能な限り早く復帰するようにする。このメソッドの中で、プログラムの実行を差し止めるような関数呼び出しをしてはならない。たとえば、メッセージの送信、イベントの差し止めなど、実行の妨げとなる Microsoft® Win32® 関数を呼び出してはならない。そうしたことを行うと、コンピュータが応答を停止したり、"ハング" することがある。

DES で定義されているエラーの一覧、および pExtraInfo が指す VARIANT の意味とデータ型については、「レンダリング エラー」を参照すること。


IAMSetErrorLog インターフェイス

Microsoft® DirectShow® 編集サービス (DES) のエラー ログを取得する。タイムライン オブジェクトは、このインターフェイスを実装している。アプリケーションでは、このインターフェイスを使用して、実行時にレンダリング エラーをログに記録できる。アプリケーションで IAMErrorLog インターフェイスを実装し、タイムラインの IAMSetErrorLog::put_ErrorLog メソッドを呼び出す。

このインターフェイスの使い方の詳細については、「エラーのログ」を参照すること。

要件

Qedit.h が必要である。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMSetErrorLog メソッド | 説明
get_ErrorLog | このオブジェクトで設定されているエラー ログを取得する。
put_ErrorLog | オブジェクトのエラー ログを指定する。

IAMSetErrorLog::get_ErrorLog

IAMSetErrorLog インターフェイス

このオブジェクトで設定されているエラー ログを取得する。

構文

HRESULT get_ErrorLog(
    IAMErrorLog **pVal
);

パラメータ

pVal
[out, retval] エラー ログの IAMErrorLog インターフェイスを受け取るポインタのアドレス。タイムラインにエラー ログがない場合、値は NULL に設定される。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

注意

pVal に返された値が NULL 以外の場合、IAMErrorLog インターフェイスは未処理の参照カウントを持つ。使い終わった場合は、インターフェイスを必ず解放すること。

IAMSetErrorLog::put_ErrorLog

IAMSetErrorLog インターフェイス

オブジェクトのエラー ログを指定する。

構文

HRESULT put_ErrorLog(
    IAMErrorLog *newVal
);

パラメータ

newVal
[in] エラー ログの IAMErrorLog インターフェイスを指すポインタ。

戻り値

S_OK を返す。


IAMTimeline インターフェイス

Microsoft® DirectShow® 編集サービス (DES) の中心的オブジェクトであるタイムラインを操作するメソッドを提供する。タイムラインは、ビデオ クリップ、オーディオ クリップ、エフェクト、およびクリップ間のトランジションなど、時間順の要素のコレクションである。レンダリング エンジンは、タイムラインを使用してフィルタ グラフを作成する。アプリケーションは、フィルタ グラフからレンダリングされた出力を生成できる。

IAMTimeline は、3 つの基本的なサービスを行う。以下のことを行う。

  • タイムライン内にオブジェクトを作成する。
  • 作成されたオブジェクトのコンテナとして機能する。
  • タイムラインの一般的パラメータの設定と取得を行う。

要件

Qedit.h が必要である。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMTimeline メソッド | 説明
CreateEmptyNode | 新しいタイムライン オブジェクトを作成する。
AddGroup | タイムラインにグループを追加する。
RemGroupFromList | サポートされていない。
GetGroup | 指定されたグループを取得する。
GetGroupCount | タイムラインに含まれるグループの個数を取得する。
ClearAllGroups | タイムライン内のすべてのグループ、およびそれらに含まれるすべてのオブジェクトを削除する。
GetInsertMode | サポートされていない。
SetInsertMode | 実装されていない。
EnableTransitions | タイムライン内のすべてのトランジションを有効または無効にする。
TransitionsEnabled | トランジションが有効かどうかを調べる。
EnableEffects | タイムライン内のすべてのエフェクトを有効または無効にする。
EffectsEnabled | エフェクトが有効かどうかを調べる。
SetInterestRange | 実装されていない。
GetDuration | タイムラインの時間幅を取得する。
GetDuration2 | GetDuration と同じ機能だが、double 型のパラメータをとる。
SetDefaultFPS | デフォルトの出力フレーム レート (毎秒のフレーム数) を設定する。
GetDefaultFPS | デフォルトの出力フレーム レート (毎秒のフレーム数) を取得する。
IsDirty | サポートされていない。
GetDirtyRange | サポートされていない。
GetCountOfType | 指定されたグループとそのすべての子に含まれる、指定されたタイプのオブジェクトの個数を取得する。
ValidateSourceNames | タイムライン内のソース名を検証する。
SetDefaultTransition | デフォルトのトランジションを設定する。
GetDefaultTransition | デフォルトのトランジションを取得する。
SetDefaultEffect | デフォルトのエフェクトを設定する。
GetDefaultEffect | デフォルトのエフェクトを取得する。
SetDefaultTransitionB | SetDefaultTransition と同じ機能だが、BSTR 値をパラメータにとる。
GetDefaultTransitionB | GetDefaultTransition と同じ機能だが、BSTR 値をパラメータにとる。
SetDefaultEffectB | SetDefaultEffect と同じ機能だが、BSTR 値をパラメータにとる。
GetDefaultEffectB | GetDefaultEffect と同じ機能だが、BSTR 値をパラメータにとる。

IAMTimeline::AddGroup

IAMTimeline インターフェイス

タイムラインにグループを追加する。

構文

HRESULT AddGroup(
    IAMTimelineObj *pGroup
);

パラメータ

pGroup
グループの IAMTimelineObj インターフェイスへのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_INVALIDARG | グループの最大数を超えた。
E_NOINTERFACE | このオブジェクトはグループではない。

注意

現在、タイムラインがサポートするグループの最大数は 32 である。

IAMTimeline::ClearAllGroups

IAMTimeline インターフェイス

タイムライン内のすべてのグループ、およびそれらに含まれるすべてのオブジェクトを削除する。

構文

HRESULT ClearAllGroups( void );

戻り値

S_OK を返す。

IAMTimeline::CreateEmptyNode

IAMTimeline インターフェイス

新しいタイムライン オブジェクトを作成する。

このメソッドは重要な初期化ルーチンを実行するので、タイムラインの作成にはこのメソッドを使用し、CoCreateInstance 関数は使用しない。このメソッドによって作成されるオブジェクトは、少なくとも IAMTimelineObj インターフェイスをサポートし、それと共にそのタイプのオブジェクトに特有の他のインターフェイスをサポートする。

構文

HRESULT CreateEmptyNode(
    IAMTimelineObj **ppObj,
    TIMELINE_MAJOR_TYPE Type
);

パラメータ

ppObj
[out] 新しいオブジェクトの IAMTimelineObj インターフェイスを受け取るポインタのアドレス。
Type
TIMELINE_MAJOR_TYPE 列挙型のメンバ。作成するオブジェクトのタイプを指定する。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_INVALIDARG | オブジェクト タイプが有効ではない。
E_OUTOFMEMORY | メモリ不足。
E_POINTER | NULL ポインタ引数。

注意

別のタイムライン インスタンスに新しいオブジェクトを追加しないこと。タイムラインのすべてのオブジェクトは、そのタイムラインによって作成されなくてはならない。

メソッドが成功した場合、返される IAMTimelineObj インターフェイスは未処理の参照カウントを持つ。使い終わった場合は、インターフェイスを必ず解放すること。

IAMTimeline::EffectsEnabled

IAMTimeline インターフェイス

エフェクトが有効かどうかを調べる。エフェクトが無効の場合、エフェクトはタイムライン内に存在したままだが、レンダリングはされない。

構文

HRESULT EffectsEnabled(
    BOOL *pfEnabled
);

パラメータ

pfEnabled
エフェクトが有効かどうかを示すブール値を受け取る変数へのポインタ。TRUE の場合、エフェクトは有効である。FALSE の場合、エフェクトは無効である。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

IAMTimeline::EnableEffects

IAMTimeline インターフェイス

タイムライン内のすべてのエフェクトを有効または無効にする。エフェクトが無効の場合、エフェクトはタイムライン内に存在したままだが、レンダリングはされない。

構文

HRESULT EnableEffects(
    BOOL fEnabled
);

パラメータ

fEnabled
エフェクトを有効または無効のどちらに設定するかを示すブール値。TRUE の場合、エフェクトが有効になる。FALSE の場合、エフェクトは無効になる。

戻り値

S_OK を返す。

IAMTimeline::EnableTransitions

IAMTimeline インターフェイス

タイムライン内のすべてのトランジションを有効または無効にする。トランジションが無効の場合、レンダリング エンジンはトランジションをカット (直接切り替え) として扱う。すなわち、レンダリングされた出力では、トラックから次のトラックに即座に切り替わる。デフォルトのカット ポイントは、トランジションの時間幅の中間点である。カット ポイントは、そのトランジションの IAMTimelineTrans::SetCutPoint メソッドを呼び出すことにより変更できる。無効になったトランジションは、タイムラインからは削除されない。

構文

HRESULT EnableTransitions(
    BOOL fEnabled
);

パラメータ

fEnabled
トランジションを有効または無効のどちらに設定するかを示すブール値。TRUE の場合、トランジションが有効になる。FALSE の場合、トランジションは無効になる。

戻り値

S_OK を返す。

IAMTimeline::GetCountOfType

IAMTimeline インターフェイス

指定されたグループとそのすべての子に含まれる、指定されたタイプのオブジェクトの個数を取得する。

構文

HRESULT GetCountOfType(
    long Group,
    long *pVal,
    long *pValWithComps,
    TIMELINE_MAJOR_TYPE MajorType
);

パラメータ

Group
オブジェクトの個数を取得するグループのインデックス番号。
pVal
グループおよびそのすべての仮想トラックに含まれる (再帰的に内部に含まれるオブジェクトも含む)、指定されたタイプのオブジェクトの個数を受け取る変数へのポインタ。
pValWithComps
pVal に返された個数と、これ自体も含めて検索された合成の個数を加えた数を受け取る変数へのポインタ。
MajorType
TIMELINE_MAJOR_TYPE 列挙型のメンバ。個数を数えるオブジェクトのタイプを指定する。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_INVALIDARG | 無効なグループ番号。
E_POINTER | NULL ポインタ引数。

注意

このメソッドを呼び出すことは、指定のグループの IAMTimelineComp::GetCountOfType を呼び出すことと同等である。詳細については、そのメソッドの「注意」を参照すること。

通常、アプリケーションではこのメソッドを呼び出さない。これは、レンダリング エンジンによって内部的に呼び出される。

IAMTimeline::GetDefaultEffect

IAMTimeline インターフェイス

デフォルトのエフェクトを取得する。レンダリング エンジンがエフェクトをレンダリングできない場合、デフォルトのエフェクトが代用される。

構文

HRESULT GetDefaultEffect(
    GUID *pGuid
);

パラメータ

pGuid
デフォルト エフェクトのグローバル ユニーク識別子 (GUID) を受け取る変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

IAMTimeline::GetDefaultEffectB

IAMTimeline インターフェイス

デフォルトのエフェクトを取得する。このメソッドは GetDefaultEffect と同じ機能だが、GUID ではなく BSTR 値を受け取る。

構文

HRESULT GetDefaultEffectB(
    BSTR *pGuid
);

パラメータ

pGuid
[out, retval] デフォルト エフェクトの GUID を表す BSTR 値を受け取る変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_OUTOFMEMORY またはエラーの発生を示すその他の HRESULT 値を返す。

注意

このメソッドは、文字列に必要なメモリを割り当てる。アプリケーションは SysFreeString を呼び出して、メモリを解放しなければならない。

IAMTimeline::GetDefaultFPS

IAMTimeline インターフェイス

デフォルトの出力フレーム レート (毎秒のフレーム数、FPS) を取得する。グループは、この値をデフォルトのフレーム レートとして使用する。グループのフレーム レートを設定するには、そのグループの IAMTimelineGroup::SetOutputFPS メソッドを呼び出す。

構文

HRESULT GetDefaultFPS(
    double *pFPS
);

パラメータ

pFPS
デフォルトのフレーム レート (毎秒のフレーム数) を受け取る変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

IAMTimeline::GetDefaultTransition

IAMTimeline インターフェイス

デフォルトのトランジションを取得する。レンダリング エンジンがトランジションをレンダリングできない場合、デフォルトのトランジションが代用される。

構文

HRESULT GetDefaultTransition(
    GUID *pGuid
);

パラメータ

pGuid
デフォルトのトランジションの GUID を受け取る変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

IAMTimeline::GetDefaultTransitionB

IAMTimeline インターフェイス

デフォルトのトランジションを取得する。このメソッドは GetDefaultTransition と同じ機能だが、GUID ではなく BSTR 値を受け取る。

構文

HRESULT GetDefaultTransitionB(
    BSTR *pGuid
);

パラメータ

pGuid
[out, retval] デフォルトのトランジションの GUID を表す BSTR 値を受け取る変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_OUTOFMEMORY またはエラーの発生を示すその他の HRESULT 値を返す。

注意

このメソッドは、文字列に必要なメモリを割り当てる。アプリケーションは SysFreeString を呼び出して、メモリを解放しなければならない。

IAMTimeline::GetDirtyRange

IAMTimeline インターフェイス

サポートされていない。

構文

HRESULT GetDirtyRange(
    REFERENCE_TIME *pStart,
    REFERENCE_TIME *pStop
);

IAMTimeline::GetDuration

IAMTimeline インターフェイス

タイムラインの時間幅を取得する。

構文

HRESULT GetDuration(
    REFERENCE_TIME *pDuration
);

パラメータ

pDuration
タイムラインの時間幅 (100 ナノ秒単位) を受け取る変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

IAMTimeline::GetDuration2

IAMTimeline インターフェイス

タイムラインの時間幅を取得する。このメソッドは GetDuration と同じ機能だが、double 型のパラメータをとる。

構文

HRESULT GetDuration2(
    double *pDuration
);

パラメータ

pDuration
タイムラインの時間幅 (小数の秒数) を受け取る変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

IAMTimeline::GetGroup

IAMTimeline インターフェイス

指定されたグループを取得する。

構文

HRESULT GetGroup(
    IAMTimelineObj **ppGroup,
    long WhichGroup
);

パラメータ

ppGroup
[out] グループの IAMTimelineObj インターフェイスを受け取るポインタのアドレス。
WhichGroup
取得するグループのインデックス。このインデックスは、グループがタイムラインに追加された順序に基づく。 タイムラインに最初に追加されたグループのインデックスは 0 となる。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_INVALIDARG | 無効な引数。
E_POINTER | NULL ポインタ引数。

注意

メソッドが成功した場合、返される IAMTimelineObj インターフェイスは未処理の参照カウントを持つ。使い終わった場合は、インターフェイスを必ず解放すること。

IAMTimeline::GetGroupCount

IAMTimeline インターフェイス

タイムラインに含まれるグループの個数を取得する。

構文

HRESULT GetGroupCount(
    long *pCount
);

パラメータ

pCount
タイムライン内のグループの個数を受け取る変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

IAMTimeline::GetInsertMode

IAMTimeline インターフェイス

サポートされていない。

構文

HRESULT GetInsertMode(
    long *pMode
);

IAMTimeline::IsDirty

IAMTimeline インターフェイス

サポートされていない。

構文

HRESULT IsDirty(
    BOOL *pDirty
);

IAMTimeline::RemGroupFromList

IAMTimeline インターフェイス

サポートされていない。

構文

HRESULT RemGroupFromList(
    IAMTimelineObj *pGroup
);

IAMTimeline::SetDefaultEffect

IAMTimeline インターフェイス

デフォルトのエフェクトを設定する。レンダリング エンジンがエフェクトをレンダリングできない場合、デフォルトのエフェクトが代用される。

構文

HRESULT SetDefaultEffect(
    GUID *pGuid
);

パラメータ

pGuid
デフォルト エフェクトの GUID を持つ変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

注意

デフォルト エフェクトを設定していない場合、またはデフォルトに指定したエフェクトがエラーを引き起こした場合、DES 自体のデフォルト エフェクトが使用される。

IAMTimeline::SetDefaultEffectB

IAMTimeline インターフェイス

デフォルトのエフェクトを設定する。このメソッドは SetDefaultEffect と同じ機能だが、GUID へのポインタではなく BSTR 値をパラメータにとる。

構文

HRESULT SetDefaultEffectB(
    BSTR pGuid
);

パラメータ

pGuid
デフォルト エフェクトの GUID を表す BSTR 値。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_OUTOFMEMORY またはエラーの発生を示すその他の HRESULT 値を返す。

IAMTimeline::SetDefaultFPS

IAMTimeline インターフェイス

デフォルトの出力フレーム レート (毎秒のフレーム数) を設定する。グループは、この値をデフォルトのフレーム レートとして使用する。グループのフレーム レートを設定するには、そのグループの IAMTimelineGroup::SetOutputFPS メソッドを呼び出す。

構文

HRESULT SetDefaultFPS(
    double FPS
);

パラメータ

FPS
デフォルトのフレーム レート (毎秒のフレーム数)。

戻り値

S_OK を返す。

IAMTimeline::SetDefaultTransition

IAMTimeline インターフェイス

デフォルトのトランジションを設定する。レンダリング エンジンがトランジションをレンダリングできない場合、デフォルトのトランジションが代用される。

構文

HRESULT SetDefaultTransition(
    GUID *pGuid
);

パラメータ

pGuid
デフォルトのトランジションの GUID を持つ変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

注意

デフォルトのトランジションを設定していない場合、またはデフォルトに指定したトランジションがエラーを引き起こした場合、DES 自体のデフォルトのトランジションが使用される。

IAMTimeline::SetDefaultTransitionB

IAMTimeline インターフェイス

デフォルトのトランジションを設定する。このメソッドは SetDefaultTransition と同じ機能だが、GUID へのポインタではなく BSTR 値をパラメータにとる。

構文

HRESULT SetDefaultTransitionB(
    BSTR pGuid
);

パラメータ

pGuid
デフォルトのトランジションの GUID を表す BSTR 値。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_OUTOFMEMORY またはエラーの発生を示すその他の HRESULT 値を返す。

IAMTimeline::SetInsertMode

IAMTimeline インターフェイス

実装されていない。

構文

HRESULT SetInsertMode(
    long Mode
);

IAMTimeline::SetInterestRange

IAMTimeline インターフェイス

実装されていない。

構文

HRESULT SetInterestRange(
    REFERENCE_TIME Start,
    REFERENCE_TIME Stop
);

IAMTimeline::TransitionsEnabled

IAMTimeline インターフェイス

トランジションが有効かどうかを調べる。

構文

HRESULT TransitionsEnabled(
    BOOL *pfEnabled
);

パラメータ

pfEnabled
ブール値を受け取る変数へのポインタ。TRUE の場合、トランジションは有効である。そうでない場合、トランジションは無効である。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

参照

EnableTransitions

IAMTimeline::ValidateSourceNames

IAMTimeline インターフェイス

メディア ロケータを使用して、タイムライン内のソース名を検証する。オプションで、このメソッドは見つかったファイルでソース オブジェクトを更新する。

構文

HRESULT ValidateSourceNames(
    long ValidateFlags,
    IMediaLocator *pOverride,
    long NotifyEventHandle
);

パラメータ

ValidateFlags
メディア ロケータの動作を指定するフラグのビットごとの組み合わせ。SFN_VALIDATEF_REPLACE フラグと SFN_VALIDATEF_CHECK フラグは必ず存在していなければならない。そうでない場合、このメソッドは E_INVALIDARG を返す。
pOverride
デフォルトの代わりに使用するメディア ロケータの IMediaLocator インターフェイスへのオプションのポインタ。デフォルトのメディア ロケータを使用するには、このパラメータの値を NULL に設定する。詳細については、「注意」を参照すること。
NotifyEventHandle
イベントのハンドル。このメソッドは、検証が完了した後でこのイベントにシグナル送信する。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_INVALIDARG または他のエラー コードを返す。

注意

pOverride パラメータを使用すると、IMediaLocator インターフェイスの独自のカスタム実装を使用できる。たとえば、デフォルトのメディア ロケータは、見つかった (または見つからなかった) ファイルについてアプリケーションに通知を行わない。このような制限を回避するために、カスタム メディア ロケータを実装して、デフォルト バージョンのラッパーとすることができる。カスタム バージョンでは、デフォルト バージョンに FindMediaFile 呼び出しを直接渡して、その戻り値を調べる。


IAMTimelineComp インターフェイス

Microsoft® DirectShow® 編集サービス (DES) で、合成上の仮想トラックを挿入または取得する。

合成は、合成された単一のトラックとして機能する、レイヤのコレクションである。たとえば、2 つのトラックとそれらの間のトランジションからなる合成は、そのトランジションを持つ合成されていない単一のトラックとして機能する。合成には、同じタイプ (オーディオまたはビデオ) のメディアだけを入れるようにする必要があるが、この制限は強制されない。仮想トラックは、合成内に配置できる、トラックおよび他の合成も含めた任意のオブジェクトである。

タイムラインの最上位のノードはグループである。グループは、IAMTimelineComp インターフェイスおよび IAMTimelineGroup インターフェイスを実装する。

詳細については、「タイムライン モデル」および「グループ、合成、およびトラック」を参照すること。

要件

Qedit.h が必要である。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMTimelineComp メソッド | 説明
VTrackInsBefore | 合成に指定の優先順位で仮想トラックを挿入する。
VTrackSwapPriorities | 2 つのトラックの優先順位レベルを入れ替える。
VTrackGetCount | 合成に含まれる仮想トラックの個数を取得する。
GetVTrack | 指定された優先順位の仮想トラックを取得する。
GetCountOfType | この合成およびそのすべての仮想トラックに含まれる (再帰的に内部に含まれるオブジェクトも含む)、指定されたタイプのオブジェクトの個数を取得する。
GetRecursiveLayerOfType | この合成に含まれる仮想トラックを深度の深い順に順序付け、その順序で n 番目の仮想トラックを取得する。
GetRecursiveLayerOfTypeI | サポートされていない。
GetNextVTrack | 指定された仮想トラックの次の仮想トラックを取得する。

IAMTimelineComp::GetCountOfType

IAMTimelineComp インターフェイス

この合成およびそのすべての仮想トラックに含まれる (再帰的に内部に含まれるオブジェクトも含む)、指定されたタイプのオブジェクトの個数を取得する。

構文

HRESULT GetCountOfType(
    long *pVal,
    long *pValWithComps,
    TIMELINE_MAJOR_TYPE MajorType
);

パラメータ

pVal
この合成およびそのすべての仮想トラックに含まれる (再帰的に内部に含まれるオブジェクトも含む)、指定されたタイプのオブジェクトの個数を受け取る変数へのポインタ。
pValWithComps
pVal に返された個数と、これ自体も含めて検索された合成の個数を加えた数を受け取る変数へのポインタ。
MajorType
TIMELINE_MAJOR_TYPE 列挙型のメンバ。個数を数えるオブジェクトのタイプを指定する。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

注意

通常、アプリケーションではこのメソッドを呼び出さない。これは、レンダリング エンジンによって呼び出される。

合成の個数を調べたとき、pVal に返される値はゼロ、pValWithComps に返される値が合成の個数である。*pValWithComps の値には、メソッドを呼び出した合成も含まれる。たとえば、空の合成でこのメソッドを呼び出した場合、*pValWithComps は 1 に等しい。

グループは合成の中に配置できないので、このメソッドでグループの数を調べることはできない (返される数は常にゼロとなる)。グループの数を調べるには、IAMTimeline::GetGroupCount メソッドを呼び出す。

IAMTimelineComp::GetNextVTrack

IAMTimelineComp インターフェイス

指定された仮想トラックの次の仮想トラックを取得する。

構文

HRESULT GetNextVTrack(
    IAMTimelineObj *pVirtualTrack,
    IAMTimelineObj **ppNextVirtualTrack
);

パラメータ

pVirtualTrack
前の仮想トラックへのポインタ。合成内の最初の仮想トラックを取得する場合は NULL。
ppNextVirtualTrack
[out] 優先順位の順序で、次の仮想トラックの IAMTimelineObj インターフェイスを受け取るポインタのアドレス。

戻り値

このメソッドは、仮想トラックを取得した場合は S_OK を返す。それ以外の場合は S_FALSE を返す。

注意

メソッドが成功した場合、返される IAMTimelineObj インターフェイスは未処理の参照カウントを持つ。使い終わった場合は、インターフェイスを必ず解放すること。

IAMTimelineComp::GetRecursiveLayerOfType

IAMTimelineComp インターフェイス

この合成に含まれる仮想トラックを深度の深い順に順序付け、その順序で n 番目の仮想トラックを取得する。

構文

HRESULT GetRecursiveLayerOfType(
    IAMTimelineObj **ppVirtualTrack,
    long WhichLayer,
    TIMELINE_MAJOR_TYPE Type
);

パラメータ

ppVirtualTrack
[out] 仮想トラックの IAMTimelineObj インターフェイスを受け取るポインタのアドレス。
WhichLayer
取得する仮想トラックを指定する、ゼロから始まるインデックスの値。
Type
TIMELINE_MAJOR_TYPE 列挙型のメンバ。検索にトラックを含めるかどうかを指定する。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_INVALIDARG | 指定されたタイプのオブジェクトはない。
E_POINTER | NULL ポインタ引数。

注意

通常、アプリケーションでこのメソッドを呼び出す必要はない。

Type パラメータが TIMELINE_MAJOR_TYPE_TRACK の場合、深度の順序付けにトラックも含まれる。それ以外の場合は、合成とグループだけが含まれる。そのオブジェクト自体も順序付けに含まれる。

たとえば、合成 A から始まる次のような配置では、順序は B、C、F、D、E、A となる。

メソッドが成功した場合、返される IAMTimelineObj インターフェイスは未処理の参照カウントを持つ。使い終わった場合は、インターフェイスを必ず解放すること。

IAMTimelineComp::GetRecursiveLayerOfTypeI

IAMTimelineComp インターフェイス

サポートされていない。代わりに、GetRecursiveLayerOfType メソッドを呼び出す。

構文

HRESULT GetRecursiveLayerOfTypeI(
    IAMTimelineObj **ppVirtualTrack,
    long *pWhichLayer,
    TIMELINE_MAJOR_TYPE Type
);

IAMTimelineComp::GetVTrack

IAMTimelineComp インターフェイス

指定された優先順位の仮想トラックを取得する。

構文

HRESULT GetVTrack(
    IAMTimelineObj **ppVirtualTrack,
    long Which
);

パラメータ

ppVirtualTrack
[out] 仮想トラックの IAMTimelineObj インターフェイスを受け取るポインタのアドレス。
Which
取得する仮想トラックの優先順位。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_INVALIDARG | 指定された優先順位の仮想トラックはない。
E_POINTER | NULL ポインタ引数。

注意

メソッドが成功した場合、返される IAMTimelineObj インターフェイスは未処理の参照カウントを持つ。使い終わった場合は、インターフェイスを必ず解放すること。

IAMTimelineComp::VTrackGetCount

IAMTimelineComp インターフェイス

合成に含まれる仮想トラックの個数を取得する。

構文

HRESULT VTrackGetCount(
    long *pVal
);

パラメータ

pVal
仮想トラックの個数を受け取る変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

IAMTimelineComp::VTrackInsBefore

IAMTimelineComp インターフェイス

合成に指定の優先順位で仮想トラックを挿入する。

構文

HRESULT VTrackInsBefore(
    IAMTimelineObj *pVirtualTrack,
    long Priority
);

パラメータ

pVirtualTrack
仮想トラックの IAMTimelineObj インターフェイスへのポインタ。
Priority
仮想トラックを挿入する優先順位。優先順位リストの最後に仮想トラックを挿入する場合は -1。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_INVALIDARG | 無効な引数。
E_NOINTERFACE | オブジェクトは仮想トラックではない。

注意

優先順位レベルはゼロから始まる。タイムラインに、指定された優先順位レベルの仮想トラックが既に存在する場合、優先順位リストのその位置以下のすべてが 1 レベルずつ繰り下げられ、挿入されるトラックの場所が確保される。現在のトラックの個数より大きい値を優先順位に指定した場合、このメソッドは失敗する。

IAMTimelineComp::VTrackSwapPriorities

IAMTimelineComp インターフェイス

2 つのトラックの優先順位レベルを入れ替える。

このメソッドは、指定された 2 つの優先順位レベルを持つそれぞれの仮想トラックの優先順位を入れ替える。このメソッドが復帰したとき、最初に指定された優先順位にあったトラックの優先順位は、2 番目に指定された優先順位レベルになり、2 番目に指定された優先順位にあったトラックの優先順位は、最初に指定された優先順位レベルになっている。

構文

HRESULT VTrackSwapPriorities(
    long VirtualTrackA,
    long VirtualTrackB
);

パラメータ

VirtualTrackA
仮想トラックを入れ替える最初の優先順位レベル。
VirtualTrackB
仮想トラックを入れ替える 2 番目の優先順位レベル。

戻り値

成功した場合は S_OK、それ以外の場合は E_INVALIDARG を返す。


IAMTimelineEffect インターフェイス

Microsoft® DirectShow® 編集サービス (DES) でエフェクトを操作するためのメソッドを提供する。エフェクト オブジェクトはこのインターフェイスを実装する。

エフェクト オブジェクトは、DES がサポートするすべてのタイプの単一入力エフェクトのラッパー オブジェクトである。使用するエフェクトを指定するには、そのエフェクトの IAMTimelineObj::SetSubObjectGUID メソッドを呼び出す。エフェクトのプロパティを設定するには、IPropertySetter インターフェイスを使用する。詳細については、「エフェクトとトランジションの操作」を参照すること。

要件

Qedit.h が必要である。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMTimelineEffect メソッド | 説明
EffectGetPriority | エフェクトの優先順位レベルを取得する。

IAMTimelineEffect::EffectGetPriority

IAMTimelineEffect インターフェイス

エフェクトの優先順位レベルを取得する。指定されたオブジェクトに対して、レンダリング エンジンは優先順位に従って、優先順位ゼロから順にエフェクトを適用する。

構文

HRESULT EffectGetPriority(
    long *pVal
);

パラメータ

pVal
優先順位レベルを受け取る変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。


IAMTimelineEffectable インターフェイス

Microsoft® DirectShow® 編集サービス (DES) のタイムライン オブジェクトにエフェクトを追加するためのメソッド、およびオブジェクトのエフェクトを操作するメソッドを提供する。自分に適用できるエフェクトを持つオブジェクトは、すべてこのインターフェイスを実装している。これには、ソース、トラック、および合成が含まれる。

このインターフェイスを実装しているオブジェクトは、エフェクトをいくつでも持つことができる。各オブジェクトごとに、レンダリング エンジンは優先順位に従って、優先順位 0 から順にエフェクトを適用する。

要件

Qedit.h が必要である。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMTimelineEffectable メソッド | 説明
EffectInsBefore | 指定された優先順位のオブジェクトにエフェクトを挿入する。
EffectSwapPriorities | 2 つのエフェクトの優先順位レベルを入れ替える。
EffectGetCount | このオブジェクトに適用されるエフェクトの数を取得する。
GetEffect | 指定された優先順位レベルのエフェクトを取得する。

IAMTimelineEffectable::EffectGetCount

IAMTimelineEffectable インターフェイス

このオブジェクトに適用されるエフェクトの数を取得する。

構文

HRESULT EffectGetCount(
    long *pCount
);

パラメータ

pCount
エフェクトの数を受け取る変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

IAMTimelineEffectable::EffectInsBefore

IAMTimelineEffectable インターフェイス

指定された優先順位のオブジェクトにエフェクトを挿入する。

構文

HRESULT EffectInsBefore(
    IAMTimelineObj *pFX,
    long Priority
);

パラメータ

pFX
エフェクトの IAMTimelineObj インターフェイスへのポインタ。
Priority
エフェクトを挿入する優先順位レベル。エフェクトを優先順位リストの最後に挿入する場合は、値として -1 を使用する。

戻り値

成功した場合は、S_OK を返す。オブジェクトがエフェクトでなかった場合は、E_NOTIMPL を返す。それ以外の場合は、エラーの発生を示す別の HRESULT 値を返す。

注意

エフェクトの開始タイムと終了タイムは、必要に応じて、オブジェクトの時間範囲の境界内に収められる。

指定された優先順位レベルのエフェクトが既に存在する場合、優先順位リストのその位置以下のエフェクトがすべて 1 レベルずつ繰り下げられ、新しいエフェクトの場所が確保される。

IAMTimelineEffectable::EffectSwapPriorities

IAMTimelineEffectable インターフェイス

2 つのエフェクトの優先順位レベルを入れ替える。

このメソッドは、指定された 2 つの優先順位レベルを持つそれぞれのエフェクトの優先順位を入れ替える。このメソッドが復帰したとき、最初に指定された優先順位にあったエフェクトの優先順位は、2 番目に指定された優先順位レベルになり、2 番目に指定された優先順位にあったエフェクトの優先順位は、最初に指定された優先順位レベルになっている。

構文

HRESULT EffectSwapPriorities(
    long PriorityA,
    long PriorityB
);

パラメータ

PriorityA
エフェクトを入れ替える最初の優先順位レベル。
PriorityB
エフェクトを入れ替える 2 番目の優先順位レベル。

戻り値

成功した場合は S_OK、それ以外の場合は E_INVALIDARG を返す。

IAMTimelineEffectable::GetEffect

IAMTimelineEffectable インターフェイス

指定された優先順位レベルのエフェクトを取得する。

構文

HRESULT GetEffect(
    IAMTimelineObj **ppFx,
    long Which
);

パラメータ

ppFX
[out] エフェクトの IAMTimelineObj インターフェイスを受け取るポインタのアドレス。
Which
取得するエフェクトの優先順位レベル。

戻り値

HRESULT 値を返す。可能な値は次のとおりである。

S_FALSE | 指定された優先順位レベルのエフェクトはない。
S_OK | 成功。
E_POINTER | NULL ポインタ引数。

注意

メソッドが S_OK を返した場合、返される IAMTimelineObj インターフェイスは未処理の参照カウントを持つ。使い終わった場合は、インターフェイスを必ず解放すること。


IAMTimelineGroup インターフェイス

Microsoft® DirectShow® 編集サービス (DES) でグループのプロパティを設定および取得する。

グループは 1 つ以上のトラックと、場合により 1 つ以上の合成を持ち、トラックは同一タイプ (ビデオまたはオーディオ) のソース クリップを持つ。グループは、タイムラインの最上位の合成であり、また IAMTimelineComp インターフェイスを公開する。タイムラインは、複数のグループを持つことができる。

各グループには以下の属性がある。

  • 関連付けられたメディア タイプ。
  • グループがレンダリングされるフレーム レート (毎秒のフレーム数、FPS)。すべての編集が始まる時間は、グループの FPS 設定によって定義される最も近いフレーム境界に丸められる。
  • 優先順位レベル。同じメディア タイプの複数のストリームを持つファイル (たとえば、2 つのビデオ ストリームを持つ AVI ファイル) を書き込む際に使用される。

要件

Qedit.h が必要である。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMTimelineGroup メソッド | 説明
SetTimeline | サポートされていない。
GetTimeline | このグループが所属するタイムラインを取得する。
GetPriority | グループの優先順位を取得する。
GetMediaType | グループの非圧縮メディア タイプを取得する。
SetMediaType | グループの非圧縮メディア タイプを設定する。
SetOutputFPS | このグループの非圧縮出力フレーム レートを設定する。
GetOutputFPS | このグループの出力フレーム レートを取得する。
SetGroupName | アプリケーションが定義するグループの名前を設定する。
GetGroupName | アプリケーションが定義するグループの名前を取得する。
SetPreviewMode | グループのプレビュー モードを設定する。
GetPreviewMode | グループのプレビュー モードを取得する。
SetMediaTypeForVB | Automation クライアント用のグループ メディア タイプを指定する。
GetOutputBuffering | プレビュー時に先行してレンダリングされるフレーム数を取得する。
SetOutputBuffering | プレビュー時に先行してレンダリングされるフレーム数を指定する。
SetSmartRecompressFormat | スマート再圧縮で使用される圧縮フォーマットを指定する。
GetSmartRecompressFormat | スマート再圧縮の現在の圧縮フォーマットを取得する。
IsSmartRecompressFormatSet | グループにスマート圧縮が設定されているかどうかを調べる。
IsRecompressFormatDirty | サポートされていない。
ClearRecompressFormatDirty | サポートされていない。
SetRecompFormatFromSource | ソース ファイルの圧縮フォーマットを使ってビデオ再圧縮フォーマットを設定する。

IAMTimelineGroup::ClearRecompressFormatDirty

IAMTimelineGroup インターフェイス

サポートされていない。

構文

HRESULT ClearRecompressFormatDirty(void);

IAMTimelineGroup::GetGroupName

IAMTimelineGroup Interface

アプリケーションが定義するグループの名前を取得する。

構文

HRESULT GetGroupName(
    BSTR *pGroupName
);

パラメータ

pGroupName
[out, retval] グループの名前を受け取る BSTR 型の変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER またはエラーの発生を示すその他の HRESULT 値を返す。

注意

このメソッドは、文字列に必要なメモリを割り当てる。アプリケーションは SysFreeString を呼び出して、メモリを解放しなければならない。

IAMTimelineGroup::GetMediaType

IAMTimelineGroup インターフェイス

グループの非圧縮メディア タイプを取得する。

構文

HRESULT GetMediaType(
    AM_MEDIA_TYPE *pmt
);

パラメータ

pmt
[out] このメディア タイプが設定されている AM_MEDIA_TYPE 構造体へのポインタ。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

IAMTimelineGroup::GetOutputBuffering

IAMTimelineGroup インターフェイス

プレビュー時に先行してレンダリングされるフレーム数を取得する。

構文

HRESULT GetOutputBuffering(
    int *pnBuffer
);

パラメータ

pnBuffer
[out] バッファリングされるフレームの数を受け取る変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

IAMTimelineGroup::GetOutputFPS

IAMTimelineGroup インターフェイス

このグループの出力フレーム レートを取得する。

構文

HRESULT GetOutputFPS(
    double *pFPS
);

パラメータ

pFPS
出力フレーム レート (毎秒のフレーム数) を受け取る変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

IAMTimelineGroup::GetPreviewMode

IAMTimelineGroup インターフェイス

グループのプレビュー モードを取得する。

構文

HRESULT GetPreviewMode(
    BOOL *pfPreview
);

パラメータ

pfPreview
プレビュー モードを示すブール値を受け取る変数へのポインタ。TRUE の場合、グループはプレビュー モードである。FALSE の場合、グループはオーサリング モードである。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

注意

プレビュー モードでは、ビデオとオーディオの同期を維持するために、時間のかかるエフェクトまたはトランジションではフレーム落ちが生じる。そのため、ビデオの動きがぎこちなくなることがある。オーサリング モードでは、すべてのフレームがレンダリングされる。オーサリング モードはファイルへの書き込みに適している。オーサリング モードで画面にプレビューを行うと、ビデオとオーディオの同期がくずれることがある。

IAMTimelineGroup::GetPriority

IAMTimelineGroup インターフェイス

グループの優先順位を取得する。

構文

HRESULT GetPriority(
    long *pPriority
);

パラメータ

pPriority
グループの優先順位を受け取る変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

IAMTimelineGroup::GetSmartRecompressFormat

IAMTimelineGroup インターフェイス

スマート再圧縮の現在の圧縮フォーマットを取得する。

構文

HRESULT GetSmartRecompressFormat(
   long **ppFormat
);

パラメータ

ppFormat
SCompFmt0 構造体へのポインタを受け取る変数のアドレス。long へのポインタにキャストされる。このメソッドが失敗すると、値は NULL に設定される。

戻り値

HRESULT 値を返す。可能な値は次のとおりである。
S_OK | 成功。
E_OUTOFMEMORY | メモリ不足。
E_POINTER | NULL ポインタ引数。

注意

アプリケーションで (SetSmartRecompressFormat を呼び出すことによって) スマート圧縮フォーマットを設定していない場合、このメソッドで返されるフォーマットは無効である。圧縮フォーマットが設定されているかどうかは、IsSmartRecompressFormatSet メソッドを呼び出して調べる。

メソッドが成功した場合、呼び出し元は返されたメディア タイプを解放し、SCompFmt0 構造体を削除しなければならない。

if (pFormat) {
    FreeMediaType(pFormat->MediaType);
    delete pFormat;
}

IAMTimelineGroup::GetTimeline

IAMTimelineGroup インターフェイス

このグループが所属するタイムラインを取得する。

構文

HRESULT GetTimeline(
    IAMTimeline **ppTimeline
);

パラメータ

ppTimeline
[out] タイムラインの IAMTimeline インターフェイスを受け取るポインタのアドレス。グループがタイムラインの一部でない場合、値は NULL に設定される。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

注意

ppTimeline に返された値が NULL 以外の場合、IAMTimeline インターフェイスは未処理の参照カウントを持つ。使い終わった場合は、インターフェイスを必ず解放すること。

IAMTimelineGroup::IsRecompressFormatDirty

IAMTimelineGroup インターフェイス

サポートされていない。

構文

HRESULT IsRecompressFormatDirty(
    BOOL *pVal
);

IAMTimelineGroup::IsSmartRecompressFormatSet

IAMTimelineGroup インターフェイス

グループにスマート再圧縮が設定されているかどうかを調べる。

構文

HRESULT IsSmartRecompressFormatSet(
    BOOL *pVal
);

パラメータ

pVal
圧縮フォーマットが設定されているかどうかを示すブール値を受け取る変数へのポインタ。TRUE の場合、圧縮フォーマットは設定されている。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

IAMTimelineGroup::SetGroupName

IAMTimelineGroup インターフェイス

アプリケーションが定義するグループの名前を設定する。

構文

HRESULT SetGroupName(
    BSTR pGroupName
);

パラメータ

pGroupName
グループの名前を指定する BSTR。

戻り値

S_OK を返す。

IAMTimelineGroup::SetMediaType

IAMTimelineGroup インターフェイス

グループの非圧縮メディア タイプを設定する。

構文

HRESULT SetMediaType(
    AM_MEDIA_TYPE *pmt
);

パラメータ

pmt
[out] フォーマットを記述する AM_MEDIA_TYPE 構造体へのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_POINTER | NULL ポインタ引数。
VFW_E_INVALIDMEDIATYPE | 指定されたメディア タイプは無効である。

注意

現在、以下のメディア タイプがサポートされている。

  • 非圧縮 RGB ビデオ
    • 16 ビット/ピクセル、555 フォーマット
    • 24 ビット/ピクセル
    • 32 ビット/ピクセル
  • 16 ビット ステレオ PCM オーディオ

グループの圧縮フォーマットを指定するには、SetSmartRecompressFormat メソッドを呼び出す。

IAMTimelineGroup::SetMediaTypeForVB

IAMTimelineGroup インターフェイス

Automation クライアント用のグループ メディア タイプを指定する。

構文

HRESULT SetMediaTypeForVB(
    long Val
);

パラメータ

Val
[in] メディア タイプを指定する値。ビデオの場合は値を 0 に設定し、オーディオの場合は 1 に設定する。

戻り値

S_OK を返す。

注意

このメソッドは、Automation クライアント用のものである。C++ アプリケーション用には、SetMediaType メソッドを使用する。

IAMTimelineGroup::SetOutputBuffering

IAMTimelineGroup インターフェイス

プレビュー時に先行してレンダリングされるフレーム数を指定する。

構文

HRESULT SetOutputBuffering(
    int nBuffer
);

パラメータ

nBuffer
[in] プレビュー時にバッファリングされるフレーム数。2 以上でなければならない。

戻り値

成功した場合は S_OK、それ以外の場合は E_INVALIDARG を返す。

注意

バッファが大きくなれば、必要なメモリ量も大きくなるが、プレビューはよりスムースになる。特に、レンダリングに時間がかかるエフェクトまたはトランジションで、それが顕著である。デフォルトのバッファは 30 フレームである。

IAMTimelineGroup::SetOutputFPS

IAMTimelineGroup インターフェイス

このグループの非圧縮出力フレーム レートを設定する。

構文

HRESULT SetOutputFPS(
    double FPS
);

パラメータ

FPS
このグループの出力フレーム レート (毎秒のフレーム数)。この値は、ゼロと等しくすることはできず、小数点以下 8 桁以上とすることはできない。

戻り値

成功した場合は S_OK、それ以外の場合は E_INVALIDARG を返す。

注意

このグループからレンダリングされた出力は、指定されたフレーム レートで実行され、ソース素材上のすべての編集は、フレーム レートによって定義される最も近いフレーム境界に丸められる。

SetSmartRecompressFormat メソッドは、フレーム レートをオーバーライドする。

IAMTimelineGroup::SetPreviewMode

IAMTimelineGroup インターフェイス

グループのプレビュー モードを設定する。

構文

HRESULT SetPreviewMode(
    BOOL fPreview
);

パラメータ

fPreview
プレビュー モードを指定するブール値。TRUE の場合、グループはプレビュー モードである。FALSE の場合、グループはオーサリング モードである。

戻り値

S_OK を返す。

注意

プレビュー モードでは、ビデオとオーディオの同期を維持するために、時間のかかるエフェクトまたはトランジションではフレーム落ちが生じる。そのため、ビデオの動きがぎこちなくなることがある。オーサリング モードでは、すべてのフレームがレンダリングされる。オーサリング モードはファイルへの書き込みに適している。オーサリング モードで画面にプレビューを行うと、ビデオとオーディオの同期がくずれることがある。

IAMTimelineGroup::SetRecompFormatFromSource

IAMTimelineGroup インターフェイス

ソース ファイルの圧縮フォーマットを使ってビデオ再圧縮フォーマットを設定する。

構文

HRESULT SetRecompFormatFromSource(
    IAMTimelineSrc *pSource
);

パラメータ

pSource
ソース オブジェクトの IAMTimelineSrc インターフェイスへのポインタ。

戻り値

HRESULT 値を返す。可能な値は次のとおりである。

S_OK | 成功。
E_NO_TIMELINE | グループはタイムライン内にない。
E_OUTOFMEMORY | メモリ不足。
E_POINTER | NULL ポインタ引数。
VFW_E_INVALIDMEDIATYPE | 無効なメディア タイプ。グループがビデオ グループでないか、またはソース ファイルにビデオ ストリームがない。

注意

このメソッドは、pSource に関連付けられたソース ファイルを探し、ファイルの最初のビデオ ストリームのメディア タイプを取得する。次に、そのタイプを使ってグループの圧縮フォーマットを設定する。圧縮フォーマットの詳細については、「SetSmartRecompressFormat」を参照すること。

IAMTimelineGroup::SetSmartRecompressFormat

IAMTimelineGroup インターフェイス

スマート再圧縮で使用される圧縮フォーマットを指定する。

スマート再圧縮は、オーディオ グループに対してはサポートされない。

構文

HRESULT SetSmartRecompressFormat(
    long *pFormat
);

パラメータ

pFormat
圧縮フォーマットを記述する構造体へのポインタ。現在は、SCompFmt0 構造体のみが有効である。このパラメータは、long 型のポインタにキャストしなければならない。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_POINTER | NULL ポインタ引数。
E_INVALIDARG | 無効な引数。

注意

このメソッドを呼び出して非圧縮フォーマットを指定する前に、同じグループの SetMediaType メソッドを呼び出す。圧縮フォーマットと非圧縮フォーマットは、幅、高さ、およびフレーム レートが同じでなければならない。これらの値が一致していない場合、グループの出力ピンは、圧縮出力ではなく、非圧縮出力を生成する。

このメソッドは、SetOutputFPS メソッドを使って設定されたフレーム レート値をオーバーライドする。

スマート再圧縮フォーマットは、持続的ではない。アプリケーションでスマート再圧縮を使用する場合、プロジェクト ファイルをロードするときに必ず再圧縮フォーマットを設定しなければならない。

IAMTimelineGroup::SetTimeline

IAMTimelineGroup インターフェイス

サポートされていない。代わりに IAMTimeline::AddGroup メソッドを呼び出す。

構文

HRESULT SetTimeline(
    IAMTimeline *pTimeline
);


IAMTimelineObj インターフェイス

Microsoft® DirectShow® 編集サービス (DES) のタイムライン オブジェクトを操作するメソッドを提供する。ソース、エフェクト、トランジション、トラック、グループ、および合成を含むすべてのタイムライン オブジェクトは、このインターフェイスを実装する。タイムライン オブジェクトは、IAMTimeline::CreateEmptyNode メソッドを呼び出すことにより作成する。

要件

Qedit.h が必要である。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMTimelineObj メソッド | 説明
GetStartStop | オブジェクトの親相対の、オブジェクトの開始タイムと終了タイムを取得する。
GetStartStop2 | GetStartStop と同じ機能だが、REFTIME 値をパラメータにとる。
FixTimes | 指定された開始タイムと終了タイムを、親グループのフレーム レート設定によって定義される最も近いフレーム境界に丸める。
FixTimes2 | FixTimes と同じ機能だが、REFTIME 値をパラメータにとる。
SetStartStop | タイムライン相対の開始タイムと終了タイムを設定する。
SetStartStop2 | SetStartStop と同じ機能だが、REFTIME 値をパラメータにとる。
GetPropertySetter | オブジェクトのプロパティ セッターを取得する。
SetPropertySetter | オブジェクトのプロパティ セッターを設定する。
GetSubObject | このオブジェクトに関連付けられているサブオブジェクトを取得する。
SetSubObject | サポートされていない。
SetSubObjectGUID | このオブジェクトに関連付けられているサブオブジェクトのグローバル ユニーク識別子 (GUID) を指定する。
SetSubObjectGUIDB | SetSubObjectGUID と同じ機能だが、BSTR 値をパラメータにとる。
GetSubObjectGUID | このタイムライン オブジェクトに関連付けられているサブオブジェクトの GUID を取得する。
GetSubObjectGUIDB | GetSubObjectGUID と同じ機能だが、BSTR 値をパラメータにとる。
GetSubObjectLoaded | オブジェクトのサブオブジェクト ポインタが設定されているかどうかを調べる。
GetTimelineType | オブジェクトのタイプを取得する。
SetTimelineType | サポートされていない。
SetUserID | オブジェクトに対するアプリケーション定義の識別子を設定する。
GetUserID | オブジェクトのアプリケーション定義の識別子を取得する。
GetGenID | オブジェクトの生成された識別子を取得する。
SetUserName | オブジェクトに対するアプリケーション定義の名前を設定する。
GetUserName | オブジェクトのアプリケーション定義の名前を取得する。
SetUserData | アプリケーション定義の持続的データを設定する。
GetUserData | アプリケーション定義の持続的データを取得する。
SetMuted | オブジェクトのミュート状態を設定する。
GetMuted | オブジェクトのミュート状態を取得する。
SetLocked | オブジェクトの編集状態をロックまたはロック解除に設定する。
GetLocked | オブジェクトの編集状態 (ロックまたはロック解除) を取得する。
GetDirtyRange | サポートされていない。
GetDirtyRange2 | サポートされていない。
SetDirtyRange | 実装されていない。
SetDirtyRange2 | 実装されていない。
ClearDirty | サポートされていない。
Remove | このオブジェクトを、他の場所へ再挿入できるように、タイムラインから削除する。
RemoveAll | このオブジェクトを、サブオブジェクトと子を含めて、タイムラインから永続的に削除する。
GetTimelineNoRef | このメソッドは現在サポートされていない。
GetGroupIBelongTo | サポートされていない。
GetEmbedDepth | サポートされていない。

IAMTimelineObj::ClearDirty

IAMTimelineObj インターフェイス

サポートされていない。

構文

HRESULT ClearDirty( void );

IAMTimelineObj::FixTimes

IAMTimelineObj インターフェイス

指定された開始タイムと終了タイムを、親グループのフレーム レート設定によって定義される最も近いフレーム境界に丸める。

構文

HRESULT FixTimes(
    REFERENCE_TIME *pStart,
    REFERENCE_TIME *pStop
);

パラメータ

pStart
開始タイム (100 ナノ秒単位) を保持する変数へのポインタ。 呼び出しが成功した場合、この変数は丸められた時間に設定される。
pStop
終了タイム (100 ナノ秒単位) を保持する変数へのポインタ。呼び出しが成功した場合、この変数は丸められた時間に設定される。

戻り値

成功した場合は、S_OK を返す。オブジェクトがグループの一部でない場合は、E_NOTINTREE を返す。

注意

レンダリング時に、DES はオブジェクトの開始タイムと終了タイムを、フレーム境界に最も近い値に丸める。ただし、DES はオブジェクトの時間は書き換えない。グループのフレーム レートを変更した場合、丸められた時間は必ず元の時間から計算される。詳細については、「フレーム レート」を参照すること。

このメソッドを使用して、レンダリングされたオブジェクト内での正確な開始タイムと終了タイムを特定できる。たとえば、オブジェクトの元の開始タイムと終了タイムではなく、丸められた時間が必要な場合がある。GetStartStop を呼び出して元の時間を取得し、その値を FixTimes に渡す。

IAMTimelineObj::FixTimes2

IAMTimelineObj インターフェイス

指定された開始タイムと終了タイムを、親グループのフレーム レート設定によって定義される最も近いフレーム境界に丸める。このメソッドは FixTimes と同じ機能だが、REFTIME 値をパラメータにとる。

構文

HRESULT FixTimes2(
    REFTIME *pStart,
    REFTIME *pStop
);

パラメータ

pStart
開始タイム (秒単位) を保持する変数へのポインタ。呼び出しが成功した場合、この変数は丸められた時間に設定される。
pStop
終了タイム (秒単位) を保持する変数へのポインタ。呼び出しが成功した場合、この変数は丸められた時間に設定される。

戻り値

成功した場合は、S_OK を返す。オブジェクトがグループの一部でない場合は、E_NOTINTREE を返す。

IAMTimelineObj::GetDirtyRange

IAMTimelineObj インターフェイス

サポートされていない。

構文

HRESULT GetDirtyRange(
    REFERENCE_TIME *pStart,
    REFERENCE_TIME *pStop
);

IAMTimelineObj::GetDirtyRange2

IAMTimelineObj インターフェイス

サポートされていない。

構文

HRESULT GetDirtyRange2(
    REFTIME *pStart,
    REFTIME *pStop
);

IAMTimelineObj::GetEmbedDepth

IAMTimelineObj インターフェイス

サポートされていない。

構文

HRESULT GetEmbedDepth(
    long *pVal
);

IAMTimelineObj::GetGenID

IAMTimelineObj インターフェイス

オブジェクトの生成された識別子を取得する。この識別子は予約された番号であり、アプリケーションで使用してはならない。

構文

HRESULT GetGenID(
    long *pVal
);

パラメータ

pVal
生成された識別子を受け取る変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

IAMTimelineObj::GetGroupIBelongTo

IAMTimelineObj インターフェイス

サポートされていない。

構文

HRESULT GetGroupIBelongTo(
    IAMTimelineGroup **ppGroup
);

IAMTimelineObj::GetLocked

IAMTimelineObj インターフェイス

オブジェクトの編集状態 (ロックまたはロック解除) を取得する。ロック状態はオブジェクトを編集してはならないことを示し、ロック解除状態はオブジェクトを編集できることを示す。タイムライン側では、ロックを強制しない。ロック状態の設定は、アプリケーション側の利便性のためにのみ存在する。

構文

GetLocked(
    BOOL *pVal
);

パラメータ

pVal
オブジェクトの編集状態を受け取るブール変数へのポインタ。この値が TRUE の場合、オブジェクトはロックされており、編集してはならない。FALSE の場合、オブジェクトはロック解除されており、編集できる。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

IAMTimelineObj::GetMuted

IAMTimelineObj インターフェイス

オブジェクトのミュート状態を取得する。

構文

HRESULT GetMuted(
    BOOL *pVal
);

パラメータ

pVal
ミュート状態を示す値を受け取るブール変数へのポインタ。この値が TRUE の場合、オブジェクトとその子はミュートされている。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

注意

オブジェクトの親がミュートされている場合、ミュート状態とは無関係に、そのオブジェクトもミュートされたままとなる。親のミュートが解除されたときには、そのオブジェクトの前のミュート状態が復元される。

IAMTimelineObj::GetPropertySetter

IAMTimelineObj インターフェイス

オブジェクトのプロパティ セッターを取得する。オブジェクトがレンダリングされるときに、プロパティ セッター内のプロパティ情報がオブジェクトに適用される。

構文

HRESULT GetPropertySetter(
    IPropertySetter **pVal
);

パラメータ

pVal
[out, retval] プロパティ セッターの IPropertySetter インターフェイスを受け取るポインタのアドレス。オブジェクトがプロパティ セッターを持っていない場合、値は NULL に設定される。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

注意

pVal に返された値が NULL 以外の場合、IPropertySetter インターフェイスは未処理の参照カウントを持つ。使い終わった場合は、インターフェイスを必ず解放すること。

IAMTimelineObj::GetStartStop

IAMTimelineObj インターフェイス

オブジェクトの親相対の、オブジェクトの開始タイムと終了タイムを取得する。

構文

HRESULT GetStartStop(
    REFERENCE_TIME *pStart,
    REFERENCE_TIME *pStop
);

パラメータ

pStart
開始タイム (100 ナノ秒単位) を受け取る変数へのポインタ。
pStop
終了タイム (100 ナノ秒単位) を受け取る変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

注意

合成、グループ、およびトラックの開始タイムは常に 0 である。

レンダリング時に、DES はオブジェクトの開始タイムと終了タイムを、フレーム境界に最も近い値に丸める。ただし、DES はオブジェクトの時間は書き換えない。グループのフレーム レートを変更した場合、丸められた時間は必ず元の時間から計算される。詳細については、「フレーム レート」を参照すること。

レンダリングされたプロジェクト内での開始タイムを終了タイムを調べるには、GetStartStop が返した値を FixTimes メソッドに渡す。

IAMTimelineObj::GetStartStop2

IAMTimelineObj インターフェイス

オブジェクトの親相対の、オブジェクトの開始タイムと終了タイムを取得する。このメソッドは GetStartStop と同じ機能だが、REFTIME 値をパラメータにとる。

構文

HRESULT GetStartStop2(
    REFTIME *pStart,
    REFTIME *pStop
);

パラメータ

pStart
開始タイム (秒単位) を受け取る変数へのポインタ。
pStop
終了タイム (秒単位) を受け取る変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

IAMTimelineObj::GetSubObject

IAMTimelineObj インターフェイス

このオブジェクトに関連付けられているサブオブジェクトを取得する。

構文

HRESULT GetSubObject(
    IUnknown **pVal
);

パラメータ

pVal
[out, retval] サブオブジェクトの IUnknown インターフェイスを受け取るポインタのアドレス。オブジェクトがサブオブジェクトを持っていない場合、値は NULL に設定される。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

注意

すべてのタイムライン オブジェクトは、関連付けられたサブオブジェクトへのポインタを保持することができる。たとえば、エフェクトのサブオブジェクトは通常、エフェクトを生成する Microsoft® DirectXt® 変換オブジェクトである。

pVal に返された値が NULL 以外の場合、IUnknown インターフェイスは未処理の参照カウントを持つ。使い終わった場合は、インターフェイスを必ず解放すること。

IAMTimelineObj::GetSubObjectGUID

IAMTimelineObj インターフェイス

このタイムライン オブジェクトに関連付けられているサブオブジェクトの GUID を取得する。

構文

HRESULT GetSubObjectGUID(
    GUID *pVal
);

パラメータ

pVal
サブオブジェクトの GUID を受け取る変数へのポインタ。または、オブジェクトがサブオブジェクトを持っていない場合は GUID_NULL。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

IAMTimelineObj::GetSubObjectGUIDB

IAMTimelineObj インターフェイス

このタイムライン オブジェクトに関連付けられているサブオブジェクトの GUID を取得する。このメソッドは GetSubObjectGUID と同じ機能だが、BSTR 値をパラメータにとる。

構文

HRESULT GetSubObjectGUIDB(
    BSTR *pVal
);

パラメータ

pVal
[out, retval] サブオブジェクトの GUID を表す文字列を受け取る BSTR へのポインタ。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_OUTOFMEMORY またはエラーの発生を示すその他の HRESULT 値を返す。

注意

このメソッドは、文字列に必要なメモリを割り当てる。アプリケーションは SysFreeString を呼び出して、メモリを解放しなければならない。

IAMTimelineObj::GetSubObjectLoaded

IAMTimelineObj インターフェイス

オブジェクトのサブオブジェクト ポインタが設定されているかどうかを調べる。

構文

HRESULT GetSubObjectLoaded(
    BOOL *pVal
);

パラメータ

pVal
ブール値を受け取る変数へのポインタ。この値が TRUE の場合、サブオブジェクト ポインタが設定されている。FALSE の場合、ポインタは設定されていない。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

IAMTimelineObj::GetTimelineNoRef

IAMTimelineObj インターフェイス

サポートされていない。

構文

HRESULT GetTimelineNoRef(
    IAMTimeline **ppResult
);

IAMTimelineObj::GetTimelineType

IAMTimelineObj インターフェイス

オブジェクトのタイプを取得する。

構文

HRESULT GetTimelineType(
    TIMELINE_MAJOR_TYPE *pVal
);

パラメータ

pVal
オブジェクトのタイプを示す、TIMELINE_MAJOR_TYPE 列挙型のメンバを受け取る変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

IAMTimelineObj::GetUserData

IAMTimelineObj インターフェイス

アプリケーション定義の持続的データを取得する。

構文

HRESULT GetUserData(
    BYTE *pData,
    long *pSize
);

パラメータ

pData
データを受け取るバッファへのポインタ。割り当てるバッファのサイズを調べるには、このパラメータを NULL に設定する。必要なサイズが pSize に返される。
pSize
データのサイズ (バイト単位) を受け取る変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

IAMTimelineObj::GetUserID

IAMTimelineObj インターフェイス

オブジェクトのアプリケーション定義の識別子を取得する。

構文

HRESULT GetUserID(
    long *pVal
);

パラメータ

pVal
アプリケーション定義の識別子を受け取る変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

IAMTimelineObj::GetUserName

IAMTimelineObj インターフェイス

オブジェクトのアプリケーション定義の名前を取得する。

構文

HRESULT GetUserName(
    BSTR *pVal
);

パラメータ

pVal
[out, retval] オブジェクトの名前を受け取る BSTR へのポインタ。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_OUTOFMEMORY またはエラーの発生を示すその他の HRESULT 値を返す。

注意

このメソッドは、文字列に必要なメモリを割り当てる。アプリケーションは SysFreeString を呼び出して、メモリを解放しなければならない。

IAMTimelineObj::Remove

IAMTimelineObj インターフェイス

このオブジェクトを (サブオブジェクトは含むが、子は含まない)、他の場所へ再挿入できるように、タイムラインから削除する。

構文

HRESULT Remove( void );

戻り値

S_OK を返す。

注意

このメソッドは、アプリケーションが即座にそのオブジェクトをタイムラインに挿入する場合にのみ呼び出す。このメソッドの呼び出しに続いてオブジェクトを再挿入しないのは、無効な操作である。オブジェクトを永続的に削除するには、RemoveAll を呼び出す。

IAMTimelineObj::RemoveAll

IAMTimelineObj インターフェイス

このオブジェクトを、サブオブジェクトと子を含めて、タイムラインから永続的に削除する。

構文

HRESULT RemoveAll( void );

戻り値

S_OK を返す。

注意

オブジェクトをタイムラインの別の場所に再挿入する目的で削除するには、Remove を呼び出す。

IAMTimelineObj::SetDirtyRange

IAMTimelineObj インターフェイス

実装されていない。

構文

HRESULT SetDirtyRange(
    REFERENCE_TIME Start,
    REFERENCE_TIME Stop
);

IAMTimelineObj::SetDirtyRange2

IAMTimelineObj インターフェイス

実装されていない。

構文

HRESULT SetDirtyRange2(
    REFTIME Start,
    REFTIME Stop
);

IAMTimelineObj::SetLocked

IAMTimelineObj インターフェイス

オブジェクトの編集状態をロックまたはロック解除に設定する。ロック状態はオブジェクトを編集してはならないことを示し、ロック解除状態はオブジェクトを編集できることを示す。タイムライン側では、ロックを強制しない。ロック状態の設定は、アプリケーション側の利便性のためにのみ存在する。

構文

HRESULT SetLocked(
    BOOL newVal
);

パラメータ

newVal
オブジェクトの編集モードを指定するブール値。TRUE の場合、オブジェクトはロックされており、編集してはならない。FALSE の場合、オブジェクトはロック解除されており、編集できる。

戻り値

S_OK を返す。

IAMTimelineObj::SetMuted

IAMTimelineObj インターフェイス

オブジェクトのミュート状態を設定する。ミュートされたオブジェクトは、レンダリングされないが、タイムライン内には存在したままとなる。

構文

HRESULT SetMuted(
    BOOL newVal
);

パラメータ

newVal
ミュート状態を指定するフラグ。TRUE の場合、オブジェクトとそのすべての子はミュートされている。

戻り値

S_OK を返す。

注意

オブジェクトをミュートすると、そのオブジェクトが持つ子もすべてミュートされる。たとえば、あるトラックをミュートすると、そのトラック内のトランジション、ソース、およびエフェクトもすべてミュートされる。オブジェクトのミュートが解除されると、その子はそれぞれの前の状態 (ミュートまたはミュート解除) に戻る。

IAMTimelineObj::SetPropertySetter

IAMTimelineObj インターフェイス

オブジェクトのプロパティ セッターを設定する。オブジェクトがレンダリングされるときに、プロパティ セッター内のプロパティ情報がオブジェクトに適用される。このメソッドは、トランジションおよびエフェクト オブジェクトで呼び出す。

構文

HRESULT SetPropertySetter(
    IPropertySetter *newVal
);

パラメータ

newVal
プロパティ セッターの IPropertySetter インターフェイスへのポインタ。

戻り値

S_OK を返す。

IAMTimelineObj::SetStartStop

IAMTimelineObj インターフェイス

オブジェクトの親相対の、オブジェクトの開始タイムと終了タイムを設定する。

構文

HRESULT SetStartStop(
    REFERENCE_TIME Start,
    REFERENCE_TIME Stop
);

パラメータ

Start
新しい開始タイム (100 ナノ秒単位)。既存の開始タイムを保持する場合は -1。
Stop
新しい終了タイム (100 ナノ秒単位)。既存の終了タイムを保持する場合は -1。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | 実装されていない。

注意

トラック、合成、およびグループは、このメソッドを実装しない。これらのオブジェクトでは、開始タイムは常にゼロであり、終了タイムはそのオブジェクトが持ちえる最大の終了タイムである。

同じトラック内のソース オブジェクトで重なり合う時間を設定してはならない。そのような設定を行うと、未定義の動作を引き起こすことがある。

ソース オブジェクトの場合、開始タイムと終了タイムは、メディア開始タイムおよびメディア終了タイムから独立している。これらの一方の組を変更しても、もう一方に影響はない。メディア開始タイムとメディア終了タイムを設定するには、IAMTimelineSrc::SetMediaTimes メソッドを呼び出す。詳細については、「DirectShow 編集サービスにおける時間」を参照すること。

IAMTimelineObj::SetStartStop2

IAMTimelineObj インターフェイス

オブジェクトの親相対の、オブジェクトの開始タイムと終了タイムを設定する。このメソッドは SetStartStop と同じ機能だが、REFTIME 値をパラメータにとる。

構文

HRESULT SetStartStop2(
    REFTIME Start,
    REFTIME Stop
);

パラメータ

Start
新しい開始タイム (秒単位)。既存の開始タイムを保持する場合は -1。
Stop
新しい終了タイム (秒単位)。既存の終了タイムを保持する場合は -1。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | 実装されていない。

IAMTimelineObj::SetSubObject

IAMTimelineObj インターフェイス

サポートされていない。

構文

HRESULT SetSubObject(
    IUnknown *newVal
);

IAMTimelineObj::SetSubObjectGUID

IAMTimelineObj インターフェイス

このオブジェクトに関連付けられているサブオブジェクトの GUID を指定する。

構文

HRESULT SetSubObjectGUID(
    GUID newVal
);

パラメータ

newVal
サブオブジェクトの GUID。

戻り値

S_OK を返す。

注意

レンダリング エンジンは、必要に応じてサブオブジェクトのインスタンスを作成する。

IAMTimelineObj::SetSubObjectGUIDB

IAMTimelineObj インターフェイス

このオブジェクトに関連付けられているサブオブジェクトの GUID を指定する。このメソッドは SetSubObjectGUID と同じ機能だが、BSTR 値をパラメータにとる。

構文

HRESULT SetSubObjectGUIDB(
    BSTR newVal
);

パラメータ

newVal
サブオブジェクトの GUID を表す BSTR。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、エラーの発生を示す HRESULT 値を返す。

IAMTimelineObj::SetTimelineType

IAMTimelineObj インターフェイス

サポートされていない。新しいタイムライン オブジェクトを作成するには、IAMTimeline::CreateEmptyNode メソッドを呼び出す。オブジェクトが作成した後では、そのタイプは変更できない。

構文

HRESULT SetTimelineType(
    TIMELINE_MAJOR_TYPE newVal
);

IAMTimelineObj::SetUserData

IAMTimelineObj インターフェイス

アプリケーション定義の持続的データを設定する。

構文

HRESULT SetUserData(
    BYTE *pData,
    long Size
)

パラメータ

pData
データを保持するバッファへのポインタ。
Size
データのサイズ (バイト単位)。

戻り値

成功した場合は、S_OK を返す。メモリが不足している場合は、E_OUTOFMEMORY を返す。

IAMTimelineObj::SetUserID

IAMTimelineObj インターフェイス

オブジェクトに対するアプリケーション定義の識別子を設定する。

構文

HRESULT SetUserID(
    long newVal
);

パラメータ

newVal
識別子を指定する値。この識別子は、アプリケーションによってのみ使用され、どのような値でもかまわない。

戻り値

S_OK を返す。

IAMTimelineObj::SetUserName

IAMTimelineObj インターフェイス

オブジェクトに対するアプリケーション定義の名前を設定する。

構文

HRESULT SetUserName(
    BSTR newVal
);

パラメータ

newVal
名前を保持するワイド文字列。256 文字を超える文字列は、切り詰められることがある。

戻り値

S_OK を返す。


IAMTimelineSplittable インターフェイス

Microsoft® DirectShow® 編集サービス (DES) のタイムライン オブジェクトを分割する。ソース、エフェクト、トランジション、およびトラックはこのインターフェイスを実装する。

要件

Qedit.h が必要である。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMTimelineSplittable メソッド | 説明
SplitAt | 指定された時間でオブジェクトを分割する。
SplitAt2 | SplitAt と同じ機能だが、REFTIME 値をパラメータにとる。

IAMTimelineSplittable::SplitAt

IAMTimelineSplittable インターフェイス

指定された時間でオブジェクトを分割する。

構文

HRESULT SplitAt(
    REFERENCE_TIME Time
);

パラメータ

Time
オブジェクトを分割する時間。オブジェクトの先頭相対で、100 ナノ秒単位。

戻り値

HRESULT 値を返す。可能な値は次のとおりである。

S_FALSE | 分割するオブジェクトがない。
S_OK | 成功。
E_INVALIDARG | 無効な引数。
E_OUTOFMEMORY | メモリ不足。

注意

ソース、エフェクト、またはトランジションを分割する場合、このメソッドは同じタイプの 2 番目のオブジェクトを作成する。元のオブジェクトは、分割を指定された時間までに切り詰められ、切り詰められた部分が新しいオブジェクトとなる。新しいオブジェクトは、同じプロパティをすべて継承する。ソース オブジェクトでは、このメソッドは分割時間にかかるエフェクトも分割する。

トラックでこのメソッドを呼び出すと、指定された分割時間にトラック内にあるすべてのソース、エフェクト、およびトランジションが分割される。この場合、2 番目のトラックは作成されない (トラックは、時間ゼロから始まり、無限に伸張する)。分割時間が、トラック内のすべてのものより後になる場合、このメソッドは S_FALSE を返す。

IAMTimelineSplittable::SplitAt2

IAMTimelineSplittable インターフェイス

指定された時間でオブジェクトを分割する。このメソッドは SplitAt と同じ機能だが、REFTIME 値をパラメータにとる。

構文

HRESULT SplitAt2(
    REFTIME Time
);

パラメータ

Time
オブジェクトを分割する時間。オブジェクトの先頭相対で、秒単位。

戻り値

HRESULT 値を返す。可能な値は次のとおりである。

S_FALSE | 分割するオブジェクトがない。
S_OK | 成功。
E_INVALIDARG | 無効な引数。
E_OUTOFMEMORY | メモリ不足。


IAMTimelineSrc インターフェイス

Microsoft® DirectShow® 編集サービス (DES) のソース オブジェクトの操作とプロパティの設定を行うメソッドを提供する。ソース オブジェクトは、メディア ソースからの 1 つのメディア ストリームを表す。

メディア開始タイムとメディア終了タイムを設定することにより、ソース ファイル内のデータの部分を使用できる。この 2 つの値は、ソース オブジェクトの始まりと終わりを、元のメディア ソース相対で指定する。メディア タイムは、タイムライン上のオブジェクトの開始および終了タイムとは異なる場合があり、速度を変えた再生が可能である (オーディオ ソースの場合、ピッチ シフトが生じる)。

詳細については、「タイムラインの構築」および「ソースの操作」を参照すること。

要件

Qedit.h が必要である。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMTimelineSrc メソッド | 説明
GetMediaTimes | メディア開始タイムと終了タイムを取得する。
GetMediaTimes2 | GetMediaTimes と同じ機能だが、REFTIME 値をパラメータにとる。
ModifyStopTime | タイムライン相対の終了タイムを設定する。
ModifyStopTime2 | ModifyStopTime と同じ機能だが、REFTIME 値をパラメータにとる。
FixMediaTimes | 指定されたタイム値を、出力フレーム レートによって定義される最も近いフレーム境界に丸める。
FixMediaTimes2 | FixMediaTimes と同じ機能だが、REFTIME 値をパラメータにとる。
SetMediaTimes | メディア終了タイムと開始タイムを設定する。
SetMediaTimes2 | SetMediaTimes と同じ機能だが、REFTIME 値をパラメータにとる。
SetMediaLength | ソース ファイルの時間幅を指定する。
SetMediaLength2 | SetMediaLength と同じ機能だが、REFTIME 値をパラメータにとる。
GetMediaLength | このソース オブジェクトのメディア長を取得する。
GetMediaLength2 | GetMediaLength と同じ機能だが、REFTIME 値をパラメータにとる。
GetMediaName | このソース オブジェクトが表すソース ファイルの名前を取得する。
SetMediaName | このソース オブジェクトが表すソース ファイルの名前を指定する。
SpliceWithNext | このソース オブジェクトを別のソース オブジェクトに結合する。
GetStreamNumber | ソース オブジェクトの現在のストリーム番号を取得する。
SetStreamNumber | このソース オブジェクトに関連付けられているソース ファイルから読み込むストリームを指定する。
IsNormalRate | クリップが通常の再生レートで再生されるかどうかを示す。
GetDefaultFPS | ソース オブジェクトのデフォルト フレーム レートを取得する。
SetDefaultFPS | ソース オブジェクトのデフォルト フレーム レートを設定する。
GetStretchMode | ビデオ ソースの伸縮モードを取得する。
SetStretchMode | ビデオ ソースの伸縮モードを設定する。

IAMTimelineSrc::FixMediaTimes

IAMTimelineSrc インターフェイス

指定されたタイム値を、出力フレーム レートによって定義される最も近いフレーム境界に丸める。通常、アプリケーションでこのメソッドを呼び出す必要はない。

構文

HRESULT FixMediaTimes(
    REFERENCE_TIME *pStart,
    REFERENCE_TIME *pStop
);

パラメータ

pStart
開始タイム (100 ナノ秒単位) を保持する変数へのポインタ。呼び出しが成功した場合、この変数は丸められた時間に設定される。
pStop
終了タイム (100 ナノ秒単位) を保持する変数へのポインタ。呼び出しが成功した場合、この変数は丸められた時間に設定される。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

注意

このメソッドは IAMTimelineObj::FixTimes メソッドに似ているが、メディア時間とタイムライン時間の元の比率を保持する。最も近いフレーム境界に時間を丸めることにより、この比が変化することがある。

IAMTimelineSrc::FixMediaTimes2

IAMTimelineSrc インターフェイス

指定されたタイム値を、出力フレーム レートによって定義される最も近いフレーム境界に丸める。このメソッドは FixMediaTimes と同じ機能だが、REFTIME 値をパラメータにとる。

構文

HRESULT FixMediaTimes2(
    REFTIME *pStart,
    REFTIME *pStop
);

パラメータ

pStart
開始タイム (秒単位) を保持する変数へのポインタ。呼び出しが成功した場合、この変数は丸められた時間に設定される。
pStop
終了タイム (秒単位) を保持する変数へのポインタ。呼び出しが成功した場合、この変数は丸められた時間に設定される。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

IAMTimelineSrc::GetDefaultFPS

IAMTimelineSrc インターフェイス

ソース オブジェクトのデフォルト フレーム レートを取得する。レンダリング エンジンが元のソースからフレーム レートを特定できない場合、この値が使用される。

構文

HRESULT GetDefaultFPS(
    double *pFPS
);

パラメータ

pFPS
デフォルトのフレーム レート (毎秒のフレーム数) を受け取る変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

注意

ファイル フォーマットでフレーム レートが指定されている場合、デフォルト フレーム レートは必要ない。これは、オーディオおよびビデオ フォーマットの場合に当てはまる。

ソースがビットマップまたは JPEG イメージの場合、レンダリング エンジンはそれをデバイスに依存しないビットマップ (DIB) シーケンスの最初のイメージとして使用し、そのフレーム レートはデフォルト フレーム レートに等しくなる。DIB シーケンスではなく、このスタティック イメージをレンダリングするには、デフォルト フレーム レートを 0 に設定する。

ソースが GIF の場合は、フレーム レートを設定してはならない。アニメーション GIF の場合、GIF ファイルが各イメージ間の遅延を指定する。

IAMTimelineSrc::GetMediaLength

IAMTimelineSrc インターフェイス

このソース オブジェクトのメディア長を取得する。

構文

HRESULT GetMediaLength(
    REFERENCE_TIME *pLength
);

パラメータ

pLength
メディア長 (100 ナノ秒単位) を受け取る変数へのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_NOTDETERMINED | このオブジェクトにメディア時間は設定されていない。
E_POINTER | NULL ポインタ引数。

参照

SetMediaLength

IAMTimelineSrc::GetMediaLength2

IAMTimelineSrc インターフェイス

このソース オブジェクトのメディア長を取得する。このメソッドは GetMediaLength と同じ機能だが、REFTIME 値をパラメータにとる。

構文

HRESULT GetMediaLength2(
    REFTIME *pLength
);

パラメータ

pLength
メディア長 (秒単位) を受け取る変数へのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_NOTDETERMINED | このオブジェクトにメディア時間は設定されていない。
E_POINTER | NULL ポインタ引数。

IAMTimelineSrc::GetMediaName

IAMTimelineSrc インターフェイス

このソース オブジェクトが表すソース ファイルの名前を取得する。

構文

HRESULT GetMediaName(
    BSTR *pVal
);

パラメータ

pVal
[out, retval] ファイルの名前を受け取る文字列へのポインタ。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_OUTOFMEMORY またはエラーの発生を示すその他の HRESULT 値を返す。

注意

このメソッドは、文字列に必要なメモリを割り当てる。アプリケーションは SysFreeString を呼び出して、メモリを解放しなければならない。

IAMTimelineSrc::GetMediaTimes

IAMTimelineSrc インターフェイス

メディア開始タイムと終了タイムを取得する。

構文

HRESULT GetMediaTimes(
    REFERENCE_TIME *pStart,
    REFERENCE_TIME *pStop
);

パラメータ

pStart
メディア開始タイム (100 ナノ秒単位) を受け取る変数へのポインタ。
pStop
メディア終了タイム (100 ナノ秒単位) を受け取る変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

注意

メディア時間は、元のメディア ファイル相対である。詳細については、「DirectShow 編集サービスにおける時間」を参照すること。

IAMTimelineSrc::GetMediaTimes2

IAMTimelineSrc インターフェイス

メディア開始タイムと終了タイムを取得する。このメソッドは GetMediaTimes と同じ機能だが、REFTIME 値をパラメータにとる。

構文

HRESULT GetMediaTimes2(
    REFTIME *pStart,
    REFTIME *pStop
);

パラメータ

pStart
メディア開始タイム (秒単位) を受け取る変数へのポインタ。
pStop
メディア終了タイム (秒単位) を受け取る変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

IAMTimelineSrc::GetStreamNumber

IAMTimelineSrc インターフェイス

ソース オブジェクトの現在のストリーム番号を取得する。

構文

HRESULT GetStreamNumber(
    long *pVal
);

パラメータ

pVal
ストリーム番号を受け取る変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

IAMTimelineSrc::GetStretchMode

IAMTimelineSrc インターフェイス

伸縮モードを取得する。伸縮モードは、ビデオ ソースのサイズが出力ディメンジョンと一致しないときに、どのようにレンダリングされるかを指定する。

構文

HRESULT GetStretchMode(
    int *pnStretchMode
);

パラメータ

pnStretchMode
現在の伸縮 モードを示すフラグを受け取る変数へのポインタ。可能な値は次のとおりである。
  • RESIZEF_STRETCH
  • RESIZEF_CROP
  • RESIZEF_PRESERVEASPECTRATIO
  • RESIZEF_PRESERVEASPECTRATIO_NOLETTERBOX

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

IAMTimelineSrc::IsNormalRate

IAMTimelineSrc インターフェイス

クリップが通常の再生レートで再生されるかどうか、つまり元のファイルの再生レートかどうかを示す。

構文

HRESULT IsNormalRate(
    BOOL *pVal
);

パラメータ

pVal
クリップのレンダリング方法を示すブール値を受け取る変数へのポインタ。値が TRUE の場合、クリップは通常の再生レートで再生される。そうでない場合、通常とは異なる速度で再生される。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

注意

クリップの再生レートは、タイムライン相対のメディア開始タイムとメディア終了タイムによって決まる。

再生レート = (メディア終了タイム - メディア開始タイム) / (タイムライン終了タイム - タイムライン開始タイム)

この比が 1 に等しい場合、クリップは作成時の速度で再生される。そうでない場合、通常とは異なる速度で再生される。詳細については、「DirectShow 編集サービスにおける時間」を参照すること。

IAMTimelineSrc::ModifyStopTime

IAMTimelineSrc インターフェイス

タイムライン相対の終了タイムを設定する。

構文

HRESULT ModifyStopTime(
    REFERENCE_TIME Stop
);

パラメータ

Stop
新しい終了タイム (100 ナノ秒単位)。

戻り値

S_OK を返す。指定された時間が有効でない場合は E_INVALIDARG を返す。

注意

このメソッドは、元の開始タイムと新しい終了タイムを指定して IAMTimelineObj::SetStartStop を呼び出すのと同等である。

IAMTimelineSrc::ModifyStopTime2

IAMTimelineSrc インターフェイス

終了タイムを設定する。このメソッドは ModifyStopTime と同じ機能だが、REFTIME 値をパラメータにとる。

構文

HRESULT ModifyStopTime2(
    REFTIME Stop
);

パラメータ

Stop
新しい終了タイム (秒単位)。

戻り値

成功した場合、S_OK を返す。指定された時間が有効でない場合は、E_INVALIDARG を返す。

IAMTimelineSrc::SetDefaultFPS

IAMTimelineSrc インターフェイス

ソース オブジェクトのデフォルト フレーム レートを設定する。

構文

HRESULT SetDefaultFPS(
    double FPS
);

パラメータ

FPS
デフォルトのフレーム レート (毎秒のフレーム数)。

戻り値

成功した場合、S_OK を返す。指定されたフレーム レートがゼロより小さい場合は、E_INVALIDARG を返す。

注意

レンダリング エンジンが元のソース ファイルからフレーム レートを特定できない場合、この値が使用される。

このメソッドは、定義済みのフレーム レートを持たないソース ファイルに対してのみ呼び出す。ビットマップおよび JPEG ファイルの場合、デフォルト フレーム レートはゼロであり、それによりソースはスティル イメージとしてレンダリングされる。イメージを DIB シーケンスの最初のフレームとして使用するには、フレーム レートをゼロより大きな値に設定する。詳細については、「ソースの操作」を参照すること。

IAMTimelineSrc::SetMediaLength

IAMTimelineSrc インターフェイス

ソース ファイルの時間幅を指定する。

構文

HRESULT SetMediaLength(
    REFERENCE_TIME Length
);

パラメータ

Length
メディア長 (100 ナノ秒単位)。

戻り値

S_OK を返す。

注意

メディア終了タイムを設定する前にメディア長を設定することにより、潜在的なレンダリング エラーを回避できる。メディア終了タイムを設定するときに、DES はそれをメディア長と付き合わせてチェックする。

このメソッドは Length パラメータを検証しないが、その値はソース ファイルの実際の時間幅と等しくなければならない。ソース ファイルの時間幅は、IMediaDet::get_StreamLength を呼び出すことにより取得する。

IAMTimelineSrc::SetMediaLength2

IAMTimelineSrc インターフェイス

ソース ファイルの時間幅を指定する。このメソッドは SetMediaLength と同じ機能だが、REFTIME 値をパラメータにとる。

構文

HRESULT SetMediaLength2(
    REFTIME Length
);

パラメータ

Length
メディア長 (秒単位)。

戻り値

S_OK を返す。

IAMTimelineSrc::SetMediaName

IAMTimelineSrc インターフェイス

このソース オブジェクトが表すソース ファイルの名前を指定する。

構文

HRESULT SetMediaName(
    BSTR newVal
);

パラメータ

newVal
メディア ファイルの名前を指定する文字列。

戻り値

S_OK を返す。

IAMTimelineSrc::SetMediaTimes

IAMTimelineSrc インターフェイス

メディア終了タイムと開始タイムを設定する。

構文

HRESULT SetMediaTimes(
    REFERENCE_TIME Start,
    REFERENCE_TIME Stop
);

パラメータ

Start
メディア開始タイム (100 ナノ秒単位)。
Stop
メディア終了タイム (100 ナノ秒単位)。

戻り値

S_OK を返す。

注意

メディア タイムは、元のメディア ファイル相対のメディア終了タイムとメディア開始タイムである。ビデオまたはオーディオ ソースをタイムラインに追加するときには、必ずメディア タイムを設定する。そうしないと、レンダリングで問題が発生することがある。終了タイムは、開始タイムより大きくなければならない。

ビデオ ソースからスティル フレームを使用するには、開始タイムから小数点以下の値 (たとえば 100 ナノ秒) だけ大きい終了タイムを設定する。開始タイムと終了タイムを同じ値に設定すると、レンダリング エラーが発生する。

タイムラインの時間幅がメディアの時間幅と一致しない場合、それに合わせてソースが伸縮する。これにより、クリップの再生は、作成時とは異なるレートで行われることになる (オーディオ ソースでは、ピッチ シフトが生じる)。詳細については、「DirectShow 編集サービスにおける時間」を参照すること。

ソース ファイルの時間幅は、SetMediaLength メソッドを呼び出すことにより指定できる。メディア終了タイムが時間幅を超える場合、DES は終了タイムを繰り上げる。

IAMTimelineSrc::SetMediaTimes2

IAMTimelineSrc インターフェイス

メディア終了タイムと開始タイムを設定する。このメソッドは SetMediaTimes と同じ機能だが、REFTIME 値をパラメータにとる。

構文

HRESULT SetMediaTimes2(
    REFTIME Start,
    REFTIME Stop
);

パラメータ

Start
メディア開始タイム (秒単位)。
Stop
メディア終了タイム (秒単位)。

戻り値

S_OK を返す。

IAMTimelineSrc::SetStreamNumber

IAMTimelineSrc インターフェイス

このソース オブジェクトに関連付けられているソース ファイルから読み込むストリームを指定する。

構文

HRESULT SetStreamNumber(
    long Val
);

パラメータ

Val
ストリーム番号。親グループの、一致するメディア タイプのストリームのセットから得られる。

戻り値

成功した場合、S_OK を返す。Val がゼロより小さい場合は、E_INVALIDARG を返す。

注意

Val パラメータは、親グループのメディア タイプに一致するストリームのセットにおけるストリーム番号を指定する。これは、ソース ファイルのストリームのセット全体における番号ではない。たとえば、ファイルにビデオ ストリームが 2 つとオーディオ ストリームが 2 つある場合、Val に 0 を指定すると最初のビデオ ストリームが選択される。呼び出し元に、有効なストリーム番号を指定する責任がある。

ストリーム番号のデフォルトはゼロである。

IAMTimelineSrc::SetStretchMode

IAMTimelineSrc インターフェイス

伸縮モードを設定する。伸縮モードは、ビデオ ソースのサイズが出力ディメンジョンと一致しないときに、どのようにレンダリングされるかを指定する。

構文

HRESULT SetStretchMode(
    int nStretchMode
);

パラメータ

nStretchMode
現在の伸縮モードを示すフラグ。可能な値は次のとおりである。
  • RESIZEF_STRETCH
  • RESIZEF_CROP
  • RESIZEF_PRESERVEASPECTRATIO
  • RESIZEF_PRESERVEASPECTRATIO_NOLETTERBOX

戻り値

S_OK を返す。

IAMTimelineSrc::SpliceWithNext

IAMTimelineSrc インターフェイス

ソース オブジェクトを別のソース オブジェクトに結合する。

構文

HRESULT SpliceWithNext(
    IAMTimelineObj *pNext
);

パラメータ

pNext
現在のソースを結合するソース オブジェクトの IAMTimelineObj インターフェイスへのポインタ。

戻り値

HRESULT 値を返す。可能な戻り値は次のとおりである。

S_OK | 成功。
E_INVALIDARG | 無効な引数。
E_NOINTERFACE | pNext パラメータによって指定されたオブジェクトはソース オブジェクトではない。
E_POINTER | NULL ポインタ引数。

注意

現在の実装では、このメソッドは pNext 上のエフェクトは破棄する。

このメソッドを正しく動作させるには、pNext は現在のソース オブジェクトのフレームに一致していなければならない。

  • これは、同じソース ファイルを共有していなければならない。
  • メディア開始タイムが、現在のソースのメディア終了タイムと等しくなければならない。
  • 再生レートが同一でなければならない。再生レートは、メディア時間幅をタイムライン時間幅で割った値である。


IAMTimelineTrack インターフェイス

Microsoft® DirectShow® 編集サービス (DES) のトラック オブジェクトを操作するメソッドを提供する。

トラックには、最終出力でレンダリングされるソースのリストが入る。同じトラック内のソースは、オーバーラップできない。ビデオ トラックは、エフェクトとトランジションの両方を持つことができる。レンダリング エンジンは、トランジションを適用する前にエフェクトを適用する。オーディオ トラックは、エフェクトを持つことはできるが、トランジションを持つことはできない。

詳細については、「タイムライン モデル」を参照すること。

要件

Qedit.h が必要である。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMTimelineTrack メソッド | 説明
SrcAdd | トラックにソースを追加する。
GetNextSrc | 指定された時間以降に始まる次のソースのトラックを検索する。
GetNextSrc2 | GetNextSrc と同じ機能だが、REFTIME 値をパラメータにとる。
MoveEverythingBy | 指定された時間以降に始まるすべてのオブジェクトを、タイムライン上で指定された距離だけ移動する。
MoveEverythingBy2 | MoveEverythingBy と同じ機能だが、REFTIME 値をパラメータにとる。
GetSourcesCount | トラック内のソースの個数を取得する。
AreYouBlank | トラックが空白 (ソース オブジェクトが入っていない) かどうか調べる。
GetSrcAtTime | 指定された境界条件に従って、指定された時間に最も近いソース オブジェクトを取得する。
GetSrcAtTime2 | GetSrcAtTime と同じ機能だが、REFTIME 値をパラメータにとる。
InsertSpace | 指定された時間に存在するすべてのオブジェクトを分割し、その間にスペースを挿入する。
InsertSpace2 | InsertSpace と同じ機能だが、REFTIME 値をパラメータにとる。
ZeroBetween | トラックから、指定された時間の間にあるすべてを削除する。
ZeroBetween2 | ZeroBetween と同じ機能だが、REFTIME 値をパラメータにとる。
GetNextSrcEx | 指定されたソースに続く次のソースを取得する。

IAMTimelineTrack::AreYouBlank

IAMTimelineTrack インターフェイス

トラックが空白 (ソース オブジェクトが入っていない) かどうか調べる。

構文

HRESULT AreYouBlank(
    long *pVal
);

パラメータ

pVal
トラックがブランクかどうかを指定するブール値を受け取る変数へのポインタ。この値が TRUE の場合、オブジェクトは空白であり、ソース オブジェクトは入っていない。FALSE の場合、トラックは空白ではない。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

IAMTimelineTrack::GetNextSrc

IAMTimelineTrack インターフェイス

指定された時間以降に始まる次のソースのトラックを検索する。

構文

HRESULT GetNextSrc(
    IAMTimelineObj **ppSrc,
    REFERENCE_TIME *pInOut
);

パラメータ

ppSrc
[out] ソース オブジェクトの IAMTimelineObj インターフェイスを受け取るポインタのアドレス。
pInOut
検索する開始タイム (100 ナノ秒単位) を保持する変数へのポインタ。このメソッドは、ソースを取得した場合、この値をソースの終了タイムに設定する。ソースを取得しなかった場合、この値は無効になり、アプリケーションで使用してはならない。

戻り値

このメソッドは、ソースを取得した場合は S_OK を返す。それ以外の場合は S_FALSE を返す。

注意

pInOut に指定された値がソースの開始タイムと終了タイムの間にあれば、メソッドはそのソースを取得する。

メソッドが S_OK を返した場合、返される IAMTimelineObj インターフェイスは未処理の参照カウントを持つ。使い終わった場合は、インターフェイスを必ず解放すること。

IAMTimelineTrack::GetNextSrc2

IAMTimelineTrack インターフェイス

指定された時間以降に始まる次のソースのトラックを検索する。このメソッドは GetNextSrc と同じ機能だが、REFTIME 値をパラメータにとる。

構文

HRESULT GetNextSrc2(
    IAMTimelineObj **ppSrc,
    REFTIME *pInOut
);

パラメータ

ppSrc
[out] ソース オブジェクトの IAMTimelineObj インターフェイスを受け取るポインタのアドレス。
pInOut
検索の開始タイム (秒単位) を保持する変数へのポインタ。このメソッドは、ソースを取得した場合、この値をソースの終了タイムに設定する。ソースを取得しなかった場合、この値は無効になり、アプリケーションで使用してはならない。

戻り値

このメソッドは、ソースを取得した場合は S_OK を返す。それ以外の場合は S_FALSE を返す。

IAMTimelineTrack::GetNextSrcEx

IAMTimelineTrack インターフェイス

指定されたソースに続く次のソースを取得する。

構文

HRESULT GetNextSrcEx(
    IAMTimelineObj *pLast,
    IAMTimelineObj **ppNext
);

パラメータ

pLast
前のソース オブジェクトへのポインタ。トラック内の最初のソースを取得する場合は NULL。
ppNext
[out] 次のソース オブジェクトの IAMTimelineObj インターフェイスを受け取るポインタのアドレス。

戻り値

このメソッドは、ソースを取得した場合は S_OK を返す。それ以外の場合は S_FALSE を返す。

注意

メソッドが S_OK を返した場合、返される IAMTimelineObj インターフェイスは未処理の参照カウントを持つ。使い終わった場合は、インターフェイスを必ず解放すること。

IAMTimelineTrack::GetSourcesCount

IAMTimelineTrack インターフェイス

トラック内のソースの個数を取得する。

構文

HRESULT GetSourcesCount(
    long *pVal
);

パラメータ

pVal
トラック内のソースの個数を受け取る変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

IAMTimelineTrack::GetSrcAtTime

IAMTimelineTrack インターフェイス

指定された境界条件に従って、指定された時間に最も近いソース オブジェクトを取得する。

構文

HRESULT GetSrcAtTime(
    IAMTimelineObj **ppSrc,
    REFERENCE_TIME Time,
    long SearchDirection
);

パラメータ

ppSrc
[out] ソース オブジェクトの IAMTimelineObj インターフェイスを受け取るポインタのアドレス。
Time
検索の開始タイム (100 ナノ秒単位)。
SearchDirection
DEXTERF_TRACK_SEARCH_FLAGS 列挙型のメンバ。検索の境界条件を指定する。

戻り値

次のいずれかの HRESULT 値を返す。

S_FALSE | ソース オブジェクトが見つからなかった。
S_OK | ソース オブジェクトが見つかった。
E_INVALIDARG | 無効な引数。
E_POINTER | NULL ポインタ引数。

注意

メソッドが S_OK を返した場合、返される IAMTimelineObj インターフェイスは未処理の参照カウントを持つ。使い終わった場合は、インターフェイスを必ず解放すること。

IAMTimelineTrack::GetSrcAtTime2

IAMTimelineTrack インターフェイス

指定された境界条件に従って、指定された時間に最も近いソース オブジェクトを取得する。このメソッドは GetSrcAtTime と同じ機能だが、REFTIME 値をパラメータにとる。

構文

HRESULT GetSrcAtTime2(
    IAMTimelineObj **ppSrc,
    REFTIME Time,
    long SearchDirection
);

パラメータ

ppSrc
[out] ソース オブジェクトの IAMTimelineObj インターフェイスを受け取るポインタのアドレス。
Time
検索の開始タイム (秒単位)。
SearchDirection
DEXTERF_TRACK_SEARCH_FLAGS 列挙型のメンバ。検索の境界条件を指定する。

戻り値

次のいずれかの HRESULT 値を返す。

S_FALSE | ソース オブジェクトが見つからなかった。
S_OK | ソース オブジェクトが見つかった。
E_INVALIDARG | 無効な引数。
E_POINTER | NULL ポインタ引数。

IAMTimelineTrack::InsertSpace

IAMTimelineTrack インターフェイス

指定された時間に存在するすべてのオブジェクトを分割し、その間にスペースを挿入する。

構文

HRESULT InsertSpace(
    REFERENCE_TIME rtStart,
    REFERENCE_TIME rtEnd
);

パラメータ

rtStart
分割を行う時間、また挿入されるスペースの始点 (100 ナノ秒単位)。
rtEnd
挿入されるスペースの終点 (100 ナノ秒単位)。

戻り値

HRESULT 値を返す。可能な戻り値は次のとおりである。

S_FALSE | 指定された時間にオブジェクトはない。
S_OK | 成功。
E_INVALIDARG | 無効な引数。
E_OUTOFMEMORY | メモリ不足。

IAMTimelineTrack::InsertSpace2

IAMTimelineTrack インターフェイス

指定された時間に存在するすべてのオブジェクトを分割し、その間にスペースを挿入する。このメソッドは InsertSpace と同じ機能だが、REFTIME 値をパラメータにとる。

構文

HRESULT InsertSpace2(
    REFTIME rtStart,
    REFTIME rtEnd
);

パラメータ

rtStart
分割を行う時間、また挿入されるスペースの始点 (秒単位)。
rtEnd
挿入されるスペースの終点 (秒単位)。

戻り値

HRESULT 値を返す。可能な戻り値は次のとおりである。

S_FALSE | 指定された時間にオブジェクトはない。
S_OK | 成功。
E_INVALIDARG | 無効な引数。
E_OUTOFMEMORY | メモリ不足。

IAMTimelineTrack::MoveEverythingBy

IAMTimelineTrack インターフェイス

指定された時間以降に始まるすべてのオブジェクトを、タイムライン上で指定された距離だけ移動する。

構文

HRESULT MoveEverythingBy(
    REFERENCE_TIME Start,
    REFERENCE_TIME MoveBy
);

パラメータ

Start
移動の開始タイム (100 ナノ秒単位)。この時間以降に開始するオブジェクトだけが移動される。
MoveBy
タイムライン上でオブジェクトを移動する時間の量 (100 ナノ秒単位)。

戻り値

オブジェクトが移動された場合、S_OK を返す。オブジェクトが移動されなかった場合は、S_FALSE を返す。

IAMTimelineTrack::MoveEverythingBy2

IAMTimelineTrack インターフェイス

指定された時間以降に始まるすべてのオブジェクトを、タイムライン上で指定された距離だけ移動する。このメソッドは MoveEverythingBy と同じ機能だが、REFTIME 値をパラメータにとる。

構文

HRESULT MoveEverythingBy2(
    REFTIME Start,
    REFTIME MoveBy
);

パラメータ

Start
移動の開始タイム (秒単位)。この時間以降に開始するオブジェクトだけが移動される。
MoveBy
タイムライン上でオブジェクトを移動する時間の量 (秒単位)。

戻り値

オブジェクトが移動された場合、S_OK を返す。オブジェクトが移動されなかった場合は、S_FALSE を返す。

IAMTimelineTrack::SrcAdd

IAMTimelineTrack インターフェイス

トラックにソースを追加する。

構文

HRESULT SrcAdd(
    IAMTimelineObj *pSrc
);

パラメータ

pSrc
ソース オブジェクトの IAMTimelineObj インターフェイスへのポインタ。

戻り値

成功した場合は、S_OK を返す。オブジェクトがソース オブジェクトでない場合、E_NOINTERFACE を返す。それ以外の場合は、エラーの発生を示す HRESULT 値を返す。

注意

このメソッドを呼び出す前に、ソースの開始タイムと終了タイムを設定する (IAMTimelineObj::SetStartStop を呼び出す)。

現在 DES は、ビデオ圧縮マネージャ (VCM) CODEC で圧縮されたソースは、同時に 75 個までしかレンダリングできない。また、そのようなソースがプロジェクト全体で 75 個を超える場合は、動的な再接続を使わなければ、DES はプロジェクトをプレビューできない。詳細については、「IRenderEngine::SetDynamicReconnectLevel」を参照すること。

IAMTimelineTrack::ZeroBetween

IAMTimelineTrack インターフェイス

トラックから、指定された時間の間にあるすべてを削除する。このメソッドは、指定された時間範囲にかかっているすべてのオブジェクトを分割し、その範囲内にある部分を削除する。

構文

HRESULT ZeroBetween(
    REFERENCE_TIME rtStart,
    REFERENCE_TIME rtEnd
);

パラメータ

rtStart
クリアする範囲の始点 (100 ナノ秒単位)。
rtEnd
クリアする範囲の終点 (100 ナノ秒単位)。

戻り値

HRESULT 値を返す。可能な値は次のとおりである。

S_FALSE | 時間範囲が、トラック内のすべてのものを超えている。
S_OK | 成功。

IAMTimelineTrack::ZeroBetween2

IAMTimelineTrack インターフェイス

トラックから、指定された時間の間にあるすべてを削除する。このメソッドは ZeroBetween と同じ機能だが、REFTIME 値をパラメータにとる。

構文

HRESULT ZeroBetween2(
    REFTIME rtStart,
    REFTIME rtEnd
);

パラメータ

rtStart
クリアする範囲の始点 (秒単位)。
rtEnd
クリアする範囲の終点 (秒単位)。

戻り値

HRESULT 値を返す。可能な値は次のとおりである。

S_FALSE | 時間範囲が、トラック内のすべてのものを超えている。
S_OK | 成功。


IAMTimelineTrans インターフェイス

Microsoft® DirectShow® 編集サービス (DES) のトランジション オブジェクトを操作するメソッドを提供する。

トランジションは、1 つのレイヤと、それより低い優先順位のすべてのレイヤのレンダリングされた合成との間で進行する。トランジションを持つことができるオブジェクトは、IAMTimelineTransable インターフェイスを実装する。トランジションのプロパティを設定するには、IPropertySetter インターフェイスを使用する。トランジションの使用については、「エフェクトとトランジションの操作」を参照すること。

要件

Qedit.h が必要である。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMTimelineTrans メソッド | 説明
GetCutPoint | カット ポイントを取得する。
GetCutPoint2 | GetCutPoint と同じ機能だが、REFTIME 値をパラメータにとる。
SetCutPoint | トランジションがカットとしてレンダリングされる場合の、トランジションが一方のソースから次のソースに切り替わる時間を設定する。
SetCutPoint2 | SetCutPoint と同じ機能だが、REFTIME 値をパラメータにとる。
GetSwapInputs | トランジションの入力がスワップされるかどうか示す値を取得する。
SetSwapInputs | トランジションの入力がスワップされるかどうかを指定する。
GetCutsOnly | トランジションがカットとしてレンダリングされるかどうかを調べる。
SetCutsOnly | トランジションがカットとしてレンダリングされるかどうかを指定する。

IAMTimelineTrans::GetCutPoint

IAMTimelineTrans インターフェイス

カット ポイントを取得する。トランジションをカット (直接切り替え) としてレンダリングする場合、カット ポイントはトランジションが一方のソースから次のソースに切り替わる時間である。デフォルトでは、この値はトランジションの中間点である。たとえば、1 秒間のトランジションでは、デフォルトのカット ポイントはトランジションの 0.5 秒の位置である。

構文

HRESULT GetCutPoint(
    REFERENCE_TIME *pTLTime
);

パラメータ

pTLTime
トランジションの開始タイム相対のカット ポイント (100 ナノ秒単位) を受け取る変数へのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

S_FALSE | カット ポイントは設定されなかった。返される値はデフォルト値である。
S_OK | カット ポイントはデフォルト以外の値に設定された。
E_POINTER | NULL ポインタ引数。

参照

SetCutPoint、GetCutsOnly、IAMTimeline::TransitionsEnabled

IAMTimelineTrans::GetCutPoint2

IAMTimelineTrans インターフェイス

カット ポイントを取得する。このメソッドは GetCutPoint と同じ機能だが、REFTIME 値をパラメータにとる。

構文

HRESULT GetCutPoint2(
    REFTIME *pTLTime
);

パラメータ

pTLTime
トランジションの開始タイム相対のカット ポイント (秒単位) を受け取る変数へのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

S_FALSE | カット ポイントは設定されなかった。返される値はデフォルト値である。
S_OK | カット ポイントはデフォルト以外の値に設定された。
E_POINTER | NULL ポインタ引数。

IAMTimelineTrans::GetCutsOnly

IAMTimelineTrans インターフェイス

トランジションがカットとしてレンダリングされるかどうかを調べる。カットとしてレンダリングされる場合、トランジションはカット ポイントで即座に行われる。

構文

HRESULT GetCutsOnly(
    BOOL *pVal
);

パラメータ

pVal
トランジションがカットとしてレンダリングされるかどうかを指定するブール値を受け取る変数へのポインタ。TRUE の場合、トランジションは即時カットである。FALSE の場合、トランジションは通常の時間幅で行われる。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

参照

SetCutsOnly、GetCutPoint、IAMTimeline::TransitionsEnabled

IAMTimelineTrans::GetSwapInputs

IAMTimelineTrans インターフェイス

トランジションの入力がスワップされるかどうか示す値を取得する。

デフォルトでは、トランジションは優先順位の低いレイヤの合成から、トランジションが存在するレイヤに向かって行われる。この進行方向を逆にすることができ、その場合、トランジションはトランジションが存在するレイヤから、優先順位の低いレイヤの合成に向かって行われる。

構文

HRESULT GetSwapInputs(
    BOOL *pVal
);

パラメータ

pVal
ブール値を受け取る変数へのポインタ。この値が FALSE の場合、トランジションは優先順位の低いすべてのレイヤの合成から、そのトランジションが存在するレイヤに向かって行われる。この値が TRUE の場合、トランジションは逆の方向で行われる。デフォルト値は FALSE。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

IAMTimelineTrans::SetCutPoint

IAMTimelineTrans インターフェイス

トランジションがカットとしてレンダリングされる場合の、トランジションが一方のソースから次のソースに切り替わる時間を設定する。

構文

HRESULT SetCutPoint(
    REFERENCE_TIME TLTime
)

パラメータ

TLTime
トランジションの始点相対のカット ポイント (100 ナノ秒単位)。この値がトランジションの範囲の外にある場合、最も近い有効な時間に設定される。

戻り値

S_OK を返す。

注意

デフォルトでは、カット ポイントはトランジションの中間点である。たとえば、1 秒間のトランジションでは、デフォルトのカット ポイントはトランジションの 0.5 秒の位置である。

IAMTimelineTrans::SetCutPoint2

IAMTimelineTrans インターフェイス

トランジションがカットとしてレンダリングされる場合の、トランジションが一方のソースから次のソースに切り替わる時間を設定する。このメソッドは SetCutPoint と同じ機能だが、REFTIME 値をパラメータにとる。

構文

HRESULT SetCutPoint2(
    REFTIME TLTime
)

パラメータ

TLTime
トランジションの始点相対のカット ポイント (秒単位)。

戻り値

S_OK を返す。

IAMTimelineTrans::SetCutsOnly

IAMTimelineTrans インターフェイス

トランジションがカットとしてレンダリングされるかどうかを指定する。カットとしてレンダリングされる場合、トランジションはカット ポイントで即座に行われる。トランジションのレンダリングに時間がかかる場合、カットとしてレンダリングしてプレビューの時間を短縮できる。

構文

HRESULT SetCutsOnly(
    BOOL Val
);

パラメータ

Val
トランジションをカットとしてレンダリングするかどうかを示すブール値。TRUE の場合、トランジションは即時カットとしてレンダリングされる。FALSE の場合、トランジションは通常の時間幅でレンダリングされる。

戻り値

S_OK を返す。

注意

カットとしてのトランジションのレンダリングは、入力のスワップと互換性がない。詳細については、「SetSwapInputs」を参照すること。値 TRUE を使って SetCutsOnly を呼び出すと、一時的に SetSwapInputs 設定にオーバーライドする。カットのみの設定はプレビューを目的としたものであるが、この制限によってファイル出力には影響がない。そのため、ファイルを書き込む前には、値 FALSE を使って SetCutsOnly を呼び出すと覚えておくこと。

IAMTimelineTrans::SetSwapInputs

IAMTimelineTrans インターフェイス

トランジションの入力がスワップされるかどうかを指定する。

デフォルトでは、トランジションは優先順位の低いレイヤの合成から、トランジションが存在するレイヤに向かって行われる。この進行方向を逆にすることができ、その場合、トランジションはトランジションが存在するレイヤから、優先順位の低いレイヤの合成に向かって行われる。詳細については、「トランジションの方向」を参照すること。

構文

HRESULT SetSwapInputs(
    BOOL Val
);

パラメータ

Val
トランジションの入力がスワップされるかどうかを指定するブール値。この値が FALSE の場合、トランジションは優先順位の低いすべてのレイヤの合成から、そのトランジションが存在するレイヤに向かって行われる。この値が TRUE の場合、トランジションは逆の方向で行われる。

戻り値

S_OK を返す。

注意

このメソッドは、ビジュアル エフェクトの方向は変更しない。たとえば、左から右へのワイプは、左から右へ行われる。その方向を変更するには、IPropertySetter インターフェイスを使って Progress プロパティを設定する。


IAMTimelineTransable インターフェイス

Microsoft® DirectShow® 編集サービス (DES) のオブジェクトにトランジションを追加する。このインターフェイスは、適用されるトランジションを持つことができるオブジェクトによって公開される。そのようなオブジェクトには、トラック、合成、およびグループが含まれる。このインターフェイスを実装しているオブジェクトはトランジションをいくつでも持つことができるが、その時間をオーバーラップさせることはできない。

注 : オーディオはトランジションをサポートしていない。オーディオ グループ内のオブジェクトは、IAMTimelineTransable インターフェイスを公開できるが、アプリケーションではそのオブジェクトにトランジションを追加してはならない。

要件

Qedit.h が必要である。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMTimelineTransable メソッド | 説明
TransAdd | オブジェクトにトランジションを追加する。
TransGetCount | このオブジェクトのトランジションの個数を取得する。
GetNextTrans | 指定された時間以降に始まる最初のトランジションを検索する。
GetNextTrans2 | GetNextTrans と同じ機能だが、REFTIME 値をパラメータにとる。
GetTransAtTime | 指定された境界条件に従って、指定された時間に最も近いトランジションを取得する。
GetTransAtTime2 | GetTransAtTime と同じ機能だが、REFTIME 値をパラメータにとる。

IAMTimelineTransable::GetNextTrans

IAMTimelineTransable インターフェイス

指定された時間以降に始まる最初のトランジションを検索する。

構文

HRESULT GetNextTrans(
    IAMTimelineObj **ppTrans,
    REFERENCE_TIME *pInOut
);

パラメータ

ppTrans
[out] トランジション オブジェクトの IAMTimelineObj インターフェイスを受け取るポインタのアドレス。
pInOut
時間 (100 ナノ秒単位) を指定する変数へのポインタ。入力では、この値はトランジションの検索を開始する時間を指定する。出力では、トランジションが取得された場合、この値はそのトランジションの終了タイムに設定される。

戻り値

このメソッドは、トランジションを取得した場合は、S_OK を返す。トランジションが見つからなかった場合は、S_FALSE を返す。それ以外の場合は、失敗の原因を示す HRESULT 値を返す。

注意

トランジションの開始タイムは、pInOut に指定する時間にかかっていれば、指定時間よりも小さくてかまわない。

メソッドが S_OK を返した場合、返される IAMTimelineObj インターフェイスは未処理の参照カウントを持つ。使い終わった場合は、インターフェイスを必ず解放すること。

IAMTimelineTransable::GetNextTrans2

IAMTimelineTransable インターフェイス

指定された時間以降に始まる最初のトランジションを検索する。 このメソッドは GetNextTrans と同じ機能だが、REFTIME 値をパラメータにとる。

構文

HRESULT GetNextTrans2(
    IAMTimelineObj **ppTrans,
    REFTIME *pInOut
);

パラメータ

ppTrans
[out] トランジション オブジェクトの IAMTimelineObj インターフェイスを受け取るポインタのアドレス。
pInOut
時間 (秒単位) を指定する変数へのポインタ。入力では、この値はトランジションの検索を開始する時間を指定する。出力では、トランジションが取得された場合、この値はそのトランジションの終了タイムに設定される。

戻り値

このメソッドは、トランジションを取得した場合は、S_OK を返す。トランジションが見つからなかった場合は、S_FALSE を返す。それ以外の場合は、失敗の原因を示す HRESULT 値を返す。

IAMTimelineTransable::GetTransAtTime

IAMTimelineTransable インターフェイス

指定された境界条件に従って、指定された時間に最も近いトランジションを取得する。

構文

HRESULT GetTransAtTime(
    IAMTimelineObj **ppObj,
    REFERENCE_TIME Time,
    long SearchDirection
);

パラメータ

ppObj
[out] トランジションの IAMTimelineObj インターフェイスを受け取るポインタのアドレス。
Time
検索を開始する時間 (100 ナノ秒単位)。
SearchDirection
DEXTERF_TRACK_SEARCH_FLAGS 列挙型のメンバ。検索の境界条件を指定する。

戻り値

次のいずれかの HRESULT 値を返す。

S_FALSE | トランジションは見つからなかった。
S_OK | トランジションが見つかった。
E_INVALIDARG | 無効な引数。
E_POINTER | NULL ポインタ引数。

注意

メソッドが S_OK を返した場合、返される IAMTimelineObj インターフェイスは未処理の参照カウントを持つ。使い終わった場合は、インターフェイスを必ず解放すること。

IAMTimelineTransable::GetTransAtTime2

IAMTimelineTransable インターフェイス

指定された境界条件に従って、指定された時間に最も近いトランジションを取得する。このメソッドは GetTransAtTime と同じ機能だが、REFTIME 値をパラメータにとる。

構文

HRESULT GetTransAtTime2(
    IAMTimelineObj **ppObj,
    REFTIME Time,
    long SearchDirection
);

パラメータ

ppObj
[out] トランジションの IAMTimelineObj インターフェイスを受け取るポインタのアドレス。
Time
検索を開始する時間 (秒単位)。
SearchDirection
DEXTERF_TRACK_SEARCH_FLAGS 列挙型のメンバ。検索の境界条件を指定する。

戻り値

次のいずれかの HRESULT 値を返す。

S_FALSE | トランジションは見つからなかった。
S_OK | トランジションが見つかった。
E_INVALIDARG | 無効な引数。
E_POINTER | NULL ポインタ引数。

IAMTimelineTransable::TransAdd

IAMTimelineTransable インターフェイス

オブジェクトにトランジションを追加する。オブジェクトは複数のトランジションを持つことができるが、その時間がオーバーラップしてはならない。トランジションは、オブジェクトの時間境界内に収まっていなければならない。

構文

HRESULT TransAdd(
    IAMTimelineObj *pTrans
);

パラメータ

pTrans
追加するトランジションの IAMTimelineObj インターフェイスのアドレス。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_INVALIDARG | トランジションを挿入できない。
E_NOINTERFACE | pTrans は、トランジションへのポインタではない。

注意

挿入するトランジションが既存のトランジションにオーバーラップする場合、このメソッドは E_INVALIDARG を返す。

IAMTimelineTransable::TransGetCount

IAMTimelineTransable インターフェイス

このオブジェクトのトランジションの個数を取得する。

構文

HRESULT TransGetCount(
    long *pCount
);

パラメータ

pCount
トランジションの数を受け取る変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。


IAMTimelineVirtualTrack インターフェイス

Microsoft® DirectShow® 編集サービス (DES) の仮想トラックを操作するメソッドを提供する。合成およびトラックは、このインターフェイスをサポートする。

要件

Qedit.h が必要である。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMTimelineVirtualTrack メソッド | 説明
TrackGetPriority | オブジェクトの優先順位レベルを取得する。
SetTrackDirty | サポートされていない。

IAMTimelineVirtualTrack::SetTrackDirty

IAMTimelineVirtualTrack インターフェイス

サポートされていない。

構文

HRESULT SetTrackDirty( void );

IAMTimelineVirtualTrack::TrackGetPriority

IAMTimelineVirtualTrack インターフェイス

オブジェクトの優先順位レベルを取得する。

構文

HRESULT TrackGetPriority(
    long *pPriority
);

パラメータ

pPriority
優先順位レベルを受け取る変数へのポインタ。オブジェクトがタイムラインの一部でない場合、値は -1 に設定される。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。


IFindCompressorCB インターフェイス

このインターフェイスは、アプリケーションが特定のメディア タイプのコンプレッサを指定できるコールバック メソッドを提供する。

注 : このインターフェイス (スマート レンダリング エンジン) を使用するように設計されたコンポーネントは、現在はその設計のように実装されていない。

スマート再圧縮を行うには、レンダリング エンジンは正しい圧縮フィルタを見つけられなければならない。IFindCompressorCB インターフェイスは、アプリケーションがコンプレッサを選択する手段である。このインターフェイスを使用するには、まずアプリケーションでこのインターフェイスを実装する。次に、ISmartRenderEngine::SetFindCompressorCB メソッドを呼び出すことにより、このインターフェイスへのポインタをレンダリング エンジンに与える。

注 : あらかじめタイムライン グループが使用しなければならないコンプレッサがわかっている場合、より直接な方法として、コンプレッサへのポインタを指定して ISmartRenderEngine::SetGroupCompressor メソッドを呼び出すことができる。また、アプリケーションで指定されていない場合、レンダリング エンジンは適切なコンプレッサを検索する。

要件

Qedit.h が必要である。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IFindCompressorCB メソッド | 説明
GetCompressor | 指定されたメディア タイプ用のコンプレッサを取得する。

IFindCompressorCB::GetCompressor

IFindCompressorCB インターフェイス

指定されたメディア タイプ用のコンプレッサを取得する。

構文

HRESULT GetCompressor(
    AM_MEDIA_TYPE *pType,
    AM_MEDIA_TYPE *pCompType,
    IBaseFilter **ppFilter
);

パラメータ

pType
非圧縮のメディア タイプを記述する AM_MEDIA_TYPE 構造体へのポインタ。
pCompType
圧縮フォーマットを記述する AM_MEDIA_TYPE 構造体へのポインタ。
ppFilter
[out] 圧縮フィルタの IBaseFilter インターフェイスへのポインタを受け取る変数のアドレス。失敗した場合、このメソッドはこのポインタに NULL を設定する。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、実装に応じたエラー コードを返す。


IMediaDet インターフェイス

メディア ファイルに関して、ストリームの数、タイプ、時間幅、各ストリームのフレーム レートなどの情報を取得する。このインターフェイスには、ビデオ ストリームからポスター フレームを取得するメソッドも含まれている。メディア ディテクタは、このインターフェイスを公開する。このインターフェイスは、Microsoft® DirectShow® 編集サービス (DES) で使用する。

ファイルに関する情報を取得するには、以下の手順を実行する。

  1. CoCreateInstance を呼び出すことにより、メディア ディテクタのインスタンスを作成する。クラス ID は CLSID_MediaDet である。
  2. put_Filename を呼び出して、ソース ファイルの名前を指定する (別の方法として、put_Filter を呼び出す)。
  3. get_OutputStreams を呼び出して、ソース内の出力ストリームの個数を取得する。
  4. put_CurrentStream を呼び出して、特定のストリームを指定する。
  5. 次の任意のメソッドを呼び出す。get_StreamType、get_StreamMediaType、get_StreamLength、または get_FrameRate。

ポスター フレームを取り出すには、GetBitmapBits または WriteBitmapBits を呼び出す。別の方法として、EnterBitmapGrabMode を呼び出した後、GetSampleGrabber を呼び出して ISampleGrabber インターフェイスへのポインタを取得する。これらの 3 つのメソッドはすべて、メディア ディテクタをビットマップ グラブ モードという新しいモードに設定する。前述の情報取得メソッドは、このモードでは動作しない。そのため、情報の取得はポスター フレームの取得の前に行う必要がある。そうでない場合は、ストリームごとにメディア ディテクタの新しいインスタンスを作成することになる。

要件

Qedit.h が必要である。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IMediaDet インターフェイス | 説明
get_Filter | メディア ディテクタが現在使用しているソース フィルタへのポインタを取得する。
put_Filter | メディア ディテクタで使用するソース フィルタを指定する。
get_OutputStreams | メディア ソースに含まれる出力ストリームの個数を取得する。
get_CurrentStream | メディア ディテクタが現在使用しているストリーム番号を取得する。
put_CurrentStream | メディア ディテクタで使用するストリーム番号を指定する。
get_StreamType | 現在のストリームのメディア タイプのグローバル ユニーク識別子 (GUID) を取得する。
get_StreamTypeB | 現在のストリームのメディア タイプの GUID を表す文字列を取得する。
get_StreamLength | 現在のストリームの時間幅を取得する。
get_Filename | メディア ディテクタが現在使用しているソース ファイルの名前を取得する。
put_Filename | メディア ディテクタで使用するソース ファイルの名前を指定する。
GetBitmapBits | 指定されたメディア タイムのポスター フレームを取得する。
WriteBitmapBits | 指定されたメディア タイムのポスター フレームを取得し、それをファイルに書き込む。
get_StreamMediaType | 現在のストリームのメディア タイプを取得する。
GetSampleGrabber | ISampleGrabber インターフェイスへのポインタを取得する。
get_FrameRate | 現在のストリームのフレーム レートを取得する。
EnterBitmapGrabMode | メディア ディテクタをビットマップ グラブ モードに切り替え、フィルタ グラフの指定の時間をシークする。

IMediaDet::EnterBitmapGrabMode

IMediaDet インターフェイス

メディア ディテクタをビットマップ グラブ モードに切り替え、フィルタ グラフの指定の時間をシークする。

構文

HRESULT EnterBitmapGrabMode(
    double StreamTime
);

パラメータ

StreamTime
グラフをシークする時間 (秒単位)。

戻り値

HRESULT 値を返す。可能な値は次のとおりである。

S_OK | 成功。
E_INVALIDARG | 無効な引数。
VFW_E_INVALIDMEDIATYPE | ファイルはビデオ ストリームを持っていない。
VFW_E_TIME_EXPIRED | シークできなかった。

注意

このメソッドを呼び出す前に、put_Filename および put_CurrentStream を呼び出してファイル名とストリームを設定する。

このメソッドは、サンプル グラバ フィルタをフィルタ グラフに挿入する。それにより、GetSampleGrabber を呼び出して ISampleGrabber インターフェイスへのポインタを取得できる。メディア ディテクタがビットマップ グラブ モードに入ってからは、IMediaDet の各種の情報取得メソッドは機能しない。

GetBitmapBits および WriteBitmapBits メソッドも、メディア ディテクタをビットマップ グラブ モードに設定する。

IMediaDet::GetBitmapBits

IMediaDet インターフェイス

指定されたメディア タイムのポスター フレームを取得する。

構文

HRESULT GetBitmapBits(
    double StreamTime,
    long *pBufferSize,
    char *pBuffer,
    long Width,
    long Height
);

パラメータ

StreamTime
ポスター フレームを取得する時間。
pBufferSize
必要なバッファ サイズを受け取る変数へのポインタ。pBuffer が NULL の場合、この変数はポスター フレームの取得に必要なバッファのサイズを受け取る。pBuffer が NULL でない場合、このパラメータは無視される。
pBuffer
ポスター フレームを受け取るバッファへのポインタ。
Width
ポスター フレーム イメージの幅 (ピクセル単位)。
Height
ポスター フレーム イメージの高さ (ピクセル単位)。

戻り値

HRESULT 値を返す。可能な値は次のとおりである。

S_OK | 成功。
E_NOINTERFACE | サンプル グラバ フィルタをグラフに追加できなかった。
E_OUTOFMEMORY | メモリ不足。
E_POINTER | NULL ポインタ エラー。
E_UNEXPECTED | 予期せぬエラー。
VFW_E_INVALIDMEDIATYPE | 無効なメディア タイプ。

注意

このメソッドを呼び出す前に、put_Filename および put_CurrentStream を呼び出してファイル名とストリームを設定する。

必要なバッファのサイズを決定するには、pBuffer を NULL にしてこのメソッドを呼び出す。サイズは、pBufferSize が指す変数に返される。そして、バッファを作成して、再度このメソッドを呼び出す。その例を次のコードに示す。

long BufferSize = 0;
GetBitmapBits(StreamTime, &BufferSize, NULL, Width, Height);
char *pBuffer = new char[BufferSize];
GetBitmapBits(StreamTime, 0, pBuffer, Width, Height);

このメソッドは、メディア ディテクタをビットマップ グラブ モードに設定する。このメソッドが呼び出された後は、メディア ディテクタの新しいインスタンスを作成しなければ、IMediaDet の各種のストリーム情報取得メソッドは機能しない。

IMediaDet::get_CurrentStream

IMediaDet インターフェイス

メディア ディテクタが現在使用しているストリーム番号を取得する。

構文

HRESULT get_CurrentStream(
    long *pVal
);

パラメータ

pVal
[out, retval] 現在のストリーム番号を受け取る変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_POINTER を返す。

IMediaDet::get_Filename

IMediaDet インターフェイス

メディア ディテクタが現在使用しているソース ファイルの名前を取得する。

構文

HRESULT get_Filename(
    BSTR *pVal
);

パラメータ

pVal
[out, retval] ファイル名を受け取る変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、エラーの発生を示す HRESULT 値を返す。

注意

このメソッドは、文字列に必要なメモリを割り当てる。アプリケーションは SysFreeString を呼び出して、メモリを解放しなければならない。

IMediaDet::get_Filter

IMediaDet インターフェイス

メディア ディテクタが現在使用しているソース フィルタへのポインタを取得する。

構文

HRESULT get_Filter(
    IUnknown **ppVal
);

パラメータ

ppVal
[out, retval] フィルタの IUnknown インターフェイスを受け取るポインタのアドレス。使用されているソース フィルタがない場合、値は NULL に設定される。

戻り値

HRESULT 値を返す。

注意

メソッドが復帰したときに *ppVal が NULL 以外の場合、IUnknown インターフェイスは未処理の参照カウントを持つ。使い終わった場合は、インターフェイスを必ず解放すること。

IMediaDet::get_FrameRate

IMediaDet インターフェイス

現在のストリームのフレーム レートを取得する。このストリームは、ビデオ ストリームでなければならない。

構文

HRESULT get_FrameRate(
    double *pVal
);

パラメータ

pVal
[out, retval] フレーム レート (毎秒のフレーム数) を受け取る変数へのポインタ。

戻り値

HRESULT 値を返す。可能な値は次のとおりである。

S_FALSE | ビデオ フォーマット ヘッダーでフレーム レートが指定されていない。
S_OK | 成功。
E_INVALIDARG | 無効な引数。
E_POINTER | NULL ポインタ引数。
VFW_E_INVALIDMEDIATYPE | 無効なメディア タイプ。

注意

このメソッドは、ASF ファイルからはフレーム レートを取得できない。

このメソッドを呼び出す前に、put_Filename および put_CurrentStream を呼び出してファイル名とストリームを設定する。

メディア ディテクタがビットマップ グラブ モードの場合、このメソッドは E_INVALIDARG を返す。詳細については、「EnterBitmapGrabMode」を参照すること。

IMediaDet::get_OutputStreams

IMediaDet インターフェイス

メディア ソースに含まれる出力ストリームの個数を取得する。

構文

HRESULT get_OutputStreams(
    long *pVal
);

パラメータ

pVal
[out, retval] 出力ストリームの個数を受け取る変数へのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_INVALIDARG | 無効な引数。
E_POINTER | NULL ポインタ引数。

注意

このメソッドを呼び出す前に、put_Filename を呼び出してファイル名を設定する。

メディア ディテクタがビットマップ グラブ モードの場合、このメソッドは E_INVALIDARG を返す。詳細については、「EnterBitmapGrabMode」を参照すること。

IMediaDet::GetSampleGrabber

IMediaDet インターフェイス

ISampleGrabber インターフェイスへのポインタを取得する。このインターフェイスにより、アプリケーションでメディア ストリームから個々のサンプルを取得できる。

構文

HRESULT GetSampleGrabber(
    ISampleGrabber **ppVal
);

パラメータ

ppVal
[out] ISampleGrabber インターフェイスを受け取るポインタのアドレス。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_NOINTERFACE | メディア ディテクタがビットマップ グラブ モードであるため、インターフェイスを取得できない。
E_POINTER | NULL ポインタ引数。

注意

このメソッドを呼び出す前に、EnterBitmapGrabMode を呼び出す。ISampleGrabber インターフェイスによって、ストリームから個々のメディア サンプルを取得することができる。ポスター フレーム用のビットマップが必要なだけの場合は、代わりに IMediaDet::GetBitmapBits メソッドを呼び出す。ISampleGrabber インターフェイスの方が柔軟性はあるが、アプリケーション側で必要な処理も多くなる。

このメソッドが成功した場合、返される ISampleGrabber インターフェイスは未処理の参照カウントを持つ。使い終わった場合は、インターフェイスを必ず解放すること。

IMediaDet::get_StreamLength

IMediaDet インターフェイス

現在のストリームの時間幅を取得する。

構文

HRESULT get_StreamLength(
    double *pVal
);

パラメータ

pVal
[out, retval] ストリームの時間幅 (秒単位) を受け取る変数へのポインタ。

戻り値

HRESULT 値を返す。可能な値は次のとおりである。

S_OK | 成功。
E_INVALIDARG | 無効な引数。
E_POINTER | NULL ポインタ引数。

注意

このメソッドを呼び出す前に、put_Filename および put_CurrentStream を呼び出してファイル名とストリームを設定する。

メディア ディテクタがビットマップ グラブ モードの場合、このメソッドは E_INVALIDARG を返す。詳細については、「EnterBitmapGrabMode」を参照すること。

IMediaDet::get_StreamMediaType

IMediaDet インターフェイス

現在のストリームのメディア タイプを取得する。

構文

HRESULT get_StreamMediaType(
    AM_MEDIA_TYPE *pVal
);

パラメータ

pVal
[out, retval] このメディア タイプが設定されている AM_MEDIA_TYPE 構造体へのポインタ。

戻り値

HRESULT 値を返す。可能な値は次のとおりである。

S_OK | 成功。
E_INVALIDARG | 無効な引数。
E_POINTER | NULL ポインタ引数。

注意

このメソッドを呼び出す前に、put_Filename および put_CurrentStream を呼び出してファイル名とストリームを設定する。

メディア ディテクタがビットマップ グラブ モードの場合、このメソッドは E_INVALIDARG を返す。詳細については、「EnterBitmapGrabMode」を参照すること。

IMediaDet::get_StreamType

IMediaDet インターフェイス

現在のストリームのメディア タイプのグローバル ユニーク識別子 (GUID) を取得する。

構文

HRESULT get_StreamType(
    GUID *pVal
);

パラメータ

pVal
[out, retval] メディア タイプのメジャー タイプ GUID を受け取る変数へのポインタ。

戻り値

HRESULT 値を返す。可能な値は次のとおりである。

S_OK | 成功。
E_INVALIDARG | 無効な引数。
E_POINTER | NULL ポインタ引数。

注意

このメソッドは、AM_MEDIA_TYPE 構造体の majortype メンバを取得する。AM_MEDIA_TYPE 構造体はストリームのフォーマットを記述し、majortype メンバはオーディオやビデオなどの汎用カテゴリを示す GUID である。ビデオ ストリームの場合、GUID は MEDIATYPE_Video である。オーディオの場合は、MEDIATYPE_Audio である。AM_MEDIA_TYPE 構造体全体を取得するには、get_StreamMediaType メソッドを呼び出す。

このメソッドを呼び出す前に、put_Filename および put_CurrentStream を呼び出してファイル名とストリームを設定する。

メディア ディテクタがビットマップ グラブ モードの場合、このメソッドは E_INVALIDARG を返す。詳細については、「EnterBitmapGrabMode」を参照すること。

IMediaDet::get_StreamTypeB

IMediaDet インターフェイス

現在のストリームのメディア タイプの GUID を表す文字列を取得する。

構文

HRESULT get_StreamTypeB(
    BSTR *pVal
);

パラメータ

pVal
[out, retval] メディア タイプ GUID の文字列表現を受け取る BSTR へのポインタ。

戻り値

HRESULT 値を返す。可能な値は次のとおりである。

S_OK | 成功。
E_INVALIDARG | 無効な引数。
E_POINTER | NULL ポインタ引数。

注意

返される BSTR は次のようなフォーマットである。{73647561-0000-0010-8000-00AA00389B71}

このメソッドは、文字列に必要なメモリを割り当てる。アプリケーションは SysFreeString を呼び出して、メモリを解放しなければならない。

このメソッドを呼び出す前に、put_Filename および put_CurrentStream を呼び出してファイル名とストリームを設定する。

メディア ディテクタがビットマップ グラブ モードの場合、このメソッドは E_INVALIDARG を返す。詳細については、「EnterBitmapGrabMode」を参照すること。

IMediaDet::put_CurrentStream

IMediaDet インターフェイス

メディア ディテクタで使用するストリーム番号を指定する。

構文

HRESULT put_CurrentStream(
    long newVal
);

パラメータ

newVal
[in] ストリーム番号。

戻り値

成功した場合は S_OK、それ以外の場合は E_INVALIDARG を返す。

注意

このメソッドを呼び出す前に、put_Filename を呼び出してファイル名を設定する。get_OutputStreams を呼び出して、ソース ファイルに含まれるストリームの個数を調べる。

メディア ディテクタがビットマップ グラブ モードの場合、このメソッドは E_INVALIDARG を返す。詳細については、「EnterBitmapGrabMode」を参照すること。

IMediaDet::put_Filename

IMediaDet インターフェイス

メディア ディテクタで使用するソース ファイルの名前を指定する。

構文

HRESULT put_Filename(
    BSTR newVal
);

パラメータ

newVal
[in] ソースのファイル名。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、エラーの発生を示す HRESULT 値を返す。

IMediaDet::put_Filter

IMediaDet インターフェイス

メディア ディテクタで使用するソース フィルタを指定する。

構文

HRESULT put_Filter(
    IUnknown *newVal
);

パラメータ

newVal
[in] ソース フィルタの IUnknown インターフェイスを指すポインタ。

戻り値

HRESULT 値を返す。可能な値は次のとおりである。

S_OK | 成功。
E_NOINTERFACE | newVal はフィルタを指していない。
E_POINTER | NULL ポインタ引数。

注意

アプリケーションでは、put_Filename を呼び出す代わりに、ソース フィルタの IUnknown インターフェイスへのポインタを指定してこのメソッドを呼び出すことができる。 既にフィルタ グラフに接続されているフィルタを使用してはならない。

IMediaDet::WriteBitmapBits

IMediaDet インターフェイス

指定されたメディア タイムのポスター フレームを取得し、それをファイルに書き込む。

構文

HRESULT WriteBitmapBits(
    double StreamTime,
    long Width,
    long Height,
    BSTR Filename
);

パラメータ

StreamTime
ポスター フレームを取得する時間。
Width
ポスター フレーム イメージの幅 (ピクセル単位)。
Height
ポスター フレーム イメージの高さ (ピクセル単位)。
Filename
ポスター フレームを保存するファイルのパス。ファイルが既に存在する場合、このメソッドはそのファイルにオーバーライドする。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、エラーの発生を示す HRESULT 値を返す。可能なエラー コードは次のとおりである。

E_NOINTERFACE | サンプル グラバ フィルタをグラフに追加できなかった。
E_FAIL | 失敗。
E_OUTOFMEMORY | メモリ不足。
E_UNEXPECTED | 予期せぬエラー。
STG_E_ACCESSDENIED | ファイルをオーバーライドできない。
VFW_E_INVALIDMEDIATYPE | 無効なメディア タイプ。

注意

このメソッドを呼び出す前に、put_Filename および put_CurrentStream を呼び出してファイル名とストリームを設定する。

このメソッドは、メディア ディテクタをビットマップ グラブ モードに設定する。このメソッドが呼び出された後は、メディア ディテクタの新しいインスタンスを作成しなければ、IMediaDet の各種のストリーム情報取得メソッドは機能しない。


IMediaLocator インターフェイス

Microsoft® DirectShow® 編集サービス (DES) でファイル名の妥当性を検証するためのメソッドを提供する。このインターフェイスを使用して、与えられたファイル名およびパスが既存のファイルに対応していることを確認する。このインターフェイスは、他の場所にあるファイルを検索する手段、および [開く] ダイアログ ボックスを表示してユーザーがファイルを探せるようにする手段も提供する。

メディア ロケータは、このインターフェイスを実装している。タイムラインおよびレンダリング エンジンも、以下のメソッドによってファイル名の検証をサポートしている。

  • IAMTimeline::ValidateSourceNames : タイムライン内のファイル名を検証および更新する。
  • IRenderEngine::SetSourceNameValidation : レンダリング エンジンがレンダリング時にファイル名を検証する方法を指定する。

DES アプリケーションでは、通常はこれらのメソッドを呼び出し、メディア ロケータのインスタンスを直接作成することはない。詳細については、「メディア ロケータの使い方」を参照すること。

要件

Qedit.h が必要である。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IMediaLocator メソッド | 説明
FindMediaFile | ファイルを検索し、成功した場合は、そのファイルへのパスを取得する。
AddFoundLocation | ディレクトリ キャッシュにディレクトリを追加する。

IMediaLocator::AddFoundLocation

IMediaLocator インターフェイス

ディレクトリ キャッシュにディレクトリを追加する。

構文

HRESULT AddFoundLocation(
    BSTR DirectoryName
);

パラメータ

DirectoryName
キャッシュに追加するディレクトリ パス。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、エラーの発生を示す HRESULT 値を返す。

注意

メディア ロケータは、過去の検索でファイルが見つかったディレクトリ パスのキャッシュを維持する。ファイルが見つかった場合は、そのディレクトリをキャッシュに追加する。

IMediaLocator::FindMediaFile

IMediaLocator インターフェイス

ファイルを検索し、成功した場合は、そのファイルへのパスを取得する。

構文

HRESULT FindMediaFile(
    BSTR Input,
    BSTR FilterString,
    BSTR *pOutput,
    long Flags
);

パラメータ

Input
ファイル名。そのファイルが存在していたことがわかっているパスも含む。タイムライン内のソース オブジェクトの場合は、現在のメディア名を使用する。
FilterString
Microsoft® Win32® の OPENFILENAME 構造体の lpstrFilter メンバで必要な書式に設定されたフィルタ文字列のペアを含む BSTR。メディア ロケータは、[開く] ダイアログ ボックスを表示する場合に、このフィルタを使用する。Flags パラメータに SFN_VALIDATEF_POPUP フラグが含まれていない場合、この値は NULL とすることができる。
pOutput
ファイルへの実際のパスが Input 内の値と異なる場合、およびメソッドがファイルを見つけられた場合、ファイルの実際のパスを受け取る変数へのポインタ。
Flags
以下のフラグの 0 個以上のビットごとの組み合わせ。
  • SFN_VALIDATEF_NOFIND
  • SFN_VALIDATEF_POPUP
  • SFN_VALIDATEF_TELLME
  • SFN_VALIDATEF_USELOCAL

戻り値

HRESULT 値を返す。可能な値は次のとおりである。

S_FALSE | ファイルは別の場所で見つかった。
S_OK | ファイルは指定された場所で見つかった。
E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_POINTER | NULL ポインタ引数。

注意

FilterString パラメータによって指定される、[開く] ダイアログ ボックスのフィルタ文字列には、内部的な NULL 文字列が含まれる。たとえば、Video\0*.avi\0\0 は有効なフィルタ文字列である。SysAllocStr 関数を使って BSTR を割り当てることはできない。この関数は、NULL によって終了する文字列を想定しており、最初の NULL 文字で文字列を切り捨てるためである。そのため、SysAllocStringLen など、長さに合った明示的なパラメータが含まれた関数を使用すること。

BSTR filter = SysAllocStringLen(L"Video\0*.avi\0\0", 13);

ユーザーが [開く] ダイアログ ボックスをキャンセルすると、メソッドは E_FAIL を返す。

このメソッドは、pOutput の BSTR にメモリを割り当てる。アプリケーションは SysFreeString を呼び出して、メモリを解放しなければならない。


IPropertySetter インターフェイス

Microsoft® DirectShow® 編集サービス (DES) のエフェクトまたはトランジションのプロパティを設定する。

このインターフェイスを使用するには、プロパティ セッター オブジェクト (CLSID_PropertySetter) のインスタンスを作成し、IAMTimelineObj::SetPropertySetter メソッドを呼び出すことにより、そのインスタンスにエフェクトまたはトランジションを関連付ける。詳細については、「エフェクトとトランジションの操作」を参照すること。

通常、アプリケーションでは ClearProps メソッドを呼び出して既存のプロパティをクリアし、AddProp メソッドを呼び出して新しいプロパティを追加するだけでよい。このインターフェイスの他のメソッドは、他の DES コンポーネントによって呼び出される。

要件

Qedit.h が必要である。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IPropertySetter メソッド | 説明
LoadXML | 拡張可能マークアップ言語 (XML) で表現されたプロパティ データをロードする。
PrintXML | プロパティ データを XML 文字列に変換する。
CloneProps | このプロパティ セッターからプロパティのセットの複製を作成し、新しいプロパティ セッターに追加する。
AddProp | プロパティが適用される時間の範囲を定義するタイム値ペアの配列と共に、プロパティをプロパティ セッターに追加する。
GetProps | このオブジェクトのプロパティ セットを、対応する値と共に取得する。
FreeProps | GetProps メソッドによって割り当てられたリソースを解放する。
ClearProps | プロパティ セッターから、すべてのプロパティ データをクリアする。
SaveToBlob | プロパティ データを永続性フォーマットに保存する。
LoadFromBlob | 永続性フォーマットからプロパティ データをロードする。
SetProps | ターゲット オブジェクトのプロパティを、指定された時間の適切な状態に設定する。

IPropertySetter::AddProp

IPropertySetter インターフェイス

プロパティが適用される時間の範囲を定義するタイム値ペアの配列と共に、プロパティをプロパティ セッターに追加する。

構文

HRESULT AddProp(
    DEXTER_PARAM Param,
    DEXTER_VALUE *paValue
);

パラメータ

Param
[in] プロパティを指定する DEXTER_PARAM 構造体。この構造体の nValues メンバは、paValue パラメータで渡される配列のサイズと等しくなければならない。
paValue
[in] タイム値ペアを保持する DEXTER_VALUE 構造体の配列へのポインタ。この配列内の時間は、昇順で並んでいなければならない。この時間は、エフェクトまたはトランジションの開始タイム相対である。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_INVALIDARG | 無効な引数。
E_OUTOFMEMORY | メモリ不足。
E_POINTER | NULL ポインタ引数。

注意

最初の DEXTER_VALUE 構造体は、ゼロの基準タイムおよび DEXTERF_JUMP の補間フラグ (dwInterp) を指定しなければならない。そうでない場合、メソッドはエラーを返す。

IPropertySetter::ClearProps

IPropertySetter インターフェイス

プロパティ セッターから、すべてのプロパティ データをクリアする。アプリケーションでは、この関数の呼び出し後に、新しいプロパティ データを設定できる。

構文

HRESULT ClearProps( void );

戻り値

S_OK を返す。

IPropertySetter::CloneProps

IPropertySetter インターフェイス

このプロパティ セッターからプロパティのセットの複製を作成し、新しいプロパティ セッターに追加する。

構文

HRESULT CloneProps(
    IPropertySetter **ppSetter,
    REFERENCE_TIME rtStart,
    REFERENCE_TIME rtStop
);

パラメータ

ppSetter
[out] 新しいプロパティ セッターの IPropertySetter インターフェイスを受け取るポインタのアドレス。
rtStart
複製する値の範囲の開始タイム (100 ナノ秒単位)。
rtStop
[in] 予約済み。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、エラーの発生を示す HRESULT 値を返す。可能なエラー コードは次のとおりである。

E_INVALIDARG | 無効な引数。
E_OUTOFMEMORY | メモリ不足。
E_POINTER | NULL ポインタ引数。

注意

指定された開始タイムより後の値だけが複製される。複製された値の時間は、開始タイム相対に調整される。たとえば、rtStart が 20000000 (2 秒) の場合、タイム 30000000 (3 秒) の値は、複製されるとタイム 10000000 (1 秒) となる。最後に、複製された各プロパティには、開始タイムの元のプロパティの値に等しい初期値が与えられる (必要であれば適切な補間が行われる)。実質的に、プロパティ データは指定された開始タイムで分割される。

メソッドが成功した場合、返される IPropertySetter インターフェイスは未処理の参照カウントを持つ。使い終わった場合は、インターフェイスを必ず解放すること。

IPropertySetter::FreeProps

IPropertySetter インターフェイス

GetProps メソッドによって割り当てられたリソースを解放する。GetProps を呼び出した後でこのメソッドを呼び出し、GetProps によって返された構造体を渡す。

構文

HRESULT FreeProps(
    LONG cParams,
    DEXTER_PARAM *paParam,
    DEXTER_VALUE *paValue
);

パラメータ

cParams
[in] paParam パラメータで与えられる配列のサイズを指定する値。
paParam
[in] DEXTER_PARAM 構造体の配列へのポインタ。
paValue
[in] DEXTER_VALUE 構造体の配列へのポインタ。

戻り値

S_OK を返す。

IPropertySetter::GetProps

IPropertySetter インターフェイス

このオブジェクトのプロパティ セットを、対応する値と共に取得する。

構文

HRESULT GetProps(
    LONG *pcParams,
    DEXTER_PARAM **paParam,
    DEXTER_VALUE **paValue
);

パラメータ

pcParams
[out] paParam に返される構造体の個数を受け取る変数へのポインタ。
paParam
[in] DEXTER_PARAM 構造体の配列へのポインタのアドレス。
paValue
[in] DEXTER_VALUE 構造体の配列へのポインタのアドレス。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_OUTOFMEMORY | メモリ不足。
E_POINTER | NULL ポインタ引数。

注意

paParam に返される各プロパティごとに、nValues メンバはそのプロパティに関連付けられている DEXTER_VALUE 構造体の個数を示す。これらのペアは、各プロパティごとに時間の昇順で返される。

たとえば、次のサンプル コードは、すべての値を繰り返し処理する方法を示している。

DEXTER_PARAM *pParam;
DEXTER_VALUE *pValue;
LONG count;

hr = pSetter->GetProps(&count, &pParam, &pValue);

LONG num = 0;
for (LONG i = 0; i < count; i++)
{
    for (LONG j = 0; j < pParam[i].nValues; j++)
    {
        // pValue[num] は、pParam[i] のシーケンス内の次の値である。
    }
    num += pParam[i].nValues;
}

返された構造体の使用が終わったら、FreeProps を呼び出して、このメソッドによって割り当てられていたリソースを解放する。

IPropertySetter::LoadFromBlob

IPropertySetter インターフェイス

永続性フォーマットからプロパティ データをロードする。

構文

HRESULT LoadFromBlob(
    LONG cSize,
    BYTE *pb
);

パラメータ

cSize
[in] データのサイズ (バイト単位)。
pb
[in] データを保持するバイトの配列へのポインタ。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_OUTOFMEMORY または他のエラー コードを返す。

IPropertySetter::LoadXML

IPropertySetter インターフェイス

拡張可能マークアップ言語 (XML) で表現されたプロパティ データをロードする。

構文

HRESULT LoadXML(
    IUnknown *pxml
);

パラメータ

pxml
[in] Microsoft XML パーサによって作成された XML 要素の IUnknown インターフェイスへのポインタ。

戻り値

HRESULT 値を返す。 可能な値は次のとおりである。

S_FALSE | プロパティ データなし。
S_OK | 成功。
E_OUTOFMEMORY | メモリ不足。
VFW_E_INVALID_FILE_FORMAT | 無効なフォーマット。

注意

通常、アプリケーションはこのメソッドを使用しない。DES では、このメソッドを内部的に使って XTL ファイルからプロパティをロードする。

このメソッドを使用するには、IXMLDocument オブジェクトを作成し、このオブジェクトを使って XML ファイルを解析する。次に、IXMLDocument オブジェクトを使って IXMLElement オブジェクトを取得する。このオブジェクトにプロパティがある場合は、IXMLElement ポインタを LoadXML メソッドに渡すことができる。このメソッドは、プロパティ セッターにプロパティをロードする。

IPropertySetter::PrintXML

IPropertySetter インターフェイス

プロパティ データを拡張可能マークアップ言語 (XML) 文字列に変換する。

構文

HRESULT PrintXML(
    char *pszXML,
    int cbXML,
    int *pcbPrinted,
    int indent
);

パラメータ

pszXML
[out] XML 文字列を受け取るバッファへのポインタ。
cbXML
[in] pszXML が指すバッファのサイズ (バイト単位)。
pcbPrinted
[out] XML 文字列の長さを受け取る変数へのポインタ。NULL の場合がある。
indent
[in] 最も外側のタグのインデント レベル数。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、エラーの発生を示す HRESULT 値を返す。XML 文字列がバッファより長かった場合、このメソッドは E_OUTOFMEMORY を返す。

IPropertySetter::SaveToBlob

IPropertySetter インターフェイス

プロパティ データを永続性フォーマットに保存する。

構文

HRESULT SaveToBlob(
    LONG *pcSize,
    BYTE **ppb
);

パラメータ

pcSize
[out] データのサイズ (バイト単位) を受け取る変数へのポインタ。
ppb
[in] データを受け取るバイトの配列へのポインタのアドレス。

戻り値

HRESULT 値を返す。可能な値は次のとおりである。

S_OK | 成功。
E_OUTOFMEMORY | メモリ不足。
E_POINTER | NULL ポインタ引数。

注意

このメソッドは、バイト配列に必要なメモリを割り当てる。呼び出し元は CoTaskMemFree 関数を使って、メモリを解放しなければならない。

IPropertySetter::SetProps

IPropertySetter インターフェイス

ターゲット オブジェクトのプロパティを、指定された時間の適切な状態に設定する。

構文

HRESULT SetProps(
    IUnknown *pTarget,
    REFERENCE_TIME rtNow
);

パラメータ

pTarget
[in] プロパティを設定するターゲット オブジェクトへのポインタ。
rtNow
[in] プロパティを設定するタイム (100 ナノ秒単位)。スタティック プロパティ (時間の経過によって変化しないプロパティ) を設定する場合は -1。

戻り値

HRESULT 値を返す。

注意

このメソッドは、DES によって呼び出され、トランジションまたはエフェクトのプロパティを設定する。通常、アプリケーションではこのメソッドを呼び出さない。

pTarget で指定されるオブジェクトは、IDispatch インターフェイスを実装していなければならない。


IRenderEngine インターフェイス

タイムラインからフィルタ グラフを構築することにより、Microsoft® DirectShow® 編集サービス (DES) プロジェクトをレンダリングする。

DES は、このインターフェイスを実装する 2 つのコンポーネントを提供している。

  • 基本レンダリング エンジンは、圧縮されていない出力を生成する。この出力は、プレビューに使用でき、また圧縮フィルタを経由して最終出力ファイルの書き込みにも使用できる。
  • スマート レンダリング エンジンは、スマート再圧縮を使用して、圧縮された出力を生成する。スマート再圧縮を使用すると、ソース ファイルのフォーマットが出力フォーマットと異なる場合にのみ、ソース ファイルが再圧縮される。ソースのフォーマットが一致しているときには、出力ファイルに直接書き込まれる。状況によって、スマート再圧縮ではレンダリング時間を大幅に改善できる。

スマート レンダリング エンジンは、ISmartRenderEngine インターフェイスもサポートしている。

アプリケーションでフィルタ グラフを作成してレンダリング エンジンに渡すことはできるが、通常の状況では、レンダリング エンジンにフィルタ グラフを作成させる。グラフの作成は、2 段階の処理で行われる。まず、ConnectFrontEnd メソッドを呼び出してフロント エンドを構築する。次に、フロント エンドの出力ピンを目的のレンダリング フィルタに接続する。

  • プレビュー用のビデオ レンダラおよびオーディオ レンダラ、または
  • コンプレッサ、マルチプレクサ、および最終出力を生成するファイル ライタ。

詳細については、「プロジェクトのレンダリング」を参照すること。

要件

Qedit.h が必要である。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IRenderEngine メソッド | 説明
SetTimelineObject | 使用するレンダリング エンジン用のタイムラインを設定する。
GetTimelineObject | レンダリング エンジンが現在使用しているタイムラインを取得する。
GetFilterGraph | レンダリング エンジンが構築したフィルタ グラフ (ある場合) を取得する。
SetFilterGraph | 使用するレンダリング エンジン用のフィルタ グラフを指定する。
SetInterestRange | サポートされていない。
SetInterestRange2 | サポートされていない。
SetRenderRange | タイムライン上の、レンダリングされる時間の範囲を設定する。
SetRenderRange2 | SetRenderRange と同じ機能だが、double 型のパラメータをとる。
GetGroupOutputPin | 指定されたグループの出力ピンを取得する。
ScrapIt | レンダリング エンジンのフィルタ グラフおよび関連付けられているすべてのオブジェクトを破棄する。
RenderOutputPins | フィルタ グラフのプレビュー部分を作成する。
GetVendorString | ベンダー文字列を取得する。
ConnectFrontEnd | 現在のタイムラインからフィルタ グラフのフロント エンドを構築する。
SetSourceConnectCallback | サポートされていない。
SetDynamicReconnectLevel | レンダリング時の動的再接続のレベルを設定する。
DoSmartRecompression | サポートされていない。
UseInSmartRecompressionGraph | サポートされていない。
SetSourceNameValidation | レンダリング エンジンがファイル名を検証する方法を指定する。
Commit | 実装されていない。
Decommit | 実装されていない。
GetCaps | 実装されていない。

IRenderEngine::Commit

IRenderEngine インターフェイス

実装されていない。

構文

HRESULT Commit( void );

IRenderEngine::ConnectFrontEnd

IRenderEngine インターフェイス

現在のタイムラインからフィルタ グラフのフロント エンドを構築する。

構文

HRESULT ConnectFrontEnd( void );

戻り値

HRESULT 値を返す。可能な戻り値は次のとおりである。

S_OK | 成功。
S_WARN_OUTPUTRESET | フラフのレンダリング部分は削除された。
E_INVALIDARG | このレンダリング エンジンにはタイムラインは設定されていない。
E_MUST_INIT_RENDERER | レンダリング エンジンが初期化に失敗した。
E_RENDER_ENGINE_IS_BROKEN | プロジェクトが正しくレンダリングされなかったため、処理に失敗。
E_UNEXPECTED | 予期しないエラー。
VFW_E_INVALIDMEDIATYPE | 無効なメディア タイプ。

注意

このメソッドは、フィルタ グラフのレンダリング部分を構築しない。アプリケーションでは、フロント エンドの出力ピンを目的のレンダリング フィルタに接続しなければならない。

  • プレビューを行うには、RenderOutputPins メソッドを呼び出す。
  • ファイルに出力するには、GetGroupOutputPin を呼び出してグループごとの出力ピンを取得してから、そのピンをマルチプレクサ フィルタに接続する。

基本レンダリング エンジンを使っている場合、フロント エンド上の出力ピンは非圧縮データを生成する。スマート レンダリング エンジンを使っている場合、出力ピンは圧縮データを出力する。

フィルタ グラフを構築した後でタイムラインを変更した場合は、ConnectFrontEnd をもう一度呼び出してフロント エンドを再構築しなければならない。このメソッドは、可能であればグラフのレンダリング部分を維持する。しかし、グループを追加または削除した場合、またはグループの順序を変更した場合は、ConnectFrontEnd はレンダリング部分を削除するため、アプリケーションはレンダリング部分を再構築しなければならない。レンダリング部分を削除した場合、このメソッドは S_WARN_OUTPUTRESET を返す。

IRenderEngine::Decommit

IRenderEngine インターフェイス

実装されていない。

構文

HRESULT Decommit( void );

IRenderEngine::DoSmartRecompression

IRenderEngine インターフェイス

サポートされていない。

構文

HRESULT DoSmartRecompression( void );

IRenderEngine::GetCaps

IRenderEngine インターフェイス

実装されていない。

構文

HRESULT GetCaps(
    long Index,
    long *pReturn
);

IRenderEngine::GetFilterGraph

IRenderEngine インターフェイス

レンダリング エンジンが構築したフィルタ グラフ (ある場合) を取得する。

構文

HRESULT GetFilterGraph(
    IGraphBuilder **ppFG
);

パラメータ

ppFG
[out] フィルタ グラフの IGraphBuilder インターフェイスを受け取るポインタのアドレス。フィルタ グラフがない場合は、値 NULL を受け取る。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_MUST_INIT_RENDERER | レンダリング エンジンが初期化に失敗した。
E_POINTER | 無効なポインタ。

注意

復帰時に *ppFG の値が NULL 以外の場合、IGraphBuilder インターフェイスは未処理のカウントを持つ。使い終わった場合は、インターフェイスを必ず解放すること。

IRenderEngine::GetGroupOutputPin

IRenderEngine インターフェイス

指定されたグループの出力ピンを取得する。

構文

HRESULT GetGroupOutputPin(
    long Group,
    IPin **ppRenderPin
);

パラメータ

Group
グループを指定する、ゼロから始まるインデックス。
ppRenderPin
[out] 出力ピンの IPin インターフェイスを受け取るポインタのアドレス。

戻り値

HRESULT 値を返す。可能な値は次のとおりである。

S_FALSE | グループは出力ピンを持っていない。
S_OK | 成功。
E_INVALIDARG | 無効な引数。
E_MUST_INIT_RENDERER | レンダリング エンジンが初期化に失敗した。
E_POINTER | 無効なポインタ。
E_RENDER_ENGINE_IS_BROKEN | プロジェクトが正しくレンダリングされなかったため、処理に失敗。
E_UNEXPECTED | 予期しないエラー。

注意

このメソッドを呼び出す前に、ConnectFrontEnd を呼び出してグラフのフロント エンドを構築する。各グループは単一のメディア ストリームを表し、フロント エンドには対応する出力ピンがある。

このメソッドを使用して、ファイル書き込みグラフのレンダリング部分を作成できる。出力ピンをマルチプレクサおよびファイル ライタ フィルタに接続する。詳細については、「プロジェクトのレンダリング」を参照すること。

プレビューの場合は、このメソッドを呼び出す必要はない。単純に、ConnectFrontEnd の後に RenderOutputPins を呼び出せばよい。

メソッドが S_OK を返した場合、返される IPin インターフェイスは未処理の参照カウントを持つ。使い終わった場合は、インターフェイスを必ず解放すること。

IRenderEngine::GetTimelineObject

IRenderEngine インターフェイス

レンダリング エンジンが現在使用しているタイムラインを取得する。

構文

HRESULT GetTimelineObject(
    IAMTimeline **ppTimeline
);

パラメータ

ppTimeline
[out] タイムラインの IAMTimeline インターフェイスを受け取るポインタのアドレス。タイムラインがない場合は、値 NULL を受け取る。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_POINTER | 無効なポインタ。
E_MUST_INIT_RENDERER | レンダリング エンジンが初期化に失敗した。

注意

復帰時に *ppTimeline の値が NULL 以外の場合、IAMTimeline インターフェイスは未処理のカウントを持つ。使い終わった場合は、インターフェイスを必ず解放すること。

IRenderEngine::GetVendorString

IRenderEngine インターフェイス

ベンダー文字列を取得する。

構文

HRESULT GetVendorString(
    BSTR *pVendorID
);

パラメータ

pVendorID
[out, retval] ベンダー文字列を持つ BSTR を受け取る変数へのポインタ。

戻り値

成功した場合、メソッドは S_OK を返す。それ以外の場合は、エラーの発生を示す HRESULT 値を返す。

注意

このメソッドは、文字列に必要なメモリを割り当てる。アプリケーションは SysFreeString を呼び出して、メモリを解放しなければならない。

IRenderEngine::RenderOutputPins

IRenderEngine インターフェイス

フィルタ グラフのプレビュー部分を作成する。

構文

HRESULT RenderOutputPins( void );

戻り値

HRESULT 値を返す。可能な値は次のとおりである。

S_OK | 成功。
VFW_S_AUDIO_NOT_RENDERED | オーディオ ストリームを再生できない。
E_INVALIDARG | 無効な引数。
E_RENDER_ENGINE_IS_BROKEN | プロジェクトが正しくレンダリングされなかったため、処理に失敗。
E_UNEXPECTED | 予期しないエラー。

注意

このメソッドを呼び出す前に、ConnectFrontEnd を呼び出してグラフのフロント エンドを構築する。プレビュー以外の処理を行う場合は、このメソッドを呼び出してはならない。代わりに、GetGroupOutputPin を呼び出して出力ピンへのポインタを取得する。

ユーザーのコンピュータにサウンド カードがない場合、このメソッドは VFW_S_AUDIO_NOT_RENDERED を返す。この場合にはオーディオのプレビューは行われないが、ビデオ プレビューには影響はない。

ピンがビデオ グループからのものである場合、このメソッドはメッセージをディスパッチしなければならない、たとえばウィンドウを動かすには、ウィンドウのクライアント エリアのマウス クリックに対応しなければならない。

IRenderEngine::ScrapIt

IRenderEngine インターフェイス

レンダリング エンジンのフィルタ グラフおよび関連付けられているすべてのオブジェクトを破棄する。

構文

HRESULT ScrapIt( void );

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_MUST_INIT_RENDERER | レンダリング エンジンが初期化に失敗した。

IRenderEngine::SetDynamicReconnectLevel

IRenderEngine インターフェイス

レンダリング時の動的再接続のレベルを設定する。

構文

HRESULT SetDynamicReconnectLevel(
    DWORD Level
);

パラメータ

Level
動的再接続フラグの組み合わせ。動的再接続のレベルを指定する。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_NOTIMPL | 実装されていない。

注意

デフォルトでは、基本レンダリング エンジンはプロジェクトをレンダリングする前にすべてのソースをロードする。このため、起動時間が長くなることがある。動的再接続を使用した場合、ソースは必要なときにのみロードされる。これによって起動時間は短くなるが、スムースな再生が妨げられることがある。一般的には、プロジェクトで使用するソース クリップが多くなるに従い、動的再接続を使用するメリットが大きくなる。

スマート レンダリング エンジンは、このメソッドを実装していない。

IRenderEngine::SetFilterGraph

IRenderEngine インターフェイス

使用するレンダリング エンジン用のフィルタ グラフを指定する。

構文

HRESULT SetFilterGraph(
    IGraphBuilder *pFG
);

パラメータ

pFG
フィルタ グラフの IGraphBuilder インターフェイスへのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_INVALIDARG | 無効な引数。
E_MUST_INIT_RENDERER | レンダリング エンジンが初期化に失敗した。

注意

ほとんどのアプリケーションではこのメソッドを呼び出す必要はない。より一般的な方法は、ConnectFrontEnd メソッドを呼び出すことにより、レンダリング エンジンにグラフを構築させることである。

レンダリング エンジンに既にフィルタ グラフがある場合、このメソッドは失敗する。

レンダリング エンジンが作成したフィルタ グラフへのポインタを取得し、それをパラメータとして別のレンダリング エンジンでこのメソッドを呼び出してはならない。それを行うと、予期できない結果を引き起こすことになる。

IRenderEngine::SetInterestRange

IRenderEngine インターフェイス

サポートされていない。

構文

HRESULT SetInterestRange(
    REFERENCE_TIME Start,
    REFERENCE_TIME Stop
);

IRenderEngine::SetInterestRange2

IRenderEngine インターフェイス

サポートされていない。

構文

HRESULT SetInterestRange2(
    double Start,
    double Stop
);

IRenderEngine::SetRenderRange

IRenderEngine インターフェイス

タイムライン上の、レンダリングされる時間の範囲を設定する。指定された範囲の外にあるオブジェクトはレンダリングされず、それらに対してリソースは割り当てられない。

構文

HRESULT SetRenderRange(
    REFERENCE_TIME Start,
    REFERENCE_TIME Stop
);

パラメータ

Start
開始タイム (100 ナノ秒単位)。
Stop
終了タイム (100 ナノ秒単位)。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_MUST_INIT_RENDERER | レンダリング エンジンが初期化に失敗した。

IRenderEngine::SetRenderRange2

IRenderEngine インターフェイス

タイムライン上の、レンダリングされる時間の範囲を設定する。このメソッドは SetRenderRange と同じ機能だが、double 型のパラメータをとる。

構文

HRESULT SetRenderRange2(
    double Start,
    double Stop
);

パラメータ

Start
開始タイム (秒単位)。
Stop
終了タイム (秒単位)。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_MUST_INIT_RENDERER | レンダリング エンジンが初期化に失敗した。

IRenderEngine::SetSourceConnectCallback

IRenderEngine インターフェイス

サポートされていない。

構文

HRESULT SetSourceConnectCallback(
    IGrfCache *pCallback
);

IRenderEngine::SetSourceNameValidation

IRenderEngine インターフェイス

レンダリング エンジンがファイル名を検証する方法を指定する。

構文

HRESULT SetSourceNameValidation(
    BSTR FilterString,
    IMediaLocator *pOverride,
    LONG Flags
);

パラメータ

FilterString
Microsoft® Win32® の OPENFILENAME 構造体の lpstrFilter メンバで必要な書式に設定されたフィルタ文字列のペアを含む BSTR 値。メディア ロケータは、エンド ユーザーに [開く] ダイアログ ボックスを表示する場合に、このフィルタを使用する。
pOverride
デフォルトの代わりに使用するメディア ロケータの IMediaLocator インターフェイスへのオプションのポインタ。デフォルトのメディア ロケータを使用する場合は、このパラメータを NULL に設定する。詳細については、「注意」を参照すること。
Flags
メディア ロケータの動作を指定するフラグのビットごとの組み合わせ。SFN_VALIDATEF_CHECK フラグは、必ず設定されていなければならない。SFN_VALIDATEF_IGNOREMUTED フラグは、このメソッドでは意味を持たない。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_MUST_INIT_RENDERER | レンダリング エンジンが初期化に失敗した。

注意

pOverride パラメータを使用すると、IMediaLocator インターフェイスの独自のカスタム実装を使用できる。たとえば、デフォルトのメディア ロケータは、見つかった (または見つからなかった) ファイルについてアプリケーションに通知を行わない。このような制限を回避するために、カスタム メディア ロケータを実装して、デフォルト バージョンのラッパーとすることができる。そして、デフォルト バージョンに IMediaLocator::FindMediaFile 呼び出しを直接渡して、その戻り値を調べる。

現在、このメソッドは動的にロードされたソースを検証しない。詳細については、「SetDynamicReconnectLevel」を参照すること。

IRenderEngine::SetTimelineObject

IRenderEngine インターフェイス

使用するレンダリング エンジン用のタイムラインを設定する。

構文

HRESULT SetTimelineObject(
    IAMTimeline *pTimeline
);

パラメータ

pTimeline
タイムライン オブジェクトの IAMTimeline インターフェイスへのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_MUST_INIT_RENDERER | レンダリング エンジンが初期化に失敗した。
E_OUTOFMEMORY | メモリ不足。
E_POINTER | 無効なポインタ。

IRenderEngine::UseInSmartRecompressionGraph

IRenderEngine インターフェイス

サポートされていない。

構文

HRESULT UseInSmartRecompressionGraph( void );


ISmartRenderEngine インターフェイス

Microsoft® DirectShow® 編集サービス (DES) のスマート再圧縮をサポートするメソッドを提供する。スマート レンダリング エンジンは、このインターフェイスを公開する。ISmartRenderEngine の使い方の詳細については、「プロジェクトのレンダリング」を参照すること。

要件

Qedit.h が必要である。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
ISmartRenderEngine メソッド | 説明
SetGroupCompressor | 指定されたグループをレンダリングするときに使用する圧縮フィルタを指定する。
GetGroupCompressor | 指定されたグループの圧縮フィルタを取得する。
SetFindCompressorCB | 実装されていない。

ISmartRenderEngine::GetGroupCompressor

ISmartRenderEngine インターフェイス

指定されたグループの圧縮フィルタを取得する。

構文

HRESULT GetGroupCompressor(
    long Group,
    IBaseFilter **pCompressor
);

パラメータ

Group
ゼロから始まるグループのインデックス。
pCompressor
[out] 圧縮フィルタの IBaseFilter インターフェイスを受け取るポインタのアドレス。圧縮フィルタがない場合は、値 NULL を受け取る。

戻り値

次のいずれかの値を返す。

E_INVALIDARG | 無効な引数。
E_POINTER | NULL ポインタ エラー。
S_OK | 成功。

注意

このメソッドを使って、キー フレーム レートなどの圧縮フィルタのプロパティを設定する。このメソッドは、IRenderEngine::ConnectFrontEnd を呼び出した後、プロジェクトをレンダリングする前に呼び出す。次に、圧縮パラメータ設定用のメソッドが含まれる IAMVideoCompression インターフェイスについて、圧縮フィルタの出力ピンに照会する。使用が終わったらインターフェイスを解放する。それ以降にタイムラインに変更を加えた場合は、ConnectFrontEnd を呼び出してから GetGroupCompressor を呼び出し、圧縮パラメータを再設定しなければならない。

復帰時に *ppCompressor の値が NULL 以外の場合、IBaseFilter インターフェイスは未処理のカウントを持つ。使い終わった場合は、インターフェイスを必ず解放すること。

ISmartRenderEngine::SetFindCompressorCB

ISmartRenderEngine インターフェイス

実装されていない。

構文

HRESULT SetFindCompressorCB(
    IFindCompressorCB *pCallback
);

ISmartRenderEngine::SetGroupCompressor

ISmartRenderEngine Interface

指定されたグループをレンダリングするときに使用する圧縮フィルタを指定する。

構文

HRESULT SetGroupCompressor(
    long Group,
    IBaseFilter *pCompressor
);

パラメータ

Group
ゼロから始まるグループのインデックス。
pCompressor
圧縮フィルタの IBaseFilter インターフェイスへのポインタ。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_INVALIDARG を返す。


IXml2Dex インターフェイス

Microsoft® DirectShow® 編集サービス (DES) の、拡張可能マークアップ言語 (XML) で記述されたプロジェクト ファイルの保存とロードを行う。このインターフェイスは、DirectShow グラフ (.grf) ファイルの読み込みと書き込みを行うメソッドも提供する。

要件

Qedit.h を必要とする。

Internet Explorer 4.0 以降を必要とする。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IXml2Dex メソッド | 説明
CreateGraphFromFile | 実装されていない。
WriteGrfFile | フィルタ グラフを .grf フォーマットでファイルに書き込む。
WriteXMLFile | タイムラインを XML に変換し、XML データをファイルに書き込む。
ReadXMLFile | XML プロジェクト ファイルをロードする。
Delete | 実装されていない。
WriteXMLPart | 実装されていない。
PasteXMLFile | 実装されていない。
CopyXML | 実装されていない。
PasteXML | 実装されていない。
Reset | 実装されていない。
ReadXML | 実装されていない。
WriteXML | タイムラインを XML 文字列に変換する。

IXml2Dex::CopyXML

IXml2Dex インターフェイス

実装されていない。

構文

HRESULT CopyXML(
    IUnknown *pTimeline,
    double dStart,
    double dEnd
);

IXml2Dex::CreateGraphFromFile

IXml2Dex インターフェイス

実装されていない。

構文

HRESULT CreateGraphFromFile(
    IUnknown **ppGraph,
    IUnknown *pTimeline,
    BSTR FileName
);

IXml2Dex::Delete

IXml2Dex インターフェイス

実装されていない。

構文

HRESULT Delete(
    IUnknown *pTimeline,
    double dStart,
    double dEnd
);

IXml2Dex::PasteXML

IXml2Dex インターフェイス

実装されていない。

構文

HRESULT PasteXML(
    IUnknown *pTimeline,
    double dStart
);

IXml2Dex::PasteXMLFile

IXml2Dex インターフェイス

実装されていない。

構文

HRESULT PasteXMLFile(
    IUnknown *pTimeline,
    double dStart,
    BSTR FileName
);

IXml2Dex::ReadXML

IXml2Dex インターフェイス

実装されていない。

構文

HRESULT ReadXML(
    IUnknown *pTimeline,
    IUnknown *pXML
);

IXml2Dex::ReadXMLFile

IXml2Dex インターフェイス

XML プロジェクト ファイルをロードする。このメソッドは、XML ファイルで表現されているすべてのオブジェクトのインスタンスを作成してタイムラインに挿入し、フレーム レートやデフォルト エフェクトなどの所定の属性をタイムラインに適用する。

構文

HRESULT ReadXMLFile(
    IUnknown *pTimeline,
    BSTR XMLName
);

パラメータ

pTimeline
タイムライン オブジェクトの IUnknown インターフェイスへのポインタ。
XMLName
ロードするファイルの名前を指定する文字列。

戻り値

成功した場合は、S_OK を返す。そうでない場合は、VFW_E_INVALID_FILE_FORMAT などの他のエラー コードを返す。

注意

このメソッドは、XML ファイルで定義されている新しいオブジェクトをタイムラインに挿入する前に、タイムラインから既存のオブジェクトをクリアしない。既存のタイムラインを更新する必要がある場合は、先に IAMTimeline::ClearAllGroups を呼び出す。

IXml2Dex::Reset

IXml2Dex インターフェイス

実装されていない。

構文

HRESULT Reset(void);

IXml2Dex::WriteGrfFile

IXml2Dex インターフェイス

フィルタ グラフを .grf フォーマットでファイルに書き込む。

構文

HRESULT WriteGrfFile(
    IUnknown *pGraph,
    BSTR FileName
);

パラメータ

pGraph
フィルタ グラフの IUnknown インターフェイスを指すポインタ。
FileName
書き込むファイルの名前を指定する文字列。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
S_OK | 成功。

このメソッドは、IStorage::CreateStream および IPersist::Save メソッドの内部呼び出しで返されたエラー コードを返すこともある。詳細については、Platform SDK を参照すること。

IXml2Dex::WriteXML

IXml2Dex インターフェイス

タイムラインを XML 文字列に変換する。

構文

HRESULT WriteXML(
    IUnknown *pTimeline,
    BSTR *pbstrXML
);

パラメータ

pTimeline
タイムライン オブジェクトの IUnknown インターフェイスへのポインタ。
pbstrXML
タイムラインを記述する XML 文字列を受け取る BSTR 型の変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。変換に必要なメモリが足りない場合は、E_OUTOFMEMORY を返す。それ以外の場合は、他のエラー コードを返す。

注意

このメソッドは、文字列にメモリを割り当てる。アプリケーションは SysFreeString を呼び出し、メモリを解放しなければならない。

IXml2Dex::WriteXMLFile

IXml2Dex インターフェイス

タイムラインを XML に変換し、XML データをファイルに書き込む。

構文

HRESULT WriteXMLFile(
    IUnknown *pTimeline,
    BSTR FileName
);

パラメータ

pTimeline
タイムライン オブジェクトの IUnknown インターフェイスへのポインタ。
FileName
書き込むファイルの名前を指定する文字列。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_INVALIDARG | 引数が無効。
E_OUTOFMEMORY | メモリ不足。
S_OK | 成功。

注意

このメソッドは、タイムライン内のすべてのコンポーネントを表す XML ファイルを生成する。

IXml2Dex::WriteXMLPart

IXml2Dex インターフェイス

実装されていない。

構文

HRESULT WriteXMLPart(
    IUnknown *pTimeline,
    double dStart,
    double dEnd,
    BSTR FileName
);


構造体

Microsoft® DirectShow® 編集サービスは、以下の構造体を定義している。

構造体 | 説明
DEXTER_PARAM | トランジションまたはエフェクトのプロパティを指定する。
DEXTER_VALUE | プロパティの値を指定する。
SCompFmt0 | スマート再圧縮のフォーマット情報を保持する。


DEXTER_PARAM 構造体

プロパティが所定の時点で想定される値を指定する。

構文

typedef struct {
    BSTR      Name;
    DISPID    dispID;
    LONG      nValues;
} DEXTER_PARAM;

メンバ

Name
プロパティの名前。
dispID
プロパティのディスパッチ ID (DISPID)。Name メンバが指定されている場合はゼロ。
nValues
そのプロパティで想定される値の個数。

注意

オブジェクトは、IDispatch インターフェイスをサポートしていなければならない。

プロパティの DISPID がわかっている場合は、dispID メンバを設定できる。ただし、通常は Name メンバにプロパティのテキスト名を設定し、dispID は 0 に設定する。プロパティ セッターは、IDispatch::GetIDsOfNames を呼び出して、DISPID を取得する。

参照

IPropertySetter、DEXTER_VALUE


DEXTER_VALUE 構造体

トランジションまたはエフェクトに設定されるプロパティを識別し、トランジションまたはエフェクトの時間幅の経過に伴って想定されるプロパティの値を指定する。

構文

typedef struct {
    VARIANT           v;
    REFERENCE_TIME    rt;
    DWORD             dwInterp;
} DEXTER_VALUE;

メンバ

v
プロパティの値。
rt
プロパティがこの値であると見なされる、トランジションまたはエフェクトの開始タイム相対の時間。
dwInterp
プロパティが前の値からこの値にどのように変化するかを示すフラグ。次のいずれかでなければならない。
DEXTERF_JUMP | プロパティは指定された時点で即座に新しい値に切り替わる。
DEXTERF_INTERPOLATE | プロパティは、前の値から時間の経過に伴って線形的に補間される。

参照

IPropertySetter、DEXTER_PARAM


SCompFmt0 構造体

スマート再圧縮のフォーマット情報を保持する。

構文

typedef struct _SCompFmt0
{
    long nFormatId;
    AM_MEDIA_TYPE MediaType;
} SCompFmt0;

メンバ

nFormatId
予約済み。ゼロでなければならない。
MediaType
圧縮フォーマットを記述する AM_MEDIA_TYPE 構造体。

参照

IAMTimelineGroup::GetSmartRecompressFormat、IAMTimelineGroup::SetSmartRecompressFormat


列挙型

Microsoft® DirectShow® 編集サービスは、以下の列挙型を定義している。

列挙型

DEXTERF_TRACK_SEARCH_FLAGS | タイムライン内のオブジェクトを検索する際の境界条件を指定する。
TIMELINE_MAJOR_TYPE | タイムライン オブジェクトのメジャー タイプを指定する。


DEXTERF_TRACK_SEARCH_FLAGS 列挙型

タイムライン内のオブジェクトを検索する際の境界条件を指定する。

構文

typedef enum
{
    DEXTERF_BOUNDING = -1,
    DEXTERF_EXACTLY_AT = 0,
    DEXTERF_FORWARDS = 1
} DEXTERF_TRACK_SEARCH_FLAGS;

要素

DEXTERF_BOUNDING
指定された時間にかかっているオブジェクトを検索する。
DEXTERF_EXACTLY_AT
指定された時間に、正確に始まるオブジェクトを検索する。
DEXTERF_FORWARDS
指定された時間以降に始まるオブジェクトを検索する。

注意

これらの境界条件の要約を次の表に示す。

列挙値 | 境界条件
DEXTERF_BOUNDING Start <= Time
Stop > Time
DEXTERF_EXACTLY_AT | Start == Time
DEXTERF_FORWARDS | Start >= Time
  • Start : 取得されるオブジェクトの開始タイム。
  • Stop : 取得されるオブジェクトの終了タイム。
  • Time : 検索に指定された時間。

参照

IAMTimelineTrack::GetSrcAtTime


TIMELINE_MAJOR_TYPE 列挙型

オブジェクトのメジャー タイプを指定する。

構文

typedef enum
{
    TIMELINE_MAJOR_TYPE_COMPOSITE = 1,
    TIMELINE_MAJOR_TYPE_TRACK = 2,
    TIMELINE_MAJOR_TYPE_SOURCE = 4,
    TIMELINE_MAJOR_TYPE_TRANSITION = 8,
    TIMELINE_MAJOR_TYPE_EFFECT = 16,
    TIMELINE_MAJOR_TYPE_GROUP = 128
} TIMELINE_MAJOR_TYPE;

要素

TIMELINE_MAJOR_TYPE_COMPOSITE
合成オブジェクト。1 つ以上のトラックを保持する。
TIMELINE_MAJOR_TYPE_TRACK
トラック オブジェクト。1 つ以上のソースを保持する。
TIMELINE_MAJOR_TYPE_SOURCE
ソース オブジェクト。メディア ソースへの参照が含まれる。
TIMELINE_MAJOR_TYPE_TRANSITION
トランジション オブジェクト。合成、トラック、またはソース間のトランジションを定義する。
TIMELINE_MAJOR_TYPE_EFFECT
エフェクト オブジェクト。合成、トラック、またはソース オブジェクトに適用される単一入力エフェクトを定義する。
TIMELINE_MAJOR_TYPE_GROUP
グループ オブジェクト。所定の型の 1 つ以上のトラックが含まれる。

参照

IAMTimeline、IAMTimelineComp::GetCountOfType、IAMTimelineObj::GetTimelineType


定数

Microsoft® DirectShow® 編集サービスは、以下の定数を定義している。

  • 動的再接続フラグ
  • ファイル名検証フラグ
  • サイズ変更フラグ

動的再接続フラグ

これらのフラグは、レンダリング中に使用される動的再接続のレベルを指定する。

定数 | 値 | 説明
CONNECTF_DYNAMIC_NONE | 0x00 | 動的再接続なし。プロジェクトをレンダリングする前にすべてをロードする。
CONNECTF_DYNAMIC_SOURCES | 0x01 | 必要なときにのみソースをロードする。
CONNECTF_DYNAMIC_EFFECTS | 0x02 | 予約済み。 使用してはならない。

参照

IRenderEngine::SetDynamicReconnectLevel

ファイル名検証フラグ

これらのフラグは、メディア ロケータの動作を指定する。

定数 | 値 | 説明
SFN_VALIDATEF_CHECK | 0x01 | ファイル名の妥当性をチェックする。ファイル名を検証するためには、このフラグを設定しなければならない。このフラグを設定しないと、他のフラグは意味を持たない。
SFN_VALIDATEF_POPUP | 0x02 | ファイルが見つからなかった場合、エンド ユーザーに [ファイルを開く] ダイアログ ボックスを表示する。
SFN_VALIDATEF_TELLME | 0x04 | 不足ファイルが見つかったときに、ファイルの名前と場所を示すメッセージ ボックスを短時間表示する。このフラグは、ほぼテスト用にのみ有用である。このメッセージ ボックスは、おそらくリテール製品には適していない。
SFN_VALIDATEF_REPLACE | 0x08 | 不足ファイルが見つかったときに、ソース オブジェクトの名前を更新する (IAMTimeline::ValidateSourceNames メソッドでのみ有効)。
SFN_VALIDATEF_USELOCAL | 0x10 | たとえそのファイルの別バージョンがネットワークにあっても、ローカル ファイルがいつも使用される。詳細については、「IMediaLocator::FindMediaFile」と「IRenderEngine::SetSourceNameValidation」を参照すること。
SFN_VALIDATEF_NOFIND | 0x20 | 不足ファイルの検索を行わない。SFN_VALIDATEF_CHECK フラグを設定しても、ファイル名の妥当性は検証される。
SFN_VALIDATEF_IGNOREMUTED | 0x40 | ミュートされたソース オブジェクトを無視する (IAMTimeline::ValidateSourceNames メソッドでのみ有効)。

参照

IMediaLocator::FindMediaFile、IRenderEngine::SetSourceNameValidation

サイズ変更フラグ

これらのフラグは、ビデオ ソースのサイズが出力ディメンジョンと一致しないときに、どのようにレンダリングされるかを指定する。

定数 | 値 | 説明
RESIZEF_STRETCH | 0 | イメージは、アスペクト比を維持せずに、ターゲット フレームの縦と横の両方に合わせて伸縮される。
RESIZEF_CROP | 1 | イメージのサイズは変更されない。イメージがターゲット フレームより小さい場合、まわりの領域は黒になる。イメージがターゲット フレームより大きい場合、イメージは切り詰められる。
RESIZEF_PRESERVEASPECTRATIO | 2 | イメージのサイズは、アスペクト比を維持して、ターゲット フレームの縦または横のどちらか一方に合わせて変更される。イメージの高さに対する幅の比がターゲット フレームの同様の比と一致しない場合は、レターボックスが作成される。
RESIZEF_PRESERVEASPECTRATIO_NOLETTERBOX | 3 | イメージのサイズは、アスペクト比を維持して、ターゲット フレーム全体を満たすように変更される。このモードでは、レターボックスは作成されず、イメージの左右または上下の両端が切り詰められる。

以下のイメージは、これらのフラグの効果を示している。

参照

IAMTimelineSrc::GetStretchMode、IAMTimelineSrc::SetStretchMode


トランジションおよびエフェクト

ここでは、Microsoft® DirectShow® 編集サービスで提供されるエフェクトとトランジションについて説明する。

トランジション

コンポジタ | 背景を変更せずに、対象の矩形に合わせて前景を伸縮する。
キー | クロマ、アルファ、色相、または輝度に基づいてキーイングを行う。
SMPTE ワイプ | 標準 SMPTE ワイプを行う。

エフェクト

アルファ セッター | ビデオ イメージのアルファ ビットを設定する。
ボリューム エンベロープ | オーディオ ストリームのボリュームを設定する。

ソース オブジェクト

ビデオ カラー ソース 単色の連続したビデオ イメージを作成する。


アルファ セッター エフェクト

ビデオ イメージにアルファ ビットを設定する。

クラス ID (CLSID) : 506D89AE-909A-44f7-9444-ABD575896E35

CLSID 変数名 : CLSID_DxtAlphaSetter

プロパティ

プロパティ | 型 | デフォルト | 説明
Alpha | BYTE | -1 | イメージ全体にアルファを設定する。
AlphaRamp | double | -1.0 | 元のアルファ値の割合としてアルファを設定する。

注意

負の値のプロパティは無視される。1 つのプロパティだけが負でない値を持つことができる。Alpha プロパティには、イメージの各ピクセルに一定のアルファ値を指定する。このプロパティは、元のイメージのアルファ値にオーバーライドされる。AlphaRamp プロパティには、各ピクセルのアルファ値をピクセルの元の値の割合として、0.0 ～ 1.0 で指定する。

参照


コンポジタ トランジション

前景のサブ矩形を、背景の他の部分を変更せずに、背景の指定された矩形に合成する。このトランジションを使用して、スプリット スクリーンまたはピクチャ イン ピクチャ エフェクトを作成できる。

次のイメージは、コンポジタ トランジションを示している。

クラス ID (CLSID) : BB44391D-6ABD-422f-9E2E-385C9DFF51FC

CLSID 変数名 : CLSID_DxtCompositor

プロパティ

プロパティ | 型 | デフォルト | 説明
Height | long | 0 | ターゲット矩形の高さ (ピクセル単位)。
OffsetX | long | 0 | ターゲット矩形の水平方向のオフセット (ピクセル単位)。
OffsetY | long | 0 | ターゲット矩形の垂直方向のオフセット (ピクセル単位)。
SrcHeight | long | 0 | ソースのサブ矩形の高さ (ピクセル単位)。
SrcOffsetX | long | 0 | ソースのサブ矩形の x 座標 (ピクセル単位)。
SrcOffsetY | long | 0 | ソースのサブ矩形の y 座標 (ピクセル単位)。
SrcWidth | long | 0 | ソースのサブ矩形の幅 (ピクセル単位)。
Width | long | 0 | ターゲット矩形の幅 (ピクセル単位)。

次の図は、これらのプロパティを示している。


キー トランジション

RGB 値、アルファ値、色相、または輝度に基づいてキーイングを実行する。

次のイメージは、キー トランジションを示している。

クラス ID (CLSID) : C5B19592-145E-11D3-9F04-006008039E37

CLSID 変数名 : CLSID_DxtKey

プロパティ

プロパティ | 型 | 有効な範囲 | 説明 | 適用先
Hue | int | 0–360 | キーイングを行う色相値。 | 色相
Invert | BOOL | FALSE または TRUE | キーのデフォルト処理を逆にするかどうかを示すブール値。FALSE の場合、上になるイメージのピクセルはデフォルトの方法で透過にされる。TRUE の場合、逆の処理が行われる。 | クロマ、色相、輝度、非赤
KeyType | int | 「注意」を参照。 | キーのタイプを指定する。詳細については、「注意」を参照すること。 | すべて
Luminance | int | 0–100 | キーイングを行う輝度値。 | 輝度
RGB | DWORD | 0x0 – 0xFFFFFF | キーイングを行う色。値は、0xRRGGBB フォーマットの 16 進数値であり、RR は赤の値、GG は緑の値、BB は青の値である (純色の赤、緑、青は、それぞれ 0xFF0000、0x00FF00、0x0000FF となる)。 | クロマ、色相
Similarity | int | 0–100 | 透過になる色データの範囲。高い値ほど、透過になる同系の色の範囲が広くなる。 | クロマ、非赤

注意

実行されるキーのタイプは、KeyType プロパティの値によって決まる。この値は、以下のいずれかでなければならない。

値 | 列挙値 | 説明
0 | DXTKEY_RGB | クロマ キー (RGB 値によるキー)。
1 | DXTKEY_NONRED | 非赤キー (青と緑の領域が透過になる)。
2 | DXTKEY_LUMINANCE | 輝度キー。
3 | DXTKEY_ALPHA | アルファ値によるキー。
4 | DXTKEY_HUE | 色相によるキー。

デフォルトのキー タイプは DXTKEY_ALPHA である。


SMPTE ワイプ トランジション

Society of Motion Picture and Television Engineers (SMPTE) が SMPTE 文書 258M-1993 で定義している任意の標準ワイプを生成する。ただし、クアッド スプリットは除く。

次のイメージは、進行中のワイプ トランジションを示している。

クラス ID (CLSID) : DE75D012-7A65-11D2-8CEA-00A0C9441E20

CLSID 変数名 : CLSID_DxtJpeg

プロパティ

プロパティ | 型 | デフォルト | 説明
BorderColor | long | 0x000000 | ワイプ パターンの端を囲む枠の色。この属性の値は、0xRRGGBB フォーマットの 16 進数値であり、RR は赤の 16 進値、GG は緑の 16 進値、BB は青の 16 進値である (したがって、純色の赤、緑、青は、それぞれ 0xFF000、0x00FF00、0x0000FF となる)。
BorderSoftness | long | 0 | ワイプ パターンの端を囲む、ぼやけたリージョンの幅。ぼやけたリージョンをなしにするには、ゼロを指定する。
BorderWidth | long | 0 | ワイプ パターンの端を囲む枠の幅。枠をなしにするには、ゼロを指定する。
MaskName | BSTR | NULL | NULL 以外の場合は、標準の組み込みワイプの代わりにワイプ マスクとして使用する JPEG ファイルの名前を指定する。ファイルは、モノクロで、ピクセル当たり 8 ビットの傾斜が含まれていなければならない。傾斜は、ワイプの進行を定義するマスクとして使用される。
MaskNum | long | 1 | 使用するワイプのスタイルを指定する標準 SMPTE ワイプ コード。ワイプ コードおよび対応するスタイルの一覧については、SMPTE 文書 258M-1993 を参照すること。
OffsetX | long | 0 | イメージの中心点からワイプの開始点までの、水平方向のオフセット。
OffsetY | long | 0 | イメージの中心点からワイプの開始点までの、垂直方向のオフセット。
ReplicateX | long | 0 | ワイプ パターンを水平方向に繰り返す回数。
ReplicateY | long | 0 | ワイプ パターンを垂直方向に繰り返す回数。
ScaleX | double | 1.0 | ワイプを水平方向に伸縮する量。ワイプの元の定義に対する割合で指定する。
ScaleY | double | 1.0 | ワイプを垂直方向に伸縮する量。ワイプの元の定義に対する割合で指定する。


ビデオ カラー ソース

単色の連続したビデオ イメージを作成する。

クラス ID (CLSID) : 1c621200-67b2-11d2-9eeb-006008039e37

CLSID 変数 : CLSID_ColorSource

プロパティ

プロパティ | 型 | デフォルト | 説明
Color | DWORD | 0 | 生成する色。この属性の値は 0xAARRGGBB フォーマットの 16 進数値であり、AA はアルファ値、RR は赤の値、GG は緑の値、BB は青の値を示す。アルファ値は 0x00 (透明) ～ 0xFF (不透明) の範囲である。このプロパティは静的であり、時間ゼロに適用されなければならない。

注意

ビデオ カラー ソースは、ソース オブジェクトと共に使われる。最初に、新しいソース オブジェクトを作成する。次に、IAMTimelineObj::SetSubobjectGUID メソッドを呼び出して、ソース オブジェクトのサブオブジェクト GUID に CLSID_ColorSource を設定する。

色を設定するには、プロパティ セッター オブジェクトを作成し、時間ゼロに Color プロパティを適用する。ビデオ カラー ソースは、このプロパティへの動的な変更をサポートしていない。この値は、時間と共に変更することはできない。

次のサンプル コードは、このオブジェクトの使い方を示している。IPropertySetter の使用の詳細については、「エフェクトおよびトランジションのプロパティの設定」を参照すること。

DWORD           dwYellow = 0xFFFF00;
IAMTimelineObj  *pSource = NULL;
IPropertySetter *pProp = NULL;

pTimeline->CreateEmptyNode(&pSourceObj, TIMELINE_MAJOR_TYPE_SOURCE);
pSource->SetStartStop(0, 50000000);
pSource->SetSubObjectGUID(CLSID_ColorSource);

// プロパティ セッターを作成する。
CoCreateInstance(CLSID_PropertySetter, NULL, CLSCTX_INPROC_SERVER,
    IID_IPropertySetter, (void**) &pProp);

// 色を設定する。
DEXTER_PARAM param;
DEXTER_VALUE val;

param.Name = SysAllocString(L"Color");
param.dispID = 0;
param.nValues = 1;

val.v.vt = VT_I4;
val.v.lVal = dwYellow;
val.rt = 0;  // 時間はゼロでなければならない。
val.dwInterp = DEXTERF_JUMP;

pProp->AddProp(param, &val);
pSource->SetPropertySetter(pProp);

// クリーン アップする。
SysFreeString(param.Name);
VariantClear(&val.v));
pProp->Release();

次のサンプル コードは、前の例で作成したオブジェクトの XML 表現を示している。この場合、PARAM タグは、AT タグおよび LINEAR タグをサポートしていない。これは、オブジェクトが動的なプロパティをサポートしていないためである。

<clip start="0" stop="5" clsid="{0CFDD070-581A-11D2-9EE6-006008039E37}">
<param name="Color" value="16776960"/>
</clip>


ボリューム エンベロープ エフェクト

オーディオ ストリームのボリュームを設定する。

クラス ID (CLSID) : 036A9790-C153-11D2-9EF7-006008039E37

CLSID 変数名 : CLSID_AudMixer

プロパティ

プロパティ | 型 | デフォルト | 説明
Vol | double | 1.0 | ボリューム。作成時のボリュームに対する割合で指定する。このプロパティ値を時間の経過に伴って変化させることで、オーディオ フェードを生成できる。

注意

タイムライン内の各オブジェクトが持つことができるボリューム エンベロープ エフェクトは、最大で 1 つである。トラック、合成、またはグループでは、ボリューム エンベロープは常に、他のオーディオ エフェクトの後で、最後に適用される (クリップでは、ボリューム エンベロープは、他のエフェクトと同様に、優先順位に従って適用される)。


DirectShow 編集サービスのコンポーネント

Microsoft® DirectShow® 編集サービス (DES) には、以下の COM コンポーネントが含まれている。「トランジションおよびエフェクト」も参照すること。

  • 合成
  • エフェクト
  • グループ
  • メディア ディテクタ
  • メディア ロケータ
  • プロパティ セッター
  • レンダリング エンジン (基本)
  • レンダリング エンジン (スマート)
  • ソース
  • タイムライン
  • トラック
  • トランジション
  • XML パーサー

    • 合成

    説明 | トラックとほかの合成が含まれる。
    クラス識別子 | 利用できない。作成するには、IAMTimeline::CreateEmptyNode を使用する。
    インターフェイス
    • IAMTimelineComp
    • IAMTimelineEffectable
    • IAMTimelineObj
    • IAMTimelineTransable
    • IAMTimelineVirtualTrack
    参照 | タイムライン モデル、タイムラインの構築

    エフェクト

    説明 | ビデオ エフェクトまたはオーディオ エフェクトを作成する。
    クラス識別子 | 利用できない。 作成するには、IAMTimeline::CreateEmptyNode を使用する。
    インターフェイス
    • IAMTimelineEffect
    • IAMTimelineObj
    • IAMTimelineSplittable
    • IPropertyBag
    参照 | タイムライン モデル、エフェクトとトランジションの操作

    グループ

    説明 | 最上位レベルの合成。
    クラス識別子 | 利用できない。 作成するには、IAMTimeline::CreateEmptyNode を使用する。
    インターフェイス
    • IAMTimelineComp
    • IAMTimelineGroup
    • IAMTimelineObj
    参照 | タイムライン モデル、タイムラインの構築

    メディア ディテクタ

    説明 | 情報とスティル フレームをファイル ソースから取得する。
    クラス識別子 | CLSID_MediaDet
    インターフェイス
    • IMediaDet
    参照 | ソースの操作

    メディア ロケータ

    説明 | ソース オブジェクトに関連したファイルを作成する。
    クラス識別子 | CLSID_MediaLocator
    インターフェイス
    • IMediaLocator
    参照 | ソースの操作

    プロパティ セッター

    説明 | タイムライン オブジェクトに IDispatch プロパティを設定する。
    クラス識別子 | CLSID_PropertySetter
    インターフェイス
    • IAMSetErrorLog
    • IPropertySetter
    参照 | タイムライン モデル、エフェクトとトランジションの操作

    レンダリング エンジン (基本)

    説明 | タイムラインからの非圧縮出力をレンダリングする。
    クラス識別子 | CLSID_RenderEngine
    インターフェイス
    • IAMSetErrorLog
    • IRenderEngine
    参照 | プロジェクトのレンダリング

    レンダリング エンジン (スマート)

    説明 | タイムラインからの圧縮出力をレンダリングする。
    クラス識別子 | CLSID_SmartRenderEngine
    インターフェイス
    • IAMSetErrorLog
    • IRenderEngine
    • ISmartRenderEngine
    参照 | プロジェクトのレンダリング

    ソース

    説明 | タイムラインのソース クリップを表す。
    クラス識別子 | 利用できない。作成するには、IAMTimeline::CreateEmptyNode を使用する。
    インターフェイス
    • IAMTimelineEffectable
    • IAMTimelineObj
    • IAMTimelineSrc
    • IAMTimelineSplittable
    参照 | タイムライン モデル、ソースの操作

    タイムライン

    説明 | ビデオ編集プロジェクトのすべてのオブジェクトが含まれる。
    クラス識別子 | CLSID_AMTimeline
    インターフェイス
    • IAMTimeline
    • IAMSetErrorLog
    • IPersistStream
    参照 | タイムライン モデル、タイムラインの構築

    トラック

    説明 | ソース オブジェクトが含まれる。
    クラス識別子 | 利用できない。作成するには、IAMTimeline::CreateEmptyNode を使用する。
    インターフェイス
    • IAMTimelineEffectable
    • IAMTimelineObj
    • IAMTimelineSplittable
    • IAMTimelineTrack
    • IAMTimelineTransable
    • IAMTimelineVirtualTrack
    参照 | タイムライン モデル、タイムラインの構築

    トランジション

    説明 | トラックまたは合成間のトランジションを作成する。
    クラス識別子 | 利用できない。作成するには、IAMTimeline::CreateEmptyNode を使用する。
    インターフェイス
    • IAMTimelineObj
    • IAMTimelineSplittable
    • IAMTimelineTrans
    参照 | タイムライン モデル、エフェクトとトランジションの操作

    XML パーサー

    説明 | XML プロジェクト ファイルをタイムラインに変換する。
    クラス識別子 | CLSID_Xml2Dex
    インターフェイス
    • IXml2Dex
    参照 | プロジェクトのロードとプレビュー


XML リファレンス

Microsoft® DirectShow® 編集サービスは、拡張可能マークアップ言語 (XML) の永続性フォーマットを使用している。このフォーマットは、以下の要素を定義している。

要素 | 説明
AT | PARAM 要素の時間ベースの設定を指定する。
CLIP | ソース ファイルを指定する。
COMPOSITE | 合成を定義する。
EFFECT | エフェクトを定義する。
GROUP | グループ (オーディオまたはビデオ) を定義する。
LINEAR | PARAM 要素の時間ベースの設定を指定する。
PARAM | トランジション、エフェクト、またはほかのサブオブジェクトのプロパティ値を指定する。
TIMELINE | タイムラインを定義する。
TRACK | トラックを定義する。
TRANSITION | トランジションを定義する。

属性のデータ型

以下の属性のデータ型には、特別な書式が必要である。

Boolean : y、Y、t、T、1は、TRUE と定義される。n、N、f、F、0 (ゼロ) は、FALSE と定義される。

CLSID : クラス識別子は、{00000000-0000-0000-0000-000000000000} フォーマットを使って文字列として指定する。

Float : すべての浮動小数点値は、小数点の前にゼロが付いていなければならない。たとえば、.3 ではなく 0.3 とする。

Time : 時刻の値には、hh:mm:ss.ff フォーマットを使用する。つまり、hh = 時間、mm = 分、ss = 秒、ff = 秒の小数部分である (例: 1:04:30.512)。先頭の単位は省略できる。たとえば、3:00 (3 分) および 45 (45 秒) は、どちらも有効である。


AT 要素

XML リファレンス

パラメータが含まれたトランジションまたはエフェクトの開始タイムに対して相対的な、特定の時間における PARAM 要素の値を定義する。AT 要素は、ある時間にパラメータ値を即座に新しい値に切り替える。新しい値へ円滑に変化させるためには、LINEAR 要素を使用する。

例

<AT TIME="1" VALUE="0.5" />

属性

名前 | 説明 | 型
TIME | パラメータが新しい値をとる、トランジションまたはエフェクトの開始タイムに対する相対的な時間。 | Time
VALUE | 指定された時間にパラメータが持つ値。 | 「注意」を参照。

親/子 情報

親 | PARAM
子 | なし

注意

VALUE 属性のデータ型は、設定されたプロパティに依存する。詳細については、「トランジションおよびエフェクト」を参照すること。


CLIP 要素

XML リファレンス

メディア ソースを指定する。

例

<CLIP SRC="sample.avi" START="1:05" STOP="1:42.5" MSTART="30" />

属性

名前 | 説明 | 型 | C/C++ で相当するもの
CLSID | ソースとして使用するソース フィルタの CLSID。SRC 属性が指定されている場合は、この属性を指定してはならない。 | CLSID | IAMTimelineObj::SetSubObjectGUID
FRAMERATE | デフォルトのフレーム レート (毎秒のフレーム数)。この属性のデフォルトは 0 であり、SRC 属性で指定されるスティル イメージのみが使用されることを示す。DIB シーケンスを有効にするには、この属性をゼロ以外の値に設定する。小数点以下が 8 桁以上の値を使用してはならない。 | Float | IAMTimelineSrc::SetDefaultFPS
LOCK クリップがロックされる (編集してはならない) かどうかを指定する。
  • TRUE : クリップはロックされる。
  • FALSE : クリップはロックされない (デフォルト)。
Boolean IAMTimelineObj::SetLocked
MLENGTH | 元のファイルの時間幅。この値は実際の時間幅でなければならない。そうでない場合、レンダリング エラーが発生することがある。 | Time | IAMTimelineSrc::SetMediaLength
MSTART | 元のメディア ファイルに対して相対的な、クリップの開始タイム。 | Time | IAMTimelineSrc::SetMediaTimes
MSTOP | 元のメディア ファイルに対して相対的な、クリップの終了タイム。 | Time | IAMTimelineSrc::SetMediaTimes
MUTE ソースのミュート状態を指定する。
  • TRUE : ソースはレンダリングされない。
  • FALSE : ソースはレンダリングされる (デフォルト)。
Boolean IAMTimelineObj::SetMuted
SRC | メディア ファイルのパス名。ファイルには、DirectShow がサポートする任意のタイプ、またはスティル イメージを使用できる。スティル イメージでサポートされるフォーマットには、ビットマップ、デバイスに依存しないビットマップ、GIF、および JPEG がある。詳細については、「注意」を参照すること。CLSID 属性が指定されているときは、この属性を指定してはならない。 | String | IAMTimelineSrc::SetMediaName
START | タイムラインに対して相対的な、クリップの開始タイム。 | Time | IAMTimelineObj::SetStartStop
STOP | タイムラインに対して相対的な、クリップの終了タイム。 | Time | IAMTimelineObj::SetStartStop
STREAM | AVI ファイルなどのマルチストリーム ファイルで、どのストリームを使用するかを指定する。 | Integer | IAMTimelineSrc::SetStreamNumber
STRETCHMODE 出力ディメンジョンに一致しないイメージを伸縮する方法を指定する。次のいずれかの値を指定できる。
  • Stretch : イメージは、アスペクト比を維持せずに、出力フレームに合わせて伸縮される (デフォルト)。
  • Crop : イメージは、出力フレームのサイズに合わせて切り詰められる。
  • PreserveAspectRatio : 元のアスペクト比が維持され、短いディメンジョンには黒のレターボックスが表示される。
  • PreserveAspectRatioNoLetterBox : イメージのサイズは、アスペクト比を維持して、ターゲット フレーム全体を満たすように変更される。
 String IAMTimelineSrc::SetStretchMode
USERDATA | アプリケーション定義の永続データ。偶数である必要がある。値 A ～ F は、大文字でなくてはならない。0x のようなプレフィックスを使用してはならない (例 : 123ABC)。 | Hexadecimal | IAMTimelineObj::SetUserData
USERID | オブジェクトに対するアプリケーション定義の識別子。 | Integer | IAMTimelineObj::SetUserID
USERNAME | オブジェクトに対するアプリケーション定義の名前。 | String | IAMTimelineObj::SetUserName

親/子 情報

親 | TRACK
子 | EFFECT

注意

少なくとも、開始タイム属性の一方 (START または MSTART) と、終了タイム属性の一方 (STOP または MSTOP) を指定する。開始タイム属性の一方が指定されなかった場合、その属性はデフォルトで 0 (START ではタイムラインの先頭、MSTART ではクリップの先頭) に設定される。終了タイム属性の一方が指定されなかった場合、DES は通常の再生レートを想定し、それに従って未指定の終了タイムを計算する。終了タイムが両方とも指定された場合、必要であれば再生の速度は通常より速く、または遅くなる。

次の例では、タイムラインの時間幅は 7 秒 (STOP - START) となる。通常の再生レートであれば、メディア終了タイムはデフォルトで 10 秒 (時間幅 + MSTART) となる。

<CLIP START="2" STOP="9" MSTART="3" />

2 番目の例では、メディア開始タイムはデフォルトで 0 となり、それによりメディアの時間幅は 10 秒となる。タイムラインの時間幅は 5 秒であるため、クリップの再生レートは通常の 2 倍の速度になる。

<CLIP START="5" STOP="10" MSTOP="10" />

SRC 属性にスティル イメージが指定された場合、DES はアニメーションを作成するために一連のスティル イメージをロードしようとする。たとえば、SRC 属性が IMAGE001.BMP である場合、DES は IMAGE002.BMP、IMAGE003.BMP、IMAGE004.BMP などのファイルを検索する。それらのファイルが存在すれば、そのファイル名の数字の順序に従って、FRAMERATE 属性に指定されたレートで表示される。


COMPOSITE 要素

XML リファレンス

合成を定義する。合成は、トラックおよび他のネストされた合成のコンテナ オブジェクトである。

例

<COMPOSITE> </COMPOSITE>

属性

名前 | 説明 | 型 | C/C++ で相当するもの
LOCK 合成がロックされる (編集してはならない) かどうかを指定する。
  • TRUE : 合成はロックされる。
  • FALSE : 合成はロックされない (デフォルト)。
Boolean IAMTimelineObj::SetLocked
MUTE 合成とそのすべての子のミュート状態を指定する。
  • TRUE : 合成とそのすべての子はレンダリングされない。
  • FALSE : 合成はレンダリングされる。子は、それぞれのミュート状態に従ってレンダリングされる (デフォルト)。
Boolean IAMTimelineObj::SetMuted
USERDATA | アプリケーション定義の永続データ。偶数でなくてはならない。A ～ F は、大文字である必要がある。0x のようなプレフィックスを使用してはならない (例 : 123ABC)。 | Hexadecimal | IAMTimelineObj::SetUserData
USERID | オブジェクトに対するアプリケーション定義の識別子。 | Integer | IAMTimelineObj::SetUserID
USERNAME | オブジェクトに対するアプリケーション定義の名前。 | String | IAMTimelineObj::SetUserName

親/子 情報

親 | COMPOSITE、GROUP
子 | COMPOSITE、EFFECT、TRACK、TRANSITION

注意

COMPOSITE 要素の中で、ネストされたレイヤの優先順位は、タグ内に指定されている順序によって暗黙的に決定される。最初のレイヤは優先順位 0 であり、以降のレイヤは順に優先順序値が大きくなる。


EFFECT 要素

XML リファレンス

エフェクト オブジェクトを定義する。エフェクトは、単一のストリーム (合成、トラック、またはソース) に適用される単一入力変換である。

例

<EFFECT CLSID="{B05A941C-3CE1-11D2-952A-00C04FA34F05}" START="0" STOP="32" />

属性

名前 | 説明 | 型 | C/C++ で相当するもの
CLSID | エフェクトを作成するサブオブジェクトのクラス識別子 (CLSID)。 | CLSID | IAMTimelineObj::SetSubObjectGUID
LOCK エフェクトがロックされる (編集してはならない) かどうかを指定する。
  • TRUE : エフェクトはロックされる。
  • FALSE : エフェクトはロックされない (デフォルト)。
Boolean IAMTimelineObj::SetLocked
MUTE エフェクトのミュート状態を指定する。
  • TRUE : エフェクトは適用されない。
  • FALSE : エフェクトは適用される (デフォルト)。
Boolean IAMTimelineObj::SetMuted
START | 親オブジェクトに対して相対的な、エフェクトの開始タイム。 | Time | IAMTimelineObj::SetStartStop
STOP | 親オブジェクトに対して相対的な、エフェクトの終了タイム。 | Time | IAMTimelineObj::SetStartStop
USERDATA | アプリケーション定義の永続データ。偶数でなくてはならない。A ～ F は、大文字である必要がある。0x のようなプレフィックスを使用してはならない (例 : 123ABC)。 | Hexadecimal | IAMTimelineObj::SetUserData
USERID | オブジェクトに対するアプリケーション定義の識別子。 | Integer | IAMTimelineObj::SetUserID
USERNAME | オブジェクトに対するアプリケーション定義の名前。 | String | IAMTimelineObj::SetUserName

親/子 情報

親 | COMPOSITE、GROUP、CLIP、TRACK
子 | PARAM


GROUP 要素

XML リファレンス

タイムライン内の最上位レベルのオブジェクトであるグループを定義する。

例

<GROUP TYPE="video" WIDTH="640" HEIGHT="480" FRAMERATE="30"> </GROUP>

属性

名前 | 説明 | 型 | C/C++ で相当するもの
BITDEPTH | 出力ビデオのビット数 (ピクセル当たりのビット数)。16、24、または 32 でなければならない。この属性は、TYPE 属性がビデオの場合にのみ指定する。デフォルト値は 16 である。 | Integer
BUFFERING | プレビュー時に先行してレンダリングされるフレーム数。1 より大きい数でなければならない。デフォルト値は 30 である。 | Integer | IAMTimelineGroup::SetOutputBuffering
FRAMERATE | 出力フレーム レート (毎秒のフレーム数)。小数点以下が 8 桁以上の値を使用してはならない。 | Float | IAMTimelineGroup::SetOutputFPS
HEIGHT | 出力ビデオの高さ (ピクセル単位)。この属性は、TYPE 属性がビデオの場合にのみ指定する。 | Integer
LOCK グループがロックされる (編集してはならない) かどうかを指定する。
  • TRUE : グループはロックされる。
  • FALSE : グループはロックされない (デフォルト)。
Boolean IAMTimelineObj::SetLocked
MUTE グループのミュート状態を指定する。
  • TRUE : グループとそのすべての子はレンダリングされない。
  • FALSE : グループはレンダリングされる。子は、それぞれのミュート状態に従ってレンダリングされる (デフォルト)。
Boolean IAMTimelineObj::SetMuted
PREVIEWMODE グループのプレビュー モード。
  • TRUE : プレビュー時にフレーム落ちが生じることがある (デフォルト)。
  • FALSE : フレーム落ちはない。
デフォルトの設定では、ビデオとオーディオの同期を維持するために、プレビュー時に時間のかかるエフェクトまたはトランジションではフレーム落ちが生じる。そのため、ビデオの動きがぎこちなくなることがある。この属性を FALSE に設定すると、プレビュー時にすべてのフレームがレンダリングされ、それによりビデオとオーディオの同期が取れなくなる場合がある (ファイルに書き込むときにフレームが落ちることはなくなる)。 		Boolean IAMTimelineGroup::SetPreviewMode
SAMPLINGRATE | 出力オーディオのサンプリング レート (Hz 単位)。8000、11025、22050、32000、44100、または 48000 でなければならない。この属性は、TYPE 属性がオーディオの場合にのみ設定する。デフォルト値は 44100 である。 | Integer
TYPE | グループのメディア タイプ。ビデオまたはオーディオでなければならない。 | String | IAMTimelineGroup::SetMediaType
USERDATA | アプリケーション定義の永続データ。偶数でなくてはならない。A ～ F は、大文字である必要がある。0x のようなプレフィックスを使用してはならない (例 : 123ABC)。 | Hexadecimal | IAMTimelineObj::SetUserData
USERID | オブジェクトに対するアプリケーション定義の識別子。 | Integer | IAMTimelineObj::SetUserID
USERNAME | オブジェクトに対するアプリケーション定義の名前。 | String | IAMTimelineObj::SetUserName
WIDTH | 出力ビデオの幅 (ピクセル単位)。この属性は、TYPE 属性がビデオの場合にのみ指定する。 | Integer

親/子 情報

親 | TIMELINE
子 | COMPOSITE、EFFECT、TRACK

注意

GROUP 要素の中で、ネストされたレイヤの優先順位は、タグ内に指定されている順序によって暗黙的に決定される。最初のレイヤは優先順位 0 であり、以降のレイヤは順に優先順序値が大きくなる。


LINEAR 要素

XML リファレンス

特定の時間における PARAM 要素の値を、その PARAM 要素が含まれたトランジションまたはエフェクトの開始タイムに対して相対的に定義する。LINEAR 要素は、そのパラメータが前の値から新しい値に円滑にトランジションすることを指定する。新しい値へ即座に切り替えるには、AT 要素を使用する。

例

<LINEAR TIME="6" VALUE="0.0" />

属性

名前 | 説明 | 型
TIME | パラメータが新しい値をとる、トランジションまたはエフェクトの開始タイムに対する相対的な時間。 | Time
VALUE | 指定された時間にパラメータが持つ値。 | 「注意」を参照。

親/子 情報

親 | PARAM
子 | なし

注意

VALUE 属性のデータ型は、設定されるプロパティに依存する。詳細については、「トランジションおよびエフェクト」を参照すること。


PARAM 要素

XML リファレンス

トランジション、エフェクト、またはほかのサブオブジェクトのプロパティ値を指定する。

例

<PARAM NAME="progress" VALUE="1.0" />

属性

名前 | 説明 | 型
NAME | 設定するプロパティの名前。 | String
VALUE | トランジションまたはエフェクトの開始タイムに対する時間 0 において、プロパティが持つ値。0 より後の時間の値を指定するには、AT または LINEAR 要素を使用する。PARAM 要素には AT または LINEAR 要素は含まれず、この属性で指定された値はエフェクトまたはトランジション全体において一定である。 | プロパティによって異なる。

親/子 情報

親 | CLIP、EFFECT、TRANSITION
子 | AT、LINEAR

注意

多数のエフェクトとトランジションで、その動作のさまざまな側面を制御するプロパティがサポートされている。

ほとんどのトランジションは標準の Progress プロパティをサポートしている。このプロパティは、0 から 1.0 の範囲で、出力に反映されるトランジションの割合を指定する。Progress = 0.0 の時点では、トランジションはそのシーケンスの始まり (全体が最初のビデオ イメージ) にある。Progress = 0.5 の時点では、トランジションは半分完了している (たとえばワイプでは、Progress = 0.5 の時点で、トランジション境界はイメージの中央にある)。Progress = 1.0 の時点で、トランジションは完了している (全体が 2 番目のイメージ)。デフォルトでは、トランジションは開始時の Progress = 0.0 から始まり、終了時の Progress = 1.0 に向かって進行する。

他のプロパティは、通常は 1 つの特定のトランジションまたはエフェクトに固有のものである。たとえばワイプ トランジションは、トランジション領域の幅を制御する GradientSize プロパティをサポートしている。プロパティの詳細については、Microsoft® DirectX® 変換のドキュメントで「変換プロパティ」を参照すること。

PARAM 要素を含めることにより、トランジションまたはエフェクトのプロパティを設定できる。VALUE 属性は、時間 0 (トランジションまたはエフェクトの開始タイム相対) でのプロパティの値を指定する。PARAM 要素に子が含まれていない場合、指定された値はトランジションまたはエフェクトの時間幅の中一定である。時間の経過に伴って値を変化させるには、PARAM 要素内で AT または LINEAR 要素をネストする。AT 要素は、指定された時間にプロパティを古い値から新しい値に即座に切り替える。LINEAR 要素は、新しい値へのスムースなトランジションを作成する。その場合、DES は中間の値を補間する。

次の例では、Progress プロパティは 0.0 で始まり、時間 2 で 1.0 に直接切り替わり、時間 2 から 6 の間にスムースに 0.5 に戻る。

<TRANSITION CLSID="{AF279B30-86EB-11D1-81BF-0000F87557DB}" START="0" STOP="6">
    <PARAM NAME="Progress" VALUE="0.0">
        <AT TIME="2" VALUE="1.0" />
        <LINEAR TIME="6" VALUE="0.5" />
    </PARAM>
</TRANSITION>

トランジションを逆方向へ実行するには、Progress プロパティのデフォルトの動作を逆にする。

<TRANSITION CLSID="{AF279B30-86EB-11D1-81BF-0000F87557DB}" START="0" STOP="6">
    <PARAM NAME="Progress" VALUE="1.0">
        <LINEAR TIME="6" VALUE="0.0" />
    </PARAM>
</TRANSITION>


TIMELINE 要素

XML リファレンス

タイムラインを定義する。この要素は、XML ファイル内のルート ノードである。

例

<TIMELINE> </TIMELINE>

属性

名前 | 説明 | 型 | C/C++ で相当するもの
DEFAULTFX | デフォルトのエフェクトの CLSID。 | CLSID | IAMTimeline::SetDefaultEffect
DEFAULTRANS | デフォルトのトランジションの CLSID。 | CLSID | IAMTimeline::SetDefaultTransition
ENABLEFX エフェクトが有効かどうかを指定する。
  • TRUE : エフェクトはレンダリングされる (デフォルト)。
  • FALSE : エフェクトはレンダリングされない。
Boolean IAMTimeline::EnableEffects
ENABLETRANS トランジションが有効かどうかを指定する。
  • TRUE : エフェクトは通常の方法でレンダリングされる (デフォルト)。
  • FALSE : トランジションはカット (直接切り替え) としてレンダリングされる。
Boolean IAMTimeline::EnableTransitions
FRAMERATE | デフォルトのフレーム レート (秒あたりのフレーム数)。小数点以下が 8 桁以上の値を使用してはならない。グループの FRAMERATE 属性が指定されている場合は、この値より優先される。 | Float | IAMTimeline::SetDefaultFPS

親/子 情報

Parent | なし。この要素は、XML ファイル内のルート ノードでなければならない。
子 | GROUP


TRACK 要素

XML リファレンス

トラック オブジェクトを定義する。

例

<TRACK> </TRACK>

属性

名前 | 説明 | 型 | C/C++ で相当するもの
LOCK トラックがロックされる (編集してはならない) かどうかを指定する。
  • TRUE : トラックはロックされる。
  • FALSE : トラックはロックされない (デフォルト)。
Boolean IAMTimelineObj::SetLocked
MUTE トラックのミュート状態を指定する。
  • TRUE : トラックとそのすべての子はレンダリングされない。
  • FALSE : トラックはレンダリングされる。子は、それぞれのミュート状態に従ってレンダリングされる (デフォルト)。
Boolean IAMTimelineObj::SetMuted
USERDATA | アプリケーション定義の永続データ。偶数でなくてはならない。A ～ F は、大文字である必要がある。0x のようなプレフィックスを使用してはならない (例 : 123ABC)。 | Hexadecimal | IAMTimelineObj::SetUserData
USERID | オブジェクトに対するアプリケーション定義の識別子。 | Integer | IAMTimelineObj::SetUserID
USERNAME | オブジェクトに対するアプリケーション定義の名前。 | String | IAMTimelineObj::SetUserName

親/子 情報

Parent | COMPOSITE、GROUP
Children | CLIP、EFFECT、TRANSITION


TRANSITION 要素

XML リファレンス

トランジション オブジェクトを定義する。トランジションは、ストリーム (合成やトラックなど) から別のストリームへのトランジションとなる双入力変換である。

例

<TRANSITION
    CLSID="{2A54C913-07AA-11D2-8D6D-00C04F8EF8E0}"
    START="7"
    STOP="10"
/>

属性

名前 | 説明 | 型 | C/C++ で相当するもの
CLSID | トランジションを作成するサブオブジェクトのクラス識別子 (CLSID)。 | CLSID | IAMTimelineObj::SetSubObjectGUID
CUTPOINT | トランジションがカットとしてレンダリングされる場合の、トランジションが一方のソースから次のソースに切り替わる時間を指定する。この値は、トランジションの開始と相対的である。 | Time | IAMTimelineTrans::SetCutPoint
CUTSONLY トランジションがカットとしてレンダリングされるかどうかを指定する。
  • TRUE : トランジションは直接切り替え (カット) となる。
  • FALSE : トランジションは通常の方法でレンダリングされる (デフォルト)。
Boolean IAMTimelineTrans::SetCutsOnly
LOCK トランジションがロックされる (編集してはならない) かどうかを指定する。次のいずれかの値でなければならない。
  • TRUE : トランジションはロックされる。
  • FALSE : トランジションはロックされない (デフォルト)。
Boolean IAMTimelineObj::SetLocked
MUTE トランジションのミュート状態を指定する。次のいずれかの値でなければならない。
  • TRUE : トランジションは適用されない。
  • FALSE : トランジションは適用される (デフォルト)。
Boolean IAMTimelineObj::SetMuted
START | 親オブジェクトに対して相対的な、トランジションの開始タイム。 | Time | IAMTimelineObj::SetStartStop
STOP | 親オブジェクトに対して相対的な、トランジションの終了タイム。 | Time | IAMTimelineObj::SetStartStop
SWAPINPUTS トランジションの入力を入れ替えるかどうかを指定する。
  • TRUE : 入力は入れ替えられる。
  • FALSE : 入力は入れ替えられない (デフォルト)。
Boolean IAMTimelineTrans::SetSwapInputs
USERDATA | アプリケーション定義の永続データ。アプリケーション定義の永続データ。偶数でなくてはならない。A ～ F は、大文字である必要がある。0x のようなプレフィックスを使用してはならない (例: 123ABC)。 | Hexadecimal | IAMTimelineObj::SetUserData
USERID | オブジェクトに対するアプリケーション定義の識別子。 | Integer | IAMTimelineObj::SetUserID
USERNAME | オブジェクトに対するアプリケーション定義の名前。 | String | IAMTimelineObj::SetUserName

親/子 情報

親 | COMPOSITE、TRACK
子 | PARAM

注意

デフォルトでは、トランジションは優先順位の低いレイヤの合成から、トランジションが存在するレイヤに向かって進行する。SWAPINPUTS 属性が 1 の場合、この方向が逆になる。DES で使用されるレイヤリング モデルについては、「タイムライン モデル」を参照すること。


レンダリング エラー

Microsoft® DirectShow® 編集サービス (DES) は、レンダリング エラーを記録するために使用される各種のエラー コードを定義している。プロジェクトが正しくレンダリングされなかった場合、レンダリング エンジンは IAMErrorLog::LogError メソッドを呼び出す。次の表は、LogError に渡されるパラメータをまとめたものである。

  • エラー コードは、ErrorCode パラメータに入っている。
  • 説明は、ErrorString パラメータに入っている。
  • 追加情報は (ある場合)、pExtraInfo が指す VARIANT に入っている。
  • 追加情報がある場合、この VARIANT 型は、pExtraInfo が指す VARIANT の vt メンバに入っている。

注 : ここで説明するエラー コードは HRESULT 値ではない。DES 固有の HRESULT 戻り値の一覧については、「エラー コードおよび成功コード」を参照すること。

エラー コード | 説明 | 追加情報 | Variant 型
DEX_IDS_BAD_SOURCE_NAME | ファイル名が存在しない。または、DirectShow が認識できないファイル拡張子である。 | ファイル名 | BSTR
DEX_IDS_BAD_SOURCE_NAME2 | ファイル タイプがファイル拡張子と一致していない。または、ファイルが壊れている。 | ファイル名 | BSTR
DEX_IDS_MISSING_SOURCE_NAME | ファイル名が必要だが、指定されなかった。 | なし | 利用できない
DEX_IDS_UNKNOWN_SOURCE | このソースによって提供されたデータ ソースを解析できない。 | なし | 利用できない
DEX_IDS_INSTALL_PROBLEM | 予期せぬエラー。 一部の DirectShow コンポーネントが正しくインストールされていない。 | なし | 利用できない
DEX_IDS_NO_SOURCE_NAMES | ソース フィルタがファイルを受け付けない。 | なし | 利用できない
DEX_IDS_BAD_MEDIATYPE | グループのメディア タイプはサポートされていない。 | グループ番号 | int
DEX_IDS_STREAM_NUMBER | このソースでは無効なストリーム番号。 | ストリーム番号 | int
DEX_IDS_OUTOFMEMORY | メモリ不足。 | なし | 利用できない
DEX_IDS_DIBSEQ_NOTALLSAME | シーケンス内のビットマップのタイプが他のビットマップと異なっていた。 | ビットマップ名 | BSTR
DEX_IDS_CLIPTOOSHORT | クリップのメディア タイムが無効である。または、デバイスに依存しないビットマップ (DIB) のシーケンスが短かすぎる。 注 : 他のレンダリング エラーが発生している場合、メディア タイムが有効であってもこのエラーが発生することがある。 | なし | 利用できない
DEX_IDS_INVALID_DXT | エフェクトまたはトランジションのクラス識別子 (CLSID) が、有効な Microsoft® DirectX® 変換エフェクトではない。 | CLSID | BSTR
DEX_IDS_INVALID_DEFAULT_DXT | デフォルトのエフェクトまたはトランジションが、有効な DirectX 変換エフェクトではない。 | CLSID | BSTR
DEX_IDS_NO_3D | 使用している DirectX のバージョンは、3 次元変換をサポートしていない。 | CLSID | BSTR
DEX_IDS_BROKEN_DXT | DirectX 変換エフェクトが正しい種類でないか、または壊れている。 | CLSID | BSTR
DEX_IDS_NO_SUCH_PROPERTY | オブジェクトにそのようなプロパティは存在しない。 | プロパティ名 | BSTR
DEX_IDS_ILLEGAL_PROPERTY_VAL | このプロパティに不正な値。 | 指定された値 | VARIANT
DEX_IDS_INVALID_XML | XML ファイル内の構文エラー。 | 行番号 | VT_I4 (4 バイト整数)
DEX_IDS_CANT_FIND_FILTER | XML 内でカテゴリとインスタンスによって指定されたフィルタが見つからない。 | フレンドリ名 (インスタンス) | BSTR
DEX_IDS_DISK_WRITE_ERROR | XML ファイルのディスク書き込みエラー。 | なし | 利用できない
DEX_IDS_INVALID_AUDIO_FX | CLSID が有効な DirectShow オーディオ エフェクト フィルタではない。 | CLSID | BSTR
DEX_IDS_CANT_FIND_COMPRESSOR | 指定された圧縮フォーマットを生成するコンプレッサが見つからない。 | なし | 利用できない

以下のエラーは発生しないはずである。万一これらのエラーが発生した場合は、dxmbug.microsoft.com へバグ レポートの送付をお願いする。

エラー コード | 説明
DEX_IDS_TIMELINE_PARSE | タイムライン解析の予期せぬエラー。
DEX_IDS_GRAPH_ERROR | フィルタ グラフ構築の予期せぬエラー。
DEX_IDS_GRID_ERROR | 内部グリッドに関する予期せぬエラー。
DEX_IDS_INTERFACE_ERROR | インターフェイス取得時の予期せぬエラー。


DVD アプリケーション

Microsoft® DirectShow® には、DVD の操作を単純化する DVD ナビゲータ ソース フィルタと呼ばれるコンポーネントが含まれている。DVD ナビゲータには、本格的なスタンドアロン DVD プレーヤーが備えるすべての機能に加えて、パソコン上で DVD を再生するための追加機能が含まれている。DVD ナビゲータと C++ およびスクリプト機能を使用することで、開発者は DVD の仕様を参照する必要なしに完全な機能を持つ DVD プレーヤーを作成できる。DVD ナビゲータは、デコーダ フィルタとの連携により、リージョン管理と著作権保護 (CSS および Macrovision) の処理も行うので、アプリケーション開発者はこれらの詳細について作業しなくて済む。

DVD ナビゲータのフィルタは DVD-Video の "ボリューム" 全体にわたって機能する。ボリュームとは、VIDEO_TS ディレクトリのファイルの集合である。個々のストリームやファイルを処理するほとんどの DirectShow ソース フィルタと異なり、DVD ナビゲータは DVD-Video のタイトル、チャプター、およびタイムコードの構造を使用する。DirectShow で 個々の MPEG-2 ファイルを再生したい開発者は、DVD ナビゲータ フィルタの代わりに MPEG-2 スプリッタ フィルタを使用すべきである。詳細については、「DirectShow の MPEG-2 サポート」を参照すること。

C++ を使用する開発者は、DVD ナビゲータが公開する Component Object Model (COM) インターフェイスを通じて、DVD ナビゲータを直接制御できる。スクリプト言語または Microsoft® Visual Basic® を使用する開発者は、MSWebDVD ActiveX® コントロールを通じて間接的に DVD ナビゲータを制御できる。

カスタマイズされたインターフェイスを持つプレーヤー、DVD 再生を制御する Web ページ、埋め込み DVD ビデオを含む PowerPoint プレゼンテーションなど、ほとんどの DVD アプリケーションは、MSWebDVD ActiveX コントロールを使用して HTML または Visual Basic で作成できる。これは C++ を用いるよりも簡単で高速である。C++ を使用する必要があるのは、ゲーム、ビデオ上にグラフィックをオーバーレイするプログラム、カスタム ActiveX コントロールまたは DLL など、より専門化されたアプリケーションの場合だけである。

注 : DirectShow は、DVD-Video の操作と再生に必要なフィルタをすべて備えているが、MPEG-2 デコーダは含まれていない。DirectShow に基づいたアプリケーションを使用して DVD を再生するには、ユーザーのシステム上に DirectShow に対応したサードパーティ製のハードウェア デコーダまたはソフトウェア デコーダをインストールする必要がある。

ここには、以下のトピックが含まれる。

  • DirectShow 8.0 の新しい DVD サポート機能
  • DVD プレーヤー アプリケーションの開発に必要な背景知識
  • DVD の基礎
  • C++ による DVD プレーヤー アプリケーションの開発
  • C++ DVD に関する参照ページへのショートカット
  • スクリプトに基づいた DVD プレーヤー アプリケーションの開発
  • MSWebDVD ActiveX コントロール

DVD/MPEG2 デコーダの開発については、「デコーダの開発」を参照すること。

DVD-ROM コンテンツ開発者へ : DVD-ROM Boilerplate ビデオは、DirectX® 8 Software Development Kit の DXF > Extras フォルダにある。このフォルダを参照するには、[Explore this CD] をクリックする。このフォルダは、ローカル ドライブにはインストールされない。boilerplate ビデオは、DVD ビデオ フォーマットのデータを含まない DVD-ROM タイトルを開発者が制作するために提供されている。適切な DVD-Video ゾーンのないディスクは、スタンドアロン DVD プレーヤーに挿入すると、ディスクが取り出されたりロックアップするなど、予期しない動作をする可能性がある。このような好ましくない状況は、ディスクに DVD-ROM Boilerplate ビデオをディスクに追加することで回避できる。ディスクが DVD ビデオ プレーヤーに挿入されると、このディスクは Microsoft® Windows® が実行される DVD-ROM PC 用に設計されていることをユーザーに知らせるメッセージが表示される。


DirectShow 8.0 における新しい DVD サポート機能

DVD ナビゲータの拡張された機能は、IDvdControl2 (DVD ナビゲータに "set" メソッドを追加する) および IDvdInfo2 ("get"メソッドを追加する) という 2 つの新しいインターフェイスによって公開される。最新機能を含む DVD ナビゲータのスクリプト機能のサポートは、Microsoft® ActiveX® コントロールの MSWebDVD によって行われる。

開発者の要求に応じて DVD ナビゲータに導入された各種機能は、以下のとおりである。

  • カラオケのサポート : DVD ナビゲータを使用して、DVD カラオケ アプリケーションを開発できる。(対応するデコーダが必要。)
  • DVD テキスト情報の文字列へのアクセスを単純化 : DVD ナビゲータでこれらの文字列を解析し、アプリケーションで列挙、識別、および検索を容易に行える。
  • IBasic Audio によるオーディオ ボリュームの制御
  • Stop コマンドの実行時に DVD ナビゲータの動作をカスタマイズするためのサポート : アプリケーションで DVD ナビゲータに指示して、フィルタ グラフを再起動する際にディスクの現在位置から再開するか、またはディスクの最初から再生できる。
  • Digital Theater Systems (DTS) および Sony Dynamic Digital Sound (SDDS) オーディオ のサポート : DTS および SDDS オーディオ ストリームは DVD ナビゲータによって認識され、オーディオ デコーダに渡される。(オーディオのデコードおよび再生を行うには、DTS 対応または SDDS 対応のサードパーティ製 デコーダが必要。)
  • ペアレンタル レベル変更に対するサポートの強化 : DVD ナビゲータによって、アプリケーションはディスクからのペアレンタル レベル変更を受け入れたり、拒否、または無視できる。
  • DVD ナビゲータの状態の管理やコマンドの同期化に関する高度なオプション
  • コマ送り、フレームアキュレート シーク、および逆転再生のサポート : これらの新しい機能を使用するには、サポートできるように更新されたビデオ デコーダが必要。
  • タイトル内の現在位置を保存して、いつでもそこに戻ることができる機能
  • ランダムな PGC タイトルにおけるタイム イベントへのサポートの簡略化 : ランダムな PGC タイトルの場合、DVD ナビゲータはアプリケーションに対して生のタイムコード情報を中継する。
  • 新しく、より便利になった、タイムコード情報を処理するためのデータ構造 : DVD_HMSF_TIMECODE 構造をバイナリ コード 10 進 (BCD) フォーマットの代わりに使用できる。 DVD_HMSF_TIMECODE は時、分、秒、フレームに対するアクセスしやすいメンバを含んでおり、ULONG との間でキャストが可能。
  • フィルタ グラフがシーク動作後にフラッシュするかどうかを制御する機能 : グラフ バッファに、いつでも数秒間のビデオを保存できる。グラフに指示して、バッファに保存されたビデオの再生をシーク後に終了するか、または新しい位置から即座に再生を開始できる。
  • 全般的なパラメータのレジスタに値を設定する機能 : DVD の仕様に詳しく、高度な機能を実装したいユーザーのための高度な機能。
  • すべての実際的な目的に対して一意である数値ディスク識別子を生成する機能 : これは、ディスクを特定の Web ベースの拡張と関連付けなければならない MSWebDVD アプリケーションにとって有用な機能である。


DVD アプリケーションの開発に必要な背景知識

すべてのアプリケーション開発者には、ペアレンタル ロック レベル、複数のオーディオおよびサブピクチャのストリーム、アングル ブロックなど、DVD テクノロジが提供する機能に関する基本的な知識が必要である。「DVD の基礎」では、これらの機能についてそれぞれ簡単に説明する。詳細については、サードパーティの書籍を参照すること。Annex J コマンド セットよりも高度な機能を実装する場合を除き、DVD の仕様を参照する必要はない。

Microsoft® DirectShow® Component Object Model (COM) のアプリケーション プログラミング インターフェイス (API) を使用している C または C++ の開発者は、COM オブジェクトの作成、および COM インターフェイス ポインタの取得や解放などの COM クライアント プログラミングの技術を熟知しているはずである。また、グラフに対する直接的なアクセスや操作が必要となる場合があるため、フィルタ グラフ オペレーションの一般的な知識も必要とされる。

Microsoft® Visual Basic®、Microsoft® JScript®、または Visual Basic Scripting Edition (VBScript) を使用している場合は、アプリケーション内の Microsoft® ActiveX® コントロールのホスティングの基礎に関しても熟知していなければならない。「スクリプト ベースの DVD アプリケーションの記述」では、Web ページにコントロールを埋め込み、そこからイベント通知を受け取る方法を示す。


DVD の基礎

消費者にとって魅力的な DVD の機能 (シームレスな分岐、複数の言語、ペアレンタル ロック、カラオケのサポート、複数のアングル) は、開発者の作業を多少複雑にするものである。DVD プレーヤーはオーディオ ストリーム、ビデオ ストリーム、およびサブピクチャ ストリームを再生するだけではなく、現在ディスクで利用できる操作オプションを把握し、たくさんの種類のユーザー コマンドを適切に処理できなければならない。DVD ナビゲータでは、ユーザーはそういった複雑さをほとんど意識せずに、完全な機能を備えた DVD アプリケーションを作成できる。DVD の仕様を参照する必要なしに DVD ナビゲータの API を効果的に使用できるが、基本的な DVD の操作の概念は知っておく必要がある。以下に、必要な背景知識を述べる。DVD の知識に関する詳細については、サードパーティの書籍または Web サイトを参照すること。

  • 操作制御のデータ
  • オーディオ、ビデオ、およびサブピクチャのデータ
  • タイトルとチャプター
  • メニュー
  • ペアレンタル ロック レベル
  • ドメイン
  • ユーザーの動作制御

操作制御のデータ

DVD-Video ディスク上のオーディオおよびビデオのデータは、さまざまな操作制御のデータによって一定間隔でインターリーブされる。このデータによって、ディスク上の特定の位置に移動するなどの動作をプレーヤーに指示したり、または単に情報のみのマーカーとして用いて、その位置以降の内容がそれ以前より高いペアレンタル ロック レベルを持つことや、チャプターのスキップ動作が無効であることをプレーヤーに知らせたりできる。プレーヤーがこの情報をアプリケーションに中継すると、アプリケーションはその情報に基づいた動作を行う。この操作マーカーは、DVD でビデオ CD よりも優れた対話操作性をユーザーに提供する機能の一部である。DVD プレーヤーのアプリケーションは、ディスクで発生するイベント同様、ユーザー側で発生するイベントも処理しなければならない。

オーディオ、ビデオ、およびサブピクチャのデータ

DVD-Video ディスクには、ビデオ、オーディオ、およびサブピクチャという 3 種類の主要なデータ ストリームが含まれている。

  • ビデオ ストリームには最大 9 個の "アングル" (サブストリームとみなされる) を含むことができる。DVD の作成者は、視聴者が同じシーンを異なるカメラ アングルから見ることができるように、任意の位置に複数のアングルを含めることができる。一度にアクティブにできるアングルは 1 つのみである。また、Line 21 クローズド キャプション データがあれば、それを含むこともできる。
  • 最大 8 つのオーディオ ストリームすなわちトラックを含むことができるため、最大 8 つのマルチチャンネル サウンドトラックが使用可能であり、DVD カラオケ ディスクでマルチチャンネル オーディオを使用できる。
  • また、メニューボタンや字幕に使用されるビットマップ グラフィックを含むサブピクチャ ストリームを最大 32 まで含むことができる。ビデオの矩形内に表示されると似ているように見えるが、サブピクチャ データ ストリームは、ビデオ ストリーム内の クローズド キャプション データには依存していない。ディスクにサブピクチャと クローズド キャプション データが両方とも含まれている場合は、それらを同時に表示することはできない。

タイトルとチャプター

DVD-Video ディスクにおける主要な論理的区分がタイトルである。タイトルによって動画全体を表すことも、または 30 秒のビデオ クリップを表すこともできる。ディスクには最大 99 タイトルを含むことができ、ディスク作成者はタイトルを最大 999 の論理的なチャプターに分けることができる。DVD 上のムービー本編では、ほとんどの場合、動画の内容は連続して再生される一連のチャプターとしてフォーマットされている。そのようなディスクでは、チャプターの最後のマーカーに分岐命令が含まれており、それにより、プレーヤーに次のチャプターを連続して再生するように指示する。これらのタイトルを、 一連のシーケンシャル PGC タイトルという。(PGC とはプログラム チェーンの略であり、一連のチャプターが属するグループの別名である。この用語は、DVD ナビゲータのドキュメントでは使用しない。)カラオケ ディスクなど他の種類のコンテンツを含むディスクにおいては、チャプターの最後のマーカーは、プレーヤーにメニューを表示させたり、単にプレーヤーを停止させたりするのに用いられる。

DVD アプリケーションの開発者はタイトルおよびチャプター番号を使用して、ディスクの特定の位置にジャンプする。詳細なアクセスを行うには、タイトル番号とタイムコードを使用する。タイムコードを使用できるのはシーケンシャル PGC タイトルのみである。これは、他の種類にはタイムコード マップがないからである。

メニュー

メニューは、ユーザーが既存のプレーヤーで 再生される DVD 上の内容とやり取りするための基本的な手段である。ユーザーはメニューを使用することによって、表示するビデオ タイトル、再生するオーディオ サウンドトラック、表示する字幕やカメラ アングル、および有効にする他の機能を選択することができる。DirectShow DVD アプリケーションの開発者は、メニューを既存のプレーヤーにおけるメニューとして有効にするか、または、ディスク上で作成されたメニューを置き換えたり補足したりするコンピュータ ベースの新しいインターフェイスを作成するかを選択できる。アプリケーションでは、プログラム的にメニュー ボタンを選択したりアクティブにすることによってユーザーの対話操作をシミュレートすることもできる。

ビデオ マネージャ メニュー
最上位のメニューはビデオ マネージャ メニュー (VMGM) であり、トップ メニューまたはタイトル メニューとも呼ばれる。メニューには通常、ボタンがあり、このボタンによってユーザーはディスク上のメイン タイトルまたはタイトルのグループに移動することができる。タイトルのグループは、タイトル セットと呼ばれる。たとえば、ムービー本編、"監督およびキャストのインタビュー"、"次の作品" というタイトル セットを含むディスク上では、VMGM のボタンは 3 つあると考えられる。"次の作品" ボタンをクリックすると、タイトル セット内にある、各タイトル用のボタンが付いたビデオ タイトル セット メニューに移動できる。

ディスクには、最大 8 つの言語によるサウンドトラックを含めることができる。また、サウンドトラックに対応する言語による VMGM を複数含むこともできる。

ディスクの最初のタイトルが自動再生タイトルとして作成されていない限り、ディスクを再生すると VMGM が最初に表示される。ディスクの最初のタイトルが自動再生タイトルとして作成されている場合、VMGM は表示されない。DVD 上のムービー本編は、ほとんど自動再生タイトルとして作成されている。

ビデオ タイトル セット メニューとサブメニュー
ビデオ タイトル セット メニュー、別名ルート メニュー (ルートにはない) は VMGM のサブメニューである。タイトル セットには、1～99 タイトルまで含むことができる。VTSM には、ユーザーがタイトル セット内の任意のタイトルに移動するためのボタンが用意されている。また、ユーザーがオーディオ ストリーム、カメラ アングル、サブピクチャ ストリーム、またはチャプターを選択するオプションに移動するためのサブメニューもある。これらのサブメニューは、タイトル セット内のタイトルすべてに対して常に有効になっている。ほとんどの DVD において、VTSM サブメニューは使用されない。ルート メニューなどのサブメニューはすべてオプションであるため、VTSM 内のサブメニューがすべて共通のルート メニューを持っているとは限らない。

ペアレンタル ロック レベル

DVD ディスクのすべてまたは一部は、1～8 のペアレンタル ロック レベル (PML) でコード化できる。8 は最も強い制限 (成人のみ) で、1 は最も弱い制限 (年齢制限なし) である。この考え方は、親の承諾なしに子供が成人向けコンテンツを見ることがないようにし、大人は子供が見られないコンテンツを見ることができるというものである。アメリカおよびカナダでは、MPAA のレーティング システム (G、PG、PG-13、NC-17) にレベルを割り当てているが、他の国では事情が異なる。

チャプターはペアレンタル ブロック内に論理的に存在することができるため、タイトル内に同一チャプターの 2 つのバージョンを含んで、それぞれに異なる PML を異なるペアレンタル ブロックにおいて割り当てることができる。たとえば、アプリケーションが PML をサポートしていれば、ディスクにログインした子供がチャプター 3 の 1 つのバージョンを見る一方で、ディスクにログインした大人は異なるバージョンを見ることができる。

タイトルまたはチャプターにテンポラリ PML を含むこともできる。全体として、その内容にはタイトルまたはチャプターより高いレーティングが与えられる。これは、タイトルが複数のペアレンタル ロック レベルを持てることを意味している。テンポラリ PML は一般的にアングル ブロックとして作成されるため、ムービーの特定のシーンに子供用、大人用の 2 つのバージョンを含むことができる。

ペアレンタル ロック レベルを適用するのは、プレーヤー アプリケーションの役割である。

ドメイン

ドメインの概念は DVD の操作にとって非常に重要であるが、ドメインはタイトル、メニュー、およびアングル ブロックと同じ方式でディスク上に物理的にマークされているわけではなく、DVD の作成者には制御できない。DVD ドメインは、5 つの可能な値を持つ状態変数の一種と考えることができる。DVD プレーヤーは、現在ディスクから読み取り中のコンテンツの種類を把握するために、この状態変数を監視する。DVD プレーヤーはドメインを使用することによって、DVD ドライブに意味のないコマンドを発行しないようにできる。たとえば、"SelectButton" コマンドに意味があるのはメニューが表示されている場合のみであり、"FastForward" コマンドはプレーヤーが現在停止しているか、または静止画像であるメニューを表示中である場合は意味をなさない。次の表に、ドメインの一覧を示し、アプリケーション側から見た意味を示す。
ドメイン | DVD ナビゲータが読み取り中のコンテンツ
First Play | ディスクの最初のセクション (FBI 警告など)。
Video Manager Menu | ディスク全体またはディスクの面のメイン メニュー。メニュー関連のメソッドはすべて有効。
Video Title Set Menu | タイトルまたはタイトルのグループのメニュー、あるいはサブメニュー (サブピクチャ、言語、オーディオ、またはアングル)。メニュー関連のメソッドはすべて有効。
Title | タイトル内のビデオ コンテンツ。メニュー関連のメソッドは有効ではない。
Stop | なし。ヘッドがディスクから離れている。ここから、Play を呼び出せる。

ユーザーの動作制御

ユーザーの動作制御 (UOP) はディスク上のマーカーであり、DVD の作成者はこのマーカーを任意の位置に挿入して、ユーザーの操作オプションを制限することができる。ほとんどのディスクは、標準の UOP 制限に準拠している。たとえば、ほとんどのディスクは First Play ドメインにおいて高速な早送りやメニューの表示をユーザーに行わせないようにしている。基本的には、コマンドが現在のドメイン内で通常は有効になる場合でも、すべてのディスクにおいて任意の UOP コマンドを任意の位置に挿入することができる。たとえば、ディスクの特定のタイトルで高速の早送りができないようにしたり、 ユーザーがタイトル ドメインを入力した後に特定のメニューが表示されないようにすることができる。DVD ナビゲータは、ディスクからのそういったコマンドにすべて準拠しており、 アプリケーションがディスクの UOP 制御をオーバーライドしないようにしている。


C++ による DVD アプリケーションの開発

ここでは、C++ で DVD アプリケーションを作成するための主要な手順について説明する。ここで示したコード例のほとんどは、DirectShow 8.0 DVD サンプル アプリケーションから取ったものである。このアプリケーションは、DirectShow SDK のサンプル ディレクトリに格納されている。ここには、以下のトピックが含まれる。DVD の基本的な一般概念の背景情報については、「DVD の基礎」を参照すること。

  • DVD アプリケーション開発の基礎
  • DVD フィルタ グラフの構成
  • DVD フィルタ グラフの作成
  • DVD イベント通知の処理
  • DVD メニューの操作
  • オーディオ ストリームとサブピクチャ ストリーム
  • ペアレンタル ロック レベルの適用
  • DVD テキスト文字列の操作
  • DvdState オブジェクトの保存と復元
  • カラオケ オーディオ ストリームの再生
  • DVD コマンドの同期化
  • DVD コマンド フラグ
  • ディスクの取り出し処理

DVD アプリケーション開発の基礎

DVD アプリケーションを開発する際には、ユーザー インターフェイス用のコードを用意し、Microsoft® DirectShow® アプリケーション プログラミング インターフェイス (API) を呼び出して DVD の再生と操作のためのすべてのコマンドを実行する。これには、Component Object Model (COM) における DVDGraphBuilder オブジェクトの CoCreateInstance メソッドの呼び出しが含まれる。これにより、DVD フィルタ グラフを作成する実際の作業が行われる。フィルタ グラフが作成されたら、DVD ナビゲータ ソース フィルタによって公開される IDvdControl2 および IDvdInfo2 インターフェイスへのポインタを取得できる。インターフェイス ポインタを取得したら、インターフェイスを PlayTitle、Pause などの DVD 操作コマンドに結びつける。この基本プロセスは非常に単純で、他の種類の DirectShow アプリケーションの作成と似ている。

DVD フィルタ グラフの構成

一般に、DVD フィルタ グラフは自動的に作成されるため、アプリケーション開発者はその詳細について関わる必要はない。このトピックは、内部で何が行われているかを知りたい人のために用意されている (ここで触れている個々のフィルタの詳細については、「フィルタ」を参照すること)。

次の図に、標準的な DVD フィルタ グラフを示す。

DVD フィルタ グラフ

DVD ナビゲータは、DVD 再生フィルタ グラフの最初のフィルタであり、以下の作業を行う。

  • ディスクから操作データおよびビデオ データを読み取る。
  • 多重化されているビデオ、オーディオ、およびサブピクチャ データから個々のストリームを取り出す。
  • 以降の処理と最終的なレンダリングのためにストリームをグラフに取り込む。
  • アプリケーションに DVD 関連イベントを通知する。

オーディオ ストリームに対しては、DVD ナビゲータの後にオーディオ デコーダが接続され、それはさらにデフォルトのオーディオ レンダラである デフォルト DirectShow デバイス フィルタに接続される。ビデオおよびサブピクチャ ストリームに対しては、DVD ナビゲータに続くフィルタとしてサードパーティ製ビデオ デコーダ、オーバーレイ ミキサー、およびビデオ レンダラが接続される。アプリケーションが Line 21 クローズド キャプション データを処理する場合には、DirectShow Line 21 デコーダ フィルタをグラフに追加する必要がある。これには 1 つのメソッド呼び出しが含まれる。このフィルタはビデオ デコーダとオーバーレイ ミキサーの間に自動的に接続される。

アプリケーションは、DVD ナビゲータが公開するカスタム インターフェイスを通じて、DVD ナビゲータと通信し、それを制御する。これは IDvdControl2 ("set" メソッド) と IDvdInfo2 ("get" メソッド) である。また、アプリケーションはグラフの停止や開始などの制御を行うために、フィルタ グラフ マネージャと (IMediaControl を通じて) 通信する必要がある。さらに、場合に応じて、ウィンドウ表示と全画面表示を切り替えるためのオーバーレイ ミキサー フィルタなど、他の個別のフィルタも制御する必要がある。詳細については、「IMixerPinConfig2」を参照すること。グラフの厳密な構成は、インストールされている MPEG-2 デコーダの種類、Line 21 クローズド キャプション データを処理する必要があるかどうかなど、いくつかの条件によって異なる。

DVD フィルタ グラフの作成

DVD 再生フィルタ グラフを作成する方法としては、DVDGraphBuilder オブジェクトによって自動的に行うことを推奨する。このアプローチは、以下の説明、および DVD サンプル アプリケーションで示されている。DVD フィルタ グラフを手動で作成する必要がある場合は、DirectShow に関する他の文書に記載されているグラフ作成の基本的な規則に従って作成することができる。一般に、DVDGraphBuilder によって作成されたグラフに対して個々のフィルタを手動で追加、削除、接続、接続解除することは推奨されない。そのような操作をすると、クリーンアップ コードによる処理で混乱が生じる可能性がある。

DVDGraphBuilder オブジェクトのインスタンスを作成すれば、アプリケーションは単にその IDvdGraphBuilder::RenderDvdVideoVolume メンバ関数を呼び出せばよい。この関数は、ローカル システムに存在する DirectShow フィルタと MPEG-2 デコーダからフィルタ グラフを作成する。詳細については、「フィルタ グラフの構築」を参照すること。

フィルタ グラフが作成されると、アプリケーションは DVD ナビゲータ、フィルタ グラフ マネージャ、およびビデオ ウィンドウの制御に必要なポインタを取得できる。以下のコード例には、エラー チェックなどのコードを省いて単純化した基本的な手順を示している。完全なコードは、DirectX8 SDK DXF\samples\multimedia\dshow\dvd ディレクトリにある DirectShow DVDSample アプリケーションで CDvdCore::BuildGraph() メソッドに含まれている。

   // DVD Graph Builder オブジェクトのインスタンスを作成する。
   HRESULT hr;
   hr = CoCreateInstance(CLSID_DvdGraphBuilder,
                          NULL,
                          CLSCTX_INPROC_SERVER,
                          IID_IDvdGraphBuilder,
                          reinterpret_cast<void**>(&m_pIDvdGB));
   // DVD フィルタ グラフを作成する。
   AM_DVD_RENDERSTATUS	buildStatus;
   hr = m_pIDvdGB->RenderDvdVideoVolume(pszwDiscPath, m_dwRenderFlags, &buildStatus);
   // DVD ナビゲータ インターフェイスへのポインタを取得する。
   hr = m_pIDvdGB->GetDvdInterface(IID_IDvdInfo2, reinterpret_cast<void**>(&m_pIDvdI2));
   hr = m_pIDvdGB->GetDvdInterface(IID_IDvdControl2, reinterpret_cast<void**>(&m_pIDvdC2));
   ...
   // フィルタ グラフ マネージャへのポインタを取得する。
   hr = m_pDvdGB->GetFiltergraph(&m_pGraph) ;
   ...
   // グラフ ポインタを使用して IMediaControl へのポインタを取得する。
   // これはフィルタ グラフを全体として制御するために使用する。
   hr = m_pGraph->QueryInterface(IID_IMediaControl, reinterpret_cast<void**>(&m_pIMC));
   ...
   // IMediaEventEx へのポインタを取得する。
   // これは DVD およびその他のフィルタ グラフ イベントの処理に使用される。
   hr = m_pGraph->QueryInterface(IID_IMediaEventEx, (LPVOID *)&m_pME) ;
   ...
   // 再びグラフ ビルダ ポインタを使用して IVideoWindow インターフェイスを取得する。
   // これはビデオ レンダリング フィルタのウィンドウ スタイルとメッセージ処理動作の設定に使用される。
   hr = m_pIDvdGB->GetDvdInterface(IID_IVideoWindow, reinterpret_cast<void**>(&m_pIVW));
   hr = m_pDvdGB->GetDvdInterface(IID_IAMLine21Decoder, (LPVOID *)&pL21Dec) ;

DVD イベント通知の処理

DVD ナビゲータは、特定のイベントが発生したときに、アプリケーションで指定されたウィンドウに通知を送信する。これは、DVD ドメインが変更された場合、新しいペアレンタル ロック レベルを検出した場合、および DVD ナビゲータがアングル ブロックに入る場合などである。イベント パラメータには、イベントに関する追加情報を含むことができる。エラー メッセージや警告も同じ方法で送信される。アプリケーションは、IMediaEventEx ポインタを使って SetNotifyWindow を呼び出すことで、イベント通知を処理するウィンドウを次のように指定する。

    hr = m_pIME->SetNotifyWindow(reinterpret_cast<OAHWND>(m_hWnd), WM_DVD_EVENT, 0);

上記の例において、m_hWnd はメッセージを受信するウィンドウの HWND であり、WM_DVD_EVENT は DVD イベントの発生を示すアプリケーション定義メッセージ (WM_USER より大きい) である。イベント自体は、アプリケーションで IMediaEvent::GetEvent を呼び出すことで取得される。特定の時点でイベント キュー内に複数のイベントが存在する場合があるため、アプリケーションはキュー内のすべてのイベントが取得されるまで繰り返すループの中で GetEvent を呼び出す必要がある。これを次のコード例に示す。

while (SUCCEEDED(m_pIME->GetEvent(&lEvent, &lParam1, &lParam2, lTimeOut)))
    {
        HRESULT hr;
        switch(lEvent)
        {

        case EC_DVD_CURRENT_HMSF_TIME:
        {
            DVD_HMSF_TIMECODE * pTC = reinterpret_cast<DVD_HMSF_TIMECODE *>(&lParam1);
            m_CurTime = *pTC;
            ...
        }
        break;
        ...
    }

DVD イベントでは、上記のように lParam1 または lParam2 パラメータに追加情報が含まれる場合がある。ここでは lParam1 に現在の時刻が含まれている。このコード例は Dvdcore.cpp の DVD サンプル アプリケーションから取ったものである。DVD イベントとそのパラメータの完全なリストは、「DVD イベント通知コード」を参照すること。

DVD メニューの操作

DVD メニューの論理的な構造は、「DVD 操作の基礎」で説明している。アプリケーションは、IDvdControl2::ShowMenu を呼び出して表示したいメニューのインデックスを渡すことにより、ディスクからメニューを表示できる。

ボタンを選択したときには、単にその境界線が強調表示されるだけであることに注意する。ボタンのコマンドを実行するには、ボタンをアクティブにする必要がある。IDvdControl2 メソッドの中には、指定されたボタンを選択するものと、ボタンをアクティブにするものとがある。SelectAndActivateButton は、その両方を行う。DVD サンプル アプリケーションの CDvdCore::OnMouseEvent では、マウスでメニュー ボタンを選択してアクティブにする方法が示されている。

アプリケーションでは、IDvdControl2 のメニュー関連メソッドを使用してメニューをプログラム的に制御できる。アプリケーションは、マウスの移動などのユーザーの動作や、その他のプログラム ロジックに基づいて、ボタンを強調表示 (選択) することができる。また、DVD のリモコン上のボタンを表すカスタム メニューまたはビットマップを実装して制御することもできる。DVD サンプル アプリケーションでは、相対ボタン メニュー コマンドがキーボードの矢印キーに関連付けられている (CDvdCore::OnKeyEvent を参照すること)。ボタンをプログラム的にアクティブにするにはさまざまな方法があるが、アクティブにする前に必ずそのボタンを選択する必要がある。

オーディオ ストリームとサブピクチャ ストリーム

DVD-Video ディスクには、最大で 8 つのオーディオ ストリームを含むことができる。これには 0 から 7 までの番号が付けられ、それぞれ 6 つまでの独立したチャンネルを持つ (オーディオ ストリームとサブピクチャ ストリームは番号が 0 から始まるが、タイトル、アングル、およびペアレンタル ロック レベルは 1 から始まることに注意)。これらのうち、同時に選択できるのは 1 つのストリームだけである。サブピクチャの場合は、最大で 32 個のストリームが使用できるが、同時にアクティブにできるのは 1 つだけである。一般に、ディスクはデフォルトのオーディオおよびサブピクチャ ストリームで作成されているが、アプリケーションによって、ユーザーに使用可能なストリームのリストを表示して、希望する言語のストリームを選択させることもできる。このプロセスにおける基本的な手順は、オーディオ ストリームの場合もサブピクチャ ストリームの場合も同じである。

  1. タイトルに対して使用可能なストリームの数を決定する。
  2. 各ストリームを順番に見て、それぞれのストリーム属性を取得する。
  3. 返されたロケール識別子 (LCID) から言語コードを取得して、人間が読める文字列を作成する。
  4. ユーザーが希望のストリームを選択できるように、リスト ボックスやその他のユーザー インターフェイス (UI) コントロールを設定する。

DVD サンプル アプリケーションでは、Dialogs.cpp の CAudioLangDlg::MakeAudioStreamList メソッドに基本的な手順が示されている。

ペアレンタル ロック レベルの適用

DVD-Video ディスクのタイトルやタイトルの一部には、一般的なペアレンタル ロック レベル (PML) 1 から 8 までを割り当てることができる。PML が割り当てられたコンテンツを DVD ナビゲータが読み取る場合、"ペアレンタル ブロック" がかかっていると表現する。1 つのペアレンタル ブロックが、チャプターの一部、複数のチャプター、または複数のタイトルから構成される場合もある。国際市場に向けて作成される DVD アプリケーションでは、そのペアレンタル ロック ロジックに特定のレーティング システムをハード コードすべきではない。

DVD ナビゲータ自体は PML を適用することはない。単に、ディスク上で PML 情報を検出したときにアプリケーションに通知するだけである。デフォルトでは、DVD ナビゲータはディスク上のこの情報を無視し、最高レベルのコンテンツを再生する。PML を適用するには、アプリケーションが何らかの形のパスワード制御ロジックを実装してユーザーとレベルを関連付け、PML イベント通知を送信するように DVD ナビゲータに指示して (起動時に DVD_NotifyParentalLevelChange と TRUE のパラメータで IDvdControl2::SetOption を呼び出す)、このイベントに応答することでアクセスの可否を決定する必要がある。

DVD タイトルには全体で 1 つの PML を割り当ててもよいが、ディスク作成者はそのタイトルの特定の部分に高い (制限の強い) PML を割り当てることもできる。これをテンポラリ PML コマンドと呼ぶ。このようなコマンドには、常に 2 つの分岐命令が含まれる。1 つは、テンポラリ PML コマンドがプレーヤー アプリケーションによって受け入れられた場合に使用され、もう 1 つはコマンドが拒否された場合に使用される。イベントのシーケンスは次のようになる。DVD ナビゲータがビデオ コンテンツ (DVD タイトル ドメイン) の読み取り中にディスク上にテンポラリ PML コマンドを検出する。DVD ナビゲータはその内部フラグをチェックして、アプリケーションがこのイベントの通知を要求しているかどうかを調べる。フラグが設定されていなければ、DVD の再生を続け、ディスク上に指定された "ペアレンタル ロック レベル変更拒否" の分岐をたどる。フラグが設定されている場合は、DVD はアプリケーションに EC_DVD_PARENTAL_LEVEL_CHANGE イベントを送信して、応答が返るまでポーズ状態で待つ。アプリケーションは、イベントを受信すると、独自のロジックを使用してそのコマンドを受け入れるかどうかを決定する。そして、TRUE または FALSE の引数で IDvdControl2::AcceptParentalLevelChange を呼び出す。TRUE の場合、DVD ナビゲータは再生を再開し、ディスク上に指定された "ペアレンタル ロック レベル変更受け入れ" の分岐をたどる。FALSE の場合は、再生を再開し、"ペアレンタル ロック レベル変更拒否" の分岐をたどる。

DvdState オブジェクトの保存と復元

DvdState オブジェクトにより、アプリケーションはユーザー セッションのスナップショットを保存することができる。これには、ディスク上の現在位置、視聴者のペアレンタル ロック レベル、選択されているオーディオおよびサブピクチャ ストリームなどの情報が含まれる。このことは、ユーザーが DVD-Video ディスク上の現在位置を保存して、後でそこから見続けられることを意味する。

アプリケーションで DvdState オブジェクトを作成することはできない。このオブジェクトは、アプリケーションが IDvdInfo2::GetState を呼び出したときに DVD ナビゲータが内部で自動的に作成する。DvdState オブジェクトは、IDvdState インターフェイスを公開して、アプリケーションが特定の情報を照会できるようにする。

DVD サンプル アプリケーションでは、CDvdCore::RestoreBookmark および CDvdCore::SaveBookmark 関数に DvdState オブジェクトの保存および復元方法が示されている。

DVD テキスト文字列の操作

DVD ディスク、特にカラオケ ディスクには、ビデオまたはオーディオ コンテンツを補足するテキスト情報のデータベースが含まれている場合がある。カラオケ ディスク上のそのようなテキストとしては、曲名、アーティスト名、レコード レーベルなどがある。このテキストは、複数の言語で存在することができる。このような文字列はオプションであり、ディスク上に必ず含めなければならないわけではない。文字列が含まれる場合は、DVD ボリュームの論理的な階層を厳密に反映するように構成される。各文字列の前には、その文字列がディスク構造のどの部分に属するかを識別し、文字列の内容の手がかりとなるような数字が付加される。文字列の型の一部が DVD_TextStringType 列挙に定義されている。

テキスト文字列には、基本的な型として構造識別子と内容文字列の 2 つがある。0x01 ～ 0x20 の値を持つ型が構造識別子である。これは空の文字列であり、数値コードはその後に続く内容文字列が属する論理構造を識別するために使用される。この構造は、DVD ディスクの内容 (ボリューム、タイトル、チャプターなど) の論理構造とかなり厳密に対応している。もう一方の型は、ユーザー インターフェイスで視聴者に表示される情報を保持する内容文字列を識別する。内容文字列の使用方法は厳密には定義されていないため、DVD 作成者はさまざまな方法でそれを使用できる。

これまで、DVD テキスト文字列はほとんどカラオケ ディスク専用に使用されてきた。これらのディスクは、ほとんどの場合、0x01 と 0x02 の構造識別子と 0x30 の内容文字列を使用している。しかし、時がたつにつれて、より多くの種類の DVD-Video ディスクにテキスト文字列が含まれるようになると考えるのが妥当である。これらの文字列は、より複雑に構成され、ディスク内容の詳細な記述を提供するようになるであろう。

DVD テキスト文字列については、DVD フォーラムの Web サイト (www.dvdforum.org) を参照すること。

DVD サンプル アプリケーションの CDvdCore::GetDvdText メソッドに、DVD テキスト文字列を列挙して表示する基本的な手順が示されている。

カラオケ オーディオ ストリームの再生

DVD ナビゲータは、カラオケ オーディオ ストリームを含む DVD-Video ディスクを再生できるが、カラオケの再生にはマルチチャンネル カラオケ ミキシングをサポートするデコーダも必要である。具体的に言えば、このデコーダは DVD カラオケ プロパティ セット (AM_KSPROPSETID_DvdKaraoke) をサポートする必要がある。

カラオケ ディスクは DVD-Video ディスクの一種であり、同じ操作構造を持っている。曲は一般にタイトルとしてフォーマットされ、タイトルは演奏者や音楽スタイルなどの条件に基づいてタイトル セットにグループ化できる。カラオケ ディスクと他の種類の DVD-Video との主な違いは、オーディオ ストリームである。すべてのカラオケ ディスクには、マルチチャンネル オーディオ (通常は Dolby AC-3) が含まれている。チャンネル 0 および 1 には常にバックグラウンドの演奏が含まれ、チャンネル 2 ～ 5 にはそれぞれガイド ボーカル、ガイド メロディ、サウンド エフェクトの任意の組み合わせを含むことができる。カラオケ アプリケーションは、各補助チャンネルについてボリュームと出力先スピーカを制御できる。

DVD ナビゲータはディスク上にカラオケ コンテンツを検出してカラオケ モードに入ると、デコーダにそれを通知し、デコーダはアプリケーションによって明示的にオンにされるまで上位 3 つのチャンネル (補助チャンネル) を無音状態にする。カラオケ アプリケーションの基本的な動作は次のとおりである。

  1. IDvdInfo2 メソッドを使用して補助チャンネルの数とその内容を確認する。
  2. IDvdControl2::SelectKaraokeAudioPresentationMode を使用して、チャンネルの内容を表示してユーザーがいつでも任意の補助チャンネルをオンまたはオフにできるようにするユーザー インターフェイスを提供する。

これらの手順は、DVD サンプル アプリケーションの DVDCore.cpp の GetAudioAttributes メソッドに示されている。

DVD コマンドの同期化

ここには、以下のサブトピックが含まれる。

  • コマンドの同期化について
  • アプローチ 1 : 同期化なし
  • アプローチ 2 : 同期化なしの単純なブロッキング
  • アプローチ 3 : 同期化オブジェクトのみを使用
  • アプローチ 4 : イベントを使用した一度に 1 コマンドの同期化
  • アプローチ 5 : イベントと IDvdCmd オブジェクトを使用した同期化

コマンドの同期化について

コマンドの同期化は、DVD ナビゲータおよび一般的な DVD の操作に精通した開発者のための高度なトピックであり、アプリケーションでコマンドの同期化による洗練された機能を必要とする場合に役立つ。まだ DVD ナビゲータを使い始めたばかりである場合や、アプリケーションでコマンドの同期化を必要としない場合には、単にアプローチ 1 に示される各種の再生コマンドを使用する。コマンドの同期化は、後からいつでも導入することができる。

IDvdControl2 の各種の再生メソッド (PlayTitle など) は、本質的に非同期である。メソッドが呼び出されると、必要なすべての手順を実行する前に、メソッドは直ちに結果を返す。メソッド呼び出しが正常に結果を返してからその動作が最終的に完了するまでの間、他のコマンドが実行されて DVD ナビゲータが新しい DVD ドメインまたは新しいフィルタ状態に入り、メソッドがすべての必要な手順を正常に完了できない場合がある。たとえば、アプリケーションが PlayTitle を呼び出して、その後すぐにユーザーが停止ボタンをクリックしたとする。コマンドが同期化されていないと、DVD ナビゲータは、ディスクが指定された位置で再生を開始する前に DVD 停止ドメインに入る場合がある。これは、全体の動作が実行される前に PlayTitle が正常に結果を返すためである。最終的にディスクが再生を開始したときに、DVD ナビゲータが既に正しい状態でなくなっていて、エラーが生じる場合がある。

多くのメソッド呼び出しが特定の状態の DVD ナビゲータに依存しているため、アプリケーションはコマンドを同期化する方法を必要とする。これには次の 2 つの基本的な機能が含まれる。

  • 非同期動作が実際に完了したときにそれを認識し、最終的な結果が何であるかを認識する。これは、動作が正常に開始されたかどうかを識別するだけのメソッド呼び出しの戻り値とは異なる。
  • 動作が完了するまで DVD ナビゲータが以降のコマンドを処理しないようにブロックすることができる。

DVD ナビゲータはアプリケーションにこれらの機能を提供し、コマンドの同期化のためのいくつかのオプションを提供する。IDvdControl2 の各再生メソッドには同期化のためのパラメータが 2 つある。1 つは同期化オブジェクトへのインターフェイス ポインタであり、もう 1 つは DVD コマンド フラグのセットである。アプリケーションはこれらのパラメータを使用して、コマンドの同期化を必要に応じたさまざまな方法で実装できる。

アプローチ 1 : 同期化なし

メソッド呼び出しの非同期の性質を保持するには、次の構文を使用する。ここで、pDVDControl2 は IDvdControl2 ポインタである。

HRESULT hres = pDVDControl2->PlayTitle( uTitle,
                                        DVD_CMD_FLAG_None, // = 0
                                        NULL);

アプローチ 2 : 同期化なしの単純なブロッキング

このアプローチでは、DVD コマンド フラグを使用して、コマンド同期化オブジェクトを管理しない単純なブロッキングを実現する。これは、同期化オブジェクトを管理したりイベント通知を処理する必要がないため、最も簡単なコマンドの同期化方法であるが、特定のコマンドの戻り状態を決定することはできない。

HRESULT hres = pDVDControl2->PlayTitle( uTitle,
                                        EC_DVD_CMD_FLAG_Block,
                                        NULL);

アプローチ 3 : 同期化オブジェクトのみを使用

このアプローチは、機能的にはアプローチ 2 と等価である。イベント通知を処理せずに直接 DVD ナビゲータをブロックする別の方法を提供する。アプリケーションが IDvdCmd ポインタのアドレスを渡すと、この特定のコマンドに関連するコマンド同期化オブジェクトを受け取る。オブジェクトの WaitToEnd 関数を呼び出すと、メソッドが正常に完了するまで DVD ナビゲータがブロックされる。その間、新しいコマンドがキューに追加される場合がある。オブジェクトは、使い終わったら必ず解放しなければならない。

IDvdCmd* pObj;
HRESULT hr = pDVDControl2->PlayTitle( uTitle,  0, &pObj);
if(SUCCEEDED(hr))
{
    pObj->WaitToEnd();
    pObj->Release();
}

アプローチ 4 : イベントを使用した一度に 1 コマンドの同期化

IDvdControl2::SetOption の呼び出しで EC_DVD_CMD_FLAG_SendEvents フラグを指定することにより、DVD ナビゲータは "再生" メソッド呼び出しに対してはブロックされない。その代わり、コマンドの開始時、およびその非同期動作の全体が完了したときに、アプリケーションに EC_DVD_CMD_START および EC_DVD_CMD_END イベント通知を送信する。これにより、IDvdCmd オブジェクトを管理せずに単一のイベントを同期化することができる。しかし、IDvdCmd オブジェクトを使用しないため、イベントがどのコマンドに関連するものかを正確に知ることはできない。多くの状況においては、そのような情報は必要とされないため、このアプローチで十分である。

// "SendEvents" を使用して PlayChapterInTitle を呼び出す。
HRESULT hres = pDVDControl2->PlayChapterInTitle( uTitle, 0x2,
                    DVD_CMD_FLAG_SendEvents, NULL);
…
// イベント通知ハンドラ関数において
switch (lEvent)
{
   case EC_DVD_CMD_END:
     DoSomethingGeneric();
     break;
}

アプローチ 5 : イベントと IDvdCmd オブジェクトを使用した同期化

このアプローチは、コマンドの同期化について最高の制御を得ることができるが、実装が最も複雑なアプローチでもある。アプリケーションは、イベントがどのコマンドに関連付けられているかを知ることができるため、EC_DVD_CMD_END イベントへの応答を適宜調整できる。最初の例にシングルスレッドのソリューションを示し、2 番目の例にマルチスレッドのソリューションを示す。

// グローバル コードにおいて
IDvdCmd* pGlobalObj=0;
…
// pGlobalObj はイベントが発行される "前" に Navigator によって
// 割り当てられる。そうしないと、pGlobalObj が割り当てられる前の
// (*1) でイベントが発生する可能性がある。
HRESULT hres = pDVDControl2->PlayTitle( uTitle,
DVD_CMD_FLAG_SendEvents, &pGlobalObj );
// (*1)
If( FAILED( hres)) {
pGlobalObj = NULL;
}
…
switch (lEvent)
{
case EC_DVD_CMD_END:
   IDvdCmd* pObj = GetDvdCmd( lParam1 );
   HRESULT hres = HRESULT( lParam2 );
If( NULL != pObj ) {
    If(pGlobalObj == pObj ) {
…
pGlobalObj->Release();
pGlobalObj = NULL;
}
pObj->Release();
   }
break;

このアプローチは、イベント ループが別のスレッドに存在するときに使用する。

// グローバル コードにおいて
IDvdCmd* pGlobalObj=0;
CcritSect globalCritSect;
…
{
CautoLock(globalCritSect );
HRESULT hres = pDVDControl2->PlayTitle( uTitle,
DVD_CMD_FLAG_SendEvents, &pGlobalObj );
If( FAILED( hres)) {
pGlobalObj = NULL;
}
}
…
switch (lEvent)
{
case EC_DVD_CMD_COMPLETE:
case EC_DVD_CMD_CANCEL:
{
CautoLock(globalCritSect );
IDvdCmd* pObj = GetDvdCmd( lParam1 );
HRESULT hres = HRESULT( lParam2 );
If( NULL != pObj ) {
If(pGlobalObj == obj ) {
…
pGlobalObj->Release();
pGlobalObj = NULL;
}
pObj->Release();
}
break;
}

DVD コマンド フラグ

SetOption の dwFlags パラメータに渡される DVD コマンド フラグは、同期化オブジェクトに加えて、または同期化オブジェクトの代わりに使用される。これは、特定のメソッド呼び出しに対してどのアプローチを使用するかによって異なる。DVD_CMD_FLAG_Block の使用はアプローチ 2 に示され、DVD_CMD_FLAG_SendEvents はアプローチ 4 ～ 6 に示されている。これらのフラグはいずれも、他のフラグ DVD_CMD_FLAG_Flush とビット単位の OR で結合することもできる。このフラグは、メソッドが直ちに実行され、フィルタ グラフのバッファ内の 1 ～ 2 秒のビデオが再生されるのを待たないようにする。このフラグを指定すると、ユーザー入力への応答時間が短くなる。次のコマンドが実行される前に特定のビデオ セグメントを完全に終了させる必要がある場合には、このフラグは使用しない。4 つのフラグとそれぞれの意味を次の表に示す。

名前 | 数値 | 意味
DVD_CMD_FLAG_None | 0x00000000 | フラグなし。次のコマンドの前にバッファをフラッシュせず、動作の完了時にイベントを発行せず、DVD ナビゲータはメソッドが結果を返した後にブロックされない。
DVD_CMD_FLAG_Flush | 0x00000001 | バッファを空にして、新しい位置から直ちに再生を開始する。
DVD_CMD_FLAG_SendEvents | 0x00000002 | アプリケーションにイベントを送り返すことで非同期動作の完了とその戻り値を通知するように、DVD ナビゲータに指示する。
DVD_CMD_FLAG_Block | 0x00000004 | 非同期動作が完了するか取り消されるまで DVD ナビゲータをブロックする。

ディスクの取り出し処理

ユーザーが DVD をドライブから取り出すと、DVD ナビゲータはアプリケーションに EC_DVD_DISC_EJECTED メッセージを送信する。アプリケーションはこのメッセージを無視しても問題なく、DVD ナビゲータにグラフの状態を管理させる。また、アプリケーションは、EC_DVD_DISC_EJECTED メッセージを処理して、ディスクの取り出し時にカスタム動作を実現することもできる。メッセージを処理する場合は、SetOption メソッドで DVD_ResetOnStop フラグを TRUE に設定してから、アプリケーションを閉じるか他のディスクを再生する前に、IMediaControl::Stop を呼び出す必要がある。


C++ DVD に関する参照ページへのショートカット

C++ で DVD アプリケーションを記述する場合には、一般に以下のインターフェイスが使用される。
インターフェイス | 目的
IAMLine21Decoder | クローズド キャプション表示を制御する。
IDvdCmd | 高度なコマンド同期化技法においてコマンド オブジェクトの制御に使用される。
IDvdControl2 | DVD ナビゲータ フィルタにコマンドを投入する ("set" メソッド)。
IDvdGraphBuilder | DVD フィルタ グラフを作成する。
IDvdInfo2 | ステート情報およびディスク情報について DVD ナビゲータに問い合わせる ("get" メソッド)。
IDvdState | ブックマークなどの情報をディスクに保存する。
IVideoFrameStep | "コマ送り" を制御する (デコーダでサポートされている場合)。


スクリプト ベースの DVD アプリケーションの記述

ここでは、MSWebDVD ActiveX® コントロールを使用してスクリプト ベースの DVD アプリケーションを記述する場合の基本的な作業について説明する。以下で述べる DVD 操作の概念に関する背景知識については、「DVD の基礎」を参照すること。

  • MSWebDVD オブジェクトの埋め込み
  • ユーザーが DVD コマンドを発行できるようにする
  • DVD メニューの操作
  • オーディオ ストリームとサブピクチャ ストリーム
  • ペアレンタル ロック レベルの適用
  • ブックマークの保存と復元
  • DVD イベント通知の処理
  • UOP イベント通知の処理
  • HTML コンテンツとビデオの同期化
  • LCID の操作
  • カラオケ ディスクの再生
  • DVD テキスト文字列の操作

MSWebDVD オブジェクトの埋め込み

MSWebDVD オブジェクトによって、すべての DVD 操作コマンドおよびビデオ矩形表示が処理される。オブジェクトは、ビデオ表示矩形として Web ページに表示される。したがって、HTML ドキュメントの BODY 要素に埋め込む必要がある。矩形の幅と高さ、およびアプリケーションに必要なすべてのプロパティのデフォルト値を設定する。

<OBJECT CLASSID=clsid:38EE5CEE-4B62-11D3-854F-00A0C9C898E7 ID=DVD
STYLE="height:369px; width:740px">
<PARAM NAME="BackColor" VALUE="1048592">
<PARAM NAME="EnableResetOnStop" VALUE="-1">
<PARAM NAME="ColorKey" VALUE="1048592">
</OBJECT>

ユーザーが DVD コマンドを発行できるようにする

ユーザーが DVD プレーヤーを制御できるようにするには、 "Stop" や "Play" などの DVD コマンドを発行するためのボタンが付いた UI を作成する必要がある。次のコード例では、基本的な HTML ボタンを MSWebDVD オブジェクト メソッドに結びつける方法を示す。

<INPUT ID=button1 NAME="button1" TYPE=button VALUE="Play" onClick='Play();'>
<INPUT ID=button2 NAME="button2" TYPE=button VALUE="Pause" onClick='Pause();'>

<SCRIPT LANGUAGE="JScript">
function Play(){
     DVD.Play();
}

function Pause(){
DVD.Pause();
}

</SCRIPT>

DVD メニューの操作

ユーザーがマウスで画面上のボタンをクリックすると、MSWebDVD は自動的にメニュー コマンドを処理する。基本的なマウスのサポートを実装するために、アプリケーションで何か行う必要はない。しかし、メニュー ボタンのクリックで別の動作が行われるようにするために、この自動的なマウスの処理をアプリケーションによって無効にできる。たとえば、ユーザーがクリックしたボタンに応じて、特定のテキストまたはイメージを表示させることができる。カスタム マウス処理を実装するには、SelectAndActivateButton、GetButtonAtPosition などの MSWebDVD メニュー関連メソッドを使用する。 自動的なマウスの処理を完全に無効にするには、DisableAutoMouseProcessing プロパティを TRUE に設定する。

MSWebDVD では、SelectUpperButton などのメソッドのセットにより、DVD リモート コントロールを表すイメージ マップ、および現在のメニューを上下左右に動かすためのボタンを Web ページに表示させることができる。ドキュメントの中では、これらのボタンを "方向" ボタンまたは "相対" ボタンと呼んでいる。DVD メニューのボタンとは異なり、方向ボタンはアプリケーションによって表示される。

オーディオ ストリームとサブピクチャ ストリーム

DVD-Video ディスクには最大 8 つのオーディオ ストリームを含むことができる。これには 0 から 7 までの番号が付けられ、それぞれ 6 つまでの独立したチャンネルを持つ。これらのうち、同時に選択できるのは 1 つのストリームだけである。サブピクチャの場合は、最大で 32 個のストリームを使用でき、0 から 31 までの番号が付けられている。これらのうち、同時に選択できるのは 1 つのストリームだけである。一般に、ディスクはデフォルトのオーディオおよびサブピクチャ ストリームを使って作成されているが、アプリケーションによって、特定のタイトルに対して使用可能なストリームをユーザーにすべて表示して、希望する言語のストリームを選択させることもできる。このプロセスにおける基本的な手順は、オーディオ ストリームの場合も、サブピクチャ ストリームの場合も同じである。

  1. 指定されたタイトルに対して使用可能なストリームの数を決定する。
  2. 各ストリームを順番に見て、それぞれのストリーム属性を取得する。
  3. 返されたロケール識別子 (LCID) から言語コードを取得して、人間が読める文字列を作成する。
  4. ユーザーが希望のストリームを選択できるように、"選択" ボックスやその他のユーザー インターフェイス コントロールを設定する。

(オーディオおよびサブピクチャ ストリームには 0 から番号が付けられているのに対して、タイトル、アングル、およびペアレンタル ロック レベルには 1 から番号が付けられていることに注意する)

ペアレンタル ロック レベルの適用

DVD-Video ディスクのタイトルやタイトルの一部には、一般的なペアレンタル ロック レベル (PML) 1 から 8 までを割り当てることができる。 8 は最も制限の強いレベルで、0 は最も制限の弱いレベルである。これは、親の承諾なしに子供が成人向けコンテンツを見ることを防ぐ方法を提供するという考え方である。各レベルの意味は国によって異なる。アメリカとカナダでは、Motion Picture Association of America のレーティング システム (G、PG、PG-13、NC-17) にレベルを割り当てているが、他の国では事情が異なる。国際的な市場向けの DVD アプリケーションでは、ペアレンタル ロック ロジックに特定のレーティング システムをハード コードすべきではない。

MSWebDVD オブジェクトは、デフォルトでディスク上の PML を無視する。ディスク上の PML マーカーが通知されるアプリケーションの場合は、NotifyParentalLevels(TRUE) を呼び出す必要がある。それにより MSWebDVD は、ディスク上で PML 情報を検出したときにアプリケーションに通知するようになる。PML を適用するには、ユーザーとレベルを関連付ける何らかのパスワード制御ロジックをアプリケーションに実装し、EC_DVD_PARENTAL_LEVEL_CHANGE イベントに応答してアクセスの許可または拒否を適切に行わなければならない。

ブックマークの保存と復元

ブックマークとは、現在のユーザー セッションのスナップショット (ディスク上の現在位置、DVD を見ているユーザーのペアレンタル ロック レベル、選択されたオーディオおよびサブピクチャ ストリーム、その他の情報) を作成するために MSWebDVD オブジェクトが使用する内部データ構造である。つまり、ユーザーは DVD-Video ディスク上の位置を保存し、後でその位置から再生することができる。

ユーザーは、SaveBookmark によってディスク上の位置を保存し、RestoreBookmark メソッドによって保存した位置から再生を再開できる。

一度に保存にできるブックマークは 1 つのみである。SaveBookmark を 2 回呼び出すと、最初のブックマークがオーバーライドされる。ブックマークは、コンピュータに固有のものである。同じ HTML ページを別のコンピュータで動作させて RestoreBookmark を呼び出すと、そのコンピュータで最後に保存されたブックマークが復元される。ブックマークが保存されていない場合はエラーが返される。

DVD イベント通知の処理

MSWebDVD オブジェクトは、特定のイベントが発生したときに、アプリケーションで指定されたメソッドに通知を送信する。これは、DVD ドメインが変更された場合、新しいペアレンタル ロック レベを検出した場合、およびアングル ブロックに入る場合などである。イベント パラメータには、イベントに関する追加情報を含むことができる。エラーメッセージや警告も同じ方法で送信される。さまざまな DVD イベント通知を取得するには、 MSWebDVD オブジェクトの OBJECT タグの下に次の HTML SCRIPT タグを入力する。

<SCRIPT LANGUAGE="JScript" FOR=DVD EVENT="DVDNotify(EventCode, Param1, Param2)">
    ProcessDVDEvent(EventCode, Param1, Param2)
</SCRIPT>

続いて、次のコード例に示すように、スクリプトにおいてイベント コードおよび ProcessDVDEvent 関数を定義する。(イベント処理関数には任意の名前を付けることができる。"ProcessEvents" である必要はない。)イベント コードの詳細については、「DVD イベント通知コード」を参照すること。

<SCRIPT LANGUAGE="JScript">

// DVD イベント コードには、257 から 283 までの値が設定されている。
var EC_DVDBASE = 256;

var EC_DVD_DOMAIN_CHANGE = (EC_DVDBASE + 1);
var EC_DVD_TITLE_CHANGE = (EC_DVDBASE + 2);
var EC_DVD_CHAPTER_START = (EC_DVDBASE + 3);
var EC_DVD_AUDIO_STREAM_CHANGE = (EC_DVDBASE + 4);
var EC_DVD_SUBPICTURE_STREAM_CHANGE = (EC_DVDBASE + 5);
var EC_DVD_ANGLE_CHANGE  = (EC_DVDBASE + 6);
var EC_DVD_BUTTON_CHANGE = (EC_DVDBASE + 7);
var EC_DVD_VALID_UOPS_CHANGE = (EC_DVDBASE + 8);
var EC_DVD_STILL_ON  = (EC_DVDBASE + 9);
var EC_DVD_STILL_OFF  = (EC_DVDBASE + 10);
var EC_DVD_CURRENT_TIME  = (EC_DVDBASE + 11); // MSWebDVD では使用しない
var EC_DVD_ERROR  = (EC_DVDBASE + 12);
var EC_DVD_WARNING  = (EC_DVDBASE + 13);
var EC_DVD_CHAPTER_AUTOSTOP  = (EC_DVDBASE + 14);
var EC_DVD_NO_FP_PGC  = (EC_DVDBASE + 15);
var EC_DVD_PLAYBACK_RATE_CHANGE  = (EC_DVDBASE + 16);
var EC_DVD_PARENTAL_LEVEL_CHANGE  = (EC_DVDBASE + 17);
var EC_DVD_PLAYBACK_STOPPED  = (EC_DVDBASE + 18);
var EC_DVD_ANGLES_AVAILABLE  = (EC_DVDBASE + 19);
var EC_DVD_PLAYPERIOD_AUTOSTOP  = (EC_DVDBASE + 20);
var EC_DVD_BUTTON_AUTO_ACTIVATED  = (EC_DVDBASE + 21);
var EC_DVD_CMD_START  = (EC_DVDBASE + 22);            // MSWebDVD では使用しない
var EC_DVD_CMD_END = (EC_DVDBASE + 23);               // MSWebDVD では使用しない
var EC_DVD_DISC_EJECTED  = (EC_DVDBASE + 24);
var EC_DVD_DISC_INSERTED  = (EC_DVDBASE + 25);
var EC_DVD_CURRENT_HMSF_TIME  = (EC_DVDBASE + 26);
var EC_DVD_KARAOKE_MODE  = (EC_DVDBASE + 27);

var nCurDomain;
var nCurParentalLevel;

function ProcessDVDEvent(EventCode, Param1, Param2)
{
switch (EventCode)
  {
case EC_DVD_DOMAIN_CHANGE:
nCurDomain = Param1;
// 何か行う。
break;
case EC_DVD_PARENTAL_LEVEL_CHANGE:
nCurParentalLevel = Param1;
// 何か行う
break;

// 他のイベントを処理する

default:
break;
  }

}
</SCRIPT>

UOP イベント通知の処理

MSWebDVD オブジェクトは、ディスクによって特定のユーザー動作 (UOP) が有効または無効になったときに、UOP イベント通知を送信してアプリケーションに知らせる。各ユーザー動作には独自のイベントがあり、その動作が有効か無効かを示す 1 つの Boolean パラメータが設定されている。個々のイベントの詳細については、「MSWebDVD イベント」を参照すること。

処理対象の各イベントに対して、次の例のようにイベント ハンドラを指定する。(任意のハンドラ メソッドを呼び出すことができる。)

<SCRIPT LANGUAGE="JScript" FOR=DVD EVENT="PlayForwards(bEnabled)">
    PlayForwardsEventHandler(bEnabled)
</SCRIPT>
次に、イベントに適切に応答するようにハンドラ メソッドを定義する。ここでは、"button_Play" 変数はアプリケーションの "Play" ボタンの id 属性であると仮定する。
function PlayForwardsEventHander(bEnabled)
{
if(bEnabled == true)
button_Play.disabled = false;
else
button_Play.disabled = true;
}

HTML コンテンツとビデオの同期化

ディスクからのタイムコード イベントを処理することによって、Web アプリケーションは HTML コンテンツをビデオと同期化できる。たとえば、ビデオの指定された位置でページ上のイメージまたはテキストを変更することができる。次のコード例により、JScript 関数呼び出しをタイムコード イベントに同期化させる方法を示す。
//DVDTriggerPoints 配列は、各トリガのフレーム数を保持する。昇順でなければならない。
//timecode2frames() を使用して、タイムコード (hh:mm:ss:ff) をフレームの合計数に変換する。

var DVDTriggerPoints = new Array(
timecode2frames("01:15:24:00"),
timecode2frames("01:23:02:00"));

//DVDTriggerProcs 配列は、DVDTimePoints で定義された各トリガ ポイントで呼び出される関数を保持する。
var DVDTriggerProcs = new Array(
"showDogPic();",
"showCatPic();");

//DVDTriggerIndex は現在のトリガ (DVDTriggerPoints および DVDTriggerProcs を示す) を把握する。
var DVDTriggerIndex = 0;

//DVD イベントを処理する
function ProcessDVDEvent(EventCode, Param1, Param2) {
  switch (EventCode) {
case EC_DVD_CURRENT_HMSF_TIME:
          if(MSWebDVD.CurrentDomain == 4) {  //ディスクが再生中でなければ、チェックは必要ない。
             if (DVDTriggerIndex < DVDTimePoints.length) {  //チェックすべきトリガ ポイントは残っているか?
currentDVDTime = (MSWebDVD.DVDTimeCode2bstr(Param1));
                 if (timecode2frames(currentDVDTime)>= DVDTriggerPoints[DVDTimeIndex]) {
// トリガ ポイントが過ぎたら、関連する関数を実行する。
eval(DVDTriggerProcs[DVDTimeIndex++]);
                 }
             }
          }
break;

// 他のイベントを処理する。
   }
}

function timecode2frames(timeCode) {

   if (timeCode != "undefined") {
return timeCode.substring(0,2)*108000
+ timeCode.substring(3,5)*1800
+ timeCode.substring(6,8)*30
+ timeCode.substring(9,11);
   } else {
return 0;
   }
}

LCID の操作

LCID すなわち "ロケール識別子" は、特定の地理的な範囲を識別できる、いくつかの異なる値を含んだ 32 ビット データ型である。この内部値の 1 つが "プライマリ言語 ID" であり、これによって英語、スペイン語、ロシア語など、地域やロケールの基本的な言語を識別する。

2 つのメソッド (SelectDefaultAudioLanguage と SelectDefaultSubpictureLanguage) に対する入力パラメータとして、MSWebDVD には完全に有効な LCID が必要である。これは Windows® で認識される有効な LCID の場合もあれば、認識されない LCID の場合もある。(ホスト システムが、フォント、キーボード マッピングなどで実際にロケールをサポートしている必要はない。)次の表に、一般的な LCID および、あまり一般的でない LCID (Windows がデフォルトでは認識しないにも関わらず MSWebDVD に対して有効) を示す。これは、使用できる LCID の完全なリストではない。Windows が認識する LCID の完全なリストなど、LCID の詳細については、MSDN オンライン ドキュメント (http://msdn.microsoft.com) を参照すること。
有効な LCID の一部
アフリカーンス語 | 0x0436 | アルバニア語 | 0x041c | アラビア語 (アルジェリア) | 0x1401
アラビア語 (バーレーン) | 0x3c01 | アラビア語 (エジプト) | 0x0c01 | アラビア語 (イラク) | 0x0801
アラビア語 (ヨルダン) | 0x2c01 | アラビア語 (クエート) | 0x3401 | アラビア語 (レバノン) | 0x3001
アラビア語 (リビア) | 0x1001 | アラビア語 (モロッコ) | 0x1801 | アラビア語 (オマーン) | 0x2001
アラビア語 (カタール) | 0x4001 | アラビア語 (サウジアラビア) | 0x0401 | アラビア語 (シリア) | 0x2801
アラビア語 (チュニジア) | 0x1c01 | アラビア語 (アラブ首長国連邦) | 0x3801 | アラビア語 (イエメン) | 0x2401
バスク語 | 0x042d | ベラルーシ語 | 0x0423 | ブルガリア語 | 0x0402
カタロニア語 | 0x0403 | 中国語 (香港) | 0x0c04 | 中国語 (中華人民共和国) | 0x0804
中国語 (シンガポール) | 0x1004 | 中国語 (台湾) | 0x0404 | クロアチア語 | 0x041a
チェコ語 | 0x0405 | デンマーク語 | 0x0406 | オランダ語 (ベルギー) | 0x0813
オランダ語 (標準) | 0x0413 | 英語 (オーストラリア) | 0x0c09 | 英語 (ベリーズ) | 0x2809
英語 (カナダ) | 0x1009 | 英語 (カリブ) | 0x2409 | 英語 (アイルランド) | 0x1809
英語 (ジャマイカ) | 0x2009 | 英語 (ニュージーランド) | 0x1409 | 英語 (南アフリカ共和国) | 0x1c09
英語 (トリニダード) | 0x2c09 | 英語 (イギリス) | 0x0809 | 英語 (アメリカ) | 0x0409
エストニア語 | 0x0425 | フェロー語 | 0x0438 | ペルシア語 | 0ｘ0429
フィンランド語 | 0x040b | フランス語 (ベルギー) | 0x080c | フランス語 (カナダ) | 0x0c0c
フランス語 (ルクセンブルク) | 0x140c | フランス語 (標準) | 0x040c | フランス語 (スイス) | 0x100c
ドイツ語 (オーストリア) | 0x0c07 | ドイツ語 (リヒテンシュタイン) | 0x1407 | ドイツ語 (ルクセンブルク) | 0x1007
ドイツ語 (標準) | 0x0407 | ドイツ語 (スイス) | 0x0807 | ギリシャ語 | 0x0408
ヘブライ語 | 0x040d | ハンガリー語 | 0x040e | アイスランド語 | 0x040f
インドネシア語 | 0ｘ0421 | イタリア語 (標準) | 0x0410 | イタリア語 (スイス) | 0x0810
日本語 | 0ｘ0411 | 韓国語 | 0ｘ0412 | 韓国語 (Johab) | 0x0812
ラトヴィア語 | 0ｘ0426 | リトアニア語 | 0ｘ0427 | マレー語 (マレーシア) | 0x043e
マレー語 (ブルネイ) | 0x083e | ノルウェー語 (ブークモール) | 0x0414 | ノルウェー語 (ニーノシク) | 0x0814
ポーランド語 | 0ｘ0415 | ポルトガル語 (ブラジル) | 0x0416 | ポルトガル語 (標準) | 0x0816
ルーマニア語 | 0ｘ0418 | ロシア語 | 0x0419 | セルビア語 (キリル) | 0x0c1a
セルビア語 (ラテン) | 0x081a | スロバキア語 | 0ｘ041ｂ | スロヴェニア語 | 0ｘ0424
スペイン語 (アルゼンチン) | 0x2c0a | スペイン語 (ボリビア) | 0x400a | スペイン語 (チリ) | 0x340a
Spanish (Colombia)スペイン語 (コロンビア) | 0x240a | スペイン語 (コスタリカ) | 0x140a | スペイン語 (ドミニカ共和国) | 0x1c0a
スペイン語 (エクアドル) | 0x300a | スペイン語 (エルサルバドル) | 0x440a | スペイン語 (グアテマラ) | 0x100a
スペイン語 (ホンジュラス) | 0x480a | スペイン語 (メキシコ) | 0x080a | スペイン語 (現代) | 0x0c0a
スペイン語 (ニカラグア) | 0x4c0a | スペイン語 (パナマ) | 0x180a | スペイン語 (パラグアイ) | 0x3c0a
スペイン語 (ペルー) | 0x280a | スペイン語 (プエルトリコ) | 0x500a | スペイン語 (旧来) | 0x040a
スペイン語 (ウルグアイ) | 0x380a | スペイン語 (ベネズエラ) | 0x200a | スワヒリ語 | 0ｘ0441
スウェーデン語 | 0x041d | スウェーデン語 (フィンランド) | 0x081d | タイ語 | 0x041e
トルコ語 | 0ｘ041ｆ | ウクライナ語 | 0ｘ0422 |  |

いくつかの MSWebDVD メソッドおよびプロパティは、サウンドトラックまたは字幕で利用できる言語を示すロケール識別子 (LCID) 値を返す。この情報を利用するには、アプリケーションによって、返された LCID からプライマリ言語 ID を抽出する必要がある。そのためには、iLCID の値と 0x3FF の間でビットごとの AND 演算を実行する。 (プライマリ言語 ID は、LCID の最下位の 10 ビットに含まれている。)次のコード例により、その方法を示す。

iPrimaryLang = iLCID & 0x3FF;

プライマリ言語 ID から、人間が読める文字列を取得するには、次の例のように GetLangFromLangID を呼び出す。

sLanguage = DVD.GetLangFromLangID(iPrimaryLang);

LCID および言語の識別子の詳細については、Microsoft® Platform SDK を参照すること。

次の表に、前の表の LCID に対するプライマリ言語 ID を示す。

有効なプライマリ言語 ID の一部
アフリカーンス語 | 0ｘ36 | アルバニア語 | 0ｘ1ｃ | アラビア語 | 0x01 | バスク語 | 0ｘ2ｄ
ベラルーシ語 | 0ｘ23 | ブルガリア語 | 0x02 | カタロニア語 | 0x03 | 中国語 | 0x04
クロアチア語 | 0x1a | チェコ語 | 0x05 | デンマーク語 | 0ｘ06 | オランダ語 | 0ｘ13
英語 | 0ｘ09 | エストニア語 | 0ｘ25 | フェロー語 | 0ｘ38 | ペルシア語 | 0ｘ29
フィンランド語 | 0ｘ0ｂ | フランス語 | 0ｘ0ｃ | ドイツ語 | 0ｘ07 | ギリシャ語 | 0ｘ08
ヘブライ語 | 0ｘ0ｄ | ハンガリー語 | 0x0e | アイスランド語 | 0ｘ0ｆ | インドネシア語 | 0ｘ21
イタリア語 | 0x10 | 日本語 | 0x11 | 韓国語 | 0ｘ12 | ラトヴィア語 | 0ｘ26
リトアニア語 | 0ｘ27 | マレー語 | 0x3e | ノルウェー語 | 0ｘ14 | ポーランド語 | 0ｘ15
ポルトガル語 | 0ｘ16 | ルーマニア語 | 0ｘ18 | ロシア語 | 0ｘ19 | セルビア語 | 0x1a
スロバキア語 | 0ｘ1ｂ | スロヴェニア語 | 0ｘ24 | スペイン語 | 0x0a | スワヒリ語 | 0ｘ41
スウェーデン語 | 0ｘ1ｄ | タイ語 | 0x1e | トルコ語 | 0x1f | ウクライナ語 | 0ｘ22

カラオケ ディスクの再生

カラオケ ディスクは DVD-Video ディスクの 一種であり、同じ操作構造を持っている。曲は一般にタイトルとしてフォーマットされ、タイトルは演奏者や音楽スタイルなどの条件に基づいてタイトル セットにグループ化できる。カラオケと他の種類の DVD-Video との主な違いはオーディオ ストリームである。すべてのカラオケ ディスクには、マルチチャンネル オーディオ (通常は Dolby AC-3) が含まれている。チャンネル 0 および 1 には常にバックグラウンドの演奏が含まれ、チャンネル 2 ～ 5 にはそれぞれガイド ボーカル、ガイド メロディ、サウンド エフェクトを含むことができる。カラオケ アプリケーションは、各補助チャンネルについてボリュームと出力先スピーカを制御できる。

カラオケの再生には、DVD ナビゲータから送信されるマルチチャンネル カラオケ ミキシング情報をサポートするデコーダも必要である。具体的に言えば、このデコーダは DVD カラオケ プロパティ セット (AM_KSPROPSETID_DvdKaraoke) をサポートする必要がある。

DVD ナビゲータはディスク上にカラオケ コンテンツを検出してカラオケ モードに入ると、デコーダにそれを通知し、デコーダはアプリケーションによって明示的にオンにされるまで上位 3 つのチャンネル (補助チャンネル) を無音状態にする。カラオケ アプリケーションの基本的な動作は次のとおりである。

  1. 補助チャンネル数とその内容を確認する。
  2. チャンネルの内容を表示してユーザーがいつでも任意の補助チャンネルをオンまたはオフにできるようにするユーザー インターフェイスを提供する。

DVD テキスト文字列の操作

DVD ディスク、特にカラオケ ディスクには、ビデオまたはオーディオ コンテンツを補足するテキスト情報のデータベースが含まれている場合がある。カラオケ ディスク上のそのようなテキストとしては、曲名、アーティスト名、レコード レーベルなどがある。このテキストは、複数の言語で存在することができる。このような文字列はオプションであり、ディスク上に必ず含めなければならないわけではない。文字列が含まれる場合は、DVD ボリュームの論理的な階層を厳密に反映するように構成される。各文字列の前には、その文字列がディスク構造のどの部分に属するかを識別し、文字列の内容の手がかりとなるような数字が付加される。

テキスト文字列には、基本的な型として構造識別子と内容文字列の 2 つがある。0x01 ～ 0x20 の値を持つ型が構造識別子である。これは空の文字列であり、数値コードはその後に続く内容文字列が属する論理構造を識別するために使用される。この構造は、DVD ディスクの内容 (ボリューム、タイトル、チャプターなど) の論理構造とかなり厳密に対応している。もう一方の型は、ユーザー インターフェイスで視聴者に表示される情報を保持する内容文字列を識別する。内容文字列の使用方法は厳密に定義されていないため、DVD 作成者はさまざまな方法でそれを使用できる。

これまで、DVD テキスト文字列はほとんどカラオケ ディスク専用に使用されてきた。これらのディスクは、ほとんどの場合、0x01 と 0x02 の構造識別子と 0x30 の内容文字列を使用している。しかし、時がたつにつれて、より多くの種類の DVD-Video ディスクにテキスト文字列が含まれるようになると考えるのが妥当である。これらの文字列は、より複雑に構成され、ディスクの内容の詳細な記述を提供するようになるであろう。

次のコードにより、ディスク上のテキスト文字列の言語ブロックの数を確認する方法、およびユーザーが言語を選択できるように表示するための人間が読める文字列を取得する方法を示す。このコードでは、文字列は "TextLanguageList" と呼ばれる HTML SELECT 要素に追加される。LCID およびプライマリ言語の詳細については、「GetLangFromLangID」を参照すること。

function GetTextLanguages()
  {
//テキスト ブロックの数を取得する。
var numLangs = DVD.GetDVDTextNumberOfLanguages();
      var iLCID;
      var iPrimaryLang;
      var sLanguage;
      var oOption;

    for (j = 0; j < numLangs; j++)
    {
//言語ブロックに対するロケール識別子を取得する
        iLCID = DVD.GetDVDTextLanguageLCID(j);

//LCID からプライマリ言語 ID を取得する
        iPrimaryLang = iLCID & 0x3FF;

//プライマリ言語 ID から、人間が読める文字列を取得する
        sLanguage = DVD.GetLangFromLangID(iPrimaryLang);

//HTML  ページ上の SELECT 要素に追加する
        oOption = document.createElement("OPTION");
        oOption.text = sLanguage;
        document.all.TextLanguageList.add(oOption);
    }

  } //関数 GetTextStrings の終わり

次のテスト コードは、文字列を列挙してテキスト文字列の型を検査する方法を示している。ここでは、数値文字列の型をどのように使用して内容文字列を編成するのかを理解する目的で、単に結果を "myTextArea" と呼ばれる HTML TEXTAREA 要素にダンプしている。実際のアプリケーションでは独自のデータ構造を作成して文字列を保持するか、または視聴者にとって便利な方法で文字列を表示する。

// iLanguage は、言語ブロックに対する 0 から始まるインデックスである
function GetTextStrings(iLanguage)
   {
    var numStrings, stringType, j;
    numStrings = DVD.GetDVDTextNumberOfStrings(iLanguage);

    for( j = 0; j < numStrings; j++)
          {
      stringType = DVD.GetDVDTextStringType(iLanguage, j);

      if(stringType > 0x20) //実際にはここで何らかのテキストを読み込む
          {
        myTextArea.value += (stringType + ": " + DVD.GetDVDTextString(iLanguage, j) + "\n");
          }
      else // ボリューム構造のレベルを示すノードである
            // 次の文字列を適用する
          {
            myTextArea.value += (stringType + "\n");
          }

        }
   } //関数 GetTextStrings の終わり

DVD テキスト文字列の型

次の表に、DVD テキスト文字列の型のサブセットの一覧を示す。値が 0x20 以下のすべての型は空の文字列であり、ディスクのコンテンツ データ構造におけるノード レベルを示すだけである。その他の文字列は、内容文字列である。ほとんどのタイトルおよび曲名の型は 0x30 である。Title、 SubTitle、および Original カテゴリ内の型によって、特定のジャンルを詳細に識別できる。これらのカテゴリの正確な意味と使用目的は公開文書に定義されており、DVD フォーラムの Web サイト (www.dvdforum.org) からダウンロードできる。

構造識別子
Volume | 0x01 | 後に続く文字列が DVD ボリュームに関係することを示す。
Title | 0x02 | 後に続く文字列が タイトルに関係することを示す。
ParentalID | 0x03 | 後に続く文字列が 特定のペアレンタル ID に関係することを示す。
Chapter | 0x04 | 後に続く文字列がチャプターに関係することを示す。
Cell | 0x05 | 後に続く文字列がセル (一般にムービーの 1 シーン) に関係することを示す。
ストリーム識別子
Audio | 0x10 | 後に続く文字列がオーディオストリームに関係することを示す。
Subpicture | 0x11 | 後に続く文字列がサブピクチャ ストリームに関係することを示す。
Angle | 0ｘ12 | 後に続く文字列がアングル ブロックに関係することを示す。
オーディオ チャンネル識別子
Channel | 0ｘ20 | 後に続く文字列がオーディオ ストリームの 1 つのチャンネルに関係することを示す。
一般的な内容文字列
Name | 0ｘ30 | タイトル名、チャプター名、曲名などに対する最も一般的な識別子。
Comments | 0ｘ31 | タイトル、チャプター、曲に関する一般的なコメント。
タイトル内容文字列
Series | 0ｘ38 | タイトル、チャプター、曲などに関する追加情報。
Movie | 0ｘ39 | ムービーの場合のタイトルまたはチャプターに関する追加情報。
Video | 0x3a | ビデオの場合のタイトルまたはチャプターに関する追加情報。
Album | 0x3b | アルバムの場合のタイトルまたはチャプターに関する追加情報。
Song | 0x3c | 曲の場合のタイトルまたはチャプターに関する追加情報。
Other | 0x3f | 他のジャンルまたはカテゴリーに属する場合のタイトルまたはチャプターに関する追加情報。
二次タイトル内容文字列
Series | 0ｘ40 | タイトル、チャプター、曲などに関する追加情報。
Movie | 0ｘ41 | ムービーの場合のタイトルまたはチャプターに関する追加情報。
Video | 0x42 | ビデオの場合のタイトルまたはチャプターに関する追加情報。
Album | 0x43 | アルバムの場合のタイトルまたはチャプターに関する追加情報。
Song | 0x44 | 曲の場合のタイトルまたはチャプターに関する追加情報。
Other | 0x45 | 他のジャンルまたはカテゴリーに属する場合のタイトルまたはチャプターに関する追加情報。
オリジナル内容文字列
Series | 0ｘ48 | タイトル、チャプター、曲などに関する追加情報。
Movie | 0ｘ49 | ムービーの場合のタイトルまたはチャプターに関する追加情報。
Video | 0x4a | ビデオの場合のタイトルまたはチャプターに関する追加情報。
Album | 0x4b | アルバムの場合のタイトルまたはチャプターに関する追加情報。
Song | 0x4c | 曲の場合のタイトルまたはチャプターに関する追加情報。
Other | 0x4f | 他のジャンルまたはカテゴリーに属する場合のタイトルまたはチャプターに関する追加情報。
その他の情報内容文字列
Other Scene | 0ｘ50 | ムービーのタイトルまたはチャプターにおける代わりのシーンに関する追加情報。
Other Cut | 0ｘ51 | ムービーのタイトルまたはチャプターにおける代わりのカットに関する追加情報。
Other Take | 0ｘ52 | ムービーのタイトルまたはチャプターにおける代わりのテイクに関する追加情報。


MSWebDVD ActiveX コントロール

以下のページには、Microsoft® MSWebDVD ActiveX® コントロールによって公開されるオブジェクトのメソッドとプロパティについて記述している。

オブジェクト | 目的
MSWebDVD | すべての DVD コマンドおよびクエリを制御する。
MSDVDAdm | Windows レジストリのデフォルト設定を制御する。
DVDRect | 各種の MSWebDVD メソッドで使用する矩形を定義する。

「MSWebDVD イベント」には、MSWebDVD ActiveX コントロールによってアプリケーションに送信されるイベント通知について記述している。


DirectShow の MPEG-2 サポート

この項では、Microsoft® DirectShow® を使って MPEG-2 コンテンツを再生するために使用可能なインターフェイスとコンポーネントについて説明する。MPEG-2 では、簡単なファイル再生が可能であり、各種の格納フォーマット (ディスクや取り外し可能なメディア) がサポートされ、オーサリングを必要としない。ソフトウェア デコーダは MPEG-2 に必ず対応しているが、古いハードウェア デコーダの一部には MPEG-2 に対応していないものがある。DVD ナビゲータと IDVDGraphBuilder コンポーネントおよびそのインターフェイスを使って DirectShow で DVD ベースのコンテンツを再生する方法については、「DVD アプリケーション」を参照すること。MPEG-2 の再生で使用されるインターフェイスは、IGraphBuilder と IMediaControl であり、DVD 固有の IDVDGraphBuilder と IDvdControl2 ではない。

MPEG-2 再生用に DirectShow が提供する最も重要なコンポーネントは、MPEG-2 スプリッタ フィルタである (DirectShow の以前のバージョンの MPEG-1 ストリーム スプリッタ コンポーネントに相当する)。DirectShow は MPEG-2 デコーダを提供しない。MPEG-2 スプリッタ フィルタは、MPEG-2 PES (Packetized Elementary Streams) を受け付ける DirectShow 互換の MPEG-2 オーディオ デコーダおよび MPEG-2 ビデオ デコーダと共に使用する必要がある。ユーザーは、DirectShow が認識する MPEG-2 プログラム ストリームのコンテンツが格納されたファイル (.mpg を推奨) をダブルクリックすることによって、MPEG-2 スプリッタ フィルタによるファイル再生をアクティブにできる。

詳細については、以下の関連トピックを参照すること。

  • MPEG-2 スプリッタ フィルタの使用
  • タイム スタンプ
  • MPEG サンプルのプロパティ
  • MPEG-2 カーネル メディア タイプ


MPEG-2 スプリッタ フィルタの使用

MPEG-2 スプリッタ フィルタは、現在、以下のストリーム タイプのうち少なくとも 1 つを含む MPEG-2 プログラム ストリームのプルモード再生をサポートする。

  • MPEG-2 ビデオ
  • MPEG-2 オーディオ
  • DVD-Video 定義によってエンコードされた Dolby AC-3 オーディオ
  • DVD-Video 定義によってエンコードされた LPCM (Linear Pulse Code Modulated) オーディオ

注 : MPEG-2 スプリッタは、トランスポート ストリームに対応していない。プッシュモードのみで出力された転送ストリームについては、MPEG-2 デマルチプレクサ を使用する。

MPEG オーディオの仕様の詳細については、 外部リンク http://www.mpeg.org/MPEG/DVD/Book_B/Audio.html を参照すること。

プログラム ストリーム内の個々のストリームを処理できる Microsoft® DirectShow® 互換のデコーダがインストールされている場合、MPEG-2 スプリッタ フィルタではこれらのタイプの再生がサポートされる。MPEG-2 スプリッタ フィルタでサポートされるメディア タイプの一覧については、「MPEG-2 スプリッタ フィルタ メディア タイプ」を参照すること。

MPEG-2 スプリッタ フィルタの使用の詳細については、以下のトピックを参照すること。

  • MPEG のタイム スタンプ
  • ストリームの選択
  • サポートされるインターフェイス

MPEG のタイム スタンプ

MPEG-2 プログラム ストリームを再生するとき、MPEG-2 スプリッタ フィルタは、最初に現れるシステム クロック参照を、ストリームの時間の原点として取り扱う。この動作は、プレゼンテーション時間スタンプを使用する MPEG-1 ストリーム スプリッタ フィルタとは異なる。IAMParse::GetParseTime メソッドは、処理したデータに対応するストリーム システム クロック タイムを返す (推定値の可能性がある) 。

MPEG-2 スプリッタ フィルタは、不連続性のプロパティが設定された入力サンプルがあった場合 (不連続性のプロパティは IMediaSample::SetDiscontinuity または IMediaSample2::SetProperties で設定できる)、データ内の最初のパックまでスキップし、そのパックのシステム クロック参照 (SCR) と不連続の前の SCR 時間が同じものと見なされるように、そのタイム スタンプを調整する。SCR クロックが前か後に 1 秒を超えてジャンプしている場合には、(MPEG-2 プログラム ストリームの仕様に従って) これも不連続なクロックとして扱われ、ダウンストリーム フィルタに渡るタイム スタンプから、明らかなクロック差が減算される。

ストリームの選択

MPEG-2 プログラム ストリームを再生するときには、プログラム ストリームを走査して最初に見つかったビデオ ストリームとオーディオ ストリームが選択される。オーディオ出力ピンとビデオ出力ピンが、それぞれ 1 つまでサポートされる。IAMStreamSelect インターフェイスを使用すると、同じタイプのストリームを複数 (システム ヘッダーにオーディオの上限として指定された数まで) 選択できる。MPEG-2 オーディオの場合、現時点では、ストリーム 0xC0 から始まる連続したストリームが想定されている。

サポートされるインターフェイス

MPEG-2 スプリッタ フィルタは、以下のインターフェイスをサポートする。

  • IAMParse—MPEG-2 プログラム ストリームのみ
  • IAMStreamSelect—MPEG-2 プログラム ストリームのみ、オーディオ ストリームのみ
  • IMediaSeeking—バイト モードのシークを含む


タイム スタンプ

タイム スタンプの詳細については、ISO1-11172: "The packet header may contain decoding and/or presentation time stamps (DTS and PTS) that refer to the first access unit in the packet" のセクション 2.4.1 を参照すること。

MPEG_Stream メジャー タイプの場合、開始タイムは、1 秒につき 1 バイトの割合で進行する最初のバイトのバイト位置である。終了タイムは最後のバイトのバイト位置である。したがって、連続するサンプルの間では、最初のパケットの終了タイムと次のパケットの開始タイムが一致しなければならない。Video CD データの場合、メディアの元データは、先頭に標準 RIFF チャンクを持つ、CDFS によって公開される Video-CD ファイルのフォーマットに従っていなければならない。

MPEG ビデオ パケット タイプおよびペイロード タイプの場合、タイム スタンプは、画像開始コードがサンプル内で始まる最初のビデオ フレームのプレゼンテーション時間である。

MPEG オーディオ パケット タイプおよびペイロード タイプの場合、タイム スタンプは、シンク コードがサンプル内で始まる最初のオーディオ フレームのプレゼンテーション時間である。

タイム スタンプのないパケットおよびペイロード データは、データを処理するフィルタによって問題なくプリロールされると想定されている。


MPEG サンプルのプロパティ

MPEG サンプルでは、次のプロパティまたは通知を使用する。

Time stamp | 一部のサンプルには開始タイムと終了タイムが設定されていない。パケットとペイロード データのサンプル終了タイムは、通常、開始タイム プラス 1 に設定されるが、これは役に立たない。MPEG パケットまたはペイロード データのサンプルでは、サンプルを生成したシステム レイヤ パケットが有効な PTS を持っていた場合にのみ開始タイムと終了タイムが設定される。
Discontinuity | たとえば、リアルタイム データのギャップやデータのエラーまたはシーク後のエラーにより、ストリームに途切れが生じると、Discontinuity プロパティが設定される。このプロパティは、受信されたサンプルに対してこのプロパティが設定された後、初めて送信されるサンプルを通じて MPEG-1 スプリッタからストリーム ハンドラに送信される。これにより、タイム スタンプの途切れが許容される。
End Of Stream | これはサンプルのプロパティではなく、独立した通知である。これを受信した場合は、すべてのバッファリングされたデータがデコーダを通過することを強制される。これにより、論理的には、すべての新しいデータが Discontinuity プロパティを持って開始することになる。


MPEG-2 カーネル メディア タイプ

MPEG-2 カーネル メディア タイプの GUID 名は、Microsoft® DirectShow® の GUID 名と異なる。次の表は、MPEG-2 に関連するタイプの DirectShow GUID とカーネル GUID を示している。

Ksuuids.h での名前 | Ksmedia.h での名前
MEDIATYPE_MPEG2_PES | KSDATAFORMAT_TYPE_MPEG2_PES
MEDIASUBTYPE_MPEG2_VIDEO | KSDATAFORMAT_SUBTYPE_MPEG2_VIDEO
FORMAT_MPEG2Video | KSDATAFORMAT_SPECIFIER_MPEG2_VIDEO
MEDIASUBTYPE_DOLBY_AC3 | KSDATAFORMAT_SUBTYPE_AC3_AUDIO
MEDIATYPE_Video | KSDATAFORMAT_TYPE_VIDEO
MEDIATYPE_Audio | KSDATAFORMAT_TYPE_AUDIO
FORMAT_WaveFormatEx | KSDATAFORMAT_SPECIFIER_WAVEFORMATEX
FORMAT_MPEG2Video | KSDATAFORMAT_SPECIFIER_MPEG2_VIDEO
MEDIASUBTYPE_MPEG2_AUDIO | KSDATAFORMAT_SUBTYPE_MPEG2_AUDIO
MEDIASUBTYPE_DVD_LPCM_AUDIO | KSDATAFORMAT_SUBTYPE_LPCM_AUDIO


Windows Media アプリケーション

Microsoft® DirectShow® を使用すると、Microsoft® Windows Media™ フォーマット ファイルを再生および作成するアプリケーションを作成できる。Windows Media フォーマットは、ネットワーク上でのデータのストリーミングおよびクライアント コンピュータ上でのデータのレンダリング用に最適化されている。Windows Media フォーマットの詳細については、Windows Media Format SDK を参照すること。

Windows Media Software Development Kit では、Windows Media フォーマット ファイルを作成する代替ソリューションを提供している。Windows Media SDK と DirectShow SDK の比較については、「Windows Media と DirectShow: Windows ベース メディア アプリケーションの選択肢」を参照すること。

ASF (Advanced Streaming Format) は、Windows Media フォーマットのファイル コンテナである。DirectShow ASF ライタ フィルタは、Windows Media フォーマット ファイルおよび WMF 以外のストリームを含む ASF ファイルを作成できる。「DirectShow での ASF ファイルの作成」を参照すること。


DirectShow での ASF ファイルの作成

ASF ファイル フォーマットおよび Windows Media Format

ここでは、Microsoft® DirectShow® の ASF ライタ フィルタを使って、ASF (Advanced Streaming Format) でファイルを作成する方法を解説する。 ASF は、任意の種類の圧縮データまたは非圧縮データを含むことができるファイル フォーマットである。AVI や WAV などのフォーマットに対する ASF の 1 つの利点は、ASF ファイルのデータにはタイム スタンプが付けられることである。Microsoft® Windows Media™ Format ファイルは、Windows Media Format Software Development Kit (SDK) で指定された特定の CODEC を使用する ASF ファイルである。これらのファイルでは、 Windows Media Audio ファイルの場合に "wma" という拡張子が使用され、Windows Media Video ファイルの場合に "wmv" という拡張子が使用される。Windows Media Format の詳細については、Windows Media Technologies ホーム ページを参照すること。

DirectShow SDK および Windows Media Format SDK

DirectShow および Windows Media Format SDK には、Windows Media Format のストリームを作成および再生するアプリケーションを書くための補足情報が与えられている。詳細については、http://www.microsoft.com/hwdev/vidcap/WM_DS.htm にあるホワイト ペーパーを読むこと。

ASF Writer フィルタは、任意の数の入力ストリームを受け付けて ASF ファイルを作成する。このフィルタは、Windows Media Format 仕様に従って ASF ファイルとしての保存を行うため、Windows Media Format SDK を使用して非圧縮オーディオ ファイルまたはビデオ ファイルを Windows Media Format に変換する。ほかの CODEC を使用したり、非圧縮データを ASF フォーマットで保存する場合は、フィルタの圧縮メカニズムをバイパスすることができる。

デジタル ビデオ (DV) キャプチャ、オーディオ再圧縮、ネットワーク ストリーミングの AVI (Audio-Video Interleaved) ファイル、MPEG マルチメディア ファイルの変換など、さまざまな状況で ASF Writer を使用できる。このフィルタによって、DirectShow® で Microsoft® Windows Media™ Audio (WMA) ファイルおよび Windows Media Video (WMV) ファイルを作成するための唯一の手段が提供される。このフィルタは、Digital Rights Management (DRM) によって保護されている Windows Media Format ファイルを作成することもできる。

ASF Writer フィルタは、Windows Media Format SDK と共にしか使用できない。このフィルタを使うアプリケーションを開発するには、開発マシンに Windows Media Format SDK をインストールしておく必要がある。この SDK をダウンロードすると、Microsoft から電子メールでソフトウェア証明書が送信される。この証明書によって、アプリケーションは SDK のロックを解除し、Digital Rights Management (DRM) を持たない任意の Windows Media Audio ファイルまたは Windows Media Video ファイルの読み書きができるようになる。この証明書がなければ、アプリケーションは ASF Writer をフィルタに追加することができない。DRM が有効になっているファイルを読み書きするには、Windows Media Technologies Web サイトで説明しているように、Microsoft から別の証明書を入手する必要がある。

このトピックは、以下のセクションで構成される。

  • ASF Writer の設定
  • グラフの構築
  • Windows Media Format SDK のロック解除

ASF Writer の設定

ASF Writer フィルタの作成時には、デフォルトのシステム プロファイルを使って自動的にフィルタが設定される。システム プロファイルの詳細については、Windows Media Format SDK で説明されている。基本的に、システム プロファイルには、ビット レート、ストリームの数とタイプ、圧縮品質など、Windows Media Format ファイルのさまざまな属性が記述される。デフォルトのプロファイルが適当でない場合、アプリケーションはフィルタの IConfigAsfWriter インターフェイスのメソッドを使って、プロファイルを変更できる。フィルタは、書き込む Windows Media Format ファイルの種類、設定する入力ピンの数、入力ピンが受け入れるメディア タイプなどのプロファイルを使って判定する。フィルタは、設定する前にグラフに追加し、アップストリーム フィルタに接続する前に設定しなければならない。

ASF Writer にプロファイルを指定する方法は、数多くある。ASF Writer は、システムで使用可能なプロファイルを一覧で示すプロパティ ページを持っている。この一覧には、指定された入力ストリームを基にフィルタで作成できるストリームの種類が示される。プロファイルの記述は、"250 Video—Creates video content for clients with 250 Kbps network connections, such as cable modems, DSL, and LAN connections" や、"128 CD Quality Audio—creates CD transparency quality audio content for clients with high-speed Internet and LAN connections. Also suited for local playback" などのように、ユーザーが読むことができる文字列で表示される。アプリケーションは、このプロパティ ページをエンド ユーザーに公開して、ユーザーがプロファイルを選択するようにできる。フィルタのプロパティ ページの表示方法については、「フィルタのプロパティ ページの表示」を参照すること。プロパティ ページを使用しない場合は、Windows Media Format SDK を使ってプロファイルの一覧を直接入手し、アプリケーションのユーザー インターフェイスを使ってエンド ユーザーに一覧を表示することができる。カスタム プロファイルを作成し、それを直接フィルタに渡すこともできる。また、Windows Media Format SDK のヘッダー ファイル Wmsysprf.h から、プロファイルのグローバル一意識別子 (GUID) をフィルタに渡すこともできる。

このフィルタでは、入力ピンの接続中にプロファイルを再設定することができるが、1 つの入力のオーディオ ストリームのプロファイルから、2 つの入力のオーディオおよびビデオ プロファイルに変わるなど、プロファイルが変更された場合は、前に接続されていたオーディオ ストリームだけが再接続される。

デフォルトでは、ASF Writer は圧縮されていないオーディオおよびビデオ ストリームを入力ピンで待ち、Windows Media Format SDK を使って圧縮を処理する。任意のデータ フォーマットを ASF に変換できるので、Windows Media Format SDK が適切な CODEC を持っていないデータ フォーマットを変換したい場合もある。ただし、その結果生成されるファイルは、完全に有効な ASF ファイルになるが、WMA または WMV ファイルとしては有効ではない。このような場合は、ASF Writer のアップストリームにあるフィルタ グラフでストリームを圧縮し、ASF Writer の圧縮メカニズムをバイパスする必要がある。そのためには、ASF Writer に接続されているアップストリーム出力ピンのメディア タイプが、現在の ASF Writer プロファイルで使用されている出力ストリームのフォーマットと完全に一致していなければならない。ASF Writer は、入力ストリームが設定済みのプロファイルとまったく同じであることを検出すると、それ以上の圧縮を試みないでデータを ASF に変換する。

IGraphBuilder::Connect メソッドの呼び出しによって、ソース フィルタとASF Writer の間にフィルタが自動的に挿入されると、ASF Writer は必ず内部で圧縮を行う。そのため、ASF Writer の圧縮メカニズムをバイパスするには、後で説明するようにグラフ全体を手動で作成しなければならない。

Windows Media Format SDK を使用するには、オーディオ ストリームが機能していなければならない。そのため、入力ピンがダミー ストリーム、つまり消音された低ビットレートのオーディオ ストリーム用のものであっても、ASF Writer は常にオーディオ入力ピンを持っていなければならない。また、すべての入力データにタイム スタンプがなければならず、フィルタを実行またはポーズする前に、すべての入力ピンが接続されていなければならない。

グラフの構築

ASF Writer を使ってフィルタ グラフを構築する方法は 2 とおりある。1 つ目の方法では、各フィルタを手動でグラフに追加し、ピンを接続する。ASF Writer を追加した後、デフォルトのプロファイルが適当でなければ、IConfigAsfWriter のメソッドを使ってプロファイルを設定し、ASF Writer の入力ピンをアップストリーム フィルタの対応する出力ピンに接続する。

2 つ目の方法では、ASF に変換するファイルの名前を指定して IGraphBuilder::RenderFile メソッドを呼び出す。RenderFile は、ファイルをレンダリングするための完全なグラフを自動的に構築する。その後、アプリケーションのコードで、手動でレンダリング フィルタを削除して ASF Writer を挿入する。これには、次の 5 つの基本ステップが含まれる。

  1. グラフに ASF Writer を追加する。
  2. レンダリング フィルタの接続を解除し、それらが接続されていた出力ピンを格納する。
  3. グラフからレンダリング フィルタを削除する。
  4. ASF Writer を設定する。
  5. IGraphBuilder::Connect を使って、ASF Writer の入力ピンを出力ピンに接続する。

次の図は、ASF Writer フィルタ グラフの代表的な設定を示す。

ASF Writer フィルタ グラフ

Windows Media Format SDK のロック解除

Windows Media Format SDK にアクセスするには、アプリケーションは実行時にソフトウェア証明書 (キーとも呼ばれる) を提供しなければならない。証明書の入手方法については、Windows Media Format SDK を参照すること。DirectShow アプリケーションは、フィルタ グラフに追加されるときに ASF Writer に証明書を提供する。アプリケーションは、Component Object Model (COM) の IServiceProvider および IObjectWithSite インターフェイスを使って、キー プロバイダとして登録しなければならない。この手法を用いて、アプリケーションは IServiceProvider から派生されたキー プロバイダ クラスを実装する。このクラスは、COM の 3 つの標準メソッドである AddRef、QueryInterface、および Release と共に、フィルタ グラフ マネージャから呼び出される追加メソッド QueryService を実装する。QueryService は、Windows Media Format SDK の WMCreateCertificate メソッドを呼び出し、作成した証明書へのポインタをフィルタ グラフ マネージャに返す。証明書が有効な場合、フィルタ グラフ マネージャはグラフの構築を進めることを許可する。

注 : アプリケーションを構築するには、WMCreateCertificate のプロトタイプ用に Wmsdkidl.h をインクルードし、Microsoft から受け取った Wmstub.lib にリンクする。

次のサンプル コードに、この処理の基本的な手順を示す。

// IServiceProvider から派生されるキー プロバイダ クラスを宣言して実装する。

class CKeyProvider : public IServiceProvider {
public:
    // IUnknown インターフェイス
    STDMETHODIMP QueryInterface(REFIID riid, void ** ppv);
    STDMETHODIMP_(ULONG) AddRef();
    STDMETHODIMP_(ULONG) Release();

    CKeyProvider();

    // IServiceProvider
    STDMETHODIMP QueryService(REFIID siid, REFIID riid, void **ppv);

private:
    ULONG m_cRef;
};

CKeyProvider::CKeyProvider() : m_cRef(0)
{
}

//////////////////////////////////////////////////////////////////////////
//
// IUnknown のメソッド
//
//////////////////////////////////////////////////////////////////////////

ULONG CKeyProvider::AddRef()
{
    return ++m_cRef;
}

ULONG CKeyProvider::Release()
{
    ASSERT(m_cRef > 0);

    m_cRef--;

    if (m_cRef == 0) {
        delete this;

        // オブジェクトはもう存在しないので、m_cRef は返さない。
        return((ULONG) 0);
    }

    return(m_cRef);
}

// IUnknown と IServiceProvider だけをサポートする。
HRESULT CKeyProvider::QueryInterface(REFIID riid, void ** ppv)
{
    if (riid == IID_IServiceProvider || riid == IID_IUnknown) {
        *ppv = (void *) static_cast<IServiceProvider *>(this);
        AddRef();
        return NOERROR;
    }

    return E_NOINTERFACE;
}

STDMETHODIMP CKeyProvider::QueryService(REFIID siid, REFIID riid, void **ppv)
{
    if (siid == __uuidof(IWMReader) && riid == IID_IUnknown) {
        IUnknown *punkCert;

        HRESULT hr = WMCreateCertificate(&punkCert);

        if (SUCCEEDED(hr)) {
            *ppv = (void *) punkCert;
        }

        return hr;
    }
    return E_NOINTERFACE;
}

////////////////////////////////////////////////////////////////////
//
// これらの例に、アプリケーションでのメソッド呼び出しの
// シーケンスを示す。簡単であるため、エラー チェックは省略した。
//
///////////////////////////////////////////////////////////////////

// フィルタ グラフ マネージャを作成するが、フィルタは追加しない。
IGraphBuilder *pGraph;
hr = CreateFilterGraph(&pGraph);

...

// キー プロバイダ クラスをインスタンス化し、COM が静的オブジェクトを
// 解放しないように AddRef の処理をする。

CKeyProvider prov;
prov.AddRef();  // COM に静的オブジェクトを解放させない。

// コールバックおよび QueryService 用に、IObjectWithSite ポインタをグラフに与える。
IObjectWithSite* pObjectWithSite = NULL;

hr = pGraph->QueryInterface(IID_IObjectWithSite, (void**)&pObjectWithSite);
if (SUCCEEDED(hr))
   {
// IObjectWithSite ポインタを使って、キー プロバイダ オブジェクトを指定する。
// フィルタ グラフ マネージャは、このポインタを使って QueryService を呼び出し、
// ロック解除を行う。
// ロック解除が成功したら、グラフを構築できる。

pObjectWithSite->SetSite((IUnknown *) (IServiceProvider *) &prov);
    pObjectWithSite->Release();
   }

// 「グラフの構築」で説明したように、グラフを構築する。


Microsoft TV テクノロジ

このセクションではアナログ TV アプリケーションとデジタル TV アプリケーションにおける Microsoft® DirectShow® の使用方法を説明する。アナログ セクションは ATI All-In-Wonder のような既存のアナログ チューニング カードをベースとしたアプリケーションの書き方を説明する。デジタル セクションでは Microsoft® Broadcast Driver Architecture (BDA) をサポートする新世代のデジタル / アナログ チューナー カードをベースとしたアプリケーションの書き方を説明する。

このセクションには次のトピックが含まれる :

  • アナログ TV アプリケーションを書く
  • デジタル TV アプリケーションを書く
  • Microsoft チューニング モデル
  • BDA デジタル TV リファレンス


アナログ TV アプリケーションを書く

このトピックは以下のセクションが含まれる :

  • アナログ TV ハードウェア デバイスのクラス
  • アナログ TV フィルタ グラフ
  • グラフの作成
  • VBI データのキャプチャリング
  • アナログ TV チューニング

アナログ TV フィルタ グラフはアナログ TV チューナー キャプチャ カードをベースにしている。通常 1 枚のカードに複数のデバイスが含まれる : チューナー、信号をルーティングするゼロ以上のクロスバー、アナログ-デジタル コンバータ (アナログ ビデオ デコーダとも呼ばれる)、そして TV オーディオが別のデバイスの場合もある。カードのそれぞれのデバイスの Microsoft® Windows® Driver Model (WDM) デバイス ドライバは製作者あるいは他のサードパーティから提供される。これらのドライバは Microsoft から提供されるフィルタやプラグインといっしょに働き、フィルタグラフに参加する事ができる。Microsoft が提供するコンポーネントは TV チューナー フィルタ、TV オーディオ フィルタ、アナログ ビデオ クロスバー フィルタ、そして WDM ビデオ キャプチャ プラグインである。GraphEdit で、これらのフィルタは "WM Streaming" カテゴリに現れる、フィルタのフレンドリ名はドライバによって変わる。アプリケーションは System Device Enumerator を使ってそれらのフィルタを発見する。それらのデバイスをプログラム上で発見する方法の詳細は、デバイスとフィルタの列挙 を参照すること。DirectShow でハードウェア デバイスの使用についての一般的な情報は、ハードウェア デバイスがフィル タグラフに参加する方法」を参照すること。

上記のデバイスフィルタについては更に、アナログ TV フィルタ グラフは DirectShow の一部として Microsoft が提供する (KsProxy ベースの) カーネル モード フィルタとユーザーモード フィルタをも含む。これらのフィルタは Tee/Sink-to-Sink コンバータ、VBI サーフェイス アロケータ、CC デコーダ、Line 21 デコーダ、オーバーレイ ミキサー、ビデオ レンダリングなどである。これらのフィルタの詳細は後のセクションで説明される。

アナログ TV ハードウェア デバイスのクラス

アナログ TV フィルタ グラフ作成のコンテキストには、2 つの基本的なアナログ キャプチャ カードのクラスがある : (1) ビデオ データを直接ビデオ メモリに送るもの、これはビデオポートを呼び出し直接ハードウェアと接続する、そして (2) ビデオ データを PCI バス、あるいは USB や IEEE 1394 接続を通してまずホストのメモリに送り、それからグラフィックス カードに送るもの。

アプリケーションから見ると、フィルタグラフ内でビデオポート デバイスと PCI/USB/1394 デバイスという 2 つの基本的な違いがある :

  1. ビデオポート デバイスをベースとしたグラフは別のフィルタ VBI サーフェイス アロケータを必要とする。このフィルタは VBI ビットマップ用にビデオ グラフィックス アダプタに別のビデオメモリ割り当てを必要とする。キャプチャ フィルタで VPVBI 出力ピンと接続する。PCI デバイスではオーバーレイ ミキサーがこのメモリを割り当て、VBI サーフェイス アロケータは不要である。
  2. ビデオポート デバイスをベースとしたグラフは Bt829 キャプチャ フィルタを使い、PCI (と 1394/USB) デバイスをベースとしたグラフは Bt848 キャプチャ グラフを使う。Bt848 フィルタは VBI サーフェイス アロケータを使わない。

    アナログ TV フィルタ グラフ

    次の図は ATI All-In-Wonder カードをベースとしたアナログ TV フィルタ グラフを示す。このグラフはビデオ、オーディオ、クローズドキャプション テキストをレンダリングし、ビデオとオーディオを非圧縮 AVI ファイルにキャプチャもする。(このフィルタ グラフは少し複雑だが、キャプチャ グラフ ビルダと数行のコードだけで作成できる。グラフの作成はこのセクションの終りで説明する。)

    ATI All-In-Wonder フィルタ グラフ

    TV チューナー: 実際には何のデータも通らないが、このフィルタは必ずグラフの最初のフィルタとなる。アプリケーションはその IAMTVTuner インターフェイスを使って、チャンネルから周波数へのマッピングをセットしチャンネル選択を行う、またハードウェアがサポートするビデオ規格の情報を取得する。

    アナログ ビデオ クロスバー: クロスバー フィルタはルーティング デバイスであり、それを使ってアプリケーションはハードウェアの入力信号を正しいデータパスに設定する。これフィルタは IAMCrossbar インターフェイスをサポートする。このフィルタの入力ピンはアンテナ、ケーブル、または(VTR のような) AUX ラインからの物理的な入力を表わす。どの入力信号も 1 つ以上の出力ピンにルーティングされ得る。前述の ATI グラフは 2 つのクロスバー フィルタを持っている。アップストリーム クロスバーは外部入力用で、2 つ目は (AD コンバータとも言われる) ハードウェア ビデオ デコーダへの複数入力用である、これはグラフ内のキャプチャ フィルタによって表現されている。別のカードは別のクロスバー構成を持つ場合がある。

    ビデオ キャプチャ フィルタ: このカーネル モード フィルタはハードウェア上の AD コンバータを表現する。それはビデオ信号を実際に処理する最初のフィルタである。Microsoft はビデオポートデバイスに使用される Brooktee 829 キャプチャ チップをサポートするドライバを提供し、IHV は Brooktree 848, 878 あるいは他のビデオチップ用のドライバを提供する。すべてのこれらのドライバは WDM ビデオ キャプチャ プラグインを使って、プロパティ ページを提供し、その COM インターフェイスを公開する。そのドライバとプラグインはアプリケーションには 1 つの「フィルタ」として現れる。アプリケーションはこのフィルタの IAMAnalogVideoDecoder インターフェイスを使って、サポートされているアナログ ビデオ フォーマット、水平同期の状態、出力バスを取得あるいは設定する。キャプチャ フィルタは出力として 2 つの別のビデオ ストリームを作成することができる、片方はレンダリング用、もう片方はキャプチャ用である。(VP あるいは ビデオポートという名の) レンダリング ピンは必ずオーバーレイ ミキサーの入力ピン ゼロに接続する。「オーバーレイ ミキサー フィルタ」にはビデオ ポート接続についての詳細情報が記述されている。

    キャプチャ フィルタは VBI データを異なるピンに出力する、あるカードは ロー VBI データを出力し、あるカードはハードウェア内で VBI デコードを行う。すべての Microsoft VBI フィルタは現在ロー データとデコード データの両方をサポートする。All-In-Wonder カードはビデオポートを持つので、Bt829 フィルタが使われる、それは VBI サーフェイス アロケータへの出力ピンを持ち、Line 21 デコーダが提供する CC オーバーレイ用にビデオ メモリを正しく構成する。このフィルタはオーバーレイ ミキサー上で入力ピン 1 以上のものと接続する。

    AVI デコンプレッサ: AVI デコンプレッサ フィルタはビデオ圧縮マネージャ CODEC のラッパー フィルタである。アナログ TV キャプチャ グラフでは、それは AVI マルチプレクサに送る前にビデオ ストリームを UYVY から RGB に変換する MSYUV カラー コンバータをラップする。

    オーディオ キャプチャ: オーディオ キャプチャ フィルタはクロスバーのオーディオ デコーダ出力ピンからデジタル化されたオーディオを受け取る。このピンは実際にはサウンド カードの内部入力を表現する、それは CD ドライブだけではなくホスト システムの内部ソースの場合もある。オーディオ キャプチャ フィルタの他の入力ピンは通常マイクロフォン、テーププレーヤーなどのような外部デバイスからのアナログ入力を表す。正確なピンの構成と名前はサウンドカードによって異なる。前述したグラフでは、オーディオ キャプチャ フィルタはオーディオ データを AVI Mux フィルタに出力する。

    このグラフにはオーディオ レンダリング フィルタ が含まれていないことに注意すること、このフィルタは TV カードが外部ケーブルでサウンドカードに (あるいはドングルでサウンドカードの入力ジャックに) 接続されているときは必要がない。このケーブルが使われていないなら、前述のようにグラフはスマート ティー フィルタを使い、オーディオ キャプチャ フィルタ ダウンストリームから AVI Mux への出力と同じようにデフォルト DirectSound デバイスにオーディオを出力する。

    Tee/Sink-to-Sink コンバータ: このフィルタはキャプチャ フィルタから VBI 情報を取得し、信号の各データサービスに対応して別のストリームに分割する。Microsoft は VBI CODEC をクローズド キャプション、NABTS、World Standard Teletext (WST) に対して提供する。上述のグラフではキャプチャについてのサービスはクローズド キャプションだけである。

    CC デコーダ: CC VBI デコーダはカーネル モード ストリーム クラス フィルタである。8 つまでの出力ピンを持ち、各ピンはそれ自身のラインとサブストリームを選択可能である。その仕事はキャプチャ された VBI ラインを処理し、CC データを Line 21 デコーダや他のアプリケーションに出力することである。最初の出力ピンは Line 21 デコーダに接続される。

    Line 21 デコーダ: Line 21 デコーダは CC デコーダからでコードされたクローズドキャプション データを取得し、ビデオ矩形にオーバーレイされるビットマップを生成する。次にこのデータはオーバーレイ ミキサーに渡される。

    NABTS/FEC VBI CODEC フィルタ (図にはない): NABTS/FEC VBI CODEC は ring-0 ストリームクラス フィルタである。それは VBI と HWNABTS という 2 つの入力ピンを持つ。8 つまでの出力ピンを持ち、各ピンは自身の VBI スキャンラインとサブストリームを選択することができる。その仕事はキャプチャされた VBI ラインを処理し、デコードされたあるいはフォワード エラーが付いた NABTS データを BDA SLIP デフレーマ フィルタに出力し、次に WinSock 経由でアプリケーションから利用可能な IP データを作成する BDA IP シンクに送ることである。

    WST CODEC と WST デコーダ フィルタ (図にはない): これらのフィルタは ring-0 ストリーム クラス フィルタであり、PAL システムの teletext データを処理する。WST CODEC は ロー VBI データを受け取る 1 つの入力ピンを持つ。それは 8 つまでの出力ピンを持ち、各ピンは自身のラインとサブストリームを選択できる。その仕事はキャプチャされた VBI ラインを処理し、デコードされた teletext データをアプリケーションに出力する事である。最初の出力ピンは WST デコーダに接続され、クローズドキャプション データで Line 21 デコーダが行うのと同じようにハードウェアオーバーレイのビットマップを作成する。

    オーバーレイ ミキサー: この DirectShow フィルタはシステムのビデオメモリで実際のビデオのレンダリングを行う。それはビデオ ポート タイプと 非ビデオ ポート タイプ両方のハードウェアで使われる。

    ビデオ レンダラ: オーバーレイ ミキサーを使ってビデオをレンダリングするすべてのグラフでは、ビデオ レンダラは単なるウィンドウ マネージャとして働き、オーバーレイ ミキサーにビデオ矩形をスクリーンのどこに置くかを指示する。

    グラフの作成

    アナログ TV グラフは単に 1 つのタイプの WDM ビデオ キャプチャ グラフである。キャプチャ グラフ ビルダを使って作成し得る、これは「キャプチャ アプリケーションの書き方」で説明され、AMCap サンプル アプリケーションでデモンストレーションされている。AMCap でデモされているように、基本原理はキャプチャ フィルタで始め、次にレンダリングあるいはキャプチャしようとする各入力ピンに対してダウンストリーム フィルタを追加する。アップストリーム フィルタは最後についたする。AMCap はクローズドキャプション データをレンダリングする CC デコーダと Line 21 デコーダ フィルタに引き込む方法を示すが、NABTS や teltetex データのキャプチャリングのために他の VBI 関連フィルタに引き込む方法はデモされていない。

    VBI データのキャプチャリング

    DirectShow はアナログ TV 放送信号の垂直同期間隔 (VBI) から NABTS と (PAL用の) World Standard Teletext (WST) をキャプチャリングするカーネルモード フィルタを提供する。これらのフィルタは GraphEdit 内で WDM ストリーミング VBI CODEC カテゴリの下に表示される。キャプチャ フィルタはロー VBI データを Tee/Sink-to-Sink コンバータに送る 1 つの出力ピンを持ち、それは NABTS IP データ、Line 21 クローズドキャプション、tetetext 情報の信号内にあるデータを調べ、各データタイプの出力ピンを作成する。クローズドキャプションや teletext データをデコードするためのフィルタを追加するには、MSTee フィルタの適切な出力ピンで ICaptureGraphBuilder2::RenderStream メソッドを使うこと。前述の図では CC データのキャプチャリングとレンダリング用のフィルタを示しており、AMCap サンプルはクローズドキャプション データをグラフに追加する方法をデモしている。(Web ページや Web イメージを含むインタラクティブ TV 拡張のような) NABTS IP データに対しては、ビデオ キャプチャ フィルタからフィルタ ダウンストリームのチェーンを手動で追加、接続しなければならない。VBI データを 2 つのストリームに分割するには Tee/Sink-to-Sink コンバータ フィルタの追加に注意すること。

    NABTS とクローズドキャプション フィルタ グラフ セグメント

    これらのカーネルモード フィルタ上にはアプリケーションから呼び出し可能なインターフェイスはない。それらは SLIP エンコードされた IP パケットを VBI 信号から抽出し、それを Winsock に渡すデータ パイプラインとしてのみ機能する。

    teletext データについては、フィルタは次の図で示されている。

    世界標準 Teletext フィルタ グラフ セグメント

    NABTS、teletext、CC デコーディング をハードウェアで処理するキャプチャデバイスもある。この場合、キャプチャ フィルタは特殊な出力ピンを公開し、ダウンストリーム デコーダはそのデータを修正せずに渡すだけである。アプリケーション開発者には特殊なプログラミングは必要ない。

    VBI の Line 21 にはクローズドキャプション テキストだけではなく、現在の放送と連携した Web ページの URL も含まれている。これは ATVEF 規格の "Transport B" として記述されている。

    アナログ TV チューニング

    TV チューナーをコントロールするときの基本的な処理順は以下のとおりである :

    1. 必要なら、アナログ ビデオ クロスバー フィルタで IAMCrossbar インターフェイスを使って、チューナーからビデオ デジタイザ (キャプチャ フィルタ) へのクロスバー経由のビデオパスを構築する。
    2. IAMTuner::put_Mode メソッドを呼び出し、受信放送タイプ (TV、AM オーディオ、FM オーディオなど) のチューナー カードをセット
    3. IAMTuner::put_CountryCode で国コードをセットして、正しい TV チャンネル-周波数マッピングを構築する。国コードの詳細については、「国際アナログ テレビのチューニング」を参照すること。
    4. チューナーの各入力に対して、IAMTVTuner::put_InputType を呼び出し、ケーブルかアンテナの入力タイプを設定する。IAMTVTuner::put_ConnectInput を使って、利用可能なチューナー入力の 1 つを選択する。
    5. IAMTVTuner::get_TVFormat を呼び出し、現在のビデオフォーマットを取得し、次にこの値を使って IAMAnalogVideoDecoder::put_TVFormat を呼び出しキャプチャ フィルタを設定する。
    6. IAMTuner::put_Channel を呼び出し、視聴を開始する。


デジタル TV アプリケーションを書く

Microsoft® DirectX® 8.0 SDK と Microsoft® Broadcast Driver Architecture (BDA) と互換のデジタル TV チューナー カードがあれば、デジタル TV 放送をパーソナル コンピュータで視聴するアプリケーションを作成することができる。PC 上でデジタル TV をサポートするための Microsoft のアーキテクチャは次のコンポーネントに分けられる :

  • Broadcast Driver Architecture
    • チューニングと復調
    • デマルチプレクス
    • デジタル TV 規格サポート (DVB, ATSC)
    • 条件付アクセス (Microsoft® Windows® オペレーティング システムの将来のバージョンでリリースされる)
    • 電子番組ガイド (Microsoft Windows オペレーティング システムの将来のバージョンでリリースされる)
    • MSTV ガイド ストア (Microsoft Windows オペレーティング システムの将来のバージョンでリリースされる)
    • ATVEF (Microsoft Windows オペレーティング システムの将来のバージョンでリリースされる)
  • チューニング モデル
    • チューニング モデルは様々なネットワークタイプに対するチューニングの複雑さをカプセル化する一連のオブジェクトである。チューニング モデルを使うと、アプリケーションは単純な単一の方法で利用可能な周波数やチャンネルをチューンすることができる。
  • ビデオ コントロール アーキテクチャ
    • ビデオ コントロールは TV や DVD アプリケーションに対するスクリプティング API を提供する ActiveX® コントロールである。それは TV や DVD フィーチャーのアプリケーションへの統合を著しく単純化する。(Microsoft Windows オペレーティング システムの将来のバージョンでリリースされる)

DirectX 8.0 には基本的なデジタル TV フィルタ グラフの作成、ATSC (アンテナあるいはケーブル) や DVB-S 放送への接続、グラフのチューンとサブストリームの選択、(電子番組ガイドのような) ロー PSI データのキャプチャとスクリーンへのビデオのレンダリングをするために必要なすべてのフィルタとコンポーネントが含まれている。

DirectX 8.0 には PSI ストリームから EPG データを抽出する MSTV ガイド ストアや、インタラクティブ TV 用の Web ページや Web イメージのような ATVEF 拡張をレンダリングするコンポーネントは含まれていない。DirectX 8.0 はまたビデオ コントロールをも提供しない、つまりアプリケーションがフィルタ グラフを作成するには自分自身でコードを実装しなければならない。

このトピックには次のセクションが含まれる :

  • デジタル TV フィルタ グラフ
  • フィルタ グラフの作成

デジタル TV フィルタ グラフ

次の図は地上波 ATSC 放送を受け取るために構成された基本的なデジタル TV フィルタ グラフを示す。チューナー、キャプチャ、MPRG-2 デコーダ フィルタの実際のフィルタ名やピン名はビデオに依存して変わる。

一般的な BDA デジタル TV フィルタ グラフ

ネットワーク プロバイダ: BDA ネットワーク プロバイダ フィルタは必ずグラフ内の最初のフィルタとなる。このグラフは ATSC ネットワーク プロバイダを持っている。Microsoft はまた DVB ネットワーク チューニングを提供する DVB ネットワーク プロバイダをも提供する。サードーパーティは自分自身のネットワーク プロバイダを持ち、自分自身の放送をカスタマイズする。ネットワーク プロバイダは、コンテンツ多重、変調、放送規格を含む、個々のチューニング空間でダウンストリーム フィルタを構成する。このフィルタは ITuner インターフェイスを実装し、アプリケーションはそれを使って指定したチャンネルや周波数にデバイスをチューニングする。

デジタル TV チューナー: このカーネルモードで KsProxy ベースのフィルタはハードウェア デバイス上のチューナーを表現する。アプリケーションから呼び出し可能なインターフェイスがある場合とない場合がある、それはサードパーティ のドライバの実装に依存している。BDASample アプリケーションでは、チューナー フィルタは ITuner をサポートするようには仮定されていない、それゆえチューニングはチューナー フィルタと内部的にコミュニケーションするネットワーク プロバイダを通して行われる。

デジタル TV キャプチャ フィルタ: このカーネルモードで KsProxy ベースのフィルタはハードウェア デバイス上での復調/デジタル化を表す。その 1 つの出力ピンは MPEG-2 トランスポート ストリームを MPEG-2 デマルチプレクサに出力する。

MPEG-2 デマルチプレクサ: デジタル TV グラフでは、MPEG-2 デマルチプレクサは MPEG-2 トランスポート ストリームをキャプチャ フィルタから受け取り、ストリームをデマルチプレクスする。通常 4 つの出力ピンを持つ。最初の出力ピンはロー プログラム サービス 情報 (PSI) パケットをトランスポート情報フィルタに出力する。2 つ目のピンはビデオ ストリームを MPEG-2 デコーダに出力する。3 番目のピンはオーディオをオーディオ デコーダに出力し、4 番面のピンはインタラクティブ TV 拡張のようなデータを出力する。

トランスポート情報フィルタ: 受信者が指定した番組に関するすべての基本ストリームを正しく受け取るために、また受信者がどの番組がストリームに含まれているのかを話せるために、トランスポート ストリームはトランスポート ストリーム内に含まれるカタログ情報として働く多くのテーブルのセットを持つ。ネットワーク プロバイダの方向に、MPEG-2 デマルチプレクサはトランスポート情報フィルタへ出力するテーブルを出力する、それらのテーブルをパースし、ネットワーク プロバイダへの情報を提供し、グラフ内の他の受信フィルタとノードをコントロールできるようになる。

HDTV 性能 MPEG-2 デコーダ: デジタル TV フィルタ グラフは高解像度 TV ビデオ ストリームの性能を持つサードパーティのデコーダが必要である。オーディオとビデオ両方のストリームを同じフィルタで操作するデコーダ実装もあるし、オーディオとビデオ別のフィルタを持つデコーダもある。

オーバーレイ ミキサー: この Microsoft® DirectShow® フィルタは実際にはビデオのレンダリングをシステムのビデオメモリに行う。

ビデオ レンダラ: ビデオのレンダリングにオーバーレイ ミキサーを使うすべてのグラフでは、ビデオ レンダラは単なるウィンドウ マネージャとして働き、オーバーレイ ミキサーにビデオ矩形をスクリーンのどこに置くかを伝える。

BDA MPE フィルタ: このフィルタはマルチ プロトコル カプセル化 (MPE) ストリームから IP パケットを抽出し、IP Sink にそれを出力する。

BDA IP シンク: このフィルタは IP パケットを受け取り、Winsock 経由でホスト システムにそれを出力する、アプリケーションはそれを受け取り、インタラクティブ TV 拡張のような IP データ ストリームを受信する。

フィルタ グラフの作成

DirectX 8.0 では、アプリケーションはデジタル TV グラフを手動で作成し、各フィルタの追加や接続をしなければならない。キャプチャ グラフ ビルダは使えない。サンプル アプリケーション BDASample が SDK に含まれている。これはこのセクションの後半で概説するステップに従って、基本的なデジタル TV フィルタ グラフの作成方法をデモンストレーションする。

次のセクションはおおむねランタイム時に行われる典型的なシーケンスの順に並んでいる。チューン リクエストが ITuner::put_TuneRequest メソッドでネットワーク プロバイダに送られた後で フィルタ グラフの作成を行うことに注意すること。なぜならチューン リクエストにはネットワーク タイプと、どのフィルタをグラフに読み込むかを決める他の詳細情報が含まれているからである。グラフはネットワーク プロバイダがこの情報をもつまで作成されない。チューニング空間、チューン リクエスト、関連オブジェクトの詳細については、「Microsoft® チューニング モデル」を参照すること。

チューニング空間の取得

DirectX 8 では、Broadcast Driver Architecture がローカル アナログ ケーブルとアンテナ、ローカル ATSC アンテナとケーブル、DVB-S に対するデフォルトのチューニング空間を提供する。アプリケーションにデジタル ケーブル サポートを実装するには、デジタル ケーブル チューニング空間を必要な値でオーバーライトし、必要ならデフォルト ロケータも提供すること。国際チューニングやデジタル衛星放送をサポートするには、自身のチューニング空間を作成する必要がある。DVB チューニング空間では、アプリケーションはユーザーインタフェイスを提供しなければならない、ユーザーはそれを使ってどのデジタル TV サービスを購読するかを指定することができる。

チューニング空間を取得するには、アプリケーションは SystemTuningSpaces オブジェクトのインスタンスを作成し、ITuningSpaceContainer::get_EnumTuningSpaces メソッドを使ってチューニング空間のリストを取得する、そのリストからチューニング空間を 1 つ選択する。この手順は BDASample アプリケーションの LoadTuningSpace メソッドでデモンストレーションされている。

Microsoft チューニング モデルはアナログ チューニング空間をサポートするために設計されたが、DirectX 8.0 には BDA フィルタ グラフ内でのアナログ TV チューニングの完全なサポートは含まれていない。このサポートは DirectX と Microsoft® Windows® の将来のリリースで追加される。一方アナログ TV グラフは DirectShow がアナログ TV キャプチャでこれまで使ってきたものと同じタイプのフィルタ グラフでサポートされる。DirectX 8.0 では、デジタル ネットワーク タイプだけが BDA フィルタ グラフでサポートされる。これは次のようなことを意味している、たとえば、デジタルとアナログ両方のチューニングをサポートするアプリケーションを書こうとすると、そのアプリケーションは 2 つの別のフィルタ グラフを作成する必要があり、ユーザーがアナログ TV チャンネルを選択したときはアナログ グラフを使い、ユーザーがデジタル チャンネルや周波数を選択したときは BDA グラフを使う。Microsoft Windows の将来のリリースでは、グラフ作成プロセスを完全に扱う Automation 互換のビデオ コントロールと共に、アナログ TV とデジタル TV とラジオ チューニング空間がすべて提供される。

チューン リクエストとネットワーク プロバイダへのサブミット

アプリケーションはチューン リクエストを直接には作成しない。その代わり、アプリケーションはITuningSpace::CreateTuneRequest メソッドを呼び出し、それは空の初期化されていないチューン リクエストを返す。次にアプリケーションは特定のインターフェイスに対応したオブジェクトの標準 COM メソッド QueryInterface を呼び出す、そのインターフェイスは IATSCChannelTuneRequest のような ITuneRequest から派生したインターフェイスである。次にアプリケーションは返されたインターフェイスを使ってチューン リクエストを構成し、それを処理し、ネットワーク プロバイダにサブミットすることができる。一般「ネットワーク プロバイダ」のようなものは実際に存在しない事を理解することは重要である、そうではなく「ATSC ネットワーク プロバイダ」や「DVB ネットワーク プロバイダ」が存在するのである。作成された個別のオブジェクトはチューニング空間オブジェクトから取得したネットワーク CLSID をベースにしている。

ネットワーク プロバイダがグラフに追加された後で、QueryInterface メソッドを使ってその ITuner インターフェイスを取得する。次に ITuner::put_TuneRequest メソッドを使ってチューン リクエストをネットワーク プロバイダに渡す。この手順はBDASample の graph.cpp の LoadNetworkProvider 関数でデモンストレーションされている。

残りのフィルタの追加と接続

ネットワーク プロバイダがチューン リクエストで構成されると、1 つ 1 つ各フィルタを追加接続することで、残りのフィルタをグラフに追加できる。BDASample アプリケーションの graph.cpp の BuildGraph と LoadAVSegment と LoadIPSegment 関数を見ること。

デフォルト優先コンポーネント タイプの定義

注 この手順は BDASample に実装されていない。

「コンポーネント」はプログラム サブストリームを参照する。デフォルト優先コンポーネント タイプは、ユーザーがデフォルトでアクティブにしたがるようなタイプのサブストリームである。たとえば、スペイン語オーディオ ストリームが利用可能なときはいつもプレイされるべきだ、とあるユーザーは指定するかも知れない。アプリケーションは空の Components コレクション オブジェクトをインスタンス化し、それに書き込むことによって優先コンポーネント セットを作成する。次にアプリケーションはそのコンポーネント オブジェクトを処理しチューナーにサブミットする、するとチューナーは利用可能なサブストリームに変更があると必ずそれをチェックする。

サブストリームの選択

注 この手順は BDASample に実装されていない。

> どのサブストリームをアクティブにするかあるいは非アクティブにするを指定するには、アプリケーションは最初にチューン リクエストをチューナーにサブミットしなければならない。チューナーが指定したチャンネルや周波数をチューンすると、チューナーはチューン リクエスト内のコンポーネント コレクションに各サブストリームがアクティブあるいは非アクティブかの情報を書き込む。次にアプリケーションはこのコレクション内の各コンポーネントを調査し、IComponent::put_Status メソッドを使って個々のサブストリームをアクティブあるいは非アクティブにすることができる。

デジタル チューニング

最初のチューンリクエストがサブミットされた後で、次のチューニングは新しいチューン リクエストをネットワーク プロバイダにサブミットすることによって行われる、これは BDASample の graph.cpp の ChannelChange メソッドでデモンストレーションされている。


Microsoft チューニング モデル

概要

デジタル レシーバのチューニング プロセスはネットワーク タイプによって異なるパラメータ セットが必要となる。チューニング モデルの目的は、これらの違いをオブジェクトとそのオブジェクトを操作するプロシージャの標準セットでカプセル化し、アプリケーションを細かい低レベルのチューニング マネージメントから解放することである。アプリケーションが DVB-S プロバイダからの番組をチューニングしようが、ローカル アナログ放送から来る番組をチューニングしようが、基本的な手順は同じである。この手順はまたその下にあるハードウェアにも依存しない。チューニング モデルのすべてのオブジェクトは標準 COM インターフェイス IPersistPropertyBag をサポートし、ストレージ メカニズムのソートが可能である。

Microsoft® DirectX® 8.0 ベースのアプリケーションは Microsoft チューニング モデルのメリットを十分には受けることができない事への注意は重要だ、なぜなら DirectX 8.0 は標準化されたガイド ストアとチューニング空間を理解するガイド ストア ローダを提供しないからだ。DirectX と Microsoft® Windows® の将来のリリースではこれらのコンポーネントが含まれる予定である。ガイド ストア ローダはトランスポート情報フィルタ上の番組サービス情報 (PSI) ストリームをモニターし、チューニング空間の利用可能なすべてのチャンネルや周波数に対してチューン リクエストを自動的に作成し、ガイド ストア データベースに保存する。これらのコンポーネントで、すべてのアプリケーションが行わねばならないことは、利用可能なチャンネルを見せるユーザー インタフェイスを作成し、ユーザーが選択したとき、ネットワーク プロバイダに準備前のチューン リクエストをサブミットすることである。しかし DirectX 8.0 では、アプリケーションはチューン リクエストの作成が必要となる (それにはチューン リクエストの意味を知らなければならない)。別の方法は、自分自身のガイド ストア ローダとガイド ストアを書くことである。

チューニング モデル オブジェクト

チューニング オブジェクトの 2 つの基本オブジェクトは チューニング空間 と チューン リクエスト である。チューニング空間はプロバイダと送信ソースを記述する、たとえば、ローカル ケーブル サービスやデジタル衛星ネットワークなど。アプリケーションはチューニング空間コンテナを使ってローカル システム上で利用可能なチューニング空間を列挙し、次にチューニング空間を使ってチューン リクエストを作成する。アプリケーションはネットワーク プロバイダにチューン リクエストをサブミットする、それはグラフ内のソース フィルタである。ネットワーク プロバイダは必要な情報をチューン リクエストから抽出し、その情報をカーネルモード ドライバに送る。次の図はアプリケーションとチューニング モデル オブジェクトと、BDA フィルタ グラフと、カーネル モード ドライバ間の上位レベルの関係を示している。

チューニング空間とチューン リクエスト

チューニング空間は個別のネットワーク プロバイダを記述する。チューニング空間の例には、EchoStar®、DirecTV®、アンテナ経由のローカル アナログ放送、ローカル アナログ ケーブル、アンテナ経由のローカル デジタル放送が含まれる。チューニング空間情報にはネットワーク タイプの情報が含まれる、たとえば地上波アナログ放送、ATSC、DVB-T、DVB-C、DVB-S。チューニング空間はチューン リクエストのコンテキストを定義する、各チューン リクエストは個別のチューニング空間以外にとっては意味がない。たとえば ATSC チューニング空間オブジェクトは ATSC チューン リクエストを作成し、CVB チューニング空間オブジェクトは DVB-S チューン リクエストを作成する、等々。チューニング空間オブジェクトとチューン リクエスト オブジェクトは Automation® 互換で、スクリプトあるいは Microsoft® Visual Basic®、C/C++ から構成可能である。

チューニング空間をチューン リクエストとネットワーク プロバイダに対応させる

異なったネットワーク タイプは異なったタイプのデータを異なったフォーマットで運ぶので、あるチューニング空間はフィルタ グラフ内で固別のネットワーク プロバイダを必要とする。たとえば、ATSC デジタル フォーマット放送のチャンネルに対するチューン リクエストを作成するには、アプリケーションは IATSCTuningSpace をサポートする ATSC チューニング空間で始め、ATSC のネットワークタイプを持ち、IATSCLocator インターフェイスで構成された (このセッションの後半で説明する) デフォルト ロケータと結合される。アプリケーションが ITuningSpace::CreateTuneRequest を呼び出すと、ITuneRequest インターフェイス ポインタを戻り値として受け取る。アプリケーションはそのインターフェイスを使って IATSCTuneRequest インターフェイスをクエリし、次にそのインターフェイスを使ってチューン リクエストを構成する。チューン リクエストがサブミットされるとき、それは Microsoft ATSC ネットワーク プロバイダ (あるいは ATSC チューニング空間と同様に ITuner をサポートするサードパーティ BDA 互換のチューナー フィルタ) にサブミットされなければならない。

注 このバージョンの Microsoft® Broadcast Driver Architecture では、2 つのネットワーク プロバイダ フィルタが提供される、1 つは ATSC ネットワークであり、もう 1 つは DVB-S ネットワークである。DVB-S プロバイダについてはデフォルト チューニング空間は提供されない、なぜならそれを定義するには個別の情報が必要だからである。アプリケーションは SystemTuningSpaces オブジェクトを使って (C++ では ITuningSpaceContainer インターフェイスを使って)、ユーザーが購読するサービスについてユーザーから提供された基本情報をベースにした、アプリケーション自身の DVB-S チューニング空間を作成しなければならない。

他のチューニング モデル オブジェクト

Microsoft チューニング モデルはこのセクションの始めに説明したものとは別のオブジェクトを含む。次の図はすべてのチューニング モデル オブジェクト間のすべての関係を示す。C++ の用語ではこのダイアグラムは基底クラス間の関係を示す。チューン リクエストを作成、サブミットする実際のプロセスでは、アプリケーションは必ず同じタイプのネットワークすべてに固有の派生クラスを使って動作する。

一般的なチューニング モデル オブジェクトの関係

チューニング空間コンテナ はシステムで利用可能なチューニング空間のレジストリを探し、チューニング空間オブジェクトをインスタンス化する。

チューニング空間 には 3 つの基本的役割がある。個別の番組ソースでは、それはネットワーク タイプと、"TV:" モニカ ネーム スペース ルールのコンテンツ パースと、チューン リクエスト オブジェクトの作成である。"TV:" Uniform Resource Identifiers (URIs) は HTML や XML に組み込むことができ、正しいオブジェクト インスタンスへのバインド用にパースされなければならない。バインドは COM オブジェクトをモニカから取得するための COM 用語である。この場合、チューニング空間はネットワーク固有のパースを提供するので、"TV:" URI へのバインドはそのチューニング空間のチューン リクエスト オブジェクトとなる。

ロケータ オブジェクトはチューンスペースと結び付けられ、より詳細の情報を提供する、この情報を使ってデバイス ドライバはチューニング空間内で指定されたチャンネルあるいは周波数をチューンするために使う。

コンポーネントは MPEG-2 番組ストリーム内の基本ストリームを参照する、たとえばビデオ、オーディオ 1、オーディオ 2、オーディオ 3、番組サービス情報 (PSI) 等々。これらの値は新しい周波数にチューンされた後でネットワーク プロバイダが書き込む。

各コンポーネントはコンポーネント タイプ オブジェクトと結び付けられる、それは、どの言語がオディオ基本ストリームで話されているかのような、コンポーネントについての情報を持つ。アプリケーションは各ユーザーが参照するコンポーネント タイプのリストを維持する。現在のユーザーのリストは ITuner を通してネットワーク プロバイダにサブミットされるべきである。 そのようなリストが提供されないと、ネットワークプロバイダはチューニング空間内の デフォルト優先コンポーネント タイプ リストを使用する。サードパーティは新しい優先コンポーネント タイプを定義することができる。各ユーザーの優先コンポーネント タイプのリストを維持することによって、アプリケーションは特別な条件を除いてコンポーネントと直接やりとりすることはない。特別な条件とは次のような場合である、優先言語が英語だが視聴者がドイツ語オーディオを代わりに聞きたいとしたとき、優先オーディオ トラックが AC-3 だが使用者がモノラル トラックに変更しようとしたとき。

ネットワーク プロバイダがチューン リクエストを受け取り、個別のチャンネルあるいは周波数にチューンしたとき、ネットワーク プロバイダはトランスポート情報フィルタが取得した PSI 情報をベースに チューン リクエストのコンポーネント リストを書き込む。次にネットワーク プロバイダは現在のユーザーの優先コンポーネント タイプとその情報を比較し、ユーザーの要求に適合するものが利用可能なら、適切な基本ストリームにチューンする。この最初のチューン リクエストがサブミットされた後で、アプリケーションは現在アクティブなチューン リクエストを取得し、新しいコンポーネント リストにアクセスできる。このチューン リクエストはユーザーの選択命令として、アップデートされたコンポーネント リストで再度サブミットされる。この例はオーディオ トラックをデフォルト優先以外の言語に変更する場合である。優先コンポーネントはチューン リクエストのコンポーネント リストが空あるいは無効の場合のみ使われる。別のコンポーネントがアクティブであろうが非アクティブであろうが、チューン リクエストは何度も再サブミットされ得るのでこれは必要である。


BDA デジタル TV リファレンス

このトピックは、以下のセクションから構成される :

  • BDA COM インターフェイス
  • チューニング モデルのスクリプト可能なオブジェクト


BDA COM インターフェイス

以下の Microsoft® Broadcast Driver Architecture (BDA) COM インターフェイスは、C/C++ アプリケーションからアクセスできる。

チューニング空間インターフェイス

アプリケーションでは、ITuningSpaceContainer をサポートするチューニング空間コンテナ オブジェクトを使って、チューニング空間の作成またはアクセスができる。基底クラス ITuningSpace インターフェイスを直接使用することはない。常に、特定のネットワーク タイプに固有の派生インターフェイスを使用する。

ITuningSpace | 特定のチューニング空間インターフェイスのための基底クラス。
IAnalogRadioTuningSpace | 地上波ラジオ ネットワーク固有のチューニング空間。
IAnalogTVTuningSpace | アナログ TV ネットワーク固有のチューニング空間。
IATSCTuningSpace | ATSC ネットワーク固有のチューニング空間。
IDVBTuningSpace | DVB ネットワーク固有のチューニング空間。
ITuningSpaceContainer | アプリケーションから使用され、新しいチューニング空間の作成や、既存のチューニング空間の列挙または修正を行う。
IEnumTuningSpaces | チューニング空間を列挙する標準 COM 列挙インターフェイス。

チューニング要求インターフェイス

チューニング要求をアプリケーションから直接作成することはない。チューニング要求は、チューニング空間オブジェクトの ITuningSpace::CreateTuneRequest を呼び出して作成する。アプリケーションでは、返されたオブジェクトへのポインタを受け取った後、そのオブジェクトの QueryInterface を呼び出して、チューニング要求の修正に使用するネットワーク固有のインターフェイスを照会する。

ITuneRequest | チューニング要求オブジェクトで公開される。チューニング要求オブジェクトを作成するのは、チューニング空間オブジェクトである。アプリケーションでは、チューニング要求を修正してチューナーに発行できる。
IChannelTuneRequest | アナログ TV ネットワーク固有のチューニング要求オブジェクトに実装される。
IATSCChannelTuneRequest | ATSC TV ネットワーク固有のチューニング要求オブジェクトに実装される。

ストリーム コンポーネント インターフェイス

このコンテキストでは、ブロードキャスト内のサブストリームを "コンポーネント" と言う。アプリケーションでは、チューニング空間に関連付ける一連のデフォルト優先コンポーネント タイプを指定することのみを目的に、Component オブジェクトを作成する。ブロードキャスト ストリームの実際のコンポーネントは、受信開始後でなければわからない。その時点で、ネットワーク プロバイダが Component オブジェクト情報を設定すると、アプリケーションからこの情報を取得し、この情報を使って、たとえばオーディオ ストリームを変更したり、現在利用可能なオーディオ ストリームを判断したりできるようになる。

IComponent | 特定コンポーネント インターフェイスのための基底クラス。
IComponentType | 特定コンポーネント タイプ インターフェイスのための基底クラス。
IComponentTypes | 標準 COM のコンポーネント タイプ リストを提供する。
IComponents | 標準 COM のコンポーネント リストを提供する。
ILanguageComponentType | サブストリームの言語に関連付けられたコンポーネント タイプ。
IMPEG2ComponentType | MPEG-2 ストリーム タイプに関連付けられたコンポーネント タイプに実装される。
IATSCComponentType | オーディオ ストリームが AC-3 フォーマットかどうかを示すコンポーネント タイプに実装される。
IEnumComponents | 現在のブロードキャスト ストリームに含まれる全コンポーネントを (アクティブかどうかにかかわらず) 格納する標準 COM コレクション オブジェクトに実装される。

ロケータ インターフェイス

ロケータ オブジェクトは、グラフに含まれるネットワーク プロバイダおよびその他のフィルタが、ある種の場合に、チューニング要求に応えるため、チューニングの方法と対象の判断に使用する。デバッグを目的とする場合を除き、アプリケーションでこれらのインターフェイスを使用することはない。

ILocator | ネットワーク タイプ固有のチューニング空間ロケータのための基底クラス。
IATSCLocator | ネットワーク プロバイダから呼び出され、ATSC ネットワーク内でのチューニングに関する情報を取得する。アプリケーションでは使用しない。

ネットワーク プロバイダ インターフェイス

これらのインターフェイスは、ネットワーク プロバイダ フィルタで公開される。フィルタでは、アプリケーションから発行されたチューニング要求およびその他のコマンドを、これらのインターフェイスを使って処理する。

ITuner | アプリケーションからチューニング要求およびその他のデータを受け取るための基底クラス インターフェイス。フィルタ グラフ内のネットワーク プロバイダ フィルタでサポートされる。
IScanningTuner | フィルタ グラフ内のネットワーク プロバイダ フィルタでサポートされる。ITuner を継承する。デフォルトのネットワーク プロバイダ フィルタを使用しているアプリケーションでは、QueryInterface を使って ITuner ではなく IScanningTuner を照会しなければならない。


IAnalogRadioTuningSpace インターフェイス

このインターフェイスは、AnalogRadioTuningSpace オブジェクトに実装される。

メソッド名 | 説明
ITuningSpace オブジェクト
get_UniqueName | チューニング空間の固有の名称を取得する。固有の名称は略称か GUID である。
put_UniqueName | チューニング空間の固有の名称を設定する。固有の名称は略称か GUID である。
get_FriendlyName | チューニング空間のローカライズされたフレンドリ名を取得する。
put_FriendlyName | チューニング空間のローカライズされたフレンドリ名を設定する。
get_CLSID | チューニング空間の CLSID を BSTR として取得する。
get_NetworkType | チューニング空間のネットワーク タイプ GUID を BSTR として取得する。
put_NetworkType | このチューニング空間のネットワーク タイプを BSTR として設定する。
get__NetworkType | チューニング空間のネットワーク タイプを GUID として取得する。
put__NetworkType | このチューニング空間のネットワーク タイプを REFCLSID として設定する。
CreateTuneRequest | 空の (初期化されていない) チューニング要求を表す COM オブジェクトを作成する。
EnumCategoryGUIDs | DirectShow カテゴリ GUID を列挙する列挙子を作成する。カテゴリ GUID は、チューニング空間をサポートするフィルタの種類を表すものである。
EnumDeviceMonikers | このチューニング空間をサポートするチューナー入力 (フィルタ) を表すデバイス モニカの列挙子を作成する。
get_DefaultPreferredComponentTypes | 優先コンポーネント タイプのリストを返す。優先コンポーネント タイプは、優先オーディオ ストリームなどのパラメータを指定するものである。
put_DefaultPreferredComponentTypes | 優先コンポーネント タイプのリストを作成する。優先コンポーネント タイプは、優先オーディオ ストリームなどのパラメータを指定するものである。
get_DefaultLocator | ローカル システムのデフォルト ロケータを取得する。
put_DefaultLocator | ローカル システムのデフォルト ロケータを設定する。
IAnalogRadioTuningSpace メソッド
get_MinFrequency | このチューニング空間の最小周波数を取得する。
put_MinFrequency | このチューニング空間の最小周波数を設定する。
get_MaxFrequency | このチューニング空間の最大周波数を取得する。
put_MaxFrequency | このチューニング空間の最大周波数を設定する。
get_Step | このチューニング空間のステップ増分を取得する。
put_Step | このチューニング空間のステップ増分を取得する。

IAnalogRadioTuningSpace::get_MinFrequency

IAnalogRadioTuningSpace インターフェイス

このチューニング空間の最小周波数を取得する。

構文

HRESULT get_MinFrequency(
    long* MinFrequencyVal
    );

パラメータ

MinFrequencyVal
[out, retval] 最小周波数を受け取る Long 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IAnalogRadioTuningSpace::put_MinFrequency

IAnalogRadioTuningSpace インターフェイス

このチューニング空間の最小周波数を設定する。

構文

HRESULT put_MinFrequency(
    long NewMinFrequencyVal
    );

パラメータ

NewMinFrequencyVal
[in] 最小周波数を指定する Long 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IAnalogRadioTuningSpace::get_MaxFrequency

IAnalogRadioTuningSpace インターフェイス

このチューニング空間の最大周波数を取得する。

構文

HRESULT get_MaxFrequency(
    long* MaxFrequencyVal
    );

パラメータ

MaxFrequencyVal
[out, retval] 最大周波数を受け取る Long 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IAnalogRadioTuningSpace::put_MaxFrequency

IAnalogRadioTuningSpace インターフェイス

このチューニング空間の最大周波数を設定する。

構文

HRESULT put_MaxFrequency(
    long NewMaxFrequencyVal
    );

パラメータ

NewMaxFrequencyVal
[in] 最大周波数を指定する Long 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IAnalogRadioTuningSpace::get_Step

IAnalogRadioTuningSpace インターフェイス

このチューニング空間のステップ増分を取得する。

構文

HRESULT get_Step(
    long* StepVal
    );

パラメータ

StepVal
[out, retval] ステップ値を受け取る Long 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IAnalogRadioTuningSpace::put_Step

IAnalogRadioTuningSpace インターフェイス

このチューニング空間のステップ増分を取得する。

構文

HRESULT put_Step(
    long NewStepVal
    );

パラメータ

NewStepVal
[in] ステップ増分を指定する Long 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。


IAnalogTVTuningSpace インターフェイス

ネットワーク タイプがアナログ TV のチューニング空間を表す。

メソッド名 | 説明
ITuningSpace メソッド
get_UniqueName | チューニング空間の固有の名称を取得する。固有の名称は略称か GUID である。
put_UniqueName | チューニング空間の固有の名称を設定する。固有の名称は略称か GUID である。
get_FriendlyName | チューニング空間のローカライズされたフレンドリ名を取得する。
put_FriendlyName | チューニング空間のローカライズされたフレンドリ名を設定する。
get_CLSID | チューニング空間の CLSID を BSTR として取得する。
get_NetworkType | チューニング空間のネットワーク タイプ GUID を BSTR として取得する。
put_NetworkType | チューニング空間のネットワーク タイプ GUID を BSTR として設定する。
get__NetworkType | このチューニング空間のネットワーク タイプを GUID として取得する。
put__NetworkType | このチューニング空間のネットワーク タイプを REFCLSID として設定する。
CreateTuneRequest | 空の (初期化されていない) チューニング要求を表す COM オブジェクトを作成する。
EnumCategoryGUIDs | DirectShow カテゴリ GUID を列挙する列挙子を作成する。カテゴリ GUID は、チューニング空間をサポートするフィルタの種類を表すものである。
EnumDeviceMonikers | このチューニング空間をサポートするチューナー入力 (フィルタ) を表すデバイス モニカの列挙子を作成する。
get_DefaultPreferredComponentTypes | 優先コンポーネント タイプのリストを返す。優先コンポーネント タイプは、優先オーディオ ストリームなどのパラメータを指定するものである。
put_DefaultPreferredComponentTypes | 優先コンポーネント タイプのリストを設定する。優先コンポーネント タイプは、優先オーディオ ストリームなどのパラメータを指定するものである。
get_DefaultLocator | ローカル システムのデフォルト ロケータを取得する。
put_DefaultLocator | ローカル システムのデフォルト ロケータを設定する。
IAnalogTVTuningSpace メソッド
get_MinChannel | このチューニング空間の最小チャンネル番号を取得する。
put_MinChannel | このチューニング空間の最小チャンネル番号を設定する。
get_MaxChannel | このチューニング空間の最大チャンネル番号を取得する。
put_MaxChannel | このチューニング空間の最大チャンネル番号を設定する。
get_InputType | チューニング空間で使用する入力タイプ (アンテナまたはケーブル) を取得する。
put_InputType | チューニング空間で使用する入力タイプ (アンテナまたはケーブル) を設定する。
get_CountryCode | チューニング空間の国コードを取得する (TAPI の国コードに準拠)。
put_CountryCode | チューニング空間の国コードを設定する (TAPI の国コードに準拠)。

IAnalogTVTuningSpace::get_MinChannel

IAnalogTVTuningSpace インターフェイス

このチューニング空間の最小チャンネル番号を取得する。

構文

HRESULT get_MinChannel(
    short* MinChannelVal
    );

パラメータ

MinChannelVal
[out, retval] 最小チャンネル番号の値を受け取る Short 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

アンテナに接続された NTSC チューニング空間は、値 2 を返す。

IAnalogTVTuningSpace::put_MinChannel

IAnalogTVTuningSpace インターフェイス

このチューニング空間の最小チャンネル番号を設定する。

構文

HRESULT put_MinChannel(
    short NewMinChannelVal
    );

パラメータ

NewMinChannelVal
[in] 最小チャンネル番号を指定する Short 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IAnalogTVTuningSpace::get_MaxChannel

IAnalogTVTuningSpace インターフェイス

このチューニング空間の最大チャンネル番号を取得する。

構文

HRESULT get_MaxChannel(
    short* MaxChannelVal
    );

パラメータ

MaxChannelVal
[out, retval] 最大チャンネル番号の値を受け取る Short 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

たとえば、アンテナに接続された NTSC チューニング空間は 69 を返す。

IAnalogTVTuningSpace::put_MaxChannel

IAnalogTVTuningSpace インターフェイス

このチューニング空間の最大チャンネル番号を設定する。

構文

HRESULT put_MaxChannel(
    short NewMaxChannelVal
    );

パラメータ

NewMaxChannelVal
[in] 最大チャンネル番号を指定する Short 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IAnalogTVTuningSpace::get_InputType

IAnalogTVTuningSpace インターフェイス

チューニング空間で使用する入力タイプ (アンテナまたはケーブル) を取得する。

構文

HRESULT get_InputType(
    TunerInputType* InputTypeVal
    );

パラメータ

InputTypeVal
[out, retval] 入力タイプを受け取る TunerInputType 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IAnalogTVTuningSpace::put_InputType

IAnalogTVTuningSpace インターフェイス

チューニング空間で使用する入力タイプ (アンテナまたはケーブル) を設定する。

構文

HRESULT put_InputType(
    TunerInputType NewInputTypeVal
    );

パラメータ

NewInputTypeVal
[in] 入力タイプを指定する TunerInputType 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IAnalogTVTuningSpace::get_CountryCode

IAnalogTVTuningSpace インターフェイス

チューニング空間の国コードを取得する (TAPI の国コードに準拠)。

構文

HRESULT get_CountryCode(
    long* CountryCodeVal
    );

パラメータ

CountryCodeVal
[out, retval] 国コードの値を受け取る Long 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

チューナーは、この国コードを使って、適したチャンネルと周波数のマッピングを判断できる。

IAnalogTVTuningSpace::put_CountryCode

IAnalogTVTuningSpace インターフェイス

チューニング空間の国コードを設定する (TAPI の国コードに準拠)。

構文

HRESULT put_CountryCode(
    long NewCountryCodeVal
    );

パラメータ

NewCountryCodeVal
[in] 国コードを指定する Long 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

チューナーは、この国コードを使って、適したチャンネルと周波数のマッピングを判断できる。


IATSCChannelTuneRequest インターフェイス

このインターフェイスは、ATSCChannelTuneRequest オブジェクトに実装される。

メソッド名 | 説明
ITuneRequest メソッド
get_TuningSpace | チューニング空間オブジェクトを取得する。
get_Components | IComponent オブジェクトのコレクションを取得する。
Clone | このチューニング要求の新しいコピーを返す。
get_Locator | ネットワーク プロバイダから呼び出され、要求されたブロードキャストに関連付けられた ILocator オブジェクトを取得する。
put_Locator | ネットワーク プロバイダから呼び出され、要求されたブロードキャストに関連付けられた ILocator オブジェクトを設定する。
IChannelTuneRequest メソッド
get_Channel | チューニングするチャンネルを取得する。
put_Channel | チューニングするチャンネルを設定する。
IATSCChannelTuneRequest メソッド
get_MinorChannel | チューニングするマイナー チャンネルを取得する。
put_MinorChannel | チューニングするマイナー チャンネルを設定する。

IATSCChannelTuneRequest::get_MinorChannel

IATSCChannelTuneRequest インターフェイス

チューニングするマイナー チャンネルを取得する。

構文

HRESULT get_MinorChannel(
    short* MinorChannel
    );

パラメータ

MinorChannel
[out, retval] 現在のマイナー チャンネルを受け取る Short 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IATSCChannelTuneRequest::put_MinorChannel

IATSCChannelTuneRequest インターフェイス

チューニングするマイナー チャンネルを設定する。

構文

HRESULT put_MinorChannel(
    short MinorChannel
    );

パラメータ

MinorChannel
[in] マイナー チャンネルを指定する Short 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。


IATSCComponentType インターフェイス

IATSCComponentType インターフェイスは、ATSCComponentType オブジェクトに実装される。このインターフェイスを使用すると、ストリーム タイプがオーディオの場合に、アプリケーションから AC3 ストリームかどうかを判断できる。

メソッド名 | 説明
get_Flags | オーディオ コンポーネントが AC-3 フォーマットかどうかを示すフラグを返す。
put_Flags | オーディオ コンポーネントが AC-3 フォーマットかどうかを示すフラグを設定する。

IATSCComponentType::get_Flags

IATSCComponentType インターフェイス

オーディオ コンポーネントが AC-3 フォーマットかどうかを示すフラグを返す。

構文

HRESULT get_Flags(
    long* Flags
    );

パラメータ

*Flags
[out, retval] ATSCComponentTypeFlags フラグを受け取る Long 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

定義されているフラグは、AC-3 オーディオを表すフラグのみである。
    typedef enum ATSCComponentTypeFlags {
        ATSCCT_AC3 = 0x00000001,
    } ATSCComponentTypeFlags;

IATSCComponentType::put_Flags

IATSCComponentType インターフェイス

オーディオ コンポーネントが AC-3 フォーマットかどうかを示すフラグを設定する。

構文

HRESULT put_Flags(
    long flags
    );

パラメータ

flags
[in] Long 型の変数。0x1 はオーディオ ストリームが AC-3 であることを示す。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

定義されているフラグは、AC-3 オーディオを表すフラグのみである。
    typedef enum ATSCComponentTypeFlags {
        ATSCCT_AC3 = 0x00000001,
    } ATSCComponentTypeFlags;


IATSCLocator インターフェイス

このインターフェイスは、ATSCLocator オブジェクトに実装される。

ILocator メソッド名 | 説明
Clone | ロケータのコピーを作成する。
get_CarrierFrequency | RF 信号の周波数を取得する。
get_InnerFEC | 使用する内部前方誤り訂正のタイプを取得する。
get_InnerFECRate | 内部 FEC レートを取得する。
get_Modulation | 変調タイプを取得する。
get_OuterFEC | 使用する外部前方誤り訂正のタイプを取得する。
get_OuterFECRate | 外部 FEC レートを設定する。
SymbolRate | QPSK シンボル レートを取得する。
put_CarrierFrequency | RF 信号の周波数を設定する。
put_InnerFEC | 使用する内部前方誤り訂正のタイプを設定する。
put_InnerFECRate | 内部 FEC レートを設定する。
put_Modulation | 変調タイプを設定する。
put_OuterFEC | 使用する外部前方誤り訂正のタイプを設定する。
put_OuterFECRate | 外部 FEC レートを設定する。
SymbolRate | QPSK シンボル レートを設定する。
IATSCLocator メソッド名 | 説明
get_PhysicalChannel | 物理チャンネルを取得する。
put_PhysicalChannel | 物理チャンネルを設定する。
get_TSID | トランスポート ストリーム ID を取得する。
put_TSID | トランスポート ストリーム ID 設定する。

IATSCLocator::get_PhysicalChannel

IATSCLocator インターフェイス

物理チャンネルを取得する。

構文

HRESULT get_PhysicalChannel(
    short* PhysicalChannel
    );

パラメータ

*PhysicalChannel
[out, retval] 物理チャンネルを受け取る Short 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IATSCLocator::put_PhysicalChannel

IATSCLocator インターフェイス

物理チャンネルを設定する。

構文

HRESULT put_PhysicalChannel(
    short PhysicalChannel
    );

パラメータ

PhysicalChannel
[in] 物理チャンネルを指定する Short 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IATSCLocator::get_TSID

IATSCLocator インターフェイス

トランスポート ストリーム ID を取得する。

構文

HRESULT get_TSID(
short* TSID
    );

パラメータ

*TSID
[out, retval] トランスポート ストリーム ID を受け取る Short 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IATSCLocator::put_TSID

IATSCLocator インターフェイス

トランスポート ストリーム ID を設定する。

構文

HRESULT put_TSID(
short TSID
    );

パラメータ

TSID
[in] トランスポート ストリーム ID を指定する Short 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。


IATSCTuningSpace インターフェイス

IATSCTuningSpace は、ITuningSpace および IAnalogTVTuningSpace を継承し、ATSC ネットワーク タイプを表すオブジェクトに実装される。これらのオブジェクトは、レジストリ内の情報に基づいてチューニング空間コンテナが作成する。IATSCTuningSpace オブジェクトは、IATSCChannelTuneRequest を公開するチューニング要求を作成する。

メソッド名 | 説明
ITuningSpace メソッド
get_UniqueName | チューニング空間の固有の名称を取得する。固有の名称は略称か GUID である。
put_UniqueName | チューニング空間の固有の名称を設定する。固有の名称は略称か GUID である。
get_FriendlyName | チューニング空間のローカライズされたフレンドリ名を取得する。
put_FriendlyName | チューニング空間のローカライズされたフレンドリ名を設定する。
get_CLSID | チューニング空間の CLSID を BSTR として取得する。
get_NetworkType | チューニング空間のネットワーク タイプ GUID を BSTR として取得する。
put_NetworkType | このチューニング空間のネットワーク タイプを BSTR として設定する。
get__NetworkType | チューニング空間のネットワーク タイプを GUID として取得する。
put__NetworkType | このチューニング空間のネットワーク タイプを REFCLSID として設定する。
CreateTuneRequest | 空の (初期化されていない) チューニング要求を表す COM オブジェクトを作成する。
EnumCategoryGUIDs | DirectShow カテゴリ GUID を列挙する列挙子を作成する。カテゴリ GUID は、チューニング空間をサポートするフィルタの種類を表すものである。
EnumDeviceMonikers | このチューニング空間をサポートするチューナー入力 (フィルタ) を表すデバイス モニカの列挙子を作成する。
get_DefaultPreferredComponentTypes | 優先コンポーネント タイプのリストを返す。優先コンポーネント タイプは、優先オーディオ ストリームなどのパラメータを指定するものである。
put_DefaultPreferredComponentTypes | 優先コンポーネント タイプのリストを設定する。優先コンポーネント タイプは、優先オーディオ ストリームなどのパラメータを指定するものである。
get_DefaultLocator | ローカル システムのデフォルト ロケータを取得する。
put_DefaultLocator | ローカル システムのデフォルト ロケータを設定する。
IAnalogTVTuningSpace メソッド
get_MinChannel | このチューニング空間の最小チャンネル番号を取得する。
put_MinChannel | このチューニング空間の最小チャンネル番号を設定する。
get_MaxChannel | このチューニング空間の最大チャンネル番号を取得する。
put_MaxChannel | このチューニング空間の最大チャンネル番号を設定する。
get_InputType | チューニング空間で使用する入力タイプ (アンテナまたはケーブル) を取得する。
put_InputType | チューニング空間で使用する入力タイプ (アンテナまたはケーブル) を設定する。
get_CountryCode | チューニング空間の国コードを取得する (TAPI の国コードに準拠)。
put_CountryCode | チューニング空間の国コードを設定する (TAPI の国コードに準拠)。
IATSCTuningSpace メソッド
get_MinMinorChannel | このチューニング空間に許される最小のマイナー チャンネル番号を取得する。
put_MinMinorChannel | このチューニング空間に許される最小のマイナー チャンネル番号を設定する。
get_MaxMinorChannel | このチューニング空間の最大マイナー チャンネル番号を取得する。
put_MaxMinorChannel | このチューニング空間の最大マイナー チャンネル番号を設定する。
get_MinPhysicalChannel | このチューニング空間に許される最小の物理チャンネル番号を取得する。
put_MinPhysicalChannel | このチューニング空間に許される最小の物理チャンネル番号を設定する。
get_MaxPhysicalChannel | このチューニング空間に許される最大の物理チャンネル番号を取得する。
put_MaxPhysicalChannel | このチューニング空間に許される最大の物理チャンネル番号を設定する。

IATSCTuningSpace::get_MinMinorChannel

IATSCTuningSpace インターフェイス

このチューニング空間に許される最小のマイナー チャンネル番号を取得する。

構文

HRESULT get_MinMinorChannel(
    short* MinMinorChannelVal
    );

パラメータ

MinMinorChannelVal
[out, retval] 最小マイナー チャンネル番号を受け取る Short 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IATSCTuningSpace::put_MinMinorChannel

IATSCTuningSpace インターフェイス

このチューニング空間に許される最小のマイナー チャンネル番号を設定する。

構文

HRESULT put_MinMinorChannel(
    short NewMinMinorChannelVal
    );

パラメータ

NewMinMinorChannelVal
[in] 最小マイナー チャンネルを指定する Short 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

最小マイナー チャンネルを最大マイナー チャンネルより大きくしないため、このプロパティより先に MaxMinorChannel プロパティを設定する必要がある。どちらのプロパティも、デフォルト値は -1 (設定なし) である。

IATSCTuningSpace::get_MaxMinorChannel

IATSCTuningSpace インターフェイス

このチューニング空間の最大マイナー チャンネル番号を取得する。

構文

HRESULT get_MaxMinorChannel(
    short* MaxMinorChannelVal
    );

パラメータ

MaxMinorChannelVal
[out, retval] 最大マイナー チャンネル番号を受け取る Short 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IATSCTuningSpace::put_MaxMinorChannel

IATSCTuningSpace インターフェイス

このチューニング空間の最大マイナー チャンネル番号を取得する。

構文

HRESULT put_MaxMinorChannel(
    short NewMaxMinorChannelVal
    );

パラメータ

NewMaxMinorChannelVal
[in] 最大マイナー チャンネルを指定する Short 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

最小マイナー チャンネルを最大マイナー チャンネルより大きくしないため、MinMinorChannel プロパティより先にこのプロパティを設定する必要がある。どちらのプロパティも、デフォルト値は -1 (設定なし) である。

IATSCTuningSpace::get_MinPhysicalChannel

IATSCTuningSpace インターフェイス

このチューニング空間の最小物理チャンネル番号を設定する。

構文

HRESULT get_MinPhysicalChannel(
    short* MinPhysicalChannelVal
    );

パラメータ

MinPhysicalChannelVal
[out, retval] 最小物理チャンネルを受け取る Short 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IATSCTuningSpace::put_MinPhysicalChannel

IATSCTuningSpace インターフェイス

このチューニング空間の最小物理チャンネル番号を設定する。

構文

HRESULT put_MinPhysicalChannel(
    short NewMinPhysicalChannelVal
    );

パラメータ

NewMinPhysicalChannelVal
[in] 最小物理チャンネルを指定する Short 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IATSCTuningSpace::get_MaxPhysicalChannel

IATSCTuningSpace インターフェイス

このチューニング空間の最大物理チャンネル番号を取得する。

構文

HRESULT get_MaxPhysicalChannel(
    short* MaxPhysicalChannelVal
    );

パラメータ

MaxPhysicalChannelVal
[out, retval] 最大物理チャンネルを受け取る Short 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IATSCTuningSpace::put_MaxPhysicalChannel

IATSCTuningSpace インターフェイス

このチューニング空間の最大物理チャンネル番号を設定する。

構文

HRESULT put_MaxPhysicalChannel(
    short NewMaxPhysicalChannelVal
    );

パラメータ

NewMaxPhysicalChannelVal
[in] 最大物理チャンネルを指定する Short 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。


IChannelTuneRequest インターフェイス

IChannelTuneRequest インターフェイスは、アナログ TV 固有の TuneRequest オブジェクトに実装される。このインターフェイスを使用すると、アプリケーションからアナログ TV ネットワーク用のチューニング要求を作成できる。

メソッド名 | 説明
ITuneRequest メソッド
get_TuningSpace | チューニング空間オブジェクトを取得する。
get_Components | IComponent オブジェクトのコレクションを取得する。
Clone | このチューニング要求の新しいコピーを返す。
get_Locator | ネットワーク プロバイダから呼び出され、要求されたブロードキャストに関連付けられた ILocator オブジェクトを取得する。
put_Locator | ネットワーク プロバイダから呼び出され、要求されたブロードキャストに関連付けられた ILocator オブジェクトを設定する。
IChannelTuneRequest メソッド
get_Channel | チューニングするチャンネルを取得する。
put_Channel | チューニングするチャンネルを設定する。

IChannelTuneRequest::get_Channel

IChannelTuneRequest インターフェイス

チューニングするチャンネルを取得する。

構文

HRESULT get_Channel(
    short* Channel
    );

パラメータ

Channel
[out, retval] 現在のチャンネルを受け取る Short 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IChannelTuneRequest::put_Channel

IChannelTuneRequest インターフェイス

チューニングするチャンネルを設定する。

構文

HRESULT put_Channel(
    short Channel
    );

パラメータ

Channel
[in] チャンネルを指定する Short 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

Channel の指定値がチューニング空間に設定された最小チャンネルより小さい場合は、最大チャンネルに "ラップ アラウンド" する。同様に、Channel の指定値がチューニング空間に設定された最大チャンネルより大きい場合は、最小チャンネルに "ラップ アラウンド" する。


IComponent インターフェイス

IComponent インターフェイスは、すべての Component オブジェクトの基底クラス インターフェイスであり、コンポーネント (主にプログラム ストリーム内の基本ストリーム) の一般的な特性を記述する。IMPEG2Component などの派生インターフェイスは、IComponent を継承し、コンポーネントに関する所定のネットワーク タイプ固有のプロパティを記述する。受信が開始すると、トランスポート情報フィルタ (TIF) が、Component オブジェクトを作成してチューニング要求にアタッチする。すべての Component オブジェクトは、IPersistPropertyBag をサポートする。

メソッド名 | 説明
get_Type | コンポーネントの一般的な特性を記述する IComponentType オブジェクトを取得する。
put_Type | コンポーネントの一般的な特性を記述する IComponentType オブジェクトを設定する。
get_DescLangID | 説明のプレゼンテーションに使用する言語を取得する。
put_DescLangID | 説明のプレゼンテーションに使用する言語を設定する。
get_Status | コンポーネントの要求された状態または実際の状態を取得する。
put_Status | コンポーネントの要求された状態または実際の状態を設定する。
get_Description | コンポーネントの説明を取得する。
put_Description | コンポーネントの説明を設定する。
Clone | コンポーネントの新しいコピーを作成する。

IComponent::Clone

IComponent インターフェイス

コンポーネントの新しいコピーを作成する。

構文

HRESULT Clone(
    IComponent** NewComponent
    );

パラメータ

NewComponent
[out, retval] 新しいコンポーネントに設定する IComponent インターフェイスへのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IComponent::get_Type

IComponent インターフェイス

コンポーネントの一般的な特性を記述する IComponentType オブジェクトを取得する。

構文

HRESULT get_Type(
    IComponentType** CT
    );

パラメータ

CT
[out, retval] 取得したコンポーネントに設定する IComponentType インターフェイス ポインタのアドレス。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IComponent::put_Type

IComponent インターフェイス

コンポーネントの一般的な特性を記述する IComponentType オブジェクトを設定する。

構文

HRESULT put_Type(
    IComponentType* CT
    );

パラメータ

CT
[in] コンポーネントに対応する新しい値を指定する IComponentType オブジェクトへのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

IComponent 基底クラス インターフェイスを使用しているときには、タイプに NULL を設定できる。同じことを IMPEG2Component 派生クラス インターフェイスで実行しようとすると、このメソッドは E_POINTER を返す。IMPEG2Component オブジェクトでは、設定するタイプとして IComponentType 基底クラス インターフェイスを持つことができない。この場合、メソッドは Type Mismatch (0x80020005) を返す。

IComponent::get_DescLangID

IComponent インターフェイス

説明のプレゼンテーションに使用する言語を取得する。

構文

HRESULT get_DescLangID(
short* LangID
    );

パラメータ

*LangID
[out, retval] 言語 ID を受け取る Short 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

この言語は、Component オブジェクトに含まれる説明情報の言語である。ストリーム コンテンツの言語を定義する言語コンポーネント タイプ内の言語 ID とは異なる。

IComponent::put_DescLangID

IComponent インターフェイス

説明のプレゼンテーションに使用する言語を設定する。

構文

HRESULT put_DescLangID(
short LangID
    );

パラメータ

LangID
[in] 言語 ID を指定する Short 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

この言語は、Component オブジェクトに含まれる説明情報の言語である。ストリーム コンテンツの言語を定義する言語コンポーネント タイプ内の言語 ID とは異なる。アプリケーションからこの値を修正すると、別の言語のサブストリームをアクティブにすることができる。

IComponent::get_Status

IComponent インターフェイス

コンポーネントの要求された状態または実際の状態を取得する。

構文

HRESULT get_Status(
    ComponentStatus* Status
    );

パラメータ

*Status
[out, retval] 状態の値を受け取る ComponentStatus 列挙型へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

typedef enum ComponentStatus
    {
        [helpstring("Component is selected")] StatusActive,
        [helpstring("Component is not selected")] StatusInactive,
        [helpstring("Component is unavailable")] StatusUnavailable,
    } ComponentStatus;

チューナーは、Components コレクションにコンポーネントを追加するとき、コンポーネントがアクティブかどうかを指定できる。アプリケーションでは、この状態の設定を試みたうえで、チューニング要求を再発行できる。チューナーは状態を更新する。状態には Active、Inactive、Unavailable の 3 種類があるが、Unavailable は、アクティブにすることを要求されたとき、コンポーネントが実際に利用可能でない場合に、チューナーだけが設定する状態である。

IComponent::put_Status

IComponent インターフェイス

コンポーネントの要求された状態または実際の状態を設定する。

構文

HRESULT put_Status(
    ComponentStatus Status
    );

パラメータ

Status
[in] 状態の値を指定する ComponentStatus 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

ストリーム コンポーネント (サブストリーム) をアクティブ/非アクティブにするには、このメソッドを使用する。

参照

get_Status

IComponent::get_Description

IComponent インターフェイス

コンポーネントの説明を取得する。

構文

HRESULT get_Description(
    BSTR* Description
    );

パラメータ

*Description
[out, retval] 説明を受け取る BSTR 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

IComponent::put_Description

IComponent インターフェイス

コンポーネントの説明を設定する。

構文

HRESULT put_Description(
    BSTR Description
    );

パラメータ

Description
[in] 新しい説明が格納された BSTR 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

このメソッドは、アプリケーションではなく、ガイド ストアから呼び出される。


IComponents インターフェイス

デジタル TV のコンテキストでは、プログラム ストリーム内のサブストリームを "Component" と言う。たとえば、プログラム ストリームに言語が異なる 3 つのオーディオ ストリームがある場合には、個々のオーディオ ストリームがそのプログラム ストリームの "Component" となる。IComponents インターフェイスは、Component オブジェクトのコレクションである Components オブジェクトに実装される。アプリケーションでは、Components オブジェクトによって、プログラム ストリームに含まれるコンポーネントを列挙し、コレクションに含まれる個々のコンポーネントに関連した処理を実行することができる。すべての Components オブジェクトは、IPersistPropertyBag もサポートする。

メソッド名 | 説明
get_Count | コレクションに含まれる Component オブジェクトの数を取得する。
get__NewEnum | Automation クライアントの For...Each ループをサポートするための列挙メソッド。
EnumComponents | コレクションに含まれるコンポーネントをすべて列挙する IEnumComponents 列挙子を返す。
get_Item | 指定したインデックス位置のコンポーネントにアクセスする。
Add | コレクションに Component オブジェクトを追加する。
Remove | コレクションから Component オブジェクトを削除する。
Clone | コレクションの新しいコピーを作成する。

IComponents::get_Count

IComponents インターフェイス

コレクションに含まれる Component オブジェクトの数を取得する。

構文

HRESULT get_Count(
long* Count
    );

パラメータ

Count
[out, retval] コンポーネント数を受け取る Long 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IComponents::get__NewEnum

IComponents インターフェイス

Automation クライアントの For...Each ループをサポートするための列挙メソッド。

構文

HRESULT get__NewEnum(
IEnumVARIANT** ppNewEnum
    );

パラメータ

ppNewEnum
[out, retval] 列挙子を受け取る IEnumVARIANT インターフェイス ポインタのアドレス。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

このメソッドは、For...Each ループの繰り返しによってコレクション全体を処理するため、スクリプト アプリケーションおよび VB アプリケーション用に提供される。C++ アプリケーションでは EnumComponents メソッドを使用すること。

IComponents::EnumComponents

IComponents インターフェイス

コレクションに含まれるコンポーネントをすべて列挙する IEnumComponents 列挙子を返す。

構文

HRESULT EnumComponents(
    IEnumComponents** ppNewEnum
    );

パラメータ

ppNewEnum
[out, retval] 新しい列挙子を受け取る IEnumComponents インターフェイス ポインタのアドレス。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IComponents::get_Item

IComponents インターフェイス

指定したインデックス位置のコンポーネントにアクセスする。

構文

HRESULT get_Item(
VARIANT Index,
    IComponent** ppComponent
    );

パラメータ

Index
[in] コレクションにおける 0 から始まるインデックスを指定する VARIANT 型変数。
ppComponent
[out, retval] 指定されたインデックス位置の Component オブジェクトを受け取る IComponent インターフェイス ポインタのアドレス。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IComponents::Add

IComponents インターフェイス

コレクションに Component オブジェクトを追加する。

構文

HRESULT Add(
    IComponent* Component,
VARIANT* NewIndex
    );

パラメータ

Component
[in] 追加する Component オブジェクトへのポインタ。
NewIndex
[out, retval] 追加したコンポーネントのインデックスを受け取る VARIANT へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IComponents::Remove

IComponents インターフェイス

コレクションから Component オブジェクトを削除する。

構文

HRESULT Remove(
VARIANT Index
    );

パラメータ

Index
[in] 削除するコンポーネントのインデックス番号を指定する VARIANT 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IComponents::Clone

IComponents インターフェイス

コレクションの新しいコピーを作成する。

構文

HRESULT Clone(
    IComponents** NewList
    );

パラメータ

NewList
[out, retval] 新しい Components オブジェクトに設定される、IComponents インターフェイス ポインタのアドレス。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。


IComponentType インターフェイス

IComponentType インターフェイスは、ComponentType オブジェクトに実装され、ComponentType オブジェクトには、コンポーネントの各種プロパティを設定および取得するためのメソッドが含まれる。すべての Component オブジェクトには、get_Type メソッドと put_Type メソッドで設定および取得する ComponentType オブジェクトが関連付けられている。

メソッド名 | 説明
Clone | このコンポーネント タイプの新しいコピーを作成する。
get_Category | コンポーネントのカテゴリを取得する。
get_MediaFormatType | DirectShow のメディア フォーマット タイプを BSTR で取得する。
get__MediaFormatType | DirectShow のメディア フォーマット タイプを GUID で取得する。
get_MediaMajorType | DirectShow のメディア メジャー タイプを BSTR で取得する。
get__MediaMajorType | DirectShow のメディア メジャー タイプを GUID で取得する。
get_MediaSubType | DirectShow のメディア サブタイプを BSTR で取得する。
get__MediaSubType | DirectShow のメディア サブタイプを GUID で取得する。
get_MediaType | コンポーネントの DirectShow AM_MEDIA_TYPE メディア タイプ構造体を取得する。
put_Category | コンポーネントのカテゴリを設定する。
put_MediaFormatType | DirectShow のメディア フォーマット タイプを設定する。
put__MediaFormatType | DirectShow のメディア フォーマット タイプを設定する。
put_MediaMajorType | DirectShow のメディア メジャー タイプを設定する。
put__MediaMajorType | DirectShow のメディア メジャー タイプを設定する。
put_MediaSubType | DirectShow のメディア サブタイプを設定する。
put__MediaSubType | DirectShow のメディア サブタイプを設定する。
put_MediaType | コンポーネントの DirectShow AM_MEDIA_TYPE メディア タイプ構造体を設定する。

IComponentType::Clone

IComponentType インターフェイス

このコンポーネント タイプの新しいコピーを作成する。

構文

HRESULT Clone(
    IComponentType** NewCT
    );

パラメータ

NewCT
[out, retval] 返されるインターフェイスに設定する IComponentType インターフェイス ポインタのアドレス。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IComponentType::get_Category

IComponentType インターフェイス

コンポーネントのカテゴリを取得する。

構文

HRESULT get_Category(
    ComponentCategory* Category
    );

パラメータ

Category
[out, retval] カテゴリを受け取る ComponentCategory データ型へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

ComponentCategory 列挙型は bdatypes.h に次のように定義されている。
typedef enum ComponentCategory
{
CategoryNotSet = -1,
CategoryOther = 0,
CategoryVideo = 1,
CategoryAudio = 2,
CategoryText = 3,
CategoryData = 4,
} ComponentCategory;

IComponentType::get_MediaFormatType

IComponentType インターフェイス

DirectShow のメディア フォーマット タイプを BSTR で取得する。

構文

HRESULT get_MediaFormatType(
    BSTR* MediaFormatType
    );

パラメータ

MediaFormatType
[out, retval] GUID を受け取る BSTR へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IComponentType::get__MediaFormatType

IComponentType インターフェイス

DirectShow のメディア フォーマット タイプを GUID で取得する。

構文

HRESULT get__MediaFormatType(
    GUID *MediaFormatType
    );

パラメータ

MediaFormatType
[out, retval] フォーマット タイプを受け取る GUID へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

このメソッドは、C++ からのみ利用可能である。メソッド名にアンダスコアが 2 つ含まれるメソッドには、アンダスコアが 1 つ少ない同等のメソッドが存在し、後者ではパラメータに BSTR を使用する。

IComponentType::get_MediaMajorType

IComponentType インターフェイス

DirectShow のメディア メジャー タイプを BSTR で取得する。

構文

HRESULT get_MediaMajorType(
    BSTR* MediaMajorType
    );

パラメータ

MediaMajorType
[out, retval] GUID を受け取る BSTR へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IComponentType::get__MediaMajorType

IComponentType インターフェイス

DirectShow のメディア フォーマット タイプを GUID で取得する。

構文

HRESULT get__MediaMajorType(
    GUID *MediaMajorType
    );

パラメータ

MediaMajorType
[out, retval] メジャー タイプを受け取る GUID へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

このメソッドは、C++ からのみ利用可能である。メソッド名にアンダスコアが 2 つ含まれるメソッドには、アンダスコアが 1 つ少ない同等のメソッドが存在し、後者ではパラメータに BSTR を使用する。

IComponentType::get_MediaSubType

IComponentType インターフェイス

DirectShow のメディア サブタイプを BSTR で取得する。

構文

HRESULT get_MediaSubType(
    BSTR* MediaSubType
    );

パラメータ

MediaSubType
[out, retval] GUID を受け取る BSTR へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IComponentType::get__MediaSubType

IComponentType インターフェイス

DirectShow のメディア サブタイプを GUID で取得する。

構文

HRESULT get__MediaSubType(
    GUID *MediaSubType
    );

パラメータ

MediaSubType
[out, retval] メジャー タイプを受け取る GUID へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

このメソッドは、C++ からのみ利用可能である。メソッド名にアンダスコアが 2 つ含まれるメソッドには、アンダスコアが 1 つ少ない同等のメソッドが存在し、後者ではパラメータに BSTR を使用する。

IComponentType::get_MediaType

IComponentType インターフェイス

コンポーネントの DirectShow AM_MEDIA_TYPE メディア タイプ構造体を取得する。

構文

HRESULT get_MediaType(
    AM_MEDIA_TYPE* MediaType
    );

パラメータ

MediaType
[out, retval] 現在の ComponentType に関連付けられた値が設定される AM_MEDIA_TYPE 構造体へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IComponentType::put_Category

IComponentType インターフェイス

コンポーネントのカテゴリを設定する。

構文

HRESULT put_Category(
    ComponentCategory Category
    );

パラメータ

Category
[in] このコンポーネント タイプの新しいカテゴリを指定する ComponentCategory 値。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

ComponentCategory 列挙型は bdatypes.h に次のように定義されている。
typedef enum ComponentCategory
{
CategoryNotSet = -1,
CategoryOther = 0,
CategoryVideo = 1,
CategoryAudio = 2,
CategoryText = 3,
CategoryData = 4,
} ComponentCategory;

IComponentType::put_MediaFormatType

IComponentType インターフェイス

DirectShow のメディア フォーマット タイプを設定する。

構文

HRESULT put_MediaFormatType(
    BSTR MediaFormatType
    );

パラメータ

MediaFormatType
[in] GUID を指定する BSTR。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IComponentType::put__MediaFormatType

IComponentType インターフェイス

DirectShow のメディア フォーマット タイプを設定する。

構文

HRESULT put__MediaFormatType(
    REFCLSID MediaFormatType
    );

パラメータ

MediaFormatType
[in] メディア フォーマット タイプを指定する REFCLSID。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

このメソッドは、C++ からのみ利用可能である。メソッド名にアンダスコアが 2 つ含まれるメソッドには、アンダスコアが 1 つ少ない同等のメソッドが存在し、後者ではパラメータに BSTR を使用する。

IComponentType::put_MediaMajorType

IComponentType インターフェイス

DirectShow のメディア メジャー タイプを設定する。

構文

HRESULT put_MediaMajorType(
    BSTR MediaMajorType
    );

パラメータ

MediaMajorType
[in] GUID を指定する BSTR。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IComponentType::put__MediaMajorType

IComponentType インターフェイス

DirectShow のメディア メジャー タイプを設定する。

構文

HRESULT put__MediaMajorType(
    REFCLSID MediaMajorType
    );

パラメータ

MediaMajorType
[in] メディア メジャー タイプを指定する REFCLSID。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

このメソッドは、C++ からのみ利用可能である。メソッド名にアンダスコアが 2 つ含まれるメソッドには、アンダスコアが 1 つ少ない同等のメソッドが存在し、後者ではパラメータに BSTR を使用する。

IComponentType::put_MediaSubType

IComponentType インターフェイス

DirectShow のメディア サブタイプを設定する。

構文

HRESULT put_MediaSubType(
    BSTR MediaSubType
    );

パラメータ

MediaSubType
[in] GUID を指定する BSTR。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IComponentType::put__MediaSubType

IComponentType インターフェイス

DirectShow のメディア サブタイプを設定する。

構文

HRESULT put__MediaSubType(
    REFCLSID MediaSubType
    );

パラメータ

MediaSubType
[in] メディア サブタイプを指定する REFCLSID。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

このメソッドは、C++ からのみ利用可能である。メソッド名にアンダスコアが 2 つ含まれるメソッドには、アンダスコアが 1 つ少ない同等のメソッドが存在し、後者ではパラメータに BSTR を使用する。

IComponentType::put_MediaType

IComponentType インターフェイス

コンポーネントの DirectShow AM_MEDIA_TYPE メディア タイプ構造体を設定する。

構文

HRESULT put_MediaType(
    AM_MEDIA_TYPE MediaType
    );

パラメータ

メディア タイプ
[in] メジャー タイプ、サブタイプ、フォーマットなどを指定する AM_MEDIA_TYPE 構造体。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。


IComponentTypes インターフェイス

ComponentTypes オブジェクトを使用すると、アプリケーションから個々の ComponentType オブジェクトを列挙、追加、削除、および取得できる。すべての ComponentTypes オブジェクトは、IPersistPropertyBag もサポートする。

メソッド名 | 説明
get_Count | コレクションに含まれる ComponentType の数を返す。
get__NewEnum | Automation クライアントの For...Each ループをサポートするための列挙メソッド。
EnumComponentTypes | コレクションに含まれるコンポーネント タイプをすべて列挙する IEnumComponentTypes 列挙子を返す。
get_Item | 指定されたインデックス位置の IComponentType インターフェイス ポインタを取得する。
put_Item | 指定されたインデックス位置の ComponentType オブジェクトを、新しい ComponentType オブジェクトに置き換える。
Add | コレクションに新しい ComponentType オブジェクトを追加する。
Remove | 指定されたインデックス位置の ComponentType オブジェクトを削除する。
Clone | コレクションの新しいコピーを作成する。

IComponentTypes::Clone

IComponentTypes インターフェイス

コレクションの新しいコピーを作成する。

構文

HRESULT Clone(
    IComponentTypes** NewList
    );

パラメータ

NewList
[out, retval] 新しい ComponentTypes オブジェクトにセットされる IComponentTypes インターフェイス ポインタのアドレス。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IComponentTypes::get_Count

IComponentTypes インターフェイス

コレクションに含まれる ComponentType の数を返す。

構文

HRESULT get_Count(
long* Count
    );

パラメータ

Count
[out, retval] コレクションに含まれる項目の数を受け取る Long 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IComponentTypes::get__NewEnum

IComponentTypes インターフェイス

Automation クライアントの For...Each ループをサポートするための列挙メソッド。

構文

HRESULT get__NewEnum(
IEnumVARIANT** ppNewEnum
    );

パラメータ

ppNewEnum
[out, retval] 新しいコレクションを受け取る IEnumVARIANT オブジェクトへのインターフェイス ポインタのアドレス。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

このメソッドは、For...Each ループの繰り返しによってコレクション全体を処理するため、スクリプト アプリケーションおよび VB アプリケーション用に提供される。C++ アプリケーションでは EnumComponents メソッドを使用すること。

IComponentTypes::EnumComponentTypes

IComponentTypes インターフェイス

コレクションに含まれるコンポーネント タイプをすべて列挙する IEnumComponentTypes 列挙子を返す。

構文

HRESULT EnumComponentTypes(
    IEnumComponentTypes** ppNewEnum
    );

パラメータ

ppNewEnum
[out, retval] 新しいコレクションを受け取る IEnumComponentTypes インターフェイス ポインタのアドレス。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IComponentTypes::get_Item

IComponentTypes インターフェイス

指定されたインデックス位置の IComponentType インターフェイス ポインタを取得する。

構文

HRESULT get_Item(
VARIANT Index,
    IComponentType** ppComponentType
    );

パラメータ

Index
[in] 取得するオブジェクトのインデックス番号。
ppComponentType
[out, retval] 指定されたインデックス位置のオブジェクトに設定する IComponentType インターフェイス ポインタのアドレス。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IComponentTypes::put_Item

IComponentTypes インターフェイス

指定されたインデックス位置の ComponentType オブジェクトを、新しい ComponentType オブジェクトに置き換える。

構文

HRESULT put_Item(
VARIANT Index,
    IComponentType* ComponentType
    );

パラメータ

Index
[in] 置き換える項目のインデックス番号。
ComponentType
[in] コレクションに挿入する IComponentType オブジェクトへのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IComponentTypes::Add

IComponentTypes インターフェイス

コレクションに新しい ComponentType オブジェクトを追加する。

構文

HRESULT Add(
    IComponentType* ComponentType,
VARIANT* NewIndex
    );

パラメータ

ComponentType
[in] コレクションに追加する IComponentType オブジェクトへのポインタ。
NewIndex
[out, retval] コレクションに追加された ComponentType のインデックス番号。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IComponentTypes::Remove

IComponentTypes インターフェイス

指定されたインデックス位置の ComponentType オブジェクトを削除する。

構文

HRESULT Remove(
VARIANT Index
    );

パラメータ

Index
[in] 削除する項目のインデックス。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。


IDVBSLocator インターフェイス

このインターフェイスは、DVBSLocator オブジェクトに実装され、チューナーが DVBS トランスポート ストリームを取得ために必要な情報を提供する。

ILocator メソッド名 | 説明
Clone | ロケータのコピーを作成する。
get_CarrierFrequency | RF 信号の周波数を取得する。
get_InnerFEC | 使用する内部前方誤り訂正のタイプを取得する。
get_InnerFECRate | 内部 FEC レートを取得する。
get_Modulation | 変調タイプを取得する。
get_OuterFEC | 使用する外部前方誤り訂正のタイプを取得する。
get_OuterFECRate | 外部 FEC レートを設定する。
get_SymbolRate | QPSK シンボル レートを取得する。
put_CarrierFrequency | RF 信号の周波数を設定する。
put_InnerFEC | 使用する内部前方誤り訂正のタイプを設定する。
put_InnerFECRate | 内部 FEC レートを設定する。
put_Modulation | 変調タイプを設定する。
put_OuterFEC | 使用する外部前方誤り訂正のタイプを設定する。
put_OuterFECRate | 外部 FEC レートを設定する。
put_SymbolRate | QPSK シンボル レートを設定する。
IDVBSLocator メソッド名 | 説明
get_Azimuth | 衛星アンテナの配置に使用する方位角設定を取得する。
get_Elevation | 衛星の仰角 (1/10°単位) を取得する。
get_OrbitalPosition | 衛星の軌道位置設定を取得する。
get_SignalPolarisation | 信号のポラリゼーションを取得する。
get_WestPosition | 軌道位置を西経と東経のどちらで表現するかを示す値を取得する。
put_Azimuth | 衛星アンテナの配置に使用する方位角設定を調整する。
put_Elevation | 衛星の仰角 (1/10°単位) を設定する。
put_OrbitalPosition | 衛星の軌道位置設定を設定する。
put_SignalPolarisation | 信号のポラリゼーションを設定する。
put_WestPosition | 経度を西経または東経で設定する。

IDVBSLocator::get_Azimuth

IDVBSLocator インターフェイス

衛星アンテナの配置に使用する方位角設定を取得する。

構文

HRESULT get_Azimuth(
    short* Azimuth
    );

パラメータ

Azimuth
[out, retval] 方位角 (1/10°単位) を受け取る Short 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IDVBSLocator::get_Elevation

IDVBSLocator インターフェイス

衛星の仰角 (1/10°単位) を取得する。

構文

HRESULT get_Elevation(
    short* Elevation
    );

パラメータ

Elevation
[out, retval] 仰角設定 (1/10°単位) を受け取る Short 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IDVBSLocator::get_OrbitalPosition

IDVBSLocator インターフェイス

衛星の軌道位置設定を取得する。

構文

HRESULT get_OrbitalPosition(
    short* longitude
    );

パラメータ

longitude
[out, retval] 経度設定 (1/10°単位) を受け取る Short 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IDVBSLocator::get_SignalPolarisation

IDVBSLocator インターフェイス

信号のポラリゼーションを取得する。

構文

HRESULT get_SignalPolarisation(
    Polarisation* PolarisationVal
    );

パラメータ

PolarisationVal
[out, retval] ポラリゼーション値を受け取る Polarisation 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。
Polarisation 列挙型は bdatypes.h に次のように定義されている。
    typedef enum {
        BDA_POLARISATION_NOT_SET = -1,
        BDA_POLARISATION_NOT_DEFINED = 0,
        BDA_POLARISATION_LINEAR_H = 1,
        BDA_POLARISATION_LINEAR_V = 2,
        BDA_POLARISATION_CIRCULAR_L = 3,
        BDA_POLARISATION_CIRCULAR_R = 4,
        BDA_POLARISATION_MAX = 5
    } Polarisation;

IDVBSLocator::get_WestPosition

IDVBSLocator インターフェイス

軌道位置を西経と東経のどちらで表現するかを示す値を取得する。

構文

HRESULT get_WestPosition(
    VARIANT_BOOL* WestLongitude
    );

パラメータ

WestLongitude
[out, retval] VARIANT_BOOL 型変数へのポインタ。真の値は "西経" を表す。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IDVBSLocator::put_Azimuth

IDVBSLocator インターフェイス

衛星アンテナの配置に使用する方位角設定を調整する。

構文

HRESULT put_Azimuth(
    short Azimuth
    );

パラメータ

Azimuth
[in] 方位角 (1/10°単位) を指定する Short 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IDVBSLocator::put_Elevation

IDVBSLocator インターフェイス

衛星の仰角 (1/10°単位) を設定する。

構文

HRESULT put_Elevation(
    short Elevation
    );

パラメータ

longitude
[in] ロケータのために衛星の仰角 (1/10°単位) を指定する Short 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IDVBSLocator::put_OrbitalPosition

IDVBSLocator インターフェイス

衛星の軌道位置設定を設定する。

構文

HRESULT put_OrbitalPosition(
    short longitude
    );

パラメータ

longitude
[in] 衛星の経度 (1/10°単位) を指定する Short 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IDVBSLocator::put_SignalPolarisation

IDVBSLocator インターフェイス

信号のポラリゼーションを設定する。

構文

HRESULT put_SignalPolarisation(
    Polarisation PolarisationVal
    );

パラメータ

PolarisationVal
[in] ポラリゼーション値を指定する Polarisation 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

Polarisation 列挙型は bdatypes.h に次のように定義されている。
    typedef enum {
        BDA_POLARISATION_NOT_SET = -1,
        BDA_POLARISATION_NOT_DEFINED = 0,
        BDA_POLARISATION_LINEAR_H = 1,
        BDA_POLARISATION_LINEAR_V = 2,
        BDA_POLARISATION_CIRCULAR_L = 3,
        BDA_POLARISATION_CIRCULAR_R = 4,
        BDA_POLARISATION_MAX = 5
    } Polarisation;

IDVBSLocator::put_WestPosition

IDVBSLocator インターフェイス

経度を西経または東経で設定する。

構文

HRESULT put_WestPosition(
    VARIANT_BOOL WestLongitude
    );

パラメータ

WestLongitude
[in] これから経度を西経と東経のどちらで表現するかを指定する VARIANT_BOOL 型変数。真の値は "西経" を表す。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。


IDVBTLocator インターフェイス

このインターフェイスは、DVBTLocator オブジェクトに実装され、チューナーが DVBT トランスポート ストリームを取得するために必要な情報を提供する。データ型は bdatypes.h に定義されている。(Microsoft® DirectX® 8 SDK に同梱されるバージョンの Broadcast Architecture では、DVB-T がサポートされない)

ILocator メソッド名 | 説明
Clone | ロケータのコピーを作成する。
get_CarrierFrequency | RF 信号の周波数を取得する。
get_InnerFEC | 使用する内部前方誤り訂正のタイプを取得する。
get_InnerFECRate | 内部 FEC レートを取得する。
get_Modulation | 変調タイプを取得する。
get_OuterFEC | 使用する外部前方誤り訂正のタイプを取得する。
get_OuterFECRate | 外部 FEC レートを設定する。
get_SymbolRate | QPSK シンボル レートを取得する。
put_CarrierFrequency | RF 信号の周波数を設定する。
put_InnerFEC | 使用する内部前方誤り訂正のタイプを設定する。
put_InnerFECRate | 内部 FEC レートを設定する。
put_Modulation | 変調タイプを設定する。
put_OuterFEC | 使用する外部前方誤り訂正のタイプを設定する。
put_OuterFECRate | 外部 FEC レートを設定する。
put_SymbolRate | QPSK シンボル レートを設定する。
IDVBTLocator メソッド名 | 説明
get_Bandwidth | 周波数の帯域幅 (MHz) を取得する。通常は 7 または 8。
get_Guard | ガード間隔を取得する。
get_HAlpha | 階層状アルファを取得する。
get_LPInnerFEC | 優先度が低いストリームの内部 FEC タイプを取得する。
get_LPInnerFECRate | 優先度が低いストリームの内部 FEC レートを取得する。
get_Mode | 伝送モードを取得する。
get_OtherFrequencyInUse | その周波数が別の DVB-T ブロードキャスタで使用されているかどうかを調べる。
put_Bandwidth | 周波数の帯域幅 (MHz) を設定する。通常は 7 または 8。
put_Guard | ガード間隔を設定する。
put_HAlpha | 階層状アルファを設定する。
put_LPInnerFEC | 優先度が低いストリームの内部 FEC タイプを設定する。
put_LPInnerFECRate | 優先度が低いストリームの内部 FEC レートを設定する。
put_Mode | 伝送モード設定する。
put_OtherFrequencyInUse | その周波数が別の DVB-T ブロードキャスタで使用されているかどうかを指定する。

IDVBTLocator::get_Bandwidth

IDVBTLocator インターフェイス

周波数の帯域幅 (MHz) を取得する。通常は 7 または 8。

構文

HRESULT get_Bandwidth(
    long* BandWidthVal
    );

パラメータ

BandWidthVal
[out, retval] 帯域幅の値を受け取る Long 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IDVBTLocator::get_Guard

IDVBTLocator インターフェイス

ガード間隔を取得する。

構文

HRESULT get_Guard(
    GuardInterval* GI
    );

パラメータ

GI
[out, retval] 有効な GuardInterval 値を受け取るポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

typedef enum GuardInterval {
    BDA_GUARD_NOT_SET = -1,
    BDA_GUARD_NOT_DEFINED = 0,
    BDA_GUARD_1_32 = 1, // ガード間隔は 1/32
    BDA_GUARD_1_16, // ガード間隔は 1/16
    BDA_GUARD_1_8, // ガード間隔は 1/8
    BDA_GUARD_1_4, // ガード間隔は 1/4
    BDA_GUARD_MAX,
} GuardInterval;

IDVBTLocator::get_HAlpha

IDVBTLocator インターフェイス

階層状アルファを取得する。

構文

HRESULT get_HAlpha(
    HierarchyAlpha* Alpha
    );

パラメータ

Alpha
[out, retval] HierarchyAlpha 列挙型に属する値。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

typedef enum HierarchyAlpha {
BDA_HALPHA_NOT_SET = -1,
BDA_HALPHA_NOT_DEFINED = 0,
BDA_HALPHA_1 = 1, // 階層状アルファは 1。
BDA_HALPHA_2, // 階層状アルファは 2。
BDA_HALPHA_4, // 階層状アルファは 4。
BDA_HALPHA_MAX,
} HierarchyAlpha;

IDVBTLocator::get_LPInnerFEC

IDVBTLocator インターフェイス

優先度が低いストリームの内部 FEC タイプを取得する。

構文

HRESULT get_LPInnerFEC(
FECMethod* FEC
    );

パラメータ

FEC
[out, retval] FEC タイプを受け取る FECMethod 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IDVBTLocator::get_LPInnerFECRate

IDVBTLocator インターフェイス

優先度が低いストリームの内部 FEC レートを取得する。

構文

HRESULT get_LPInnerFECRate(
BinaryConvolutionCodeRate* FEC
    );

パラメータ

FEC
[out, retval] 内部 FEC レートを受け取る BinaryConvolutionCodeRate 値へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

BinaryConvolutionCodeRate は bdatypes.h に次のように定義されている。

typedef enum {
BDA_BCC_RATE_NOT_SET = -1,
BDA_BCC_RATE_NOT_DEFINED = 0,
BDA_BCC_RATE_1_2 = 1,
BDA_BCC_RATE_2_3 = 2,
BDA_BCC_RATE_3_4 = 3,
BDA_BCC_RATE_3_5 = 4,
BDA_BCC_RATE_4_5 = 5,
BDA_BCC_RATE_5_6 = 6,
BDA_BCC_RATE_5_11 = 7,
BDA_BCC_RATE_7_8 = 8,
BDA_BCC_RATE_MAX = 9
} BinaryConvolutionCodeRate;

IDVBTLocator::get_Mode

IDVBTLocator インターフェイス

伝送モードを取得する。

構文

HRESULT get_Mode(
    TransmissionMode* mode
    );

パラメータ

mode
[out, retval] TransmissionMode 列挙型に属する値。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

typedef enum TransmissionMode {
    BDA_XMIT_MODE_NOT_SET = -1,
    BDA_XMIT_MODE_NOT_DEFINED = 0,
    BDA_XMIT_MODE_2K = 1, // 伝送に 1705 キャリアを使用する (2K FFT を使用)
    BDA_XMIT_MODE_8K, // 伝送に 6817 キャリアを使用する (8K FFT を使用)
    BDA_XMIT_MODE_MAX,
} TransmissionMode;

IDVBTLocator::get_OtherFrequencyInUse

IDVBTLocator インターフェイス

その周波数が別の DVB-T ブロードキャスタで使用されているかどうかを調べる。

構文

HRESULT get_OtherFrequencyInUse(
    VARIANT_BOOL* OtherFrequencyInUseVal
    );

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IDVBTLocator::put_Bandwidth

IDVBTLocator インターフェイス

周波数の帯域幅 (MHz) を設定する。通常は 7 または 8。

構文

HRESULT put_Bandwidth(
    long BandwidthVal
    );

パラメータ

BandwidthVal
[in] 帯域幅を指定する Long 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IDVBTLocator::put_Guard

IDVBTLocator インターフェイス

ガード間隔を設定する。

構文

HRESULT put_Guard(
    GuardInterval GI
    );

パラメータ

GI
[in] ガード間隔を指定する GuardInterval 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IDVBTLocator::put_HAlpha

IDVBTLocator インターフェイス

階層状アルファを設定する。

構文

HRESULT put_HAlpha(
    HierarchyAlpha Alpha
    );

パラメータ

Alpha
[in] 階層状アルファを指定する HierarchyAlpha 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

typedef enum HierarchyAlpha {
BDA_HALPHA_NOT_SET = -1,
BDA_HALPHA_NOT_DEFINED = 0,
BDA_HALPHA_1 = 1, // 階層状アルファは 1。
BDA_HALPHA_2, // 階層状アルファは 2。
BDA_HALPHA_4, // 階層状アルファは 4。
BDA_HALPHA_MAX,
} HierarchyAlpha;

IDVBTLocator::put_LPInnerFEC

IDVBTLocator インターフェイス

優先度が低いストリームの内部 FEC タイプを設定する。

構文

HRESULT put_LPInnerFEC(
FECMethod FEC
    );

パラメータ

FEC
[in] FEC タイプを指定する FECMethod 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IDVBTLocator::put_LPInnerFECRate

IDVBTLocator インターフェイス

優先度が低いストリームの内部 FEC レートを設定する。

構文

HRESULT put_LPInnerFECRate(
BinaryConvolutionCodeRate FEC
    );

パラメータ

FEC
[in] レートを指定する BinaryConvolutionCodeRate 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IDVBTLocator::put_Mode

IDVBTLocator インターフェイス

伝送モード設定する。

構文

HRESULT put_Mode(
    TransmissionMode mode
    );

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IDVBTLocator::put_OtherFrequencyInUse

IDVBTLocator インターフェイス

その周波数が別の DVB-T ブロードキャスタで使用されているかどうかを指定する。

構文

HRESULT put_OtherFrequencyInUse(
    VARIANT_BOOL OtherFrequencyInUseVal
    );

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。


IDVBTuneRequest インターフェイス

このインターフェイスは、DVBTuneRequest オブジェクトに実装される。

ITuneRequest メソッド名 | 説明
get_TuningSpace | チューニング空間オブジェクトを取得する。
get_Components | IComponent オブジェクトのコレクションを取得する。
Clone | このチューニング要求の新しいコピーを返す。
get_Locator | ネットワーク プロバイダから呼び出され、要求されたブロードキャストに関連付けられた ILocator オブジェクトを取得する。
put_Locator | ネットワーク プロバイダから呼び出され、要求されたブロードキャストに関連付けられた ILocator オブジェクトを設定する。
IDVBTuneRequest メソッド名 | 説明
get_ONID | 元のネットワーク ID を取得する。
get_SID | サービス ID を設定する。
get_TSID | トランスポート ストリーム ID を取得する。
put_ONID | 元のネットワーク ID を設定する。
put_SID | サービス ID を取得する。
put_TSID | トランスポート ストリーム ID を設定する。

IDVBTuneRequest::get_ONID

IDVBTuneRequest インターフェイス

元のネットワーク ID を取得する。

構文

HRESULT get_ONID(
    short* ONID
    );

パラメータ

ONID
[out, retval] 元のネットワーク ID を受け取る Short 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IDVBTuneRequest::get_SID

IDVBTuneRequest インターフェイス

ネットワークのサービス ID を取得する。

構文

HRESULT get_SID(
    short* SID
    );

パラメータ

SID
[out, retval] サービス ID を受け取る Short 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IDVBTuneRequest::get_TSID

IDVBTuneRequest インターフェイス

トランスポート ストリーム ID を取得する。

構文

HRESULT get_TSID(
short* TSID
    );

パラメータ

TSID
[out, retval] トランスポート ストリーム ID を受け取る Short 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IDVBTuneRequest::put_ONID

IDVBTuneRequest インターフェイス

元のネットワーク ID を設定する。

構文

HRESULT put_ONID(
    short ONID
    );

パラメータ

ONID
[in] 元のネットワーク ID を指定する Short 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IDVBTuneRequest::put_SID

IDVBTuneRequest インターフェイス

サービス ID を設定する。

構文

HRESULT put_SID(
    short SID
    );

パラメータ

SID
[in] サービス ID を指定する Short 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IDVBTuneRequest::put_TSID

IDVBTuneRequest インターフェイス

トランスポート ストリーム ID を設定する。

構文

HRESULT put_TSID(
short TSID
    );

パラメータ

TSID
[in] トランスポート ストリーム ID を指定する Short 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。


IDVBTuningSpace インターフェイス

このインターフェイスは、DVBTuningSpace オブジェクトに実装される。

メソッド名 | 説明
ITuningSpace メソッド
get_UniqueName | チューニング空間の固有の名称を取得する。固有の名称は略称か GUID である。
put_UniqueName | チューニング空間の固有の名称を設定する。固有の名称は略称か GUID である。
get_FriendlyName | チューニング空間のローカライズされたフレンドリ名を取得する。
put_FriendlyName | チューニング空間のローカライズされたフレンドリ名を設定する。
get_CLSID | チューニング空間の CLSID を BSTR として取得する。
get_NetworkType | チューニング空間のネットワーク タイプ GUID を BSTR として取得する。
put_NetworkType | このチューニング空間のネットワーク タイプを BSTR として設定する。
get__NetworkType | チューニング空間のネットワーク タイプを GUID として取得する。
put__NetworkType | このチューニング空間のネットワーク タイプを REFCLSID として設定する。
CreateTuneRequest | 空の (初期化されていない) チューニング要求を表す COM オブジェクトを作成する。
EnumCategoryGUIDs | (現時点では未実装) DirectShow カテゴリ GUID を列挙する列挙子を作成する。カテゴリ GUID は、チューニング空間をサポートするフィルタの種類を表すものである。
EnumDeviceMonikers | (現時点では未実装) このチューニング空間をサポートするチューナー入力 (フィルタ) を表すデバイス モニカの列挙子を作成する。
get_DefaultPreferredComponentTypes | 優先コンポーネント タイプのリストを返す。優先コンポーネント タイプは、優先オーディオ ストリームなどのパラメータを指定するものである。
put_DefaultPreferredComponentTypes | 優先コンポーネント タイプのリストを作成する。優先コンポーネント タイプは、優先オーディオ ストリームなどのパラメータを指定するものである。
get_FrequencyMapping | ネットワーク プロバイダが put_FrequencyMapping を呼び出して直前に作成した周波数マッピングを取得する。
put_FrequencyMapping | 周波数とチャンネルのマッピング、周波数と中継器のマッピング、またはキャリア周波数から周波数識別子への、チューニング空間に適したその他のあらゆるマッピングを作成する。
get_DefaultLocator | ローカル システムのデフォルト ロケータを取得する。
put_DefaultLocator | ローカル システムのデフォルト ロケータを設定する。
IDVBTuningSpace メソッド
get_SystemType | DVB のシステム タイプを取得する。
put_SystemType | DVB のシステム タイプを設定する。

IDVBTuningSpace::get_SystemType

IDVBTuningSpace インターフェイス

システム タイプを取得する。

構文

HRESULT get_SystemType(
    DVBSystemType* SysType
    );

パラメータ

SysType
[out, retval] システム タイプを受け取る DVDSystemType 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

typedef enum DVBSystemType {
DVB_Cable,
DVB_Terrestrial,
DVB_Satellite,
} DVBSystemType;

IDVBTuningSpace::put_SystemType

IDVBTuningSpace インターフェイス

システム タイプを設定する。

構文

HRESULT put_SystemType(
    DVBSystemType SysType
    );

パラメータ

SysType
[in] システム タイプを指定する DVDSystemType 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

typedef enum DVBSystemType {
DVB_Cable,
DVB_Terrestrial,
DVB_Satellite,
} DVBSystemType;


IEnumComponents インターフェイス

IEnumComponents インターフェイスは、所定のプログラム ストリームに含まれるコンポーネント (サブストリーム) に対応する標準 COM 列挙オブジェクトを提供する。C++ アプリケーションから特定のプログラム ストリームに含まれる Component オブジェクトを列挙するには、IComponents ではなく、このインターフェイスを使用すること。

メソッド名 | 説明
Next | コレクションの次から始まる n 個の要素を取得する。
Skip | コレクションに含まれる指定された要素をスキップする (取得しない)。
Reset | 列挙子をコレクション先頭に戻す。
Clone | コレクション全体の新しいコピーを作成する。

IEnumComponents::Next

IEnumComponents インターフェイス

コレクションの次から始まる n 個の要素を取得する。

構文

HRESULT Next(
ULONG celt,
    IComponent** rgelt,
ULONG* pceltFetched
    );

パラメータ

celt
[in] 取得する要素数を指定する ULONG 型変数。
rgelt
[out, size_is(celt), length_is(*pceltFetched)] 取得した Component オブジェクトを受け取る IComponent インターフェイス ポインタ配列のアドレス。
pceltFetched
[out] 実際に取得した要素数を受け取る ULONG 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IEnumComponents::Skip

IEnumComponents インターフェイス

コレクションに含まれる指定された要素をスキップする (取得しない)。

構文

HRESULT Skip(
ULONG celt
    );

パラメータ

celt
[in] スキップする要素を指定する ULONG 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IEnumComponents::Reset

IEnumComponents インターフェイス

列挙子をコレクション先頭に戻す。

構文

HRESULT Reset();

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IEnumComponents::Clone

IEnumComponents インターフェイス

コレクション全体の新しいコピーを作成する。

構文

HRESULT Clone(
    IEnumComponents** ppEnum
    );

パラメータ

ppEnum
[out] 新しいコレクションに設定する IEnumComponents インターフェイス ポインタのアドレス。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

新しいコレクションは、使用後にアプリケーション側で解放する必要がある。


IEnumComponentTypes インターフェイス

このインターフェイスは、所定のブロードキャスト ストリームに関連付けられた ComponentType オブジェクトの標準 COM コレクションに実装され、IComponentTypes::EnumComponentTypes の呼び出しを通じて返される。

メソッド名 | 説明
Clone | コレクション全体とそのサブオブジェクトすべての新しいコピーを作成する。
Next | コレクションの次から始まる n 個の要素を取得する。
Reset | 反復子をコレクション先頭に戻す。
Skip | 指定されたインデックス位置の要素をスキップする。

IEnumComponentTypes::Clone

IEnumComponentTypes インターフェイス

コレクションとそのサブオブジェクトすべての新しいコピーを作成する。

構文

HRESULT Clone(
    IEnumComponentTypes** ppEnum
    );

パラメータ

ppEnum
[out] 返されるコレクション オブジェクトに設定する IEnumComponentTypes インターフェイス ポインタのアドレス。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IEnumComponentTypes::Next

IEnumComponentTypes インターフェイス

コレクションの次から始まる n 個の要素を取得する。

構文

HRESULT Next(
ULONG celt,
    IComponentType** rgelt,
ULONG* pceltFetched
    );

パラメータ

celt
[in] 取得する要素数。
rgelt
[out, size_is(celt), length_is(*pceltFetched)] 返された ComponentType オブジェクトを受け取る IComponentType インターフェイス ポインタ配列のアドレス。
pceltFetched
[out] 実際に取得した要素数を受け取る ULONG 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IEnumComponentTypes::Reset

IEnumComponentTypes インターフェイス

反復子をコレクション先頭に戻す。

構文

HRESULT Reset();

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IEnumComponentTypes::Skip

IEnumComponentTypes インターフェイス

指定されたインデックス位置の要素をスキップする。

構文

HRESULT Skip(
ULONG celt
    );

パラメータ

celt
[in] スキップする要素のインデックス。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。


IEnumTuningSpaces インターフェイス

このインターフェイスは、ローカル システム上のチューニング空間オブジェクトの標準 COM コレクションに実装され、ITuningSpaceContainer::EnumTuningSpaces の呼び出しを通じて返される。

メソッド名 | 説明
Next | コレクションの次から始まる n 個の要素を取得する。
Skip | コレクションに含まれる指定された要素をスキップする。
Reset | 反復子をコレクション先頭に戻す。
Clone | コレクションとそのサブオブジェクトすべての新しいコピーを作成する。

IEnumTuningSpaces::Next

IEnumTuningSpaces インターフェイス

コレクションの次から始まる n 個の要素を取得する。

構文

HRESULT Next(
ULONG celt,
    ITuningSpace** rgelt,
ULONG* pceltFetched
    );

パラメータ

celt
[in] 取得する要素数。
rgelt
[out, size_is(celt), length_is(*pceltFetched)] 取得したチューニング空間オブジェクトを受け取る ITuningSpace インターフェイス ポインタ配列のアドレス。
pceltFetched
[out] 実際に取得した要素数を受け取る ULONG 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。このメソッドは、celt が 0 でも成功する。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IEnumTuningSpaces::Skip

IEnumTuningSpaces インターフェイス

コレクションに含まれる指定された要素をスキップする。

構文

HRESULT Skip(
ULONG celt
    );

パラメータ

celt
[in] スキップする要素のインデックス。

戻り値

成功した場合は、S_OK を返す。このメソッドは、celt が 0 でも成功する。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IEnumTuningSpaces::Reset

IEnumTuningSpaces インターフェイス

反復子をコレクション先頭に戻す。

構文

HRESULT Reset();

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IEnumTuningSpaces::Clone

IEnumTuningSpaces インターフェイス

コレクションとそのサブオブジェクトすべての新しいコピーを作成する。

構文

HRESULT Clone(
IEnumTuningSpaces** ppEnum
    );

パラメータ

ppEnum
[out] 返されたインターフェイスを受け取る IEnumTuningSpaces インターフェイス ポインタのアドレス。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。


ILocator インターフェイス

ILocator 基底クラス インターフェイスは、チューニング空間に関する情報が格納されたロケータ オブジェクトに、その派生インターフェイス (IATSCLocator など) を通じて実装される。ロケータ オブジェクトは、通常、チューナーによるトランスポート ストリームの検索および取得を助けるため、ネットワーク プロバイダが使用する。デバッグを目的とする場合を除き、アプリケーションでロケータ オブジェクトを使用することはない。すべてのロケータ オブジェクトは、IPersistPropertyBag もサポートする。

メソッド名 | 説明
Clone | ロケータのコピーを作成する。
get_CarrierFrequency | RF 信号の周波数を取得する。
get_InnerFEC | 使用する内部前方誤り訂正のタイプを取得する。
get_InnerFECRate | 内部 FEC レートを取得する。
get_Modulation | 変調タイプを取得する。
get_OuterFEC | 使用する外部前方誤り訂正のタイプを取得する。
get_OuterFECRate | 外部 FEC レートを設定する。
SymbolRate | QPSK シンボル レートを取得する。
put_CarrierFrequency | RF 信号の周波数を設定する。
put_InnerFEC | 使用する内部前方誤り訂正のタイプを設定する。
put_InnerFECRate | 内部 FEC レートを設定する。
put_Modulation | 変調タイプを設定する。
put_OuterFEC | 使用する外部前方誤り訂正のタイプを設定する。
put_OuterFECRate | 外部 FEC レートを設定する。
SymbolRate | QPSK シンボル レートを設定する。

ILocator::Clone

ILocator インターフェイス

ロケータのコピーを作成する。

構文

HRESULT Clone(
    ILocator **NewLocator
    );

パラメータ

NewLocator
[out, retval] 返されたインターフェイスを受け取る ILocator インターフェイス ポインタのアドレス。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

ILocator::get_CarrierFrequency

ILocator インターフェイス

RF 信号の周波数を取得する。

構文

HRESULT get_CarrierFrequency(
    long* Frequency
    );

パラメータ

Frequency
[out, retval] 周波数の値を受け取る Long 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

ILocator::get_InnerFEC

ILocator インターフェイス

使用する前方誤り訂正のタイプを取得する。

構文

HRESULT get_InnerFEC(
FECMethod* FEC
    );

パラメータ

FEC
[out, retval] 内部 FEC のタイプを受け取る FECMethod 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

FECMethod は bdatypes.h に次のように定義されている。
typedef enum FECMethod {
    BDA_FEC_METHOD_NOT_SET = -1,
    BDA_FEC_METHOD_NOT_DEFINED = 0,
    BDA_FEC_VITERBI = 1,      // FEC はヴィテルビ 2 進たたみ込み法。
    BDA_FEC_RS_204_188,       // FEC はリ－ド-ソロモン 204/188 (外部 FEC)。
    BDA_FEC_MAX,
} FECMethod;

ILocator::get_InnerFECRate

ILocator インターフェイス

内部 FEC レートを取得する。

構文

HRESULT get_InnerFECRate(
BinaryConvolutionCodeRate* FEC
    );

パラメータ

FEC
[out, retval] 内部 FEC レートを受け取る BinaryConvolutionCodeRate 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

BinaryConvolutionCodeRate は bdatypes.h に次のように定義されている。

typedef enum {
BDA_BCC_RATE_NOT_SET = -1,
BDA_BCC_RATE_NOT_DEFINED = 0,
BDA_BCC_RATE_1_2 = 1,
BDA_BCC_RATE_2_3 = 2,
BDA_BCC_RATE_3_4 = 3,
BDA_BCC_RATE_3_5 = 4,
BDA_BCC_RATE_4_5 = 5,
BDA_BCC_RATE_5_6 = 6,
BDA_BCC_RATE_5_11 = 7,
BDA_BCC_RATE_7_8 = 8,
BDA_BCC_RATE_MAX = 9
} BinaryConvolutionCodeRate;

ILocator::get_Modulation

ILocator インターフェイス

変調タイプを取得する。

構文

HRESULT get_Modulation(
    ModulationType* Modulation
    );

パラメータ

Modulation
[out, retval] 新しい変調タイプを受け取るポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

ModulationType の定義については、「put_Modulation」を参照すること。

ILocator::get_OuterFEC

ILocator インターフェイス

使用する外部前方誤り訂正のタイプを取得する。

構文

HRESULT get_OuterFEC(
FECMethod* FEC
    );

パラメータ

FEC
[out, retval] 外部 FEC を受け取る FECMethod 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

FECMethod の定義については、「get_InnerFEC」を参照すること。

ILocator::get_OuterFECRate

ILocator インターフェイス

外部 FEC レートを取得する。

構文

HRESULT get_OuterFECRate(
BinaryConvolutionCodeRate* FEC
    );

パラメータ

FEC
[out, retval] 外部 FEC レートを受け取る BinaryConvolutionCodeRate 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

ILocator::get_SymbolRate

ILocator インターフェイス

QPSK シンボルレートを取得する。

構文

HRESULT get_SymbolRate(
    long* Rate
    );

パラメータ

Rate
[out, retval] QPSK レートを受け取るlong 型変数へのポインタ。

Return Value

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

QPSK は RF 信号にシンボルを変調する。これらのシンボルは復調器によって検出され、ビット ストリームを再構築するのに使われる。OPSK は変更のために変調/復調されるレートを許可する。

ILocator::put_CarrierFrequency

ILocator インターフェイス

RF 信号の周波数を設定する。

構文

HRESULT put_CarrierFrequency(
    long Frequency
    );

パラメータ

Frequency
[in] 周波数の値を指定する Long 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

ILocator::put_InnerFEC

ILocator インターフェイス

使用する内部前方誤り訂正のタイプを設定する。

構文

HRESULT put_InnerFEC(
FECMethod FEC
    );

パラメータ

FEC
[in] 内部 FEC のタイプを指定する FECMethod 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

ILocator::put_InnerFECRate

ILocator インターフェイス

内部 FEC レートを設定する。

構文

HRESULT put_InnerFECRate(
BinaryConvolutionCodeRate FEC
    );

パラメータ

FEC
[in] 内部 FEC レートを指定する BinaryConvolutionCodeRate 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

ILocator::put_Modulation

ILocator インターフェイス

変調タイプを設定する。

構文

HRESULT put_Modulation(
    ModulationType Modulation
    );

パラメータ

Modulation
[in] 変調タイプを指定する。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

ModulationType 列挙型は bdatypes.h に次のように定義されている。
typedef enum {
    BDA_MOD_NOT_SET = -1,
    BDA_MOD_NOT_DEFINED = 0,
    BDA_MOD_16QAM = 1,
    BDA_MOD_32QAM = 2,
    BDA_MOD_64QAM = 3,
    BDA_MOD_80QAM = 4,
    BDA_MOD_96QAM = 5,
    BDA_MOD_112QAM = 6,
    BDA_MOD_128QAM = 7,
    BDA_MOD_160QAM = 8,
    BDA_MOD_192QAM = 9,
    BDA_MOD_224QAM = 10,
    BDA_MOD_256QAM = 11,
    BDA_MOD_320QAM = 12,
    BDA_MOD_384QAM = 13,
    BDA_MOD_448QAM = 14,
    BDA_MOD_512QAM = 15,
    BDA_MOD_640QAM = 16,
    BDA_MOD_768QAM = 17,
    BDA_MOD_896QAM = 18,
    BDA_MOD_1024QAM = 19,
    BDA_MOD_QPSK = 20,
    BDA_MOD_BPSK = 21,
    BDA_MOD_OQPSK = 22,
    BDA_MOD_8VSB = 23,
    BDA_MOD_16VSB = 24,
    BDA_MOD_ANALOG_AMPLITUDE = 25,
    BDA_MOD_ANALOG_FREQUENCY = 26,
    BDA_MOD_MAX = 27
} ModulationType;

ILocator::put_OuterFEC

ILocator インターフェイス

使用する外部前方誤り訂正のタイプを設定する。

構文

HRESULT put_OuterFEC(
FECMethod FEC
    );

パラメータ

FEC
[in] 外部前方誤り訂正のタイプを指定する FECMethod 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

ILocator::put_OuterFECRate

ILocator インターフェイス

外部 FEC レートを設定する。

構文

HRESULT put_OuterFECRate(
BinaryConvolutionCodeRate FEC
    );

パラメータ

FEC
[in] 外部 FEC レートを指定する BinaryConvolutionCodeRate 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

BinaryConvolutionCodeRate は bdatypes.h に次のように定義されている。
typedef enum {
BDA_BCC_RATE_NOT_SET = -1,
BDA_BCC_RATE_NOT_DEFINED = 0,
BDA_BCC_RATE_1_2 = 1,
BDA_BCC_RATE_2_3 = 2,
BDA_BCC_RATE_3_4 = 3,
BDA_BCC_RATE_3_5 = 4,
BDA_BCC_RATE_4_5 = 5,
BDA_BCC_RATE_5_6 = 6,
BDA_BCC_RATE_5_11 = 7,
BDA_BCC_RATE_7_8 = 8,
BDA_BCC_RATE_MAX = 9
} BinaryConvolutionCodeRate;

ILocator::put_SymbolRate

ILocator インターフェイス

QPSK シンボル レートを設定する。

構文

HRESULT put_SymbolRate(
    long Rate
    );

パラメータ

Rate
[in] QPSK レートを指定するlong 型変数へのポインタ

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

QPSK は RF 信号にシンボルを変調する。これらのシンボルは復調器によって検出され、ビット ストリームを再構築するのに使われる。OPSK は変更のために変調/復調されるレートを許可する。


ILanguageComponentType インターフェイス

ILanguageComponentType インターフェイスは、ストリーム コンテンツの言語を定義する LanguageComponentType オブジェクトに実装される。すべてのストリームに言語コンポーネントがあるとは限らない。

メソッド名 | 説明
get_LangID | ストリーム コンテンツの言語を取得する。
put_LangID | ストリーム コンテンツの言語を設定する。

ILanguageComponentType::get_LangID

ILanguageComponentType インターフェイス

言語を識別する LCID を取得する。

構文

HRESULT get_LangID(
short* LangID
    );

パラメータ

LangID
[out, retval] LCID を受け取る Short 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

LangID は Win32 の LANGID である。IComponent 基底クラス インターフェイスには、説明の言語を定義する別の言語 ID がある。

ILanguageComponentType::put_LangID

ILanguageComponentType インターフェイス

言語を識別する LCID を指定する。

構文

HRESULT put_LangID(
short LangID
    );

パラメータ

LangID
[in] LCID を指定する Short 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。


IMPEG2Component インターフェイス

IMPEG2Component インターフェイスは、MPEG2 基本ストリームに関するプロパティを取得および設定するためのメソッドを提供する。

IComponent メソッド名 | 説明
get_Type | コンポーネントの一般的な特性を記述する IComponentType オブジェクトを取得する。
put_Type | コンポーネントの一般的な特性を記述する IComponentType オブジェクトを設定する。
get_DescLangID | 説明のプレゼンテーションに使用する言語を取得する。
put_DescLangID | 説明のプレゼンテーションに使用する言語を設定する。
get_Status | コンポーネントの要求された状態または実際の状態を取得する。
put_Status | コンポーネントの要求された状態または実際の状態を設定する。
get_Description | コンポーネントの説明を取得する。
put_Description | コンポーネントの説明を設定する。
Clone | コンポーネントの新しいコピーを作成する。
IMPEG2Component メソッド名 | 説明
get_PCRPID | このサブストリームのタイム スタンプに対応する MPEG2 パケット ID を返す。
get_PID | このサブストリームのパケット識別子を取得する。
get_ProgramNumber | PAT の逆引き参照に使用するプログラム番号を取得する。
put_PCRPID | このサブストリームのタイム スタンプに対応する MPEG2 パケット ID を設定する。
put_PID | このサブストリームのパケット識別子を設定する。
put_ProgramNumber | PAT の逆引き参照に使用するプログラム番号を取得する。

IMPEG2Component::get_PCRPID

IMPEG2Component インターフェイス

このサブストリームのタイム スタンプに対応する MPEG2 パケット ID を返す。

構文

HRESULT get_PCRPID(
    short *PCRPID
    );

パラメータ

PCRPID
[out, retval] パケット ID の値を受け取る Short 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IMPEG2Component::get_PID

IMPEG2Component インターフェイス

このサブストリームのパケット識別子を取得する。

構文

HRESULT get_PID(
    short *PID
    );

パラメータ

PID
[out, retval] パケット識別子を受け取る Short 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IMPEG2Component::get_ProgramNumber

IMPEG2Component インターフェイス

PAT の逆引き参照に使用するプログラム番号を取得する。

構文

HRESULT get_ProgramNumber(
    short *ProgramNumber
    );

パラメータ

ProgramNumber
[out, retval] プログラム番号を受け取る Short 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IMPEG2Component::put_PCRPID

IMPEG2Component インターフェイス

このサブストリームのタイム スタンプに対応する MPEG2 パケット ID を設定する。

構文

HRESULT put_PCRPID(
    short PCRPID
    );

パラメータ

PCRPID
[in] パケット ID を指定する Short 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IMPEG2Component::put_PID

IMPEG2Component インターフェイス

このサブストリームのパケット識別子を設定する。

構文

HRESULT put_PID(
    short PID
    );

パラメータ

PID
[in] パケット識別子を指定する Short 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

IMPEG2Component::put_ProgramNumber

IMPEG2Component インターフェイス

PAT の逆引き参照に使用するプログラム番号を設定する。

構文

HRESULT put_ProgramNumber(
    short ProgramNumber
    );

パラメータ

ProgramNumber
[in] プログラム番号を指定する Short 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。


IMPEG2ComponentType インターフェイス

このインターフェイスは、IComponentLanguageType を継承し、IMPEG2ComponentType オブジェクトに実装される。アプリケーションでは、このインターフェイスを使って MPEG2 のストリーム タイプに関する情報を設定および取得できる。

メソッド名 | 説明
get_StreamType | ストリーム タイプを取得する。
put_StreamType | ストリーム タイプを設定する。

IMPEG2ComponentType::get_StreamType

IMPEG2ComponentType インターフェイス

ストリーム タイプを取得する。

構文

HRESULT get_StreamType(
    MPEG2StreamType* MP2StreamType
    );

パラメータ

MP2StreamType
[out, retval] ストリーム タイプの値を受け取る MPEG2StreamType 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

typedef enum MPEG2StreamType {
        BDA_UNITIALIZED_MPEG2STREAMTYPE = -1,
    Reserved1 = 0x0,
    ISO_IEC_11172_2_VIDEO	= Reserved1 + 1,
    ISO_IEC_13818_2_VIDEO	= ISO_IEC_11172_2_VIDEO + 1,
    ISO_IEC_11172_3_AUDIO	= ISO_IEC_13818_2_VIDEO + 1,
    ISO_IEC_13818_3_AUDIO	= ISO_IEC_11172_3_AUDIO + 1,
    ISO_IEC_13818_1_PRIVATE_SECTION = ISO_IEC_13818_3_AUDIO + 1,
    ISO_IEC_13818_1_PES		= ISO_IEC_13818_1_PRIVATE_SECTION + 1,
    ISO_IEC_13522_MHEG		= ISO_IEC_13818_1_PES + 1,
    ANNEX_A_DSM_CC			= ISO_IEC_13522_MHEG + 1,
    ITU_T_REC_H_222_1		= ANNEX_A_DSM_CC + 1,
    ISO_IEC_13818_6_TYPE_A	= ITU_T_REC_H_222_1 + 1,
    ISO_IEC_13818_6_TYPE_B	= ISO_IEC_13818_6_TYPE_A + 1,
    ISO_IEC_13818_6_TYPE_C	= ISO_IEC_13818_6_TYPE_B + 1,
    ISO_IEC_13818_6_TYPE_D	= ISO_IEC_13818_6_TYPE_C + 1,
    ISO_IEC_13818_1_AUXILIARY = ISO_IEC_13818_6_TYPE_D + 1,
    ISO_IEC_13818_1_RESERVED = ISO_IEC_13818_1_AUXILIARY + 1,
    USER_PRIVATE			= ISO_IEC_13818_1_RESERVED + 1
} MPEG2StreamType;

IMPEG2ComponentType::put_StreamType

IMPEG2ComponentType インターフェイス

MPEG2 のストリーム タイプを設定する。

構文

HRESULT put_StreamType(
    MPEG2StreamType MP2StreamType
    );

パラメータ

MP2StreamType
[in] ストリーム タイプを指定する MPEG2StreamType 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

typedef enum MPEG2StreamType {
        BDA_UNITIALIZED_MPEG2STREAMTYPE = -1,
    Reserved1 = 0x0,
    ISO_IEC_11172_2_VIDEO	= Reserved1 + 1,
    ISO_IEC_13818_2_VIDEO	= ISO_IEC_11172_2_VIDEO + 1,
    ISO_IEC_11172_3_AUDIO	= ISO_IEC_13818_2_VIDEO + 1,
    ISO_IEC_13818_3_AUDIO	= ISO_IEC_11172_3_AUDIO + 1,
    ISO_IEC_13818_1_PRIVATE_SECTION = ISO_IEC_13818_3_AUDIO + 1,
    ISO_IEC_13818_1_PES		= ISO_IEC_13818_1_PRIVATE_SECTION + 1,
    ISO_IEC_13522_MHEG		= ISO_IEC_13818_1_PES + 1,
    ANNEX_A_DSM_CC			= ISO_IEC_13522_MHEG + 1,
    ITU_T_REC_H_222_1		= ANNEX_A_DSM_CC + 1,
    ISO_IEC_13818_6_TYPE_A	= ITU_T_REC_H_222_1 + 1,
    ISO_IEC_13818_6_TYPE_B	= ISO_IEC_13818_6_TYPE_A + 1,
    ISO_IEC_13818_6_TYPE_C	= ISO_IEC_13818_6_TYPE_B + 1,
    ISO_IEC_13818_6_TYPE_D	= ISO_IEC_13818_6_TYPE_C + 1,
    ISO_IEC_13818_1_AUXILIARY = ISO_IEC_13818_6_TYPE_D + 1,
    ISO_IEC_13818_1_RESERVED = ISO_IEC_13818_1_AUXILIARY + 1,
    USER_PRIVATE			= ISO_IEC_13818_1_RESERVED + 1
} MPEG2StreamType;


ISignalEvents インターフェイス

このインターフェイスは、標準 COM IConnectionPoint インターフェイスである。アプリケーションから現在の信号の強度に関する情報を受け取るには、このインターフェイスを実装する。ITuner::TriggerSignalEvents を呼び出すと、チューナーがアプリケーションに OnSignal イベントを繰り返し送信する。

ISignalEvents::OnSignal

ISignalEvents インターフェイス

アプリケーションに現在の信号の強度を知らせる。

構文

HRESULT OnSignal(long* Strength );

パラメータ

Strength
[out] 新しい信号強度値を受け取る Long 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。


IScanningTuner インターフェイス

IScanningTuner は、ITuner を継承し、有効なプログラミングのサーチをサポートするチューナーを直接制御する。クライアントは、このインターフェイスに含まれるメソッドのいずれかを呼び出す前に、有効なチューニング空間を提供する必要がある (ITuner::put_TuningSpace または ITuner::put_TuneRequest を使用)。このインターフェイスは、出力用の ITunerEvents インターフェイスと共に使用するようになっている。

メソッド名 | 説明
ITuner メソッド
get_TuningSpace | チューナー用の現在有効なチューニング空間を取得する。
put_TuningSpace | チューナー用の現在有効なチューニング空間を設定する。
EnumTuningSpaces | この実装で優先されるチューニング空間を列挙する列挙子を作成する。
get_TuneRequest | チューナー用の現在有効なチューニング要求を取得する。
put_TuneRequest | チューナー用の現在有効なチューニング要求を設定する。
Validate | チューニング要求を実行できるかどうかを示す値を返す。
get_PreferredComponentTypes | デフォルト コンポーネントの選択に使用する ComponentType オブジェクトのコレクションを取得する。
put_PreferredComponentTypes | デフォルト コンポーネントの選択に使用する ComponentType オブジェクトのコレクションを設定する。
get_SignalStrength | チューナー固有の信号強度メトリックを取得する。
TriggerSignalEvents | ISignalEvents::OnSignal が繰り返し呼び出されるモードにチューナーを切り替える。
IScanningTuner メソッド
SeekUp | 有効なプログラミングを持つ 1 つ上のチャンネルに切り替える。
SeekDown | 有効なプログラミングを持つ 1 つ下のチャンネルに切り替える。
ScanUp | 有効なプログラミングを持つ 1 つ上のチャンネルに切り替え、指定された時間 (ミリ秒) ポーズする処理を、取り消されるまで繰り返す。
ScanDown | 有効なプログラミングを持つ 1 つ下のチャンネルに切り替え、指定された時間 (ミリ秒) ポーズする処理を、取り消されるまで繰り返す。
AutoProgram | 有効なプログラミングを持つチャンネルをすべてスキャンする。

IScanningTuner::SeekUp

IScanningTuner インターフェイス

有効なプログラミングを持つ 1 つ上のチャンネルに切り替える。

構文

HRESULT SeekUp();

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

即座に呼び出し元へ制御が戻り、バックグラウンドでシークが続行される。ほかの任意のチューニング処理を呼び出すと、シークを取り消すことができる。

IScanningTuner::SeekDown

IScanningTuner インターフェイス

有効なプログラミングを持つ 1 つ下のチャンネルに切り替える。

構文

HRESULT SeekDown();

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

即座に呼び出し元へ制御が戻り、バックグラウンドでシークが続行される。ほかの任意のチューニング処理を呼び出すと、シークを取り消すことができる。

IScanningTuner::ScanUp

IScanningTuner インターフェイス

有効なプログラミングを持つ 1 つ上のチャンネルに切り替え、指定された時間 (ミリ秒) ポーズする処理を、取り消されるまで繰り返す。

構文

HRESULT ScanUp(
long MillisecondsPause
    );

パラメータ

MillisecondsPause
[in] ポーズする時間 (ミリ秒) を指定する Long 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

即座に呼び出し元へ制御が戻り、バックグラウンドでスキャンが続行される。ほかの任意のチューニング処理を呼び出すと、スキャンを取り消すことができる。

IScanningTuner::ScanDown

IScanningTuner インターフェイス

有効なプログラミングを持つ 1 つ下のチャンネルに切り替え、指定された時間 (ミリ秒) ポーズする処理を、取り消されるまで繰り返す。

構文

HRESULT ScanDown(
long MillisecondsPause
    );

パラメータ

MillisecondsPause
[in] ポーズする時間 (ミリ秒) を指定する Long 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

即座に呼び出し元へ制御が戻り、バックグラウンドでスキャンが続行される。ほかの任意のチューニング処理を呼び出すと、スキャンを取り消すことができる。

IScanningTuner::AutoProgram

IScanningTuner インターフェイス

有効なプログラミングを持つチャンネルをすべてスキャンする。

構文

HRESULT AutoProgram();

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

このメソッドでは、即座に呼び出し元へ制御が戻り、バックグラウンドでスキャンが続行される。デバイスにその能力があれば、ほかの任意のチューニング処理を呼び出すと、スキャンを取り消すことができる。それ以外の場合、スキャンは全チャンネルを一通り通過するまで続く。大半の内部デバイスでは、この機能のソフトウェア実装があり、スキャンから得られる最適チューニング情報が収集される。また、外部デバイスでは、この機能が実装されているため、このメソッドが処理を開始する手段に過ぎない場合が多い。


ITuneRequest インターフェイス

すべての ITuneRequest オブジェクトは、IPersistPropertyBag もサポートする。

メソッド名 | 説明
get_TuningSpace | チューニング空間オブジェクトを取得する。
get_Components | IComponent オブジェクトのコレクションを取得する。
Clone | このチューニング要求の新しいコピーを返す。
get_Locator | ネットワーク プロバイダから呼び出され、要求されたブロードキャストに関連付けられた ILocator オブジェクトを取得する。
put_Locator | ネットワーク プロバイダから呼び出され、要求されたブロードキャストに関連付けられた ILocator オブジェクトを設定する。

ITuneRequest::get_TuningSpace

ITuneRequest インターフェイス

チューニング空間オブジェクトを取得する。

構文

HRESULT get_TuningSpace(
ITuningSpace** TuningSpace
    );

パラメータ

TuningSpace
[out, retval] 返されるオブジェクトに設定する ITuningSpace インターフェイス ポインタのアドレス。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

ITuneRequest::get_Components

ITuneRequest インターフェイス

IComponent オブジェクトのコレクションを取得する。

構文

HRESULT get_Components(
    IComponents** Components
    );

パラメータ

Components
[out, retval] 返されるオブジェクトに設定する IComponents インターフェイス ポインタのアドレス。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

チューニング要求には必ず Components コレクションが関連付けられているが、このコレクションは空である可能性がある。

ITuneRequest::Clone

ITuneRequest インターフェイス

このチューニング要求の新しいコピーを返す。

構文

HRESULT Clone(
    ITuneRequest** NewTuneRequest
    );

パラメータ

NewTuneRequest
[out, retval] 新しいオブジェクトに設定する ITuneRequest インターフェイス ポインタのアドレス。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

このメソッドはオブジェクトの "ディープ コピー" を実行する。つまり、Components、LanguageComponents などを含むすべてのサブオブジェクトもコピーされる。

ITuneRequest::get_Locator

ITuneRequest インターフェイス

ネットワーク プロバイダから呼び出され、要求されたブロードキャストに関連付けられた ILocator オブジェクトを取得する。

構文

HRESULT get_Locator(
    ILocator** Locator
    );

パラメータ

Locator
[out, retval] 新しいオブジェクトに設定する ILocator インターフェイス ポインタのアドレス。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

ロケータは、要求されたブロードキャストを取得する方法や場所に関する情報を取得するために、ネットワーク プロバイダとトランスポート情報フィルタ (TIF) から使用される。この情報には、変調の方式、エラー訂正方式、および周波数が含まれる。アプリケーションは下位レベルの細かいチューニング処理に関与しないため、通常、アプリケーションでこの情報を使用することはない。

ITuneRequest::put_Locator

ITuneRequest インターフェイス

ネットワーク プロバイダから呼び出され、要求されたブロードキャストに関連付けられた ILocator オブジェクトを設定する。

構文

HRESULT put_Locator(
    ILocator* Locator
    );

パラメータ

Locator
[in] 新しいロケータを指定する ILocator インターフェイスへのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。


ITunerEvents インターフェイス

このインターフェイスは、標準 COM IConnectionPoint インターフェイスである。アプリケーションにこのインターフェイスを実装すると、新しい周波数またはチャンネルにチューニングするたびに、チューナー オブジェクトからイベント通知を受け取ることができる。このインターフェイスは TuneRequest オブジェクトを返し、新しいチャンネルまたは周波数で実際に利用可能なサブストリームが、その Components コレクションに反映されている。

ITunerEvents::OnTune

ITunerEvents インターフェイス

チューナー フィルタが新しい周波数にチューニングしたことをアプリケーションに知らせる。

構文

  HRESULT OnTune(
  ITuneRequest** Request,
  long* Strength
    );

パラメータ

Request
[in] TuneRequest オブジェクトを受け取る ITuneRequest インターフェイス ポインタのアドレス。このオブジェクトの Components コレクションに、新しいチャンネルまたは周波数で利用可能なサブストリームが反映されている。
Strength
[in] 新しいチャンネルまたは周波数の信号強度を表す Long 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。


ITuningSpace インターフェイス

ITuningSpace インターフェイスは、ネットワーク固有のチューニング空間すべてに共通の機能を提供する基底クラスである。チューニング空間コンテナでは、ITuningSpace のみを公開するオブジェクトのインスタンスを重複して作成することはなく、必ず、ITuningSpace から派生する何らかのインターフェイス (IASTCTuningSpace など) をサポートするオブジェクトのインスタンスを作成する。

メソッド名 | 説明
get_UniqueName | チューニング空間の固有の名称を取得する。固有の名称は略称か GUID である。
put_UniqueName | チューニング空間の固有の名称を設定する。固有の名称は略称か GUID である。
get_FriendlyName | チューニング空間のローカライズされたフレンドリ名を取得する。
put_FriendlyName | チューニング空間のローカライズされたフレンドリ名を設定する。
get_CLSID | チューニング空間の CLSID を BSTR として取得する。
put_NetworkType | このチューニング空間のネットワーク タイプを BSTR として設定する。
get__NetworkType | チューニング空間のネットワーク タイプを GUID として取得する。
put__NetworkType | このチューニング空間のネットワーク タイプを REFCLSID として設定する。
get_NetworkType | チューニング空間のネットワーク タイプを BSTR として取得する。
CreateTuneRequest | 空の (初期化されていない) チューニング要求を表す COM オブジェクトを作成する。
EnumCategoryGUIDs | (現時点では未実装) DirectShow カテゴリ GUID を列挙する列挙子を作成する。カテゴリ GUID は、チューニング空間をサポートするフィルタの種類を表すものである。
EnumDeviceMonikers | (現時点では未実装) このチューニング空間をサポートするチューナー入力 (フィルタ) を表すデバイス モニカの列挙子を作成する。
get_DefaultPreferredComponentTypes | 優先コンポーネント タイプのリストを返す。優先コンポーネント タイプは、優先オーディオ ストリームなどのパラメータを指定するものである。
put_DefaultPreferredComponentTypes | 優先コンポーネント タイプのリストを作成する。優先コンポーネント タイプは、優先オーディオ ストリームなどのパラメータを指定するものである。
get_FrequencyMapping | ネットワーク プロバイダが put_FrequencyMapping を呼び出して直前に作成した周波数マッピングを取得する。
put_FrequencyMapping | 周波数とチャンネルのマッピング、周波数と中継器のマッピング、またはキャリア周波数から周波数識別子への、チューニング空間に適したその他のあらゆるマッピングを作成する。
get_DefaultLocator | ローカル システムのデフォルト ロケータを取得する。
put_DefaultLocator | ローカル システムのデフォルト ロケータを設定する。
Clone | チューニング空間の新しいコピーを作成する。

ITuningSpace::get_UniqueName

ITuningSpace インターフェイス

チューニング空間の固有の名称を取得する。固有の名称は略称か GUID である。

構文

HRESULT get_UniqueName(
BSTR* Name
    );

パラメータ

Name
[out, retval] 固有の名称を受け取る BSTR 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

固有の名称は、グローバルに一意な任意の文字列である。

ITuningSpace::put_UniqueName

ITuningSpace インターフェイス

チューニング空間の固有の名称を設定する。固有の名称は略称か GUID である。

構文

HRESULT put_UniqueName(
BSTR Name
    );

パラメータ

Name
[in] 固有の名称を指定する BSTR 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

ITuningSpace::get_FriendlyName

ITuningSpace インターフェイス

チューニング空間のローカライズされたフレンドリ名を取得する。

構文

HRESULT get_FriendlyName(
BSTR* Name
    );

パラメータ

Name
[out, retval] フレンドリ名を受け取る BSTR 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

ITuningSpace::put_FriendlyName

ITuningSpace インターフェイス

チューニング空間のローカライズされたフレンドリ名を設定する。

構文

HRESULT put_FriendlyName(
    BSTR Name
    );

パラメータ

Name
[in] フレンドリ名を指定する BSTR 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

ITuningSpace::get_CLSID

ITuningSpace インターフェイス

チューニング空間の CLSID を BSTR として取得する。

構文

HRESULT get_CLSID(
    BSTR* SpaceCLSID
    );

パラメータ

SpaceCLSID
[out, retval] チューニング空間の CLSID を受け取る BSTR 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

このメソッドは、IPersist::GetClassID メソッドへのスクリプト アクセスを提供する。

ITuningSpace::get_NetworkType

ITuningSpace Interface

チューニング空間のネットワーク タイプを BSTR として取得する。

構文

HRESULT get_NetworkType(
    BSTR* NetworkTypeGuid
    );

パラメータ

NetworkTypeGuid
[out, retval] ネットワーク タイプを示す GUID を受け取る BSTR 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

フィルタ グラフ構築時には、このメソッドで取得した GUID を、ネットワーク プロバイダ フィルタを作成するための CLSID として使用する。このメソッドは、Visual Basic® とスクリプト アプリケーション用に提供される。C++ アプリケーションでは、get__NetworkType を使って、ネイティブな GUID データ型としてネットワーク タイプを取得すること。

ITuningSpace::put_NetworkType

ITuningSpace Interface

チューニング空間のネットワーク タイプを BSTR として指定する。

構文

HRESULT put_NetworkType(
    REFCLSID NetworkTypeGuid
    );

パラメータ

NetworkTypeGuid
[in] ネットワーク タイプを指定する BSTR 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

このメソッドは、Visual Basic® とスクリプト アプリケーション用に提供される。C++ アプリケーションでは、put__NetworkType を使うこと。

ITuningSpace::get__NetworkType

ITuningSpace Interface

チューニング空間のネットワーク タイプを GUID として取得する。

構文

HRESULT get_NetworkType(
    GUID* NetworkTypeGuid
    );

パラメータ

NetworkTypeGuid
[out, retval] ネットワーク タイプを受け取る GUID 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

フィルタ グラフの構築時にネットワーク プロバイダを作成するときは、このメソッドで取得される GUID を CLSID として使用する。

ITuningSpace::put__NetworkType

ITuningSpace Interface

チューニング空間のネットワーク タイプを REFCLSID として指定する。

構文

HRESULT put__NetworkType(
    BSTR NetworkTypeGuid
    );

パラメータ

NetworkTypeGuid
[in] ネットワーク タイプを指定する REFCLSID 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

ITuningSpace::CreateTuneRequest

ITuningSpace インターフェイス

空の (初期化されていない) チューニング要求を表す COM オブジェクトを作成する。

構文

HRESULT CreateTuneRequest(
    ITuneRequest** TuneRequest
    );

パラメータ

TuneRequest
[out, retval] 新しいチューニング要求オブジェクトを受け取る ITuneRequest インターフェイス ポインタのアドレス。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

このメソッドは ITuneRequest 基底クラス インターフェイスを返すが、このインターフェイスを使ってチューニング要求を作成することはできない。チューニング要求を作成するには、使用しているチューニング空間のタイプに関連付けられた派生インターフェイスを使う必要がある。派生インターフェイスを取得するには、返された ITuneRequest オブジェクトの QueryInterface を呼び出し、必要なインターフェイスを指定する。次の一覧は、チューニング空間とチューニング要求の関係を示す。

チューニング空間 | チューニング要求
IAnalogTVTuningSpace | IID_IChannelTuneRequest
IAnalogRadioTuningSpace | IID_IChannelTuneRequest
IDVBTuningSpace | IID_IDVBTuneRequest
IATSCTuningSpace | IID_IATSCChannelTuneRequest

ITuningSpace::EnumCategoryGUIDs

ITuningSpace インターフェイス

(現時点では未実装) DirectShow カテゴリ GUID を列挙する列挙子を作成する。カテゴリ GUID は、チューニング空間をサポートするフィルタの種類を表すものである。

構文

HRESULT EnumCategoryGUIDs(
    IEnumGUID** ppEnum
    );

パラメータ

ppEnum
[out, retval] 返された列挙オブジェクトを受け取る IEnumGUID インターフェイス ポインタのアドレス。

戻り値

E_NOTIMPL を返す。

注意

このメソッドにオートメーション言語からアクセスすることはできない。

ITuningSpace::EnumDeviceMonikers

ITuningSpace インターフェイス

(現時点では未実装) このチューニング空間をサポートするチューナー入力 (フィルタ) を表すデバイス モニカの列挙子を作成する。

構文

HRESULT EnumDeviceMonikers(
    IEnumMoniker** ppEnum
    );

パラメータ

ppEnum
[out, retval] 返された列挙オブジェクトを受け取る IEnumMoniker インターフェイス ポインタのアドレス。

戻り値

E_NOTIMPL を返す。

注意

このメソッドにオートメーション言語からアクセスすることはできない。

ITuningSpace::get_DefaultPreferredComponentTypes

ITuningSpace インターフェイス

優先コンポーネント タイプのリストを返す。優先コンポーネント タイプは、優先オーディオ ストリームなどのパラメータを指定するものである。

構文

HRESULT get_DefaultPreferredComponentTypes(
    IComponentTypes** ComponentTypes
    );

パラメータ

ComponentTypes
[out, retval] 返されたコレクションを受け取る IComponentTypes インターフェイス ポインタのアドレス。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

このコンテキストでは、プログラム内のストリームを "コンポーネント" と言う。"優先コンポーネント" には、たとえば英語のオーディオ ストリームなどが設定されている。コンポーネントまたはサブストリームが複数ある場合、チューナーは必ず優先コンポーネントを先に再生しようとする。

ITuningSpace::put_DefaultPreferredComponentTypes

ITuningSpace インターフェイス

優先コンポーネント タイプのリストを作成する。優先コンポーネント タイプは、優先オーディオ ストリームなどのパラメータを指定するものである。

構文

HRESULT put_DefaultPreferredComponentTypes(
    IComponentTypes* NewComponentTypes
    );

パラメータ

NewComponentTypes
[in] デフォルトの優先コンポーネント タイプを指定する ComponentTypes オブジェクトの IComponentTypes インターフェイスへのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

ITuningSpace::get_FrequencyMapping

ITuningSpace インターフェイス

ネットワーク プロバイダが put_FrequencyMapping を呼び出して直前に作成した周波数マッピングを取得する。

構文

HRESULT get_FrequencyMapping(
    BSTR* pMapping
    );

パラメータ

pMapping
[out, retval] ネットワーク プロバイダが作成した周波数マッピングを受け取る BSTR。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

この BSTR はバイナリ ラージ オブジェクト (BLOB) として処理される。この BSTR には、NULL が埋め込まれ、ネットワーク プロバイダがふさわしいと判断する書式で内部的にフォーマットされる可能性がある。

ITuningSpace::put_FrequencyMapping

ITuningSpace インターフェイス

周波数とチャンネルのマッピング、周波数と中継器のマッピング、またはキャリア周波数から周波数識別子への、チューニング空間に適したその他のあらゆるマッピングを作成する。

構文

HRESULT put_FrequencyMapping(
    BSTR Mapping
    );

パラメータ

Mapping
[in] 周波数マッピングが格納された BSTR。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

このメソッドは、周波数マッピングが入った文字列を格納するために、ネットワーク プロバイダから使用される。

ITuningSpace::get_DefaultLocator

ITuningSpace インターフェイス

ローカル システムのデフォルト ロケータを取得する。

構文

HRESULT get_DefaultLocator(
    ILocator** LocatorVal
    );

パラメータ

LocatorVal
[out, retval] 返された ILocator インターフェイスを受け取るポインタのアドレス。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

デフォルトのロケータは、インストール後に IScanningTuner オブジェクトの始点として使用できる。

ITuningSpace::put_DefaultLocator

ITuningSpace インターフェイス

ローカル システムのデフォルト ロケータを設定する。

構文

HRESULT put_DefaultLocator(
    ILocator* LocatorVal
    );

パラメータ

LocatorVal
[in] デフォルトのロケータとして設定するオブジェクトの ILocator インターフェイスへのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

デフォルトのロケータは、インストール後に IScanningTuner オブジェクトの始点として使用できる。

ITuningSpace::Clone

ITuningSpace インターフェイス

新しいチューニング空間をコピーする。

構文

HRESULT Clone(
    ITuningSpace** NewTS
    );

パラメータ

NewTS
[out, retval] 新しいチューニング空間オブジェクトがセットされる ITuningSpace インターフェイス ポインタのアドレス。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。


ITuningSpaces インターフェイス

このインターフェイスは、SystemTuningSpaces オブジェクトに実装され、ホスト システムで利用可能なチューニング空間を取得するメソッドを提供する。

メソッド名 | 説明
get_Count | コレクションに含まれるチューニング空間の数を取得する。
get_EnumTuningSpaces | C++ アプリケーション用のコンビニエンス関数。VARIANT データ型をアンパックする必要がない。
get_Item | コレクションに含まれる指定された項目を返す。
get__NewEnum | Visual Basic およびスクリプト アプリケーション用のヘルパー メソッド。C++ では使用しない。

ITuningSpaces::get_Count

ITuningSpaces インターフェイス

コレクションに含まれるチューニング空間の数を取得する。

構文

HRESULT get_Count(
long* Count
    );

パラメータ

Count
[out, retval] コレクションに含まれる項目の数を受け取る Long 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。

ITuningSpaces::get_EnumTuningSpaces

ITuningSpaces インターフェイス

C++ アプリケーション用のコンビニエンス関数。VARIANT データ型をアンパックする必要がない。

構文

HRESULT get_EnumTuningSpaces(
    IEnumTuningSpaces** NewEnum
    );

パラメータ

NewEnum
[out, retval] 新しいコレクションを受け取る IEnumTuningSpaces インターフェイス ポインタのアドレス。

戻り値

成功した場合は、S_OK を返す。

ITuningSpaces::get_Item

ITuningSpaces インターフェイス

コレクションに含まれる指定された項目を返す。

構文

HRESULT get_Item(
VARIANT varIndex,
ITuningSpace** TuningSpace
    );

パラメータ

varIndex
[in] 返す項目を指定する文字列またはインデックス番号。
TuningSpace
[out, retval] 返される ITuningSpace インターフェイス ポインタのアドレス。

戻り値

成功した場合は、S_OK を返す。

ITuningSpaces::get__NewEnum

ITuningSpaces インターフェイス

Visual Basic およびスクリプト アプリケーション用のヘルパー メソッド。C++ では使用しない。

構文

HRESULT get__NewEnum(
    IEnumVARIANT** NewEnum
    );

パラメータ

NewEnum
[out, retval] IEnumVariant インターフェイス ポインタのアドレス。

戻り値

成功した場合は、S_OK を返す。

注意

Microsoft® Visual Basic® およびスクリプト アプリケーションで、For...Next ループ内から項目を取得するには、このメソッドを使用する。


ITuningSpaceContainer インターフェイス

ITuningSpaceContainer インターフェイスは、SystemTuningSpaces オブジェクトに実装される。SystemTuningSpaces オブジェクトを使用すると、アプリケーションからローカル システムに定義された全チューニング空間のアクセスおよび修正ができる。

メソッド名 | 説明
get_Count | ローカル システム上で現在利用可能なチューニング空間の数を取得する。
get__NewEnum | Automation クライアントの For...Each ループをサポートするための列挙メソッド。
get_Item | 指定されたインデックス位置のチューニング空間オブジェクトを取得する。
put_Item | 指定されたインデックス位置にチューニング空間オブジェクトを保存する。
TuningSpacesForCLSID | 指定された CLSID 文字列と一致するチューニング空間のコレクションを取得する。(Automation クライアントで使用)
_TuningSpacesForCLSID | 指定された CLSID 文字列と一致するチューニング空間のコレクションを取得する。(C++ クライアントで使用)
TuningSpacesForName | フレンドリ名と一致するチューニング空間のコレクションを取得する。
FindID | 指定されたチューニング空間のローカル一意識別子を取得する。
Add | 新しい持続的なチューニング空間をシステムに追加する。
get_EnumTuningSpaces | ローカル システム上で利用可能な全チューニング空間のコレクションを取得する。
Remove | チューニング空間をシステムから完全に削除する。
put_MaxCount | システム上で許されるチューニング空間の最大数を取得する。
get_MaxCount | システム上で許されるチューニング空間の最大数を設定する。

ITuningSpaceContainer::get_Count

ITuningSpaceContainer インターフェイス

ローカル システム上で現在利用可能なチューニング空間の数を取得する。

構文

HRESULT get_Count(
    long *Count
    );

パラメータ

Count
[out, retval] チューニング空間の数を受け取る Long 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

ITuningSpaceContainer::get_MaxCount

ITuningSpaceContainer インターフェイス

システム上で許されるチューニング空間の最大数を取得する。

構文

HRESULT get_MaxCount(
    long *MaxCount
    );

パラメータ

MaxCount
[out, retval] チューニング空間の最大数を受け取る Long 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

ITuningSpaceContainer::get__NewEnum

ITuningSpaceContainer インターフェイス

Automation クライアントの For...Each ループをサポートするための列挙メソッド。

構文

HRESULT get__NewEnum(
    IEnumVARIANT **NewEnum
    );

パラメータ

NewEnum
[out, retval] 返されるコレクションに設定する IEnumVARIANT インターフェイス ポインタのアドレス。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

このメソッドは、For...Each ループの繰り返しによってコレクション全体を処理するため、スクリプト アプリケーションおよび VB アプリケーション用に提供される。C++ アプリケーションでは get_EnumTuningSpaces メソッドを使用すること。

ITuningSpaceContainer::get_Item

ITuningSpaceContainer インターフェイス

指定されたインデックス位置の ITuningSpace オブジェクトを取得する。

構文

HRESULT get_Item(
VARIANT varIndex,
    ITuningSpace **ppTuningSpace
    );

パラメータ

varIndex
[in] 取得する項目のインデックスを指定する VARIANT 型変数。
ppTuningSpace
[out, retval] 返されるインターフェイスに設定する ITuningSpace インターフェイス ポインタのアドレス。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

ITuningSpaceContainer::put_Item

ITuningSpaceContainer インターフェイス

指定されたインデックス位置にチューニング空間オブジェクトを保存する。

構文

HRESULT put_Item(
VARIANT varIndex,
    ITuningSpace *pTuningSpace
    );

パラメータ

varIndex
[in] 設定する項目のインデックスを指定する VARIANT 型変数。
pTuningSpace
[in] システムに持続的に保存するオブジェクトの ITuningSpace インターフェイスへのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

ITuningSpace のメソッドを使用すると、アプリケーションから既存のチューニング空間を修正し、ITuningSpaceContainer::put_Item を使って変更内容をディスクに保存することができる。

ITuningSpaceContainer::TuningSpacesForCLSID

ITuningSpaceContainer インターフェイス

CLSID 文字列と一致するチューニング空間のコレクションを取得する。(Automation クライアントで使用)

構文

HRESULT TuningSpacesForCLSID(
    BSTR SpaceCLSID,
    ITuningSpaces **ppTuningSpaces
    );

パラメータ

SpaceCLSID
[in] チューニング空間の CLSID を表す文字列。
ppTuningSpaces
[out, retval] 返されるコレクションに設定する ITuningSpaces インターフェイス ポインタのアドレス。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

このメソッドを使用すると、Automation クライアントから CLSID を BSTR で指定できる。内部的には、_TuningSpacesForCLSID を呼び出しているだけである。

ITuningSpaceContainer::_TuningSpacesForCLSID

ITuningSpaceContainer インターフェイス

指定された CLSID 文字列と一致するチューニング空間のコレクションを取得する。(C++ クライアントで使用)

構文

HRESULT _TuningSpacesForCLSID(
    REFCLSID SpaceCLSID,
    ITuningSpaces **ppTuningSpaces
    );

パラメータ

SpaceCLSID
[in] 取得するチューニング空間のタイプを指定する REFCLSID 型変数。
ppTuningSpaces
[out, retval] 返されるコレクションに設定する ITuningSpaces インターフェイス ポインタのアドレス。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

C++ アプリケーションでは、TuningSpacesForCLSID ではなくこのメソッドを使用すること。

ITuningSpaceContainer::TuningSpacesForName

ITuningSpaceContainer インターフェイス

フレンドリ名と一致するチューニング空間のコレクションを取得する。

構文

HRESULT TuningSpacesForName(
    BSTR Name,
    ITuningSpaces **ppTuningSpaces
    );

パラメータ

Name
[in] チューニング空間タイプのフレンドリ名を表す文字列。
ppTuningSpaces
[out, retval] 返されるコレクションに設定する ITuningSpaces インターフェイス ポインタのアドレス。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

ITuningSpaceContainer::FindID

ITuningSpaceContainer インターフェイス

指定されたチューニング空間のローカル一意識別子を取得する。

構文

HRESULT FindID(
    ITuningSpace *pTuningSpace,
    long *pID
    );

パラメータ

pTuningSpace
[in] ID を取得するオブジェクトの ITuningSpace インターフェイスへのポインタ。
pID
[out, retval] ID 番号を受け取る Long 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。TuningSpace が有効なオブジェクトを指していない場合は、E_INVALIDARG を返す。

ITuningSpaceContainer::Add

ITuningSpaceContainer インターフェイス

新しい持続的なチューニング空間をシステムに追加する。

構文

HRESULT Add(
    ITuningSpace *pTuningSpace,
    VARIANT *pNewIndex
    );

パラメータ

pTuningSpace
[in] システムに追加する新しいチューニング空間オブジェクトの ITuningSpace インターフェイスへのポインタ。
pNewIndex
[out, retval] 現在のコレクションにおける新しいチューニング空間のインデックス番号を受け取る VARIANT 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

ITuningSpaceContainer::Add() メソッドでは、追加したオブジェクトのインデックスが 1 から始まる。IComponentTypes::Add() メソッドおよびその他のコレクションでは、すべて 0 から始まる。

ITuningSpaceContainer::get_EnumTuningSpaces

ITuningSpaceContainer インターフェイス

ローカル システム上で利用可能な全チューニング空間のコレクションを取得する。

構文

HRESULT get_EnumTuningSpaces(
    IEnumTuningSpaces **ppEnum
    );

パラメータ

ppEnum
[out, retval] 返されるコレクションに設定する IEnumTuningSpaces インターフェイス ポインタのアドレス。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

C++ アプリケーションでは、このメソッドを使ってローカル システムに定義されたチューニング空間の初期リストを取得する。

ITuningSpaceContainer::put_MaxCount

ITuningSpaceContainer インターフェイス

システム上で許されるチューニング空間の最大数を設定する。

構文

HRESULT put_MaxCount(
    long MaxCount
    );

パラメータ

MaxCount
[in] チューニング空間の最大数を指定する Long 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

ITuningSpaceContainer::Remove

ITuningSpaceContainer インターフェイス

チューニング空間をシステムから完全に削除する。

構文

HRESULT Remove(
VARIANT Index
    );

パラメータ

Index
[in] システムから削除するチューニング空間のインデックス番号を指定する VARIANT 型変数。

戻り値

成功した場合は、S_OK を返す。指定されたチューニング空間が無効か、またはレジストリ内で破損している場合は、情報をすべて削除し、S_FALSE を返す。


ITuner インターフェイス

ITuner は、ネットワーク プロバイダ フィルタに実装される。

メソッド名 | 説明
get_TuningSpace | ネットワーク プロバイダ用の現在有効なチューニング空間を取得する。
put_TuningSpace | ネットワーク プロバイダ用のチューニング空間を設定する。
EnumTuningSpaces | この実装で優先されるチューニング空間のコレクションを作成する。
get_TuneRequest | ネットワーク プロバイダ用の現在有効なチューニング要求を取得する。
put_TuneRequest | ネットワーク プロバイダ用のチューニング要求を設定する。
Validate | チューニング要求を実行できるかどうかを示す値を返す。
get_PreferredComponentTypes | デフォルト コンポーネントの選択に使用する ComponentType オブジェクトのコレクションを取得する。
put_PreferredComponentTypes | デフォルト コンポーネントの選択に使用する ComponentType オブジェクトのコレクションを設定する。
get_SignalStrength | ネットワーク プロバイダ固有の信号強度メトリックを取得する。
TriggerSignalEvents | ISignalEvents::OnSignal が繰り返し呼び出されるモードにネットワーク プロバイダを切り替える。

ITuner::get_TuningSpace

ITuner インターフェイス

ネットワーク プロバイダ用の現在有効なチューニング空間を取得する。

構文

HRESULT get_TuningSpace(
ITuningSpace** TuningSpace
    );

パラメータ

TuningSpace
[out, retval] 現在のチューニング空間に設定する ITuningSpace インターフェイス ポインタのアドレス。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

ITuner::put_TuningSpace

ITuner インターフェイス

ネットワーク プロバイダ用のチューニング空間を設定する。

構文

HRESULT put_TuningSpace(
ITuningSpace* TuningSpace
    );

パラメータ

TuningSpace
[in] ネットワーク プロバイダに設定するチューニング空間へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

ITuner::EnumTuningSpaces

ITuner インターフェイス

この実装で優先されるチューニング空間のコレクションを作成する。

構文

HRESULT EnumTuningSpaces(
IEnumTuningSpaces** ppEnum
    );

パラメータ

ppEnum
[out, retval] 返されるコレクションに設定する IEnumTuningSpaces インターフェイス ポインタのアドレス。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

このリストは、この実装と互換性のあるチューニング空間のサブセットである。

ITuner::get_TuneRequest

ITuner インターフェイス

ネットワーク プロバイダ用の現在有効なチューニング要求を取得する。

構文

HRESULT get_TuneRequest(
ITuneRequest** TuneRequest
    );

パラメータ

TuneRequest
[out, retval] 返されるオブジェクトに設定する ITuneRequest インターフェイス ポインタのアドレス。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

チューナーにチューニング要求を発行した後に、その Components コレクションの内容が設定される。アプリケーションでは、プログラムへのチューニング後に get_TuneRequest を呼び出して、そのプログラムで現在利用可能なコンポーネントを判断し、さらに、コレクションに含まれるコンポーネントオブジェクトの IComponent::put_Status メソッドを使って、そのコンポーネントをアクティブまたは非アクティブにすることができる。アプリケーションでオーディオ ストリームを (たとえば英語からスペイン語に) 切り替える場合には、この方法で行う。

ITuner::put_TuneRequest

ITuner インターフェイス

ネットワーク プロバイダ用の現在有効なチューニング要求を設定する。

構文

HRESULT put_TuneRequest(
ITuneRequest* TuneRequest
    );

パラメータ

TuneRequest
[in] ネットワーク プロバイダの設定に使用する ITuneRequest オブジェクトへのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

このメソッドを呼び出すと、チューニング要求のプロパティに基づいてチューニング処理が開始する。チューニング処理は非同期で行われる可能性がある。

ITuner::Validate

ITuner インターフェイス

チューニング要求を実行できるかどうかを示す値を返す。

構文

HRESULT Validate(
ITuneRequest* TuneRequest
    );

パラメータ

TuneRequest
[in] チューニング要求オブジェクトへのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

入力として IUnknown* を受け付ける。ネットワーク プロバイダは、まず、優先されるチューニング要求インターフェイスを照会する。見つかった場合は、チューニング要求を実行できるかどうかを確認する。見つからなければ、優先されるチューニング空間インターフェイスを照会する。見つかった場合は、所定のチューニング空間にあわせてネットワーク プロバイダ自体を構成できるかどうかを確認する。

ITuner::get_PreferredComponentTypes

ITuner インターフェイス

デフォルト コンポーネントの選択に使用する ComponentType オブジェクトのコレクションを取得する。

構文

HRESULT get_PreferredComponentTypes(
IComponentTypes** ComponentTypes
    );

パラメータ

ComponentTypes
[out, retval] ComponentType オブジェクトのコレクションを受け取る IComponentTypes インターフェイス ポインタのアドレス。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

プログラムが終了すると、新しいサブストリーム ("コンポーネント") のセットが利用可能になる可能性がある。このため、チューナーは、優先コンポーネント タイプのリストを自動的に調べ、そのリストに従ってサブストリームを選択する。リストがない場合は、ほかの要因に基づいて選択が行われる。アプリケーションでは、単に現在のリストを調べるため、このメソッドを呼び出す。

ITuner::put_PreferredComponentTypes

ITuner インターフェイス

デフォルト コンポーネントの選択に使用する ComponentType オブジェクトのコレクションを設定する。

構文

HRESULT put_PreferredComponentTypes(
IComponentTypes* ComponentTypes
    );

パラメータ

ComponentTypes
[in] ComponentType オブジェクトのコレクションが格納された IComponentTypes インターフェイスへのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

アプリケーションで優先コンポーネント タイプのリストを作成するには、空の ComponentTypes コレクションをインスタンス化し、そこに内容を設定してから put_PreferredComponentTypes を使ってチューナーに渡す。

ITuner::get_SignalStrength

ITuner インターフェイス

ネットワーク プロバイダ固有の信号強度メトリックを取得する。

構文

HRESULT get_SignalStrength(
long* Strength
    );

パラメータ

Strength
[out, retval] 信号強度を受け取る Long 型変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

-1 は信号強度を判断できないことを表し、0 はチューニングされていないことを表す。また、大きい値は強い信号を意味する。デジタル チューナーの場合、FEC のビット エラー レート (BER) も同様に解釈できる。

ITuner::TriggerSignalEvents

ITuner インターフェイス

ISignalEvents::OnSignal が繰り返し呼び出されるモードにネットワーク プロバイダを切り替える。

構文

HRESULT TriggerSignalEvents(
long Interval
    );

パラメータ

Interval
[in] トリガー イベントの送信間隔を指定する Long 型変数。

戻り値

成功した場合は、S_OK を返す。失敗した場合は、標準の IErrorInfo インターフェイスを使ってエラー情報を取得できる。

注意

このモードがサポートされていない場合は、E_NOTIMPL を返す。間隔には、Signal イベントの生成頻度をミリ秒単位で指定する。


スクリプト可能なオブジェクト

以下のスクリプト可能なオブジェクト (Automation 準拠のオブジェクト) は、スクリプト アプリケーションからアクセスできる。このリリースでは、これらのオブジェクトのメソッドとプロパティを JScript の構文のみで表現する。VisualBasic を使用する場合は、オブジェクト ブラウザでオブジェクトを表示すると、データ型を調べることができる。C++ を使用する場合、詳細については idl ファイルを調べること。

チューニング空間オブジェクト

チューニング空間オブジェクトは、ネットワーク タイプやネットワーク プロバイダとかかわりなく、特定のプログラムにチューニングするための汎用的な手段を実装するために使用する。ガイド ストアを使用するアプリケーションでは独自のチューニング要求を構築する必要がないため、通常、アプリケーションでこれらのオブジェクトを使用することはない。アプリケーションでは、既製のチューニング要求をガイド ストアから取得し、それらをビデオ コントロールに渡す。

AnalogRadioTuningSpace | 地上波ラジオ ネットワーク固有のチューニング空間。
AnalogTVTuningSpace | アナログ TV ネットワーク固有のチューニング空間。
ATSCTuningSpace | ATSC ネットワーク固有のチューニング空間。
DVBTuningSpace | DVB ネットワーク固有のチューニング空間。
SystemTuningSpaces | アプリケーションから使用され、新しいチューニング空間の作成や、既存のチューニング空間の列挙または修正を行う。

チューニング要求オブジェクト

チューニング要求は、チューニング空間オブジェクトの ITuningSpace::CreateTuneRequest を呼び出して作成する。通常のアプリケーションでは、TuneRequest を独自に作成せずにガイド ストアから取得する。

ChannelTuneRequest | アナログ TV ネットワーク固有のチューニング要求オブジェクトに実装される。
ATSCChannelTuneRequest | ATSC TV ネットワーク固有のチューニング要求オブジェクトに実装される。
DVBTuneRequest | DVB TV ネットワーク固有のチューニング要求オブジェクトに実装される。

ストリーム コンポーネント オブジェクト

このコンテキストでは、ブロードキャスト内のサブストリームを "コンポーネント" と言う。ブロードキャスト ストリームの実際のコンポーネントは、受信開始後でなければわからない。その時点で、ネットワーク プロバイダが Component オブジェクト情報を設定する。

Component | 特定の Component オブジェクトの基底クラス。
ComponentType | 特定コンポーネント タイプ オブジェクトの基底クラス。
ComponentTypes | 標準 COM のコンポーネント タイプ リストを提供する。
Components | 標準 COM のコンポーネント リストを提供する。
LanguageComponentType | サブストリームの言語に関連付けられたコンポーネント タイプ。
MPEG2ComponentType | MPEG-2 ストリーム タイプに関連付けられたコンポーネント タイプに実装される。
ATSCComponentType | オーディオ ストリームが AC-3 フォーマットかどうかを示すコンポーネント タイプに実装される。

ロケータ オブジェクト

ロケータ オブジェクトは、グラフに含まれるネットワーク プロバイダおよびその他のフィルタが、ある種の場合に、チューニング要求に応えるため、チューニングの方法と対象の判断に使用する。アプリケーションではこれらのオブジェクトを使用しない。

Locator | ネットワーク タイプ固有のチューニング空間ロケータのための基底クラス。
MPEG2Locator | ネットワーク プロバイダから呼び出され、MPEG-2 ベースのネットワーク内におけるチューニングについて情報を取得する。アプリケーションでは使用しない。
ATSCLocator | ネットワーク プロバイダから呼び出され、ATSC ネットワーク内でのチューニングに関する情報を取得する。アプリケーションでは使用しない。
DVBTLocator | ネットワーク プロバイダから呼び出され、DVB-T ネットワーク内でのチューニングに関する情報を取得する。アプリケーションでは使用しない。
DVBSLocator | ネットワーク プロバイダから呼び出され、DVB-S ネットワーク内でのチューニングに関する情報を取得する。アプリケーションでは使用しない。


AnalogRadioTuningSpace オブジェクト

AnalogRadioTuningSpace オブジェクトは、AM または FM アナログ ラジオのチューニング空間を表す。

メソッド名またはプロパティ名 | 説明
CLSID | チューニング空間の CLSID を取得する。
CreateTuneRequest | このチューニング空間固有のチューニング要求オブジェクトを作成する。
DefaultLocator | インストール後にチューナーが使用できる初期のデフォルト ロケータを設定または取得する。
DefaultPreferredComponentTypes | ユーザーまたはアプリケーションから指定されたデフォルトの優先コンポーネント タイプが入った Components コレクション オブジェクト。
FriendlyName | チューニング空間のローカライズされたフレンドリ名。
MaxFrequency | このチューニング空間で使用可能な最大周波数 (KHz)。
MinFrequency | このチューニング空間で使用可能な最小周波数 (KHz)。
NetworkType | ネットワーク タイプの CLSID。
Step | このチューニング空間で使用する次の周波数までのデフォルトのステップ値 (KHz)。
UniqueName | チューニング空間を表すグローバルな固有の名称。

AnalogRadioTuningSpace.CLSID プロパティ

AnalogRadioTuningSpace オブジェクト

チューニング空間の CLSID を取得する。

構文

AnalogRadioTuningSpace.CLSID

可能な値

注意

このプロパティは、読み取り専用プロパティである。

AnalogRadioTuningSpace.CreateTuneRequest メソッド

AnalogRadioTuningSpace オブジェクト

このチューニング空間固有のチューニング要求オブジェクトを作成する。

構文

AnalogRadioTuningSpace.CreateTuneRequest()

戻り値

TuneRequest オブジェクトを返す。

AnalogRadioTuningSpace.DefaultLocator プロパティ

AnalogRadioTuningSpace オブジェクト

インストール後にチューナーが使用できる初期のデフォルト Locator オブジェクトを設定または取得する。

構文

AnalogRadioTuningSpace.DefaultLocator

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

AnalogRadioTuningSpace.DefaultPreferredComponentTypes プロパティ

AnalogRadioTuningSpace オブジェクト

ユーザーまたはアプリケーションから指定されたデフォルトの優先コンポーネント タイプが入った Components コレクション オブジェクト。

構文

AnalogRadioTuningSpace.DefaultPreferredComponentTypes

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

AnalogRadioTuningSpace.FriendlyName プロパティ

AnalogRadioTuningSpace オブジェクト

チューニング空間のフレンドリ名。

構文

AnalogRadioTuningSpace.FriendlyName

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

AnalogRadioTuningSpace.MaxFrequency プロパティ

AnalogRadioTuningSpace オブジェクト

このチューニング空間で使用可能な最大周波数 (KHz)。

構文

AnalogRadioTuningSpace.MaxFrequency

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

AnalogRadioTuningSpace.MinFrequency プロパティ

AnalogRadioTuningSpace オブジェクト

このチューニング空間で使用可能な最小周波数 (KHz)。

構文

AnalogRadioTuningSpace.MinFrequency

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

AnalogRadioTuningSpace.NetworkType プロパティ

AnalogRadioTuningSpace オブジェクト

ネットワーク タイプの CLSID。

構文

AnalogRadioTuningSpace.NetworkType

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

AnalogRadioTuningSpace.Step プロパティ

AnalogRadioTuningSpace オブジェクト

このチューニング空間で使用する次の周波数までのデフォルトのステップ値 (KHz)。

構文

AnalogRadioTuningSpace.Step

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

AnalogRadioTuningSpace.UniqueName プロパティ

AnalogRadioTuningSpace オブジェクト

チューニング空間を表すグローバルな固有の名称。

構文

AnalogRadioTuningSpace.UniqueName

可能な値

注意

このプロパティは、読み書き可能なプロパティである。


AnalogTVTuningSpace オブジェクト

アナログ TV のチューニング空間を表す。

メソッド名またはプロパティ名 | 説明
CLSID | チューニング空間の CLSID を取得する。
CountryCode | 物理ブロードキャスト ソースへの発信で最初にダイヤルする番号
CreateTuneRequest | チューニング要求オブジェクトを作成する。
DefaultLocator | インストール後にチューナーが使用できる初期のデフォルト ロケータを設定または取得する。
DefaultPreferredComponentTypes | ユーザーまたはアプリケーションから指定されたデフォルトの優先コンポーネント タイプが入った Components コレクション オブジェクト。
FriendlyName | チューニング空間のフレンドリ名。
InputType | このチューニング空間の入力タイプ。
MaxChannel | このチューニング空間で提供可能な最大チャンネル番号。
MinChannel | このチューニング空間で提供可能な最小チャンネル番号。
NetworkType | ネットワーク タイプ (CLSID)。
UniqueName | チューニング空間の固有の名称。

AnalogTVTuningSpace.CLSID プロパティ

AnalogTVTuningSpace オブジェクト

チューニング空間の CLSID を取得する。

構文

AnalogTVTuningSpace.CLSID

可能な値

注意

このプロパティは、読み取り専用プロパティである。

AnalogTVTuningSpace.CountryCode プロパティ

AnalogTVTuningSpace オブジェクト

物理ブロードキャスト ソースへの発信で最初にダイヤルする番号。

構文

AnalogTVTuningSpace.CountryCode

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

AnalogTVTuningSpace.CreateTuneRequest メソッド

AnalogTVTuningSpace オブジェクト

チューニング要求オブジェクトを作成する。

構文

AnalogTVTuningSpace.CreateTuneRequest()

戻り値

ChannelTuneRequest オブジェクトを返す。

AnalogTVTuningSpace.DefaultLocator プロパティ

AnalogTVTuningSpace オブジェクト

インストール後にチューナーが使用できる初期のデフォルト Locator オブジェクトを設定または取得する。

構文

AnalogTVTuningSpace.DefaultLocator

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

AnalogTVTuningSpace.DefaultPreferredComponentTypes プロパティ

AnalogTVTuningSpace オブジェクト

ユーザーまたはアプリケーションから指定されたデフォルトの優先コンポーネント タイプが入った Components コレクション オブジェクト。

構文

AnalogTVTuningSpace.DefaultPreferredComponentTypes

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

AnalogTVTuningSpace.FriendlyName プロパティ

AnalogTVTuningSpace オブジェクト

チューニング空間のフレンドリ名。

構文

AnalogTVTuningSpace.FriendlyName

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

AnalogTVTuningSpace.InputType プロパティ

AnalogTVTuningSpace オブジェクト

このチューニング空間の入力タイプ。

構文

AnalogTVTuningSpace.InputType

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

AnalogTVTuningSpace.MaxChannel プロパティ

AnalogTVTuningSpace オブジェクト

このチューニング空間で提供可能な最大チャンネル番号。

構文

AnalogTVTuningSpace.MaxChannel

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

AnalogTVTuningSpace.MinChannel プロパティ

AnalogTVTuningSpace オブジェクト

このチューニング空間で提供可能な最小チャンネル番号。

構文

AnalogTVTuningSpace.MinChannel

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

AnalogTVTuningSpace.NetworkType プロパティ

AnalogTVTuningSpace オブジェクト

ネットワーク タイプ (CLSID)。

構文

AnalogTVTuningSpace.NetworkType

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

AnalogTVTuningSpace.UniqueName プロパティ

AnalogTVTuningSpace オブジェクト

チューニング空間の固有の名称。

構文

AnalogTVTuningSpace.UniqueName

可能な値

注意

このプロパティは、読み書き可能なプロパティである。


ATSCChannelTuneRequest オブジェクト

メソッド名またはプロパティ名 | 説明
Channel | チャンネル。
Clone | このチューニング要求の新しいコピーを作成する。
Components | コンポーネントのコレクション。
Locator | ロケータ オブジェクト。
MinorChannel | マイナー チャンネル。
TuningSpace | チューニング空間オブジェクト。

ATSCChannelTuneRequest.Channel プロパティ

ATSCChannelTuneRequest オブジェクト

チャンネル。

構文

ATSCChannelTuneRequest.Channel

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

ATSCChannelTuneRequest.Clone メソッド

ATSCChannelTuneRequest オブジェクト

このチューニング要求の新しいコピーを作成する。

構文

ATSCChannelTuneRequest.Clone()

戻り値

現在のオブジェクトのコピーである ATSCChannelTuneRequest オブジェクトを返す。

ATSCChannelTuneRequest.Components プロパティ

ATSCChannelTuneRequest オブジェクト

コンポーネントのコレクション。

構文

ATSCChannelTuneRequest.Components

可能な値

注意

このプロパティは、読み取り専用プロパティである。

ATSCChannelTuneRequest.Locator プロパティ

ATSCChannelTuneRequest オブジェクト

ロケータ オブジェクト。

構文

ATSCChannelTuneRequest.Locator

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

ATSCChannelTuneRequest.MinorChannel プロパティ

ATSCChannelTuneRequest オブジェクト

マイナー チャンネル

構文

ATSCChannelTuneRequest.MinorChannel

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

ATSCChannelTuneRequest.TuningSpace プロパティ

ATSCChannelTuneRequest オブジェクト

チューニング空間オブジェクト。

構文

ATSCChannelTuneRequest.TuningSpace

可能な値

注意

このプロパティは、読み取り専用プロパティである。


ATSCComponentType オブジェクト

ATSC コンポーネント タイプを表す。

メソッド名またはプロパティ名 | 説明
Category | コンポーネントの一般カテゴリ。
Clone | このコンポーネント タイプのコピーを作成する。
Flags | ATSC コンポーネント タイプのフラグ。
LangID | サブストリーム コンテンツの言語を表す言語識別子。
StreamType | MPEG2 のストリーム タイプ。

ATSCComponentType.Category プロパティ

ATSCComponentType オブジェクト

コンポーネントの一般カテゴリ。

構文

ATSCComponentType.Category

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

ATSCComponentType.Clone メソッド

ATSCComponentType オブジェクト

このコンポーネント タイプのコピーを作成する。

構文

ATSCComponentType.Clone()

戻り値

現在のオブジェクトのコピーである ATSCComponentType オブジェクトを返す。

ATSCComponentType.Flags プロパティ

ATSCComponentType オブジェクト

ATSC コンポーネント タイプのフラグ。

構文

ATSCComponentType.Flags

可能な値

オーディオ ストリームが AC-3 の場合は 1。それ以外の場合は 0。

注意

このプロパティは、読み書き可能なプロパティである。

ATSCComponentType.LangID プロパティ

ATSCComponentType オブジェクト

サブストリーム コンテンツの言語を表す言語識別子。

構文

ATSCComponentType.LangID

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

ATSCComponentType.StreamType プロパティ

ATSCComponentType オブジェクト

MPEG2 のストリーム タイプ。

構文

ATSCComponentType.StreamType

可能な値

注意

このプロパティは、読み書き可能なプロパティである。


ATSCLocator オブジェクト

ATSC ネットワーク タイプ用のロケータ オブジェクト。

メソッド名またはプロパティ名 | 説明
CarrierFrequency | キャリア周波数 (デカ Hz)。
Clone | ロケータをコピーする。
InnerFEC | 内部 FEC タイプ。
InnerFECRate | 内部 FEC レート。
InnerFECRate | 内部 FEC レート。
Modulation | 変調タイプ。
OuterFEC | 外部 FEC タイプ。
OuterFECRate | 外部 FEC レート。
PhysicalChannel | 物理チャンネル。
TSID | トランスポート ストリーム ID。
SymbolRate | QPSK シンボル レートをセットあるいは取得する。

ATSCLocator.CarrierFrequency プロパティ

ATSCLocator オブジェクト

キャリア周波数 (デカ Hz)。

構文

ATSCLocator.CarrierFrequency

注意

このプロパティは、読み書き可能なプロパティである。

ATSCLocator.Clone メソッド

ATSCLocator オブジェクト

ロケータをコピーする。

構文

ATSCLocator.Clone()

戻り値

現在のオブジェクトのコピーである ATSCLocator オブジェクトを返す。

ATSCLocator.InnerFEC プロパティ

ATSCLocator オブジェクト

内部 FEC タイプ。

構文

ATSCLocator.InnerFEC

注意

このプロパティは、読み書き可能なプロパティである。

ATSCLocator.InnerFECRate プロパティ

ATSCLocator オブジェクト

内部 FEC レート。

構文

ATSCLocator.InnerFECRate

注意

このプロパティは、読み取り専用プロパティである。

ATSCLocator.InnerFECRate プロパティ

ATSCLocator オブジェクト

内部 FEC レート。

構文

ATSCLocator.InnerFECRate

注意

このプロパティは、読み取り専用プロパティである。

ATSCLocator.Modulation プロパティ

ATSCLocator オブジェクト

変調タイプ。

構文

ATSCLocator.Modulation

注意

このプロパティは、読み書き可能なプロパティである。

ATSCLocator.OuterFEC プロパティ

ATSCLocator オブジェクト

外部 FEC タイプ。

構文

ATSCLocator.OuterFEC

注意

このプロパティは、読み書き可能なプロパティである。

ATSCLocator.OuterFECRate プロパティ

ATSCLocator オブジェクト

外部 FEC レート。

構文

ATSCLocator.OuterFECRate

注意

このプロパティは、読み書き可能なプロパティである。

ATSCLocator.PhysicalChannel プロパティ

ATSCLocator オブジェクト

物理チャンネル。

構文

ATSCLocator.PhysicalChannel

注意

このプロパティは、読み書き可能なプロパティである。

ATSCLocator.TSID プロパティ

ATSCLocator オブジェクト

トランスポート ストリーム ID。

構文

ATSCLocator.TSID

注意

このプロパティは、読み書き可能なプロパティである。

ATSCLocator.SymbolRate プロパティ

ATSCLocator オブジェクト

QPSK シンボル レートをセットあるいは取得する。

構文

ATSCLocator.SymbolRate

注意

このプロパティは読み書き可能なプロパティである。QPSK は RF 信号にシンボルを変調する。これらのシンボルは復調器によって検出され、ビット ストリームを再構築するのに使われる。OPSK は変更のために変調/復調されるレートを許可する。


ATSCTuningSpace オブジェクト

ATSC ネットワーク タイプのチューニング空間を表す。

メソッド名またはプロパティ名 | 説明
CLSID | チューニング空間の CLSID を取得する。
CountryCode | 物理ブロードキャスト ソースへの発信で最初にダイヤルする番号。
CreateTuneRequest | チューニング要求オブジェクトを作成する。
DefaultLocator | インストール後にチューナーが使用できる初期のデフォルト ロケータを設定または取得する。
DefaultPreferredComponentTypes | ユーザーまたはアプリケーションから指定されたデフォルトの優先コンポーネント タイプが入った Components コレクション オブジェクト。
FriendlyName | チューニング空間のフレンドリ名。
InputType | このチューニング空間の入力タイプ。
MaxChannel | このチューニング空間で提供可能な最大チャンネル番号。
MaxMinorChannel | このチューニング空間で提供可能な最大のマイナー チャンネル番号。
MaxPhysicalChannel | このチューニング空間で提供可能な最大の物理チャンネル番号。
MinChannel | このチューニング空間で提供可能な最小チャンネル番号。
MinMinorChannel | このチューニング空間で提供可能な最小のマイナー チャンネル番号。
MinPhysicalChannel | このチューニング空間で提供可能な最小の物理チャンネル番号。
NetworkType | ネットワーク タイプ (CLSID)。
UniqueName | チューニング空間の固有の名称。

ATSCTuningSpace.CLSID プロパティ

ATSCTuningSpace オブジェクト

物理ブロードキャスト ソースを使用する国向けの、国際ダイヤル プレフィックス。

構文

ATSCTuningSpace.CLSID

可能な値

注意

このプロパティは、読み取り専用プロパティである。

ATSCTuningSpace.CountryCode プロパティ

ATSCTuningSpace オブジェクト

物理ブロードキャスト ソースへの発信で最初にダイヤルする番号。

構文

ATSCTuningSpace.CountryCode

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

ATSCTuningSpace.CreateTuneRequest メソッド

ATSCTuningSpace オブジェクト

チューニング要求オブジェクトを作成する。

構文

ATSCTuningSpace.CreateTuneRequest()

戻り値

ATSCChannelTuneRequest オブジェクトを返す。

ATSCTuningSpace.DefaultLocator プロパティ

ATSCTuningSpace オブジェクト

インストール後にチューナーが使用できる初期のデフォルト Locator オブジェクトを設定または取得する。

構文

ATSCTuningSpace.DefaultLocator

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

ATSCTuningSpace.DefaultPreferredComponentTypes プロパティ

ATSCTuningSpace オブジェクト

ユーザーまたはアプリケーションから指定されたデフォルトの優先コンポーネント タイプが入った Components コレクション オブジェクト。

構文

ATSCTuningSpace.DefaultPreferredComponentTypes

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

ATSCTuningSpace.FriendlyName プロパティ

ATSCTuningSpace オブジェクト

チューニング空間のフレンドリ名。

構文

ATSCTuningSpace.FriendlyName

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

ATSCTuningSpace.InputType プロパティ

ATSCTuningSpace オブジェクト

このチューニング空間の入力タイプ。

構文

ATSCTuningSpace.InputType

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

ATSCTuningSpace.MaxChannel プロパティ

ATSCTuningSpace オブジェクト

このチューニング空間で提供可能な最大チャンネル番号。

構文

ATSCTuningSpace.MaxChannel

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

ATSCTuningSpace.MaxMinorChannel プロパティ

ATSCTuningSpace オブジェクト

このチューニング空間で提供可能な最大のマイナー チャンネル番号。

構文

ATSCTuningSpace.MaxMinorChannel

可能な値

注意

このプロパティは、読み書き可能なプロパティである。最小マイナー チャンネルを最大マイナー チャンネルより大きくしないため、MinMinorChannel プロパティより先にこのプロパティを設定する必要がある。どちらのプロパティも、デフォルト値は -1 (設定なし) である。

ATSCTuningSpace.MaxPhysicalChannel プロパティ

ATSCTuningSpace オブジェクト

このチューニング空間で提供可能な最大の物理チャンネル番号。

構文

ATSCTuningSpace.MaxPhysicalChannel

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

ATSCTuningSpace.MinChannel プロパティ

ATSCTuningSpace オブジェクト

このチューニング空間で提供可能な最小チャンネル番号。

構文

ATSCTuningSpace.MinChannel

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

ATSCTuningSpace.MinMinorChannel プロパティ

ATSCTuningSpace オブジェクト

このチューニング空間で提供可能な最小のマイナー チャンネル番号。

構文

ATSCTuningSpace.MinMinorChannel

可能な値

注意

このプロパティは、読み書き可能なプロパティである。最小マイナー チャンネルを最大マイナー チャンネルより大きくしないため、このプロパティより先に MaxMinorChannel プロパティを設定する必要がある。どちらのプロパティも、デフォルト値は -1 (設定なし) である。

ATSCTuningSpace.MinPhysicalChannel プロパティ

ATSCTuningSpace オブジェクト

このチューニング空間で提供可能な最小の物理チャンネル番号。

構文

ATSCTuningSpace.MinPhysicalChannel

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

ATSCTuningSpace.MinPhysicalChannel プロパティ

ATSCTuningSpace オブジェクト

このチューニング空間で提供可能な最小の物理チャンネル番号。

構文

ATSCTuningSpace.MinPhysicalChannel

可能な値

注意

このプロパティは、読み取り専用プロパティである。

ATSCTuningSpace.NetworkType プロパティ

ATSCTuningSpace オブジェクト

ネットワーク タイプ (CLSID)。

構文

ATSCTuningSpace.NetworkType

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

ATSCTuningSpace.UniqueName プロパティ

ATSCTuningSpace オブジェクト

チューニング空間の固有の名称。

構文

ATSCTuningSpace.UniqueName

可能な値

注意

このプロパティは、読み書き可能なプロパティである。


ChannelTuneRequest オブジェクト

アナログ TV ネットワーク タイプ用の有効なチューニング要求を表す。

メソッド名またはプロパティ名 | 説明
Channel | このチューニング要求のチャンネルを取得または設定する。
Clone | このチューニング要求の新しいコピーを作成する。
Components | コンポーネントのコレクション。
Locator | ロケータ オブジェクト。
TuningSpace | チューニング空間オブジェクト。

ChannelTuneRequest.Channel プロパティ

ChannelTuneRequest オブジェクト

チャンネル。

構文

ChannelTuneRequest.Channel

可能な値

注意

このプロパティは、読み書き可能なプロパティである。チャンネルの指定値がチューニング空間に設定された最小チャンネルより小さい場合は、最大チャンネルに "ラップ アラウンド" する。同様に、チャンネルの指定値がチューニング空間に設定された最大チャンネルより大きい場合は、最小チャンネルに "ラップ アラウンド" する。

ChannelTuneRequest.Clone メソッド

ChannelTuneRequest オブジェクト

このチューニング要求の新しいコピーを作成する。

構文

ChannelTuneRequest.Clone(NewTuneRequest)

戻り値

現在のオブジェクトのコピーである ChannelTuneRequest オブジェクトを返す。

ChannelTuneRequest.Components プロパティ

ChannelTuneRequest オブジェクト

コンポーネントのコレクション。

構文

ChannelTuneRequest.Components

可能な値

注意

このプロパティは、読み取り専用プロパティである。

ChannelTuneRequest.Locator プロパティ

ChannelTuneRequest オブジェクト

ロケータ オブジェクト。

構文

ChannelTuneRequest.Locator

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

ChannelTuneRequest.TuningSpace プロパティ

ChannelTuneRequest オブジェクト

チューニング空間オブジェクト。

構文

ChannelTuneRequest.TuningSpace

可能な値

注意

このプロパティは、読み取り専用プロパティである。


Component オブジェクト

現在のブロードキャスト ストリームに含まれるコンポーネントまたはサブストリームを表す。

メソッド名またはプロパティ名 | 説明
Clone | コンポーネントをコピーする。
DescLangID | 解説言語の言語識別子。
Description | コンポーネントの説明。
Status | コンポーネントの状態。
Type | コンポーネントのタイプ。

Component.Clone メソッド

Component オブジェクト

コンポーネントをコピーする。

構文

Component.Clone()

戻り値

現在のオブジェクトのコピーである Component オブジェクトを返す。

Component.DescLangID プロパティ。

Component オブジェクト

解説言語の言語識別子。

構文

Component.DescLangID

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

Component.Description プロパティ

Component オブジェクト

コンポーネントの説明。

構文

Component.Description

可能な値

注意

このプロパティは、読み取り専用プロパティである。

Component.Status プロパティ

Component オブジェクト

コンポーネントの状態。

構文

Component.Status

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

Component.Type プロパティ

Component オブジェクト

コンポーネントのタイプ。

構文

Component.Type

可能な値

注意

このプロパティは、読み取り専用プロパティである。


Components オブジェクト

Component オブジェクトのコレクションを表す。

メソッド名またはプロパティ名 | 説明
Add | コンポーネントをコレクションに追加する。
Clone | このオブジェクトの新しいコピーを作成する。
Count | コレクションに含まれる項目の数。
Item | 指定されたインデックス位置のコンポーネントを取得する。
Remove | 指定されたインデックス位置のコンポーネントを削除する。

Components.Add メソッド

Components オブジェクト

コンポーネントをコレクションに追加する。

構文

Components.Add(Component)

パラメータ

Component コレクションに追加する Component オブジェクト。

戻り値

成功した場合は、新しく追加したオブジェクトのインデックス値を返す。

注意

参照

Components.Clone メソッド

Components オブジェクト

このオブジェクトの新しいコピーを作成する。

構文

Components.Clone

注意

参照

Components.Count プロパティ

Components オブジェクト

コレクションに含まれる項目の数。

構文

Components.Count

注意

このプロパティは、読み取り専用プロパティである。

参照

Components.Item プロパティ

Components オブジェクト

指定されたインデックス位置のコンポーネントを取得する。

構文

Components.Item(Index,ppComponent)

パラメータ

Index 取得する項目のインデックス。

可能な値

Component オブジェクトを返す。

注意

このプロパティは、読み取り専用プロパティである。

参照

Components.Remove メソッド

Components オブジェクト

指定されたインデックス位置のコンポーネントを削除する。

構文

Components.Remove(Index)

パラメータ

Index コレクションから削除する Component オブジェクトのインデックス値。

戻り値

注意

参照


ComponentType オブジェクト

DVB プログラム ストリームでは、オーディオ ストリームなどの基本ストリームをコンポーネントと言う。この基本ストリームのプロパティを記述するのが ComponentType オブジェクトである。

メソッド名またはプロパティ名 | 説明
Category | コンポーネントの一般カテゴリ。
Clone | このコンポーネント タイプのコピーを作成する。
MediaFormatType | DirectShow メディア タイプのフォーマット GUID。
MediaMajorType | DirectShow メディア タイプのメジャー タイプ GUID。
MediaSubType | DirectShow メディア タイプのサブタイプ GUID。

ComponentType.Category プロパティ

ComponentType オブジェクト

コンポーネントの一般カテゴリ。

構文

ComponentType.Category

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

参照

ComponentType.Clone メソッド

ComponentType オブジェクト

このコンポーネント タイプのコピーを作成する。

構文

ComponentType.Clone();

戻り値

現在のオブジェクトと同じ値を持つ新しい ComponentType オブジェクトを返す。

注意

参照

ComponentType.MediaFormatType プロパティ

ComponentType オブジェクト

DirectShow メディア タイプのフォーマット GUID。

構文

ComponentType.MediaFormatType

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

参照

ComponentType.MediaMajorType プロパティ

ComponentType オブジェクト

DirectShow メディア タイプのメジャー タイプ GUID。

構文

ComponentType.MediaMajorType

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

参照

ComponentType.MediaSubType プロパティ

ComponentType オブジェクト

DirectShow メディア タイプのサブタイプ GUID。

構文

ComponentType.MediaSubType

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

参照


ComponentTypes オブジェクト

ComponentType オブジェクトのコレクションを表す。

メソッド名またはプロパティ名 | 説明
Add | ComponentType をコレクションに追加する。
Clone | このオブジェクトの新しいコピーを作成する。
Count | コレクションに含まれる項目の数。
Item | 指定されたインデックス位置の ComponentType を取得する。
Remove | コレクションを消去する。

ComponentTypes.Add メソッド

ComponentTypes オブジェクト

ComponentType をコレクションに追加する。

構文

ComponentTypes.Add(ComponentType)

パラメータ

ComponentType コレクションに追加する ComponentType オブジェクト。

戻り値

成功した場合は、新しく追加したオブジェクトのインデックス値を返す。

注意

参照

ComponentTypess.Clone メソッド

ComponentTypes オブジェクト

このオブジェクトの新しいコピーを作成する。

構文

ComponetTypes.Clone

ComponentTypes.Count プロパティ

ComponentTypes オブジェクト

コレクションに含まれる項目の数。

構文

ComponentTypes.Count

注意

このプロパティは、読み取り専用プロパティである。

参照

ComponentTypes.Item プロパティ

ComponentTypes オブジェクト

指定されたインデックス位置の ComponentType を取得する。

構文

ComponentTypes.Item(Index,ComponentType)

パラメータ

Index コレクションに含まれる ComponentType オブジェクトのインデックス。

可能な値

ComponentType オブジェクトを返す。

注意

このプロパティは、読み書き可能なプロパティである。

参照

ComponentTypes.Remove メソッド

ComponentTypes オブジェクト

コレクションを消去する。

構文

ComponentTypes.Remove(Index)

パラメータ

Index 削除する ComponentType オブジェクトのインデックス。

戻り値

注意

参照


DVBSLocator オブジェクト

DVBS ネットワーク タイプ用のロケータ オブジェクト。

メソッド名またはプロパティ名 | 説明
Azimuth | 方位角 (1/10°単位)。
CarrierFrequency | キャリア周波数 (デカ Hz)。
Clone | ロケータをコピーする。
Elevation | 衛星の仰角 (1/10°単位)。
InnerFEC | 内部 FEC タイプ。
InnerFECRate | 内部 FEC レート。
Modulation | 変調タイプ。
OrbitalPosition | 経度 (1/10°単位)。
OuterFEC | 外部 FEC タイプ。
OuterFECRate | 外部 FEC レート。
SignalPolarisation | 信号のポラリゼーション タイプ。
SymbolRate | QPSK シンボル レートをセットあるいは取得する。
WestPosition | VARIANT_TRUE は軌道位置を西経で表現することを意味する。

DVBSLocator.Azimuth プロパティ

DVBSLocator オブジェクト

方位角 (1/10°単位)。

構文

DVBSLocator.Azimuth

注意

このプロパティは、読み書き可能なプロパティである。

DVBSLocator.CarrierFrequency プロパティ

DVBSLocator オブジェクト

キャリア周波数 (デカ Hz)。

構文

DVBSLocator.CarrierFrequency

注意

このプロパティは、読み書き可能なプロパティである。

DVBSLocator.Clone メソッド

DVBSLocator オブジェクト

ロケータをコピーする。

構文

DVBSLocator.Clone()

戻り値

現在のオブジェクトのコピーである DVBSLocator オブジェクトを返す。

DVBSLocator.Elevation プロパティ

DVBSLocator オブジェクト

衛星の高度 (1/10°単位)。

構文

DVBSLocator.Elevation

注意

このプロパティは、読み書き可能なプロパティである。

DVBSLocator.InnerFEC プロパティ

DVBSLocator オブジェクト

内部 FEC タイプ。

構文

DVBSLocator.InnerFEC

注意

このプロパティは、読み書き可能なプロパティである。

DVBSLocator.InnerFECRate プロパティ

DVBSLocator オブジェクト

内部 FEC レート。

構文

DVBSLocator.InnerFECRate

注意

このプロパティは、読み取り専用プロパティである。

DVBSLocator.Modulation プロパティ

DVBSLocator オブジェクト

変調タイプ。

構文

DVBSLocator.Modulation

注意

このプロパティは、読み書き可能なプロパティである。

DVBSLocator.OrbitalPosition プロパティ

DVBSLocator オブジェクト

経度 (1/10°単位)。

構文

DVBSLocator.OrbitalPosition

注意

このプロパティは、読み書き可能なプロパティである。

DVBSLocator.OuterFEC プロパティ

DVBSLocator オブジェクト

外部 FEC タイプ。

構文

DVBSLocator.OuterFEC

注意

このプロパティは、読み書き可能なプロパティである。

DVBSLocator.OuterFECRate プロパティ

DVBSLocator オブジェクト

外部 FEC レート。

構文

DVBSLocator.OuterFECRate

注意

このプロパティは、読み書き可能なプロパティである。

DVBSLocator.SignalPolarisation プロパティ

DVBSLocator オブジェクト

信号のポラリゼーション タイプ。

構文

DVBSLocator.SignalPolarisation

注意

このプロパティは、読み書き可能なプロパティである。

DVBSLocator.SymbolRate プロパティ

DVBSLocator オブジェクト

QPSK シンボル レートをセットあるいは取得する。

構文

DVBSLocator.SymbolRate

注意

このプロパティは読み書き可能なプロパティである。QPSK は RF 信号にシンボルを変調する。これらのシンボルは復調器によって検出され、ビット ストリームを再構築するのに使われる。OPSK は変更のために変調/復調されるレートを許可する。

DVBSLocator.WestPosition プロパティ

DVBSLocator オブジェクト

VARIANT_TRUE は軌道位置を西経で表現することを意味する。

構文

DVBSLocator.WestPosition

注意

このプロパティは、読み書き可能なプロパティである。


DVBTLocator オブジェクト

DVBT ネットワーク タイプ用のロケータ オブジェクト。

メソッド名またはプロパティ名 | 説明
Bandwidth | 帯域幅。
CarrierFrequency | キャリア周波数 (デカ Hz)。
Clone | ロケータをコピーする。
Guard | ガード間隔。
HAlpha | 階層状アルファ。
InnerFEC | 内部 FEC タイプ。
InnerFECRate | 内部 FEC レート。
InnerFECRate | 内部 FEC レート。
LPInnerFEC | 優先度が低いストリームの内部 FEC タイプ。
LPInnerFECRate | 優先度が低いストリームの内部 FEC レート。
Mode | 伝送モード。
Modulation | 変調タイプ。
OtherFrequencyInUse | 階層状アルファ。
OuterFEC | 外部 FEC タイプ。
OuterFECRate | 外部 FEC レート。
SymbolRate | QPSK シンボル レートをセットあるいは取得する。

DVBTLocator.Bandwidth プロパティ

DVBTLocator オブジェクト

帯域幅。

構文

DVBTLocator.Bandwidth

注意

このプロパティは、読み書き可能なプロパティである。

DVBTLocator.CarrierFrequency プロパティ

DVBTLocator オブジェクト

キャリア周波数 (デカ Hz)。

構文

DVBTLocator.CarrierFrequency

注意

このプロパティは、読み書き可能なプロパティである。

DVBTLocator.Clone メソッド

DVBTLocator オブジェクト

ロケータをコピーする。

構文

DVBTLocator.Clone()

戻り値

現在のオブジェクトのコピーである DVBTLocator オブジェクトを返す。

DVBTLocator.Guard プロパティ

DVBTLocator オブジェクト

ガード間隔。

構文

DVBTLocator.Guard

注意

このプロパティは、読み書き可能なプロパティである。

DVBTLocator.HAlpha プロパティ

DVBTLocator オブジェクト

階層状アルファ。

構文

DVBTLocator.HAlpha

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

DVBTLocator.InnerFEC プロパティ

DVBTLocator オブジェクト

内部 FEC タイプ。

構文

DVBTLocator.InnerFEC

注意

このプロパティは、読み書き可能なプロパティである。

DVBTLocator.InnerFECRate プロパティ

DVBTLocator オブジェクト

内部 FEC レート。

構文

DVBTLocator.InnerFECRate

注意

このプロパティは、読み取り専用プロパティである。

DVBTLocator.InnerFECRate プロパティ

DVBTLocator オブジェクト

内部 FEC レート。

構文

DVBTLocator.InnerFECRate

注意

このプロパティは、読み取り専用プロパティである。

DVBTLocator.LPInnerFEC プロパティ

DVBTLocator オブジェクト

優先度が低いストリームの内部 FEC タイプ。

構文

DVBTLocator.LPInnerFEC

注意

このプロパティは、読み書き可能なプロパティである。

DVBTLocator.LPInnerFECRate プロパティ

DVBTLocator オブジェクト

優先度が低いストリームの内部 FEC レート。

構文

DVBTLocator.LPInnerFECRate

注意

このプロパティは、読み書き可能なプロパティである。

DVBTLocator.Mode プロパティ

DVBTLocator オブジェクト

伝送モード。

構文

DVBTLocator.Mode

注意

このプロパティは、読み書き可能なプロパティである。

DVBTLocator.Modulation プロパティ

DVBTLocator オブジェクト

変調タイプ。

構文

DVBTLocator.Modulation

注意

このプロパティは、読み書き可能なプロパティである。

DVBTLocator.OtherFrequencyInUse プロパティ

DVBTLocator オブジェクト

階層状アルファ。

構文

DVBTLocator.OtherFrequencyInUse

注意

このプロパティは、読み書き可能なプロパティである。

DVBTLocator.OuterFEC プロパティ

DVBTLocator オブジェクト

外部 FEC タイプ。

構文

DVBTLocator.OuterFEC

注意

このプロパティは、読み書き可能なプロパティである。

DVBTLocator.OuterFECRate プロパティ

DVBTLocator オブジェクト

外部 FEC レート。

構文

DVBTLocator.OuterFECRate

注意

このプロパティは、読み書き可能なプロパティである。

DVBTLocator.SymbolRate プロパティ

DVBTLocator オブジェクト

QPSK シンボル レートをセットあるいは取得する。

構文

DVBTLocator.SymbolRate

注意

このプロパティは読み書き可能なプロパティである。QPSK は RF 信号にシンボルを変調する。これらのシンボルは復調器によって検出され、ビット ストリームを再構築するのに使われる。OPSK は変更のために変調/復調されるレートを許可する。


DVBTuneRequest オブジェクト

DVB ネットワーク タイプ用の有効なチューニング要求を表す。

メソッド名またはプロパティ名 | 説明
Clone | このチューニング要求の新しいコピーを作成する。
Components | コンポーネントのコレクション。
Locator | ロケータ オブジェクト。
ONID | 元のネットワーク ID。
SID | サービス ID。
TSID | トランスポート ストリーム ID。
TuningSpace | チューニング空間オブジェクト。

DVBTuneRequest.Clone メソッド

DVBTuneRequest オブジェクト

このチューニング要求の新しいコピーを作成する。

構文

DVBTuneRequest.Clone()

戻り値

現在のオブジェクトのコピーである DVBTuneRequest オブジェクトを返す。

DVBTuneRequest.Components プロパティ

DVBTuneRequest オブジェクト

コンポーネントのコレクション。

構文

DVBTuneRequest.Components

可能な値

注意

このプロパティは、読み取り専用プロパティである。

DVBTuneRequest.Locator プロパティ

DVBTuneRequest オブジェクト

ロケータ オブジェクト。

構文

DVBTuneRequest.Locator

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

DVBTuneRequest.ONID プロパティ

DVBTuneRequest オブジェクト

元のネットワーク ID。

構文

DVBTuneRequest.ONID

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

DVBTuneRequest.SID プロパティ

DVBTuneRequest オブジェクト

サービス ID。

構文

DVBTuneRequest.SID

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

DVBTuneRequest.TSID プロパティ

DVBTuneRequest オブジェクト

トランスポート ストリーム ID。

構文

DVBTuneRequest.TSID

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

DVBTuneRequest.TuningSpace プロパティ

DVBTuneRequest オブジェクト

チューニング空間オブジェクト。

構文

DVBTuneRequest.TuningSpace

可能な値

注意

このプロパティは、読み取り専用プロパティである。


DVBTuningSpace オブジェクト

DVB ネットワーク タイプのチューニング空間を表す。

メソッド名またはプロパティ名 | 説明
CLSID | チューニング空間の CLSID を取得する。
CreateTuneRequest | DVBTuneRequest オブジェクトを作成する。
DefaultLocator | インストール後にチューナーが使用できる初期のデフォルト ロケータを設定または取得する。
DefaultPreferredComponentTypes | ユーザーまたはアプリケーションから指定されたデフォルトの優先コンポーネント タイプが入った Components コレクション オブジェクト。
FrequencyMapping | ネットワーク プロバイダが定義するチャンネルと周波数のマッピングが入った文字列を設定または取得する。
FriendlyName | チューニング空間のフレンドリ名。
NetworkType | ネットワーク タイプ (CLSID)。
SystemType | DVB システムのタイプ。
UniqueName | チューニング空間の固有の名称。

DVBTuningSpace.CLSID プロパティ

DVBTuningSpace オブジェクト

チューニング空間の CLSID を取得する。

構文

DVBTuningSpace.CLSID

可能な値

注意

このプロパティは、読み取り専用プロパティである。

DVBTuningSpace.CreateTuneRequest メソッド

DVBTuningSpace オブジェクト

DVBTuneRequest オブジェクトを作成する。

構文

DVBTuningSpace.CreateTuneRequest()

戻り値

DVBTuneRequest オブジェクトを返す。

DVBTuningSpace.DefaultLocator プロパティ

DVBTuningSpace オブジェクト

インストール後にチューナーが使用できる初期のデフォルト Locator オブジェクトを設定または取得する。

構文

DVBTuningSpace.DefaultLocator

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

DVBTuningSpace.DefaultPreferredComponentTypes プロパティ

DVBTuningSpace オブジェクト

ユーザーまたはアプリケーションから指定されたデフォルトの優先コンポーネント タイプが入った Components コレクション オブジェクト。

構文

DVBTuningSpace.DefaultPreferredComponentTypes

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

DVBTuningSpace.FrequencyMapping プロパティ

DVBTuningSpace オブジェクト

ネットワーク プロバイダが定義するチャンネルと周波数のマッピングが入った文字列を設定または取得する。

構文

DVBTuningSpace.FrequencyMapping

可能な値

ネットワーク プロバイダが定義したマッピング テーブルが格納された文字列。

注意

このプロパティは、読み書き可能なプロパティである。この文字列には、周波数とチャンネルのマッピング、周波数と中継器のマッピング、またはキャリア周波数から周波数識別子への、チューニング空間に適したその他のあらゆるマッピングを格納できる。

DVBTuningSpace.FriendlyName プロパティ

DVBTuningSpace オブジェクト

チューニング空間のフレンドリ名。

構文

DVBTuningSpace.FriendlyName

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

DVBTuningSpace.NetworkType プロパティ

DVBTuningSpace オブジェクト

ネットワーク タイプ (CLSID)。

構文

DVBTuningSpace.NetworkType

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

DVBTuningSpace.SystemType プロパティ

DVBTuningSpace オブジェクト

DVB システムのタイプ。

構文

DVBTuningSpace.SystemType

可能な値

注意

このプロパティは、読み書き可能なプロパティである。

DVBTuningSpace.UniqueName プロパティ

DVBTuningSpace オブジェクト

チューニング空間の固有の名称。

構文

DVBTuningSpace.UniqueName

可能な値

注意

このプロパティは、読み書き可能なプロパティである。


LanguageComponentType オブジェクト

ブロードキャスト ストリームに含まれる単独コンポーネント (サブストリーム) の言語コンポーネント タイプを表す。

メソッド名またはプロパティ名 | 説明
Category | コンポーネントの一般カテゴリ。
Clone | このコンポーネント タイプのコピーを作成する。
LangID | サブストリーム コンテンツの言語を表す言語識別子。

LanguageComponentType.Category プロパティ

LanguageComponentType オブジェクト

コンポーネントの一般カテゴリ。

構文

LanguageComponentType.Category

注意

このプロパティは、読み書き可能なプロパティである。

LanguageComponentType.Clone メソッド

LanguageComponentType オブジェクト

このコンポーネント タイプのコピーを作成する。

構文

LanguageComponentType.Clone()

戻り値

現在のオブジェクトのコピーである LanguageComponentType オブジェクトを返す。

LanguageComponentType.LangID プロパティ

LanguageComponentType オブジェクト

サブストリーム コンテンツの言語を表す言語識別子。

構文

LanguageComponentType.LangID

注意

このプロパティは、読み書き可能なプロパティである。


MPEG2Component オブジェクト

MPEG-2 ブロードキャスト ストリームに含まれる単独のコンポーネント (サブストリーム) を表す。

メソッド名またはプロパティ名 | 説明
Clone | コンポーネントをコピーする。
DescLangID | 解説言語の言語識別子。
Description | コンポーネントの説明。
PCRPID | このサブストリームのタイム スタンプに対応する MPEG2 パケット ID。
PID | このサブストリームの MPEG2 パケット ID。
ProgramNumber | MPEG2 のプログラム番号。
Status | コンポーネントの状態。
Type | コンポーネントのタイプ。

MPEG2Component.Clone メソッド

MPEG2Component オブジェクト

コンポーネントをコピーする。

構文

MPEG2Component.Clone()

戻り値

現在のオブジェクトのコピーである MPEG2Component オブジェクトを返す。

MPEG2Component.DescLangID プロパティ

MPEG2Component オブジェクト

解説言語の言語識別子。

構文

MPEG2Component.DescLangID

注意

このプロパティは、読み書き可能なプロパティである。

MPEG2Component.Description プロパティ

MPEG2Component オブジェクト

コンポーネントの説明。

構文

MPEG2Component.Description

注意

このプロパティは、読み取り専用プロパティである。

MPEG2Component.PCRPID プロパティ

MPEG2Component オブジェクト

このサブストリームのタイム スタンプに対応する MPEG2 パケット ID。

構文

MPEG2Component.PCRPID

注意

このプロパティは、読み書き可能なプロパティである。

MPEG2Component.PID プロパティ

MPEG2Component オブジェクト

このサブストリームの MPEG2 パケット ID。

構文

MPEG2Component.PID

注意

このプロパティは、読み書き可能なプロパティである。

MPEG2Component.ProgramNumber プロパティ

MPEG2Component オブジェクト

MPEG2 のプログラム番号。

構文

MPEG2Component.ProgramNumber

注意

このプロパティは、読み書き可能なプロパティである。

MPEG2Component.Status プロパティ

MPEG2Component オブジェクト

コンポーネントの状態。

構文

MPEG2Component.Status

注意

このプロパティは、読み書き可能なプロパティである。

MPEG2Component.Type プロパティ

MPEG2Component オブジェクト

コンポーネントのタイプ。

構文

MPEG2Component.Type

注意

このプロパティは、読み取り専用プロパティである。


MPEG2ComponentType オブジェクト

MPEG-2 ストリームに含まれる単独コンポーネントのストリーム タイプを表す。

メソッド名またはプロパティ名 | 説明
Category | コンポーネントの一般カテゴリ。
Clone | このコンポーネント タイプのコピーを作成する。
LangID | サブストリーム コンテンツの言語を表す言語識別子。
StreamType | MPEG2 のストリーム タイプ。

MPEG2ComponentType.Category プロパティ

MPEG2ComponentType オブジェクト

コンポーネントの一般カテゴリ。

構文

MPEG2ComponentType.Category

注意

このプロパティは、読み書き可能なプロパティである。

MPEG2ComponentType.Clone メソッド

MPEG2ComponentType オブジェクト

このコンポーネント タイプのコピーを作成する。

構文

MPEG2ComponentType.Clone()

戻り値

現在のオブジェクトのコピーである MPEG2ComponentType オブジェクトを返す。

MPEG2ComponentType.LangID プロパティ

MPEG2ComponentType オブジェクト

サブストリーム コンテンツの言語を表す言語識別子。

構文

MPEG2ComponentType.LangID

注意

このプロパティは、読み書き可能なプロパティである。

MPEG2ComponentType.StreamType プロパティ

MPEG2ComponentType オブジェクト

MPEG2 のストリーム タイプ。

構文

MPEG2ComponentType.StreamType

注意

このプロパティは、読み書き可能なプロパティである。


SystemTuningSpaces オブジェクト

SystemTuningSpaces オブジェクトには、ローカル システム上で現在利用可能な全チューニング空間のコレクションが格納される。また、このオブジェクトは、新しいチューニング空間を追加したり、既存のチューニング空間を削除したりするメソッドを提供する。

メソッド名またはプロパティ名 | 説明
Add | コレクションに新しいチューニング空間を追加する。このチューニング空間は削除されるまで持続する。
Count | コレクションに含まれる項目の数。
FindID | 指定されたチューニング空間のローカルな ID 番号を検索する。
Item | 指定されたインデックスを持つチューニング空間を検索するか、またはコレクションに含まれる既存のチューニング空間を更新する。
MaxCount | コレクション内で許される項目の最大数を取得する。
Remove | コレクションからチューニング空間を削除する。このチューニング空間はレジストリから削除される。
TuningSpacesForCLSID | 同じ実装を持つチューニング空間のコレクションを返す。
TuningSpacesForName | 名前に一致するチューニング空間のコレクションを返す。

SystemTuningSpaces.Add メソッド

SystemTuningSpaces オブジェクト

コレクションに新しいチューニング空間を追加する。このチューニング空間は削除されるまで持続する。

構文

SystemTuningSpaces.Add(TuningSpace)

パラメータ

TuningSpace 追加するチューニング空間オブジェクト (ATSCTuningSpace、DVBTuningSpace など)。

戻り値

成功した場合は、新しく追加したオブジェクトのインデックスを返す。

SystemTuningSpaces.Count プロパティ

SystemTuningSpaces オブジェクト

コレクションに含まれる項目の数。

構文

SystemTuningSpaces.Count

注意

このプロパティは、読み取り専用プロパティである。

SystemTuningSpaces.FindID メソッド

SystemTuningSpaces オブジェクト

指定されたチューニング空間のローカル一意識別子を検索する。

構文

SystemTuningSpaces.FindID(TuningSpace)

パラメータ

TuningSpace 識別子を取得するオブジェクト。

戻り値

成功した場合は、指定されたオブジェクトの識別子を返す。

SystemTuningSpaces.Item プロパティ

SystemTuningSpaces オブジェクト

指定されたインデックスを持つチューニング空間を検索するか、またはコレクションに含まれる既存のチューニング空間を更新する。

構文

SystemTuningSpaces.Item(varIndex)

パラメータ

varIndex 設定または取得するチューニング空間オブジェクトのインデックス。

可能な値

任意の有効なチューニング空間オブジェクト (ATSCTuningSpace、DVBTuningSpace など)。

注意

このプロパティは、読み書き可能なプロパティである。チューニング空間オブジェクトを設定すると、変更内容がバッキング ストアに持続的に保存される。

SystemTuningSpaces.MaxCount プロパティ

SystemTuningSpaces オブジェクト

コレクション内で許される項目の最大数を取得する。

構文

SystemTuningSpaces.MaxCount

注意

このプロパティは、スクリプトからは読み取り専用である。C++ アプリケーションでは、この値を修正することも、レジストリ内で修正することもできる。

SystemTuningSpaces.Remove プロパティ

SystemTuningSpaces オブジェクト

コレクションからチューニング空間を削除する。このチューニング空間はレジストリから削除される。

構文

SystemTuningSpaces.Remove

注意

このプロパティは、読み書き可能なプロパティである。

SystemTuningSpaces.TuningSpacesForCLSID メソッド

SystemTuningSpaces オブジェクト

同じ実装を持つチューニング空間のコレクションを返す。

構文

SystemTuningSpaces.TuningSpacesForCLSID(SpaceCLSID)

パラメータ

SpaceCLSID 検索するチューニング空間の CLSID。

戻り値

成功した場合は、CLSID に一致するチューニング空間オブジェクトのコレクションが格納された SystemTuningSpaces オブジェクトを返す。

SystemTuningSpaces.TuningSpacesForName メソッド

SystemTuningSpaces オブジェクト

名前に一致するチューニング空間のコレクションを返す。

構文

SystemTuningSpaces.TuningSpacesForName(Name)

パラメータ

Name 検索するチューニング空間のローカルな固有の名称。

戻り値

成功した場合は、指定された名前に一致するチューニング空間が格納された SystemTuningSpaces オブジェクトを返す。


DirectShow フィルタの開発

Microsoft® DirectShow® フィルタ グラフで使用するフィルタの開発は、このセクションのトピックに従って行う。一般に、アプリケーションはここで説明するようなレベルでフィルタやフィルタ グラフにアクセスすることはないため、アプリケーション開発者がこれらのトピックを参照する必要はない。

  • フィルタ開発者のための DirectShow アーキテクチャ
  • DirectShow と COM
  • 変換フィルタ
  • ビデオ レンダラ
  • キャプチャ フィルタ
  • キャプチャ フォーマットと圧縮フォーマットの公開
  • フィルタのカテゴリ
  • ファイル フォーマット


フィルタ開発者のための DirectShow アーキテクチャ

このセクションでは、Microsoft® DirectShow® アーキテクチャをフィルタ開発者向けの詳細なレベルで説明する。このセクションのトピックを読む前に、「ファースト ステップ ガイド」を参照すること。DirectShow アプリケーションを開発する際にフィルタの開発を行わない場合は、このセクションをとばすか、ざっと目を通す程度でも問題はない。

  • フィルタの接続
  • フィルタ開発者が使用するデータ フロー
  • DirectShow のタイムとクロック
  • 品質コントロールの管理


フィルタの接続

ここでは、Microsoft® DirectShow® でフィルタがどのように接続されるかについて説明する。このトピックはフィルタの開発者を対象としている。DirectShow アプリケーションを作成している場合、このトピックの詳細説明は必ずしも重要ではない。

ここでは、以下の項目について説明する。

  • ピン接続
  • メディア タイプの調整
  • アロケータの調整
  • ピンの再接続

ピン接続

フィルタは IPin インターフェイスを介してピンで接続される。出力ピンは入力ピンに接続する。各ピン接続にはメディア タイプがあり、AM_MEDIA_TYPE 構造体に記述される。

アプリケーションは、フィルタ グラフ マネージャでメソッドを呼び出すことで、フィルタに接続する。フィルタやピン自体にメソッドを呼び出すことはしない。アプリケーションは、IFilterGraph::ConnectDirect メソッドや IGraphBuilder::Connect メソッドを呼び出すことで接続するフィルタを直接指定できる。また、IGraphBuilder::RenderFile などのグラフ構築メソッドのいずれかを使って、間接的にフィルタに接続することもできる。

正常に接続するために、両方のフィルタがフィルタ グラフ内になければならない。アプリケーションは、IFilterGraph::AddFilter メソッドを呼び出すことで、フィルタをフィルタ グラフに追加できる。フィルタ グラフ マネージャも、フィルタを作成してフィルタ グラフに追加できる。どちらの場合も、フィルタ グラフ マネージャはフィルタの IBaseFilter::JoinFilterGraph メソッドを呼び出してフィルタに通知する。

大まかな接続プロセスは次のようになる。

  1. フィルタ グラフ マネージャが出力ピンに対して IPin::Connect を呼び出し、入力ピンへのポインタを渡す。
  2. 出力ピンが接続を受け入れる場合、入力ピンに対して IPin::ReceiveConnection を呼び出す。
  3. 入力ピンも接続を受け入れる場合、接続が成功し、ピンが接続される。

一部のピンは、フィルタがアクティブである間でも接続解除や再接続が可能である。このような再接続は動的再接続と呼ばれる。詳細については、「動的グラフ作成」を参照すること。ただし、多くのフィルタは動的再接続をサポートしていない。

フィルタは通常、ダウンストリーム順に接続される。つまりフィルタの出力ピンの前に入力ピンが接続される。フィルタは常にこの順での接続をサポートする必要がある。一部のフィルタは逆順の接続もサポートしている。つまり、出力ピンが先で、その後に入力ピンが接続される。たとえば、MUX フィルタの入力ピンを接続する前に、MUX フィルタの出力ピンをフィルタ ライタ フィルタに接続することができる。

メディア タイプの調整

フィルタ グラフ マネージャが IPin::Connect メソッドを呼び出すときに、次のオプションでメディア タイプを指定する。

  • 完全なタイプ: メディア タイプが詳細に指定されている場合、ピンはそのタイプでの接続を試みる。接続できない場合、接続は失敗する。
  • 不完全なメディア タイプ: メジャー タイプ、サブタイプ、またはフォーマット タイプのいずれかが GUID_NULL である場合、メディア タイプは不完全である。値 GUID_NULL は、任意の値を受け入れ可能であることを示す "ワイルドカード" として機能する。ピンはその不完全なタイプに一致するタイプを取り決める。
  • メディア タイプなし: フィルタ グラフ マネージャが NULL ポインタを渡す場合、ピンは両方のピンで受け入れ可能な任意のメディア タイプを使用できる。

ピンが実際に接続すると、接続は常に完全なメディア タイプを持つ。フィルタ グラフ マネージャがメディア タイプを指定する目的は、起こりうる接続タイプを限定することである。

調整プロセス中に、出力ピンは入力ピンの IPin::ReceiveConnection メソッドを呼び出すことで、メディア タイプを提示する。入力ピンは、提示されたタイプの受け入れまたは拒否を選択できる。入力ピンがタイプを受け入れるまでこのプロセスが繰り返される。出力ピンがあらゆるタイプを提示し尽くして、すべて拒否された場合、接続は失敗する。

提示するメディア タイプを出力ピンがどのように選択するかは、実装により異なる。DirectShow 基底クラスでは、出力ピンが入力ピンに対して IPin::EnumMediaTypes を呼び出す。このメソッドは、入力ピンの優先メディア タイプを列挙する列挙子を返す。これに失敗すると、出力ピンは出力ピン側の優先タイプを列挙する。

アロケータの調整

2 つのピンが接続すると、メディア データを交換するためのしくみが必要となる。このしくみは転送と呼ばれる。通常、DirectShow アーキテクチャは転送に関して中立的である。2 つのフィルタは、両者がサポートする任意の転送方法で接続することに合意できる。

最も一般的な転送は、ローカル メモリ転送である。この転送では、メディア データはメイン メモリに保持される。アロケータと呼ばれるオブジェクトが、メモリ バッファの割り当てを担当する。アロケータは、IMemAllocator インターフェイスをサポートする(詳細については、「フィルタ グラフのデータ フロー」を参照すること)。入力ピンは、IMemInputPin インターフェイスを公開することで、メイン メモリ転送をサポートする。出力ピンは、接続プロセス中にこのインターフェイスを問い合わせる。

両方のピンが同じアロケータを共有する。ピンが接続すると、どちらのピンがアロケータを提供するかを次の手順で調整する。

  1. 出力ピンが IMemInputPin::GetAllocatorRequirements を呼び出す (省略可能)。このメソッドは、メモリ配置など、入力ピンのバッファ要件を取得する。通常、出力ピンは、十分な理由がない限り入力ピンの要求を受け入れることになる。
  2. 出力ピンが IMemInputPin::GetAllocator を呼び出す (省略可能)。このメソッドは、入力ピンからアロケータを要求する。入力ピンはアロケータを提供するか、提供できない場合はエラー コードを返す。
  3. 出力ピンがアロケータを選択する。入力ピンから提供されたアロケータを使用するか、または出力ピン自体がアロケータを提供する。出力ピンが IMemInputPin::NotifyAllocator を呼び出して、入力ピンに選択結果を通知する。

このプロセスで必須なのはステップ 3 のみであることに注意すること。

フィルタがダウンストリーム入力ピンからのアロケータを選択する場合、フィルタはその入力ピンにサンプルを提供するためにのみ、アロケータを使用する必要がある。このアロケータは、ほかのピンにサンプルを提供するために使用することはできない。

ピンの再接続

ピン接続中に、フィルタはほかのピンの接続を解除したり、再接続したりしなければならないことがある。たとえば次のような場合である。

  • フィルタの入力ピンがあるメディア タイプと既に接続されている場合、出力ピンが接続しようとしても、入力タイプと互換性のあるメディア タイプが見つからないことがある。ダウンストリーム接続を実行するには、フィルタは入力ピンを別のタイプで再接続する必要がある。
  • コピーを減らすために、一部の変換フィルタはデータをその場で変更する(例については CTransInPlacerFilter 基底クラスを参照すること)。このようなフィルタは独自のアロケータを用意しない。出力ピンが接続すると、フィルタは入力ピンを再接続して、アップストリーム フィルタにダウンストリーム フィルタのアロケータを提供する。このように、3 つのフィルタすべてが 1 つのアロケータを共有することで、バッファの合計必要量が最小化される。

再接続するには、フィルタはフィルタ グラフ マネージャに対して IFilterGraph::Reconnect または IFilterGraph2::ReconnectEx を呼び出す。フィルタ グラフ マネージャは非同期にピンの接続解除と再接続を行う。メディア タイプを指定するので、ReconnectEx メソッドを使うことが望ましい。メディア タイプを指定しない場合、再接続を始めるフィルタが、目的のメディア タイプを内部に格納する必要がある。

フィルタは、再接続が成功することが確実でない限り、再接続を試行してはならない。再接続に失敗すると、ピンは接続が解除されたままになり、グラフ エラーの原因となる。フィルタが新しいメディア タイプで再接続する場合は、既知の有効なメディア タイプを指定しなければならない。不明な場合は、IPin::QueryAccept メソッドを呼び出す。

また、フィルタは、同じスレッド上の IPin::Connect メソッドの中から再接続を要求する必要がある。あるスレッドに IPin::Connect メソッドが返されているにもかかわらず、別のスレッドから再接続要求が行われると、フィルタ グラフ マネージャは、再接続を行う前にグラフを実行する可能性があり、グラフ エラーの原因となる。


フィルタ開発者が使用するデータ フロー

ここでは、データがフィルタ グラフ内をどのように移動するかについて説明する。独自のカスタム フィルタを作成する開発者を対象にしている。Microsoft® DirectShow® でのデータ フロー処理の概要については、「フィルタ グラフのデータ フロー」を参照すること。

ここでは、IMemInputPin および IMemAllocator インターフェイスを使用したローカル メモリ転送について説明する。内容は次のとおりである。

  • プッシュとプル
  • 新しいサンプルの生成
  • サンプルの処理
  • 新しいセグメント
  • ストリームの終わり
  • フラッシュ
  • スレッドとクリティカル セクション

プッシュとプル

ソース フィルタの役割は、データをグラフに読み込むことである。ソース フィルタは、プッシュ モデルまたはプル モデルのいずれかのモデルに従う。

  • プッシュ モデルでは、ソース フィルタは独自のスレッドでサンプルを作成し、ダウンストリーム フィルタに送信する。ダウンストリーム フィルタはサンプルを処理し、次のフィルタに送信する。各フィルタがこのステップを繰り返し、サンプルはレンダラに到達する。
  • プル モデルでは、ソース フィルタの直後のダウンストリーム フィルタが、ソース フィルタにデータを要求する。このダウンストリーム フィルタは、プッシュ モデルと同様に、次のフィルタにサンプルを送信する。

ビデオ カメラなどのライブ ソースではプッシュ モデルが一般的である。プル モデルはファイル リーダーで一般的であり、その場合のダウンストリーム フィルタは AVI スプリッタ フィルタなどのファイル パーサーである。

新しいサンプルの生成

ここでは、ソース フィルタがメディア サンプルを生成する方法について説明する。

プッシュ モデル

プッシュ モデルでは、ソース フィルタは次のように処理を開始する。

  1. ソース フィルタは IMemAllocator::GetBuffer を呼び出し、空のメディア サンプルを取得する。
  2. ソース フィルタは、取得した空のメディア サンプルにデータを挿入する。挿入の方法は、ソースの種類によって完全に異なる。
  3. ソース フィルタは、ダウンストリームの入力ピンに対して IMemInputPin::Receive を呼び出し、サンプルの IMediaSample インターフェイスへのポインタを渡す。
  4. ダウンストリーム フィルタは、Receive から戻る前にサンプルを処理するか、あるいはサンプルを保留して後で処理することができる。フィルタを保留する場合、ダウンストリーム フィルタはサンプルに対して IUnknown::AddRef を呼び出す。
  5. ソース フィルタは、サンプルに対して IUnknown::Release を呼び出す。

この時点で、ダウンストリーム フィルタはサンプルの参照カウントを保留し、ソース フィルタが簡単にサンプルを再利用できないようにする。次のサンプルを送信するには、ソース フィルタは、手順 1 に示したように IMemAlloctor::GetBuffer をもう一度呼び出す必要がある。

注 : 複数のサンプルを送信するには、ソース フィルタは手順 3 で代わりに IMemInputPin::ReceiveMultiple を呼び出すことができる。

プル モデル

プル モデルでは、パーサー フィルタがソース フィルタにデータを要求する。パーサー フィルタはソース フィルタの出力ピンに対して、次のように IAsyncReader インターフェイスを使用する。

  1. パーサー フィルタは IMemAllocator::GetBuffer を呼び出し、空のメディア サンプルを取得する。
  2. パーサー フィルタは IAsyncReader::Request を呼び出し、ソース フィルタにデータを要求する。
  3. ソース フィルタがデータを取得する間、パーサーは IAsyncReader::WaitForNext を呼び出す。このメソッドは、手順 2 の要求が完了するまで待機する。
  4. パーサー フィルタはデータを処理し、ダウンストリームに送信する。

手順 2 ～ 3 で実行されるのは非同期読み取り操作であるが、パーサーは、IAsyncReader::SyncRead または IAsyncReader::SyncReadAligned メソッドを使用して、代わりに同期読み取り操作を要求することもできる。

サンプルの処理

フィルタの入力ピンがサンプルを受け取ると、フィルタはサンプルに含まれるデータを処理し、次のダウンストリーム フィルタにサンプルを送信する。前の「新しいサンプルの生成」で説明したように、フィルタは Receive メソッドの中ですべての処理を実行するか、サンプルを保留して後で処理することができる。

Receive の呼び出しの中で、入力ピンはアップストリーム フィルタの呼び出し側スレッドをブロックすることが可能である。入力ピンの動作は、IMemInputPin::ReceiveCanBlock メソッドを呼び出すことによって確認できる。戻り値が S_OK である場合、入力ピンは Receive の呼び出しをブロックする。戻り値が S_FALSE である場合、入力ピンが Receive の呼び出しをブロックすることはない。戻り値に基づいて、アップストリーム フィルタは別個のワーカー スレッドを使用してサンプルを送信できる。

データをコピーせずサンプルを元の場所で処理するフィルタもある。データをコピーしてから処理するフィルタもある。当然のこととして、不要なコピー操作によるオーバーヘッドを避けるために、可能な限りデータを元の場所で処理する方が望ましい。

入力ピンは、Receive メソッドでエラー コードまたは S_FALSE を返すことによって、サンプルを拒否できる。S_FALSE という値は、ピンがデータをフラッシュすることを示す (「フラッシュ」を参照すること)。エラー コードは、それとは別の問題を示す。たとえば、フィルタが停止した場合、戻り値は VFW_E_WRONG_STATE になる。ピンがサンプルを拒否した場合、フィルタは接続されている入力ピンに対して IPin::EndOfStream メソッドを呼び出す。さらに、エラーが発生した場合、フィルタはフィルタ グラフ マネージャに EC_ERRORABORT イベントを送信する。ピンがサンプルを拒否した後、アップストリーム フィルタはデータの送信を停止する。データ送信は、フラッシュが完了した後、またはグラフが停止後に再起動した時点で再開できる。

フィルタは特定の入力ピンに対するすべての Receive 呼び出しを継続して処理する必要がある。

新しいセグメント

新しい各ストリームの始めに、ソース フィルタ (またはパーサー フィルタ) は IPin::NewSegment を呼び出す必要がある。このメソッドは、ストリームの開始タイムと終了タイムを元のソースに対して相対的に指定し、再生レートを指定する。フィルタは、ストリーミング開始時、およびシーク操作後に NewSegment を呼び出す。新しいセグメントごとにストリーム時間はゼロにリセットされ、新しいセグメントの後に送信されたサンプルにはゼロから始まるタイム スタンプが付く。

フィルタがサンプルを正しく処理するためにセグメント情報が必要な場合もある。たとえば、MPEG-1 などのフォーマットでは、中間フレームを構成するためにフィルタは終了タイム以後のキー フレームを必要とする。セグメント情報はフィルタに実際の終了タイムを知らせる。フィルタがセグメント情報を使用するかどうかにかかわらず、フィルタは NewSegment 呼び出しをダウンストリームに渡す。NewSegment 呼び出しは、Receive などのほかのストリーミング呼び出しとともに継続して処理する必要がある。

ストリームの終わり

ソース フィルタは、送信するデータがなくなると、ダウンストリームの入力ピンに対して IPin::EndOfStream メソッドを呼び出す。ダウンストリーム フィルタはこの呼び出しを次のフィルタに伝達する。最後には EndOfStream 呼び出しがレンダリング フィルタに到達する。レンダリング フィルタはフィルタ グラフ マネージャに EC_COMPLETE イベントを送信する。

フィルタ グラフ マネージャは、アプリケーションに EC_COMPLETE 通知を直ちに転送するのではなく、すべてのストリームから EC_COMPLETE が送信されるまで待機する。すべてのストリームが完了すると、アプリケーションは EC_COMPLETE 通知を受け取る。グラフ内のストリームの数を確認するために、フィルタ グラフ マネージャは IMediaSeeking または IMediaPosition をサポートし、レンダリングされた入力ピンを持つフィルタの数をカウントする。レンダリングされた入力ピンは、対応する出力がない入力ピンである。IPin::QueryInternalConnections メソッドは、レンダリングされた入力ピンについては 0 を返す。ほかのオプションとして、フィルタは IAMFilterMiscFlags インターフェイスを実装し、AM_FILTER_MISC_FLAGS_IS_RENDERER フラグを返すことができる。

フィルタは、Receive などのほかのストリーミング呼び出しとともに EndOfStream 呼び出しを継続して処理する必要がある。

フラッシュ

フラッシュは、グラフ内のペンディング状態のサンプルすべてを破棄する処理である。フラッシュは、イベントによって正常なデータ フローが変更されたときのグラフの応答を改善する。たとえば、シーク操作では、新しいデータが読み込まれる前に古いデータをグラフからフラッシュする。グラフに複数のストリームが含まれている場合は、各ストリームを別々にフラッシュすることが可能である。

フラッシュ処理には 2 つの段階がある。

  • ソース フィルタが、接続されている入力ピンに対する IPin::BeginFlush を呼び出す。それに応じて、ダウンストリーム フィルタはアップストリームからのサンプル受け取りを停止する。BeginFlush の呼び出しがダウンストリームに伝達されていき、レンダラまで到達する。
  • ソース フィルタは入力ピンに対する IPin::EndFlush を呼び出す。ペンディング状態のデータがストリームからフラッシュされ、呼び出しがダウンストリームに伝達される。

入力ピンの BeginFlush メソッドを呼び出すとき、フィルタは次の動作を実行する。

  1. ダウンストリームの入力ピンに対する BeginFlush を呼び出す。
  2. Receive や EndOfStream など、データのストリーミングを実行する次の呼び出しを拒否する。
  3. フィルタのアロケータからのサンプルを待ってブロックされているアップストリーム フィルタを非ブロックにする。この目的のため、フィルタはそのアロケータをデコミットする事が多い。
  4. ストリーミングをブロックする待機状態を終了する。たとえば、レンダリング フィルタはポーズするとブロックする。さらに、正しいストリーム タイムにサンプルをレンダリングするために待機しているときも、ブロックする。フィルタは、ブロックを解除して、アップストリームのキューにあるサンプルを送信および拒否できるようにしなければならない。この手順によって、ストリーミング チェーン内のすべてのフィルタが最終的にブロック解除されることが保証される。

EndFlush メソッドを呼び出すとき、フィルタは次の動作を実行する。

  1. キューにあるすべてのサンプルが破棄されるまで待機する。
  2. バッファ内のデータを解放する。この手順は場合によって BeginFlush メソッドで実行することも可能である。ただし、BeginFlush はストリーミング スレッドと同期化されない。フィルタは、BeginFlush を呼び出してから EndFlush を呼び出すまでの間、データを処理したりバッファに入れることはできない。
  3. ペンディング状態の EC_COMPLETE 通知をクリアする。
  4. ダウンストリームの EndFlush を呼び出す。

この時点で、フィルタはサンプルの受け取りを再開できる。すべてのサンプルはフラッシュより新しいことが保証されている。

プル モデルでは、ソース フィルタではなくパーサー フィルタがフラッシュを開始する。イベントのシーケンスは同じだが、ソース フィルタの出力ピンに対する BeginFlush および EndFlush もパーサーが呼び出す。

スレッドとクリティカル セクション

DirectShow アプリケーションでは、最低 2 つの重要なスレッドが動作している。1 つ目はアプリケーション スレッドである。このスレッドは、フィルタ グラフの状態の変更を開始する。状態変更には、グラフの実行、ポーズ、および停止、ピンの接続と接続終了、グラフへのフィルタの追加、およびグラフからのフィルタの削除がある。2 つ目の重要なスレッドはストリーミング スレッドである。ピンはストリーミング スレッド内でサンプルを受け取って送信する。アプリケーション スレッドがデータ フローを中断することなくブロックできるように (たとえば、アプリケーションがユーザーと通信する間)、別個のストリーミング スレッドが必要である。

フィルタはスレッドを作成することもできる。たとえば、IMemInputPin::Receive メソッドでは、フィルタは直ちに戻って受信したサンプルを別のスレッドで処理できる。別個のスレッドを使用して、送信待ちのサンプルをキューに入れるフィルタもある。

フィルタ操作はマルチスレッドであるため、特定の操作では、フィルタが操作を継続して処理することが非常に重要である。そうしないと、競合状態が発生する可能性がある。たとえば、次に示すコードを考える。このコードは基準クロックの有無を確認し、現在の時刻を取得する。

if (m_pClock != NULL)  // 基準クロックがあるか?
{
    m_pClock->GetTime(&rtTimeNow);
    // 以下コード省略...
}

ストリーミング スレッドがこのコードを実行し、コードはプロテクトされていないとする。 if ステートメントと次の行の間に、アプリケーション スレッドが IMediaFilter::SetSyncSource を呼び出し、基準クロックを NULL に設定することがある。その結果、ストリーミング スレッドは NULL ポインタの参照を解除する。例外が発生し、アプリケーションはクラッシュする。

競合状態を回避するために、フィルタは 2 つのクリティカル セクションを使用する。1 つ目はストリーミング ロックである。ストリーミング ロックはストリーミング操作を継続して処理する。2 つ目はフィルタ ロックである。フィルタ ロックは状態変更を継続して処理し、ステート情報の整合性を保護する。

フィルタは次に示すメソッド呼び出しを処理するときにストリーミング ロックを保持する。

  • IMemInputPin::Receive
  • IMemInputPin::ReceiveMultiple
  • IPin::EndOfStream
  • IPin::NewSegment

フィルタは次に示すタイプの呼び出しを処理するときにフィルタ ロックを保持する。

  • 状態変更 : IBaseFilter::JoinFilterGraph、IMediaFilter::Pause、IMediaFilter::Run、IMediaFilter::Stop、IQualityControl::SetSink
  • 基準クロック : IMediaFilter::GetSyncSource、IMediaFilter::SetSyncSource
  • ピン操作 : IBaseFilter::FindPin、IPin::Connect、IPin::ConnectedTo、IPin::ConnectionMediaType、IPin::Disconnect、IPin::ReceiveConnection
  • アロケータ関数 : IMemInputPin::GetAllocator、IMemInputPin::NotifyAllocator
  • フラッシュ : IPin::BeginFlush、IPin::EndFlush

この一覧に示した呼び出しがすべてではない。フィルタを実装する場合は、フィルタ状態を変更するメソッドはどれか、およびストリーミング操作を実行するメソッドはどれかを考慮する必要がある。

クリティカル セクションは潜在的にデッドロックを発生させる可能性がある。デッドロックを回避するには、ストリーミング メソッドがフィルタ ロックを保持してはならない。理由は、フィルタ グラフの状態移行が終わらないと完了しないストリーミング操作が存在するからである。たとえばレンダラは、ポーズ中は Receive 呼び出しをブロックする。アップストリーム フィルタが Receive を呼び出すときにフィルタ ロックを保持すると、循環する待機状態が発生する場合がある。ストリーミング スレッドはグラフのポーズ状態が終了するのを待機する。しかし、アプリケーション スレッドはフィルタ ロックを取得するまで待機するため、その状態移行が行われることはあり得ない。

次の図は、このデッドロックを示している。

Stop および EndFlush メソッドでは、ストリーミング操作をフィルタ状態と同期化する必要がある。そうしないと、フィルタは状態移行後も古いサンプルを送信し続けることがある。Stop メソッドでは、デッドロックを回避するように注意する必要がある。最初にフィルタ ロックを保持し、入力ピンのアロケータをデコミットする。次にストリーミング ロックを保持する。アロケータをデコミットすると、Receive の呼び出しが失敗し、したがってブロックを確実に回避できる (実装については、「CTransformFilter::Stop」を参照すること)。フラッシュ処理では、BeginFlush メソッドがサンプルの取り出しを開始し、EndFlush メソッドがストリーミング ロックを保持する。


DirectShow のタイムとクロック

ここでは、DirectShow® アーキテクチャにおけるタイムとクロックについて概説する。このトピックは、以下のセクションを含んでいる。

  • 基準クロック
  • クロック タイム
  • タイム スタンプとメディア タイム
  • ライブ ソース

基準クロック

フィルタ グラフ マネージャの 1 つの機能として、グラフ内のフィルタを同期化させることがある。このために、フィルタ グラフ マネージャとフィルタは、基準クロックと呼ばれる同一のクロックを使用する。IReferenceClock インターフェイスをサポートするすべてのオブジェクトは基準クロックとしてのサービスを提供することができる。ハードウェア タイマにアクセスするフィルタは、クロックを提供することができ (たとえばオーディオ レンダラ)、フィルタ グラフ マネージャはシステム タイムを使用するクロックを作成することができる。

実行時、フィルタ グラフ マネージャは基準クロックを選択し、すべてのフィルタの IMediaFilter::SetSyncSource を呼び出してその選択内容を通知する。アプリケーションは、フィルタ グラフ マネージャの SetSyncSource を呼び出すことによって、フィルタ グラフ マネージャが選択したクロックをオーバーライドすることができる。この操作は、別のクロックを使用する明確な理由がある場合にのみ行うこと。

フィルタ グラフ マネージャは、以下の条件に基づいて基準クロックを選択する。

  • グラフ内のフィルタが基準クロックを提供できる場合はそのフィルタを使用する。例外: グラフがライブ ソースを含んでいる場合は、ソース フィルタ クロックだけを選択する。
  • 適切なクロックを提供するフィルタがない場合は、システム タイムを使用する。

基準クロックは、100 ナノ秒間隔でタイムを計測する。クロックの現在のタイムを取得するには、IReferenceClock::GetTime メソッドを呼び出す。クロックの基線、すなわちカウントを開始するタイムは、クロックの実装に依存するので、返される特定のタイム値は本質的に意味のあるものではない。重要なのは、100 ナノ秒に 1 回の割合で単調増加する値を返すということである。

クロック タイム

DirectShow では、基準タイムとストリーム タイムの 2 つの関連クロック タイムを定義している。

  • 基準タイムは、基準クロックから返される絶対タイムである。
  • ストリーム タイムは、グラフが最後に実行を開始したときを基準に定義される。
    • グラフが実行しているときは、ストリーム タイムは、基準タイムから開始タイムを差し引いた値に等しい。
    • グラフがポーズしているときは、ストリーム タイムはポーズされたときのストリーム タイムに留まる。
    • グラフが停止しているときは、ストリーム タイムはゼロである。
    • シーク処理後には、ストリーム タイムはゼロにリセットされる。

フィルタ グラフを実行するためにアプリケーションが IMediaControl::Run を呼び出すと、フィルタ グラフ マネージャはそれぞれのフィルタで IMediaFilter::Run を呼び出す。各フィルタが実行を開始するまでに要するわずかなタイムを補正するために、フィルタ グラフ マネージャは、わずかに進めた開始タイムを指定する。

タイム スタンプとメディア タイム

メディア サンプルは、タイム スタンプとメディア タイムの 2 つのタイム ベースのプロパティを持つ。

タイム スタンプ

タイム スタンプは、ストリーム タイムで示されるサンプルの開始タイムと終了タイムを定義する。タイム スタンプは、プレゼンテーション時間と呼ばれることもある。

フィルタを受け取ると、レンダリング フィルタはタイム スタンプに基づいてレンダリングをスケジュールする。サンプルの到着が遅れたり、タイム スタンプがない場合、フィルタは即座にそのサンプルのレンダリングを開始する。それ以外の場合、フィルタはサンプルの開始タイムまで待ってからそのサンプルのレンダリングを開始する。(フィルタは、IReferenceClock::AdviseTime メソッドを呼び出して開始タイムを待つ。)

ソース フィルタとパーサー フィルタは、処理対象のサンプルに適切なタイム スタンプを設定する責任を負う。以下のガイドラインを使用する。

  • ファイルの再生 : 最初のサンプルには、ゼロの開始タイムのタイム スタンプが設定される。以降のタイム スタンプは、サンプルの長さと再生レートによって決定される。
  • ビデオおよびオーディオのキャプチャ : すべてのサンプルには、キャプチャが行われたストリーム タイムに等しい開始タイムのタイム スタンプが設定される。ビデオ プレビュー フレームは例外である。グラフ遅延時間があるために、現在のストリーム タイムのタイム スタンプが設定されたプレビュー フレームは必ず遅れてビデオ レンダラに到着する。この場合、レンダラは品質コントロールの目的でフレームをドロップする可能性がある。したがって、プレビュー フレームにはタイム スタンプを設定してはならない。品質コントロールについては、「品質コントロールの管理」を参照すること。

サンプルにタイム スタンプを設定するには、IMediaSample::SetTime メソッドを呼び出す。

メディア タイム

メディア タイムは、シーク可能なメディア内のサンプルの本来の位置 (たとえばディスク上のファイル) を指定する。ビデオの場合、メディア タイムはフレーム番号を表す。オーディオの場合、メディア タイムはパケット内のサンプル番号を表す。たとえば、各パケットに 1 秒の 44.1 kHz オーディオが含まれている場合、最初のパケットのメディア開始タイムはゼロ、メディア終了タイムは 44100 となる。レンダリング フィルタは、メディア タイムのギャップをチェックすることで、フレームまたはサンプルがドロップされたかどうかを調べることができる。

タイム スタンプは、たとえばシーク レートや再生レートなどのソース外の要因に依存するが、メディア タイムは常にオリジナルのソースを基準として計算される。

サンプルのメディア タイムを設定するには、IMediaSample::SetMediaTime メソッドを呼び出す。

ライブ ソース

プッシュ ソースとも呼ばれるライブ ソースは、メディア データをリアルタイムで受け取る。たとえば、ビデオ キャプチャやネットワーク ブロードキャストなどが例として挙げられる。一般に、ライブ ソースはデータが到着するレートを制御することはできない。ライブ ソース フィルタは、出力ピンで IAMPushSource インターフェイスを実装しなければならない。フィルタ グラフ マネージャはこのインターフェイスを使用して、ライブ ソースがレンダリングされるときに発生する可能性のある 2 つの問題に対処する。

  • 遅延時間
  • レート マッチング

遅延時間

フィルタの遅延時間とは、フィルタがサンプルを処理するのに要する時間である。ライブ ソースの場合、遅延時間はサンプルを保持するためのバッファのサイズによって決まる。たとえばフィルタ グラフがビデオ ソースをレンダリングする際に 33 ミリ秒 (ms) の遅延時間があり、オーディオ ソースをレンダリングする際に 500 ms の遅延時間があるとする。この場合、各ビデオ フレームは、対応するオーディオ サンプルがオーディオ レンダラに到着する約 470 ms 前にビデオ レンダラに到着する。この差異をグラフで補正しないと、オーディオとビデオは同期しない。

アプリケーションが IAMGraphStreams::SyncUsingStreamOffset メソッドを呼び出して同期化を有効にしない限り、フィルタ グラフ マネージャはライブ ソースを同期化しない。同期化が有効にされた場合、フィルタ グラフ マネージャはそれぞれのソース フィルタに対して IAMPushSource インターフェイスを照会する。IAMPushSource をサポートするすべてのフィルタに対して、グラフは IAMLatency::GetLatency を呼び出してフィルタの予想遅延時間を取得し、これらの値から予想最大遅延時間を求める。グラフは次に IAMPushSource::SetStreamOffset を呼び出して各ソース フィルタにストリーム オフセットを与える。フィルタは、このストリーム オフセットを生成するタイム スタンプに加える。

レート マッチング

レンダリング フィルタが 1 つの基準クロックを使ってサンプルをスケジュールする一方で、ソース フィルタが異なるクロックを使用してサンプルを生成した場合、再生時にグリッチが発生することがある。レンダラがソースよりも高速に実行すると、データにギャップが生じる。レンダラがソースよりも低速に実行すると、サンプルの処理が"追いつかなくなり"、どこかでデータをドロップしなければならなくなる。通常、ライブ ソースはそのプロダクション レートを制御することができないので、レンダラ側でソースとクロック レートを一致させる。

レート マッチングを行うためには、レンダリング フィルタは別のクロックに従ってそのクロックを設定しなければならない。どのクロックを使用するかは、ソース フィルタがどのようにタイム スタンプを生成するかに依存する。

  • ソース フィルタが基準クロックからタイム スタンプを生成し、レンダラが同じクロックにアクセスできる場合、レンダラはクロックを基準クロックに設定する。この場合、ソース フィルタはレンダラの専用クロックを基準クロックとして使用していてはならない。そうでないと、レンダラは自分自身とレートを合わせることになり、クロックのずれが発生する。
  • ソース フィルタがプライベート クロック、すなわちレンダラがアクセスできないクロックからタイム スタンプを生成する場合、レンダラは入力するサンプルのタイム スタンプに基づいてクロック レートを調整する。
  • ソース フィルタがタイム スタンプをまったく生成しない場合、レンダラは、配送されたバイト数とフォーマット ブロックで宣言された 1 秒あたりのバイト数に基づいてソース フィルタの配送レートを計算する。

レンダラは、ソース フィルタの IAMPushSource::GetPushSourceFlags を呼び出して、ソース フィルタがどのようにタイム スタンプを設定するかを求める。オーディオ再生におけるグリッチはビデオにおけるそれよりも著しいので、現在、オーディオ レンダラだけがレート マッチングを実行する。


品質コントロールの管理

品質コントロールは、フィルタ グラフ内のデータ フローのレートを実行時のパフォーマンスに応じて調整するためのメカニズムである。レンダリング フィルタは、受け取るデータの量が多すぎる場合または少なすぎる場合、品質メッセージを送信できる。品質メッセージはデータ レートの調整を要求する。デフォルトでは、品質メッセージは、レンダラから応答可能なフィルタ (存在する場合) までアップストリーム方向に移動する。アプリケーションでは、カスタム品質マネージャを実装することもできる。その場合、レンダラは品質メッセージをアプリケーションの品質マネージャに直接渡す。

ここで説明する内容は次のとおりである。

  • 品質メッセージ
  • デフォルトの品質メッセージ

品質メッセージ

品質メッセージは Quality 構造体を使用して定義する。この構造体には次のメンバが含まれる。

  • Type: Famine (フィルタが受け取るデータが少なすぎることを示す)、または Flood (フィルタが受け取るデータが多すぎることを示す) 。
  • Proportion: 要求されたデータ レートの調整 (ベースラインは 1000)。たとえば、750 は 75%、1500 は 150% を表す。
  • Late: 最新のサンプルの到着がどれだけ遅れたかを示す基準タイム。サンプルが早く到着した場合は、この値が負になる。
  • TimeStamp: 最新サンプルのタイム スタンプ。

たとえば、240 ミリ秒 (ms) のタイム スタンプを持つサンプルが、280 ms のストリーム タイムにレンダラに到着したとする。レンダラはタイプが Famine の品質メッセージを作成する。サンプルは 40 ms 遅れて到着したので、Late メンバは 400000 となる (すべての基準タイムは 100 ナノ秒単位)。TimeStamp メンバは 2400000 である。

Proportion メンバについては、レンダラは移動平均を使って値を計算する。サンプルは時間どおりに到着しており、このサンプルは変則である。その場合、レンダラはわずかな修正しか要求しない。一方、サンプルが一貫して遅れている場合は、レンダラは大幅な修正を要求することになる。

品質コントロールは IQualityControl インターフェイスを通じて処理される。このインターフェイスには 2 つのメソッドがある。

  • Notify: 品質メッセージを送信する。
  • SetSink: カスタム品質マネージャを指定する。

IQualityControl を実装するオブジェクトは、Notify メソッドを通じて品質メッセージを受け取り、メッセージを処理するか、別のオブジェクトにメッセージを渡す。アプリケーションでオブジェクトの SetSink メソッドを呼び出す場合、オブジェクトは指定された品質マネージャに品質コントロールを委任する必要がある。

デフォルトの品質メッセージ

フィルタ基底クラスは、ビデオ品質コントロールに関するいくつかのデフォルト動作を実装する。

品質メッセージはレンダラで開始される。ビデオ レンダラの基底クラスは CBaseVideoRenderer であり、次のように動作する。

  1. ビデオ レンダラは、サンプルを受け取ると、サンプルのタイム スタンプを現在の基準タイムと比較する。
  2. ビデオ レンダラは品質メッセージを生成する。基底クラスでは、品質メッセージのメンバ Proportion は 500 (50%) から 2000 (200%) までの範囲に制限されている。値がこの範囲外である場合は、品質が急激に変化することがある。
  3. デフォルトでは、ビデオ レンダラは品質メッセージをアップストリームの出力ピン (レンダラの入力ピンに接続されているピン) に送信する。アプリケーションでは、SetSink メソッドを呼び出すことによって、この動作をオーバーライドできる。

次に行われる処理は、アップストリーム フィルタによって異なる。通常は変換フィルタになる。変換フィルタの基底クラスは CTransformFilter で、CTransformInputPin および CTransformOutputPin クラスを使用して入力ピンと出力ピンを実装する。これらのクラスは、一緒に次のように動作する。

  1. CTransformOutputPin::Notify メソッドは、フィルタ基底クラスに対するプライベート メソッドである CTransformFilter::AlterQuality を呼び出す。
  2. 派生フィルタは AlterQuality をオーバーライドして品質メッセージを処理できる。デフォルトでは、AlterQuality は品質メッセージを無視する。
  3. AlterQuality が品質メッセージを処理しない場合、出力ピンはフィルタの入力ピンに対するプライベート メソッドである CBaseInputPin::PassNotify を呼び出す。
  4. PassNotify は、適切な場所つまり次のアップストリーム出力ピンかカスタム品質マネージャに品質メッセージを渡す。

変換フィルタが品質メッセージを処理すると想定した場合、メッセージは最終的にソース フィルタの出力ピンに到着する。基底クラスでは、CBasePin::Notify が E_NOTIMPL を返す。特定のソース フィルタが品質メッセージを処理する方法は、ソースの種類によって異なる。ライブ ビデオ キャプチャなど、有効な品質コントロールを実行できないソースもある。サンプルを送信するレートを調整できるソースもある。

次の図は、デフォルトの動作を示している。

ベース ビデオ レンダラは IQualityControl::Notify を実装する。これは、レンダラ自身に品質メッセージを渡せることを意味する。Proportion メンバを 1000 未満の値に設定すると、ビデオ レンダラはレンダリングする各フレームの間に待機期間を挿入し、その結果レンダラの速度が遅くなる (これは、たとえばシステム リソースの使用率を減らすために実行する)。詳細については、CBaseVideoRenderer::ThrottleWait を参照すること。Proportion メンバに 1000 より大きい値を設定しても無効になる。


DirectShow と COM

このセクションは、以下のトピックを含んでいる。

  • IUnknown の実装方法
  • DLL の作成方法
  • DirectShow フィルタの登録方法


IUnknown の実装方法

Microsoft® DirectShow® は、Component Object Model (COM) に基づいている。自分でフィルタを書く場合は、フィルタを COM オブジェクトとして実装しなければならない。DirectShow の基底クラスは、このような作業を行うためのフレームワークを提供する。基底クラスを使う必然性はないが、基底クラスを使えば開発プロセスを簡略化することができる。ここでは、COM オブジェクトの内部的な動作と、DirectShow 基底クラスでの COM オブジェクトの実装について説明する。

このトピックは、COM クライアント アプリケーションのプログラミングを理解している、すなわち、IUnknown のメソッドを理解しているユーザーを対象にしているが、COM オブジェクトの開発経験があるユーザーを前提とするものではない。DirectShow は、COM オブジェクトの開発に関する多くを扱う。COM オブジェクトの開発経験があるユーザーは、CUnknown 基底クラスを解説している「CUnknown の使用」セクションを読むべきである。

COM は実装ではなく仕様である。COM は、コンポーネントが従うべき規則を定義する。規則を実際に適用するのは開発者の役目である。DirectShow では、すべてのオブジェクトは C++ の基底クラスから派生する。基底クラス コンストラクタおよびメソッドは、一貫した参照カウントの保持などの COM "ブックキーピング"処理のほとんどを行う。フィルタを基底クラスから派生させることによって、そのクラスの機能を継承することができる。基底クラスを効果的に使用するためには、COM 仕様がどのようにクラスに実装されているかを理解する必要がある。

このトピックは、以下のセクションを含んでいる。

  • IUnknown の動作
  • CUnknown の使用
  • 要約

IUnknown の動作

IUnknown のメソッドを使用すると、アプリケーションはコンポーネントのインターフェイスを照会したり、コンポーネントの参照カウントを管理することができる。このセクションは、以下のトピックを含んでいる。

  • 参照カウント
  • インターフェイスの照会
  • 集成化と委任

参照カウント

参照カウントは、AddRef メソッドでインクリメントされ Release メソッドでデクリメントされる内部変数である。基底クラスは、参照カウントを管理し、複数のスレッド間で参照カウントへのアクセスを同期化する。

インターフェイスの照会

インターフェイスの照会はわかりやすい。呼び出し元は、インターフェイス識別子 (IID) とポインタのアドレスの 2 つのパラメータを渡す。要求されたインターフェイスをコンポーネントがサポートしている場合、コンポーネントはそのインターフェイスへのポインタを設定し、専用の参照カウントをインクリメントし、S_OK を返す。コンポーネントがそのインターフェイスをサポートしていない場合、コンポーネントは NULL へのポインタを設定し、E_NOINTERFACE を返す。以下の擬似コードは、QueryInterface メソッドの概要を示す。次の節で説明するコンポーネントの集成化では、処理が複雑になっている。

if (IID == IID_IUnknown)
    set pointer to (IUnknown *)this
AddRef
return S_OK

else if (IID == IID_ISomeInterface)
    set pointer to (ISomeInterface *)this
AddRef
return S_OK

else if ...

else
    set pointer to NULL
    return E_NOINTERFACE

1 つのコンポーネントの QueryInterface メソッドと別のコンポーネントの QueryInterface メソッドの唯一の違いは、それぞれのコンポーネントがテストする IID のリストにある。コンポーネントがサポートするすべてのインターフェイスに対して、コンポーネントはそのインターフェイスの IID のテストを行わなければならない。

集成化と委任

コンポーネントの集成は呼び出し元に対して透過的でなければならない。したがって、集成は、外部コンポーネントの実装に従う集成されたコンポーネントを使用して、1 つの IUnknown インターフェイスを公開しなければならない。そうでないと、呼び出し元は同じ集成内で 2 つの異なる IUnknown インターフェイスを認識することになる。コンポーネントが集成されていない場合、コンポーネントは独自の実装を使用する。

この動作をサポートするためには、コンポーネントは間接的なレベルを追加しなければならない。委任 IUnknown は、作業を適切な場所に委任する。すなわち、インターフェイスが 1 つであれば外部コンポーネントか、またはコンポーネントの内部バージョンに委任する。非委任 IUnknown は、前の節で説明した操作を行う。

委任バージョンはパブリックで、IUnknown の名前をそのまま保持する。非委任バージョンは INonDelegatingUnknown に名前が変更される。これはパブリック インターフェイスではないので、この名前は COM 仕様の一部ではない。

クライアントがコンポーネントのインスタンスを作成するとき、クライアントは IClassFactory::CreateInstance メソッドを呼び出す。パラメータは、集成コンポーネントの IUnknown インターフェイスへのポインタか、または新しいインスタンスが集成されていない場合は NULL である。以下の例に示すように、コンポーネントは使用する IUnknown インターフェイスを示すメンバ変数を格納するためにこのパラメータを使用する。

CMyComponent::CMyComponent(IUnknown *pOuterUnkown)
{
    if (pOuterUnknown == NULL)
        m_pUnknown = (IUnknown *)(INonDelegatingUnknown *)this;
    else
        m_pUnknown = pOuterUnknown;

    [ ... コンストラクタ コード ... ]
}

委任 IUnknown の各メソッドは、次の例に示すように対応する非委任メソッドを呼び出す。

HRESULT QueryInterface(REFIID iid, void **ppv)
{
    return m_pUnknown->QueryInterface(iid, ppv);
}

委任動作の本質上、委任メソッドはすべてのコンポーネントにおいて同じに見える。非委任バージョンだけが変わる。

CUnknown の使用

DirectShow は CUnknown と呼ばれる基底クラスの IUnknown を実装する。この CUnknown を使用してほかのクラスを派生し、コンポーネント間で変わるメソッドだけをオーバーライドすることができる。DirectShow のほかの基底クラスのほとんどは CUnknown から派生するので、作成するコンポーネントを CUnknown またはほかの基底クラスから直接継承することができる。

このセクションは、以下のトピックを含んでいる。

  • INonDelegatingUnknown
  • IUnknown
  • クラス コンストラクタ

INonDelegatingUnknown

CUnknown は INonDelegatingUnknown を実装する。CUnknown は参照カウントを内部的に管理し、ほとんどの状況で派生クラスは同じ 2 つの参照カウント メソッドを実装する。CUnknown は参照カウントがゼロになるとそれ自体を削除する。その一方では、NonDelegatingQueryInterface をオーバーライドしなければならない。なぜなら、基底クラスのメソッドは IID_IUnknown 以外の IID を受け取ると E_NOINTERFACE を返すからである。派生クラスでは、以下の例に示すようにサポートするインターフェイスの IID をテストする必要がある。

STDMETHODIMP NonDelegatingQueryInterface(REFIID riid, void **ppv)
{
    if (riid == IID_ISomeInterface)
    {
    return GetInterface((ISomeInterface*)this, ppv);
    }
    // デフォルト
    return CUnknown::NonDelegatingQueryInterface(riid, ppv);
}

ユーティリティ関数 GetInterface はポインタを設定し、スレッドに対応した方法で参照カウントを実装し、S_OK を返す。デフォルトのケースでは、基底クラス メソッドを呼び出してその結果を返す。別の基底クラスから派生させた場合は、その NonDelegatingQueryInterface メソッドを代わりに呼び出す。これにより、親クラスがサポートするすべてのインターフェイスをサポートすることができる。

IUnknown

上述のように、IUnknown の委任バージョンは、非委任バージョンの正しいインスタンスを起動するだけなのですべてのコンポーネントで同じである。便宜上、ヘッダー ファイル Combase.h は、インライン メソッドとして 3 つの委任メソッドを宣言するマクロ DECLARE_IUNKNOWN を含んでいる。このコードを以下に示す。

STDMETHODIMP QueryInterface(REFIID riid, void **ppv) {
    return GetOwner()->QueryInterface(riid,ppv);
};
STDMETHODIMP_(ULONG) AddRef() {
    return GetOwner()->AddRef();
};
STDMETHODIMP_(ULONG) Release() {
    return GetOwner()->Release();
};

ユーティリティ関数 GetOwner は、このコンポーネントを所有するコンポーネントの IUnknown インターフェイスへのポインタを取得する。集成したコンポーネントの場合、その所有者は外部コンポーネントである。それ以外の場合、コンポーネントはそれ自体を所有する。クラス定義の public セクションに DECLARE_IUNKNOWN マクロをインクルードする。

クラス コンストラクタ

クラスに固有の操作に加えて、クラス コンストラクタは、親クラスのコンストラクタ メソッドを起動しなければならない。以下の例に、一般的なコンストラクタ メソッドを示す。

CMyComponent(TCHAR *tszName, LPUNKNOWN pUnk, HRESULT *phr)
: CUnknown(tszName, pUnk, phr)
{
/* その他の初期化 */
};

このメソッドは以下のパラメータを取って CUnknown コンストラクタ メソッドに直接渡す。

  • tszName は、コンポーネントの名前を指定する。
  • pUnk は、集成化 IUnknown へのポインタである。
  • pHr は、メソッドの成功または失敗を表す HRESULT 値へのポインタである。

要約

以下に、IUnknown と ISomeInterface という名前の仮想のインターフェイスをサポートする派生クラスの例を示す。

class CMyComponent : public CUnknown, public ISomeInterface
{
public:

DECLARE_IUNKNOWN;

STDMETHODIMP NonDelegatingQueryInterface(REFIID riid, void **ppv)
    {
        if( riid == IID_ISomeInterface )
        {
        return GetInterface((ISomeInterface*)this, ppv);
        }
        return CUnknown::NonDelegatingQueryInterface(riid, ppv);
    }

CMyComponent(TCHAR *tszName, LPUNKNOWN pUnk, HRESULT *phr)
: CUnknown(tszName, pUnk, phr)
    {
/* その他の初期化 */
    };

    // 後で宣言を追加する。
};

この例では、以下のポイントを示している。

  • CUnknown クラスは IUnknown インターフェイスを実装する。新しいコンポーネントは CUnknown およびコンポーネントがサポートするすべてのインターフェイスを継承する。コンポーネントは、CUnknown から継承した別の基底クラスから派生することができる。
  • DECLARE_IUNKNOWN マクロは、委任 IUnknown メソッドをインライン メソッドとして宣言することができる。
  • CUnknown クラスは、INonDelegatingUnknown の実装を提供する。
  • IUnknown 以外のインターフェイスを実装するためには、派生クラスは NonDelegatingQueryInterface メソッドをオーバーライドし、新しいインターフェイスの IID のテストを行う必要がある。
  • クラス コンストラクタは、CUnknown のコンストラクタ メソッドを起動する。

フィルタ開発における次のステップでは、アプリケーションを有効にしてコンポーネントの新しいインスタンスを作成する。このためには、DLL に関する知識に加え、クラス ファクトリおよびクラス コンストラクタ メソッドとの関係を理解していることが必要になる。詳細については、「DLL の作成方法」を参照すること。


DLL の作成方法

ここでは、Microsoft® DirectShow® でコンポーネントをダイナミック リンク ライブラリ (DLL) として実装する方法を説明する。このトピックは、CUnknown 基底クラスからコンポーネントを派生することによって IUnknown インターフェイスを実装する方法を説明した「IUnknown の実装方法」の続きである。

このトピックは、以下のセクションを含んでいる。

  • クラス ファクトリとファクトリ テンプレート
  • ファクトリ テンプレートの配列
  • DLL 関数

(汎用 COM オブジェクトとは異なり) DirectShow フィルタの登録には、ここで説明していないいくつかの追加のステップが必要になる。フィルタの登録については、「DirectShow オブジェクトの登録方法」を参照すること。

クラス ファクトリとファクトリ テンプレート

クライアントは COM オブジェクトのインスタンスを作成する前に、CoGetClassObject 関数呼び出しを使用してオブジェクトのクラス ファクトリのインスタンスを作成する。次にクライアントは、クラス ファクトリの IClassFactory::CreateInstance メソッドを呼び出す。実際にコンポーネントを作成したり、要求されたインターフェイスへのポインタを返すのはクラス ファクトリである。(CoCreateInstance 関数は、これらのステップを関数呼び出し内で組み合わせる。)

次の図に、メソッド呼び出しのシーケンスを示す。

CoGetClassObject は、DLL で定義された DllGetClassObject 関数を呼び出す。この関数はクラス ファクトリを作成し、クラス ファクトリ上のインターフェイスへのポインタを返す。DirectShow は DllGetClassObject を実装するが、この関数は特定の部分でコードに依存する。この動作を理解するためには、DirectShow がどのようにクラス ファクトリを実装するかを理解することが必要である。

クラス ファクトリは、別の COM オブジェクトを作成する処理に特化した COM オブジェクトである。それぞれのクラス ファクトリでは、作成するオブジェクトの型が決まっている。DirectShow では、すべてのクラス ファクトリは同じ C++ クラス CClassFactory のインスタンスである。クラス ファクトリは、ファクトリ テンプレートと呼ばれるクラス CFactoryTemplate によって特化される。各クラス ファクトリは、ファクトリ テンプレートへのポインタを保持する。ファクトリ テンプレートには、特定のコンポーネントに関する情報 (コンポーネントのクラス識別子 (CLSID) など) と、そのコンポーネントを作成した関数へのポインタが格納される。

DLL は、ファクトリ テンプレートのグローバル配列を DLL 内の各コンポーネントに 1 つずつ宣言する。新しいクラス ファクトリを作成するとき、DllGetClassObject は同じ CLSID を持つテンプレートの配列を探す。該当するものが見つかると、DllGetClassObject は当該テンプレートへのポインタを保持するクラス ファクトリを作成する。クライアントが IClassFactory::CreateInstance を呼び出すと、クラス ファクトリはテンプレートに定義されているインスタンス化関数を呼び出す。

次の図に、メソッド呼び出しのシーケンスを示す。

このアーキテクチャの利点は、クラス ファクトリ全体を実装することなく、インスタンス化関数などのコンポーネントに固有のいくつかの要素だけを定義すれば良いということである。

ファクトリ テンプレートの配列

ファクトリ テンプレートは、以下のパブリック メンバ変数を格納する。

const WCHAR *              m_Name;                // 名前
const CLSID *              m_ClsID;               // CLSID
LPFNNewCOMObject           m_lpfnNew;             // コンポーネントのインスタンス
                                                  //   を作成する関数
LPFNInitRoutine            m_lpfnInit;            // 初期化関数 (オプション)
const AMOVIESETUP_FILTER * m_pAMovieSetup_Filter; // セットアップ情報 (フィルタ用)

2 つの関数ポインタ m_lpfnNew および m_lpfnInit は、以下の型定義を使用する。

typedef CUnknown *(CALLBACK *LPFNNewCOMObject)(LPUNKNOWN pUnkOuter, HRESULT *phr);
typedef void (CALLBACK *LPFNInitRoutine)(BOOL bLoading, const CLSID *rclsid);

1 番目の定義は、コンポーネントのインスタンス化関数である。2 番目の定義は、オプションの初期化関数である。初期化関数を指定した場合、関数は DLL エントリ ポイント関数内部から呼び出される。(DLL エントリ ポイント関数については、後の節で説明する。)

たとえば CUnknown から継承した CMyComponent という名前のコンポーネントを含む DLL を作成するとする。この場合、以下の項目を DLL に提供しなければならない。

  • 初期化関数。CMyComponent の新しいインスタンスを返すプライベート メソッド。
  • g_Templates という名前のファクトリ テンプレートのグローバル配列。この配列は、CMyComponent のファクトリ テンプレートを格納する。
  • 配列のサイズを指定する g_cTemplates という名前のグローバル変数。

これらの項目を宣言する例を以下に示す。

// 新しいインスタンスを返すプライベート メソッド
CUnknown * WINAPI CMyComponent::CreateInstance(LPUNKNOWN pUnk, HRESULT *pHr) {
    CMyComponent *pNewObject = new CMyComponent(NAME("My Component"), pUnk, pHr );
if (pNewObject == NULL) {
*phr = E_OUTOFMEMORY;
    }
return pNewObject;
}

CFactoryTemplate g_Templates[1] =
{
    {
      L"My Component",      // 名前
      &CLSID_MyComponent,         // CLSID
      CMyComponent::CreateInstance,   // MyComponent のインスタンスを作成するメソッド
      NULL,                           // 初期化関数
      NULL                            // セットアップ情報 (フィルタ用)
    }
};
int g_cTemplates = sizeof(g_Templates) / sizeof(g_Templates[0]);

CreateInstance メソッドは、クラス コンストラクタを呼び出して新しいクラス インスタンスへのポインタを返す。パラメータ pUnk は、集成化 IUnknown へのポインタである。このパラメータをクラス コンストラクタに渡す。パラメータ pHr は、HRESULT 値へのポインタである。クラス コンストラクタはこれを適切な値に設定する。ただしコンストラクタが失敗した場合は、値を E_OUTOFMEMORY に設定する。

NAME マクロは、デバッグ ビルドにおいて文字列を生成するが、リテール ビルドでは NULL に解決する。この例でコンポーネントに与えられている名前は、デバッグ ログには記録されるが、最終バージョンではメモリを占有しない。

CreateInstance はプライベート メソッドなので任意の名前を持つことができる。クラス ファクトリは CreateInstance へのポインタをファクトリ テンプレート内で受け取る。ただし、g_Templates と g_cTemplates は、クラス ファクトリが期待するグローバル変数なので、必ずこの名前を持たなければならない。

DLL 関数

DLL の登録、登録解除、メモリへのロードを可能にするためには、DLL は以下の関数を実装しなければならない。

  • DllMain : DLL エントリ ポイント。この名前 DllMain は、ライブラリで定義された関数名のプレースホルダである。DirectShow の実装は、DllEntryPoint という名前を使用する。詳細については、Platform SDK を参照すること。
  • DllGetClassObject : クラス ファクトリのインスタンスを作成する。前の節にて解説済み。
  • DllCanUnloadNow : DLL が安全にアンロード可能かどうかを照会する。
  • DllRegisterServer : DLL のレジストリ エントリを作成する。
  • DllUnregisterServer : DLL のレジストリ エントリを削除する。

これらのうち、最初の 3 つは DirectShow によって実装される。ファクトリ テンプレートが初期化関数を m_lpfnInit メンバ変数で提供する場合、その関数は DLL エントリ ポイント関数内部から呼び出される。システムが DLL エントリ ポイント関数を呼び出すタイミングについては、Platform SDK の DllMain を参照すること。

DllRegisterServer と DllUnregisterServer は自分で実装しなければならない。しかし、DirectShow には必要な操作を行うための AMovieDllRegisterServer2 関数が提供されている。次の例に示すように、単にこの関数をコンポーネントにラップすれば良い。

STDAPI DllRegisterServer()
{
    return AMovieDllRegisterServer2( TRUE );
}

STDAPI DllUnregisterServer()
{
    return AMovieDllRegisterServer2( FALSE );
}

ただし、DllRegisterServer および DllUnregisterServer 内では、登録プロセスを必要に応じてカスタマイズすることができる。DLL にフィルタが含まれているなら、いくつかの追加作業が必要である。詳細については、「DirectShow オブジェクトの登録方法」を参照すること。

モジュール定義 (.def) ファイル内で、エントリ ポイント関数以外のすべての DLL 関数をエクスポートする。以下に、.def ファイルの例を示す。

EXPORTS
    DllGetClassObject PRIVATE
    DllCanUnloadNow PRIVATE
    DllRegisterServer PRIVATE
    DllUnregisterServer PRIVATE

DLL は Regsvr32.exe ユーティリティを使って登録することができる。


DirectShow オブジェクトの登録方法

このトピックでは、Microsoft® DirectShow® フィルタを自己登録にする方法を説明する。以下のセクションで構成される。

  • レジストリ キーのレイアウト
  • フィルタの登録
  • フィルタの登録解除

ここでは、DLL の作成方法については説明しない。DLL 作成の詳細については、「DLL の作成方法」を参照すること。

レジストリ キーのレイアウト

DirectShow フィルタは、次の 2 つの場所に登録される。

  • フィルタが含まれた DLL は、そのフィルタの COM サーバーとして登録される。アプリケーションが CoCreateInstance を呼び出してフィルタを作成すると、Microsoft® Windows® COM ライブラリはそのレジストリ エントリを使って DLL を見つける。
  • フィルタに関する情報は、フィルタ カテゴリの内部に登録されるので、システム デバイス列挙子とフィルタ マッパーは、この情報を見つけることができる。

次に、DLL のレジストリ エントリを示す。

HKEY_CLASSES_ROOT
    CLSID
        Filter CLSID
            REG_SZ: (Default) = フレンドリ名

            InprocServer32
                REG_SZ: (Default) = DLL のファイル名
                REG_SZ: ThreadingModel = Both

次に、フィルタ情報のレジストリ エントリを示す。

HKEY_CLASSES_ROOT
    CLSID
        Category
            Instance
                Filter CLSID
                    REG_SZ: CLSID = フィルタの CLSID
                    REG_BINARY: Filter Data = フィルタ情報
                    REG_SZ: FriendlyName = フレンドリ名

"Category" は、フィルタ カテゴリの GUID である。フィルタ情報はバイナリ フォーマットにパックされる。IFilterMapper2 インターフェイスが、フィルタのレジストリを検索するときに、このデータをアンパックする。

フィルタの登録

フィルタを登録するには、次の操作を行う。

  1. フィルタ情報を宣言する。
  2. フィルタのファクトリ テンプレートに、フィルタ情報へのポインタを含める。
  3. DllRegisterServer 関数を実装する。

以下では、これらの操作について詳しく説明する。

フィルタ情報の宣言

最初のステップは、フィルタ情報の宣言である。DirectShow は、フィルタ、ピン、およびメディア タイプを記述するために、次のような構造体を定義している。

AMOVIESETUP_FILTER | フィルタを記述する。
AMOVIESETUP_PIN | ピンを記述する。
AMOVIESETUP_MEDIATYPE | メディア タイプを記述する。

これらの構造体はネストしている。フィルタ構造体は ピン構造体の配列へのポインタを持ち、それぞれのピン構造体は、メディア タイプ構造体の配列へのポインタを持っている。これらの構造体によって、IFilterMapper2 インターフェイスがフィルタを見つけるために必要な情報が十分に与えられる。構造体によって、フィルタが完全に記述されるわけではない。たとえば、フィルタが同じピンの複数のインスタンスを生成する場合でも、そのフィルタに対して 1 つの AMOVIESETUP_PIN 構造体を宣言するだけでよい。また、フィルタは、登録するメディア タイプのすべての組み合わせをサポートするように求められてはいない。

このセットアップ構造体を、DLL の内部でグローバル変数として宣言する。次の例に、出力ピンを 1 つ持つフィルタを示す。

static const WCHAR g_wszName[] = L"Some Filter";

AMOVIESETUP_MEDIATYPE sudMediaTypes[] = {
    { &MEDIATYPE_Video, &MEDIASUBTYPE_RGB24 },
    { &MEDIATYPE_Video, &MEDIASUBTYPE_RGB32 },
};

AMOVIESETUP_PIN sudOutputPin = {
    L"",            // 現在は使用されていない。
    FALSE,          // このピンをレンダリングするか?
    TRUE,           // これは出力ピンか?
    FALSE,          // このフィルタはゼロ インスタンスを生成できるか?
    FALSE,          // このフィルタは複数のインスタンスを生成するか?
    &GUID_NULL,     // 現在は使用されていない。
    NULL,           // 現在は使用されていない。
    2,              // メディア タイプの数。
    sudMediaTypes   // メディア タイプへのポインタ。
};

AMOVIESETUP_FILTER sudFilterReg = {
    &CLSID_SomeFilter,      // フィルタの CLSID
    g_wszName,              // フィルタの名前
    MERIT_NORMAL,           // メリット
    1,                      // ピン タイプの数
    &sudPins                // ピン情報へのポインタ
};

フィルタ名はほかの場所でも使用するので、静的グローバル変数としてフィルタ名を宣言している。

ファクトリ テンプレートの宣言

次のステップは、フィルタ用のファクトリ テンプレートの宣言である。ファクトリ テンプレートは、クラス ファクトリの情報を格納する C++ クラスである。DLL の中で、DLL 内のフィルタまたは COM コンポーネントごとに 1 つずつ、ファクトリ テンプレートのグローバル配列を宣言する。この配列の名前は g_Templates でなければならない。ファクトリ テンプレートの詳細については、「DLL の作成方法」を参照すること。

ファクトリ テンプレートの m_pAMovieSetup_Filter メンバは、前に説明した AMOVIESETUP_FILTER 構造体へのポインタである。次の例に、ファクトリ テンプレートを示す。前の例で示した構造体を使用している。

CFactoryTemplate g_Templates[] =
{
    {
        g_wszName,                      // 名前
        &CLSID_SomeFilter,              // CLSID
        CSomeFilter::CreateInstance,    // 作成関数
        NULL,
        &sudFilterReg                   // フィルタ情報へのポインタ
    }
};
int g_cTemplates = sizeof(g_Templates) / sizeof(g_Templates[0]);

DllRegisterServer の実装

最後のステップは、DllRegisterServer 関数の実装である。コンポーネントが含まれた DLL は、この関数を公開しなければならない。この関数は、セットアップ プログラム、またはユーザーが Regsvr32.exe ツールを実行したときに呼び出される。

次の例に、DlLRegisterServer の最小限の実装を示す。

STDAPI DllRegisterServer(void)
{
    return AMovieDllRegisterServer2(TRUE);
}

DirectShow 関数である AMovieDllRegisterServer2 は、g_Templates 配列のすべてのコンポーネント用にレジストリのエントリを作成する。ただし、この関数には制限がいくつかある。まず、この関数はすべてのフィルタを CLSID_LegacyAmFilterCategory カテゴリに割り当てるが、すべてのフィルタがこのカテゴリに属するわけではない。たとえば、キャプチャ フィルタや圧縮フィルタは、それぞれのカテゴリを持っている。カテゴリ一覧については、「フィルタ カテゴリ」を参照すること。次に、フィルタがハードウェア デバイスをサポートしている場合は、AMovieDLLRegisterServer2 が処理しない 2 つの情報、つまり "メディア" と "ピン カテゴリ" を登録する必要がある。メディアは、ハードウェア デバイスの通信方法 (バスなど) を定義し、ピン カテゴリは、ピンの機能を定義する。メディアの詳細については、Microsoft® Windows® Driver Development Kit (DDK) の「KSPIN_MEDIUM」を参照すること。ピン カテゴリの一覧については、「ピン プロパティ セット」を参照すること。

フィルタ カテゴリ、メディア、またはピン カテゴリを指定する場合は、DllRegisterServer 内から IFilterMapper2::RegisterFilter メソッドを呼び出す。このメソッドは、REGFILTER2 構造体へのポインタを受け取る。REGFILTER2 構造体は、フィルタに関する情報を指定する。

面倒なのは、REGFILTER2 構造体が、ピンを登録するためのフォーマットを 2 種類サポートしていることである。dwVersion メンバで、このフォーマットを指定する。

  • dwVersion が 1 の場合、ピン フォーマットは AMOVIESETUP_PIN (前で説明) である。
  • dwVersion が 2 の場合、ピン フォーマットは REGFILTERPINS2 である。

REGFILTERPINS2 構造体には、ピン メディアとピン カテゴリのエントリが含まれる。また、一部の項目については、AMOVIESETUP_PIN がブール値として宣言するビット フラグを使用する。

次の例に、DllRegisterServer の中から IFilterMapper2::RegisterFilter を呼び出す方法を示す。

REGFILTER2 rf2FilterReg = {
    1,              // バージョン 1 (ピン メディアとピン カテゴリはなし)
    MERIT_NORMAL,   // メリット
    1,              // ピンの数
    &sudPins        // ピン情報へのポインタ
};

STDAPI DllRegisterServer(void)
{
    HRESULT hr;
    IFilterMapper2 *pFM2 = NULL;

    hr = AMovieDllRegisterServer2(TRUE);
    if (FAILED(hr))
        return hr;

    hr = CoCreateInstance(CLSID_FilterMapper2, NULL, CLSCTX_INPROC_SERVER,
            IID_IFilterMapper2, (void **)&pFM2);

    if (FAILED(hr))
        return hr;

    hr = pFM2->RegisterFilter(
        CLSID_SomeFilter,                // フィルタの CLSID
        g_wszName,                       // フィルタの名前
        NULL,                            // デバイス モニカ
        &CLSID_VideoCompressorCategory,  // ビデオ コンプレッサのカテゴリ
        g_wszName,                       // インスタンス データ
        &rf2FilterReg                    // フィルタ情報へのポインタ
    );
    pFM2->Release();
    return hr;
}

フィルタの登録解除

フィルタの登録を解除するには、DllUnregisterServer 関数を実装する。この関数の中で、値 FALSE を使って DirectShow AMovieDllRegisterServer2 関数を呼び出す。フィルタの登録時に IFilterMapper2::RegisterFilter を呼び出した場合は、ここで IFilterMapper2::UnregisterFilter メソッドを呼び出す。

次の例に、フィルタの登録を解除する方法を示す。

STDAPI DllUnregisterServer()
{
    HRESULT hr;
    IFilterMapper2 *pFM2 = NULL;

    hr = AMovieDllRegisterServer2(FALSE);
    if (FAILED(hr))
        return hr;

    hr = CoCreateInstance(CLSID_FilterMapper2, NULL, CLSCTX_INPROC_SERVER,
            IID_IFilterMapper2, (void **)&pFM2);

    if (FAILED(hr))
        return hr;

    hr = pFM2->UnregisterFilter(&CLSID_VideoCompressorCategory,
            g_wszName, CLSID_SomeFilter);

    pFM2->Release();
    return hr;
}


変換フィルタ

このセクションでは、変換フィルタの作成方法、変換フィルタの種類、変換基底クラスの使用方法、オーバーライドする基底クラス メンバ関数、および変換フィルタの接続機会と接続方法について説明する。

  • 変換フィルタの作成
  • 変換基底クラス CTransformFilter および CTransInPlaceFilter の使用
  • 変換フィルタの接続
  • C/C++ による変換フィルタの開発
  • 圧縮フィルタについて
  • エフェクト フィルタについて


変換フィルタの作成

変換フィルタは、入力ピンに入力されたメディア データを変換し、変換後のデータを出力ピンに送信する。変換フィルタは、データの圧縮や圧縮解除、オーディオ データやビジュアル データの分割、コントラストやワーブリングなどのエフェクトのメディア データへの適用といった用途に使用することができる。Microsoft® DirectShow® には、いろいろな変換を行ういくつかのサンプル 変換フィルタが用意されている。

ここでは、DirectShow C++ クラス ライブラリを使用する変換を作成するステップを説明する。5 つの基本ステップを説明する中で、最後のステップとして、派生クラスの必要なメンバ関数をオーバーライドして変換フィルタを実装する方法を説明する。また、変換フィルタの作成に伴う 2 つのよくある質問 (どの基底クラスを使用すべきか?、どのようにメンバ関数をオーバーライドするか?) についての答えも示す。

このトピックは、以下のセクションを含んでいる。

  • 変換フィルタを作成する
  • フィルタがメディア サンプルをコピーする必要性を判断する
  • 使用する基底クラスを決める
  • フィルタをインスタンス化する
  • 追加したインターフェイスを NonDelegatingQueryInterface で利用できるようにする
  • 基底クラス メンバ関数をオーバーライドする

詳細については、以下のトピックを参照すること。

  • フィルタ
  • C/C++ による変換フィルタの開発
  • 変換基底クラス CTransformFilter および CTransInPlaceFilter の使用
  • 変換フィルタの接続

変換フィルタを作成する

変換フィルタを作成する作業は、以下のステップに分けられる。

  1. フィルタがメディア サンプルをコピーする必要があるか、またはその場でメディア サンプルを処理できるかを判断する。

    メディア ストリーム内のコピーの数は少ないほど良い。しかし、コピー操作が必要なフィルタもある。この点が基底クラスの選択に影響する。

  2. 使用する基底クラスを決め、その基底クラスからフィルタ クラス (および必要であればピン クラス) を派生させる。

    このステップでは、フィルタのヘッダーを作成する。多くの場合は、変換基底クラスを使用して適切な変換フィルタ クラスからクラスを派生させ、いくつかのメンバ関数をオーバーライドする。また、汎用的な基底クラスを使うこともできる。接続およびネゴシエーション メカニズムのほとんどはこれらのクラスによって実装されるが、さらにメンバ関数をオーバーライドすることによって柔軟性を提供することができる。

  3. フィルタをインスタンス化するのに必要なコードを追加する。

    このステップでは、スタティックな CreateInstance メンバ関数を派生クラスに追加し、さらにフィルタの名前、CLSID、およびそのメンバ関数へのポインタを格納するグローバル配列を追加する。

  4. フィルタの一意なインターフェイスを渡すための NonDelegatingQueryInterface メンバ関数を追加する。

    このステップは、Component Object Model (COM) の、基底クラス以外のインターフェイスの実装に関する側面を示している。

  5. 基底クラス メンバ関数をオーバーライドする。

    この作業には、フィルタに固有の変換関数を書いて、アロケータ サイズの設定やメディア タイプの提供などの、接続プロセスに必要ないくつかのメンバ関数をオーバーライドすることが含まれる。

フィルタがメディア サンプルをコピーする必要性を判断する

すべてのコピー処理は貴重な CPU サイクルを使用するので、フィルタの開発者は可能であればメディア サンプルのコピー処理を行わないようにすべきである。最も望ましいのは、別のフィルタから取得したアロケータ上でその場でメディア サンプルを変更するようなフィルタを書くことである。場合によってはこのような処理が不可能で、コピー処理を実行しなければならないことがある。

コピーの必要がない変換インプレイス フィルタの実行時のオーバーヘッドは、関数のそれに比べて大きくなるということはない。しかし、変換をフィルタとしてパッケージ化することにより、フィルタ グラフ アーキテクチャの完全な柔軟性を手に入れることができる。

以下のような場合は、フィルタを変換インプレイス フィルタではなくコピー変換フィルタとして作成する。

  • 変換によって生成されるデータが、入力のアロケータ (たとえばデコンプレッサ フィルタ) で提供される領域よりも大きい場合、または変換によって出力に生成されるデータが少なく、メモリを整理しなければならない場合。
  • オリジナルのメディア データを保持しなければならない場合。変換フィルタがデータ ストリームを分割するスプリッタがこれに該当する。
  • デコンプレッサ フィルタが、デルタ情報に関して隣接フレームに依存しながら時系列圧縮を行っている場合。この場合、別個のコピーを作成する必要がある。これは、別のフィルタがオリジナルのデータにアクセスしてそれを変更することをデコンプレッサが許可しないことがその主な理由である。
  • フィルタがキューに依存している場合。たとえば不規則に間隔が空けられたビデオ フレームの配送を円滑にするためにキューを作成するフィルタは、サンプルをコピーする必要がある。

使用する基底クラスを決める

変換フィルタの基底クラスを選ぶ前に、フィルタに複数の入力ピンおよび出力ピンが必要かどうかを決めなければならない。複数のピンが必要な場合は、CBaseFilter からフィルタ クラスを派生しなければならない。

フィルタでビデオ変換を行う必要がある場合は、CVideoTransformFilter からフィルタ クラスを派生しなければならない。

それ以外の場合は、CTransformFilter または CTransInPlaceFilter からフィルタ クラスを派生する。どちらを使用するかを決めるためには、フィルタがメディア サンプルをコピーする必要があるか、またはメディア サンプルをその場で変換することができるかを決めなければならない。すべてのコピー処理は貴重な CPU サイクルを使用するので、フィルタの開発者は可能であればメディア サンプルのコピー処理を行わないようにすべきである。最も望ましいのは、別のフィルタから取得したアロケータ上でその場でメディア サンプルを変更するようなフィルタを書くことである。場合によってはこのような処理が不可能で、コピー処理を実行しなければならないことがある。

コピーの必要がない変換インプレイス フィルタの実行時のオーバーヘッドは、関数のそれに比べて大きくなるということはない。しかし、変換をフィルタとしてパッケージ化することにより、フィルタ グラフ アーキテクチャの完全な柔軟性を手に入れることができる。

以下のような場合は、フィルタを変換インプレイス フィルタではなくコピー変換フィルタとして作成する。

  • 変換によって生成されるデータが、入力のアロケータ (たとえばデコンプレッサ フィルタ) で提供される領域よりも大きい場合、または変換によって出力に生成されるデータが少なく、メモリを整理しなければならない場合。
  • オリジナルのメディア データを保持しなければならない場合。変換フィルタがデータ ストリームを分割するスプリッタがこれに該当する。
  • デコンプレッサ フィルタが、フレーム間で変更された情報に関して隣接フレームに依存しながら時系列圧縮を行っている場合。この場合、別個のコピーを作成する必要がある。これは、別のフィルタがオリジナルのデータにアクセスしてそれを変更することをデコンプレッサが許可しないことがその主な理由である。
  • フィルタがキューに依存している場合。たとえば不規則に間隔が空けられたビデオ フレームの配送を円滑にするためにキューを作成するフィルタは、サンプルをコピーする必要がある。

変換フィルタがメディア サンプルをコピーするか、またはメディア サンプルをその場で変換するかを決定した後は、使用する基底クラスと、オーバーライドおよび実装するメンバ関数を決める必要がある。その後、派生クラスを定義する。

基底クラスの一部のメンバ関数は、基底クラスで純粋仮想関数として宣言されている (実装を持たない) か、またはエラー値を返す以外の動作を行わないデフォルト実装を持っているので、派生クラスでオーバーライドしなければならない。

フィルタ クラスは、変換基底クラス CTransformFilter、CTransInPlaceFilter、または CVideoTransformFilter から派生させるか、または汎用的な CBaseFilter フィルタ クラスから派生させる。接続、メディア タイプ、およびアロケータ ネゴシエーション コードのほとんどは基底クラスで扱われ、変換クラスによって継承される。変換クラスを使用すると、1 つのフィルタ クラス (ピン クラスなし) を派生させるだけでフィルタを作成することができる。変換クラスは、変換フィルタを作成するプロセスを簡単にするために、変換フィルタの動作についていくつかの仮定を行っている。

CTransformFilter および CTransInPlaceFilter について、および派生クラスによって通常オーバーライドされるメンバ関数については、「変換基底クラス CTransformFilter および CTransInPlaceFilter の使用」を参照すること。

フィルタをインスタンス化する

すべてのフィルタは、基底クラスがフィルタをインスタンス化するためのコードを追加しなければならない。フィルタをインスタンス化するには、2 種類のコードをフィルタに追加する必要がある。1 つは派生フィルタ クラスに追加するスタティックな CreateInstance メンバ関数で、もう 1 つは、この関数へのアクセス法を基底クラスのクラス ファクトリに通知するためのコードである。

一般に、CreateInstance メンバ関数は派生フィルタ クラスに対してコンストラクタを呼び出す。以下に、CreateInstance メンバ関数の実装例を示す。

CUnknown *CGargle::CreateInstance(LPUNKNOWN punk, HRESULT *phr) {

    CGargle *pNewObject = new CGargle(NAME("Gargle Filter"), punk, phr);
    if (pNewObject == NULL) {
    *phr = E_OUTOFMEMORY;
    }

return pNewObject;
} // CreateInstance

クラス ファクトリと通信を行うためには、CFactoryTemplate オブジェクトのグローバル配列を g_Templates として宣言し、フィルタの名前、フィルタのクラス識別子 (CLSID)、およびフィルタ オブジェクトを作成するスタティック CreateInstance メンバ関数へのポインタを指定する。

// CreateInstance メカニズムに必要
CFactoryTemplate g_Templates[2]=
    { { L"Gargle filter"              , &CLSID_Gargle , CGargle::CreateInstance          }
    , { L"Gargle filter Property Page", &CLSID_GargProp, CGargleProperties::CreateInstance}
    };

int g_cTemplates = sizeof(g_Templates) / sizeof(g_Templates[0]);

フィルタが自己登録を行うようにするには、CFactoryTemplate テンプレートにパラメータを追加する。この処理については、「DirectShow オブジェクトの登録方法」を参照すること。

最後に、フィルタを Strmbase.lib にリンクし、.def ファイルを使用して DllGetClassObject および DllCanUnloadNow をエクスポートする。

追加したインターフェイスを NonDelegatingQueryInterface で利用できるようにする

IUnknown メンバ関数 (基底クラスでは INonDelegatingUnknown と呼ばれる) を実装する必要があるのは、基底クラスに含まれていないインターフェイス (たとえばプロパティ ページの作成に必要なインターフェイス) を追加するフィルタだけである。基底クラスは、IUnknown メソッドのデフォルトの実装を提供する。COM ベースのコード内の IUnknown メソッドは、オブジェクトからインターフェイスを取得し、そのインターフェイスの参照カウントをインクリメントおよびデクリメントする。たとえば、IUnknown::QueryInterface メソッドはインターフェイスをオブジェクトから取得する。

DirectShow では、INonDelegatingUnknown という特殊な IUnknown クラスが定義されていて、このクラスのメソッドは IUnknown と同じ働きを持つ。(名前が変更されているのは、オブジェクトを集成できるようにするためである。) NonDelegatingQueryInterface メソッドは、いずれかのオブジェクトまたはアプリケーションが、実装するインターフェイスについてピンまたはフィルタに照会する場合に呼び出される。基底クラス実装にリストされている以外のインターフェイスをフィルタが実装する場合は、NonDelegatingQueryInterface メソッドをオーバーライドして、実装しているインターフェイスへのポインタを返す必要がある。たとえば、以下のコード例は、メンバ関数をオーバーライドして、ISpecifyPropertyPages および IPersistStream インターフェイスへの参照を配布する。

// 永続ストリーム、プロパティ ページ、および IGargle インターフェイスを公開する。
STDMETHODIMP CGargle::NonDelegatingQueryInterface(REFIID riid, void **ppv) {

if (riid == IID_IGargle) {
return GetInterface((IGargle *) this, ppv);
} else if (riid == IID_ISpecifyPropertyPages) {
return GetInterface((ISpecifyPropertyPages *) this, ppv);
} else if (riid == IID_IPersistStream) {
        AddRef();     // 参照カウントを追加する
*ppv = (void *)(IPersistStream *)this;
return NOERROR;

} else {
return CTransInPlaceFilter::NonDelegatingQueryInterface(riid, ppv);
    }
} // NonDelegatingQueryInterface

注 : このサンプルは、メンバ関数の CTransInPlaceFilter 実装を呼び出して終了処理を行う。

基底クラス メンバ関数をオーバーライドする

使用する基底クラスを決めたら (「使用する基底クラスを決める」を参照)、ヘッダーを書いて、実装するメンバ関数を定義する。このとき、変換基底クラス (CTransformFilter または CTransInPlaceFilter) または汎用の CBaseFilter フィルタ クラスのいずれからフィルタ クラスを派生させるか決める必要がある。ここでは、以下のメンバ関数の実装法について説明する。

  • Transform メンバ関数をオーバーライドする
  • CheckInputType メンバ関数をオーバーライドする
  • CheckTransform メンバ関数をオーバーライドする
  • DecideBufferSize メンバ関数をオーバーライドする
  • GetMediaType メンバ関数をオーバーライドする
  • ピン メンバ関数をオーバーライドする
  • CBaseOutput::DecideAllocator メンバ関数をオーバーライドする

Transform メンバ関数をオーバーライドする

派生クラスの Transform メンバ関数は、別のサンプルを転送するために、フィルタの入力ピンの IMemInputPin::Receive メソッドが呼び出されるごとに呼び出される。フィルタの実際の目的の処理を実行するコードを、このメンバ関数またはそこから呼び出される関数に挿入する。一般に、コピー変換フィルタは、変換コードをプライベートな Copy メンバ関数に関連付けるが、変換インプレイス関数は 1 つのバッファ内のコードを変更する。

CheckInputType メンバ関数をオーバーライドする

ピン接続の間、提示されたメディア タイプが受け付け可能かどうかを調べるために入力ピンの CheckMediaType メンバ関数が呼び出される。CTransformInputPin::CheckMediaType メンバ関数は、派生フィルタ クラスの CheckInputType メンバ関数をそのメディア タイプで呼び出すように実装される。フィルタが対応しているメディア タイプを使用するためには、このメンバ関数を実装しなければならない。以下のコード例に、MEDIATYPE_Audio 以外のメディア タイプを拒否する CGargle::CheckInputType メンバ関数の一部を示す。

HRESULT CGargle::CheckInputType(const CMediaType *pmt) {
    ...
    // Audio 以外のタイプを拒否する
    if (pmt->majortype != MEDIATYPE_Audio) {
    return E_INVALIDARG;
    }

CheckTransform メンバ関数をオーバーライドする

コピー変換フィルタは、入力ピンから出力ピンにメディア タイプを変換することができる。したがって、出力ピンが接続される (すなわちそのメディア タイプが既知である) 場合、接続時に CTransformInputPin::CheckMediaType メンバ関数が呼び出されると、入力タイプから出力タイプへの変換が有効かどうかを調べるために、派生クラスの CheckTransform メンバ関数が呼び出される。このメンバ関数は、CTransformOutputPin::CheckMediaType が呼び出されたときも呼び出される。

CTransInPlaceFilter クラスでは、このメンバ関数は単に S_OK を返すために基底クラスのヘッダー ファイル内で実装される。なぜなら、このメンバ関数を呼び出す CTransformFilter の関数は、CheckInputType を呼び出すために CTransInPlaceFilter でオーバーライドされるからである。この操作は、コピー変換フィルタの場合と同様に、変換インプレイス フィルタ内でメディア タイプが変化しないことを想定している。

DecideBufferSize メンバ関数をオーバーライドする

コピー変換フィルタは、コピー先のアロケータのプロパティを設定しなければならないことがある。このような状況は、ダウンストリーム フィルタが新しく作成されたアロケータを提供した場合 (すなわち、さらに先のダウンストリームからのアロケータを渡しているのではない場合) や、出力ピンが独自のアロケータを作成しなければならない場合に起こりやすい。この場合、純粋仮想 CBaseOutputPin::DecideBufferSize メンバ関数が CBaseOutputPin::DecideAllocator メンバ関数から呼び出され、派生クラスが参照先のアロケータ オブジェクトの IMemAllocator::SetProperties メソッドを呼び出すことによってバッファ要求を満たす。

別のフィルタのアロケータは常に使用されているので、CTransInPlaceFilter::DecideBufferSize メソッドが呼び出されることはない。このメソッドは基底クラスのヘッダー ファイルで実装されて E_UNEXPECTED を返す。

GetMediaType メンバ関数をオーバーライドする

ピンは、列挙子を提供して、ほかのオブジェクトがピンのメディア タイプを判定できるようにする。ピンは、メディア タイプ列挙子 (IEnumMediaTypes インターフェイス) を提供する (メディア タイプ列挙子は、ピン クラスの GetMediaType メンバ関数を呼び出すためにピン基底クラスが実装する)。コピー変換フィルタ クラスでは、それぞれのピンの CTransformOutputPin::GetMediaType メンバ関数は、フィルタ クラスの仮想 CTransformFilter::GetMediaType メンバ関数を呼び出すだけである。このメンバ関数を派生クラスで実装して、メディア タイプのリスト内のサポートされている各メディア タイプを提供しなければならない。

変換インプレイス クラスでは、列挙子は、変換フィルタのアップストリームとダウンストリームのフィルタの間に透過チャンネルを形成する。変換フィルタの入力ピンが列挙を行わなければならない場合、入力ピンはダウンストリーム フィルタの入力ピンから列挙子を取得する。出力ピンが列挙を行わなければならない場合、出力ピンはアップストリーム フィルタの出力ピンから列挙子を取得する。したがって、2 つの変換インプレイス フィルタを互いに接続するためには、そのうちの少なくとも 1 つがそれ以外のものに接続していなければならない。なぜなら、どちらの変換インプレイス フィルタも接続のためのメディア タイプを提示できないからである。

ピン メンバ関数をオーバーライドする

フィルタ クラスを変換クラスから派生し、複数の入力ピンまたは出力ピンを使用する場合は、ピン クラス (たとえば CTransformInputPin または CTransformOutputPin) をオーバーライドする必要がある。ピン クラスをオーバーライドする場合は、CTransformFilter または CTransInPlaceFilter の GetPin メンバ関数をオーバーライドして、派生クラスからピン オブジェクトを作成できるようにしなければならない。一方のピン クラス (たとえば CTransformInputPin) をオーバーライドし、GetPin をオーバーライドしてピン オブジェクトを作成する場合は、さらに同じ基底クラスのもう一方のピン オブジェクト (たとえば CTransformOutputPin) も作成するように GetPin をオーバーライドしなければならない。

複数の入力または出力ピンを使用する場合は、変換クラスよりも CBaseFilter からフィルタを派生させる方が簡単である。

CBaseOutput::DecideAllocator メンバ関数をオーバーライドする

基底クラスは CBaseOutputPin::DecideAllocator を実装して、出力ピンが自動的にダウンストリーム ピンのアロケータを使うようにする。派生クラスにおける最も一般的な変更は、オブジェクト独自のアロケータ (またはアップストリーム フィルタからのアロケータ) の使用を強制することである。たとえば DirectShow のモデルでは、ソース フィルタはメディア サンプルを次のフィルタにプッシュし、独自のアロケータを必要とする。たとえば、変換インプレイス フィルタを書いてそれをソース フィルタとデコンプレッサ フィルタの間に配置した場合、変換フィルタはソース フィルタのアロケータをデコンプレッサに提示しなければならない。したがって、CBaseOutputPin::DecideAllocator メンバ関数をオーバーライドしなければならない。


変換基底クラス CTransformFilter および CTransInPlaceFilter の使用

このトピックでは、変換フィルタの作成用に提供されているクラスについて説明する。「変換フィルタの作成」で変換フィルタ作成の具体的な手順を見る前に、このトピックの情報を背景知識として理解する必要がある。

このトピックは、以下のセクションを含んでいる。

  • CTransformFilter および CTransInPlaceFilter クラスの概要
  • 派生クラスの要件
  • 変換フィルタ宣言のサンプル

CTransformFilter および CTransInPlaceFilter クラスの概要

変換フィルタを開発するうえで最も簡単な方法は、変換フィルタ クラスを使用することである。これらのクラスは、ほとんどの種類の変換フィルタで機能する。通常、非コピーの変換フィルタは CTransInPlaceFilter クラスとその関連ピン クラスから派生する。コピー変換フィルタは、CTransformFilter クラスとその関連ピン クラスから派生する。

変換フィルタ クラスは階層的であり、階層ツリーの最下位には変換インプレイス クラスが位置する。次の図に示すように、CTransInPlaceFilter は CTransformFilter から派生し、CTransformFilter は CBaseFilter から派生する。

次の図に示すように、CTransInPlaceInputPin クラスは CTransformInputPin クラスから派生し、CTransformInputPin クラスは CBaseInputPin クラスから派生する。

次の図に示すように、CTransInPlaceOutputPin クラスは CTransformOutputPin クラスから派生し、CTransformOutputPin クラスは CBaseOutputPin クラスから派生する。

コピー変換クラスと変換インプレイス クラスでは、多くの機能が共通している。これは、変換インプレイス クラスのメンバ関数がほとんどすべてコピー変換クラスから派生するためである。基底クラスに対する変換クラスの主な拡張内容は、すべての必要なピン メンバ関数が実装されていることである。したがって、デフォルトの実装では、メインのフィルタ クラスを (CTransInPlaceFilter または CTransformFilterから) 派生するだけでよい。

派生クラスの要件

派生されたフィルタ クラスは、いくつかのメンバ関数を提供する必要がある。これは一般に次のような目的のためである

  • フィルタがメディア タイプを受け入れるかどうかを確認する。
  • 必要なアロケータの数とサイズを指定する (コピー変換のみ)。
  • フィルタの変換機能を提供する。

すべての派生されたフィルタ クラスは、スタティックな CFactoryTemplate::CreateInstance 関数を実装しなければならない。また、CBaseFilter::GetSetupData メンバ関数をオーバーライドしてフィルタを自己登録にすることもできる。それとは別に、クラスは変換基底クラス内のいくつかのメンバ関数をオーバーライドする必要がある。フィルタのインスタンス化の詳細については、「変換フィルタの作成」を参照すること。

派生されたフィルタ クラスが CTransformFilter クラスに基づいている場合、以下のメンバ関数をオーバーライドする必要がある。
Transform | 変換を実装する。
CheckInputType | メディア タイプのサポートを確認する。
CheckTransform | このタイプの変換のサポートを確認する (デバッグ用ビルドのみ)。
DecideBufferSize | コピー時のサイズと数を設定する。
GetMediaType | 出力ピンのメディア タイプを指定する。

派生されたフィルタ クラスが CTransInPlaceFilter クラスに基づいている場合、以下のメンバ関数をオーバーライドする必要がある。
Transform | 変換を実装する。
CheckInputType | メディア タイプのサポートを確認する。

最低限のオーバーライドによって変換フィルタにデフォルトの実装を提供する以外に、他のメンバ関数をオーバーライドして動作をさらに特化することもできる。もちろん、どのメンバ関数をオーバーライドするかは、フィルタに求める機能によって異なる。たとえば、フィルタに複数の入力ピンと出力ピンを持たせたい場合は、GetPin および GetPinCount メンバ関数をオーバーライドする必要がある。

また、BreakConnect や CompleteConnect などいくつかの基底クラス メンバ関数は、ピンを通したフィルタへの通知として呼び出される。一般に、そのようなメンバ関数のほとんどは、ピンにだけ存在する。CTransformFilter に基づくクラスでは、ピン関数はフィルタ クラス内の似た名前の関数を呼び出すように実装されている。これは、オーバーライドの必要性が高いメンバ関数はすべて 1 つのフィルタ クラスに集められていることを意味する。そのため、ピン クラスを変更しないで済み、実装が小さく簡単になる。これらのメンバ関数を以下に示す。
メンバ関数 | オーバーライドする理由
NonDelegatingQueryInterface | 派生クラスに追加されたインターフェイスを配布するため
GetPinCount | 変換フィルタにピンを追加する場合
GetPin | 変換フィルタにピンを追加する場合
CheckConnect | 接続時に追加インターフェイスを取得するため、など
BreakConnect | 接続の切断時に追加インターフェイスを解放するため、など
CompleteConnect | 接続の終了時にいくつかの動作を実行するため (入力ピンの再接続など)
SetMediaType | メディア タイプが設定されたときに通知を受けるため
StartStreaming | ストリーミング状態に入るときに通知を受けるため
StopStreaming | ストリーミング状態を出るときに通知を受けるため
AlterQuality | 品質コントロール メッセージを単に渡す以外に何らかの操作を行うため

変換フィルタ宣言のサンプル

このサンプルは、完全な最小機能フィルタを示している。これは、フィルタに対して必要な最低限の実装を示すほかには、何もしない。このフィルタは変換インプレイス クラスを使用し、そのフィルタ クラスを CTransInPlaceFilter クラスから派生している。派生されたフィルタ クラス CNullNull のクラス宣言を次に示す。

// CNullNull
//
class CNullNull
: public CTransInPlaceFilter
{

public:

    static CUnknown *CreateInstance(LPUNKNOWN punk, HRESULT *phr);

DECLARE_IUNKNOWN;

    LPAMOVIESETUP_FILTER GetSetupData()
    {
        return &sudNullNull;
    }

private:

    // コンストラクタ。単に基底クラス コンストラクタを呼び出す。
    CNullNull(TCHAR *tszName, LPUNKNOWN punk, HRESULT *phr)
        : CTransInPlaceFilter (tszName, punk, CLSID_NullNull, phr)
    { }

    // CTransInPlaceFilter 基底クラスの純粋仮想変換をオーバーライドする。
    // 変換の "実際の仕事" は *pSample を変更することで行われる。
    // Null 変換は *pSample を変更しない。
    HRESULT Transform(IMediaSample *pSample){ return NOERROR; }

    // このフィルタはすべての入力タイプを受け入れる。
    // (通常は、受け入れないタイプに対して S_FALSE を返す)
    HRESULT CheckInputType(const CMediaType* mtIn) { return S_OK; }
};

この例には、基底クラスで必要な、以下の基本的なメンバ関数が示されている。
CreateInstance | クラスを COM オブジェクトとしてインスタンス化するために、すべてのクラスで必要。
GetSetupData | CBaseFilter::GetSetupData をオーバーライドし、この特定のフィルタを登録するために必要な情報をクラスに提供する。ここでは、SDK に含まれる Nullnull.cpp ファイルに定義された構造体のアドレスを提供している。
CNullNull | クラス コンストラクタ。通常は単に基底クラス コンストラクタを呼び出す。
Transform | CTransInPlaceFilter::Transform をオーバーライドし、CNullNull の主たる作業を実行する。ここでは、何もしない。
CheckInputType | CTransInPlaceFilter::CheckInputType をオーバーライドし、接続時のメディア タイプを確認する。この関数は単にメディア タイプを次のフィルタに渡すだけなので、ここではすべてのメディア タイプを受け入れる。

厳密に言えば、GetSetupData はフィルタを自己登録にしたい場合にのみ必要である。しかし、この機能は基底クラスで実装され、実装は簡単に行えるので、これを基底クラスに含めておくことをお勧めする。


変換フィルタの接続

ここでは、変換フィルタを作成する場合の接続に関するいくつかの問題を説明する。任意の 2 つのフィルタを接続するには、どのメディア タイプを使用するかを調整したり、サンプルを渡すための共有のアロケータを決定することが必要になる。変換フィルタは両側で接続され、また一部の変換フィルタはグラフ内の別のフィルタのメディア タイプとアロケータを使用することから、変換フィルタの接続に関する概念を理解することが重要である。

このトピックは、以下のセクションを含んでいる。

  • アロケータ ネゴシエーションの仕組み
  • フィルタ グラフの接続 : 例
  • メディア タイプ接続の確立

アロケータ ネゴシエーションの仕組み

メディア タイプやアロケータ ネゴシエーションを含めた接続プロセスについては、「フィルタの接続」を参照すること。変換フィルタの特性を決めるうえで、変換フィルタのアロケータ ネゴシエーションのモデルを理解しておくと役に立つ。

変換フィルタでコピー処理が必要な場合、変換フィルタは、入力ピンによって確立されたバッファから出力ピンによって確立されたバッファにメディア サンプルをコピーする。これらのバッファは、アロケータによって指定されるが、アロケータは実際にはほかのフィルタに存在する場合がある。中間にあるフィルタがデータをコピーしない場合は、いくつか先のフィルタに存在することもある。

コピー変換フィルタの場合、通常は入力ピンに対してはアップストリーム フィルタのアロケータが、出力ピンに対してはダウンストリーム フィルタのアロケータが使用される。接続プロセスの間、どのアロケータを使用してアップストリーム転送を行うかは、アップストリーム フィルタの出力ピンによって決定される。したがって、コピー変換の入力ピンは、接続されている出力ピンからその IMemInputPin::GetAllocator メソッドが呼び出された場合に、アップストリーム転送のアロケータを作成する準備ができていなければならない。基底クラスを使用することで、任意の接続の入力ピンから新しいアロケータを作成することができる。

一方、変換インプレイス フィルタはコピーを作成せずに、既存のバッファ内のデータを変更する。これらのフィルタは、必ずダウンストリーム フィルタからアップストリーム フィルタにアロケータを提供しなければならない。このためには再接続が必要となる。なぜなら、入力ピンが最初に接続されるときには、フィルタはダウンストリーム フィルタについて何も知らないからである。また、インプレイス変換はメディア タイプを変更しないので、ダウンストリーム フィルタからのメディア タイプを再接続時にアップストリーム フィルタに提供する必要がある。

フィルタ グラフの接続 : 例

変換インプレイス フィルタの割り当てモデルをわかりやすくするために、以下に単純で一般的なフィルタ グラフの例を示す。

この単純な例は、ダウンストリーム アロケータをアップストリーム フィルタに提供する変換インプレイス フィルタのモデルを示している。InPlace E が VidRen F に接続された場合を考えてみよう。

接続時、ビデオ レンダラ フィルタ (VidRen F) はアップストリーム インプレイス フィルタ (InPlace E) から利用できるようにアロケータを提供する。これは変換インプレイス フィルタなので、InPlace E はアロケータをその前のアップストリーム フィルタ InPlace D に提供する。この再接続と再ネゴシエーションは、ソース フィルタまたはコピー変換フィルタに到達するまで繰り返される。この場合はデコンプレッサ CopyDec C に到達する。(コピー変換フィルタはコピー処理を実行しなければならないので、アロケータをアップストリームに提供できない。) デコンプレッサは、ビデオ レンダラのバッファに書き込みを直接行う (バッファは DirectDraw® サーフェスである場合もある)。これが、変換フィルタを変換インプレイス フィルタとして記述し、可能であればレンダラからのアロケータをアップストリームに渡すことが重要であることの理由である。

次に、フィルタ InPlace B と CopyDec C を考えてみよう。変換インプレイス フィルタからのダウンストリーム フィルタがレンダラではなくコピー変換フィルタであるとしたらどうなるだろう? この場合、コピー変換フィルタは、独自のアロケータを入力ピンに作成し (基底クラスがこの処理を行う)、変換インプレイス フィルタは再接続時にそのアロケータをアップストリームに提供する (レンダリング フィルタに接続されている場合と同じ)。

ただし、CopyDec C が (IMemInputPin::GetAllocator メソッドを使用して) 独自のアロケータを作成することができる一方で、ソース フィルタ Source A は独自のバッファ (たとえばファイル) を使用する。したがって、InPlace B が CopyDec C に接続するとき、InPlace B は既にソース フィルタのアロケータを受け入れていることになり、自身とデコンプレッサ フィルタの間で転送を行う場合に強制的にそのアロケータを使用する。InPlace B はアップストリーム フィルタの Source A に対して CopyDec C から提供されたアロケータを使用するオプションを提示するが、ソース フィルタは、ファイル バッファからデコンプレッサの入力バッファへの余分なコピーを実行しなくて済むように、このアロケータを拒否する。

したがって、すべてのアップストリーム フィルタはそのアロケータをダウンストリームで使用するように強制することができるが、そうする理由を持たなければならない (たとえばすでにバッファがあるなど)。この例では、ファイル バッファとビデオ メモリの間で (デコンプレッサ フィルタによって) コピーが 1 つだけ作成される。

メディア タイプ接続の確立

異なるフィルタのピンを接続する場合、ピン間で交換されるサンプルの共通のメディア タイプを決めなければならない。ここでは、変換フィルタがどのようにメディア タイプのネゴシエーションを扱うかを理解するために、接続メカニズムを簡単に説明する。

このトピックは、以下のセクションを含んでいる。

  • 接続プロセス : 要約
  • 再接続のタイミング

接続プロセス : 要約

フィルタ グラフ マネージャがあるフィルタの出力ピンを呼び出して 2 番目のフィルタの入力ピンに接続する場合、IPin::Connect メソッドが呼び出される。次にこのメソッドは、CBaseOutputPin::CheckConnect を呼び出して接続するピンからインターフェイスを取得し、CBasePin::AgreeMediaType を使って共通のメディア タイプを調べる。

AgreeMediaType は、メディア タイプ列挙子を使用して各ピンに希望のメディア タイプを照会する CBasePin::TryMediaTypes を呼び出す。IEnumMediaTypes は、TryMediaTypes が最初に使用する、接続先の入力ピン上のインターフェイスである。基底クラスは IEnumMediaTypes を使用して、リスト内のそれぞれのメディア タイプについて CBasePin メンバ関数 GetMediaType を繰り返し呼び出す。このメンバ関数を入力および出力ピン クラスで使用して、ピンで希望されるメディア タイプを返す。

TryMediaTypes は、返された入力タイプそれぞれについて出力ピンの CheckMediaType メンバ関数を呼び出す。CheckMediaType を使用して、このタイプが許容されるかどうかを確認しなければならない。メディア タイプが見つからない (たとえば、GetMediaType が接続先の入力ピンで使用されていない、または許容できないメディア タイプを返した) 場合、AgreeMediaType は出力ピンのメディア タイプ列挙子を取得して、順番にメディア タイプを調べる。ここで、派生した出力ピンの GetMediaType メンバ関数がそれぞれのタイプについて再び呼び出される。この場合、フィルタの入力ピンによって確立された既存の接続に関して照会を行うことによってメディア タイプを判定することができる。

再接続のタイミング

入力ピンから出力ピンの間でメディア タイプを変更しない変換フィルタ (ほとんどのインプレイス変換および多くのコピー変換) の場合、ダウンストリーム フィルタのメディア タイプをアップストリーム フィルタに提供するために再接続スキームが用意されていなければならない。これを理解するために、次の図の変換インプレイス Filter B のメディア タイプ ネゴシエーションを検討する。

Filter B の入力ピンが最初に接続され、アップストリームの出力ピン (AOutPin) とメディア タイプを確立する。次に Filter B の出力ピンを接続する場合、出力ピンには専用の列挙子がないので、接続されているアップストリーム フィルタの出力ピン (AOutPin) からの列挙子を使用しなければならない。

ダウンストリーム フィルタ CInPin のピンがこのメディア タイプを受け付けた場合、接続は完了する。今度は、Filter C がこのメディア タイプを受け付けずに、Filter B が扱えるメディア タイプを処理するケースを考えてみる。

メディア タイプを扱えるかどうかを判定する前に、Filter B は AOutPin の IPin::QueryAccept メソッドを呼び出して、そのメディア タイプが許容されることを確認する。すべてのフィルタで許容されるメディア タイプを検出できない場合、BOutPin から CInPin への接続は失敗する。(変換インプレイス フィルタがそのアップストリームまたはダウンストリームに接続することはできるが、両方に同時には接続できない。)

適切なタイプが見つかった場合、BOutPin はフィルタ全体に再接続を強制して、AOutPin と BInPin が再び接続されたときに、確立されたメディア タイプ (CInPin のメディア タイプ) を AOutPin に渡す。


C/C++ による変換フィルタの開発

変換フィルタは、メディア入力を受け取り、それに何らかの変更を加える。変換フィルタを設計する場合、フィルタ クラスはいずれかの変換基底クラス (CTransformFilter、CTransInPlaceFilter、または CVideoTransformFilter) から派生するか、より一般的な CBaseFilter クラスから派生する。どの基底クラスを選択するかは、フィルタがメディア サンプルをコピーする必要があるか、あるいはそのまま変換できるかによって決まる。詳細については、「使用する基底クラスを決める」を参照すること。

フィルタ グラフ マネージャは、フィルタの派生元の基底クラスの関数を使用して、フィルタ グラフにフィルタを挿入し、フィルタ間の接続を自動的に作成する。フィルタ マッパーは、フィルタのレジストリ情報を使用してフィルタ グラフを設定する。

最も単純な変換フィルタ (たとえば、入力ピンと出力ピンが 1 つずつしかないフィルタ) の場合、フィルタ クラスを CTransformFilter から派生して、Transform 関数と CheckInputType 関数だけをオーバーライドすればよい。カスタム機能が必要であれば、他の関数をオーバーライドして独自の接続、ピン、および他のフィルタ機能を作成できる。詳細については、「基底クラス メンバ関数をオーバーライドする」を参照すること。また、フィルタ クラスを CBaseFilter から派生して、そのメソッドをオーバーライドすることもできる。

このセクションでは、以下の方法について説明する。

  • フィルタ クラスの定義とインスタンス化
  • CheckInputType のオーバーライド (CBaseFilter から派生したフィルタ クラスには適用されない)
  • Transform 関数のオーバーライド (CBaseFilter から派生したフィルタ クラスには適用されない)
  • 追加インターフェイスへのアクセス
  • レジストリ情報の作成

すべての変換フィルタは、追加インターフェイスへのアクセスを除き、上記のステップをすべて実行するコードを実装しなければならない。

変換フィルタの背景情報については、以下のトピックを参照すること。

  • 使用する基底クラスを決める
  • 基底クラス メンバ関数をオーバーライドする

フィルタの登録と自己登録化については、「DirectShow オブジェクトの登録方法」を参照すること。

フィルタ クラスの定義とインスタンス化

フィルタ クラスを定義してインスタンス化するための手順を以下に示す。

  1. フィルタ クラス (および必要に応じてピン クラス) を派生する基底クラスを決定する。通常、変換フィルタ クラスは変換基底クラスである CTransformFilter、CTransInPlaceFilter、または CVideoTransformFilter から派生するか、または、より一般的な CBaseFilter クラスから派生する。ビデオ メディア (特に AVI データ) を変換したい場合は、CVideoTransformFilter から派生する。フィルタが入力メディア サンプルをコピーする必要がある場合は、CTransformFilter から派生する。フィルタがメディア サンプルをそのまま変換できる場合は、CTransInPlaceFilter から派生する。変換基底クラスで提供される単純な変換フィルタ サポートの代わりに、独自のメンバ関数を実装したい場合は、CBaseFilter から派生する。詳細については、「使用する基底クラスを決める」を参照すること。

    次の例では、フィルタ クラスを CTransInPlaceFilter から派生している。

        class CMyFilter  :public CTransInPlaceFilter
  2. オブジェクトに対して IUnknown インターフェイスを実装する。

    フィルタ クラス定義のパブリック セクションで CUnknown のインスタンスを作成してから、DECLARE_IUNKNOWN マクロを呼び出す。

    public:
        static CUnknown *WINAPI CreateInstance(LPUNKNOWN punk, HRESULT
    *phr);
DECLARE_IUNKNOWN;
  3. コンストラクタを定義する。また、Transform 関数と CheckInputType 関数を定義する (フィルタ クラスが CBaseFilter から派生している場合、これらの関数は定義しない)。

    フィルタ クラス定義のプライベート セクションで、コンストラクタを定義する。これは、派生元の変換フィルタ クラスのコンストラクタを呼び出すことで行う。次に、変換を実行して入力タイプをチェックするコードを追加する。次に例を示す。

        // CTransInPlaceFilter のコンストラクタを呼び出すことにより、
    // コンストラクタを定義する。
    CMyFilter(TCHAR *tszName, LPUNKNOWN punk, HRESULT *phr)
    : CTransInPlaceFilter (tszName, punk, CLSID_MyFilter, phr)
    { }

    // 変換コードを追加する。
    HRESULT Transform(IMediaSample *pSample){
    // ここに変換コードが入る。
    }

    // 入力タイプをチェックするコードを追加する。
    HRESULT CheckInputType(const CMediaType* mtIn) {
    // ここに入力チェック コードが入る。
    }
  4. フィルタ オブジェクトに対して CreateInstance を実装する。通常、CreateInstance はフィルタ クラスのコンストラクタを呼び出す。次に例を示す。
        CUnknown * WINAPI CMyFilter::CreateInstance(LPUNKNOWN punk, HRESULT *phr) {
    CMyFilter *pNewObject = new CMyFilter(NAME("Description of My Filter"),
        punk, phr );
if (pNewObject == NULL) {
*phr = E_OUTOFMEMORY;
    }
return pNewObject;
    }
  5. CFactoryTemplate オブジェクトのグローバル配列 g_Templates を宣言する。これは、CreateInstance 関数へのアクセス方法をデフォルトのクラス ファクトリ コードに通知するために使用される。
        CFactoryTemplate g_Templates[]=
        {   { L"My Filter"
            , &CLSID_MyFilter
            , CMyFilter::CreateInstance  // クラス ファクトリによって呼び出される関数
            , NULL
            , &sudMyFilter }     // AMOVIESETUP_FILTER 構造体のアドレス。
                                 //   構造体が存在しない場合は NULL。
    };
int g_cTemplates = sizeof(g_Templates) / sizeof(g_Templates[0]);

    g_cTemplates 変数は、フィルタに対するクラス ファクトリ テンプレート (CFactoryTemplate) の数を定義する。各テンプレートは COM とフィルタの間のリンクを提供し、フィルタのベース オブジェクトを作成するために使用される。フィルタには最低でも 1 つのテンプレートがある。これは、フィルタ独自の CreateInstance 関数のアドレスを提供する。この関数は、呼び出されるとベース オブジェクトを作成する。

    CFactoryTemplate テンプレートにパラメータを追加することで、プロパティ ページを追加できる。登録時の CFactoryTemplate の使用法については、「DirectShow オブジェクトの登録方法」を参照すること。

  6. フィルタ オブジェクトの GUID を生成する。

    GUID の生成に関する一般的な情報については、Platform SDK の "GUID の作成と最適化" および "uuidgen ユーティリティ" を参照すること。

    Microsoft® Visual C++® 5.x で GUID を生成するには、[ツール] メニューから [Create GUID] を選択する。GUID のデフォルトのフォーマットは DEFINE_GUID であり、これをそのまま使用する。[コピー] ボタンをクリックする。ソース ファイルでインクルード文の下にカーソルを置き、[編集] メニューの [貼り付け] を選択する。次の例に示すようなコードが挿入される。ただし、番号と CLSID は固有のものが入る。ヘッダー ファイルまたはメイン ファイルのクラス定義の前にコードを挿入する。

        // {3FA5D260-AF2F-11d0-AE9C-00A0C91F0841}
    DEFINE_GUID(CLSID_MyFilter,
    0x3fa5d260, 0xaf2f, 0x11d0, 0xae, 0x9c, 0x0, 0xa0, 0xc9, 0x1f, 0x8, 0x41);

CheckInputType のオーバーライド

フィルタに対して指定された入力が正しいかどうか確認するために、CheckInputType 関数をオーバーライドする (これは CBaseFilter から派生したフィルタ クラスには適用されない)。実装では、サポートできないメディア タイプに対してエラーを返す必要がある。フィルタがサポートするメディア タイプは、AMOVIESETUP_MEDIATYPE 構造体にリストされる。次に例を示す。

    HRESULT CMyFilter::CheckInputType(const CMediaType *pmt)
    {
       if (pmt->majortype != MEDIATYPE_Video) {
           return S_FALSE;
       }
           else return S_OK;
       }

Transform 関数のオーバーライド

入力メディアに対して必要な変換を実行するために、変換基底クラスの Transform 関数をオーバーライドするか、または独自の変換関数を実装する必要がある (これは CBaseFilter から派生したフィルタ クラスには適用されない)。

たとえば、コントラスト サンプルの以下のコードについて考える。CContrast::Transform 関数を次のようにオーバーライドする。

    HRESULT CContrast::Transform(IMediaSample *pIn, IMediaSample *pOut)
    {
            HRESULT hr = Copy(pIn, pOut);
        if (FAILED(hr)) {
        return hr;
        }
            return Transform(pOut);

    }

最初の CContrast::Transform 関数はメディア データをコピーして、(pOut パラメータが指す) そのコピーを次の Transform 関数に渡す。コントラスト サンプルの最初の Transform 関数はオーバーロードされた関数であり、2 番目の形の Transform 関数は入力メディアのコピーに対してインプレイス変換を行う。これを次のコードに示す。

    HRESULT CContrast::Transform(IMediaSample *pMediaSample)
    {
        signed char ContrastLevel;
        ContrastLevel = m_ContrastLevel;
        AM_MEDIA_TYPE *pAdjustedType = NULL;

        pMediaSample->GetMediaType(&pAdjustedType);
        HRESULT hr = Transform(&AdjustedType, ContrastLevel);
        pMediaSample->SetMediaType(&AdjustedType);
return NOERROR;
    }

2 番目の形のオーバーロードされた Transform 関数は、さらに 3 番目の形のオーバーロードされた Transform 関数を呼び出すことに注意。

追加インターフェイスへのアクセス

フィルタが基底クラスに実装されていないインターフェイスを実装する場合は、NonDelegatingQueryInterface 関数をオーバーライドして、実装されたインターフェイスへのポインタを返す必要がある。

  1. フィルタ クラス定義のパブリック セクションで、NonDelegatingQueryInterface を宣言する。
    STDMETHODIMP NonDelegatingQueryInterface(REFIID riid, void **ppv)
  2. クラスの実装セクションで、NonDelegatingQueryInterface 関数を実装する。次に例を示す。
        // 永続ストリームとプロパティ ページを公開する。
    STDMETHODIMP CMyFilter::NonDelegatingQueryInterface(REFIID riid, void **ppv)
    {
        if (riid == IID_IPersistStream) {
          AddRef( );   // 参照カウントを追加する。終了後に解放すること。
          *ppv = (void *)(IPersistStream *)this;
          return NOERROR;
       }
       } else if (riid == IID_ISpecifyPropertyPages) {
return GetInterface((ISpecifyPropertyPages *) this, ppv);
       }
       else {
return CTransInPlaceFilter::NonDelegatingQueryInterface(riid, ppv);
       }
    }

レジストリ情報の作成

フィルタ グラフ マネージャは、フィルタのレジストリ エントリを使用して、フィルタとその接続を設定する。フィルタのレジストリ情報は、AMOVIESETUP_MEDIATYPE、AMOVIESETUP_PIN、および AMOVIESETUP_FILTER 構造体に提供する。通常、これらの構造体はフィルタ実装コードの先頭に位置する。これらの構造体の使用法の詳細については、「DirectShow オブジェクトの登録方法」を参照すること。

フィルタの登録に必要な 3 つの構造体を提供するための手順を以下に示す。

  1. AMOVIESETUP_MEDIATYPE 構造体を提供する。この構造体は、フィルタがサポートするメディア タイプに関するレジストリ情報を保持する。次に例を示す。
        const AMOVIESETUP_MEDIATYPE sudPinTypes =
                    { &MEDIATYPE_Video             // メジャー タイプ
                    , &MEDIASUBTYPE_NULL}  ;       // マイナー タイプ

    メジャー タイプは、MEDIATYPE_Stream、MEDIATYPE_Video、MEDIATYPE_Audio のいずれかである。

  2. Provide the AMOVIESETUP_PIN 構造体を提供する。この構造体は、フィルタがサポートするピンに関するレジストリ情報を保持する。
  3. AMOVIESETUP_FILTER 構造体を提供する。この構造体は、フィルタ オブジェクトに関するレジストリ情報 (CLSID、説明、ピン数、ピン構造体の名前、フィルタのメリット) を保持する。メリット は、フィルタ グラフ マネージャがフィルタにアクセスする順序を制御する。メリットの値は MERIT_PREFERRED、MERIT_NORMAL、MERIT_UNLIKELY、MERIT_DO_NOT_USE のいずれかである。メリット値の詳細については、「IFilterMapper::RegisterFilter」を参照すること。次のコードは、AMOVIESETUP_FILTER 構造体の例を示す。
        const AMOVIESETUP_FILTER
    sudMyFilter = { &CLSID_MyFilter         // clsID
                , L"My Filter Description"  // strName
                , MERIT_UNLIKELY            // dwMerit
                , 2                         // nPins
                , sudpPins };               // lpPin


圧縮フィルタについて

圧縮フィルタは、特殊なタイプの変換フィルタである。圧縮フィルタ (コンプレッサ) は、データを受け取り、圧縮スキームを使ってそのデータを変換し、圧縮データをダウンストリームに渡す。

Microsoft® DirectShow® には、Microsoft Video for Windows® のビデオまたはオーディオ CODEC を使用してデータを圧縮する AVI コンプレッサ フィルタと ACM ラッパー フィルタが含まれている。DirectShow によって提供されるデフォルト フィルタではサポートされないフォーマットでデータを圧縮する必要がある場合は、自分でコンプレッサ フィルタを書くことができる。

圧縮フィルタを書く場合は、1 つの入力ピンと 1 つの出力ピンを持つ変換フィルタを書く。変換フィルタの書き方については、次のトピックを参照すること。

  • 変換フィルタの作成
  • 変換基底クラス CTransformFilter および CTransInPlaceFilterの使い方
  • 変換フィルタの接続

変換フィルタを書き終えた後は、圧縮フィルタを作成する際に以下のポイントを確認する必要がある。

  • フィルタを登録する。

    AMovieDllRegisterServer2 関数を使って圧縮フィルタを登録する。これにより、アプリケーションがシステム上のほかの圧縮フィルタとともに作成したフィルタを列挙することが可能になる。

  • 推奨コンプレッサ インターフェイスを実装する。

    すべての圧縮フィルタの出力ピンに IAMStreamConfig インターフェイスを実装し、ビデオ コンプレッサの出力ピンに IAMVideoCompression を実装して、アプリケーションがフィルタの圧縮機能にアクセスできるようにすることが強く推奨される。

    IAMStreamConfig を使用すると、データの圧縮フォーマットについての情報をアプリケーションに通知して、特定のデータ型に圧縮するためにアプリケーションがコンプレッサを構成できるようになる。

    IAMVideoCompression を使用すると、アプリケーションは、AM_MEDIA_TYPE 構造体には現れないビデオ固有の設定、たとえばキー フレームの頻度などを設定することができる。


エフェクト フィルタについて

Microsoft® DirectShow® では、エフェクト フィルタは、エフェクトをメディア データに適用するがメディア タイプを変更しないフィルタとして定義される。

入力と出力のメディア フォーマットが同じで、適用されたエフェクトはフォーマットを変更できないので、エフェクト フィルタがメディア フォーマッティングをチェックするコードを含むこともある。フィルタが変換フィルタの基底クラス (CTransformFilter または CTransInPlaceFilter) のどちらかから派生した場合、そのフィルタは通常、CheckMediaType、CTransformFilter::CheckInputType、および CheckTransform メソッドを使用してフォーマットをチェックする。フィルタが変換フィルタのいずれかの基底クラスから派生したものでない場合、通常は、CBasePin::CheckMediaType メンバ関数を呼び出すことによってピンがフォーマットをチェックする。

エフェクト フィルタ クラスには、必要な最大の機能を提供する基底クラスを選択する必要がある。変換フィルタ基底クラスのいずれかを基底クラスとすることはよくある。必要な機能を上位レベルの基底クラスがいずれもサポートしていない場合は、CBaseFilter または CBasePin を基底クラスとして選択することができる。

エフェクトの状態を GraphEdit に保存したい場合、エフェクト フィルタは IPersistStream インターフェイスを実装しなければならない。このインターフェイスにアクセスするには、CPersistStream からエフェクト フィルタ クラスを派生し、IPersistStream インターフェイスを照会する。設計時にフィルタの状態を保存しても役に立たないが、GraphEdit が閉じたときにエフェクト フィルタがデフォルトの状態に戻るようにしておくと便利である。この場合は、IPersistStream を実装する必要はない。

ユーザーがエフェクトを操作できるようにするには、エフェクト フィルタのプロパティ ページを作成および表示し、さらにユーザーの入力をフィルタに返すためのメカニズムを提供する必要がある。このためには。プロパティ ページ クラス、(プロパティ ページを公開する) ISpecifyPropertyPages インターフェイス、およびプロパティ ページ値を変更するカスタム インターフェイスを実装しなければならない。通常、プロパティ ページは、スライダ、ボタン、チェック ボックスなどのコントロールを使ってユーザー入力を受け取る。また、プロパティ ページにコントロールを表示するリソース ファイルも提供しなければならない。

プロパティ ページ クラスを実装するには、CBasePropertyPage から派生するクラスを作成し、OnReceiveMessage メソッド、CPersistStream::SetDirty メソッド、およびそれぞれのエフェクト パラメータのデータ メンバを実装する。この 2 つのインターフェイスにアクセスするには、エフェクト フィルタ クラスを ISpecifyPropertyPages とカスタム インターフェイスから派生させてインターフェイスを照会する。以下のコード例に示すように、NonDelegatingQueryInterface メソッドをオーバーライドすることによってすべてのインターフェイスを照会することができる (IGargle はカスタム インターフェイス)。

STDMETHODIMP CGargle::NonDelegatingQueryInterface(REFIID riid, void **ppv)
{
    CheckPointer(ppv,E_POINTER);
if (riid == IID_IGargle) {
return GetInterface((IGargle *) this, ppv);
} else if (riid == IID_ISpecifyPropertyPages) {
return GetInterface((ISpecifyPropertyPages *) this, ppv);
} else if (riid == IID_IPersistStream) {
        return GetInterface((IPersistStream *) this, ppv);
} else {
return CTransInPlaceFilter::NonDelegatingQueryInterface(riid, ppv);
    }
}

通常、エフェクト フィルタのカスタム インターフェイスは、それぞれのエフェクト パラメータの put メソッドと get メソッドを提供する。たとえば IGargle カスタム インターフェイスは、put_GargleRate および get_GargleRate メソッドを提供する。Contrast サンプルの IContrast カスタム インターフェイスは、put_ContrastLevel および get_ContrastLevel メソッドを提供する。ユーザーがプロパティ ページのいずれかのコントロールにアクセスすると、ページはウィンドウ メッセージを生成する。プロパティ ページ クラスの OnReceiveMessage メンバ関数がこのメッセージを処理する。Contrast サンプルの以下のコードに、このメッセージ生成および処理を示す。IDB_DEFAULT は、[Default] ボタンのリソース ID である。ユーザーがこのボタンをクリックすると、ビデオのコントラストがデフォルト状態に設定される。CContrastProperties クラスはプロパティ ページを設定し、IContrast::put_DefaultContrastLevel メソッドはコントラスト レベルをデフォルト値に設定する。

BOOL CContrastProperties::OnReceiveMessage(HWND hwnd, UINT uMsg,
    WPARAM wParam, LPARAM lParam)
{
    switch (uMsg)
    {
       case WM_COMMAND:
        {
          if (LOWORD(wParam) == IDB_DEFAULT)
            {
            pIContrast()->put_DefaultContrastLevel();
            SendMessage(m_hwndSlider, TBM_SETPOS, TRUE, 0L);
              SetDirty();
        }
            return (LRESULT) 1;
        }
...

エフェクト フィルタは、クリティカル セクションを内部的に使用してグローバル フィルタの状態を保護する。エフェクト フィルタはクリティカル セクションをロックすることによって、フィルタ グラフを通過するデータ フローが直列化され、エフェクトが発生しているときにグローバル フィルタの状態が変化しないことを保証することができる。DirectShow は、CAutoLock クラス オブジェクトを宣言することによってクリティカル セクションをロックする。通常、エフェクト フィルタはエフェクトを適用する関数を入力すると即座にクリティカル セクションをロックする。たとえば以下のコードでエフェクトを適用する関数は MessItAbout である。

// エフェクト フィルタ クラス定義において
// クリティカル セクションのデータ メンバ を宣言する。
CCritSec   m_GargleLock;

void CGargle::MessItAbout(PBYTE pb, int cb)
{
    CAutoLock foo(&m_GargleLock);

通常、エフェクト プロパティの put および get メソッド (たとえば put_GargleRate) はクリティカル セクションをロックするので、エフェクト値は更新の途中で変化しない。


ビデオ レンダラ

このセクションでは、ビデオ レンダラの作成方法と使用方法について説明する。フルスクリーン レンダラとカスタム レンダラの両方について説明する。フルスクリーン レンダラをサポートする方法と理由、およびカスタム レンダラで通知、状態変更、動的フォーマット変更を処理する方法について説明する。

  • フルスクリーン ビデオ レンダラ
  • 代替ビデオ レンダラ
  • ビデオ レンダラにおける転送元矩形と転送先矩形


フルスクリーン ビデオ レンダラ

このトピックでは、アプリケーションからビデオをフルスクリーン モードでレンダリングするように指示されたときにデフォルトの IVideoWindow PID で使用されるロジックについて説明する。代替レンダラ フィルタは、IVideoWindow PID を使用してアプリケーションとやり取りできる。代替レンダラの開発者は、フルスクリーン モードでのレンダリングが要求されたときに、フルスクリーン ビデオを表現するための最良の手段をこの PID がフィルタ グラフからどのように検索するかを、知っておく必要がある。

このトピックは、以下のセクションを含んでいる。

  • IVideoWindow PID を使用したフルスクリーン サポートの実装
  • フルスクリーン モードをサポートするフィルタの検索
  • コストなしでフルスクリーンに伸長できるフィルタの検索
  • フルスクリーン レンダリング フィルタの提供
  • レンダラ出力のフルスクリーンへの伸長
  • アプリケーションに対するフルスクリーン サポートの意味

IVideoWindow PID を使用したフルスクリーン サポートの実装

Microsoft® DirectShow® は、利用可能なハードウェア リソースの種類に応じて、いくつかの方法でフルスクリーン サポートを実装する。アプリケーションは、フィルタ グラフ マネージャによって提供される IVideoWindow インターフェイスを通じてフルスクリーン ビデオ再生をサポートできる。アプリケーションは、フルスクリーン再生に対して独自の実装を持つこともできるが、多くの場合 IVideoWindow 実装を使用したほうがリソースの使用効率が良い。

アプリケーションがフルスクリーン モードを要求すると、IVideoWindow PID はフルスクリーン サポートを実装するために、3 つの異なるオプションを試す。通常このオプションは、フィルタ グラフが最初にフルスクリーン モードに入るときに選択される。フルスクリーン モードの間は、IVideoWindow メソッドが呼び出されることはない (フルスクリーン プロパティへのアクセスを除いて)。呼び出そうとすると、VFW_E_IN_FULLSCREEN_MODE メッセージが返される。PID は、IVideoWindow をサポートして以下のいずれかの特性を持つフィルタを、次の順序で検索する。

  1. フルスクリーン モードを直接提供するフィルタ
  2. そのウィンドウをペナルティなしでフルスクリーンに伸長できるフィルタ
  3. フルスクリーン レンダラで置換可能なフィルタ

この 3 つのオプションのいずれも見つからない場合は、デフォルトとして、IVideoWindow をサポートするフィルタのビデオを単純にフルスクリーンに伸長する。パフォーマンス ペナルティは考慮されない。

フルスクリーン モードをサポートするフィルタの検索

最初のオプションは、フルスクリーン モードを直接サポートするフィルタをフィルタ グラフから検索することである。フルスクリーン モードへの移行を指示されると、IVideoWindow PID はまずフィルタ グラフ内で IVideoWindow をサポートするフィルタをすべてスキャンする。PID は各フィルタ上で IVideoWindow::get_FullScreenMode を呼び出す。フィルタが E_NOTIMP (デフォルト) を返した場合、PID はそのフィルタにはフルスクリーン再生の固有サポートがないと仮定する。フィルタがそれ以外の値を返した場合は、フルスクリーン再生の候補フィルタとなる。すなわち、フルスクリーン モードをオンまたはオフにするためのフィルタ グラフ マネージャへの呼び出しは、その候補フィルタに直接送られる。このメカニズムにより、フィルタがフルスクリーン モードを直接サポートするように拡張できる。通常の Windows ベースのレンダラのほとんどは、この機能をサポートする必要がない。

コストなしでフルスクリーンに伸長できるフィルタの検索

フルスクリーン レンダリング フィルタが見つからない場合、PID は IVideoWindow インターフェイスをサポートするフィルタのうち、そのウィンドウがペナルティなしでフルスクリーンに伸長できるものを検索する。そのために PID は、フィルタ グラフ内で IVideoWindow をサポートするフィルタのリストをスキャンする。見つかった各フィルタに対して、PID は IVideoWindow::GetMaxIdealImageSize を呼び出す。フィルタがそのウィンドウがコストなしでフルスクリーンに伸長できることを示していれば、そのフィルタが候補フィルタになる。

その候補フィルタに対してフルスクリーンでのレンダリングが要求されると、PID はフィルタの IVideoWindow プロパティのいくつかをリセットして、ウィンドウをフルスクリーンに伸長する。これは通常、所有者を NULL に設定し、ウィンドウのスタイルを境界またはキャプションを表示しないように変更し、ウィンドウの位置を現在の表示サイズに一致するように更新することを意味する。フルスクリーン モードがオフになると、フィルタのプロパティはフルスクリーン モードに入る前の状態に戻る。

IVideoWindow をサポートするビデオ レンダラのほとんどは、アクティブ (ポーズまたは実行中) になったときに初めてリソースを割り当てるので、それまでの間は理想的な最大イメージ サイズを返すことができない。そのため、フィルタ グラフが停止状態のときにフィルタのリストをスキャンする場合、PID は IVideoWindow::GetMaxIdealImageSize を呼び出す前に各フィルタをポーズする。このメソッドを呼び出した後、フィルタはもう一度停止される。

フルスクリーン レンダリング フィルタの提供

ここまでのオプションがいずれも失敗した場合、PID はフィルタ グラフ内で IVideoWindow インターフェイスをサポートする最初のフィルタを検索し、それが現在のビデオ レンダリング フィルタであると仮定する。

IVideoWindow をサポートするフィルタがない場合、フルスクリーン モードに変更するための呼び出しは VFW_E_NO_FULLSCREEN を返す。フルスクリーン モードへの変更を要求されると、PID は現在のレンダラに対してフルスクリーン モードを効率的にサポートできるかどうかを問い合わせる。効率的にサポートできる場合、グラフに変更は加えられない。それができない場合には、PID はフィルタ グラフが停止されていなければそれを停止し、現在のレンダラを切り離し、その代わりに DirectShow フルスクリーン レンダラを再接続して、終了後に元のフィルタ グラフを復元する。フルスクリーン モードから出るときには、これと逆の手順を踏む。すなわち、フルスクリーン レンダラが切り離され、元のフィルタが再接続される。フィルタ グラフの状態は同様に復元される。フルスクリーン レンダラは、Microsoft® DirectDraw® によって提供される表示変更機能を使用した特別なレンダラである。たとえば、1024 × 768 からフルスクリーン表示を 320 × 240 に切り替えたりできる。低い解像度のモードに変更することにより、イメージを伸長することなく低コストでフルスクリーン レンダリングを実装できる。

フルスクリーン レンダラは現在、320 × 200 × 8/16 ビット/ピクセル、320 × 240 × 8/16、640 × 400 × 8/16、640 × 400 × 8/16、640 × 480 × 8/16、800 × 600 × 8/16、1024 × 768 × 8/16、1152 × 864 × 8/16、1280 × 1024 × 8/16 の各表示モードを実装している。モード X レンダラは IFullScreenVideo インターフェイスをサポートする。モード X レンダラを接続すると、このレンダラは DirectDraw によって利用可能になった表示モードをロードする。利用可能なモードの数は、IFullScreenVideo::CountModes によって取得できる。各モードに関する情報は、IFullScreenVideo::GetModeInfo および IFullScreenVideo::IsModeAvailable を呼び出すことで得られる。アプリケーションは、OATRUE または OAFALSE で SetEnabled フラグを呼び出すことにより、各モードを有効または無効にできる。現在の値は、IFullScreenVideo::IsModeEnabled で照会できる。

モードを有効にするもう 1 つの方法は、クリップ消失係数を使用することである。これは、使用する表示モードを決定する際に失われる可能性のあるビデオの量を定義する。デコーダがビデオを圧縮できないと仮定した場合、たとえば 352 × 288 ピクセルの MPEG ファイルを 320 × 200 表示で再生すると、イメージの 40 パーセント以上が失われる。クリップ消失係数は、許容されるクリップ消失の上限を指定する。標準的な MPEG ビデオを 320 × 200 で再生できるように、デフォルトは 50 パーセントになっている。クリップ消失係数は IFullScreenVideo::SetClipFactor で設定できる。

レンダラ出力のフルスクリーンへの伸長

最初の 3 つのオプションを試みた後は、フルスクリーン サポートを実装するための最後のオプションとして、IVideoWindow によって有効にされた任意のフィルタを使用し、そのウィンドウをフルスクリーンに伸長する。これは、結果のパフォーマンスの良し悪しに関係なく行われる。基本的に、フィルタ グラフ内で IVideoWindow インターフェイスによって有効にされた最初のフィルタが、候補フィルタとなる。このフィルタは、パフォーマンスを犠牲にせずにフルスクリーン伸長できるフィルタと、まったく同じように使用される (すなわち、所有者がリセットされ、スタイルが変更され、ウィンドウ位置は表示範囲に合わせて変更される)。

暗黙のパフォーマンス ペナルティがある場合にウィンドウをフルスクリーンに伸長するコストは、現在の表示解像度によって異なる。最悪のケースは、ユーザーが比較的高い解像度 (たとえば、1024 × 768) を使用し、レンダラが GUI を使ってイメージを伸長しなければならない場合である。この場合、フレーム スループットが非常に低くなるため、最後の手段としてのみ使用する。

アプリケーションに対するフルスクリーン サポートの意味

アプリケーションに公開されるインターフェイスは比較的単純であるが、その基盤となる実装は複雑になる場合がある。フルスクリーン レンダラには、アプリケーション開発者が注意しなければならない特別な属性がある。特に、レンダラが表示モードを変更するのはアクティブな間 (ポーズ中または実行中) だけであることに注意する。したがって、フルスクリーン モードへの切り替え時にフィルタ グラフが停止していた場合には、フィルタ グラフが再び開始されるまで目に見える変更は行われない。フィルタ グラフが実行されると、表示モードが変更され、フルスクリーン レンダリングが開始される。

ウィンドウがフルスクリーンに伸長される場合 (すなわち、フルスクリーン レンダラを使用しない場合) は、状態に関係なく、フルスクリーン モードが設定された時点で変更が表示される。フルスクリーン再生がフィルタ グラフ内のフィルタによって直接サポートされる場合は、フルスクリーン レンダラの動作に準じて、アクティブな間にしかフルスクリーンに切り替えないこともある。フルスクリーン再生をサポートするフィルタがそのように動作するのは、フルスクリーン再生に必要なリソースがその時点まで利用できない場合があるためである。したがって、アプリケーションは停止中にフルスクリーン モードを設定することは避けたほうがよい。

これはユーザー インターフェイスのコンテキストにも同様に当てはまる。なぜなら、フィルタ グラフの停止中にフルスクリーン モードを設定すると、ユーザーはフルスクリーン モードから出る (すなわち元のアプリケーションに戻る) まで、グラフの実行を開始できない可能性がある。

IVideoWindow を実装するレンダラはすべて、そのウィンドウがアクティブになったとき、または非アクティブになったときに、フィルタ グラフ マネージャにイベント コードを送信する。フルスクリーン モードの間、PID はこれらのイベント コードを監視する。フルスクリーンにしたウィンドウが非アクティブになったことを検出すると、自動的にフルスクリーンモードを終了し、アプリケーション イベント キューに EC_FULLSCREEN_LOST 通知を送信する。これは PID によって行われる唯一の介入である。このトピックで説明したとおり、その他すべてのユーザー インターフェイスはアプリケーションに公開されている。

フルスクリーン再生で最も重要な点の 1 つは、フルスクリーン モードの間、フルスクリーン ウィンドウの上に他のウィンドウを表示できないことである。実際、フルスクリーン レンダラが表示モードを切り替えると、他のアプリケーションに対する GDI 出力がすべて無効にされるため、フルスクリーン ウィンドウの上にウィンドウを表示することは実際に不可能である。ユーザーがコンピュータにアクセスするには、ホット キーを使用する必要がある。

PID は、フルスクリーン再生の実装のために最終的にどのようなメカニズムを使用する場合でも、再生を実行するウィンドウで常にメッセージ ドレーン プロパティが設定されるようにする (メッセージ ドレーンは、レンダラに送信されるすべての Windows® メッセージが転送されるウィンドウを指定する)。そのため、フルスクリーン レンダラが使用される場合でも、フィルタ グラフ マネージャの IVideoWindow インターフェイスでメッセージ ドレーンが設定されている限り、すべてのメッセージがそのレンダラに渡される。

メッセージ ドレーンが適切なウィンドウに設定されているため、アプリケーションは、フルスクリーン モードを実装するフィルタに関係なく、フルスクリーン モードにおいてすべてのマウスおよびキーボード メッセージを受信できる。アプリケーションはそれに基づき、シークなどに対してホット キー サポートを実装することができる。ただし、プロパティはフルスクリーン モードでないときにしか設定できないので、アプリケーションがフルスクリーン モードの間しかメッセージを捕捉する必要がない場合、フルスクリーン モードをオンにする前にメッセージ ドレーンを設定しなければならない。同様に、メッセージ ドレーンのリセットは、フルスクリーン モードをオフにした後でなければ行えない。

アプリケーションについて考慮すべきもう 1 つの点は、フルスクリーン モードの間、IBasicVideo で設定した転送元矩形および転送先矩形が適用されないということである。PID はフルスクリーン モードに切り替える際にこれらの矩形をリセットする。これは、フルスクリーン サポートを実装するすべてのフィルタが同様に IBasicVideo をサポートすることが保証できないからである。


代替ビデオレンダラ

ここでは、レンダラのやや複雑な実装要件のいくつかについて説明する。ビデオに固有の要素 (たとえば EC_REPAINT やその他の通知) もあるが、これらの要件はほとんどのレンダラに当てはまる。ここでは特に、各種の通知、状態の変更、およびフォーマットの変更について説明する。また、レンダラがフィルタ グラフ マネージャに送信する通知もおおまかに説明する。

このトピックは、以下のセクションを含んでいる。

  • 代替レンダラを書く
  • エンドオブストリーム通知およびフラッシング通知の処理
  • 状態の変更とポーズの完了の処理
  • 終了処理
  • 動的なフォーマットの変更の処理
  • 持続プロパティの処理
  • EC_REPAINT 通知の処理
  • フルスクリーン モードでの通知の処理
  • 通知の要約

代替レンダラを書く

Microsoft® DirectShow® は、ウィンドウ ベースのビデオ レンダラを提供するほか、ランタイム インストールではフルスクリーン レンダラも提供する。DirectShow の基底クラスを使用すると、代替ビデオ レンダラを書くことができる。代替レンダラが DirectShow ベースのアプリケーションと正常にやり取りを行うためには、レンダラはこのトピックで説明するガイドラインに従わなければならない。CBaseRenderer および CBaseVideoRenderer クラスは、代替ビデオ レンダラを実装するときにこのガイドラインを守るうえで役に立つ。DirectShow の開発は現在も進行中なので、実装を定期的に見直して、レンダラが最新バージョンの DirectShow との互換性を確保しているかどうかを確認することが重要である。

ここでは、レンダラが扱うべき多くの通知について説明する。その前に、DirectShow の通知を簡単に復習しておく。基本的に、DirectShow で発生する通知には次の 3 種類の通知がある。

  • ストリーム通知は、メディア ストリーム内で発生し、あるフィルタから次のフィルタに渡されるイベントである。このような通知には、フラッシング開始、フラッシング終了、またはエンドオブストリーム通知があり、ダウンストリーム フィルタの入力ピン (たとえば IPin::BeginFlush) で適切なメソッドを呼び出すことによって送信される。
  • フィルタ グラフ マネージャ通知は、フィルタからフィルタ グラフ マネージに渡される通知 (たとえば EC_COMPLETE) である。フィルタ グラフ マネージャの IMediaEventSink::Notify メソッドを呼び出すことによって送信される。
  • アプリケーション通知は、制御アプリケーションによってフィルタ グラフ マネージャから取得される。アプリケーションは、フィルタ グラフ マネージャの IMediaEvent::GetEvent メソッドを呼び出してこれらのイベントを取得する。しばしば、フィルタ グラフ マネージャは、受け取ったイベントをアプリケーションに渡す。

ここでは、受け取ったストリーム通知を処理して適切なフィルタ グラフ マネージャ通知を送信するレンダリング フィルタの役割について説明する。

エンドオブストリーム通知およびフラッシング通知の処理

エンドオブストリーム通知は、送信すべきデータがもはやそれ以上ないことを検出したアップストリーム フィルタ (たとえばソース フィルタ) が生成する。この通知はグラフ内のすべてのフィルタに渡され、最終的にレンダラに渡される。これに対して、レンダラは EC_COMPLETE 通知をフィルタ グラフ マネージャに渡す責任を持つ。これらの通知の処理に関して、レンダラには特別な役割が与えられている。

入力ピンの IPin::EndOfStream メソッドがアップストリーム フィルタに呼び出されると、レンダラはエンドオブストリーム通知を受け取る。レンダラはこの通知を認識し、引き続き既に受け取っているすべてのデータをレンダリングしなければならない。残っているデータがすべて受け取られたら、レンダラは EC_COMPLETE 通知をフィルタ グラフ マネージャに送信しなければならない。EC_COMPLETE 通知は、エンドオブストリームに到達するごとにレンダラによって 1 回だけ送信されなければならない。さらに EC_COMPLETE 通知は、フィルタ グラフが実行中でない限り送信されてはならない。したがって、ソース フィルタがエンドオブストリーム通知を送信したときにフィルタ グラフがポーズ状態であった場合は、フィルタ グラフが実行されるまでは EC_COMPLETE が送信されてはならない。

エンドオブストリーム通知が通知済になると、すべての IMemInputPin::Receive または IMemInputPin::ReceiveMultiple メソッド呼び出しは拒否されなければならない。この場合、返されるエラー メッセージとしては E_UNEXPECTED が最も適している。

フィルタ グラフが停止状態にあるときは、キャッシュされたエンドオブストリーム通知はすべてクリアされなければならず、次に開始されたときに再送信されてはならない。これは、適切なフラッシングが発生するように、フィルタ グラフ マネージャがフィルタを実行する直前に必ずすべてのフィルタをポーズさせるからである。したがって、たとえばフィルタ グラフがポーズ状態でエンドオブストリーム通知が受け取られ、フィルタ グラフが停止した場合、レンダラは、後で実行されるときに EC_COMPLETE 通知を送信してはならない。シークが発生しなかった場合、ソース フィルタは、実行状態の前のポーズ状態にある間に自動的に別のエンドオブストリーム通知を送信する。一方、フィルタ グラフが停止している間にシークが発生した場合、ソース フィルタは送信すべきデータを持っている可能性がある。したがって、ソース フィルタははエンドオブストリーム通知を送信しない。

ビデオ レンダラは、EC_COMPLETE 通知を送信するよりも、エンドオブストリーム通知を使用することが多い。たとえばストリームが再生を完了し (すなわち、エンドオブストリーム通知が送信され)、別のウィンドウがビデオ レンダラ ウィンドウ上にドラッグされた場合、いくつかの WM_PAINT ウィンドウ メッセージが生成される。ビデオ レンダラを実行する一般的な方法は、WM_PAINT メッセージを受信したときに、(描画されるべき別のフレームが受信されると想定して) 現在のフレームを再描画しないようにすることである。ただし、エンドオブストリーム通知が送信されると、レンダラは待機状態になる。すなわち、レンダラは実行中ではあるが追加のデータを受信しない。このような状況で、レンダラは通常、再生領域を黒で塗りつぶす。

フラッシングの処理は、レンダラにとってのもう 1 つの問題である。フラッシングは、BeginFlush と EndFlush の 1 組の IPin メソッドを介して実行される。基本的に、フラッシングはレンダラが処理しなければならない追加の状態である。ソース フィルタが EndFlush を呼び出さずに BeginFlush を呼び出すことは不正であるので、この状態はおそらく短くて連続していない。ただしレンダラは、フラッシュ移行の間に受け取ったデータまたは通知を正常に処理しなければならない。

BeginFlush 呼び出し後に受け取ったデータは、E_UNEXPECTED を返すことによって即座に拒否しなければならない。さらに、キャッシュされたエンドオブストリーム通知も、レンダラがフラッシュされるときにクリアされなければならない。通常、レンダラはシークに対してフラッシュされる。フラッシュを行うことにより、新しいサンプルが送信される前に古いデータがフィルタ グラフから確実にクリアされる。(通常、ストリームの 2 つのセクションを続けて再生する場合、1 つのセクションが完了するのを待ってからシーク コマンドを発行するよりも、遅延コマンドを使う方が処理的に優れている。)

状態の変更とポーズの完了の処理

レンダリング フィルタは、その状態が変化するときにフィルタ グラフ内のほかのフィルタと同じように動作するが、次のような例外がある。ポーズされた後、レンダラはデータをキューに入れ、以降の実行でレンダリングを行う準備をする。ビデオ レンダラを停止した場合、レンダラはこのキューに入っているデータを保持する。これは、フィルタ グラフが停止状態のときはフィルタはリソースを保持してはならないという DirectShow の規則に対する例外である。

この例外の理由は、リソースを保持することでレンダラは WM_PAINT メッセージを受け取った場合にウィンドウを再描画するイメージを常に持つということにある。またレンダラは、現在のイメージのコピーを要求する CBaseControlVideo::GetStaticImage などのメソッドを満足するイメージを持つ。リソースを保持するもう 1 つの効果として、イメージを保持することでアロケータがデコミットされることがなくなり、イメージ バッファが既に割り当てられているので次の状態変更がより迅速に行われるようになる。

ビデオ レンダラは、実行中にのみ、サンプルをレンダリングおよび解放しなければならない。ポーズ状態のときは、フィルタがサンプルをレンダリングすることはある (たとえばウィンドウ内でスタティック ポスター イメージを描画するとき) が、サンプルを解放してはならない。オーディオ レンダラは、ポーズ状態のときはレンダリングを行わない (ただし、たとえば wave デバイスの準備などのほかの処理は行える)。サンプルをレンダリングするタイムは、サンプルのストリーム タイムと、IMediaControl::Run メソッドへのパラメータとして渡された基準タイムとを組み合わせることによって求められる。レンダラは、終了タイム以下の開始タイムを持つサンプルを拒否しなければならない。

アプリケーションがフィルタ グラフをポーズすると、フィルタ グラフはレンダラでキューに入れられたデータが存在するまで IMediaControl::Pause メソッドから復帰しない。これを確実にするために、レンダラがポーズされたときにレンダリングするデータがない場合は S_FALSE を返さなければならない。キューに入れられているデータがある場合は、S_OK を返すことができる。

フィルタ グラフ マネージャは、フィルタ グラフをポーズするときにすべての戻り値をチェックして、レンダラがデータをキューに入れたこと確認する。1 つまたは複数のフィルタの準備が整っていない場合、フィルタ グラフ マネージャは GetState 呼び出しによってグラフ内のそのフィルタをポーリングする。GetState メソッドは、タイムアウト パラメータを取る。状態の変更を完了する前にデータが到着するのを待っているフィルタ (通常はレンダラ) は、GetState メソッドがタイムアウトすると VFW_S_STATE_INTERMEDIATE を返す。データがレンダラに到着した場合は、GetState は S_OK を即座に返さなければならない。

中間状態および完了状態のどちらにおいても、報告されるフィルタ状態は State_Paused となる。フィルタの準備が整っているかどうかは、戻り値によって示される。レンダラがデータの到着を待っている場合、ソース フィルタはエンドオブストリーム通知を送信し、状態変更を完了しなければならない。

すべてのフィルタにおいてレンダリングするデータの準備が整うと、フィルタ グラフは、ポーズ状態の変更を完了する。

終了処理

ビデオ レンダラは、ユーザーからの終了イベントを正常に処理しなければならない。これは、ウィンドウを正常に非表示にするとともに、ウィンドウの表示が後で強制されたときにどうすべきかを知ることを意味する。ビデオ レンダラは、ウィンドウをいつ破棄 (正確には、レンダラがいつフィルタ グラフから削除されるか) してリソースを解放するかをフィルタ グラフ マネージャに通知しなければならない。

ユーザーがビデオ ウィンドウを閉じた場合 (たとえば Alt + F4 キーを押した場合)、慣習ではウィンドウを即座に非表示にし、EC_USERABORT 通知をフィルタ グラフ マネージャに送信する。この通知はアプリケーションに渡され、アプリケーションはグラフの再生を中止する。EC_USERABORT を送信した後は、ビデオ レンダラは配送されるすべてのサンプルを拒否しなければならない。

レンダラはアボート フラグをオンに保たなければならず、中止されたときに、アプリケーションがユーザー アクションをオーバーライドして (必要であれば) グラフの再生を続行するできるようにフラグをリセットしなければならない。ビデオの実行中に Alt + F4 キーが押された場合、ウィンドウは非表示になり、それ以降に配送されたサンプルはすべて拒否される。ウィンドウがそれ以降も表示される場合 (IVideoWindow::put_Visible)、EC_REPAINT 通知が生成されてはならない。

また、ビデオ レンダラは、終了するときに EC_WINDOW_DESTROYED 通知をフィルタ グラフに送信しなければならない。この処理は、実際のビデオ ウィンドウが破棄されるまで待つよりも、レンダラの IBaseFilter::JoinFilterGraph メソッドが (レンダラがフィルタ グラフから削除されようとしていることを示す) Null パラメータを取って呼び出されたときに行うのが最適である。この通知を送信すると、フィルタ グラフ マネージャの PID が、ウィンドウのフォーカスに依存したリソースを別のフィルタ (たとえばオーディオ デバイス) に渡せるようになる。

動的なフォーマットの変更の処理

DirectShow のビデオ レンダラは、効率的に描画できるビデオ フォーマットしか受け付けない。たとえばウィンドウ ベースのランタイム レンダラは、現在のディスプレイ デバイス モードに一致する RGB フォーマット (たとえばディスプレイが 65,536 色に設定されている場合は RGB565) だけを受け付ける。また、最後の手段として、ビデオ レンダラは、ほとんどのディスプレイ カードで効率的な描画が可能である 8 ビットのパレット化されたフォーマットを受け付ける。Microsoft® DirectDraw® をロードした場合、レンダラは DirectDraw サーフェスに書き込んだりディスプレイ ハードウェアから直接描画できるものに切り替えるように後でソース フィルタに要求することがある。場合によっては、ビデオの再生中にレンダラのアップストリーム フィルタがビデオ フォーマットを変更しようとすることもある。このような操作は、ビデオ ストリームがパレットの変更を行ったときによく発生する。動的なフォーマット変更を開始するのは、ほとんどの場合ビデオ デコンプレッサである。

フォーマットを動的に変更しようとするアップストリーム フィルタは、レンダラの入力ピンで必ず IPin::QueryAccept メソッドを呼び出さなければならない (CTransformFilter に基づくフィルタの場合、これは CTransformFilter::CheckInputType で実装される)。アップストリーム フィルタが動的に変更する対象としてレンダラがどのフォーマットを許可するかは不定である。ただし、最低限でもレンダラはアップストリーム フィルタがパレットを変更することを許可しなければならない。メディア タイプを変更する場合、アップストリーム フィルタは新しいタイプで配送された最初のサンプルにフォーマットをアタッチする。レンダリングされるのを待っているキューにたくさんのサンプルがある場合、レンダラはタイプが変更されたサンプルが実際にレンダリングされるときまで、フォーマットの変更を遅らせなければならない。

フォーマットの変更を検出するごとに、ビデオ レンダラは EC_DISPLAY_CHANGED 通知を送信しなければならない。ほとんどのビデオ レンダラは接続中にフォーマットを選択して、そのフォーマットが GDI を介して効率的に描画されるようにする。ユーザーがコンピュータを再起動せずに現在のディスプレイ モードを変更した場合、レンダラはそれ自体のイメージ フォーマット接続が不良であると判断してこの通知を送信しなければならない。第 1 パラメータは、再接続が必要なピンとする。フィルタ グラフ マネージャは、フィルタ グラフを停止してピンの再接続が行われるように準備する。それに続く再接続の間、レンダラはより適切なフォーマットを受け付けることができる。

ストリーム内でパレットの変更を検出するごとに、ビデオ レンダラは EC_PALETTE_CHANGED 通知をフィルタ グラフ マネージャに送信しなければならない。DirectShow ビデオ レンダラは、パレットが動的に変更されたかどうかを検出する。ビデオ レンダラは、送信された EC_PALETTE_CHANGED 通知をフィルタで除外するほかに、必要なパレットの作成、インストール、および削除処理の量を減らす目的で、このような動作を行う。

最後に、ビデオ レンダラはビデオのサイズが変更されたことを検出することがある。この場合、ビデオ レンダラは EC_VIDEO_SIZE_CHANGED 通知を送信しなければならない。アプリケーションはこの通知を使用して複合ドキュメント内の空間を調整することができる。ビデオの実際のディメンジョンは、IBasicVideo コントロール インターフェイスを使用して取得できる。DirectShow レンダラは、これらのイベントを送信する前に、ビデオのサイズが変更されたかどうかを検出する。

持続プロパティの処理

IBasicVideo および IVideoWindow インターフェイスを介して設定されるすべてのプロパティは、接続間で持続性を持つとみなされる。したがって、レンダラの接続解除および接続処理は、ウィンドウのサイズ、位置、またはスタイルに影響を及ぼしてはならない。しかし、接続間でビデオ ディメンジョンが変更された場合、レンダラは転送元矩形および転送先矩形をそのデフォルトにリセットしなければならない。転送元および転送先の位置は、IBasicVideo インターフェイスを介して設定される。

IBasicVideo および IVideoWindow は、どちらもプロパティへの十分なアクセスを提供して、インターフェイス内のすべてのデータを持続フォーマットで保存および復元することを可能にする。これは、編集セッション中にフィルタ グラフの正確な構成およびプロパティを保存して後で復元しなければならないアプリケーションにとって役に立つ。

EC_REPAINT 通知の処理

EC_REPAINT 通知は、レンダラがポーズまたは停止状態のときだけ送信される。この通知は、レンダラがデータを必要としていることをフィルタ グラフ マネージャに通知する。これらの通知の 1 つを受け取ったときにフィルタ グラフが停止状態であった場合、フィルタ グラフ マネージャはフィルタ グラフをポーズ状態にし、(GetState 呼び出しによって) すべてのフィルタがデータを受け取るのを待ち、再度フィルタ グラフを停止させる。停止状態のとき、ビデオ レンダラは後続の WM_PAINT メッセージを処理できるようにイメージを保持しなければならない。

したがって、停止またはポーズ状態でビデオ レンダラが WM_PAINT メッセージを受け取り、ウィンドウを描画するものがない場合は、EC_REPAINT をフィルタ グラフ マネージャに送信しなければならない。EC_REPAINT 通知がポーズ状態で受け取られた場合、フィルタ グラフ マネージャは、現在位置を使って IMediaPosition::put_CurrentPosition を呼び出す (すなわち現在位置へのシーク)。これにより、ソース フィルタはフィルタ グラフをフラッシュし、新しいデータがフィルタ グラフを介して送信される。

レンダラは、一度のこれらの通知のうち 1 つだけを送信しなければならない。したがって、通知を送信した場合、レンダラはいくつかのサンプルが配送されるまでそれ以上のデータが送信されないことを保証しなければならない。これを行う従来の方法は、フラグを使用して再描画が送信可能かどうかを示す方法である。この場合、フラグは、EC_REPAINT 通知が送信された後にオフに設定される。このフラグは、データが配送されたり入力ピンがフラッシュされたときにリセットされなければならない。ただし、エンドオブストリームが入力ピンに通知済の場合はこれに当てはまらない。

レンダラがその EC_REPAINT 通知を監視しないと、フィルタ グラフ マネージャは EC_REPAINT 要求であふれることになる (非常に高価な処理になる)。たとえば描画するイメージをレンダラが持たず、フルドラッグ操作で別のウィンドウがレンダラのウィンドウ上をドラッグされた場合、レンダラは複数の WM_PAINT メッセージを受け取る。これらのメッセージのうちの最初のものだけがレンダラからフィルタ グラフ マネージャへの EC_REPAINT イベント通知を生成しなければならない。

レンダラは、その入力ピンを EC_REPAINT 通知の第 1 パラメータとして送信しなければならない。これにより、アタッチされた出力ピンに対して IMediaEventSink の照会が行われ、サポートされている場合は EC_REPAINT 通知が最初に送信される。これにより、フィルタ グラフ以前に出力ピンが再描画を扱うことが可能になる。フィルタ グラフが停止状態の場合、デコミットされたレンダラ アロケータからのバッファを利用することができないので、この処理は行われない。

出力ピンが要求を処理することができず、フィルタ グラフが実行中の場合、EC_REPAINT 通知は無視される。出力ピンは、IMediaEventSink::Notify から NOERROR (S_OK) を返すことによって、再描画要求を正常に処理したことを通知しなければならない。出力ピンはフィルタ グラフ マネージャのワーカー スレッドで呼び出される。すなわち、レンダラが出力ピンを直接呼び出さないようにしてデッドロックが回避されする。フィルタ グラフが停止状態またはポーズ状態で出力が要求を処理しない場合は、デフォルトの処理が行われる。

フルスクリーン モードでの通知の処理

フィルタ グラフの IVideoWindow PID は、フルスクリーン再生を管理する。この PID は、スペシャリスト フルスクリーン レンダラのためにビデオ レンダラをスワップ アウトしたり、レンダラのウィンドウをフルスクリーンに拡大したり、あるいはレンダラにフルスクリーン再生を直接実装させる。フルスクリーン プロトコルを使うためには、ビデオ レンダラはウィンドウがアクティブまたは非アクティブにされるごとに EC_ACTIVATE 通知を送信しなければならない。すなわち、レンダラが受け取るそれぞれの WM_ACTIVATEAPP メッセージに対して EC_ACTIVATE 通知を送信しなければならない。

レンダラをフルスクリーン モードで使用するとき、これらの通知はフルスクリーン モードの切り替えを管理する。通常、ウィンドウの非アクティブは、ユーザーが Alt + Tab キーを押して別のウィンドウに切り替えるときに発生する。DirectShow フルスクリーン レンダラはこれをキューとして一般的なレンダリング モードに戻る。

フルスクリーン モードの終了時に EC_ACTIVATE 通知がフィルタ グラフ マネージャに送信されると、フィルタ グラフ マネージャは EC_FULLSCREEN_LOST 通知を制御アプリケーションに送信する。アプリケーションは、たとえばこの通知を使用してフルスクリーン ボタンの状態を復元する。EC_ACTIVATE 通知は、ビデオ レンダラからキューが渡されたときのフルスクリーン切り替えを管理するために DirectShow 内部で使用される。

通知の要約

レンダラが送信可能なフィルタ グラフ通知を以下に示す。

イベント通知 | 説明
EC_ACTIVATE | フルスクリーン レンダリング モードのビデオ レンダラによって、受け取ったそれぞれの WM_ACTIVATEAPP メッセージについて送信される。
EC_COMPLETE | すべてのデータがレンダリングされた後でレンダラによって送信される。
EC_DISPLAY_CHANGED | ディスプレイ フォーマットが変更されたときにビデオ レンダラによって送信される。
EC_PALETTE_CHANGED | ビデオ レンダラがストリーム内でパレットの変更を検出するごとに送信される。
EC_REPAINT | WM_PAINT メッセージが受け取られ、表示するデータがないときに、停止またはポーズ状態のビデオ レンダラによって送信される。これにより、フィルタ グラフ マネージャは、ディスプレイに描画するフレームを生成する。
EC_USERABORT | ユーザーが終了を要求したことを通知するためにビデオ レンダラによって送信される (たとえばユーザーがビデオ ウィンドウを閉じた場合)。
EC_VIDEO_SIZE_CHANGED | ネイティブ ビデオ サイズの変更が検出されるごとにビデオ レンダラによって送信される。
EC_WINDOW_DESTROYED | フィルタが削除または破棄されたときにビデオ レンダラによって送信され、ウィンドウのフォーカスに依存するリソースをほかのフィルタに渡せるようにする。


ビデオ レンダラにおける転送元矩形と転送先矩形

ビデオ メディア タイプの VIDEOINFO、VIDEOINFOHEADER、および VIDEOINFOHEADER2 フォーマット構造体には 3 つのサイズがある。ここでは、その内容と機能について説明する。

まず、これらの構造体の bmiHeader メンバにサイズがある。bmiHeader メンバは BITMAPINFOHEADER 構造体であり、独自の幅メンバと高さメンバとして bmiHeader.biWidth および bmiHeader.biHeight を持つ。

また、各構造体の rcSource メンバに矩形がある。さらに、各構造体の rcTarget メンバにも矩形がある。

2 つのフィルタ A と B があり、この 2 つが特定のビデオ メディア タイプで互いに接続されているとする。A が左側 (アップストリーム)、B が右側 (ダウンストリーム) である。

フィルタ A とフィルタ B の間のバッファには、サイズ (bmiHeader.biWidth、bmiHeader.biHeight) がある。フィルタ A は rcSource によって決定される入力ビデオの一部を受け取り、そのビデオをバッファの rcTarget 部分に合わせて伸縮する。入力ビデオで使用される部分は、フィルタ A および B が最初に接続されるメディア タイプの (biWidth、biHeight) サイズと、rcSource との比率によって決まる。rcSource が空である場合、フィルタ A はその入力ビデオの全体を使用する。rcTarget が空である場合、フィルタ A は出力バッファの全体にビデオを収める。

たとえば、フィルタ A が 160 × 120 ピクセルのビデオ データを受け取ると仮定する。また、フィルタ A が次のメディア タイプでフィルタ B に接続されているとする。

(biWidth, biHeight) : 320, 240
rcSource : (0, 0, 0, 0)
rcTarget : (0, 0, 0, 0)

この場合、フィルタ A は受け取ったビデオを x 方向と y 方向の両方について 2 倍に伸長し、320 × 240 の出力バッファに収める。

もう 1 つの例として、フィルタ A が 160 × 120 のビデオ データを受け取り、次のメディア タイプでフィルタ B に接続されているとする。

(biWidth, biHeight) : 320, 240
rcSource : (0, 0, 160, 240)
rcTarget : (0, 0, 0, 0)

rcSource メンバは接続されたバッファ サイズ (320, 240) に対する値である。指定された rcSource (0, 0, 160, 240) はバッファの左半分であるため、フィルタ A は入力ビデオの左半分、すなわち (0, 0, 80, 120) 部分を受け取り、ビデオをサイズ (320, 240) に (x 方向に 4 倍、y 方向に 2 倍に) 伸長して、320 × 240 の出力バッファに収める。

ここで、フィルタ A が GetBuffer を呼び出し、返されたメディア サンプルにアタッチされたメディア タイプにより、フィルタ B がフィルタ A にそれまでと異なるサイズまたは種類のビデオを要求していることが示される。新しいメディア タイプは次のとおりである。

(biWidth, biHeight) : 640, 480
rcSource : (0, 0, 160, 120)
rcTarget : (0, 0, 80, 60)

この場合、メディア サンプルにはサイズが 640 × 480 のバッファが含まれる。rcSource メンバは、新しいメディア タイプ (640, 480) ではなく最初に接続されていたメディア タイプ (320, 240) に基づく。したがって、rcSource は入力ビデオの左上の 25% が使用されることを指定する。rcTarget の (0, 0, 80, 60) に従って、入力ビデオのこの部分は 640 × 480 の出力バッファの左上の (80, 60) ピクセルに配置される。フィルタ A は 160 × 120 のビデオを受け取るため、入力ビデオの左上は (80, 60) となる。これは出力ビットマップと同じサイズであり、伸縮は不要である。

フィルタ A は出力バッファの残りのピクセルにはデータを配置せず、その部分のビットは操作しない。rcSource メンバは、フィルタ A とフィルタ B の間に最初に接続されていたメディア タイプの biWidth と biHeight によって制限される。rcTarget は、メディア サンプルの新しい biWidth と biHeight によって制限される。上記の例では、rcSource は (0, 0, 320, 240) の境界を出ることができず、rcTarget は (0, 0, 640, 480) の境界を出ることができない。


キャプチャ フィルタ

ここでは、キャプチャ フィルタを作成する方法について説明する。

  • ビデオ キャプチャ フィルタの作成
  • オーディオ キャプチャ フィルタの作成


ビデオ キャプチャ フィルタの開発

このトピックでは、ビデオ キャプチャ フィルタを作成する際に考慮すべき重要な点について説明する。Microsoft® DirectShow® には標準の VFW キャプチャ フィルタが含まれている。

このトピックは、以下のセクションを含んでいる。

  • キャプチャ ピンとプレビュー ピンの要件
  • キャプチャとプレビューの最適化 (オプション)
  • ビデオ キャプチャ フィルタの登録
  • データの生成
  • 個々のストリームの制御
  • タイム スタンプ
  • フレーム レート
  • IAMDroppedFrames の実装
  • 必要なインターフェイス

キャプチャ ピンとプレビュー ピンの要件

キャプチャ フィルタのキャプチャ ピンとプレビュー ピン (存在する場合) は、IKsPropertySet インターフェイスをサポートする必要がある。アプリケーションはこのインターフェイスを呼び出して、AMPROPSETID_Pin プロパティ セットの AMPROPERTY_PIN_CATEGORY の値を取得することにより "どのカテゴリのピンであるか" をたずねる。戻り値は、通常、PIN_CATEGORY_CAPTURE または PIN_CATEGORY_PREVIEW のいずれかの GUID である。詳細は、「ピン プロパティ セット」を参照すること。キャプチャ フィルタは IKsPropertySet をサポートする必要がある。サポートされていないと、アプリケーションはフィルタ グラフ内でフィルタを接続する方法を指示することができない。

ピンには任意の名前を付けることができ、その他の必要な目的のために出力ピンを追加できる。ピンの名前がチルダ (~) 文字で始まる場合、アプリケーションが IGraphBuilder::RenderFile を呼び出しても、フィルタ グラフはそのピンに対して自動的なレンダリングを行わない。たとえば、キャプチャ フィルタにキャプチャ ピンとプレビュー ピンが両方ともあり、キャプチャ ピンに "~capture" 、プレビュー ピンに "preview" という名前を付けたとする。この場合、アプリケーションがグラフ内でフィルタをレンダリングすると、プレビュー ピンはビデオ レンダラに接続され、キャプチャ ピンには何も接続されない。デフォルトでこのような設定を使用することは一般的である。これは、レンダリングを行わない単なる情報用のピンや、プロパティを設定するために列挙する必要があるピンなどにも応用できる。

接頭文字チルダ (~) は、RenderFile とインテリジェント接続 (IGraphBuilder::Connect) の動作にのみ影響する。それでも、このプロパティを含んでいるピンが IPin::Connect メソッドを実装していれば、それらのピンの接続にインテリジェントな接続を使用できる。しかし、名前がチルダ文字で始まる接続を完了するために中間フィルタを使用している場合は、インテリジェント接続に際してそのフィルタの出力ピンが接続されることはない。

オーディオ キャプチャ フィルタの詳細については、「オーディオ キャプチャ ピンの要件」を参照すること。

次のサンプル コードに、キャプチャ ピンに IKsPropertySet を実装する方法を示す。

//
// ピン カテゴリ - これがキャプチャ ピンであることを示す。
//

HRESULT CMyCapturePin::Set(REFGUID guidPropSet, DWORD dwPropID,
LPVOID pInstanceData, DWORD cbInstanceData,
                           LPVOID pPropData, DWORD cbPropData)
{
    return E_NOTIMPL;
}

// プロパティを取得するために、呼び出し元は呼び出した関数がデータを格納するための
// バッファを割り当てる。必要なバッファ サイズを決定するために、pPropData=NULL および
// cbPropData=0 を指定して Get を呼び出す。
HRESULT CMyCapturePin::Get(REFGUID guidPropSet, DWORD dwPropID,
LPVOID pInstanceData, DWORD cbInstanceData, LPVOID pPropData,
                           DWORD cbPropData, DWORD *pcbReturned)
{
if (guidPropSet != AMPROPSETID_Pin)
return E_PROP_SET_UNSUPPORTED;

if (dwPropID != AMPROPERTY_PIN_CATEGORY)
return E_PROP_ID_UNSUPPORTED;

    if (pPropData == NULL && pcbReturned == NULL)
return E_POINTER;

    if (pcbReturned)
        *pcbReturned = sizeof(GUID);

    if (pPropData == NULL)
return S_OK;

    if (cbPropData < sizeof(GUID))
        return E_UNEXPECTED;

    *(GUID *)pPropData = PIN_CATEGORY_CAPTURE;
return S_OK;
}

// QuerySupported は E_NOTIMPL を返すか、または、プロパティ セットとプロパティの
// 取得や設定がサポートされているかどうかを正しく示す必要がある。
// S_OK は、プロパティ セットとプロパティ ID の組み合わせが正しいことを示す。
HRESULT CMyCapturePin::QuerySupported(REFGUID guidPropSet, DWORD dwPropID,
                                      DWORD *pTypeSupport)
{
if (guidPropSet != AMPROPSETID_Pin)
return E_PROP_SET_UNSUPPORTED;

if (dwPropID != AMPROPERTY_PIN_CATEGORY)
return E_PROP_ID_UNSUPPORTED;

    if (pTypeSupport)
        *pTypeSupport = KSPROPERTY_SUPPORT_GET;
return S_OK;
}

キャプチャとプレビューの最適化 (オプション)

フィルタが動作中で、データのキャプチャを行っているときには、プレビュー ピンとキャプチャ ピンの両方からフレームのコピーを送信する必要がある。ハードウェア支援 (オーバーレイなど) によるプレビューが可能で、プレビュー ピンを使用している場合は、そのプレビュー ピンに対して IMemInputPin インターフェイスの代わりに IOverlay インターフェイス転送を使用できる。IOverlay の使用はオプションである。ハードウェア支援によるプレビューを実行できない場合は、空いた時間があるときにだけプレビュー ピンからフレームを送る。フレームをドロップするおそれがある場合は、これを行わない。キャプチャ ピンが優先される。

たとえば、キャプチャ ピンから直ちに送るべきものが 1 つもなく、ダウンストリーム フィルタがキャプチャ ピンから以前に配送されたバッファをすべて解放してある場合のみ、プレビュー ピンからフレームを配送することができる。

データのフォーマットを 1 種類しかキャプチャできず、そのためにプレビュー ピンとキャプチャ ピンが同じメディア タイプを生成する必要がある場合、または、ピンを適切に再接続する方法の詳細を知りたい場合は、先へ読み進む。それ以外の場合は、このトピックを読む必要はない。

プレビュー ピンとキャプチャ ピンから同じフォーマットのデータを送る。フィルタ グラフ マネージャがキャプチャ ピンを異なるフォーマットで再接続した場合は、プレビュー ピンを同じフォーマットで再接続しなければ機能しない。キャプチャ ピンが接続されていてプレビュー ピンが接続されていない場合は、キャプチャ ピンと同じメディア タイプでプレビュー ピンのみ接続する必要がある。2 つのピンは、一致していなければならない。

次のサンプル コードに、適切な再接続の手順を示す。

// プレビュー ピンの接続先のフィルタが新しいメディア タイプを受け入れない場合、
// キャプチャ ピンがそのメディア タイプを受け入れることはできない。プレビュー
// ピンは、常にキャプチャ ピンと同じタイプを出力しなければならない。
CCapturePin::CheckMediaType(CMediaType *pmt)
{
    if (m_pMyPreviewPin->IsConnected()) {
        // プレビュー ピンの接続はこのタイプと同じか?
          if (m_pMyPreviewPin->GetConnected()->QueryAccept(pmt) != NOERROR) {
            // プレビュー ピンはこの新しいタイプでは再接続できない。
            return E_INVALIDARG;
        }
    }

    // キャプチャ ピンの接続先がわかれば、このメディア タイプで
    // よいかどうか決定できるであろう。しかし、その必要は
    // ない。キャプチャ ピンが接続されると、同じフォーマットを
    // 使用して再接続される。

    return NOERROR;
}

// プレビュー ピンが受け入れ可能なメディア タイプは、
// キャプチャ ピンが使用しているものだけである。
CPreviewPin::CheckMediaType(CMediaType *pmt)
{
    CMediaType cmt = m_pMyCapturePin->m_mt;
     if (m_pMyCapturePin->IsConnected() && *pmt != cmt)
        // プレビュー ピンはキャプチャ ピンと同じ
        // フォーマットでなければ接続できない。
        return E_INVALIDARG;

    else if (!m_pMyCapturePin->IsConnected())
        // キャプチャ ピンの接続先がわかれば、このメディア タイプで
        // よいかどうか決定できるであろう。しかし、その必要は
        // ない。キャプチャ ピンが接続されると、同じフォーマットを
        // 使用して再接続される。

    // キャプチャ ピンが接続されていて、これが同じメディア タイプであれば、
    // OK である。
    return NOERROR;
}

// キャプチャ ピンは、特定のメディア タイプを使用するように指定されている。
// プレビュー ピンにも、同じメディア タイプを使用させなければならない。
CCapturePin::SetMediaType(CMediaType *pmt);
{
if (m_pMyPreviewPin->IsConnected()) {

    // このメディア タイプでプレビュー ピンを再接続する必要がある。
      if (m_pMyPreviewPin->GetConnected()->QueryAccept(pmt) == NOERROR) {

        // プレビュー ピンが接続されている他のフィルタは、この新しい
        // メディア タイプを受け入れることができるので、そのまま再接続する。
        m_pFilter->m_pGraph->Reconnect(m_pMyPreviewPin);
    }
    }
}

ビデオ キャプチャ フィルタの登録

フィルタはビデオ キャプチャ フィルタ カテゴリに登録する必要がある。詳細については、AMovieDllRegisterServer2 の説明を参照すること。

データの生成

キャプチャ ピンおよびプレビュー ピンでのデータの生成は、フィルタ グラフが実行状態の場合にだけ行う。フィルタ グラフがポーズしている間は、ピンからデータを送信してはならない。もし送信すると、フィルタ グラフに混乱が生じる。これを避けるには CBaseFilter::GetState 関数から VFW_S_CANT_CUE を返すことで、フィルタ グラフに対して、ポーズ中はデータを送信しないことを警告する。これを次のコードに示す。

CMyVidcapFilter::GetState(DWORD dw, FILTER_STATE *State)
{
*State = m_State;
if (m_State == State_Paused)
return VFW_S_CANT_CUE;
else
return S_OK;
}

個々のストリームの制御

出力ピンはすべて IAMStreamControl インターフェイスをサポートする必要があるため、アプリケーションは各ピンを個別にオンまたはオフにすることができる (たとえば、キャプチャせずにプレビューする場合など)。IAMStreamControl を使用すると、別のグラフを再作成しなくとも、プレビューとキャプチャの間で切り替えることができる。

タイム スタンプ

フレームをキャプチャして送信する場合、フレームがキャプチャされたときのグラフのクロックの時刻によって、フレームにタイム スタンプを記録する。終了タイムは、開始タイムに時間幅を加えた値である。たとえば、1 秒間に 10 フレームというレートでキャプチャされ、キャプチャされた時点でグラフのクロックが 200,000,000 単位を示している場合、サンプルのタイム スタンプは (200000000, 201000000) となる (1 秒あたり 10,000,000 単位)。

プレビュー フレームには遅延時間の問題があるので、タイム スタンプを記録しないほうがよい。サンプルのタイム スタンプがプレビュー ピンから出力されたときのグラフの時刻である場合、サンプルがレンダラに到着するまでに遅れが生じるため、遅延時間が発生する。したがって、レンダラは時間を節約して "遅れを取り戻す" ために、そのサンプルを描画しない場合がある。これは、ライブ ストリームでは許されない。IAMStreamControl を実装するにはタイム スタンプが必要である。そのため、プレビュー ピンにはストリーム コントロールを実装しないか、処理待ちの開始または停止要求がある場合のみプレビュー ピン サンプルにタイム スタンプを記録するか、あるいは遅延時間の問題を許容するか、のいずれかを選択する。

配送するサンプルのメディア タイムを設定しなければならない。また、キャプチャ ピンに対する通常のタイム スタンプの設定も必要である。メディア タイムはサンプルのフレーム番号である。たとえば、フレームのキャプチャと送信を行い、フレーム 3 がドロップされる場合、メディア タイム値を (0,1) (1,2) (2,3) (4,5) (5,6) のように設定する。これにより、使用されているクロックがビデオ デジタル化用のクロックではなく通常のタイム スタンプがややランダムな場合でも、ビデオ フレームにドロップが生じると、ダウンストリームにそれを通知できる。

また、実行状態からポーズし、再び実行する場合は、ポーズの前に送信された最後のタイム スタンプよりも小さいタイム スタンプでサンプルを送信してはならない。タイム スタンプは時間をさかのぼることはできず、ポーズ前の時間に戻ることもできない。

フレーム レート

フィルタがデータを生成するフレーム レートは、出力ピンが接続されているメディア タイプの VIDEOINFOHEADER の AvgTimePerFrame フィールドによって決定される。キャプチャは任意のフレーム レートでは行えず、特定のレートでのみ行える。ピンが接続されているメディア タイプから、実行できないフレーム レートを要求された場合、そのレートより低く、最も近い値の実行可能なフレーム レートによってフレームを提供しなければならない。たとえば、メディア タイプの AvgTimePerFrame が 333333 (1 秒の約 1/30、つまり 1 秒あたり 30 フレーム) であるのに対して、実行可能なフレーム レートが 1 秒に 29.97 フレームまたは 35 フレームである場合、1 秒あたり 29.97 フレームというレートにしなければならない。このフレーム レートが実行可能な値の中で最も 30 に近く、30 より小さい値だからである。AvgTimePerFrame には丸め誤差があるので、提供するフレーム レートによるフレームの時間幅が要求された値より 1 マイクロ秒以上短くならなければ、要求された値より大きなフレーム レートにすることができる。AvgTimePerFrame フィールドが 0 の場合、任意のデフォルト フレーム レートでフレームを供給できる。

IAMDroppedFrames の実装

キャプチャ フィルタのビデオ出力ピンは、必ず IAMDroppedFrames インターフェイスを実装しなければならない。

キャプチャ フィルタを実行すると、フィルタは 0、1、2、3 というシーケンスで始まるフレーム番号を送信する (フレームがドロップされた場合、その番号は欠落する) 。送信された各フレームのタイム スタンプは、イメージがデジタル化されたときのグラフ クロックの時刻に対応する。終了タイムは、開始タイムにビデオ フレームの時間幅を加えた値である。

CMediaSample::SetMediaTime を使用し、開始タイムと終了タイムのフレーム番号に基づいて、各サンプルのメディア タイムを設定する。たとえば、開始タイムと終了タイムのシーケンスは (0,1) (1,2) (2,3) のように表示される。ダウンストリーム フィルタは、通常のタイム スタンプにおける欠落を探す代わりに、フレーム番号のシーケンスにおける欠落を調べることにより、フレームがドロップされたかどうかを簡単に確認できる。開始タイムと終了タイムのシーケンスが (1,2) (2,3) (4,5) (5,6) であれば、フレーム番号 3 がドロップされたことがわかる。

キャプチャ フィルタでは、状態が State_Stopped から State_Paused に変化するたびに、カウントをすべて 0 にリセットする必要がある。

フィルタが実行状態からポーズされ、再び実行された場合、ポーズ状態と関係なくフレームの配送を継続する必要がある。2 回目の実行の後の最初のフレームには、ポーズの前に送信された最後のフレームよりも早い時刻のタイム スタンプを記録してはならない。つまり、フィルタは送信された各サンプルのメディア タイムを常に増加させる必要がある。同じフレーム番号を 2 回送信したり、時間をさかのぼったりしてはならない。

必要なインターフェイス

以下のインターフェイスの説明を読み、その実装を考慮すること。これらのインターフェイスはアプリケーションが使用する可能性のある機能を提供するので、実装することを強く推奨する。

  • フィルタまたはデータを送信する各出力ピンに IAMDroppedFrames を実装する。
  • ビデオ データを送信する各出力ピンに IAMStreamConfig を実装する。
  • データを送信する各出力ピンに IAMStreamControl を実装する。
  • ビデオ データを送信する各出力ピンに IAMVideoCompression を実装する。


オーディオ キャプチャ フィルタの開発

このトピックでは、オーディオ キャプチャ フィルタを作成する際に考慮する重要な点について説明する。Microsoft® DirectShow® には標準のオーディオ キャプチャ フィルタが含まれる。

このトピックは、以下のセクションを含んでいる。

  • オーディオ キャプチャ ピンの要件
  • オーディオ キャプチャ フィルタの登録
  • データの生成
  • 個々のストリームの制御
  • タイム スタンプ
  • 必要なインターフェイス

オーディオ キャプチャ ピンの要件

キャプチャ フィルタのキャプチャ ピンとプレビュー ピン (存在する場合) は、IKsPropertySet インターフェイスをサポートする必要がある。詳細については、「キャプチャ ピンとプレビュー ピンの要件」を参照すること。このトピックには、キャプチャ ピンに IKsPropertySet を実装するためのサンプル コードも含まれる。

キャプチャ カードはオーディオをデジタル化する前にいくつかのサウンドをミキシングすることができるが、ミキシングする各サウンド ソースについて、それぞれ 1 つの入力ピンが必要である。たとえば、サウンド カードにライン入力、マイク入力、および CD-ROM 入力がある場合は、3 つの入力ピンを使用する。通常、これらの入力ピンを他のフィルタに接続することはない。単に各ピン上で IAMAudioInputMixer インターフェイスをサポートするだけであり、アプリケーションはこのインターフェイスを使用して各ピンの録音レベル、バランス、高音域などを設定する。

オーディオ キャプチャ フィルタの登録

フィルタはオーディオ キャプチャ フィルタのカテゴリに登録する必要がある。詳細については、AMovieDllRegisterServer2 関数の説明を参照すること。

データの生成

キャプチャ ピンでのデータの生成は、フィルタ グラフが実行状態の場合にだけ行う。フィルタ グラフがポーズしている間は、ピンからデータを送信してはならない。もし送信すると、フィルタ グラフに混乱が生じる。これを避けるには CBaseFilter::GetState 関数から VFW_S_CANT_CUE を返すことで、フィルタ グラフに対して、ポーズ中はデータを送信しないことを警告する。これを次のコード サンプルに示す。

CMyVidcapFilter::GetState(DWORD dw, FILTER_STATE *State)
{
*State = m_State;
if (m_State == State_Paused)
return VFW_S_CANT_CUE;
else
return S_OK;
}

個々のストリームの制御

出力ピンはすべて IAMStreamControl インターフェイスをサポートする必要があるため、アプリケーションは各ピンを個別にオンまたはオフにすることができる (たとえば、キャプチャせずにプレビューする場合など)。IAMStreamControl を使用すると、別のグラフを再作成しなくとも、プレビューとキャプチャの間で切り替えることができる。

タイム スタンプ

キャプチャされたオーディオ サンプルを送信する場合、各グループの開始タイム スタンプは、パケット内の最初のサンプルがキャプチャされたときのグラフのクロックの開始タイムに等しい。終了タイム スタンプは、開始タイムにオーディオ パケットが表す時間幅を加えた値に等しい。オーディオ キャプチャ フィルタがクロックを提供しない場合、タイム スタンプは厳密には一致しない (1 つのパッケージの終わりが次のパッケージの開始タイム スタンプに等しい) が、これは許容範囲である。タイム スタンプ設定の例については、「ビデオ キャプチャ フィルタの開発」を参照すること。

通常のタイム スタンプに加えて、配送するサンプルのメディア タイムも設定する必要がある。メディア タイムは、パケット内のサンプル番号である。したがって、44.1 kHz オーディオの 1 秒パケットを送信する場合は、メディア タイム値を (0, 44100)、(44100, 88200) ... のように設定する。これにより、使用されているクロックがオーディオ デジタル化用のクロックではなく通常のタイム スタンプがややランダムな場合でも、オーディオ サンプルにドロップが生じると、ダウンストリーム フィルタでそれを検出できる

もう 1 つの注意点として、フィルタ グラフが実行状態からポーズされ、再び実行された場合、ポーズの前に生成した最後のタイム スタンプよりも小さいタイム スタンプでサンプルを生成してはならない。タイム スタンプは時間をさかのぼることはできず、ポーズ前の時間に戻ることもできない。

必要なインターフェイス

以下のインターフェイスの説明を読み、その実装を考慮すること。これらのインターフェイスはアプリケーションが使用する可能性のある機能を提供するので、実装することを強く推奨する。

  • フィルタまたはデータを送信する各出力ピンに IAMDroppedFrames を実装する。
  • データを送信する各出力ピンに IAMStreamConfig を実装する。
  • データを送信する各出力ピンに IAMStreamControl を実装する。
  • フィルタおよび各入力ピンに IAMAudioInputMixer を実装する。


キャプチャ フォーマットと圧縮フォーマットの公開

ここでは、IAMStreamConfig::GetStreamCaps メソッドを使用してキャプチャ フォーマットと圧縮フォーマットを返す方法を説明する。このメソッドを使うと、受け付けられるメディア タイプに関して、ピンのメディア タイプを列挙する従来の方法に比べてより多くの情報を取得することができるので、通常はこのメソッドを使用すべきである。従来のメディア タイプを列挙する方法については、「メディア タイプ接続の確立」を参照すること。GetStreamCaps は、オーディオやビデオに許された各種フォーマットに関する情報を返す。またここでは、フィルタが特定の出力を生成できるように変換フィルタの入力ピンを再接続するためのコード例を示す。

GetStreamCaps メソッドは、メディア タイプ構造体と能力構造体のペアを要素とする配列を返す。メディア タイプは AM_MEDIA_TYPE 構造体で、能力は AUDIO_STREAM_CONFIG_CAPS 構造体または VIDEO_STREAM_CONFIG_CAPS 構造体で表される。ここでは最初にビデオの例を示し、次にオーディオの例を示す。

このトピックは、以下のセクションを含んでいる。

  • ビデオ能力
  • オーディオ能力
  • 特定の出力タイプを保証するために入力を再接続する

ビデオ能力

IAMStreamConfig::GetStreamCaps メソッドは、AM_MEDIA_TYPE 構造体と VIDEO_STREAM_CONFIG_CAPS 構造体のペアの配列でビデオ能力を示す。以下に説明するように、このメソッドを使用すると、ピンでサポートされているすべてのフォーマットと解像度を公開することができる。

GetStreamCaps のオーディオ関連の例については、「オーディオ能力」を参照すること。

使用しているキャプチャ カードが、160 × 120 ピクセルから 320 × 240 ピクセルの間のすべての解像度で JPEG フォーマットをサポートしているとする。この場合、サポートされている解像度間の違いは 1 である。なぜなら、サポートされている各解像度に対して 1 ピクセル加算または減算することによって、次のサポートされている解像度を得ているからである。サポートされている解像度間におけるこの差は、細分度と呼ばれる。

カードが 640 × 480 のサイズもサポートしているとする。以下の図に、この単独の解像度と、上記の解像度範囲 (160 × 120 ピクセルから 320 × 240 ピクセルまでの範囲のすべての解像度) を示す。

160 × 120 ピクセルから 320 × 240 ピクセルまでの範囲のすべてのサイズ、および 640 × 480 での JPEG サポート

さらに、細分度が 8 で 160 × 120 から 320 × 240 までの範囲の解像度で 24 ビット カラーの RGB フォーマットをサポートしているとする。以下の図に、この場合の有効サイズのいくつかを示す。

細分度が 8 で 160 × 120 から 320 × 240 までの範囲のサイズでの RGB サポート

具体的には、有効な解像度として以下の解像度がある。

  • 160 × 120
  • 168 × 120
  • 168 × 128
  • 176 × 128
  • 176 × 136
  • ... 中略 ...
  • 312 × 232
  • 320 × 240

GetStreamCaps を使用して、最小能力 160 × 120、最大能力 320 × 240、細分度 1 を組み合わせた 320 × 240 JPEG (これがデフォルトまたは希望サイズの場合) のメディア タイプを提供することによって、これらのカラー フォーマットおよびディメンジョン能力を公開する。GetStreamCaps を使って次に公開するペアは、最小能力 640 × 480、最大能力 640 × 480、細分度 0 を組み合わせた 640 × 480 JPEG のメディア タイプとなる。3 番目のペアは、最小能力 160 × 120、最大能力 320 × 240、細分度 8 を持つ、 320 × 240 の 24 ビット RGB のメディア タイプである。このように、カードがサポートするほとんどすべてのフォーマットおよび能力を公開することができる。どのような圧縮フォーマットが提供されるかを知らなければならないアプリケーションは、すべてのペアを取得して、メディア タイプの一意なサブタイプのリストを作成することができる。

フィルタは、 VIDEOINFOHEADER 構造体の rcSource および rcTarget メンバからメディア タイプの転送元矩形および転送先矩形をそれぞれ取得する。フィルタは、転送元矩形および転送先矩形をサポートする必要はない。

IAMStreamConfig の解説で説明したクロッピング矩形は、出力ピンの VIDEOINFOHEADER 構造体の rcSource 矩形と同じである。

IAMStreamConfig の解説で説明した出力矩形は、出力ピンの BITMAPINFOHEADER 構造体の biWidth および biHeight メンバと同じである。

フィルタの出力ピンが、空でない転送元矩形および転送先矩形を持つメディア タイプに接続されている場合、フィルタは、入力フォーマットの転送元サブ矩形を出力フォーマットの転送先サブ矩形に伸縮する必要がある。転送元サブ矩形は、VIDEO_STREAM_CONFIG_CAPS 構造体の InputSize メンバに格納される。

たとえば、以下のようなビデオ コンプレッサ シナリオを考えてみよう。入力イメージは RGB フォーマットで、160 × 120 ピクセルのサイズを持つ。転送元矩形の左上隅の座標は (20,20) で、その右下隅の座標は (30,30) である。出力イメージは、サイズが 320 × 240 の MPEG フォーマットである。転送先矩形の左上隅の座標は (0,0) で、その右下隅の座標は (100,100) である。この場合、フィルタは、160 × 120 RGB の転送元ビットマップの 10 × 10 部分を取り出して、それを 320 × 240 のビットマップの最初の 100 × 100 領域に埋め、320 × 240 ビットマップの残りの領域はそのままにしておかなければならない。以下の図にこの操作を示す。

フィルタがこのような操作をサポートしていない場合、rcSource と rcTarget が空でないメディア タイプへの接続は失敗する。

VIDEOINFOHEADER 構造体は、フィルタのデータ レート能力に関する情報を公開する。たとえば、あるメディア タイプを持つ次のフィルタに (直接的に、または CMediaType::SetFormat 関数から渡されたメディア タイプを使用して) 出力ピンを接続したとする。そのメディア タイプの VIDEOINFOHEADER フォーマット構造体の dwBitRate メンバを見ると、ビデオの圧縮に使用すべきデータ レートがわかる。VIDEOINFOHEADER 構造体の AvgTimePerFrame メンバ内のフレームあたりのタイム単位数に dwBitRate メンバ内のデータ レートを掛け、その結果を 10,000,000 (1 秒あたりの単位数) で割ると、フレームあたりのバイト数を求めることができる。小さなサイズのフレームを生成することはできるが、大きなサイズのフレームは生成できない。ビデオ コンプレッサまたはキャプチャ フィルタのフレーム レートを求めるには、出力ピンのメディア タイプの AvgTimePerFrame を使用する。

オーディオ能力

オーディオ能力に関して、IAMStreamConfig::GetStreamCaps は AM_MEDIA_TYPE 構造体と AUDIO_STREAM_CONFIG_CAPS 構造体のペアの配列を返す。ビデオの場合と同様に、これを使用してピンのすべての種類のオーディオ能力 (たとえばデータ レートやモノラルまたはステレオのサポートの有無) を公開することができる。

GetStreamCaps のビデオ関連の例については、「ビデオ能力」を参照すること。

毎秒 11,025、22,050、および 44,100 サンプルのサンプリング レート、8 ビットまたは 16 ビット モノラルまたはステレオの PCM (pulse code modulation) wave フォーマット (Microsoft® Win32® PCMWAVEFORMAT 構造体で示される) をサポートする場合を考えてみる。この場合、2 つの構造体ペアを提供する。1 番目のペアは、AUDIO_STREAM_CONFIG_CAPS 能力構造体を持ち、毎秒 11,025 サンプルの細分度 (細分度は、サポートされている値の差) で 1 秒あたり最小 11,025 ～ 最大 22,050 サンプル、1 サンプルあたり 8 ビットの細分度で 1 サンプルあたり最小 8 ～ 最大 16 ビット、最小 1 チャンネル、最大 2 チャンネルをサポートすることを示す。1 番目のペアのメディア タイプは、その範囲内のデフォルト PCM フォーマットとなり、22kHz、16 ビット ステレオとなる。2 番目のペアは、1 秒あたりの最小および最大サンプル数が 44,100、1 サンプルあたり 8 ビットの細分度で 1 サンプルあたり 8 ビット (最小) および 16 ビット (最大)、最小 1 チャンネル、最大 2 チャンネルを表す。このメディア タイプは、デフォルトの 44kHz フォーマットとなり、44kHz 16 ビット ステレオとなる。

非 PCM wave フォーマットをサポートする場合、このメソッドから返されるメディア タイプは、サポートする非 PCM フォーマット (デフォルトのサンプリング レート、ビット レート、およびチャンネル) を示し、そのメディア タイプに伴う能力構造体は、サポートするサンプリング レート、ビット レート、およびチャンネルを示す。

特定の出力タイプを保証するために入力を再接続する

フィルタは、ピンが接続される前にオーディオまたはビデオ ストリームのフォーマットを設定するために、IAMStreamConfig::SetFormat メソッドを実装する。また、出力ピンが既に接続されていて新しいタイプを提供できる場合は、ピンを再接続する。フィルタが接続されている先のピンがメディア タイプを使用できない場合、この呼び出しは失敗し、接続はそのままになる。

ピンがどのような出力タイプを提供するかわからない変換フィルタは、入力ピンが接続されるまで、すべての SetFormat 呼び出しおよび IAMStreamConfig::GetStreamCaps 呼び出しをエラー コード VFW_E_NOT_CONNECTED で拒否しなければならない。

入力が接続されていなくても、ピンが提供できるタイプがわかっている場合は、通常どおりにタイプを提示したり受け付けることができる。詳細については、「変換フィルタの接続」を参照すること。

場合によっては、確立済みの接続に対してフォーマットを提示するときにピンを再接続した方が便利なこともある。たとえば、24 ビットの RGB 入力があるときだけビデオをフォーマット X に圧縮できる一方で、8 ビット RGB 入力を圧縮フォーマット Y に圧縮できる場合、次の選択肢がある。

  1. GetStreamCaps および SetFormat を使用して常に X と Y の両方を提示および受け付ける。
  2. 入力が 24 として接続された場合だけフォーマット X を提示し、入力が 8 として接続された場合だけフォーマット Y を提示する。入力が接続されていない場合は、GetStreamCaps および SetFormat の両方を失敗させる。

どちらの方法を選んだとしても、次のような再接続を行うコードが必要になる。

// 手の込んだ再接続を行うためのオーバーライド。
//
HRESULT MyOutputPin::CheckMediaType(const CMediaType *pmtOut)
{
HRESULT hr;
    CMediaType *pmtEnum;
    BOOL fFound = FALSE;
    IEnumMediaTypes *pEnum;

    if (!m_pFilter->m_pInput->IsConnected()) {
return VFW_E_NOT_CONNECTED;
    }

    // メディア タイプが不正ではないことをすばやくチェックする。
    //

    // SetFormat があらかじめ呼び出されている場合、メディア タイプが一致
    // しなければこの呼び出しを失敗させる。

    // 通常どおりにこの出力タイプを受け付ける。特別な操作は必要ない。
    hr = m_pFilter->CheckTransform(&m_pFilter->m_pInput->CurrentMediaType(),
        pmtOut);
if (hr == NOERROR)
return hr;

    DbgLog((LOG_TRACE,3,TEXT("Can't accept this output media type")));
    DbgLog((LOG_TRACE,3,TEXT(" But how about reconnecting the input...")));

    // 入力ピンを再接続して、使用可能なタイプを探す。
    // 入力ピンに接続されるピンにより、必要なタイプに変換可能な
    // タイプがわかる場合もある。
    hr = m_pFilter->m_pInput->GetConnected()->EnumMediaTypes(&pEnum);
if (hr != NOERROR)
        return E_FAIL;
    while (1) {
        hr = pEnum->Next(1, (AM_MEDIA_TYPE **)&pmtEnum, &j);

    // すべて列挙型から。
    if (hr == S_FALSE || j == 0) {
break;
    }

    // ピンはこれらのタイプ間で変換を行えるか?
    hr = m_pFilter->CheckTransform(pmtEnum, pmtOut);

if (hr != NOERROR) {
DeleteMediaType(pmtEnum);
continue;
    }

    // OK。使用可能なタイプが提示された。いますぐ受け入れるか?
    hr = m_pFilter->m_pInput->GetConnected()->QueryAccept(pmtEnum);
    // No。
if (hr != NOERROR) {
DeleteMediaType(pmtEnum);
continue;
    }
    // OK。
    fFound = TRUE;
    DbgLog((LOG_TRACE,2,TEXT("This output type is only acceptable after
                                reconnecting the input.")));

    // すべて完了。
DeleteMediaType(pmtEnum);
break;
    }
    pEnum->Release();

    if (!fFound)
        DbgLog((LOG_TRACE,3,TEXT("*NO! Reconnecting the input won't help")));

    return fFound ? NOERROR : VFW_E_INVALIDMEDIATYPE;
}

HRESULT MyOutputPin::SetFormat(AM_MEDIA_TYPE *pmt)
{
HRESULT hr;
    LPWAVEFORMATEX lpwfx;
    DWORD dwSize;

    if (pmt == NULL)
return E_POINTER;

    // ストリーミングが開始/停止の途中でないことを確認する。
    CAutoLock cObjectLock(&m_pFilter->m_csFilter);

    if (m_pFilter->m_State != State_Stopped)
    return VFW_E_NOT_STOPPED;

    // 可能な出力フォーマットは入力フォーマットに依存する。
    if (!m_pFilter->m_pInput->IsConnected())
return VFW_E_NOT_CONNECTED;

    // このフォーマットは既に使用している。
    if (IsConnected() && CurrentMediaType() == *pmt)
return NOERROR;

    // このタイプが使用可能かどうかを調べる。
    if ((hr = CheckMediaType((CMediaType *)pmt)) != NOERROR) {
    DbgLog((LOG_TRACE,2,TEXT("IAMStreamConfig::SetFormat rejected")));
return hr;
    }

    // 別のフィルタに接続する場合は、そのフィルタが当該タイプを受け付けるか確認する。
    if (IsConnected()) {
    hr = GetConnected()->QueryAccept(pmt);
if (hr != NOERROR)
        return VFW_E_INVALIDMEDIATYPE;
    }

    // 以降、これが唯一許されるフォーマットであり、これ以外の
    // フォーマットは上記の CheckMediaType コードで拒否することに注意。

    // フォーマットの変更は、必要に応じて再接続することを意味する。
    if (IsConnected())
        m_pFilter->m_pGraph->Reconnect(this);

return NOERROR;
}

// 手の込んだ再接続を完了するためにオーバーライド。
//
HRESULT MyWrapper::SetMediaType(PIN_DIRECTION direction,const CMediaType *pmt)
{
HRESULT hr;

    // OUTPUT タイプを設定する。
    if (direction == PINDIR_OUTPUT) {

    // 手の込んだ再接続の一部として、入力ピンは、
    // 別のタイプに再接続せずには提供できないメディア タイプを
    // 提供するように要求される。
    if (m_pInput && m_pInput->IsConnected()) {

        // ピンがこのタイプを今実際に提供できる場合は問題ない。
            hr = CheckTransform(&m_pInput->CurrentMediaType(),
                    &m_pOutput->CurrentMediaType());
if (hr == NOERROR)
return hr;

                DbgLog((LOG_TRACE,2,TEXT("*Set OUTPUT requires RECONNECT of INPUT!")));

        // 入力ピンを再接続する。
        return m_pGraph->Reconnect(m_pInput);

    }

return NOERROR;
    }

return NOERROR;
}


フィルタのカテゴリ

Microsoft® DirectX® SDK に付属の GraphEdit サンプル ツールを使用して、[Graph] メニューから [Insert Filters] を選択すると、システム上の Microsoft® DirectShow® フィルタがいくつかのカテゴリに分類されていることがわかる。DirectShow フィルタ カテゴリは、ほとんどのフィルタが含まれる全般的なカテゴリである。新しいフィルタはデフォルトでこのカテゴリに登録される。GraphEdit では、空のカテゴリは表示されない。

ただし、フィルタが以下のいずれかの種類である場合は、フィルタがそれぞれ適切なカテゴリに表示されるようにする必要がある。

  • オーディオ キャプチャ ソース—外部デバイスからオーディオ データを生成する。
  • オーディオ コンプレッサ—PCM オーディオを圧縮する。
  • オーディオ レンダラ—ローカルのスピーカ セットでオーディオ データを再生する。
  • エスクターナル レンダラ—外部周辺機器 (1394 DV カメラなど) にデータを送信する。
  • デバイス コントロール—ビデオ テープ マシン (1394 DV カメラなど) のトランスポートを制御する。
  • MIDI レンダラ—ローカルのスピーカ セットで MIDI データを再生する。
  • ビデオ キャプチャ ソース—外部デバイスからビデオ データを生成する。
  • ビデオ コンプレッサ—RGB ビデオを圧縮ビデオに変換する。

フィルタをカテゴリ別に登録する方法については、AMovieDllRegisterServer2 関数のトピックを参照すること。このトピックには、ビデオ コンプレッサ フィルタを登録するためのサンプル コードが含まれている。詳細については、「DirectShow オブジェクトの登録方法」を参照すること。


ファイル フォーマット

このセクションでは、Microsoft® DirectShow® で使用される各種ファイルのファイル フォーマットについて説明する。

  • AVI ファイル フォーマットの DV データ
  • カスタム ファイル タイプの登録


AVI ファイル フォーマットの DV データ

Microsoft はデジタル ビデオ (DV) データを AVI ファイルに保存するためのフォーマットを指定している。この仕様に従うことで、このフォーマットで作成された AVI ファイルは Microsoft® Windows® プラットフォーム用の Microsoft® DirectShow® デジタル ビデオ アーキテクチャの将来のバージョンに対して互換性を持つことが保証される。

このトピックでは、DV オーディオおよびビデオ データを含む AVI (Audio-Video Interleaved) ファイルのフォーマットを理解するための背景情報を提供する。また、他のプラットフォーム上で DV-AVI ファイルを使用するプログラマのための情報も提供する。AVI ファイルを読み書きするアプリケーションは、ファイル ソース (Async) フィルタと AVI スプリッタ フィルタ、および AVI Mux フィルタと ファイル ライタ フィルタ、そして DirectShow アーキテクチャで提供される関連インターフェイスを使用する。それにより、それらのサービスを実行するためのルーチンを開発しなくて済む。これらのフィルタは、AVI ファイルにアクセスするためのプログラミング上の要件を単純化する。

ここではさらに、DV データを含む AVI ファイルのフォーマットについても説明する。インターリーブされた DV データ ストリームおよび DV コンプレッサ/デコンプレッサ ストリーム ハンドラ用の特定の FOURCC (4 文字コード) を定義し、DV データのストリーム フォーマット構造体を定義する。また、AVI ファイル フォーマットに DV データを格納するための 2 つの方法の仕様についても説明する。

このトピックは、読者が DV データ フォーマットについてある程度理解していることを前提として書かれている。(このフォーマットについては、『Specification of Consumer-use Digital VCRs』に定義されている。この文書は Blue Book とも呼ばれる。)

このトピックは、以下のセクションを含んでいる。

  • DV AVI ファイルのタイプ
  • AVI RIFF ファイルのリファレンス
  • AVI 2.0 ファイル フォーマット拡張

RIFF (Resource Interchange File Format) ファイルの詳細については、Windows Software Development Kit (SDK) の 『Multimedia Programmer's Guide』と『Multimedia Programmer's Reference』を参照すること。

AVI ファイルの詳細については、Microsoft Video for Windows Development Kit バージョン 1.1 の『Programmer's Guide』第 6 章、および『OpenDML AVI File Format Extensions』(OpenDML AVI M-JPEG File Format Subcommittee 編、1996 年 2 月 28 日) のバージョン 1.02 を参照すること。

コンプレッサおよびデコンプレッサの詳細については、MSDN ライブラリにある Windows DDK Documentation の「Video Compression and Decompression Drivers」セクションを参照すること。

DV AVI ファイルのタイプ

DV AVI ファイルには次の 2 つのタイプがある。

  • 1 つの DV データ ストリームを含む AVI ファイル
  • DV ビデオを 'vids' ストリームとして含み DV オーディオを 'auds' ストリームとして含む AVI ファイル

1 つの DV データ ストリームを含む AVI ファイル

インターリーブされた DV データは、AVI RIFF ファイル内に 1 つのストリームとしてそのネイティブ フォーマットで格納できる。この方法には、DV に対して使用するデータ格納領域の量が最小限で済むという利点がある。主な欠点としては、このファイル フォーマットにはビデオ 'vids' ストリームもオーディオ 'auds' ストリームも含まれないため、Video for Windows に対する後方互換性を持たないことが挙げられる。インターリーブされた DV ストリームのサポートは、DirectShow の DV Muxer および DV スプリッタ フィルタによって提供される。

DV データを AVI RIFF ファイル内に 1 つのストリームとして格納するには、'strh' ストリーム ヘッダー チャンクの fccType メンバに 'iavs' (interleaved audio and video stream) FOURCC (four-character code : 4 文字コード) を指定し、fccHandler メンバに 'dvsd'、'dvhd'、'dvsl' のいずれかの FOURCC を指定する。ビデオ ストリームの毎秒のフレーム数を dwRate および dwScale メンバに指定し、'movi' チャンク内のビデオ ブロックの総数を dwLength メンバに指定する。

'dvsd' ストリーム ハンドラ FOURCC は、DV データが『Specification of Consumer-use Digital VCRs』の Part 2 に従っていることを指定する。ビデオのフォーマットは 525 ライン、29.97 Hz (525-60) か、または 625 ライン、25.00 Hz (625-50) である。

'dvhd' ストリーム ハンドラ FOURCC は、DV データが『Specification of Consumer-use Digital VCRs』の Part 3 に従っていることを指定する。ビデオのフォーマットは 1125 ライン、30.00 Hz (1125-60) か、または 1250 ライン、25.00 Hz (1250-50) である。

'dvsl' ストリーム ハンドラ FOURCC は、DV データが『Specification of Consumer-use Digital VCRs』の Part 6 に従っていることを指定する。ビデオのフォーマットは高圧縮 SD (SDL) である。

注 : このトピックの以降の部分では、'dvsd' ストリームの定義を提供する。

ストリーム ヘッダー チャンクの後には、DVINFO ストリーム フォーマット チャンクが続く。DVINFO ストリーム フォーマットに対しては、以下のデータ構造体が定義される。

typedef struct tag_DVINFO {
    DWORD dwDVAAuxSrc;
    DWORD dwDVAAuxCtl;
    DWORD dwDVAAuxSrc1;
    DWORD dwDVAAuxCtl1;
    DWORD dwDVVAuxSrc;
    DWORD dwDVVAuxCtl;
    DWORD dwDVReserved[2];
} DVINFO, *PDVINFO;
dwDVAAuxSrc
フレームの最初のオーディオ ブロック (525-60 システムでは最初の 5 つの DV DIF シーケンス、625-50 システムでは最初の 6 つの DV DIF シーケンス) に対する Audio Auxiliary Data Source Pack を指定する。DIF シーケンスは、150 個の DIF ブロックを含むデータ ブロックである。各 DIF ブロックには 80 バイトが含まれる。Audio Auxiliary Data Source Pack については、『Specification of Consumer-use Digital VCRs』の Part 2、Annex D「The Pack Header Table and Contents of Packs」のセクション D.7.1 に定義されている。
dwDVAAuxCtl
フレームの最初のオーディオ ブロックの Audio Auxiliary Data Source Control Pack を指定する。Audio Auxiliary Data Control Pack については、『Specification of Consumer-use Digital VCRs』の Part 2、Annex D「The Pack Header Table and Contents of Packs」のセクション D.7.2 に定義されている。
dwDVAAuxSrc1
フレームの 2 番目のオーディオ ブロック (525-60 システムでは 2 番目の 5 つの DV DIF シーケンス、625-50 システムでは 2 番目の 6 つの DV DIF シーケンス) に対する Audio Auxiliary Data Source Pack を指定する。
dwDVAAuxCtl1
フレームの 2 番目のオーディオ ブロックの Audio Auxiliary Data Source Control Pack を指定する。
dwDVVAuxSrc
『Specification of Consumer-use Digital VCRs』の Part 2、Annex D「The Pack Header Table and Contents of Packs」のセクション D.8.1 に定義されている Video Auxiliary Data Source Pack を指定する。
dwDVVAuxCtl
『Specification of Consumer-use Digital VCRs』の Part 2、Annex D「The Pack Header Table and Contents of Packs」のセクション D.8.2 に定義されている Video Auxiliary Data Source Control Pack を指定する。
DwDVReserved[2]
予約されている。この配列はゼロに設定する。

実際の DV データは 'movi' チャンク内の '##dc' チャンクとして格納される (## はストリーム識別子)。各チャンクには、1 フレームのデータが含まれる。これは 525-60 システムの場合は 10 個の DV DIF シーケンス、625-50 システムの場合は 12 個の DV DIF シーケンスである。DV SD ('dvsd') DIF シーケンス フォーマットについては、『Specification of Consumer-use Digital VCRs』の Part 2 で定義されている。

次の図に、1 つの DV データ ストリームを含む AVI ファイルを DirectShow フィルタ グラフを使用して再生する例を示す (DV スプリッタおよび DV ビデオ デコーダ フィルタは、特に DV データを扱うために DirectShow に用意されている)。下の表で、メディア タイプを定義する。

1 つの DV データ ストリームを含む AVI ファイルの再生
メディア | メジャー タイプ | サブタイプ | フォーマット構造体
A | MEDIATYPE_Stream | MEDIASUBTYPE_AVI | なし
B | MEDIATYPE_iavs | MEDIASUBTYPE_dvsd、MEDIASUBTYPE_dvhd、または MEDIASUBTYPE_dvsl | DVINFO
C | MEDIATYPE_VIDEO | MEDIASUBTYPE_dvsd、MEDIASUBTYPE_dvhd、または MEDIASUBTYPE_dvsl | DVINFO
D | MEDIATYPE_AUDIO | NULL | WAVEFORMATEX
E | MEDIATYPE_VIDEO | 標準ビデオ タイプ | VIDEOINFO

次の図に、1 つの DV データ ストリームを含む AVI ファイルを DirectShow フィルタ グラフを使用して作成する例を示す (DV ビデオ エンコーダ および DV Muxer フィルタは、特に DV データを扱うために DirectShow に用意されている)。メディア タイプは上の表に定義されている。アップストリーム フィルタは、ここには示されていないが、適切なメディア タイプ D および E を生成する任意の組み合わせを使用できる。

1 つの DV データ ストリームを含む AVI ファイルの作成

次の図に、1 つの DV データ ストリームを含む AVI ファイルを DirectShow フィルタ グラフを使用して作成する例を示す。ここでは、ハードウェア デバイス ドライバを通して DV デバイス (1394 ベースの DV カムコーダなど) と通信するソース フィルタを DV データ入力として使用している (このソース フィルタは、特に DV データを扱うために DirectShow に用意されている)。メディア タイプは上の表に定義されている。

1 つの DV データ ストリームを含む AVI ファイルへの DV キャプチャ

次の図に、1 つの DV データ ストリームを含む AVI ファイルを DirectShow フィルタ グラフを使用して出力する例を示す。ここでは、ハードウェア デバイス ドライバを通して DV デバイス (1394 ベースの DV カムコーダなど) と通信するシンク フィルタを DV データ出力として使用している (このシンク フィルタは、特に DV データを扱うために DirectShow に用意されている)。メディア タイプは上の表に定義されている。

1 つの DV データ ストリームを含む AVI ファイルの出力

次の例は、完全なヘッダー チャンクによって拡張された、1 つの DV データ ストリームを含む AVI ファイルの AIFF RIFF フォーマットを示す。

00000000 RIFF (0FAE35D4) 'AVI '
0000000C LIST (00000106) 'hdrl'
00000018 avih (00000038)
dwMicroSecPerFrame    : 33367
dwMaxBytesPerSec      : 3728000
dwPaddingGranularity  : 0
dwFlags               :0x810 HASINDEX | TRUSTCKTYPE
dwTotalFrames         : 2192
dwInitialFrames       : 0
dwStreams             : 1
dwSuggestedBufferSize : 120000
dwWidth               : 720
dwHeight              : 480
dwReserved            :0x0
00000058         LIST (0000006C) 'strl'
00000064             strh (00000038)
fccType               : 'iavs'
fccHandler            :'dvsd'
dwFlags               :0x0
wPriority             : 0
wLanguage             :0x0 undefined
dwInitialFrames       : 0
dwScale               :100 (29.970 Frames/Sec)
dwRate                : 2997
dwStart               : 0
dwLength              : 2192
dwSuggestedBufferSize : 120000
dwQuality             : 0
dwSampleSize          : 0
rcFrame               : 0,0,720,480
000000A4             strf (00000020)
dwDVAAuxSrc     :0x........
dwDVAAuxCtl     :0x........
dwDVAAuxSrc1    :0x........
dwDVAAuxCtl1    :0x........
dwDVVAuxSrc     :0x........
dwDVVAuxCtl     :0x........
dwDVReserved[2] : 0,0
000000CC     LIST (0FADAC00) 'movi'
0FADACD4     idx1 (00008900)

DV ビデオを 'vids' ストリームとして含み DV オーディオを 'auds' ストリームとして含む AVI ファイル

インターリーブされた DV データは、AVI RIFF ファイル内で 1 つのビデオ ストリームと 1 つから 4 つまでのオーディオ ストリームに分割することができる。このファイル フォーマットには標準ビデオ 'vids' ストリームと少なくとも 1 つの標準オーディオ 'auds' ストリームが含まれるため、Video for Windows に対して後方互換性を持つという利点がある。主な欠点は、このファイル フォーマットではオーディオ データをオーディオ ストリームとして冗長に格納しなければならないことである。"ビデオ" ストリームは、実際にはネイティブのインターリーブされた DV データ ストリームである。ただし、ハンドラ タイプ 'dvsd' の標準 'vids' ストリームとして、DV ビデオ デコーダが使用される。また、このフォーマットでは、"キャプチャされた" ファイルを AVI ファイルとして書き込む前に、DV スプリッタ フィルタを使用してファイルを分割する必要がある。

DV データは、1 つのビデオ ストリームと、別にいくつかのオーディオ ストリームとして AVI RIFF ファイルに格納できる。ビデオ ストリームは標準ビデオ ストリーム ヘッダー (fccType メンバ値が 'vids') によって指定される。fccHandler メンバは 'dvsd'、'dvhd'、または 'dvsl' として指定される。ビデオ ストリームの毎秒のフレーム数を dwRate および dwScale メンバに指定し、'movi' チャンク内のビデオ ブロックの総数を dwLength メンバに指定する。

このように DV ビデオを 'vids' ストリームとして含み DV オーディオを 'auds' ストリーム フォーマットの DV として含む AVI ファイルでは、ビデオ ストリーム フォーマット チャンクは標準の BITMAPINFOHEADER 構造体である。ストリーム フォーマット チャンクは、オプションで DVINFO 構造体を含むように拡張できる。その場合は、ストリーム フォーマット チャンクのサイズを 40 バイト (BITMAPINFOHEADER 構造体のサイズ) から 72 バイト (BITMAPINFOHEADER＋DVINFO 構造体のサイズ) に変更し、BITMAPINFOHEADER データ構造体の直後に DVINFO データ構造体を記述する。

オーディオ ストリームは標準オーディオ ストリーム ヘッダー (fccType メンバ値が 'auds') によって指定される。fccHandler メンバは、オーディオ ストリームでは使用しない。

DV ビデオ データは、前の「1 つの DV データ ストリームを含む AVI ファイル」で説明したとおり、'##dc' チャンクとして格納される。オーディオ データは、'##wb' チャンクとして 'movi' チャンクに格納される。

次の図に、DV ビデオを 'vids' ストリームとして含み DV オーディオを 'auds' ストリームとして含む AVI ファイルを DirectShow フィルタ グラフを使用して再生する例を示す (DV ビデオ デコーダ フィルタは、特に DV データを扱うために DirectShow に用意されている)。メディア タイプは、DV メディア タイプの表に定義されている。

DV ビデオを 'vids' ストリームとして含み DV オーディオを 'auds' ストリームとして含む AVI ファイルの再生

次の図に、DV ビデオを 'vids' ストリームとして含み DV オーディオを 'auds' ストリームとして含む AVI ファイルを DirectShow フィルタ グラフを使用して作成する例を示す (DV ビデオ デコーダは、特に DV データを扱うために DirectShow に用意されている)。メディア タイプは、DV メディア タイプの表に定義されている。アップストリーム フィルタは、ここには示されていないが、適切なメディア タイプ D および E を生成する任意の組み合わせを使用できる。

DV ビデオを 'vids' ストリームとして含み DV オーディオを 'auds' ストリームとして含む AVI ファイルの作成

次の図に、DV ビデオを 'vids' ストリームとして含み DV オーディオを 'auds' ストリームとして含む AVI ファイルを DirectShow フィルタ グラフを使用して作成する例を示す。ここでは、ハードウェア デバイス ドライバを通して DV デバイス (1394 ベースの DV カムコーダなど) と通信するソース フィルタを DV データ入力として使用している (このソース フィルタと DV スプリッタ フィルタは、特に DV データを扱うために DirectShow に用意されている)。メディア タイプは、DV メディア タイプの表に定義されている。

DV ビデオを 'vids' ストリームとして含み DV オーディオを 'auds' ストリームとして含む AVI ファイルへの DV キャプチャ

次の図に、DV ビデオを 'vids' ストリームとして含み DV オーディオを 'auds' ストリームとして含む AVI ファイルを DirectShow フィルタ グラフを使用して出力する例を示す。ここでは、ハードウェア デバイス ドライバを通して DV デバイス (1394 ベースの DV カムコーダなど) と通信するシンク フィルタを DV データ出力として使用している (このシンク フィルタと DV Muxer フィルタは、特に DV データを扱うために DirectShow に用意されている)。メディア タイプは、DV メディア タイプの表に定義されている。

DV ビデオを 'vids' ストリームとして含み DV オーディオを 'auds' ストリームとして含む AVI ファイルの出力

次の例は、完全なヘッダー チャンクによって拡張された、DV ビデオを 'vids' ストリームとして含み DV オーディオを 'auds' ストリームとして含む AVI ファイルの AIFF RIFF フォーマットを示す ('vids' ストリームの 'strf' サブチャンクにおいて、BITMAPINFO の後にオプションで DVINFO データが記述されている)。

00000000 RIFF (103E2920) 'AVI '
0000000C LIST (00000146) 'hdrl'
00000018 avih (00000038)
dwMicroSecPerFrame    : 33367
dwMaxBytesPerSec      : 3728000
dwPaddingGranularity  : 0
dwFlags               :0x810 HASINDEX | TRUSTCKTYPE
dwTotalFrames         : 2192
dwInitialFrames       : 0
dwStreams             : 2
dwSuggestedBufferSize : 120000
dwWidth               : 720
dwHeight              : 480
dwReserved            :0x0
00000058         LIST (00000094) 'strl'
00000064             strh (00000038)
fccType               :'vids'
fccHandler            :'dvsd'
dwFlags               :0x0
wPriority             : 0
wLanguage             :0x0 undefined
dwInitialFrames       : 0
dwScale               :100 (29.970 Frames/Sec)
dwRate                : 2997
dwStart               : 0
dwLength              : 2192
dwSuggestedBufferSize : 120000
dwQuality             : 0
dwSampleSize          : 0
rcFrame               : 0,0,720,480
000000A4             strf (00000048)
                         biSize          : 40
                         biWidth         : 720
                         biHeight        : 480
                         biPlanes        : 1
                         biBitCount      : 24
                         biCompression   : 0x64737664 'dvsd'
                         biSizeImage     : 120000
                         biXPelsPerMeter : 0
                         biYPelsPerMeter : 0
                         biClrUsed       : 0
                         biClrImportant  : 0
dwDVAAuxSrc     :0x........
dwDVAAuxCtl     :0x........
dwDVAAuxSrc1    :0x........
dwDVAAuxCtl1    :0x........
dwDVVAuxSrc     :0x........
dwDVVAuxCtl     :0x........
dwDVReserved[2] : 0,0
000000F4         LIST (0000005E) 'strl'
00000100             strh (00000038)
fccType               :'auds'
fccHandler            : '    '
dwFlags               :0x0
wPriority             : 0
wLanguage             :0x0 undefined
dwInitialFrames       : 0
dwScale               : 1 (32000.000 Samples/Sec)
dwRate                : 32000
dwStart               : 0
dwLength              : 2340474
dwSuggestedBufferSize : 4272
dwQuality             : 0
dwSampleSize          : 4
rcFrame               : 0,0,0,0
00000140             strf (00000012)
                         wFormatTag      : 1 PCM
                         nChannels       : 2
                         nSamplesPerSec  : 32000
                         nAvgBytesPerSec : 128000
                         nBlockAlign     : 4
                         wBitsPerSample  : 16
                         cbSize          : 0
00000814     LIST (103D0EF4) 'movi'
103D1710     idx1 (00011210)

AVI RIFF ファイルのリファレンス

Microsoft AVI ファイル フォーマットは、オーディオ/ビデオ シーケンスのキャプチャ、編集、再生を行うアプリケーションで使用される RIFF ファイル仕様である。一般に、AVI ファイルには異なる種類のデータのストリームが複数含まれる。ほとんどの AVI シーケンスは、オーディオ ストリームとビデオ ストリームの両方を使用する。単純な AVI シーケンスでは、ビデオ データのみを使用し、オーディオ ストリームは必要としない。

元々の AVI ファイル仕様に対して OpenDML AVI File Format Extensions で加えられた変更については、このセクションでは取り上げない。詳細については、『OpenDML AVI File Format Extensions』(OpenDML AVI M-JPEG File Format Subcommittee 編、1996 年 2 月 28 日) のバージョン 1.02 を参照すること。

このセクションには、以下の内容が含まれる。

  • AVI RIFF フォーマット
  • AVI メイン ヘッダー
  • AVI ストリーム ヘッダー
  • ストリーム データ (LIST 'movi' チャンク)
  • BITMAPINFOHEADER 構造体
  • WAVEFORMATEX 構造体

AVI RIFF フォーマット

AVI ファイルは、AVI RIFF フォーマットを使用する。AVI RIFF フォーマットは、FOURCC (4 文字コード) 'AVI ' によって識別される。すべての AVI ファイルには、2 つの必須の LIST チャンクが含まれる。これらのチャンクは、ストリームとストリーム データのフォーマットを定義する。AVI ファイルには、インデックス チャンクが含まれる場合もある。このオプションのチャンクは、ファイル内でのデータ チャンクの位置を指定する。これらの要素を含んだ AVI ファイルは、次のようなフォーマットを持つ。

RIFF ('AVI '
LIST ('hdrl'
              .
              .
              .
           )
LIST ('movi'
              .
              .
              .
           )
['idx1'<AVI Index>]
     )

LIST チャンクとインデックス チャンクは、RIFF 'AVI ' チャンクのサブチャンクである。'AVI ' チャンクは、ファイルが AVI RIFF ファイルであることを示す。LIST 'hdrl' チャンクはデータのフォーマットを定義し、これは最初の必須 LIST チャンクである。LIST 'movi' チャンクは AVI シーケンスのデータを含み、これは 2 番目の必須チャンクである。'idx1' チャンクはインデックス チャンクである。AVI ファイルには、この 3 つのコンポーネントを適切な順序で含む必要がある。

LIST 'hdrl' および LIST 'movi' チャンクは、そのデータに対してサブチャンクを使用する。次の例に、LIST 'hdrl' および LIST 'movi' チャンクを完成させるのに必要なチャンクを追加した AVI RIFF フォーマットを示す。

RIFF ('AVI '
LIST ('hdrl'
            'avih'(<Main AVI Header>)
            LIST ('strl'
                  'strh'(<Stream header>)
                  'strf'(<Stream format>)
                  'strd'(<additional header data>)
                  'strn'(<Stream name>)
                  ...
                 )
             .
             .
             .
           )

LIST ('movi'
            {SubChunk | LIST ('rec '
                              SubChunk1
                              SubChunk2
                                .
                                .
                                .
                             )
               .
               .
               .
            }
            .
            .
            .
           )

['idx1'<AVI Index>]
     )

AVI メイン ヘッダー

以降のセクションでは、LIST 'hdrl' および LIST 'movi' チャンクに含まれるチャンクについて説明する。'idx1' チャンクについては、このドキュメントでは説明しない。AVI ファイルの 'idx1' チャンクおよびインデックスの詳細については、『OpenDML AVI File Format Extensions』(OpenDML AVI M-JPEG File Format Subcommittee 編、1996 年 2 月 28 日) のバージョン 1.02 を参照すること。

ファイルはメイン ヘッダーで始まる。AVI ファイルの場合、このヘッダーは 'avih' という FOURCC (4 文字コード) で示される。ヘッダーには、ファイル内のストリーム数、AVI シーケンスの幅と高さなど、AVI ファイル全体に関するグローバル情報が含まれる。AVI メイン ヘッダー構造体は、次のように定義される。

typedef struct {
    DWORD dwMicroSecPerFrame;
    DWORD dwMaxBytesPerSec;
    DWORD dwReserved1;
    DWORD dwFlags;
    DWORD dwTotalFrames;
    DWORD dwInitialFrames;
    DWORD dwStreams;
    DWORD dwSuggestedBufferSize;
    DWORD dwWidth;
    DWORD dwHeight;
    DWORD dwReserved[4];
} MainAVIHeader;
dwMicroSecPerFrame
フレーム間の間隔をマイクロ秒単位で指定する。この値はファイルの全体のタイミングを示す。
dwMaxBytesPerSec
ファイルの概算最大データ レートを指定する。この値は、メイン ヘッダーおよびストリーム ヘッダー チャンクに含まれる他のパラメータに従って AVI シーケンスを表示するために、システムが処理しなければならない毎秒のバイト数を示す。
dwReserved1
予約されている。ゼロに設定すること。
dwFlags
ファイルに対するフラグを含む。以下のフラグが定義されている。
AVIF_HASINDEX | AVI ファイルの終わりにインデックスを含む 'idx1' チャンクがあることを示す。良好なパフォーマンスのためには、すべての AVI ファイルがインデックスを含む必要がある。
AVIF_MUSTUSEINDEX | データのプレゼンテーションの順序を決定するために、ファイル内のチャンクの物理的な順序ではなく、インデックスを使用することを示す。たとえば、これを使ってフレームのリストを作成して編集することができる。
AVIF_ISINTERLEAVED | AVI ファイルがインターリーブされていることを示す。
AVIF_WASCAPTUREFILE | AVI ファイルが、リアルタイム ビデオのキャプチャ用に特別に割り当てられたファイルであることを示す。アプリケーションは、このフラグが設定されたファイルをオーバーライドする前に、ユーザーに警告を発する必要がある。これは、ユーザーがこのファイルをデフラグメントしている可能性が高いからである。
AVIF_COPYRIGHTED | AVI ファイルに著作権のあるデータおよびソフトウェアが含まれていることを示す。このフラグが使用されている場合、ソフトウェアはデータの複製を許可すべきではない。
dwTotalFrames
ファイル内のデータのフレームの総数を指定する。
dwInitialFrames
インターリーブされたファイルの開始フレームを指定する。インターリーブされたファイル以外では、ゼロを指定する。インターリーブされたファイルを作成する場合、ファイル内で AVI シーケンスの開始フレームより前にあるフレーム数を、このメンバに指定する。このメンバの内容に関する詳細については、『Video for Windows Programmer's Guide』の「Special Information for Interleaved Files」を参照すること。
dwStreams
ファイル内のストリーム数を指定する。たとえば、オーディオとビデオを含むファイルには 2 つのストリームがある。
dwSuggestedBufferSize
ファイルを読み取るためのバッファ サイズを指定する。一般に、このサイズはファイル内の最大のチャンクを格納するのに十分な大きさにする。ゼロに設定したり、小さすぎる値に設定した場合、再生ソフトウェアは再生中にメモリを再割り当てしなければならず、パフォーマンスが低下する。インターリーブされたファイルの場合、バッファ サイズはチャンクではなくレコード全体を読み取るのに十分な大きさでなければならない。
dwWidth
AVI ファイルの幅をピクセル単位で指定する。
dwHeight
AVI ファイルの高さをピクセル単位で指定する。
dwReserved[4]
予約されている。この配列はゼロに設定する。

AVI ストリーム ヘッダー

メイン ヘッダーの次には、1 つ以上の 'strl' チャンクが続く ('strl' チャンクは各データ ストリームごとに必要である)。これらのチャンクには、ファイル内のストリームに関する情報が含まれる。各 'strl' チャンクには、ストリーム ヘッダー チャンクとストリーム フォーマット チャンクが必ず含まれる。ストリーム ヘッダー チャンクは、FOURCC (4 文字コード) 'strh' で示され、ストリーム フォーマット チャンクは、FOURCC 'strf' で示される。ストリーム ヘッダー チャンクとストリーム フォーマット チャンクに加えて、'strl' チャンクにはストリーム ヘッダー データ チャンクとストリーム名チャンクが含まれる場合がある。ストリーム ヘッダー データ チャンクは FOURCC 'strd' で示される。ストリーム名チャンクは FOURCC 'strn' で示される。

ストリーム ヘッダー構造体には、ファイル内の単一のストリームに対するヘッダー情報が含まれる。

typedef struct {
    FOURCC fccType;
    FOURCC fccHandler;
    DWORD dwFlags;
    DWORD  dwPriority;
    DWORD dwInitialFrames;
    DWORD  dwScale;
    DWORD  dwRate;
    DWORD  dwStart;
    DWORD  dwLength;
    DWORD dwSuggestedBufferSize;
    DWORD  dwQuality;
    DWORD  dwSampleSize;
    RECT   rcFrame;
} AVIStreamHeader;

ストリーム ヘッダーは、FOURCC を使用して、ストリームに含まれるデータのタイプ (オーディオ、ビデオなど) を指定する。

fccType
ストリームに含まれるデータのタイプを指定する FOURCC を含む。ビデオおよびオーディオに対して以下の標準 AVI 値が定義されている。
'vids' | ストリームにビデオ データが含まれることを示す。ストリーム フォーマット チャンクには、パレット情報を含むことが可能な BITMAPINFO 構造体が含まれる。
'auds' | ストリームにオーディオ データが含まれることを示す。ストリーム フォーマット チャンクには、WAVEFORMATEX または PCMWAVEFORMAT 構造体が含まれる。
'txts' | ストリームにテキスト データが含まれることを示す。
fccHandler
特定のデータ ハンドラを示す FOURCC を含む (オプション)。データ ハンドラは、ストリームに対して適切なハンドラである。オーディオおよびビデオ ストリームの場合は、インストール可能なコンプレッサまたはデコンプレッサを指定する。
dwFlags
データ ストリームに対するフラグを含む。これらのフラグの上位ワードのビットは、ストリームに含まれるデータのタイプに固有である。以下の標準フラグが定義されている。
AVISF_DISABLED | このストリームをデフォルトで有効にしないことを示す。
AVISF_VIDEO_PALCHANGES | このビデオ ストリームにパレットの変更が含まれることを示す。このフラグは、再生ソフトウェアに対して、パレットをアニメーションする必要があることを警告する。
dwPriority
ストリーム タイプの優先順位を指定する。たとえば、複数のオーディオ ストリームを含むファイルでは、優先順位の最も高いストリームがデフォルトのストリームになる。
dwInitialFrames
インターリーブされたファイルで、オーディオ データがビデオ フレームからどのくらいスキューされているかを指定する。通常は、約 0.75 秒である。インターリーブされたファイルを作成する場合、ファイル内で AVI シーケンスの開始フレームより前にあるフレーム数を、このメンバに指定する。このメンバの内容に関する詳細については、『Video for Windows Programmer's Guide』の「Special Information for Interleaved Files」を参照すること。
dwScale
dwRate とともに使用して、このストリームが使用するタイム スケールを指定する。dwRate を dwScale で割ることにより、1 秒あたりのサンプル数が求められる。ビデオ ストリームの場合、このレートはフレーム レートに等しくなる。オーディオ ストリームの場合、このレートは nBlockAlign バイトのオーディオ データに必要な時間に対応する。これは PCM オーディオの場合はサンプル レートに等しくなる。
dwRate
dwScale を参照すること。
dwStart
AVI ファイルの開始タイムを指定する。単位は、メイン ファイル ヘッダーの dwRate および dwScale メンバによって定義される。通常、これはゼロであるが、ファイルと同時に開始されないストリームに対しては、遅延時間を指定することができる。
dwLength
このストリームの長さを指定する。単位は、ストリームのヘッダーの dwRate および dwScale メンバによって定義される。
dwSuggestedBufferSize
このストリームを読み取るために必要なバッファの大きさを指定する。通常は、ストリーム内の最大のチャンクに対応する値である。正しいバッファ サイズを使用することで、再生の効率が高まる。正しいバッファ サイズがわからない場合は、ゼロを指定する。
dwQuality
ストリーム内のデータの品質を示す値を指定する。品質は、0 ～ 10,000 の範囲の値で示される。圧縮データの場合、これは通常、圧縮ソフトウェアに渡される品質パラメータの値を示す。–1 に設定した場合、ドライバはデフォルトの品質値を使用する。
dwSampleSize
データの 1 サンプルのサイズを指定する。サンプルのサイズが変化する場合は、ゼロに設定する。この値がゼロでない場合、ファイル内で複数のデータ サンプルを 1 つのチャンクにグループ化できる。ゼロの場合、各データ サンプル (ビデオ フレームなど) はそれぞれ別のチャンクに含まれなければならない。ビデオ ストリームの場合、この値は通常ゼロであるが、すべてのビデオ フレームが同じサイズであれば、ゼロ以外の値にもできる。オーディオ ストリームの場合、この値はオーディオを記述する WAVEFORMATEX 構造体の nBlockAlign メンバと同じでなければならない。
rcFrame
AVI メイン ヘッダー構造体の dwWidth および dwHeight メンバによって指定される動画矩形内のテキストまたはビデオ ストリームに対する転送先矩形を指定する。通常、rcFrame メンバは、複数のビデオ ストリームをサポートするために使用される。この矩形は、動画矩形に対応する座標に設定して、動画矩形全体を更新する。このメンバの単位はピクセルである。転送先矩形の左上隅は、動画矩形の左上隅からの相対指定となる。

最後の 8 つのメンバは、ストリームの再生特性を記述する。これらの要素には、再生レート (dwScale と dwRate)、シーケンスの開始タイム (dwStart)、シーケンスの長さ (dwLength)、再生バッファのサイズ (dwSuggestedBuffer)、データ 品質の指標 (dwQuality)、およびサンプル サイズ (dwSampleSize) が含まれる。

ストリーム ヘッダー構造体のメンバのいくつかは、メイン ヘッダー構造体にも含まれる。メイン ヘッダーのデータはファイル全体に適用され、ストリーム ヘッダーのデータはストリームにだけ適用される。

ストリーム ヘッダー ('strh') チャンクの次には、ストリーム フォーマット ('strf') チャンクが続く。ストリーム フォーマット チャンクは、ストリーム内のデータのフォーマットを記述する。ビデオ ストリームの場合、このチャンク内の情報は BITMAPINFO 構造体 (該当する場合はパレット情報を含む) である。オーディオ ストリームの場合、このチャンク内の情報は WAVEFORMATEX または PCMWAVEFORMAT 構造体である (WAVEFORMATEX 構造体は WAVEFORMAT 構造体の拡張版である)。この構造体および他のストリーム タイプの詳細については、『New Multimedia Data Types and Data Techniques Standards Update』を参照すること。

'strl' チャンクには、ストリーム ヘッダー データ ('strd') チャンクが追加される場合がある。このチャンクを使用する場合は、ストリーム フォーマット チャンクの後に記述する。このチャンクのフォーマットと内容は、インストール可能な圧縮または復元ドライバによって定義される。通常、これらのドライバはこの情報を使用して設定を行う。RIFF ファイルを読み書きするアプリケーションは、この情報をデコードする必要はない。アプリケーションはドライバとの間でこのデータをメモリ ブロックとして転送する。

オプションの 'strn' ストリーム名チャンクは、ストリームについて説明するゼロ終端文字列を提供する。(AVI ファイル関数でこのチャンクを使用することにより、アプリケーションはアクセスしたいストリームを名前で識別することができる。)

AVI プレーヤーは、'strl' チャンクの順序に基づいて、LIST 'hdrl' チャンク内のストリーム ヘッダーを LIST 'movi' チャンク内のストリーム データと関連付ける。最初の 'strl' チャンクはストリーム 0 に対応し、2 番目の 'strl' チャンクはストリーム 1 に対応し、以下同様に続く。

たとえば、最初の 'strl' チャンクが wave オーディオ データを記述する場合、その wave オーディオ データはストリーム 0 に含まれる。同様に、2 番目の 'strl' チャンクがビデオ データを記述する場合、そのビデオ データはストリーム 1 に含まれる。

ストリーム データ (LIST 'movi' チャンク)

ヘッダー情報の次に続くのは、ストリーム内の実際のデータ (画像やサウンドそれ自体) のチャンクを含む LIST 'movi' チャンクである。データ チャンクは、LIST 'movi' チャンク内に直接記述する場合と、'rec' チャンクにグループ化する場合がある。'rec' へのグループ化は、グループ化されたチャンクがディスクから一度に読み出されることを意味する。これは、CD-ROM から再生するために特別にインターリーブされたファイルの場合にだけ使用される。

すべての RIFF チャンクと同様に、データ チャンクにはチャンク タイプを識別する FOURCC (4 文字コード) が含まれる。FOURCC は、1 文字から 4 文字の ASCII 英数字のシーケンスで表される 32 ビット量である (右側は空白文字が埋められる)。各チャンクを識別する FOURCC は、ストリーム番号と、チャンク内にカプセル化された情報のタイプを定義する 2 文字のコードとで構成される。たとえば、波形チャンクは 2 文字コード 'wb' で示される。波形チャンクが 2 番目の LIST 'hdrl' ストリーム記述に対応している場合、FOURCC は '01wb' となる。

注 : 2 文字コードはストリームを記述するのに便利な方法だが、他のアプリケーションがそれを認識するとは限らない。ストリームを作成したり情報を他のアプリケーションに転送する場合には、FOURCC を使用すること。

フォーマット情報はすべてヘッダーに含まれるため、これらのデータ チャンク内のオーディオ データにフォーマットに関する情報を含めてはならない。オーディオ データ チャンクのフォーマットを次に示す (## はストリーム識別子)。

WAVE Bytes '##wb'
BYTE  abBytes[];

音声データは、圧縮 DIB または非圧縮 DIB である。非圧縮 DIB の場合、関連する BITMAPINFO 構造体の biCompression メンバに BI_RGB が指定されている。圧縮 DIB の場合は、biCompression メンバに BI_RGB 以外の値が指定されている。圧縮フォーマットの詳細については、『Microsoft Windows Programmer's Reference』で BITMAPINFOHEADER データ構造体の説明を参照すること。

非圧縮 DIB のデータ チャンクには RGB ビデオ データが含まれる。これらのチャンクは、2 文字コード 'db' (db は DIB bits の略) で識別される。圧縮 DIB のデータ チャンクは、2 文字コード 'dc' (dc は DIB compressed の略) で識別される。どちらのデータ チャンクも、DIB に関するヘッダー情報は含んでいない。非圧縮 DIB のデータ チャンクのフォーマットを次に示す。

DIB  Bits  '##db'
BYTE  abBits[];

圧縮 DIB のデータ チャンクのフォーマットを次に示す。

Compressed DIB  Bits  '##dc'
BYTE  abBits[];

ビデオ データ チャンクは、AVI シーケンス内でパレットを更新するための新しいパレット エントリを定義することもできる。パレット情報の指定の詳細については、『Video for Windows Programmer's Guide』を参照すること。

テキスト ストリームには任意の 2 文字コードを使用できる。

BITMAPINFOHEADER 構造体

BITMAPINFOHEADER 構造体には、AVI RIFF ファイルのビデオ ストリームに関する情報が含まれる。この構造体には以下のメンバが含まれる。

typedef struct tagBITMAPINFOHEADER {
    DWORD  biSize;
    LONG   biWidth;
    LONG   biHeight;
    WORD   biPlanes;
    WORD   biBitCount;
    DWORD  biCompression;
    DWORD  biSizeImage;
    LONG   biXPelsPerMeter;
    LONG   biYPelsPerMeter;
    DWORD  biClrUsed;
    DWORD  biClrImportant;
} BITMAPINFOHEADER;
biSize
構造体が必要とするバイト数を指定する。
biWidth
ビットマップの幅をピクセル単位で指定する。
biHeight
ビットマップの高さをピクセル単位で指定する。biHeight の値が正である場合、ビットマップはボトムアップ DIB (device-independent bitmap : デバイスに依存しないビットマップ) であり、左下隅が原点となる。biHeight の値が負である場合、ビットマップはトップダウン DIB であり、左上隅が原点となる。
biPlanes
ターゲット デバイスに対する面の数を指定する。これは必ず 1 に設定する。
biBitCount
1 ピクセルあたりのビット数を指定する。圧縮フォーマットによっては、ピクセルの色を正しくデコードするためにこの情報が必要である。
biCompression
使用されている、または要求されている圧縮のタイプを指定する。既存の圧縮フォーマットと新しい圧縮フォーマットの両方でこのメンバを使用する。
biSizeImage
イメージのサイズをバイト単位で指定する。非圧縮 RGB ビットマップの場合は、0 に設定できる。
biXPelsPerMeter
ビットマップのターゲット デバイスの水平解像度を 1 メートルあたりのピクセル単位で指定する。アプリケーションはこの値を使用して、リソース グループの中から現在のデバイスの特性に最も適合するビットマップを選択することができる。
biYPelsPerMeter
ビットマップのターゲット デバイスの垂直解像度を 1 メートルあたりのピクセル単位で指定する。
biClrUsed
カラー テーブル内のカラー インデックスのうち、ビットマップ内で実際に使用されるインデックスの数を指定する。この値がゼロの場合、ビットマップは、biCompression で指定される圧縮モードに対して、biBitCount メンバの値に対応する最大色数を使用する。
biClrImportant
ビットマップを表示するために重要とみなされるカラー インデックス数を指定する。この値がゼロの場合は、すべての色が重要とみなされる。

biBitCount メンバの値が 8 より大きい値に設定された場合、ビデオ ドライバはビットマップがトゥルー カラーであるとみなすことができ、カラー テーブルを使用しない。

biBitCount メンバの値が 8 以下の値に設定された場合、ビデオ ドライバはビットマップが BITMAPINFO データ構造体に定義されたパレットまたはカラー テーブルを使用しているとみなすことができる。このデータ構造体は、以下のメンバを持つ。

typedef struct tagBITMAPINFO {
    BITMAPINFOHEADER bmiHeader;
    RGBQUAD          bmiColors[1];
} BITMAPINFO;

BITMAPINFO の bmiheader メンバは、BITMAPINFOHEADER 構造体を指定する。BITMAPINFO の bmiColors メンバは、ビットマップ内の色を定義する RGBQUAD データ型の配列を指定する。

WAVEFORMATEX 構造体

WAVEFORMATEX 構造体には、AVI RIFF ファイルのオーディオ データ ストリームに関する情報が含まれる。この構造体には以下のメンバが含まれる。

typedef struct waveformat_extended_tag {
    WORD  wFormatTag;
    WORD  nChannels;
    DWORD nSamplesPerSec;
    DWORD nAvgBytesPerSec;
    WORD  nBlockAlign;
    WORD  wBitsPerSample;
    WORD  cbSize;
} WAVEFORMATEX;
wFormatTag
オーディオ ストリームのオーディオ波形タイプを定義する。フォーマット タグの完全なリストは、Microsoft® Visual C++® および他の Microsoft 製品に付属する Mmreg.h ヘッダー ファイルにある。
nChannels
オーディオ ストリーム内のチャンネル数を指定する。1 はモノ、2 はステレオを示す。
nSamplesPerSec
オーディオ ストリームのサンプル レート周波数をサンプル/秒 (Hz) で指定する。たとえば、11,025、22,050、または 44,100。
nAvgBytesPerSec
平均データ レートを指定する。再生ソフトウェアはこの値を使ってバッファ サイズを見積もることができる。
nBlockAlign
データのブロック アラインメントをバイト単位で指定する。再生ソフトウェアが 1 回に処理するデータのバイト数は nBlockAlign の整数倍でなければならないため、nBlockAlign の値を使用してバッファのアラインメントを行うことができる。
wBitsPerSample
チャンネル データごとの 1 サンプルあたりのビット数を指定する。各チャンネルのサンプル解像度は同じであると仮定される。このフィールドが必要ない場合は、ゼロに設定する。
cbSize
フォーマット ヘッダー内の追加情報のサイズをバイト単位で指定する。これには、WAVEFORMATEX 構造体のサイズは含まれない。たとえば、wFormatTag WAVE_FORMAT_IMA_ADPCM に対応する wave フォーマットの場合、cbSize は sizeof(IMAADPCMWAVEFORMAT) - sizeof(WAVEFORMATEX) として計算され、結果は 2 となる。

AVI 2.0 ファイル フォーマット拡張

現在 DirectShow は、以下の AVI 2.0 ファイル フォーマット拡張をサポートしている。

  • 大きな AVI ファイル サイズ (1 GB 以上)
  • 階層的なインデックス

『OpenDML AVI File Format Extensions』(OpenDML AVI M-JPEG File Format Subcommittee 編、1996 年 2 月 28 日) のバージョン 1.02 に記載された仕様を参照すること。


カスタム ファイル タイプの登録

このトピックでは、ファイル リーダー ソース フィルタで認識できるように新しいファイル タイプを登録する方法について説明する。ここで用いられるメカニズムは Microsoft® Win32® の GetClassFile 関数で使用されているもので、特定のファイル名に関連付けられた CLSID を返す。Microsoft® DirectShow® のメディア タイプではレジストリ内の 4 つの値のセットを使用しており、これは GetClassFile の FileType 登録で使われるものと同じである。ただし、この基準に合致するファイルはファイル タイプではなくメディア タイプに関連付けられる。また、DirectShow メディア タイプのレジストリ エントリには、このメディア タイプを読み取るために使用できるソース フィルタの CLSID が提供される。

FileType 登録と MediaType 登録のいずれにおいても、レジストリ内のパターンには次のフォーマットのエントリ列が含まれる。

regdb key = offset, cb, mask, value

メディア タイプは CLSID のペア {Majortype clsid, Subtype clsid} として定義される。ファイル内の指定されたオフセット位置にあるデータが HKEY_CLASSES_ROOT\Media Type\{<major type>}\{<subtype>} 内のパターンと一致した場合、そのパターンに関連付けられたメディア タイプ CLSID ペアがファイルのメディア タイプとなる。

レジストリ キーのパラメータは次のように解釈される。offset の値はファイルの先頭または末尾からのオフセットであり、cb は長さ (バイト単位) である。この 2 つの 10 進値は、ファイル内の特定のバイト範囲を表す (オフセット値が負の場合はファイルの末尾からのオフセットを表す)。mask 値は 16 進のビット マスクであり、offset と cb で指定されたバイト範囲との論理 AND 演算に使用される。論理 AND 演算の結果は value と比較される。マスクを省略した場合は、すべて 1 と仮定される。mask と value 内の 16 進の桁数は、cb の値の 2 倍でなければならない (cb はバイト単位であるため)。

レジストリ内の各パターンは、データベース内のパターンの順序に従ってファイルと比較される。それぞれの値が AND 演算の結果と一致した最初のパターンが、ファイルのメディア タイプを決定する。

各エントリには、4 つの値の組が複数含まれる場合もある。その場合は、すべての組がファイル内のデータと一致した場合に、メディア タイプがファイルに関連付けられる。1 つのエントリに 4 つの値の組を複数使用する例としては、バイト シーケンスをファイルの先頭と末尾の両方と一致させる場合などがある。次の例では、ファイルの最初の 4 バイトとしてパターン AB CD 12 34、ファイルの最後の 4 バイトとして AB AB 00 AB を指定している (マスクは適用されていない)。ファイルをメディア タイプに関連付けるには、パターンに対してすべての要素が一致する必要がある。

0 = REG_SZ 0, 4, , ABCD1234,  -4, 4, , ABAB00AB

また、1 つのメディア タイプについて複数のエントリが指定される場合もある。この場合、いずれか 1 つのエントリに一致すれば、ファイルがメディア タイプに関連付けられる。

たとえば、次のレジストリ エントリに含まれるパターンでは、最初の 3 バイトが AB CD 12、4 つ目のバイトが 32、33、34、または 35、そして最後の 4 バイトが FE FE FE FE である必要がある。

HKEY_CLASSES_ROOT
Media Type
{12345678-0000-0001-C000-000000000095}
{87654321-0000-0001-C000-000000000095}
                    0 = REG_SZ 0, 4, FFFFFFFE, ABCD1234, -4, 4, , FEFEFEFE
                    1 = REG_SZ 0, 4, FFFFFFFE, ABCD1232, -4, 4, , FEFEFEFE
                    Source Filter = {56781234-0000-0001-C000-000000000095}

ファイルにそのようなパターンが含まれる場合は、メディア タイプ {12345678-0000-0001-C000-000000000095}{87654321-0000-0001-C000-000000000095} がこのファイルに関連付けられる。メディア タイプに対するファイル ソース フィルタは、メディア タイプのキーにある Source Filter 値の CLSID によって識別される。

メディア タイプを使用して、ファイルをレンダリングするためのフィルタ ハンドラを見つけることができる。タイプに対応するハンドラは、データをレンダリングする前にファイルの詳細なテストを実行して、ファイルのタイプを確認する。

この方式では、代替マスクのセット (.wav ファイル) を使用できる。これには RIFF ヘッダーがあってもなくてもよい。

バイト拡張子なしでのファイル拡張子の登録

前に述べたように、特定のファイル拡張子に対して特定のメディア タイプ/サブタイプのペアまたはソース フィルタ CLSID を登録できる。この場合、メディア タイプの読み取りにはこのタイプおよびソース フィルタのみが使用される。ただし、独自のソース フィルタを登録した場合は、名前がソース フィルタに渡されて解釈されるため、実際のファイル名を表す名前には何の制限もない。

レジストリ エントリは次のようになる。

HKEY_CLASSES_ROOT\Media Type\Extensions

ファイル拡張子が .foo であれば、キーの内容は次のようになる。

.foo
REG_SZ:Media Type
REG_SZ:Subtype
REG_SZ: Source Filter

それぞれの値が GUID を表す。


DirectShow でのデバッグ

このトピックは Microsoft® DirectShow® アプリケーションとフィルタをデバッグする際のヒントをいくつか提供する。

このトピックには次のセクションが含まれる :

  • アサート チェック
  • オブジェクト名
  • デバッグ ロギング
  • クリティカル セクション
  • ポインタの有効性確認

参照 : GraphEdit によるグラフ構築のシミュレーション

アサート チェック

アサート チェック ライブラリを使うこと。アサートはコード内の必要条件、十分条件について作成した仮定を検証する。DirectShow はいくつかのアサート マクロを提供する。詳細については、「アサート マクロとブレークポイント マクロ」を参照すること。

たとえば、ピン クラスにピンが接続されていると仮定したプライベート メソッドが含まれているかもしれない。以下のように、アサートを使ってこの仮定をテストできる :

ASSERT(IsConnected());  // ピンは接続されていなければならない。

オブジェクト名

デバッグ ビルドでは、CBaseObject クラスから派生したオブジェクトのグローバル リストがある。オブジェクトが作成されると、それはリストに追加される。そのオブジェクトが削除されると、リストから消去される。オブジェクトのリストを表示するには、DbgDumpObjectRegister 関数を呼び出すこと。

CBaseObject 基底クラス (とそこから派生された大部分のクラス) のコンストラクタ メソッドにはオブジェクト名についてのパラメータが含まれている。それを識別する固有の名前をオブジェクトにつけること。名前の宣言に NAME マクロを使うと、名前の文字列はデバッグ ビルド時にのみ割り当てられる。リテール ビルドでは、その名前は NULL となる。

デバッグ ロギング

DbgLog 関数はプログラム実行時にデバッグ メッセージを表示する。この関数を使ってアプリケーションやフィルタの例外をトレースすること。戻り値や、変数の値、それ以外の任意の関連情報をログすることができます。

すべてのデバッグ メッセージは LOG_TRACE や LOG_ERROR のようなメッセージ タイプ、メッセージの重要度を示すデバッグ レベルを持っている。低いデバッグ レベルは高いレベルより重要となる。

次の例では、仮のフィルタがピン配列からあるピンを接続解除する。接続解除が成功すると、フィルタは LOG_TRACE メッセージを表示する。それが失敗すると、LOG_MESSAGE を表示する :

hr = m_PinArray[iPin]->Disconnect();
if (FAILED(hr))
{
    DbgLog((LOG_ERROR, 1, TEXT("Could not disconnect pin %d. HRESULT = %#x", iPin, hr));

   // エラー ハンドリング コード (省略).
}
DbgLog((LOG_TRACE, 3, TEXT("Disconnected pin %d"), iPin));

デバッグ中に、各メッセージ タイプのデバッグ レベルを設定することができる。また各モジュール (DLL あるいは 実行モジュール) は自分自身のデバッグ レベルを保持する。フィルタをテストしているなら、そのフィルタを持つ DLL のデバッグ レベルを上げること。詳細については、「デバッグ出力関数」を参照すること。

クリティカル セクション

デッドブロックをより容易にトラックするには、呼び出しコードが与えられたクリティカル セクション自身を所有しているかどうかを確認するアサートをインクルードすること。CritCheckIn と CritCheckOut 関数は呼び出し元のスレッドがクリティカル セクションを所有しているかどうかを示す。通常、アサート マクロ内部からこれらの関数が呼び出される。詳細については、「クリティカル セクション デバッグ関数」を参照すること。

クリティカル セクションが取得、解放されたときに、DbgLockTrace 関数を使ってトレースすることもできる。

ポインタの有効性確認

ポインタの有効性を考慮すること。たとえば、ValidateReadPtr マクロはして下ポインタが読み込み可能なメモリを指しているかどうかをチェックする。現在、DirectShow ポインタ有効マクロは IsBadReadPtr のような Microsoft® Win32® ポインタ評価関数を使用する。あるシステムでは、これらの関数が指定した範囲でページごとにスワップを起こす場合がある、これは著しくパフォーマンスを低下させる。詳細については、「ポインタ有効マクロ」を参照すること。


プログラミングのヒント

ここには、Microsoft® DirectShow® アプリケーションを効果的に開発するための情報が含まれている。

グローバル オブジェクト

グローバル C++ オブジェクトは、コンストラクタ メソッドで DirectShow オブジェクトを作成したり、デストラクタ メソッドでオブジェクトを解放してはならない。このようにすると、次のような理由でアプリケーションが無限にブロックする。

スレッドは、DLL のエントリ ポイント関数内にある間は終了できない。Kernel 32 は、エントリ ポイント関数内ではグローバル プロセスを保持し、ロックによってスレッドが終了できなくなる。DirectShow オブジェクトには独自のスレッドを持つものがあるので、DLL エントリ ポイント関数から解放するとブロックする可能性がある。アプリケーションにグローバル C++ オブジェクトがある場合、C ランタイム DLL は DLL がアンロードされたときにオブジェクトのデストラクタを呼び出す。デストラクタが DirectShow オブジェクトを解放すると、結果としてブロックする可能性がある。

同じような理由で、DLL はエントリ ポイント ルーチンで DirectShow オブジェクトを作成または解放してはならない。

フィルタ プロパティ

DirectShow フィルタを作成する際は、アプリケーションの書き手に対して、いくつかの方法でプロパティへのアクセスを与えることができる。IProvidePropertyPages インターフェイスを使ってプロパティ ページを提供すると、アプリケーションがこのインターフェイスを表示できる。アプリケーションが独自の UI を提供できるようにするには、IPropertyBag インターフェイスをサポートし、アプリケーションがフィルタに照会してプロパティを発見するようにできる。プロパティに特別なインターフェイスを提供する場合は、フィルタ情報とピン情報の独自のインターフェイスを作成することもできる。


デコーダの開発

ここでは、Microsoft® DirectShow® デコーダ開発のユーザー モードに関する側面について説明する。

  • DirectX ビデオ アクセラレーション
  • DVD デコーダの開発


Microsoft DirectX VA : ビデオ アクセラレーション API/DDI 仕様 (Rev 1.0)

Microsoft DirectX 8.0

Microsoft DirectX VA : ビデオ アクセラレーション
API/DDI 仕様 (Rev 1.0)

注 : このスペックの最新版は Microsoft® Word® フォーマットで http://www.microsoft.com/hwdev/DirectX_VA/ からダウンロード可能である。

要約 : この文書では、DVD サブピクチャなどに対応するためのアルファ ブレンディングのサポートを含め、デジタル ビデオのデコード処理をハードウェアでアクセラレーションするためのアプリケーション プログラミング インターフェイス (API) およびそれに対応するデバイス ドライバ インターフェイス (DDI) について説明する。特に MPEG-2 の "メイン プロファイル" ビデオ (以前の ITU-T MPEG-2 | ISO/IEC 13818-2) のサポートに焦点を当ててインターフェイスを解説するが、ほかの主要なビデオ CODEC (ITU-T 勧告 H.263 および H.261、ならびに MPEG-1 および MPEG-4 など) もサポートする。

目次

  • 1 概要
    • 1.1 要約
    • 1.2 目的および関連する標準規格
    • 1.3 必要条件、パフォーマンス検証、スケジュール
      • 1.3.1 非圧縮ピクチャ フォーマット
      • 1.3.2 アクセラレータの連続性必要条件
      • 1.3.3 ソフトウェア デコーダの連続性必要条件
        • 1.3.3.1 デコードに 4 つの非圧縮サーフェスを使用する
        • 1.3.3.2 デコードに 5 つ以上の非圧縮サーフェスを使用する
    • 1.4 用語
      • 1.4.1 略語と記号
      • 1.4.2 ビット番号付け規則
      • 1.4.3 定義
    • 1.5 ステージ
    • 1.6 フレーム バッファの構成
  • 2 現在の標準規格の処理
    • 2.1 ITU-T H.261
    • 2.2 MPEG-1
    • 2.3 MPEG-2 (別名 MPEG-2)
    • 2.4 ITU-T H.263
    • 2.5 MPEG-4
    • 2.6 予測の原理
      • 2.6.1 予測のステージ
      • 2.6.2 マクロブロック部分
      • 2.6.3 予測プレーン
  • 3 DirectX VA データ構造とプログラム構成
    • 3.1 暗号化サポート
    • 3.2 グローバル制限モードの情報
    • 3.3 構成をプローブおよびロックする
    • 3.4 バッファ記述リスト
    • 3.5 圧縮ピクチャのデコード (bDXVA_Func=1)
      • 3.5.1 接続構成
      • 3.5.2 最小限の相互動作性構成セット
      • 3.5.3 補足的な推奨構成セット
      • 3.5.4 圧縮ピクチャのパラメータ
      • 3.5.5 ピクチャのマクロブロックのバッファ構造
        • 3.5.5.1 マクロブロック制御コマンド
        • 3.5.5.2 逆量子化、IDCT 前飽和、ミスマッチ制御、イントラ DC オフセット、IDCT、ピクチャ再構築、および再構築クリッピング
          • 3.5.5.2.1 オフホストの IDCT
            • 3.5.5.2.1.1 単一係数のデータ フォーマット
            • 3.5.5.2.1.2 グループ化された 4 係数のデータ フォーマット
          • 3.5.5.2.2 ホストベースの IDCT
            • 3.5.5.2.2.1 16 ビット方式
            • 3.5.5.2.2.2 8-8 オーバーフロー方式
        • 3.5.5.3 ブロック解除フィルタ制御
        • 3.5.5.4 読み戻しバッファ
      • 3.5.6 オフホストの VLD ビットストリーム デコード処理
        • 3.5.6.1 逆量子化行列バッファ
        • 3.5.6.2 スライス制御バッファ
        • 3.5.6.3 ビットストリーム データ バッファの内容
    • 3.6 アルファ ブレンド データのロード (bDXVA_Func=2)
      • 3.6.1 接続構成
      • 3.6.2 最小限の相互動作性構成セット
      • 3.6.3 AYUV アルファ ブレンディング サーフェスのロード
        • 3.6.3.1 16 エントリ AYUV パレットのロード
        • 3.6.3.2 AYUV サーフェスのロード
      • 3.6.4 IA44/AI44 アルファ ブレンディング サーフェスのロード
      • 3.6.5 DPXD アルファ ブレンディング サーフェスのロード
      • 3.6.6 ハイライト データのロード
      • 3.6.7 DCCMD データのロード
    • 3.7 アルファ ブレンド コンビネーション (bDXVA_Func=3)
      • 3.7.1 接続構成
      • 3.7.2 最小限の相互動作性構成セット
      • 3.7.3 アルファ ブレンド コンビネーション バッファ
        • 3.7.3.1 例: MPEG-2 パン-スキャン操作
        • 3.7.3.2 例: 16:9 ピクチャでの DVD 4:3 パン スキャン
        • 3.7.3.3 例: DVD 704 ワイド非パン スキャン ピクチャ操作
        • 3.7.3.4 例: DVD 352 ワイド ピクチャ操作
        • 3.7.3.5 例: DVD 720 ワイド ピクチャ操作
    • 3.8 ピクチャ再サンプリング制御 (bDXVA_Func=4)
      • 3.8.1 接続構成
      • 3.8.2 最小限の相互動作性構成セット
      • 3.8.3 ピクチャ再サンプリング制御バッファ
  • 4 制限モード
    • 4.1 新規制限プロファイルの追加
    • 4.2 非制限処理
    • 4.3 H261_A 制限プロファイル
    • 4.4 H261_B 制限プロファイル
    • 4.5 H263_A 制限プロファイル
    • 4.6 H263_B 制限プロファイル
    • 4.7 H263_C 制限プロファイル
    • 4.8 H263_D 制限プロファイル
    • 4.9 H263_E 制限プロファイル
    • 4.10 H263_F 制限プロファイル
    • 4.11 MPEG1_A 制限プロファイル
    • 4.12 MPEG2_A 制限プロファイル
    • 4.13 MPEG2_B 制限プロファイル
    • 4.14 MPEG2_C 制限プロファイル
    • 4.15 MPEG2_D 制限プロファイル
  • 5 IAMVideoAccelerator 処理
    • 5.1 IAMVideoAccelerator インターフェイス
    • 5.2 IAMVideoAccelerator への DirectX VA のマッピング
      • 5.2.1 制限モード プロファイルと構成の設定
      • 5.2.2 DirectX VA IAMVideoAccelerator 処理仕様
      • 5.2.3 動き補償デバイス ドライバとの処理上の通信

概要

この文書では、DVD サブピクチャなどに対応するためのアルファ ブレンディングのサポートを含め、デジタル ビデオのデコード処理をアクセラレーションするためのアプリケーション プログラミング インターフェイス (API) およびそれに対応するデバイス ドライバ インターフェイス (DDI) について説明する。特に MPEG-2 の "メイン プロファイル" ビデオ (以前の ITU-T MPEG-2 | ISO/IEC 13818-2) のサポートに焦点を当ててインターフェイスを解説するが、ほかの主要なビデオ CODEC (ITU-T 勧告 H.263 および H.261、ならびに MPEG-1 および MPEG-4など) もサポートする。ここで解説する設計は現時点ではデコードに限定されているが、将来インターフェイスがさらに拡張される際には、エンコード機能も定義される予定である。このインターフェイスは、各種 CODEC の設計の中で、多量の計算を要する最も基礎的な部分を抜き出し、ハードウェア内でのそれらのアクセラレーションをサポートするよう設計されている。

グラフィック ハードウェア ドライバは、グラフィック ハードウェア実装のアクセラレーション機能に対する共通のアクセス方式を提供するため、このインターフェイスをサポートしたほうがよい。過去に、グラフィック ハードウェア メーカー数社から、これとよく似た機能が自社製品専用のものとして定義されたことがあった。しかし、この仕様の目的は、ソフトウェア アプリケーション プログラムと高度なグラフィック アクセラレーション機能の間に、ベンダーに依存しない共通インターフェイスを確立することである。共通インターフェイスの確立により、ビデオをサポートするコンピューティング システムの能力が拡大され、この機能を提供するソフトウェア アプリケーションの需要が増加し、ハイパフォーマンスなグラフィック機能への需要が増加することが期待される。

1.1 要約

この仕様で定義されているインターフェイスは、ITU-T の H.26x シリーズおよび ISO/IEC JTC1 の MPEG-x シリーズを含め、現在の主な標準動き補償ビデオ CODEC をサポートすることができる。当初は、現在最も商業的に優勢なビデオ CODEC である MPEG-2 (厳密には ITU-T 勧告 MPEG-2 または ISO/IEC 13838-2) をサポートするよう設計された。

この文書で定義している構文は、この標準規格を非常に直接的にサポートするよう設計されているため、標準規格の構文をここで定義されたフォーマットに変換する際には、わずかな "翻訳" しか必要ない。ほかの標準規格を最大限に一貫した方法でサポートするために必要な機能も追加された。また暗号化を必要とするアプリケーションのために、暗号化もサポートされている。このインターフェイスでは、各種の標準規格に共通の中心的な基本処理を抽出し、また規格固有のいくつかの処理をホスト CPU に限定している。これにより、規格に依存しない高い柔軟性を持ちながら、アクセラレーション ハードウェアに対する規格ごとのカスタマイズも最小限で済むビデオ CODEC ハードウェア アクセラレーションのサポートを可能にしている。

1.2 目的および関連する標準規格

この仕様は、1 つ以上のステージを 1 つ以上のデバイス間で分割できるようにするビデオ デコーダ アクセラレーションの言語を定義している。現在この文書では、ITU-T H.261、MPEG-1 (ISO/IEC 11172-2)、MPEG-2 (ISO/IEC 13818-2 | ITU-T 勧告 MPEG-2)、ITU-T H.263、および MPEG-4 (ISO/IEC 14496-2) の一部の、動き補償予測 (MCP : motion-compensated prediction) および逆離散コサイン変換 (IDCT : inverse discrete-cosine transform) ステージを実行するハードウェア アクセラレータと、ホスト CPU との区分を説明している。総合的な目的は、CPU リソースを浪費する、簡単で、しかも頻繁に実行される処理を、専用の目的のために設計された低コストなアクセラレータにオフロードし、ビットストリーム解析や可変長デコード (VLD : variable-length decoding) といった、複雑で、あまり頻繁に実行されない処理をホスト CPU に残すことである。

ここで説明している仕様は、単一のビデオ ストリームのデコードに対してのみ有効である。複数のビデオ ストリームは、Microsoft® DirectX® VA API では明示的にはサポートされていない。このため、複数のビデオ ストリームをサポートするには、ビデオ ストリームごとに個別の DirectX® VA セッション処理が必要となる (例 : フィルタ グラフ処理での使用に、ビデオ デコーダとアクセラレーション ドライバに個別の出力ピンおよび入力ピンのセット)。

1.3 必要条件、パフォーマンス検証、スケジュール

この仕様書に記載されたインターフェイスを使用するすべてのアクセラレータ ドライバについて、この仕様書の内容に準拠していることを確認する必要がある。確認内容は次のとおり。

  • この API を使用するハードウェアが実行する処理によって、意図したとおりの計算結果が得られること
  • この API を使用するソフトウェア デコーダによって得られるパフォーマンスが、同機能を実行するためにホスト－ソフトウェア実装でなくこの API を使用すべきであることを正当化するに足りる速度と信頼性を示すこと

Microsoft では、これらが検証されていない実装は、あくまでテスト目的に使用すべきであり、この文書で指定しているインターフェイスを公開するドライバに配備すべきではないと考える。

中期的将来には、デコーダおよびグラフィック アクセラレータの実装の認可に、このインターフェイスのサポート、およびサポートのためのパフォーマンス検証が必要となる。厳密なテスト スイートおよびパフォーマンス測定方法はまだ定義されていない。この文書で述べている中期的将来の必要条件は、ハードウェア ビデオ デコード アクセラレーションをサポートするすべてのグラフィック アクセラレーション ハードウェア、およびそれらのグラフィック アクセラレーション ハードウェア サポートを使用するすべてのソフトウェア デコーダについて、2001 年の半ばにおけるすべての Microsoft Windows® オペレーティング システム (Windows 2000、Windows Millennium Edition、および Windows 2000 "Whistler") に適用される条件として定義される予定である。この文書で述べている長期的将来の必要条件は、中期的な必要条件のおよそ 1 年後に適用される条件として定義されている。この期待される要件のデッドライン日付は進行状況によって調整され得る。

暗号化、構成、および制限モード サポートの必要条件については、暗号化サポート、構成、および制限モードに関する以降の各セクションで解説する。ピクセル フォーマット サポートの必要条件については、ここで解説する。

1.3.1 非圧縮ピクチャ フォーマット

DirectX VA で作成されたデコード済み非圧縮ピクチャをアプリケーションで使用するには、それらのピクチャが認識可能なフォーマットで作成されている必要がある。DirectX VA アクセラレータがサポートする非圧縮ピクセル フォーマットのリストには、次のピクセル フォーマット リストのメンバが 1 つ以上含まれていなければならない (「YUV フォーマット」を参照)。

  1. 圧縮 4:2:2 ビデオのデコード :
    1. "YUY2" では、データを符号なし char 型の配列として取り扱うことができる。最初のバイトには Y の最初のサンプルが格納され、2 番目のバイトには Cb の最初のサンプル、3 番目のバイトには Y の 2 番目のサンプル、4 番目のバイトには Cr の最初のサンプル、というように続く (たとえば 2 つのリトル エンディアン WORD 型変数の配列としてアドレスされた場合は、最初の WORD には LSB に Y0 および MSB に Cb が格納され、2 番目の WORD には LSB に Y1 および MSB に Cr が格納される)。これは、推奨される DirectX VA 4:2:2 ピクセル フォーマットであり、4:2:2 ビデオをサポートする DirectX VA アクセラレータの中期的必要条件となる予定である。
    2. "UYVY" は、"YUY2" と同様だが、各ワードのバイト順序が逆になる (たとえば 2 つのリトル エンディアン WORD 型変数の配列としてアドレスされた場合は、最初の WORD には LSB に Cb および MSB に Y0 が格納され、2 番目の WORD には LSB に Cr および MSB に Y1 が格納される)。
  2. 圧縮 4:2:0 ビデオのデコード :
    1. "YUY2" は、上記と同様だが、実際の 4:2:0 Cb および Cr サンプルの各ラインに対して、2 ラインの出力 Cb および Cr サンプルが作成される。各組の 2 番目のラインは、1 番目の複製か、または 1 番目および 3 番目の平均値である。使用中のあらゆるフォーマットからこのフォーマットへ "フロントエンド" 変換する能力は、中期的必要条件となる予定である。
    2. "UYVY" は、上記と同様だが、実際の 4:2:0 Cb および Cr サンプルの各ラインに対して、2 ラインの出力 Cb および Cr サンプルが作成される。各組の 2 番目のラインは、1 番目の複製か、または 1 番目および 3 番目の平均値である。
    3. "YV12" では、すべての Y サンプルが、符号なし char 型配列としてメモリの最初に存在し (メモリのアラインメントのために、より大きなストライドになっている可能性あり)、その直後にすべての Cr サンプルが (Y ラインの半分のストライド、かつ半分のライン数で) 続き、その直後にすべての Cr サンプルが同様に続く。
    4. "IYUV" は、YV12 と同様だが、Cb および Cr プレーンの順序が逆になる。
    5. "NV12" (参照先 Web ページに記載なし) では、すべての Y サンプルが、符号なし char 型の偶数ラインの配列としてメモリの最初に存在し (メモリのアラインメントのために、より大きなストライドになっている可能性あり)、その直後に、Y サンプルと同じ合計ストライドで、インターリーブされた Cb および Cr サンプルを含む符号なし char 型の配列が続く (たとえば 1 つのリトル エンディアン WORD 型としてアドレスされた場合は、Cb は LSB に、Cr は MSB に入る)。これは推奨される 4:2:0 ピクセル フォーマットであり、4:2:0 ビデオをサポートする DirectX VA アクセラレータの中期的必要条件となる予定である。
    6. "NV21" (参照先 Web ページに記載されていない新語) は、NV12 と同様だが、Cb および Cr サンプルが逆になっており、符号なし char 型のクロマ配列で各サンプルが Cr、Cb の順に並ぶ (たとえば 1 つのリトル エンディアン WORD 型としてアドレスされた場合は、Cr は LSB に、Cb は MSB に入る)。
    7. "IMC1" (参照先 Web ページに記載されていない新語) は、YV12 と同様だが、Cb および Cr プレーンのストライドが Y プレーンでのストライドと同じである。また Cb および Cr プレーンは、16 ラインの倍数であるメモリ境界内に収まるよう制限されている (標準ではすべて 16×16 マクロブロックを使用するため、標準フォーマットではこの制限は意味を持たない)。
    8. "IMC2" (参照先 Web ページに記載されていない新語) は、IMC1 と同様だが、Cb および Cr ラインがハーフストライドの境界でインターリーブされる。つまり、色光度領域の各フルストライドのラインは、Cb のラインで始まり、次のハーフストライド境界から始まる Cr のラインが続く。(この場合、色光度のアドレス空間が半分になることで、合計アドレス空間が 25% 削減されるため、IMC1 よりもアドレス空間を効果的に利用できるフォーマットと言える。) これは NV12 より比較的優れているが、NV12 の方がより一般的であるとされる。
    9. "IMC3" (参照先 Web ページに記載されていない新語) は Cb と Cr のスワップ以外は IMC1 と同じである。
    10. "IMC4" (参照先 Web ページに記載されていない新語) は Cb と Cr のスワップ以外は IMC2 と同じである。

これらのフォーマットを定義する第 1 の目的は、使用されるフォーマットを文書化し、圧縮解除されたビデオをその後の処理に使用できるようにすることである (この処理では、ビデオを DirectDraw サーフェス テクスチャとして操作する)。第 2 の目的は、フォーマットの種類が増えることを防いで、ソフトウェア処理を単純化する (多種類のフォーマットを使うことによって同じ機能が重複することを避ける) ことである。

1.3.2 アクセラレータの連続性必要条件

インターフェイスの操作中にレース コンディションが予期せぬ出来事を引き起こさないようにするための基本的な負担はハードウェア アクセラレータではなく、ホスト ソフトウェア デコーダ上にある。これに関してアクセラレータに負わされた要求は、非圧縮サーフェスの表示が停止しているか実行中かを問われたときに正しくレポートできる事と、要求された操作が完了したかどうかを問われたときに正しくレポートすることである。

1.3.3 ソフトウェア デコーダの連続性必要条件

ここでは、デコード処理において連続処理が確実に正しく実行されるよう、特定の必要条件が課せられている。これらの条件は、デコードおよび表示の際の、非圧縮サーフェスの取り扱いに関するものである。ここで挙げる例は、ブロック解除フィルタを使わない、一般的な I、B、および P 構造化ビデオ フレームのピクチャ デコードの取り扱いについての例である。ほかの状況でも、おおむね同じ原則が適用される。

原則は、次のように単純なものである : 参照や表示に必要なものにオーバーライドしないこと、レース コンディションを避けること。これは、次の 2 つのルールに分解できる。

  • ディスプレイにサブミットされたピクチャは、既に画面に表示され画面から消されるまでは、オーバーライドできない (画面に予期せぬ表示が出るのを避ける)、そして
  • まだ作成されていないピクチャ作成の参照として必要なピクチャには、オーバーライドできない

これは次のの要件となる、ソフトウェア デコーダはアクセラレータの状態を問い合わせ レース コンディションを避けなければならない、そしてデコーダは十分な数の非圧縮サーフェスを使ってそのスペースがすべての必要な操作で利用可能でなければならない。

この結果、I、B、P ピクチャの処理には 4 つ以上の非圧縮ピクチャ サーフェスが必要となる。(より多い数が通常は期待されており、フロントエンド アルファ ブレンディングに使うようないくつかの操作では、より多くの数が必要である。)

以下の 2 つのサブセクションでは、B ピクチャのビデオ デコードにおける 4 つ以上の非圧縮サーフェスの使用について記述し、通常は 4 つ以上の非圧縮サーフェスが必要であり、ディレイを最小限に抑える必要がないアプリケーションでは 5 つ以上が推奨されることを結論付ける。追加サーフェスを使うことにより、解決しなければならない操作による待ち状態を著しく軽減させることができる。

圧縮バッファは圧縮サーフェスと同様に、割り当てられたバッファと同じものあるいはその同じサブセットを再利用するより、一般的にはすべての有効なすべてのバッファを繰り返し使った方が良いことに注意。それは不必要な依存性を待つために追加されたディレイを要求するボトルネックがおきる可能性があるからである。いくつかの場合、ドライバによる複数バッファの割り当てはダブルバッファやトリプルバッファの繰り返し使用が予期せぬ表示なしで操作する正しい方法であることを示す。(これは特にアルファ ブレンディング データ読み込みに適用する。)

1.3.3.1 デコードに 4 つの非圧縮サーフェスを使用する

図 1 に、特定の状況を仮定したビデオ デコーダを示す。このデコーダは、各ピクチャのデコードに 1 フレーム タイム要し、また P ピクチャの組の間に (最初の I ピクチャの後にある 0 個の B ピクチャから始まって) 増加し続ける B ピクチャを含むビットストリームをデコードしている。この例では、I、B、P の文字が各ピクチャのタイプを、下付き文字が各ピクチャの一時的な表示順序を、上付き文字がピクチャを保持するバッファを、それぞれ示している。各 B ピクチャをデコードするには、ビットストリーム順序で先行する 2 つのピクチャが必要である。その結果、デコーダは、2 番目のピクチャがデコードされるまで (デコードの 3 番目のタイム スライスに入るまで)、正しいタイミングでピクチャを表示し始めることができない。この 3 番目のタイム スライスのどこかで、正しいタイミングでのピクチャ表示を開始できる。

ピクチャ表示の開始は、通常、ピクチャが画面に現れるのと同時には実行されない。その代わり、新しいピクチャへの切り替えに適した時が来るまで、表示するよう命令されたピクチャに先行する別のピクチャが表示され続ける。このため、パフォーマンスを最適化するには、サーフェス 0 (最初の I ピクチャを保持する) はたとえ I ピクチャが必要なくても、3 フレームタイム後に来る B ピクチャによってオーバーライドされるべきではない。そうではなく、4 番目のサーフェス (サーフェス 3) は理想的には B ピクチャを保持するために用いられるべきだ。これによって B ピクチャをデコードする前に、最初の I ピクチャの表示ピリオドが完了してしまったかどうかをチェックする必要が無くなる。

上で与えられた 2 つのルールの応用は最初の 3 つのデコードされたピクチャが別のサーフェスに置かれなければならないということである、なぜならそのどれもが 3 番目のピリオド (ピリオド 2) の間には表示されてしまわないからである。次に4番目のデコードされたピクチャは理想的には4番目のサーフェスに置かれるべきである、なぜなら最初に表示されたピクチャは4番目のピリオド (ピリオド 3) の間には終了していないかもしれないからである。

図1 で起こり得る処理中の大きなボトルネックは、1 行に 2 つ以上の B ピクチャを持つ結果として、10番目のデコードされたピクチャ (B19) で起きる。連続シーケンスの 3 番目あるいはその次の B ピクチャが来たとき、1 つの B ピクチャの表示と次のデコードされた B ピクチャを保持するサーフェス使用の間のタイムラグ許容値は排除される。この状態では、ホスト デコーダは前のピリオドで表示された B ピクチャのディスプレイ状態 (この場合は、B17)をチェックしてディスプレイから削除されたことを確かめなければならない (必要ならこれを待つ)、次にすぐに同じサーフェスを使って次の B ピクチャ (この場合は、 B19 に使われているサーフェス 1) をデコードしなければならない。参照 I ピクチャあるいは P ピクチャ(この場合は、サーフェス 0 と 2、これらは P06 と P210 に使われている) を保持するために使われてるどちらのサーフェスでも新しい B ピクチャをデコードすることはできない、そして同じインターバル タイム注に表示されているサーフェス (この場合、 B38 に使われているサーフェス 3 ) で新しい B ピクチャをデコードはできない。従って直前のピリオドで表示されたサーフェスを使わなければならない (この場合は、サーフェス 1)。

デコード処理 | I00 | P11 | P23 | B32 | P06 | B14 | B35 | P210 | B17 | B38 | B19 | P015
表示処理 |  |  | I00 | P11 | B32 | P23 | B14 | B35 | P06 | B17 | B38 | B19
デコードされたフレーム* | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11
デコード処理 | B311 | B112 | B313 | B114 | P221 | B316 | B117 | B318 | B119 | B320 | P028 | ...
表示処理 | P210 | B311 | B112 | B313 | B114 | P221 | B316 | B117 | B318 | B119 | B320 | ...
デコードされたフレーム* | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | ...
* インターバルの開始点。

図 1 -- 4 フレーム デコーダ バッファリング (右上の数字はバッファ ナンバー、右下の数字はディスプレイ インデックス)

1.3.3.2 デコードに 5 つ以上の非圧縮サーフェスを使用する

バッファを 5 つ以上使用できるため、バッファの表示開始と同バッファへの新しい書き込みの時間差を、最低 1 表示周期から 2 以上に広げることができる。これにより、デコード処理のタイミングにより大きなジッタを許可することができる。また、デコード済みピクチャの出力処理で、表示処理の一環として 3 フィールドの非インターレース処理を実行できる (現在のピクチャだけでなく前のピクチャも表示に利用可能なので、前のピクチャを使って、コンテキストを提供したり、実際の表示処理で 1 フィールドのディレイを許したりすることができるため)。それはまた誤って設計されたハードウェア ドライバに対していくつかの免責を提供する、それはピクチャが実際にまだ表示されているかそうではないのかを正しく認識しないで書かれているドライバである (そのような状態を提示しないハードウェア ドライバに正しくは依存するべきではないけれども)。B ピクチャに DirectX VA を効率よく使用するには、バッファが少なくとも 4 つあれば足りると考えられる。ただし、ディレイの抑制が要件とされない場合には、5 つ以上のバッファの使用を推奨する。I、B、P 構造化されたビデオ デコーディング用のDirectX VA デコーダはそれゆえ、非圧縮サーフェスを割り当てるとき、その最小と最大の要求可能な非圧縮サーフェス割り当て数を少なくともそれぞれ 4 と 5 に設定すべきである。1 つ以上の追加非圧縮サーフェスを使うことはスムースで、信頼性高く、ティア フリーの操作を得る良い方法であることが多い。

1.4 用語

1.4.1 略語と記号

' ' 2 進値 (左のビットが MSB)

" " 10 進値

0x 16 進値

LSB 最下位ビット (Least Significant Bit)

MSB 最上位ビット (Most Significant Bit)

// 0 と逆方向に丸める区切り

/ 0 方向に切り捨てる区切り

1.4.2 ビット番号付け規則

この仕様書では、ビット番号を Microsoft で普及している規則に従って表現する。この規則では、LSB がビット 0 、MSB がビット N-1 となる (ビット数が N の場合)。

注 : ビデオ コーディング規格には、最も若い番号のビットが MSB とされるものがあり、その場合はこの番号付け規則とは異なる。

ただし、この文書で構造体内に 8 ビット未満のフィールドのシーケンスが現れる場合、その順序はビデオ コーディング規格で使用されている規則に従う。つまり、最初にリストされる要素が MSB に最も近い位置にあるものと見なされる。たとえば、単一ビットの配列要素 5 つを構造記述内に並べる場合には、構造記述内にインデックスが減少する順序で各要素がリストされる。

このアプローチに見られる分裂的現象は、このインターフェイス仕様の各ビットがどこに位置するのかを決める最終的な権限が、この文書でなく、このインターフェイスに関連付けられる ".h" ファイルにあるものと見なしたほうがよいことを意味する。

1.4.3 定義

参照ブロック - 参照フレーム バッファから抽出されたブロック領域。

予測ブロック - 参照ブロックからフィルタされたブロック。

予測プレーン - マクロブロック予測を結合する前に形成されるサンプルの配列。各プレーンは、通常 1 つのフレーム ロケーションから集められた、一連の予測ブロックを表す。プレーンが結合されて、単一のマクロブロック予測を形成する。

予測マクロブロック - すべての色チャンネルを含むマクロブロック予測。

成分 - 3 つの色チャンネル {Y, Cb, Cr } の 1 つ。

ホスト CPU - ビデオ デコードの機能全体 (上位処理) を制御する、プログラム可能なプロセッサ。

アクセラレータ - IDCT、MCP、表示フォーマット変換といった、単純だが頻繁に実行される処理を実行する機能単位。

動きベクトル計算 - 動きベクトルを予測ブロック アドレスに変換する処理。

予測アドレス - 実装固有の設計の中で、予測ブロックのある位置。

合成予測ブロック - 属性が輝度と色光度の両方に適用される予測ブロック。

成分予測ブロック - 属性が輝度か色光度のどちらかに適用される予測ブロック。

イントラ (フレーム内) - デコード済みのピクチャを参照した予測を行わないピクチャ コンテンツの表現。

インター (フレーム間) - まずデコード済みのピクチャを使ってピクチャの 1 領域の予測をエンコードし、その後必要に応じて予測からの偏差を表す信号を追加するピクチャ コンテンツの表現。

残差デコード - 必要に応じて、動き補償予測後に残っている信号を表現するため、エンコードされた誤差信号を表す波形をデコードすること。この結果、非予測波形の "イントラ" 表現だけが使用される場合と、予測後の "インター" 差異が使用される場合がある。

ReservedBits - この仕様で名前または名前の一部に ReservedBits が含まれているフィールドは、現在この仕様では使用されていないため、値は 0 でなければならない。

～ほうがよい - 推奨される (必須ではない) 動作の記述に使用される表現。

～ならない - 必須 (または禁止された) 動作の記述に使用される表現。

1.5 ステージ

次の図に示すステージは、MCP および IDCT アクセラレータで構成されている。

図 2 -- デコーダのステージ

1.6 フレーム バッファの構成

すべてのピクチャ バッファは、MPEG-2 仕様どおり、フレームで構成されたバッファを保持していると見なされる。アドレス単位は、特に指定がない限りフレーム座標で設定しなければならない。フレーム座標で記述された予測ブロックを、実装固有の変換レイヤを使って、損失なしにフィールド座標に変換することができる。たとえば、単一フレームの動き予測は、上下 2 つの個別のマクロブロック部分予測に分割できる。

3 つのビデオ成分チャンネル {Y, Cb, Cr} は、この仕様で定義されたインターフェイスによってアクセスされる。2 つの色光度成分の動きベクトルは、輝度成分に送られたベクトルから派生する。これらの動きベクトルは、アクセラレータによって別の座標システムに変換される。

現在の標準規格の処理

図 3 -- ホストおよびアクセラレータのシステム

以下に、H.261、MPEG-1、MPEG-2 (MPEG-2)、H.263、および MPEG-4 の基本処理を年代順にリストし、この仕様を使ってどのように実現できるかを簡単に説明する。

2.1 ITU-T H.261

正式には "Video CODEC for Audiovisual Services at px64 kbit/s" と呼ばれる ITU-T 勧告 H.261 は、比較的高い圧縮率を持つ実用的な設計としては最初のデジタル ビデオ コーディング標準規格であった (最初のデジタル ビデオ コーディング標準規格である H.120 は既に忘れられている)。また、Y、Cb、Cr 成分を使った 8 ビット サンプル、4:2:0 サンプリング、16×16 "マクロブロック" ベースの動き補償、8×8 IDCT、係数のジグザグ逆スキャン、スカラー量子化、値 0 の RLE (run-lengths) および量子化インデックス値の組み合わせに基づく係数の可変長コーディングといった、ほかのビデオ CODEC 標準で後に使用されるのと同様の基本設計が使用されていた。すべての H.261 予測ブロックは、先行するピクチャから順方向のみの予測を使用する。H.261 はハーフサンプル精度の予測フィルタを持たないが、その代わりに "ループ フィルタ" と呼ばれる低パス フィルタの一種を使用する (H.261 仕様のセクション 3.2.3)。このフィルタは、各マクロブロックの動き補償予測中にオン/オフできる。

補遺 D グラフィック : H.261 は後に、"補遺 D グラフィック転送" と呼ばれる興味深いトリック モードを取り入れた。このアクセラレータ インターフェイスでは、この機能に対する特別なサポートは提供されていない。この仕様を使ってこの機能をサポートするには、デコードされた 4 つのピクチャをアクセラレータからホストに読み戻し、そこでインターリーブして、高解像度のグラフィック ピクチャとして表示することができる。

2.2 MPEG-1

正式には ISO/IEC 11172-2 と呼ばれる MPEG-1 ビデオは、H.261 からほどなくして、H.261 の設計の多くを取り入れて設計された。ループ フィルタはなく、その代わりに、フレーム間のサブピクセルの動きを解決するためのシンプル ハーフサンプル フィルタを持つ。追加された双方向予測モードおよび逆方向予測モードでは、参照フレームが 1 つ余分にバッファされる必要がある。双方向予測は、順方向に予測された予測ブロックと逆方向に予測された予測ブロックの平均を取る。順方向と逆方向の予測ブロックを平均化する計算は、ハーフサンプルされた "補間" 予測ブロックの作成に似ている。その他の基本構造は H.261 と同様である。

2.3 MPEG-2 (別名 MPEG-2)

正式には "Information Technology - Generic Coding of Moving Pictures and Associated Audio Information : Video" ITU-T 勧告 MPEG-2 | ISO/IEC 13818-2 と呼ばれる MPEG-2 は、非常に下位の層から見れば、既存の MPEG-1 のツールに、基本的な 16×8 形状を追加しただけの仕様である。少し上位の層から見れば、MPEG-2 には、インターレース ビデオの特性を取り扱うために、複数のフィールドから参照した予測を組み合わせる多くの方法が追加されている。

MPEG-2 フレーム構造化ピクチャ :

  1. フレーム MC : MPEG-1 予測と非常によく似た 16×16 の予測ブロック形状を持つ。これは、MPEG-2 では唯一、プログレッシブ フォーマットの動きである (MPEG-2 の motion_type パラメータで指定される)。MPEG-2 の macroblock_type パラメータの設定によって、1 つの予測プレーン (順方向のみ、または逆方向のみ) を持つか、または 2 つの予測プレーン (双方向) を持つ。参照ブロックは、フレーム バッファからの連続フレーム ラインで形成される。フレーム バッファは、デコード処理のセマンティクスによって選択される。ハーフサンプル補間 (MPEG-2 セクション 7.6.4) および双方向補間 (MPEG-2 セクション 7.6.7.1) の平均化処理は、MPEG-1 とまったく同じである。
  2. フィールド (16×8) MC : 順方向および逆方向の各プレーンは、上 16×8 予測ブロック、および下 16×8 予測ブロックで構成される。各予測ブロックに対応する参照ブロックは、参照フレームの上フィールドまたは下フィールドから抽出できる (MPEG-2 の motion_vertical_field_select[r][s] パラメータによって決定される)。1 つの予測プレーンに対して 2 つの予測ブロックが 1 セットある (順方向のみまたは逆方向のみ。この場合は 1 つのマクロブロックに合計 2 つの予測ブロックが存在する) 場合と、2 つの予測プレーンに対して複数のセットがある (双方向。この場合は、1 つのマクロブロックに合計 4 つの予測ブロックが存在する) 場合がある。
  3. デュアル プライム : 前記のフィールド MC と同様、各プレーン (パリティ) は、上下の 16×8 形状で構成される。同パリティ プレーンと逆パリティ プレーンは、1、2、4、5 の双方向補間と同様の平均化処理によって結合される。ほかの動きタイプ (1、2、4、5) と異なり、デュアル プライムのマクロブロックは、常に 2 セットの予測ブロック (同パリティおよび逆パリティ) で構成され、1 つのマクロブロックに合計 4 つの予測ブロックが存在する。

MPEG-2 フィールド構造化ピクチャ :

  4. フィールド (16×16) MC : 各予測が 16×16 形状を持つ点でフレーム MC に似ているが、参照ブロック データは、連続的な上または下のラインのみから形成される。プログレッシブ フォーマットの動きのように上下のラインが交互に混在することはない。フィールド構造化ピクチャのすべての動きタイプと同様、再構築されたマクロブロックも、連続的な上または下のラインのみの状態で、現在のフレーム バッファに格納される。上フィールドまたは下フィールドの宛先は、MPEG-2 の picture_structure 変数によって決定される。
  5. 16×8 MC : このタイプの動きの基本的な予測ブロック形状は、ほかの 16×8 形状 (2、3) と同一であるが、同じ方法でマクロブロックにパーティション分割されることはない。2 つのパーティションは、マクロブロック内の上下のフィールドでなく、マクロブロック予測プレーンの上半分と下半分に対応する (図 を参照)。下半分の 16×8 のアンカー ポイントは 16×8 下部分の左上であって、ほかのすべての動きタイプのようにマクロブロック全体の左上ではないという点には、特に注意したほうがよい。
  6. デュアル プライム : 最下層においては、デュアル プライムと、双方向予測のフィールド構造化フィールド動き補償の間に実質的な区別はない。違いは、参照ブロックの形成元となるフレーム バッファの選択に表れる。フィールド構造化ピクチャのデュアル プライム動きタイプは常に、2 つの 16×16 予測ブロック (同パリティ予測および逆パリティ予測) で構成される。

2.4 ITU-T H.263

正式には "Video Coding for Low Bit Rate Communication" と呼ばれる ITU-T 勧告 H.263 は、H.261、MPEG-1、MPEG-2 と比較して圧縮パフォーマンスが向上した、比較的新しいビデオ コーダである。H.263 の最も基本的なフォーマットだけをサポートする、"ベースライン" モード処理を含む。また、各種の目的に使用できる多数のオプション拡張モード処理も含む。(1995 年後半に承認された初期バージョンでは、オプション モードは 5 つであったが、1997 年に技術的に完成した 2 番目のバージョンではいくつかのモードが追加され、2000 年にはさらにいくつかが追加される。) このインターフェイスでは、ベースライン H.263 予測は MPEG-1 機能のサブセットを使って動作する。ベースライン モードには順方向予測のみが含まれる。双方向予測は含まれていない。

丸め制御 : H.263 オプション モードの中には、丸め制御を必要とするものがある。この仕様では、丸め制御は bRcontrol フラグによってサポートされる。

H.263 補遺 D で定義されているように、H.263 オプション モードの中には、ピクチャの境界の外にアドレスする動きベクトルを許可するものがある。この仕様では、この機能は、アクセラレータがそのような動きをサポートする必要があるかどうか指定する bPicExtrapolation フラグによってサポートされる。そのような動きをサポートするには、2 つの基本的な方法がある : 1) 各サンプル フェッチのアドレスの値をクリッピングし、ピクチャの境界内に収まるようにする。2) 複製したサンプルをピクチャにパディングし、ピクチャの各境界にわたるマクロブロックの幅と高さによって使用されている実際のメモリ領域を広げる。結果はどちらも同じであるため、アクセラレータはどちらの方法でも使用できる。

双方向動き予測 : いくつかのオプション H.263 予測処理で使用されている双方向動き予測では、MPEG-1 とは異なり、丸め演算子として、丸めでなく切り捨ての区切りが使用される。この仕様では、この機能は、bBidirectionalAveragingMode フラグによってサポートされる。

4 MV 動き補償 (4MV) : H.263 の各マクロブロックのサイズは 16×16 であるが、補遺 F および J といったいくつかの H.263 のオプション モードでは、単一のマクロブロックに 4 つの動きベクトルが送信されることを許可する (マクロブロック内の各 8×8 輝度ブロックに 1 マクロブロック)。対応する 8×8 色光度領域は、派生した単一の動きベクトルを使用する。

重複ブロック動き補償 (OBMC : Overlapped Block Motion Compensation) : H.263 の 補遺 F は、4MV サポートのほかに、輝度サンプルの OBMC も含んでいる。この仕様では、OBMC 予測は、12 の動きベクトルをマクロブロックの順方向予測に送信することを許可することによってサポートされている。

OBMC 予測ブロックは、この仕様で与えられたツールによって、3 つのプレーンに構成された予測の組合せとしてハードウェア内で実現される。3 つのプレーンとは、現在のプレーン ("0")、上/下プレーン ("1")、および 左/右プレーン ("2") である。3 つのプレーンは、H.263 セクション F.3 で定義された q(x,y)、r(x,y)、および s(x,y) ブロックの一時記憶域として使用される。3 つのプレーンの 4 ブロックすべてが埋められると、H.263 セクション F.3 の式に従って結合され、H.263 の 図 F.2、F.3、F.4 で示された個々の H 行列によって重みが付けられる。

たとえば、OBMC 輝度マクロブロック予測は、8×4 形状の上/下予測ブロック 8 つ、4x8 形状の 左/右ブロック 8 つ、および 8×8 形状の現在のブロック 4 つで構成される。4 つのプレーン 0 動きベクトルが同じ動きベクトルを持っている場合 (4MV マクロブロックでない場合) は、単一の 16×16 マクロブロック予測を使って 16×16 プレーン 0 全体を埋めることができる。

この仕様での OBMC 処理の表現に関しては、10 個の動きベクトルがマクロブロックに送られる。最初の 4 つは現在のマクロブロックの Y0、Y1、Y2、Y3 ブロック用である。次にマクロブロックの上側の左半分および右半分のリモート ベクトルが送られる。その後マクロブロックの左側の上半分および下半分のリモート ベクトル、最後にマクロブロックの右側の上半分と下半分のリモート ベクトル、と続く。(H.263 では、マクロブロック下側の左半分と右半分に別個のリモート ベクトルが使用されず、現在のマクロブロックのベクトルが再利用される。)

図 4 -- OBMC 予測プレーン内の 1 つの 8×8 ブロックの H.263 登録

P-B フレーム (補遺 G & M) : このモードでは、P フレームおよび擬似 B フレームのマクロブロックは、まとめて一意の "PB フレーム" ピクチャ コーディング タイプに多重化される。各マクロブロックの B フレーム部分は、マクロブロックの P フレーム部分用にエンコードされた情報を取り入れる。B 部分の順方向および逆方向動きベクトルは、P 部分のベクトルからスケールされ、再構築された P 部分のマクロブロックは、B 部分の逆方向参照として使用される。逆方向マクロブロックは同じ PB マクロブロックに含まれる再構築された P マクロブロックしか参照できないため、PB には擬似 B フレームだけが含まれる。ただし従来の B フレーム セマンティクスと同様、PB フレーム内の B マクロブロックは、順方向参照フレーム内のどの場所でも参照できる。

逆方向参照に関するこの制限により、H.263 図 G.2 に示されているような、小さなサイズの逆方向予測ブロック形状が作成される。この仕様では、PB フレームを、2 つの動きベクトルを持つ個別のマクロブロック タイプとしてラベリングすることによってサポートしている。

ブロック解除フィルタ (補遺 J) : この仕様には、ブロック解除フィルタをアクセラレーションするための特別なコマンドが定義されている。このコマンドは、補遺 J と同様にループ内で使用するか、または H.261 ピクチャや H.263 ベースライン ピクチャの場合のようにループ外で使用する。ホスト CPU は、GOB またはスライス セグメントを監視するブロック解除コマンドを、必要に応じて作成しなければならない。

参照ピクチャ選択 (補遺 N および U) : 各予測ブロックのピクチャ インデックス選択フィールドを使うアクセラレータによって、複数の参照フレームがサポートされる。

スケーラビリティ (補遺 O) : この仕様のツールでは、一時スケーラビリティ、SNR スケーラビリティ、および空間スケーラビリティがサポートされる。この仕様の H.263 空間スケーラビリティ B フレームは、MPEG-1 の B フレームに非常に似ている。空間スケーラビリティでは、下位層の参照ピクチャをアップサンプルしたうえで、アップサンプルされたピクチャを参照として使用する必要がある (ほかのすべての側面では、SNR スケーラビリティおよび一時スケーラビリティと基本的に同一である)。H.263 の切り捨てには、適切な双方向平均化丸め制御を設定したほうがよい (MPEG-1 および MPEG-2 は上方バイアス平均化を使用し、H.263 は下方切り捨て平均化を使用する)。

参照ピクチャの再サンプリング (補遺 P) : この補遺の単純なフォーマットが、参照バッファの再サンプリングによってサポートされている。より豊富なフォーマットの補遺 P 再サンプリングについては、参照フレームとして使用される再構築されたフレームが、外的方法によって再サンプリングされ、アクセラレータからアドレス可能な参照フレーム バッファとして格納される必要がある。

解像度低減更新 (Reduced-Resolution Update) モード (補遺 Q) : H.263 の解像度低減更新モードでは、ブロック解除フィルタの別フォーマットおよび高度予測 OBMC (Advanced Prediction OBMC) の別フォーマットである、あまり一般的でない残余アップサンプリング条件が要求されるため、この仕様では現在サポートされていない。ただし、ブロック解除フィルタ (Deblocking Filter) モードがアクティブで、高度予測 (Advanced Prediction) モードがアクティブでない状態での処理は、ホストベースの IDCT 処理によって、このインターフェイスでもサポートできる可能性がある。

独立セグメント デコード (補遺 R) : 独立セグメント境界の下位およびアクセラレータ対応は存在しない。補遺 R のいくつかのフォーマットは、特別な処理なしにサポート可能である (ベースラインと 補遺 R の組み合わせなど)。ピクチャ セグメントの外挿を必要とする補遺 R のフォーマットは、各セグメントをピクチャとしてデコードし、その後それらの小さなピクチャから完全な出力ピクチャを構築することによってサポート可能である。

その他の H.263 オプション機能 : その他の H.263 オプション機能は、アクセラレータのインターフェイスに影響を与えることなくサポート可能である。たとえば、補遺 I、K、S、および T は、ホスト側の処理を変更することで、アクセラレータに影響を与えずに簡単に処理できる。

特定の IDCT : このインターフェイスでは、新しい H.263 オプション機能として近い将来追加されると思われる、特定の IDCT のサポート仕様が考慮されている。

2.5 MPEG-4

MPEG-4 は、プログレッシブ スキャン コーディングについては H.263 の規格、インターレースおよび 4:2:0 以外のカラー サンプリング フォーマットのサポートについては MPEG-2 の規格を大幅に取り入れている。この仕様にある、H.263 および MPEG-2 をサポートする機能は、MPEG-4 をサポートするために使用できる。1 ピクセルに対して 8 ビット以上をサポートするために、BPP パラメータが用意されている。シェープ コーディング、オブジェクト回転、フェース モデリング、メッシュ オブジェクト、スプライトといった MPEG-4 に固有の機能は、現在のインターフェイスではサポートされない。ただし、将来開発されるバリエーションで追加される可能性がある。

2.6 予測の原理

ブロック動き補償予測 (MCP) は、MPEG および H.26x ファミリの CODEC に、JPEG のような純粋な静止フレーム コーディング方法にはない利点を提供する基本ツールである。一般的な予測の例は、CODEC のさまざまなステージにあるが、MCP は最も多くの処理を必要とする。動きベクトル、DCT 係数、その他 MCP 処理の直接の一部でない要素も、転送後の状態をよりコンパクトにするために予測を利用する。これらの予測の例は、この仕様では解説しない。またこれらは、ホスト CPU プロセッサまたはビットストリーム パーサー/可変長デコード装置で実行されるものと見なす。

一般的な予測コーディング スキームでは、先に転送およびデコードされた要素が、現在の要素の予測として使用され、予測値と現在の要素の実際値との差異が予測誤差として送られる。転送された差異情報によって、正しい値、または必要とされる値に十分近い値 (MCP の場合) に、予測が更新される。先にデコードされたフレームは、将来のフレームがどのように見えたほうがよいかを予測 ("推測") するために使用される。その後差異データ (予測誤差) が推測を修正し、予測と予測誤差を組み合わせた (再構築された) イメージを、圧縮前のオリジナルの将来のフレームにできるだけ近付けようとする。

再構築が終わった現在の要素は、格納され、将来の要素の予測に使用される。この繰り返しのループは、予測される要素固有の各種のリセットによって壊される場合がある。リセットは、デコード処理のセマンティクスによって記述される。たとえば、動きベクトルや DC 係数予測はスライスでリセットされ、一時フレーム予測チェーン全体は、イントラ リフレッシュ フレームによってリセットされる。一時基本予測ループはこの記述に適合するが、予測として使用されるフレーム全体から取り出された修正データと共に動作する。予測として使用される参照フレームからのデータは、動きや、その他時間と共に生ずる変更内容に合わせて修正される。

図 5 -- 一般的な MCP 信号の流れ

2.6.1 予測のステージ

この仕様書の目的上、MCP によるマクロブロック予測の構造は、それぞれ独立した一連のフェーズとして説明しなければならない。この点を認識していると、この仕様書での MCP 処理に関する記述のフォーマットが理解しやすくなる。

図 6 -- MoComp3 予測ブロックの信号の流れ

ステージ 1. 参照フレームの形成

注 : 必要に応じて入力ピクチャの再サンプリングが含まれる場合がある。

図 7 -- MCP での予測データの進化

ステージ 2. 参照ブロック

参照ブロックは、予測ブロックと同じであるとは限らず、予測フィルタリング ステージで必要となる追加サンプルで構成される場合が多い。参照ブロックは、実装固有のピクチャ バッファ保持方法を反映した性質を持つことが多いため、この仕様書では定義していない。メモリ単位内でハーフサンプル フィルタリングが実行されない限り、16×16 ハーフサンプル フィルタされたマクロブロックの参照ブロックは、17x17 の形状を持つ。参照ブロックのサイズは、予測ブロックの大きさの関数でもあり、予測ブロックのフィルタ属性でもある。この仕様書では、参照ブロックは、動き補償予測 (MCP) で使用するために、参照フレーム バッファから抽出されたデータのブロックを参照しなければならない。

ステージ 3. 予測ブロック

フィルタされた参照ブロックの結果。

ステージ 4. 結合されたマクロブロック予測

1 つまたは複数の予測ブロックの平均化処理の結果。

2.6.2 マクロブロック部分

マクロブロックは、さまざまな性質を持つ領域を区分するために、通常のセグメントに分割される。

図 8 -- 基本的なマクロブロック分割スキーム

MPEG-2 では、マクロブロックの上部分と下部分が、時間的に離れた (最大 1/50 秒) インスタンスからキャプチャされた 2 つの異なるフィールドからのラインを表す。このため、マクロブロックの担当部分であるフレーム領域の 2 つのフィールド間に大きな動きがあった場合は、上部分と下部分に、相互関連性がまったくない内容が入る場合がある。予測の垂直方向の細分度を細かくするため、フィールド構造化ピクチャに 16×8 スキームが追加される。

図 9 -- MPEG-2 マクロブロックの 2 つの 16×8 部分

マクロブロックのパーティション分割によっても予測の細分度が細かくなり、動きの速度が異なる場合でも、エッジや小さなオブジェクトがより適切に表現される。予測ブロック自体は、未完成な、近似された形状であり、予測ブロックが表現するマクロブロックの部分に属するすべてのサンプルについての、ある種の平均的動きベクトルを表現している。サンプルまたはサブサンプルが各自の動きベクトルを持つことが理想的であるが、そうすると非常に大量のビットを消費し、処理のオーバーヘッドも増加する。予測ブロックは適切な程度の近似状態を維持する。

予測ブロックは、マクロブロックの 1 つの部分のみに対して働く。予測ブロック全体は、マクロブロックの 16×16 領域を担当する。これは、すべての H.261 および MPEG-1 予測で共通である。MPEG-2 では、マクロブロックのデュアル フィールド/フレームという性質に対応するため、16×8 予測形状が採用された。MPEG-2 フィールド構造化ピクチャで使用して予測の細分度を細かくするために、16×8 形状も取り入れられた。8×8 形状は H.263 (高度予測)、H.264、および MPEG-4 で使用されている。現在最も細分度が細かいのは、将来の "H.26L" 4×4 予測ブロック形状のドラフトである。

通常色光度予測ブロックは、対応する輝度予測ブロックに比べ、水平方向にも垂直方向にも半分のサイズであり、輝度に使用されたのと同じベクトルを共有する。これは、この仕様書で扱っている標準規格では、動きを常に成分平面に共存するものとしているためである。このため、それぞれの輝度および色光度サンプルのディメンションの違いを調整するため、色光度ベクトルは、何らかの手段によって輝度ベクトルからスケールされる。MPEG-2 の 16×8 輝度予測ブロックには、対応する 8×4 色光度形状がある。輝度予測ブロックが小さくなりすぎると、例外が多々発生する。たとえば、H.263 の高度予測モードでは、色光度予測ブロックの形状は 8×8 のままで、色光度動きベクトルは、4 つの 8×8 輝度動きベクトルの平均から派生する。この文書の多くの部分では、予測ブロック、プレーン、およびマクロブロックの、輝度の範囲のみについて述べる。特に明記しない限り、色光度については類推すること。

2.6.3 予測プレーン

図 10 -- MPEG-2 マクロブロック予測プレーン

上の図は、最終的なマクロブロック予測を形成する前に存在する、概念的なマクロブロック予測プレーンを示している。MPEG-2 には、順方向および逆方向 (双方向予測)、または同パリティおよび逆パリティ (デュアル プライム) の 2 つのプレーンがある。MPEG-1 および MPEG-2 では、単純な平均化処理によってプレーンが結合される。H.263 の重複ブロック動き補償予測 (Overlapped Block Motion Compensation Prediction) といった、より洗練された予測スキームの場合は、3 つのプレーンがある。将来は、最大 8 またはそれ以上の予測プレーンを、より洗練されたフィルタを使って結合するコーディング方法が採用される可能性がある。

DirectX VA データ構造とプログラム構成

3.1 暗号化サポート

アプリケーションのセキュリティ要求によっては、ビデオのデコードに使用されるデータの一部の暗号化が必要になる場合がある。そのようなアプリケーションをサポートするため、この仕様では、Direct VA データの暗号化が、その処理に定義された次の 3 つのデータ構造体に適用できるようになっている。

  • マクロブロック制御コマンド データ構造体
  • 残差ブロック データ構造体
  • ビットストリーム バッファの内容

ただし暗号化は、DirectX VA 処理の、中期的将来に向けたオプションである。すべてのアクセラレータは、暗号化を使用せずに処理を実行できなければならない。いくつかの暗号化プロトコルは、長期的将来には必要条件となる予定である。

内容を保護するためには、クリアテキスト データ処理のためのホストベースのソフトウェアとデータをわかりにくくすること、および暗号化処理を実行することが重要である。このような保護は、アクセラレータ側の暗号解読処理についても同様に重要である (暗号解読がハードウェアベースの処理である場合も同様)。

ホスト デコーダ ソフトウェアが暗号化を利用するには、アクセラレータがどのタイプの暗号化をサポートしているかを判断する必要がある。アクセラレータがサポートしている暗号化のタイプに関する基本情報は、ビデオ アクセラレータ タイプ GUID としてホストに供給される暗号化タイプ GUID のリストに含まれている。("暗号なし" の GUID である DXVA_NoEncrypt は、そのサポートが暗黙な必須条件になっているため、このリストで送信してはならない。)

ホストが、適用する暗号化プロトコルのタイプを選択し、セクション 3.2 で記述したように、GUID を通じてその選択肢をアクセラレータに指示する。典型的な暗号化の処理では、暗号化データを正しく転送するために、転送前にさらに次の 2 つの手順を実行する必要がある。

  • ホスト デコーダから、アクセラレータがデータ受信を承認されていることを検証するよう要求される場合がある。これを実行するには、認証された公開キーと秘密キーの組をアクセラレータが保持していることを証明する署名付きデータ構造体を、アクセラレータからホストに送信させる。
  • ホスト デコーダはその後、暗号化 "内容キー" をアクセラレータに送信する。

暗号化プロトコルを初期化するのに必要な手順の正確な数は、使用される暗号化のタイプによって異なる。暗号化処理の初期化のためにホストとアクセラレータの間で交換される各データ セットには、データの暗号化タイプを区別するため、暗号化プロトコル タイプ GUID が接頭辞として付いていなければならない (あるタイプの暗号化をあるタイプの DirectX VA バッファに使用し、ほかのタイプの暗号化をほかのタイプの DirectX VA バッファに使用する場合など)。

暗号化データ セットは、次によって指定される、実行されている処理が暗号化プロトコルであるという指示と交換される。

DXVA_EncryptProtocolFunc {
            EncryptProtocolFlag,     // 24b
            bDXVA_Func              //  8b
            }

EncryptProtocolFlag : 実行されている処理が暗号化プロトコル トランザクションであることを、24 ビットで示す。EncryptProtocolFlag は、ホスト ソフトウェア デコーダにより送信されるときには 0xFFFF00 と等しく、アクセラレータにより送信されるときには 0xFFFF08 でなければならない。

bDXVA_Func : 暗号化プロトコルを適用する DirectX VA の bDXVA_Func 機能を示す。現在この文書で定義されているように、暗号化サポートを要求する bDXVA_Func の値は 1 だけである。

ホストとアクセラレータの間でやり取りされる実際のデータ セットには、次のヘッダー情報が含まれていなければならない。

DXVA_EncryptProtocolHeader {
                dwFunction,              // 指示された処理
                dwReservedBits[3],       // 3 * 32b アラインメント
                guidEncryptProtocol     // 128b
                }

dwFunction : 内容が暗号化プロトコルに関するものであることを示す DXVA_EncryptProtocolFunction が含まれる。

guidEncryptProtocol : 暗号化プロトコルに関連付けられた GUID が含まれる。

3.2 グローバル制限モードの情報

デコーダがこの API を使って動作するためには、デコーダとビデオ アクセラレータの間で、処理における次の 2 つの側面について共通の認識が成り立っている必要がある :

  1. デコードされるビデオ データ フォーマットのタイプ。これは、DXVA_ConnectMode データ構造体を使用してここに成文化される。
  2. API の処理がどのように構成されるか。つまり、どの中間データ フォーマットが使用され、処理のどの側面がホスト、どの側面がアクセラレータに属するか。これは、使用される DXVA 機能それぞれの接続構成のネゴシエーションによって確立される。

DirectX VA のグローバル接続パラメータは、次の接続制限モードである。

DXVA_ConnectMode {
            guidMode,        // 128b
            wRestrictedMode // 16b
            }

guidMode : 使用される制限モード プロファイルに関連付けられた GUID。

wRestrictedMode : 接続制限モードを示す数値による識別子 (セクション 4 を参照)。

3.3 構成をプローブおよびロックする

構成を必要とする個々の DirectX VA 機能 (bDXVA_Func の特定値) の構成を確立する処理は、次のように実行される。

  1. 必要に応じて、構成がアクセラレータに受け付けられるかどうかを判断するためにプローブする。
  2. 構成がサポートされていれば、その構成にロックする。

特定構成サポートのプローブは、構成をプローブする特定 bDXVA_Func に対応するプローブ コマンドを、アクセラレータに送信することによって実行される。プローブ コマンドと共に、プローブでサポートの有無を判断する構成を記述する (DXVA_Func の値に固有の) 構成データ構造体が送信される。アクセラレータは、指定された構成をサポートしているかどうかを示す S_OK または S_FALSE を返す。さらに、代替として提案される構成も返す場合がある。

特定構成へのロックは、その構成にロックする特定 bDXVA_Func に対応するロック コマンドを、アクセラレータに送信することにより実行される。ロック コマンドと共に、サポートされている場合にロックする構成を記述する (bDXVA_Func の値に固有の) 構成データ構造体が送信される。アクセラレータは、指定された構成をアクセラレータがサポートしているかどうかを示す S_OK または S_FALSE を返す。S_OK の場合は、使用に備え、指定された構成にロックされる。S_FALSE の場合は、代替として提案される構成が返される。

デコーダは、指定された構成を調べるプローブ コマンドを事前に送信せずに、ロック コマンドを送信する可能性がある。アクセラレータは、特定の構成を調べるプローブ コマンドに S_OK を返した場合は、同じ構成へのロック コマンドにも、特に明記されていない限り S_OK を返さなければならない。

ロック コマンドを送信し、許可を示す結果が返されて使用が認められると、指定した構成にロックされる。これ以後、同じ値の bDXVA_Func に対応するプローブ コマンドまたはロック コマンドが、デコーダから送信されてはならない。

すべての DirectX VA ソフトウェア デコーダが、すべての DirectX VA アクセラレータと共に動作できるように、特定の bDXVA_Func を使用するあらゆるソフトウェア デコーダがサポートしなければならないすべての構成のセットとして、最小限の相互動作性構成セットが定義される。bDXVA_Func のサポートを示すすべてのアクセラレータは、関連付けられたビデオ アクセラレータの GUID を公開することにより、最小限の相互動作性構成セットのうち少なくとも 1 つのメンバをサポートしなければならない。場合によっては、補足的な推奨構成セットも定義される可能性がある。

プローブおよびロックは、プローブ コマンドまたはロック コマンドで送信されるデータ構造体の最初のメンバとして渡される DXVA_ConfigQueryOrReplyFunc により制御される。

DXVA_ConfigQueryOrReplyFunc {
                QueryOrReplyFlag,        // 24b
                bDXVA_Func              //  8b
                }

QueryOrReplyFlag : 指定する照会または応答のタイプ。以下のように定義される。

  • 0xFFFFF1 : ソフトウェア デコーダが、プローブ コマンドとして送信する。
  • 0xFFFFF5 : ソフトウェア デコーダが、ロック コマンドとして送信する。
  • 0xFFFFF8 : アクセラレータが、プローブ コマンド対して S_OK 応答とプローブされた構成のコピーを返す場合に、共に送信する。
  • 0xFFFFF9 : アクセラレータが、プローブ コマンドに対して S_OK 応答を返すが、代替構成も提案する場合に、共に送信する。
  • 0xFFFFFC : アクセラレータが、ロック コマンドに対して S_OK 応答とロックされた構成のコピーを返す場合に、共に送信する。
  • 0xFFFFFB : アクセラレータが、プローブ コマンドに対して S_FALSE 応答と提案する代替構成を返す場合に、共に送信する。
  • 0xFFFFFF : アクセラレータが、ロック コマンドに対して S_FALSE 応答と提案する代替構成を返す場合に、共に送信する。
QueryOrReplyFlag の下位 4 ビットは、以下のように解釈できる。

  • ビット 3 : ホスト デコーダから送信された = "0"、アクセラレータから送信された = "1"。
  • ビット 2 : プローブに関連付けられている = "0"、ロックに関連付けられている = "1"。
  • ビット 1 : 成功 = "0"、失敗 = "1"。
  • ビット 0 : 複製された構成構造体 = "0"、新しい構造体 = "1"。

bDXVA_Func : 同時に送信された構成が適用される bDXVA_Func 機能。

3.4 バッファ記述リスト

DirectX VA は主として、データのバッファをホストからアクセラレータに渡すことによって動作する。DXVA 機能のパラメータ (bDXVA_Func) により、渡される可能性があるバッファのタイプ、および実行される DXVA タスクが決定する。次のような各種バッファ タイプがここに定義されている。

  1. ピクチャ デコード パラメータ バッファ
  2. マクロブロック制御コマンド バッファ (残差ブロック データ バッファと深く関連し、それと 1:1 で対応する)
  3. 残差ブロック データ バッファ
  4. ブロック解除フィルタ制御コマンド バッファ (フィルタ効力の制限あり、または制限なし)
  5. 逆量子化行列バッファ (オフホストの VLD 処理でのみ使用)
  6. スライス制御バッファ (ビットストリーム データ バッファと深く関連している)
  7. ビットストリーム データ バッファ
  8. AYUV アルファ ブレンディング サンプル バッファ
  9. IA44/AI44 アルファ ブレンディング サーフェス バッファ
  10. DPXD アルファ ブレンディング サーフェス バッファ
  11. ハイライト データ バッファ
  12. DCCMD データ バッファ
  13. アルファ ブレンド コンビネーション バッファ
  14. ピクチャ再サンプリング制御バッファ
  15. 最終結果のピクチャのマクロブロックをホストに読み戻すコマンドを格納した読み戻しバッファ

バッファの 1 セットがホストからアクセラレータに渡されるとき、それらのバッファに関する追加データも渡される。この追加データのことを、バッファ記述リストと呼ぶ。バッファ記述リストは、順序付きリストで構成されている。このリストは、先に列挙した最初のタイプの最初のバッファで始まり、次は同タイプの次のバッファと続き、その後次のタイプの最初のバッファ、というように移っていく。リストの各メンバは、次のように定義されたデータ構造体で構成されている。

DXVA_BufferDescription {
             dwTypeIndex,       // 32b
             dwBufferIndex,     // 32b
             dwDataOffset,      // 32b
             dwDataSize,        // 32b
             dwFirstMBaddress,  // 32b
             dwNumMBsInBuffer,  // 32b
             dwWidth,           // 32b
             dwHeight,          // 32b
             dwStride,          // 32b
             dwReservedBits     // 32b
            }

dwTypeIndex : このセクションで前述したリストにある、該当するバッファのタイプ番号。

dwBufferIndex : 同じバッファ記述リスト内で渡される同じタイプのバッファ内でのバッファのシーケンス番号。

dwDataOffset : バッファの先頭からの該当データのオフセット (バイト単位)。0 でなければならない。

dwDataSize : バッファ内の該当データの量 (バイト単位)。つまり、バッファ内容の最後のバイトの位置は、dwDataOffset + dwDataSize - 1 で与えられる。

dwFirstMBaddress : ラスタ スキャン順序で表した、バッファ内の最初のマクロブロックのマクロブロック アドレス (0 は左上マクロブロックのアドレス、PicWidthInMBminus1 は右上マクロブロックのアドレス、PicHeightInMBminus1 * PicWidthInMB は左下マクロブロックのアドレス、PicHeightInMBminus1 * PicWidthInMB + PicWidthInMBminus1 は右下マクロブロックのアドレスとなる)。データ バッファが、ピクチャ デコード パラメータ、逆量子化行列、スライス コントロール、ビットストリーム データ、AYUV、IA44/AI44、DPXD、ハイライト、DCCMD のいずれかのタイプである場合は、0 でなければならない。もしそのデータ バッファが残差ブロック バッファなら、dwFirstMBaddress は対応するマクロブロック コントロール コマンド バッファと同じ値を持つべきである。

dwNumMBsInBuffer : バッファ内のデータのマクロブロック数。データ バッファが、ピクチャ デコード パラメータ、逆量子化行列、AYUV、IA44/AI44、DPXD、Highlight、DCCMD のいずれかのタイプである場合は、0 でなければならない。データバッファがマクロブロック コントロール バッファなら、dwNumMBsInBuffer は MBskipsFollowing の値とマクロブロック コントロール ブロック バッファ内のマクロブロック コントロール コマンドの総数の和と等しいべきである。データバッファが残差ブロック データ バッファなら、dwNumMBsInBuffer は対応するマクロブロック コントロール コマンド バッファと同じ値を持つべきである。データバッファがスライス コントロール コマンド バッファなら、dwNumMBsInBuffer はスライスコントロールバッファ内の wNumberMBsInSlice の総数と等しいべきである。データバッファがビットストリーム データ バッファなら、dwNumMBsInBuffer は対応するスライス コントロール コマンドバッファと同じ値を持つべきである。

dwWidth、dwHeight、dwStride : バッファ内のデータの幅、高さ、およびストライド。データ バッファが IA44/AI44 または DPXD のいずれかのタイプでない限り、0 でなければならない。適用されるバッファ タイプに対しては、アクセラレータが実行するバッファ割り当てセットアップによって dwStride が決定される。

注: デコーダは IA44/AI44 あるいは DPXD に指定されているストライドを守ることに必ず注意しなければならない。

3.5 圧縮ピクチャのデコード (bDXVA_Func=1)

DirectX VA 処理のために定義された最初の関数タイプは、圧縮ピクチャの一部または全部のデコードである。

3.5.1 接続構成

圧縮ピクチャをデコードするための DirectX VA 接続構成データ構造体は、次のように定義されなければならない。

DXVA_ConfigPictureDecode {
                dwFunction,                      // 指定された処理  32b
                dwReservedBits[3],               // 3 * 32b アラインメント
                guidConfigBitstreamEncryption,   // 暗号化タイプの GUID 128b
                guidConfigMBcontrolEncryption,
                guidConfigResidDiffEncryption,
                bConfigBitstreamRaw,             // ビットストリーム処理  8b
                bConfigMBcontrolRasterOrder,     // マクロブロック制御   8b
                bConfigResidDiffHost,            // ホスト残差  8b
                bConfigSpatialResid8,            // 8b
                bConfigResid8Subtraction,        // 8b
                bConfigSpatialHost8or9Clipping,  // 8b
                bConfigSpatialResidInterleaved,  // 8b
                bConfigIntraResidUnsigned,       // 8b
                bConfigResidDiffAccelerator,     // アクセラレータ残差  8b
                bConfigHostInverseScan,          // 8b
                bConfigSpecificIDCT,             // 8b
                bConfig4GroupedCoefs             // 8b
}

dwFunction : 構成データの構造を記述する DXVA_ConfigQueryOrReplyFunc を含む。

guidConfigBitstreamEncryption : ビットストリーム データ バッファの暗号プロトコル タイプに関連付けられた GUID を表す。DXVA_NoEncrypt という値 (関連付けられたヘッダー ファイル内に定義された GUID 名) は、暗号が適用されていないことを意味する。bConfigBitstreamRaw が "0" の場合は、DXVA_NoEncrypt でなければならない。

guidConfigMBcontrolEncryption : マクロブロック制御データ バッファの暗号プロトコル タイプに関連付けられた GUID を表す。DXVA_NoEncrypt という値 (関連付けられたヘッダー ファイル内に定義された GUID 名) は、暗号が適用されていないことを意味する。bConfigBitstreamRaw が "1" の場合は、DXVA_NoEncrypt でなければならない。

guidConfigResidDiffEncryption : 残差デコード データ バッファ (空間領域データ、またはアクセラレータベース IDCT の変換領域係数セットを含むバッファ) の暗号プロトコル タイプに関連付けられた GUID を表す。DXVA_NoEncrypt という値 (関連付けられたヘッダー ファイル内に定義された GUID 名) は、暗号が適用されていないことを意味する。bConfigBitstreamRaw が "1" の場合は、DXVA_NoEncrypt でなければならない。

bConfigBitstreamRaw : 値 "1" は、ピクチャのデータが、生のビットストリーム コンテンツとしてビットストリーム バッファ内に送信されることを示す。値 "0" は、ピクチャ データがマクロブロック制御コマンド バッファを使って送信されることを示す。bConfigResidDiffHost が "1" の場合、または bConfigResidDiffAccelerator が "1" の場合は、"0" でなければならない。中期的な条件は、"0" をサポートすることである。さらに "1" がサポートすることが望ましい。

bConfigMBcontrolRasterOrder : 値 "1" は、各マクロブロック制御コマンド バッファ内のマクロブロック制御コマンドが、ラスタスキャンの順になっていなければならないことを示す。値 "0" は、任意の順であることを示す。ビットストリームのタイプによっては、ラスタ順序を強制すると、処理が必要なマクロブロック制御バッファの数が非常に増えたり、制御情報をホスト側で並べ替える必要が生じたりする。このため、任意の順序をサポートすることは、デコード処理に有利である。たとえば、H.261 CIF 解像度のデコードでは、各バッファ内がラスタスキャンの順序になっている必要がある場合は、1 ピクチャごとに 36 のマクロブロック制御バッファが要る (H.263 補遺 K の任意スライス順序および矩形スライス モードでも同様の影響がある)。中期的な条件は、"0" をサポートすることである。短期的には "1" のサポートも容認されるが、低レベルの機能であり、あまり推奨されない。

bConfigResidDiffHost : 値 "1" は、いくつかの残差デコード データが、空間領域内のブロックとしてホストから送信される可能性があることを示す。値 "0" は、空間領域データが送信されないことを示す。bConfigBitstreamRaw が "1" の場合は、"0" でなければならない。中期的な条件は、"1" をサポートすることである。これは推奨される値である。

bConfigSpatialResid8: ホストベースの残差デコードを使うとき (ie. bConfigResidDiffHost が "1" のとき) 、予測される (ie 非イントラ) ピクチャの残差空間領域ブロックに用いる WORD サイズを示す。

bConfigSpatialResid8 が "1" かつ bConfigResidDiffHost が "1" なら次のことを示す、ホストは符号付き 8 ビットサンプルを使用する非イントラ マクロブロックについては残差空間領域ブロックを送り、フォーマットが bConfigIntraResidUnsigned に依存する予測される (ie. 非イントラ) ピクチャのイントラ マクロブロックについては次のようになる :

  • bConfigIntraResidUnsigned が "0" なら、イントラ マクロブロックの空間領域ブロックは一定参照値 2(BPP-1) に相対した 8 ビット符号付き整数値として送られる、そして
  • bConfigIntraResidUnsigned が "1" なら、イントラ マクロブロックの空間領域ブロックは一定参照値 0 に相対した 8 ビット符号なし整数値として送られる。

bConfigSpatialResid8 が "0" かつ bConfigResidDiffHost が "1" なら次のことを示す、ホストは符号付き 16 ビットサンプルを使用する非イントラ マクロブロックについては残差空間領域ブロックを送り、フォーマットが bConfigIntraResidUnsigned に依存する予測される (ie. 非イントラ) ピクチャのイントラ マクロブロックについては次のようになる :

  • bConfigIntraResidUnsigned が "0" なら、イントラ マクロブロックの空間領域ブロックは一定参照値 2(BPP-1) に相対した 16 ビット符号付き整数値として送られる、そして
  • bConfigIntraResidUnsigned が "1" なら、イントラ マクロブロックの空間領域ブロックは一定参照値 0 に相対した 16 ビット符号なし整数値として送られる。

bConfigResidDiffHost が "0" なら bConfigSpatialResid8 は "0" であるべきである。このスペックは bConfigResidDiffHost が "1" のとき、bConfigSpatialResid8 が持つべき値の参照を持たない。

注 : 非予測 (イントラ) ピクチャの場合、空間領域ブロックは、BPP = 8 の場合は常に 8 ビット サンプルを使って送信され、BPP > 8 の場合は 16 ビット サンプルを使って送信されなければならない。bConfigIntraResidUnsigned が "0" なら、これらのサンプルは一定参照値 2(BPP-1) に相対した符号付き整数値として送られ、ConfigIntraResidUnsigned が "1" なら、一定参照値 0 に相対した符号なし整数値として送られる。

bConfigResid8Subtraction : bConfigSpatialResid8 が "1" の場合に、値 "1" は、8 ビット差異のオーバーフロー ブロックが加算でなく減算されることを示す。bConfigSpatialResid8 が "1" でない場合は、"0" でなければならない。"1" の場合、これはあらゆるオーバーフロー ブロックが加算でなく減算されることを示す。中期的な条件は、bConfigSpatialResid8 が "1" の場合の "1" をサポートすることである。差異を加算するのでなく減算できることによって、8 ビット差異デコードが、ビデオ デコーダの仕様で必要となる値の全範囲である ±255 に完全に対応できる。これは、2 つの符号付き 8 ビット数値の加算で +255 を表現することはできないが、2 つの符号付き 8 ビット数値の差異を使えば ±255 の範囲のあらゆる数値を表現できるためである (+255 = +127 マイナス -128)。

bConfigSpatialHost8or9Clipping : bConfigSpatialResid8 = "0" かつ bConfigResidDiffHost = "1" の場合、値 "1" は、イントラ マクロブロックの空間領域ブロックがホスト上の 8 ビット範囲にクリップされ、非イントラ マクロブロックの空間領域ブロックがホスト上の 9 ビット範囲にクリップされなければならないことを示す。値 "0" は、ホストによってそのようなクリッピングが実行される必要がないことを示す。bConfigSpatialResid8 = "0" で bConfigResidDiffHost = "1" でない限り、"0" でなければならない。中期的な条件は、"0" をサポートすることである。短期的には "1" のサポートも容認されるが、低レベルのアクセラレータ機能であり、あまり推奨されない。

bConfigSpatialResidInterleaved : bConfigResidDiffHost が "1" で、YUV フォーマットが "NV12" または "NV21" のときにこの値が "1" の場合は、すべての空間領域残差データが、YUV フォーマットのクロマ インターリーブ パターンに一致するクロマインターリーブ フォーマットで送信されなければならないことを示す。bConfigResidDiffHost が "1" で YUV フォーマットが "NV12" または "NV21" でない限り、"0" でなければならない。中期的な条件は、"0" をサポートすることである。短期的には "1" のサポートも容認されるが、低レベルのアクセラレータ機能であり、あまり推奨されない。

bConfigIntraResidUnsigned: ホストベースの残差デコードを使うとき (ie. bConfigResidDiffHost が "1" のとき) 、イントラ ブロックに関する残差空間領域ブロック表示のメソッドを示す。

bConfigIntraResidUnsigned が "0" かつ bConfigResidDiffHost が "1"なら次のことを示す、イントラ マクロブロックの空間領域残差データ ブロックは以下のように送られる :

  • 非イントラ ピクチャの場合 bConfigSpatialResid8 が "0" なら、イントラ マクロブロックの空間領域残差データ ブロックは一定参照値 2(BPP-1) に相対した 16 ビット符号付き整数値として送られる。
  • 非イントラ ピクチャの場合 bConfigSpatialResid8 が "1" なら、そして イントラ ピクチャの場合 BPP が "8" と等しければ (bConfigSpatialResid8 の値とは関係なく)、イントラ マクロブロックの空間領域残差データ ブロックは一定参照値 2(BPP-1) に相対した 8 ビット符号付き整数値として送られる。

bConfigIntraResidUnsigned が "1" かつ bConfigResidDiffHost が "1" なら、イントラ マクロブロックの空間領域残差データ ブロックは以下のように送られる :

  • 非イントラ ピクチャの場合 bConfigSpatialResid8 が "0" なら、イントラ マクロブロックの空間領域残差データ ブロックは一定参照値 0 に相対した 16 ビット符号付き整数値として送られる。
  • 非イントラ ピクチャの場合 bConfigSpatialResid8 が "1" なら、そして イントラ ピクチャの場合 BPP が "8" と等しければ (bConfigSpatialResid8 の値とは関係なく)、イントラ マクロブロックの空間領域残差データ ブロックは一定参照値 0 に相対した 8 ビット符号付き整数値として送られる。

bConfigResidDiffHost が "1" でなければ、bConfigIntraResidUnsigned は "0" であるべきだ。"1" と等しい bConfigIntraResidUnsigned により近いタームのサポートは許可されるが、"0" と等しい bConfigIntraResidUnsigned がより好ましく、アクセラレータ能力のレベルが低いと解釈される。

bConfigResidDiffAccelerator : 値 "1" は、係数データの変換領域ブロックが、アクセラレータベースの IDCT のためにホストから送信される可能性があることを示す。値 "0" は、アクセラレータベースの IDCT が使用されないことを示す。bConfigResidDiffHost および bConfigResidDiffAccelerator の両方が "1" の場合は、マクロブロックレベル制御コマンドで示されたように、残差デコードの一部がホスト上で実行され、一部がアクセラレータ上で実行されることを示す。bConfigBitstreamRaw が "1" の場合は、"0" でなければならない。bConfigResidDiffAccelerator = "1" のサポートが必要であるが、このサポートに関しては、中期的な条件は設定されない。bConfigResidDiffAccelerator が "1" であり、bConfigResidDiffHost も "1" である場合がサポートされるということは、残差デコードが、マクロブロックごとに、ホストとアクセラレータの間で共有できることを示す。これは、bConfigResidDiffAccelerator が "1" であり bConfigResidDiffHost が "0" である場合よりも高いアクセラレータ機能であると見なされる

bConfigHostInverseScan : 値 "1" は、変換領域ブロック処理の逆スキャンがホスト上で実行され、変換係数の代わりに絶対インデックスが送信されることを示す。値 "0" は、逆スキャンがアクセラレータ上で実行されることを示す。bConfigResidDiffAccelerator が "0" の場合は、"0" でなければならない。bConfig4GroupedCoefs が "0" の場合は、"1" でなければならない。中期的な条件は、bConfigResidDiffAccelerator が "1" の場合に "1" をサポートすることである。短期的には bConfig4GroupedCoefs が "1" の場合に "0" をサポートすることも容認されるが、あまり推奨されない。これは、低レベルのアクセラレータ機能であり、任意のスキャン パターンをサポートする柔軟性に欠け、ホストでの逆スキャンによるホスト ソフトウェア デコーダ処理の負担増はほとんどないと考えられるためである。

bConfigSpecificIDCT : 値 "1" は、ITU-T 勧告 H.263 の補遺 W で定義された IDCT が使用されることを示し、値 "0" は、オフホストの IDCT に、あらゆる準拠 IDCT が使用できることを示す。(注 : ドラフト段階にある参照先の補遺は、まだ ITU-T の最終承認を受けていない。ITU 内で変更があった場合、このビットはドラフト バージョンでなく最終バージョンを参照する。また、参照先ドラフトは MPEG-2 正誤表 2 にある IDCT の条件を満たさず、したがって MPEG-2 ビデオに使用する場合に bConfigSpecificIDCT を 1 としてはならない点にも注意したほうがよい) bConfigResidDiffAccelerator が "0" の場合は、0 でなければならない (純粋にホストベースの残差デコードであることを示す)。中期的な条件は、bConfigResidDiffAccelerator が "1" の場合に "0" がサポートされることである。さらに "1" がサポートされることが望ましい。これら以外の値も将来定義される可能性がある。

bConfig4GroupedCoefs : 値 "1" は、オフホストの IDCT 用の変換係数が、DXVA_TCoefSingle データ構造体でなく DXVA_TCoef4Group データ構造体を使って送信されることを示す。bConfigResidDiffAccelerator が "0" の場合、または bConfigHostInverseScan が "1" の場合は、"0" でなければならない。中期的な条件は、bConfigResidDiffAccelerator が "1" の場合に "0" がサポートされることである。短期的には bConfigHostInverseScan が "0" の場合に "1" をサポートすることも容認されるが、低レベルのアクセラレータ機能であり、あまり推奨されない。

3.5.2 最小限の相互動作性構成セット

設計上の条件として、すべての DirectX VA デコーダは、すべての DirectX VA アクセラレータと相互動作する必要がある。このためには、すべての DirectX VA デコーダが、接続構成セットのすべてのメンバと共に動作でき、すべての DirectX VA アクセラレータが、同セットに属する少なくとも 1 つの接続構成メンバと共に動作できる必要がある。最小限の相互動作性セットは次のように定義される。

  1. この最も基本的なセットのすべてのメンバは次の共通点を持つ。
    1. guidConfigBitstreamEncryption = DXVA_NoEncrypt
    2. guidConfigMBcontrolEncryption = DXVA_NoEncrypt
    3. guidConfigResidDiffEncryption = DXVA_NoEncrypt
    4. bConfigBitstreamRaw = 0
    5. bConfigHostInverseScan = 0
    6. bConfigSpecificIDCT = 0
  2. このセットの最初の 2 つのメンバ (ここに属するアクセラレータは、bConfigSpatialHost8or9Clipping = 0 のバリエーションをサポートすることを推奨される) は、次によって定義される。
    1. bConfigMBcontrolRasterOrder = 1
    2. bConfigResidDiffHost = 1
    3. bConfigSpatialResid8 = 0
    4. bConfigResid8Subtraction = 0
    5. bConfigSpatialHost8or9Clipping = 0 or 1
    6. bConfigSpatialResidInterleaved = 0
    7. bConfigIntraResidUnsigned = 0
    8. bConfigResidDiffAccelerator = 0
  3. セットの 3 番目のメンバ (アクセラレータ実装を特に推奨されない) は、次のとおり。
    1. bConfigMBcontrolRasterOrder = 1
    2. bConfigResidDiffHost = 1
    3. bConfigSpatialResid8 = 1
    4. bConfigResid8Subtraction = 0
    5. bConfigSpatialHost8or9Clipping = 0
    6. bConfigSpatialResidInterleaved = 1
    7. bConfigIntraResidUnsigned = 0
    8. bConfigResidDiffAccelerator = 0
  4. セットの 4 番目のメンバ (アクセラレータ実装を特に推奨されない) は、次のとおり。
    1. bConfigMBcontrolRasterOrder = 1
    2. bConfigResidDiffHost = 1
    3. bConfigSpatialResid8 = 0
    4. bConfigResid8Subtraction = 0
    5. bConfigSpatialHost8or9Clipping = 1
    6. bConfigSpatialResidInterleaved = 0
    7. bConfigIntraResidUnsigned = 1
    8. bConfigResidDiffAccelerator = 0
  5. このセットに含まれる残り 2 つのメンバ (ここに属するアクセラレータは、bConfigResid8Subtraction = 1 のバリエーションをサポートすることを推奨される) は、次によって定義される。
    1. bConfigMBcontrolRasterOrder = 1
    2. bConfigResidDiffHost = 1
    3. bConfigSpatialResid8 = 1
    4. bConfigResid8Subtraction = 0 or 1
    5. bConfigSpatialHost8or9Clipping = 0
    6. bConfigSpatialResidInterleaved = 0
    7. bConfigIntraResidUnsigned = 0
    8. bConfigResidDiffAccelerator = 0
  6. このセットに含まれる残り 1 つのメンバは4章に説明され、DXVA_ConnectMode に示されている MPEG2_C と MPEG2_D 限定モード プロファイル用にのみ定義される。他のプロファイルは最小インターオペラビリティ セットのこの構成には含まれない。この追加メンバは次によって定義される。
    1. bConfigMBcontrolRasterOrder = 1
    2. bConfigResidDiffHost = 0
    3. bConfigResidDiffAccelerator = 1
    4. bConfigHostInverseScan = 0
    5. bConfig4GroupedCoefs = 1

3.5.3 補足的な推奨構成セット

ソフトウェア デコーダでは、いくつかの補足的構成をサポートすることを推奨する。これは、量産されるハードウェアにこれらの構成が存在し、これらの構成は最小限の構成セットより圧倒的に高いパフォーマンスを提供しうると考えられるからである。推奨構成セットは以下のとおり。

  1. このセットのメンバすべてに共通の性質は以下のとおり。
    1. guidConfigBitstreamEncryption = DXVA_NoEncrypt
    2. guidConfigMBcontrolEncryption = DXVA_NoEncrypt
    3. guidConfigResidDiffEncryption = DXVA_NoEncrypt
    4. bConfigMBcontrolRasterOrder = 0
    5. bConfigResidDiffHost = 0
    6. bConfigSpatialResid8 = 0
    7. bConfigResid8Subtraction = 0
    8. bConfigSpatialHost8or9Clipping = 0
    9. bConfigSpatialResidInterleaved = 0
    10. bConfigSpecificIDCT = 0
  2. このセットの最初のメンバは、オフホストのビットストリーム処理のアクセラレーションを適切にサポートするため、次のように定義される。
    1. bConfigBitstreamRaw = 1
    2. bConfigResidDiffAccelerator = 0
    3. bConfigHostInverseScan = 0
    4. bConfig4GroupedCoefs = 0
  3. このセットの 2 番目のメンバは、オフホストの IDCT アクセラレーションを適切にサポートするため、次のように定義される。
    1. bConfigBitstreamRaw = 0
    2. bConfigResidDiffAccelerator = 1
    3. bConfigHostInverseScan = 1
    4. bConfig4GroupedCoefs = 0
  4. このセットの 3 番目のメンバ (2 番目のメンバと比較するとアクセラレータにはあまり推奨されない) は、一部の実装に見られると予想されるオフホスト IDCT をサポートするため、次のように定義される。
    1. bConfigBitstreamRaw = 0
    2. bConfigResidDiffAccelerator = 1
    3. bConfigHostInverseScan = 0
    4. bConfig4GroupedCoefs = 1

推奨構成セットの最初のメンバをサポートするアクセラレータは、そのアクセラレーション能力の使い方に柔軟性を持たせるため、2 番目のメンバもサポートすることを強く推奨する。

3.5.4 圧縮ピクチャのパラメータ

ピクチャ 1 つにつき、次の変数が 1 回送信されなければならない。

DXVA_PictureParameters {
                wDecodedPictureIndex        // 16b
                wDeblockedPictureIndex      // 16b

                wForwardRefPictureIndex     // 16b
                wBackwardRefPictureIndex    // 16b

                wPicWidthInMBminus1         // 16b
                wPicHeightInMBminus1        // 16b

                bMacroblockWidthMinus1      // 8b
                bMacroblockHeightMinus1     // 8b

                bBlockWidthMinus1           // 8b
                bBlockHeightMinus1          // 8b

                bBPPminus1                  // 8b

                bPicStructure               // 8b
                bSecondField                // 8b
                bPicIntra                   // 8b
                bPicBackwardPrediction      // 8b

                bBidirectionalAveragingMode // 8b
                bMVprecisionAndChromaRelation   // 8b
                bChromaFormat                   // 8b
                bPicScanFixed                   // 8b
                bPicScanMethod                  // 8b
                bPicReadbackRequests            // 8b

                bRcontrol                       // 8b
                bPicSpatialResid8               // 8b
                bPicOverflowBlocks              // 8b
                bPicExtrapolation               // 8b

                bPicDeblocked                   // 8b
                bPicDeblockConfined             // 8b
                bPic4MVallowed                  // 8b
                bPicOBMC                        // 8b
                bPicBinPB                       // 8b
                bMV_RPS                         // 8b
                bReservedBits                   //  8b (アラインメント)

                wBitstreamFcodes                // 16b
                wBitstreamPCEelements           // 16b
                bBitstreamConcealmentNeed       // 8b
                bBitstreamConcealmentMethod     // 8b
                }

wDecodedPictureIndex : デコードされたマクロブロックの宛先フレーム バッファを指定する。

wDeblockedPictureIndex : bPicDeblocked が "1" の場合に、ブロック解除された出力ピクチャの宛先フレーム バッファを指定する。bPicDeblocked が "0" の場合は意味がなく、"0" でなければならない。wDecodedPictureIndex と同じになる場合がある。

wForwardRefPictureIndex : 現在のピクチャの "順方向予測" の参照ピクチャとして使用されるピクチャのフレーム バッファ インデックスを指定する。wDecodedPictureIndex と同じにしてはならない。bPicIntra が "1" なら 0xFFFF となるべきである。

wBackwardRefPictureIndex : 現在のピクチャの "逆方向予測" の参照ピクチャとして使用されるピクチャのフレーム バッファ インデックスを指定する。逆方向参照動き予測が使用される場合は、wDecodedPictureIndex と同じにしてはならない。bPicBackwardPrediction が "0" なら 0xFFFF となるべきである

wPicWidthInMBminus1 : クロブロックの単位で表した、現在のピクチャの幅マイナス 1 を指定する。派生語である PicWidthInMB は、PicWidthInMBminus1 に 1 を足したものである。

wPicHeightInMBminus1 : マクロブロックの単位で表した、現在のピクチャの高さマイナス 1 を指定する。派生語である PicHeightInMB は、PicHeightInMBminus1 に 1 を足したものである。

bMacroblockWidthMinus1 : マクロブロックの宛先輝度サンプルの幅を指定する。MPEG-1、MPEG-2、H.263、MPEG-4 の場合は "15" となる。派生語である MacroblockWidth は、bMacroblockWidthMinus1 に 1 を足したものである。

bMacroblockHeightMinus1 : マクロブロックの宛先輝度サンプルの高さを指定する。MPEG-1、MPEG-2、H.261、H.263、MPEG-4 の場合は "15" となる。派生語である MacroblockHeight は、bMacroblockHeightMinus1 に 1 を足したものである。

bBlockWidthMinus1 : 残差ブロックのブロック幅を指定する。MPEG-1、MPEG-2、H.261、H.263、MPEG-4 の場合は "7" となる。bConfig4GroupedCoefs が "1" の場合は、"7" でなければならない。マクロブロック内の残差ブロックは、MPEG-2 図 6-10、6-11、6-12 で指定された順に送信される (ラスタスキャン順の Y、ラスタスキャン順の Cb の全 4:2:0 ブロック、Cr の 4:2:0 ブロック、Cb の 4:2:2 ブロック、Cr の 4:2:2 ブロック、Cb の 4:4:4 ブロック、Cr の 4:4:4 ブロックの順)。派生語である WT は、BlockWidthMinus1 に 1 を足したものである。

bBlockHeightMinus1 : IDCT ブロックのブロックの高さを指定する。MPEG-1、MPEG-2、H.261、H.263、MPEG-4 の場合は "7" となる。bConfig4GroupedCoefs が "1" の場合は、"7" でなければならない。派生語である HT は、BlockHeightMinus1 に 1 を足したものである。

bBPPminus1 : ビデオ サンプル値の、ピクセルごとのビット数を指定する。最小でも、8 ビット ピクセルを表す "7" でなければならない。MPEG-1、MPEG-2、H.261、H.263 の場合は "7" となる。MPEG-4 のいくつかの処理モードでは、1 ピクセルごとのビット数を多くできる。派生語である BPP は、bBPPminus1 に 1 を足したものである。

bPicStructure : このパラメータは、MPEG-2 の セクション 6.3.10 および表 6-14 で定義されている picture_structure パラメータと同じ意味を持ち、現在のピクチャが、上フィールド ピクチャ (値 '01')、下フィールド ピクチャ (値 '10')、フレーム ピクチャ (値 '11') のどれであるのかを示す。H.261 のようなプログレッシブスキャン フレーム構造化コーディングの場合、bPicStructure は '11' でなければならない。bPicStructure が '10' (下フィールド) でない限り、派生パラメータである PicCurrentField は "0" として定義され、その場合このパラメータは "1" となる。

bSecondField : フィールド構造化コーディング (bPicStructure が '01' または '10' のとき) の場合に、現在のフィールドがピクチャの 2 番目のフィールドであるかどうかを示す。これは、動き補償予測のために逆パリティ ラインの参照として使用される逆パリティ フィールドが、参照ピクチャの逆パリティ フィールドか、または現在のピクチャの逆パリティ フィールドかを決定するのに使用される。bSecondField が "1" の場合、現在のフィールドは、ピクチャの第 2 フィールドであり、動き補償のために逆パリティ ラインの参照として使用されるフィールドは、現在のピクチャの逆パリティ ラインである。(どちらの場合も、動き補償のために同パリティ ラインの参照として使用されるフィールドは、参照ピクチャの同パリティ ラインである。) それ以外の場合、bSecondField は "0" でなければならない。

bPicIntra : このピクチャに対して動き補償予測が必要かどうかを指定する。bPicIntra が "1" の場合は、すべてのマクロブロックは IntraMacroblock は "1" で送信される (つまり、そのピクチャに関して動き補償予測は実行されない)。それ以外の場合、ピクチャの一部マクロブロックが IntraMacroblock が "0" となる可能性がある。

bPicBackwardPrediction : 現在のピクチャに逆方向予測を含むマクロブロックかあるかどうかを示す。bPicIntra が "1" の場合、bPicBackwardPrediction は "0" でなければならない。それ以外の場合、bPicBackwardPrediction が "0" であれば、ピクチャの全マクロブロックで MotionBackward が "0" でなければならない。bPicBackwardPrediction が "1" であれば、ピクチャの全マクロブロックで MotionBackward が "1" でなければならない。

bBidirectionalAveragingMode : このフラグは、双方向動き補償で予測プレーンを組み合わせる際の丸め方法を指定する (B ピクチャおよびデュアルプライムの動きに使用される)。値 "0" は MPEG-1 と MPEG-2 の丸め平均化 (//2)、および "1" は H.263 の切り捨て平均化 (/2) を含む。双方向平均化が必要ない場合は、bBidirectionalAveragingMode は "0" でなければならない。

bMVprecisionAndChromaRelation : この 2 ビット フィールドは、輝度動きベクトルの精度と、輝度動きベクトルから色光度動きベクトルが派生されなければならない方法を示す。

'00' は、輝度動きベクトルの精度がハーフサンプルであり、色光度動きベクトルが MPEG-2 の規則に従って輝度動きベクトルから派生されることを示す。

'01' は、輝度動きベクトルの精度がハーフサンプルであり、色光度動きベクトルが H.263 の規則に従って輝度動きベクトルから派生されることを示す。

'10' は、輝度動きベクトルの精度がフルサンプルであり、色光度動きベクトルが H.261 セクション 3.2.2 の規則 (2 で除算し、フルサンプル値まで 0 方向に切り捨て) に従って輝度動きベクトルから派生されることを示す。

'11' は予約されている。

bChromaFormat : アクセラレータによって予期される予測エラー ブロックの数に影響を与える。この変数は、MPEG-2 のセクション 6.3.5 および表 6-5 で定義されている。MPEG-1、MPEG-2 "メイン プロファイル"、H.261、H.263 ビットストリームの場合、この値は常に "4:2:0" フォーマットを示す '01' に設定されなければならない。'10' の場合は "4:2:2"、'11' の場合は "4:4:4" サンプリングを示す。bConfig4GroupedCoefs が "1" なら、'01' とするべきである。(なぜなら bConfig4GroupedCoefs は 4:2:2 と 4:4:4 フォーマットの係数データに必要とされている EOB 指示を含んでいないので。)

注 : H.261、H.263、および MPEG-1 と、MPEG-2 および MPEG-4 では水平方向のクロマ配置が若干異なる。この差異は、無視できる程度に小さなものであると想定される。

bPicScanFixed : 残差ブロックのアクセラレータベース IDCT 処理を使用する際、このフラグの値が "1" の場合は、逆スキャン方法がピクチャ内のすべてのマクロブロックについて同じであることを示す。値が "0" の場合は同じでないことを示す。bConfigHostInverseScan が "1"、または bConfigResidDiffAccelerator が "0" の場合、この値は "1" でなければならない。

bPicScanMethod : bPicScanFixed が "1" の場合、このフィールドは、ピクチャの固定逆スキャン方法を指定する。bPicScanFixed が "0" の場合は、このフィールドは意味がなく、'00' でなければならない。bPicScanFixed が "1" の場合、このフィールドは次のいずれかの値でなければならない。

  • bConfigHostInverseScan = 0 の場合、bPicScanMethod は次のとおり。
    • '00' = ジグザグ スキャン (MPEG-2 図 7-2)
    • '01' = 交互垂直 (MPEG-2 図 7-3)
    • '10' = 交互水平 (H.263 図 I.2 パート a)
  • bConfigHostInverseScan が "1" の場合、bPicScanMethod は次のとおり。
    • '11' = 絶対係数アドレスによる任意スキャン

bPicReadbackRequests : デコードされた (wDecodedPictureIndex と等しい wDeblockedPictureIndex でブロック解除が適用される場合には、ブロックも解除された) 最終ピクチャ内のマクロブロックの値を読み戻すために、現在のピクチャについて読み戻し制御要求が実行されるかどうか指定する。値 "1" は、読み戻し要求があることを示す。値 "0" は要求がないことを示す。

bRcontrol : このフラグは、H.263 セクション 6.1.2 に定義されており、ハーフサンプル動き補償に使われる丸め方法を指定する。値 "0" は、MPEG-1、MPEG-2、および最初のバージョンの H.263 のハーフサンプル丸め方法が使われることを示す。値 "1" は、H.263 および MPEG-4 のいくつかのオプション モードで選択できる、下方平均化バイアスを含む丸め方法が使われることを示す。H.261 にはハーフサンプル動き補償がないため、このフラグは H.261 では意味を持たない。すべての MPEG-1、および MPEG-2 のビットストリームの場合、これらの規格で定義されている丸め演算子に準拠するためには、この値が "0" に設定されなければならない。

bPicSpatialResid8 : 値 "1" は、ホストベースの残差デコードの空間領域差異ブロックが、8 ビット サンプルを使って送信できることを示す。値 0 は送信できないことを示す。bConfigResidDiffHost が "0"、または BPP > 8 の場合は、この値は "0" でなければならない。BPP = 8 で bPicIntra = 1 で、bConfigResidDiffHost が "1" の場合は、"1" でなければならない。bPicSpatialResid8 が 1 の場合は、空間領域イントラ マクロブロックが、定数値 2(BPP-1) に対応する符号付き 8 ビット差異値として送信され、空間領域非イントラ マクロブロック差異が、動き補償予測に対応する符号付き 8 ビット差異値として送信されることを示す。bPicSpatialResid8 は、ビデオ シーケンス全体に対してグローバルに指定するのではなく、特定のピクチャに関してのみ指定するという点で、bConfigSpatialResid8 と異なる。BPP が "8" であるイントラ ピクチャのような場合は、bConfigSpatialResid8 が "0" であっても bPicSpatialResid8 は "1" となる。

bPicOverflowBlocks : 値 1 は、ピクチャのホストベース残差デコードのための空間領域差異ブロックが、"オーバーフロー" ブロックを使って送信される可能性があることを示し、値 0 はその可能性がないことを示す。bConfigResidDiffHost が 0 か、bConfigSpatialResid8 が "0" か、または BPP > 8 の場合は、"0" でなければならない。bPicOverflowBlocks は、特定のピクチャに対応するオーバーフロー ブロックが存在する可能性があるかどうかを示す。BPP が "8" のイントラ ピクチャでは、この場合にオーバーフロー ブロックは不要なため、bPicOverflowBlocks は "0" でなければならない。

bPicExtrapolation : このフラグは、H.263 補遺 D および MPEG-4 で定義されているように、ピクチャ境界を越える動きベクトルが許可されるかどうかを指定する。これを実行するには、デコードされるピクチャのサイズよりも幅が 2 マクロブロック分広く (左右にそれぞれ余分のマクロブロック)、高さが 2 マクロブロック分高い (上下にそれぞれ余分のマクロブロック) ピクチャ プレーンを割り当てるか、またはピクチャ境界内で個々のピクセルがアクセスするアドレスをクリッピングする必要がある。この仕様でのマクロブロック アドレスは、ピクチャ内部のマクロブロック用であり、パディングを含まない。

bPicDeblocked : ブロック解除された出力ピクチャを wDeblockedPictureIndex で指定されたピクチャ バッファ内に作成するために、ブロック解除コマンドがこのピクチャ用に送信されるかどうかを示す。bPicDeblocked が "1" の場合は、ブロック解除コマンドが送信され、ブロック解除フレームが生成されなければならない。bPicDeblocked が "0" の場合は、ブロック解除コマンドが送信されず、ブロック解除ピクチャが生成されてはならない。

bPicDeblockConfined : ブロック解除フィルタ処理の効力を、バッファに格納されているのと同一のマクロブロック セット内に限定するコマンドを、ブロック解除フィルタ コマンド バッファに含めるかどうか指定する。

bPic4MVallowed : H.263 補遺 F および J で使用されているように、マクロブロックごとに 4 つの順方向参照動きベクトルが許可されるかどうかを指定する。

bPicOBMC : 現在のピクチャの動き補正が、H.263 補遺 F で定義されているように、重複ブロック動き補償 (OBMC) を使って動作するかどうかを指定する。bPic4MVallowed が 0 の場合は、0 でなければならない。

bPicBinPB : ピクチャ内の双方向予測マクロブロックが "PB 内の B" 動き補償を使用するかどうか指定する。この動き補償は、H.263 の補遺 G および M で定義されているように、各マクロブロックについて、双方向に予測された領域を、逆参照ピクチャ内の対応するマクロブロックのリージョンに限定する。

bMV_RPS : 動きベクトル参照ピクチャ選択の使用方法を指定する。"1" の場合は、ピクチャ全体としての順方向および (場合によっては) 逆方向動きピクチャ インデックスだけでなく、各動きベクトルについて参照ピクチャ インデックスが送信されることを示す。bMV_RPS が "1" の場合は、パラメータ wForwardRefPictureIndex および wBackwardRefPictureIndex は意味がなく、"0" でなければならない。

wBitstreamFcodes : bConfigBitstreamRaw が "1" の場合、このパラメータは、MPEG-2 に定義されているように 4 つの動きベクトル f_code 値を持つ。各 f_code 値は 4 ビットを取る。これらの値は、MPEG-2 と同様、次のような 16 ビット ワードにパックされる。

ビット 12 ～ 15 (MSB) : f_code[0][0] : 順方向水平 f_code

ビット 8 ～ 11 : f_code[0][1] : 順方向垂直 f_code

ビット 7 ～ 4 : f_code[1][0] : 逆方向水平 f_code

ビット 0 ～ 3 (LSB) : f_code[1][1] : 逆方向垂直 f_code

ビットストリーム データの構造上の理由のため、または bConfigBitstreamRaw = 0 であるため、または該当するビデオ コーディング ビットストリーム構文 (H.261 や H.263 など) で f_code パラメータが必要ないために、いずれかの f_code 値が不要または関係ない場合は、その f_code 値は 0xF でなければならない。

注 : MPEG-1 ビットストリームは、この情報を別のフォーマットで提供する。このため、MPEG-1 ビットストリームの場合は、f_code[0][0] および f_code[0][1] は MPEG-1 の forward_f_code、f_code[1][0] および f_code[1][1] は MPEG-1 の backward_f_code と同じでなければならない。

wBitstreamPCEelements : bConfigBitstreamRaw が "1" の場合、このパラメータには、MPEG-2 ビデオのビットストリーム デコード処理に必要な一連のフラグが含まれる。bConfigBitstreamRaw が "0" で、非 MPEG-2 ビデオの場合は、このパラメータは使用されず、値は "0" でなければならない。このパラメータ内のビットは、次のように、MPEG-2 ピクチャ コーディング エクステンションのビットストリーム要素との対応によって定義される。

ビット 14 および 15 : IntraDCprecision = intra_dc_precision

ビット 12 および 13 : AnotherPicStructure = picture_structure (bPicStructure と同じでなければならない)

ビット 11 : TopFieldFirst = top_field_first

ビット 10 : FrameDCTprediction = frame_pred_frame_dct

ビット 9 : ConcealmentMVs = concealment_motion_vectors

ビット 8 : QuantScaleType = q_scale_type

ビット 7 : IntraVLCformat = intra_vlc_format

ビット 6 : AlternateScan = alternate_scan

ビット 5 : RepeatFirstField = repeat_first_field (アクセラレータはこれを必要としない)

ビット 4: Chroma420type = chroma_420_type (アクセラレータには不要であり、MPEG-2 により progressive_frame と等しい値に制限される)

ビット 3 : ProgressiveFrame = progressive_frame

ビット 0、1、および 2 (LSB) : ReservedBits

bBitstreamConcealmentNeed : bConfigBitstreamRaw が "1" の場合、ビットストリーム データにエラーが含まれている可能性が大きいかどうかを示す。bConfigBitstreamRaw が "0" の場合は、この値は "0" でなければならない。ビデオ アクセラレータは、与えられたデータの内容にかかわらず、クラッシュしたりロックアップしたりしないように設計される必要がある。しかし、ビデオ アクセラレータが、ビットストリームのデコード処理を遅らせる、より複雑なエラー隠匿アルゴリズムを呼び出せるようにする必要があるかどうかを決定する際、構文エラーの可能性をホストがどのよう評価しているかを認識することは役立つ。このパラメータに使用できる値は次のとおり (これ以外の値はすべて予約されている)。

"0" : ビットストリームの構文上のフォーマットに、大量のエラーが含まれている可能性が低いことを示す。

"1" : ビットストリームにいくつかのエラーが含まれている可能性があるが、それらが頻繁に現れない (1 時間に 1 ～ 2 回) ことを示す。

"2" : ビットストリームにエラーが含まれており、ユーザーの使用状況に影響を及ぼす程度の頻度で発生する可能性が高く (5 ～ 10 分にいくつかのエラー)、しかしそれらのエラーが一定には存在していないことを示す。

"3" : ビットストリームに、比較的重大、深刻、かつ頻繁な構文フォーマット エラーが含まれていることを示す (1 分間に 1 回以上)。

bBitstreamConcealmentMethod : bConfigBitstreamRaw が "1" の場合、推奨されるエラー隠匿処理のデフォルト方法を示す。bConfigBitstreamRaw が "0" の場合は、"0" でなければならない。このパラメータに使用できる値は次のとおり (これ以外の値はすべて予約されている)。

0 : 推奨される隠匿方法が未知である、または指定されていない。

1 : 推奨される隠匿方法は、ピクチャ内での、空間イントラピクチャ隠匿の使用である。

2 : 推奨される隠匿方法は、インターピクチャ隠匿の順方向動き参照ピクチャの使用である (対応する逆方向動き参照ピクチャよりも順方向動き参照ピクチャに一時的に近くなっている P ピクチャまたは B ピクチャ内で最も一般的に使用される)。

3 : 推奨される隠匿方法は、インターピクチャ隠匿の逆方向動き参照ピクチャの使用である (対応する順方向動き参照ピクチャよりも逆方向動き参照ピクチャに一時的に近くなっている B ピクチャ内で最も一般的に使用される)。

3.5.5 ピクチャのマクロブロックのバッファ構造

デコードされたピクチャにビットストリーム データ バッファが含まれていない場合は、1 つまたは複数のマクロブロック制御コマンド バッファが含まれていなければならない。すべてのマクロブロックのデコード処理は、使用される各タイプのバッファ内で1 度だけアドレスされなければならない。すべてのマクロブロック制御コマンド バッファについて、同じマクロブロックのセットを持つ、対応する IDCT 残余コーディング バッファが存在しなければならない。1 つまたは複数のブロック解除フィルタ制御バッファが送信される場合、各ブロック解除フィルタ制御バッファ内のマクロブロック セットは、対応するマクロブロック制御バッファおよび IDCT 残余コーディング バッファ内のマクロブロック セットと同一でなければならない。

ピクチャを処理するには、各マクロブロックの動き予測が、IDCT 残余データの追加に先行する必要がある。これを実行するには、まず動き予測コマンドを処理してから、IDCT 残余コーディング コマンドの処理中に、このデータを宛先ピクチャ バッファから読み戻すか、またはこれらの 2 つのバッファを、統合して処理する (結果を宛先ピクチャ バッファに書き込む前に、残余データを予測に追加する)。各マクロブロックの動き予測コマンドと IDCT 残余コーディング コマンドは、そのマクロブロック内の矩形リージョンのみに影響する。

マクロブロックのブロック解除フィルタ コマンドは、現在のマクロブロックの上および左に隣接するサンプルの 2 行 2 列の再構築された値、および現在のマクロブロック内の再構築された値を読み込むためのアクセスを必要とする場合がある。その結果、現在のマクロブロックの上および左に隣接するサンプルの、1 行 1 列、および現在のマクロブロック内の最大 3 行 3 列が修正される場合がある。このため、特定のマクロブロックのフィルタリング処理を実行するために、事前にほかのマクロブロックの再構築が必要になる場合がある。ここでは、2 つの異なるタイプのブロック解除フィルタ バッファが定義されている。1) 現在のバッファの外にあるマクロブロックの、再構築されたサンプルの値に対するアクセスおよび値の修正を必要とするバッファ タイプ (bPicDeblockConfined が "0" の場合)、および 2) それらを必要としないバッファ タイプ (bPicDeblockConfined が "1" の場合) である。1) のタイプのブロック解除コマンド バッファを処理するには、現在のバッファ内でブロック解除コマンドを処理する前に、現在のバッファのマクロブロックの左および上にあるマクロブロックに影響するすべてのバッファの再構築が完了していることを、アクセラレータが確認する必要がある。2) のタイプを処理する場合は、現在のバッファ内の値が事前に再構築されていればよい。ブロック解除のポストプロセッシングを行うには、まずバッファ全体またはフレームに対して動き予測と IDCT 残余コーディング コマンドを処理し、次にいくつかのサンプルの値を読み戻し、ブロック解除フィルタ処理の結果としてそれらを修正するか、またはブロック解除コマンド バッファを、IDCT 残余コーディング バッファと統合して処理する (最終出力値を宛先ピクチャ バッファに書き込む前に、ブロック解除を実行する)。ブロック解除されたピクチャの宛先ピクチャ バッファは、ブロック解除の前に再構築されたピクチャのバッファとは異なる場合がある。これは、ポストプロセッシングとして、次のピクチャの予測に使われるサンプル値に影響を与えない "ループ外" ブロック解除をサポートするためである。

3.5.5.1 マクロブロック制御コマンド

if (bPicIntra)
    NumMV = 0;
else if (PicOBMC) {
    NumMV = 10;
    if (bPicBinPB)
        NumMV++;
}
else {
    NumMV = 4;
    if (bPicBinPB && bPic4MVallowed)
        NumMV++;
}

DXVA_MB_Control {           // 16 バイトに整列

  // 一般マクロブロック情報
  wMBaddress                // 16b どのマクロブロックか
  wMBtype                   // 16b 制御ビット
  MBskipsFollowing          //  8b

  // 残差情報
  MBdataLocation            // 24b バッファ内の位置
  wPatternCode              // 16b コードされたブロック

  if(bPicOverflowBlocks==1 &&
     IntraMacroblock==0){
    wPC_Overflow            // 16b wPatternCode ごと
    dwReservedBits2         // 32b
  }
  else if(HostResidDiff)
    ReservedBits3           // 48b
  else if (bChromaFormat == '01')
    for (i = 0; i < 6; i++)
        bNumCoef[i]               //  8b * 6 blocks = 48b
  else {
    wTotalNumCoef                 // 16b
    ReservedBits3                 // 32b
}

  if (bPicIntra != 0) {
  // 動き予測情報
    for(i=0; i<NumMV; i++) {
        MVector[i].horz    // 16b * NumMV ベクトル
        MVector[i].vert    // 16b * NumMV ベクトル
    }
    if(bMV_RPS)
      for(i=0; i<NumMV; i++)
        bRefPicSelect[i]       //  8b * NumMV ベクトル
        ReservedBits4                   //  16b バイト整列
    }
  }

wMBaddress : 現在のマクロブロックのマクロブロック アドレスをラスタ スキャン順序で指定する (0 は左上マクロブロックのアドレス、PicWidthInMBminus1 は右上マクロブロックのアドレス、PicHeightInMBminus1 * PicWidthInMB は左下マクロブロックのアドレス、PicHeightInMBminus1 * PicWidthInMB + PicWidthInMBminus1 は右下マクロブロックのアドレス)。

wMBtype : 処理されるマクロブロックのタイプを指定する。指定方法は次のとおり。

  • ビット 15 : MvertFieldSel[3] (MSB)
  • ビット 14 : MvertFieldSel[2]
  • ビット 13 : MvertFieldSel[1]
  • ビット 12 : MvertFieldSel[0] : マクロブロック制御コマンド内で後に送信される、対応する動きベクトルの垂直フィールド選択を指定する。詳しくは後述。フレーム ピクチャ構造を持つフレームベースの動きの場合 (H.261 および H.263 など)、これらのビットはすべて 0 でなければならない。これらのビットの使用は、MPEG-2 のセクション 6.3.17.2 で対応するビットに指定されているのと同様である。
  • ビット 11 : ReservedBits
  • ビット 10 : HostResidDiff : 現在のマクロブロックのオフホスト IDCT のために、空間領域残差デコード済みブロックが送信されるかどうか、または変換係数が送信されるかどうかを指定する。bConfigResidDiffHost が "0" なら "0"。bConfigResidDiffAccerelator が "0" なら "1" 。
  • ビット 9 および 8 : MotionType : ピクチャの動きタイプを指定する。詳しくは後述。フレーム ピクチャ構造を持つフレームベースの動きの場合 (H.261 など)、これらのビットは '10' (フレーム動き) でなければならない。これらのビットの使用は、後の表 1 に定義され、MPEG-2 のセクション 6.3.17.1、表 6-17 および 6-18 にある frame_motion_type または field_motion_type ビットの使用と直接対応する (MPEG-2 にこれらのビットが存在する場合)。

  • ビット 7 および 6 : MBscanMethod : bPicScanFixed が "1" の場合は、bPicScanMethod と等しくなければならない。bConfigHostInverseScan = 0 の場合、MBscanMethod は次の値でなければならない。
    • '00' = ジグザグ スキャン (MPEG-2 図 7-2)
    • '01' = 交互垂直 (MPEG-2 図 7-3)
    • '10' = 交互水平 (H.263 図 I.2 パート a)

    bConfigHostInverseScan = 1 の場合、MBscanMethod は次と等しくなければならない。

    • '11' = 絶対係数アドレスによる任意スキャン
  • ビット 5 : FieldResidual : MPEG-2 に指定されているように、IDCT ブロックがフィールド IDCT 構造を使用するかどうかを示すフラグ。
  • ビット 4 : H261LoopFilter : 現在のマクロブロック予測に対して H.261 ループ フィルタ (H.261 のセクション 3.2.3) がアクティブかどうかを指定するフラグ。H.261 ループ フィルタは、H.261 マクロブロックの 6 つすべてのブロックに、(タップの 1 つがブロック外に落ちるブロックの端は除いて) 水平にも垂直にも適用される、分割可能な ¼、½、¼ フィルタである。このような場合、フィルタは係数 0、1、0 を持つように変更される。2D フィルタ処理の出力時に、8 ビット整数への丸めと共に、計算上の完全な精度が保持される (半整数以上の値は丸められる)。
  • ビット 3 : Motion4MV : H.263 補遺 F および J で使用されているように、順方向の動きが、マクロブロック内の 4 つの輝度ブロックそれぞれに対して、個別の動きベクトルを使用することを示すフラグ。MotionForward が "0" または bPic4MVallowed が "0" の場合は、Motion4MV は "0" でなければならない。
  • ビット 2 : MotionBackward : MPEG-2 の対応する macroblock_motion_backward パラメータに指定されたように使用されるフラグ。bPicBackwardPrediction が "0" の場合、MotionBackward shall は 0 でなければならない。このフラグの使用に関する詳細は後述。
  • ビット 1 : MotionForward : MPEG-2 の対応する macroblock_motion_forward パラメータに指定されたように使用されるフラグ。このフラグの使用に関する詳細は後述。
  • ビット 0 : IntraMacroblock : (LSB) マクロブロックが "イントラ" としてコードされ、現在のマクロブロックには動きベクトルが使用されないことを示すフラグ。MPEG-2 の macroblock_intra に対応する。このフラグの使用に関する詳細は後述。

MBskipsFollowing : 現在のマクロブロックに続いて生成される、"スキップされるマクロブロック" の数を指定する。スキップされる各マクロブロックは、wMBaddress の値を増加させ、その後同じマクロブロック制御コマンドを反復するのと同等の計算方法で生成されなければならない。

MBskipsFollowing の値が "0" でないマクロブロック制御コマンドはすべて、スキップされる各マクロブロックごとに動き補償予測がどのように実行されるかに関する明示的な指定を含み、また (MBskipsFollowing の値を除いて)、スキップされる一連のマクロブロックの最初のマクロブロックの生成に関する明示的な "非スキップ" 指定と同等である。このため、MBskipsFollowing が "0" でない場合は常に、次のパラメータがすべて "0" と等しくなければならない。

  • Motion4MV
  • IntraMacroblock
  • wPatternCode
  • wPCOverflow (存在する場合)
  • bNumCoef[i] (存在する場合)

さらに、後に続くスキップされるマクロブロックの生成は、ピクチャ内のマクロブロックの新しい行への "折り返し" を含まないよう、デコーダによって制限されなければならない。つまり、マクロブロックの各行の最初の (しかし最後である必要はない) マクロブロックを生成するために、個別のマクロブロック制御コマンドが送信される必要がある。

注 :

  1. この状況における、スキップされるマクロブロックの生成は、MPEG-2 のセクション 7.6.6 のものとはいくらか異なる。この仕様では、スキップされるマクロブロックが生成される方法は、先行する非スキップ マクロブロックおよびピクチャのタイプから導かれるのでなく、個別のマクロブロック制御コマンド内で指定される (たとえば、MPEG-2 では、スキップされるマクロブロックの生成方法は、ピクチャが P ピクチャであるか B ピクチャであるかに依存する)。この点を明確にするため、次のような例を用意した。MPEG-2 ビットストリームで、マクロブロック 0 が残差でコードされ、マクロブロック 1 がスキップされ、マクロブロック 2 が残差でコードされ、マクロブロック 3、4、5 がスキップされ、マクロブロック 6 が残差でコードされているとする。これら 7 つのマクロブロックは、少なくとも 5 つの DirectX VA マクロブロック制御コマンドの生成を必要とする。最小限の 5 つの制御コマンドは、次のように特徴付けられる。
    1. 最初のコマンドは wMBaddress = "0" および MBskipsFollowing = "0" となる
    2. 2 番目のコマンドは wMBaddress = "1" および MBskipsFollowing = "0" となる
    3. 3 番目のコマンドは wMBaddress = "2" および MBskipsFollowing = "0" となる
    4. 4 番目のコマンドは wMBaddress = "3" および MBskipsFollowing = "2" となる
    5. 5 番目のコマンドは wMBaddress = "6" および MBskipsFollowing = "0" となる
  2. 上記に指定したように、次の条件が必要となる。
    1. スキップされるマクロブロックが残差を保持していない
    2. スキップされるマクロブロックが、wMBaddress を増加させながらマクロブロック制御コマンド処理を反復することによって生成できる
    3. マクロブロックのスキップが、マクロブロックの新しい行に折り返さないよう制限されている
  3. 注 2 に挙げた 3 つの条件により、同じマクロブロック制御処理の MBskipsFollowing+1 反復ではなく、輝度成分の MacroblockWidth·(MBskipsFollowing+1) と同じ幅を持つ矩形 (および同様に指定された色光度成分の矩形) への指定された動きベクトルの適用として、アクセラレータが実際に動き補償を実現できる (Motion4MV が "0" の場合)。
  4. 高度予測モード (補遺 F) が有効となっている H.263 でスキップと示されたマクロブロックを生成する場合、それらのマクロブロック内で OBMC 効果を指定するには、この仕様を使って、いくつかの "スキップされた" マクロブロックを非スキップ マクロブロックとしてコーディングする必要がある。

MBdataLocation : IDCT 残余コーディング ブロック データ バッファへのインデックス。現在のマクロブロック内のブロックの残差データ位置を、32 ビットの倍数で示す。マクロブロック制御コマンド バッファの最初のマクロブロックの場合は、"0" でなければならない。

wPatternCode : ホストベース残差デコードを使用する場合、wPatternCode (ビット 0 が LSB) の ビット 11-i は、ブロック i の残差ブロックが送信されるかどうかを示す。ここで、i は、図 6-10、6-11、および 6-12 で指定されたマクロブロック内のブロックのインデックスである (ラスタスキャン順の Y、ラスタスキャン順の Cb の 4:2:0 ブロック、Cr の 4:2:0 ブロック、Cb の 4:2:2 ブロック、Cr の 4:2:2 ブロック、Cb の 4:4:4 ブロック、Cr の 4:4:4 ブロックの順)。コードされたブロックのデータ (ビット 11-i が 1 であるブロック) は、同じインデックス順序 (増分 i) の残余コーディング バッファにある。4:2:0 MPEG-2 データの場合、wPatternCode の値は、デコードされた CBP の値を左に 6 ビット位置シフトしたものに対応する (これらの下位ビット位置は、4:2:2 および 4:4:4 クロマ フォーマットで使用される)。

bConfigSpatialResidInterleaved が "1" の場合、ホストベースの残差は、使用されている YUV ピクセル フォーマットに一致するクロマインターリーブ フォーマットで送信される。この場合、Cb および 空間的に対応する Cr のブロックの各組は、単一の残差データ構造単位として扱われる。これにより wPatternCode の値や意味が変更されることはないが、Cb および Cr データ ブロックのどちらかが wPatternCode に対応するビット セットを持っていれば、これらのデータ ブロックの各組の両方のメンバが常に送信されることを意味する。特定のデータ ブロックの wPatternCode のビットが 0 の場合、この組が、wPatternCode ビットが 0 であるブロックの残差データ ブロックの送信を必要とするときは常に、対応する残差データ値が 0 として送信されなければならない。

wPC_Overflow : bPicOverflowBlocks が 1、IntraMacroblock が 0 (8-8 オーバーフロー方式) でホストベースの残差デコードを使用する場合、wPC_Overflow には、wPatternCode と同じ方法で指定されたオーバーフロー ブロックのパターン コードが含まれる。コードされたオーバーフロー ブロックのデータ (ビット 11-i が 1 であるブロック) は、同じインデックス順序 (増分 i) の残余コーディング バッファにある。

bNumCoef[i] : マクロブロックの各ブロック i の、残余コーディング ブロック データ バッファ内の係数の数を示す。ここで、i は、MPEG-2 の 図 6-10、6-11、および 6-12 で指定されたマクロブロック内のブロックのインデックスである(Y のラスタ スキャン順、Cb に続く、Cr に続く)。 HostResidDiff が "0" で bChromaFormat が '01' (4:2:0) のときのみ使用される。(4:2:2 か 4:2:0 フォーマットで使用されると、典型的なマクロブロック コントロール コマンドのサイズが増加して、クリティカル メモリ割り当て境界を越えてしまう、そのため非 4:2:0 の場合各ブロックの係数の数を決めるのに EOB だけが使用される。) これらの係数のデータは同じ順の残差バッファ内にある。

wTotalNumCoef: 全マクロブロックの残差データバッファ内の係数の全数を示す。HostResidDiff が "0" かつ bChromaFormat が '01'以外のとき (4:2:0) のみ使用される。

MVector[i].horz、MVector[i].vert : 水平方向および垂直方向の動きベクトルの値を指定する。これら 2 つの値を 2 次元に統合した値は、MVvalue[i] と呼ばれる。各動きベクトルの各方向には、ハーフサンプル単位の符号付き整数動きオフセットが含まれる。bMVprecisionAndChromaRelation が '10' (整数サンプル オフセットだけをサポートしている H.261 フォーマットの動き) の場合は、どちらの要素も偶数でなければならない。

bRefPicSelect[i] : 動きベクトル参照ピクチャ選択が使用中の場合は、MVvalue[i] の予測に使用される参照ピクチャ バッファを指定する。

IntraMacroblock、MotionForward、MotionBackward、PicMotionType、MvertFieldSel、および MVector[i] の有効な組み合わせを、下の表 1 に示す。表内で指定された値は、H261LoopFilter、Motion4MV、および bPicOBMC がすべて 0 であることを前提としている。

表 1 - 各種動きタイプにおけるマクロブロック パラメータの使用

IntraMacroblock、 MotionForward、 MotionBackward | MotionType (意義はピクチャ タイプによる) | MVector[0] MvertFieldSel[0] (1st, dir1) | MVector[1] MvertFieldSel[1] (1st, dir2) | MVector[2] MvertFieldSel[2] (2nd, dir1) | MVector[3] MvertFieldSel[3] (2nd, dir2)
フレーム構造化ピクチャ (bPicStructure = '11')
1,0,0 (intra) | '00' (intra) | - - | - - | - - | - -
0,0,0 (no motion) | '10' (no motion) | 0 - | - - | - - | - -
0,1,0 | '10' (frame MC) | PMV[0][0] - | - - | - - | - -
0,0,1 | '10' (frame MC) | - - | PMV[0][1] - | - - | - -
0,1,1 | '10' (frame MC) | PMV[0][0] - | PMV[0][1] - | - - | - -
0,1,0 | '01' (field MC) | PMV[0][0] sel[0][0] | - - | PMV[1][0] sel[1][0] | - -
0,0,1 | '01' (field MC) | - - | PMV[0][1] sel[0][1] | - - | PMV[1][1] sel[1][1]
0,1,1 | '01' (field MC) | PMV[0][0] sel[0][0] | PMV[0][1] sel[0][1] | PMV[1][0] sel[1][0] | PMV[1][1] sel[1][1]
0,1,0 | '11' (dual-prime) | PMV[0][0] 0 (top) | vector'[2][0][0], vector'[2][0][1]<<1 1 (bot) | PMV[0][0] 1 | vector'[3][0][0], vector'[3][0][1]<<1 0
フィールド構造化ピクチャ (bPicStructure == '01' or '10')
1,0,0 (intra) | '00' (intra) | - - | - - | - - | - -
0,0,0 (no motion) | '01' (no motion) | 0 PicCurrentField | - - | - - | - -
0,1,0 | '01' (field MC) | PMV[0][0] sel[0][0] | - - | - - | - -
0,0,1 | '01' (field MC) | - - | PMV[0][1] sel[0][1] | - - | - -
0,1,1 | '01' (field MC) | PMV[0][0] sel[0][0] | PMV[0][1] sel[0][1] | - - | - -
0,1,0 | '10' (16×8 MC) | PMV[0][0] sel[0][0] | - - | PMV[1][0] sel[1][0] | - -
0,0,1 | '10' (16×8 MC) | - - | PMV[0][1] sel[0][1] | - - | PMV[1][1] sel[1][1]
0,1,1 | '10' (16×8 MC) | PMV[0][0] sel[0][0] | PMV[0][1] sel[0][1] | PMV[1][0] sel[1][0] | PMV[1][1] sel[1][1]
0,1,0 | '11' (dual-prime) | PMV[0][0] PicCurrentField | vector'[2][0] !PicCurrentField | - - | - -

注 :

  1. この表は非常に重要である。よく検討して完全に理解する必要がある。経験上、表内の利用されるすべてのマクロブロック タイプ (特にフィールド構造化ピクチャまたはデュアル プライム動き) に適切な対応をしていないあらゆる実装には、バグが含まれていると思われる。
  2. 上の表に、生の動きベクトル値でなく値 PMV が使用されている箇所がある。これは、フレーム座標内にある PMV を、(ハーフ垂直解像度の) フィールド座標にある可能性がある動きベクトルと区別するためである。上のような PMV はすべて、現在の動きベクトルで更新した後の PMV 値を意味する。
  3. vector'[2][0] と vecotor'[3][0] の定義は MPEG-2 セクション 7.6.3.6 にある。シフト操作は垂直コンポーネントがフレーム座標に修正されることを示す。
  4. 上の "動きなし" (0,0,0) の両ケースでは、マクロブロック パラメータが、動きベクトルの値が 0 の順方向予測マクロブロック (0,1,0) をエミュレートする (MPEG-2 セクション 7.6.3.5 を参照)。

このほかの可能な組み合わせは次のとおり。

H261LoopFilter == 1 && bPicOBMC == 0 && Motion4MV == 0 : 順方向動きベクトルの 1 個が MVector[0] に送信され、マクロブロックの順方向予測に対して、H.261 のセクション 3.2.3 で指定された H.261 ループ フィルタがアクティブであることを示す。この場合、MotionForward は 1、IntraMacroblock と MotionBackward の両方は "0" でなければならない。

bPicOBMC == 0 && Motion4MV == 1 : 4 個の順方向動きベクトルが MVector[0, 1, 2, 3] に送信されることを示す。この場合、MotionForward が 1、IntraMacroblock が "0" でなければならない。MotionBackward が "1" の場合、5 番目の動きベクトルが逆方向予測のために MVector[4] に送信される。

bPicOBMC == 1 && Motion4MV == 0 : 10 個の順方向動きベクトルが OBMC の動き指定のために MVector[0, 1, 2, ..., 9] に送信され、これら動きベクトルの最初の 4 個の値がすべて同じであることを示す。MotionBackward が "1" の場合、11 番目の動きベクトルが逆方向予測のために MVector[10] に送信される。

bPicOBMC == 1 && Motion4MV == 1 : 10 個の順方向動きベクトルが OBMC 動きの指定のために MVvalue[0, 1, 2, ..., 9] に送信され、これら動きベクトルの最初の 4 個の値がすべて異なる可能性があることを示す。MotionBackward が 1 の場合、11 番目の動きベクトルが逆方向予測のために MVvalue[10] に送信される。

注 : H.263 標準規格の現在の構成では、bPicOBMC == 1、Motion4MV == 1、MotionBackward == 1 という組み合わせは使用されない。

PB 内の H.263 の OBMC、4MV、B、EP、B 間の関連についてのいくつかの詳細は有効であろう :
a) OBMC は H.263 B あるいは EP ピクチャ内では使用できない (H.263 セクション 5.1.4.5 第 2 項)。
b) OBMC は H.263 PB ピクチャの B パート内では使用できない (H.263 セクション F.1 第 1 段落)。
c) 4MV は H.263 B あるいは EP ピクチャ内には送ることができない (構文ダイアグラムの MVFW と MVBW 1 つだけ、H.263 表 O.1 と O.2 内の 4MV マクロブロック タイプはない)。
d) H.263 B ピクチャの "直接"予測の詳細の参照マクロブロックとして使用される H.263 P ピクチャのマクロブロックで 4MV が使用されるなら、OBMC は直接予測には使用されない、なぜなら 4 つのモーション ベクトルが H.263 Annex M にしたがって使用されるからである、これは OBMC を適用しない H.263 Annex G のようにそれを用いる (H.263 セクション O.4 第 2 段落と第 2 項目)。それゆえ、H.263 は OBMC も逆予測も同時には要求しない、そして逆方向にも 4MV を使わない。

注 : MPEG-1、MPEG-2 ハーフサンプル予測フィルタリング、双方向平均化、およびデュアル プライムの同パリティと逆パリティの組み合わせのいずれにおいても、平均演算子は算術的には同じ ((s1+s2)//2) である。この演算子は、C 言語の式 (s1+s2+1)>>1 と同じである。H.263 双方向平均化演算子は、ダウンシフトに先行して "+1" オフセットでシードしない。bBidirectionalAveragingMode パラメータは、これらのどの方法を使うかを決定する。

3.5.5.2 逆量子化、IDCT 前飽和、ミスマッチ制御、イントラDCオフセット、IDCT、ピクチャ再構築、および再構築クリッピング

このインターフェイスは、IDCT 処理のための、3 つの下位レベルの方法をサポートする。どの場合でも、基本的な逆量子化処理、IDCT 前の範囲飽和、MPEG-2 ミスマッチ制御 (必要に応じて)、およびイントラ DC オフセット (必要に応じて) はホスト側で実行され、最終的なピクチャの再構築および再構築クリッピングはアクセラレータ側で実行される。最初の方法は、変換係数のマクロブロックを、外部の IDCT、ピクチャ再構築、および再構築クリッピングのためにアクセラレータに渡すことである。2 番目と 3 番目の方法では、IDCT をホスト上で実行し、外部のピクチャ再構築および再構築クリッピングのために空間領域結果のブロックを渡す。

逆量子化、IDCT 前飽和、ミスマッチ制御、イントラ DC オフセット、IDCT、ピクチャの再構築、および再構築クリッピングの処理は、次のように定義される。

  1. エントロピーコード化された量子化インデックスから、一連の IDCT 係数値 [image] を作成するために、必要に応じて逆量子化 (逆量子化重み付け行列の適用を含む) を実行する (ホストによって実行)。
  2. 制限された範囲内の値 [image] を取得するために、変換係数ブロックの、再構築された各係数値 [image] を飽和させる (ホストによって実行)。

  3. ミスマッチ制御 (MPEG-2 のみに必要で、ホストによって実行として説明する) は、マクロブロック内のすべての係数の飽和値を加算することによって実行される (LSB すべての XOR と同等)。合計が偶数になった場合は、 [image] が奇数なら 1 を引き、 [image] が偶数なら 1 を足すことにより (LSB の切り替えと同等)、最後の係数の飽和値 [image] を修正しなければならない。(合計が奇数になった場合は、 [image] の飽和値がそのまま使用される。) 飽和およびミスマッチ制御後の係数値は、ここで、 [image] として表される。
  4. 注: MPEG-1 はミスマッチ制御に別のフォームを持つ、これはそうしないと逆量子化後遇数となる各係数に 1 を足すあるいは引くことで値を変えることによって構成される。H.263 は個々で記述されている意味でのミスマッチ制御を要求しない。いつでも、適用可能であれば、ミスマッチ制御はホストの責任である。
  5. 必要に応じてイントラ DC オフセットを追加する (ホストによって実行)。これは、空間参照予測値 2(BPP-1) への差異の追加にすべてのイントラ ブロックを対応させるためである。このようなオフセットは、HostResidDiff が "1" かつ bConfigIntraResidUnsigned が "1" のとき、すべての参照ビデオ コーディング標準規格 (H.261&3 および MPEG-1&2&4) で必要であり、どの場合でも [image] という値を持つ (値は、BPP>8 が許可される MPEG-4 以外ではすべて 1024 となる)。
  6. 単一の分割可能な変換を実行する (ホストまたはアクセラレータによって実行)。

    各記号の意味 :

    C(u) は、u = 0 の場合は 1、それ以外の場合は

    C(v) は、v = 0 の場合は 1、それ以外の場合は

    x および y は、ピクセル領域内の水平および垂直空間座標

    u および v は、変換領域の水平および垂直周波数座標

    WT および HT は、変換 ブロックの幅および高さ (通常はどちらも 8)

    注 : この IDCT 処理の精度は、H.261&3 および MPEG-1&2&4 ビデオ コーディング標準規格で求められるもの (ほぼ同様) に準拠しなければならない。

  7. ピクチャの再構築を行うため、空間領域残余情報を、非イントラ ブロックの場合は動き補償予測値に、イントラ ブロックの場合は定数参照値に追加する (この定数は HostResidDiff が "1" かつ bConfigIntraResidUnsigned が "1" のとき以外は 2(BPP-1) である、前述の場合は "0")。
  8. ピクチャ再構築を、最終結果のピクチャ サンプル値として保管するために、[0, (2BPP)-1] の範囲にクリッピングする (アクセラレータ上で実行)。

3.5.5.2.1 オフホストの IDCT

オフホスト IDCT 処理のための、マクロブロック IDCT 係数データの転送には、インデックスのバッファと値の情報が含まれる。インデックス情報は 16 ビット ワードとして送信され (ただし 8×8 変換 ブロックに本当に必要なのは 6 ビットのみ)、変換係数値情報は符号付き 16 ビット ワードとして送信される (ただし通常の 8×8 変換 ブロックの場合で BPP=8 の場合は、必要なのは 12 ビット のみ)。

変換係数は、DXVA_TCoefSingle または DXVA_TCoef4Group のどちらかのデータ構造体で送信される。bConfig4GroupedCoefs が "0" の場合、係数は DXVA_TCoefSingle 構造体を使って別々に送信される。bConfig4GroupedCoefs が "1" の場合、係数は DXVA_TCoef4Group 構造体を使って 4 つずつ送信される。これら二者択一のデータ構造体には、以下に定義する 2 つの似通った基本要素が含まれる。

TCoefIDX : bConfigHostInverseScan から決定されたとおりに、ブロック内の係数のインデックスを指定する。TCoefIDX の使用には、次の基本的な 2 つの方法がある。

  1. RLE (Run-length) 順序 : bConfigHostInverseScan が "0" の場合、MBscanMethod は、ジグザグ、交互垂直、または交互水平逆スキャンを示す。この場合、TCoefIDX には、指定されたスキャン順序で現在の係数に先行し、ブロックに最後に送られた係数に続く (先行する係数がなければブロック先頭からの)、値 0 の係数の数が含まれる。
  2. 任意の順序 : bConfigHostInverseScan が "1" の場合、MBscanMethod は任意の順序を示す。この場合、TCoefIDX には、ブロック内の係数のラスタ インデックスだけが含まれる (つまり、TCoefIDX = u + v·WT)。

TCoefIDX は、WT·HT 以上になってはならない。

TCoefValue : ブロック内の係数の値。TCoefValue は、係数値を逆 DCT 処理のためにアクセラレータに渡す前に、前述のセクション 3.4.2 で示したように、ホスト側で適切な範囲にクリップしなければならない。必要に応じて、MPEG-2 ミスマッチ制御も、アクセラレータでなくホストによって実行される (このために、0 でない余分な "幽霊" 係数の作成が必要になる場合がある)。

3.5.5.2.1.1 単一係数のデータ フォーマット

DXVA_TCoefSingle データ構造体は、bConfig4GroupedCoefs が "0" の場合に必ず使用され、次のように定義される。

DXVA_TCoefSingle {
  TCoefIDX        15 /* 8×8 に本当に必要なのは 6 のみ */
  TCoefEOB         1
  TCoefValue    16 /* ホスト上で飽和 */
}

TCoefEOB : 現在の変換係数が、係数の現在のブロックに関連付けられた最後の係数かどうかを示す。値 "1" は、現在の係数がブロックの最後の 1 つであることを示す。値 "0" は、そうでないことを示す。

3.5.5.2.1.2 グループ化された 4 係数のデータ フォーマット

DXVA_TCoef4Group データ構造体は、bConfig4GroupedCoefs が "1"、bConfigHostInverseScan が "0" の場合のみに使用され、次のように定義される。

DXVA_TCoef4Group {
  TCoefIDX[4]    4*8  /* 8x8 に本当に必要なのは 6 のみ */
  TCoefValue[4]  4*16
}

DXVA_TCoef4Group データ構造体では、グループ化された 4 つの変換係数が、RLE (Run-length) 値と共に一括送信される。DXVA_TCoef4Group 内の各配列のi 番目の要素には実際のの係数か実行長リストの要素 3-i が入る (それゆえ、最初の係数あるいはインデックスは要素 3 になる、要素 2 に次...)。送信すべき 0 でない係数の数 NC が 4 より少ない場合、i=NC ～ 3 について、TCoefIDX[i] は 63 (16進の 0x3F)、TCoefValue[i] は TCoefValue[NC-1] でなければならない。

3.5.5.2.2 ホストベースの IDCT

IDCT はホスト上で実行することもできる。この場合、結果は API を使って渡される。結果送信のスキームとしては、16 ビットと 8-8 オーバーフローの 2 つの方法がサポートされる。どちらが使用されるかは、bConfigSpatialResid8 に示される。

3.5.5.2.2.1 16 ビット方式

16 ビット方式を使って 16 ビットデータを送信する場合は、データのブロックは連続的に送信される。空間領域データの各ブロックは、DXVA_Sample16 の WT·HT 値で構成される。

A DXVA_Sample16 は 16 ビットの符号付き整数である。BPP が "8" より大きい場合は、16 ビット方式だけが使用できる。bPicIntra が "1" で BPP が "8" の場合は、16 ビット方式は使用できない。IntraMacroblock が "0" なら、16 ビット サンプルはモーション圧縮された予測値に関する符号付きの数として送られる。IntraMacroblock が "1" なら、16 ビット サンプルは以下のように送られる :

  • bConfigIntraResidUnsigned が "1" なら、サンプルは "0" の一定参照値に関する符号なしの数として送られる。
  • bConfigIntraResidUnsigned が "0" なら、サンプルは 2(BPP-1) の一定参照値に関する符号なしの数として送られる。

データのブロックは、MSB から LSB に 1 バリュー ビットのスキャンにより指定された wPatternCode 順に、シーケンシャルに送られる。

注 :

  1. bConfigSpatialHost8or9Clipping が "1" でない限り、ホスト上でこれらの値のクリッピングが行われたと見なすことはできない。空間領域差異データを適切に表現するには BPP+1 ビット範囲で足りるが、クリップされていない場合、一部の IDCT ではこの範囲を超える数値が出力される可能性がある。アクセラレータは、少なくとも 15 ビット範囲の値で正しく動作しなければならない。
  2. ビデオ コーディング標準規格では通常、差異値を予測値に追加する前に、差異値のクリッピングが指定される (1 サンプル 8 ビットのビデオで、 9 ビットのクリッピングなど) が、これはデコードされた出力ピクチャに何の影響も与えないため、このクリッピングは実際には必要ない。このため、bConfigSpatialHost8or9Clipping が "1" に設定されることによってアクセラレータ ハードウェアがクリッピングを必要としていることが明らかな場合以外は、クリッピングがここで発生すると仮定しない。

3.5.5.2.2.2 8-8 オーバーフロー方式

BPPが "8" の場合は、8 ビット差異方式が使用できる。bPicIntra が "1" で BPP が "8" の場合は、この方式を使用する必要がある。その場合、各空間領域差異値は、8 ビットだけを使って表現される。この場合、各空間領域差分値は 8 ビットだけを使って表現される。8 ビットメソッドを使ってデータを送るとき、8 ビットデータのブロックはシーケンシャルに送られる。8 ビット空間領域残差データの各ブロックは DXVA_Sample8 の WTxHT 値から構成される。

IntraMacroblock が 1 の場合は、8 ビット サンプルはモーション圧縮予測に応じて加算あるいは減算 (bConfigResid8Subtraction と、サンプルが最初のパス ブロックとオーバーフロー ブロックのどちらにあるかにより決定) される符号付き差異である。IntraMacroblock が 0 でブロック内のあるピクセルを表現する差異が8ビットを使う表現にとって大きすぎるなら、サンプルの 2 つ目の"オーバーフロー" ブロックが送られ得る。

IntraMacroblock が "1" なら、8 ビットサンプルは次のように設定される :

  • bConfigIntraResidUnsigned が "1" なら、8 ビット サンプルは一定参照値 "0" に応じた符号なしの数として送られる。
  • bConfigIntraResidUnsigned が "0" なら、8 ビット サンプルは一定参照値 2(BPP-1) に応じた符号付きの数として送られる。
IntraMacroblock が "1" なら、オーバーフロー ブロックは送られるべきではない。

データのブロックは、MSB から LSB に 1 バリュー ビットのスキャンにより指定された wPatternCode 順に、シーケンシャルに送られ、次にすべての必要な 8 ビット オーバーフロー ブロックが wPC_Overflow に指定されたとして送られる。bConfigResid8Subtraction が "1" なら、このようなオーバーフロー ブロックは加算ではなく減算される。

各非イントラ マクロブロックの 8 ビット差異の最初のパスが追加される。bPicOverflowBlocks が "0" あるいは IntraMacroblock が "1" なら、2 つ目のパスはない。bPicOverflowBlocks が "1"、IntraMacroblock が "0" で、bConfigResid8Subtraction が "1" なら、各非イントラ マクロブロックの 8 ビット 差異の 2 番目のパスが追加される。

元の 8 ビット ブロックおよび対応する 8 ビット オーバーフロー ブロックの両方で、いずれかのサンプルが 0 でない場合、次のようになる。

  • bConfigResid8Subtraction が "0" の場合、サンプルの符号は両方のブロックで同一でなければならない。
  • bConfigResid8Subtraction が "1" の場合、元の 8 ビット ブロックのサンプルは、対応する 8 ビット オーバーフロー ブロックのサンプルの否定と、符号が一致しなければならない。

これにより、2 つのパスのそれぞれの後に、結果の 8 ビット クリッピングと共に、サンプルを予測ピクチャに追加できる。

注 : IntraMacroblock が 0 の場合、ビデオ コーディング標準規格に厳密に準拠しなくなるので、8+8 方式では +255 の残差値を表現できない。しかし、ここではこのフォーマットはサポートされている。その理由は、このフォーマットが、1) いくつかの既存の実装で使われている、2) ピクチャを表現するために必要なデータ量という点で効率的である、3) 通常はビデオ品質を有意に悪化させる結果にならないと考えられる、という理由による。

3.5.5.3 ブロック解除フィルタ制御

ブロック解除フィルタ制御コマンドが存在する場合、このコマンドは、マクロブロック内の各輝度ブロックに対して送信され、色光度ブロックの各組に対して 1 度ずつ送信される。コマンドは、マクロブロック内のラスタ スキャン順序で送信される。色光度のブロックの前に輝度のすべてのブロックが送信され、次に、色光度 4:2:0 コマンド 1 つ、必要に応じて色光度 4:2:2 コマンド 1 つ、次に必要に応じて色光度 4:4:4 コマンド 2 つと続く (両方の色光度成分に同じフィルタリングが適用される)。各ブロックのフィルタリングは、上端にかけて現れるブロック解除の仕様、およびそれに続く、左端にかけて現れるブロック解除の仕様によって指定される。色光度のブロック解除は一度だけ指定され、Cb 成分と Cr 成分の両方に同じブロック解除コマンドが使用される。たとえば、4:2:0 データを含む 16x16 のマクロブロックを、8x8 ブロックを使ってブロック解除する場合、輝度ブロック用に上下 2 つのエッジ フィルタリング コマンドを 4 セット送信し、次に色光度用に 2 つのエッジ フィルタリング コマンド 1 セットを送信することによって指定する。各ブロック解除エッジの指定のデータ構造は次のとおり。

DXVA_DeblockingEdgeControl {
    EdgeFilterStrength    7 /* H.263 では 4b のみ必要 */
    EdgeFilterOn        1
}

EdgeFilterStrength : このパラメータは、H.263 補遺 J で指定された、実行されるフィルタリングの強度を指定する。

EdgeFilterOn : このフラグは、エッジがフィルタされる場合は 1 となり、それ以外の場合は "0" でなければならない。

EdgeFilterOn が "1" と等しいエッジに対する実際のエッジ フィルタリングは、H.263 補遺 J に指定されているように、EdgeFilterStrength に指定された値で、範囲 [0, (2BPP)-1] への出力時のクリッピングを伴って、正確に実行されなければならない。H.263 補遺 J に指定されているように、すべてのブロックのすべての上エッジ フィルタリングは、どのブロックのどの左エッジ フィルタリングよりも "先に" 実行されなければならない (上エッジ フィルタリングに使われるサンプルの値は、左エッジ フィルタリングのどのブロック解除フィルタよりも先に再構築された値でなければならないという意味において)。

現在のブロック解除フィルタ コマンド バッファの外にあるマクロブロックのサンプル値が影響を受けないことが、バッファ タイプによって示されている場合は、バッファ内にブロック解除フィルタ コマンドを持つマクロブロックが担当するリージョンの左および上のすべてのエッジに対して、EdgeFilterOn パラメータは "0" でなければならない。

3.5.5.4 読み戻しバッファ

bPicReadbackRequests が "1" の場合は、読み戻しコマンド バッファが 1 つ存在し、これがアクセラレータに対して、結果の最終 (適応できるなら非ブロックの後で) ピクチャ マクロブロック データをホストに返すよう指令する。暗号化プロトコルを使用中なら、アクセラレータはガベージデータを返す、カプセルデータを返すなどのエラー指摘 (暗号化プロトコルによって指定される) を返して読み戻しリクエストに対応する場合がある。

アクセラレータに渡されるバッファには、読み取り対象のマクロブロック 1 つにつき 1 つのパラメータを含む読み戻しコマンドが含まれなければならない。

wMBaddress : (16 ビット) 現在のマクロブロックのマクロブロック アドレスをラスタ スキャン順序で指定する ("0" は左上マクロブロックのアドレス、PicWidthInMBminus1 は右上マクロブロックのアドレス、PicHeightInMBminus1 * PicWidthInMB は左下マクロブロックのアドレス、PicHeightInMBminus1 * PicWidthInMB + PicWidthInMBminus1 は右下マクロブロックのアドレス)。

BPP が "8" の場合は、データは符号なしの 8 ビット値 (したがって表面上、黒は Y=16、Cb=Cr=128 となり、白は Y=235、Cb=Cr=128 となる) で返されなければならない。BPP > 8 の場合は、データは符号なしの 16 ビット値で返されなければならない。

データは、アクセラレータからホストへ、次のフォーマットで返される。

  1. 最初に読み戻しコマンド バッファ自体のコピー、その後次の 32 バイト整列境界へのパディング、そして
  2. 読み戻しコマンド バッファに送信された順序で返されたマクロブロック データ値。フォーマットは各マクロブロックの各ブロックに対して、ブロックごとに WT·HT サンプル。マクロブロック内の残差ブロックは、MPEG-2 図 6-10、6-11、6-12 で指定された順に返されなければならない (ラスタスキャン順の Y、ラスタスキャン順の Cb の全 4:2:0 ブロック、Cr の 4:2:0 ブロック、Cb の 4:2:2 ブロック、Cr の 4:2:2 ブロック、Cb の 4:4:4 ブロック、Cr の 4:4:4 ブロックの順)。

3.5.6 オフホストの VLD ビットストリーム デコード処理

生のビットストリーム データの可変長デコードがアクセラレータ上で実行される場合、ピクチャのデコードのためにホストによって送信されるデータは、次の 3 タイプのバッファに分割される。

  1. 逆量子化行列バッファ。ビットストリーム データの逆量子化を行う方法についての情報を提供する。
  2. スライス制御バッファ。それぞれがビットストリーム データ バッファ内のスタート コードおよびデータの位置に関する情報を提供する。
  3. ビットストリーム データ バッファ。特定のビデオ コーディング仕様に基づいてエンコードされた生のデータ ストリームを含む。

3.5.6.1 逆量子化行列バッファ

逆量子化行列バッファは、オフホストでのビットストリーム デコード用に逆量子化行列を初期化するために送信される。逆量子化行列バッファは、新しい逆量子化行列バッファが供給されるまで、ビットストリーム内の、現在およびそれに続くすべてのビデオのデコード方法に関する情報を提供する。(この点で、逆量子化行列は固定的である。) ホストからアクセラレータに一度に複数の逆量子化行列バッファを送信してはならない。

DXVA_QmatrixData {
  for(i=0; i<4; i++)
    bNewQmatrix[i]      // 8b
  for(i=0; i<4; i++)
    if(bNewQmatrix[i] == 1)
      Qmatrix[i]        // WT・HT・16b
}

bNewQmatrix[i] : タイプ i の新しい逆量子化行列がバッファ内に存在するかどうかを示す。bNewQmatrix[i] が "1" の場合は、逆量子化行列バッファ内にタイプ i の新しい逆量子化行列が続いている。タイプ i=0 はイントラ輝度量子化、i=1 はインター輝度量子化、i=2 はイントラ色光度量子化、i=3 はインター色光度量子化である。ホストから先行する値が送られていない場合、アクセラレータは逆量子化行列のデフォルト値を想定できない。i=0 および i=1 の両方について、bNewQmatrix[i] の値は 0 であってはならない。

i=2 または i=3 について bNewQmatrix[i] の値が "0" の場合は、次のようになる。

  1. bNewQmatrix[i-2] が "0" の場合、アクセラレータは引き続き i の直前の逆量子化行列を使用しなければならない。
  2. bNewQmatrix[i-2] が "1" の場合、i の逆量子化行列を、i-2 の新しい逆量子化行列と同じに設定しなければならない。

該当するビデオ コーディング仕様で逆量子化行列が必要とされない場合 (H.261 や H.263 など) は、逆量子化行列バッファを送信してはならない。該当するビデオ コーディング仕様で逆量子化行列が必要とされる場合は、ホストによって、ビデオ デコード処理の開始時に、いずれかのビットストリーム データ バッファの転送の前、または転送と協調して、これらの逆量子化行列のために値が提供される必要がある。

注 : ホストから先行する値が送られていない場合は、量子化行列のデフォルト値は設定されない。該当するビデオ コーディング仕様でデフォルトで使用できる値が含まれているとしても、量子化行列の値は、明示的に送信される必要がある。

Qmatrix[i] : 逆量子化行列。bNewQmatrix[i] が "1" の場合のみ存在する。行列は、WT・HT 符号なしワード (各ワードの下位の 8 ビットだけが有力なビデオ コーディング標準規格で使用される) で構成される。逆量子化行列内でのデータ値の順序は、該当するビデオ コーディング仕様の定義に従わなければならない。

注 : MPEG-2ビットストリームの場合、Qmatrix[i] 内のデータ値は、MPEG-2 の副節 7.3.1 および 図 7-2 で指定されているとおり、ジグザグ逆スキャン順序である。

3.5.6.2 スライス制御バッファ

オフホストでの VLD ビットストリーム処理を先導するため、スライス制御バッファが提供されなければならない。ホスト ソフトウェア デコーダは、ビットストリーム内の "スライスレベルの" 再同期化ポイントを決定しなければならない。スライスは、ビットストリーム データ内に再同期化ポイントを含むマルチマクロブロック レイヤとして定義される。H.261 ビットストリームでは、GOB をスライスと見なし、H.263 ビットストリームでは、GOB 開始コードに続く一連の GOB をスライスと見さなければならない。スライス制御バッファには、対応するビットストリーム データ バッファの内容に応じて、1 つ以上の DXVA_SliceInfo データ構造体が含まれていなければならない。

DXVA_SliceInfo {
              wHorizontalPosition       //16b
              wVerticalPosition         //16b
              dwSliceBitsInBuffer       //32b
              dwSliceDataLocation       //32b
              bStartCodeBitOffset       // 8b
              bReservedBits             // 8b
              wMBbitOffset              //16b
              wNumberMBsInSlice         //16b
              wQuantizerScaleCode       //16b
              wBadSliceChopping         //16b
            }

wHorizontalPosition、wVerticalPosition : スライスの最初のマクロブロックの水平位置および垂直位置を、マクロブロックの単位で表したもの、0 はピクチャの一番上または一番左のマクロブロックを意味する。

dwSliceBitsInBuffer : 現在のスライスのデータを含む、対応するビットストリーム データ バッファ内の合計ビット数。MPEG-1、MPEG-2、および MPEG-4 では、スライス開始コードがバイト整列されるため、この値は 8 の倍数でなければならない。

dwSliceDataLocation : ビットストリーム データ バッファ内の、スライスのデータを含む最初のバイトの位置 (スライス開始コードの位置など)。スライスの開始部分が、対応するビットストリーム データ バッファ内にない場合は、0 でなければならない。

bStartCodeBitOffset : スライスのデータを含まない、dwSliceDataLocation のバイトの MSB の数 (MPEG-1、MPEG-2、MPEG-4 では、スライス開始コードがバイト整列されるため、0 となるが、H.261 および H.263 では、GOB 開始コードのバイト整列を強制しないため、0 でない場合がある)。範囲は、0...7 でなければならない。スライスの開始部分が、対応するビットストリーム データ バッファ内にない場合は、0 でなければならない。bStartCodeBitOffset によって、現在のスライスに関係しないとマークされた MSB は、前のスライスのデータを含む場合がある。

bMBbitOffset : スライスの開始部分から、ビットストリーム バッファ内のマクロブロック レイヤ データの最初のビットへのビット数。たとえば、wMBbitOffset が 83 なら、スライスのマクロブロック レイヤ データはスライス ヘッダー データ 83 ビットから開始する。スライスの開始部分が、対応するビットストリーム データ バッファ内にない場合は、0 でなければならない。

wNumberMBsInSlice : スキップされるマクロブロックを含め、スライス内にあるデータのマクロブロックの数。ピクチャのヘッダー、およびビットストリーム内の現在と次のスライスのヘッダーと初期マクロブロック データから、H.263 のスライス モードの任意スライス順序サブモードのようにこの数がすぐに決定できない場合は、0 の場合がある。H.261、MPEG-1、MPEG-2、MPEG-4 あるいは H.263 でスライス構造化モードの矩形スライスか任意スライス サブ モードを使用していないとき、ゼロであってはならない。

wQuantizerScaleCode : それぞれのビデオ コーディング仕様で指定された、ビットストリームのスライス レベルからの量子化スケール コード (H.261、MPEG-2、H.263、MPEG-1、および MPEG-4 に対して "1" ～ "31" の範囲)。

wBadSliceChopping : 次のように定義された値が入るパラメータ。

"0" : スライスのすべてのビットが、対応するビットストリーム データ バッファ内に位置する。

"1" : スライスの開始部分のビットが、対応するビットストリーム データ バッファ内にあり、スライスの終了部分のビットが (ビットストリーム データ バッファが一杯なため)、対応するビットストリーム データ バッファ内にない。

"2" : スライスの開始部分のビットが (前のビットストリーム データ バッファが一杯たなめ)、対応するビットストリーム データ バッファ内になく、スライスの終了部分のビットが、対応するビットストリーム データ バッファ内にある。

"3" : スライスの開始部分のビットが (前のビットストリーム データ バッファが一杯たなめ)、対応するビットストリーム データ バッファ内になく、また、スライスの終了部分のビットも (対応するビットストリーム データ バッファも一杯なため)、対応するビットストリーム データ バッファ内にない。

wBadSliceChopping が 0 以外の値になることは、通常、ホスト ソフトウェア デコーダ側で回避したほうがよい。

3.5.6.3 ビットストリーム データ バッファの内容

ビットストリーム バッファが使用される場合、可変長デコードでの下位ビットストリーム解析を含めたオフホストのデコードをサポートするため、バッファには単に、ビデオ ビットストリームからの生のバイトが含まれる。

意図された設計に沿った方法でビットストリーム データ バッファが使用されるよう、バッファの内容には一定の制限が課せられる。

  1. 各ピクチャの最初のビットストリーム データ バッファは、ビットストリーム内における当該ピクチャ データの最初のバイトで始まらなければならない。
  2. MPEG-1 と MPEG-2 使用以外では、(前のピクチャの全データの終りにに続いて)それがビット ストリーム内の現在のピクチャの最初のスライス(シーケンス ヘッダー、ピクチャ ヘッダーなど) に先行するなら、各ピクチャのビットストリーム データ バッファはすべてのデータとともに開始しなければならない。
  3. MPEG-1 と MPEG-2 使用については、最各ピクチャの初のビットストリーム データ バッファはピクチャの最初のスライスのスライス開始コードで開始しなければならない (シーケンス ヘッダーやピクチャ ヘッダーなどはない、なぜならすべての関連データはこのスペックのパラメータで提供されるからである)。
  4. 、ビットストリーム データのスライスの先頭が、あるビットストリーム データ バッファ内に位置している場合、そのバッファが割り当てられたサイズまで一杯でない限り、スライスの末尾も同じデータ バッファ内に位置していなくてはならない。

デコーダでは、ビットストリーム データ バッファへの格納状況を、スライスが複数のバッファになるべくまたがらないように管理したほうがよい。

3.6 アルファ ブレンド データのロード (bDXVA_Func=2)

DirectX VA 機能の 2 番目のタイプは、ビデオ データとブレンドされるアルファ ブレンディング サーフェスを指定する情報のロードである。

3.6.1 接続構成

アルファ ブレンド データをロードするための DirectX VA 接続構成データ構造体は、次のように定義しなければならない。

DXVA_ConfigAlphaLoad {
           // 指定された処理
          dwFunction         //32b
          dwReservedBits[3] // 3 * 32b 整列
          bConfigDataType //8b
}

dwFunction : 構成データの構造を記述する DXVA_ConfigQueryOrReplyFunc が含まれる。

bConfigDataType : 使用されるアルファ ブレンド データのタイプを指定する。次のように定義される。

"0" : IA44 アルファ ブレンディング サーフェスと 16 エントリ YUV パレット

"1" : AI44 アルファ ブレンディング サーフェスと 16 エントリ AYUV パレット

"2" : DXPD、Highlight、および DCCMD データと 16 エントリ AYUV パレット

"3" : AYUV グラフィック サーフェス

短期的なアクセラレータ実装では bConfigDataType が "1" あるいは "2" のサポートが許されているが、ほかのフォーマットが望ましく、限定モードプロファイルがそれ以外を示さない限り、フォーマット "1" と "3" の両方が中期的には要求されると予想される

3.6.2 最小限の相互動作性構成セット

設計上の条件として、すべての DirectX VA デコーダは、すべての DirectX VA アクセラレータと相互動作する必要がある。このためには、すべての DirectX VA デコーダが、接続構成セットのすべてのメンバと共に動作でき、すべての DirectX VA アクセラレータが、同セットの最低 1 つの接続構成メンバと共に動作できる必要がある。アルファ ブレンディング データをロードするための最小限の相互動作性構成セットは、bConfigDataType のすべての定義値から構成される。

3.6.3 AYUV アルファ ブレンディング サーフェスのロード

AYUV アルファ ブレンディング サーフェスは、それぞれ 32 ビットのサンプルの配列として定義される。このサーフェスは、グラフィックとデコード済みビデオ ピクチャをブレンドする際に、ソースとして使用できる。

各 AYUV サンプルは次のように構成される。

DXVA_AYUVsample{
            bSampleAlpha8   // 8b (MSB)
            bY_Value        // 8b
            bCbValue        // 8b
            bCrValue        // 8b (LSB)
}

bSampleAlpha8 : サンプルの不透明性。値 0 は、サンプルが透明であることを示す (つまり、ほかのエントリはブレンド後のピクチャに影響を与えない)。値 255 は、サンプルが不透明であることを示す (つまり、ほかのエントリがブレンド後のピクチャ サンプルの値を完全に決定する)。SampleAlpha8 の値が "0" でない場合、指定されたブレンドは、グラフィック値の (SampleAlpha8+1) 倍を、ピクチャ値の (255-SampleAlpha8) 倍および定数 128 に加算し、結果を 8 桁右シフトする。SampleAlpha8 の値が 0 の場合は、指定されたブレンドはピクチャ値をそのまま使用する。

bY_Value, bCbValue, bCrValue : 符号付き数量として指定される Y、Cb、Cr 色空間内の色 (ITU-T 勧告 601 による)。たとえば、BPP=8 の場合、表面上、黒は Y=16、Cb=Cr=128 で指定され、白は Y=235、Cb=Cr=128 で指定される。

AYUV アルファ ブレンディング サーフェスの幅と高さは、関連付けられたバッファ記述リスト内で指定される。

3.6.3.1 16 エントリ AYUV パレットのロード

16 エントリ YUV パレットは、16 個の DXVA_AYUVsamples サンプルの配列として定義される。この場合、個々のサンプルの SampleAlpha8 は意味を持たないため、"0" でなければならない。

パレットは、グラフィックとデコード済みビデオ ピクチャをブレンドする際に、ソースを作成するために使用できる。このパレットは、以下のいずれかと共に、グラフィック ソースの作成に使用できる。

  1. IA44/AI44 アルファ ブレンディング サーフェス
  2. DPXD アルファ ブレンディング サーフェス、ハイライト バッファ、および DCCMD データ

3.6.3.2 AYUV サーフェスのロード

16 エントリ パレットのみをロードするのではなく、グラフィックの内容を指定する AYUV イメージとして、イメージ グラフィック全体を直接ロードできる。

3.6.4 IA44/AI44 アルファ ブレンディング サーフェスのロード

インデックスアルファ 4-4 (IA44) アルファ ブレンディング サーフェスは、それぞれ次のように構成される 8 ビットのサンプルの配列として定義される。

DXVA_IA44sample{
        SampleIndex4        // 4b (MSB)
        SampleAlpha4        // 4b (LSB)
        }

アルファインデックス 4-4 (AI44) アルファ ブレンディング サーフェスは、それぞれ次のように構成される 8 ビットのサンプルの配列として定義される。

DXVA_AI44sample{
    SampleAlpha4        // 4b (MSB)
    SampleIndex4        // 4b (LSB)
    }

SampleIndex4 : サンプルの 16 エントリ パレットへのインデックス。

SampleAlpha4 : サンプルの不透明性。値 "0" は、サンプルが透明であることを示す (つまり SampleIndex4 のパレット エントリは、ブレンド後のピクチャに影響を与えない)。値 15 は、サンプルが不透明であることを示す (つまり SampleIndex4 のパレット エントリが、ブレンド後のピクチャの状態を完全に決定する)。SampleAlpha4 の値が 0 でない場合、指定されたブレンドは、グラフィック値の (SampleAlpha4+1) 倍を、ピクチャ値の (15-SampleAlpha4) 倍および定数 8 に加算し、結果を 4 桁右シフトする。SampleAlpha4 の値が 0 でない場合、指定されたブレンドはピクチャ値をそのまま使用する。

IA44 アルファ ブレンディング サーフェスの幅と高さは、関連付けられたバッファ記述リスト内で指定される。

3.6.5 DPXD アルファ ブレンディング サーフェスのロード

デコードされる PXD (DPXD) アルファ ブレンディング サーフェスは、2 ビット サンプルのパックされたフレーム構造化配列として定義される。これらのサンプルはそれぞれ、ハイライトおよび DCCMD データによって決定された 4 色カラー テーブルへのインデックスとして使用される。DPXD、ハイライト、および DCCMD の組み合わせの結果は、IA44 サーフェスと同等であり、16 エントリ YUV パレットと共にブレンディングに使われる。バイトの配列として取り扱われる場合、最初の 2 ビット サンプルのインデックスは、DPXD データの最初のバイトの MSB に、次のサンプルは次の 2 ビットに、3番目のサンプルは次の 2 ビットに、4 番目のサンプルは LSB に、5 番目のサンプルは 次のバイトの MSB に、というように配置しなければならない。

DPXD アルファ ブレンディング サーフェスは、RLE (run-length) エンコード フォーマットの DVD 上の PXD 情報から作成することもできる。このため、DVD 上の PXD から DirectX VA のための DPXD を作成する場合、ホストが、ディスクからの生データの RLE (run-length) デコードを実行する必要がある。

サーフェスのストライドは、2 ビット サンプル単位でなく、バイト単位のストライドとして解釈されなければならない。ただし、幅と高さは 2 ビット サンプル単位でなければならない。

注 : DVD 上の PXD は、フィールド構造化インターレース フォーマットである。ここで定義されている DPXD アルファ ブレンディング サーフェスは、フィールド構造化インターレース フォーマットではない。このため、DVD の PXD データから DPXD を作成する場合は、ホストが、2 つのフィールドからデータをインターリーブする必要がある。

注 : DVD サブピクチャ定義およびデータ フィールド解釈の詳細については、「DVD Specifications for Read-Only Disk:Part 3 – Video Specification (v. 1.11, May '99)」を参照すること。

3.6.6 ハイライト データのロード

ハイライト データは、DVD ROM 仕様に準拠した方法でフォーマットされ、アルファ ブレンディング サーフェスを作成するため、DCCMD データと共に DPXD サーフェスに適用される。ハイライト データ バッファの内容は、次のように定義しなければならない。

DXVA_Highlight {
    wHighlightActive    // 16b
    wHighlightIndices   // 16b
    wHighlightAlphas    // 16b
    HighlightRect       // 128b
}

HighlightActive : 矩形ハイライト領域が現在アクティブになっているかどうかを示す ("0" は非アクティブを示し、"1" はアクティブを示す)。非アクティブの場合、ハイライト データがブレンド後のピクチャの内容に影響を与えてはならない。

HighlightIndices : DPXD 内の各 2 ビット インデックスに対し、サブピクチャ上でハイライトされた矩形領域の 4 ビット パレット インデックスを示す。4 つの MSB はインデックス 3、次の 4 ビットはインデックス 2、次の 4 ビットはインデックス 1、4 つの LSB はインデックス "0" に対応していなければならない。

HighlightAlphas : DPXD に使用される各 2 ビット インデックスに対し、サブピクチャ上でハイライトされた矩形領域の 4 ビット不透明性を示す。4 つの MSB はインデックス 3、次の 4 ビットはインデックス 2、次の 4 ビットはインデックス 1、4 つの LSB はインデックス 0 にしていなければならない。4 ビット不透明性の値は、上の SampleAlpha4 に関する説明と同様に解釈しなければならない。

HighlightRect : RECT データ タイプとしての、矩形ハイライト領域の定義を含む。

RECT パラメータには次の制限が適用される :

  • "left" と "top" はゼロ以上でなければならない。
  • "right" と "bottom" はそれぞれ "left" と "top" より大きくなければならない
  • "right" は 720 を越えてはない、"bottom" は 576 を越えてはならない。

注 : DVD の仕様でサブピクチャ矩形領域を定義する方法と、Microsoft アプリケーションで通常使用されている方法には違いがあると見られる。 この仕様では Microsoft の慣例に従い、ピクチャの左上にある幅 10 高さ 10 の矩形を、Top = 0、Left = 0、Right = 10、Bottom = 10 と定義する。DVD の仕様の慣例では、Right = 9 および Bottom = 9 が使用される。

3.6.7 DCCMD データのロード

DCCMD (ディスプレイ制御コマンド) データは、DVD ROM 仕様に準拠した方法でフォーマットされ、アルファ ブレンディング サーフェスを作成するため、ハイライト データと共に DPXD サーフェスに適用される。DCCMD データ バッファの内容は、DVD ディスプレイ制御コマンド (DCCMD) のリストとしてフォーマットされたデータで構成しなければならない。

注 : DVD サブピクチャ定義およびデータ フィールド解釈の詳細については、「DVD Specifications for Read-Only Disk:Part 3 – Video Specification (v. 1.11, May '99)」を参照すること。

3.7 アルファ ブレンド コンビネーション (bDXVA_Func=3)

アルファ ブレンド コンビネーションでは、最後にロードされてたアルファ ブレンド ソース情報を参照ピクチャと組み合わせて、表示用のブレンド ピクチャを作成する。この処理は、アルファ ブレンド コンビネーション データ バッファを使って制御される。

3.7.1 接続構成

アルファ ブレンド コンビネーションのための DirectX VA 接続構成データ構造体は、次のように定義しなければならない。

DXVA_ConfigAlphaCombine {
  // Operation Indicated
  dwFunction                 // 32b
  dwReservedBits[3]         // 3 * 32b アラインメント

  bConfigBlendType          // 8b
  bConfigPictureResizing    // 8b
  bConfigOnlyUsePicDestRectArea  //8b
  bConfigGraphicResizing    // 8b
  bConfigWholePlaneAlpha    // 8b
}

dwFunction : 構成データの構造を記述する DXVA_ConfigQueryOrReplyFunc が含まれる。

bConfigBlendType : 実行されるアルファ ブレンド コンビネーションのタイプを指定する。次のように定義される。

"0": フロントエンドのバッファ間ブレンド

"1": バックエンドのハードウェア ブレンド

短期的なアクセラレータ実装では bConfigBlendType = "1" のサポートが許されているが、中期的には bConfigBlendType = "0" のサポートが必要になるものと予想される。

bConfigPictureResizing: サブピクチャ ブレンディングの PictureSourceRect16thPel が違うかどうかを示す、PictureDestinationRect から (PictureSourceRect16thPel の 1/16th サンプル スケーリングで調整された) 幅と高さ、また PictureSourceRect16thPel のパラメータが16の倍数ではないかどうかを示す、それによってソース ピクチャにアクセラレータによる再サンプルを要求する。"1" は (リサイズ精度であれ、サブピクセル精度であれ) 再サンプルがサポートされていることを示し、"0" はサポートされていないことを示す。

bConfigOnlyUsePicDestRectArea: デコーダが PictureDestinationRect 外に落ちる生成されたデスティネーション ピクチャの出力範囲の値を指定するコマンド操作が可能かどうかを示す。"0" は PictureDestinationRect の外部エリアはブレンド コンビネーション コマンドで指定可能であることを示す。"1" はホスト デコーダは PictureDestinationRect が指定した外のブレンドされたサーフェスの値は信頼できず、そのリージョンは表示できないことを示す。

bConfigGraphicResizing: サブピクチャ ブレンディングの GraphicSourceRect が GraphicDestinationRect のサイズと違っているかどうかを示す、それによってアルファ ブレンディング グラフィックスをアクセラレータが再サンプルするかどうかを要求する。"1" はリサイズがサポートされていることを示し、"0" はサポートされていないことを示す。

bConfigWholePlaneAlpha : グラフィック データに全プレーン アルフファ パラメータを適用できるかどうかを指定する。"1" は全プレーンアルファが適用可能なことを示し、"0" は適用できないことを示す。

3.7.2 最小限の相互動作性構成セット

設計上の条件として、すべての DirectX VA デコーダは、すべての DirectX VA アクセラレータと相互動作する必要がある。このためには、すべての DirectX VA デコーダが、接続構成セットのすべてのメンバと共に動作でき、すべての DirectX VA アクセラレータが、同セットの最低 1 つの接続構成メンバと共に動作できる必要がある。アルファ ブレンディング データをロードするための最小限の相互動作性構成セットは bConfigBlendType から構成される、それは DirectX VA 限定モード プロファイルによって決められた範囲の値を持つ。

3.7.3 アルファ ブレンド コンビネーション バッファ

アルファ ブレンド コンビネーション バッファは、ソース ピクチャと、アルファ ブレンディング情報を伴うグラフィック イメージからの、ブレンド ピクチャの生成を制御する。ソース ピクチャおよび宛先ピクチャが 4:4:4 フォーマットでない場合は、サブサンプリングされたソースの基準色情報に対して、グラフィック ブレンディング情報のサンプルが 1 つ置き (1、3、5 など) に、ブレンド結果を得るために適した方向 (垂直または水平) に適用されなければならない。

DXVA_BlendCombination {
          wPictureSourceIndex           //16b
          wBlendedDestinationIndex      //16b
          PictureSourceRect16thPel      //128b
          PictureDestinationRect        //128b
          GraphicSourceRect             //128b
          GraphicDestinationRect        //128b
          wBlendDelay                   //16b
          bBlendOn                      //8b
          bWholePlaneAlpha              //8b
          OutsideYUVcolor               //32b
        }

wPictureSourceIndex : グラフィックと組み合わされるピクチャのインデックス。バックエンドのハードウェア アルファ ブレンディングが使用されている場合は、0xFFFF でなければならない。

wBlendedDestinationIndex : 作成される組み合わせピクチャのインデックス。バックエンドのハードウェア アルファ ブレンディングを使用している場合は、0xFFFF でなければならない。wPictureSourceIndex と同じであってはならない。

PictureSourceRect16thPel: グラフィックと組み合わされるソースピクチャの範囲は輝度コンポーネントの 1/16th サンプルの単位で RECT データ構造体として指定される。言い換えると、RECT データ 構造体のパラメータは固定小数点で表現される、バイナリ ポイント前 28 ビットと後 4 ビットである。(この 1/16th サンプル精度では PictureSourceRect16thPel はMPEG-2 の frame_centre_horizontal_offset と frame_centre_vertical_offset パン-スキャン パラメータと同じ精度を持つ) bConfigPictureResizing が "0" なら、PictureSourceRect16thPel のすべてのパラメータは 16 の整数倍でなければならない。

次の制限が PictureSourceRect16thPel の RECT パラメータに適用される :

  • "left" と "top" はゼロ以上でなければならない。
  • "right" と "bottom" はそれぞれ "left" と "top" 以上でなければならない。
  • "right" が "left" と同じ、あるいは "top" が "bottom" と同じなら、bConfigOnlyUsePicDestRectArea が "0" の場合のみ、RECT パラメータのすべての値は "0" を持ち、ソースピクチャを使用しないことを示す。

たとえば、PictureSourceRect16thPel を使って全 MPEG-2 デコードされたピクチャを選択したら、PictureSourceRect16thPel パラメータは次のように計算される :

  • left = 0
  • top = 0
  • right = 16×horizontal_size
  • bottom = 16×vertical_size

PictureDestinationRect : ソース ピクチャからの領域を保持する宛先ピクチャの領域。RECT データ構造体として指定する。bConfigPictureResizing が "0" の場合は、幅と高さが PictureSourceRect16thPel で指定された領域と同じでなければならない。PictureDestinationRect と PictureSourceRect16thPel のサイズが異なる場合、適用される再サンプリング方式は指定されないが、最低でもバイリニア再サンプリングと同等の品質を持っていたほうがよい。

次の制限が RECT パラメータに適用される :

  • "left" と "top" はゼロ以上でなければならない。
  • "right" と "bottom" はそれぞれ "left" と "top" 以上でなければならない。
  • "right" が "left" と同じ、あるいは "top" が "bottom" と同じなら、bConfigOnlyUsePicDestRectArea が "0" の場合のみ、RECT パラメータのすべての値は "0" を持ち、PictureSourceRect16thPel もすべてのパラメータが値 "0" を持つことを示す。
  • bConfigBlendType = 0 なら、"right" と "bottom" はそれぞれ非圧縮デスティネーションピクチャ サーフェスに割り当てられた幅と高さを越えてはならない。
  • bConfigBlendType = 1 なら、"right" と "bottom" はそれぞれソース グラフィック サーフェスに割り当てられた幅と高さを越えてはならない。

GraphicSourceRect: ソース ピクチャと組み合わされるグラフィック ピクチャの領域。RECT データ構造体として指定する。アルファ ブレンド データ ローディングが bConfigDataType に "2" を使うなら、次の制限が GraphicSourceRect に適用される :

  1. GraphicSourceRect の "top" と "left" パラメータはゼロでなければならない。
  2. GraphicSourceRect の "right" パラメータは "End X-coordinate" から 直前の DVD SET_DAREA DCCMD の "Start X-coordinate" を引いたものに 1 を加えたものと等しくなければならない、最後に加えた 1 は下の注に説明してあるように矩形補間の違いを調整するものである。
  3. GraphicSourceRect の "bottom" パラメータは "End Y-coordinate" から 直前の DVD SET_DAREA DCCMD の "Start Y-coordinate" を引いたものに 1 を加えたものと等しくなければならない、最後に加えた 1 は下の注に説明してあるように矩形補間の違いを調整するものである。

次の制限が RECT パラメータに適用される :

  1. "left" と "top" はゼロ以上でなければならない。
  2. "right" と "bottom" はそれぞれ "left" と "top" 以上でなければならない。
  3. "right" が "left" と同じ、あるいは "top" が "bottom" と同じなら、すべての RECT パラメータは値 "0" を持たなければならない、これはグラフィック ピクチャを使用しないことを示す。
  4. "right" と "bottom" はそれぞれグラフィック ソース サーフェスの幅と高さを越えてはならない。 bConfigDataType = "2" のとき、割り当てられた幅と高さはそれぞれ 720 と 576 である。

GraphicDestinationRect : グラフィック ピクチャからの領域を保持する宛先ピクチャの領域。RECT データ構造体として指定する。bConfigGraphicResizing が "0" の場合は、幅と高さが GraphicSourceRect で指定された領域と同じでなければならない。GraphicDestinationRect と GraphicSourceRect のサイズが異なる場合、グラフィックに適用される再サンプリング方式は指定されないが、最低でもブレンディング情報を表す AYUV サーフェスのバイリニア再サンプリングと同等の品質を持っていたほうがよい。

次の制限が GraphicDestinationRect の RECT パラメータに適用される :

  1. この要件が次のパラグラフと3.7.3.3 と 3.7.3.4 章で説明されている 8 サンプルによるグラフィックのオフセットの必要性と矛盾しない限りは、"left" と "top" はゼロ以上でなければならない。
  2. "right" と "bottom" はそれぞれ "left" と "top" 以上でなければならない。
  3. "right" が "left" と同じ、あるいは "top" が "bottom" と同じなら、すべての RECT パラメータは "0" を持たなければならない、GraphicSourceRect もすべてのパラメータが "0" を持つように指定しなければならない。
  4. bConfigBlendType = 0 なら、"right" と "bottom" はそれぞれ非圧縮デスティネーション サーフェスに割り当てられた幅と高さを越えてはならない。
  5. bConfigBlendType = 1 なら、"right" と "bottom" はそれぞれソース グラフィック サーフェスに割り当てられた幅と高さを越えてはならない。

アルファ ブレンド データ ローディングが bConfigDataType に "2" を使い、bConfigGraphicResizingに "0" を使うなら、次の制限が GraphicSourceRect に適用される :

  1. "top" は直前の DVD SET_DAREA DCCMD の "Start Y-coordinate" と等しくなければならない。
  2. "left" は直前の DVD SET_DAREA DCCMD の "Start X-coordinate" あるはその値引く 8 のどちらかと等しくなければならない (3.7.3.3 章と 3.7.3.4 章を参照すること)。
  3. GraphicDestinationRect の "right" パラメータは "left" プラス 直前の DVD SET_DAREA DCCMD の "End X-coordinate" マイナス "Start X-coordinate" プラス 1 と等しくなければならない。最後に加えた 1 は下の注に説明してあるように矩形補間の違いを調整するものである。
  4. GraphicDestinationRect の "bottom" パラメータは "top" プラス 直前の DVD SET_DAREA DCCMD の "End Y-coordinate" マイナス "Start Y-coordinate" プラス 1 と等しくなければならない。最後に加えた 1 は下の注に説明してあるように矩形補間の違いを調整するものである。

注 : DVD の仕様でサブピクチャ矩形領域を定義する方法と、Microsoft アプリケーションで通常使用されている方法には違いがあると見られる。 この仕様では Microsoft の慣例に従い、ピクチャの左上にある幅 10 高さ 10 の矩形を、Top = 0、Left = 0、Right = 10、Bottom = 10 と定義する。DVD の仕様の慣例では、Right = 9 および Bottom = 9 が使用される。

wBlendDelay : バックエンドのハードウェア ブレンディングが使用されている場合、wBlendDelay には組み合わせ処理により効果が現れるまでのディレイ (ミリ秒数) が含まれる。フロントエンド ブレンディングが使用されている場合は、意味がないため、0 でなければならない。

bBlendOn : バックエンドのハードウェア ブレンディングが使用されている場合は、bBlendOn が "1" のブレンディング コンビネーション機能で指定された時間から、bBlendOn = 1 の新しいブレンディング コンビネーションで指定された実行時間までか、または bBlendOn が "0" のブレンディング コンビネーション機能によりブレンディングが無効になるまで、指定されたブレンディングが適用されなければならない。

bWholePlaneAlpha : グラフィックのアルファ チャンネルの不透明性を示す乗数が含まれる。値 "0" は、グラフィックが透明であることを示し (つまりグラフィックの内容がブレンド後のピクチャに影響を与えない)、値 "255" は、グラフィック内容がサンプルの不透明度を最大限使用することを示す。bWholePlaneAlpha の値が "0" でない場合、指定されたブレンドは、グラフィック内容の各位置の不透明度に (bWholePlaneAlpha+1)/256 を乗算する。bWholePlaneAlpha の値が "0" の場合、指定されたブレンドは、グラフィック内容で指定された不透明度をそのまま使用する。bConfigWholePlaneAlpha が "0" の場合は、"0" でなければならない。

OutsideYUVcolor: PictureDestinationRect 外の範囲がブレンディング 一定色を持つとして生成されるかどうかを示す識別子が入る、またその場合その一定色が入る。OutsideYUVcolor は DXVA_AYUVsample としてフォーマットされ、以下の決まりに従う :

  1. PictureDestinationRect 外の範囲がブレンディング一定色として生成されるなら、OutsideYUVcolor の bSampleAlpha8 の値は "255" でなければならない。
  2. 以下の 2 つの場合のどちらかであれば、OutsideYUVcolor の bSampleAlpha8 の値は "0" でなければならない :
    1. PictureDestinationRect 外の範囲がブレンディングによっては影響されない場合、あるいは
    2. PictureDestinationRect 外の範囲が使用され得ない (bConfigStayInPicDestRectArea が 値 "1" を持つ) 場合。
  3. OutsideYUVcolor の bSampleAlpha8 の他のすべての値は将来の使用のために予約されている。

bConfigStayInPicDestRectArea が "1" なら、OutsideYUVcolor の bSampleAlpha8 の値は "1" でなければならない。

OutsideYUVcolor の bSampleAlpha8 が "0" なら、ブレンドの影響を受けるデスティネーション サーフェスの範囲は PictureDestinationRect 内の部分である。OutsideYUVcolor の bSampleAlpha8 が "255" なら、PictureDestinationRect 外だが GraphicDestinationRect 内のデスティネーション サーフェスの範囲は OutsideYUVcolor の非アルファ パラメータに指定される色でブレンディングしたグラフィックによって生成され、PictureDestinationRect と GraphicDestinationRect 両方の外に落ちるデスティネーション サーフェスの全割り当て範囲は OutsideYUVcolor の非アルファ パラメータで指定された色に設定される。bConfigBlendType が "1" なら、OutsideYUVcolor パラメータは黒とのブレンディングを示す bSampleAlpha8 = 255, bY_Value = 16, bCbValue = bCrValue = 128 を指定しなければならない。

注 : bConfigBlendType が "1" (バックエンド ハードウェア ブレンド) なら、実際のブレンディング操作はここで説明したものとは少し異なる場合がある。しかし、表示結果は同じでなければならない。たとえば、ビデオ ピクチャをソースからデスティネーション サイズにマップするよう指定したリサイズは、逆の方法でグラフィック内容をソースビデオ ピクチャに従ってその正しい位置にマップするよう適用されるかもしれない、するとこの操作の違いに対応してブレンディング結果が表示される - しかし結果の最終視覚効果はブレンド コンビネーション コマンドで指定されなければならない。

3.7.3.1 例 : MPEG-2 パン - スキャン 操作

たとえば、PictureSourceRect16thPel を使って MPEG-2 ビデオ パン - スキャン パラメータが指定する範囲を選択した場合、PictureSourceRect16thPel パラメータは次のように組み合われる (その計算された値が上の制限に反しないように提供される、MPEG-2 パン - スキャン パラメータの場合と 特に MPEG-2 DVD コンテンツの場合) :

  1. left = 8×(horizontal_size - display_horizontal_size) - frame_centre_horizontal_offset
  2. top = 8×(vertical_size - display_vertical_size) - frame_centre_vertical_offset
  3. right = left + 16×display_horizontal_size
  4. bottom = top + 16×display_vertical_size

次に PictureDestinationRect は通常次のように作成される :

  1. left = 0 or 8 (3.7.3.3 章)
  2. top = 0
  3. right = left + display_horizontal_size
  4. bottom = top + display_vertical_size

3.7.3.2 例 : 16:9 ピクチャ での DVD 4:3 パン スキャン

たとえば、16:9 ピクチャで 4:3 パン スキャンを MPEG-2 DVD で使うと、パン スキャン パラメータは上記の制限を犯さない範囲に制限され、更にこの場合にはパン スキャン パラメータは次の制限に従う :

  1. horizontal_size = 720 or 704
  2. vertical_size = 480 or 576
  3. display_horizontal_size = 540
  4. display_vertical_size = vertical_size
  5. frame_centre_vertical_offset = 0
  6. frame_centre_horizontal_offset は次の絶対値を持つ
    1. horizontal_size = 720 に対して 1440 以下
    2. horizontal_size = 704 に対して 1312 以下

次に 3.7.3.1 章で説明されている公式がこの場合直接に適用される。

3.7.3.3 例: DVD 704 ワイド 非パン スキャン ピクチャ操作

もう 1 つの例として、704 ワイド ピクチャで DVD MPEG-2 を使うとき、デコードされたピクチャの境界を拡張する 3.7.3.1 章を使うと (デコードされた horizontal_size を 704 に拡張するように display_horizontal_size に 720 を指定するなら)、転送元矩形を指定する。このような場合、ホスト ソフトウェア デコーダは転送元矩形を割り当てられたソース範囲の外まで届くようにクロップし、そのクロップに対してデスティネーション矩形の調整を管理する必要がある。この場合、2 つの基本的な場合がある。両方とも次のようなピクチャ 転送元矩形の指定を要件とする :

  • left = 0
  • right = 16×(left + horizontal_size) = 11264

2 つの場合とは :

  1. ピクチャ デスティネーション矩形が次のように設定され得るか :
    • left = (display_horizontal_size – horizontal_size) / 2 = 8
    • right = left + horizontal_size = 712
    この場合直進方式のグラフィックを使う。
  2. あるいはピクチャ デスティネーション矩形が次のように設定され得るか :
    • left = 0
    • right = left + horizontal_size = 704
    この場合グラフィック デスティネーション矩形はシフトされたピクチャ デスティネーションを補償する 8 サンプルで左に表示される。

これらの 2 つの場合のうち多分 2 番目が優先される

3.7.3.4 例 : DVD 352 ワイド ピクチャ操作

もう 1 つの例は 325 ワイドピクチャの DVD 使用である、これはピクチャ 転送元矩形 (1/16th サンプル解像度) を使って 704 の幅に拡大する :

  1. left = 0
  2. right = 16×(left + horizontal_size) = 5632
そして、ピクチャ デスティネーション矩形は 2 つの場合がある :
  1. ピクチャ デスティネーション矩形が次のように設定されるか :
    1. left = 8
    2. right = left + 2×horizontal_size = 712
    3. この場合直進方式のグラフィックを使う。
  2. あるいはピクチャ デスティネーション矩形が次のように設定され得るか :
    1. left = 0
    2. right = left + 2×horizontal_size = 704
    3. この場合グラフィック デスティネーション矩形はシフトされたピクチャ デスティネーションを補償する 8 サンプルで左に表示される。

これらの 2 つの場合のうち多分 2 番目が優先される

3.7.3.5 例 : DVD 720 ワイド ピクチャ操作

かなり小さな例は 720 ワイド ピクチャの DVD MPEG-2 の使用である、(1/16 サンプル解像度で) ピクチャ 転送元矩形は次のとおりである :

  1. left = 0
  2. right = left + 16×horizontal_size = 11520
デスティネーション矩形は通常以下のとおりである :
  1. left = 0
  2. right = left + horizontal_size = 720

3.7.3.6 例 : 4:3 ピクチャ操作における DVD 16:9 レターボックス高さ

もう 1 つの例はレターボックス フレーミングを持つ 4:3 ディスプレイでのDVD 16:9 ビデオの使用である。以下のピクチャ 転送元矩形を使うことによってサポートされる :

  1. top = 0
  2. bottom = top + 16×vertical_size = 7680 or 9216
そしてピクチャ デスティネーション矩形は以下のとおりである :
  1. top = vertical_size / 8 = 60 or 72
  2. bottom = 7 × vertical_size / 8 = 420 or 504

3.8 ピクチャ再サンプリング制御 (bDXVA_Func=4)

ピクチャの再サンプリング機能は、空間スケーラブル ビデオ コーディング、参照ピクチャの再サンプリング、またはアップサンプル ピクチャや表示ピクチャとして使用するための再サンプリングといった目的で定義される。

再サンプリングは、ピクチャのエッジでの "クリッピング" を使い、H.263 補遺 O 「空間スケーラビリティ (Spatial Scalability)」、または MPEG-2 および MPEG-4 の「空間スケーラビリティ (Spatial Scalability)」のいくつかのフォーマットと同じである H.263 補遺 P に定義されているように実行されなければならない。この場合、単純な 2 タップ分割可能フィルタリングが使用される。

3.8.1 接続構成

ピクチャの再サンプリング制御に接続構成は不要である。この処理には適切な制限モード GUID のサポートのみが必要となる。

3.8.2 最小限の相互動作性構成セット

ピクチャの再サンプリング制御には接続構成が不要なため、この処理に最小限の相互動作性セットを定義する必要はない。

3.8.3 ピクチャ再サンプリング制御バッファ

再サンプリング処理を制御するためのバッファタイプが 1 つ定義されている。

DXVA_PicResample {

  wPicResampleSourcePicIndex    // 16b
  wPicResampleDestPicIndex      // 16b

  wPicResampleRcontrol          // 8b
  bPicResampleExtrapWidth       // 8b
  bPicResampleExtrapHeight

  dwPicResampleSourceWidth      // 32b
  dwPicResampleSourceHeight     // 32b

  dwPicResampleDestWidth        // 32b
  dwPicResampleDestHeight       // 32b

  dwPicResampleFullDestWidth    // 32b
  dwPicResampleFullDestHeight   // 32b
}

wPicResampleRcontrol : 再サンプリング処理の平均化丸めモードを指定する。H.263 補遺 O 「空間スケーラビリティ (Spatial Scalability)」の場合は、このパラメータは 1 でなければならない。(これは、H.263 補遺 O の空間スケーラビリティに必要なアップサンプリングと同等の、H.263 補遺 P の RCRPR の値に対応する。) H.263 補遺 P 「参照ピクチャ再サンプリング (Reference Picture Resampling)」の場合は、このパラメータは H.263 のパラメータ RCRPR と同じでなければならない。

bPicResampleExtrapWidth、bPicResampleExtrapHeight : 0 以外で、かつピクチャ境界上での動きベクトル使用のパディング方法がアクセラレータ上で使用されている場合は、再サンプリングに、再サンプルされたピクチャのパディングが含まれなければならない。また、このパディングは、実行される再サンプリング処理に関係なく、少なくとも、再サンプルされたピクチャの各エッジの周りに指定された幅および高さをカバーしなければならない。

dwPicResampleSourcePicIndex : 再サンプル対象の参照バッファを指定する。

dwPicResampleDestPicIndex : 参照ピクチャの再サンプリング処理の出力に使用されるバッファを指定する。

dwPicResampleSourceWidth、dwPicResampleSourceHeight : 宛先ピクチャに再サンプルされるソース ピクチャの領域の幅と高さ。

dwPicResampleDestWidth、dwPicResampleDestHeight : ソース ピクチャから再サンプルされたデータを格納する宛先ピクチャの領域の幅と高さ。

dwPicResampleFullDestWidth、dwPicResampleFullDestHeight : ソース ピクチャから再サンプルされたデータを格納する宛先ピクチャの領域全体の幅と高さ。ソース再サンプリング領域の外にサンプルを生成するには、クリッピングが使用されなければならない。(このパラメータは、輝度の幅または高さが 16 で除算できないカスタム ソース フォーマットに H.263 補遺 P サポートを提供するために必要となる。)

4 制限モード

多くの制限モード プロファイルがこの章で定義される。これらの制限モード プロファイルによって、どの制限モード プロファイルをサポートしているかの指標が得られるので、デコーダはアクセラレータの性能を確認することができる。

ここで定義されているいくつかの制限モード プロファイルはここで定義される他の制限モード プロファイルの能力の単純なサブセットで定義される (たとえば、MPEG2_A プロファイルは MPEG2_B プロファイルの能力のサブセットである)。アクセラレータ能力決定の論理構造を強化するため次のことが要求される、ある個別の制限モード プロファイルをサポートするアクセラレータは、問題のそのプロファイルの能力のサブセットとして定義されるすべての制限モード プロファイルをもサポートしなければならない。たとえば、MPEG2_A プロファイルは MPEG2_B プロファイルの能力のサブセットとして定義されるので、MPEG2_B プロファイルをサポートするすべてのアクセラレータは MPEG2_A プロファイルをもサポートしなければならない。

4.1 新規制限プロファイルの追加

以下に挙げる制限モード プロファイルは、将来広くサポートされると思われる機能の組み合わせを見越して定義された。Microsoft では、これら以外の、実用的かつ必要と思われる各種機能の組み合わせを含む新規プロファイル追加の提案を受け入れている。制限モード プロファイルは、デコードに必要な一連のビデオ コーディング "ツール" を確立するために、この仕様で定義されている。最も重要な点は、特定のビデオ データ フォーマットが、API を使って何らかの方法でデコードできるかどうかを決定することである。一連の "ツール" を確立することに加え、デコーダは、それらのツールを、API を使ってどのように操作するか認識している必要がある。これについては、続く構成情報のセクションで解説する。

4.2 非制限処理

この API/DDI が、以下に定義する制限モード プロファイルに厳密に準拠せずに使用される場合、wRestrictedMode フィールドは、制限がないことを示す値に設定されなければならない。

  1. 接続モードと機能 :
    1. wRestrictedMode = 0xFFFF
    2. 定義済みの bDXVA_Func 値がすべて使用可能

4.3 H261_A 制限プロファイル

H261_A 制限プロファイルには、ITU-T 勧告 H.261 を最小限にサポートするのに必要な一連の機能が含まれる。H.261 補遺 D グラフィックのアクセラレーション サポートは除外される。このプロファイルのサポートは、中期的な必要条件ではない。この機能セットは、次の一連の制限によって定義される。

  1. 接続モードと機能 :
    1. wRestrictedMode = "1"
    2. bDXVA_Func = 1
  2. bDXVA_Func = 1 (ピクチャのデコード) の制限 :
    1. フレームレベルの制限 :
      • BPP = 8
      • bSecondField = 0
      • (MacroblockWidth, MacroblockHeight) = (16, 16)
      • (WT, HT) = (8, 8)
      • bChromaFormat = '01' (4:2:0)
      • bPicStructure = '11' (フレーム構造化)
      • bMVprecisionAndChromaRelation = '10' (H.261 整数サンプル動き)
      • bPicExtrapolation = 0
      • bPicDeblocked = 0
      • bPic4MVallowed = 0
      • bPicOBMC = 0
      • bMV_RPS = 0
      • bPicScanFixed = 1
    2. マクロブロックレベルの制限 :
      • MotionType = '10' (フレーム動き) (MotionForward = 1 の場合)
      • MBscanMethod = '00' (ジグザグ) (bConfigHostInverseScan = 0 の場合)
      • FieldResidual = 0 (フレーム残余)
      • MotionBackward = 0 (逆方向予測なし)
    3. ビットストリーム バッファの制限 :
      • すべてのビットストリーム バッファの内容は、H.261 ビデオ フォーマットのデータを含んでいなければならない。

    3. 4.4 H261_B 制限プロファイル

    H261_B 制限プロファイルには、ITU-T 勧告 H.261 をサポートするのに必要な一連の機能が含まれる。H.261 補遺 D グラフィックのアクセラレーション サポートは除外されるが、ブロック解除フィルタ ポストプロセッシングのサポートは含まれる。このプロファイルのサポートは、中期的な必要条件ではない。この機能セットは、H261_A 制限プロファイルにリストしたものと同じ制限によって定義される。ただし次の項目については異なる。

    1. 接続モードと機能 :
      1. wRestrictedMode = "2"
    2. bDXVA_Func = 1 (ピクチャのデコード) の制限 :
      1. bPicDeblocked は 0 または 1
      2. bPicDeblocked が 1 の場合は、wDeblockedPictureIndex は wDecodedPictureIndex と同じであってはならない。

    4.5 H263_A 制限プロファイル

H263_A 制限プロファイルには、ITU-T 勧告 H.263、および少数の特定の拡張オプション機能をサポートするのに必要な一連の機能が含まれる。このプロファイルのサポートは、中期的な必要条件である。この機能セットは、次の一連の制限によって定義される。

  1. 接続モードと機能 :
    1. wRestrictedMode = "3"
    4. bDXVA_Func = 1
  2. bDXVA_Func = 1 (ピクチャのデコード) の制限 :
    1. フレームレベルの制限 :
      • BPP = 8
      • bSecondField = 0
      • (MacroblockWidth, MacroblockHeight) = (16, 16)
      • (WT, HT) = (8, 8)
      • bChromaFormat = '01' (4:2:0)
      • bPicStructure = '11' (フレーム構造化)
      • bRcontrol = 0
      • bMVprecisionAndChromaRelation = '01' (H.263 ハーフサンプル動き)
      • bPicExtrapolation = 0
      • bPicDeblocked = 0
      • bPic4MVallowed = 0
      • bPicOBMC = 0
      • bMV_RPS = 0
      • bPicScanFixed = 1
    2. マクロブロックレベルの制限 :
      • MotionType = '10' (フレーム動き) (MotionForward = 1 の場合)
      • MBscanMethod = '00' (ジグザグ) (bConfigHostInverseScan = 0 の場合)
      • FieldResidual = 0 (フレーム残余)
      • H261LoopFilter = 0 (H.261 ループ フィルタなし)
      • MotionBackward = 0 (逆方向動きおよび双方向動きなし)
    3. ビットストリーム バッファの制限 :
      • すべてのビットストリーム バッファの内容は、"ベースライン" モードの H.263 ビデオ フォーマット データ (オプションなし、PLUSPTYPE なし) を含んでいなければならない。または無視する場合は、補遺 L 情報付きの H.263 ビデオ フォーマット データを含んでいなければならない。

4.6 H263_B 制限プロファイル

H263_B 制限プロファイルには、ITU-T 勧告 H.263、および特定の拡張オプション機能をサポートするのに必要な一連の機能が含まれる。このプロファイルのサポートは、中期的な必要条件である。この機能セットは、H263_A 制限プロファイルにリストしたものと同じ制限によって定義される。ただし次の項目については異なる。

  1. 接続モードと機能 :
    1. wRestrictedMode = "4"
  2. bDXVA_Func = 1 (ピクチャのデコード) の制限 :
    1. フレームレベルの制限 :
      • bPicDeblocked は 0 あるいは 1 でもよい
      • bPicDeblocked = 1 の場合、wDeblockedPictureIndex は wDecodedPictureIndex と同じでも同じでなくてもよい
      • bRcontrol は 0 または 1
      • bPicExtrapolation は 0 または 1
      • Pic4MV は 0 または 1
      • Motion4MV は 0 または 1
      • bPicScanFixed は 0 または 1
    2. マクロブロックレベルの制限 :
      • bConfigHostInverseScan = 0 の場合、MBscanMethod は、'00' (ジグザグ)、'01' (交互垂直)、または '10' (交互水平) のいずれでもかまわない
    3. ビットストリーム バッファの制限 :
      • すべてのビットストリーム バッファの内容は、CPCF、CPFMT、および 補遺 D、I、N (出力ピクチャ 1 つにつき 1 つの順方向参照ピクチャ)、および T のサブセットと共に、H.263 ビデオ フォーマットのデータも含むことができる。

4.7 H263_C 制限プロファイル

H263_C 制限プロファイルには、ITU-T 勧告 H.263、および特定の拡張オプション機能をサポートするのに必要な一連の機能が含まれる。このプロファイルのサポートは、長期的な必要条件である。この機能セットは、H263_B 制限プロファイルにリストしたものと同じ制限によって定義される。ただし次の項目については異なる。

  1. 接続モードと機能 :
    1. wRestrictedMode = "5"
  2. bDXVA_Func = 1 (ピクチャのデコード) の制限 :
    1. フレームレベルの制限 :
      • bPicDeblocked は 1 でもよい
      • bPicDeblocked = 1 の場合、wDeblockedPictureIndex は wDecodedPictureIndex と同じでも同じでなくてもよい
    2. ビットストリーム バッファの制限 :
      • すべてのビットストリーム バッファの内容は、CPCF、CPFMT、および 補遺 D、I、J、N (出力ピクチャ 1 つにつき 1 つの順方向参照ピクチャ)、および T のサブセットと共に、H.263 ビデオ フォーマットのデータも含むことができる。

4.8 H263_D 制限プロファイル

H263_D 制限プロファイルには、ITU-T 勧告 H.263、および特定の拡張オプション機能をサポートするのに必要な一連の機能が含まれる。このプロファイルのサポートは、中期的な必要条件である。この機能セットは、H263_C 制限プロファイルにリストしたものと同じ制限によって定義される。ただし次の項目については異なる。

  1. 接続モードと機能 :
    1. wRestrictedMode = "6"
    2. bDXVA_Func は 1 (ピクチャのデコード) または 4 (ピクチャの再サンプリング)
  2. bDXVA_Func = 1 (ピクチャのデコード) の制限 :
    1. フレームレベルの制限 :
      • bBidirectionalAveragingMode = 1 (H.263 双方向平均化) または 0 (MPEG-2 双方向平均化)
      • bMV_RPS は 0 または 1
    2. マクロブロックレベルの制限 :
      • MotionBackward は 0 または 1
    3. ビットストリーム バッファの制限 :
      • すべてのビットストリーム バッファの内容は、補遺 K、O、P (一方向または両方向のクリッピングおよび 2 の因数によるサイズ変更)、S、および U のサブセットと共に、H.263 ビデオ フォーマットのデータも含むことができる。
  3. bDXVA_Func = 4 (ピクチャの再サンプリング) の制限 :
    1. PicResampleSourceWidth と PicResampleDestWidth は同じか、または 2 (または 1/2) の倍数で比例しなければならない。
    2. PicResampleSourceHeight と PicResampleDestHeight は同じか、または 2 (または 1/2) の倍数で比例しなければならない。
    3. PicResampleSourceHeight と PicResampleDestHeight が等しい場合は、PicResampleSourceWidth と PicResampleDestWidth は 2 (または 1/2) の倍数で比例しなければならない。PicResampleSourceHeight と PicResampleDestHeight がアップサンプリング処理を指定している場合は、PicResampleSourceWidth と PicResampleDestWidth はダウンサンプリング処理を指定してはならない。逆も同様。

注 : MotionForward が "1" で MotionBackward が "1" の場合、H.263 では bBidirectionalAveragingMode が "1" のサポートだけが必要となるが、H263_C 制限プロファイルでは、bBidirectionalAveragingMode = 0 も可能である。これは、H263_C 制限プロファイルが、H.263 ビデオに加え、MPEG-4 ビデオもサポートできるように意図して設計された。MPEG-4 は、MPEG-1/MPEG-2 フォーマットの双方向平均化を使用する。

4.9 H263_E 制限プロファイル

H263_E 制限プロファイルには、ITU-T 勧告 H.263、および特定の拡張オプション機能をサポートするのに必要な一連の機能が含まれる。このプロファイルのサポートは、中期的な必要条件ではない。この機能セットは、H263_D 制限プロファイルにリストしたものと同じ制限によって定義される。ただし次の項目については異なる。

  1. 接続モードと機能 :
    1. wRestrictedMode = "7"
  2. bDXVA_Func = 1 (ピクチャのデコード) の制限 :
    1. フレームレベルの制限 :
      • bPicOBMC は 0 または 1 のいずれか
    2. マクロブロックレベルの制限 :
      • bPicOBMC が 1 で Motion4MV が 1 の場合、MotionBackward は "0" でなければならない。
    3. ビットストリーム バッファの制限 :
      • すべてのビットストリーム バッファの内容は、補遺 F を適用した H.263 ビデオ フォーマットのデータも含むことができる。

4.10 H263_F 制限プロファイル

H263_F 制限プロファイルには、ITU-T 勧告 H.263、および特定の拡張オプション機能をサポートするのに必要な一連の機能が含まれる。このプロファイルのサポートは、中期的な必要条件ではない。この機能セットは、H263_E 制限プロファイルにリストしたものと同じ制限によって定義される。ただし次の項目については異なる。

  1. 接続モードと機能 :
    1. wRestrictedMode = "8"
  2. bDXVA_Func = 1 (ピクチャのデコード) の制限 :
    4. フレームレベルの制限 :
      • bPicBinPB may は 0 または 1
    5. ビットストリーム バッファの制限 :
      • すべてのビットストリーム バッファの内容は、補遺 G、M、V、W のサブセットと共に、H.263 ビデオ フォーマットのデータも含むことができる。

4.11 MPEG1_A 制限プロファイル

MPEG1_A 制限プロファイルには、MPEG-1 ビデオをサポートするのに必要な一連の機能が含まれる。このプロファイルのサポートは、中期的な必要条件である。この機能セットは、次の一連の制限によって定義される。

  1. 接続モードと機能 :
    1. wRestrictedMode = "9"
    2. bDXVA_Func = 1
  2. bDXVA_Func = 1 (ピクチャのデコード) の制限 :
    1. フレームレベルの制限 :
      • BPP = 8
      • bSecondField = 0
      • (MacroblockWidth, MacroblockHeight) = (16, 16)
      • (WT, HT) = (8, 8)
      • bChromaFormat = '01' (4:2:0)
      • bPicStructure = '11' (フレーム構造化)
      • bRcontrol = 0
      • bBidirectionalAveragingMode = 0 (MPEG-2 双方向平均化)
      • bMVprecisionAndChromaRelation = '00' (MPEG-2 ハーフサンプル動き)
      • bPicExtrapolation = 0
      • bPicDeblocked = 0
      • bPic4MVallowed = 0
      • bPicOBMC = 0
      • bMV_RPS = 0
      • SpecificIDCT = 0
      • bPicScanFixed = 1
    2. マクロブロックレベルの制限 :
      • MotionType = '10' (フレーム動き)
      • MBscanMethod = '00' (ジグザグ) (bConfigHostInverseScan = 0 の場合)
      • FieldResidual = 0 (フレーム残余)
      • H261LoopFilter = 0 (H.261 ループ フィルタなし)
    3. ビットストリーム バッファの制限 :
      • すべてのビットストリーム バッファの内容は、MPEG-1 メイン プロファイル ビデオ フォーマットのデータを含んでいなければならない。

4.12 MPEG2_A 制限プロファイル

MPEG2_A 制限プロファイルには、MPEG-2 ビデオ メイン プロファイルをサポートするのに必要な一連の機能が含まれる。このプロファイルのサポートは、中期的な必要条件である。この機能セットは、次の一連の制限によって定義される。

  1. 接続モードと機能 :
    1. wRestrictedMode = 0xA
    2. bDXVA_Func = 1
  2. bDXVA_Func = 1 (ピクチャのデコード) の制限 :
    1. フレームレベルの制限 :
      • wRestrictedMode = 0xA
      • BPP = 8
      • (MacroblockWidth, MacroblockHeight) = (16, 16)
      • (WT, HT) = (8, 8)
      • bChromaFormat = '01' (4:2:0)
      • bRcontrol = 0
      • bBidirectionalAveragingMode = 0 (MPEG-2 双方向平均化)
      • bMVprecisionAndChromaRelation = '00' (MPEG-2 ハーフサンプル動き)
      • bPicExtrapolation = 0
      • bPicDeblocked = 0
      • bPic4MVallowed = 0
      • bPicOBMC = 0
      • bMV_RPS = 0
      • SpecificIDCT = 0
      • bPicScanFixed = 1
    2. マクロブロックレベルの制限
      • bConfigHostInverseScan = 0 の場合、MBscanMethod は '00' (ジグザグ) または '01' (交互垂直) のどちらでもかまわない
      • H261LoopFilter = 0
    3. ビットストリーム バッファの制限 :
      • すべてのビットストリーム バッファの内容は、MPEG-2 メイン プロファイル ビデオ フォーマットのデータを含んでいなければならない。
      • bNewQmatrix[i] = 0 (i = 2 および 3)

4.13 MPEG2_B 制限プロファイル

MPEG2_B 制限プロファイルには、MPEG-2 ビデオ メイン プロファイルおよび関連するフロントエンド バッファ トゥー バッファ サブピクチャ ブレンディングを使った DVD サブピクチャをサポートするのに必要な一連の機能が含まれる。このプロファイルのサポートは、中期的な必要条件ではない。この機能セットは、MPEG2_A 制限プロファイルにリストしたものと同じ制限によって定義される。ただし次の項目については異なる。

  3. 接続モードと機能 :
    1. wRestrictedMode = 0xB
    2. bDXVA_Func = 1 (ピクチャのデコード)、2 (アルファ ブレンド データのロード)、または 3 (アルファ ブレンド コンビネーション) (これらのすべての値がサポートされなければならない)

4.14 MPEG2_C 制限プロファイル

The MPEG2_C 制限プロファイルには MPEG-2 ビデオ メイン プロファイルをサポートするために必要な一連のフィーチャーが含まれる。このプロファイルのサポートは中期的要件である。このフィーチャー セットは上記の MPEG2_A 制限プロファイルにリストしたものと同じ制限によって定義される、ただし次の項目については異なる :

  1. 接続モードと機能 :
    1. wRestrictedMode = 0xC
    2. 3.5.2 章で説明されている最小相互運用性について、bConfigResidDiffHost=0 と bConfigResidDiffAccelerator=1 を持つメンバが 1 つ追加される。

MPEG2_C 制限プロファイルは MPEG2_A プロファイルのアクセラレータ プロファイルを緩和することによって定義され (これによってアクセラレータは MPEG2_A の最小相互運用性セットのメンバをサポートせずに済む) 、MPEG2_A をサポートするすべてのアクセラレータは MPEG2_C プロファイルをサポートしなければならない。同様に、MPEG2_D プロファイルをサポートするすべてのアクセラレータは MPEG2_C プロファイルをサポートしなければならない。

4.15 MPEG2_D 制限プロファイル

MPEG2_D 制限プロファイルには MPEG-2 ビデオ メイン プロファイルのサポートに必要なフィーチャー セットと、バックエンド ハードウェア サブピクチャ ブレンディングを使った DVD サブピクチャを組み合わせるために必要なフィーチャー セットが含まれる。このフィーチャー セットは上記の MPEG2_B 制限プロファイルにリストしたものと同じ制限によって定義される、ただし次の項目については異なる :

  1. 接続モードと機能 :
    1. wRestrictedMode = 0xD
    2. 3.5.2 章で説明されている最小相互運用性について、bConfigResidDiffHost=0 と bConfigResidDiffAccelerator=1 を持つメンバが 1 つ追加される。
    3. bConfigBlendType は 0 か 1 のいずれか (アクセラレータが決定)
    4. bConfigDataType は任意の値 (アクセラレータが決定)

MPEG2_D 制限プロファイルは MPEG2_B プロファイルのアクセラレータ プロファイル を緩和することによって定義され (これによってアクセラレータは MPEG2_B の最小相互運用性セットのメンバをサポートせずに済む)、MPEG2_B をサポートするすべてのアクセラレータは MPEG2_D プロファイルをサポートしなければならない。

5 IAMVideoAccelerator 処理

IAMVideoAccelerator は、Windows 2000 内に DirectX VA 処理メカニズムを備えるためのインターフェイスである。このセクションでは、DirectX VA データ フォーマットがこのインターフェイスを介してどのように送信されなければならないかを説明する。

5.1 IAMVideoAccelerator インターフェイス

以下は、現在の Microsoft DirectShow® ドキュメント セットにある IAMVideoAccelerator の使用に関する概要説明を拡張、また向上させることを意図している。

注 : このインターフェイスは、Microsoft Windows® 2000 で利用可能である。

オーバーレイ ミキサーの入力ピンは IAMVideoAccelerator インターフェイスをサポートしており、デコーダの出力ピンは IAMVideoAcceleratorNotify インターフェイスをサポートしている。フィルタ ピン接続のイベントは次の順序で発生する。

  1. フィルタ グラフ マネージャがデコーダの出力ピンの IPin::Connect を呼び出す。AM_MEDIA_TYPE はオプション パラメータである。
    • AM_MEDIA_TYPE は、メディア タイプを記述するデータ構造体である。この構造体には、メジャータイプ GUID (この場合は MEDIATYPE_Video)、サブタイプ GUID (この場合はビデオ アクセラレータ GUID)、およびその他さまざまなものが含まれる。その 1 つは、この場合なら非圧縮ビデオ ピクチャの幅と高さを含む、メディアについての情報を格納したフォーマット タイプ GUID である (多くの場合 MPEG1VIDEOINFO、VIDEOINFOHEADER、MPEG2VIDEOINFO、または VIDEOINFOHEADER2 構造体)。
    • AM_MEDIA_TYPE が存在する場合は、デコーダに、指定されたメディア タイプを使って動作するよう指示する。この指定は、"完全指定" の場合と "部分指定" の場合がある。"完全指定" の場合、デコーダは通常、そのメディア タイプを使って動作しようとする。"部分指定" の場合、"部分指定" メディア タイプと矛盾しない方法での接続に使用できる "完全指定" 互換動作モードを見つけようとする。
    • 接続に使用する "完全指定" メディア タイプを探す際は、通常、"部分指定" メディア タイプと互換性のある、出力ピンがサポートしているすべての "完全指定" メディア タイプを調べて、接続が成功するまで 1 つずつ試すという方法を使う。IPin::Connect 呼び出しに AM_MEDIA_TYPE が含まれておらず、しかしすべてのメディア タイプをチェックする必要のある出力ピンがある場合、同様の処理が行われる。
  2. デコーダ側で、特定の AM_MEDIA_TYPE (ビデオ アクセラレータ GUID を含む) がダウンストリーム入力ピンによってサポートされているかどうか調べる必要がある場合、そのピンの IPin::QueryAccept (AM_MEDIA_TYPE のサブタイプとしてビデオ アクセラレータ GUID を指定) を呼び出すか、または後述の項目 5 に解説するように、そのピンに接続を試みることによって調べることができる。
  3. デコーダ側で、ダウンストリーム入力ピンがどのビデオ アクセラレータ GUID をサポートしているかを認識しておらず、またダウンストリーム入力ピンの IPin::QueryAccept を呼び出すことによって特定のいくつかのビデオ アクセラレータ GUID だけを指名することを避けたい場合、デコーダは、IAMVideoAccelerator::GetVideoAcceleratorGUIDs を呼び出して、そのピンがサポートしているビデオ アクセラレータ GUID の一覧を取得することができる。
  4. いくつかの特定のビデオ アクセラレータ GUID については、デコーダはダウンストリーム入力ピンの IAMVideoAccelerator::GetUncompFormatsSupported を呼び出して、特定のビデオ アクセラレータ GUID の生成に使用できる DDPIXELFORMAT の一覧を取得することができる。返される一覧は、推奨の度合いが高いものから順にリストされている (最も推奨されるフォーマットが最初に記載される) ものと見なした方がよい。
  5. デコーダはダウンストリーム入力ピンの IPin::ReceiveConnection を呼び出す。その際、メディア タイプのサブタイプとして、適切なビデオ アクセラレータ GUID を指定した AM_MEDIA_TYPE を渡す。これにより、非圧縮出力サーフェスの作成を含め、動作に必要な接続が設定される。このサーフェスは、AM_MEDIA_TYPE にある幅と高さや、後述する呼び出しによって見つけられた、割り当てるサーフェスの数や、その他ビデオアクセラレータが保持していてサーフェス作成目的で使用したい情報 (ビデオ アクセラレータ GUID 自体など) を使って割り当てられる。ダウンストリーム入力ピンが、ビデオ アクセラレータ GUID、またはその他の接続に関する何らかの要素を拒否した場合、IPin::ReceiveConnection が失敗することがある。IPin::ReceiveConnection が失敗した場合は、返される HRESULT でそのことが示される。デコーダは、AM_MEDIA_TYPE にある別のビデオ アクセラレータ GUID を使うなどして、呼び出しを再試行することができる。
    • 注 : IPin::ReceiveConnection を呼び出して接続を試行し、接続が成功したかどうかチェックするというのは、ダウンストリーム入力ピンがサポートしているメディア タイプをデコーダ側で調べるもう 1 つの方法であり、最も確実な方法でもある。
  6. IPin::ReceiveConnection の実行中、オーバーレイ ミキサーは、割り当てる非圧縮サーフェスの数を計算するため、デコーダの IAMVideoAcceleratorNotify::GetUncompSurfacesInfo を呼び出し、ビデオ アクセラレータ GUID と AMVAUncompBufferInfo 構造体を渡す。デコーダは、AMVAUncompBufferInfo 構造体を返す。
    • AMVAUncompBufferInfo データ構造体には、特定のタイプに割り当てられるサーフェス数の最大値と最小値、および割り当てられるサーフェスのピクセル フォーマットを記述した DDPIXELFORMAT 構造体が含まれる。
    • マイナーな注 : 実際に IAMVideoAcceleratorNotify::GetUncompSurfacesInfo の呼び出しでデコーダに渡されるのは、ビデオ アクセラレータ GUID のみである。
  7. オーバーレイ ミキサーはデコーダの IAMVideoAcceleratorNotify::SetUncompSurfacesInfo を呼び出す。その際デコーダに、実際に割り当てられた非圧縮サーフェスの数を渡す。
  8. オーバーレイ ミキサーは、ビデオ アクセラレータの初期化に必要なデータを取得するため、デコーダの IAMVideoAcceleratorNotify::GetCreateVideoAcceleratorData を呼び出す。
  9. デコーダは、一連の AMVACompBufferInfo データ構造体 (ビデオ アクセラレータ GUID に使用される圧縮データ バッファの各タイプごとに 1 つが対応する) を取得するため、IAMVideoAccelerator::GetCompBufferInfo を呼び出す。その際、ビデオ アクセラレータ GUID、AMVAUncompDataInfo 構造体、および圧縮バッファ タイプの数を渡す。
    • AMVAUncompDataInfo 構造体には、デコードされた非圧縮データの幅と高さをピクセルで表した値と、非圧縮ピクチャの DDPIXELFORMAT が含まれる。
    • 返される AMVACompBufferInfo データ構造体にはそれぞれ次の項目が含まれる。
      • 特定のタイプに必要な圧縮バッファの数。
      • 作成するサーフェスの幅と高さ (実際の意味を持つ、または持たないフィールド)。

        注 : DirectDraw の圧縮バッファのサーフェス割り当て処理は、現在のところこれらのサーフェスの幅または高さが 215 以上になることを想定していない、ただしサーフェス アロケータはこの制限を犯しても明らかな失敗とはならない。このためドライバは、そのような極端なサイズを避けるように、圧縮バッファ メモリへの要求を構成したほうがよい。たとえば、幅 が "1" で高さが "65536" のバッファより、幅が "1024" で高さが "64" のバッファを要求したほうがよい。
      • サーフェスによって使用されるバイトの合計数。
      • DirectDrawSurface オブジェクトを定義し、圧縮データを格納するサーフェスの作成機能を記述した DDSCAPS2 タイプの構造体。
      • 圧縮データを格納するサーフェスの作成に使用するピクセル フォーマットを記述した DDPIXELFORMAT (実際の意味を持つ、または持たないフィールド)。
  10. 注 : いくつかのデコーダの IAMVideoAcceleratorNotify インターフェイス メソッドへのオーバーレイ ミキサーの呼び出しは、オーバーレイ ミキサーの IPin::ReceiveConnection へのデコーダの呼び出し内で発生することが可能であり、通常そのように発生する。これは特に次の場合に当てはまる。
    • IAMVideoAcceleratorNotify::GetUncompSurfacesInfo
    • IAMVideoAcceleratorNotify::SetUncompSurfacesInfo
    • IAMVideoAcceleratorNotify::GetCreateVideoAcceleratorData
  11. 注 : 動的フォーマット変更をサポートするため、フィルタが接続され実行されている間、上記のメソッドによって IPin::ReceiveConnection およびその他のメソッドを呼び出すことができる。この機能は動的フォーマット変更をサポートするために用意されているが、ただしすべてのデータ セットが最初からもう一度開始されてすべての参照ピクチャ情報が失われる H.263 の動的フォーマット変更は対象とならない。

初期化後の処理中の IAMVideoAccelerator の使用について次に解説する。

  1. デコーダは、出力ピクチャの作成処理を開始するため、各非圧縮データ バッファに対して IAMVideoAccelerator::BeginFrame を呼び出す。その際、 AMVABeginFrameInfo 構造体を送信する。
    • AMVABeginFrameInfo 構造体には、宛先バッファのインデックス、ダウンストリームに送信するデータへのポインタ、およびデコーダが読み取るためにアクセラレータがデータを配置できる場所を示すポインタが含まれる。
    • 注 1 : アクセラレータは実際には宛先バッファのインデックスを受け取らず、インデックスはダウンストリームへ行く前にオーバーレイ ミキサーによって変換される。
    • 注 2 : IAMVideoAccelerator::BeginFrame は、IAMVideoAccelerator::EndFrame への呼び出しの間に何度でも呼び出すことができる。
    • 注 3 : インターフェイス処理の中では、ビットストリーム内の個々のピクチャを処理するために、IAMVideoAccelerator::BeginFrame および IAMVideoAccelerator::EndFrame を呼び出す必要があるという前提はない。インターフェイスに関して IAMVideoAccelerator::BeginFrame が実行することは次の 2 つである。
      • オーバーレイ ミキサー内で、インデックスと非圧縮サーフェスとの間に関連付けを作成する。
      • デバイス ドライバ内で特定の関数を呼び出す手段を提供する (任意のデータをデコーダとデバイス ドライバの間でやり取りする手段のサポートを含む)。

    2. (しかしながら、DirectX VA 操作にはビットストリームの各ピクチャの処理には IAMVideoAccelerator::BeginFrame と IAMVideoAccelerator::EndFrame 呼び出しが必要だという要件がある、これについては後に説明する。)

  2. 非圧縮データをアクセラレータに送信するため、デコーダは次のメソッドを呼び出す。
    • IAMVideoAccelerator::GetBuffer。指定されたバッファへのアクセスをロックおよび取得するため (アクセスを取得するためにこのメソッドを前に呼び出していない場合)。このメソッドの使い方として、IAMVideoAccelerator::BeginFrame の呼び出し対象となった最後の非圧縮出力ピクチャの内容のコピーを取得するのに使える特別な方法がある。ただしその宛先バッファ インデックスに対して IAMVideoAccelerator::EndFrame が呼び出されていないことが条件となる。IAMVideoAccelerator::GetBuffer を呼び出すために、デコーダは AMVACompBufferInfo データ構造からいくつかの情報が必要となる。これは、IAMVideoAccelerator::GetCompBufferInfo または IAMVideoAccelerator::GetInternalCompBufferInfo を呼び出すことで取得できる (どちらも同じ情報を取得するようである)。警告 : デコーダが IAMVideoAccelerator::GetInternalCompBufferInfo を呼び出した結果、デバイス ドライバの DdMoCompGetInternalInfo が呼び出されることはない。
    • IAMVideoAccelerator::Execute。AMVABUFFERINFO データ構造体の配列で指示された一連の圧縮バッファに含まれるデータを処理したほうがよいことを示す。この呼び出しでは、関数コード dwFunction がドライバに渡される。また、ダウンストリームに送信するデータへの lpPrivateInputData ポインタ、およびデコーダが読み取るためにダウンストリーム処理がデータを配置できる場所を指す lpPrivateOutputData ポインタも渡される。
    • IAMVideoAccelerator::ReleaseBuffer。デコーダが、指定されたバッファの使用を完了したため、当面はバッファへのロックされたアクセスが必要なくなったことを示す。(デコーダが引き続きバッファを使用したい場合は、バッファをそれ以上使用しないとはっきりするまで IAMVideoAccelerator::ReleaseBuffer を呼び出さないでおけば、IAMVideoAccelerator::GetBuffer を呼び出す必要性を回避できる。)
    • IAMVideoAccelerator::QueryRenderStatus。バッファが読み取りや書き込みの対象として安全かどうかを調べるため。
  3. デコーダは、宛先バッファの出力処理を完了するため、IAMVideoAccelerator::EndFrame を呼び出す。この呼び出しの際に任意のデータ ダウンストリームを渡すことができる (この呼び出しの結果実行されるのは、基本的にはこれだけである)。この呼び出しでは宛先バッファのインデックスは送信しないため、ここで渡す任意のデータ内で示さない限り、どの宛先バッファが完了したかをアクセラレータに正確に伝えることはできない。
  4. デコーダは、フレームを表示するため、表示するフレームのインデックスと、開始および終了のタイム スタンプを含む IMediaSample 構造体と共に、IAMVideoAccelerator::DisplayFrame を呼び出す。
  5. 最後に、デコーダは、すべての処理が完了したときに、IAMVideoAccelerator::EndFrame を呼び出すことによって、開始された残りの出力フレームがすべて完了したことを示し、未解放の各バッファに対して IAMVideoAccelerator::ReleaseBuffer を呼び出すことによって、ロックされたバッファをすべて解放した方がよい。

5.2 IAMVideoAccelerator への DirectX VA のマッピング

5.2.1 制限モード プロファイルと構成の設定

DirectX VA でデコード可能なデータ タイプは多岐にわたるため、またこれらのデータ タイプそれぞれに対して DirectX VA では複数のデコード構成 (ビットストリーム バッファ、ホスト残差デコード、当該バッファ タイプごとに暗号ありまたは暗号なしのアクセラレータベースの IDCT など) がサポートされているため、個々のデータ タイプとデコード構成にそれぞれ一意の GUID を指定することはあまり良い方法とはいえない。個々に指定すると GUID の数が多くなりすぎ (DirectX VA のプロファイルが 16 個あり、それぞれに 16 個の構成があると仮定すると、256 個の GUID を定義する必要がある)、それらを保持するためだけに 4 KB のメモリをすべて使い果たしてしまう。DirectX VA を IAMVideoAccelerator にマップする方法を決定する際、この点は、非常に難しい問題である。これに対し、ほかの処理定義はきわめて単純と言える。結果として、我々は各データ タイプ (つまり各制限モード プロファイル) のみに対して一意の GUID を指定し、追加の GUID 1 つを、各暗号タイプに関連付けられるようにする。その後デコード構成は、デコーダとアクセラレータの間で、DirectX VA 機能の個々のタイプについて構成を確立するための、プローブおよびロック処理を使った下位従属ネゴシエーションによって確立される。

5.2.2 DirectX VA IAMVideoAccelerator 処理仕様

厳密な処理メカニズムは次のとおり。

  1. ここで定義されている各制限モード プロファイルにはそれぞれ、ダウンストリーム入力ピンの IPin::QueryAccept、IPin::ReceiveConnection、および IAMVideoAccelerator::GetVideoAcceleratorGUIDs にリストされているメソッドによってサポート可能な DirectX VA GUID が 1 つ関連付けられている。
  2. 2) 同様に、DirectX VA で使用する各暗号プロトコル タイプにはそれぞれ、ダウンストリーム入力ピンの IPin::QueryAccept、IPin::ReceiveConnection、および IAMVideoAccelerator::GetVideoAcceleratorGUIDs にリストされているメソッドによってサポート可能な暗号プロトコル タイプ GUID が 1 つ関連付けられていなければならない。"暗号なし" GUID である DXVA_NoEncrypt のサポートは暗黙の必須条件であるため、このリストに送信されてはならない。
  3. 入力ピンへのダウンストリームに接続するための IPin::ReceiveConnection を呼び出した後で、デコーダの IAMVideoAcceleratorNotify::GetCreateVideoAcceleratorData はその接続の接続モード情報が入る DXVA_ConnectMode データ構造体へのポインタを返さなければならない。IAMVideoAccelerator::GetCompBufferInfo は *pdwNumTypesCompBuffers = 16 で呼び出されなければならず、圧縮されたバッファ情報を返さなければならない、この情報は 3.4 章で定義されているように各バッファのタイプ数が、返った AMVACompBufferInfo データ構造体の配列内でゼロから始まるインデックスで直接使用可能になっている。これは、使用されないバッファ タイプ (バッファ タイプ 0 を含む、なぜならそのバッファタイプには使用が定義いされないからである) については、アクセラレータ ドライバが AMVACompBufferInfo データ構造体をダミー パラメータ (ex. dwNumCompBuffers=0, dwWidthToCreate=0, dwHeightToCreate=0, and dwBytesToAllocate=0) 値の形で提供することを要求する。
  4. DXVA 機能の指示、および関連付けられたデータ バッファは、IAMVideoAccelerator::Execute を使って送信される。DXVA 機能は呼び出しの dwFunction パラメータで指示される。初期化にとって意味を持つ DXVA 機能は、DXVA_ConfigQueryOrReplyFunc および DXVA_EncryptProtocolFunc だけである。
    • dwFunction に DXVA_ConfigQueryOrReplyFunc が含まれる場合、この呼び出しでアクセラレータにデータを渡すための lpPrivateInputData ポインタは、構成データ構造体を指し、アクセラレータから情報を受け取るための lpPrivateOutputData ポインタは、代替または複製の構成データ構造体を格納できる領域を指していなければならない、AMVABUFFERINFO の配列の pamvaBufferInfo ポインタは NULL、dwNumBuffers はゼロでなければならない。返される HRESULT は、S_OK または S_FALSE となるか、またはプロトコル実行における深刻な問題があれば (無効な構成パラメータなど) E_FAIL かE_INVALIDARG あるいはその他のエラーを示す HRESULT となる。DXVA_ConfigQueryOrReplyFunc のすべての使用に対応する IAMVideoAccelerator::Execute の呼び出しは、ほかのすべての IAMVideoAccelerator::Execute 呼び出しより先に実行されなければならない。
    • dwFunction に DXVA_EncryptProtocolFunc が含まれる場合、この呼び出しでアクセラレータにデータを渡すためのポインタは、DXVA_EncryptProtocolHeader で始まる暗号化プロトコル データ構造体を指し、アクセラレータから情報を受け取るためのポインタは、暗号化プロトコルから返される、DXVA_EncryptProtocolHeader で始まるデータ (証明書など) を格納できる領域を、指していなければならない。返される HRESULT は、暗号化プロトコルが正常に動作していれば S_OK となり、プロトコル実行における深刻な問題があれば E_FAIL か E_INVALIDARG またはその他のエラーを示す HRESULT となる。
    上記のような処理の初期化が終わった後、実際のデコーダの処理は次のように進行する。
  5. IAMVideoAccelerator::BeginFrame は圧縮されたバッファ パラメータで bDXVA_Func を送る前に呼び出されなければならない、bDXVA_Func は非圧縮デスティネーション サーフェスへの書き込みを発生させる。DirectX VA における IAMVideoAccelerator::BeginFrame の目的は、デスティネーション サーフェスをインデックス値と結びつけ、目的のビデオ アクセラレータ ドライバにサーフェス書き込みの初期化を通知することである、これによってドライバはサーフェスがオーバーライドされる準備ができているかどうかを示して対応することができる。IAMVideoAccelerator::BeginFrame 内に渡される AMVABeginFrameInfo 構造体には IAMVideoAccelerator::BeginFrame (かつ dwSizeInputData は 2 でなければならない) 内に渡されるフレーム インデックスと適合する 1 WORD wBeginPictureIndex パラメータの pInputData ポインタが入る。これは圧縮バッファ内でサーフェスにコマンドを書き込むために用いられるインデックスである (ie. wDecodedPictureIndex、wDeblockedPictureIndex、wBlendedDestinationIndex、wPicResampleDestPicIndex として用いられる)。AMVABeginFrameInfo の pOutputData ポインタは NULL でなければならない (かつ dwSizeOutputData は "0" でなければならない)。IAMVideoAccelerator::BeginFrame が返す HRESULT は次のとおり :
    • S_OK : 非圧縮サーフェスが有効で使用準備完了。
    • E_PENDING : 非圧縮サーフェスはまだ有効ではないが、すぐに有効になる (ie. 非圧縮サーフェスは表示用に読み込まれており、サーフェスの読み込み、表示はまだ完了していない)。
    • E_FAIL あるいは E_INVALIDARG : データ フォーマットかプロところエラーが発生した場合にのみ示されるエラー (dwSizeInputData あるいは NULL 以外の pOutputData のような間違った値)。
  6. DXVA 機能の指示、および関連付けられたデータ バッファは、IAMVideoAccelerator::Execute を使って送信される。1 より大きい bDXVA_Func 値は IAMVideoAccelerator::Execute への同じ呼び出しで示される場合がある。bDXVA_Func 値は呼び出しの dwFunction パラメータ内にパックされなければならない。bDXVA_Func の 0xFF 値は、bDXVA_Func は 2 あるいは 4 バイト拡張されることを示す。2 番目のバイトも 0xFF なら、これは bDXVA_Func が 4 バイトに拡張されていることを示す。第 3 バイトの上位 4 ビットが 0xF または 0x0 の場合は、bDXVA_Func に DXVA_ConfigQueryOrReplyFunc または DXVA_EncryptProtocolFunc が含まれていることを示す。マルチバイト コマンドは、dwFunction 終了後の継続を指示してはならない。次のことにデコーダは注意を払わなければならない、IAMVideoAccelerator::Execute への同じ呼び出しに指定される異なった bDXVA_Func 値間にシーケンシャルな依存性がない事、そして連続的な IAMVideoAccelerator::Execute 呼び出しの前に IAMVideoAccelerator::BeginFrame と IAMVideoAccelerator::QueryRenderStatus の適切な呼び出しによってすべての潜在的な緊急条件 (ピクチャ デコーディング と サブピクチャ ブレンディングの間、サブピクチャ ローディングとサブピクチャ ブレンディングの間など) が避けられること。
    • dwFunction に DXVA_ConfigQueryOrReplyFunc があるなら、この呼び出しでアクセラレータにデータを渡すための lpPrivateInputData ポインタは構成データ構造体を指さなければならない、アクセラレータから情報を受け取るための lpPrivateOutputData ポインタは別のあるいはコピーされた構成データ構造体を置くことの出来る範囲を指さなければならない、AMVABUFFERINFO の配列用の pamvaBufferInfo ポインタは NULL でなければならない、dwNumBuffers はゼロでなければならない。返った HRESULT には クエリの結果を示す S_OK か S_FALSE 、あるいは E_FALSE か E_INVALIDARG あるいは (不適切な構成パラメータのような) プロトコル実行の深刻な問題のイベントに HRESULT エラー識別子 が入る。DXVA_ConfigQueryOrReplyFunc のすべての使用に対応する IAMVideoAccelerator::Execute の呼び出しは、ほかのすべての IAMVideoAccelerator::Execute 呼び出しより先に実行されなければならない。
    • dwFunction に DXVA_EncryptProtocolFunc が含まれる場合、この呼び出しでアクセラレータにデータを渡すための lpPrivateInputData ポインタは、DXVA_EncryptProtocolHeader で始まる暗号化プロトコル データ構造体を指し、アクセラレータから情報を受け取るための lpPrivateOutputData ポインタは、(DXVA_EncryptProtocolHeader で始まる) 暗号化プロトコルから返される、DXVA_EncryptProtocolHeader で始まるデータ (証明書など) を格納できる領域を指していなければならない、AMVABUFFERINFO の配列用の pamvaBufferInfo ポインタは NULL でなければならない、dwNumBuffers はゼロでなければならない。返った HRESULT には 暗号化プロトコルが通常に機能している限り S_OK が入り、 E_FALSE か E_INVALIDARG あるいは プロトコル実行の深刻な問題のイベントに HRESULT エラー識別子 が入る。
    • dwFunction に DXVA_ConfigQueryOrReplyFunc または DXVA_EncryptProtocolFunc が含まれない場合、アクセラレータにデータを渡すための pPrivateInputData ポインタは、バッファ記述リストを指していなければならない。各バッファのバッファ記述リスト構造体の最初の 4 エントリ (dwTypeIndex、dwBufferIndex、dwDataOffset、および dwDataSize) は、同バッファの AMVABUFFERINFO データ構造体のものと同じでなければならない。dwFunction 内に bDXVA_Func が "1" と等しく、bPicReadbackRequests が "1" の場合、アクセラレータから情報を受け取るための lpPrivateOutputData ポインタは、アクセラレータからの読み戻しデータが格納される永続的メモリ (ヒープ) 領域を指していなければならない、この領域は読み返しマクロブロック データでアクセラレータから書き込まれる (こういったデータは下の項目 10 で説明されているように、同じピクチャ パラメータ バッファを書き込む IAMVideoAccelerator::QueryRenderStatus が S_OK を示すまでは存在が保証されない)。 それ以外の場合、アクセラレータから情報を受け取るためのポインタは、以下のいずれかの値が設定される単一の DWORD を指していなければならない (特にオフホストの VLD 処理でビットストリーム エラーを報告するときに有用)。
      • "0" : 実行 OK。
      • "1" : データ フォーマットに関する軽度の問題が発見された。
      • "2" : データ フォーマットに関する重大な問題が発見された。
      • "3" : データ フォーマットに関する深刻な問題が発見された。
      • "4" : その他の深刻な問題が発見された。

      いずれかのタイプの "深刻" な問題が示される場合、対策をとれない限り、ソフトウェア デコーダは機能の実行を止めたほうがよい。アクセラレータから返されるこのデータは、ピクチャのバッファ レンダリングが完了する前に、ホストから読み取ってはならない。バッファ レンダリングの完了は、IAMVideoAccelerator::QueryRenderStatus でテストできる。返される HRESULT は、インターフェイス処理が正常に動作していれば S_OK となり、プロトコル実行における深刻な問題があれば E_FAIL か E_INVALIDARG またはその他のエラーを示す HRESULT となる可能性がある。

  7. ピクチャ デコーディング パラメータ バッファは IAMVideoAccelerator::Execute の bDXVA_Func を "1" として使用したとき、各ピクチャのデコーディングに送られる最初のバッファになければならない、そしてビット ストリーム内のピクチャをデコードするすべてのバッファは次のピクチャをデコードするバッファの前に送られなければならない。マクロブロック制御コマンド バッファが送られると、対応する残差データ バッファが同じ IAMVideoAccelerator::Execute 呼び出しで (同じマクロブロックにデータを持って) 送られなければならない。
  8. IAMVideoAccelerator::EndFrame はすべての圧縮バッファが送られた後で呼び出されなければならない、それは指定した非圧縮サーフェス内の出力内容を作成する (ie. wDecodedPictureIndex、wDeblockedPictureIndex、wBlendedDestinationIndex、あるいは wPicResampleDestPicIndex に指定された操作の結果)。この IAMVideoAccelerator::EndFrame 呼び出しの目的は、ビデオ アクセラレータ ハードウェアに指定した操作に必要なすべてのデータは送られた事を知らせることである。IAMVideoAccelerator::EndFrame 経由でダウンストリームを送るデータへのポインタは終了しているフレームのインデックスを持つ 1 WORD wEndPictureIndex へのポインタでなければならない。このパラメータは 関連する圧縮バッファに送る前の IAMVideoAccelerator::BeginFrame 呼び出しに指定される wBeginPictureIndex 値と一致しなければならない。IAMVideoAccelerator::EndFrame 呼び出しに続いて、IAMVideoAccelerator::BeginFrame の別の呼び出しによってこれが発生させられ結果として S_OK が返るまでは、インデックス wEndPictureIndex の非圧縮サーフェスはピクチャの wDecodedPictureIndex、wDeblockedPictureIndex、wBlendedDestinationIndex、あるいは wPicResampleDestPicIndex 内にあってはならない。しかし、デスティネーション サーフェス インデックスは wForwardRefPictureIndex、wBackwardRefPictureIndex、wPicResampleSourcePicIndex、あるいは bRefPicSelect[i] のような続いて起きる読み込みアクセスコマンド内にもあるかもしれない。ある種のデータフォーマット エラーかプロトコル エラーがない限り、IAMVideoAccelerator::EndFrame によって返る HRESULT は S_OK でなければならない、上記のエラーの場合 E_FAIL か E_INVALIDARG あるいは他のエラー識別子となる。
  9. フィールド ベースの デコードの場合 (ex. MPEG-2 ビットストリーム)、ビットストリーム内機能ピクチャのアクセラレータ インターフェイスの非圧縮サーフェスへの 1 対 1 マッピングはない。MPEG-2 ビットストリームでフィールド ピクチャをデコードするとき、非圧縮サーフェスに 1 つの完全な出力をデコードして生成するための 2 つの"ピクチャ"がある。DirectX VA インターフェイス定義では、各フレームは wDecodedPictureIndex、wDeblockedPictureIndex、wBlendedDestinationIndex、あるいは wPicResampleDestPicIndex の各使用に対応する。それゆえ、出力非圧縮サーフェスにフィールドピクチャをデコードするには IAMVideoAccelerator::BeginFrame と IAMVideoAccelerator::EndFrame への 2 つの呼び出しペアが必要である。
  10. dwFlags をゼロで IAMVideoAccelerator::QueryRenderStatus を呼び出すと、非圧縮サーフェスへのすべての書き込み操作が完了すれば S_OK を返し、その操作がまだ完了していなければ E_PENDING が返る。この呼び出しは個別の wEndPictureIndex で IAMVideoAccelerator::EndFrame を呼び出した後に起こる場合があり、wDecodedPictureIndex、wDeblockedPictureIndex、wBlendedDestinationIndex、あるいは wPicResampleDestPicIndex 内に wEndPictureIndex が設定されて送られたバッファの状態をチェックする。プロトコル エラーのイベントでは、E_FAIL か E_INVALIDARG あるいはエラー識別子が返る。

5.2.3 動き補償デバイス ドライバとの処理上の通信

ここでは、DirectX VA インターフェイスの動き補償デバイス ドライバの側面について解説する (「Windows 2000 DDK - Graphics Drivers - Design Guide - 3.0 DirectDraw DDI - 3.12 Motion Compensation」を参照)。次に、DD_MOTIONCOMPCALLBACKS 構造体を使ってアクセスされるエントリに関連する項目を列挙する。

  1. 当該処理の開始時に、ソフトウェア デコーダがビデオ アクセラレーション オブジェクトの使用を開始することをドライバに通知するため、デバイス ドライバの DdMoCompCreate が使用される。
  2. IAMVideoAccelerator::GetVideoAcceleratorGUIDs から受信される GUID は、デバイス ドライバの DdMoCompGetGUIDs から生じる。
  3. ダウンストリーム入力ピンの IAMVideoAccelerator::GetUncompFormatsSupported への呼び出しは、デバイス ドライバの DdMoCompGetFormats からのデータを返す。
  4. デコーダの IAMVideoAcceleratorNotify::GetCreateVideoAcceleratorData からの DXVA_ConnectMode データ構造体は、デバイス ドライバの DdMoCompCreate に渡される。
  5. IAMVideoAccelerator::GetCompBufferInfo から返されるデータは、デバイス ドライバの DdMoCompGetBuffInfo から生じる。
  6. IAMVideoAccelerator::Execute を使って送信されたバッファは、デバイス ドライバの DdMoCompRender によって受信される。
  7. IAMVideoAccelerator::QueryRenderStatus を使用すると、デバイス ドライバの DdMoCompQueryStatus が呼び出される。DdMoCompQueryStatus からの DDERR_WASSTILLDRAWING の戻り値をホスト デコーダは IAMVideoAccelerator::QueryRenderStatus からの E_PENDING の戻り値として見る。
  8. IAMVideoAccelerator::BeginFrame に送信されたデータは、デバイス ドライバの DdMoCompBeginFrame によって受信される。DdMoCompBeginFrame からの E_PENDING の戻り値をホスト デコーダは IAMVideoAccelerator::BeginFrame からの E_PENDING の戻り値として見る。
  9. IAMVideoAccelerator::EndFrame に送信されたデータは、デバイス ドライバの DdMoCompEndFrame によって受信される。
  10. 当該処理の最後に、現在のビデオ アクセラレーション オブジェクトがそれ以降使用されないため、ドライバが必要なクリーンアップを実行できることをドライバに通知するため、デバイス ドライバの DdMocompDestroy が使用される。


DirectShow による DVD デコーダの開発

ここには、DirectShow のすべてのプロパティ セットおよびインターフェイスに関する参照ページへのリンクが含まれる。これらのプロパティ セットおよびインターフェイスには、DVD 専用のものと、DVD のデコードにおいて広範囲に使用されるものとがある。ここに挙げたもののほかに、デコーダとそのピンは『DirectShow フィルタの開発』に記載されている汎用の DirectShow フィルタ インターフェイスもサポートする必要がある。

ここには、以下のトピックが含まれる。

  • デコーダのボリューム制御
  • Windows における DVD のリージョン変更のサポート

関連項目

  • DVD カラオケ プロパティ セット
  • DVD コピー保護プロパティ セット
  • DVD サブピクチャ プロパティ セット
  • ピン プロパティ セット
  • IKsPropertySet インターフェイス
  • IVideoFrameStep インターフェイス (ハードウェア デコーダのみ)
  • IVPConfig インターフェイス (ハードウェア デコーダのみ)


デコーダのボリューム制御

アプリケーションは、IBasicAudio インターフェイスを使用してオーディオのボリュームを制御する。IBasicAudio インターフェイス ハンドラが KSProxy に対して提供されている。デコーダが KSProxy からのボリューム コマンドを処理するには、そのセットアップ スクリプトにいくつかのレジストリ キーを追加する必要がある。また、KSPROPSETID_Wave プロパティ セットをサポートしていなければならない。

ドライバに対していくつかの新しいレジストリ キーを作成する:

  HKLM\SYSTEM\
    CurrentControlSet\Control
      DeviceClasses
        (decoder guid, eg 2721AE....)
          (Pnp id, eg ##?#VDGENDEV#...)
            #GLOBAL
              Device Parameters
                CLSID		REG_SZ	{17CCA...}
                  FriendlyName	REG_SZ	WDM DVD Driver
                    Interfaces <--- このキーを作成する
                    {b9f8ac3e-0f71-11d2-b72c-00c04fb6bd3d} <-- このキーも作成する。これは値ではない)
      MediaInterfaces
        {b9f8ac3e-0f71-11d2-b72c-00c04fb6bd3d} <-- このキーを作成する
          (default)		REG_SZ	'KsProxy IBasicAudio handler' <-- この値を設定する
          IID	REG_SZ	56 a8 68 b3 0a d4 11 ce b0 3a 00 20 af 0b a7 70	<-- この文字列値を設定する

ボリューム制御を実現するために、ドライバは KsProperty.Id = KSPROPERTY_WAVE_VOLUME と共に KSPROPSETID_Wave もサポートする必要がある。このプロパティは、IKsPropertySet::Get および IKsPropertySet::Set メソッドを通してドライバに渡される。LeftAttenuation および RightAttentuation フィールドは、それぞれ左側と右側のスピーカのボリュームを 0x0000 ～ 0xffff のリニア値として指定する。


DVD リージョン変更サポート (Windows)

はじめに

ここでは、DVD リージョン選択プロセスが Microsoft® Windows® 9x および Windows 2000 上でどのように動作するかについて述べる。最初に、DVD リージョン情報の 3 つのソースについて説明する。次に、PC システム メーカーがシステムの初期 DVD リージョンをどのように設定するかを説明する。最後に、DVD ナビゲータがドライブ、デコーダ、およびディスク間でどのようにリージョンの一致を決定するかについて説明する。ここでは、アプリケーションおよびデコーダの開発者がコード内に適切な DVD リージョン選択サポートをどのように実装するかを示す。

DVD リージョン情報のソース

DVD リージョン情報にはソースが 3 つあり、Windows PC 上の DVD の再生に対するリージョンはこのすべてのソースによって決定される。
  • DVD タイトル
    ほとんどの DVD タイトルには、特定のリージョンに対するマークが付いている。タイトルの中には 1 つのリージョンでのみ再生できるもの、複数のリージョンで再生できるもの、すべてのリージョンで再生できるものがある。
  • DVD-ROM ドライブ
    DVD-ROM ドライブには、RPC Phase 1 と RPC Phase 2 (以降は RPC1 および RPC2 と表記する) の 2 種類がある。RPC1 ドライブには、リージョン管理に対するハードウェア サポートは内蔵されていない。これらのドライブの場合、Windows はリージョン変更回数情報を保持し、リージョンは 1 回のみ変更できる。RPC2 ドライブは、リージョン変更回数情報をハードウェア内に保持し、一般的にリージョンは 5 回まで変更できる。
  • DVD デコーダ
    一部の DVD デコーダ、ハードウェア、ソフトウェアは、特定のリージョン用に設定されている。 一般に、ユーザーはデコーダのリージョンを変更できない。

Windows 98 および Windows 2000 において初期リージョンを設定する方法

PC の DVD ドライブに対する初期 DVD リージョンを選択するのは、システム メーカーの役割である。

  • Windows 98 の場合
    システム メーカーはレジストリ キー (HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\DefaultDVDRegion (バイナリ)) の設定によって、ドライブに対するデフォルト DVD リージョンを設定できる。このキーの値は、最初の再生に対して設定するリージョン番号の値にしなければならない。OPK ビルドを使用しているシステム メーカーはこの値を "監査モード ブート" の間にレジストリに追加できるため、エンド ユーザーが初期リージョンを設定することはない。DVD 対応 Windows システム上で DVD タイトルが再生される前にこのキーが設定された場合は、Windows のコンポーネントは DVD タイトルの再生を最初に試みるときにドライブに対してそのリージョンを選択する。

    システム メーカーがレジストリにデフォルト リージョンを設定し、デフォルト リージョンを含むマルチ リージョン ディスクを再生した場合、リージョンはデフォルトに設定されディスクが再生される。ディスクのリージョンがデフォルト リージョンに一致しない場合、ユーザーは必要なリ-ジョンへの変更を求められる。(RPC-1 ドライブに対して行うことができる変更はこの一度だけである。)このデフォルト リージョンがシステム メーカーによって設定されていない場合、Windows はオペレーティング システムのロケール、タイム ゾーンなどに基づいてリージョンを選択する。最初に再生されるディスクがマルチ リージョン ディスクである場合、Windows はロケール、タイムゾーンなどに基づいてリージョンを選択し、最も小さいリージョン番号との一致を探す。マルチ リージョン ディスク上のリージョンと Windows によって選択されたリージョンが 1 つも一致しなかった場合は、ディスク上の最も小さい番号を持つリージョンが選択される。

    メーカーがリージョンを設定しなかった場合、Windows 98 オペレーティング システムのベース コンポーンネントはオペレーティング システム言語およびタイム ゾーンに基づいて最初のブート時にリージョンを選択し、ドライブをそのリージョンに設定する。システム メーカーはドライブ上でリージョンを自由に設定できるが、製造プロセスの間に設定が行われなかった場合は、Windows が推測に基づいてドライブのリージョンを選択する。

  • Windows 2000 の場合
    Windows 2000 では、マシンがセット アップされているロケールに基づいて デフォルト DVD リージョンが選択される。Windows 2000 は常にこの値を使用して DVD ドライブに対する初期リージョンを設定するが、ドライブにディスクが入っていればディスクのリージョンも使用する。システム メーカーでは、Windows 2000 の DVD ドライバに対する初期リージョンを設定するために何か行う必要はない。

    RPC1 ドライブの場合、ブート アップの間にドライブにディスクがないときはマシンのロケールだけに基づいてデフォルト リージョンが設定される。ブート アップの間にドライブに DVD ディスクがある場合は、デフォルト リージョンがディスクのリージョンと一致すれば選択されてドライブのリージョンになる。一致しない場合は、ディスク上の最も小さい番号のリージョンがドライブの初期リージョンとして選択される。デフォルトが適切ではない場合に、ユーザー (またはシステム メーカー) が行える変更は一度だけである。

    RPC2 ドライブの場合、セットアップ プロセスの間に Windows 2000 がドライブにリージョン セット がないこと (フレッシュ ドライブ) を見つけると、上記のようなリージョンを選択するが、これはドライブにディスクがある場合のみである。(ドライブにディスクがない場合、RPC1 ドライブはリージョンを選択しない)。 RPC2 ドライブに対してリージョンがいったん設定されると、オペレーティング システムの再インストールまたはクリーン インストールによって自動的に変更されることはない。

Microsoft DVD ナビゲータによって実行されること

Microsoft DVD ナビゲータは以下の方法を使用して、PC 上で DVD ディスクを再生中にリージョンの一致を確認する。

DVD ナビゲータはディスクのリージョン、ドライバのリージョン、およびデコーダのリージョンを取得する。ディスクのリージョンが "すべてのリージョン" である場合、DVD ナビゲータはディスクを再生する。ディスクにすべてのリージョンに対するマークが付いていない場合、DVD ナビゲータはデコーダにあらかじめ設定されたリージョンがあるかどうかを確認する。デコーダにあらかじめリージョンが設定されており、それがディスクのリージョンと一致しない場合は、DVD ナビゲータはエラーを返し、現在の DVD の設定ではディスクを再生できないということを示す。デコーダのリージョンがディスクのリージョンと同じ場合、DVD ナビゲータはドライブのリージョンがディスクのリージョンと同じかどうかを確認する。同じであれば、DVD ナビゲータはタイトルを再生する。同じでない場合は、DVD ナビゲータはドライブのリージョンを変更するためのコードを呼び出す。使用できるリージョン番号が残っていない場合、リージョン変更の試みは失敗し、そのシステム上でタイトルを再生できない。

次の DVD リージョンの変更

Windows 9x の場合、DVD ナビゲータは DVD ドライブ上でのリージョンの変更が必要であることがわかると、DVDRgn.exe を使用してドライブ上のリージョンの変更を要求する。このアプリケーションは、オペレーティング システムの他のコンポーネントと合わせてリージョナライズされる。このアプリケーションは、Windows 98 にデフォルトではインストールされていない。対象となるシステムへのインストールの方法を以下に示す。

Windows 2000 の場合、DVD ナビゲータは DVD マネージャで DVD-ROM ドライブ デバイス上のプロパティ ページを呼び出す。リージョンを変更する必要がある場合は、DVDPlay.exe アプリケーションによってもプロパティ ページが呼び出される。プロパティ ページの UI は DVDRgn.exe の UI によく似ており、オペレーティング システムによってリージョナライズされる。

RPC1 ドライブの場合、Windows オペレーティング システムのコンポーネントがリージョンの変更を管理する。RPC2 ドライブでは、リージョン設定はハードウェア自体に保持される。使用できる変更番号が RPC2 ドライブ上に残っていない場合、ドライブはリージョン変更の呼び出しに失敗し、そのことはオペレーティング システム内のリージョン変更コンポ-ネントによってユーザーに示される。

Windows リージョン変更サポート コンポーネントのインストール

アプリケーション開発者は Windows に組み込まれた DVD リージョン変更サポートを使用して、DVD 再生アプリケーション内のリージョンを変更できる。Windows 9x および Windows 2000 プラットフォームにおいてこれを実行するには 2 つの方法がある。
  • Windows 9x の場合
    Windows 9x プラットフォームにおいては、標準 INF ファイルを使って MDM ストリーム クラス ミニドライバの付いたハードウェア デコーダをインストールした場合のみ、リージョン変更アプリケーションの DVDRgn.exe がインストールされる。他のソフトウェア デコーダおよびアップグレード マーケットの場合は、インストール プログラムが使用する INF ファイルに以下の行を挿入することによって、対象のシステムに DVDRgn.exe を追加する。
    [Version]
Signature=$CHICAGO$
LayoutFile=layout.inf

[DestinationDirs]
DvdRgnCopy=25       ; Windows
DefaultDestDir=25   ; Windows

[DefaultInstall]
CopyFiles=DvdRgnCopy

[DvdRgnCopy]
dvdrgn.exe
  • Windows 2000 の場合
    Windows 2000 システムでは、DVD リージョン変更サポートを提供するコンポーネントは DLL storprop.dll (%windir%\system32 内) にある。 この DLL はデフォルトでインストールされており、これが有効にするための追加手順は必要ない。

リージョン変更サポートのアプリケーションへの統合

以下の関数は、デコーダまたは DVD アプリケーションにリージョン変更サポートを統合したい開発者に提供される。
/////////////////////////////////////////////////////////////////////
// ChangeDVDRegion : DVD ドライブのリージョンを変更する関数
//
// パラメータ :
//  In : hWnd - この関数を呼び出すアプリケーション
//             のウィンドウ ハンドル
//  Out : なし。
//
// 以下の値を返す :
//     TRUE : ドライブのリージョン変更が成功した場合
//     FALSE : リージョン変更が失敗した場合 (おそらく、
//          有効な DVD-V ディスクのあるドライブが見つからないため)。
/////////////////////////////////////////////////////////////////////
BOOL ChangeDVDRegion(HWND hWnd)
{
typedef BOOL (APIENTRY *DVDPPLAUNCHER) (HWND hWnd, CHAR DriveLetter);
BOOL   bRegionChanged = FALSE;
TCHAR   szCmdLine[MAX_PATH];

// まず、有効な DVD-V ディスクのある DVD ドライブはどれかを見つける。

TCHAR     szDVDDrive[4];
if (! GetDriveLetter (szDVDDrive) )
  {
MessageBox(hWnd,
TEXT("No DVD drive was found with DVD-V disc.")
TEXT("\nCannot change DVD region of the drive."),
TEXT("Error"), MB_OK | MB_INFORMATION) ;
return FALSE ;
  }

// 実行中の OS を検出する。Windows NT の場合、storprop.dll を使用し、
// Windows 9x の場合は DVDRgn.exe アプリケーションを使用してリージョンを変更する。

OSVERSIONINFO   ver;
ver.dwOSVersionInfoSize = sizeof(OSVERSIONINFO);
GetVersionEx(&ver);
if (VER_PLATFORM_WIN32_NT  == ver.dwPlatformId)
  {
// Windows NT プラットフォーム
HINSTANCE       hInstDLL;
DVDPPLAUNCHER    dvdPPLauncher;
CHAR         szDVDDriveA[4];

#ifdef UNICODE
WideCharToMultiByte(0, 0, szDVDDrive, -1,
szDVDDriveA, sizeof(szDVDDriveA),
NULL, NULL );
#else
strcpy(szDVDDriveA, szDVDDrive);
#endif  // UNICODE

GetSystemDirectory(szCmdLine, MAX_PATH);
lstrcat(szCmdLine, TEXT("\\storprop.dll"));

hInstDLL = LoadLibrary (szCmdLine);
if (hInstDLL)
    {
dvdPPLauncher = (DVDPPLAUNCHER) GetProcAddress(hInstDLL,
"DvdLauncher");
if (dvdPPLauncher)
      {
bRegionChanged = dvdPPLauncher(hWnd, szDVDDriveA[0]);
      }
FreeLibrary(hInstDLL);
    }
}  // Windows NT プラットフォーム用のリージョン変更コードの終わり
else   // Windows 9x プラットフォーム
  {
// コマンド ライン文字列用の \windows\dvdrgn.exe のパスを取得する
GetWindowsDirectory(szCmdLine, MAX_PATH);
lstrcat(szCmdLine, TEXT("\\DVDRgn.exe "));

// コマンド ライン パラメータとしてドライブ レターのみ追加する
lstrncat(szCmdLine, szDVDDrive, 1);

// DVDRgn.exe 実行の準備をする
STARTUPINFO               StartupInfo;
PROCESS_INFORMATION       ProcessInfo;
StartupInfo.cb            = sizeof(StartupInfo);
StartupInfo.dwFlags       = STARTF_USESHOWWINDOW;
StartupInfo.wShowWindow   = SW_SHOWNORMAL;
StartupInfo.lpReserved    = NULL;
StartupInfo.lpDesktop     = NULL;
StartupInfo.lpTitle       = NULL;
StartupInfo.cbReserved2   = 0;
StartupInfo.lpReserved2   = NULL;
if (CreateProcess(csModuleName, szCmdLine,
NULL, NULL, TRUE,
NORMAL_PRIORITY_CLASS,
NULL, NULL, &StartupInfo, &ProcessInfo) )
    {
// DVDRgn.exe が終了するまで待つ
WaitForSingleObject(ProcessInfo.hProcess, INFINITE);
DWORD dwRet = 1;
BOOL bRet = GetExitCodeProcess(ProcessInfo.hProcess,
&dwRet);
// ユーザーがドライブのリージョン変更に成功した場合、
// DVDRgn.exe の終了コードは 0。
if (bRet && 0 == dwRet)
      {
bRegionChanged = TRUE;
      }
    }
}  // Windows 9x プラットフォーム用のリージョン変更コードの終わり

if (bRegionChanged)   // リージョンの変更が成功した場合
  {
// 古いフィルタ グラフを削除して新しいフィルタ グラフを作成するために、
// IDvdGraphBuilder::RenderDvdVideoVolume() を使用する。
  }
else   // DVD リージョンがなかった
  {
MessageBox(hWnd,
TEXT("DVD drive region could not be changed.")
TEXT("Error"), MB_OK | MB_INFORMATION) ;
  }
} //関数 ChangeDVDRegion の終わり

/////////////////////////////////////////////////////////////////////
// GetDriveLetter : 現在アクティブなドライブのドライブ レターを
//           取得する関数
// パラメータ :
//  In : pDvdC - DVDNavigator フィルタの IDvdControl
//                インターフェイスへのポインタ..
//  Out : pszDrive - 有効な DVD-V ディスクがあることがわかった、
//                  最初の DVD ドライブ。
//
// 以下の値を返す :
//     TRUE : DVD ドライブが検出された場合 (有効なディスクと共に)
//     FALSE : 有効な DVD-V ディスクのある DVD ドライブが検出されなかった場合。
/////////////////////////////////////////////////////////////////////
BOOL GetDriveLetter(IDvdControl *pDvdC, TCHAR *pszDrive)
{
CHAR   szPathA[MAX_PATH];
TCHAR   szPath[MAX_PATH];
ULONG   ulActualSize;
pszDrive[0] = pszDrive[3] = 0;

// 現在のルート ディレクトリを取得する
if (pDvdC ->GetRoot(szPathA, MAX_PATH, &ulActualSize))
  {
#ifdef UNICODE
MultiByteToWideChar(CP_ACP, 0, szPathA, 0, szPath, MAX_PATH);
#else
lstrcpy(szPath, szPathA);
#endif  // UNICODE
lstrcpyn(pszDrive, szPath, 3);
if (DRIVE_CDROM == GetDriveType(pszDrive)) // DVD ドライブ の場合
return TRUE;
  }

// 有効なドライブ全体をループして、有効な DVD-V ディスクが入っている
// DVD ドライブはどれかを見つける。

// 有効なドライブをすべて取得する
DWORD dwLeng = GetLogicalDriveStrings(MAX_PATH, szPath);
TCHAR  *pszTemp = szPath;
// すべてのドライブを 1 つずつ試す
for (DWORD dw = 0; dw < dwLeng; dw += 4)
  {
// 必要な (.ifo) ファイルを持つ CD-ROM ドライブのみ調べる
if (DRIVE_CDROM  == GetDriveType(pszTemp))
      {
TCHAR   szDVDPath1[MAX_PATH]
TCHAR   szDVDPath2[MAX_PATH];
lstrcpyn(szDVDPath1, pszTemp, 4);
lstrcpyn(szDVDPath 2, pszTemp, 4);
lstrcat(szDVDPath1, TEXT("Video_ts\\Video_ts.ifo"));
lstrcat(szDVDPath2, TEXT("Video_ts\\Vts_01_0.ifo"));

//  .ifo ファイルがドライブ上にある場合、それは有効な DVD-V ディスクを持っている
if (DoesFileExist(achDVDPath1) && DoesFileExist(achDVDPath2))
        {
lstrcpyn(pszDrive, pszTemp, 3);
return TRUE;   // 有効な DVD-V ディスクを持っている最初のドライブを返す
        }
      }
pszTemp += 4;
  }

return FALSE ;   // DVD ドライブ (DVD-V コンテンツを含む) が見つからなかった。
} //関数 GetDriveLetter の終わり

/////////////////////////////////////////////////////////////////////
// DoesFileExist : 特定のファイル名が既存のファイルであるかどうかを確認する関数。
//
// パラメータ :
//  In : pszFile - 存在を確認するファイル名の文字列
//  Out : なし。
//
// 以下の値を返す :
//     TRUE : 指定されたファイルが見つかった場合。
//      FALSE : 指定されたファイルが見つからなかった場合。
/////////////////////////////////////////////////////////////////////
BOOL DoesFileExist(LPTSTR pszFile)
{
HANDLE    hFile = NULL ;
// 必要なファイルを開いて読むことができるかどうかテストを試みる場合に、
// エラー メッセージ ボックスが表示されないようにしたい。

UINT uErrorMode = SetErrorMode(SEM_FAILCRITICALERRORS |
SEM_NOOPENFILEERRORBOX);
hFile = CreateFile(pszFile, GENERIC_READ,
FILE_SHARE_READ, NULL,
OPEN_EXISTING, FILE_FLAG_SEQUENTIAL_SCAN,
NULL);
SetErrorMode(uErrorMode);  // エラー モードを回復する。
If (INVALID_HANDLE_VALUE  == hFile)
return FALSE ;

CloseHandle(hFile);
return TRUE;
} //関数 DoesFileExist の終わり


DirectShow チュートリアル

ここでは、Microsoft® DirectShow® のチュートリアルを示す。

  • デバイスとフィルタの列挙
  • フィルタ グラフ内のオブジェクトの列挙
  • フィルタのプロパティ ページの表示
  • ストリーム内のシーク
  • メディア サンプルの入手
  • AVI ファイルの再圧縮


デバイスとフィルタの列挙

アプリケーションが、ユーザーのシステムにある特定のフィルタを見つけなければならないことがある。たとえば、ビデオ キャプチャ アプリケーションは、使用可能なキャプチャ デバイスのリストを表示する必要がある。Microsoft® DirectShow® はコンポーネントベースのアーキテクチャを使用しているため、システムにどのフィルタがインストールされているかが実行時までわからないことがある。ハードウェア デバイスを表すフィルタの場合は特にそうである。以下に示す DirectShow の 2 つのコンポーネントによって、フィルタを見つけやすくなる。

  • システム デバイス列挙子は、カテゴリごとにフィルタを見つける。
  • フィルタ マッパーは、アプリケーションが与える検索条件に応じてフィルタを見つける。

ここで議論する列挙子は、COM の列挙インターフェイスで使用される標準形に従う。詳細については、Microsoft Platform SDK の IEnumXXXX のトピックを参照すること。このトピックは、以下のセクションで構成される。

  • システム デバイス列挙子の使用
  • フィルタ マッパーの使用

システム デバイス列挙子の使用

システム デバイス列挙子は、ユーザーのシステムに登録されているフィルタをカテゴリごとに列挙するための統一された方法を提供する。さらに、同じフィルタが複数のデバイスをサポートしている場合でも、それぞれのハードウェア デバイスを区別できる。このことは、Windows Driver Model (WDM) および KSProxy フィルタを使用するデバイスの場合に特に有用である。たとえば、ユーザーが複数の WDM ビデオ キャプチャ デバイスを持ち、それらすべてが同じフィルタによってサポートされることがある。システム デバイス列挙子は、これらを別々のデバイス インターフェイスとして扱う。

システム デバイス列挙子は、オーディオ キャプチャやビデオ圧縮など、特定カテゴリ向けの列挙子を作成することで機能する。カテゴリ列挙子は、そのカテゴリ内の各デバイスに対する一意のモニカを返す。また、関連のあるプラグ アンド プレイ デバイスを自動的にカテゴリに含める。カテゴリのリストについては、「フィルタ カテゴリ」を参照すること。

システム デバイス列挙子を作成するには、クラス識別子 (CLSID) に CLSID_SystemDeviceEnum を指定して CoCreateInstance を呼び出す。カテゴリ列挙子を入手するには、そのカテゴリの CLSID を使って ICreateDevEnum::CreateClassEnumerator を呼び出す。カテゴリ列挙子は IEnumMoniker インターフェイスをサポートしていて、このインターフェイスを使ってそれぞれのモニカを列挙できる。モニカの IMoniker::BindToObject を呼び出してデバイス オブジェクトを生成および初期化するか、IMoniker::BindToStorage を呼び出してデバイスのフレンドリ名を取得する (たとえば、ユーザー インターフェイスのリスト ボックスを満たすため)。次の図にこの処理を示す。

以下の例に、システム デバイス列挙子のインスタンスを生成し、それを使ってビデオ コンプレッサ デバイスを列挙する方法を示す。簡単であるため、エラー チェックは行っていない。

ICreateDevEnum *pSysDevEnum = NULL;
CoCreateInstance(CLSID_SystemDeviceEnum,
    NULL, CLSCTX_INPROC, IID_ICreateDevEnum,
    (void **)&pSysDevEnum);

IEnumMoniker *pEnumCat = NULL;
pSysDevEnum->CreateClassEnumerator(CLSID_VideoCompressorCategory, &pEnumCat, 0);

IMoniker *pMoniker;
ULONG cFetched;
while(pEnumCat->Next(1, &pMoniker, &cFetched) == S_OK)
{
    IPropertyBag *pPropBag;
    pMoniker->BindToStorage(0, 0, IID_IPropertyBag, (void **)&pPropBag);

    VARIANT varName;
    varName.vt = VT_BSTR;
    pPropBag->Read(L"FriendlyName", &varName, 0);

    // この名前を使って何かを行う。

    SysFreeString(varName.bstrVal);
    pPropBag->Release();
    pMoniker->Release();
}
pEnumCat->Release();
pSysDevEnum->Release();

フィルタ マッパーの使用

フィルタ マッパーは、さまざまな検索条件に基づいてフィルタを列挙する COM オブジェクトである。フィルタ マッパーはシステム デバイス列挙子ほど効率的ではないので、特定のカテゴリのフィルタが必要な場合は、システム デバイス列挙子を使う方がよい。しかし、特定のメディア タイプの組み合わせをサポートするが、はっきりしたカテゴリには入らないフィルタを見つける場合は、フィルタ マッパーを使用する必要がある。その例が、レンダリング フィルタやデコーダ フィルタである。

フィルタ マッパーは、IFilterMapper2 インターフェイスをサポートしている。フィルタを捜すには、IFilterMapper2::EnumMatchingFilters を呼び出す。このメソッドは、検索条件を定義するパラメータをいくつか受け取り、条件に一致するフィルタの列挙子を返す。この列挙子は IEnumMoniker をサポートし、一致するそれぞれのフィルタに一意のモニカを与える。

以下の例では、デジタル ビデオ (DV) 入力を受け取り、1 つ以上の出力ピンを持つ任意のメディア タイプのフィルタを列挙している (DV ビデオ デコーダ フィルタ がこの条件に合致する)。

IFilterMapper2 *pMapper = NULL;
IEnumMoniker *pEnum = NULL;

CoCreateInstance(CLSID_FilterMapper2,
    NULL, CLSCTX_INPROC, IID_IFilterMapper2,
    (void **) &pMapper);

GUID arrayInTypes[2];
arrayInTypes[0] = MEDIATYPE_Video;
arrayInTypes[1] = MEDIASUBTYPE_dvsd;

hr = pMapper->EnumMatchingFilters(
        &pEnum,
        0,                  // 予約済み
        TRUE,               // 完全一致を使用?
        MERIT_DO_NOT_USE+1, // 最小のメリット
        TRUE,               // 1 つ以上の入力ピン?
        1,                  // 入力のメジャー タイプ/サブタイプの対の数
        arrayInTypes,       // 入力のメジャー タイプ/サブタイプの対の配列
        NULL,               // 入力メディア
        NULL,               // 入力ピンのカテゴリ
        FALSE,              // レンダラでなければならないか?
        TRUE,               // 1 つ以上の出力ピン?
        0,                  // 出力のメジャー タイプ/サブタイプの対の数
        NULL,               // 出力のメジャー タイプ/サブタイプの対の配列
        NULL,               // 出力メディア
        NULL);              // 出力ピンのカテゴリ

// 前の例のように、pEnum を使って列挙する。

EnumMatchingFilters メソッドには、上の例にコメントを付けたようにかなりの数のパラメータがある。この例で重要なのは以下のパラメータである。

  • 最小のメリット値: フィルタは、MERIT_DO_NOT_USE より大きいメリット値を持っていなければならない。
  • 入力タイプ: 呼び出し元は、メジャー タイプとサブタイプの対を含む配列を渡す。これらの対のうち 1 つ以上をサポートするフィルタだけが合致する。
  • 完全一致: フィルタは、メジャー タイプ、サブタイプ、ピン カテゴリ、またはメディアに NULL 値を登録できる。完全一致を指定しなければ、NULL 値はワイルドカードとして機能し、任意の指定値と一致する。完全一致の場合、フィルタは条件と完全に一致しなければならない。しかし、検索条件に NULL パラメータを与えると、それは常にワイルドカード、すなわち "考慮されない" 値として機能し、任意のフィルタと一致する。


フィルタ グラフ内のオブジェクトの列挙

Microsoft® DirectShow® アプリケーションは、フィルタ グラフのメソッドを呼び出すだけでよいので、それぞれのフィルタについて悩む必要はほとんどない。しかし時には、グラフ内の特定のフィルタや、フィルタ上の特定のピンを見つけなければならないこともある。たとえば、アプリケーションがフィルタのプロパティを設定するために、フィルタが公開するカスタム インターフェイスを使用する場合である。あるいは、特殊化したフィルタ グラフを手作業で構築する場合は、フィルタを接続するためにそれぞれのピンのメソッドを呼び出す必要がある。こういうときのために、DirectShow には、フィルタ グラフ内のオブジェクトを列挙するためのメソッドがいくつか用意されている。

ここで議論する列挙子は、COM の列挙インターフェイスで使用される標準形に従う。詳細については、Platform SDK の IEnumXXXX のトピックを参照すること。ユーザーのコンピュータに登録されていながら、まだフィルタ グラフには入っていないフィルタの列挙については、「デバイスとフィルタの列挙」を参照すること。

このトピックは、以下のセクションで構成される。

  • フィルタの列挙
  • ピンの列挙
  • メディア タイプの列挙

フィルタの列挙

フィルタ グラフ マネージャがサポートする IFilterGraph::EnumFilters メソッドが、フィルタ グラフ内のすべてのフィルタを列挙する。これは、IEnumFilters インターフェイスへのポインタを返す。IEnumFilters::Next メソッドは、IBaseFilter インターフェイス ポインタを取得する。

以下の例に示す関数は、グラフ内のフィルタを列挙し、各フィルタの名前が付いたメッセージ ボックスを表示する。この関数は、IBaseFilter::QueryFilterInfo メソッドを使ってフィルタの名前を取得する。参照カウントをデクリメントするために、インターフェイスの IUnknown::Release を呼び出す部分に注意すること。

void EnumFilters (IFilterGraph *pGraph)
{
    IEnumFilters *pEnum = NULL;
    IBaseFilter *pFilter;
    ULONG cFetched;

    pGraph->EnumFilters(&pEnum);
    while(pEnum->Next(1, &pFilter, &cFetched) == S_OK)
    {
        FILTER_INFO FilterInfo;
        char szName[256];

        pFilter->QueryFilterInfo(&FilterInfo);
        WideCharToMultiByte(CP_ACP, 0, FilterInfo.achName, -1, szName, 256, 0, 0);
        MessageBox(NULL, szName, "Filter name", MB_OK);

        FilterInfo.pGraph->Release();
        pFilter->Release();
    }
    pEnum->Release();
}

ピンの列挙

フィルタがサポートする IBaseFilter::EnumPins メソッドが、フィルタで使用できるピンを列挙する。これは、IEnumPins インターフェイスへのポインタを返す。IEnumPins::Next メソッドは、IPin インターフェイス ポインタを取得する。

以下の例に示す関数は、与えられたフィルタ上で与えられた方向 (入力または出力) のピンを見つける。この関数は、PIN_DIRECTION の列挙を使ってピンの方向を指定し、IPin::QueryDirection メソッドを使って列挙された各ピンの方向を見つける。この関数は、一致するピンを見つけると、未処理の参照カウントを持つ IPin インターフェイス ポインタを返す。インターフェイスの解放は、呼び出し元が行わなければならない。

IPin *GetPin(IBaseFilter *pFilter, PIN_DIRECTION PinDir)
{
    BOOL       bFound = FALSE;
    IEnumPins  *pEnum;
    IPin       *pPin;

    pFilter->EnumPins(&pEnum);
    while(pEnum->Next(1, &pPin, 0) == S_OK)
    {
        PIN_DIRECTION PinDirThis;
        pPin->QueryDirection(&PinDirThis);
        if (bFound = (PinDir == PinDirThis))
            break;
        pPin->Release();
    }
    pEnum->Release();
    return (bFound ? pPin : 0);
}

メディア タイプの列挙

ピンがサポートする IPin::EnumMediaTypes メソッドが、ピンの優先されるメディア タイプを列挙する。これは、IEnumMediaTypes インターフェイスへのポインタを返す。IEnumMediaTypes::Next メソッドは、メディア タイプを記述する AM_MEDIA_TYPE 構造体へのポインタを取得する。

メディア タイプ列挙子があるのは、主にフィルタ グラフがインテリジェント接続を行いやすくするためであり、アプリケーションでこれを使用することはまずない。ピンは、優先されるメディア タイプを返すとは限らず、返されるメディア タイプはフィルタの接続状態によって異なる。たとえば、フィルタの出力ピンは、フィルタの入力ピンにどのメディア タイプが設定されているかによって異なるメディア タイプ セットを返す。


ストリーム内のシーク

ここでは、アプリケーションがメディア ストリーム内の複数の位置をシークする方法について説明する。次のトピックが含まれる。

  • 概要
  • シーク機能
  • タイム フォーマット
  • ストリーム位置の設定と取得
  • 再生レートの設定
  • ケース スタディ:シーク バーの実装

概要

Microsoft® DirectShow® は、IMediaSeeking インターフェイスによるシークをサポートしている。このインターフェイスを公開するのはフィルタ グラフ マネージャであるが、シーク機能を実装するのは常にフィルタである。

アプリケーションはフィルタ グラフ マネージャに IMediaSeeking を問い合わせ、これを使ってシーク コマンドを発行する。フィルタ グラフ マネージャも IMediaSeeking インターフェイスを使って、そのシーク コマンドをグラフ内のすべてのレンダリング フィルタに配布する。各レンダラは、これらのコマンドを実行できるフィルタに到達するまで、アップストリーム フィルタの出力ピンを介してコマンドをアップストリームに転送する。通常AVI Splitter などのソース フィルタまたはパーサー フィルタが、シーク操作を実行する。

フィルタがシーク操作を実行すると、保留中のデータはすべてフラッシュされる。ダウンストリーム フィルタでもデータがフラッシュされる。詳細については、「フィルタ開発者が使用するデータ フロー」を参照すること。結果としてグラフから既存のデータがフラッシュされるため、シーク コマンドの遅延時間が最小化されることになる。次の図は、処理の順序を具体的に示す。

パーサー フィルタに複数の出力ピンがある場合は通常、その中の 1 つがシーク コマンドを受け取るよう指定されている。その他のピンがシーク コマンドを受け取っても、拒否するか無視する。このように、パーサーはそのストリームのすべてが同期化する状態を維持する。

シーク機能

データによってはシークできないものがある。たとえば、カメラからのライブ ストリームをシークすることはできない。ストリームがシーク可能である場合、サポートされるシークの種類はさまざまである。シークには次の種類がある。

  • ストリーム内の任意の位置をシークする。
  • ストリームの時間幅を取得する。
  • ストリーム内の現在位置を取得する。
  • 逆方向に再生する。

IMediaSeeking インターフェイスは、対応可能なシーク機能を表す AM_SEEKING_SEEKING_CAPABILITIES フラグを定義する。ストリームの機能を取得するには、IMediaSeeking::GetCapabilities メソッドを呼び出す。このメソッドにより、ビット単位のフラグの組み合わせが返される。アプリケーションは & (ビット単位の AND) 演算子を使って、フラグを検査できる。たとえば、次のコードはグラフが任意の位置をシークできるかどうかをチェックする。

DWORD dwCap = 0;
HRESULT hr = pSeek->GetCapabilities(&dwCap);
if (AM_SEEKING_CanSeekAbsolute & dwCap)
{
// グラフは絶対位置をシークできる。
}

このほかに、IMediaSeeking::CheckCapabilities メソッドを使って、シーク機能のサブセットを検査できる。アプリケーションは、次のようにフラグの組み合わせをビット単位で解析する。

// チェックする機能のフラグを設定する。
DWORD dwCaps = AM_SEEKING_CanSeekAbsolute |
AM_SEEKING_CanSeekForwards |
AM_SEEKING_CanSeekBackwards;

HRESULT hr = pMediaSeeking->CheckCapabilities(&dwCaps);

指定した機能がサポートされる場合、戻り値は S_OK である。指定した機能がまったくサポートされない場合、エラー コードが返される。指定した機能の一部がサポートされる場合、戻り値は S_FALSE である。メソッドが戻った時点で、入力パラメータには、最初に渡されたセットではなく、サポートされる機能のビット単位の組み合わせが格納されている。この結果は次のように検査できる。

if (hr == S_FALSE) // 要求された機能の一部がサポートされない。
{
if (dwCaps & AM_SEEKING_CanSeekAbsolute)
// この機能がサポートされる。
        ...
}

タイム フォーマット

IMediaSeeking インターフェイスは、メディア タイム (100 ナノ秒単位)、ビデオ フレーム、およびストリーム内のバイト オフセットなど、複数のタイム フォーマットをサポートしている。各タイム フォーマットは、グローバル一意識別子 (GUID) で定義される。DirectShow で定義されるタイム フォーマットの一覧については、「タイム フォーマット GUID」を参照すること。サード パーティもカスタムタイム フォーマットの GUID を定義できる。

フィルタ グラフ マネージャの既定値はメディア タイムである。別のタイム フォーマットを使用するには、IMediaSeeking::SetTimeFormat メソッドを呼び出す。このメソッドが正常終了すると、その後のすべてのシーク コマンドは新しく設定されたフォーマットを使用する。メディア ストリームが指定のタイム フォーマットをサポートするかどうかを判断するには、IMediaSeeking::IsFormatSupported メソッドを呼び出す。次のコードは、タイム フォーマットをフレーム単位に設定し、その結果を後で使用するためにブール値のフラグに格納する例である。

hr = pSeek->SetTimeFormat(&TIME_FORMAT_FRAME);
BOOL bTimeInFrames = SUCCEEDED(hr);

ストリーム位置の設定と取得

フィルタ グラフが保持する位置値は、現在位置と停止位置の 2 つである。

  • 実行中のグラフでは、現在位置はレンダリング中のデータを反映する。停止またはポーズしたグラフでは、次の実行コマンドでストリーミングが開始する位置を表す。
  • 停止位置はストリームが終了する位置である。グラフが停止位置に到達すると、それ以降はデータがストリームされず、フィルタ グラフ マネージャは EC_COMPLETE イベントを投入する(ただし、グラフは自動的には停止状態に切り替わらない。詳細については、「イベントへの応答」を参照すること)。

現在位置を取得するには、IMediaSeeking::GetCurrentPosition メソッドを呼び出す。停止位置を取得するには、IMediaSeeking::GetStopPosition メソッドを呼び出す。戻り値は、現在のタイム フォーマットの単位を使用する (前の「タイム フォーマット」を参照すること)。戻り値は常に元のメディア ソースに対する相対値である。

新しい位置をシークする、または新しい停止位置を設定するには、IMediaSeeking::SetPositions メソッドを呼び出す。次のコードはその例である。

#define ONE_SECOND 10000000
REFERENCE_TIME rtNow = 2 * ONE_SECOND, rtStop = 5 * ONE_SECOND;

hr = pSeek->SetPositions(
&rtNow,  AM_SEEKING_AbsolutePositioning,
&rtStop, AM_SEEKING_AbsolutePositioning
    );

この例では、現在のタイム フォーマットがメディア タイムであることを前提としている。これは 100 ナノ秒単位である。1 秒は 10,000,000 単位となる。便宜上、例ではこの値を ONE_SECOND として定義している。

注 DirectShow 基底クラスを使用している場合、同じ値を持つ定数 UNITS が定義されている。詳細については、「基底クラス」を参照すること。

rtNow パラメータは新しい位置を指定する。2 番目のパラメータは、rtNow の解釈方法を定義するフラグである。この例のフラグは、rtNow がソース内の絶対位置として定義されることを示している。呼び出しが戻ると、フィルタ グラフは、ストリームの開始から 2 秒の位置にシークする。rtStop パラメータは終了タイムを指定する。最後のパラメータは、終了タイムも絶対位置であることを示すフラグである。

前の位置値からの相対位置を指定するには、AM_SEEKING_RelativePositioning フラグを使用する。位置値のいずれか 1 つを変更しないまま残すには、AM_SEEKING_NoPositioning フラグを使用する。その場合、対応する時間パラメータは NULL でもよい。次の例では、停止位置を変更せずに、10 秒先までシークする。

REFERENCE_TIME rtNow = 10 * ONE_SECOND;
hr = pSeek->SetPositions(
&rtNow, AM_SEEKING_RelativePositioning,
NULL, AM_SEEKING_NoPositioning
    );

フィルタ グラフを停止すると、ビデオ レンダラはシーク操作後にイメージを更新しない。ユーザーにとっては、シークが発生しなかったかのように見える。イメージを更新するには、シーク操作後にグラフをポーズする。グラフをポーズすることで、ビデオ レンダラに新しいビデオ フレームが挿入される。IMediaControl::StopWhenReady メソッドを使うと、グラフはポーズしてから停止状態に戻る。

再生レートの設定

再生レートを変更するには、IMediaSeeking::SetRate メソッドを呼び出す。新しいレートを元のレートの比として指定する。たとえば、通常速度の 2 倍で再生するには、次のようにする。

pSeek->SetRate(2.0)

レートは 0 より大きくなければならない。レートが 1 より大きくなると、通常より高速になる。レートが 0 と 1 の間であれば、通常より低速になる。

再生レートにかかわらず、現在位置と停止位置は常にオリジナル ソースからの相対で表される。たとえば、ソース ファイルが 20 秒 (通常の再生レートで) である場合、現在位置を 10 秒に設定してファイルの中央にシークする。停止位置が 20 秒 (ファイルの最後) で、再生レートが 2.0 である場合、ファイルは実時間の 5 秒で再生が終了する。つまり、ソース ファイルの残り 10 秒間は通常の 2 倍の速度で再生される。

ケース スタディ:シーク バーの実装

ここでは、メディア プレーヤー アプリケーションにシーク バーを実装する方法を説明する。シーク バーはトラック バー コントロールとして実装される。

アプリケーションの起動時に、トラック バーを初期化する。

HWND hTrack = GetDlgItem(hwnd, IDC_SLIDER1);
EnableWindow(hTrack, FALSE);
SendMessage(hTrack, TBM_SETRANGE, TRUE, MAKELONG(0, 100));

トラック バーは、ユーザーがメディア ファイルを開くまで無効である。トラック バーの範囲は 0 から 100 となる。アプリケーションはメディア タイムをファイル時間幅のパーセンテージに変換する。たとえば、トラック バーの位置 "50" は常にファイルの中央に相当する(このほかに、トラック バーの最大範囲をファイルの時間幅に設定する方法もある。ただし、メディア タイムは 64 ビットの整数であるのに対し、トラック バーの範囲は 32 ビットに制限されている)。

ユーザーがファイルを開くと、アプリケーションはファイル再生グラフを構築する。アプリケーションは、フィルタ グラフ マネージャに対して IMediaSeeking インターフェイスを問い合わせる (ここには示されない)。次に、アプリケーションは、グラフがシーク可能かどうか、およびファイル時間幅を取得可能かどうかをチェックする。グラフがこれら両方の機能をサポートする場合、アプリケーションはファイル時間幅を取得し、トラック バーを有効にする。

REFERENCE_TIME g_rtTotalTime;
DWORD caps = AM_SEEKING_CanSeekAbsolute | AM_SEEKING_CanGetDuration;

if (pSeek && S_OK == pSeek->CheckCapabilities(&caps))
{
pSeek->GetDuration(&g_rtTotalTime);
EnableWindow(hTrack, TRUE);
}

ユーザーが "再生" コマンドを発行すると、アプリケーションはグラフを実行する。また、トラック バーの位置を定期的に更新するタイマ イベントも開始される。各タイマ イベントがアクティブになると、タイマ コールバックが現在の再生位置を取得し、それに応じてトラック バーを設定する。

#define TICKLEN 100   // ティックの長さ (トラック バーの更新間隔)
MMRESULT wTimerID;

void CALLBACK MediaTimer(UINT wTimerID, UINT msg,
DWORD dwUser, DWORD dw1, DWORD dw2)
{
REFERENCE_TIME rtNow;
pSeek->GetCurrentPosition(&rtNow);
long sliderTick = (long)((rtNow * 100) / g_rtTotalTime);
SendMessage( hScroll, TBM_SETPOS, TRUE, sliderTick );
}

void OnUserPlay()
{
pGraph->Run();
if(wTimerID)        // タイマ イベントは保留中か?
    {
timeKillEvent(wTimerID);  // タイマをキャンセルする。
wTimerID = 0;
    }
wTimerID = timeSetEvent(TICKLEN, 50, MediaTimer, NULL, TIME_PERIODIC);
}

ユーザーがグラフを停止またはポーズすると、アプリケーションはタイマ イベントをキャンセルする。

ユーザーがトラック バー コントロールをドラッグまたはクリックすると、アプリケーションは WM_HSCROLL イベントを受け取る。wParam パラメータの下位ワードは、トラック バー通知メッセージである。関係するメッセージは、トラック バー アクションの終了時に送信される TB_ENDTRACK、およびユーザーがトラック バーをドラッグ中に継続的に送信される TB_THUMBTRACK である。

次の関数は、これら両方のメッセージを処理する。

void HandleTrackbar(HWND hTrackbar, short int userReq)
{
// ファイルがシーク可能でない場合、トラック バーは無効になる。
// このため、シークはここでは有効である。

static OAFilterState state;
static BOOL bStartOfScroll = TRUE;

if (userReq == TB_ENDTRACK || userReq == TB_THUMBTRACK)
    {
DWORD Position  = SendMessage(hTrackbar, TBM_GETPOS, 0, 0);

// スクロール操作が開始するとポーズする。
if (bStartOfScroll)
        {
pControl->GetState(10, &state);
bStartOfScroll = FALSE;
pControl->Pause();
        }

// 位置を継続的に更新する。
REFERENCE_TIME newTime = (g_rtTotalTime * Position) / 100;
pSeek->SetPositions(&newTime, AM_SEEKING_AbsolutePositioning,
NULL, AM_SEEKING_NoPositioning);

// 最後で状態を復元する。
if (userReq == TB_ENDTRACK)
        {
if (state == State_Stopped)
pControl->Stop();
else if (state == State_Running)
pControl->Run();
bStartOfScroll = TRUE;
        }
    }
}

ユーザーがトラック バーをドラッグするのに合わせてシークを滑らかに行うために、ユーザーがトラック バーを離すまで、アプリケーションはグラフをポーズしている。グラフが実行中であった場合、ポーズ モードでは、ユーザーがコントロールをドラッグしている最中に、グラフの再生を継続できなくなる。グラフが停止していた場合、ポーズ モードでもビデオ ウィンドウが確実に更新される。TB_ENDTRACK メッセージを受け取ると、関数はグラフを当初の状態に復元する。


フィルタのプロパティ ページの表示

プロパティ ページは、ユーザーが設定可能なプロパティをサポートするための 1 つの方法である。ここでは、アプリケーションでフィルタのプロパティ ページを表示する方法を解説し、コンソール アプリケーションのサンプルを示す。このサンプル アプリケーションは、ファイル再生グラフを構築し、グラフ内のフィルタが定義したプロパティ ページを表示してから、ファイルを再生する。

以下の項で構成される。

  • プロパティ ページの表示法
  • サンプル コード

プロパティ ページの詳細については、Platform SDK のドキュメントを参照すること。

プロパティ ページの表示法

プロパティ ページを持つフィルタは、ISpecifyPropertyPages インターフェイスを公開する。フィルタがプロパティ ページを定義しているかどうかを判断するには、QueryInterface を使ってフィルタにこのインターフェイスを照会し、SUCCEEDED マクロを使って戻り値を検査する。以下の例に処理の概要を示す。

IBaseFilter *pFilter;
// フィルタの IBaseFilter インターフェイスを取得する (表示されない)。

ISpecifyPropertyPages *pSpecify;
HRESULT hr = pFilter->QueryInterface(IID_ISpecifyPropertyPages, (void **)&pSpecify);
if (SUCCEEDED(hr)) {
    // ページを表示する。
}

フィルタのインスタンスを (CoCreateInstance を呼び出して) 直接生成した場合は、フィルタへのポインタを既に持っている。そうでない場合は、以下のいずれかの操作を行う。

  • IFilterGraph::EnumFilters メソッドを使って、グラフ内のフィルタを列挙する。以下に示すサンプル コードでは、この方法を用いている。フィルタの列挙の詳細については、「フィルタ グラフ内のオブジェクトの列挙」を参照すること。
  • フィルタ グラフの IFilterGraph::FindFilterByName メソッドを呼び出す。

ISpecifyPropertyPages インターフェイス ポインタが得られれば、ISpecifyPropertyPages::GetPages メソッドを呼び出してフィルタのプロパティ ページを取り出すことができる。このメソッドは、グローバル一意識別子 (GUID) のカウント配列に各プロパティ ページのクラス識別子 (CLSID) を書き込む。カウント配列は CAUUID 構造体で定義される。この構造体は割り当てなければならないが、初期化する必要はない。配列自体はこのメソッドによって割り当てられ、CAUUID 構造体の pElems メンバに格納される。

CAUUID caGUID;
pSpecify->GetPages(&caGUID);
pSpecify->Release();

以下のコードに示すように、OleCreatePropertyFrame 関数によって、モーダル ダイアログ ボックスにプロパティ ページを簡単に表示する手段が提供される。

OleCreatePropertyFrame(
    NULL,                   // 親ウィンドウ
    0,                      // x (予約済み)
    0,                      // y (予約済み)
    FilterInfo.achName,     // ダイアログ ボックスのキャプション
    1,                      // フィルタの数
    (IUnknown **)&pFilter,  // フィルタへのポインタ
    caGUID.cElems,          // プロパティ ページの数
    caGUID.pElems,          // プロパティ ページの CLSID へのポインタ
    0,                      // ロケール識別子
    0,                      // 予約済み
    NULL                    // 予約済み
);

サンプル コードでは、ダイアログ ボックスのキャプションにフィルタの名前を使っている。名前は、フィルタの IBaseFilter::QueryFilterInfo メソッドを呼び出して取得する。詳細については、以下のサンプル コードを参照すること。処理が終わったら、必ず CoTaskMemFree 関数を呼び出して GUID 配列を解放する。

CoTaskMemFree(caGUID.pElems);

サンプル コード

以下のサンプル コードは、コンソール アプリケーションである。これは、コマンドライン引数としてファイル名を受け取り、ファイルを再生するグラフを構築し、グラフ内のフィルタが定義するプロパティ ページを表示し、ファイルを再生する。

#include <dshow.h>
#include <stdio.h>

int main(int argc, char *argv[])
{
    HRESULT  hr;
    WCHAR    wPath[MAX_PATH];
    IGraphBuilder *pGraph = NULL;

    if (argc < 2) {
        printf("Usage: %s movie.ext\n", argv[0]);
        exit(0);
    }
    CoInitialize(NULL);
    CoCreateInstance(CLSID_FilterGraph, NULL, CLSCTX_INPROC_SERVER,
                        IID_IGraphBuilder, (LPVOID *)&pGraph);

    // ファイル名をワイド文字列に変換する。
    MultiByteToWideChar(CP_ACP, 0, argv[1], -1, wPath, MAX_PATH);
    hr = pGraph->RenderFile(wPath, NULL);
    if (FAILED(hr)) {
        printf("Error: Could not open file named %s.\n", argv[1]);
        pGraph->Release();
        CoUninitialize();
        exit(1);
    }

    // フィルタを列挙し、それらのプロパティ ページを表示する。
    IEnumFilters *pEnum;
    IBaseFilter *pFilter = NULL;

    pGraph->EnumFilters(&pEnum);
    while(pEnum->Next(1, &pFilter, NULL) == S_OK)
    {
        ISpecifyPropertyPages *pSpecify;
        hr = pFilter->QueryInterface(IID_ISpecifyPropertyPages, (void **)&pSpecify);
        if (SUCCEEDED(hr)) {
            FILTER_INFO FilterInfo;
            pFilter->QueryFilterInfo(&FilterInfo);

            CAUUID caGUID;
            pSpecify->GetPages(&caGUID);
            pSpecify->Release();

            OleCreatePropertyFrame(
                NULL,                   // 親ウィンドウ
                0,                      // x (予約済み)
                0,                      // y (予約済み)
                FilterInfo.achName,     // ダイアログ ボックスのキャプション
                1,                      // フィルタの数
                (IUnknown **)&pFilter,  // フィルタへのポインタ
                caGUID.cElems,          // プロパティ ページの数
                caGUID.pElems,          // プロパティ ページ CLSID へのポインタ
                0,                      // ロケール識別子
                0,                      // 予約済み
                NULL                    // 予約済み
            );
            CoTaskMemFree(caGUID.pElems);
            FilterInfo.pGraph->Release();
        }
        pFilter->Release();
    }
    pEnum->Release();

// グラフを実行する。
    IMediaControl *pMediaControl = NULL;
    pGraph->QueryInterface(IID_IMediaControl, (void **)&pMediaControl);
    pMediaControl->Run();
    MessageBox(NULL, "Click to end playback.", "DirectShow", MB_OK);

    pMediaControl->Release();
    pGraph->Release();
    CoUninitialize();
    return 0;
}


メディア サンプルの獲得

このトピックでは、サンプル グラバ フィルタを使ってメディア サンプルを取り出す方法を解説する。

Microsoft® DirectShow® アークテクチャでは、アプリケーションがメディア データを直接操作することはない。メディア データの変更が必要な場合は、そのための変換フィルタまたは Microsoft® DirectX® Media Object (DMO) を書く必要がある。一方、ビデオ ファイルからフレームを表示するなど、メディア データを変更せずに使用する必要がある場合は、サンプル グラバ フィルタを使用できる。

このトピックは、以下のセクションで構成される。

  • フィルタ グラフへのサンプル グラバの追加
  • バッファとワンショット モード
  • コールバック メソッドの使用

フィルタ グラフへのサンプル グラバの追加

サンプル グラバは、ISampleGrabber インターフェイスをサポートする変換フィルタである。このフィルタは、すべてのサンプルを変更しないでダウンストリームに送るので、データ ストリームを変更しなくてもフィルタ グラフに挿入できる。サンプル グラバを使用すると、サンプルがフィルタを通過するときにサンプルを獲得できる。

デフォルトでは、サンプル グラバには優先されるメディア タイプはない。サンプル グラバをフィルタ グラフに挿入する前に、ISampleGrabber::SetMediaType メソッドを呼び出して入力ピンのメディア タイプを設定する。メディア タイプを設定することで、フィルタ グラフ マネージャがグラフ内の正しい位置にサンプル グラバを挿入することが保証される。

SetMediaType メソッドは、メディア タイプを記述する AM_MEDIA_TYPE 構造体へのポインタを受け取る。状況に応じて、サブタイプまたはフォーマット タイプを GUID_NULL に設定できる。GUID_NULL は、"未設定" を示す。次の例では、サンプル グラバをフィルタ グラフに追加し、メディア タイプに 24 ビット非圧縮 RGB ビデオを設定している。

#include <dshow.h>
#include <qedit.h>

IBaseFilter     *pF = NULL;
ISampleGrabber  *pGrab = NULL;  // これらは後で必ず解放すること。
AM_MEDIA_TYPE   mt;

CoCreateInstance(CLSID_SampleGrabber, NULL, CLSCTX_INPROC_SERVER,
                    IID_IBaseFilter, (LPVOID *)&pF);
pF->QueryInterface(IID_ISampleGrabber, (void **)&pGrab);

pGraph->AddFilter(pF, L"Grabber");

ZeroMemory(&mt, sizeof(AM_MEDIA_TYPE));
mt.majortype = MEDIATYPE_Video;
mt.subtype = MEDIASUBTYPE_RGB24;
mt.formattype = FORMAT_VideoInfo;
hr = pGrab->SetMediaType(&mt);

これで、グラフの残りの部分を構築し、サンプル グラバ フィルタを接続できる。そのためには、さまざまな方法があるが、その例を次に示す。

  • IGraphBuilder::RenderFile を呼び出す。フィルタ グラフ マネージャは、このメディア タイプに従って、サンプル グラバを接続する。
  • 一度に 1 つずつフィルタを追加し、IGraphBuilder::Connect メソッドを使って接続する。
  • ICaptureGraphBuilder2 インターフェイスを使用する。

たとえば、次のコードでは、Example.avi ファイルの再生グラフが構築される。

pGraph->RenderFile(L"C:\\Example.avi", NULL);

サンプル グラバのメディア タイプは非圧縮ビデオに設定されているので、フィルタ グラフ マネージャは、非圧縮ビデオ サンプルを受け取る場所である、ビデオ デコンプレッサとビデオ レンダラの間にフィルタを配置する。

レンダリングしないでサンプルを獲得したい場合は、サンプル グラバの出力ピンを Null レンダリング フィルタに接続する。このフィルタは、受け取ったサンプルを破棄する。

バッファとワンショット モード

サンプル グラバは、内部バッファに受け取るサンプルをコピーできる。バッファリングを有効にするには、値 TRUE を指定して ISampleGrabber::SetBufferSamples メソッドを呼び出す。サンプルのコピーを取得するには、ISampleGrabber::GetCurrentBuffer メソッドを呼び出す。

各サンプルは、バッファにある以前のサンプルにオーバーライドされる。ストリームの特定のポイントからサンプルを獲得するには、サンプル グラバを "ワンショット" モードに切り替える。ワンショット モードでは、サンプル グラバは 1 つのサンプルを受け取るとすぐにグラフを停止する。ワンショット モードを有効にするには、値 TRUE を指定して ISampleGrabber::SetOneShot メソッドを呼び出す。

目的の時間にシークし、グラフを実行し、グラフが停止するのを待つ。次のコードは、その方法を示している。

// これらのインターフェイス (示されない) についてフィルタ グラフ マネージャに問い合せる。
IMediaControl   *pMediaControl = NULL;
IMediaSeeking   *pSeek = NULL;
IMediaEvent     *pEvent = NULL;

// ワンショット モードを設定する。
pGrab->SetBufferSamples(TRUE);
pGrab->SetOneShot(TRUE);

// 3 秒シークする。
REFERENCE_TIME rtStart = 3 * 10000000;
REFERENCE_TIME rtStop = rtStart;

hr = pSeek->SetPositions(&rtStart, AM_SEEKING_AbsolutePositioning,
                         &rtStop, AM_SEEKING_AbsolutePositioning);

// グラフを実行し、終了を待つ。
long evCode;
hr = pMediaControl->Run();
hr = pEvent->WaitForCompletion(INFINITE, &evCode);

次に、WaitForCompletion メソッドが返り、サンプル グラバのバッファにビデオ フレームのコピーが格納される。バッファには、サンプルのメディア データの部分だけが含まれ、フォーマット ヘッダーは含まれていない。フォーマット ヘッダーを獲得するには、ISampleGrabber::GetConnectedMediaType を呼び出す。このメソッドは、AM_MEDIA_TYPE 構造体を返す。この構造体の pbFormat メンバが、フォーマット ヘッダーを指している。使用後は、必ずバッファ メモリを解放すること。

例として、次のコードはフォーマット ヘッダーとサンプル バッファを使って、ビデオ ストリームからデバイスに依存しないビットマップ (DIB) を作成する。

AM_MEDIA_TYPE MediaType;
pGrab->GetConnectedMediaType(&MediaType);

// ビデオ ヘッダーへのポインタを獲得する。
VIDEOINFOHEADER *pVideoHeader = (VIDEOINFOHEADER*)MediaType.pbFormat;

// ビデオ ヘッダーには、ビットマップ情報が含まれる。
// ビットマップ情報を BITMAPINFO 構造体にコピーする。
BITMAPINFO BitmapInfo;
ZeroMemory(&BitmapInfo, sizeof(BitmapInfo));
CopyMemory(&BitmapInfo.bmiHeader, &(pVideoHeader->bmiHeader), sizeof(BITMAPINFOHEADER));

// ビットマップ ヘッダーから DIB を作成し、バッファへのポインタを獲得する。
void *buffer = NULL;
HBITMAP hBitmap =
    CreateDIBSection(0, &BitmapInfo, DIB_RGB_COLORS, &buffer, NULL, 0);

// イメージをバッファにコピーする。
hr = pGrab->GetCurrentBuffer(NULL, (long *)buffer);

アプリケーションは、BitBlt を呼び出してイメージを表示できる。詳細については、Platform SDK を参照すること。この例ではビデオ ストリームを想定しているが、サンプル グラバはオーディオ サンプルやほかのメディア サンプルを取得できる。イメージをブリットするには、次のようなコードを使用する。

long Width = pVideoHeader->bmiHeader.biWidth;
long Height = pVideoHeader->bmiHeader.biHeight;

HDC hdcDest = GetDC(hwnd);
HDC hdcSrc = CreateCompatibleDC(NULL);
SelectObject(hdcSrc, hBitmap);
BitBlt(hdcDest, 0, 0, Width, Height, hdcSrc, 0, 0, SRCCOPY);

コールバック メソッドの使用

サンプル グラバは、ワンショット モードでの操作の代わりに、受け取るサンプルごとにコールバック メソッドを呼び出すことができる。アプリケーションは ISampleGrabberCB インターフェイスを実装しなければならない。このインターフェイスには、次のメソッドが含まれる。

  • SampleCB: サンプルの IMediaSample インターフェイスへのポインタを受け取る。
  • BufferCB: メディア データが含まれたバッファを受け取る。

通常は、これらのメソッドのうち 1 つだけを実装する。コールバックを設定するには、ISampleGrabber::SetCallback メソッドを呼び出す。このメソッドは、使用するコールバック メソッドを指定するインデックス値をとる。BufferCB メソッドを指定する場合は、前に説明したように、ISampleGrabber::SetBufferSamples も呼び出してバッファリングを有効にする。

次の例では、CGrabCB という名前のクラスにコールバック インターフェイスを実装している。このクラスは、DirectShow SDK に含まれた基底クラスの 1 つである CUnknown から派生している。CUnknown の使用は必須ではないが、これを使うことで、コードがいくらか短くなる。CUnknown の使用の詳細については、「IUnknown の実装方法」を参照すること。

この例では、SampleCB メソッドが、各サンプルの開始タイムをコンソール ウィンドウに出力する。BufferCB メソッドは実装されず、E_NOTIMPL を返す。

#include <streams.h>
// Strmbase.lib にリンクする

class CGrabCB: public CUnknown, public ISampleGrabberCB
{
public:
    DECLARE_IUNKNOWN;

    STDMETHODIMP NonDelegatingQueryInterface(REFIID riid, void **ppv)
    {
        if( riid == IID_ISampleGrabberCB )
        {
            return GetInterface((ISampleGrabberCB*)this, ppv);
        }
        return CUnknown::NonDelegatingQueryInterface(riid, ppv);
    }

    // ISampleGrabberCB のメソッド
    STDMETHODIMP SampleCB(double SampleTime, IMediaSample *pSample)
    {
        printf("Sample time: %f\n", SampleTime);
        return S_OK;
    }

    STDMETHODIMP BufferCB(double SampleTime, BYTE *pBuffer, long BufferLen)
    {
        return E_NOTIMPL;
    }

    // コンストラクタ
    CGrabCB( ) : CUnknown("SGCB", NULL)
    { }
};

このコールバックを使用するには、CGrabCB クラスの新しいインスタンスを生成し、それを ISampleGrabber::SetCallback メソッドに渡す。次に、フィルタ グラフを実行する。

pGrab->SetOneShot(FALSE);
pGrab->SetBufferSamples(FALSE);

CGrabCB *cb = new CGrabCB();
pGrab->SetCallback(cb, 0);


AVI ファイルの再圧縮

このトピックでは、キャプチャ グラフ ビルダを使って AVI (Audio-Video Interleaved) ファイルを再圧縮する方法を解説する。キャプチャ グラフ ビルダは、キャプチャ グラフやその他のカスタム フィルタ グラフを構築する COM オブジェクトである。

注 : Microsoft® DirectShow® に付属するキャプチャ グラフ ビルダには 2 種類のバージョンがある。それぞれ異なるクラス識別子を持ち、異なるインターフェイスを公開する。古い方のバージョンは、CLSID_CaptureGraphBuilder のクラス識別子を持ち、ICaptureGraphBuilder インターフェイスを公開する。これは、既存のアプリケーションとの互換性のためにサポートされている。新しいバージョンは、CLSID_CaptureGraphBuilder2 のクラス識別子を持ち、柔軟性が増した新しい ICaptureGraphBuilder2 インターフェイスを公開する。

ビデオ キャプチャ アプリケーションでの ICaptureGraphBuilder2 の使用については、「キャプチャ アプリケーションの書き方」を参照すること。ここでは、ICaptureGraphBuilder2 を使って、メディア データをソース ファイルから出力ファイルにコピーし、その途中でデータを再圧縮する。

このトピックは、以下のセクションで構成される :

  • グラフの作成
  • レンダリング セクションの構築
  • ソース フィルタの接続
  • ファイルの書き込み
  • サンプル コード

グラフの作成

まず、以下の例に示すように、キャプチャ グラフ ビルダのインスタンスを生成する。

ICaptureGraphBuilder2   *pBuild = NULL;
CoCreateInstance(CLSID_CaptureGraphBuilder2, NULL, CLSCTX_INPROC,
        IID_ICaptureGraphBuilder2, (void **)&pBuild);

キャプチャ グラフ ビルダは、自動的にフィルタ グラフ マネージャを作成する。最初はフィルタ グラフは空で、フィルタを持っていない。フィルタ グラフは、以下の 2 段階の処理で構築する。

  1. グラフのレンダリング セクションを構築する。このセクションには、AVI MUX フィルタとファイル ライタが含まれる。MUX フィルタは、ビデオ ストリームとオーディオ ストリームを、ファイル ライタ用の 1 つの AVI ストリームに結合する。
  2. ファイル ソース フィルタをグラフに追加し、それを MUX フィルタに接続する。キャプチャ グラフ ビルダは、ファイル フォーマットを解析するために必要なスプリッタ フィルタとデコーダ フィルタを挿入する。必要な場合は、オーディオおよびビデオ ストリームを、オーディオおよびビデオ圧縮フィルタに通すこともできる。

レンダリング セクションの構築

グラフのレンダリング セクションを構築するには、ICaptureGraphBuilder2::SetOutputFileName メソッドを呼び出す。このメソッドは、出力のメディア サブタイプと出力ファイルの名前を指定する入力パラメータを受け取り、MUX フィルタとファイル ライタへのポインタが格納された出力パラメータを返す。MUX フィルタへのポインタは、グラフ構築の次の段階で必要になる。ファイル ライタへのポインタはこの例では必要ないので、NULL にすることができる。コードを短く保つために、以下の例ではファイル名にリテラル文字列を使用している。

IBaseFilter *pMux = NULL;
pBuild->SetOutputFileName(
        &MEDIASUBTYPE_Avi,  // ファイル タイプ。
        L"Output.avi",// ファイル名。
        &pMux,              // マルチプレクサへのポインタを受け取る。
        NULL);                  // ファイル ライタへのポインタを受け取る。

このメソッドが返ると、MUX フィルタへのポインタの参照カウントが大きくなっているので、アプリケーションは終了時にポインタを解放しなければならない。MUX フィルタは、AVI フォーマットを制御するために以下のインターフェイスを公開している。

  • IConfigInterleaving には、インターリーブ モードを設定するためのメソッドが含まれる。
  • IConfigAviMux には、マスター ストリームと AVI 互換性インデックスを設定するためのメソッドが含まれる。

次の図は、現状のフィルタ グラフを示す。

フィルタ グラフのレンダリング セクション

ソース フィルタの接続

次の作業は、グラフの残りの部分へのソース フィルタの接続である。まず、ICaptureGraphBuilder2::GetFiltergraph メソッドを呼び出して、フィルタ グラフの IGraphBuilder インターフェイスへのポインタを取得する。次に、IGraphBuilder::AddSourceFilter メソッドを呼び出す。このメソッドは、ファイルをロードし、ファイル ソース フィルタへのポインタを取得する。

IGraphBuilder   *pGraph = NULL;
IBaseFilter     *pSrc = NULL;

pBuild->GetFiltergraph(&pGraph);
pGraph->AddSourceFilter(L"C:\\Input.avi", L"Source Filter", &pSrc);

次に、ファイルの再圧縮に使用するビデオおよびオーディオ圧縮フィルタのインスタンスを生成する。1 つの方法として、ユーザーのシステムにある圧縮デバイスを列挙して、ユーザーがデバイスを選択するようにできる。この方法については、「デバイスとフィルタの列挙」を参照すること。別の方法として、使いたい圧縮フィルタがある場合は、CoCreateInstance を呼び出してそのインスタンスを直接生成することもできる。圧縮フィルタのインスタンスを生成したら、IFilterGraph::AddFilter を呼び出してインスタンスをフィルタ グラフに追加する。

以下の例では、ビデオを圧縮する AVI Compressor フィルタのインスタンスを生成している。オーディオは圧縮しないままにしてある。

CoCreateInstance(CLSID_AVICo, NULL, CLSCTX_INPROC,
        IID_IBaseFilter, (void **)&pVComp);
pGraph->AddFilter(pVComp, L"Compressor");

次の図に示すように、まだソース フィルタと圧縮フィルタは、グラフ内のほかのものとは接続されていない。

ソース フィルタと圧縮フィルタを伴うフィルタ グラフ

グラフ構築の最後のステップは、ICaptureGraphBuilder2::RenderStream メソッドを使ったビデオおよびオーディオ ストリームのレンダリングである。このメソッドは、ソース フィルタの出力ピンをグラフのレンダリング セクションに接続し、オプションが指定されれば圧縮フィルタを通す。

ICaptureGraphBuilder2 のメソッドは、プレビューおよびキャプチャ用に別々の出力ピンを持てるビデオ カメラなど、生のキャプチャ ソースを扱えるようにデザインされている。そういう状況では、RenderStream の最初の 2 つのパラメータで、ピン カテゴリとメディア タイプを指定することで、どのピンを接続するかを指定する。ファイル ソース フィルタを使用する場合、出力ピンは 1 つだけなので、これらのパラメータを指定する必要はない。

その次の 3 つのパラメータは、ソース フィルタ (または、ソース フィルタのピン)、圧縮フィルタ、およびシンク フィルタへのポインタである。ファイルに書き込む場合は、これらの最後のパラメータはマルチプレクサへのポインタでなければならない。

以下のコードは、ビデオ コンプレッサを介してビデオ ストリームをレンダリングする。

pBuild->RenderStream(
        NULL,       // 出力ピンのカテゴリ
        NULL,       // メディア タイプ
        pSrc,       // ソース フィルタ
        pVComp,     // コンプレッサ フィルタ
        pMux);      // シンク フィルタ (AVI Mux)

次の図は、現状のフィルタ グラフを示す。

この図では、ソース ファイルに 2 つのストリーム、すなわちオーディオ ストリームとビデオ ストリームがあると仮定している。その場合、AVI スプリッタ フィルタにはオーディオ ストリーム用の出力ピンが含まれるが、ピンはグラフ内の何にも接続されていない。オーディオ ストリームをレンダリングするには、RenderStream をもう一度呼び出す。

pBuild->RenderStream(NULL, NULL, pSrc, NULL, pMux);

ソース フィルタの唯一の出力ピンは既に接続されているので、RenderStream メソッドはスプリッタ フィルタの未接続の出力ピンを探す。次に、オーディオ出力ピンを見つけ、それを MUX フィルタに直接接続する。ソース ファイルにビデオ ストリームだけがあって、オーディオ ストリームがない場合、2 回目の RenderStream の呼び出しは予想どおり失敗する。しかし、RenderStream への最初の呼び出しでグラフは完成するので、2 回目の呼び出しが失敗しても問題はない。グラフは実行される。

次の図は、完成したフィルタ グラフを示す。

この例では、2 回の呼び出しの順序が重要である。ビデオ ストリームは再圧縮されるが、オーディオ ストリームは再圧縮されないためである。最初の呼び出しにはビデオ コンプレッサが含まれているので、ビデオ ストリームが指定される。2 回目の呼び出しにはコンプレッサが含まれないので、どのストリーム タイプにも適用できる。残っているのはオーディオ ストリームだけなので、この呼び出しは正しく機能する。

ただし、以下に示すように、この順序が入れ替わったとする。

pBuild->RenderStream(NULL, NULL, pSrc, NULL, pMux);
// 間違い。これによってビデオ ストリームがレンダリングされることもある。

pBuild->RenderStream(NULL, NULL, pSrc, pVComp, pMux);
// すると、これは失敗する。

この例では、2 回目の呼び出しでコンプレッサが指定されている。最初の呼び出しによって、ビデオ ストリームとオーディオ ストリームのどちらがレンダリングされるかは未確定であるが、ビデオ ストリームがレンダリングされれば、2 回目の呼び出しは失敗する。

一方、この例でビデオ コンプレッサとオーディオ コンプレッサの両方が使用された場合、順序は問題ではなくなる。それぞれの呼び出しによって、どちらかのストリームが完全に指定されるためである。同じような理由で、圧縮フィルタを使用しない場合も、順序は問題ではなくなる。その場合、2 つの呼び出しは同じになる。

ソース ファイルに 3 つ以上のストリームがある場合、フィルタ グラフは正しく構築されず、予期しない動作を示す。こういう状況はまれであるが、安全のため、最初のストリームをレンダリングした後、スプリッタ フィルタの出力ピンを列挙する必要がある。詳細については、「フィルタ グラフ内のオブジェクトの列挙」を参照すること。

ファイルの書き込み

ファイルを書き込む前に、圧縮フィルタのプロパティを設定できる。サンプル コードには、ビット レートとキー フレーム レートを設定する方法を示している。詳細については、後のサンプル コードを参照すること。

ファイルを書き込むには、フィルタ グラフを実行し、IMediaControl::Run メソッドを呼び出し、再生が終了するのを待ってから、IMediaControl::Stop を呼び出してグラフを明示的に停止しなければならない。停止しないと、ファイルは正しく書き込まれない。詳細については、「イベントへの応答」を参照すること。

ファイル書き込み処理の進行状況を表示するには、IMediaSeeking インターフェイスに関して MUX フィルタに問い合せる。IMediaSeeking::GetDuration メソッドを呼び出し、ファイルの時間幅を取得する。グラフの実行中は、定期的に IMediaSeeking::GetCurrentPosition メソッドを呼び出し、ストリームでのグラフの現在位置を取得する。現在位置を時間幅で割ると、完了した割合が得られる。

注 : 通常、アプリケーションは IMediaSeeking に関してはフィルタ グラフ マネージャに問い合わせるべきであり、個別のフィルタにも問い合わせるべきでない。ファイルの書き込みは、この規則の例外である。フィルタ グラフ マネージャは、フィルタから現在位置を取得しない。その代わり、開始位置と、グラフの実行時間を基にして位置を計算する。ファイルの書き込みでは、これによって間違った結果が生じることもある。これは、ファイルの書き込み時間がファイルの時間幅よりも長くなることがあるためである。MUX フィルタから位置を取得すると、正確な結果が得られる。

サンプル コード

より簡潔にするため、以下のコードではエラー チェックは行われない。

#include <dshow.h>
#include <stdio.h>

void __cdecl main(void)
{
    ICaptureGraphBuilder2   *pBuild = NULL;
    IGraphBuilder           *pGraph = NULL;
    IBaseFilter             *pSrc = NULL;       // ソース フィルタ
    IBaseFilter             *pMux = NULL;       // MUX フィルタ
    IBaseFilter             *pVComp = NULL;     // ビデオ コンプレッサ フィルタ

    CoInitialize(NULL);

    // キャプチャ グラフ ビルダを作成する。
    CoCreateInstance(CLSID_CaptureGraphBuilder2, NULL, CLSCTX_INPROC,
            IID_ICaptureGraphBuilder2, (void **)&pBuild);

    // グラフのレンダリング セクションを作成する。
    pBuild->SetOutputFileName(
            &MEDIASUBTYPE_Avi,  // ファイル タイプ。
            L"C:\\Output.avi",          // ファイル名。
            &pMux,              // マルチプレクサへのポインタを受け取る。
            NULL);                  // ファイル ライタへのポインタを受け取る。

    // ソース ファイルをロードする。
    pBuild->GetFiltergraph(&pGraph);
    pGraph->AddSourceFilter(L"C:\\Input.avi", L"Source Filter", &pSrc);

    // コンプレッサ フィルタを追加する。
    CoCreateInstance(CLSID_AVICo, NULL, CLSCTX_INPROC,
            IID_IBaseFilter, (void **)&pVComp);
    pGraph->AddFilter(pVComp, L"Compressor");

    // コンプレッサを介してビデオ ストリームをレンダリングする。
    pBuild->RenderStream(
            NULL,       // 出力ピンのカテゴリ
            NULL,       // メディア タイプ
            pSrc,       // ソース フィルタ
            pVComp,     // コンプレッサ フィルタ
            pMux);      // シンク フィルタ (AVI Mux)

    // オーディオ ストリームをレンダリングする。
    pBuild->RenderStream(NULL, NULL, pSrc, NULL, pMux);

    // ビデオ圧縮プロパティを設定する。
    IAMStreamConfig         *pStreamConfig = NULL;
    IAMVideoCompression     *pCompress = NULL;

    // 100k/秒のデータ レートで圧縮する。
    AM_MEDIA_TYPE *pmt;
    pBuild->FindInterface(NULL, NULL, pVComp, IID_IAMStreamConfig, (void **)&pStreamConfig);
    pStreamConfig->GetFormat(&pmt);
    if (pmt->formattype == FORMAT_VideoInfo)
    {
        ((VIDEOINFOHEADER *)(pmt->pbFormat))->dwBitRate = 100000;
        pStreamConfig->SetFormat(pmt);
    }
    DeleteMediaType(pmt);

    // 4 つのフレームごとにキー フレームを要求する。
    pStreamConfig->QueryInterface(IID_IAMVideoCompression, (void **)&pCompress);
    pCompress->put_KeyFrameRate(4);
    pCompress->Release();
    pStreamConfig->Release();

// グラフを実行する。
    IMediaControl           *pControl = NULL;
    IMediaSeeking   *pSeek = NULL;
    IMediaEvent             *pEvent = NULL;
    pGraph->QueryInterface(IID_IMediaControl, (void **)&pControl);
    pGraph->QueryInterface(IID_IMediaEvent, (void **)&pEvent);

    HRESULT hr = pMux->QueryInterface(IID_IMediaSeeking, (void**)&pSeek);

    pControl->Run();
    printf("Recompressing... \n");
    long evCode;

    if (SUCCEEDED(hr))  // IMediaSeeking がサポートされる
    {
        REFERENCE_TIME rtTotal, rtNow = 0;
        pSeek->GetDuration(&rtTotal);
        while ((pEvent->WaitForCompletion(1000, &evCode)) == E_ABORT)
        {
            pSeek->GetCurrentPosition(&rtNow);
            printf("%d%%\n", (rtNow * 100)/rtTotal);
        }
        pSeek->Release();
    }
    else  // 進行状況を更新できない。
    {

    pEvent->WaitForCompletion(INFINITE, &evCode);
    pControl->Stop();
    printf("All done\n");

    pSrc->Release();
    pMux->Release();
    pVComp->Release();
    pControl->Release();
    pEvent->Release();
    pBuild->Release();
    pGraph->Release();
    CoUninitialize();
}


DirectShow リファレンス

このトピックでは、Microsoft® DirectShow® のリファレンス情報を紹介する。

  • フィルタ
  • インターフェイス
  • 構造体
  • 列挙型
  • 定数と GUID
  • 関数
  • MSWebDVD ActiveX コントロール
  • プロパティ セット
  • DirectShow のコンポーネント
  • DirectShow 基底クラス


フィルタ

Microsoft® DirectShow® では、Microsoft® Windows® と共に自動的にインストールされる、デフォルト フィルタの集まりが提供される。これらのフィルタは、数多くのデータ フォーマットをサポートすると同時に、高いハードウェア非依存性を提供する。アプリケーションは、目的のシステムにカスタム フィルタを登録、インストールできる。以下に、デフォルトのフィルタを示す。

  • ACM ラッパー
  • アナログ ビデオ クロスバー
  • ASF ライタ
  • ASF リーダー
  • オーディオ キャプチャ
  • オーディオ レンダリング
  • AVI コンプレッサ
  • AVI デコンプレッサ
  • AVI ドロー
  • AVI Mux
  • AVI スプリッタ
  • BDA IP シンク
  • BDA MPE フィルタ
  • BDA ネットワーク プロバイダ
  • BDA SLIP デフレーマ
  • BDA MPEG2 トランスポート情報フィルタ
  • CC デコーダ
  • カラー スペース変換
  • デフォルト DirectSound デバイス
  • DMO ラッパー
  • DV Muxer
  • DV スプリッタ
  • DV ビデオ デコーダ
  • DV ビデオ エンコーダ
  • DVD ナビゲータ
  • ファイル ソース (Async)
  • ファイル ソース (URL)
  • ファイル ライタ
  • フルスクリーン レンダリング
  • インフィニット ピン ティー
  • 内部スクリプト コマンド レンダリング
  • Line 21 デコーダ
  • MIDI パーサー
  • MIDI レンダリング
  • MJPEG コンプレッサ
  • MJPEG デコンプレッサ
  • MPEG-1 オーディオ デコーダ
  • MPEG-1 ストリーム スプリッタ
  • MPEG-1 ビデオ デコーダ
  • MPEG-2 デマルチプレクサ
  • MPEG-2 スプリッタ
  • MSYUV カラー スペース変換 CODEC
  • NABTS/FEC CODEC フィルタ
  • Null レンダリング
  • オーバーレイ ミキサー
  • オーバーレイ ミキサー 2
  • QT デコンプレッサ
  • QuickTime ムービー パーサー>
  • SAMI (CC) パーサー
  • サンプル グラバ
  • スマート ティー
  • Tee/Sink-to-Sink コンバータ
  • TV オーディオ
  • TV チューナー
  • VBI サーフェイス アロケータ
  • VFW キャプチャ フィルタ
  • VGA 16 色 ディザラ
  • ビデオ レンダリング
  • WAVE パーサー
  • WDM ビデオ キャプチャ
  • WST CODEC
  • WST デコーダ


ACM ラッパー フィルタ

ACM ラッパー フィルタは、Audio Compression Manager (ACM) を使用する CODEC が Microsoft® DirectShow® フィルタ グラフに結合するのを可能にする。展開は、PCM オーディオに対してのみ行われる。コンプレッサをラッピングする場合、このフィルタはオーディオ コンプレッサ カテゴリとみなされ、追加のインターフェイスをサポートすることができる。このフィルタはフィルタ グラフ マネージャによって自動的に使用されるので、手作業でグラフに追加する必要はない。このフィルタは、再生またはサンプル レートの変換にのみ使用される。

フィルタ インターフェイス | IBaseFilter、IPersistPropertyBag
入力ピン メディア タイプ | MEDIATYPE_Audio、MEDIASUBTYPE_NULL、FORMAT_WaveFormatEx
入力ピン インターフェイス | IMemInputPin、IPin、IQualityControl
出力ピン メディア タイプ MEDIATYPE_Audio、MEDIASUBTYPE_PCM、FORMAT_WaveFormatEx

以下の任意の組み合わせが可能。

  • 1 秒あたりのサンプル数 (kHz) : 44.1、22.05、11.025、または 8.0
  • チャンネル : ステレオまたはモノ
  • 1 サンプルあたりのビット数 : 8 または 16
出力ピン インターフェイス | IAMStreamConfig、IMediaPosition、IMediaSeeking、IPin、IQualityControl
フィルタ CLSID | CLSID_ACMWrapper
プロパティ ページ CLSID | プロパティ ページなし。
実行モジュール | Quartz.dll
メリット | MERIT_NORMAL
カテゴリ | CLSID_AudioCompressorCategory


アナログ ビデオ クロスバー フィルタ

アナログ ビデオ クロスバー フィルタは、Windows® ドライバ モデル(WDM) をサポートするビデオ キャプチャ デバイスで、ビデオ クロスバーと同じ働きをする。1 つの出力ストリームは、アナログ ベースバンド ビデオのハードウェア パスを表す。入力ピン の 1 つは TV チューナー (TV チューナー フィルタ) から入力される。ほかの入力ピンは、ビデオ ストリームをサポートする。そのフィルタは、ダウンストリーム接続でサポートされている、すべてのメディア サブタイプとフォーマットをサポートする。

アナログ ビデオ クロスバー フィルタは、所定のソース選択に使用される IAMCrossbar インターフェイスを公開する。

このフィルタは、Windows 98 および Windows® 2000 において利用できる。
フィルタ インターフェイス | IAMCrossbar, ISpecifyPropertyPages, IPersistPropertyBag, IPersistStream
入力ピン メディア タイプ | MEDIATYPE_AnalogAudio, MEDIATYPE_AnalogVideo
入力ピン インターフェイス | IKsPropertySet
出力 ピン メディア タイプ | MEDIATYPE_AnalogAudio, MEDIATYPE_AnalogVideo
出力ピン インターフェイス | IKsPropertySet
フィルタ CLSID | CLSID_CrossbarFilter
プロパティ ページ CLSID | CLSID_CrossbarFilterPropertyPage
実行モジュール | ksxbar.ax
メリット | ドライバに依存する。
カテゴリ | AM_KSCATEGORY_CROSSBAR


ASF ライタ フィルタ

ASF ライタは、可変数の入力ストリームを受け入れて ASF (Advanced Streaming Format) ファイルを作成する。このフィルタは、圧縮と多重化を取り扱う。ただし、圧縮メカニズムはバイパスすることができる。ASF ライタは、デジタル ビデオ (DV) キャプチャ、オーディオ再圧縮、およびネットワーク ストリーミング用の AVI (Audio-Video Interleaved) ファイルまたは MPEG マルチメディア ファイルの変換など、各種のシナリオで使用することができる。このフィルタは、Microsoft® DirectShow® の Microsoft® Windows Media™ Audio ファイルおよび Windows Media Video ファイルを作成する唯一の方法を提供する。

ASF ファイルの記述方法については、「DirectShow での ASF ファイルの作成」を参照すること。

フィルタ インターフェイス | IAMFilterMiscFlags、 IConfigAsfWriter、 IFileSinkFilter2、 IMediaSeeking、 IPersistStream、 ISpecifyPropertyPages
入力ピン インターフェイス | IPin、IMemInputPin IAMStreamConfig
出力ピン メディア タイプ | 利用できない。
出力ピン インターフェイス | 利用できない。
フィルタ CLSID | CLSID_WWAsfWriter
プロパティ ページ CLSID | CLSID_AsfWriterProperties
実行モジュール | Qasf.dll
メリット | MERIT_DO_NOT_USE
カテゴリ | 指定なし。

注意

このフィルタには、Windows Media Format Software Development Kit (SDK) の有効なインストールが必要である。

入力ピンの数は、ASF ストリームのプロファイルまたはプロファイル識別子に応じて異なる。

入力ピン上でサポートされる IAMStreamConfig のメソッドは、IAMStreamConfig::GetFormat だけである。ほかのすべてのメソッドは E_NOTIMPL を返す。GetFormat を呼び出し、フィルタの構成に使用された ASF プロファイルに基づいて、ストリームのフォーマットを判定する。詳細については、「IConfigAsfWriter)」を参照すること。


ASF リーダー フィルタ

ASF ファイルの名前が与えられると、ASF リーダーはディスクからファイルを読み取り、圧縮されたストリームを解析し、それぞれに出力ピンを公開する。通常、このフィルタは、展開を行うオーディオまたはビデオ CODEC フィルタに接続する。ASF ファイルがシーク可能な場合はシークがサポートされる。ASF リーダーは、ストリームをダウンストリームに送る前にサンプルにタイム スタンプを設定する。

このフィルタは、Microsoft® Windows Media™ Software Development Kit (SDK) が必要である。このフィルタは、ASF ファイルのデフォルトのソース フィルタではない。このフィルタは、クラス識別子 (CLSID) を使用して明示的にグラフに追加する必要がある。このフィルタは、Microsoft® DirectShow® の IFileSourceFilter インターフェイスおよび Windows Media SDK の IWMHeaderInfo インターフェイスを公開する。

これは、ファイル再生用の一般的な ASF フィルタ グラフである。

フィルタ インターフェイス | IFileSourceFilter、IWMHeaderInfo
入力ピン メディア タイプ | 利用できない。
入力ピン インターフェイス | 利用できない。
出力ピン メディア タイプ | ASF ファイル内のストリームに応じて異なる。
出力ピン インターフェイス | IMediaSeeking
フィルタ CLSID | CLSID_WMAsfReader {187463A0-5BB7-11d3-ACBE-0080C75E246E}
プロパティ ページ CLSID | プロパティ ページなし。
実行モジュール | Qasf.dll
メリット | MERIT_UNLIKELY
カテゴリ | CLSID_LegacyAmFilterCategory


オーディオ キャプチャ フィルタ

オーディオ キャプチャ フィルタは、オーディオ キャプチャ デバイスを表す。オーディオ キャプチャ フィルタには、1 つのキャプチャ 出力ピンと (LineIn、Mic、CD、MIDI などのカード上の入力のタイプごとに 1 つの) 複数の入力ピンがある。

このフィルタは、複数のハードウェア デバイスに対して使用できる。システム デバイス 列挙子は、このフィルタを使用できるそれぞれのデバイスに対して一意なモニカを返す。フレンドリ名はデバイスの名前に対応する (これは、GraphEdit に表示される名前である)。詳細については、「デバイスとフィルタの列挙」を参照すること。

フィルタ インターフェイス | IAMAudioInputMixer、IAMFilterMiscFlags、IAMResourceControl、IBaseFilter、 IPersistPropertyBag、ISpecifyPropertyPages
入力ピン メディア タイプ | MEDIATYPE_AnalogAudio、MEDIASUBTYPE_NULL
入力ピン インターフェイス | IAMAudioInputMixer、IMemInputPin、IPin、IQualityControl
出力ピン メディア タイプ | MEDIATYPE_Audio、MEDIASUBTYPE_NULL
出力ピン インターフェイス | IAMBufferNegotiation、IAMPushSource、IAMStreamConfig、IAMStreamControl、IKsPropertySet、IPin、IQualityControl
フィルタ CLSID | CLSID_AudioRecord
プロパティ ページ CLSID | CLSID_AudioInputMixerProperties
実行モジュール | qcap.dll
メリット | MERIT_DO_NOT_USE
カテゴリ | CLSID_AudioInputDeviceCategory

注意

入力ピンは物理ハードウェア接続を表し、DirectShow のほかのフィルタに接続されることはない。


オーディオ レンダリング フィルタ

オーディオ レンダリング フィルタは汎用オーディオ レンダリング フィルタで、非同期ファイル ソース、ファイル ソース (URL)、MPEG-1 ストリーム スプリッタ、AVI スプリッタ、WAVE パーサー、またはその他のオーディオ変換フィルタが WAV オーディオを含んでいる場合に、その出力に接続することができる。このフィルタは、オーディオ ストリームのサブタイプをチェックしない。フォーマット ブロックで渡される WAVEFORMAT または WAVEFORMATEX 構造には、このフィルタへの接続に必要な情報が入っている。

このフィルタはオーディオ ドライバに依存するある幅のサンプル レートをサポートする。

フィルタ インターフェイス | IAMDirectSound、IAMResourceControl、IBaseFilter、IBasicAudio、IMediaPosition、IMediaSeeking、IPersistPropertyBag、IPersistStream、IQualityControl、IReferenceClock,
入力ピン メディア タイプ | MEDIATYPE_Audio
入力ピン インターフェイス | IMemInputPin、IPin、IPinConnection、IQualityControl
出力ピン メディア タイプ | 利用できない。
出力ピン インターフェイス | 利用できない。
フィルタ CLSID | CLSID_AudioRender
プロパティ ページ CLSID | CLSID_AudioProperties、CLSID_AudioRendererAdvancedProperties
実行モジュール | quartz.dll
メリット | MERIT_PREFERRED
カテゴリ | CLSID_AudioRendererCategory


AVI コンプレッサ フィルタ

AVI コンプレッサは、Video Compression Manager (VCM) インターフェイスをサポートするインストール可能なビデオ コンプレッサのラッパー フィルタである。VCM インターフェイスは DirectShow アーキテクチャには含まれていないので、これらのコンプレッサがフィルタ グラフのコンテキスト内で機能するためには "ラッパー フィルタ" が必要となる。AVI コンプレッサは、圧縮 AVI ファイルを新しく作成したり既存の AVI ファイルを再圧縮するグラフにおいて使用される。キャプチャ グラフ ビルダに対してこのフィルタをキャプチャ グラフに追加するよう指示することができる。

AVI コンプレッサの入力ピンは、展開されたビデオ データを渡すフィルタにアップストリームを接続する。このようなフィルタには、VFW キャプチャ フィルタや WDM ビデオ キャプチャ フィルタ (どちらもハードウェア ビデオ ソースをラッピングする)、AVI スプリッタ、カラー スペース変換などの、展開されたビデオ データを処理できるフィルタが含まれる。通常、AVI コンプレッサのダウンストリーム ピンは、圧縮ビデオと ACM ラッパー フィルタからの圧縮オーディオ ストリームをインターリーブする AVI MUX フィルタに接続される。AVI コンプレッサが VCM と一緒に動作するのと同様に、ACM ラッパーは Audio Compression Manager と一緒に動作する。

コンプレッサにプロパティ ページが用意されていて、ユーザーが各種の圧縮パラメータを設定できるようになっている場合、アプリケーションは AVI コンプレッサの IAMVfwCompressDialogs インターフェイスを使用してそれを表示することができる。

注 : MPEG コンプレッサおよびデコンプレッサは VCM CODEC としては実装されずに、ネイティブ DirectShow フィルタとしてのみ実装される。同様に、DirectShow で提供される Intel® Indeo® コンプレッサおよびデコンプレッサも VCM CODEC としてではなくネイティブ フィルタとして実装される。

フィルタ インターフェイス | IAMVfwCompressDialogs、IBaseFilter、IPersistPropertyBag、ISpecifyPropertyPages
入力ピン メディア タイプ | MEDIATYPE_Video、MEDIASUBTYPE_NULL
入力ピン インターフェイス | IMemInputPin、IPin、IQualityControl
出力ピン メディア タイプ | MEDIATYPE_Video、MEDIASUBTYPE_NULL
出力ピン インターフェイス | IAMStreamConfig、IAMVideoCompression、IMediaPosition、IMediaSeeking、IPin、IQualityControl
フィルタ CLSID | CLSID_AVICo
プロパティ ページ CLSID | プロパティ ページなし。
実行モジュール | qcap.dll
メリット | MERIT_DO_NOT_USE
カテゴリ | CLSID_VideoCompressorCategory


AVI デコンプレッサ フィルタ

AVI デコンプレッサは、Video Compression Manager (VCM) インターフェイスをサポートするインストール可能なビデオ コンプレッサのラッパー フィルタである。VCM インターフェイスは DirectShow アーキテクチャには含まれていないので、これらのコンプレッサがフィルタ グラフのコンテキスト内で機能するためには "ラッパー フィルタ" が必要になる。

AVI ファイルをレンダリングするためのグラフを作成するとき、フィルタ グラフ マネージャはファイルの AVI ヘッダー内の FOURCC をチェックしてそのビデオ ストリームが圧縮されているかどうかを判定する。圧縮されている場合、フィルタ グラフ マネージャは AVI デコンプレッサを追加する。AVI デコンプレッサは、当該ファイルを処理できる、インストールされているデコンプレッサをレジストリから探す (ただし Intel® Indeo® 圧縮スキームで AVI ファイルが圧縮されている場合は、AVI デコンプレッサの代わりにネイティブ Indeo DirectShow フィルタがグラフに使用される)。この処理はすべて自動的に行われるので、アプリケーション側は詳細に関して責任を負う必要はない。

アップストリーム ピンでは、AVI デコンプレッサは一般に AVI スプリッタに接続する。出力ピンでは、AVI デコンプレッサは一般に ビデオ レンダラに接続する。
フィルタ インターフェイス | IBaseFilter
入力ピン メディア タイプ | MEDIATYPE_Video、MEDIASUBTYPE_NULL、FORMAT_VideoInfo サブタイプは古いフォーマットの FOURCC に対応する必要がある (詳細については、「FOURCCMap クラス」を参照すること)。
入力ピン インターフェイス | IMemInputPin、IPin、IQualityControl
出力ピン メディア タイプ | MEDIATYPE_Video、MEDIASUBTYPE_NULL、FORMAT_VideoInfo
出力ピン インターフェイス | IMediaPosition、IMediaSeeking、IPin、IQualityControl
フィルタ CLSID | CLSID_AVIDec
プロパティ ページ CLSID | プロパティ ページなし。
実行モジュール | quartz.dll
メリット | MERIT_NORMAL
カテゴリ | CLSID_LegacyAmFilterCategory

注意

ピン上のメディア サブタイプは、AVI ファイル内の FourCC コードから作成される。


AVI ドロー フィルタ

AVI ドローは、外部 NTSC テレビ モニタにビデオを出力するときに AVI デコンプレッサの代わりに自動的に再生グラフに使用される。

フィルタ インターフェイス | IBaseFilter
入力ピン メディア タイプ MEDIATYPE_Video、FORMAT_VideoInfo

次のサブタイプが有効
  • MEDIASUBTYPE_MJPG
  • MEDIASUBTYPE_TVMJ
  • MEDIASUBTYPE_WAKE
  • MEDIASUBTYPE_CFCC
  • MEDIASUBTYPE_IJPG
  • MEDIASUBTYPE_Plum
  • MEDIASUBTYPE_DVCS
  • MEDIASUBTYPE_DVSD
  • MEDIASUBTYPE_MDVF
入力ピン インターフェイス | IMemInputPin、IPin、IQualityControl
出力ピン メディア タイプ | MEDIATYPE_Video、MEDIASUBTYPE_NULL
出力ピン インターフェイス | IMediaPosition、IMediaSeeking、IOverlayNotify、IPin、IQualityControl
フィルタ CLSID | CLSID_AVIDraw
プロパティ ページ CLSID | プロパティ ページなし。
実行モジュール | quartz.dll
メリット | MERIT_NORMAL + 100
カテゴリ | CLSID_LegacyAmFilterCategory

注意

AVI ドロー フィルタと VFW キャプチャ フィルタはどちらも同じハードウェアに接続するので、同じフィルタ グラフ内で使用することはできない。


AVI Mux フィルタ

AVI Mux は複数の入力ストリームを受け取ってそれらを AVI フォーマットにインターリーブする。ビデオ キャプチャ アプリケーションやオーサリング アプリケーションは、AVI Mux フィルタを使用してファイルを AVI フォーマットでディスクに保存することができる。通常、このフィルタはファイル ライタ フィルタに接続されるが、入力ピンで IStream および IMemInputPin をサポートする任意のフィルタに接続することができる。AVI Mux フィルタは、それぞれの入力ストリームに対して別の入力ピンを作成する。

フィルタ インターフェイス | IBaseFilter、IConfigAviMux、IConfigInterleaving、IMediaSeeking、IPersistMediaPropertyBag、ISpecifyPropertyPages
入力ピン メディア タイプ 古いフォーマットの FOURCC に対応するメジャー タイプ、または MEDIATYPE_AUXLine21Data (詳細については、「FOURCCMap クラス」を参照すること)。
  • メジャー タイプが MEDIATYPE_Audio である場合、フォーマットは FORMAT_WaveFormatEx でなければならない。
  • メジャー タイプが MEDIATYPE_Video である場合、フォーマットは FORMAT_VideoInfo または FORMAT_DvInfo でなければならない。
  • メジャー タイプが MEDIATYPE_Interleaved である場合、フォーマットは FORMAT_DvInfo でなければならない。
入力ピン インターフェイス | IAMStreamControl、IMemInputPin、IPin、IQualityControl
出力ピン メディア タイプ | MEDIATYPE_Stream、MEDIASUBTYPE_avi
出力ピン インターフェイス | IPin、IPinFlowControl、IQualityControl
フィルタ CLSID | CLSID_AviDest
プロパティ ページ CLSID | CLSID_AviMuxProptyPage、CLSID_AviMuxProptyPage1
実行モジュール | qcap.dll
メリット | MERIT_DO_NOT_USE
カテゴリ | CLSID_LegacyAmFilterCategory
メディア | なし。

注意

このフィルタは複数の入力ピンと 1 つの出力ピンを持つ。


AVI スプリッタ フィルタ

AVI スプリッタ フィルタは、AVI ファイルの再生に使用する。AVI スプリッタ フィルタは、AVI フォーマットのデータを受け取り、それを構成ストリームに分割して以降の処理やレンダリングに利用できるようにする。このフィルタは IAsyncReader をサポートする出力ピンを持つ任意のフィルタに接続することができるが、通常は入力ピンで非同期ファイル ソース フィルタに接続される (AVI Mux フィルタは IAsyncReader をサポートしないことに注意すること)。

フィルタ インターフェイス | IAMMediaContent、IBaseFilter、IPersistMediaPropertyBag
入力ピン メディア タイプ | MEDIATYPE_stream、MEDIASUBTYPE_avi
入力ピン インターフェイス | IPin、IQualityControl
出力ピン メディア タイプ | MEDIATYPE_Video、MEDIATYPE_audio、またはほかのタイプ (ファイルの内容、ファイルが圧縮されているかどうか、どのような CODEC が使用されているかに応じて異なる)。
出力ピン インターフェイス | IMediaPosition、IMediaSeeking、IPin、IQualityControl
フィルタ CLSID | CLSID_AviSplitter
プロパティ ページ CLSID | プロパティ ページなし。
実行モジュール | quartz.dll
メリット | MERIT_NORMAL
カテゴリ | CLSID_LegacyAmFilterCategory

注意

このフィルタは、AVI 再生フィルタ グラフを介してデータをプッシュし、シークを実装するので、ソース フィルタとみなされる。


BDA IP シンク

BDA IP シンク はカーネルモード フィルタで、BDA あるいは 非 BDA、アナログあるいはデジタル、TV グラフ使用され、(NABTS VBI スキャン ラインにあるような) IP データを Winsock に出力する。アナログ グラフでは、アップストリームを BDA SLIP デフレーマ に接続する。デジタル グラフでは、アップストリームを BDA MPE フィルタ に接続する。DirectX® 8.0 ではダウンストリームへの接続はサポートされていない、アプリケーション開発者は Winsock から IP データを受け取り処理するには、自身のコンポーネントを実装しなければならない。BDA IP シンク にはアプリケーションから呼び出し可能なインターフェイスはない。

BDA IP シンク は GrapEdit 内で"BDA Network Providers" カテゴリにある。これはカーネルモード フィルタなので、アプリケーションはそれを直接 Co-Create できないが、「デバイスとフィルタの列挙」で説明されているように、システム デバイス列挙子 を使ってそれをインスタンス化することができる。このフィルタは IFilterGraph::AddFilter を使って、グラフに手動で追加されなければならない、キャプチャ グラフ ビルダ はこのフィルタをグラフに追加するためは使えない。


BDA MPE フィルタ

マルチ プロトコル カプセル化 (MPE) は IP データをデジタル TV ネットワークで流すためのプロトコルである。BDA MPE フィルタ はカーネルモード フィルタであり、IP パケットを MPE フレームから抽出し、それを BDA IP シンク に最終的には Winsock に出力する、そこで興味を持つアプリケーションはそのデータを聞き、処理する。BDA SLIP デフレーマ は同じ機能をアナログ TV グラフで実行する、ここでは SLIP フレーミング プロトコルが使用される。

BDA MPE フィルタ はGrapEdit 内で "BDA Network Providers" カテゴリにある。これはカーネルモード フィルタなので、アプリケーションは直接 co-create できないが、デバイスとフィルタの列挙 で説明されているように、システム デバイス列挙子 を使ってインスタンス化しなければならない。このフィルタは IFilterGraph::AddFilter メソッドを使ってグラフに手動で追加されなければならない、キャプチャ グラフ ビルダ はこのフィルタをグラフに追加するためには使用できない。


BDA ネットワーク プロバイダ

Microsoft は 2 つのネットワーク プロバイダ フィルタを提供する、1 つは ATSC ネットワーク用で、1 つは DVB ネットワーク用である。ネットワーク プロバイダ は Microsoft® Broadcast Driver Architecture (BDA) をベースとしたデジタル TV フィルタ グラフ内のソース フィルタであるこのフィルタは BDA フィルタ グラフ内で ITuner をサポートすることにより、デフォルト チューナーとして機能する。それは基本的なグラフ構成タスクを実行し、BDA MPEG2 トランスポート情報フィルタや MPEG-2 デマルチプレクサのようなダウンストリーム フィルタを利用可能にする。

パーソナル コンピュータの TV レシーバは 1 つ以上のハードウェアで構成され、1 つ以上のソフトウェア結びついて動作する。BDA はこのハードウェアとソフトウェアの構成と制御に対して共通の方法を提供する。BDA ネットワーク プロバイダはこれらのインターフェイスを使って、レシーバのハードウェア コンポーネントとソフトウェア コンポーネントを構成し、TV 放送を受信する。デジタル TV 放送の場合、BDA ネットワーク プロバイダは番組情報を BDA MPEG2 トランスポート情報フィルタ から取得する。この情報を使ってレシーバ コンポーネントを構成し、基本ストリーム (たとえばビデオ、オーディオ、データ) を取得し番組をレンダリングできるようにする。

Microsoft ATSC ネットワーク プロバイダ フィルタと Microsoft DVB ネットワーク プロバイダ フィルタは GrapEdit 内で"BDA Network Providers" カテゴリにある。このフィルタは IFilterGraph::AddFilter メソッドを使って手動でグラフに追加されなければならない、キャプチャ グラフ ビルダはこのフィルタをグラフに追加するために用いることはできない。


BDA SLIP デフレーマ

BDA SLIP デフレーマ はカーネルモード フィルタで、BDA あるいは 非BDA アナログ TV グラフのどちらでも使うことができる、このグラフでは (NABTS VBI スキャン ラインにあるような) IP データの SLIP デ・フレーミングが必要とされる。それはアップストリームを NABTS/FEC VBI CODEC に、ダウンストリームを BDA IP シンク に接続し、Winsock 経由で受信しようとしているアプリケーションが IP パケットを利用できるようにする。BDA SLIP デフレーマ にはアプリケーションから呼び出し可能なインターフェイスはない。デジタル TV グラフでは、BDA MPE フィルタ を使用してデータ ストリームから IP パケットを抽出する。

BDA SLIP デフレーマ は GraphEdit 内の "BDA Receiver Component" にある。これはカーネルモード フィルタなので、アプリケーションは直接 co-create できないが、デバイスとフィルタの列挙 で説明されているように、システム デバイス列挙子 を使ってインスタンス化しなければならない。このフィルタは IFilterGraph::AddFilter メソッドを使ってグラフに手動で追加されなければならない、キャプチャ グラフ ビルダ はこのフィルタをグラフに追加するためには使用できない。


BDA MPEG2 トランスポート情報フィルタ

デジタル TV 放送は多くの番組と関連の基本ストリーム(たとえば オーディオ、ビデオ、ATVEF データ)を 1 つのトランスポート ストリームにマルチプレックスする。レシーバがすべての個別の番組に関する基本ストリームを正しく取得できるために、またレシーバがどのプログラムがストリームに含まれているのかを理解するために、トランスポート ストリームはそのトランスポート ストリームに含まれている情報のカタログとして働く多くの表を持っている。ネットワーク プロバイダ のディレクションの下で、MPEG-2 デマルチプレクサ はこれらの表をトランスポート情報フィルタに出力する。次に、別のレシーバ フィルタとグラフ内のノードのコントロールができるように、トランスポート情報フィルタはこれらの表をパースし、ネットワーク プロバイダにその情報を提供する。

BDA MPE シンク はGrapEdit 内で "BDA Transport Information Renderers" カテゴリにある。このフィルタは IFilterGraph::AddFilter メソッドを使ってグラフに手動で追加されなければならない。キャプチャ グラフ ビルダ はこのフィルタをグラフに追加するためには使用できない。


CC デコーダ フィルタ

CC VBI デコーダはカーネルモード ストリーム クラス フィルタである。GraphEdit では "WDM Streaming VBI CODEC" カテゴリにある。キャプチャされた VBI ラインを処理し、デコードされたクローズドキャプション データを Line 21 デコーダ や適切なアプリケーションに出力する。

このフィルタには 2 つの入力ピン VBI と HWCC がある。VBI ピンはロー VBI データ用に使用され、HWCC ピンは VBI デコードがキャプチャ フィルタによってハードウェアで処理されるときに使用される。データを HWCC ピンで受け取ったとき、CC デコーダは "パススルー モード" で操作し、データ ディレクトリを何も処理せず Line 21 デコーダに送る。

CC デコーダには 8 つまでの出力ピンがあり、それぞれが自身のラインとサブストリームを選択することができる。最初の出力ピンは Line-21 デコーダに接続される。

これはカーネルモード フィルタなので、アプリケーションはそれを直接 co-create できないが、「デバイスとフィルタの列挙」で説明されているように、システム デバイス列挙子 を使ってインスタンス化しなければならない。


カラー スペース変換フィルタ

変換フィルタは、1 つの RGB 色タイプを別の RGB タイプに変換する (たとえば 24 ビット RGB 色と 8 ビット RGB 色の変換)。一般にこのような変換はビデオ デコンプレッサ内でより効率的に処理できるので、カラー スペース変換は主にストリーム ソースが非圧縮 RGB フレームから構成される場合に使用される。

フィルタ インターフェイス | IBaseFilter
入力ピン メディア タイプ MEDIATYPE_Video、FORMAT_VideoInfo

次のサブタイプが有効
  • MEDIASUBTYPE_RGB8
  • MEDIASUBTYPE_RGB555
  • MEDIASUBTYPE_RGB565
  • MEDIASUBTYPE_RGB24
  • MEDIASUBTYPE_RGB32
入力ピン インターフェイス | IMemInputPin、IPin、IQualityControl
出力ピン メディア タイプ MEDIATYPE_Video、FORMAT_VideoInfo

次のサブタイプが有効
  • MEDIASUBTYPE_RGB8
  • MEDIASUBTYPE_RGB555
  • MEDIASUBTYPE_RGB565
  • MEDIASUBTYPE_RGB24
  • MEDIASUBTYPE_RGB32
出力ピン インターフェイス | IMediaPosition、IMediaSeeking、IPin、IQualityControl
フィルタ CLSID | CLSID_Colour
プロパティ ページ CLSID | プロパティ ページなし。
実行モジュール | quartz.dll
メリット | MERIT_UNLIKELY
カテゴリ | CLSID_LegacyAmFilterCategory


デフォルト DirectSound デバイス フィルタ

このフィルタは汎用のオーディオ レンダリング フィルタで、ファイル ソース (Async)、URL ファイル ソース、MPEG-1 ストリーム スプリッタ、AVI スプリッタ、WAVE パーサー、またはその他のオーディオ変換フィルタが WAV オーディオを含んでいる場合に、その出力に接続することができる。基本的なサウンド レンダリング機能に加え、このフィルタは Microsoft® DirectSound® API 呼び出しを処理することができる。すなわち、IAMDirectSound メソッドを使用してサウンドの再生を処理するウィンドウを設定および取得する。 DirectSound オーディオ レンダラは、Microsoft® DirectShow® のデフォルトのオーディオ レンダリング フィルタである。

このフィルタはオーディオドライバに関わらず、100 Hz から 100,000 Hz まで同じレートをサポートする。

フィルタ インターフェイス | IAMDirectSound、IAMResourceControl、IBaseFilter、IBasicAudio、IDirectSound3DBuffer、IDirectSound3dListener、IMediaPosition、IMediaSeeking、IQualityControl、IReferenceClock
入力ピン メディア タイプ | MEDIATYPE_Audio、MEDIASUBTYPE_NULL、FORMAT_WaveFormatEx
入力ピン インターフェイス | IMemInputPin、IPin、IPinConnection、IQualityControl
出力ピン メディア タイプ | 利用できない。
出力ピン インターフェイス | 利用できない。
フィルタ CLSID | CLSID_DSoundRender
プロパティ ページ CLSID | CLSID_AudioProperties、CLSID_AudioRendererAdvancedProperties
実行モジュール | quartz.dll
メリット |
カテゴリ | CLSID_AudioRendererCategory


DMO ラッパー フィルタ

DMO ラッパー フィルタは、Microsoft® DirectShow® アプリケーションがフィルタ グラフ内で Microsoft® DirectX® Media Object (DMO) を使用できるようにする。このフィルタは DMO をラップし、DMO とのデータの受け渡しなど、DMO の使用に関するすべての処理を扱う。また、このフィルタは DMO を集成するので、アプリケーションは DMO が公開するすべての COM インターフェイスのフィルタに問い合わせることができる。

このフィルタの使用方法については、「DirectShow アプリケーションでの DMO の使用」を参照すること。

フィルタ インターフェイス | IBaseFilter、IDMOWrapperFilter、IPersistStream
入力ピン メディア タイプ | 「注意」を参照
入力ピン インターフェイス | IMemInputPin、IPin、IQualityControl
出力ピン メディア タイプ | 「注意」を参照
出力ピン インターフェイス | IAMStreamConfig、 IAMVideoCompression、 IPin、IQualityControl
フィルタ CLSID | CLSID_DMOWrapperFilter
プロパティ ページ CLSID | プロパティ ページなし
実行モジュール | Qasf.dll
メリット | 「注意」を参照
カテゴリ | 「注意」を参照

注意

DMO の各入力ストリームに対して、このフィルタは対応する入力ピンを作成する。各出力ストリームに対しては、対応する出力ピンを作成する。メディア タイプは DMO に依存する。

DMO がビデオ エンコーダまたはオーディオ エンコーダである場合、フィルタの出力ピンは IAMStreamConfig インターフェイスを公開する。DMO がビデオ エンコーダである場合、出力ピンも IAMVideoCompression インターフェイスを公開する。ピンはインターフェイスについて DMO に照会する。DMO がインターフェイスをサポートしている場合、ピンは DMO に委任する。サポートしていない場合、ピンは独自の実装を提供する。

DirectShow は、デフォルトのメリット値 MERIT_NORMAL + 0x800 をすべての DMO に割り当てる。この値は、MERIT_NORMAL と MERIT_PREFERRED の間である。通常、デコーダ フィルタのメリット値は MERIT_NORMAL である。したがって、通常、フィルタ グラフ マネージャはデコーダ フィルタの代わりに DMO デコーダを選択する。デフォルトのメリット値をオーバーライドするには、HKEY_CLASSES_ROOT\CLSID 内の DMO の レジストリ キーに、レジストリ エントリを追加する。メリットを指定する値を持つ Merit という名前の DWORD 値をインクルードする。

DMO ラッパー フィルタは、単独ではどのカテゴリにも示されない。DMO をラップすると、DMO のカテゴリに対応した DirectShow カテゴリで、DMO 名の配下に示される。詳細については、「DirectShow アプリケーションでの DMO の使用」を参照すること。


DV Muxer フィルタ

このフィルタは、デジタル ビデオ (DV) エンコードのビデオ ストリームと 1 つあるいは 2 つのオーディオ ストリームとを組み合わせて、インターリーブ DV ストリームを生成する。ストリームを AVI ファイルに書き込むには、このフィルタを AVI Mux フィルタに接続する。次に AVI Mux をファイル ライタ フィルタに接続する。詳細については、「DirectShow でのデジタル ビデオ」を参照すること。

フィルタ インターフェイス | IBaseFilter、IMediaSeeking
入力ピン メディア タイプ | ビデオ : MEDIATYPE_Video、MEDIASUBTYPE_dvsd、FORMAT_VideoInfo オーディオ : MEDIATYPE_Audio、MEDIASUBTYPE_PCM、FORMAT_WaveFormatEx
入力ピン インターフェイス | IMemInputPin、IPin、IQualityControl
出力ピン メディア タイプ | MEDIATYPE_Interleaved、MEDIASUBTYPE_dvsd、FORMAT_DvInfo
出力ピン インターフェイス | IPin、IQualityControl
フィルタ CLSID | CLSID_DVMux
プロパティ ページ CLSID | プロパティ ページなし。
実行モジュール | qdv.dll
メリット | MERIT_UNLIKELY
カテゴリ | CLSID_LegacyAmFilterCategory

注意

DX Muxer は 2 つのオーディオ入力ピンを作成できる。以下の表に示されるオーディオ フォーマットがサポートをサポートする :

オーディオ ピン 1 | オーディオ ピン 2 | 出力フォーマット
サンプル レート (kHz) | ビット/サンプル | チャンネル | サンプル レート | ビット/サンプル | チャンネル
32 | 16 | モノラル | 接続しない | SD 2 チャンネル
32 | 16 | ステレオ | 接続しない | SD 4 チャンネル
44.1 or 48 | 16 | ステレオ or モノラル | 接続しない | SD 2 チャンネル
接続しない | 32 | 16 | ステレオ or モノラル | 許可されない
接続しない | 44.1 or 48 | 16 | モノラル | 許可されない
接続しない | 44.1 or 48 | 16 | ステレオ | SD 2 チャンネル
32 | 16 | モノラル | 32 | 16 | モノラル | SD 2 チャンネル
32 | 16 | ステレオ or モノラル* | 32 | 16 | ステレオ or モノラル* | SD 4 チャンネル
44.1 | 16 | モノラル | 44.1 | 16 | モノラル | SD 2 チャンネル
48 | 16 | モノラル | 48 | 16 | モノラル | SD 2 チャンネル
* 少なくとも 1 つのピンはステレオ。

この表では、オーディオ ピン 1 はオーディオ ソースに接続されている最初の入力ピンとして定義され、オーディオ ピン 2 はオーディオ ソースに接続されている 2 つめの入力ピンとして定義されている。オーディオ ピンを一度接続すると、両方のオーディオ ピンが接続解除されるまで、このナンバリング スキームは有効のまま残る。たとえば、オーディオ ピンを両方接続し、次にオーディオ ピン 1 だけを接続解除しても、残ったピンはそのままピン 2 として解釈される。

ピン 1 に提供されるオーディオは DV フレームの第 1 オーディオ ブロック (CH1) に録音され、ピン 2 に提供されるオーディオは第 2 オーディオ ブロック (CH2) に録音される。例外 : フィルタが 44.1 kHz あるいは 48 kHz でステレオ入力を 1 つだけ持っているなら、左のオーディオ チャンネルが第 1 オーディオ トラックに、右のオーディオ チャンネルが第 2 オーディオブロックに録音される。

SD 4 チャンネル 出力について : 入力がステレオなら、左トラックが CHa か CHc に録音され、右トラックが CHb か CHd に録音される。入力がモノラルなら、オーディオは CHa か CHc に録音され、CHb と CHd は空である。

オーディオ ピン 1 を接続と接続解除する事によって、許可されていないフォーマットにアクセスする場合がある。この場合、フィルタの IMediaFilter::Pause は VFW_E_NOT_CONNECTED を返す。この制限によって最初のオーディオ ブロックにオーディオがないような状態を防ぐことができるが、第 2 ブロックにはオーディオがある。第 1 ブロックにオーディオがある場合にのみ第 2 ブロックはオーディオを持つべきである。

DV Muxer は異なったサンプリング レートのオーディオ入力を許可しない。しかし IGraphBuilder::Connect のようなグラフ ビルディング メソッドは通常 ACM ラッパー フィルタを追加する、これは第 2 オーディオ ストリームを変換して第 1 ストリームのサンプリング レートに合わせる。

オーディオ入力が 48 kHz か 32 kHz なら、オーディオ出力はロックされる。(44.1-kHz オーディオをロックすることはできない。)

オーディオ ピンが接続されていないと、出力には入力 DV フレームからオーディオ データが入る。これは無音または有効なオーディオ データである。


DV スプリッタ フィルタ

このフィルタは、インターリーブされたデジタル ビデオ (DV) ストリームをそのコンポーネント ビデオとオーディオ ストリームに分割する。

フィルタ インターフェイス | IBaseFilter、IDVSplitter
入力ピン メディア タイプ | MEDIATYPE_Interleaved、MEDIASUBTYPE_dvsd、FORMAT_DvInfo
入力ピン インターフェイス | IMemInputPin、IPin、IQualityControl
出力ピン メディア タイプ | ビデオ : MEDIATYPE_Video、MEDIASUBTYPE_NULL、FORMAT_DvInfo オーディオ : MEDIATYPE_Audio、MEDIASUBTYPE_PCM、FORMAT_WaveFormatEx
出力ピン インターフェイス | IMediaPosition、IMediaSeeking、IPin、IQualityControl
フィルタ CLSID | CLSID_DVSplitter
プロパティ ページ CLSID | プロパティ ページなし。
実行モジュール | qdv.dll
メリット | MERIT_NORMAL
カテゴリ | CLSID_LegacyAmFilterCategory

注意

一度に 1 つの出力ピンだけが IMediaPosition および IMediaSeeking インターフェイスを公開する。

DV スプリッタ フィルタは、オーディオ ストリームの動的なフォーマットの変更を受け付けることができる。ただし AVI Mux フィルタがダウンストリームの場合は、フォーマットの変更を拒否する。この場合、DV スプリッタはオーディオ ストリームの生成を中止する。

注 : この制限は、タイプ 2 のファイル キャプチャにのみ影響する。プレビューについては、AVI Mux フィルタ ダウンストリームはない。タイプ 1 のファイル キャプチャの場合、インターリーブされたストリームは元々分割されない。DV ソースがライブ カメラの場合、通常はオーディオ フォーマットを変更する理由はない。ただし、異種のソースが一緒に編集された VTR テープから転送する場合は、そのような状況もあり得る。


DV ビデオ デコーダ フィルタ

このフィルタは、デジタル ビデオ (DV) ストリームを非圧縮ビデオにデコードする。このフィルタは、デコード解像度を設定するためのカスタム インターフェイス IIPDVDec を提供する。

フィルタ インターフェイス | IBaseFilter、IIPDVDec、 IPersistStream、ISpecifyPropertyPages
入力ピン メディア タイプ
  • MEDIATYPE_Video
  • MEDIASUBTYPE_dvsd または MEDIASUBTYPE_dvc
  • FORMAT_VideoInfo または FORMAT_DvInfo
入力ピン インターフェイス | IMemInputPin、IPin、IQualityControl
出力ピン メディア タイプ MEDIATYPE_Video、FORMAT_VideoInfo

次のサブタイプが有効
  • MEDIASUBTYPE_RGB24
  • MEDIASUBTYPE_RGB565
  • MEDIASUBTYPE_RGB555
  • MEDIASUBTYPE_RGB8
  • MEDIASUBTYPE_UYVY
  • MEDIASUBTYPE_YUY2
出力ピン インターフェイス | IMediaPosition、IMediaSeeking、IPin、IQualityControl
フィルタ CLSID | CLSID_DVVideoCodec
プロパティ ページ CLSID | CLSID_DVDecPropertiesPage
実行モジュール | qdv.dll
メリット | MERIT_NORMAL
カテゴリ | CLSID_LegacyAmFilterCategory


DV ビデオ エンコーダ フィルタ

このフィルタは、非圧縮ビデオ ストリームをデジタル ビデオ (DV) にエンコードする。このフィルタは、エンコード解像度およびフォーマットを設定するためのカスタム インターフェイス IDVEnc を提供する。

フィルタ インターフェイス | IAMVideoCompression、IBaseFilter、IDVEnc、IPersistStream、ISpecifyPropertyPages
入力ピン メディア タイプ MEDIATYPE_Video、FORMAT_VideoInfo

次のサブタイプが有効
  • MEDIASUBTYPE_RGB24
  • MEDIASUBTYPE_RGB565
  • MEDIASUBTYPE_RGB555
入力ピン インターフェイス | IMemInputPin、IPin、IQualityControl
出力ピン メディア タイプ | MEDIATYPE_Video、MEDIASUBTYPE_dvsd、FORMAT_VideoInfo
出力ピン インターフェイス | IMediaPosition、IMediaSeeking、IPin、IQualityControl
フィルタ CLSID | CLSID_DVVideoEnc
プロパティ ページ CLSID | CLSID_DVEncPropertiesPage
実行モジュール | qdv.dll
メリット | MERIT_DO_NOT_USE
カテゴリ | CLSID_VideoCompressorCategory

注意

16 ビット ビデオ (MEDIASUBTYPE_RGB555 または MEDIASUBTYPE_RGB565) の場合、NTSC の入力は 720 x 480 ピクセル、PAL の入力は 720 x 576 ピクセルでなければならない。24 ビット ビデオの場合、入力サイズに関する制約はない。

出力は、NTSC の場合は 720 x 480、PAL の場合は 720 x 576 に必ずなる。24 ビット ビデオはこの寸法に合うようにスケーリングされる。


DVD ナビゲータ フィルタ

DVD ナビゲータ フィルタは、DVD-Video 再生フィルタ グラフのソース フィルタである。このフィルタは、DVD-Video ボリューム内の必要なファイルをすべて開き、リニア DVD-Video .vob ファイル内をナビゲートして結果の MPEG-2 プログラム ストリームを解析し、ストリームを 3 つ (ビデオ、オーディオ、サブピクチャ) の出力ピンに分割する。

また、DVD ナビゲータ フィルタは、DVD 再生アプリケーションが DVD-Video の再生を制御できるようにする IDVDControl2 インターフェイスおよび IDVDInfo2 インターフェイスを実装する。新しいインターフェイスの採用により、従来の IDVDControl および IDVDInfo インターフェイスは使用されない。新しいインターフェイスは完全に新しい実装で、従来のインターフェイスを継承するものではない。

フィルタ インターフェイス | IBaseFilter、IDVDControl、IDVDControl2、IDVDCmd、IDVDInfo、IDVDInfo2、IDVDState IFileSourceFilter、ISpecifyPropertyPages
入力ピン メディア タイプ | MEDIATYPE_Stream; MEDIASUBTYPE_MPEG2_PROGRAM
入力ピン インターフェイス | 利用できない。
出力ピン メディア タイプ
  • MEDIATYPE_Audio、MEDIASUBTYPE_MPEG1AudioPayload
  • MEDIATYPE_Video、MEDIASUBTYPE_MPEG2_VIDEO
出力ピン インターフェイス | IPin、IQualityControl
フィルタ CLSID | CLSID_DVDNavigator
プロパティ ページ CLSID | プロパティ ページなし。
実行モジュール | qdvd.dll
メリット | MERIT_DO_NOT_USE
カテゴリ | CLSID_LegacyAmFilterCategory


ファイル ソース (Async) フィルタ

非同期ファイル ソース フィルタは、さまざまな異なるデータ フォーマットのローカル ファイルを開いて読み取り、データをパーサー フィルタに渡す。Web からデータをダウンロードする場合は、URL ファイル ソース フィルタを使用する。

フィルタ インターフェイス | IBaseFilter、IFileSourceFilter
入力ピン メディア タイプ | 利用できない。
入力ピン インターフェイス | 利用できない。
出力ピン メディア タイプ | MEDIATYPE_Stream。サブタイプはメディア フォーマットに依存する (フィルタがフォーマットを認識しない場合は MEDIASUBTYPE_NULL)。
出力ピン インターフェイス | IAsyncReader
フィルタ CLSID | CLSID_AsyncReader
プロパティ ページ CLSID | プロパティ ページなし。
実行モジュール | quartz.dll
メリット | MERIT_UNLIKELY
カテゴリ | CLSID_LegacyAmFilterCategory


ファイル ソース (URL) フィルタ

URL ファイル ソース フィルタは汎用の非同期ソース フィルタで、Uniform Resource Locator (URL) によって識別可能なソース ファイルのうち、メディア メジャー タイプがストリームであるすべてのファイルに対して使用できる。このようなファイルには、AVI、MOV、MPEG、および WAV ファイルがある。このフィルタを使用するには、ダウンストリーム フィルタが、MPEG-1 ストリーム スプリッタ、AVI スプリッタ、または QuickTime ムービー パーサーなどのパーサーであることが必要である。

フィルタ インターフェイス | IAMOpenProgress, IBaseFilter, IFileSourceFilter
入力ピン メディア タイプ | 利用できない。
入力ピン インターフェイス | 利用できない。
出力ピン メディア タイプ | MEDIATYPE_Stream。サブタイプはメディア フォーマットに依存する (フィルタがフォーマットを認識しない場合は MEDIASUBTYPE_NULL)。
出力ピン インターフェイス | IAsyncReader、IPin
フィルタ CLSID | CLSID_URLReader
プロパティ ページ CLSID | プロパティ ページなし。
実行モジュール | quartz.dll
メリット | MERIT_UNLIKELY
カテゴリ | CLSID_LegacyAmFilterCategory

注意

このフィルタは、Microsoft® Internet Explorer の URLMon を使用し、コード ページをサポートする。


ファイル ライタ フィルタ

ファイル ライタ フィルタを使用すると、フォーマットに関係なくディスクにファイルを書き込むことができる。このフィルタは入力ピンで受け取ったものを単にディスクに書き込むだけなので、ファイルを正常にフォーマットできるマルチプレクサのアップストリームに接続する必要がある。ファイル ライタを使用して新しい出力ファイルを作成したり、既存のファイルを指定することができる。ファイルが既に存在している場合、そのファイルは新しいデータで完全にオーバーライドされる。

ファイル ライタに渡されるサンプルのタイム スタンプは、ファイルのバイト オフセットである。入力ピンは IStream インターフェイスを公開し、インターフェイスのサブセットをサポートする。これにより、グラフが中止されたときにアップストリーム フィルタがデータを書き込むことが可能になる。

注 : Microsoft® Windows Media™ Software Development Kit を使用して ASF ファイルを記述する場合は、ASF ライタ フィルタを使用する。ASF ライタは、Microsoft DirectShow において Microsoft Windows Media Audio (WMA) ファイルを作成する唯一の方法を提供する。

フィルタ インターフェイス | IAMFilterMiscFlags、 IBaseFilter、 IFileSinkFilter、 IFileSinkFilter2、 IPersistStream
入力ピン メディア タイプ | MEDIATYPE_Stream、MEDIASUBTYPE_NULL
入力ピン インターフェイス | IMemInputPin、IPin、IQualityControl、IStream
出力ピン メディア タイプ | 利用できない。
出力ピン インターフェイス | 利用できない。
フィルタ CLSID | CLSID_FileWriter
プロパティ ページ CLSID | プロパティ ページなし。
実行モジュール | qcap.dll
メリット | MERIT_DO_NOT_USE
カテゴリ | CLSID_LegacyAmFilterCategory


フルスクリーン レンダリング フィルタ

フルスクリーン レンダリング フィルタは、Microsoft® DirectDraw® を使用して、320x240 ビデオを 1024x768 に即座に拡張できない古いグラフィックス カード上でフルスクリーン ビデオをレンダリングする。このハードウェア制限に対処するために、フルスクリーン レンダラは、単にグラフィックス ディスプレイ カードを 320x240 モードに切り替える。最近のビデオ カードは即座に表示を拡張できるので、ビデオ レンダラ フィルタをウィンドウ モードとフルスクリーン モードのどちらでも使用できる。フィルタ グラフ マネージャはフルスクリーン レンダラをグラフ内に自動的に呼び出す。ビデオ カードが新しいほど、このフィルタを使用する機会が減る。このフィルタを手作業でグラフに追加してはならない。ビデオ レンダラを選択するのはフィルタ グラフ マネージャの役割である。

フィルタ インターフェイス | IBaseFilter、IFullScreenVideo、IFullScreenVideoEx、IMediaPosition、IMediaSeeking、IQualityControl、IQualProp
入力ピン メディア タイプ | MEDIATYPE_Video、MEDIASUBTYPE_Null
入力ピン インターフェイス | IMemInputPin、IPin、IQualityControl
出力ピン メディア タイプ | 利用できない。
出力ピン インターフェイス | 利用できない。
フィルタ CLSID | CLSID_ModexRenderer
プロパティ ページ CLSID | CLSID_ModexProperties
実行モジュール | quartz.dll
メリット | MERIT_UNLIKELY
カテゴリ | CLSID_LegacyAmFilterCategory


インフィニット ピン ティー フィルタ

このフィルタは、入力ピンに配送されたサンプルを可変数の出力ピンに送る。このフィルタのインスタンスが作成されると、インスタンスは 1 つの出力ピンを持つ。出力ピンを接続するごとに、フィルタは別の出力ピンを作成する。すべての出力ピンは入力ピンと同じメディア タイプを共有する。

フィルタ インターフェイス | IBaseFilter
入力ピン メディア タイプ | 任意のメディア タイプ。
入力ピン インターフェイス | IMemInputPin、IPin、IQualityControl
出力ピン メディア タイプ | 任意のメディア タイプ。入力ピンのメディア タイプと同じ。
出力ピン インターフェイス | IMediaPosition、IMediaSeeking、IPin、IQualityControl
フィルタ CLSID | CLSID_InfTee
プロパティ ページ CLSID | プロパティ ページなし。
実行モジュール | qcap.dll
メリット | MERIT_DO_NOT_USE
カテゴリ | CLSID_LegacyAmFilterCategory


内部スクリプト コマンド レンダリング フィルタ

スクリプト コマンドを受け取り、アプリケーションにディスパッチする。

このフィルタは、次の 2 つのフォーマットのいずれかでスクリプトを受け取る。

  • MEDIATYPE_Text : 各メディア サンプルに ANSI テキスト文字列が含まれる。
  • MEDIATYPE_ScriptCommand : 各メディア サンプルに NULL 終端の 2 つの Unicode™ 文字列が連結されて含まれる。最初の文字列はコマンド タイプを示し、2 つ目の文字列はスクリプト コマンドを示す。

フィルタがサンプルを受け取ると、EC_OLE_EVENT イベント通知を送る。最初のイベントのパラメータはコマンド タイプを持つ BSTR であるか、またはフォーマットが MEDIATYPE_Text である場合は Text である。2 つ目のイベント パラメータは、スクリプト コマンドを持つ BSTR である。アプリケーションは、イベントを取得し、スクリプト コマンドに応答できる。

このフィルタの使い方の例については、「SAMI (CC) パーサー」を参照すること。

フィルタ インターフェイス | IBaseFilter、IMediaPosition、IMediaSeeking
入力ピン メディア タイプ
  • MEDIATYPE_ScriptCommand、MEDIASUBTYPE_NULL
  • MEDIATYPE_Text、MEDIASUBTYPE_NULL
入力ピン インターフェイス | IMemInputPin、IPin、IQualityControl
出力ピン メディア タイプ | 利用できない
出力ピン インターフェイス | 利用できない
フィルタ CLSID | {48025243-2D39-11CE-875D-00608CB78066}
プロパティ ページ CLSID | プロパティ ページなし
実行モジュール | Quartz.dll
メリット | MERIT_PREFERRED + 1
カテゴリ | CLSID_LegacyAmFilterCategory


Line 21 デコーダ フィルタ

Line 21 デコーダ フィルタは、Line 21 データを標準バイト ペア フォーマット、または DVD の場合は、ピクチャ グループ (GOP) 全体のパケットとして受け付ける。DVD ビデオ ストリーム内のすべての GOP に関して、当該 GOP のヘッダー情報と Line 21 データを持つユーザー データ パケットが存在可能である。

入力ピンでは、フィルタは任意の Line 21 データ プロバイダ (たとえば、Line 21 データ出力ピンを持つ DVD ビデオ デコーダ)、または TV チューナー/ビデオ キャプチャ カードから入ってくる VBI ストリームから Line 21 データを提供する CC デコーダ WDM フィルタ (KsProxy 経由) に接続される。

このフィルタは、Line 21 データをビットマップにデコードして、ダウンストリーム フィルタ、すなわちオーバーレイ ミキサーのセカンダリ ピンまたはビデオ レンダラに渡す (オーバーレイ ミキサーのプライマリ ピンは必ずメイン ビデオ ストリームを受け取る)。

次の図に、Line 21 デコーダを使用した一般的な DVD フィルタ グラフを示す。

Line 21 デコーダを使用した一般的な DVD フィルタ グラフ

フィルタ インターフェイス | IAMLine21Decoder
入力ピンのメディア タイプ メジャー タイプ: MEDIATYPE_AUXLine21Data
サブタイプ:
  • MEDIASUBTYPE_Line21_BytePair [標準 Line 21]
  • MEDIASUBTYPE_Line21_GOPPacket [DVD Line 21]
フォーマット タイプ : FORMAT_VideoInfo またはなし
入力ピン インターフェイス | なし。
出力ピン メディア タイプ メジャー タイプ : MEDIATYPE_Video
サブタイプ :
  • MEDIASUBTYPE_RGB8
  • MEDIASUBTYPE_RGB555
  • MEDIASUBTYPE_RGB565
  • MEDIASUBTYPE_RGB24
  • MEDIASUBTYPE_RGB32
フォーマット タイプ : FORMAT_VideoInfo
出力ピン インターフェイス | なし
フィルタ CLSID | CLSID_Line21Decoder
プロパティ ページ CLSID | なし
実行モジュール | qdvd.dll
メリット | MERIT_NORMAL
カテゴリ | CLSID_LegacyAmFilterCategory


MIDI パーサー フィルタ

MIDI パーサー フィルタは、.MID ファイルおよび .RMI ファイルの MIDI データを読み取る。このフィルタは、非同期ファイル ソース フィルタまたはURL ファイル ソース フィルタからのストリームを受け取り、MIDI サンプルを再生するために MIDI レンダラに出力する。

フィルタ インターフェイス | IAMMediaContent、IBaseFilter
入力ピン メディア タイプ | MEDIATYPE_Stream、MEDIASUBTYPE_Midi
入力ピン インターフェイス | IPin、IQualityControl
出力ピン メディア タイプ | MEDIATYPE_Midi、MEDIASUBTYPE_NULL
出力ピン インターフェイス | IMediaSeeking、IQualityControl、IPin
フィルタ CLSID | CLSID_MIDIParser {D51BD5A2-7548-11cf-A520-0080C77EF58A}
プロパティ ページ CLSID | プロパティ ページなし。
実行モジュール | quartz.dll
メリット | MERIT_UNLIKELY
カテゴリ | CLSID_LegacyAmFilterCategory

注意

詳細については、「MIDI レンダラ」を参照すること。


MIDI レンダリング フィルタ

MIDI レンダリング フィルタは、MIDI パーサー フィルタからの MIDI データをレンダリングする。

フィルタ インターフェイス | IAMDirectSound、IAMResourceControl、IBaseFilter、IBasicAudio、IMediaPosition、IMediaSeeking、IQualityControl、IReferenceClock
入力ピン メディア タイプ | MEDIATYPE_Midi、MEDIASUBTYPE_NULL
入力ピン インターフェイス | IMemInputPin、IPin、IQualityControl
出力ピン メディア タイプ | 利用できない。
出力ピン インターフェイス | 利用できない。
フィルタ CLSID | CLSID_AVIMIDIRender
プロパティ ページ CLSID | プロパティ ページなし。
実行モジュール | quartz.dll
メリット | MERIT_PREFERRED
カテゴリ | CLSID_MidiRendererCategory

注意

フォーマット タイプの GUID は NULL だが、フォーマット ブロックには次の構造体が入る :

typedef struct _MIDIFORMAT {
    DWORD       dwDivision;
    DWORD       dwReserved[7];
} MIDIFORMAT, FAR * LPMIDIFORMAT;

dwDivision メンバ変数はファイルの時間分割を指定する。時間分割は標準 MIDI ファイル (SMF) のヘッダーの MThd チャンクで与えられている。MIDI レンダラは midiStreamProperty 関数を呼び出すことによって、このプロパティを MIDI データ ストリームに設定する。

MIDI パーサー フィルタからのサンプルには 1 秒の MIDI データが入っている。MIDI レンダラは midiStreamOut 関数を使って MIDI データをレンダリングする。各サンプルは つの 同期ポイント である : そのバッファの始めには、そのバッファをレンダリングするための正しい状態を設定するのに必要なすべてのコマンドが含まれている。


MJPEG コンプレッサ フィルタ

このフィルタは、モーション JPEG 圧縮を使用して非圧縮ビデオ ストリームを圧縮する。

フィルタ インターフェイス | IBaseFilter、IPersistStream
入力ピン メディア タイプ | MEDIATYPE_VIDEO、MEDIASUBTYPE_NULL
入力ピン インターフェイス | IMemInputPin、IPin、IQualityControl
出力ピン メディア タイプ | MEDIATYPE_Video、MEDIASUBTYPE_MJPG
出力ピン インターフェイス | IAMStreamConfig、IAMVideoCompression、IMediaPosition、IMediaSeeking、IPin、IQualityControl
フィルタ CLSID | CLSID_MJPGEnc
プロパティ ページ CLSID | プロパティ ページなし。
実行モジュール | quartz.dll
メリット | MERIT_DO_NOT_USE
カテゴリ | CLSID_VideoCompressorCategory

注意

このフィルタは、FOURCC コード 'MJPG' に対応するメディア サブタイプ MEDIASUBTYPE_MJPG を使用してエンコードを行う。


MJPEG デコンプレッサ フィルタ

このフィルタは、モーション JPEG から非圧縮ビデオにビデオ ストリームをデコードする。一部のデジタル ビデオ カメラは、モーション JPEG ビデオ ストリームを生成する。

フィルタ インターフェイス | IBaseFilter
入力ピン メディア タイプ | MEDIATYPE_Video、MEDIASUBTYPE_MJPG
入力ピン インターフェイス | IMemInputPin、IPin、IQualityControl
出力ピン メディア タイプ | MEDIATYPE_VIDEO、MEDIASUBTYPE_NULL
出力ピン インターフェイス | IMediaPosition、IMediaSeeking、IPin、IQualityControl
フィルタ CLSID | CLSID_MjpegDec
プロパティ ページ CLSID | プロパティ ページなし。
実行モジュール | quartz.dll
メリット | MERIT_NORMAL
カテゴリ | CLSID_LegacyAmFilterCategory

注意

このフィルタは、FOURCC コード 'MJPG' を使用するモーション JPEG ビデオとの互換性を持つ。これ以外のモーション JPEG はデコードできない。そのようなモーション JPEG については、サードパーティのデコーダ フィルタを使用する必要がある。


MPEG-1 オーディオ デコーダ フィルタ

MPEG-1 Layer I および Layer II オーディオを PCM にデコードする。

フィルタ インターフェイス | IBaseFilter、ISpecifyPropertyPages
入力ピン メディア タイプ MEDIATYPE_Audio、FORMAT_WaveFormatEx

次のサブタイプが有効
  • MEDIASUBTYPE_MPEG1Packet
  • MEDIASUBTYPE_MPEG1Payload
  • MEDIASUBTYPE_MPEG1AudioPayload
  • GUID_NULL
入力ピン インターフェイス | IMemInputPin、IPin、IQualityControl
出力ピン メディア タイプ | MEDIATYPE_Audio、MEDIASUBTYPE_PCM
出力ピン インターフェイス | IMediaPosition、IMediaSeeking、IPin、IQualityControl
フィルタ CLSID | CLSID_CMpegAudioCodec
プロパティ ページ CLSID | CLSID_MpegAudioDecoderPropertyPage
実行モジュール | quartz.dll
メリット | 0x03680001
カテゴリ | CLSID_LegacyAmFilterCategory


MPEG-1 ストリーム スプリッタ フィルタ

このフィルタは、MPEG-1 システム ストリームをそのコンポーネント オーディオおよびビデオ ストリームに分割する。

フィルタ インターフェイス | IAMMediaContent、IAMStreamSelect、IBaseFilter
入力ピン メディア タイプ MEDIATYPE_Stream

次のサブタイプが有効
  • MEDIASUBTYPE_MPEG1System
  • MEDIASUBTYPE_MPEG1VideoCD
  • MEDIASUBTYPE_Audio
  • MEDIASUBTYPE_Video
入力ピン インターフェイス | IMemInputPin、IPin、IQualityControl
出力ピン メディア タイプ
  • MEDIATYPE_Video、MEDIASUBTYPE_MPEG1Packet
  • MEDIATYPE_Video、MEDIASUBTYPE_MPEG1Payload
  • MEDIATYPE_Audio、MEDIASUBTYPE_MPEG1Packet
  • MEDIATYPE_Audio、MEDIASUBTYPE_MPEG1Payload
出力ピン インターフェイス | IPin、IMediaSeeking
フィルタ CLSID | CLSID_MPEG1Splitter
プロパティ ページ CLSID | プロパティ ページなし。
実行モジュール | quartz.dll
メリット | MERIT_NORMAL
カテゴリ | CLSID_LegacyAmFilterCategory

注意

MPEG-1 コンテンツはインデックスが付けられていないので、シーク処理が非常に大まかになる。通常は、固定ビット レートの MPEG-1 システム ストリーム (通常はビデオ CD のハードウェアで生成される) に使用する。IAMMediaContent は MP3 ID3 コンテンツに対して公開される。


MPEG-1 ビデオ デコーダ フィルタ

MPEG-1 ビデオをデコードする。

フィルタ インターフェイス | IBaseFilter、IMpegVideoDecoder、ISpecifyPropertyPages
入力ピン メディア タイプ MEDIATYPE_Video、FORMAT_MPEGVideo

次のサブタイプが有効
  • MEDIASUBTYPE_MPEG1Packet
  • MEDIASUBTYPE_MPEG1Payload
入力ピン インターフェイス | IPin、IMemInputPin
出力ピン メディア タイプ MEDIATYPE_Video、FORMAT_VideoInfo or FORMAT_VideoInfo2

次のサブタイプが有効
  • MEDIASUBTYPE_RGB24
  • MEDIASUBTYPE_RGB32
  • MEDIASUBTYPE_RGB8
  • MEDIASUBTYPE_RGB555
  • MEDIASUBTYPE_RGB565
  • MEDIASUBTYPE_UYVY
  • MEDIASUBTYPE_Y41P
  • MEDIASUBTYPE_YUY2
  • MEDIASUBTYPE_YV12
出力ピン インターフェイス | IPin、IQualityControl
フィルタ CLSID | CLSID_CMPEGVideoCodec
プロパティ ページ CLSID | CLSID_MpegVideoDecodePropertyPage
実行モジュール | quartz.dll
メリット | 0x40000001
カテゴリ | CLSID_LegacyAmFilterCategory

注意

このフィルタは、DirectDraw サーフェスへのデコードも可能である。 このフィルタは、マシンが MMX をサポートしていれば MMX を使用する。


MPEG-2 デマルチプレクサ

MPEG-2 デマルチプレクサ (Demux) は プッシュモードで出力される MPEG-2 トランスポートと番組ストリームを操作する。(ファイル再生シナリオのような、プルモードで出力される MPEG-2 番組ストリームをについては、MPEG-2 スプリッタ フィルタを使用する。) トランスポート ストリーム上で操作するとき、Demux は トランスポート スリーム モード にあると言われる。番組ストリーム上で操作するとき、Demux は 番組ストリーム モード にあると言われる。トランスポート ストリーム モードでは、デマルチプレキシングは 1 つ以上のパケット ID (PID) の出力ピンへのマッピングをベースにしている。番組ストリーム モードでは、このマッピングは 1 つのストリーム ID と 1 つの出力ピン間となる。ある PID あるいは ストリーム ID がある出力ピンにマップされないと、Demux は破棄するだけである。

Demux は パス スルー モード でも操作できる。たとえば、アプリケーションはすべての PID を 1 つの出力ピンにマッピングし、PID パケットのストリームを作成できる、それはファイルにも書き込めるし、再度ブロードキャストにもできるし、別の方法で処理することもできる。パケットの再マルチプレキシングはパス スルー モードでは実行できない、出力ストリームは素直な MPEG-2 トランスポート ストリームではない。エラーのあるパケットはフィルタで出力できない。

次の図は Demux がトランスポート ストリーム モードのときの可能なデータ フローを示す。

トランスポート ストリーム モードでの Demux

フィルタを構成する

Demux が最初にインスタンス化されフィルタ グラフに追加されると、入力ピンを 1 つ持ち出力ピンは持たない。デジタル TV 放送をレンダリングし、Microsoft® Broadcast Driver Architecture (BDA) をベースにしているフィルタ グラフでは、BDA ネットワーク プロバイダ フィルタは Demux 上の出力ピンを作成し、ピンに PID をマッピングする責任がある。他のフィルタグラフでは、ピンが作成されストリーム ID (番組ストリーム モード) か PID (トランスポート ストリーム モード) を各ピンにマッピングするとき、ピンのメディア タイプを設定することによって出力ピンの作成と構成をすることはアプリケーションの責任である。

Demux は、どのタイプのストリームをフィルタが期待しているかを示すトリガー イベントが発生した後で、自分自身を内部的に各トランスポート ストリームあるいは番組ストリームに対して構成する。通常トリガー イベントは最初に出力ピンが構成されたときに起こる。たとえば、番組ストリーム モードでは、アプリケーションはフィルタの IMpeg2Demultiplexer::CreateOutputPin メソッドを使って新しい出力ピンを作成する。このメソッドは IPin インターフェイスポインタを作成されたピンに返す。アプリケーションは次に QueryInterface を呼び出す際に、このポインタを使って IMPEG2StreamIDMap インターフェイスを取得する。このときに Demux は番組ストリーム モードに自分自身を構成する、なぜなら IMPEG2StreamIDMap は番組ストリームを指定しているからである。アプリケーションが最初の出力ピンでQueryInterface を呼び出し、IMPEG2PIDMap インターフェイスを要求したとき、同じプロセスがトランスポート モードで起きる。もう 1 つ別のトリガー イベントは Demux の入力ピンが接続されたときである、接続メディア タイプは入力ストリームが番組ストリームかトランスポート ストリームかを Dexmu に示す。

Demux は Run 状態になり得る前に構成されなければならない。Demux があるストリーム タイプで自分自身を 1 度構成すると別のストリーム タイプで再構成することはできない。Demux を番組ストリーム モードとトランスポート ストリーム モードで切り替えるには、新しくフィルタをインスタンス化して始めなおさなければならない。

番組ストリーム モードでピンを構成する

前のセクションで説明したように、出力ピンを作成した後で、アプリケーションは IMPEG2StreamIDMap インターフェイスに対してそのピンをクエリする。アプリケーションは次に IMPEG2StreamIDMap::MapStreamId メソッドを呼び出し、そのピンと指定した基本ストリームを組み合わせ、サブストリーム フィルタリングが要求されているかどうかを知らせる。MPEG-2 (トランスポート ストリームではなく) 番組ストリームではオーディオ基本ストリームは複数のサブストリームに将来分割されるかもしれない。これはプライベート複数オーディオ トラックで起こることが多い。アプリケーションは必要なサブストリーム フィルタリング情報と共にピンを提供する責任があるので、ピンはどのサブストリームをオーディオ デコーダに渡すかを知っている。詳細は IMPEG2StreamIDMap::MapStreamID ページを参照すること。

トランスポート ストリーム モードでピンを構成する

フィルタ グラフに BDA Network Provider フィルタがあるなら、このフィルタは自動的にすべての必要な 出力ファイルを Demux 上に作成し、各ピンに PID をマップする。オーディオとビデオのストリームでは、一般的には各ピンに 1 つの PID がある。番組サービス情報 (PSI) ストリームでは、いくつかの PID が トランスポート情報フィルタ (TIF) に接続する出力ピンにマッピングされる場合がある。BDA ネットワーク プロバイダ はシーンの裏側で TIF と共に動作し、PSI ストリームの様々な表の PID を取得し、それに従って Demux の出力ピンを構成する。BDA をベースとしないカスタム フィルタを通してトランスポート ストリームを提供しているなら、フィルタかアプリケーションのいずれかがこの作業をしなければならない。

Clock Behavior

Demux は IReferenceClock インターフェイスを実装することにより、フィルタグラフの参照クロックとして機能する。トランスポート ストリームと共に、このクロックは最後にマップされたオーディオあるいはビデオ ストリームに対応する PCR ストリームに従属する。これ以外に PCR が存在しても、それらはトラックされるが、使用されない。番組ストリームと共に、Demux はそのクロックを SCR ストリームに従属させる。クロックの PCR や SCR ストリームへの従属によって、ダウンストリーム バッファのオーバーフローやアンダーフローの状態を避けることができる、そうしないとローカル システム クロックとストリーム クロック間の違いによってオーバーフローやアンダーフローが起こる。

Demux はダウンストリーム フィルタに対して単調増加するプレゼンテーション時間を保証する。これはたとえば次のようなことを意味する、トランスポート ストリームが主番組とは違うクロックで作成されたコマーシャルのようなセグメントを含んでいても、Demux はプレゼンテーション時間スタンプを調整し、ダウンストリーム デコーダとレンダラから不連続さを隠す。

フィルタ インターフェイス | IMpeg2Demultiplexer、IBaseFilter、IReferenceClock、ISpecifyPropertyPages
入力ピン メディア タイプ | MEDIATYPE_Stream、MEDIASUBTYPE_MPEG2_TRANSPORT、Format_None MEDIATYPE_Stream、MEDIASUBTYPE_MPEG2_PROGRAM、Format_None
入力ピン インターフェイス | IPin
出力ピン メディア タイプ | オーディオとビデオの基本ストリームはオーディオとビデオのメジャータイプを持たなければならない。Demux はメディア サブタイプに無制限を設定する。
出力ピン インターフェイス | IMPEG2StreamIDMap、 IMPEG2PIDMap、 IPin
フィルタ CLSID | CLSID_MPEG2Demultiplexer
プロパティ ページ CLSID | ISpecifyPropertyPages インターフェイスを使ってプロパティ ページにアクセスする。
実行モジュール | mpg2splt.ax
メリット | MERIT_NORMAL
カテゴリ | CLSID_LegacyAmFilterCategory


MPEG-2 スプリッタ

MPEG-2 スプリッタ フィルタは、MPEG-2 ビデオ、MPEG-2 オーディオ、DVD ビデオの定義に従ってエンコードされた AC3 オーディオ、DVD ビデオの定義に従ってエンコードされた PCM オーディオのいずれかのストリーム タイプを 1 つ以上含むプルモードで出力された(ファイル再生) MPEG-2 プログラム ストリームを入力として受け付ける。このフィルタは、ストリームを解析してそれぞれに対する出力ピンを作成し、圧縮オーディオまたはビデオ MPEG パケットを MPEG-2 デコーダ フィルタに出力する。

Microsoft DirectShow は MPEG-2 デコーダを提供しない。

プッシュモード (ライブソース) で出力された MPEG-2 番組ストリームとトランスポート ストリームは MPEG-2 Demultiplexer を使用する。

フィルタ インターフェイス | IBaseFilter、 ISpecifyPropertyPages、IAMParse、IAMStreamSelect
入力ピン メディア タイプ
  • MEDIATYPE_Stream, MEDIASUBTYPE_MPEG2_PROGRAM
  • MEDIATYPE_Stream, MEDIASUBTYPE_MPEG2_TRANSPORT
  • MEDIATYPE_Stream, MEDIASUBTYPE_MPEG1_Video
  • MEDIATYPE_Stream, MEDIASUBTYPE_NULL
入力ピン インターフェイス | IPin、IMemInputPin
出力ピン メディア タイプ
出力ピン インターフェイス | IPin、IMediaSeeking
フィルタ CLSID | CLSID_MMSPLITTER
プロパティ ページ CLSID | N/A
実行モジュール | mpg2splt.ax
メリット | MERIT_NORMAL + 1
カテゴリ | CLSID_AudioInputDeviceCategory


MSYUV カラー スペース変換 CODEC

MSYUV は YUV から RGB カラー スペースへのコンバータ CODEC である。たとえクライアントのビデオ ディスプレイ アダプタのハードウェア YUV-to-RGB 変換を使えなくても、YUV フォーマットのビデオ ソース データの再生を可能にする。CODEC は AVI デコンプレッサ ラッパー フィルタを通してフィルタ グラフに参加する。

1394 か USB インターフェイスを持ったデジタル カンファレンス カメラは複数の YUV フォーマットでイメージ データを生成し得る。ディスプレイ ハードウェアがオンボードの YUV-to-RGB 変換をサポートしていない、あるいはハードウェア 変換性能がある別の理由で使用できないなら、YUV イメージ データはビデオ レンダラに送られる前に RGB フォーマットに変換されなければならない。

フィルタ グラフを構築するとき、グラフ ビルダは出力ピン メディア タイプの YUV フォーマットを検知し、グラフ内に AVI デコンプレッサ を挿入する、そして AVI デコンプレッサ は MSYUV CODEC をロードし RGB への変換を行うよう最初に構成する。グラフが最初に実行あるいはポーズに移行した後で、ビデオ レンダリング フィルタはビデオ ディスプレイ アダプタがハードウェア変換可能かどうかを検知できる。可能であれば、AVI デコンプレッサ は通知を受け、MSYUV を 「パス スルー モード」で処理するよう再構成する、それにより CODEC は変換をスキップし、YUV イメージデータを直接ビデオ メモリの DirectDraw オーバーレイ サーフェイスにコピーする。

以下のリストに示すように、MSYUV はパックされた YUV フォーマットを RGB に変換する :
  • UYVY -> RGB16, RGB8
  • YUY2 -> RGB16, RGB8
  • YVYU -> RGB16, RGB8

フィルタの詳細については、「AVI デコンプレッサ」を参照すること。


NABTS/FEC VBI CODEC フィルタ

NABTS/FEC VBI CODEC はアナログ TV フィルタ グラフ内のカーネルモード ストリーム クラス フィルタである。キャプチャ された VBI ラインを処理し、NABTS データストリームに含まれるデコード処理やフォワードエラー修正をされた SLOP パケットを BDA SLIP デフレーマ、BDA IP シンク そして最終的には Winsock に出力する。このフィルタにはアプリケーションから呼び出し可能なインターフェイスはない。

NABTS/FEC VBI CODEC は 2 つのピンを持つ、VBI と HQNABTS である。VBI ピンはキャプチャ フィルタがロー VBI データを出力しているときに用いられ、HWNABTS はキャプチャ フィルタがデコードされた VBI データを出力しているときに用いられる、この場合、NABTS/FEC VBI CODEC は単にそのデータを BDA SLIP デフレーマ に渡すだけである。

NABTS/FEC VBI CODEC はGrapEdit 内で "WDM Streaming VBI CODEC" カテゴリにある。これはカーネルモード フィルタなので、アプリケーションは直接 co-create できないが、デバイスとフィルタの列挙 で説明されているように、システム デバイス列挙子 を使ってインスタンス化しなければならない。このフィルタは IFilterGraph::AddFilter メソッドを使ってグラフに手動で追加されなければならない、キャプチャ グラフ ビルダ はこのフィルタをグラフに追加するためには使用できない。


Null レンダリング フィルタ

このフィルタは、サンプル データの表示やレンダリングを行わない、受け取ったすべてのサンプルを破棄するレンダラである。

Null レンダラは、グラフの出力ピンとダウンストリーム接続が必要である、しかし当該ピンからのデータをレンダリングしないことに注意すること。出力ピンを Null レンダラに接続することで、データのレンダリングを行わない接続を実現できる。

フィルタ インターフェイス | IBaseFilter
入力ピン メディア タイプ | 任意のメディア タイプ。
入力ピン インターフェイス | IMemInputPin、IPin、IQualityControl
出力ピン メディア タイプ | 利用できない。
出力ピン インターフェイス | 利用できない。
フィルタ CLSID | CLSID_NullRenderer
プロパティ ページ CLSID | プロパティ ページなし。
実行モジュール | Qedit.dll
メリット | MERIT_DO_NOT_USE
カテゴリ | CLSID_LegacyAmFilterCategory


オーバーレイ ミキサー フィルタ

オーバーレイ ミキサー フィルタは、基本的には Microsoft® DirectDraw® ベースのビデオ レンダラである。このフィルタは転送先カラー キーイングを使用して、ビデオ サーフェスを Line 21 クローズド キャプションまたはデジタル ビデオ ディスク (DVD) サブピクチャ データなどのシナリオのオーバーレイとミキシングする。このフィルタは、主に DVD 再生アプリケーションやビデオ キャプチャ アプリケーションで使用されるが、ビデオ サーフェスにオーバーレイを適用する必要がある任意のシナリオで使用できる。

アプリケーションが IDVDGraphBuilder インターフェイスおよび ICaptureGraphBuilder2 インターフェイスを使用してグラフを作成すると、このフィルタは自動的にフィルタ グラフに追加される。メリットが MERIT_DO_NOT_USE であるので、オーバーレイ ミキサーは、ファイルのレンダリング時にフィルタ グラフ マネージャによって自動的にグラフに適用されることはない。ゲーム アプリケーションはオーバーレイ ミキサーを制限付きで使用して、ビデオをゲーム画面に追加することができる。

(注 : オーバーレイ ミキサー 2 フィルタは、2 つの点を除いてオーバーレイ ミキサーと同じである。オーバーレイ ミキサーは、VIDEOINFO および VIDEOINFO2 フォーマット タイプをサポートするが、オーバーレイ ミキサー 2 は VIDEOINFO2 フォーマット タイプしかサポートしない。そして、オーバーレイ ミキサー 2 のメリットは MERIT_UNLIKELY で、これはフィルタ グラフ マネージャを使用してファイルをレンダリングするときに、場合によっては自動的にグラフに適用されることがあることを意味する。このフィルタは、主に TV プレビュー/キャプチャ グラフに使用される。)

アプリケーションは、オーバーレイ ミキサーの特定の動作を IMixerPinConfig2 インターフェイスを介して制御することができるが、このトピックで説明するように、アプリケーション開発者はミキサーの内部動作を気にする必要はない。以下の情報は、フィルタ開発者や、オーバーレイ ミキサーの DirectDraw 排他モードを使用するゲーム開発者を対象にしている。

内部動作

オーバーレイ ミキサーは、入力ストリームごとに入力ピンを公開する。一般には、ビデオ データ用のピン 0、Line 21 および DVD サブピクチャ データ用のピン 1 および 2 の 3 つの入力ピンがある。内部的にはオーバーレイ ミキサーは DirectDraw を使用してビデオをレンダリングする。オーバーレイ ミキサーは、デスクトップ全体を構成するプライマリ サーフェスと、ピン 0 に接続されたビデオ ストリームのサイズによってその矩形が定義されるオーバーレイ サーフェスを持つ DirectDraw オブジェクトを作成する。デコーダがカラー キーを指定しない場合、オーバーレイ ミキサーはデフォルトのカラー キーとして、最近のグラフィックス カードの場合はダーク グレー、古い 256 色カードの場合はマゼンタを使用する。

注 : オーバーレイ ミキサーの現在のバージョンでは、オーバーレイ サーフェス上の同じ場所で同時にレンダリングする 2 つのビデオ ストリームをデコーダが渡した場合、その結果は不定である。このような状況は、サブピクチャと Line 21 ストリームの両方を含む DVD で発生することがある。ビデオにフリッカーが発生するか、いずれか一方のストリームが表示される。

ビデオ デコーダとのアップストリーム接続

通常、オーバーレイ ミキサーの入力ピンは、アップストリームのビデオ デコーダ (別のデコーダが Line 21 または DVD サブピクチャ データを処理する場合は複数のデコーダ) に接続する。入力ビデオ データは、必ずオーバーレイ ミキサーのピン 0 に接続する必要がある。Line 21 またはサブピクチャ データ ストリームは、それが同じビデオ デコーダから入力されるかどうかに関係なく、ピン 1 またはそれ以降に接続する。デコーダが、ホスト CPU を排他的に使用するソフトウェア デコーダの場合、デコーダとオーバーレイ ミキサーのピン 0 との間の接続は、標準 IMemInputPin インターフェイス接続になる。デコーダがハードウェア アクセラレーションを利用する場合、オーバーレイ ミキサーのピン 0 への接続は IAMVideoAccelerator 接続でなければならない。これら 2 種類の接続は互いに排他的である。

ハードウェア デコーダをラップしてビデオ ポート経由でオーバーレイ ミキサーに接続するフィルタは、IVPConfig を実装する必要がある。オーバーレイ ミキサーは IVPNotify インターフェイスを実装する。このフィルタは、各種の制御情報を設定および取得するためにデコーダ上の IVPConfig で使用される。このメカニズムにより、デコーダが必要なオーバーレイ サーフェスに関する情報を指定できる一方、オーバーレイ ミキサーは、ビデオ メモリ内でのそれらのサーフェスの位置をデコーダに通知することが可能になる。またオーバーレイ ミキサーは、ビデオ矩形が正常にスケーリングされることを保証する。ビデオ キャプチャ シナリオは、プレビュー イメージのスケーリングとインターリーブされたビデオ フレームのキャプチャに関して特定の問題を提示する。ハードウェア ビデオ キャプチャ デバイスのフィルタまたは WDM ドライバの開発に関する詳細については、「IVPConfig」および「IVPNotify」を参照すること。

オーバーレイ ミキサーは、1394 または USB キャプチャ シナリオでは使用されない。オーバーレイ ミキサーは、PCI バス上でのビデオ キャプチャに使用される。

ビデオ レンダラとのダウンストリーム通信

オーバーレイ ミキサーに接続された Microsoft® DirectShow® ビデオ レンダラ フィルタは、実際はビデオをまったくレンダリングしない。その接続は、IMemInputPin 接続ではなく、IOverlay 接続である。これにより、オーバーレイ ミキサーが実際のレンダリングを行えるようになり、ビデオ レンダラの役割はウィンドウの作成とデスクトップ上でのウィンドウのサイズと位置の制御だけになる。このウィンドウは、最上位のウィンドウまたはアプリケーション内の子ウィンドウを意味する。オーバーレイ ミキサーとビデオ レンダラは、ビデオ レンダラ側の IOverlay とオーバーレイ ミキサー側の IOverlayNotify を使用して、グラフ処理中に連続的に対話を行う。ウィンドウ サイズおよび位置情報に加え、ビデオ レンダラは、矩形クリッピングを管理する DirectDraw にウィンドウ ハンドルをオーバーレイ ミキサー経由で渡す。アプリケーションは、IVideoWindow インターフェイスおよび IBasicVideo2 インターフェイスを介してビデオ レンダラを制御することができる。

DirectDraw 排他モード

オーバーレイ ミキサーの DirectDraw 排他モードは、ゲームで画面の一部にビデオを表示できるようにする。このモードでは、オーバーレイ ミキサーは、ビデオ レンダラによって提供されたウィンドウ内ではなく、ゲーム アプリケーションによって作成された DirectDraw サーフェスにビデオを直接レンダリングする。これにより、ゲームはカラー キーを制御できる。オーバーレイ ミキサーを DirectDraw 排他モードで使用するには、オーバーレイ ミキサーのインスタンスを作成し、フィルタ グラフを作成する前にその IDDrawExclModeVideo インターフェイスを取得し、DirectDraw サーフェスをオーバーレイ ミキサーに追加する。オーバーレイ ミキサーにより、レンダリングが DirectDraw サーフェスで行われる。このモードに関する 1 つの重要な制限として、ゲームが実際のビデオ ビットにアクセスできないということがある。IDDrawExclModeVideo を使用した場合、アプリケーションはプライマリ サーフェスを作成し、オーバーレイ ミキサーはオーバーレイ サーフェスを作成する。

また、DirectDraw 排他モードを使用して (たとえば Web ページ内で) ウィンドウレス レンダリングを行うこともできるが、このような処理は推奨されない。その理由は、オーバーレイ ミキサーがこのモードでミキシングを行わないからである。これは、Line 21 またはサブピクチャ データを表示できないことを意味する。ウィンドウレス モードで DVD 再生アプリケーションを書く場合は、MSWebDVD ActiveX® コントロールを使用するアプローチが推奨される。

フィルタ インターフェイス | IAMOverlayFX、 IAMVideoDecimationProperties、 IBaseFilter、 IDDrawExclModeVideo、 IKsPropertySet、 IMediaPosition、 IMediaSeeking、 IQualProp
入力ピン メディア タイプ メジャー タイプ : MEDIATYPE_Video
サブタイプ :
  • MEDIASUBTYPE_Overlay (ピン 0 のみ)
  • DirectDraw YUV フォーマット : MEDIASUBTYPE_YUVxx (ピン 0 のみ)
  • DirectDraw ビデオ アクセラレーション フォーマット : MEDIASUBTYPE_DVAxxx (ピン 0 のみ)
  • Microsoft® DirectDraw® RGB フォーマット : MEDIASUBTYPE_RGBxx (すべての入力ピン)
フォーマット タイプ: Format_VIDEOINFO、Format_VIDEOINFO2
入力ピン インターフェイス | IAMVideoAccelerator、 IKsPropertySet、 IMemInputPin、 IMixerPinConfig、 IMixerPinConfig2、 IOverlay (ピン 0 のみ)、 IPin、 IPinConnection、 IQualityControl、 IVPNotify、 IVPNotify2
出力ピン メディア タイプ | MEDIATYPE_Video、MEDIASUBTYPE_Overlay
出力ピン インターフェイス | IPin、 IQualityControl
フィルタ CLSID | CLSID_OverlayMixer
プロパティ ページ CLSID | プロパティ ページなし。
実行モジュール | qdvd.dll
メリット | MERIT_DO_NOT_USE
カテゴリ | CLSID_LegacyAmFilterCategory


オーバーレイ ミキサー 2 フィルタ

オーバーレイ ミキサー 2 フィルタは機能的にはオーバーレイ ミキサーと同じだが、メリットが高く、自動的にフィルタ グラフに追加される。オーバーレイ ミキサー 2 フィルタは、TV キャプチャ/プレビュー グラフ内の非 DVD MPEG-2 ファイルをレンダリングするときにフィルタ グラフ マネージャがオーバーレイ ミキサーをグラフに追加できるように用意されている。このような処理は、メリットが MERIT_DO_NOT_USE であるオリジナルのオーバーレイ ミキサーでは不可能である。もう 1 つの違いとして、オーバーレイ ミキサーが VIDEOINFO および VIDEOINFO2 フォーマット タイプをサポートするのに対し、オーバーレイ ミキサー 2 は VIDEOINFO2 フォーマット タイプしかサポートしない。オーバーレイ ミキサーとオーバーレイ ミキサー 2 のどちらを選択するかは、グラフを作成したコンポーネント、すなわちフィルタ グラフ マネージャ、キャプチャ グラフ ビルダ、または DVD グラフ ビルダによって異なる。アプリケーションから見れば、両者は同じインターフェイスと機能を持つ同一のフィルタである。

オーバーレイ ミキサーに関する説明もオーバーレイ ミキサー 2 に当てはまる。

フィルタ インターフェイス | IAMOverlayFX、 IAMVideoDecimationProperties、 IBaseFilter、 IDDrawExclModeVideo、 IKsPropertySet、 IMediaPosition、 IMediaSeeking、 IQualProp
入力ピン メディア タイプ メジャー タイプ : MEDIATYPE_Video
サブタイプ :
  • MEDIASUBTYPE_Overlay (ピン 0 のみ)
  • Microsoft® DirectDraw® RGB フォーマット : MEDIASUBTYPE_RGBxx (すべての入力ピン)
  • DirectDraw YUV フォーマット : MEDIASUBTYPE_YUVxx (ピン 0 のみ)
  • DirectDraw ビデオ アクセラレーション フォーマット : MEDIASUBTYPE_DVAxxx (ピン 0 のみ)
フォーマット タイプ: Format_VIDEOINFO2
入力ピン インターフェイス | IAMVideoAccelerator、 IKsPropertySet、 IMemInputPin、 IMixerPinConfig、 IMixerPinConfig2、 IOverlay (ピン 0 のみ)、 IPin、 IPinConnection、 IQualityControl、 IVPNotify、 IVPNotify2
出力ピン メディア タイプ | MEDIATYPE_Video、MEDIASUBTYPE_Overlay
出力ピン インターフェイス | IPin、 IQualityControl
フィルタ CLSID | CLSID_OverlayMixer2
プロパティ ページ CLSID | プロパティ ページなし。
実行モジュール | qdvd.dll
メリット | MERIT_UNLIKELY
カテゴリ | CLSID_LegacyAmFilterCategory


QT デコンプレッサ フィルタ

QT デコンプレッサ フィルタは、Apple® QuickTime® 2.0 ビデオを圧縮解除する。通常、このフォーマットは古い QuickTime ファイルで使用されている。

フィルタ インターフェイス | IBaseFilter
入力ピン メディア タイプ MEDIATYPE_Video、FORMAT_VideoInfo

次のサブタイプが有効である。
  • MEDIASUBTYPE_QTRpza
  • MEDIASUBTYPE_QTSmc
  • MEDIASUBTYPE_QTRle
  • MEDIASUBTYPE_QTJpeg
入力ピン インターフェイス | IMemInputPin、IPin、IQualityControl
出力ピン メディア タイプ | MEDIATYPE_Video、MEDIASUBTYPE_NULL、FORMAT_VideoInfo
出力ピン インターフェイス | IMediaPosition、IMediaSeeking、IPin、IQualityControl
フィルタ CLSID | CLSID_QTDec
プロパティ ページ CLSID | プロパティ ページなし。
実行モジュール | quartz.dll
メリット | MERIT_NORMAL
カテゴリ | CLSID_LegacyAmFilterCategory


QuickTime ムービー パーサー フィルタ

QuickTime ムービー パーサー フィルタは、Apple® QuickTime® データをオーディオ ストリームとビデオ ストリームに分割する。このフィルタは QuickTime 2.0 以前をサポートする。入力ピンは、非同期ファイル ソース フィルタまたはURL ファイル ソース フィルタなどのソース フィルタに接続される。このパーサーは、AVI デコンプレッサまたは QT デコンプレッサ フィルタを使用して、QuickTime ファイルを圧縮解除する。このフィルタは、ビデオ ストリーム用の 1 つの出力ピンとオーディオ ストリーム用の 1 つの出力ピンを作成する。

フィルタ インターフェイス | IAMMediaContent、IBaseFilter
入力ピン メディア タイプ | MEDIATYPE_Stream、MEDIASUBTYPE_QTMovie;
入力ピン インターフェイス | IPin、IQualityControl
出力ピン メディア タイプ
  • MEDIATYPE_Video、MEDIASUBTYPE_NULL、FORMAT_VideoInfo
  • MEDIATYPE_Audio、MEDIASUBTYPE_NULL、FORMAT_WaveFormatEx
出力ピン インターフェイス | IMediaPosition、IMediaSeeking、IPin、IQualityControl
フィルタ CLSID | CLSID_QuickTimeParser
プロパティ ページ CLSID | プロパティ ページなし。
実行モジュール | quartz.dll
メリット | MERIT_NORMAL
カテゴリ | CLSID_LegacyAmFilterCategory


SAMI (CC) パーサー フィルタ

SAMI (Synchronized Accessible Media Interchange) ファイルからのキャプション データを解析する。

SAMI は、HTML に似たテキスト フォーマットであり、タイム ベース キャプションのエンコードに使用される。このフィルタは、SAMI データをテキスト ストリームに変換する。ストリームの各サンプルには、キャプション エントリと共に、フォーマット情報が含まれている。サンプルのタイム スタンプは、SAMI ファイルのタイム情報から生成される。

このフィルタは、内部スクリプト コマンド レンダリング フィルタと共に使用するように設計されている。内部スクリプト コマンド レンダラは、テキスト サンプルを受け取り、イベント通知としてアプリケーションに送る。詳細については、「注意」を参照すること。

フィルタ インターフェイス | IAMStreamSelect、IBaseFilter
入力ピン メディア タイプ | MEDIATYPE_Stream
入力ピン インターフェイス | IPin、IQualityControl
出力ピン メディア タイプ | MEDIATYPE_Text、MEDIASUBTYPE_NULL
出力ピン インターフェイス | IMediaSeeking、IPin、IQualityControl
フィルタ CLSID | {33FACFE0-A9BE-11D0-A520-00A0D10129C0}
プロパティ ページ CLSID | プロパティ ページなし
実行モジュール | quartz.dll
メリット | MERIT_UNLIKELY
カテゴリ | CLSID_LegacyAmFilterCategory

注意

次に示すのは、単純な SAMI ファイルである。

<SAMI>
<Head>
<STYLE TYPE="text/css"> <!--
    .ENCC {Name: English; lang:en-US; SAMI_TYPE: CC;}
    .FRCC {Name: French; lang:fr-FR; SAMI_TYPE: CC;}
    #NORMAL {Name: Normal; font-family: arial;}
    #GREENTEXT {Name: GreenText; color:green; font-family: verdana;}
-->
</STYLE>
</Head>
<BODY>
<Sync Start=1000>
    <P CLASS="ENCC">One
    <P CLASS="FRCC">Un

<Sync Start=2000>
    <P CLASS="ENCC">Two
    <P CLASS="FRCC">Deux

<Sync Start=3000>
    <P CLASS="ENCC">Three
    <P CLASS="FRCC">Trois
</BODY>
</SAMI>

STYLE タグでは、英語 (.ENCC) とフランス語 (.FRCC) の 2 つの言語設定が定義される。また、#NORMAL および #GREENTEXT という 2 つのスタイルも定義される。各 SYNC タグでは、キャプションの開始タイムをミリ秒単位で定義する。P タグにはキャプション テキストが含まれ、CLASS 属性にはキャプションの適用先となる言語設定を指定する。

各言語とスタイルについて、フィルタは論理ストリームを作成する。常に、1 つの言語ストリームと 1 つのスタイル ストリームを有効にできる。フィルタがサンプルを生成する際は、現在の言語のキャプションを選択し、現在のスタイルを適用する。デフォルトでは、ファイルで宣言する最初の言語とスタイルが有効になる。アプリケーションは IAMStreamSelect::Enable メソッドを使って、異なるストリームを有効にできる。

デフォルトの設定では、サンプル ファイルの最初のキャプションによって、次の出力が作成される。

<P STYLE=" Name: English; lang:en-US; SAMI_TYPE: CC; Name: Normal; font-family: arial;">One

出力が内部スクリプト コマンド レンダラに送られると、このフィルタは EC_OLE_EVENT イベント通知を送る。2 つ目のイベント パラメータは、キャプション テキストを持つ BSTR である。アプリケーションは、イベントを取得してキャプションを表示できる。

次のサンプル コードは、SAMI ファイルのレンダリング方法、ストリーム情報の取得方法、ストリームを有効にする方法、およびキャプション テキストの表示方法について示している。この例では、以前の SAMI ファイルが C:\Sami_test_file.sami として保存されていることを想定している。簡潔にするために、このサンプル コードでは、IAMStreamSelect::Enable メソッドを呼び出す際にハード コーディングされたストリーム インデックスを使用している。

void __cdecl main()
{
    HRESULT hr;
    IGraphBuilder *pGraph;
    IMediaControl *pMediaControl;
    IMediaEventEx *pEv;
    IBaseFilter   *pSAMI;

    CoInitialize(NULL);

    // フィルタ グラフ マネージャを作成する。
    CoCreateInstance(CLSID_FilterGraph, NULL, CLSCTX_INPROC,
                        IID_IGraphBuilder, (void **)&pGraph);
    pGraph->QueryInterface(IID_IMediaControl, (void **)&pMediaControl);
    pGraph->QueryInterface(IID_IMediaEventEx, (void**)&pEv);

    // グラフを作成し、SAMI パーサーを探す。
    pGraph->RenderFile(L"C:\\Sami_test_file.sami", NULL);
    hr = pGraph->FindFilterByName(L"SAMI (CC) Parser", &pSAMI);
    if (SUCCEEDED(hr))
    {
        IAMStreamSelect *pStrm = NULL;
        hr = pSAMI->QueryInterface(IID_IAMStreamSelect, (void**)&pStrm);
        if (SUCCEEDED(hr))
        {
            DWORD dwStreams = 0;
            pStrm->Count(&dwStreams);
            printf("Stream count: %d\n", dwStreams);

            // フランス語および "GreenText" を選択する。
            hr = pStrm->Enable(1, AMSTREAMSELECTENABLE_ENABLE);
            hr = pStrm->Enable(3, AMSTREAMSELECTENABLE_ENABLE);

            // 各論理ストリームの名前を出力する。
            for (DWORD index = 0; index < dwStreams; index++)
            {
                DWORD dwFlags;
                WCHAR *wszName;
                hr = pStrm->Info(index, NULL, &dwFlags, NULL, NULL, &wszName, NULL, NULL);
                wprintf(L"Stream %d: %s [%s]\n", index, wszName,
                    (dwFlags ?  L"ENABLED" : L"DISABLED"));
                CoTaskMemFree(wszName);
            }
            pStrm->Release();
        }
        pSAMI->Release();
    }

    // グラフを実行し、キャプションを表示する。
    pMediaControl->Run();
    while (1)
    {
        long evCode, lParam1, lParam2;
        pEv->GetEvent(&evCode, &lParam1, &lParam2, 100);

        if (evCode == EC_OLE_EVENT) {
            wprintf(L"%s\n", (BSTR)lParam2);
        }
        pEv->FreeEventParams(evCode, lParam1, lParam2);

        if (evCode == EC_USERABORT || evCode == EC_COMPLETE || evCode == EC_ERRORABORT)
            break;
    }

    // クリーン アップする。
    pMediaControl->Release();
    pEv->Release();
    pGraph->Release();
    CoUninitialize();
}

このフィルタは、IAsyncReader インターフェイスを使ってソース フィルタからサンプルを取得している。そのため、このフィルタは、入力ピン上で IMemInputPin インターフェイスをサポートしていない。


サンプル グラバ フィルタ

サンプル グラバ フィルタは、サンプルがフィルタ グラフを通過するときにそれを取得する方法を提供する。このフィルタは、1 つの入力ピンと 1 つの出力ピンを持つ変換フィルタである。このフィルタは、すべてのサンプルをそのままダウンストリームに渡すので、データ ストリームを変更せずにフィルタ グラフに挿入することができる。これにより、アプリケーションは ISampleGrabber インターフェイスでメソッドを呼び出すことで、フィルタから個々のサンプルを取得できる。

データをレンダリングせずにサンプルを取得する場合は、サンプル グラバ フィルタを Null レンダリング フィルタに接続する。

このフィルタの使用方法については、「メディア サンプルの入手」を参照すること。

フィルタ インターフェイス | IBaseFilter、ISampleGrabber
入力ピン メディア タイプ | 任意のメディア タイプ。
入力ピン インターフェイス | IMemInputPin、IPin、IQualityControl
出力ピン メディア タイプ | 任意のメディア タイプ。入力メディア タイプと同じ。
出力ピン インターフェイス | IPin、IQualityControl
フィルタ CLSID | CLSID_SampleGrabber
プロパティ ページ CLSID | プロパティ ページなし。
実行モジュール | Qedit.dll
メリット | MERIT_DO_NOT_USE
カテゴリ | CLSID_LegacyAmFilterCategory


スマート ティー フィルタ

スマート ティー フィルタは、ビデオ ストリームをプレビュー ストリームとキャプチャ ストリームに分割するためにビデオ キャプチャ グラフで使用される。この処理は、ほかにデータをコピーすることなく行われる。出力ピンは、ダウンストリーム接続においてサポートされるすべてのメディア タイプをサポートする。

スマート ティー フィルタは、ビデオ キャプチャ フィルタがキャプチャとプレビュー用に個別のピンを提供しない場合に便利である。スマート ティー フィルタは、それによってキャプチャ パフォーマンスが低下することがない場合にのみ、プレビュー データを配送する。またスマート ティー フィルタは、プレビュー ストリームからタイム スタンプを削除する。キャプチャ グラフ ビルダは、必要に応じてスマート ティー フィルタを自動的に挿入する。詳細については、「キャプチャ アプリケーションの書き方」を参照すること。

以下の図に、スマート ティー フィルタを使用する一般的なキャプチャ グラフを示す。

スマート ティー フィルタの使い方

フィルタ インターフェイス | IBaseFilter
入力ピン メディア タイプ | MEDIATYPE_Video、MEDIASUBTYPE_NULL
入力ピン インターフェイス | IMemInputPin、IPin、IQualityControl
出力ピン メディア タイプ | MEDIATYPE_Video、MEDIASUBTYPE_NULL
出力ピン インターフェイス | IAMStreamControl、 IPin、 IQualityControl
フィルタ CLSID | CLSID_SmartTee
プロパティ ページ CLSID | プロパティ ページなし。
実行モジュール | qcap.dll
メリット | MERIT_DO_NOT_USE
カテゴリ | CLSID_LegacyAmFilterCategory


Tee/Sink-to-Sink コンバータ

Tee/Sink-to-Sink コンバータ はカーネルモードの sProxy ベースのフィルタである。VBI データがレンダリングされたりキャプチャされたりするアナログ ビデオ TV フィルタ グラフ内で用いられる。このフィルタはアップストリームを WDM ビデオ キャプチャ フィルタに接続し、カーネルモードとユーザーモード間の変換に負荷をかけず、カーネルモード内でデータのストリームをコピーする効率的な手法を提供する。それは受け取った各データブロックをすべての出力ピンに出力し、ダウンストリーム CODEC は指定されたデコードべき VBI データを見つける責任を持つ。

Tee/Sink-to-Sink コンバータ の他の重要な機能は実際にはアプリケーション プログラマには関係ないが、ここでは完結について言及する。"Sink-to-Sink" 性能は Microsoft® Windows 98® プラットフォームに対して、それぞれが入ってくる IRP だけをサポートする 2 つのドライバの接続を可能にするために要求されていた。この機能は WDM アーキテクチャの別のコンポーネントによって実行されている。

Tee/Sink-to-Sink コンバータ は GrapEdit 内で "WDM Streaming Tee/Splitter Devices" カテゴリにある。これはカーネルモード フィルタなので、アプリケーションは直接 co-create できないが、デバイスとフィルタの列挙 で説明されているように、システム デバイス列挙子 を使ってインスタンス化しなければならない。


TV オーディオ フィルタ

TV オーディオ フィルタは、テレビ オーディオ デコーディング、ステレオ/モノラルの選択、およびセカンダリ オーディオ プログラム (SAP) の選択に関する制御を提供する。

このフィルタは、Microsoft® Windows® 98 および Windows 2000 で利用可能である。

フィルタ インターフェイス | IAMTVAudio、IPersistPropertyBag、ISpecifyPropertyPages、IKsPropertySet
入力ピン メディア タイプ | MEDIATYPE_AnalogAudio
入力ピン インターフェイス | IKsPropertySet
出力ピン メディア タイプ | MEDIATYPE_AnalogAudio
出力ピン インターフェイス | IKsPropertySet
フィルタ CLSID | CLSID_TVAudioFilter
プロパティ ページ CLSID | CLSID_TVAudioFilterPropertyPage
実行モジュール |
メリット |
カテゴリ | CLSID_AudioInputDeviceCategory


TV チューナー フィルタ

TV チューナー フィルタは、アナログ ブロードキャストまたはケーブル チャンネルのどちらを表示するかを選択する。この 1 つの出力ストリームは、アナログ ベースバンド ビデオ用のハードウェア パスである。この出力は、アナログ ビデオ クロスバー フィルタに接続する必要がある。入力ピンには、ケーブル入力とアンテナ入力がある。

このフィルタは、Microsoft® Windows 98® および Windows 2000 で利用可能である。

フィルタ インターフェイス | IBaseFilter、IAMTVTuner、ISpecifyPropertyPages、IPersistPropertyBag、IKsObject、IKsPropertySet
入力ピン メディア タイプ | 利用できない。
入力ピン インターフェイス | 利用できない。
出力ピン メディア タイプ | ビデオ : MEDIATYPE_AnalogVideo、KSDATAFORMAT_SUBTYPE_NONE オーディオ : MEDIATYPE_AnalogAudio、MEDIASUBTYPE_NULL
出力ピン インターフェイス | IPin
フィルタ CLSID | CLSID_CTVTunerFilter
プロパティ ページ CLSID | CLSID_TVTunerFilterPropertyPage
実行モジュール | KSTVTune.ax
メリット |
カテゴリ | CLSID_VideoInputDeviceCategory


VBI サーフェイス アロケータ

VBI サーフェイス アロケータは、ハードウェアのビデオ ポート キャプチャがあるアナログ TV グラフ内の、VBI バッファの割り当てをコントロールする。 Bt829 デコーダなどのデバイスでは、フレーム バッファは複数の VBI キャプチャ バッファを持っている可能性がある。そのバッファには、一般的にビデオ ポートとして知られる、ハードウェア独自のメカニズムを通してアクセスする。VBISurf フィルタはキャプチャ フィルタからダウンストリーム フィルタと接続し、出力ピンを持たない。そのフィルタは DirectDraw を通してオーバーレイ ミキサーと密接して動作し、同じ限定された SVGA フレーム バッファ メモリを利用し、ハードウェアのビデオ ポートで調整された操作を行う。

フィルタ インターフェイス | IBaseFilter, IVPVBINotify
入力ピン メディア タイプ | MEDIATYPE_Video, MEDIASUBTYPE_VPVBI
入力ピン インターフェイス | IVPVBINotify、IKsPropertySet
出力ピン メディア タイプ | MEDIATYPE_NULL, MEDIASUBTYPE_NULL (出力ピンには何も接続されない。)
出力ピン インターフェイス | 利用できない。
フィルタ CLSID | CLSID_VBISurfaces
プロパティ ページ CLSID | プロパティ ページなし。
実行モジュール | vbisurf.ax
メリット | MERIT_NORMAL
カテゴリ | CLSID_LegacyAmFilterCategory


VFW キャプチャ フィルタ

このフィルタは、Video for Windows を使用する古いビデオ キャプチャ ハードウェア用である。

このフィルタには 2 つの出力ピンがあり、1 つはキャプチャ、もう 1 つはプレビューまたはオーバーレイと呼ばれる。

フィルタ インターフェイス | IPersistPropertyBag、IAMVfwCaptureDialogs、IAMFilterMiscFlags、IBaseFilter、ISpecifyPropertyPages、IVfwCaptureOptions、IOverlayNotify
入力ピン メディア タイプ | 利用できない。
入力ピン インターフェイス | 利用できない。
出力ピン メディア タイプ | キャプチャ : MEDIATYPE_Video、MEDIASUBTYPE_NULL、FORMAT_VideoInfo オーバーレイ : MEDIATYPE_Video、MEDIASUBTYPE_Overlay、FORMAT_VideoInfo プレビュー : MEDIATYPE_Video、MEDIASUBTYPE_NULL、FORMAT_VideoInfo
出力ピン インターフェイス | キャプチャ : IAMBufferNegotiation、IAMDroppedFrames、IAMPushSource、IAMStreamConfig、IAMStreamControl、IAMVideoCompression、IKsPropertySet、IPin、IQualityControl オーバーレイ : IAMStreamControl、IKsPropertySet、IPin、IQualityControl プレビュー : IAMPushSource、IAMStreamControl、IKsPropertySet、IPin、IQualityControl
フィルタ CLSID | CLSID_VfwCapture
プロパティ ページ CLSID | CLSID_CaptureProperties
実行モジュール | qcap.dll
メリット | MERIT_DO_NOT_USE
カテゴリ | CLSID_VideoInputDeviceCategory


VGA 16 色 ディザラ フィルタ

VGA 16 カラー ディザラ フィルタは、旧式の 16 色モニタ上で AVI および MPEG ビデオ ストリームを表示できるように、RGB 色タイプを 4 ビットのカラー ディスプレイに変換する。このフィルタは、デコンプレッサ フィルタとビデオ レンダリング フィルタとの間のグラフに挿入される。

フィルタ インターフェイス | IBaseFilter
入力ピン メディア タイプ | MEDIATYPE_Video、MEDIASUBTYPE_RGB8
入力ピン インターフェイス | IMemInputPin、IPin、IQualityControl
出力ピン メディア タイプ | MEDIATYPE_Video、MEDIASUBTYPE_RGB4
出力ピン インターフェイス | IMediaPosition、IMediaSeeking、IPin、IQualityControl
フィルタ CLSID | CLSID_Dither
プロパティ ページ CLSID | プロパティ ページなし。
実行モジュール | quartz.dll
メリット | MERIT_UNLIKELY
カテゴリ | CLSID_LegacyAmFilterCategory


ビデオ レンダリング フィルタ

ビデオ レンダリング フィルタは汎用のビデオ レンダラであり、圧縮解除されたビデオ データを生成する任意のビデオ変換フィルタに接続できる。

ビデオ カードがサポートしている場合、ビデオ レンダリング フィルタは Microsoft® DirectDraw® のメソッドを使用する。フルスクリーン レンダリングは、フィルタ グラフ マネージャから有効になる。フィルタ グラフ マネージャは、一部の古いグラフィックス カードでは、必要に応じてビデオ レンダラと フルスクリーン レンダラを自動的に切り替える。そのため、事前にフィルタ グラフにフルスクリーン レンダラをインクルードする必要はない。新しいカードでは、ビデオ レンダラ自身がフルスクリーン レンダリングを実行する。

ビデオ グラフィックス カードが YUV オーバーレイ サービスをサポートしている場合、ビデオ レンダラは YUV フォーマットおよび RGB フォーマットを受け入れる。しかし、ビデオ レンダラが最初にアップストリーム フィルタに接続されると、必ず現在のモニタ設定の色数と一致する RGB フォーマットを要求することに注意するのが重要である。たとえば、ユーザーがモニタを 24 ビット色に設定している場合、アップストリーム フィルタは 24 ビット RGB のデータを提供できなくてはならない。グラフが実行状態でなくなると、ビデオ レンダラは適切な YUV カラー空間への動的なフォーマット変更をネゴシエーションする。ビデオ レンダラは、ビデオをレンダリングするために、DirectDraw の使用から GDI の使用に動的に切り替えなければならないこともあるため、最初に RGB フォーマットを要求する。GDI は、YUV カラー空間をサポートしていない。ビデオ メモリがほかのアプリケーションによって使われているか、またはビデオ表示矩形が複数のモニタ システムで 2 つのモニタにまたがっている、またはビデオ矩形が完全に画面上のほかのウィンドウによって隠されている場合、ビデオ レンダラは GDI に切り替える。

このフィルタは、フィルタ グラフ マネージャに独自の PID を持ち、フィルタ グラフ マネージャ上で対応するインターフェイス メソッドを呼び出すことで、アプリケーションはフィルタのプロパティを設定および取得できる。この場合ほかのほとんどの Microsoft® DirectShow® フィルタはアプリケーションからは見えない。

ビデオ レンダラを co-create するスレッドは ビデオ レンダラのウィンドウを作成したスレッドである。そのスレッドはビデオ レンダラのウィンドウにメッセージを送るメッセージ ループを持っていなければならない。

フィルタ インターフェイス | IBaseFilter、 IBasicVideo、 IBasicVideo2、 IDirectDrawVideo、 IKsPropertySet IMediaPosition、 IMediaSeeking、 IQualityControl、 IQualProp、 IVideoWindow
入力ピン メディア タイプ | MEDIATYPE_Video
入力ピン インターフェイス | IMemInputPin、IOverlay、IPin、IPinConnection、IQualityControl
出力ピン メディア タイプ | 利用できない。
出力ピン インターフェイス | 利用できない。
フィルタ CLSID | CLSID_VideoRenderer
プロパティ ページ CLSID | プロパティ ページなし。
実行モジュール | quartz.dll
メリット | MERIT_PREFERRED
カテゴリ | CLSID_LegacyAmFilterCategory


WAVE パーサー フィルタ

WAVE パーサー フィルタは、.wav、.au、または .aif ファイルからの WAV フォーマットのオーディオ データを解析する。アップストリーム フィルタは、非同期ファイル ソース フィルタ、URL ファイル ソース フィルタ、または WAV オーディオ データを含んだ、サードパーティの互換性の非同期ソース フィルタでなければならない。出力ストリームはオーディオ データで、直接オーディオ レンダリング フィルタに、または間に入るオーディオ変換フィルタに接続することができる。

フィルタ インターフェイス | IAMMediaContent、IBaseFilter、IPersistMediaPropertyBag
入力ピン メディア タイプ MEDIATYPE_Stream

次のサブタイプが有効
  • MEDIASUBTYPE_AIFF
  • MEDIASUBTYPE_AU
  • MEDIASUBTYPE_WAVE
入力ピン インターフェイス | IPin、IQualityControl
出力ピン メディア タイプ | MEDIATYPE_Audio、MEDIASUBTYPE_NULL
出力ピン インターフェイス | IPin"、IMediaSeeking
フィルタ CLSID | CLSID_WAVEParser {D51BD5A1-7548-11cf-A520-0080C77EF58A}
プロパティ ページ CLSID | プロパティ ページなし。
実行モジュール | quartz.dll
メリット | MERIT_UNLIKELY
カテゴリ | CLSID_LegacyAmFilterCategory


WDM ビデオ キャプチャ フィルタ

WDM ビデオ キャプチャ フィルタは実際にはカーネルモード KsProxy プラグインであり、(アナログ ビデオ デコーダとも呼ばれる) アナログ キャプチャ デバイスを制御する WDM ドライバのプロパティ ページと COM インターフェイスを提供する。もちろん、アプリケーションの視点からは、これはシステム デバイス列挙子を通して発見され得る単なるもう 1 つのフィルタである。KSProxy をベースにしたフィルタでは、フィルタのフレンドリ名はその下のドライバに依存するシステム デバイス列挙子はこのプラグインを使う各デバイスに固有のモニカを返す。詳細は、「デバイスとフィルタの列挙」と「ハードウェア デバイスがフィルタ グラフに参加する方法」を参照すること。

WDM ビデオ キャプチャ フィルタ を通して公開されるすべてのデバイスは以下に説明されるすべてのインターフェイスを実装する。個別のデバイスがどのインターフェイスをサポートするかを確認するのはアプリケーションの責任である。

フィルタ インターフェイス | デバイスの WDM ドライバは、次の 1 つまたは複数のインターフェイスをサポートしている場合がある。IAMExtDevice、IAMExtTransport、IAMTimecodeReader、IAMCameraControl、IAMVideoProcAmp、IAMAnalogVideoDecoder、 IAMVideoCompression、IAMVideoControl
入力ピン メディア タイプ | デバイスに依存する。
入力ピン インターフェイス | デバイスに依存する。
出力ピン メディア タイプ | デバイスに依存する。
出力ピン インターフェイス | デバイスに依存する (ビデオが圧縮されている場合)。 IAMStreamControl または IAMVideoCompression を含む場合がある。
フィルタ CLSID | デバイスに依存する。
プロパティ ページ CLSID | デバイスに依存する。
プラグイン実行モジュール | kswdmcap.ax
メリット | デバイスに依存する。
カテゴリ | CLSID_VideoInputDeviceCategory


WST CODEC

World Standard Teletext (WST) は PAL アナログ TV 信号上で VBI を使うデータ送信のヨーロッパ規格である。文字サービスとデータサービスの両方がこの規格で提供されている。WST CODEC はロー VBI サンプルを受け取り、(オプションとして) Teletxt サンプルを Tee/Sink-to-Sink コンバータ 経由でキャプチャ フィルタからデコードするカーネルモード フィルタである。この CODEC は WST デコーダ フィルタでデコードされ、フォワードエラー修正された Teletxt データをデコードとコピー両方あるいは一方をする。WST デコーダ は次にオーバーレイ ミキサーに送るビットマップを作成する。

WST CODEC は GrapEdit 内で "WDM Streaming VBI CODEC" カテゴリにある。これはカーネルモード フィルタなので、アプリケーションは直接 co-create できないが、デバイスとフィルタの列挙 で説明されているように、システム デバイス列挙子 を使ってインスタンス化しなければならない。


WST デコーダ

The WST デコーダ は WST CODEC からデコードされた World Standard Teletext データを受け取り、Microsoft が提供するフォントを使って オーバーレイ ミキサー のピン 2 にビットマップを出力するカーネルモード フィルタである。現在西欧の言語は規格化されているが、Unicode˜ フォントは現在提供されていない。WST デコーダ にはアプリケーションから呼び出し可能なインターフェイスはない。

WST デコーダ は GrapEdit 内で "WDM Streaming VBI CODEC" カテゴリにある。これはカーネルモード フィルタなので、アプリケーションは直接 co-create できないが、デバイスとフィルタの列挙 で説明されているように、システム デバイス列挙子 を使ってインスタンス化しなければならない。このフィルタは WST CODEC の出力ピンで ICaptureGraphBuilder2::RenderStream を呼び出すことによって自動的に追加される。


インターフェイス

このトピックには、Microsoft® DirectShow® COM インターフェイスのリファレンス情報を記載する。多様なハードウェア、ファイル フォーマット、およびストリーム操作をサポートするため、DirectShow は多数のインターフェイスを実装する。これらのインターフェイスの一部はアプリケーションで使用され、その他はフィルタおよびほかの DirectShow コンポーネントで内部的に使用される。

個々のアプリケーションでは一部のサブセットのみを使用する。必要なインターフェイスはアプリケーションの性質によって異なる。以下の一覧は、アプリケーション レベルのインターフェイスを目的ごとにまとめたものである。

  • フィルタ グラフの構築
  • フィルタ グラフの制御
  • オーディオのキャプチャとレンダリング
  • DVD
  • ビデオのキャプチャ
  • ビデオの編集
  • ファイルのエンコードとデコード
  • ビデオのレンダリング、拡大縮小、およびオーバーレイ
  • TV の調整
  • 外部デバイスの制御

参照 :

  • DirectShow COM インターフェイスの一覧 (アルファベット順)
  • フィルタ
  • DirectShow のコンポーネント

フィルタ グラフの構築

アプリケーションでは、以下のインターフェイスを使用して各種のフィルタ グラフを構築する。

インターフェイス | 目的
ICaptureGraphBuilder2 | ビデオ キャプチャ用のフィルタ グラフを構築する。
ICreateDevEnum | 利用可能なシステム デバイスを列挙する。
IDvdGraphBuilder | DVD のナビゲーションおよび再生に使用するフィルタ グラフを構築する。
IFilterGraph2 | フィルタを追加、削除、または接続する。
IFilterMapper2 | ユーザーのシステムに登録されているフィルタを列挙する。
IGraphBuilder | ファイルの再生またはカスタム ユースに使用するフィルタ グラフを構築する。
IGraphConfig | フィルタ グラフを動的に再構成する。
IGraphVersion | グラフの変更時期を判断する。

フィルタ グラフの制御

以下のインターフェイスは、フィルタ グラフを制御するメソッドを提供する。

インターフェイス | 目的
IAMGraphStreams | フィルタ グラフのライブ ストリームの同期をとる。
IEnumFilters | グラフのフィルタを列挙する。
IFilterChain | フィルタ チェーンを制御する。
IMediaControl | フィルタ グラフを実行、ポーズ、および停止する (グラフを構築する Automation 互換のメソッドも提供する)。
IMediaEventEx | グラフ内のイベントに応答する。
IMediaSeeking | ファイル内のシークを行う。
IQueueCommand | コマンドをキューに入れ、後で実行する。
IVideoFrameStep | ビデオ ストリーム内のコマ送りをする。

オーディオのキャプチャとレンダリング

以下のインターフェイスは、オーディオのキャプチャおよびレンダリングをサポートする。

インターフェイス | 目的
IAMAudioInputMixer | モノラル/ステレオ、ミキシング レベル、パン レベル、ラウドネス、高音域、低音域など、オーディオ入力の特性を調整する。
IAMDirectSound | ほかのアプリケーションにフォーカスがあるときサウンドを鳴らすかどうか、どのアプリケーション ウィンドウをサウンドに関連付けるかなど、Microsoft DirectSound® 互換デバイスの設定を制御する。
IAMResourceControl | オーディオ デバイスを事前に確保する。
IBasicAudio | オーディオのプロパティを設定する。

DVD

インターフェイス | 目的
IDvdCmd | コマンドが開始または完了するまで DVD ナビゲータをブロックする。
IDvdControl2 | カラオケを含む DVD ビデオのタイトルをナビゲートおよび再生する。
IDvdGraphBuilder | システム上の利用可能なソフトウェアおよびハードウェアから、DVD ビデオ再生に使用するフィルタ グラフを構築する。
IDvdInfo2 | DVD ディスクの各種属性または DVD ナビゲータの状態を照会する。
IDvdState | ユーザー セッションの状態をディスクに保存する。状態には、再生位置、ペアレンタル ロック レベル、およびリージョンが含まれる。

ビデオのキャプチャ

以下のインターフェイスは、Microsoft® Windows® Driver Model (WDM) デバイス、または旧来の Microsoft® Video for Windows® (VfW) デバイスを使用したビデオ キャプチャをサポートする。

インターフェイス | 目的
IAMAnalogVideoDecoder | WDM ビデオ キャプチャ カードによるビデオ信号のデジタル化を制御する。
IAMAnalogVideoEncoder | ハードウェア ビデオ エンコーダを制御する。
IAMBufferNegotiation | ピンのバッファ割り当てを制御する。
IAMCopyCaptureFileProgress | ファイル コピー操作の進行状況を受け取るコールバック インターフェイス。
IAMCrossbar | WDM のオーディオ ソースまたはビデオ ソースと、WDM キャプチャ デバイスの間のハードウェア接続を確立する。
IAMDroppedFrames | キャプチャ フィルタにキャプチャのパフォーマンスを照会する。
IAMStreamControl | 個々のストリームの開始タイムおよび終了タイムを制御する。
IAMVfwCaptureDialogs | VFW キャプチャ ドライバのダイアログ ボックスを表示する。
IAMVideoControl | キャプチャ デバイスからの画像を制御する。
IAMVideoProcAmp | 輝度、コントラスト、色相、飽和、ガンマ、鮮明度などのビデオ信号品質を調整する。
ICaptureGraphBuilder2 | ビデオ キャプチャ用のフィルタ グラフを構築する。
IFileSinkFilter2 | 出力ファイルの名前および属性を指定する。
ISampleGrabber | フィルタ グラフ内を通るメディア サンプルを取得する。

ビデオの編集

DES (DirectShow 編集サービス) は、以下のインターフェイスを提供する。

インターフェイス | 目的
IAMErrorLog | エラー ログのためのコールバック インターフェイス。
IAMSetErrorLog | エラー ログを設定または取得する。
IAMTimeline | タイムラインのプロパティを設定および取得し、タイムライン オブジェクトを作成する。
IAMTimelineComp | 合成の仮想トラックを挿入または取得する。
IAMTimelineEffect | エフェクトの優先順位を取得する。
IAMTimelineEffectable | タイムライン オブジェクトにエフェクトを追加する。
IAMTimelineGroup | グループのプロパティを設定および取得する。
IAMTimelineObj | タイムライン オブジェクトのプロパティを設定および取得する。
IAMTimelineSplittable | タイムライン オブジェクトを分割する。
IAMTimelineSrc | ソースのプロパティを設定および取得する。
IAMTimelineTrack | トラックのプロパティを設定および取得する。
IAMTimelineTrans | トランジションのプロパティを設定および取得する。
IAMTimelineTransable | タイムライン オブジェクトに移行部を追加する。
IAMTimelineVirtualTrack | 仮想トラックのプロパティを設定および取得する。
IMediaDet | メディア ファイルに関する情報を取得する。
IMediaLocator | ファイル名を検証する。
IPropertySetter | エフェクトまたは移行部のプロパティを設定する。
IRenderEngine | ビデオ編集プロジェクトをレンダリングする。
ISmartRenderEngine | スマート再圧縮を使用して、ビデオ編集プロジェクトをレンダリングする。
IXml2Dex | XML (Extensible Markup Language) でビデオ編集プロジェクトを保存およびロードする。

ファイルのエンコードとデコード

インターフェイス | 目的
IAMMediaContent | 作成者やタイトルなどのメタ データをストリームから取得する。
IAMOpenProgress | ファイルを開く処理の進捗状況を判定する。
IAMParse | MPEG ストリームの現在位置の解析時間を照会、設定する。
IAMStreamSelect | 再生する論理ストリームを制御し、それに関する情報を取得する。
IAMVfwCompressDialogs | VFW CODEC のダイアログ ボックスを表示する。
IAMVideoCompression | ビデオ圧縮のパラメータを設定する。
IConfigAsfWriter | ASF ライタ フィルタが ASF (Advanced Streaming Format) ファイルを書き込む方法を制御する。
IConfigAviMux | AVI Mux フィルタが AVI ファイルを書き込む方法を制御する。
IConfigInterleaving | AVI Mux フィルタが AVI ファイルを書き込むときのインターリーブを構成する。
IDVEnc | DV ビデオ エンコーダ フィルタのエンコード解像度を設定する。
IDVSplitter | デジタル ビデオ (DV) ストリームのフレームをダウングレードする。
IIPDVDec | DV ビデオ デコーダ フィルタのデコード解像度を設定する。
IPersistMediaPropertyBag | AVI ストリームの INFO チャンクおよび DISP チャンクを設定、取得する。

ビデオのレンダリング、拡大縮小、およびオーバーレイ

インターフェイス | 目的
IAMLine21Decoder | クローズド キャプション情報および設定にアクセスする。
IAMOverlayFX | ビデオ サーフェスにオーバーレイ エフェクトを適用する。
IAMVideoDecimationProperties | ビデオの本来のサイズよりビデオ ウィンドウが小さい場合に、DirectShow がビデオ イメージを拡大縮小する方法を制御する。
IBasicVideo2 | ビデオのプロパティを設定する。
IDDrawExclModeVideo | Microsoft® DirectDraw® の排他的な全画面モードでビデオをレンダリングする。
IDDrawExclModeVideoCallback | オーバーレイの位置、サイズ、および表示/非表示の変更に関する通知を受け取るコールバック インターフェイス。
IDirectDrawVideo | 指定された DirectDraw 能力を無効にする。
IDirectDrawMediaSample | オーバーレイ ミキサー フィルタが割り当てた DirectDraw サーフェスにアクセスする。
IFullScreenVideo | フルスクリーン レンダリング フィルタを制御する。
IMixerPinConfig2 | 複数のビデオ ストリームをミキシングするときに、オーバーレイ ミキサー上にビデオのカラー コントロールを設定する。
IQualProp | ビデオ レンダラにパフォーマンス情報を照会する。
IVideoWindow | ビデオ ウィンドウのプロパティを設定する。

TV の調整

インターフェイス | 目的
IAMTunerNotification | TV チューナー フィルタからのイベント通知を受け取るコールバック インターフェイス。
IAMTVTuner | TV チューナー デバイスを制御する。
IAMTVAudio | TV チューナーからのオーディオを制御する。
IAMTVAudioNotification | TV チューナー カードからのイベント通知を受け取るコールバック インターフェイス。
IAMAnalogVideoDecoder | 水平ロックの表示を含むデジタル化フォーマットの選択と、デジタイザの位相同期の時間定数を制御するメソッドが入る。

外部デバイスの制御

インターフェイス | 目的
IAMCameraControl | カメラを制御する。
IAMExtDevice | VCR やカムコーダーなどの外部デバイスを制御する。
IAMExtTransport | VCR の転送機能 (再生、ポーズ、録画、早送り、巻き戻しなど) を制御する。
IAMTimecodeDisplay | SMPTE タイムコードを表示するデバイスにプロパティを設定する。
IAMTimecodeGenerator | SMPTE タイムコードを生成するデバイスにプロパティを設定する。
IAMTimecodeReader | 外部デバイスから SMPTE タイムコードを読み取る。


DirectShow COM インターフェイスの一覧 (アルファベット順)

以下は DirectShow COM インターフェイスのアルファベット順の一覧である。

  • IAMAnalogVideoDecoder
  • IAMAnalogVideoEncoder
  • IAMAudioInputMixer
  • IAMBufferNegotiation
  • IAMCameraControl
  • IAMClockAdjust
  • IAMCollection
  • IAMCopyCaptureFileProgress
  • IAMCrossbar
  • IAMDirectSound
  • IAMDroppedFrames
  • IAMErrorLog
  • IAMExtDevice
  • IAMExtTransport
  • IAMFilterMiscFlags
  • IAMGraphStreams
  • IAMLatency
  • IAMLine21Decoder
  • IAMMediaContent
  • IAMOpenProgress
  • IAMOverlayFX
  • IAMParse
  • IAMPushSource
  • IAMResourceControl
  • IAMSetErrorLog
  • IAMStreamConfig
  • IAMStreamControl
  • IAMStreamSelect
  • IAMTimecodeDisplay
  • IAMTimecodeGenerator
  • IAMTimecodeReader
  • IAMTimeline
  • IAMTimelineComp
  • IAMTimelineEffect
  • IAMTimelineEffectable
  • IAMTimelineGroup
  • IAMTimelineObj
  • IAMTimelineSplittable
  • IAMTimelineSrc
  • IAMTimelineTrack
  • IAMTimelineTrans
  • IAMTimelineTransable
  • IAMTimelineVirtualTrack
  • IAMTuner
  • IAMTunerNotification
  • IAMTVAudio
  • IAMTVAudioNotification
  • IAMTVTuner
  • IAMVfwCaptureDialogs
  • IAMVfwCompressDialogs
  • IAMVideoAccelerator
  • IAMVideoAcceleratorNotify
  • IAMVideoCompression
  • IAMVideoControl
  • IAMVideoDecimationProperties
  • IAMVideoProcAmp
  • IAsyncReader
  • IBaseFilter
  • IBasicAudio
  • IBasicVideo
  • IBasicVideo2
  • ICaptureGraphBuilder2
  • IConfigAviMux
  • IConfigInterleaving
  • ICreateDevEnum
  • IDDrawExclModeVideo
  • IDDrawExclModeVideoCallback
  • IDecimateVideoImage
  • IDeferredCommand
  • IDirectDrawVideo
  • IDirectDrawMediaSample
  • IDirectDrawMediaSampleAllocator
  • IDistributorNotify
  • IDMOWrapperFilter
  • IDvdCmd
  • IDvdControl2
  • IDvdGraphBuilder
  • IDvdInfo2
  • IDvdState
  • IDVEnc
  • IDVSplitter
  • IEnumFilters
  • IEnumMediaTypes
  • IEnumPIDMap
  • IEnumPins
  • IEnumStreamIdMap
  • IFileSinkFilter
  • IFileSinkFilter2
  • IFileSourceFilter
  • IFilterChain
  • IFilterGraph
  • IFilterGraph2
  • IFilterInfo
  • IFilterMapper2
  • IFindCompressorCB
  • IFullScreenVideo
  • IGraphBuilder
  • IGraphConfig
  • IGraphConfigCallback
  • IGraphVersion
  • IIPDVDec
  • IKsPropertySet
  • IMediaControl
  • IMediaDet
  • IMediaEvent
  • IMediaEventEx
  • IMediaEventSink
  • IMediaFilter
  • IMediaLocator
  • IMediaPosition
  • IMediaPropertyBag
  • IMediaSample
  • IMediaSample2
  • IMediaSeeking
  • IMediaTypeInfo
  • IMemAllocator
  • IMemInputPin
  • IMixerPinConfig
  • IMixerPinConfig2
  • IMPEG2Demultiplexer
  • IMPEG2PIDMap
  • IMPEG2StreamIdMap
  • IOverlay
  • IOverlayNotify
  • IOverlayNotify2
  • IPersistMediaPropertyBag
  • IPin
  • IPinConnection
  • IPinFlowControl
  • IPinInfo
  • IPropertySetter
  • IQualityControl
  • IQualProp
  • IQueueCommand
  • IReferenceClock
  • IRegFilterInfo
  • IRenderEngine
  • IResourceConsumer
  • IResourceManager
  • ISampleGrabber
  • ISampleGrabberCB
  • ISeekingPassThru
  • ISmartRenderEngine
  • IStreamBuilder
  • IUnknown
  • IVideoFrameStep
  • IVideoWindow
  • IVPBaseConfig
  • IVPBaseNotify
  • IVPConfig
  • IVPNotify
  • IVPNotify2
  • IXml2Dex


IAMAnalogVideoDecoder インターフェイス

IAMAnalogVideoDecoder インターフェイスは、WDM ビデオ キャプチャ フィルタで実装される。このインターフェイスは、WDM 準拠のビデオ キャプチャ カードで処理されるビデオのデジタル化に関する情報を指定および取得するものである。このインターフェイスは、デジタル化方式を選択するメソッド、水平ロックの状態を示すメソッド、およびデジタイザの位相同期ループ (PLL) における時間定数を制御するメソッドを備えている。

アプリケーションはこのインターフェイスを使用して、サポートされているビデオ方式の取得と設定、水平同期がロックされているかどうかの判別、デジタル化方式に関するその他の各種情報の取得など、さまざまなビデオ デジタル化情報を選択および制御する。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMAnalogVideoDecoder メソッド | 説明
get_AvailableTVFormats | 現在利用できるアナログ ビデオ方式を取得する。
put_TVFormat | 現在のアナログ ビデオ方式を設定する。
get_TVFormat | 現在のアナログ ビデオ方式を取得する。
get_HorizontalLocked | 水平同期がロックされているかどうかを判別する。
put_VCRHorizontalLocking | VCR への接続状態を設定する (PLL タイミングを変更する)。
get_VCRHorizontalLocking | 水平ロックが設定されているかどうかを判別する。
get_NumberOfLines | 現在のビデオ信号内の走査線の数を取得する。
put_OutputEnable | 出力バスを有効または無効にする。
get_OutputEnable | 出力バスが有効かどうかを判別する。

IAMAnalogVideoDecoder::get_AvailableTVFormats

IAMAnalogVideoDecoder インターフェイス

現在利用できるアナログ ビデオ方式を取得する。

構文

HRESULT get_AvailableTVFormats(
    long *lAnalogVideoStandard
    );

パラメータ

lAnalogVideoStandard
[out] 利用できるアナログ ビデオ方式を表す整数へのポインタ。AnalogVideoStandard 列挙型で定義される各種の値を、ビット OR で結んだ論理和となる。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。

E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_POINTER | Null ポインタ引数。
S_OK | 成功。

IAMAnalogVideoDecoder::get_HorizontalLocked

IAMAnalogVideoDecoder インターフェイス

水平同期がロックされているかどうかを判別する。

構文

HRESULT get_HorizontalLocked(
    long *plLocked
    );

パラメータ

plLocked
[out] 水平同期がロックされているかどうかを示す値へのポインタ。TRUE は水平同期がロックされていることを表し、FALSE はロックされていないことを表す。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。

E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_POINTER | Null ポインタ引数。
S_OK | 成功。

IAMAnalogVideoDecoder::get_NumberOfLines

IAMAnalogVideoDecoder インターフェイス

ビデオ信号内の走査線の数を取得する。

構文

HRESULT get_NumberOfLines(
    long *plNumberOfLines
    );

パラメータ

plNumberOfLines
[out] ビデオ信号内の走査線の数へのポインタ。NTSC の場合、この値は一般に 525 であり、PAL/SECAM の場合は通常 625 である。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。

E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_POINTER | Null ポインタ引数。
S_OK | 成功。

IAMAnalogVideoDecoder::get_OutputEnable

IAMAnalogVideoDecoder インターフェイス

出力バスが有効または無効であることを判別する。

構文

HRESULT get_OutputEnable(
    long *plOutputEnable
    );

パラメータ

plOutputEnable
[out] 出力バスが有効かどうかを示す値へのポインタ。TRUE は有効であることを表し、FALSE は無効であることを表す。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。

E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_POINTER | Null ポインタ引数。
S_OK | 成功。

IAMAnalogVideoDecoder::get_TVFormat

IAMAnalogVideoDecoder インターフェイス

現在のアナログ ビデオ方式を取得する。

構文

HRESULT get_TVFormat(
    long *plAnalogVideoStandard
    );

パラメータ

plAnalogVideoStandard
[out] サポートされるアナログ ビデオ方式を定義している AnalogVideoStandard 列挙型へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。

E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_POINTER | Null ポインタ引数。
S_OK | 成功。

IAMAnalogVideoDecoder::get_VCRHorizontalLocking

IAMAnalogVideoDecoder インターフェイス

水平ロックが設定されているかどうかを判別する。

構文

HRESULT get_VCRHorizontalLocking(
    long *plVCRHorizontalLocking
    );

パラメータ

plVCRHorizontalLocking
[out] 水平ロックが設定されているかどうかを示す値へのポインタ。TRUE は水平ロックが設定されていることを表す。それ以外の場合は FALSE となる。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。

E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_POINTER | Null ポインタ引数。
S_OK | 成功。

注意

テープのずれ、ノイズ、またはデータドロップアウト、および記録メカニズムの機械的な特性が原因で、VCR の同期タイミングが合わないことがある。水平ロックを設定するとデコーダの基準が緩和され、その結果、同期がとりやすくなる。

IAMAnalogVideoDecoder::put_OutputEnable

IAMAnalogVideoDecoder インターフェイス

出力バスを有効または無効にする。

構文

HRESULT put_OutputEnable(
    long lOutputEnable
    );

パラメータ

lOutputEnable
[in] 出力バスが有効かどうかを示す値。TRUE は有効を指定し、FALSE は無効を指定する。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。

E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_POINTER | Null ポインタ引数。
S_OK | 成功。

IAMAnalogVideoDecoder::put_TVFormat

IAMAnalogVideoDecoder インターフェイス

サポートされているアナログ ビデオ方式の 1 つを現在の方式に設定する。

構文

HRESULT put_TVFormat(
    long lAnalogVideoStandard
    );

パラメータ

lAnalogVideoStandard
[in] サポートされるアナログ ビデオ方式を定義している AnalogVideoStandard 列挙型の値。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。

E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_POINTER | Null ポインタ引数。
S_OK | 成功。

IAMAnalogVideoDecoder::put_VCRHorizontalLocking

IAMAnalogVideoDecoder インターフェイス

水平ロックを設定するかどうかを指定する。

構文

HRESULT put_VCRHorizontalLocking(
    long lVCRHorizontalLocking
    );

パラメータ

lVCRHorizontalLocking
[in] 水平ロックを設定するかどうかを示す値。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。

E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_POINTER | Null ポインタ引数。
S_OK | 成功。

注意

テープのずれ、ノイズ、またはデータ ドロップアウト、および記録メカニズムの機械的な特性が原因で、VCR の同期タイミングが合わないことがある。このメソッドによってデコーダの基準が緩和され、その結果、同期がとりやすくなる。


IAMAnalogVideoEncoder インターフェイス

IAMAnalogVideoEncoder インターフェイスは、アプリケーションがデータをディスクにストリームし、これをビデオテープに送り返す場合に、ビデオ キャプチャ処理におけるハードウェア ビデオ エンコーダ によって実装される。このインターフェイスは、ビデオ方式を設定するメソッドと、クローズド キャプションおよびコピー保護を有効または無効にするメソッドを備えている。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMAnalogVideoEncoder メソッド | 説明
get_AvailableTVFormats | エンコーダがサポートするアナログ ビデオ方式 (NTSC/M、PAL/B、SECAM/K1 など) を取得する。
put_TVFormat | エンコーダを特定のアナログ ビデオ方式に設定する。
get_TVFormat | エンコーダに現在設定されているアナログ ビデオ方式を取得する。
put_CopyProtection | エンコーダのコピー保護のレベルを設定する。
get_CopyProtection | コピー保護が現在有効かどうかを判別する。
put_CCEnable | クローズド キャプションを有効または無効にする。
get_CCEnable | クローズド キャプションが現在有効かどうかを判別する。

IAMAnalogVideoEncoder::get_AvailableTVFormats

IAMAnalogVideoEncoder インターフェイス

エンコーダがサポートするアナログ ビデオ方式 (NTSC/M、PAL/B、SECAM/K1 など) を取得する。

構文

HRESULT get_AvailableTVFormats(
    long *lAnalogVideoStandard
);

パラメータ

lAnalogVideoStandard
[out] AnalogVideoStandard 列挙型で定義される値の任意の組み合わせを受け取る変数へのポインタ。

戻り値

HRESULT 値を返す。

IAMAnalogVideoEncoder::get_CCEnable

IAMAnalogVideoEncoder インターフェイス

クローズド キャプションが現在有効かどうかを判別する。

構文

HRESULT get_CCEnable(
    long *lCCEnable
);

パラメータ

lCCEnable
[out] エンコーダのクローズド キャプションの現在の状態を受け取る変数へのポインタ。1 はクローズド キャプションが有効であることを表し、0 はクローズド キャプションが無効であることを表す。

戻り値

HRESULT 値を返す。

IAMAnalogVideoEncoder::get_CopyProtection

IAMAnalogVideoEncoder インターフェイス

エンコーダのコピー保護が現在有効かどうかを判別する。

構文

HRESULT get_CopyProtection(
    long *lVideoCopyProtection
);

パラメータ

lVideoCopyProtection
[out] 現在のコピー保護レベルを受け取る変数へのポインタ。コピー保護レベルは、AM_COPY_MACROVISION_LEVEL 列挙型で定義される。

戻り値

HRESULT 値を返す。

IAMAnalogVideoEncoder::get_TVFormat

IAMAnalogVideoEncoder インターフェイス

エンコーダに現在設定されているアナログ ビデオ方式 (NTSC/M、PAL/B、SECAM/K1 など) を取得する。

構文

HRESULT get_TVFormat(
    long *plAnalogVideoStandard
);

パラメータ

plAnalogVideoStandard
[out] エンコーダの現在のビデオ方式を受け取る変数へのポインタ。

戻り値

HRESULT 値を返す。

注意

有効値とその意味は、AnalogVideoStandard 列挙型で定義される。

IAMAnalogVideoEncoder::put_CCEnable

IAMAnalogVideoEncoder インターフェイス

クローズド キャプションを有効または無効にする。

構文

HRESULT put_CCEnable(
    long lCCEnable
);

パラメータ

lCCEnable
[in] クローズド キャプションをオンまたはオフに切り替える値。1 は "オン" を表し、0 は "オフ" を表す。

戻り値

HRESULT 値を返す。

IAMAnalogVideoEncoder::put_CopyProtection

IAMAnalogVideoEncoder インターフェイス

エンコーダのコピー保護レベルを設定する。

構文

HRESULT put_CopyProtection(
    long lVideoCopyProtection
);

パラメータ

lVideoCopyProtection
[in] 設定するコピー保護レベルを示す値。コピー保護レベルは、AM_COPY_MACROVISION_LEVEL 列挙型で定義される。

戻り値

HRESULT 値を返す。

IAMAnalogVideoEncoder::put_TVFormat

IAMAnalogVideoEncoder インターフェイス

エンコーダを特定のアナログ ビデオ方式 (NTSC/M、PAL/B、SECAM/K1 など) に設定する。

構文

HRESULT put_TVFormat(
    long lAnalogVideoStandard
);

パラメータ

lAnalogVideoStandard
[in] エンコーダが設定されるビデオ方式。指定できる値は AnalogVideoStandard 列挙型で定義される。

戻り値

HRESULT 値を返す。


IAMAudioInputMixer インターフェイス

IAMAudioInputMixer インターフェイスは Audio Capture Filter の各入力ピンで実装され、フィルタにレベル、パン、およびイコライザを指定する。"Line in" や "Microphone" のような各ピンの名前は入力の種類を表す。

オーディオ キャプチャ フィルタの機能は、関連付けられている特定のハードウェア デバイスに対応するので、デバイスがサポートしないインターフェイス メソッドを、フィルタがサポートすることはできない。

アプリケーション開発者 : このインターフェイスを使用してサウンドカードのアナログ入力にアクセスし、特定の入力のミキシング、モノラルまたはステレオの使用、ミキシング レベル、パン レベル、ラウドネス、高音域、低音域の各種設定など、オーディオ キャプチャ フィルタにおけるオーディオ入力特性を調整できる。

フィルタ開発者 : オーディオ キャプチャ フィルタの各入力ピンでこのインターフェイスを実装する。オーディオ キャプチャ フィルタ自体にこのインターフェイスを実装し、オーディオ ミキシング後の全体の録音レベルとパンを制御することもできる。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMAudioInputMixer メソッド | 説明
put_Enable | ミキシングにおける入力を有効または無効にする
get_Enable | 入力が有効かどうかを取得する。
put_Mono | 入力のすべてのチャンネルを 1 つのモノラル信号にまとめる。
get_Mono | 入力のすべてのチャンネルが 1 つのモノラル信号にまとめられているかどうかを取得する。
put_MixLevel | 入力の録音レベルを設定する。
get_MixLevel | 入力の録音レベルを取得する。
put_Pan | 入力のパンを設定する。
get_Pan | 入力のパンを取得する。
put_Loudness | 入力のラウドネス コントロールをオンまたはオフにする。
get_Loudness | 入力のラウドネス コントロールの設定を取得する。
put_Treble | 入力の高音域のイコライジングを設定する。
get_Treble | 入力の高音域のイコライジングを取得する。
get_TrebleRange | 入力の高音域の範囲を取得する。
put_Bass | 入力の低音域のイコライジングを設定する。
get_Bass | 入力の低音域のイコライジングを取得する。
get_BassRange | 入力の低音域の範囲を取得する。

IAMAudioInputMixer::get_Bass

IAMAudioInputMixer インターフェイス

この入力の低音域のイコライジングを取得する。

構文

HRESULT get_Bass(
  double *pBass
  );

パラメータ

pBass
[in] デシベル単位の低音域ゲイン (負の値は減衰を表す) を示す double タイプの変数へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
NOERROR | 成功。

IAMAudioInputMixer::get_BassRange

IAMAudioInputMixer インターフェイス

この入力の低音域の範囲を取得する。

構文

HRESULT get_BassRange(
  double *pRange
  );

パラメータ

pRange
[out, retval] put_Bass で指定される低音域の範囲内の最大値を示す double タイプの変数へのポインタ。たとえば、6.0 は –6.0 から 6.0 の範囲の値が有効であることを表す。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
NOERROR | 成功。

IAMAudioInputMixer::get_Enable

IAMAudioInputMixer インターフェイス

入力が有効かどうかを取得する。

構文

HRESULT get_Enable(
  BOOL *pfEnable
  );

パラメータ

pfEnable
[in] 入力のミキシングが有効かどうかを示す BOOL タイプの変数へのポインタ。TRUE は入力が有効であることを表し、FALSE は入力が無効であることを表す。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 情報を取得できない。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
NOERROR | 成功。

IAMAudioInputMixer::get_Loudness

IAMAudioInputMixer インターフェイス

入力のラウドネス コントロールの設定を取得する。

構文

HRESULT get_Loudness(
  int *pfLoudness
  );

パラメータ

pfLoudness
[in] ラウドネス コントロールがオンまたはオフであることを示す int タイプの変数へのポインタ。TRUE はオンを表し、FALSE はオフを表す。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | エラー。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
E_OUTOFMEMORY | メモリ不足。
NOERROR | 成功。

IAMAudioInputMixer::get_MixLevel

IAMAudioInputMixer インターフェイス

この入力の録音レベルを取得する。

構文

HRESULT get_MixLevel(
  double *pLevel
  );

パラメータ

[out] pLevel
録音レベルを示す変数へのポインタ。値は 0 (オフ) から 1 (最大ボリューム) の範囲である。AMF_AUTOMATICGAIN (-0x0001) は、これがサポートされている場合、レベルの自動調整を表す。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 録音レベルの取得エラー。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
NOERROR | 成功。

IAMAudioInputMixer::get_Mono

IAMAudioInputMixer インターフェイス

入力のすべてのチャンネルが 1 つのモノラル信号にまとめられているかどうかを取得する。

構文

HRESULT get_Mono(
  BOOL *pfMono
  );

パラメータ

pfMono
[in] モノラルが有効かどうかを示す BOOL タイプの変数へのポインタ。TRUE はモノラルが有効であることを表し、FALSE はモノラルが無効であることを表す。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | モノラル コントロールの取得エラー。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
NOERROR | 成功。

IAMAudioInputMixer::get_Pan

IAMAudioInputMixer インターフェイス

この入力のパン レベルを取得する。

構文

HRESULT get_Pan(
  double *pPan
  );

パラメータ

pPan
[in] パン レベルを示す double タイプの変数へのポインタ。有効なレベルは –1 から 1 の範囲である。値の意味は次のとおりである。
–1 | 左端
0 | 中央
1 | 右端

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | パン レベルの取得エラー。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | パンできない: ステレオでない。
NOERROR | 成功。

IAMAudioInputMixer::get_Treble

IAMAudioInputMixer インターフェイス

この入力の高音域のイコライジングを取得する。

構文

HRESULT get_Treble(
  double *pTreble
  );

パラメータ

pTreble
[in] デシベル単位の高音域ゲイン (負の値は減衰を表す) を示す double タイプの変数へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
NOERROR | 成功。

IAMAudioInputMixer::get_TrebleRange

IAMAudioInputMixer インターフェイス

この入力の高音域の範囲を取得する。

構文

HRESULT get_TrebleRange(
  double *pRange
  );

パラメータ

pRange
[out, retval] put_Treble で指定される高音域の範囲内の最大値を示す double タイプの変数へのポインタ。たとえば、6.0 は –6.0 から 6.0 の範囲の値が有効であることを表す。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
NOERROR | 成功。

IAMAudioInputMixer::put_Bass

IAMAudioInputMixer インターフェイス

この入力の低音域のイコライジングを設定する。

構文

HRESULT put_Bass(
  double Bass
  );

パラメータ

Bass
[in] デシベル単位のゲイン (負の値は減衰を表す) を示す double タイプの変数。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 引数が無効。 get_BassRange で指定される範囲になければならない。
E_NOTIMPL | メソッドがサポートされていない。
NOERROR | 成功。

注意

録音前に Bass で指定されるデシベル数だけ信号の低音域の増幅または減衰が行われる。

IAMAudioInputMixer::put_Enable

IAMAudioInputMixer インターフェイス

ミキシングにおける入力を有効または無効にする。

構文

HRESULT put_Enable(
  BOOL fEnable
  );

パラメータ

fEnable
[in] 入力を有効または無効にするかを示す BOOL タイプの変数。TRUE は入力を有効にし、FALSE は入力を無効にする。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 入力の有効化または無効化が失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
NOERROR | 入力の有効化または無効化が成功。

注意

無効の場合、この入力が録音信号の一部としてミキシングされることはない。

IAMAudioInputMixer::put_Loudness

IAMAudioInputMixer インターフェイス

この入力のラウンドネス コントロールをオンまたはオフにする。

構文

HRESULT put_Loudness(
  BOOL fLoudness
  );

パラメータ

fLoudness
[in] ラウドネス コントロールがオンかどうかを示す BOOL タイプの変数。TRUE はラウドネス コントロールをオンに設定し、FALSE はラウドネス コントロールをオフに設定する。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | ラウドネス コントロールの設定が失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
NOERROR | 成功。

注意

IAMAudioInputMixer::put_Loudness によって、録音前に低音域量信号の低音域が増幅され、小さな音の低音域サウンドやその他のサウンドが聞こえないという状態が補正される。

IAMAudioInputMixer::put_MixLevel

IAMAudioInputMixer インターフェイス

この入力の録音レベルを設定する。

構文

HRESULT put_MixLevel(
  double Level
  );

パラメータ

Level
録音レベルを示す double タイプの変数。値は 0 (オフ) から 1 (最大ボリューム) の範囲である。AMF_AUTOMATICGAIN (-0x0001) は、これがサポートされている場合、レベルの自動調整を表す。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | ボリュームの設定エラー。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 録音レベルは 0 から 1 の範囲でなければならない。
E_NOTIMPL | 自動ゲインは現在実装されていない。
NOERROR | 成功。

IAMAudioInputMixer::put_Mono

IAMAudioInputMixer インターフェイス

入力のすべてのチャンネルを 1 つのモノラル信号にまとめる。

構文

HRESULT put_Mono(
  BOOL fMono
  );

パラメータ

fMono
[in] モノラル信号またはマルチチャンネル信号を示す BOOL タイプの変数。TRUE はモノラルを表し、FALSE はマルチチャンネルを表す。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | モノラル コントロールの設定エラー。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
NOERROR | 成功。

注意

モノラル モードに設定されている場合、この入力をステレオ録音すると、両方のチャンネルに同じデータが格納される。左信号と右信号を合わせたものが得られる。

IAMAudioInputMixer::put_Pan

IAMAudioInputMixer インターフェイス

この入力のパンを設定する。

構文

HRESULT put_Pan(
  double Pan
  );

パラメータ

Pan
[in] パン レベルを示す double タイプの変数。Pan の有効値は、-1 から 1 の範囲である。値の意味は次のとおりである。
-1 | 左端
0 | 中央
1 | 右端

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | ボリュームの設定エラー。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | パン レベルは -1 から 1 の範囲でなければならない。
E_NOTIMPL | パンできない: ステレオでない。
NOERROR | 成功。

注意

入力のパンを左端に設定すると、入力の信号がステレオ録音の左チャンネルにのみ設定される。モノラル録音ではパンの効果はない。

IAMAudioInputMixer::put_Treble

IAMAudioInputMixer インターフェイス

この入力の高音域のイコライジングを設定する。

構文

HRESULT put_Treble(
  [in] double Treble
  );

パラメータ

Treble
[in] デシベル単位のゲイン (負の値は減衰を表す) を示す double タイプの変数。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 引数が無効。 get_TrebleRange で指定される範囲になければならない。
E_NOTIMPL | メソッドがサポートされていない。
NOERROR | 成功。

注意

このメソッドによって、録音前に指定のデシベル数だけ信号の高音域の増幅または減衰が行われる。


IAMBufferNegotiation インターフェイス

IAMBufferNegotiation インターフェイスは、ピンの中でも特にキャプチャ フィルタ内のピンにおいて実装される。これによってアプリケーションは、ピンにおけるバッファの割り当て処理を制御できる。

電子会議アプリケーションでは、このインターフェイスを使用して最小のバッファ数を指定する。これによって、低速なキャプチャ環境やディスクへの書き込みが行われる環境での、情報のバッファリングによるリソースの無駄を防ぐことができる。

アプリケーションが、キャプチャしたオーディオを出力デバイスに送信することによってオーディオ プレビューを実行していて、遅延時間が大きすぎると思われる場合は、バッファ数を少なくしてみる。

IAMBufferNegotiation::SuggestAllocatorProperties メソッドは、使用するアロケータのカウント、サイズ、アラインメント、およびプレフィックスのプロパティで構成される ALLOCATOR_PROPERTIES 構造体をサポートする。通常は、ALLOCATOR_PROPERTIES 構造体の cBuffers メンバだけを設定する。これは、指定のアロケータのバッファ数に相当する。その他のすべてのプロパティについては、負の値を指定することで、キャプチャ ハードウェア自体のデフォルト値が使用される。

cBuffers に対して負の値を指定すると、アロケータが必要とするだけのバッファ数の割り当てが試みられる。その個数は、利用可能なリソースとキャプチャ フレーム レートによって異なる。大きな値を指定すると、システムで利用可能なメモリを最高に、より多くのバッファの割り当てがアロケータによって試みられる。バッファ数の割り当てが少ないと、場合によってはドロップ フレームが発生する。電子会議アプリケーションでは、多くの場合、この値を小さな値に設定することが望ましい。たとえば、ネットワークが、指定のビデオ方式と解像度では 2 フレーム/秒 (fps) の転送速度だけをサポートする場合は、2 という値が適切な設定である。

アプリケーションでは、IAMBufferNegotiation::GetAllocatorProperties メソッドを呼び出して、使用しているアロケータのプロパティを取得できる。

フィルタ開発者: IMemInputPin インターフェイスを使用してピンを別のピンに接続し、フィルタ間でメディア サンプルをトランスポートするときに使用するバッファ設定をアプリケーションが割り当てる場合は、このインターフェイスを実装する。アプリケーションが正確なバッファ設定を指定できるようにするためには、すべてのキャプチャ フィルタがこのインターフェイスをサポートする必要がある。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMBufferNegotiation メソッド | 説明
SuggestAllocatorProperties | ALLOCATOR_PROPERTIES 構造体に設定されているアロケータのバッファ プロパティを使用することを、ピンに対して指定する。
GetAllocatorProperties | ピンが使用する、アロケータのプロパティを取得する。

IAMBufferNegotiation::GetAllocatorProperties

IAMBufferNegotiation インターフェイス

ピンが使用している、アロケータのプロパティを取得する。

構文

HRESULT GetAllocatorProperties(
  ALLOCATOR_PROPERTIES *pprop
  );

パラメータ

pprop
[out] ALLOCATOR_PROPERTIES 構造体へのポインタ。

戻り値

成功した場合は S_OK を返す。それ以外の場合は、失敗の原因を示す HRESULT 値を返す。有効なエラー コードは、次のとおりである。

E_FAIL | 失敗。
E_POINTER | NULL ポインタ。
VFW_E_NOT_CONNECTED | ピンが接続されていない。

注意

このメソッドを呼び出すのは、ピンが接続した後に限られる。

参照

SuggestAllocatorProperties

IAMBufferNegotiation::SuggestAllocatorProperties

IAMBufferNegotiation インターフェイス

ALLOCATOR_PROPERTIES 構造体に設定されているアロケータのバッファ プロパティを使用することを、ピンに対して指定する。

構文

HRESULT SuggestAllocatorProperties(
  const ALLOCATOR_PROPERTIES *pprop
  );

パラメータ

pprop
[in] ALLOCATOR_PROPERTIES 構造体へのポインタ。

戻り値

成功した場合は S_OK を返す。それ以外の場合は、失敗の原因を示す HRESULT 値を返す。有効なエラー コードは、次のとおりである。

E_FAIL | 失敗。 (指定のプロパティを使用できなかった。)
E_POINTER | NULL ポインタ。
E_UNEXPECTED | 予期せぬ失敗。
VFW_E_ALREADY_CONNECTED | ピンは接続済みである。

注意

アプリケーションでは、2 つのピンを接続する前にこの関数を呼び出す必要がある。このメソッドを呼び出す前にピンが接続されている場合、フィルタ グラフはバッファを既に決定しており、アプリケーションがこれを事前に割り当てることはもやはできない。

アプリケーションでは、接続する両方のピンについてこのメソッドを呼び出し、ほかのピンがアプリケーションの要求を書き換えることがないようにしなければならない。ただし、一方のピンがこのインターフェイスをサポートしていない場合は、1 回の呼び出しで十分である。

ALLOCATOR_PROPERTIES 構造体内の任意の要素に対して負の値を使用すると、プロパティはデフォルト値に設定される。

参照

IAMBufferNegotiation::GetAllocatorProperties


IAMCameraControl インターフェイス

IAMCameraControl インターフェイスは、カメラに対するローカル制御またはリモート制御を提供する。

このインターフェイスは、ズーム、パン、絞り、またはシャッター スピードなどのデバイス制御を備えている、カメラ デバイスを制御するフィルタを対象に、Microsoft® DirectShow® の中で実装される。WDM キャプチャ ドライバは、関連するカーネル ストリーミング プロパティ セットをサポートしている場合、KsProxy.ax におけるこのインターフェイスを自動的に使用するので注意すること。

アプリケーションは、このインターフェイスを使用して、ズーム、パン、絞り、またはシャッター スピードなどのデバイス設定を制御する。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMCameraControl メソッド | 説明
GetRange | 指定のカメラ プロパティの範囲に関連付けられている値を取得する。
Set | カメラ プロパティを設定する。
Get | 特定のカメラ制御プロパティの値を取得する。

IAMCameraControl::Get

IAMCameraControl インターフェイス

特定のカメラ制御プロパティの値を取得する。

構文

HRESULT Get (
     long Property,
     long *lValue,
     long *Flags
    );

パラメータ

Property
[in] 照会する CameraControlProperty 列挙型のプロパティを指定する値。
lValue
[out] 指定のプロパティの取得値へのポインタ。有効な範囲と値については、「注意」を参照すること。
Flags
[out] カメラ プロパティが自動または手動であることを示す、CameraControlFlags 列挙型の値へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。

E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_POINTER | Null ポインタ引数。
S_OK | 成功。

注意

CameraControlProperty 列挙型で表される各プロパティは、自動または手動の設定を持つことができる。Flags パラメータに CameraControlFlags 列挙型の CameraControl_Flags_Auto が設定されている場合、lValue パラメータは無視される。lValue の範囲と意味は、照会するプロパティによってそれぞれ異なる。次の表は、有効な値を示している。

プロパティ | lValue の範囲と意味
Pan | パンの設定を指定する値 (度単位)。値は –180 から +180 の範囲で、デフォルト値は 0 である。正の値は原点から右回り (上から見た場合、カメラが右回りに回転する) を表し、負の値は原点から左回りを表す。特定のデバイスでは、この範囲のサブセットのみが実装される場合があるので注意すること。
Tilt | チルトの設定を指定する値 (度単位)。値は –180 から +180 の範囲で、デフォルト値は 0 である。正の値はイメージの面を上方向に向けることを表し、負の値はイメージの面を下方向に向けることを表す。特定のデバイスでは、この範囲のサブセットのみが実装される場合があるので注意すること。
Roll | ロールの設定を指定する値 (度単位)。値は –180 から +180 の範囲で、デフォルト値は 0 である。正の値はイメージ表示軸に沿ってカメラを右回りに回転することを表し、負の値はカメラの左回りの回転を表す。特定のデバイスでは、この範囲のサブセットのみが実装される場合があるので注意すること。
Zoom | ズームの設定を指定する値 (mm 単位)。値は 10 から 600 の範囲で、デフォルト値はデバイスによってそれぞれ異なる。
Exposure 次の式を元に、露出の設定を指定する値 (秒単位)。0 未満の値の場合、露出時間は 1/2n 秒である。正の値と 0 の場合、露出時間は 2n 秒である。特定のデバイスでは、この範囲のサブセットのみが実装される場合があるので注意すること。たとえば、デバイスの範囲が –7 から 1 で、ステップが 1 とする。対応する露出時間は、次のとおりである。
値 | -7 | -6 | -5 | -4 | -3 | -2 | -1 | 0 | 1
秒 | 1/128 | 1/64 | 1/32 | 1/16 | 1/8 | 1/4 | 1/2 | 1 | 2
Iris | fstop * 10 で表される絞りの設定を指定する値。
Focus | 焦点の設定を、対象に対する最適な焦点距離として指定する値 (mm 単位)。範囲とデフォルト値は、デバイスによってそれぞれ異なる。特定のデバイスでは、この範囲のサブセットのみが実装される場合があるので注意すること。

IAMCameraControl::GetRange

IAMCameraControl インターフェイス

指定のカメラ プロパティの範囲に関連付けられている値を取得する。

構文

HRESULT GetRange (
     long property,
     long *pMin,
     long *pMax,
     long *pSteppingDelta,
     long *pDefault,
     long *pCapsFlags
    );

パラメータ

property
[in] 照会する CameraControlProperty 列挙型のプロパティを指定する値。
pMin
[out] 指定のプロパティの最小範囲へのポインタ。
pMax
[out] 指定のプロパティの最大範囲へのポインタ。
pSteppingDelta
[out] 指定のプロパティのステップ サイズへのポインタ。ステップ サイズはプロパティの変化の単位で、基になるハードウェアによってそれぞれ異なる。たとえば、デジタル カメラの場合は、5°ずつ変更できる。
pDefault
[out] 指定のプロパティのデフォルト値へのポインタ。
pCapsFlags
[out] カメラ プロパティが自動または手動であることを指定する CameraControlFlags 列挙型の値へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。

E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_POINTER | Null ポインタ引数。
S_OK | 成功。

IAMCameraControl::Set

IAMCameraControl インターフェイス

特定のカメラ制御プロパティの値を設定する。

構文

HRESULT Set (
     long Property,
     long lValue,
     long Flags
    );

パラメータ

Property
[in] 変更する CameraControlProperty 列挙型のプロパティを指定する値。
lValue
[in] 指定のプロパティの新しい値。
Flags
[in] カメラ プロパティが自動または手動であることを指定する CameraControlFlags 列挙型の値。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。

E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_POINTER | Null ポインタ引数。
S_OK | 成功。

注意

CameraControlProperty 列挙型で表される各プロパティは、自動または手動の設定を持つことができる。Flags パラメータに CameraControlFlags 列挙型の CameraControl_Flags_Auto が設定されている場合、lValue パラメータは無視される。lValue の範囲と意味は、照会するプロパティによってそれぞれ異なる。次の表は、有効な値を示している。

プロパティ | lValue の範囲と意味
Pan | パンの設定を指定する値 (度単位)。値は –180 から +180 の範囲で、デフォルト値は 0 である。正の値は原点から右回り (上から見た場合、カメラが右回りに回転する) を表し、負の値は原点から左回りを表す。特定のデバイスでは、この範囲のサブセットのみが実装される場合があるので注意すること。
Tilt | チルトの設定を指定する値 (度単位)。値は –180 から +180 の範囲で、デフォルト値は 0 である。正の値はイメージの面を上方向に向けることを表し、負の値はイメージの面を下方向に向けることを表す。特定のデバイスでは、この範囲のサブセットのみが実装される場合があるので注意すること。
Roll | ロールの設定を指定する値 (度単位)。値は –180 から +180 の範囲で、デフォルト値は 0 である。正の値はイメージ表示軸に沿ってカメラを右回りに回転することを表し、負の値はカメラの左回りの回転を表す。特定のデバイスでは、この範囲のサブセットのみが実装される場合があるので注意すること。
Zoom | ズームの設定を指定する値 (mm 単位)。値は 10 から 600 の範囲で、デフォルト値はデバイスによってそれぞれ異なる。
Exposure 次の式を元に、露出の設定を指定する値 (秒単位)。0 未満の値の場合、露出時間は 1/2n 秒である。正の値と 0 の場合、露出時間は 2n 秒である。特定のデバイスでは、この範囲のサブセットのみが実装される場合があるので注意すること。たとえば、デバイスの範囲が –7 から 1 で、ステップ 1 とする。対応する露出時間は、次のとおりである。
値 | -7 | -6 | -5 | -4 | -3 | -2 | -1 | 0 | 1
秒 | 1/128 | 1/64 | 1/32 | 1/16 | 1/8 | 1/4 | 1/2 | 1 | 2
Iris | fstop * 10 で表される絞りの設定を指定する値。
Focus | 焦点の設定を、対象に対する最適な焦点距離として指定する値 (mm 単位)。範囲とデフォルト値は、デバイスによってそれぞれ異なる。特定のデバイスでは、この範囲のサブセットのみが実装される場合があるので注意すること。


IAMClockAdjust インターフェイス

IAMClockAdjust インターフェイスは、外部ソースからフィルタ グラフにタイミング情報を提供する。マルチメディア ストリームの状況で、アプリケーションがフィルタ グラフ外のオーディオ ストリームとビデオ ストリームを両方使用している場合は、このインターフェイスを使用することで、フィルタ グラフにクロック情報を伝えることができる。これを使用して、異なるストリームの同期をとることができる。

Microsoft® DirectShow® のシステム基準クロック オブジェクトは、このインターフェイスを実装している。詳細については、「IReferenceClock」を参照すること。

このインターフェイスを使用すると、DirectShow 内のデフォルトのクロック オブジェクトを調整できる。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMClockAdjust メソッド | 説明
SetClockDelta | 時間の増分値を設定する。これによって、フィルタ グラフは、自身のクロックを外部ソースから更新できる。

IAMClockAdjust::SetClockDelta

IAMClockAdjust インターフェイス

フィルタ グラフに基準タイムを渡すことによってクロックを調整する。システム基準クロック オブジェクトに時間の増分値が追加される。

構文

HRESULT SetClockDelta(
    REFERENCE_TIME rtDelta
);

パラメータ

rtDelta
[in] 時間の差を表す値 (ミリ秒単位)。

戻り値

成功の場合は S_OK を返し、rtDelta が無効な場合は E_POINTER を返す。


IAMCollection インターフェイス

このインターフェイスはフィルタ グラフ マネージャが実装し、Microsoft® Visual Basic® やスクリプティング言語で書かれたアプリケーションが使用する。

IAMCollection によって、IPinInfo インターフェイスと IFilterInfo インターフェイスをエクスポートするオブジェクトのコレクションなどにアクセスできる。たとえば、IFilterInfo::get_Pins メソッドは、IAMCollection インターフェイスを取得して使用することで、フィルタのピンに対応している IPinInfo インターフェイスにアクセスできる。

Vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IDispatch メソッド | 説明
GetTypeInfoCount | このディスパッチ インターフェイスで利用可能なタイプ情報があるかどうかを判別する。
GetTypeInfo | GetTypeInfoCount が成功した場合は、このディスパッチ インターフェイスのタイプ情報を取得する。
GetIDsOfNames | (引数を含む) プロパティおよびメソッドのテキスト名を対応する DISPID に変換する。
Invoke | DISPID およびその他の必要なパラメータが指定された場合は、このディスパッチ インターフェイスのメソッドを呼び出すか、またはプロパティにアクセスする。
IAMCollection メソッド | 説明
get_Count | コレクション内の項目数を取得する。
get_NewEnum | このコレクションで IEnumVARIANT を実装している列挙型オブジェクトを取得する。
Item | コレクションからインデックス付きの項目を取得する。

IAMCollection::get_Count

IAMCollection インターフェイス

コレクション内の項目数を取得する。

構文

HRESULT get_Count(
    LONG *plCount
    );

パラメータ

plCount
[out, retval] コレクション内の項目数へのポインタ。

戻り値

HRESULT 値を返す。

IAMCollection::get_NewEnum

IAMCollection インターフェイス

このコレクションで IEnumVARIANT を実装している列挙型オブジェクトを取得する。

構文

HRESULT get_NewEnum(
    IUnknown **ppUnk
    );

パラメータ

ppUnk
[out, retval] このコレクションで IEnumVARIANT を実装しているオブジェクトの、IUnknown インターフェイスへのポインタのアドレス。

戻り値

HRESULT 値を返す。

IAMCollection::Item

IAMCollection インターフェイス

コレクションからインデックス付きの項目を取得する。

構文

HRESULT Item(
    long lItem,
    IUnknown **ppUnk
    );

パラメータ

lItem
[in] コレクション内のインデックス。
ppUnk
[out] コレクション項目の、返された IUnknown インターフェイスへのポインタのアドレス。

戻り値

HRESULT 値を返す。

注意

返される ppUnk パラメータは、コンテナ内のオブジェクトの種類に対応するオブジェクトを表す。これは、IFilterInfo オブジェクト、IPinInfo オブジェクト、または IMediaTypeInfo オブジェクトのいずれかである。インデックスは 0 から始まる。


IAMCopyCaptureFileProgress インターフェイス

IAMCopyCaptureFileProgress インターフェイスは、Progress というメソッドを 1 つだけ備えている。ICaptureGraphBuilder::CopyCaptureFile メソッドがこれを呼び出すことで、コピー処理の終了済みのパーセンテージに関する情報を受け取ることができる。

キャプチャ アプリケーションはこのメソッドを実装して、コピー処理の進行状況に関する情報を受け取る。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMCopyCaptureFileProgress メソッド | 説明
Progress | キャプチャ操作中に ICaptureGraphBuilder::CopyCaptureFile が定期的に呼び出す。

IAMCopyCaptureFileProgress::Progress

IAMCopyCaptureFileProgress インターフェイス

ICaptureGraphBuilder::CopyCaptureFile メソッドが実行しているコピー処理の進捗状況 (終了済みのパーセンテージ) をアプリケーションに送る。

構文

HRESULT Progress(
  int iProgress
  );

パラメータ

iProgress
[in]コピー処理の終了済みのパーセンテージを示す、 0 から 100 の範囲の整数。

戻り値

成功した場合は S_OK を返し、処理が中断した場合は S_FALSE を返す。

注意

通常アプリケーションは iProgress の値を使ってユーザー インターフェイスのプログレス バーをアップデートする。


IAMCrossbar インターフェイス

IAMCrossbar インターフェイスは DirectShow® アナログ ビデオ クロスバー フィルタである。このフィルタは WDM ストリーミング デバイス上のクロスバーのラッパー フィルタであり、それゆえいつもラッピングしているデバイスのフレンドリ名を前提としている。ラッパー フィルタと WDM ストリーミング デバイスの詳細については、「ハードウェア デバイスがフィルタ グラフに参加する方法」を参照すること。

アナログ ビデオ クロスバーはアナログからの信号とビデオ キャプチャ フィルタからのデジタル オーディオあるいはビデオ ソースをルーティングする。このフィルタは n 入力と m 出力の一般的なスイッチング マトリクス以降に設計されている。すべての入力信号は 1 つあるいはそれ以上の出力にルーティングされる。1 つのクロスバーはビデオとオーディオ両方をルーティングできる。ビデオピンを使って合成信号のオーディオ部分だけをルーティングする事も可能である。

注 : このインターフェイスの多くのメソッドでは、ピン インデックスをパラメータに指定する。ピン インデックスは、IEnumPins 列挙型を使用して計算する。入力ピンと出力ピンのインデックス値は、両方とも 0 から始まる。get_PinCounts メソッドを呼び出すことで、入力ピンと出力ピンの個数を取得できる。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMCrossbar メソッド | 説明
get_PinCounts | 入力ピンと出力ピンの個数を取得する。
CanRoute | クロスバー フィルタがアナログ信号またはデジタル信号をルーティングできるかどうかを判別する。
Route | 入力ピンを出力ピンへルーティングする。
get_IsRoutedTo | 指定の出力ピンに接続している入力ピンを取得する。
get_CrossbarPinInfo | 指定のピンに関連するオーディオ データまたはビデオ データを持つピンを取得する。

IAMCrossbar::CanRoute

IAMCrossbar インターフェイス

ルーティングが可能かどうかを判別する。

構文

HRESULT CanRoute (
  long OutputPinIndex,
  long InputPinIndex
  );

パラメータ

OutputPinIndex
[in] 出力ピン。
InputPinIndex
[in] 入力ピン。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

IAMCrossbar::get_CrossbarPinInfo

IAMCrossbar インターフェイス

指定のピンに関連するオーディオ データまたはビデオ データを持つピンを取得する。

構文

HRESULT get_CrossbarPinInfo (
  BOOL IsInputPin,

  long PinIndex,

  long *PinIndexRelated,

  long *PhysicalType
  );

パラメータ

IsInputPin
[in] 入力ピンの場合は TRUE を指定し、出力ピンの場合は FALSE を指定する。
PinIndex
[in] 関連ピンを検索する基準となるピン。
PinIndexRelated
[out] 関連ピンのインデックス値へのポインタ。
PhysicalType
[out] ピンの物理的な種類 (オーディオまたはビデオ) へのポインタ。PhysicalConnectorType 列挙型のメンバを返す。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

たとえばこのメソッドは、指定のビデオ ピンに関連するオーディオ ピンを取得する。

IAMCrossbar::get_IsRoutedTo

IAMCrossbar インターフェイス

指定の出力ピンに接続している入力ピンを取得する。

構文

HRESULT get_IsRoutedTo (

  long OutputPinIndex,

  long *InputPinIndex

  );

パラメータ

OutputPinIndex
[in] 出力ピン。
InputPinIndex
[out] 接続している入力ピンへのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

IAMCrossbar::get_PinCounts

IAMCrossbar インターフェイス

入力ピンと出力ピンの個数を取得する。

構文

HRESULT get_PinCounts(

  long *OutputPinCount,

  long *InputPinCount

  );

パラメータ

OutputPinCount
[out] 出力ピンの個数へのポインタ。
InputPinCount
[out] 入力ピンの個数へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

IAMCrossbar::Route

IAMCrossbar インターフェイス

入力ピンを出力ピンにルーティングする。

構文

HRESULT Route (
  long OutputPinIndex,
  long InputPinIndex
  );

パラメータ

OutputPinIndex
[in] 出力ピン。
InputPinIndex
[in] 入力ピン。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

ピンのインデックスは 0 から始まる。


IAMDirectSound インターフェイス

このインターフェイスは、DSound オーディオ レンダラ フィルタで実装される。アプリケーションでは、IAMDirectSound インターフェイスを使用して、ほかのサウンド アプリケーションにフォーカスが設定されている場合に、アプリケーションのサウンドが依然として聞こえるかどうかを制御し、サウンドに関連付けられるアプリケーションのウィンドウを制御する。

注 : このインターフェイスに現在実装されているのは、GetWindowFocus メソッドと SetWindowFocus メソッドだけである。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを返す。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMDirectSound メソッド | 説明
GetDirectSoundInterface | 現在は実装されていない。
GetPrimaryBufferInterface | 現在は実装されていない。
GetSecondaryBufferInterface | 現在は実装されていない。
ReleaseDirectSoundInterface | 現在は実装されていない。
ReleasePrimaryBufferInterface | 現在は実装されていない。
ReleaseSecondaryBufferInterface | 現在は実装されていない。
SetWindowFocus | 現在のメディア ファイルのサウンド再生を処理するウィンドウを設定する。
GetWindowFocus | 現在のメディア ファイルのサウンド再生を処理しているウィンドウを取得する。

IAMDirectSound::GetDirectSoundInterface

IAMDirectSound インターフェイス

このメソッドは現在実装されていない。E_NOTIMPL を返す。

構文

HRESULT GetDirectSoundInterface(
  LPDIRECTSOUND *lplpds
);

パラメータ

lplpds
現在のサウンド デバイスのインターフェイスを指す、IDirectSound インターフェイスへのポインタのアドレス。

戻り値

E_NOTIMPL を返す。

実装されると、このメソッドは次のいずれかの値を返す。

E_FAIL | 利用できるサウンド デバイスはない。
E_INVALIDARG | lplpds パラメータが NULL である。
E_NOTIMPL | DirectSound がインストールされていない。
NOERROR | メソッドが成功した。

IAMDirectSound::GetPrimaryBufferInterface

IAMDirectSound インターフェイス

このメソッドは現在実装されていない。E_NOTIMPL を返す。

構文

HRESULT GetDirectSoundInterface(
  LPDIRECTSOUNDBUFFER *lplpdsb
);

パラメータ

lplpdsb
現在のサウンド デバイスのプライマリ サウンド バッファを指す、IDirectSoundBuffer インターフェイスへのポインタのアドレス。

戻り値

E_NOTIMPL を返す。

実装されると、このメソッドは次のいずれかの値を返す。

E_FAIL | 利用できるサウンド デバイスはない。
E_INVALIDARG | lplpdsb パラメータが NULL である。
E_NOTIMPL | DirectSound がインストールされていない。
NOERROR | メソッドが成功した。

IAMDirectSound::GetSecondaryBufferInterface

IAMDirectSound インターフェイス

このメソッドは現在実装されていない。E_NOTIMPL を返す。

構文

HRESULT GetSecondaryBufferInterface(
  LPDIRECTSOUNDBUFFER *lplpdsb
);

パラメータ

lplpdsb
IDirectSoundBuffer インターフェイスへのポインタのアドレス。終了時には、現在のサウンド デバイスのセカンダリ サウンド バッファを指す。

戻り値

E_NOTIMPL を返す。

実装されると、このメソッドは次のいずれかの値を返す。

E_FAIL | 利用できるサウンド デバイスはない。
E_INVALIDARG | lplpdsb パラメータが NULL である。
E_NOTIMPL | DirectSound がインストールされていない。
NOERROR | メソッドが成功した。

IAMDirectSound::GetWindowFocus

IAMDirectSound インターフェイス

現在のメディア ファイルのサウンド再生を処理しているウィンドウを取得する。

構文

HRESULT GetWindowFocus(
  HWND hWnd,
  BOOL bMixingOnOrOff
);

パラメータ

hWnd
サウンド再生ウィンドウへのハンドル。この値が NULL の場合、サウンドはウィンドウに関連付けられていない。Windows NT® 4.0 では、現在、ウィンドウなしでのサウンド再生はサポートされていないので注意すること。
bMixingOnOrOff
サウンドをミキシングするか (TRUE)、ミキシングしないか (FALSE) を示す値。

戻り値

次のいずれかの値を返す。
E_FAIL | 利用できるサウンド デバイスはない。
E_INVALIDARG | 引数 hWnd が無効である。
E_NOTIMPL | DirectSound がインストールされていない。
NOERROR | メソッドが成功した。

IAMDirectSound::ReleaseDirectSoundInterface

IAMDirectSound インターフェイス

このメソッドは現在実装されていない。E_NOTIMPL を返す。

構文

HRESULT ReleaseDirectSoundInterface(
  LPDIRECTSOUND lpds
);

パラメータ

lpds
解放する IDirectSound インターフェイスへのポインタ。

戻り値

E_NOTIMPL を返す。

実装されると、このメソッドは次のいずれかの値を返す。

E_FAIL | 指定の IDirectSound インターフェイスへの参照がなく、これを解放できない。
E_INVALIDARG | lpds パラメータが NULL である。
NOERROR | メソッドが成功した。

IAMDirectSound::ReleasePrimaryBufferInterface

IAMDirectSound インターフェイス

このメソッドは現在実装されていない。E_NOTIMPL を返す。

構文

HRESULT ReleasePrimaryBufferInterface(
  LPDIRECTSOUNDBUFFER lpdsb

);

パラメータ

lpdsb
解放する IDirectSoundBuffer インターフェイスへのポインタ。

戻り値

E_NOTIMPL を返す。

実装されると、このメソッドは次のいずれかの値を返す。

E_FAIL | 指定の IDirectSoundBuffer インターフェイスへの参照がなく、これを解放できない。
E_INVALIDARG | lpdsb パラメータが NULL である。
NOERROR | メソッドが成功した。

IAMDirectSound::ReleaseSecondaryBufferInterface

IAMDirectSound インターフェイス

このメソッドは現在実装されていない。E_NOTIMPL を返す。

構文

HRESULT ReleaseSecondaryBufferInterface(
  LPDIRECTSOUNDBUFFER lpdsb
);

パラメータ

lpdsb
解放する IDirectSoundBuffer インターフェイスへのポインタ。

戻り値

E_NOTIMPL を返す。

実装されると、このメソッドは次のいずれかの値を返す。

E_FAIL | 指定の IDirectSoundBuffer インターフェイスへの参照がなく、これを解放できない。
E_INVALIDARG | lpdsb パラメータが NULL である。
NOERROR | メソッドが成功した。

IAMDirectSound::SetWindowFocus

IAMDirectSound インターフェイス

現在のメディア ファイルのサウンド再生を処理するウィンドウを設定する。

構文

HRESULT SetWindowFocus(
  HWND hWnd,
  BOOL bMixingOnOrOff
);

パラメータ

hWnd
サウンド再生ウィンドウへのハンドル。この値が NULL の場合、サウンドはウィンドウに関連付けられない。Windows NT 4.0 では、現在、ウィンドウなしでのサウンド再生はサポートされていないので注意すること。
bMixingOnOrOff
サウンドをミキシングするか (TRUE)、ミキシングしないか (FALSE) を示す値。

戻り値

次のいずれかの値を返す。
E_FAIL | 利用できるサウンド デバイスはない。
E_INVALIDARG | 引数 hWnd が無効である。
E_NOTIMPL | DirectSound がインストールされていない。
NOERROR | メソッドが成功した。


IAMDroppedFrames インターフェイス

IAMDroppedFrames インターフェイスは、キャプチャ フィルタからアプリケーションに対して、フィルタが欠落させたフレーム (送信しなかったフレーム)、実現されたフレーム レート (グラフの実行時間を欠落しなかったフレーム数で割った値)、および実現されたデータ レート (グラフの実行時間をフレームの平均サイズで割った値) に関する情報を提供する。ドロップ フレーム数が多いと、ビデオ クリップの滑らかさが損なわれる可能性がある。

アプリケーションが IAMStreamControl インターフェイスまたは ICaptureGraphBuilder::ControlStream を使用してピンをオフにしている場合でも、欠落フレームと非欠落フレームを、ビデオ キャプチャ ドライバが引き続きカウントしている可能性がある。多くの場合、そのカウントに意味はない。アプリケーションにとって、ピンがオンのときのみ欠落フレームと非欠落フレームの個数が意味を持つ場合は、IAMStreamControl::StartAt または ICaptureGraphBuilder::ControlStream でピンをオンにした直後に IAMDroppedFrames::GetNumDropped および IAMDroppedFrames::GetNumNotDropped を呼び出すことによって、その値を求めることができる。この後の GetNumDropped または GetNumNotDropped への呼び出しで返される値から前の値を引くことによって、ピンがオンの間にドロップされた個数が得られる。多くの場合、この値に意味がある。IAMStreamControl::StartAt または ICaptureGraphBuilder::ControlStream への呼び出しがピンを即座にオンにせず、指定の時間が経過した後でピンをオンにする場合は、通知 (EC_STREAM_CONTROL_STARTED) を受け取ってから最初の GetNumDropped および GetNumNotDropped を呼び出す必要がある。詳細については、IAMStreamControl に関するドキュメントを参照すること。両方のインターフェイスを適切に使用するキャプチャ アプリケーションの例については、CAPTURE のサンプルを参照すること。

キャプチャ フィルタのビデオ出力ピンは、常にこのインターフェイスを実装する。

キャプチャ フィルタが State_Stopped から State_Paused に変化するたびに、すべてのカウントを 0 にリセットする必要がある。

このインターフェイスの実装の詳細については、「ビデオ キャプチャ フィルタの開発」を参照すること。

アプリケーションは、キャプチャの際は常にこのインターフェイスを使用して、現在のキャプチャの状態を更新する。キャプチャの終了後、アプリケーションはこのインターフェイスを使用して、最終的なキャプチャの結果を判別する。

注 : このインターフェイスのメソッドには、実装されていないものがある。多くのフィルタでは、GetNumDropped と GetNumNotDropped のみが実装される。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMDroppedFrames メソッド | 説明
GetNumDropped | 前回のストリーミングの開始以降、ピンが欠落させた総フレーム数を取得する。
GetNumNotDropped | ピンがダウンストリームに配信した (欠落しなかった) 総フレーム数を取得する。
GetDroppedInfo | ドロップ フレーム番号の配列を取得する。
GetAverageFrameSize | ドロップ フレームの平均サイズを取得する。

IAMDroppedFrames::GetAverageFrameSize

IAMDroppedFrames インターフェイス

ピンが欠落させたフレームの平均サイズを取得する。

構文

HRESULT GetAverageFrameSize(
    long *plAverageSize );

パラメータ

plAverageSize
[out, retval] ストリーミングの開始以降、ピンが送信したフレームの平均サイズへのポインタ (バイト単位)。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

GetAverageFrameSize への呼び出しでデータがキャプチャされない場合、plAverageSize は値 0 を返す。

IAMDroppedFrames::GetDroppedInfo

IAMDroppedFrames インターフェイス

ピンが欠落させたフレーム番号の配列を取得する。

構文

HRESULT GetDroppedInfo(
    long lSize,
    long *plArray,
    long *plNumCopied );

パラメータ

lSize
[in] 要求される配列内の要素数。
plArray
[out] 配列へのポインタ。
plNumCopied
[out, retval] 設定された配列要素数へのポインタ。フィルタが任意の要素数の保存を決め、要求したフレーム数分だけこの情報を保存しないことがあるので、この値は lSize と異なる場合がある。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

フィルタは、ドロップ フレームの最初の lSize 数までそのフレーム数を配列に書き込み、それによって plNumCopied を設定する。

IAMDroppedFrames::GetNumDropped

IAMDroppedFrames インターフェイス

前回のストリーミングの開始以降、ピンが欠落させた総フレーム数を取得する。

構文

HRESULT GetNumDropped(
    long *plDropped );

パラメータ

plDropped
[out] ドロップされた総フレーム数へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

IAMDroppedFrames::GetNumNotDropped

IAMDroppedFrames インターフェイス

ピンがダウンストリームに配信した (欠落しなかった) 総フレーム数を取得する。

構文

HRESULT GetNumNotDropped(
  long *plNotDropped );

パラメータ

plNotDropped
[out] 欠落しなかった総フレーム数へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。


IAMExtDevice インターフェイス

IAMExtDevice インターフェイスは、外部デバイスを制御する基本インターフェイスである。このインターフェイスを実装すると、さまざまな種類のデバイスを制御できる。ただし、現在の Microsoft® DirectShow® の実装では VCR に限られる。IAMExtDevice インターフェイスは外部ハードウェアの全般的な設定を制御するもので、VCR の詳細設定を制御する IAMExtTransport インターフェイスと組み合わせて使用することが想定されている。フィルタが SMPTE (Society of Motion Picture and Television Engineers) タイムコードを管理していて、外部デバイスが該当する機能を備えている場合は、IAMTimecodeReader、IAMTimecodeGenerator、および IAMTimecodeDisplay の各インターフェイスも実装できる。

VCR などの外部デバイスを制御するフィルタまたはアプリケーションを作成する場合は、このインターフェイスを実装する。このインターフェイスが制御するのはデバイスの全般情報なので、外部デバイス固有の詳細なプロパティを制御するには、IAMExtTransport インターフェイスを実装する。

アプリケーションでは、VCR などの外部デバイスを直接インスタンス化および制御できる。しかし、これらのデバイスがグラフ内の唯一のフィルタであっても、常にフィルタ グラフのコンテキストの中でこれらのデバイスをインスタンス化することが推奨される。

このインターフェイスは、アプリケーションに外部デバイス制御を追加する場合に使用する。

アプリケーションでは、フィルタ グラフを使用してフィルタを列挙し、適切なフィルタから IAMExtDevice インターフェイスを直接取得する。

ハードウェアの要件

外部 VCR を制御するには、特定のハードウェアの要件が推奨される。RS-422 シリアル インターフェイスを持つ VCR の場合は、特別なシリアル ポート カードまたは外付けの RS-232 対 RS-422 アダプタが必要である。さらに、最適なパフォーマンスを得るには、16550 高性能 UART (Universal Asynchronous Receiver/Transmitter) が組み込まれたシリアル ポート カードをコンピュータが装着し、38.4 ボーなどの高速なボーレートを実現する必要がある。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMExtDevice メソッド | 説明
GetCapability | 外部デバイスの機能を取得する。
get_ExternalDeviceID | 外部デバイスのモデル番号を取得する。
get_ExternalDeviceVersion | 外部デバイスのオペレーティング ソフトウェアのバージョン番号を取得する。
put_DevicePort | 外部デバイスの接続先の通信ポートを指定する。
get_DevicePower | 外部デバイスの電源モードがオン、オフ、スタンバイのどれであるかを取得する。
put_DevicePower | 外部デバイスの電源モードをオン、オフ、またはスタンバイに設定する。
Calibrate | 外部デバイスの転送メカニズムをキャリブレートする。
get_DevicePort | 外部デバイスの接続先の通信ポートを取得する。

IAMExtDevice::Calibrate

IAMExtDevice インターフェイス

外部デバイスの転送メカニズムをキャリブレートする。

構文

HRESULT Calibrate(
    HEVENT hEvent,
    long Mode,
    long *pStatus
);

パラメータ

hEvent
[in] このプロセスの終了を通知するために使用するイベント。
Mode
[in] キャリブレーション プロセスをアクティブまたは非アクティブにする値。次のいずれかを指定する。
ED_ACTIVE | キャリブレーション プロセスをアクティブにする。
ED_INACTIVE | キャリブレーション プロセスを非アクティブにする。
NULL | 現在の状態がアクティブまたは非アクティブであることを判別するときに使用する。
pStatus
[out] OATRUE または OAFALSE に設定される変数へのポインタ。OATRUE はイベントがアクティブであることを表し、OAFALSE は非アクティブであることを表す。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

このメソッドは、キャリブレーションが必要な特定の外部デバイスで使用する。たとえば、テープを巻き戻してカウンタをリセットする場合、またはタイムコード リーダーやジェネレータのフレーム オフセットを計算する場合などがこれに相当する。

各種外部デバイスに対応するフィルタでは、デバイスが必要とするキャリブレーションに応じて、このメソッドをそれぞれ異なるフォーマットで実装できる。このメソッドでは、IMediaEventSink インターフェイスがイベント シンクを既に設定している、または別のイベント通知メソッドが設定されていることが前提である。

IAMExtDevice::GetCapability

IAMExtDevice インターフェイス

外部デバイスの機能を取得する。

構文

HRESULT GetCapability(
    long Capability,
    long *pValue,
    double *pdblValue
);

パラメータ

Capability
[in] 確認する機能を指定する値。次のいずれかを指定する。
ED_DEVCAP_CAN_RECORD | デバイスが記録可能かどうかを確認する。
ED_DEVCAP_CAN_RECORD_STROBE | デバイスがシングル フレーム記録可能かどうかを確認する。
ED_DEVCAP_CAN_SAVE | デバイスがデータを保存可能かどうかを確認する。
ED_DEVCAP_DEVICE_TYPE | 外部デバイスの種類を確認する。
ED_DEVCAP_HAS_AUDIO | デバイスにオーディオ機能があるかどうかを確認する。
ED_DEVCAP_HAS_VIDEO | デバイスにビデオ機能があるかどうかを確認する。
ED_DEVCAP_USES_FILES | デバイスにファイル システムが組み込まれているかどうかを確認する。
pValue
[out] Capability パラメータで指定されたプロパティの機能を示す値を受け取る変数へのポインタ。ED_DEVCAP_DEVICE_TYPE を除くすべてのプロパティでは、この変数は OATRUE または OAFALSE に設定される。OATRUE はプロパティがサポートされることを表し、OAFALSE はプロパティがサポートされないことを表す。ED_DEVCAP_DEVICE_TYPE の場合、変数は次のいずれかの値に設定される。
ED_DEVTYPE_ATR | オーディオ テープ レコーダ
ED_DEVTYPE_CG | キャラクタ ジェネレータ
ED_DEVTYPE_DDR | デジタル ディスク レコーダ
ED_DEVTYPE_DVE | デジタル ビデオ エフェクト ユニット
ED_DEVTYPE_GPI | 汎用インターフェイス トリガ
ED_DEVTYPE_KEYER | ビデオ キーヤー
ED_DEVTYPE_LASERDISK | レーザー ディスク
ED_DEVTYPE_MIXER_AUDIO | オーディオ ミキサー
ED_DEVTYPE_MIXER_VIDEO | ビデオ ミキサー
ED_DEVTYPE_ROUTER | ビデオ ルーター
ED_DEVTYPE_TBC | タイムベース コレクタ
ED_DEVTYPE_TCG | タイムコード ジェネレータ/リーダー
ED_DEVTYPE_VCR | VCR
ED_DEVTYPE_WIPEGEN | ビデオ ワイプ ジェネレータ
ED_DEVTYPE_JOYSTICK | ジョイスティック
ED_DEVTYPE_KEYBOARD | キーボード
pdblValue
[out] 指定のプロパティ (double 型値の場合) の機能を表す変数へのポインタ。使用されていない場合は NULL が渡される。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

大きな値や浮動小数点の値を返す場合を除き、すべての戻り値は pValue で返される。大きな値や浮動小数点の値は、pdblValue パラメータで返される。

IAMExtDevice::get_DevicePort

IAMExtDevice インターフェイス

外部デバイスの接続先の通信ポートを取得する。

構文

HRESULT get_DevicePort(
    long *pDevicePort
);

パラメータ

pDevicePort
[out] デバイスの接続先のポートを指定する、次のいずれかの値に設定される変数へのポインタ。
DEV_PORT_1394 | IEEE 1394 バス
DEV_PORT_ARTI | ARTI ドライバ
DEV_PORT_COM1 | COM1
DEV_PORT_COM2 | COM2
DEV_PORT_COM3 | COM3
DEV_PORT_COM4 | COM4
DEV_PORT_DIAQ | Diaquest ドライバ
DEV_PORT_SIM | シミュレーション ポート
DEV_PORT_USB | USB (Universal Serial Bus)

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

参照

IAMExtDevice::put_DevicePort

IAMExtDevice::get_DevicePower

IAMExtDevice インターフェイス

外部デバイスの電源モード (オン、オフ、スタンバイ) を取得する。

構文

HRESULT get_DevicePower(
    long *pPowerMode
);

パラメータ

pPowerMode
[out] 外部デバイスの電源モードを指定する次のいずれかの値に設定される変数へのポインタ。
ED_POWER_OFF | オフ
ED_POWER_ON | オン
ED_POWER_STANDBY | スタンバイ

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

参照

IAMExtDevice::put_DevicePower

IAMExtDevice::get_ExternalDeviceID

IAMExtDevice インターフェイス

外部デバイスのモデル番号を取得する。

構文

HRESULT get_ExternalDeviceID(
    LPOLESTR *ppszData
);

パラメータ

ppszData
[out] メーカー固有の ID 番号または文字列のテキストを受け取る変数へのポインタのアドレス。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

IAMExtDevice::get_ExternalDeviceVersion

IAMExtDevice インターフェイス

外部デバイスのオペレーティング ソフトウェアのバージョン番号を取得する。

構文

HRESULT get_ExternalDeviceVersion(
    LPOLESTR *ppszData
);

パラメータ

ppszData
[out] 外部デバイスの、メーカー固有のオペレーティング ソフトウェアのバージョン番号を受け取る変数へのポインタのアドレス。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

IAMExtDevice::put_DevicePort

IAMExtDevice インターフェイス

外部デバイスの接続先の通信ポートを指定する。

構文

HRESULT put_DevicePort(
    long DevicePort
);

パラメータ

DevicePort
[in] デバイスの接続先のポート。次のいずれかを指定する。
DEV_PORT_1394 | IEEE 1394 バス
DEV_PORT_ARTI | ARTI ドライバ
DEV_PORT_COM1 | COM1
DEV_PORT_COM2 | COM2
DEV_PORT_COM3 | COM3
DEV_PORT_COM4 | COM4
DEV_PORT_DIAQ | Diaquest ドライバ
DEV_PORT_MIN | DEV_PORT_SIM
DEV_PORT_SIM | シミュレーション ポート ("非ハードウェア" シミュレーションで使用する)
DEV_PORT_USB | USB (Universal Serial Bus)

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

参照

IAMExtDevice::get_DevicePort

IAMExtDevice::put_DevicePower

IAMExtDevice インターフェイス

外部デバイスの電源モードをオン、オフ、またはスタンバイに設定する。

構文

HRESULT put_DevicePower(
    long PowerMode
);

パラメータ

PowerMode
[in] デバイスの電源モードを指定する値。次のいずれかの値に設定する。
ED_POWER_OFF | オフ
ED_POWER_ON | オン
ED_POWER_STANDBY | スタンバイ

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

参照

IAMExtDevice::get_DevicePower


IAMExtTransport インターフェイス

IAMExtTransport インターフェイスは、外部 VCR の特定の動作を制御するメソッドを備えている。このメソッドでは、通常、VCR とコンピュータとの間のデータ変換の方法を決定する、転送プロパティを設定および取得する。このインターフェイスは、トランスポートの特定の動作を制御するものなので、外部デバイスの全般的な動作を制御する IAMExtDevice インターフェイスと組み合わせて実装する必要がある。VCR 以外の外部デバイスを制御するには、2 通りの方法がある。1 つは、必要なメソッドを使用し、残りに対しては E_NOTIMPL を返す方法である。もう 1 つは、新しいインターフェイスを設計し、IAMExtDevice を集成する方法である。

このインターフェイスは、開発者が編集イベントを定義するためのメソッドも備えている。編集イベントはコンテンツのオーサリング処理を促進するもので、編集プロパティ セットにグループ化される個別の編集プロパティで構成される。編集プロパティ セットでは、トランスポート上での実際の記録シーケンスや、単純な位置指定コマンドを定義できる。たとえば、編集の特定のモードの指定、記録シーケンスの イン点と アウト点の記録、またはブックマークと呼ばれる位置の記憶などを行うことができる。SetEditPropertySet メソッドは、編集プロパティ セットと呼ばれる編集プロパティのグループを作成または登録するものである。一方 SetEditProperty によって、各編集プロパティのパラメータと値をアプリケーションで定義できる。これは比較的高度な技術を要するので、実装は上級開発者が担当する。

VCR などの外部デバイスを制御するフィルタまたはアプリケーションを作成する場合は、このインターフェイスを実装する。このインターフェイスはデバイスの特定の情報を制御するものなので、IAMExtDevice インターフェイスと共に実装する必要がある。

アプリケーションでは、VCR などを対象とする、外部デバイス制御フィルタを直接インスタンス化および制御できる。しかし、これらがグラフ内の唯一のフィルタであっても、常にフィルタ グラフのコンテキストの中でインスタンス化することが強く推奨される。

実装は、制御される外部デバイスの種類によってそれぞれ異なる。デバイスによっては、メソッドを適用できない場合に E_NOTIMPL が返される。

このインターフェイスは、コンピュータに接続されているビデオ テープ マシンとオーディオ テープ マシンをフィルタで制御する場合に使用する。このインターフェイスは、オーディオとビデオの "バッチ キャプチャ" と "テープ出力" を実装するアプリケーションでも一般的に使用される。

アプリケーションは、フィルタ グラフを使用してフィルタを列挙し、適切なフィルタから IAMExtTransport インターフェイスを直接取得する。

ハードウェアの要件

外部 VCR を制御するには、特定のハードウェアの要件が推奨される。RS-422 シリアル インターフェイスを持つ VCR の場合は、特別なシリアル ポート カードまたは外付けの RS-232 対 RS-422 アダプタが必要である。さらに、最適なパフォーマンスを得るには、16550 高性能 UART (Universal Asynchronous Receiver/Transmitter) が組み込まれたシリアル ポート カードをコンピュータが装着し、38.4 ボーなどの高速なボーレートを実現する必要がある。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMExtTransport メソッド | 説明
GetCapability | 外部トランスポートの全般機能を取得する。
put_MediaState | メディアの現在の状態を設定する。
get_MediaState | メディアの現在の状態を取得する。
put_LocalControl | 外部デバイスの状態をローカル制御またはリモート制御に設定する。
get_LocalControl | 外部デバイスの状態を取得する。
GetStatus | 外部トランスポートの状態を判別する。
GetTransportBasicParameters | 外部トランスポートの基本パラメータの設定値を取得する。
SetTransportBasicParameters | 外部トランスポートの基本パラメータを設定する。
GetTransportVideoParameters | 外部トランスポートのビデオ パラメータの設定値を取得する。
SetTransportVideoParameters | 外部トランスポートのビデオ パラメータを設定する。
GetTransportAudioParameters | 外部トランスポートのオーディオ パラメータの設定値を取得する。
SetTransportAudioParameters | 外部トランスポートのオーディオ パラメータを設定する。
put_Mode | 新しいトランスポート モード (再生、停止、記録、編集など) への移行を設定する。
get_Mode | トランスポートのモード (再生、停止、記録、編集など) を取得する。
put_Rate | 速度変更が可能な外部デバイスの再生速度を設定する。
get_Rate | 速度変更が可能な外部デバイスの put_Rate で設定された再生速度を取得する。
GetChase | チェース モードの状態を取得する。
SetChase | チェース モードを有効または無効にする。
GetBump | バンプ モードの状態を取得する。
SetBump | 複数の外部デバイスの同期をとるために再生速度を変更する。
get_AntiClogControl | ヘッド詰まり防止コントロールが有効かどうかを判別する。
put_AntiClogControl | トランスポートのヘッド詰まり防止コントロールを有効または無効にする。
GetEditPropertySet | 編集プロパティ セットの現在の状態を取得する。
SetEditPropertySet | 編集プロパティのグループを形成する編集プロパティを登録する。
GetEditProperty | 特定の編集プロパティ セットに関連付けられている個別のパラメータと値を取得する。
SetEditProperty | 特定の編集プロパティ セットに関連付けられている個別のパラメータと値を定義する。
get_EditStart | 外部トランスポートの編集コントロールがアクティブかどうかを判別する。
put_EditStart | トランスポートのエディット コントロールをアクティブにする (可能な場合)。

IAMExtTransport::get_AntiClogControl

IAMExtTransport インターフェイス

ヘッド詰まり防止コントロールが有効かどうかを判別する。

構文

HRESULT get_AntiClogControl(
    long *pEnabled
);

パラメータ

pEnabled
[out] ヘッド詰まり防止が有効かどうかを示す値へのポインタ。OATRUE はヘッド詰まり防止が有効であることを表し、OAFALSE は無効であることを表す。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

参照

IAMExtTransport::put_AntiClogControl

IAMExtTransport::GetBump

IAMExtTransport インターフェイス

バンプ モードの状態を取得する。

構文

HRESULT GetBump(
    long *pSpeed,
    long *pDuration
);

パラメータ

pSpeed
[out] 一時速度 (標準速度の倍数) へのポインタ。
pDuration
[out] 現在のタイム フォーマットで表されるバンプ時間幅へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

このメソッドは、アクティブな "バンプ" の一時速度と残りの時間幅を返す。

サポートされるタイム フォーマットについては、(SDK ルート)\Include\Edevdefs.h の中の "IAMExtTransport Basic Parms" を参照すること。

参照

IAMExtTransport::SetBump

IAMExtTransport::GetCapability

IAMExtTransport インターフェイス

外部トランスポートの全般機能を取得する。

構文

HRESULT GetCapability(
    long Capability,
    long *pValue,
    double *pdblValue
);

パラメータ

Capability
[in] 照会する機能。次のいずれかを指定する。
ED_TRANSCAP_CAN_BUMP_PLAY | トランスポートで、同期をとるために速度を変更できるかどうかを確認する。
ED_TRANSCAP_CAN_DELAY_AUDIO_IN | トランスポートで、ディレイ イン オーディオ編集を行うかどうかを確認する。
ED_TRANSCAP_CAN_DELAY_AUDIO_OUT | トランスポートで、ディレイ アウト オーディオ編集を行うかどうかを確認する。
ED_TRANSCAP_CAN_DELAY_VIDEO_IN | トランスポートで、ディレイ イン ビデオ編集を行うかどうかを確認する。
ED_TRANSCAP_CAN_DELAY_VIDEO_OUT | トランスポートで、ディレイ アウト ビデオ編集を行うかどうかを確認する。
ED_TRANSCAP_CAN_EJECT | トランスポートで、メディアをイジェクトできるかどうかを確認する。
ED_TRANSCAP_CAN_PLAY_BACKWARDS | トランスポートで、メディアをリバース再生 (負のレート) できるかどうかを確認する。
ED_TRANSCAP_CAN_SET_EE | トランスポートで、入力映像を出力で表示できるかどうかを確認する。
ED_TRANSCAP_CAN_SET_PB | トランスポートで、メディア再生映像を出力で表示できるかどうかを確認する。
ED_TRANSCAP_FWD_VARIABLE_MAX | 最高フォワード速度 (再生速度の倍数) を pdblValue で返す。
ED_TRANSCAP_FWD_VARIABLE_MIN | 最低フォワード速度 (再生速度の倍数) を pdblValue で返す。
ED_TRANSCAP_REV_VARIABLE_MAX | 最高リバース速度 (再生速度の倍数) を pdblValue で返す。
ED_TRANSCAP_REV_VARIABLE_MIN | 最低リバース速度 (再生速度の倍数) を pdblValue で返す。
ED_TRANSCAP_FWD_SHUTTLE_MAX | 最高フォワード シャトル モード速度 (再生速度の倍数) を pdblValue で返す。
ED_TRANSCAP_LTC_TRACK | リニア タイムコード (LTC) のトラック番号を pValue で返す。
ED_TRANSCAP_NUM_AUDIO_TRACKS | オーディオ トラック数を pValue で返す。
ED_TRANSCAP_FWD_SHUTTLE_MIN | 最低フォワード シャトル モード速度 (再生速度の倍数) を pdblValue で返す。
ED_TRANSCAP_REV_SHUTTLE_MAX | 最高リバース シャトル モード速度 (再生速度の倍数) を pdblValue で返す。
ED_TRANSCAP_REV_SHUTTLE_MIN | 最低リバース シャトル モード速度 (再生速度の倍数) を pdblValue で返す。
ED_TRANSCAP_HAS_DT_OATRUE | デバイスがダイナミック トラッキングを備えていることを指定する。
pValue
[out] Capability で指定される機能がサポートされるかどうかを示す値へのポインタ。サポートされる場合は OATRUE を返し、サポートされない場合は OAFALSE を返す。
pdblValue
[out] Capability で指定されるプロパティの機能を示す値へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

すべての OATRUE 値と OAFALSE 値は pValue に返される。数値は pValue または pdblValue に返される。pValue パラメータでは足りない double 型の値を返す場合、pdblValue パラメータが使用される。いずれかのパラメータが不要な場合は NULL を返す。

IAMExtTransport::GetChase

IAMExtTransport インターフェイス

チェース モードの状態を取得する。

構文

HRESULT GetChase(
    long *pEnabled,
    long *pOffset,
    HEVENT *phEvent
);

パラメータ

pEnabled
[out] チェースが有効かどうかを示す値へのポインタ。OATRUE はチェースが有効であることを表し、OAFALSE はチェースが無効であることを表す。
pOffset
[out] 現時点からのオフセットへのポインタ。これは、トランスポートが再生の間保持するオフセットを表す。
phEvent
[out] チェース オフセットが設定されていることを伝える完了通知へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

pOffset の時間は、現在のタイム フォーマットで与えられる。サポートされるタイム フォーマットについては、(SDK ルート)\Include\Edevdefs.h の中の "IAMExtTransport Basic Parms" を参照すること。

参照

IAMExtTransport::SetChase

IAMExtTransport::GetEditProperty

IAMExtTransport インターフェイス

特定の編集イベントに関連付けられているパラメータと値を取得する。

構文

HRESULT GetEditProperty(
    long EditID,
    long Param,
    long *pValue
);

パラメータ

EditID
[in] 編集プロパティ セットの ID 番号。
Param
[in] 値を調べる元となる編集イベント パラメータ。
pValue
[out] Param で指定されるパラメータの戻り値へのポインタ。OATRUE、OAFALSE、または固有の値が返される。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

参照

IAMExtTransport::SetEditProperty

IAMExtTransport::GetEditPropertySet

IAMExtTransport インターフェイス

特定の編集プロパティ セットに関連付けられている個別のパラメータと値を取得する。

構文

HRESULT GetEditPropertySet(
    long EditID,
    long *pState
);

パラメータ

EditID
[in] 編集プロパティ セットの ID 番号。
pState
[out] 編集プロパティ セットの状態へのポインタ。次のいずれかを取得する。
DC_SET_ACTIVE | 編集プロパティ セットをアクティブにする。
DC_SET_DELETE | 編集プロパティ セットを削除する。
DC_SET_INACTIVE | 編集プロパティ セットを非アクティブにする。
DC_SET_REGISTER | 編集プロパティ セットを登録する。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

参照

IAMExtTransport::SetEditPropertySet

IAMExtTransport::get_EditStart

IAMExtTransport インターフェイス

外部トランスポートのエディット コントロールがアクティブかどうかを判別する。

構文

HRESULT get_EditStart(
    long *pValue
);

パラメータ

pValue
[out] エディット コントロールがアクティブかどうかを示す値へのポインタ。OATRUE はエディット コントロールがアクティブであることを表し、OAFALSE はアクティブでないことを表す。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

参照

IAMExtTransport::put_EditStart

IAMExtTransport::get_LocalControl

IAMExtTransport インターフェイス

外部デバイスの状態を取得する。

構文

HRESULT get_LocalControl(
    long *pState
);

パラメータ

pState
[out] ローカル制御またはリモート制御を示す値へのポインタ。OATRUE はローカル制御を表し、OAFALSE はリモート制御を表す。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

外部デバイスを制御するには、リモート モードでなければならない。

参照

IAMExtTransport::put_LocalControl

IAMExtTransport::get_MediaState

IAMExtTransport インターフェイス

put_MediaState で設定されるメディアの現在の状態を取得する。

構文

HRESULT get_MediaState(
    long *pState
);

パラメータ

pState
[out] メディアの現在の状態を示す戻り値へのポインタ。値はデバイスによって異なるが、次の値が含まれる。
ED_MEDIA_SPIN_DOWN | スピンが停止している (ディスク メディアの場合)。アンスレッドしている (テープ メディアの場合)。
ED_MEDIA_SPIN_UP | スピンが開始したがフル スピードではない (ディスク メディアの場合)。テープのスレッドが開始している (テープ メディアの場合)。
ED_MEDIA_UNLOAD | メディアがドライブからイジェクトされている (デバイスがイジェクト機能をサポートしている場合)。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

IAMExtTransport::get_Mode

IAMExtTransport インターフェイス

トランスポートのモード (再生、停止、記録、編集など) を取得する。

構文

HRESULT get_Mode(
    long *pMode
);

パラメータ

pMode
[out] 現在のトランスポート モードへのポインタ。有効なモードについては、「IAMExtTransport::put_Mode」を参照すること。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

IAMExtTransport::get_Rate

IAMExtTransport インターフェイス

速度変更が可能な外部デバイスの再生速度を取得する。

構文

HRESULT get_Rate(
    double *pdblRate
);

パラメータ

pdblRate
[out] IAMExtTransport::put_Rate で設定される再生速度へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

IAMExtTransport::GetStatus

IAMExtTransport インターフェイス

外部トランスポートの状態に関する詳細情報を返す。

構文

HRESULT GetStatus(
    long StatusItem,
    long *pValue
);

パラメータ

StatusItem
[in] 状態を調べる元となる項目。次のいずれかを指定できる。
ED_MODE_EDIT_CUE | デバイスがアクティブな編集イベントまで頭出ししているかどうかを確認する。
ED_MODE_FF | デバイスが早送りしているかどうかを確認する。
ED_MODE_FREEZE | デバイスが再生モードでポーズしているかどうかを確認する。
ED_MODE_LINK_OFF | トランスポート コントロールが、フィルタ グラフの実行、停止、またはポーズの制御にリンクしていないかどうかを確認する。
ED_MODE_LINK_ON | トランスポート コントロールが、フィルタ グラフの実行、停止、またはポーズの制御にリンクしているかどうかを確認する。
ED_MODE_PLAY | デバイスが再生中であるかどうかを確認する。
ED_MODE_RECORD | デバイスが記録中であるかどうかを確認する。
ED_MODE_RECORD_STROBE | デバイスがシングル フレーム記録中であるかどうかを確認する。
ED_MODE_RECORD_FREEZE | デバイスが記録モードでポーズしているかどうかを確認する。
ED_MODE_REW | デバイスが巻き戻し中であるかどうかを確認する。
ED_MODE_SHUTTLE | デバイスがシャトル (高速再生) 中かどうかを確認する。実際のトランスポート速度を判別するには IAMExtTransport::get_Rate を使用する。
ED_MODE_STEP_FWD または ED_MODE_STEP | デバイスが順方向にシングル ステップ処理 (一度に 1 つのフレームを検索) しているかどうかを確認する。
ED_MODE_STOP | デバイスが停止しているかどうかを確認する。
pValue
[out] StatusItem 内の項目がアクティブかどうかを示す値へのポインタ。OATRUE は StatusItem がアクティブであることを表し、OAFALSE はアクティブでないことを表す。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

このインターフェイスを実装する場合、その StatusItem パラメータは大半の DirectShow インターフェイスよりも拡張的であり、コードでその多様性に対処し、該当するパラメータの転送状態を確認する必要があるので注意すること。

IAMExtTransport::GetTransportAudioParameters

IAMExtTransport インターフェイス

外部トランスポートのオーディオ パラメータ設定を取得する。

構文

HRESULT GetTransportAudioParameters(
    long Param,
    long *pValue
);

パラメータ

Param
[in] 値を取得する元となるオーディオ パラメータ。次のいずれかを指定する。
ED_TRANSAUDIO_ENABLE_OUTPUT | オーディオ出力チャンネル
ED_TRANSAUDIO_ENABLE_RECORD | オーディオ録音チャンネル
ED_TRANSAUDIO_ENABLE_SELSYNC | オーディオ selsync 録音チャンネル
ED_TRANSAUDIO_SET_MONITOR | モニタ出力オーディオ チャンネル
ED_TRANSAUDIO_SET_SOURCE | オーディオ ソース チャンネル
pValue
[out] IAMExtTransport::SetTransportAudioParameters メソッドで設定されるチャンネルへのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

IAMExtTransport::GetTransportBasicParameters

IAMExtTransport インターフェイス

トランスポートの基本パラメータの設定値を取得する。

構文

HRESULT GetTransportBasicParameters(

  long Param,

  long *pValue,

  LPOLESTR *ppszData
);

パラメータ

Param
[in] 設定値を取得する元となるパラメータ。指定できるパラメータについては、Edevdefs.h の中の "IAMExtTransport Basic Parms" を参照すること。
pValue
[out] パラメータの設定値が数値の場合、その設定値へのポインタ。
ppszData
[out] パラメータの設定値が文字列の場合、その設定値へのポインタのアドレス。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

参照

IAMExtTransport::SetTransportBasicParameters

IAMExtTransport::GetTransportVideoParameters

IAMExtTransport インターフェイス

外部トランスポートのビデオ パラメータの設定値を取得する。

構文

HRESULT GetTransportVideoParameters(
    long Param,
    long *pValue
);

パラメータ

Param
[in] 設定値を取得する元となるビデオ パラメータ。ED_TRANSVIDEO_SET_OUTPUT (ビデオ トランスポート出力パラメータ) または ED_TRANSVIDEO_SET_SOURCE (ビデオ トランスポート入力ソース) を指定する。
pValue
[out] ビデオ パラメータを受け取る変数へのポインタ。Param に ED_TRANSVIDEO_SET_SOURCE が指定されている場合、pValue は実際のビデオ入力を受け取る。Param に ED_TRANSVIDEO_SET_OUTPUT が指定されている場合、pValue は次のいずれかの値を受け取る。
ED_E2E | トランスポート モードにかかわらず、デバイスの出力に入力映像が表示される。
ED_OFF | 映像出力が無効である。
ED_PLAYBACK | メディアの再生映像が画面上に表示される。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

参照

IAMExtTransport::SetTransportVideoParameters

IAMExtTransport::put_AntiClogControl

IAMExtTransport インターフェイス

外部トランスポートのヘッド詰まり防止コントロールを有効または無効にする。

構文

HRESULT put_AntiClogControl(
    long Enable
);

パラメータ

Enable
[in] ヘッド詰まり防止コントロールが有効かどうかを示す値。OATRUE を指定すると有効になり、OAFALSE を指定すると無効になる。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

このメソッドを使用すると、自動ヘッド クリーニング機能を備えた VCR の、ビデオ ヘッドの詰まりを防ぐことができる。

参照

IAMExtTransport::get_AntiClogControl

IAMExtTransport::put_EditStart

IAMExtTransport インターフェイス

トランスポートのエディット コントロールをアクティブにする (可能な場合)。

構文

HRESULT put_EditStart(
    long Value
);

パラメータ

Value
[in] エディット コントロールをアクティブにするかどうかを示す値。OATRUE を指定するとエディット コントロールがアクティブにされ、OAFALSE を指定すると非アクティブにされる。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

このメソッドを使用すると、エディット コントロールを手動で有効にできる。エディット コントロールは、VCR 上の個別のレコード トラック、またはレコード トラックのセットを正確に有効化するものとして定義される。たとえば、ビデオだけの挿入編集では、ビデオ レコード ヘッドのみが有効化され、新しいビデオ信号が記録される。オーディオ信号は変化しない。このメソッドを使用すると、この機能を持つマシン上でオンザフライ編集を制御できる。

参照

IAMExtTransport::get_EditStart

IAMExtTransport::put_LocalControl

IAMExtTransport インターフェイス

外部トランスポートの状態をローカル制御またはリモート制御に設定する。

構文

HRESULT put_LocalControl(
    long State
);

パラメータ

State
[in] 現在の状態。OATRUE を指定するとローカルになり、OAFALSE を指定するとリモートになる。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

参照

IAMExtTransport::get_LocalControl

IAMExtTransport::put_MediaState

IAMExtTransport インターフェイス

メディアの現在の状態を設定する。

構文

HRESULT put_MediaState(
    long State
);

パラメータ

State
[in] 状態を指定する値。次のいずれかを使用する。
ED_MEDIA_SPIN_DOWN | スピンを停止する (ディスク メディアの場合)。テープをアンスレッドする (テープ メディアの場合)。
ED_MEDIA_SPIN_UP | スピンを開始する (ディスク メディアの場合)。テープをスレッドする (テープ メディアの場合)。
ED_MEDIA_UNLOAD | ドライブからメディアをイジェクトする (デバイスが機能をサポートしている場合)。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

ディスク メディアとテープ メディアについては、上のパラメータを使用する。ほかのデバイスについては、場合によっては新しいパラメータを指定する必要がある。

参照

IAMExtTransport::get_MediaState

IAMExtTransport::put_Mode

IAMExtTransport インターフェイス

新しいトランスポート モード (再生、停止、記録、編集など) への移行を設定する

構文

HRESULT put_Mode(
    long Mode
);

パラメータ

Mode
[in] トランスポート モード。次のいずれかを指定する。
ED_MODE_PLAY | 再生。
ED_MODE_STOP | 停止。
ED_MODE_FREEZE | ポーズ。
ED_MODE_THAW | 再開。
ED_MODE_FF | 早送り。
ED_MODE_REW | 巻き戻し。
ED_MODE_RECORD | 記録。
ED_MODE_RECORD_STROBE | シングル フレーム記録。
ED_MODE_STEP_FWD | 順方向のシングル ステップ。
ED_MODE_STEP_REV | 逆方向のシングル ステップ。
ED_MODE_SHUTTLE | シャトル (高速再生)。トランスポート速度を設定するには、IAMExtTransport::put_Rate と共に使用する。
ED_MODE_EDIT_CUE | アクティブな編集イベントの位置に頭出しする。
ED_MODE_LINK_ON | このメソッドをグラフの IMediaControl::Run、Stop、および Pause メソッドにリンクする。
ED_MODE_LINK_OFF | このメソッドをグラフの IMediaControl::Run、Stop、および Pause メソッドから解放する。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

参照

IAMExtTransport::get_Mode

IAMExtTransport::put_Rate

IAMExtTransport インターフェイス

速度変更が可能な外部デバイスの再生速度を設定する。

構文

HRESULT put_Rate(
    double dblRate
);

パラメータ

dblRate
[in] 再生速度の倍数を指定する。.5 は 2 分の 1、1 は標準、2 は 2 倍、3 は 3 倍を表す。以降についても同様である。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

このメソッドによって、アプリケーションは、通常のデフォルトの再生速度を基準に、再生をアクセラレーションまたは低速化できる。レート 1.0 は通常の再生速度を示す。 2.0 を指定すると、通常の 2 倍の速度で再生される。

このメソッドを IMediaPosition::put_Rate メソッドにリンクして、標準速度を基準に再生速度を設定する代替の手段にすることもできる。

参照

IAMExtTransport::get_Rate

IAMExtTransport::SetBump

IAMExtTransport インターフェイス

複数の外部デバイスの同期をとるために、再生速度を一時的に変更する。

構文

HRESULT SetBump(
    long Speed,
    long Duration
);

パラメータ

Speed
[in] 一時速度 (標準速度の倍数)。
Duration
[in] 現在のタイム フォーマットで表されるバンプ時間幅。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

このメソッドによって、物理的な同期処理の際に、トランスポートの速度をさまざまな一時速度に変更できる。このメソッドは、Duration で指定される時間が経過するまで有効である。

サポートされるタイム フォーマットについては、(SDK ルート)\Include\Edevdefs.h の中の "IAMExtTransport Basic Parms" を参照すること。

参照

IAMExtTransport::GetBump

IAMExtTransport::SetChase

IAMExtTransport インターフェイス

チェース モードを有効または無効にする。

構文

HRESULT SetChase(
    long Enable,
    long Offset,
    HEVENT hEvent
);

パラメータ

Enable
[in] チェースが有効かどうかを示す値。OATRUE を指定するとチェースは有効になり、OAFALSE を指定すると無効になる。
Offset
[in] トランスポートが保持しているタイム基準からのオフセット。現在のタイム フォーマットで指定する。
hEvent
[in] 設定されているオフセットを通知するイベント。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

SetChase メソッドは、外部トランスポートが固定のオフセットでタイムコード信号に連続的に従う場合に使用する。たとえば、コンピュータがタイムコードを生成している場合、チェースの機能を備えている VCR に対して、自身は再生モードを設定し、メディアは基準タイムコードからのオフセットを保持することを指定できる。オフセットは、再生メディアのタイムコードと、生成された基準タイムコードを比較することで決定する。

このメソッドは、メソッドがキャンセルまたは完了するまで有効である。また、フィルタに対して、トランスポートのタイムコードを定期的に読み取ることによって、トランスポートが本当に固定オフセットを保持しているかどうか、確認することを要求する。

Offset の時間は、現在のタイム フォーマットで指定する。サポートされるタイム フォーマットについては、(SDK ルート)\Include\Edevdefs.h の中の "IAMExtTransport Basic Parms" を参照すること。

参照

IAMExtTransport::GetChase

IAMExtTransport::SetEditProperty

IAMExtTransport インターフェイス

特定の編集プロパティ セットに関連付けられている個別のパラメータと値を定義する。

構文

HRESULT SetEditProperty(
    long EditID,
    long Param,
    long Value
);

パラメータ

EditID
[in] 編集プロパティ セットの ID 番号。
Param
[in] 定義する編集イベント パラメータ。
Value
[in] Param で指定されるパラメータの値。OATRUE、OAFALSE、または固有の値を使用する。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

編集イベントは、実際の記録シーケンスを定義する定義済みのプロパティのグループを参照することも、単純な位置指定コマンドを参照することもできる。たとえば、編集の特定のモードの指定、IN 点と OUT 点の記録、またはブックマークと呼ばれる位置の記憶などを行うことができる。SetEditPropertySet メソッドは、編集プロパティ セットと呼ばれる編集プロパティのグループを作成または登録するものである。一方 SetEditProperty によって、ユーザーは各編集イベントのパラメータと値を定義できる。これは比較的高度な技術を要するので、実装は上級開発者が担当する。

編集プロパティのセットを定義するには、最初に編集プロパティ セットを登録し、SetEditPropertySet メソッドで EditID を取得する。次に、SetEditProperty メソッドを使用して、各編集プロパティの固有のパラメータと値を定義する。最後に、SetEditPropertySet メソッドで編集プロパティ セットをアクティブにする。

Edevdefs.h ファイル ヘッダー ファイルには、編集プロパティ セットの有効なパラメータと値が一覧されている。

参照

IAMExtTransport::GetEditProperty

IAMExtTransport::SetEditPropertySet

IAMExtTransport インターフェイス

編集プロパティのグループである編集プロパティ セットを登録する。

構文

HRESULT SetEditPropertySet(
    long *pEditID,
    long State
);

パラメータ

pEditID
[in, out] 編集プロパティ セットの ID 番号へのポインタ。
State
[in] 編集プロパティ セットの状態。次のいずれかを指定する。
DC_SET_ACTIVE | 編集プロパティ セットをアクティブにする。
DC_SET_DELETE | 編集プロパティ セットを削除する。
DC_SET_INACTIVE | 編集プロパティ セットを非アクティブにする。
DC_SET_REGISTER | 編集プロパティ セットを登録する。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

編集イベントは、トランスポート上の実際の記録シーケンスや単純な位置指定コマンドを定義する、定義済みのプロパティのグループを参照する。たとえば、編集の特定のモードの指定、IN 点と OUT 点の記録、またはブックマークと呼ばれる位置の記憶などを行うことができる。SetEditPropertySet メソッドは、編集プロパティ セットと呼ばれる編集プロパティのグループを定義および登録するものである。一方 SetEditProperty によって、ユーザーは各編集イベント プロパティのパラメータと値を定義できる。

編集プロパティのセットを定義するには、最初に編集プロパティ セットを登録し、SetEditPropertySet メソッドで EditID を取得する。次に、SetEditProperty メソッドを使用して、各編集プロパティの固有のパラメータと値を定義する。最後に、SetEditPropertySet メソッドで編集プロパティ セットをアクティブにする。

たとえば、次のコードでは、すべてのトラック上でインサート編集を設定する。

// 編集プロパティ セット ID を登録する (メモリが割り当てられる)。
SetEditPropertySet(&EditID, ED_REGISTER);

// 編集モードを設定する。
SetEditProperty(EditID, ED_EDIT_MODE, ED_EDIT_MODE_INSERT);

// イベントの詳細を設定する。
SetEditProperty(EditID, ED_EDIT_TRACK, ED_VIDEO | ED_AUDIO_ALL);
SetEditProperty(EditID, ED_REHEARSE_MODE, ED_EDIT_PERFORM);

// (記録とソースの時間などを設定する。)

SetEditPropertySet(pEditID, ED_ACTIVE); // アクティブにする。
SetEditProperty(EditID, ED_EDIT_SEEK, OATRUE); // マシンを頭出しする。

// (グラフを起動する。)

即時編集を行うには ("オンザフライ"編集)、ED_EDIT_IMMEDIATE 編集プロパティを使用する。

編集プロパティ セットのメカニズムを使用して、タイムコード検索を行うこともできる。このためには、次のプロパティを設定する。

  1. ED_EDIT_SRC_INPOINT に目的のタイムコード値を設定する。
  2. ED_EDIT_SEEK_MODE に ED_EDIT_SEEK_EDIT_IN を設定する。
  3. ED_EDIT_SEEK に OATRUE を設定する。検索操作が起動される。

VCR 制御フィルタでは、編集と同期制御に関する各種モードの 1 つをサポートできる。

  • 1 台のマシンを使用し、このマシンがマスタとして使用されるモード : これは、ノンリニア編集にとって最も一般的な構成である。1 台の VCR で、ソース マテリアルのキャプチャと最終結果の記録が行われる。VCR のタイムコードが、フィルタ グラフのマスタ クロック基準として使用される。このモードでは、VCR において要求される機械的な同期化の必要性が最も少ない。これは、外部の機械制御のデバイスに比べて、デジタル再生エンジンの方が簡単に基準クロックに同期することができるためである。
  • 1 台のマシンを使用し、基準クロックに同期するモード : 1 台の VCR でキャプチャと再生を行う。VCR は、フィルタ グラフの基準クロックに同期する。
  • 複数のマシンを使用し、その中の 1 つがマスタとして使用されるモード : これは、リニア編集およびハイブリッド編集にとって最も一般的な構成である。フィルタ グラフのクロックはマスタ (記録) VCR に同期し、再生 VCR はフィルタ グラフのクロックに同期することが要求される。
  • 複数のマシンを使用し、すべてのマシンを基準クロックに同期するモード : これも、リニア編集およびハイブリッド編集にとって一般的な構成である。すべての VCR はフィルタ グラフのクロックに同期する。

特定のデバイスのマスタ/従属モードを判別するには、IAMExtTransport::GetCapability メソッドで ED_TRANSCAP_IS_MASTER の項目を確認する。

SMPTE タイムコードを使用してフィルタ グラフ再生をマスタ VCR に同期させることは、比較的簡単である。IAMTimecodeReader::GetTimecode メソッドから返される TIMECODE_SAMPLE には、VCR のフレーム位置とフィルタ グラフのクロックとの間の時間の関係を表す、基準クロックのタイム スタンプが含まれる。このオフセットを使用することで、ストリーム コントロール インターフェイスで再生のデジタル キャプチャを起動できる。

VCR をフィルタ グラフのクロックに同期させるには、VCR 制御フィルタに目的のタイム オフセットを送る必要がある。最も単純なケースでは、IAMExtTransport::SetChase メソッドを実行することによってこれを実現できる。1 つまたは複数のイベント編集をサポートしている場合は、編集プロパティ セットの ED_EDIT_OFFSET プロパティを使用する。

編集プロパティ セットの有効なパラメータおよび値の一覧については、[DXMedia\Include] フォルダの中の Edevdefs.h を参照すること。

参照

IAMExtTransport::GetEditPropertySet

IAMExtTransport::SetTransportAudioParameters

IAMExtTransport インターフェイス

外部トランスポートのオーディオ パラメータの設定値を設定する。

構文

HRESULT SetTransportAudioParameters(
    long Param,
    long Value
);

パラメータ

Param
[in] 設定するオーディオ パラメータ。次のいずれかを指定する。
ED_TRANSAUDIO_ENABLE_OUTPUT | 出力用のオーディオ チャンネルを有効にする。
ED_TRANSAUDIO_ENABLE_RECORD | 録音用のオーディオ チャンネルを有効にする。
ED_TRANSAUDIO_ENABLE_SELSYNC | selsync 録音用のオーディオ チャンネルを有効にする。
ED_TRANSAUDIO_SET_MONITOR | モニタ出力ソースを設定する。
ED_TRANSAUDIO_SET_SOURCE | アクティブなオーディオ入力を設定する。
Value
[in] パラメータを設定するオーディオ チャンネル。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

ED_AUDIO_1 から ED_AUDIO_24 の範囲のいずれかを選択することによって、Value に正確なチャンネルを指定する。複数のチャンネルを指定するには、or スイッチを使用する。すべてのチャンネルを指定するには、ED_AUDIO_ALL を選択する。

参照

IAMExtTransport::GetTransportAudioParameters

IAMExtTransport::SetTransportBasicParameters

IAMExtTransport インターフェイス

外部トランスポートの基本パラメータを設定する。

構文

HRESULT SetTransportBasicParameters(
    long Param,
    long Value,
    LPCOLESTR pszData
);

パラメータ

Param
[in] 設定するパラメータ。指定できるパラメータについては、Edevdefs.h の中の "IAMExtTransport Basic Parms" を参照すること。
Value
[in] 数値型のパラメータの設定値。
pszData
[in] 文字列型のパラメータの設定値へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

基本設定には、タイム フォーマット、記録方式、プリロール設定、サーボ設定などが含まれる。Edevdefs.h を参照すること。

参照

IAMExtTransport::GetTransportBasicParameters

IAMExtTransport::SetTransportVideoParameters

IAMExtTransport インターフェイス

外部トランスポートのビデオ パラメータを設定する。

構文

HRESULT SetTransportVideoParameters(
    long Param,
    long Value
);

パラメータ

Param
[in] 設定するビデオ パラメータ。ED_TRANSVIDEO_SET_OUTPUT (ビデオ トランスポート出力パラメータ) または ED_TRANSVIDEO_SET_SOURCE (ビデオ トランスポート物理入力) を指定する。
Value
[in] ED_TRANSVIDEO_SET_SOURCE フラグを設定する場合は、アクティブなビデオ入力を指定する。ED_TRANSVIDEO_SET_OUTPUT フラグを設定する場合は、次のいずれかの値を指定する。
ED_E2E | トランスポート モードにかかわらず、デバイスの出力に入力映像が表示される。
ED_OFF | 映像出力が無効である。
ED_PLAYBACK | メディアの再生映像が画面上に表示される。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

ED_TRANSVIDEO_SET_SOURCE フラグの場合、外部デバイス フィルタは物理的なピンを使用してその入力を記述する。フィルタのピンの列挙型を呼び出すと、インデックス値が返される。その値は Value パラメータとしてこのメソッドに渡される。

参照

IAMExtTransport::GetTransportVideoParameters


IAMFilterMiscFlags インターフェイス

IAMFilterMiscFlags インターフェイスは、フィルタ グラフ マネージャに対して、フィルタのデータ ストリームがソース データまたはレンダリングされるデータのどちらであるかを判別する手段を提供する。これを元に、予測されるムービー終了時までの EC_COMPLETE 通知の個数を判別できる。このインターフェイスは、VFW キャプチャ フィルタ、ファイル ライタ、およびオーディオ キャプチャ フィルタで実装される。

アプリケーションでこのインターフェイスを使用することはない。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMFilterMiscFlags メソッド | 説明
GetMiscFlags | フィルタの状態フラグを取得する。

IAMFilterMiscFlags::GetMiscFlags

IAMFilterMiscFlags インターフェイス

フィルタの状態フラグを取得する。

構文

ULONG GetMiscFlags(void);

戻り値

ストリームがレンダリングされている場合は、AM_FILTER_MISC_FLAGS_IS_RENDERED を返す。ストリームがソース データの場合は、AM_FILTER_MISC_FLAGS_IS_SOURCE を返す。両方のフラグは、AM_FILTER_MISC_FLAGS 列挙型で定義される。フィルタが IMediaSeeking をサポートし、いくつかのストリームをレンダリングする場合、AM_FILTER_MISC_FLAGS_IS_RENDERER が返される。


IAMGraphStreams インターフェイス

このインターフェイスは、ライブ ソースをレンダリングするフィルタ グラフの、動作を制御するメソッドを備えている。ライブ ソースとは、キャプチャ デバイスやネットワーク ブロードキャストのように、リアルタイムでデータをストリームするものである。フィルタ グラフ マネージャは、このインターフェイスを実装している。

アプリケーションではこのインターフェイスのメソッドを呼び出すことによって、ライブ ソースをレンダリングする際の遅延時間と同期化を、グラフが処理する方法を指定できる。詳細については、「ライブ ソース」を参照すること。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMGraphStreams メソッド | 説明
FindUpstreamInterface | 指定のピンからアップストリーム方向に、指定のインターフェイスをサポートするピンまたはフィルタを検索する。
SyncUsingStreamOffset | タイム スタンプ オフセットを使用して同期化を有効または無効にする。
SetMaxGraphLatency | グラフの最大遅延時間を設定する。

IAMGraphStreams::FindUpstreamInterface

IAMGraphStreams インターフェイス

指定のピンからアップストリーム方向に、指定のインターフェイスをサポートするピンまたはフィルタを検索する。

構文

HRESULT FindUpstreamInterface(
    IPin *pPin,
    REFIID riid,
    void **ppvInterface,
    DWORD dwFlags
);

パラメータ

pPin
[in] 検索を開始するピンの IPin インターフェイスへのポインタ。
riid
[in] 検索するインターフェイスの参照識別子。
ppvInterface
[out, iid_is(riid)] void 型ポインタのアドレス。メソッドが成功した場合、この変数は riid で指定されるインターフェイスへのポインタを受け取る。
dwFlags
[in] AM_INTF_SEARCH_FLAGS 列挙型で定義されるフラグの組み合わせ。検索対象 (ピンまたはフィルタ) を指定する。

戻り値

次のいずれかの HRESULT 値を返す。

E_NOINTERFACE | インターフェイスが見つからない。
E_POINTER | 無効なポインタ。
S_OK | 成功。

IAMGraphStreams::SetMaxGraphLatency

IAMGraphStreams インターフェイス

グラフの最大遅延時間を設定する。このメソッドを呼び出す前に、SyncUsingStreamOffset メソッドを呼び出す必要がある。

構文

HRESULT SetMaxGraphLatency(
    REFERENCE_TIME rtMaxGraphLatency
);

パラメータ

rtMaxGraphLatency
[in] 最大遅延時間を指定する基準タイム。

戻り値

成功した場合は、S_OK を返す。SyncUsingStreamOffset が呼び出されていない場合は、E_FAIL を返す。それ以外の場合は、別の HRESULT 値を返す。

注意

ライブ ソース フィルタによっては、接続時に、最大遅延時間を使用して、割り当てるバッファのサイズを確認する。グラフを作成する前にこのメソッドを呼び出すことによって、予期される遅延時間に対して十分なバッファが割り当てられていることを確認できる。

IAMGraphStreams::SyncUsingStreamOffset

IAMGraphStreams インターフェイス

タイム スタンプ オフセットを使用して、同期化を有効または無効にする。

構文

HRESULT SyncUsingStreamOffset(
    BOOL bUseStreamOffset
);

パラメータ

bUseStreamOffset
[in] タイム スタンプ オフセットを使用するかどうかを示すブール値。TRUE を指定すると、ライブ ソースはタイム スタンプ オフセットを使用してストリームの同期をとる。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

デフォルトでは、フィルタ グラフが、タイム スタンプ オフセットを使用してライブ ストリームの同期化を試みることはない。フィルタ グラフに対して、グラフ内の最大遅延時間を調べ、それに従ってタイム スタンプを調整することを求める場合は、TRUE の値を指定してこのメソッドを呼び出す。詳細については、「IAMPushSource::SetStreamOffset」を参照すること。


IAMLatency インターフェイス

このインターフェイスは、グラフに適用される遅延時間を報告する、フィルタ用のメソッドを備えている。遅延時間は、フィルタがサンプルを処理するのに要する時間として定義される。ソース フィルタの場合、遅延時間は、フィルタの最大バッファ サイズを時間の単位で表したものである。たとえば、30 フレーム/秒の速度で 1 フレームをバッファリングするビデオ キャプチャ フィルタの場合、遅延時間は約 33 ミリ秒となる。

現在のところ、このインターフェイス自体の使用はサポートされていない。ライブ データまたはリアルタイム データをストリームするソース フィルタは、このインターフェイスを継承する IAMPushSource インターフェイスを実装する必要がある。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMLatency メソッド | 説明
GetLatency | このフィルタに関連付けられている、予期される遅延時間を取得する。

IAMLatency::GetLatency

IAMLatency インターフェイス

このフィルタに関連付けられている、予期される遅延時間を取得する。

構文

HRESULT GetLatency(
    REFERENCE_TIME *prtLatency
);

パラメータ

prtLatency
[in] 遅延時間を示す基準タイムを受け取る変数へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。


IAMLine21Decoder インターフェイス

IAMLine21Decoder インターフェイスは、Line 21 デコーダ フィルタで実装される。このインターフェイスは、クローズド キャプション情報やその設定にアクセスする機能を備えており、主に、アプリケーションがクローズド キャプションの表示をオンまたはオフにするときに使用される。

クローズド キャプション情報は、テレビジョン信号の垂直同期間隔 (VBI) 内のフィールド 1 の Line 21 上で転送される。ビデオ カセット レコーダはこの情報をビデオ テープに記録するので、Line 21 デコーダ フィルタおよびその他の Microsoft® DirectShow® フィルタを使用することで、Line 21 データをキャプチャし、これを AVI (Audio-Video Interleaved) などのメディア ファイル フォーマットでディスクに保存できる。クローズド キャプション情報は、メディア ファイル内で別のストリームとして表示される。

クローズド キャプション テキストは、現在、DVD ムービーに加えてテレビの生放送番組でも使用されている。DVD ムービーの場合は、ビデオ ストリーム内の各 GOP (Group of Pictures) のユーザー データ セクションの一部として、Line 21 データを格納する。WDM (Windows Driver Model) ドライバを備えたテレビジョン レシーバ カードが、Line 21 データを提供する。

アプリケーションが GetDrawBackgroundMode メソッドと SetDrawBackgroundMode メソッドを呼び出すことによって、ユーザーは半透明なクローズド キャプション表示または不透明なクローズド キャプション表示を選択できる。

要件

Il21dec.h が必要である。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMLine21Decoder メソッド | 説明
GetDecoderLevel | クローズド キャプション デコーダ レベルを取得する。
GetCurrentService | ユーザーによって選択されている現在のクローズド キャプション サービスを取得する。
SetCurrentService | 現在のクローズド キャプション サービスを設定する。
GetServiceState | クローズド キャプション サービスの状態 (オンまたはオフ) を取得する。
SetServiceState | クローズド キャプション サービスの状態を設定する。
GetOutputFormat | サイズやビット深度などの出力ビデオ特性に関する情報を取得する。
SetOutputFormat | DirectShow Line 21 デコーダ フィルタでは実装されない。サイズやビット深度などの出力ビデオ特性に関する情報を設定する。
GetBackgroundColor | オーバーレイのバックグラウンドとして使用する物理的な色を取得する。
SetBackgroundColor | オーバーレイのバックグラウンドとして使用する物理的な色を設定する。
GetRedrawAlways | レンダラが、各サンプルの出力ビットマップ全体を再描画するかどうかを取得する。
SetRedrawAlways | レンダラが、各サンプルの出力ビットマップ全体を再描画することを設定する。
GetDrawBackgroundMode | クローズド キャプション テキストの背景が不透明または透明かどうかを取得する。
SetDrawBackgroundMode | クローズド キャプション テキストの背景を不透明または透明に設定する。

IAMLine21Decoder::GetBackgroundColor

IAMLine21Decoder インターフェイス

オーバーレイのバックグラウンドとして使用する物理的な色を取得する。

構文

HRESULT GetBackgroundColor(
    DWORD *pdwPhysColor
);

パラメータ

pdwPhysColor
バックグラウンド カラーを示す取得値へのポインタ。カラー値は DWORD 型で、ビット単位の OR で結んだ RGB 3 原色で構成される。各カラー コンポーネントのビット数は、現在のビット深度によって異なる。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。現在の DirectShow の実装では、パラメータが無効な場合は E_INVALIDARG、または成功を示す NOERROR を返す。

注意

デフォルトのバックグラウンド カラーはマジェンタである。

参照

IAMLine21Decoder::SetBackgroundColor

IAMLine21Decoder::GetCurrentService

IAMLine21Decoder インターフェイス

ユーザーによって選択されている現在のクローズド キャプション サービスを取得する。

構文

HRESULT GetCurrentService(
    AM_LINE21_CCSERVICE *lpService
);

パラメータ

lpService
現在のサービスへのポインタ。この値は、AM_LINE21_CCSERVICE 列挙型のメンバである。デフォルト サービスは AM_L21_CCSERVICE_Caption1 である。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。現在の DirectShow の実装では、パラメータが無効な場合は E_INVALIDARG、または成功を示す NOERROR を返す。

参照

IAMLine21Decoder::SetCurrentService

IAMLine21Decoder::GetDecoderLevel

IAMLine21Decoder インターフェイス

クローズド キャプション デコーダ レベルを取得する。

構文

HRESULT GetDecoderLevel(
    AM_LINE21_CCLEVEL *lpLevel
);

パラメータ

lpLevel
取得されるデコーダ レベルへのポインタ。AM_L21_CCLEVEL_TC2 (TC2) のみがチャンネル レベルとしてサポートされている。これは、元の TC1 レベルを拡張したもので、後方互換性を備えている。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。現在の DirectShow の実装では、パラメータが無効な場合は E_INVALIDARG、または成功を示す NOERROR を返す。

注意

このメソッドは、情報の参照専用である。

TC1 および TC2 はテレビジョン セットのデコーダ レベルで、テレビジョンがクローズド キャプションのバイト ペアを処理して目的のクローズド キャプションを出力できるかどうかを表す。Line 21 デコーダは TC2 レベルのデコード機能を備えており、これにはすべての TC1 デコード機能が含まれる。クローズド キャプション表示機能が組み込まれて製造されたテレビジョン セットのうち、最初の 100,000 台は TC1 準拠であった。以降の TV セットは TC2 準拠である。

IAMLine21Decoder::GetDrawBackgroundMode

IAMLine21Decoder インターフェイス

クローズド キャプション テキストのバックグラウンドが不透明または透明であるかどうかを取得する。

構文

HRESULT GetDrawBackgroundMode(
    AM_LINE21_DRAWBGMODE *lpMode
);

パラメータ

lpMode
取得されるモードへのポインタ。モードは AM_L21_DRAWBGMODE_Opaque または AM_L21_DRAWBGMODE_Transparent である。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。現在の DirectShow の実装では、パラメータが無効な場合は E_INVALIDARG、または成功を示す NOERROR を返す。

注意

デフォルトでは、クローズド キャプションのバックグラウンドは不透明である。

参照

IAMLine21Decoder::SetDrawBackgroundMode

IAMLine21Decoder::GetOutputFormat

IAMLine21Decoder インターフェイス

サイズやビット深度などの出力ビデオ特性に関する情報を取得する。

構文

HRESULT GetOutputFormat(
    LPBITMAPINFOHEADER lpbmih
);

パラメータ

lpbmih
取得される BITMAPINFOHEADER 構造体へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

成功の場合、デフォルトの実装では、ダウンストリーム フィルタが出力フォーマットを定義していなければ S_FALSE、出力フォーマットが定義されていれば S_OK を返す。

注意

デフォルトのビデオ出力サイズは 320 × 240 ピクセルである。

IAMLine21Decoder::GetRedrawAlways

IAMLine21Decoder インターフェイス

レンダラが各サンプルの出力ビットマップ全体を再描画するかどうかを取得する。

構文

HRESULT GetRedrawAlways(
    LPBOOL lpbOption
);

パラメータ

lpbOption
ビットマップ全体が再描画されるかどうかを示す値。デフォルト値は FALSE で、常に再描画されるとは限らないことを表す。TRUE は常に再描画されることを表す。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。現在の DirectShow の実装では、パラメータが無効な場合は E_INVALIDARG、または成功を示す NOERROR を返す。

参照

IAMLine21Decoder::SetRedrawAlways

IAMLine21Decoder::GetServiceState

IAMLine21Decoder インターフェイス

クローズド キャプション サービスの状態 (オンまたはオフ) を取得する。

構文

HRESULT GetServiceState(
    AM_LINE21_CCSTATE *lpState
);

パラメータ

lpState
取得される状態へのポインタ。サポートされる状態値は AM_L21_CCSTATE_On および AM_L21_CCSTATE_Off である。デフォルトでは、クローズド キャプション テキストはオフである。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。現在の DirectShow の実装では、パラメータが無効な場合は E_INVALIDARG、または成功を示す NOERROR を返す。

参照

IAMLine21Decoder::SetServiceState

IAMLine21Decoder::SetBackgroundColor

IAMLine21Decoder インターフェイス

オーバーレイのバックグラウンドとして使用する物理的な色を設定する。

構文

HRESULT SetBackgroundColor(
    DWORD dwPhysColor
);

パラメータ

dwPhysColor
物理的なバックグラウンド カラーを指定する DWORD 値。色は、ビット単位の OR で結んだ RGB 3 原色で指定される。各カラー コンポーネントのビット数は、現在のビット深度によって異なる。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。現在の DirectShow の実装では、パラメータが無効な場合は E_INVALIDARG、または成功を示す NOERROR を返す。

注意

デフォルトのバックグラウンド カラーはマジェンタである。

参照

IAMLine21Decoder::GetBackgroundColor

IAMLine21Decoder::SetCurrentService

IAMLine21Decoder インターフェイス

現在のクローズド キャプション サービスを設定する。

構文

HRESULT SetCurrentService(
    AM_LINE21_CCSERVICE Service
);

パラメータ

Service
設定するサービス。この値は、AM_LINE21_CCSERVICE 列挙型のメンバである。デフォルト サービスは AM_L21_CCSERVICE_Caption1 である。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。現在の DirectShow の実装では、パラメータが無効な場合は E_INVALIDARG、または成功を示す NOERROR を返す。

参照

IAMLine21Decoder::GetCurrentService

IAMLine21Decoder::SetDrawBackgroundMode

IAMLine21Decoder インターフェイス

クローズド キャプション テキストのバックグラウンドを不透明または透明に設定する。

構文

HRESULT SetDrawBackgroundMode(
    AM_LINE21_DRAWBGMODE Mode
);

パラメータ

Mode
設定するモード。サポートされるモードの値は、AM_L21_DRAWBGMODE_Opaque および AM_L21_DRAWBGMODE_Transparent である。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。現在の DirectShow の実装では、パラメータが無効な場合は E_INVALIDARG、または成功を示す NOERROR を返す。

注意

デフォルトでは、クローズド キャプションのバックグラウンドは不透明である。

参照

IAMLine21Decoder::GetDrawBackgroundMode

IAMLine21Decoder::SetOutputFormat

IAMLine21Decoder インターフェイス このメソッドは、DirectShow® Line 21 デコーダ フィルタでは実装されない。サイズやビット深度などの出力ビデオ特性に関する情報を設定する。

構文

HRESULT SetOutputFormat(
    LPBITMAPINFO lpbmi
);

パラメータ

lpbmi
目的の出力フォーマットを格納している指定の BITMAPINFO 構造体へのポインタ。

戻り値

DirectShow Line 21 デコーダ フィルタが実装しているインターフェイスの場合は、E_NOTIMPL を返す。

注意

デフォルトのビデオ出力サイズは 320 × 240 ピクセルである。

参照

IAMLine21Decoder::GetOutputFormat

IAMLine21Decoder::SetRedrawAlways

IAMLine21Decoder インターフェイス

レンダラが各サンプルの出力ビットマップ全体を再描画するかどうかを設定する。

構文

HRESULT SetRedrawAlways(
    BOOL bOption
);

パラメータ

bOption
ビットマップ全体を再描画するかどうかを示す値。TRUE は常に再描画することを表し、FALSE は常に再描画するとは限らないことを表す。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。現在の DirectShow の実装では、パラメータが無効な場合は E_INVALIDARG、または成功を示す NOERROR を返す。

注意

フィルタが、Line 21 デコーダ フィルタに送るバッファをダーティーな状態にしてしまった場合は、フィルタからこのメソッドを呼び出す。通常、ミキサー フィルタは、Line 21 デコーダ フィルタから直接ダウンストリームしているフィルタ グラフの中にある。ミキサー フィルタは、このメソッドを呼び出し、bOption に TRUE を指定して、ビットマップ全体が正しく再描画されることを指定する必要がある。

ダウンストリーム ミキサー、またはその処理が必要な任意のミキサーは、セカンダリ ビデオ ストリームをミックスするときに使用するバッファと同じバッファを、Line 21 デコーダに提供する場合のみ、bOption に TRUE を指定してこのメソッドを呼び出す必要がある。

bOption に TRUE を指定して再描画を行うと、可能な最適化が無効になるので、パフォーマンスは低下し、CPU の負荷は増加する。

参照

IAMLine21Decoder::GetRedrawAlways

IAMLine21Decoder::SetServiceState

IAMLine21Decoder インターフェイス

クローズド キャプション サービスの状態を設定する。

構文

HRESULT SetServiceState(
    AM_LINE21_CCSTATE State
);

パラメータ

State
指定する状態。サポートされる状態値は、AM_L21_CCSTATE_On および AM_L21_CCSTATE_Off である。クローズド キャプション テキストは、デフォルトではオフである。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。現在の DirectShow の実装では、パラメータが無効な場合は E_INVALIDARG、または成功を示す NOERROR を返す。

参照

IAMLine21Decoder::GetServiceState


IAMMediaContent インターフェイス

ストリームからメタ データを取得する。 アプリケーションは、このインターフェイスを使って、作成者、タイトル、著作権など、ストリームにエンコードされた情報を取得できる。通常、このインターフェイスは AVI スプリッタや MPEG-1 ストリーム スプリッタなどのパーサー フィルタによって公開される。

ストリーム タイプによっては、フィルタはこのインターフェイスでメソッドのサブセットをサポートすることがある。たとえば、AVI スプリッタは AVI ファイルの INFO チャンクから、著作権、作成者名、およびタイトルを取得する。ほかのメソッドは、E_NOTIMPL を返す。

Vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IDispatch メソッド | 説明
GetTypeInfoCount | このディスプ インターフェイスのタイプ情報が利用できるかどうかを判定する。
GetTypeInfo | GetTypeInfoCount が正しく返る場合に、このディスプ インターフェイスのタイプ情報を取得する。
GetIDsOfNames | 引数を含めた、プロパティとメソッドのテキスト名を、該当するディスパッチ識別子 (DISPID) に変換する。
Invoke | DISPID およびほかの必要なパラメータがある場合に、このディスプ インターフェイスのメソッドを呼び出すか、そのプロパティにアクセスする。
IAMMediaContent メソッド | 説明
get_AuthorName | 作成者名を取得する。
get_Title | タイトルを取得する。
get_Rating | レーティングを取得する。
get_Description | 内容の説明を取得する。
get_Copyright | 著作権情報を取得する。
get_BaseURL | 関連 Web コンテンツのベース URL を取得する。
get_LogoURL | ロゴの URL を取得する。
get_LogoIconURL | ロゴ アイコンの URL を取得する。
get_WatermarkURL | ウォーターマークの URL を取得する。
get_MoreInfoURL | 内容に関する追加情報の URL を取得する。
get_MoreInfoBannerImage | 関連情報バナーのイメージを取得する。
get_MoreInfoBannerURL | 関連情報バナーの URL を取得する。
get_MoreInfoText | 追加情報をテキストとして取得する。

IAMMediaContent::get_AuthorName

IAMMediaContent インターフェイス

作成者名を取得する。

構文

HRESULT get_AuthorName(
    BSTR *pbstrAuthorName
);

パラメータ

pbstrAuthorName
情報を持つ BSTR を受け取る変数へのポインタ。

戻り値

HRESULT 値を返す。次の表に示されるいずれかの値。

S_OK | 成功。
E_NOTIMPL | 実装されていない。
E_OUTOFMEMORY | メモリ不足。
VFW_E_NOT_FOUND | 項目は見つからなかった。

注意

メソッドが成功した場合、呼び出し元は SysFreeString 関数を呼び出して、返された BSTR を解放しなければならない。

IAMMediaContent::get_Title

IAMMediaContent インターフェイス

タイトルを取得する。

構文

HRESULT get_Title(
    BSTR *pbstrTitle
);

パラメータ

pbstrTitle
情報を持つ BSTR を受け取る変数へのポインタ。

戻り値

HRESULT 値を返す。次の表に示されるいずれかの値。

S_OK | 成功。
E_NOTIMPL | 実装されていない。
E_OUTOFMEMORY | メモリ不足。
VFW_E_NOT_FOUND | 項目は見つからなかった。

注意

メソッドが成功した場合、呼び出し元は SysFreeString 関数を呼び出して、返された BSTR を解放しなければならない。

IAMMediaContent::get_Rating

IAMMediaContent インターフェイス

レーティングを取得する。

構文

HRESULT get_Rating(
    BSTR *pbstrRating
);

パラメータ

pbstrRating
情報を持つ BSTR を受け取る変数へのポインタ。

戻り値

HRESULT 値を返す。次の表に示されるいずれかの値。

S_OK | 成功。
E_NOTIMPL | 実装されていない。
E_OUTOFMEMORY | メモリ不足。
VFW_E_NOT_FOUND | 項目は見つからなかった。

注意

メソッドが成功した場合、呼び出し元は SysFreeString 関数を呼び出して、返された BSTR を解放しなければならない。

IAMMediaContent::get_Description

IAMMediaContent インターフェイス

内容の説明を取得する。

構文

HRESULT get_Description(
    BSTR *pbstrDescription
);

パラメータ

pbstrDescription
情報を持つ BSTR を受け取る変数へのポインタ。

戻り値

HRESULT 値を返す。次の表に示されるいずれかの値。

S_OK | 成功。
E_NOTIMPL | 実装されていない。
E_OUTOFMEMORY | メモリ不足。
VFW_E_NOT_FOUND | 項目は見つからなかった。

注意

メソッドが成功した場合、呼び出し元は SysFreeString 関数を呼び出して、返された BSTR を解放しなければならない。

IAMMediaContent::get_Copyright

IAMMediaContent インターフェイス

著作権情報を取得する。

構文

HRESULT get_Copyright(
    BSTR *pbstrCopyright
);

パラメータ

pbstrCopyright
情報を持つ BSTR を受け取る変数へのポインタ。

戻り値

HRESULT 値を返す。次の表に示されるいずれかの値。

S_OK | 成功。
E_NOTIMPL | 実装されていない。
E_OUTOFMEMORY | メモリ不足。
VFW_E_NOT_FOUND | 項目は見つからなかった。

注意

メソッドが成功した場合、呼び出し元は SysFreeString 関数を呼び出して、返された BSTR を解放しなければならない。

IAMMediaContent::get_BaseURL

IAMMediaContent インターフェイス

関連 Web コンテンツのベース URL を取得する。

構文

HRESULT get_BaseURL(
    BSTR *pbstrBaseURL
);

パラメータ

pbstrBaseURL
情報を持つ BSTR を受け取る変数へのポインタ。

戻り値

HRESULT 値を返す。次の表に示されるいずれかの値。

S_OK | 成功。
E_NOTIMPL | 実装されていない。
E_OUTOFMEMORY | メモリ不足。
VFW_E_NOT_FOUND | 項目は見つからなかった。

注意

メソッドが成功した場合、呼び出し元は SysFreeString 関数を呼び出して、返された BSTR を解放しなければならない。

IAMMediaContent::get_LogoURL

IAMMediaContent インターフェイス

ロゴの URL を取得する。

構文

HRESULT get_LogoURL(
    BSTR *pbstrLogoURL
);

パラメータ

pbstrLogoURL
情報を持つ BSTR を受け取る変数へのポインタ。

戻り値

HRESULT 値を返す。次の表に示されるいずれかの値。

S_OK | 成功。
E_NOTIMPL | 実装されていない。
E_OUTOFMEMORY | メモリ不足。
VFW_E_NOT_FOUND | 項目は見つからなかった。

注意

メソッドが成功した場合、呼び出し元は SysFreeString 関数を呼び出して、返された BSTR を解放しなければならない。

IAMMediaContent::get_LogoIconURL

IAMMediaContent インターフェイス

ロゴ アイコンの URL を取得する。

構文

HRESULT get_LogoIconURL(
    BSTR *pbstrLogoURL
);

パラメータ

pbstrLogoURL
情報を持つ BSTR を受け取る変数へのポインタ。

戻り値

HRESULT 値を返す。次の表に示されるいずれかの値。

S_OK | 成功。
E_NOTIMPL | 実装されていない。
E_OUTOFMEMORY | メモリ不足。
VFW_E_NOT_FOUND | 項目は見つからなかった。

注意

メソッドが成功した場合、呼び出し元は SysFreeString 関数を呼び出して、返された BSTR を解放しなければならない。

IAMMediaContent::get_WatermarkURL

IAMMediaContent インターフェイス

ウォーターマークの URL を取得する。

構文

HRESULT get_WatermarkURL(
    BSTR *pbstrWatermarkURL
);

パラメータ

pbstrWatermarkURL
情報を持つ BSTR を受け取る変数へのポインタ。

戻り値

HRESULT 値を返す。次の表に示されるいずれかの値。

S_OK | 成功。
E_NOTIMPL | 実装されていない。
E_OUTOFMEMORY | メモリ不足。
VFW_E_NOT_FOUND | 項目は見つからなかった。

注意

メソッドが成功した場合、呼び出し元は SysFreeString 関数を呼び出して、返された BSTR を解放しなければならない。

IAMMediaContent::get_MoreInfoURL

IAMMediaContent インターフェイス

内容に関する追加情報の URL を取得する。

構文

HRESULT get_MoreInfoURL(
    BSTR *pbstrMoreInfoURL
);

パラメータ

pbstrMoreInfoURL
情報を持つ BSTR を受け取る変数へのポインタ。

戻り値

HRESULT 値を返す。次の表に示されるいずれかの値。

S_OK | 成功。
E_NOTIMPL | 実装されていない。
E_OUTOFMEMORY | メモリ不足。
VFW_E_NOT_FOUND | 項目は見つからなかった。

注意

メソッドが成功した場合、呼び出し元は SysFreeString 関数を呼び出して、返された BSTR を解放しなければならない。

IAMMediaContent::get_MoreInfoBannerImage

IAMMediaContent インターフェイス

関連情報バナーのイメージを取得する。

構文

HRESULT get_MoreInfoBannerImage(
    BSTR *pbstrMoreInfoBannerImage
);

パラメータ

pbstrMoreInfoBannerImage
情報を持つ BSTR を受け取る変数へのポインタ。

戻り値

HRESULT 値を返す。次の表に示されるいずれかの値。

S_OK | 成功。
E_NOTIMPL | 実装されていない。
E_OUTOFMEMORY | メモリ不足。
VFW_E_NOT_FOUND | 項目は見つからなかった。

注意

メソッドが成功した場合、呼び出し元は SysFreeString 関数を呼び出して、返された BSTR を解放しなければならない。

IAMMediaContent::get_MoreInfoBannerURL

IAMMediaContent インターフェイス

関連情報バナーの URL を取得する。

構文

HRESULT get_MoreInfoBannerURL(
    BSTR *pbstrMoreInfoBannerURL
);

パラメータ

pbstrMoreInfoBannerURL
情報を持つ BSTR を受け取る変数へのポインタ。

戻り値

HRESULT 値を返す。次の表に示されるいずれかの値。

S_OK | 成功。
E_NOTIMPL | 実装されていない。
E_OUTOFMEMORY | メモリ不足。
VFW_E_NOT_FOUND | 項目は見つからなかった。

注意

メソッドが成功した場合、呼び出し元は SysFreeString 関数を呼び出して、返された BSTR を解放しなければならない。

IAMMediaContent::get_MoreInfoText

IAMMediaContent インターフェイス

追加情報をテキストとして取得する。

構文

HRESULT get_MoreInfoText(
    BSTR *pbstrMoreInfoText
);

パラメータ

pbstrMoreInfoText
情報を持つ BSTR を受け取る変数へのポインタ。

戻り値

HRESULT 値を返す。次の表に示されるいずれかの値。

S_OK | 成功。
E_NOTIMPL | 実装されていない。
E_OUTOFMEMORY | メモリ不足。
VFW_E_NOT_FOUND | 項目は見つからなかった。

注意

メソッドが成功した場合、呼び出し元は SysFreeString 関数を呼び出して、返された BSTR を解放しなければならない。


IAMOpenProgress インターフェイス

ファイル オープン操作の進行状況をレポートする。

ネットワーク越しにファイルをオープンするフィルタはこのインターフェイスを公開することができる。アプリケーションはそれを使ってダウンロードの進行状況を問い合わせることができる。ネットワークのレスポンスが悪いと、IGraphBuilder::RenderFile のようなメソッドは無期限にブロックしてしまうかもしれない。アプリケーションがブロックするのを防ぐために、進行状況をモニターする IAMOpenProgress を使うワーカー スレッドを作成すること。事前に定義されたタイムアウトが起きる、あるいはユーザーからのコマンドに対応して、そのワーカー スレッドは操作を終了する。

URL ファイル ソース フィルタはこのインターフェイスをサポートする。

Vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMOpenProgress メソッド | 説明
QueryProgress | ファイル オープン操作の進行状況を取得する。
AbortOperation | ファイル オープン操作の終了。

IAMOpenProgress::AbortOperation

IAMOpenProgress インターフェイス

ファイル オープン操作の終了。

構文

HRESULT AbortOperation(void);

戻り値

成功なら S_OK を返す、あるいはエラーの原因を示すHRESULT 値を返す。

IAMOpenProgress::QueryProgress

IAMOpenProgress インターフェイス

ファイル オープン操作の進行状況を取得する。

構文

HRESULT QueryProgress(
    LONGLONG *pllTotal,
    LONGLONG *pllCurrent
);

パラメータ

pllTotal
[out] 全ファイルの長さを受け取る変数へのポインタ、バイト単位。
pllCurrent
[out] ファイルのダウンロードした長さを受け取る変数へのポインタ、バイト単位。

戻り値

HRESULT 値を返す。 以下の表に示されるいずれかの値。

S_OK | 成功。
VFW_S_ESTIMATED | 戻り値は評価される。
E_UNEXPECTED | 予期せぬエラー。


IAMOverlayFX インターフェイス

IAMOverlayFX インターフェイスは、オーバーレイ ミキサー フィルタで実装される。このインターフェイスによって、アプリケーションは、ユーザーの画面上でのビデオ オーバーレイの表示方法を制御できる。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMOverlayFX メソッド | 説明
QueryOverlayFXCaps | オーバーレイ ミキサー フィルタで有効なオーバーレイ エフェクトに関する情報を取得する。
SetOverlayFX | 指定のエフェクトをオーバーレイ サーフェスに適用する。
GetOverlayFX | オーバーレイ サーフェスに現在適用されているエフェクトがある場合は、これを取得する。

IAMOverlayFX::GetOverlayFX

IAMOverlayFX インターフェイス

オーバーレイ サーフェスに現在適用されているエフェクトがある場合は、これを取得する。アプリケーションでは、フィルタ グラフの実行中にこのメソッドを呼び出すことができる。

構文

HRESULT GetOverlayFX(
    DWORD *lpdwOverlayFX
);

パラメータ

lpdwOverlayFX
[out] オーバーレイ サーフェスに現在適用されているエフェクトがある場合、これを示す値を受け取る変数へのポインタ。値は、AMOVERLAYFX 列挙型のフラグの論理和である。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。Microsoft® DirectShow® の実装では、成功の場合は S_OK を返す。NULL ポインタ引数の場合は E_POINTER を返す。

IAMOverlayFX::SetOverlayFX

IAMOverlayFX インターフェイス

指定のエフェクトをオーバーレイ サーフェスに適用する。

構文

HRESULT SetOverlayFX(
    DWORD dwOverlayFX
);

パラメータ

dwOverlayFX
[in] 適用するエフェクトを指定する値。値は、AMOVERLAYFX 列挙型フラグの論理和でなければならない。それ以外の場合、メソッドは E_INVALIDARG を返す。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。 DirectShow の実装では、次のいずれかの値、またはこれ以外の値を返す。

E_FAIL | 失敗。
E_INVALIDARG | 無効な引数。
S_OK | 成功。

注意

アプリケーションは、フィルタ グラフの実行中にこのメソッドを呼び出す必要がある。エフェクトは即時に適用される。

IAMOverlayFX::QueryOverlayFXCaps

IAMOverlayFX インターフェイス

オーバーレイ ミキサー フィルタで有効なオーバーレイ エフェクトに関する情報を取得する。

構文

HRESULT QueryOverlayFXCaps(
    DWORD *lpdwOverlayFXCaps
);

パラメータ

lpdwOverlayFXCaps
[out] オーバーレイ サーフェスのオーバーレイ エフェクト機能を示す値を受け取る変数へのポインタ。値は、AMOVERLAYFX 列挙型フラグの論理和である。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。DirectShow の実装では、次のいずれかの値を返す。

E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
S_OK | 成功。


IAMParse インターフェイス

このインターフェイスは、MPEG-2 スプリッタで実装される。このインターフェイスによって、アプリケーションは、解析時間を照会および設定できる。解析時間とは、パーサー フィルタに提供されるバイト ストリーム内での、現在の位置に関連付けられている概念上の時間である。この時間はタイム スタンプの始点にも対応しており、タイム スタンプの 0 は解析時間の 0 に対応する。

このインターフェイスを使用すると、現在のストリームの解析時間を取得または設定できる。または、現在のデータのデータ バッファをクリアできる。

要件

Amparse.h が必要である。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMParse メソッド | 説明
Flush | 現在のファイル バッファを空にする。
GetParseTime | 現在のストリーム 解析時間を取得する。
SetParseTime | 現在のストリーム 解析時間を設定する。

IAMParse::Flush

IAMParse インターフェイス

現在のファイル データをクリアし、新しいファイルにさらに早く切り替える。

構文

HRESULT Flush(void);

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_POINTER | Null ポインタ引数。
S_OK | 成功。

注意

このメソッドによって移行はさらに即時的に行われるが、シームレスの度合いも失われる。

IAMParse::GetParseTime

IAMParse インターフェイス

現在のストリーム 解析時間を取得する。MPEG-2 の場合、これは、現在のストリーム位置に対して計算されるシステム クロック タイムに対応する。

構文

HRESULT GetParseTime(
  REFERENCE_TIME *ptrParseTime
  );

パラメータ

ptrParseTime
[out] 現在の解析時間へのポインタ。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、VFW_E_NOT_CONNECTED を返す。後者は、入力ピンが接続されていないために解析時間を利用できないことを表す。

注意

MPEG-2 スプリッタ フィルタの解析時間は、現在のストリーム位置をシステム クロックで表したものである。解析時間の初期値は 0 である。

IAMParse::SetParseTime

IAMParse インターフェイス

現在のストリーム解析時間を設定する。MPEG-2 の場合、これは、現在のストリーム位置に対して計算されるシステム クロック タイムに対応する。

構文

HRESULT SetParseTime(
  REFERENCE_TIME rtPosition
  );

パラメータ

rtPosition
[in] 現在のストリーム解析時間。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、VFW_E_NOT_CONNECTED を返す。後者は、入力ピンが接続されていないために解析時間を設定できなかったことを表す。

注意

MPEG-2 スプリッタ フィルタの解析時間は、現在のストリーム位置をシステム クロックで表したものである。解析時間の初期値は 0 である。


IAMPushSource インターフェイス

このインターフェイスは、ライブ ソースをレンダリングするフィルタ グラフの同期をとるメソッドを備えている。ライブ ソースとは、キャプチャ デバイスやネットワーク ブロードキャストのように、リアルタイムでデータをストリーミングするものである。このインターフェイスは、IAMLatency インターフェイスを継承している。

ライブ データをストリームするソース フィルタは、その出力ピンにおいてこのインターフェイスを公開する必要がある。

一般に、アプリケーションはこのインターフェイスのメソッドを呼び出してはならない。代わりに、IAMGraphStreams インターフェイスを使用する。フィルタ グラフ マネージャは、このインターフェイスのメソッドを使用して、ライブ ソースをレンダリングするときに共通して発生する 2 つの問題を解決する。

  • 遅延時間 : フィルタ グラフに複数のライブ ソースが含まれる場合、しばしばその遅延時間がそれぞれ異なるために、同期がとれないことがある。たとえば、オーディオ キャプチャの遅延時間がビデオ キャプチャの遅延時間よりも長い場合、フィルタ グラフがその相違を補正しない限り、音声が映像よりも遅れてしまう。
  • レート マッチング : レンダリング フィルタがライブ ソースに接続している場合は、そのデータ消費レートを調整してソース フィルタの生成レートに一致させる必要がある。この操作を行わないと、データにギャップが生じたり (レンダラの実行速度がソースよりも速い場合)、データが欠落してしまう (ソースの実行速度の方が早い場合)。

遅延時間を補正するためにフィルタ グラフは、IAMPushSource インターフェイスを公開している各出力ピンにおいて IAMLatency::GetLatency を呼び出し、グラフ内の最大の遅延時間を調べる。次に、最大遅延時間よりも遅延時間が短いフィルタにおいて IAMPushSource::SetStreamOffset を呼び出し、各自が生成するタイム スタンプを正しいオフセットで調整する。

レート マッチングを実行するためにフィルタ グラフは、レンダリング フィルタがクロック レートをソース フィルタに一致できるかどうかを調べる必要がある。IAMPushSource::GetPushSourceFlags メソッドによって、レンダラがレートをソースに一致させても問題がないかどうかを示すフラグのセットが返される。

これらの問題は、ファイルへのキャプチャには影響しない。ファイル ライタ フィルタは、受信するサンプル上のタイム スタンプに基づいてファイルに正しく書き込む。この後、再生するときにストリームの同期化が行われる。レート マッチングに関して、データは常に可能な限り高速にファイルに書き込まれる。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMLatency メソッド | 説明
GetLatency | このフィルタに関連付けられている、予期される遅延時間を取得する。
IAMPushSource メソッド | 説明
GetPushSourceFlags | フィルタの動作を表すフラグの組み合わせを取得する。
SetPushSourceFlags | フィルタの動作を指定するフラグを設定する。
SetStreamOffset | このフィルタで生成されるタイム スタンプのオフセットを設定する。
GetStreamOffset | タイム スタンプを生成するときにフィルタが使用するオフセットを取得する。
GetMaxStreamOffset | フィルタがサポートできる最大ストリーム オフセットを取得する。
SetMaxStreamOffset | 最大ストリーム オフセットを指定する基準タイム。

IAMPushSource::GetMaxStreamOffset

IAMPushSource インターフェイス

フィルタがサポートできる最大ストリーム オフセットを取得する。

構文

HRESULT GetMaxStreamOffset(
    REFERENCE_TIME *prtMaxOffset
);

パラメータ

prtMaxOffset
[out] フィルタがサポートできる最大オフセットを示す基準タイムを受け取る変数へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。Microsoft® DirectShow® の実装では、E_POINTER または S_OK を返す。

注意

ストリームのオフセットが、サポートされる最大オフセットよりも大きな値に設定される場合、オフセット全体のデータを保持できるだけのバッファが、フィルタに用意されるとは限らない。別のバッファ ダウンストリームがない限り、データが失われる可能性がある。

IAMPushSource::GetPushSourceFlags

IAMPushSource インターフェイス

フィルタの動作を表すフラグの組み合わせを取得する。

構文

HRESULT GetPushSourceFlags(
    ULONG *pFlags
);

パラメータ

pFlags
[out] AM_PUSHSOURCE_FLAGS 列挙型で定義されるフラグの組み合わせを受け取る変数へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

このメソッドを使用すると、レンダリング フィルタがクロック レートをこのソース フィルタに確実に一致できるかどうかを判別できる。

IAMPushSource::GetStreamOffset

IAMPushSource インターフェイス

フィルタがタイム スタンプを生成するときに使用するオフセットを取得する。

構文

HRESULT GetStreamOffset(
    REFERENCE_TIME  *prtOffset
);

パラメータ

prtOffset
[out] 現在のストリーム オフセットを示す基準タイムを受け取る変数へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

IAMPushSource::SetMaxStreamOffset

IAMPushSource インターフェイス

フィルタ グラフ内で可能なストリーム オフセットを指定する。

構文

HRESULT SetMaxStreamOffset(
    REFERENCE_TIME rtMaxOffset
);

パラメータ

rtMaxOffset
[in] 最大ストリーム オフセットを指定する基準タイム。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

フィルタを接続する前にこのメソッドを呼び出すと、フィルタは適切なサイズのバッファを割り当てることができる。

IAMPushSource::SetPushSourceFlags

IAMPushSource インターフェイス

フィルタの動作を指定するフラグを設定する。現在、アプリケーションでこのメソッドを呼び出してはならない。これは、要求フラグがサポートされていないので、フィルタが設定したフラグをアプリケーションがオーバーライドしてはならないためである。

構文

HRESULT SetPushSourceFlags(
    ULONG Flags
);

パラメータ

Flags
[in] AM_PUSHSOURCE_FLAGS 列挙型で定義されるフラグの組み合わせ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

IAMPushSource::SetStreamOffset

IAMPushSource インターフェイス

このフィルタで生成されるタイム スタンプのオフセットを設定する。

構文

HRESULT SetStreamOffset(
    REFERENCE_TIME rtOffset
);

パラメータ

rtOffset
[in] フィルタの新しいストリーム オフセット。

戻り値

指定されたオフセットが、フィルタで可能な最大オフセットよりも大きい場合は、S_FALSE を返す。それ以外の場合で、成功した場合は S_OK を返す。または、エラーの原因を示す HRESULT 値を返す。

注意

遅延時間がそれぞれ異なるストリームの同期をとるために、フィルタ グラフはこのメソッドを呼び出してフィルタのストリーム オフセットを調整する。

戻り値が S_FALSE の場合、要求されたオフセットに対応できるだけの大きさのバッファを、フィルタがサポートしない可能性がある。別のダウンストリーム バッファがない限り、データが失われることがある。サポートできるフィルタの最大オフセットを取得するには、GetMaxStreamOffset メソッドを呼び出す。


IAMResourceControl インターフェイス

IAMResourceControl インターフェイスによって、アプリケーションは、オーディオ デバイス リソースが実際に必要になる前に、これをオープンし、保持できる。これによって、再生が可能であることを確認したり、デバイスが利用できないことを事前に知ることができる。

利用できないことがあるリソースの使用に備えて、フィルタでは IAMResourceControl を実装できる。このフィルタは、Microsoft® DirectShow® のオーディオ キャプチャ フィルタおよび オーディオ レンダリング フィルタで実装される。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMResourceControl メソッド | 説明
Reserve | デバイス リソースを予約または予約解除する。

IAMResourceControl::Reserve

IAMResourceControl Interface

デバイス リソースを予約または予約解除する。

構文

HRESULT Reserve(
    DWORD dwFlags
     PVOID pvReserved
);

パラメータ

dwFlags
[in] このデバイスを予約するかどうかを示すフラグ。指定できる値については、「注意」を参照すること。
pvReserved
[in] NULL でなければならない。

戻り値

デバイスが予約または予約解除された場合は、S_OK を返す。デバイスが現在予約されていて、その予約が続く場合は、S_FALSE を返す。デバイスを予約できなかった場合は、HRESULT エラー コードを返す。

注意

dwFlags に指定できる値は、AMRESCTL_RESERVEFLAGS 列挙型で定義される。

重要 リソースは何度でも予約できる。予約カウントは、S_OK が返された場合にのみインクリメントまたはデクリメントされる。S_OK が返される、デバイスを予約する各呼び出しは、デバイスの予約を解除する呼び出しに対応している必要がある。


IAMStreamConfig インターフェイス

IAMStreamConfig インターフェイスは、オーディオ キャプチャ フィルタ、ビデオ キャプチャ フィルタ、および圧縮フィルタの出力ピンに実装される。これには、VFW キャプチャ フィルタ、MJPEG コンプレッサ、ACM ラッパー、オーディオ キャプチャ フィルタ、および AVI コンプレッサ が含まれる。フィルタ開発者は、オーディオ データまたはビデオ データを処理する任意の出力ピンに、このインターフェイスを実装できる。

このインターフェイスによって、アプリケーションは、出力ピンでフィルタがサポートしているフォーマット タイプについて問い合わせることができる。また、そのピンが、ダウンストリームに接続されているピンに提案するフォーマットを設定できる。これによって、アプリケーションはピンで IGraphBuilder::Render を呼び出すことができ、グラフ ビルダは目的のフォーマットに対して適切なグラフを作成する。

注 : アプリケーションが SetFormat を呼び出した後に、IPin::EnumMediaTypes を使ってピンでサポートされるメディア タイプを列挙しようとすると、1 つのメディア タイプだけが返る。

IAMStreamConfig::GetStreamCaps メソッドは、そのストリームに関連した AM_MEDIA_TYPE 構造体を取得するとともに、ストリームの特性を詳細に記述する VIDEO_STREAM_CONFIG_CAPS 構造体または AUDIO_STREAM_CONFIG_CAPS 構造体も取得する。ビデオに関して取得される特性には、クロッピング、ストレッチング、アラインメント、細分度、データ レートなどがある。GetStreamCaps の詳細については、「キャプチャ フォーマットと圧縮フォーマットの公開」を参照すること。

フィルタ開発者へ : ビデオ キャプチャ フィルタあるいはビデオ圧縮フィルタを書く際は、このインターフェイスをビデオ出力ピンに実装する。詳細については、axextend.idl のコメントを参照すること。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMStreamConfig メソッド | 説明
SetFormat | オーディオ ストリームまたはビデオ ストリームのフォーマットを設定する。
GetFormat | オーディオ ストリームまたはビデオ ストリームのフォーマットを取得する。
GetNumberOfCapabilities | コンプレッサのストリーム機能を示す構造体の個数を取得する。
GetStreamCaps | pSCC パラメータで指定される構造体のタイプに応じて、ストリームのオーディオ機能またはビデオ機能を取得する。

IAMStreamConfig::GetFormat

IAMStreamConfig インターフェイス

オーディオ ストリームまたはビデオ ストリームのフォーマットを取得する。

構文

HRESULT GetFormat(
  AM_MEDIA_TYPE **pmt
  );

パラメータ

pmt
[out] AM_MEDIA_TYPE 構造体へのポインタのアドレス。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

メディア タイプ構造体の使用が終了したら、DeleteMediaType 関数を呼び出し、構造体を解放する。

IAMStreamConfig::GetNumberOfCapabilities

IAMStreamConfig インターフェイス

コンプレッサのストリーム機能を示す構造体の個数を取得する。

構文

HRESULT GetNumberOfCapabilities(
  int *piCount,
  int *piSize
  );

パラメータ

piCount
[out] サポートされる VIDEO_STREAM_CONFIG_CAPS 構造体または AUDIO_STREAM_CONFIG_CAPS 構造体の個数へのポインタ。
piSize
[out] 構成の構造体 (AUDIO_STREAM_CONFIG_CAPS または VIDEO_STREAM_CONFIG_CAPS) のサイズへのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

IAMStreamConfig::GetStreamCaps

IAMStreamConfig インターフェイス

pSCC パラメータで指定される構造体のタイプに応じて、ストリームのオーディオ、ビデオ、またはその他の機能を取得する。

構文

HRESULT GetStreamCaps(
  int iIndex,
  AM_MEDIA_TYPE **pmt,
  BYTE *pSCC
  );

パラメータ

iIndex
[in] 目的のメディア タイプと機能のペアに対するインデックス。このペアの総数を取得するには、GetNumberOfCapabilities メソッドを使用する。指定できるインデックス値は、0 から (ペアの総数 - 1) の範囲である。
pmt
[out] AM_MEDIA_TYPE 構造体へのポインタのアドレス。
pSCC
[out] ストリーム構成構造体へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

このメソッドによって、ピンのメディア タイプを列挙するという従来の方法よりも、有効なメディア タイプに関して詳細な情報を取得できる。このため、通常は、ピンを列挙する方法ではなくこのメソッドを使用する。可能なビデオ キャプチャ レート、メディア タイプ、およびサイズなどの情報は、VIDEO_STREAM_CONFIG_CAPS 構造体で返される。入力数、サンプリング レート、およびビット レートの細分度をはじめとする、フィルタの出力ピンのオーディオ機能については、AUDIO_STREAM_CONFIG_CAPS 構造体で返される。

DeleteMediaType を呼び出すと、pmt メディア タイプを解放できる。

GetStreamCaps の詳細については、「キャプチャ フォーマットと圧縮フォーマットの公開」を参照すること。

IAMStreamConfig::SetFormat

IAMStreamConfig インターフェイス

オーディオ ストリームまたはビデオ ストリームのフォーマットを設定する。

構文

HRESULT SetFormat(
  AM_MEDIA_TYPE *pmt
  );

パラメータ

pmt
[in] AM_MEDIA_TYPE 構造体へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

ピンがストリーム中の場合は、このメソッドを呼び出しても失敗する。

出力ピンが未接続で、これにこのメディア タイプを接続できる場合は、このメソッドから S_OK が返され、指定のメディア タイプの列挙が開始される。具体的には、このフォーマットを、CTransformOutputPin::GetMediaType 関数の iPosition パラメータで、フォーマット番号が 0 として指定する。このタイプだけを設定および許可することによって、ピンにおいて接続が発生するときにこのフォーマットを使用するようにできる。

出力ピンが接続済みで、このタイプを提供できる場合は、ピンを再接続する。ただし、ほかのピンがメディア タイプを許可できない場合、この呼び出しは失敗し、それまでの接続がそのまま残される。

パラメータ値として NULL を渡すと、フィルタによってはデフォルト フォーマットが設定され、このメソッドで指定した以前のフォーマットが無効になる。

フィルタがデータを生成するフレーム レートは、出力ピンが接続しているメディア タイプの、VIDEOINFOHEADER の AvgTimePerFrame フィールドで決まる。任意のフレーム レートでキャプチャできず、一定のレートでのみキャプチャできる可能性もある。ピンに接続しているメディア タイプが、対応できないフレーム レートを要求する場合は、実現できる次に最も低いフレームを提供しなければならない。たとえば、メディア タイプが AvgTimePerFrame=333333 (1 秒の約 1/30 で、1 秒あたり 30 フレームに相当する) で、ピンでは 1 秒あたり 29.97 または 35 フレームのみキャプチャできる場合は、1 秒あたり 29.97 フレームの割合でフレームを提供する必要がある。これは、この値が、提供できる中で 30 に最も近く、かつ 30 を超えない値のためである。提供するフレーム レートによって作成されるフレームの時間幅が、要求される長さよりも 1 マイクロ秒以上短くなることがない場合は、AvgTimePerFrame が単に丸め誤差を持つ場合もあるので、要求されるフレーム レートよりも高いレートを提供できる。AvgTimePerFrame フィールドが 0 の場合は、任意のデフォルトのフレーム レートでフレームを提供できる。


IAMStreamControl インターフェイス

このインターフェイスを使用すると、フィルタ上のストリームを個別に制御できる。いくつかのフィルタ上のピンは、このインターフェイスを公開している。たとえば、AVI Mux フィルタは、その入力ピンでこのインターフェイスをサポートし、オーディオ キャプチャ フィルタと WDM ビデオ キャプチャ フィルタは、それぞれの出力ピンでこのインターフェイスをサポートする。

このインターフェイスによって、アプリケーションは、指定の時間にストリームのオンとオフを切り替えることができる。たとえば、ビデオの再生中にオーディオ ストリームをオフにして音声を消すことができる。キャプチャ アプリケーションの場合は、このインターフェイスを使用することで、キャプチャの正確な開始タイムと終了タイムを指定したり、キャプチャ ストリームとプレビュー ストリームを互いに独立して制御できる。

ピンがストリーミングを開始する基準タイムを指定するには、StartAt メソッドを呼び出す。ピンがストリーミングを終了する時間を指定するには、StopAt メソッドを呼び出す。次に、フィルタ グラフ マネージャ上で IMediaControl::Run を呼び出す。

このインターフェイスを使用する場合は、次の制限事項に注意する。

  • 基準クロックはフィルタ グラフでなければならない。
  • ハードウェア オーバーレイを伴うキャプチャ カード上のプレビュー ピンは、このインターフェイスをサポートしない。
  • ビデオとオーディオをインターリーブ AVI ファイルにキャプチャしている場合、AVI Mux フィルタは両方のストリームを必要とする。一方のストリームを停止すると、フィルタはデータをインターリーブできない。詳細については、「IConfigInterleaving」を参照すること。

アプリケーションによっては、ICaptureGraphBuilder2::ControlStream メソッドの方が便利な場合がある。これは、このメソッドがグラフ レベルでのストリーム制御をサポートし、アプリケーションが各フィルタとピンを列挙する必要がないからである。

フィルタ開発者 : CBaseStreamControl 基底クラスは、このインターフェイスを実装する。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMStreamControl メソッド | 説明
StartAt | ピンに対してストリーミング データ送信の開始タイムを指定する。
StopAt | ピンに対して処理とデータ送信の終了タイムを指定する。
GetInfo | 現在のストリーミング設定に関する情報を取得する。

IAMStreamControl::GetInfo

IAMStreamControl インターフェイス

開始タイムと終了タイムを含む、現在のストリーミング設定に関する情報を取得する。

構文

HRESULT GetInfo(
    AM_STREAM_INFO *pInfo
);

パラメータ

pInfo
[out] 現在のストリーム設定が含まれている AM_STREAM_INFO 構造体へのポインタ。

戻り値

メソッドが成功した場合は、S_OK を返す。それ以外の場合は、失敗の原因を示す HRESULT 値を返す。

注意

AM_STREAM_INFO 構造体の dwFlags メンバには、有効な開始タイムと終了タイムが設定されているかどうかを示すフラグと、フィルタがデータを破棄しているかどうかを示すフラグが含まれる。

IAMStreamControl::StartAt

IAMStreamControl インターフェイス

ピンに対してストリーミング データ送信の開始タイムを指定する。ストリーミングが実際に開始すると、フィルタは EC_STREAM_CONTROL_STARTED 通知コードを送信する。

構文

HRESULT StartAt(
    const REFERENCE_TIME *ptStart,
    DWORD dwCookie
);

パラメータ

ptStart
[in] ストリーミングの開始タイムへのポインタ。NULL の場合、イベント通知を送信せずに即座に開始する。MAX_TIME の場合、既存の開始要求がキャンセルされる。
dwCookie
[in] 開始時にイベント通知と共に送信される値。ptStart が MAX_TIME または NULL の場合は無視される。

戻り値

メソッドが成功した場合は、S_OK を返す。それ以外の場合は、失敗の原因を示す HRESULT 値を返す。

注意

デフォルトでストリームは有効なので、このメソッドを呼び出す必要があるのは、StopAt メソッドを呼び出した後だけである。

ピンが実際にストリーミングを開始すると、EC_STREAM_CONTROL_STARTED イベントが通知される。先頭のイベント パラメータは、ピンの IPin インターフェイスへのポインタであり、2 番目のパラメータは、dwCookie パラメータで指定される値である。これによって、アプリケーションは、イベントを各自の要求に結び付け直すことができる。

開始タイムと終了タイムが 1 つの時点に対してスケジュールされている場合、瞬間的に開始し、そして終了する。これを使用することで、1 つのフレームをキャプチャできる。

IAMStreamControl::StopAt

IAMStreamControl インターフェイス

ピンに対して処理とデータ送信の終了タイムを指定する。

構文

HRESULT StopAt(
    const REFERENCE_TIME *ptStop,
    BOOL bSendExtra,
    DWORD dwCookie
);

パラメータ

ptStop
[in] ストリーミングの終了タイムへのポインタ。NULL の場合、イベント通知を送信せずに即座に終了する。MAX_TIME の場合、既存の終了要求がキャンセルされる。
bSendExtra
[in] スケジュールされている終了タイムを過ぎてから追加サンプルを送信するかどうかを示すブール値。TRUE を指定すると、追加サンプルが送信される。
dwCookie
[in] 終了時にイベント通知と共に送信する値。ptStart が MAX_TIME または NULL の場合は無視される。

戻り値

メソッドが成功した場合は、S_OK を返す。それ以外の場合は、失敗の原因を示す HRESULT 値を返す。

注意

ピンが実際にストリーミングを終了すると、EC_STREAM_CONTROL_STOPPED イベントが通知される。先頭のイベント パラメータは、ピンの IPin インターフェイスへのポインタであり、2 番目のパラメータは、dwCookie パラメータで指定される値である。これによって、アプリケーションは、イベントを各自の要求に結び付け直すことができる。

ビデオ キャプチャの場合は、一般に、キャプチャ フィルタの出力ピンとマルチプレクサの入力ピンの両方でこのメソッドを呼び出し、マルチプレクサからの通知のみに注意を払う。これによって、キャプチャ フィルタが余分なフレームを不必要にキャプチャすることが防止され、その一方で、マルチプレクサが最後のフレームを実際にファイルに保存することが保証される。

さらに、キャプチャ ピンの bSendExtra パラメータには TRUE を指定し、マルチプレクサ ピンには FALSE を指定する必要がある。追加フレームが送信されない場合、マルチプレクサはいつまでも終了タイムを待ち、既にすべての情報をキャプチャしたことを理解しない。マルチプレクサはキャプチャ ピンが送信した追加フレームを破棄するので、これがファイルに書き込まれることはない。上のケースに示したように、別のダウンストリーム ピンでも IAMStreamControl を使用しているのでない限り、bSendExtra に TRUE を設定してはならない。

パケットの中間の時間を指定して StopAt を呼び出すと、破棄の状態に移行する前に、フィルタはパケット全体を配信する。また、開始タイムと終了タイムが 1 つの時点に対してスケジュールされている場合は、瞬間的に開始し、そして終了する。これを使用することで、1 つのフレームをキャプチャできる。


IAMStreamSelect インターフェイス

再生する論理ストリームを制御し、それに関する情報を取得する。論理ストリームを選択する例としては、各国語をコード化しているオーディオ ストリームのセットからの選択が挙げられる。たとえばこの場合、英語、ドイツ語、フランス語で構成されるオーディオ ストリームのセットから英語を選択できる。

MPEG-1 ストリーム スプリッタ フィルタは、このインターフェイスを実装する。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMStreamSelect メソッド | 説明
Count | 有効なストリームの総数を取得する。
Info | 指定のストリームに関する情報を取得する。
Enable | 指定のストリームを有効または無効にする。

IAMStreamSelect::Count

IAMStreamSelect インターフェイス

有効なストリームの総数を取得する。

構文

HRESULT Count(
  DWORD *pcStreams
  );

パラメータ

pcStreams
[out] 有効なストリーム数を示す値へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。現在の Microsoft® DirectShow® の実装では、S_OK を返す。

IAMStreamSelect::Enable

IAMStreamSelect インターフェイス

指定のストリームを有効または無効にする。

構文

HRESULT Enable(
  long lIndex,
  DWORD dwFlags
  );

パラメータ

lIndex
[in] 目的のストリームのインデックス番号。インデックス番号は 0 から始まる。
dwFlags
[in] ストリームが有効または無効であることを示すフラグ。次のいずれかを指定する。
0 | このストリームを含むグループ内のすべてのストリームを無効にする。
AMSTREAMSELECTENABLE_ENABLE | 指定のグループ内のこのストリームだけを有効にし、ほかのすべてのストリームを無効にする。
AMSTREAMSELECTENABLE_ENABLEALL | このストリームを含むグループ内のすべてのストリームを有効にする。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。現在の DirectShow の実装では、指定のフラグのサポートが実装されていない場合は E_NOTIMPL を返し、ストリーム ID が無効の場合は E_INVALIDARG を返す。それ以外の場合は、S_OK を返す。

IAMStreamSelect::Info

IAMStreamSelect インターフェイス

指定のストリームに関する情報を取得する。

構文

HRESULT Info(
  long lIndex,
  AM_MEDIA_TYPE **ppmt,
  DWORD *pdwFlags,
  LCID *plcid,
  DWORD *pdwGroup,
  WCHAR **ppszName,
  IUnknown **ppObject,
  IUnknown **ppUnk
  );

パラメータ

lIndex
[in] 目的のストリームのインデックス番号。インデックス番号は 0 から始まる。
ppmt
[out] ストリームのメディア タイプへのポインタのアドレス。オプションである。終了時に AM_MEDIA_TYPE 構造体を解放するには、DeleteMediaType 関数を使用する。
pdwFlags
[out] ストリームの状態を示すフラグへのオプションのポインタ。有効な値は次のとおりである。
0 | このストリームは無効である。
AMSTREAMSELECTINFO_ENABLED | ストリームは有効で、このグループ内のほかのストリームも有効である。
AMSTREAMSELECTINFO_EXCLUSIVE | グループ内でこのストリームのみが有効である。
plcid
[out] ロケール コンテキスト (LCID) 値へのポインタ。LCID がない場合は、このパラメータは 0 値を指す。オプションである。
pdwGroup
[out] 論理グループへのポインタ。オプションである。
ppszName
[out] ストリーム名へのポインタのアドレス。オプションである。終了時に CoTaskMemFree 関数で解放される。
ppObject
[out] このストリームに関連付けられているピンまたはフィルタ オブジェクトへのポインタのアドレス。IAMStreamSelect::Enable メソッドが呼び出されると、オブジェクトが変わる可能性がある。関連するオブジェクトがない場合、このメソッドが返されるとこのパラメータには NULL 値が含まれる。
ppUnk
[out] ストリーム固有のインターフェイスへのポインタのアドレス。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。現在の DirectShow の実装では、lIndex が範囲外の場合は S_FALSE を返し、それ以外の場合は S_OK を返す。

注意

各グループ内の先頭のストリームはデフォルトである。


IAMTimecodeDisplay インターフェイス

IAMTimecodeDisplay インターフェイスは、外部の SMPTE/MIDI タイムコード ディスプレイ デバイスの動作を定義するプロパティとメソッドを備えている。このインターフェイスは、IAMExtDevice、IAMExtTransport、およびその他のタイムコード インターフェイスと共に実装し、VCR などのように、タイムコード データを読み取り、生成、または表示できる外部デバイスを制御する。このインターフェイスでは、VCR または同様の外部デバイスに組み込まれている物理的なタイムコード キャラクタ ジェネレータの表示を制御する。

SMPTE タイムコードの詳細については、「SMPTE タイムコード」を参照すること。

外部のタイムコード リーダーまたはタイムコード ジェネレータにおけるタイムコード表示を制御する外部デバイス フィルタで、このインターフェイスを実装する。タイムコード リーダーまたはタイムコード ジェネレータは、VCR に組み込むことも、個別の外部デバイスとして扱うこともできる。外部デバイスがタイムコードを表示できない場合、または統合ハードウェアやオーバーレイ ハードウェアを持たない内蔵カードによってタイムコードが生成されている場合は、このインターフェイスを実装してはならない。

このインターフェイスは、Microsoft® DirectShow® フィルタ グラフ内でのレンダリングを目的とするものではない。純粋に外部デバイスの表示で使用するものである。

外部デバイスとタイムコード情報の表示方法をアプリケーションで制御する必要がある場合は、このインターフェイスを使用する。

ハードウェアの要件

ハードウェア要件については、「IAMExtTransport インターフェイス」を参照すること。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMTimecodeDisplay メソッド | 説明
GetTCDisplayEnable | 外部デバイスのタイムコード キャラクタ ジェネレータ出力が有効かどうかを判別する。
SetTCDisplayEnable | 外部デバイスのタイムコード キャラクタ出力ジェネレータを有効または無効にする。
GetTCDisplay | タイムコード キャラクタ ジェネレータ出力の現在の設定を取得する。
SetTCDisplay | タイムコード キャラクタ ジェネレータ出力の特性を設定する。

IAMTimecodeDisplay::GetTCDisplay

IAMTimecodeDisplay インターフェイス

タイムコード キャラクタ ジェネレータ出力の現在の設定を取得する。

構文

HRESULT GetTCDisplay(
  long Param,
  long *pValue
  );

パラメータ

Param
[in] タイムコードの表示特性。設定を取得する元となる、次の項目のいずれかを指定する。
ED_TCD_BORDER | 黒色の文字で白色の境界、または白色の文字で黒色の境界
ED_TCD_INTENSITY | 文字の輝度 (明るさ)
ED_TCD_INVERT | 白色のバックグラウンドに黒色の文字、または黒色のバックグラウンドに白色の文字
ED_TCD_POSITION | 文字の位置
ED_TCD_SIZE | 文字のサイズ
ED_TCD_SOURCE | 表示するデータのソース
ED_TCD_TRANSPARENCY | 文字の透明度
pValue
[out] Param で指定されるパラメータの現在の設定値へのポインタ。このパラメータは、次のいずれかの値を取得する。

ED_TCD_SOURCE が Param に指定されている場合は、次のいずれかが返される。
ED_TCG | タイムコード ジェネレータ
ED_TCR | タイムコード リーダー

ED_TCD_SIZE が Param に指定されている場合は、次のいずれかが返される。
ED_LARGE | 大
ED_MED | 中
ED_SMALL | 小

ED_TCD_POSITION が Param に指定されている場合は、次のいずれかが返される。
ED_BOTTOM | 下
ED_MIDDLE | 中
ED_TOP | 上

上の値と、次のいずれかが組み合わされて返される。
ED_CENTER | 中央
ED_LEFT | 左
ED_RIGHT | 右

ED_TCD_INTENSITY が Param に指定されている場合は、次のいずれかが返される。
ED_HIGH | 高
ED_LOW | 低

ED_TCD_TRANSPARENCY が Param に指定されている場合は、0 から 4 の範囲の値が返される。0 は完全に不透明なことを表す。

ED_TCD_INVERT が Param に指定されている場合は、次のいずれかが返される。
OAFALSE | 白色のバックグラウンドに黒色の文字
OATRUE | 黒色のバックグラウンドに白色の文字

ED_TCD_BORDER が Param に指定されている場合は、次のいずれかが返される。
OAFALSE | 黒色の文字で白色の境界
OATRUE | 白色の文字で黒色の境界

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

参照

IAMTimecodeDisplay::SetTCDisplay

IAMTimecodeDisplay::GetTCDisplayEnable

IAMTimecodeDisplay インターフェイス

外部デバイスのタイムコード キャラクタ ジェネレータ出力が有効かどうかを判別する。

構文

HRESULT GetTCDisplayEnable(
  long *pState
  );

パラメータ

pState
[out] タイムコード キャラクタ ジェネレータ出力が有効かどうかを示す値へのポインタ。OATRUE は有効であることを表し、OAFALSE は無効であることを表す。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

このメソッドは、フィルタ グラフ内でのキャラクタ レンダリングを目的とするものではなく、純粋にハードウェアの表示を目的とするものである。このメソッドを使用する前に、外部のタイムコード リーダーまたはタイムコード ジェネレータが表示機能を備えていることを確認する必要がある。

参照

IAMTimecodeDisplay::SetTCDisplayEnable

IAMTimecodeDisplay::SetTCDisplay

IAMTimecodeDisplay インターフェイス

タイムコード キャラクタ ジェネレータ出力の特性を設定する。

構文

HRESULT SetTCDisplay(
  long Param,
  long Value
  );

パラメータ

Param
[in] タイムコードの表示特性。値を設定する次のいずれかのプロパティを指定する。
ED_TCD_BORDER | 黒色の文字で白色の境界、または白色の文字で黒色の境界
ED_TCD_INTENSITY | 文字の輝度 (明るさ)
ED_TCD_INVERT | 白色のバックグラウンドに黒色の文字、または黒色のバックグラウンドに白色の文字
ED_TCD_POSITION | 文字の位置
ED_TCD_SIZE | 文字のサイズ
ED_TCD_SOURCE | 表示するデータのソース
ED_TCD_TRANSPARENCY | 文字の透明度
Value
[in] Param で指定されるパラメータの設定値。次のいずれかを指定する必要がある。

ED_TCD_SOURCE が Param に指定されている場合は、次のいずれかを設定する。
ED_TCG | タイムコード ジェネレータ
ED_TCR | タイムコード リーダー

ED_TCD_SIZE が Param に指定されている場合は、次のいずれかを設定する。
ED_LARGE | 大
ED_MED | 中
ED_SMALL | 小

ED_TCD_POSITION が Param に指定されている場合は、次のいずれかを設定する。
ED_BOTTOM | 下
ED_MIDDLE | 中
ED_TOP | 上

上の値と、次のいずれかを組み合わせて指定する。
ED_CENTER | 中央
ED_LEFT | 左
ED_RIGHT | 右

ED_TCD_INTENSITY が Param に指定されている場合は、次のいずれかを設定する。
ED_HIGH | 高
ED_LOW | 低

ED_TCD_TRANSPARENCY が Param に指定されている場合は、0 から 4 の範囲の値を設定する。0 は完全に不透明で、4 は可能な限り暗い。

ED_TCD_INVERT が Param に指定されている場合は、次のいずれかを設定する。
OAFALSE | 白色の上に黒色
OATRUE | 黒色の上に白色

ED_TCD_BORDER が Param に指定されている場合は、次のいずれかを設定する。
OAFALSE | 黒色の文字で白色の境界
OATRUE | 白色の文字で黒色の境界

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

参照

IAMTimecodeDisplay::GetTCDisplay

IAMTimecodeDisplay::SetTCDisplayEnable

IAMTimecodeDisplay インターフェイス

外部デバイスのタイムコード キャラクタ出力ジェネレータを有効または無効にする。

構文

HRESULT SetTCDisplayEnable(
  long State
  );

パラメータ

State
[in] タイムコード キャラクタ出力ジェネレータを有効または無効にする値。OATRUE を指定すると有効になり、OAFALSE を指定すると無効になる。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

このメソッドは、フィルタ グラフ内でのキャラクタ レンダリングを目的とするものではなく、純粋にハードウェアの表示を目的とするものである。このメソッドを使用する前に、外部のタイムコード リーダーまたはタイムコード ジェネレータが表示機能を備えていることを確認する必要がある。

参照

IAMTimecodeDisplay::GetTCDisplayEnable


IAMTimecodeGenerator インターフェイス

IAMTimecodeGenerator インターフェイスは、外部 SMPTE/MIDI タイムコード ジェネレータがフィルタ グラフにデータを提供する方法と、タイムコードが提供されるフォーマットを指定するプロパティとメソッドを備えている。このインターフェイスは、IAMExtDevice インターフェイスおよび IAMExtTransport インターフェイスと共に実装し、VCR などの外部デバイスを制御する。このインターフェイスが備えているメソッドによって、アプリケーションは、外部デバイスがタイムコードの生成時に使用する各種の SMPTE/MIDI タイムコード モードまたはフォーマットを指定できる。また、ジェネレータが正しく動作していることを確認するメソッドも用意されている。

SMPTE タイムコードはフレーム アドレッシング システムで、ビデオ ソースとオーディオ ソースを識別し、自動トラック同期を実現し、さらに結果に関する付加データのコンテナとしての役割を果たす。SMPTE タイムコードの一番の目的は、ビデオとオーディオ用の、マシンで読み取り可能なアドレスを提供することである。これは hh:mm:ss:ff フォーマットで表示され、ANSI/SMPTE 12-1986 で定義されている。

SMPTE タイムコードの詳細については、「SMPTE タイムコード」を参照すること。

外部タイムコード リーダーにアクセスするメソッドの詳細については、「IAMTimecodeReader インターフェイス」を参照すること。

外部タイムコード ジェネレータが SMPTE/MIDI タイムコード情報を生成する方法を制御する場合は、外部デバイス フィルタにおいてこのインターフェイスを実装する。

フィルタ上で IMediaSeeking インターフェイスを公開することによって、アプリケーションはその IMediaSeeking::ConvertTimeFormat を使用して、タイムコードを Microsoft® DirectShow® 基準タイムに変換できる。

外部デバイスは、タイムコードを読み取り、そのコントロール インターフェイスを介してこれをコンピュータに送信できる必要がある (「ハードウェアの要件」を参照すること)。外部デバイスがこの機能を備えていない場合は、コンピュータにタイムコード リーダー カードを装着するか、キャプチャされたビデオ フレームに埋め込まれている VITC、またはオーディオ信号としてキャプチャされた LTC を、DirectShow タイムコード サンプルに変換するソフトウェア デコーダを作成する必要がある。

外部デバイスの中で SMPTE タイムコードを生成する場合は、このインターフェイスを使用する。

ハードウェアの要件

ハードウェアの要件については、「IAMExtTransport インターフェイス」を参照すること。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMTimecodeGenerator メソッド | 説明
GetTCGMode | SMPTE タイムコード ジェネレータ プロパティを取得する。
SetTCGMode | SMPTE タイムコード ジェネレータ プロパティを設定する。
put_VITCLine | VITC (Vertical Interval Timecode) 情報を挿入するラインを指定する。
get_VITCLine | VITC 情報が挿入されたラインを取得する。
SetTimecode | タイムコード、ユーザービット、または両方を設定する。
GetTimecode | ストリーム内で有効な最新のタイムコードまたはユーザービット値を取得する。

IAMTimecodeGenerator::GetTCGMode

IAMTimecodeGenerator インターフェイス

SMPTE タイムコード ジェネレータ プロパティを取得する。

構文

HRESULT GetTCGMode(
  long Param,
  long *pValue
  );

パラメータ

Param
[in] タイムコード ジェネレータ モード。設定値を取得する元となる、次のいずれかのモードを指定する。
ED_TCG_FRAMERATE | フレーム レート。
ED_TCG_REFERENCE_SOURCE | カウント値のソース。
ED_TCG_SYNC_SOURCE | ハードウェア クロック基準のソース。
ED_TCG_TIMECODE_TYPE | ジェネレータの SMPTE タイムコード フォーマット。
pValue
[out] Param で指定されるモードの現在の設定値へのポインタ。

ED_TCG_FRAMERATE が Param に指定されている場合、このパラメータは次のいずれかを取得する。
ED_FORMAT_SMPTE_24 | 24 フレーム/秒。
ED_FORMAT_SMPTE_25 | 25 フレーム/秒。
ED_FORMAT_SMPTE_30 | 30 フレーム/秒。フレームの欠落なし。
ED_FORMAT_SMPTE_30DROP | 30 フレーム/秒。フレームの欠落あり (実際には 29.97 フレーム/秒)。

ED_TCG_REFERENCE_SOURCE が Param に指定されている場合、このパラメータは次のいずれかを取得する。
ED_TCG_FREE | カウントの基準となるソースはない。
ED_TCG_READER | リーダーの値に同期する (jamsync)。

ED_TCG_SYNC_SOURCE が Param に指定されている場合、このパラメータは次のいずれかを取得する。
ED_TCG_FREE | ロックされない (freerun)。
ED_TCG_READER | タイムコード リーダーにロックする。
ED_TCG_VIDEO | 受信ビデオにロックする。

ED_TCG_TIMECODE_TYPE が Param に指定されている場合、このパラメータは次のいずれかを取得する。
ED_TCG_MIDI_FULL | MIDI フル フレーム タイムコード。
ED_TCG_MIDI_QF | MIDI クォーター フレーム タイムコード。
ED_TCG_SMPTE_LTC | LTC (Liner Timecode)。
ED_TCG_SMPTE_VITC | VITC (Vertical Interval Timecode)。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

このメソッドは、タイムコード ジェネレータの各種設定値を返す。ED_TCG_TIMECODE_TYPE の詳細については、「IAMTimecodeReader::SetTCRMode」を参照すること。

IAMTimecodeGenerator::GetTimecode

IAMTimecodeGenerator インターフェイス

ストリーム内で有効な最新のタイムコードまたはユーザービット値を取得する。

構文

HRESULT GetTimecode(
  PTIMECODE_SAMPLE pTimecodeSample
  );

パラメータ

pTimecodeSample
[out] TIMECODE_SAMPLE タイムコード構造体へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

このメソッドを使用すると、ストリーム内で有効な最新のタイムコード値を取得できる。これによってアプリケーションはタイムコードを監視し、ジェネレータが正しく動作していることを確認できる。

参照

IAMTimecodeGenerator::SetTimecode

IAMTimecodeGenerator::get_VITCLine

IAMTimecodeGenerator インターフェイス

VITC (Vertical Interval Timecode) 情報が挿入されたラインを取得する。

構文

HRESULT get_VITCLine(
  long *pLine );

パラメータ

pLine
[out] タイムコード情報を格納しているラインへのポインタ。有効なラインは 11 から 20 の範囲である。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

複数のラインから VITC 情報を取得するには、ハイ ビットがセットされている目的のラインごとにこのメソッドを連続して呼び出す。

参照

IAMTimecodeGenerator::put_VITCLine

IAMTimecodeGenerator::put_VITCLine

IAMTimecodeGenerator インターフェイス

VITC (Vertical Interval Timecode) 情報を挿入するラインを指定する。

構文

HRESULT put_VITCLine(
    long Line );

パラメータ

Line
[in] タイムコード情報を格納するライン。有効なラインは 11 から 20 の範囲である。0 は自動選択を表す。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

特定の複数のライン上に VITC 情報を設定するには、目的のラインごとにこのメソッドを連続して呼び出す。

以前に設定されたラインにこのラインを追加するには、ハイ ビットを設定する。

参照

IAMTimecodeGenerator::get_VITCLine

IAMTimecodeGenerator::SetTCGMode

IAMTimecodeGenerator インターフェイス

SMPTE タイムコード ジェネレータ プロパティを設定する。

構文

HRESULT SetTCGMode(
  long Param,
  long Value
  );

パラメータ

Param
[in] タイムコード ジェネレータ モード。次のいずれかのモードを指定する。
ED_TCG_FRAMERATE | フレーム レート。
ED_TCG_REFERENCE_SOURCE | カウント値のソース。
ED_TCG_SYNC_SOURCE | ハードウェア クロック基準のソース。
ED_TCG_TIMECODE_TYPE | ジェネレータの SMPTE タイムコード フォーマット。
Value
[in] Param に指定されるモードの設定値。

ED_TCG_FRAMERATE が Param に指定されている場合は、次のいずれかを設定する。
ED_FORMAT_SMPTE_24 | 24 フレーム/秒。
ED_FORMAT_SMPTE_25 | 25 フレーム/秒。
ED_FORMAT_SMPTE_30 | 30 フレーム/秒。フレームの欠落なし。
ED_FORMAT_SMPTE_30DROP | 30 フレーム/秒。フレームの欠落あり (実際には 29.97 フレーム/秒)。

ED_TCG_REFERENCE_SOURCE が Param に指定されている場合は、次のいずれかを設定する。
ED_TCG_FREE | カウントの基準となるソースはない。
ED_TCG_READER | リーダー値に同期する (jamsync)。

ED_TCG_SYNC_SOURCE が Param に指定されている場合は、次のいずれかを設定する。
ED_TCG_FREE | ロックされない (freerun)。
ED_TCG_READER | タイムコード リーダーにロックする。
ED_TCG_VIDEO | 受信ビデオにロックする。

ED_TCG_TIMECODE_TYPE が Param に指定されている場合は、次のいずれかを設定する。
ED_TCG_MIDI_FULL | MIDI フル フレーム タイムコード。
ED_TCG_MIDI_QF | MIDI クォーター フレーム タイムコード。
ED_TCG_SMPTE_LTC | LTC (Liner Timecode)。
ED_TCG_SMPTE_VITC | VITC (Vertical Interval Timecode)。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

ED_TCG_TIMECODE_TYPE の詳細については、「IAMTimecodeReader::SetTCRMode メソッド」を参照すること。

参照

IAMTimecodeGenerator::GetTCGMode

IAMTimecodeGenerator::SetTimecode

IAMTimecodeGenerator インターフェイス

タイムコード、ユーザービット値、または両方を設定する。

構文

HRESULT SetTimecode(
  PTIMECODE_SAMPLE pTimecodeSample
  );

パラメータ

pTimecodeSample
[in] TIMECODE_SAMPLE タイムコード構造体へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

タイムコードだけを設定する場合は、ユーザービット値に NULL を設定する。逆についても同様である。ジェネレータが実行している場合は、これらの値は即座に反映される。

参照

IAMTimecodeGenerator::GetTimecode


IAMTimecodeReader インターフェイス

IAMTimecodeReader インターフェイスを実装すると、外部デバイスからの SMPTE (Society of Motion Picture and Television Engineers) タイムコードや MIDI タイムコードを読み取ることができるようになる。このインターフェイスでは、外部デバイスが読み取るタイムコード フォーマット、およびそのタイムコードをメディアに埋め込む方法を指定するプロパティとメソッドを備えている。このインターフェイスは、IAMExtDevice インターフェイスおよび IAMExtTransport インターフェイスと共に使用して、VCR などのようにタイムコード データを読み取ることができる外部デバイスを制御することが求められる。

SMPTE タイムコードはフレーム アドレッシング システムで、ビデオ ソースとオーディオ ソースを識別し、自動トラック同期を実現し、さらにソース マテリアルに関する付加データのコンテナとしての役割を果たす。SMPTE タイムコードの一番の目的は、ビデオとオーディオ用の、マシンで読み取り可能なアドレスを提供することである。これは hh:mm:ss:ff (時間、分、秒、フレーム) フォーマットで表示され、ANSI/SMPTE 12-1986 で定義されている。

SMPTE タイムコードの詳細については、「SMPTE タイムコード」を参照すること。

外部デバイスが SMPTE/MIDI タイムコード情報を読み取る方法を指定する場合は、外部デバイス フィルタにおいてこのインターフェイスを実装する。

フィルタ上で IMediaSeeking インターフェイスを公開することによって、アプリケーションはその IMediaSeeking::ConvertTimeFormat メソッドを使用して、タイムコードを Microsoft® DirectShow® 基準タイムに変換できる。

外部デバイスは、タイムコードを読み取り、そのコントロール インターフェイスを介してこれをコンピュータに送信できる必要がある。外部デバイスがこの機能を備えていない場合は、コンピュータにタイムコード リーダー カードを装着するか、キャプチャされたビデオ フレーム内の VITC (Vertical Interval Timecode)、またはオーディオ信号としてキャプチャされた LTC (Linear Timecode) を、DirectShow タイムコード サンプルに変換するソフトウェア デコーダを作成する必要がある。

タイムコード情報を読み取って外部デバイスを制御する必要がある場合、または元のプログラム情報を参照しなければならない外部デバイスからのタイムコード情報をアプリケーションの中で使用する場合は、このインターフェイスを使用する。

通常、アプリケーションがタイムコードを保存するには 2 とおりの方法がある。キャプチャ ファイルに対して、追加のストリームとして書き込む方法と、拡張 AVI ファイル インデックスに格納される不連続性テーブルとして書き込む方法である。タイムコードは、キャプチャや再生をトリガする場合、または最終結果に至るまでのソース マテリアルの編集方法を記述する EDL (Edit Decision List) を作成する場合に、一般的に使用される。

タイムコードをキャプチャする場合は、これを、自身のメディア タイプを持つ個別のストリームとして扱う。マルチプレクサ フィルタを作成することによって、適切なファイルがこれを使用できる。ただし、テープからタイムコードを読み取る場合は、しばしばエラーが発生する。これは、テープのデータが抜けていたり、テープに関するその他の機械的な問題が原因である。このような場合、タイムコード ソース フィルタは単純にサンプルを破棄し、次の有効なサンプルに不連続性のプロパティのマークを付ける。

タイムコードを使用して、タイムコード付き ("ストライプ") ビデオテープからのキャプチャまたは再生をトリガする場合は、次の順序で操作を行う。

  1. キャプチャ グラフを作成し、目的の AVI ファイルを開き、必要に応じてディスク領域を事前に割り当てる。キャプチャするマテリアルを既存の AVI ファイルに追加する場合は、書き込む前にファイルの終端をシークする。キャプチャ グラフはこの位置でポーズする。
  2. VCR のキャプチャ開始点を検索し、タイムコードを記録する。この値は手動でプログラムに入力することも、アプリケーションが自動的に読み取ることもできる。自動読み取りの場合、グラフが実行していることが求められる。しかし、ファイル マルチプレクサの入力ピン上のストリーム コントロール インターフェイスが、受信サンプルを破棄することによってキャプチャを効率的に制御している必要がある。
  3. VCR をプリロール位置まで頭出しする。これは通常、ターゲット点の 5 秒前である。
  4. VCR とグラフを開始する。トリガ点、またはトリガ点からファイル ライタのプリロールを引いた時点に達すると、ストリーム コントロール インターフェイスはファイル マルチプレクサを解放し、ファイル ライタへのメディア サンプルのストリーミングを開始する。
  5. キャプチャ処理は手動で停止することも、ストリーム コントロール インターフェイスで時間幅のプロパティを設定することによって停止することもできる。

プリロール時とキャプチャ処理時の両方について、不連続なタイムコードを考慮する必要がある。タイムコードは一般的に、プリロールとキャプチャの開始点以降、連続的、かつ単調増加していくことが望まれる。この状態であれば、IMediaSeeking::ConvertTimeFormat メソッドによる、必ずしも明確でない相対的なストリーム タイムを計算しなくて済む。また、タイムコードが、キャプチャをトリガする唯一の制御信号である必要もない。Intercast やクローズド キャプション データ (XDS) などのように、垂直同期間隔に格納されるタイム スタンプ付きデータを使用して、ビデオ データとオーディオ データのディスクへのストリーミングを開始できる。

ハードウェアの要件

ハードウェアの要件については、「IAMExtTransport インターフェイス」を参照すること。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMTimecodeReader メソッド | 説明
GetTCRMode | タイムコード リーダーのプロパティを取得する。
SetTCRMode | タイムコード リーダーのプロパティを設定する。
put_VITCLine | タイムコード リーダーがタイムコードを読み取るときに使用する VITC (Vertical Interval Timecode) ラインを指定する。
get_VITCLine | タイムコード リーダーがタイムコードを読み取るときに使用する VITC ラインを取得する。
GetTimecode | 最新のタイムコード、ユーザービット、およびストリーム内で有効なフラグ値を取得する。

IAMTimecodeReader::GetTCRMode

IAMTimecodeReader インターフェイス

タイムコード リーダーのプロパティを取得する。

構文

HRESULT GetTCRMode(

  long Param,

  long *pValue

  );

パラメータ

Param
[in] 設定値を取得する元となるタイムコード リーダーのプロパティ (ED_TCR_SOURCE または ED_TCR_NOTIFY_ENABLE)。
pValue
[out] 要求されたタイムコード リーダー プロパティの値へのポインタ。Param に ED_TCR_NOTIFY_ENABLE が指定されている場合は、通知が有効であることを表す OATRUE、または OAFALSE を返す。Param に ED_TCR_SOURCE が指定されている場合は、次のいずれかの値を返す。
ED_TCR_CT | コントロール トラック
ED_TCR_LTC | LTC (Linear Timecode)
ED_TCR_VITC | VITC (Vertical Interval Timecode)
ED_TCR_LAST_VALUE | 前回の読み取り値

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

LTC は、アナログ オーディオ トラック上でバイフェーズ マーク エンコード信号として記録される。各タイムコード フレームは、時間幅内の 1 つのビデオ フレーム タイムである。

VITC は、通常、ビデオ信号の垂直同期間隔の、11 から 20 の範囲内の 2 つのラインに格納される。

コントロール トラックは、テープ上の特別なトラックに、1 フレームあたり 1 回記録される信号である。ヘッドおよびドライブ サーボのメカニズムでは、これを使用してすべてをロックする。また、タイムコード機能を備えていないマシン上でカウンタを操作するのに使用したり、場合によってはタイムコード リーダーが装備されているマシン上でも使用できる。

ED_TCR_LAST_VALUE は、外部デバイスに対してほかのタイムコード要求を送ることがアプリケーションで望まれない場合、タイムコード通知を実装するときに使用される。この方法はマルチスレッドに関する問題があるので、フレームの正確さが要求されるアプリケーションでは、その使用は推奨されない。

参照

IAMTimecodeReader::SetTCRMode

IAMTimecodeReader::GetTimecode

IAMTimecodeReader インターフェイス

最新のタイムコード、ユーザービット、およびストリーム内で有効なフラグ値を取得する。

構文

HRESULT GetTimecode(
  PTIMECODE_SAMPLE pTimecodeSample
  );

パラメータ

pTimecodeSample
[out] TIMECODE_SAMPLE タイムコード構造体へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

このメソッドを使用すると、タイムコードを監視し、重複と不連続性を解析できる。タイムコードを提供するソース フィルタ、および場合によってはダウンストリーム フィルタでは、不連続性やエラーを解析することが望まれる。これは、最新のタイムコードを取得するために、すべてのサンプルを参照する必要があるためである。

アプリケーションでは、タイムコード情報に未定義のビットを設定して、同期情報を格納したり、元のフィルム情報とオーディオ テープ情報をエンコードできる。このような未定義ビット、つまりユーザービットは、このメソッドを呼び出すことによって取得される。

IAMTimecodeReader::get_VITCLine

IAMTimecodeReader インターフェイス

タイムコード リーダーがタイムコードを読み取るときに使用する VITC (Vertical Interval Timecode) ラインを取得する。

構文

HRESULT get_VITCLine(
  long *pLine );

パラメータ

pLine
[out] タイムコード情報を格納している、11 から 20 の範囲内のラインへのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

ハイ ビットは複数のラインが使用されていることを表し、ライン番号に対して呼び出しが連続して行われる。

参照

IAMTimecodeReader::put_VITCLine

IAMTimecodeReader::put_VITCLine

IAMTimecodeReader インターフェイス

タイムコード リーダーがタイムコードを読み取るときに使用する VITC (Vertical Interval Timecode) ラインを指定する。

構文

HRESULT put_VITCLine(
  long Line );

パラメータ

Line
[in] タイムコード情報を格納する、11 から 20 の範囲内のライン。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

IAMTimecodeReader::SetTCRMode メソッドで VITC モードが指定されている場合は、タイムコード情報を含むラインを指定する必要がある。特定の複数のライン上の VITC を読み取るには、目的のラインごとに put_VITCLine を連続して呼び出す。

ハイ ビットをセットしてラインのリストに追加することによって、リーダーが複数のラインを調べる。

参照

IAMTimecodeReader::get_VITCLine

IAMTimecodeReader::SetTCRMode

IAMTimecodeReader インターフェイス

タイムコード リーダーのプロパティを設定する。

構文

HRESULT SetTCRMode(
  long Param,
  long Value
  );

パラメータ

Param
[in] 設定するプロパティ。ED_TCR_SOURCE または ED_TCR_NOTIFY_ENABLE を設定する。
Value
[in] 指定のプロパティの値。Param に ED_TCR_NOTIFY_ENABLE が指定されている場合は、OATRUE または OAFALSE を指定する。Param に ED_TCR_SOURCE が指定されている場合は、次のいずれかを指定する。
ED_TCR_CT | コントロール トラック
ED_TCR_LTC | LTC (Liner Timecode)
ED_TCR_VITC | VITC (Vertical Interval Timecode)
ED_TCR_LAST_VALUE | 前回の読み取り値を返す

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

LTC は、アナログ オーディオ トラック上で NRZ バイフェーズ マーク エンコード信号として記録される。各タイムコード フレームは、時間幅内の 1 つのビデオ フレーム タイムである。

VITC は、通常、ビデオ信号の垂直同期間隔の、10 から 20 の範囲内の 2 つのラインに格納される。

コントロール トラックは、テープ上の特別なトラックに、1 フレームあたり 1 回記録される信号である。ヘッドおよびドライブ サーボのメカニズムでは、これを使用してすべてをロックする。また、タイムコード機能を備えていないマシン上でカウンタを操作するのに使用したり、場合によってはタイムコード リーダーが装備されているマシン上でも使用できる。

ED_TCR_LAST_VALUE は、外部デバイスに対してほかのタイムコード要求を送ることがアプリケーションで望まれない場合に、タイムコード通知を実装するときに使用される。この方法はマルチスレッドに関する問題があるので、フレームの正確さが要求されるアプリケーションでは、その使用は推奨されない。

参照

IAMTimecodeReader::GetTCRMode


IAMTuner インターフェイス

IAMTuner インターフェイスは IAMTVTuner の基底クラスで、IAMTVTuner は IAMTuner のすべてのメソッドを継承する。Microsoft® DirectShow® を使用して TV チューナーを制御する方法の詳細については、IAMTVTuner のドキュメントを参照すること。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMTuner メソッド | 説明
put_Channel | TV チャンネルを設定する。
get_Channel | チューナーに設定されている TV チャンネルを取得する。
ChannelMinMax | 使用可能なチャンネルの最大値と最小値を取得する。
put_CountryCode | 国コードを設定して、使用する周波数を確立する。
get_CountryCode | 国コードを取得する。
put_TuningSpace | チャンネル周波数変換の地域マッピングの格納インデックスを設定する。
get_TuningSpace | 地域の最適チューニングの格納インデックスを取得する。
Logon | ユーザーをシステムにログオンさせる。
Logout | ユーザーをシステムからログオフさせる。
SignalPresent | 指定されたチャンネルの信号の強度を取得する。
put_Mode | 多機能チューナーを指定されたモードに設定する。
get_Mode | 多機能チューナーの現在のモードを取得する。
GetAvailableModes | そのチューナーでサポートされているモードを取得する。
RegisterNotificationCallBack | IAMTunerNotification インターフェイスを実装するオブジェクトが、チューナーの状態が変化したときにイベント通知を受け取ることができるようにする。
UnRegisterNotificationCallBack | イベント通知対象のオブジェクトの登録を削除する｡

IAMTuner::ChannelMinMax

IAMTuner インターフェイス

使用可能なチャンネルの最大値と最小値を取得する。

構文

HRESULT ChannelMinMax(
    long *lChannelMin,
    long *lChannelMax
);

パラメータ

lChannelMin
[out] 最小チャンネルを受け取る変数へのポインタ。
lChannelMax
[out] 最大チャンネルを受け取る変数へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

参照

国際アナログ テレビのチューニング

IAMTuner::get_Channel

IAMTuner インターフェイス

チューナーに設定されている TV チャンネルを取得する。

構文

HRESULT get_Channel (
    long *plChannel,
    long *plVideoSubChannel,
    long *plAudioSubChannel
);

パラメータ

plChannel
[out] チャンネルを受け取る変数へのポインタ。周波数については、「国際アナログ テレビのチューニング」を参照すること。
plVideoSubChannel
[out] 定義済みのビデオ サブチャンネル値を受け取る変数へのポインタ。AMTUNER_SUBCHAN_NO_TUNE はチューニングなしを示し、AMTUNER_SUBCHAN_DEFAULT はデフォルトのサブチャンネルを示す。
plAudioSubChannel
[out] 定義済みのオーディオ サブチャンネルを受け取る変数へのポインタ。AMTUNER_SUBCHAN_NO_TUNE はチューニングなしを示し、AMTUNER_SUBCHAN_DEFAULT はデフォルトのサブチャンネルを示す。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

IAMTuner::get_CountryCode

IAMTuner インターフェイス

現在のチャンネルと周波数のマッピングを確立している国コードを取得する。

構文

HRESULT get_CountryCode(
    long *plCountryCode
);

パラメータ

plCountryCode
[out] 現在 TV チューナー フィルタで使用されている国コードを受け取る変数へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

put_CountryCode メソッドによって、使用するチャンネルと周波数のマッピング テーブルが決定される。これによって、指定された国の基本周波数が確立される。特定の地域の正確な周波数を決定する場合は、IAMTVTuner::AutoTune メソッドを使用する。

別の国のソースからブロードキャスト ビデオを受信する場合は、国コードをオーバーライドする。国コードのリストについては、「国際アナログ テレビのチューニング」を参照すること。

IAMTuner::get_Mode

IAMTuner インターフェイス

多機能チューナーの現在のモードを取得する。

構文

HRESULT get_Mode(
    AMTunerModeType *plMode
);

パラメータ

plMode
[out] 現在のモード設定を示すフラグを受け取る変数へのポインタ。取得できる値は、AMTunerModeType 列挙型で定義される。

戻り値

HRESULT 値を返す。

IAMTuner::get_TuningSpace

IAMTuner インターフェイス

チューニング空間を取得する。

構文

HRESULT get_TuningSpace(
    long *plTuningSpace
);

パラメータ

*plTuningSpace
[out] 現在のチューニング空間を受け取る変数へのポインタ。

戻り値

HRESULT 値を返す。

注意

アプリケーションはこのメソッドで取得した値を定義する。この値は、put_TuningSpace を呼び出して設定する。

IAMTuner::GetAvailableModes

IAMTuner インターフェイス

チューナーでサポートされているモードを取得する。

構文

HRESULT GetAvailableModes(
    long *plModes
);

パラメータ

plModes
[out] AMTunerModeType 列挙型で指定されている値の組み合わせを受け取る変数へのポインタ。

戻り値

HRESULT 値を返す。

IAMTuner::Logon

IAMTuner インターフェイス

ユーザーをシステムにログオンさせる。

構文

HRESULT Logon(
    HANDLE hCurrentUser
);

パラメータ

hCurrentUser
[in] 現在のユーザーを識別するアプリケーション定義のデータ構造体へのハンドル。

戻り値

HRESULT 値を返す。

注意

Logon および Logout を使用すると、ユーザー アクセスの選択を実現できる。

IAMTuner::Logout

IAMTuner インターフェイス

現在のユーザーをログアウトさせる。

構文

HRESULT Logout(void);

戻り値

HRESULT 値を返す。

IAMTuner::put_Channel

IAMTuner インターフェイス

TV チャンネルを設定する。

構文

HRESULT put_Channel(
    long lChannel,
    long lVideoSubChannel,
    long lAudioSubChannel
);

パラメータ

lChannel
[in] TV チャンネルの番号。
lVideoSubChannel
定義済みのビデオ サブチャンネル値。AMTUNER_SUBCHAN_NO_TUNE はチューニングなしを示し、AMTUNER_SUBCHAN_DEFAULT はデフォルトのサブチャンネルを示す。衛星放送の場合にのみ有効である。
lAudioSubChannel
定義済みのオーディオ サブチャンネル値。AMTUNER_SUBCHAN_NO_TUNE はチューニングなしを示し、AMTUNER_SUBCHAN_DEFAULT はデフォルトのサブチャンネルを示す。衛星放送の場合にのみ有効である。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

このメソッドは、TV チャンネルを TV 周波数に変換する、チャンネル周波数変換関数の呼び出しを処理する。チャンネルに対する周波数のリストについては、「国際アナログ テレビのチューニング」を参照すること。

IAMTuner::put_CountryCode

IAMTuner インターフェイス

国コードを設定して、使用する周波数を確立する。

構文

HRESULT put_CountryCode(
    long lCountryCode
);

パラメータ

lCountryCode
[in] 国コードを示す値。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

このメソッドによって、指定された国の基本周波数が確立される。指定された国に関して以前にキャッシュされた設定がない場合、特定の地域の正確な周波数を決定するには、IAMTVTuner::AutoTune メソッドを使用する。

チャンネルには各国で異なる周波数がマップされているので、付録の「国際アナログ テレビのチューニング」で世界各地のマッピング テーブルを提供している。この付録から新しい値を選択し、put_CountryCode メソッドのパラメータとして渡して、既存の国コードをオーバーライドする。これは、ほかの国のソースからブロードキャスト ビデオを受信する場合に便利である。

IAMTuner::put_Mode

IAMTuner インターフェイス

指定されたモードを多機能チューナーに設定する。

構文

HRESULT put_Mode(
    AMTunerModeType lMode
);

パラメータ

lMode
[in] 切り替え先のモードを示すフラグ。指定できる値は、AMTunerModeType 列挙型で定義される。

また、カードでデジタル TV がサポートされている場合には、モードをデジタル TV に指定できる。これを行うには、AMTUNER_MODE_DTV を値 0x0010 で定義する。

戻り値

HRESULT 値を返す。

IAMTuner::put_TuningSpace

IAMTuner インターフェイス

チャンネルと周波数の地域マッピングの格納インデックスを設定する。

構文

HRESULT put_TuningSpace(
    long lTuningSpace
);

パラメータ

lTuningSpace
[in] 現在のロケールを示す値。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

TV チューナーをポータブル システムに搭載する場合、使用可能なチャンネルとその実際の周波数を処理するロケール固有のマッピングを維持する必要がある。各ロケール用に異なる lTuningSpace 値を指定することで、地域間を移動する場合にチャンネルと周波数のマッピングを切り替える手段が提供される。

IAMTuner::RegisterNotificationCallBack

IAMTuner インターフェイス

チューナーの状態が変化したときに、IAMTunerNotification インターフェイスを実装するオブジェクトがイベント通知を受け取ることができるようにする。

構文

HRESULT RegisterNotificationCallBack(
    IAMTunerNotification *pNotify
    long lEvents
);

パラメータ

pNotify
[in] チューナーのイベント通知を受け取るオブジェクトの IAMTunerNotification インターフェイスへのポインタ。
lEvents
[in] イベントが発生したことを示すフラグ。現在定義されている値は、AMTUNER_EVENT_CHANGED だけである。

戻り値

HRESULT 値を返す。

IAMTuner::SignalPresent

IAMTuner インターフェイス

指定されたチャンネルの信号の強度を取得する。

構文

HRESULT SignalPresent(
    long *plSignalStrength
);

パラメータ

plSignalStrength
[out] 現在のチャンネルで信号が存在するかどうかを示す値を受け取る変数へのポインタ。次のいずれかの値を返す。
AMTUNER_HASNOSIGNALSTRENGTH | -1
AMTUNER_NOSIGNAL | 0
AMTUNER_SIGNALPRESENT | 1

値 AMTUNER_HASNOSIGNALSTRENGTH は、この時点では信号強度を確認できないことを意味する。

戻り値

HRESULT 値を返す。

IAMTuner::UnRegisterNotificationCallBack

IAMTuner インターフェイス

イベント通知対象のオブジェクトの登録を削除する。

構文

HRESULT UnRegisterNotificationCallBack(
    IAMTunerNotification *pNotify
);

パラメータ

pNotify
[in] RegisterNotificationCallBack を以前に呼び出したときに指定した IAMTunerNotification インターフェイスへのポインタ。

戻り値

HRESULT 値を返す。


IAMTunerNotification インターフェイス

テレビジョン信号のキャプチャまたは表示を行うアプリケーションで IAMTunerNotification インターフェイスを実装すると、IAMTuner::RegisterNotificationCallBack を介して呼び出された TV チューナー フィルタからのイベント通知を受け取ることができる。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMTunerNotification メソッド | 説明
OnEvent | TV チューナー カードからのイベントを処理する。

IAMTunerNotification::OnEvent

IAMTunerNotification インターフェイス

TV チューナー カードからのイベントを処理する。

構文

HRESULT OnEvent(
    AMTunerEventType Event
);

パラメータ

Event
[in] イベントのタイプを識別するフラグ。現在定義されている値は、AMTUNER_EVENT_CHANGED だけである。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。


IAMTVAudio インターフェイス

IAMTVAudio インターフェイスは、TV オーディオ フィルタで実装される。このインターフェイスによって、アプリケーションはセカンダリ オーディオ プログラム (SAP) などのテレビジョン ソースからのオーディオに特有の設定、およびステレオまたはモノラルの選択を制御できる。これらの制御は、一般にシステム オーディオ ミキサーの外部のデバイスにある。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMTVAudio メソッド | 説明
GetHardwareSupportedTVAudioModes | ハードウェアで使用可能なフォーマットのビットマスクを取得する。
GetAvailableTVAudioModes | 使用可能なモードのビットマスクを取得する。
get_TVAudioMode | 現在の TV オーディオ モードを取得する。
put_TVAudioMode | 現在の TV オーディオ モードを設定する。

IAMTVAudio::GetHardwareSupportedTVAudioModes

IAMTVAudio インターフェイス

ハードウェアで使用可能なフォーマットのビットマスクを取得する。

構文

HRESULT GetHardwareSupportedTVAudioModes(
  long *plModes
  );

パラメータ

plModes
[out] オーディオ モードを識別する TVAudioMode 列挙型へのポインタ。

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
S_OK または NOERROR | 成功。

IAMTVAudio::GetAvailableTVAudioModes

IAMTVAudio インターフェイス

使用可能なモードのビットマスクを取得する。

構文

HRESULT GetAvailableTVAudioModes(
  long *plModes
);

パラメータ

plModes
[out] オーディオ モードを識別する TVAudioMode 列挙型へのポインタ。

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。

E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
S_OK または NOERROR | 成功。

IAMTVAudio::get_TVAudioMode

IAMTVAudio インターフェイス

現在の TV オーディオ モードを取得する。

構文

HRESULT get_TVAudioMode(
  long *plModes
);

パラメータ

plModes
[out] オーディオ モードを識別する TVAudioMode 列挙型へのポインタ。

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。

E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
S_OK または NOERROR | 成功。

IAMTVAudio::put_TVAudioMode

IAMTVAudio インターフェイス

現在の TV オーディオ モードを設定する。

構文

HRESULT put_TVAudioMode(
  long plModes
);

パラメータ

plModes
[in] オーディオ モードを識別する TVAudioMode 列挙型。

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。

E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
S_OK または NOERROR | 成功。


IAMTVAudioNotification インターフェイス

TV オーディオ フィルタを使用するアプリケーションは、IAMTVAudioNotification インターフェイスを実装して、IAMTuner::RegisterNotificationCallBack を介して TV チューナー カードからのイベント通知を受け取ることができる。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMTVAudioNotification メソッド | 説明
OnEvent | IAMTVAudio インターフェイスで制御される TV チューナー カードからのイベントを処理する。

IAMTVAudioNotification::OnEvent

IAMTVAudioNotification インターフェイス

IAMTVAudio インターフェイスで制御される TV チューナー カードからのイベントを処理する。

構文

HRESULT OnEvent(
    AMTVAudioEventType Event
);

パラメータ

Event
[in] イベントのタイプを識別するフラグ。現在定義されている値は、AMTVAUDIO_EVENT_CHANGED だけである。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。


IAMTVTuner インターフェイス

IAMTVTuner インターフェイスは、TV チューナー フィルタで実装される。このインターフェイスは、アプリケーションが TV チューナー デバイスを制御できるメソッドを IAMTuner から継承し、提供する。このインターフェイスは、アナログ放送テレビおよび AM/FM ラジオに対応している。

IAMTVTuner は、複数の入力ピンを持つチューナーに対応しており、複数のデバイスおよび複数の転送タイプを使用できる。

IAMTVTuner は、IAMTuner::put_Channel メソッドおよび IAMTVTuner::AutoTune メソッドを介して、TV チャンネルを特定の周波数にマップする。この 2 つのメソッドは、ハードウェア ドライバが正確な周波数を取得するようにこの変換の細部を取り扱う。TV チューナー フィルタは世界各地のチューニング範囲をサポートしている。

TV チャンネルの設定、そのチャンネルの周波数情報の取得または設定、および使用する TV チューナー カードが対応しているアナログ ビデオ規格を判別するには、アプリケーションからこのインターフェイスを使用する。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMTuner メソッド | 説明
put_Channel | TV チャンネルを設定する。
get_Channel | 現在エンコーダに設定されている TV チャンネルを取得する。
ChannelMinMax | 使用可能なチャンネルの最大値および最小値を取得する。
put_CountryCode | 国コードを設定して、使用する周波数を確立する。
get_CountryCode | 現在のチャンネルと周波数のマッピングを確立している国コードを取得する。
put_TuningSpace | チャンネルと周波数の地域マッピングの格納インデックスを設定する。
get_TuningSpace | 地域の最適チューニングの格納インデックスを取得する。
Logon | ユーザーをシステムにログオンさせる。
Logout | ユーザーをシステムからログオフさせる。
SignalPresent | 指定されたチャンネルの信号の強度を取得する。
put_Mode | 多機能チューナーの操作モードを設定する。
get_Mode | 多機能チューナーの操作モードを取得する。
GetAvailableModes | チューナーで使用可能なビデオ モードを判別する。
RegisterNotificationCallBack | IAMTunerNotification インターフェイスを実装するオブジェクトが、チューナーの状態が変化したときにイベント通知を受け取ることができるようにする。
UnRegisterNotificationCallBack | イベント通知対象のオブジェクトの登録を削除する。
IAMTVTuner メソッド | 説明
get_AvailableTVFormats | チューナーがサポートしているアナログ ビデオ TV 規格をすべて取得する。
get_TVFormat | 現在使用されているアナログ ビデオ TV 規格を取得する。
AutoTune | 目的のチャンネルの正確な周波数をスキャンする。
StoreAutoTune | すべてのチャンネルの最適チューニング情報を保存する。
get_NumInputConnections | チューナー フィルタに接続された TV ソースの番号を取得する。
put_InputType | チューナーの入力タイプ (ケーブルまたはアンテナ) を設定する。
get_InputType | 入力タイプを取得する。
put_ConnectInput | ハードウェア チューナー入力接続を設定する。
get_ConnectInput | ハードウェア チューナー入力接続を取得する。
get_VideoFrequency | 現在のビデオ周波数を取得する。
get_AudioFrequency | 現在のオーディオ周波数を取得する。

IAMTVTuner::AutoTune

IAMTVTuner インターフェイス

指定したチャンネルの周波数の正確な信号をスキャンする。

構文

HRESULT AutoTune(
    long lChannel,
    long *plFoundSignal
);

パラメータ

lChannel
[in] TV チャンネルの番号
plFoundSignal
[out] 指定したチャンネルの周波数が検出されたかどうかを示す変数へのポインタ。0 以外は検出されたことを示し、0 は検出されなかったことを示す。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

通常、TV チャンネルは、地域ごとに一意の周波数にマップされる。複数の送信機で同じチャンネルが割り当てられ、その送信機が地理的に近接していると、混信が生じる場合がある。この混信を防ぐために、各送信機でわずかな周波数オフセットが行われる。米国でのオフセット範囲は最大 +/– 26.25 キロヘルツ (kHz) である。

このメソッドは、チャンネルと周波数の変換を処理し、最も正確な周波数をスキャンする。この値は IAMTVTuner::StoreAutoTune メソッドを呼び出して保存する。チャンネルの基本周波数については、付録の「国際アナログ TV チューニング」を参照すること。

IAMTVTuner::get_AudioFrequency

IAMTVTuner インターフェイス

現在チューニングされているオーディオ周波数を取得する。

構文

HRESULT get_AudioFrequency(
    long *lFreq
);

パラメータ

lFreq
[out] オーディオ周波数へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

これは、指定したチャンネルで使用されている正確な周波数を調査できる診断メソッドである。

IAMTVTuner::get_AvailableTVFormats

IAMTVTuner インターフェイス

チューナーがサポートしているアナログ ビデオ TV 規格をすべて取得する。

構文

HRESULT get_AvailableTVFormats(
    long *lAnalogVideoStandard
);

パラメータ

lAnalogVideoStandard
[out] サポートされているアナログ ビデオ規格の組み合わせへのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

サポートされているフォーマットについては、「AnalogVideoStandard 列挙型」を参照すること。

IAMTVTuner::get_ConnectInput

IAMTVTuner インターフェイス

ハードウェア チューナー入力接続を取得する。

構文

HRESULT get_ConnectInput (
    long *plIndex
);

パラメータ

plIndex
[out] 接続を取得する入力ピンへのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

IAMTVTuner::get_InputType

IAMTVTuner インターフェイス

put_InputType で設定されている入力タイプを取得する。

構文

HRESULT get_InputType (
    long lIndex,
    TunerInputType *pInputType
);

パラメータ

lIndex
[in] 設定対象の入力ピンを指定するインデックス値。
pInputType
[out] TunerInputType 接続列挙型へのポインタ。ケーブル (TunerInputCable) またはアンテナ (TunerInputAntenna)。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

IAMTVTuner::get_NumInputConnections

IAMTVTuner インターフェイス

チューナー フィルタに接続されている TV ソースの数を取得する。

構文

HRESULT get_NumInputConnections(
    long *plNumInputConnections
);

パラメータ

plNumInputConnections
[out] チューナー フィルタに接続されている TV ソースの数へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

IAMTVTuner::get_TVFormat

IAMTVTuner インターフェイス

現在使用されているアナログ ビデオ TV 規格を取得する。

構文

HRESULT get_TVFormat(
    long *plAnalogVideoStandard
);

パラメータ

plAnalogVideoStandard
[out] 現在 TV チューナー フィルタで使用されているアナログ ビデオ規格へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

サポートされているフォーマットについては、「AnalogVideoStandard列挙型」を参照すること。

IAMTVTuner::get_VideoFrequency

IAMTVTuner インターフェイス

現在のビデオ周波数を取得する。

構文

HRESULT get_VideoFrequency(
    long *lFreq
);

パラメータ

lFreq
[out] ビデオ周波数へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

これは、指定したチャンネルで使用されている正確な周波数を調査できる診断メソッドである。

IAMTVTuner::put_ConnectInput

IAMTVTuner インターフェイス

ハードウェア チューナー入力接続を設定する。

構文

HRESULT put_ConnectInput(
    long lIndex
);

パラメータ

lIndex
[in] 接続を設定する入力ピンのインデックス値。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

IAMTVTuner::put_InputType

IAMTVTuner インターフェイス

チューナーの入力タイプ (ケーブルまたはアンテナ) を設定する。

構文

HRESULT put_InputType(
    long lIndex,
    TunerInputType InputType
);

パラメータ

lIndex
[in] 設定対象の入力ピンを指定するインデックス値。
InputType
[in] TunerInputType 列挙型で指定される接続タイプを示す値。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

IAMTVTuner::StoreAutoTune

IAMTVTuner インターフェイス

すべてのチャンネルの最適チューニング情報を保存する。

構文

HRESULT StoreAutoTune(void);

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

このメソッドで保存したチャンネルと周波数の情報をオーバーライドするには、IAMTuner::put_CountryCode メソッドで新しい国コードを設定する。国コードの一覧については、「国際アナログ TV チューニング」を参照すること。


IAMVfwCaptureDialogs インターフェイス

IAMVfwCaptureDialogs インターフェイスは、VFW キャプチャ フィルタで実装される。このインターフェイスによって、アプリケーションは、Microsoft® Video for Windows® キャプチャ ドライバで提供される 3 種類のダイアログ ボックス (ソース、フォーマット、または表示) のいずれかを表示できる。アプリケーションで、Video for Windows キャプチャ ドライバが提供するダイアログ ボックスを使用してユーザーが設定を変更できるようにする場合は、このインターフェイスを使用する。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMVfwCaptureDialogs メソッド | 説明
HasDialog | 指定されたダイアログ ボックスがドライバ内に存在するかどうかを確認する。
ShowDialog | 指定されたダイアログ ボックスを表示する。
SendDriverMessage | ドライバ固有のメッセージを送信する。

IAMVfwCaptureDialogs::HasDialog

IAMVfwCaptureDialogs インターフェイス

指定されたダイアログ ボックスがドライバ内に存在するかどうかを確認する。

構文

HRESULT HasDialog(
  int iDialog );

パラメータ

iDialog
[in] 必要なダイアログ ボックス。このダイアログ ボックスは VfwCaptureDialogs 列挙型のメンバである。

戻り値

ドライバに目的のダイアログ ボックスがある場合は S_OK を返す。それ以外の場合は S_FALSE を返す。

注意

このメソッドは、Video for Windows の videoDialog 関数を呼び出して、該当するダイアログ ボックスが存在するかどうかを照会する。

IAMVfwCaptureDialogs::SendDriverMessage

IAMVfwCaptureDialogs インターフェイス

ドライバ固有のメッセージを送信する。

構文

HRESULT SendDriverMessage(
  int iDialog,
  int uMsg,
  long dw1,
  long dw2 );

パラメータ

iDialog
[in] ドライバのダイアログ ボックスのハンドル。このダイアログ ボックスは VfwCaptureDialogs 列挙型のメンバである。
uMsg
[in] ドライバに送信するメッセージ。
dw1
[in] メッセージ データ。
dw2
[in] メッセージ データ。

戻り値

戻り値は、各ドライバ内の実装に応じて異なる。

注意

このメソッドを使用する必要はない。このメソッドを使用すると任意のプライベート メッセージをキャプチャ ドライバに送信できる。ただし、任意のメッセージに応答する動作が決められていない場合があるので、このメソッドはユーザーの責任において使用すること。

このメソッドは、Video for Windows の videoMessage 関数を呼び出して、目的のドライバ メッセージを送信する。

IAMVfwCaptureDialogs::ShowDialog

IAMVfwCaptureDialogs インターフェイス

指定されたダイアログ ボックスを表示する。

構文

HRESULT ShowDialog(
  int iDialog,
  long hwnd );

パラメータ

iDialog
[in] 表示するダイアログ ボックス。このダイアログ ボックスは VfwCaptureDialogs 列挙型のメンバである。
hwnd
[in] ダイアログ ボックスの親ウィンドウのハンドル。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

目的のドライバがストリーミング中または別のダイアログ ボックスを表示している場合は、このメソッドを使用できない。ドライバがダイアログ ボックスを表示している間は、フィルタをストリーム (停止または実行) できない。

IAMVfwCaptureDialogs::ShowDialog は、Video for Windows® の VideoDialog 関数を呼び出して、該当するダイアログ ボックスを表示する。

このメソッドを使用して VfwCaptureDialog_Format ダイアログ ボックスを表示する場合、キャプチャ フィルタがグラフで既に接続されていて、既存のグラフが新しいフォーマットを受け付けることができないと、VFW_E_CANNOT_CONNECT エラー コードが返される。このエラーが発生した場合、キャプチャ アプリケーションは、フィルタ グラフのキャプチャ フィルタのダウンストリームである部分を再構築する必要がある。


IAMVfwCompressDialogs インターフェイス

IAMVfwCompressDialogs インターフェイスは、AVI コンプレッサ フィルタで実装される。このインターフェイスによって、アプリケーションは Video for Windows CODEC の [Configure] または [About] ダイアログ ボックスを表示し、コンプレッサ状態の設定と取得を行うことができる。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMVfwCompressDialogs methods | 説明
ShowDialog | 指定されたダイアログ ボックスを表示する。
GetState | 現在使用されている VCM CODEC の現在の構成設定を取得する。
SetState | VCM CODEC の構成を設定する。
SendDriverMessage | ドライバ固有のメッセージを送信する。

IAMVfwCompressDialogs::GetState

IAMVfwCompressDialogs インターフェイス

現在使用されている VCM CODEC の現在の構成設定を取得する。

構文

HRESULT GetState(

  LPVOID pState,

  int *pcbState

パラメータ

pState
[out] VCM CODEC の状態。
pcbState
[in, out] ステート情報のサイズへのポインタ。

戻り値

戻り値は、各ドライバ内の実装に応じて異なる。

注意

このメソッドは、COM ICGetState マクロを呼び出す。

IAMVfwCompressDialogs::SendDriverMessage

IAMVfwCompressDialogs インターフェイス

ドライバ固有のメッセージを送信する。

構文

HRESULT SendDriverMessage(
  int uMsg,
  long dw1,
  long dw2 );

パラメータ

uMsg
[in] ドライバに送信するメッセージ。
dw1
[in] メッセージ データ。
dw2
[in] メッセージ データ。

戻り値

戻り値は、各ドライバ内の実装に応じて異なる。

注意

このメソッドを使用する必要はない。このメソッドを使用すると、任意のプライベート メッセージをビデオ コンプレッサ (CODEC) に送信できる。ただし、任意のメッセージに応答する動作が決められていない場合があるので、このメソッドはユーザーの責任において使用すること。

このメソッドは、Video for Windows のビデオ圧縮マネージャ (VCM) の ICSendMessage 関数を呼び出してメッセージを送信する。

IAMVfwCompressDialogs::SetState

IAMVfwCompressDialogs インターフェイス

VCM CODEC の構成を設定する。

構文

HRESULT SetState(
  LPVOID pState,
  int cbState );

パラメータ

pState
[in] VCM CODEC の状態。
cbState
[in] ステート情報のサイズ。

戻り値

戻り値は、各ドライバ内の実装に応じて異なる。

注意

このメソッドは、COM ICSetState マクロを呼び出す。このマクロは、ビデオ圧縮ドライバにコンプレッサの状態を設定するように通知する。

IAMVfwCompressDialogs::ShowDialog

IAMVfwCompressDialogs インターフェイス

指定されたダイアログ ボックスを表示する。

構文

HRESULT ShowDialog(
  int iDialog,
  long hwnd );

パラメータ

iDialog
[in] 表示するダイアログ ボックス。このダイアログ ボックスは VfwCompressDialogs 列挙型のメンバである。
hwnd
[in] ダイアログ ボックスの親ウィンドウのハンドル。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

目的のドライバがストリーミング中または別のダイアログ ボックスを表示している場合に、ダイアログ ボックスの表示を要求すると、このメソッドはエラーを返す。ドライバがダイアログ ボックスを表示している間は、フィルタをストリーム (停止または実行) できない。

IAMVfwCompressDialogs::ShowDialog は Video for Windows のビデオ圧縮マネージャ (VCM) の関数 ICConfigure、ICAbout、ICQueryConfigure、および ICQueryAbout を呼び出し、該当するダイアログ ボックスを表示するか、またはそのダイアログ ボックスが存在するかどうかを確認する。

VfwCompressDialogs 列挙型の VfwCompressDialog_QueryConfig および VfwCompressDialog_QueryAbout メンバによって、Configure ダイアログまたは About ダイアログが使用可能かどうかがわかる。この 2 つのフラグのいずれかが渡されると、フィルタはダイアログが存在する場合は S_OK を返し、存在しない場合は S_FALSE を返す。ダイアログが利用可能な場合、値 VfwCompressDialog_Config または VfwCompressDialog_About を指定して ShowDialog を呼び出し、ダイアログを表示する。


IAMVideoAccelerator インターフェイス

IAMVideoAccelerator インターフェイスによって、ビデオ デコーダ フィルタはビデオ アクセラレータ機能にアクセスできる。オーバーレイ ミキサー フィルタの入力ピンは、このインターフェイスをサポートしている。ビデオ デコーダ フィルタがこのインターフェイスでメソッドを呼び出す場合、デコーダの出力ピンで IAMVideoAcceleratorNotify インターフェイスをサポートしている必要がある。アプリケーションが、このインターフェイスでメソッドを呼び出す必要はない。

注 : このインターフェイスは Microsoft® Windows® 2000 で使用できる。

ビデオ デコーダ フィルタの接続に関するイベントの順序を次に示す。

  1. フィルタ グラフ マネージャが、ビデオ デコーダ フィルタの出力ピンで IPin::Connect メソッドを呼び出す。
  2. ビデオ デコーダは、オーバーレイ ミキサーの入力ピンで IAMVideoAccelerator::GetVideoAcceleratorGUIDs メソッドを呼び出して、ビデオ アクセラレータの GUID のリストを取得できる。これは、オーバーレイ ミキサーが受け付けるビデオ アクセラレータ フォーマットを示す。
  3. ビデオ デコーダは、指定されたビデオ アクセラレータの GUID に関して IAMVideoAccelerator::GetUncompFormatsSupported を呼び出し、提示する適切なピクセル フォーマットを確認する。
  4. ビデオ デコーダは、オーバーレイ ミキサーの入力ピンで IPin::ReceiveConnection メソッドを呼び出し、メディア タイプのサブタイプとしてビデオ アクセラレータの GUID を指定する。この呼び出し内で、オーバーレイ ミキサーは、デコーダ フィルタの出力ピンで次のメソッドを呼び出す。
    • IAMVideoAcceleratorNotify::GetUncompSurfacesInfo を呼び出して、作成する出力サーフェスの数を確認する。デコーダは、割り当てるサーフェスの最小数と最大数、および必要なピクセル フォーマット情報を返す。
    • IAMVideoAcceleratorNotify::SetUncompSurfacesInfo を呼び出して、実際に割り当てられているサーフェスの数をビデオ デコーダに通知する。
    • IAMVideoAcceleratorNotify::GetCreateVideoAcceleratorData を呼び出して、ドライバに渡すビデオ アクセラレータ作成データを取得して、その内部ビデオ アクセラレータ オブジェクトを作成する。
  5. ビデオ デコーダは IAMVideoAccelerator::GetCompBufferInfo を呼び出して、前に指定されたビデオ アクセラレータの GUID に関連付けられている圧縮済みデータバッファに関する情報を取得する。

動的なフォーマットの変更をサポートするために、フィルタが接続され、実行されている間に次の手順も実行できる。

操作中に、ビデオ デコーダが次の手順を実行する。

  1. 圧縮されていない各データバッファに関して、IAMVideoAccelerator::BeginFrame を呼び出して出力フレームの処理を開始する。
  2. 圧縮されていないデータをビデオ アクセラレータに送るために、デコーダが次のメソッドを呼び出す。
    • IAMVideoAccelerator::GetBuffer を呼び出して、バッファをロックし、バッファへのアクセスを取得する。
    • Execute を呼び出して、一連の圧縮済みバッファ内のデータを処理する。
    • IAMVideoAccelerator::ReleaseBuffer を呼び出して、バッファのロックを解除する。
    • IAMVideoAccelerator::QueryRenderStatus を呼び出して、バッファに対する書き込みまたは読み取りが可能かどうかを照会する。
  3. フレーム処理を終了するために、IAMVideoAccelerator::EndFrame を呼び出す。
  4. フレームを表示するために、IAMVideoAccelerator::DisplayFrame を呼び出す。

GetBuffer メソッドでバッファをロックする前に、ビデオ デコーダは、そのバッファを更新する任意の圧縮解除操作が完了したかどうかを確認する必要がある。DisplayFrame についても同様に、ビデオ デコーダがそのフレームを更新するすべての圧縮解除操作が完了しているかどうかを確認する必要がある。

要件

Videoacc.h が必要である。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMVideoAccelerator methods | 説明
GetVideoAcceleratorGUIDs | 受け付けられるビデオ アクセラレータ フォーマットの GUID のリストを取得する。
GetUncompFormatsSupported | 指定されたビデオ アクセラレータ フォーマットのレンダリングに使用できるピクセル フォーマットのリストを取得する。
GetInternalMemInfo | ビデオ アクセラレータの GUID、圧縮されていないデータのサイズ、およびピクセル フォーマットに基づいて、圧縮されていないデータのメモリ要件に関する情報を取得する。
GetCompBufferInfo | 圧縮済みバッファの情報を取得する。
GetInternalCompBufferInfo | ピンが接続された後に呼び出され、接続するタイプが指定されていると、圧縮済みバッファの情報を取得する。
BeginFrame | フレーム処理を開始する。
EndFrame | フレーム処理を終了し、各種のデータをビデオ アクセラレータ ドライバに渡す。
GetBuffer | 指定されたインデックスおよびタイプの圧縮済みバッファを取得する。
ReleaseBuffer | 処理後に圧縮済みバッファを解放する。
Execute | 圧縮解除操作を実行する。
QueryRenderStatus | 一連のマクロ ブロックのデコード状態を照会する。
DisplayFrame | デコード済みフレームを表示する。

IAMVideoAccelerator::GetVideoAcceleratorGUIDs

IAMVideoAccelerator

受け付けられるビデオ アクセラレータ フォーマットの GUID のリストを取得する。

構文

HRESULT GetVideoAcceleratorGUID(
  LPDWORD pdwNumGuidsSupported,
  LPGUID pGuidsSupported
);

パラメータ

pdwNumGuidsSupported
[in] [out] pGuidsSupported が NULL の場合、pdwNumGuidsSupported はサポートされているビデオ アクセラレータ フォーマットの GUID の数を返す。NULL ではない場合、このパラメータは pGuidsSupported に返される GUID の最大数へのポインタとなる。サポートされているビデオ アクセラレータ フォーマットがこの数よりも少ない場合、pdwNumGuidsSupported は実際に返された GUID の数に更新される。
pGuidsSupported
[in] [out] このパラメータが NULL ではない場合、サポートされている GUID がこの配列に返される。その配列のサイズは、バイト単位で少なくとも sizeof(GUID) * (*pdwNumGuidsSupported) である。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。

E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_POINTER | Null ポインタ引数。
S_OK | 成功。

IAMVideoAccelerator::GetUncompFormatsSupported

IAMVideoAccelerator

指定されたビデオ アクセラレータ フォーマットのレンダリングに使用できるピクセル フォーマットのリストを取得する。

構文

HRESULT GetUncompFormatsSupported(
    const GUID *pGuid,
    LPDWORD pdwNumFormatsSupported,
    LPDDPIXELFORMAT pFormatsSupported
);

パラメータ

pGuid
[in] ビデオ アクセラレータの GUID へのポインタ。
pdwNumFormatsSupported
[in] [out] pFormatsSupported が NULL の場合、pdwNumFormatsSupported には、pGuid で定義されているビデオ アクセラレータ フォーマットから変換可能なピクセル フォーマットの数が返される。NULL ではない場合、このパラメータは pFormatsSupported に返されるピクセル フォーマットの数である。メソッドが戻ると、このパラメータは実際に返されたピクセル フォーマットの数になる。
pFormatsSupported
[in] [out] DDPIXELFORMAT 構造体へのポインタ。このパラメータが NULL ではない場合、最大 *pdwNumFormatsSupported 個のピクセル フォーマットがこの配列にコピーされる。バッファのサイズは、少なくとも *pdwNumFormatsSupported * sizeof(DDPIXELFORMAT) である。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。

E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_POINTER | Null ポインタ引数。
S_OK | 成功。

IAMVideoAccelerator::GetInternalMemInfo

IAMVideoAccelerator

ビデオ アクセラレータの GUID、圧縮されていないデータのサイズ、およびピクセル フォーマットに基づいて、圧縮されていないデータのメモリ要件に関する情報を取得する。

構文

HRESULT GetInternalMemInfo(
    const GUID *pGuid,
    const AMVAUncompDataInfo *pamvaUncompDataInfo,
    LPAMVAInternalMemInfo pamvaInternalMemInfo
);

パラメータ

pGuid
[in] ビデオ アクセラレータの GUID へのポインタ。
pamvaUncompDataInfo
[in] 圧縮されていないデータのサイズとピクセル フォーマットの情報を含む AMVAUncompDataInfo 構造体へのポインタ。
pamvaInternalMemInfo
[in] [out] スクラッチ メモリ要件に関する情報を含む AMVAInternalMemInfo 構造体へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。

E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_POINTER | Null ポインタ引数。
S_OK | 成功。

IAMVideoAccelerator::GetCompBufferInfo

IAMVideoAccelerator

圧縮済みバッファ情報を取得する。

構文

HRESULT GetCompBufferInfo(
    const GUID *pGuid,
    const AMVAUncompDataInfo *pamvaUncompDataInfo,
    LPDWORD pdwNumTypesCompBuffers,
    LPAMVACompBufferInfo pamvaCompBufferInfo
);

パラメータ

pGuid
[in] ビデオ アクセラレータ フォーマットの GUID へのポインタ。
pamvaUncompDataInfo
[in] 圧縮されていないデータのサイズおよびピクセル フォーマットの情報を含む AMVAUncompDataInfo 構造体へのポインタ。
pdwNumTypesCompBuffers
[in] [out] DWORD 型 の変数へのポインタ。pamvaCompBufferInfo が NULL ではない場合、このパラメータは、圧縮されていないバッファ タイプの数を取得する。NULL の場合、入力であれば、このパラメータは返される圧縮済みバッファ タイプの最大数を指定し、出力であれば、圧縮済みバッファ タイプの実際の数を取得する。
pamvaCompBufferInfo
[out] NULL 以外の場合、最大pdwNumTypesCompBuffers 個の AMVACompBufferInfo 構造体が返される。このデータには、サーフェスの作成に使用される幅、高さ、ピクセル フォーマット、DirectDraw 機能、およびサーフェスが占有するサイズ (バイト単位) が含まれる。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。

E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_POINTER | Null ポインタ引数。
S_OK | 成功。

注意

このメソッドは、DirectDraw を使用して、必要なタイプのビデオ アクセラレータ サーフェスを作成するために必要な情報を返す。ビデオ アクセラレータ ドライバで、複数の圧縮済みバッファ タイプ (たとえば、ビデオ アクセラレータ データと逆離散コサイン変換 [IDCT] データ) がサポートされている場合がある。

IAMVideoAccelerator::GetInternalCompBufferInfo

IAMVideoAccelerator

ピンが接続された後に呼び出され、接続するタイプが指定されていると、圧縮済みバッファの情報を取得する。

構文

HRESULT GetInternalCompBufferInfo(
    LPDWORD pdwNumTypesCompBuffers,
    LPAMVACompBufferInfo pamvaCompBufferInfo
);

パラメータ

pdwNumTypesCompBuffers
[in] [out] DWORD 型の変数へのポインタ。pamvaCompBufferInfo が NULL ではない場合、このパラメータは圧縮されていないバッファ タイプの数を取得する。NULL の場合、入力であれば、このパラメータは返される圧縮済みバッファ タイプの最大数を指定し、出力であれば、圧縮済みバッファ タイプの実際の数を取得する。
pamvaCompBufferInfo
[out] NULL 以外の場合、最大 pdwNumTypesCompBuffers 個の AMVACompBufferInfo 構造体が返される。このデータには、サーフェスの作成に使用される幅、高さ、ピクセル フォーマット、DirectDraw 機能、およびサーフェスが占有するサイズ (バイト単位) が含まれる。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。

E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_POINTER | Null ポインタ引数。
S_OK | 成功。

注意

ビデオ アクセラレータ ドライバで、複数の圧縮済みバッファ タイプ (たとえば、ビデオ アクセラレータ データと逆離散コサイン変換 [IDCT] データ) がサポートされている場合がある。

IAMVideoAccelerator::BeginFrame

IAMVideoAccelerator

フレーム処理を開始する。

構文

HRESULT BeginFrame(
    const AMVABeginFrameInfo *pamvaBeginFrameInfo
    );

パラメータ

pamvaBeginFrameInfo
[in] フレーム処理の開始に必要な情報を含む AMVABeginFrameInfo 構造体へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。

E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_POINTER | Null ポインタ引数。
S_OK | 成功。

注意

このメソッドは、ピンが接続された後にのみ呼び出すことができる。

AMVABeginFrameInfo 構造体には、転送先バッファのインデックスが含まれる。有効なインデックス値は、0 から dwActualUncompSurfacesAllocated–1 の範囲である。dwActualUncompSurfacesAllocated の値は IAMVideoAcceleratorNotify::SetUncompSurfacesInfo を呼び出して取得する。

使用されるフレーム メモリがこのフレーム インデックスで最後に使用されたメモリと異なる場合があるので、デコーダがそのフレームの初期コンテンツに関する引き継ぎは行わないようにする。

空いているフレーム バッファがないと、このメソッドの呼び出しは処理中の操作をブロックする場合がある。

IAMVideoAccelerator::EndFrame

IAMVideoAccelerator

フレーム処理を終了し、各種のデータをビデオ アクセラレータ ドライバに渡す。

構文

HRESULT EndFrame(
    const AMVAEndFrameInfo *pEndFrameInfo
);

パラメータ

pEndFrameInfo
[in] ビデオ アクセラレータ ドライバに渡す各種のデータが含まれる AMVAEndFrameInfo 構造体へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。

E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_POINTER | Null ポインタ引数。
S_OK | 成功。

IAMVideoAccelerator::GetBuffer

IAMVideoAccelerator

指定されたインデックスおよびタイプの圧縮済みバッファを取得する。

構文

HRESULT GetBuffer(
    DWORD dwTypeIndex,
    DWORD dwBufferIndex,
    BOOL bReadOnly,
    LPVOID *ppBuffer,
    LONG *lpStride
);

パラメータ

dwTypeIndex
[in] ビデオ アクセラレータ ドライバでサポートされているサーフェス タイプへの 0 を基準とするインデックス、または 0xFFFFFFFF。「注意」を参照すること。
dwBufferIndex
[in] タイプ内のバッファ インデックス。有効範囲は、0 から AMVACompBufferInfo 構造体の dwNumCompBuffers メンバの値までである。
bReadOnly
[in] バッファが更新されるかどうかを示すブール値。TRUE の場合、バッファは更新されず、ビジーな参照フレームにアクセスできる。
ppBuffer
[out] 圧縮済みデータが格納されるバッファへのポインタ。このバッファのサイズは、GetInternalCompBufferInfo メソッドから dwSurfaceTypeIndex エントリに返される AMVACompBufferInfo 構造体の dwBytesToAllocate メンバによって確定される。
lpStride
[out] この圧縮タイプと互換性のあるストライド。通常、このストライドは、AMVACompBufferInfo 構造体の dwWidthToCreate メンバと等しい。出力ディスプレイ バッファまたはその他の圧縮されていないタイプについては、dwWidthToCreate と等しくない場合もあることに注意する。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。

E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_POINTER | Null ポインタ引数。
S_OK | 成功。

注意

このメソッドは、単一のバッファをロックし、バッファへのアクセスを取得する。バッファはタイプとそのタイプ内のインデックスによって識別される。IAMVideoAccelerator::GetInternalCompBufferInfo メソッドは pdwNumTypesCompBuffers パラメータにタイプ数を返す。これによって dwTypeIndex の有効範囲が定義される。各タイプに対して、AMVACompBufferInfo 構造体の dwNumCompBuffers メンバはバッファの数を与える。これによって dwBufferIndex の有効範囲が定義される。dwTypeIndex と dwBufferIndex には両方とも 0 を基準とするオフセットを指定することに注意すること。

また、タイプ インデックス 0xFFFFFFFF を使用して出力バッファへのポインタを取得する方法もある。現在、これは BeginFrame の呼び出しと EndFrame の呼び出しの間でのみ有効である。この場合、バッファ インデックスは、最後の BeginFrame 呼び出しに渡された AMVABeginFrameInfo 構造体の dwDestSurfaceIndex メンバと等しい必要がある。

フィルタのピンが接続されていないと、このメソッドは失敗する。

圧縮済みバッファがすべて解放されるまで、このスレッドが Win16 ロックまたは DirectDraw ロックを保持することがある。

IAMVideoAccelerator::ReleaseBuffer

IAMVideoAccelerator

処理後に圧縮済みバッファを解放する。

構文

HRESULT ReleaseBuffer(
    DWORD dwTypeIndex,
    DWORD dwBufferIndex
);

パラメータ

dwTypeIndex
[in] ビデオ アクセラレータ ドライバでサポートされているサーフェス タイプへの 0 を基準とするインデックス、または 0xFFFFFFFF。
dwBufferIndex
[in] タイプ内のバッファ インデックス。有効範囲は、0 からAMVACompBufferInfo 構造体の dwNumCompBuffers メンバの値までである。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。

E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_POINTER | Null ポインタ引数。
S_OK | 成功。

注意

このメソッドは、ピンの接続後に呼び出した場合にのみ有効である。このメソッドを呼び出すと、単一のバッファのロックが解除される。ビデオ デコーダは、バッファがこれ以上必要ない場合に、Execute が呼び出された後にこのメソッドを呼び出す。この呼び出しの後、バッファ ポインタは無効になることに注意すること。

IAMVideoAccelerator::Execute

IAMVideoAccelerator

圧縮解除操作を実行する。

構文

HRESULT Execute(
    DWORD dwFunction,
    LPVOID lpPrivateInputData,
    DWORD cbPrivateInputData,
    LPVOID lpPrivateOutputData,
    DWORD cbPrivateOutputData,
    DWORD dwNumBuffers,
    const AMVABUFFERINFO *pamvaBufferInfo
);

パラメータ

dwFunction
[in] 関数番号。引数がデフォルトであるか、または指定しない場合は、ゼロになる。
lpPrivateInputData
[in] ドライバに渡されるプライベート入力データへのポインタ。
cbPrivateInputData
[in] プライベート入力データの長さ。
lpPrivateOutputData
[in] ドライバに渡されるプライベート出力データへのポインタ。
cbPrivateOutputData
[in] プライベート データ バッファの長さ。
dwNumBuffers
[in] AMVABUFFERINFO 構造体の数
pamvaBufferInfo
[in] 渡される AMVABUFFERINFO 構造体のリストへのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。

E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_POINTER | Null ポインタ引数。
S_OK | 成功。

注意

このメソッドは、ピンの接続後に呼び出した場合にのみ有効である。

関連付けられているバッファのリストは、関数番号 (デフォルトは 0) および圧縮解除操作を説明する必要なプライベート データと共に渡される。たとえば、圧縮が解除された参照フレーム情報はバッファ リストに渡される。バッファ リストの順序は重要で、実行される特定の圧縮解除操作によって定義される。

プライベート データはドライバに渡すこともドライバから受け取ることもできる。

IAMVideoAccelerator::QueryRenderStatus

IAMVideoAccelerator

一連のマクロ ブロックのデコード状態を照会する。

構文

HRESULT QueryRenderStatus(
    DWORD dwTypeIndex,
    DWORD dwBufferIndex,
    DWORD dwFlags
);

パラメータ

dwTypeIndex
[in] テストされるバッファのタイプ インデックス。
dwBufferIndex
[in] テストされるバッファのバッファ インデックス。
dwFlags
[in] 実行される照会のタイプを示すフラグ。ゼロの場合、サーフェスを更新に使用しても安全かどうかがテストされる。AMVA_QUERYRENDERSTATUSF_READ の場合、サーフェスを読み取りに使用しても安全かどうかがテストされる。

戻り値

HRESULT 値を返す。操作が完了した場合は S_OK、操作が進行中の場合は E_PENDING を返す。操作が失敗すると、このメソッドは別の失敗コードを返す。このコードには、次の標準的な定数の 1 つか、または一覧に示されていないその他の値が含まれる。

E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_POINTER | Null ポインタ引数。
S_OK | 成功。

注意

このメソッドを呼び出すと、進行状況と失敗が報告される。

IAMVideoAccelerator::DisplayFrame

IAMVideoAccelerator

デコード済みフレームを表示する。

構文

HRESULT DisplayFrame(
    DWORD dwFlipToIndex,
    IMediaSample *pMediaSample
);

パラメータ

dwFlipToIndex
[in] 表示する圧縮解除されたフレームのサーフェス インデックス。
pMediaSample
[in] 開始と停止のタイム スタンプが含まれる IMediaSample 構造体へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。

E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_POINTER | Null ポインタ引数。
S_OK | 成功。

注意

このメソッドは、ピンの接続後に呼び出した場合にのみ有効である。この呼び出しはほかの操作をブロックしない。

ビデオ デコーダは、インデックスが dwFlipToIndex であるサーフェスに対して EndFrame を呼び出した後に、このメソッドを呼び出す。このインデックスは、前に BeginFrame の呼び出しで渡された AMVABeginFrameInfo 構造体の dwDestSurfaceIndex メンバの値である必要がある。


IAMVideoAcceleratorNotify インターフェイス

IAMVideoAcceleratorNotify インターフェイスは、ビデオ デコーダの出力ピンでサポートされている。このメソッドは、ダウンストリーム オーバーレイ ミキサーとピンが接続している間に呼び出され、IAMVideoAccelerator インターフェイスを設定する。

注 : このインターフェイスは、Microsoft® Windows® 2000 で使用できる。

要件

Videoacc.h が必要である。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMVideoAcceleratorNotify メソッド | 説明
GetUncompSurfacesInfo | 指定されたビデオ アクセラレータの GUID に関する圧縮解除されたバッファの情報を取得する。
SetUncompSurfacesInfo | 圧縮されていないバッファの情報を設定する。
GetCreateVideoAcceleratorData | ビデオ アクセラレータ オブジェクトの作成に必要な情報を取得する。

IAMVideoAcceleratorNotify::GetUncompSurfacesInfo

IAMVideoAcceleratorNotify

指定されたビデオ アクセラレータの GUID に対する圧縮解除されたバッファの情報を取得する。

構文

HRESULT GetUncompSurfacesInfo(
    const GUID *pGuid,
    LPAMVAUncompBufferInfo pUncomBufferInfo
);

パラメータ

pGuid
[in] 情報取得対象のビデオ アクセラレータを識別する GUID へのポインタ。
pUncompBufferInfo
[in, out] 圧縮されていないサーフェス情報を含む AMVAUncompBufferInfo 構造体へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。

E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_POINTER | Null ポインタ引数。
S_OK | 成功。

注意

このメソッドを呼び出すと、ピクセル フォーマットだけでなく、サーフェスの最小数および最大数に対するビデオ デコーダの要件が返される。このメソッドは圧縮されていないデータ バッファの割り当てに必要な情報を提供する。

IAMVideoAcceleratorNotify::SetUncompSurfacesInfo

IAMVideoAcceleratorNotify

圧縮されていないバッファの情報を設定する。

構文

HRESULT SetUncompSurfacesInfo(
    DWORD  dwActualUncompSurfacesAllocated
);

パラメータ

dwActualUncompSurfacesAllocated
[in] 割り当てられるサーフェスの数。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。

E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_POINTER | Null ポインタ引数。
S_OK | 成功。

注意

このメソッドを呼び出すと、実際に割り当てられている圧縮解除されたサーフェスの数がビデオ デコーダに通知される。

IAMVideoAcceleratorNotify::GetCreateVideoAcceleratorData

IAMVideoAcceleratorNotify

ビデオ アクセラレータ オブジェクトの作成に必要な情報を取得する。

構文

HRESULT GetCreateVideoAcceleratorData(
    const GUID *pGuid,
    LPWDORD pdwSizeMiscData,
    LPVOID *ppMiscData
);

パラメータ

pGuid
[in] ビデオ アクセラレータを識別する GUID へのポインタ。
pdwSizeMiscData
[out] ppMiscData に返されるデータのサイズ (バイト単位) を受け取る変数へのポインタ。
ppMiscData
[out] 各種のデータ (pdwSizeMiscData が 0 の場合は NULL) を受け取る void 型 のポインタへのアドレス。このポインタは CoTaskMemAlloc (COM ライブラリのヘルパー関数) で割り当てる必要がある。このアドレスは呼び出し元が解放する。「注意」を参照すること。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。

E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_POINTER | Null ポインタ引数。
S_OK | 成功。

注意

このメソッドは、ビデオ アクセラレータの初期化時にビデオ デコーダがビデオ アクセラレータに送信する必要のある各種のデータへのポインタを取得する。ppMiscData について CoTaskMemFree を呼び出す操作は呼び出し元で行う。


IAMVideoCompression インターフェイス

IAMVideoCompression ピン インターフェイスを使用すると、メディア タイプに含まれていない圧縮パラメータを制御できる。

put_PFramesPerKeyFrame メソッドおよび get_PFramesPerKeyFrame メソッドは、予測 (P) フレームおよび両方向予測 (B) フレームを参照する。これは、MPEG の概念で、一般に MPEG より単純なタイプのコンプレッサには該当しない。

このインターフェイスを、圧縮済みビデオ データを提供するビデオ キャプチャまたはビデオ コンプレッサ フィルタの出力ピンで実装する。

アプリケーションは、このインターフェイスを使用して、キー フレームの数、フレーム品質などの特性を含めて、ビデオの圧縮方法を制御する。また、コンプレッサのテキスト説明、およびコンプレッサの機能などのその他の入手可能な情報の取得に使用する。

注 : このインターフェイスは、キャプチャ フィルタの出力ピンがグラフ内の別のフィルタに接続していない場合、使用できないことがある。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMVideoCompression methods | 説明
put_KeyFrameRate | キー フレーム レートを設定する。
get_KeyFrameRate | キー フレーム レートを取得する。
put_PFramesPerKeyFrame | 予測 (P) フレームの間隔を設定する。
get_PFramesPerKeyFrame | P フレームの間隔を取得する。
put_Quality | ビデオ イメージ圧縮の品質を設定する。
get_Quality | 現在のイメージ品質の設定を取得する。
put_WindowSize | コンプレッサが維持しなければならない平均データ レートの基準となるフレーム数を設定する。
get_WindowSize | コンプレッサが維持しなければならない平均データ レートの基準となるフレーム数を取得する。
GetInfo | コンプレッサの情報を取得する。
OverrideKeyFrame | 特定のフレームをキー フレームにする。
OverrideFrameSize | 特定のフレームのデータ レートを無効にする。

IAMVideoCompression::GetInfo

IAMVideoCompression インターフェイス

コンプレッサの情報を取得する。

構文

HRESULT GetInfo(
    WCHAR *pszVersion,
    int *pcbVersion,
    LPWSTR pszDescription,
    int *pcbDescription,
    long *pDefaultKeyFrameRate,
    long *pDefaultPFramesPerKey,
    double *pDefaultQuality,
    long *pCapabilities
    ) PURE;

パラメータ

pszVersion
[out] "Version 2.1.0" などのバージョン文字列へのポインタ。
pcbVersion
[in, out] バージョン文字列に必要なサイズ。文字数ではなく Unicode™ 文字列でのバイト数へのポインタ。したがって、その文字列が保持できる文字数の 2 倍でなければならない。現在のサイズを取得する場合は、このパラメータに NULL を設定して呼び出す。
pszDescription
[out] "Awesome Video Compressor" などの説明文字列へのポインタ。
pcbDescription
[in, out] 説明文字列に必要なサイズ。文字数ではなく Unicode™ 文字列でのバイト数へのポインタ。したがって、その文字列が保持できる文字数の 2 倍でなければならない。現在のサイズを取得する場合は、このパラメータに NULL を設定して呼び出す。
pDefaultKeyFrameRate
[out] デフォルトのキー フレーム レートを受け取るためのポインタ。
pDefaultPFramesPerKey
[out] キー フレームごとのデフォルトの予測 (P) フレーム数を受け取るためのポインタ。
pDefaultQuality
[out] デフォルトの品質を受け取るためのポインタ。
pCapabilities
[out] 圧縮機能の情報を受け取るためのポインタ。この圧縮機能の情報は、CompressionCaps 列挙型フラグの組み合わせである。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

IAMVideoCompression::get_KeyFrameRate

IAMVideoCompression インターフェイス

現在のキー フレーム レートを取得する。

構文

get_KeyFrameRate(
    long *pKeyFrameRate
    ) PURE;

パラメータ

pKeyFrameRate
[out] コンプレッサの現在のキー フレーム レートへのポインタ。負の値は、コンプレッサがビデオ コンプレッサのデフォルトのフレーム レートを使用していることを示す。ゼロ値は、最初のフレームだけがキー フレームであることを示す。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

コンプレッサがこのメソッドをサポートしているかどうかを確認するには、IAMVideoCompression::GetInfo メソッドの pCapabilities パラメータに返される CompressionCaps_CanKeyFrame フラグを調べる。

参照

IAMVideoCompression::put_KeyFrameRate

IAMVideoCompression::get_PFramesPerKeyFrame

IAMVideoCompression インターフェイス

予測 (P) フレームの間隔を取得する。

構文

HRESULT get_PFramesPerKeyFrame(
    long *pPFramesPerKeyFrame
    ) PURE;

パラメータ

pPFramesPerKeyFrame
[out] キー フレームごとの P フレームの数を受け取るためのポインタ。負の値は、コンプレッサがデフォルト値を使用することを示す。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。Video for Windows のキャプチャ フィルタ (VFW キャプチャ) および AVI 圧縮フィルタ (AVI コンプレッサ) では、現在このインターフェイスがサポートされていないので、E_NOTIMPL が返される。

注意

コンプレッサがこのメソッドをサポートしているかどうかを確認するには、IAMVideoCompression::GetInfo メソッドの pCapabilities パラメータに返される CompressionCaps_CanBFrame フラグを調べる。

各フレーム タイプの間の関係の例として、10 フレームごとにキー フレームが一度発生し、キー フレームごとに 3 個の P フレームがある場合を想定する。これらの P フレームはキー フレーム間で等間隔に発生する。キー フレームと P フレームの間にあるほかの 6 個のフレームは両方向予測 (B) フレームである。

参照

IAMVideoCompression::put_KeyFrameRate

IAMVideoCompression::get_Quality

IAMVideoCompression インターフェイス

現在のイメージ品質の設定を取得する。

構文

HRESULT get_Quality(
    double *pQuality
    ) PURE;

パラメータ

pQuality
[out] 現在の品質の設定へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

品質は、0 から 1 の範囲の値である。1 は最高品質を示し、0 は最低品質を示す。負の値は、コンプレッサのデフォルトが使用されていることを示す。この値はコンプレッサによって解釈する。その解釈はコンプレッサごとに異なる。コンプレッサが特定のデータ レートで圧縮しているのではない場合、この値によってイメージ サイズまたは品質が大まかに決定される。

コンプレッサがこのメソッドをサポートしているかどうかを確認するには、IAMVideoCompression::GetInfo メソッドの pCapabilities パラメータに返される CompressionCaps_CanQuality フラグを調べる。

固定データ レートで圧縮している場合、品質値が高いと、全データ レートが使用されることを意味する。品質値が低いと、そのデータ レートよりもかなり低いデータ レートを使用できることを意味する。

IAMVideoCompression::get_WindowSize

IAMVideoCompression インターフェイス

コンプレッサが維持しなければならない平均データ レートの基準となるフレーム数を取得する。

構文

HRESULT get_WindowSize(
    DWORDLONG *pWindowSize
    );

パラメータ

pWindowSize
[out] ウィンドウ サイズを受け取る DWORDLONG 値へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

参照

IAMVideoCompression::put_WindowSize

IAMVideoCompression::OverrideFrameSize

IAMVideoCompression インターフェイス

フレームのデータ レートを無効にする。

構文

HRESULT OverrideFrameSize(
    long FrameNumber,
    long Size
    ) PURE;

パラメータ

FrameNumber
[in] サイズを変更するフレームの番号。
Size
[in] 指定したフレームに対する変更後のサイズ (バイト単位)。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。Video for Windows のキャプチャ フィルタ (VFW キャプチャ) および AVI 圧縮フィルタ (AVI コンプレッサ) では、現在このインターフェイスがサポートされていないので、E_NOTIMPL が返される。

注意

コンプレッサがこのメソッドをサポートしているかどうかを確認するには、IAMVideoCompression::GetInfo メソッドの pCapabilities パラメータに返される CompressionCaps_CanCrunch フラグを調べる。このフラグは、dwBitRate 値を AM_MEDIA_TYPE の VIDEOINFOHEADER 構造体で設定できることを示すために設定される場合もある。

フレーム番号は、ストリーミング後にフィルタから出力されるフレームを指す。たとえば、フレーム 0 は、このピンが配信する 1 番目のフレームを示す。フレーム 11 はピンが配信する 12 番目のフレームを示す。このメソッドは、サイズ変更対象のフレームがフィルタによって配信される前に呼び出すようにする。

フレーム サイズを無効にする (フレーム "クランチング") と、本来予定されていたサイズではなくこのメソッドで指定されたバイトまたはそれ以下にするようにフィルタに指示される。

IAMVideoCompression::OverrideKeyFrame

IAMVideoCompression インターフェイス

フレームをキー フレームにする。

構文

HRESULT OverrideKeyFrame(
    long FrameNumber
    ) PURE;

パラメータ

FrameNumber
[in] 通常はキー フレームでない場合でも、グラフの実行時にキー フレームにされるフレームの番号。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。Video for Windows のキャプチャ フィルタ (VFW キャプチャ) および AVI 圧縮フィルタ (AVI コンプレッサ) では、現在このインターフェイスがサポートされていないので、E_NOTIMPL が返される。

注意

コンプレッサは、キー フレームを作成した後にそのカウントをリセットして、次にキー フレームが発生する場所を決定できる。たとえば、通常キー フレームが 10 フレームおきに発生するとする。OverrideKeyFrame を使用してフレーム 5 をキー フレームとして設定すると、コンプレッサは次のキー フレームを作成するまでもう 10 フレーム待つことができる。

IAMVideoCompression::put_KeyFrameRate

IAMVideoCompression インターフェイス

キー フレーム レートを設定する。

構文

HRESULT put_KeyFrameRate(
    long KeyFrameRate
    ) PURE;

パラメータ

KeyFrameRate
[in] 設定するキー フレーム レート。負の値はビデオ コンプレッサがデフォルトのフレーム レートを使用することを示す。ゼロ値は最初のフレームだけがキー フレームであることを示す。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

コンプレッサがこのメソッドをサポートしているかどうかを確認するには、IAMVideoCompression::GetInfo メソッドの pCapabilities パラメータに返される CompressionCaps_CanKeyFrame フラグを調べる。

IAMVideoCompression::put_PFramesPerKeyFrame

IAMVideoCompression インターフェイス

予測 (P) フレームの間隔を設定する。

構文

HRESULT put_PFramesPerKeyFrame(
    long PFramesPerKeyFrame
    ) PURE;

パラメータ

PFramesPerKeyFrame
[in] 設定する P フレームの間隔。負の値はビデオ コンプレッサがデフォルトのフレーム レートを使用することを示す。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。 Video for Windows のキャプチャ フィルタ (VFW キャプチャ) および AVI 圧縮フィルタ (AVI コンプレッサ) では、現在このインターフェイスがサポートされていないので、E_NOTIMPL が返される。

注意

コンプレッサがこのメソッドをサポートしているかどうかを確認するには、IAMVideoCompression::GetInfo メソッドの pCapabilities パラメータに返される CompressionCaps_CanBFrame フラグを調べる。

各フレーム タイプの間の関係の例として、10 フレームごとにキー フレームが一度発生し、キー フレームごとに 3 個の P フレームがある場合を想定する。これらの P フレームはキー フレーム間で等間隔に発生する。キー フレームと P フレームの間にあるほかの 6 個のフレームは両方向予測 (B) フレームである。

IAMVideoCompression::put_Quality

IAMVideoCompression インターフェイス

ビデオ イメージの品質を設定する。

構文

HRESULT put_Quality(
    double Quality
    ) PURE;

パラメータ

Quality
[in] 設定する品質。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

品質は 0 と 1 を含む 0 ～ 1 の範囲の値である。1 は最高品質を示し、0 は最低品質を示す。負の値は、コンプレッサのデフォルトが使用されることを示す。この値はコンプレッサ (CODEC) によって解釈される。その解釈は CODEC ごとに異なる。コンプレッサが特定のデータ レートで圧縮しているのではない場合、この値によってイメージ サイズまたは品質が大まかに決定される。

コンプレッサがこのメソッドをサポートしているかどうかを確認するには、IAMVideoCompression::GetInfo メソッドの pCapabilities パラメータに返される CompressionCaps_CanQuality フラグを調べる。

固定データ レートで圧縮している場合、品質値が高いと、全データ レートが使用されることを意味する。品質値が低いと、そのデータ レートよりもかなり低いデータ レートを使用できることを意味する。

IAMVideoCompression::put_WindowSize

IAMVideoCompression インターフェイス

コンプレッサが維持しなければならない平均データ レートの基準となるフレーム数を設定する。

構文

HRESULT put_WindowSize(
    DWORDLONG WindowSize
    );

パラメータ

WindowSize
[in] ウィンドウのサイズ (フレーム数)。その平均サイズは、コンプレッサが提供するように求められているデータ レートを超えることはできない。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

サイズ n のウィンドウの場合、連続した n 個のフレームの平均フレーム サイズは、そのストリームの指定されたデータ レートを超えない。ただし、それぞれのフレームはそれよりも大きくても小さくてもかまわない。たとえば、毎秒 10 フレーム (fps) のムービーに対して毎秒 100 キロバイト (KB) のデータ レートを設定した場合、通常は、各フレームが 10 KB 以下でなければならないことを意味する。しかし、ウィンドウ サイズに n を設定することで、これら n 個のフレームの平均の長さが 10 KB 以下である限り、それぞれのフレームの大きさは問題ではないことを指定することになる。たとえば、フレームが 10 KB より小さくても、10 KB よりも大きくても、平均が 10 KB 以下であればかまわない。

参照

IAMVideoCompression::get_WindowSize


IAMVideoControl インターフェイス

IAMVideoControl インターフェイスによって、水平方向および垂直方向へのピクチャのフリッピング、外部トリガ (ユーザーが押すカメラのボタンなど) のキャプチャを可能にするためのストリームの設定、ソフトウェアでの外部トリガのシミュレーション、および利用可能なフレーム レートのリストの取得を行うことができる。

このインターフェイスは、VideoControlFlags 列挙型のビデオ制御フラグを使用する。

フィルタによるビデオ イメージの制御またはフレーム レートの一覧の取得が必要な場合に、このインターフェイスを実装する。

また、フリッピングおよび外部トリガのキャプチャが可能なハードウェア上でアプリケーションを実行する場合にこのインターフェイスを使用する。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMVideoControl メソッド | 説明
GetCaps | 基礎となるハードウェアの能力を取得する。
SetMode | 操作のビデオ制御モードを設定する。
GetMode | 操作のビデオ制御モードを取得する。
GetCurrentActualFrameRate | デバイスがストリーミングしている実際のフレーム レートを取得する。このメソッドは、USB (Universal Serial Bus)、IEEE 1394 シリアル通信規格対応カメラなど、利用可能な帯域幅によって最大フレーム レートが制限されるデバイスと共に使用する。このメソッドは、ビデオ ストリーミング中にのみ使用できる。
GetMaxAvailableFrameRate | USB、IEEE 1394 対応カメラ デバイスなど、利用可能な帯域幅によって最大フレーム レートが制限される接続のバス帯域幅の使用率に基づいて、現在利用可能な最大フレーム レートを取得する。
GetFrameRateList | 利用可能なフレーム レートのリストを取得する。

IAMVideoControl::GetCaps

IAMVideoControl インターフェイス

基礎となるハードウェアの能力を取得する。

構文

HRESULT GetCaps (

  IPin *pPin,

  long *pCapsFlags

  );

パラメータ

pPin
[in] 能力の照会対象となるピンへのポインタ。
pCapsFlags
[out] VideoControlFlags 列挙型のフラグの組み合わせを表す値へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

取得できる能力には、水平方向へのピクチャのフリッピング、垂直方向へのピクチャのフリッピング、外部トリガの有効化、および外部トリガのシミュレーションのうち、1 つまたは複数が含まれる。

IAMVideoControl::GetCurrentActualFrameRate

IAMVideoControl インターフェイス

実際のフレーム レートを取得する。フレーム レートは 100 ナノ秒単位のフレーム時間幅として表される。USB (Universal Serial Bus) および IEEE 1394 対応カメラの場合、利用可能な帯域幅によって、要求よりもフレーム レートが低くなる場合がある。このメソッドは、ビデオ ストリーミング中にのみ使用できる。

構文

HRESULT GetCurrentActualFrameRate (

  IPin *pPin,

  LONGLONG *ActualFrameRate

  );

パラメータ

pPin
[in] フレーム レートの取得対象となるピンへのポインタ。
ActualFrameRate
[out] 100 ナノ秒単位のフレーム時間幅で表されるフレーム レートへのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

IAMVideoControl::GetFrameRateList

IAMVideoControl インターフェイス

利用可能なフレーム レートのリストを取得する。

構文

HRESULT GetFrameRateList (

  IPin *pPin,

  long iIndex,

  SIZE Dimensions,

  long *ListSize,

  LONGLONG **FrameRates

  );

パラメータ

pPin
[in] フレーム レートのリストの照会対象となるピンへのポインタ。
iIndex
[in] フレーム レートの照会対象となるフォーマットのインデックス。このインデックスは、フォーマットが IAMStreamConfig::GetStreamCaps で列挙される順序に対応している。値の範囲は、0 から IAMStreamConfig::GetNumberOfCapabilities メソッドが返すサポートされている VIDEO_STREAM_CONFIG_CAPS 構造体の数から 1 を減算した値までである。
Dimensions
[in] フレーム イメージのピクセル単位のサイズ (幅と高さ)。
ListSize
[out] フレーム レートのリスト内の要素数へのポインタ。
FrameRates
[out] 100 ナノ秒単位のフレーム レートの配列へのポインタのアドレス。ListSize だけを必要とする場合は、このデータは NULL になる可能性がある。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

呼び出し元は、CoTaskMemFree を呼び出してメモリを解放する必要がある。

IAMVideoControl::GetMaxAvailableFrameRate

IAMVideoControl インターフェイス

USB、IEEE 1394 対応カメラ デバイスなど、利用可能な帯域幅によって最大フレーム レートが制限される接続に対するバス帯域幅の使用率に基づいて、現在利用可能な最大フレーム レートを取得する。

構文

HRESULT GetMaxAvailableFrameRate(

  IPin *pPin,

  long iIndex,

  SIZE Dimensions,

  LONGLONG *MaxAvailableFrameRate

  );

パラメータ

pPin
[in] 最大フレーム レートの取得対象となるピンへのポインタ。
iIndex
[in] 最大フレーム レートを照会対象となるフォーマットのインデックス。このインデックスは、フォーマットが IAMStreamConfig::GetStreamCaps で列挙されている順序に対応している。値の範囲は、0 から IAMStreamConfig::GetNumberOfCapabilities メソッドが返すサポートされている VIDEO_STREAM_CONFIG_CAPS 構造体の数から 1 を減算した値までである。
Dimensions
[in] フレーム イメージのピクセル単位のサイズ (幅と高さ)。
MaxAvailableFrameRate
[out] 利用可能な最大フレーム レートへのポインタ。フレーム レートは、100 ナノ秒単位のフレーム時間幅として表される。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

IAMVideoControl::GetMode

IAMVideoControl インターフェイス

操作のビデオ制御モードを取得する。

構文

HRESULT GetMode (

  IPin *pPin,

  long *Mode

  );

パラメータ

pPin
[in] ビデオ制御モードの取得対象となるピンへのポインタ。
Mode
[out] ビデオ制御モードを指定する VideoControlFlags 列挙型のフラグの組み合わせを表す値へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

取得できる操作モードには、水平方向へのピクチャのフリッピング、垂直方向へのピクチャのフリッピング、外部トリガの有効化、および外部トリガのシミュレーションのうち、1 つまたは複数が含まれる。

IAMVideoControl::SetMode

IAMVideoControl インターフェイス

操作のビデオ制御モードを設定する。

構文

HRESULT SetMode (

  IPin *pPin,

  long Mode

  );

パラメータ

pPin
[in] ビデオ制御モードの設定対象となるピンへのポインタ。
Mode
[in] ビデオ制御モードを設定する VideoControlFlags 列挙型のフラグの組み合わせを指定する値。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

取得できる操作モードには、水平方向へのピクチャのフリッピング、垂直方向へのピクチャのフリッピング、外部トリガの有効化、および外部トリガのシミュレーションのうち、1 つまたは複数が含まれる。


IAMVideoDecimationProperties インターフェイス

IAMVideoDecimationProperties インターフェイスによって、アプリケーションはビデオ デシメーションの発生場所を制御できる。このインターフェイスはオーバーレイ ミキサー フィルタで実装される。

ビデオ ウィンドウが表示中のビデオのネイティブ サイズよりも小さい場合、ビデオ レンダラは受信ビデオをデシメートする必要がある。つまり、ビデオを小さいサイズに縮小する必要がある。デシメーションは、次のいずれかの場所で実行できる。

  • VGA チップ上のオーバーレイ ハードウェア
  • ビデオ ポートに組み込みのスカラー (接続にビデオ ポートを使用する場合)
  • ビデオをレンダラに供給するデコーダ

アプリケーションはこのインターフェイスでメソッドを呼び出し、特定のデシメーション方法を選択して、パフォーマンスを最適化できる。ただし、ほとんどのアプリケーションの場合このインターフェイスを使用することはない。アプリケーションが特定のハードウェアをサポートするように設計されていない限り、オーバーレイ ミキサーのデフォルトのデシメーション動作を変更する必要はない。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMVideoDecimationProperties メソッド | 説明
QueryDecimationUsage | 現在のデシメーション方法を取得する。
SetDecimationUsage | デシメーション方法を設定する。

IAMVideoDecimationProperties::QueryDecimationUsage

IAMVideoDecimationProperties インターフェイス

現在のデシメーション方法を取得する。

構文

HRESULT QueryDecimationUsage(
    DECIMATION_USAGE *lpUsage
);

パラメータ

lpUsage
[out] デシメーションの設定を取得する DECIMATION_USAGE 列挙型の変数へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。Microsoft® DirectShow® の実装では、成功した場合は S_OK、それ以外の場合は E_FAIL またはほかのエラー コードを返す。

IAMVideoDecimationProperties::SetDecimationUsage

IAMVideoDecimationProperties インターフェイス

デシメーション方法を設定する。

構文

HRESULT SetDecimationUsage(
    DECIMATION_USAGE Usage
);

パラメータ

Usage
[in] デシメーション方法を指定する DECIMATION_USAGE 列挙型のメンバ｡

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。DirectShow の実装は、成功した場合は S_OK を返し、それ以外の場合は E_INVALIDARG を返す。


IAMVideoProcAmp インターフェイス

IAMVideoProcAmp インターフェイスは、WDM ビデオ キャプチャ フィルタで実装される。このインターフェイスによって、アプリケーションは輝度、コントラスト、色相、彩度、ガンマ、鮮明度など、受信するビデオ信号の品質を調整できる。アナログ ドメインとデジタル ドメインのどちらで調整したかに関係なく、これらの設定に対して同一の範囲が定義される。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMVideoProcAmp methods | 説明
GetRange | 設定プロパティの最小値、最大値、およびデフォルト値を取得する。
Set | 指定されたプロパティのビデオ品質を設定する。
Get | 指定されたプロパティのビデオ品質を取得する。

IAMVideoProcAmp::Get

IAMVideoProcAmp インターフェイス

指定されたプロパティのビデオ品質を取得する。

構文

HRESULT Get(

  long Property,

  long *lValue,

  long *Flags );

パラメータ

Property
[in] 設定の取得対象となる特定のプロパティ。VideoProcAmpProperty 列挙型のメンバを指定する。
lValue
[out] プロパティの現在の値へのポインタ。
Flags
[out] VideoProcAmpFlags 列挙型のメンバへのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
NOERROR | エラーなし。

IAMVideoProcAmp::GetRange

IAMVideoProcAmp インターフェイス

設定プロパティの最小値、最大値、およびデフォルト値を取得する。

構文

HRESULT GetRange(

  long Property,

  long *pMin,

  long *pMax,

  long *pSteppingDelta,

  long *pDefault,

  long *pCapsFlags );

パラメータ

Property
[in] 範囲の確認対象となる特定のプロパティ。VideoProcAmpProperty 列挙型のメンバを指定する。
pMin
[out] 設定範囲の最小値へのポインタ。
pMax
[out] 設定範囲の最大値へのポインタ。
pSteppingDelta
[out] ステップ サイズへのポインタ。
pDefault
[out] デフォルト値へのポインタ。
pCapsFlags
[out] VideoProcAmpFlags 列挙型のメンバへのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
NOERROR | エラーなし。

IAMVideoProcAmp::Set

IAMVideoProcAmp インターフェイス

指定されたプロパティのビデオ品質を設定する。

構文

HRESULT Set(
  long Property,
  long lValue,
  long Flags );

パラメータ

Property
[in] 設定対象となる特定のプロパティ。VideoProcAmpProperty 列挙型のメンバを指定する。
lValue
[in] プロパティの設定を示す値。
Flags
[in] VideoProcAmpFlags 列挙型のメンバ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
NOERROR | エラーなし。


IAsyncReader インターフェイス

IAsyncReader インターフェイスは 非同期ファイル ソース フィルタの出力ピンによって実装される。このインターフェイスによって、メディア ストリーム内の異なる位置から複数の読み取りをオーバーラップさせることができる。このインターフェイスのメソッドはダウンストリーム フィルタの入力ピンによって呼び出される。アプリケーションでこのインターフェイスを使用することはない。

フィルタ開発者: フィルタがソースから MEDIATYPE_Stream メディア タイプのデータを読み取る場合は、このインターフェイスをピンで実装する。接続中に、IAsyncReader をサポートする出力ピンは、その出力ピンの QueryInterface メソッドが呼び出されて IAsyncReader インターフェイスが要求されたかどうを調べる必要がある。呼び出されていないと、接続中に使用するほかの転送を確立しない限り、出力ピンが接続に失敗する。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAsyncReader メソッド | 説明
RequestAllocator | 実際に使用されるアロケータを取得する。
Request | データ要求をキューに入れる。
WaitForNext | 次のサンプルが完了するか、またはタイムアウトが発生するまでブロックする。
SyncReadAligned | 位置合わせされた同期読み取りを実行する。
SyncRead | 同期読み取りを実行する。
Length | ストリームのトータルの長さ、および現在利用可能な長さを取得する。
BeginFlush | すべての未処理の読み取りが返される。
EndFlush | フラッシング操作を完了する。

IAsyncReader::BeginFlush

IAsyncReader インターフェイス

フラッシング操作を開始する。

構文

HRESULT BeginFlush(void);

戻り値

成功した場合は S_OK、それ以外の場合は S_FALSE を返す。

注意

すべての未処理の読み取りが返される。これに失敗コード (VFW_E_TIMEOUT) が付随する場合もある。この操作は、未処理の読み取りをキャンセルすることを示す。IAsyncReader::BeginFlush 呼び出しと IAsyncReader::EndFlush 呼び出しの間に、IAsyncReader::Request 呼び出しが失敗し、即座に IAsyncReader::WaitForNext 呼び出しが必ず完了する。

IAsyncReader::EndFlush

IAsyncReader インターフェイス

フラッシング操作を完了する。

構文

HRESULT EndFlush(void);

戻り値

成功した場合は S_OK、それ以外の場合は S_FALSE を返す。

注意

IAsyncReader::BeginFlush 呼び出しと IAsyncReader::EndFlush 呼び出しの間に、IAsyncReader::Request 呼び出しが失敗し、即座に IAsyncReader::WaitForNext 呼び出しが必ず完了する。このメソッドを呼び出して、ソースのスレッドが IAsyncReader::WaitForNext メソッド内で再び待機できるようする。

IAsyncReader::Length

IAsyncReader インターフェイス

ストリームのトータルの長さ、および現在利用可能な長さを取得する。

構文

HRESULT Length(

  LONGLONG *pTotal,

  LONGLONG *pAvailable

  );

パラメータ

pTotal
割り当て済みのトータルの長さへのポインタ。
pAvailable
利用可能な長さへのポインタ。

戻り値

成功した場合は S_OK、ファイルが開かれていない場合は E_UNEXPECTED を返す。

注意

読み取りがトータルの長さ以内であっても利用可能な長さを超える場合、通常その操作は成功するが、長時間ブロックする場合がある。

IAsyncReader::Request

IAsyncReader インターフェイス

データ要求をキューに入れる。

構文

HRESULT Request(

  IMediaSample *pSample,

  DWORD dwUser

  );

パラメータ

pSample
要求されているメディア サンプルへのポインタ。
dwUser
[in] ユーザー コンテキスト。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。 現在の Microsoft® DirectShow® の実装での戻り値は、次のとおりである。
VFW_E_BADALIGN | 無効なアラインメントが指定された。
VFW_E_MEDIA_TIME_NOT_SET | 時間が設定されていない。
HRESULT_FROM_WIN32 | ファイルの末尾を越えるデータが要求されている。
NOERROR | エラーなし。
S_OK | 成功。

注意

メディア サンプルの開始タイムと終了タイムには、要求される絶対バイト位置が含まれる。ただし、開始位置は含まれるが、停止位置は含まれない。このメソッドは、合意されたアロケータからサンプルが取得されない場合、あるいは開始位置または停止位置が合意されたアラインメントに一致しない場合に失敗することがある。IAsyncReader::WaitForNext から戻るまでに、ソース ピンのアロケータから割り当てられたサンプルによって、IMediaSample::GetPointer が失敗する場合がある。

停止位置は位置合わせされなければならない。ただし、その停止位置が時間幅を超えている場合がある。その場合は、完了時に停止位置は位置合わせされていない実際のデータに訂正される。

dwUser パラメータは、IAsyncReader::WaitForNext メソッドから返されるサンプルを識別するために、呼び出し元が使用する。これは IAsyncReader 内では無意味だが、サンプル情報を個別に追跡する場合に使用できる。

IAsyncReader::RequestAllocator

IAsyncReader インターフェイス

実際に使用されるアロケータを取得する。

構文

HRESULT RequestAllocator(

  IMemAllocator *pPreferred,

  ALLOCATOR_PROPERTIES *pProps,

  IMemAllocator **ppActual

  );

パラメータ

pPreferred
[in] 優先するアロケータへのポインタ。
pProps
[in] 優先するアロケータのプロパティ (サイズ、カウント、およびアラインメント) へのポインタ。
ppActual
[out] 実際に使用されるアロケータへのポインタのアドレス。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。現在の DirectShow の実装での戻り値は次のとおりである。
E_FAIL | アロケータの初期化が失敗した。
VFW_E_BADALIGN | 無効なアラインメントが指定された。
S_OK | アロケータが返された。

注意

優先するアロケータおよび優先するアロケータのプロパティを渡す必要がある。このメソッドは実際に使用されるアロケータを返す。

選択されているアラインメントおよびプレフィックスを調べるには、返されたアロケータに対して IMemAllocator::GetProperties を呼び出す。このアロケータに対してコミットおよびデコミットを指示するのは、非同期リーダーではなく、コンシューマである。IAsyncReader::Request を呼び出す前に、このメソッドを呼び出す必要がある。

IAsyncReader::SyncRead

IAsyncReader インターフェイス

同期読み取りを実行する。

構文

HRESULT SyncRead(

  LONGLONG llPosition,

  LONG lLength,

  BYTE *pBuffer

  );

パラメータ

llPosition
[in] 絶対ファイル位置。
lLength
[in] 必要なバイト数。
pBuffer
[out] データが書き込まれている場所へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。現在の DirectShow の実装での戻り値は次のとおりである。
VFW_E_BADALIGN | 無効なアラインメントが指定された。
HRESULT_FROM_WIN32 | Microsoft® Win32® エラー。
S_FALSE | サイズが変更された (おそらくファイルの末尾を越えたため)。
S_OK | 成功。

注意

SyncRead メソッドは実行状態だけでなく停止状態でも動作する。読み取りは必ずしも位置合わせされている必要はない。読み取りが実際のトータルの長さを超えていると、このメソッドは失敗する。

IAsyncReader::SyncReadAligned

IAsyncReader インターフェイス

データの同期読み取りを実行する。

構文

HRESULT SyncReadAligned(

  IMediaSample *pSample

  );

パラメータ

pSample
読み込むサンプルへのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。現在の DirectShow の実装での戻り値は次のとおりである。
VFW_E_BADALIGN | 無効なアラインメントが指定された。
HRESULT_FROM_WIN32 | Win32 エラー。
S_FALSE | サイズが変更された (おそらくファイルの末尾を越えたため)。
S_OK | 成功。

注意

渡されるサンプルは、合意されたアロケータから取得されていなければならない。開始位置と停止位置は、IAsyncReader::Request/IAsyncReader::WaitForNext ペアに合わせて位置合わせされなければならないが、ソース フィルタ上のスレッドの必要性はなくなる。

IAsyncReader::WaitForNext

IAsyncReader インターフェイス

IAsyncReader::Request を介して要求された次の読み取りが完了するまで、またはタイムアウトが発生するまでブロックする。

構文

HRESULT WaitForNext(

  DWORD dwTimeout,

  IMediaSample **ppSample,

  DWORD *pdwUser

  );

パラメータ

dwTimeout
[in] タイムアウト (ミリ秒単位)。ゼロまたは INFINITE も指定できる。
ppSample
[out] 完了したサンプルへのポインタのアドレス。
pdwUser
[out] ユーザー コンテキストへのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。現在の DirectShow の実装での戻り値は次のとおりである。
VFW_E_TIMEOUT | タイムアウトに達した。
VFW_E_WRONG_STATE | フィルタが不正な状態にあるため、操作を実行できなかった。
E_FAIL | 失敗。
S_OK | 成功。

注意

サンプルが順番どおりに返されない場合がある。なんらかの読み取りエラーがある場合、ソース フィルタによる通知が既に完了しており、HRESULT がエラーになる。ppSample が NULL ではなければ、要求は返された結果コードで完了している。

pdwUser パラメータは、返されたサンプルに対応する呼び出し元のコンテキスト DWORD を返す。


IBaseFilter インターフェイス

フィルタを制御するメソッドを提供する。すべての Microsoft® DirectShow® フィルタはこのインターフェイスを公開する。このインターフェイスは IMediaFilter インターフェイスから派生し、IMediaFilter フィルタを通して IPersist インターフェイスを継承する。

フィルタ グラフ マネージャはこのインターフェイスを使用してフィルタを制御する。アプリケーションと他のフィルタはこのインターフェイスを使用してピンを列挙し、フィルタ情報をクエリすることができる。アプリケーションはフィルタの状態を変更する際にそれを使うべきではない。そうではなく、フィルタ グラフ マネージャの IMediaControl インターフェイスを呼び出すこと。

フィルタ開発者へ : すべての DirectShow フィルタでこのインターフェイスを実装すること。CBaseFilter 基底クラスはこのインターフェイスを実装する。

Vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IMediaFilter メソッド | 説明
Stop | フィルタを停止する。
Pause | フィルタをポーズする。
Run | フィルタを実行する。
GetState | フィルタの状態 (実行、停止、ポーズ) を取得する。
SetSyncSource | フィルタの基準クロックを設定する。
GetSyncSource | フィルタが使っている基準クロックを取得する。
IBaseFilter メソッド | 説明
EnumPins | このフィルタのピンを列挙する。
FindPin | 指定した識別子でピンを取得する。
QueryFilterInfo | フィルタについての情報を取得する。
JoinFilterGraph | フィルタグラフに参加した、あるいはフィルタグラフから離れたことをフィルタに通知する。
QueryVendorInfo | ベンダー情報をもつ文字列を取得する。

IBaseFilter::EnumPins

IBaseFilter インターフェイス

このフィルタのピンを列挙する。

構文

HRESULT EnumPins(
    IEnumPins **ppEnum
);

パラメータ

ppEnum
[out] IEnumPins インターフェイスへのポインタを受け取る変数のアドレス。

戻り値

HRESULT 値を返す。以下の表に示されるいずれかの値。

S_OK | 成功
E_OUTOFMEMORY | メモリ不足
E_POINTER | NULL ポインタ引数

注意

このメソッドは IEnumPins インターフェイスをサポートする列挙子を返す、それは標準 COM 列挙子と同様に動作する。詳細については、「ピンの列挙」を参照すること。

メソッドが成功すると、IEnumPins インターフェイスに参照カウントが残る。インターフェイスの解放時に注意が必要。

IBaseFilter::FindPin

IBaseFilter インターフェイス

指定した識別子でピンを取得する。

構文

HRESULT FindPin(
    LPCWSTR Id,
    IPin **ppPin
);

パラメータ

Id
[in] 定数へのポインタ、ピンを示す NULL で終わる Unicode™ 文字列。IPin::QueryId を呼び出してピンの識別子を取得すること。
ppPin
[out] ピンの IPin インターフェイスへのポインタを受け取る変数のアドレス。メソッドが失敗すると、*ppPin は NULL にセットされる。

戻り値

HRESULT 値を返す。次の表に示されるいずれかの値。

S_OK | 成功。
E_POINTER | NULL ポインタ引数。
VFW_E_NOT_FOUND | この識別子ではピンを見つけられなかった。

注意

このメソッドはグラフの永続性をサポートする。IPin::QueryId メソッドを使ってピンの状態をセーブし、このメソッドを使って常態をリストアすること。ピンの識別子文字列はフィルタ実装によって定義される。識別子はフィルタ内でユニークなものでなければならない。

メソッドが成功すると、返ってくる IPin インターフェイスには参照カウントが残る。解放時には注意が必要。

IBaseFilter::JoinFilterGraph

IBaseFilter インターフェイス

フィルタ グラフに参加した、あるいはフィルタ グラフから離れたことをフィルタに通知する。

構文

HRESULT JoinFilterGraph(
    IFilterGraph *pGraph,
    LPCWSTR pName
);

パラメータ

pGraph
[in] フィルタ グラフ マネージャの IFilterGraph インターフェイスへのポインタ、あるいはフィルタがグラフを離れたなら NULL。
pName
[in, string] フィルタの名前を示す NULL で終わる Unicode™ 文字列へのポインタ。

戻り値

成功なら S_OK を返す、あるいはエラーの原因を示す HRESULT 値を返す。

注意

フィルタ グラフ マネージャがあるフィルタをフィルタ グラフに追加するとき、それは自分自身のポインタでこのメソッドを呼び出す。グラフからフィルタを削除するとき、このメソッドを NULL ポインタで呼び出す。

アプリケーションはこのメソッドを決して呼び出してはならない。フィルタをグラフに追加するには、フィルタ グラフ マネージャで IFilterGraph::AddFilter を呼び出すこと。

フィルタは IFilterGraph インターフェイス ポインタを保存するので、イベント通知を送ることができる。しかしこのインターフェイスへの参照カウントを追加しては ならない。そうすると参照化運との繰り返しを作る事になる、なぜならフィルタ グラフ マネージャはフィルタの参照カウントを保持しているからだ。参照の繰り返しによってインターフェイスは正しく解放できなくなる。フィルタ グラフ マネージャがフィルタにグラフから削除されたことを通知するまでは、IFilterGraph インターフェイスは有効性が保証される。

pName パラメータに渡される名前は QueryFilterInfo メソッドを呼び出すことで得られる。

IBaseFilter::QueryFilterInfo

IBaseFilter インターフェイス

フィルタについての情報を取得する。

構文

HRESULT QueryFilterInfo(
    FILTER_INFO *pInfo
);

パラメータ

pInfo
[out] FILTER_INFO 構造体へのポインタ。

戻り値

HRESULT 値を返す。次の表に示されるいずれかの値。

S_OK | 成功
E_POINTER | NULL ポインタ引数

注意

このメソッドは FILTER_INFO 構造体にフィルタ情報を書き込む。帰ったとき、FILTER_INFO 構造体の pGraph メンバが NULL ではないなら、IFilterGraph インターフェイスには参照カウントが残る。解放時には注意が必要。

IBaseFilter::QueryVendorInfo

IBaseFilter インターフェイス

ベンダー情報をもつ文字列を取得する。

構文

HRESULT QueryVendorInfo(
    LPWSTR *pVendorInfo
);

パラメータ

pVendorInfo
[out] ベンダー情報が入るワイド キャラクタ文字列へのポインタを受け取る変数のアドレス。

戻り値

HRESULT 値を返す。次の表に示されるいずれかの値。

S_OK | 成功。
E_NOTIMPL | メソッドはサポートされていない。
E_POINTER | NULL ポインタ引数。

注意

このメソッドはオプションである。フィルタはそのサポートを要求されない。

メソッドがサポートされているなら、それは CoTaskMemAlloc 関数を使って文字列用のメモリを割り当てる。メモリを解放するには CoTaskMemFree 関数を呼び出すこと。


IBasicAudio インターフェイス

IBasicAudio オートメーション インターフェイスは、オーディオ レンダリング フィルタおよびデフォルト DirectSound デバイス フィルタで実装されるが、PID によってフィルタ グラフ マネージャを介して公開される。アプリケーションは、常にフィルタ グラフ マネージャからこのインターフェイスを取得する必要がある。このインターフェイスを使用すると、C++ および Microsoft® Visual Basic® アプリケーションはオーディオ ストリームの基本ボリュームおよびバランスのプロパティを制御できる。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IDispatch メソッド | 説明
GetTypeInfoCount | このディスプインターフェイスに利用可能なタイプ情報があるかどうか判断する。
GetTypeInfo | GetTypeInfoCount が成功した場合は、このディスプインターフェイスのタイプ情報を取得する。
GetIDsOfNames | (引数を含む) プロパティおよびメソッドのテキスト名を対応する DISPID に変換する。
Invoke | DISPID およびその他の必要なパラメータが指定された場合は、このディスプインターフェイスのメソッドを呼び出すか、またはプロパティにアクセスする。
IBasicAudio methods | 説明
put_Volume | オーディオ信号のボリューム (振幅) を設定する。
get_Volume | オーディオ信号のボリューム (振幅) を取得する。
put_Balance | オーディオ信号のバランスを設定する。
get_Balance | オーディオ信号のバランスを取得する。

IBasicAudio::get_Balance

IBasicAudio インターフェイス

オーディオ信号のバランスを取得する。

構文

HRESULT get_Balance(

  long *plBalance

  );

パラメータ

plBalance
[out] Balance プロパティの戻り値へのポインタ。

戻り値

HRESULT 値を返す。

注意

Balance プロパティの値の範囲は、–10,000 から 10,000 までである。値 –10,000 は右スピーカが無効で、左スピーカだけがオーディオ信号を受け取っていることを示す。値 0 は両方のスピーカが同等のオーディオ信号を受け取っていることを示す。値 10,000 は左スピーカが無効で、右スピーカだけがオーディオ信号を受け取っていることを示す。

Volume プロパティと同様に、.01 デシベル (dB) 単位で表される (plBalance が正の値である場合は、–1 倍)。たとえば、値 1000 は右チャンネルが –10 dBで、左チャンネルが –90 dB であることを示す。

IBasicAudio::get_Volume

IBasicAudio インターフェイス

オーディオ信号のボリューム (振幅) を取得する。

構文

HRESULT get_Volume(

  long *plVolume

  );

パラメータ

plVolume
[out] Volume プロパティの戻り値へのポインタ。100 で除算されて、デシベル値に換算される (たとえば、–10,000 = –100 dB)。

戻り値

HRESULT 値を返す。

注意

IBasicAudio::put_Balance

IBasicAudio インターフェイス

オーディオ信号のバランスを設定する。

構文

HRESULT put_Balance(
  long lBalance
  );

パラメータ

lBalance
[in] Balance プロパティに設定する値。有効な入力範囲は、–10,000 から 10,000 まで。値 0 はバランスが真中に設定される。つまり、左右のスピーカに同じ振幅のオーディオ信号が送られる。

戻り値

HRESULT 値を返す。値が有効な入力範囲外である場合は E_INVALIDARG が返され、基礎となるデバイスがエラーを返した場合は E_FAIL が返される。

注意

Volume プロパティと同様に、.01 デシベル (dB) 単位で表される (plBalance が正の値である場合は、–1 倍)。たとえば、値 1000 は右チャンネルが –10 dBで、左チャンネルが –90 dB であることを示す。

IBasicAudio::put_Volume

IBasicAudio インターフェイス

オーディオ信号のボリューム (振幅) を設定する。

構文

HRESULT put_Volume(
  long lVolume
  );

パラメータ

lVolume
[in] Volume プロパティに設定する値。有効な入力範囲は、–10,000 から 0 まで。

戻り値

HRESULT 値を返す。値が有効な入力範囲外である場合は E_INVALIDARG が返され、基礎となるデバイスがエラーを返した場合は E_FAIL が返される。

注意

0 は最大ボリュームで、–10,000 は無音。ボリュームには対数目盛りが使用される。必要なデシベル レベルを 100 倍する (たとえば、–10,000 = –100 dB)。


IBasicVideo インターフェイス

IBasicVideo インターフェイスは、ビデオ レンダラ フィルタで実装され、PID を介してフィルタ グラフ マネージャで公開される。アプリケーションは、常にフィルタ グラフ マネージャを介してこのインターフェイスを取得する必要がある。このインターフェイスを使用すると、アプリケーションで、ビット レート、転送先矩形、転送元矩形などのビデオ プロパティを設定できる。これは、デュアル インターフェイスなので、C++ だけでなく Microsoft® Visual Basic® で記述されたアプリケーションからもアクセスできる。

IBasicVideo インターフェイスのメソッドを使用する場合、ビデオ レンダラが接続されていることだけが必要とされる。接続されていないと、インターフェイス メソッドはすべて VFW_E_NOT_CONNECTED を返す。ビデオ レンダラで設定されたプロパティは、連続した接続と接続解除の間で保持される。

ビデオを取り扱う場合、アプリケーションは使用するビデオの一部分を選択できる。この部分は、IBasicVideo インターフェイスが制御する転送元矩形となる。IBasicVideo を使用すると、この転送元矩形を設定および取得できる。IBasicVideo が使用するすべての矩形には、Microsoft® Win32® プログラミングで好まれる top、left、width、および height を使用し、top、left、right、および bottom は使用しない。転送元矩形を設定していない場合、その転送元矩形のプロパティはフル サイズのネイティブ ビデオを返す。矩形のディメンジョンはすべてピクセル単位で指定する。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IDispatch メソッド | 説明
GetTypeInfoCount | このディスプインターフェイスに利用可能なタイプ情報があるかどうか判断する。
GetTypeInfo | GetTypeInfoCount が成功した場合は、このディスプインターフェイスのタイプ情報を取得する。
GetIDsOfNames | (引数を含む) プロパティおよびメソッドのテキスト名を対応する DISPID に変換する。
Invoke | DISPID およびその他の必要なパラメータが指定された場合は、このディスプインターフェイスのメソッドを呼び出すか、またはプロパティにアクセスする。
IBasicVideo メソッド | 説明
get_AvgTimePerFrame | 連続するフレーム間の平均時間を 100 ナノ秒単位で取得する。
get_BitRate | ビデオ ストリームのおよそのビット レートを取得する。
get_BitErrorRate | ビデオ ストリームのおよそのビット エラー レートを取得する。
get_VideoWidth | 現在のビデオの幅を取得する。
get_VideoHeight | 現在のビデオの高さを取得する。
put_SourceLeft | ビデオの転送元矩形の x 軸の座標を設定する。
get_SourceLeft | ビデオの転送元矩形の x 軸の座標を取得する。
put_SourceWidth | ビデオの転送元矩形の幅を設定する。
get_SourceWidth | ビデオの転送元矩形の幅を取得する。
put_SourceTop | ビデオの転送元矩形の y 軸の座標を設定する。
get_SourceTop | ビデオの転送元矩形の y 軸の座標を取得する。
put_SourceHeight | ビデオの転送元矩形の高さを設定する。
get_SourceHeight | ビデオの転送元矩形の高さを取得する。
put_DestinationLeft | ビデオの転送先矩形の x 軸の座標を設定する。
get_DestinationLeft | ビデオの転送先矩形の x 軸の座標を取得する。
put_DestinationWidth | ビデオの転送先矩形の幅を設定する。
get_DestinationWidth | ビデオの転送先矩形の幅を取得する。
put_DestinationTop | ビデオの転送先矩形の y 軸の座標を設定する。
get_DestinationTop | ビデオの転送先矩形の y 軸の座標を取得する。
put_DestinationHeight | ビデオの転送先矩形の高さを設定する。
get_DestinationHeight | ビデオの転送先矩形の高さを取得する。
SetSourcePosition | ビデオの転送元矩形を設定する。
GetSourcePosition | ビデオの転送元矩形を取得する。
SetDefaultSourcePosition | デフォルトの転送元矩形を使用するようにレンダラに指示する。
SetDestinationPosition | ウィンドウに対する転送先矩形を設定する。
GetDestinationPosition | ウィンドウに対するビデオの転送先矩形を取得する。
SetDefaultDestinationPosition | ウィンドウに対するデフォルトの転送先位置を設定する。
GetVideoSize | ネイティブ ビデオのディメンジョンを取得する。
GetVideoPaletteEntries | ビデオで必要とされるカラー パレットのエントリを取得する。
GetCurrentImage | レンダラで待機している現在のイメージのコピーを返す。
IsUsingDefaultSource | レンダラがデフォルトの転送元矩形を使用しているかどうかを判別する。
IsUsingDefaultDestination | レンダラがデフォルトの転送先矩形を使用しているかどうかを判別する。

IBasicVideo::get_AvgTimePerFrame

IBasicVideo インターフェイス

連続するフレーム間の平均時間を 100 ナノ秒単位で取得する。

構文

HRESULT get_AvgTimePerFrame(
    REFTIME *pAvgTimePerFrame
);

パラメータ

pAvgTimePerFrame
[out] フレーム間の時間へのポインタ。

戻り値

HRESULT 値を返す。

IBasicVideo::get_BitErrorRate

IBasicVideo インターフェイス

ビデオ ストリームのビット エラー レートを取得する (ほぼこのビット数に対して 1 つのエラー)。

構文

HRESULT get_BitErrorRate(
    long *pBitErrorRate
);

パラメータ

pBitErrorRate
[out] およそのビット エラー レートへのポインタ。

戻り値

HRESULT 値を返す。

IBasicVideo::get_BitRate

IBasicVideo インターフェイス

ビデオ ストリームのおよそのビット レート (ビット/秒単位) を取得する。

構文

HRESULT get_BitRate(
    long *pBitRate
);

パラメータ

pBitRate
[out] およそのビット レートへのポインタ。

戻り値

HRESULT 値を返す。

IBasicVideo::GetCurrentImage

IBasicVideo インターフェイス

レンダラで待機している現在のイメージを取得する。

構文

HRESULT GetCurrentImage(
    long *pBufferSize,
    long *pDIBImage
);

パラメータ

pBufferSize
[in, out] 呼び出し元が渡しているバッファ サイズへのポインタ。
pDIBImage
[out] イメージ全体がデバイスに依存しないビットマップ (DIB) フォーマットで格納されるバッファへのポインタ。このバッファはこの関数で使用できるように long 型のポインタにキャストされる必要がある。

戻り値

HRESULT 値を返す。

注意

このメソッドは、レンダラで DirectDraw アクセラレーションが使用されていると失敗する。失敗するかどうかはエンドユーザーのハードウェア構成に依存するため、実際にはこのメソッドを信頼することはできない。グラフ内のストリームからサンプルを取得する場合は、ISampleGrabber インターフェイスを使用する方がよい。

このメソッドを呼び出す前にビデオ レンダラをポーズする。ポーズしていないと、VFW_E_NOT_PAUSED が返される。ImediaCOntrol::GetState を呼び出すことによって完了することに注意すること。ポーズ操作が終了していないと、 GetCurrentImage の呼び出しは E_UNEXPECTED を返す。 ソース フィルタで利用可能になるデータによっては、ビデオ レンダラがこの要求に応じない場合もある。利用可能なイメージがない場合は、E_FAIL が返される。

イメージ ポインタを NULL にしてこのメソッドを呼び出すことで、イメージの保持に必要なバッファのサイズを取得する。この場合、バッファ サイズには必要なバイト数が返される。バッファ サイズ ポインタは必ず有効である必要がある。アプリケーションがこのメソッドを呼び出したときに、バッファ サイズが小さすぎてイメージ全体を保持できないと、レンダラは E_OUTOFMEMORY を返す。

このメソッドが成功すると、出力イメージ ポインタに DIB イメージ全体が格納される。これには、Microsoft Win32 BITMAPINFOHEADER 構造体、必要な任意のパレット、 および Win32 BITMAPINFO 構造体で定義されているビット マスクも含まれる。返されるイメージのフォーマットはソース フィルタが提供するタイプに応じて異なり、あらかじめ明示的に定義することはできない。通常、イメージは 24 ビット、16 ビット、または 8 ビットのパレット化されたイメージになる。

IBasicVideo::get_DestinationHeight

IBasicVideo インターフェイス

転送先矩形の高さを取得する。

構文

HRESULT get_DestinationHeight(
    long *pDestinationHeight
);

パラメータ

pDestinationHeight
[out] 現在の高さへのポインタ (ピクセル単位)。

戻り値

HRESULT 値を返す。

IBasicVideo::get_DestinationLeft

IBasicVideo インターフェイス

転送先矩形の x 軸の基点の座標を取得する。

構文

HRESULT get_DestinationLeft(
    long *pDestinationLeft
);

パラメータ

pDestinationLeft
[out] 現在の x 軸の基点へのポインタ。

戻り値

HRESULT 値を返す。

IBasicVideo::GetDestinationPosition

IBasicVideo インターフェイス

ウィンドウ座標内の転送先矩形の位置を取得する。

構文

HRESULT GetDestinationPosition(
    long *pLeft,
    long *pTop,
    long *pWidth,
    long *pHeight
);

パラメータ

pLeft
[out] 転送先ウィンドウの x 軸の基点へのポインタ。
pTop
[out] 転送先ウィンドウの y 軸の基点へのポインタ。
pWidth
[out] 転送先ウィンドウの幅へのポインタ (ピクセル単位)。
pHeight
[out] 転送先ウィンドウの高さへのポインタ (ピクセル単位)。

戻り値

HRESULT 値を返す。

注意

このメソッドを使用すると、IBasicVideo::get_DestinationLeft、IBasicVideo::get_DestinationTop、IBasicVideo::get_DestinationWidth、および IBasicVideo::get_DestinationHeight の各メソッドを個別に呼び出した場合と同じ結果が得られる。

IBasicVideo::get_DestinationTop

IBasicVideo インターフェイス

転送先の y 軸の基点の座標を取得する。

構文

HRESULT get_DestinationTop(
    long *pDestinationTop
);

パラメータ

pDestinationTop
[out] 現在の y 軸の基点へのポインタ。

戻り値

HRESULT 値を返す。

IBasicVideo::get_DestinationWidth

IBasicVideo インターフェイス

転送先矩形の幅を取得する。

構文

HRESULT get_DestinationWidth(
    long *pDestinationWidth
);

パラメータ

pDestinationWidth
[out] 現在の幅へのポインタ (ピクセル単位)。

戻り値

HRESULT 値を返す。

IBasicVideo::get_SourceHeight

IBasicVideo インターフェイス

転送元矩形の高さを取得する。

構文

HRESULT get_SourceHeight(
    long *pSourceHeight
);

パラメータ

pSourceHeight
[out] 現在の矩形の高さへのポインタ (ピクセル単位)。

戻り値

HRESULT 値を返す。

IBasicVideo::get_SourceLeft

IBasicVideo インターフェイス

転送元矩形の x 軸の座標を取得する。

構文

HRESULT get_SourceLeft(
    long *pSourceLeft
);

パラメータ

pSourceLeft
[out] 転送元矩形の x 軸の基点へのポインタ。

戻り値

HRESULT 値を返す。

IBasicVideo::GetSourcePosition

IBasicVideo インターフェイス

利用可能なビデオにクリップされる転送元矩形の位置を取得する。

構文

HRESULT GetSourcePosition(
    long *pLeft,
    long *pTop,
    long *pWidth,
    long *pHeight
);

パラメータ

pLeft
[out] 転送元ウィンドウの x 軸の基点へのポインタ。
pTop
[out] 転送元ウィンドウの y 軸の基点へのポインタ。
pWidth
[out] 転送元ウィンドウの幅へのポインタ (ピクセル単位)。
pHeight
[out] 転送元ウィンドウの高さへのポインタ (ピクセル単位)。

戻り値

HRESULT 値を返す。

注意

このメソッドを使用すると、IBasicVideo::get_SourceLeft、IBasicVideo::get_SourceTop、IBasicVideo::get_SourceWidth、および IBasicVideo::get_SourceHeight の各メソッドを個別に呼び出した場合と同じ結果が得られる。

IBasicVideo::get_SourceTop

IBasicVideo インターフェイス

転送元矩形の y 軸の基点の座標を取得する。

構文

HRESULT get_SourceTop(
    long *pSourceTop
);

パラメータ

pSourceTop
[out] 新しいトップ座標へのポインタ。

戻り値

HRESULT 値を返す。

注意

このメソッドを設定しても、転送元矩形の高さには影響を与えない。

IBasicVideo::get_SourceWidth

IBasicVideo インターフェイス

転送元矩形の幅を取得する。

構文

HRESULT get_SourceWidth(
    long *pSourceWidth
);

パラメータ

pSourceWidth
[out] 現在の幅へのポインタ (ピクセル単位)。

戻り値

HRESULT 値を返す。

注意

このメソッドは、転送元矩形の x 軸の座標に影響を与えない。

IBasicVideo::get_VideoHeight

IBasicVideo インターフェイス

現在のビデオの高さを取得する。

構文

HRESULT get_VideoHeight(
    long *pVideoHeight
);

パラメータ

pVideoHeight
[out] ビデオのネイティブの高さへのポインタ (ピクセル単位)。

戻り値

HRESULT 値を返す。

注意

このメソッドは、レンダラに供給されるビデオの実際の高さを返す。このメソッドは設定された転送元矩形を対象としておらず、単純にネイティブの垂直ディメンジョンを返す。アプリケーションはこのメソッドを使用して埋め込みコンテナ ドキュメントとの間でサイズ要件をネゴシエートできる。

IBasicVideo::GetVideoPaletteEntries

IBasicVideo インターフェイス

ビデオのパレットの色を取得する。

構文

HRESULT GetVideoPaletteEntries(
    long StartIndex,
    long Entries,
    long *pRetrieved,
    long *pPalette
);

パラメータ

StartIndex
[in] パレットの開始インデックス。
Entries
[in] 必要なパレット エントリの数。
pRetrieved
[out] 実際に返されるエントリの数へのポインタ。
pPalette
[out] Microsoft Win32 PALETTEENTRY 構造体の配列へのポインタ。

戻り値

HRESULT 値を返す。

注意

アプリケーションは、このメソッドを使用して、ビデオで必要となる色数を照会できる。アプリケーションは NULL の pPalette パラメータを渡すことができ、pRetrieved パラメータには使用されている色の数が返される。pPalette パラメータは、PALETTEENTRY 構造体の配列へのポインタである。StartIndex パラメータおよび Entries パラメータを使用すると、アプリケーションは 1 つのメソッドでパレットの連続しているセクションを要求できる。このインターフェイスは、Win32 GetSystemPaletteEntries 関数でモデル化されている。

IBasicVideo::GetVideoSize

IBasicVideo インターフェイス

ネイティブ ビデオのディメンジョンを取得する。

構文

HRESULT GetVideoSize(
    long *pWidth,
    long *pHeight
);

パラメータ

pWidth
[out] ビデオ ウィンドウの幅へのポインタ (ピクセル単位)。
pHeight
[out] ビデオ ウィンドウの高さへのポインタ (ピクセル単位)。

戻り値

HRESULT 値を返す。

注意

このメソッドは、設定されている可能性のある転送元矩形を無視して、ネイティブなビデオの幅および高さを取得する。Microsoft® ActiveX® コントロールまたはその他のアプリケーションは、この情報を使用して複合ドキュメント内の領域をネゴシエートできる。

IBasicVideo::get_VideoWidth

IBasicVideo インターフェイス

現在のビデオの幅を取得する。

構文

HRESULT get_VideoWidth(
    long *pVideoWidth
);

パラメータ

pVideoWidth
[out] ビデオのネイティブの幅へのポインタ (ピクセル単位)。

戻り値

HRESULT 値を返す。

注意

このメソッドは、レンダラに供給されるビデオの実際の幅を返す。このメソッドは設定された転送元矩形を対象としておらず、単純にネイティブの水平ディメンジョンを返す。アプリケーションはこのメソッドを使用して埋め込み ActiveX ドキュメントとの間でサイズ要件をネゴシエートできる。

IBasicVideo::IsUsingDefaultDestination

IBasicVideo インターフェイス

レンダラがデフォルトの転送先矩形を使用しているかどうかを判別する。

構文

HRESULT IsUsingDefaultDestination(void);

戻り値

HRESULT 値を返す。デフォルトの転送先矩形が使用されている場合は S_OK、それ以外の場合は S_FALSE を返す。

注意

フィルタに転送先矩形のデフォルト設定を使用するように指示する場合に、IBasicVideo::SetDefaultDestinationPosition メソッドを使用できる。IsUsingDefaultDestination メソッドは、その設定が使用されているかどうかを返す。

IBasicVideo::IsUsingDefaultSource

IBasicVideo インターフェイス

レンダラがデフォルトの転送元矩形を使用しているかどうかを判別する。

構文

HRESULT IsUsingDefaultSource(void);

戻り値

HRESULT 値を返す。デフォルトの転送元矩形が使用されている場合は S_OK、それ以外の場合は S_FALSE を返す。

注意

フィルタに転送元矩形のデフォルト設定を使用するように指示する場合に、IBasicVideo::SetDefaultSourcePosition メソッドを使用できる。IsUsingDefaultSource メソッドはその設定が使用されているかどうかを返す。

IBasicVideo::put_DestinationHeight

IBasicVideo インターフェイス

転送先矩形の高さを設定する。

構文

HRESULT put_DestinationHeight(
    long DestinationHeight
);

パラメータ

DestinationHeight
[in] 新しい高さ (ピクセル単位)。

戻り値

HRESULT 値を返す。

注意

この座標を設定しても、転送先矩形の y 軸の基点には影響を与えない。

IBasicVideo::put_DestinationLeft

IBasicVideo インターフェイス

転送先の x 軸の基点の座標を設定する。

構文

HRESULT put_DestinationLeft(
    long DestinationLeft
);

パラメータ

DestinationLeft
[in] 新しい x 軸の基点。

戻り値

HRESULT 値を返す。

注意

この座標を設定しても、転送先矩形の幅には影響を与えない。

IBasicVideo::put_DestinationTop

IBasicVideo インターフェイス

転送先の y 軸の基点の座標を設定する。

構文

HRESULT put_DestinationTop(
    long DestinationTop
);

パラメータ

DestinationTop
[in] 新しい y 軸の基点。

戻り値

HRESULT 値を返す。

注意

この座標を設定しても、転送先矩形の高さには影響を与えない。

IBasicVideo::put_DestinationWidth

IBasicVideo インターフェイス

転送先矩形の幅を設定する。

構文

HRESULT put_DestinationWidth(
    long DestinationWidth
);

パラメータ

DestinationWidth
[in] 新しい幅 (ピクセル単位)。

戻り値

HRESULT 値を返す。

注意

この座標を設定しても、転送先矩形の x 軸の基点には影響を与えない。

IBasicVideo::put_SourceHeight

IBasicVideo インターフェイス

転送元矩形の高さを設定する。

構文

HRESULT put_SourceHeight(
    long SourceHeight
);

パラメータ

SourceHeight
[in] 新しい矩形の高さ (ピクセル単位)。

戻り値

HRESULT 値を返す。

注意

転送元矩形の高さを設定しても、転送元の y 軸の座標には影響を与えない。

IBasicVideo::put_SourceLeft

IBasicVideo インターフェイス

転送元矩形の x 軸の座標を設定する。

構文

HRESULT put_SourceLeft(
    long SourceLeft
);

パラメータ

SourceLeft
[in] 転送元矩形の x 軸の基点。

戻り値

HRESULT 値を返す。

注意

このメソッドを設定しても、転送元矩形の幅には影響を与えない。

IBasicVideo::put_SourceTop

IBasicVideo インターフェイス

転送元矩形の y 軸の基点の座標を設定する。

構文

HRESULT put_SourceTop(
    long SourceTop
);

パラメータ

SourceTop
[in] 新しいトップ座標。

戻り値

HRESULT 値を返す。

注意

このメソッドを設定しても、転送元矩形の高さには影響を与えない。

IBasicVideo::put_SourceWidth

IBasicVideo インターフェイス

転送元矩形の幅を設定する。

構文

HRESULT put_SourceWidth(
    long SourceWidth
);

パラメータ

SourceWidth
[in] 転送元矩形の新しい幅 (ピクセル単位)。

戻り値

HRESULT 値を返す。

注意

このメソッドを設定しても、転送元矩形の x 軸の座標には影響を与えない。

IBasicVideo::SetDefaultDestinationPosition

IBasicVideo インターフェイス

レンダラが再生にウィンドウ全体を使用するように、ビデオ ウィンドウのデフォルトの転送先位置を設定する。

構文

HRESULT SetDefaultDestinationPosition(void);

戻り値

HRESULT 値を返す。

IBasicVideo::SetDefaultSourcePosition

IBasicVideo インターフェイス

デフォルトの転送元矩形を使用するようにレンダラに指示する。

構文

HRESULT SetDefaultSourcePosition(void);

戻り値

HRESULT 値を返す。

IBasicVideo::SetDestinationPosition

IBasicVideo インターフェイス

ウィンドウ座標内での転送先矩形の位置を設定する。

構文

HRESULT SetDestinationPosition(
    long Left,
    long Top,
    long Width,
    long Height
);

パラメータ

Left
[in] 転送先ウィンドウの x 軸の基点。
Top
[in] 転送先ウィンドウの y 軸の基点。
Width
[in] 転送先ウィンドウの幅 (ピクセル単位)。
Height
[in] 転送先ウィンドウの高さ (ピクセル単位)。

戻り値

HRESULT 値を返す。

注意

このメソッドを使用すると、IBasicVideo::put_DestinationLeft、IBasicVideo::put_DestinationTop、IBasicVideo::put_DestinationWidth、および IBasicVideo::put_DestinationHeight の各メソッドを個別に呼び出した場合と同じ結果が得られる。

IBasicVideo::SetSourcePosition

IBasicVideo インターフェイス

利用可能なビデオにクリップされる転送元矩形を設定する。

構文

HRESULT SetSourcePosition(
    long Left,
    long Top,
    long Width,
    long Height
);

パラメータ

Left
[in] 転送元ウィンドウの x 軸の基点。
Top
[in] 転送元ウィンドウの y 軸の基点。
Width
[in] 転送元ウィンドウの幅 (ピクセル単位)。
Height
[in] 転送元ウィンドウの高さ (ピクセル単位)。

戻り値

HRESULT 値を返す。

注意

このメソッドを使用すると、IBasicVideo::put_SourceLeft、IBasicVideo::put_SourceTop、IBasicVideo::put_SourceWidth、および IBasicVideo::put_SourceHeight の各メソッドを個別に呼び出した場合と同じ結果が得られる。

この座標を設定しても、転送先矩形の高さには影響を与えない。


IBasicVideo2 インターフェイス

IBasicVideo2 インターフェイスは、IBasicVideo から派生したインターフェイスで、ビデオ ストリームのアスペクト比を取得する別の方法をアプリケーションに提供する。このインターフェイスは ビデオ レンダラ フィルタで実装されるが、フィルタ グラフ マネージャでアプリケーションに公開される。詳細については、「IBasicVideo」を参照すること。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IDispatch メソッド | 説明
GetTypeInfoCount | このディスプインターフェイスに利用可能なタイプ情報があるかどうか判断する。
GetTypeInfo | GetTypeInfoCount が成功した場合は、このディスプインターフェイスのタイプ情報を取得する。
GetIDsOfNames | (引数を含む) プロパティおよびメソッドのテキスト名を対応する DISPID に変換する。
Invoke | DISPID およびその他の必要なパラメータが指定された場合は、このディスプインターフェイスのメソッドを呼び出すか、またはプロパティにアクセスする。
IBasicVideo メソッド | 説明
get_AvgTimePerFrame | 連続するフレーム間の平均時間を 100 ナノ秒単位で取得する。
get_BitRate | ビデオ ストリームのおよそのビット レートを取得する。
get_BitErrorRate | ビデオ ストリームのおよそのビット エラー レートを取得する。
get_VideoWidth | 現在のビデオの幅を取得する。
get_VideoHeight | 現在のビデオの高さを取得する。
put_SourceLeft | ビデオの転送元矩形の x 軸の座標を設定する。
get_SourceLeft | ビデオの転送元矩形の x 軸の座標を取得する。
put_SourceWidth | ビデオの転送元矩形の幅を設定する。
get_SourceWidth | ビデオの転送元矩形の幅を取得する。
put_SourceTop | ビデオの転送元矩形の y 軸の座標を設定する。
get_SourceTop | ビデオの転送元矩形の y 軸の座標を取得する。
put_SourceHeight | ビデオの転送元矩形の高さを設定する。
get_SourceHeight | ビデオの転送元矩形の高さを取得する。
put_DestinationLeft | ビデオの転送先矩形の x 軸の座標を設定する。
get_DestinationLeft | ビデオの転送先矩形の x 軸の座標を取得する。
put_DestinationWidth | ビデオの転送先矩形の幅を設定する。
get_DestinationWidth | ビデオの転送先矩形の幅を取得する。
put_DestinationTop | ビデオの転送先矩形の y 軸の座標を設定する。
get_DestinationTop | ビデオの転送先矩形の y 軸の座標を取得する。
put_DestinationHeight | ビデオの転送先矩形の高さを設定する。
get_DestinationHeight | ビデオの転送先矩形の高さを取得する。
SetSourcePosition | ビデオの転送元矩形を設定する。
GetSourcePosition | ビデオの転送元矩形を取得する。
SetDefaultSourcePosition | デフォルトの転送元矩形を使用するようにレンダラに指示する。
SetDestinationPosition | ウィンドウに対する転送先矩形を設定する。
GetDestinationPosition | ウィンドウに対するビデオの転送先矩形を取得する。
SetDefaultDestinationPosition | ウィンドウに対するデフォルトの転送先位置を設定する。
GetVideoSize | ネイティブ ビデオのディメンジョンを取得する。
GetVideoPaletteEntries | ビデオで必要とされるカラー パレットのエントリを取得する。
GetCurrentImage | レンダラで待機している現在のイメージのコピーを返す。
IsUsingDefaultSource | レンダラがデフォルトの転送元矩形を使用しているかどうかを判別する。
IsUsingDefaultDestination | レンダラがデフォルトの転送先矩形を使用しているかどうかを判別する。
IBasicVideo2 メソッド | 説明
GetPreferredAspectRatio | ムービーのアスペクト比を取得する。

IBasicVideo2::GetPreferredAspectRatio

IBasicVideo2 インターフェイス

ムービーのアスペクト比を定義する比率を示す、ディメンジョンが含まれていない 1 組の値を取得する。

構文

HRESULT GetPreferredAspectRatio (
    long *plAspectX,
    long *plAspectY
    );

パラメータ

plAspectX
[out] ムービーの x 軸のアスペクト比を示す値へのポインタ。
plAspectY
[out] ムービーの y 軸のアスペクト比を示す値へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

現在の DirectShow の実装での戻り値は次のとおりである。
S_OK | 成功。
E_INVALIDARG | 一方または両方のパラメータが無効。
E_NOINTERFACE | レンダラで IBasicVideo2 が実装されていない。

注意

ムービーのアスペクト比の詳細については、VIDEOINFOHEADER2 構造体のドキュメントを参照すること。


ICaptureGraphBuilder2 インターフェイス

このインターフェイスは、キャプチャ グラフ、プレビュー グラフ、ファイル再圧縮グラフを作成するためのメソッドを備えている。キャプチャ グラフ ビルダがこのインターフェイスを実装する。

このインターフェイスは、ICaptureGraphBuilder インターフェイスを置き換えるものである。このインターフェイスでは、オーディオとビデオの両方など、複数のメディアをキャプチャできる Microsoft® Windows® Driver Model (WDM) キャプチャ ドライバを使用できる。従来の ICaptureGraphBuilder インターフェイスでは、ビデオとオーディオの両方のキャプチャに同じドライバを使用するデバイスは使用できない。

このインターフェイスの使い方の詳細については、「キャプチャ アプリケーションの書き方」および「AVI ファイルの再圧縮」を参照すること。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
ICaptureGraphBuilder2 メソッド | 説明
SetFiltergraph | キャプチャ グラフ ビルダが使用するフィルタ グラフを指定する。
GetFiltergraph | ビルダが使用しているフィルタ グラフを取得する。
SetOutputFileName | フィルタ グラフのファイル ライティング セクションを作成する。
FindInterface | 指定されたフィルタから始めて、指定されたインターフェイスをグラフ内で検索する。
RenderStream | ソース フィルタの出力ピンを、オプションで圧縮フィルタを経由して、レンダリング フィルタに接続する。
ControlStream | キャプチャされたデータの 1 つ以上のストリームの開始タイムと終了タイムを設定する。
AllocCapFile | キャプチャ ファイルを指定されたサイズにあらかじめ割り当てる。
CopyCaptureFile | キャプチャ ファイルから有効なメディア データをコピーする。
FindPin | フィルタの特定のピンを取得するか、特定のピンが指定された条件に適合するかどうかを判別する。

ICaptureGraphBuilder2::AllocCapFile

ICaptureGraphBuilder2 インターフェイス

キャプチャ ファイルを指定されたサイズにあらかじめ割り当てる。最良の結果を得るには、常に、キャプチャ データよりサイズが大きく、最適化され、あらかじめ割り当てられたキャプチャ ファイルにキャプチャする。

構文

HRESULT AllocCapFile(
    LPCOLESTR lpwstr,
    DWORDLONG dwlSize
);

パラメータ

lpwstr
[in] 作成またはサイズを変更するファイルの名前が格納された Unicode™ 文字列へのポインタ。
dwlSize
[in] 割り当てるファイルのサイズ (バイト単位)。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、エラーの原因を示す HRESULT 値を返す。

注意

ファイルが読み取り専用の場合、このメソッドは失敗する。

理想的には必要以上に大きな可能な限りのスペースを割り当てることが最も望ましい。しかしこれは比較的小さなデータをもつ非常に大きなファイルを作成することになる。たとえば、1ギガバイト(GB)キャプ チャファイルに数メガバイトのキャプチャ ビデオが入る場合もある。CopyCaptureFile メソッドを使って新しいファイルにデータをコピーすること。このメソッドはデータだけをコピーし、オリジナルファイルの空き部分は無視する。

注 : AllocCapFile メソッドは、あらかじめ割り当てられたファイル全体にわたって書き込む必要があるため、Microsoft® Windows NT® 4.x プラットフォーム上または Microsoft® Windows® 2000 プラットフォーム上では、Windows 9x プラットフォーム上より動作が遅くなる。ただし、それでもこのメソッドはキャプチャのパフォーマンスが高いため、このメソッドを使用することが推奨されている。

ICaptureGraphBuilder2::ControlStream

ICaptureGraphBuilder2 インターフェイス

キャプチャされたデータの 1 つ以上のストリームの開始タイムと終了タイムを設定する。

このメソッドは、メソッドの呼び出しで指定された検索条件を使って、キャプチャ フィルタ上の出力ピンを検索する。次に、これらのピンに対して IAMStreamControl メソッドを呼び出す。このメソッドを利用すると、アプリケーションは、グラフ内のフィルタやピンを列挙せずに、ストリームを制御できる。

このメソッドは、フレーム単位の精度が要求されるキャプチャや、個別のキャプチャ動作およびプレビュー動作の制御に使用する。たとえば、ビデオのプレビューを中断せずに、ディスクへのキャプチャを停止することができる。

構文

HRESULT ControlStream(
    const GUID *pCategory,
    const GUID *pType,
    IBaseFilter *pFilter,
    REFERENCE_TIME *pstart,
    REFERENCE_TIME *pstop,
    WORD wStartCookie,
    WORD wStopCookie
);

パラメータ

pCategory
[in] ピン カテゴリを指定する AMPROPERTY_PIN_CATEGORY プロパティ セットのメンバへのポインタ。このパラメータの値を NULL にすることはできない。
pType
[in] メディア タイプを指定するメジャー タイプ GUID へのポインタまたは NULL。このパラメータが NULL の場合は、pFilter パラメータも NULL に設定する。そうしないと、間違ったピンが制御され、予期しない結果が生じることがある。
pFilter
[in] 制御するフィルタを指定する IBaseFilter インターフェイスへのポインタ。グラフ内のすべてのキャプチャ フィルタを制御するには、このパラメータを NULL に設定する。
pstart
[in] 開始タイムが格納された変数へのポインタ。直ちに開始するには、値を NULL に設定する。前の開始要求をキャンセルするには、値を MAX_TIME に設定する。前の要求がない場合、値 を MAX_TIME にすることには何の効果もない。
pstop
[in] 終了タイムが格納された変数へのポインタ。直ちに終了するには、値を NULL に設定する。前の終了要求をキャンセルするには、値を MAX_TIME に設定する。前の要求がない場合、値 を MAX_TIME にすることには何の効果もない。
wStartCookie
[in] EC_STREAM_CONTROL_STARTED イベント通知の第 2 パラメータとして送られる値。詳細については、「注意」を参照すること。
wStopCookie
[in] EC_STREAM_CONTROL_STOPPED イベント通知の第 2 パラメータとして送られる値。詳細については、「注意」を参照すること。

戻り値

HRESULT 値を返す。設定される値は次のとおりである。

S_FALSE | 少なくとも 1 つのダウンストリーム レンダラが終了通知を送らない。
S_OK | 成功。
E_FAIL | 適合するピンが見つからない、またはピンがストリーム コントロールをサポートしていない。
E_POINTER | NULL ポインタ引数。

注意

最初の 3 つのパラメータは、制御するピンを指定する。キャプチャ グラフは、複数のキャプチャ フィルタを備えていることがある。たとえば、キャプチャ グラフは、ビデオ用のフィルタ、オーディオ用のフィルタ、クローズド キャプション データ用のフィルタを備えていることがある。また、キャプチャ フィルタは、複数の出力ピンを備えていることがある。一部のキャプチャ フィルタは、プレビュー用とキャプチャ用の別々のピンを備えていたり、ビデオ専用データ用とオーディオ-ビデオ インターリーブ データ用の別々のピンを備えていることがある。たとえば、ビデオ プレビューを制御するには、pCategory として PIN_CATEGORY_PREVIEW を指定し、pType として MEDIATYPE_Video を指定する。

ピンを制御するとき、このメソッドは IAMStreamControl::StartAt メソッドと IAMStreamControl::StopAt メソッドを呼び出す。各ピンは、開始時に EC_STREAM_CONTROL_STARTED イベント通知を送る。イベント通知の第 2 パラメータは、wStartCookie が示す値である。ピンは停止すると、EC_STREAM_CONTROL_STOPPED イベント通知を送る。このイベント通知の第 2 パラメータは、wStopCookie が示す値である。

このメソッドは、適合するピンを見つけると、ダウンストリームで、IAMStreamControl (通常はマルチプレクサ) をサポートする別のフィルタを検索する。フィルタが見つかると、このメソッドは、そのフィルタの開始タイムと終了タイムを設定する。これによって、キャプチャ フィルタ用とダウンストリーム フィルタ用の 2 つの終了通知のペアが生成される。ダウンストリーム フィルタからの終了通知のみが wStopCookie パラメータを使用する。このイベントを待機することにより、ダウンストリーム フィルタが最後のサンプルを受け取ることが保証される。

IAMStreamControl をサポートするダウンストリーム フィルタがない場合、メソッドは S_FALSE を返す。その場合は、最後のサンプルがレンダリングされる前に終了通知を受け取ることがある。

ICaptureGraphBuilder2::CopyCaptureFile

ICaptureGraphBuilder2 インターフェイス

キャプチャ ファイルから有効なメディア データをコピーする。

通常は、まずあらかじめ割り当てられた大きいファイルにキャプチャする。このメソッドは新しいファイルに有効なメディア データのみをコピーする。結果的に新しいファイルはコピー元ファイルよりずっと小さくなる。

構文

HRESULT CopyCaptureFile(
    LPOLESTR lpwstrOld,
    LPOLESTR lpwstrNew,
    int fAllowEscAbort,
    IAMCopyCaptureFileProgress *pCallback
);

パラメータ

lpwstrOld
[in] コピー元ファイル名が格納された Unicode™ 文字列へのポインタ。
lpwstrNew
[in] コピー先ファイル名が格納された Unicode™ 文字列へのポインタ。このファイルに有効なデータがコピーされる。
fAllowEscAbort
[in] Esc キーを押すとコピー操作が中断されるかどうかを示すブール型の値。値が TRUE の場合は、ユーザーが Esc キーを押すとコピー操作が中断される。値が FALSE の場合、メソッドは Esc キー操作を無視する。
pCallback
[in] 進行状況を表示する IAMCopyCaptureFileProgress インターフェイスへのポインタまたは NULL。詳細については、「注意」を参照すること。

戻り値

HRESULT 値を返す。設定される値は次のとおりである。

S_FALSE | 操作が完了する前にユーザーが操作をキャンセルした。
S_OK | 成功。
E_FAIL | 失敗。
E_INVALIDARG | コピー元ファイルまたはコピー先ファイルが開けない。
E_OUTOFMEMORY | メモリ不足。
E_POINTER | NULL ポインタ引数。

注意

コピー元ファイルとコピー先ファイルは AVI ファイルでなければならない。他のファイルタイプはサポートされていない。

コピー操作の進行状況を表示するには、IAMCopyCaptureFileProgress インターフェイスを実装し、pCallback パラメータを使ってポインタをインターフェイスに渡す。pCallback が NULL でない場合、このメソッドは、パーセント単位の達成率を示す 0 から 100 の間の整数を指定して、定期的に IAMCopyCaptureFileProgress::Progress メソッドを呼び出す。

ICaptureGraphBuilder2::FindInterface

ICaptureGraphBuilder2 インターフェイス

指定されたフィルタから始めて、指定されたインターフェイスをグラフ内で検索する。検索をフィルタのアップストリームまたはダウンストリームのグラフのセクションに限定したり、特定のピン カテゴリまたはメディア タイプに限定したりすることができる。

構文

HRESULT FindInterface(
    const GUID *pCategory,
    const GUID *pType,
    IBaseFilter *pf,
    REFIID riid,
    void **ppint
);

パラメータ

pCategory
[in] 検索条件を指定する GUID へのポインタ。詳細については、「注意」を参照すること。指定できる値は次のとおりである。
  • LOOK_UPSTREAM_ONLY
  • LOOK_DOWNSTREAM_ONLY
  • ピン カテゴリを指定する AMPROPERTY_PIN_CATEGORY プロパティ セットのメンバ。
  • NULL
pType
[in] 出力ピンのメディア タイプを指定するメジャー タイプ GUID へのポインタまたは NULL。
pf
[in] フィルタの IBaseFilter インターフェイスへのポインタ。
riid
[in] インターフェイスの参照識別子 (ID)。
ppint
[out] インターフェイス ポインタを受け取る変数のアドレス。インターフェイスを使用した後は、取得したインターフェイス ポインタを必ず解放すること。

戻り値

HRESULT 値を返す。設定される値は次のとおりである。

S_OK | 成功。
E_FAIL | 失敗。
E_NOINTERFACE | そのインターフェイスはサポートされていない。
E_POINTER | NULL ポインタ引数。

注意

キャプチャ グラフでは、さまざまなフィルタおよびピンが、圧縮パラメータ (IAMVideoCompression) やストリーム フォーマット (IAMStreamConfig) などのプロパティを設定するインターフェイスを公開する可能性がある。キャプチャ デバイスによっては、アナログ信号のルーティングを行う IAMCrossbar や、TV チューナー デバイスを制御する IAMTVTuner など、ほかの有用なインターフェイスも使われる。このメソッドを使えば、グラフを対象に検索を行うための特殊なコードを書かなくても、インターフェイスを検索できる。

重要 : IVideoWindow インターフェイス ポインタを取得するときは、このメソッドを呼び出さずに、必ずフィルタ グラフ マネージャにこのインターフェイスを問い合わせる。そうしないと、フィルタ グラフ マネージャは、画面解像度およびその他のイベントに正しく反応しなくなる。

pCategory パラメータが NULL である場合、このメソッドは、グラフ全体を対象として要求されたインターフェイスを検索する。このメソッドは、pf パラメータによって指定されたフィルタから始めて、グラフ内で次のオブジェクトを検索する。

  • フィルタ
  • フィルタのピン
  • フィルタのピンを含むすべてのダウンストリーム フィルタ
  • フィルタのピンを含むすべてのアップストリーム フィルタ

pCategory パラメータと pType パラメータを設定することにより、検索を限定できる。

  • pCategory が &LOOK_UPSTREAM_ONLY である場合、検索はフィルタの入力ピンから始まって、アップストリーム方向に継続する。フィルタ自体やフィルタのダウンストリームにあるものは検索の対象にならない。pType パラメータは無視される。
  • pCategory が &LOOK_DOWNSTREAM_ONLY である場合、検索はフィルタの出力ピンから始まって、ダウンストリーム方向に継続する。フィルタ自体やフィルタのアップストリームにあるものは検索の対象にならない。pType パラメータは無視される。
  • pCategory がピン カテゴリを指定している場合、検索のダウンストリームの部分は、ピン カテゴリと pType パラメータによって指定されるメディア タイプの両方が一致するフィルタの出力ピンに限定される。その場合、メソッドは、フィルタおよびフィルタのアップストリームにあるすべてのものも検索する。

ピン カテゴリは、キャプチャ フィルタのピン インターフェイスを検索するときに役立つ。たとえば、キャプチャ フィルタは、キャプチャ用とプレビュー用の別々のピンを備えていることがある。ピン カテゴリを指定する場合は、メソッドが正しいフィルタとピンを選択できるように、メディア タイプも指定する必要がある。

一部のビデオ キャプチャ フィルタは、プレビュー ピンの代わりにビデオ ポート ピン (PIN_CATEGORY_VIDEOPORT) を備えている。PIN_CATEGORY_PREVIE と MEDIATYPE_Video を指定すると、メソッドは、すべてのビデオ ポート ピンをプレビュー ピンとして扱う。アプリケーションでこの可能性をテストする必要はない。

サポートするフィルタ。キャプチャ デバイスが Windows Driver Model (WDM) ドライバを使用する場合、グラフは、TV チューナー フィルタやアナログ ビデオ クロスバー フィルタなど、WDM ビデオ キャプチャ フィルタのアップストリームにある特定のフィルタを必要とすることがある。グラフがこれらの WDM フィルタのいずれかを必要とする場合、このメソッドは自動的にそれらのフィルタをグラフに挿入する。メソッドは、キャプチャ フィルタの入力ピンに問い合わせて、入力ピンがサポートするメディアを判別し、それらのメディアを適合するフィルタに接続する。

ICaptureGraphBuilder2::FindPin

ICaptureGraphBuilder2 インターフェイス

フィルタの特定のピンを取得するか、特定のピンが指定された条件に適合するかどうかを判別する。

構文

HRESULT FindPin(
    IUnknown *pSource,
    PIN_DIRECTION pindir,
    const GUID *pCategory,
    const GUID *pType,
    BOOL fUnconnected,
    int num,
    IPin **ppPin
);

パラメータ

pSource
[in] フィルタのインターフェイスへのポインタまたはピンのインターフェイスへのポインタ。
pindir
[in] ピンの方向 (入力または出力) を指定する PIN_DIRECTION 列挙のメンバ。
pCategory
[in] ピン カテゴリを指定する AMPROPERTY_PIN_CATEGORY プロパティ セットのメンバ。すべてのカテゴリが適合する場合は NULL を使用する。
pType
[in] メディア タイプを指定するメジャー タイプ GUID へのポインタ。すべてのメディアが適合する場合は NULL を使用する。
fUnconnected
[in] ピンの接続が外れている必要があるかどうかを指定するブール型の値。TRUE の場合、ピンの接続は外れている必要がある。FALSE の場合は、ピンが接続されていても、接続されていなくてもよい。
num
[in] 適合するピンのセットから取得するピンの、開始値をゼロとするインデックス。pSource がフィルタへのポインタで、複数のピンが検索条件に適合する場合は、このパラメータで取得するピンを指定する。pSource がピンへのポインタである場合、このパラメータは無視される。
ppPin
[out] 適合するピンの IPin インターフェイスを受け取るポインタのアドレス。

戻り値

適合するピンが見つかった場合は S_OK、それ以外の場合は E_FAIL を返す。

注意

pSource がフィルタへのポインタである場合、メソッドは、そのフィルタ上で検索条件に適合する n 番目のピンを検索する。n は num パラメータによって指定される。メソッドは、適合するピンを見つけると、ppPin パラメータによってピンへのポインタを返す。

pSource がピンへのポインタである場合、メソッドは、そのピンが検索条件に適合するかどうかをテストする。ピンが条件に適合する場合、メソッドは S_OK を返し、ppPin パラメータによってピンの IPin インターフェイスへのポインタを返す。それ以外の場合、メソッドは E_FAIL を返す。

いずれの場合も、メソッドが成功すると、ppPin パラメータによって返される IPin インターフェイスには、未解決の参照カウントが残る。インターフェイスを使った後は、必ず解放すること。

通常、アプリケーションがこのメソッドを使う必要はない。このメソッドは、RenderStream メソッドではフィルタ グラフを作成できない、きわめて複雑なタスクを処理するために用意されている。このメソッドを使って目的のピンをキャプチャ フィルタから取得し、グラフの残りの部分を手動で作成する。

ICaptureGraphBuilder2::GetFiltergraph

ICaptureGraphBuilder2 インターフェイス

キャプチャ グラフ ビルダが使用しているフィルタ グラフを取得する。

構文

HRESULT GetFiltergraph(
    IGraphBuilder **ppfg
);

パラメータ

ppfg
[out] IGraphBuilder インターフェイス ポインタを受け取る変数のアドレス。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_POINTER | NULL ポインタ引数。
E_UNEXPECTED | フィルタ グラフがない。

注意

このメソッドは、IGraphBuilder インターフェイスの参照カウントをインクリメントする。インターフェイスの使用を終わったら、必ずインターフェイスを解放すること。

ICaptureGraphBuilder2::RenderStream

ICaptureGraphBuilder2 インターフェイス

ソース フィルタの出力ピンを、オプションで圧縮フィルタを経由して、レンダリング フィルタに接続する。

構文

HRESULT RenderStream(
    const GUID *pCategory,
    const GUID *pType,
    IUnknown *pSource,
    IBaseFilter *pfCompressor,
    IBaseFilter *pfRenderer
);

パラメータ

pCategory
[in] ピン カテゴリを指定する AMPROPERTY_PIN_CATEGORY プロパティ セットのメンバへのポインタ。カテゴリに関係なく、任意のピンを使用する場合は NULL を指定する。通常は、次の値を指定する。
  • PIN_CATEGORY_CAPTURE
  • PIN_CATEGORY_PREVIEW
  • PIN_CATEGORY_VBI
  • PIN_CATEGORY_CC
pType
[in] 出力ピンのメディア タイプを指定するメジャー タイプ GUID へのポインタ。メディア タイプに関係なく、任意のピンを使用する場合は NULL を指定する。
pSource
[in] ソース フィルタのインターフェイスへのポインタまたは出力ピンのインターフェイスへのポインタ。
pfCompressor
[in] 圧縮フィルタの IBaseFilter インターフェイスへのオプションのポインタ。
pfRenderer
[in] レンダリング フィルタまたはマルチプレクサ フィルタの IBaseFilter インターフェイスへのオプションのポインタ。

戻り値

HRESULT 値を返す。可能な戻り値は次のとおりである。

S_OK | 成功。
VFW_S_NOPREVIEWPIN | スマート ティー フィルタを経由してプレビューがレンダリングされた。
E_FAIL | 失敗。
E_INVALIDARG | 無効な引数。
E_POINTER | NULL ポインタ引数。

注意

このメソッドは、プレビューまたはファイルへの書き込みを行う際にストリームをレンダリングする。このメソッドは、キャプチャ グラフの多くの複雑な処理を自動的に行う。

pSource パラメータでは、出力ピンまたはフィルタを指定する。出力ピンを指定した場合、メソッドは、そのピンからのストリームをレンダリングする。その場合は、pCategory パラメータと pType パラメータを NULL に設定する。フィルタを指定した場合、メソッドは、ピン カテゴリが pCategory パラメータと一致し、メディア タイプが pType パラメータと一致する、そのフィルタの出力ピンを検索する。

pfRenderer パラメータでは、シンク フィルタを指定する。シンク フィルタは、通常、ファイル ライタ フィルタ、AVI Mux などのマルチプレクサ フィルタのどちらかである。マルチプレクサへのポインタを取得するには、SetOutputFileName メソッドを呼び出す。このメソッドは、ppf パラメータによってポインタを返す。

pfRenderer が NULL である場合、メソッドは、デフォルトのレンダラ、つまりビデオの場合はビデオ レンダラ、オーディオの場合はデフォルト DirectSound デバイスを使用する。

pfCompressor パラメータでは、圧縮フィルタまたは一般的には任意の変換フィルタを指定する。ストリームを圧縮しない場合は、このパラメータを NULL に設定する。

スマート ティー。一部のキャプチャ フィルタにはキャプチャ ピンはあるが、プレビュー ピンがない。プレビューを行うには、キャプチャ ピンがスマート ティー フィルタに接続されている必要がある。このフィルタは、データをキャプチャ ストリームとプレビュー ストリームの 2 つのストリームに分割する。PIN_CATEGORY_PREVIEW または PIN_CATEGORY_CAPTURE を指定すると、必要に応じて、メソッドがスマート ティー フィルタを挿入する。次に、メソッドは、スマート ティー フィルタ上で指定されたストリームのレンダリングを行う。プレビュー ストリームをレンダリングするときにメソッドがスマート ティー フィルタを使用する場合、メソッドは VFW_S_NOPREVIEWPIN を返す。

クローズド キャプション。このメソッドを使ってクローズド キャプションのキャプチャまたはプレビューを行うことができる。一部のキャプチャ フィルタは垂直同期間隔 (VBI) データを出力し、別のキャプチャ フィルタはクローズド キャプション データを出力する。いずれの場合も、1 回は PIN_CATEGORY_VBI を使って、もう 1 回は PIN_CATEGORY_CC を使って、メソッドを 2 回呼び出す。メソッドは、VBI データをクローズド キャプションに変換するのに必要なすべてのフィルタを挿入する。データのプレビューを行うには、pfRenderer パラメータを NULL に設定する。データをファイルにキャプチャするには、マルチプレクサ フィルタの IBaseFilter インターフェイス ポインタを使用する。同じグラフでデータのキャプチャとプレビューを行うことができる。1 回目は NULL を使い、2 回目はマルチプレクサを使ってメソッドを呼び出す。pfCompressor パラメータを NULL に設定する。

ビデオ ポート ピン。 ビデオ ポート エクステンション (VPE) ビデオ キャプチャ ハードウェアを使用するフィルタは、プレビュー ピンの代わりにビデオ ポート ピン (PIN_CATEGORY_VIDEOPORT) を備えている。プレビューやキャプチャを機能させるには、ビデオ ポート ピンがオーバーレイ ミキサー フィルタに接続されている必要がある。細部はメソッドが処理する。PIN_CATEGORY_VIDEOPORT を指定する必要はない。PIN_CATEGORY_PREVIEW または PIN_CATEGORY_CAPTURE を指定すれば、メソッドがピンを正しく接続する。これと同様に、一部のフィルタは、ビデオ ポート ピン (PIN_CATEGORY_VIDEOPORT_VBI) を使って VBI データを出力する。PIN_CATEGORY_VIDEOPORT の場合と同様に、メソッドが細部を処理する。PIN_CATEGORY_VIDEOPORT_VBI を指定する必要はない。

サポートするフィルタ。キャプチャ デバイスが Windows Driver Model (WDM) ドライバを使用する場合、グラフは、WDM ビデオ キャプチャ フィルタのアップストリームにある TV チューナー フィルタやアナログ ビデオ クロスバー フィルタなどの特定のフィルタを必要とすることがある。このメソッドが正しくストリームのレンダリングを行えば、メソッドは、必要になるすべての WDM フィルタをグラフに挿入する。メソッドは、キャプチャ フィルタの入力ピンに問い合わせて、入力ピンがサポートするメディアを判別し、それらのメディアを適合するフィルタに接続する。

ファイル ソース。このメソッドの本来の目的はキャプチャ グラフの作成であるが、このメソッドはファイルのトランスコードや再圧縮にも使用できる。以下の説明では、ファイルに最大でも 1 つのビデオ ストリームと 1 つのオーディオ ストリームまたは 1 つのインターリーブ ストリームが含まれているものとする。それ以外の条件では、メソッドは正しく機能しない。ファイル ソースの出力ピンは 1 つなので、pCategory と pType を NULL に設定する。1 回はビデオ ストリームをレンダリングするために、もう 1 回はオーディオ ストリームをレンダリングするために、計 2 回メソッドを呼び出す。最初の呼び出しでは、ソース フィルタがパーサー フィルタに接続され、パーサー フィルタの出力ピンの中の 1 つがレンダリングされる。2 回目の呼び出しでは、パーサーの残りの出力ピンがレンダリングされる。1 つのストリームを圧縮し、もう 1 つのストリームを圧縮しない場合は、必ず最初の呼び出しでコンプレッサ フィルタ (pfCompressor パラメータ) を指定すること。最初の呼び出しで pfCompressor を NULL にすると、メソッドはビデオ ストリームをレンダリングすることも、オーディオ ストリームをレンダリングすることもある。詳しい使用例については、「AVI ファイルの再圧縮」を参照すること。

ICaptureGraphBuilder2::SetFiltergraph

ICaptureGraphBuilder2 インターフェイス

キャプチャ グラフ ビルダが使用するフィルタ グラフを指定する。

構文

HRESULT SetFiltergraph(
    IGraphBuilder *pfg
);

パラメータ

pfg
[in] フィルタ グラフの IGraphBuilder インターフェイスへのポインタ。

戻り値

HRESULT 値を返す。設定される値は次のとおりである。

E_POINTER | NULL ポインタ引数。
E_UNEXPECTED | 予期せぬエラー。

注意

このメソッドを呼び出さない場合は、キャプチャ グラフ ビルダが、必要なときに自動的にフィルタ グラフを作成する。キャプチャ グラフ ビルダが既にフィルタ グラフを備えている場合、このメソッドは E_UNEXPECTED を返す。

ICaptureGraphBuilder2::SetOutputFileName

ICaptureGraphBuilder2 インターフェイス

フィルタ グラフのファイル ライティング セクションを作成する。

構文

HRESULT SetOutputFileName(
    const GUID *pType,
    LPCOLESTR lpwstrFile,
    IBaseFilter **ppf,
    IFileSinkFilter **pSink
);

パラメータ

pType
[in] 出力のメディア サブタイプあるいはマルチプレクサ フィルタまたはファイル ライタ フィルタのクラス識別子 (CSLID) を表す GUID へのポインタ。指定するメディア サブタイプは、次のいずれかでなければならない。
MEDIASUBTYPE_Avi | AVI (Audio-Video Interleaved)
MEDIASUBTYPE_Asf | ASF (Advanced Streaming Format)
lpwstrFile
[in] 出力ファイル名が格納された Unicode™ 文字列へのポインタ。
ppf
[out] マルチプレクサの IBaseFilter インターフェイスを受け取るポインタのアドレス。
pSink
[out] ファイル ライタの IFileSinkFilter インターフェイスを受け取るポインタのアドレス。NULL の場合がある。

戻り値

HRESULT 値を返す。設定される値は次のとおりである。
S_OK | 成功。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。

注意

このメソッドは、マルチプレクサと File ライタ フィルタをフィルタ グラフに挿入する。また、このメソッドは、IFileSinkFilter::SetFileName を呼び出して出力ファイル名を設定する。

ppf パラメータによって返されるマルチプレクサ フィルタへのポインタを、RenderStream メソッドの pfRenderer パラメータとして使うことができる。

メソッドが成功すると、ppf パラメータによって返される IBaseFilter インターフェイスに、未解決の参照カウントが残る。メソッドが成功し、pSink が NULL でない場合は、IFileSinkFilter インターフェイスにも未解決の参照カウントが残る。いずれのインターフェイスも、使用した後で、必ず解放すること。


IConfigAviMux インターフェイス

IConfigAviMux インターフェイスは、AVI マルチプレクサ フィルタがディスクにファイルを書き込む方法を制御する。現在、Microsoft® DirectShow® は、AVI マルチプレクサ フィルタのプロパティ ページを通じてこのインターフェイスを公開しており、これを利用して、マスタ ストリームと互換インデックスを設定できる。

IConfigAviMux は、旧バージョンの Video for Windows® AVI (Audio-Video Interleaved) インデックス フォーマット (idx1) および 1 GB を超えるファイル サイズに対応する 拡張 AVI 2.0 インデックス フォーマット (indx) と下位互換性を持っている。IConfigAviMux::SetOutputCompatibilityIndex メソッドおよび IConfigAviMux::GetOutputCompatibilityIndex メソッドを使って、互換インデックスの設定および取得を行う。AVI 2.0 の詳細については、「AVI 2.0 ファイル フォーマット拡張」を参照すること。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IConfigAviMux メソッド | 説明
SetMasterStream | ファイルがディスクに保存された後、ほかのストリームを同期させるときの基準となるマスタ ストリームを設定する。
GetMasterStream | ファイルが書き込まれた後、ほかのストリームを同期させるときの基準となるマスタ ストリームを取得する。
SetOutputCompatibilityIndex | マルチプレクサが保存するファイルの AVI インデックス フォーマットを設定する。
GetOutputCompatibilityIndex | マルチプレクサが書き込むファイルの AVI インデックス フォーマットを取得する。

IConfigAviMux::GetMasterStream

IConfigAviMux インターフェイス

ファイルが書き込まれた後、ほかのストリームを同期させるときの基準となるマスタ ストリームを取得する。

構文

HRESULT GetMasterStream(
  LONG *pStream
  );

パラメータ

pStream
[out] マスタ ストリームへのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

オーディオ サンプリング レートとビデオ フレーム レートとの間で発生するキャプチャ ドリフトをなくするために、大きいファイルをキャプチャするときはオーディオ/ビデオ一体型カードを使用することを推奨する。

参照

IConfigAviMux::SetMasterStream

IConfigAviMux::GetOutputCompatibilityIndex

IConfigAviMux インターフェイス

マルチプレクサが書き込むファイルの AVI インデックス フォーマットを取得する。

構文

HRESULT GetOutputCompatibilityIndex(
  BOOL *pfOldIndex
  );

パラメータ

pfOldIndex
[out] インデックス フォーマットを示す値へのポインタ。AVI 1.0 (idx1) インデックス フォーマットまたは AVI 2.0 (indx) インデックス フォーマットが設定されている場合は TRUE を返し、AVI 2.0 (indx) インデックス フォーマットのみが設定されている場合は FALSE を返す。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

参照

SetOutputCompatibilityIndex

IConfigAviMux::SetMasterStream

IConfigAviMux インターフェイス

ファイルがディスクに保存された後、ほかのストリームを同期させるときの基準となるマスタ ストリームを設定する。

構文

HRESULT SetMasterStream(
  LONG iStream
  );

パラメータ

iStream
[in] マスタ入力ストリーム。無効にするときは –1 に設定する。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

別々のオーディオ キャプチャ カードとビデオ キャプチャ カードを使用している場合は、キャプチャ シナリオ内のさまざまなストリームがさまざまなレートでキャプチャされる可能性がある。このメソッドでは、マスタ ストリームを指定して、ほかのすべてのストリームをそれに同期させることにより、フレーム レートまたはオーディオ サンプリング レートを調整してレートのドリフトを除去する。

オーディオ サンプリング レートとビデオ フレーム レートとの間で発生するキャプチャ ドリフトをなくすために、大きいファイルをキャプチャするときはオーディオ/ビデオ一体型カードを使用することを推奨する。

参照

IConfigAviMux::GetMasterStream

IConfigAviMux::SetOutputCompatibilityIndex

IConfigAviMux インターフェイス

マルチプレクサが保存するファイルの AVI インデックス フォーマットを設定する。

構文

HRESULT SetOutputCompatibilityIndex(
  BOOL fOldIndex
  );

パラメータ

fOldIndex
[in] AVI インデックス フォーマットを指定する値。TRUE は AVI 1.0 (idx1) インデックス フォーマットまたは AVI 2.0 (indx) インデックス フォーマットのいずれかを示し、FALSE は AVI 2.0 (indx) インデックス フォーマットのみを示す。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

DirectShow は、Video for Windows® AVI インデックス フォーマット (idx1) と下位互換性を持っているほか、拡張 AVI 2.0 インデックス フォーマット (indx) もサポートしており、このメソッドではそれを指定できる。AVI 2.0 インデックス フォーマットを利用すると、AVI ファイル サイズの拡大 (1 GB を超える)、階層的インデックス付け、ファイルの増分追加、およびディスク シークの削減が可能になる。AVI 2.0 の詳細については、「AVI 2.0 ファイル フォーマット拡張」を参照すること。

参照

IConfigAviMux::GetOutputCompatibilityIndex


IConfigInterleaving インターフェイス

IConfigInterleaving インターフェイスは AVI マルチプレクサ フィルタに実装される。このインターフェイスは、ファイルをディスクに書き込む方法を制御し、周期パラメータやプリロール パラメータなどのインターリーブ構成情報を設定する。

このインターフェイスは、オーディオ サンプルおよびビデオ フレームをディスクに保存する方法を指定する InterleavingMode 列挙型を使用する。オーサリングを直ちに行うか、後で行うかに応じて、INTERLEAVE_NONE から INTERLEAVE_FULL までのキャプチャ インターリーブ設定がある。

キャプチャリングを処理するビデオ オーサリング アプリケーションは、オーディオ サンプルおよびビデオ フレームをディスクに保存する方法を制御する必要があるときに、このインターフェイスを使用する必要がある。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IConfigInterleaving メソッド | 説明
put_Mode | インターリーブ品質を指定することにより、オーディオ サンプルとビデオ フレームをディスクに保存する方法を設定する。
get_Mode | インターリーブ品質の設定を取得する。
put_Interleaving | インターリーブのオーディオ プリロール タイムと周期を設定する。
get_Interleaving | インターリーブのオーディオ プリロール タイムと周期を取得する。

IConfigInterleaving::get_Interleaving

IConfigInterleaving インターフェイス

インターリーブのオーディオ プリロール タイムと周期を取得する。

構文

HRESULT get_Interleaving(
    REFERENCE_TIME *prtInterleave,
    REFERENCE_TIME *prtPreroll );

パラメータ

prtInterleave
[out] ファイル内のストリームの周期へのポインタ (100 ナノ秒単位)。
prtPreroll
[out] オーディオ プリロールへのポインタ (100 ナノ秒単位)。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

参照

IConfigInterleaving::put_Interleaving

IConfigInterleaving::get_Mode

IConfigInterleaving インターフェイス

インターリーブ品質の設定を取得する。

構文

HRESULT get_Mode(
    InterleavingMode *pMode );

パラメータ

pMode
[out] InterleavingMode 列挙型で指定されるインターリーブ品質の設定へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

インターリーブ モードは、InterleavingMode 列挙型によって指定され、IConfigInterleaving::put_Mode メソッドによって設定される。

参照

IConfigInterleaving::put_Mode

IConfigInterleaving::put_Interleaving

IConfigInterleaving インターフェイス

インターリーブのオーディオ プリロール タイムと周期を設定する。

構文

HRESULT put_Interleaving(
    const REFERENCE_TIME *prtInterleave,
    const REFERENCE_TIME *prtPreroll );

パラメータ

prtInterleave
[in] ファイル内のストリームの周期へのポインタ (100 ナノ秒単位)。
prtPreroll
[in] オーディオ プリロールへのポインタ (100 ナノ秒単位)。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

配布用のファイルのオーサリングを行うときは、オーディオ プリロールを 750 ミリ秒にすることを推奨する。

prtInterleave のデフォルト値は 1000 ミリ秒である。ただし、この値は調整できる。数値を小さくするほど、ファイルが大きくなる。

参照

IConfigInterleaving::get_Interleaving

IConfigInterleaving::put_Mode

IConfigInterleaving インターフェイス

インターリーブ品質を指定することにより、オーディオ サンプルとビデオ フレームをディスクに保存する方法を設定する。

構文

HRESULT put_Mode(
    InterleavingMode mode );

パラメータ

mode
[in] InterleavingMode 列挙型で指定されるインターリーブ品質の設定。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

後でオーサリングを行う場合、完全なインターリーブ オーサリング品質を必要とするアプリケーションでは、INTERLEAVE_FULL、INTERLEAVE_CAPTURE、および INTERLEAVE_NONE の設定を指定する必要がある。

参照

IConfigInterleaving::get_Mode


ICreateDevEnum インターフェイス

指定されたフィルタ カテゴリ内のフィルタおよびハードウェア デバイスのリストの列挙子を作成する。返される列挙子は、IEnumMoniker インターフェイスをサポートする。

システム デバイス列挙子はこのインターフェイスを公開する。同じフィルタが複数のハードウェア デバイスをサポートしている場合でも、この列挙子は、個々のハードウェア デバイスを区別する。

アプリケーションはこのインターフェイスを使って、ハードウェア デバイスに対応するフィルタのインスタンスを見つけることができる。まず、システム デバイス列挙子のインスタンスを作成し、次に、それを使って特定のカテゴリのデバイス用の列挙子を作成する。詳細については、「デバイスとフィルタの列挙」を参照すること。

列挙子の使い方の詳細については、Platform SDK のドキュメントの「IEnumXXXX」を参照すること。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
ICreateDevEnum メソッド | 説明
CreateClassEnumerator | 指定されたカテゴリのクラス列挙子を作成する。

ICreateDevEnum::CreateClassEnumerator

ICreateDevEnum インターフェイス

指定されたタイプのオブジェクトの列挙子を作成する。

構文

HRESULT CreateClassEnumerator(

  REFCLSID clsidDeviceClass,

  IEnumMoniker **ppEnumMoniker,

  DWORD dwFlags

  );

パラメータ

clsidDeviceClass
[in] 列挙するデバイスのタイプを指定する REFCLSID 値。(「フィルタ カテゴリ」を参照すること。)
ppEnumMoniker
[out] 新しいクラス列挙子によって実装される Win32 IEnumMoniker (または派生) インターフェイスへのポインタのアドレス。
dwFlags
[in] 予約済み。0 でなければならない。

戻り値

次のいずれかの値を返す。
NOERROR | 成功。
S_OK | 成功。
E_OUTOFMEMORY | クラス列挙子を作成するのに十分なメモリが利用できない。
S_FALSE | clsidDeviceClass によって指定されたカテゴリが存在しない。

注意

デバイスが見つからない場合、メソッドは、要素の数がゼロのモニカを返す代わりに、モニカを返さない。

新しいクラス列挙子は、このメソッドを呼び出したクラスと同じプロセスで動作する非集成オブジェクトである。


IDDrawExclModeVideo インターフェイス

IDDrawExclModeVideo インターフェイスはオーバーレイ ミキサー フィルタによって実装される。このインターフェイスを利用すると、Microsoft® DirectDraw® 排他フルスクリーン モードになっている間でもビデオを再生できる。ゲーム アプリケーションは、DirectDraw を排他フルスクリーン モードで使用しながらビデオ再生を継続することができる。たとえば、バックグラウンドでビデオを再生しながら、その上にグラフィックをのせることができる。アプリケーションは、DirectDraw オブジェクトとプライマリ サーフェスを渡し、それらがフィルタ グラフのオーバーレイ ミキサー フィルタに渡される。

DVD グラフ ビルダ オブジェクトは、DirectDraw 排他フルスクリーン モードになっている間、IDDrawExclModeVideo を使って DVD コンテンツを再生する。このインターフェイスを単独で使って、ゲーム内で MPEG-1 ビデオまたは AVI ビデオを再生することもできる。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IDDrawExclModeVideo メソッド | 説明
SetDDrawObject | これ以降の描画に使われる DirectDraw オブジェクトを設定する。
GetDDrawObject | オーバーレイ ミキサーが使用している DirectDraw オブジェクトを取得する。
SetDrawParameters | 元のビデオのどの部分を画面のどこに表示するかを指定する。
SetDDrawSurface | これ以降の描画に使われる DirectDraw サーフェスを設定する。
GetDDrawSurface | オーバーレイ ミキサーが使用している DirectDraw サーフェスを取得する。
GetNativeVideoProps | オーバーレイ ミキサーのプライマリ ストリームの幅、高さ、およびアスペクト比を取得する。
SetCallbackInterface | オーバーレイ ミキサーへのコールバック インターフェイスを指定し、呼び出し側アプリケーションがビデオの再生中に表示の調整に関する通知を受け取れるようにする。

IDDrawExclModeVideo::GetDDrawObject

IDDrawExclModeVideo インターフェイス

オーバーレイ ミキサー フィルタが使用している DirectDraw オブジェクトを取得する。

構文

HRESULT GetDDrawObject(
    LPDIRECTDRAW *pDDrawObject,
    LPBOOL *pbUsingExternal
);

パラメータ

pDDrawObject
[out] オーバーレイ ミキサーが使用している IDirectDraw インターフェイスへのポインタのアドレス。
pbUsingExternal
[out] オーバーレイ ミキサーが SetDDrawObject で指定されている DirectDraw オブジェクトを使用しているかどうかを示す値へのポインタのアドレス。オーバーレイ ミキサーが SetDDrawObject で指定されている DirectDraw オブジェクトを使用している場合は TRUE、それ以外の場合は FALSE になる。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

現在実装されている Microsoft® DirectShow® は、次の値を返す。

S_OK | 成功。
E_INVALIDARG | 引数が無効。
DirectDraw エラー コード | 指定されたサーフェスをオーバーレイ ミキサー上で設定しようとしたときに DirectDraw エラーが発生した。

注意

フィルタ グラフが DirectDraw オブジェクトを設定しておらず、オーバーレイ ミキサーがまだ DirectDraw オブジェクトを割り当てていない場合は、pDDrawObject が NULL に設定され、pbUsingExternal が FALSE に設定される。

IDDrawExclModeVideo::GetDDrawSurface

IDDrawExclModeVideo インターフェイス

オーバーレイ ミキサーが使用している DirectDraw サーフェスを取得する。

構文

HRESULT GetDDrawSurface(
    LPDIRECTDRAWSURFACE *pDDrawSurface,
    LPBOOL *pdUsingExternal
);

パラメータ

pDDrawSurface
[out] オーバーレイ ミキサーが使用している IDirectDrawSurface インターフェイスへのポインタのアドレス。
pdUsingExternal
[out] オーバーレイ ミキサーが SetDDrawSurface で指定されている DirectDraw サーフェスを使用しているかどうかを示すブール型の値へのポインタのアドレス。オーバーレイ ミキサーが SetDDrawSurface で指定されている DirectDraw サーフェスを使用している場合は TRUE、それ以外の場合は FALSE になる。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

現在の DirectShow の実装での戻り値は次のとおりである。

S_OK | 成功。
E_INVALIDARG | 引数が無効。
DirectDraw エラー コード | 指定されたサーフェスをオーバーレイ ミキサー上で設定しようとしたときに DirectDraw エラーが発生した。

注意

フィルタ グラフが DirectDraw サーフェスを設定しておらず、オーバーレイ ミキサーがまだ DirectDraw サーフェスを割り当てていない場合は、pDDrawSurface が NULL に設定され、pbUsingExternal が FALSE に設定される。

IDDrawExclModeVideo::GetNativeVideoProps

IDDrawExclModeVideo インターフェイス

オーバーレイ ミキサーのプライマリ ストリームの現在のビデオのサイズとアスペクト比を取得する。

構文

HRESULT GetNativeVideoProps(
    LPDWORD *pdwVideoWidth,
    LPDWORD *pdwVideoHeight,
    LPDWORD *pdwPictAspectRatioX,
    LPDWORD *pdwPictAspectRatioY
);

パラメータ

pdwVideoWidth
[out] ビデオの幅へのポインタのアドレス。
pdwVideoHeight
[out] ビデオの高さへのポインタのアドレス。
pdwPictAspectRatioX
[out] アスペクト比の x 軸へのポインタのアドレス。
pdwPictAspectRatioY
[out] アスペクト比の y 軸へのポインタのアドレス。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

現在の DirectShow の実装での戻り値は次のとおりである。

S_OK | 成功。
E_INVALIDARG | 引数が無効。

注意

フィルタ グラフは、EC_VIDEO_SIZE_CHANGED イベントを予期し、イベントを受け取ったら、このメソッドを呼び出してアスペクト比と位置を調整する必要がある。

IDDrawExclModeVideo::SetCallbackInterface

IDDrawExclModeVideo インターフェイス

オーバーレイ ミキサーのコールバック インターフェイスへのポインタを取得し、呼び出し側アプリケーションがビデオを再生中に表示の調整に関する通知を受け取れるようにする。

構文

HRESULT SetCallbackInterface(
    IDDrawExclModeVideoCallback *pCallback
    DWORD dwFlag
);

パラメータ

pCallback
[out] IDDrawExclModeVideoCallback インターフェイスを実装するオブジェクトへのポインタ。pCallback が NULL の場合は、コールバック インターフェイスが NULL に設定され、それ以降のコールバックは行われない。前のコールバック インターフェイスがあった場合は、そのインターフェイスが解放され、それ以降のそのインターフェイスへのコールバックは行われない。pCallback が NULL 以外の値で、このメソッドが S_OK を返す場合は、pCallback が指すオブジェクトの参照カウントがインクリメントされる。
dwFlag
[in] 0 でなければならない。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

現在の DirectShow の実装での戻り値は次のとおりである。

S_OK | 成功。
E_INVALIDARG | 引数が無効。

注意

アプリケーションは、このメソッドを使ってオーバーレイのサイズ、位置、カラー キーの変更が発生したときに通知を受け取り、それに合わせてビデオを非表示にしたり、表示したり、再生の開始時、終了時、または再生中にビデオを調整したりする必要がある。アプリケーションは、このメソッドを呼び出すことにより、IDDrawExclModeVideoCallback インターフェイスにアクセスし、そのインターフェイスへのポインタをオーバーレイ ミキサーに渡すことができる。

IDDrawExclModeVideo::SetDDrawObject

IDDrawExclModeVideo インターフェイス

これ以降の描画に使われる DirectDraw オブジェクトを設定する。

構文

HRESULT SetDDrawObject(
    LPDIRECTDRAW *pDDrawObject
);

パラメータ

pDDrawObject
[in] 使用するオブジェクトの IDirectDraw インターフェイスへのポインタのアドレス。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

現在の DirectShow の実装での戻り値は次のとおりである。

S_OK | 成功。
E_INVALIDARG | 引数が無効。
DirectDraw エラー コード | 指定されたサーフェスをオーバーレイ ミキサー上で設定しようとしたときに DirectDraw エラーが発生した。

注意

ゲーム アプリケーションは、このメソッドを使って、自アプリケーション用に作成した DirectDraw オブジェクトをオーバーレイ ミキサー フィルタに共有させ、SetDDrawSurface で設定されている、指定されたサーフェスでビデオを描画することができる。

IDDrawExclModeVideo::SetDrawParameters

IDDrawExclModeVideo インターフェイス

元のビデオのどの部分を画面のどこに表示するかを指定する。

構文

HRESULT SetDrawParameters(
    RECT *pSrcRect,
    RECT *pDestRect
);

パラメータ

pSrcRect
[in] 元のビデオの RECT 構造体へのポインタ。
pDestRect
[in] ビデオが画面のどこに表示されるかを示す RECT へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

参照

IDDrawExclModeVideoCallback

IDDrawExclModeVideo::SetDDrawSurface

IDDrawExclModeVideo インターフェイス

これ以降の描画に使われる DirectDraw サーフェスを指定する。

構文

HRESULT SetDDrawSurface(
    LPDIRECTDRAWSURFACE *pDDrawSurface
);

パラメータ

pDDrawSurface
[in] 使用するサーフェスの IDirectDrawSurface インターフェイスへのポインタのアドレス。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

現在の DirectShow の実装での戻り値は次のとおりである。

S_OK | 成功。
E_INVALIDARG | 引数が無効。
DirectDraw エラー コード | 指定されたサーフェスをオーバーレイ ミキサー上で設定しようとしたときに DirectDraw エラーが発生した。

注意

ゲーム アプリケーションは、このメソッドを使って、自アプリケーション用に作成した DirectDraw サーフェスをオーバーレイ ミキサー フィルタに共有させ、指定されたサーフェスでビデオを描画することができる。このサーフェスは、SetDDrawObject で指定されたオブジェクトと関連付けられていなければならない。


IDDrawExclModeVideoCallback インターフェイス

IDDrawExclModeVideoCallback インターフェイスを利用すると、アプリケーションは、オーバーレイの位置、サイズ、表示/非表示などに関する同期通知を取得し、アプリケーションのビデオの表示/非表示、サイズ、位置を調整することができる。これにより、再生の開始時、終了時、または途中でカラー キーのちらつきが発生することがなくなる。アプリケーションは、このインターフェイスをサポートする COM オブジェクトを実装する必要がある。

IDDrawExclModeVideo インターフェイスを使用しており、(おそらく常時) コールバック情報を必要としている場合は、このインターフェイスを実装すること。

Microsoft® DirectShow® オーバーレイ ミキサー フィルタを使用している場合、および、より一般的には、IDDrawExclModeVideo をサポートするフィルタ、またはアプリケーションが適切なタイミングでカラー キーを描画できるようにコールバックを生成する必要があるフィルタを書いている場合は、このインターフェイスを使用する。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IDDrawExclModeVideoCallback メソッド | 説明
OnUpdateOverlay | ビデオのオーバーレイ サーフェスが変わる直前にアプリケーションに通知する。
OnColorKeyChange | カラー キーが変わり、アプリケーションが新しいカラー キーを使ってビデオにグラフィックスをオーバーレイできるようになったことをアプリケーションに通知する。

IDDrawExclModeVideoCallback::OnColorKeyChange

IDDrawExclModeVideoCallback Interface

カラー キーが変わり、アプリケーションが新しいカラー キーを使ってビデオにグラフィックスをオーバーレイできるようになったことをアプリケーションに通知する。

構文

HRESULT OnColorKeyChange (
    COLORKEY const *pKey,
    DWORD dwColor
);

パラメータ

pKey
[out] キー タイプとパレット インデックスが格納された COLORKEY 構造体へのポインタ。
dwColor
[out] 現在のディスプレイ モードが 8 ビットでパレット化されている場合は、pKey によって返される COLORKEY の 8 ビット パレット インデックスを示す値。それ以外の場合は、現在のディスプレイ フォーマットのピクセル フォーマットで表すカラー キーに相当する値。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

現在の DirectShow の実装での戻り値は次のとおりである。
S_OK | 成功。
E_INVALIDARG | パラメータの中の 1 つが無効である。

IDDrawExclModeVideoCallback::OnUpdateOverlay

IDDrawExclModeVideoCallback インターフェイス

ビデオのオーバーレイ サーフェスが表示される直前、非表示になる直前、サイズを変える直前、または位置を変える直前にアプリケーションに通知し、アプリケーションがそれに合わせてウィンドウを再描画できるようにする。

構文

HRESULT OnUpdateOverlay(
    BOOL bBeforeChange,
    DWORD dwFlags,
    BOOL bOldVisible,
    LPRECT *prcSrcOld,
    LPRECT *prcDestOld,
    BOOL bNewVisible,
    LPRECT *prcSrcNew,
    LPRECT *prcDestNew,
);

パラメータ

bBeforeChange
[in] 呼び出しがオーバーレイに関連する変更の前に行われるか、後で行われるかを示すブール型の値。TRUE は前に行われることを示し、FALSE は後で行われることを示す。
dwFlags
[in] 何が変わるのか、または変わったのかを示す AM_OVERLAY_NOTIFY_FLAGS データ型の値。
bOldVisible
[in] 旧ウィンドウが表示されているかどうかを示すブール型の値。TRUE は旧ウィンドウが表示されていることを示す。
prcSrcOld
[in] DirectDraw サーフェスの古いソースの位置を示す矩形へのポインタ。
prcDestOld
[in] オーバーレイ サーフェス内の矩形の古い表示位置を示す矩形へのポインタ。
bNewVisible
[in] 新しいウィンドウが表示されているかどうかを示すブール型の値。TRUE は新しいウィンドウが表示されていることを示す。
prcSrcNew
[in] DirectDraw サーフェスの新しいソースの位置を示す矩形へのポインタ。
prcDestNew
[in] オーバーレイ サーフェス内の矩形の新しい表示位置を示す矩形へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

現在の DirectShow の実装での戻り値は次のとおりである。
S_OK | 成功。
E_INVALIDARG | 無効なパラメータ。

注意

アプリケーションは、オーバーレイに関連する変更が発生する前に 1 回、発生した後に 1 回、このメソッドを呼び出す必要がある。変更前に行われる呼び出しでは、アプリケーションがこのメソッドの実行を完了するまでオーバーレイの変更は発生しない。


IDecimateVideoImage インターフェイス

IDecimateVideoImage インターフェイスは、デコーダ フィルタ上のデシメーションを指定する。デシメーション とは、ビデオ出力をビデオ本来のサイズより小さくすることをいう。

アプリケーションはこのインターフェイス上でメソッドを呼び出してはならない。オーバーレイ ミキサー フィルタは、このインターフェイスを使ってビデオ デコーダのビデオをデシメーションする。

ビデオ出力をデシメーションできるデコーダ フィルタは、このインターフェイスをサポートする必要がある。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IDecimateVideoImage メソッド | 説明
SetDecimationImageSize | デコーダがどのサイズまで出力画像をデシメーションするかを指定する。
ResetDecimationImageSize | デコーダが出力画像をデシメーションしてはいけないこと示す。

IDecimateVideoImage::ResetDecimationImageSize

IDecimateVideoImage インターフェイス

デコーダが出力画像をデシメーションしてはいけないこと示す。

構文

HRESULT ResetDecimationImageSize(void);

戻り値

呼び出しが成功したか、失敗したかを示す HRESULT 値を返す。

IDecimateVideoImage::SetDecimationImageSize

IDecimateVideoImage インターフェイス

デコーダがどのサイズまで出力画像をデシメーションするかを指定する。

構文

HRESULT SetDecimationImageSize(
    long lWidth,
    long lHeight
);

パラメータ

lWidth
[in] ビデオ画像の幅 (ピクセル単位)。
lHeight
[in] ビデオ画像の高さ (ピクセル単位)。

戻り値

次のいずれかの HRESULT 値を返す。

E_FAIL | デコーダがデシメーションを実行できない、または現在実行しているデシメーションを中止する必要がある。
S_OK | デコーダが要求されているサイズまでビデオをデシメーションできる。


IDeferredCommand インターフェイス

アプリケーションが IQueueCommand インターフェイスを使って前にキューに入れたグラフコントロール コマンドをキャンセルまたは変更できるようにする。

アプリケーションは、フィルタ グラフ マネージャ上で IQueueCommand メソッドを呼び出すと、IDeferredCommand インターフェイスへのポインタを受け取る。アプリケーションはこのインターフェイスを使って、コマンドをキャンセルまたは延期したり、コマンドからの戻り値を取得したりすることができる。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IDeferredCommand メソッド | 説明
Cancel | アプリケーションが前にキューに入れたコマンドをキャンセルする。
Confidence | 要求された時間にコマンドが呼び出される可能性を示すコンフィデンス レベルを取得する。
Postpone | コマンドの新しい呼び出し時間を指定する。
GetHResult | 呼び出されたコマンドからの戻り値を取得する。

IDeferredCommand::Cancel

IDeferredCommand インターフェイス

アプリケーションが前にキューに入れたコマンドをキャンセルする。

構文

HRESULT Cancel(void);

戻り値

成功した場合は、S_OK を返す。要求が既にキャンセルされている場合は、VFW_E_ALREADY_CANCELLED を返す。

IDeferredCommand::Confidence

IDeferredCommand インターフェイス

要求された時間にコマンドが呼び出される可能性を示すコンフィデンス レベルを取得する。

このメソッドは実装されず、E_NOTIMPL を返す。

構文

HRESULT Confidence(
    LONG *pConfidence
);

パラメータ

pConfidence
0 から 100 の段階で表されるコンフィデンス レベルを受け取る変数へのポインタ。

戻り値

E_NOTIMPL を返す。

IDeferredCommand::GetHResult

IDeferredCommand インターフェイス

呼び出されたコマンドからの戻り値を取得する。

構文

HRESULT GetHResult(
    HRESULT *phrResult
);

パラメータ

phrResult
HRESULT 値を受け取る変数へのポインタ。

戻り値

HRESULT 値を返す。設定される値は次のとおりである。

S_OK | 成功。
E_ABORT | コマンドがまだ呼び出されていない。
E_POINTER | NULL ポインタ引数。

IDeferredCommand::Postpone

IDeferredCommand インターフェイス

コマンドの新しい呼び出し時間を指定する。

構文

HRESULT Postpone(
    REFTIME newtime
);

パラメータ

newtime
コマンドを呼び出す新しい時間。

戻り値

成功した場合は、S_OK を返す。要求された時間が既に過ぎている場合は、VFW_E_TIME_ALREADY_PASSED を返す。


IDirectDrawVideo インターフェイス

IDirectDrawVideo インターフェイスはビデオ レンダラに実装され、DirectDraw サーフェスとハードウェア機能に関する情報をアプリケーションに提供する。アプリケーションはこのインターフェイスを使って、ビデオ レンダラが利用する DirectDraw 機能を制御する。たとえば、ビデオ レンダラでハードウェア オーバーレイを利用しないことが確実であれば、SetSwitches メソッドを使って、ハードウェア オーバーレイの使用を無効にすることができる。

注 : このインターフェイスを使って、ビデオ レンダラに DirectDraw の特定の機能を強制的に使用させることはできない。可能なのは、ビデオ レンダラが特定の機能を使わないようにすることだけである。

このインターフェイスは、一部が IDirectDraw インターフェイスと重複する。ただし、このインターフェイスでは、DirectDraw プロバイダを直接呼び出さなくても、同じ情報に簡単にアクセスできる。

ビデオ レンダラは接続されるまで DirectDraw をロードせず、同様に、DirectDraw はレンダラの接続が切断されるまでアンロードされない。レンダラがビデオ再生に使用する DirectDraw サーフェスを割り当てると、アプリケーションはそれを記述する DDSURFACEDESC 構造体を取得できる。レンダラは DDSURFACEDESC 構造体へのポインタを渡すことによって、現在のサーフェスに関する詳細なデータを構造体に格納する。DirectDraw がロードされていない場合、レンダラは、E_FAIL を返す。レンダラが DCI (DirectDraw の前のバージョン) を使っている場合、DDSURFACEDESC 構造体にデータは格納されず、呼び出しは S_FALSE を返す。レンダラが使用する DCI サーフェスのタイプは、プライマリ サーフェスに限られる。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IDirectDrawVideo メソッド | 説明
GetCaps | ハードウェア機能が格納された DirectDraw 定義 DDCAPS 構造体を取得する。
GetEmulatedCaps | エミュレート機能が格納された DirectDraw 定義 DDCAPS 構造体を取得する。
CanUseOverlayStretch | レンダラがオーバーレイ制限をチェックするかどうかを決定する。
CanUseScanLine | レンダラが描画するときに現在の走査線をチェックするかどうかを決定する。
GetDirectDraw | IDirectDraw インターフェイスを取得する。
GetFourCCCodes | マルチメディア フォーマット タイプ FOURCC DWORD を取得する。
GetSurfaceDesc | 使用されている DirectDraw サーフェスの説明を取得する。
GetSurfaceType | 実際のサーフェス タイプを取得する。
GetSwitches | レンダラが使用できるサーフェス タイプを取得する。
SetDefault | 現在のプロパティ設定をグローバル デフォルトにする。
SetDirectDraw | ロードされているドライバに IDirectDraw インターフェイスを渡す。
SetSwitches | レンダラが使用できるサーフェス タイプを設定する。
UseOverlayStretch | レンダラがオーバーレイ拡大制限をチェックする必要があるかどうかを決定する。
UseScanLine | レンダラがビデオを描画するときに現在の走査線をチェックする必要があるかどうかを決定する。
UseWhenFullScreen | フルスクリーン モードに切り替わるときに DirectShow がディスプレイ モードを変更する必要があるかどうかを決定する。
WillUseFullScreen | フルスクリーン モードに切り替わるときに DirectShow がディスプレイ モードを変更するかどうかを決定する。

IDirectDrawVideo::CanUseOverlayStretch

IDirectDrawVideo インターフェイス

レンダラがオーバーレイ制限をチェックするかどうかを決定する。

構文

HRESULT CanUseOverlayStretch(
    long *UseOverlayStretch
);

パラメータ

UseOverlayStretch
レンダラがオーバーレイ制限を使えるかどうかを示す値へのポインタ。OATRUE はレンダラがオーバーレイ制限をチェックすることを示し、OAFALSE はチェックしないことを示す。

戻り値

HRESULT 値を返す。

注意

オーバーレイ拡大機能については、「IDirectDrawVideo::UseOverlayStretch」を参照すること。

IDirectDrawVideo::CanUseScanLine

IDirectDrawVideo インターフェイス

レンダラが描画するときに現在の走査線をチェックするかどうかを決定する。

構文

HRESULT CanUseScanLine(
    long *UseScanLine
);

パラメータ

UseScanLine
レンダラが走査線情報を使用するかどうかを示す値へのポインタ。OATRUE はレンダラが描画するときに現在の走査線をチェックすることを示し、OAFALSE はチェックしないことを示す。

戻り値

HRESULT 値を返す。

注意

DirectShow ビデオ レンダラで走査線検出を使用する方法については、「IDirectDrawVideo::UseScanLine」を参照すること。

IDirectDrawVideo::GetCaps

IDirectDrawVideo インターフェイス

ハードウェア機能が格納された DirectDraw 定義 DDCAPS 構造体を取得する。

構文

HRESULT GetCaps(
    DDCAPS *pCaps
);

パラメータ

pCaps
ハードウェア機能が格納されている DDCAPS 構造体へのポインタ。

戻り値

HRESULT 値を返す。

注意

レンダラが DirectDraw をロードしていない場合、このメソッドは E_FAIL を返す。

IDirectDrawVideo::GetDirectDraw

IDirectDrawVideo インターフェイス

IDirectDraw インターフェイスを取得する。

構文

HRESULT GetDirectDraw(
    LPDIRECTDRAW *ppDirectDraw
);

パラメータ

ppDirectDraw
IDirectDraw インターフェイスへのポインタのアドレス。

戻り値

HRESULT 値を返す。

注意

アプリケーションが DirectDraw をロードしたいが、レンダラがサーフェスを割り当てられるようにもしたい場合、アプリケーションは、レンダラに DirectDraw をロードさせた後、このメソッドを使って、参照がインクリメントされた DirectDraw へのインターフェイスを取得することができる。アプリケーションは、返されたインターフェイスを使用した後、解放する必要がある。

IDirectDrawVideo::GetEmulatedCaps

IDirectDrawVideo インターフェイス

エミュレート機能が格納された DirectDraw 定義 DDCAPS 構造体を取得する。

構文

HRESULT GetEmulatedCaps(
    DDCAPS *pCaps
);

パラメータ

pCaps
エミュレート機能が格納されている DDCAPS 構造体へのポインタ。

戻り値

HRESULT 値を返す。レンダラが DirectDraw をロードしていない場合、このメソッドは E_FAIL を返す。

IDirectDrawVideo::GetFourCCCodes

IDirectDrawVideo インターフェイス

マルチメディア フォーマット タイプを取得する。

構文

HRESULT GetFourCCCodes(
    DWORD *pCount,
    DWORD *pCodes
);

パラメータ

pCount
pCodes 配列内の FOURCC コードの数へのポインタ。
pCodes
以前 Microsoft マルチメディア タイプで使用されていた DWORD メディア タグの配列へのポインタ。

戻り値

HRESULT 値を返す。

注意

最初の Microsoft® Windows® multimedia API では、メディア タイプに FOURCC コードと呼ばれる 4 個の 8 ビット文字から作成される 32 ビット値のタグが付けられていた。FOURCC コードは一意であるため、FOURCC を表す 40 億個の GUID を割り当てることによって、1 対 1 のマッピングが可能だった。

このメソッドは、現在のディスプレイ ドライバがサポートできる FOURCC コードを取得する。利用可能な FOURCC コードの数を取得するには、有効な pCount ポインタを指定し、pCodes を NULL に設定してメソッドを呼び出す。その場合、pCount 変数には、利用可能な FOURCC コードの数が格納される。次に、アプリケーションは、取得された FOURCC コードの数に対応する十分な数の DWORD 値を割り当てて、pCodes で配列ポインタを指定し、メソッドを再び呼び出す。

IDirectDrawVideo::GetSurfaceDesc

IDirectDrawVideo インターフェイス

現在の DirectDraw サーフェスを記述する DDSURFACEDESC 構造体を取得する。

構文

HRESULT GetSurfaceDesc(
    DDSURFACEDESC *pSurfaceDesc
);

パラメータ

pSurfaceDesc
現在の DirectDraw サーフェスを記述する DDSURFACEDESC 構造体へのポインタ。

戻り値

HRESULT 値を返す。割り当てられているサーフェスがない場合、このメソッドは E_FAIL を返す。DCI プライマリ サーフェスが使用されている場合、DDSURFACEDESC 構造体にはデータが格納されず、呼び出しは S_FALSE を返す。

注意

サーフェスはレンダラがポーズしているときにだけ割り当てられる。レンダラがポーズした後、停止したときにサーフェスを解放することはできない。

IDirectDrawVideo::GetSurfaceType

IDirectDrawVideo インターフェイス

実際のサーフェス タイプを DirectShow DirectDraw Surface (AMDDS) 定義として取得する。

構文

HRESULT GetSurfaceType(
    DWORD *pSurfaceType
);

パラメータ

pSurfaceType
次の AMDDS 定義のリストから選択された 1 ビット設定が格納されているフィールドへのポインタ。
AMDDS_NONE | DCI/DirectDraw を使用しない。
AMDDS_DCIPS | DCI プライマリ サーフェスを使用する。
AMDDS_PS | DirectDraw プライマリ サーフェスを使用する。
AMDDS_RGBOVR | RGB オーバーレイ サーフェス。
AMDDS_YUVOVR | YUV オーバーレイ サーフェス。
AMDDS_RGBOFF | RGB オフスクリーン サーフェス。
AMDDS_YUVOFF | YUV オフスクリーン サーフェス。
AMDDS_RGBFLP | RGB フリッピング サーフェス。
AMDDS_YUVFLP | YUV フリッピング サーフェス。
AMDDS_ALL | 上記すべてのフラグ。
AMDDS_DEFAULT | 利用可能なサーフェスすべてを使用する。
AMDDS_YUV | (AMDDS_YUVOFF | AMDDS_YUVOVR | AMDDS_YUVFLP)。
AMDDS_RGB | (AMDDS_RGBOFF | AMDDS_RGBOVR | AMDDS_RGBFLP)。
AMDDS_PRIMARY | (AMDDS_DCIPS | AMDDS_PS)。

戻り値

HRESULT 値を返す。

注意

DDSURFACEDESC 構造体を見ただけは、使用されているサーフェスの種類がわからないことがある。したがって、アプリケーションは GetSurfaceType を呼び出して、サーフェス タイプを取得することができる。フィールドには、上記の AMDDS 定義のリストから選択された 1 ビット設定が格納される。

IDirectDrawVideo::GetSwitches

IDirectDrawVideo インターフェイス

レンダラが使用できるサーフェス タイプを取得する。

構文

HRESULT GetSwitches(
    DWORD *pSwitches
);

パラメータ

pSwitches
次の DirectShow DirectDraw Surface (AMDDS) サーフェス タイプの中の 1 つ以上が含まれたビット マスクへのポインタ。
AMDDS_NONE | DCI/DirectDraw を使用しない。
AMDDS_DCIPS | DCI プライマリ サーフェスを使用する。
AMDDS_PS | DirectDraw プライマリ サーフェスを使用する。
AMDDS_RGBOVR | RGB オーバーレイ サーフェス。
AMDDS_YUVOVR | YUV オーバーレイ サーフェス。
AMDDS_RGBOFF | RGB オフスクリーン サーフェス。
AMDDS_YUVOFF | YUV オフスクリーン サーフェス。
AMDDS_RGBFLP | RGB フリッピング サーフェス。
AMDDS_YUVFLP | YUV フリッピング サーフェス。
AMDDS_ALL | 上記すべてのフラグ。
AMDDS_DEFAULT | 利用可能なサーフェスすべてを使用する。
AMDDS_YUV | (AMDDS_YUVOFF | AMDDS_YUVOVR | AMDDS_YUVFLP)。
AMDDS_RGB | (AMDDS_RGBOFF | AMDDS_RGBOVR | AMDDS_RGBFLP)。
AMDDS_PRIMARY | (AMDDS_DCIPS | AMDDS_PS)。

戻り値

HRESULT 値を返す。

IDirectDrawVideo::SetDefault

IDirectDrawVideo インターフェイス

現在のプロパティ設定をグローバル デフォルトにする。

構文

HRESULT SetDefault(void);

戻り値

HRESULT 値を返す。

注意

IDirectDrawVideo を通じて設定されるすべてのプロパティは、その特定のインスタンスに固有のプロパティである。このメソッドを呼び出すことによって、IDirectDrawVideo のこのインスタンスに対して設定されているプロパティを、このインターフェイスのすべての DirectShow インスタンスのグローバル デフォルトにする。メソッドが呼び出された後は、ほかの DirectShow フィルタ グラフを起動したり、コンピュータを再起動したりしても、現在のプロパティ設定が引き継がれる。

IDirectDrawVideo::SetDirectDraw

IDirectDrawVideo インターフェイス

ロードされているドライバに IDirectDraw インターフェイスを渡す。

構文

HRESULT SetDirectDraw(
    LPDIRECTDRAW pDirectDraw
);

パラメータ

pDirectDraw
渡される IDirectDraw インターフェイスへのポインタ。

戻り値

HRESULT 値を返す。

注意

アプリケーションは SetDirectDraw を呼び出して NULL を渡すことにより、SetDirectDraw を通じて前に渡した DirectDraw インターフェイスをレンダラに解放させることができる。しかし、レンダラは、レンダラの接続が切断されるまで、その DirectDraw インターフェイスを使い続ける。したがって、NULL パラメータを指定して SetDirectDraw を呼び出しても、レンダラが直ちにインターフェイスの使用をやめるわけではない。

このメソッドが作られた理由は、DirectX 7.0 以前の DirectDraw のバージョンでは、1 つのプロセスにつき 1 つの IDirectDraw のインスタンスしかロードできなかったからである。DirectX 7.0 以降を使っている場合は、このメソッドを呼び出す必要はない。アプリケーションが IDirectDraw をロードしたいが、ビデオ レンダラがサーフェスを割り当てられるようにもしたい場合、アプリケーションは、IDirectDraw 自体を開き、IDirectDrawVideo::SetDirectDraw を使って、ロードされているドライバにインターフェイスを渡すことができる。このほかに、アプリケーションがレンダラに DirectDraw をロードさせた後、IDirectDrawVideo::GetDirectDraw を使って、参照がインクリメントされた DirectDraw へのインターフェイスを取得するという方法もある。ただし、DirectShow には最新バージョンの DirectDraw が付属するため、アプリケーションがディスプレイ モード自体を変更し、DirectDraw オブジェクトを渡して、レンダラがそれを使ってサーフェスを割り当てられるようにする場合を除き、このメソッドは必要ない。

IDirectDrawVideo::SetSwitches

IDirectDrawVideo インターフェイス

レンダラが使用できるサーフェス タイプを設定する。

構文

HRESULT SetSwitches(
    DWORD Switches
);

パラメータ

Switches
次の DirectShow DirectDraw Surface (AMDDS) サーフェス タイプの中の 1 つ以上が含まれたビット マスク。
AMDDS_NONE | DCI/DirectDraw を使用しない。
AMDDS_DCIPS | DCI プライマリ サーフェスを使用する。
AMDDS_PS | DirectDraw プライマリ サーフェスを使用する。
AMDDS_RGBOVR | RGB オーバーレイ サーフェス。
AMDDS_YUVOVR | YUV オーバーレイ サーフェス。
AMDDS_RGBOFF | RGB オフスクリーン サーフェス。
AMDDS_YUVOFF | YUV オフスクリーン サーフェス。
AMDDS_RGBFLP | RGB フリッピング サーフェス。
AMDDS_YUVFLP | YUV フリッピング サーフェス。
AMDDS_ALL | 上記すべてのフラグ。
AMDDS_DEFAULT | 利用可能なサーフェスすべてを使用する。
AMDDS_YUV | (AMDDS_YUVOFF | AMDDS_YUVOVR | AMDDS_YUVFLP)。
AMDDS_RGB | (AMDDS_RGBOFF | AMDDS_RGBOVR | AMDDS_RGBFLP)。
AMDDS_PRIMARY | (AMDDS_DCIPS | AMDDS_PS)。

戻り値

HRESULT 値を返す。

注意

このメソッドはビデオ レンダラが接続する前に呼び出されなければならない。

IDirectDrawVideo::UseOverlayStretch

IDirectDrawVideo インターフェイス

レンダラがオーバーレイ拡大制限をチェックする必要があるかどうかを決定する。

構文

HRESULT UseOverlayStretch(
    long UseOverlayStretch
);

パラメータ

UseOverlayStretch
レンダラがオーバーレイ拡大機能をチェックするかどうかを指定する値。レンダラにオーバーレイ 拡大機能をチェックさせるときは OATRUE に設定し、それ以外の場合は、OAFALSE に設定する。

戻り値

HRESULT 値を返す。

注意

一部のディスプレイ カードは、DirectDraw を経由してオーバーレイ サーフェスを使用する機能を備えている。オーバーレイ サーフェスとは、モニタの垂直リフレッシュ期間中にディスプレイにオーバーレイされる内容が格納されているビデオ メモリのブロックである。通常、オーバーレイ サーフェスは、ビデオの画質が高く、パフォーマンスがきわめて高速であるため、DirectShow は、可能な限り、利用可能なすべてのオーバーレイ サーフェスを使用する。比較的高いビット深度に設定されている一部のディスプレイ カードでは、ディスプレイのハードウェア帯域幅の制限に対応するために、オーバーレイを実際のオーバーレイのサイズより大きい画面に表示する必要がある。オーバーレイを十分に大きく表示しないと、ディスプレイ上で "瞬間的なちらつき" と呼ばれる画面の乱れが発生する可能性がある。

UseOverlayStretch が OATRUE (オン、デフォルト) に設定されていると、DirectShow は、オーバーレイを表示する前に、オーバーレイが正しく拡大されていることを確認する。UseOverlayStretch が OAFALSE (オフ) に設定されていると、DirectShow は、オーバーレイが正しく拡大されているかどうかをチェックしないため、画面の乱れが発生する可能性がある。ただし、可能な場合にはオーバーレイが使用されることは保証される。

IDirectDrawVideo::UseScanLine

IDirectDrawVideo インターフェイス

レンダラがビデオを描画するときに現在の走査線をチェックする必要があるかどうかを決定する。

構文

HRESULT UseScanLine(
    long UseScanLine
);

パラメータ

UseScanLine
走査線情報を使うかどうかを指定する Long 型整数値。走査線情報を使用するには OATRUE に設定し、走査線情報を無視するには OAFALSE に設定する。

戻り値

引数が無効である場合は E_INVALIDARG を返し、それ以外の場合は NOERROR を返す。

注意

モニタの走査線が画面の見える部分を走査している間にビデオ画像をビデオ メモリにブリットすると、完成した画像は、古い画像と新しい画像の複合画像になる。この複合画像は、分裂ビデオ画像と呼ばれる。前の画像が完了するまで新しい画像のブリットを待つことによって、分裂画像の発生を避けることができる。一部のビデオ カードでは、走査線の現在の位置を取得できる。この情報が利用できれば、走査線が画面の外に出るまで DirectShow に新しい画像のブリットを待機させることによって、テアリングを軽減することができる。ただし、走査線の位置のチェックはプロセッサの負荷を増大させるため、画面に表示されるビデオ フレームの量が減少する可能性があることに注意する必要がある。走査線情報が利用できれば、DirectShow はデフォルトでそれを利用する。多少画像の乱れがあっても処理時間を優先させたい場合は、UseScanLine を OAFALSE に設定する。

IDirectDrawVideo::UseWhenFullScreen

IDirectDrawVideo インターフェイス

フルスクリーン モードに切り替わるときに DirectShow がディスプレイ モードを変更する必要があるかどうかを決定する。

構文

HRESULT UseWhenFullScreen(
    long UseWhenFullScreen
);

パラメータ

UseWhenFullScreen
ディスプレイ モードを変更するかどうかを指定する値。レンダラに DirectShow をフルスクリーン モードで使わせるには OATRUE に設定し、それ以外の場合は OAFALSE に設定する。

戻り値

HRESULT 値を返す。

注意

フルスクリーン モードに移行するように要求された場合、DirectShow には多くの選択肢がある。最初の選択肢は、グラフ内にフルスクリーン再生を直接サポートするフィルタがあるかどうかを調べることで、フィルタがある場合、そのフィルタはフルスクリーン再生のサポートを要求される。

2 番目の選択肢は、DirectDraw モード変更サービスを使用する特殊なフルスクリーン レンダラをフィルタ グラフに自動的に追加し、ビデオを再生する方法である。ディスプレイ モードを変更すると、ビデオは、ディスプレイ上の、より大きい領域 (必ずしも全領域ではない) を占める。したがって、たとえば、1024 × 768 ピクセル モードでは小さくしか表示されないビデオでも、ディスプレイ モードが 320 × 240 になれば、見栄えがずっとよくなる。

3 番目で最後の選択肢は、IVideoWindow インターフェイスをサポートする任意のレンダラを使って、そのレンダラのウィンドウをフルスクリーンに拡大させる方法である。通常、この方法では、フルスクリーンの DirectDraw 対応レンダラに切り替える 2 番目の選択肢よりパフォーマンスが低くなる。UseWhenFullScreen パラメータをオン (OATRUE) に設定すれば、フルスクリーン再生のときには常にウィンドウがフルスクリーンにまで拡大される。このパラメータをオフ (デフォルト) に設定すれば、フィルタ グラフ マネージャは、DirectDraw 対応のフルスクリーン レンダラに切り替えることができる。

IDirectDrawVideo::WillUseFullScreen

IDirectDrawVideo インターフェイス

フルスクリーン モードに切り替わるときに DirectShow がディスプレイ モードを変更するかどうかを決定する。

構文

HRESULT WillUseFullScreen(
    long *UseWhenFullScreen
);

パラメータ

UseWhenFullScreen
DirectShow が DirectX をフルスクリーン モードで使用するかどうかを示す値へのポインタ。OATRUE は、フルスクリーン モードで使用することを示し、OAFALSE は使用しないことを示す。

戻り値

HRESULT 値を返す。

注意

この機能については、「IDirectDrawVideo::UseWhenFullScreen」を参照すること。


IDirectDrawMediaSample インターフェイス

IDirectDrawMediaSample インターフェイスは、IMediaSample もサポートするオブジェクトによってサポートされる。この種のサンプルの "バッファ" は、Microsoft® DirectDraw® サーフェスである。この種のサンプルは、オーバーレイ ミキサーとアップストリーム デコーダ フィルタとの接続用の IDirectDrawMediaSampleAllocator によって割り当てられる。 このインターフェイスを利用すると、デコーダ フィルタは、サーフェスのロックを解除すると同時にサーフェスを保持できるため、ほかのコンポーネントもサーフェスにアクセスできる。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IDirectDrawMediaSample メソッド | 説明
GetSurfaceAndReleaseLock | サンプルが表すサーフェスを取得し、ロックを解除する。
LockMediaSamplePointer | サンプルが表すサーフェスをロックする。

IDirectDrawMediaSample::GetSurfaceAndReleaseLock

IDirectDrawMediaSample Interface

サンプルが表すサーフェスを取得し、ロックを解除する。

構文

HRESULT GetSurfaceAndReleaseLock(
    IDirectDrawSurface **ppDirectDrawSurface
    RECT *pRect
);

パラメータ

ppDirectDrawSurface
[out] サンプルの IDirectDrawSurface インターフェイスへのポインタのアドレス。
pRect
[out] サンプルが表すサーフェスの部分を定義する矩形のアドレスを受け取る変数へのポインタ。

戻り値

HRESULT 値を返す。

注意

呼び出し側は、このインターフェイスのオーバーレイ ミキサー フィルタの実装を呼び出す場合を除き、返されたサーフェス ポインタを解放する必要がある。

IDirectDrawMediaSample::LockMediaSamplePointer

IDirectDrawMediaSample インターフェイス

サンプルが表すサーフェスをロックする。

構文

HRESULT LockMediaSamplePointer(void);

戻り値

HRESULT 値を返す。

注意

このメソッドは、必ず GetSurfaceAndReleaseLock を呼び出した後に呼び出すこと。


IDirectDrawMediaSampleAllocator インターフェイス

IDirectDrawMediaSampleAllocator インターフェイスは、ビデオ デコーダとのアップストリーム接続用にオーバーレイ ミキサーが作成するアロケータに実装される。このアロケータは、IMediaSample インターフェイスもサポートする IDirectDrawMediaSample メディア サンプルを割り当てる。

デコーダ フィルタは、このインターフェイスを使ってオーバーレイ ミキサーに接続する必要はない。アプリケーションがこのインターフェイスを使うことはない。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IDirectDrawMediaSampleAllocator メソッド | 説明
GetDirectDraw | サーフェスの割り当てに使用される DirectDraw のインスタンスを取得する。

IDirectDrawMediaSampleAllocator::GetDirectDraw

IDirectDrawMediaSampleAllocator インターフェイス

サーフェスの割り当てに使用される DirectDraw のインスタンスへのポインタを取得する。

構文

HRESULT GetDirectDraw(
    IDirectDraw **ppDirectDraw
);

パラメータ

ppDirectDraw
[out] DirectDraw オブジェクトの IDirectDraw インターフェイスを受け取るポインタのアドレス。

戻り値

HRESULT 値を返す。

注意

呼び出し側は、このインターフェイスのオーバーレイ ミキサー フィルタの実装を呼び出す場合を除き、返された IDirectDraw ポインタを解放する必要がある。


IDistributorNotify インターフェイス

IDistributorNotify インターフェイスは、PID にフィルタ グラフの状態の変化を通知するために使用するオプションのインターフェイスである。アプリケーションがこのインターフェイスを使用することはない。

フィルタ グラフの制御と構成の変更を PID に通知したい場合は、フィルタ グラフ マネージャに集成される PID を作成するときに、このインターフェイスを実装する。

PID がフィルタ グラフ マネージャ上でメソッドを使用することはよくある。IDistributorNotify メソッドが呼び出されている間は、フィルタ グラフ マネージャを呼び出す別のコード パスが保持している可能性のあるロックを取得してはならない。これを行うと、デッドロックが発生することがある。

フィルタ グラフ マネージャは、フィルタ グラフ マネージャに集成されるすべての PID に対してこのインターフェイスを問い合わせる。インターフェイスが見つかった場合、フィルタ グラフ マネージャは、各フィルタの IBaseFilter インターフェイス上で PID を呼び出す前に、適切な Run メソッド、Pauseメソッド、または SetSyncSource メソッドを呼び出す。フィルタが追加または削除された場合、あるいは接続が変更された場合、フィルタ グラフ マネージャは必ず NotifyGraphChange メソッドを呼び出す。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IDistributorNotify methods | 説明
Stop | フィルタ グラフが停止状態に移行するときに呼び出される。
Pause | フィルタ グラフがポーズ状態に移行するときに呼び出される。
Run | フィルタ グラフが実行状態に移行するときに呼び出される。
SetSyncSource | 新しいクロックが登録されるときに呼び出される。
NotifyGraphChange | フィルタ グラフ内のフィルタのセットまたはその接続が変更されるときに呼び出される。

IDistributorNotify::NotifyGraphChange

IDistributorNotify インターフェイス

フィルタ グラフ内のフィルタのセットまたはその接続が変更されるときに呼び出される。

構文

HRESULT NotifyGraphChange(void);

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
S_OK または NOERROR | 成功。

注意

このメソッドは、IFilterGraph::AddFilter メソッド、IFilterGraph::RemoveFilter メソッド、または IFilterGraph::ConnectDirect メソッドが呼び出されたとき、または、たとえば IGraphBuilder::RenderFile など、これらのメソッドの呼び出しにつながるメソッドが呼び出されたときに、必ず呼び出される。

既に削除されているフィルタで、保持されているものがあれば、この時点で必ずそのフィルタに対して Release を使用すること。複数の別々の通知が送信されることがあるため、PID は、パフォーマンス上の理由から、PID が実際にインターフェイスを必要とするまでフィルタを再スキャンしないことがある。ただし、キャッシュされたインターフェイスは、直ちに解放することが重要である。

IDistributorNotify::Pause

IDistributorNotify インターフェイス

フィルタ グラフがポーズ状態に移行するときに呼び出される。

構文

HRESULT Pause(void);

戻り値

移行が完了した場合は、S_OK を返す。それ以外の場合は、次のいずれかの値を返す。
Error 値 | 移行が失敗した。
S_FALSE | 移行は完了していないが、エラーは発生しなかった。

注意

このメソッドは、フィルタに通知が行われる前に呼び出される。

IDistributorNotify::Run

IDistributorNotify インターフェイス

フィルタ グラフが実行状態に移行するときに呼び出される。

構文

HRESULT Run(
  REFERENCE_TIME tStart
  );

パラメータ

tStart
すべてのフィルタの IMediaFilter::Run メソッドに渡されるストリームタイム オフセット。

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
S_OK または NOERROR | 成功。

注意

このメソッドは、フィルタに通知が行われる前に呼び出される。

IDistributorNotify::SetSyncSource

IDistributorNotify インターフェイス

新しいクロックが登録されるときに呼び出される。

構文

HRESULT SetSyncSource(

  IReferenceClock *pClock

  );

パラメータ

pClock
[in] IReferenceClock インターフェイスへのポインタ。

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
S_OK または NOERROR | 成功。

注意

このメソッドは、フィルタに通知が行われる前に呼び出される。PID がこのメソッド呼び出し以降も pClock パラメータを保持する場合は、必ず pClock パラメータに対して AddRef を使用すること。

IDistributorNotify::Stop

IDistributorNotify インターフェイス

フィルタ グラフが停止状態に移行するときに呼び出される。

構文

HRESULT Stop(void);

戻り値

移行が完了した場合は、S_OK を返す。それ以外の場合は、次のいずれかの値を返す。
Error 値 | 移行が失敗した。
S_FALSE | 移行は完了していないが、エラーは発生しなかった。

注意

このメソッドは、フィルタに通知が行われる前に呼び出される。


IDMOWrapperFilter インターフェイス

アプリケーションがフィルタ グラフで Microsoft® DirectX® Media Object (DMO) を使用できるようにする。DMO ラッパー フィルタは、このインターフェイスを公開する。

DMO をフィルタ グラフに追加するには、DMO ラッパー フィルタのインスタンスを作成し、そのインスタンスに IDMOWrapperFilter インターフェイスを問い合わせる。次に、Init メソッドを呼び出してフィルタを DMO で初期化する。詳細については、「DirectShow アプリケーションでの DMO の使用」を参照すること。

要件

Dmodshow.h が必要である。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IDMOWrapperFilter メソッド | 説明
Init | 指定された DMO で DMO ラッパー フィルタを初期化する。

IDMOWrapperFilter::Init

IDMOWrapperFilter インターフェイス

指定された DMO で DMO ラッパー フィルタを初期化する。

構文

HRESULT Init(
    REFCLSID clsidDMO,
    REFCLSID catDMO
);

パラメータ

clsidDMO
DMO のクラス識別子 (CLSID)。
catDMO
DMO のカテゴリを指定する CLSID。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、エラーの原因を示す HRESULT 値を返す。

注意

DMO カテゴリの一覧については、「カテゴリ GUID」を参照すること。DMO ラッパー フィルタはカテゴリに基づいて最適化を実行する場合がある。


IDvdCmd インターフェイス

IDvdCmd インターフェイスは、DVD ナビゲータによって割り当てられるコマンド同期オブジェクトに実装される。PlayTitle、PlayAtTimeInTitle など、IDvdControl2 の "play" メソッド呼び出しによってアプリケーションから指示されると、DVD ナビゲータは、コマンド同期オブジェクトを割り当てて、そのコマンド同期オブジェクトの IDvdCmd インターフェイスへのポインタをアプリケーションに返す。コマンド同期オブジェクトは、コマンドが処理を開始する開始時とコマンドが完了する終了時にコマンドの結果を格納する。アプリケーションは、コマンド同期オブジェクトを使って、コマンドが開始または終了するまで、DVD ナビゲータを止めることができる。

コマンド同期オブジェクトと IDvdCmd インターフェイスの使い方の詳細については、「DVD コマンドの同期化」を参照すること。(この項では、コマンド同期オブジェクトを使わずにコマンドを同期させる代替手段についても説明している。)

注意 DVD ナビゲータはコマンド同期オブジェクトを割り当てるが、アプリケーションは、オブジェクトを使い終わったら、オブジェクトに対する Release を呼び出す必要がある。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IDvdCmd メソッド | 説明
WaitForStart | このオブジェクトに関連付けられたコマンドが開始するまで、DVD ナビゲータを止める。
WaitForEnd | このオブジェクトに関連付けられたコマンドが終了するか、キャンセルされるまで、DVD ナビゲータを止める。

IDvdCmd::WaitForEnd

IDvdCmd インターフェイス

このオブジェクトに関連付けられたコマンドが終了するか、キャンセルされるまで、DVD ナビゲータを止める。

構文

HRESULT WaitForEnd(void);

戻り値

成功すれば S_OK を返し、それ以外の場合は HRESULT エラー コードを返す。

IDvdCmd::WaitForStart

IDvdCmd インターフェイス

このオブジェクトに関連付けられたコマンドが開始するまで、DVD ナビゲータを止める。

構文

HRESULT WaitForStart(void);

戻り値

成功すれば S_OK を返し、それ以外の場合は HRESULT エラー コードを返す。


IDvdControl2 インターフェイス

Microsoft® DirectShow® DVD ナビゲータ ソース フィルタは、IDvdControl2 インターフェイスを公開して、カラオケ タイトルを含む DVD-Video タイトルのナビゲーションと再生をアプリケーションが実行できるようにする。DVD プレーヤー アプリケーションは、IDvdGraphBuilder インターフェイスを使って DVD フィルタ グラフを作成した後、IDvdControl2 と IDvdInfo2 のメソッドを使用して DVD ナビゲータに DVD コマンドを送信し、DVD ナビゲータからステート情報を取得する。

IDvdControl2 は、旧バージョンの DVD コントロール インターフェイスである IDvdControl に比べて大幅に改良されている。新しいインターフェイスでは旧インターフェイスを継承せずに、全面的に刷新された実装をカプセル化している。IDvdControl2 は、再生、メニュー ナビゲーション、およびペアレンタル ロックを実行するためのメソッドのほか、DVD Annex J 仕様で規定されているすべての機能を備えている。

DVD フィルタ グラフ、コマンド同期、ペアレンタル ロック、メニュー、およびカラオケ サポートに関するトピックを含む DVD ナビゲータを使った DVD プレーヤー アプリケーションの作成の詳細については、「DVD アプリケーション」を参照すること。

カテゴリ別のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IDvdControl2 メソッド | 説明
再生
Pause | 現在の位置で再生をポーズまたは再開する。
PlayAtTime | 現在のタイトルの指定された時間から再生を開始する。
PlayAtTimeInTitle | 指定されたタイトルの指定された時間から再生を開始する。
PlayBackwards | 指定された速度で現在の位置から逆方向に再生する。
PlayChapter | 現在のタイトルの指定されたチャプターから再生を開始する。
PlayChapterInTitle | 指定されたタイトルの指定されたチャプターの先頭から再生を開始する。
PlayChaptersAutoStop | 指定されたタイトルの指定されたチャプターから指定された数のチャプターを再生する。
PlayForwards | 指定された速度で現在の位置から順方向に再生する。
PlayNextChapter | 現在のタイトルの次のチャプターの先頭から再生を開始する。
PlayPeriodInTitleAutoStop | 指定されたタイトルを指定された開始タイムから指定された終了タイムまで再生する。
PlayPrevChapter | 現在のタイトルの前のチャプターの先頭から再生を開始する。
PlayTitle | 指定されたタイトルの先頭から再生を開始する。
ReplayChapter | 現在のチャプターの先頭から再生を開始する。
Stop | DVD ナビゲータを DVD Stop ドメインに移行させることにより、タイトルまたはメニューの再生を停止する。
メニュー
ActivateAtPosition | マウス ポインタの下にあるメニュー ボタンをアクティブにする。
ActivateButton | 選択されているメニュー ボタンをアクティブにする。
Resume | メニューから抜けて再生を再開する。
ReturnFromSubmenu | 表示をサブメニューからそのサブメニューの親メニューに戻す。
SelectAtPosition | マウス ポインタの下にあるメニュー ボタンを強調表示する。
SelectAndActivateButton | 指定されたメニュー ボタンを選択し、アクティブにする。
SelectButton | 指定されたメニュー ボタンを選択する。
SelectDefaultMenuLanguage | すべてのメニューとメニュー ボタンで使用されるデフォルトの言語を設定する。
SelectRelativeButton | 指定された相対ボタン (上、下、右、左) を選択する。
ShowMenu | 指定されたメニューがあれば表示する。
ビデオ ストリーム
SelectAngle | DVD ナビゲータがアングル ブロックにある間、新しいアングルを設定する。
StillOff | 再生を再開し、静止モードをキャンセルする。
SelectVideoModePreference | 現在以降のビデオ ディスプレイ モードをワイド スクリーン、レターボックス、またはパン-スキャンのいずれかに設定する。
オーディオ ストリーム
SelectAudioStream | 再生するオーディオ ストリームを選択する。
SelectDefaultAudioLanguage | デフォルトのオーディオ言語を設定する。
SelectKaraokeAudioPresentationMode | カラオケ補助チャンネルを左スピーカまたは右スピーカに送る。
サブピクチャ ストリーム
SelectDefaultSubpictureLanguage | サブピクチャ テキストのデフォルトの言語を設定する。
SelectSubpictureStream | 表示するサブピクチャ ストリームを設定する。
SetSubpictureState | サブピクチャの表示をオン、オフする。
ペアレンタル ロック レベル
AcceptParentalLevelChange | 現在より高いペアレンタル ロック レベルでコンテンツを再生することを求める DVD ナビゲータからの要求を受諾または拒否する。
SelectParentalCountry | ペアレンタル ロック アクセス レベルを解釈し、デフォルトの言語を設定するときの基準となる国を設定する。
SelectParentalLevel | ログオンしているユーザーのペアレンタル ロック アクセス レベルを設定する。
DVD ナビゲータ コントロール
SetDVDDirectory | DVD ナビゲータが読み込む DVD ドライブを設定する。
SetOption | DVD ナビゲータの内部動作フラグを有効または無効にする。
SetState | 後で取り出せるように、現在のディスク位置と DVD ナビゲータの状態を保存する。
SetGPRM | 汎用パラメータ レジスタ値を設定する。

IDvdControl2::AcceptParentalLevelChange

IDvdControl2 インターフェイス

現在より高いペアレンタル ロック レベルでコンテンツを再生することを求める DVD ナビゲータからの要求を受諾または拒否する。

構文

HRESULT AcceptParentalLevelChange(
    BOOL bAccept
);

パラメータ

bAccept
[in] アプリケーションがペアレンタル ロック レベルの変更を受け入れるかどうかを示すフラグ。変更を受け入れて、現在より高いレベルのコンテンツを再生するときは TRUE を指定し、変更を拒否するときは FALSE を指定する。

戻り値

成功すれば S_OK を返す。それ以外の場合はエラー コードを返す。

注意

一時ペアレンタル ロック レベル (PML) コマンドは、それ以降のコンテンツの PML がタイトル全体に指定されているレベルより高いことを示す DVD ディスク上のマーカーである。このマーカーには、変更が受諾または拒否された場合の分岐箇所を示す指示も含まれている。FALSE を指定すると、DVD ナビゲータはディスク上の拒否時の分岐に移動する。TRUE を指定すると、DVD ナビゲータは、現在より高いレベルのコンテンツに至る分岐に移動する。

AcceptParentalLevelChange は SetOption メソッドと共に使用する。イベントの順序は以下のとおりである。まず、SetOption(DVD_NotifyParentalLevelChange, TRUE) を呼び出し、DVD ナビゲータに対して、アプリケーションに EC_DVD_PARENTAL_LEVEL_CHANGE イベント通知を送信した後は常に待機するように指示する。次に、変更を受け入れるか、拒否するかを決定するためのコードをイベント ハンドラに実装し、AcceptParentalLevelChange を呼び出してその決定を DVD ナビゲータに通知する。

次の表は、このメソッド名が対応する Annex J コマンド名、およびこのメソッドが有効なドメインを示している。

Annex J コマンド名 | 有効なドメイン
なし | すべて

参照

ペアレンタル ロック レベルの適用

IDvdControl2::ActivateAtPosition

IDvdControl2 インターフェイス

マウス ポインタの下にあるメニュー ボタンをアクティブにする。

構文

HRESULT ActivateAtPosition(
    POINT point
);

パラメータ

point
[in] 画面ピクセル座標で表すクライアント ウィンドウ領域上の位置。

戻り値

次のいずれかの値を返す。
S_OK | 強調表示されているボタンの矩形領域内でマウスがクリックされ、ボタンがアクティブになっている。
E_INVALIDARG | ポインタが有効なビデオ リージョンの外にある。
E_UNEXPECTED | ボタンはあるが、動作していない。
VFW_E_DVD_INVALIDDOMAIN | DVD ナビゲータがメニュー ドメイン内にない。
VFW_E_DVD_NO_BUTTON | マウス ポインタの下にメニュー ボタンがない。
VFW_E_DVD_OPERATION_INHIBITED | ユーザー操作 (UOP) コントロールによって操作が禁止されている。

注意

マウス ポインタの座標の基準点はクライアント領域の左上隅であるが、ビデオのフォーマットがレターボックスの場合は、クライアント領域がビデオ ディスプレイ領域と一致しないことがある。

ユーザーがメニュー ボタン上で直接マウス ポインタを動かすことによってメニューのナビゲーションを行っている場合は、このメソッドを使用する。ユーザーが相対ボタンを使ってメニューのナビゲーションを行っている場合は、ActivateAtPosition ではなく、ActivateButton を使用する。

次の表は、このメソッド名が対応する Annex J コマンド名、およびこのメソッドが有効なドメインを示している。

Annex J コマンド名 有効なドメイン
なし DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu

参照

DVD メニューの操作

IDvdControl2::ActivateButton

IDvdControl2 インターフェイス

選択されているメニュー ボタンをアクティブにする。

構文

HRESULT ActivateButton(void);

戻り値

次のいずれかの値を返す。
S_OK | 成功。
VFW_E_DVD_INVALIDDOMAIN | DVD ナビゲータが無効なドメイン内にある。
VFW_E_DVD_OPERATION_INHIBITED | UOP コントロールにより、DVD ナビゲータがポーズ状態になることを禁止されている。
VFW_E_DVD_NO_BUTTON | どのボタンも選択されていない。

注意

アプリケーションのビデオ ディスプレイ上には、物理的なリモート コントロールのボタンに相当する 4 個の相対ボタンが表示される場合も、表示されない場合もある。相対ボタンを使用すると、ユーザーは、メニュー ボタンをアクティブにせずに、選択するだけにどどめることができる。この場合は、選択されたボタンをアクティブにするための 5 番目のボタンが必要になる。5 番目のボタンがクリックされた場合は、それに応じて ActivateButton を呼び出す。

次の表は、このメソッド名が対応する Annex J コマンド名、およびこのメソッドが有効なドメインを示している。

Annex J コマンド名 有効なドメイン
Button_Activate DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title

参照

DVD メニューの操作

IDvdControl2::Pause

IDvdControl2 インターフェイス

現在の位置で再生をポーズまたは再開する。

構文

HRESULT Pause(
    BOOL bState
);

パラメータ

bState
[in] 再生をポーズするかどうかを示すブール型の値。TRUE を指定するとポーズが実行される。

戻り値

次のいずれかの値を返す。

S_OK | 成功。
VFW_E_DVD_INVALIDDOMAIN | 無効なドメイン。
VFW_E_DVD_OPERATION_INHIBITED | UOP コントロールにより、DVD ナビゲータがポーズ状態になることを禁止されている。

注意

DVD ナビゲータをポーズ状態にすると、IMediaControl2::Pause と同様に、再生とすべての内部タイマが静止する。フィルタ グラフが動作していない場合、このメソッドは何もしない。

このメソッドの使用例については、DVDSample アプリケーションの「CDvdCore::Pause」を参照すること。

次の表は、このメソッド名が対応する Annex J コマンド名、およびこのメソッドが有効なドメインを示している。

Annex J コマンド名 有効なドメイン
PauseOn/PauseOff DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title

IDvdControl2::PlayAtTime

IDvdControl2 インターフェイス

現在のタイトルの指定された時間から再生を開始する。

構文

HRESULT PlayAtTime(
    DVD_HMSF_TIMECODE *pTime,
    DWORD dwFlags,
    IDvdCmd **ppCmd
);

パラメータ

pTime
[in] 再生を開始する時間を指定する DVD_HMSF_TIMECODE 構造体へのポインタ。
dwFlags
[in] コマンド同期オプションを指定する 1 つ以上の DVD_CMD_FLAGS 値を含むビット フラグ。
ppCmd
[out] DVD コマンドの同期に使用できる IDvdCmd オブジェクトへのポインタのアドレス。

戻り値

次のいずれかの値を返す。

S_OK | 成功。
E_INVALIDARG | 無効な引数。
VFW_E_DVD_OPERATION_INHIBITED | UOP コントロールが処理を禁止している。

注意

このメソッドの使用例については、DVDSample アプリケーションの「CDvdCore::PlayTime」を参照すること。

次の表は、このメソッド名が対応する Annex J コマンド名、およびこのメソッドが有効なドメインを示している。

Annex J コマンド名 | 有効なドメイン
Time_Search | DVD_DOMAIN_Title

参照

DVD コマンドの同期化

IDvdControl2::PlayAtTimeInTitle

IDvdControl2 インターフェイス

指定されたタイトルの指定された時間から再生を開始する。

構文

HRESULT PlayAtTimeInTitle(
    ULONG uiTitle,
    DVD_HMSF_TIMECODE *pTime,
    DWORD dwFlags,
    IDvdCmd **ppCmd
);

パラメータ

uiTitle
[in] 再生するタイトルの番号を指定する値。この値は 1 から 99 の間でなければならない。
pTime
[in] 再生を開始する位置を指定する DVD_HMSF_TIMECODE 構造体へのポインタ。
dwFlags
[in] コマンド同期オプションを指定する 1 つ以上の DVD_CMD_FLAGS 値を含むビット フラグ。
ppCmd
[out] DVD コマンドの同期に使用できる IDvdCmd オブジェクトへのポインタのアドレス。

戻り値

次のいずれかの値を返す。

S_OK | 成功。
VFW_E_DVD_OPERATION_INHIBITED | UOP コントロールが処理を禁止している。
E_INVALIDARG | 無効な引数。

注意

次の表は、このメソッド名が対応する Annex J コマンド名、およびこのメソッドが有効なドメインを示している。

Annex J command name Valid domains
Time_Play DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title
DVD_DOMAIN_Stop

参照

DVD コマンドの同期化

IDvdControl2::PlayBackwards

IDvdControl2 インターフェイス

指定された速度で現在の位置から逆方向に再生する。

構文

HRESULT PlayBackwards(
    double dwSpeed,
    DWORD dwFlags,
    IDvdCmd **ppCmd
);

パラメータ

dwSpeed
[in] 逆方向の再生速度を指定する値。この値は、作成されたときの速度を 1.0 とする乗数である。したがって、2.5 を指定すると、作成速度の 2.5 倍の速度で逆方向の再生が行われ、0.5 を指定すると作成速度の半分の速度で逆方向の再生が行われる。実際の再生速度は、ビデオ デコーダの機能によって異なり、指定された速度と異なることがある。逆方向の再生では、オーディオがミュートされ、サブピクチャは表示されない。0.00001 未満の速度はすべて 0.00001 に変換される。
dwFlags
[in] コマンド同期オプションを指定する 1 つ以上の DVD_CMD_FLAGS 値を含むビット フラグ。
ppCmd
[out] DVD コマンドの同期に使用できる IDvdCmd オブジェクトへのポインタのアドレス。

戻り値

次のいずれかの値を返す。

S_OK | 成功。
VFW_E_DVD_OPERATION_INHIBITED | UOP コントロールが処理を禁止している。

注意

このメソッドの使用例については、DVDSample アプリケーションの「CDvdCore::Rewind」を参照すること。1 フレームずつコマ送りしながら逆方向に再生するには、サンプル アプリケーションの CDvdCore::FrameStep の使用例のように IVideoFrameStep インターフェイスを使用する。

次の表は、このメソッド名が対応する Annex J コマンド名、およびこのメソッドが有効なドメインを示している。

Annex J コマンド名 有効なドメイン
Backward_Scan DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title

IDvdControl2::PlayChapter

IDvdControl2 インターフェイス

現在のタイトルの指定されたチャプターから再生を開始する。

構文

HRESULT PlayChapter(
    ULONG ulChapter,
    DWORD dwFlags,
    IDvdCmd **ppCmd
);

パラメータ

ulChapter
[in] DVD ナビゲータが再生を開始する現在のタイトルのチャプターを指定する値。この値は 1 から 999 の間でなければならない。
dwFlags
[in] コマンド同期オプションを指定する 1 つ以上の DVD_CMD_FLAGS 値を含むビット フラグ。
ppCmd
[out] DVD コマンドの同期に使用できる IDvdCmd オブジェクトへのポインタのアドレス。

戻り値

次のいずれかの値を返す。

S_OK | 成功。
VFW_E_DVD_OPERATION_INHIBITED | UOP コントロールが処理を禁止している。
E_INVALIDARG | 無効な引数。

注意

DVD ナビゲータは、指定されたチャプターから再生を開始し、それ以降のチャプターを引き続き再生する。現在のチャプターだけを再生するには、PlayChaptersAutoStop を使用する。

次の表は、このメソッド名が対応する Annex J コマンド名、およびこのメソッドが有効なドメインを示している。

このメソッドの使用例については、DVDSample アプリケーションの「CDvdCore::PlayChapter」を参照すること。
Annex J コマンド名 | 有効なドメイン
PTT_Search | DVD_DOMAIN_Title

参照

DVD コマンドの同期化

IDvdControl2::PlayChapterInTitle

IDvdControl2 インターフェイス

指定されたタイトルの指定されたチャプターの先頭から再生を開始する。

構文

HRESULT PlayChapterInTitle(
    ULONG ulTitle,
    ULONG ulChapter,
    DWORD dwFlags,
    IDvdCmd **ppCmd
);

パラメータ

ulTitle
[in] 目的のチャプターが含まれているタイトルを指定する値。この値は 1 から 99 の間でなければならない。
ulChapter
[in] DVD ナビゲータが再生を開始する指定されたタイトルのチャプターを指定する値。この値は 1 から 999 の間でなければならない。
dwFlags
[in] コマンド同期オプションを指定する 1 つ以上の DVD_CMD_FLAGS 値を含むビット フラグ。
ppCmd
[out] DVD コマンドの同期に使用できる IDvdCmd オブジェクトへのポインタのアドレス。

戻り値

次のいずれかの値を返す。

S_OK | 成功。
VFW_E_DVD_OPERATION_INHIBITED | UOP コントロールが処理を禁止している。
E_INVALIDARG | 無効な引数。

注意

次の表は、このメソッド名が対応する Annex J コマンド名、およびこのメソッドが有効なドメインを示している。

このメソッドの使用例については、DVDSample アプリケーションの「CDvdCore::PlayChapterInTitle」を参照すること。
Annex J コマンド名 有効なドメイン
PTT_Play DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title
DVD_DOMAIN_Stop

参照

DVD コマンドの同期化

IDvdControl2::PlayChaptersAutoStop

IDvdControl2 インターフェイス

指定されたタイトルの指定されたチャプターから指定された数のチャプターを再生する。

構文

HRESULT PlayChaptersAutoStop(
    ULONG ulTitle,
    ULONG ulChapter,
    ULONG ulChaptersToPlay,
    DWORD dwFlags,
    IDvdCmd **ppCmd
);

パラメータ

ulTitle
[in] 目的のチャプターが含まれているタイトルを指定する値。この値は 1 から 99 の間でなければならない。
ulChapter
[in] DVD ナビゲータが再生を開始する指定されたタイトルのチャプターを指定する値。この値は 1 から 999 の間でなければならない。
ulChaptersToPlay
[in] 開始チャプターから再生するチャプターの数。
dwFlags
[in] コマンド同期オプションを指定する 1 つ以上の DVD_CMD_FLAGS 値を含むビット フラグ。
ppCmd
[out] DVD コマンドの同期に使用できる IDvdCmd オブジェクトへのポインタのアドレス。

戻り値

次のいずれかの値を返す。

S_OK | 成功。
E_UNEXPECTED | DVD ナビゲータが初期化されていない、またはタイトルが単一シーケンシャル PGC タイトルではない。
E_INVALIDARG | ulTitle 値が存在しない、またはタイトルの数を上回る。あるいは、ulChapter が存在しない、またはチャプターの数を上回る。あるいは、ulChapter と ulChaptersToPlay の合計がチャプターの数を上回る。
VFW_E_DVD_GRAPHNOTREADY | グラフが動作状態になっていない。

注意

このメソッドは One_Sequential_PGC_Title でのみ機能する。DVD ナビゲータは、指定された数のチャプターを再生した後、アプリケーションに EC_DVD_CHAPTER_AUTOSTOP イベント通知を送る。

次の表は、このメソッド名が対応する Annex J コマンド名、およびこのメソッドが有効なドメインを示している。

Annex J コマンド名 | 有効なドメイン
なし | すべて

参照

EC_DVD_CHAPTER_AUTOSTOP、DVD コマンドの同期化

IDvdControl2::PlayForwards

IDvdControl2 インターフェイス

指定された速度で現在の位置から順方向に再生する。

構文

HRESULT PlayForwards(
    double dwSpeed,
    DWORD dwFlags,
    IDvdCmd **ppCmd
);

パラメータ

dwSpeed
[in] 再生速度を指定する値。この値は、作成されたときの速度を 1.0 とする乗数である。したがって、2.5 を指定すると、作成速度の 2.5 倍の速度で再生され、0.5 を指定すると作成速度の半分の速度で再生される。実際の再生速度は、ビデオ デコーダの機能によって異なる。
dwFlags
[in] コマンド同期オプションを指定する 1 つ以上の DVD_CMD_FLAGS 値を含むビット フラグ。
ppCmd
[out] DVD コマンドの同期に使用できる IDvdCmd オブジェクトへのポインタのアドレス。

戻り値

次のいずれかの値を返す。

S_OK | 成功。
VFW_E_DVD_OPERATION_INHIBITED | UOP コントロールが処理を禁止している。

注意

このメソッドの使用例については、DVDSample アプリケーションの「CDvdCore::FastForward」を参照すること。

次の表は、このメソッド名が対応する Annex J コマンド名、およびこのメソッドが有効なドメインを示している。

Annex J コマンド名 有効なドメイン
Forward_Scan DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title

IDvdControl2::PlayNextChapter

IDvdControl2 インターフェイス

現在のタイトルの次のチャプターの先頭から再生を開始する。

構文

HRESULT PlayNextChapter(
    DWORD dwFlags,
    IDvdCmd **ppCmd
);

パラメータ

dwFlags
[in] コマンド同期オプションを指定する 1 つ以上の DVD_CMD_FLAGS 値を含むビット フラグ。
ppCmd
[out] DVD コマンドの同期に使用できる IDvdCmd オブジェクトへのポインタのアドレス。

戻り値

次のいずれかの値を返す。

S_OK | 成功。
VFW_E_DVD_OPERATION_INHIBITED | UOP コントロールが処理を禁止している。

注意

DVD ナビゲータは、次のチャプターを再生した後、ディスク上の分岐命令に従って再生を継続する。次のチャプターだけを再生するには、PlayChaptersAutoStop を呼び出す。

このメソッドの使用例については、DVDSample アプリケーションの「CDvdCore::NextChapter」を参照すること。

次の表は、このメソッド名が対応する Annex J コマンド名、およびこのメソッドが有効なドメインを示している。

Annex J コマンド名 有効なドメイン
NextPG_Search DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title

参照

DVD コマンドの同期化

IDvdControl2::PlayPeriodInTitleAutoStop

IDvdControl2 インターフェイス

指定されたタイトルを指定された開始タイムから指定された終了タイムまで再生する。

構文

HRESULT PlayPeriodInTitleAutoStop(
    ULONG ulTitle
    DVD_HMSF_TIMECODE *pStartTime
    DVD_HMSF_TIMECODE *pEndTime
    DWORD dwFlags
    IDvdCmd **ppCmd
);

パラメータ

ulTitle
[in] タイトルを指定する値。この値は 1 から 99 の間でなければならない。
pStartTime
[in] 再生を開始する時間を指定する DVD_HMSF_TIMECODE 構造体へのポインタ。
pEndTime
[in] 再生を停止する時間を指定する DVD_HMSF_TIMECODE 構造体へのポインタ。
dwFlags
[in] コマンド同期オプションを指定する 1 つ以上の DVD_CMD_FLAGS 値を含むビット フラグ。
ppCmd
DVD コマンドの同期に使用できる IDvdCmd オブジェクトへのポインタ。

戻り値

次のいずれかの値を返す。

S_OK | 成功。
VFW_E_DVD_OPERATION_INHIBITED | UOP コントロールが処理を禁止している。
E_INVALIDARG | 無効な引数。

注意

実際の開始タイムおよび終了タイムは、DVD_HMSF_TIMECODE によって指定されるフレーム番号またはそれ以前の時間である。pStartTime および pEndTime ではフレーム レート コードは無視される。

次の表は、このメソッド名が対応する Annex J コマンド名、およびこのメソッドが有効なドメインを示している。

Annex J コマンド名 有効なドメイン
なし DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title
DVD_DOMAIN_Stop

参照

DVD コマンドの同期化

IDvdControl2::PlayPrevChapter

IDvdControl2 インターフェイス

現在のタイトルの前のチャプターの先頭から再生を開始する。

構文

HRESULT PlayPrevChapter(
    DWORD dwFlags,
    IDvdCmd **ppCmd
);

パラメータ

dwFlags
コマンド同期オプションを指定する 1 つ以上の DVD_CMD_FLAGS 値を含むビット フラグ。
ppCmd
DVD コマンドの同期に使用できる IDvdCmd オブジェクトへのポインタ。

戻り値

次のいずれかの値を返す。

S_OK | 成功。
VFW_E_DVD_OPERATION_INHIBITED | UOP コントロールが処理を禁止している。

注意

次の表は、このメソッド名が対応する Annex J コマンド名、およびこのメソッドが有効なドメインを示している。

このメソッドの使用例については、DVDSample アプリケーションの「CDvdCore::PrevChapter」を参照すること。
Annex J コマンド名 有効なドメイン
PrevPG_Search DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title

参照

DVD コマンドの同期化

IDvdControl2::PlayTitle

IDvdControl2 インターフェイス

指定されたタイトルの先頭から再生を開始する。

構文

HRESULT PlayTitle(
    ULONG uiTitle
    DWORD dwFlags,
    IDvdCmd **ppCmd
);

パラメータ

uiTitle
タイトル番号を指定する値。この値は 1 から 99 の間でなければならない。
dwFlags
コマンド同期オプションを指定する 1 つ以上の DVD_CMD_FLAGS 値を含むビット フラグ。
ppCmd
DVD コマンドの同期に使用できる IDvdCmd オブジェクトへのポインタ。

戻り値

次のいずれかの値を返す。

S_OK | 成功。
VFW_E_DVD_OPERATION_INHIBITED | UOP コントロールが処理を禁止している。
E_INVALIDARG | 無効な引数。

注意

次の表は、このメソッド名が対応する Annex J コマンド名、およびこのメソッドが有効なドメインを示している。

Annex J コマンド名 有効なドメイン
Title_Play DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title
DVD_DOMAIN_Stop

参照

DVD コマンドの同期化

IDvdControl2::ReplayChapter

IDvdControl2 インターフェイス

現在のチャプターの先頭から再生を開始する。

構文

HRESULT ReplayChapter(
    DWORD dwFlags,
    IDvdCmd **ppCmd
);

パラメータ

dwFlags
コマンド同期オプションを指定する 1 つ以上の DVD_CMD_FLAGS 値を含むビット フラグ。
ppCmd
DVD コマンドの同期に使用できる IDvdCmd オブジェクトへのポインタ。

戻り値

次のいずれかの値を返す。

S_OK | 成功。
VFW_E_DVD_OPERATION_INHIBITED | UOP コントロールが処理を禁止している。

注意

次の表は、このメソッド名が対応する Annex J コマンド名、およびこのメソッドが有効なドメインを示している。

Annex J コマンド名 有効なドメイン
TopPG_Search DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title

参照

DVD コマンドの同期化

IDvdControl2::Resume

IDvdControl2 インターフェイス

メニューから抜けて再生を再開する。

構文

HRESULT Resume(
    DWORD dwFlags,
    IDvdCmd **ppCmd
    );

パラメータ

dwFlags
コマンド同期オプションを指定する 1 つ以上の DVD_CMD_FLAGS 値を含むビット フラグ。
ppCmd
DVD コマンドの同期に使用できる IDvdCmd オブジェクトへのポインタ。

戻り値

次のいずれかの値を返す。

S_OK | 成功。
VFW_E_DVD_OPERATION_INHIBITED | UOP コントロールが処理を禁止している。
VFW_E_DVD_NO_RESUME_INFORMATION | ビデオ マネージャ メニューから Resume が呼び出された。

注意

このメソッドでは、再生を中断した位置から再生が再開される。

次の表は、このメソッド名が対応する Annex J コマンド名、およびこのメソッドが有効なドメインを示している。

このメソッドの使用例については、DVDSample アプリケーションの「CDvdCore::RootMenu」および「CDvdCore::TitleMenu」を参照すること。
Annex J コマンド名 有効なドメイン
Resume DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Stop

IDvdControl2::ReturnFromSubmenu

IDvdControl2 インターフェイス

表示をサブメニューからサブメニューの親メニューに戻す。

構文

HRESULT ReturnFromSubmenu(
    DWORD dwFlags,
    IDvdCmd **ppCmd
);

パラメータ

dwFlags
コマンド同期オプションを指定する 1 つ以上の DVD_CMD_FLAGS 値を含むビット フラグ。
ppCmd
DVD コマンドの同期に使用できる IDvdCmd オブジェクトへのポインタ。

戻り値

次のいずれかの値を返す。

S_OK | 成功。
VFW_E_DVD_OPERATION_INHIBITED | UOP コントロールが処理を禁止している。

注意

DVD ナビゲータが最上位メニューにある場合、このメソッドは Resume メソッドを呼び出し、再生を中断した位置から再生を再開させる。

次の表は、このメソッド名が対応する Annex J コマンド名、およびこのメソッドが有効なドメインを示している。

Annex J コマンド名 有効なドメイン
GoUP DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title

参照

DVD コマンドの同期化、DVD メニューの操作

IDvdControl2::SelectAndActivateButton

IDvdControl2 インターフェイス

指定されたメニュー ボタンを選択し、アクティブにする。

構文

HRESULT SelectAndActivateButton(
    ULONG ulButton
);

パラメータ

ulButton
[in] 選択し、アクティブにするボタンを指定する 1 から 36 の間の値。

戻り値

次のいずれかの値を返す。

S_OK | 成功。
E_INVALIDARG | ulButton が範囲外である。
E_UNEXPECTED | ulButton 値は有効であるが、DVD ナビゲータ フィルタがボタンをアクティブにすることができなかった。
VFW_E_DVD_OPERATION_INHIBITED | UOP コントロールが処理を禁止している。

注意

次の表は、このメソッド名が対応する Annex J コマンド名、およびこのメソッドが有効なドメインを示している。

Annex J コマンド名 有効なドメイン
Button_Select_And_Activate DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title

参照

DVD メニューの操作

IDvdControl2::SelectAngle

IDvdControl2 インターフェイス

DVD ナビゲータがアングル ブロックにある間、新しいアングルを設定する。

構文

HRESULT SelectAngle(
    ULONG ulAngle,
    DWORD dwFlags,
    IDvdCmd **ppCmd
);

パラメータ

ulAngle
[in] 新しいアングルの値。1 から 9 の間でなければならない。
dwFlags
[in] コマンド同期オプションを指定する 1 つ以上の DVD_CMD_FLAGS 値を含むビット フラグ。
ppCmd
[out] DVD コマンドの同期に使用できる IDvdCmd オブジェクトへのポインタのアドレス。

戻り値

次のいずれかの値を返す。

S_OK | 成功。
E_INVALIDARG | ulAngle が範囲外である。
VFW_E_DVD_INVALIDDOMAIN | DVD ナビゲータが First Play ドメイン内にある。
VFW_E_DVD_OPERATION_INHIBITED | UOP コントロールが処理を禁止している。

注意

オーディオ ストリームとサブピクチャ ストリームのインデックスは開始値が 0 であるが、アングルとメニュー ボタンのインデックスは開始値が 1 である点に注意すること。

次の表は、このメソッド名が対応する Annex J コマンド名、およびこのメソッドが有効なドメインを示している。

Annex J コマンド名 有効なドメイン
Angle_Change DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title
DVD_DOMAIN_Stop

参照

ドメイン

IDvdControl2::SelectAtPosition

IDvdControl2 インターフェイス

マウス ポインタの下にあるメニュー ボタンを強調表示する。

構文

HRESULT SelectAtPosition(
    POINT point
);

パラメータ

point
[in] 画面ピクセル座標で表す画面上の位置。

戻り値

次のいずれかの値を返す。

S_OK | 成功。
VFW_E_DVD_NO_BUTTON | マウス ポインタの位置にボタンがない。
VFW_E_DVD_INVALIDDOMAIN | DVD ナビゲータが Stop ドメイン内にある。

注意

オーディオ ストリームとサブピクチャ ストリームのインデックスは開始値が 0 であるが、アングルとメニュー ボタンのインデックスは開始値が 1 である点に注意すること。

ポインタがメニュー ボタン上にある場合は、マウスのクリックに応じて ActivateButton を呼び出す。

次の表は、このメソッド名が対応する Annex J コマンド名、およびこのメソッドが有効なドメインを示している。

このメソッドの使用例については、DVDSample の「CDvdCore::OnMouseEvent」を参照すること。

Annex J コマンド名 有効なドメイン
なし DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title
DVD_DOMAIN_FirstPlay

参照

ActivateAtPosition、ドメイン、DVD メニューの操作

IDvdControl2::SelectAudioStream

IDvdControl2 インターフェイス

再生するオーディオ ストリームを選択する。

構文

HRESULT SelectAudioStream(
    ULONG ulAudio,
    DWORD dwFlags,
    IDvdCmd **ppCmd
);

パラメータ

ulAudio
[in] 使用するオーディオ トラックを指定する値。0 から 7 の間の整数値でなければならない。デフォルトのストリームを指定するには、DVD_DEFAULT_AUDIO_STREAM を指定する。
dwFlags
[in] コマンド同期オプションを指定する 1 つ以上の DVD_CMD_FLAGS 値を含むビット フラグ。
ppCmd
[out] DVD コマンドの同期に使用できる IDvdCmd オブジェクトへのポインタのアドレス。

戻り値

次のいずれかの値を返す。

S_OK | 成功。
E_INVALIDARG | ulAudio が範囲外であるか、オーディオ ストリームに対応していない。
E_UNEXPECTED | ulAudio 値は有効であるが、何らかの理由で DVD ナビゲータが値を設定できなかった。
VFW_E_DVD_OPERATION_INHIBITED | UOP コントロールが処理を禁止している。
VFW_E_DVD_STREAM_DISABLED | 指定されたストリームが無効になっている。

注意

このメソッドは、現在のビデオ タイトル セット (VTS) のオーディオを対象とする。メニュー内からこのメソッドを呼び出した場合は、メニューを呼び出したタイトルのオーディオ ストリームが設定される。

次の表は、このメソッド名が対応する Annex J コマンド名、およびこのメソッドが有効なドメインを示している。

Annex J コマンド名 有効なドメイン
Audio_Stream_Change DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title
DVD_DOMAIN_Stop

IDvdControl2::SelectButton

IDvdControl2 インターフェイス

指定されたメニュー ボタンを選択する。

構文

HRESULT SelectButton(
    ULONG ulButton
);

パラメータ

ulButton
[in] 選択するボタンを指定する 1 から 36 の間の値。

戻り値

次のいずれかの値を返す。

S_OK | 成功。
VFW_E_DVD_INVALIDDOMAIN | DVD ナビゲータが無効なドメイン内にある。
VFW_E_DVD_NO_BUTTON | どのボタンも選択されていない。
VFW_E_DVD_OPERATION_INHIBITED | UOP コントロールにより、DVD ナビゲータがポーズ状態になることを禁止されている。

注意

次の表は、このメソッド名が対応する Annex J コマンド名、およびこのメソッドが有効なドメインを示している。

Annex J コマンド名 有効なドメイン
Button_Select DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title

参照

DVD メニューの操作

IDvdControl2::SelectDefaultAudioLanguage

IDvdControl2 インターフェイス

デフォルトのオーディオ言語を設定する。

構文

HRESULT SelectDefaultAudioLanguage(
    LCID Language
    DVD_AUDIO_LANG_EXT audioExtension
);

パラメータ

Language
[in] デフォルト言語を指定するロケール識別子。
audioExtension
[in] デフォルトのオーディオ言語拡張機能を指定する DVD_AUDIO_LANG_EXT 値。

戻り値

次のいずれかの値を返す。

S_OK | 成功。
E_INVALIDARG | audioExtension 値が無効である。
VFW_E_DVD_INVALIDDOMAIN | DVD ナビゲータ フィルタが Stop ドメイン内にある。

注意

このメソッドでは、ディスクを再生するときに使用するデフォルトの言語および言語拡張機能を選択する。たとえば、Language が英語に相当する 0x409 に指定されており、audioExtension が DVD_AUD_EXT_NotSpecified に指定されている場合、DVD ナビゲータは、英語の基本的なオーディオ ストリームを検索する。audioExtension が DVD_AUD_EXT_VisuallyImpaired に指定されている場合、DVD ナビゲータは、まず、視力が弱い人のための英語の特殊なオーディオ ストリームを検索する。デフォルトのストリームがディスク上で見つからない場合、DVD ナビゲータは、要求に最も近いストリームを選択する。

次の表は、このメソッド名が対応する Annex J コマンド名、およびこのメソッドが有効なドメインを示している。

Annex J コマンド名 | 有効なドメイン
なし | DVD_DOMAIN_Stop

IDvdControl2::SelectDefaultMenuLanguage

IDvdControl2 インターフェイス

すべてのメニューとメニュー ボタンで使用されるデフォルトの言語を設定する。

構文

HRESULT SelectDefaultMenuLanguage(
    LCID Language
);

パラメータ

Language
デフォルト言語を指定する LCID 型の変数。

戻り値

次のいずれかの値を返す。

S_OK | 成功。
E_INVALIDARG | 無効な引数。
VFW_E_DVD_INVALIDDOMAIN | DVD ナビゲータ フィルタが有効なドメイン内にない。

注意

このメソッドでは、ディスクを再生するときにメニューで使用するデフォルトのテキスト言語を選択する。たとえば、Language がアメリカ英語に相当する 0x409 に指定されている場合、DVD ナビゲータは、メニューにアメリカ英語のテキストを表示しようと試みる。デフォルトのメニュー言語がディスク上で見つからない場合、DVD ナビゲータは要求に最も近い言語を選択する。

次の表は、このメソッド名が対応する Annex J コマンド名、およびこのメソッドが有効なドメインを示している。

Annex J コマンド名 | 有効なドメイン
なし | DVD_DOMAIN_Stop

IDvdControl2::SelectDefaultSubpictureLanguage

IDvdControl2 インターフェイス

サブピクチャ テキストのデフォルトの言語を設定する。

構文

HRESULT SelectDefaultSubpictureLanguage(
    LCID Language
    DVD_SUBPICTURE_LANG_EXT subpictureExtension
);

パラメータ

Language
[in] デフォルト言語を指定するロケール識別子。
subpictureExtension
[in] デフォルトのサブピクチャ拡張機能を指定する DVD_SUBPICTURE_LANG_EXT 値。

戻り値

次のいずれかの値を返す。

S_OK | 成功。
E_INVALIDARG | Language が無効である。
VFW_E_DVD_INVALIDDOMAIN | DVD ナビゲータ フィルタが有効なドメイン内にない。

注意

このメソッドでは、ディスクの再生時にサブピクチャおよびメニューで使用するデフォルトの言語とフォーマットを選択する。たとえば、Language が英語に相当する 0x409 に指定されており、subpictureExtension が DVD_SP_EXT_Caption_Big に指定されている場合、DVD ナビゲータは、サブピクチャのテキストを "ビッグ キャプション" フォーマットのアメリカ英語で表示しようと試みる。デフォルトの言語または言語拡張機能がディスク上で見つからない場合、DVD ナビゲータは要求に最も近いものを選択する。

次の表は、このメソッド名が対応する Annex J コマンド名、およびこのメソッドが有効なドメインを示している。

Annex J コマンド名 | 有効なドメイン
なし | DVD_DOMAIN_Stop

IDvdControl2::SelectKaraokeAudioPresentationMode

IDvdControl2 インターフェイス

カラオケ補助チャンネルを左スピーカまたは右スピーカに送る。

構文

HRESULT SelectKaraokeAudioPresentationMode(
    ULONG ulMode
);

パラメータ

ulMode
[in] 5 つのカラオケ チャンネルをチャンネル 0 とチャンネル 1 にミックスダウンする方法を示す DVD_KARAOKE_DOWNMIX フラグのビットごとの OR。通常、チャンネル 0 とチャンネル 1 は左スピーカと右スピーカに出力される。

戻り値

次のいずれかの値を返す。

S_OK | 成功。
VFW_E_DVD_INVALIDDOMAIN | DVD ナビゲータ フィルタが無効なドメイン内にある。
VFW_E_DVD_OPERATION_INHIBITED | UOP コントロールが現在の操作を禁止している。

注意

DVD ナビゲータは、カラオケ モードに移行すると、オーディオ デコーダにカラオケ ダウンミキシングをサポートしているかどうかを問い合わせる。デコーダがカラオケ ダウンミキシングサポートしている場合は、チャンネル 2 からチャンネル 4 まで (ガイド ボーカル、ガイド メロディー、音響効果から構成されるカラオケ補助チャンネル) がミュートされる。このメソッドを使用して、チャンネルを個別にオン、オフし、チャンネル 0 とチャンネル 1 に割り当てる。

このメソッドの使用例については、DVDSample アプリケーションの「CKaraokeDlg::DoModal」を参照すること。

次の表は、このメソッド名が対応する Annex J コマンド名、およびこのメソッドが有効なドメインを示している。

Annex J コマンド名 有効なドメイン
Karaoke_Audio_Presentation_Mode_Change DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title
DVD_DOMAIN_Stop

IDvdControl2::SelectParentalCountry

IDvdControl2 インターフェイス

ペアレンタル ロック アクセス レベルを解釈し、デフォルト言語を設定するときの基準となる国を設定する。

構文

HRESULT SelectParentalCountry(
    BYTE country[2]
);

パラメータ

country
[in] ISO 3166 に従って現在の国を指定する BYTE 型の値の配列。

戻り値

次のいずれかの値を返す。

S_OK | 成功。
E_INVALIDARG | 無効な引数。
VFW_E_DVD_INVALIDDOMAIN | DVD ナビゲータ フィルタが有効なドメイン内にない。

注意

ペアレンタル カントリは、8 つの基本ペアレンタル ロック レベルの意味およびサウンドトラックとメニューのデフォルト言語を規定する。詳細については、「ペアレンタル ロック レベルの適用」を参照すること。

次の表は、このメソッド名が対応する Annex J コマンド名、およびこのメソッドが有効なドメインを示している。

Annex J コマンド名 | 有効なドメイン
Parental_Country_Select | DVD_DOMAIN_Stop

参照

IDvdControl2::SelectParentalLevel

IDvdControl2::SelectParentalLevel

IDvdControl2 インターフェイス

ログオンしているユーザーのペアレンタル ロック アクセス レベルを設定する。

構文

HRESULT SelectParentalLevel(
    ULONG ulParentalLevel
);

パラメータ

ulParentalLevel
現在のユーザーのペアレンタル ロック アクセス レベルを指定する値。詳細については、「注意」を参照すること。

戻り値

次のいずれかの値を返す。

S_OK | 成功。
E_INVALIDARG | 無効な引数。
VFW_E_DVD_INVALIDDOMAIN | 無効なドメイン。

注意

DVD の仕様では、1 (最も制限の多いレベル) から 8 (最も制限の少ないレベル) までの 8 つの基本ペアレンタル ロック レベルが定義されている。これらのレベルの意味は地域によって異なり、現在の国に依存する (「SelectParentalCountry」を参照)。アメリカ合衆国とカナダ (DVD リージョン 1) では、以下のレベルが提唱されている。
ペアレンタル ロック レベル | 意味
1 | 格付けは一般向けの G である。
3 | 格付けは保護者の指導が望ましい PG である。
4 | 格付けは保護者の指導が望ましく、13 歳未満の子供には推奨できない PG-13 である。
6 | 格付けは制限付きの R である。
7 | 格付けは 17 歳未満には不適切な NC-17 である。

このメソッドでは、現在のユーザーのアクセス レベルを設定する。このアクセス レベルによって、ユーザーが再生できるメディア ファイルが決まる。高いレベルは低いレベルのコンテンツを再生できるが、低いレベルは高いレベルのコンテンツを再生できない。たとえば、成人は子供向けのコンテンツを見ることができるが、子供は成人向けのコンテンツを見ることはできない。

DVD プレーヤー アプリケーションでは、現在のペアレンタル ロック レベルを上げる操作をパスワードによって保護するなど、ペアレンタル ロック レベルの設定を強制的に制限することができる。アプリケーションのユーザー インターフェイスには、レベルを設定し、チェックを完全に無効にする手段を持たせる必要がある。レベル 8 も許可しないようにディスクを作成することができるが、この場合はペアレンタル ロックが有効になっていると、有効なレベルがないため、だれもディスクを見ることができない。このようなディスクを見るには、ペアレンタル ロックを無効にする必要がある。DVD ナビゲータ フィルタのペアレンタル ロックは、デフォルトで無効になっている。

有効になっているペアレンタル ロックを無効にするには、ulParentalLevel として 0xffffffff を渡す。

このメソッドの使用例については、DVDSample アプリケーションの「CDvdCore::SetParentalLevel」を参照すること。

次の表は、このメソッド名が対応する Annex J コマンド名、およびこのメソッドが有効なドメインを示している。

Annex J コマンド名 | 有効なドメイン
Parental_Level_Select | DVD_DOMAIN_Stop

IDvdControl2::SelectRelativeButton

IDvdControl2 インターフェイス

指定された相対ボタン (上、下、右、左) を設定する。

構文

HRESULT SelectRelativeButton(
    DVD_RELATIVE_BUTTON buttonDir,
);

パラメータ

buttonDir
選択するボタンを示す DVD_RELATIVE_BUTTON 値。

戻り値

次のいずれかの値を返す。

S_OK | 成功。
VFW_E_DVD_INVALIDDOMAIN | DVD ナビゲータ フィルタが有効なドメイン内にない。
VFW_E_DVD_OPERATION_INHIBITED | UOP コントロールが処理を禁止している。

注意

次の表は、このメソッド名が対応する Annex J コマンド名、およびこのメソッドが有効なドメインを示している。

Annex J コマンド名 有効なドメイン
(Left/Right/Upper/Lower)_Button_Select DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title

参照

DVD_RELATIVE_BUTTON、DVD メニューの操作

IDvdControl2::SelectSubpictureStream

IDvdControl2 インターフェイス

表示するサブピクチャ ストリームを設定する。

構文

HRESULT SelectSubpictureStream(
    ULONG ulSubPicture,
    DWORD dwFlags,
    IDvdCmd **ppCmd
);

パラメータ

ulSubPicture
サブピクチャ ストリームを指定する値。0 から 31 の間または 63 でなければならない。
0-31 | ストリームが有効である。
63 | ストリームがダミー ストリーム、つまりミュートされた低ビットレート ストリームである。
dwFlags
[in] コマンド同期オプションを指定する 1 つ以上の DVD_CMD_FLAGS 値を含むビット フラグ。
ppCmd
[out] DVD コマンドの同期に使用できる IDvdCmd オブジェクトへのポインタのアドレス。

戻り値

次のいずれかの値を返す。

S_OK | 成功。
E_INVALIDARG | ulSubPicture が範囲外であるか、SP ストリームに対応していない。
E_UNEXPECTED | ulSubPicture パラメータは有効であるが、何らかの理由で DVD ナビゲータがこのパラメータを設定できない。
VFW_E_DVD_OPERATION_INHIBITED | UOP コントロールが処理を禁止している。
VFW_E_DVD_INVALIDDOMAIN | 無効なドメイン。
VFW_E_DVD_STREAM_DISABLED | 指定されたストリームが無効になっている。

注意

次の表は、このメソッド名が対応する Annex J コマンド名、およびこのメソッドが有効なドメインを示している。

Annex J コマンド名 有効なドメイン
Sub-picture_Stream_Change DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title
DVD_DOMAIN_Stop

参照

オーディオ ストリームとサブピクチャ ストリーム

IDvdControl2::SelectVideoModePreference

IDvdControl2 インターフェイス

指定された再生用のビデオ ディスプレイ モード (ワイド スクリーン、レターボックス、またはパン-スキャン) を設定する。

構文

HRESULT SelectVideoModePreference(
    ULONG ulPreferredDisplayMode
);

パラメータ

ulPreferredDisplayMode
[in] DVD コンテンツの新しいディスプレイ モードを指定する値。DVD_PREFERRED_DISPLAY_MODE 列挙型のメンバ。

戻り値

次のいずれかの値を返す。

S_OK | 成功。
E_INVALIDARG | 無効な引数。
VFW_E_DVD_INVALIDDOMAIN | 無効なドメイン。
VFW_E_DVD_OPERATION_INHIBITED | UOP コントロールが処理を禁止している。

注意

このメソッドでは、デフォルトのビデオ ウィンドウのアスペクト比を変更する。また、デフォルトのアスペクト比変換メカニズムを指定することもできる。

720×480 のソース ビデオをアスペクト比 16×9 に引き伸ばした変形 16×9 ソース ビデオは、以下のように表示される。

ワイドスクリーン 16×9 ビデオをクライアント出力ウィンドウの最大の 16×9 領域に置き、拡大する必要がある。ハイライト領域は 16×9 領域の内側に比例する。ブラック バーを上下または左右に追加して 16×9 領域を保持する必要がある。

パン スキャン 表示するビデオは、引き伸ばされた 16×9 ビデオから 4×3 サブウィンドウを取り出すことによって計算する。このとき、水平オフセットは MPEG-2 ビデオ ウィンドウのオフセットから得る。4×3 サブウィンドウを出力クライアント ウィンドウの最大の 4×3 領域に置く。ハイライト領域の座標は 4×3 出力ウィンドウに比例し、ソースの 16×9 ビデオには比例しない。ブラック バーを上下または左右に追加して 4×3 領域を保持する必要がある。

レターボックス 出力クライアント ウィンドウの最大の 4×3 領域を取り出すことによって 4×3 ディスプレイ領域を形成する。ブラック バーを上下または左右に追加して 4×3 領域を保持する必要がある。ソースの 16×9 ビデオを 4×3 サブウィンドウ内部の最大の 16×9 サブウィンドウ内に置く。ブラック バーをサブウィンドウの上下に追加して 16×9 領域を保持する必要がある。ハイライト領域の座標は、4×3 サブウィンドウに比例し、ソースの 16×9 ビデオには比例しない。ディスクで、16×9 領域の外ではあるが、4×3 ウィンドウの中にハイライト領域が表示されるように指定することが技術的に可能である。

4×3 ビデオの場合は、ビデオを出力クライアント ウィンドウの最大の 4×3 出力領域に表示する。ブラック バーを上下または左右に追加して 4×3 領域を保持する必要がある。

次の表は、このメソッド名が対応する Annex J コマンド名、およびこのメソッドが有効なドメインを示している。

Annex J コマンド名 有効なドメイン
Video_PresentationMode_Change DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title
DVD_DOMAIN_Stop

IDvdControl2::SetDVDDirectory

IDvdControl2 インターフェイス

DVD ナビゲータ フィルタが読み込む DVD ドライブを設定する。

構文

HRESULT SetDVDDirectory(
    LPCWSTR  pszwPath
);

パラメータ

pszwPath
[in] ルート ディレクトリのパスを指定する LPCWSTR 型の変数。

戻り値

次のいずれかの値を返す。

S_OK | 成功。
E_INVALIDARG | pszwPath パラメータが無効な DVD パスを指しているか、列挙中に DVD ドライブが見つからない。
E_UNEXPECTED | DVD ナビゲータが初期化されていない。
S_FALSE | pszwPath パラメータが NULL であり、DVD ナビゲータが DVD ボリュームを見つけられない。
VFW_E_DVD_INVALIDDOMAIN | 無効なドメイン。詳細については「注意」を参照すること。

注意

pszwPath が NULL の場合、DVD ナビゲータは利用可能なすべてのドライブ上で DVD ボリュームを選択しようと試みる。起動時、DVD ナビゲータは、ルート フォルダに VIDEO_TS フォルダを持つドライブをドライブ C から順番に自動的に検索する。したがって、SetDVDDirectory を呼び出す必要があるのは、コンピュータに複数の DVD ドライブがある場合、または DVD ドライブ文字が A または B の場合に限られる。パスを指定するときは、vide_ts フォルダを含める。

SetDVDDirectory("e:\video_ts");

一部の DVD ボリュームでは、"video_ts" 以外のディレクトリにビデオが格納されていることがある。一般に、追加の "DVD ボリューム" (通常は VIDEO_TS ディレクトリに格納される .IFO. VOB、および .BUP ファイルのセット) をディスク上のサブディレクトリに格納することができる。このディレクトリを指すようにルートを変更することにより、MSWebDVD はこの DVD ボリューム上で動作するようになる。その場合は、アクセス不能になる VIDEO_TS ルート内のタイトルとは異なる、新しいメニュー、タイトルなどのセットが利用可能になる。このようなディレクトリは "隠しディレクトリ" と呼ばれる。以下の例は、隠しディレクトリをルートとして設定する方法を示している。"hidden" はディスクの作成者がディレクトリに付けた名前が入るプレースホルダである。

SetDVDDirectory("d:\\webdvd\\hidden");

フィルタ グラフが動作しており、DVD ナビゲータが pszwPath によって指定されたディレクトリ内で DVD を見つけると、DVD ナビゲータは自動的にディスクの再生を開始する。この動作は DVD の仕様に準拠しており、これによって新しいディスクが正しく初期化されることが保証される。SetDVDDirectory から動作が戻った後、新しいディスクを自動的に再生したくない場合は、SetOption の DVD_ResetOnStop フラグを TRUE に設定し、フィルタ グラフ マネージャで IMediaControl::Stop を呼び出すことによってフィルタ グラフを停止する必要がある。DVD_ResetOnStop が FALSE に設定されている場合、SetDVDDirectory は VFW_E_DVD_INVALIDDOMAIN を返す。

このメソッドの使用例については、DVDSample アプリケーションの「CDvdCore::SetDirectory」を参照すること。

次の表は、このメソッド名が対応する Annex J コマンド名、およびこのメソッドが有効なドメインを示している。

Annex J コマンド名 | 有効なドメイン
なし | DVD_DOMAIN_Stop

IDvdControl2::SetGPRM

IDvdControl2 インターフェイス

汎用パラメータ レジスタ値を設定する。

構文

HRESULT SetGPRM(
    ULONG ulIndex
    WORD wValue
    DWORD dwFlags,
    IDvdCmd **ppCmd
);

パラメータ

ulIndex
[in] レジスタ インデックス。0 から 15 の値。
wValue
[in] 指定されたレジスタに格納される 16 ビットの値。
dwFlags
[in] コマンド同期オプションを指定する 1 つ以上の DVD_CMD_FLAGS 値を含むビット フラグ。
ppCmd
[out] DVD コマンドの同期に使用できる IDvdCmd オブジェクトへのポインタのアドレス。

戻り値

次のいずれかの値を返す。

S_OK | 成功。
E_INVALIDARG | ulIndex パラメータが 15 を超えているか、ほかのいずれかの入力パラメータが無効である。

注意

DVD ディスクは汎用パラメータ レジスタを使ってさまざまな種類の情報を格納する。これらのレジスタを 1 つ以上手動で設定することにより、アプリケーションに特定のカスタム機能を持たせることができる。これは高度なコマンドであり、DVD の仕様を完全に理解していない場合は使用しない方がよい。

次の表は、このメソッド名が対応する Annex J コマンド名、およびこのメソッドが有効なドメインを示している。

Annex J コマンド名 | 有効なドメイン
なし | すべて

参照

IDvdInfo2::GetAllGPRMs

IDvdControl2::SetOption

IDvdControl2 インターフェイス

DVD ナビゲータ フィルタの内部動作フラグを有効または無効にする。

構文

HRESULT SetOption(
    DVD_OPTION_FLAG flag
    BOOL bEnable
);

パラメータ

flag
[in] 変更するフラグを指定する DVD_OPTION_FLAG 値。詳細については「注意」を参照すること。
bEnable
[in] flag を有効にするか無効にするかを指定する BOOL 型の変数。flag を有効にするには TRUE に設定し、無効にするには FALSE に設定する。

戻り値

次のいずれかの値を返す。

S_OK | 成功。
E_INVALIDARG | flag 値が DVD_ResetOnStop または DVD_NotifyParentalLevelChange でない。

注意

DVD ナビゲータのインスタンスを作成した直後、およびいずれかの動作を変更したい場合は、必ず目的のフラグを指定して SetOption を呼び出す。
フラグ | 意味
DVD_ResetOnStop このフラグを TRUE に設定すると、フィルタ グラフが停止したときに、ナビゲータは DVD Stop ドメインに入る。これはデフォルトの動作である。ナビゲータが Stop ドメインから再生を再開するときは、ディスクの先頭から再生が行われる。画面の解像度が変わったり、スクリーン セーバーが起動したり、コンピュータがサスペンド モードに入ったりすることにより、あるいはほかの理由によって、フィルタ グラフが突然停止することがあるため、この動作は望ましくないことがある。グラフが Stop 状態に移行したときにナビゲータが DVD Stop ドメインに入ることを防止するには、このフラグを FALSE に設定する。フラグを FALSE に設定すると、フィルタ グラフが動作を再開したとき、ナビゲータは前回停止した位置から再生を再開する。

通常、アプリケーションでは、IMediaControl::Run を呼び出して DVD-Video の再生を開始した直後あるいは再生を開始する前に、このフラグを FALSE に設定する必要がある。アプリケーションは、再生を停止するための明示的なユーザー コマンドに応えて IMediaControl::Stop を呼び出す前に、このフラグを TRUE に設定する必要がある。

DVD_NotifyParentalLevelChange このフラグでは、ディスク上でペアレンタル ロック レベルの変更が発生したときに、DVD ナビゲータがアプリケーションに通知する必要があるかどうかを指示する。このフラグを TRUE に設定すると、ナビゲータは、一時ペアレンタル ロック レベル コマンドが発生したときに、アプリケーションに EC_DVD_PARENTAL_LEVEL_CHANGE イベントを送信し、AcceptParentalLevelChange を通じてアプリケーションの応答を受信するまで、動作をブロックする。

このフラグが FALSE に設定されていると、ナビゲータが一時ペアレンタル ロック レベル コマンドを受け取り、現在のペアレンタル ロック レベルが低すぎる場合に、ナビゲータはコマンドを自動的に拒否し、そのコマンドが拒否されたときに移動するようにディスク上で指示されているパスに分岐する。次に、どのレベルが必要かをアプリケーションに通知する EC_DVD_PARENTAL_LEVEL_CHANGE イベントを送信する。次回の試行が成功するように、再生を停止し、パスワード ダイアログ ボックスを表示し、ムービーの再生を再開するかどうかは、アプリケーション側で判断する。

DVD_HMSF_TimeCodeEvents | EC_DVD_CURRENT_TIME イベントと共に渡される旧来の BCD フォーマットではなく、DVD_HMSF_TIMECODE フォーマットで EC_DVD_CURRENT_HMSF_TIME タイム イベントを受信するときに、このフラグを TRUE に設定する。DVD_HMSF_TIMECODE フォーマットの方が扱いやすい。BCD フォーマットを使用するアプリケーションとの下位互換性を保つために、このフラグは、デフォルトでは FALSE に設定される。

次の表は、このメソッド名が対応する Annex J コマンド名、およびこのメソッドが有効なドメインを示している。

Annex J コマンド名 | 有効なドメイン
なし | すべて

参照

DVD コマンド フラグ

IDvdControl2::SetState

IDvdControl2 インターフェイス

現在のディスクの位置と DVD ナビゲータ フィルタの状態を保存する。

構文

HRESULT SetState(
    IDvdState*pState,
    DWORD    dwFlags,
    IDvdCmd  **ppCmd
);

パラメータ

pState
[in] ステート情報が格納されているオブジェクトの IDvdState インターフェイスへのポインタ。
dwFlags
[in] コマンド同期オプションを指定する 1 つ以上の DVD_CMD_FLAGS 値を含むビット フラグ。
ppCmd
[out] DVD コマンドの同期に使用できる IDvdCmd オブジェクトへのポインタのアドレス。

戻り値

成功すれば S_OK を返す。それ以外の場合は HRESULT 値を返す。

注意

DVD ナビゲータは、指定された状態オブジェクトに格納された位置情報を使って、再生位置をディスク上の特定の位置に戻す。

このメソッドの使用例については、DVDSample アプリケーションの「CDvdCore::RestoreBookmark」を参照すること。

IDvdControl2::SetSubpictureState

IDvdControl2 インターフェイス

サブピクチャの表示をオン、オフする。

構文

HRESULT SetSubpictureState(
    BOOL bState,
    DWORD dwFlags,
    IDvdCmd **ppCmd
);

パラメータ

bState
[in] サブピクチャの表示をオンにするかどうかを指定するブール型の値。TRUE を指定すると、それ以降の再生でサブピクチャが表示される。
dwFlags
[in] コマンド同期オプションを指定する 1 つ以上の DVD_CMD_FLAGS 値を含むビット フラグ。
ppCmd
[out] DVD コマンドの同期に使用できる IDvdCmd オブジェクトへのポインタのアドレス。

戻り値

次のいずれかの値を返す。

S_OK | 成功。
VFW_E_DVD_INVALIDDOMAIN | DVD ナビゲータが First Play ドメイン内にある。
VFW_E_DVD_OPERATION_INHIBITED | UOP コントロールが処理を禁止している。

注意

通常、サブピクチャ ストリームは、メニューではボタン テキストやボタンのグラフィックに、ビデオの再生では字幕、クレジット、その他のオーバーレイ グラフィックに使用される。サブピクチャをクローズド キャプションと混同してはならない。クローズド キャプションは、ビデオ ストリームの内部にエンコードされている。一般的に、このメソッドは、DVD ナビゲータ フィルタが DVD Title ドメイン内でビデオを再生している間にビデオに重ねて表示されるサブピクチャを制御することを目的としている。

このメソッドは、Annex J "Sub-picture_Stream_Change" コマンドの第 2 パラメータに相当する。

次の表は、このメソッド名が対応する Annex J コマンド名、およびこのメソッドが有効なドメインを示している。

Annex J コマンド名 有効なドメイン
Sub-picture_stream_Change DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title
DVD_DOMAIN_Stop

参照

SelectSubpictureStream

IDvdControl2::ShowMenu

IDvdControl2 インターフェイス

指定されたメニューがあれば表示する。

構文

HRESULT ShowMenu(
    DVD_MENU_ID MenuID
    DWORD dwFlags,
    IDvdCmd **ppCmd
);

パラメータ

MenuID
[in] 表示するメニューを指定する DVD_MENU_ID 値。
dwFlags
コマンド同期オプションを指定する 1 つ以上の DVD_CMD_FLAGS 値を含むビット フラグ。
ppCmd
コマンドを DVD ナビゲータ フィルタと同期させるために使用できる IDvdCmd オブジェクトへのポインタのアドレス。

戻り値

次のいずれかの値を返す。

S_OK | 成功。
E_INVALIDARG | MenuID 値が範囲外である。
VFW_E_DVD_INVALIDDOMAIN | 無効なドメイン。
VFW_E_DVD_OPERATION_INHIBITED | UOP コントロールが処理を禁止している。

注意

ビデオ マネージャ メニュー (VMGM) は、Title ドメインまたは Video Title Set ドメインからアクセスできなければならない。ビデオ タイトル セット メニュー (VTSM) は、VMGM を通じてしかアクセスできなくてもよい。各 VTSM (チャプター、アングル、オーディオ ストリーム、サブピクチャ ストリーム用) の下のサブメニューは、その VTSM を通じてしかアクセスできない。

このメソッドの使用例については、DVDSample アプリケーションの「CDvdCore::RootMenu」および「CDvdCore::TitleMenu」を参照すること。

次の表は、このメソッド名が対応する Annex J コマンド名、およびこのメソッドが有効なドメインを示している。

Annex J コマンド名 | 有効なドメイン
Menu_Call | すべて

参照

DVD メニューの操作

IDvdControl2::StillOff

IDvdControl2 インターフェイス

再生を再開し、静止モードをキャンセルする。

構文

HRESULT StillOff(void);

戻り値

次のいずれかの値を返す。

S_OK | 成功。
E_UNEXPECTED | DVD ナビゲータ フィルタがメニュー ドメイン内にあり、メニューにボタンがある。
VFW_E_DVD_INVALIDDOMAIN | 無効なドメイン。
VFW_E_DVD_OPERATION_INHIBITED | UOP コントロールが処理を禁止している。

注意

still はディスクに格納されている静止画像である。これは、ユーザーが Pause ボタンをクリックしたときに表示される静止画とは異なる。DVD ナビゲータは静止画像を検出すると、アプリケーションに EC_DVD_STILL_ON メッセージを送信し、静止画保持モードに移行して画像を表示し、StillOff が呼び出されるまで再生を再開しない。

DVD ナビゲータが静止画保持モードになっていない場合、このメソッドは何もしない。

メニューを静止画として表示することもできるが、メニュー ドメインでは DVD ナビゲータが再生再開位置の情報を取得できないため、メニュー ドメイン内でこのメソッドを呼び出してはならない。

次の表は、このメソッド名が対応する Annex J コマンド名、およびこのメソッドが有効なドメインを示している。

Annex J コマンド名 有効なドメイン
Still_Off DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title

IDvdControl2::Stop

IDvdControl2 インターフェイス

DVD ナビゲータを DVD Stop ドメインに移行させることにより、タイトルまたはメニューの再生を停止する。

構文

HRESULT Stop(void);

戻り値

次のいずれかの値を返す。

S_OK | 成功。
VFW_E_DVD_INVALIDDOMAIN | 無効なドメイン。

注意

このメソッドを呼び出すと、DVD ナビゲータは Stop ドメインに移行するが、DVD フィルタ グラフ全体は、いつでも再生を再開できる実行状態にとどまる。ユーザーは Stop ドメインからメニューを表示したり、任意の "Play" メソッドを使って再生を直接開始したりすることができる。

次の表は、このメソッド名が対応する Annex J コマンド名、およびこのメソッドが有効なドメインを示している。

Annex J コマンド名 有効なドメイン
Stop DVD_DOMAIN_FirstPlay
DVD_DOMAIN_VideoManagerMenu
DVD_DOMAIN_VideoTitleSetMenu
DVD_DOMAIN_Title


IDvdGraphBuilder インターフェイス

IDvdGraphBuilder インターフェイスは、DVD グラフ ビルダ オブジェクトで実装される。RenderDvdVideoVolume メソッドは、システム上の利用可能なソフトウェアとハードウェアから、DVD ビデオを再生するためのフィルタ グラフを自動的に作成する。DVD フィルタ グラフを作成する方法と、必要なすべてのインターフェイスへのポインタを入手する方法については、「DVD フィルタ グラフの作成」を参照すること。DVDSample アプリケーションの DvdCore.cpp にも、この過程が示されている。

注 : DVD フィルタ グラフは、ハードウェアまたはソフトウェアの MPEG-2 デコーダを必要とする。これは DirectShow には含まれていない。そこで、DVD フィルタ グラフの作成に先立ち、DirectShow 互換のサードパーティ製のデコーダをコンピュータにインストールする必要がある。

一般に、RenderDvdVideoVolume で作成されたグラフ内の個別のフィルタを追加、削除、接続、切断、またはアクセスしてはならない。これらの操作を行うと、クリーンアップ コードに混乱をきたす場合がある。DvdGraphBuilder オブジェクトの目的は、DVD ビデオ アプリケーションの開発を簡略化することである。特別な目的を持つ特殊なグラフが必要な場合は、フィルタ グラフ全体を手動で作成する必要がある。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IDvdGraphBuilder メソッド | 説明
GetFiltergraph | DVD ビデオ グラフ ビルダ オブジェクトが使用するフィルタ グラフの IGraphBuilder インターフェイスを取得する。
GetDvdInterface | DVD ビデオ再生グラフ内の特定のインターフェイス ポインタを取得する。これによって、DVD ビデオ再生の開発が簡略化される。
RenderDvdVideoVolume | DVD ビデオのボリューム再生に関するユーザー指定に従って、フィルタ グラフの作成を完了する。

IDvdGraphBuilder::GetDvdInterface

IDvdGraphBuilder インターフェイス

DVD ビデオ再生グラフ内の特定のインターフェイス ポインタを取得する。これによって、DVD ビデオ再生の開発が簡略化される。

構文

HRESULT GetDvdInterface(
    REFIID riid,
    void **ppvIF
    );

パラメータ

riid
[in] 目的のインターフェイスの IID。
ppvIF
[out] 取得されたインターフェイスへのポインタのアドレス。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

DirectShow の実装が返す値には、次の値が含まれる。
E_INVALIDARG | ppvIF パラメータが無効である。
E_NOINTERFACE | riid パラメータ値がサポートされていない。
VFW_E_DVD_GRAPHNOTREADY | このインターフェイスを取得する以前に、IDvdGraphBuilder::RenderDvdVideoVolume メソッドを介してグラフが作成されていない。

注意

このメソッドを使用して、IDvdControl2 と IDvdInfo2 インターフェイスを取得して DVD ビデオ ボリュームの再生を制御したり、IAMLine21Decoder インターフェイスを取得してクローズド キャプション表示のオンとオフを切り替えること。このメソッドを使用して、IBasicVideo、IVideoWindow、および IBasicAudio の各インターフェイスを取得することもできる。オーディオ レンダラがオーディオをレンダリングする場合のみ、IBasicAudio へのポインタが必要である。

インターフェイスの使用が終了したら、次のコードを使用してこれを解放する必要がある。

*ppvIF->Release();

このインターフェイスを使用すると、DVD ビデオ再生グラフ内のオーバーレイ ミキサーの先頭の入力ピン (プライマリ ビデオ ストリーム) から、IMixerPinConfig2 インターフェイスを取得できる。DVD ビデオ グラフ内のオーバーレイ ミキサーから、IDDrawExclModeVideo インターフェイスも取得できる。このインターフェイスは、ゲームによっては、DirectDraw の排他モードでビデオを再生するときに必要である。ほかのインターフェイスとは異なり、GetDvdInterface を呼び出す前に、RenderDvdVideoVolume メソッドを使用してグラフを作成する必要はない。このインターフェイスは、RenderDvdVideoVolume メソッドを使用してグラフを作成する前に取得する必要がある。

IDvdGraphBuilder::GetFiltergraph

IDvdGraphBuilder インターフェイス

DVD ビデオ グラフ ビルダ オブジェクトが使用するフィルタ グラフの IGraphBuilder インターフェイスを取得する。

構文

HRESULT GetFiltergraph(
    IGraphBuilder **ppGB
    );

パラメータ

ppGB
[out] DVD ビデオ グラフ ビルダ オブジェクトが使用している IGraphBuilder インターフェイスへのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。現在の DirectShow の実装では、ppGB が無効の場合、E_INVALIDARG を返す。

注意

IGraphBuilder インターフェイスの使用が終了したら、次のコードを使用してこれを解放する必要がある。

*ppGB->Release();

IDvdGraphBuilder::RenderDvdVideoVolume

IDvdGraphBuilder インターフェイス

DVD ビデオのボリューム再生に関するユーザー指定に従って、フィルタ グラフの作成を完了する。

構文

HRESULT RenderDvdVideoVolume(
    LPCWSTR lpcwszPathName,
    DWORD dwFlags,
    AM_DVD_RENDERSTATUS *pStatus
    );

パラメータ

lpcwszPathName
[in] 再生する DVD ビデオ ボリュームのパスへのポインタ。NULL の場合がある。
dwFlags
[in] デコーダのタイプを示す AM_DVD_GRAPH_FLAGS 列挙型のメンバ。デコーダのタイプには、ハードウェア、ソフトウェア、またはハードウェアとソフトウェアの混合があり、指定されたデコーダがフィルタ グラフに含まれる。デフォルト値は、最大ハードウェア デコード (AM_DVD_HWDEC_PREFER) である。
pStatus
[out] 取得された AM_DVD_RENDERSTATUS 構造体へのポインタ。障害があった場合は、その障害が構造体に示される。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。DirectShow の実装の戻り値には、次の値が含まれる。
E_INVALIDARG | dwFlags パラメータが指定するオプションが競合している。または、pStatus のポインタが不良である。
S_FALSE | グラフは作成されたが、完全ではない。pStatus パラメータに、問題の詳細が返される。
S_OK | 成功。再生グラフが正しく作成され、すべてのストリームがレンダリングされ、DVD ビデオ ボリュームが指定された、または見つかった。
VFW_E_DVD_DECNOTENOUGH | AM_DVD_HWDEC_ONLY または AM_DVD_SWDEC_ONLY が指定されたが、ハードウェアまたはソフトウェアのデコーダが足りないために、すべてのストリームをデコードできない。
VFW_E_DVD_RENDERFAIL | グラフの作成中に、何らかの基本的なエラーが発生した。DVD ナビゲータ フィルタ、ビデオ レンダラ、またはオーディオ レンダラがインスタンス化されていない、接続やピン列挙が単に失敗した、またはストリームがレンダリングされない、などが原因として考えられる。

注意

AM_DVD_RENDERSTATUS 構造体は、このメソッドの失敗コードを表す。このメソッドが S_FALSE を返す原因には、次のものが含まれる。

  • グラフは完全に作成されたが、次のいずれかの条件が該当する。
    • オーバーレイ ミキシングが動作しない。アプリケーションは AM_DVD_NOVPE フラグを使用していないので、ビデオ ストリームをオーバーレイ ミキサーに設定できない。このケースでは、ビデオがソフトウェアでデコードされていれば、アプリケーションはユーザーに対して、ビデオが表示されないことを伝える情報を持つことができる。ハードウェア デコード ビデオは、ハードウェア ビデオ デコーダの NTSC 出力ポートに接続している TV 上でのみ表示される。
    • ビデオ デコーダが Line 21 データを生成しない。アプリケーションでは、デコーダが原因でクローズド キャプションが利用できないことを伝える警告やメッセージを表示できる。
    • ボリューム パスが指定されていないので、再生する DVD ビデオ ボリュームを DVD ナビゲータが検索できない。再生が開始するときに、ドライブに DVD ビデオ ディスクがセットされていない場合、アプリケーションはユーザーにディスクを挿入するように求めることができる。
  • 一部のストリームがレンダリングされなかった、またはストリームがまったくレンダリングされなかった。アプリケーションでは、ユーザーに対して、一部のストリームを再生できないことを伝えることができる。

このメソッドを使用すると、DVD ビデオ フィルタや再生するボリュームを理解していなくても、グラフを作成できる。DVD ビデオ グラフ ビルダは、lpcwszPathName が NULL であったり、DVD ナビゲータ フィルタがデフォルトで再生する DVD ビデオ ボリュームを見つけることができなかった場合でも、グラフを作成することができる。アプリケーションでは、IDvdControl::SetRoot メソッドを使用することで、後でボリュームを指定できる。


IDvdInfo2 インターフェイス

DVD ナビゲータ ソース フィルタによって実装される IDvdInfo2 インターフェイスは、ディスクのさまざまな属性や DVD ナビゲータの状態を問い合わせるメソッドを備えている。IDvdInfo2 は、IDvdControl2 と対になるインターフェイスである。IDvdInfo2 は DVD ナビゲータの "get" メソッドの集合であり、IDvdControl2 は "set" メソッドの集合である。これら 2 つのインターフェイスは、DVD Annex J 仕様の範囲を超える DVD のナビゲーション機能と再生機能を備えている。

注 : これらのメソッドの一部が提供する情報は、DVD ナビゲータからアプリケーションのメッセージ ループに送信されるイベント通知を通じて取得することもできる。たとえば、現在の DVD ドメインを取得するには、IDvdInfo2::GetCurrentDomain を呼び出したり、アプリケーションのメッセージ ループで EC_DVD_DOMAIN_CHANGE イベントを処理し、イベントの lParam1 パラメータから新しいドメインを抽出することもできる。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IDvdInfo2 メソッド | 説明
メニュー
GetButtonAtPosition | 表示ウィンドウ内の指定された位置にあるボタンを取得する。
GetButtonRect | 指定されたボタンの矩形の座標を取得する。
GetCurrentButton | 利用できるボタンの数と現在選択されているボタンの番号を取得する。
GetDefaultMenuLanguage | デフォルトのメニュー言語を取得する。
GetMenuLanguages | ディスク上のすべてのメニューで利用できるすべての言語を取得する。
GetVMGAttributes | ビデオ マネージャ メニューのすべてのビデオ ストリーム、オーディオ ストリーム、およびサブピクチャ ストリームの属性を取得する。
タイトル
GetNumberOfChapters | 指定されたタイトルのチャプターの数を取得する。
GetTitleAttributes | 指定されたタイトルとそのメニューのすべてのビデオ ストリーム、オーディオ ストリーム、およびサブピクチャ ストリームの属性を取得する。
GetTotalTitleTime | 現在のタイトルの総再生時間を取得する。
ディスク情報
GetAllSPRMs | すべてのシステム パラメータ レジスタ (SPRM) の現在の内容を取得する。
GetAllGPRMs | すべての汎用パラメータ レジスタ (GPRM) の現在の内容を取得する。
GetCurrentUOPS | コンテンツの作成者が明示的に無効にしたナビゲーション コマンドが現在のディスク位置にあれば、それを示すフラグのセットを取得する。
GetDiscID | 指定された DVD に対してシステムが生成した 64 ビットの "一意" な識別番号を取得する。
GetDVDVolumeInfo | 現在の DVD ボリューム情報を取得する。
ビデオ ストリーム
GetCurrentAngle | 現在のアングル ブロック内の利用できるアングルの数と現在選択されているアングル番号を取得する。
GetCurrentVideoAttributes | 現在のタイトルまたはメニューのビデオ属性を取得する。
オーディオ ストリーム
GetAudioAttributes | 現在のタイトルまたはメニューの指定されたオーディオ ストリームの属性を取得する。
GetAudioLanguage | 現在のタイトル内の指定されたオーディオ ストリームの言語を取得する。
GetCurrentAudio | 利用できるオーディオ ストリームの数と現在選択されているオーディオ ストリームの番号を取得する。
GetDecoderCaps | DVD デコーダのビデオ、オーディオ、およびサブピクチャの最大データ レート (逆方向および順方向) と、サポートしているオーディオの種類 (Dolby AC-3、MPEG-2、DTS、SDDS、LPCM) を取得する。
GetDefaultAudioLanguage | デフォルトのオーディオ言語を取得する。
GetKaraokeAttributes | 現在のタイトルまたはメニューの指定されたオーディオ ストリームのカラオケ属性を取得する。
IsAudioStreamEnabled | 指定されたオーディオ ストリームが現在のタイトルで有効になっているかどうかを判別する。
サブピクチャ ストリーム
GetCurrentSubpicture | 現在のタイトルの利用できるサブピクチャ ストリームの数、現在選択されているサブピクチャ ストリーム番号、およびサブピクチャの状態を取得する。
GetDefaultSubpictureLanguage | デフォルトのサブピクチャ言語を取得する。
GetSubpictureAttributes | 現在のタイトルまたはメニューの指定されたサブピクチャ ストリームの属性を取得する。
GetSubpictureLanguage | 現在のタイトル内の指定されたサブピクチャ ストリームの言語を取得する。
IsSubpictureStreamEnabled | 指定されたサブピクチャ ストリームが現在のタイトルで有効になっているかどうかを判別する。
ペアレンタル ロック レベル
GetPlayerParentalLevel | DVD ナビゲータの現在のペアレンタル ロック レベルおよび ISO 3166 国コードの設定を取得する。
GetTitleParentalLevels | 特定のタイトルに定義されているペアレンタル ロック レベルを取得する。
DVD ナビゲータ ステート情報
GetCmdFromEvent | EC_DVD_CMD_START イベント、EC_DVD_CMD_END イベントまたは VFW_E_DVD_CMD_CANCELLED イベントから IDvdCmd オブジェクトを取得する。
GetCurrentDomain | 現在 DVD ナビゲータが置かれている DVD ドメインを取得する。
GetCurrentLocation | 現在の再生位置を取得する。
GetDVDDirectory | DVD ナビゲータで設定されているルート ディレクトリを取得する。
GetState | ディスク位置と DVD ナビゲータ ステート情報が格納されているブックマークを取得する。
DVD テキスト文字列
GetDVDTextNumberOfLanguages | 現在の DVD またはディスク面のテキスト言語の数を取得する。
GetDVDTextLanguageInfo | 指定されたテキスト文字列言語ブロックの情報を取得する。
GetDVDTextStringAsNative | 指定された言語のテキスト文字列をバイトの配列として取得する。
GetDVDTextStringAsUnicode | 指定された言語のテキスト文字列を Unicode™ で取得する。

IDvdInfo2::GetAllGPRMs

IDvdInfo2 インターフェイス

すべての汎用パラメータ レジスタ (GPRM) の現在の内容を取得する。

構文

HRESULT GetAllGPRMs(
  GPRMARRAY *pRegisterArray
);

パラメータ

pRegisterArray
[out] 16 個の現在の GPRM 値すべてを受け取る GPRMARRAY へのポインタ。「注意」を参照すること。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_POINTER | 無効な引数。

注意

GPRM は、各ディスクが一時的にデータを格納するためにそれぞれ独自の方法で使用できる 16 ビット レジスタである。Dvdif.idl ファイルには、以下の typedef が含まれている。

typedef WORD DVD_REGISTER;
typedef DVD_REGISTER    GPRMARRAY[16];
typedef DVD_REGISTER    SPRMARRAY[24];

注 : DVD ナビゲータを使用するプレーヤー アプリケーションは、Annex J の再生機能またはナビゲーション制御機能を使用する限り、これらのレジスタにアクセスする必要はない。このメソッドは、高度な機能を実装したプレーヤー アプリケーション用に用意されている。DVD の仕様および再生する特定のディスクでの GPRM の使用法が完全にわかっていない限り、直接 GPRM を変更しない方がよい。

参照

IDvdControl2::SetGPRM

IDvdInfo2::GetAllSPRMs

IDvdInfo2 インターフェイス

すべてのシステム パラメータ レジスタ (SPRM) の現在の内容を取得する。

構文

HRESULT GetAllSPRMs(
  SPRMARRAY *pRegisterArray
);

パラメータ

pRegisterArray
[out] SPRM の配列のアドレスを受け取る SPRMARRAY 型の変数へのポインタ。「注意」を参照すること。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_POINTER | 無効な引数。

注意

24 個の SPRM を使って、現在の言語、サブピクチャ、およびその他のナビゲーション データに関する情報を格納する。Dvdif.idl ファイルには、以下の typedef が含まれている。

typedef WORD DVD_REGISTER;
typedef DVD_REGISTER    GPRMARRAY[16];
typedef DVD_REGISTER    SPRMARRAY[24];

注 : プレーヤー アプリケーションは、標準ナビゲーション機能を使う限り、これらのレジスタにアクセスする必要はない。これらのレジスタを有効に活用するには、このドキュメントに記載されている内容より詳しい DVD ナビゲーション コマンドに関する知識が必要になる。以下の表は、各レジスタの内容の一覧を示している。ワード内のビットは、b0 (最下位ビット) から b15 (最上位ビット) として表記されている。

レジスタ | コンテンツ
0 | ISO-639 言語コード (小文字 2 文字の ASCII 文字)。デフォルトの値が定義されていない。
1 | 下位 4 ビット (b0 ～ b3) にオーディオ ストリーム番号 (0 ～ 7) または 15 (なし) が格納される。デフォルト値は 15。
2 | 下位 6 ビット (b0 ～ b5) にサブピクチャ番号 (0 ～ 31) または 62 (なし) または 63 (強制サブピクチャ用のダミー ストリーム) が格納される。第 7 ビット (b6) にサブピクチャ表示フラグ (0 = サブピクチャを表示しない) が格納される。デフォルト値は 62。
3 | 下位 4 ビット (b0 ～ b3) にアングル番号 (1 ～ 9) が格納される。デフォルト値は 1。
4 | 下位 7 ビット (b0 ～ b6) にタイトル番号 (1 ～ 99) が格納される。デフォルト値は 1。
5 | 下位 7 ビット (b0 ～ b6) に現在の VTS 内のタイトル番号 (1 ～ 99) が格納される。デフォルト値は 1。
6 | 下位 15 ビット (b0 ～ b14) に現在のタイトル内の PGC 番号 (1 ～ 32767) が格納される。デフォルトの値が定義されていない。
7 | 下位 10 ビット (b0 ～ b9) にチャプター番号 (1 ～ 99) が格納される。デフォルト値は 1 である。タイトルが one_sequential_PGC_title でない場合、値は未定義になる。
8 | 上位 6 ビット (b10 ～ b15) にボタン番号 (1 ～ 36) が格納される。デフォルト値は 1024 (ボタン 1) である。
9 | 秒単位のタイマ カウント (0 ～ 65535)。デフォルト値は 0。
10 | 下位 15 ビット (b0 ～ b14) に現在のタイトル内の PGC 番号 (1 ～ 32767) が格納される。デフォルトの値が定義されていない。
11 | 6 個のフラグ (b2: ミックス ch2 を ch1 へ、b3: ミックス ch3 を ch1 へ、b4: ミックス ch4 を ch1 へ、 b10: ミックス ch2 を ch0 へ、b11: ミックス ch3 を ch0 へ、b12: ミックス ch4 を ch0 へ)。フラグ値 0 はミックスしないことを意味する。すべてのフラグのデフォルト値は 0 である。カラオケ ストリームを再生しない場合、値は未定義になる。
12 | ISO-3166 国コード (大文字 2 文字の ASCII 文字) または 65535 (指定なし)。デフォルトの値が定義されていない。
13 | 下位 4 ビット (b0 ～ b3) にペアレンタル ロック レベル (1 ～ 8) または 15 (なし) が格納される。デフォルトの値が定義されていない。
14 | b8 ～ b9 に優先ディスプレイ モード (0 = 4:3、3 = 16:9) が格納される。b10 ～ b11 に現在のビデオ出力モード (0 = 標準 [4:3 または 16:9]、1 = パン-スキャン、2 = レターボックス) が格納される。デフォルトの値が定義されていない。
15 | 9 個のフラグ (b2: SDDS カラオケ、b3: DTS カラオケ、b4: MPEG カラオケ、b6: Dolby Digital カラオケ、b7: PCM カラオケ、b10: SDDS 再生、b11: DTS 再生、b12: MPEG 再生、b14: Dolby Digital 再生)。フラグ値 0 は機能がないことを示し、フラグ値 1 は機能があることを示す。デフォルトの値が定義されていない。
16 | ISO-639 国コード (小文字 2 文字の ASCII 文字) または 65535 (指定なし)。デフォルト値は 65535。
17 | 言語拡張コード (0 = 指定なし、1 = 標準オーディオ、2 = 視力の弱い人のためのオーディオ、3 = ディレクター コメント #1、4 = ディレクター コメント #2)。デフォルト値は 0。
18 | ISO-639 国コード (小文字 2 文字の ASCII 文字) または 65535 (指定なし)。デフォルト値は 65535。デフォルト値は 65535。
19 | 言語拡張コード (0 = 指定なし、1 = 標準字幕、2 = 大きい字幕、3 = 子供用字幕、5 = 標準クローズド キャプション、6 = 大きいクローズド キャプション、7 = 子供用クローズド キャプション、9 = 強制表示字幕、13 = ディレクター コメント、14 = 大きいディレクター コメント、15 = 子供用ディレクター コメント)。デフォルト値は 0。
20 | 下位 8 ビット (b0 ～ b7) に地域番号 (1 ～ 8) が格納される。

IDvdInfo2::GetAudioAttributes

IDvdInfo2 インターフェイス

現在のタイトルまたはメニューの指定されたオーディオ ストリームの属性を取得する。

構文

HRESULT GetAudioAttributes(
  ULONG ulStream,
  DVD_AudioAttributes *pATR
);

パラメータ

ulStream
[in] 問い合わせの対象となる属性を持つオーディオ ストリームを指定する ULONG 型の変数。「注意」を参照すること。
pATR
[out] 指定されたオーディオ ストリームの属性が格納される DVD_AudioAttributes 構造体へのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_UNEXPECTED | DVD ナビゲータが初期化されていない。
VFW_E_DVD_NO_ATTRIBUTES | 何らかの理由により、ストリームのオーディオ属性が取得できない。
E_POINTER | 無効な引数。

注意

ulStream は 0 から 7 の間のインデックス番号または次の値である。

DVD_DEFAULT_AUDIO_STREAM | デフォルトのオーディオ ストリームの属性を問い合わせる。
DVD_STREAM_DATA_CURRENT | 現在のストリームを問い合わせる。
DVD_STREAM_DATA_VMGM | VMGM のオーディオ属性を問い合わせる。
DVD_STREAM_DATA_VTSM | VTSM のオーディオ属性を問い合わせる。

このメソッドの使用例については、DVDSample の「CDvdCore::GetAudioAttributes()」および「CAudioLangDlg::GetAudioLang」を参照すること。

IDvdInfo2::GetAudioLanguage

IDvdInfo2 インターフェイス

現在のタイトル内の指定されたオーディオ ストリームの言語を取得する。

構文

HRESULT GetAudioLanguage(
  ULONG ulStream,
  LCID *pLanguage
);

パラメータ

ulStream
[in] 言語を取得するオーディオ ストリーム番号。
pLanguage
[out] 言語情報を受け取る LCID へのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_INVALIDARG | 無効な引数。
E_POINTER | pLanguage パラメータが NULL である。
E_UNEXPECTED | DVD ナビゲータが初期化されていない。
VFW_E_DVD_INVALIDDOMAIN | DVD ナビゲータが有効なドメイン内にない。

注意

このメソッドはメニューの言語は返さない。ストリームに未知の言語が含まれている場合、このメソッドは、pLanguage が指す値をゼロに設定する。pLanguage から読み取り可能な文字列名を作成するには、次のように Microsoft® Win32® GetLocaleInfo 関数を呼び出す。LOCALE_SENGLANGUAGE はロケール情報型であり、pszString は要求されたデータを受け取るバッファへのポインタであり、cbSize は pszString のサイズを指定する。

GetLocaleInfo(*pLanguage, LOCALE_SENGLANGUAGE, pszString, cbSize);

参照

IDvdControl2::SelectAudioStream

IDvdInfo2::GetButtonAtPosition

IDvdInfo2 インターフェイス

表示ウィンドウ内の指定された位置にあるボタンを取得する。

構文

HRESULT GetButtonAtPosition(
  POINT point,
  ULONG *puButtonIndex
);

パラメータ

point
[in] Win32 WM_MOUSEMOVE メッセージを使って取得された現在のマウス ポインタの位置。
puButtonIndex
[out] 現在のマウス ポインタ位置にあるボタンのインデックス (1 から 36 の間) を受け取る ULONG 型の変数へのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_INVALIDARG | 無効な引数。
E_POINTER | puButtonIndex パラメータが無効である。
VFW_E_DVD_NO_BUTTON | point にボタンがない。

注意

通常、このメソッドは、DVD メニュー表示ウィンドウ内のマウス ポインタの移動に応じて呼び出される。ボタン番号を取得する前に、必ず HRESULT で成功を確認すること。指定された位置にボタンがあった場合、このメソッドは puButtonIndex の値の設定のみを行う。DVD ボタンは強調表示される矩形を持たない場合があり、ボタンの矩形どうしは重なり合うことがあり、ボタンの矩形は必ずしもボタンの外観と一致するわけではない。

参照

IDvdControl2::ActivateButton

IDvdInfo2::GetButtonRect

IDvdInfo2 インターフェイス

指定されたメニュー ボタンの矩形の座標を取得する。このメソッドは現在実装されていない。

構文

HRESULT GetButtonRect(
  ULONG ulButton
  RECT *pRect
);

パラメータ

ulButton
[in] ボタンを指定する 1 から 36 の間の ULONG 型の変数。
pRect
[out] ボタンの矩形の座標を受け取る RECT 型の変数へのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

E_NOTIMPL このメソッドは現在実装されていない。

IDvdInfo2::GetCmdFromEvent

IDvdInfo2 インターフェイス

EC_DVD_CMD_START イベントまたは EC_DVD_CMD_END イベントから IDvdCmd オブジェクトを取得する。

構文

HRESULT GetCmdFromEvent(
  LONG_PTR lParam1,
  IDvdCmd **ppCmdObj
);

パラメータ

lParam1
[in] イベント通知の lParam1 パラメータ。
ppCmdObj
[out] イベントを発生させたコマンドに関連付けられている IDvdCmd コマンド オブジェクトへのポインタのアドレス。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_FAIL | コマンドが存在しない。
E_POINTER | 無効な引数。

注意

このメソッドは、EC_DVD_CMD_START イベントまたは EC_DVD_CMD_END イベントの lParam1 パラメータを、イベントを発生させたコマンドに関連付けられている IDvdCmd オブジェクトにマップする。 その後は、WaitForStart または WaitForEnd を呼び出すことにより、そのコマンドに関連する DVD ナビゲータのブロック動作を制御することができる。IDvdCmd オブジェクトは DVD ナビゲータによって作成され、返されるポインタの参照カウントは既に増加しているため、WaitForStart または WaitForEnd から動作が戻った後、IDvdCmd オブジェクトを解放する必要がある。

参照

DVD コマンドの同期化、 EC_DVD_CMD_START、EC_DVD_CMD_END

IDvdInfo2::GetCurrentAngle

IDvdInfo2 インターフェイス

現在のアングル ブロック内の利用できるアングルの数と現在選択されているアングル番号を取得する。

構文

HRESULT GetCurrentAngle(
  ULONG *pulAnglesAvailable,
  ULONG *pulCurrentAngle
);

パラメータ

pulAnglesAvailable
[out] 利用できるアングルの数を受け取る ULONG 型の変数へのポインタ。1 つのアングル ブロック内には最大 9 個のアングルがあり、それぞれに 1 から 9 の番号が振られる。値が 1 の場合、DVD ナビゲータはアングル ブロック内にない。
pulCurrentAngle
[out] 現在のアングル番号を受け取る ULONG 型の変数へのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_POINTER | 無効な引数。
VFW_E_DVD_INVALIDDOMAIN | DVD ナビゲータが初期化されていない、または有効なドメイン内にない。

注意

オーディオ ストリームとサブピクチャ ストリームのインデックスは開始値が 0 であるが、アングルとメニュー ボタンのインデックスは開始値が 1 である点に注意すること。DVD ナビゲータは、アングル ブロックに入る直前に、lParam パラメータを 1 に設定して EC_DVD_ANGLES_AVAILABLE イベント通知をアプリケーションに送る。通常、アプリケーションは、EC_DVD_ANGLES_AVAILABLE のイベント ハンドラ内で GetCurrentAngle および IDvdControl2::SelectAngle を呼び出す。

このメソッドの使用例については、DVDSample アプリケーションの「CAngleDlg::MakeAngleList」を参照すること。

参照

IDvdControl2::SelectAngle、EC_DVD_ANGLES_AVAILABLE、EC_DVD_ANGLE_CHANGE

IDvdInfo2::GetCurrentAudio

IDvdInfo2 インターフェイス

利用できるオーディオ ストリームの数と現在選択されているオーディオ ストリームの番号を取得する。

構文

HRESULT GetCurrentAudio(
  ULONG *pulStreamsAvailable,
  ULONG *pulCurrentStream
);

パラメータ

pulStreamsAvailable
[out] 利用できるオーディオ ストリームの数を受け取る ULONG 型の変数へのポインタ。
pulCurrentStream
[out] 現在のタイトル内の現在選択されているオーディオ ストリーム番号を受け取る ULONG 型の変数へのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_POINTER | 入力された引数が無効である。
VFW_E_DVD_INVALIDDOMAIN | DVD ナビゲータが初期化されていない、または有効なドメイン内にない。

注意

ディスク上の利用できるオーディオ言語を取得するには、GetCurrentAudio を呼び出した後、ゼロから (pulStreamsAvailable - 1) までの各ストリームについて GetAudioLanguage を呼び出し、言語の内容を取得する。

参照

EC_DVD_AUDIO_STREAM_CHANGE、IDvdControl2::SelectAudioStream

IDvdInfo2::GetCurrentButton

IDvdInfo2 インターフェイス

利用できるボタンの数と現在選択されているボタンの番号を取得する。

構文

HRESULT GetCurrentButton(
  ULONG *pulButtonsAvailable,
  ULONG *pulCurrentButton
);

パラメータ

pulButtonsAvailable
[out] 利用できるボタンの数を受け取る ULONG 型の変数へのポインタ。
pulCurrentButton
[out] 現在選択されているボタンの番号 (1 から 36 の間) を受け取る ULONG 型の変数へのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_POINTER | ポインタ引数の 1 つが無効である。

注意

ボタンが存在しない場合は、pulButtonsAvailable と pulCurrentButton の両方がゼロに設定される。

参照

EC_DVD_BUTTON_CHANGE、IDvdControl2::ActivateButton

IDvdInfo2::GetCurrentDomain

IDvdInfo2 インターフェイス

現在 DVD ナビゲータが置かれているドメインを取得する。

構文

HRESULT GetCurrentDomain(
  DVD_DOMAIN *pDomain
);

パラメータ

pDomain
[out] 現在のドメインを受け取る DVD_DOMAIN 型の変数へのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_UNEXPECTED | 予期せぬエラー。
E_POINTER | 無効な引数。

注意

このメソッドを使って、DVD ナビゲータが特定のタイトル ドメイン内で再生を終了したかどうかをテストできる。アプリケーションは、PlayTitle、PlayForwards などの IDvdControl2 メソッドを呼び出す前に現在のドメインのテストを行う必要はない。DVD ナビゲータは、ドメインのテストを行い、現在のコマンドがドメインに対して無効である場合は、何もせずに、VFW_E_DVD_INVALIDDOMAIN を返す。

参照

Domains、EC_DVD_DOMAIN_CHANGE

IDvdInfo2::GetCurrentLocation

IDvdInfo2 インターフェイス

現在の再生位置を取得する。

構文

HRESULT GetCurrentLocation(
  DVD_PLAYBACK_LOCATION2 *pLocation
);

パラメータ

pLocation
[out] 再生位置情報を受け取る DVD_PLAYBACK_LOCATION2 型の変数へのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_INVALIDARG | 無効な引数。
E_POINTER | pLocation パラメータが無効である。
VFW_E_DVD_INVALIDDOMAIN | DVD ナビゲータが無効なドメイン内にある。

注意

このメソッドは、現在の位置のシークを明示的に禁止していないタイトルの現在の再生位置からビデオの再生を再開するのに十分な情報を取得する。ディスクが排出された後は、このメソッドが返す情報では再生を再開するのに十分でない場合がある。ユーザーが後からいつでも同じ位置に戻れるように、現在の位置とステート情報をディスクに保存するには、GetState を使用する。

IDvdInfo2::GetCurrentSubpicture

IDvdInfo2 インターフェイス

現在のタイトル内の利用できるサブピクチャ ストリームの数、現在選択されているサブピクチャ ストリーム番号、およびサブピクチャの状態を取得する。

構文

HRESULT GetCurrentSubpicture(
  ULONG *pulStreamsAvailable,
  ULONG *pulCurrentStream,
  BOOL *pbIsDisabled
);

パラメータ

pulStreamsAvailable
[out] 利用できるサブピクチャ ストリームの数を受け取る ULONG 型の変数へのポインタ。
pulCurrentStream
[out] 現在選択されているサブピクチャ ストリームの番号を受け取る ULONG 型の変数へのポインタ。
pbIsDisabled
[out] サブピクチャの表示が無効になっているかどうかを示す値を受け取る BOOL 型の変数へのポインタ。TRUE は無効を意味する。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_POINTER | 無効な引数。
VFW_E_DVD_INVALIDDOMAIN | DVD ナビゲータが初期化されていないか、Title ドメイン内にない。

注意

DVD コンテンツの作成者は、ディスク上の任意のサブピクチャ ストリームを強制的にアクティブにするように指定し、利用者が見たいかどうかに関係なく、このストリームを必ず表示するように要求することができる。DVD ナビゲータはそのようなディスクからのすべてのコマンドに従い、アプリケーションが IDvdControl2::SetSubpictureState メソッドによってサブピクチャの表示を無効にした場合でも、強制的にアクティブにされたストリームを表示する。

参照

EC_DVD_SUBPICTURE_STREAM_CHANGE、IDvdControl2::SelectSubpictureStream

IDvdInfo2::GetCurrentVideoAttributes

IDvdInfo2 インターフェイス

現在のタイトルまたはメニューのビデオ属性を取得する。

構文

HRESULT GetCurrentVideoAttributes(
    DVD_VideoAttributes *pATR
);

パラメータ

pATR
[out] 属性を受け取る DVD_VideoAttributes 構造体へのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_POINTER | 無効な引数。
E_UNEXPECTED | DVD ナビゲータが初期化されていない。

注意

このメソッドの使用例については、DVDSample の「CDvdCore::GetVideoAttributes()」を参照すること。

IDvdInfo2::GetDecoderCaps

IDvdInfo2 インターフェイス

DVD デコーダのビデオ、オーディオ、およびサブピクチャの最大データ レート (逆方向および順方向) と、サポートしているオーディオの種類 (Dolby AC-3、MPEG-2、DTS、SDDS、LPCM) を取得する。

構文

HRESULT GetDecoderCaps(
  DVD_DECODER_CAPS *pCaps
);

パラメータ

pCaps
[out] デコーダに関する情報を受け取る DVD_DECODER_CAPS 型の変数へのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
VFW_E_WRONG_STATE | フィルタ グラフが初期化されていない。

IDvdInfo2::GetDefaultAudioLanguage

IDvdInfo2 インターフェイス

デフォルトのオーディオ言語を取得する。

構文

HRESULT GetDefaultAudioLanguage(
  LCID *pLanguage,
  DVD_AUDIO_LANG_EXT *pAudioExtension
);

パラメータ

pLanguage
[out] デフォルトの言語情報を受け取る LCID へのポインタ。
pAudioExtension
デフォルトの DVD オーディオ言語拡張機能を示す値を受け取る DVD_AUDIO_LANG_EXT 型の変数へのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_INVALIDARG | 無効な引数。
E_POINTER | pLanguage パラメータが NULL である。
E_UNEXPECTED | DVD ナビゲータが初期化されていない。
VFW_E_DVD_INVALIDDOMAIN | DVD ナビゲータが有効なドメイン内にない。

参照

IDvdControl2::SelectAudioStream、IDvdControl2::SelectDefaultAudioLanguage

IDvdInfo2::GetDefaultMenuLanguage

IDvdInfo2 インターフェイス

デフォルトのメニュー言語を取得する。

構文

HRESULT GetDefaultMenuLanguage(
  LCID *pLanguage
);

パラメータ

pLanguage
[out] 言語情報を受け取る LCID へのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_INVALIDARG | 無効な引数。
E_POINTER | pLanguage パラメータが NULL である。
E_UNEXPECTED | DVD ナビゲータが初期化されていない。
VFW_E_DVD_INVALIDDOMAIN | DVD ナビゲータが有効なドメイン内にない。

参照

IDvdControl2::SelectDefaultMenuLanguage

IDvdInfo2::GetDefaultSubpictureLanguage

IDvdInfo2 インターフェイス

デフォルトのサブピクチャ言語を取得する。

構文

HRESULT GetDefaultSubpictureLanguage(
  LCID *pLanguage,
  DVD_SUBPICTURE_LANG_EXT *pSubpictureExtension
);

パラメータ

pLanguage
[out] 言語情報を受け取る LCID へのポインタ。
pSubpictureExtension
[out] デフォルトの言語拡張機能を示す値として許可されている値の 1 つを受け取る DVD_SUBPICTURE_LANG_EXT 型の変数へのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_INVALIDARG | 無効な引数。
E_POINTER | pLanguage パラメータが NULL である。
E_UNEXPECTED | DVD ナビゲータが初期化されていない。
VFW_E_DVD_INVALIDDOMAIN | DVD ナビゲータが有効なドメイン内にない。

参照

IDvdControl2::SelectDefaultSubpictureLanguage

IDvdInfo2::GetDiscID

IDvdInfo2 インターフェイス

指定された DVD に対してシステムが生成した 64 ビットの識別番号を取得する。

構文

HRESULT GetDiscID(
    LPCWSTR pszwPath,
    ULONGLONG *pullDiscID
  );

パラメータ

pszwPath
[in] ディスク ID に使用するボリュームのパス。現在の DVD ボリュームを使用するには、NULL を指定する。
pullDiscID
[out] 64 ビットのディスク ID を受け取る ULONGLONG 型の変数へのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_INVALIDARG | 無効な引数。
E_UNEXPECTED | DVD ナビゲータが初期化されていない。

注意

DVD ナビゲータは、BCA 値ではなく、ファイルのサイズ、日付その他の情報に基づいて "一意な" ID を計算する。この番号はディスクが再生されるたびに同じであることが保証される。ID は、複製されたディスクのすべてのコピーに適用される。つまり、特定のムービーのすべてのコピーは同じ ID を持つ。2 つの別々のタイトルが同じ ID を持つ確率は十分に低いため、この ID は、実用上 "一意" であるものと見なすことができる。

IDvdInfo2::GetDVDDirectory

IDvdInfo2 インターフェイス

DVD ナビゲータで設定されているルート ディレクトリを取得する。

構文

HRESULT GetDVDDirectory(
  LPWSTR pszwPath,
  ULONG ulMaxSize,
  ULONG *pulActualSize
);

パラメータ

pszwPath
[out, size_is(cbMaxSize)] パス文字列を受け取るバッファへのポインタ。
ulMaxSize
[in] WCHAR 単位のバッファのサイズ。
pulActualSize
[out] WCHAR 単位で返された実際のデータのサイズを受け取る変数へのポインタ。

注意

このメソッドの使用例については、DVDSample の「CDvdCore::GetDriveLetter」を参照すること。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_INVALIDARG | バッファの大きさが文字列を格納するのに十分でない。
VFW_E_DVD_INVALIDDOMAIN | DVD ナビゲータが有効なドメイン内にない。

IDvdInfo2::GetKaraokeAttributes

IDvdInfo2 インターフェイス

現在のタイトルまたはメニューの指定されたオーディオ ストリームのカラオケ属性を取得する。

構文

HRESULT GetKaraokeAttributes(
  ULONG ulStream,
  DVD_KaraokeAttributes *pATR
);

パラメータ

ulStream
[in] 属性を問い合わせるオーディオ ストリームのインデックスを指定する ULONG 型の変数。「注意」を参照すること。
pATR
[out] カラオケ属性が格納される DVD_KaraokeAttributes 構造体へのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_POINTER | 無効な引数。
E_UNEXPECTED | DVD ナビゲータが初期化されていない。
VFW_E_DVD_NOT_IN_KARAOKE_MODE | 指定されたストリームがカラオケ フォーマットになっていない。
VFW_E_DVD_INVALIDDOMAIN | DVD ナビゲータがタイトル ドメイン内にない。
VFW_E_DVD_NO_ATTRIBUTES | 何らかの理由で、指定されたストリームのカラオケ属性が取得できない。

注意

このメソッドは、ストリーム内のチャンネルの数を明示的には返さない。その情報は、IDvdInfo2::GetAudioAttributes を呼び出すことによって取得できる。このメソッドの使用例については、DVDSample の「CKaraokeDlg::DoModal」を参照すること。

ulStream パラメータは、0 から 7 の間の値または次のいずれかである。
DVD_STREAM_DATA_CURRENT (0x800) | 現在選択されているオーディオ ストリームを問い合わせる。
DVD_DEFAULT_AUDIO_STREAM | デフォルトのオーディオ ストリームを問い合わせる。

IDvdInfo2::GetSubpictureAttributes

IDvdInfo2 インターフェイス

指定されたタイトルまたはメニューの指定されたサブピクチャ ストリームの属性を取得する。

構文

HRESULT GetSubpictureAttributes(
  ULONG ulStream,
  DVD_SubpictureAttributes *pAttributes
  );

パラメータ

ulStream
[in] 問い合わせるサブピクチャ ストリームを示す 0 から 31 の間のインデックス番号。「注意」を参照すること。
pAttributes
[out] サブピクチャの属性を受け取る DVD_SubpictureAttributes 構造体へのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_FAIL | サブピクチャ ストリームが見つからない。
E_POINTER | 無効な引数。
VFW_E_ATTRIBUTES_DO_NOT_EXIST | サブピクチャに属性が定義されていない。

注意

タイトルとしてインデックス数 0-31 が有効である。メニューは 1 つのサブピクチャ ストリームのみを持つ、それは以下の表の 1 つを使用して指定されなければならない。

DVD_STREAM_DATA_CURRENT (0x800) | 現在選択されているサブピクチャ ストリームを問い合わせる。
DVD_STREAM_DATA_VMGM (0x400) | ビデオ マネージャまたは "トップ" メニューのサブピクチャ属性を問い合わせる。
DVD_STREAM_DATA_VTSM (0x401) | 現在選択されているビデオ タイトル セット メニューのサブピクチャ属性を問い合わせる。

このメソッドの使用例については、DVDSample の「CDvdCore::GetSPAttributes()」および「CSPLangDlg::GetSPLang」を参照すること。

参照

メニュー、IsSubpictureStreamEnabled

IDvdInfo2::GetCurrentUOPS

IDvdInfo2 インターフェイス

コンテンツの作成者が明示的に無効にしたナビゲーション コマンドが現在のディスク位置にあれば、それを示すフラグのセットを取得する。

構文

HRESULT GetCurrentUOPS(
  ULONG *pulUOPs
);

パラメータ

pulUOPs
[out] VALID_UOP_FLAG 値のビットごとの OR である ULONG 型の変数へのポインタ。個々のビットは、ユーザ操作 (UOP) の状態 (有効または無効) を示す。ビットがセットされていれば、ユーザ操作は禁止されている。「注意」を参照すること。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_POINTER | pulUOPs が有効なポインタではない。

注意

DVD の作成者は、ディスク上のほとんどすべての位置で、UOP コマンドを挿入することにより、通常は現在の DVD ドメイン内で許可されているナビゲーション コマンドを禁止することができる。つまり、UOP コマンドを利用すると、ディスクの作成者は、通常のナビゲーション権限をオーバーライドできる。

DVD ナビゲータは、コマンドを処理する前に自動的にすべての UOP 権限をチェックし、コマンドが現在の UOP によって無効になっていれば、どのメソッドからでも VFW_E_DVD_OPERATION_INHIBITED を返すため、通常は DVD プレーヤー アプリケーショがこのメソッドを使う必要はない。アプリケーションで現在の UOP 権限そのものを追跡する必要がある場合は、現在の UOP 権限が必要になるたびに GetCurrentUOPS を呼び出すか、メッセージ ループで EC_DVD_VALID_UOPS_CHANGE イベント通知を処理し、lParam1 パラメータから UOP 情報を取得することができる。一般的に、後者の方式の方が効率がよい。

参照

EC_DVD_VALID_UOPS_CHANGE

IDvdInfo2::GetDVDVolumeInfo

IDvdInfo2 インターフェイス

現在の DVD ボリューム情報を取得する。

構文

HRESULT GetDVDVolumeInfo(
    ULONG *pulNumOfVolumes,
    ULONG *pulVolume,
    DVD_DISC_SIDE *pSide,
    ULONG *pulNumOfTitles
    );

パラメータ

pulNumOfVolumes
[out] ボリューム セット内のボリュームの数を受け取る ULONG 型の変数へのポインタ。
pulVolume
[out] このルート ディレクトリのボリューム番号を受け取る ULONG 型の変数へのポインタ。
pSide
[out] 現在のディスク面を受け取る DVD_DISC_SIDE 型の変数へのポインタ。
pulNumOfTitles
[out] このボリュームで使用できるタイトルの数を受け取る ULONG 型の変数へのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_POINTER | 無効な引数。

注意

一部のディスクは、マルチディスク セットの一部として配布できる。その場合、ここでいう "ボリューム" は、ディスクが作成された方法によって、"ディスク" を意味することも、"ディスク面" を意味することもある。

IDvdInfo2::GetDVDTextLanguageInfo

IDvdInfo2 インターフェイス

指定されたテキスト文字列言語ブロックの情報を取得する。

構文

HRESULT GetDVDTextLanguageInfo(
    ULONG ulLangIndex,
    ULONG *pulNumOfStrings,
    LCID pLangCode,
    DVD_TextCharSet *pbCharacterSet
  );

パラメータ

ulLangIndex
[in] 言語ブロックを指定するインデックス。「注意」を参照すること。
pulNumOfStrings
[out] 指定された言語ブロックの文字列の数を受け取る ULONG 型の変数へのポインタ。
pLangCode
[out] ISO 639 言語コードが格納されている LCID 型の変数へのポインタ。
pbCharacterSet
[out] 指定されている言語のどの文字セットが使用されているかを示す値を受け取る DVD_TextCharSet 列挙へのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_POINTER | 無効な引数。
E_UNEXPECTED | 予期しない内部エラーが発生した。

注意

GetDVDTextNumberOfLanguages を呼び出して、使用できるすべてのメニューとサブピクチャのテキスト言語のインデックスを設定する。次に、各インデックス エントリについて GetDVDTextLanguageInfo を呼び出し、特定の言語の情報 (文字列の数、言語コード、文字セット) を取得する。

参照

DVD テキスト文字列の操作

IDvdInfo2::GetDVDTextNumberOfLanguages

IDvdInfo2 インターフェイス

現在の DVD またはディスク面のテキスト言語の数を取得する。

構文

HRESULT GetDVDTextNumberOfLanguages(
    ULONG *pulNumOfLangs
  );

パラメータ

pulNumOfLangs
[out] テキスト言語の数を受け取る ULONG 型の変数へのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_POINTER | 無効な引数。
E_UNEXPECTED | 予期しない内部エラーが発生した。

注意

言語の数は、ディスクが作成された方法によって、ディスク全体について有効であることも、現在のディスク面についてのみ有効であることもある。

参照

DVD テキスト文字列の操作

IDvdInfo2::GetDVDTextStringAsNative

IDvdInfo2 インターフェイス

指定された言語のテキスト文字列をバイトの配列として取得する。

構文

HRESULT GetDVDTextStringAsNative(
  ULONG ulLangIndex,
  ULONG ulStringIndex,
  BYTE *pchBuffer,
  ULONG ulMaxBufferSize,
  ULONG *pulActualSize,
  DVD_TextStringType *pType
);

パラメータ

ulLangIndex
[in] 言語インデックス。
ulStringIndex
[in] 特定の言語の文字列インデックス。
pchBuffer
[out] テキスト文字列を受け取るバッファへのポインタ。pchBuffer が NULL の場合、このメソッドは pulActualSize によって文字列のサイズのみを返す。
ulMaxBufferSize
[in] 許容最大文字列サイズ (pchBuffer のサイズ)。
pulActualSize
[out] pchBuffer によって返される、最後の NULL を含む文字列のバイト単位の実際の長さ。
pType
[out] 返された文字列データの種類を受け取る DVD_TextStringType 型の変数へのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_POINTER | 無効な引数。
E_UNEXPECTED | 予期しない内部エラーが発生した。

注意

一般的に、堅牢なアプリケーションは Unicode™ 文字列を処理できる。したがって、通常、文字列を取得するときは、まず GetDVDTextStringAsUnicode を呼び出す。しかし、一部の文字列には Unicode™ で表せない文字が含まれていることがあるため、GetDVDTextStringAsUnicode が失敗した場合、アプリケーションは GetDVDTextStringAsNative を呼び出すことができる。

最後の NULL が返された文字列に追加される。

参照

DVD テキスト文字列の操作

IDvdInfo2::GetDVDTextStringAsUnicode

IDvdInfo2 インターフェイス

指定された言語と文字列インデックスのテキスト文字列を Unicode™ で取得する。

構文

HRESULT GetDVDTextStringAsUnicode(
    ULONG ulLangIndex,
    ULONG ulStringIndex,
    TCHAR *pchBuffer,
    ULONG ulMaxBufferSize,
    ULONG *pulActualSize,
    enum DVD_TextStringType *pType
  );

パラメータ

ulLangIndex
[in] 文字列インデックス。
ulStringIndex
[in] 特定の言語の文字列インデックス。
pchBuffer
[out] テキスト文字列を受け取るバッファへのポインタ。pchBuffer が NULL の場合、このメソッドは pulActualSize によって文字列のサイズのみを返す。
ulMaxBufferSize
[in] sizeof(pchBuffer)/sizeof(*pchBuffer) によって計算される許容最大文字列サイズ。
pulActualSize
[out] pchBuffer によって返される、最後の NULL を含む文字列のバイト単位の実際の長さを受け取る ULONG 型の変数へのポインタ。
pType
[out] 返された文字列データの種類を受け取る DVD_TextStringType 型の変数へのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_POINTER | 無効な引数。
E_UNEXPECTED | 予期しない内部エラーが発生した。

注意

一般的に、堅牢なアプリケーションは Unicode™ 文字列を処理できる。したがって、通常、文字列を取得するときは、まず GetDVDTextStringAsUnicode を呼び出す。しかし、一部の文字列には Unicode™ で表せない文字が含まれていることがあるため、GetDVDTextStringAsUnicode が失敗した場合、アプリケーションは GetDVDTextStringAsNative を呼び出すことができる。

最後の NULL が返された文字列に追加される。

参照

DVD テキスト文字列の操作

IDvdInfo2::GetMenuLanguages

IDvdInfo2 インターフェイス

ディスク上のすべてのメニューで利用できるすべての言語を取得する。

構文

HRESULT GetMenuLanguages(
    LCID *pLanguages,
    ULONG ulMaxLanguages,
    ULONG *puActualLanguages
  );

パラメータ

pLanguages
[out] 返された言語を受け取る LCID 配列へのポインタ。実際の言語自体ではなく、メニューで使用できる言語の数だけを取得するには、pLanguages に NULL を指定する。
ulMaxLanguages
[in] 取得する言語の最大数。
puActualLanguages
[out] 取得された言語の実際の数を受け取る ULONG 型の変数へのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_INVALIDARG | 無効な引数。
E_UNEXPECTED | DVD ナビゲータが初期化されていない。

IDvdInfo2::GetNumberOfChapters

IDvdInfo2 インターフェイス

指定されたタイトルのチャプターの数を取得する。

構文

HRESULT GetNumberOfChapters(
  ULONG ulTitle,
  ULONG *pulNumOfChapters
);

パラメータ

ulTitle
[in] タイトルを指定する ULONG 型の変数。
pulNumOfChapters
[out] 指定されたタイトルのチャプターの数を受け取る ULONG 型の変数へのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_INVALIDARG | 無効な引数。
E_POINTER | パラメータが無効である。
E_UNEXPECTED | DVD ナビゲータが初期化されていない。

注意

IDvdControl2::PlayChapter を呼び出す前に、このメソッドを呼び出してチャプターの数を取得し、指定するチャプター番号が有効であることを確認する。

IDvdInfo2::GetPlayerParentalLevel

IDvdInfo2 インターフェイス

DVD ナビゲータの現在のペアレンタル ロック レベルおよび ISO 3166 国コードの設定を取得する。

構文

HRESULT GetPlayerParentalLevel(
  ULONG *pulParentalLevel,
  ULONG *pulCountryCode
);

パラメータ

pulParentalLevel
[out] 現在のペアレンタル ロック レベルを示す値を受け取る ULONG 型の変数へのポインタ。有効なペアレンタル ロック レベルは、ペアレンタル ロックが有効であれば 1 から 8 の間であり、ペアレンタル ロックが無効であれば 0xFFFFFFFF である。
pulCountryCode
[out] 現在の国コード (ISO 3166 Alpha-2 コード) を示す値を受け取る ULONG 型の変数へのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_POINTER | パラメータが無効である。

注意

DVD ナビゲータでは、ペアレンタル ロックがデフォルトで無効になっている。このメソッドの使用例については、DVDSample の「CDvdCore::GetParentalLevel」を参照すること。

参照

ペアレンタル ロック レベルの適用、 EC_DVD_PARENTAL_LEVEL_CHANGE

IDvdInfo2::GetState

IDvdInfo2 インターフェイス

ディスク位置と DVD ナビゲータ ステート情報が格納されているブックマークを取得する。

構文

HRESULT GetState(
    IDvdState **pStateData
);

パラメータ

pStateData
[out] DVD ナビゲータによって割り当てられた DVDState オブジェクトの IDvdState インターフェイスへのポインタのアドレス。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_INVALIDARG | 無効な引数。
E_UNEXPECTED | DVD ナビゲータが初期化されていない。

注意

このメソッドが呼び出されると、DVD ナビゲータは新しい状態オブジェクトを作成し、そのオブジェクトに現在の位置、現在のペアレンタル ロック レベル、およびその他のステート情報を保存する。後から DVDState オブジェクトを使って IDvdControl2::SetState を呼び出すことにより、保存した位置に DVD ナビゲータを戻すことができる。これにより、利用者は、ディスクの途中で再生を停止してその位置を保存し、後から、すべての内部設定を元どおりに復元して、前に停止した位置から再生を再開することができる。

DVD ナビゲータは、DvdState オブジェクトをアプリケーションに返す前に、DvdState オブジェクトに対する AddRef を呼び出す。アプリケーションは、オブジェクトを使用した後、オブジェクトに対する Release を呼び出す必要がある。

このメソッドの使用例については、DVDSample の「CDvdCore::RestoreBookmark」を参照すること。

IDvdInfo2::GetSubpictureLanguage

IDvdInfo2 インターフェイス

現在のタイトル内の指定されたサブピクチャ ストリームの言語を取得する。

構文

HRESULT GetSubpictureLanguage(
  ULONG ulStream,
  LCID *pLanguage
  );

パラメータ

ulStream
[in] 言語を取得するサブピクチャ ストリームの番号。
pLanguage
[out] ロケール情報を受け取る LCID へのポインタ。言語情報は、Win32 MAKELANGID マクロを使って LCID から抽出できる。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_INVALIDARG | 無効な引数。
VFW_E_DVD_INVALIDDOMAIN | DVD ナビゲータが初期化されていない、または有効なドメイン内にない。

注意

メニューで利用できるテキスト言語を取得するには、GetMenuLanguages を呼び出す。ストリームに未知の言語が含まれる場合、GetSubpictureLanguage は pLanguage が指す値をゼロに設定する。pLanguage から読み取り可能な文字列名を作成するには、次のように Win32 GetLocaleInfo 関数を呼び出す。LOCALE_SENGLANGUAGE はロケール情報型であり、pszString は要求されたデータを受け取るバッファへのポインタであり、cbSize は pszString のサイズを指定する。

GetLocaleInfo(*pLanguage, LOCALE_SENGLANGUAGE, pszString, cbSize);

IDvdInfo2::GetTitleAttributes

IDvdInfo2 インターフェイス

指定されたタイトルとそのメニューのすべてのビデオ ストリーム、オーディオ ストリーム、およびサブピクチャ ストリームの属性を取得する。

構文

HRESULT GetTitleAttributes(
    ULONG ulTitle,
    DVD_MenuAttributes *pMenu,
    DVD_TitleAttributes *pTitle
    );

パラメータ

ulTitle
[in] 情報を要求するタイトル番号を指定する 1 から 99 の間の ULONG 型の変数。現在のタイトルの情報を要求するには、0xFFFFFFFF を指定する。
pMenu
[out] 指定されたタイトルに関連付けられているメニューの属性を受け取る DVD_MenuAttributes 構造体へのポインタ。
pTitle
[out] 指定されたタイトルの属性を受け取る DVD_TitleAttributes 構造体へのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_INVALIDARG | nTitle パラメータが無効である。
E_INVALIDDOMAIN | DVD ナビゲータがタイトル ドメイン内にない。
E_POINTER | pMenu パラメータまたは pTitle パラメータが無効である。
E_UNEXPECTED | DVD ナビゲータが初期化されていない、またはそれ以外の内部エラーが発生した。

IDvdInfo2::GetTitleParentalLevels

IDvdInfo2 インターフェイス

特定のタイトルに定義されているペアレンタル ロック レベルを取得する。

構文

HRESULT GetTitleParentalLevels(
    ULONG ulTitle,
    ULONG *pulParentalLevels
  );

パラメータ

ulTitle
[in] ペアレンタル ロック レベルを要求するタイトル。現在のタイトルのペアレンタル ロック レベルを取得するには、0xfffffff を指定する。
pulParentalLevels
[out] タイトルに対して定義されている DVD_PARENTAL_LEVEL 値のビットごとの OR の組み合わせを受け取る ULONG 型の変数へのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_INVALIDARG | 無効な引数。
E_UNEXPECTED | DVD ナビゲータが初期化されていない。

注意

1 つのタイトルの別々のセクションには、別々のペアレンタル ロック レベルが含まれていることがある。

参照

ペアレンタル ロック レベルの適用

IDvdInfo2::GetTotalTitleTime

IDvdInfo2 インターフェイス

現在のタイトルの総再生時間を取得する。

構文

HRESULT GetTotalTitleTime(
    DVD_HMSF_TIMECODE *pTotalTime,
    ULONG *pulTimeCodeFlags
  );

パラメータ

pTotalTime
[out] 時、分、秒、フレーム単位の総時間を受け取る DVD_HMSF_TIMECODE 型の変数へのポインタ。
pulTimeCodeFlags
[out] ディスクが作成されたときの再生フレーム レートを示す DVD_TIMECODE_FLAGS 値を受け取る ULONG 型の変数へのポインタ。タイムコード情報を受け取りたくない場合は、NULL を指定する。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_POINTER | 無効な引数。
VFW_E_DVD_INVALIDDOMAIN | DVD ナビゲータがタイトル ドメイン内にない。
VFW_S_DVD_NON_ONE_SEQUENTIAL | タイトルが単一シーケンシャル ビデオ タイトルでない。

注意

総タイトル時間は、タイトルを順番に再生するのに必要な時間であり、静止画の再生、ポーズなどにかかる時間は含まれない。

このメソッドは、各チャプターが自動的に次のチャプターに分岐し、タイトル全体が途中で停止することなく連続的に再生される、単一シーケンシャル ビデオ タイトルでのみ使用される。非シーケンシャル ビデオ タイトルとは、自動的に次々とチャプターが再生されないタイトルである。DVD の作成者によって、非シーケンシャル ビデオ タイトルに時間情報をエンコードする方法が異なるため、そのようなタイトルの総時間を調べるためにこのメソッドを使用しないこと。

IDvdInfo2::GetVMGAttributes

IDvdInfo2 インターフェイス

ビデオ マネージャ メニューのすべてのビデオ ストリーム、オーディオ ストリーム、およびサブピクチャ ストリームの属性を取得する。

構文

HRESULT GetVMGAttributes(
  DVD_MenuAttributes *pATR
);

パラメータ

pATR
[out] 属性を受け取る DVD_MenuAttributes 構造体へのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_POINTER | 無効な引数。
E_UNEXPECTED | DVD ナビゲータが初期化されていない。

注意

ビデオ マネージャ メニューは特定のタイトル番号に関連付けられていない。

IDvdInfo2::IsAudioStreamEnabled

IDvdInfo2 インターフェイス

指定されたオーディオ ストリームが現在のタイトルで有効になっているかどうかを判別する。

構文

HRESULT IsAudioStreamEnabled(
    ULONG ulStreamNum,
    BOOL *pbEnabled
    );

パラメータ

ulStreamNum
[in] テストするオーディオ ストリーム番号。
pbEnabled
[out] オーディオ ストリームが有効になっていれば TRUE、それ以外の場合は FALSE になる値を受け取る BOOL 型の変数へのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_INVALIDARG | 無効な引数。
E_UNEXPECTED | DVD ナビゲータが初期化されていない。

注意

DVD には最大 8 個の個別のオーディオ ストリームを含めることができるが、通常は、1 つのタイトルのすべてのストリームが有効になることはない。IsAudioStreamEnabled を使用して、特定のストリームが現在のタイトルで有効であるかどうかを調べた後、IDvdControl2::SelectAudioStream を呼び出して、いずれかの有効なストリームを選択する。

IDvdInfo2::IsSubpictureStreamEnabled

IDvdInfo2 インターフェイス

指定されたサブピクチャ ストリームが現在のタイトルで有効になっているかどうかを判別する。

構文

HRESULT IsSubpictureStreamEnabled(
    ULONG ulStreamNum,
    BOOL *pbEnabled
);

パラメータ

ulStreamNum
[in] テストするサブピクチャ ストリーム番号。
pbEnabled
[out] サブピクチャ ストリームが有効になっていれば TRUE、それ以外の場合は FALSE になる値を受け取る BOOL 型の変数へのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_INVALIDARG | 無効な引数。
E_UNEXPECTED | DVD ナビゲータが初期化されていない。

注意

DVD には最大 32 個の個別のサブピクチャ ストリームを含めることができるが、通常は、1 つのタイトルのすべてのストリームが有効になることはない。IsSubpictureStreamEnabled を使用して、特定のストリームが現在のタイトルで有効であるかどうかを調べた後、IDvdControl2::SelectSubpictureStream を呼び出して、いずれかの有効なストリームを選択する。


IDvdState インターフェイス

IDvdState インターフェイスは、DvdState オブジェクトによって実装される。DvdState オブジェクトは、アプリケーションが IDvdInfo2::GetState を呼び出して、再生位置、ペアレンタル ロック レベル、リージョンを含むユーザーのセッションの状態をディスクに保存するときに、DVD ナビゲータ フィルタによって作成される。アプリケーションは、IDvdState メソッドを使用して、DvdState オブジェクトに保存されるこの情報を問い合わせることができる。

DvdState オブジェクトは、IPersist を実装して、ディスクへの保存を有効にする。ブックマークを保存する方法を示すサンプル コードについては、「DvdState オブジェクトの保存と復元」を参照すること。

DVD ナビゲータは、DVD 上の現在の再生位置、ユーザーのペアレンタル ロック レベル、および DVD リージョンによって DvdState オブジェクトを初期化する。この方法の代わりに、アプリケーションが CoCreateInstance: を呼び出すことによって状態オブジェクトを作成することもできる。

CoCreateInstance( CLSID_DVDState, NULL, CLSCTX_INPROC_SERVER,
    IID_IDvdState, (void **) ppState );

後から、ペアレンタル ロック レベルとリージョンの設定を復元し、GetState が呼び出されたときに停止した位置から再生を再開するには、IDvdControl2::SetState を呼び出す。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IDvdState メソッド | 説明
GetDiscID | ブックマークが作成されたディスクの一意な識別子 (ID) を取得する。
GetParentalLevel | DvdState オブジェクトに保存されたユーザーのペアレンタル ロック レベルを取得する。
GetRegion | DvdState オブジェクトに保存された DVD リージョンを取得する。

IDvdState::GetDiscID

IDvdState インターフェイス

ブックマークが作成されたディスクの一意な識別子 (ID) を取得する。

構文

HRESULT GetDiscID(
  ULONGLONG *pullUniqueID
  );

パラメータ

pullUniqueID
[out] ID を受け取る ULONGLONG 型の変数へのポインタ。

戻り値

次の表に示されるいずれかの値を返す。

S_OK | 成功。
E_POINTER | 無効な引数。

IDvdState::GetParentalLevel

IDvdState インターフェイス

DvdDState オブジェクトに保存されたユーザーのペアレンタル ロック レベルを取得する。

構文

HRESULT GetParentalLevel(
  ULONG *pulParentalLevel
  );

パラメータ

pulParentalLevel
[out] ペアレンタル ロック レベルを受け取る ULONG 型の変数へのポインタ。

戻り値

次のいずれかの値を返す。
S_OK | 成功。
E_POINTER | 無効な引数。

IDvdState::GetRegion

IDvdState インターフェイス

DvdState オブジェクトに保存された DVD リージョンを取得する。

構文

HRESULT GetRegion(
  ULONG *pulRegion
  );

パラメータ

pulRegion
[out] リージョン値を受け取る ULONG 型の変数へのポインタ。

戻り値

次のいずれかの値を返す。
S_OK | 成功。
E_UNEXPECTED | DVD ナビゲータが初期化されていない。
E_POINTER | 無効な引数。


IDVEnc インターフェイス

このインターフェイスは、DV ビデオ エンコーダ フィルタのプロパティの設定および取得を行うメソッドを備えている。

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IDVEnc メソッド | 説明
get_IFormatResolution | エンコーディング解像度を取得する。
put_IFormatResolution | エンコーディング解像度を設定する。

IDVEnc::get_IFormatResolution

IDVEnc インターフェイス

エンコーディング解像度を取得する。

構文

HRESULT get_IFormatResolution(
    int *VideoFormat,
    int *DVFormat,
    int *Resolution,
    BYTE fDVInfo,
    DVINFO *sDVInfo
);

パラメータ

VideoFormat
[out] 使用されているビデオ方式 (NTSC または PAL) を指定する DVENCODERVIDEOFORMAT 列挙のメンバを受け取る変数へのポインタ。
DVFormat
[out] デジタル ビデオ (DV) フォーマットを指定する DVENCODERFORMAT 列挙のメンバを受け取る変数へのポインタ。
Resolution
[out] ビデオ解像度を指定する DVENCODERRESOLUTION 列挙のメンバを受け取る変数へのポインタ。
fDVInfo
[in] ストリーム フォーマットを指定する DVINFO 構造体を取得するかどうかを指定するブール型の値。TRUE の場合は、sDVInfo パラメータによってストリーム フォーマットが返される。
sDVInfo
[out] ストリーム フォーマットが格納されている DVINFO 構造体を受け取る変数へのポインタ。(fDVInfo が FALSE の場合、このパラメータは無視される。)

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_FAIL またはその他のエラー コードを返す。

IDVEnc::put_IFormatResolution

IDVEnc インターフェイス

エンコーディング解像度を設定する。

構文

HRESULT put_IFormatResolution(
    int VideoFormat,
    int DVFormat,
    int Resolution,
    BYTE fDVInfo,
    DVINFO *sDVInfo
);

パラメータ

VideoFormat
[in] 使用するビデオ方式 (NTSC または PAL) を指定する DVENCODERVIDEOFORMAT 列挙のメンバ。
DVFormat
[in] DV フォーマットを指定する DVENCODERFORMAT 列挙のメンバ。
Resolution
[in] ビデオ解像度を指定する DVENCODERRESOLUTION 列挙のメンバ。
fDVInfo
[in] sDVInfo パラメータに有効な DVINFO 構造体を格納するかどうかを指定するブール型の値。ストリーム フォーマットを設定するには、このパラメータを TRUE に設定し、フォーマット チャンクを sDVInfo パラメータで指定する。
sDVInfo
[in] fDVInfo が TRUE の場合、このパラメータはストリーム フォーマットを記述する DVINFO 構造体を指す必要がある。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_FAIL またはその他のエラー コードを返す。


IDVSplitter インターフェイス

デジタル ビデオ (DV) ストリームのフレーム レートをダウングレードする。DV スプリッタ フィルタはこのインターフェイスを公開する。

アプリケーションはこのインターフェイスを使って、ストリームが DV ビデオ デコーダに届く前に DV ストリームのフレーム レートを削減する。これはリアルタイム デコードの様なプロセッサの負荷の高いタスクに有効となリ得る。

Vtable 順のメソッド

IUnknown methods | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IDVSplitter メソッド | 説明
DiscardAlternateVideoFrames | ビデオ ストリームのフレームの半分を廃棄する。

IDVSplitter::DiscardAlternateVideoFrames

IDVSplitter インターフェイス

ビデオ ストリームのフレームの半分を廃棄する。NTSC ではフレーム レートは毎秒 30 フレーム (fps) から 15 fps に削減される。PAL では フレーム レートは 25 fps から 12.5 fps に削減される。

構文

HRESULT DiscardAlternateVideoFrames(
    int nDiscard
);

パラメータ

nDiscard
[in] フレームを削減するかどうかを示すフラグ。値がゼロ以外なら、フィルタは 1 フレームおきにフレームを廃棄する。値がゼロなら、フィルタはすべてのフレームを廃棄する。

戻り値

HRESULT 値を返す。 以下の表に示されるいずれかの値。

S_OK | 成功。
E_UNEXPECTED | フィルタはポーズあるいは実行中。


IEnumFilters インターフェイス

IFilterGraph::EnumFilters メソッドはこのインターフェイスを返す、それはフィルタ グラフ内で現在フィルタを持っている標準的な Component Object Model (COM) コレクション オブジェクトへのアクセスを提供する。COM コレクションについては Platform SDK の IEnumXXXX トピックを参照。フィルタの列挙についての詳細については、「Enumerating Objects in a Filter Graph」を参照すること。

グラフ内のフィルタ セットが変更になったなら、このインターフェイスのいくつかのメソッドが VFW_E_ENUM_OUT_OF_SYNC を返す。Reset メソッドを呼び出して列挙子を再同期すること。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IEnumFilters メソッド | 説明
Next | 列挙シーケンスの中で、指定のフィルタ数を取得する。
Skip | 指定のフィルタ数をスキップする。
Reset | 列挙シーケンスを先頭からリセットする。
Clone | 同じ列挙状態で、列挙子のコピーを作成する。

IEnumFilters::Clone

IEnumFilters インターフェイス

同じ列挙状態で、列挙子のコピーを作成する

構文

HRESULT Clone(
    IEnumFilters **ppEnum
);

パラメータ

ppEnum
[out] 新しい列挙子 IEnumFilters へのポインタを受け取る変数のアドレス。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_OUTOFMEMORY | メモリ不足。
E_POINTER | Null ポインタ引数。

IEnumFilters::Next

IEnumFilters インターフェイス

列挙シーケンスの中で、指定のフィルタ数を取得する。

構文

HRESULT Next(
    ULONG cFilters,
    IBaseFilter **ppFilter,
    ULONG *pcFetched
);

パラメータ

cFilters
[in] 取得するフィルタの数。
ppFilter
[out] cFilters サイズの配列、ここに IBaseFilter ポインタが配置される。
pcFetched
[out] 取得したフィルタの数を受け取る変数へのポインタ。cFilters が 1 なら、NULL もあり得る。

戻り値

次のいずれかの HRESULT 値を返す。

S_FALSE | 要求された数と同じ数のフィルタを取得できなかった。
S_OK | 成功。
E_INVALIDARG | 無効な引数。
E_POINTER | Null ポインタ引数。
VFW_E_ENUM_OUT_OF_SYNC | グラフが変更され、この列挙子と互換性がない。

注意

メソッドが成功すると、IBaseFilter ポインタすべてに参照カウントが残る。解放時に注意が必要。

フィルタ グラフが変更される(たとえば、アプリケーションがあるフィルタを削除した)と、列挙子はそのグラフとの互換性をなくし、メソッドは VFW_E_ENUM_OUT_OF_SYNC を返す。列挙子へのその前の呼び出しで取得したデータは廃棄すること、なぜなら有効ではない可能性があるからだ。Reset メソッドを呼び出して列挙子をアップデートすること。そうすれば Next メソッドを安全に呼び出すことができる。

IEnumFilters::Reset

IEnumFilters インターフェイス

列挙シーケンスを先頭からリセットする。

構文

HRESULT Reset(void);

戻り値

成功を示す S_OK を返す。

IEnumFilters::Skip

IEnumFilters インターフェイス

指定のフィルタ数をスキップする。

構文

HRESULT Skip(
    ULONG cFilter
);

パラメータ

cFilter
[in] スキップするフィルタ数。

戻り値

次のいずれかの HRESULT 値を返す。

S_FALSE | スキップはシーケンスの最後を越えた。
S_OK | 成功。
VFW_E_ENUM_OUT_OF_SYNC | グラフは変更されて、現在その列挙子と互換性がない。

注意

フィルタ グラフが変更される(たとえば、アプリケーションがあるフィルタを削除した)と、列挙子はそのグラフとの互換性をなくし、メソッドは VFW_E_ENUM_OUT_OF_SYNC を返す。列挙子へのその前の呼び出しで取得したデータは廃棄すること、なぜなら有効ではない可能性があるからだ。Reset メソッドを呼び出して列挙子をアップデートすること。そうすれば Skip メソッドを安全に呼び出すことができる。


IEnumMediaTypes インターフェイス

ピンの許容するフォーマットを列挙する。

IPin::EnumMediaTypes メソッドはこのインターフェイスを返す。それは標準 Component Object Model (COM) 列挙子をベースにしている。詳細については、Platform SDK の IEnumXXXX トピックを参照すること。

ピンが他のピンと接続するとき、ピンはこのインターフェイスを使用する。アプリケーションはそれを使って、ピンの許容するメディアタイプを試験することもできる。詳細については、「Enumerating Objects in a Filter Graph」を参照すること。

ピンの許容するメディア タイプが変更されると、このインターフェイスのあるメソッドが VFW_E_ENUM_OUT_OF_SYNC を返す。Reset メソッドを呼び出して列挙子を再同期すること。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IEnumMediaTypes メソッド | 説明
Next | 指定した数のメディア タイプを取得する。
Skip | 指定した数のメディア タイプをスキップする。
Reset | 列挙シーケンスを先頭からリセットする。
Clone | 同じ列挙状態で列挙子のコピーを作成する。

IEnumMediaTypes::Clone

IEnumMediaTypes インターフェイス

同じ列挙状態で列挙子のコピーを作成する。

構文

HRESULT Clone(
    IEnumMediaTypes **ppEnum
);

パラメータ

ppEnum
[out] 新しい列挙子のIEnumMediaTypes インターフェイスへのポインタを受け取る変数のアドレス。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_OUTOFMEMORY | メモリ不足。
E_POINTER | Null ポインタ引数。
VFW_E_ENUM_OUT_OF_SYNC | ピンの状態が変更になり、現在その列挙子と互換性がない。

注意

メディア タイプが変更されると、列挙子はそのピンとの互換性をなくし、メソッドは VFW_E_ENUM_OUT_OF_SYNC を返す。列挙子へのその前の呼び出しで取得したデータは廃棄すること、なぜなら有効ではない可能性があるからだ。Reset メソッドを呼び出して列挙子をアップデートすること。そうすれば Clone メソッドを安全に呼び出すことができる。

IEnumMediaTypes::Next

IEnumMediaTypes インターフェイス

指定した数のメディア タイプを取得する。

構文

HRESULT Next(
    ULONG cMediaTypes,
    AM_MEDIA_TYPE **ppMediaTypes,
    ULONG *pcFetched
);

パラメータ

cMediaTypes
[in] 取得するメディア タイプ数。
ppMediaTypes
[out] cPins サイズの AM_MEDIA_TYPE 構造体へのポインタの配列。
pcFetched
[out] メソッドが返したメディア タイプの数を受け取る変数へのポインタ。cMediaTypes が 1 なら NULL の場合もある。

戻り値

次のいずれかの HRESULT 値を返す。

S_FALSE | 要求されたメディア タイプの数と同じ数を取得できなかった。
S_OK | 成功。
E_INVALIDARG | 無効な引数。
E_POINTER | Null ポインタ引数。
VFW_E_ENUM_OUT_OF_SYNC | ピンの状態が変更になり、現在その列挙子と互換性がない。

注意

メソッドが成功すると、ppMediaTypes によって指定された配列には AM_MEDIA_TYPE 構造体へのポインタが入る。構造体の数は *pcFetched と等しい。DeleteMediaType を呼び出して各メディア タイプを解放すること。

メディア タイプが変更されると、列挙子はそのピンとの互換性をなくし、メソッドは VFW_E_ENUM_OUT_OF_SYNC を返す。列挙子へのその前の呼び出しで取得したデータは廃棄すること、なぜなら有効ではない可能性があるからだ。Reset メソッドを呼び出して列挙子をアップデートすること。そうすれば Next メソッドを安全に呼び出すことができる。

IEnumMediaTypes::Reset

IEnumMediaTypes インターフェイス

列挙シーケンスを先頭からリセットする。

構文

HRESULT Reset(void);

戻り値

S_OK を返す。

IEnumMediaTypes::Skip

IEnumMediaTypes インターフェイス

指定した数のメディア タイプをスキップする。

構文

HRESULT Skip(
    ULONG cMediaTypes);

パラメータ

cMediaTypes
[in] スキップするメディア タイプの数。

戻り値

次のいずれかの HRESULT 値を返す。

S_FALSE | スキップはシーケンスの最後を越えた。
S_OK | 成功。
VFW_E_ENUM_OUT_OF_SYNC | ピンの状態が変更され、現在その列挙子と互換性がない。

注意

メディア タイプが変更されると、列挙子はそのピンとの互換性をなくし、メソッドは VFW_E_ENUM_OUT_OF_SYNC を返す。列挙子へのその前の呼び出しで取得したデータは廃棄すること、なぜなら有効ではない可能性があるからだ。Reset メソッドを呼び出して列挙子をアップデートすること。そうすれば Skip メソッドを安全に呼び出すことができる。


IEnumPIDMap インターフェイス

このインターフェイスはパケット ID (PID) マップの 標準 COM コレクションで実装されている、PID マップは MPEG-2 デマルチプレクサの出力ピンの IMPEG2PIDMap::MapPID メソッドを呼び出すことにより作成される。このインターフェイスのポインタを取得するには、IMPEG2PIDMap::EnumPIDMap メソッドを使用する。通常、オーディオとビデオ ストリームの出力ピンは与えられた時間にマップされた PID を 1 つしか持たない。このコレクションはそれが作成されたときにマップされた PID のスナップショットを表す。このコレクションは自動的にはアップデートされない。

メソッド名 | 説明
Clone | 新しいコレクションとそのサブ オブジェクトすべての新しいコピーを作成する。
Next | コレクションの次の n 要素を取得する。
Reset | イタレータをコレクションの先頭に移動する。
Skip | コレクション内の指定した要素をスキップする。

IEnumPIDMap::Clone

IEnumPIDMap インターフェイス

コレクションをコピーする。

構文

HRESULT Clone(
    IEnumPIDMap** ppIEnumPIDMap
    );

パラメータ

ppIEnumPIDMap
[out] 返されるコレクション オブジェクトにセットされる IEnumPIDMap インターフェイス ポインタのアドレス。

戻り値

成功なら S_OK を返す。メソッドが失敗すると、標準 COM IErrorInfo インターフェイスを使ってエラー情報が取得できる。

IEnumPIDMap::Next

IEnumPIDMap インターフェイス

コレクションの次の n 要素を取得する。

構文

HRESULT Next(
    ULONG cRequest,
    PID_MAP* pPIDMap,
    ULONG* pcReceived
    );

パラメータ

cRequest
[in] 取得する要素の数。
pPIDMap
[in, out, size_is (cRequest)] 呼び出し元が割り当てた配列のアドレス、取得される PID_MAP 構造体を受け取る cRequest 要素が入る。
pcReceived
[out] 実際に取得された要素の数が入る ULONG 型の変数のポインタ。

戻り値

成功なら S_OK を返す。メソッドが失敗すると、標準 COM IErrorInfo インターフェイスを使ってエラー情報が取得できる。

注意

cRequest = 0 かつ pcReceived が NULL なら、コレクションに残っている PID マップの数が入った pcReceived が返る。

IEnumPIDMap::Reset

IEnumPIDMap インターフェイス

イタレータをコレクションの先頭に移動する。

構文

HRESULT Reset();

戻り値

成功なら S_OK を返す。メソッドが失敗すると、標準 COM IErrorInfo インターフェイスを使ってエラー情報が取得できる。

IEnumPIDMap::Skip

IEnumPIDMap インターフェイス

コレクション内の指定した要素をスキップする。

構文

HRESULT Skip(
    ULONG cRecords
    );

パラメータ

cRecords
[in] スキップする要素のインデックス。

戻り値

成功なら S_OK を返す。メソッドが失敗すると、標準 COM IErrorInfo インターフェイスを使ってエラー情報が取得できる。


IEnumPins インターフェイス

フィルタ上のピンを列挙する。

IBaseFilter::EnumPins メソッドは、このインターフェイスを返す。このメソッドは、標準 Component Object Model (COM) 列挙子を基にしている。詳細については、Platform SDK の「IEnumXXXX」 というトピックを参照すること。

フィルタ グラフ マネージャは、フィルタと接続するときこのインターフェイスを使用する。アプリケーションは、このインターフェイスを使って、フィルタ上のピンを取得することができる。詳細については、「フィルタ グラフ内のオブジェクトの列挙」を参照すること。

フィルタのピンの数が変更になると、このインターフェイスのいくつかのメソッドが VFW_E_ENUM_OUT_OF_SYNC を返す。Reset を呼び出して列挙子を再同期する。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IEnumPins メソッド | 説明
Next | 指定した数のピンを取得する。
Skip | 指定した数のピンをスキップする。
Reset | 列挙子をシーケンスの先頭からリセットする。
Clone | 同じ列挙状態で列挙子のコピーを作成する。

IEnumPins::Clone

IEnumPins インターフェイス

同じ列挙状態で列挙子のコピーを作成する。

構文

HRESULT Clone(
    IEnumPins **ppEnum
);

パラメータ

ppEnum
[out] 新しい列挙子の IEnumPins インターフェイスへのポインタを受け取る変数のアドレス。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_OUTOFMEMORY | メモリ不足。
E_POINTER | Null ポインタ引数。
VFW_E_ENUM_OUT_OF_SYNC | フィルタの状態が変更になり、現在その列挙子と互換性がない。

注意

ピンの数が変更されると、列挙子はそのピンとの互換性をなくし、メソッドは VFW_E_ENUM_OUT_OF_SYNC を返す。列挙子へのその前の呼び出しで取得したデータは廃棄すること、なぜなら有効ではない可能性があるからだ。Reset メソッドを呼び出して列挙子をアップデートすること。そうすれば Clone メソッドを安全に呼び出すことができる。

IEnumPins::Next

IEnumPins インターフェイス

列挙シーケンスで指定した数のピンを取得する。

構文

HRESULT Next(
    ULONG cPins,
    IPin **ppPins,
    ULONG *pcFetched
);

パラメータ

cPins
[in] 取得するピンの数。
ppPins
[out] IPin ポインタが書き込まれる cPins サイズの配列。
pcFetched
[out] 取得したピンの数を受け取る変数へのポインタ。cPins が 1 なら NULL の場合もある。

戻り値

次のいずれかの HRESULT 値を返す。

S_FALSE | 要求した数と同じ数のピンを取得できなかった。
S_OK | 成功。
E_INVALIDARG | 無効な引数。
E_POINTER | Null ポインタ引数。
VFW_E_ENUM_OUT_OF_SYNC | フィルタの状態が変更になり、現在その列挙子と互換性がない。

注意

このメソッドは、列挙の現在位置から開始して、指定した数のピンへのポインタを取得し、それを指定した配列に置く。

メソッドが成功すると、IPin ポインタすべてに参照カウントが残る。解放時に注意が必要。

ピンの数が変更されると、列挙子はそのピンとの互換性をなくし、メソッドは VFW_E_ENUM_OUT_OF_SYNC を返す。列挙子へのその前の呼び出しで取得したデータは廃棄すること、なぜなら有効ではない可能性があるからだ。Reset メソッドを呼び出して列挙子をアップデートすること。そうすれば Next メソッドを安全に呼び出すことができる。

IEnumPins::Reset

IEnumPins インターフェイス

列挙子をシーケンスの先頭からリセットする。

構文

HRESULT Reset(void);

戻り値

S_OK を返す。

IEnumPins::Skip

IEnumPins インターフェイス

指定した数のピンをスキップする。

構文

HRESULT Skip(
    ULONG cPins
);

パラメータ

cPins
[in] スキップするピン数。

戻り値

次のいずれかの HRESULT 値を返す。

S_FALSE | スキップはシーケンスの最後を越えた。
S_OK | 成功。
VFW_E_ENUM_OUT_OF_SYNC | フィルタの状態が変更になり、現在その列挙子と互換性がない。

注意

ピンの数が変更されると、列挙子はそのピンとの互換性をなくし、メソッドは VFW_E_ENUM_OUT_OF_SYNC を返す。列挙子へのその前の呼び出しで取得したデータは廃棄すること、なぜなら有効ではない可能性があるからだ。Reset メソッドを呼び出して列挙子をアップデートすること。そうすれば Skip メソッドを安全に呼び出すことができる。


IEnumStreamIdMap インターフェイス

このインターフェイスは MPEG-2 デマルチプレクサのIMPEG2StreamIdMap::MapStreamID メソッドによって作成された ストリーム ID マップの標準 COM コレクションで実装されいる。このインターフェイスのポインタを取得するには、IMPEG2StreamIdMap::EnumStreamIdMap メソッドを使用する。通常、出力ピンは与えられた時間にそれをマップするストリーム ID を 1 以上は持たない。このコレクションはそれが作成されたときにマップされた ストリーム ID のスナップショットを表す。このコレクションは自動的にはアップデートされない。

メソッド名 | 説明
Clone | 新しいコレクションとそのサブ オブジェクトすべての新しいコピーを作成する。
Next | コレクションの次の n 要素を取得する。
Reset | イタレータをコレクションの先頭に移動する。
Skip | コレクション内の指定した要素をスキップする。

IEnumStreamIdMap::Clone

IEnumStreamIdMap インターフェイス

コレクションをコピーする。

構文

HRESULT Clone(
    IEnumStreamIdMap** ppIEnumStreamIdMap
    );

パラメータ

ppIEnumStreamIdMap
[out] 返されるコレクション オブジェクトにセットされる IEnumStreamIdMap インターフェイス ポインタのアドレス。

戻り値

成功なら S_OK を返す。メソッドが失敗すると、標準 COM IErrorInfo インターフェイスを使ってエラー情報が取得できる。

IEnumStreamIdMap::Next

IEnumStreamIdMap インターフェイス

コレクションの次の n 要素を取得する。

構文

HRESULT Next(
    ULONG cRequest,
    STREAM_ID_MAP* pStreamIdMap,
    ULONG* pcReceived
    );

パラメータ

cRequest
[in] 取得する要素の数。
pStreamIdMap
[in, out, size_is (cRequest)] 呼び出し元が割り当てた配列のアドレス、取得される STREAM_ID_MAP 構造体を受け取る cRequest 要素が入る。
pcReceived
[out] 実際に取得された要素の数が入る ULONG 型の変数のポインタ。

戻り値

成功なら S_OK を返す。メソッドが失敗すると、標準 COM IErrorInfo インターフェイスを使ってエラー情報が取得できる。

注意

cRequest = 0 かつ pcReceived が NULL なら、コレクションに残っている PID マップの数が入った pcReceived が返る。

IEnumStreamIdMap::Reset

IEnumStreamIdMap インターフェイス

イタレータをコレクションの先頭に移動する。

構文

HRESULT Reset();

戻り値

成功なら S_OK を返す。メソッドが失敗すると、標準 COM IErrorInfo インターフェイスを使ってエラー情報が取得できる。

IEnumStreamIdMap::Skip

IEnumStreamIdMap インターフェイス

コレクション内の指定した要素をスキップする。

構文

HRESULT Skip(
    ULONG cRecords
    );

パラメータ

cRecords
[in] スキップする要素のインデックス。

戻り値

成功なら S_OK を返す。メソッドが失敗すると、標準 COM IErrorInfo インターフェイスを使ってエラー情報が取得できる。


IFileSinkFilter インターフェイス

IFileSinkFilter インターフェイスは、メディア ストリームをファイルに書き込むフィルタに実装される。たとえば、ビデオ キャプチャ用フィルタ グラフのファイル シンク フィルタでは、ビデオ圧縮フィルタの出力をファイルに書き込む。通常、このフィルタ グラフを実行するアプリケーションでは、ユーザーが出力先のファイル名を入力できる必要がある。このインターフェイスを使用すると、その情報をやり取りできる。

Microsoft® ActiveMovie® 1.0 との後方互換性を保つ必要がない場合は、このインターフェイスではなく IFileSinkFilter2 を使用してもよい。

出力ファイル名を受け取る必要があるフィルタでは、アプリケーションからファイル名を設定するため、このインターフェイスを公開しなければならない。現在、このインターフェイスを実装する基底クラスはない。

ファイル シンク フィルタの出力先ファイル名を設定する必要があるアプリケーションでは、このインターフェイスを使用してファイル名を取得および設定すること。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IFileSinkFilter メソッド | 説明
SetFileName | メディア サンプルの出力先ファイル名を設定する。
GetCurFile | メディア サンプルが書き込まれる現在のファイル (シンク ファイル) の名前を取得する。

IFileSinkFilter::GetCurFile

IFileSinkFilter インターフェイス

メディア サンプルが書き込まれる現在のファイル (シンク ファイル) の名前を取得する。

構文

HRESULT GetCurFile(
    LPOLESTR *ppszFileName,
    AM_MEDIA_TYPE *pmt
);

パラメータ

ppszFileName
[out] メディア サンプルの出力先ファイル名へのポインタのアドレス。
pmt
[out] ファイルに書き込まれるメディア サンプルのタイプへのポインタ。

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
S_OK または NOERROR | 成功。

ファイル名が割り当てられなかった場合、このメソッドは E_FAIL を返す。

IFileSinkFilter::SetFileName

IFileSinkFilter インターフェイス

メディア サンプルの出力先ファイル名を設定する。

構文

HRESULT SetFileName(
    LPCOLESTR pszFileName,
    const AM_MEDIA_TYPE *pmt
);

パラメータ

pszFileName
[in] メディア サンプルの出力先ファイル名へのポインタ。
pmt
[in] ファイルに書き込むメディア サンプルのタイプと、シンク フィルタの入力ピンのメディア タイプへのポインタ。

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
S_OK または NOERROR | 成功。

注意

pszFileName パラメータのファイルが存在しない場合には、そのファイルが作成される。既存ファイルの場合、シンク フィルタはファイルを先に破棄ぜすにオーバーライドする。


IFileSinkFilter2 インターフェイス

IFileSinkFilter2 インターフェイスは、IFileSinkFilter インターフェイスから派生するものであり、Microsoft® ActiveMovie® 1.0 との後方互換性を保つ必要がない場合は、こちらのインターフェイスを使用してもよい。IFileSinkFilter 同様、メディア ストリームをファイルに書き込むフィルタでは、このインターフェイスを実装する。たとえば、ビデオ キャプチャ用フィルタ グラフのファイル シンク フィルタは、圧縮フィルタの出力をファイルに保存する。通常、このフィルタ グラフを実行するアプリケーションでは、ユーザーが保存先のファイル名を入力できなければいけない。このインターフェイスを使用すると、その情報をやり取りできる。 IFileSinkFilter2 には、既に同じ名前のファイルがある場合に既存ファイルを破棄すべきかどうかを決定するオプションが加わっている。ビデオ キャプチャの場合、ファイル容量を事前に割り当てるには非常に時間がかかるため、既に作成したファイルを破棄しないこと。デフォルトでは、元のファイルは破棄されない。それ以外の場合、新しく書き込むファイルに不要なデータを残さないため、元のファイルが破棄される。

出力ファイル名を必要とするフィルタ、または出力ファイルのオプションを設定する必要があるフィルタでは、このインターフェイスを実装しなければならない。開発するフィルタと ActiveMovie 1.0 との互換性を保つには、従来の IFileSinkFilter インターフェイスを実装する。現在、このインターフェイスを実装する基底クラスはない。

ファイル シンク フィルタの出力先ファイル名を設定する必要があるアプリケーションでは、このインターフェイスを使用して、ファイル名を取得および設定するか、またはオプションを設定しなければならない。開発するアプリケーションと ActiveMovie 1.0 との互換性を保つには、従来の IFileSinkFilter インターフェイスを使用すること。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IFileSinkFilter メソッド | 説明
SetFileName | メディア サンプルの出力先ファイル名を設定する。
GetCurFile | メディア サンプルが書き込まれる現在のファイル (シンク ファイル) の名前を取得する。
IFileSinkFilter2 メソッド | 説明
SetMode | 新規ファイルの作成時にファイル ライタがファイルを破棄するかどうかを決定する。
GetMode | 新規ファイルの作成時にファイル ライタがファイルを破棄するかどうかを取得する。

IFileSinkFilter2::GetMode

IFileSinkFilter2 インターフェイス

新規ファイルの作成時にファイル ライタがファイルを破棄するかどうかを取得する。

構文

HRESULT GetMode(
    DWORD *dwFlags
);

パラメータ

dwFlags
[out] 取得されたフラグへのポインタ。現在定義されているフラグは、ファイルを破棄することを示す AM_FILE_OVERWRITE のみ。0 はファイルを破棄しないことを示す。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

IFileSinkFilter2::SetMode

IFileSinkFilter2 インターフェイス

新規ファイルの作成時にファイル ライタがファイルを破棄するかどうかを決定する。

構文

HRESULT SetMode(
    DWORD dwFlags
);

パラメータ

dwFlags
[in] 現在定義されているフラグは、ファイルを破棄することを示す AM_FILE_OVERWRITE のみ。ファイルを破棄しないためには、dwFlags に 0 を指定する。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。


IFileSourceFilter インターフェイス

IFileSourceFilter インターフェイスは、レンダリングするメディア ファイルのファイル名およびメディア タイプを設定するため、ソース フィルタで公開される。このインターフェイスは、IPersistFile COM インターフェイスの省略版である。「カスタム ファイル タイプの登録」にあるアルゴリズムで判断できるタイプのファイルの場合、そのフィルタ グラフをレンダリングするとき、フィルタ グラフ マネージャは推奨されたファイル ソース フィルタの CLSID を使用する。

ファイルを開くときにファイル名が必要なフィルタでは、アプリケーションからファイル名を設定するため、このインターフェイスを公開しなければならない。現在、このインターフェイスを実装する基底クラスはない。

ファイル ソース フィルタを直接挿入するアプリケーションでは、このインターフェイスを照会し、ファイル名を設定しなければならない。通常、アプリケーションから IGraphBuilder::RenderFile を呼び出すと、フィルタ グラフ マネージャはこのインターフェイスを使用する。Graphedt.exe ツールは、IFileSourceFilter インターフェイスを照会し、インターフェイスがわかったら、ファイル名の入力を求めるプロンプトを表示する。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを返す。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IFileSourceFilter メソッド | 説明
Load | ソース フィルタにファイルをロードする。
GetCurfile | 現在のファイルを取得する。

IFileSourceFilter::GetCurfile

IFileSourceFilter インターフェイス

開くファイルに関する情報を収集する。

構文

HRESULT GetCurfile(
  LPOLESTR *ppszFileName,
  AM_MEDIA_TYPE *pmt
  );

パラメータ

ppszFileName
[out] ロードされたファイルのパスへのポインタのアドレス。
pmt
[out] メディア タイプへのポインタ。

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
S_OK または NOERROR | 成功。

IFileSourceFilter::Load

IFileSourceFilter インターフェイス

メディア ファイルをロードする。

構文

HRESULT Load(
  LPCOLESTR pszFileName,
  const AM_MEDIA_TYPE *pmt
  );

パラメータ

pszFileName
[in] 開くファイルの絶対パスへのポインタ。
pmt
[in] ファイルのメディア タイプへのポインタ。NULL の場合がある。

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
S_OK または NOERROR | 成功。

注意

このメソッドはインターフェイスの初期化メソッドである。複数ファイルをロードするように設計されていないため、最初の呼び出し以降の呼び出しはすべて失敗する。

pszFileName で指定されたファイルをロードするには、このメソッドを実装しなければならない。

pszFileName の名前は、ディスク ファイル名 (たとえば Microsoft® Win32® CreateFile 関数に渡すことができるファイル名) である必要はない。URL 名でもよい。URL モニカ フィルタは、IFileSourceFilter を使用してその URL 名を取得し、IGraphBuilder::AddSourceFilter (および IGraphBuilder::RenderFile) がそれを適切に処理する。ファイルが見つからない場合、IGraphBuilder::AddSourceFilter は固有のエラー (ERROR_FILE_NOT_FOUND) を返す。このエラーは、指定されたファイルが存在しないという意味であり、フィルタが存在しないという意味ではない。


IFilterChain インターフェイス

このインターフェイスは、フィルタ グラフのフィルタ チェーンを開始、停止、または削除するメソッドを提供する。フィルタ グラフ マネージャがこのインターフェイスを公開する。

"フィルタ チェーン" は、一連のフォルタから成る 1 つの連続したフィルタである。個々のフィルタには 1 つまでの入力ピンと 1 つの出力ピンが接続される。フィルタ チェーンは、チェーン先頭フィルタとチェーン終端フィルタにより定義される (先頭フィルタと終端フィルタが同じ場合は、フィルタを 1 つだけ含むチェーンとなる)。定義によって、チェーンの先頭からダウンストリームへ終端まで続く単一のストリームができる。

このインターフェイスのメソッドは、ネットワーク経由で複数のストリームを受信するテレビ会議アプリケーションのように、データ ストリーム全体が現れたり消えたりする場合に利用する。詳細については、「動的グラフ作成」を参照すること。キャプチャ フィルタ上の個々のストリームを制御するには、このインターフェイスではなく、IAMStreamControl インターフェイスを使用する。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IFilterChain メソッド | 説明
StartChain | フィルタ チェーンのフィルタをすべて実行状態に切り替える。
StopChain | フィルタ チェーンのフィルタをすべて停止状態に切り替える。
RemoveChain | フィルタ チェーンのフィルタをすべてフィルタ グラフから削除する。
PauseChain | フィルタ チェーンのフィルタをすべて一時ポーズ状態に切り替える。

IFilterChain::PauseChain

IFilterChain インターフェイス

フィルタ チェーンのフィルタをすべてポーズ状態に切り替える。

構文

HRESULT PauseChain(
    IBaseFilter *pStartFilter,
    IBaseFilter *pEndFilter
);

パラメータ

pStartFilter
[in] チェーン先頭フィルタへのポインタ。
pEndFilter
[in] チェーン終端フィルタへのポインタ。このパラメータが NULL の場合、メソッドは先頭フィルタからダウンストリームへと続く最長のフィルタ チェーンを使用する。

戻り値

成功した場合は、S_OK を返す。メソッドが失敗した場合、戻り値は VFW_E_NOT_PAUSED またはその他の HRESULT 値になる。

注意

所定のフィルタをポーズ状態に切り替えることができない場合、このメソッドはチェーンのフィルタをすべて停止する。このメソッドを呼び出すとき、フィルタ グラフはポーズしていなければならない。

IFilterChain::RemoveChain

IFilterChain インターフェイス

フィルタ チェーンのフィルタをすべてフィルタ グラフから削除する。

構文

HRESULT RemoveChain(
    IBaseFilter *pStartFilter,
    IBaseFilter *pEndFilter
);

パラメータ

pStartFilter
[in] チェーン先頭フィルタへのポインタ。
pEndFilter
[in] チェーン終端フィルタへのポインタ。このパラメータが NULL の場合、メソッドは先頭フィルタからダウンストリームへと続く最長のフィルタ チェーンを使用する。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、失敗の原因を示す HRESULT 値を返す。

注意

このメソッドはグラフ実行中に呼び出すことができる。その場合、メソッドはチェーン内のフィルタを停止してからフィルタをグラフから削除する。

IFilterChain::StartChain

IFilterChain インターフェイス

フィルタ チェーンのフィルタをすべて実行状態に切り替える。

構文

HRESULT StartChain(
    IBaseFilter *pStartFilter,
    IBaseFilter *pEndFilter
);

パラメータ

pStartFilter
[in] チェーン先頭フィルタへのポインタ。
pEndFilter
[in] チェーン終端フィルタへのポインタ。このパラメータが NULL の場合、メソッドは先頭フィルタからダウンストリームへと続く最長のフィルタ チェーンを使用する。

戻り値

成功した場合は、S_OK を返す。メソッドが失敗した場合、戻り値は VFW_E_NOT_RUNNING またはその他の HRESULT 値になる。

注意

所定のフィルタを実行状態に切り替えることができない場合、フィルタはすべて停止状態に留まる。このメソッドを呼び出すとき、フィルタ グラフは実行中でなければならない。

IFilterChain::StopChain

IFilterChain インターフェイス

フィルタ チェーンのフィルタをすべて停止状態に切り替える。

構文

HRESULT StopChain(
    IBaseFilter *pStartFilter,
    IBaseFilter *pEndFilter
);

パラメータ

pStartFilter
[in] チェーン先頭フィルタへのポインタ。
pEndFilter
[in] チェーン終端フィルタへのポインタ。このパラメータが NULL の場合、メソッドは先頭フィルタからダウンストリームへと続く最長のフィルタ チェーンを使用する。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、失敗の原因を示す HRESULT 値を返す。


IFilterGraph インターフェイス

このインターフェイスはフィルタ グラフを構築するメソッドを提供する。アプリケーションからこのインターフェイスを使用して、グラフにフィルタを追加したり、フィルタを接続または切断したり、フィルタを削除したり、その他の基本的な操作を実行することができる。ただし、IGraphBuilder インターフェイスは、このインターフェイスを継承し、さらに高度なメソッドを提供する。したがって、アプリケーションでは、IFilterGraph を直接使用せずに、IGraphBuilder を使用すること。

フィルタ グラフ マネージャがこのインターフェイスを実装する。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IFilterGraph メソッド | 説明
AddFilter | グラフにフィルタを追加し、そのフィルタに名前を付ける。
RemoveFilter | グラフからフィルタを削除する。
EnumFilters | グラフのフィルタすべてに対して列挙子を提供する。
FindFilterByName | 特定の名前で追加されたフィルタを検索する。
ConnectDirect | 2 つのピンを直接接続する (フィルタを通さない)。
Reconnect | 既存のピン接続を切断し、同じピンに再接続する。
Disconnect | 特定のピンを切断する。
SetDefaultSyncSource | デフォルトの同期基準 (クロック) を設定する。

IFilterGraph::AddFilter

IFilterGraph インターフェイス

グラフにフィルタを追加し、そのフィルタに名前を付ける。

構文

HRESULT AddFilter(
    IBaseFilter *pFilter,
    LPCWSTR pName
);

パラメータ

pFilter
[in] グラフに追加するフィルタへのポインタ。
pName
[in] フィルタ名へのポインタ。

戻り値

HRESULT 値を返す。可能な値は次のとおりである。

S_OK | 成功。
VFW_S_DUPLICATE_NAME | 名前が重複したフィルタの追加に成功した。
E_FAIL | 失敗。
E_OUTOFMEMORY | メモリ不足。
E_POINTER | Null ポインタ引数。
VFW_E_CERTIFICATION_FAILURE | このフィルタの使用は、ソフトウェア キーによって制限される。
VFW_E_DUPLICATE_NAME | 名前が重複したフィルタの追加に失敗した。

注意

フィルタ名は NULL の場合がある。その場合、フィルタ グラフ マネージャが名前を生成する。フィルタ名が NULL 以外で一意でない場合、このメソッドは、フィルタ名を変更して一意な名前を生成しようとする。これに成功すると、VFW_S_DUPLICATE_NAME を返す。一意な名前を生成できない場合は、VFW_E_DUPLICATE_NAME を返す。

AddFilter は、フィルタの IBaseFilter::JoinFilterGraph メソッドを呼び出して、フィルタが追加されたことをそのフィルタに通知する。IGraphBuilder::Connect メソッド、IFilterGraph::ConnectDirect メソッド、または IGraphBuilder::Render メソッドを使用して、追加したフィルタに属するピンを接続またはレンダリングする場合には、その前に AddFilter を呼び出さなければならない。

IFilterGraph::ConnectDirect

IFilterGraph インターフェイス

2 つのピンを直接接続する (フィルタを通さない)。

構文

HRESULT ConnectDirect(
    IPin *ppinOut,
    IPin *ppinIn,
    const AM_MEDIA_TYPE *pmt
);

パラメータ

ppinOut
[in] 出力ピンへのポインタ。
ppinIn
[in] 入力ピンへのポインタ。
pmt
[in] 接続に使用するメディア タイプへのポインタ (省略、つまり NULL も可能)。

戻り値

次のいずれかの値か、または IPin::Connect が返したエラー値を返す。

S_OK | 成功。
E_POINTER | Null ポインタ引数。
VFW_E_NOT_IN_GRAPH | 指定されたピンのいずれかがグラフに含まれていない。
VFW_E_CIRCULAR_GRAPH | 入力ピンが出力ピンのアップストリームにあるため、グラフが循環する。

IFilterGraph::Disconnect

IFilterGraph インターフェイス

このピンを切断する。

構文

HRESULT Disconnect(
    IPin *ppin
);

パラメータ

ppin
[in] 切断するピンへのポインタ。

戻り値

次のいずれかの値を返す。

S_OK | 成功。
S_FALSE | ピンが接続されていない。エラーなし。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
VFW_E_NOT_STOPPED | フィルタが停止していないが、実行状態での再接続がサポートされていない。

注意

このメソッドでは、接続が完全には切断されない。完全に切断するには、両端を切断しなければならない。

IFilterGraph::EnumFilters

IFilterGraph インターフェイス

グラフのフィルタすべてに対して列挙子を提供する。

構文

HRESULT EnumFilters(
    IEnumFilters **ppEnum
);

パラメータ

ppEnum
[out] 列挙子へのポインタのアドレス。

戻り値

次のいずれかの値を返す。

S_OK | 成功。
E_OUTOFMEMORY | メモリ不足のため、列挙子を作成できない。
E_POINTER | Null ポインタ引数。

注意

このメソッドによって返されるインターフェイスは、インクリメントされている参照カウントを持っている。インターフェイスを使い終わった場合は、インターフェイス上で必ず IUnknown::Release を使用して、参照カウントをデクリメントすること。

IFilterGraph::FindFilterByName

IFilterGraph インターフェイス

特定の名前でフィルタ グラフに追加されたフィルタを検索する。

構文

HRESULT FindFilterByName(
    LPCWSTR pName,
    IBaseFilter **ppFilter
);

パラメータ

pName
[in, string] 検索する名前へのポインタ。
ppFilter
[out] 見つかったフィルタの IBaseFilter インターフェイスへのポインタのアドレス。

戻り値

次のいずれかの値を返す。

S_OK | 成功。
E_POINTER | Null ポインタ引数。
VFW_E_NOT_FOUND | 指定された名前のフィルタが見つからない。

注意

フィルタが見つからない場合、メソッドは ppFilter パラメータに NULL ポインタを返す。

IFilterGraph::Reconnect

IFilterGraph インターフェイス

このフィルタ グラフとピンの接続を切断し、同じピンに再接続する。これによって、接続の詳細 (メディア タイプやアロケータなど) をネゴシエートし直すことができる。

構文

HRESULT Reconnect(
    IPin *ppin
);

パラメータ

ppin
[in] 切断および再接続するピンへのポインタ。

戻り値

次のいずれかの値を返す。

S_OK | 成功。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
VFW_E_NOT_CONNECTED | ピンが接続されていない。
VFW_E_WRONG_STATE | フィルタが停止していない。

注意

このメソッドは、関連するロックを保持しない独立したスレッドで操作を実行する。ピンまたはフィルタからこのメソッドを呼び出して、接続のネゴシエーションをやり直すことができる。変換フィルタは、その入力と接続するときにメディア タイプを決めなければならない。その後、出力を接続する時点で、アップストリームとダウンストリームの接続を共に満足させるには、アップストリームの接続に別のメディア タイプを選択した方がよかったことがわかる場合がある。その解決策が入力ピンの再接続である。再接続は非同期に実行され、エラーを報告または訂正する手段がないため、このメソッドの呼び出し元では、ネゴシエーションのやり直しが成功することを (たとえば IPin::QueryAccept を呼び出して) 確認しなければならない。

IFilterGraph::RemoveFilter

IFilterGraph インターフェイス

グラフからフィルタを削除する。

構文

HRESULT RemoveFilter(
    IBaseFilter *pFilter
);

パラメータ

pFilter
[in] グラフから削除するフィルタへのポインタ。

戻り値

次のいずれかの値を返す。

S_OK | 成功。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。

注意

フィルタ グラフの実装は、引数 NULL で IBaseFilter::JoinFilterGraph メソッドを呼び出して、フィルタが削除されることをそのフィルタに通知する。RemoveFilter を呼び出す前にフィルタのピンを切り離す必要がないが、フィルタ グラフは停止状態にすべきだ。フィルタが停止していないと、RemoveFilter はピンとの切り離しに失敗し、グラフからのフィルタの削除に失敗するかもしれない。IGraphConfig::RemoveFilterEx を使うと、アプリケーションはピンとの切り離しなしにフィルタを自動的に削除できる、これは接続されているフィルタを新しいグラフに移動したいときパフォーマンスを改善する。

IFilterGraph::SetDefaultSyncSource

IFilterGraph インターフェイス

デフォルトの同期基準を設定する。

構文

HRESULT SetDefaultSyncSource(void);

戻り値

成功した場合は、S_OK を返す。それ以外の場合、VFW_E_NOT_STOPPED (グラフが停止状態にないことを示す) またはその他のエラー値を返す。

注意

このメソッドは、フィルタ グラフにクロックが供給されていないとき、フィルタ グラフ マネージャが同期基準として使用するクロックを探すために使用する。フィルタ グラフ マネージャは、レンダラから順に、IReferenceClock インターフェイスを提供する最初のフィルタを選択しながら、接続されているフィルタをすべて試していく。接続されているフィルタがない場合、フィルタ グラフ マネージャは、クロックをエクスポートする接続されていないフィルタを選択する。通常、このとき選択されるのはオーディオ レンダリング フィルタである。クロックをエクスポートする接続されていないフィルタがない場合、フィルタ グラフ マネージャはシステム クロックを作成する。


IFilterGraph2 インターフェイス

このインターフェイスは、フィルタ グラフを構築するメソッドを提供する IFilterGraph インターフェイスおよび IGraphBuilder インターフェイスを拡張する。

フィルタ グラフ マネージャがこのインターフェイスを実装する。アプリケーションでグラフを構築するとき、このインターフェイスを使用すると、追加のメソッドを利用できる。

IFilterGraph2 には、IFilterGraph および IGraphBuilder にない 2 つのメソッドがある。

  • AddSourceFilterForMoniker メソッドは、モニカに基づいたソース フィルタを作成し、そのソース フィルタをグラフに追加する。
  • ReconnectEx メソッドは、メディア タイプを指定できるように IFilterGraph::Reconnect メソッドを改良したものである。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IFilterGraph メソッド | 説明
AddFilter | グラフにフィルタを追加し、そのフィルタに名前を付ける。
RemoveFilter | グラフからフィルタを削除する。
EnumFilters | グラフのフィルタすべてに対して列挙子を提供する。
FindFilterByName | 特定の名前で追加されたフィルタを検索する。
ConnectDirect | 2 つのピンを直接接続する (フィルタを通さない)。
Reconnect | 既存のピン接続を切断し、同じピンに再接続する。
Disconnect | 特定のピンを切断する。
SetDefaultSyncSource | デフォルトの同期基準 (クロック) を設定する。
IGraphBuilder メソッド | 説明
Connect | 2 つのピンを接続する。直接接続できない場合は変換を介して接続する。
Render | 特定の出力ピンにフィルタ チェーンを追加してレンダリングする。
RenderFile | 指定されたファイルをレンダリングするフィルタ グラフを構築する。
AddSourceFilter | 特定のファイルのフィルタ グラフにソース フィルタを追加する。IGraphBuilder::RenderFile メソッドはこのメソッドを呼び出してソース フィルタを検索する。
SetLogFile | ログ ファイルを設定する。操作を実行しようとしたとき行われた各アクションは、このファイルに出力される。
Abort | 現在のタスクからできる限り早く戻るようにグラフ ビルダに要求する。
ShouldOperationContinue | 現在の操作が継続すべきかどうかを照会する。
IFilterGraph2 メソッド | 説明
AddSourceFilterForMoniker | モニカに基づいたソース フィルタを追加する。
ReconnectEx | 既存のピン接続を切断し、特定のメディア タイプを使用して同じピンに再接続する。

IFilterGraph2::AddSourceFilterForMoniker

IFilterGraph2 インターフェイス

モニカに基づいたソース フィルタを追加する。たとえば、ビデオ キャプチャ デバイスなどのシステム デバイス用のモニカを取得し、そのデバイス用のビデオ キャプチャ フィルタを追加することができる (システム デバイス モニカの詳細については、「ICreateDevEnum」を参照すること)。

構文

HRESULT AddSourceFilterForMoniker(
  IMoniker *pMoniker,
  IBindCtx *pCtx,
  LPCWSTR lpcwstrFilterName,
  IBaseFilter **ppFilter );

パラメータ

pMoniker
[in] IMoniker インターフェイスへのポインタ。
pCtx
[in] コンテキストをバインドする IBindCtx インターフェイスへのポインタ。
lpcwstrFilterName
[in] フィルタ名へのポインタ。
ppFilter
[out] IBaseFilter インターフェイスへのポインタのアドレス。

戻り値

メソッドが成功した場合、戻り値は次のいずれかの値になる。

S_OK | 成功。
VFW_S_DUPLICATE_NAME | 名前が重複したフィルタの追加に成功した。

メソッドが失敗した場合、戻り値は次のいずれかのエラー値になる。

E_FAIL | 失敗。
E_OUTOFMEMORY | メモリ不足。
VFW_E_DUPLICATE_NAME | 名前が重複したフィルタの追加に失敗した。
VFW_E_CANNOT_LOAD_SOURCE_FILTER | ソース フィルタをロードできない。
VFW_E_UNKNOWN_FILE_TYPE | このファイルのメディア タイプが認識されない。

注意

指定されたモニカのためのソース フィルタをグラフに追加するとき、IMoniker::BindToStorage COM メンバ関数は IStream インターフェイスを照会する。これに失敗すると、IMoniker::BindToObject が IBaseFilter インターフェイスを取得しようとする。

IFilterGraph2::ReconnectEx

IFilterGraph2 インターフェイス

既存のピン接続を切断し、特定のメディア タイプを使用して同じピンに再接続する。

構文

HRESULT ReconnectEx(

  IPin *ppin,

  const AM_MEDIA_TYPE *pmt );

パラメータ

ppin
[in] 切断および再接続するピンへのポインタ。
pmt
[in] 再接続に使用するメディア タイプへのポインタ。既存のメディア タイプを使用するには、NULL を指定する。

戻り値

S_OK | 成功。
S_FALSE | ピンが接続されていない。エラーなし。

メソッドが失敗した場合、戻り値は次のいずれかのエラー値になる。

E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
VFW_E_NOT_STOPPED | フィルタが停止していないが、実行中の再接続がサポートされていない。

注意

ReconnectEx メソッドは、IFilterGraph::Reconnect メソッド同様、ピンとそのピンが現在接続されているピンの再接続をスケジュールする。このメソッドを呼び出すときにメディア タイプを指定すると、ピン側で、元の接続に使用されていたタイプを確認したり、可能性のある新しいタイプを列挙したりする必要がないため、再接続が成功する可能性が高くなる。

参照

IFilterGraph::Reconnect


IFilterInfo インターフェイス

IFilterInfo インターフェイスは、フィルタに関する情報を管理し、フィルタと、フィルタに属するピンを表す IPinInfo インターフェイスへのアクセスを提供する。基本的には、Automation を通じてアクセス可能な IBaseFilter インターフェイスと同じものである。このインターフェイスは、Microsoft® Visual Basic® アプリケーションから IBaseFilter メソッドにアクセスするとき、IBaseFilter インターフェイス自体にある Automation のオーバーヘッドを避けるために作成された。

このインターフェイスは、フィルタ グラフ マネージャで実装され、Microsoft Visual Basic などの Automation クライアント アプリケーションから使用される。

アプリケーションでは、このインターフェイスを使用して、フィルタに関する情報を取得し、フィルタの個々のピン オブジェクト、またはフィルタに属するすべてのピン オブジェクトの集合を取得する。フィルタ グラフにフィルタを追加し、ピンどうしを接続するときには、このインターフェイスを使用できる。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IDispatch メソッド | 説明
GetTypeInfoCount | このディスプインターフェイスに利用可能なタイプ情報があるかどうか判断する。
GetTypeInfo | GetTypeInfoCount が成功した場合は、このディスプインターフェイスのタイプ情報を取得する。
GetIDsOfNames | (引数を含む) プロパティおよびメソッドのテキスト名を対応する DISPID に変換する。
Invoke | DISPID およびその他の必要なパラメータが指定された場合は、このディスプインターフェイスのメソッドを呼び出すか、またはプロパティにアクセスする。
IFilterInfo メソッド | 説明
FindPin | ピンを探し、IPinInfo インターフェイスを返す。
get_Name | フィルタ名を取得する。
get_VendorInfo | 指定されたフィルタに関するオプション情報が格納されたベンダー提供の文字列を取得する。
get_Filter | フィルタに対応する IBaseFilter インターフェイスを取得する。
get_Pins | IAMCollection インターフェイスを取得する。このインターフェイスは、このフィルタに対応する IPinInfo インターフェイスへのアクセスを提供する。
get_IsFileSource | フィルタがファイル ソース フィルタかどうかを判断する。
get_Filename | ソース フィルタに関連付けられたファイル名を取得する。
put_Filename | メディア ソースが格納されたファイルの名前を設定する。

IFilterInfo::FindPin

IFilterInfo インターフェイス

指定された識別子のピンを探し、IPinInfo インターフェイスを返す。

構文

HRESULT FindPin(
    BSTR strPinID,
    IDispatch **ppUnk
);

パラメータ

strPinID
[in] ピン識別子の文字列。
ppUnk
[out] IPinInfo インターフェイスへのポインタのアドレス。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
E_POINTER | Null ポインタ引数。
S_OK | 成功。

注意

このメソッドは IBaseFilter::FindPin メソッドに対応するものである。このメソッドは、Automation クライアントによる使用のために公開される。パフォーマンスの制限のため、C または C++ アプリケーションによる使用は想定されていない。

IFilterInfo::get_Filename

IFilterInfo インターフェイス

ソース フィルタに関連付けられたファイル名を取得する。

構文

HRESULT get_Filename(
    BSTR *pstrFilename
);

パラメータ

pstrFilename
[out, retval] ソース メディアが格納されたファイルの名前へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
E_POINTER | Null ポインタ引数。
S_OK | 成功。

注意

このメソッドは、Automation クライアントによる使用のために公開される。パフォーマンスの制限のため、C または C++ アプリケーションによる使用は想定されていない。

IFilterInfo::get_Filter

IFilterInfo インターフェイス

フィルタの IBaseFilter インターフェイスを取得する。

構文

HRESULT get_Filter(
    IUnknown **ppUnk
);

パラメータ

ppUnk
[out, retval] IFilterInfo が表すフィルタの IBaseFilter インターフェイスへのポインタのアドレス。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
E_POINTER | Null ポインタ引数。
S_OK | 成功。

注意

IFilterInfo を実装するオブジェクトは、ラッパーであり、フィルタのような COM オブジェクトではない。したがって、IBaseFilter を照会するために IFilterInfo::QueryInterface を呼び出すと失敗する。アプリケーションからフィルタ オブジェクト自体を取得するには、IFilterInfo::get_Filter メソッドを使用する。このメソッドは、Automation クライアントによる使用のために公開される。パフォーマンスの制限のため、C または C++ アプリケーションによる使用は想定されていない。

IFilterInfo::get_IsFileSource

IFilterInfo インターフェイス

フィルタがファイル ソース フィルタかどうかを判断する。

構文

HRESULT get_IsFileSource(
    LONG *pbIsSource
);

パラメータ

pbIsSource
[out, retval] フィルタがファイル ソース フィルタかどうかを示す返された値へのポインタ。ファイル ソース フィルタの場合は、OATRUE を返す。それ以外の場合は、OAFALSE を返す。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
E_POINTER | Null ポインタ引数。
S_OK | 成功。

注意

このメソッドは、Automation クライアントによる使用のために公開される。パフォーマンスの制限のため、C または C++ アプリケーションによる使用は想定されていない。

IFilterInfo::get_Name

IFilterInfo インターフェイス

フィルタ名を取得する。

構文

HRESULT get_Name(
    BSTR *strName
);

パラメータ

strName
[out, retval] フィルタ名へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
E_POINTER | Null ポインタ引数。
S_OK | 成功。

注意

このメソッドは、Automation クライアントによる使用のために公開される。パフォーマンスの制限のため、C または C++ アプリケーションによる使用は想定されていない。

IFilterInfo::get_Pins

IFilterInfo インターフェイス

IAMCollection インターフェイスを取得する。このインターフェイスは、このフィルタに属するピンに対応する IPinInfo インターフェイスへのアクセスを提供する。

構文

HRESULT get_Pins(
    IDispatch **ppUnk
);

パラメータ

ppUnk
[out, retval] IAMCollection インターフェイスへのポインタのアドレス。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
E_POINTER | Null ポインタ引数。
S_OK | 成功。

注意

このメソッドは、Automation クライアントによる使用のために公開される。パフォーマンスの制限のため、C または C++ アプリケーションでの使用は想定されていない。Visual Basic アプリケーションでは、このメソッドが返す IAMCollection オブジェクトに含まれる IPinInfo インターフェイスを、For Each ...Next という構文を使用して列挙できる。

IFilterInfo::get_VendorInfo

IFilterInfo インターフェイス

指定されたフィルタに関するオプション情報が格納されたベンダー提供の文字列を取得する。

構文

HRESULT get_VendorInfo(
    BSTR *strVendorInfo
);

パラメータ

strVendorInfo
[out, retval] ベンダー提供の情報が格納された文字列へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
E_POINTER | Null ポインタ引数。
S_OK | 成功。

注意

このメソッドは、Automation クライアントによる使用のために公開される。パフォーマンスの制限のため、C または C++ アプリケーションによる使用は想定されていない。

IFilterInfo::put_Filename

IFilterInfo インターフェイス

メディア ソースが格納されたファイルの名前を設定する。

構文

HRESULT put_Filename(
    BSTR strFilename
);

パラメータ

strFilename
[in] ソース フィルタが読み取るファイルの名前。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
E_POINTER | Null ポインタ引数。
S_OK | 成功。

注意

このメソッドは、Automation クライアントによる使用のために公開される。パフォーマンスの制限のため、C または C++ アプリケーションによる使用は想定されていない。


IFilterMapper2 インターフェイス

このインターフェイスは、フィルタを登録および登録解除し、レジストリ内のフィルタを検索する。フィルタ マッパー ヘルパー オブジェクトは、このインターフェイスを実装する。

フィルタでは、このインターフェイスを使用して、フィルタ自体を登録および登録解除する。フィルタ グラフ マネージャがフィルタ グラフを構築するとき、このインターフェイスを使用してフィルタを検索し、フィルタの特性を判断する。アプリケーションからも、このインターフェイスを使用してフィルタを検索できる。詳細については、「フィルタ マッパーの使用」および「DirectShow オブジェクトの登録方法」を参照すること。

注 : このインターフェイスは IFilterMapper インターフェイスに取って代わるものである。IFilterMapper2 では、フィルタ カテゴリ、ピン メディア、およびピン カテゴリがサポートされている。更にフィルタの登録が 1 つのメソッド呼び出しにまとめられている。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IFilterMapper2 メソッド | 説明
CreateCategory | レジストリに新しいフィルタ カテゴリを追加する。
UnregisterFilter | レジストリからフィルタ情報を削除する。
RegisterFilter | レジストリにフィルタ情報を追加する。
EnumMatchingFilters | 指定された要件を満たす登録済みフィルタを列挙する。

IFilterMapper2::CreateCategory

IFilterMapper2 インターフェイス

レジストリに新しいフィルタ カテゴリを追加する。

構文

HRESULT CreateCategory(
    REFCLSID clsidCategory,
    DWORD dwCategoryMerit,
    LPCWSTR Description
);

パラメータ

clsidCategory
[in] 新しいフィルタ カテゴリのクラス識別子 (CLSID)。
dwCategoryMerit
[in] カテゴリのメリット値。メリット値の高いカテゴリほど先に列挙される。
Description
[in] カテゴリの内容を表すわかりやすい名前。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、エラーの原因を示す HRESULT 値を返す。

注意

フィルタ グラフ マネージャは、まず MERIT_DO_NOT_USE 以下のメリット値を持つカテゴリをすべて除外することによって、グラフの構築処理をアクセラレーションする。再生の際に考慮すべきでないフィルタ カテゴリには、MERIT_DO_NOT_USE 以下のメリット値を設定すること。

検索範囲を絞るため、1 つのフィルタは 1 つ以上のカテゴリに含めることができる (たとえばビデオ コンプレッサ)。

IFilterMapper2::EnumMatchingFilters

IFilterMapper2 インターフェイス

指定された要件を満たす登録済みフィルタを列挙する。

構文

HRESULT EnumMatchingFilters(
    IEnumMoniker **ppEnum,
    DWORD dwFlags,
    BOOL bExactMatch,
    DWORD dwMerit,
    BOOL bInputNeeded,
    DWORD cInputTypes,
    const GUID *pInputTypes,
    const REGPINMEDIUM *pMedIn,
    const CLSID *pPinCategoryIn,
    BOOL bRender,
    BOOL bOutputNeeded,
    DWORD cOutputTypes,
    const GUID *pOutputTypes,
    const REGPINMEDIUM *pMedOut,
    const CLSID *pPinCategoryOut
);

パラメータ

ppEnum
[out] IEnumMoniker インターフェイスを受け取るポインタのアドレス。メソッドが成功した場合は、このインターフェイス ポインタを使用して、列挙型からフィルタ モニカを取得する。インターフェイスは使い終わったら解放すること。
dwFlags
[in] 予約済み。0 でなければならない。
bExactMatch
[in] 完全に一致するものだけを列挙するかどうかを示すブール型の値。詳細については、「注意」を参照すること。
dwMerit
[in] 最小メリット値。
bInputNeeded
[in] フィルタに入力ピンが必要かどうかを示すブール型の値。TRUE の場合、フィルタには入力ピンが少なくとも 1 つ必要である。
cInputTypes
[in] pInputTypes で指定する入力メディア タイプの数。
pInputTypes
[in] メジャー タイプおよびサブタイプを指定する GUID ペアの配列へのポインタ。これらに一致する入力ピンを列挙する。配列のサイズは 2 * cInputTypes となる。配列は NULL の場合がある。配列の個々のメンバには、あらゆるタイプに一致する GUID_NULL を指定できる。
pMedIn
[in] 入力ピンのメディアを指定する REGPINMEDIUM 構造体へのポインタ。必要がない場合は、NULL を設定する。
pPinCategoryIn
[in] 入力ピン カテゴリを指定する GUID へのポインタ。必要がない場合は、NULL を設定する。
bRender
[in] フィルタがその入力をレンダリングする必要があるかどうかを指定するブール型の値。TRUE の場合には、指定されたフィルタが入力をレンダリングする必要がある。
bOutputNeeded
[in] フィルタに出力ピンが必要かどうかを指定するブール型の値。TRUE の場合、フィルタには出力ピンが少なくとも 1 つ必要である。
cOutputTypes
[in] pOutputTypes で指定する出力メディア タイプの数。
pOutputTypes
[in] メジャー タイプおよびサブタイプを指定する GUID ペアの配列へのポインタ。これらに一致する出力ピンを列挙する。配列のサイズは 2 * cOutputTypes となる。配列は NULL の場合がある。配列の個々のメンバには、あらゆるタイプに一致する GUID_NULL を指定できる。
pMedOut
[in] 出力ピンのメディアを指定する REGPINMEDIUM 構造体へのポインタ。必要がない場合は、NULL を設定する。
pPinCategoryOut
[in] 出力ピン カテゴリを指定する GUID へのポインタ。必要がない場合は、NULL を設定する。

戻り値

HRESULT 値を返す。以下の表に示されるいずれかの値。

S_OK | 成功
E_FAIL | 失敗
E_OUTOFMEMORY | メモリ不足
E_POINTER | NULL ポインタ引数

注意

入力ピンが与えられた一連のメディア タイプと一致するフィルタを検索するには、メジャー タイプ GUID とサブタイプ GUID のペアを順に並べた配列を宣言する。pInputTypes パラメータに配列のアドレスを渡し、cInputTypes パラメータにペアの数 (つまり配列サイズの半分) を設定する。

GUID arrayInTypes[2];
arrayInTypes[0] = MEDIATYPE_Video;
arrayInTypes[1] = GUID_NULL;

DWORD cInTypes = 1;

出力ピンの場合は、pOutputTypes パラメータに同様の配列を渡し、cOutputTypes パラメータで GUID ペアの数を指定する。

bExactMatch パラメータの値が TRUE の場合、このメソッドは、メディア タイプ、ピン カテゴリ、およびピン メディアで指定された値と完全に一致するフィルタを検索する。この値が FALSE の場合、これらの項目のいずれかに値 NULL が登録されているフィルタも、一致するものと見なされる (レジストリ内の値 NULL はワイルドカードの役目を果たす)。

メディア タイプ、ピン カテゴリ、またはピン メディアに NULL を指定すると、あらゆるフィルタがそのパラメータに一致するものと見なされる。

メディア タイプが登録されていないピンは、そのメディア タイプに一致しないものと見なされる。

IFilterMapper2::RegisterFilter

IFilterMapper2 インターフェイス

レジストリにフィルタ情報を追加する。

構文

HRESULT RegisterFilter(
    REFCLSID clsidFilter,
    LPCWSTR Name,
    IMoniker **ppMoniker,
    const CLSID *pclsidCategory,
    const OLECHAR *szInstance,
    const REGFILTER2 *prf2
);

パラメータ

clsidFilter
[in] フィルタのクラス識別子 (CLSID)。
Name
[in] フィルタの内容を表すわかりやすい名前。
ppMoniker
[in, out] このフィルタのデータ出力先を決めるデバイス モニカへのポインタのアドレス。NULL の場合がある。
pclsidCategory
[in] フィルタのフィルタ カテゴリへのポインタ。NULL なら、デフォルト カテゴリは CLSID_ActiveMovieFilters である。
szInstance
[in] デバイス モニカの表示名を構築するために使用するインスタンス データ。フレンドリ名でも、フィルタの CLSID の文字列表現でもよい。NULL の場合は、フィルタの CLSID が使用される。
prf2
[in] フィルタ情報が格納された REGFILTER2 構造体へのポインタ。

戻り値

HRESULT 値を返す。以下の表に示されるいずれかの値。

S_OK | 成功。
VFW_E_BAD_KEY | レジストリ キーを取得できない。

注意

このメソッドは、レジストリ内の指定されたフィルタ カテゴリに対応するレジストリ エントリ下に、フィルタに関する情報を追加する。フィルタを作成するインプロセス サーバー (通常は DLL) を登録するのではない。サーバーを登録するには、AMovieDllRegisterServer2 関数を呼び出せばよい。

ppMoniker パラメータには、次のいずれかを使用する。

  • 既存のデバイス モニカに対する IMoniker インターフェイス ポインタのアドレス
  • NULL IMoniker インターフェイス ポインタのアドレス
  • NULL

WDM (Windows Driver Model) デバイスまたはプラグ アンド プレイ デバイス用のフィルタを登録する場合は、既存のデバイス モニカのアドレスを渡す。こうすると、このモニカを使用してフィルタが登録される。メソッドから戻るとき、*ppMoniker には NULL が設定される。

それ以外の場合は、新しいモニカが作成される。ppMoniker が NULL でない場合、*ppMoniker に新しいモニカへのポインタが設定される。そのアプリケーションでは、このモニカを使用してプロパティ バッグにプライベートな値を追加できる。インターフェイスの解放を忘れないこと。

モニカを提供または取得する必要がない場合は、ppMoniker に NULL を設定する。

IFilterMapper2::UnregisterFilter

IFilterMapper2 インターフェイス

レジストリからフィルタ情報を削除する。

構文

HRESULT UnregisterFilter(
    const CLSID *pclsidCategory,
    const OLECHAR *szInstance,
    REFCLSID Filter
);

パラメータ

pclsidCategory
[in] フィルタを削除するフィルタ カテゴリへのポインタ。
szInstance
[in] デバイス モニカの表示名の構築に使用したインスタンス データ。RegisterFilter メソッドに渡した値を使用する。
Filter
[in] フィルタのクラス識別子 (CLSID)。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、エラーの原因を示す HRESULT 値を返す。

注意

フィルタが登録されていない場合、メソッドはエラーを返す。


IFullScreenVideo インターフェイス

IFullScreenVideo インターフェイスは、フルスクリーン レンダリング フィルタに実装される。旧式のグラフィックス カードは、320 x 240 のビデオを 1024 x 768 に伸張する際に時間がかかる。システムにこのようなグラフィックス カードが搭載されている場合、フィルタ グラフ マネージャは、フルスクリーン レンダラを使用してフルスクリーン ビデオをレンダリングする。ハードウェアが持つこの制約を解消するため、フルスクリーン レンダラでは、グラフィックス ディスプレイ カードを単純に 320 x 240 モードに切り替える。比較的新しいビデオ カードの場合には、表示を高速で伸張できるので、ウィンドウ モードでもフルスクリーン モードでもビデオ レンダリング フィルタを使用できる。表示は、アプリケーションが IVideoWindow::put_FullScreenMode を呼び出すとフルスクリーン モードに切り替わり、ユーザーが Esc キーを押すと通常のウィンドウ再生に戻る。

接続されると、フルスクリーン レンダラは利用可能なディスプレイ モードをロードする。利用可能なモードの数は IFullScreenVideo::CountModes で取得できる。個々のモードに関する情報は、その後 IFullScreenVideo::GetModeInfo および IFullScreenVideo::IsModeAvailable を呼び出して取得する。アプリケーションから任意のディスプレイ モードを有効および無効にするには、IFullScreenVideo::SetEnabled メソッドを呼び出す。現在の値は IFullScreenVideo::IsModeEnabled を呼び出して照会する。アプリケーションから任意のディスプレイ モードを有効または無効にするには、(C/C++ の TRUE 値や FALSE 値ではなく) OATRUE または OAFALSE を指定して IFullScreenVideo::SetEnabled を呼び出す。

フルスクリーン レンダラは、フォアグラウンドのアクティブ ウィンドウでのみ機能する。フルスクリーン モード中に、ユーザーがほかのアプリケーションに切り替えようとすると、ビデオは非表示になる。フルスクリーン レンダラは、実際にビデオを描画しているウィンドウを最小化することにより、これを実現する (ただしウィンドウの使用はユーザーにはわからない)。ウィンドウを最大化すると、ビデオが復元される。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IFullScreenVideo メソッド | 説明
CountModes | フルスクリーン レンダラ上の利用可能なモード数を取得する。
GetModeInfo | 特定のモードに関する情報を取得する。
GetCurrentMode | 現在有効なビデオ モードを取得する。
IsModeAvailable | 特定のビデオ モードが利用可能かどうかを判断する。
IsModeEnabled | 特定のビデオ モードが有効かどうかを判断する。
SetEnabled | ビデオ モードを有効および無効にする。
GetClipFactor | クリップ損失係数の現在の設定を取得する。
SetClipFactor | 失われる最大のイメージ領域に基づいてビデオ モードを指定する。
SetMessageDrain | レンダラ宛てのウィンドウ メッセージを受け取るウィンドウを指定する。
GetMessageDrain | レンダラ宛てのウィンドウ メッセージを受け取るウィンドウを取得する。
SetMonitor | 使用中のモニタを設定する (複数モニタの実装時に使用)。
GetMonitor | 使用中のモニタを取得する。
HideOnDeactivate | ウィンドウがアクティブでないときは表示しない。
IsHideOnDeactivate | HideOnDeactivate プロパティの状態を取得する。
SetCaption | フルスクリーン ウィンドウに関連付けるキャプションを設定する。
GetCaption | フルスクリーン ウィンドウに関連付けられたキャプションを取得する。
SetDefault | フルスクリーン ビデオ レンダラのプロパティすべてにデフォルト値を設定する。

IFullScreenVideo::CountModes

IFullScreenVideo インターフェイス

フルスクリーン レンダラ上の利用可能なモード数を取得する。

構文

HRESULT CountModes(
    long *pModes
);

パラメータ

pModes
[out] 返されたモード数へのポインタ。

戻り値

HRESULT 値を返す。

注意

DirectShow のフルスクリーン レンダラでは、8 つのモード (320 × 200 × 8/16 ビット、320 × 240 × 8/16、640 × 400 × 8/16、および 640 × 480 × 8/16) がサポートされる。解像度の高いモードより、低いモードを優先的に使用すること。アプリケーションから個々のモードを有効および無効にすると、利用可能なモードを正確に指定できる。選択したモードに関する大まかな設定には、クリップ損失係数を使用する。

IFullScreenVideo::GetCaption

IFullScreenVideo インターフェイス

フルスクリーン ウィンドウに関連付けられたキャプションを取得する。

構文

HRESULT GetCaption(
    BSTR *pstrCaption
);

パラメータ

pstrCaption
[out] 取得されたキャプションへのポインタ。

戻り値

HRESULT 値を返す。

注意

Alt + Tab キーを押して別のウィンドウに切り替えると、DirectShow のフルスクリーン レンダラを非アクティブにできる。フルスクリーン レンダラは、非アクティブにするとアイコンとして表示される。タイトル文字列はこのメソッドで設定できる。アクティブでないときにレンダラが非表示になる場合、このメソッドは成功するが、ウィンドウがアイコンとして表示されないため、設定による効果はない。

IFullScreenVideo::GetClipFactor

IFullScreenVideo インターフェイス

クリップ損失係数の現在の設定を取得する。

構文

HRESULT GetClipFactor(
    long *pClipFactor
);

パラメータ

pClipFactor
[out] 失われてもよいイメージの最大量へのポインタ。

戻り値

HRESULT 値を返す。

注意

クリップ損失係数の設定の詳細については、「IFullScreenVideo::SetClipFactor」を参照すること。

IFullScreenVideo::GetCurrentMode

IFullScreenVideo インターフェイス

現在有効なビデオ モードを取得する。

構文

HRESULT GetCurrentMode(
    long *pMode
);

パラメータ

pMode
[out] 取得されたフルスクリーン ビデオ モードへのポインタ。

戻り値

HRESULT 値を返す。

注意

接続されると、フルスクリーン ビデオ レンダラはビデオ再生に使用するディスプレイ モードを選択する。選択されたモードは、このメソッドで取得できる。そのうえで IFullScreenVideo::GetModeInfo を使用すると、そのモードの詳細を取得できる。

DirectShow のフルスクリーン ビデオ レンダラに利用可能なモードの一覧については、「IFullScreenVideo::SetEnabled」を参照すること。

IFullScreenVideo::GetMessageDrain

IFullScreenVideo インターフェイス

レンダラ宛てのウィンドウ メッセージを受け取るウィンドウを取得する。

構文

HRESULT GetMessageDrain(
    HWND *hwnd
);

パラメータ

hwnd
[out] メッセージ ドレーンとして指定されているウィンドウのウィンドウ ハンドルへのポインタ。

戻り値

HRESULT 値を返す。

注意

フルスクリーン ビデオ レンダラは、受け取ったマウス メッセージおよびキーボード メッセージを、すべてメッセージ ドレーンとして指定されているウィンドウに送る。このとき、メッセージのパラメータは変換しない。渡されるメッセージの一覧は、IVideoWindow::put_MessageDrain の場合と同じである。アプリケーションからこのメソッドを使用して、フルスクリーン ビデオ用のホットキー サポートを実装できる。たとえば、Ctrl キーと P キーの組み合わせを監視し、それを合図にビデオをポーズするような処理が考えられる。

IFullScreenVideo::GetModeInfo

IFullScreenVideo インターフェイス

特定のモードに関する情報を取得する。

構文

HRESULT GetModeInfo(
    long Mode,
    long *pWidth,
    long *pHeight,
    long *pDepth
);

パラメータ

Mode
[in] 情報を取得するモード。
pWidth
[out] モードのイメージ表示の幅へのポインタ (ピクセル単位)。
pHeight
[out] モードのイメージ表示の高さへのポインタ (ピクセル単位)。
pDepth
[out] ピクセルあたりのカラー ビット数へのポインタ。

戻り値

HRESULT 値を返す。

注意

このメソッドは、そのレンダラに利用可能な所定のモードの高さ、幅、および色深度を返す。利用可能なディスプレイ モードの数は、IFullScreenVideo::CountModes で取得できる。

DirectShow のフルスクリーン ビデオ レンダラに利用可能なモードの一覧については、「IFullScreenVideo::SetEnabled」を参照すること。

IFullScreenVideo::GetMonitor

IFullScreenVideo インターフェイス

使用中のモニタ タイプを取得する。

構文

HRESULT GetMonitor(
    long *Monitor
);

パラメータ

Monitor
[out] 現在使用中のモニタへのポインタ。

戻り値

NOERROR を返す。

注意

DirectShow のフルスクリーン レンダラは、常に 0 (プライマリ モニタ) を返す。

IFullScreenVideo::HideOnDeactivate

IFullScreenVideo インターフェイス

フルスクリーン ウィンドウが非アクティブなとき、そのウィンドウ アイコンを非表示にする。

構文

HRESULT HideOnDeactivate(
    long Hide
);

パラメータ

Hide
[in] フルスクリーン ウィンドウが非アクティブなとき、そのビデオ ウィンドウ アイコンを非表示にするかどうかを指定する値。非表示にするには OATRUE、表示するには OAFALSE を設定する。

戻り値

成功した場合は、NOERROR を返す。Hide が無効な場合は、E_INVALIDARG を返す。

注意

DirectShow のフルスクリーン レンダラ用のデフォルト設定は OATRUE になっている。

フルスクリーン レンダラは、フォアグラウンドのアクティブ ウィンドウでのみ機能する。フルスクリーン モード中に、ユーザーがほかのアプリケーションに切り替えようとすると、ビデオが非表示になる。レンダラは、実際にビデオを描画しているウィンドウを最小化することにより、これを実現する (ただしウィンドウの使用はユーザーにはわからない)。ウィンドウを最大化すると、ビデオが復元される。

IFullScreenVideo::IsHideOnDeactivate

IFullScreenVideo インターフェイス

IFullScreenVideo::HideOnDeactivate プロパティの状態を取得する。

構文

HRESULT IsHideOnDeactivate(void);

戻り値

HideOnDeactivate に OATRUE が設定されている場合は、S_OK を返す。OAFALSE が設定されている場合は、S_FALSE を返す。

IFullScreenVideo::IsModeAvailable

IFullScreenVideo インターフェイス

特定のビデオ モードが利用可能かどうかを判断する。

構文

HRESULT IsModeAvailable(
    long Mode
);

パラメータ

Mode
[in] 確認するフルスクリーン モード。

戻り値

そのビデオ モードが利用可能な場合は、S_OK を返す。それ以外の場合は、S_FALSE を返す。

注意

フルスクリーン レンダラでサポートされるディスプレイ モードは、ディスプレイ カード上の実際に利用可能なモードとは異なる。レンダラが接続されるまでは、この情報を利用するために必要なリソースの割り当てが済んでいない可能性があるため、アプリケーションではレンダラが接続されているときのみにこのメソッドを呼び出すこと。モードが利用可能であっても、必ずしもそのモードがビデオ再生に使用されるとは限らない。ビデオ再生に使用されるモードには、フィルタ グラフのフィルタとの互換性も必要になる。

IFullScreenVideo::IsModeEnabled

IFullScreenVideo インターフェイス

特定のモードが有効かどうかを判断する。

構文

HRESULT IsModeEnabled(
    long Mode
);

パラメータ

Mode
[in] 確認するフルスクリーン モード。

戻り値

そのビデオ モードが有効な場合は、S_OK を返す。それ以外の場合は、S_FALSE を返す。

注意

このメソッドを使用して、レンダラでサポートされている特定のディスプレイ モードを有効および無効にすることができる。モードが利用可能であっても、必ずしもそのモードがビデオ再生に使用されるとは限らない。ビデオ再生に使用されるモードには、フィルタ グラフのフィルタとの互換性も必要になる。

DirectShow のフルスクリーン ビデオ レンダラに利用可能なモードの一覧については、「IFullScreenVideo::SetEnabled」を参照すること。

参照

IFullScreenVideo::IsModeAvailable

IFullScreenVideo::SetCaption

IFullScreenVideo インターフェイス

フルスクリーン ウィンドウに関連付けるタイトルを設定する。

構文

HRESULT SetCaption(
    BSTR strCaption
);

パラメータ

strCaption
[in] キャプションが格納された文字列。

戻り値

HRESULT 値を返す。

IFullScreenVideo::SetClipFactor

IFullScreenVideo インターフェイス

失われる最大のイメージ領域に基づいてビデオ モードを指定する。

構文

HRESULT SetClipFactor(
    long ClipFactor
);

パラメータ

ClipFactor
[in] 失われてもよいイメージの最大量。

戻り値

HRESULT 値を返す。

注意

クリップ損失係数は、フルスクリーン モードを有効にするための、アプリケーションから使いやすく汎用性が高い手段である。このメソッドは、使用するディスプレイ モードを決めるときに、失われてもよいビデオの量を定義する。たとえば、デコーダがビデオを圧縮できない場合に、MPEG ファイル (たとえば 352 × 288 ピクセル) を、ディスプレイ モード 320 × 200 で再生すると、イメージの約 25% が失われる。クリップ損失係数は、許容範囲の上限を指定する。典型的な QCIF サイズの MPEG ビデオ (352 × 288 ピクセル) を、ディスプレイ モード 320 × 200 で再生するため、デフォルト値は 25% になっている。

IFullScreenVideo::SetDefault

IFullScreenVideo インターフェイス

フルスクリーン ビデオ レンダラのデフォルト設定を設定する。

構文

HRESULT SetDefault(void);

戻り値

HRESULT 値を返す。

注意

このインターフェイスで設定するプロパティは、現在のレンダラ インスタンスにのみ適用される。ただし、このインターフェイス メソッドを呼び出して、そのプロパティを共通のデフォルト値にすることができる。

IFullScreenVideo::SetEnabled

IFullScreenVideo インターフェイス

ビデオ モードを有効および無効にする。

構文

HRESULT SetEnabled(
    long Mode,
    long bEnabled
);

パラメータ

Mode
[in] 有効または無効にするモード (下の一覧を参照)。
bEnabled
[out] 次のいずれかの値を設定する。
OATRUE | モードを有効にする。
OAFALSE | モードを無効にする。

戻り値

HRESULT 値を返す。

注意

利用可能な DirectShow のモードは以下のように定義される。ただし、モードの順序は変更されることがあるので、IFullScreenVideo::CountModes および IFullScreenVideo::GetModeInfo のインターフェイス メソッドを使用してモードを列挙すること。
モード | 幅 | 高さ | RGB 深度 (ビット単位)
0 | 320 | 200 | 16
1 | 320 | 200 | 8
2 | 320 | 240 | 16
3 | 320 | 240 | 8
4 | 640 | 400 | 16
5 | 640 | 400 | 8
6 | 640 | 480 | 16
7 | 640 | 480 | 8
8 | 800 | 600 | 16
9 | 800 | 600 | 8
10 | 1024 | 768 | 16
11 | 1024 | 768 | 8
12 | 1152 | 864 | 16
13 | 1152 | 864 | 8
14 | 1280 | 1024 | 16
15 | 1280 | 1024 | 8

IFullScreenVideo::SetMessageDrain

IFullScreenVideo インターフェイス

レンダラ宛てのウィンドウ メッセージを受け取るウィンドウを指定する。

構文

HRESULT SetMessageDrain(
    HWND hwnd
);

パラメータ

hwnd
[in] メッセージ ドレーン ウィンドウのウィンドウ ハンドル。

戻り値

HRESULT 値を返す。

注意

フルスクリーン ビデオ レンダラは、受け取ったマウス メッセージおよびキーボード メッセージを、すべてメッセージ ドレーンとして指定されているウィンドウに送る。このとき、メッセージのパラメータは変換しない。渡されるメッセージの一覧は、IVideoWindow::put_MessageDrain の場合と同じである。アプリケーションでは、このメソッドを使用して、フルスクリーン ビデオ用のホットキー サポートを実装できる。たとえば、Ctrl キーと P キーの組み合わせを監視し、それを合図にビデオをポーズするような処理が考えられる。

IFullScreenVideo::SetMonitor

IFullScreenVideo インターフェイス

使用中のモニタ タイプを設定する。

構文

HRESULT SetMonitor(
    long Monitor
);

パラメータ

Monitor
[in] 現在使用しているモニタ。

戻り値

HRESULT 値を返す。

注意

プライマリ ディスプレイ (0) 以外を設定すると、このメソッドはエラーを返す。DirectShow の将来のバージョンでは、レンダラがフルスクリーン ビデオを再生するモニタを、アプリケーションで選択できるようになる可能性がある。


IGraphBuilder インターフェイス

このインターフェイスは、アプリケーションからフィルタ グラフを構築するメソッドを提供する。フィルタ グラフ マネージャがこのインターフェイスを実装する。

IGraphBuilder は IFilterGraph インターフェイスを継承する。IFilterGraph が提供するのは、グラフへのフィルタの追加、2 つのピンの接続などの基本的な操作である。IGraphBuilder は、これらに加えて部分的な情報からグラフを構築するメソッドを提供する。たとえば、RenderFile メソッドは、指定されたファイル名に対応するファイル再生用のグラフを構築する。また、Render メソッドは、出力ピンに新しいフィルタを接続して、そのピンからのデータをレンダリングする。

これらのメソッドを使用すると、そのグラフのフィルタとピン接続を、アプリケーションから個別に指定する手間を省くことができる。アプリケーションの代わりに、フィルタ グラフ マネージャが、ユーザーのシステムに登録されているフィルタから選択したフィルタを、グラフに導入して接続する。フィルタ グラフ マネージャは、内部的にフィルタ マッパーを使用してレジストリ内のフィルタを検索する。詳細については、「IFilterMapper2」を参照すること。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IFilterGraph メソッド | 説明
AddFilter | グラフにフィルタを追加し、そのフィルタに名前を付ける。
RemoveFilter | グラフからフィルタを削除する。
EnumFilters | グラフのフィルタすべてに対して列挙子を提供する。
FindFilterByName | 特定の名前で追加されたフィルタを検索する。
ConnectDirect | 2 つのピンを直接接続する (フィルタを通さない)。
Reconnect | 既存のピン接続を切断し、同じピンに再接続する。
Disconnect | 特定のピンを切断する。
SetDefaultSyncSource | デフォルトの同期基準 (クロック) を設定する。
IGraphBuilder メソッド | 説明
Connect | 2 つのピンを接続する。直接接続できない場合は変形を介して接続する。
Render | 特定の出力ピンにフィルタ チェーンを追加してレンダリングする。
RenderFile | 指定されたファイルをレンダリングするフィルタ グラフを構築する。
AddSourceFilter | 特定のファイルに対応するフィルタ グラフにソース フィルタを追加する。
SetLogFile | ログ ファイルを設定する。このファイルには操作を実行しようとしたとき行われた各アクションが出力される。
Abort | 現在のタスクからできる限り早く戻るようにグラフ ビルダに要求する。
ShouldOperationContinue | 現在の操作が継続すべきかどうかを照会する。

IGraphBuilder::Abort

IGraphBuilder インターフェイス

現在のタスクからできる限り早く戻るようにグラフ ビルダに要求する。

現在のタスクが完了するかどうかはわからない。グラフ ビルダを現在のタスクから最も早く戻すには、グラフ ビルダにそれを完了させる事が一番だ。

構文

HRESULT Abort(void);

戻り値

S_OK を返す。

IGraphBuilder::AddSourceFilter

IGraphBuilder インターフェイス

特定のファイルに対応するフィルタ グラフにソース フィルタを追加する。IGraphBuilder::RenderFile メソッドはこのメソッドを呼び出してソース フィルタを検索する。

構文

HRESULT AddSourceFilter(
    LPCWSTR lpwstrFileName,
    LPCWSTR lpwstrFilterName,
    IBaseFilter **ppFilter
);

パラメータ

lpwstrFileName
[in] ファイルへのポインタ。
lpwstrFilterName
[in] 追加するソース フィルタに付ける名前へのポインタ。
ppFilter
[out] 追加されたフィルタの IBaseFilter インターフェイスへのポインタのアドレス。

戻り値

HRESULT を返す。設定される値は次のとおりである。

S_OK | 成功。
E_NOINTERFACE | ソース フィルタで IFileSourceFilter インターフェイスがサポートされていない。
E_OUTOFMEMORY | メモリ不足。
E_POINTER | NULL ポインタ引数。
VFW_E_CANNOT_LOAD_SOURCE_FILTER | このファイルのソース フィルタをロードできない。
VFW_E_NOT_FOUND | オブジェクトまたは名前が見つからなかった。
VFW_E_UNKNOWN_FILE_TYPE | このファイルのメディア タイプが認識されない。

注意

このメソッドを使用すると、グラフの残り部分の構築についてより詳細に制御し、正確に把握することができる。たとえば、IFilterGraph::AddFilter メソッドを使用して好みのレンダラを追加したうえで、IGraphBuilder::Connect メソッドを使用して 2 つのフィルタを接続することができる。そのソース フィルタが公開する IBaseFilter インターフェイスは、ppFilter パラメータに返され、参照は IUnknown::AddRef メソッドで既に追加されている。lpwstrFilterName パラメータを使用すると、このフィルタ グラフ内ではこの名前でフィルタを識別できる。詳細については、「FindFilterByName」を参照すること。

フィルタ グラフの残り部分を構築するために、追加するソース フィルタの出力ピンを探すことは、アプリケーション側の責任である。それには、出力ピンの IGraphBuilder::Render を呼び出して、フィルタ グラフ全体を自動的に構築するか、またはフィルタを個別に追加および接続する。フィルタを個別に追加する場合、非同期ファイル リーダー ソース フィルタおよび URL モニカ ソース フィルタではデータが解析されないため、これらのソース フィルタの出力ピンは、MPEG スプリッタ フィルタなどのパーサー フィルタにのみ接続できる。

IGraphBuilder::RenderFile メソッドは同じソース フィルタを追加する。

IGraphBuilder::Connect

IGraphBuilder インターフェイス

2 つのピンを接続する (必要に応じて中間フィルタを使用)。

構文

HRESULT Connect(
    IPin *ppinOut,
    IPin *ppinIn
);

パラメータ

ppinOut
[in] 出力ピンへのポインタ。
ppinIn
[in] 入力ピンへのポインタ。

戻り値

HRESULT を返す。設定される値は次のとおりである。

S_OK | 成功。
VFW_S_PARTIAL_RENDER | このムービーにサポートされないフォーマットのストリームが含まれている。
E_ABORT | 操作が中止された。
E_POINTER | NULL ポインタ引数。
VFW_E_CANNOT_CONNECT | 接続を確立する中間フィルタの組み合わせが見つからなかった。
VFW_E_NOT_IN_GRAPH | フィルタ グラフに存在しないオブジェクトに要求された関数を実行できない。

注意

このメソッドは、2 つのピンを直接接続するか、または必要に応じて変換フィルタを使用して間接的に接続する。失敗した場合、メソッドはファイル グラフを変更しない。フィルタ グラフ マネージャは、まずピンを直接接続しようとする。これに失敗すると、既にフィルタ グラフに属しているフィルタが提供する利用可能な変換のいずれかを使用しようとする (このとき列挙の順序は任意である)。これに失敗すると、さらに、変換を提供するフィルタをレジストリから検索しようとする。このときはメリット順に試す。

接続処理では、中間フィルタのピン名が ~ (チルダ) で始まる場合、フィルタ グラフ マネージャはそのフィルタのピンを無視する。詳細については、「PIN_INFO」を参照すること。

IGraphBuilder::Render

IGraphBuilder インターフェイス

この出力ピンからのデータをレンダリングするフィルタ グラフを構築する。

構文

HRESULT Render(
    IPin *ppinOut
);

パラメータ

ppinOut
[in] 出力ピンへのポインタ。

戻り値

HRESULT を返す。設定される値は次のとおりである。

S_OK | 成功。
VFW_S_AUDIO_NOT_RENDERED | オーディオ ストリームを再生できない。適切なレンダラが見つからなかった。
VFW_S_DUPLICATE_NAME | 名前が重複しているフィルタの追加が、変更後の名前で成功した。
VFW_S_PARTIAL_RENDER | このムービーにサポートされないフォーマットのストリームが含まれている。
VFW_S_VIDEO_NOT_RENDERED | ビデオ ストリームを再生できない。適切なレンダラが見つからなかった。
E_ABORT | 操作が中止された。
E_POINTER | NULL ポインタ引数。
VFW_E_CANNOT_CONNECT | 接続を確立する中間フィルタの組み合わせが見つからなかった。
VFW_E_CANNOT_RENDER | ストリームをレンダリングするフィルタの組み合わせが見つからなかった。
VFW_E_NO_ACCEPTABLE_TYPES | これらのピンに共通のメディア タイプがない。
VFW_E_NOT_IN_GRAPH | フィルタ グラフに存在しないオブジェクトに要求された関数を実行できない。

注意

このメソッドは、レンダリングするフィルタにこの出力ピンを、直接接続するか、または必要に応じて変換フィルタを中間フィルタとして使用して間接的に接続する。フィルタは IGraphBuilder::Connect メソッドの場合と同じ順序で試される。

接続処理では、中間フィルタのピン名が ~ (チルダ) で始まる場合、フィルタ グラフ マネージャはそのフィルタのピンを無視する。詳細については、「PIN_INFO」を参照すること。

IGraphBuilder::RenderFile

IGraphBuilder インターフェイス

指定されたファイルをレンダリングするフィルタ グラフを構築する。

構文

HRESULT RenderFile(
    LPCWSTR lpwstrFile,
    LPCWSTR lpwstrPlayList
);

パラメータ

lpwstrFile
[in] レンダリング対象データが格納されたファイルの名前、またはキャプチャ デバイスのモニカへのポインタ。
lpwstrPlayList
[in] 予約済み。NULL でなければならない。

戻り値

HRESULT を返す。設定される値は次のとおりである。

S_OK | 成功。
VFW_S_AUDIO_NOT_RENDERED | オーディオ ストリームを再生できない。適切なレンダラが見つからなかった。
VFW_S_DUPLICATE_NAME | 名前が重複しているフィルタの追加が、変更後の名前で成功した。
VFW_S_PARTIAL_RENDER | このムービーにサポートされないフォーマットのストリームが含まれている。
VFW_S_VIDEO_NOT_RENDERED | ビデオ ストリームを再生できない。適切なレンダラが見つからなかった。
E_ABORT | 操作が中止された。
E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_OUTOFMEMORY | メモリ不足。
E_POINTER | NULL ポインタ引数。
VFW_E_CANNOT_CONNECT | 接続を確立する中間フィルタの組み合わせが見つからなかった。
VFW_E_CANNOT_LOAD_SOURCE_FILTER | このファイルのソース フィルタをロードできない。
VFW_E_CANNOT_RENDER | ストリームをレンダリングするフィルタの組み合わせが見つからなかった。
VFW_E_INVALID_FILE_FORMAT | ファイル フォーマットが無効。
VFW_E_NOT_FOUND | オブジェクトまたは名前が見つからなかった。
VFW_E_NOT_IN_GRAPH | フィルタ グラフに存在しないオブジェクトに要求された関数を実行できない。
VFW_E_UNKNOWN_FILE_TYPE | このファイルのメディア タイプが認識されない。
VFW_E_UNSUPPORTED_STREAM | ファイルを再生できない。フォーマットがサポートされていない。

注意

このメソッドは、指定されたファイルを処理できるソース フィルタを追加する。次に、必要に応じて中間フィルタを追加して、そのソース フィルタの出力ピンをレンダリングする。フィルタは IGraphBuilder::Connect メソッドの場合と同じ順序で試される。

接続処理では、中間フィルタのピン名が ~ (チルダ) で始まる場合、フィルタ グラフ マネージャはそのフィルタのピンを無視する。詳細については、「PIN_INFO」を参照すること。

指定したファイルのメディア タイプと圧縮スキームを確認するために、フィルタ グラフ マネージャはファイルの最初の数バイトを読み込み、カスタム ファイル タイプの登録に記述されているファイル署名を探す。

lpwstrFile パラメータは GraphEdit .grf ファイルを指定することができる。フィルタ グラフ マネージャはグラフをそのファイルからロードする。

lpwstrFile パラメータは USB カメラや DV カムコーダのようなキャプチャ デバイスのデバイス モニカを指定することもできる。フィルタ グラフ マネージャは単純なプレビューグラフを作成する。

IGraphBuilder::SetLogFile

IGraphBuilder インターフェイス

ログ ファイルを設定する。このファイルには操作を実行しようとしたとき行われた各アクションが出力される。

構文

HRESULT SetLogFile(
    HANDLE hFile
);

パラメータ

hFile
ログ ファイルのハンドル。

戻り値

S_OK を返す。

注意

このメソッドは、デバッグに使用し、フィルタ グラフの自動構築に失敗したとき、その原因を判断することを目的としている。

hFile パラメータは、開いたファイル ハンドルでなければならない。ファイルを開き、ログ出力が終わってからファイルを閉じることは、アプリケーション側の責任である。ファイル ハンドルを閉じる前に、ファイル ハンドル NULL で SetLogFile を呼び出す。こうすると、既に閉じたファイル ハンドルをコンポーネントが使用しないように防止できる。

IGraphBuilder::ShouldOperationContinue

IGraphBuilder インターフェイス

現在の操作が継続すべきかどうかを照会する。グラフからの要求に基づいて何らかの操作を実行しているフィルタでは、このメソッドを呼び出して、その操作が継続すべきかどうかを判断できる。通常、アプリケーションからこのメソッドを呼び出すことはない。

構文

HRESULT ShouldOperationContinue(void);

戻り値

HRESULT を返す。設定される値は次のとおりである。

S_OK | 現在の操作は継続しなければならない。
S_FALSE | 現在の操作が継続してはならない。
E_UNEXPECTED | 予期せぬエラー。


IGraphConfig インターフェイス

フィルタ グラフ マネージャは、グラフを動的に構築する IGraphConfig を公開する。このインターフェイスを使用すると、アプリケーションおよびフィルタから、ストリームからのデータを失わずに、実行状態にあるフィルタ グラフを再構成できる。

グラフを動的に再構築する最も直接的な方法は、Reconnect メソッドを呼び出す方法である。グラフを動的に再構築するための細かい処理の大半は、メソッド側で実行する。独自の技法を使う必要がある場合のために、IGraphConfig は Reconfigure メソッドも提供する。このメソッドは、フィルタ グラフをロックしたうえで、アプリケーション側のコールバック関数を呼び出し、その関数がグラフを再構成する。このメソッドでは、処理の大半をアプリケーション側で実行する。詳細については、「動的グラフ作成」を参照すること。

フィルタを追加および削除する処理を最適化するため、フィルタ グラフはフィルタのキャッシュを保持する。Reconnect メソッドの呼び出しでは、グラフから削除されるフィルタをキャッシュに追加するように指定できる。また、必要になりそうなフィルタがある場合は、AddFilterToCache を呼び出してそのフィルタをキャッシュに直接追加することもできる。IGraphBuilder::Render メソッド、IGraphBuilder::RenderFile メソッド、および IGraphBuilder::Connect メソッドは、キャッシュ内のフィルタを優先的に使用する。また、Reconnect メソッドでは、再接続にキャッシュ内のフィルタだけを使用するように指定することもできる。キャッシュに保持されているフィルタは、実際にはグラフの一部ではないので注意すること。キャッシュ内のフィルタは、ピンには接続されない状態で停止している。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IGraphConfig メソッド | 説明
Reconnect | 2 つのピンの間の動的な再接続を実行する。
Reconfigure | フィルタ グラフをロックし、アプリケーションまたはフィルタのコールバック関数を呼び出して、動的な再構成を実行する。
AddFilterToCache | フィルタ キャッシュにフィルタを追加する。
RemoveFilterFromCache | フィルタ キャッシュからフィルタを削除する。
EnumCacheFilter | フィルタ キャッシュ内のフィルタを列挙する。
GetStartTime | フィルタ グラフが最後に実行状態に切り替わったときに使用された基準タイムを取得する。
PushThroughData | 指定されたピンにフィルタ グラフを通じてデータを引き渡す。
SetFilterFlags | フィルタの構成情報を設定する。
GetFilterFlags | フィルタの構成情報を取得する。
RemoveFilterEx | フィルタ グラフからフィルタを削除する。

IGraphConfig::AddFilterToCache

IGraphConfig インターフェイス

フィルタ キャッシュにフィルタを追加する。

構文

HRESULT AddFilterToCache(
    IBaseFilter *pFilter
);

パラメータ

pFilter
[in] フィルタの IBaseFilter インターフェイスへのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
S_FALSE | フィルタは既にキャッシュに入っている。
S_OK | フィルタがキャッシュに追加された。

注意

このメソッドを呼び出す前に、フィルタのピンをすべて切断しなければならない。切断しなかった場合、このメソッドは失敗する。フィルタがフィルタ グラフに含まれている場合、そのフィルタは削除される。また、フィルタが停止状態にない場合、そのフィルタは停止状態に切り替えられる。

IGraphConfig::EnumCacheFilter

IGraphConfig インターフェイス

フィルタ キャッシュ内のフィルタを列挙する。

構文

HRESULT EnumCacheFilter(
    IEnumFilters **pEnum
);

パラメータ

pEnum
[out] フィルタ列挙子の IEnumFilters インターフェイスへのポインタのアドレス。

戻り値

次のいずれかの HRESULT 値を返す。

E_OUTOFMEMORY | 必要なメモリの割り当てに失敗した。
E_POINTER | Null ポインタ引数。
S_OK | 成功。

IGraphConfig::GetFilterFlags

IGraphConfig インターフェイス

フィルタの構成情報を取得する。

構文

HRESULT GetFilterFlags(
    IBaseFilter *pFilter,
    DWORD *pdwFlags
);

パラメータ

pFilter
[in] フィルタ グラフのフィルタへのポインタ。
pdwFlags
[out] 現在の構成フラグを受け取る DWORD 型変数へのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

E_POINTER | Null ポインタ引数。
S_OK | 成功。
VFW_E_NOT_IN_GRAPH | フィルタがグラフに含まれていない。

参照

SetFilterFlags

IGraphConfig::GetStartTime

IGraphConfig インターフェイス

フィルタ グラフが最後に実行状態に切り替わったときに使用された基準タイムを取得する。

構文

HRESULT GetStartTime(
    REFERENCE_TIME *prtStart
);

パラメータ

prtStart
[out] 開始タイムを受け取る変数へのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
VFW_E_WRONG_STATE | フィルタ グラフが実行状態にない。

注意

フィルタ グラフが現在実行状態にないと、このメソッドは失敗する。

IGraphConfig::PushThroughData

IGraphConfig インターフェイス

指定されたピンにフィルタ グラフを通じてデータを引き渡す。

構文

HRESULT PushThroughData(
    IPin *pOutputPin,
    IPinConnection *pConnection,
    HANDLE hEventAbort
);

パラメータ

pOutputPin
[in] フィルタ グラフの出力ピンへのポインタ。
pConnection
[in] フィルタ グラフの入力ピンへのポインタ、または NULL。
hEventAbort
[in] イベントのハンドル。フィルタのデータ処理スレッドのいずれかからこのメソッドを呼び出す場合は、このパラメータに、そのフィルタが停止状態に切り替わったときに通知済になるイベントのハンドルを指定しなければならない。それ以外の場合、このパラメータは NULL でかまわない。詳細については、「注意」を参照すること。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、次のいずれかのエラー コードか、または一覧に示されていないその他の値を返す。

E_OUTOFMEMORY | 必要なメモリの割り当てに失敗した。
VFW_E_NOT_FOUND | 候補となる入力ピンが見つからない。
VFW_E_STATE_CHANGED | 操作中にフィルタの状態が変化した。

注意

このメソッドは、特定の出力ピンから特定の入力ピンへ、待機中のデータを引き渡す。また、入力ピンを指定しないと、フィルタ グラフから最適な入力ピンを検索できる。データの引き渡しを行っているスレッドからは、このメソッドを呼び出さないこと。

フィルタのデータ処理スレッドのいずれかからこのメソッドを呼び出すと、デッドロックに陥る危険性がある。このメソッドがフィルタ グラフをロックするため、IMediaFilter::Stop の呼び出しを受け取ったとき、フィルタが停止できない可能性がある。この状況を避けるため、このメソッドはフィルタが提供するイベント オブジェクトのハンドルを利用する。フィルタは、その Stop メソッドの呼び出しを受け取ったら、イベントを通知しなければならない。

IGraphConfig::Reconfigure

IGraphConfig インターフェイス

フィルタ グラフをロックし、アプリケーションまたはフィルタのコールバック関数を呼び出して、動的な再構成を実行する。

構文

HRESULT Reconfigure(
    IGraphConfigCallback *pCallback,
    PVOID pvContext,
    DWORD dwFlags,
    HANDLE hAbortEvent
);

パラメータ

pCallback
[in] アプリケーションまたはフィルタの IGraphConfigCallback コールバック インターフェイスへのポインタ。
pvContext
[in] コールバック ルーチンに渡す PVOID 型変数へのポインタ。
dwFlags
[in] コールバック ルーチンに渡すアプリケーションで定義したフラグ。
hAbortEvent
[in] イベントのハンドル。フィルタのデータ処理スレッドのいずれかからこのメソッドを呼び出す場合は、このパラメータに、フィルタが停止状態に切り替わったときに通知済になるイベントのハンドルを指定しなければならない。それ以外の場合、このパラメータは NULL でかまわない。詳細については、「注意」を参照すること。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、エラー コードを返す。フィルタ グラフをロックできなかった場合には、コールバック ルーチンが返す HRESULT にかかわりなく、エラー コードは VFW_E_WRONG_STATE となる。また、フィルタを実行状態に切り替えられなかったことを示すエラー コードもある。

注意

このメソッドは、アプリケーションまたはフィルタで特殊な動的グラフ構築を実装するために提供される。ただし、通常は IGraphConfig::Reconnect メソッドで目的を達成できる。また、実装の細かい処理の大半がメソッド側で実行されるという点でも、IGraphConfig::Reconnect メソッドを優先的に使用すること。

このメソッドを呼び出す前に、必要に応じてストリームをブロックし、グラフを通じてデータを引き渡すこと (詳細については、「IPinFlowControl::Block」および「IGraphConfig::PushThroughData」を参照すること)。コールバック メソッドが成功した場合、IGraphConfig::Reconfigure はフィルタをすべて実行状態に切り替えようとする (ブロックされているデータの流れを、呼び出し元で解除しなければならない)。それ以外の場合は、コールバック メソッドが返したエラー コードを返す。

フィルタのデータ処理スレッドのいずれかからこのメソッドを呼び出すと、デッドロックに陥る危険性がある。このメソッドがフィルタ グラフをロックするため、IMediaFilter::Stop の呼び出しを受け取ったとき、フィルタが停止できない可能性がある。この状況を避けるため、このメソッドはフィルタが提供するイベント オブジェクトのハンドルを利用する。フィルタは、その Stop メソッドの呼び出しを受け取ったら、イベントを通知しなければならない。

IGraphConfig::Reconnect

IGraphConfig インターフェイス

2 つのピンの間の動的な再接続を実行する。

構文

HRESULT Reconnect(
    IPin *pOutputPin,
    IPin *pInputPin,
    const AM_MEDIA_TYPE *pmtFirstConnection,
    IBaseFilter *pUsingFilter,
    HANDLE hAbortEvent,
    DWORD dwFlags
);

パラメータ

pOutputPin
[in] 出力ピンへのポインタ。NULL の場合がある。その場合、pInputPin が NULL であってはならない。
pInputPin
[in] 入力ピンへのポインタ。NULL の場合がある。その場合、pOutputPin が NULL であってはならない。
pmtFirstConnection
[in] 再接続の最初のピン接続に使用するメディア タイプを指定する AM_MEDIA_TYPE 構造体へのポインタ。このパラメータが NULL の場合、最初の接続のメディア タイプは限定されない。
pUsingFilter
[in] 再接続に使用するフィルタへのポインタ (省略可能)。フィルタは既にグラフに含まれていなければならない。NULL の場合がある。
hAbortEvent
[in] イベントのハンドル。フィルタのデータ処理スレッドのいずれかからこのメソッドを呼び出す場合は、このパラメータに、フィルタが停止状態に切り替わったときに通知済になるイベントのハンドルを指定しなければならない。それ以外の場合、このパラメータは NULL でかまわない。詳細については、「注意」を参照すること。
dwFlags
[in] 再接続の実行方法を指定する AM_GRAPH_CONFIG_RECONNECT_FLAGS 列挙型のフラグの組み合わせ。

戻り値

成功した場合は、S_OK を返す。 それ以外の場合は、次のいずれかのエラー コードか、または一覧に示されていないその他の値を返す。

E_INVALIDARG | 無効な引数。たとえば、pInputPin と pOutputPin の両方に NULL が指定された場合など。
E_NOINTERFACE | 入力ピンで IPinConnection がサポートされていない。
VFW_E_CANNOT_CONNECT | フィルタを接続できない。
VFW_E_STATE_CHANGED | フィルタの状態が変化した。操作を完了できない。

注意

出力ピンを 1 つだけ指定すると、メソッドはもう一方のピンを検索する。ただしデフォルトでは、IFilterGraph::AddFilter メソッドでグラフに追加したフィルタが見つかると検索が失敗する。この動作をオーバーライドするには、IGraphConfig::SetFilterFlags を呼び出してフィルタの AM_FILTER_FLAGS_REMOVABLE フラグを設定する。

再接続は以下のステップで実行され、その大半はこのメソッド内で処理される。

  1. まず、メソッドを呼び出す前に、再構成しようとしているパスに沿ったデータの流れを確実にブロックする。呼び出し元がアプリケーションの場合、これには IPinFlowControl::Block メソッドを呼び出さなければならない。アプリケーションではなくフィルタから呼び出す場合、データの流れをフィルタ側で内部的に制御できる可能性がある。
  2. 指定する出力ピンと入力ピンによって、再接続の始点と終点が定義される。入力ピンは IPinConnection インターフェイスをサポートしなければならない。これらのピンのいずれかを指定しない (NULL パラメータを渡す) と、メソッドは、フィルタ グラフから再接続の候補となるピンを検索する (入力ピンは出力ピンからダウンストリームへ、出力ピンは入力ピンからアップストリームへ検索する)。
  3. メソッドが、フィルタ グラフを通じて待機中のデータを引き渡す (内部的に PushThroughData を呼び出す)。
  4. グラフに挿入するフィルタを指定した場合、そのフィルタの入力ピンに最初の出力ピンが接続され、そのフィルタの出力ピンが最後の入力ピンに接続される。フィルタを指定しなかった場合には、出力ピンが入力ピンに直接接続される。いずれの場合も、接続の確立に必要な変換フィルタがあれば挿入される。ただし、適切なフラグを設定すると、この動作をオーバーライドできる (詳細については、dwFlags パラメータの説明を参照すること)。
  5. 最後に、新しいフィルタが実行状態に切り替えられる。データの流れを再開することは、呼び出し元の責任である。呼び出し元がアプリケーションの場合、これには、フラグをセットせずに IPinFlowControl::Block を呼び出せばよい。

フィルタのデータ処理スレッドのいずれかからこのメソッドを呼び出すと、デッドロックに陥る危険性がある。このメソッドがフィルタ グラフをロックするため、IMediaFilter::Stop の呼び出しを受け取ったとき、フィルタが停止できない可能性がある。この状況を避けるため、このメソッドはフィルタが提供するイベント オブジェクトのハンドルを利用する。フィルタは、その Stop メソッドの呼び出しを受け取ったら、イベントを通知しなければならない。

IGraphConfig::RemoveFilterEx

IGraphConfig インターフェイス

フィルタ グラフからフィルタを削除する。

構文

HRESULT RemoveFilterEx(
    IBaseFilter *pFilter,
    DWORD Flags
);

パラメータ

pFilter
[in] グラフから削除するフィルタへのポインタ。
Flags
[in] REM_FILTER_FLAGS 列挙型のフラグの組み合わせ。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、失敗の原因を示す HRESULT 値を返す。

注意

このメソッドは、IFilterGraph::RemoveFilter メソッドをメソッドの動作を指定するフラグを受け付けるように拡張したものである。このフラグを使うと、アプリケーションは自動的にピンから切り離すことなくフィルタを削除できる、それは接続されているフィルタ グループを新しいグラフに移動するときパフォーマンスを改善する。

デフォルトでは、削除の前にフィルタが切断される。フィルタを切断しないためには、REMFILTERF_LEAVECONNECTED フラグを使用する。

IGraphConfig::RemoveFilterFromCache

IGraphConfig インターフェイス

フィルタ キャッシュからフィルタを削除する。

構文

HRESULT RemoveFilterFromCache(
    IBaseFilter *pFilter
);

パラメータ

pFilter
[in] キャッシュから削除するフィルタへのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

E_POINTER | Null ポインタ引数。
S_FALSE | フィルタがキャッシュに入っていない。
S_OK | キャッシュからのフィルタの削除に成功した。

IGraphConfig::SetFilterFlags

IGraphConfig インターフェイス

フィルタの構成情報を設定する。

構文

HRESULT SetFilterFlags(
    IBaseFilter *pFilter,
    DWORD dwFlags
);

パラメータ

pFilter
[in] フィルタ グラフのフィルタへのポインタ。
dwFlags
[in] 新しい構成フラグを指定する値。可能な値は次のいずれかである。
ゼロ (0) | フラグをセットしない。
AM_FILTER_FLAGS_REMOVABLE | 動的な再接続の間にフィルタを削除できる。詳細については、「注意」を参照すること。

戻り値

次のいずれかの HRESULT 値を返す。

E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
S_OK | 成功。
VFW_E_NOT_IN_GRAPH | フィルタがグラフに含まれていない。

注意

AM_FILTER_FLAGS_REMOVABLE フラグは、IGraphConfig::Reconnect メソッドの動作を変更する。Reconnect メソッドは、2 つのピンの間の動的な再接続を実行する。一方のピンだけを指定し、もう片方のピンを指定しなかった場合、Reconnect は指定されたピンからアップストリームまたはダウンストリームに向かって適切なピンを検索する。ただしデフォルトでは、IFilterGraph::AddFilter メソッドでグラフに追加したフィルタが見つかると検索が失敗する。この動作をオーバーライドするには、SetFilterFlags を呼び出してフィルタの AM_FILTER_FLAGS_REMOVABLE フラグを設定する。


IGraphConfigCallback インターフェイス

IGraphConfigCallback インターフェイスには、IGraphConfig::Reconfigure に渡されたコールバック メソッドが格納される。このインターフェイスは、呼び出し元 (アプリケーションまたはフィルタ) が実装する。詳細については、「IGraphConfig」を参照すること。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IGraphConfigCallback メソッド | 説明
Reconfigure | IGraphConfig::Reconfigure に渡すコールバック メソッド。

IGraphConfigCallback::Reconfigure

IGraphConfigCallback インターフェイス

IGraphConfig::Reconfigure に渡すコールバック メソッド。

構文

HRESULT Reconfigure(
    PVOID pvContext,
    DWORD dwFlags
);

パラメータ

pvContext
IGraphConfig::Reconfigure メソッドの pvContext パラメータに渡す値。
dwFlags
IGraphConfig::Reconfigure メソッドの dwFlags パラメータに渡す値。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、エラーの原因を示す HRESULT 値を返す。

注意

開発するアプリケーションまたはフィルタから IGraphConfig::Reconfigure を呼び出す場合は、このメソッドを実装してコールバックとして渡す必要がある。IGraphConfig::Reconfigure メソッドは、フィルタ グラフのロック後に、指定された Reconfigure メソッドを呼び出す。グラフを動的に構築するためのその他の細かい処理はすべて、指定されたメソッド側で行う。

このメソッドが成功すると、IGraphConfig::Reconfigure はグラフのフィルタをすべて実行状態に戻そうとする。メソッドが失敗すると、IGraphConfig::Reconfigure はこのメソッドが返すエラー コードをそのまま返す。

このメソッドでは、特殊なグラフ構築が行える。動的なグラフ構築のためのより直接的な手法については、「IGraphConfig::Reconnect」を参照すること。


IGraphVersion インターフェイス

IGraphVersion インターフェイスは、フィルタ グラフ マネージャに実装され、PID およびアプリケーションからグラフの変更時期を知る手段を提供する。グラフが変わったとき、アプリケーションまたは PID が、特定のフィルタまたはピンのインターフェイスを持っている場合、そのアプリケーションまたは PID は、グラフに照会し直して、そのポインタがまだ有効かどうか、または使用すべき新しいポインタがあるかどうかを、確認しなければならない。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IGraphVersion メソッド | 説明
QueryVersion | 現在のグラフのバージョン番号を取得する。

IGraphVersion::QueryVersion

IGraphVersion インターフェイス

現在のグラフのバージョン番号を取得する。

構文

HRESULT QueryVersion(
    LONG *pVersion
    );

パラメータ

pVersion
現在のグラフのバージョンへのポインタ。

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
S_OK または NOERROR | 成功。

注意

バージョン番号は、グラフのフィルタ構成が変わるか、またはそれらフィルタの接続が変わるたびにインクリメントされる。最後に列挙してからバージョン番号が変わった場合には、グラフを列挙し直す必要がある。


IIPDVDec インターフェイス

このインターフェイスは、DV ビデオ デコーダ フィルタのプロパティを設定および取得するメソッドを提供する。

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IIPDVDec メソッド | 説明
get_IPDisplay | デコード解像度を取得する。
put_IPDisplay | デコード解像度を設定する。

IIPDVDec::get_IPDisplay

IIPDVDec インターフェイス

デコード解像度を取得する。

構文

HRESULT get_IPDisplay(
    int *displayPix
);

パラメータ

displayPix
デコード解像度を示す DVDECODERRESOLUTION 列挙型のメンバを受け取る変数へのポインタ。

戻り値

S_OK を返す。

IIPDVDec::put_IPDisplay

IIPDVDec インターフェイス

デコード解像度を設定する。

構文

HRESULT put_IPDisplay(
    int displayPix
);

パラメータ

displayPix
[in] デコード解像度を指定する DVDECODERRESOLUTION 列挙型のメンバ。この値の意味は現在のフォーマット (NTSC または PAL) によって異なる。適用されるフォーマットは実行時にフィルタがメディア タイプに基づいて判断する。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_FAIL またはその他のエラー コードを返す。

注意

既にそのフィルタがメディアのデータをストリームしている場合、このメソッドは失敗する。


IKsPropertySet インターフェイス

IKsPropertySet インターフェイスの本来の目的は、KSProxy を使用して、ユーザーモードの COM メソッド呼び出しを、WDM ストリーミング クラス ドライバが使用するカーネルモードの "プロパティ セット" に変換することによって、WDM ドライバ上のデバイス プロパティを効率よく設定および取得することである。現在では、このインターフェイスは、コンポーネント間で情報を正確にやり取りする目的にも使用する。場合によっては、コンポーネントでこのインターフェイスを実装する必要がある。たとえば、Microsoft® DVD ナビゲータに使用するソフトウェア MPEG-2 デコーダを作成する場合には、このインターフェイスを実装し、さらに、IKsPropertySet::Get メソッドおよび IKsPropertySet::Set メソッドを使用して、ナビゲータがデコーダに送る DVD 関連のプロパティ セットをサポートしなければならない。そのピンのプロパティをほかのピンまたはフィルタから設定または取得できるように、ピンでこのインターフェイスをサポートしてもよい。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを返す。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IKsPropertySet メソッド | 説明
Set | プロパティ セット GUID およびプロパティ ID で識別されるプロパティを設定する。
Get | プロパティ セット GUID およびプロパティ ID で識別されるプロパティを取得する。
QuerySupported | 特定のプロパティ セットがオブジェクトでサポートされているかどうかを判断する。

IKsPropertySet::Get

IKsPropertySet インターフェイス

プロパティ セット GUID およびプロパティ ID で識別されるプロパティを取得する。

構文

HRESULT Get(
  REFGUID guidPropSet,
  DWORD dwPropID,
  LPVOID pInstanceData,
  DWORD cbInstanceData,
  LPVOID pPropData,
  DWORD cbPropData,
  DWORD *pcbReturned
  );

パラメータ

guidPropSet
[in] プロパティ セット GUID。
dwPropID
[in] プロパティ セット内でのプロパティの識別子。
pInstanceData
[out, size_is(cbInstanceData)] プロパティに対応するインスタンス データへのポインタ。
cbInstanceData
[in] pInstanceData が指すバッファに含まれるデータのバイト数。
pPropData
[out, size_is(cbPropData)] プロパティの値が入った取得されたバッファへのポインタ。
cbPropData
[in] pPropData が指すバッファに含まれるデータのバイト数。
pcbReturned
[out] pPropData が指すバッファに返されたデータのバイト数へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

現在の Microsoft® DirectShow® の実装では、プロパティ セットがサポートされていない場合、E_PROP_SET_UNSUPPORTED を返す。また、指定されたプロパティ セットでそのプロパティ ID がサポートされていない場合には、E_PROP_ID_UNSUPPORTED を返す。

注意

プロパティを取得するには、このメソッドがデータを設定するバッファを割り当てること。必要なバッファ サイズを判断するには、pPropData に NULL、cbPropData に 0 を指定する。必要なバッファ サイズが pcbReturned に返される。

IKsPropertySet::QuerySupported

IKsPropertySet インターフェイス

特定のプロパティ セットがオブジェクトでサポートされているかどうかを判断する。

構文

HRESULT QuerySupported(
  REFGUID guidPropSet,
  DWORD dwPropID,
  DWORD *pTypeSupport
  );

パラメータ

guidPropSet
[in] プロパティ セット GUID。
dwPropID
[in] プロパティ セット内でのプロパティの識別子。
pTypeSupport
[out] ドライバのサポートを示すフラグを示す値へのポインタ。サポートされるフラグは次のとおりである。
KSPROPERTY_SUPPORT_GET | IKsPropertySet::Get メソッドを呼び出してプロパティを取得できる。
KSPROPERTY_SUPPORT_SET | IKsPropertySet::Set メソッドを呼び出してプロパティを変更できる。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

現在の DirectShow の実装が返す戻り値は次のとおりである。
E_NOTIMPL | プロパティ セットがサポートされていない。
E_PROP_ID_UNSUPPORTED | 指定されたプロパティ セットでそのプロパティ ID がサポートされていない。
E_PROP_SET_UNSUPPORTED | プロパティ セットがサポートされていない。
S_OK | 指定されたプロパティ セットとプロパティ ID の組み合わせがサポートされている。

IKsPropertySet::Set

IKsPropertySet インターフェイス

プロパティ セット GUID およびプロパティ ID で識別されるプロパティを設定する。

構文

HRESULT Set(
  REFGUID guidPropSet,
  DWORD dwPropID,
  LPVOID pInstanceData,
  DWORD cbInstanceData,
  LPVOID pPropData,
  DWORD cbPropData
  );

パラメータ

guidPropSet
[in] プロパティ セット GUID。
dwPropID
[in] プロパティ セット内でのプロパティの識別子。
pInstanceData
[out, size_is(cbInstanceData)] プロパティに対応するインスタンス データへのポインタ。
cbInstanceData
[in] pInstanceData が指すバッファに含まれるデータのバイト数。
pPropData
[out, size_is(cbPropData)] プロパティの値が入った取得されたバッファへのポインタ。
cbPropData
[in] pPropData が指すバッファに含まれるデータのバイト数。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

現在の DirectShow の実装は、プロパティ セットがサポートされていない場合、E_PROP_SET_UNSUPPORTED を返し、指定されたプロパティ セットでそのプロパティ ID がサポートされていない場合、E_PROP_ID_UNSUPPORTED を返す。


IMediaControl インターフェイス

このインターフェイスは、フィルタ グラフを通るデータの流れを制御するメソッドを提供する。ここには、グラフを実行、ポーズ、および停止するメソッドが含まれる。フィルタ グラフ マネージャがこのインターフェイスを実装する。フィルタグラフの状態についての詳細については、「フィルタ グラフのデータ フロー」を参照すること。

IMediaControl はグラフを構築する Automation 互換のメソッドも提供する。Microsoft® Visual Basic® アプリケーションでは、これらのメソッドを使用して、フィルタ グラフを構築したり、グラフに関する情報を取得したりすることができる。C/C++ アプリケーションでは、このインターフェイスではなく、効率のよい IGraphBuilder および IFilterGraph2 のメソッドを使用すること。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IDispatch メソッド | 説明
GetTypeInfoCount | このディスプインターフェイスにタイプ情報が利用可能かどうかを判断する。
GetTypeInfo | GetTypeInfoCount が成功した場合に、このディスプインターフェイスのタイプ情報を取得する。
GetIDsOfNames | (引数を含む) プロパティおよびメソッドのテキスト名を対応するディスパッチ識別子 (DISPID) に変換する。
Invoke | DISPID およびその他の必要なパラメータが指定された場合は、このディスプインターフェイスのメソッドを呼び出すか、またはプロパティにアクセスする。
IMediaControl メソッド | 説明
Run | フィルタ グラフのすべてのフィルタを実行する。
Pause | フィルタ グラフのフィルタをすべてポーズする。
Stop | フィルタ グラフのすべてのフィルタを停止する。
StopWhenReady | フィルタがキューに入れられるようにフィルタグラフをポーズにし、次にフィルタグラフを停止する。
GetState | フィルタ グラフの状態を取得する。
RenderFile | Visual Basic アプリケーションで用いられ、指定したファイルをレンダリングするフィルタグラフを構築する。
AddSourceFilter | Visual Basic で用いられ、与えられたファイル名を読み込むことのできるソースフィルタをグラフに追加する。
get_FilterCollection | Visual Basic アプリケーションで用いられ、グラフのフィルタを表す IFilterInfo インターフェイスの集合を取得し、指定したファイルをレンダリングするフィルタ グラフを構築する。
get_RegFilterCollection | Visual Basic アプリケーションで用いられ、ローカル システムで利用可能な登録されたフィルタを表す IRegFilterInfo インターフェイスの集合を取得する。

IMediaControl::AddSourceFilter

IMediaControl インターフェイス

Visual Basic で用いられ、与えられたファイル名を読み込むことのできるソースフィルタをグラフに追加する。

構文

HRESULT AddSourceFilter(
    BSTR strFilename,
    IDispatch **ppUnk
);

パラメータ

strFilename
[in] ソース ビデオが格納されたファイルの名前。
ppUnk
[out] フィルタの IFilterInfo インターフェイスを受け取るポインタのアドレス。

戻り値

HRESULT 値を返す。以下のいずれかの値。

S_OK | 成功。
E_OUTOFMEMORY | メモリ不足。
VFW_E_CANNOT_LOAD_SOURCE_FILTER | このファイルのソース フィルタをロードできない。
VFW_E_NOT_FOUND | オブジェクトまたは名前が見つからなかった。
VFW_E_UNKNOWN_FILE_TYPE | このファイルのメディア タイプが認識されない。

注意

このメソッドは IDispatch インターフェイス ポインタを返す。したがって、主に Automation クライアントから使用する。C/C++ アプリケーションでこの操作を最も効率よく実行するには、IGraphBuilder::AddSourceFilter メソッドを呼び出すこと。

IMediaControl::get_FilterCollection

IMediaControl インターフェイス

Visual Basic アプリケーションで用いられ、グラフのフィルタを表す IFilterInfo インターフェイスの集合を取得し、指定したファイルをレンダリングするフィルタ グラフを構築する。

構文

HRESULT get_FilterCollection(
    IDispatch **ppUnk
);

パラメータ

ppUnk
[out, retval] IFilterInfo オブジェクトの集合の IAMCollection インターフェイスを受け取るポインタのアドレス。

戻り値

HRESULT 値を返す。以下のいずれかの値。
S_OK | 成功。
E_OUTOFMEMORY | メモリ不足。

注意

このメソッドは IDispatch インターフェイス ポインタを返す。したがって、主に Automation クライアントから使用する。C/C++ アプリケーションでこの操作を最も効率よく実行するには、IFilterGraph::EnumFilters メソッドを呼び出すこと。

IMediaControl::get_RegFilterCollection

IMediaControl インターフェイス

Visual Basic アプリケーションで用いられ、ローカル システムで利用可能な登録されたフィルタを表す IRegFilterInfo インターフェイスの集合を取得する。

構文

HRESULT get_RegFilterCollection(
    IDispatch **ppUnk
);

パラメータ

ppUnk
[out, retval] IAMCollection オブジェクトの IDispatch インターフェイスを受け取るポインタのアドレス。

戻り値

HRESULT 値を返す。以下のいずれかの値。

S_OK | 成功。
E_OUTOFMEMORY | メモリ不足。

注意

このメソッドは IDispatch インターフェイス ポインタを返す。したがって、主に Automation クライアントから使用する。C/C++ アプリケーションでこの操作を最も効率よく実行するには、IFilterMapper::EnumMatchingFilters メソッドを呼び出すこと。

IMediaControl::GetState

IMediaControl インターフェイス

フィルタ グラフの状態 (ポーズ、実行、または停止) を取得する。

状態は必ずしも同期して移行するとは限らない。したがって、このメソッドを呼び出したとき、フィルタ グラフは新しい状態に移行している途中かもしれない。その場合、移行が完了するか、または指定されたタイムアウト時間が過ぎるまで、メソッドはブロックする。

構文

HRESULT GetState(
    LONG msTimeout,
    OAFilterState *pfs
);

パラメータ

msTimeout
[in] タイムアウトの時間幅 (ミリ秒単位)、またはタイムアウト時間が無制限であることを指定する INFINITE。
pfs
[out] 返された (フィルタ グラフの) 状態を受け取るポインタ。この値は FILTER_STATE 列挙型のメンバである。

戻り値

HRESULT 値を返す。以下のいずれかの値。

S_OK | 成功。
VFW_S_STATE_INTERMEDIATE | フィルタ グラフは取得された状態に移行中。
VFW_S_CANT_CUE | フィルタ グラフはポーズしているが、データをキューに入れることができない。
E_FAIL | 失敗。

注意

アプリケーションはこのメソッドを使って IMediaControl::Run 呼び出し後再生が開始されたかどうかを確かめることができる。一般的に、アプリケーションはフィルタ グラフをどの状態にしたかをトラックするメカニズムを自分自身で持つべきだ。通常アプリケーションは現在の状態を使って、どのユーザー インターフェイス コントロールが使用可能にするかを決定する。たとえば、グラフが実行状態にあるなら、アプリケーションは「再生」ボタンを使用不可にし、「停止」と「ポーズ」ボタンを使用可能にする。

フィルタ グラフが新しい状態に移行中である場合は、以前の状態ではなく新しい状態が返される。

メソッドがブロックされているときに、別のスレッドから呼び出して状態を変更すると、このメソッドはエラーを返す。

GetState での待機中にスレッドはメッセージを処理できないため、タイムアウト値への INFINITE の指定は避けること。Windows メッセージを処理するスレッドから GetState を呼び出す場合は、ユーザー入力への応答に支障がないように、できるだけ短い待機時間を指定すること。特に、ネットワークやインターネット経由でソースがストリームされる場合は、状態の移行が完了するまでに非常に時間がかかるため、注意が必要である。

フィルタ グラフの状態の詳細については、「フィルタ グラフのデータ フロー」を参照すること。

IMediaControl::Pause

IMediaControl インターフェイス

フィルタ グラフのフィルタをすべてポーズする。

フィルタ グラフをポーズすると、次にグラフを実行するとき即座にレンダリングするため、グラフがキューに入る。グラフがポーズしているとき、データは処理されるが、レンダリングは行われない。データは、バッファに余裕がある限り、グラフに引き渡され、変換フィルタで処理されるが、そのデータをレンダリング フィルタがレンダリングすることはない。ただし、ビデオ レンダラは現在のサンプルの静止したポスター フレームを表示する。

構文

HRESULT Pause(void);

戻り値

HRESULT 値を返す。以下のいずれかの値。

S_FALSE | グラフのポーズに成功したが、状態の移行が完了していないフィルタがある。
S_OK | グラフのフィルタがすべてポーズ状態への移行を完了した。

注意

このメソッドが S_FALSE を返す場合は、GetState メソッドを呼び出して、状態の移行の完了を待機するか、または移行が完了しているか確認すること。

失敗した場合、メソッドは、戻る前にグラフを停止する。

IMediaControl::RenderFile

IMediaControl インターフェイス

Visual Basic アプリケーションで用いられ、指定したファイルをレンダリングするフィルタグラフを構築する。

構文

HRESULT RenderFile(
    BSTR strFilename
);

パラメータ

strFilename
レンダリングするファイルの名前。

戻り値

HRESULT 値を返す。以下のいずれかの値。

S_OK | 成功。
VFW_S_AUDIO_NOT_RENDERED | オーディオ ストリームを再生できない。適切なレンダラが見つからなかった。
VFW_S_DUPLICATE_NAME | 名前が重複しているフィルタの追加が、変更後の名前で成功した。
VFW_S_PARTIAL_RENDER | このムービーにサポートされないフォーマットのストリームが含まれている。
VFW_S_VIDEO_NOT_RENDERED | ビデオ ストリームを再生できない。適切なレンダラが見つからなかった。
E_ABORT | 操作が中止された。
VFW_E_CANNOT_CONNECT | 接続を確立する中間フィルタの組み合わせが見つからなかった。
VFW_E_CANNOT_LOAD_SOURCE_FILTER | このファイルのソース フィルタをロードできない。
VFW_E_CANNOT_RENDER | ストリームをレンダリングするフィルタの組み合わせが見つからなかった。
VFW_E_INVALID_FILE_FORMAT | ファイル フォーマットが無効。
VFW_E_NOT_FOUND | オブジェクトまたは名前が見つからなかった。
VFW_E_NOT_IN_GRAPH | フィルタ グラフに存在しないオブジェクトに要求された関数を実行できない。
VFW_E_UNKNOWN_FILE_TYPE | このファイルのメディア タイプが認識されない。
VFW_E_UNSUPPORTED_STREAM | ファイルを再生できない。フォーマットがサポートされていない。

注意

このメソッドでは、アプリケーションからフィルタ グラフ マネージャに、レンダリングするメディア ファイルの名前を渡すことができる。フィルタ グラフ マネージャは、そのファイルの再生に必要なフィルタのグラフを構築する。このメソッドは、IGraphBuilder::RenderFile メソッドと同等の役目をする Automation 互換のメソッドである。C/C++ アプリケーションではこのメソッドを使用すること。

IMediaControl::Run

IMediaControl インターフェイス

フィルタ グラフのすべてのフィルタを実行する。グラフが実行中、データはグラフを通って移動しレンダリングされる。

構文

HRESULT Run (void);

戻り値

HRESULT 値を返す。以下のいずれかの値。

S_FALSE | グラフは実行の準備をしているが、実行状態への移行が完了していないフィルタがある。
S_OK | グラフのフィルタがすべて実行状態への移行を完了した。

注意

IMediaControl::Pause あるいは IMediaControl::Stop が呼び出されるまで、メソッドは実行状態になる。再生がストリームの終りについたとき、フィルタはそれ以上データを流せないが、グラフは実行のままである。そのとき、アプリケーションはグラフを停止あるいはポーズにできる。エンドオブストリーム (EOS) イベントの詳細については、「IMediaEvent」と「EC_COMPLETE」を参照すること。

このメソッドはストリームの初めまでシークしない。グラフを実行し、それをポーズして、次に再度それを実行すると、ポーズ位置から再生される。エンドオブストリーム (EOS) まで着いた後で、グラフを実行させると、何も起こらない。グラフをシークするには、IMediaSeeking インターフェイスを使うこと。

このメソッドが S_FALSE を返す場合は、GetState メソッドを呼び出して、状態の移行の完了を待機することができる。メソッドが失敗した場合、グラフの一部のフィルタは実行状態に切り替えられている可能性がある。ストリームが複数あるグラフでは、ストリームがすべて正常に再生されることもある。グラフを停止するかどうかはアプリケーション側で判断しなければならない。

IMediaControl::Stop

IMediaControl インターフェイス

グラフのフィルタをすべて停止する。

構文

HRESULT Stop(void);

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、エラーの原因を示す HRESULT 値を返す。

注意

グラフが実行中なら、今メソッドはそれを停止させる前にポーズさせる。ポーズ中は、ビデオ レンダラは現在のフレームをポスター フレームとしてディスプレイにコピーできる。

このメソッドはストリームの初めまでシークしない。このメソッドを呼び出し、次に IMediaControl::Run を呼び出すと、停止位置から再生される。グラフをシークするには、IMediaSeeking インターフェイスを使うこと。

フィルタ グラフ マネージャはグラフ内のすべてのフィルタで Pause を呼び出し、次にポーズ操作の完了を待たずすべてのフィルタで IMediaFilter::Stopメソッドを呼び出す。それゆえポーズ操作の完了前に Stop メソッドの呼び出しを受け取るフィルタがあるかもしれない。カスタム レンダリング フィルタを開発しているなら、こういったケースを考慮して、実行状態にまだある間に Stop を受け取ったら、最初にフィルタをポーズするようにしなければならない。しかし、ほとんどのフィルタはこういった場合に特に何かする必要はない。

参照

StopWhenReady

IMediaControl::StopWhenReady

IMediaControl インターフェイス

フィルタがキューに入れられるようにフィルタ グラフをポーズにし、次にフィルタ グラフを停止する。

構文

HRESULT StopWhenReady(void);

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、エラーの原因を示す HRESULT 値を返す。

注意

グラフが停止しているときフィルタ グラフをシークしたいなら、このメソッドは有用である。フィルタグラフが停止している限り、現在位置の変更をしても新しいフレームでビデオ ウィンドウを再描画はしない。それゆえ、IMediaSeeking::SetPositions はビデオ ウィンドウをアップデートしない。シーク操作後ウィンドウをアップデートするには StopWhenReady を呼び出す。このメソッドはグラフをポーズ状態に移行させ、ポーズ処理が完了するのを待ち、グラフを停止状態に再度移行させる。ポーズ処理はデータをグラフのキューに入れるので、ビデオ レンダラはそれを受け取り、新しいフレームを表示する。

このメソッドは非同期である。それはここのスレッドのポーズが完了するのを待つ。呼び出されたスレッドはブロックせず、アプリケーションはユーザー入力に反応することができる。メソッドが帰ると、ポーズ操作が完了する前であっても、グラフの論理状態は停止となる。この時点で GetState メソッドを呼び出すと State_Stopped が返る。

ポーズ操作が完了する前に (ポーズ、実行、シークのような) 状態変更コマンドを受け取ると、新しいコマンドは途中の stop コマンドをキャンセルする。ポーズ操作は完了するが、グラフは停止しない。


IMediaEvent インターフェイス

このインターフェイスは、イベント通知を取得するメソッドと、フィルタ グラフのデフォルトのイベント処理をオーバーライドするメソッドを提供する。IMediaEventEx インターフェイスは、このインターフェイスを継承し、拡張する。

フィルタ グラフ マネージャがこのインターフェイスを実装する。アプリケーションでは、このインターフェイスを使用して、ストリームの終了、レンダリング エラーなど、フィルタ グラフ内で発生するイベントに応答できる。フィルタでは、IMediaEventSink インターフェイスを使用してフィルタ グラフにイベントを送る。

イベント通知の詳細については、「DirectShow でのイベント通知」を参照すること。システム定義のイベント通知の一覧については、「イベント通知コード」を参照すること。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IDispatch メソッド | 説明
GetTypeInfoCount | このディスプインターフェイスに利用可能なタイプ情報があるかどうか判断する。
GetTypeInfo | GetTypeInfoCount が成功した場合は、このディスプインターフェイスのタイプ情報を取得する。
GetIDsOfNames | (引数を含む) プロパティおよびメソッドのテキスト名を対応する DISPID に変換する。
Invoke | DISPID およびその他の必要なパラメータが指定された場合は、このディスプインターフェイスのメソッドを呼び出すか、またはプロパティにアクセスする。
IMediaEvent メソッド | 説明
GetEventHandle | キューにイベント通知がある間通知済状態の、手動リセット イベントへのハンドルを受け取る。
GetEvent | 次の通知イベントをイベント キューから取得する。
WaitForCompletion | フィルタ グラフがすべての有効なデータをレンダリングするのを待つ。
CancelDefaultHandling | 指定したイベントに対するフィルタ グラフ マネージャのデフォルト処理をキャンセルする。
RestoreDefaultHandling | 指定したイベントに対するフィルタ グラフ マネージャのデフォルト処理をリストアする。
FreeEventParams | イベントのパラメータに関連付けられたリソースを解放する。

IMediaEvent::CancelDefaultHandling

IMediaEvent インターフェイス

指定したイベントに対するフィルタ グラフ マネージャのデフォルト処理をキャンセルする。

構文

HRESULT CancelDefaultHandling(
    long lEvCode
);

パラメータ

lEvCode
デフォルト処理をキャンセルするイベント コード。

戻り値

HRESULT 値を返す。以下の表に示されるいずれかの値。

S_OK | 成功。
E_INVALIDARG | このイベントにはデフォルト処理はない。

注意

イベントのデフォルト処理をリストアするには、イベントコードを渡して RestoreDefaultHandling メソッドを呼び出すこと。

IMediaEvent::FreeEventParams

IMediaEvent インターフェイス

イベントのパラメータに関連付けられたリソースを解放する。

構文

HRESULT FreeEventParams(
    long lEventCode,
    long lParam1,
    long lParam2
);

パラメータ

lEventCode
[in] イベント コード。
lParam1
[in] 第 1 イベント パラメータ。
lParam2
[in] 第 2 イベント パラメータ。

戻り値

S_OK を返す。

注意

IMediaEvent::GetEvent メソッドを呼び出してイベント通知を受け取った後で、FreeEventParams を呼び出さなければならない。このメソッドはイベントパラメータに割り当てられてすべてのリソースを解放する。次の例に示すように GetEvent に用いた同じ変数を渡すこと :

hr = pEvent->GetEvent(&evCode, &param1, &param2, 0);
// Handle the event (not shown).
hr = pEvent->FreeEventParams(evCode, param1, param2);

IMediaEvent::GetEvent

IMediaEvent インターフェイス

次の通知イベントをイベント キューから取得する。

構文

HRESULT GetEvent(
    long *lEventCode,
    long *lParam1,
    long *lParam2,
    long msTimeout
);

パラメータ

IEventCode
[out] イベント コードを受け取る変数へのポインタ。
lParam1
[out] 第 1 イベント パラメータを受け取る変数へのポインタ。
lParam2
[out] 第 2 イベント パラメータを受け取る変数へのポインタ。
msTimeout
[in] タイムアウト時間、ミリ秒単位。イベントがある間は INFINITE を使いブロックする。

戻り値

HRESULT 値を返す。以下のいずれかの値。

S_OK | 成功。
E_ABORT | タイムアウトによる時間切れ。

注意

アプリケーションはタイムアウト時間 INFINITE を使うのは避けるべきだ、なぜならスレッドは GetEvent を待つ間メッセージを処理することができないからだ。Windows メss-時を処理する同じスレッドから GetEvent を呼び出すなら、ユーザー入力へのレスポンスを維持するために待ち時間を少なくすること。インターネットのようなソースからデータをストリーミングするときにはこれは最も重要である、なぜなら状態の移行は完了するまで非常に時間がかかるからだ。

GetEvent を呼び出した後で、FreeEventParams メソッドを呼び出してイベントパラメータに確保したすべてのリソースを解放すること。

通知コードおよびパラメータ値の一覧については、「イベント通知コード」を参照すること。

IMediaEvent::GetEventHandle

IMediaEvent インターフェイス

キューにイベント通知がある間通知済状態の、手動リセット イベントへのハンドルを受け取る。

構文

HRESULT GetEventHandle(
    OAEVENT *hEvent
);

パラメータ

hEvent
[out] イベント ハンドルを受け取る変数へのポインタ。

戻り値

S_OK を返す。

注意

フィルタ グラフ マネージャはイベント キューの状態を反映した手動リセット イベントを保持する。キューにイベント通知が入っていると、手動リセット イベントが通知済になる。キューがカラなら、IMediaEvent::GetEvent メソッドはそのイベントをリセットする。

アプリケーションはこのイベントを使用してキューの状態を確認することができる。最初に GetEventHandle を呼び出してイベントのハンドルを取得する。WaitForSingleObject のような Microsoft® Windows® 関数を使って、イベントが通知済になるまで待つ。イベントが通知済になると、GetEvent メソッドを呼び出して次のイベント通知をキューから受け取る。フィルタ グラフ マネージャはキューが空になるまでイベント通知を保持し、その後イベントをリセットする。

注 Automation との互換性のため、このメソッドは OAEVENT 変数へのポインタを持つ。C++ では、次のように HANDLE タイプの変数を宣言しそれを OAEVENT タイプにキャストする :
HANDLE hEvent;
GetEventHandle( (OAEVENT*) &hEvent );

アプリケーションがイベントキューをモニタするもう 1 つの方法は IMediaEventEx::SetNotifyWindow メソッドを呼び出すことである。

IMediaEvent::RestoreDefaultHandling

IMediaEvent インターフェイス

指定したイベントに対するフィルタ グラフ マネージャのデフォルト処理をリストアする。

構文

HRESULT RestoreDefaultHandling(
    long lEvCode
);

パラメータ

lEvCode
[in] デフォルト処理に戻すイベント コード。

戻り値

HRESULT 値を返す。以下の表に示されるいずれかの値。

S_OK | 成功。
E_INVALIDARG | このイベントにはデフォルト処理はない。

注意

デフォルトでは、グラフ マネージャは (EC_REPAINT のような) いくつかのイベントをアプリケーションに渡さずに処理する。CancelDefaultHandling メソッドを呼び出してイベントのデフォルト処理をオーバーライドすると、同じイベント コードで RestoreDefaultHandling をコーすることでデフォルトの処理をリストアすることができる。

IMediaEvent::WaitForCompletion

IMediaEvent インターフェイス

フィルタ グラフがすべての有効なデータをレンダリングするのを待つ。

構文

HRESULT WaitForCompletion(
    long msTimeout,
    long *pEvCode
);

パラメータ

msTimeout
[in] タイムアウト時間、ミリ秒単位。即座に戻るには 0 を渡す。無期限にブロックするには INFINITE を渡す。
pEvCode
[out] イベント コードを受け取る変数へのポインタ。詳細については、「注意」を参照すること。

戻り値

HRESULT 値を返す。以下のいずれかの値。

S_OK | 成功。
E_ABORT | タイムアウトによる時間切れ。
VFW_E_WRONG_STATE | フィルタ グラフが実行中ではない。

注意

このメソッドはタイムアウトが時間切れになるまでブロックする、あるいは以下のイベントの 1 つを起こす :

  • EC_COMPLETE
  • EC_ERRORABORT
  • EC_USERABORT

待っている間、このメソッドはすべての他のイベント通知を廃棄する。

戻り値が S_OK なら、pEvCode パラメータは待ち状態終了のイベントコードを受け取る。メソッドが帰っても、フィルタ グラフはまだ実行している。アプリケーションは必要に応じてグラフをポーズしたり停止したりできる。


IMediaEventEx インターフェイス

このインターフェイスは、イベント通知を取得するメソッドと、フィルタ グラフのデフォルトのイベント処理をオーバーライドするメソッドを提供する IMediaEvent インターフェイスを継承する。IMediaEventEx には、イベント発生時にアプリケーション ウィンドウでメッセージを受け取るためのメソッドが加わっている。このインターフェイスは、IMediaEvent と異なり、Automation を通じて利用できない。したがって、Microsoft® Visual Basic® から直接呼び出すこともできない。

フィルタ グラフ マネージャがこのインターフェイスを実装する。

イベント通知の詳細については、「DirectShow でのイベント通知」を参照すること。システム定義のイベント通知の一覧については、「イベント通知コード」を参照すること。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IDispatch メソッド | 説明
GetTypeInfoCount | このディスプインターフェイスに利用可能なタイプ情報があるかどうか判断する。
GetTypeInfo | GetTypeInfoCount が成功した場合は、このディスプインターフェイスのタイプ情報を取得する。
GetIDsOfNames | (引数を含む) プロパティおよびメソッドのテキスト名を対応する DISPID に変換する。
Invoke | DISPID およびその他の必要なパラメータが指定された場合は、このディスプインターフェイスのメソッドを呼び出すか、またはプロパティにアクセスする。
IMediaEvent メソッド | 説明
GetEventHandle | キューにイベント通知が入っている間に通知済状態の自動リセット イベントのハンドルを取得する。
GetEvent | イベント キューから次の通知イベントを取得する。
WaitForCompletion | フィルタ グラフがすべての有効なデータをレンダリングするまで待機する。
CancelDefaultHandling | フィルタ グラフによる指定されたイベントのフィルタ グラフ マネージャのデフォルト処理をキャンセルする。
RestoreDefaultHandling | フィルタ グラフによる指定されたイベントのフィルタ グラフ マネージャのデフォルト処理をリストアする。
FreeEventParams | イベントのパラメータに関連付けられたリソースを解放する。
IMediaEventEx メソッド | 説明
SetNotifyWindow | イベント通知を処理するウィンドウを登録する。
SetNotifyFlags | イベント通知を利用可あるいは不可にする。
GetNotifyFlags | イベント通知の利用可あるいは不可を確認する。

IMediaEventEx::GetNotifyFlags

IMediaEventEx インターフェイス

イベント通知の利用可あるいは不可を確認する。

構文

HRESULT GetNotifyFlags(
    long *lplNoNotifyFlags
);

パラメータ

lplNoNotifyFlags
[out] イベント通知のオン/オフを示す値へのポインタ。
  • ゼロ: イベント通知は利用可能。
  • AM_MEDIAEVENT_NONOTIFY: イベント通知は利用不可。

戻り値

成功した場合は、S_OK を返す。lplNoNotifyFlags パラメータが NULL の場合は、E_POINTER を返す。

注意

デフォルトでは、フィルタ グラフ マネージャはアプリケーションにイベント通知を送る。イベント通知を利用不可にするには、SetNotifyFlags に AM_MEDIAEVENT_NONOTIFY を引数として呼び出す。

イベント通知が利用不可なら、各ストリームが終ると GetEventHandle メソッドから返るハンドルが通知済になる、すなわちフィルタ グラフ マネージャが EC_COMPLETE イベントを受け取るたびに通知済になる。

IMediaEventEx::SetNotifyFlags

IMediaEventEx インターフェイス

イベント通知を利用可あるいは不可にする。

構文

HRESULT SetNotifyFlags(
    long lNoNotifyFlags
);

パラメータ

lNoNotifyFlags
[in] イベント通知を利用可にするか不可にするかを示す値。以下の値の 1 つでなければならない :
  • ゼロ : イベント通知を利用可能にする。
  • AM_MEDIAEVENT_NONOTIFY: イベント通知を利用不可にする。

戻り値

成功した場合は、S_OK を返す。lNoNotifyFlags パラメータが無効な場合は、E_INVALIDARG を返す。

注意

デフォルトでは、フィルタ グラフ マネージャはアプリケーションにイベント通知を送る。イベント通知を利用不可にするには、SetNotifyFlags メソッドを AM_MEDIAEVENT_NONOTIFY フラグで呼び出す。

イベント通知が利用不可なら、各ストリームが終ると GetEventHandle メソッドから返るハンドルが通知済になる、すなわちフィルタ グラフ マネージャが EC_COMPLETE イベントを受け取るたびに通知済になる。

IMediaEventEx::SetNotifyWindow

IMediaEventEx インターフェイス

イベント通知を処理するウィンドウを登録する。

構文

HRESULT SetNotifyWindow(
    OAHWND hwnd,
    long lMsg,
    long lInstanceData
);

パラメータ

hwnd
[in] 通知するウィンドウのハンドル、あるいは通知を停止するには NULL を渡す。
lMsg
[in] 通知として渡すウィンドウ メッセージ。
lInstanceData
[in] lMsg メッセージの lParam パラメータとして渡す値 。

戻り値

成功した場合は、S_OK を返す。hwnd パラメータが有効なウィンドウ ハンドルでない場合は、E_INVALIDARG を返す。

注意

このメソッドはイベント通知を処理するウィンドウを指示する。フィルタ グラフ マネージャがイベントをイベント キューに入れるたびに、指定したウィンドウにメッセージも送る。hwnd パラメータはウィンドウを指定し、lMsg パラメータはメッセージを指定する。アプリケーションはプライベート ウィンドウ メッセージをこのために定義すべきである。メッセージの lParam パラメータには lInstanceData の値がセットされ、wParam パラメータはゼロにセットされる。

ウィンドウがメッセージを受け取ったら、GetEvent メソッドを呼び出してイベントを取得すべきだ。イベントは非同期なので、キューには複数の(あるいはゼロの)イベントが入っている可能性がある。GetEvent がエラーコードを返すまで繰り返し呼び出すこと。


IMediaEventSink インターフェイス

フィルタ グラフ マネージャにフィルタグラフ内で起きたイベントを通知する。フィルタはこのインターフェイスを使ってイベントをレポートする。フィルタ グラフ マネージャはこのインターフェイスを公開する。

アプリケーションでは IMediaEventSink を使用しない。アプリケーションからイベントを取得するには、IMediaEventEx インターフェイスを使用する。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IMediaEventSink メソッド | 説明
Notify | フィルタ グラフ マネージャにイベントを通知する。

IMediaEventSink::Notify

IMediaEventSink インターフェイス

フィルタ グラフ マネージャにイベントを通知する。

構文

HRESULT Notify(
long EventCode,
LONG_PTR EventParam1,
LONG_PTR EventParam2
);

パラメータ

EventCode
[in] イベントの識別子。
EventParam1
[in] イベントの第 1 パラメータ。
EventParam2
[in] イベントの第 2 パラメータ。

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
S_OK または NOERROR | 成功。

注意

イベントはキューに入れられるが、このスレッド上ではアプリケーションに通知されない。通知コードおよびパラメータ値の一覧については、「イベント通知コード」を参照すること。


IMediaFilter インターフェイス

フィルタのストリーミング状態を制御する。

すべての Microsoft® DirectShow® フィルタは、このインターフェイスを実装する。このインターフェイスは、フィルタの状態 (停止、ポーズ、実行) を切り替えるメソッド、フィルタの現在の状態を取得するメソッド、および基準クロックを設定するメソッドを提供する。フィルタ グラフ マネージャも、このインターフェイスを公開する。フィルタ グラフ マネージャは、フィルタグラフ内のフィルタに、メソッド呼び出しを提供する。

このインターフェイスは、低いレベルの制御をグラフへ提供する。アプリケーションは、より高いレベルの制御を提供する IMediaControl インターフェイスを使う必要がある。

IMediaFilter は、IPersist インターフェイスを継承する。IBaseFilter インターフェイスは、IMediaFilter から継承される。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを返す。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IMediaFilter メソッド | 説明
Stop | フィルタを停止する。
Pause | フィルタをポーズする。
Run | フィルタを実行する。
GetState | フィルタの状態 (停止、ポーズ、実行) を取得する。
SetSyncSource | フィルタの基準クロックを設定する。
GetSyncSource | フィルタが使用している基準クロックを取得する。

IMediaFilter::GetState

IMediaFilter インターフェイス

フィルタの状態 (停止、ポーズ、実行) を取得する。

構文

HRESULT GetState(
  DWORD dwMilliSecsTimeout,
  FILTER_STATE *State
  );

パラメータ

dwMilliSecsTimeout
[in] タイムアウト時間、ミリ秒単位。無期限にブロックするには INFINITE を渡す。
State
[out] フィルタの状態を示す FILTER_STATE 列挙型のメンバを受け取る変数へのポインタ。

戻り値

HRESULT 値を返す。以下の表に示されるいずれかの値。

S_OK | 成功。
E_POINTER | NULL ポインタ引数。
VFW_S_STATE_INTERMEDIATE | 状態移行中。
VFW_S_CANT_CUE | フィルタはアクティブだが、データを出力することができない。

注意

状態移行は非同期で行うことができる。フィルタが新しい状態に移行していて、移行が完了する前にメソッドのタイムアウト時間が来たなら、メソッドは VFW_S_STATE_INTERMEDIATE を返す。

フィルタがある理由でデータを出力できないなら、VFW_S_CANT_CUE を返す。ライブ キャプチャ フィルタは、ポーズ状態ではデータを出力しないため、ポーズ中にこの値を返す。

詳細については、「フィルタ グラフのデータ フロー」を参照すること。

IMediaFilter::GetSyncSource

IMediaFilter インターフェイス

フィルタが使用している基準クロックを取得する。

構文

HRESULT GetSyncSource(

  IReferenceClock **pClock

  );

パラメータ

pClock
[out] クロックの IReferenceClock インターフェイスへのポインタを受け取る変数のアドレス。

戻り値

HRESULT 値を返す。以下の表に示されるいずれかの値。

E_OK | 成功。
E_POINTER | Null ポインタ引数。

注意

もしフィルタが基準クロックを使わないなら、*pClock に NULL が設定される。メソッドが帰るとき、*pClock が NULL 以外なら、IReferenceClock インターフェイスには参照カウントが残る。解放時には注意が必要である。

IMediaFilter::Pause

IMediaFilter インターフェイス

フィルタをポーズする。

構文

HRESULT Pause(void);

戻り値

HRESULT 値を返す。以下の表に示されるいずれかの値。

S_FALSE | 移行が完了しなかった。
S_OK | 成功。移行は完了した。

注意

フィルタがポーズのとき、フィルタはサンプルを受け取り、処理し、出力することができる。しかし、レンダリング フィルタはポーズ中は 1 つのサンプルにしかアクセスできない。そのため、フィルタ グラフがポーズのときは、最初のサンプルがレンダラに届くまではサンプルはグラフ内を移動する。そのとき、ストリーミングは Run メソッドが呼び出されるまでポーズとなる。ビデオ レンダラは、最初のサンプルを静止画として表示する。

ライブ キャプチャ フィルタはポーズ中にはサンプルを出力できず、実行中のみ出力する。

状態移行は非同期の場合がある。移行が完了する前にメソッドが返るなら、戻り値は S_FALSE である。レンダラ フィルタは、サンプルを 1 つ受け取るまでは状態移行を完了しない。

IMediaFilter::Run

IMediaFilter インターフェイス

フィルタを実行する。

構文

HRESULT Run(
    REFERENCE_TIME tStart
);

パラメータ

tStart
ストリーム タイム 0 に対応する基準タイム。

戻り値

HRESULT 値を返す。以下の表に示されるいずれかの値。

S_FALSE | 移行が完了しなかった。
S_OK | 成功。移行は完了した。

注意

フィルタがポーズのとき、フィルタはサンプルを受け取り、処理し、出力することができる。しかし、ソース フィルタは新しいサンプルを生成し、レンダリング フィルタはそれをレンダリングする。

状態移行は非同期の場合がある。移行が完了する前にメソッドが返る場合、戻り値は S_FALSE である。

ストリーム タイムは現在の基準タイムから tStart を引いて計算される。メディア サンプルがいつレンダリングされかを計算するために、レンダラは現在のストリーム タイムとタイム スタンプを比較する。そのため、タイム スタンプ ゼロのメディア サンプルは、tStart 時にレンダリングされる必要がある。詳細については、「DirectShow のタイムとクロック」を参照すること。

アプリケーションが IMediaControl::Run メソッドを呼び出す場合に、フィルタ グラフ マネージャは各フィルタで IMediaFilter::Run を呼び出す。フィルタ グラフ マネージャは tStart の値を少し後で設定し、グラフの遅延に対応する。

IMediaFilter::SetSyncSource

IMediaFilter インターフェイス

フィルタの基準クロックを設定する。

構文

HRESULT SetSyncSource(
    IReferenceClock *pClock
);

パラメータ

pClock
[in] クロックの IReferenceClock インターフェイスへのポインタまたは NULL 。

戻り値

成功の場合 S_OK を返す。それ以外の場合は、エラーの原因を示す HRESULT 値を返す。

注意

pClock パラメータが NULL の場合、フィルタは基準クロックを使用しない。レンダリング フィルタは基準クロックを使って、いつサンプルがレンダリングされるかをスケジュールする。基準クロックがない場合、レンダリング フィルタは、すべてのサンプルを受け取るとすぐにレンダリングする。

フィルタ グラフ内のすべてのフィルタは、同期を取るために、同じ基準クロックを共有する必要がある。通常、フィルタ グラフ マネージャは基準クロックを選択する。アプリケーションは、フィルタ グラフ マネージャで IMediaFilter::SetSyncSource メソッドを呼び出して、デフォルトのクロックをオーバーライドできる。ただし、このようにするのは、ほかのクロックを選択する特別な理由がある場合のみである。

IMediaFilter::Stop

IMediaFilter インターフェイス

フィルタを停止する。

構文

HRESULT Stop(void);

戻り値

HRESULT 値を返す。以下の表に示されるいずれかの値。

S_FALSE | 移行が完了しなかった。
S_OK | 成功。移行は完了した。

注意

フィルタが停止すると、フィルタはサンプルの処理や出力は行わない。また、アップストリーム フィルタからのサンプルを拒否する。

状態移行は非同期の場合がある。移行が完了する前にメソッドが返る場合、戻り値は S_FALSE となる。


IMediaPosition インターフェイス

ストリーム内の位置をシークするメソッドを持つ。

IMediaSeeking インターフェイスはこのインターフェイスを改善している。C/C++ で書かれたアプリケーションは IMediaPosition の代わりに IMediaSeeking を使うべきである。しかし、IMediaSeeking は Automation と互換性がないので、Microsoft® Visual Basic® で書かれたアプリケーションは代わりに IMediaPosition を使用しなければならない。

このインターフェイスは個々のフィルタが行うのと同様にフィルタ グラフ マネージャによって公開されている。アプリケーションは IMediaPosition インターフェイス ポインタをフィルタからではなくフィルタ グラフ マネージャから取得すべきである。フィルタ グラフ マネージャはソース フィルタへのアップストリーム 呼び出しを継承する。イベントのこのシーケンスによってすべてのストリームは同期される。

割り当てた呼び出しがエラーを返したら、フィルタ グラフ マネージャは取得した最初のエラー値を返す。この場合割り当てた呼び出しのいくつかが成功している可能性がある。しかし、割り当てたすべての呼び出しが E_NOTIMPL を返すまで、フィルタ グラフは E_NOTIMPL を返さない。グラフ内の少なくとも 1 つのフィルタがそのメソッドを実装すると、フィルタ グラフ マネージャは E_NOTIMPL を返さない。

フィルタ 開発者 : このメソッドを実装してはならない。代わりに IMediaSeeking を実装すること。そのフィルタが IMediaSeeking をサポートするなら、フィルタ グラフ マネージャは自動的に IMediaPosition への呼び出しを処理する。

Vtable 順のメソッド。

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IDispatch メソッド | 説明
GetTypeInfoCount | オブジェクトが提供するタイプ情報インターフェイスの数を取得する。
GetTypeInfo | オブジェクトのタイプ情報を取得する、それを使ってインターフェイスのタイプ情報を取得する。
GetIDsOfNames | 一連の DISPID に対応する一連の名前をマップする。
Invoke | オブジェクトによって公開されるプロパティとメソッドへのアクセスを提供する。
IMediaPosition メソッド | 説明
get_Duration | ストリームの時間幅を取得する。
put_CurrentPosition | 現在の位置を設定する、ストリームの全時間幅からの相対値。
get_CurrentPosition | 現在の位置を取得する、ストリームの全時間幅からの相対値。
get_StopTime | 再生が停止する時間を取得する、ストリームの全時間幅からの相対値。
put_StopTime | 再生が停止する時間を設定する、ストリームの全時間幅からの相対値。
get_PrerollTime | 開始位置の前にキューに入っているデータの量を取得する。
put_PrerollTime | 開始位置の前にキューに入っているデータの量を設定する。
put_Rate | 再生レートを設定する。
get_Rate | 再生レートを取得する。
CanSeekForward | フィルタ グラフがストリームの順方向にシーク可能かどうかを確認する。
CanSeekBackward | フィルタ グラフがストリームの逆方向にシーク可能かどうかを確認する。

IMediaPosition::CanSeekBackward

IMediaPosition インターフェイス

フィルタ グラフがストリームの逆方向にシーク可能かどうかを確認する。

構文

HRESULT CanSeekBackward(
    LONG *pCanSeekBackward
);

パラメータ

pCanSeekBackward
[out] グラフが逆方向にシーク可能なら OATRUE 値を受け取り、シークできないなら OAFALSE を受け取る変数へのポインタ。

戻り値

HRESULT を返す。以下のいずれかの値。

S_OK | 成功。
E_NOTIMPL | 実装されていない。
E_POINTER | NULL ポインタ引数。

IMediaPosition::CanSeekForward

IMediaPosition インターフェイス

フィルタ グラフがストリームの順方向にシーク可能かどうかを確認する。

構文

HRESULT CanSeekForward(
    LONG *pCanSeekForward
);

パラメータ

pCanSeekForward
[out] グラフが順方向にシーク可能なら OATRUE 値を受け取り、シークできないなら OAFALSE を受け取る変数へのポインタ。

戻り値

HRESULT を返す。以下のいずれかの値。

S_OK | 成功。
E_NOTIMPL | 実装されていない。
E_POINTER | NULL ポインタ引数。

IMediaPosition::get_CurrentPosition

IMediaPosition インターフェイス

現在の位置を取得する、ストリームの全時間幅からの相対値。

構文

HRESULT get_CurrentPosition(
    REFTIME *pllTime
);

パラメータ

pllTime
[out] 現在の位置を受け取る変数へのポインタ、秒単位。

戻り値

HRESULT を返す。以下のいずれかの値。

S_OK | 成功。
E_NOTIMPL | 実装されていない。
E_POINTER | NULL ポインタ引数。

注意

このメソッドは再生が到達した現在位置を返す。その値は再生レートと開始タイムを無視する。たとえば、レートに 2.0 をセットし、開始タイムが 5 秒だとすると、4 秒グラフを実行すると現在の位置は 9.0 秒となる (5 + 4 × 2.0)。

グラフがポーズあるいは停止なら、現在位置は再生が復帰するポイントとなる。

IMediaPosition::get_Duration

IMediaPosition インターフェイス

ストリームの時間幅を取得する。

構文

HRESULT get_Duration(
    REFTIME *plength
);

パラメータ

plength
[out] 全ストリーム長を受け取る変数へのポインタ、秒単位。

戻り値

HRESULT を返す。以下のいずれかの値。

S_OK | 成功。
E_NOTIMPL | 実装されていない。
E_POINTER | NULL ポインタ引数。

注意

このメソッドは通常再生スピードでの時間幅を取得する。再生レートを変更してもその時間幅には影響しない。

IMediaPosition::get_PrerollTime

IMediaPosition インターフェイス

開始位置の前にキューに入っているデータの量を取得する。

構文

HRESULT get_PrerollTime(
    REFTIME *pllTime
);

パラメータ

pllTime
[out] プリロール タイムを受け取る変数へのポインタ、秒単位。

戻り値

HRESULT を返す。以下のいずれかの値。

S_OK | 成功。
E_NOTIMPL | 実装されていない。
E_POINTER | NULL ポインタ引数。

注意

プリロール は開始位置より前のタイムで、テープ プレーヤーのような非ランダム アクセス デバイスではそこからテープなどの巻き込みが開始される。

グラフ内にこのメソッドを実装したフィルタがないなら、フィルタ グラフ マネージャは *pllTime の値をゼロにセットして S_OK を返す。

IMediaPosition::get_Rate

IMediaPosition インターフェイス

再生レートを取得する。

構文

HRESULT get_Rate(
    double *pdRate
);

パラメータ

pdRate
[out] 再生レートを受け取る変数へのポインタ。

戻り値

HRESULT を返す。以下のいずれかの値。

S_OK | 成功。
E_NOTIMPL | 実装されていない。
E_POINTER | NULL ポインタ引数。

注意

再生レートは通常スピードからの比で表現される。それゆえ、1.0 は通常再生スピードで、0.5 は半分のスピード、2.0 は倍のスピードである。

IMediaPosition::get_StopTime

IMediaPosition インターフェイス

再生が停止する時間を取得する、ストリームの全時間幅からの相対値。

構文

HRESULT get_StopTime(
    REFTIME *pllTime
);

パラメータ

pllTime
[out] 終了タイムを受け取る変数へのポインタ、秒単位。

戻り値

HRESULT を返す。以下のいずれかの値。

S_OK | 成功。
E_NOTIMPL | 実装されていない。
E_POINTER | NULL ポインタ引数。

注意

再生レートはこのメソッドによって返る値に影響を与えない。

IMediaPosition::put_CurrentPosition

IMediaPosition インターフェイス

現在の位置を設定する、ストリームの全時間幅からの相対値。

構文

HRESULT put_CurrentPosition(
    REFTIME llTime
);

パラメータ

llTime
[in] 新しい位置、秒単位。

戻り値

Returns an HRESULT 値を返す。以下のいずれかの値 :

S_FALSE | グラフはポーズだった、そして実行状態に戻る移行中である。
S_OK | 成功。
E_INVALIDARG | 不適切な引数。
E_NOTIMPL | 実装されていない。

注意

llTime パラメータによって指定される位置は全時間幅からの相対値であり、再生レートは無視される。たとえば、ソース ファイルが 10 秒の長さなら、5.0 の位置を設定するとグラフは再生レートとは無関係にファイルの真中をシークする。

フィルタ グラフが実行中なら、フィルタ グラフ マネージャはグラフをポーズし、シーク コマンドを処理し、次にグラフを再度実行する。グラフが実行状態への移行中にメソッドが返ると、戻り値は S_FALSE となる。

シーク コマンドを受け取ったときフィルタがポーズなら、新しい位置からそのデータを取り込む前に既存のデータをフラッシュしなければならない。詳細については、IPin::BeginFlush」と「IPin::EndFlush」を参照すること。

IMediaPosition::put_PrerollTime

IMediaPosition インターフェイス

開始位置の前にキューに入っているデータの量を設定する。

構文

HRESULT put_PrerollTime(
    REFTIME llTime
);

パラメータ

llTime
[in] プリロール タイム、秒単位。

戻り値

HRESULT を返す。以下のいずれかの値。

S_OK | 成功。
E_NOTIMPL | 実装されていない。

注意

プリロール は開始位置より前のタイムで、テープ プレーヤーのような非ランダム アクセス デバイスではそこからテープなどの巻き込みが開始される。

IMediaPosition::put_Rate

IMediaPosition インターフェイス

再生レートを設定する。

構文

HRESULT put_Rate(
    double dRate
);

パラメータ

dRate
[in] 再生レート、ゼロであってはならない。

戻り値

HRESULT を返す。以下のいずれかの値。

S_OK | 成功。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | 実装されていない。

注意

再生レートは通常スピードの割合として表現される。したがって、1.0 は通常再生スピード、0.5 は半分のスピード、2.0 は倍のスピードである。オーディオ ストリームについては、レートを変えるとそのピッチも変わる。

詳細については、「IMediaSeeking::SetRate」を参照すること。

IMediaPosition::put_StopTime

IMediaPosition インターフェイス

再生が停止する時間を取得する、ストリームの全時間幅からの相対値。

構文

HRESULT put_StopTime(
    REFTIME llTime
);

パラメータ

llTime
[in] ストップ タイム、秒単位。

戻り値

HRESULT を返す。以下のいずれかの値。

S_OK | 成功。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | 実装されていない。

注意

ストップ単位は開始タイムと再生レートを無視する。たとえば、開始タイムが 2 秒で、ストップタイムが 12 秒で、再生レートが 2.0 なら、再生は (実際の時間で) 5 秒後に停止する。


IMediaPropertyBag インターフェイス

IMediaPropertyBag インターフェイスは、メディア プロパティ バッグで公開される。メディア プロパティ バッグとは、標準的な COM のプロパティ バッグを特殊化したものであり、AVI (Audio-Video Interleaved) ファイルの INFO チャンクおよび DISP チャンクの設定および取得を目的としている。

INFO チャンクには、作者、著作権情報など、ファイルに関する包括的な情報が格納されている。DISP チャンクには、データがクリップボード フォーマットで格納されている。詳細については、RIFF (Resource Interchange File Format) の仕様を参照すること。

メディア プロパティ バッグのチャンクは、次のように名前/値ペアで格納される。

  • INFO チャンク : 名前は INFO/XXXX フォーマットの文字列。ここで XXXX は包括的な情報の種類を定義する 4 文字のコードであり、たとえば ICOP は著作権情報、IART は作者名を意味する。値は任意の文字列。
  • DISP チャンク : 名前は DISP/0000000000 フォーマットの文字列。ここで 0000000000 は標準的なクリップボード フォーマットと同等の 10 桁の十進数であり、たとえば 0000000008 は CF_DIB を意味する。値は表示データが格納されたバイト配列。

このインターフェイスは IPropertyBag インターフェイスを継承する。このインターフェイスを IPersistMediaPropertyBag インターフェイスと共に使用して、AVI ファイルから INFO チャンクおよび DISP チャンクを取得する。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IMediaPropertyBag メソッド | 説明
EnumProperty | プロパティと値のペアを取得する。

IMediaPropertyBag::EnumProperty

IMediaPropertyBag インターフェイス

プロパティと値のペアを取得する。

構文

HRESULT EnumProperty(
    ULONG iProperty,
    VARIANT *pvarPropertyName,
    VARIANT *pvarPropertyValue
);

パラメータ

iProperty
[in] ペアのインデックス値。
pvarPropertyName
[in, out] プロパティの名前を受け取る VARIANT へのポインタ。
pvarPropertyValue
[in, out] プロパティの値を受け取る VARIANT へのポインタ。

戻り値

HRESULT 値を返す。設定される値は次のとおりである。

S_OK | 成功。
E_INVALIDARG | 無効な引数。
E_OUTOFMEMORY | メモリ不足。
E_POINTER | NULL ポインタ引数。
HRESULT_FROM_WIN32(ERROR_NO_MORE_ITEMS) | インデックスが範囲外。

注意

名前は常に文字列である。このメソッドを呼び出す前に、VARIANT 型の pvarPropertyName パラメータに VT_EMPTY または VT_BSTR を設定すること。

値は文字列 (INFO チャンクの場合) またはバイト配列 (DISP チャンクの場合) である。VARIANT 型の pvarPropertyName パラメータに VT_EMPTY、VT_BSTR、または (VT_ARRAY | VT_UI1) を設定する。


IMediaSample インターフェイス

メディア サンプルのプロパティをセットあるいは取得する。メディア サンプルは COM オブジェクトでありメディアデータのブロックが格納される。メディア サンプルはフィルタ間の共有メモリ バッファの使用をサポートする。

このインターフェイスは、メディア サンプルのプロパティを設定および取得するメソッドを提供する。メディア サンプルとは、メディア データのブロックが格納された COM オブジェクトである。メディア サンプルは、フィルタ間での共有メモリ バッファの使用をサポートする。

IMediaSample2 インターフェイスは、このインターフェイスを継承する。

通常、このインターフェイスのメソッドを、アプリケーションから呼び出すことはない。フィルタでは、このインターフェイスを使用して、サンプルのプロパティを設定し、ダウンストリーム フィルタにデータを渡す。そのダウンストリーム フィルタでは、このインターフェイスを使用して、プロパティを取得し、データを読み取る。フィルタは、データを直接修正するか、またはサンプルをコピーしてから変更し、ダウンストリームへ渡す。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IMediaSample メソッド | 説明
GetPointer | このバッファのメモリへの読み取り/書き込みポインタを取得する。
GetSize | バッファのサイズを取得する。
GetTime | このサンプルが開始および終了すべきストリーム タイムを取得する。
SetTime | このサンプルが開始および終了すべきストリーム タイムを設定する。
IsSyncPoint | このサンプルの始まりが同期ポイントかどうかを判断する。
SetSyncPoint | このサンプルの始まりが同期ポイントかどうかを設定する。
IsPreroll | このサンプルがプリロール サンプルかどうかを確認する。
SetPreroll | このサンプルがプリロール サンプルかどうかを指定する。
GetActualDataLength | バッファ内の有効なデータの長さを取得する。
SetActualDataLength | バッファ内の有効なデータの長さを設定する。
GetMediaType | メディア タイプが以前のサンプルと異なるなら、メディア タイプを取得する。
SetMediaType | サンプルのメディア タイプを設定する。
IsDiscontinuity | このサンプルがデータ ストリーム内でブレークを表示するかどうかを確認する。
SetDiscontinuity | このサンプルがデータ ストリーム内でブレークを表示するかどうかを指定する。
GetMediaTime | このサンプルのメディア タイムを取得する。
SetMediaTime | このサンプルのメディア タイムを設定する。

IMediaSample::GetActualDataLength

IMediaSample インターフェイス

バッファ内の有効なデータの長さを取得する。

構文

LONG GetActualDataLength(void);

戻り値

有効なデータの長さを返す、バイト単位。

IMediaSample::GetMediaTime

IMediaSample インターフェイス

このサンプルのメディア タイムを取得する。

構文

HRESULT GetMediaTime(
    LONGLONG *pTimeStart,
    LONGLONG *pTimeEnd
);

パラメータ

pTimeStart
[out] メディア開始タイムを受け取る変数へのポインタ。
pTimeEnd
[out] メディア終了タイムを受け取る変数へのポインタ。

戻り値

HRESULT 値を返す。 以下の表に示されるいずれかの値。

S_OK | 成功。
VFW_E_MEDIA_TIME_NOT_SET | このサンプルにはメディア タイムがセットされていない。

注意

メディア タイムの詳細については、「DirectShow のタイムとクロック」を参照すること。

IMediaSample::GetMediaType

IMediaSample インターフェイス

メディア タイプが以前のサンプルと異なるなら、メディア タイプを取得する。

構文

HRESULT GetMediaType(
    AM_MEDIA_TYPE **ppMediaType
);

パラメータ

ppMediaType
AM_MEDIA_TYPE 構造体へのポインタを受け取る変数のアドレス。メディア タイプが以前のサンプルと異ならないなら、*ppMediaType には NULL がセットされる。

戻り値

HRESULT 値を返す。以下の表に示されるいずれかの値。

S_FALSE | メディア タイプは以前のサンプルから変更されていない。
S_OK | 成功。
E_OUTOFMEMORY | メモリ不足。

注意

このメソッドによってフィルタはパレット変更のような限定したメディア タイプの変更を行うことができる。メディア タイプの大きな変更をするなら、ピンは再接続して、メディア タイプを再ネゴシエーションする必要がある。

メディア タイプの扱いが終了したら、DeleteMediaType ユーティリティ関数を呼び出してメモリ ブロックを解放すること。

IMediaSample::GetPointer

IMediaSample インターフェイス

このバッファのメモリへの読み取り/書き込みポインタを取得する。

構文

HRESULT GetPointer(
    BYTE **ppBuffer
);

パラメータ

ppBuffer
[out] バッファへのポインタのアドレス。

戻り値

成功なら S_OK を返す、あるいはエラーの原因を示す HRESULT 値を返す。

IMediaSample::GetSize

IMediaSample インターフェイス

バッファのサイズを取得する。

構文

ling GetSize(void);

戻り値

バッファのサイズを返す、バイト単位。

IMediaSample::GetTime

IMediaSample インターフェイス

このサンプルが開始および終了すべきストリーム タイムを取得する。

構文

HRESULT GetTime(
    REFERENCE_TIME *pTimeStart,
    REFERENCE_TIME *pTimeEnd
);

パラメータ

pTimeStart
[out] 開始ストリーム タイムを受け取る変数へのポインタ。
pTimeEnd
[out] 終了ストリーム タイムを受け取る変数へのポインタ。サンプルに終了タイムがない場合、この値には開始タイムに 1 を加えた値が設定される。

戻り値

HRESULT 値を返す。以下の表に示されるいずれかの値。

S_OK | 成功。サンプルは有効な開始タイムと終了タイムを持つ。
VFW_S_NO_STOP_TIME | サンプルは有効な開始タイムを持つが、終了タイムを持たない。
VFW_E_SAMPLE_TIME_NOT_SET | サンプルはタイム スタンプを持たない。

注意

ストリーム タイムの詳細については、「DirectShow のタイムとクロック」を参照すること。

IMediaSample::IsDiscontinuity

IMediaSample インターフェイス

このサンプルがデータ ストリーム内でブレークを表示するかどうかを確認する。

構文

HRESULT IsDiscontinuity(void);

戻り値

サンプルがデータストリーム内にブレークを持っているなら S_OK を返す。そうでなければ S_FALSE を返す。

注意

フィルタがストリーム内の違った場所をシークするとき、あるいはフィルタが品質コントロールのためにサンプルをドロップするとき、不連続が起きる。

IMediaSample::IsPreroll

IMediaSample インターフェイス

このサンプルがプリロール サンプルかどうかを確認する。

構文

HRESULT IsPreroll(void);

戻り値

サンプルがプリロール サンプルの場合は S_OK を返し、そうでなければ S_FALSE を返す。

注意

プリロール サンプルは処理されるが表示はされない。それはメディア ストリーム内で表示するサンプルの前にある。

IMediaSample::IsSyncPoint

IMediaSample インターフェイス

このサンプルの始まりが同期ポイントかどうかを判断する。

構文

HRESULT IsSyncPoint(void);

戻り値

サンプルが同期ポイントの場合は S_OK を返す。そうでなければ S_FALSE を返す。

注意

フィルタは同期ポイントでストリームを開始できる。いくつかの圧縮タイプではストリーミングはストリーム内のあるポインタからしか開始できない、たとえばキー フレームから。AM_MEDIA_TYPE 構造体の bTemporalCompression メンバが FALSE なら、すべてのサンプルが同期ポイントである。

IMediaSample::SetActualDataLength

IMediaSample インターフェイス

バッファ内の有効なデータの長さを設定する。

構文

HRESULT SetActualDataLength(
    long lLen
);

パラメータ

lLen
メディア サンプルのデータの長さ (バイト単位)。

戻り値

HRESULT 値を返す。以下の表に示されるいずれかの値。

S_OK | 成功。
VFW_E_BUFFER_OVERFLOW. | lLen で指定された長さがバッファサイズより長い。

IMediaSample::SetDiscontinuity

IMediaSample インターフェイス

このサンプルがデータ ストリーム内でブレークを表示するかどうかを指定する。

構文

HRESULT SetDiscontinuity(
    BOOL bIsDiscontinuity
);

パラメータ

bIsDiscontinuity
[in] このサンプルが不連続かどうかを示すブール値。TRUE なら、メディア サンプルは以前のサンプルと不連続である。

戻り値

S_OK を返す、あるいはエラーの原因を示す HRESULT を返す。

参照

IMediaSample::IsDiscontinuity

IMediaSample::SetMediaTime

IMediaSample インターフェイス

このサンプルのメディア タイムを設定する。

構文

HRESULT SetMediaTime(
    LONGLONG *pTimeStart,
    LONGLONG *pTimeEnd
);

パラメータ

pTimeStart
[in] 開始メディア タイムへのポインタ。
pTimeEnd
[in] 終了メディア タイムへのポインタ。

戻り値

S_OK を返す、あるいはエラーの原因を示す HRESULT を返す。

注意

メディア タイムを無効にするには、pTimeStart と pTimeEnd を NULL に設定する。これによって IMediaSample::GetMediaTime メソッドは VFW_E_MEDIA_TIME_NOT_SET を返す。

メディア タイムの詳細については、「DirectShow のタイムとクロック」を参照すること。

IMediaSample::SetMediaType

IMediaSample インターフェイス

サンプルのメディア タイプを設定する

構文

HRESULT SetMediaType(
    AM_MEDIA_TYPE *pMediaType
);

パラメータ

pMediaType
メディア タイプを指定する AM_MEDIA_TYPE 構造体へのポインタ。

戻り値

HRESULT 値を返す。 以下の表に示されるいずれかの値。

S_OK | 成功。
E_OUTOFMEMORY | メモリ不足。

注意

デフォルトでは、すべてのサンプルは前のサンプルと同じメディア タイプを持つ (ピン接続がオリジナルのメディア タイプを決定する)。このメソッドを呼び出すことによってフィルタはパレット変更のような限定したメディア タイプの変更を行うことができる。メディア タイプの大きな変更をするなら、ピンは再接続して、メディア タイプを再ネゴシエーションする必要がある。

IMediaSample::SetPreroll

IMediaSample インターフェイス

このサンプルがプリロール サンプルかどうかを指定する。

構文

HRESULT SetPreroll(
    BOOL bIsPreroll
);

パラメータ

bIsPreroll
これがプリロール サンプルかどうかを示すブール値。TRUE ならこれはプリロール サンプル。

戻り値

S_OK を返す、あるいはエラーの原因を示す HRESULT 値を返す。

参照

IMediaSample::IsPreroll

IMediaSample::SetSyncPoint

IMediaSample インターフェイス

このサンプルの始まりが同期ポイントかどうかを設定する。

構文

HRESULT SetSyncPoint(
    BOOL bIsSyncPoint
);

パラメータ

bIsSyncPoint
[in] これが同期ポイントかどうかを示すブール値。TRUE ならこれは同期ポイント。

戻り値

S_OK を返す、あるいはエラーの原因を示す HRESULT 値を返す。

参照

IMediaSample::IsSyncPoint

IMediaSample::SetTime

IMediaSample インターフェイス

このサンプルが開始および終了すべきストリーム タイムを設定する。

構文

HRESULT SetTime(
    REFERENCE_TIME *pTimeStart,
    REFERENCE_TIME *pTimeEnd
);

パラメータ

pTimeStart
[in] サンプルの開始ストリーム タイムへのポインタ、100 ナノ秒単位。
pTimeEnd
[in] サンプルの終了ストリーム タイムへのポインタ、100 ナノ秒単位。

戻り値

S_OK を返す、あるいはエラーの原因を示す HRESULT 値を返す。

注意

メディア タイムを無効にするには、pTimeStart と pTimeEnd を NULL に設定する。これによって IMediaSample::GetTime メソッドは VFW_E_SAMPLE_TIME_NOT_SET を返す。

ストリーム タイムの詳細については、「DirectShow のタイムとクロック」を参照すること。


IMediaSample2 インターフェイス

メディア サンプルのプロパティをセットし取得する。このインターフェイスは IMediaSample インターフェイスを継承する。IMediaSample インターフェイスは各サンプル プロパティに別々のメソッド呼び出しを要求する。IMediaSample2 インターフェイスは複数のプロパティを一度でセットあるいは取得できるメソッドを追加する。

メディア サンプルは IMediaSample2 のサポートを保証していない。しかしアロケータが IMediaSample2 をサポートするサンプルを作成すれば、それがサポートするすべてのサンプルはそのインターフェイスをサポートしなければならない。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IMediaSample メソッド | 説明
GetPointer | このバッファのメモリへの読み取り/書き込みポインタを取得する。
GetSize | バッファのサイズを取得する。
GetTime | このサンプルが開始および終了すべきストリーム タイムを取得する。
SetTime | このサンプルが開始および終了すべきストリーム タイムを設定する。
IsSyncPoint | サンプルの始まりが同期ポイントかどうかを判断する。
SetSyncPoint | このサンプルの開始が同期ポイントかどうかを指定する。
IsPreroll | このサンプルがプリロール サンプルかどうかを確認する。
SetPreroll | このサンプルがプリロール サンプルかどうかを設定する。
GetActualDataLength | バッファ内の有効なデータの長さを取得する。
SetActualDataLength | バッファ内の有効なデータの長さを設定する。
GetMediaType | メディア タイプが以前のサンプルと異なるなら、メディア タイプを取得する。
SetMediaType | サンプルのメディア タイプを設定する。
IsDiscontinuity | このサンプルがデータ ストリーム内でブレークを表示するかどうかを確認する。
SetDiscontinuity | このサンプルがデータ ストリーム内でブレークを表示するかどうかを指定する。
GetMediaTime | このサンプルのメディア タイムを取得する。
SetMediaTime | このサンプルのメディア タイムを設定する。 定する。
IMediaSample2 メソッド | 説明
GetProperties | メディア サンプルのプロパティを取得する。
SetProperties | メディア サンプルのプロパティを設定する。

IMediaSample2::GetProperties

IMediaSample2 インターフェイス

メディア サンプルのプロパティを取得する。

構文

HRESULT GetProperties(
    DWORD cbProperties,
    BYTE *pbProperties
    );

パラメータ

cbProperties
[in] 取得するプロパティ データの長さ (バイト単位)。
pbProperties
[out] cbProperties サイズのバッファへのポインタ。

戻り値

HRESULT 値を返す。以下のいずれかの値。

S_OK | 成功。
E_POINTER | NULL ポインタ引数。

注意

受け取ったデータは AM_SAMPLE2_PROPERTIES 構造体のフォーマットに従う。cbProperties を AM_SAMPLE2_PROPERTIES 構造体のサイズより小さい値にセットすれば、サンプル プロパティのサブセットを取得することができる。

効率のため、AM_SAMPLE2_PROPERTIES に返る pMediaType メンバはメディア サンプルにストアされているデータのポインタであり、そのデータのコピーではない。サンプルが他のフィルタに渡された後、あるいは入力ピンの IMemInputPin::Receive メソッドが完了した後では、そのポインタは無効となる可能性がある。またメディア タイプを解放あるいは削除してはならない。

IMediaSample2::SetProperties

IMediaSample2 インターフェイス

メディア サンプルのプロパティを設定する。

構文

HRESULT SetProperties(
    DWORD cbProperties,
    const BYTE *pbProperties
    );

パラメータ

cbProperties
[in] 設定するプロパティ データの長さ (バイト単位)。
pbProperties
[in] cbProperties サイズのバッファへのポインタ。

戻り値

HRESULT 値を返す。以下のいずれかの値。

S_OK | 成功。
E_INVALIDARG | 不適切な引数。
E_OUTOFMEMORY | メモリ不足。
E_POINTER | NULL ポインタ引数。

注意

pbProperties 内に入るデータは AM_SAMPLE2_PROPERTIES 構造体のフォーマットに従わなければならない。cbProperties を AM_SAMPLE2_PROPERTIES 構造体のサイズより小さい値にセットすれば、サンプル プロパティのサブセットを指定することができる。


IMediaSeeking インターフェイス

ストリーム内の位置にシークするメソッドと、再生レートを設定するメソッドが含まれる。

フィルタ グラフ マネージャは、個々のフィルタと同じように、このインターフェイスを公開する。アプリケーションはフィルタからではなく、フィルタ グラフ マネージャからこのインターフェイスを取得する必要がある。フィルタ グラフ マネージャは、メソッドをすべてのレンダリング フィルタに割り当てる。レンダリング フィルタは、その呼び出しをソース フィルタへのアップストリームに送る。すべてのストリームは、イベントのこのシーケンスによって同期される。

配布されたいずれかの呼び出しがエラーを返した場合、フィルタ グラフ マネージャは、配布された呼び出しの一部が成功した場合でも、最初に受け取ったエラー値を返す。この例外には、E_NOTIMPL がある。フィルタ グラフ マネージャは、配布されたすべての呼び出しが E_NOTIMPL を返さない限り、E_NOTIMPL を返さない。

グラフがどの状態 (実行中、ポーズ、停止中) にあっても、アプリケーションはグラフをシークできる。グラフが実行中の場合、フィルタ グラフ マネージャはシークコマンドを処理する前にグラフをポーズする。その後、グラフを再度実行状態にする。すべてのシーク操作は、現在の再生レートには依存しない。シーク操作によって残っているメディア データは、グラフからフラッシュされる。

このインターフェイスは、IMediaPosition インターフェイスよりも強化されている。IMediaPosition のメソッドでは、コンマ秒単位のタイム パラメータを必要とするのに対して、IMediaSeeking メソッドでは、フレーム、バイト、100 ナノ秒単位など任意のフォーマットを使用できる。また、IMediaSeeking はより高い精度を提供するために、64 ビット整数 (LONGLONG) を使用する。一方、IMediaSeeking は Automation と互換性がないので、Microsoft® Visual Basic® で書かれたアプリケーションは IMediaPosition を使用しなければならない。

タイムおよびタイムの単位を指定する IMediaSeeking のすべてのパラメータは、現在使用中のタイム フォーマットには依存しない。タイム フォーマットを設定するには、IMediaSeeking::SetTimeFormat を呼び出す。タイム フォーマットは、uuids.h で定義されているグローバルに一意の識別子 (GUID) である。詳細については、「タイム フォーマット GUID」を参照すること。

Vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IMediaSeeking メソッド | 説明
GetCapabilities | ストリームのすべてのシーク能力を取得する。
CheckCapabilities | 指定したシーク能力をストリームが持っているかどうかを照会する。
IsFormatSupported | 指定したタイム フォーマットをストリームがサポートしているかどうかを確認する。
QueryPreferredFormat | ストリームの優先タイム フォーマットを取得する。
GetTimeFormat | 現在のタイム フォーマットを取得する。
IsUsingTimeFormat | 指定したタイム フォーマットが現在使用中のフォーマットかどうかを確認する。
SetTimeFormat | タイム フォーマットを設定する。
GetDuration | ストリームの時間幅を取得する。
GetStopPosition | ストリームの時間幅に対して、再生が停止するタイムを取得する。
GetCurrentPosition | ストリームの時間幅に対する現在の位置を取得する。
ConvertTimeFormat | あるタイム フォーマットをほかのフォーマットに変換する。
SetPositions | 現在の位置と停止位置を設定する。
GetPositions | ストリームの時間幅に対する、現在の位置と停止位置を取得する。
GetAvailable | シークが有効なタイムの範囲を取得する。
SetRate | 再生レートを設定する。
GetRate | 再生レートを取得する。
GetPreroll | 開始位置の前にキューに入っているデータの量を取得する。

IMediaSeeking::CheckCapabilities

IMediaSeeking インターフェイス

指定したシーク能力をストリームが持っているかどうかを照会する。

構文

HRESULT CheckCapabilities(
    DWORD *pCapabilities
);

パラメータ

pCapabilities
[in, out] AM_SEEKING_SEEKING_CAPABILITIES 属性の 1 つまたは複数のビットごとの組み合わせへのポインタ。メソッドの戻り値は、どの属性が利用可能であるかを示す。

戻り値

HRESULT 値を返す。次の可能な値がある。

S_FALSE | pCapabilities のすべての能力を持ってはいない。
S_OK | pCapabilities のすべての能力がある。
E_FAIL | pCapabilities の能力がまったくない。
E_POINTER | NULL ポインタ引数。

注意

2 ～ 3 の能力だけが必要な場合、すべてのストリームのシーク能力をチェックする GetCapabilities を呼び出すよりも、このメソッドの方が効率的である。

テストする AM_SEEKING_SEEKING_CAPABILITIES 属性のビットごとの OR 組み合わせと等しい DWORD を宣言し、pCapabilities パラメータにこの値のポインタを渡す。メソッドが返ると、pCapabilities には元のビットのサブセットが入り、実際にどの能力があるかを示す。戻り値は、要求した能力がない、いくつかある、またはすべてあることを示す値を返す。

次のコード サンプルは、ストリームが順方向シーク、逆方向シーク、および絶対シークをサポートしているかどうかを調べる方法を示している。

// チェックする能力のフラグを設定する。
DWORD dwCaps = AM_SEEKING_CanSeekAbsolute |
             AM_SEEKING_CanSeekForwards |
             AM_SEEKING_CanSeekBackwards;

HRESULT hr = pMediaSeeking->CheckCapabilities(&dwCaps);
if(FAILED(hr))
{
    // ストリームではシークはできない。
}
else if (hr == S_OK)
{
    // ストリームでは、順方向シーク、逆方向シーク、および絶対シークができる。
}
else if (hr == S_FALSE) // ストリームはいくつかの能力を持つ可能性がある。
{
    if (dwCaps & AM_SEEKING_CanSeekAbsolute)
        // ストリームは絶対位置へのシークができる。
    if dwCaps & AM_SEEKING_CanSeekAbsolute)
        // ストリームは順方向へのシークができる。
    if (dwCaps & AM_SEEKING_CanSeekBackwards)
        // ストリームは逆方向へのシークができる。
}

IMediaSeeking::ConvertTimeFormat

IMediaSeeking インターフェイス

あるタイム フォーマットをほかのフォーマットに変換する。

構文

HRESULT ConvertTimeFormat(
    LONGLONG *pTarget,
    const GUID *pTargetFormat,
    LONGLONG Source,
    const GUID *pSourceFormat
);

パラメータ

pTarget
[out] 変換したタイム値を受け取る変数へのポインタ。
pTargetFormat
[in] 目的のフォーマットのタイム フォーマット GUID へのポインタ。NULL の場合は、現在のフォーマットが使われる。
Source
[in] 変換されるタイム値。
pSourceFormat
[in] 変換するフォーマットのタイム フォーマット GUID へのポインタ。NULL の場合は、現在のタイム フォーマットが使われる。

戻り値

HRESULT 値を返す。次の可能な値がある。

S_OK | 成功。
E_INVALIDARG | このタイプ間の変換はサポートされていない。
E_NOTIMPL | メソッドはサポートされていない。
E_POINTER | NULL ポインタ引数。

IMediaSeeking::GetAvailable

IMediaSeeking インターフェイス

シークが有効なタイムの範囲を取得する。

構文

HRESULT GetAvailable(
    LONGLONG *pEarliest,
    LONGLONG *pLatest
);

パラメータ

pEarliest
[out] シークが有効な、最も早いタイムを受け取る変数へのポインタ。
pLatest
[out] シークが有効な、最も遅いタイムを受け取る変数へのポインタ。

戻り値

HRESULT 値を返す。次の可能な値がある。

S_OK | 成功。
E_NOTIMPL | メソッドはサポートされていない。
E_POINTER | NULL ポインタ引数。

注意

このメソッドは、主にネットワークを越えて送られてくるような、遅延の大きなメディア ストリームでのシークを対象としている。戻り値は、容易にシーク可能な、既に到着済みのキャッシュ データを表す。返されたパラメータを超えた値をシークすると、アプリケーションがデータの到着を待つ間、遅延が発生することが想定されている。

IMediaSeeking::GetCapabilities

IMediaSeeking インターフェイス

ストリームのすべてのシーク能力を取得する。

構文

HRESULT GetCapabilities(
    DWORD *pCapabilities
);

パラメータ

pCapabilities
[out] AM_SEEKING_SEEKING_CAPABILITIES フラグのビットごとの組み合わせを受け取る変数へのポインタ。

戻り値

HRESULT 値を返す。次の可能な値がある。

S_OK | 成功。
E_POINTER | NULL ポインタ引数。

注意

このメソッドは、ストリームのすべてのシーク能力に関する情報を返す。必要な AM_SEEKING_SEEKING_CAPABILITIES 値について、ビットごとの AND 操作を行い、pCapabilities を調べること。

DWORD dwCaps = 0;
pMediaSeeking->GetCapabilities(&dwCaps);

if (dwCaps & AM_SEEKING_CanGetCurrentPos)
{
    // ストリームでは現在位置へのシークができる。
}
if (dwCaps & AM_SEEKING_CanPlayBackwards)
{
    // ストリームでは再生逆方向へのシークができる。
}

IMediaSeeking::GetCurrentPosition

IMediaSeeking インターフェイス

ストリームの合計時間幅に対する現在の位置を取得する。

構文

HRESULT GetCurrentPosition(
    LONGLONG *pCurrent
);

パラメータ

pCurrent
[out] 現在位置を取得する変数へのポインタ (現在のタイム フォーマットの単位)。

戻り値

HRESULT 値を返す。次の可能な値がある。

S_OK | 成功。
E_NOTIMPL | メソッドはサポートされていない。
E_POINTER | NULL ポインタ引数。

注意

このメソッドは、再生が到達した現在位置を返す。この値では、再生レートと開始タイムは無視される。たとえば、レートに 2.0 を設定し、開始タイムが 5 秒だとすると、グラフを 4 秒実行すると現在の位置は 9.0 秒となる (5 + 4 × 2.0)。戻り値は、現在のタイム フォーマットの単位で表される。現在のタイム フォーマットを確認するには、GetTimeFormat メソッドを呼び出すこと。

グラフがポーズまたは停止されている場合、現在位置は再生が再開されるポイントとなる。

フィルタ グラフ マネージャは、現在のストリーム タイムから位置を計算するので、グラフのフィルタに照会することはない。ファイルの再生では、これによって再生がストリーム タイムに同期されるため、正確な結果が得られる。ファイルの書き込みでは、結果は正確にはならない。ファイルを書き込むグラフで現在の位置を取得するには、マルチプレクサ フィルタに照会すること。ただし、ライブ キャプチャでは、位置は適切なものとはならない。

IMediaSeeking::GetDuration

IMediaSeeking インターフェイス

ストリームの時間幅を取得する。

構文

HRESULT GetDuration(
    LONGLONG *pDuration
);

パラメータ

pDuration
[out] 時間幅を受け取る変数へのポインタ (現在のタイム フォーマットの単位)。

戻り値

HRESULT 値を返す。次の可能な値がある。

S_OK | 成功。
E_NOTIMPL | メソッドはサポートされていない。
E_POINTER | NULL ポインタ引数。

注意

このメソッドは、通常、再生速度での時間幅を取得する。再生レートはこの時間幅には影響を与えない。戻り値は現在のタイム フォーマット単位で表される。現在のタイム フォーマットを確認するには、GetTimeFormat メソッドを呼び出すこと。

IMediaSeeking::GetPositions

IMediaSeeking インターフェイス

ストリームの合計時間幅に対する、現在の位置と停止位置を取得する。

構文

HRESULT GetPositions(
    LONGLONG *pCurrent,
    LONGLONG *pStop
);

パラメータ

pCurrent
[out] 現在位置を受け取る変数へのポインタ (現在のタイム フォーマットの単位)。
pStop
[out] 停止位置を受け取る変数へのポインタ (現在のタイム フォーマットの単位)。

戻り値

HRESULT 値を返す。次の可能な値がある。

S_OK | 成功。
E_NOTIMPL | メソッドはサポートされていない。
E_POINTER | NULL ポインタ引数。

注意

現在位置と停止位置は、両方とも元のストリームに対する値であり、再生レートには依存しない。

戻り値は、現在のタイム フォーマット単位で表される。現在のタイム フォーマットを確認するには、GetTimeFormat メソッドを呼び出すこと。

IMediaSeeking::GetPreroll

IMediaSeeking インターフェイス

開始位置の前にキューに入っているデータの量を取得する。

構文

HRESULT GetPreroll(
    LONGLONG *pllPreroll
);

パラメータ

pllPreroll
[out] プリロール タイムを受け取る変数へのポインタ (現在のタイム フォーマットの単位)。

戻り値

HRESULT 値を返す。次の可能な値がある。

S_OK | 成功。
E_NOTIMPL | メソッドはサポートされていない。
E_POINTER | NULL ポインタ引数。

注意

プリロールは、テープ プレーヤーのような非ランダム アクセス デバイスで、ローリングが開始される開始位置より前のタイムである。

IMediaSeeking::GetRate

IMediaSeeking インターフェイス

再生レートを取得する。

構文

HRESULT GetRate(
    double *dRate
);

パラメータ

dRate
[out] 再生レートを受け取る変数へのポインタ。

戻り値

HRESULT 値を返す。次の可能な値がある。

S_OK | 成功。
E_NOTIMPL | メソッドはサポートされていない。
E_POINTER | NULL ポインタ引数。

注意

再生レートは、通常、速度との比率で表される。したがって、1.0 は通常の再生速度、0.5 は半分の速度、2.0 は 2 倍の速度を示す。

IMediaSeeking::GetStopPosition

IMediaSeeking インターフェイス

ストリームの時間幅に対して、再生が停止するタイムを取得する。

構文

HRESULT GetStopPosition(
    LONGLONG *pStop
);

パラメータ

pStop
[out] 停止位置を受け取る変数へのポインタ (現在のタイム フォーマットの単位)。

戻り値

HRESULT 値を返す。次の可能な値がある。

S_OK | 成功。
E_NOTIMPL | メソッドはサポートされていない。
E_POINTER | NULL ポインタ引数。

注意

再生レートは、このメソッドによって返る値に影響を与えない。戻り値は、現在のタイム フォーマット単位で表される。現在のタイム フォーマットを確認するには、GetTimeFormat メソッドを呼び出すこと。

IMediaSeeking::GetTimeFormat

IMediaSeeking インターフェイス

現在のタイム フォーマットを取得する。

構文

HRESULT GetTimeFormat(
    GUID *pFormat
);

パラメータ

pFormat
[out] タイム フォーマット GUID を受け取る変数へのポインタ。

戻り値

HRESULT 値を返す。次の可能な値がある。

S_OK | 成功。
E_POINTER | NULL ポインタ引数。

IMediaSeeking::IsFormatSupported

IMediaSeeking インターフェイス

指定したタイム フォーマットをストリームがサポートしているかどうかを確認する。

構文

HRESULT IsFormatSupported(
    const GUID *pFormat
);

パラメータ

pFormat
[in] タイム フォーマット GUID へのポインタ。

戻り値

HRESULT 値を返す。次の可能な値がある。

S_FALSE | フォーマットはサポートされていない。
S_OK | フォーマットはサポートされている。
E_NOTIMPL | 実装されていない。
E_POINTER | NULL ポインタ引数。

IMediaSeeking::IsUsingTimeFormat

IMediaSeeking インターフェイス

指定したタイム フォーマットが現在使用中のフォーマットかどうかを確認する。

構文

HRESULT IsUsingTimeFormat(
    const GUID *pFormat
);

パラメータ

pFormat
[in] タイム フォーマット GUID へのポインタ。

戻り値

HRESULT 値を返す。次の可能な値がある。

S_FALSE | 指定したフォーマットは現在のフォーマットではない。
S_OK | 指定したフォーマットは現在のフォーマットである。
E_NOTIMPL | 実装されていない。
E_POINTER | NULL ポインタ引数。

注意

このメソッドは GUID をコピーする必要がないため、IMediaSeeking::GetTimeFormat メソッドよりも効率的である。

IMediaSeeking::QueryPreferredFormat

IMediaSeeking インターフェイス

ストリームの優先タイム フォーマットを取得する。

構文

HRESULT QueryPreferredFormat(
    GUID *pFormat
);

パラメータ

pFormat
[out] タイム フォーマット GUID へのポインタ。

戻り値

HRESULT 値を返す。次の可能な値がある。

S_OK | 成功。
E_NOTIMPL | 実装されていない。
E_POINTER | NULL ポインタ引数。

注意

返されたフォーマットが不十分な場合は、IsFormatSupported メソッドを呼び出して、ほかにサポートされているタイム フォーマットを照会すること。

IMediaSeeking::SetPositions

IMediaSeeking インターフェイス

現在の位置と停止位置を設定する。

構文

HRESULT SetPositions(
    LONGLONG *pCurrent,
    DWORD dwCurrentFlags,
    LONGLONG *pStop,
    DWORD dwStopFlags
);

パラメータ

pCurrent
[in,out] 現在のタイムを指定する変数へのポインタ (現在のタイム フォーマットの単位)。
dwCurrentFlags
[in] フラグのビットごとの組み合わせ (「注意」を参照)。
pStop
[in,out] 現在のタイムを指定する変数へのポインタ (現在のタイム フォーマットの単位)。
dwStopFlags
[in] フラグのビットごとの組み合わせ (「注意」を参照)。

戻り値

HRESULT 値を返す。次の可能な値がある。

S_FALSE | 位置変更はない(両方のフラグがシークしないと指定)。
S_OK | 成功。
E_INVALIDARG | 不適切な引数。
E_NOTIMPL | メソッドはサポートされていない。
E_POINTER | NULL ポインタ引数。

注意

dwCurrentFlags パラメータと dwStopFlags パラメータには、シーク タイプを定義する。次のフラグが定義されている。

位置フラグ
AM_SEEKING_NoPositioning | 位置の変更はない。タイム パラメータは、NULL とすることもできる。
AM_SEEKING_AbsolutePositioning | 指定した位置は絶対値である。
AM_SEEKING_RelativePositioning | 指定した位置は以前の値からの相対値である。
AM_SEEKING_IncrementalPositioning | 停止位置 (pStop) は現在位置 (pCurrent) からの相対値である。
修飾フラグ
AM_SEEKING_SeekToKeyFrame | 最も近いキーフレームをシークする。これは高速だが、精度は落ちる。
AM_SEEKING_ReturnTime | 等しい基準タイムを返す。
AM_SEEKING_Segment | セグメント シークを使用する。
AM_SEEKING_NoFlush | フラッシュしない。

各パラメータに対して、1 つの位置フラグを使用する。1 つまたは複数の修飾子フラグを含めることもできる。

AM_SEEKING_ReturnTime フラグが指定されると、メソッドはその位置の値を基準タイムに変換し、pCurrent 変数または pStop 変数で返す。フレームのような別のタイムフォーマットを使っているときに、このフラグは有用である。

AM_SEEKING_Segment と AM_SEEKING_NoFlush フラグは、シームレス ループをサポートする。

  • AM_SEEKING_Segment が存在する場合、ソースフィルタは停止位置に到達したときに、IPin::EndOfStream を呼び出す代わりに EC_END_OF_SEGMENT イベントを送る。アプリケーションはこのイベントを待って、もう 1 つのシーク コマンドを処理することができる。
  • AM_SEEKING_NoFlush が存在する場合、グラフはシーク中にデータをフラッシュしない。このフラグは AM_SEEKING_Segment と共に使用する。

ループを実行するためには、グラフは GetCapabilities メソッドの AM_SEEKING_CanDoSegments を報告しなければならない。現在、この機能をサポートしているのは WAVE パーサー フィルタだけである。

IMediaSeeking::SetRate

IMediaSeeking インターフェイス

再生レートを設定する。

構文

HRESULT SetRate(
    double dRate
);

パラメータ

dRate
[in] 再生レート。ゼロであってはならない。

戻り値

HRESULT 値を返す。次の可能な値がある。

S_OK | 成功。
E_INVALIDARG | 指定されたレートは、0 または負の値であった (「注意」を参照)。
E_NOTIMPL | 実装されていない。
E_POINTER | NULL ポインタ引数。
VFW_E_UNSUPPORTED_AUDIO | オーディオ デバイスあるいはフィルタがこのレートをサポートしていない。

注意

再生レートは、通常、速度との比率で表される。したがって、1.0 は通常の再生速度、0.5 は半分の速度、2.0 は 2 倍の速度を示す。オーディオ ストリームについては、レートを変えるとピッチも変わる。

マイナス値は逆再生を示す。大部分のフィルタは逆再生をサポートしない、代わりに dRate パラメータがマイナスだとエラーコードを返す。

アプリケーションがこのメソッドをフィルタ グラフ マネージャで呼び出すと、フィルタ グラフ マネージャは以下の事を行う :

  1. GetCurrentPosition メソッドを呼び出す。この呼び出しによってフィルタ グラフ マネージャが計算した現在位置を返す。
  2. (グラフがポーズあるいは実行中なら) フィルタ グラフを停止する。
  3. 現在位置を開始タイムとして、SetPositions メソッドを呼び出す。これはストリームタイムをゼロにリセットする結果となる。
  4. 新しいレートで、フィルタの SetRate メソッドを呼び出す。
  5. ポーズあるいは実行中だったなら、フィルタグラフを再開する。

ステップ 4 でエラーが起きると、フィルタ グラフ マネージャは以前のレートを再び使おうとする。

フィルタは以下のようにレート変更に対応すべきだ :

パーサー フィルタとソース フィルタ : タイム スタンプを発生させているフィルタは SetRate 呼び出しに対応しなければならない。通常これは AVI スプリッタ のようなパーサー フィルタであるが、ソース フィルタの場合もある。シークやレート変更の後、フィルタは IPin::NewSegment メソッドを新しい設定で呼び出すべきである。レート変更の後、そのタイム スタンプをそれに従って調整すべきだ。レート変更はシークに優先するので、タイム スタンプはゼロから再スタートとなる、従ってフィルタはそのレートで割った新しいタイム スタンプを計算することができる。

デコーダ フィルタ : デコーダは SetRate 呼び出しに対して、それらをアップストリームに渡す以外のことをすべきではない。そうではなく、デコーダはアップストリーム パーサーが出す NewSegment 呼び出しに対応すべきである。デコーダ フィルタが新しいセグメント情報を受け取るとき、そのフィルタはその値を保存して、NewSegment 呼び出しダウンストリームに渡す。いくつかのデコーダはその入力を補間することによって追加タイム スタンプを生成する必要がある、そうするときアカウント内にレート変更を渡すべきである。

レンダラ : ビデオ レンダラは通常レート変更を無視できる、なぜなら入ってくるフレームは既に正しいタイム スタンプを持っているからだ。オーディオ レンダラはその再生レートを変更しなければならない、なぜならオーディオ デコーダは通常レート変更変換をしないからである。

IMediaSeeking::SetTimeFormat

IMediaSeeking インターフェイス

タイム フォーマットを設定する。

構文

HRESULT SetTimeFormat(
    const GUID *pFormat
);

パラメータ

pFormat
[in] タイム フォーマット GUID へのポインタ。

戻り値

HRESULT 値を返す。次の可能な値がある。

S_OK | 成功。
E_INVALIDARG | 不適切な引数。
E_NOTIMPL | メソッドはサポートされていない。
E_POINTER | NULL ポインタ引数。
VFW_E_WRONG_STATE | フィルタ グラフが停止していない。

注意

このメソッドは、GetPositions や SetPositions など、ほかの IMediaSeeking メソッドを使ってタイムの単位を指定する。どのフォーマットがサポートされているかを確認するには、IsFormatSupported メソッドを呼び出すこと。現在のタイム フォーマットを取得するには、GetTimeFormat メソッドを呼び出し、優先タイム フォーマットを取得するには、QueryPreferredFormat メソッドを呼び出すこと。

フィルタ グラフには、一度に 1 つのタイム フォーマットしか設定できない。


IMediaTypeInfo インターフェイス

このインターフェイスは、ピン接続のメディア タイプを取得する Automation 互換のメソッドを提供する。

Microsoft® Visual Basic® アプリケーションでは、このインターフェイスを使用して、ピン接続のメディア タイプを取得できる。IPinInfo::get_ConnectionMediaType メソッドは、このインターフェイスをサポートするオブジェクトを返す。メジャー タイプ GUID およびマイナー タイプ GUID は、このオブジェクトのプロパティとして取得される。

C/C++ アプリケーションでは、このメソッドではなく、IPin::ConnectionMediaType メソッドを呼び出すこと。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IDispatch メソッド | 説明
GetTypeInfoCount | このディスプインターフェイスに利用可能なタイプ情報があるかどうか判断する。
GetTypeInfo | GetTypeInfoCount が成功した場合は、このディスプインターフェイスのタイプ情報を取得する。
GetIDsOfNames | (引数を含む) プロパティおよびメソッドのテキスト名を対応する DISPID に変換する。
Invoke | DISPID およびその他の必要なパラメータが指定された場合は、このディスプインターフェイスのメソッドを呼び出すか、またはプロパティにアクセスする。
IMediaTypeInfo メソッド | 説明
get_Type | GUID を文字列で取得する。
get_Subtype | サブタイプ GUID を文字列で取得する。

IMediaTypeInfo::get_Subtype

IMediaTypeInfo インターフェイス

サブタイプ GUID を文字列で取得する。

構文

HRESULT get_Subtype(
    BSTR *strType
);

パラメータ

strType
[out, retval] サブタイプ GUID が格納された文字列へのポインタ。

戻り値

HRESULT 値を返す。

IMediaTypeInfo::get_Type

IMediaTypeInfo インターフェイス

メジャー タイプ GUID を文字列で取得する。

構文

HRESULT get_Type(
    BSTR *strType
);

パラメータ

strType
[out, retval] メジャー タイプ GUID が格納された文字列へのポインタ。

戻り値

HRESULT 値を返す。


IMemAllocator インターフェイス

ピン間でデータを移動させるために、メディア サンプルを割り当てる。

入力ピンが IMemInputPin インターフェイスを公開するとき、アロケータを共有するピンによってこのインターフェイスは使われる。そのピンはどのピンがアロケータを提供するかをネゴシエートする。アロケータを使って、メモリ バッファを割り当て、からのバッファを取得し、バッファを解放する。すべてのフィルタがそれ自身のアロケータを作成するわけではないので、1 つのアロケータを複数のフィルタが使用する場合もある。詳細については、「フィルタの接続」を参照すること。

アプリケーションは通常このインターフェイスを使わない。

アロケータを使うには次のステップを行う。

  1. IMemAllocator::SetProperties メソッドを呼び出して、バッファの数と各バッファのサイズを含むバッファ要求を指定する。
  2. IMemAllocator::Commit メソッドを呼び出して、バッファを割り当てる。
  3. Call IMemAllocator::GetBuffer メソッドを呼び出して、メディア サンプルを取得する。このメソッドは次のサンプルが有効になるまでブロックする。
  4. 各サンプルについて終了したとき、サンプルで IUnknown::Release メソッドを呼び出す。サンプルはその参照カウントがゼロになっても削除されない。代わりに、サンプルはアロケータのフリー リストを返す。
  5. そのアロケータの使用が終わったとき、IMemAllocator::Decommit メソッドを呼び出してバッファ用のメモリを解放する。

Vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IMemAllocator メソッド | 説明
SetProperties | 割り当てるバッファの数と各バッファのサイズを指定する。
GetProperties | アロケータが作成するバッファの数とバッファのプロパティを取得する。
Commit | バッファ メモリを割り当てる。
Decommit | バッファ用のメモリを解放する。
GetBuffer | カラのバッファを持つメディアサンプルを取得する。
ReleaseBuffer | メディア サンプルを解放する。

IMemAllocator::Commit

IMemAllocator インターフェイス

バッファ メモリを割り当てる。

構文

HRESULT Commit(void);

戻り値

HRESULT 値を返す。以下の表に示されるいずれかの値。

S_OK | 成功。
E_OUTOFMEMORY | メモリ不足。
VFW_E_SIZENOTSET | バッファ要求はセットされなかった。

注意

このメソッドを呼び出す前に、IMemAllocator::SetProperties メソッドを呼び出してバッファ要求を指定すること。

IMemAllocator::GetBuffer メソッドを呼び出す前に、必ずこのメソッドを呼び出すこと。

IMemAllocator::Decommit

IMemAllocator インターフェイス

バッファ用のメモリを解放する。

構文

HRESULT Decommit(void);

戻り値

成功なら S_OK を返す、あるいはエラーの原因を示す HRESULT 値を返す。

注意

IMemAllocator::GetBuffer メソッドで待っているスレッドはエラーを返す。IMemAllocator::Commit メソッドが呼び出されるまでは、以降の GetBuffer への呼び出しは失敗する。

IMemAllocator::GetBuffer

IMemAllocator インターフェイス

カラのバッファを持つメディアサンプルを取得する。

構文

HRESULT GetBuffer(
    IMediaSample **ppBuffer,
    REFERENCE_TIME *pStartTime,
    REFERENCE_TIME *pEndTime,
    DWORD dwFlags
);

パラメータ

ppBuffer
[out] バッファの IMediaSample インターフェイスへのポインタを受け取る変数のアドレス。
pStartTime
[in] サンプルの開始タイムへのポインタ、あるいは NULL 。
pEndTime
[in] サンプルの終了タイムへのポインタ、あるいは NULL 。
dwFlags
[in] ゼロあるいはそれ以上のフラグの組み合わせ。
  • AM_GBF_NOTASYNCPOINT: このサンプルは同期ポイントではない。このサンプルには動的なフォーマット変更は許可されない。
  • AM_GBF_PREVFRAMESKIPPED: このサンプルは不連続後の最初である。(ビデオ レンダラのみがこのフラグを使う)
  • AM_GBF_NOWAIT: バッファが有効になるのを待つべきではない。

戻り値

HRESULT 値を返す。以下の表に示されるいずれかの値。

S_OK | 成功。
VFW_E_NOT_COMMITTED | アロケータはデコミットである。
VFW_E_TIMEOUT | タイム アウト。

注意

デフォルトでは、このメソッドはフリー サンプルが利用できるまで、あるいはアロケータがデコミットになるまでブロックする。呼び出し元が AM_GBF_NOWAIT フラグを指定し、サンプルが利用できないなら、アロケータは VFW_E_TIMEOUT 値を戻してすぐに返る。しかし、アロケータによるこのフラグのサポートは必須ではない。

ppBuffer で返るサンプルは利用可能なバッファポインタを持つ。呼び出し元はサンプルの他のプロパティを設定する責任がある、それはたとえばタイム スタンプやメディア タイムや同期ポイント プロパティなどである (詳細については、「IMediaSample」を参照すること)。

pStartTime パラメータと pEndTime パラメータはサンプルに適用されない。アロケータはこれらの値を使ってどのバッファを取得したかを確認する場合がある。たとえば、ビデオ レンダラ フィルタはこれらの値を使って Microsoft® DirectDraw® サーフェイスとの同期をスイッチする。サンプルのタイム スタンプを設定するには IMediaSample::SetTime メソッドを呼び出すこと。

このメソッドを呼び出す前に IMemAllocator::Commit メソッドを必ず呼び出さなければならない。IMemAllocator::Decommit メソッドが呼び出された後ではこの呼び出しは失敗する。メソッドが成功すると、IMediaSample インターフェイスには参照カウントが残る。使用したときインターフェイスの解放に注意。

IMemAllocator::GetProperties

IMemAllocator インターフェイス

アロケータが作成するバッファの数とバッファのプロパティを取得する。

構文

HRESULT GetProperties(
    ALLOCATOR_PROPERTIES *pProps
);

パラメータ

pProps
[out] アロケータ プロパティを受け取る ALLOCATOR_PROPERTIES 構造体へのポインタ。

戻り値

成功なら S_OK を返す、あるいはエラーの原因を示す HRESULT 値を返す。

注意

IMemAllocator::Commit メソッドが呼び出されるまで、このメソッドへの呼び出しは成功しない場合がある。

IMemAllocator::ReleaseBuffer

IMemAllocator インターフェイス

メディア サンプルを解放する。

構文

HRESULT ReleaseBuffer(
    IMediaSample *pBuffer
);

パラメータ

pBuffer
[in] メディア サンプルの IMediaSample インターフェイスへのポインタ。

戻り値

成功なら S_OK を返す、あるいはエラーの原因を示す HRESULT 値を返す。

注意

メディア サンプルの参照カウントがゼロになると、このメソッドは pBuffer にそれ自身を入れて呼び出す。このメソッドはサンプルを解放して、アロケータの利用可能なサンプルのリストに戻す。

IMemAllocator::SetProperties

IMemAllocator インターフェイス

割り当てるバッファの数と各バッファのサイズを指定する。

構文

HRESULT SetProperties(
    ALLOCATOR_PROPERTIES *pRequest,
    ALLOCATOR_PROPERTIES *pActual
);

パラメータ

pRequest
バッファ要求が入る ALLOCATOR_PROPERTIES 構造体へのポインタ。
pActual
実際のバッファプロパティを受け取る ALLOCATOR_PROPERTIES 構造体へのポインタ。

戻り値

HRESULT 値を返す。以下の表に示されるいずれかの値。

S_OK | 成功。
E_POINTER | NULL ポインタ引数。
VFW_E_ALREADY_COMMITTED | フィルタがアクティブな間は割り当てたメモリを変更することはできない。
VFW_E_BADALIGN | 不適切な引数が指定された。
VFW_E_BUFFERS_OUTSTANDING | 1 つ以上のバッファがまだアクティブ。

注意

このメソッドはバッファ要求を指定するが、バッファを割り当てるわけではない。IMemAllocator::Commit メソッドを呼び出してバッファを割り当てること。

呼び出し元は 2 つの ALLOCATOR_PROPERTIES 構造体を割り当てる。pRequest パラメータにはバッファの数と各バッファのサイズを含む呼び出し元のバッファ要求が入る。メソッドが返ると、pActual パラメータにはアロケータによってセットされた実際のバッファ プロパティが入る。

このメソッドが呼び出されるとき、アロケータはコミットされていなければならない、あるいは利用可能なバッファを持っていなければならない。


IMemInputPin インターフェイス

メディア データを入力ピンに出力する。入力ピンが IMemAllocator インターフェイスを使ってバッファを割り当てる場合、入力ピンはこのインターフェイスを公開する。出力ピンが入力ピンに接続すると、出力ピンはこのインターフェイスを使ってアロケータ要求をネゴシエーションし、入力ピンにサンプルを出力する。

通常、アプリケーションはこのインターフェイスを使用する。

フィルタ開発者へ : CBaseInputPin クラスはこのインターフェイスを実装する。

Vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタ。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IMemInputPin メソッド | 説明
GetAllocator | このピンが提案したメモリ アロケータを取得する。
NotifyAllocator | 接続用のアロケータを指定する。
GetAllocatorRequirements | 入力ピンが要求したアロケータ プロパティを取得する。
Receive | ストリーム内の次のメディア サンプルを取得する。
ReceiveMultiple | ストリーム内の複数のサンプルを取得する。
ReceiveCanBlock | Receive メソッドへの呼び出しがブロックになるかどうかを確認する。

IMemInputPin::GetAllocator

IMemInputPin インターフェイス

このピンが提案したメモリ アロケータを取得する。

構文

HRESULT GetAllocator(
IMemAllocator **ppAllocator
);

パラメータ

ppAllocator
[out] アロケータの IMemAllocator インターフェイスへのポインタを受け取る変数のアドレス。

戻り値

HRESULT 値を返す。以下の表に示されるいずれかの値。

S_OK | 成功。
VFW_E_NO_ALLOCATOR | 利用可能なアロケータがない。

注意

出力ピンは入力ピンと接続するとき、入力ピンにメモリ アロケータを決めるようネゴシエーションする。出力ピンはこのメソッドを呼び出して入力ピンの提案したアロケータを取得する。それは NotifyAllocator メソッドを呼び出しどのアロケータがそれを選択したのかを指定する。

このメソッドが成功すると、IMemAllocator インターフェイスには参照カウントが残る。使用後、解放時に注意。

IMemInputPin::GetAllocatorRequirements

IMemInputPin インターフェイス

入力ピンが要求したアロケータ プロパティを取得する。

構文

HRESULT GetAllocatorRequirements(
    ALLOCATOR_PROPERTIES *pProps
);

パラメータ

pProps
[in] 要求を書き込む ALLOCATOR_PROPERTIES 構造体へのポインタ。

戻り値

HRESULT 値を返す。以下の表に示されるいずれかの値。

S_OK | 成功。
E_NOTIMPL | 実装されていない。
E_POINTER | NULL ポインタ引数。

注意

出力ピンはメモリ アロケータを初期化するとき、このメソッドを呼び出して入力ピンがバッファ要求を持っているかどうかを確認する。入力ピンのこのメソッドの実装は必須ではない。フィルタが指定したアラインメントやプレフィックスの要求を持っていないなら、このメソッドを実装すべきだ。

IMemInputPin::NotifyAllocator

IMemInputPin インターフェイス

接続用のアロケータを指定する。

構文

HRESULT NotifyAllocator(
    IMemAllocator *pAllocator,
    BOOL bReadOnly
);

パラメータ

pAllocator
[in] アロケータの IMemAllocator インターフェイスへのポインタ。
bReadOnly
[out] このアロケータからのサンプルが読み込み専用かどうかを指定するフラグ。TRUE ならサンプルは読み込み専用。

戻り値

成功なら S_OK を返す、あるいはエラーの原因を示す HRESULT 値を返す。

注意

ピン接続中に、出力ピンはアロケータを選び、このメソッドを呼び出して入力ピンに通知する。出力ピンは IMemInputPin::GetAllocator で入力ピンが提案したアロケータを使う場合もあるが、それ自身のアロケータを提供する場合もある。

bReadOnly パラメータが TRUE なら、アロケータ内のすべてのサンプルは読み込み専用である。フィルタがデータを修正するにはそれらをコピーしなければならない。

IMemInputPin::Receive

IMemInputPin インターフェイス

ストリーム内の次のメディア サンプルを取得する。

構文

HRESULT Receive(
    IMediaSample *pSample
);

パラメータ

pSample
[in] サンプルの IMediaSample インターフェイスへのポインタ。

戻り値

HRESULT 値を返す。以下の表に示されるいずれかの値。

S_OK | 成功。
S_FALSE | ピンは現在フラッシュしている、サンプルは拒否された。
E_POINTER | NULL ポインタ引数。
VFW_E_INVALIDMEDIATYPE | 不適切なメディア タイプ
VFW_E_RUNTIME_ERROR | ランタイム エラーが起きた。
VFW_E_WRONG_STATE | ピンは停止している。

注意

このメソッドは同期しており、ブロックの可能性がある。ピンは以下の 1 つを行う :

  • サンプルを拒否する。
  • すぐに戻り、ワーカー スレッドでサンプルを処理する。
  • 戻る前にサンプルを処理する。

最後のケースでは、メソッドは無限にブロックする可能性がある。これが起こりそうなら、ReceiveCanBlock メソッドは S_OK を返す。

ピンがワーカー スレッドを使ってサンプルを処理するなら、それはサンプルの参照カウントを保持する。どのケースでも出力ピンはこのサンプルを直接再使用することはできない。IMemAllocator::GetBuffer メソッドを呼び出して新しいサンプルを取得しなければならない。

IMemInputPin::ReceiveCanBlock

IMemInputPin インターフェイス

Receive メソッドへの呼び出しがブロックになるかどうかを確認する。

構文

HRESULT ReceiveCanBlock(void);

戻り値

HRESULT 値を返す。以下の表に示されるいずれかの値。

S_FALSE | Receive を呼び出してもピンはブロックにならない。
S_OK | Receive を呼び出すとピンはブロックになる可能性がある。

注意

このメソッドが S_FALSE を返すなら、Receive メソッドの呼び出しはブロックしないことが保証される。そうでなければ、ブロックになる場合がある。アップストリーム フィルタはこのメソッドを使ってそのスレッド方針を決定することができる。Receive の呼び出しがブロックになり得るのなら、アップストリーム フィルタは、データをバッファリングするワーカー スレッドの使用を決めることもできる。

IMemInputPin::ReceiveMultiple

IMemInputPin インターフェイス

ストリーム内の複数のサンプルを取得する。

構文

HRESULT ReceiveMultiple(
    IMediaSample **pSamples,
    long nSamples,
    long *nSamplesProcessed
);

パラメータ

pSamples
[in] nSamples サイズの IMediaSample ポインタの配列のアドレス。
nSamples
[in] 処理するサンプルの数。
nSamplesProcessed
[out] 処理されたサンプルの数を受け取る変数へのポインタ。

戻り値

HRESULT 値を返す。以下の表に示されるいずれかの値。

S_OK | 成功。
S_FALSE | ピンは現在フラッシュしている、サンプルは拒否された。
E_POINTER | NULL ポインタ引数。
VFW_E_INVALIDMEDIATYPE | 不適切なメディア タイプ。
VFW_E_RUNTIME_ERROR | ランタイムエラーが起こった。
VFW_E_WRONG_STATE | ピンは停止している。

注意

このメソッドは Receive メソッドと同じように動作するが、サンプルの配列を取得する。


IMixerPinConfig インターフェイス

IMixerPinConfig インターフェイスは、オーバーレイ ミキサー フィルタの入力ピン上で公開され、ビデオ ストリームの各種操作を実行するメソッドを提供する。オーバーレイ ミキサーには、ビデオ入力ストリームの追加時に動的に作成される複数の入力ピンがある。最初のピンのビデオ ストリームを "プライマリ ストリーム"、その後のピンストリームを "セカンダリ ストリーム" と呼ぶ。

各種ビデオ ストリームのミキシングにかかわるパラメータを操作するには、このインターフェイスを使用する。これらのパラメータには、位置、Z オーダー、ブレンディング レベルと透過性レベル、アスペクト比補正、およびストリームのカラー キーの取得と設定が含まれる。

表示ウィンドウでのビデオ ストリームの位置を設定すると、"セカンダリ ストリーム" すべてのデフォルトの相対位置が {0, 0, 0, 0} になる。したがって、"セカンダリ ストリーム" 上にある SetRelativePosition メソッドを使用して、確実にすべてのビデオ ストリームを正しく配置する。

アプリケーションでは、複数のビデオ ストリームをミキシングするときに、このインターフェイスを使用して属性を取得および設定する。

要件

Mpconfig.h が必要である。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IMixerPinConfig メソッド | 説明
SetRelativePosition | 表示ウィンドウでのストリームの位置を設定する。
GetRelativePosition | 表示ウィンドウでのストリームの位置を設定する。
SetZOrder | 特定のビデオ ストリームの Z オーダーを設定する。
GetZOrder | 特定のビデオ ストリームの Z オーダーを取得する。
SetColorKey | ビデオ ストリームで使用されているカラー キーを設定する。
GetColorKey | ビデオ ストリームで使用されているカラー キーを取得する。
SetBlendingParameter | ブレンディング パラメータを設定する。このパラメータはセカンダリ ストリームとプライマリ ストリームのブレンド方法を定義する。
GetBlendingParameter | ブレンディング パラメータの値を取得する。このパラメータはセカンダリ ストリームとプライマリ ストリームのブレンド方法を定義する。
SetAspectRatioMode | ウィンドウのサイズ変更でのアスペクト比補正モードを設定する。
GetAspectRatioMode | ウィンドウのサイズ変更でのアスペクト比補正モードを取得する。
SetStreamTransparent | ストリームを透過に設定する。
SetStreamTransparent | ストリームが透過かどうかを判断する。

IMixerPinConfig::GetAspectRatioMode

IMixerPinConfig インターフェイス

ウィンドウのサイズ変更でのアスペクト比補正モードを取得する。

構文

HRESULT GetAspectRatioMode(
    AM_ASPECT_RATIO_MODE *pamAspectRatioMode
    ) PURE;

パラメータ

pamAspectRatioMode
[out] AM_ASPECT_RATIO_MODE 列挙型メンバへのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。現在の DirectShow の実装での戻り値は次のとおりである。
E_NOTIMPL | セカンダリ ストリーム上のメソッドが呼び出された。
E_INVALIDARG | 無効な値または NULL。
NOERROR | エラーなし。

参照

IMixerPinConfig::SetAspectRatioMode

IMixerPinConfig::GetBlendingParameter

IMixerPinConfig インターフェイス

ブレンディング パラメータの値を取得する。このパラメータはセカンダリ ストリームとプライマリ ストリームのブレンド方法を定義する。

構文

HRESULT GetBlendingParameter(
    DWORD *pdwBlendingParameter
    ) PURE;

パラメータ

pdwBlendingParameter
[out] プライマリ ストリームとセカンダリ ストリームの間のブレンド量を示す 0 ～ 255 の値へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。現在の DirectShow の実装での戻り値は次のとおりである。
E_UNEXPECTED | プライマリ ストリーム上のメソッドが呼び出された。
E_INVALIDARG | 値が可能な範囲 (0 ～ 255) を超えている。
NOERROR | エラーなし。

注意

値 0 は、セカンダリ ストリームが非表示であることを示す。値 255 は、セカンダリ ストリームが占める領域でプライマリ ストリームが非表示であることを示す。

参照

IMixerPinConfig::SetBlendingParameter

IMixerPinConfig::GetColorKey

IMixerPinConfig インターフェイス

ビデオ ストリームで使用されているカラー キーを取得する。

構文

HRESULT GetColorKey(
    COLORKEY *pColorKey,
    DWORD *pColor ) PURE;

パラメータ

pColorKey
[out] キーの種類およびパレット インデックスが格納された COLORKEY 構造体へのポインタ。
pColor
[out] 返された値へのポインタ。値は、現在のディスプレイ モードが 8 ビットのパレット化モードの場合、返された COLORKEY の 8 ビット パレット インデックスを示す。それ以外の場合、カラー キーを現在のディスプレイ モードのピクセル フォーマットで表現したもの。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。現在の DirectShow の実装での戻り値は次のとおりである。
E_INVALIDARG | 無効な引数。パラメータが両方とも NULL。
E_FAIL | カラー キーが不明なため、GetColorKey が失敗した。
NOERROR | エラーなし。

注意

プライマリ ストリーム上の値を取得すると、オーバーレイ サーフェスで使用している転送先カラー キーが得られる。セカンダリ ピン上の値を取得すると、そのストリームで使用しているカラー キーが得られる。

現在の DirectShow におけるこのインターフェイスの実装は、pColorKey パラメータと pColor パラメータのどちらかに NULL を返す場合がある。ただし、両方が NULL の場合、メソッドは失敗し、E_INVALIDARG を返す。

注 : pColor パラメータで返される DWORD 値は、実際に使用されている色である。したがって、ディスプレイのビット深度が 8、16、24、または 32 の場合、それぞれ、DWORD の下位 8、16、24、32 ビットがカラー キーの実際の値を示す。

参照

IMixerPinConfig::SetColorKey

IMixerPinConfig::GetStreamTransparent

IMixerPinConfig インターフェイス

ストリームが透過かどうかを判断する。

構文

HRESULT GetStreamTransparent(
    BOOL *pbStreamTransparent
    ) PURE;

パラメータ

pbStreamTransparent
[out] ストリームが透過かどうかを示す値へのポインタ。TRUE は透過であることを示し、FALSE は透過でないことを示す。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_NOTIMPL | メソッドがサポートされていない。
NOERROR | エラーなし。

参照

IMixerPinConfig::SetStreamTransparent

IMixerPinConfig::GetRelativePosition

IMixerPinConfig インターフェイス

表示ウィンドウでのストリームの位置を設定する。

構文

HRESULT GetRelativePosition(
    DWORD *pdwLeft,
    DWORD *pdwTop,
    DWORD *pdwRight,
    DWORD *pdwBottom ) PURE;

パラメータ

pdwLeft
[out] 表示ウィンドウの左上角の x 座標を示す値へのポインタ。
pdwTop
[out] 表示ウィンドウの左上角の y 座標を示す値へのポインタ。
pdwRight
[out] 表示ウィンドウの右下角の x 座標を示す値へのポインタ。
pdwBottom
[out] 表示ウィンドウの右下角の y 座標を示す値へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。現在の DirectShow の実装での戻り値は次のとおりである。
E_INVALIDARG | 座標が {0, 0, 10,000, 10,000} の範囲を超えている。
NOERROR | エラーなし。

注意

このメソッドでは、{0, 0, 10,000, 10,000} のウィンドウ座標が想定されている。表示ウィンドウの右下部分でビデオ ストリームがレンダリングされている場合、このメソッドは {5,000, 5,000, 10,000, 10,000} を返す。

参照

IMixerPinConfig::SetRelativePosition

IMixerPinConfig::GetZOrder

IMixerPinConfig インターフェイス

特定のビデオ ストリームの Z オーダーを取得する。

このメソッドは現在実装されていない。E_NOTIMPL を返す。

構文

HRESULT GetZOrder(
    DWORD *pdwZOrder
    ) PURE;

パラメータ

pdwZOrder
[out] ストリーム間のクリップ順序を示す値へのポインタ。

戻り値

E_NOTIMPL を返す。

注意

z 値が大きいイメージは、z 値が小さいイメージより常に手前にある。

参照

IMixerPinConfig::SetZOrder

IMixerPinConfig::SetAspectRatioMode

IMixerPinConfig インターフェイス

ウィンドウのサイズ変更でのアスペクト比補正モードを設定する。

構文

HRESULT SetAspectRatioMode(
    AM_ASPECT_RATIO_MODE amAspectRatioMode
    ) PURE;

パラメータ

amAspectRatioMode
[in] AM_ASPECT_RATIO_MODE 列挙型メンバのいずれかを指定する値。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。現在の DirectShow の実装での戻り値は次のとおりである。
E_NOTIMPL | セカンダリ ストリーム上のメソッドが呼び出された。
E_INVALIDARG | 無効な引数。
NOERROR | エラーなし。

注意

現在、このメソッドは、オーバーレイ ミキサー フィルタのプライマリ ピンのみに実装される。セカンダリ ピンのこのメソッドを呼び出すと、エラーになる。

参照

IMixerPinConfig::GetAspectRatioMode

IMixerPinConfig::SetBlendingParameter

IMixerPinConfig インターフェイス

ブレンディング パラメータを設定する。このパラメータはセカンダリ ストリームとプライマリ ストリームのブレンド方法を定義する。

構文

HRESULT SetBlendingParameter(
    DWORD dwBlendingParameter
    ) PURE;

パラメータ

dwBlendingParameter
[in] プライマリ ストリームとセカンダリ ストリームのブレンドの量を示す 0 ～ 255 の値。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。現在の DirectShow の実装での戻り値は次のとおりである。
E_UNEXPECTED | プライマリ ストリーム上のメソッドが呼び出された。
E_INVALIDARG | 値が可能な範囲 (0 ～ 255) を超えている。
NOERROR | エラーなし。

注意

dwBlendingParameter パラメータには、0 ～ 255 の値を指定する。値 0 では、セカンダリ ストリームが非表示になる。また、値 255 では、セカンダリ ストリームが占める領域でプライマリ ストリームが非表示になる。値を設定しないと、デフォルト値 255 が使用される。

このメソッドでは、プライマリ ストリーム上での呼び出しは想定されていない。

注 : 現在の DirectShow におけるこのインターフェイスの実装では、dwBlendingParameter パラメータに使用できる値は 0 ～ 255 のみである。これ以外の値はすべて無効になる。

参照

IMixerPinConfig::GetBlendingParameter

IMixerPinConfig::SetColorKey

IMixerPinConfig インターフェイス

ビデオ ストリームで使用されているカラー キーを設定する。

構文

HRESULT SetColorKey(
    COLORKEY *pColorKey
) PURE;

パラメータ

pColorKey
[in] COLORKEY 構造体へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

カラー キーという用語の持つ意味は、対象のストリームによって異なる。プライマリ ストリームのカラー キーとは、オーバーレイ サーフェスで使用されている転送先カラー キーを意味する。セカンダリ ストリームのカラー キーとは、オフスクリーン サーフェスからプライマリ サーフェスへのブリットで使用される転送元カラー キーを意味する。

アプリケーションでは、プライマリ ピンのカラー キーに表示されない色 (デスクトップにないと思われる色) を設定すること。オーバーレイ ミキサー フィルタは、目立たない色を選択しようとするが、指定された色がほかのコンテンツに含まれていることがわかっている場合は、アプリケーション側で変更すること。

セカンダリ ストリームのカラー キーを設定してストリームを透過にすると、矩形以外のイメージが可能になる。たとえば、セカンダリ ストリームがクローズド キャプション テキストなら、クローズド キャプション テキスト デコーダで、背景を純色で塗りつぶしたうえで、対応するピンのカラー キーとしてそのカラーを設定する。この結果、カラー キーで指定したピクセル以外がすべて転送される。可能であれば、アプリケーションで、セカンダリ ストリームのカラー キーにプライマリ ストリームのカラー キーと同じ色を設定すると、パフォーマンスを若干上げることができる。

プライマリ ストリームにこの値を設定すると、オーバーレイ サーフェスで使用される転送先カラー キーが設定される。デフォルトでは、透過の (セカンダリ) ストリームすべてのカラー キーとして、転送先カラー キーが使用される。

pColorKey パラメータとして有効な引数には、CK_INDEX および CK_RGB が含まれる。ビデオ ディスプレイ モードは、CK_INDEX では 256 色に設定され、CK_RGB ではハイカラー、24 ビット、32 ビットなどの比較的高い色深度に設定される。CK_RGB フラグは、CK_INDEX と共に指定する。CK_INDEX フラグを設定すると、256 色モードでのパレット インデックスとして、そのインデックスが使用される。ただし、ディスプレイ モードが突然変更されたときに DirectShow が指定されたトゥルーカラーを使用できるように、COLORREF には有効なトゥルーカラーを提供する必要がある。これは、複数のトゥルーカラーは単独のパレット インデックスにマップできるが、パレット インデックスからトゥルーカラーへのマップは 1 対 1 でないためである。

注 : 現在、このメソッドはプライマリ入力ピン用にのみ実装される。

参照

IMixerPinConfig::GetColorKey

IMixerPinConfig::SetStreamTransparent

IMixerPinConfig インターフェイス

ストリームを透過に設定する。

構文

HRESULT SetStreamTransparent(
    BOOL bStreamTransparent
    ) PURE;

パラメータ

bStreamTransparent
[in] ストリームの透過性を指定する値。ストリームが透過の場合は、TRUE を渡す。透過でない場合は、FALSE を渡す。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_NOTIMPL | メソッドがサポートされていない。
NOERROR | エラーなし。

参照

IMixerPinConfig::GetStreamTransparent

IMixerPinConfig::SetRelativePosition

IMixerPinConfig インターフェイス

表示ウィンドウにおけるストリームの位置を設定する。

構文

HRESULT SetRelativePosition(
    DWORD dwLeft,
    DWORD dwTop,
    DWORD dwRight,
    DWORD dwBottom ) PURE;

パラメータ

dwLeft
[in] 表示ウィンドウの左上角の x 座標を指定する値。
dwTop
[in] 表示ウィンドウの左上角の y 座標を指定する値。
dwRight
[in] 表示ウィンドウの右下角の x 座標を指定する値。
dwBottom
[in] 表示ウィンドウの右下角の y 座標を指定する値。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。現在の DirectShow の実装での戻り値は次のとおりである。
E_INVALIDARG | 座標が {0, 0, 10,000, 10,000} の範囲を超えている。
NOERROR | エラーなし。

注意

このメソッドでは、{0, 0, 10,000, 10,000} のウィンドウ座標が想定されている。したがって、表示ウィンドウの右下部分でビデオ ストリームをレンダリングするには、パラメータに {5,000, 5,000, 10,000, 10,000} を指定して呼び出す。

注 : 10,000 を超える値は無効である。指定するとエラーになる。

参照

IMixerPinConfig::GetRelativePosition

IMixerPinConfig::SetZOrder

IMixerPinConfig インターフェイス

特定のビデオ ストリームの Z オーダーを設定する。

このメソッドは現在実装されていない。E_NOTIMPL を返す。

構文

HRESULT SetZOrder(
  DWORD dwZOrder
) PURE;

パラメータ

dwZOrder
[in] ストリーム間のクリップ順序を示す値。

戻り値

E_NOTIMPL を返す。

注意

Z オーダーは、どのストリームがどのストリームをクリップできるかを示す。z 値が大きいイメージは、z 値が小さいイメージより常に手前にある。

複数ストリーム間の相対順序は、それらのビデオ イメージがオーバーラップする場合にのみ意味を持つ。

オーバーラップする 2 つのストリームに同じ Z オーダーを指定すると、ビデオに不自然な効果が現れることがある。

参照

IMixerPinConfig::GetZOrder


IMixerPinConfig2 インターフェイス

IMixerPinConfig2 インターフェイスは、オーバーレイ ミキサーの入力ピン上で公開され、ビデオのカラー コントロールを操作を実行するメソッドを提供する (ただし、VGA チップがカラー コントロールをサポートする場合)。

このインターフェイスは、IMixerPinConfig インターフェイスから派生する。

アプリケーションでは、複数のビデオ ストリームをミキシングするときに、このインターフェイスを使用してビデオのカラー コントロールを取得および設定する。

要件

Mpconfig.h が必要である。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IMixerPinConfig2 メソッド | 説明
SetOverlaySurfaceColorControls | 指定されたオーバーレイ サーフェスに関連付けられたカラー コントロールを設定する。
GetOverlaySurfaceColorControls | 指定されたオーバーレイ サーフェスに現在関連付けられているカラー コントロールを取得する。

IMixerPinConfig2::GetOverlaySurfaceColorControls

IMixerPinConfig2 インターフェイス

指定されたオーバーレイ サーフェスに関連付けられたカラー コントロールを取得する。

構文

HRESULT GetOverlaySurfaceColorControls(
    LPDDCOLORCONTROL pColorControl
    ) PURE;

パラメータ

pColorControl
[out] 指定されたサーフェスに現在適用されているカラー値が入った DDCOLORCONTROL 構造体へのポインタのアドレス。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。ピン上のアロケータがオーバーレイ サーフェスを使用していない場合は、E_FAIL が返される。

IMixerPinConfig2::SetOverlaySurfaceColorControls

IMixerPinConfig2 インターフェイス

指定されたオーバーレイ サーフェスに関連付けられたカラー コントロールを設定する。

構文

HRESULT SetOverlaySurfaceColorControls(
    LPDDCOLORCONTROL pColorControl
    ) PURE;

パラメータ

pColorControl
[in] 指定されたサーフェスに適用される新しい値が入った DDCOLORCONTROL 構造体へのポインタのアドレス。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。ピン上のアロケータがオーバーレイ サーフェスを使用していない場合は、E_FAIL が返される。


IMpeg2Demultiplexer インターフェイス

このインターフェイスは MPEG-2 デマルチプレクサ フィルタ (Demux) 上で実装され、番組ストリーム モードとトランスポート ストリーム モードの両方で用いられる。アプリケーションや他のフィルタが Demux 上で出力ピンを作成、構成、削除する際に呼び出される。

メソッド名 | 説明
CreateOutputPin | Demux に新しい出力ピンを作成する。
SetOutputPinMediaType | 指定された出力ピンのメディア タイプをアップデートする。(DirectX® 8 では実装されていない。)
DeleteOutputPin | 指定された出力ピンを削除する。

IMpeg2Demultiplexer::CreateOutputPin

IMpeg2Demultiplexer インターフェイス

Demux に新しい出力ピンを作成する。

構文

HRESULT CreateOutputPin(
    AM_MEDIA_TYPE* pMediaType,
     LPWSTR pszPinName,
      IPin** ppIPin
    );

パラメータ

pMediaType
[in] 新しいピンのメディア タイプ情報を指定する AM_MEDIA_TYPE 構造体へのポインタ。
pszPinName
[in] 新しいピンのアプリケーション定義のフレンドリ名を指定するワイド キャラクタ文字列へのポインタ。
ppIPin
[out] 新しいピンの IPin インターフェイスにセットされるポインタ。

戻り値

成功なら S_OK を返す。 メソッドが失敗すると、エラー情報は標準 COM IErrorInfo インターフェイスを使って取得できる。

注意

同じ名前のピン名は許可されない。返される IPin インターフェイス は IMPEG2StreamIdMap インターフェイス (番組ストリーム用) あるいは IMPEG2PIDMap インターフェイス (トランスポート ストリーム用) に対して新しいピンをクエリするために用いられる。最初の出力ピンとしてどのインターフェイスがクエリされるかを基に、Demux は自分自身をトランスポート ストリーム モードあるいは番組ストリーム モードのどちらかに構成する。Demux が一度構成されると、別のインターフェイスを取得する QueryInterface への呼び出しは失敗する。

IMpeg2Demultiplexer::SetOutputPinMediaType

IMpeg2Demultiplexer インターフェイス

指定された出力ピンのメディア タイプをアップデートする。(DirectX® 8 では実装されていない。)

構文

HRESULT SetOutputPinMediaType(
    LPWSTR pszPinName,
    AM_MEDIA_TYPE* pMediaType
    );

パラメータ

pszPinName
[in] ピンが CreateOutputPin の呼び出し時に作成されたとき指定されたピンのフレンドリ名。
pMediaType
[in] ピンに対して新しいメディア タイプを指定する AM_MEDIA_TYPE 構造体へのポインタ。

戻り値

成功なら S_OK を返す。 メソッドが失敗すると、エラー情報は標準 COM IErrorInfo インターフェイスを使って取得できる。

注意

DirectX 8 では、ピンが作成されたときのメディア タイプがピンにアサインされなければならない。そのメディア タイプは後で変更することができない。

ピンは新しいメディア タイプでいつでも再構成可能である。接続していなければ、メディア タイプは単にアップデートされるだけである。そのピンが接続されていると、ダウンストリーム入力ピンが指定されたメディア タイプを許容するか拒否するかによって、その呼び出しが成功あるいは失敗する。

メディア タイプは Demux では解釈されない。その解釈は出力ピンによる接続ネゴシエーション中にだけ行われる。メディア サンプルの内容からは解釈されない。メディア サンプルの内容は PID が IMPEG2PIDMap::MapPID メソッドの MEDIA_SAMPLE_CONTENT パラメータでマップされるとき、あるいは IMPEG2StreamId::MapStreamId 呼び出しに定義された値によって定義される。

IMpeg2Demultiplexer::DeleteOutputPin

IMpeg2Demultiplexer Interface

指定された出力ピンを削除する。

構文

HRESULT DeleteOutputPin(
    LPWSTR pszPinName
    );

パラメータ

pszPinName
[in] ピンが CreateOutputPin の呼び出し時に作成されたとき指定されたピンのフレンドリ名。

戻り値

成功なら S_OK を返す。 エラー情報は標準 COM IErrorInfo インターフェイスを使って取得できる。

注意

フィルタを残したままピンを削除する必要があるときにのみ、このメソッドを呼び出すこと。フィルタは解放されるとき、出力ピンで必要なすべてのクリーン アップを行う。


IMPEG2PIDMap インターフェイス

このインターフェイスは MPEG-2 デマルチプレクサ フィルタ (Demux) の各出力ピンで実装され、トランスポート ストリーム モードでのみ使用される。アプリケーションや他のフィルタがピンと 1 つ以上のパケット ID (PID) を組み合わせるためにこのインターフェイスを呼び出す。PID が一度マップされると、Demux はすべてのパケットを出力ピンへその ID で出力する

番組ストリームについては、IMPEG2StreamIdMap インターフェイスを使用する。

メソッド名 | 説明
MapPID | 指定された PID のパケットをピンにマップする。
UnmapPID | MapPID への以前の呼び出しで作成された PID マッピングを解除する。
EnumPIDMap | このピンに現在マップされているすべての PID のコレクションを返す。

IMPEG2PIDMap::MapPID

IMPEG2PIDMap インターフェイス

指定された PID のパケットをピンにマップする。

構文

HRESULT MapPID(
    ULONG culPID,
    ULONG* pulPID,
    MEDIA_SAMPLE_CONTENT MediaSampleContent
);

パラメータ

culPID
[in] putPID 配列の要素数を指定する ULONG 型の変数。
pulPID
[in] マップする PID を指定する ULONG 型の変数へのポインタ。
MediaSampleContent
[in] ストリームの内容を指定する MEDIA_SAMPLE_CONTENT 型の変数。

戻り値

成功なら S_OK を返す。 メソッドが失敗すると、エラー情報は標準 COM IErrorInfo インターフェイスを使って取得できる。

注意

与えられた時間に 255 より多い異なる PID をマップできない。これは Demux が自分自身で使用するために内部的にマップする PID を含む、この数はトランスポート ストリームに依存して変わる。アプリケーションは与えられたトランスポート ストリーム上で通常 10 から 12 より多い PID をマップしないので、この制限は問題とならないであろう。

IMPEG2PIDMap::UnmapPID

IMPEG2PIDMap インターフェイス

MapPID への以前の呼び出しで作成された PID マッピングを解除する。

構文

HRESULT UnmapPID(
    ULONG culPID,
    ULONG* pulPID
);

パラメータ

culPID
[in] putPID 配列の要素数を指定する ULONG 型の変数。
pulPID
[in] このピンにマップされる PID の配列。

戻り値

成功なら S_OK を返す。 メソッドが失敗すると、エラー情報は標準 COM IErrorInfo インターフェイスを使って取得できる。

注意

オーディオ ストリームとビデオ ストリームの出力ピンでは、与えられた時間にマップされる PID は 1 つだけである。PSI ストリームをトランスポート情報フィルタに出力するピンのような出力ピンでは、1 つのピンに複数の PID がマップされる場合がある。そのピンにどの PID がマップされているかを確認するには、IEnumPIDMap メソッドを使い、次にその値を pulPID 配列に書き込むこと。

IMPEG2PIDMap::EnumPIDMap

IMPEG2PIDMap インターフェイス

このピンに現在マップされているすべての PID のコレクションを返す。

構文

HRESULT EnumPIDMap(
    IEnumPIDMap** ppIEnumPIDMap
);

パラメータ

ppIEnumPIDMap
[in] 返されるコレクションにセットされる IEnumPIDMap インターフェイス ポインタ。

戻り値

成功なら S_OK を返す。 メソッドが失敗すると、エラー情報は標準 COM IErrorInfo インターフェイスを使って取得できる。


IMPEG2StreamIdMap インターフェイス

このインターフェイスは MPEG-2 デマルチプレクサ フィルタ (Demux) の各出力ピンで実装される。番組ストリーム モードでのみ使用される。アプリケーションや他のフィルタがピンと指定されたストリーム ID を組み合わせるために、そしてそのピンにサブストリーム フィルタリングがストリームに要求されているかどうかを知らせるためにこのインターフェイスを呼び出す。

トランスポート ストリームについては IMPEG2PIDMap インターフェイスを使用する。

メソッド名 | 説明
MapStreamId | MPEG-2 番組ストリーム内の基本ストリームのストリーム ID をメディア内容タイプとサブストリーム情報にマップする。
UnmapStreamId | 以前の MapStreamId 呼び出しで作成されたストリーム ID マッピングを解除する。
EnumStreamIdMap | このピンにマップされているすべてのストリーム ID のコレクションを返す。

IMPEG2StreamIdMap::MapStreamId

IMPEG2StreamIdMap インターフェイス

MPEG-2 番組ストリーム内の基本ストリームのストリーム ID をメディア内容タイプとサブストリーム情報にマップする。

構文

HRESULT MapStreamId(
    ULONG ulStreamId,
    DWORD MediaSampleContent,
    ULONG ulSubstreamFilterValue,
    int iDataOffset
);

パラメータ

ulStreamId
[in] PES ストリームのストリーム ID を指定する ULONG 型の変数。
MediaSampleContent
[in] ストリームの内容を指定する ULONG 型の変数。現在サポートされている値は MPEG2_PROGRAM_ELEMENTARY_STREAM (axextend.idl で 0x00000001 と定義されている) のみである。
ulSubstreamFilterValue
[in] この基本ストリーム内のどのサブストリームをダウンストリーム デコーダに渡すかを指定する ULONG 型の変数。低オーダー バイトだけに有効な値が入っている。iDataOffset = 0 なら、このパラメータは無視される。
iDataOffset
[in] サブストリーム開始点のバイト オフセットを指定する int 型の変数。

戻り値

成功なら S_OK を返す。 メソッドが失敗すると、エラー情報は標準 COM IErrorInfo インターフェイスを使って取得できる。

注意

このメソッドがマップするストリーム ID は PES ヘッダー内のストリーム ID である。サブストリーム フィルタリングは 1 つのオーディオ ストリームで複数チャンネルを提供するために最も普通に使われている。

IMPEG2StreamIdMap::UnmapStreamId

IMPEG2StreamIdMap インターフェイス

以前の MapStreamId 呼び出しで作成されたストリーム ID マッピングを解除する。

構文

HRESULT UnmapStreamId(
    ULONG culStreamId,
    ULONG* pulStreamID
);

パラメータ

culStreamId
[in] pulStreamID 配列内の要素の数を指定する ULONG 型の変数。
pulStreamID
[in] このピンにマップされたストリーム ID の配列。

戻り値

成功なら S_OK を返す。 メソッドが失敗すると、エラー情報は標準 COM IErrorInfo インターフェイスを使って取得できる。

注意

与えられたピンにマップされるストリーム ID は通常 1 つだけである、それゆえ pulStreamID は通常 1 つの要素だけをもつ。

IMPEG2StreamIdMap::EnumStreamIdMap

IMPEG2StreamIdMap インターフェイス

このピンにマップされているすべてのストリーム ID のコレクションを返す。

構文

HRESULT EnumStreamIdMap(
    IEnumStreamIdMap** ppIEnumStreamIdMap
);

パラメータ

ppIEnumStreamIdMap
[in] 返されるコレクションがセットされる IEnumStreamIdMap インターフェイス ポインタ。

戻り値

成功なら S_OK を返す。 メソッドが失敗すると、エラー情報は標準 COM IErrorInfo インターフェイスを使って取得できる。

注意

現在、与えられたピンにマップされるストリーム ID は 1 つだけである、それゆえこのコレクションは通常 1 つの要素だけをもつ。


IOverlay インターフェイス

IOverlay インターフェイスは、ビデオを正しいウィンドウ位置に配置した状態で、フィルタからビデオ メモリに直接書き込むために必要な情報を提供する。このインターフェイスは、ビデオ レンダラの入力ピン上に実装され、アップストリーム フィルタ (主にビデオ デコンプレッサ フィルタ) の IOverlayNotify メソッドを呼び出して、ビデオ ウィンドウへの変更を通知することにより、そのフィルタと通信する。

このインターフェイスは、DirectDraw® のオーバーレイ能力とは無関係である。Microsoft のビデオ レンダラは、IMemInputPin インターフェイスを通じて受け取ったデータを、DirectDraw オーバレイを使用して描画する (ただし利用可能な場合)。このインターフェイスは、IMemInputPin の代わりに使用され、レンダラの描画能力をバイパスするが、ディスプレイのその他プロパティの通知を受ける必要がある、すべてのアップストリーム フィルタに、通知のサポートを提供することを目的としている。

IOverlay インターフェイスと IOverlayNotify インターフェイスの連携の詳細については、「IOverlayNotify インターフェイス」を参照すること。

レンダリング ウィンドウへの変更の非同期通知の詳細については、「IOverlayNotify2 インターフェイス」を参照すること。

このインターフェイスは、Microsoft® DirectShow® ビデオ レンダリング フィルタに実装される。また、必要に応じて、代替ビデオ レンダリング フィルタに実装することもできる。その場合には、このインターフェイスを実装して、フレーム バッファに直接書き込むフィルタ、またはオーバーレイを配置しようとするフィルタに、ビデオをどこに表示すればよいかを知らせる。このインターフェイスを実装するには、ビデオ プロパティの変更の通知も含め、描画を行っているフィルタの IOverlayNotify インターフェイスまたは IOverlayNotify2 インターフェイスのメソッドを使用する準備が、レンダラにできている必要がある。

DirectShow のウィンドウ ベースのレンダラは、IMemInputPin インターフェイスと IOverlay インターフェイスの両方をサポートする。これら 2 つのインターフェイスは互いに排他である。フィルタでは、サブタイプが MEDIASUBTYPE_Overlay のメディア タイプを接続中に提供することにより、IOverlay 転送 インターフェイスの方を使用する。接続後、フィルタは問題なく IOverlay インターフェイスを取得および使用できる。フィルタがほかのビデオ フォーマット (MEDIASUBTYPE_RGB8 など) で接続する場合、IOverlay を通じて呼び出そうとすると、VFW_E_NOT_OVERLAY_CONNECTION が返される。

ビデオ オーバーレイのプロパティを制御する必要があり、ビデオ データ自体の表示を処理しようとするアップストリーム フィルタからは、このインターフェイスのメソッドを使用すること。このインターフェイスは、通常、ビデオ ハードウェアへの代替接続を持つハードウェア ビデオ デコーダで使用される。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを返す。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IOverlay メソッド | 説明
GetPalette | 現在のパレットを取得する。
SetPalette | パレットを設定する。
GetDefaultColorKey | デフォルトのカラー キーを取得する。
GetColorKey | 現在アクティブなカラー キーの識別子を取得する。
SetColorKey | カラー キーを変更する。
GetWindowHandle | ウィンドウ ハンドルを返す。
GetClipList | クリップ リストを取得する。
GetVideoPosition | 現在のビデオの転送元矩形および転送先矩形を取得する。
Advise | オーバーレイ イベント用のアドバイズ リンクを設定する。
Unadvise | アドバイズ リンクを終了する。

IOverlay::Advise

IOverlay インターフェイス

dwInterests パラメータで指定されたオーバーレイ イベント用のアドバイズ リンクを設定する。

構文

HRESULT Advise(

  IOverlayNotify *pOverlayNotify,

  DWORD dwInterests

  );

パラメータ

pOverlayNotify
[in] 通知インターフェイスへのポインタ。
dwInterests
[in] 目的のコールバック。以下のイベントから成る任意のサブセットを指定する。
ADVISE_NONE | 変更なし。
ADVISE_CLIPPING | クリッピング リージョンの変更 (ウィンドウと同期する)。
ADVISE_PALETTE | パレットの変更。
ADVISE_COLORKEY | クロマ キー値の変更。
ADVISE_POSITION | ビデオ ウィンドウの位置の変更 (ウィンドウと同期しない)。
ADVISE_DISPLAY_CHANGE | WM_DISPLAYCHANGE に関する呼び出し。ディスプレイ解像度を変更すると、すべてのウィンドウに WM_DISPLAYCHANGE メッセージが送られる。
ADVISE_ALL2 | 上のすべてのイベント。

戻り値

戻り値なし。

注意

このメソッドは、IOverlayNotify インターフェイスが通知を受け取るためのアドバイズ リンクを設定する。これらのイベントのいずれかが発生すると、pOverlayNotify パラメータに渡された適切なエントリ ポイントが呼び出される (IOverlayNotify::OnClipChange、IOverlayNotify::OnColorKeyChange、IOverlayNotify::OnPaletteChange、または IOverlayNotify::OnPositionChange)。

1 つの IOverlay インターフェイスに設定できるアドバイズ リンクは 1 つだけである。2 度目以降の呼び出しで別の通知インターフェイスを設定しようとすると、VFW_E_ADVISE_ALREADY_SET が返される。アドバイズ リンクを取り消すには、IOverlay::Unadvise を使用する。

IOverlay::GetClipList

IOverlay インターフェイス

クリップ リストを取得する。

構文

HRESULT GetClipList(

  RECT *pSourceRect,

  RECT *pDestinationRect,

  RGNDATA **ppRgnData

  );

パラメータ

pSourceRect
[out] クライアントの境界矩形へのポインタ。
pDestinationRect
[in] 転送先矩形へのポインタ。
ppRgnData
[out] クリッピングが記述されたヘッダーおよびデータへのポインタのアドレス。成功した場合は、Microsoft® Win32® CoTaskMemFree 関数でメモリを解放しなければならない。

戻り値

戻り値なし。

注意

クリッピング矩形のメモリは、サイズが可変なため IOverlay の実装によって割り当てられる。このメソッドの呼び出し元フィルタでは、使い終わったら (CoTaskMemFree を使用して) メモリを解放しなければならない。

IOverlay::GetColorKey

IOverlay インターフェイス

クロマ キー処理に使用する現在のカラー キーを取得する。

構文

HRESULT GetColorKey(

  COLORKEY *pColorKey

  );

パラメータ

pColorKey
[out] クロマ キー処理に使用する現在のカラー キーのコピー先へのポインタ。

戻り値

戻り値なし。

注意

IOverlay::SetColorKey メソッドを使用してカラー キーを変更すると、すべてのアドバイズ リンクが、新しい色が指定された IOverlayNotify::OnColorKeyChange コールバック メソッドを受け取る。

現在使用されているカラー キーがない場合、このメソッドは VFW_E_NO_COLOR_KEY_SET を返す。

IOverlay::GetDefaultColorKey

IOverlay インターフェイス

クロマ キー オーバーレイに使用するデフォルトのカラー キーを取得する。

構文

HRESULT GetDefaultColorKey(

  COLORKEY *pColorKey

  );

パラメータ

pColorKey
[out] デフォルトのカラー キーのコピー先へのポインタ。

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
S_OK または NOERROR | 成功。

注意

カラー キーを使用するフィルタは、ビデオ レンダラからデフォルトの色を取得できる。そのうえで IOverlay::SetColorKey を使用して、ウィンドウにデフォルトのカラー キーを組み込める。このメソッドで返される色は、現在のディスプレイ モードによって異なる。8 ビットのパレット化モードの場合は、明るいシステム カラーが返される (マゼンタなど)。トゥルーカラー モードの場合は、黒の濃淡が返される。

IOverlay インターフェイスでは、同じコンピュータにあるそのレンダラの各インスタンスに、それぞれ異なったカラー キーが渡されるようになっているため、オーバーレイの競合は発生しない。

IOverlay::GetPalette

IOverlay インターフェイス

現在のシステム パレットを取得する。

構文

HRESULT GetPalette(

  DWORD *pdwColors,

  PALETTEENTRY **ppPalette

  );

パラメータ

pdwColors
[out] 存在する色の数へのポインタ。
ppPalette
[out] 取得されたパレット構造体へのポインタのアドレス。

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
S_OK または NOERROR | 成功。

IOverlay::GetVideoPosition

IOverlay インターフェイス

現在のビデオの転送元矩形および転送先矩形を取得する。

構文

HRESULT GetVideoPosition(
  [out] RECT *pSourceRect,
  [out] RECT *pDestinationRect
  );

パラメータ

pSourceRect
[out] ビデオ クライアントの境界矩形へのポインタ。
pDestinationRect
[in] ビデオの転送先矩形へのポインタ。

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
S_OK または NOERROR | 成功。

IOverlay::GetWindowHandle

IOverlay インターフェイス

現在のウィンドウ ハンドルを取得する。

構文

HRESULT GetWindowHandle(
  HWND *pHwnd
  );

パラメータ

pHwnd
[out] ウィンドウ ハンドルへのポインタ。

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
S_OK または NOERROR | 成功。

IOverlay::SetColorKey

IOverlay インターフェイス

カラー キーを変更する。

構文

HRESULT SetColorKey(

  COLORKEY *pColorKey

  );

パラメータ

pColorKey
[out] 設定するカラー キー値へのポインタ。成功した場合は、実際に選択されたカラー キー値が、このパラメータにコピーされる。

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
S_OK または NOERROR | 成功。

注意

IOverlay::SetColorKey メソッドを使用してカラー キーを変更すると、すべてのアドバイズ リンクが、新しい色が指定された IOverlayNotify::OnColorKeyChange コールバック メソッドを受け取る。

パレット化されているディスプレイ上の IOverlay を使用するとき、フィルタは、カラー キーを組み込む (IOverlay::SetColorKey を使用) ことも、パレットを組み込む (IOverlay::SetPalette を使用する) こともできるが、両方を組み込むことはできない。これは、このモードのカラー キーではパレットが認識される必要があり、これが SetPalette と矛盾するからである。カラー キーを削除するには、CK_NOCOLORKEY フラグを指定してカラー キーを要求する。同様に、SetPalette で組み込んだパレットを削除するには、SetPalette を呼び出して NULL パラメータを渡す (つまり SetPalette(0,NULL))。

カラー キーが組み込まれているときに、パレットを設定しようとすると、VFW_E_PALETTE_SET エラーが返される。パレットが組み込まれているときに、カラー キーを設定しようとすると、VFW_E_COLOR_KEY_SET が返される。

IOverlay::SetPalette

IOverlay インターフェイス

パレットを設定する。

構文

HRESULT SetPalette(

  DWORD dwColors,

  PALETTEENTRY *pPalette

  );

パラメータ

dwColors
[in] 存在する色の数。
pPalette
[in] パレットに使用する色へのポインタ。

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
S_OK または NOERROR | 成功。

注意

このメソッドは、ウィンドウの論理パレットを設定する。実際のシステム デバイス パレットで要求された色を、ウィンドウが常に持っているとは限らない。Microsoft® Windows® オペレーティング システムでは、フォアグラウンドのアクティブ ウィンドウにのみ、それらの色が保証される。現在のデバイス パレットを取得するには、IOverlay::GetPalette を呼び出す。

デバイスにパレットがない場合、VFW_E_NO_DISPLAY_PALETTE が返される。

オーバーレイ ミキサー フィルタは、E_NOTIMPL を返す。

IOverlay::Unadvise

IOverlay インターフェイス

IOverlayNotify インターフェイスで確立したアドバイズ リンクを終了する。

構文

HRESULT Unadvise(void);

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
S_OK または NOERROR | 成功。

注意

このメソッドは、IOverlay::Advise メソッドを使用して確立したアドバイズ リンクを終了する。同時に保持できるアドバイズ リンクは 1 つだけである。


IOverlayNotify インターフェイス

IOverlayNotify インターフェイスは、デコーダなどのアップストリーム フィルタに、レンダリング ウィンドウへの変更の通知を提供する。このインターフェイスには、パレット、カラー キー、およびウィンドウ位置への変更、および可視領域 (クリッピング) の変化に関する通知が含まれる。

多くのソフトウェア ビデオ デコーダでは、デコーダがレンダラの入力ピンの IMemInputPin インターフェイスにメディア サンプルを渡し、その結果生成された圧縮解除後のイメージを、ビデオ レンダラが描画する。

ただし、一部のビデオ デコード フィルタ (主にハードウェア圧縮解除ボード) では、(多くの場合 VGA コネクタを使用して) そのデコーダ内でイメージを描画する。このようなフィルタでは、IMemInputPin を使用する必要はないが、代わりに、レンダラの入力ピンが提供する IOverlay インターフェイスを使用できる。デコーダは、ウィンドウの位置またはサイズが変化したとき、または現在のシステム パレットが変化したときに、このインターフェイスを通じて通知を受けることによって、カラー キーおよびパレットの組み込みや変更ができる。

独自の描画処理を行うデコーダは、ウィンドウのサイズまたは位置が変化したとき、現在のシステム パレットが変化したとき、または別のカラー キーが使用されたときに通知を受けるために、IOverlayNotify インターフェイスを実装しなければならない。そうすると、このメソッドで、このインターフェイスへのポインタを、レンダラの入力ピンの IOverlay インターフェイスに渡して、アドバイズ リンク (本来はコールバック メカニズム) を設定できる。アドバイズ リンクの確立後には、該当するイベントが発生すると、レンダラがデコーダの IOverlayNotify メソッドを呼び出す。アドバイズ リンクを取り消すには、IOverlay::Unadvise を呼び出す。

ビデオ レンダラは、このインターフェイスのメソッドを呼び出す唯一のフィルタである。この呼び出しは、デフォルトのレンダラによって自動的に行われる。代替ビデオ レンダラを開発する場合、そのフィルタで IOverlay をサポートし、IOverlay::Advise の呼び出しでフィルタにこのインターフェイスが渡されるなら、このインターフェイスのメソッドを使用する必要がある。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを返す。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IOverlayNotify メソッド | 説明
OnPaletteChange | ウィンドウのパレットが変化したことを示す通知を提供する。
OnClipChange | ウィンドウの可視領域が変化したことを示す通知を提供する。
OnColorKeyChange | クロマ キーが変化したことを示す通知を提供する。
OnPositionChange | 位置が変化したことを示す通知を提供する。

IOverlayNotify::OnClipChange

IOverlayNotify インターフェイス

ウィンドウの可視領域が変化したことを示す通知を提供する。メソッドから戻る前に、オーバーレイ ハードウェアすべてに可視領域への変更が反映されなければならない。

構文

HRESULT OnClipChange(
  RECT *pSourceRect,
  RECT *pDestinationRect,
  RGNDATA *pRgnData
  );

パラメータ

pSourceRect
[in] ビデオ内の使用する領域へのポインタ。
pDestinationRect
[in] ビデオの転送先へのポインタ。
pRgnData
[in] クリッピング情報へのポインタ。

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
S_OK または NOERROR | 成功。

注意

OnClipChange の呼び出しは、ウィンドウと同期して発生する。このメソッドは、ウィンドウの移動前にビデオをフリーズするために、空のクリップ リストを指定して呼び出され、新しいクリップ リストを使用してウィンドウが安定化されたときに、もう一度呼び出される。

ウィンドウ矩形がすべて 0 の場合、ウィンドウは非表示である。AVI デコーダの場合、現在のイメージを利用して次のイメージを復号化するなら、デコーダはイメージを保存しなければならない。

IOverlayNotify::OnColorKeyChange

IOverlayNotify インターフェイス

ウィンドウのカラー キーが変化したことを示す通知を提供する。

構文

HRESULT OnColorKeyChange(

  COLORKEY *pColorKey

  );

パラメータ

pColorKey
[in] 新しいクロマ キーへのポインタ。

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
S_OK または NOERROR | 成功。

IOverlayNotify::OnPaletteChange

IOverlayNotify インターフェイス

ウィンドウのパレットが変化したことを示す通知を提供する。

構文

HRESULT OnPaletteChange(

  DWORD dwColors,

  const PALETTEENTRY *pPalette

  );

パラメータ

dwColors
[in] 存在する色の数。
pPalette
[in] パレット カラーの配列へのポインタ。

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
S_OK または NOERROR | 成功。

注意

戻る前に、必要に応じてフィルタで RGBQUAD 値の配列をコピーすること。

IOverlayNotify::OnPositionChange

IOverlayNotify インターフェイス

位置が変化したことを示す通知を提供する。

構文

HRESULT OnPositionChange(
  const RECT *pSourceRect,
  const RECT *pDestinationRect
  );

パラメータ

pSourceRect
[in] ビデオの転送元矩形へのポインタ。
pDestinationRect
[in] ビデオの転送先矩形へのポインタ。表示可能領域に合わせてクリッピングされないので注意すること。

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
S_OK または NOERROR | 成功。

注意

このメソッドは、クリッピングを同期更新する必要はなく、ビデオの転送元位置または転送先位置が変更されたときにのみ知る必要がある、ハードウェア オーバーレイ カードでの使用を目的とするコールバックである。

IOverlayNotify::OnClipChange メソッドと異なり、このメソッドはウィンドウの変化と同期して呼び出されるのではなく、ウィンドウが変化した後の任意の時点で (基本的には WM_SIZE のメッセージが届いたとき) 呼び出される。したがって、このメソッドは、データをフレーム バッファに差し込まないオーバーレイ カードに適している。


IOverlayNotify2 インターフェイス

IOverlayNotify2 インターフェイスは、IOverlayNotify インターフェイスから派生する。IOverlayNotify2 は、公開されているウィンドウ領域の変更を識別して、レンダリング ウィンドウの変更を知らせる非同期通知を提供する。アドバイズ リンクは、IOverlayNotify2::OnDisplayChange 通知を受け付けるため、このインターフェイスをオプションでサポートする。

表示されるウィンドウ領域が変化したときに通知を受けるため、独自の描画処理を行うデコーダは、IOverlayNotify2 インターフェイスを実装しなければならない。

ビデオ レンダラは、このインターフェイスのメソッドを呼び出す唯一のフィルタである。この呼び出しは、デフォルトのレンダラによって自動的に行われる。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IOverlayNotify メソッド | 説明
OnPaletteChange | ウィンドウのパレットが変化したことを知らせる通知を提供する。
OnClipChange | ウィンドウの可視リージョンが変化したことを知らせる通知を提供する。
OnColorKeyChange | クロマ キーが変化したことを知らせる通知を提供する。
OnPositionChange | 位置が変化したことを知らせる通知を提供する。
IOverlayNotify2 メソッド | 説明
OnDisplayChange | 表示されるウィンドウ領域が変化したことを知らせる通知を提供する。

IOverlayNotify2::OnDisplayChange

IOverlayNotify2 インターフェイス

表示されるウィンドウ領域が変化したことを知らせる通知を提供する。

構文

HRESULT OnDisplayChange(
    HMONITOR hMonitor
);

パラメータ

hMonitor
[in] オーバーレイの表示に使用するモニタのハンドル。

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
S_OK または NOERROR | 成功。


IPersistMediaPropertyBag インターフェイス

IPersistMediaPropertyBag インターフェイスは、AVI (Audio-Video Interleaved) ストリームの INFO チャンクおよび DISP チャンクを設定および取得する。このインターフェイスは、IMediaPropertyBag インターフェイスを使用して、チャンクを名前/値ペアとして格納する。

AVI スプリッタ フィルタおよび WAV パーサー フィルタは、AVI ファイルまたは WAV ファイルから INFO チャンクおよび DISP チャンクを読み取るため、このインターフェイスをサポートする。AVI Mux フィルタは、これらのチャンクをファイルに書き込むため、このインターフェイスをサポートする。

IPersistMediaPropertyBag は、IPersistPropertyBag インターフェイスを原型にしているが、継承はしていない。詳細については、Platform SDK を参照すること。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IPersistMediaPropertyBag メソッド | 説明
InitNew | メディア ファイルのヘッダー情報を保持する新しいプロパティ バッグを初期化する。
Load | メディア ファイルからプロパティを取得し、それをプロパティ バッグに格納する。
Save | メディア ファイルのプロパティを保存する。

IPersistMediaPropertyBag::InitNew

IPersistMediaPropertyBag インターフェイス

新しいプロパティを受け取るオブジェクトを初期化する。

構文

HRESULT InitNew(void);

戻り値

S_OK を返す。

注意

AVI Mux フィルタのこのメソッドを呼び出すと、Load メソッドを使用して直前に設定されたプロパティがすべて消去される。

AVI スプリッタ フィルタまたは WAV パーサーのこのメソッドは、呼び出しても効果がない。

IPersistMediaPropertyBag::Load

IPersistMediaPropertyBag インターフェイス

メディア プロパティ バッグからフィルタにプロパティをロードする。

構文

HRESULT Load(
    IMediaPropertyBag *pPropBag
    IErrorLog *pErrorLog
);

パラメータ

pPropBag
[in] 呼び出し元で作成したメディア プロパティ バッグの IMediaPropertyBag インターフェイスへのポインタ。
pErrorLog
[in] 予約済み。値に NULL を設定する。

戻り値

HRESULT 値を返す。設定される値は次のとおりである。

S_OK | 成功。
E_POINTER | NULL ポインタ引数。
STG_E_ACCESSDENIED | アクセスが拒否された。
VFW_E_WRONG_STATE | フィルタ グラフが停止状態にない。

注意

AVI ストリームにプロパティを書き込むには、AVI Mux フィルタのこのメソッドを呼び出す。次のサンプル コードは、ストリームに IART (作者名) INFO チャンクを書き込む方法を示す。

IPersistMediaPropertyBag *pPersist = NULL;
IMediaPropertyBag *pBag = NULL;
VARIANT val;

// AVI Mux フィルタに IPersistMediaPropertyBag (非表示) を照会する。

CoCreateInstance(CLSID_MediaPropertyBag, NULL, CLSCTX_INPROC,
        IID_IMediaPropertyBag, (LPVOID *)&pBag);

val.vt = VT_BSTR;
val.bstrVal = SysAllocString(L"Author Name");
pBag->Write(L"INFO/IART", &val);
pPersist->Load(pBag, NULL);
VariantClear(&val);

AVI スプリッタ フィルタおよび WAV パーサーは、このメソッドをサポートしない。

IPersistMediaPropertyBag::Save

IPersistMediaPropertyBag インターフェイス

フィルタからのプロパティをメディア プロパティ バッグに保存する。

構文

HRESULT Save(
    IMediaPropertyBag *pPropBag
    BOOL fClearDirty
    BOOL fSaveAllProperties
);

パラメータ

pPropBag
[in] 呼び出し元で作成したメディア プロパティ バッグの IMediaPropertyBag インターフェイスへのポインタ。
fClearDirty
[in] 予約済み。任意の値。
fSaveAllProperties
[in] 予約済み。任意の値。

戻り値

HRESULT 値を返す。設定される値は次のとおりである。

S_OK | 成功。
E_NOTIMPL | 実装されていない。
E_OUTOFMEMORY | メモリ不足。
HRESULT_FROM_WIN32(ERROR_INVALID_DATA) | 無効なデータ。

注意

AVI スプリッタ フィルタまたは WAV パーサーのこのメソッドを呼び出すと、フィルタはファイルから INFO チャンクおよび DISP チャンクを読み取り、それをメディア プロパティ バッグに格納する。これらのチャンクを取得するには、IMediaPropertyBag::Read メソッドまたは IMediaPropertyBag::EnumProperty メソッドを使用する。

AVI Mux フィルタはこのメソッドを実装しない。


IPin インターフェイス

このインターフェイスはすべての入力ピン、出力ピンによって公開される。

フィルタ グラフ マネージャはこのインターフェイスを使ってピンと接続し、フラッシュ処理を行う。アプリケーションはこのインターフェイスを使ってピンの情報を問い合わせることができる。アプリケーションは IPin メソッドを呼び出して、Connect や Disconnect や BeginFlush や EndFlush のようなピンの状態の変更を起こってはならない。ピンを接続するには、アプリケーションは IGraphBuilder 内のメソッドを使用しなければならない。

フィルタ 開発者 : CBasePin と CBaseInputPin と CBaseOutputPin クラスはこのインターフェイスを実装する。他の基底クラスはこれら 3 つのクラスから派生する。

Vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを返す。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IPin メソッド | 説明
Connect | ピンを他のピンと接続する。
ReceiveConnection | 他のピンからの接続を許可する。
Disconnect | 現在のピン接続を解除する。
ConnectedTo | このピンに接続しているピンを取得する。
ConnectionMediaType | 現在のピン接続のメディア タイプを取得する。
QueryPinInfo | 名前、所有者フィルタ、向きなどのピンについての情報を取得する。
QueryId | ピン識別子を取得する。
QueryAccept | 指定したメディアタイプをピンが許容するかどうかを確認する。
EnumMediaTypes | ピンの優先メディアタイプを列挙する。
QueryInternalConnections | このピンに (フィルタ内で) 内部的に接続しているピンを取得する。
EndOfStream | 追加データはもうないことをピンに通知する。
BeginFlush | フラッシュ処理を開始する。
EndFlush | フラッシュ処理を終了する。
NewSegment | この呼び出しの後に受け取ったメディア サンプルがセグメント グループであることをピンに通知する。
QueryDirection | ピンの向き (入力ピンか出力ピンか) を取得する。

IPin::BeginFlush

IPin インターフェイス

フラッシュ処理を開始する。

構文

HRESULT BeginFlush(void);

戻り値

成功なら S_OK を返す、あるいはエラーの原因を示す HRESULT 値を返す。

注意

フラッシュ処理中に、フィルタはそれが処理したどのデータをも廃棄する。フラッシュが完了するまで新しいデータは拒絶される。アップストリーム ピンが IPin::EndFlush を呼び出すと、フラッシュは完了する。フラッシュによってイベントが通常のデータフローを変更するときのフィルタ グラフのレスポンスが改善される。たとえば、シーク中にフラッシュは行われる。

BeginFlush が呼び出されると、フィルタ グラフは以下のステップを行う :

  1. IPin::BeginFlush 呼び出しをダウンストリームに渡す。
  2. IMemInputPin::Receive のようなすべてのデータ ストリーミング メソッドを失敗させる内部フラグを設定する。
  3. すべてのブロックが Receive メソッドへの呼び出しを返す。

BeginFlush 通知が レンダラ フィルタに届くと、レンダラは保持しているすべてのサンプルを解放する。

BeginFlush が呼び出された後、IPin::EndFlush メソッドが呼び出されるまで、ピンはアップストリームからのすべてのサンプルを受け付けずに S_FALSE を返す。

参照

フィルタ開発者が使用するデータ フロー

IPin::Connect

IPin インターフェイス

ピンを他のピンと接続する。

構文

HRESULT Connect(
    IPin *pReceivePin,
    const AM_MEDIA_TYPE *pmt
);

パラメータ

pReceivePin
[in] ピンの IPin インターフェイスを受け取るポインタ。
pmt
[in] 接続のメディア タイプを指定する AM_MEDIA_TYPE 構造体へのポインタ。NULL が可能。

戻り値

HRESULT 値を返す。以下のいずれかの値。

S_OK | 成功。
VFW_E_ALREADY_CONNECTED | ピンは既に接続されている。
VFW_E_NO_ACCEPTABLE_TYPES | 許可されたメディア タイプを見つけることができなかった。
VFW_E_NOT_STOPPED | フィルタがアクティブで、ピンが動的再接続をサポートしていない。
VFW_E_TYPE_NOT_ACCEPTED | 指定したメディア タイプは許可されない。

注意

pmt パラメータは NULL が可能。メジャー タイプやサブタイプやフォーマットに GUID_NULL の値を入れて部分的メディアタイプを指定することも可能。

このメソッドは接続が可能なことを検証する。ピンが接続を拒否すれば、メソッドは失敗する。受信ピンで IPin::ReceiveConnection を呼び出すことで、接続ピンはメディア タイプを提案する。

IPin::ConnectedTo

IPin インターフェイス

もしあれば、このピンに接続しているピンを取得する。

構文

HRESULT ConnectedTo(
    IPin **ppPin
);

パラメータ

ppPin
[out] 他のピンの IPin インターフェイスへのポインタを受け取る変数のアドレス。NULL は不可。

戻り値

HRESULT 値を返す。以下のいずれかの値。

S_OK | 成功。
E_POINTER | NULL ポインタ引数。
VFW_E_NOT_CONNECTED | ピンが接続されていない。

注意

メソッドが成功すれば、それを返す IPin インターフェイスは参照カウントが残る。使用後、解放に注意。

IPin::ConnectionMediaType

IPin インターフェイス

現在のピン接続のメディア タイプを取得する。

構文

HRESULT ConnectionMediaType(
    AM_MEDIA_TYPE *pmt
);

パラメータ

pmt
[out] メディア タイプを受け取る AM_MEDIA_TYPE 構造体へのポインタ。

戻り値

HRESULT 値を返す。以下のいずれかの値。

S_OK | 成功。
E_POINTER | NULL ポインタ引数。
VFW_E_NOT_CONNECTED | ピンが接続されていない。

注意

ピンが接続されると、このメソッドは pmt にが指定する AM_MEDIA_TYPE 構造体にメディア タイプをコピーする。呼び出し元はメディア タイプのフォーマット ブロックを解放しなければならない。Microsoft® Win32® CoTaskMemFree 関数か、FreeMediaType ヘルパー関数が使用できます。

ピンが接続されないと、このメソッドは pmt が指定するメディア タイプをクリアし、エラー コードを返す。

IPin::Disconnect

IPin インターフェイス

現在のピン接続を解除する。

構文

HRESULT Disconnect(void);

戻り値

HRESULT 値を返す。以下のいずれかの値。

S_FALSE | ピンが接続されていなかった。
S_OK | 成功。
VFW_E_NOT_STOPPED | フィルタがアクティブ。

注意

フィルタがポーズか実行中なら、このメソッドは失敗する。ピンが IPinConnection インターフェイスをサポートするなら、フィルタがポーズか実行中のとき、IPinConnection::DynamicDisconnect を呼び出してピンの接続を解除すること。

ピンはこのメソッドを使って接続解除をしてはならない。

IPin::EndFlush

IPin インターフェイス

フラッシュ処理を終了する。

構文

HRESULT EndFlush(void);

戻り値

成功なら S_OK を返す、あるいはエラーの原因を示す HRESULT 値を返す。

注意

このメソッドが呼び出されるとき、フィルタは以下の処理が行われる :

  1. キューにあるすべてのサンプルの廃棄を待つ。
  2. バッファにあるすべてのデータを解放する。
  3. 残っている EC_COMPLETE 通知をクリアする。
  4. EndFlush ダウンストリームを呼び出す。

メソッドが返ると、ピンは新しいサンプルを許可する。

参照

フィルタ開発者が使用するデータ フロー

IPin::EndOfStream

IPin インターフェイス

新しい実行コマンドがフィルタに発行されるまでは、追加データはもうないことをピンに通知する。

構文

HRESULT EndOfStream(void);

戻り値

以下の HRESULT 値の 1 つを返す。

S_OK | 成功。
E_UNEXPECTED | ピンはこのメソッドをサポートしていない。

注意

このメソッドは入力ピンでのみ呼び出しすること。出力ピンは E_UNEXPECTED を返す。

このメソッドはエンドオブストリーム (end-of-stream) 通知をピンに送る。ピンはその通知をダウンストリームに送る。IMemInputPin::Receive を呼び出してエンドオブストリーム通知を継続して処理しなければならない。ピンが出力すべきメディア サンプルをキューに入れるなら、エンドオブストリーム通知も同様にキューに入れるべきである。IPin::BeginFlush メソッドはキュー内のすべてのエンドオブストリーム通知をフラッシュする。

IPin::EnumMediaTypes

IPin インターフェイス

ピンの優先メディアタイプを列挙する。

構文

HRESULT EnumMediaTypes(
    IEnumMediaTypes **ppEnum
);

パラメータ

ppEnum
[out] IEnumMediaTypes インターフェイスへのポインタを受け取る変数のアドレス。

戻り値

HRESULT 値を返す。以下のいずれかの値。

S_OK | 成功。
E_OUTOFMEMORY | メモリ不足。
E_POINTER | NULL ポインタ引数。

注意

IEnumMediaTypes インターフェイスは標準 COM 列挙子のように動作する。詳細については、「Enumerating Objects in a Filter Graph」を参照すること。メソッドが成功すると、IEnumMediaTypes インターフェイスに参照カウントが残る。使用後、解放に注意。

IPin::NewSegment

IPin インターフェイス

この呼び出しの後に受け取ったメディア サンプルが、共通の開始タイムと終了タイムとレートを持つセグメント グループであることをピンに通知する。

構文

HRESULT NewSegment(
    REFERENCE_TIME tStart,
    REFERENCE_TIME tStop,
    double dRate
);

パラメータ

tStart
セグメントの開始タイム、オリジナル ソースの相対値、100ナノ秒単位。
tStop
セグメントの終了タイム、オリジナル ソースの相対値、100ナノ秒単位
dRate
セグメントが処理されるレート、オリジナル レートのパーセンテージ。

戻り値

成功なら S_OK を返す、あるいはエラーの原因を示す HRESULT 値を返す。

注意

新しいストリームを開始するたびとシーク操作が終わるたびに、ソース フィルタ (あるいはパーサーフィルタ) はこのメソッドを呼び出す。以前のデータバッチを出力した後で、新しいデータで IMemInputPin::Receive を呼び出す前に、それはダウンストリーム フィルタの入力ピンのメソッドを呼び出す。ダウンストリーム フィルタは NewSegment 呼び出しをダウンストリームに継承する。

フィルタはセグメント情報を使ってサンプルを処理する。たとえば、いくつかのフォーマットでは次のフレームなしでデルタ フレームを再構築することはできない。それゆえ、終了タイムがデルタ フレームにあると、ソース フィルタは追加フレームを送らなければならない。デコーダ フィルタはセグメント情報を基に最終フレームを決定する。たとえば、オーディオ レンダラはサンプリング レートとセグメント レートを使って、オーディオ データを正しくレンダリングする。

IPin::QueryAccept

IPin インターフェイス

指定したメディアタイプをピンが許容するかどうかを確認する。

構文

HRESULT QueryAccept(
    const AM_MEDIA_TYPE *pmt
);

パラメータ

pmt
[in] メディア タイプを指定する AM_MEDIA_TYPE 構造体へのポインタ。

戻り値

メディアタイプが許容されるなら S_TRUE を返す。そうでなければ、S_FALSE を返す。

注意

S_OK が返るなら、フィルタ実行中にピンが指定したフォーマットに変更できることが保証される。フィルタ実行中にフォーマットを変更する必要があり、ピンが IPinConnection をサポートするなら、IPinConnection::DynamicQueryAccept メソッドを呼び出すこと。

IPin::QueryDirection

IPin インターフェイス

ピンの向き (入力ピンか出力ピンか) を取得する。

構文

HRESULT QueryDirection(
    PIN_DIRECTION *pPinDir
);

パラメータ

pPinDir
[out] PIN_DIRECTION 列挙型のメンバを受け取る変数へのポインタ。

戻り値

HRESULT 値を返す。以下のいずれかの値。

S_OK | 成功。
E_POINTER | NULL ポインタ引数。

IPin::QueryId

IPin インターフェイス

ピン識別子を取得する

構文

HRESULT QueryId(
    LPWSTR *Id
);

パラメータ

Id
[out] ピン識別子が入る文字列を受け取る変数のアドレス。

戻り値

HRESULT 値を返す。以下のいずれかの値。

S_OK | 成功。
E_OUTOFMEMORY | メモリ不足。
E_POINTER | NULL ポインタ引数。

注意

このメソッドはグラフ永続性をサポートする。このメソッドを使用してピンの状態を保存し、IBaseFilter::FindPin メソッドを使ってその状態をリストアすること。ピン識別文字列はフィルタ実装によって定義されている。その識別子はフィルタ内でユニークでなければならない。

注 ピン ID は必ずしもQueryPinInfo メソッドが返す ピン名 と同じではない。

フィルタは Microsoft® Win32® CoTaskMemAlloc 関数を使用して返った文字列を割り当てる。呼び出し元は CoTaskMemFree を使ってそれを解放しなければならない。

IPin::QueryInternalConnections

IPin インターフェイス

このピンに (フィルタ内で) 内部的に接続しているピンを取得する。

構文

HRESULT QueryInternalConnections(
    IPin **apPin,
    ULONG *nPin
);

パラメータ

apPin
[out] IPin ポインタの配列のアドレス。
nPin
[in, out] 入力時は配列のサイズを指定する。メソッドが返ると、この値は配列内に返るポインタの数がセットされる。

戻り値

以下の HRESULT 値の 1 つを返す。

S_FALSE | 不適切な配列サイズ。
S_OK | 成功。
E_FAIL | 失敗。
E_NOTIMPL | 実装されていない。

注意

いくつかのフィルタでは、入力ピンは固有の出力ピンに対応している。各ピンについて、このメソッドは対応するピンへのポインタの配列を書き込む。各入力ピンが各出力ピンにデータを提供するなら、ピンは E_NOTIMPL を返す。

メソッドが成功し、ゼロ以上の *nPin 値を返すと、その配列には IPin インターフェイスへのポインタが入る。使用後、各インターフェイス ポインタの解放に注意すること。

IPin::QueryPinInfo

IPin インターフェイス

ピンについての情報を取得する。

構文

HRESULT QueryPinInfo(
    PIN_INFO *pInfo
);

パラメータ

pInfo
[out] ピン情報を受け取る PIN_INFO 構造体へのポインタ。

戻り値

HRESULT 値を返す。以下のいずれかの値。

S_OK | 成功。
E_POINTER | NULL ポインタ引数。

注意

メソッドが返るとき、PIN_INFO 構造体の pFilter メンバが NULL 以外なら、参照カウントが残る。使用後インターフェイスの解放に注意すること。

IPin::ReceiveConnection

IPin インターフェイス

他のピンからの接続を許可する。

構文

HRESULT ReceiveConnection(
    IPin *pConnector,
    AM_MEDIA_TYPE *pmt
);

パラメータ

pConnector
[in] 接続しているピンの IPin インターフェイスへのポインタ。
pmt
[in] 接続のメディア タイプを指定する AM_MEDIA_TYPE 構造体へのポインタ。

戻り値

HRESULT 値を返す。以下のいずれかの値。

S_OK | 成功。
E_POINTER | NULL ポインタ引数。
VFW_E_ALREADY_CONNECTED | ピンは既に接続している。
VFW_E_NOT_STOPPED | フィルタがアクティブな間は接続できない。
VFW_E_TYPE_NOT_ACCEPTED | 指定したメディア タイプが許可されない。

注意

接続を初期化するピンはこのメソッドを受信ピンで呼び出す。受信ピンがエラー コードを返すなら、接続は失敗する。


IPinConnection インターフェイス

このインターフェイスは、フィルタがまだ実行中のときに入力ピンを再接続するメソッドを提供する。フィルタ グラフは、動的な再接続を実行するとき、このインターフェイスのメソッドを呼び出す (「IGraphConfig インターフェイス」を参照すること)。詳細については、「動的グラフ作成」を参照すること。

フィルタ開発者へ : 動的な再接続、またはフォーマットの動的な変更を許すすべての入力ピンに、このインターフェイスを実装すること。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IPinConnection メソッド | 説明
DynamicQueryAccept | 現在このピンに接続しているグラフの実行中に、指定されたメディア タイプをピンが受け付けることができるかどうかを照会する。
NotifyEndOfStream | 次にエンドオブストリーム条件が発生したとき通知するようにピンに要求する。
IsEndPin | 再接続の検索をこのピンで終了すべきかどうかを示す。
DynamicDisconnect | フィルタ実行中にピンを切断する。

IPinConnection::DynamicDisconnect

IPinConnection インターフェイス

フィルタがアクティブなとき (ポーズ中または実行中) にピンを切断する。アクティブなフィルタのピンを切断するには、IPin::Disconnect ではなくこのメソッドを呼び出す。

構文

HRESULT DynamicDisconnect(void)

戻り値

ピンが接続されていて、メソッドが成功した場合、戻り値は S_OK になる。ピンが接続されなかった場合、戻り値は S_FALSE になる。

メソッドが成功した場合は、エラーの原因を示す HRESULT 値を返す。

IPinConnection::DynamicQueryAccept

IPinConnection インターフェイス

現在このピンに接続しているグラフの実行中に、指定されたメディア タイプをピンが受け付けることができるかどうかを照会する。

構文

HRESULT DynamicQueryAccept(
    const AM_MEDIA_TYPE *pmt
);

パラメータ

pmt
[in] メディア タイプを指定する AM_MEDIA_TYPE 構造体へのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | メディア タイプが受け付けられる。
VFW_E_TYPE_NOT_ACCEPTED | メディア タイプが受け付けられない。

注意

このメソッドが成功した場合、ピンは、次のサンプル上のメディア タイプ、または IPin::ReceiveConnection の呼び出しで指定されるメディア タイプを受け付けることができる。

アプリケーションまたはフィルタでは、このメソッドを呼び出して、フィルタ グラフを再構成する必要があるかどうか判断できる。指定したメディア タイプをピンが受け付けることができるなら、グラフを再構成する必要はない。

IPin::QueryAccept メソッドは、ピンがフォーマット タイプを受け付けることができるかどうかも判断する。ただし、フォーマット タイプ受け付けられても、フィルタ実行中にピンがそのフォーマットに切り替わることができるとは限らない。フィルタ実行中にフォーマットを切り替える必要がある場合は、代わりに DynamicQueryAccept を呼び出す。

IPinConnection::IsEndPin

IPinConnection インターフェイス

再接続の検索をこのピンで終了すべきかどうかを示す。

構文

HRESULT IsEndPin(void);

戻り値

成功した場合は、次のいずれかの HRESULT 値を返す。

S_FALSE | メディア タイプが受け付けられない。
S_OK | メディア タイプが受け付けられる。

それ以外の場合は、発生したエラーを示すエラー コードを返す。

注意

フィルタまたはアプリケーションでは、このメソッドを呼び出して、ピンが動的な再接続の候補となりうるかどうかを判断できる。

通常、シンク フィルタとデータを分割またはマージするフィルタは、S_OK を返さなければならない。その他のフィルタ (たとえば単純な変換フィルタ) は、S_FALSE を返さなければならない。

IPinConnection::NotifyEndOfStream

IPinConnection インターフェイス

次にエンドオブストリーム条件が発生したとき通知するようにピンに要求する。

構文

HRESULT NotifyEndOfStream(
    HANDLE hNotifyEvent
);

パラメータ

hNotifyEvent
[in] ピンが通知するイベント オブジェクトのハンドル。

戻り値

成功した場合は、次のいずれかの HRESULT 値を返す。

S_FALSE | イベント ハンドルが NULL だが、リセットするイベント ハンドルが存在しなかった。
S_OK | イベント ハンドルが設定された (イベント ハンドルが NULL の場合、イベント通知は取り消される)。

それ以外の場合は、発生したエラーを示すエラー コードを返す。

注意

このメソッドを使用すると、フィルタ グラフのこのピンまでの部分を通じて、呼び出し元がデータを引き渡すことができる。

たとえば、呼び出し元が、あるフィルタの出力ピン "A" から別のフィルタの入力ピン "B" へ、必要に応じてそれらを接続する中間フィルタを使用してデータを引き渡す場合を考える。このとき、次の一連のイベントが発生する。

  1. 呼び出し元が、ピン A でデータをブロックする。
  2. ピン B の IPinConnection::NotifyEndOfStream を呼び出す。
  3. ピン A に接続されている入力ピンの IPin::EndOfStream を呼び出す。
  4. 残りのデータが中間フィルタを通じてダウンストリームへ流れていくと、それらのフィルタがエンドオブストリーム通知を伝達する。
  5. ピン B は、エンドオブストリーム通知を受け取ると、hNotifyEvent パラメータに指定されたイベントを通知する。その時点で、呼び出し元は ピン A とピン B の間のグラフを安全に再構成できる。

このメソッドの目的は、呼び出し元からグラフを動的に再構築し、接続を再開することにあるため、エンドオブストリーム通知はストリーム実際の終了を意味しない。したがって、ピン B は、エンドオブストリーム条件を伝達することも、EC_COMPLETE を通知することもない。フィルタ グラフ内でのデータの流れにおける通常の規則から見ると、これは例外的な動作である。

このメソッドをもう一度イベント ハンドル NULL で呼び出して通知を取り消すことは、呼び出し元の責任である。

フィルタ グラフでは、IGraphConfig::Reconnect メソッド内でこのメソッドを呼び出す。アプリケーションまたはフィルタで (IGraphConfig::Reconfigure メソッドを使用して) グラフに何らかの特殊な動的再構成を行う場合は、再構成するグラフの部分を通じてデータを引き渡すため、最初にこのメソッドを呼び出す可能性がある。


IPinFlowControl インターフェイス

アクティブな出力ピンからデータ フローをブロックする。このインターフェイスは動的再接続可能な出力ピンによって公開される。このインターフェイスを使ってフィルタ グラフなしで動的再接続を開始する。詳細については、「動的グラフ作成」を参照すること。

フィルタ開発者へ : 動的な再接続をサポートするパーサー フィルタとキャプチャ フィルタでは、その出力ピン上でこのインターフェイスをサポートしなければならない。通常、その他のタイプのフィルタでは、このインターフェイスを実装する必要はない。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IPinFlowControl メソッド | 説明
Block | ピンからのデータ フローをブロック、あるいはブロック解除する。

IPinFlowControl::Block

IPinFlowControl インターフェイス

ピンからのデータフローをブロック、あるいはブロック解除する。

構文

HRESULT Block(
    DWORD dwBlockFlags,
    HANDLE hEvent,
);

パラメータ

dwBlockFlags
[in] ピンをブロックするかブロック解除するかを示すフラグ。以下の値でなければならない :
  • ゼロ : ピンからのデータ フローをブロック解除する。
  • AM_PIN_FLOW_CONTROL_BLOCK: ピンからのデータ フローをブロックする。
hEvent
[in] イベント オブジェクトのハンドルまたは NULL。このパラメータが NULL でない場合、メソッドは非同期になり、即座に戻る。操作が完了すると、イベントが通知済になる。このパラメータが NULL の場合、メソッドは同期になり、ピンがブロックされるまで完了しない。dwBlockFlags がゼロなら、このパラメータは NULL でなければならない。

戻り値

HRESULT 値を返す。以下のいずれかの値。

S_FALSE | ピンは既にブロック解除されている。
S_OK | 成功。
VFW_E_PIN_ALREADY_BLOCKED | ピンは他のスレッドによって既にブロックされている。
VFW_E_PIN_ALREADY_BLOCKED_ON_THIS_THREAD | ピンは呼び出しているスレッドによって既にブロックされている。

注意

このメソッドは同期も非同期も可能である :

  • 非同期に呼び出すには、CreateEvent 関数を使ってイベントオブジェクトを作成する。イベント ハンドルを hEvent パラメータに渡す。メソッドはすぐに戻り、操作が完了するとイベントを通知する。WaitForSingleObject のような待ち関数を呼び出してそのイベントを待つこと。
  • 同期して呼び出すには、hEvent パラメータを NULL に設定する。そのメソッドは完了するまでブロックする。メソッドはピンがサンプル出力する用意ができるまで完了しない可能性がある。フィルタがポーズなら、メソッドは完全にブロックする可能性がある。それゆえ、メインのアプリケーションスレッドからこのメソッドを同期して呼び出すべきではない。


IPinInfo インターフェイス

このインターフェイスは、ピンに関する情報の取得およびピンの接続を行う Automation 互換のメソッドを提供する。フィルタ グラフ マネージャがこのインターフェイスを公開する。

Microsoft® Visual Basic® アプリケーションでは、このインターフェイスを使用して、ピンに関する情報 (メディア タイプ、ピンの方向など) を取得できる。また、必要に応じて中間フィルタを使用してピンを接続することもできる。

C/C++ アプリケーションでは、このインターフェイスではなく、IGraphBuilder インターフェイスおよび IPin インターフェイスを使用すること。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IDispatch メソッド | 説明
GetTypeInfoCount | このディスプインターフェイスに利用可能なタイプ情報があるかどうか判断する。
GetTypeInfo | GetTypeInfoCount が成功した場合は、このディスプインターフェイスのタイプ情報を取得する。
GetIDsOfNames | (引数を含む) プロパティおよびメソッドのテキスト名を対応する DISPID に変換する。
Invoke | DISPID およびその他の必要なパラメータが指定された場合は、このディスプインターフェイスのメソッドを呼び出すか、またはプロパティにアクセスする。
IPinInfo メソッド | 説明
get_Pin | IPin インターフェイスをサポートするピン オブジェクトを取得する。
get_ConnectedTo | このピンが接続している対応するピンに対応する IPinInfo オブジェクトを取得する。
get_ConnectionMediaType | この接続のメディア タイプを取得する。
get_FilterInfo | このピンが属するフィルタに対応する IFilterInfo オブジェクトを取得する。
get_Name | このピンの名前を取得する。
get_Direction | ピンの方向を取得する。
get_PinID | ピン識別子を取得する。
get_MediaTypes | このピンがサポートする優先メディア タイプへのアクセスを提供する IAMCollection インターフェイスを取得する。
Connect | 指定されたピンに接続する。
ConnectDirect | 指定されたピンに直接接続する。
ConnectWithType | 指定されたメディア タイプだけを使用して、指定されたピンに直接接続する。
Disconnect | このピンを接続先のピンから切断する。
Render | ピンのメディア タイプをレンダリングできるフィルタ グラフを作成する。

IPinInfo::Connect

IPinInfo インターフェイス

必要に応じてほかの変換フィルタを使用し、指定されたピンに接続する。

構文

HRESULT Connect(
    IUnknown *pPin
    );

パラメータ

pPin
[in] 接続先のピンへのポインタ。

戻り値

HRESULT 値を返す。

注意

pPin パラメータは、IPin でも IPinInfo オブジェクトでもよい。このメソッドは、このピンと指定されたピンとの接続を有効にするために必要な変換フィルタを、グラフ ビルダを使用して判断する。たとえば、ピンがソース フィルタの出力ピンであり、要求された接続先がビデオ レンダラの入力ピンである場合は、有効なフィルタ グラフにするために、適切なメディア タイプを持つデコンプレッサ フィルタを挿入する。このメソッドは、本来、IGraphBuilder::Connect メソッドに対応する Automation ラッパーである。

IPinInfo::ConnectDirect

IPinInfo インターフェイス

中間フィルタを使用せずに、所定のピンに直接接続する。

構文

HRESULT ConnectDirect(
  IUnknown *pPin
  );

パラメータ

pPin
[in] 直接接続する接続先のピンへのポインタ。

戻り値

HRESULT 値を返す。

注意

接続するピンの間で共通のメディア タイプを決められない場合、このメソッドはエラーを返す。このメソッドは、本来、IFilterGraph::ConnectDirect メソッドに対応する Automation ラッパーである。

IPinInfo::ConnectWithType

IPinInfo インターフェイス

指定されたメディア タイプを使用して、指定されたピンに直接接続する。

構文

HRESULT ConnectWithType(
  IUnknown *pPin,
  IDispatch *pMediaType
  );

パラメータ

pPin
[in] 接続先のピンへのポインタ。pPin は、IPin インターフェイスおよび IPinInfo インターフェイスのどちらかをサポートするオブジェクトでなければならない。
pMediaType
[in] ピンの接続に使用するメディア タイプへのポインタ。pMediaType は、IMediaTypeInfo インターフェイスをサポートする必要がある。

戻り値

HRESULT 値を返す。

注意

このメソッドを使用すると、接続のメディア タイプを接続時にピン側で決めるのではなく、呼び出し元で決定することができる。

IPinInfo::Disconnect

IPinInfo インターフェイス

このピンを接続先のピンから切断する。

構文

HRESULT Disconnect(void);

戻り値

HRESULT 値を返す。

注意

このメソッドは、両方のピンの IPin::Disconnect を呼び出す。

IPinInfo::get_ConnectedTo

IPinInfo インターフェイス

接続先のピンに対応する IPinInfo インターフェイスを取得する。

構文

HRESULT get_ConnectedTo(
  IDispatch **ppUnk
  );

パラメータ

ppUnk
[out, retval] ピンに対応する IPinInfo インターフェイスへのポインタのアドレス。

戻り値

HRESULT 値を返す。

注意

このメソッドは、本来、IPin::ConnectedTo メソッドに対応する Automation ラッパーである。

IPinInfo::get_ConnectionMediaType

IPinInfo インターフェイス

コネクション情報が格納された IMediaTypeInfo オブジェクトを取得する。

構文

HRESULT get_ConnectionMediaType(
  IDispatch **ppUnk
  );

パラメータ

ppUnk
[out, retval] 返された IMediaTypeInfo インターフェイスへのポインタのアドレス。

戻り値

HRESULT 値を返す。

注意

このメソッドは、本来、IPin::ConnectionMediaType メソッドに対応する Automation ラッパーである。

IPinInfo::get_Direction

IPinInfo インターフェイス

ピンの方向を取得する。

構文

HRESULT get_Direction(
  LONG *ppDirection
  );

パラメータ

ppDirection
[out, retval] ピンの方向へのポインタのアドレス。ピンの方向は、PINDIR_INPUT と PINDIR_OUTPUT のどちらかである。

戻り値

HRESULT 値を返す。

IPinInfo::get_FilterInfo

IPinInfo インターフェイス

このピンが属するフィルタに対応する IFilterInfo インターフェイスを取得する。

構文

HRESULT get_FilterInfo(
  IDispatch **ppUnk
  );

パラメータ

ppUnk
[out, retval] 取得された IFilterInfo インターフェイスへのポインタのアドレス。

戻り値

HRESULT 値を返す。

IPinInfo::get_MediaTypes

IPinInfo インターフェイス

このピンがサポートする優先メディア タイプへのアクセスを提供する IAMCollection インターフェイスを取得する。

構文

HRESULT get_MediaTypes(
  IDispatch **ppUnk
  );

パラメータ

ppUnk
[out, retval] IMediaTypeInfo オブジェクトとして優先されるメディア タイプが格納された IAMCollection インターフェイスへのポインタのアドレス。

戻り値

HRESULT 値を返す。

注意

このメソッドは、本来、IPin::EnumMediaTypes メソッドに対応する Automation ラッパーである。

IPinInfo::get_Name

IPinInfo インターフェイス

このピンの名前を取得する。

構文

HRESULT get_Name(
  BSTR **ppUnk
  );

パラメータ

ppUnk
[out, retval] ピンの名前へのポインタのアドレス。

戻り値

HRESULT 値を返す。

IPinInfo::get_Pin

IPinInfo インターフェイス

IPin インターフェイスをサポートするピン オブジェクトを取得する。

構文

HRESULT get_Pin(
  IUnknown **ppUnk
  );

パラメータ

ppUnk
[out, retval] IPin をサポートする IUnknown オブジェクトへのポインタのアドレス。

戻り値

HRESULT 値を返す。

注意

IPinInfo インターフェイスは、ラッパー COM オブジェクトで実装される。したがって、このオブジェクトの IPin を照会する QueryInterface は失敗する。IPinInfo::get_Pin メソッドが返すピン オブジェクトで、IPin インターフェイスがサポートされる。

IPinInfo::get_PinID

IPinInfo インターフェイス

ピンの識別子を取得する。

構文

HRESULT get_PinID(
  BSTR *strPinID
  );

パラメータ

strPinID
[out, retval] ピンの識別子文字列へのポインタ。

戻り値

HRESULT 値を返す。

注意

strPinID に返された文字列は、IFilterInfo::FindPin に渡すことができる。この識別子は、ピンの名前と等しいことが多いが、異なる場合もある。2 次記憶に書き込み、後からフィルタの別のインスタンスに含まれる同じピンの識別に使用することができる。

IPinInfo::Render

IPinInfo インターフェイス

このピンの出力をレンダリングするために、必要に応じて変換フィルタおよびレンダリング フィルタを使用して、フィルタどうしを接続する。

構文

HRESULT Render(void);

戻り値

HRESULT 値を返す。

注意

このメソッドは、本来、IGraphBuilder::Render メソッドに対応する Automation ラッパーである。また、このメソッドは出力ピンでのみ有効である。


IQualityControl インターフェイス

このインターフェイスは、品質コントロールのサポートを提供する。品質コントロール メッセージを生成または取得できるオブジェクトは、このインターフェイスを公開する。そのようなオブジェクトには、レンダリング フィルタ (通常、品質コントロール メッセージを生成する)、ピン (それらを受け取る)、および外部の品質 マネージャ (やはりそれらを受け取る) が含まれる。

レンダリング フィルタは、アップストリーム フィルタの出力ピンの IQualityControl::Notify メソッドを呼び出して、品質コントロール メッセージを生成する。アップストリーム フィルタは、そのメッセージを処理するか、またはアップストリームに渡す。

アプリケーションでは、独自の品質コントロール マネージャを実装できる。品質コントロール メッセージの受信者として、その品質コントロール マネージャを指定するには、レンダラの IQualityControl::SetSink を呼び出す。このメソッドを呼び出すと、品質コントロール メッセージのデフォルト処理がオーバーライドされる。

ただし、多くのアプリケーションでは、独自の品質コントロール マネージャを実装しない。したがって、この特殊なケースを除き、通常、アプリケーションでこのインターフェイスを使用することはない。詳細については、「品質コントロールの管理」を参照すること。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IQualityControl メソッド | 説明
Notify | 品質の変更が要求されたことを受信者に通知する。
SetSink | 品質 メッセージを受け取る IQualityControl オブジェクトを設定する。

IQualityControl::Notify

IQualityControl インターフェイス

品質の変更が要求されたことをフィルタに通知する。

構文

HRESULT Notify(
    IBaseFilter *pSelf,
    Quality q
);

パラメータ

pSelf
[in] 品質通知の送信元フィルタへのポインタ。
q
[in] 品質通知の構造体。

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
S_OK または NOERROR | 成功。

IQualityControl::SetSink

IQualityControl インターフェイス

品質 メッセージを受け取る IQualityControl オブジェクトを設定する。

構文

HRESULT SetSink(
    IQualityControl *piqc
);

パラメータ

piqc
通知の送信先 IQualityControl オブジェクトへのポインタ。

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
S_OK または NOERROR | 成功。

注意

このメソッドの呼び出しを受け取るフィルタは、piqc を記録しなければならないが、それに参照カウントを追加してはならない。ポインタが指すオブジェクトは、品質 マネージャであり、フィルタ グラフ (たとえば、PID) の一部である。ここに参照カウントを追加すると、循環参照の危険性がある。

piqc で指定されたオブジェクトの参照は、このメソッドが値 NULL で呼び出されまで、有効であることが保証される。


IQualProp インターフェイス

このインターフェイスは、ビデオ レンダラからパフォーマンス情報を取得するメソッドを提供する。インターフェイスを通じて返される値は、フィルタを停止するたびにリセットされる。ビデオ レンダリング フィルタおよびフルスクリーン レンダリング フィルタは、このインターフェイスを公開する。

アプリケーションでは、このインターフェイスを使用してビデオのパフォーマンス情報を取得できる。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを返す。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IQualProp メソッド | 説明
get_AvgFrameRate | 達成された平均フレーム レートを取得する。
get_AvgSyncOffset | フレームの目標レンダリング時間とレンダリングが実際に開始した時間の平均時間差を取得する (ミリ秒単位の値で返される)。
get_DevSyncOffset | フレームの目標レンダリング時間とレンダリングが実際に開始した時間の平均時間差を取得する (標準偏差で返される)。
get_FramesDrawn | ストリーム開始後に描画されたフレーム数を取得する。
get_FramesDroppedInRenderer | レンダラでドロップされたフレーム数を取得する。
get_Jitter | ビデオ レンダラに渡される連続フレーム間の平均時間を表現する。

IQualProp::get_AvgFrameRate

IQualProp インターフェイス

ストリーム開始後の平均フレーム レートを取得する。

構文

HRESULT get_AvgFrameRate(
    int *piAvgFrameRate
    ) PURE;

パラメータ

piAvgFrameRate
ストリーム開始後の 1 秒あたりのフレーム数 (fps) へのポインタ。

戻り値

HRESULT 値を返す。

IQualProp::get_AvgSyncOffset

IQualProp インターフェイス

ビデオ フレームの目標表示時間と実際に表示された時間との平均時間差を取得する。

構文

HRESULT get_AvgSyncOffset(
    int *piAvg
    );

パラメータ

piAvg
時間差 (ミリ秒単位) へのポインタ。

戻り値

HRESULT 値を返す。

IQualProp::get_DevSyncOffset

IQualProp インターフェイス

ビデオ フレームの目標表示時間と実際に表示された時間との平均時間差を取得する。このメソッドは、値が単なる平均ではなく標準偏差で返される点を除き、IQualProp::get_AvgSyncOffset メソッドと同じである。

構文

HRESULT get_DevSyncOffset(
    int *piDev
    );

パラメータ

piDev
表示されるビデオ フレームの精度を表す値へのポインタ。

戻り値

HRESULT 値を返す。

注意

ネットワークからのビデオを再生するとき、ネットワークの状態が悪い場合には表示が中断することがある。このため、ビデオ フレームの精度を単なる平均値で表現することは適切でない。標準偏差を調べると、全体の精度をより正しく把握できる。

IQualProp::get_FramesDrawn

IQualProp インターフェイス

ストリーム開始後に描画されたフレーム数を取得する。

構文

HRESULT get_FramesDrawn(
    int *pcFramesDrawn
    );

パラメータ

pcFramesDrawn
ストリーム開始後に描画されたフレーム数へのポインタ。

戻り値

HRESULT 値を返す。

IQualProp::get_FramesDroppedInRenderer

IQualProp インターフェイス

レンダラでドロップされたフレーム数を取得する。

構文

HRESULT get_FramesDroppedInRenderer(
    int *pcFrames
    );

パラメータ

pcFrames
レンダラでドロップされたフレーム数へのポインタ。

戻り値

HRESULT 値を返す。

注意

プロパティ ページでは、このメソッドを使用してレンダラからデータが取得される。

IQualProp::get_Jitter

IQualProp インターフェイス

ビデオ レンダラに渡される連続フレーム間の平均時間を表現する。

構文

HRESULT get_Jitter(
    int *piJitter
    );

パラメータ

piJitter
フレーム間時間 (ミリ秒単位) の標準偏差へのポインタ。

戻り値

HRESULT 値を返す。


IQueueCommand インターフェイス

特定の時間に処理するためにコマンドをキューに入れる。フィルタ グラフ マネージャはそれを使ってグラフ管理コマンドを先にキューに入れることができる。

IQueueCommand 内のメソッドは IDispatch::InvokeAt メソッドの後で設計された。アプリケーションはインターフェイスとインターフェイスのメソッドと、メソッドのパラメータと、基準タイムを指定する。フィルタ グラフ マネージャはこの情報をキューに入れ、次に指定した時間にこのメソッドを起動する。リクエストされたインターフェイスは IDispatch を継承し、フィルタ グラフ マネージャによって公開されなければならない。例としては IMediaControl、IMediaEventEx、および IMediaPosition が挙げられる。

コマンドがキューに入れられると、フィルタ グラフ マネージャは IDeferredCommand インターフェイスへのポインタを返す。アプリケーションは、このインターフェイスを使用してそのコマンドを取り消したり変更したりすることができる。

注 : IQueueCommand には、InvokeAtStreamTime と InvokeAtPresentationTime の 2 つのメソッドがある。フィルタ グラフ マネージャのコンテキストでは、ストリーム タイムとプレゼンテーション時間が等しいため、この 2 つのメソッドに機能上の差はない。ただし、その他のオブジェクトでは、それとは異なった IQueueCommand を実装する可能性がある。ストリーム タイムとプレゼンテーション時間の詳細については、「DirectShow のタイムとクロック」を参照すること。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを返す。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IQueueCommand メソッド | 説明
InvokeAtStreamTime | 指定されたストリーム タイムに起動するため、メソッドをキューに入れる。
InvokeAtPresentationTime | 指定されたプレゼンテーション時間に起動するため、メソッドをキューに入れる。

IQueueCommand::InvokeAtPresentationTime

IQueueCommand インターフェイス

指定されたストリーム タイムに起動するため、メソッドをキューに入れる。

構文

HRESULT InvokeAtPresentationTime(
    IDeferredCommand **pCmd,
    REFTIME time,
    GUID *iid,
    long dispidMember,
    short wFlags,
    long cArgs,
    VARIANT *pDispParams,
    VARIANT *pvarResult,
    short *puArgErr
);

パラメータ

pCmd
[out] IDeferredCommand インターフェイス ポインタを受け取る変数へのポインタ。
time
[in] コマンドを起動する時間。
iid
[in] インターフェイスのインターフェイス識別子 (IID) へのポインタ。
dispidMember
[in] インターフェイスのメソッドまたはプロパティのディスパッチ識別子 (DISPID)。IDispatch::InvokeAt メソッドの dispIdMember パラメータと同等。
wFlags
[in] 呼び出しのコンテキストを記述するフラグ。IDispatch::InvokeAt メソッドの wFlags パラメータと同等。
cArgs
[in] pDispParams 内の引数の数。DISPPARAMS 構造体の cArgs メンバと同等。
pDispParams
[in] 引数が格納された配列へのポインタ。DISPPARAMS 構造体の rgvarg メンバと同等。
pvarResult
[in, out] 結果を受け取る VARIANT へのポインタ。IDispatch::InvokeAt メソッドの pVarResult パラメータと同等。
puArgErr
[out] 最初にエラーが発生した引数のインデックスを受け取る変数へのポインタ。IDispatch::InvokeAt メソッドの puArgErr パラメータと同等。

戻り値

HRESULT 値を返す。

注意

dispidMember パラメータのための DISPID を取得するには、IDispatch::GetIDsOfNames メソッドを使用する。

IQueueCommand::InvokeAtStreamTime

IQueueCommand インターフェイス

特定のストリーム タイム (つまり、現在のストリーム タイム オフセットとプレゼンテーション時間の差) に実行するため、メソッドまたはプロパティの変更をキューに入れる。

構文

HRESULT InvokeAtStreamTime(
    IDeferredCommand **pCmd,
    REFTIME time,
    GUID *iid,
    long dispidMember,
    short wFlags,
    long cArgs,
    VARIANT *pDispParams,
    VARIANT *pvarResult,
    short *puArgErr
);

パラメータ

pCmd
[out] IDeferredCommand インターフェイス ポインタを受け取る変数へのポインタ。
time
[in] コマンドを起動する時間。
iid
[in] インターフェイスのインターフェイス識別子 (IID) へのポインタ。
dispidMember
[in] インターフェイスのメソッドまたはプロパティのディスパッチ識別子 (DISPID)。IDispatch::InvokeAt メソッドの dispIdMember パラメータと同等。
wFlags
[in] 呼び出しのコンテキストを記述するフラグ。IDispatch::InvokeAt メソッドの wFlags パラメータと同等。
cArgs
[in] pDispParams 内の引数の数。DISPPARAMS 構造体の cArgs メンバと同等。
pDispParams
[in] 引数が格納された配列へのポインタ。DISPPARAMS 構造体の rgvarg メンバと同等。
pvarResult
[in, out] 結果を受け取る VARIANT へのポインタ。IDispatch::InvokeAt メソッドの pVarResult パラメータと同等。
puArgErr
[out] 最初にエラーが発生した引数のインデックスを受け取る変数へのポインタ。IDispatch::InvokeAt メソッドの puArgErr パラメータと同等。

戻り値

HRESULT 値を返す。

注意

dispidMember パラメータのための DISPID を取得するには、IDispatch::GetIDsOfNames メソッドを使用する。


IReferenceClock インターフェイス

フィルタ グラフに基準タイムを提供する。

基準クロックとしての機能を持つフィルタは、このインターフェイスを公開できる。このインターフェイスは、システム基準クロックでも公開される。フィルタ グラフ マネージャは、このインターフェイスを使用してフィルタ グラフの同期をとる。アプリケーションでは、このインターフェイスを使用して、現在の基準タイムを取得したり、経過時間の通知を要求したりできる。

詳細については、「DirectShow のタイムとクロック」を参照すること。

フィルタ開発者へ : 信頼性の高いクロック タイムを生成するフィルタを開発するには、このインターフェイスを実装すること。たとえば、サウンド ボードには基準クロックが付いていることが多いので、オーディオ レンダリング フィルタはこのインターフェイスを実装する。このインターフェイスを実装するには、CBaseReferenceClock クラスを使用すること。

非レンダリング フィルタがフィルタグラフマネージャから参照クロックとして選択されるチャンスを増やすには、以下のステップ :

  1. そのフィルタ内で IReferenceClock を実装する。
  2. そのフィルタ内で IAMFilterMiscFlags を実装する。
  3. IAMFilterMiscFlags::GetMiscFlags から AM_FILTER_MISC_FLAGS_IS_SOURCE を返す。
  4. すべての出力ピンで IAMPushSource を実装する。
  5. IAMPushSource::GetPushSourceFlags から (* pFlags) = 0 を返す。
  6. すべての他の IAMPushSource メソッドから E_NOTIMPL を返す。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを返す。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IReferenceClock メソッド | 説明
GetTime | 現在の基準タイムを取得する。
AdviseTime | 単発のアドバイズ要求を作成する。
AdvisePeriodic | 周期的なアドバイズ要求を作成する。
Unadvise | 保留中のアドバイズ要求を削除する。

IReferenceClock::AdvisePeriodic

IReferenceClock インターフェイス

周期的なアドバイズ要求を作成する。

構文

HRESULT AdvisePeriodic(
    REFERENCE_TIME rtStartTime,
    REFERENCE_TIME rtPeriodTime,
    HSEMAPHORE hSemaphore,
    DWORD *pdwAdviseCookie
);

パラメータ

rtStartTime
[in] 最初の通知のタイム (100 ナノ秒単位)。ゼロ以上、MAX_TIME 以下でなくてはならない。
rtPeriodTime
[in] 通知の間のタイム (100 ナノ秒単位)。ゼロ以上でなくてはならない。
hSemaphore
[in] 呼び出し元によって作成されるセマフォのハンドル。
pdwAdviseCookie
[out] このアドバイズ要求の識別子を受け取る変数へのポインタ。

戻り値

HRESULT 値を返す。次の可能な値がある。

S_OK | 成功。
E_INVALIDARG | 無効なタイム値。
E_OUTOFMEMORY | 失敗。
E_POINTER | NULL ポインタ引数。

注意

クロックは、通知のたびに hSemaphore パラメータで指定されたセマフォを解放する。それ以上通知が不要になった場合は Unadvise を呼び出し、この呼び出しによって返された pdwAdviseToken 値を渡す。

次のサンプル コードでは、作成後 5 秒、およびそれ以降の 2 秒ごとに通知されるアドバイズ要求を作成している。

IReferenceClock *pRefClock = NULL;
// IReferenceClock ポインタを取得する (示されない)。

DWORD          dwAdviseToken;
HANDLE         hSemaphore = CreateSemaphore(NULL, 0, 0x7FFFFFFF, NULL);
REFERENCE_TIME rtPeriodTime = 10000000; // A one-second interval
REFERENCE_TIME rtNow;

pRefClock->GetTime(&rtNow);
pRefClock->AdvisePeriodic(rtNow + (5 * rtPeriodTime),
                          rtPeriodTime,
                          hSemaphore,
                          &dwAdviseToken);
...

pRefClock->Unadvise(dwAdviseToken);

IReferenceClock::AdviseTime

IReferenceClock インターフェイス

単発のアドバイズ要求を作成する。

構文

    HRESULT AdviseTime(
    REFERENCE_TIME rtBaseTime,
    REFERENCE_TIME rtStreamTime,
    HEVENT hEvent,
    DWORD *pdwAdviseCookie
);

パラメータ

rtBaseTime
[in] 基本となる基準タイム (100 ナノ秒単位)。「注意」を参照すること。
rtStreamTime
[in] ストリーム オフセット タイム (100 ナノ秒単位)。「注意」を参照すること。
hEvent
[in] 呼び出し元によって作成されるイベントへのハンドル。
pdwAdviseCookie
[out] アドバイズ要求の識別子を受け取る変数へのポインタ。

戻り値

HRESULT 値を返す。次の可能な値がある。

S_OK | 成功。
E_INVALIDARG | 無効なタイム値。
E_OUTOFMEMORY | 失敗。
E_POINTER | NULL ポインタ引数。

注意

このメソッドは、基準タイム baseTime + streamTime に対して単発のアドバイズ要求を作成する。その合計は、ゼロ以上、MAX_TIME 以下でなくてはならない。これ以外の場合は、E_INVALIDARG を返す。クロックは、要求されたタイムに、hEvent パラメータで指定されたイベントを通知する。

タイムに到達する前に通知を取り消すには、Unadvise メソッドを呼び出し、呼び出しによって返された pdwAdviseToken 値を渡す。通知の発生後、クロックは自動的に通知を消去するので、Unadvise を呼び出す必要はない。ただし、呼び出しても間違いではない。

IReferenceClock::GetTime

IReferenceClock インターフェイス

現在の時間を取得する。

構文

HRESULT GetTime(
    REFERENCE_TIME *pTime
);

パラメータ

pTime
[out] 現在の時間を受け取る変数へのポインタ (100 ナノ秒単位)。

戻り値

HRESULT 値を返す。次の可能な値がある。

POINTER | NULL ポインタ引数。
S_FALSE | 返されたタイムは、前の値と同じである。
S_OK | 成功。

IReferenceClock::Unadvise

IReferenceClock インターフェイス

保留中のアドバイズ要求を削除する。

構文

HRESULT Unadvise(
    DWORD dwAdviseCookie
);

パラメータ

dwAdviseCookie
[in] 削除する要求の識別子。AdviseTime、または pdwAdviseToken パラメータの AdvisePeriodic から返された値を使用する。

戻り値

HRESULT 値を返す。次の可能な値がある。
S_FALSE | 見つからなかった。
S_OK | 成功。


IRegFilterInfo インターフェイス

Windows® レジストリにあるフィルタへのアクセスを提供し、登録済みフィルタをフィルタ グラフに追加する。

フィルタ グラフ マネージャは、Microsoft® Visual Basic® アプリケーションからの使用を目的に、このインターフェイスを実装する。C/C++ アプリケーションでは、このインターフェイスではなく、IFilterMapper2 インターフェイスを使用すること。

IMediaControl::get_RegFilterCollection メソッドは、IRegFilterInfo インターフェイスの集合を返す。このインターフェイスを使用して、集合に含まれるフィルタの名前を照会し、フィルタ グラフに希望のフィルタを追加する。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを返す。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IDispatch メソッド | 説明
GetTypeInfoCount | このディスプインターフェイスに利用可能なタイプ情報があるかどうか判断する。
GetTypeInfo | GetTypeInfoCount が成功した場合は、このディスプインターフェイスのタイプ情報を取得する。
GetIDsOfNames | (引数を含む) プロパティおよびメソッドのテキスト名を対応する DISPID に変換する。
Invoke | DISPID およびその他の必要なパラメータが指定された場合は、このディスプインターフェイスのメソッドを呼び出すか、またはプロパティにアクセスする。
IRegFilterInfo メソッド | 説明
get_Name | フィルタ名を取得する。
Filter | このフィルタのインスタンスを作成し、それをフィルタ グラフに追加する。

IRegFilterInfo::Filter

IRegFilterInfo インターフェイス

このフィルタのインスタンスを作成し、それをフィルタ グラフに追加する。

構文

HRESULT Filter(

  IDispatch **ppUnk

  );

パラメータ

ppUnk
[out] 追加されたフィルタの IFilterInfo インターフェイスへのポインタのアドレス。

戻り値

HRESULT 値を返す。

注意

IRegFilterInfo インターフェイスの集合に含まれる名前を比較してフィルタを検索するには、IRegFilterInfo::get_Name メソッド (Visual Basic の Name プロパティ) を使用する。

IRegFilterInfo::get_Name

IRegFilterInfo インターフェイス

フィルタ名を取得する。

構文

HRESULT get_Name(

  BSTR *strName

  );

パラメータ

strName
[out, retval] フィルタ名へのポインタ。

戻り値

HRESULT 値を返す。

注意

通常、Visual Basic アプリケーションでは、IRegFilterInfo インターフェイスの集合に For Each...Next 構文を使用して、追加したいフィルタが見つかるまで、レジストリに含まれる個々のフィルタの名前を確認する。次に、IRegFilterInfo::Filter メソッドを使用して、そのフィルタをフィルタ グラフに追加できる。


IResourceConsumer インターフェイス

IResourceManager インターフェイスを使用するオブジェクトに、コールバック メカニズムを提供する。

IResourceManager インターフェイスを使用してフィルタ グラフ マネージャからのリソースを要求するオブジェクトでは、IResourceConsumer を実装する必要がある。リソースが利用可能になったとき、または取得したリソースを解放しなければならないときには、フィルタ グラフ マネージャが IResourceConsumer のメソッドを呼び出してそのオブジェクトに通知する。

通常、アプリケーションでこのインターフェイスを使用または実装することはない。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを返す。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IResourceManager メソッド | 説明
AcquireResource | リソースの使用者にリソースが取得可能なことを通知する。
ReleaseResource | 指定されたリソースを解放するようにリソースの使用者に要求する。

IResourceConsumer::AcquireResource

IResourceConsumer インターフェイス

リソースが取得可能なことをリソースの使用者に通知する。

構文

HRESULT AcquireResource(
  LONG idResource
  );

パラメータ

idResource
[in] 取得するリソースのリソース識別子。

戻り値

次のいずれかの値を返す。
S_OK | リソースの使用者がリソースの取得に成功した。
S_FALSE | リソースの使用者がリソースを取得せず、取得したときに IResourceManager::NotifyAcquire を使用する。
VFW_S_RESOURCE_NOT_NEEDED | リソースの使用者がリソースを使い終わった。
エラー値 | リソースの使用者がリソースを取得しようとしたが、失敗した。

IResourceConsumer::ReleaseResource

IResourceConsumer インターフェイス

指定されたリソースを解放するようにリソースの使用者に要求する。

構文

HRESULT ReleaseResource(
  LONG idResource
  );

パラメータ

idResource
[in] 解放するリソースの識別子。

戻り値

リソース解放後に、利用可能になった同じリソースをリソースの使用者がもう一度要求した場合は、S_OK を返す。リソースの使用者がリソースを解放せず、解放したときに IResourceManager::NotifyRelease を使用する場合には、S_FALSE を返す。


IResourceManager インターフェイス

システム リソースの競合を解決する。

フィルタ グラフ マネージャがこのインターフェイスを公開する。フィルタでは、このインターフェイスを使用して、ほかのオブジェクトが使用する可能性があるリソースを要求できる。たとえば、オーディオ レンダリング フィルタでは、このインターフェイスを使用して、ウェーブ出力デバイスの競合を解決し、サウンドとフォーカスを一致させる。

通常、アプリケーションでこのインターフェイスを使用することはない。

オブジェクトでは、既存のリソース間で起きる可能性がある競合を、このインターフェイスを使用して解決できる。まず、オブジェクトは、インターフェイスにリソースを登録し、必要なときにそのリソースを要求する。オブジェクトは、ユーザーのフォーカスが変化するたびに、フィルタ グラフ マネージャに通知しなければならない。これによって、フィルタ グラフ マネージャは、競合するデバイスをユーザーのフォーカスがあるオブジェクトに切り替えることができる。

このインターフェイスを使用するオブジェクトは、IResourceConsumer インターフェイスを実装する必要がある。IResourceConsumer は、リソースが利用可能になったとき、または取得したリソースをオブジェクトが解放すべきときに、フィルタ グラフ マネージャがオブジェクトに通知するためのコールバック メカニズムを提供する。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IResourceManager メソッド | 説明
Register | 単独の名前付きリソースをリソース マネージャに登録する。
RegisterGroup | 名前付きリソース グループをリソース マネージャに登録する。
RequestResource | 所定の登録済みリソースの使用を要求する。
NotifyAcquire | リソース取得の試みが完了したことをリソース マネージャに通知する。
NotifyRelease | リソース コンシューマがリソースを解放したことをリソース マネージャに通知する。
CancelRequest | リソース要求を取り消す。
SetFocus | 特定のオブジェクトにユーザーのフォーカスが与えられたことをリソース マネージャに通知する。
ReleaseFocus | 現在のフォーカス オブジェクトが指定された場合に、リソース マネージャ内のフォーカス オブジェクトを NULL に設定する。

IResourceManager::CancelRequest

IResourceManager インターフェイス

リソース要求を取り消す。

構文

HRESULT CancelRequest(
    LONG idResource,
    IResourceConsumer *pConsumer
);

パラメータ

idResource
[in] 待機中の要求のリソース識別子。
pConsumer
[in] 要求元の IResourceConsumer インターフェイスへのポインタ。

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
S_OK または NOERROR | 成功。

注意

要求したリソースが受け取り前に不要になった場合、要求元の IResourceConsumer オブジェクトはこのメソッドを呼び出す必要がある。また、リソースを既に受け取った場合には、IResourceManager::NotifyRelease メソッドを使用する必要がある。

IResourceManager::NotifyAcquire

IResourceManager インターフェイス

リソース取得の試みが完了したことをリソース マネージャに通知する。

構文

HRESULT NotifyAcquire(
    LONG idResource,
    IResourceConsumer *pConsumer,
    HRESULT hr
);

パラメータ

idResource
[in] 登録済みリソースに対応するトークン。
pConsumer
[in] リソースを要求しているオブジェクトの IResourceConsumer インターフェイスへのポインタ。
hr
[in] 取得の成功を示す値。リソースが取得された場合は S_OK、それ以外の場合はエラー値。

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
S_OK または NOERROR | 成功。

注意

このメソッドは、IResourceConsumer::AcquireResource メソッドが S_FALSE 値を返した後に使用する。S_FALSE 値は、取得が非同期に行われる (つまり、コールバック メカニズムで処理される) ことを示す。hr パラメータが S_OK の場合、リソース マネージャは、そのリソースが呼び出し元に保持されているものと見なす。hr パラメータが S_OK でない場合、リソース マネージャは、リソース取得の試みが失敗し、そのリソースが別の機会にまた割り当てられるものと見なす。

IResourceManager::NotifyRelease

IResourceManager インターフェイス

IResourceConsumer がリソースを解放したことをリソース マネージャに通知する。

構文

HRESULT NotifyRelease LONG idResource,
    IResourceConsumer *pConsumer,
    BOOL bStillWant
);

パラメータ

idResource
[in] リソースのトークン。
pConsumer
[in] リソースを解放しようとしているオブジェクトへのポインタ。
bStillWant
[in] リソースがまだ必要かどうかを指定するフラグ。次に利用可能になったときにまだリソースが必要な場合は、TRUE を設定する。リソースが必要でない場合は、FALSE を設定する。

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
S_OK または NOERROR | 成功。

注意

このメソッドは、IResourceConsumer::ReleaseResource メソッドへの応答として使用するか、またはリソースを使い終わったときに使用する。

IResourceManager::Register

IResourceManager インターフェイス

単独の名前付きリソースをリソース マネージャに登録する。

構文

HRESULT Register(
    LPCWSTR pName,
    LONG cResource,
    LONG *plToken
);

パラメータ

pName
[in] 名前付きリソース。
cResource
[in] リソース数。
plToken
[out] 返されたトークンへのポインタ。このトークンが識別するリソースを、これ以降の呼び出しで使用する。

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
S_OK または NOERROR | 成功。

注意

このメソッドは、複数のリソースを格納できる名前付きリソースを登録し、このリソースを要求するときに使用するトークンを返す。リソースが既に登録されていてもエラーにはならない。登録済みの数より少ない数を cResource パラメータに渡すと、リソースの割り当てがが新しい数に変更される。リソースの登録を解除するには、cResource に 0 を渡す。

IResourceManager::RegisterGroup

IResourceManager インターフェイス

名前付きリソース グループをリソース マネージャに登録する。

構文

HRESULT RegisterGroup(
    LPCWSTR pName,
    LONG cResource,
    LONG *palTokens,
    LONG *plToken
);

パラメータ

pName
[in] 名前付きリソース グループ。
cResource
[in] グループに含まれるリソースの数。
palTokens
[in, size_is(cResource)] グループに含まれるリソースの配列へのポインタ。
plToken
[out] 返されたグループ リソース識別子へのポインタ。

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
S_OK または NOERROR | 成功。

IResourceManager::ReleaseFocus

IResourceManager インターフェイス

現在のフォーカス オブジェクトが指定された場合に、リソース マネージャ内のフォーカス オブジェクトを NULL に設定する。

構文

HRESULT ReleaseFocus(
    IUnknown *pFocusObject
);

パラメータ

pFocusObject
[in] フォーカス オブジェクトへのポインタ。

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
S_OK または NOERROR | 成功。

注意

このメソッドは、フォーカス オブジェクトを破棄しようとしているとき、フォーカスがもう参照されないようにするために使用する。

IResourceManager::RequestResource

IResourceManager インターフェイス

所定の登録済みリソースの使用を要求する。

構文

HRESULT RequestResource(
    LONG idResource,
    IUnknown *pFocusObject,
    IResourceConsumer *pConsumer
);

パラメータ

idResource
[in] リソース登録時に取得されたリソースのトークン。
pFocusObject
[in] 要求に関連付けられたフォーカス オブジェクトの IUnknown インターフェイス (通常はフィルタの IUnknown インターフェイス) へのポインタ。
pConsumer
[in] リソースを要求しているオブジェクトの IResourceConsumer インターフェイスへのポインタ。

戻り値

HRESULT 値を返す。要求したリソースが返された場合は、S_OK を返す。リソースが利用できない場合は、S_FALSE を返す。この場合、リソース マネージャは、リソースが利用可能になった時点で、要求元オブジェクトをコールバックする。それ以外の戻り値はすべてエラーである。

注意

そのリソースへの要求が複数ある場合、リソース マネージャは、個々の要求で渡されたフォーカス オブジェクトを、最新の IResourceManager::SetFocus メソッドで渡されたフォーカス オブジェクトと比較することによって、優先順位を決定する。

要求は次の優先順位で処理される。

  1. 最新の SetFocus メソッドとまったく同じフォーカス オブジェクトに関する要求。
  2. フォーカス オブジェクトとソース フィルタを共有する要求。
  3. フォーカス オブジェクトとフィルタ グラフを共有する要求。
  4. フォーカスと同じ処理からの要求。

この優先順位を調べるとき、リソース マネージャは、フォーカス オブジェクトの QueryInterface を使用して IID_IFilter を照会する。見つかった場合、リソース マネージャは、IBaseFilter メソッドを使用して、フィルタ グラフを調べ、現在のフォーカス オブジェクトと共通のソース フィルタを探す。

フィルタでは、そのフィルタの IUnknown インターフェイスを pFocusObject パラメータに渡さなければならない。フィルタ グラフ マネージャは、フォーカス オブジェクトを調べるとき、フィルタをフィルタ グラフと比較して、共通のソース フィルタまでフィルタをたどろうとする。

フォーカス オブジェクトは、要求の有効期間全体を通して有効である必要がある。要求の有効期間とは、IResourceManager::CancelRequest メソッドが呼び出されるか、または bStillWant パラメータに FALSE を設定して IResourceManager::NotifyRelease メソッドが呼び出されるまでの期間である。

IResourceManager::SetFocus

IResourceManager インターフェイス

特定のオブジェクトにユーザー フォーカスが与えられたことをリソース マネージャに通知する。

構文

HRESULT SetFocus(
    IUnknown *pFocusObject
);

パラメータ

pFocusObject
[in] ユーザー フォーカスを与えられたオブジェクトへのポインタ。

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
S_OK または NOERROR | 成功。

注意

DirectShow では、通常、フォーカスを受け取ったウィンドウを所有するビデオ レンダラが、ユーザー フォーカスを与えられるオブジェクトである。リソース マネージャは、リソース要求に次の順序で優先順位を与える。

  1. pFocusObject パラメータで指定されたフォーカス オブジェクトに関する要求。
  2. フォーカス オブジェクトとソース フィルタを共有する要求。
  3. フォーカス オブジェクトとフィルタ グラフを共有する要求。
  4. フォーカスと同じ処理からの要求。

リソース マネージャは、フォーカスが設定されてから ReleaseFocus が呼び出されるまで、フォーカス オブジェクトを維持しなければならない。つまり、このメソッドを呼び出したら、フォーカス オブジェクトの IUnknown インターフェイスが無効になる前に、ReleaseFocus を使用する必要がある。ただし、別のオブジェクトからそれまでに確実に SetFocus が呼び出される場合はこの限りではない。フォーカス オブジェクト上には参照カウントが保持されない。

リソース マネージャは、置き換えられるか取り消されるまでこのポインタを保持し、リソース競合の解決に使用する。リソース マネージャは、少なくとも QueryInterface を使用して IBaseFilter インターフェイスを照会し、見つかった場合はこのインターフェイスのメソッドを使用する。IBaseFilter のメソッドは、オーディオ レンダラが 2 つある場合に、どちらを使用するか決定する (フォーカス オブジェクトとソース フィルタを共有するものを選ぶ) ために呼び出され、さらに、2 つのオブジェクトが同じフィルタ グラフに含まれるかどうかを判断するために呼び出される。


ISampleGrabber インターフェイス

このインターフェイスは、フィルタ グラフ内を通る個々のメディア サンプルを取得するメソッドを提供する。

サンプル グラバ フィルタは、このインターフェイスを公開する。アプリケーションでは、このインターフェイスのメソッドを呼び出して、メディア サンプルを取得できる。詳細については、｢メディア サンプルの入手｣を参照すること。

要件

Requires Qedit.h が必要である。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
ISampleGrabber メソッド | 説明
SetOneShot | サンプルを 1 つ受け取ったらフィルタがグラフを停止すべきかどうかを指定する。
SetMediaType | サンプル グラバの入力ピン上の接続に使用するメディア タイプを指定する。
GetConnectedMediaType | サンプル グラバの入力ピン上の接続に使用するメディア タイプを取得する。
SetBufferSamples | フィルタ内を通るサンプルをバッファにコピーするかどうかを指定する。
GetCurrentBuffer | フィルタが受け取った最新サンプルのコピーを取得する。
GetCurrentSample | 現在は実装されていない。
SetCallback | サンプル到着時に呼び出すコールバック メソッドを指定する。

ISampleGrabber::GetConnectedMediaType

ISampleGrabber インターフェイス

サンプル グラバの入力ピン上の接続に使用するメディア タイプを取得する。

構文

HRESULT GetConnectedMediaType(
    AM_MEDIA_TYPE *pType
);

パラメータ

pType
AM_MEDIA_TYPE 構造体を受け取る変数へのポインタ。

戻り値

次のいずれかの値を返す。

E_POINTER | NULL ポインタ引数。
S_OK | 成功。
VFW_E_NOT_CONNECTED | フィルタが接続されていない。

ISampleGrabber::GetCurrentBuffer

ISampleGrabber インターフェイス

最新サンプルに関連付けられたバッファのコピーを取得する。

構文

HRESULT GetCurrentBuffer(
    long *pBufferSize,
    long *pBuffer
);

パラメータ

pBufferSize
[in, out] バッファのサイズへのポインタ。pBuffer が NULL の場合、このパラメータは必要なサイズを受け取る。pBuffer が NULL でない場合、このパラメータはバッファのサイズを示す。
pBuffer
[out] サンプルのコピーを受け取るバッファへのポインタ、または NULL。

戻り値

次のいずれかの値を返す。

E_INVALIDARG | サンプルがバッファリングされていない。
E_POINTER | NULL ポインタ引数。
S_OK | 成功。
VFW_E_NOT_CONNECTED | フィルタが接続されていない
VFW_E_WRONG_STATE | フィルタが不適切な状態にある。

注意

バッファリングをアクティブにするには、値 TRUE で SetBufferSamples を呼び出す。

ISampleGrabber::GetCurrentSample

ISampleGrabber インターフェイス

現在は実装されていない。

構文

HRESULT GetCurrentSample(
    IMediaSample **ppSample
);

ISampleGrabber::SetBufferSamples

ISampleGrabber インターフェイス

フィルタ内を通るサンプルをバッファにコピーするかどうかを指定する。

構文

HRESULT SetBufferSamples(
    BOOL BufferThem
);

パラメータ

BufferThem
サンプル データをバッファリングするかどうかを指定するブール型の値。TRUE の場合、フィルタはサンプル データを内部バッファにコピーする。

戻り値

S_OK を返す。

ISampleGrabber::SetCallback

ISampleGrabber インターフェイス

サンプル到着時に呼び出すコールバック メソッドを指定する。

構文

HRESULT SetCallback(
    ISampleGrabberCB *pCallback,
    long WhichMethodToCallback
);

パラメータ

pCallback
コールバック メソッドが格納された ISampleGrabberCB インターフェイスへのポインタ、または NULL。コールバックを取り消す場合に、NULL を指定する。
WhichMethodToCallback
コールバック メソッドを指定するインデックス。次のいずれかの値を指定する。
0 | ISampleGrabberCB::SampleCB メソッドを呼び出す。
1 | ISampleGrabberCB::BufferCB メソッドを呼び出す。

戻り値

次のいずれかの値を返す。

E_INVALIDARG | サンプルはバッファリングされていない。
S_OK | 成功。

注意

サンプルが Microsoft® DirectDraw® サーフェスである場合、そのサーフェスはコールバック中にロックされる。Win16 ロック (Win16Mutex とも呼ばれる) も、ロックされることがある。これらのロックによって、デッドロックの可能性が生まれる。コールバック スレッドが DirectDraw API を呼び出そうとしているスレッドを待っている場合、デッドロックが発生する可能性がある。さらに、Win16 ロックが保持されている場合、コールバックにクリティカル セクションが保持されているか、またはほかのスレッドが処理を完了するのを待っていると、デッドロックが発生する可能性がある。

そのため、コールバックはブロックを発生させる可能性のある処理を実行してはならない。これには、クリティカル セクションの保持や、ほかのスレッド待ちが含まれる。また、ウィンドウを動かすような GDI や USER32.DLL API を呼び出してはならない。Win16 ロックについての詳細は、Knowledge Base 文章 Q125867 : Understandign Win16Mutex ((http://support.microsoft.com/support/kb/articles/Q125/8/67.asp) を参照すること。

データ処理スレッドは、コールバック メソッドから戻るまでブロックする。コールバック メソッドから戻るまでに時間がかかると、再生に影響が出る可能性がある。

ISampleGrabber::SetMediaType

ISampleGrabber インターフェイス

サンプル グラバの入力ピン上の接続に使用するメディア タイプを指定する。

構文

HRESULT SetMediaType(
    const AM_MEDIA_TYPE *pType
);

パラメータ

pType
メディア タイプを指定する AM_MEDIA_TYPE 型の変数へのポインタ。構造体メンバをすべて設定する必要はない。このパラメータでは、メジャー タイプだけを指定したり、メジャー タイプとサブタイプを指定したり、メジャー タイプ、サブタイプ、およびフォーマット タイプを指定したりすることができる。その他の構造体メンバは無視される。

戻り値

S_OK を返す。

注意

デフォルトでは、サンプル グラバに優先メディア タイプはない。サンプル グラバを正しいフィルタに確実に接続するには、グラフをレンダリングする前にこのメソッドを呼び出す。

ISampleGrabber::SetOneShot

ISampleGrabber インターフェイス

サンプルを 1 つ受け取ったらフィルタがグラフを停止すべきかどうかを指定する。

構文

HRESULT SetOneShot(
    BOOL OneShot
);

パラメータ

OneShot
サンプルを 1 つ受け取ったらフィルタがグラフを停止すべきかどうかを指定するブール型の値。TRUE の場合、最初のサンプルを受け取ると、フィルタは停止し、EC_COMPLETE を通知する。FALSE の場合、フィルタは通常どおり実行を続ける。

戻り値

S_OK を返す。

注意

値 TRUE でこのメソッドを呼び出し、希望の時間までシークし、グラフを実行すると、特定時間のサンプルを取得できる。


ISampleGrabberCB インターフェイス

このインターフェイスは、ISampleGrabber::SetCallback メソッドに対応するコールバック メソッドを提供する。このメソッドを呼び出すアプリケーションでは、このインターフェイスを実装する必要がある。詳細については、｢ISampleGrabber｣を参照すること。

要件

Qedit.h が必要である。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
ISampleGrabberCB メソッド | 説明
SampleCB | メディア サンプルへのポインタを受け取るコールバック メソッド。
BufferCB | サンプル バッファへのポインタを受け取るコールバック メソッド。

ISampleGrabberCB::BufferCB

ISampleGrabberCB インターフェイス

サンプル バッファへのポインタを受け取るコールバック メソッド。

構文

HRESULT BufferCB(
    double SampleTime,
    BYTE *pBuffer,
    long BufferLen
);

パラメータ

SampleTime
サンプルの開始タイム (秒単位)。
pBuffer
サンプル データが格納されたバッファへのポインタ。
BufferLen
pBuffer が指すバッファの長さ (バイト単位)。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、HRESULT エラー コードを返す。

注意

サンプルのバッファリングをアクティブにするには、ISampleGrabber::SetBufferSamples メソッドを呼び出す。そうしないと、サンプルがバッファリングされない。

ISampleGrabberCB::SampleCB

ISampleGrabberCB インターフェイス

メディア サンプルへのポインタを受け取るコールバック メソッド。

構文

HRESULT SampleCB(
    double SampleTime,
    IMediaSample *pSample
);

パラメータ

SampleTime
サンプルの開始タイム (秒単位)。
pSample
サンプルの IMediaSample インターフェイスへのポインタ。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、HRESULT エラー コードを返す。


ISeekingPassThru インターフェイス

単独入力フィルタのためのシークを実装するヘルパー オブジェクトを初期化する。SeekingPassThru ヘルパー オブジェクトは、このインターフェイスを公開する。入力ピンが 1 つのフィルタでは、このインターフェイスを使用して、IMediaSeeking インターフェイスおよび IMediaPosition インターフェイスを実装できる。詳細については、「CSeekingPassThru」を参照すること。

アプリケーションでこのインターフェイスを使用することはない。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
ISeekingPassThru メソッド | 説明
Init | シーク元のヘルパー クラスを初期化する。

ISeekingPassThru::Init

ISeekingPassThru インターフェイス

シーク元のヘルパー クラスを初期化する。

構文

HRESULT Init(
    BOOL bSupportRendering,
    IPin *pPin
);

パラメータ

bSupportRendering
[in] フィルタがレンダラかどうかを指定するブール型の値。レンダラの場合は TRUE を使用し、それ以外の場合は FALSE を使用する。
pPin
[in] フィルタの入力ピン上の IPin インターフェイスへのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_FAIL | オブジェクトは既に初期化されている。
E_OUTOFMEMORY | メモリ不足のため、オブジェクトを作成できない。


IStreamBuilder インターフェイス

このインターフェイスを使用すると、出力ピンからフィルタ グラフ マネージャに、フィルタ グラフのダウンストリーム部分をピン自体が構築することを通知できる。特殊な接続を必要とする出力ピンでは、このインターフェイスを実装して、フィルタ グラフ マネージャが使用するピン接続のデフォルト処理をオーバーライドできる。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IStreamBuilder メソッド | 説明
Render | このピンから始まるストリームのレンダリングを完了する。このとき必要に応じて、フィルタがフィルタ グラフに追加され、接続される。
Backout | Render で行われたステップを元に戻す。Render 内で追加されたフィルタがあれば、その切断および削除も行われる。

IStreamBuilder::Backout

IStreamBuilder インターフェイス

Render で行われたステップを元に戻す。Render 内で追加されたフィルタがあれば、その切断および削除も行われる。

構文

HRESULT Backout(
   IPin *ppinOut
   IGraphBuilder *pGraph
)

パラメータ

ppinOut
[in] このピンの IPin インターフェイスへのポインタ。
pGraph
[in] フィルタ グラフ マネージャの IGraphBuilder インターフェイスへのポインタ。

戻り値

HRESULT 値を返す。グラフ ビルダにとって、リターン コード S_OK は切断が成功したことを示す。

注意

次のコードは、このメソッドを出力ピンに実装する方法を示す。

STDMETHODIMP CMyOutputPin::BackOut(IPin *pOutputPin, IGraphBuilder *pBuilder)
{
    HRESULT hr = S_OK;
    if (m_Connected != NULL) {
        FILTER_INFO fi;

        // 自分のピンに接続しているピンのフィルタ ポインタを検索する。
        hr = m_Connected->QueryFilterInfo(&fi);
        if (SUCCEEDED(hr)) {
            if (fi.pFilter != NULL) {
                // 切断する。
                pBuilder->Disconnect(m_Connected);
                pBuilder->Disconnect(pOutputPin);
                // 追加したフィルタをグラフから削除する。
                pBuilder->RemoveFilter(fi.pFilter);
                fi.pFilter->Release();
            } else {
                hr = E_UNEXPECTED;
            }
        }
    }
    return hr;
}

IStreamBuilder::Render

IStreamBuilder インターフェイス

このピンから始まるストリームのレンダリングを完了する。このとき必要に応じて、フィルタがフィルタ グラフに追加され、接続される。

構文

HRESULT Render(
    IPin *ppinOut
    IGraphBuilder *pGraph
);

パラメータ

ppinOut
[in] このピンの IPin インターフェイスへのポインタ。
pGraph
[in] フィルタ グラフ マネージャの IGraphBuilder インターフェイスへのポインタ。

戻り値

HRESULT 値を返す。リターン コード S_OK はストリームのレンダリングが成功したことを示す。

注意

次のコードは、このメソッドを出力ピンに実装する方法を示す。

STDMETHODIMP CMyOutputPin::Render(IPin *pOutputPin, IGraphBuilder *pBuilder)
{
    // このフィルタには自作の特殊なレンダラを接続する必要がある。
    IBaseFilter *pMyRenderer = NULL;
    IPin *pMyRendererInputPin = NULL;
    bool bAddedToGraph = false;

    // 独自のレンダラを作成する。
    HRESULT hr = CoCreateInstance(CLSID_MyRenderer, NULL, CLSCTX_INPROC, IID_IBaseFilter, (void **)&pMyRenderer);
    if (SUCCEEDED(hr)) {
        // レンダラをフィルタ グラフに追加する。
        hr = pBuilder->AddFilter(pMyRenderer, L"My Renderer");
    }
    // レンダラの入力ピンを検索する。

    if (SUCCEEDED(hr)) {
            bAddedToGraph = true;
            IEnumPins *pEnumPins;
            hr = pMyRenderer->EnumPins(&pEnumPins);
            if (SUCCEEDED(hr)) {
                DWORD nPins;
                if (S_OK != pEnumPins->Next(1, &pMyRendererInputPin, &nPins)) {
                    hr = E_UNEXPECTED;
                }
            }
    }
    if (SUCCEEDED(hr)) {
        // レンダラを自分の出力ピンに接続する。
        hr = pBuilder->ConnectDirect(pOutputPin, pMyRendererInputPin);
    }
    if (FAILED(hr)) {
        if (bAddedToGraph) {
            pBuilder->RemoveFilter(pMyRenderer);
        }
        pMyRenderer->Release();
    }
    if (NULL != pMyRendererOutputPin) {
        pMyRendererInputPin->Release();
    }
    return hr;
}


IUnknown インターフェイス

COM (Component Object Model) コンポーネントの有効期間を管理し、コンポーネントにその他の COM インターフェイスを照会する。その他の COM インターフェイスはすべて IUnknown を継承する。

このインターフェイスおよびこのインターフェイスに含まれるメソッドの詳細は、COM のドキュメントに記載されている。ここでは、クイック リファレンスとしてその概要のみを説明する。

インターフェイスを実装する場合には、IUnknown も同時に実装する必要がある。IUnknown を実装するための便利な手段は、CUnknown 基底クラスで提供されるが、独自の実装を開発することもできる。詳細については、｢IUnknown の実装方法｣を参照すること。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。

IUnknown::AddRef

IUnknown インターフェイス

オブジェクト上にある呼び出し元インターフェイスの参照カウントをインクリメントする。このメソッドは、所定のオブジェクト上にあるインターフェイスを指すポインタの新しいコピーそれぞれについて呼び出さなければならない。

構文

ULONG AddRef(void);

戻り値

新しい参照カウントを表す 1 ～ n の整数を返す。この情報は診断やテストでの使用のみを目的としている。このため、状況によっては不安定な値をとることがある。

IUnknown::QueryInterface

IUnknown インターフェイス

クライアントが現在インターフェイス ポインタを保持しているコンポーネント上にある特定のインターフェイスを指すポインタを取得する。このメソッドは、メソッドが返すポインタ上の IUnknown::AddRef を使用する必要がある。

構文

HRESULT QueryInterface(

  REFIID iid,

  void **ppvObject

  );

パラメータ

iid
[in] 要求先インターフェイスの IID を指定する値。
ppvObject
[out] オブジェクトへのポインタのアドレス (メソッドから戻ったとき)。iid に指定されたインターフェイスをオブジェクトがサポートしていない場合、ppvObject は NULL に設定される。

戻り値

インターフェイスがサポートされている場合は、S_OK を返す。それ以外の場合は、E_NOINTERFACE を返す。

IUnknown::Release

IUnknown インターフェイス

オブジェクト上にある呼び出し元インターフェイスの参照カウントをデクリメントする。オブジェクト上の参照カウントが 0 になると、オブジェクトがメモリから解放される。

構文

ULONG Release(void);

戻り値

参照カウントの新しい値を返す。参照カウントは診断やテストの目的にのみ使用する。リソースが解放されたことを知る必要がある場合には、セマンティクス レベルが高いインターフェイスを使用する。


IVideoFrameStep インターフェイス

ビデオ ストリームを進める。このインターフェイスを使用すると、DVD プレーヤーを含む Microsoft® DirectShow® アプリケーションから、ビデオ ストリームを 1 フレームずつ進めることができる。このインターフェイスは、フィルタ グラフ マネージャから入手する。フィルタ グラフ マネージャは、オーバーレイ ミキサー フィルタまたはビデオ レンダラ フィルタと共に、コマ送り処理を制御する。逆方向のコマ送り処理は、サポートされていない。

注 : ハードウェア デコーダでコマ送りが機能するには、そのデコーダで AM_KSPROPSETID_FrameStep プロパティ セットがサポートされている必要がある。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IVideoFrameStep メソッド | 説明
Step | 指定されたフレーム数だけフィルタ グラフを順方向にコマ送りする。
CanStep | 指定されたフィルタのコマ送り能力を判断する。
CancelStep | 直前のコマ送り操作を取り消す。

IVideoFrameStep::CancelStep

IVideoFrameStep インターフェイス

直前の Step 操作を取り消す。

構文

HRESULT CancelStep();

戻り値

Step 操作の取り消しに成功した場合は、S_OK を返す。それ以外の場合は、E_FAIL を返す。

IVideoFrameStep::CanStep

IVideoFrameStep インターフェイス

指定されたフィルタのコマ送り能力を判断する。

構文

HRESULT CanStep(
   long bMultiple,
   IUnknown *pStepObject
);

パラメータ

bMultiple
bMultiple が 0 の場合にメソッドが S_OK を返す場合は、オブジェクトが 1 フレームずつコマ送りできることを意味する。bMultiple が正の場合にメソッドが S_OK を返す場合は、pStepObject が bMultiple フレームずつコマ送りできることを意味する。
pStepObject
コマ送り操作を制御するフィルタのインターフェイスへのポインタ。フィルタ グラフ マネージャに対して、特定のフィルタ グラフ用のレンダリング フィルタを使ってコマ送りを実行するように指示するには、NULL を指定する。コマ送りを実装するカスタム フィルタがグラフに含まれている場合、pStepObject はそのフィルタの IBaseFilter インターフェイスをポイントする必要がある。

戻り値

オブジェクトがコマ送り可能な場合は、S_OK を返す。pStepObject が無効な場合は、E_INVALIDARG を返す。

注意

コマ送りは実時間で行われる。これは、ムービーを 30 フレーム/秒で再生しているときに、bMultiple に 60 を設定して Step を呼び出すと、実行に 2 秒かかることを意味する。このインターフェイスのメソッドはすべて非同期であり、制御は直ちにアプリケーションに返される。

IVideoFrameStep::Step

IVideoFrameStep インターフェイス

指定されたフレーム数だけフィルタ グラフを順方向にコマ送りする。

構文

HRESULT Step(
   DWORD dwFrames,
   IUnknown *pStepObject
);

パラメータ

dwFrames
スキップするフレーム数を指定する DWORD 型の変数。dwFrames が 1 の場合、1 フレーム、順方向にコマ送りすることを意味する。dwFrames が 1 より大きい値 n の場合、n - 1 フレームをスキップし、n 番目のフレームを表示することを意味する。
pStepObject
コマ送り操作を制御するフィルタのインターフェイスへのポインタ。フィルタ グラフ マネージャに対して、特定のフィルタ グラフ用のレンダリング フィルタを使ってコマ送りを実行するように指示するには、NULL を指定する。コマ送りを実装するカスタム フィルタがグラフに含まれている場合、pStepObject はそのフィルタの IBaseFilter インターフェイスをポイントする必要がある。

戻り値

HRESULT 値を返す。次の可能な値がある。

S_OK | 成功。
VFW_E_FRAME_STEP_UNSUPPORTED | コマ送りはサポートされていない。
E_INVALIDARG | pStepObject パラメータは無効である。

注意

コマ送り操作が完了すると、このメソッドはフィルタ グラフ マネージャに EC_STEP_COMPLETE イベント通知を送る。フィルタ グラフ マネージャは、これをアプリケーションのイベント ループに渡し、フィルタ グラフをポーズ状態に切り替える。


IVideoWindow インターフェイス

IVideoWindow インターフェイスは、Microsoft® DirectShow® 提供のビデオ レンダリング フィルタに実装され、フィルタ グラフ マネージャを通じてアプリケーションに公開される (注 : C++ 開発者へ : このインターフェイスは、必ずフィルタ グラフ マネージャの QueryInterface を呼び出して取得し、ビデオ レンダラから直接取得しないこと)。IVideoWindow は、Microsoft® Visual Basic® アプリケーションからも Visual C++® アプリケーションからもアクセスできるデュアル インターフェイスである。IVideoWindow は、ビデオを再生するウィンドウを制御するためのメソッドおよびプロパティを提供する。

このインターフェイスのメソッドの唯一の条件は、ビデオ レンダラが接続されていることである。ビデオ レンダラが接続されていない場合、インターフェイスの関数はすべて VFW_E_NOT_CONNECTED を返す。ビデオ レンダラに設定したプロパティは、それ以降に行われる接続および切断の間ずっと有効である。すべてのアプリケーションでは、表示を開始する前にレンダラのプロパティを確実にリセットすること。

このインターフェイスは Automation 互換である。したがって、メソッドが受け付けるパラメータには、重要な特徴が 2 つある。1 番目は、返されるブール値が OAFALSE (0) または OATRUE (–1) であり、これらが C/C++ の定義と異なっている点である。2 番目は、文字列がすべて BSTR 型として定義されている点である。インターフェイスに送る文字列は、すべて Automation の SysAllocString 関数を通じて割り当てなければならない。同様に、インターフェイスから返された文字列は、すべて Automation の SysFreeString 関数を使用して解放しなければならない。

代替ビデオ レンダラを開発する場合には、このインターフェイスを実装する。Automation 用の IDispatch 実装を処理する CBaseVideoWindow クラスを使用すると、このインターフェイスが実装しやすい。

注 : ビデオ レンダラがチャイルド ウィンドウにある MFC アプリケーションは、ビデオ ディスプレイ エリアを正しく再描画させるために、カラの WM_ERASEBKGND メッセージ ハンドラを持たなければならない。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IDispatch メソッド | 説明
GetTypeInfoCount | このディスプインターフェイスに利用可能なタイプ情報があるかどうか判断する。
GetTypeInfo | GetTypeInfoCount が成功した場合は、このディスプインターフェイスのタイプ情報を取得する。
GetIDsOfNames | (引数を含む) プロパティおよびメソッドのテキスト名を対応する DISPID に変換する。
Invoke | DISPID およびその他の必要なパラメータが指定された場合は、このディスプインターフェイスのメソッドを呼び出すか、またはプロパティにアクセスする。
IVideoWindow メソッド | 説明
put_Caption | 再生ウィンドウのタイトル文字列を設定する。
get_Caption | 再生ウィンドウのタイトル文字列を取得する。
put_WindowStyle | 再生ウィンドウ スタイルを設定する。
get_WindowStyle | ビデオ ウィンドウのウィンドウ スタイルを取得する。
put_WindowStyleEx | コントロール ウィンドウのスタイルを設定する。
get_WindowStyleEx | ビデオ ウィンドウの拡張スタイルを取得する。
put_AutoShow | 状態が最初に変化したときにウィンドウが自動的に表示されるかどうかを指定する。
get_AutoShow | ウィンドウが自動的に表示されるかどうかに関する情報を取得する。
put_WindowState | 現在のウィンドウ状態 (表示/非表示、最小化など) を設定する。
get_WindowState | 現在のウィンドウ状態 (表示/非表示、最小化など) を取得する。
put_BackgroundPalette | レンダラにそのパレットをバックグラウンドで認識するように知らせる。
get_BackgroundPalette | 必要なパレットがバックグラウンドで認識されるかどうかに関する情報を取得する。
put_Visible | ウィンドウの表示/非表示を設定する。
get_Visible | ウィンドウの表示/非表示を取得する。
put_Left | ビデオ ウィンドウの x 軸座標を設定する。
get_Left | ビデオ ウィンドウの x 軸座標を取得する。
put_Width | ビデオ ウィンドウの幅を設定する。
get_Width | ビデオ ウィンドウの幅を取得する。
put_Top | ビデオ ウィンドウの y 軸座標を設定する。
get_Top | ビデオ ウィンドウの y 軸座標を取得する。
put_Height | ビデオ ウィンドウの高さを設定する。
get_Height | ビデオ ウィンドウの高さを取得する。
put_Owner | ビデオ再生ウィンドウを所有する親ウィンドウを設定する。
get_Owner | ビデオ再生ウィンドウを所有する親ウィンドウを取得する。
put_MessageDrain | ビデオ ウィンドウのメッセージの送信先ウィンドウを指定する。
get_MessageDrain | ビデオ ウィンドウのメッセージを受け取るウィンドウを取得する。
get_BorderColor | ビデオ ウィンドウの境界色を取得する。
put_BorderColor | ビデオ ウィンドウの境界色を設定する。
get_FullScreenMode | このインターフェイスをサポートしているビデオ レンダリング フィルタのフルスクリーン レンダリング モードを取得する。
put_FullScreenMode | このインターフェイスをサポートしているビデオ レンダリング フィルタのフルスクリーン モードを設定する。
SetWindowForeground | 前面ウィンドウに切り替わるようにレンダリング フィルタに知らせる。
NotifyOwnerMessage | 親ウィンドウから受け取ったメッセージを、フィルタが所有する子ウィンドウに転送する。
SetWindowPosition | ディスプレイ上のビデオ ウィンドウ位置を設定する。
GetWindowPosition | ビデオ ウィンドウ位置を取得する。
GetMinIdealImageSize | ビデオ イメージ再生 (クライアント) 領域の理論上の最小イメージ サイズを取得する。
GetMaxIdealImageSize | ビデオ イメージ再生 (クライアント) 領域の理論上の最大イメージ サイズを取得する。
GetRestorePosition | 復元されるウィンドウの通常のディメンジョンを取得する。
HideCursor | カーソルを非表示にする。
IsCursorHidden | カーソルの表示/非表示を判断する。

IVideoWindow::get_AutoShow

IVideoWindow インターフェイス

ウィンドウが自動的に表示されるかどうかに関する情報を取得する。

構文

HRESULT get_AutoShow(
    long *AutoShow
);

パラメータ

AutoShow
[out] ウィンドウが自動的に表示されるかどうかを示す値へのポインタ。OATRUE は、ポーズ状態または実行状態に変わったとき、ウィンドウが表示されることを示す。

戻り値

可能な戻り値は次のとおりである。

E_POINTER | NULL ポインタ。
S_OK | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されない。

IVideoWindow::get_BackgroundPalette

IVideoWindow インターフェイス

必要なパレットがバックグラウンドで認識されるかどうかに関する情報を取得する。

構文

HRESULT get_BackgroundPalette(
    long *pBackgroundPalette
);

パラメータ

pBackgroundPalette
[out] パレットがバックグラウンドで認識されるかどうかを示す値へのポインタ。OATRUE は認識されることを示す。

戻り値

可能な戻り値は次のとおりである。

E_POINTER | NULL ポインタ。
S_OK | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されない。

IVideoWindow::get_BorderColor

IVideoWindow インターフェイス

ビデオ ウィンドウの境界色を取得する。

構文

HRESULT get_BorderColor(
    long *pColor
);

パラメータ

pColor
[out] 取得された境界色 (Microsoft Win32® COLORREF 値) へのポインタ。

戻り値

可能な戻り値は次のとおりである。

E_POINTER | NULL ポインタ。
S_OK | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されない。

IVideoWindow::get_Caption

IVideoWindow インターフェイス

ビデオ ウィンドウのタイトル文字列を取得する。

構文

HRESULT get_Caption(
    BSTR *strCaption
);

パラメータ

strCaption
[out] 取得されたウィンドウ タイトル文字列へのポインタ。

戻り値

可能な戻り値は次のとおりである。

E_POINTER | NULL ポインタ。
S_OK | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されない。

IVideoWindow::get_FullScreenMode

IVideoWindow インターフェイス

このインターフェイスをサポートしているレンダリング フィルタのフルスクリーン レンダリング能力を取得する。

構文

HRESULT get_FullScreenMode(
    long *FullScreenMode
);

パラメータ

FullScreenMode
[out] レンダラにフルスクリーン能力があるかどうかを示す値へのポインタ。レンダラがフルスクリーン ビデオをサポートしている場合は、OATRUE。サポートしていない場合は、OAFALSE。

戻り値

可能な戻り値は次のとおりである。

E_NOTIMPL | フィルタがフルスクリーン モードをサポートしていない。
E_POINTER | NULL ポインタ。
S_OK | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されない。

注意

フィルタ グラフ マネージャは、ビデオをフルスクリーン サイズでレンダリングするように要求されると、このメソッドを呼び出す。レンダラは、レンダラ自体がもともとフルスクリーン再生をサポートしていない場合は E_NOTIMPL を返し、それ以外の場合には NOERROR を返さなければならない。レンダラがフルスクリーン再生をサポートしている場合、このメソッドは現在それがオンになっているかどうかを判断する。

IVideoWindow::get_Height

IVideoWindow インターフェイス

ビデオ ウィンドウの高さを取得する。

構文

HRESULT get_Height(
    long *pHeight
);

パラメータ

pHeight
[out] 取得されたビデオ ウィンドウ垂直ディメンジョンへのポインタ。

戻り値

可能な戻り値は次のとおりである。

E_POINTER | NULL ポインタ。
S_OK | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されない。

IVideoWindow::get_Left

IVideoWindow インターフェイス

ビデオ ウィンドウの x 軸座標を取得する。

構文

HRESULT get_Left(
    long *pLeft
);

パラメータ

pLeft
[out] 取得する x 軸座標へのポインタ。

戻り値

可能な戻り値は次のとおりである。

E_POINTER | NULL ポインタ。
S_OK | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されない。

IVideoWindow::GetMaxIdealImageSize

IVideoWindow インターフェイス

ビデオ イメージ再生 (クライアント) 領域の理論上の最大イメージ サイズを取得する。

構文

HRESULT GetMaxIdealImageSize(
    long *pWidth,
    long *pHeight
);

パラメータ

pWidth
[out] イメージの幅へのポインタ (ピクセル単位)。
pHeight
[out] イメージの高さへのポインタ (ピクセル単位)。

戻り値

可能な戻り値は次のとおりである。

E_POINTER | NULL ポインタ。
S_FALSE | 最小イメージ サイズを取得できない。
S_OK | 成功。
VFW_E_WRONG_STATE | フィルタが停止している。

注意

このメソッドは次のようにさまざまな状況で S_FALSE を返す。

  • フィルタが IOverlay トランスポートを使用している。
  • UseWhenFullScreen モードがオンになっている (「IDirectDrawVideo::UseWhenFullScreen」を参照すること)。
  • ビデオ サーフェスに最大オーバーレイ伸縮がない (DDCAPS 構造体の dwMaxOverlayStretch メンバが 0)。「IDirectDrawVideo::GetCaps」を参照すること。

IVideoWindow::get_MessageDrain

IVideoWindow インターフェイス

ビデオ ウィンドウのメッセージを受け取るウィンドウを取得する。

構文

HRESULT get_MessageDrain(
    OAHWND *Drain
);

パラメータ

Drain
[in] 現在ビデオ ウィンドウのメッセージの送信先として割り当てられているウィンドウへのポインタ。

戻り値

可能な戻り値は次のとおりである。

E_POINTER | NULL ポインタ。
S_OK | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されない。

注意

メッセージ ドレーンとして指定したウィンドウに渡される Microsoft Win32® メッセージの一覧は、「IVideoWindow::put_MessageDrain」の説明に記載されている。

IVideoWindow::GetMinIdealImageSize

IVideoWindow インターフェイス

ビデオ イメージ再生 (クライアント) 領域の理論上の最小イメージ サイズを取得する。

構文

HRESULT GetMinIdealImageSize(
    long *pWidth,
    long *pHeight
);

パラメータ

pWidth
[out] イメージの幅へのポインタ (ピクセル単位)。
pHeight
[out] イメージの高さへのポインタ (ピクセル単位)。

戻り値

可能な戻り値は次のとおりである。

E_POINTER | NULL ポインタ。
S_FALSE | 最小イメージ サイズを取得できない。
S_OK | 成功。
VFW_E_WRONG_STATE | フィルタが停止している。

注意

このメソッドは次のようにさまざまな状況で S_FALSE を返す。

  • フィルタが IOverlay トランスポートを使用している。
  • UseWhenFullScreen モードがオンになっている (「IDirectDrawVideo::UseWhenFullScreen」を参照すること)。
  • 伸縮可能なオフスクリーン サーフェスがビデオ再生で使用されている (DDCAPS 構造体の dwCaps メンバに DDCAPS_BLTSTRETCH フラグが含まれている)。「IDirectDrawVideo::GetCaps」を参照すること。
  • ビデオ サーフェスに最小オーバーレイ伸縮がない (DDCAPS 構造体の dwMinOverlayStretch メンバが 0)。「IDirectDrawVideo::GetCaps」を参照すること。

IVideoWindow::get_Owner

IVideoWindow インターフェイス

ビデオ ウィンドウを所有する親ウィンドウを取得する。

構文

HRESULT get_Owner(
    OAHWND *pOwner
);

パラメータ

pOwner
[out] 取得されたウィンドウ ハンドルへのポインタ。

戻り値

可能な戻り値は次のとおりである。

E_POINTER | NULL ポインタ。
S_OK | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されない。

IVideoWindow::GetRestorePosition

IVideoWindow インターフェイス

復元されるウィンドウの通常のディメンジョンを取得する。

構文

HRESULT GetRestorePosition(
    long *pLeft,
    long *pTop,
    long *pWidth,
    long *pHeight
);

パラメータ

pLeft
[out] ウィンドウ左端の x 軸座標へのポインタ。
pTop
[out] ウィンドウ上端の y 軸座標へのポインタ。
pWidth
[out] ウィンドウの幅へのポインタ (ピクセル単位)。
pHeight
[out] ウィンドウの高さへのポインタ (ピクセル単位)。

戻り値

可能な戻り値は次のとおりである。

E_POINTER | NULL ポインタ。
S_OK | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されない。

注意

ウィンドウが最大化または最小化されているとき、ウィンドウ位置関係のメソッドは実際のウィンドウ サイズを返す。このメソッドでは、ウィンドウが復元されたときのディメンジョンを返す。アプリケーションでは、ウィンドウが最大化または最小化されている間、ウィンドウ状態を保存しておくために、このメソッドを使用できる。

IVideoWindow::get_Top

IVideoWindow インターフェイス

ビデオ ウィンドウの y 軸座標を取得する。

構文

HRESULT get_Top(
    long *pTop
);

パラメータ

pTop
[out] 取得された y 軸の基点へのポインタ。

戻り値

可能な戻り値は次のとおりである。

E_POINTER | NULL ポインタ。
S_OK | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されない。

IVideoWindow::get_Visible

IVideoWindow インターフェイス

ビデオ ウィンドウの表示/非表示を取得する。

構文

HRESULT get_Visible(
    long *pVisible
);

パラメータ

pVisible
[out] ウィンドウが表示されているかどうかを示す値へのポインタ。OATRUE は表示されていることを示し、それ以外の場合は非表示を示す。

戻り値

可能な戻り値は次のとおりである。

E_POINTER | NULL ポインタ。
S_OK | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されない。

IVideoWindow::get_Width

IVideoWindow インターフェイス

ビデオ ウィンドウの幅を取得する。

構文

HRESULT get_Width(
    long *pWidth
);

パラメータ

pWidth
[out] 取得された幅へのポインタ。

戻り値

可能な戻り値は次のとおりである。

E_POINTER | NULL ポインタ。
S_OK | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されない。

IVideoWindow::GetWindowPosition

IVideoWindow インターフェイス

(クライアント矩形ではなく) 現在のウィンドウ矩形をデバイス座標で取得する。

構文

HRESULT GetWindowPosition(
    long *pLeft,
    long *pTop,
    long *pWidth,
    long *pHeight
);

パラメータ

pLeft
[out] ウィンドウの x 軸の基点へのポインタ。
pTop
[out] ウィンドウの y 軸の基点へのポインタ。
pWidth
[out] ウィンドウの幅へのポインタ (ピクセル単位)。
pHeight
[out] ウィンドウの高さへのポインタ (ピクセル単位)。

戻り値

可能な戻り値は次のとおりである。

E_POINTER | NULL ポインタ。
S_OK | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されない。

注意

このメソッドの効果は、IVideoWindow::get_Left メソッド、IVideoWindow::get_Top メソッド、IVideoWindow::get_Width メソッド、および IVideoWindow::get_Height メソッドを個別に呼び出した場合と等しい。

IVideoWindow::get_WindowState

IVideoWindow インターフェイス

ビデオ ウィンドウの状態を返す。

構文

HRESULT get_WindowState(
    long *WindowState
);

パラメータ

WindowState
[out] ビデオ ウィンドウの状態を示すフラグへのポインタ。

戻り値

可能な戻り値は次のとおりである。

E_POINTER | NULL ポインタ。
S_OK | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されない。

注意

このメソッドは、ウィンドウ状態 (つまり、SW_MINIMIZE、SW_MAXIMIZE、SW_SHOW、または SW_HIDE) のプロパティのサブセットを取得する。 これらのウィンドウ状態の定義は、Win32 ShowWindow 関数と同じである。

IVideoWindow::get_WindowStyle

IVideoWindow インターフェイス

ビデオ ウィンドウのウィンドウ スタイルを取得する。

構文

HRESULT get_WindowStyle(
    long *pWindowStyle
);

パラメータ

pWindowStyle
[out] Win32 GetWindowLong 関数の GWL_STYLE 値で設定できるフラグのサブセットと対応するフラグ セットへのポインタ。

戻り値

可能な戻り値は次のとおりである。

E_POINTER | NULL ポインタ。
S_OK | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されない。

注意

ウィンドウ スタイルの一覧については、Platform Software Development Kit (SDK) の「CreateWindow 関数」を参照すること。

IVideoWindow::get_WindowStyleEx

IVideoWindow インターフェイス

ビデオ ウィンドウの拡張スタイルを取得する。

構文

HRESULT get_WindowStyleEx(
    long *pWindowStyleEx
);

パラメータ

pWindowStyleEx
[out, retval] Win32 GetWindowLong 関数の GWL_STYLE 値で設定できるフラグのサブセットと対応するフラグ セットへのポインタ。

戻り値

可能な戻り値は次のとおりである。

E_POINTER | NULL ポインタ。
S_OK | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されない。

注意

このメソッドは、拡張ウィンドウ スタイルを使用する。ウィンドウ スタイルの一覧については、Platform SDK の ｢CreateWindow 関数｣を参照すること。

IVideoWindow::HideCursor

IVideoWindow インターフェイス

カーソルを非表示にする。

構文

HRESULT HideCursor(
    long HideCursor
);

パラメータ

HideCursor
[in] カーソルを非表示にするかどうかを指定する値。OATRUE の場合は、カーソルを表示しない。OAFALSE の場合は、カーソルを表示する。

戻り値

可能な戻り値は次のとおりである。

E_INVALIDARG | 無効な引数。
S_OK | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されない。

注意

このメソッドは、通常、ビデオ レンダラがフルスクリーン モード (カーソルを表示したくないことがある) のときに使用される。

IVideoWindow::IsCursorHidden

IVideoWindow インターフェイス

カーソルの表示/非表示を判断する。

構文

HRESULT IsCursorHidden(
    long *CursorHidden
);

パラメータ

CursorHidden
[out] カーソルが非表示になっているかどうかを示す値へのポインタ。OATRUE の場合、カーソルは非表示。OAFALSE の場合、カーソルは表示されている。

戻り値

可能な戻り値は次のとおりである。

E_POINTER | NULL ポインタ。
S_OK | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されない。

注意

このメソッドは、通常、ビデオ レンダラがフルスクリーン モード (カーソルを表示したくないことがある) のときに使用される。

IVideoWindow::NotifyOwnerMessage

IVideoWindow インターフェイス

親ウィンドウから受け取ったメッセージを、フィルタが所有する子ウィンドウに転送する。

構文

HRESULT NotifyOwnerMessage(
    long hwnd,
    long uMsg,
    long wParam,
    long lParam
    );

パラメータ

hwnd
[in] ウィンドウ ハンドル。
uMsg
[in] 送ろうとしているメッセージ。
wParam
[in] メッセージに渡された wParam。
lParam
[in] メッセージに渡された lParam。

戻り値

可能な戻り値は次のとおりである。

S_OK | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されない。

注意

このメソッドは、レンダラ ウィンドウを子ウィンドウにするウィンドウから使用しなければならない。このメソッドは、通常ならば子ウィンドウが受け取ることのない多数のメッセージを、子ウィンドウに転送する。転送されるメッセージには、次のようなものがある。

  • WM_ACTIVATEAPP
  • WM_DEVMODECHANGE
  • WM_DISPLAYCHANGE
  • WM_PALETTECHANGED
  • WM_PALETTEISCHANGING
  • WM_QUERYNEWPALETTE
  • WM_SYSCOLORCHANGE

IVideoWindow::put_AutoShow

IVideoWindow インターフェイス

ウィンドウが自動的に表示されるかどうかを判断する。

構文

HRESULT put_AutoShow(
    long AutoShow
);

パラメータ

AutoShow
[in] ウィンドウが自動的に表示されるかどうかを指定する値。OATRUE (–1) は、状態が変わるとウィンドウが表示されることを意味する。OAFALSE (0) の場合、明示的に表示しない限り、ウィンドウは表示されない。

戻り値

可能な戻り値は次のとおりである。

E_INVALIDARG | 無効な引数。
S_OK | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されない。

注意

簡単なアプリケーションでは、フィルタ グラフが実行状態に入るとき、表示されたウィンドウが必要になることが多い。デフォルトでは、AutoShow が OATRUE となり、グラフがポーズ状態または実行状態に変わるとウィンドウが表示される (ウィンドウはさらに前面ウィンドウとして設定される)。その後、ポーズ状態または実行状態に変わっても、ウィンドウが非表示になることはない。ストリームの実行中にウィンドウを閉じた場合、ウィンドウは自動的に再表示されない。ただし、ストリームを停止後にもう一度開始すると、ウィンドウが自動的に再表示される。

参照

IVideoWindow::put_Visible

IVideoWindow::put_BackgroundPalette

IVideoWindow インターフェイス

必要なパレットがバックグラウンドで認識されるかどうかを判断する。

構文

HRESULT put_BackgroundPalette(
    long BackgroundPalette
);

パラメータ

BackgroundPalette
[in] パレットがバックグラウンドで認識されるかどうかを指定する値。パレットをバックグラウンドで認識するには、OATRUE (–1) を設定する。それ以外の場合は、OAFALSE を設定する。

戻り値

可能な戻り値は次のとおりである。

E_INVALIDARG | 無効な引数。
S_OK | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されない。

注意

BackgroundPalette が OATRUE の場合、レンダラでビデオに必要なパレットがバックグラウンドで認識される。これは、パレットが使用する色がすべて、描画前にディスプレイ パレット内の最も近い色に変更されることを意味する。この結果、ビデオ再生時にアプリケーションのパレットが影響を受けない。ただし、ビデオのパフォーマンスに大きな影響が出るので、どうしても必要な場合以外は使用しないこと。このプロパティのデフォルト値は OAFALSE。

IVideoWindow::put_BorderColor

IVideoWindow インターフェイス

ビデオ ウィンドウの境界色を設定する。

構文

HRESULT put_BorderColor(
    long Color
);

パラメータ

Color
[in] COLORREF 型の新しい境界色。

戻り値

可能な戻り値は次のとおりである。

S_OK | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されない。

注意

設定する転送先矩形が、ウィンドウのクライアント可視領域と異なるときには、縁の周りに境界が表示される。このメソッドを使用すると、アプリケーションからこの境界の色を変更できる。境界色のデフォルト値は黒である。システム カラー以外の色を渡すと、使用前に現在のパレットに基づく最も近い色に変換される (トゥルーカラー デバイス以外でも同様)。境界色を設定すると、ウィンドウの境界が新しい色で自動的に再描画される。

IVideoWindow::put_Caption

IVideoWindow インターフェイス

ビデオ ウィンドウのタイトル文字列を設定する。

構文

HRESULT put_Caption(
    BSTR strCaption
);

パラメータ

strCaption
[in] ウィンドウのタイトル キャプション。

戻り値

可能な戻り値は次のとおりである。

E_POINTER | NULL ポインタ。
S_OK | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されない。

IVideoWindow::put_FullScreenMode

IVideoWindow インターフェイス

このインターフェイスをサポートしているビデオ レンダリング フィルタのフルスクリーン モードを設定する。

構文

HRESULT put_FullScreenMode(
    long FullScreenMode
);

パラメータ

FullScreenMode
[in] ビデオ レンダリング フィルタがフルスクリーン モードをサポートしているかどうかを指定する値。フルスクリーン ビデオをサポートしている場合は、OATRUE を設定する。それ以外の場合は、OAFALSE を設定する。

戻り値

可能な戻り値は次のとおりである。

E_NOTIMPL | フィルタがフルスクリーン モードをサポートしていない。
S_FALSE | フィルタが既に要求されたモードになっている。
S_OK | 成功。

注意

このメソッドを使用すると、アプリケーションからフルスクリーン レンダラを、フルスクリーン モードに切り替えたり、フルスクリーン モードから切り替えたりすることができる。レンダラがフルスクリーン モードから切り替えられたときの動作は、実装によって異なる。たとえば、Microsoft のフルスクリーン レンダラでは、ウィンドウ モードに戻る。

フィルタ グラフ マネージャの IVideoWindow PID は、フルスクリーン レンダラの切り替えを実装する。PID は、フルスクリーン モードをサポートするレンダラをグラフ内から探し、見つからない場合には、レンダラをデフォルトの DirectShow フルスクリーン レンダラに一時的に置き換える。IVideoWindow::GetMaxIdealImageSize を呼び出して、ウィンドウを最前面ウィンドウにし、画面全体へサイズ変更することができるかどうかを判断する。フィルタ グラフは DirectDraw® オーバーレイまたはハードウェア デコーダ フィルタを使用している可能性があるため、レンダラを交換するよりこの方法の方が好ましい。

IVideoWindow::put_Height

IVideoWindow インターフェイス

ビデオ ウィンドウの高さを設定する。

構文

HRESULT put_Height(
    long Height
);

パラメータ

Height
[in] ビデオ ウィンドウの新しい垂直ディメンジョン。

戻り値

可能な戻り値は次のとおりである。

E_INVALIDARG | 無効な引数。
S_OK | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されない。

注意

ビデオ ウィンドウの y 軸座標は、このメソッドの呼び出しにより影響を受けない。

IVideoWindow::put_Left

IVideoWindow インターフェイス

ビデオ ウィンドウの x 軸座標を設定する。

構文

HRESULT put_Left(
    long Left
);

パラメータ

Left
[in] 設定する x 軸座標。

戻り値

可能な戻り値は次のとおりである。

E_INVALIDARG | 無効な引数。
S_OK | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されない。

注意

ビデオ ウィンドウの幅は、このメソッドの呼び出しにより影響を受けない。

IVideoWindow::put_MessageDrain

IVideoWindow インターフェイス

ビデオ ウィンドウのメッセージの送信先ウィンドウを指定する。

構文

HRESULT put_MessageDrain(
    OAHWND Drain
);

パラメータ

Drain
[in] メッセージの送信先ウィンドウ。

戻り値

可能な戻り値は次のとおりである。

S_OK | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されない。

注意

ビデオ レンダラは、Win32 PostMessage 関数を呼び出して、指定されたメッセージ ドレーンにメッセージを渡す。これらのメッセージを使用すると、ユーザーの介入 (ビデオ表示の特定領域内をマウスでクリックするなど) を伴うアプリケーションを開発できる。アプリケーションでは、ビデオ ウィンドウと緊密な関係を保ち、ユーザーの介入を調べるべき時期を知ることができる。レンダラからメッセージ ドレーンにメッセージが渡されるとき、パラメータ (クライアント領域の座標など) はまったく手を加えずに送られる。

アプリケーションが次のメッセージを生成すると、DirectShow はそれを Drain パラメータで指定されたウィンドウに渡す。

  • WM_KEYDOWN
  • WM_KEYUP
  • WM_LBUTTONDBLCLK
  • WM_LBUTTONDOWN
  • WM_LBUTTONUP
  • WM_MBUTTONDBLCLK
  • WM_MBUTTONDOWN
  • WM_MBUTTONUP
  • WM_MOUSEACTIVATE
  • WM_MOUSEMOVE
  • WM_NCLBUTTONDBLCLK
  • WM_NCLBUTTONDOWN
  • WM_NCLBUTTONUP
  • WM_NCMBUTTONDBLCLK
  • WM_NCMBUTTONDOWN
  • WM_NCMBUTTONUP
  • WM_NCMOUSEMOVE
  • WM_NCRBUTTONDBLCLK
  • WM_NCRBUTTONDOWN
  • WM_NCRBUTTONUP
  • WM_RBUTTONDBLCLK
  • WM_RBUTTONDOWN
  • WM_RBUTTONUP

このメンバ関数は、メッセージ ドレーン ウィンドウを子ウィンドウにしないので、フルスクリーン能力のあるアプリケーションから使用できる。

IVideoWindow::put_Owner

IVideoWindow インターフェイス

ビデオ ウィンドウを所有する親ウィンドウを設定する。

構文

HRESULT put_Owner(
    OAHWND Owner
);

パラメータ

Owner
[in] 新しい所有者ウィンドウのハンドル。

戻り値

可能な戻り値は次のとおりである。

S_OK | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されない。

注意

このメソッドは、アプリケーションからビデオ ウィンドウの所有者を設定するための手段を提供し、複合ドキュメント内のビデオを再生するときによく使用される。このメソッドは、レンダラ ウィンドウの親を変更し、ビデオ ウィンドウに対応する WS_CHILD スタイルを設定する。

ビデオ ウィンドウ メッセージを親ウィンドウに転送するには、親ウィンドウのウィンドウ ハンドルを指定して IVideoWindow::put_MessageDrain メソッドを使用する。このメッセージは、メッセージを自動的に送信しない。

このメッセージを使用してビデオ ウィンドウの所有者を設定した場合は、フィルタ グラフを解放する前に (put_Owner(NULL) を呼び出して) 所有者を NULL にリセットする必要がある。そうしないと、引き続きこのウィンドウにメッセージが送られ、アプリケーション終了時にエラーが発生する可能性が高い。

IVideoWindow::put_Top

IVideoWindow インターフェイス

ビデオ ウィンドウの y 軸座標を設定する。

構文

HRESULT put_Top(
    long Top
);

パラメータ

Top
[in] ビデオ ウィンドウの y 軸の基点。

戻り値

可能な戻り値は次のとおりである。

E_INVALIDARG | 無効な引数。
S_OK | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されない。

注意

ビデオ ウィンドウの高さは、このメソッドの呼び出しにより影響を受けない。

IVideoWindow::put_Visible

IVideoWindow インターフェイス

ビデオ ウィンドウの表示/非表示を変更する。

構文

HRESULT put_Visible(
    long Visible
);

パラメータ

Visible
[in] Automation 互換のブール型フラグ。

戻り値

可能な戻り値は次のとおりである。

E_INVALIDARG | 無効な引数。
S_OK | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されない。

注意

Visible パラメータに OATRUE (–1) を設定すると、ウィンドウが表示される。OAFALSE (0) を設定すると、ウィンドウが非表示になる。

IVideoWindow::put_Width

IVideoWindow インターフェイス

ビデオ ウィンドウの幅を設定する。

構文

HRESULT put_Width(
    long Width
);

パラメータ

Width
[in] 設定する幅 (ピクセル単位)。

戻り値

可能な戻り値は次のとおりである。

E_INVALIDARG | 無効な引数。
S_OK | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されない。

注意

ビデオ ウィンドウの x 軸座標は、このメソッドの呼び出しにより影響を受けない。

IVideoWindow::put_WindowState

IVideoWindow インターフェイス

ビデオ ウィンドウの状態を設定する。

構文

HRESULT put_WindowState(
    long WindowState
);

パラメータ

WindowState
[in] ビデオ ウィンドウの状態を記述する。

戻り値

可能な戻り値は次のとおりである。

S_OK | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されない。

注意

このメソッドは、Microsoft Win32 ShowWindow 関数のラッパーである。WindowState パラメータは、IVideoWindow::put_WindowState から CBaseWindow::DoShowWindow に渡され、さらにそこから ShowWindow に渡される。したがって、WindowState には ShowWindow に有効な任意の値を指定できる。

IVideoWindow::put_WindowStyle

IVideoWindow インターフェイス

ビデオ ウィンドウのスタイル パラメータを変更する。

構文

HRESULT put_WindowStyle(
    long WindowStyle
);

パラメータ

WindowStyle
[in] Win32 GetWindowLong 関数の GWL_STYLE 値で設定できるフラグのサブセットと対応するフラグ セット。

戻り値

可能な戻り値は次のとおりである。

S_OK | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されない。

注意

このプロパティを使用して、たとえばビデオ ウィンドウの境界およびキャプションの領域を削除するなど、ビデオ ウィンドウの全体的なスタイルを変更する。これは、Microsoft Win32 GetWindowLong 関数の GWL_STYLE 値の設定を制御する非常に薄いラッパーなので、取り扱いには十分な注意が必要である。特に、最初に現在のスタイルを取得したうえで、必要なビット フィールドを追加または削除することは重要である。(ここで説明する) 一部の例外を除き、使用可能なフラグは、Win32 CreateWindow 関数の場合と同じである。

このメソッドを使用して、ウィンドウ サイズに影響を与えてはならない。たとえば、ウィンドウが最小化されているときに WS_MAXIMIZE スタイルを設定した場合、結果は予測不可能である。ウィンドウを最大化または最小化するには、このメソッドではなく IVideoWindow::put_WindowState メソッドを使用する。

以下のスタイルでは、すべて E_INVALIDARG を返す。

  • WS_DISABLED
  • WS_HSCROLL
  • WS_ICONIC
  • WS_MAXIMIZE
  • WS_MINIMIZE
  • WS_VSCROLL

IVideoWindow::put_WindowStyleEx

IVideoWindow インターフェイス

コントロール ウィンドウのスタイルを設定する。

構文

HRESULT put_WindowStyleEx(
    long WindowStyleEx
);

パラメータ

WindowStyleEx
[in] コントロール ウィンドウのスタイルを指定する値。

戻り値

可能な戻り値は次のとおりである。

S_OK | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されない。

注意

このメソッドは、拡張ウィンドウ スタイルを使用する。ウィンドウ スタイルの一覧については、Platform SDK の ｢CreateWindowEx 関数｣を参照すること。

このプロパティを使用して、たとえばビデオ ウィンドウの境界およびキャプションの領域を削除するなど、ビデオ ウィンドウの全体的なスタイルを変更する。これは、Microsoft Win32 GetWindowLong 関数の GWL_STYLE 値の設定を制御する非常に薄いラッパーなので、取り扱いには十分な注意が必要である。特に、最初に現在のスタイルを取得したうえで、必要なビット フィールドを追加または削除することは重要である。

次のウィンドウ スタイルは有効でないので使用しないこと。

  • WS_DISABLED
  • WS_HSCROLL
  • WS_ICONIC
  • WS_MAXIMIZE
  • WS_MINIMIZE
  • WS_VSCROLL

(ここで説明する) 一部の例外を除き、使用可能なフラグは、Win32 CreateWindow 関数の場合と同じである。

IVideoWindow::SetWindowForeground

IVideoWindow インターフェイス

ビデオ ウィンドウを前面に移動し、オプションでそのウィンドウにフォーカスを与える。

構文

HRESULT SetWindowForeground(
    long Focus
);

パラメータ

Focus
ビデオ ウィンドウにフォーカスを与えるかどうかを指定する値。–1 の場合は、フォーカスを与える。0 の場合は、与えない。

戻り値

可能な戻り値は次のとおりである。

E_INVALIDARG | 無効な引数。
S_OK | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されない。

IVideoWindow::SetWindowPosition

IVideoWindow インターフェイス

(クライアントの矩形ではなく) ビデオ ウィンドウの位置をデバイス座標で設定する。

構文

HRESULT SetWindowPosition(
    long Left,
    long Top,
    long Width,
    long Height
);

パラメータ

Left
[in] ウィンドウの x 軸の基点。
Top
[in] ウィンドウの y 軸の基点。
Width
[in] ウィンドウの幅 (ピクセル単位)。
Height
[in] ウィンドウの高さ (ピクセル単位)。

戻り値

可能な戻り値は次のとおりである。

E_INVALIDARG | 無効な引数。
S_OK | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されない。

注意

このメソッドの効果は、IVideoWindow::put_Left メソッド、IVideoWindow::put_Top メソッド、IVideoWindow::put_Width メソッド、および IVideoWindow::put_Height メソッドを個別に呼び出した場合と等しい。

ビデオの表示位置をウィンドウ座標で指定する。たとえば、(100,50,200,400) という転送先を設定すると、ビデオ再生の基点がクライアント領域の左から 100 ピクセル、上から 50 ピクセルに設定され、全体のサイズが 200 × 400 ピクセルになる。ビデオがこれより小さい場合 (または転送元矩形がビデオより小さいサイズに指定されている場合) には、このサイズに合わせてビデオが伸縮される。同様に、ビデオが転送先矩形より大きい場合には、表示矩形に合わせてビデオが圧縮される。これらの処理はパフォーマンスに非常に大きな影響を与えるので、アプリケーションでは転送元矩形と転送先矩形をなるべく等しくすること。

通常の状況では、転送先矩形が設定されていないとき、(ユーザーによるウィンドウの伸縮の程度にかかわらず) ウィンドウのクライアント表示領域全体がビデオで塗りつぶされる。さらに、転送先矩形のプロパティは、ビデオ ウィンドウのクライアント領域の正しいサイズを返す。


IVPBaseConfig インターフェイス

IVPBaseConfig は、デコーダなどのハードウェア デバイスにグラフィックス アダプタへのビデオ ポートがある場合に、これらのデバイスをラップするフィルタに実装される。このインターフェイスを使用すると、ビデオ ポートがオーバーレイ ミキサーとの間で構成情報をやり取りできる。IVPConfig インターフェイスは、このインターフェイスから派生する。｢IVPBaseNotify｣および｢IVPNotify｣を参照すること。

アプリケーションからこのインターフェイスを使用しないこと。

要件

Dvp.h、Vptype.h、Vpconfig.h が必要である。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IVPBaseConfig メソッド | 説明
GetConnectInfo | コネクション情報の構造体を取得する。
SetConnectInfo | ビデオ ポートの現在のコネクション情報のインデックスを設定する。
GetVPDataInfo | ビデオ ポートの現在のデータ情報を取得する。
GetMaxPixelRate | 所定の幅および高さに対応する最大レート (ピクセル/秒) を取得する。
InformVPInputFormats | ビデオ ポートがサポートするビデオ フォーマットをデバイスに知らせる。
GetVideoFormats | デコーダがサポートするビデオ フォーマットを取得する。
SetVideoFormat | ビデオが使用するフォーマットを設定する。
SetInvertPolarity | デコーダが使用する現在の極性を反転する。
GetOverlaySurface | オーバーレイ ミキサーがドライバのオーバーレイ サーフェスを使用すべきかどうか判断し、使用すべき場合にはサーフェスへのポインタを取得する。
SetDirectDrawKernelHandle | デコーダのミニドライバが使用する Microsoft® DirectDraw® カーネル ハンドルを設定する。
SetVideoPortID | ビデオが使用するポート ID を設定する。
SetDDSurfaceKernelHandle | DirectDraw サーフェスが使用するカーネル ハンドルを設定する。
SetSurfaceParameters | オーバーレイ ミキサー フィルタまたは VBI サーフェス フィルタが代わりに作成したサーフェスについて、キャプチャ ドライバに知らせる。

IVPBaseConfig::GetConnectInfo

IVPBaseConfig インターフェイス

コネクション情報の構造体を取得する。

構文

HRESULT GetConnectInfo(
    LPDWORD pdwNumConnectInfo,
    LPDDVIDEOPORTCONNECT pddVPConnectInfo
    );

パラメータ

pdwNumConnectInfo
[in, out] pddVPConnectInfo パラメータが示す DDVIDEOPORTCONNECT 構造体の数が入ったバッファへのポインタ。実際に返された構造体の数が格納される。pddVPConnectInfo が NULL の場合、このパラメータはドライバでサポートされる構造体の数に置き換えられる。
pddVPConnectInfo
[in, out] ドライバが設定する DDVIDEOPORTCONNECT 構造体の配列へのポインタ。サポートされるフォーマットの総数を取得するには、NULL を指定する。

戻り値

カウントまたは構造体が取得された場合は、NOERROR を返す。それ以外の場合は、ドライバ エラーを返す。

注意

このメソッドは、GUID やポート幅などの各種コネクション情報の構造体を、pddVPConnectInfo で指定された構造体の配列に取得する。呼び出し先では、要求する構造体の数に適した正しい容量を割り当てる必要がある。

コネクション情報のインデックスを設定するには、IVPBaseConfig::SetConnectInfo メソッドを使用する。

IVPBaseConfig::GetMaxPixelRate

IVPBaseConfig インターフェイス

所定の幅および高さに対応する最大レート (ピクセル/秒) を取得する。

構文

HRESULT GetMaxPixelRate(
    LPAMVPSIZE pamvpSize,
    LPDWORD pdwMaxPixelsPerSecond
    );

パラメータ

pamvpSize
[in, out] 希望する幅および高さが格納された AMVPSIZE 構造体へのポインタ。メソッドから戻るときには、この構造体に最終的なディメンジョンが入る。
pdwMaxPixelsPerSecond
[out] 取得された最大レート (ピクセル/秒) へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | NULL ポインタ引数。
E_INVALIDARG | 無効な引数。
NOERROR | 最大レート (ピクセル/秒) が取得された。

注意

このメソッドは、所定のフォーマットおよび所定のスケーリング係数で予想される最大レート (ピクセル/秒) を取得する。デコーダがこれらのスケーリング係数をサポートしていない場合は、レートおよびサポートする最も近いスケーリング係数を返す。

IVPBaseConfig::GetOverlaySurface

IVPBaseConfig インターフェイス

オーバーレイ ミキサーがドライバのオーバーレイ サーフェスを使用すべきかどうか判断し、使用すべき場合にはサーフェスへのポインタを取得する。

構文

HRESULT GetOverlaySurface(
    LPDIRECTDRAWSURFACE *ppddOverlaySurface
    );

パラメータ

ppddOverlaySurface
[out] 取得された DirectDraw® オーバーレイ サーフェス オブジェクトへのポインタのアドレス。

戻り値

オーバーレイ サーフェス オブジェクトが返された場合は、NOERROR を返す (デフォルトの実装では、サーフェスに NULL を設定し、NOERROR を返す)。

注意

オーバーレイ ミキサーは、この関数を使用して、オーバーレイ ミキサーがドライバ側のオーバーレイ サーフェスを使用する必要があるかどうか判断し、必要がある場合にはそのポインタを取得する。この関数が NULL を返した場合には、オーバーレイ ミキサーが独自のサーフェスを割り当てる。

IVPBaseConfig::GetVideoFormats

IVPBaseConfig インターフェイス

デコーダがサポートするビデオ フォーマットを取得する。

構文

HRESULT GetVideoFormats(
    LPDWORD pdwNumFormats,
    LPDDPIXELFORMAT pddPixelFormats
    );

パラメータ

pdwNumFormats
[in, out] pddPixelFormats パラメータが示す DDPIXELFORMAT 構造体の数へのポインタ。呼び出すと、このメソッドはこのパラメータを実際に取得された構造体の数に置き換える。pddPixelFormats が NULL の場合、このメソッドはこのパラメータをドライバがサポートするフォーマットの数に置き換える。
pddPixelFormats
[in, out] ドライバが設定する DDPIXELFORMAT 構造体の配列へのポインタ。サポートされるフォーマットの総数だけを pdwNumFormats に取得するには、NULL を指定する。

戻り値

数または構造体が返された場合は、NOERROR を返す。それ以外の場合は、ドライバ エラーを返す。

注意

このメソッドは、ドライバでサポートされる DDPIXELFORMAT 構造体の数を照会するか、または提供されたバッファに入るできるだけ多くの構造体を取得する。

呼び出し先では、要求された構造体の数に適した正しい容量を割り当てる必要がある。

ビデオ フォーマットを設定するには、IVPBaseConfig::SetVideoFormat を使用する。

IVPBaseConfig::GetVPDataInfo

IVPBaseConfig インターフェイス

ビデオ ポートの現在のデータ情報を取得する。

構文

HRESULT GetVPDataInfo(
    LPAMVPDATAINFO pamvpDataInfo
    );

パラメータ

pamvpDataInfo
[in, out] AMVPDATAINFO データ情報の構造体へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | NULL ポインタ引数。
E_INVALIDARG | 無効な引数。
NOERROR | ビデオ ポートのデータ情報が取得された。

IVPBaseConfig::InformVPInputFormats

IVPBaseConfig インターフェイス

ビデオ ポートがサポートするビデオ フォーマットをデバイスに知らせる。

構文

HRESULT InformVPInputFormats(
    DWORD dwNumFormats,
    LPDDPIXELFORMAT pDDPixelFormats
    );

パラメータ

dwNumFormats
[in] pDDPixelFormats パラメータに格納されたビデオ フォーマットの数。
pDDPixelFormats
[in] デバイスに送るピクセル フォーマット構造体 (DDPIXELFORMAT) の配列へのポインタ。

戻り値

失敗した場合は、S_FALSE を返す。それ以外の場合は、NOERROR を返す。

注意

サポートされるビデオ ポート フォーマットとして指定した配列により、デバイスがそれらのフォーマットを提示する順序が決まることがある。

IVPBaseConfig::SetConnectInfo

IVPBaseConfig インターフェイス

ビデオ ポートの現在のコネクション情報のインデックスを設定する。

構文

HRESULT SetConnectInfo(
    DWORD dwChosenEntry
    );

パラメータ

dwChosenEntry
[in] ドライバに渡す (ビデオ ポートの) 新しいコネクション情報のインデックス (0 ベース)。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_INVALIDARG | 無効な引数。
NOERROR | ビデオ ポートのコネクション情報が設定された。

注意

コネクション情報を取得するには、IVPBaseConfig::GetConnectInfo を使用する。

IVPBaseConfig::SetDDSurfaceKernelHandle

IVPBaseConfig インターフェイス

DirectDraw サーフェスによって使用されるカーネル ハンドルを設定する。

構文

HRESULT SetDDSurfaceKernelHandle(
    DWORD dwDDKernelHandle
    );

パラメータ

dwDDKernelHandle
[in] カーネル モード用の DirectDraw サーフェス ハンドル。DWORD 値として渡す。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_INVALIDARG | 無効な引数。
NOERROR | 指定されたハンドルの設定に成功した。

注意

このメソッドは、ミニドライバに DirectDraw ハンドルを設定して、ミニドライバがビデオ ポートと直接通信できるようにする。

IVPBaseConfig::SetDirectDrawKernelHandle

IVPBaseConfig インターフェイス

デコーダのミニドライバが使用する DirectDraw® カーネル ハンドルを設定する。

構文

HRESULT SetDirectDrawKernelHandle(
    DWORD dwDDKernelHandle
    );

パラメータ

dwDDKernelHandle
[in] DirectDraw カーネル レベルのハンドル。DWORD 値として渡す。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_INVALIDARG | 無効な引数。
NOERROR | 指定されたハンドルの設定に成功した。

IVPBaseConfig::SetInvertPolarity

IVPBaseConfig インターフェイス

デコーダが使用する現在の極性を反転する。

構文

HRESULT SetInvertPolarity(void);

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
NOERROR | 極性が反転された。

注意

極性を反転するとは、デコーダに対し、偶数フィールドは奇数フィールドとして扱い、逆に奇数フィールドは偶数フィールドとして扱うように求めることを意味する。

IVPBaseConfig::SetSurfaceParameters

IVPBaseConfig インターフェイス

オーバーレイ ミキサー フィルタまたは VBI サーフェス フィルタが代わりに作成したサーフェスについて、キャプチャ ドライバに知らせる。

構文

HRESULT SetSurfaceParameters(
    DWORD dwPitch,
    DWORD dwXOrigin,
    DWORD dwYOrigin ) PURE;

パラメータ

dwPitch
[in] サーフェスのピッチ。サーフェスの連続する 2 ラインの開始ピクセル間の距離 (またはピッチ)。ピクセル単位で表す。
dwXOrigin
[in] 有効データが開始するピクセルの X 値。
dwYOrigin
[in] 有効データが開始するピクセルの Y 値。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。現在のデフォルトの実装は、呼び出しが成功した場合、NOERROR を返し、メソッドが実装されていない場合、E_NOTIMPL を返す。

IVPBaseConfig::SetVideoFormat

IVPBaseConfig インターフェイス

ビデオが使用するフォーマットを設定する。

構文

HRESULT SetVideoFormat(
    DWORD dwChosenEntry
    );

パラメータ

dwChosenEntry
[in] ビデオのピクセル フォーマットのインデックス (0 ベース) を指定する値。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_INVALIDARG | 無効な引数。
NOERROR | 新しいビデオ フォーマットが設定された。

注意

ビデオ フォーマットを取得するには、IVPBaseConfig::GetVideoFormats を使用する。

IVPBaseConfig::SetVideoPortID

IVPBaseConfig インターフェイス

ビデオが使用するポート ID を設定する。

構文

HRESULT SetVideoPortID (
    DWORD dwVideoPortID
    );

パラメータ

dwVideoPortID
[in] DirectDraw ビデオ ポート ID。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_INVALIDARG | 無効な引数。
NOERROR | 指定されたポート ID の設定に成功した。

注意

このメソッドは、ミニドライバに DirectDraw ビデオ ポート ID を設定して、ミニドライバがビデオ ポートと直接通信できるようにする。


IVPBaseNotify インターフェイス

ビデオ ポートを使用するデコーダなどのハードウェア デバイスのプロパティを、オーバーレイ ミキサーから制御できるようにする。IVPNotify インターフェイスは、このインターフェイスから派生する。｢IVPBaseConfig」および「IVPConfig｣を参照すること。

アプリケーションからこのインターフェイスを使用してはならない。

要件

Vptype.h、Vpnotify.h が必要である。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IVPBaseNotify メソッド | 説明
RenegotiateVPParameters | デコーダとの接続を初期化する。

IVPBaseNotify::RenegotiateVPParameters

IVPBaseNotify インターフェイス

デコーダとの接続を初期化する。

構文

HRESULT RenegotiateVPParameters(void) PURE;

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | NULL ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
NOERROR | エラーなし。

注意

オーバーレイ ミキサー フィルタは、デコーダまたはドライバとの間で (IVPBaseConfig インターフェイスを使用して) 各種パラメータをネゴシエートする。それらのパラメータのいずれか (ビデオ フォーマット、サイズなど) が変わったら、このメソッドを呼び出す。現在のオーバーレイ ミキサーでは、接続処理全体を繰り返す。このメソッドはグラフの再生中でも呼び出すことができる。


IVPConfig インターフェイス

ビデオ ポートを持つハードウェア デコーダをラップするフィルタでは、すべて IVPConfig を実装する必要がある。このインターフェイスを使用すると、オーバーレイ ミキサーは、その IVPNotify インターフェイスを通じて、ディスプレイ アダプタのビデオ メモリに関するビデオ ポート上の構成情報を設定および取得できる。このインターフェイスは、IVPBaseConfig から派生する。｢IVPBaseNotify」および「IVPNotify2｣を参照すること。

アプリケーションからこのインターフェイスを使用しないこと。

要件

Dvp.h、Vptype.h、Vpconfig.h が必要である。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IVPBaseConfig メソッド | 説明
GetConnectInfo | 接続情報の構造体を取得する。
SetConnectInfo | ビデオ ポートの現在の接続情報のインデックスを設定する。
GetVPDataInfo | ビデオ ポートの現在のデータ情報を取得する。
GetMaxPixelRate | 所定の幅および高さに対応する最大レート (ピクセル/秒) を取得する。
InformVPInputFormats | ビデオ ポートがサポートするビデオ フォーマットをデバイスに知らせる。
GetVideoFormats | デコーダがサポートするビデオ フォーマットを取得する。
SetVideoFormat | ビデオが使用するフォーマットを設定する。
SetInvertPolarity | デコーダが使用する現在の極性を反転する。
GetOverlaySurface | オーバーレイ ミキサーがドライバのオーバーレイ サーフェスを使用すべきかどうか判断し、また使用すべき場合には、サーフェスへのポインタを取得する。
SetDirectDrawKernelHandle | デコーダのミニドライバが使用する DirectDraw® カーネル ハンドルを設定する。
SetVideoPortID | ビデオが使用するポート ID を設定する。
SetDDSurfaceKernelHandle | DirectDraw サーフェスが使用するカーネル ハンドルを設定する。
SetSurfaceParameters | キャプチャ ドライバに、オーバーレイ ミキサー フィルタまたは VBI サーフェス フィルタで代わりに作成されたサーフェスについて知らせる。
IVPConfig メソッド | 説明
IsVPDecimationAllowed | 所定のコンテキストで、ビデオ ポートでのスケーリングが可能かどうかを取得する。
SetScalingFactors | デコーダがビデオ ストリームをスケールする際の係数を設定する。

IVPConfig::IsVPDecimationAllowed

IVPConfig インターフェイス

所定のコンテキストで、ビデオ ポートでのスケーリングが可能かどうかを取得する。

構文

HRESULT IsVPDecimationAllowed(
    AMVP_CONTEXT amvpContext,
    LPBOOL pbIsDecimationAllowed
    );

パラメータ

amvpContext
[in] VP のデシメーション能力を照会するコンテキスト (ビデオまたは VBI)。
pbIsDecimationAllowed
[out] デシメーションが可能かどうかを示す取得された値へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | NULL ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
NOERROR | エラーなし。

注意

オーバーレイ ミキサー フィルタは、この関数を使用して、そのドライバでは、ビデオ データのデシメーションをミキサー側が独自の判断で行う必要があるかどうかを判断する。プレビュー付きのキャプチャで、VP ミキサー フィルタによってビデオ ポート上でスケーリングが行われると都合が悪い場合などには、この関数が特に便利である。

IVPConfig::SetScalingFactors

IVPConfig インターフェイス

デコーダがビデオ ストリームをスケールする際の係数を設定する。

構文

HRESULT SetScalingFactors(
    LPAMVPSIZE pamvpSize
    );

パラメータ

pamvpSize
[in] 幅および高さの指定に使用する新しいスケーリング サイズの構造体 (AMVPSIZE) へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
NOERROR | 新しいスケーリング係数が設定された。

注意

指定されたスケーリング係数をサポートしていない場合には、サポート可能な最も近い係数が設定される。


IVPNotify インターフェイス

オーバーレイ ミキサー フィルタと、ハードウェア デコーダを表す VPE デコーダ フィルタの間の、ローカルな通信メカニズムをサポートする。このインターフェイスは、IVPBaseNotify から派生する。「IVPBaseConfig」および「IVPConfig」を参照すること。

このインターフェイスを実装するのは、オーバーレイ ミキサー フィルタのみである。アプリケーションから使用してはならない。

要件

Vptype.h、Vpnotify.h が必要である。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IVPBaseNotify メソッド | 説明
RenegotiateVPParameters | デコーダとの接続を初期化する。
IVPNotify メソッド | 説明
SetDeinterlaceMode | 非インターレース モード (Bob、Weave など) を設定する。
GetDeinterlaceMode | 非インターレース モード (Bob、Weave など) を取得する。

IVPNotify::GetDeinterlaceMode

IVPNotify インターフェイス

モード (Bob、Weave など) を取得する。

このメソッドは現在実装されていない。E_NOTIMPL を返す。

構文

HRESULT GetDeinterlaceMode(
  AMVP_MODE *pmode
) PURE;

パラメータ

pmode
[out] 取得されたモードへのポインタ。この値は AMVP_MODE 列挙型のメンバ。

戻り値

E_NOTIMPL を返す。

IVPNotify::SetDeinterlaceMode

IVPNotify インターフェイス

モード (Bob、Weave など) を設定する。

構文

HRESULT SetDeinterlaceMode(
    AMVP_MODE mode
    ) PURE;

パラメータ

mode
[in] 指定されたモード。この値は、AMVP_MODE 列挙型のメンバ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。


IVPNotify2 インターフェイス

IVPNotify2 インターフェイスは、IVPNotify を継承するものであり、オーバーレイ ミキサー フィルタでのみ実装される。このインターフェイスを使用すると、オーバーレイ ミキサーから IVPConfig を実装する (デコーダなどのハードウェア デバイス上にある) ビデオ ポートと通信することができる。

アプリケーションからこのインターフェイスを使用してはならない。

要件

Vptype.h、Vpnotify.h が必要である。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IVPNotify2 メソッド | 説明
SetVPSyncMaster | ビデオ ポートが VGA の垂直同期を制御するかどうかを設定する。
GetVPSyncMaster | ビデオ ポートが VGA の同期を制御するかどうかを確認する。

IVPNotify2::GetVPSyncMaster

IVPNotify2 インターフェイス

ビデオ ポートが VGA の同期を制御するかどうかを確認する。

構文

HRESULT GetVPSyncMaster(
    BOOL *pbVPSyncMaster
) PURE;

パラメータ

pbVPSyncMaster
[out] ビデオ ポートが VGA モニタの垂直同期を制御するかどうかを示す値へのポインタ。ポートがモニタの同期を制御する場合は TRUE。それ以外の場合は FALSE。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

IVPNotify2::SetVPSyncMaster

IVPNotify2 インターフェイス

ビデオ ポートが VGA の垂直同期を制御するかどうかを設定する。

構文

HRESULT GetVPSyncMaster(
    BOOL bVPSyncMaster
) PURE;

パラメータ

bVPSyncMaster
[in] ビデオ ポートが VGA モニタの垂直同期を制御するかどうかを指定する値。ポートがモニタの同期を制御する場合は TRUE。それ以外の場合は FALSE。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。


構造体

ここでは、Microsoft® DirectShow® の構造体について説明する。

構造体 | 説明
ALLOCATOR_PROPERTIES | アロケータのプロパティ (カウント、サイズ、アラインメント、およびプレフィックス) が格納される。
AM_DVD_RENDERSTATUS | DVD ビデオ再生の状態を示すコードが格納される。このコードは、IDvdGraphBuilder::RenderDvdVideoVolume メソッドで使用される。
AM_MEDIA_TYPE | メディア サンプルのタイプを記述する。
AM_SAMPLE2_PROPERTIES | 汎用メディア サンプルのプロパティを記述する。
AMOVIESETUP_FILTER | フィルタを登録するためのフィルタ情報が格納される。
AMOVIESETUP_MEDIATYPE | フィルタを登録するためのメディア タイプ情報が格納される。
AMOVIESETUP_PIN | フィルタを登録するためのピン情報が格納される。
AM_STREAM_INFO | ピンに渡された開始および停止の情報が格納される。
AMVABeginFrameInfo | フレームの処理を開始するために必要な情報を指定する。
AMVABUFFERINFO | バッファ情報を記述する。
AMVACompBufferInfo | 割り当てられたサーフェスおよび圧縮バッファの情報を記述する。
AMVAEndFrameInfo | フレームの処理を終了するための情報を指定する。
AMVAInternalMemInfo | ハードウェア アブストラクション レイヤ (HAL) が内部で使用するために割り当てるスクラッチ メモリの量を指定する。
AMVAUncompBufferInfo | 割り当てるサーフェスを記述する。
AMVAUncompDataInfo | データ入力ストリームのピクセル フォーマットおよびディメンジョン特性を指定する。
AMVPDATAINFO | VP 入力ストリームに関するデータ固有の特性を指定する。
AMVPDIMINFO | VP 入力ストリームに関するディメンジョン特性を指定する。
AMVPSIZE | VP イメージの幅と高さを指定する。
DVD_ATR | DVD の属性を指定する。
DVD_DECODER_CAPS | オーディオ デコーダの能力に関する情報が格納される。
DVD_HMSF_TIMECODE | 古い DVD_TIMECODE 構造体より使いやすいようにタイムコード情報をカプセル化する。DVD_HMSF_TIMECODE は新しい DVD2 インターフェイスと共に使用する。
DVD_KaraokeAttributes | DVD ディスクのカラオケ オーディオ ストリームに関する情報が格納される。
DVD_MenuAttributes | DVD ディスクのメニューに関する情報が格納される。
DVD_MUA_Coeff | DVD のマルチチャンネル オーディオに対応するサラウンド サウンド ミキシング係数に関する情報が格納される。
DVD_MUA_MixingInfo | DVD ディスクのサラウンド サウンド ミキシング係数に関する情報が格納される。
DVD_MultichannelAudioAttributes | DVD ディスクのマルチチャンネル オーディオに関する情報が格納される。
DVD_PLAYBACK_LOCATION | DVD の再生位置が格納される。
DVD_PLAYBACK_LOCATION2 | DVD の再生位置が格納される。新しい DVD2 インターフェイスと共に使用する。
DVD_SubpictureAttributes | DVD ディスクのサブピクチャ ストリームに関する情報が格納される。
DVD_TIMECODE | DVD のタイムコード (時、分、秒、およびフレーム) が格納される。
DVD_TitleAttributes | DVD ディスクのタイトルに関する情報が格納される。
DVD_VideoAttributes | DVD ディスクのビデオ ストリームに関する情報が格納される。
FILTER_INFO | フィルタに関する情報が格納される。
PIN_INFO | ピンの情報が格納される。
Quality | レンダラのパフォーマンスを最適化するため、レンダラ内がデータ過剰かデータ不足かを示し、フレームを加減するパーセンテージを指定することによって、品質メッセージを記述する。
REGFILTER | レジストリ内のフィルタを記述する。
REGFILTER2 | IFilterMapper2 インターフェイスを通じて登録するためにフィルタを記述する。
REGFILTERPINS | フィルタを登録するためのピン情報が格納される。
REGFILTERPINS2 | IFilterMapper2 インターフェイスを通じてフィルタを登録するための情報が格納される。
REGPINMEDIUM | IFilterMapper2 インターフェイスを通じて登録するために、(Microsoft Windows® NT DDK に定義された) ピンのメディアを記述する。
REGPINTYPES | フィルタを登録するためのメディア タイプ情報が格納される。
STREAM_ID_MAP | MPEG-2 ストリーム内の基本ストリームについての情報が格納される。

次の構造体は、グラフィック デバイス インターフェイス (GDI) のビットマップおよびデバイスに依存しないビットマップ (DIB) に関する情報を保持する。CImageAllocator、CImageSample、および CDrawImage ウィンドウ ユーティリティ クラスのみで使用される。

構造体 | 説明
DIBDATA | 個々の DIB に関する情報が格納される。

以下の構造体は、ビデオとビデオのキャプチャおよび圧縮に関する情報を保持する。

構造体 | 説明
TRUECOLORINFO | 色情報を保持する。
ANALOGVIDEOINFO | アナログ ビデオ信号のフォーマットに関する情報を保持する。
AUDIO_STREAM_CONFIG_CAPS | サポートされる可能なオーディオ フォーマットすべてに関する情報が格納される。
COLORKEY | レンダラとほかのフィルタとの間でカラー キー情報をやり取りする。
MPEG1VIDEOINFO | MPEG-1 ビデオの追加システム情報が格納される。
MPEG2VIDEOINFO | MPEG-2 ビデオの追加システム情報が格納される。
TIMECODE | 基本的なタイムコード フレーム カウント情報が格納される。
TIMECODE_SAMPLE | タイムコードの完全な情報が格納される。
VIDEO_STREAM_CONFIG_CAPS | 可能な接続に関する情報が格納される。
VIDEOINFO | ビデオ イメージとそのカラー パレットおよびビットマスクを指定する情報が格納される。
VIDEOINFOHEADER | ビデオ イメージのビットマップと色情報を記述する。
VIDEOINFOHEADER2 | インターレース、コピー保護、およびピクセルのアスペクト比情報を含む、ビデオ イメージのビットマップと色情報を記述する。


ALLOCATOR_PROPERTIES 構造体

構造体

アロケータのプロパティ (カウント、サイズ、アラインメント、およびプレフィックス) の記述。

構文

typedef struct _AllocatorProperties {
    long cBuffers;
    long cbBuffer;
    long cbAlign;
    long cbPrefix;
} ALLOCATOR_PROPERTIES;

メンバ

cBuffers
このアロケータのバッファ数。
cbBuffer
プレフィックスを除いた各バッファのサイズ (バイト単位)。
cbAlign
バッファのアラインメント。バッファはこの値の倍数から始まる。
cbPrefix
各バッファの先頭にあるプレフィックスのバイト数。

注意

IMediaSample::GetPointer メンバ関数はバッファの先頭ポインタを返すが、cbPrefix が設定したプレフィックスのバイト数は含まない。

アラインメントはプレフィックス データに適用される (ある場合)。プレフィックスのサイズが 0 でない場合、プレフィックスの先頭は cbAlign に従ってアラインメントされる。


AM_DVD_RENDERSTATUS 構造体

構造体

DVD ビデオ再生の状態を示すコードが格納される。このコードは、IDvdGraphBuilder::RenderDvdVideoVolume メソッドで使用される。

構文

typedef struct {
    HRESULT hrVPEStatus;
    BOOL    bVPEFailed;
    BOOL    bDVDVolInvalid;
    BOOL    bDVDVolUnknown;
    BOOL    bNoLine21In;
    BOOL    bNoLine21Out;
    int     iNumStreams;
    int     iNumStreamsFailed;
    DWORD   dwFailedStreamsFlag;
} AM_DVD_RENDERSTATUS;

メンバ

hrVPEStatus
オーバーレイ/VPE エラー コード。0 は成功を示し、その他の値は失敗を示す。
bDVDVolInvalid
再生するように指定された DVD ボリュームが存在しない場合は、TRUE。それ以外の場合は、FALSE。
bDVDVolUnknown
DVD ボリュームが指定されていないか、または見つからない場合は、TRUE。それ以外の場合は、FALSE。
bNoLine21In
ビデオ デコーダが Line 21 (クローズド キャプション) データを生成しない場合は、TRUE。それ以外の場合は、FALSE。
bNoLine21Out
グラフ構築に問題があり、ビデオ上にクローズド キャプションとしてビデオ デコーダを表示できない場合は、TRUE。それ以外の場合は、FALSE。
iNumStreams
レンダリングする DVD ストリームの数。
iNumStreamsFailed
レンダリングに失敗したストリームの数。
dwFailedStreamsFlag
失敗したストリームを示す AM_DVD_STREAM_FLAGS フラグの組み合わせ。

参照

IDvdGraphBuilder::RenderDvdVideoVolume


AM_MEDIA_TYPE 構造体

構造体

メディア サンプルのフォーマットを記述。

AM_MEDIA_TYPE 構造体との共同動作については、「メディア タイプ関数」を参照すること。

構文

typedef struct  _MediaType
{
    GUID      majortype;
    GUID      subtype;
    BOOL      bFixedSizeSamples;
    BOOL      bTemporalCompression;
    ULONG     lSampleSize;
    GUID      formattype;
    IUnknown  *pUnk;
    ULONG     cbFormat;
    /* [size_is] */ BYTE __RPC_FAR *pbFormat;
} AM_MEDIA_TYPE;

メンバ

majortype
メディア サンプルの メジャー タイプを指定するグローバル ユニーク識別子 (GUID)。
subtype
メディア サンプルのサブタイプを指定する GUID。詳細については、「メディア タイプ」を参照すること。
bFixedSizeSamples
TRUE の場合、サンプルのサイズは固定である。このフィールドは参照専用である。通常、オーディオでは TRUE に設定される。ビデオでは、通常、圧縮されていなければ TRUE、圧縮されていれば FALSE に設定される。
bTemporalCompression
TRUE の場合、サンプルは時系列 (フレーム間) 圧縮方式で圧縮されている。値 TRUE はフレームがすべてキー フレームとは限らないことを示す。このフィールドは参照専用である。
lSampleSize
サンプルのサイズ (バイト単位)。圧縮データでは 0 の場合がある。
formattype
フォーマット タイプを指定する GUID。pbFormat メンバは対応するフォーマット構造体を指す。フォーマット タイプには次のものがある :
フォーマット タイプ | フォーマット構造体
FORMAT_None | フォーマット タイプなし
FORMAT_MPEGVideo | MPEG1VIDEOINFO
FORMAT_MPEG2Video | MPEG2VIDEOINFO
FORMAT_VideoInfo | VIDEOINFOHEADER
FORMAT_VideoInfo2 | VIDEOINFOHEADER2
FORMAT_WaveFormatEx | WAVEFORMATEX
pUnk
未使用。
cbFormat
メディア タイプのフォーマット ブロックのサイズ。
pbFormat
フォーマット構造体へのポインタ。構造体の種類は formattype メンバで指定される。formattype が GUID_NULL または FORMAT_None でない限り、フォーマット構造体が存在しなければならない。

注意

フィルタが接続したとき、通常フィルタはメディア タイプをネゴシエーションする。メディア タイプはフィルタが交換するデータのフォーマットを記述する。フィルタがメディア タイプを受け入れないなら、接続はできない。Microsoft® DirectShow® は AM_MEDIA_TYPE 構造体でメディア タイプを記述する。

メディア タイプの最初のパートにはデータ ストリームの一般属性が入っている。たとえば、bFixedSizeSamples メンバはデータが固定サイズのバッファで渡されるかどうかを宣言する。2 つ目のパートはフォーマット ブロックと呼ばれるフォーマット固有のヘッダーが入る可変長ブロックのデータである。pbFormat メンバはこのブロックへのポインタである。フォーマット ブロックのレイアウトはストリーム内のデータ タイプに依存する。たとえば、データ ストリームにビデオ フレームが入っているなら、そのフォーマット ブロックは VIDEOINFOHEADER 構造体である。

ストリーム タイプは メジャー タイプと サブタイプと呼ばれる 2 つの GUID によって指定される。メジャー タイプはビデオ、オーディオ、あるいはバイト ストリームの様な一般的なカテゴリを定義する。サブタイプはメジャー タイプ内部のより細かいカテゴリを定義する。たとえば、8-bit、16-bit、24-bit、そして 32-bit RGB を含むビデオ サブタイプ。

ある場合には、サブタイプは (ビット深度のように) フォーマットで指定された情報をコピーする。しかしフォーマット タイプに GUID_NULL を指定すると役に立つ場合もある。完全なフォーマットを与えることなく、サブタイプによってあるフォーマット情報を指定することができる。たとえば、ビデオフレームの個々の幅や高さを与えることなく、24ビット RGB を指定することができる。


AM_SAMPLE2_PROPERTIES 構造体

構造体

汎用メディア サンプルのプロパティを記述する。IMediaSample2 インターフェイスはこの構造体を使用する。

構文

typedef struct tagAM_SAMPLE2_PROPERTIES
{
    DWORD    cbData;
    DWORD    dwTypeSpecificFlags;
    DWORD    dwSampleFlags;
    LONG     lActual;
    REFERENCE_TIME tStart;
    REFERENCE_TIME tStop;
    DWORD    dwStreamId;
    AM_MEDIA_TYPE *pMediaType;
    BYTE    *pbBuffer;
    LONG     cbBuffer;
} AM_SAMPLE2_PROPERTIES;

メンバ

cbData
プロパティ データの長さ (バイト単位)。この構造体メンバは拡張用である。
dwTypeSpecificFlags
タイプ固有のフラグ データ。フラグはメディア タイプごとに定義される。デフォルトは 0。
dwSampleFlags
データ タイプを列挙する AM_SAMPLE_PROPERTY_FLAGS フラグのビット組み合わせ。未定義のビットは予約されており、ゼロでなければならない。
lActual
バッファ内の有効なデータの長さ。
tStart
有効なら、開始タイム。dwSampleFlags メンバはこのメンバが有効かどうかを示す。
tStop
有効なら、終了タイム。dwSampleFlags メンバはこのメンバが有効かどうかを示す。
dwStreamId
ストリーム識別子。この値が AM_STREAM_MEDIA なら、ストリームにはメディア データが入る。この値が AM_STREAM_CONTROL なら、ストリ－ムにはコントロール情報が入る。アプリケーションは 0x80000000 以上の値をアプリケーション自身の用途に使用できる。
pMediaType
メディア タイプを示す AM_MEDIA_TYPE 構造体へのポインタ。
pbBuffer
バッファへのポインタ。このプロパティは読み込み専用である。
cbBuffer
バッファのサイズ (バイト単位)。このプロパティは読み込み専用である。


AM_STREAM_INFO 構造体

構造体

ピンに渡された開始および停止の情報が入る。

構文

typedef struct {
    REFERENCE_TIME tStart;
    REFERENCE_TIME tStop;
    DWORD dwStartCookie;
    DWORD dwStopCookie;
    DWORD dwFlags;
} AM_STREAM_INFO;

メンバ

tStart
ストリーミングの開始タイム。
tStop
ストリーミングの終了タイム。
dwStartCookie
開始を指示したアプリケーションにイベント発生時に渡される番号。
dwStopCookie
停止を指示したアプリケーションにイベント発生時に渡される番号。
dwFlags
AM_STREAM_INFO_FLAGS 列挙型のフラグ。

注意

この構造体は、IAMStreamControl インターフェイスを通じてアクセスする。


AMOVIESETUP_FILTER 構造体

構造体

フィルタを登録するための情報が入る。

構文

typedef struct _AMOVIESETUP_FILTER
{
    const CLSID           *clsID;
    const WCHAR           *strName;
    DWORD                 dwMerit;
    UINT                  nPins;
    const AMOVIESETUP_PIN *lpPin;
} AMOVIESETUP_FILTER, * PAMOVIESETUP_FILTER, * FAR LPAMOVIESETUP_FILTER;

メンバ

clsID
フィルタのクラス識別子。
strName
フィルタの名前。
dwMerit
フィルタのメリット。IGraphBuilder インターフェイスがフィルタ グラフの構築時に使用する。
nPins
フィルタのピンの数。
lpPin
AMOVIESETUP_PIN 構造体の配列へのポインタ。配列のサイズは nPins。


AMOVIESETUP_MEDIATYPE 構造体

「REGPINTYPES」を参照すること。


AMOVIESETUP_PIN 構造体

「REGFILTERPINS」を参照すること。


AMVABeginFrameInfo 構造体

構造体

フレームの処理を開始するために必要な情報を指定する。

注 : この構造体は、Microsoft® Windows® 98 Second Edition および Windows 2000 で利用可能である。

構文

typedef struct _tag_AMVABeginFrameInfo{
    DWORD dwDestSurfaceIndex;
    LPVOID pInputData;
    DWORD dwSizeInputData;
    LPVOID pOutputData;
    DWORD dwSizeOutputData;
 } AMVABeginFrameInfo, *LPAMVABeginFrameInfo;

メンバ

dwDestSurfaceIndex
このフレームをデコードする転送先バッファ。
pInputData
その他のデータへのポインタ。
dwSizeInputData
フレーム処理を開始するためのその他のデータ サイズ。
pOutputData
VGA (Video Graphics Array) によって設定されるデータへのポインタ。
dwSizeOutputData
VGA によって設定されるデータのサイズ。

注意

pInputData にはポインタを格納できないので注意すること。これは、フレームの処理が行われるカーネル モードでは、そのアドレスが有効でないためである。


AMVABUFFERINFO 構造体

構造体

バッファ情報を記述する。

注 : この構造体は、Microsoft® Windows® 98 Second Edition および Windows 2000 で利用可能である。

構文

typedef struct _tag_AMVABUFFERINFO{
    DWORD dwTypeIndex;
    DWORD dwBufferIndex;
    DWORD dwDataOffset;
    DWORD dwDataSize;
 } AMVABUFFERINFO, *LPAMVABUFFERINFO;

メンバ

dwTypeIndex
バッファの種類。
dwBufferIndex
バッファのインデックス。
dwDataOffset
関連データのバッファ先頭からのオフセット。
dwDataSize
関連データのサイズ。


AMVACompBufferInfo 構造体

構造体

割り当てられたサーフェスおよび圧縮バッファの情報を記述する。

注 : この構造体は、Microsoft® Windows® 98 Second Edition および Windows 2000 で利用可能である。

構文

typedef struct _tag_AMVACompBufferInfo{
    DWORD dwNumCompBuffers;
    DWORD dwWidthToCreate;
    DWORD dwHeightToCreate;
    DWORD dwBytesToAllocate;
    DDSCAPS2 ddCompCaps;
    DDPIXELFORMAT ddPixelFormat;
 } AMVACompBufferInfo, *LPAMVACompBufferInfo;

メンバ

dwNumCompBuffers
圧縮データ用に要求されたバッファの数。
dwWidthToCreate
作成するサーフェスの幅。
dwHeightToCreate
作成するサーフェスの高さ。
dwBytesToAllocate
各サーフェスで使用されるトータルのバイト数。
ddCompCaps
圧縮データを格納するために作成された DirectDrawSurface オブジェクトの能力を定義する DDSCAPS2 構造体。
ddPixelFormat
圧縮データを格納するサーフェスの作成に使用されたピクセル フォーマットを記述する DDPIXELFORMAT 構造体。


AMVAEndFrameInfo 構造体

構造体

フレームの処理を終了するための情報を指定する。

注 : この構造体は、Microsoft® Windows® 98 Second Edition および Windows 2000 で利用可能である。

構文

typedef struct _tag_AMVAEndFrameInfo{
    DWORD dwSizeMiscData;
    LPVOID pMiscData;
 } AMVAEndFrameInfo, *LPAMVAEndFrameInfo;

メンバ

dwSizeMiscData
フレームを開始するためのその他のデータ サイズ。
pMiscData
その他のデータへのポインタ。

注意

pMiscData にはポインタを格納できないので注意すること。


AMVAInternalMemInfo 構造体

構造体

ハードウェア アブストラクション レイヤ (HAL) が内部で使用するために割り当てるスクラッチ メモリの量を指定する。

注 : この構造体は、Microsoft® Windows® 98 Second Edition および Windows 2000 で利用可能である。

構文

typedef struct _tag_AMVAInternalMemInfo{
    DWORD dwScratchMemAlloc;
 } AMVAInternalMemInfo, *LPAMVAInternalMemInfo;

メンバ

dwScratchMemAlloc
HAL が内部で使用するために割り当てるスクラッチ メモリの量を指定する。


AMVAUncompBufferInfo 構造体

構造体

割り当てるサーフェスを記述する。

注 : この構造体は、Microsoft® Windows® 98 Second Edition および Windows 2000 で利用可能である。

構文

typedef struct _tag_AMVAUncompBufferInfo{
    DWORD dwMinNumSurfaces;
    DWORD dwMaxNumSurfaces;
    DDPIXELFORMAT ddUncompPixelFormat;
 } AMVAUncompBufferInfo, *LPAMVAUncompBufferInfo;

メンバ

dwMinNumSurfaces
割り当てるサーフェスの最小数。
dwMaxNumSurfaces
割り当てるサーフェスの最大数。
ddUncompPixelFormat
割り当てるサーフェスのピクセル フォーマットを記述する DDPIXELFORMAT 構造体。


AMVAUncompDataInfo 構造体

構造体

データ入力ストリームのピクセル フォーマットおよびディメンジョン特性を指定する。

注 : この構造体は、Microsoft® Windows® 98 Second Edition および Windows 2000 で利用可能である。

構文

typedef struct _tag_AMVAUncompDataInfo{
    DWORD dwUncompWidth;
    DWORD dwUncompHeight;
    DDPIXELFORMAT ddUncompPixelFormat;
 } AMVAUncompDataInfo, *LPAMVAUncompDataInfo;

メンバ

dwUncompWidth
非圧縮データの幅。
dwUncompHeight
非圧縮データの高さ。
ddUncompPixelFormat
非圧縮データのピクセル フォーマットを記述する DDPIXELFORMAT 構造体。


AMVPDATAINFO 構造体

構造体

VP 入力ストリームに関するデータ固有の特性を指定する。

構文

typedef struct _AMVPDATAINFO{
    DWORD dwSize;
    DWORD dwMicrosecondsPerField;
    AMVPDIMINFO amvpDimInfo;
    DWORD dwPictAspectRatioX;
    DWORD dwPictAspectRatioY;
    BOOL bEnableDoubleClock;
    BOOL bEnableVACT;
    BOOL bDataIsInterlaced;
    LONG lHalfLinesOdd;
    BOOL bFieldPolarityInverted;
    DWORD dwNumLinesInVREF;
    LONG lHalfLinesEven;
    DWORD dwReserved1;
} AMVPDATAINFO, *LPAMVPDATAINFO;

メンバ

dwSize
構造体のサイズ (バイト単位)。
dwMicrosecondsPerField
各フィールドの所要時間。
amvpDimInfo
ディメンジョン情報。
dwPictAspectRatioX
画像アスペクト比の x ディメンジョン。
dwPictAspectRatioY
画像アスペクト比の y ディメンジョン。
bEnableDoubleClock
ビデオ ポートはダブルクロッキングを有効にする必要がある。
bEnableVACT
ビデオ ポートは外部 VACT 信号を使用する必要がある。
bDataIsInterlaced
インターレース信号であることを示す。
lHalfLinesOdd
奇数フィールドのハーフ ライン数。
bFieldPolarityInverted
ビデオ ポートはフィールド極性を反転する必要がある。
dwNumLinesInVREF
VREF のデータのライン数。
lHalfLinesEven
偶数フィールドのハーフ ライン数。
dwReserved1
将来的な使用のために予約されている。


AMVPDIMINFO 構造体

構造体

VP 入力ストリームに関するディメンジョン特性を指定する。

構文

typedef struct _AMVPDIMINFO{
    DWORD dwFieldWidth;
    DWORD dwFieldHeight;
    DWORD dwVBIWidth;
    DWORD dwVBIHeight;
    RECT rcValidRegion;
} AMVPDIMINFO, *LPAMVPDIMINFO;

メンバ

dwFieldWidth
データのフィールドの幅。
dwFieldHeight
データのフィールドの高さ。
dwVBIWidth
VBI データの幅。
dwVBIHeight
VBI データの高さ。
rcValidRegion
クロッピングに使用する有効な矩形。


AMVPSIZE 構造体

構造体

VP イメージの幅と高さを指定する。

構文

typedef struct _AMVPSIZE{
DWORD dwWidth;
DWORD dwHeight;
} AMVPSIZE, *LPAMVPSIZE;

メンバ

dwWidth
幅 (ピクセル単位)。
dwHeight
高さ。

注意

コンテキストは限定されない (スケーリング、クロッピングなど)。


ANALOGVIDEOINFO 構造体

構造体

アナログ ビデオ信号のフォーマットに関する情報を保持する。

構文

typedef struct tagAnalogVideoInfo {
    RECT            rcSource;
    RECT            rcTarget;
    DWORD           dwActiveWidth;
    DWORD           dwActiveHeight;
    REFERENCE_TIME  AvgTimePerFrame;
} ANALOGVIDEOINFO;

メンバ

rcSource
ソース ビデオの矩形。
rcTarget
転送先のターゲット矩形。
dwActiveWidth
ソース ビデオの幅。
dwActiveHeight
ソース ビデオの高さ (NTSC では 483、PAL および SECAM では 575)。
AvgTimePerFrame
フレームの平均時間 (100 ナノ秒単位)。

注意

通常、このフォーマットを使用するフィルタは、メモリ ベースの転送ではなくハードウェア ベースの接続によってビデオ信号を渡す。

メディア タイプがアナログ ビデオの接続が定義される例としては、"M" 色の符号化を使用して NTSC ビデオを接続する場合が挙げられる。この場合、メジャー タイプ、サブタイプ、およびフォーマット タイプ に、それぞれ MEDIATYPE_AnalogVideo、MEDIASUBTYPE_AnalogVideo_NTSC_M、FORMAT_AnalogVideo が使用される。


AUDIO_STREAM_CONFIG_CAPS 構造体

構造体

サポートされる可能なオーディオ フォーマットすべてに関する情報が格納される。

構文

typedef struct _AUDIO_STREAM_CONFIG_CAPS {
        GUID guid;
        ULONG MinimumChannels;
        ULONG MaximumChannels;
        ULONG ChannelsGranularity;
        ULONG MinimumBitsPerSample;
        ULONG MaximumBitsPerSample;
        ULONG BitsPerSampleGranularity;
        ULONG MinimumSampleFrequency;
        ULONG MaximumSampleFrequency;
        ULONG SampleFrequencyGranularity;
    } AUDIO_STREAM_CONFIG_CAPS;

メンバ

guid
オーディオ サンプルを示す MEDIATYPE_Audio に設定される。
MinimumChannels
このピンがサポートする最小チャンネル数。
MaximumChannels
このピンがサポートする最大チャンネル数 (たとえばステレオなら 2)。
ChannelsGranularity
チャンネル数の細分度。たとえば、2 ～ 4 チャンネルを 2 チャンネル間隔で指定する。
MinimumBitsPerSample
サンプルあたりの最小ビット数。
MaximumBitsPerSample
サンプルあたりの最大ビット数。
BitsPerSampleGranularity
ビット数の細分度。たとえば、8 ～ 32 ビットを 8 ビット間隔で指定する。
MinimumSampleFrequency
使用できる最小の周波数。
MaximumSampleFrequency
使用できる最大の周波数。
SampleFrequencyGranularity
周波数の細分度。たとえば、11025 ～ 44100 Hz を 11025 Hz 間隔で指定する。

注意

この構造体は、オーディオ キャプチャ フィルタまたは圧縮フィルタから返される。

参照

IAMStreamConfig::GetStreamCaps


COLORKEY 構造体

構造体

レンダラとほかのフィルタとの間でカラー キー情報をやり取りする。

構文

typedef struct tagCOLORKEY
    {
    DWORD           KeyType;
    DWORD           PaletteIndex;
    COLORREF        LowColorValue;
    COLORREF        HighColorValue;
    }    COLORKEY;

メンバ

KeyType
キーの種類。CK_NOCOLORKEY、CK_INDEX、または CK_RGB。CK_INDEX と CK_RGB は、論理的に組み合わせることができる。
PaletteIndex
パレット インデックス。
LowColorValue
RGB カラー値の下限。
HighColorValue
RGB カラー値の上限。

注意

ビデオ レンダラは、IOverlay インターフェイスを通じてアクセスされるデータ転送をサポートする。このインターフェイスは、通常、レンダラにデータの描画を要求せずに、データを置く位置をレンダラから知る必要があるハードウェア デコーダ フィルタで使用される。イメージを置く位置を知るための 1 つのメカニズムが、カラー キーを使用する方法である。この構造体は、カラー キーの要件をビデオ レンダラに説明するために、フィルタ (主にハードウェア デコーダ) から使用される。


DIBDATA 構造体

構造体

個々の GDI DIB に関する情報を保持する。

構文

typedef struct tagDIBDATA {
    LONG        PaletteVersion;
    DIBSECTION  DibSection;
    HBITMAP     hBitmap;
    HANDLE      hMapping;
    BYTE        *pBase;
} DIBDATA;

メンバ

PaletteVersion
現在使用中のパレット バージョン。
DibSection
割り当てられた DIB セクションの詳細。
hBitmap
描画するビットマップのハンドル。
hMapping
共有メモリ ブロックのハンドル。
pBase
ベース メモリ アドレスへのポインタ。

注意

サンプルを作成するとき、アロケータはサンプルに DIBSECTION を割り当てる。ウィンドウがサンプルを受け取ると、ウィンドウは、Microsoft Win32® BitBlt 関数を呼び出して、1 つのデバイス コンテキストから別のデバイス コンテキストに、サンプルを渡すことができる。これは、イメージ アロケータ、イメージ サンプル、および描画クラスが互いにビットマップ情報をやり取りするメカニズムである。


DVD_ATR 構造体

構造体

ディスクから得られる DVD の各種属性を記述する。この情報を解析するには、DVD ビデオの仕様を参照すること。

構文

typedef struct tagDVD_ATR
{
    ULONG    ulCAT;
    BYTE    pbATRI[768];
} DVD_ATR;

メンバ

ulCAT
1 ボリュームの場合は VMG_CAT、ビデオ タイトル セット (VTS) の場合は VTS_CAT。
pbATRI
ビデオ マネージャ情報 (VMGI) またはビデオ タイトル セット情報 (VTSI) のバイト 256 ～ 1023 から得られるメニューおよびタイトルの全ストリーム属性。

注意

この構造体は IDVDInfo インターフェイス (非推奨) と共に使用する。新しいアプリケーションでは、IDVDInfo2 インターフェイスを使用するべきである。


DVD_DECODER_CAPS 構造体

構造体

DVD デコーダの能力を示す。IDvdInfo2::GetDecoderCaps 内で使用される。

構文

typedef struct tagDVD_DECODER_CAPS
{
    DWORD   dwSize ;
    DWORD   dwAudioCaps ;
    double  dFwdMaxRateVideo ;
    double  dFwdMaxRateAudio ;
    double  dFwdMaxRateSP ;
    double  dBwdMaxRateVideo ;
    double  dBwdMaxRateAudio ;
    double  dBwdMaxRateSP ;
    DWORD   dwRes1 ;
    DWORD   dwRes2 ;
    DWORD   dwRes3 ;
    DWORD   dwRes4 ;
} DVD_DECODER_CAPS ;

メンバ

dwSize
構造体のサイズ。
dwAudioCaps
サポートされるオーディオ フォーマットを示す。以下の値のビットごとの OR。
  • DVD_AUDIO_CAPS_AC3 = 0x00000001
  • DVD_AUDIO_CAPS_MPEG2 = 0x00000002
  • DVD_AUDIO_CAPS_LPCM = 0x00000004
  • DVD_AUDIO_CAPS_DTS = 0x00000008
  • DVD_AUDIO_CAPS_SDDS = 0x00000010
dFwdMaxRateVideo
順方向の最大ビデオ データ レート。
dFwdMaxRateAudio
順方向の最大オーディオ データ レート。
dFwdMaxRateSP
順方向の最大サブピクチャ データ レート。
dBwdMaxRateVideo
逆方向の最大ビデオ データ レート (デコーダがスムーズ反転メカニズムをサポートしていない場合は 0)。
dBwdMaxRateAudio
逆方向の最大オーディオ データ レート (デコーダがスムーズ反転メカニズムをサポートしていない場合は 0)。
dBwdMaxRateSP
逆方向の最大サブピクチャ データ レート (デコーダがスムーズ反転メカニズムをサポートしていない場合は 0)。
dwRes1
将来的な使用のために予約されている。
dwRes2
将来的な使用のために予約されている。
dwRes3
将来的な使用のために予約されている。
dwRes4
将来的な使用のために予約されている。


DVD_HMSF_TIMECODE 構造体

構造体

時、分、秒、およびフレームを DVD タイムコードにカプセル化する。

構文

typedef struct tagDVD_HMSF_TIMECODE
{
    BYTE    bHours;
    BYTE    bMinutes;
    BYTE    bSeconds;
    BYTE    bFrames;
} DVD_HMSF_TIMECODE;

メンバ

bHours
時。
bMinutes
分。
bSeconds
秒。
bFrames
フレーム。

注意

DVD_HMSF_TIMECODE 構造体は、IDvdControl2 および IDvdInfo2 と共に使用する。古いインターフェイス IDvdControl および IDvdInfo と共に使用されていた DVD_TIMECODE 構造体より使いやすくなっている。DVD_HMSF_TIMECODE 構造体と ULONG とはどちら向きにもキャストできる。これは、後方互換性を保つために古い BCD タイム フォーマットを使用う必要がある場合に、DVD_HMSF_TIMECODE 構造体の代わりに使用できることを意味する。


DVD_KaraokeAttributes 構造体

構造体

カラオケ オーディオ ストリームに関する情報が格納される。特定のストリームの DVD_KaraokeAttributes 構造体は、IDvdInfo2::GetKaraokeAttributes メソッドで設定する。

構文

typedef struct tagDVD_KaraokeAttributes
{
    BYTE            bVersion;
    BOOL            fMasterOfCeremoniesInGuideVocal1;
    BOOL            fDuet;
    DVD_KARAOKE_ASSIGNMENT  ChannelAssignment;
    WORD            wChannelContents[8];
} DVD_KaraokeAttributes;

メンバ

bVersion
カラオケの現在のバージョンは 1.0 である。
fMasterOfCeremoniesInGuideVocal1
TRUE は "ガイド音声 1" チャンネルに "司会" のコンテンツが格納されていることを意味する。
fDuet
デュエット曲かどうかを示すブール値。
ChannelAssignment
全チャンネルのミキシング出力先となるスピーカの構成を示す。有効な DVD_KARAOKE_ASSIGNMENT 値のビットごとの OR。
wChannelContents
各チャンネルのコンテンツを識別する有効な DVD_KARAOKE_CONTENTS 値の配列。


DVD_MenuAttributes 構造体

構造体

DVD メニューに関する情報が格納される。特定のストリームの DVD_MenuAttributes 構造体は、IDvdInfo2::GetTitleAttributes メソッドで設定する。

構文

typedef struct tagDVD_MenuAttributes
{

    BOOL                        fCompatibleRegion[8];
    DVD_VideoAttributes         VideoAttributes;

    BOOL                        fAudioPresent;
    DVD_AudioAttributes         AudioAttributes;

    BOOL                        fSubpicturePresent;
    DVD_SubpictureAttributes    SubpictureAttributes;
} DVD_MenuAttributes;

メンバ

fCompatibleRegion
ディスクが作成された地域と互換性のある DVD リージョンを示す TRUE/FALSE 値の配列。配列の 8 つのインデックス (0 ～ 7) それぞれが、8 つの DVD の地域 (1 ～ 8) に対応する。この配列は、Video Manager Menu (ディスク全体のメイン メニュー) について照会した場合にのみ設定される。
VideoAttributes
メニューのビデオ属性が格納された DVD_VideoAttributes 構造体。この構造体は VMGM と VTSM の両方に適用される。
fAudioPresent
メニューにオーディオ ストリームがあるかどうかを示すブール型の変数。
AudioAttributes
メニューのオーディオ ストリームに関する情報が格納された DVD_AudioAttributes 構造体。この構造体は fAudioPresent が TRUE の場合にのみ設定される。
fSubpicturePresent
メニューにサブピクチャ ストリームがあるかどうかを示すブール型の変数。
SubpictureAttributes
メニューのサブピクチャ ストリームに関する情報が格納された DVD_SubpictureAttributes 構造体。この構造体は fSubpicturePresent が TRUE の場合にのみ設定される。


DVD_MUA_Coeff 構造体

構造体

マルチチャンネルのオーディオ ストリームに含まれる 1 つのチャンネルのミキシング係数を定義する。DVD_MultichannelAudioAttributes 構造体には、ストリームの各チャンネルに対応する DVD_MUA_Coeff 構造体 8 つから成る配列が格納される。

構文

typedef struct tagDVD_MUA_Coeff
{
    double   log2_alpha;
    double   log2_beta;
} DVD_MUA_Coeff;

メンバ

log2_alpha
このチャンネルのチャンネル 0 に対するミキシング係数を示す double 型の変数。
log2_beta
このチャンネルのチャンネル 1 に対するミキシング係数を示す double 型の変数。

注意

この構造体に格納される情報には、デジタル ビデオ ディスク (DVD) に明記されたミキシング係数が反映される。オーディオのデコードもアプリケーション側で行う場合を除き、この係数をアプリケーションから変更したり、逆に使用したりすることはできない。一般的な DVD フィルタ グラフでは、DVD ナビゲータ フィルタからデコーダにこの情報を送ることはない。

alpha 係数はオーディオ チャンネル 0 へのミキシングに使用され、beta 係数はオーディオ チャンネル 1 へのミキシングに使用される。通常、ミキシング係数は次の式で計算される。

Audio channel 0 = coeff[0].alpha * value[0] + coeff[1].alpha * value[1] + ...
Audio channel 1 = coeff[0].beta * value[0]  + coeff[1].beta * value[1] + ...

参照

DVD_AudioAttributes、DVD_MUA_MixingInfo


DVD_MUA_MixingInfo 構造体

構造体

特定タイトルの 1 つのオーディオ ストリームに含まれるチャンネルのサラウンド サウンドのミキシング情報を記述する。

構文

typedef struct tagDVD_MUA_MixingInfo
{
    BOOL    fMixTo0;
    BOOL    fMixTo1;
    BOOL    fMix0InPhase;
    BOOL    fMix1InPhase;
    DWORD   dwSpeakerPosition;
} DVD_MUA_MixingInfo;

メンバ

fMixTo0
ブール型の変数。TRUE はチャンネルがチャンネル 0 にミキシングされることを意味する。
fMixTo1
ブール型の変数。TRUE はチャンネルがチャンネル 1 にミキシングされることを意味する。
fMix0InPhase
ブール型の変数。TRUE はチャンネルがチャンネル 0 に同期してミキシングされることを意味する。
fMix1InPhase
ブール型の変数。TRUE はチャンネルがチャンネル 1 に同期してミキシングされることを意味する。
dwSpeakerPosition
このチャンネルの出力先スピーカを示す DWORD 型の変数。「注意」を参照すること。

注意

フィルタ グラフに手動で挿入されたカスタムなオーディオ デコーダと通信する手段を持っていない限り、この構造体に格納された情報をアプリケーションから使用してミキシングを変更することはできない。デフォルトのオーディオ デコーダは、ミキシング情報を使用して、デジタル ビデオ ディスク (DVD) の LPCM (Linear Pulse Code Modulated) オーディオを処理するが、アプリケーションにはデコーダにミキシング値の変更を指示する手段がない。これは、現在の DVD 再生アプリケーションでは、マルチチャンネル関連データの構造体にアクセスしないでよいことを意味する。

DVD_MultichannelAudioAttributes 構造体には、特定タイトルの 1 つのオーディオ ストリームに関する情報が格納される。以下の条件が満たされる場合は、この構造体に含まれる 8 つ以内の DVD_MUA_MixingInfo 構造体から成る配列に、値が設定される。

  • DVD_AudioAttributes.AppMode = DVD_AudioMode_Surround
  • DVD_AudioAttributes.AudioFormat = DVD_AudioFormat_LPCM
  • DVD_AudioAttributes.fHasMultichannelInfo = 1

dwSpeakerPosition として可能な値は、Ksmedia.h に次のように定義されている。

KSAUDIO_SPEAKER_LEFT | 0x1
KSAUDIO_SPEAKER_RIGHT | 0x2
KSAUDIO_SPEAKER_CENTER | 0x4
KSAUDIO_SPEAKER_SURROUND_LEFT | 0x8
KSAUDIO_SPEAKER_SURROUND_RIGHT | 0x10
KSAUDIO_SPEAKER_SUBWOOFER | 0x20
KSAUDIO_SPEAKER_LEFT_OF_CENTER | 0x40
KSAUDIO_SPEAKER_RIGHT_OF_CENTER | 0x80
KSAUDIO_SPEAKER_SURROUND_MONO | 0x100
KSAUDIO_SPEAKER_SIDE_LEFT | 0x200
KSAUDIO_SPEAKER_SIDE_RIGHT | 0x400
KSAUDIO_SPEAKER_TOP | 0x800

参照

DVD_AudioAttributes


DVD_MultichannelAudioAttributes 構造体

構造体

特定タイトルに含まれる 1 つのオーディオ ストリームのマルチチャンネル属性を記述する。

構文

typedef struct tagDVD_MultichannelAudioAttributes
{
    DVD_MUA_MixingInfo  Info[8];
    DVD_MUA_Coeff       Coeff[8];
} DVD_MultichannelAudioAttributes;

メンバ

Info
DVD_MUA_MixingInfo 構造体 8 つから成る配列。オーディオ ストリームの各チャンネルのミキシング情報が格納される。
Coeff
DVD_MUA_Coeff 構造体 8 つから成る配列。オーディオ ストリームの各チャンネルのミキシング係数が格納される。

注意

DVD_TitleAttributes 構造体には、DVD_MultichannelAudioAttributes 構造体 8 つまでから成る配列が格納される。IDvdInfo2::GetTitleAttributes メソッドの呼び出しにより DVD_TitleAttributes が設定されると、タイトル内の利用可能なオーディオ ストリームそれぞれにつき 1 つの DVD_MultichannelAudioAttributes 構造体が配列に設定される。


DVD_PLAYBACK_LOCATION 構造体

構造体

DVD の再生位置を示す。

構文

typedef struct tagDVD_PLAYBACK_LOCATION
{
ULONG   TitleNum;
    ULONG   ChapterNum;
    ULONG   TimeCode;
} DVD_PLAYBACK_LOCATION;

メンバ

TitleNum
ディスク全体のタイトル番号。タイトル トラック番号 (TTN) であり、ビデオ タイトル セットのタイトル トラック番号 (VTS_TTN) ではない。
ChapterNum
タイトルの部分を示す番号。単純でリニアなムービーでない場合は 0xffffffff。
TimeCode
タイムコード。現在の再生時間には DVD_TIMECODE を使用する。単純リニアなムービーでない場合は 0xffffffff。

注意

単純でリニアなムービーの場合、TitleNum と ChapterNum か、TitleNum と TimeCode さえあれば、再生位置を保存できる。


DVD_PLAYBACK_LOCATION2 構造体

構造体

DVD の再生位置を示す。

構文

typedef struct tagDVD_PLAYBACK_LOCATION2
{
    ULONG   TitleNum;
    ULONG   ChapterNum;
    DVD_HMSF_TIMECODE   TimeCode;
    ULONG   TimeCodeFlags;
} DVD_PLAYBACK_LOCATION2;

メンバ

TitleNum
ディスク全体のタイトル番号 (ビデオ タイトル セットのトラック番号ではない)。
ChapterNum
タイトルの部分を示す番号。単純でリニアなムービーでない場合は 0xffffffff。
TimeCode
タイムコード。現在の再生時間には DVD_HMSF_TIMECODE を使用する。単純でリニアなムービーでない場合は 0xffffffff。
TimeCodeFlags
DVD_TIMECODE_EVENT_FLAGS の組み合わせ。

注意

単純でリニアなムービーの場合、TitleNum と ChapterNum か、TitleNum と TimeCode さえあれば、再生位置を保存できる。


DVD_SubpictureAttributes 構造体

構造体

DVD サブピクチャに関する情報が格納される。特定のストリームの DVD_SubpictureAttributes 構造体は、IDvdInfo2::GetSubpictureAttributes メソッドで設定する。

構文

typedef struct tagDVD_SubpictureAttributes
{
    DVD_SUBPICTURE_TYPE     Type;
    DVD_SUBPICTURE_CODING   CodingMode;
    LCID                    Language;
    DVD_SUBPICTURE_LANG_EXT LanguageExtension;
} DVD_SubpictureAttributes;

メンバ

Type
サブピクチャに言語関連のコンテンツが格納されているかどうかを示す DVD_SUBPICTURE_TYPE 型の変数。
CodingMode
サブピクチャ グラフィックス ストリームのエンコード方法を示す DVD_SUBPICTURE_CODING 型の変数。
Language
Type が DVD_SPType_Language の場合にサブピクチャ言語を識別する LCID 型の変数。
LanguageExtension
Type が DVD_SPType_Language の場合にサブピクチャ言語エクステンションを識別する DVD_SUBPICTURE_LANG_EXT 型の変数。


DVD_TIMECODE 構造体

構造体

DVD タイムコード (時、分、秒、およびフレーム) が格納される。

構文

typedef struct tagDVD_TIMECODE")
{
   ULONG Hours1   :4;
   ULONG Hours10  :4;

   ULONG Minutes1 :4;
   ULONG Minutes10:4;

   ULONG Seconds1 :4;
   ULONG Seconds10:4;

   ULONG Frames1  :4;
   ULONG Frames10 :2;

   ULONG FrameRateCode:2;
} DVD_TIMECODE;

メンバ

Hours1
時 (1 の桁)。
Hours10
時 (10 の桁)。
Minutes1
分 (1 の桁)。
Minutes10
分 (10 の桁)。
Seconds1
秒 (1 の桁)。
Seconds10
秒 (10 の桁)。
Frames1
フレーム (1 の桁)。
Frames10
フレーム (10 の桁)。
FrameRateCode
DVD_FRAMERATE が示す、1 秒あたりのドロップされるフレーム数、およびドロップされないフレーム数。

注意

DVD タイムコードは、0xHhMmSsFf フォーマットの BCD (Binary Coded Decimal) コードである。

  • H = 時 (10 の桁)
  • h = 時 (1 の桁)
  • M = 分 (10 の桁)
  • m = 分 (1 の桁)
  • S = 秒 (10 の桁)
  • s = 秒 (1 の桁)
  • F = フレーム (10 の桁)
  • f = フレーム (1 の桁)

BCD を使用するには、まず BCD を作成する。

ULONG timeCode = 0;	// BCD を作成する。
// DVD_TIMECODE 構造体へのポインタを作成し、BCD のアドレスを設定する。
DVD_TIMECODE * dvdTimeCode = ( DVD_TIMECODE * ) &timeCode;

dvdTimeCode は DVD_TIMECODE 構造体として使用できる。

dvdTimeCode->Hours10 = 0;
dvdTimeCode->Hours1 = 2;

最後に、timeCode を IDvdControl::TimeSearch メソッドに渡す。

TimeSearch ( timeCode );


DVD_TitleAttributes 構造体

構造体

DVD タイトルに関する情報が格納される。特定のストリームの DVD_TitleAttributes 構造体は、IDvdInfo2::GetTitleAttributes メソッドで設定する。

構文

typedef struct tagDVD_TitleMainAttributes
{

    DVD_TITLE_APPMODE                   AppMode;
    DVD_VideoAttributes                 VideoAttributes;
    ULONG                               ulNumberOfAudioStreams;
    DVD_AudioAttributes                 AudioAttributes[8];
    DVD_MultichannelAudioAttributes     MultichannelAudioAttributes[8];
    ULONG                               ulNumberOfSubpictureStreams;
    DVD_SubpictureAttributes            SubpictureAttributes[32];
} DVD_TitleAttributes;

メンバ

AppMode
DVD ナビゲータが "カラオケ" モードかどうかを示す DVD_TITLE_APPMODE 型の変数。
VideoAttributes
現在のメニューまたはタイトルの "メイン" ビデオに関する情報が格納された DVD_VideoAttributes 構造体。
ulNumberOfAudioStreams
タイトルの利用可能なオーディオ ストリーム数を示す ULONG 型の変数。
AudioAttributes
現在のタイトルに含まれる個々のオーディオ ストリームに関する情報が格納された DVD_AudioAttributes 構造体の配列。
MultichannelAudioAttributes
マルチチャンネル フォーマットの利用可能なオーディオ ストリームに関する追加情報が格納された DVD_MultichannelAudioAttributes 構造体の配列。ストリームの DVD_AudioAttributes 構造体にマルチチャンネル ビットがセットされている場合は、対応するオーディオ ストリームの内容がこの構造体に設定される。
ulNumberOfSubpictureStreams
タイトル内の利用可能なサブピクチャ ストリーム数を示す ULONG 型の変数。
SubpictureAttributes
タイトル内の各サブピクチャ ストリームに関する情報が格納された DVD_SubpictureAttributes 構造体の配列。DVD_SubpictureAttributes 構造体には、タイトル内の利用可能なサブピクチャ ストリームそれぞれに関する情報が格納される。


DVD_VideoAttributes 構造体

構造体

現在のタイトルまたはメニューに対応するビデオ ストリームの属性を記述する。

構文

typedef struct tagDVD_VideoAttributes
{
    BOOL                     fPanscanPermitted;
    BOOL                     fLetterboxPermitted;
    ULONG                    ulAspectX;
    ULONG                    ulAspectY;
    ULONG                    ulFrameRate;
    ULONG                    ulFrameHeight;
    DVD_VIDEO_COMPRESSION    Compression;
    BOOL                     fLine21Field1InGOP;
    BOOL                     fLine21Field2InGOP;
    ULONG                    ulSourceResolutionX;
    ULONG                    ulSourceResolutionY;
    BOOL                     fIsSourceLetterboxed;
    BOOL                     fIsFilmMode;
} DVD_VideoAttributes;

メンバ

fPanscanPermitted
TRUE は、表示アスペクト比が 4 x 3 のときに、画像をパン-スキャン表示できることを意味する。
fLetterboxPermitted
TRUE は、表示アスペクト比が 4 x 3 のときに、画像をレターボックス表示できることを意味する。
ulAspectX
ビデオ ストリームの x アスペクト (4 または 16)。
ulAspectY
ビデオ ストリームの y アスペクト (3 または 9)。
ulFrameRate
フレーム レート (50 または 60)。単位は Hz。
ulFrameHeight
フレームの高さ (ライン数)。フレーム レートが 60 Hz の場合は 525、50 Hz の場合は 625。
Compression
ディスク上で使用される MPEG 圧縮の種類を示す DVD_VIDEO_COMPRESSION 型の変数。
fLine21Field1InGOP
TRUE は Line 21 のフィールド 1 にユーザー データがあることを意味する。
fLine21Field2InGOP
TRUE は Line 21 のフィールド 2 にユーザー データがあることを意味する。
ulSourceResolutionX
x 軸のソース解像度 (352、704、または 720)。
ulSourceResolutionY
y 軸のソース解像度 (240、480、288、または 576)。
fIsSourceLetterboxed
TRUE はソース ビデオがレターボックス フォーマットであることを意味する。サブピクチャとメニュー ボタンは、アクティブなビデオ領域内にしか表示できない。
fIsFilmMode
625/50 Hz のシステムで、TRUE が "フィルム モード" を意味し、FALSE が "カメラ モード" を意味する。

注意

この構造体の値は、アプリケーションが IDvdInfo2::GetCurrentVideoAttributes メソッドを呼び出すと設定される。


FILTER_INFO 構造体

構造体

フィルタに関する情報が格納される。

構文

typedef struct _FilterInfo {
    WCHAR        achName[MAX_FILTER_NAME];
    IFilterGraph * pGraph;
} FILTER_INFO;

メンバ

achName
フィルタ名が格納された、NULL で終了する文字列。
pGraph
フィルタがフィルタ グラフに属している場合は、フィルタ グラフの IFilterGraph インターフェイスへのポインタが入る。フィルタがフィルタ グラフに属していない場合は、NULL。

注意

pGraph メンバが NULL でない場合、使い終わったら、アプリケーション側で IFilterGraph インターフェイスを解放しなければならない。


MPEG1VIDEOINFO 構造体

構造体

MPEG-1 ビデオ ストリームを記述する。

構文

typedef struct tagMPEG1VIDEOINFO {
    VIDEOINFOHEADER hdr;
    DWORD           dwStartTimeCode;
    DWORD           cbSequenceHeader;
    BYTE            bSequenceHeader[1];
} MPEG1VIDEOINFO;

メンバ

hdr
VIDEOINFOHEADER 構造体。
dwStartTimeCode
データ先頭にある 25 ビットの "画像グループ (GOP)" タイムコード。
cbSequenceHeader
bSequenceHeader の長さ (バイト単位)。
bSequenceHeader
量子化マトリックス(ある場合) を含むシーケンス ヘッダー。


MPEG2VIDEOINFO 構造体

構造体

MPEG-2 ビデオ ストリームを記述する。

構文

typedef struct tagMPEG2VIDEOINFO {
    VIDEOINFOHEADER2    hdr;
    DWORD               dwStartTimeCode;
    DWORD               cbSequenceHeader;
    DWORD               dwProfile;
    DWORD               dwLevel;
    DWORD               dwFlags;
    DWORD               dwSequenceHeader[1];
} MPEG2VIDEOINFO;

メンバ

hdr
VIDEOINFOHEADER2 構造体。
dwStartTimeCode
データ先頭にある 25 ビットの "画像グループ(GOP)" タイムコード (DVD では使用しない)。
cbSequenceHeader
dwSequenceHeader の長さ (バイト単位)。DVD では 0。
dwProfile
MPEG2Profile 列挙型のメンバ。
dwLevel
MPEG2Level 列挙型のメンバ。
dwFlags
各種設定を示すフラグ。以下の値を 1 つ以上組み合わせて設定する。
AMMPEG2_DoPanScan | オンの場合、MPEG-2 ビデオ デコーダは、画像表示エクステンションのパン-スキャン ベクトルに基づいて出力イメージをくり抜き、それに合わせて画像アスペクト比を変更しなければならない。
AMMPEG2_DVDLine21Field1 | オンの場合、MPEG-2 ビデオ デコーダは、フィールド 1 の Group Of Pictures (GOP) 層にある DVD スタイルのクローズド キャプション データのために出力ピンを生成できなければならない。
AMMPEG2_DVDLine21Field2 | オンの場合、MPEG-2 ビデオ デコーダは、フィールド 2 の GOP 層にある DVD スタイルのクローズド キャプション データのために出力ピンを生成できなければならない。
AMMPEG2_SourceIsLetterboxed | オンの場合、ビデオの上下に黒い帯がエンコードされていることを示す。
AMMPEG2_FilmCameraMode | オンの場合は、625/50 (ライン/フィールド) のコンテンツに "フィルム モード" が使用されていることを示す。オフの場合は、"カメラ モード" が使用されていることを示す。
未定義のフラグは 0 に設定すること。0 以外の場合、接続は拒否される。
dwSequenceHeader
量子化マトリックス (ある場合) を含むシーケンス ヘッダー。


PID_MAP 構造体

構造体

MPEG-2 トランスポート ストリーム パケット ID の内容を示す情報が入る。IEnumPIDMap::Next メソッドと共に用いられる。

構文

typedef struct {
    ULONG                   ulPID;
    MEDIA_SAMPLE_CONTENT    MediaSampleContent ;
} PID_MAP ;

メンバ

ulPID
パケット ID を指定。
MediaSampleContent
パケット ペイロードの内容を指定。


PIN_INFO 構造体

構造体

ピンに関する情報が格納される。IPin::QueryPinInfo メソッドと共に使われる。

構文

typedef struct  _PinInfo
{
    IBaseFilter *pFilter;
    PIN_DIRECTION dir;
    WCHAR achName[128];
} PIN_INFO;

メンバ

pFilter
所有者フィルタの IBaseFilter インターフェイスへのポインタ。
dir
ピンの方向 (入力/出力)。
achName
ピンの名前。

注意

出力ピンの名前が ~ (チルダ) から始まる場合、フィルタ グラフ マネージャでは、グラフの構築時にその出力ピンは無視される。IGraphBuilder::Connect、IGraphBuilder::Render、または IGraphBuilder::RenderFile の呼び出しで中間フィルタにそのピンが見つかった場合、フィルタ グラフ マネージャはピンをレンダリングしない (ただし Connect メソッドか Render メソッドに明示的にピンを渡した場合は除く)。

デフォルトではレンダリングされないセカンダリ ストリームを渡すピンや、正しくレンダリングするために特殊なコードが必要になるピンには、~ (チルダ) を使用する。たとえば、DVD フィルタでは、サブピクチャまたはクローズド キャプション データを渡すピンに使用する。また、ビデオ キャプチャ フィルタでは、キャプチャ ピン (ただしプレビュー ピン以外) に使用する。


Quality 構造体

構造体

レンダラのパフォーマンスを最適化するため、レンダラ内の状態 (データ過剰またはデータ不足) を示し、フレームを加減するパーセンテージを指定することによって、品質メッセージを記述する。

構文

typedef struct{
    QualityMessageType  Type;
    long                Proportion;
    REFERENCE_TIME      Late;
    REFERENCE_TIME      TimeStamp;
} Quality;

メンバ

Type
Famine または Flood。ダウンストリーム フィルタへのデータが不足しているか、または過剰であることを示す。
Proportion
Microsoft® DirectShow® がメディア サンプルの送信を継続すべきレートを指定する値。基底値 1000 は、レートを変更しないことを示す。1000 からの増減の割合が、加減するフレーム数の割合を示す。たとえばこの値が 800 の場合、DirectShow は、レンダラの速度に合わせるため、受け取ったフレームの 20 % をドロップする。
Late
ダウンストリームでデータ不足が起きている場合、ストリームが遅れている時間の長さを示す。
TimeStamp
DirectShow がこの構造体を作成した時間を指定する値。通常、この値はビデオ サンプル上の開始タイムである。


REGFILTER 構造体

構造体

名前とクラス識別子 (CLSID) によってフィルタを識別する。

構文

typedef struct {
    CLSID Clsid;
    LPWSTR Name;
} REGFILTER;

メンバ

Clsid
フィルタの CLSID。
Name
フィルタの名前。

注意

廃止された IEnumRegFilters インターフェイスは、この構造体を使用する。ただし、新しいアプリケーションでは、モニカを列挙する IFilterMapper2 を使用すること。


REGFILTER2 構造体

構造体

フィルタを登録するための情報が格納される。

構文

typedef struct
{
    DWORD dwVersion;
    DWORD dwMerit;
    union
    {
        struct
        {
            ULONG cPins;
            const REGFILTERPINS *rgPins;
        };
        struct
        {
            ULONG cPins2;
            const REGFILTERPINS2 *rgPins2;
        };
    };
} REGFILTER2;

メンバ

dwVersion
フィルタ登録のフォーマット。値 1 は、共用体に名前のない 1 番目の構造体が格納されていることを示す。値 2 は、共用体に名前のない 2 番目の構造体が格納されていることを示す。
dwMerit
フィルタのメリット。メリット値が高いフィルタほど先に列挙される。
cPins
ピンの数 (dwVersion が 1 の場合のみに定義される)。
rgPins
REGFILTERPINS 構造体の配列へのポインタ (dwVersion が 1 の場合のみに定義される)。配列のサイズは cPins。
cPins2
ピンの数 (dwVersion が 2 の場合のみに定義される)。
rgPins2
REGFILTERPINS2 構造体の配列へのポインタ (dwVersion が 2 の場合のみに定義される)。配列のサイズは cPins2。

注意

この構造体は、IFilterMapper2::RegisterFilter メソッドに渡される。

ピンのメディアまたはカテゴリを登録するには、dwVersion に 2 を設定し、REGFILTERPINS2 構造体を使用する。


REGFILTERPINS 構造体

構造体

フィルタを登録するためのピン情報が格納される。

構文

typedef struct
{
    LPWSTR            strName;
    BOOL              bRendered;
    BOOL              bOutput;
    BOOL              bZero;
    BOOL              bMany;
    const CLSID       *clsConnectsToFilter;
    const WCHAR       *strConnectsToPin;
    UINT              nMediaTypes;
    const REGPINTYPES *lpMediaType;
} REGFILTERPINS;

typedef REGFILTERPINS AMOVIESETUP_PIN,
    * PAMOVIESETUP_PIN,
    * FAR LPAMOVIESETUP_PIN;

メンバ

strName
ピンの名前。(廃止)
bRendered
TRUE の場合、フィルタはこのピンからの入力をレンダリングする (入力ピンのみに適用される)。出力ピンの場合は常に FALSE。
bOutput
TRUE の場合、このピンは出力ピンとなる。それ以外の場合は、入力ピンとなる。
bZero
TRUE の場合、フィルタがこのピンのインスタンスを 1 つも持たないことがある。
bMany
TRUE の場合、フィルタがこの種類のピンのインスタンスを複数作成できる。
clsConnectsToFilter
このピンが接続するフィルタのクラス識別子 (CLSID)。(廃止)
strConnectsToPin
このピンが接続するピンの名前。(廃止)
nMediaTypes
このピンがサポートするメディア サンプル数。
lpMediaType
REGPINTYPES 構造体の配列へのポインタ。配列のサイズは nMediaTypes。

注意

この構造体は、フィルタを登録するために IFilterMapper2 インターフェイスで使用される。この構造体を使用する場合には、REGFILTER2 構造体の dwVersion メンバに 1 を設定する。ピンのメディアまたはカテゴリを登録するには、REGFILTERPINS2 構造体を使用する。この場合、REGFILTER2 構造体の dwVersion メンバに 2 を設定する。

クラス ファクトリ テンプレート (CFactoryTemplate) では、同等の AMOVIESETUP_PIN 型が使用される。

strName、clsConnectsToFilter、および strConnectsToPin メンバは廃止された。これらメンバの値はレジストリに追加されない。

詳細については、「DirectShow オブジェクトの登録方法」を参照すること。


REGFILTERPINS2 構造体

構造体

IFilterMapper2 インターフェイスを通じてフィルタを登録するための情報が格納される。

構文

typedef struct
{
    DWORD               dwFlags;
    UINT                cInstances;
    UINT                nMediaTypes;
    const REGPINTYPES   *lpMediaType;
    UINT                nMediums;
    const REGPINMEDIUM  *lpMedium;
    const CLSID         *clsPinCategory;
} REGFILTERPINS2;

メンバ

dwFlags
REG_PINFLAG フラグのビットごとの組み合わせ (0 個でもよい)。
cInstances
ピンのインスタンス数。
nMediaTypes
このピンがサポートするメディア サンプル数。
lpMediaType
REGPINTYPES 構造体の配列へのポインタ。配列のサイズは nMediaTypes。
nMediums
メディア数。0 でもよい。
lpMedium
REGPINMEDIUM 構造体の配列へのポインタ。配列のサイズは nMediums。
clsPinCategory
ピン プロパティ セットから得られるピン カテゴリ (省略可能)。

注意

この構造体を使用する場合は、REGFILTER2 構造体の dwVersion メンバに 2 を設定する。


REGPINMEDIUM 構造体

構造体

IFilterMapper2 インターフェイスを通じて登録するためにピン メディアを記述する。

構文

typedef struct
{
    CLSID clsMedium;
    DWORD dw1;
    DWORD dw2;
} REGPINMEDIUM;

メンバ

clsMedium
メディアを指定する GUID。
dw1
このメディアのインスタンスを指定する DWORD 型の変数。これは 2 つの同じデバイスがホスト システムに存在するときに必要である。
dw2
未使用。

注意

medium は 1 つのハードウェア デバイス内にあるいは 2 つのデバイス間に存在するコミュニケーションのハードウェア パスを指定する。開発するフィルタが、カーネル ストリーミング ピン上で構築され、同様のフィルタに接続する必要がある場合には、メディアを登録する。

この構造体は、カーネル ストリーミング ドライバが用いる KSPIN_MEDIUM 構造体と同等である。詳細については、Microsoft® Windows® Driver Development Kit (DDK) を参照すること。


REGPINTYPES 構造体

構造体

フィルタを登録するためのメディア タイプ情報が格納される。

構文

typedef struct
{
    const CLSID *clsMajorType;
    const CLSID *clsMinorType;
} REGPINTYPES;

typedef REGPINTYPES AMOVIESETUP_MEDIATYPE,
    * PAMOVIESETUP_MEDIATYPE,
    * FAR LPAMOVIESETUP_MEDIATYPE;

メンバ

clsMajorType
メディア タイプのメジャー タイプ GUID。
clsMinorType
メディア タイプのサブタイプ GUID。MEDIASUBTYPE_NULL でもよい。

注意

この構造体は、ピンがサポートするメディア タイプを識別するために、IFilterMapper2 インターフェイスで使用される。クラス ファクトリ テンプレート (CFactoryTemplate) では、同等の AMOVIESETUP_MEDIATYPE 型が使用される。

同じメジャー タイプに含まれるサブタイプの範囲を登録するには、値 MEDIASUBTYPE_NULL を使用する。

詳細については、「DirectShow オブジェクトの登録方法」を参照すること。


STREAM_ID_MAP 構造体

構造体

MPEG-2 番組ストリーム内の基本ストリームを記述する。IEnumStreamIdMap インターフェイス メソッドと共に用いられる。

構文

typedef struct {
    ULONG   stream_id;
    DWORD   dwMediaSampleContent;
    ULONG   ulSubstreamFilterValue;
    int     iDataOffset;
} STREAM_ID_MAP ;

メンバ

stream_id
PES ストリームの ID を指定する。
dwMediaSampleContent
ストリームのメディアの内容を指定する。以下の変数のいずれか (axextend.idl 内で定義される) :
    MPEG2_PROGRAM_STREAM_MAP                 0x00000000
    MPEG2_PROGRAM_ELEMENTARY_STREAM          0x00000001
    MPEG2_PROGRAM_DIRECTORY_PES_PACKET       0x00000002
    MPEG2_PROGRAM_PACK_HEADER                0x00000003
    MPEG2_PROGRAM_PES_STREAM                 0x00000004
    MPEG2_PROGRAM_SYSTEM_HEADER              0x00000005
ulSubstreamFilterValue
基本ストリーム内のサブストリームを指定する。サブストリーム フィルタリングが要求されていないなら、SUBSTREAM_FILTER_VAL_NONE (0x10000000) を使用すること。
iDataOffset
サブストリームに対するオフセットをバイト単位で指定する。フィルタリングが要求されていないなら 0 を指定すること。


TIMECODE 構造体

構造体

基本的なタイムコード フレーム カウント情報が格納される。

構文

typedef struct tagTIMECODE {
    WORD  wFrameRate;
    WORD  wFrameFract;
    DWORD  dwFrames;
}TIMECODE;

メンバ

wFrameRate
1 秒あたりのフレーム数。以下の値のいずれかを指定する。
ED_FORMAT_SMPTE_30 | 30 フレーム/秒。
ED_FORMAT_SMPTE_30DROP | 30 フレーム/秒のドロップ フレーム (実際のレートは 29.97 fps)。
ED_FORMAT_SMPTE_25 | 25 フレーム/秒。
ED_FORMAT_SMPTE_24 | 24 フレーム/秒。
wFrameFract
フレームの分数。フルスケールはは 0x1000。
dwFrames
バイナリのフレーム カウントで表現されたタイムコード値。

注意

フレームの分数を使用すると、タイムコードが実際に外部デバイスから読みこまれた時間を、フレーム内における時間的なオフセットで示すことができる。たとえば、wFrameFract=0x7ff は、デバイスから読みこまれたタイムコード値が、第 1 ビデオ フィールドの最後にあったことを意味する。

注 : コンピュータとのタイムコードのやり取りは、通常、ASCII 値で行われるため、サンプル フィルタには、バイナリのフレーム カウントと ASCII 値を変換するためのヘルパー メソッドが用意されている。


TIMECODE_SAMPLE 構造体

構造体

タイムコードの完全な情報が格納される。

構文

typedef struct tagTIMECODE_SAMPLE {
    LONGLONG  qwTick;
    TIMECODE  timecode;
    DWORD  dwUser;
    DWORD  dwFlags;
} TIMECODE_SAMPLE;

メンバ

qwTick
基準タイム (100 ナノ秒単位)。
timecode
TIMECODE 構造体。
dwUser
パックされた SMPTE ユーザービット。
dwFlags
タイムコードのフラグ マスク。以下の値を 1 つ以上組み合わせて指定する。
AM_TIMECODE_FLAG_FCM | フレーム コードのモード (0 は非ドロップ、1 はドロップ)。
AM_TIMECODE_FLAG_CF | カラー フレーム フラグ。
AM_TIMECODE_FLAG_FIELD | フィールド フラグ。
AM_TIMECODE_FLAG_DF | ドロップ フレーム フラグ (外部メディア上の実際のタイムコードにあるフラグから得られる)。
AM_TIMECODE_COLORFRAME | カラー フレームのシーケンスを指定する。
AM_TIMECODE_COLORSEQUENCE | シーケンス全体の時間幅 (フレーム数)。
AM_TIMECODE_FILMSEQUENCE_TYPE | FILM_SEQUENCE_XXX 定義の 1 つ。

注意

dwFlags の上位 16 ビットは、将来的な使用のために予約されている。0 に設定する。


TRUECOLORINFO 構造体

構造体

ビデオ イメージのカラー パレットおよびビットマスク情報が格納される。

構文

typedef struct tag_TRUECOLORINFO {
    DWORD dwBitMasks[iMASK_COLORS];
    RGBQUAD bmiColors[iPALETTE_COLORS];
} TRUECOLORINFO;

メンバ

dwBitMasks[iMASK_COLORS]
色のマスクの配列 (色の要素ごとに 1 つづつ)。
bmiColors[iPALETTE_COLORS]
パレット色の配列。

注意

この構造体は、一部の RGB フォーマットには使用されない。各種状況ごとの有効なフィールドについては、Platform SDK のドキュメントの BITMAPINFO を参照すること。

参照

VIDEOINFO


VIDEO_STREAM_CONFIG_CAPS 構造体

構造体

可能な接続に関する情報が格納される。

構文

typedef struct  _VIDEO_STREAM_CONFIG_CAPS
    {
    GUID guid;
    ULONG VideoStandard;
    SIZE InputSize;
    SIZE MinCroppingSize;
    SIZE MaxCroppingSize;
    int CropGranularityX;
    int CropGranularityY;
    int CropAlignX;
    int CropAlignY;
    SIZE MinOutputSize;
    SIZE MaxOutputSize;
    int OutputGranularityX;
    int OutputGranularityY;
    int StretchTapsX;
    int StretchTapsY;
    int ShrinkTapsX;
    int ShrinkTapsY;
    LONGLONG MinFrameInterval;
    LONGLONG MaxFrameInterval;
    LONG MinBitsPerSecond;
    LONG MaxBitsPerSecond;
    }  VIDEO_STREAM_CONFIG_CAPS;

メンバ

guid
ビデオ サンプルを示す MEDIATYPE_Video に設定される。
VideoStandard
サポートされるアナログ ビデオ規格。AnalogVideoStandard 列挙型が設定される (サポートされない場合は 0)。
InputSize
受け取る信号のサイズ。Win32 SIZE 構造体を通じて、イメージ矩形の幅および高さ (ピクセル単位) で表現される。コンプレッサ フィルタの場合、このサイズは入力ピンの AM_MEDIA_TYPE 構造体内にある Win32 BITMAPINFOHEADER 構造体の幅および高さのメンバから取得される。キャプチャ フィルタの場合、このサイズはフィルタが全ピクセルが一意なままデジタル化することができる最大の信号サイズである。
MinCroppingSize
VIDEOINFOHEADER 構造体の rcSource メンバに指定された、使用できる最小のクロッピング矩形。
MaxCroppingSize
VIDEOINFOHEADER 構造体の rcSource メンバに指定された、使用できる最大のクロッピング矩形。
CropGranularityX
クロッピング サイズの細分度。たとえば、有効な幅を 4 の整数倍に限定する。
CropGranularityY
クロッピング サイズの細分度。たとえば、有効な高さを 4 の整数倍に限定する。
CropAlignX
InputSize 内におけるクロッピング矩形のアラインメント。たとえば、矩形が 4 の倍数の境界から始まるように指定する。
CropAlignY
InputSize 内におけるクロッピング矩形のアラインメント。たとえば、矩形が 4 の倍数の境界から始まるように指定する。
MinOutputSize
このピンが生成できる最小のビットマップ。
MaxOutputSize
このピンが生成できる最大のビットマップ。
OutputGranularityX
出力ビットマップの幅の細分度。
OutputGranularityY
出力ビットマップの高さの細分度。
StretchTapsX
フィルタがイメージの幅を引き伸ばす能力を示す値。値 0 は引き伸ばす能力がないことを意味し、値 1 はピクセル ダブリングを使用することを意味する。また、値 2 は補間 (タップ数 2) を使用し、値 3 以上はさらに精度の高い補間を実装することを意味する。
StretchTapsY
フィルタがイメージの高さを引き伸ばす能力を示す値。値 0 は引き伸ばす能力がないことを意味し、値 1 はピクセル ダブリングを使用することを意味する。また、値 2 は補間 (タップ数 2) を使用し、値 3 以上はさらに精度の高い補間を実装することを意味する。
ShrinkTapsX
フィルタがイメージの幅を縮める能力を示す値。値 0 は縮める能力がないことを意味し、値 1 は一部のピクセル行を単純に除去することを意味する。また、値 2 は補間 (タップ数 2) を使用し、値 3 以上はさらに精度の高い補間を実装することを意味する。
ShrinkTapsY
フィルタがイメージの高さを縮める能力を示す値。値 0 は縮める能力がないことを意味し、値 1 は一部のピクセル行を単純に除去することを意味する。また、値 2 は補間 (タップ数 2) を使用し、値 3 以上はさらに精度の高い補間を実装することを意味する。
MinFrameInterval
使用できる最小のフレーム レート。キャプチャ フィルタにのみ適用される。
MaxFrameInterval
使用できる最大のフレーム レート。キャプチャ フィルタにのみ適用される。
MinBitsPerSecond
このピンが生成できる最小のデータ レート。
MaxBitsPerSecond
このピンが生成できる最大のデータ レート。

注意

たとえば、構造体の一部のメンバとして以下の値を想定する。

  • MinCroppingSize = (160, 120)
  • MaxCroppingSize = (320, 240)
  • CropGranularityX = 4
  • CropGranularityY = 8

これらの値は、有効なクロッピング サイズが、MinCroppingSize から始まり、x 方向に CropGranularityX 間隔、y 方向に CropGranularityY 間隔で増加することを示す。この場合、x は 160 ～ 320 ピクセルの範囲で 4 間隔の値を取り、y は 120 ～ 240 ピクセルの範囲で 8 間隔の値を取る。

たとえば次のようなサイズが有効である。

  • 160 × 120、164 × 120、168 × 120、172 × 120 など
  • 160 × 128、164 × 128、168 × 128、172 × 128 など
  • 160 × 136、164 × 136、168 × 136、172 × 136 など

CropAlignX および CropAlignY は、入力サイズ矩形内におけるクロッピング矩形の位置を示す。クロッピング矩形のサイズを 160 × 120 とし、これらの値を次のように想定する。

  • CropAlignX = 2
  • CropAlignY = 4

この場合、VIDEOINFOHEADER 構造体の rcSource メンバとしては、たとえば次のような値が有効である。

  • (0, 0, 160, 120)
  • (2, 0, 162, 120)
  • (2, 4, 162, 124)
  • (2, 8, 162, 128)

同じアラインメントでクロッピング矩形を 320 × 240 とした場合、有効な矩形は (2, 4, 322, 244) などとなる。

この項で説明する構造体メンバは、セットで機能し、出力ピンのメディア タイプを記述する VIDEOINFOHEADER 構造体として有効な rcSource の値を指定する。構造体の残りのメンバのうち、MinOutputSize、MaxOutputSize、OutputGranularityX、および OutputGranularityY は、出力ピンのメディア タイプ VIDEOINFOHEADER 構造体に格納された BITMAPINFOHEADER 構造体の biWidth メンバおよび biHeight メンバを記述する。


VIDEOINFO 構造体

構造体

ビデオ イメージのビットマップと色情報を記述する。

構文

typedef struct tagVIDEOINFO {
    RECT            rcSource,
    RECT            rcTarget,
    DWORD           dwBitRate,
    DWORD           dwBitErrorRate,
    REFERENCE_TIME  AvgTimePerFrame;
    BITMAPINFOHEADER    bmiHeader;
union {
        RGBQUAD     bmiColors[iPALETTE_COLORS];
        DWORD       dwBitMasks[iMASK_COLORS];
        TRUECOLORINFO   TrueColorInfo;
    };
} VIDEOINFO;

メンバ

rcSource
入力ビデオの使用部分。
rcTarget
ビデオの表示先。
dwBitRate
ビット データ レート (概数)。
dwBitErrorRate
このストリームのビット エラー レート。
AvgTimePerFrame
フレームあたりの平均時間 (100 ナノ秒単位)。
bmiHeader
デバイズに依存しないビットマップの色およびディメンジョン情報が格納された Win32 BITMAPINFOHEADER 構造体。
bmiColors
赤、緑、および青の輝度でビデオのカラー パレットを指定する Win32 RGBQUAD 構造体の配列。
dwBitMasks
トゥルーカラーのビットマスクを指定する DWORD 値の配列。
TrueColorInfo
カラー パレットとカラー ビットマスクの両方が格納された TRUECOLORINFO 構造体。

注意

標準の RGB フォーマット以外を格納する可能性がある場合は、この構造体を使用しないこと。標準の RGB 以外を格納すると、bmiHeader 構造体の変数サイズが原因で問題が起きる可能性が高い。代わりに VIDEOINFOHEADER 構造体を使用すること。何らかの理由で VIDEOINFO 構造体を使用する必要がある場合には、TrueColorInfo、dwBitMasks、および bmiColors に直接アクセスせずに、TRUECOLORINFO マクロ、COLORS マクロ、および BITMASKS マクロを使用して色情報へのポインタを返すこと。これらのメンバのいずれかが、BITMAPINFOHEADER 構造体に対応して有効になる。

最初のデータ メンバ 5 つは、VIDEOINFOHEADER 構造体と同等である。VIDEOINFO 構造体へのポインタの処理に必要な逆参照の量を減らすために、これらのメンバが完全に展開されている。

rcSource と rcTarget メンバの使い方の詳細については、「ビデオ レンダラにおける転送元矩形と転送先矩形」を参照すること。


VIDEOINFOHEADER 構造体

構造体

ビデオ イメージのビットマップと色情報を記述する。

構文

typedef struct tagVIDEOINFOHEADER {
    RECT                rcSource,
    RECT                rcTarget;
    DWORD               dwBitRate;
    DWORD               dwBitErrorRate;
    REFERENCE_TIME      AvgTimePerFrame;
    BITMAPINFOHEADER    bmiHeader;
} VIDEOINFOHEADER;

メンバ

rcSource
転送元ビデオ ウィンドウを指定する RECT 構造体。ソース ビデオ ストリームの一部を選択するため、この構造体をクリッピング矩形としてもよい。
rcTarget
転送先ビデオ ウィンドウを指定する RECT 構造体。
dwBitRate
ビデオ ストリームのおおよそのデータ レート (ビット/秒) 。
dwBitErrorRate
ビデオ ストリームのデータ エラー レート (ビット エラー/秒) 。
AvgTimePerFrame
ビデオ フレームの平均表示時間 (100 ナノ秒単位) 。
bmiHeader
ビデオ イメージの色およびディメンジョン情報が格納された Win32 BITMAPINFOHEADER 構造体。

注意

rcSource と rcTarget メンバの使用についての情報は、「ビデオ レンダラにおける転送元矩形と転送先矩形」を参照すること。


VIDEOINFOHEADER2 構造体

構造体

インターレース、コピー保護、およびピクセルのアスペクト比の情報を含む、ビデオ イメージのビットマップおよび色情報を記述する。

構文

typedef struct tagVIDEOINFOHEADER2 {
    RECT                rcSource;
    RECT                rcTarget;
    DWORD               dwBitRate;
    DWORD               dwBitErrorRate;
    REFERENCE_TIME      AvgTimePerFrame;
    DWORD               dwInterlaceFlags;
    DWORD               dwCopyProtectFlags;
    DWORD               dwPictAspectRatioX;
    DWORD               dwPictAspectRatioY;
    DWORD               dwReserved1;
    DWORD               dwReserved2;
    BITMAPINFOHEADER    bmiHeader;
} VIDEOINFOHEADER2;

メンバ

rcSource
転送先バッファに送るソース ストリームの使用部分を指定する RECT 構造体。レンダラでは、このフィールドを使用して、デコーダに伸縮またはクリッピングを指示できる。詳細については、「ビデオ レンダラにおける転送元矩形と転送先矩形」を参照すること。
rcTarget
転送先バッファのどの部分を使用するかを指定する RECT 構造体。詳細については、「ビデオ レンダラにおける転送元矩形と転送先矩形」を参照すること。
dwBitRate
ビデオ ストリームのおおよそのデータ レート (ビット/秒)。
dwBitErrorRate
ビデオ ストリームのデータ エラー レート (ビット/秒)。
AvgTimePerFrame
ビデオ フレームの平均表示時間 (100 ナノ秒単位)。
dwInterlaceFlags
以下のフラグのビットごとの組み合わせ (0 個でもよい)。このフラグの詳細については、このページの最後の表を参照すること。
AMINTERLACE_IsInterlaced | ストリームがインターレース方式である。このフラグがオフの場合、ほかのビットは意味がない。
AMINTERLACE_1FieldPerSample | メディア サンプルあたり 1 フィールド。このフラグがオフの場合は、メディア サンプルごとに 2 フィールドとなる。
AMINTERLACE_Field1First | フィールド 1 が先。このフラグがオフの場合は、フィールド 2 が先になる (先頭フィールドは、PAL ではフィールド 1、NTSC ではフィールド 2)。
AMINTERLACE_FieldPatField1Only | ストリームにフィールド 2 はない。
AMINTERLACE_FieldPatField2Only | ストリームにフィールド 1 はない。
AMINTERLACE_FieldPatBothRegular | フィールド 1 ごとにフィールド 2 が必ず 1 つある。
AMINTERLACE_FieldPatBothIrregular | フィールド 1 とフィールド 2 が不規則に配置されている。
AMINTERLACE_DisplayModeBobOnly | ディスプレイ モードは Bob のみ。
AMINTERLACE_DisplayModeWeaveOnly | ディスプレイ モードはウィーブのみ。
AMINTERLACE_DisplayModeBobOrWeave | Bob とウィーブの両方のモードがある。
未定義のフラグは 0 に設定すること。0 以外の場合、接続は拒否される。
dwCopyProtectFlags
ストリームの重複を制限しなければならないことを示す AMCOPYPROTECT_RestrictDuplication 値がセットされたフラグ。未定義の場合は、0 に指定すること。0 以外の場合、接続は拒否される。
dwPictAspectRatioX
画像のアスペクト比 (x ディメンジョン)。たとえば、16 × 9 インチ ディスプレイの場合は 16。
dwPictAspectRatioY
画像のアスペクト比 (y ディメンジョン)。たとえば、16 × 9 インチ ディスプレイの場合は 9。
dwReserved1
予約済み。ゼロでなくてはならない。
dwReserved2
将来的な使用のために予約されている。ゼロでなくてはならない。
bmiHeader
ビデオ イメージの色およびディメンジョン情報が格納された Microsoft® Win32® BITMAPINFOHEADER 構造体。

注意

dwInterlaceFlags のフィールド パターン フラグを確認するには、次のようにビット マスク AMINTERLACE_FieldPatternMask を使用する。

switch (dwInterlaceFlags & AMINTERLACE_FieldPatternMask)
{
    case AMINTERLACE_FieldPatField1Only:
        // ストリームにフィールド 2 はない。
    case AMINTERLACE_FieldPatField2Only:
        // ストリームにフィールド 1 はない。
    case AMINTERLACE_FieldPatBothRegular:
        // フィールド 1 ごとにフィールド 2 が必ず 1 つある。
    case AMINTERLACE_FieldPatBothIrregular:
        // フィールド 1 とフィールド 2 が不規則に配置されている。
}

dwInterlaceFlags のディスプレイ モード フラグを確認するには、次のようにビット マスク AMINTERLACE_DisplayModeMask を使用する。

switch (dwInterlaceFlags & AMINTERLACE_DisplayModeMask)
{
    case AMINTERLACE_DisplayModeBobOnly:
        // ディスプレイ モードは Bob のみ。
    case AMINTERLACE_DisplayModeWeaveOnly:
        // ディスプレイ モードはウィーブのみ。
    case AMINTERLACE_DisplayModeBobOrWeave:
        // Bob とウィーブの両方のモードがある。
}

次の表は、オーバーレイ ミキサー フィルタのインターレース フィールド/フレームを表示するための、インターフェイス フラグとサンプル プロパティの有効な組み合わせを記述している。サンプル プロパティは各サンプルの AM_SAMPLE2_PROPERTIES 構造体の dwTypeSpecificFlags メンバに指定されている。

ディスプレイ モード | インターレース フラグ | メディア サンプル プロパティ
フレーム | 0 | 0
非インターレースの Bob AMINTERLACE_IsInterlaced |
AMINTERLACE_1FieldPerSample |
AMINTERLACE_DisplayModeBobOnly 		AM_VIDEO_FLAG_FIELD1 or AM_VIDEO_FLAG_FIELD2
ウィーブ のみ AMINTERLACE_IsInterlaced |
AMINTERLACE_FieldPatBothRegular |
AMINTERLACE_DisplayModeWeaveOnly 		AM_VIDEO_FLAG_WEAVE
インターレースの Bob のみ フィールド 1 が最初 AMINTERLACE_IsInterlaced |
AMINTERLACE_DisplayModeBobOnly 		AM_VIDEO_FLAG_FIELD1_FIRST
フィールド 2 が最初 AMINTERLACE_IsInterlaced |
AMINTERLACE_DisplayModeBobOnly 		0
Bob か ウィーブ
(入れ替え可能) 		Bob、フィールド 1 が最初 AMINTERLACE_IsInterlaced |
AMINTERLACE_DisplayModeBobOrWeave 		AM_VIDEO_FLAG_FIELD1_FIRST
Bob、フィールド 2 が最初 AMINTERLACE_IsInterlaced |
AMINTERLACE_DisplayModeBobOrWeave 		0
ウィーブ AMINTERLACE_IsInterlaced |
AMINTERLACE_DisplayModeBobOrWeave 		AM_VIDEO_FLAG_WEAVE


列挙型

このトピックでは、Microsoft® DirectShow® の列挙型について説明する。最初のリストの後には、機能別のクローズド キャプション、DVD、および VPE 列挙型を示す。

列挙型 | 説明
AM_ASPECT_RATIO_MODE | 表示ウィンドウ内のビデオ イメージのアスペクト比を指定する。
AM_FILTER_MISC_FLAGS | ソースまたはレンダリング フィルタ フラグを含む。
AM_GRAPH_CONFIG_RECONNECT_FLAGS | フィルタ グラフを動的に再作成するときにフィルタの再接続方法を指定する。
AM_INTF_SEARCH_FLAGS | フィルタ グラフ上のインターフェイスを検索するときに、検索対象のオブジェクトのタイプを指定する。
AM_OVERLAY_NOTIFY_FLAGS | オーバーレイによって何が変更されたか、または何が変更されようとしているかについての情報を含む。
AM_PIN_CONNECTION_BLOCK_FLAGS | 出力ピンからのデータ フローをブロックする方法を指定するフラグを定義する。
AM_PUSHSOURCE_FLAGS | ライブ転送元フィルタの動作を示す。
AM_RESCTL_RESERVEFLAGS | 現在予約されているリソースの数をインクリメントまたはデクリメントするかどうかを指定するフラグを含む。
AM_SAMPLE_PROPERTY_FLAGS | AM_SAMPLE2_PROPERTIES 構造体の dwSampleFlags および dwStreamId メンバの値を指定する。これらの値はメディア サンプルのプロパティを記述する。
AM_SEEKING_SEEKING_CAPABILITIES | メディア ストリームのシーク能力を指定する。
AM_STREAM_INFO_FLAGS | AM_STREAM_INFO 構造体の各種のコンポーネントが設定されたかどうかを示す。
AMOVERLAYFX | Microsoft® DirectDraw® ハードウェア オーバーレイ サーフェスでのエフェクトを指定する。
AMTunerModeType | TV チューナー (ケーブルまたはアンテナ) の周波数を指定する。
AnalogVideoStandard | ベースバンド アナログ ビデオ信号のフォーマットを指定する。
CameraControlFlags | カメラが自動か手動かを指定する。
CameraControlProperty | DirectShow がカメラのどの部分を制御するかを指定する。
CL_ELEM_FLAGS | カットリスト要素フラグを指定する。
CL_ELEM_STATUS | カットリスト状態フラグを指定する。
CompressionCaps | ビデオ圧縮能力を示す。
DECIMATION_USAGE | オーバーレイ ミキサー フィルタが使用するデシメーション方法を記述する。
DVDECODERRESOLUTION | デジタル ビデオ (DV) のデコーディング解像度を示す。
DVENCODERFORMAT | DV フォーマットを示す。
DVENCODERRESOLUTION | DV エンコーディング解像度を示す。
DVENCODERVIDEOFORMAT | DV エンコーディング用のビデオ規格 (NTSC または PAL) を示す。
FILTER_STATE | フィルタの状態を指定する。
InterleavingMode | ビデオ フレームとオーディオ サンプルをどのようにディスクに書き込むかを指定する。
MEDIA_SAMPLE_CONTENT | MPEG-2 トランスポート ストリーム内の基本ストリームの要素を記述する。
MPEG2Level | MPEG-2 ビデオ規格に規定された MPEG-2 ビデオ レベルを示す。(ISO13818-2)
MPEG2Profile | MPEG-2 ビデオ規格に規定された MPEG-2 ビデオ プロファイルを示す。(ISO13818-2)
PhysicalConnectorType | ピンの物理タイプ (オーディオまたはビデオ) を指定する。
PIN_DIRECTION | ピンの方向を示す。
QualityMessageType | 品質メッセージ タイプを記述する。
REG_PINFLAG | REGFILTERPINS2 構造体の dwFlags メンバのフラグを示す。
REM_FILTER_FLAGS | フィルタ グラフからどのようにフィルタを削除するかを指定する。
SNDDEV_ERR | エラーが発生したときにオーディオ デバイスがどのようにアクセスされていたかを指定する。
StreamControlState | ストリームの状態を指定する。
TunerInputType | TV チューナー (ケーブルまたはアンテナ) の周波数を指定する。
TVAudioMode | TV オーディオ制御のモードを指定する。
VfwCaptureDialogs | Microsoft Video for Windows® のキャプチャ ドライバに存在可能なダイアログ ボックスを指定する。
VfwCompressDialogs | Microsoft Video for Windows の圧縮 (CODEC) ドライバに存在可能なダイアログ ボックスを指定する。
VideoControlFlags | ビデオ デバイスの動作ビデオ モード (水平または垂直フリップ、外部トリガ イネーブル、およびトリガ シミュレート) を指定する。
VideoProcAmpFlags | ビデオ プロパティの設定方法を指定する。
VideoProcAmpProperty | ビデオ プロパティを指定する。

クローズド キャプションに固有の列挙型を以下に示す。

クローズド キャプションの列挙型 | 説明
AM_LINE21_CCLEVEL | クローズド キャプションの能力レベルを示す。
AM_LINE21_CCSERVICE | クローズド キャプション デコーダ サービスを示す。
AM_LINE21_CCSTATE | クローズド キャプションの状態 (オンまたはオフ) を示す。
AM_LINE21_DRAWBGMODE | クローズド キャプション テキストのバックグラウンド モードを示す。

DVD に固有の列挙型を以下に示す。

DVD の列挙型 | 説明
AM_DVD_GRAPH_FLAGS | DVD フィルタ グラフで使用するデコーダのタイプを指定する。
AM_DVD_STREAM_FLAGS | DVD ストリーム タイプ (ビデオ、オーディオ、またはサブピクチャ) を記述する。
DVD_AUDIO_APPMODE | 現在のオーディオ モードを示す。
DVD_AUDIO_FORMAT | DVD のオーディオ フォーマットを示す。
DVD_AUDIO_LANG_EXT | オーディオ ストリームがオーディオ言語拡張を含んでいるかどうかを示すフラグを定義する。
DVD_CMD_FLAGS | DVD ナビゲータ フィルタがどのようにコマンドの同期化を処理するかを制御するフラグを定義する。
DVD_DISC_SIDE | DVD ディスクの面を示す。
DVD_DOMAIN | DVD ドメインを指定する。
DVD_ERROR | DVD エラー状態を指定する。
DVD_FRAMERATE | DVD を 1 秒あたり 25 フレームで再生するようにオーサリングするか、1 秒あたり 30 フレームで再生するようにオーサリングするかを示す。
DVD_KARAOKE_ASSIGNMENT | オーディオ チャンネルを割り当てるスピーカを示すフラグを定義する。
DVD_KARAOKE_CONTENTS | ビット単位の OR 処理において、カラオケ タイトルのオーディオ ストリームの各チャンネルのコンテンツを記述するフラグを指定する。
DVD_KARAOKE_DOWNMIX | 各補助チャンネルがダウンミックスされるスピーカがある場合にそれを制御するために IDvdControl2::SelectKaraokeAudioPresentationMode メソッドが使用するフラグを定義する。
DVD_MENU_ID | DVD ビデオ タイトル設定 (VTS) メニュー識別子を指定する。
DVD_OPTION_FLAG | DVD コンテンツの再生に関連する DVD ナビゲータ フィルタの動作を制御するフラグを定義する。
DVD_PARENTAL_LEVEL | DVD 規格で規定された汎用ペアレンタル ロック レベルのフラグを識別する。
DVD_PREFERRED_DISPLAY_MODE | ユーザーが優先的に使用するウィンドウのアスペクト比と変換方法を示す。
DVD_RELATIVE_BUTTON | DVD メニューのナビゲーションやその他の操作に使用する 4 つの方向ボタンを識別する。
DVD_SUBPICTURE_CODING | サブピクチャ ストリームがどのような種類のコンテンツを含んでいるかを示す。
DVD_SUBPICTURE_LANG_EXT | 指定されたサブピクチャ ストリーム内で可能な言語拡張を定義する。
DVD_SUBPICTURE_TYPE | サブピクチャ ストリームがどのような種類のコンテンツを含んでいるかを調べるためのフラグを定義する。
DVD_TextCharSet | 指定された文字列のエンコードに使用する ISO 文字セットを定義する。
DVD_TextStringType | DVD テキスト文字列タイプのサブセットを定義する。
DVD_TIMECODE_FLAGS | DVD が再生用にオーサリングされたフレーム レートを示す。
DVD_TITLE_APPMODE | DVD タイトルがカラオケ タイトルかどうかを示す。
DVD_VALID_UOP_FLAG | DVD で現在どのユーザー オペレーション (UOP) コマンドが許されているかを示す。
DVD_VIDEO_COMPRESSION | 可能なDVD ビデオ圧縮タイプを定義する。
DVD_WARNING | DVD 警告状態を指定する。

VPE に固有の列挙型を以下に示す。

VPE の列挙型 | 説明
AMVP_MODE | ビデオ ポート (VP) の各種のモードを指定する。
AMVP_SELECT_FORMAT_BY | ビデオ フォーマットを選択するために VP ミキサーが使用しなければならない条件を指定する。


AM_ASPECT_RATIO_MODE 列挙

列挙型

表示ウィンドウ内のビデオ イメージのアスペクト比を指定する。

構文

typedef enum _AM_ASPECT_RATIO_MODE
{
    AM_ARMODE_STRETCHED,
    AM_ARMODE_LETTER_BOX,
    AM_ARMODE_CROP,
    AM_ARMODE_STRETCHED_AS_PRIMARY
} AM_ASPECT_RATIO_MODE;

要素

AM_ARMODE_STRETCHED
アスペクト比の補正を行わない。
AM_ARMODE_LETTER_BOX
ビデオをレターボックス フォーマットにする。ビデオが歪まないように、余分なリージョンをバックグラウンド カラーで塗りつぶす。
AM_ARMODE_CROP
ビデオを適切なアスペクト比にクロッピングする。
AM_ARMODE_STRETCHED_AS_PRIMARY
プライマリ ストリームに現在設定されているモードを使用する。この値は、セカンダリ ストリームに対してのみ有効である。

注意

AM_ARMODE_STRETCHED メンバは、ウィンドウのサイズ変更時にビデオを伸縮してビデオ ストリームが表示ウィンドウ全体に表示されるようにする。AM_ARMODE_LETTER_BOX メンバは、アスペクト比を一定に保つと共にウィンドウの余分なリージョンをバックグラウンド カラーで塗りつぶすことによって、ビデオの伸縮や歪みを発生させないようにする。AM_ARMODE_CROP メンバも、必要に応じてイメージをクロッピングすることによって、伸縮が発生しないようにする。

参照

IMixerPinConfig::GetAspectRatioMode、IMixerPinConfig::SetAspectRatioMode


AM_DVD_GRAPH_FLAGS 列挙

列挙型

DVD フィルタ グラフで使用するデコーダのタイプを指定する。

構文

enum {
    AM_DVD_HWDEC_PREFER,
    AM_DVD_HWDEC_ONLY,
    AM_DVD_SWDEC_PREFER,
    AM_DVD_SWDEC_ONLY,
    AM_DVD_NOVPE
} AM_DVD_GRAPH_FLAGS;

要素

AM_DVD_HWDEC_PREFER
最大ハードウェア デコーディング。デフォルト。
AM_DVD_HWDEC_ONLY
ハードウェア デコーディングのみ。
AM_DVD_SWDEC_PREFER
最大ソフトウェア デコーディング。
AM_DVD_SWDEC_ONLY
ソフトウェア デコーディングのみ。
AM_DVD_NOVPE
コンピュータ モニタ上にビデオを表示しない。このフラグは、ハードウェア DVD-Video デコーダと TV 接続可能なポートを持つディスプレイ デバイスの組み合わせに対してのみ使用すること。DVD-Video を再生可能なセットトップ ボックス タイプのデバイスを使用すると、コンピュータ モニタではなく TV 上で DVD タイトルを再生表示できる。

注意

ハードウェア フラグ (AM_DVD_HWDEC_*) とソフトウェア フラグ (AM_DVD_SWDEC_*) を組み合わせてはならない。ただし、AM_DVD_NOVPE は任意のハードウェア フラグと組み合わせることができる。

参照

IDvdGraphBuilder::RenderDvdVideoVolume


AM_DVD_STREAM_FLAGS 列挙

列挙型

DVD ストリーム タイプ (ビデオ、オーディオ、またはサブピクチャ) を記述する。

構文

enum {
    AM_DVD_STREAM_VIDEO,
    AM_DVD_STREAM_AUDIO,
    AM_DVD_STREAM_SUBPIC
} AM_DVD_STREAM_FLAGS;

要素

AM_DVD_STREAM_VIDEO
DVD ビデオ ストリーム。
AM_DVD_STREAM_AUDIO
DVD オーディオ ストリーム。
AM_DVD_STREAM_SUBPIC
DVD サブピクチャ ストリーム。

参照

AM_DVD_RENDERSTATUS


AM_FILTER_MISC_FLAGS 列挙

列挙型

ソースまたはレンダリング フィルタ フラグが入る。

構文

typedef enum _AM_FILTER_MISC_FLAGS {
    AM_FILTER_MISC_FLAGS_IS_RENDERER = 0x00000001,
    AM_FILTER_MISC_FLAGS_IS_SOURCE   = 0x00000002
};

要素

AM_FILTER_MISC_FLAGS_IS_RENDERER
フィルタはレンダラである。
AM_FILTER_MISC_FLAGS_IS_SOURCE
フィルタはソースである。


AM_GRAPH_CONFIG_RECONNECT_FLAGS 列挙

列挙型

フィルタ グラフを動的に再作成するときのフィルタの接続法を指定する。

構文

typedef enum _AM_GRAPH_CONFIG_RECONNECT_FLAGS {
    AM_GRAPH_CONFIG_RECONNECT_DIRECTCONNECT = 0x00000001,
    AM_GRAPH_CONFIG_RECONNECT_CACHE_REMOVED_FILTERS = 0x00000002,
    AM_GRAPH_CONFIG_RECONNECT_USE_ONLY_CACHED_FILTERS = 0x00000004
} AM_GRAPH_CONFIG_RECONNECT_FLAGS;

要素

AM_GRAPH_CONFIG_RECONNECT_DIRECTCONNECT
再接続中に、明示的に要求されたフィルタを除いて追加のフィルタをグラフに挿入しない。
AM_GRAPH_CONFIG_RECONNECT_CACHE_REMOVED_FILTERS
グラフから削除されたフィルタをフィルタ キャッシュに入れる。
AM_GRAPH_CONFIG_RECONNECT_USE_ONLY_CACHED_FILTERS
追加のフィルタをグラフに挿入するときに、フィルタ キャッシュに現在入っているフィルタだけを使用する。

参照

IGraphConfig::Reconnect、IPinFlowControl::Block


AM_INTF_SEARCH_FLAGS 列挙

列挙型

フィルタ グラフ上のインターフェイスを検索するときの、検索対象のオブジェクトのタイプを指定する。

構文

enum _AM_INTF_SEARCH_FLAGS {
    AM_INTF_SEARCH_INPUT_PIN  = 0x00000001,
    AM_INTF_SEARCH_OUTPUT_PIN = 0x00000002,
    AM_INTF_SEARCH_FILTER     = 0x00000004
};

要素

AM_INTF_SEARCH_INPUT_PIN
入力ピンを検索する。
AM_INTF_SEARCH_OUTPUT_PIN
出力ピンを検索する。
AM_INTF_SEARCH_FILTER
フィルタを検索する。

注意

フラグがセットされていない場合 (デフォルト)、すべてのフラグのビットごとの OR と同じ動作を持つ。すべてのフィルタおよびピンが検索される。

参照

IAMGraphStreams::FindUpstreamInterface


AM_LINE21_CCLEVEL 列挙

列挙型

クローズド キャプションの能力レベルを示す。

構文

 typedef enum _AM_LINE21_CCLEVEL {
    AM_L21_CCLEVEL_TC2
} AM_LINE21_CCLEVEL, *PAM_LINE21_CCLEVEL ;

要素

AM_L21_CCLEVEL_TC2
能力レベル 2。

参照

IAMLine21Decoder::GetDecoderLevel


AM_LINE21_CCSERVICE 列挙

列挙型

クローズド キャプション デコーダ サービスを示す。

構文

 typedef enum _AM_LINE21_CCSERVICE {
    AM_L21_CCSERVICE_None,
    AM_L21_CCSERVICE_Caption1,
    AM_L21_CCSERVICE_Caption2,
    AM_L21_CCSERVICE_Text1,
    AM_L21_CCSERVICE_Text2,
    AM_L21_CCSERVICE_XDS,
} AM_LINE21_CCSERVICE, *PAM_LINE21_CCSERVICE ;

要素

AM_L21_CCSERVICE_None
現在のサービスなし。
AM_L21_CCSERVICE_Caption1
トゥルー キャプション。1 番目のフィールド。デフォルト サービス。
AM_L21_CCSERVICE_Caption2
第 2 言語のキャプショニング。2 番目のフィールド。通常は使用しない。
AM_L21_CCSERVICE_Text1
1 番目のテキスト フィールド。将来の互換性のために提供されているだけで、現時点では実装されていない。
AM_L21_CCSERVICE_Text2
2 番目のテキスト フィールド。将来の互換性のために提供されているだけで、現時点では実装されていない。
AM_L21_CCSERVICE_XDS
拡張データ サービス (XDS または EDS)。将来の互換性のために提供されているだけで、現時点では実装されていない。

参照

IAMLine21Decoder::GetCurrentService、IAMLine21Decoder::SetCurrentService


AM_LINE21_CCSTATE 列挙

列挙型

クローズド キャプションの状態 (オンまたはオフ) を示す。

構文

 typedef enum _AM_LINE21_CCSTATE {
    AM_L21_CCSTATE_Off,
    AM_L21_CCSTATE_On
} AM_LINE21_CCSTATE, *PAM_LINE21_CCSTATE ;

要素

AM_L21_CCSTATE_Off
クローズド キャプションはオフである。
AM_L21_CCSTATE_On
クローズド キャプションはオンである。

参照

IAMLine21Decoder::GetServiceState、IAMLine21Decoder::SetServiceState


AM_LINE21_DRAWBGMODE 列挙

列挙型

クローズド キャプション テキストのバックグラウンド モードを示す。

構文

 typedef enum _AM_LINE21_DRAWBGMODE {
    AM_L21_DRAWBGMODE_Opaque,
    AM_L21_DRAWBGMODE_Transparent
} AM_LINE21_DRAWBGMODE, *PAM_LINE21_DRAWBGMODE ;

要素

AM_L21_DRAWBGMODE_Opaque
不透明バックグラウンド。
AM_L21_DRAWBGMODE_Transparent
透明バックグラウンド。

参照

IAMLine21Decoder::GetDrawBackgroundMode、IAMLine21Decoder::SetDrawBackgroundMode


AM_OVERLAY_NOTIFY_FLAGS 列挙

列挙型

オーバーレイによって何が変更されたか、または何が変更されようとしているかについての情報が入る。

構文

typedef enum _AM_OVERLAY_NOTIFY_FLAGS {
    AM_OVERLAY_NOTIFY_FLAGS_VISIBLE_CHANGE = 0x00000001,
    AM_OVERLAY_NOTIFY_FLAGS_SOURCE_CHANGE   = 0x00000002,
    AM_OVERLAY_NOTIFY_FLAGS_DEST_CHANGE   = 0x00000004
};

要素

AM_OVERLAY_NOTIFY_VISIBLE_CHANGE
矩形が表示から非表示設定に、または非表示から表示設定に変更されることをオーバーレイに通知する。
AM_OVERLAY_NOTIFY_SOURCE_CHANGE
転送元矩形が変更された、または変更されようとしている。
AM_OVERLAY_NOTIFY_DEST_CHANGE
転送先矩形が変更された、または変更されようとしている。

注意

IDDrawExclModeVideoCallback::OnUpdateOverlay メソッドは、アプリケーションが必要な処理を行えるように、これらのフラグを使用してオーバーレイがどのように変更されたかを示す。

参照

IDDrawExclModeVideoCallback::OnUpdateOverlay


AM_PIN_CONNECTION_BLOCK_FLAGS 列挙

列挙型

出力ピンからのデータ フローをブロックする方法を指定するフラグを定義する。

構文

enum _AM_PIN_CONNECTION_BLOCK_FLAGS {
    AM_PIN_FLOW_CONTROL_BLOCK = 0x00000001,
    AM_PIN_PUSH_THROUGH_DATA = 0x00000002
};

要素

AM_PIN_FLOW_CONTROL_BLOCK
データ フローをブロックする。
AM_PIN_PUSH_THROUGH_DATA
データをフィルタ グラフに渡す。

参照

IPinFlowControl::Block


AM_PUSHSOURCE_FLAGS 列挙

列挙型

ライブ転送元フィルタの動作を示す。

構文

enum _AM_PUSHSOURCE_FLAGS {
    AM_PUSHSOURCECAPS_INTERNAL_RM        = 0x00000001,
    AM_PUSHSOURCECAPS_NOT_LIVE           = 0x00000002,
    AM_PUSHSOURCECAPS_PRIVATE_CLOCK      = 0x00000004,
    AM_PUSHSOURCEREQS_USE_STREAM_CLOCK   = 0x00010000
};

要素

AM_PUSHSOURCECAPS_INTERNAL_RM
フィルタは、独自のレート マッチング メカニズムを使用する。したがって、レンダラはこのフィルタとレートを一致させようとしてはならない。
AM_PUSHSOURCECAPS_NOT_LIVE
フィルタはライブではない。フィルタが IAMPushSource インターフェイスを公開していてもそれをライブ転送元として扱ってはならない。
AM_PUSHSOURCECAPS_PRIVATE_CLOCK
予約済み。使用してはならない。
AM_PUSHSOURCEREQS_USE_STREAM_CLOCK
予約済み。使用してはならない。

注意

フラグがセットされていない場合 (デフォルト)、転送元フィルタは、ライブであるので独自のレート マッチングを行わないと見なされる。


AM_SAMPLE_PROPERTY_FLAGS 列挙

列挙型

AM_SAMPLE2_PROPERTIES 構造体の dwSampleFlags および dwStreamId メンバの値を指定する。これらの値はメディア サンプルのプロパティを記述する。

構文

enum tagAM_SAMPLE_PROPERTY_FLAGS
     { AM_SAMPLE_SPLICEPOINT        = 0x01,
       AM_SAMPLE_PREROLL            = 0x02,
       AM_SAMPLE_DATADISCONTINUITY  = 0x04,
       AM_SAMPLE_TYPECHANGED        = 0x08,
       AM_SAMPLE_TIMEVALID          = 0x10,
       AM_SAMPLE_TIMEDISCONTINUITY  = 0x40,
       AM_SAMPLE_FLUSH_ON_PAUSE     = 0x80,
       AM_SAMPLE_STOPVALID          = 0x100,
       AM_SAMPLE_ENDOFSTREAM        = 0x200,
       AM_STREAM_MEDIA              = 0,
       AM_STREAM_CONTROL            = 1
     };

要素

AM_SAMPLE_SPLICEPOINT
サンプルはスプライス ポイントである (前のデータを参照せずにデコードできる)。
AM_SAMPLE_PREROLL
サンプルはプリロール サンプルである。
AM_SAMPLE_DATADISCONTINUITY
このサンプルの初期データはスプライス ポイントである。前のサンプルのデータは、その後にこのサンプルのデータが続くことを想定していない。詳細については、「注意」を参照すること。
AM_SAMPLE_TYPECHANGED
サンプル タイプが変更された。
AM_SAMPLE_TIMEVALID
タイムが有効である。
AM_SAMPLE_TIMEDISCONTINUITY
データのタイム ギャップがこのサンプルの後から始まる。AM_SAMPLE2_PROPERTIES 構造体の pbBuffer メンバは NULL であってもかまわない。
AM_SAMPLE_FLUSH_ON_PAUSE
ライブ データのみ。ポーズ状態での破棄を示す。
AM_SAMPLE_STOPVALID
終了タイムが有効である。
AM_SAMPLE_ENDOFSTREAM
このサンプルの後でストリームの終わりになった。これは、カーネル ストリーミング用に予約されており、現時点で Microsoft® DirectShow® はこれを使用しない。
AM_STREAM_MEDIA
通常データ ストリーム 識別子。
AM_STREAM_CONTROL
制御ストリーム 識別子。0x7FFFFFFF を超える値は、アプリケーション定義のストリームを示す。

注意

AM_SAMPLE_DATADISCONTINUITY フラグは、現在のメディア サンプル内のデータが前のサンプルのデータと連続しているとは見なされないことを示す。AM_SAMPLE_DATADISCONTINUITY フラグがセットされたサンプルを受け取ったフィルタは、バッファ内の未処理データを破棄してはならない。バッファに格納されているデータの処理を終了させる前に、入力データを待機しているフィルタは、バッファに格納されているデータを即座に処理しなければならない。ただし、バッファに格納されたデータが不完全な場合は破棄される場合がある。

たとえば、ビデオ デコンプレッサ フィルタは、2 つの完全な圧縮ビデオ フレームと 1 つの不完全な圧縮ビデオ フレームをバッファに持つ場合に、AM_SAMPLE_DATADISCONTINUITY フラグがセットされたメディア サンプルを受け取る。このような場合、フィルタは、現在のメディア サンプルのデータの処理を開始する前に、2 つの完全なフレームを圧縮解除し、不完全な 3 番目のフレームを破棄する。

AM_SAMPLE_DATADISCONTINUITY フラグは、フラッシュまたは停止に続いて受け取った最初のサンプルにセットされる。さらに、ソース内でコンテンツが切り替えられたとき、チャンネル (およびフォーマット) の変更が発生したとき、またはストリームの中断が原因でデータが失われたときは、AM_SAMPLE_DATADISCONTINUITY フラグを使用する必要がある。

AM_SAMPLE_DATADISCONTINUITY フラグは、S_OK を返す IMediaSample::IsDiscontinuity メソッドに相当する。


AM_SEEKING_SEEKING_CAPABILITIES 列挙

列挙型

メディア ストリームのシーク能力を指定する。

構文

typedef
enum AM_SEEKING_SeekingCapabilities
    {	AM_SEEKING_CanSeekAbsolute    = 0x1,
    AM_SEEKING_CanSeekForwards        = 0x2,
    AM_SEEKING_CanSeekBackwards       = 0x4,
    AM_SEEKING_CanGetCurrentPos       = 0x8,
    AM_SEEKING_CanGetStopPos          = 0x10,
    AM_SEEKING_CanGetDuration         = 0x20,
    AM_SEEKING_CanPlayBackwards       = 0x40,
    AM_SEEKING_CanDoSegments          = 0x80,
    AM_SEEKING_Source                 = 0x100
    }   AM_SEEKING_SEEKING_CAPABILITIES;

要素

AM_SEEKING_CanSeekAbsolute
ストリームは絶対位置にシークすることができる。
AM_SEEKING_CanSeekForwards
ストリームは順方向にシークすることができる。
AM_SEEKING_CanSeekBackwards
ストリームは逆方向にシークすることができる。
AM_SEEKING_CanGetCurrentPos
ストリームは現在位置にシークすることができる。
AM_SEEKING_CanGetStopPos
ストリームは停止位置にシークすることができる。
AM_SEEKING_CanGetDuration
ストリームは時間幅の合計を返すことができる。
AM_SEEKING_CanPlayBackwards
ストリームは逆方向に再生することができる。
AM_SEEKING_CanDoSegments
ストリームはシームレス ループを行うことができる (IMediaSeeking::SetPositions を参照)。
AM_SEEKING_Source
予約済み。

参照

IMediaSeeking::GetCapabilities、IMediaSeeking::CheckCapabilities


AM_STREAM_INFO_FLAGS 列挙

列挙型

AM_STREAM_INFO 構造体の各種のコンポーネントが設定されたかどうかを示す。

構文

typedef enum {
    AM_STREAM_INFO_START_DEFINED = 0x00000001,
    AM_STREAM_INFO_STOP_DEFINED  = 0x00000002,
    AM_STREAM_INFO_DISCARDING    = 0x00000004,
    AM_STREAM_INFO_STOP_SEND_EXTRA = 0x00000010
} AM_STREAM_INFO_FLAGS;

要素

AM_STREAM_INFO_START_DEFINED
有効なストリーム開始タイムが設定されたことを示す。
AM_STREAM_INFO_STOP_DEFINED
有効なストリーム終了タイムが設定されたことを示す。
AM_STREAM_INFO_DISCARDING
ストリームの破棄が現在アクティブであることを示す。
AM_STREAM_INFO_STOP_SEND_EXTRA
完了時にピンが追加のストリーム サンプルを送信することを示す。


AMOVERLAYFX 列挙

列挙型

Microsoft® DirectDraw® ハードウェア オーバーレイ サーフェスでのエフェクトを指定する。

構文

enum AMOVERLAYFX {
    AMOVERFX_NOFX =             0x00000000,
    AMOVERFX_MIRRORLEFTRIGHT =  0x00000002,
    AMOVERFX_MIRRORUPDOWN =     0x00000004,
    AMOVERFX_DEINTERLACE =      0x00000008
};

要素

AMOVERFX_NOFX
ノーマル ビデオ (エフェクトなし)。
AMOVERFX_MIRRORLEFTRIGHT
垂直軸を基準にオーバーレイをミラーリングする。
AMOVERFX_MIRRORUPDOWN
水平軸を基準にオーバーレイをミラーリングする。
AMOVERFX_DEINTERLACE
IAMOverlayFX::QueryOverlayFXCaps 内で使うとき、このフラグはハードウェアが DirectDraw 7 DDOVERFX_DEINTERLACE ヒントをサポートできるかどうかを指定する。GetOverlayFX あるいは SetOverlayFX で使うときは、このフラグは可能ならオーバーレイは非インターレースであるべきだということを示す。

参照

IAMOverlayFX インターフェイス


AMRESCTL_RESERVEFLAGS 列挙

列挙型

現在予約されているリソースの数をインクリメントまたはデクリメントするかどうかを指定する。

構文

enum _AMRESCTL_RESERVEFLAGS{
    AMRESCTL_RESERVEFLAGS_RESERVE     = 0x00,
    AMRESCTL_RESERVEFLAGS_UNRESERVE   = 0x01
};

要素

AMRESCTL_RESERVEFLAGS_RESERVE
予約されているリソースの数をインクリメントする。
AMRESCTL_RESERVEFLAGS_UNRESERVE
予約されているリソースの数をデクリメントする。


AMTunerModeType 列挙

列挙型

TV チューナー (ケーブルまたはアンテナ) の周波数を指定する。

構文

typedef enum tagAMTunerModeType
    {
        AMTUNER_MODE_DEFAULT = 0x0000,
        AMTUNER_MODE_TV = 0x0001,
        AMTUNER_MODE_FM_RADIO = 0x0002,
        AMTUNER_MODE_AM_RADIO = 0x0004,
        AMTUNER_MODE_DSS = 0x0008
    } AMTunerModeType;

要素

AMTUNER_MODE_DEFAULT
デフォルト チューナー モードを示す。
AMTUNER_MODE_TV
TV チューナー モードを示す。
AMTUNER_MODE_FM_RADIO
FM ラジオ チューナー モードを示す。
AMTUNER_MODE_AM_RADIO
AM ラジオ チューナー モードを示す。
AMTUNER_MODE_DSS
デジタル衛星サービス (DSS) チューナー モードを示す。


AMVP_MODE 列挙

列挙型

ビデオ ポート (VP) の各種のモードを指定する。

構文

typedef enum _AMVP_MODE{
AMVP_MODE_WEAVE,
AMVP_MODE_BOBINTERLEAVED,
AMVP_MODE_BOBNONINTERLEAVED,
AMVP_MODE_SKIPEVEN,
AMVP_MODE_SKIPODD
} AMVP_MODE;

要素

AMVP_MODE_WEAVE
Weave。
AMVP_MODE_BOBINTERLEAVED
インターリーブ Bob。たとえば次のフレームでリソースを割り当てて Weave モードに切り替えられる Bob モード。
MODE_BOBNONINTERLEAVED
非インターリーブ Bob。リソースを割り当てずに Weave モードに切り替えられる Bob モード。
AMVP_MODE_SKIPEVEN
偶数フィールドをスキップする。
AMVP_MODE_SKIPODD
奇数フィールドをスキップする。


AMVP_SELECT_FORMAT_BY 列挙

列挙型

ビデオ フォーマットを選択するためにオーバーレイ ミキサーが使用しなければならない条件を指定する。

構文

typedef enum _AMVP_SELECT_FORMAT_BY{
AMVP_DO_NOT_CARE,
AMVP_BEST_BANDWIDTH,
AMVP_INPUT_SAME_AS_OUTPUT
} AMVP_SELECT_FORMAT_BY;

要素

AMVP_DO_NOT_CARE
フォーマットは考慮されない。
AMVP_BEST_BANDWIDTH
最大帯域幅を使用する。
AMVP_INPUT_SAME_AS_OUTPUT
出力フォーマットと同じ入力フォーマットを使用する。


AnalogVideoStandard 列挙

列挙型

ベースバンド アナログ ビデオ信号のフォーマットを指定する。

構文

 typedef enum
    {
        AnalogVideo_None       = 0x00000000
        AnalogVideo_NTSC_M     = 0x00000001,
        AnalogVideo_NTSC_M_J   = 0x00000002,
        AnalogVideo_NTSC_433   = 0x00000004,
        AnalogVideo_PAL_B      = 0x00000010,
        AnalogVideo_PAL_D      = 0x00000020,
        AnalogVideo_PAL_H      = 0x00000080,
        AnalogVideo_PAL_I      = 0x00000100,
        AnalogVideo_PAL_M      = 0x00000200,
        AnalogVideo_PAL_N      = 0x00000400,
        AnalogVideo_PAL_60     = 0x00000800,
        AnalogVideo_SECAM_B    = 0x00001000,
        AnalogVideo_SECAM_D    = 0x00002000,
        AnalogVideo_SECAM_G    = 0x00004000,
        AnalogVideo_SECAM_H    = 0x00008000,
        AnalogVideo_SECAM_K    = 0x00010000,
        AnalogVideo_SECAM_K1   = 0x00020000,
        AnalogVideo_SECAM_L    = 0x00040000,
        AnalogVideo_SECAM_L1   = 0x00080000,
        AnalogVideo_PAL_N_COMBO = 0x00100000
    } AnalogVideoStandard;

要素

AnalogVideo_None
デジタル センサ
AnalogVideo_NTSC_M
75 IRE Setup
AnalogVideo_NTSC_M_J
日本。0 IRE Setup
AnalogVideo_PAL_B
PAL_B
AnalogVideo_PAL_D
PAL_D
AnalogVideo_PAL_H
PAL_H
AnalogVideo_PAL_I
PAL_I
AnalogVideo_PAL_M
PAL_M
AnalogVideo_PAL_N
PAL_N
AnalogVideo_SECAM_B
SECAM_B
AnalogVideo_SECAM_D
SECAM_D
AnalogVideo_SECAM_G
SECAM_G
AnalogVideo_SECAM_H
SECAM_H
AnalogVideo_SECAM_K
SECAM_K
AnalogVideo_SECAM_K1
SECAM_K1
AnalogVideo_SECAM_L
SECAM_L
アルゼンチンの PAL N Combo カラー規格を示す。
SECAM_K1


CameraControlFlags 列挙

列挙型

カメラが自動か手動かを指定する。

構文

typedef enum{
    CameraControl_Flags_Auto    = 0x0001,
    CameraControl_Flags_Manual = 0x0002
} CameraControlFlags;

要素

CameraControl_Flags_Auto
カメラの自動フラグを設定する。
CameraControl_Flags_Manual
カメラの手動フラグを設定する。


CameraControlProperty 列挙

列挙型

Microsoft® DirectShow® がカメラのどの部分を制御するかを指定する。

構文

typedef enum
{
    CameraControl_Pan = 1,
    CameraControl_Tilt,
    CameraControl_Roll,
    CameraControl_Zoom,
    CameraControl_Exposure,
    CameraControl_Iris,
    CameraControl_Focus
} CameraControlProperty;

要素

CameraControl_Pan
カメラのパン設定を設定および取得する。
CameraControl_Tilt
カメラのチルトを制御する。
CameraControl_Roll
カメラのロールを制御する。
CameraControl_Zoom
カメラのズームを制御する。
CameraControl_Exposure
カメラの露出を制御する。
CameraControl_Iris
カメラの絞りを制御する。
CameraControl_Focus
カメラのフォーカスを制御する。


CL_ELEM_FLAGS 列挙

列挙型

カット リスト要素フラグを示す。

構文

enum CL_ELEM_FLAGS{
     CL_ELEM_FIRST,
     CL_ELEM_LAST,
     CL_ELEM_NULL,
     CL_ELEM_ALL,
     CL_ELEM_NONE};

要素

CL_ELEM_FIRST
最初の要素。
CL_ELEM_LAST
最後の要素。
CL_ELEM_NULL
NULL 要素。
CL_ELEM_ALL
すべての要素。
CL_ELEM_NONE
要素なし。


CL_ELEM_STATUS 列挙

列挙型

カット リスト状態フラグを示す。

構文

enum CL_ELEM_STATUS{
     CL_NOT_PLAYED,
     CL_PLAYING,
     CL_FINISHED,
     CL_STATE_INVALID,
     CL_STATE_MASK,
     CL_WAIT_FOR_STATE};

要素

CL_NOT_PLAYED
要素は再生されていない。
CL_PLAYING
要素は再生中である。
CL_FINISHED
要素の再生が終了した。
CL_STATE_INVALID
無効な状態。
CL_STATE_MASK
無効な状態のマスク (CL_STATE_INVALID と同じ)。
CL_WAIT_FOR_STATE
待機フラグ。入力パラメータのみ。


CompressionCaps 列挙

列挙型

ビデオ圧縮能力を示す。

構文

typedef enum {
    CompressionCaps_CanQuality = 0x00000001,
    CompressionCaps_CanCrunch = 0x00000002,
    CompressionCaps_CanKeyFrame = 0x00000004,
    CompressionCaps_CanBFrame = 0x00000008,
    CompressionCaps_CanWindow = 0x0000000A
} CompressionCaps;

要素

CompressionCaps_CanQuality
ビデオ コンプレッサは、IAMVideoCompression::put_Quality および IAMVideoCompression::get_Quality メソッドをサポートする。
CompressionCaps_CanCrunch
ビデオ コンプレッサは、指定されたデータ レートにビデオを圧縮することができる。コンプレッサにこの能力がある場合、出力ピン メディア タイプは、VIDEOINFOHEADER 構造体の dwBitRate メンバにデータ レートを含む。データ レートを設定する唯一の方法は、dwBitRate を設定することである。
CompressionCaps_CanKeyFrame
ビデオ コンプレッサは、IAMVideoCompression::put_KeyFrameRate および IAMVideoCompression::get_KeyFrameRate メソッドをサポートする。
CompressionCaps_CanBFrame
ビデオ コンプレッサは、IAMVideoCompression::put_PFramesPerKeyFrame および IAMVideoCompression::get_PFramesPerKeyFrame メソッドをサポートする。
CompressionCaps_CanWindow
ビデオ コンプレッサは、IAMVideoCompression::put_WindowSize および IAMVideoCompression::get_WindowSize メソッドをサポートする。

参照

IAMVideoCompression


DECIMATION_USAGE 列挙

列挙型

ビデオ イメージを小さなサイズにスケール ダウンするためにオーバーレイ ミキサー フィルタが使用する方法を記述する。

構文

typedef enum {
    DECIMATION_LEGACY,
    DECIMATION_USE_DECODER_ONLY,
    DECIMATION_USE_VIDEOPORT_ONLY,
    DECIMATION_USE_OVERLAY_ONLY,
    DECIMATION_DEFAULT
} DECIMATION_USAGE;

要素

DECIMATION_LEGACY
次のステップをいずれかが成功するまで順に実行し、ビデオをデシメーションする。
  1. VGA チップ上のオーバーレイ スケーラの使用を試みる。
  2. オーバーレイ ミキサーがビデオ ポートを介して接続されている場合は、ビデオ ポート上のスケーラの使用を試みる。
  3. ビデオ イメージをクロッピングする。
DECIMATION_USE_DECODER_ONLY
ビデオ デコーダ上のスケーラを使用してデシメートする。失敗した場合は、ビデオ イメージをクロッピングする。
DECIMATION_USE_VIDEOPORT_ONLY
ビデオ ポートのスケーラを使用してデシメートする。失敗した場合は、ビデオ イメージをクロッピングする。
DECIMATION_USE_OVERLAY_ONLY
VGA チップ上のオーバーレイ スケーラを使用してデシメートする。失敗した場合は、ビデオ イメージをクロッピングする。
DECIMATION_DEFAULT
次のステップをいずれかが成功するまで順に実行し、ビデオをデシメートする。
  1. ビデオ デコーダ上のスケーラの使用を試みる。
  2. VGA チップ上のオーバーレイ スケーラの使用を試みる。
  3. オーバーレイ ミキサーがビデオ ポートを介して接続されている場合は、ビデオ ポート上のスケーラの使用を試みる。
  4. ビデオ イメージをクロッピングする。
このモードは、デフォルトのデシメーション方法である。

参照

IAMVideoDecimationProperties


DVD_AUDIO_APPMODE 列挙

列挙型

IDvdInfo2::GetAudioAttributes 呼び出しで取得された現在のオーディオ モードを示す。

構文

typedef enum tagDVD_AUDIO_APPMODE
{
    DVD_AudioMode_None     = 0,
    DVD_AudioMode_Karaoke  = 1,
    DVD_AudioMode_Surround = 2,
    DVD_AudioMode_Other    = 3,
} DVD_AUDIO_APPMODE;

要素

DVD_AudioMode_None
特殊なオーディオ モードなし。DVD ナビゲータは、特別な処理をせずにオーディオをデコーダに送信する。
DVD_AudioMode_Karaoke
現在のオーディオ モードはカラオケ コンテンツである。
DVD_AudioMode_Surround
現在のオーディオ モードはサラウンド サウンドである。
DVD_AudioMode_Other
認識できないオーディオ モード。


DVD_AUDIO_FORMAT 列挙

列挙型

DVD のオーディオ フォーマットを示す。

構文

typedef enum tagDVD_AUDIO_FORMAT
{
    DVD_AudioFormat_AC3       = 0,
    DVD_AudioFormat_MPEG1     = 1,
    DVD_AudioFormat_MPEG1_DRC = 2,
    DVD_AudioFormat_MPEG2     = 3,
    DVD_AudioFormat_MPEG2_DRC = 4,
    DVD_AudioFormat_LPCM      = 5,
    DVD_AudioFormat_DTS       = 6,
    DVD_AudioFormat_SDDS      = 7,
    DVD_AudioFormat_Other     = 8
} DVD_AUDIO_FORMAT;

要素

DVD_AudioFormat_AC3
オーディオ フォーマットは Dolby AC-3 である。
DVD_AudioFormat_MPEG1
オーディオ フォーマットは MPEG-1 である。
DVD_AudioFormat_MPEG1_DRC
オーディオ フォーマットはダイナミック レンジ コントロール付きの MPEG-1 である。
DVD_AudioFormat_MPEG2
オーディオ フォーマットは MPEG-2 である。
DVD_AudioFormat_MPEG2_DRC
オーディオ フォーマットはダイナミック レンジ コントロール付きの MPEG-2 である。
DVD_AudioFormat_LPCM
オーディオ フォーマットはリニア パルス符号変調 (LPCM) である。
DVD_AudioFormat_DTS
オーディオ フォーマットはデジタル シアター システム (DTS) である。
DVD_AudioFormat_SDDS
オーディオ フォーマットは Sony ダイナミック デジタル サウンド (SDDS) である。
DVD_AudioFormat_Other
オーディオ フォーマットを認識できない。

注意

この列挙は、DVD_AudioAttributes 構造体のメンバである。


DVD_AUDIO_LANG_EXT 列挙

列挙型

オーディオ ストリームがオーディオ言語拡張を含んでいるかどうかを示すフラグを定義する。

構文

typedef enum tagDVD_AUDIO_LANG_EXT
{
    DVD_AUD_EXT_NotSpecified        = 0,
    DVD_AUD_EXT_Captions            = 1,
    DVD_AUD_EXT_VisuallyImpaired    = 2,
    DVD_AUD_EXT_DirectorComments1   = 3,
    DVD_AUD_EXT_DirectorComments2   = 4
} DVD_AUDIO_LANG_EXT;

要素

DVD_AUD_EXT_NotSpecified
DVD は、このオーディオ ストリームのオーディオ言語拡張を指定していない。
DVD_AUD_EXT_Captions
オーディオ ストリームはキャプションを含む。
DVD_AUD_EXT_VisuallyImpaired
オーディオ ストリームは、視力が弱い人向けのコンテンツを含む。
DVD_AUD_EXT_DirectorComments1
オーディオ ストリームは "ディレクタ コメント 1" を含む。
DVD_AUD_EXT_DirectorComments2
オーディオ ストリームは "ディレクタ コメント 2" を含む。

注意

この列挙は、(DVD_AudioAttributes 構造体のメンバとして) IDvdInfo2::GetAudioAttributes および IDvdInfo2::GetDefaultAudioLanguage メソッドで使用される。


DVD_CMD_FLAGS 列挙

列挙型

DVD ナビゲータ フィルタがどのようにコマンドの同期化を処理するかを制御するフラグを定義する。

構文

typedef enum {
    DVD_CMD_FLAG_None          = 0x00000000,
    DVD_CMD_FLAG_Flush         = 0x00000001,
    DVD_CMD_FLAG_SendEvents    = 0x00000002,
    DVD_CMD_FLAG_Block         = 0x00000004,
} DVD_CMD_FLAGS;

要素

DVD_CMD_FLAG_None
新しいコマンドが発行されたときにバッファのフラッシュを行わない、イベントを送信しない、およびメソッド呼び出しで実行スレッドをブロックしないように DVD ナビゲータに指示する。
DVD_CMD_FLAG_Flush
PlayTitle、PlayForwards などの新しいコマンドを受け取ったとき、バッファに現在入っている約 2 秒相当のビデオを破棄してその新しいコマンドのインスタンスを即座に作成するように、DVD ナビゲータに指示する。
DVD_CMD_FLAG_SendEvents
非同期処理が完了したらアプリケーションにイベントを送信するように DVD ナビゲータに指示する。イベント パラメータは、処理の戻り値を含む。
DVD_CMD_FLAG_Block
処理が完了またはキャンセルされるまで、非同期処理がブロックされるように DVD ナビゲータに指示する。


DVD_DISC_SIDE 列挙

列挙型

DVD ディスクのサイドを示す。

構文

typedef enum tagDVD_DISC_SIDE {
    DVD_SIDE_A,
    DVD_SIDE_B
} DVD_DISC_SIDE;

要素

DVD_SIDE_A
サイド A。
DVD_SIDE_B
サイド B。

要素

この列挙は、IDVDInfo2::GetDVDVolumeInfo メソッドで使用される。


DVD_DOMAIN 列挙

列挙型

DVD ドメインを定義する。

構文

typedef enum tagDVD_DOMAIN {
    DVD_DOMAIN_FirstPlay,
    DVD_DOMAIN_VideoManagerMenu,
    DVD_DOMAIN_VideoTitleSetMenu,
    DVD_DOMAIN_Title,
    DVD_DOMAIN_Stop
} DVD_DOMAIN;

要素

DVD_DOMAIN_FirstPlay
DVD ディスクのデフォルトの初期化を行う。
DVD_DOMAIN_VideoManagerMenu
ディスク全体のメニューを表示する。
DVD_DOMAIN_VideoTitleSetMenu
現在のタイトル セットのメニューを表示する。
DVD_DOMAIN_Title
現在のタイトルを表示する。
DVD_DOMAIN_Stop
DVD ナビゲータは DVD 停止ドメインに入っている。

注意

この列挙は、IDVDInfo2::GetCurrentDomain メソッドで使用される。

ドメインとは、DVD ディスク上の論理領域である。ディスクのメイン メニューを表示している場合、DVD ナビゲータはビデオ マネージャ ドメインにあると言う。タイトル固有のメニューを表示しているときは、ビデオ タイトル設定ドメインにあると言う。ビデオを再生している場合、それはタイトル ドメインである。ユーザーが Stop コマンドを発行すると、ナビゲータは停止ドメインに入る。


DVD_ERROR 列挙

列挙型

DVD エラー状態を指定する。

構文

typedef enum _tagDVD_ERROR {
    DVD_ERROR_Unexpected                          = 1,
    DVD_ERROR_CopyProtectFail                     = 2,
    DVD_ERROR_InvalidDVD1_0Disc                   = 3,
    DVD_ERROR_InvalidDiscRegion                   = 4,
    DVD_ERROR_LowParentalLevel                    = 5,
    DVD_ERROR_MacrovisionFail                     = 6,
    DVD_ERROR_IncompatibleSystemAndDecoderRegions = 7,
    DVD_ERROR_IncompatibleDiscAndDecoderRegions   = 8
} DVD_ERROR;

要素

DVD_ERROR_Unexpected
予期しないエラーが発生した。コンテンツのオーサリング方法に誤りがある可能性がある。再生は中止される。
DVD_ERROR_CopyProtectFail
DVD コピー保護のためのキー交換が失敗した。再生は中止される。
DVD_ERROR_InvalidDVD1_0Disc
規格 1.x に関して DVD-Video ディスクのオーサリング方法に誤りがある。再生は中止される。
DVD_ERROR_InvalidDiscRegion
システム リージョンで再生されるようにディスクがオーサリングされていないために DVD-Video ディスクを再生できない。リージョンの不整合は、Dvdrgn.exe を使用してシステム リージョンを変更すれば修復できる。
DVD_ERROR_LowParentalLevel
プレーヤーのペアレンタル ロック レベルが DVD コンテンツで利用可能な最低ペアレンタル ロック レベルよりも低い。再生は中止される。
DVD_ERROR_MacrovisionFail
Macrovision® ディストリビューションが失敗した。再生は中止される。
DVD_ERROR_IncompatibleSystemAndDecoderRegions
システム リージョンがデコーダ リージョンと一致しないのでディスクを再生できない。
DVD_ERROR_IncompatibleDiscAndDecoderRegions
デコーダのリージョンで再生されるようにディスクがオーサリングされていないためにディスクを再生できない。

参照

EC_DVD_ERROR、DVD リージョン変更サポート (Windows)


DVD_FRAMERATE 列挙

列挙型

DVD を 1 秒あたり 25 フレームで再生するようにオーサリングするか、1 秒あたり 30 フレームで再生するようにオーサリングするかを示す。

構文

typedef enum tagDVD_FRAMERATE
{
    DVD_FPS_25 = 1,
    DVD_FPS_30NonDrop = 3
} DVD_FRAMERATE;

要素

DVD_FPS_25
25 フレーム/秒。
DVD_FPS_30NonDrop
30 フレーム/秒。

注意

フレーム カウントをタイムに換算するにはフレーム レートがわかっていなければならない。


DVD_KARAOKE_ASSIGNMENT 列挙

列挙型

オーディオ チャンネルを割り当てるスピーカを示すフラグを定義する。この列挙は、DVD_KaraokeAttributes 構造体のメンバである。

構文

typedef enum tagDVD_KARAOKE_ASSIGNMENT
{
    DVD_Assignment_reserved0   = 0,
    DVD_Assignment_reserved1   = 1,
    DVD_Assignment_LR    = 2,
    DVD_Assignment_LRM   = 3,
    DVD_Assignment_LR1   = 4,
    DVD_Assignment_LRM1  = 5,
    DVD_Assignment_LR12  = 6,
    DVD_Assignment_LRM12 = 7
} DVD_KARAOKE_ASSIGNMENT;

要素

DVD_Assignment_reserved0
現在は使用されない。
DVD_Assignment_reserved1
現在は使用されない。
DVD_Assignment_LR
チャンネルは、左および右スピーカに割り当てられる。
DVD_Assignment_LRM
チャンネルは、左、右、および中央スピーカに割り当てられる。
DVD_Assignment_LR1
チャンネルは、左、右、および audio1 スピーカに割り当てられる。
DVD_Assignment_LRM1
チャンネルは、左、右、中央、および audio1 スピーカに割り当てられる。
DVD_Assignment_LR12
チャンネルは、左、右、および audio2 スピーカに割り当てられる。
DVD_Assignment_LRM12
チャンネルは、左、右、中央、および audio2 スピーカに割り当てられる。


DVD_KARAOKE_CONTENTS 列挙

列挙型

ビット単位の OR 処理において、カラオケ タイトルのオーディオ ストリームの各チャンネルのコンテンツを記述するフラグを指定する。

構文

typedef enum tagDVD_KARAOKE_CONTENTS
{
    DVD_Karaoke_GuideVocal1  = 0x0001,
    DVD_Karaoke_GuideVocal2  = 0x0002,
    DVD_Karaoke_GuideMelody1 = 0x0004,
    DVD_Karaoke_GuideMelody2 = 0x0008,
    DVD_Karaoke_GuideMelodyA = 0x0010,
    DVD_Karaoke_GuideMelodyB = 0x0020,
    DVD_Karaoke_SoundEffectA = 0x0040,
    DVD_Karaoke_SoundEffectB = 0x0080
} DVD_KARAOKE_CONTENTS;

要素

DVD_Karaoke_GuideVocal1
チャンネルはガイド ボーカル 1 を含む。
DVD_Karaoke_GuideVocal2
チャンネルはガイド ボーカル 2 を含む。
DVD_Karaoke_GuideMelody1
チャンネルはガイド メロディ 1 を含む。
DVD_Karaoke_GuideMelody2
チャンネルはガイド メロディ 2 を含む。
DVD_Karaoke_GuideMelodyA
チャンネルはガイド メロディ A を含む。
DVD_Karaoke_GuideMelodyB
チャンネルはガイド メロディ B を含む。
DVD_Karaoke_SoundEffectA
チャンネルはサウンド エフェクト A を含む。
DVD_Karaoke_SoundEffectB
チャンネルはサウンド エフェクト B を含む。

注意

この列挙は、DVD_KaraokeAttributes 構造体で使用される。


DVD_KARAOKE_DOWNMIX 列挙

列挙型

各補助チャンネルがダウンミックスされるスピーカがある場合にそれを制御するために IDvdControl2::SelectKaraokeAudioPresentationMode メソッドが使用するフラグを定義する。

構文

typedef enum tagDVD_KARAOKE_DOWNMIX
{
    DVD_Mix_0to0 = 0x0001,
    DVD_Mix_1to0 = 0x0002,
    DVD_Mix_2to0 = 0x0004,
    DVD_Mix_3to0 = 0x0008,
    DVD_Mix_4to0 = 0x0010,
    DVD_Mix_Lto0 = 0x0020,
    DVD_Mix_Rto0 = 0x0040,

    DVD_Mix_0to1 = 0x0100,
    DVD_Mix_1to1 = 0x0200,
    DVD_Mix_2to1 = 0x0400,
    DVD_Mix_3to1 = 0x0800,
    DVD_Mix_4to1 = 0x1000,
    DVD_Mix_Lto1 = 0x2000,
    DVD_Mix_Rto1 = 0x4000,
} DVD_KARAOKE_DOWNMIX;

要素

DVD_Mix_0to0
使用されていない。将来的な使用のために予約されている。
DVD_Mix_1to0
使用されていない。将来的な使用のために予約されている。
DVD_Mix_2to0
チャンネル 2 を左スピーカにダウンミックスする。
DVD_Mix_3to0
チャンネル 3 を左スピーカにダウンミックスする。
DVD_Mix_4to0
チャンネル 4 を左スピーカにダウンミックスする。
DVD_Mix_Lto0
使用されていない。将来的な使用のために予約されている。
DVD_Mix_Rto0
使用されていない。将来的な使用のために予約されている。
DVD_Mix_0to1
使用されていない。将来的な使用のために予約されている。
DVD_Mix_1to1
使用されていない。将来的な使用のために予約されている。
DVD_Mix_2to1
チャンネル 2 を右スピーカにダウンミックスする。
DVD_Mix_3to1
チャンネル 3 を右スピーカにダウンミックスする。
DVD_Mix_4to1
チャンネル 4 を右スピーカにダウンミックスする。
DVD_Mix_Lto1
使用されていない。将来的な使用のために予約されている。
DVD_Mix_Rto1
使用されていない。将来的な使用のために予約されている。

注意

オーディオ チャンネルはゼロから始まる。したがって、チャンネル 2 ～ 4 は、3 つの補助カラオケ チャンネルである。ビット単位の OR 処理を使用して適切なビットを設定することにより、チャンネルを左スピーカ (0)、右スピーカ (1)、または両スピーカに送信することを指定するか、または両方のビットをオフにしてスピーカを使用しないことを指定する。DVD ナビゲータ フィルタがカラオケ モードになると、これらのビットはデフォルトですべてオフになる。


DVD_MENU_ID 列挙

列挙型

IDVDControl2::ShowMenu 呼び出しの中で DVD メニューを指定する。

構文

typedef enum tagDVD_MENU_ID {
    DVD_MENU_Title      = 2,
    DVD_MENU_Root       = 3,
    DVD_MENU_Subpicture = 4,
    DVD_MENU_Audio      = 5,
    DVD_MENU_Angle      = 6,
    DVD_MENU_Chapter    = 7
} DVD_MENU_ID;

要素

DVD_MENU_Title
DVD-Video ボリュームのトップ メニューを指定する。このメニューは、タイトル メニューまたはビデオ マネージャ メニューとも呼ばれ、ディスク上のすべての VTS (ビデオ タイトル セット) メニューへのアクセスを提供する。
DVD_MENU_Root
VTS のルート メニューを指定する。
DVD_MENU_Subpicture
VTS メニューのサブピクチャ サブメニューを指定する。
DVD_MENU_Audio
VTS メニューのオーディオ サブメニューを指定する。
DVD_MENU_Angle
VTS メニューのアングル サブメニューを指定する。
DVD_MENU_Chapter
VTS メニューのチャプター サブメニューを選択する。

注意

ルート メニューは、サブピクチャ、オーディオ、アングル、およびチャプター メニューが存在する場合にそれらにアクセスする方法を常に提供する。


DVD_OPTION_FLAG 列挙

列挙型

デジタル ビデオ ディスク (DVD) コンテンツの再生に関連する DVD ナビゲータ フィルタの動作を制御するフラグを定義する。

構文

typedef enum {
    DVD_ResetOnStop               = 1,
    DVD_NotifyParentalLevelChange = 2,
    DVD_HMSF_TimeCodeEvents       = 3
} DVD_OPTION_FLAG;

要素

DVD_ResetOnStop
このフラグを設定すると、DVD ナビゲータは、フィルタ グラフが停止して再起動された場合に、ディスクの先頭から再生を再開する。このフラグは、デフォルトでオンである。
DVD_NotifyParentalLevelChange
ディスク上で一時ペアレンタル ロック レベル コマンドを検出したらアプリケーションに通知するように、DVD ナビゲータに指示する。このフラグがセットされていない場合、DVD ナビゲータは自動的にそのコマンドを拒否して分岐する。このフラグは、デフォルトでオフである。
DVD_HMSF_TimeCodeEvents
すべてのタイムコード情報を、DVD_TIMECODE 構造体で定義されている従来の 2 進化 10 進 (BCD) フォーマットではなく、新しい DVD_HMSF_Timecode フォーマットで送信するように、DVD ナビゲータに指示する。このフラグは、デフォルトでオフである。


DVD_PARENTAL_LEVEL 列挙

列挙型

DVD 規格で規定された汎用ペアレンタル ロック レベルのフラグを識別する。

構文

typedef enum tagDVD_PARENTAL_LEVEL
{
    DVD_PARENTAL_LEVEL_8 = 0x8000,
    DVD_PARENTAL_LEVEL_7 = 0x4000,
    DVD_PARENTAL_LEVEL_6 = 0x2000,
    DVD_PARENTAL_LEVEL_5 = 0x1000,
    DVD_PARENTAL_LEVEL_4 = 0x0800,
    DVD_PARENTAL_LEVEL_3 = 0x0400,
    DVD_PARENTAL_LEVEL_2 = 0x0200,
    DVD_PARENTAL_LEVEL_1 = 0x0100
} DVD_PARENTAL_LEVEL;

注意

DVD_PARENTAL_LEVEL_8 は最も制限の厳しいレベルで、DVD_PARENTAL_LEVEL_1 は最も制限の緩いレベルである。レベルの解釈または使用方法は国によって異なる。米国およびカナダでは、以下の表に示すようにレベルは Motion Picture Association of America (MPAA) のレーティング レベルに対応する。
ペアレンタル ロック レベル | 意味
1 | レイティングは G (一般) である。
3 | レイティングは PG (保護者付き添いが望まれる) である。
4 | レイティングは PG-13 (13 才未満の子供には推奨されない、保護者付き添いが望まれる) である。
6 | レイティングは R (制限) である。
7 | レイティングは NC-17 (成人向き) である。

この列挙は、IDVDInfo2::GetTitleParentalLevels メソッドで使用される。


DVD_PREFERRED_DISPLAY_MODE 列挙

列挙型

ユーザーが優先的に使用するウィンドウのアスペクト比と変換方法を示す。

構文

typedef enum tagDVD_PREFERRED_DISPLAY_MODE
{
    DISPLAY_CONTENT_DEFAULT = 0,
    DISPLAY_16x9 = 1,
    DISPLAY_4x3_PANSCAN_PREFERRED = 2,
    DISPLAY_4x3_LETTERBOX_PREFERRED = 3
} DVD_PREFERRED_DISPLAY_MODE;

要素

DISPLAY_CONTENT_DEFAULT
デフォルトのウィンドウ サイズとコンテンツ タイプを使用する。
DISPLAY_16x9
16 × 9 ウィンドウを使用する。
DISPLAY_4x3_PANSCAN_PREFERRED
4 × 3 ウィンドウを使用し、可能であればパン-スキャンに変換する。
DISPLAY_4x3_LETTERBOX_PREFERRED
4 × 3 ウィンドウを使用し、可能であればレターボックスに変換する。

注意

DVD_PREFERRED_DISPLAY_MODE は、ユーザーが優先的に使用するウィンドウのアスペクト比と、16 × 9 のコンテンツを 4 × 3 のウィンドウ アスペクト比に変換する方法を示す。パン-スキャンおよびレターボックス変換は、2 つの変換方法である。クロッピングまたは伸縮を行わずに表示ウィンドウ内でビデオを可能な限り大きなサイズで表示する方法は、レターボックス フォーマットでの表示と呼ばれる。パン-スキャンは、ビデオの制作者が定義したパラメータを使用して、16 × 9 のビデオ画面をクロッピングして 4 × 3 のウィンドウに表示する。

一部のコンテンツはこれらのいずれかの方法でしか表示できないという状況があることから、この列挙型は優先的な変換方法を示す。4 × 3 のコンテンツは、サイドボックス化によって必ず 16 × 9 ウィンドウに変換される。このとき、レターボックス化を使用した 16 × 9 から 4 × 3 への変換で画面の上下に追加される黒色のバーが、この変換では画面の左右に追加される。

以下の表に、実際のコンテンツ タイプ (1 列目) とユーザーの好みの表示設定 (2 列目以降) との間で使用される変換方法を示す。
実際のコンテンツ タイプ | 16 × 9 | 4 × 3 パン-スキャン | 4 × 3 レターボックス
4 × 3 | サイドボックス化 | なし | なし
16 × 9 レターボックスのみ | なし | レターボックス | レターソックス
16 × 9 パン-スキャンのみ | なし | パン-スキャン | パン-スキャン
16 × 9 パン-スキャンまたはレターボックス | なし | パン-スキャン | レターボックス

ネイティブ ウィンドウ サイズは、常にユーザーの好みのサイズが使用される。


DVD_RELATIVE_BUTTON 列挙

列挙型

DVD メニューのナビゲーションやその他の操作に使用する 4 つの方向ボタンを識別する。

構文

typedef enum tagDVD_RELATIVE_BUTTON {
    DVD_RELATIVE_BUTTON_Upper = 1,
    DVD_RELATIVE_BUTTON_Lower = 2,
    DVD_RELATIVE_BUTTON_Left =  3,
    DVD_RELATIVE_BUTTON_Right = 4
    } DVD_RELATIVE_BUTTON;

要素

DVD_RELATIVE_BUTTON_Upper
上ボタン。
DVD_RELATIVE_BUTTON_Lower
下ボタン。
DVD_RELATIVE_BUTTON_Left
左ボタン。
DVD_RELATIVE_BUTTON_Right
右ボタン。


DVD_SUBPICTURE_LANG_EXT 列挙

列挙型

指定されたサブピクチャ ストリーム内で可能な言語拡張を定義する。

構文

typedef enum tagDVD_SUBPICTURE_LANG_EXT
{
    DVD_SP_EXT_NotSpecified     =0,
    DVD_SP_EXT_Caption_Normal   =1,
    DVD_SP_EXT_Caption_Big      =2,
    DVD_SP_EXT_Caption_Children =3,
    DVD_SP_EXT_CC_Normal        =5,
    DVD_SP_EXT_CC_Big           =6,
    DVD_SP_EXT_CC_Children      =7,
    DVD_SP_EXT_Forced           =9,
    DVD_SP_EXT_DirectorComments_Normal      =13,
    DVD_SP_EXT_DirectorComments_Big         =14,
    DVD_SP_EXT_DirectorComments_Children    =15,
} DVD_SUBPICTURE_LANG_EXT;

要素

DVD_SP_EXT_NotSpecified
言語拡張が存在しないことを示す。
DVD_SP_EXT_Caption_Normal
指定されたストリームが通常のキャプションを含んでいることを示す。
DVD_SP_EXT_Caption_Big
指定されたストリームが大きなキャプションを含んでいることを示す。
DVD_SP_EXT_Caption_Children
指定されたストリームが子供向けのキャプションを含んでいることを示す。
DVD_SP_EXT_CC_Normal
指定されたストリームが通常のクローズド キャプションを含んでいることを示す。
DVD_SP_EXT_CC_Big
指定されたストリームが大きなクローズド キャプションを含んでいることを示す。
DVD_SP_EXT_CC_Children
指定されたストリームが子供向けのクローズド キャプションを含んでいることを示す。
DVD_SP_EXT_Forced
サブピクチャ ストリームが強制的に起動された、つまり、アプリケーションがサブピクチャ ストリームをオフにできないことを示す。
DVD_SP_EXT_DirectorComments_Normal
指定されたストリームが通常サイズのディレクタ コメントを含んでいることを示す。
DVD_SP_EXT_DirectorComments_Big
指定されたストリームが大きなサイズのディレクタ コメントを含んでいることを示す。
DVD_SP_EXT_DirectorComments_Children
指定されたストリームが子供向けのディレクタ コメントを含んでいることを示す。


DVD_SUBPICTURE_TYPE 列挙

列挙型

サブピクチャ ストリームがどのような種類のコンテンツを含んでいるかを調べるためのフラグを定義する。

構文

typedef enum tagDVD_SUBPICTURE_TYPE
{
    DVD_SPType_NotSpecified = 0,
    DVD_SPType_Language     = 1,
    DVD_SPType_Other        = 2,
} DVD_SUBPICTURE_TYPE;

要素

DVD_SPType_NotSpecified
DVD はサブピクチャ タイプを指定していない。
DVD_SPType_Language
サブピクチャは、ムービーのサブタイトルやその他のテキストなどの言語関連のコンテキストを含んでいる。
DVD_SPType_Other
サブピクチャは、カラオケ タイトルにおけるバウンシング ボールなどの言語に関係ないコンテンツを含んでいる。


DVD_SUBPICTURE_CODING 列挙

列挙型

サブピクチャ ストリームがどのような種類のコンテンツを含んでいるかを示す。

構文

typedef enum tagDVD_SUBPICTURE_CODING
{
    DVD_SPCoding_RunLength    = 0,
    DVD_SPCoding_Extended     = 1,
    DVD_SPCoding_Other        = 2,
} DVD_SUBPICTURE_CODING;

要素

DVD_SPCoding_RunLength
サブピクチャがラン レングス エンコーディングを使用していることを示す。
DVD_SPCoding_Extended
サブピクチャが拡張エンコーディングを使用していることを示す。
DVD_SPCoding_Other
サブピクチャがほかのエンコーディング スキームを使用していることを示す。

注意

ほとんどのサブピクチャ ストリームは、ムービーのサブタイトルのような言語関連のコンテンツを含んでいるが、カラオケにおけるバウンシング ボールまたはその他の言語に関係ない目的にサブピクチャを使用することもできる。


DVD_TextCharSet 列挙

列挙型

指定された文字列のエンコードに使用する文字セットを定義する。

構文

enum DVD_TextCharSet {
    DVD_CharSet_Unicode                       = 0,
    DVD_CharSet_ISO646                        = 1,
    DVD_CharSet_JIS_Roman_Kanji               = 2,
    DVD_CharSet_ISO8859_1                     = 3,
    DVD_CharSet_ShiftJIS_Kanji_Roman_Katakana = 4
};

要素

DVD_CharSet_Unicode
Unicode™ 文字セット。
DVD_CharSet_ISO646
ISO 646 文字セット。
DVD_CharSet_JIS_Roman_Kanji
JIS Roman Kanji 文字セット。
DVD_CharSet_ISO8859_1
ISO 8859-1 文字セット。
DVD_CharSet_ShiftJIS_Kanji_Roman_Katakana
JIS Kanji-Roman-Katakana 文字セット。


DVD_TextStringType 列挙

列挙型

DVD テキスト文字列タイプのサブセットを定義する。

構文

enum DVD_TextStringType {
    // ディスク構造体識別子 (0x00..0x0f)。
    // これらは、その文字列タイプを使用して
    // 内容文字列を整理するための空の文字列。
    DVD_Struct_Volume               = 0x01,
    DVD_Struct_Title                = 0x02,
    DVD_Struct_ParentalID           = 0x03,
    DVD_Struct_PartOfTitle          = 0x04,
    DVD_Struct_Cell                 = 0x05,
    // ストリーム (0x10..0x1f)。
    DVD_Stream_Audio                = 0x10,
    DVD_Stream_Subpicture           = 0x11,
    DVD_Stream_Angle                = 0x12,
    // ストリーム (0x20..0x2f) のチャンネル。
    DVD_Channel_Audio               = 0x20,

    // アプリケーション情報。
    // 一般 (0x30..0x37)。
    // 現在のノードの名前、つまりボリューム タイトル、
    // ムービー タイトル、ソング タイトルなどを
    // を識別するために使用される。
    DVD_General_Name                = 0x30,
    DVD_General_Comments            = 0x31,

    // タイトル (0x38..0x3f)。
    DVD_Title_Series                = 0x38,
    DVD_Title_Movie                 = 0x39,
    DVD_Title_Video                 = 0x3a,
    DVD_Title_Album                 = 0x3b,
    DVD_Title_Song                  = 0x3c,
    DVD_Title_Other                 = 0x3f,

    // タイトル (サブ) (0x40..0x47)。
    DVD_Title_Sub_Series            = 0x40,
    DVD_Title_Sub_Movie             = 0x41,
    DVD_Title_Sub_Video             = 0x42,
    DVD_Title_Sub_Album             = 0x43,
    DVD_Title_Sub_Song              = 0x44,
    DVD_Title_Sub_Other             = 0x47,

    // タイトル (オリジナル) (0x48..0x4f)。
    DVD_Title_Orig_Series           = 0x48,
    DVD_Title_Orig_Movie            = 0x49,
    DVD_Title_Orig_Video            = 0x4a,
    DVD_Title_Orig_Album            = 0x4b,
    DVD_Title_Orig_Song             = 0x4c,
    DVD_Title_Orig_Other            = 0x4f,

    // その他の情報 (0x50..0x57)。
    DVD_Other_Scene                 = 0x50,
    DVD_Other_Cut                   = 0x51,
    DVD_Other_Take                  = 0x52,

    //以下の使用率の低いカテゴリは、DVD 規格
    //で規定されているが、DVD_TextStringType 列挙
    //では定義されていない。
    // 言語。    0x58..0x5b
    // ワーク。        0x5c..0x6b
    // 文字。   0x6c..0x8f
    // データ。        0x90..0x93
    // カラオケ。     0x94..0x9b
    // カテゴリ。    0x9c..0x9f
    // 歌詞。      0xa0..0xa3
    // ドキュメント。    0xa4..0xa7
    // その他。      0xa8..0xab
    // 予約済み。    0xac..0xaf
    // 管理。       0xb0..0xb7
    // 別の管理。  0xb8..0xc0
    // 予約済み。    0xd0..0xdf
    // ベンダー。      0xe0..0xef
    // 拡張。   0xf0..0xf7
    // 予約済み。    0xf8..0xff
};

要素

DVD_Struct_Volume
論理階層の最上位レベルを示す。片面ディスクまたは両面ディスクの 1 面の全内容を参照する。
DVD_Struct_Title
次の DVD_Struct_Title までの、1 つのタイトルに属するすべての内容文字列を示す。
DVD_Struct_ParentalID
次の文字列のペアレンタル ID を示す。
DVD_Struct_PartOfTitle
次の DVD_Struct_PartOfTitle までの、1 つのチャプターに属するすべての内容文字列を示す。
DVD_Struct_Cell
次の DVD_Struct_Cell までの、1 つのセルに属するすべての内容文字列を示す。セルは、チャプターのシーンであってもかまわない。
DVD_Stream_Audio
次の内容文字列がオーディオ ストリームを参照することを示す。
DVD_Stream_Subpicture
次の内容文字列がサブピクチャ ストリームを参照することを示す。
DVD_Stream_Angle
次の内容文字列がアングルを参照することを示す。
DVD_Channel_Audio
次の内容文字列がオーディオ チャンネルを参照することを示す。
DVD_General_Name
最も重要な内容文字列を示す。このタイプの文字列は、ボリューム、タイトル、チャプターなどの名前を含み、任意の構造体識別子の後に続くことができる。
DVD_General_Comments
DVD_General_Name 文字列によって記述された、タイトルやチャプターなどに関する追加の情報を持つ内容文字列を識別する。これらのコメントの細かな内容または構造は定義されていない。
DVD_Title_Series
タイトルが属するシリーズの名前を含んだ内容文字列を識別する。
DVD_Title_Movie
メイン ムービー タイトルを含んだ内容文字列を識別する。
DVD_Title_Video
ビデオ タイトル名を含んだ内容文字列を識別する。
DVD_Title_Album
アルバム タイトル名を含んだ内容文字列を識別する。
DVD_Title_Song
ソング タイトル名を含んだ内容文字列を識別する。
DVD_Title_Other
ほかのジャンルのタイトル名を含んだ内容文字列を識別する。
DVD_Title_Sub_Series
特定の国向けにローカライズされたシリーズの名前を含んだ内容文字列を識別する。
DVD_Title_Sub_Movie
特定の国向けにローカライズされたムービー タイトルを含んだ内容文字列を識別する。
DVD_Title_Sub_Video
特定の国向けにローカライズされたビデオ タイトルを含んだ内容文字列を識別する。
DVD_Title_Sub_Album
特定の国向けにローカライズされたアルバム タイトルを含んだ内容文字列を識別する。
DVD_Title_Sub_Song
特定の国向けにローカライズされたソング タイトルを含んだ内容文字列を識別する。
DVD_Title_Sub_Other
特定の国向けにローカライズされほかのジャンルのタイトルの名前を含んだ内容文字列を識別する。
DVD_Title_Orig_Series
シリーズのオリジナル名を含んだ内容文字列を識別する。
DVD_Title_Orig_Movie
ムービーのオリジナル名を含んだ内容文字列を識別する。
DVD_Title_Orig_Video
ビデオのオリジナル名を含んだ内容文字列を識別する。
DVD_Title_Orig_Album
アルバムのオリジナル名を含んだ内容文字列を識別する。
DVD_Title_Orig_Song
ソングのオリジナル名を含んだ内容文字列を識別する。
DVD_Title_Orig_Other
コンテンツのオリジナル名を含んだ内容文字列を識別する。
DVD_Other_Scene
ムービーまたはビデオの特定のシーンに関係する内容文字列を識別する。
DVD_Other_Cut
ムービーまたはビデオの特定のカットに関係する内容文字列を識別する。
DVD_Other_Take
ムービーまたはビデオの特定のテイクに関係する内容文字列を識別する。

注意

DVD_TextStringType は、IDvdInfo2::GetDVDTextStringAsUnicode および IDvdInfo2::GetDVDTextStringAsNative メソッドで返されて、指定されたテキスト文字列をディスク制作者がどのように分類したかを識別する。テキスト文字列については、「DVD テキスト文字列の操作」を参照すること。

この列挙において定義されていない 1 つの重要なテキスト文字列タイプは、拡張ソート テキスト文字列タイプ 0xF0 である. このタイプの文字列を使用すると、プレーヤーによる文字列データのソートが可能になる。このタイプには、一意な数字または語順を変えた前の文字列の組み合わせを使用することができる。たとえば "The Greatest Country Hits" という名前を持つ文字列タイプ 0x30 の後にタイプ 0xF0 の文字列 "Greatest Country Hits, The" を続けることができる。内容文字列と同様に、ソート文字列の使い方は厳密に定義されていない。


DVD_TIMECODE_FLAGS 列挙

列挙型

DVD が再生用にオーサリングされたフレーム レートを示す。

構文

typedef enum tagDVD_TIMECODE_FLAGS {
    DVD_TC_FLAG_25fps         = 0x00000001,
    DVD_TC_FLAG_30fps         = 0x00000002,
    DVD_TC_FLAG_DropFrame     = 0x00000004,
    DVD_TC_FLAG_Interpolated  = 0x00000008,
} DVD_TIMECODE_FLAGS;

要素

DVD_TC_FLAG_25fps
ディスクは、25 フレーム/秒で再生されるようにオーサリングされている。
DVD_TC_FLAG_30fps
ディスクは、30 フレーム/秒で再生されるようにオーサリングされている。
DVD_TC_FLAG_DropFrame
ディスクは、29.97 フレーム/秒で再生されるようにオーサリングされている。
DVD_TC_FLAG_Interpolated
DVD ナビゲータ フィルタによるディスクのフレーム レートの最善の見積りを表す値。


DVD_TITLE_APPMODE 列挙

列挙型

デジタル ビデオ ディスク (DVD) タイトルがカラオケ タイトルかどうかを示す。この列挙は、アプリケーションが IDvdInfo2::GetTitleAttributes メソッドを呼び出したときに値が入れられる DVD_TitleAttributes 構造体のメンバである。

構文

typedef enum tagDVD_TITLE_APPMODE
{
    DVD_AppMode_Not_Specified = 0,
    DVD_AppMode_Karaoke  = 1,
    DVD_AppMode_Other    = 3,
} DVD_TITLE_APPMODE;

要素

DVD_AppMode_Not_Specified
ディスクは、このタイトルに関するアプリケーション モード情報を提供しない。
DVD_AppMode_Karaoke
タイトルはカラオケ コンテンツを含んでいる。
DVD_AppMode_Other
タイトルは、DVD ナビゲータ フィルタが認識できないタイプのコンテンツを含んでいる。アプリケーションはこのタイトルを通常の DVD-Video タイトルとして扱う。

注意

ディスク上にカラオケ タイトルを検出すると、DVD ナビゲータは "カラオケ モード" に入ってオーディオ デコーダに通知する。デコーダは、最初に 3 つの補助チャンネルを無音にしなければならない。アプリケーションは、IDvdControl2 のカラオケ関連メソッドを使用して、これらのチャンネルのボリュームおよびミキシング構成を選択的に制御する。詳細については、 「カラオケ オーディオ ストリームの再生」を参照すること。


DVD_VIDEO_COMPRESSION 列挙

列挙型

可能なDVD ビデオ圧縮タイプを定義する。

構文

typedef enum tagDVD_VIDEO_COMPRESSION
{
    DVD_VideoCompression_Other  = 0,
    DVD_VideoCompression_MPEG1  = 1,
    DVD_VideoCompression_MPEG2  = 2,
} DVD_VIDEO_COMPRESSION;

要素

DVD_VideoCompression_Other
認識できない圧縮タイプ。
DVD_VideoCompression_MPEG1
MPEG-1 圧縮タイプ。
DVD_VideoCompression_MPEG2
MPEG-2 圧縮タイプ。

注意

この列挙は、IDvdInfo2::GetCurrentVideoAttributes メソッド呼び出しによって値が入れられる DVD_VideoAttributes 構造体のメンバである。


DVD_WARNING 列挙

列挙型

DVD 警告状態を指定する。

構文

typedef enum _tagDVD_WARNING {
    DVD_WARNING_InvalidDVD1_0Disc=1,
    DVD_WARNING_FormatNotSupported=2,
    DVD_WARNING_IllegalNavCommand=3
} DVD_WARNING;

要素

DVD_WARNING_InvalidDVD1_0Disc
DVD-Video ディスクのオーサリング方法に誤りがある。再生は続行できるが、予期しない動作が発生する可能性がある。
DVD_WARNING_FormatNotSupported
デコーダは現在のフォーマットをサポートしていない。ストリームの再生は機能しない可能性がある。
DVD_WARNING_IllegalNavCommand
内部 DVD ナビゲーション コマンド プロセッサが無効なコマンドを処理しようとした。

参照

EC_DVD_WARNING


DVDECODERRESOLUTION 列挙

列挙型

デジタル ビデオ (DV) のデコーディング解像度を示す。

構文

enum _DVDECODERRESOLUTION {
    DVDECODERRESOLUTION_720x480     =   1000,
    DVDECODERRESOLUTION_360x240     =   1001,
    DVDECODERRESOLUTION_180x120     =   1002,
    DVDECODERRESOLUTION_88x60       =   1003
};

enum _DVRESOLUTION {
    DVRESOLUTION_FULL    = 1000,
    DVRESOLUTION_HALF    = 1001,
    DVRESOLUTION_QUARTER = 1002,
    DVRESOLUTION_DC      = 1003
};

要素

DVRESOLUTION_FULL
フル サイズでデコード
DVRESOLUTION_HALF
ハーフ サイズでデコード
DVRESOLUTION_QUARTER
1/4 サイズでデコード
DVRESOLUTION_DC
1/8 サイズでデコード

注意

DVDECODERRESOLUTION 列挙子と DVRESOLUTION 列挙子は等価である、DVDECODERRESOLUTION は既存のアプリケーションと互換性を含んでいる。

デコード解像度は、現在のフォーマットが NTSC であるか PAL であるかに依存する :

列挙子 | NTSC | PAL
DVRESOLUTION_FULL | 720 x 480 | 720 x 576
DVRESOLUTION_HALF | 360 x 240 | 360 x 288
DVRESOLUTION_QUARTER | 180 x 120 | 180 x 144
DVRESOLUTION_DC | 88 x 60 | 88 x 72

参照

IIPDVDec


DVENCODERFORMAT 列挙

列挙型

デジタル ビデオ (DV) フォーマットを示す。

構文

enum _DVENCODERFORMAT {
    DVENCODERFORMAT_DVSD        =   2007,
    DVENCODERFORMAT_DVHD        =   2008,
    DVENCODERFORMAT_DVSL        =   2009
};

要素

DVENCODERFORMAT_DVSD
'dvsd' ストリーム ハンドラを使用する。
DVENCODERFORMAT_DVHD
'dvhd' ストリーム ハンドラを使用する。
DVENCODERFORMAT_DVSL
'dvsl' ストリーム ハンドラを使用する。

注意

この列挙は、AVI ストリーム ヘッダーの fccType メンバを指定する。詳細については、「AVI ファイル フォーマットの DV データ」を参照すること。

参照

IDVEnc


DVENCODERRESOLUTION 列挙

列挙型

デジタル ビデオ (DV) のエンコーディング解像度を示す。

構文

enum _DVENCODERRESOLUTION {
    DVENCODERRESOLUTION_720x480     =   2012,
    DVENCODERRESOLUTION_360x240     =   2013,
    DVENCODERRESOLUTION_180x120     =   2014,
    DVENCODERRESOLUTION_88x60       =   2015
};

要素

列挙要素の意味は、現在のフォーマットが NTSC であるか PAL であるかによって異なる。

要素 | NTSC | PAL
DVENCODERRESOLUTION_720x480 | 720 x 480 | 720 x 576
DVENCODERRESOLUTION_360x240 | 360 x 240 | 360 x 288
DVENCODERRESOLUTION_180x120 | 180 x 120 | 180 x 144
DVENCODERRESOLUTION_88x60 | 88 x 66 | 88 x 72

参照

IDVEnc


DVENCODERVIDEOFORMAT 列挙

列挙型

デジタル ビデオ (DV) エンコーディング用のビデオ規格 (NTSC または PAL) を示す。

構文

enum _DVENCODERVIDEOFORMAT {
    DVENCODERVIDEOFORMAT_NTSC       =   2000,
    DVENCODERVIDEOFORMAT_PAL        =   2001
};

要素

DVENCODERVIDEOFORMAT_NTSC
NTSC
DVENCODERVIDEOFORMAT_PAL
PAL

参照

IDVEnc


FILTER_STATE 列挙

列挙型

フィルタの状態や (IMediaControl::GetState から戻ったとき) フィルタ グラフの状態を指定する。

構文

typedef enum _FilterState
{
    State_Stopped   = 0,
    State_Paused    = State_Stopped + 1,
    State_Running   = State_Paused + 1
} FILTER_STATE;

要素

State_Stopped
停止中。フィルタはデータ処理中でない。
State_Paused
ポーズ。フィルタはデータのレンダリング中ではないが処理中である。
State_Running
実行中。フィルタはデータの処理およびレンダリング中である。

注意

様々なフィルタ状態の詳細については、「停止、ポーズ、および実行」を参照すること。


InterleavingMode 列挙

列挙型

ビデオ フレームとオーディオ サンプルをどのようにディスクに書き込むかを指定する。

構文

  typedef enum
    {
        INTERLEAVE_NONE,
        INTERLEAVE_CAPTURE,
        INTERLEAVE_FULL
    } InterleavingMode;

要素

INTERLEAVE_NONE
入力順にフレームを書き込む (非インターリーブ)。後でファイルを再生時に元に戻す必要がある。
INTERLEAVE_CAPTURE
INTERLEAVE_FULL よりもオーバーヘッドが少ないおおよそのインターリーブ。ビデオ キャプチャ向け。
INTERLEAVE_FULL
オーディオ サンプルおよびビデオ フレームの完全な精細インターリーブ。オーサリングおよび再生向け。


MEDIA_SAMPLE_CONTENT 列挙

列挙型

MPEG-2 トランスポート ストリーム内の基本ストリームの要素を記述する。この列挙は IMPEG2PIDMap インターフェイスで使われる、これは MPEG-2 デマルチプレクサ フィルタの出力ピンで実装される。

構文

typedef enum {
    MEDIA_TRANSPORT_PACKET,
    MEDIA_ELEMENTARY_STREAM,
    MEDIA_MPEG2_PSI,
    MEDIA_TRANSPORT_PAYLOAD
} MEDIA_SAMPLE_CONTENT ;

メンバ

MEDIA_TRANSPORT_PACKET
処理されずにパス スルーする完全なトランスポート ストリーム パケットを指定する。
MEDIA_ELEMENTARY_STREAM
オーディオあるいはビデオの PES ペイロードを指定する。
MEDIA_MPEG2_PSI
PAT、PMT、CAT あるいはプライベート データ ストリームを指定する。再組み立てが必要とされない完全な PSI セクションがある。
MEDIA_TRANSPORT_PAYLOAD
PES パケットのような、蓄積された TS パケット ペイロードを指定する。


MPEG2Level 列挙

列挙型

MPEG-2 ビデオ規格に規定された MPEG-2 ビデオ レベルを示す。 (ISO13818-2)

構文

enum MPEG2Level {
    MPEG2Level_Low = 1,
    MPEG2Level_Main,
    MPEG2Level_High1440,
    MPEG2Level_High
};

要素

MPEG2Level_Low
低レベル。
MPEG2Level_Main
メイン レベル。
MPEG2Level_High1440
高レベル。
MPEG2Level_High
最高レベル。

注意

DVD MPEG-2 ビデオ デコーダは、MPEG2Level_Low または MPEG2Level_Main をサポートしなければならない。


MPEG2Profile 列挙

列挙型

MPEG-2 ビデオ規格に規定された MPEG-2 ビデオ プロファイルを示す。 (ISO13818-2)

構文

enum MPEG2Profile {
    MPEG2Profile_Simple = 1,
    MPEG2Profile_Main,
    MPEG2Profile_SNRScalable,
    MPEG2Profile_SpatiallyScalable,
    MPEG2Profile_High
};

要素

MPEG2Profile_Simple
シンプル。
MPEG2Profile_Main
メイン。
MPEG2Profile_SNRScalable
信号対雑音比 (SNR) がスケーラブル。
MPEG2Profile_SpatiallyScalable
空間的にスケーラブル。
MPEG2Profile_High
ハイ。

注意

DVD ビデオ デコーダは、MPEG2Profile_Simple または MPEG2Profile_Main をサポートしなければならない。


PhysicalConnectorType 列挙

列挙型

ピンの物理タイプ (オーディオまたはビデオ) を指定する。

構文

  typedef enum
    {
    PhysConn_Video_Tuner = 1,
    PhysConn_Video_Composite,
    PhysConn_Video_SVideo,
    PhysConn_Video_RGB,
    PhysConn_Video_YRYBY,
    PhysConn_Video_SerialDigital,
    PhysConn_Video_ParallelDigital,
    PhysConn_Video_SCSI,
    PhysConn_Video_AUX,
    PhysConn_Video_1394,
    PhysConn_Video_USB,
    PhysConn_Video_VideoDecoder,
    PhysConn_Video_VideoEncoder,
    PhysConn_Video_SCART,

    PhysConn_Audio_Tuner = 4096,
    PhysConn_Audio_Line,
    PhysConn_Audio_Mic,
    PhysConn_Audio_AESDigital,
    PhysConn_Audio_SPDIFDigital,
    PhysConn_Audio_SCSI,
    PhysConn_Audio_AUX,
    PhysConn_Audio_1394,
    PhysConn_Audio_USB,
    PhysConn_Audio_AudioDecoder,
    } PhysicalConnectorType;

要素

PhysConn_Video_Tuner
ビデオのチューナー ピンを指定する。
PhysConn_Video_Composite
ビデオのコンポジット ピンを指定する。
PhysConn_Video_SVideo
S-Video (Y/C ビデオ) ピンを指定する。
PhysConn_Video_RGB
ビデオの RGB ピンを指定する。
PhysConn_Video_YRYBY
ビデオの YRYBY (Y、R-Y、B-Y) ピンを指定する。
PhysConn_Video_SerialDigital
ビデオのシリアル デジタル ピンを指定する。
PhysConn_Video_ParallelDigital
ビデオのパラレル デジタル ピンを指定する。
PhysConn_Video_SCSI
ビデオの SCSI (Small Computer System Interface) ピンを指定する。
PhysConn_Video_AUX
ビデオの AUX (補助) ピンを指定する。
PhysConn_Video_1394
ビデオの IEEE 1394 ピンを指定する。
PhysConn_Video_USB
ビデオの USB (Universal Serial Bus) ピンを指定する。
PhysConn_Video_VideoDecoder
ビデオ デコーダ ピンを指定する。
PhysConn_Video_VideoEncoder
ビデオ エンコーダ ピンを指定する。
PhysConn_Video_SCART
ビデオの SCART (Peritel) ピンを指定する。
PhysConn_Audio_Tuner
オーディオのチューナー ピンを指定する。
PhysConn_Audio_Line
オーディオのライン ピンを指定する。
PhysConn_Audio_Mic
マイク ピンを指定する。
PhysConn_Audio_AESDigital
オーディオの AES/EBU (Audio Engineering Society/European Broadcast Union) デジタル ピンを指定する。
PhysConn_Audio_SPDIFDigital
オーディオの S/PDIF (Sony/Philips Digital Interface Format) デジタル ピンを指定する。
PhysConn_Audio_SCSI
オーディオの SCSI ピンを指定する。
PhysConn_Audio_AUX
オーディオの AUX ピンを指定する。
PhysConn_Audio_1394
オーディオの IEEE 1394 ピンを指定する。
PhysConn_Audio_USB
オーディオの USB ピンを指定する。
PhysConn_Audio_AudioDecoder
オーディオ デコーダ ピンを指定する。


PIN_DIRECTION 列挙

列挙型

ピンの方向を示す。

構文

typedef enum _PinDirection {
    PINDIR_INPUT,
    PINDIR_OUTPUT
} PIN_DIRECTION;

要素

PINDIR_INPUT
入力ピン。
PINDIR_OUTPUT
出力ピン。


QualityMessageType 列挙

列挙型

品質メッセージ タイプを記述する。

構文

typedef enum {
    Famine,
    Flood
} QualityMessageType;

要素

Famine
ダウンストリーム フィルタは、さらに多くのデータを必要としている。
Flood
ダウンストリーム フィルタは、さらに少ないデータを必要としている。


REG_PINFLAG 列挙

列挙型

REGFILTERPINS2 構造体の dwFlags メンバのフラグを定義する。

構文

enum
{
    REG_PINFLAG_B_ZERO = 0x1,
    REG_PINFLAG_B_RENDERER = 0x2,
    REG_PINFLAG_B_MANY = 0x4,
    REG_PINFLAG_B_OUTPUT = 0x8
} REG_PINFLAG;

要素

REG_PINFLAG_B_ZERO
フィルタは、このピンのゼロ個のインスタンスを持つことができる。
REG_PINFLAG_B_RENDERER
フィルタは、このピンからの入力をレンダリングする。(入力ピンだけに該当する。出力ピンはこのフラグをセットしてはならない。)
REG_PINFLAG_B_MANY
フィルタは、このピンのインスタンスを複数作成することができる。
REG_PINFLAG_B_OUTPUT
このピンは出力ピンである。


REM_FILTER_FLAGS 列挙

列挙型

フィルタ グラフからどのようにフィルタを削除するかを指定する。

構文

enum _REM_FILTER_FLAGS {
    REMFILTERF_LEAVECONNECTED = 0x00000001
};

要素

REMFILTERF_LEAVECONNECTED
フィルタを接続したままにしておく。デフォルトでは、フィルタはグラフから削除されるときに接続解除される。

参照

IGraphConfig::RemoveFilterEx


SNDDEV_ERR 列挙

列挙型

エラーが発生したときにオーディオ デバイスがどのようにアクセスされていたかを指定する。

構文

typedef enum _tagSND_DEVICE_ERROR {
    SNDDEV_ERROR_Open             =1,
    SNDDEV_ERROR_Close            =2,
    SNDDEV_ERROR_GetCaps          =3,
    SNDDEV_ERROR_PrepareHeader    =4,
    SNDDEV_ERROR_UnprepareHeader  =5,
    SNDDEV_ERROR_Reset            =6,
    SNDDEV_ERROR_Restart          =7,
    SNDDEV_ERROR_GetPosition      =8,
    SNDDEV_ERROR_Write            =9,
    SNDDEV_ERROR_Pause            =10,
    SNDDEV_ERROR_Stop             =11,
    SNDDEV_ERROR_Start            =12,
    SNDDEV_ERROR_AddBuffer        =13,
    SNDDEV_ERROR_Query            =14,
    } SNDDEV_ERR;

要素

SNDDEV_ERROR_Open
オーディオ デバイスを開こうとしていた。
SNDDEV_ERROR_Close
オーディオ デバイスを閉じようとしていた。
SNDDEV_ERROR_GetCaps
基礎となっているハードウェアの能力の取得中であった。
SNDDEV_ERROR_PrepareHeader
オーディオ デバイスのヘッダーの準備中であった。
SNDDEV_ERROR_UnprepareHeader
オーディオ デバイスのヘッダーの準備が行われていなかった。
SNDDEV_ERROR_Reset
オーディオ デバイスのリセットを行おうとしていた。
SNDDEV_ERROR_Restart
オーディオ デバイスの再起動を行おうとしていた。
SNDDEV_ERROR_GetPosition
現在位置および停止位置設定の取得中であった。
SNDDEV_ERROR_Write
オーディオ デバイスへの書き込み中であった。
SNDDEV_ERROR_Pause
オーディオ デバイスがポーズしようとしていた。
SNDDEV_ERROR_Stop
オーディオ デバイスが停止しようとしていた。
SNDDEV_ERROR_Start
オーディオ デバイスが起動しようとしていた。
SNDDEV_ERROR_AddBuffer
オーディオ デバイスにバッファを追加しようとしていた。
SNDDEV_ERROR_Query
オーディオ デバイスへの問い合わせが行われていた。


StreamControlState 列挙

列挙型

ストリームの状態を指定する。

構文

enum StreamControlState {
      STREAM_FLOWING,
      STREAM_DISCARDING
    };

要素

STREAM_FLOWING
現在ストリームがデータを転送していることを示す。
STREAM_DISCARDING
サンプルを受け取るごとに破棄する。


TunerInputType 列挙

列挙型

TV チューナー (ケーブルまたはアンテナ) の周波数を指定する。

構文

typedef enum
    {
        TunerInputCable,
        TunerInputAntenna
    } TunerInputType;

要素

TunerInputCable
ケーブルの周波数を示す。
TunerInputAntenna
ブロードキャスト アンテナの周波数を示す。


TVAudioMode 列挙

列挙型

TV オーディオ制御のモードを指定する。

構文

typedef enum tagTVAudioMode
    {
        AMTVAUDIO_MODE_MONO	    = 0x0001,
        AMTVAUDIO_MODE_STEREO       = 0x0002,
        AMTVAUDIO_MODE_LANG_A       = 0x0010,
        AMTVAUDIO_MODE_LANG_B       = 0x0020,
        AMTVAUDIO_MODE_LANG_C       = 0x0040,
    } TVAudioMode;

要素

AMTVAUDIO_MODE_MONO
オーディオがモノラルであることを指定する。
AMTVAUDIO_MODE_STEREO
オーディオがステレオであることを指定する。
AMTVAUDIO_MODE_LANG_A
オーディオが追加言語であることを指定する。「注意」を参照すること。
AMTVAUDIO_MODE_LANG_B
オーディオが追加言語であることを指定する。「注意」を参照すること。
AMTVAUDIO_MODE_LANG_C
オーディオが追加言語であることを指定する。「注意」を参照すること。

注意

日本などの特定の国において 2 カ国語 TV オーディオを使用する場合、要素は次のように定義される。

要素 | 説明
AMTVAUDIO_MODE_LANG_A | 主多言語オーディオ プログラム。
AMTVAUDIO_MODE_LANG_B | 副多言語オーディオ プログラム。
AMTVAUDIO_MODE_LANG_C | 第 3 言語、または主多言語オーディオ プログラムと副多言語オーディオ プログラム。たとえば、この要素を使用して英語と日本語を別々のスピーカから出力する。


VALID_UOP_FLAG 列挙

列挙型

DVD で現在どのユーザー オペレーション (UOP) コマンドが許されているかを示す。この列挙は、IDvdInfo2::GetCurrentUOPS メソッドで使用される。

構文

typedef enum {

    UOP_FLAG_Play_Title_Or_AtTime           = 0x00000001,
    UOP_FLAG_Play_Chapter                   = 0x00000002,
    UOP_FLAG_Play_Title                     = 0x00000004,
    UOP_FLAG_Stop                           = 0x00000008,
    UOP_FLAG_ReturnFromSubMenu              = 0x00000010,
    UOP_FLAG_Play_Chapter_Or_AtTime         = 0x00000020,
    UOP_FLAG_PlayPrev_Or_Replay_Chapter     = 0x00000040,
    UOP_FLAG_PlayNext_Chapter               = 0x00000080,
    UOP_FLAG_Play_Forwards                  = 0x00000100,
    UOP_FLAG_Play_Backwards                 = 0x00000200,
    UOP_FLAG_ShowMenu_Title                 = 0x00000400,
    UOP_FLAG_ShowMenu_Root                  = 0x00000800,
    UOP_FLAG_ShowMenu_SubPic                = 0x00001000,
    UOP_FLAG_ShowMenu_Audio                 = 0x00002000,
    UOP_FLAG_ShowMenu_Angle                 = 0x00004000,
    UOP_FLAG_ShowMenu_Chapter               = 0x00008000,
    UOP_FLAG_Resume                         = 0x00010000,
    UOP_FLAG_Select_Or_Activate_Button      = 0x00020000,
    UOP_FLAG_Still_Off                      = 0x00040000,
    UOP_FLAG_Pause_On                       = 0x00080000,
    UOP_FLAG_Select_Audio_Stream            = 0x00100000,
    UOP_FLAG_Select_SubPic_Stream           = 0x00200000,
    UOP_FLAG_Select_Angle                   = 0x00400000,
    UOP_FLAG_Select_Karaoke_Audio_Presentation_Mode = 0x00800000,
    UOP_FLAG_Select_Video_Mode_Preference   = 0x01000000
} VALID_UOP_FLAG ;

要素

UOP_FLAG_Play_Title_Or_AtTime
Annex J コマンド名 : Title_Or_Time_Play
UOP_FLAG_Play_Chapter
Annex J コマンド名 : Chapter_Search_Or_Play
UOP_FLAG_Play_Title
Annex J コマンド名 : Title_Play
UOP_FLAG_Stop
Annex J コマンド名 : Stop
UOP_FLAG_ReturnFromSubMenu
Annex J コマンド名 : GoUp
UOP_FLAG_ReturnFromSubMenu
Annex J コマンド名 : Time_Or_Chapter_Search
UOP_FLAG_PlayPrev_Or_Replay_Chapter
Annex J コマンド名 : Prev_Or_Top_PG_Search
UOP_FLAG_PlayNext_Chapter
Annex J コマンド名 : Next_PG_Search
UOP_FLAG_Play_Forwards
Annex J コマンド名 : Forward_Scan
UOP_FLAG_Play_Backwards
Annex J コマンド名 : Backward_Scan
UOP_FLAG_ShowMenu_Title
Annex J コマンド名 : Title_Menu_Call
UOP_FLAG_ShowMenu_Root
Annex J コマンド名 : Root_Menu_Call
UOP_FLAG_ShowMenu_SubPic
Annex J コマンド名 : SubPic_Menu_Call
UOP_FLAG_ShowMenu_Audio
Annex J コマンド名 : Audio_Menu_Call
UOP_FLAG_ShowMenu_Angle
Annex J コマンド名 : Angle_Menu_Call
UOP_FLAG_ShowMenu_Chapter
Annex J コマンド名 : Chapter_Menu_Call
UOP_FLAG_Resume
Annex J コマンド名 : Resume
UOP_FLAG_Select_Or_Activate_Button
Annex J コマンド名 : Button_Select_Or_Activate
UOP_FLAG_Still_Off
Annex J コマンド名 : Still_Off
UOP_FLAG_Pause_On
Annex J コマンド名 : Pause_On
UOP_FLAG_Select_Audio_Stream
Annex J コマンド名 : Audio_Stream_Change
UOP_FLAG_Select_SubPic_Stream
Annex J コマンド名 : SubPic_Stream_Change
UOP_FLAG_Select_Angle
Annex J コマンド名 : Angle_Change
UOP_FLAG_Select_Karaoke_Audio_Presentation_Mode
Annex J コマンド名 : Karaoke_Audio_Pres_Mode_Change
UOP_FLAG_Select_Video_Mode_Preference
Annex J コマンド名 : Video_Pres_Mode_Change


VfwCaptureDialogs 列挙

列挙型

Video for Windows のキャプチャ ドライバに存在可能なダイアログ ボックスを指定する。

構文

 typedef enum {
    VfwCaptureDialog_Source = 1,
    VfwCaptureDialog_Format = 2,
    VfwCaptureDialog_Display = 4
} VfwCaptureDialogs;

要素

VfwCaptureDialog_Source
ビデオ ソース ダイアログ ボックス。
VfwCaptureDialog_Format
ビデオ フォーマット ダイアログ ボックス。
VfwCaptureDialog_Display
ビデオ ディスプレイ ダイアログ ボックス。

注意

IAMVfwCaptureDialogs インターフェイスはこの列挙データ型を使用する。


VfwCompressDialogs 列挙

列挙型

Video for Windows の圧縮 (CODEC) ドライバに存在可能なダイアログ ボックスを指定する。

構文

typedef enum {
    VfwCompressDialog_Config = 1,
    VfwCompressDialog_About = 2,
    VfwCompressDialog_QueryConfig = 4,
    VfwCompressDialog_QueryAbout = 8
} VfwCompressDialogs;

要素

VfwCompressDialog_Config
[Configure] ダイアログ ボックス。
VfwCompressDialog_About
[About] ダイアログ ボックス。
VfwCompressDialog_QueryConfig
[Configure] ダイアログ ボックスが利用可能かどうかを指定する。
VfwCompressDialog_QueryAbout
[About] ダイアログ ボックスが利用可能かどうかを指定する。

注意

IAMVfwCompressDialogs インターフェイスはこの列挙データ型を使用する。


VideoControlFlags 列挙

列挙型

ビデオ デバイスの動作ビデオ モードを指定する。

構文

typedef enum tagVideoControlFlags
{
    VideoControlFlag_FlipHorizontal        = 0x0001,
    VideoControlFlag_FlipVertical          = 0x0002,
    VideoControlFlag_ExternalTriggerEnable = 0x0004,
    VideoControlFlag_Trigger               = 0x0008
} VideoControlFlags;

要素

VideoControlFlag_FlipHorizontal
ピクチャを水平方向にフリップすることを指定する。
VideoControlFlag_FlipVertical
ピクチャを垂直方向にフリップすることを指定する。
VideoControlFlag_ExternalTriggerEnable
外部ソース (たとえばカメラの押しボタン) からキャプチャをトリガするためにストリームをセットアップする。バッファはドライバのキューに入れることができるが、外部イベントが発生するまでは WDM キャプチャ ドライバ (ファイルの圧縮、表示、または書き込みの場合) から渡されない。「注意」を参照すること。
VideoControlFlag_Trigger
ストリームに VideoControlFlag_ExternalTriggerEnable フラグがセットされているときに、ソフトウェアで外部トリガをシミュレートする。

注意

IAMVideoControl インターフェイスはこの列挙データ型を使用する。

複数のキャプチャ バッファはキャプチャ ドライバのキューに入れられ、ストリームが "実行" 状態になると固定レートで値が入れられる。VideoControlFlag_ExternalTriggerEnable フラグがセットされている場合、値が入れられたバッファは外部イベントが発生するまでは WDM キャプチャ ドライバ (ファイルの圧縮、表示、または書き込みの場合) から渡されない。


VideoProcAmpFlags 列挙

列挙型

ビデオ プロパティの設定方法を指定する。

構文

typedef enum tagVideoProcAmpFlags
    {
        VideoProcAmp_Flags_Manual = 0x0000,
        VideoProcAmp_Flags_Auto   = 0x0001,
    } VideoProcAmpFlags;

要素

VideoProcAmp_Flags_Manual
手動でプロパティを設定する。
VideoProcAmp_Flags_Auto
自動設定を使用する。

注意

IAMVideoProcAmp インターフェイスはこの列挙データ型を使用する。


VideoProcAmpProperty 列挙

列挙型

ビデオ プロパティを指定する。

構文

typedef enum tagVideoProcAmpProperty
    {
        VideoProcAmp_Brightness,
        VideoProcAmp_Contrast,
        VideoProcAmp_Hue,
        VideoProcAmp_Saturation,
        VideoProcAmp_Sharpness,
        VideoProcAmp_Gamma,
        VideoProcAmp_ColorEnable,
        VideoProcAmp_WhiteBalance,
        VideoProcAmp_BacklightCompensation,
        VideoProcAmp_Gain
    } VideoProcAmpProperty;

要素

VideoProcAmp_Brightness
輝度。
VideoProcAmp_Contrast
コントラスト。
VideoProcAmp_Hue
色相。
VideoProcAmp_Saturation
彩度。
VideoProcAmp_Sharpness
シャープネス。
VideoProcAmp_Gamma
ガンマ。
VideoProcAmp_ColorEnable
色。
VideoProcAmp_WhiteBalance
ホワイト バランス。
VideoProcAmp_BacklightCompensation
バックライト補正。
VideoProcAmp_Gain
ゲイン調整。

参照

IAMVideoProcAmp


定数と GUID

ここでは、Microsoft® DirectShow® で定義されている定数とグローバル ユニーク識別子 (GUID) について説明する。

  • DVD イベント通知コード
  • エラーおよび成功コード
  • イベント通知コード
  • フィルタのカテゴリ
  • メディア タイプ
  • メリット
  • タイム フォーマット GUID

参照

  • フィルタ クラス識別子 (CLSIDs): 「フィルタ」を参照。
  • 他のコンポーネント CLSID: 「DirectShow のコンポーネント」を参照。
  • 内部識別子 (IID): すべての DirectShow IID は、IID_InterfaceName フォーマットである。たとえば、IGraphBuilder インターフェイスの IID は IID_IGraphBuilder である。


DVD イベント通知コード

注 : この概要説明は、C++ 開発者だけを対象にしている。

Microsoft® DirectShow® では、フィルタ グラフ内のフィルタがフィルタ グラフ マネージャに渡す、システム定義イベントをサポートしている。フィルタは、IMediaEventSink::Notify メソッドを使用してこれらのイベントをフィルタ グラフ マネージャに渡し、アプリケーションは IMediaEvent::GetEvent メソッドを使用してこれらのイベントを取得する。

GetEvent を呼び出してイベントを取得するとき、イベントはインターフェイス ポインタまたは割り当てられているメモリへのポインタを含むことができる。したがって、GetEvent を使用するコードは、イベントの処理が終った後で IMediaEvent::FreeEventParams を使用してイベントのパラメータに関連付けられているすべてのリソースを解放する必要がある。

DVD イベント通知コードは、Dvdevcod.h に記述されている。 非 DVD イベント通知コードについては、「イベント通知コード」を参照すること。以下に、DVD イベント通知コードをアルファベット順に示す。
DVD イベント通知コード | 説明
EC_DVD_ANGLE_CHANGE | 利用可能なアングルの数または現在のアングル数が変更されたことを通知する。
EC_DVD_ANGLES_AVAILABLE | アングル ブロックが再生中にアングルの変更が可能かどうかを示す。
EC_DVD_AUDIO_STREAM_CHANGE | メイン タイトルに対して現在のオーディオ ストリーム番号が変更されたことを通知する。
EC_DVD_BUTTON_AUTO_ACTIVATED | ディスク上の命令によってメニュー ボタンが自動的にアクティブになったことを通知する。
EC_DVD_BUTTON_CHANGE | 利用可能なボタンの数が変更された、または現在選択されているボタンの番号が変更されたことを通知する。
EC_DVD_CHAPTER_AUTOSTOP | IDvdControl2::PlayChaptersAutoStop メソッド呼び出しによって再生が中止されたことを通知する。
EC_DVD_CHAPTER_START | DVD ナビゲータが現在のタイトルの新しいチャプターの再生を開始したことを通知する。
EC_DVD_CMD_START | 特定のコマンドが開始されたことを通知する。
EC_DVD_CMD_END | 特定のコマンドが完了したことを通知する。
EC_DVD_CURRENT_HMSF_TIME | .4 ～ 1.0 秒ごとに発生するすべての VOBU の先頭での現在のタイムを DVD_HMSF_TIMECODE フォーマットで通知する。
EC_DVD_CURRENT_TIME | 0.4 ～ 1.0 秒の長さを持つビデオ セグメントであるビデオ オブジェクト単位 (VOBU) の開始をすべて通知する。
EC_DVD_DISC_EJECTED | ディスクがドライブから取り出されたことを通知する。
EC_DVD_DISC_INSERTED | ディスクがドライブに挿入されたことを通知する。
EC_DVD_DOMAIN_CHANGE | DVD ナビゲータの新しいドメインを示す。
EC_DVD_ERROR | DVD エラー状態を通知する。
EC_DVD_KARAOKE_MODE | ナビゲータがカラオケ データの再生を開始または終了したことを示す。
EC_DVD_NO_FP_PGC | DVD ディスクのフォーマットが FP_PGC (First Play Program Chain) でないことを示す。
EC_DVD_PARENTAL_LEVEL_CHANGE | オーサリングされたコンテンツのペアレンタル ロック レベルが変更されようとしていることを通知する。
EC_DVD_PLAYBACK_RATE_CHANGE | 再生レートの変更が開始され、新しいレートがパラメータに指定されていることを示す。
EC_DVD_PLAYBACK_STOPPED | 再生が中止されたことを示す。DVD ナビゲータはタイトルの再生を完了し、以降の再生についての分岐命令を検出しなかった。
EC_DVD_PLAYPERIOD_AUTOSTOP | PlayPeriodInTitleAutoStop 呼び出しで指定されたセグメントの再生をナビゲータが完了したことを示す。
EC_DVD_STILL_OFF | 静止の終わりを通知する。
EC_DVD_STILL_ON | 静止の始まりを通知する。
EC_DVD_SUBPICTURE_STREAM_CHANGE | メイン タイトルに対して現在のサブピクチャ ストリーム番号が変更されたことを通知する。
EC_DVD_TITLE_CHANGE | 現在のタイトル番号が変更されたことを示す。
EC_DVD_VALID_UOPS_CHANGE | 利用可能な IDVDControl2 インターフェイス メソッドのセットが変更されたことを通知する。
EC_DVD_WARNING | DVD 警告状態を通知する。

EC_DVD_ANGLE_CHANGE

DVD イベント通知コード

利用可能なアングルの数または現在のアングル数が変更されたことを通知する。

パラメータ

lParam1
利用可能なアングルの数を示す DWORD 値。利用可能なアングルの数が 1 の場合、現在のビデオはマルチアングルではない。
lParam2
現在のアングル番号を示す DWORD 値。

注意

アングル番号は、1 ～ 9 の値で示される。

現在のアングル番号は、ディスク上でオーサリングされたナビゲーション コマンドによって自動的に変更することができる。また、IDVDControl2 インターフェイスを使用してアプリケーションで制御することもできる。

このイベントは、すべてのドメインで発生する。

EC_DVD_ANGLES_AVAILABLE

DVD イベント通知コード

アングル ブロックが再生中でアングルの変更が可能などうかを示す。

パラメータ

lParam1
アングル ブロックが再生中かどうかを示すブール (BOOL) 値。 ゼロ (0) は、再生がアングル ブロック内ではないのでアングルを利用できないことを示す。1 は、アングル ブロックが再生中であり、アングルの変更が可能であることを示す。
lParam2
ゼロ。

注意

アングルの変更はアングル ブロックに限られてはいないが、アングルの変更の明示はアングル ブロック内でのみ見ることができる。

EC_DVD_AUDIO_STREAM_CHANGE

DVD イベント通知コード

メイン タイトルに対して現在のオーディオ ストリーム番号が変更されたことを通知する。

パラメータ

lParam1
新しいユーザー オーディオ ストリーム番号を示す DWORD 値。オーディオ ストリーム番号は、0 ～ 7 の値で示される。ストリーム 0xFFFFFFFF は、ストリームが選択されていないことを示す。
lParam2
ゼロ。

注意

現在のオーディオ ストリームは、ディスク上でオーサリングされたナビゲーション コマンドによって自動的に変更することができる。また、IDVDControl2 インターフェイスを使用してアプリケーションで制御することもできる。

このイベントは、すべてのドメインで発生する。

EC_DVD_BUTTON_AUTO_ACTIVATED

DVD イベント通知コード

ディスク上の命令によってメニュー ボタンが自動的にアクティブになったことを通知する。この動作は、メニューがタイムアウトするとディスク上の特定のボタンが自動的にアクティブになるように指定されている場合に発生する。

パラメータ

lParam1
アクティブにされたボタンを示す DWORD 値。
lParam2
ゼロ。

このイベントは、すべてのドメインで発生する。

EC_DVD_BUTTON_CHANGE

DVD イベント通知コード

利用可能なボタンの数が変更された、または現在選択されているボタンの番号が変更されたことを通知する。

パラメータ

lParam1
利用可能なボタンの数を示す DWORD 値。
lParam2
現在選択されているボタン番号を示す DWORD 値。ゼロの場合、ボタンが選択されていないことを暗示する。

注意

ボタン番号は、1 ～ 36 の値で示される。

現在選択されているボタン番号は、ディスク上でオーサリングされたナビゲーション コマンドによって自動的に変更することができる。また、IDVDControl2 インターフェイスを使用してアプリケーションで制御することもできる。

このイベントは、任意の利用可能なボタン番号を通知することができる。これらの番号は、ボタンのサブセットだけをアクティブにすることができる IDvdControl::SelectAndActivateButton で使用されるボタン番号とは必ずしも対応しない。

このイベントは、すべてのドメインで発生する。

EC_DVD_CHAPTER_AUTOSTOP

DVD イベント通知コード

IDvdControl::PlayChaptersAutoStop メソッド呼び出しによって再生が中止されたことを通知する。

パラメータ

lParam1
Zero.
lParam2
Zero.

注意

このイベントは、タイトル ドメインで発生する。

EC_DVD_CHAPTER_START

DVD イベント通知コード

DVD プレーヤーが DVD_DOMAIN_Title ドメイン内の新しいプログラムの再生を開始したことを通知する。

パラメータ

lParam1
新しいチャプター (プログラム) 番号を示す DWORD 値。
lParam2
ゼロ。

注意

単純なリニア ムービーだけがこのイベントを通知する。

このイベントは、タイトル ドメインで発生する。

EC_DVD_CMD_START

DVD イベント通知コード

特定のコマンドが開始されたことを通知する。

パラメータ

lParam1
コマンド ID および HRESULT 戻り値。
lParam2
ゼロ。

注意

このイベントは、アプリケーションがいずれかの IDVDControl2::Play... メソッドの DVD_CMD_FLAG_SendEvents フラグをセットした場合にのみ発生する。詳細については「DVD コマンドの同期化」を参照すること。

このイベントは、タイトル ドメインで発生する。

EC_DVD_CMD_END

DVD イベント通知コード

特定のコマンドが完了したことを通知する。

パラメータ

lParam1
コマンド ID および完了結果。
lParam2
ゼロ。

注意

このイベントは、アプリケーションがいずれかの IDVDControl2::Play... メソッドの DVD_CMD_FLAG_SendEvents フラグをセットした場合にのみ発生する。詳細については「DVD コマンドの同期化」を参照すること。

このイベントは、タイトル ドメインで発生する。

EC_DVD_CURRENT_HMSF_TIME

DVD イベント通知コード

タイトルの開始時を基準とした現在のタイムを DVD_HMSF_TIMECODE フォーマットで通知する。このイベントは、0.4 ～ 1.0 秒間隔で発生する VOBU の開始ごとに発生する。

パラメータ

lParam1
DVD_HMSF_TIMECODE 構造体を含む ULONG 値。lParam1 を ULONG 変数に代入し、その変数を DVD_HMSF_TIMECODE にキャストして値にアクセスする。
lParam2
DVD_TIMECODE_FLAGS の共用体を含む ULONG 値。

注意

DVD_HMSF_TIMECODE フォーマットは、EC_DVD_CURRENT_TIME イベントで返される古い BCD フォーマットの代わりに使用する。HMSF タイムコードは操作が簡単である。EC_DVD_CURRENT_TIME イベントの代わりにナビゲータに EC_DVD_CURRENT_HMSF_TIME イベントを送信させるためには、アプリケーションは IDVDControl2::SetOption(DVD_HMSF_TimeCodeEvents, TRUE) を呼び出す必要がある。このフラグをセットした場合、ナビゲータは IDVDControl2 および IDVDInfo2 メソッド内のすべてのタイム パラメータが DVD_HMSF_TIMECODE として渡されることを想定する。

このイベントは、タイトル ドメインで発生する。

EC_DVD_CURRENT_TIME

DVD イベント通知コード

0.4 ～ 1.0 秒の長さを持つビデオ セグメントであるビデオ オブジェクト単位 (VOBU) の開始をすべて通知する。

パラメータ

lParam1
現在の再生タイムコードを 2 進化 10 進 (BCD) の時間、分、秒、フレーム (HH:MM:SS:FF) フォーマットで示す DWORD 値。DVD_TIMECODE 構造体のメンバ。
lParam2
タイムコードを示すブール (BOOL) 値。ゼロ (0) は 25 フレーム/秒 を示し、1 は 30 フレーム/秒 (非ドロップ) を示す。値 2 は、再生タイムを判定できないことを示す。

注意

単純なリニア ムービーだけがこのイベントを通知する。

このイベントは、タイトル ドメインで発生する。

EC_DVD_DISC_EJECTED

DVD イベント通知コード

ディスクがドライブから取り出されたことを通知する。

パラメータ

lParam1
ゼロ。
lParam2
ゼロ。

注意

ディスクが取り出されると、再生は自動的に中止される。アプリケーションはこのイベントに対して特に操作を行う必要はない。

このイベントは、すべてのドメインで発生する。

EC_DVD_DISC_INSERTED

DVD イベント通知コード

ディスクがドライブに挿入されたことを通知する。

パラメータ

lParam1
ゼロ。
lParam2
ゼロ。

注意

ディスクが挿入されると、再生は自動的に開始される。アプリケーションはこのイベントに対して特に操作を行う必要はない。

このイベントは、すべてのドメインで発生する。

EC_DVD_DOMAIN_CHANGE

DVD イベント通知コード

DVD プレーヤーの新しいドメインを示す。

パラメータ

lParam1
新しいドメインを示す DWORD 値。DVD_DOMAIN 列挙データ型のメンバ。
lParam2
ゼロ。

注意

DVD プレーヤーは、ドメインを変更するごとにこのイベントを通知する。

このイベントは、すべての DVD ドメインで発生する。

EC_DVD_ERROR

DVD イベント通知コード

DVD エラー状態を通知する。

パラメータ

lParam1
エラー状態を示す DWORD 値。DVD_ERROR 列挙データ型のメンバ。
lParam2
デコーダ リージョンをビットの反転セットとして HIWORD に含み、ドライブ/システム リージョンをビットの反転セットとして LOWORD に含む DWORD 値。「注意」を参照。

注意

このイベントは、すべてのドメインで発生する。

lParam1 = DVD_ERROR_IncompatibleSystemAndDecoderRegion の場合、(1) 指定されたリージョンがデコーダにあること、(2) ドライブとデコーダ リージョンが一致しないことを示す。

lParam1 = DVD_ERROR_IncompatibleDiscAndDecoderRegion の場合、(1) 指定されたリージョンがデコーダにあること、(2) ディスクとデコーダ リージョンが一致しないことを示す。

ディスク リージョンは、ディスク上とまったく同じように、lParam2 の LOWORD のビットの予約セットとしてエンコードされる。ディスクがリージョン内で許される場合、そのビットはオフになる。たとえばリージョン 2 のディスクに対する戻り値は、最下位 から 2 番目のビットがオフになった 253 (1111 1101) となる。複数のリージョンを持つディスクでは、このようにオフになったビットが複数ある。

lParam2 の HIWORD のデコーダ リージョンも同様にエンコードされる。

EC_DVD_KARAOKE_MODE

DVD イベント通知コード

ナビゲータがカラオケ データの再生を開始または終了したことを示す。

パラメータ

lParam1
BOOL 値。TRUE はカラオケ トラックの再生中であることを、FALSE はカラオケ データの再生中でないことを示す。
lParam2
予約済み。

注意

DVD プレーヤーは、ドメインを変更するごとにこのイベントを通知する。

このイベントは、すべての DVD ドメインで発生する。

EC_DVD_NO_FP_PGC

DVD イベント通知コード

DVD ディスクが FP_PGC (First Play Program Chain) を持たず、DVD ナビゲータが自動的に PGC をロードして再生を開始しないことを通知する。

注意

このイベントは、First Play ドメインで発生する。

EC_DVD_PARENTAL_LEVEL_CHANGE

DVD イベント通知コード

オーサリングされたコンテンツのペアレンタル ロック レベルが変更されようとしていることを通知する。

パラメータ

lParam1
プレーヤーに設定された新しいペアレンタル ロック レベルを表す LONG 値。
lParam2
ゼロ。

注意

DVD ナビゲータのソース フィルタは、DVD ディスク上の SetTmpPML コマンドに対する "オンザフライ" のペアレンタル ロック レベルの変更を現在サポートしていない。

EC_DVD_PLAYBACK_RATE_CHANGE

DVD イベント通知コード

再生レートの変更が開始されたことを通知する。パラメータ lParam1 は新しい再生レートを示す。

パラメータ

lParam1
LONG は新しい再生レートを示す。lParam1 < 0 は逆方向再生モードを示す。lParam1 > 0 は正方向再生モードを示す。lParam1 は、実際の再生レートに 10,000 を掛けた値を示す (すなわち、lParam1 = playback_rate * 10000) 。
lParam2
ゼロ。

注意

このイベントは、タイトル ドメインで発生する。

EC_DVD_PLAYBACK_STOPPED

DVD イベント通知コード

再生が中止されたことを示す。DVD ナビゲータはタイトルまたはチャプターの再生を完了し、以降の再生についての分岐命令を検出しなかった。

パラメータ

lParam1
ゼロ。
lParam2
ゼロ。

注意

このイベントはタイトル ドメインで発生するが、ユーザーが起動した Stop では発生しない。

EC_DVD_STILL_OFF

DVD イベント通知コード

静止の終わり (PGC、Cell、または VOBU) を通知する。

パラメータ

lParam1
ゼロ。
lParam2
ゼロ。

注意

このイベントは、現在アクティブな静止が解放されたことを示す。

このイベントは、すべてのドメインで発生する。

EC_DVD_PLAYPERIOD_AUTOSTOP

DVD イベント通知コード

PlayPeriodInTitleAutoStop 呼び出しで指定されたセグメントの再生をナビゲータが完了したことを示す。

パラメータ

lParam1
ゼロ。
lParam2
ゼロ。

注意

このイベントは、タイトル ドメインで発生する。

このイベントは、指定されたセグメントの再生をナビゲータが完了する前にその再生がキャンセルされたときにも送信される。

EC_DVD_STILL_ON

DVD イベント通知コード

静止の始まり (PGC、Cell、または VOBU) を通知する。

パラメータ

lParam1
ボタンが利用可能かどうかを示すブール (BOOL) 値。ゼロ (0) は、ボタンが利用可能なので IDVDControl2::StillOff メソッドが機能しないことを示す。1 は、ボタンが利用不可能なので IDVDControl2::StillOff が機能することを示す。
lParam2
静止を継続する秒数を表す DWORD 値。0xFFFFFFFF は、無期限の静止、すなわちユーザーがボタンを押すか、またはアプリケーションが IDVDControl2::StillOff を呼び出すまで待機することを示す。

注意

ボタンと静止はすべての組み合わせが可能である (ボタンがオンで静止がオン、ボタンがオンで静止がオフ、ボタンがオフで静止がオン、ボタンがオフで静止がオフ)。

このイベントは、すべてのドメインで発生する。

EC_DVD_SUBPICTURE_STREAM_CHANGE

DVD イベント通知コード

メイン タイトルに対して現在のサブピクチャ ストリーム番号が変更されたことを通知する。

パラメータ

lParam1
新しいサブピクチャ ストリーム番号を示す DWORD 値。サブピクチャ ストリーム番号は、0 ～ 31 の値で示される。ストリーム 0xFFFFFFFF は、ストリームが選択されていないことを示す。
lParam2
ゼロ。

注意

サブピクチャは、ディスク上でオーサリングされたナビゲーション コマンドによって自動的に変更することができる。また、IDVDControl2 を使用してアプリケーションで制御することもできる。

このイベントは、すべてのドメインで発生する。

EC_DVD_TITLE_CHANGE

DVD イベント通知コード

現在のタイトル番号が変更されたことを示す。

パラメータ

lParam1
新しいタイトル番号を示す　DWORD 値。
lParam2
ゼロ。

注意

タイトル番号は、1 ～ 99 の値で示される。この番号は、ディスク全体のタイトル番号である TTN を示すもので、現在の VTS に関するタイトル番号である VTS_TTN を示すものではない。

このイベントは、タイトル ドメインで発生する。

EC_DVD_VALID_UOPS_CHANGE

DVD イベント通知コード

利用可能な IDVDControl2 インターフェイス メソッドのセットが変更されたことを通知する。

パラメータ

lParam1
そのビットが DVD ディスクが明示的に無効にした IDVDControl2 コマンドを示している ULONG を表す DWORD 値。
lParam2
ゼロ。

注意

このイベントは、DVD ディスク上のコンテンツによって明示的に無効にされた操作を示すだけで、無効になっていないメソッドの呼び出しが有効であることを保証するものではない。たとえばボタンが存在しない場合、IDvdControl::ActivateButton メソッドは明示的に無効にされていなくても機能しない。

このイベントは、すべてのドメインで発生する。

EC_DVD_WARNING

DVD イベント通知コード

DVD 警告状態を通知する。

パラメータ

lParam1
警告状態を示す DWORD 値。DVD_WARNING 列挙データ型のメンバ。
lParam2
ゼロ。

注意

このイベントは、すべてのドメインで発生する。


エラーおよび成功コード

Microsoft® DirectShow® は、エラーおよび成功通知 (戻りコード) を HRESULT 値のフォーマットでアプリケーションに返す。戻りコードの LOWORD 部分は、16 進フォーマットの戻りコードそのものを表す。戻りコードを取得した後で AMGetErrorText 関数を呼び出すと、コードのテキスト記述が返される。COM Win32 HRESULT のドキュメントには、FAILED および SUCCEEDED マクロを使用して戻り値をテストする方法など、詳しい情報が記載されている。

このトピックは、以下のセクションを含んでいる。

  • 一般的な COM HRESULT 値
  • DirectShow に固有の HRESULT 値
  • DirectShow Editing Services に固有の HRESULT 値

一般的な COM HRESULT 値

以下に、DirectShow が返す一般的な COM エラー コードと成功コードのいくつかを示す。
値 | 意味
E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_OUTOFMEMORY | メモリ不足。
E_POINTER | NULL ポインタ引数。
E_UNEXPECTED | 予期せぬエラー。
NOERROR | エラーなし。数値的には S_OK と同じ。
S_FALSE | 成功。条件が FALSE だった。
S_OK | 成功。数値的には NOERROR と同じ。
S_TRUE | 成功。条件が TRUE だった。

DirectShow に固有の HRESULT 値

以下の表に、DirectShow に固有のエラーおよび成功コードを数字の順に示す。VFW_S_ で始まる戻りコードは全体としての成功を示す。処理が部分的に成功してそれ以外に成功を示す戻り値を返すこともある。たとえば VFW_S_SOME_DATA_IGNORED は、プロパティ設定のいくつかを無視してファイルがレンダリングされたことを示す。VFW_E_ で始まる戻りコードはエラーを示し、CTL_ (制御エラー コード) で始まる戻りコードは Microsoft® Windows Media™ Player コントロールに関係する情報を示す。この表は可能な戻り値コードをすべて網羅したものではなく、特に DirectShow に関係する戻りコードをリストしてある。DirectShow に固有の戻りコードは、Vfwmsgs.h ヘッダー ファイルにも記述されている。ここにリストされていないエラーが発生した場合は、別のソース、たとえば COM または Microsoft® Windows® 9x エラーの一覧などを参照すること。たとえば Microsoft® Visual C++® ユーザーであれば、Winerror.h インクルード ファイルを見れば COM または Windows 9x エラーを調べることができる。

C/C++ プログラマは、完全な (32 ビット) 16 進フォーマットのエラー コードを受け取る。一方、Microsoft® Visual Basic® プログラマは、エラー コードの先頭 16 ビットだけに相当する 10 進値を受け取る。この値は、エラー通知ダイアログ ボックスまたは Err オブジェクトにランタイム エラーとして表示される。エラーが以下の表に示されていない場合は、10 進値を対応する 16 進値に変換してから前述のようにそれに対応するエラーを調べる必要がある。エラーの 16 進値は最大で 4 桁である。エラーを調べるには、エラー コード表に記載された 16 進コードの最後の 4 桁を、変換されたランタイム エラーと照合する。
戻りコード | 説明 | 16 進値 | 10 進値 (LOWORD)
CTL_E_ILLEGALFUNCTIONCALL | 関数呼び出しの構文に誤りがある。 | 0x800A0005 | 5
CTL_E_OVERFLOW | 結果が大きすぎて関数の戻り型で表すことができない。 | 0x800A0006 | 6
CTL_E_OUTOFMEMORY | メモリ不足のために要求された処理を行えない。 | 0x800A0007 | 7
CTL_E_DIVISIONBYZERO | 関数がゼロによる除算を行うとした。 | 0x800A000B | 11
CTL_E_OUTOFSTRINGSPACE | 文字列空間不足のために要求された処理を行えない。一部の操作 (たとえばコピー) では、文字列空間を使い果たすような一時文字列が使用されることがある。 | 0x800A000E | 14
CTL_E_OUTOFSTACKSPACE | 文字列空間不足のために要求された処理を行えない。各スレッドには専用のスタックがある一方で、ほかのリソース (たとえばヒープ メモリ) はプロセス内のすべてのスレッドで共用される。プログラムが必要とする追加のスレッドのそれぞれのスタックにどれ位のメモリを割り当てるかを指定しなければならない。オペレーティング システムは必要に応じてスレッドの追加スタック空間を割り当てるが、デフォルト値は自分で指定する必要がある。必要な空間をオペレーティング システムが割り当てることができない場合、このエラーが発生する。 | 0x800A001C | 28
CTL_E_BADFILENAMEORNUMBER | 関数がアクセスしようとしたファイルのファイル名または番号が無効である。 | 0x800A0034 | 52
CTL_E_FILENOTFOUND | 関数がアクセスしようとしたファイルが見つからない。 | 0x800A0035 | 53
CTL_E_BADFILEMODE | 関数が互換性のないファイル モードを持つファイルに対して操作を行おうとした。ファイル モードには、追加、バイナリ、入力、出力、ランダムがある。 | 0x800A0036 | 54
CTL_E_FILEALREADYOPEN | 関数が既に開かれているファイルを開こうとした。 | 0x800A0037 | 55
CTL_E_DEVICEIOERROR | 関数の実行中にデバイス I/O エラーが発生した。 | 0x800A0039 | 57
CTL_E_FILEALREADYEXISTS | 関数が既に存在しているファイルを作成しようとした。 | 0x800A003A | 58
CTL_E_BADRECORDLENGTH | 関数が不正なファイル レコードにアクセスしようとした。たとえばランダム アクセス用に開かれるファイルは、同じ長さのレコードから構成されていることが想定される。 | 0x800A003B | 59
CTL_E_DISKFULL | 関数がディスクに書き込みを行おうとしたがディスクが一杯だった。 | 0x800A003D | 61
CTL_E_BADRECORDNUMBER | 関数が不正なファイル レコードにアクセスしようとした。レコード番号は、レコードセット (データ ソースのレコードのセット) 内の位置である。 | 0x800A003F | 63
CTL_E_BADFILENAME | 関数が不正なファイル名にアクセスしようとした。 | 0x800A0040 | 64
CTL_E_TOOMANYFILES | 関数が既にたくさんのファイルを開きすぎている状態でファイルを開こうとした。 | 0x800A0043 | 67
CTL_E_DEVICEUNAVAILABLE | 関数が利用できないデバイスにアクセスしようとした。 | 0x800A0044 | 68
CTL_E_PERMISSIONDENIED | 関数が適切な権限を持たないファイルにアクセスしようとした。 | 0x800A0046 | 70
CTL_E_DISKNOTREADY | 関数がディスクの準備が整っていないのにファイルにアクセスしようとした。 | 0x800A0047 | 71
CTL_E_PATHFILEACCESSERROR | 関数が不正なまたは権限が不適切なファイルまたはパスにアクセスしようとした。 | 0x800A004B | 75
CTL_E_PATHNOTFOUND | 関数が不正なパスを持つファイルにアクセスしようとした。 | 0x800A004C | 76
CTL_E_INVALIDPATTERNSTRING | 関数が無効な文字列で呼び出された。 | 0x800A005D | 93
CTL_E_INVALIDUSEOFNULL | 関数が無効な NULL で呼び出された。 | 0x800A005E | 94
VFW_S_NO_MORE_ITEMS | リストにはもう項目がない。 | 0x00040103 | 259
CTL_E_INVALIDFILEFORMAT | 関数が互換性のないファイル フォーマットを持つファイルに対して操作を行おうとした。 | 0x800A0141 | 321
CTL_E_INVALIDPROPERTYVALUE | 関数が無効なプロパティ値で呼び出された。 | 0x800A017C | 380
CTL_E_INVALIDPROPERTYARRAYINDEX | 関数が無効なプロパティ配列インデックスで呼び出された。 | 0x800A017D | 381
CTL_E_SETNOTSUPPORTEDATRUNTIME | 関数が実行時に設定できないプロパティを設定しようとした。 | 0x800A017E | 382
CTL_E_SETNOTSUPPORTED | 関数が設定できないプロパティを設定しようとした。 | 0x800A017F | 383
CTL_E_NEEDPROPERTYARRAYINDEX | 配列インデックスが必要なプロパティに対して、関数が配列インデックスなしでアクセスしようとした。 | 0x800A0181 | 385
CTL_E_SETNOTPERMITTED | 関数がプロパティを設定する適切な権限を持たずにプロパティを設定しようとした。 | 0x800A0183 | 387
CTL_E_GETNOTSUPPORTEDATRUNTIME | 関数が実行時に取得できないプロパティを取得しようとした。 | 0x800A0189 | 393
CTL_E_GETNOTSUPPORTED | 関数が取得できないプロパティを取得しようとした。 | 0x800A018A | 394
CTL_E_PROPERTYNOTFOUND | 関数が取得しようとしたプロパティが見つからない。 | 0x800A01A6 | 422
CTL_E_INVALIDCLIPBOARDFORMAT | 関数が無効なクリップボード フォーマットで操作を行おうとした。 | 0x800A01CC | 460
CTL_E_INVALIDPICTURE | 関数が無効なピクチャ フォーマットで操作を行おうとした。 | 0x800A01E1 | 481
CTL_E_PRINTERERROR | 関数が印刷を行おうとしたがプリンタ エラーが発生した。 | 0x800A01E2 | 482
VFW_E_INVALIDMEDIATYPE | 指定されたメディア タイプは無効である。 | 0x80040200 | 512
VFW_E_INVALIDSUBTYPE | 指定されたメディア サブタイプは無効である。 | 0x80040201 | 513
VFW_E_NEED_OWNER | このオブジェクトは集成オブジェクトとしてのみ作成することができる。 | 0x80040202 | 514
VFW_E_ENUM_OUT_OF_SYNC | 列挙オブジェクトの状態が変化して、列挙子の状態との矛盾が発生した。列挙子の前の呼び出しで取得したデータを破棄し、列挙子の Reset メソッドを呼び出してその列挙子を更新すること。 | 0x80040203 | 515
VFW_E_ALREADY_CONNECTED | 処理に含まれるピンが既に少なくとも 1 つ接続されている。 | 0x80040204 | 516
VFW_E_FILTER_ACTIVE | フィルタがアクティブなので、この処理を実行できない。 | 0x80040205 | 517
VFW_E_NO_TYPES | 指定されたいずれかのピンがメディア タイプをサポートしていない。 | 0x80040206 | 518
VFW_E_NO_ACCEPTABLE_TYPES | これらのピンの間に共通のメディア タイプがない。 | 0x80040207 | 519
VFW_E_INVALID_DIRECTION | 同じ方向のピンを 2 つ接続することはできない。 | 0x80040208 | 520
VFW_E_NOT_CONNECTED | ピンが接続されていないため、処理を実行できない。 | 0x80040209 | 521
VFW_E_NO_ALLOCATOR | サンプル バッファ アロケータが利用不可能。 | 0x8004020A | 522
VFW_E_RUNTIME_ERROR | ランタイム エラーが発生した。 | 0x8004020B | 523
VFW_E_BUFFER_NOTSET | バッファ空間が設定されていない。 | 0x8004020C | 524
VFW_E_BUFFER_OVERFLOW | バッファが小さい。 | 0x8004020D | 525
VFW_E_BADALIGN | 無効なアラインメントが指定された。 | 0x8004020E | 526
VFW_E_ALREADY_COMMITTED | フィルタがアクティブのときは割り当て済みメモリを変更できない。 | 0x8004020F | 527
VFW_E_BUFFERS_OUTSTANDING | 1 つまたは複数のバッファがアクティブである。 | 0x80040210 | 528
VFW_E_NOT_COMMITTED | アロケータがアクティブでないときはサンプルを割り当てることができない。 | 0x80040211 | 529
VFW_E_SIZENOTSET | サイズが設定されていないので、メモリを割り当てることができない。 | 0x80040212 | 530
VFW_E_NO_CLOCK | クロックが定義されていないので、同期化を行えない。 | 0x80040213 | 531
VFW_E_NO_SINK | 品質シンクが定義されていないので、品質メッセージを送信できない。 | 0x80040214 | 532
VFW_E_NO_INTERFACE | 必要なインターフェイスが実装されていない。 | 0x80040215 | 533
VFW_E_NOT_FOUND | オブジェクトまたは名前が見つからなかった。 | 0x80040216 | 534
VFW_E_CANNOT_CONNECT | 接続を確立する中間フィルタの組み合わせが見つからなかった。 | 0x80040217 | 535
VFW_E_CANNOT_RENDER | ストリームをレンダリングするフィルタの組み合わせが見つからない。 | 0x80040218 | 536
VFW_E_CHANGING_FORMAT | フォーマットを動的に変更できない。 | 0x80040219 | 537
VFW_E_NO_COLOR_KEY_SET | カラー キーが設定されていない。 | 0x8004021A | 538
VFW_E_NOT_OVERLAY_CONNECTION | 現在のピン接続はIOverlay 転送を使用していない。 | 0x8004021B | 539
VFW_E_NOT_SAMPLE_CONNECTION | 現在のピン接続は IMemInputPin 転送を使用していない。 | 0x8004021C | 540
VFW_E_PALETTE_SET | カラー キーを設定すると、既に設定されているパレットと矛盾する可能性がある。 | 0x8004021D | 541
VFW_E_COLOR_KEY_SET | パレットを設定すると、既に設定されているカラー キーと矛盾する可能性がある。 | 0x8004021E | 542
VFW_E_NO_COLOR_KEY_FOUND | 一致するカラー キーがない。 | 0x8004021F | 543
VFW_E_NO_PALETTE_AVAILABLE | パレットが利用不可能。 | 0x80040220 | 544
VFW_E_NO_DISPLAY_PALETTE | ディスプレイはパレットを使用しない。 | 0x80040221 | 545
VFW_E_TOO_MANY_COLORS | 現在のディスプレイ設定に対して色が多すぎる。 | 0x80040222 | 546
VFW_E_STATE_CHANGED | サンプルの処理を待っている間に状態が変化した。 | 0x80040223 | 547
VFW_E_NOT_STOPPED | フィルタが停止されていないので、処理を実行できない。 | 0x80040224 | 548
VFW_E_NOT_PAUSED | フィルタがポーズされていないので、処理を実行できない。 | 0x80040225 | 549
VFW_E_NOT_RUNNING | フィルタが実行されていないので、処理を実行できない。 | 0x80040226 | 550
VFW_E_WRONG_STATE | フィルタの状態に誤りがあるので、処理を実行できない。 | 0x80040227 | 551
VFW_E_START_TIME_AFTER_END | サンプルの開始タイムがサンプルの終了タイムの後になっている。 | 0x80040228 | 552
VFW_E_INVALID_RECT | 提供された矩形が無効である。 | 0x80040229 | 553
VFW_E_TYPE_NOT_ACCEPTED | このピンは、提供されたメディア タイプを使用できない。 | 0x8004022A | 554
VFW_E_SAMPLE_REJECTED | このサンプルはレンダリングできない。 | 0x8004022B | 555
VFW_E_SAMPLE_REJECTED_EOS | ストリームの終わりに到達しているので、このサンプルをレンダリングできない。 | 0x8004022C | 556
VFW_E_DUPLICATE_NAME | 同じ名前のフィルタを追加しようとしたが失敗した。 | 0x8004022D | 557
VFW_S_DUPLICATE_NAME | 同じ名前のフィルタを追加しようとしたところ、名前を変更して処理が成功した。 | 0x0004022D | 557
VFW_E_TIMEOUT | タイムアウト期間が過ぎた。 | 0x8004022E | 558
VFW_E_INVALID_FILE_FORMAT | フォーマットが無効である。 | 0x8004022F | 559
VFW_E_ENUM_OUT_OF_RANGE | リストが使い果たされた。 | 0x80040230 | 560
VFW_E_CIRCULAR_GRAPH | フィルタ グラフが繰り返しである。 | 0x80040231 | 561
VFW_E_NOT_ALLOWED_TO_SAVE | この状態での更新は許されない。 | 0x80040232 | 562
VFW_E_TIME_ALREADY_PASSED | 過去のタイムのコマンドをキューに入れようとした。 | 0x80040233 | 563
VFW_E_ALREADY_CANCELLED | キューに入れられたコマンドは既にキャンセルされていた。 | 0x80040234 | 564
VFW_E_CORRUPT_GRAPH_FILE | ファイルが壊れているのでレンダリングできない。 | 0x80040235 | 565
VFW_E_ADVISE_ALREADY_SET | IOverlay アドバイズ リンクが既に存在している。 | 0x80040236 | 566
VFW_S_STATE_INTERMEDIATE | 状態の移行が完了していない。 | 0x00040237 | 567
VFW_E_NO_MODEX_AVAILABLE | フルスクリーン モードは利用できない。 | 0x80040238 | 568
VFW_E_NO_ADVISE_SET | このアドバイズは正常に設定されていないのでキャンセルできない。 | 0x80040239 | 569
VFW_E_NO_FULLSCREEN | フルスクリーン モードは利用できない。 | 0x8004023A | 570
VFW_E_IN_FULLSCREEN_MODE | フルスクリーン モードでは IVideoWindow メソッドを呼び出せない。 | 0x8004023B | 571
VFW_E_UNKNOWN_FILE_TYPE | このファイルのメディア タイプが認識されない。 | 0x80040240 | 576
VFW_E_CANNOT_LOAD_SOURCE_FILTER | このファイルのソース フィルタをロードできない。 | 0x80040241 | 577
VFW_S_PARTIAL_RENDER | このムービーのいくつかのストリームが、サポートされていないフォーマットを持つ。 | 0x00040242 | 578
VFW_E_FILE_TOO_SHORT | ファイルが不完全である。 | 0x80040243 | 579
VFW_E_INVALID_FILE_VERSION | ファイルのバージョン番号が無効である。 | 0x80040244 | 580
VFW_S_SOME_DATA_IGNORED | ファイルにいくつかの使用されていないプロパティ設定が含まれている。 | 0x00040245 | 581
VFW_S_CONNECTIONS_DEFERRED | 一部の接続が失敗して遅延された。 | 0x00040246 | 582
VFW_E_INVALID_CLSID | このファイルは壊れている。無効なクラス識別子が含まれている。 | 0x80040247 | 583
VFW_E_INVALID_MEDIA_TYPE | このファイルは壊れている。無効なメディア タイプが含まれている。 | 0x80040248 | 584
VFW_E_SAMPLE_TIME_NOT_SET | このサンプルにはタイム スタンプが設定されていない。 | 0x80040249 | 585
VFW_S_RESOURCE_NOT_NEEDED | 指定されたリソースはもはや必要ない。 | 0x00040250 | 592
VFW_E_MEDIA_TIME_NOT_SET | このサンプルにはメディア タイムが設定されていない。 | 0x80040251 | 593
VFW_E_NO_TIME_FORMAT_SET | メディア タイム フォーマットが選択されていない。 | 0x80040252 | 594
VFW_E_MONO_AUDIO_HW | オーディオ デバイスがモノラル専用なので、バランスを変更できない。 | 0x80040253 | 595
VFW_S_MEDIA_TYPE_IGNORED | 持続グラフのメディア タイプに接続できない。 | 0x00040254 | 596
VFW_E_NO_DECOMPRESSOR | ビデオ ストリームを再生できない。適切なデコンプレッサが見つからなかった。 | 0x80040255 | 597
VFW_E_NO_AUDIO_HARDWARE | オーディオ ストリームを再生できない。オーディオ ハードウェアが利用できない、またはハードウェアがサポートされていない。 | 0x80040256 | 598
VFW_S_VIDEO_NOT_RENDERED | ビデオ ストリームを再生できない。適切なレンダラが見つからなかった。 | 0x00040257 | 599
VFW_S_AUDIO_NOT_RENDERED | オーディオ ストリームを再生できない。適切なレンダラが見つからなかった。 | 0x00040258 | 600
VFW_E_RPZA | ビデオ ストリームを再生できない。フォーマット 'RPZA' はサポートされていない。 | 0x80040259 | 601
VFW_S_RPZA | ビデオ ストリームを再生できない。フォーマット 'RPZA' はサポートされていない。 | 0x0004025A | 602
VFW_E_PROCESSOR_NOT_SUITABLE | DirectShow はこのプロセッサ上で MPEG ムービーを再生できない。 | 0x8004025B | 603
VFW_E_UNSUPPORTED_AUDIO | オーディオ ストリームを再生できない。オーディオ フォーマットはサポートされていない。 | 0x8004025C | 604
VFW_E_UNSUPPORTED_VIDEO | ビデオ ストリームを再生できない。ビデオ フォーマットはサポートされていない。 | 0x8004025D | 605
VFW_E_MPEG_NOT_CONSTRAINED | このビデオ ストリームは規格に準拠していないので DirectShow で再生できない。 | 0x8004025E | 606
VFW_E_NOT_IN_GRAPH | フィルタ グラフに存在しないオブジェクトに要求された関数を実行できない。 | 0x8004025F | 607
VFW_S_ESTIMATED | 返された値は予測値である。値の正確さを保証できない。 | 0x00040260 | 608
VFW_E_NO_TIME_FORMAT | オブジェクトのタイム フォーマットにアクセスできない。 | 0x80040261 | 609
VFW_E_READ_ONLY | ストリームが読み出し専用で、フィルタによってデータが変更されているので、接続を確立できない。 | 0x80040262 | 610
VFW_S_RESERVED | この成功コードは、DirectShow の内部処理用に予約されている。 | 0x00040263 | 611
VFW_E_BUFFER_UNDERFLOW | バッファが十分に満たされていない。 | 0x80040264 | 612
VFW_E_UNSUPPORTED_STREAM | ファイルを再生できない。フォーマットがサポートされていない。 | 0x80040265 | 613
VFW_E_NO_TRANSPORT | 同じ転送をサポートしていないのでピン同士を接続できない。 | 0x80040266 | 614
VFW_S_STREAM_OFF | ストリームがオフになった。 | 0x00040267 | 615
VFW_S_CANT_CUE | グラフ フィルタはアクティブであるが、データを出力できない。「IMediaFilter::GetState」を参照すること。 | 0x00040268 | 616
VFW_E_BAD_VIDEOCD | デバイスがビデオ CD を正常に読み出せない、またはビデオ CD のデータが壊れている。 | 0x80040269 | 617
VFW_S_NO_STOP_TIME | サンプルに終了タイムではなく開始タイムが設定されていた。この場合、返される終了タイムは開始タイムに 1 を加えた値に設定される。 | 0x80040270 | 624
VFW_E_OUT_OF_VIDEO_MEMORY | このディスプレイ解像度と色数に対してビデオ メモリが不十分である。解像度を低くすると良い。 | 0x80040271 | 625
VFW_E_VP_NEGOTIATION_FAILED | ビデオ ポート接続ネゴシエーション プロセスが失敗した。 | 0x80040272 | 626
VFW_E_DDRAW_CAPS_NOT_SUITABLE | Microsoft® DirectDraw® がインストールされていない、またはビデオ カードの能力が適切でない。ディスプレイが 16 色モードでないことを確認すること。 | 0x80040273 | 627
VFW_E_NO_VP_HARDWARE | ビデオ ポート ハードウェアが利用できない、またはハードウェアが応答しない。 | 0x80040274 | 628
VFW_E_NO_CAPTURE_HARDWARE | キャプチャ ハードウェアが利用できない、またはハードウェアが応答しない。 | 0x80040275 | 629
VFW_E_DVD_OPERATION_INHIBITED | この時点でこのユーザー操作は DVD コンテンツによって禁止されている。 | 0x80040276 | 630
VFW_E_DVD_INVALIDDOMAIN | 現在のドメインでこの処理は許可されていない。 | 0x80040277 | 631
VFW_E_DVD_NO_BUTTON | 要求されたボタンが利用できない。 | 0x80040278 | 632
VFW_E_DVD_GRAPHNOTREADY | DVD-Video 再生グラフが構築されていない。 | 0x80040279 | 633
VFW_E_DVD_RENDERFAIL | DVD-Video 再生グラフの構築が失敗した。 | 0x8004027A | 634
VFW_E_DVD_DECNOTENOUGH | デコーダが不十分だったために、DVD-Video 再生グラフが構築できなかった。 | 0x8004027B | 635
VFW_E_DVD_NOT_IN_KARAOKE_MODE | DVD ナビゲータはカラオケ モードではない。 | 0x8004028B | 651
VFW_E_FRAME_STEP_UNSUPPORTED | コマ送りがサポートされていない。 | 0x8004028E | 654
VFW_E_PIN_ALREADY_BLOCKED_ON_THIS_THREAD | ピンは既に呼び出し側スレッドでブロックされている。 | 0x80040293 | 659
VFW_E_PIN_ALREADY_BLOCKED | ピンは既にほかのスレッドでブロックされている。 | 0x80040294 | 660
VFW_E_CERTIFICATION_FAILURE | このフィルタの使用はソフトウェア キーによって制限されている。アプリケーションは、フィルタをロック解除しなければならない。 | 0x80040295 | 661
CTL_E_CANTSAVEFILETOTEMP | ファイルは TEMP ディレクトリに保存できない。 | 0x800A02DF | 735
CTL_E_SEARCHTEXTNOTFOUND | 検索対象のテキストが見つからない。 | 0x800A02E8 | 744
CTL_E_REPLACEMENTSTOOLONG | テキストの置換が長すぎる。 | 0x800A02EA | 746
VFW_E_BAD_KEY | レジストリ エントリが壊れている。 | 0x800403F2 | 1010

DirectShow Editing Services に固有の HRESULT 値

上記の値に加え、DirectShow Editing Services では以下の HRESULT 値が定義されている。

戻りコード | 説明 | 16 進値 | 10 進値 (LOWORD)
S_WARN_OUTPUTRESET | グラフのレンダリング部分が削除された。アプリケーションはこれを再構築しなければならない。 | 0x00040404 | 1028
E_NOTINTREE | オブジェクトがタイムラインに含まれていない。 | 0x80040400 | 1024
E_RENDER_ENGINE_IS_BROKEN | プロジェクトが正常にレンダリングされなかったので、処理が失敗した。 | 0x80040401 | 1025
E_MUST_INIT_RENDERER | レンダリング エンジンが起動されていない。 | 0x80040402 | 1026
E_NOTDETERMINED | 要求された値を判定できない。 | 0x80040403 | 1027
E_NO_TIMELINE | タイムライン オブジェクトがない。 | 0x80040404 | 1028


イベント通知コード

Microsoft® DirectShow® では、システム定義イベントをサポートしている。フィルタは、IMediaEventSink::Notify メソッドを使ってフィルタ グラフ マネージャにイベントを渡す。フィルタ グラフ マネージャは、一部のイベントを処理し、それ以外のイベントをアプリケーションに渡す。アプリケーションは、IMediaEvent::GetEvent メソッドを呼び出すことで、イベントを取得する。詳細については、「DirectShow でのイベント通知」を参照すること。

ここでは、DVD 固有イベント以外の DirectShow イベントについて説明する。DVD に固有のイベントについては、「DVD イベント通知コード」を参照すること。

ここでは、イベントごとにイベント コードと 2 つのイベント パラメータの意味を示す。また、フィルタ グラフ マネージャによるイベントの既定処理がある場合は、それについても記述する。既定処理を無効にするには、アプリケーションで IMediaEvent::CancelDefaultHandling を呼び出す。

イベント通知コードは、ヘッダー ファイルの Evcode.h および Audevcod.h に定義されている。

イベント通知コード | 説明
EC_ACTIVATE | ビデオ ウィンドウがアクティブまたは非アクティブ。
EC_BUFFERING_DATA | グラフがデータをバッファリングしている、またはデータのバッファリングを停止した。
EC_CLOCK_CHANGED | 基準クロックが変更された。
EC_COMPLETE | 特定のストリームからのすべてのデータをレンダリングし終えた。
EC_DEVICE_LOST | プラグ & プレイ デバイスが取り外された、または再び使用できるようになった。
EC_DISPLAY_CHANGED | 表示モードが変更された。
EC_END_OF_SEGMENT | セグメントの終わりに到達した。
EC_ERROR_STILLPLAYING | グラフを実行する非同期コマンドが失敗した。
EC_ERRORABORT | エラーのため操作が中止された。
EC_FULLSCREEN_LOST | ビデオ レンダラがフルスクリーン モードから抜けようとしている。
EC_GRAPH_CHANGED | フィルタ グラフが変更された。
EC_NEED_RESTART | フィルタがグラフの再開を要求している。
EC_NOTIFY_WINDOW | フィルタにビデオ レンダラのウィンドウを通知する。
EC_OLE_EVENT | フィルタがアプリケーションにテキスト文字列を渡している。
EC_OPENING_FILE | グラフがファイルを開いている、またはファイルを開き終えた。
EC_PALETTE_CHANGED | ビデオ パレットが変更された。
EC_PAUSED | ポーズ要求が完了した。
EC_QUALITY_CHANGE | 品質管理のため、グラフがサンプルを削除した。
EC_REPAINT | ビデオ レンダラが再描画を要求している。
EC_SEGMENT_STARTED | 新しいセグメントが開始した。
EC_SHUTTING_DOWN | フィルタ グラフが破棄前にシャットダウンしている。
EC_SNDDEV_IN_ERROR | 入力ピンでオーディオ デバイス エラーが発生した。
EC_SNDDEV_OUT_ERROR | 出力ピンでオーディオ デバイス エラーが発生した。
EC_STARVATION | フィルタは十分なデータを受け取っていない。
EC_STEP_COMPLETE | コマ送りを実行しているフィルタが、指定数のコマ送りを完了した。
EC_STREAM_CONTROL_STARTED | ストリーム制御開始コマンドが有効になった。
EC_STREAM_CONTROL_STOPPED | ストリーム制御停止コマンドが有効になった。
EC_STREAM_ERROR_STILLPLAYING | ストリーム内にエラーが発生した。ストリームは引き続き再生中である。
EC_STREAM_ERROR_STOPPED | エラーのためストリームが停止した。
EC_USERABORT | ユーザーが再生を強制終了した。
EC_VIDEO_SIZE_CHANGED | ネイティブ ビデオ サイズが変更された。
EC_WINDOW_DESTROYED | ビデオ レンダラが破棄またはグラフから削除された。

EC_ACTIVATE

ビデオ ウィンドウがアクティブまたは非アクティブ。

パラメータ

lParam1
ウィンドウがアクティブになった場合は TRUE、ウィンドウが非アクティブになった場合は FALSE。
lParam2
レンダラの IBaseFilter インターフェイスへのポインタ。

既定処理

フィルタ グラフ マネージャは、IResourceManager インターフェイスを介してフォーカスを設定する。アプリケーションにはイベント通知を送信しない。

注意

ビデオ レンダラは、ウィンドウがアクティブまたは非アクティブにされたとき (ACTIVATEAPP を受け取ったとき) にこのイベントを送信する。ウィンドウのアクティブと非アクティブが発生するのは、ウィンドウがフォーカスを取得または喪失したこと、またはレンダラがフルスクリーン モードとウィンドウ モードを切り替えたことが原因である。

このイベントにより、フィルタ グラフ マネージャは、オーディオ デバイスなど、ウィンドウ フォーカスに依存するリソースを割り当てることができる。

EC_BUFFERING_DATA

イベント通知コード

グラフがデータをバッファリングしている、またはデータのバッファリングを停止した。

パラメータ

lParam1
グラフがバッファリングを開始する場合は TRUE、グラフがバッファリングを停止する場合は FALSE。
lParam2
ゼロ。

既定処理

なし。

注意

外部ソースからで多をバッファリングする必要がある場合に、フィルタはこのイベントを送信する(ネットワークからデータを読み込む場合など)。アプリケーションはこのイベントを使ってユーザー インターフェイスを調整する。

EC_CLOCK_CHANGED

イベント通知コード

基準クロックが変更された。

パラメータ

lParam1
ゼロ。
lParam2
ゼロ。

既定処理

なし。

注意

フィルタ グラフの IMediaFilter::SetSyncSource メソッドが呼び出されると、フィルタ グラフはこのイベントを送信する。

EC_COMPLETE

イベント通知コード

特定のストリームからのすべてのデータをレンダリングし終えた。

パラメータ

lParam1
HRESULT 値。S_OK でもよい。
lParam2
ゼロ、またはレンダラの IBaseFilter インターフェイスへのポインタ。

既定処理

既定では、フィルタ グラフ マネージャはこのイベントをアプリケーションには転送しない。ただし、グラフ内のすべてのストリームが EC_COMPLETE を報告した後、フィルタ グラフ マネージャはアプリケーションに対して別に EC_COMPLETE イベントを送信する。

このイベントの既定処理が無効化されると、アプリケーションはレンダラからすべての EC_COMPLETE イベントを受け取る。

注意

レンダリング フィルタはエンドオブストリーム通知を受け取ると、このイベントを送信する(エンドオブストリームは IPin::EndOfStream メソッドを介して通知済になる)。フィルタは各ストリームに対して EC_COMPLETE イベントを 1 回だけ送信する。フィルタはこのイベントを送信する前に、保留中のサンプルをすべて処理する必要がある。レンダラを停止すると、キャッシュ内のエンドオブストリーム状態がすべてリセットされる。

フィルタは lParam2 パラメータを IBaseFilter ポインタに設定する。既定処理が有効な場合、フィルタ グラフ マネージャはこのパラメータをゼロに設定する。

EC_DEVICE_LOST

イベント通知コード

プラグ & プレイ デバイスが取り外された、または再び使用できるようになった。

パラメータ

lParam1
デバイスを表すフィルタの IUnknown インターフェイスへのポインタ。
lParam2
デバイスが取り外された場合はゼロ、デバイスが再び使用可能になった場合は 1。

既定処理

なし。

注意

デバイスが再び使用可能になると、デバイス フィルタの前の状態はもはや有効ではなくなる。アプリケーションがデバイスを使用するためには、グラフを再構築する必要がある。

EC_DISPLAY_CHANGED

イベント通知コード

表示モードが変更された。

パラメータ

lParam1
ビデオ レンダラの入力ピンの IPin インターフェイスへのポインタ、またはゼロ。
lParam2
ゼロ。

既定処理

フィルタ グラフ マネージャはグラフを一時的に停止してから、ビデオ レンダラの接続解除と再接続を行う。アプリケーションにはイベントを送信しない。

注意

ビデオ レンダラは、WM_DISPLAYCHANGE メッセージへの応答としてこのイベントを送信できる。WM_DISPLAYCHANGE メッセージは、ユーザーがディスプレイ解像度を変更したことを示す。

ピン接続中に、大部分のビデオ レンダラは現在のディスプレイ モードに基づいてフォーマットを選択する。ディスプレイ モードが変更されると、ビデオ レンダラは別のフォーマットを選択しなければならないことが多い。このメッセージを送信することで、レンダラは再接続する必要があることをフィルタ グラフ マネージャに対して通知する。再接続中に、レンダラは新しいフォーマットを選択できる。再接続に失敗すると、フィルタ グラフ マネージャはアプリケーションに対して EC_ERRORABORT イベントを送信する。

EC_END_OF_SEGMENT

イベント通知コード

セグメントの終わりに到達した。

パラメータ

lParam1
セグメントの開始以降の累積ストリーム時間を示す REFERENCE_TIME 値へのポインタ。
lParam2
セグメント番号 (ゼロから開始) を示す DWORD 値。

既定処理

フィルタ グラフ マネージャは、EC_END_OF_SEGMENT イベントの番号と EC_SEGMENT_STARTED イベントの番号を比較する。一致する場合は、EC_END_OF_SEGMENT イベントをアプリケーションに転送する。

注意

このイベント コードはシームレス ルーピングをサポートしている。IMediaSeeking::SetPositions メソッドの呼び出しに AM_SEEKING_Segment フラグが設定されている場合、ソース フィルタは IPin::EndOfStream を呼び出す代わりに、このイベント コードを送信する。

EC_ERROR_STILLPLAYING

イベント通知コード

グラフを実行する非同期コマンドが失敗した。

パラメータ

lParam1
失敗した処理の HRESULT 値。
lParam2
ゼロ。

既定処理

なし。

注意

フィルタ グラフ マネージャが非同期実行コマンドを発行し、それが失敗した場合、アプリケーションにこのイベントを送信する。グラフは実行中状態のままになる。基底となるフィルタの状態は不定である。あるフィルタは実行中である可能性もあるが、別のフィルタは違う可能性もある。

EC_ERRORABORT

イベント通知コード

エラーのため操作が中止された。

パラメータ

lParam1
失敗した処理の HRESULT 値。
lParam2
ゼロ。

既定処理

なし。

EC_FULLSCREEN_LOST

イベント通知コード

ビデオ レンダラがフルスクリーン モードから抜けようとしている。

パラメータ

lParam1
ゼロ。
lParam2
ビデオ レンダラの IBaseFilter インターフェイスへのポインタ、または NULL。

既定処理

なし。

注意

フル スクリーン レンダラがアクティブでなくなると、このイベントを送信する。別のビデオ レンダラがフルスクリーン モードから抜けると、フィルタ グラフ マネージャは、レンダラからの EC_ACTIVATE イベントへの応答として、このイベントを送信する。

EC_GRAPH_CHANGED

イベント通知コード

フィルタ グラフが変更された。

パラメータ

lParam1
ゼロ。
lParam2
ゼロ。

既定処理

なし。

注意

このイベント コードはデバッグ用である。すべてのグラフの変更で送信されるとは限らない。

EC_NEED_RESTART

イベント通知コード

フィルタがグラフの再起動を要求している。

パラメータ

lParam1
ゼロ。
lParam2
ゼロ。

既定処理

フィルタ グラフ マネージャはグラフをポーズして再開する。アプリケーションにはイベントを送信しない。

注意

フィルタがストリーム半ばのサンプルを拒絶する場合、アップストリーム ピンがサンプルの配信を停止する。フィルタは、このイベントを送信することでストリームを再開できる。たとえば、オーディオ レンダラは、ビデオ ウィンドウがフォーカスを失ったためにサウンド デバイスへのアクセスを失うことがある。その時点で、オーディオ レンダラはサンプルの拒絶を開始する。サウンド デバイスへのアクセスを再取得したら、このイベントを送信して、オーディオ ストリームを再開する。

EC_NOTIFY_WINDOW

イベント通知コード

フィルタにビデオ レンダラのウィンドウを通知する。

パラメータ

lParam1
ウィンドウのハンドル。
lParam2
ゼロ。

既定処理

このイベントは DirectShow で内部的に使用される。フィルタ グラフ マネージャはこのイベントをアプリケーションには送信しない。アプリケーションは、このイベントの既定処理をオーバーライドできない。

注意

ビデオ レンダラが接続されたら、レンダラは、アップストリーム出力ピンが IMediaEventSink インターフェイスをサポートするかどうかをチェックする。サポートされる場合、レンダラはこのイベントをアップストリーム フィルタに送信する。

EC_OLE_EVENT

イベント通知コード

フィルタがアプリケーションにテキスト文字列を渡している。

パラメータ

lParam1
BSTR 型の文字列。
lParam2
BSTR 型の文字列。

既定処理

なし。

注意

規約により、最初のパラメータにはタイプ情報 (Text など)を格納し、2 番目のパラメータにはテキスト文字列を格納する。

EC_OPENING_FILE

イベント通知コード

グラフがファイルを開いている、またはファイルを開き終えた。

パラメータ

lParam1
グラフがファイルのオープンを開始する場合は TRUE、グラフがファイルのオープンを行っていない場合は FALSE。
lParam2
ゼロ。

既定処理

なし。

注意

フィルタは、ファイルを開くのに時間がかかる場合、このイベントを送信できる(ファイルがネットワーク上にある場合など)。アプリケーションはこのイベントを使ってユーザー インターフェイスを調整する。

現在のところ、DirectShow に含まれるフィルタはいずれも、このイベントを送信しない。

EC_PALETTE_CHANGED

イベント通知コード

ビデオ パレットが変更された。

パラメータ

lParam1
ゼロ。
lParam2
ゼロ。

既定処理

なし。

注意

ビデオ レンダラは、ストリーム内でパレットの変更を検出した場合、このイベントを送信する。

EC_PAUSED

イベント通知コード

ポーズ要求が完了した。

パラメータ

lParam1
移行結果を示す HRESULT 値。この値が S_OK である場合、フィルタ グラフは現在ポーズ状態にある。
lParam2
ゼロ。

既定処理

なし。

注意

フィルタ グラフ マネージャは、非同期ポーズ コマンドが完了したときに、このイベントを送信する。

EC_QUALITY_CHANGE

イベント通知コード

品質管理のため、グラフがサンプルを削除した。

パラメータ

lParam1
ゼロ。
lParam2
ゼロ。

既定処理

なし。

注意

フィルタは、品質コントロール メッセージへの応答としてサンプルを削除する場合、このイベントを送信する。イベントが送信されるのは、品質レベルを調整する場合のみであり、サンプルを削除するたびに送信されるわけではない。詳細については、「品質コントロールの管理」を参照すること。

EC_REPAINT

イベント通知コード

ビデオ レンダラが再描画を要求している。

パラメータ

lParam1
ビデオ レンダラの入力ピンの IPin インターフェイスへのポインタ、または NULL。
lParam2
ゼロ。

既定処理

多くの場合、lParam1 パラメータは、ビデオ レンダラの入力ピンを指定する。この場合、フィルタ グラフ マネージャは、そのピンに接続された出力ピンを探し、IMediaEventSink インターフェイスがあるかどうかを問い合わせる。出力ピンが IMediaEventSink をサポートする場合、フィルタ グラフ マネージャは EC_REPAINT イベント コードを指定して IMediaEventSink::Notify を呼び出す。これにより、アップストリーム フィルタは、最後のサンプルを再送信する機会を得ることができる。

lParam1 が NULL である場合、出力ピンが IMediaEventSink をサポートしない場合、または Notify メソッドが失敗した場合は、フィルタ グラフ マネージャ自体が EC_REPAINT イベントを処理する。その動作は、グラフの状態により次のいずれかになる。

  • 実行中:イベントを無視する(レンダラがストリーム内の次のサンプルを受信する)。
  • ポーズ:グラフの現在位置をシークする。その際に、フィルタはフラッシュされ、データは再び待ち行列に入れられる。
  • 停止:グラフをポーズおよび停止する。その際にデータは再び待ち行列に入れられる。

既定では、フィルタ グラフ マネージャはこのイベントをアプリケーションには送信しない。

注意

ビデオ レンダラは、WM_PAINT メッセージを受け取り、表示するデータがないときに、このメッセージを送信する。

EC_SEGMENT_STARTED

イベント通知コード

新しいセグメントが開始した。

パラメータ

lParam1
セグメントの開始以降の累積ストリーム時間を示す REFERENCE_TIME 値へのポインタ。
lParam2
セグメント番号 (ゼロから開始) を示す DWORD 値。

既定処理

このイベント通知はアプリケーションに送信されない。

注意

フィルタがセグメントの最後で EC_END_OF_SEGMENT を送信する予定である場合は、セグメントの最初でこのイベントを送信する。フィルタ グラフ マネージャは、このイベント通知を使って、セグメントの最後でいくつの EC_END_OF_SEGMENT 通知を受け取ることになるかを計算する。

既定では、フィルタはセグメントの最後に EC_END_OF_SEGMENT イベントを送信しないので、このイベントを送信するべきではない。詳細については、「AM_SEEKING_Segment」および「IMediaSeeking::SetPositions」を参照すること。

EC_SHUTTING_DOWN

イベント通知コード

フィルタ グラフが破棄前にシャットダウンしている。

パラメータ

lParam1
ゼロ。
lParam2
ゼロ。

既定処理

このイベント通知はアプリケーションに送信されない。フィルタ グラフ マネージャは、PID に対してこのイベントを送信し、グラフがシャットダウンすることを通知するアプリケーションは、このイベントの既定処理をオーバーライドできない。

EC_SNDDEV_IN_ERROR

イベント通知コード

入力ピンでオーディオ デバイス エラーが発生した。

パラメータ

lParam1
エラーが発生したときにデバイスがどのようにアクセスされていたかを示す、SNDDEV_ERR 列挙型の DWORD 値。
lParam2
サウンド デバイス呼び出しから返されたエラーを示す DWORD 値。

既定処理

なし。

EC_SNDDEV_OUT_ERROR

イベント通知コード

出力ピンでオーディオ デバイス エラーが発生した。

パラメータ

lParam1
エラーが発生したときにデバイスがどのようにアクセスされていたかを示す、SNDDEV_ERR 列挙型の DWORD 値。
lParam2
サウンド デバイス呼び出しから返されたエラーを示す DWORD 値。

既定処理

なし。

EC_STARVATION

イベント通知コード

フィルタは十分なデータを受け取っていない。

パラメータ

lParam1
ゼロ。
lParam2
ゼロ。

既定処理

このイベントはアプリケーションに送信されない。フィルタ グラフが実行中である場合、フィルタ グラフ マネージャはグラフをポーズし、ポーズが完了するまで待機する。その後、グラフを再び実行する。このイベントを送信するフィルタがポーズ状態への移行を完了するには、再開するのに十分なデータを受け取らなければならない。フィルタ グラフが実行中でない場合、フィルタ グラフ マネージャはこのイベントを無視する。

注意

到着するデータ量が少なすぎる場合に、パーサーまたはソース フィルタがこのイベントを送信できる。

EC_STEP_COMPLETE

イベント通知コード

コマ送りを実行しているフィルタが、指定数のコマ送りを完了した。

パラメータ

lParam1
ゼロ。
lParam2
ゼロ。

既定処理

フィルタ グラフ マネージャは、グラフをポーズし、イベントをアプリケーションに渡す。

関連項目

IVideoFrameStep::Step

EC_STREAM_CONTROL_STARTED

イベント通知コード

ストリーム制御停止コマンドが有効になった。

パラメータ

pSender
ストリームを開始したピンの IPin インターフェイスへのポインタ。
dwCookie
ユーザー定義の DWORD 値。

既定処理

なし。

注意

フィルタは、IAMStreamControl::StartAt メソッドへの応答としてこのイベントを送信する。このメソッドは、ストリーム送信を開始するピンの基準時間を指定する。ストリーム送信が実際に開始された時点で、フィルタはこのイベントを送信する。

pSender パラメータは、開始コマンドを実行するピンを指定する。実装方法により、このピンは、StartAt 呼び出しを受け取ったピンとは異なる場合がある。

dwCookie パラメータは、StartAt メソッドでアプリケーションにより指定される。このパラメータを使うと、アプリケーションは StartAt メソッドの複数呼び出しを追跡できる。

EC_STREAM_CONTROL_STOPPED

イベント通知コード

ストリーム制御停止コマンドが有効になった。

パラメータ

pSender
ストリームを停止したピンの IPin インターフェイスへのポインタ。
dwCookie
ユーザー定義の DWORD 値。

既定処理

なし。

注意

フィルタは、IAMStreamControl::StopAt メソッドへの応答としてこのイベントを送信する。このメソッドは、ストリーム送信を停止するピンの基準時間を指定する。ストリーム送信が実際に停止された時点で、フィルタはこのイベントを送信する。

pSender パラメータは、停止コマンドを実行するピンを指定する。実装方法により、このピンは、StopAt 呼び出しを受け取ったピンとは異なる場合がある。

dwCookie パラメータは、StopAt メソッドでアプリケーションにより指定される。このパラメータを使うと、アプリケーションは StopAt メソッドの複数呼び出しを追跡できる。

EC_STREAM_ERROR_STILLPLAYING

イベント通知コード

ストリーム内にエラーが発生した。ストリームは引き続き再生中である。

パラメータ

lParam1
失敗した処理の HRESULT 値。
lParam2
DWORD 値、通常はゼロ。

既定処理

なし。アプリケーションはグラフを停止するかどうか決定しなければならない。

EC_STREAM_ERROR_STOPPED

イベント通知コード

エラーのためストリームが停止した。

パラメータ

lParam1
失敗した処理の HRESULT 値。
lParam2
DWORD 値、通常はゼロ。

既定処理

なし。

EC_USERABORT

イベント通知コード

ユーザーが再生を強制終了した。

パラメータ

lParam1
ゼロ。
lParam2
ゼロ。

既定処理

なし。アプリケーションはグラフを停止するかどうか決定しなければならない。

注意

このイベント コードは、ユーザーが通常のグラフ再生を強制終了したことを通知する。たとえば、ビデオ レンダラは、ユーザーがビデオ ウィンドウを閉じた場合、このイベントを送信する。

このイベントの送信後、フィルタが停止してリセットされるまで、フィルタはすべてのサンプルを拒絶し、EC_REPAINT イベントを送信しない。

EC_VIDEO_SIZE_CHANGED

イベント通知コード

ネイティブ ビデオ サイズが変更された。

パラメータ

lParam1
下位 WORD が新しい幅をピクセル単位で指定し、上位 WORD が新しい高さをピクセル単位で指定する。
lParam2
ゼロ。

既定処理

なし。

注意

ビデオ レンダラは、ネイティブ ビデオ サイズの変更を検出した場合、このイベントを送信する。

EC_WINDOW_DESTROYED

イベント通知コード

ビデオ レンダラが破棄またはグラフから削除された。

パラメータ

lParam1
ビデオ レンダラの IBaseFilter インターフェイスへのポインタ。
lParam2
ゼロ。

既定処理

フィルタ グラフ マネージャは、IResourceManager インターフェイスを介し、このウィンドウとフォーカスを解放する。アプリケーションにはイベント通知を送信しない。

注意

ビデオ レンダラは、フィルタ グラフを IBaseFilter::JoinFilterGraph メソッドに残すときに、このイベントを送信する(フィルタが破棄される時点で、フィルタ グラフ マネージャも破棄される可能性があるので、フィルタの破棄時にこのイベントを送信するのでは遅すぎる)。

このイベントにより、ほかのフィルタは、オーディオ デバイスなど、ウィンドウ フォーカスに依存するリソースを取得できる。


フィルタ カテゴリ

次の表は、フィルタ カテゴリの CLSID の一覧を示している。特定のカテゴリのフィルタを列挙するには、該当する CLSID を ICreateDevEnum::CreateClassEnumerator メソッドに渡す。詳細については、「デバイスとフィルタの列挙」を参照すること。

これらのカテゴリは、[Graph] メニューの [Insert Filters] を選択したときにも GraphEdit に表示される。詳細については、「GraphEdit によるグラフ構築のシミュレーション」を参照すること。

CLSID | 説明
CLSID_AudioInputDeviceCategory | オーディオ キャプチャ フィルタ。
CLSID_AudioCompressorCategory | オーディオ コンプレッサ、オーディオ エンコーダ。
CLSID_AudioRendererCategory | オーディオ レンダラ。
CLSID_LegacyAmFilterCategory | デコーダを含むその他のフィルタ。
CLSID_MidiRendererCategory | MIDI レンダラ。
CLSID_VideoInputDeviceCategory | ビデオ キャプチャ フィルタ。
CLSID_VideoCompressorCategory | ビデオ コンプレッサ、ビデオ エンコーダ。
CLSID_ActiveMovieCategories | カテゴリのリストが含まれたメタカテゴリ。GraphEdit はこの CLSID を使ってすべてのカテゴリを列挙する。通常、アプリケーションでは、この CLSID を使用しない。


メディア タイプ

Microsoft® DirectShow® では、AM_MEDIA_TYPE 構造体を使ってメディア サンプルを記述する。この構造体には、メジャー タイプ、サブタイプ、およびフォーマット タイプの GUID メンバのほかに、サンプルが圧縮されているかどうかなど、サンプルのその他の特性を示すフィールドが含まれている。このトピックでは、DirectShow によって登録されるメジャー タイプおよびサブタイプのオプションの概要について説明する。これらのメディア タイプは、Uuids.h で定義されている。

このトピックは、以下のセクションで構成される。

  • メジャー タイプ
  • オーディオ サブタイプ
  • Line 21 サブタイプ
  • MPEG-2 サブタイプ
  • ストリーム サブタイプ
  • ビデオ サブタイプ
  • アナログ ビデオ サブタイプ

メジャー タイプ

次の表は、メジャー メディア タイプを示している。

GUID | 説明
MEDIATYPE_AnalogAudio | アナログ オーディオ。
MEDIATYPE_AnalogVideo | アナログ ビデオ。
MEDIATYPE_Audio | オーディオ。
MEDIATYPE_AUXLine21Data | Line 21 データ。クローズド キャプションによって使用される。
MEDIATYPE_File | ファイル。クローズド キャプションによって使用される。
MEDIATYPE_Interleaved | インターリーブ。デジタル ビデオ (DV) によって使用される。
MEDIATYPE_LMRT | 廃止。使用しないこと。
MEDIATYPE_Midi | MIDI フォーマット。
MEDIATYPE_MPEG2_PES | MPEG-2。DVD によって使用される。
MEDIATYPE_ScriptCommand | データは、クローズド キャプションによって使用されるスクリプト コマンドである。
MEDIATYPE_Stream | タイム スタンプのないバイト ストリーム。
MEDIATYPE_Text | テキスト。
MEDIATYPE_Timecode | タイムコード データ。
MEDIATYPE_URL_STREAM | 廃止。使用しないこと。
MEDIATYPE_Video | ビデオ。

オーディオ サブタイプ

次の表は、オーディオ メディア サブタイプを示している。

GUID | 説明
MEDIASUBTYPE_PCMAudio | PCM オーディオ
MEDIASUBTYPE_PCMAudioObsolete | 廃止。使用しないこと。
MEDIASUBTYPE_MPEG1Packet | MPEG1 オーディオ パケット
MEDIASUBTYPE_MPEG1Payload | MPEG1 オーディオ ペイロード

WAVEFORMATEX 構造体の wFormatTag フィールドは、オーディオ フォーマット タイプを指定する。一般的にフォーマット タイプは、FORMAT_WaveFormatEx である。メディア サンプルは、一般的に、WAVEFORMATEX 構造体の wBitsPerSample フィールドで指定されるサンプル全体である。この条件は、元がパケット化されたストリームである可能性があり、したがって、必ずしもサンプル/フレーム境界上にパッケージされていない MPEG オーディオ サンプルには当てはまらない。MPEG オーディオの場合、メディア サンプルのタイム スタンプは、フレームの最初のバイトがメディア サンプルに含まれている最初のフレームのタイム スタンプである。

それぞれの wFormatTag に対応するメディア サブタイプの定義を次に示す。

  • メディア サブタイプの Data1 サブフィールドは、wFormatTag 値と同じ。
  • Data 2 フィールドは 0。
  • Data 3 フィールドは 0x0010。
  • Data 4 フィールドは、0x80、0x00、0x00、0xAA、0x00、0x38、0x9B、0x71。

したがって、PCM オーディオのサブタイプ GUID は、次のようになる。

{00000001-0000-0010-8000-00AA00389B71}

古いフィルタでは、GUID_NULL をサブタイプとして使用していることがあるため、これをチェックする必要がある。ただし、明示的なサブタイプを使ってフィルタを登録すると、特に特定のフィルタが必要とされていない場合は、グラフの読み込み速度が大幅に向上する。CreateAudioMediaType 関数を使って、WAVEFORMATEX 構造体から AM_MEDIA_TYPE 構造体を作成できる。

Line 21 サブタイプ

次の表は、Line 21 クローズド キャプション メディア サブタイプを示している。

GUID | 説明
MEDIASUBTYPE_Line21_BytePair | バイト ペアとしての Line 21 データ
MEDIASUBTYPE_Line21_GOPPacket | DVD GOP パケットの Line 21 データ
MEDIASUBTYPE_Line21_VBIRawData | 生の VBI フォーマットの Line 21 データ

MPEG-2 サブタイプ

次の表は、MPEG-2 メディア サブタイプを示している。

GUID | 説明
MEDIASUBTYPE_DVD_SUBPICTURE | サブピクチャ データ
MEDIASUBTYPE_DOLBY_AC3 | Dolby データ
MEDIASUBTYPE_MPEG2_AUDIO | MPEG-2 オーディオ データ
MEDIASUBTYPE_DVD_LPCM_AUDIO | DVD オーディオ データ
MEDIASUBTYPE_MPEG2_TRANSPORT | MPEG-2 トランスポート ストリーム
MEDIASUBTYPE_MPEG2_PROGRAM | MPEG2 番組ストリーム

ストリーム サブタイプ

次の表は、ストリーム メディア サブタイプを示している。

GUID | 説明
MEDIASUBTYPE_AIFF | AIFF ファイルのデータ
MEDIASUBTYPE_Asf | ASF (Advanced Streaming Format)
MEDIASUBTYPE_Avi | AVI ファイルのデータ
MEDIASUBTYPE_AU | AU ファイルのデータ
MEDIASUBTYPE_DssAudio | Dss Audio
MEDIASUBTYPE_DssVideo | Dss Video
MEDIASUBTYPE_MPEG1Audio | MPEG オーディオ
MEDIASUBTYPE_MPEG1System | MPEG システム
MEDIASUBTYPE_MPEG1SystemStream | 廃止。使用しないこと。
MEDIASUBTYPE_MPEG1Video | MPEG ビデオ
MEDIASUBTYPE_MPEG1VideoCD | MPEG ビデオ CD
MEDIASUBTYPE_WAVE | WAV ファイルのデータ

タイム スタンプは、リアル タイムではなく、バイト位置 * 10000000 (1 秒につき 1 バイト) である。

ビデオ サブタイプ

次の表は、ビデオ メディア サブタイプを示している。

GUID | 説明
MEDIASUBTYPE_YVU9 | 標準 YVU9 フォーマット非圧縮データ。平面 YUV フォーマット。すべての水平ラインのすべてのピクセルで Y のサンプリングを行い、4 ピクセルごとに U と V のサンプリングを行う。すべての垂直ラインで Y のサンプリングを行い、垂直ライン 4 本ごとに U と V のサンプリングを行う。1 ピクセルにつき 9 ビット。
MEDIASUBTYPE_Y411 | YUV 411 フォーマット データ。Y41P と同じ。
MEDIASUBTYPE_Y41P | Y41P フォーマット データ。パックされた YUV フォーマット。すべての水平ラインのすべてのピクセルで Y のサンプリングを行い、4 ピクセルごとに U と V のサンプリングを行う。すべての垂直ラインをサンプリングする。バイトの順序は、最下位から順に、U0、Y0、V0、Y1、U4、Y2、V4、Y3、Y4、Y5、Y6、Y7 であり、サフィックス 0 は左端のピクセルで、番号が大きいほどピクセルは右寄りになる。12 バイトのブロックが 8 画像ピクセルに相当する。
MEDIASUBTYPE_YUY2 | YUY2 フォーマット データ。ピクセルの順序を除いて UYVY と同じ。バイトの順序は、最下位から順に、Y0、U0、Y1、V0、Y2、U2、Y3、V2、Y4、U4、Y5、V4 であり、サフィックス 0 は左端のピクセルで、番号が大きいほどピクセルは右寄りになる。4 バイトのブロックが 2 画像ピクセルに相当する。
MEDIASUBTYPE_YVYU | YVYU フォーマット データ。パックされた YUV フォーマット。ピクセルの順序を除いて UYVY と同じ。バイトの順序は、最下位から順に、Y0、V0、Y1、U0、Y2、V2、Y3、U2、Y4、V4、Y5、U4 であり、サフィックス 0 は左端のピクセルで、番号が大きいほどピクセルは右寄りになる。4 バイトのブロックが 2 画像ピクセルに相当する。
MEDIASUBTYPE_UYVY | UYVY フォーマット データ。パックされた YUV フォーマット。すべての水平ラインのすべてのピクセルで Y のサンプリングを行い、2 ピクセルごとに U と V のサンプリングを行う。すべての垂直ラインをサンプリングする。さまざまな YUV 4:2:2 フォーマットの中でも最もよく使われている。バイトの順序は、最下位から順に、U0、Y0、V0、Y1、U2、Y2、V2、Y3、U4、Y4、V4、Y5 であり、サフィックス 0 は左端のピクセルで、番号が大きいほどピクセルは右寄りになる。4 バイトのブロックが 2 画像ピクセルに相当する。
MEDIASUBTYPE_Y211 | YUV 211 フォーマット データ。パックされた YUV フォーマット。すべての水平ラインで 2 ピクセルごとに Y のサンプリングを行い、4 ピクセルごとに U と V のサンプリングを行う。すべての垂直ラインをサンプリングする。バイトの順序は、最下位から順に、Y0、U0、Y2、V0、Y4、U4、Y6、V4、Y8、U8、Y10、V8 であり、サフィックス 0 は左端のピクセルで、番号が大きいほどピクセルは右寄りになる。4 バイト のブロックが 4 画像ピクセルに相当する。
MEDIASUBTYPE_CLJR | Y、U、V サンプル 1 つにつき 8 ビット未満の Cirrus Logic Jr YUV 411 フォーマット。Cinepak ではこれを生成でき、Cirrus 5440 ではこれを使ってオーバレイを生成できる。すべての水平ラインのすべてのピクセルで Y のサンプリングを行い、4 ピクセルごとに U と V のサンプリングを行う。すべての垂直ラインをサンプリングする。
MEDIASUBTYPE_IF09 | 最後のフレームとの差異に関する追加情報が含まれた、Indeo で生成される YVU9 フォーマット。1 ピクセルにつき 9.5 ビットであるが、9 として報告される。
MEDIASUBTYPE_CPLA | Cinepak UYVY フォーマット。
MEDIASUBTYPE_MJPG | Motion JPEG (MJPG) 圧縮ビデオ。
MEDIASUBTYPE_TVMJ | TrueVision MJPG フォーマット。
MEDIASUBTYPE_WAKE | 一部のカードによって生成される MJPG フォーマット。
MEDIASUBTYPE_CFCC | 一部のカードによって生成される MJPG フォーマット。
MEDIASUBTYPE_IJPG | Intergraph JPEG フォーマット。
MEDIASUBTYPE_Plum | Plum MJPG フォーマット。
MEDIASUBTYPE_RGB1 | 1 ピクセルにつき RGB 1 ビット。パレット化されている。
MEDIASUBTYPE_RGB4 | 1 ピクセルにつき RGB 4 ビット。パレット化されている。
MEDIASUBTYPE_RGB8 | 1 ピクセルにつき RGB 8 ビット。パレット化されている。
MEDIASUBTYPE_RGB565 | RGB の 565 フォーマット、1 ピクセルにつき 16 ビット。非圧縮 RGB サンプル。
MEDIASUBTYPE_RGB555 | RGB の 555 フォーマット、1 ピクセルにつき 16 ビット。非圧縮 RGB サンプル。
MEDIASUBTYPE_RGB24 | 1 ピクセルにつき RGB 24 ビット。非圧縮 RGB サンプル。
MEDIASUBTYPE_RGB32 | 1 ピクセルにつき RGB 32 ビット。非圧縮 RGB サンプル。このメディア タイプではアルファ ビットは使用しないこと (MEDIASUBTYPE_ARGB32 と比較)。
MEDIASUBTYPE_ARGB32 | 1 ピクセルにつき ARGB 32 ビット。有効なアルファ ビットを持つ非圧縮 RGB サンプル。
MEDIASUBTYPE_Overlay | ハードウェア オーバーレイを使って配信されるビデオ。
MEDIASUBTYPE_QTMovie | Apple® QuickTime® 圧縮。
MEDIASUBTYPE_QTRpza | Quicktime RPZA 圧縮データ。
MEDIASUBTYPE_QTSmc | Quicktime SMC 圧縮データ。
MEDIASUBTYPE_QTRle | Quicktime RLE 圧縮データ。
MEDIASUBTYPE_QTJpeg | Quicktime JPEG 圧縮データ。
MEDIASUBTYPE_dvsd | 標準 DV フォーマット。
MEDIASUBTYPE_dvhd | 高品位 DV フォーマット。
MEDIASUBTYPE_dvsl | ロング プレイ DV フォーマット。
MEDIASUBTYPE_MPEG1Packet | MPEG1 ビデオ パケット。
MEDIASUBTYPE_MPEG1Payload | MPEG1 ビデオ ペイロード。
MEDIASUBTYPE_VideoPort | DVD で使用されるビデオ ポート データ。
MEDIASUBTYPE_VPVideo | ビデオ ポート ビデオ データ。
MEDIASUBTYPE_VPVBI | ビデオ ポート垂直同期間隔 (VBI) データ。

アナログ ビデオ サブタイプ

以下のアナログ ビデオ フォーマットは Microsoft® ActiveMovie® 1.0 で導入されたが、現在は使われていない。その代わりに、IAMAnalogVideoDecoder インターフェイスと IAMTVTuner インターフェイスは、AnalogVideoStandard 列挙を使用する。
GUID | 説明
MEDIASUBTYPE_AnalogVideo_NTSC_M | (M) NSTC
MEDIASUBTYPE_AnalogVideo_PAL_B | (B) PAL
MEDIASUBTYPE_AnalogVideo_PAL_D | (D) PAL
MEDIASUBTYPE_AnalogVideo_PAL_G | (G) PAL
MEDIASUBTYPE_AnalogVideo_PAL_H | (H) PAL
MEDIASUBTYPE_AnalogVideo_PAL_I | (I) PAL
MEDIASUBTYPE_AnalogVideo_PAL_M | (M) PAL
MEDIASUBTYPE_AnalogVideo_PAL_N | (N) PAL
MEDIASUBTYPE_AnalogVideo_SECAM_B | (B) SECAM
MEDIASUBTYPE_AnalogVideo_SECAM_D | (D) SECAM
MEDIASUBTYPE_AnalogVideo_SECAM_G | (G) SECAM
MEDIASUBTYPE_AnalogVideo_SECAM_H | (H) SECAM
MEDIASUBTYPE_AnalogVideo_SECAM_K | (K) SECAM
MEDIASUBTYPE_AnalogVideo_SECAM_K1 | (K1) SECAM
MEDIASUBTYPE_AnalogVideo_SECAM_L | (L) SECAM


MPEG-1 メディア タイプ

ここでは、Microsoft® DirectShow® が MPEG データに使用するメディア タイプについて説明する。

MPEG-1 システム ストリーム
メジャー タイプ:MEDIATYPE_Stream

マイナー タイプ:MEDIASUBTYPE_MPEG1System

フォーマット:なし

サンプルの内容:BYTE ストリーム、調整なし

ビデオ CD の MPEG-1 システム ストリーム
メジャー タイプ:MEDIATYPE_Stream

マイナー タイプ:MEDIASUBTYPE_MPEG1VideoCD

フォーマット:なし

サンプルの内容:BYTE ストリーム、調整なし

MPEG-1 オーディオ パケット
メジャー タイプ:MEDIATYPE_Audio

マイナー タイプ:MEDIASUBTYPE_MPEG1Packet

フォーマット:MPEG1WAVEFORMAT

サンプルの内容:パケット ヘッダーが含まれた単一の MPEG-1 パケット

MPEG-1 オーディオ ペイロード
メジャー タイプ:MEDIATYPE_Audio

マイナー タイプ:MEDIASUBTYPE_MPEG1Payload

フォーマット:MPEG1WAVEFORMAT

サンプルの内容:バイト調整された MPEG-1 オーディオ データ

MPEG-1 ビデオ パケット
メジャー タイプ:MEDIATYPE_Video

マイナー タイプ:MEDIASUBTYPE_MPEG1Packet

フォーマット:VIDEOINFO + ビデオ シーケンス ヘッダー

サンプルの内容:パケット ヘッダーが含まれた単一の MPEG-1 パケット

MPEG-1 ビデオ ペイロード
メジャー タイプ:MEDIATYPE_Video

マイナー タイプ:MEDIASUBTYPE_MPEG1Payload

フォーマット:VIDEOINFO + ビデオ シーケンス ヘッダー

サンプルの内容:バイト調整された MPEG-1 ビデオ データ

MPEG-1 ネイティブ ビデオ ストリーム
メジャー タイプ:MEDIATYPE_Stream

マイナー タイプ: MEDIASUBTYPE_ MPEG1Video

フォーマット:なし

サンプルの内容:ビデオ ストリーム バイトの配列 (システム レイヤなし)

MPEG-1 ネイティブ オーディオ ストリーム
メジャー タイプ:MEDIATYPE_Stream

マイナー タイプ: MEDIASUBTYPE_ MPEG1Audio

フォーマット:なし

サンプルの内容:オーディオ ストリーム バイトの配列 (システム レイヤなし)

さまざまなフィルタは、次のようにピンをサポートする。

フィルタ | 方向 | メディア タイプ
システム レイヤ スプリッタ | 入力 | MPEG-1 システム ストリーム ビデオ CD の MPEG-1 システム ストリーム
システム レイヤ スプリッタ | 出力 | MPEG-1 オーディオ パケットまたは MPEG-1 オーディオ データ
システム レイヤ スプリッタ | 出力 | MPEG-1 ビデオ パケットまたは MPEG-1 ビデオ データ
ソフトウェア オーディオ CODEC | 入力 | MPEG-1 オーディオ データまたは MPEG-1 オーディオ パケット
ソフトウェア ビデオ CODEC | 入力 | MPEG-1 ビデオ データまたは MPEG-1 ビデオ パケット
ソフトウェア オーディオ CODEC | 出力 | PCM オーディオ モノまたはステレオ、入力サンプリング レート、入力サンプリング レートの 2 分の 1 または入力サンプリング レートの 4 分の 1
ソフトウェア ビデオ CODEC | 出力 | Y41P、YUY2、UYVY、RGB24、RGB32、RGB565、RGB555、RGB8 フォーマットの非圧縮ビデオ

シーケンス ヘッダーがビデオ再生を初期化しなくてもファイルの途中からデータを再生できるように、MPEG-1 ビデオ パケットとペイロードのメディア タイプには完全なシーケンス ヘッダーが含まれている。

ストリームの途中から再生を開始できるように、MPEG ビデオのビデオ データ タイプにはビデオ シーケンス ヘッダーが追加される。このフィールドの長さは、最大 140 バイトである。このフィールドの先頭および最初のシーケンス ヘッダー内で見つかった量子化マトリクスには、シーケンス ヘッダー開始コード —0x000001B3— が含まれている。


MPEG-2 スプリッタ フィルタ メディア タイプ

現在、MPEG-2 スプリッタは、オーディオとビデオをサポートしている。Dolby AC-3 は DVD で定義されているサブストリームとしてサポートされている。MPEG-2 オーディオもサポートされている。

ビデオのタイプを次に示す。

 | PES 出力 | Payload 出力
タイプ | MEDIATYPE_MPEG2_PES | MEDIATYPE_Video
サブタイプ | MEDIASUBTYPE_MPEG2_VIDEO | MEDIASUBTYPE_MPEG2_VIDEO
フォーマット | FORMAT_MPEG2Video | FORMAT_MPEG2Video
フォーマット ブロック | MPEG2VIDEOINFO | MPEG2VIDEOINFO

AC-3 オーディオのタイプを次に示す。

 | PES 出力 | Payload 出力
タイプ | MEDIATYPE_MPEG2_PES | MEDIATYPE_Audio
サブタイプ | MEDIASUBTYPE_DOLBY_AC3 | MEDIASUBTYPE_DOLBY_AC3
フォーマット | FORMAT_WaveFormatEx | FORMAT_WaveFormatEx
フォーマット ブロック | WAVEFORMATEX | WAVEFORMATEX

AC-3 に対応する WAVEFORMATEX 構造体の wFormatTag メンバは、現在 WAVE_FORMAT_UNKNOWN であるが、変わる可能性があるため、確認する必要がある。

MPEG-2 のタイプを次に示す。

 | PES 出力 | Payload 出力
タイプ | MEDIATYPE_MPEG2_PES | MEDIATYPE_Audio
サブタイプ | MEDIASUBTYE_MPEG2_AUDIO | MEDIASUBTYPE_MPEG2_AUDIO
フォーマット | FORMAT_WaveFormatEx | FORMAT_WaveFormatEx
フォーマット ブロック | WAVEFORMATEX | WAVEFORMATEX

MPEG-2 オーディオに対応する WAVEFORMATEX 構造体の wFormatTag メンバは、現在 WAVE_FORMAT_UNKNOWN であるが、変わる可能性があるため、確認する必要がある。

MPEG-2 スプリッタでは、DVD MPEG-2 オーディオの場合と同様に、ストリーム D0 ～ DF がマルチチャンネル拡張ストリームに使用されていると想定しているため、ストリーム Cx が選択されていると、スプリッタは必ずストリーム Dx のパケットも転送する。

LPCM オーディオのタイプを次に示す。

 | PES 出力 | Payload 出力
タイプ | MEDIATYPE_MPEG2_PES | MEDIATYPE_Audio
サブタイプ | MEDIASUBTYPE_DVD_LPCM_AUDIO | MEDIASUBTYPE_DVD_LPCM_AUDIO
フォーマット | FORMAT_WaveFormatEx | FORMAT_WaveFormatEx
フォーマット ブロック | WAVEFORMATEX | WAVEFORMATEX

LPCM オーディオに対応する WAVEFORMATEX 構造体の wFormatTag メンバは、現在 WAVE_FORMAT_UNKNOWN であるが、変わる可能性があるため、確認する必要がある。


メリット

グラフを構築中に、フィルタ グラフ マネージャがフィルタを試行する順序を定義する。「フィルタ グラフの構築」も参照すること。

構文

enum
{
    MERIT_PREFERRED     = 0x800000,
    MERIT_NORMAL        = 0x600000,
    MERIT_UNLIKELY      = 0x400000,
    MERIT_DO_NOT_USE    = 0x200000,
    MERIT_SW_COMPRESSOR = 0x100000,
    MERIT_HW_COMPRESSOR = 0x100050
};

注意

各フィルタには、メリット値が登録される。フィルタ グラフ マネージャは、グラフを構築する際に、適切なメディア タイプに登録されているすべてのフィルタを列挙する。次にフィルタ グラフ マネージャは、メリットの上位から下位の順にフィルタを試行する。(メリット値が同じフィルタに対しては別の条件を適用する。) フィルタ グラフ マネージャは、メリット値が MERIT_DO_NOT_USE 以下のフィルタは試行しない。

通常再生において考慮されるべきではないフィルタは、MERIT_DO_NOT_USE 以下のメリットを持つ必要がある。フィルタには、ここに挙げていない中間値 (たとえば MERIT_NORMAL + 1) を登録することができる。


タイム フォーマット GUID

次のグローバル ユニーク識別子 (GUID) は異なるタイム フォーマットを定義する。

宣言 : Uuids.h

GUID | 説明
TIME_FORMAT_NONE | フォーマットなし。
TIME_FORMAT_FRAME | ビデオ フォーマット。
TIME_FORMAT_SAMPLE | ストリーム内のサンプル。
TIME_FORMAT_FIELD | インターレース ビデオ フォーマット。
TIME_FORMAT_BYTE | ストリーム内のバイト オフセット。
TIME_FORMAT_MEDIA_TIME | メディア タイム (100 ナノ秒単位)。

参照

IMediaSeeking


関数

Microsoft® DirectShow® では以下の関数を提供する :

AMGetErrorText 任意のメッセージ ID のエラー メッセージ テキストを取得する。

AMGetErrorText

関数

現在の言語の設定を使って、戻りコードに対応するエラー メッセージを取得する。

この関数は、HRESULT の戻りコードをエラー メッセージに変換する。定数 MAX_ERROR_TEXT_LEN は、エラー メッセージの最大文字数を指定する。

注 : この関数を使うためには、アプリケーションはライブラリ ファイル Quartz.lib にリンクしなければならない。

構文

DWORD AMGetErrorText(
    HRESULT hr,
    TCHAR *pBuffer,
    DWORD MaxLen
    );

パラメータ

hr
HRESULT 値。
pBuffer
エラー メッセージを受け取る文字バッファへのポインタ。
MaxLen
pBuffer の最大文字数。

戻り値

バッファに返された文字数を返す。エラーが発生した場合は、ゼロを返す。


MSWebDVD に関する参照ページ

Microsoft® MSWebDVD ActiveX® コントロールを使用することによって、スクリプト ベースの DVD アプリケーションを作成できる。この ActiveX コントロールは、以下のオブジェクトおよびイベントをアプリケーションに対して公開する。

  • MSWebDVD
  • MSDVDAdm
  • DVDRect
  • MSWebDVD イベント


MSWebDVD オブジェクト

MSWebDVD オブジェクトのメソッド、プロパティ、およびイベントを使用すると、アプリケーションから DVD ビデオのナビゲーションおよび再生を完全に制御し、ディスクから情報を取得することができる。MSWebDVD オブジェクトは、ナビゲーション処理自体は実行せずに、DVD ナビゲータ フィルタにコマンドを渡す。このフィルタは、DVD ビデオのディスクを読み取る Microsoft® DirectShow® コンポーネントである。

MSWebDVD のメソッドおよびプロパティは、DVD ナビゲータの現在の状態、ディスク上の情報、またはその両方に作用する。ペアレンタル ロック レベルおよびデフォルト言語のユーザー設定など、レジストリ内にあるアプリケーション固有の各種情報を格納および取得するには、MSDVDAdm オブジェクトのメソッドを使用する。このオブジェクトにアクセスするには、DVDAdm プロパティを使用する。

参照

MSWebDVD イベント
スクリプト ベースの DVD アプリケーションの記述

メソッドおよびプロパティ (カテゴリ別)

再生
CanStep | ローカル システムの MPEG-2 デコーダがコマ送りを実行できるかどうかを判断する。
Eject | ドライブのディスクの取り出し/挿入を行う。
FramesPerSecond | 現在の DVD タイトルのビデオ フレーム レートを取得する。
Pause | 再生を現在位置でポーズする。
Play | 現在の DVD タイトルを再生する。
PlayAtTime | 現在のタイトルの指定された時間から再生を開始する。
PlayAtTimeInTitle | 指定されたタイトルの指定された時間から再生を開始する。
PlayBackwards | 指定された速度で現在位置から逆方向再生を開始する。
PlayChapter | 現在のタイトルの指定されたチャプターから再生を開始する。
PlayChapterInTitle | 指定されたタイトルの指定されたチャプターを再生する。
PlayChaptersAutoStop | 指定されたタイトルの指定されたチャプターから指定されたチャプター数の再生を開始する。
PlayForwards | 指定された速度で現在位置から順方向再生を開始する。
PlayNextChapter | 現在のタイトルの次のチャプターから再生を開始する。
PlayPeriodInTitleAutoStop | 指定されたタイトルの指定された時間から指定された終了タイムまでの再生を開始する。
PlayPrevChapter | 現在のタイトルの直前のタイトルから再生を開始する。
PlayTitle | 指定されたタイトルの最初から再生を開始する。
ReplayChapter | 現在のチャプターの最初から再生を開始する。
Resume | メニュー表示後に再生を再開する。
StillOff | 再生を再開し、静止モードをキャンセルする。
Step | DVD ビデオ ストリームを指定されたフレーム数だけ進める。
Stop | 再生を停止する。
メニュー
ActivateAtPosition | メニュー ボタンを指定された位置でアクティブにする。
ActivateButton | 選択されたメニュー ボタンをアクティブにする。
ButtonsAvailable | 現在のメニューに含まれるボタンの総数を取得する。
CurrentButton | 選択されたボタンの番号を取得する。
DefaultMenuLanguage | ディスクからデフォルトのメニュー言語を取得する。
GetButtonAtPosition | ボタンを選択またはアクティブにせずに、指定された座標にあるボタンの番号を取得する。
GetButtonRect | 指定されたボタンの矩形をウィンドウ座標で取得する。
ReturnFromSubmenu | 表示をサブメニューから親メニューに戻す。トップレベル メニューなら現在のタイトルに戻す。
SelectAndActivateButton | 指定されたボタンを選択し、アクティブにする。
SelectAtPosition | 指定された位置にあるメニュー ボタンを選択する。
SelectLeftButton | 表示されたメニューから左方向ボタンを選択する。
SelectLowerButton | 表示されたメニューから下方向ボタンを選択する。
SelectRightButton | 表示されたメニューから右方向ボタンを選択する。
SelectUpperButton | 表示されたメニューから上方向ボタンを選択する。
ShowMenu | 指定されたメニューを画面上に表示する。
オーディオ ストリーム
AudioStreamsAvailable | 現在のタイトル内の利用可能なオーディオ ストリーム数を取得する。
Balance | オーディオ ストリーム出力のスピーカ バランスを設定または取得する。
CurrentAudioStream | 有効なオーディオ ストリームの数を設定または取得する。
DefaultAudioLanguage | ディスクからデフォルトのオーディオ言語を取得する。
DefaultAudioLanguageExt | ディスクからデフォルトのオーディオ言語エクステンションを取得する。
GetAudioLanguage | 指定されたオーディオ ストリーム上の利用可能な言語を示す文字列を取得する。
IsAudioStreamEnabled | 指定されたオーディオ ストリームが現在のタイトルで有効かどうかを示す値を取得する。
Mute | オーディオ ストリーム出力のオン/オフを切り替える。
SelectDefaultAudioLanguage | DVD ナビゲータ内の現在のデフォルト オーディオ言語を設定する。
Volume | オーディオのボリュームを設定または取得する。
サブピクチャ ストリーム
CurrentSubpictureStream | 選択されたサブピクチャ ストリームを取得する。
DefaultSubpictureLanguage | ディスクからデフォルトのサブピクチャ言語を取得する。
DefaultSubpictureLanguageExt | ディスクからデフォルトのサブピクチャ言語エクステンションを取得する。
GetSubpictureLanguage | 指定されたサブピクチャ ストリームの言語を取得する。
IsSubpictureStreamEnabled | 指定されたサブピクチャ ストリームが現在のタイトルで有効かどうかを示す値を取得する。
PreferredSubpictureStream | 現在の表示セッションに対応するユーザー設定のサブピクチャ ストリームを設定または取得する。
SelectDefaultSubpictureLanguage | DVD ナビゲータ内の現在のデフォルト サブピクチャ言語を設定する。
SubpictureOn | サブピクチャの現在の状態 (オン/オフ) を設定または取得する。
SubpictureStreamsAvailable | 現在のタイトル内の利用可能なサブピクチャ ストリーム数を取得する。
ビデオ矩形
AspectRatio | ディスクに明記された現在のビデオ ストリームのアスペクト比を取得する。
BackColor | ネイティブ ビデオのアスペクト比がオブジェクトの表示領域のアスペクト比と異なっているときに、ビデオ矩形の縁の周りに表示されるバーの色を設定または取得する。
Capture | MSWebDVD オブジェクトがウィンドウレス モードのときに、ビデオ フレームから静止画をキャプチャする。
FullScreenMode | 表示がフルスクリーン モードかどうかを示す値を設定または取得する。
GetClipVideoRect | ビデオ表示用に定義されたクリッピング矩形を取得する。
GetVideoSize | ネイティブ ビデオのディメンジョンを取得する。
SetClipVideoRect | ビデオ表示が占めるクリッピング矩形を設定する。
Zoom | 所定のスクリーン座標を中心に、ビデオ表示をズームイン/ズームアウトする。
クローズド キャプション
CCActive | クローズド キャプションの現在の状態を設定または取得する。
ColorKey | クローズド キャプションで使用するカラー キーを設定または取得する。
CurrentCCService | 現在のクローズド キャプション サービスを設定または取得する。
アングル ブロック
AnglesAvailable | 利用可能なアングル数を取得する。
CurrentAngle | アングル ブロック内の現在のアングルを設定または取得する。
カラオケ オーディオ
GetKaraokeChannelAssignment | カラオケ チャンネルの左右スピーカへの割り当てを示す値を取得する。
GetKaraokeChannelContent | 指定されたストリームの指定されたカラオケ チャンネルのコンテンツの種類を示す値を取得する。
KaraokeAudioPresentationMode | 外部カラオケ チャンネルの左右スピーカ ミキシング比を設定または取得する。
テキスト
GetDVDTextLanguageLCID | 指定されたテキスト文字列ブロックのロケール識別子 (LCID) を取得する。
GetDVDTextNumberOfLanguages | 現在の DVD ディレクトリ内の利用可能なテキスト言語数を取得する。
GetDVDTextNumberOfStrings | 指定された言語に利用可能なテキストの数を取得する。
GetDVDTextString | 指定されたテキストをディスクから取得する。
GetDVDTextStringType | 指定された DVD テキストに格納された情報の種類を示す値を取得する。
GetLangFromLangID | 所定の主言語識別子 (ID) に対応する人が読むことができる文字列を取得する。
ペアレンタル ロック
AcceptParentalLevelChange | 新しい一時ペアレンタル ロック レベルを受け付けるかまたは拒否するように DVD ナビゲータに指示する。
GetPlayerParentalCountry | DVD ナビゲータに設定された現在の国を取得する。
GetPlayerParentalLevel | DVD ナビゲータに設定されたペアレンタル ロック レベルを取得する。
GetTitleParentalLevels | 指定されたタイトルのペアレンタル ロック レベル数を取得する。
NotifyParentalLevelChange | 一時ペアレンタル ロック レベル コマンドのイベント処理を有効または無効にする。
SelectParentalCountry | 今後の再生に使用する国として、指定されたペアレンタル カントリを設定する。
SelectParentalLevel | 今後の再生に使用するペアレンタル ロック レベルとして、指定されたペアレンタル ロック レベルを設定する。
ディスク情報
CurrentChapter | 現在再生しているチャプターの番号を取得する。
CurrentDiscSide | DVD の現在のサイドを取得する。
CurrentDomain | DVD ナビゲータの現在の DVD ドメインを取得する。
CurrentTime | 現在の再生時間を取得する。
CurrentTitle | 現在再生しているタイトルの番号を取得する。
CurrentVolume | 現在のルート ディレクトリのボリューム番号を取得する。
DVDDirectory | 現在の DVD ボリュームのルート ディレクトリを取得または設定する。
DVDTimeCode2bstr | ディスク上の現在時間を示す文字列を取得する。
DVDUniqueID | 現在の DVD を一意に識別する、システムで生成された番号を取得する。
GetNumberOfChapters | 指定されたタイトルに含まれるチャプターの数を取得する。
TitlesAvailable | DVD 上の利用可能なタイトル数を取得する。
TotalTitleTime | 現在のタイトルの総再生時間を取得する。
UOPValid | 指定されたユーザー操作が現在有効かどうかを示す値を取得する。
VolumesAvailable | ディスク セットのボリューム数を示す値を取得する。
オブジェクトの初期化および制御
DisableAutoMouseProcessing | オブジェクトのマウス処理機能を有効または無効にする。
DVDAdm | アプリケーションおよびユーザーの情報を保存するメソッドおよびプロパティが格納された MSDVDAdm オブジェクトへのアクセスを提供する。
EnableResetOnStop | フィルタ グラフが停止状態から移行するときに再生をどのように再開するかを決定する値を、設定または取得する。
PlayState | 現在の再生状態を取得する。
ReadyState | MSWebDVD オブジェクトの ReadyState を取得する。
RegionChange | DVD に関連付けられたリージョンをユーザーが変更するためのシステム ダイアログ ボックスを表示する。
Render | DVD フィルタ グラフを初期化する。
WindowlessActivation | ウィンドウ モードとウィンドウレス モードのいずれかに使用する MSWebDVD オブジェクトを設計時に初期化する。
ブックマーク
DeleteBookmark | 現在のブックマークを削除する。
RestoreBookmark | 現在のブックマークが示す DVD 上の位置に DVD ナビゲータを移動し、オーディオ、ビデオ、およびサブピクチャの設定をすべて復元する。
SaveBookmark | ユーザーが後で同じ場所に戻れるように、DVD ナビゲータの現在のディスク位置および状態をディスクに保存する。
カーソルおよびツールチップ
CursorType | 現在のカーソルの種類を設定または取得する。
GetDelayTime | MSWebDVD オブジェクトに関連付けられたツールチップに対応する遅延時間を取得する。
SetDelayTime | MSWebDVD オブジェクトに関連付けられたツールチップに対応する遅延時間を設定する。
ShowCursor | DVD ナビゲータがフルスクリーン モードのときに、マウス ポインタを表示する。
ToolTip | マウス ポインタが MSWebDVD ビデオ矩形に重なったときに表示されるツールチップのテキストを設定する。
ToolTipMaxWidth | MSWebDVD オブジェクトに関連付けられたツールチップの最大幅を設定または取得する。
GPRM および SPRM
GetGPRM | 指定された一般パラメータ レジスタを取得する。
GetSPRM | 指定されたシステム パラメータ レジスタを取得する。
SetGPRM | 指定された一般パラメータ レジスタに指定された値を設定する。

AcceptParentalLevelChange メソッド

MSWebDVD オブジェクト

新しい一時ペアレンタル ロック レベルを受け付けるかまたは拒否するように DVD ナビゲータに指示する。

構文

MSWebDVD.AcceptParentalLevelChange(bAccept);

パラメータ

bAccept 新しいペアレンタル レベルを受け付けるか拒否するかを指示するブール値 (trueが容認)。

戻り値

No return value.

注意

EC_DVD_PARENTAL_LEVEL_CHANGE イベント通知に対応してこのメソッドを呼び出し、新しいペアレンタル レベルでコンテンツを再生するべきかどうかを指定するか、あるいは新しいレベルが拒否されるならディスクの指定した所へ飛ぶ。

参照

ペアレンタル ロック レベルの使用、GetPlayerParentalCountry、GetPlayerParentalLevel、GetTitleParentalLevels、NotifyParentalLevelChange、SelectParentalCountry、SelectParentalLevel

ActivateAtPosition メソッド

MSWebDVD オブジェクト

マウス ポインタが現在重なっているメニュー ボタンをアクティブにする。

構文

MSWebDVD.ActivateAtPosition(xPos, yPos);

パラメータ

xPos | マウス ポインタの x 座標を指定する整数値。
xPos | マウス ポインタの y 座標を指定する整数値。

戻り値

戻り値なし。

注意

DisableAutoMouseProcessing を TRUE に設定した後、カスタム マウス ハンドリングを実装する場合は、このメソッドを使用する。

参照

ButtonsAvailable、CurrentButton、GetButtonAtPosition、GetButtonRect、SelectAndActivateButton、SelectAtPosition

ActivateButton メソッド

MSWebDVD オブジェクト

選択されたメニュー ボタンをアクティブにする。

構文

MSWebDVD.ActivateButton();

戻り値

戻り値なし。

注意

DisableAutoMouseProcessing を TRUE に設定した後、カスタム マウス ハンドリングを実装する場合は、このメソッドを使用する。

このメソッドは、SelectLeftButton メソッド、SelectLowerButton メソッド、SelectUpperButton メソッド、または SelectRightButton メソッドで選択したボタンをアクティブにするために使用する。

AnglesAvailable プロパティ

MSWebDVD オブジェクト

現在利用可能なアングル数を取得する。

構文

[ iAngles = ] MSWebDVD.AnglesAvailable

可能な値

iAngles 現在利用可能なアングル数を表す 1 ～ 9 の整数値。iAngles = 1 の場合、現在位置にはアングル ブロックがない。

このプロパティは、デフォルト値を持たない読み取り専用プロパティである。

注意

"アングル ブロック" とは、複数のアングルから撮影したビデオ セグメントである。アングル ブロックには、アングルが最大 9 つ含まれ、それらに 1 ～ 9 の番号が付いている。DVD ナビゲータは、最初にアングル ブロックに入ると、アングル番号を lParam1 に設定して、アプリケーションに EC_DVD_ANGLES_AVAILABLE イベント通知を送る。アングル ブロックに入ったときに利用可能なアングルのメニューを自動的に表示するディスクを作成することもできるが、通常は、アプリケーションで、利用可能なアングル数を判断し、そのうち 1 つを選択する手段をユーザーに提供する必要がある。

参照

CurrentAngle

AspectRatio プロパティ

MSWebDVD オブジェクト

ディスクに明記された現在のビデオ ストリームのアスペクト比を取得する。

構文

[ nAspectRatio = ] MSWebDVD.AspectRatio

可能な値

nAspectRatio ディスクに明記された現在のビデオ ストリームのアスペクト比を表す数値 (アスペクト比 4:3 の場合は 1.33、アスペクト比 16:9 の場合は 1.78)。

このプロパティは、デフォルト値を持たない読み取り専用プロパティである。

AudioStreamsAvailable プロパティ

MSWebDVD オブジェクト

現在のタイトル内の利用可能なオーディオ ストリーム数を取得する。

構文

[ iStreams = ] MSWebDVD.AudioStreamsAvailable

可能な値

iStreams 現在のタイトル内の利用可能なオーディオ ストリーム数を表す 1 ～ 8 の整数値。
このプロパティは、デフォルト値を持たない読み取り専用プロパティである。

注意

複数のオーディオ ストリームを使用する主な目的は、ムービーのサウンドトラックを複数の言語で提供することにある。通常、ディスクには一部のオーディオ ストリームのみが有効なタイトルが含まれている。たとえば、本編には 3 か国語のサウンドトラックがあるが、予告編には英語のサウンドトラックしかないかもしれない。ユーザーがストリームを選択するためには、現在のタイトル内の利用可能なストリームを、アプリケーションで判断する必要がある。個々のストリームは 0 ～ 7 のインデックスで識別されるので注意すること。

通常、ディスクには利用可能なサウンドトラックを表示するメニューがあり、有効にするオーディオ ストリームをユーザーが選択できるようになっている。

参照

GetAudioLanguage

BackColor プロパティ

MSWebDVD オブジェクト

ネイティブ ビデオのアスペクト比がオブジェクトの表示領域のアスペクト比と異なっているときに、ビデオ矩形の縁の周りに表示されるバーの色を設定または取得する。

構文

[ iBackColor = ] MSWebDVD.BackColor

可能な値

iBackColor 背景色の RGB 値を表す整数値。

このプロパティは、デフォルト値が off-black (0x100010) の読み書き可能なプロパティである。

Balance プロパティ

MSWebDVD オブジェクト

オーディオ ストリーム出力のスピーカ バランスを設定または取得する。

構文

[ iBalance = ] MSWebDVD.Balance

可能な値

iBalance バランス レベルを表す整数値。入力の許容範囲は -10,000 ～ 10,000 である。値 0 では均等なバランスが設定される。つまり、左右のスピーカに同じ振幅のオーディオ信号が供給される。

このプロパティは、両方のスピーカに同等のオーディオ信号が供給される 0 をデフォルト値に持つ、読み書き可能なプロパティである。Volume プロパティ同様に、単位は .01 デシベルに相当する (iBalance の値が正の場合は 1 倍される)。たとえば値 1000 では、右チャンネルが 10 dB、左チャンネルが 90 dB になる。

ButtonsAvailable プロパティ

MSWebDVD オブジェクト

現在のメニューに含まれるボタンの総数を取得する。

構文

[ iButtons = ] MSWebDVD.ButtonsAvailable

可能な値

iButtons ボタンの数を表す整数値。

このプロパティは、デフォルト値を持たない読み取り専用プロパティである。

注意

DisableAutoMouseProcessing を TRUE に設定した後、カスタム マウス ハンドリングを実装する場合は、このメソッドを使用する。

このメソッドを呼び出して、有効なボタン数の範囲の上限を取得する。

参照

CurrentButton、GetButtonAtPosition、GetButtonRect、SelectAndActivateButton、SelectAtPosition

CanStep メソッド

MSWebDVD オブジェクト

ローカル システムの MPEG-2 デコーダがコマ送りを実行できるかどうかを判断する。

構文

[ bCanStep = ] MSWebDVD.CanStep(bBackwards);

パラメータ

bBackwards 逆方向コマ送りを問い合わせるのかどうかを指定するブール値。デフォルトは、順方向コマ送りを意味する false。

戻り値

デコーダが指定された方向にコマ送り可能かどうかを示すブール値を返す。TRUE は可能であることを意味する。

注意

ハードウェア MPEG-2 デコーダすべてが、DirectShow® 8.0 の新しいコマ送り能力をサポートするとは限らない。このメソッドは、デコーダが持つコマ送り能力を照会する。デコーダがコマ送りを実行できる場合には、アプリケーションから Step メソッドを使用してフレームを進めることができる。ソフトウェア デコーダを使用している場合、このメソッドは常に TRUE を返す。

Capture メソッド

MSWebDVD オブジェクト

MSWebDVD オブジェクトがウィンドウレス モードのときに、ビデオ フレームから静止画をキャプチャする。

構文

MSWebDVD.Capture();

注意

このメソッドは、DVD ビデオ イメージから現在のフレームをキャプチャし、ユーザーがイメージを保存または編集できるウィンドウにそれを描画する。このメソッドが成功するには、MSWebDVD オブジェクトがウィンドウレス モードである必要がある。

CCActive プロパティ

MSWebDVD オブジェクト

クローズド キャプションの現在の状態を設定または取得する。

構文

[ bCCActive = ] MSWebDVD.CCActive

可能な値

bCCActive クローズド キャプションがオンかどうかを示すブール値。

このプロパティは、デフォルト値が false の読み書き可能なプロパティである。

参照

CurrentCCService

ColorKey プロパティ

MSWebDVD オブジェクト

クローズド キャプションで使用するカラー キーを設定または取得する。

構文

[ iColorKey = ] MSWebDVD.ColorKey

可能な値

iColorKey クローズド キャプション テキストの透過型バックグラウンドとして使用する色を表す整数値。デフォルト値は、256 色ではマゼンタ、それ以外の色深度ではオフブラックとなる。

このプロパティは、読み書き可能なプロパティである。

注意

このプロパティは、クローズド キャプションにのみ適用され (存在する場合)、サブピクチャ ストリームには適用されない。

CurrentAngle プロパティ

MSWebDVD オブジェクト

アングル ブロック内の現在のアングルを設定または取得する。

構文

[ iCurAngle = ] MSWebDVD.CurrentAngle

可能な値

iCurAngle アングルを表す 1 ～ 9 の整数値。

このプロパティは、デフォルト値を持たない読み書き可能なプロパティである。

参照

AnglesAvailable

CurrentAudioStream プロパティ

MSWebDVD オブジェクト

有効なオーディオ ストリームの数を設定または取得する。

構文

[ iStream = ] MSWebDVD.CurrentAudioStream

可能な値

iStream 現在のオーディオ ストリームを示す 0 ～ 7 の整数値。

このプロパティは、デフォルト値を持たない読み書き可能なプロパティである。

注意

新しいオーディオ ストリームを設定する場合は、その前に IsAudioStreamEnabled を呼び出してそのストリームが利用可能かどうか検査する。

参照

AudioStreamsAvailable

CurrentButton プロパティ

MSWebDVD オブジェクト

選択されたメニュー ボタンの番号を取得する。

構文

[ iButton = ] MSWebDVD.CurrentButton

可能な値

iButton ボタンを表す整数値。

このプロパティは、デフォルト値を持たない読み取り専用プロパティである。

注意

DisableAutoMouseProcessing を TRUE に設定した後、カスタム マウス ハンドリングを実装する場合は、このメソッドを使用する。

参照

ActivateButton、ButtonsAvailable、CurrentButton、GetButtonAtPosition、GetButtonRect、SelectAndActivateButton、SelectAtPosition

CurrentCCService プロパティ

MSWebDVD オブジェクト

現在のクローズド キャプション サービスを設定または取得する。

構文

[ iService = ] MSWebDVD.CurrentCCService

可能な値

iService 有効なクローズド キャプション サービスの種類を示す整数値。

このプロパティは、デフォルト値が 0x0 の読み書き可能なプロパティである。

次の一覧は、iService として可能な値である。
CC サービスの種類 | 値
現在のサービスはない。 | 0x0
トゥルー キャプション (フィールド 1)。デフォルトのサービス。 | 0x1
副言語のキャプション (フィールド 2)。通常は使用しない。 | 0x2

参照

CCActive

CurrentChapter プロパティ

MSWebDVD オブジェクト

現在再生しているチャプターの番号を取得する。

構文

[ iCurChapter = ] MSWebDVD.CurrentChapter

可能な値

iCurChapter 現在のタイトルの現在のチャプターを表す整数値。

このプロパティは、デフォルト値を持たない読み取り専用プロパティである。

CurrentDiscSide プロパティ

MSWebDVD オブジェクト

ディスクの現在のサイドを取得する。

構文

[ iCurSide = ] MSWebDVD.CurrentDiscSide

可能な値

iCurSide 現在のサイドを表す整数値。サイド A は 1、サイド B は 2。

このプロパティは、デフォルト値を持たない読み取り専用プロパティである。

CurrentDomain プロパティ

MSWebDVD オブジェクト

MSWebDVD オブジェクトの現在の DVD ドメインを取得する。

構文

[ iDomain = ] MSWebDVD.CurrentDomain

可能な値

iDomain 現在のドメインを表す 1 ～ 5 の整数値。

iDomain として可能な値は次のとおりである。
First Play | 1
Video Manager Menu | 2
Video Title Set Menu | 3
Title | 4
Stop | 5

このプロパティは、デフォルト値を持たない読み取り専用プロパティである。

注意

これから呼び出すメソッドに DVD ナビゲータのドメインが有効かどうか確認するには、このメソッドを呼び出す。たとえば、PlayTitle を呼び出す前には、CurrentDomain プロパティを確認して、DVD ナビゲータのドメインが Stop または First Play でないことを確認する。

CurrentSubpictureStream プロパティ

MSWebDVD オブジェクト

現在のサブピクチャ ストリームを設定または取得する。

構文

[ iSPStream = ] MSWebDVD.CurrentSubpictureStream

可能な値

iSPStream サブピクチャ ストリームを表す 0 ～ 31 の整数値。63 も可能 (ミュートされたビットレートの低いストリームを示す)。

このプロパティは、デフォルト値を持たない読み書き可能なプロパティである。

注意

新しいサブピクチャ ストリームを設定する場合は、その前に IsSubpictureStreamEnabled を呼び出してそのストリームが利用可能かどうか検査する。

参照

SubpictureOn、SubpictureStreamsAvailable

CurrentTime プロパティ

MSWebDVD オブジェクト

現在の再生時間を取得する。

構文

[ sCurTime = ] MSWebDVD.CurrentTime

可能な値

sCurTime 現在の再生時間を表す 11 文字の文字列。フォーマットは "hh:mm:ss:ff" (時、分、秒、フレーム)。

このプロパティは、デフォルト値を持たない読み取り専用プロパティである。

参照

TotalTitleTime

CurrentTitle プロパティ

MSWebDVD オブジェクト

現在再生しているタイトルの番号を取得する。

構文

[ iCurTitle = ] MSWebDVD.CurrentTitle

可能な値

iCurTitle 現在のディスク タイトルを表す 1 ～ 99 の整数値。

このプロパティは、デフォルト値を持たない読み取り専用プロパティである。

参照

TitlesAvailable

CurrentVolume プロパティ

MSWebDVD オブジェクト

現在のルート ディレクトリのボリューム番号を取得する。

構文

[ iCurVolume = ] DVD.CurrentVolume

可能な値

iCurVolume 現在の DVD ボリュームを表す整数値。複数ボリュームのセットに含まれるディスクでは、iCurVolume が 0 より大きくなければならない。

このプロパティは、デフォルト値を持たない読み取り専用プロパティである。

参照

VolumesAvailable

CursorType プロパティ

MSWebDVD オブジェクト

現在のカーソルの種類を設定または取得する。

構文

[ iCursorType = ] MSWebDVD.CursorType

可能な値

iCursorType カーソルの種類を表す整数値。

このプロパティとして可能な値は次のとおりである。
矢印 (Arrow) | 0
拡大 (Zoom In) | 1
縮小 (Zoom Out) | 2
手のひら (Hand) | 3
なし (None) | -1

このプロパティは、デフォルト値が 0 の読み書き可能なプロパティである。

注意

画像がズームインされているときに CursorType を手のひら (Hand) (0x3) に設定すると、アプリケーションがドラッグ モードに切り替わり、ユーザーがビデオ表示領域内でイメージを移動できるようになる。

DefaultAudioLanguage プロパティ

MSWebDVD オブジェクト

デフォルトのオーディオ言語を取得する。

構文

[ iLang = ] MSWebDVD.DefaultAudioLanguage

可能な値

iLang デフォルト オーディオ言語に対応する主言語 ID が格納された LCID 値。主な値の一覧、および LCID からの主言語 ID の抽出方法を示すサンプル コードについては、｢LCID の操作｣を参照すること。

このプロパティは、デフォルト値を持たない読み取り専用プロパティである。

参照

SelectDefaultAudioLanguage

DefaultAudioLanguageExt プロパティ

MSWebDVD オブジェクト

デフォルトの DVD オーディオ言語エクステンションを取得する。

構文

[ iLangExt = ] MSWebDVD.DefaultAudioLanguageExt

可能な値

iLangExt デフォルトのオーディオ言語エクステンションを示す整数値。可能な値については、「注意」を参照すること。

注意

このプロパティは、デフォルト値を持たない読み取り専用プロパティである。次の一覧は、DVD オーディオ言語エクステンションとして可能な値である。

エクステンション | 値
指定なし (NotSpecified) | 0
キャプション (Captions) | 1
視覚障害者向け (VisuallyImpaired) | 2
ディレクター コメント 1 (DirectorComments1) | 3
ディレクター コメント 2 (DirectorComments2) | 4

参照

SelectDefaultAudioLanguage

DefaultMenuLanguage プロパティ

MSWebDVD オブジェクト

デフォルトのメニュー言語を取得する。

構文

[ iLang = ] MSWebDVD.DefaultMenuLanguage

可能な値

iLang デフォルト オーディオ言語に対応する主言語 ID が格納された LCID 値。主な値の一覧、および LCID からの主言語 ID の抽出方法を示すサンプル コードについては、｢LCID の操作｣を参照すること。

注意

このプロパティは、デフォルト値を持たない読み書き可能なプロパティである。

DefaultSubpictureLanguage プロパティ

MSWebDVD オブジェクト

デフォルトのサブピクチャ言語を取得する。

構文

[ iLang = ] MSWebDVD.DefaultSubpictureLanguage

可能な値

iLang デフォルト オーディオ言語に対応する主言語 ID が格納された LCID 値。主な値の一覧、および LCID からの主言語 ID の抽出方法を示すサンプル コードについては、｢LCID の操作｣を参照すること。

このプロパティは、デフォルト値を持たない読み取り専用プロパティである。

参照

SelectDefaultSubpictureLanguage

DefaultSubpictureLanguageExt プロパティ

MSWebDVD オブジェクト

デフォルトの DVD サブピクチャ言語エクステンションを取得する。

構文

[ iLangExt = ] MSWebDVD.DefaultSubpictureLanguageExt

可能な値

iLangExt デフォルトの DVD サブピクチャ言語エクステンションを示す整数値。

注意

このプロパティは、デフォルト値を持たない読み取り専用プロパティである。次の表は、可能な値である。

エクステンション | 値
指定なし | 0
キャプション (ノーマル) | 1
キャプション (大) | 2
キャプション (子供向け) | 3
クローズド キャプション (ノーマル) | 5
クローズド キャプション (大) | 6
クローズド キャプション (子供向け) | 7
強制 | 9
ディレクター コメント (ノーマル) | 13
ディレクター コメント (大) | 14
ディレクター コメント (子供向け) | 15

参照

SelectDefaultSubpictureLanguage

DeleteBookmark メソッド

MSWebDVD オブジェクト

保存したブックマークを削除する。

構文

MSWebDVD.DeleteBookmark();

戻り値

戻り値なし。

注意

同時に設定できるブックマークは 1 つだけである。

DisableAutoMouseProcessing プロパティ

MSWebDVD オブジェクト

MSWebDVD オブジェクトのマウス処理機能を有効または無効にする。

構文

[ bMouseProcessing = ] MSWebDVD.DisableAutoMouseProcessing

可能な値

bMouseProcessing デフォルトのマウス処理を無効にするかどうかを示すブール値。

注意

このプロパティは、デフォルト値が FALSE の読み書き可能なプロパティである。

MSWebDVD オブジェクトは、デフォルトで、DVD のスクリーン上のメニューにおけるマウス操作を自動的に処理する。アプリケーションで特別なプログラミングをしないでも、ユーザーがメニュー ボタンを強調表示し、アクティブにすることができる。このデフォルトのマウス処理機能をオフにするには、このプロパティを TRUE に設定する。自動のマウス処理をオフにする場合には、アプリケーションで、ボタン関連の各種メソッドおよびプロパティを使用して、スクリーン上のメニューにおけるマウスの移動およびクリックを処理する必要がある。また、DisableAutoMouseProcessing が FALSE に設定されていても、ボタン関連のメソッドを使用して自動のマウス処理をオーバーライドすることができる。

DVDAdm プロパティ

MSWebDVD オブジェクト

アプリケーションおよびユーザーの情報を保存するメソッドおよびプロパティが格納された MSDVDAdm オブジェクトへのアクセスを提供する。

構文

MSWebDVD.DVDAdm

注意

このプロパティは、デフォルト値を持たない読み取り専用プロパティである。MSDVDAdm オブジェクトの参照を独自に作成する必要はない。オブジェクトのメソッドおよびプロパティにアクセスするには、次のように DVDAdm プロパティを使用する。

DVD.DVDAdm.DisableScreenSaver = true;

DVDDirectory プロパティ

MSWebDVD オブジェクト

現在の DVD ボリュームの現在のディレクトリを設定または取得する。

構文

[ sDirPath = ] MSWebDVD.DVDDirectory

可能な値

sDirPath DVD のルート ディレクトリのパスを示す文字列値。

注意

このプロパティは、デフォルト値を持たない読み書き可能なプロパティである。システムに DVD ドライブが複数あるときに、ルート パスを設定するには、このメソッドを使用する。システムにあるドライブが 1 台のみで、そのドライブ文字が C より大きい場合には、MSWebDVD オブジェクトがルート パスを自動的に検索する。標準の DVD ビデオ ディスクでは、たとえば次のように、ルート パスに video_ts ディレクトリが含まれていなければならない。

MSWebDVD.DVDDirectory = "e:\\video_ts";

一部の DVD ボリュームでは、ビデオが video_ts 以外のディレクトリに格納されていることがある。たとえば、ディスクのサブディレクトリに追加の "DVD ボリューム" (通常は VIDEO_TS ディレクトリに格納される .IFO、VOB および .BUP ファイルのセット) が配置されている場合などが考えられる。このディレクトリを指すようにルートを変更すると、MSWebDVD がその独立した DVD ボリューム上で動作するようになる。VIDEO_TS ルートにあるタイトルとは別の、新しいメニューやタイトルなどのセットが利用可能になり、VIDEO_TS ルートはアクセスできない。このようなディレクトリは、"隠しディレクトリ" と呼ばれる。次の例は、隠しディレクトリをルートとして設定する方法を示す。"hidden" は、ディスクの作者がディレクトリに付けた任意の名前を示すプレースホルダである。

MSWebDVD.DVDDirectory = "d:\\webdvd\\hidden";

MSWebDVD.DVDTimeCode2bstr メソッド

MSWebDVD オブジェクト

ディスク上の現在時間を示す文字列を取得する。

構文

[ sTimeCode = ] MSWebDVD.DVDTimeCode2bstr(nTimeCode);

パラメータ

nTimeCode EC_DVD_CURRENT_HMSF_TIME イベントを通じて取得される、タイトルの開始タイムに対するディスク上の現在時間を表す数。

戻り値

現在の再生時間を定義する 11 文字の文字列を返す。フォーマットは "hh:mm:ss:ff" (時、分、秒、フレーム)。

注意

このプロパティは、読み取り専用プロパティである。

参照

DVD イベント通知の処理

DVDUniqueID プロパティ

MSWebDVD オブジェクト

現在のディスクを一意に識別する、システムで生成された番号を取得する。

構文

[ iDiscID = ] MSWebDVD.DVDUniqueID

可能な値

iDiscID 現在のディスクを一意に識別する整数値。

このプロパティは、デフォルト値を持たない読み取り専用プロパティである。

注意

この識別子 (ID) は、完全に一意ではないが、実用上は一意なものと見なすことができる。ID は、ディスクの複製すべてに適用される。つまり、1 つのムービーのコピーはすべて同じ ID を持つ。また、ID は、BCA 値ではなくファイル サイズ、日付、およびその他の情報に基づいて決定される。

Eject メソッド

MSWebDVD オブジェクト

ドライブの DVD の取り出し/挿入を行う。

構文

MSWebDVD.Eject();

戻り値

戻り値なし。

注意

DVD ドライブによっては、このメソッドがトグル動作をし、呼び出すたびに取り出しと挿入の動作が切り替わる。この動作はハードウェアに依存する。

EnableResetOnStop プロパティ

MSWebDVD オブジェクト

フィルタ グラフが停止状態から移行するときに再生をどのように再開するかを決定する値を、設定または取得する。

構文

[ bEnableReset = ] MSWebDVD.EnableResetOnStop

可能な値

bEnableReset フィルタ グラフの停止後に MSWebDVD オブジェクトが再生を再開する位置を示すブール値。TRUE は、DVD ナビゲータがリセット後にディスクの最初から再生を開始することを意味する。FALSE は、これまでに再生された最後の位置から再開することを意味する。

注意

このプロパティは、デフォルト値が TRUE の読み書き可能なプロパティである。

FramesPerSecond プロパティ

MSWebDVD オブジェクト

現在の DVD タイトルのビデオ フレーム レートを取得する。

構文

[ iFramesPerSec = ] MSWebDVD.FramesPerSecond

可能な値

iFramesPerSec ビデオのフレーム レートを表す整数値。25 または 30 フレーム/秒。

注意

このプロパティは、デフォルト値を持たない読み取り専用プロパティである。NTSC ビデオ信号は 30 フレーム/秒で表示される。PAL は 25 フレーム/秒で表示される。ディスクは、NTSC と PAL のどちらかで再生するようにエンコードされ、両方で再生することはできない。

FullScreenMode プロパティ

MSWebDVD オブジェクト

表示がフルスクリーン モードかどうかを示す値を設定または取得する。

構文

[ bFullScreen = ] MSWebDVD.FullScreenMode

可能な値

bFullScreen フルスクリーン再生を有効にするか無効にするかを示すブール値。TRUE は、フルスクリーン モードを有効にすることを意味する。

注意

このプロパティは、デフォルト値が false の読み書き可能なプロパティである。

GetAudioLanguage メソッド

MSWebDVD オブジェクト

指定されたオーディオ ストリーム上の利用可能な言語を示す文字列を取得する。

構文

[ slang = ] MSWebDVD.GetAudioLanguage(iStream);

パラメータ

iStream 現在のタイトル内のオーディオ ストリーム番号を指定する整数値。

戻り値

現在のタイトル内のオーディオ ストリームの言語を識別する、人が読むことができる文字列を返す。

GetButtonAtPosition メソッド

MSWebDVD オブジェクト

ボタンを選択またはアクティブにせずに、指定された座標にあるボタンの番号を取得する。

構文

[ iButton = ] MSWebDVD.GetButtonAtPosition(xPos, yPos);

パラメータ

xPos | マウス ポインタの x 座標を指定する整数値。
yPos | マウス ポインタの y 座標を指定する整数値。

戻り値

指定された位置にあるボタンを示す整数値を返す (ある場合)。

注意

指定された座標にボタンがない場合、このメソッドは 0 を返す。DisableAutoMouseProcessing を TRUE に設定した後、カスタム マウス ハンドリングを実装する場合は、このメソッドを使用する。

参照

ActivateButton、ButtonsAvailable、CurrentButton、GetButtonRect、SelectAndActivateButton、SelectAtPosition

GetButtonRect メソッド

MSWebDVD オブジェクト

指定されたボタンの矩形をウィンドウ座標で取得する。

構文

[ oButton = ] MSWebDVD.GetButtonRect(iButton);

パラメータ

iButton ボタン番号を指定する整数値。

戻り値

矩形を定義する DVDRect オブジェクトを返す。

注意

DisableAutoMouseProcessing を TRUE に設定した後、カスタム マウス ハンドリングを実装する場合は、このメソッドを使用する。

参照

ButtonsAvailable、CurrentButton、ActivateButton、SelectAndActivateButton、SelectAtPosition

GetClipVideoRect メソッド

MSWebDVD オブジェクト

ビデオ表示用に現在定義されているクリッピング矩形を取得する。

構文

[ oClipRect = ] MSWebDVD.GetClipVideoRect();

戻り値

矩形を定義する DVDRect オブジェクトを返す。

参照

SetClipVideoRect

GetDelayTime メソッド

MSWebDVD オブジェクト

MSWebDVD オブジェクトに関連付けられたツールチップに対応する遅延時間を取得する。

構文

[ iDelay = ] MSWebDVD.GetDelayTime();

戻り値

ツールチップの遅延時間 (ミリ秒単位) を示す整数値を返す。

参照

SetDelayTime

GetDVDTextLanguageLCID メソッド

MSWebDVD オブジェクト

指定されたテキスト ブロックのロケール識別子 (LCID) を取得する。

構文

[ iLCID = ] MSWebDVD.GetDVDTextLanguageLCID(iLangIndex);

パラメータ

iLangIndex ディスク上のテキスト言語ブロックを識別する整数値。

戻り値

テキストに使用される言語を示す情報が格納された LCID 値を返す。LCID からの主言語コードの抽出については、｢LCID の操作｣を参照すること。

注意

補足のテキストは、ディスク上の連続ブロックに格納されている。それぞれの言語が 1 つのテキスト ブロックを持つ。アプリケーションでは、これらのブロックをインデックスで指定する。インデックスは、GetDVDTextNumberOfLanguages で返される値より小さくなければならない。

参照

GetLangFromLangID、DVD テキスト文字列の操作

GetDVDTextNumberOfLanguages メソッド

MSWebDVD オブジェクト

ディスク上の利用可能なテキスト言語数を取得する。

構文

[ iLanguages = ] MSWebDVD.GetDVDTextNumberOfLanguages();

戻り値

利用可能なテキスト言語の数を示す整数値を返す。

参照

DVD テキスト文字列の操作

GetDVDTextNumberOfStrings メソッド

MSWebDVD オブジェクト

指定された言語に利用可能なテキストの数を取得する。

構文

[ iStrings = ] MSWebDVD.GetDVDTextNumberOfStrings(iLangIndex);

パラメータ

iLangIndex 言語を識別する整数値。有効な範囲は、0 から、GetDVDTextNumberOfLanguages で返される値から 1 引いた値まで。

戻り値

指定された言語で格納された文字列の数を示す整数値を返す。

参照

DVD テキスト文字列の操作

GetDVDTextString メソッド

MSWebDVD オブジェクト

指定されたテキストを取得する。

構文

[ sText = ] MSWebDVD.GetDVDTextString(iLangIndex, iStringIndex);

パラメータ

iLangIndex | 言語のインデックスを指定する整数値。
iStringIndex | テキストのインデックス番号を指定する整数値。

戻り値

iStringIndex で指定された文字列を返す。

参照

GetDVDTextNumberOfLanguages、DVD テキスト文字列の操作

GetDVDTextStringType メソッド

MSWebDVD オブジェクト

指定された DVD テキストに格納された情報の種類を示す値を取得する。

構文

[ iStringType = ] MSWebDVD.GetDVDTextStringType(iLangIndex, iStringIndex);

パラメータ

iLangIndex | テキストの言語を指定する整数値。
iStringIndex | テキストのインデックス番号を指定する整数値。

戻り値

文字列に格納された情報の種類を示す整数値を返す。

注意

テキストの種類とその意味の一覧については、｢DVD テキスト文字列の操作｣を参照すること。

GetGPRM メソッド

MSWebDVD オブジェクト

指定された一般パラメータ レジスタを取得する。

構文

[ iGPRM = ] MSWebDVD.GetGPRM(iIndex);

パラメータ

iIndex 取得レジスタを示す 0 ～ 15 の整数値。

戻り値

指定されたレジスタに対応する整数値を返す。

注意

このメソッドには、MSWebDVD オブジェクトを使用した DVD のナビゲーション機能または再生機能は必要ない。このメソッドは、DVD の仕様を十分に理解したユーザーが高度な機能を実装するために提供される。GPRM を使用して、任意の値を格納し、自由に読み書きすることができる。ただし、GPRM はディスク コマンドの格納にも使用されるので、SetGPRM を使用して内容を変更した場合、それによって引き起こされる動作は予測不可能である。

参照

SetGPRM

GetKaraokeChannelAssignment メソッド

MSWebDVD オブジェクト

カラオケ チャンネルのスピーカへの割り当てを示す値を取得する。

構文

[ iAssignment = ] MSWebDVD.GetKaraokeChannelAssignment(iStream , iChannel);

パラメータ

iStream | オーディオ ストリームを指定する整数値。
iChannel | チャンネルを指定する整数値。

戻り値

指定されたチャンネルへのスピーカの割り当てを示す整数を返す。iAssignment として可能な値は次のとおりである。
2 | チャンネルが左および右のスピーカに割り当てられている。
3 | チャンネルが左、右、および中央のスピーカに割り当てられている。
4 | チャンネルが左、右、およびオーディオ 1 のスピーカに割り当てられている。
5 | チャンネルが左、右、中央、およびオーディオ 1 のスピーカに割り当てられている。
6 | チャンネルが左、右、およびオーディオ 2 のスピーカに割り当てられている。
7 | チャンネルが左、右、中央、およびオーディオ 2 のスピーカに割り当てられている。

参照

KaraokeAudioPresentationMode

GetKaraokeChannelContent メソッド

MSWebDVD オブジェクト

指定されたストリームの指定されたカラオケ チャンネルのコンテンツの種類を示す値を取得する。

構文

[ iContent = ] MSWebDVD.GetKaraokeChannelContent(iStream, iChannel);

パラメータ

iStream | オーディオ ストリームを指定する 0 ～ 7 の整数値。
iChannel | iStream 内のカラオケ チャンネルを指定する整数値。

各チャｚンネルに指定可能な値は次のとおりである。

ガイド音声 (Guide Vocal) 1 | 0x0001
ガイド音声 (Guide Vocal) 2 | 0x0002
ガイド メロディ (Guide Melody) 1 | 0x0004
ガイド メロディ (Guide Melody) 2 | 0x0008
ガイド メロディ (Guide Melody) A | 0x0010
ガイド メロディ (Guide Melody) B | 0x0020
サウンド エフェクト (Sound Effect) A | 0x0040
サウンド エフェクト (Sound Effect) B | 0x0080

戻り値

カラオケ チャンネルのコンテンツを各ビットが示す整数値を返す。

注意

DVD オーディオ チャンネルの番号は 0 から始まり、チャンネル 2、3、および 4 は外部カラオケ チャンネルとなっている。メソッドから戻った後、iContent のビットごとの AND 演算を実行して、各チャンネルのコンテンツを判断する。1 つのチャンネルに記録されているコンテンツの種類は 1 つとは限らないため、一致するものが見つかっても、その他の可能な値をすべてテストしなければならない。

次のサンプル コードは、すべての iContent を可能な値それぞれについてテストする方法を示している。

    if(iContent & 0x0001)
        {
            // チェック ボックスまたはその他の UI コントロールをオンにして、
            // このチャンネルにガイド音声 1 があることを示す。
        }
    if(iContent & 0x0002)
        {
            // チェック ボックスまたはその他の UI コントロールをオンにして、
            // このチャンネルにガイド音声 2 があることを示す。
        }
    if(iContent & 0x0004)
        {
            // チェック ボックスまたはその他の UI コントロールをオンにして、
            // このチャンネルにガイド メロディ 1 があることを示す。
        }

    // 各チャンネルの可能な値それぞれについて繰り返す。

ユーザーは、各チャンネルのコンテンツを知ったうえで、必要に応じてボリュームを調整したり個々のチャンネルのオン/オフを切り替えたりできなければならない。アプリケーションにこの機能を実装するには、KaraokeAudioPresentationMode プロパティを使用する。

注 : カラオケ ディスクを再生するには、ユーザーのシステムのオーディオ デコーダが、DirectShow 8 のカラオケ実装と互換でなければならない。

GetLangFromLangID メソッド

MSWebDVD オブジェクト

所定の主言語 ID に対応する人が読むことができる文字列を取得する。

構文

[ sLanguage = ] MSWebDVD.GetLangFromLangID(iPrimaryLangID)

パラメータ

iPrimaryLangID 主言語 ID を指定する整数。可能な値の主な一覧については、「LCID の操作」を参照すること。

戻り値

iPrimaryLangID が有効な場合は、アプリケーションのユーザー インターフェイスに表示できる言語を文字列で返す。iPrimaryLangID が無効な場合は、エラー コードを返す。

注意

このメソッドの名前は GetLangFromLangID だが、呼び出し元から実際に渡すパラメータは、主言語 ID であり、言語 ID ではない。

参照

LCID の操作、GetAudioLanguage、GetDVDTextLanguageLCID

GetNumberOfChapters メソッド

MSWebDVD オブジェクト

指定されたタイトルに含まれるチャプターの数を取得する。

構文

iChapters = MSWebDVD.GetNumberOfChapters(iTitle);

パラメータ

iTitle タイトルを指定する整数値。

戻り値

チャプター数を示す 1 ～ 999 の整数値を返す。

GetPlayerParentalCountry メソッド

MSWebDVD オブジェクト

MSWebDVD オブジェクトに設定された現在の国を取得する。

構文

iCountryCode = MSWebDVD.GetPlayerParentalCountry();

戻り値

国別コードを表す整数値を返す。

参照

ペアレンタル ロック レベルの適用、GetPlayerParentalLevel、GetTitleParentalLevels、SelectParentalCountry、SelectParentalLevel

GetPlayerParentalLevel メソッド

MSWebDVD オブジェクト

MSWebDVD オブジェクトに設定されたペアレンタル ロック レベルを取得する。

構文

[ iLevel = ] MSWebDVD.GetPlayerParentalLevel();

戻り値

DVD ナビゲータに設定された現在のペアレンタル ロック レベルを示す整数値を返す、あるいはペアレンタル ロックが使用不可なら -1 。

注意

プレーヤー アプリケーションには、ペアレンタル ロックを使用する義務がある。プレーヤーのペアレンタル ロック レベルは、アプリケーションから設定し、現在のユーザーが見ることができる最も高いペアレンタル ロック レベルを指定するために使用する。DVD ナビゲータは、新しいペアレンタル ロック レベルが見つかったとき、新しいペアレンタル ロック レベルが SelectParentalLevel を通じてアプリケーションから設定されたペアレンタル ロック レベルより高いかどうかを、このメソッドを使用して判断する。

参照

ペアレンタル ロック レベルの適用、GetTitleParentalLevels、GetPlayerParentalCountry、SelectParentalCountry、SelectParentalLevel

GetSPRM メソッド

MSWebDVD オブジェクト

指定されたシステム パラメータ レジスタを取得する。

構文

[ iSPRM = ] MSWebDVD.GetSPRM(iIndex);

パラメータ

iIndex 値を取得するレジスタを指定する 0 ～ 23 の整数値。

戻り値

指定されたレジスタの内容を表す整数値を返す。

注意

ディスクはシステム パラメータ レジスタ (SPRM) を制御する。プレーヤー アプリケーションでは、標準的なナビゲーション機能のために、これらのレジスタにアクセスする必要はない。SPRM は、プレーヤーの状態を表す。それぞれの意味は、ユーザー設定、ディスク コマンド、およびアプリケーションからは直接制御できないその他の場面で設定される。SPRM は、アプリケーションから読み取れるが、書き込むことができない。SPRM を効率よく使用するには、DVD ナビゲーション コマンドについてこのドキュメントより詳しい情報が必要になる場合がある。次の一覧は各レジスタの内容である。レジスタ内容の詳細については、「IDVDInfo2::GetAllSPRMs」を参照すること。

レジスタ | 内容 | レジスタ | 内容 | レジスタ | 内容
0 | メニュー言語コード | 1 | オーディオ ストリーム番号 | 2 | サブピクチャ ストリーム番号
3 | 現在のアングル番号 | 4 | 現在のタイトル番号 | 5 | タイトル番号
6 | PGC 番号 | 7 | 現在のチャプター番号 (PTT) | 8 | 強調表示されているボタンの番号
9 | ナビゲーション タイマ | 10 | ナビゲーション タイマに対応する PGC ジャンプ | 11 | カラオケ オーディオのプレゼンテーション モード
12 | PML の国別コード | 13 | PML | 14 | ビデオ設定
15 | オーディオ能力 | 16 | オーディオ言語 | 17 | オーディオ言語エクステンション
18 | サブピクチャ言語 | 19 | サブピクチャ言語エクステンション | 20 | プレーヤーの地域コード
21 | 予約済み | 22 | 予約済み | 23 | 予約済み

参照

GetGPRM、SetGPRM

GetSubpictureLanguage メソッド

MSWebDVD オブジェクト

指定されたサブピクチャ ストリームの言語を取得する。

構文

[ sLang = ] MSWebDVD.GetSubpictureLanguage(iStream);

パラメータ

iStream テキスト言語を取得するサブピクチャ ストリームの番号を指定する整数値。

戻り値

現在のタイトル内のオーディオ ストリームの言語を識別する、人が読むことができる文字列を返す。

GetTitleParentalLevels メソッド

MSWebDVD オブジェクト

指定されたタイトルのペアレンタル ロック レベル数を取得する。

構文

[ iLevels = ] MSWebDVD.GetTitleParentalLevels(iTitle);

パラメータ

iTitle タイトルを指定する整数値。

戻り値

指定されたタイトルに設定されたペアレンタル ロック レベル (PML) を各ビットが示す整数値を返す。

注意

タイトル全体と異なる PML を持つチャプター (またはチャプターより短いセグメント) が、タイトル内に含まれていることがある。このメソッドを使用して、特定のタイトルを再生するときに現れるすべての PML を判断する。返される整数は、下の一覧に定義されているビット フラグを組み合わせたものである。iLevels と可能な値それぞれのビットごとの AND 演算を実行する。演算の結果が TRUE になる場合、このタイトルのどこかにその PML が現れることを意味する。

可能なレベル | 16 進値
DVD ペアレンタル ロック レベル 1 | 0x100
DVD ペアレンタル ロック レベル 2 | 0x200
DVD ペアレンタル ロック レベル 3 | 0x400
DVD ペアレンタル ロック レベル 4 | 0x800
DVD ペアレンタル ロック レベル 5 | 0x1000
DVD ペアレンタル ロック レベル 6 | 0x2000
DVD ペアレンタル ロック レベル 7 | 0x4000
DVD ペアレンタル ロック レベル 8 | 0x8000
次のサンプル コードは、タイトル 1 の PML をテストする方法を示す。この情報の 1 つの目的は、タイトルに定義された最も高い PML と現在のユーザーに割り当てられた PML とを比較し、指定されたタイトルを再生すべきかどうか判断することにある。
iLevels = oDVD.GetTitleParentalLevels(1);
if(iLevels & 0x100)
 // このタイトルには PML 1 が定義されている。
if(iLvels & 0x200)
   // このタイトルには PML 2 が定義されている。
if(iLevels & 0x400)
  // このタイトルには PML 3 が定義されている。
...   // レベル 8 まで繰り返す。

参照

ペアレンタル ロック レベルの適用、SelectParentalLevel、GetPlayerParentalCountry、GetPlayerParentalLevel、SelectParentalCountry

IsAudioStreamEnabled メソッド

MSWebDVD オブジェクト

指定されたオーディオ ストリームが現在のタイトルで有効かどうかを示す値を取得する。

構文

[ bEnabled = ] MSWebDVD.IsAudioStreamEnabled(iStream)

パラメータ

iStream オーディオ ストリームを指定する 0 ～ 7 の整数値。

戻り値

指定されたオーディオ ストリームが現在のタイトルに利用可能かどうかを示すブール値を返す。TRUE は利用可能なことを意味する。

注意

ディスクには、独立した 8 つまでのオーディオ ストリームがあるが、個々のストリームが必ずしもすべてのタイトルに利用可能とは限らない。たとえば、本編には英語、スペイン語、日本語の 3 つのオーディオ ストリームがあるが、"予告編" には英語のオーディオ ストリームしかない可能性がある。CurrentAudioStream プロパティを設定するときには、その前にタイトルにそのストリームが利用可能かどうかを必ず検査する。

IsSubpictureStreamEnabled メソッド

MSWebDVD オブジェクト

指定されたサブピクチャ ストリームが現在のタイトルで有効かどうかを示す値を取得する。

構文

[ bEnabled = ] MSWebDVD.IsSubpictureStreamEnabled(iStream)

パラメータ

iStream サブピクチャ ストリームを指定する 0 ～ 31 の整数値 (またはミュートされたビットレートの低いストリームを表す 63)。

戻り値

指定されたオーディオ ストリームか現在のタイトルで利用可能かどうかを示すブール値を返す。TRUE は利用可能なことを意味する。

注意

ディスクには 32 までのサブピクチャ ストリームが入るが、個々のストリームが必ずしもすべてのタイトルに利用可能とは限らない。CurrentSubpictureStream プロパティを設定するときには、その前にタイトルにそのストリームが利用可能かどうかを必ず検査する。

GetVideoSize メソッド

MSWebDVD オブジェクト

ネイティブ ビデオのディメンジョンを取得する。

構文

[ oSizeRect = ] MSWebDVD.GetVideoSize();

戻り値

(左上の) x、(左上の) y、Width、Height の 4 つの読み書き可能なプロパティが格納された DVDRect オブジェクトを返す。x プロパティおよび y プロパティには 0 が設定され、ほかの 2 つのプロパティにはディスクに明記されたビデオ矩形の幅および高さが反映される。

KaraokeAudioPresentationMode プロパティ

MSWebDVD オブジェクト

外部カラオケ チャンネルの左右スピーカ ミキシング比を設定または取得する。

構文

[iMode ] = MSWebDVD.KaraokeAudioPresentationMode

可能な値

iMode 外部カラオケ チャンネルの左右スピーカへのダウンミックスを指定するビット フラグの組み合わせが格納された整数値。「注意」を参照すること。

注意

このプロパティは、デフォルト値が 0 の読み書き可能なプロパティである。

オーディオ チャンネルの番号は 0 から始まる。したがって、チャンネル 0 および 1 は、通常、左右のスピーカ チャンネルを表し、チャンネル 2 ～ 4 は 3 つの外部カラオケ チャンネルである。MSWebDVD オブジェクトは、カラオケ モードに切り替わると、チャンネル 2 以降を自動的にミュートする。外部チャンネルを、左、右、または左右両方 (両方のビットをオンにする) のスピーカに送る場合や、どちらのスピーカにも送らない (両方のビットをオフにする) 場合、それぞれに適したビットを設定するには、ビットごとの OR 演算を実行する。DVD ナビゲータがカラオケ モードに切り替わると、デフォルトでは、これらのビットがすべてオフになる。次の一覧は、ビットの値とその値に対応する操作を示す。

操作 | 値
チャンネル 2 を左のスピーカにダウンミックスする | 0x0004
チャンネル 3 を左のスピーカにダウンミックスする | 0x0008
チャンネル 4 を左のスピーカにダウンミックスする | 0x0010
チャンネル 2 を右のスピーカにダウンミックスする | 0x0400
チャンネル 3 を右のスピーカにダウンミックスする | 0x0800
チャンネル 4 を右のスピーカにダウンミックスする | 0x1000

次のサンプル コードは、ビットごとの OR 演算を使用して、チャンネル 2 を左のスピーカに、チャンネル 3 および 4 を右のチャンネルに送る方法を示す。

  var iMode = 0;
  iMode = 0x0004 | 0x0800 | 0x1000 ;
  DVD.KaraokeAudioPresentationMode = iMode;

KaraokeAudioPresentationMode の値を取得するには、次のように、可能な値とのビットごとの AND 演算を実行する。

  if (DVD.KaraokeAudioPresentationMode & 0x0004)
  {
     // チャンネル 2 は左のスピーカに送られている。
  }
  if (DVD.KaraokeAudioPresentationMode & 0x0008)
  {
     // チャンネル 3 は左のスピーカに送られている。
  }
  // 可能な値すべてについて繰り返す。

Mute プロパティ

MSWebDVD オブジェクト

オーディオ ストリーム出力のオン/オフを切り替える。

構文

[ bMute = ] MSWebDVD.Mute

可能な値

bMute オーディオ ストリームをミュートすべきかどうかを示すブール値。

注意

このプロパティは、デフォルト値が false の読み書き可能なプロパティである。

NotifyParentalLevelChange メソッド

MSWebDVD オブジェクト

一時ペアレンタル ロック レベル コマンドのイベント処理を有効または無効にする。

構文

MSWebDVD.NotifyParentalLevelChange(bNotify);

パラメータ

bNotify ディスク全体のレーティングより高いレーティングが指定されたビデオ セグメントが見つかったときに、MSWebDVD オブジェクトがアプリケーションに通知するかどうかを指定するブール値。

戻り値

戻り値なし。

注意

ペアレンタル ロック通知は、デフォルトでは無効になっている。これは、ディスクからの一時ペアレンタル ロック レベル コマンドは、可能ではあるが無視され、ディスクが途切れずに再生されることを意味する。ディスクからの一時ペアレンタル ロック レベル コマンドを処理するには、アプリケーションの初期化中にこのメソッドを呼び出す。有効にしたペアレンタル ロックを無効にするには、引数に FALSE を指定してこのメソッドを呼び出す。ペアレンタル ロックの詳細については、「AcceptParentalLevelChange」を参照すること。

参照

ペアレンタル ロック レベルの適用、SelectParentalLevel、GetTitleParentalLevels、GetPlayerParentalCountry、GetPlayerParentalLevel、SelectParentalCountry

Pause メソッド

MSWebDVD オブジェクト

再生を現在位置でポーズする。

構文

MSWebDVD.Pause();

戻り値

戻り値なし。

注意

既に再生がポーズしている場合、このメソッドは何も実行しない。

Play メソッド

MSWebDVD オブジェクト

現在の DVD タイトルを再生する。

構文

MSWebDVD.Play();

戻り値

戻り値なし。

注意

再生がポーズまたは停止していて EnableResetOnStop が TRUE の場合、Play を呼び出すと、通常の速度で現在位置から再生が再開する。再生が停止していて EnableResetOnStop が FALSE の場合、Play を呼び出すと、最初のタイトルの始めからディスクが再生される。

参照

Resume

PlayAtTime メソッド

MSWebDVD オブジェクト

現在のタイトルの指定された時間から再生を開始する。

構文

MSWebDVD.PlayAtTime(sTime);

パラメータ

sTime 再生を開始する時間を指定する文字列値。フォーマットは "hh:mm:ss:ff" (時、分、秒、フレーム)。

戻り値

戻り値なし。

参照

PlayAtTimeInTitle

PlayAtTimeInTitle メソッド

MSWebDVD オブジェクト

指定されたタイトルの指定された時間から再生を開始する。

構文

MSWebDVD.PlayAtTimeInTitle(sTime, iTitle);

パラメータ

sTime | 再生を開始する時間を指定する文字列値。フォーマットは "hh:mm:ss:ff" (時、分、秒、フレーム)。
iTitle | タイトルのインデックスを指定する整数。

戻り値

戻り値なし。

参照

CurrentTitle、PlayAtTime、TitlesAvailable

PlayBackwards メソッド

MSWebDVD オブジェクト

指定された速度で現在位置から逆方向再生を開始する。

構文

MSWebDVD.PlayBackwards(nSpeed);

パラメータ

nSpeed 再生の速度を指定する数値。この値は乗数であり、たとえば、1.0 は通常の再生速度、2.0 は倍の速度、0.5 は半分の速度を意味する。nSpeed が 1.0 以外の場合には、オーディオがミュートされ、サブピクチャがオフになる。

戻り値

戻り値なし。

参照

PlayForwards

PlayChapter メソッド

MSWebDVD オブジェクト

現在のタイトル内の指定されたチャプターから再生を開始する。

構文

MSWebDVD.PlayChapter(iChapter);

パラメータ

iChapter 現在のタイトル内でのチャプター インデックスを指定する整数値。

戻り値

戻り値なし。

注意

指定されたチャプターの最後に達すると、その後にまだチャプターがあれば、このメソッドは引き続きそれらのチャプターを再生する。指定したチャプターだけを再生するには、PlayChaptersAutoStop を使用する。

参照

PlayChapterInTitle

PlayChaptersAutoStop メソッド

MSWebDVD オブジェクト

指定されたタイトルの指定されたチャプターから指定されたチャプター数の再生を開始する。

構文

MSWebDVD.PlayChaptersAutoStop(iTitle, iChapter, iChapterCount);

パラメータ

iTitle | タイトルを指定する整数値。
iChapter | 開始チャプターを指定する整数値。
iChapterCount | 再生するチャプター数を指定する整数値。

戻り値

戻り値なし。

注意

最後のチャプターの再生が済むと、このメソッドは、アプリケーションに EC_DVD_CHAPTER_AUTOSTOP イベント通知が送られるようにする。

PlayChapterInTitle メソッド

MSWebDVD オブジェクト

指定されたタイトルの指定されたチャプターを再生する。

構文

MSWebDVD.PlayChapterInTitle(iTitle, iChapter);

パラメータ

iTitle | タイトルを指定する整数値。
iChapter | チャプターを指定する整数値。

注意

このメソッドは、指定されたチャプターから再生を開始し、いつまでも再生を続ける。特定のチャプターだけを再生するには、PlayChaptersAutoStop を使用する。

戻り値

戻り値なし。

PlayForwards メソッド

MSWebDVD オブジェクト

指定された速度で現在位置から順方向再生を開始する。

構文

MSWebDVD.PlayForwards(nSpeed);

パラメータ

nSpeed 再生の速度を指定する数値。この値は乗数であり、たとえば、1.0 は通常の再生速度、2.0 は倍の速度、0.5 は半分の速度を意味する。nSpeed が 1.0 以外の場合には、オーディオがミュートされ、サブピクチャがオフになる。

戻り値

戻り値なし。

参照

PlayBackwards

PlayNextChapter メソッド

MSWebDVD オブジェクト

現在のタイトルの次のチャプターから再生を開始する。

構文

MSWebDVD.PlayNextChapter();

戻り値

戻り値なし。

参照

PlayPrevChapter

PlayPeriodInTitleAutoStop メソッド

MSWebDVD オブジェクト

指定されたタイトルの指定された時間から指定された終了タイムまでの再生を開始する。

構文

MSWebDVD.PlayPeriodInTitleAutoStop(iTitle, sStartTime, sEndTime);

パラメータ

iTitle | タイトルを指定する整数値。
sStartTime | 開始タイムを指定する文字列。フォーマットは "hh:mm:ss:ff" (時、分、秒、フレーム)。
sEndTime | 終了タイムを指定する文字列。フォーマットは "hh:mm:ss:ff" (時、分、秒、フレーム)。

戻り値

戻り値なし。

参照

PlayChaptersAutoStop

PlayPrevChapter メソッド

MSWebDVD オブジェクト

現在のタイトルの直前のタイトルから再生を開始する。

構文

MSWebDVD.PlayPrevChapter();

戻り値

戻り値なし。

参照

PlayNextChapter

PlayState プロパティ

MSWebDVD オブジェクト

MSWebDVD オブジェクトの現在の状態を取得する。

構文

[ iState = ] MSWebDVD.PlayState

可能な値

iState DVD ナビゲータの現在の状態を表す整数値。-2 (未定義)、-1 (初期化されていない)、0 (停止)、1 (ポーズ)、2 (実行中) のいずれか。

このプロパティは、デフォルト値を持たない読み取り専用プロパティである。

注意

MSWebDVD オブジェクトは DirectShow DVD ナビゲータ フィルタを制御し、DVD ナビゲーションの実際の処理はこのフィルタが行う。このプロパティが参照するのは、実際には DVD ナビゲータの状態である。DVD ナビゲータには、上のようにいくつかの状態がある。PlayState プロパティは診断ツールとして利用できるが、通常、スクリプト アプリケーションから DVD ナビゲータの状態を監視する理由はない。

PlayTitle メソッド

MSWebDVD オブジェクト

指定されたタイトルの最初から再生を開始する。

構文

MSWebDVD.PlayTitle(iTitle);

パラメータ

iTitle タイトルを指定する整数値。

戻り値

戻り値なし。

参照

PlayPeriodInTitleAutoStop

PreferredSubpictureStream プロパティ

MSWebDVD オブジェクト

現在表示しているセッションの優先サブピクチャ ストリームを設定または取得する。

構文

[ iStream = ] MSWebDVD.PreferredSubpictureStream

可能な値

iStream MSWebDVD オブジェクト内の現在の優先サブピクチャ ストリームを表す整数値。この値は、Microsoft® Windows® レジストリ内にある現在のデフォルトの優先サブピクチャ ストリームと異なる場合がある。デフォルトの優先サブピクチャ ストリームは、DVDAdm.DefaultSubpictureLCID で設定する。

ReadyState プロパティ

MSWebDVD オブジェクト

MSWebDVD オブジェクトの ReadyState を取得する。

構文

[ iReadyState = ] MSWebDVD.ReadyState

可能な値

iReadyState コントロールの ReadyState を表す整数値。可能な値は、READYSTATE_UNINITIALIZED = 0、READYSTATE_LOADING = 1、READYSTATE_LOADED = 2、READYSTATE_INTERACTIVE = 3、READYSTATE_COMPLETE = 4 のいずれか。

注意

このプロパティは、デフォルト値を持たない読み取り専用プロパティである。

ReadyState プロパティは、Web ページに埋め込まれるオブジェクトで公開される。この値には次の意味がある。

READYSTATE_UNINITIALIZED | デフォルトの初期化状態。
READYSTATE_LOADING | オブジェクトはプロパティをロード中。
READYSTATE_LOADED | オブジェクトは初期化された。
READYSTATE_INTERACTIVE | オブジェクトは応答可能だが、利用できないデータがある。
READYSTATE_COMPLETE | オブジェクトはデータをすべて受け取った。

Render メソッド

MSWebDVD オブジェクト

DVD フィルタ グラフを初期化する。

構文

MSWebDVD. Render(iRender = 0);

パラメータ

iRender フィルタ グラフを破棄および再構築するかどうかを指定する整数値。指定しなかった場合、値は 0 と見なされる。0 は、フィルタ グラフが既に存在する場合に破棄および再構築しないことを意味する。グラフを破棄および再構築するには、1 を指定する。

戻り値

戻り値なし。

注意

Render メソッドを使用すると、MSWebDVD オブジェクトから、その基盤となる DirectShow フィルタ グラフを起動時に完全に初期化できる。初期化しておくと、ユーザーがディスクを再生またはメニューを表示するために最初にコマンドを発行したとき発生する若干の遅延をなくすことができる。ほかのメソッドを呼び出す前に、Render を呼び出す必要はない。たとえば、フィルタ グラフの初期化前にアプリケーションから PlayTitle を呼び出すと、MSWebDVD オブジェクトは、ディスク再生前に自動的に Render を呼び出す。

ReplayChapter メソッド

MSWebDVD オブジェクト

現在のチャプターの最初から再生を開始する。

構文

MSWebDVD.ReplayChapter();

戻り値

戻り値なし。

参照

PlayChapter、PlayChaptersAutoStop

RegionChange メソッド

MSWebDVD オブジェクト

DVD に関連付けられたリージョンをユーザーが変更するためのシステム ダイアログ ボックスを表示する。

構文

MSWebDVD.RegionChange();

注意

DVD ドライブのリージョンは、5 回しか変更できない。

戻り値

戻り値なし。

RestoreBookmark メソッド

MSWebDVD オブジェクト

現在のブックマークが示すディスク上の位置に MSWebDVD オブジェクトを移動し、オーディオ、ビデオ、およびサブピクチャの設定をすべて復元する。

構文

MSWebDVD.RestoreBookmark();

戻り値

戻り値なし。

Resume メソッド

MSWebDVD オブジェクト

メニュー表示後に再生を再開する。

構文

MSWebDVD.Resume();

戻り値

戻り値なし。

ReturnFromSubmenu メソッド

MSWebDVD オブジェクト

表示をサブメニューから親メニューに戻す。トップレベル メニューなら現在のタイトルに戻す。

構文

MSWebDVD.ReturnFromSubmenu();

戻り値

戻り値なし。

SaveBookmark メソッド

MSWebDVD オブジェクト

ユーザーが後で同じ場所に戻れるように、MSWebDVD オブジェクトの現在のディスク位置および状態を保存する。

構文

MSWebDVD.SaveBookmark();

戻り値

戻り値なし。

注意

ブックマークは、DVD ナビゲータの現在状態のスナップショットである。ここには、再生中のディスク位置や、選択しているオーディオ ストリームおよびサブピクチャ ストリームなどの情報が含まれる。ブックマークを保存すると、アプリケーションを終了し、コンピュータをシャットダウンしても、後から前とまったく同じ設定でディスクの続きを見ることができれる。ブックマークは同時に 1 つしか保存できない。SaveBookmark を呼び出すと、古いブックマークにオーバーライドされる。

参照

RestoreBookmark、ブックマークの保存と復元

SelectAndActivateButton メソッド

MSWebDVD オブジェクト

指定されたボタンを選択し、アクティブにする。

構文

MSWebDVD.SelectAndActivateButton(iButton);

パラメータ

iButton ボタンを指定する整数値。

戻り値

戻り値なし。

注意

DisableAutoMouseProcessing を TRUE に設定した後、カスタム マウス ハンドリングを実装する場合は、このメソッドを使用する。

このメソッドは、指定されたボタンを強調表示し、自動的にアクティブにする。

参照

ButtonsAvailable、CurrentButton、ActivateButton、GetButtonAtPosition、GetButtonRect、SelectAtPosition

SelectAtPosition メソッド

MSWebDVD オブジェクト

指定された (マウス ポインタの) 座標にあるメニュー ボタンを選択する。

構文

MSWebDVD.SelectAtPosition(xPos, yPos);

パラメータ

xPos | x 座標を指定する整数値。
yPos | y 座標を指定する整数値。

戻り値

戻り値なし。

注意

DisableAutoMouseProcessing を TRUE に設定した後、カスタム マウス ハンドリングを実装する場合は、このメソッドを使用する。

ボタンを選択すると、そのボタンがただ強調表示される。選択したボタンに関連付けられたコマンドを送るには、ActivateButton を呼び出す。

参照

ButtonsAvailable、CurrentButton、GetButtonAtPosition、GetButtonRect、SelectAndActivateButton

SelectDefaultAudioLanguage メソッド

MSWebDVD オブジェクト

MSWebDVD オブジェクト内の現在のデフォルト オーディオ言語を設定する。

構文

MSWebDVD.SelectDefaultAudioLanguage(iLang, iExt);

パラメータ

iLang | 言語を指定する整数の LCID 値。可能な値については、「LCID の操作」の一覧を参照すること。
iExt | DVD オーディオ言語エクステンションを指定する整数値。可能な値については、「注意」を参照すること。

注意

エクステンション | 値
指定なし (NotSpecified) | 0
キャプション (Captions) | 1
視覚障害者向け (VisuallyImpaired) | 2
ディレクター コメント 1 (DirectorComments1) | 3
ディレクター コメント 2 (DirectorComments2) | 4

戻り値

戻り値なし。

SelectDefaultSubpictureLanguage メソッド

MSWebDVD オブジェクト

MSWebDVD オブジェクト内の現在のデフォルト サブピクチャ言語を設定する。

構文

MSWebDVD.SelectDefaultSubpictureLanguage(iLang,iExt);

パラメータ

iLang | 言語を指定する整数値。
iExt | サブピクチャ言語エクステンションを指定する整数値。可能な値については、「注意」を参照すること。

戻り値

戻り値なし。

注意

サブピクチャ言語エクステンションは、サブピクチャに関する詳細情報を提供する。可能な戻り値は次のとおりである。

エクステンション | 値
指定なし | 0
キャプション (ノーマル) | 1
キャプション (大) | 2
キャプション (子供向け) | 3
クローズド キャプション (ノーマル) | 5
クローズド キャプション (大) | 6
クローズド キャプション (子供向け) | 7
強制 | 9
ディレクター コメント (ノーマル) | 13
ディレクター コメント (大) | 14
ディレクター コメント (子供向け) | 15

SelectLeftButton メソッド

MSWebDVD オブジェクト

表示されたメニューから左方向ボタンを選択する。

構文

MSWebDVD.SelectLeftButton();

戻り値

戻り値なし。

参照

ActivateButton、SelectLowerButton、SelectRightButton、SelectUpperButton

SelectLowerButton メソッド

MSWebDVD オブジェクト

表示されたメニューから下方向ボタンを選択する。

構文

MSWebDVD.SelectLowerButton();

戻り値

戻り値なし。

参照

ActivateButton、SelectLeftButton、SelectRightButton、SelectUpperButton

SelectParentalCountry メソッド

MSWebDVD オブジェクト

今後の再生に使用する国として、指定されたペアレンタル カントリを設定する。

構文

MSWebDVD.SelectParentalCountry(iCountry, sUserName, sPassword);

パラメータ

iCountry | 国を指定する整数値。
sUserName | 現在のログオン ユーザーを指定する文字列値 (現在は無視される)。
sPassword | アプリケーションのパスワードを指定する文字列値。

戻り値

戻り値なし。

注意

ペアレンタル カントリはペアレンタル ロック レベルの解釈を決定する。

参照

ペアレンタル ロック レベルの適用、SelectParentalLevel、NotifyParentalLevelChange、GetTitleParentalLevels、GetPlayerParentalCountry、GetPlayerParentalLevel、AcceptParentalLevelChange

SelectParentalLevel メソッド

MSWebDVD オブジェクト

今後の再生に使用するペアレンタル ロック レベルとして、指定されたペアレンタル ロック レベルを設定する。

構文

MSWebDVD.SelectParentalLevel(iLevel, sUserName, sPassword);

パラメータ

iLevel | ペアレンタル ロック レベルを指定する整数値 (1 ～ 8)。ペアレンタル ロックを無効にするには、iLevel に -1 を設定する。
sUserName | 現在のユーザーを指定する文字列値 (現在は無視される)。
sPassword | レジストリに現在格納されているパスワードを指定する文字列値。

戻り値

戻り値なし。

注意

このメソッドは、MSWebDVD オブジェクト内のペアレンタル ロック レベルを設定する。ユーザーが再生できるコンテンツはこのペアレンタル ロック レベルで決まる。高いレベルではレベルの低いコンテンツを再生できるが、低いレベルではレベルの高いコンテンツを再生できない。DVD の 8 つのペアレンタル ロック レベルが持つ正確な意味は国によって異なる。米国およびカナダの場合、レベルは MPAA (Motion Picture Association of America) のレーティング カテゴリに対応する。デフォルトでは、DVD ナビゲータのペアレンタル ロックは無効になっている。

参照

ペアレンタル ロック レベルの適用、SelectParentalCountry、NotifyParentalLevelChange、GetTitleParentalLevels、GetPlayerParentalCountry、GetPlayerParentalLevel、AcceptParentalLevelChange

SelectRightButton メソッド

MSWebDVD オブジェクト

表示されたメニューから右方向ボタンを選択する。

構文

MSWebDVD.SelectRightButton();

戻り値

戻り値なし。

参照

ActivateButton、SelectLeftButton、SelectLowerButton、SelectUpperButton

SelectUpperButton メソッド

MSWebDVD オブジェクト

表示されたメニューから上方向ボタンを選択する。

構文

MSWebDVD.SelectUpperButton();

戻り値

戻り値なし。

参照

ButtonsAvailable、CurrentButton、ActivateButton、GetButtonAtPosition、GetButtonRect、SelectAndActivateButton、SelectAtPosition、SelectLeftButton、SelectLowerButton、SelectRightButton

SetClipVideoRect メソッド

MSWebDVD オブジェクト

指定されたサブ矩形に合わせてビデオ表示をズームする。

構文

 DVD.SetClipVideoRect(oRect);

パラメータ

oRect クリッピング矩形を指定する DVDRect オブジェクト。

戻り値

戻り値なし。

注意

新しいクリッピング矩形を設定すると、オブジェクトがアプリケーションの表示ディメンジョン全体に合わせてその領域を拡大する。こうすると、画面の特定領域にズーム インするエフェクトが生成される。矩形を指定するには、新しい DVDRect オブジェクトを作成し、そのプロパティを設定する。

ビデオ表示には一般的に 720 x 540 の矩形を使用する。

参照

GetClipVideoRect

SetDelayTime

MSWebDVD オブジェクト

MSWebDVD オブジェクトに関連付けられたツールチップに対応する遅延時間を設定する。

構文

MSWebDVD.SetDelayTime(iDelayType, iNewVal)

パラメータ

iDelayType | 遅延の種類を指定する整数値。「注意」を参照すること。
iNewVal | 遅延時間を指定する整数値 (ミリ秒単位)。

戻り値

戻り値なし。

注意

次の一覧は、iDelayType として可能な値である。

TTDT_AUTOPOP = 0 | ポインタがツールの境界矩形内に一定時間留まると、[ツールチップ] ウィンドウが消去される。この時間の長さ (自動ポップアップの遅延時間) を設定する。デフォルト値に戻すには、iNewVal に -1 を設定する。
TTDT_INITIAL = 1 | ポインタがツールの境界矩形内に一定時間静止すると、[ツールチップ] ウィンドウが表示される。この時間の長さ (立ち上がりの遅延時間) を設定する。デフォルト値に戻すには、iNewVal に -1 を設定する。
TTDT_RESHOW = 2 | ポインタが別のツールに移動すると、一定時間後に次の [ツールチップ] ウィンドウが表示される。この時間の長さ (再表示の遅延時間) を設定する。デフォルト値に戻すには、iNewVal に -1 を設定する。
TTDT_AUTOMATIC = 3 | 3 つの遅延時間の割合をデフォルトに戻す。自動ポップアップ時間は初期時間の 10 倍、再表示時間は初期時間 1/5 である。このフラグを設定する場合、iNewVal に正の値を使用して初期遅延時間 (ミリ秒単位) を指定する。3 つの遅延時間すべてをそれぞれのデフォルト値に戻すには、iNewVal に負の値を設定する。

SetGPRM メソッド

MSWebDVD オブジェクト

指定された一般パラメータ レジスタに指定された値を設定する。

構文

MSWebDVD.SetGPRM(iIndex, nValue)

パラメータ

iIndex | 設定する一般パラメータ レジスタを指定する 0 ～ 15 の整数値。
iValue | レジスタに設定する新しい値を指定する整数。

注意

一般パラメータ レジスタ (GPRM) は、各ディスクが一時データの格納に自由に使用できる 16 ビット レジスタである。プレーヤー アプリケーションでは、MSWebDVD オブジェクトを使用して再生またはナビゲーションの標準的な制御のために、これらのレジスタにアクセスする必要はない。このメソッドは、進んだ機能を実装するプレーヤー アプリケーションのために提供される。DVD の仕様と、GPRM を使用してそのディスクがどのように再生されるかを完全に理解していない限り、GPRM を直接変更しないこと。GPRM の値を変更した場合、それによって引き起こされる動作は予測不可能である。

ShowCursor メソッド

MSWebDVD オブジェクト

MSWebDVD オブジェクトがフルスクリーン モードのときにカーソルを表示する。

構文

MSWebDVD.ShowCursor(bShow);

パラメータ

bShow カーソルを表示するかどうかを指定するブール値。

戻り値

戻り値なし。

注意

DVD の表示がフルスクリーン モードに切り替わると、3 ～ 5 秒でカーソルが消える。フルスクリーン モードでアプリケーションのコントロール ボタンが表示される場合、カーソルをもう一度表示するには、このメソッドを使用する。

ShowMenu メソッド

MSWebDVD オブジェクト

指定されたメニューを画面上に表示する。

構文

MSWebDVD.ShowMenu(iMenuID);

パラメータ

iMenuID メニューを指定する整数値。可能な値については、「注意」を参照すること。

戻り値

戻り値なし。

注意

iMenuID として可能な値は次のとおりである。
メニューの種類 | 値
タイトル (トップ) | 2
ルート | 3
サブピクチャ | 4
オーディオ | 5
アングル | 6
チャプター | 7

DVD のメニュー名は若干複雑である。[タイトル(title)] メニューは、ディスク全体のメイン メニューである Video Manager Menu の別名であり、通常、ここにディスク内の利用可能なビデオ タイトル セットがすべて表示される。[ルート(root)] メニューは、1 つのビデオ タイトル セットに対応するメニューである。ビデオ タイトル セットには、1 つ以上のタイトルが入っている。タイトル セット内の全タイトルは、同じ [サブピクチャ(Subpicture)] メニュー、[オーディオ(Audio)] メニュー、および [アングル(Angle)] メニューを共有する。

Step メソッド

MSWebDVD オブジェクト

DVD ビデオ ストリームを指定されたフレーム数だけ進める。

構文

MSWebDVD.Step(iFrames)

パラメータ

iFrames コマ送りするフレーム数を指定する整数値。

戻り値

戻り値なし。

注意

このメソッドを呼び出す前に、CanStep を呼び出してデコーダがコマ送りをサポートしているかどうかを判断する。

DVD ビデオを反転モードで再生しているときにこのメソッドを呼び出すと、デコーダが反転のコマ送りをサポートしていれば、コマ送りも反転で行われる。

StillOff メソッド

MSWebDVD オブジェクト

再生を再開し、静止モードをキャンセルする。

構文

MSWebDVD.StillOff();

戻り値

戻り値なし。

注意

ディスク上に明記された静止フレームが見つかると、DVD ナビゲータは、静止モードに切り替わり、EC_DVD_STILL_ON イベントを送ってアプリケーションに通知する。DVD ナビゲータの静止モードは、ユーザー操作の点でポーズ状態と異なる。StillOff を呼び出すと、静止モードからは再生に戻るが、ポーズ状態の DVD ナビゲータは再開しない。

Stop メソッド

MSWebDVD オブジェクト

再生を停止する。

構文

MSWebDVD.Stop();

戻り値

戻り値なし。

注意

EnableResetOnStop が TRUE に設定されている場合は、Stop を呼び出すと、DVD ナビゲータがフィルタ グラフの残り部分と共に停止状態に切り替わる。これは、ユーザーが次に [再生] ボタンを押すと、 ディスクの最初から再生が始まることを意味する。EnableResetOnStop が TRUE に設定されている場合は、ユーザーが次の Play コマンドを発行すると、最後に再生された位置から再生が再開する。

SubpictureOn プロパティ

MSWebDVD オブジェクト

サブピクチャの現在の状態 (オン/オフ) を設定または取得する。

構文

[ bState = ] MSWebDVD.SubpictureOn

可能な値

bState サブピクチャが表示されるかどうかを示すブール値。

注意

このプロパティは、クローズド キャプションの表示には影響しない。クローズド キャプションはビデオ ストリーム内に埋め込まれているが、DVD のサブピクチャは独立したストリームでトランスポートされる。

このプロパティは、デフォルト値が false の読み書き可能なプロパティである。

SubpictureStreamsAvailable プロパティ

MSWebDVD オブジェクト

現在のタイトル内の利用可能なサブピクチャ ストリーム数を取得する。

構文

[ iStreams = ] MSWebDVD.SubpictureStreamsAvailable

可能な値

iStreams 利用可能なオーディオ ストリーム数を表す整数値。

注意

このプロパティは、デフォルト値を持たない読み取り専用プロパティである。個々のストリームにその言語属性を照会するには、まずこのメソッドを呼び出して上限を取得する。ストリームの番号は 0 から始まる。

TitlesAvailable プロパティ

MSWebDVD オブジェクト

ディスク上の利用可能なタイトル数を取得する。

構文

[ iTitles = ] MSWebDVD.TitlesAvailable

可能な値

iTitles 利用可能なタイトル数を表す 1 ～ 99 の整数値。

注意

このプロパティは、デフォルト値を持たない読み取り専用プロパティである。

ToolTip プロパティ

MSWebDVD オブジェクト

マウス ポインタが MSWebDVD ビデオ矩形に重なったときに表示されるツールチップのテキストを設定する。

構文

[ sToolTip = ] MSWebDVD.ToolTip

可能な値

sToolTip ツールチップのテキストを指定する文字列値。

注意

このプロパティは、デフォルト値を持たない読み書き可能なプロパティである。文字列が空の場合、ツールチップは表示されない。

ToolTipMaxWidth プロパティ

MSWebDVD オブジェクト

MSWebDVD オブジェクトに関連付けられたツールチップの最大幅を設定または取得する。

構文

[ iMaxWidth = ] MSWebDVD.ToolTipMaxWidth

可能な値

iMaxWidth アプリケーションのツールチップの最大幅を表す整数値。

注意

このプロパティは、デフォルト値が 200 ピクセルの読み書き可能なプロパティである。

TotalTitleTime プロパティ

MSWebDVD オブジェクト

現在のタイトルの総再生時間を取得する。

構文

[ sTotalTime = ] MSWebDVD.TotalTitleTime

可能な値

sTotalTime 現在のタイトルの総再生時間を表す文字列値。フォーマットは "hh:mm:ss:ff"。

注意

このプロパティは、デフォルト値を持たない読み取り専用プロパティである。"hh:mm:ss:ff" (時、分、秒、フレーム) というフォーマットの 11 文字の文字列が返される。

参照

PlayAtTime、PlayAtTimeInTitle

UOPValid メソッド

MSWebDVD オブジェクト

指定されたユーザー操作 (UOP) が現在有効かどうかを示す値を取得する。

構文

[ bIsValid = ] MSWebDVD.UOPValid(iUOP);

パラメータ

iUOP UOP を指定する整数値。可能な値については、「注意」を参照すること。

戻り値

指定された操作が UOP コントロールに許されるかどうかを示すブール値を返す。

注意

iUOP として可能な値は次のように定義されている。

値 | ユーザー関数
0x0 | PlayTitle、PlayAtTime、PlayAtTimeInTitle
0x1 | PlayChapter
0x2 | PlayTitle
0x4 | Stop
0x8 | ReturnFromSubmenu
0x10 | PlayChapter
0x20 | PlayPrevChapter、ReplayChapter
0x40 | PlayNextChapter
0x80 | PlayForwards
0x100 | PlayBackwards
0x200 | ShowMenu の引数に 2 (DVD_MENU_Title) を指定
0x400 | ShowMenu の引数に 3 (DVD_MENU_Root) を指定
0x800 | ShowMenu の引数に 4 (DVD_MENU_Subpicture) を指定
0x1000 | ShowMenu の引数に 5 (DVD_MENU_Audio) を指定
0x2000 | ShowMenu の引数に 6 (DVD_MENU_Angle) を指定
0x4000 | ShowMenu の引数に 7 (DVD_MENU_Chapter) を指定
0x8000 | Resume
0x10000 | SelectLeftButton、SelectRightButton、SelectUpperButton、SelectLowerButton
0x20000 | StillOff
0x40000 | Pause
0x80000 | CurrentAudioStream
0x100000 | CurrentSubpictureStream
0x200000 | CurrentAngle、SelectParentalLevel
0x400000 | KaraokeAudioPresentationMode

Volume プロパティ

MSWebDVD オブジェクト

オーディオ ストリーム出力のスピーカ ボリュームを設定または取得する。

構文

[ iVolume = ] MSWebDVD.Volume

可能な値

iVolume ボリュームを減衰 (デシベル) で表現した整数値。

注意

このプロパティは、デフォルト値が 0 の読み書き可能なプロパティである。 最大ボリュームは 0、無音は 10,000。スケールは対数である。目的のデシベル値を 100 倍する (たとえば、10,000 = 100 dB)。

VolumesAvailable プロパティ

MSWebDVD オブジェクト

複数ボリュームのセットに含まれるボリューム数を取得する。

構文

[ iVolumes = ] MSWebDVD.VolumesAvailable

可能な値

iVolumes セットに含まれるボリュームの数を表す整数値。

注意

このプロパティは、デフォルト値を持たない読み取り専用プロパティである。DVD タイトルは、複数のディスク セットやシリーズでリリースされることがある。現在のディスクのボリューム番号を判断するには、このメソッドを使用する。

WindowlessActivation プロパティ

MSWebDVD オブジェクト

ウィンドウ モードとウィンドウレス モードのいずれかに使用する MSWebDVD オブジェクトを設計時に初期化する。

構文

[ bWindowless = ] MSWebDVD.WindowlessActivation

可能な値

bWindowless オブジェクトがウィンドウ モードかどうかを示すブール値。

注意

このプロパティは、デフォルト値が TRUE の読み書き可能なプロパティである。 したがって、このプロパティを設定しなければならないのは、MSWebDVD オブジェクトをウィンドウ付きコンテナ内で実行している場合だけである。Microsoft® Internet Explorer の Web ページ内では、MSWebDVD が常にウィンドウレス モードになるため、このプロパティを設定する必要はない。

Zoom メソッド

MSWebDVD オブジェクト

所定のスクリーン座標を中心に、ビデオ表示をズームイン/ズームアウトする。

構文

MSWebDVD.Zoom(iXPos, iYPos, iZoomRatio);

パラメータ

iXPos | ズームする矩形の中央の x 座標を指定する整数値。
iYPos | ズームする矩形の中央の y 座標を指定する整数値。
iZoomRatio | 現在のズーム値に適用する倍率を指定する数値。ズーム後の最大サイズは、ハードウェア オーバーレイのサポートによって異なるが、通常は元のサイズの 32 ～ 64 倍である。

戻り値

戻り値なし。

注意

新しいズーム率は、元のサイズに戻すか、または再度変更するまで有効である。つまり、iZoomRatio に 2 を指定してこのメソッドを 2 回呼び出すと、ズーム率がビデオ本来のサイズの 4 倍になる。ユーザーがハードウェアの能力を超えてズームしようとした場合、このメソッドは成功するが、何も実行されない。

ズームインには SetClipVideoRect メソッドを使用してもよい。2 つの方法の唯一の違いは、ズーム矩形の指定方法にある。


MSDVDAdm オブジェクト

MSDVDAdm "管理" オブジェクトのメソッドおよびプロパティを使用すると、スクリプト アプリケーションから、Microsoft® Windows® レジストリ内にあるアプリケーション自体のデフォルト設定を修正できる。レジストリは、すべての Windows システムにあるデータベースであり、アプリケーションからアプリケーション自体に関する情報を格納して、初期化または実行時に使用することができる。

これらのメソッドおよびプロパティの多くは、MSWebDVD オブジェクト自体の現在値を設定または取得するものではない。つまり、たとえば GetParentalLevel を呼び出したときに返される値は、オブジェクトに格納された現在のペアレンタル ロック レベルではない。返される値は、レジストリに格納されたデフォルトのペアレンタル ロック レベルである。現在のペアレンタル ロック レベルを取得するには、MSWebDVD メソッドの GetPlayerParentalLevel を呼び出す。SaveParentalLevel を呼び出すと、ただ、新しいデフォルトのペアレンタル ロック レベルがレジストリに書き込まれる。その変更を直ちに MSWebDVD オブジェクトに反映するには、MSWebDVD メソッドの SelectParentalLevel を呼び出す必要がある。デフォルトのロケール識別子 (LCID) 関連メソッドも同様の動作をする。

一方、BookmarkOnStop メソッドおよび BookmarkOnClose メソッドでの設定は直ちに反映される。これは、MSWebDVD オブジェクトが、初期化時ではなく、ユーザーが再生を停止するかアプリケーションを終了する直前に、これらの設定を確認するためである。

MSDVDAdm オブジェクトには、MSWebDVD の DVDAdm プロパティを通じてアクセスする。このため、たとえば MSWebDVD オブジェクトの名前が "DVD" であれば、次のように ChangePassword を呼び出す。

DVD.DVDAdm.ChangePassword(sUserName, sOld, sNew);

メソッドおよびプロパティ

次の一覧は、MSDVDAdm オブジェクトで公開されるメソッドおよびプロパティである。
メソッド
ChangePassword | アプリケーションの新しいパスワードをレジストリに保存する。
SaveParentalLevel | 新しいデフォルトのペアレンタル ロック レベルをレジストリに保存する。
SaveParentalCountry | アプリケーションの新しいペアレンタル カントリをレジストリに保存する。
ConfirmPassword | 指定されたパスワードが直前に保存したパスワードと一致するかどうか検査する。
GetParentalLevel | レジストリに最後に保存したペアレンタル ロック レベルを取得する。
GetParentalCountry | レジストリに最後に保存したペアレンタル カントリを取得する。
RestoreScreenSaver | システムのスクリーン セーバー設定を復元する。
プロパティ
DisableScreenSaver | システムのスクリーン セーバーのオン/オフを切り替える。
DefaultAudioLCID | オーディオ ストリームに対応するユーザーが指定したデフォルト LCID のレジストリ設定を設定または取得する。
DefaultSubpictureLCID | サブピクチャ ストリームに対応するユーザーが指定したデフォルト LCID のレジストリ設定を設定または取得する。
DefaultMenuLCID | メニューに対応するユーザーが指定したデフォルト LCID のレジストリ設定を設定または取得する。
BookmarkOnStop | MSDVDAdm オブジェクトに、ユーザーが [停止] ボタンをクリックしたときに現在位置と設定のブックマークを自動的に保存するかどうかを知らせる値を、設定または取得する。
BookmarkOnClose | MSDVDAdm オブジェクトに、ユーザーがアプリケーションを終了したときに現在位置と設定のブックマークを自動的に保存するかどうかを知らせる値を、設定または取得する。

BookmarkOnClose プロパティ

MSDVDAdm オブジェクト

MSDVDAdm オブジェクトに、ユーザーがアプリケーションを終了したときに現在位置と設定のブックマークを自動的に保存するかどうかを知らせる値を、設定または取得する。

構文

[ bBookmarkOnClose = ] DVD.DVDAdm.BookmarkOnClose

構成要素

DVD | MSWebDVD オブジェクトを表すオブジェクト式。
DVDAdm | MSWebDVD オブジェクトの DVDAdm プロパティ。
bBookmarkOnClose | ユーザーが DVD プレーヤー アプリケーションを終了したときに、ディスク上の位置、ペアレンタル ロック レベル、およびペアレンタル カントリを含むすべての DVD 設定のブックマークを、MSDVDAdm コントロールで保存するかどうかを示すブール型の値。

注意

このプロパティは、デフォルト値が TRUE の読み書き可能なプロパティである。

参照

BookmarkOnStop、ブックマークの保存と復元

BookmarkOnStop プロパティ

MSDVDAdm オブジェクト

MSWebDVD オブジェクトに、ユーザーが [停止] ボタンをクリックしたときに現在位置と設定のブックマークを自動的に保存するかどうかを知らせる値を、設定または取得する。

構文

[ bBookmarkOnStop = ] DVD.DVDAdm.BookmarkOnStop

構成要素

DVD | MSWebDVD オブジェクトを表すオブジェクト式。
DVDAdm | MSWebDVD オブジェクトの DVDAdm プロパティ。
bBookmarkOnStop | ディスク上の位置、ペアレンタル ロック レベル、およびペアレンタル カントリを含むすべての DVD 設定のブックマークを、MSDVDAdm オブジェクトで保存するかどうかを示すブール型の値。

注意

このプロパティは、デフォルト値が FALSE の読み書き可能なプロパティである。

ブックマークはそのコンピュータでのみ有効である。別のコンピュータで読み取るため、ユーザーがブックマークを保存し、ほかのユーザーに送ることはできない。

参照

BookmarkOnClose

ChangePassword メソッド

MSDVDAdm オブジェクト

アプリケーションの新しいパスワードをレジストリに保存する。

構文

DVD.DVDAdm.ChangePassword(sUserName, sOld, sNew );

構成要素

DVD | MSWebDVD オブジェクトを表すオブジェクト式。
DVDAdm | MSWebDVD オブジェクトの DVDAdm プロパティ。
sUserName | 現在のユーザーのログオン名を指定する文字列型の値。MSDVDAdm オブジェクトはこのパラメータを無視する。「注意」を参照すること。
sOld | ユーザーの古いパスワードを指定する文字列型の値。
sNew | ユーザーの新しいパスワードを指定する文字列型の値。NULL であってはならない。

戻り値

戻り値なし。

注意

現在、sUserName パラメータは、このメソッドを含むすべての関連メソッドで無視される。これは、パスワードを知っているユーザーであれば、誰でもペアレンタル ロック レベルを設定できることを意味する。アプリケーションには、パスワードとペアレンタル ロック レベルがそれぞれ 1 つしかない。個々のユーザーのログオン名または複数パスワードの管理はサポートされていない。ペアレンタル ロックを使用するには、大人がパスワードを設定したうえで、子供に適したペアレンタル ロック レベルを設定する必要がある。成人向けコンテンツが格納されたディスクを大人が再生するには、ペアレンタル ロック レベルを変更し、見終わってから元に戻せばよい。パスワードを知らない限り、子供は設定したペアレンタル ロック レベル以下のコンテンツしか見ることができない。

参照

ConfirmPassword

ConfirmPassword メソッド

MSDVDAdm オブジェクト

指定されたパスワードが直前に保存したパスワードと一致するかどうか検査する。

構文

[ bIsConfirmed = ] DVD.DVDAdm.ConfirmPassword(sUserName, sPassword);

構成要素

DVD | MSWebDVD オブジェクトを表すオブジェクト式。
DVDAdm | MSWebDVD オブジェクトの DVDAdm プロパティ。
sUserName | ユーザー名を指定する文字列型の値。「注意」を参照すること。
sPassword | 新しいパスワードを指定する文字列型の値。

戻り値

指定されたパスワードが既存のパスワードと一致する場合は、TRUE を返す。それ以外の場合は、FALSE を返す。

注意

現在、sUserName パラメータは、このメソッドを含むすべての関連メソッドで無視される。

参照

ChangePassword

DefaultAudioLCID プロパティ

MSDVDAdm オブジェクト

オーディオ ストリームに対応するユーザーが指定したデフォルト LCID のレジストリ設定を設定または取得する。

構文

[ iAudioLCID = ] DVD.DVDAdm.DefaultAudioLCID

構成要素

DVD | MSWebDVD オブジェクトを表すオブジェクト式。
DVDAdm | MSWebDVD オブジェクトの DVDAdm プロパティ。
iAudioLCID | DVD アプリケーションに対応するレジストリ設定に格納された、ユーザーが指定したデフォルトのオーディオ LCID を表す整数型の値。この値は、DVD に明記されたデフォルトのオーディオ ストリームと等しいとは限らない。有効な LCID の範囲については、Platform SDK の Microsoft® Win32® ドキュメントを参照すること。

このプロパティは、デフォルト値を持たない読み書き可能なプロパティである。デフォルトのオーディオ LCID を指定しなかった場合、MSDVDAdm オブジェクトは、デフォルト ストリームとしてディスクにマークされたオーディオ ストリームを再生する。

DefaultMenuLCID プロパティ

MSDVDAdm オブジェクト

メニューに対応するユーザーが指定したデフォルト LCID のレジストリ設定を設定または取得する。

構文

[ iMenuLCID = ] DVD.DVDAdm.DefaultMenuLCID

構成要素

DVD | MSWebDVD オブジェクトを表すオブジェクト式。
DVDAdm | MSWebDVD オブジェクトの DVDAdm プロパティ。
iMenuLCID | DVD アプリケーションに対応するレジストリ設定に格納された LCID を表す整数型の値。この値は、DVD に明記されたデフォルトのメニュー言語と等しいとは限らない。有効な LCID の範囲については、Platform SDK の Win32 ドキュメントを参照すること。

このプロパティは、デフォルト値を持たない読み書き可能なプロパティである。デフォルトのメニュー LCID を指定しなかった場合、MSDVDAdm オブジェクトは、デフォルトのメニュー言語としてディスクにマークされた言語を使用する。

DefaultSubpictureLCID プロパティ

MSDVDAdm オブジェクト

サブピクチャ ストリームに対応するユーザーが指定したデフォルト LCID のレジストリ設定を設定または取得する。

構文

[ iSubpictureLCID = ] DVD.DVDAdm.DefaultSubpictureLCID

構成要素

DVD | MSWebDVD オブジェクトを表すオブジェクト式。
DVDAdm | MSWebDVD オブジェクトの DVDAdm プロパティ。
iSubpictureLCID | DVD アプリケーションに対応するレジストリ設定に格納された、ユーザーが指定したデフォルトのサブピクチャ LCID を表す整数型の値。この値は、DVD に明記されたデフォルトのサブピクチャ ストリームと等しいとは限らない。有効な LCID の範囲については、Platform SDK の Win32 ドキュメントを参照すること。

このプロパティは、デフォルト値を持たない読み書き可能なプロパティである。デフォルトのサブピクチャ LCID を指定しなかった場合、MSDVDAdm オブジェクトは、デフォルト ストリームとしてディスクにマークされたサブピクチャ ストリームを再生する。

DisableScreenSaver プロパティ

MSDVDAdm オブジェクト

システムのスクリーン セーバーのオン/オフを切り替える。

構文

[ bDisabled = ] DVD.DVDAdm.DisableScreenSaver

構成要素

DVD | MSWebDVD オブジェクトを表すオブジェクト式。
DVDAdm | MSWebDVD オブジェクトの DVDAdm プロパティ。
bDisabled | システムの DVD プレーヤー アプリケーションに対応するスクリーン セーバー設定がオフになっているかどうかを示すブール型の値。TRUE はオフになっていることを意味する。

このプロパティは、デフォルト値が TRUE の読み書き可能なプロパティである。

注意

DVD ビデオのディスクを見るときには、マウスやキーボードを長時間使用しないことが多い。このため、MSWebDVD ActiveX® コントロールは、デフォルトでシステムのスクリーン セーバーを無効にする。

参照

RestoreScreenSaver

GetParentalCountry メソッド

MSDVDAdm オブジェクト

レジストリに最後に保存したペアレンタル カントリを取得する。

構文

[ iParentalCountry = ] DVD.DVDAdm.GetParentalCountry();

構成要素

DVD | MSWebDVD オブジェクトを表すオブジェクト式。
DVDAdm | MSWebDVD オブジェクトの DVDAdm プロパティ。

戻り値

レジストリに格納されたデフォルトの国別コードを示す整数を返す。

注意

このメソッドで取得するペアレンタル カントリは、MSWebDVD オブジェクトに現在格納されている国と同じとは限らない。

GetParentalLevel メソッド

MSDVDAdm オブジェクト

レジストリに最後に保存したペアレンタル ロック レベルを取得する。

構文

[ iParentalLevel = ] DVD.DVDAdm.GetParentalLevel();

構成要素

DVD | MSWebDVD オブジェクトを表すオブジェクト式。
DVDAdm | MSWebDVD オブジェクトの DVDAdm プロパティ。

戻り値

デフォルトのペアレンタル ロック レベルを示す 1 ～ 8 の整数を返す。

注意

このメソッドで取得するペアレンタル ロック レベルは、MSWebDVD コントロールに現在格納されているペアレンタル ロック レベルと等しいとは限らない。コントロールに現在格納されているペアレンタル ロック レベルを取得するには、MSWebDVD.GetPlayerParentalLevel を呼び出す。-1 の値はペアレンタル ロックが無効であることを示す。

RestoreScreenSaver メソッド

MSDVDAdm オブジェクト

システムのスクリーン セーバー設定を復元する。

構文

DVD.DVDAdm.RestoreScreenSaver();

構成要素

DVD | MSWebDVD オブジェクトを表すオブジェクト式。
DVDAdm | MSWebDVD オブジェクトの DVDAdm プロパティ。

戻り値

戻り値なし。

注意

通常、DVD アプリケーションでは、起動時に DisableScreenSaver プロパティを TRUE に設定してシステムのスクリーン セーバーを無効にし、終了時に RestoreScreenSaver を呼び出してスクリーン セーバーをもう一度有効にする。アプリケーションでシステムのスクリーン セーバー設定を使用しないなら、このメソッドを呼び出したり、DisableScreenSaver プロパティをセットしたりする必要はない。

SaveParentalCountry メソッド

MSDVDAdm オブジェクト

アプリケーションの新しいペアレンタル カントリをレジストリに保存する。

構文

DVD.DVDAdm.SaveParentalCountry( iCountry,  sUserName, sPassword);

構成要素

DVD | MSWebDVD オブジェクトを表すオブジェクト式。
DVDAdm | MSWebDVD オブジェクトの DVDAdm プロパティ。
iCountry | ペアレンタル カントリを指定する整数型の値。
sUserName | ユーザー名を指定する文字列型の値。現在は無視される。
sPassword | パスワードを指定する文字列型の値。

戻り値

戻り値なし。

注意

このメソッドを使用すると、現在のパスワードを知っているユーザーが、レジストリに新しいペアレンタル カントリの設定を保存できる。MSDVDAdm の全メソッドと同じように、このメソッドは、プレーヤー内の現在のペアレンタル ロック レベルは変更せずに、レジストリのみを変更する。このため、新しい国で開くのは、次に作成した MSWebDVD オブジェクトである。プレーヤー内のペアレンタル カントリを変更するには、MSWebDVD.SelectParentalCountry を呼び出す。この場合、レジストリ設定は変更されない。

参照

SaveParentalLevel

SaveParentalLevel メソッド

MSDVDAdm オブジェクト

新しいデフォルトのペアレンタル ロック レベルをレジストリに保存する。

構文

DVD.DVDAdm.SaveParentalLevel( iLevel, sUserName, sPassword);

構成要素

DVD | MSWebDVD オブジェクトを表すオブジェクト式。
DVDAdm | MSWebDVD オブジェクトの DVDAdm プロパティ。
iLevel | ペアレンタル ロック レベルを指定する整数型の値 (1 ～ 8)。
sUserName | ユーザー名を指定する文字列型の値。現在は無視される。
sPassword | パスワードを指定する文字列型の値。

戻り値

戻り値なし。

注意

このメソッドを使用すると、現在のパスワードを知っているユーザーが、レジストリに新しいペアレンタル ロック レベル設定を保存できる。MSDVDAdm の全メソッドと同じように、このメソッドは、プレーヤー内の現在のペアレンタル ロック レベルは変更せずに、レジストリのみを変更する。このため、新しいペアレンタル ロック レベルで開くのは、次に起動した MSWebDVD オブジェクトである。プレーヤー内のペアレンタル ロック レベルを変更するには、MSWebDVD.SelectParentallevel を呼び出す。この場合、レジストリ設定は変更されない。 -1 の値はペアレンタル ロックが無効であることを示す。


DVDRect オブジェクト

DVDRect オブジェクトのプロパティを使用すると、スクリプト アプリケーションから、GetButtonRect、GetClipVideoRect、GetVideoSize、SetClipVideoRect などの MSWebDVD メソッドの矩形座標を指定および取得できる。

プロパティ

プロパティ
x | 矩形の左上角の x 座標を設定または取得する。
y | 矩形の左上角の y 座標を設定または取得する。
Width | 矩形の幅 (ピクセル単位) を設定または取得する。
Height | 矩形の高さ (ピクセル単位) を設定または取得する。

Height プロパティ

矩形の高さを設定または取得する。

構文

[ iHeight = ] DVDRect.Height

構成要素

DVDRect | MSWebDVD オブジェクトを表すオブジェクト式。
iHeight | 矩形の高さ (ピクセル単位)。

注意

このプロパティは、デフォルト値を持たない読み書き可能なプロパティである。

Width プロパティ

矩形の幅を設定または取得する。

構文

[ iWidth = ] DVDRect.Width

構成要素

DVDRect | MSWebDVD オブジェクトを表すオブジェクト式。
iWidth | 矩形の幅 (ピクセル単位)。

注意

このプロパティは、デフォルト値を持たない読み書き可能なプロパティである。

x プロパティ

矩形の左上角の x 座標を設定または取得する。

構文

[ iXPos = ] DVDRect.x

構成要素

DVDRect | MSWebDVD オブジェクトを表すオブジェクト式。
iXPos | 矩形の左上角の x 座標。

注意

このプロパティは、デフォルト値を持たない読み書き可能なプロパティである。

y プロパティ

矩形の左上角の y 座標を設定または取得する。

構文

[ iYPos = ] DVDRect.y

構成要素

DVDRect | MSWebDVD オブジェクトを表すオブジェクト式。
iYPos | 矩形の左上角の y 座標。

注意

このプロパティは、デフォルト値を持たない読み書き可能なプロパティである。


MSWebDVD イベント

MSWebDVD Microsoft® ActiveX® コントロールは、各種の内部イベントが発生したときや、ディスク上に特定の情報が見つかったときに、アプリケーションに通知する。

イベントの大半は、ユーザー操作 (UOP) コントロールに関連する。DVD の作成者は、任意の DVD コマンド (PlayForwards、Pause、ShowMenu など) をいつでも無効にできるようにディスクをエンコードできる。たとえば、多くのディスクでは、FBI による通告の再生中には早回しやメニュー表示ができないが、通告が済むとできるようになっている。アプリケーションでは、UOP イベントを処理し、ユーザー インターフェイスを更新することによって、現在そのディスクに実行できるコマンドをユーザーに知らせることができる。通常、これにはボタンの有効/無効を切り替える。たとえば、bEnabled が FALSE にセットされた PlayForwards イベントを受け取ったら [再生] ボタンを無効にし、bEnabled が TRUE にセットされた PlayForwards イベントを受け取ったら [再生] ボタンをもう一度有効にする。

UOP コントロールに関連しないイベントは 3 つある。DVDNotify イベントは、DVD に関連する各種の通知をアプリケーションに通知する。イベントは EventCode パラメータで識別する。イベントによっては、Param1 パラメータおよび Param2 パラメータに追加情報が渡される。ReadyStateChange イベントは、ActiveX コントロールすべてに共通のプロパティである MSWebDVD ReadyState プロパティの変化を、アプリケーションに通知する。UpdateOverlay イベントは、ウィンドウレス モードで MSWebDVD のホストとなっているアプリケーションにのみ送られる。アプリケーションでは、フルスクリーン モードでビデオ矩形上にフローティング ボタンを表示している場合にのみ、このイベントに応答すればよい。

参照

イベントの処理方法を示すサンプル コードについては、「DVD イベント通知の処理」を参照すること。

MSWebDVD オブジェクト

イベント

イベント | 説明
ChangeCurrentAngle | ディスクでアングルの変更が有効または無効になると送信される。
ChangeCurrentAudioStream | ディスクでオーディオ ストリームの変更が有効または無効になると送信される。
ChangeCurrentSubpictureStream | ChangeCurrentSubpictureStream コマンドが有効または無効になると送信される。
DVDNotify | 各種の DVD イベントおよびディスク関連命令をアプリケーションに通知する。
PauseOn | Pause コマンドが有効または無効になると送信される。
PlayAtTime | PlayAtTime コマンドが有効または無効になると送信される。
PlayAtTimeInTitle | PlayAtTimeInTitle コマンドが有効または無効になると送信される。
PlayBackwards | PlayBackwards コマンドが有効または無効になると送信される。
PlayChapter | PlayChapter コマンドが有効または無効になると送信される。
PlayChapterInTitle | PlayChapterInTitle コマンドが有効または無効になると送信される。
PlayForwards | PlayForwards コマンドが有効または無効になると送信される。
PlayNextChapter | PlayNextChapter コマンドが有効または無効になると送信される。
PlayPrevChapter | PlayPrevChapter コマンドが有効または無効になると送信される。
PlayTitle | ReturnFromSubmenu コマンドが有効または無効になると送信される。
ReadyStateChange | MSWebDVD コントロールの ReadyState プロパティが変化すると送信される。
ReplayChapter | ReplayChapter コマンドが有効または無効になると送信される。
Resume | Resume コマンドが有効または無効になると送信される。
ReturnFromSubmenu | ReturnFromSubmenu コマンドが有効または無効になると送信される。
SelectOrActivatButton | ディスクでメニュー ボタンのアクティブが有効または無効になると送信される。
ShowMenu | ディスクでメニューの表示が有効または無効になると送信される。
StillOff | StillOff コマンドが有効または無効になると送信される。
Stop | Stop コマンドが有効または無効になると送信される。
UpdateOverlay | オーバーレイ サーフェスが移動またはサイズ変更されるか、またはそのカラー キーが変化すると送信される。

ChangeCurrentAngle

MSWebDVD イベント

ディスクでアングルの変更が有効または無効になると送信される。

構文

ChangeCurrentAngle(bEnabled)

パラメータ

bEnabled 処理が有効か無効かどうかを示すブール型の値。

ChangeCurrentAudioStream

MSWebDVD イベント

ディスクでオーディオ ストリームの変更が有効または無効になると送信される。

構文

ChangeCurrentAudioStream(bEnabled)

パラメータ

bEnabled 処理が有効か無効かどうかを示すブール型の値。

ChangeCurrentSubpictureStream

MSWebDVD イベント

ディスクでサブピクチャ ストリームの変更が有効または無効になると送信される。

構文

ChangeCurrentSubpictureStream(bEnabled)

パラメータ

bEnabled 処理が有効か無効かどうかを示すブール型の値。

DVDNotify

MSWebDVD イベント

各種の DVD イベントおよびディスク関連命令をアプリケーションに通知する。

構文

DVDNotify(EventCode, Param1, Param2)

パラメータ

EventCode | DVD イベントを指定する。
Param1 | イベントに関連する追加情報が入ることがある。
param2 | イベントに関連する追加情報が入ることがある。

参照

DVD イベント通知コードとそのパラメータの完全な一覧については、「DVD イベント通知コード」を参照すること。

PauseOn

MSWebDVD イベント

PauseOn コマンドが有効または無効になると送信される。

構文

PauseOn(bEnabled)

パラメータ

bEnabled 処理が有効か無効かどうかを示すブール型の値。

PlayAtTime

MSWebDVD イベント

PlayAtTime コマンドが有効または無効になると送信される。

構文

PlayAtTime(bEnabled)

パラメータ

bEnabled 処理が有効か無効かどうかを示すブール型の値。

PlayAtTimeInTitle

MSWebDVD イベント

PlayAtTimeInTitle コマンドが有効または無効になると送信される。

構文

PlayAtTimeInTitle(bEnabled)

パラメータ

bEnabled 処理が有効か無効かどうかを示すブール型の値。

PlayBackwards

MSWebDVD イベント

PlayBackwards コマンドが有効または無効になると送信される。

構文

PlayBackwards(bEnabled)

パラメータ

bEnabled 処理が有効か無効かどうかを示すブール型の値。

PlayChapter

MSWebDVD イベント

PlayChapter コマンドが有効または無効になると送信される。

構文

PlayChapter(bEnabled)

パラメータ

bEnabled 処理が有効か無効かどうかを示すブール型の値。

PlayChapterInTitle

MSWebDVD イベント

PlayChapterInTitle コマンドが有効または無効になると送信される。

構文

PlayChapterInTitle(bEnabled)

パラメータ

bEnabled 処理が有効か無効かどうかを示すブール型の値。

PlayForwards

MSWebDVD イベント

PlayForwards コマンドが有効または無効になると送信される。

構文

PlayForwards(bEnabled)

パラメータ

bEnabled 処理が有効か無効かどうかを示すブール型の値。

PlayNextChapter

MSWebDVD イベント

PlayNextChapter コマンドが有効または無効になると送信される。

構文

PlayNextChapter(bEnabled)

パラメータ

bEnabled 処理が有効か無効かどうかを示すブール型の値。

PlayPrevChapter

MSWebDVD イベント

PlayPrevChapter コマンドが有効または無効になると送信される。

構文

PlayPrevChapter(bEnabled)

パラメータ

bEnabled 処理が有効か無効かどうかを示すブール型の値。

PlayTitle

MSWebDVD イベント

PlayTitle コマンドが有効または無効になると送信される。

構文

PlayTitle(bEnabled)

パラメータ

bEnabled 処理が有効か無効かどうかを示すブール型の値。

ReadyStateChange

MSWebDVD イベント

MSWebDVD コントロールの ReadyState プロパティが変化すると送信される。

構文

ReadyStateChange(ReadyState)

パラメータ

ReadyState ReadyState プロパティの新しい値を示す。可能な値は、READYSTATE_UNINITIALIZED = 0、READYSTATE_LOADING = 1、READYSTATE_LOADED = 2、READYSTATE_INTERACTIVE = 3、READYSTATE_COMPLETE = 4 のいずれか。

ReplayChapter

MSWebDVD イベント

ReplayChapter コマンドが有効または無効になると送信される。

構文

ReplayChapter(bEnabled)

パラメータ

bEnabled 処理が有効か無効かどうかを示すブール型の値。

Resume

MSWebDVD イベント

Resume コマンドが有効または無効になると送信される。

構文

Resume(bEnabled)

パラメータ

bEnabled 処理が有効か無効かどうかを示すブール型の値。

ReturnFromSubmenu

MSWebDVD イベント

ReturnFromSubmenu コマンドが有効または無効になると送信される。

構文

ReturnFromSubmenu(bEnabled)

パラメータ

bEnabled 処理が有効か無効かどうかを示すブール型の値。

SelectOrActivatButton

MSWebDVD イベント

ディスクでメニュー ボタンのアクティブが有効または無効になると送信される。

構文

SelectOrActivatButton(bEnabled)

パラメータ

bEnabled 処理が有効か無効かどうかを示すブール型の値。

ShowMenu

MSWebDVD イベント

ディスクでメニューの表示が有効または無効になると送信される。

構文

ShowMenu(DVDMenuIDConstants, bEnabled)

パラメータ

DVDMenuIDConstants 有効または無効になったメニューを示す数値。可能な値は次のいずれかである。
2 | タイトル
3 | ルート
4 | サブピクチャ
5 | オーディオ
6 | アングル
7 | チャプター
bEnabled 処理が有効か無効かどうかを示すブール型の値。

StillOff

MSWebDVD イベント

StillOff コマンドが有効または無効になると送信される。

構文

StillOff(bEnabled)

パラメータ

bEnabled 処理が有効か無効かどうかを示すブール型の値。

Stop

MSWebDVD イベント

Stop コマンドが有効または無効になると送信される。

構文

Stop(bEnabled)

パラメータ

bEnabled 処理が有効か無効かどうかを示すブール型の値。

UpdateOverlay

MSWebDVD イベント

オーバーレイ サーフェスが移動またはサイズ変更されるか、またはそのカラー キーが変化すると送信される。

構文

UpdateOverlay()

注意

アプリケーションでは、サイズ変更または移動されるオーバーレイ サーフェスを気にしてはならない。それはすべて内部的に処理される。このイベントはカラー キーが変化したときにも送られる。つまり、ウィンドウのないコントロールとして MSWebDVD のホストとなっているアプリケーションでは、フルスクリーン モードでビデオ サーフェス上にフローティング ボタンを表示している場合、ボタンを正しく表示するには、ColorKey プロパティの新しい値を取得してこのイベントに応答しなければならない。


プロパティ セット

Microsoft® DirectShow® は、プロパティ セットを使用して、ハードウェアとその関連ドライバおよびフィルタが提供する拡張サービスをサポートする。ハードウェアおよびフィルタのベンダーは、新しい能力をプロパティとして定義し、それらをプロパティ セットにまとめ、プロパティ セットの仕様を公開することができる。アプリケーション ベンダーは、IKsPropertySet インターフェイスのメソッドを使用して、ドライバやフィルタが特定のプロパティ セットをサポートしているかどうか判断し、それらのプロパティを取得または設定することができる。

IKsPropertySet が公開するすべてのメソッドでは、プロパティ セットを識別する GUID (guidPropSet パラメータ) と、プロパティ セット内のプロパティを識別する DWORD (dwPropID パラメータ) が必要になる。dwPropID パラメータは、通常、列挙型のメンバである。

個々のプロパティには、IKsPropertySet::Set メソッドおよび IKsPropertySet::Get メソッドの pPropData パラメータで指定したデータを関連付けることができる。これらのパラメータは、IKsPropertySet で内部的に定義されず (データ型 LPVOID)、プロパティ セット開発者が個々のプロパティに適した方法で使用できるようになっている。各プロパティの定義は、プロパティ データの目的を提供する。

DirectShow は、DVD とキャプチャのためのプロパティ セットを提供する。以下の項では、これらのプロパティの詳細について説明する。

  • DVD コピー保護プロパティ セット
  • DVD カラオケ プロパティ セット
  • DVD サブピクチャ プロパティ セット
  • コマ送りプロパティ セット
  • ピン プロパティ セット


DVD コピー保護プロパティ セット

DVD コピー保護プロパティ セットは、ハードウェア デクリプタまたはソフトウェア デクリプタから得られるコピー保護情報の認証を提供する。このプロパティ セットは、DVD ビデオからの違法コピーを防止するために使用する。

Microsoft は、暗号化方式に必要な認証処理を助けることにより、DVD-ROM ドライブが DVD デクリプタを使用してキーの認証および転送ができるようにするソフトウェアを提供する。現在のところ DVD デクリプタを製品化する予定はないが、代わりに、ハードウェア デクリプタとソフトウェア デクリプタのどちらかの認証を有効にするエージェントとして機能するシステム コードを提供している。

DVD ナビゲータはキー交換処理を開始および制御する。DVD ミニドライバは以下のプロパティを実装するだけでよい。残りはその他のコンポーネントが処理する。

コピー保護プロパティは、個々の DVD 入力ストリームに送られる。このことは、DVD ストリームをすべて同じハードウェアで制御する場合でも変わらない。

次の情報は、IKsPropertySet メソッドの呼び出しでこのプロパティ セットに使用するために必要な定数およびデータ型の情報を示している。GUID (guidPropSet)、プロパティ ID (dwPropID)、およびプロパティのデータ型 (pPropData) パラメータの値を提供する。

プロパティ セット GUID: AM_KSPROPSETID_CopyProt
プロパティ ID | 指定されたプロパティによって使用されるデータ型
AM_PROPERTY_COPY_MACROVISION | AM_COPY_MACROVISION
AM_PROPERTY_DVDCOPY_CHLG_KEY | AM_DVDCOPY_CHLGKEY
AM_PROPERTY_DVDCOPY_DEC_KEY2 | AM_DVDCOPY_BUSKEY
AM_PROPERTY_DVDCOPY_DISC_KEY | AM_DVDCOPY_DISCKEY
AM_PROPERTY_DVDCOPY_DVD_KEY1 | AM_DVDCOPY_BUSKEY
AM_PROPERTY_DVDCOPY_REGION | DVD_REGION 構造体。
AM_PROPERTY_DVDCOPY_SET_COPY_STATE | AM_DVDCOPY_SET_COPY_STATE
AM_PROPERTY_DVDCOPY_TITLE_KEY | AM_DVDCOPY_TITLEKEY

次の一覧は、DVD コピー保護プロパティの ID とその説明である。

AM_PROPERTY_COPY_MACROVISION
これは設定専用プロパティである。このプロパティは、受信ピンの出力側にある NTSC エンコーダのマクロビジョン レベルを設定する。
AM_PROPERTY_DVDCOPY_CHLG_KEY
このプロパティでは設定と取得の両方の操作がサポートされている。取得操作では、デコーダにそのバス チャレンジ キーの提供を要求する。設定操作では、DVD ドライブからのバス チャレンジ キーをデコーダに提供する。このプロパティに渡されるデータは、AM_DVDCOPY_CHLGKEY 型の構造体である。
AM_PROPERTY_DVDCOPY_DEC_KEY2
これは取得専用プロパティである。このプロパティは、デコーダのバス キー 2 を DVD ドライブに転送するように要求する。渡されるデータは AM_DVDCOPY_BUSKEY 型の構造体である。
AM_PROPERTY_DVDCOPY_DISC_KEY
これは取得専用プロパティである。このプロパティはディスク キーを提供する。ディスク キーは AM_DVDCOPY_DISCKEY 型の構造体である。
AM_PROPERTY_DVDCOPY_DVD_KEY1
これは設定専用プロパティである。このプロパティは DVD ドライブのバス キー 1 をデコーダに提供する。渡されるデータは AM_DVDCOPY_BUSKEY 型の構造体である。
AM_PROPERTY_DVDCOPY_SET_COPY_STATE
このプロパティでは設定と取得の両方の操作がサポートされている。まず、認証が必要かどうかを判断するために Get が呼び出される。設定プロパティは、コピー保護のネゴシエーションのどのフェーズにフィルタが入ろうとしているかを示す。渡されるデータは AM_DVDCOPY_SET_COPY_STATE 型の構造体である。
AM_PROPERTY_DVDCOPY_REGION
地域コードは、DVD コンソーシアムで決定されたそのデコーダを再生に使用できる地域の定義を要求する。この地域は次の構造体で定義される。
typedef struct _DVD_REGION {
   UCHAR CopySystem;   //ディスクがコピー保護されているかどうかを指定する。
   UCHAR RegionData;    //デコーダからの地域情報。
   UCHAR SystemRegion;  //DVD ドライブからの地域情報。
   UCHAR Reserved; //予約済み。
} DVD_REGION, *PDVD_REGION;
AM_PROPERTY_DVDCOPY_TITLE_KEY
これは設定専用プロパティである。このプロパティは、現在のコンテンツからのタイトル キーを提供する。このキーは AM_DVDCOPY_TITLEKEY 型の構造体である。

IKsPropertySet インターフェイスを使用して、これらのプロパティをサポートするために設定、取得、およびクエリを行う。

このプロパティ セットでは、次のデータ型が使用される。
データ型 | 説明
AM_COPY_MACROVISION | NTSC エンコーダのマクロビジョン レベル。
AM_COPY_MACROVISION_LEVEL | マクロビジョン レベル。AM_COPY_MACROVISION 構造体はこのデータ型を使用する。
AM_DVDCOPY_BUSKEY | DVD バス キー。
AM_DVDCOPY_CHLGKEY | DVD チャレンジ キー。
AM_DVDCOPY_DISCKEY | DVD ディスク キー。
AM_DVDCOPY_SET_COPY_STATE | フィルタのコピー保護状態を判断する。
AM_DVDCOPYSTATE | コピー保護状態。AM_DVDCOPY_SET_COPY_STATE 構造体はこのデータ型を使用する。
AM_DVDCOPY_TITLEKEY | 現在のコンテンツからの DVD タイトル キー。

AM_COPY_MACROVISION

DVD コピー保護プロパティ セット

NTSC エンコーダのマクロビジョン レベル。

構文

typedef struct _AM_COPY_MACROVISION {
    ULONG MACROVISIONLevel;
} AM_COPY_MACROVISION, *PAM_COPY_MACROVISION;

メンバ

MACROVISIONLevel
NTSC エンコーダのマクロビジョン レベル。AM_COPY_MACROVISION_LEVEL 列挙型のメンバ。

注意

AM_PROPERTY_COPY_MACROVISION プロパティはこの構造体を使用する。

AM_COPY_MACROVISION_LEVEL

DVD コピー保護プロパティ セット

マクロビジョン レベル。

構文

typedef enum {
    AM_MACROVISION_DISABLED,
    AM_MACROVISION_LEVEL1,
    AM_MACROVISION_LEVEL2,
    AM_MACROVISION_LEVEL3
} AM_COPY_MACROVISION_LEVEL, *PAM_COPY_MACROVISION_LEVEL;

要素

AM_MACROVISION_DISABLED
無効。
AM_MACROVISION_LEVEL1
レベル 1。
AM_MACROVISION_LEVEL2
レベル 2。
AM_MACROVISION_LEVEL3
レベル 3。

注意

AM_COPY_MACROVISION 構造体はこのデータ型を使用する。

AM_DVDCOPY_BUSKEY

DVD コピー保護プロパティ セット

DVD バス キー。

構文

 typedef struct _AM_DVDCOPY_BUSKEY {
    BYTE BusKey[5];
    BYTE Reserved[1];
} AM_DVDCOPY_BUSKEY, *PAM_DVDCOPY_BUSKEY;

メンバ

BusKey
DVD ドライブのバス キー。
Reserved
予約済み。

注意

AM_PROPERTY_DVDCOPY_DVD_KEY1 プロパティと AM_PROPERTY_DVDCOPY_DEC_KEY2 プロパティはこの構造体を使用する。

バス キーは、暗号解除のための DVD CSS キー交換に使用する。実装者は、CSS ライセンスを取得して、CSS からのより詳しい説明を参照する必要がある。連絡先の情報については、「DVD ビデオの仕様」を参照すること。

AM_DVDCOPY_CHLGKEY

DVD コピー保護プロパティ セット

DVD チャレンジ キー。

構文

 typedef struct _AM_DVDCOPY_CHLGKEY {
    BYTE ChlgKey[10];
    BYTE Reserved[2];
} AM_DVDCOPY_CHLGKEY, *PAM_DVDCOPY_CHLGKEY;

メンバ

ChlgKey
チャレンジ キー。
Reserved
予約済み。

注意

AM_PROPERTY_DVDCOPY_CHLG_KEY プロパティはこの構造体を使用する。

チャレンジ キーは、暗号解除のための DVD CSS キー交換に使用する。実装者は、CSS ライセンスを取得して、CSS からのより詳しい説明を参照する必要がある。連絡先の情報については、「DVD ビデオの仕様」を参照すること。

AM_DVDCOPY_DISCKEY

DVD コピー保護プロパティ セット

DVD ディスク キー。

構文

 typedef struct _AM_DVDCOPY_DISCKEY {
    BYTE DiscKey[2048];
} AM_DVDCOPY_DISCKEY, *PAM_DVDCOPY_DISCKEY;

メンバ

DiscKey
DVD ディスク キー。

注意

AM_PROPERTY_DVDCOPY_DISC_KEY プロパティはこの構造体を使用する。

ディスク キーは、暗号解除のための DVD CSS キー交換に使用する。実装者は、CSS ライセンスを取得して、CSS からのより詳しい説明を参照する必要がある。連絡先の情報については、「DVD ビデオの仕様」を参照すること。

AM_DVDCOPY_SET_COPY_STATE

DVD コピー保護プロパティ セット

フィルタのコピー保護状態を判断する。

構文

typedef struct AM_DVDCOPY_SET_COPY_STATE {
    ULONG DVDCopyState;
} AM_DVDCOPY_SET_COPY_STATE, *PAM_DVDCOPY_SET_COPY_STATE;

メンバ

DVDCopyState
フィルタのコピー保護状態。AM_DVDCOPYSTATE 列挙型のメンバ。

注意

このプロパティでは、IKsPropertySet::Get メソッドと IKsPropertySet::Set メソッドの両方がサポートされる。認証が必要かどうかを判断するため、まず IKsPropertySet::Get メソッドが呼び出される。ハードウェア DVD デコーダのように、同じ認証者を使用する複数のピンを提供するフィルタがある場合、キー交換アルゴリズムを 1 度だけ適用すればよいことを示すため、デコーダが一部のピンについて AM_DVDCOPYSTATE_AUTHENTICATION_NOT_REQUIRED で応答する可能性がある。このプロパティが発行される最初のピンの正しいコピー保護状態を取得するためには、このフィルタが AM_DVDCOPYSTATE_AUTHENTICATION_REQUIRED で応答する必要がある。

IKsPropertySet::Set メソッドは、コピー保護のネゴシエーションのどのフェーズにフィルタが入ろうとしているかを示すために使用する。フェーズは、AM_DVDCOPYSTATE 列挙型の必要なフラグをセットして指定する。

AM_PROPERTY_DVDCOPY_SET_COPY_STATE プロパティはこの構造体を使用する。

AM_DVDCOPYSTATE

DVD コピー保護プロパティ セット

コピー保護状態。

構文

typedef enum {
    AM_DVDCOPYSTATE_INITIALIZE,
        AM_DVDCOPYSTATE_INITIALIZE_TITLE,
    AM_DVDCOPYSTATE_AUTHENTICATION_NOT_REQUIRED,
    AM_DVDCOPYSTATE_AUTHENTICATION_REQUIRED,
    AM_DVDCOPYSTATE_DONE
} AM_DVDCOPYSTATE;

要素

AM_DVDCOPYSTATE_INITIALIZE
完全なキー交換アルゴリズムを開始する。
AM_DVDCOPYSTATE_INITIALIZE_TITLE
タイトル キー交換アルゴリズムを開始する。
AM_DVDCOPYSTATE_AUTHENTICATION_NOT_REQUIRED
認証は必要ない。
AM_DVDCOPYSTATE_AUTHENTICATION_REQUIRED
認証が必要。
AM_DVDCOPYSTATE_DONE
キー交換のネゴシエーションが完了した。

注意

AM_DVDCOPY_SET_COPY_STATE 構造体はこのデータ型を使用する。

AM_DVDCOPY_TITLEKEY

DVD コピー保護プロパティ セット

現在のコンテンツからの DVD タイトル キー。

構文

 typedef struct AM_DVDCOPY_TITLEKEY {
    ULONG KeyFlags;
    UCHAR TitleKey[6];
    UCHAR Reserved[2];
} AM_DVDCOPY_TITLEKEY, *PAM_DVDCOPY_TITLEKEY;

メンバ

KeyFlags
キー フラグ。
TitleKey
タイトル キー。
Reserved
予約済み。

注意

AM_PROPERTY_DVDCOPY_TITLE_KEY プロパティはこの構造体を使用する。

タイトル キーは、暗号解除のための DVD CSS キー交換に使用する。実装者は、CSS ライセンスを取得して、CSS からのより詳しい説明を参照する必要がある。連絡先の情報については、「DVD ビデオの仕様」を参照すること。


DVD カラオケ プロパティ セット

DVD ナビゲータ フィルタは、カラオケ モードに切り替わるとき、AM_PROPERTY_DVDKARAOKE_ENABLE プロパティを通じてオーディオ デコーダに知らせる。デコーダは、外部チャンネルのミキシング方法を示す AM_DvdKaraokeData 構造体へのポインタが指定された AM_PROPERTY_DVDKARAOKE_DATA プロパティを DVD ナビゲータから受け取るまで、オーディオ チャンネル 2 ～ 5 をミュートする必要がある。

AM_PROPERTY_DVDKARAOKE

DVD カラオケ プロパティ セット

構文

typedef enum {
    AM_PROPERTY_DVDKARAOKE_ENABLE = 0,  // ブール
    AM_PROPERTY_DVDKARAOKE_DATA = 1,
} AM_PROPERTY_DVDKARAOKE;

要素

AM_PROPERTY_DVDKARAOKE_ENABLE
DVD ナビゲータは、このプロパティを true に設定してデコーダに送ることによってカラオケのミックスダウンを有効にし、false に設定して送ることによって無効にする。
AM_PROPERTY_DVDKARAOKE_DATA
DVD ナビゲータは、AM_DvdKaraokeData 構造体へのポインタを指定された AM_PROPERTY_DVDKARAOKE_DATA プロパティをデコーダに送って、ミックスダウン構成を変更する (つまり、あるカラオケ チャンネルのオン/オフを切り替え、左右の出力チャンネルに割り当てる)。

AM_DvdKaraokeData

DVD カラオケ プロパティ セット

構文

typedef struct tagAM_DvdKaraokeData
{
    DWORD   dwDownmix;
    DWORD   dwSpeakerAssignment;
} AM_DvdKaraokeData;

メンバ

dwDownmix
DVD_KARAOKE_DOWNMIX フラグのビット和。チャンネル 0 か 1 にミックスダウンするチャンネルを選択する。
dwSpeakerAssignment
出力先スピーカを示す有効な DVD_KARAOKE_ASSIGNMENT 値。

参照

SelectKaraokeAudioPresentationMode


DVD サブピクチャ プロパティ セット

DVD サブピクチャ プロパティは、サブピクチャ表示の色、コントラスト、および出力を制御する。

次の情報は、IKsPropertySet メソッドの呼び出しでこのプロパティ セットに使用するために必要な定数およびデータ型の情報を示している。GUID (guidPropSet)、プロパティ ID (dwPropID)、およびプロパティのデータ型 (pPropData) パラメータの値を提供する。

プロパティ セット GUID: AM_KSPROPSETID_DvdSubPic

プロパティ ID | 指定されたプロパティによって使用されるデータ型
AM_PROPERTY_DVDSUBPIC_COMPOSIT_ON | AM_PROPERTY_COMPOSIT_ON
AM_PROPERTY_DVDSUBPIC_HLI | AM_PROPERTY_SPHLI
AM_PROPERTY_DVDSUBPIC_PALETTE | AM_PROPERTY_SPPAL

次の一覧は、サブピクチャ プロパティの ID とその説明である。

AM_PROPERTY_DVDSUBPIC_COMPOSIT_ON
サブピクチャの表示を有効または無効にする設定専用プロパティ。Microsoft® DirectShow® は、このプロパティに対応する AM_PROPERTY_COMPOSIT_ON ブール型と、このデータ型へのポインタである PAM_PROPERTY_COMPOSIT_ON を定義する。TRUE はサブピクチャを表示することを示し、FALSE は表示しないことを示す。詳細については、Windows 98 DDK の WDM 部分を参照すること。
AM_PROPERTY_DVDSUBPIC_HLI
色またはコントラストを変更するサブピクチャまたは画面の矩形を指定する設定専用プロパティ。データ型は AM_PROPERTY_SPHLI。

AM_PROPERTY_DVDSUBPIC_HLI プロパティは設定専用である。このプロパティは、色またはコントラストを変更するサブピクチャまたは画面の矩形を指定する。ここでは、「DVD ビデオの仕様」と異なり、Microsoft DVD ナビゲータがボタンおよびキーボードの情報をすべて解析し、強調表示する矩形を 1 つずつサブピクチャ デコーダに渡す。この結果、強調表示情報がデコーダに送られる回数は、DVD ストリーム内に存在するこの情報の数より多くなる。

強調表示情報はデータ ストリームと非同期に届く。デコーダは、強調表示の開始と終了のタイム スタンプを使用して、強調表示情報とそれに関連するサブピクチャ情報を対応付ける (存在する場合)。要求されたタイム スタンプに対応するサブピクチャ ストリーム情報が届かなかった場合、デコーダは、その強調表示情報をサブピクチャに関連しない独立した情報と見なす。この場合、色およびコントラストの情報は、すべて同じ色として処理される。

このデータは完全な DVD ディスク フォーマットではない。Microsoft では、AM_PROPERTY_SPHLI 型の追加の構造体を提供する。この構造体は、このプロパティのパラメータとして渡され、DVD の強調表示情報から得られる現在選択されているボタンを記述する。

DVD ナビゲータは、キーストローク情報をすべて処理し、ボタン状態が変化するたびに新しい強調表示情報を送る。この情報は、1 度に 1 つのボタンの 1 モードのみを記述する。ここには、ピクセル座標で表された画面の表示矩形、またはサブピクチャの表示 (ある場合) が含まれる。構造体には、色とコントラストの情報も格納されているが、この情報は現在選択されているボタンの現在の状態のみに対応する。フォーマットは DVD の仕様に定義されている。

強調表示情報には開始と終了のタイム スタンプが格納されている。これらの単位はほかのタイム スタンプと同じである。ただし例外が 2 つだけある。0xFFFFFFFF という開始タイム スタンプは、強調表示プロパティが受け取りと同時に有効になることを意味し、0xFFFFFFFF という終了タイム スタンプは、強調表示プロパティを次に受け取るまで有効なことを意味する。

HLISS フィールドは、DVD の仕様に定義されているとおりである。値 0 は、強調表示がすべて無効であり、デコーダでオフにしなければならないことを示す。

AM_PROPERTY_DVDSUBPIC_PALETTE
サブピクチャのパレットを設定する。データ型は AM_PROPERTY_SPPAL。

IKsPropertySet インターフェイスを使用して、これらのプロパティをサポートするために設定、取得、およびクエリを行う。

このプロパティ セットでは、次のデータ型が使用される。

データ型 | 説明
AM_COLCON | カラー コントラストを指定する。AM_PROPERTY_SPHLI 構造体のサブ構造体。
AM_DVD_YUV | DVD YUV サブピクチャ データを指定する。AM_PROPERTY_SPPAL 構造体のサブ構造体。
AM_PROPERTY_COMPOSIT_ON | AM_PROPERTY_DVDSUBPIC_COMPOSIT_ON プロパティで使用されるブール値。
AM_PROPERTY_SPHLI | DVD の強調表示情報から得られる現在選択されているボタンを記述する。
AM_PROPERTY_SPPAL | DVD サブピクチャのパレットを指定する。

AM_COLCON

DVD サブピクチャ プロパティ セット

DVD 強調表示 (HLI) 構造体から得られるカラー コントラストの記述を示す。

構文

 typedef struct _AM_COLCON {
    UCHAR emph1col:4;
    UCHAR emph2col:4;
    UCHAR backcol:4;
    UCHAR patcol:4;
    UCHAR emph1con:4;
    UCHAR emph2con:4;
    UCHAR backcon:4;
    UCHAR patcon:4;
} AM_COLCON, *PAM_COLCON;

メンバ

emph1col
強調色 1。
emph2col
強調色 2。
backcol
背景色。
patcol
パターン色。
emph1con
強調コントラスト 1。
emph2con
強調コントラスト 2。
backcon
背景コントラスト。
patcon
パターン コントラスト。

注意

この構造体は AM_PROPERTY_SPHLI 構造体に含まれる。

AM_DVD_YUV

DVD サブピクチャ プロパティ セット

DVD YUV サブピクチャ データ。

構文

 typedef struct _AM_DVD_YUV {
    UCHAR   Reserved;
    UCHAR   Y;
    UCHAR   U;
    UCHAR   V;
} AM_DVD_YUV, *PAM_DVD_YUV;

メンバ

Reserved
予約済み。
Y
Y の色データ。
U
U の色データ。
V
V の色データ。

注意

この構造体は AM_PROPERTY_SPPAL 構造体に含まれる。

AM_PROPERTY_SPHLI

DVD サブピクチャ プロパティ セット

DVD の強調表示情報から得られる現在選択されているボタンを記述する。

構文

 typedef struct _AM_PROPERTY_SPHLI {
    USHORT  HLISS;
    USHORT  Reserved;
    ULONG   StartPTM;
    ULONG   EndPTM;
    USHORT  StartX;
    USHORT  StartY;
    USHORT  StopX;
    USHORT  StopY;
    AM_COLCON  ColCon;
} AM_PROPERTY_SPHLI, *PAM_PROPERTY_SPHLI;

メンバ

HLISS
現在選択されているボタンの強調表示状態。
Reserved
内部で使用するために予約済み。使用または設定しないこと。
StartPTM
開始プレゼンテーション時間を 90,000 で割った値。
EndPTM
終了プレゼンテーション時間を 90,000 で割った値。
StartX
現在強調表示されているボタンの開始 x ピクセル座標。
StartY
現在強調表示されているボタンの開始 y ピクセル座標。
StopX
現在強調表示されているボタンの終了 x ピクセル座標。
StopY
現在強調表示されているボタンの終了 y ピクセル座標。
ColCon
カラー コントラストの記述。データ型は AM_COLCON。

注意

AM_PROPERTY_DVDSUBPIC_HLI プロパティはこの構造体を使用する。

AM_PROPERTY_SPPAL

DVD サブピクチャ プロパティ セット

DVD サブピクチャのパレットを指定する。

構文

 typedef struct _AM_PROPERTY_SPPAL {
    AM_DVD_YUV sppal[16];
} AM_PROPERTY_SPPAL, *PAM_PROPERTY_SPPAL;

メンバ

sppal
YUV 要素 16 個から成る配列。サブピクチャ コマンド ストリーム内で要求された 4 ビットの色番号に対応する。YUV 要素のデータ型は AM_DVD_YUV。

注意

AM_PROPERTY_DVDSUBPIC_PALETTE プロパティはこの構造体を使用する。


コマ送りプロパティ セット

Microsoft® DirectShow® 下でフレーム単位のシークを実装するデコーダは、AM_KSPROPSETID_FrameStep プロパティ セットを実装する必要がある。このプロパティ セットは、IVideoFrameStep インターフェイスと共に使用し、2 つのプロパティから構成される。AM_PROPERTY_FRAMESTEP は、コマ送りコマンドとコマ送り能力情報を渡すために使用する。AM_FRAMESTEP_STEP は、コマ送りするフレーム数を指定するために使用する。

構文

typedef enum {
        AM_PROPERTY_FRAMESTEP_STEP   = 0x01,
        AM_PROPERTY_FRAMESTEP_CANCEL = 0x02,
        AM_PROPERTY_FRAMESTEP_CANSTEP = 0x03,
        AM_PROPERTY_FRAMESTEP_CANSTEPMULTIPLE = 0x04
} AM_PROPERTY_FRAMESTEP;

メンバ

AM_PROPERTY_FRAMESTEP_STEP
デコーダにコマ送り操作の開始を指示する。
AM_PROPERTY_FRAMESTEP_CANCEL
デコーダに現在のコマ送り操作の取り消しを指示する。
AM_PROPERTY_FRAMESTEP_CANSTEP
デコーダにコマ送りが実行可能かどうかを照会する。実行可能な場合は S_OK を返し、それ以外の場合は S_FALSE を返す。
AM_PROPERTY_FRAMESTEP_CANSTEPMULTIPLE
同時に複数のフレームをコマ送りできるどうかをデコーダに照会する。実行可能な場合は S_OK を返し、それ以外の場合は S_FALSE を返す。
typedef struct _AM_FRAMESTEP_STEP
{
    DWORD dwFramesToStep;
} AM_FRAMESTEP_STEP;

AM_FRAMESTEP_STEP メンバ

dwFramesToStep
コマ送りするフレーム数をデコーダに知らせる DWORD 値。1 以上でなければならない。1 より大きい場合には、(n - 1) フレームをスキップし、n 番目のフレームを表示することを意味する。


ピン プロパティ セット

ピン プロパティ セットを使用すると、ピンが属するカテゴリを取得できる (ある場合)。そのカテゴリはフィルタがピンを作成するときにそのフィルタによってセットされる、カテゴリはどのタイプのデータがピンを流れているのかを示す。最もよく使われるカテゴリはキャプチャ フィルタのキャプチャピンとプレビューピンに対するものである。[SDK Root]/samples/multimedia/DirectShow/Capture/AMCap ディレクトリの AMCaps サンプルは、Windows Driver Model (WDM) の ビデオ キャプチャ デバイスをベースにしたフィルタ倉をを構築するときにこのプロパティ セットをどう設定するかを示す。

次の情報は、IKsPropertySet メソッドの呼び出しでこのプロパティ セットに使用するために必要な定数およびデータ型の情報を示している。GUID (guidPropSet)、プロパティ ID (dwPropID)、およびプロパティのデータ型 (pPropData) パラメータの値を提供する。

プロパティ セット GUID: AMPROPSETID_Pin

このプロパティ セットは、AMPROPERTY_PIN_CATEGORY ピン カテゴリ プロパティのみで構成される。このプロパティは GUID データ型を使用する。Microsoft® DirectShow® では、SDK のインクルード ディレクトリの Uuids.h に、次のピン カテゴリが定義されている。

カテゴリ | 説明
PIN_CATEGORY_ANALOGVIDEOIN | アナログ信号を入力してデジタル化するキャプチャ フィルタの入力ピン。
PIN_CATEGORY_CAPTURE | キャプチャ ピン。
PIN_CATEGORY_CC | Line 21 からのクローズド キャプション データを提供するピン。
PIN_CATEGORY_EDS | 拡張データ サービス (Line 21、偶数フィールド) を提供するピン。
PIN_CATEGORY_NABTS | 北米ビデオ テキスト規格データを提供するピン。
PIN_CATEGORY_PREVIEW | プレビュー ピン。
PIN_CATEGORY_STILL | 静止画を提供するピン。
PIN_CATEGORY_TELETEXT | 文字放送 (クローズド キャプションの変種) を提供するピン。
PIN_CATEGORY_TIMECODE | タイムコード データを提供するピン。
PIN_CATEGORY_VBI | 垂直同期間隔 データを提供するピン。
PIN_CATEGORY_VIDEOPORT | Video output pin to be connected to input pin zero on the オーバーレイ ミキサー の入力ピン ゼロに接続するビデオ出力ピン。
PIN_CATEGORY_VIDEOPORT_VBI | VBISurf に接続されるピン、ビデオポートが使われる場合のクローズド キャプション オーバーレイのようなものに正しいビデオ メモリを割り当てる必要がある VBI サーフェイス アロケータ フィルタ。PCI、IEEE 1394、USB シナリオはこのフィルタを使わない。詳細については、「Microsoft TV テクノロジ」を参照すること。

IKsPropertySet インターフェイスを使用して、これらのプロパティをサポートするために設定、取得、およびクエリを行う。


DirectShow のコンポーネント

このトピックでは、Microsoft® DirectShow® に含まれる、フィルタ以外の COM コンポーネントを紹介する。DirectShow に含まれるフィルタの一覧については、「フィルタ」を参照すること。

コンポーネント | 説明
キャプチャ グラフ ビルダ | ビデオ キャプチャ グラフを作成する。
DVD グラフ ビルダ | DVD 再生グラフを作成する。
フィルタ グラフ マネージャ | フィルタ グラフを作成および制御する。
フィルタ マッパー | 登録されているフィルタをレジストリ内で検索する。
メディア プロパティ バッグ | AVI ファイルの INFO および DISP チャンクを設定または取得する。
メモリ アロケータ | メディア サンプルのバッファを割り当てる。
SeekingPassThru | 1 つの入力ピンを持つフィルタのシークを実装するヘルパー オブジェクト。
システム基準クロック | 基準クロックを実装する。
システム デバイス 列挙子 | システムにインストールされているフィルタおよびハードウェア デバイスを列挙する。

キャプチャ グラフ ビルダ

ビデオ キャプチャ グラフを作成する。ビデオ キャプチャまたは編集アプリケーションは、このコンポーネントを使用してフィルタ グラフを作成することができる。

クラス識別子 | CLSID_CaptureGraphBuilder2
インターフェイス | ICaptureGraphBuilder2
参照 | ビデオ キャプチャ、DirectShow 編集サービス

DVD グラフ ビルダ

DVD 再生グラフを作成する。アプリケーションは、このコンポーネントを使用して DVD 再生および操作のフィルタ グラフを作成することができる。

クラス識別子 | CLSID_DvdGraphBuilder
インターフェイス | IDvdGraphBuilder
参照 | DVD アプリケーション

フィルタ グラフ マネージャ

フィルタ グラフを作成および制御する。フィルタ グラフ マネージャは、DirectShow の中心的コンポーネントである。アプリケーションは、このコンポーネントを使用してフィルタ グラフを作成および制御する。また、フィルタ グラフ マネージャは、同期化、イベント通知、およびその他のフィルタ グラフの側面も処理する。

クラス識別子 | CLSID_FilterGraph
インターフェイス | IAMGraphStreams、IBasicAudio、IBasicVideo、IBasicVideo2、IFilterChain、IFilterGraph、IFilterGraph2、IFilterMapper2、IGraphBuilder、IGraphConfig、IGraphVersion、IMediaControl、IMediaEvent、IMediaEventEx、IMediaEventSink、IMediaFilter、IMediaPosition、IMediaSeeking、IQueueCommand、IResourceManager、IVideoFrameStep、IVideoWindow

フィルタ マッパー

登録されているフィルタをレジストリ内で検索する。フィルタ グラフ マネージャは、このコンポーネントを使用してフィルタ グラフを作成する。アプリケーションは、このコンポーネントを使用して特定の検索条件に一致するフィルタを検索することができる。

クラス識別子 | CLSID_FilterMapper2
インターフェイス | IFilterMapper2
参照 | デバイスとフィルタの列挙

メディア プロパティ バッグ

AVI ファイルの INFO および DISP チャンクを設定または取得する。

クラス識別子 | CLSID_MediaPropertyBag
インターフェイス | IMediaPropertyBag
参照 | IPersistMediaPropertyBag

メモリ アロケータ

メディア サンプルのバッファを割り当てる。フィルタは、このコンポーネントを使用して共有メモリ バッファを割り当てる。

クラス識別子 | CLSID_MemoryAllocator
インターフェイス | IMemAllocator

SeekingPassThru

1 つの入力ピンを持つフィルタのシークを実装するヘルパー オブジェクト。単独入力フィルタは、このオブジェクトを使用して IMediaSeeking インターフェイスおよび IMediaPosition インターフェイスを実装する。

クラス識別子 | CLSID_SeekingPassThru
インターフェイス | ISeekingPassThru
参照 | CPosPassThru、CRendererPosPassThru

システム基準クロック

基準クロックを実装する。グラフ内のいずれのフィルタもクロックを提供しない場合は、フィルタ グラフ マネージャはこのコンポーネントを使用してグラフを同期化する。

クラス識別子 | CLSID_SystemClock
インターフェイス | IAMClockAdjust、IReferenceClock
参照 | DirectShow のタイムとクロック

システム デバイス列挙子

システムにインストールされているフィルタおよびハードウェア デバイスを列挙する。アプリケーションは、このコンポーネントを使用して任意のカテゴリのフィルタおよびデバイスを検索することができる。

クラス識別子 | CLSID_SystemDeviceEnum
インターフェイス | ICreateDevEnum
参照 | フィルタ カテゴリ、デバイスとフィルタの列挙


DirectShow 基底クラス

Microsoft® DirectShow® 基底クラスは DirectShow フィルタを実装するために設計された C++ クラスとユーティリティ関数のセットである。アプリケーション開発者には、いくつかのヘルパー関数も有用である。

  • DirectShow 基底クラスの使い方
  • 基底クラス リファレンス
  • ユーティリティ関数
  • デバッグ ユーティリティ


DirectShow 基底クラスの使い方

Microsoft® DirectShow® の基底クラスを使うには、以下のディレクトリにある基底クラス ライブラリをビルド、リンクしなければならない :

(SDK root)\Samples\Multimedia\DirectShow\BaseClasses

注 SDK の以前のバージョンではバイナリファイルとしてライブラリが含まれていた。Microsoft® DirectX® 8.0 では、基底クラスを使おうとするなら、このライブラリを自身でビルドしなければならない。

基底クラスのプロジェクト ワークスペースは BaseClasses.dsw と名づけられている。このプロジェクトは 2 つのバージョンのライブラリをビルドする、リテール バージョン Strmbase.lib と デバッグ バージョン Strmbasd.lib である。自分のプロジェクト内で、ヘッダー ファイル Streams.h をインクルードすること。リテール ビルドかデバッグ ビルド化によって、プロジェクトに Strmbase.lib か Strmbsd.lib をリンクすること。デバッグ ビルドでは、ヘッダー ファイルをインクルードする前にプリプロセッサ シンボル DEBUG を定義すること。

次の表は必要なファイルを要約する。

ワークスペース | BaseClasses.dsw
リテール ライブラリ | Strmbase.lib
デバッグ ライブラリ | Strmbasd.lib
ヘッダー ファイル | Streams.h

ビルド環境のセットアップの詳細については、「ビルド環境の設定」を参照すること。

プリプロセッサ シンボル

ヘッダー ファイル Streams.h をインクルードするとき、次のプリプロセッサ シンボルが特殊な意味を持つ :

  • DEBUG: デバッグ ビルド。このプリプロセッサ シンボルを使うと、多くのデバッグ ユーティリティが使用可能になる。詳細については、「デバッグ ユーティリティ」を参照すること。
  • PERF: 予約されている。このプリプロセッサ シンボルを使ってはいけない。
  • VFWROBUST: ポインタ有効性評価を可能にする。詳細については、「ポインタ有効マクロ」を参照すること。DEBUG が定義されているなら、VFWROBUST を定義する必要はない。


基底クラス リファレンス

ここには Microsoft® DirectShow® のすべての C++ クラス、データ メンバ、および関数のリファレンスが含まれる。

  • フィルタ基底クラスについて
クラス | 説明
CAggDirectDraw | IDirectDraw インターフェイスを集成する。
CAggDrawSurface | IDirectDrawSurface インターフェイスを集成する。
CAMEvent | 手動リセットおよび自動リセット イベントのラッパー クラス。
CAMMsgEvent | メッセージ処理を行うイベント オブジェクトのラッパー クラス。
CAMSchedule | 基準クロックのスケジューラ。
CAMThread | ワーカー スレッドを管理するための基底クラス。
CAutoLock | ブロックの範囲のクリティカル セクションを保持する。
CAutoUsingOutputPin | CDynamicOutputPin オブジェクトへのアクセスを取得、解放する。
CBaseAllocator | アロケータの基底クラス。
CBaseBasicVideo | IBasicVideo インターフェイスの IDispatch コンポーネントを処理する。
CBaseControlVideo | 汎用ビデオ ウィンドウ用の IBasicVideo インターフェイスを実装する。
CBaseControlWindow | IVideoWindow インターフェイスを実装する。
CBaseDispatch | IDispatch インターフェイスを実装する基底クラス。
CBaseFilter | フィルタの基底クラス。
CBaseInputPin | 入力ピンの基底クラス。
CBaseList | 属性リストの基底クラス。
CBaseMediaFilter | IMediaFilter インターフェイスを実装する。
CBaseObject | DirectShow オブジェクトを実装する基底クラス。
CBaseOutputPin | 出力ピンの基底クラス。
CBasePin | ピンの基底クラス。
CBasePropertyPage | プロパティ ページ実装の基底クラス。
CBaseReferenceClock | 基準クロックを実装する。
CBaseRenderer | レンダリング フィルタを実装する基底クラス。
CBaseStreamControl | IAMStreamControl インターフェイスを実装する。
CBaseVideoRenderer | ビデオ レンダラの基底クラス。
CBaseVideoWindow | IVideoWindow インターフェイスの IDispatch コンポーネントを処理する。
CBaseWindow | ウィンドウを管理する基底クラス。
CBasicAudio | IBasicAudio インターフェイスの IDispatch インターフェイス コンポーネントを処理する。
CCmdQueue | IQueueCommand インターフェイスを実装するヘルパー クラス。
CCritSec | スレッドのロックを提供する。
CCrossbar | クロスバー フィルタを操作するヘルパー クラス。
CDeferredCommand | IDeferredCommand インターフェイスの実装。
CDispParams | DISPPARAMS 構造体のラッパー クラス。
CDrawImage | ウィンドウ描画のヘルパー クラス。
CDynamicOutputPin | 動的な再接続とフォーマット変更をサポートする出力ピン。
CEnumMediaTypes | 優先されるメディア タイプの列挙子。
CEnumPins | ピンの列挙子。
CFactoryTemplate | クラス ファクトリの情報を提供するクラス。
CGenericList | タイプ固有のリストを実装するクラス テンプレート。
CImageAllocator | DIB セクションのアロケータ。
CImageDisplay | イメージ表示フォーマットを管理するヘルパー クラス。
CImagePalette | パレットを管理するヘルパー クラス。
CImageSample | DIB セクションを使うメディア サンプル。
CLoadDirectDraw | Microsoft® DirectDraw® ライブラリのロード、アンロードのヘルパー クラス。
CMediaControl | IMediaControl インターフェイスの IDispatch メソッドを処理する。
CMediaEvent | IMediaEvent インターフェイスの IDispatch メソッドを処理する。
CMediaPosition | IMediaPosition インターフェイスの IDispatch メソッドを処理する。
CMediaSample | メディア サンプル。
CMediaType | メディア タイプを管理するクラス。
CMemAllocator | メモリ アロケータ。
CMsg | CMsgThread オブジェクトに作成された管理リクエストのヘルパー クラス。
CMsgThread | 同期の完了でキューイングしているスレッドにリクエストをキューに入れるワーカー スレッド。
COARefTime | 秒と 100 ナノ秒の間で基準タイムの単位を変換する。
COutputQueue | メディア サンプルを提供するため、キューに入れるオブジェクト。
CPersistStream | IPersistStream インターフェイスを実装する基底クラス。
CPosPassThru | 1 つの入力ピンを持つフィルタのシーク コマンドを処理する。
CPullPin | IAsyncReader インターフェイスをサポートする出力ピンからデータを引き出すヘルパー クラス。
CQueue | 単純で、静的にサイズを割り当てたキューを実装するテンプレート。
CRefTime | 基準タイムを管理するヘルパー クラス。
CRenderedInputPin | 複数入力ピンをサポートするレンダリング フィルタの入力ピン。
CRendererInputPin | CBaseRenderer クラスの入力ピン。
CRendererPosPassThru | レンダリング フィルタのシーク コマンドを処理する。
CSeekingPassThru | CPosPassThru オブジェクトと CRendererPosPassThru オブジェクトを作成する、ヘルパー オブジェクト。
CSource | ソース フィルタを実装する基底クラス。
CSourcePosition | IMediaPosition インターフェイスを実装する抽象クラス。使われていない。
CSourceSeeking | 1 つの出力ピンでソース フィルタ内のシークを実装する抽象クラス。
CSourceStream | CSource クラスの出力ピン。
CSystemClock | システム クロック。
CTransformFilter | 変換フィルタを実装する基底クラス。
CTransformInputPin | CTransformFilter クラスが使用する入力ピン。
CTransformOutputPin | CTransformFilter クラスが使用する出力ピン。
CTransInPlaceFilter | データをコピーしない変換フィルタを実装するクラス。
CTransInPlaceInputPin | CTransInPlaceFilter クラスの入力ピン。
CTransInPlaceOutputPin | CTransInPlaceFilter クラスの出力ピン。
CUnknown | IUnknown インターフェイスを実装する。
CVideoTransformFilter | ビデオ変換フィルタの基底クラス。
FOURCCMap | GUID と FOURCC 間の変換をするヘルパー クラス。


フィルタ基底クラスの概要

このトピックでは、Microsoft® DirectShow® クラス ライブラリの概要、基底クラスとそれが実装する DirectShow Component Object Model (COM) インターフェイスの関係、およびこれらのインターフェイスとは直接関係のないユーティリティ クラスについて説明する。ここでは、各クラスの低レベルな解説や、フィルタを構築したりフィルタ グラフ マネージャを実行する方法などの特定の手順についての説明は行わない。

DirectShow C++ クラス ライブラリは、自分で作成したフィルタに必要なインターフェイスを実装する場合に役に立つ。ほかのユーティリティ クラスを使用すると クリティカル セクションやスレッド管理などの Microsoft Win32® の機能を組み込むことができる一方で、ほとんどの基底クラスはインターフェイスに直接対応する。

このトピックは、以下のセクションを含んでいる。

  • 基底クラス
  • ユーティリティ クラス

基底クラス

DirectShow クラス ライブラリのほとんどの基底クラスは DirectShow COM インターフェイスを実装する。これらのクラスは IUnknown インターフェイスを提供する C++ オブジェクトを生成するので、外部コンポーネントはそのオブジェクトがサポートするインターフェイスにアクセスできる。

このセクションでは、以下の項目について説明する。

  • CBaseObject および CUnknown クラス
  • インターフェイスを実装する基底クラス

CBaseObject および CUnknown クラス

CBaseObject クラスは、すべての基底クラスのルートである。このクラスの主な目的は、すべてのアクティブな DirectShow オブジェクトの数を保持することによってデバッグを支援することである。派生クラス内のすべての基底クラス コンストラクタは、デバッギング オブジェクト名を第 1 パラメータとして提供しながら CBaseObject コンストラクタを呼び出す。この基底クラスに送られたデバッギング オブジェクト名は、デバッギング モニタ上で見ることができる。

インターフェイスを実装するすべての DirectShow クラスは、CBaseObject から派生した CUnknown と呼ばれる基底クラスから派生する。CUnknown は INonDelegatingUnknown インターフェイスを実装する。このインターフェイスは IUnknown インターフェイスと同様に、インターフェイスを要求するメソッドやそのインターフェイスへの参照を追加または解放するメソッドを提供する。

IUnknown のサービスを実装するインターフェイスがなぜ 2 つあるのだろうか? その理由は、集成 (aggregation) にある。集成とは、複数のオブジェクトを結合して 1 つの大きなオブジェクトにする COM 用語である。フィルタやピンなどのフィルタ グラフ オブジェクトを集成することはほとんどない。ただし、将来の拡張性を確保したり、フィルタ グラフ マネージャによって集成されるオブジェクトである PID を実装する目的で、その設計を取り入れることは可能である。集成したオブジェクトにおいて、外部オブジェクト (ほかのオブジェクトをその中に含んでいるオブジェクト) は、IUnknown インターフェイスを使用してオブジェクトの外部と通信する。外部オブジェクトの IUnknown インターフェイスは、その内部オブジェクトの IUnknown インターフェイスへの参照を渡す。つまり、アプリケーションが外部オブジェクトの IUnknown インターフェイスを呼び出して、そのいずれかの内部オブジェクトに属するインターフェイスを要求すると、外部オブジェクトは内部オブジェクトの IUnknown インターフェイスを呼び出して、要求されたインターフェイスを取得する。

内部オブジェクトは IUnknown インターフェイスを外部オブジェクトの IUnknown に委任しなければならないので、内部オブジェクトの IUnknown インターフェイスをプライベートに (つまり外部オブジェクトの IUnknown インターフェイスを経由せずに) アクセスしてはならない。内部オブジェクトの IUnknown は、外部オブジェクトを介した通信専用に予約されている。ただし、外部オブジェクトを経由せずにオブジェクトがほかのオブジェクトにプライベートに接続することは可能である。たとえばフィルタのピンは、ほかのオブジェクトのピンのインターフェイスをプライベートに照会しなければならないことがある。

INonDelegatingUnknown インターフェイスは、オブジェクトが集成されているかどうかに関係なく、インターフェイスへの直接的なプライベート アクセスを提供する。直接アクセスは、ピン、アロケータ、フィルタなどの DirectShow オブジェクト間でのほとんどの通信において重要であり、通信を行う場合のデフォルトの方法である。実際、基底クラスは、集成されていないオブジェクト (フィルタ グラフのほとんどすべてのオブジェクト) の IUnknown インターフェイスを実装して非委任インターフェイスを直接呼び出す。

インターフェイスを実装する基底クラス

DirectShow クラス ライブラリに含まれるクラスの大半は COM インターフェイスを実装し、次のように分類される。

  • フィルタ基底クラスは、IBaseFilter インターフェイスを実装し、CBaseFilter およびそこから派生したクラスを含む。
  • ピン クラスは、IPin インターフェイスを実装し、CBasePin および派生クラスを含む。
  • 列挙子クラスは、CEnumPins および CEnumMediaTypes を含む。
  • 転送基底クラスは、CMediaSample、CBaseAllocator、CMemAllocator、およびその派生クラスを含む。これらのクラスはピン間でメモリを共有し、そのメモリを使用してメディア サンプルを渡す。
  • コントロール クラスおよび位置クラスは、CBaseFilter、CMediaPosition、CMediaControl、CBaseMediaFilter、CSourceSeeking、および CBaseStreamControl を含む。
  • クロック基底クラスは、CBaseReferenceClock および CSystemClock を含む。

ここでは、以下の項目について説明する。

  • フィルタ基底クラス
  • ピン基底クラス
  • 列挙子基底クラス
  • 転送基底クラス
  • メディア コントロールおよび配置クラス
  • クロック基底クラス

フィルタ基底クラス

DirectShow のストリームのアーキテクチャは、フィルタとピンに基づいている。フィルタは、フィルタ グラフ マネージャおよびフィルタのピンと通信を行う。ピンはフィルタに接続し、データをストリームの下流に転送する。

CBaseFilter は、すべてのフィルタ クラスの基底クラスである。このクラスは、IBaseFilter インターフェイスを実装する。IBaseFilter インターフェイスが指定するメソッドにより、フィルタ グラフ マネージャはピンの作成や列挙、およびフィルタ情報の取得を行い、また、フィルタ グラフに追加されたことをフィルタに通知することができる。また、CBaseFilter は、フィルタがフィルタ グラフ マネージャから実行、ポーズ、および停止コマンドを受け取るための IMediaFilter インターフェイス (IBaseFilter の派生元) も実装する。この基底クラスは、メンバ関数を追加して、ピン カウントの取得、個々のピンへのポインタの取得、およびピン バージョンの取得を行う。

また、CBaseMediaFilter クラスは、IMediaFilter インターフェイスも実装する。ただし IMediaFilter は CBaseFilter によっても実装されるので、このクラスは PID を書く場合を除いてほとんど使用しない。

いくつかのクラスは CBaseFilter から直接派生する。このようなクラスのそれぞれは、特定のタイプのフィルタを実装するための基底クラスを提供する。このようなクラスには以下のクラスがある。

  • ソース フィルタの基底クラスである CSource。
  • 変換フィルタの基底クラスである CTransformFilter。
  • レンダラ フィルタの基底クラスである CBaseRenderer。

CSource フィルタ クラスは CSourceStream ピン クラスと共に、ソース フィルタの作成を支援する。ほとんどの処理はピン クラスで行われ、CSource はピン作成および削除メンバ関数を追加する。CSourcePosition クラスは、ソース フィルタを実装する。

CTransformFilter クラスは、変換フィルタを実装する。データのコピーを作成したい場合は、CTransformFilter から変換クラスを派生する。CTransformFilter から派生した CTransInPlaceFilter クラスを使用すると、データのコピーを作成せずにその場で変換が可能になる。これらの変換フィルタ クラスは、同じような名前が付けられたピン クラス (たとえば CTransformOutputPin と CTransformInputPin) といっしょに動作する。ピン クラスのほとんどのメンバ関数は、変換フィルタ クラスのメンバ関数を呼び出すために実装されるので、通常はフィルタ クラスから自分のフィルタを派生させた後、変換フィルタを実装するいくつかのメンバ関数をオーバーライドするだけで良い。

CTransformFilter は、CBaseFilter から派生したクラスにいくつかのメンバ関数を追加する。その中には、派生クラスがオーバーライドしなければならない純粋仮想メンバ関数が含まれる。1 つの例として、入力ピンがサンプルを受け取ったときに呼び出さなければならない CTransformFilter::Transform メンバ関数がある。このメンバ関数は、変換機能の核部分を提供する。オーバーライドされるほかのメンバ関数には、派生クラスに固有の実装 (たとえば ピンのメディア タイプのチェックや適切な量のメモリの割り当て) も含まれる。さらに、いくつかの CTransformFilter メンバ関数は、接続またはストリーミングプロセスにおける各種のポイントで呼び出される。派生クラスはこれらをオーバーライドして、インターフェイスへの参照の追加や解放を処理する。

CVideoTransformFilter クラスは CTransformFilter クラスから派生し、ビデオ レンダラが品質コントロール メッセージを送信したときにフレームをドロップすることによってレンダリングされたビデオの品質に作用するフィルタの基底クラスとして使用される。このクラスは、主にビデオ デコンプレッサによって使用される。

CBaseRenderer クラスとその派生クラスである CBaseVideoRenderer は、ビデオ レンダリング フィルタを実装するベース フィルタ クラスである。DirectShow で使用されるビデオ レンダリング フィルタは、CBaseVideoRenderer から派生する。これらのクラスといっしょに動作するが CBaseFilter から派生しないレンダラ クラスもある。このようなクラスには、以下のクラスがある。

  • CRendererInputPin
  • CBaseControlVideo およびその基底クラス CBaseBasicVideo
  • CBaseControlWindow およびその基底クラス CBaseVideoWindow および CBaseWindow
  • CAggDirectDraw
  • CAggDrawSurface

次の図は、CBaseFilter または CBasePin から派生しない、レンダラをサポートするすべてのクラスを示している。

CBaseFilter または CBasePin から派生しない、レンダラをサポートするクラスの階層

ピン基底クラス

ピンの操作はフィルタに比べて手間がかかる。ピンは、フィルタ グラフ マネージャがそれを別のフィルタのピンに接続できるように、メソッドを公開しなければならない。また、ピンは、どのメディア タイプを渡すかについて、そしてメディア サンプルを転送するための共有メモリ アロケータをどのピンが提供するかについて、接続されているピンどうしで調整するためにもメソッドを公開する。出力ピンは、それぞれのメディア サンプルを接続されている入力ピンに渡す役目を持ち、入力ピンは、それを受け取る役目を持つ。ピンは、インターフェイスをサポートして、品質コントロール メッセージおよび位置情報がピンの間でストリームを介して渡されるようにしなければならない。

次の図は、ピン クラスを示している。すべてのピン クラスは、CUnknown から派生した基底クラス CBasePin から派生する。

CBasePin は、IPin インターフェイスを実装する。IPin インターフェイスは、ほかのピンへの接続、接続されているピンで使用するメディア タイプの調整、ピンの内部接続のクエリ、ストリームのアクティビティのピンへの通知を行うためのメソッドを指定する。

IPin メソッドの実装に加え、CBasePin は IQualityControl メソッドを実装して、フィルタ グラフを経由してピンどうしで品質コントロール メッセージを渡せるようにする。品質コントロール メッセージを使用すると、たとえばレンダラなどのフィルタは、サンプル レートを調整するために別のフィルタを要求できる。通常、品質コントロール メッセージは、レンダラからアップストリームのソース フィルタに渡される。ただし、ビデオ キャプチャ フィルタの場合には、ソース フィルタ (たとえば VTR リーダー) は、品質コントロール メッセージをダウンストリームのレンダリング フィルタに渡してレートを調整することができる。

CBasePin クラスは、接続処理、メディア タイプの調整、および接続解除処理を提供するためのオーバーライド可能ないくつかの仮想メンバ関数を提供する。CBasePin から派生する 2 つの基底クラスは、このような操作の多くのデフォルト処理を提供する。

  • CBaseOutputPin は出力ピンを実装する。
  • CBaseInputPin は入力ピンを実装する。

CBaseOutputPin は、CTransformOutputPin および CSourceStream クラスの基底クラスである。同様に、CBaseInputPin は、CTransformInputPin クラスの基底クラスである。これらの派生ベース ピン クラスを理解するうえで、CBaseOutputPin および CBaseInputPin クラスが使用する基本モデルを理解することが大切である。

2 つのピンで使用される接続および転送モデルにおいて、入力ピンはメディア サンプルを受け取ることができるように IMemInputPin インターフェイスをサポートする。CBaseInputPin クラスは、IMemInputPin インターフェイスを実装する。また、2 つのピンの一方は、ピン間で渡されるメディア サンプル オブジェクトを生成する IMemAllocator インターフェイスを含むオブジェクトである、共有メモリ アロケータ オブジェクトを提供しなければならない。CBaseInputPin クラスによって実装される IMemInputPin メソッドは、CMemAllocator クラスによって実装されるこのアロケータ オブジェクトを提供する。接続されている出力ピンは、専用のアロケータを提供することもできる。この場合、出力ピンは、どのアロケータを使用するかを入力ピンに (別の IMemInputPin メソッドを介して) 通知しなければならない。

CBaseOutputPin クラスは追加のメンバ関数を提供して、アロケータのサンプルのサイズおよび数を設定し、アロケータからのメディア サンプルを取得し、そのメディア サンプルを接続されている入力ピンに配送し、エンドオブストリーム メッセージおよびフラッシュの終わりメッセージをダウンストリームに配送する。このクラスはまた、多くの IPin メソッドも実装する。

CPullPin は、パーサー フィルタの入力ピンで使用されるクラスである。次の図に示すように、このクラスは CAMThread クラスから派生する。

パーサー フィルタは、非同期ファイル リーダー フィルタを使用してディスクから情報を取り出したり、URL モニカ フィルタを使用してインターフェイスから情報を取り出す。CPullPin は、アップストリームのソース リーダー フィルタで実装される IAsyncReader インターフェイスといっしょに動作する。CPullPin はスレッドを開始し、アップストリーム フィルタからデータを取り出し、そのデータをダウンストリームに送る。つまり、CPullPin は、サンプルをソースから取り出した後で専用の IMemInputPin::Receive メソッドを単に呼び出すだけで良い (または、同等のルーチンをどこかで実行する)。

列挙子基底クラス

列挙子とは、要素のリストをたどる方法を提供するインターフェイスである。列挙子は COM プログラミングにおいて使用され、オブジェクトを列挙する場合に DirectShow モデルは COM モデルの方法に従う。クラス ライブラリでは、IEnumPins インターフェイスを実装する CEnumPins と、IEnumMediaTypes インターフェイスを実装する CEnumMediaTypes の 2 つの列挙子クラスが提供されている。ほかの 2 つの DirectShow 列挙子インターフェイスである IEnumFilters および IEnumRegFilters はフィルタ グラフ マネージャによってのみ実装されるので、基底クラスによって表されない。

CEnumPins クラスは、IBaseFilter::EnumPins メソッドが呼び出されると列挙子を作成する。このメソッドから返される列挙子は、CEnumPins クラスによって実装される IEnumPins インターフェイスへのポインタである。次に CEnumPins メンバ関数を呼び出して、フィルタの各ピンへのポインタを取得できる。この処理は、この列挙子がフィルタで CBaseFilter::GetPin メンバ関数を呼び出すことによって実現される。フィルタは、基底クラスの CBaseFilter::GetPin メンバ関数をオーバーライドして、それが呼び出されるごとにリスト内で次のピンを列挙子に提供しなければならない。

CEnumMediaTypes クラスは、IPin::EnumMediaTypes メソッドが呼び出されると列挙子を作成する。ピンは、それがサポートするメディア タイプのリストを格納する。通常、メディア タイプの調整では、接続されているピンの EnumMediaTypes メソッドを一方のピンが呼び出して列挙子を取得し、それを使用してメディア タイプを選択する。これらの列挙子クラスは、どちらも COM プログラマに馴染みの Next、Skip、Reset、および Clone メソッドをサポートする。メディア タイプ列挙子は、派生ピン クラスによってオーバーライドされなければならない CBasePin::GetMediaType メンバ関数を呼び出し、そのピンで利用可能なメディア タイプのリスト内で次のメディア タイプを返す。

列挙子はスレッドとして動作し、ピン メディア タイプ リストへの同期アクセスを持たなければならない。このため、列挙子を実装するクラスは、クリティカル セクション管理を提供する CCritSec クラスを (複数の継承を介して) 継承する。CCritSec クラスの詳細については、「Win32 クラス」を参照すること。

転送基底クラス

転送クラスはピン間でメモリを共有し、そのメモリを使用してメディア サンプルを渡す。DirectShow では、ローカル メモリ転送の実装を行うための 4 つのクラスを提供している。

  • CBaseAllocator
  • CMemAllocator
  • CMediaSample
  • CImageSample

CBaseAllocator は、次の図に示すように、IMemAllocator インターフェイスを実装するためのメンバ関数を提供するクラスである。

入力ピンの IMemAllocator インターフェイスは、 割り当てるバッファの数およびサイズを設定するためのメソッドを指定し、そのメモリの割り当てと解放を行い、IMediaSample インターフェイスを含んでいる 1 つのバッファを返す。入力ピンに接続されている出力ピンは、IMemAllocator メソッドを呼び出す。CBaseAllocator は、Commit および Decommit メソッドから呼び出されるメンバ関数 Alloc および Free を提供する。派生クラスは Alloc および Free メンバ関数をオーバーライドして、メモリの割り当ておよび解放を行う専用のルーチンを提供する。

CBaseAllocator はそれ自体で実装をほとんど行わないので、ほとんどのピンは、CBaseAllocator から派生した CMemAllocator クラスを使用する。CMemAllocator は、CBaseAllocator::Free メンバ関数をオーバーライドして、システム メモリに基づいてメディア サンプルの割り当てを提供する。このクラスは、アロケータが最終的に解放されるときに呼び出される専用のメンバ関数である ReallyFree を提供する。

CMediaSample は、メディア サンプル データを格納するクラスであり、データ型や開始および終了タイム スタンプなどのメディア サンプルのプロパティにアクセスするメンバ関数を提供する。 このクラスは、メソッドの指定を提供する IMediaSample インターフェイスを実装する。CImageSample は CMediaSample から派生し、レンダラのアロケータが使用されるときにビデオ レンダラによって使用される。CImageSample は、CMediaSample インターフェイスのすべてのメソッドを使用するほか、DIBSECTION 情報を設定および取得するための 2 つのメソッドを使用する。これにより、レンダラは、アップストリーム フィルタから受け取った CMediaSample ポインタを容易に CImageSample ポインタにキャストして、ビデオ フレームのビットマップのハンドルを取得することができる。

メディア コントロールおよび配置クラス

メディア コントロール インターフェイスは、アプリケーションから Run、Stop、または Pause などのコマンドをフィルタ グラフ マネージャを介して個々のフィルタに渡す。フィルタ側から見て必要なコントロール インターフェイスは、これらのコマンドを受け付けて実装するためのメソッドを公開する IMediaFilter だけである。CBaseFilter クラスはこのインターフェイスを実装する。メディア コントロール メソッドを公開するほかのすべてのインターフェイスは、フィルタ グラフ マネージャによって扱われるので、既に実装されている。CMediaControl クラスが存在し、IMediaControl インターフェイスを実装した場合でも、フィルタ グラフ マネージャがその機能を制御するので、このインターフェイスはあまり使用されない。次の図は、これらのクラスとインターフェイスの関係を示している。

メディア配置インターフェイスは、指定された位置でメディア ストリームを開始したり、指定された期間ストリームを再生したり、またはメディア ストリームのレートを変更する。IMediaPosition インターフェイスは、この機能をサポートする主要なインターフェイスである。CMediaPosition クラスはこのインターフェイスを実装して、CPosPassThru および CSourcePosition の 2 つのクラスの基底クラスとして機能する。

通常、フィルタ グラフ マネージャは、メディア ストリームを配置するときにレンダリング フィルタの IMediaPosition インターフェイスを呼び出す。レンダラは、表示が予測されるサンプル タイムを認め、適切に配置されたソース ストリームを提供可能なアップストリームのシーク可能フィルタ (たとえばソース ファイル フィルタ) にメディア配置データを渡す。この情報をアップストリームに渡すためには、出力ピンは配置情報を受け取ることができなければならない。

CPosPassThru クラスは、フィルタの出力ピンの IMediaPosition インターフェイスおよび IMediaSeeking インターフェイスを実装するが、次のアップストリーム フィルタの出力ピンの対応するインターフェイスを呼び出して配置データを渡す以外の処理はほとんど行わない。IMediaSeeking は、メディア ストリームをタイム以外の単位 (たとえば MPEG フォーマットのフレーム、サンプル、またはインデックス付きフィールド) にシーク可能である点で IMediaPosition とは異なる。ビデオ レンダラに実装される CRendererPosPassThru クラスは、個々のサンプルの開始および終了基準タイムを設定する。したがって、この情報に関していつでもサンプルに対するクエリを行うことができる。これは IMediaSeeking を使ってシークを扱うときに役に立つ、それはメディア タイム をシークし、サンプルの基準タイムを追跡しないからだ。

グラフ内のすべてのフィルタに新しい位置を連続して通知する理由は、メディアの配置に関係のあるフィルタが新しい位置に対して準備できるようにするためである。たとえば特定のストリーム スプリッタは、メイン メディア ストリームを基準としたメディア位置を使用してストリームを分割しているかもしれない。これが、フィルタ グラフ マネージャが単純にソース フィルタの IMediaPosition または IMediaSeeking インターフェイスを直接呼び出さないことの理由である。

CSourcePosition は、ソース フィルタがその IMediaPosition インターフェイスを実装するのを支援するクラスである。

CSourceSeeking クラスは、ソース フィルタがその IMediaSeeking インターフェイスを実装するのを支援する。このクラスにより、メディア ストリーム内の開始位置や停止位置、再生レートを変更する呼び出しをソース フィルタが処理することが可能になる。

CBaseStreamControl クラスは、ソース フィルタがその IAMStreamControl インターフェイスを実装するのを支援する。このクラスは、主にキャプチャ フィルタによって使用される。次の図は、CBaseStreamControl とそれを継承したインターフェイスとの関係を示している。

クロック基底クラス

DirectShow では、フィルタ グラフでクロックを実装するための 2 つのクラスとして CBaseReferenceClock および CSystemClock が提供される。次の図は、これらのクラスとそれが実装するインターフェイスの関係を示している。

CBaseReferenceClock は IReferenceClock を実装する。これにより、要求されたときに正確な基準タイムを返したり、登録されたオブジェクトに特定のタイムや時間間隔をイベント通知およびセマフォを介してアドバイズする能力が提供される。

CSystemClock は、タイム情報とタイミング信号をアプリケーションに提供するシステム クロックを実装する。このクラスは、CBaseReferenceClock 基底クラスを使用して、実際のタイム呼び出しをオーバーライドしながらその機能のほとんどを提供する。

ユーティリティ クラス

Microsoft® DirectX® SDK には、必須の Win32 関数、マルチメディア データ構造体、およびオブジェクト リストおよびキュー操作の多くを C++ クラスにカプセル化したものを提供するユーティリティ クラスがいくつか含まれている。ここでは、これらのクラスについて簡単に説明する。

  • Win32 クラス
  • リストおよびキュー クラス
  • マルチメディア データ型クラス
  • COM ユーティリティ クラス
  • デバッギング クラス

Win32 クラス

DirectShow は、Win32 のスレッド、イベント、およびクリティカル セクションを扱うためのいくつかのクラスを実装している。このようなクラスには、以下のクラスがある。

  • CAMEvent
  • CCritSec
  • CAutoLock
  • CAMThread
  • CMsgThread
  • CMsg

次の図は、これらのクラスを示している。

Win32 ユーティリティ クラスの階層

CAMEvent は、Win32 イベントを C++ オブジェクトとして扱う。このクラスのメソッドを使用すると、イベントを通知済状態にしたり、未通知状態にリセットできるほか、イベントが通知済になるまで呼び出し元をブロック状態にすることができる。また、イベントをハンドルにキャストして Win32 WaitForMultipleObjects 関数に渡すこともできる。

CCritSec は、Win32 クリティカル セクションを C++ オブジェクトとして扱って、プロセス内同期化を提供する。このクラスのメソッドを使用すると、クリティカル セクションの作成、ロック、およびロック解除を行うことができる。

CAutoLock は、クリティカル セクション (CCritSec オブジェクト) をブロックまたは関数の範囲で保持する。クリティカル セクションは、コンストラクタでロックされ、デストラクタでロック解除される。

CAMThread は、抽象ワーカー スレッド クラスを提供し、作成、同期化、ほかのワーカー スレッドとの通信を可能にする。

CMsgThread は、要求を直接ではなく非同期に送ることが可能なワーカー スレッドのサポートを提供する。CMsg オブジェクトのフォーマットを持つメッセージは、CMsgThread オブジェクトに送ることができる。

CMsg は、CMsgThread オブジェクトに渡されるメッセージを含んだオブジェクトを作成する。

リストおよびキュー クラス

次の図に示すように、DirectShow は、リストおよびキューを扱うための CBaseList、CGenericList、および COutputQueue クラスを実装している。

リストおよびキュー ユーティリティ クラスの階層

CBaseList は、CBaseObject から派生したオブジェクトへの型なしポインタのリンク リスト データ構造体を表す。

CGenericList は、CBaseList メンバ関数を呼び出す CBaseList から派生したテンプレート クラスを実装し、テンプレートで指定されたタイプのタイプ チェックを追加する。

COutputQueue は、フィルタの出力ピンからのメディア サンプルをキューに入れる処理をサポートする。出力ピンは、接続されている入力ピンのメソッドを呼び出す代わりに、このクラスのメンバ関数を呼び出してメディア サンプルを受け取る。COutputQueue クラスがメディア サンプルをダウンストリームに渡す処理を受け持つ一方で、出力ピンはブロッキングなしで処理を続行できる 。

マルチメディア データ型クラス

次の図に示すように、DirectShow は、CMediaType、CRefTime、および FOURCCMap マルチメディア データ型クラスを実装している。

CMediaType は、メディア タイプ データ構造体および構造体の各メンバへのアクセスを提供するメソッドを含んだ C++ クラス オブジェクトを提供する。

CRefTime は、基準タイムにアクセスするためのメソッドを含む C++ クラス オブジェクト、および 2 つの CRefTime オブジェクトに対してブール テストまたは演算を行うための演算子を提供する。

FOURCCMap は、メディア タイプの識別と登録を行うために使用される古いフォーマットの FOURCC メディア タグと、DirectShow で使用される GUID メディア サブタイプとの間の変換を行う。

COM ユーティリティ クラス

DirectShow の COM インターフェイス クラスは、オブジェクト作成とインターフェイス実装の 2 つに分類される。クラス ファクトリ クラスは、オブジェクトの作成用に提供され、それ以外のクラスは、既存の COM インターフェイスを実装するために提供される。

COM ユーティリティ クラスには、以下のクラスがある。

  • CClassFactory
  • CFactoryTemplate
  • CPersistStream
  • CBasePropertyPage

次の図は、COM クラスとそれが実装するインターフェイスの関係を示している。

COM ユーティリティ クラスの階層

CClassFactory および CFactoryTemplate は、フィルタ、ピン、およびその他の DirectShow COM オブジェクトの自動インスタンス化を扱うために基底クラスによって実装される。 これらのクラスは、オブジェクトを作成するのに必要な実際の COM 要素をラッピングして、オブジェクトを作成するうえでの基礎部分を提供する。 CPersistStream および CBasePropertyPage は、COM 持続ストレージおよびプロパティ ページ インターフェイスの実装に役に立つ。

Dllentry.cpp にある CClassFactory は CBaseObject を継承したクラスで、COM IClassFactory インターフェイスを実装する。このインターフェイスは、IClassFactory::CreateInstance を呼び出すことによって COM オブジェクトをインスタンス化する CoCreateInstance によって使用される (IClassFactory::CreateInstance は、派生クラスの静的 CreateInstance メンバ関数を呼び出す)。

基底クラスは CFactoryTemplate を使用して、オブジェクトの CLSID を含むテンプレートと、オブジェクト クラスの静的 CreateInstance 関数へのポインタを CClassFactory に提供する。

CPersistStream は COM IPersistStream を実装して、保存されているフィルタ グラフのフィルタ プロパティの格納と取得を行う。これにより、格納されているフィルタ グラフは、定義済みのプロパティ値に設定されたフィルタを持つことができる。このクラスはまた、ストリーム内のデータのバージョン化を扱う特殊なメンバ関数を提供する。

CBasePropertyPage は、フィルタに関連するプロパティ ページのフレームワークを提供する COM IPropertyPage インターフェイスを実装する。

デバッギング クラス

DirectShow は、「デバッギング」リファレンス セクションに説明するように、多くのデバッギング関数およびマクロを提供する。DirectShow には、デバッギング フィルタの開発に便利な 3 つのクラスが用意されている。

  • CDispBasic
  • CDisp
  • CGuidNameList

次の図は、この 3 つのクラスを示している。

デバッギング ユーティリティ クラスの階層

CDispBasic は、m_PString データ メンバを適切な文字列サイズに変換する。

CDisp は、CDispBasic クラスの m_PString データ メンバを、コンストラクタのパラメータとして使用されるオブジェクトに関する適切なデバッギング情報を記述する文字列に設定する、コンストラクタを提供する。たとえば、IPin ポインタを使用して作成された場合、m_PString はピンの名前を返し、CLSID を使用して作成された場合、m_PString はそれを示す文字列を返す。また、このクラスは m_PString の値を返す LPCTSTR キャスト演算子を提供するので、LPCTSTR 値として単にクラスをキャストして、作成時に文字列を返すことができる。

CGuidNameList は、Uuids.h インクルード ファイル内の GUID (グローバル ユニーク識別子) 名の配列を実装する。これにより、たとえばメディア タイプの GUID 名を取得することができる。


CAggDirectDraw クラス

CAggDirectDraw クラスは IDirectDraw インターフェイスを集成する。Microsoft® DirectDraw® のインターフェイス (IDirectDraw および IDirectDrawSurface) は本来集成することができるが、この機能は現在実装されていない。Microsoft DirectShow® のさまざまなパーツは DirectDraw インターフェイスの集成を必要とする。特に、ビデオ レンダラは、IDirectDraw および IDirectDrawSurface を公開するメディア サンプルを渡す。このクラスおよび CAggDrawSurface クラスは、DirectDraw クラスのメソッドを再公開し、集成できるようにする。

このクラスのコンストラクタ以外の各メンバ関数、SetDirectDraw および NonDelegatingQueryInterface は、パラメータを渡して IDirectDraw インターフェイスの対応するメソッドを呼び出す。

プロテクト データ メンバ

m_pDirectDraw DirectDraw オブジェクト。

メンバ関数

CAggDirectDraw | CAggDirectDraw オブジェクトを作成する。
SetDirectDraw | このクラスによって集成される DirectDraw オブジェクトを設定する。

オーバーライド可能なメンバ関数

NonDelegatingQueryInterface インターフェイスを取得し、参照カウントをインクリメントする。

実装される IDirectDraw メソッド

以下の IDirectDraw メソッドが実装される。詳細については、DirectDraw のドキュメントを参照すること。

Compact | ビデオ カード上のすべてのサーフェス メモリを連続ブロックに移動し、最大空きメモリ チャンクを使用可能にする。
CreateClipper | DirectDrawClipper オブジェクトを作成する。
CreatePalette | この DirectDraw オブジェクトに対する DirectDrawPalette オブジェクトを作成する。
CreateSurface | この DirectDraw オブジェクトに対する DirectDrawSurface オブジェクトを作成する。
DuplicateSurface | DirectDrawSurface オブジェクトを複製する。
EnumDisplayModes | ハードウェアが DirectDraw オブジェクトを介して公開するディスプレイ モードのうち、提供されたサーフェス記述と互換性があるすべてのディスプレイ モードを列挙する。
EnumSurfaces | 指定された検索基準に合う、既存のまたは可能なサーフェスをすべて列挙する。
FlipToGDISurface | GDI が書き込むサーフェスをプライマリ サーフェスにする。
GetCaps | デバイス ドライバ (ハードウェア) やハードウェア エミュレーション レイヤ (HEL) の能力 (残りの能力ではない) を格納する。
GetDisplayMode | 現在のディスプレイ モードを取得する。
GetFourCCCodes | DirectDraw オブジェクトによってサポートされる FOURCC コードを取得する。
GetGDISurface | GDI がプライマリ サーフェスとして処理するサーフェス メモリを現在示す DirectDrawSurface オブジェクトを取得する。
GetMonitorFrequency | DirectDraw オブジェクトが動作するモニタの周波数を取得する。
GetScanLine | モニタ上で現在描画されている走査線を取得する。
GetVerticalBlankStatus | 垂直同期の状態を取得する。
Initialize | DirectDraw オブジェクトを初期化する。
RestoreDisplayMode | プライマリ サーフェスのディスプレイ デバイス ハードウェアのモードを、CAggDirectDraw::SetDisplayMode メンバ関数が呼び出される前の状態にリセットする。
SetCooperativeLevel | アプリケーションの最上位動作を決定する。
SetDisplayMode | ディスプレイ デバイス ハードウェアのモードを設定する。
WaitForVerticalBlank | 呼び出し元が垂直同期間隔と同期できるようにする。

CAggDirectDraw::CAggDirectDraw

CAggDirectDraw クラス

CAggDirectDraw オブジェクトを作成する。

構文

CAggDirectDraw(
TCHAR *pName,
LPUNKNOWN pUnk
    );

パラメータ

pName
オブジェクトの名前へのポインタ。デバッグのために使用される。
pUnk
このオブジェクトの所有者へのポインタ。NULL 以外の場合、IUnknown の呼び出しはこのオブジェクトに委任される。

戻り値

戻り値なし。

注意

このメンバ関数は、CUnknown::CUnknown 基底クラス コンストラクタを呼び出し、m_pDirectDraw メンバ変数を NULL に設定する。

CAggDirectDraw::NonDelegatingQueryInterface

CAggDirectDraw クラス

インターフェイスを取得し、参照カウントをインクリメントする。

構文

HRESULT NonDelegatingQueryInterface(
REFIID riid,
void **ppv
    );

パラメータ

riid
参照識別子。
ppv
インターフェイスへのポインタのアドレス。

戻り値

ppv が無効な場合は、E_POINTER を返す。クエリが成功した場合は NOERROR、失敗した場合は E_NOINTERFACE を返す。

注意

このメンバ関数は、INonDelegatingUnknown::NonDelegatingQueryInterface メソッドを実装する。デフォルトでは、IDirectDraw への参照を渡し、CUnknown::NonDelegatingQueryInterface メンバ関数を呼び出して、基底クラスのインターフェイス参照を取得する。このクラスをオーバーライドして、派生クラスで追加されたインターフェイスを返す。

CAggDirectDraw::SetDirectDraw

CAggDirectDraw クラス

このクラスによって集成される DirectDraw オブジェクトを設定する。

構文

void SetDirectDraw(
LPDIRECTDRAW pDirectDraw
    );

パラメータ

pDirectDraw
集成される IDirectDraw オブジェクトへのポインタ。

戻り値

戻り値なし。

注意

このメンバ関数は、m_pDirectDraw データ メンバを pDirectDraw パラメータに設定する。


CAggDrawSurface クラス

CAggDrawSurface クラスは IDirectDrawSurface インターフェイスを集成する。Microsoft® DirectDraw® のインターフェイス (IDirectDraw および IDirectDrawSurface) は本来集成することができるが、この機能は現在実装されていない。Microsoft® DirectShow® のさまざまなパーツは DirectDraw インターフェイスの集成を必要とする。特に、ビデオ レンダラは、IDirectDraw および IDirectDrawSurface を公開するメディア サンプルを渡す。このクラスおよび CAggDirectDraw クラスは、DirectDraw クラスのメソッドを再公開し、集成できるようにする。

このクラスのコンストラクタ以外の各メンバ関数、SetDirectDrawSurface および NonDelegatingQueryInterface は、パラメータを渡して IDirectDrawSurface インターフェイスの対応するメソッドを呼び出す。

プロテクト データ メンバ

m_pDirectDrawSurface DirectDraw サーフェス。

メンバ関数

CAggDrawSurface | CAggDrawSurface オブジェクトを作成する。
SetDirectDrawSurface | このクラスによって集成される DirectDraw オブジェクトを設定する。この関数は、IDirectDrawSurface インターフェイスのメソッドを呼び出す前に呼び出さなければならない。

オーバーライド可能なメンバ関数

NonDelegatingQueryInterface インターフェイスを取得し、参照カウントをインクリメントする。

実装される IDirectDrawSurface メソッド

以下の IDirectDrawSurface メソッドが実装される。詳細については、DirectDraw のドキュメントを参照すること。

AddAttachedSurface | サーフェスを別のサーフェスにアタッチする。可能なアタッチの例としては、Z バッファ、アルファ チャンネル、およびバック バッファがある。
AddOverlayDirtyRect | 次に UpdateOverlayDisplay メンバ関数を呼び出したときに更新しなければならない矩形のリストを構築する。
Blt | ビットブロック転送を実行する。
BltBatch | 複数の転送元から単一の転送先に一連の CAggDrawSurface::Blt 処理を実行する。
BltFast | 転送元または転送先のカラー キーを使用して、転送元コピーのビットブロック転送または透過型ビットブロック転送を実行する。
DeleteAttachedSurface | 2 つのサーフェス間のアタッチを解除する。
EnumAttachedSurfaces | 与えられたサーフェスにアタッチされるすべてのサーフェスを列挙する。
EnumOverlayZOrders | 指定された転送先のオーバーレイを列挙する。オーバーレイは、フロントからバック、またはバックからフロントの順で列挙される。
Flip | DDSCAPS_BACKBUFFER サーフェスと関連付けられたサーフェス メモリを、FRONTBUFFER サーフェスと関連付ける。
GetAttachedSurface | 指定した能力を持つアタッチされたサーフェスを取得する。
GetBltStatus | ビットブロック転送の状態を取得する。
GetCaps | サーフェスの能力を取得する。
GetClipper | このサーフェスに関連付けられた DirectDrawClipper オブジェクトを取得する。
GetColorKey | DirectDrawSurface オブジェクトのカラー キー値を取得する。
GetDC | サーフェスの GDI 互換 hDC を作成する。
GetFlipStatus | 呼び出したサーフェスでフリッピングが終了している場合は OK を返し、それ以外の場合は DDERR_WASSTILLDRAWING を返す。
GetOverlayPosition | 表示状態のアクティブなオーバーレイ サーフェス (DDSCAPS_OVERLAY が設定されている) が与えられると、サーフェスのディスプレイ座標を取得する。
GetPalette | このサーフェスに関連付けられた DirectDrawPalette 構造体を取得する。
GetPixelFormat | サーフェスのカラーとピクセル フォーマットを取得する。
GetSurfaceDesc | 現在の状態におけるサーフェスを記述する DDSURFACEDESC 構造体を取得する。
Initialize | DirectDrawSurface オブジェクトを初期化する。
IsLost | DirectDrawSurface オブジェクトに関連付けられたサーフェス メモリが解放されたかどうかを判断する。
Lock | サーフェス メモリへの有効なポインタを取得する。
ReleaseDC | CAggDrawSurface::GetDC によって取得された GDI 互換 hDCを解放する。
Restore | "消失" したサーフェスをリストアする。DirectDrawSurface オブジェクトに関連付けられたサーフェス メモリは解放されている。
SetClipper | DirectDrawClipper オブジェクトを DirectDrawSurface オブジェクトにアタッチする。
SetColorKey | ハードウェアがサーフェスごとのカラー キー値をサポートしている場合に、DirectDrawSurface オブジェクトのカラー キー値を設定する。
SetOverlayPosition | オーバーレイ サーフェスのディスプレイ座標を変更する。
SetPalette | 指定された DirectDrawPalette オブジェクトを DirectDrawSurface にアタッチする。
Unlock | DirectDraw に直接サーフェス処理が完了したことを通知する。
UpdateOverlay | オーバーレイ サーフェスのビジュアル属性を再配置したり変更する。これらのサーフェスには、DDSCAPS_OVERLAY ビットを設定する必要がある。
UpdateOverlayDisplay | すべてのアクティブ オーバーレイのダーティー矩形のリストにある矩形を再描画する。
UpdateOverlayZOrder | オーバーレイの Z オーダーを設定する。Z オーダーは、複数のオーバーレイを同時に表示するときにどのオーバーレイが遮られるかを決定する。

CAggDrawSurface::CAggDrawSurface

CAggDrawSurface クラス

CAggDrawSurface オブジェクトを作成する。

構文

CAggDrawSurface(
  TCHAR *pName,
  LPUNKNOWN pUnk
  );

パラメータ

pName
オブジェクトの名前へのポインタ。デバッグのために使用される。
pUnk
このオブジェクトの所有者へのポインタ。NULL 以外の場合、IUnknown インターフェイスの呼び出しはこのオブジェクトに委任される。

戻り値

戻り値なし。

注意

このメンバ関数は、CUnknown::CUnknown 基底クラス コンストラクタを呼び出し、m_pDirectDrawSurface メンバ変数を NULL に設定する。

CAggDrawSurface::NonDelegatingQueryInterface

CAggDrawSurface クラス

インターフェイスを取得し、参照カウントをインクリメントする。

構文

HRESULT NonDelegatingQueryInterface(

  REFIID riid,

  void **ppv

  );

パラメータ

riid
参照識別子。
ppv
インターフェイスへのポインタのアドレス。

戻り値

ppv が無効な場合は、E_POINTER を返す。クエリが成功した場合は NOERROR、失敗した場合は E_NOINTERFACE を返す。

注意

このメンバ関数は、INonDelegatingUnknown::NonDelegatingQueryInterface メソッドを実装する。デフォルトでは、IDirectDrawSurface への参照を渡し、CUnknown::NonDelegatingQueryInterface メンバ関数を呼び出して、基底クラスのインターフェイス参照を取得する。このクラスをオーバーライドして、派生クラスで追加されたインターフェイスを返す。

CAggDrawSurface::SetDirectDrawSurface

CAggDrawSurface クラス

この集成オブジェクトの所有者によって呼び出され、集成が行われる実際の DirectDraw サーフェスを設定する。

構文

void SetDirectDrawSurface(
  LPDIRECTDRAWSURFACE pDirectDrawSurface
  );

パラメータ

pDirectDrawSurface
設定される IDirectDraw サーフェスへのポインタ。

戻り値

戻り値なし。

注意

このメンバ関数は、IDirectDrawSurface インターフェイスのメソッドを呼び出す前に呼び出さなければならない。


CAMEvent クラス

手動および自動リセット イベントのラッパー クラス。

定義: Wxutil.h

このクラスは CreateEvent、WaitForSingleObject、ResetEvent のような Microsoft® Win32® 関数よりも簡便なイベント管理方法を提供する。

プロテクト メンバ変数
m_hEvent | イベント ハンドル。
Public メソッド
CAMEvent | コンストラクタ メソッド。
~CAMEvent | デストラクタ メソッド。
Check | イベントがブロッキングなしに設定されているかどうかをチェックする。
Reset | イベントの状態を未通知に設定する。
Set | イベントのシグナル
Wait | イベントが通知済になるか、タイムアウトが発生するまでブロックする。
演算子
HANDLE | イベント ハンドルを取得する。

CAMEvent.m_hEvent

CAMEvent クラス

イベント ハンドル。

構文

HANDLE m_hEvent;

CAMEvent::CAMEvent

CAMEvent クラス

コンストラクタ メソッド。

構文

CAMEvent(
BOOL fManualReset = FALSE
    );

パラメータ

fManualReset
オブジェクトが手動リセット イベントまたは自動リセット イベントのどちらであるかを指定するブール型の値。TRUE の場合、オブジェクトは手動リセット イベントである。それ以外の場合は、自動リセット イベントである。

注意

イベントは未通知状態で始まる。

自動リセット イベントの場合、CAMEvent::Wait メソッドは、メソッドが返るときにイベントを未通知にリセットする。手動リセット イベントの場合、CAMEvent::Reset メソッドを呼び出すまで、イベントは通知済のままである。

CAMEvent::~CAMEvent

CAMEvent クラス

ディストラクタ メソッド

構文

~CAMEvent(void);

CAMEvent::Check

CAMEvent クラス

イベントがブロッキングなしに設定されているかどうかをチェックする。

構文

BOOL Check(void);

注意

イベントが設定されている場合は TRUE、それ以外の場合は FALSE を返す。

注意

このメソッドは、タイムアウトに 0 を指定して Wait メソッドを呼び出す。オブジェクトが自動リセット イベントの場合、このメソッドはイベントをリセットする。

CAMEvent::Reset

CAMEvent クラス

イベントの状態を未通知に設定する。

構文

void Reset(void);

CAMEvent::Set

CAMEvent クラス

イベントのシグナル。

構文

void Reset(void);

注意

この振る舞いはオブジェクトが自動リセットイベントか、手動リセット イベントかに依存する :

  • 自動リセット : 任意のスレッドがこのイベントを待っている場合、あるスレッドが解放されイベントはリセットされる。このイベントを待っているスレッドがない場合、イベントは通知済のまま残る。
  • 手動リセット : このイベントを待っているすべてのスレッドが解放される。イベントは通知済のまま残る。

CAMEvent::Wait

CAMEvent クラス

イベントが通知済になるか、タイムアウトが発生するまでブロックする。

構文

BOOL Wait(
DWORD dwTimeout = INFINITE
);

パラメータ

dwTimeout
オプションのタイムアウト値 (ミリ秒単位)。

戻り値

イベントが通知済になった場合は、TRUE を返す。それ以外の場合は、FALSE を返す。

注意

自動リセット イベントの場合、このメソッドが返るとイベントは未通知状態にリセットされる。

CAMEvent::operator HANDLE

CAMEvent クラス

イベント ハンドルを取得する。この演算子は左辺値はサポートされない。

構文

operator HANDLE () const;

戻り値

m_hEvent メンバ変数を返す。


CAMMsgEvent クラス

メッセージ処理を行うイベント オブジェクトのラッパー クラス

定義 : Wxutil.h

このクラスは CAMEvent オブジェクトから派生しており、1 つのメソッド WaitMsg を追加する。このメソッドは、待機中に受信したメッセージをディスパッチする。

Public メソッド
WaitMsg 送られたメッセージをディスパッチすると同時に、イベントが通知済になるのを待つ。

CAMMsgEvent::WaitMsg

CAMMsgEvent クラス

送られたメッセージをディスパッチすると同時に、イベントが通知済になるのを待つ、あるいは指定されたタイムアウトが起こるのを待つ。

構文

BOOL WaitMsg(
DWORD dwTimeOut = INFINITE
    );

パラメータ

dwTimeOut
オプションのタイムアウト値 (ミリ秒単位)。

戻り値

イベントが通知済になった場合は TRUE、タイムアウトが発生した場合は FALSE を返す。

注意

このメソッドはメッセージ処理に PeekMessage 関数を呼び出す。スレッドがイベントを待つ間にメッセージを処理する必要がある場合、CAMEvent::Wait の代わりにこのメソッドを呼び出す。 スレッドがメッセージを処理せず他のスレッドがメッセージを送った場合、デッドロックが起こる可能性がある。

たとえば、スレッドを作成してからそのスレッドの初期化までブロックしたとする。そのスレッドが SendMessage 関数を呼び出して、ウィンドウにメッセージを送るとデッドロックになる。これは SendMessage はそのメッセージが処理されるまで返らないからだ。WaitMsg を使えば SendMessage は返り、デッドロックは避けられる。


CAMSchedule クラス

基準クロックのスケジューラ。

宣言: Schedule.h

このヘルパー オブジェクトは、基準クロックのアドバイズ要求のリストを維持する。CBaseReferenceClock クラスは、このオブジェクトを使ってアドバイズ要求のスケジューリングを手助けする。クロックは、このオブジェクトを次のように使用する。

  1. クロックは、ワーカー スレッドを作成してスケジューリングを処理する。
  2. ワーカー スレッドは GetEvent メソッドを呼び出して、スケジューラからイベント ハンドルを取得する。スレッドは、最初は無限タイムアウトを使って、このイベントで待ち状態となる。
  3. 新しいアドバイズ要求をスケジュールするため、クロックは AddAdvisePacket メソッドを呼び出す。アドバイズ要求は、単発または周期的なものとすることができる。スケジューラは、時間順に要求リストを維持する。
  4. リストの先頭に要求が追加されると、スケジューラはイベントを通知する。このリストは最初は空であるので、最初の要求があるとイベントは確実に通知される。
  5. イベントが通知済になると、ワーカー スレッドは Advise メソッドを呼び出し、現在の基準タイムを指定する。保留中の要求の有効期限が切れると、スケジューラはそれらの要求をディスパッチする。
  6. Advise メソッドは、次の要求のタイムを返す。ワーカー スレッドはこの値を使って、新しいタイムアウト値を計算する。
  7. ステップ 2 ～ 6 は、無限に繰り返される。
  8. ワーカー スレッドを終了するため、クロックは内部フラグを設定し、イベントを通知する。

ステップ 2 では、イベントが通知済になるか、または待ちのタイムアウトが発生する。イベントが通知済になる場合は、新しい要求がリストの先頭に追加されたことを意味する。ワーカー スレッドは新しいタイムアウト値を計算しなければならない。一方、待ちのタイムアウトが発生する場合は、アドバイズ要求の期限期限が切れており、ディスパッチされなければならないことを意味する。いずれの場合も、ステップ 5 の Advise の呼び出しによって処理が行われる。

Public メソッド
CAMSchedule | コンストラクタ メソッド。
~CAMSchedule | デストラクタ メソッド。仮想。
GetAdviseCount | 保留中のアドバイス要求数を取得する。
GetNextAdviseTime | 次のアドバイズ要求のタイムを取得する。
AddAdvisePacket | 保留中の要求リストにアドバイズ要求を追加する。
Unadvise | アドバイズ要求を削除する。
Advise | 特定のタイムまたはそれ以前にスケジュールされた、すべての要求をディスパッチする。
GetEvent | イベント ハンドルを取得する。これは、次のアドバイズ タイムの変更を通知するために使われる。

CAMSchedule::AddAdvisePacket

CAMSchedule クラス

新しい保留中の通知を作成し、アドバイズ通知リストに追加する。

構文

DWORD AddAdvisePacket(
    const REFERENCE_TIME& time1,
    const REFERENCE_TIME& time2,
    HANDLE hNotify,
    BOOL bPeriodic
);

パラメータ

time1
アドバイズの要求タイム。
time2
周期的なアドバイズ要求での通知の間隔。bPeriodic が FALSE の場合、このパラメータは無視される。
hNotify
bPeriodic が TRUE の場合はセマフォ ハンドル。bPeriodic が FALSE の場合はイベント ハンドル。
bPeriodic
周期的な通知を追加するか、単発の通知を追加するかを指定するブール値。TRUE の場合、通知は周期的になる。time2 パラメータによって、通知の間隔が指定される。FALSE の場合、通知は単発で発生する。

戻り値

アドバイズ要求の識別子 (Cookie) を返す。メソッドが失敗した場合、戻り値は 0 になる。

CAMSchedule::Advise

CAMSchedule クラス

特定のタイムまたはそれ以前にスケジュールされた、すべての要求をディスパッチする。

構文

REFERENCE_TIME Advise(
    const REFERENCE_TIME& rtTime
);

パラメータ

rtTime
現在の基準タイムを指定する値。

戻り値

次にスケジュールされたアドバイズ要求の基準タイムを返す。アドバイズがない場合は MAX_TIME を返す。

注意

クロックがこのメソッドを呼び出す際に、現在の基準タイムを指定する。スケジューラは、有効期限が切れたアドバイズを判定し、それらをディスパッチする。単発要求の有効期限が切れた場合、スケジューラはその要求を削除する。周期的な要求の有効期限が切れた場合、スケジューラは次のアドバイズ タイムにそれらを再スケジュールする。このメソッドは、保留中の次の要求のタイムを返す。

アドバイズ要求をディスパッチするため、スケジューラは、AddAdvisePacket メソッドの hNotify パラメータに指定されたイベントまたはセマフォを通知する。

CAMSchedule::CAMSchedule

CAMSchedule クラス

コンストラクタ メソッド。

構文

CAMSchedule(
    HANDLE hEvent
);

パラメータ

hEvent
自動リセット イベントへのハンドル。

CAMSchedule::~CAMSchedule

CAMSchedule Class

デストラクタ メソッド。

構文

~CAMSchedule(void);

CAMSchedule::GetAdviseCount

CAMSchedule クラス

未処理のアドバイス要求の数を取得する。

構文

DWORD GetAdviseCount(void);

戻り値

未処理のイベントの数を返す。

CAMSchedule::GetEvent

CAMSchedule クラス

アドバイズ タイムが再評価を必要とする場合に、設定するイベント ハンドルを取得する。

構文

HANDLE GetEvent(void);

戻り値

このオブジェクトのアドバイズ タイムが再評価を必要とする場合に、設定するイベントへのハンドルを返す。

CAMSchedule::GetNextAdviseTime

CAMSchedule クラス

次のアドバイズのタイムをチェックする。

構文

REFERENCE_TIME GetNextAdviseTime(void);

戻り値

次のアドバイズが設定されている基準タイムを返す。イベントがスケジュールされていない場合は MAX_TIME を返す。

CAMSchedule::Unadvise

CAMSchedule クラス

アドバイズ リクエストを削除する。

構文

HRESULT Unadvise(
    DWORD dwAdviseCookie
);

パラメータ

dwAdviseCookie
アドバイズ リクエストの識別子。この値は、AddAdvisePacket メソッドによって返される。

戻り値

以下の表にある HRESULT 値の 1 つを返す。

S_FALSE | 見つけられない
S_OK | 成功


CAMThread クラス

ワーカー スレッドを管理する抽象クラス。

宣言 : Wxutil.h

このクラスはワーカー スレッドの作成、そのスレッドへのリクエストの送信、そのスレッドの終了の待機を提供する。このクラスの使用方法は次のとおり :

  • CAMThread からクラスを派生し、純粋な仮想メソッド ThreadProc をオーバーライドする。このメソッドはスレッドの開始時に呼び出されるスレッド プロシージャである。
  • アプリケーション内で、派生クラスのインスタンスを作成する。スレッドを 作成しない オブジェクトを作成する。 スレッドの作成には Create メソッドを使用する。
  • スレッドにリクエストを送るには、CallWorker メソッドを呼び出す。このメソッドの DWORD パラメータの意味はクラスによって定義される。このメソッドはスレッドが応答するまでブロックする(次を参照)。
  • スレッド プロシージャで、GetRequest あるいは CheckRequest のどちらかを呼び出すことによって応答をリクエストする。GetRequest メソッドは非ブロッキングで、これによりそのスレッドは非同期に動作している最中に新しいリクエストをチェックできる。
  • スレッドはリクエストを受け取ると、Reply を呼び出して要求もとのスレッドを非ブロックとする。Reply メソッドの DWORD パラメータは CallWorker の戻り値として要求もとのスレッドに渡される。

スレッドでの処理が終了したら、Close メソッドを呼び出す。このメソッドはスレッドの終了を待機し、スレッド ハンドルを閉じる。ThreadProc メッセージはそれ自身であれ、CallWorker リクエストへの応答であれ、終了を保証するものでなければならない。デストラクタ メソッドもまた Close を呼び出す。

次の例はこのステップを示す。

class MyThread : public CAMThread
{
protected:
    DWORD ThreadProc(void);
};

DWORD MyThread::ThreadProc()
{
    BOOL bShutDown = FALSE;
    while (!bShutDown)
    {
        DWORD req = GetRequest();
        printf("Request: %d\n", req);
        bShutDown = (req == 0);
        Reply(bShutDown ? S_FALSE : S_OK);
    }
    printf("Quitting Thread\n");
    return 1;
}

void main()
{
    MyThread thread;
    DWORD reply;

    thread.Create();
    reply = thread.CallWorker(3);
    reply = thread.CallWorker(0); // スレッド終了
}

派生したクラスで、CallWorker のパラメータを有効にするメンバ関数を定義することもできる。次の例はこれの一般的な方法を示す。

enum Command {CMD_INIT, CMD_RUN, CMD_STOP, CMD_EXIT};

HRESULT Init(void)  { return CallWorker(CMD_INIT); }
HRESULT Run(void)   { return CallWorker(CMD_RUN); }
HRESULT Stop(void)  { return CallWorker(CMD_STOP); }
HRESULT Exit(void)  { return CallWorker(CMD_EXIT); }

CAMThread クラスはパブリック メンバ変数として 2 つのクリティカル セクションを提供する。m_AccessLock を使って、他のスレッドからアクセスされているスレッドをロックする。(たとえば、Create と CallWorker メソッドはこのロックを保持し、スレッドの操作を継続する。) m_WorkerLock を使い、スレッド間で共有されているデータをロックする。

Protected メンバ変数
m_hThread | スレッドのハンドル。
Public メンバ関数
m_AccessLock | 他のスレッドからアクセスされてるスレッドをロックするクリティカル セクション。
m_WorkerLock | スレッド間で共有されているデータをロックするクリティカル セクション。
Public メソッド
CAMThread | コンストラクタ メソッド。
~CAMThread | デストラクタ メソッド。仮想。
InitialThreadProc | スレッドが作成されたとき ThreadProc メソッドを呼び出す。
Create | スレッドの作成。
CallWorker | スレッドにリクエストを通知する。
Close | スレッドの終了を待ち、そのリソースを解放する。
ThreadExists | スレッドが終了したかどうかを調べる。
GetRequest | 次のリクエストを待つ。
CheckRequest | リクエストがあれば、ブロッキングなしでチェックする。
Reply | リクエストに応答する。
GetRequestHandle | CallWorker メソッドで通知済のイベントのハンドルを取得する。
GetRequestParam | 最新のリクエストを取得する。
CoInitializeHelper | スレッドの開始時に CoInitializeEx を呼び出す。
純粋な仮想メソッド
ThreadProc | スレッド プロシージャ。

CAMThread.m_AccessLock

CAMThread クラス

他のスレッドからアクセスされているスレッドをロックするクリティカル セクション。

構文

CCritSec m_AccessLock;

注意

Create と CallWorker メソッドはこのロックを保持し、スレッドの操作を継続する。

CAMThread.m_WorkerLock

CAMThread クラス

スレッド間で共有されているデータをロックするクリティカル セクション

構文

CCritSec m_WorkerLock;

CAMThread.m_hThread

CAMThread クラス

スレッドのハンドル

構文

HANDLE m_hThread;

注意

この変数は NULL で初期化される。Create メソッドはこの変数をスレッド ハンドルに設定する。スレッドが終了したかどうかを見極めるには、ThreadExists メソッドを呼び出す。

CAMThread::CAMThread

CAMThread クラス

コンストラクタ メソッド。

構文

CAMThread(void);

注意

このコンストラクタ メソッドはスレッドを作成しない。スレッドを作成するには Create を呼び出す。

CAMThread::~CAMThread

CAMThread クラス

デストラクタ メソッド

構文

virtual ~CAMThread(void);

注意

このデストラクタ メソッドは Close メソッドを呼び出す、このメソッドはスレッドの終了を待つ。

CAMThread::CallWorker

CAMThread クラス

スレッドにリクエストを通知する。

構文

DWORD CallWorker(
    DWORD dwParam
);

パラメータ

dwParam
リクエスト パラメータ。この派生クラスはパラメータの意味を定義する。

戻り値

派生クラスが定義した値を返す。

注意

GetRequest と CheckRequest メソッドは dwParam パラメータの値を取得する。GetRequest メソッドは CallWorker が呼び出されるまでブロックする。

このメソッドは Reply メソッドが呼び出されるまでブロックする。戻り値は Reply によって与えられたパラメータ。

このメソッドは m_AccessLock ロックをホールドし、リクエストを継続する。したがって、スレッドからあるいはスレッドのコンテクストを実行するメンバ関数からこのメソッドを呼び出す。

CAMThread::CheckRequest

CAMThread クラス

リクエストがあれば、ブロッキングなしでチェックする。

構文

BOOL CheckRequest(
    DWORD *pParam
);

パラメータ

pParam
CallWorker メソッドの最後の呼び出しに通した値を受け取る変数のポインタ。

戻り値

未処理のリクエストがあれば TRUE を、それ以外なら FALSE を返す。

注意

このメソッドは GetRequest の非ブロッキング版である。

他のスレッドが CallWorker の呼び出しを待っているなら、このメソッドはリクエストパラメータを取得し、TRUE を返す。それ以外の場合、FALSE を返す。このメソッドが TRUE を返したら、Reply メソッドを呼び出し、スレッドのリクエストを取得する。

CAMThread::Close

CAMThread クラス

スレッドの終了を待ち、そのリソースを解放する。

構文

void Close(void);

戻り値

戻り値なし。

注意

このメソッドを呼び出す前に、スレッドが終了できるようにしなければならない。たとえば ThreadProc メソッドを使って、スレッドに対して終了を通知するリクエストを定義する。次に CAMThread::CallWorker メソッドをその値で呼び出す。

The ~CAMThread デストラクタ メソッドはこのメソッドを呼び出す。

CAMThread::Create

CAMThread クラス

スレッドの作成。

構文

BOOL Create(void);

戻り値

成功すれば TRUE を返し、それ以外なら FALSE を返す。

注意

このメソッドはスレッドを作成する、その際スレッド プロシ－ジャとして InitialThreadProc メソッドを、スレッド引数として this を使用する。

このメソッドはスレッドが既にある場合失敗する。

CAMThread::CoInitializeHelper

CAMThread クラス

スレッドが開始されたとき CoInitializeEx 関数を呼び出す。

構文

static HRESULT CoInitializeHelper(void);

戻り値

HRESULT 値を返す。以下はその値である。

S_FALSE | CoInitializeEx 関数は有効ではない。
S_OK | 成功。
E_FAIL | 失敗。

注意

InitialThreadProc メソッドは CoInitializeEx 関数を呼び出すこのヘルパー メソッドを呼び出す。COINIT_DISABLE_OLE1DDE フラグを使い、Dynamic Data Exchange (DDE) を無効にする。詳細については、Platform SDK を参照すること。

CAMThread::GetRequest

CAMThread クラス

次のリクエストを待つ。

構文

DWORD GetRequest(void);

戻り値

派生クラスが定義した値を返す。

注意

このメソッドは他のスレッドが CallWorker メソッドを呼び出すまでブロックする。次に CallWorker に渡したパラメータを返す。 Reply メソッドを呼び出してリクエストしているスレッドを解放する。

CAMThread::GetRequestHandle

CAMThread クラス

CallWorker メソッドで通知済のイベントのハンドルを取得する。

構文

HANDLE GetRequestHandle(void) const;

戻り値

イベント ハンドルを返す。

注意

The CAMEvent クラスは、非公開の手動リセット イベントを維持する。このイベントは CallWorker によって設定され、Reply メソッドによってリセットされる。

WaitForMultipleObjects のような関数を呼び出す場合、GetRequestHandle を使ってイベントハンドルを取得する。

CAMThread::GetRequestParam

CAMThread クラス

最新のリクエストを取得する。

構文

DWORD GetRequestParam(void) const;

戻り値

最も最近に CallWorker メソッドに送られたパラメータ値を返す。

CAMThread::InitialThreadProc

CAMThread クラス

スレッドが作成されたとき、ThreadProc メソッドを呼び出す。

構文

DWORD InitialThreadProc(
    LPVOID pv
);

パラメータ

pv
this ポインタ。

戻り値

CAMThread::ThreadProc が返した DWORD を返す。この値は派生クラスが定義したものである。

注意

The Create メソッドはスレッドを作成する際、このメソッドをスレッド プロシージャに使用する。スレッド引数として this ポインタを使用する。

このメソッドは CoInitializeHelper メソッドを呼び出し、次に ThreadProc を呼び出す。

CAMThread::Reply

CAMThread クラス

リクエストに応答する。

構文

void Reply(
    DWORD dw
);

パラメータ

dw
CallWorker メソッドの戻り値。

注意

CallWorker メソッドはこのメソッドが呼び出されるまでブロックする。dw パラメータは CallWorker の戻り値を与える。リクエストを取得した後にスレッド プロシージャでこのメソッドを呼び出して、リクエストしているスレッドを解放する。

CAMThread::ThreadExists

CAMThread クラス

スレッドがあるかどうか調べる。

構文

BOOL ThreadExists(void);

戻り値

スレッドがある場合 TRUE を返し、スレッドがない場合 FALSE を返す。

CAMThread::ThreadProc

CAMThread クラス

スレッド プロシージャ。

構文

virtual DWORD ThreadProc(void) = 0;

戻り値

Returns a DWORD 値を返す、その意味は派生クラスによって定義される。

注意

これは純粋な仮想メソッドである。このメソッドを仮想クラスで実行して、スレッド プロシージャに与える。 Create メソッドがスレッドを作成するとき、順に ThreadProc メソッドを呼び出す InitialThreadProc メソッドのアドレスを与える。

通常 ThreadProc メソッドは(GetRequest や CheckRequest メソッドを呼び出すことで)リクエストを取得するループとなり、データを処理する。

このメソッドが戻るとき、スレッドは終了する。


CAutoLock クラス

ブロックの範囲のクリティカル セクションを保持する。

宣言 : Wxutil.h

このクラスは、クリティカル セクション オブジェクトのラッパーである CCritSec クラスとの組み合わせて使用する。CAutoLock のコンストラクタはクリティカル セクションをロックし、デストラクタはロックを解除する。CAutoLock オブジェクトをローカル変数として使用して、すべてのコード パスがクリティカル セクションをロック解除することを保証しながら、クリティカル セクションをロックすることができる。

次のサンプル コードは、このクラスの使用方法を示す。

CCritSec csMyLock;  // クリティカル セクションはまだロックされていない。

{
CAutoLock cObjectLock(&csMyLock);  // クリティカル セクションをロックする。

// コードの保護されたセクション。

} // ロックはここで解除される。

このクラスのメソッドは、オーバーライドされるように設計されていない。

プロテクト メンバ変数
m_pLock | このロックのクリティカル セクション。
Public メソッド
CAutoLock | コンストラクタ メソッド。指定されたクリティカル セクション オブジェクトをロックする。
~CAutoLock | デストラクタ メソッド。クリティカル セクション オブジェクトのロックを解除する。

CAutoLock.m_pLock

CAutoLock クラス

このロックのクリティカル セクション

構文

CCritSec *m_pLock;

CAutoLock::CAutoLock

CAutoLock クラス

コンストラクタ メソッド。指定されたクリティカル セクション オブジェクトをロックする。

構文

CAutoLock(
CCritSec *plock
);

パラメータ

plock
クリティカル セクション オブジェクトを含む CCritSec オブジェクトへのポインタ。

CAutoLock::~CAutoLock

CAutoLock クラス

デストラクタ メソッド。クリティカル セクション オブジェクトのロックを解除する。

構文

CAutoLock(void);


CAutoUsingOutputPin クラス

CDynamicOutputPin オブジェクトへのアクセスの取得と解放。

宣言 : Amfilter.h

あるメソッドが CDynamicOutputPin で呼び出されるとき、呼び出し元はピンへのアクセスを取得し、次にそのアクセスを解放しなければならない。アクセスを取得するには呼び出し元は CDynamicOutputPin::StartUsingOutputPin メソッドを使用する。アクセスを解放するには CDynamicOutputPin::StopUsingOutputPin メソッドを呼び出す。CAutoUsingOutputPin クラスはコンストラクタとデコンストラクタ メソッドでそのタスクをハンドルするヘルパー クラスである。次のコード例はこのクラスの使い方を示す。

CDynamicOutputPin *pPin;
HRESULT hr = S_OK;  // 重要！S_OK で初期化する。

// ピンのポインタを取得する (示されていない)。

{
    CAutoUsingOutputPin UsingPin(pPin, &hr)
    if (SUCCEEDED(hr)) {
        // ピンを使用できる。
        pPin->Deliver(pSample);
    }
} // オブジェクトへのアクセスはここで解除する。

// ピンは使用できない。

Public メソッド
CAutoUsingOutputPin | コンストラクタ メソッド。指定したピンへのアクセスを取得。
~CAutoUsingOutputPin | デストラクタ メソッド。そのピンへのアクセスを解放。

CAutoUsingOutputPin

CAutoUsingOutputPin Class

コンストラクタ メソッド。指定したピンへのアクセスを取得。

構文

CAutoUsingOutputPin(
    CDynamicOutputPin *pOutputPin,
    HRESULT *phr
);

パラメータ

pOutputPin
CDynamicOutputPin オブジェクトへのポインタ
phr
HRESULT 値を含む変数へのポインタ。その値は S_OK でなければならない。

注意

メソッドが返ったとき、*phr の値はそのメソッドが成功したか失敗したかを示す。

CAutoLock::~CAutoUsingOutputPin

CAutoUsingOutputPin クラス

デストラクタ メソッド。そのピンへのアクセスを解放。

構文

~CAutoUsingOutputPin(void);


CBaseAllocator クラス

アロケータを実装する抽象基底クラス。アロケータは IMemAllocator インターフェイスを公開する。

宣言 : Amfilter.h

allocator はメモリ バッファを割り当てるオブジェクトである。アロケータは有効なバッファのリストを保持する。クライアント(一般的にはフィルタ)がバッファを要求すると、アロケータはそのリストから 1 つを取得する。そのクライアントはバッファをデータで埋め、そのバッファを他のオブジェクトに渡す場合もある。最終的にそのバッファは解放され、アロケータはフリーなバッファのリストにそれを戻す。

各バッファは media sample を呼び出すオブジェクトによってカプセル化される。メディア サンプルは Component Object Model (COM) フレームワークを使ってポインタをメモリ ブロックにパッケージする 1 つの方法である。メディア サンプルは IMediaSample インターフェイスを公開し、CMediaSample クラスを使って実装される。メディア サンプルは結合されたバッファのポインタを含む、それはIMediaSample::GetPointer を呼び出すことにより結合されている。

通常、アロケータは連続的なメモリ ブロックをアロケートする。次にブロック内のアドレスのポインタを含むメディアサンプルを作成する。次の図はアロケータとメディア サンプルとメモリ ブロックの関係を示す。

アロケータを使うには、次のステップを実行する。

  1. SetProperties メソッドを呼び出して、バッファ要求を指定する、これはバッファの数と各バッファのサイズを含む。
  2. Commit メソッドを呼び出して、バッファを割り当てる。
  3. GetBuffer メソッドを呼び出してメディア サンプルを取得。このメソッドは次のサンプルが有効になるまでブロックする。
  4. 各サンプルが終了したら、サンプルに IUnknown::Release メソッドを呼び出す。サンプルはその参照カウントがゼロになっても削除されない。代わりにサンプルはアロケータのフリー リストを返す。
  5. アロケータの使用が終わったら、Decommit メソッドを呼び出して、バッファのメモリを解放する。

Commit メソッドはバッファのメモリを割り当てる仮想メソッド Alloc を呼び出す。Decommit メソッドはメモリを解放する純粋な仮想メソッド Free を呼び出す。派生クラスはこの 2 つのメソッドをオーバーライドしなければならない。

CMemAllocator 基底クラスは CBaseAllocator から派生する。フィルタ基底クラスは CMemAllocator クラスを使用する。

Protected メンバ変数
m_lFree | 有効な(フリーの)メディアサンプルのリストのポインタ。
m_hSem | サンプルが有効なときの通知済のセマフォ。
m_lWaiting | サンプルを待つスレッドの数。
m_lCount | 提供するバッファの数。
m_lAllocated | 現在割り当てられているバッファの数。
m_lSize | 各バッファのサイズ。
m_lAlignment | 各バッファのアラインメント。
m_lPrefix | 各バッファの接頭値(prefix)
m_bChanged | バッファ要求が変更されたかどうかを示すフラグ。
m_bCommitted | アロケータにコミットされたかどうかを示すフラグ。
m_bDecommitInProgress | コミットされていない操作が進行中かどうかを示すフラグ。
m_pNotify | サンプルが解放されたときに呼び出されるコールバック インターフェイスのポインタ。
m_fEnableReleaseCallback | 解放コールバックが有効かどうかを示すフラグ。
Protected メソッド
Alloc | バッファのメモリを割り当てる。 仮想。
Public メソッド
CBaseAllocator | コンストラクタ メソッド。
~CBaseAllocator | デストラクタ メソッド。
SetNotify | サンプルが解放されるたびに呼び出されるコールバック メソッドを指定する。
GetFreeCount | 使われていないメディア サンプルの数を取得。
NotifySample | サンプルを待つスレッドを解放。
SetWaiting | 待ち状態のスレッドの数をインクリメント。
Pure Virtual メソッド
Free | 最後のメディア サンプルが解放された後、デコミット操作の間にバッファ メモリを解放する。
IMemAllocator メソッド
SetProperties | 割り当てるバッファの数と各バッファのサイズを指定する。
GetProperties | アロケータが作成するバッファの数とそのバッファのプロパティを取得。
Commit | バッファにメモリを割り当てる。
Decommit | バッファをデコミットとする。
GetBuffer | バッファを含むメディア サンプルを取得。
ReleaseBuffer | フリー メディア サンプルのリストにメディア サンプルを返す。

CBaseAllocator.m_lFree

CBaseAllocator クラス

有効な(フリーな)メディア サンプル リストのポインタ。

構文

CSampleList m_lFree;

CBaseAllocator.m_hSem

CBaseAllocator クラス

サンプルが有効なときの通知済のセマフォ。

構文

HANDLE m_hSem;

CBaseAllocator.m_lWaiting

CBaseAllocator クラス

サンプルを待つスレッドの数。

構文

long m_lWaiting

CBaseAllocator.m_lCount

CBaseAllocator クラス

提供するバッファの数。SetProperties メソッドはこの値を設定する。バッファは Commit メソッドが呼び出されるまで割り当てられない。現在割り当てられているバッファの数は m_lAllocated 数値によって指定される。

構文

long m_lCount;

CBaseAllocator.m_lAllocated

CBaseAllocator クラス

現在割り当てられているバッファの数。

構文

long m_lAllocated;

CBaseAllocator.m_lSize

CBaseAllocator クラス

各バッファのサイズ。

構文

long m_lSize;

CBaseAllocator.m_lAlignment

CBaseAllocator クラス

各バッファのアラインメント。各バッファのアドレスは複数のこの値でなければならない。接頭値(prefix)はそのアラインメントの中で計算されなければならない。詳細については、「m_lPrefix」を参照すること。

構文

long m_lAlignment;

CBaseAllocator.m_lPrefix

CBaseAllocator クラス

バイト単位で示した各バッファの接頭値 (prefix)。この値がゼロでないとき、GetBuffer メソッドによって返る各バッファのポインタはサイズ m_lPrefix の複数バイトのブロックで頭に置かれる。m_lSize メンバ変数には、接頭値は含まれない。

構文

long m_lPrefix;

CBaseAllocator.m_bChanged

CBaseAllocator クラス

バッファ要求が変更されたかどうかを示すフラグ。SetProperties メソッドはその値を TRUE に設定する。派生クラスでは、純粋な仮想メソッド Alloc はその値を FALSE に戻す。バッファがいったん割り当てられると、m_bChanged が FALSE の間それれを再割り当てする必要はない。

構文

BOOL m_bChanged;

CBaseAllocator.m_bCommitted

CBaseAllocator クラス

アロケータがコミットされているかどうかを示すフラグ。

構文

BOOL m_bCommitted;

CBaseAllocator.m_bDecommitInProgress

CBaseAllocator クラス

デコミット操作が行われているかどうかを示すフラグ。Decommit メソッドが呼び出された後、すべてのバッファが解放される前に、この値は TRUE になる。この値が TRUE なら、GetBuffer メソッドは失敗する。また値が TRUE の間アロケータはそれ自身を削除するべきではない。

構文

BOOL m_bDecommitInProgress;

CBaseAllocator.m_pNotify

CBaseAllocator クラス

サンプルが解放されたとき呼び出されるコールバックのポインタ。

構文

IMemAllocatorNotifyCallbackTemp *m_pNotify;

CBaseAllocator.m_fEnableReleaseCallback

CBaseAllocator クラス

解放コールバックが有効かどうかを示すフラグ。このフラグはコンストラクタ メソッドでセットされる。この値が FALSE のとき、 SetNotify メソッドを呼び出すと、(デバッグ ビルドでは) assertion to fire となる。

構文

BOOL m_fEnableReleaseCallback;

CBaseAllocator::Alloc

CBaseAllocator クラス

バッファのメモリを割り当てる。

構文

virtual HRESULT Alloc(void);

戻り値

次の HRESULT 値の 1 つが返る

S_FALSE | バッファ要求は変更されていない。
S_OK | バッファ要求は変更された。
VFW_E_SIZENOTSET | バッファ要求はセットされていない。

注意

このメソッドは Commit メソッドによって呼び出される。

基底クラスでは、このメソッドはメモリを割り当てない。バッファ要求がセットされていなければエラーを返し、変更されていなければ S_FALSE を返し、要求が変更されていれば S_OK を返す。

派生クラスがこのメソッドをオーバーライドして実際のメモリ割り当てをするべきである。通常は派生クラスは次のようなステップで実行する。

  1. 基底クラスの実装を呼び出し、メモリを本当に割り当てる必要があるかどうかを決定する。
  2. メモリを割り当てる。
  3. Createステップ 2 からメモリのチャンクを含む CMediaSample オブジェクトを作成する。
  4. 各 CMediaSample オブジェクトをフリー サンプル リスト (m_lFree) に追加する。

この例については、「CMemAllocator::Alloc」を参照すること。

CBaseAllocator::CBaseAllocator

CBaseAllocator クラス

コンストラクタ メソッド。

構文

CBaseAllocator(
    TCHAR *pName,
    LPUNKNOWN pUnk,
    HRESULT *phr,
    BOOL bEvent = TRUE,
    BOOL fEnableReleaseCallback  = FALSE
);

パラメータ

pName
アロケータの名前を含む文字列のポインタ。
pUnk
このオブジェクトの所有者のポインタ。オブジェクトが集成されている場合、集成されたオブジェクトの IUnknown インターフェイスのポインタを渡す。それ以外の場合はこのパラメータには NULL を設定する。
phr
メソッドの成功や失敗を含む HRESULT 値を受け取る変数のポインタ。
bEvent
セマフォを作成したかどうかを示すブール値。TRUE なら、アロケータはサンプルが有効になるたびに通知済のセマフォ (m_hSem) を作成する。実装している派生クラスがセマフォを必要としないなら、この値を FALSE に設定する。
fEnableReleaseCallback
解放コールバック メカニズムが有効かどうかを示すブール値。バッファが解放されたときに呼び出されるコールバック インターフェイスを提供したければ、この値を TRUE に設定する。SetNotify メソッドの呼び出しによってコールバックを指定する。

CBaseAllocator::~CBaseAllocator

CBaseAllocator クラス

デストラクタ メソッド

構文

~CBaseAllocator(void);

構文

オブジェクトを消去する前に必ず Decommit メソッドを呼び出すこと。基底クラス デストラクタは Decommit を呼び出すことができない、なぜならそのメソッドは純粋仮想メソッド Free を呼び出すからだ。派生クラスはこのデストラクタをオーバーライドして Decommit を呼び出す。

CBaseAllocator::Commit

CBaseAllocator クラス

バッファにメモリを割り当てる。IMemAllocator::Commit メソッドを実装する。

構文

HRESULT Commit(void);

戻り値

HRESULT 値を返す。次の表は、可能な値を示している。

S_OK | 成功。
VFW_E_SIZENOTSET | バッファ要求は指定されていなかった。

注意

このメソッドを呼び出す前に、SetProperties を呼び出してバッファ要求を指定すること。

このメソッドは仮想メソッド Alloc を呼び出してバッファへのメモリの割り当てを行う。派生クラスは Alloc をオーバーライドすることができる。デコミット操作が行われていると、それはキャンセルされる。

このメソッドは GetBuffer メソッドの前に呼び出されなければならない。

CBaseAllocator::Decommit

CBaseAllocator クラス

バッファをデコミットにする。IMemAllocator::Decommit メソッドを実装する。

構文

HRESULT Decommit(void);

戻り値

S_OK を返す。

注意

このメソッドを呼び出した後で、GetBuffer メソッドを呼び出すと失敗する。サンプルは解放されて、フリー リストに戻る。最後のサンプルが返ると、割り当てたメモリを解放するため、アロケータは Free メソッドを呼び出す。(基底クラスの場合、Free は純粋な仮想メソッド)。

更に、このメソッドは GetBuffer でブロックされたスレッドを解放する。GetBuffer を呼び出すと失敗する。

CBaseAllocator::Free

CBaseAllocator クラス

最後のメディア サンプルが解放された後、デコミット操作中にバッファ メモリを解放する。

構文

virtual void Free(void) PURE;

注意

Decommit メソッドが呼び出された後で、最後のメディア サンプルが解放されたとき、アロケータはこのメソッドを呼び出す。派生クラスはこのメソッドを実装しなければならない。

CBaseAllocator::GetBuffer

CBaseAllocator クラス

バッファを含むメディア サンプルを取得する。IMemAllocator::GetBuffer メソッドを実装する。

構文

HRESULT GetBuffer(
    IMediaSample **ppBuffer,
    REFERENCE_TIME *pStartTime,
    REFERENCE_TIME *pEndTime,
    DWORD dwFlags
);

パラメータ

ppBuffer
バッファのIMediaSample インターフェイスのポインタを取得する変数のアドレス。
pStartTime
サンプルの開始タイムのポインタ。
pEndTime
サンプルの終了タイムのポインタ。
dwFlags
ゼロあるいは複数のフラグのビットの組み合わせ。基底クラスは次のフラグをサポートする。
  • AM_GBF_NOWAIT: バッファが有効になるのを待たない。

戻り値

次の HRESULT 値の 1 つを返す。

S_OK | 成功。
VFW_E_NOT_COMMITTED | アロケータはコミットではなかった。
VFW_E_TIMEOUT | タイム アウト。

注意

呼び出し元が dwFlags で AM_GBF_NOWAIT フラグを指定しなくても、このメソッドは次のサンプルが有効になるまでブロックする。

取得したメディア サンプルは割り当てられたバッファの有効なポインタを持つ。呼び出し元は、タイム スタンプやメディア タイムや同期ポイント プロパティのような、サンプルの他のプロパティを設定する責任を持つ。詳細については、「IMediaSample」を参照すること。

基底クラスでは、pStartTime と pEndTime パラメータは無視される。派生クラスはこれらの値を使うことができる。たとえば、ビデオ レンダラ フィルタのアロケータはこれらの値を使って、Microsoft® DirectDraw® サーフェイス間の切り替えの同期を行う。

メソッドがサンプルを待つ必要があるとき、待ちオブジェクト数 (m_lCount) をインクリメントし、セマフォ (m_hSem) の WaitForSingleObject 関数を呼び出す。サンプルが有効になったとき、アロケータの IBaseAllocator::ReleaseBuffer メソッドを呼び出し、m_lCount によってセマフォ カウントをインクリメント (したがって待ちスレッドを解放) し、 m_lCount をゼロに戻す。

CBaseAllocator::GetFreeCount

CBaseAllocator クラス

使われていないメディア サンプルの数を取得。

構文

HRESULT GetFreeCount(
    LONG *plBuffersFree
);

パラメータ

plBuffersFree
使われていないサンプルの数を受け取る変数のアドレス。

戻り値

S_OK を返す。

注意

この値はフリー リスト (m_lFree) のサンプルと、削除されなかったサンプルをも含む。

CBaseAllocator::GetProperties

CBaseAllocator クラス

アロケータが作成したバッファの数とバッファ プロパティを取得する。IMemAllocator::GetProperties メソッドを実装。

構文

HRESULT GetProperties(
    ALLOCATOR_PROPERTIES *pProps
);

パラメータ

pProps
アロケータ プロパティを受け取る ALLOCATOR_PROPERTIES 構造体のポインタ。

戻り値

S_OK を返す。

CBaseAllocator::NotifySample

CBaseAllocator クラス

サンプルを待っているスレッドを解放する。

構文

void NotifySample(void);

注意

サンプルを待っているスレッドがあるとき、m_lWaiting の値はゼロより大きい。m_lWaiting の値がゼロより大きければ、このメソッドは m_hSem セマフォの ReleaseSemaphore 関数を呼び出し、待っているスレッドをアクティブにする。そしてまた m_lWaiting をゼロにリセットする。

このメソッドは、サンプルがフリー リストに戻ったとき ReleaseBuffer メソッドから呼び出される。またアロケータがデコミットのとき Decommit メソッドから呼び出される。

CBaseAllocator::ReleaseBuffer

CBaseAllocator クラス

メディア サンプルをフリー メディア サンプルのリストに戻す。IMemAllocator::ReleaseBuffer を実装する。

構文

HRESULT ReleaseBuffer(
    IMediaSample *pSample
);

パラメータ

pSample
メディア サンプル オブジェクトの IMediaSample インターフェイスのポインタ。

戻り値

S_OK を返す。

注意

メディア サンプルの参照カウントがゼロになるとき、サンプルは ReleaseBuffer を自分自身のパラメータとして呼び出す。このメソッドは次の動作をする。

  • メディア サンプルをフリー リスト (m_lFree) に戻す。
  • NotifySample メソッドを呼び出して、 GetBuffer メソッドの呼び出しでブロックされたスレッドを解放する。
  • SetNotify メソッドが以前に呼び出されていたなら、IMemAllocatorNotifyCallbackTemp::NotifyReleaseメソッドを呼び出す。
  • 最後のサンプルが解放されるとき、動作中の Decommit 呼び出しがあるなら、Free メソッドを呼び出して、バッファ メモリを解放する。基底クラスでは、Free は純粋な仮想メソッドである。

CBaseAllocator::SetNotify

CBaseAllocator クラス

サンプルが解放されるたびに呼び出されるコールバック メソッドを指定する。

構文

HRESULT SetNotify(
    IMemAllocatorNotifyCallbackTemp *pNotify
);

パラメータ

pNotify
呼び出し元に実装された IMemAllocatorNotifyCallbackTemp インターフェイスのポインタ。

戻り値

S_OK を返す。

注意

このメソッドは m_pNotify メンバ変数を pNotify と同じ値にセットし、インターフェイスの参照カウントをインクリメントする。m_pNotify が NULL 以外なら、ReleaseBuffer メソッドは IMemAllocatorNotifyCallbackTemp::NotifyRelease を呼び出す。この呼び出しは任意のコンテキストで使われるので、NotifyRelease メソッドを実装するときは、呼び出しがブロックしないように注意する必要がある。たとえば、あるイベントの設定用にメソッドを制限するとか、他のスレッドへのメッセージの発送に制限する。

CBaseAllocator::SetProperties

CBaseAllocator クラス

割り当てられたバッファの数と各バッファのサイズを指定。IMemAllocator::SetProperties メソッドを実装。

構文

HRESULT SetProperties(
    ALLOCATOR_PROPERTIES *pRequest,
    ALLOCATOR_PROPERTIES *pActual
);

パラメータ

pRequest
バッファ要求を含む ALLOCATOR_PROPERTIES 構造体のポインタ。
pActual
実際のバッファ プロパティを受け取る ALLOCATOR_PROPERTIES 構造体のポインタ。

戻り値

以下のHRESULT の 1 つを返す。

S_OK | 成功。
E_POINTER | NULL ポインタ値。
VFW_E_ALREADY_COMMITTED | フィルタがアクティブな間は、割り当てたメモリは変更できない。
VFW_E_BADALIGN | 不適切なアラインメントが指定された。
VFW_E_BUFFERS_OUTSTANDING | 1 つあるいはそれ以上のバッファがまだアクティブ。

注意

このメソッドはバッファ要求を指定するが、バッファを割り当てるわけではない。Commit メソッドを呼び出してバッファを割り当てる。

呼び出し元は 2 つの ALLOCATOR_PROPERTIES 構造体を割り当てる。pRequest パラメータは呼び出し元のバッファの数と各バッファのサイズを含むバッファ要求を持つ。このメソッドが返ると、pActual パラメータはアロケータにセットされた実際のバッファ プロパティを持つ。このメソッドは成功すると仮定されている基底クラスでは、実際のプロパティは必ず要求されたプロパティと一致する。派生クラスではこれをオーバーライドする場合もある。

アロケータはコミットであってはならないし、特殊なバッファであってもいけない。基底クラスの場合、アラインメントは1でなければならない。CMemAllocator クラスはこの要求をオーバーライドする。

CBaseAllocator::SetWaiting

CBaseAllocator クラス

待ちスレッドの数をインクリメントする。

構文

void SetWaiting(void);

注意

このメソッドは m_lWaiting メンバ変数をインクリメントする。スレッドが CBaseAllocator::GetBuffer メソッドでブロックされていると、アロケータは SetWaiting を呼び出し、次に m_hSem セマフォが通知されるのを待つ。ReleaseBuffer メソッドはセマフォに通知し、m_lWaiting をゼロに戻す。


CBaseBasicVideo クラス

CBaseBasicVideo クラスは、IBasicVideo インターフェイスの IDispatch コンポーネントを処理し、プロパティおよびメソッドは純粋仮想のままにしておく。

IDispatch::GetIDsOfNames、IDispatch::GetTypeInfo、IDispatch::GetTypeInfoCount、および IDispatch::Invoke メソッドは、IDispatch インターフェイスの標準的な実装で、CBaseDispatch クラス (およびタイプ ライブラリ) を使用してコマンドを解析し、IBasicVideo インターフェイスの純粋仮想メソッドに渡す。

メンバ関数

CBaseBasicVideo CBaseBasicVideo オブジェクトを作成する。

実装される INonDelegatingUnknown メソッド

NonDelegatingQueryInterface 指定された参照カウントのインターフェイスを返す。

実装される IDispatch メソッド

GetIDsOfNames | 単一のメンバおよびオプションのパラメータのセットを、対応する整数のディスパッチ識別子にマップする。この識別子は、以降の IDispatch::Invoke メソッドの呼び出しで使用できる。
GetTypeInfo | タイプ情報オブジェクトを取得する。インターフェイスのタイプ情報を取得できる。
GetTypeInfoCount | オブジェクトによって提供されるタイプ情報インターフェイスの数を取得する。
Invoke | オブジェクトによって公開されるプロパティおよびメソッドへのアクセスを提供する。

CBaseBasicVideo::CBaseBasicVideo

CBaseBasicVideo クラス

CBaseBasicVideo オブジェクトを作成する。

構文

CBaseBasicVideo(

  const TCHAR *pName,

  LPUNKNOWN pUnk

  );

パラメータ

pName
デバッグのために使用されるオブジェクトの名前へのポインタ。
pUnk
このオブジェクトの所有者へのポインタ。

戻り値

戻り値なし。

注意

スタティック メモリに pName パラメータを割り当てる。この名前は、オブジェクトの作成および削除を行うデバッギング端末上に現れる。

CBaseBasicVideo::GetIDsOfNames

CBaseBasicVideo クラス

単一のメンバ関数およびオプションのパラメータのセットを、対応する整数のディスパッチ識別子にマップする。この識別子は、以降の CBaseBasicVideo::Invoke メンバ関数の呼び出しで使用できる。

構文

HRESULT GetIDsOfNames(

  REFIID riid,

  OLECHAR **rgszNames,

  UINT cNames,

  LCID lcid,

  DISPID *rgdispid

  );

パラメータ

riid
参照識別子。将来的な使用のために予約されている。NULL でなければならない。
rgszNames
渡されたマップする名前の配列へのポインタのアドレス。
cNames
マップされる名前の数。
lcid
名前を解釈するロケール コンテキスト。
rgdispid
呼び出し元割り当て済み配列へのポインタ。各要素には、rgszNames 配列に渡される名前の 1 つに対応する ID が含まれる。最初の要素はメンバの名前を表し、以降の要素は各メンバのパラメータを表す。

戻り値

次のいずれかの値を返す。
S_OK | 成功。
E_OUTOFMEMORY | メモリ不足。
DISP_E_UNKNOWNNAME | 1 つ以上の名前が不明だった。返された DISPID には、不明な名前に対応する各エントリの DISPID_UNKNOWN が含まれる。
DISP_E_UNKNOWN_CLSID | CLSID が認識されなかった。

CBaseBasicVideo::GetTypeInfo

CBaseBasicVideo クラス

タイプ情報オブジェクトを取得する。インターフェイスのタイプ情報を取得できる。

構文

HRESULT GetTypeInfo(

  UINT itinfo,

  LCID lcid,

  ITypeInfo **pptinfo

  );

パラメータ

itinfo
返されるタイプ情報。ゼロを渡して、IDispatch 実装のタイプ情報を取得する。
lcid
タイプ情報のロケール ID。ローカライズされたメンバ名をサポートするクラスの場合、オブジェクトは異なる言語の異なるタイプ情報を返すことができる場合がある。ローカライズされたメンバ名をサポートしないクラスの場合、このパラメータは無視することができる。
pptinfo
要求されたタイプ情報オブジェクトへのポインタのアドレス。

戻り値

pptinfo が無効な場合は、E_POINTER を返す。itinfo がゼロ以外の場合は、TYPE_E_ELEMENTNOTFOUND を返す。成功した場合は、S_OK を返す。それ以外の場合は、タイプを取得するための呼び出しの 1 つから HRESULT を返す。HRESULT はエラーを示し、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。

CBaseBasicVideo::GetTypeInfoCount

CBaseBasicVideo クラス

オブジェクトによって提供されるタイプ情報インターフェイスの数を取得する。

構文

HRESULT GetTypeInfoCount(

  UINT *pctinfo

  );

パラメータ

pctinfo
オブジェクトが提供するタイプ情報インターフェイスの数を受け取る場所へのポインタ。オブジェクトがタイプ情報を提供した場合、この数は 1 である。それ以外の場合は、0 である。

戻り値

pctinfo が無効な場合は、E_POINTER を返す。それ以外の場合は、S_OK を返す。

CBaseBasicVideo::Invoke

CBaseBasicVideo クラス

オブジェクトによって公開されるプロパティおよびメソッドへのアクセスを提供する。

構文

HRESULT Invoke(

  DISPID dispidMember,

  REFIID riid,

  LCID lcid,

  WORD wFlags,

  DISPPARAMS *pdispparams,

  VARIANT *pvarResult,

  EXCEPINFO *pexcepinfo,

  UINT *puArgErr

  );

パラメータ

dispidMember
メンバの識別子。ディスパッチ識別子を取得するには、CBaseBasicVideo::GetIDsOfNames またはオブジェクトのドキュメントを使用する。
riid
将来的な使用のために予約されている。IID_NULL でなければならない。
lcid
引数を解釈するロケール コンテキスト。
wFlags
CBaseBasicVideo::Invoke 呼び出しのコンテキストを記述するフラグ。
pdispparams
引数の配列、名前付き引数の引数ディスパッチ ID の配列、および配列内の要素の数を含む構造体へのポインタ。
pvarResult
結果が格納されるポインタ、または呼び出し元が結果を求めていない場合は NULL。
pexcepinfo
例外情報を含む構造体へのポインタ。
puArgErr
rgvarg 配列内で、エラーがある最初の引数のインデックスへのポインタ。

戻り値

riid が IID_NULL 以外の場合は、DISP_E_UNKNOWNINTERFACE を返す。呼び出しが失敗した場合は、CBaseBasicVideo::GetTypeInfo からエラー コードの 1 つを返す。それ以外の場合は、IDispatch::Invoke への呼び出しから HRESULT を返す。

CBaseBasicVideo::NonDelegatingQueryInterface

CBaseBasicVideo クラス

指定された参照カウントのインターフェイスを返す。

構文

HRESULT NonDelegatingQueryInterface(
  REFIID riid,
  void **ppv
  );

パラメータ

riid
参照識別子。
ppv
インターフェイスへのポインタのアドレス。

戻り値

ppv が無効な場合は、E_POINTER を返す。クエリが成功した場合は NOERROR、失敗した場合は E_NOINTERFACE を返す。

注意

デフォルトでは、IBasicVideo および IUnknown インターフェイスへのポインタを返す。このメソッドをオーバーライドして、派生クラスで実装された追加のインターフェイスを公開する。


CBaseControlVideo クラス

CBaseControlVideo クラスは、IBasicVideo デュアル インターフェイスを実装し、汎用ビデオ ウィンドウのビデオのプロパティを制御する。一般的に、CBaseControlVideo オブジェクトは、ディスプレイ上のウィンドウにビデオを描画するビデオ レンダラである。

CBaseControlVideo クラスはプロパティとメソッドの両方をサポートする。プロパティは、多くのオートメーション コントローラ (Microsoft® Visual Basic® プログラミング環境など) からの方が容易にアクセスできる。ただし、処理によっては、アプリケーションで複数のプロパティを同時に変更できる機能が必要になる。このため、複数の関連するプロパティを変更できるメソッドが提供されている。

CBaseControlVideo の多くのメンバ関数では、ビデオ レンダラがフィルタ グラフに接続されている必要がある。接続されていない場合、メンバ関数は VFW_E_NOT_CONNECTED を返す。接続と切断を繰り返しても、ビデオ レンダラに設定されたプロパティは変化しない。すべてのアプリケーションで、プレゼンテーションを開始する前にレンダラのプロパティをリセットしたことを確認する必要がある。

ビデオを処理する場合、アプリケーションは使用するビデオの部分を選択できる。この部分は、CBaseControlVideo オブジェクトが制御する転送元矩形である。CBaseControlVideo は、アプリケーションが転送元矩形を設定および取得できるようにする。CBaseControlVideo が使用するすべての矩形では、Microsoft Win32® プログラミングで使用される上、左、右、下ではなく、上、左、幅、高さが使用される。転送元矩形が設定されていない場合、転送元矩形のプロパティはフル サイズのネイティブ ビデオのサイズを返す。

プロテクト データ メンバ

m_pFilter | 所有するメディア フィルタへのポインタ。
m_pInterfaceLock | 外部的に定義されるクリティカル セクション。
m_pPin | 接続のメディア タイプの制御。

メンバ関数

CBaseControlVideo | CBaseControlVideo オブジェクトを作成する。
CopyImage | ビデオ イメージのメモリ コピーを作成する。
GetImageSize | ビデオ イメージのサイズ情報を取得する。
SetControlVideoPin | このオブジェクトが同期しなければならないピンを設定する。

オーバーライド可能なメンバ関数

CheckSourceRect | 転送元矩形が有効であるかどうかを判断する。
CheckTargetRect | 転送先矩形が有効であるかどうかを判断する。
GetSourceRect | 現在のビデオの転送元矩形を取得する (純粋仮想)。
GetStaticImage | メモリ バッファ内の現在のイメージを返す (純粋仮想)。
GetTargetRect | 現在のビデオの転送先矩形を取得する (純粋仮想)。
GetVideoFormat | ビデオ フォーマットを含む VIDEOINFOHEADER 構造体を取得する。
IsDefaultSourceRect | レンダラがデフォルトの転送元矩形を使用しているかどうかを判断する (純粋仮想)。
IsDefaultTargetRect | レンダラがデフォルトの転送先矩形を使用しているかどうかを判断する (純粋仮想)。
OnUpdateRectangles | 転送元または転送先矩形が変更されると呼び出される。
OnVideoSizeChange | EC_VIDEO_SIZE_CHANGED をアプリケーションに渡す。
SetDefaultSourceRect | デフォルトのビデオの転送元矩形を設定する (純粋仮想)。
SetDefaultTargetRect | デフォルトのビデオの転送先矩形を設定する (純粋仮想)。
SetSourceRect | 現在のビデオの転送元矩形を設定する (純粋仮想)。
SetTargetRect | 現在の転送先矩形を設定する (純粋仮想)。

実装される IBasicVideo メソッド

get_AvgTimePerFrame | フレームごとのおよその平均時間を取得する。
get_BitErrorRate | およそのビット エラー レートを取得する。
get_BitRate | ビデオのおよそのビット レートを取得する。
GetCurrentImage | 現在のイメージのメモリ レンダリングを取得する。
get_DestinationHeight | 現在の転送先矩形の高さを取得する。
get_DestinationLeft | 現在の転送先矩形の左の座標を取得する。
GetDestinationPosition | 現在の転送先の位置を取得する。
get_DestinationTop | 現在の転送先矩形の上の座標を取得する。
get_DestinationWidth | 現在の転送先矩形の幅を取得する。
get_SourceHeight | 現在の転送元矩形の高さを取得する。
get_SourceLeft | 現在の転送元矩形の左の座標を取得する。
GetSourcePosition | 現在の転送元の位置を取得する。
get_SourceTop | 現在の転送元矩形の上の座標を取得する。
get_SourceWidth | 現在の転送元矩形の幅を取得する。
get_VideoHeight | ネイティブ ビデオの高さを取得する。
GetVideoPaletteEntries | ビデオのパレット エントリの範囲を取得する。
GetVideoSize | ネイティブ ビデオの幅と高さを取得する。
get_VideoWidth | ネイティブ ビデオの幅を取得する。
IsUsingDefaultDestination | レンダラがデフォルトの転送先ウィンドウを使用しているかどうかを判断する。
IsUsingDefaultSource | レンダラがデフォルトの転送元ウィンドウを使用しているかどうかを判断する。
put_DestinationHeight | 転送先矩形の高さを設定する。
put_DestinationLeft | 転送先矩形の左の座標を設定する。
put_DestinationTop | 転送先矩形の上の座標を設定する。
put_DestinationWidth | 転送先矩形の幅を設定する。
put_SourceHeight | 転送元矩形の高さを設定する。
put_SourceLeft | 転送元矩形の左の座標を設定する。
put_SourceTop | 転送元矩形の上の座標を設定する。
put_SourceWidth | 転送元矩形の幅を設定する。
SetDefaultDestinationPosition | デフォルトの転送先の位置を再度設定する。
SetDefaultSourcePosition | デフォルトの転送元の位置を再度設定する。
SetDestinationPosition | 転送先矩形の位置を設定する。
SetSourcePosition | 転送元矩形の位置を設定する。

CBaseControlVideo::CBaseControlVideo

CBaseControlVideo クラス

CBaseControlVideo オブジェクトを作成する。

構文

CBaseControlVideo(
CBaseFilter *pFilter,
CCritSec *pInterfaceLock,
TCHAR *pName,
LPUNKNOWN pUnk,
HRESULT *phr
    );

パラメータ

pFilter
所有するメディア フィルタ オブジェクトへのポインタ。
pInterfaceLock
ロックのために使用するクリティカル セクションへのポインタ。
pName
オブジェクト記述へのポインタ。
pUnk
オブジェクトが集成の一部ではない場合は、制御する IUnknown インターフェイスへのポインタ。それ以外の場合は、NULL でなければならない。
phr
コンストラクタ メソッドの成功または失敗を示す HRESULT 値を受け取る変数へのポインタ。

戻り値

戻り値なし。

注意

このオブジェクトは、IBasicVideo コントロール インターフェイスを実装する。

このクラスで実装する IBasicVideo のすべてのインターフェイス メソッドでは、フィルタが正しく接続されている必要がある。このため、このクラスには同期しなければならないピンが渡される。インターフェイス メソッドが呼び出されると、オブジェクトは必ずピンが接続されていることを確認する。

CBaseControlVideo::CheckSourceRect

CBaseControlVideo クラス

転送元矩形が有効であるかどうかを判断する。

構文

virtual HRESULT CheckSourceRect(
RECT *pSourceRect
    );

パラメータ

pSourceRect
チェックする転送元矩形へのポインタ。

戻り値

有効ではない場合は E_INVALIDARG を返す。それ以外の場合は NOERROR (S_OK) を返す。

注意

このメンバ関数は、要求された転送元矩形が、使用可能な転送元ビデオよりも大きくないかチェックする。左および上の座標を負の値にすることはできない。また、幅および高さがビデオの右および下を超えることはできない。

CBaseControlVideo::CheckTargetRect

CBaseControlVideo クラス

転送先矩形が有効であるかどうかを判断する。

構文

virtual HRESULT CheckTargetRect(
RECT *pTargetRect
    );

パラメータ

pTargetRect
チェックする転送先矩形へのポインタ。

戻り値

有効ではない場合は E_INVALIDARG を返す。それ以外の場合は NOERROR (S_OK) を返す。

注意

このメンバ関数は、要求された転送先矩形が有効であるかどうかを判断する。転送先矩形は、ウィンドウの論理クライアントで位置を指定するので、最終的な幅および高さを 0 および負の値にすることはできないが、座標は負の値になる場合がある。

CBaseControlVideo::CopyImage

CBaseControlVideo クラス

イメージのメモリ コピーを作成する。

構文

HRESULT CopyImage(
IMediaSample *pMediaSample,
VIDEOINFOHEADER *pVideoInfo,
LONG *pBufferSize,
BYTE *pVideoImage,
RECT *pSourceRect
    );

パラメータ

pMediaSample
ビデオ イメージを含むサンプルへのポインタ。
pVideoInfo
ビデオ イメージを表すフォーマットへのポインタ。
pBufferSize
出力バッファのサイズへのポインタ。
pVideoImage
出力バッファへのポインタ。
pSourceRect
ビデオの転送元矩形へのポインタ。

戻り値

pVideoImage パラメータが NULL の場合、pBufferSize パラメータには、イメージを保存するために出力バッファが必要とするバイト数が格納される。渡されたバッファが小さすぎる場合や、このメンバ関数が十分なメモリを割り当てることができない場合、このメンバ関数は E_OUTOFMEMORY を返す。

注意

このメンバ関数はサンプルからイメージを取得し、出力バッファにコピーする。出力バッファにコピーされたビデオのセクションは、IBasicVideo インターフェイスで設定された転送元矩形を反映する (ただし、転送先矩形は反映しない)。

CBaseControlVideo::get_AvgTimePerFrame

CBaseControlVideo クラス

フレームごとの平均時間を取得する。

構文

HRESULT get_AvgTimePerFrame(
REFTIME *pAvgTimePerFrame
    );

パラメータ

pAvgTimePerFrame
フレームごとの平均時間へのポインタ。

戻り値

成功した場合は NOERROR を返す。十分なメモリがない場合は E_OUTOFMEMORY を返す。

注意

このメンバ関数は、IBasicVideo::get_AvgTimePerFrame メソッドを実装する。このメンバ関数は、純粋仮想メンバ関数 CBaseControlVideo::GetVideoFormat を呼び出して、派生クラスから VIDEOINFOHEADER 構造体を取得する。

CBaseControlVideo::get_BitErrorRate

CBaseControlVideo クラス

ビデオのおよそのビット エラー レートを取得する。

構文

HRESULT get_BitErrorRate(
long *pBitErrorRate
    );

パラメータ

pBitErrorRate
ビット エラー レート (およそこの数のビットについて 1 つのエラー) へのポインタ。

戻り値

成功した場合は NOERROR を返す。十分なメモリがない場合は E_OUTOFMEMORY を返す。

注意

このメンバ関数は、IBasicVideo::get_BitErrorRate メソッドを実装する。このメンバ関数は、純粋仮想メンバ関数 CBaseControlVideo::GetVideoFormat を呼び出して、派生クラスから VIDEOINFOHEADER 構造体を取得する。

CBaseControlVideo::get_BitRate

CBaseControlVideo クラス

ビデオのおよそのビット レートを取得する。

構文

HRESULT get_BitRate(
long *pBitRate
    );

パラメータ

pBitRate
ビット レート (ビット/秒) へのポインタ。

戻り値

成功した場合は NOERROR を返す。十分なメモリがない場合は E_OUTOFMEMORY を返す。

注意

このメンバ関数は、IBasicVideo::get_BitRate メソッドを実装する。このメンバ関数は、純粋仮想メンバ関数 CBaseControlVideo::GetVideoFormat を呼び出して、派生クラスから VIDEOINFOHEADER 構造体を取得する。

CBaseControlVideo::GetCurrentImage

CBaseControlVideo クラス

レンダラの現在のイメージのコピーを取得する。

構文

HRESULT GetCurrentImage(
long *pBufferSize,
long *pVideoImage
    );

パラメータ

pBufferSize
出力バッファのサイズへのポインタ。
pVideoImage
イメージの出力バッファへのポインタ。

戻り値

実装に応じた HRESULT 値を返す。この値は、次の値の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_INVALIDARG | 無効な引数。
E_OUTOFMEMORY | メモリ不足。pVideoInfo パラメータが NULL の場合に返される。
NOERROR | 成功。
VFW_E_NOT_PAUSED | フィルタが停止されていないため、処理を実行できなかった。

注意

このメンバ関数はサンプルからイメージを取得し、出力バッファにコピーする。出力バッファにコピーされたビデオのセクションは、IBasicVideo インターフェイスで設定された転送元矩形を反映する。転送先の矩形は反映されない。

CBaseControlVideo::get_DestinationHeight

CBaseControlVideo クラス

現在の転送先矩形の高さを取得する。

構文

HRESULT get_DestinationHeight(
long *pDestinationHeight
    );

パラメータ

pDestinationHeight
転送先の高さへのポインタ。

戻り値

実装に応じた HRESULT 値を返す。この値は、次の値の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
VFW_E_NOT_CONNECTED | ピンが接続されていないため、処理を実行できない。
NOERROR | 成功。

注意

このメンバ関数は、IBasicVideo::get_DestinationHeight メソッドを実装する。

IBasicVideo インターフェイスを使用して、アプリケーションでビデオの転送元矩形および転送先矩形を変更することができる。転送元矩形は、ネイティブ ビデオ ソースのいずれのセクションが画面上に表示されるかに影響を及ぼす。転送先矩形は、ビデオが再生される場所に影響を及ぼす。転送先矩形は、再生されるウィンドウのクライアント領域に比例する。ウィンドウの左上角の座標は (0,0) である。

CBaseControlVideo::get_DestinationLeft

CBaseControlVideo クラス

現在の転送先矩形の左の座標を取得する。

構文

HRESULT get_DestinationLeft(
long *pDestinationLeft
    );

パラメータ

pDestinationLeft
転送先矩形の左の座標へのポインタ。

戻り値

実装に応じた HRESULT 値を返す。この値は、次の値の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
VFW_E_NOT_CONNECTED | ピンが接続されていないため、処理を実行できない。
NOERROR | 成功。

注意

このメンバ関数は、IBasicVideo::get_DestinationLeft メソッドを実装する。

IBasicVideo インターフェイスを使用して、アプリケーションでビデオの転送元矩形および転送先矩形を変更することができる。転送元矩形は、ネイティブ ビデオ ソースのいずれのセクションが画面上に表示されるかに影響を及ぼす。転送先矩形は、再生時にビデオが表示される場所に影響を及ぼす。転送先矩形は、再生されるウィンドウのクライアント領域に比例する。ウィンドウの左上角の座標は (0,0) である。

CBaseControlVideo::GetDestinationPosition

CBaseControlVideo クラス

1 つの処理で転送先矩形を取得する。

構文

HRESULT GetDestinationPosition(
long *pLeft,
long *pTop,
long *pWidth,
long *pHeight
    );

パラメータ

pLeft
転送先矩形の左の座標へのポインタ。
pTop
転送先矩形の上の座標へのポインタ。
pWidth
転送先矩形の幅へのポインタ。
pHeight
転送先矩形の高さへのポインタ。

戻り値

実装に応じた HRESULT 値を返す。この値は、次の値の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
VFW_E_NOT_CONNECTED | ピンが接続されていないため、処理を実行できない。
NOERROR | 成功。

注意

このメンバ関数は、CBaseControlVideo::get_DestinationLeft、CBaseControlVideo::get_DestinationTop、CBaseControlVideo::get_DestinationWidth、および CBaseControlVideo::get_DestinationHeight メンバ関数の個々の呼び出しの代わりに使用できる。IBasicVideo インターフェイスを使用して、アプリケーションでビデオの転送元矩形および転送先矩形を変更することができる。転送元矩形は、ネイティブ ビデオ ソースのいずれのセクションが画面上に表示されるかに影響を及ぼす。転送先矩形は、再生時にビデオが表示される場所に影響を及ぼす。転送先矩形は、再生されるウィンドウのクライアント領域に比例する。ウィンドウの左上角の座標は (0,0) である。

CBaseControlVideo::get_DestinationTop

CBaseControlVideo クラス

現在の転送先矩形の上の座標を取得する。

構文

HRESULT get_DestinationTop(
long *pDestinationTop
    );

パラメータ

pDestinationTop
転送先矩形の上の座標へのポインタ。

戻り値

実装に応じた HRESULT 値を返す。この値は、次の値の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
VFW_E_NOT_CONNECTED | ピンが接続されていないため、処理を実行できない。
NOERROR | 成功。

注意

このメンバ関数は、IBasicVideo::get_DestinationTop メソッドを実装する。

IBasicVideo インターフェイスを使用して、アプリケーションでビデオの転送元矩形および転送先矩形を変更することができる。転送元矩形は、ネイティブ ビデオ ソースのいずれのセクションが画面上に表示されるかに影響を及ぼす。転送先矩形は、再生時にビデオが表示される場所に影響を及ぼす。転送先矩形は、再生されるウィンドウのクライアント領域に比例する。ウィンドウの左上角の座標は (0,0) である。

CBaseControlVideo::get_DestinationWidth

CBaseControlVideo クラス

現在の転送先矩形の幅を取得する。

構文

HRESULT get_DestinationWidth(
long *pDestinationWidth
    );

パラメータ

pDestinationWidth
転送先の幅へのポインタ。

戻り値

実装に応じた HRESULT 値を返す。この値は、次の値の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
VFW_E_NOT_CONNECTED | ピンが接続されていないため、処理を実行できない。
NOERROR | 成功。

注意

このメンバ関数は、IBasicVideo::get_DestinationWidth メソッドを実装する。

IBasicVideo インターフェイスを使用して、アプリケーションでビデオの転送元矩形および転送先矩形を変更することができる。転送元矩形は、ネイティブ ビデオ ソースのいずれのセクションが画面上に表示されるかに影響を及ぼす。転送先矩形は、再生時にビデオが表示される場所に影響を及ぼす。転送先矩形は、再生されるウィンドウのクライアント領域に比例する。ウィンドウの左上角の座標は (0,0) である。

CBaseControlVideo::GetImageSize

CBaseControlVideo クラス

ビデオ イメージのサイズ情報を取得する。

構文

HRESULT GetImageSize(
VIDEOINFOHEADER *pVideoInfo,
long *pBufferSize,
RECT *pSourceRect
    );

パラメータ

pVideoInfo
格納される VIDEOINFOHEADER 構造体へのポインタ。
pBufferSize
ビデオ バッファのサイズへのポインタ。
pSourceRect
ビデオの転送元矩形のディメンジョンへのポインタ。

戻り値

実装に応じた HRESULT 値を返す。この値は、次の値の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_INVALIDARG | 無効な引数。データ フォーマットに互換性がない。
E_UNEXPECTED | 予期しないエラーが発生した。1 つ以上の引数が NULL である。
NOERROR | 成功。

注意

このメンバ関数は、DIB イメージのメモリ イメージ レンダリングを作成するために使用するヘルパー関数である。このメンバ関数に渡された pVideoImage パラメータが NULL である場合に、CBaseControlVideo::GetCurrentImage の基底クラスの実装から呼び出される。この結果、このメンバ関数は pBufferSize および pSourceRect の情報を使用して、VIDEOINFOHEADER 構造体を構築して返す。

CBaseControlVideo::get_SourceHeight

CBaseControlVideo クラス

現在の転送元矩形の高さを取得する。

構文

HRESULT get_SourceHeight(
long *pSourceHeight
    );

パラメータ

pSourceHeight
転送元矩形の高さへのポインタ。

戻り値

実装に応じた HRESULT 値を返す。この値は、次の値の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
VFW_E_NOT_CONNECTED | ピンが接続されていないため、処理を実行できない。
NOERROR | 成功。

注意

このメンバ関数は、IBasicVideo::get_SourceHeight メソッドを実装する。

IBasicVideo インターフェイスを使用して、アプリケーションでビデオの転送元矩形および転送先矩形を変更することができる。転送元矩形は、ネイティブ ビデオ ソースのいずれのセクションが画面上に表示されるかに影響を及ぼす。転送先矩形は、再生時にビデオが表示される場所に影響を及ぼす。転送先矩形は、再生されるウィンドウのクライアント領域に比例する。ウィンドウの左上角の座標は (0,0) である。

CBaseControlVideo::get_SourceLeft

CBaseControlVideo クラス

現在の転送元矩形の左の座標を取得する。

構文

HRESULT get_SourceLeft(
long *pSourceLeft
    );

パラメータ

pSourceLeft
現在の転送元矩形の左の座標へのポインタ。

戻り値

実装に応じた HRESULT 値を返す。この値は、次の値の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
VFW_E_NOT_CONNECTED | ピンが接続されていないため、処理を実行できない。
NOERROR | 成功。

注意

IBasicVideo インターフェイスを使用して、アプリケーションでビデオの転送元矩形および転送先矩形を変更することができる。転送元矩形は、ネイティブ ビデオ ソースのいずれのセクションが画面上に表示されるかに影響を及ぼす。転送先矩形は、再生時にビデオが表示される場所に影響を及ぼす。転送先矩形は、再生されるウィンドウのクライアント領域に比例する。ウィンドウの左上角の座標は (0,0) である。

CBaseControlVideo::GetSourcePosition

CBaseControlVideo クラス

1 つの処理で転送元矩形の位置およびディメンジョンを取得する。

構文

HRESULT GetSourcePosition(
long *pLeft,
long *pTop,
long *pWidth,
long *pHeight
    );

パラメータ

pLeft
転送元矩形の左の座標へのポインタ。
pTop
転送元矩形の上の座標へのポインタ。
pWidth
転送元矩形の幅へのポインタ。
pHeight
転送元矩形の高さへのポインタ。

戻り値

実装に応じた HRESULT 値を返す。この値は、次の値の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
VFW_E_NOT_CONNECTED | ピンが接続されていないため、処理を実行できない。
NOERROR | 成功。

注意

IBasicVideo インターフェイスを使用して、アプリケーションでビデオの転送元矩形および転送先矩形を変更することができる。転送元矩形は、ネイティブ ビデオ ソースのいずれのセクションが画面上に表示されるかに影響を及ぼす。転送先矩形は、再生時にビデオが表示される場所に影響を及ぼす。転送先矩形は、再生されるウィンドウのクライアント領域に比例する。ウィンドウの左上角の座標は (0,0) である。

CBaseControlVideo::GetSourceRect

CBaseControlVideo クラス

転送元矩形を取得する。これは内部的なメソッドである。

構文

virtual HRESULT GetSourceRect(
RECT *pSourceRect
) PURE;

パラメータ

pSourceRect
取得された転送元矩形へのポインタ。

戻り値

HRESULT 値を返す。

注意

ビデオ レンダラによって保持されている転送元矩形を返すには、このメンバ関数を派生クラスでオーバーライドしなければならない。このメンバ関数は、次の CBaseControlVideo メンバ関数から呼び出される。

  • CBaseControlVideo::GetSourcePosition
  • CBaseControlVideo::put_SourceLeft
  • CBaseControlVideo::get_SourceLeft
  • CBaseControlVideo::put_SourceWidth
  • CBaseControlVideo::get_SourceWidth
  • CBaseControlVideo::put_SourceTop
  • CBaseControlVideo::get_SourceTop
  • CBaseControlVideo::put_SourceHeight
  • CBaseControlVideo::get_SourceHeight

次の例は、この関数を派生クラスに実装する方法を示している。

// 現在の転送元矩形を返す

HRESULT CVideoText::GetSourceRect(RECT *pSourceRect)
{
ASSERT(pSourceRect);
m_pRenderer->m_DrawImage.GetSourceRect(pSourceRect);
return NOERROR;
}

この例では、CVideoText は CBaseControlVideo から派生したクラスであり、m_pRenderer は CBaseVideoRenderer から派生したクラスのオブジェクトを保持する。また、派生クラスで定義される m_DrawImage データ メンバは CDrawImage オブジェクトを保持する。

CBaseControlVideo::get_SourceTop

CBaseControlVideo クラス

現在の転送元矩形の上の座標を取得する。

構文

HRESULT get_SourceTop(
long *pSourceTop
    );

パラメータ

pSourceTop
転送元矩形の上の座標へのポインタ。

戻り値

実装に応じた HRESULT 値を返す。この値は、次の値の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
VFW_E_NOT_CONNECTED | ピンが接続されていないため、処理を実行できない。
NOERROR | 成功。

注意

このメンバ関数は、IBasicVideo::get_SourceTop メソッドを実装する。

IBasicVideo インターフェイスを使用して、アプリケーションでビデオの転送元矩形および転送先矩形を変更することができる。転送元矩形は、ネイティブ ビデオ ソースのいずれのセクションが画面上に表示されるかに影響を及ぼす。転送先矩形は、再生時にビデオが表示される場所に影響を及ぼす。転送先矩形は、再生されるウィンドウのクライアント領域に比例する。ウィンドウの左上角の座標は (0,0) である。

CBaseControlVideo::get_SourceWidth

CBaseControlVideo クラス

現在の転送元矩形の幅を取得する。

構文

HRESULT get_SourceWidth(
long *pSourceWidth
    );

パラメータ

pSourceWidth
現在の転送元矩形の幅へのポインタ。

戻り値

実装に応じた HRESULT 値を返す。この値は、次の値の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
VFW_E_NOT_CONNECTED | ピンが接続されていないため、処理を実行できない。
NOERROR | 成功。

注意

このメンバ関数は、IBasicVideo::get_SourceWidth メソッドを実装する。

IBasicVideo インターフェイスを使用して、アプリケーションでビデオの転送元矩形および転送先矩形を変更することができる。転送元矩形は、ネイティブ ビデオ ソースのいずれのセクションが画面上に表示されるかに影響を及ぼす。転送先矩形は、再生時にビデオが表示される場所に影響を及ぼす。転送先矩形は、再生されるウィンドウのクライアント領域に比例する。ウィンドウの左上角の座標は (0,0) である。

CBaseControlVideo::GetStaticImage

CBaseControlVideo クラス

派生クラスでオーバーライドする純粋仮想メソッド。

構文

virtual HRESULT GetStaticImage(
long *pBufferSize,
long *pDIBImage
) PURE;

パラメータ

pBufferSize
出力バッファのサイズへのポインタ。
pDIBImage
出力バッファへのポインタ。

戻り値

HRESULT 値を返す。

注意

IBasicVideo インターフェイスを使用して、アプリケーションでメモリ バッファ内にある現在のイメージのコピーを要求できる (レンダラがサポートしていない場合は、E_NOIMPL を返すことができる)。イメージを取得する方法は、派生クラスで決定する。アプリケーションが CBaseControlVideo::GetStaticImage を呼び出す場合、アプリケーションは、派生クラスでオーバーライドして実装する必要があるこの純粋仮想メソッドを呼び出す。これは、CBaseControlVideo::GetCurrentImage メンバ関数によっても呼び出される。

このクラスは、イメージを含むサンプルを取得できるヘルパー メンバ関数 CBaseControlVideo::CopyImage を提供しする。このメンバ関数は (現在の転送元矩形に基づいて) イメージの関連するセクションをコピーし、アプリケーションによって提供された出力バッファにコピーする。

次の例は、このメンバ関数を派生クラスに実装する方法を示している。この例で、m_pRenderer は CBaseVideoRenderer から派生したクラスのオブジェクトを保持する。

// ビデオ レンダラ内の現在のイメージのコピーを返す。

HRESULT CVideoText::GetStaticImage(long *pBufferSize,long *pDIBImage)
{
// レンダラが保持しているサンプルを取得する。

IMediaSample *pMediaSample = m_pRenderer->GetCurrentSample();
if (pMediaSample == NULL) {
return E_UNEXPECTED;
    }

// 基底クラスのヘルパー メソッドを呼び出して処理を行う。

HRESULT hr = CopyImage(pMediaSample,          // イメージを含むバッファ
&m_pRenderer->m_mtIn,                // ビットマップを表すタイプ
pBufferSize,                                     // DIB のバッファのサイズ
(BYTE*) pDIBImage);                   // 出力用のデータ バッファ

pMediaSample->Release();
return hr;
}

CBaseControlVideo::GetTargetRect

CBaseControlVideo クラス

転送先矩形を取得する。これは内部的なヘルパー メンバ関数である。

構文

virtual HRESULT GetTargetRect(
RECT *pTargetRect
) PURE;

パラメータ

pTargetRect
転送先矩形へのポインタ。

戻り値

HRESULT 値を返す。

注意

ビデオ レンダラによって保持されている転送先矩形を返すには、このメンバ関数を派生クラスでオーバーライドしなければならない。このメンバ関数は、次の CBaseControlVideo メンバ関数から呼び出される。

  • CBaseControlVideo::GetDestinationPosition
  • CBaseControlVideo::put_DestinationLeft
  • CBaseControlVideo::get_DestinationLeft
  • CBaseControlVideo::put_DestinationWidth
  • CBaseControlVideo::get_DestinationWidth
  • CBaseControlVideo::put_DestinationTop
  • CBaseControlVideo::get_DestinationTop
  • CBaseControlVideo::put_DestinationHeight
  • CBaseControlVideo::get_DestinationHeight

次の例は、この関数を派生クラスに実装する方法を示している。

// 現在の転送先矩形を返す。

HRESULT CVideoText::GetTargetRect(RECT *pTargetRect)
{
ASSERT(pTargetRect);
m_pRenderer->m_DrawImage.GetTargetRect(pTargetRect);
return NOERROR;
}

この例では、CVideoText は CBaseControlVideo から派生したクラスであり、m_pRenderer は CBaseVideoRenderer から派生したクラスのオブジェクトを保持する。また、派生クラスで定義される m_DrawImage データ メンバは CDrawImage オブジェクトを保持する。

CBaseControlVideo::GetVideoFormat

CBaseControlVideo クラス

現在のビデオ フォーマットを表すビデオ サンプルを取得する。

構文

virtual VIDEOINFOHEADER * GetVideoFormat(void) PURE;

戻り値

現在のビデオ フォーマットを含む VIDEOINFOHEADER 構造体へのポインタを返す。

注意

IBasicVideo を使用して特定の情報を返してチェックするには、オブジェクトで現在のビデオ フォーマットがわかっている必要がある。オブジェクトは、派生クラスでオーバーライドする必要があるこの純粋仮想メソッドを呼び出すことによって、この情報を取得する。このメンバ関数は、次の CBaseControlVideo メンバ関数から呼び出される。

  • CBaseControlVideo::OnVideoSizeChange
  • CBaseControlVideo::get_AvgTimePerFrame
  • CBaseControlVideo::get_BitRate
  • CBaseControlVideo::get_BitErrorRate
  • CBaseControlVideo::get_VideoWidth
  • CBaseControlVideo::get_VideoHeight
  • CBaseControlVideo::GetVideoPaletteEntries
  • CBaseControlVideo::GetVideoSize

CBaseControlVideo::get_VideoHeight

CBaseControlVideo クラス

ネイティブ ビデオの高さを取得する。

構文

HRESULT get_VideoHeight(
long *pVideoHeight
    );

パラメータ

pVideoHeight
ピクセル単位のネイティブ ビデオの高さへのポインタ。

戻り値

成功した場合は NOERROR を返す。十分なメモリがない場合は E_OUTOFMEMORY を返す。

注意

このメンバ関数は、IBasicVideo::get_VideoHeight メソッドを実装する。このメンバ関数は、純粋仮想メンバ関数 CBaseControlVideo::GetVideoFormat を呼び出して、派生クラスから VIDEOINFOHEADER 構造体を取得する。

CBaseControlVideo::GetVideoPaletteEntries

CBaseControlVideo クラス

ビデオのパレット エントリの範囲を取得する。

構文

HRESULT GetVideoPaletteEntries(
long StartIndex,
long Entries,
long *pRetrieved,
long *pPalette
    );

パラメータ

StartIndex
0 から始まる開始パレット エントリ。
Entries
必要なエントリの数。
pRetrieved
取得されたカラーの数へのポインタ。
pPalette
カラーの出力バッファへのポインタ。

戻り値

成功した場合は NOERROR、ビデオ サンプルにカラー パレットがない場合は VFW_E_NO_PALETTE_AVAILABLE、十分なメモリがない場合は E_OUTOFMEMORY、StartIndex が無効である場合は E_INVALIDARG、パレットにカラーがない場合は S_FALSE を返す。

注意

このメンバ関数は、現在のビデオのパレットを、ユーザーによって割り当てられた配列として返す。一貫性を保つために、Win32 PALETTEENTRY 構造体のメンバを使用してカラーを返す。パラメータは LONG であるが、RGBQUAD 構造体のメンバは使用しない。メモリは呼び出し元によって割り当てられるので、単にそれぞれをコピーする。要求されたエントリの数および開始位置のオフセットの両方が有効であることを確認する。エントリの数が 0 である場合は、S_FALSE コードを返す。

CBaseControlVideo::GetVideoSize

CBaseControlVideo クラス

ネイティブ ビデオの幅と高さを取得する。

構文

HRESULT GetVideoSize(
long *pWidth,
long *pHeight
    );

パラメータ

pWidth
ビデオの幅へのポインタ。
pHeight
ビデオの高さへのポインタ。

戻り値

実装に応じた HRESULT 値を返す。この値は、次の値の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_OUTOFMEMORY | メモリ不足。
E_POINTER | Null ポインタ引数。
VFW_E_NOT_CONNECTED | ピンが接続されていないため、処理を実行できない。
NOERROR | 成功。

CBaseControlVideo::get_VideoWidth

CBaseControlVideo クラス

ネイティブ ビデオの幅を取得する。

構文

HRESULT get_VideoWidth(
long *pVideoWidth
    );

パラメータ

pVideoWidth
ピクセル単位のネイティブ ビデオの幅へのポインタ。

戻り値

成功した場合は NOERROR を返す。十分なメモリがない場合は E_OUTOFMEMORY を返す。

注意

このメンバ関数は、IBasicVideo::get_VideoWidth メソッドを実装する。このメンバ関数は、純粋仮想メンバ関数 CBaseControlVideo::GetVideoFormat を呼び出して、派生クラスから VIDEOINFOHEADER 構造体を取得する。

CBaseControlVideo::IsDefaultSourceRect

CBaseControlVideo クラス

レンダラがデフォルトの転送元矩形を使用しているかどうかを判断する (純粋仮想)。

構文

virtual HRESULT IsDefaultSourceRect(void) PURE;

戻り値

HRESULT 値を返す。レンダラがデフォルトの転送元を使用している場合は S_OK、それ以外の場合は S_FALSE を返す。

注意

このメンバ関数は派生クラスで実装しなければならない。これは、CBaseControlVideo::IsUsingDefaultSource メンバ関数によって呼び出される。

次の例は、この関数を派生クラスに実装する方法を示している。

// デフォルトの転送元を使用している場合は S_OK、それ以外の場合は S_FALSE を返す。

HRESULT CVideoText::IsDefaultSourceRect()
{
RECT SourceRect;

VIDEOINFO *pVideoInfo = (VIDEOINFO *) m_pRenderer->m_mtIn.Format();
BITMAPINFOHEADER *pHeader = HEADER(pVideoInfo);
m_pRenderer->m_DrawImage.GetSourceRect(&SourceRect);

// ビデオのディメンジョンに一致する座標をチェックする。

if (SourceRect.left != 0 || SourceRect.top != 0 ||
SourceRect.right != pHeader->biWidth ||
SourceRect.bottom != pHeader->biHeight) {
return S_FALSE;
    }
return S_OK;
}

この例では、CVideoText は CBaseControlVideo から派生したクラスであり、m_pRenderer は CBaseVideoRenderer から派生したクラスのオブジェクトを保持する。また、派生クラスで定義される m_DrawImage データ メンバは CDrawImage オブジェクトを保持する。この派生クラスで定義される m_mtIn データ メンバも、入力ピンのメディア タイプを持つ CMediaType オブジェクトを保持する。

CBaseControlVideo::IsDefaultTargetRect

CBaseControlVideo クラス

レンダラがデフォルトの転送先矩形を使用しているかどうかを判断する (純粋仮想)。

構文

virtual HRESULT IsDefaultTargetRect(void) PURE;

戻り値

HRESULT 値を返す。レンダラがデフォルトの転送先を使用している場合は S_OK、それ以外の場合は S_FALSE を返す。

注意

このメンバ関数は派生クラスで実装しなければならない。これは、CBaseControlVideo::IsUsingDefaultDestination メンバ関数によって呼び出される。

次の例は、この関数を派生クラスに実装する方法を示している。

// デフォルトの転送先を使用している場合は S_OK、それ以外の場合は S_FALSE を返す。

HRESULT CVideoText::IsDefaultTargetRect()
{
RECT TargetRect;

VIDEOINFO *pVideoInfo = (VIDEOINFO *) m_pRenderer->m_mtIn.Format();
BITMAPINFOHEADER *pHeader = HEADER(pVideoInfo);
m_pRenderer->m_DrawImage.GetTargetRect(&TargetRect);

// 初期クライアント領域に一致する転送先をチェックする。

if (TargetRect.left != 0 || TargetRect.top != 0 ||
TargetRect.right != m_Size.cx ||
TargetRect.bottom != m_Size.cy) {
return S_FALSE;
    }
return S_OK;
}

この例では、CVideoText は CBaseControlVideo から派生したクラスであり、m_pRenderer は CBaseVideoRenderer から派生したクラスのオブジェクトを保持する。また、派生クラスで定義される m_DrawImage データ メンバは CDrawImage オブジェクトを保持する。この派生クラスで定義される m_mtIn データ メンバも、入力ピンのメディア タイプを持つ CMediaType オブジェクトを保持する。

CBaseControlVideo::IsUsingDefaultSource

CBaseControlVideo クラス

レンダラがデフォルトの転送元ウィンドウを使用しているかどうかを判断する。

構文

virtual HRESULT IsUsingDefaultSource(void);

戻り値

HRESULT 値を返す。レンダラがデフォルトの転送元を使用している場合は S_OK、それ以外の場合は S_FALSE を返す。

CBaseControlVideo::IsUsingDefaultDestination

CBaseControlVideo クラス

レンダラがデフォルトの転送先ウィンドウを使用しているかどうかを判断する。

構文

virtual HRESULT IsUsingDefaultDestination(void);

戻り値

HRESULT 値を返す。デフォルトの転送先を使用している場合は S_OK、それ以外の場合は S_FALSE を返す。

CBaseControlVideo::OnUpdateRectangles

CBaseControlVideo クラス

転送元矩形または転送先矩形のいずれかが変更されると呼び出される。

構文

virtual HRESULT OnUpdateRectangles(void);

戻り値

NOERROR を返す。

CBaseControlVideo::OnVideoSizeChange

CBaseControlVideo クラス

EC_VIDEO_SIZE_CHANGED メッセージをフィルタ グラフ マネージャに渡す。

構文

virtual HRESULT OnVideoSizeChange(void);

戻り値

実装に応じた HRESULT 値を返す。この値は、次の値の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_OUTOFMEMORY | メモリ不足。

注意

ビデオ レンダラはビデオのサイズが変更されるたびにこのメンバ関数を呼び出す必要がある。通常、最初の接続の後に 1 回呼び出される。レンダラが動的なフォーマットの変更 (320 x 240 から 160 x 120) をサポートしている場合、レンダラは各変更の後にもこのメンバ関数を呼び出す必要がある。

CBaseControlVideo::put_DestinationHeight

CBaseControlVideo クラス

転送先矩形の高さを設定する。

構文

HRESULT put_DestinationHeight(
long DestinationHeight
    );

パラメータ

DestinationHeight
新しい転送先の高さ。

戻り値

実装に応じた HRESULT 値を返す。この値は、次の値の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_INVALIDARG | 無効な引数。
E_POINTER | Null ポインタ引数。
NOERROR | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されていないため、処理を実行できない。

注意

IBasicVideo インターフェイスを使用して、アプリケーションでビデオの転送元矩形および転送先矩形を変更することができる。転送元矩形は、ネイティブ ビデオ ソースのいずれのセクションが画面上に表示されるかに影響を及ぼす。転送先矩形は、再生時にビデオが表示される場所に影響を及ぼす。転送先矩形は、再生されるウィンドウのクライアント領域に比例する。ウィンドウの左上角の座標は (0,0) である。

CBaseControlVideo::put_DestinationLeft

CBaseControlVideo クラス

転送先矩形の左の座標を設定する。

構文

HRESULT put_DestinationLeft(
long DestinationLeft
    );

パラメータ

DestinationLeft
新しい転送先の左の座標。

戻り値

実装に応じた HRESULT 値を返す。この値は、次の値の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_INVALIDARG | 無効な引数。
E_POINTER | Null ポインタ引数。
NOERROR | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されていないため、処理を実行できない。

注意

IBasicVideo インターフェイスを使用して、アプリケーションでビデオの転送元矩形および転送先矩形を変更することができる。転送元矩形は、ネイティブ ビデオ ソースのいずれのセクションが画面上に表示されるかに影響を及ぼす。転送先矩形は、再生時にビデオが表示される場所に影響を及ぼす。転送先矩形は、再生されるウィンドウのクライアント領域に比例する。ウィンドウの左上角の座標は (0,0) である。

CBaseControlVideo::put_DestinationTop

CBaseControlVideo クラス

転送先矩形の上の座標を設定する。

構文

HRESULT put_DestinationTop(
long DestinationTop
    );

パラメータ

DestinationTop
新しい転送先の上の座標。

戻り値

実装に応じた HRESULT 値を返す。この値は、次の値の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_INVALIDARG | 無効な引数。
E_POINTER | Null ポインタ引数。
NOERROR | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されていないため、処理を実行できない。

注意

IBasicVideo インターフェイスを使用して、アプリケーションでビデオの転送元矩形および転送先矩形を変更することができる。転送元矩形は、ネイティブ ビデオ ソースのいずれのセクションが画面上に表示されるかに影響を及ぼす。転送先矩形は、再生時にビデオが表示される場所に影響を及ぼす。転送先矩形は、再生されるウィンドウのクライアント領域に比例する。ウィンドウの左上角の座標は (0,0) である。

CBaseControlVideo::put_DestinationWidth

CBaseControlVideo クラス

転送先矩形の幅を設定する。

構文

HRESULT put_DestinationWidth(
long DestinationWidth
    );

パラメータ

DestinationWidth
新しい転送先の幅。

戻り値

実装に応じた HRESULT 値を返す。この値は、次の値の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_INVALIDARG | 無効な引数。
E_POINTER | Null ポインタ引数。
NOERROR | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されていないため、処理を実行できない。

注意

IBasicVideo インターフェイスを使用して、アプリケーションでビデオの転送元矩形および転送先矩形を変更することができる。転送元矩形は、ネイティブ ビデオ ソースのいずれのセクションが画面上に表示されるかに影響を及ぼす。転送先矩形は、再生時にビデオが表示される場所に影響を及ぼす。転送先矩形は、再生されるウィンドウのクライアント領域に比例する。ウィンドウの左上角の座標は (0,0) である。

CBaseControlVideo::put_SourceHeight

CBaseControlVideo クラス

転送元矩形の高さを設定する。

構文

HRESULT put_SourceHeight(
long SourceHeight
    );

パラメータ

SourceHeight
転送元の高さ。

戻り値

実装に応じた HRESULT 値を返す。この値は、次の値の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_INVALIDARG | 無効な引数。
E_POINTER | Null ポインタ引数。
NOERROR | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されていないため、処理を実行できない。

注意

IBasicVideo インターフェイスを使用して、アプリケーションでビデオの転送元矩形および転送先矩形を変更することができる。転送元矩形は、ネイティブ ビデオ ソースのいずれのセクションが画面上に表示されるかに影響を及ぼす。転送先矩形は、再生時にビデオが表示される場所に影響を及ぼす。転送先矩形は、再生されるウィンドウのクライアント領域に比例する。ウィンドウの左上角の座標は (0,0) である。

CBaseControlVideo::put_SourceLeft

CBaseControlVideo クラス

転送元矩形の左の座標を設定する。

構文

HRESULT put_SourceLeft(
long SourceLeft
    );

パラメータ

SourceLeft
新しい転送元の左の座標。

戻り値

実装に応じた HRESULT 値を返す。この値は、次の値の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_INVALIDARG | 無効な引数。
E_POINTER | Null ポインタ引数。
NOERROR | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されていないため、処理を実行できない。

注意

IBasicVideo インターフェイスを使用して、アプリケーションでビデオの転送元矩形および転送先矩形を変更することができる。転送元矩形は、ネイティブ ビデオ ソースのいずれのセクションが画面上に表示されるかに影響を及ぼす。転送先矩形は、再生時にビデオが表示される場所に影響を及ぼす。転送先矩形は、再生されるウィンドウのクライアント領域に比例する。ウィンドウの左上角の座標は (0,0) である。

CBaseControlVideo::put_SourceTop

CBaseControlVideo クラス

転送元矩形の上の座標を設定する。

構文

HRESULT put_SourceTop(
long SourceTop
    );

パラメータ

SourceTop
新しい転送元の上の座標。

戻り値

実装に応じた HRESULT 値を返す。この値は、次の値の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_INVALIDARG | 無効な引数。
E_POINTER | Null ポインタ引数。
NOERROR | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されていないため、処理を実行できない。

注意

IBasicVideo インターフェイスを使用して、アプリケーションでビデオの転送元矩形および転送先矩形を変更することができる。転送元矩形は、ネイティブ ビデオ ソースのいずれのセクションが画面上に表示されるかに影響を及ぼす。転送先矩形は、再生時にビデオが表示される場所に影響を及ぼす。転送先矩形は、再生されるウィンドウのクライアント領域に比例する。ウィンドウの左上角の座標は (0,0) である。

CBaseControlVideo::put_SourceWidth

CBaseControlVideo クラス

転送元矩形の幅を設定する。

構文

HRESULT put_SourceWidth(
long SourceWidth
    );

パラメータ

SourceWidth
新しい転送元矩形の幅。

戻り値

実装に応じた HRESULT 値を返す。この値は、次の値の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_INVALIDARG | 無効な引数。
E_POINTER | Null ポインタ引数。
NOERROR | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されていないため、処理を実行できない。

注意

IBasicVideo インターフェイスを使用して、アプリケーションでビデオの転送元矩形および転送先矩形を変更することができる。転送元矩形は、ネイティブ ビデオ ソースのいずれのセクションが画面上に表示されるかに影響を及ぼす。転送先矩形は、再生時にビデオが表示される場所に影響を及ぼす。転送先矩形は、再生されるウィンドウのクライアント領域に比例する。ウィンドウの左上角の座標は (0,0) である。

CBaseControlVideo::SetControlVideoPin

CBaseControlVideo クラス

フィルタによって使用されるピンを設定する。

構文

void SetControlVideoPin(
CBasePin *pPin
    );

パラメータ

pPin
インターフェイスが同期するピンへのポインタ。

戻り値

戻り値なし。

注意

このインターフェイスは、フィルタが正常に接続された場合にのみ呼び出すことができる。オブジェクトは、このメソッドによって同期されるピンに渡される。ほとんどの場合、インターフェイス メソッドが呼び出されたときにピンが接続されているかどうかを判断し、失敗した場合は VFW_E_NOT_CONNECTED を返す。

CBaseControlVideo::SetDefaultDestinationPosition

CBaseControlVideo クラス

レンダラがデフォルトの転送先の位置 (通常、ウィンドウ クライアント領域全体) を使用するように設定する。

構文

HRESULT SetDefaultDestinationPosition(void);

戻り値

実装に応じた HRESULT 値を返す。この値は、次の値の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
NOERROR | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されていないため、処理を実行できない。

注意

IBasicVideo インターフェイスを使用して、アプリケーションでビデオの転送元矩形および転送先矩形を変更することができる。転送元矩形は、ネイティブ ビデオ ソースのいずれのセクションが画面上に表示されるかに影響を及ぼす。転送先矩形は、再生時にビデオが表示される場所に影響を及ぼす。転送先矩形は、再生されるウィンドウのクライアント領域に比例する。ウィンドウの左上角の座標は (0,0) である。

CBaseControlVideo::SetDefaultSourcePosition

CBaseControlVideo クラス

レンダラがデフォルトの転送元の位置 (通常、すべてのネイティブ ビデオ) を使用するように設定する。

構文

HRESULT SetDefaultSourcePosition(void);

戻り値

実装に応じた HRESULT 値を返す。この値は、次の値の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
NOERROR | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されていないため、処理を実行できない。

注意

IBasicVideo インターフェイスを使用して、アプリケーションでビデオの転送元矩形および転送先矩形を変更することができる。転送元矩形は、ネイティブ ビデオ ソースのいずれのセクションが画面上に表示されるかに影響を及ぼす。転送先矩形は、再生時にビデオが表示される場所に影響を及ぼす。転送先矩形は、再生されるウィンドウのクライアント領域に比例する。ウィンドウの左上角の座標は (0,0) である。

CBaseControlVideo::SetDefaultSourceRect

CBaseControlVideo クラス

デフォルトのビデオの転送元矩形を設定する (純粋仮想)。これは、転送元矩形がリセットされたときに呼び出される内部的なメンバ関数である。

構文

virtual HRESULT SetDefaultSourceRect(void) PURE;

戻り値

HRESULT 値を返す。

注意

転送元矩形をリセットするには、派生クラスでこれをオーバーライドする必要がある。このメンバ関数は CBaseControlVideo::SetDefaultSourcePosition から呼び出される。

次の例は、この関数を派生クラスに実装する方法を示している。

// これはデフォルトの転送元矩形をリセットすると呼び出される。

HRESULT CVideoText::SetDefaultSourceRect()
{
VIDEOINFO *pVideoInfo = (VIDEOINFO *) m_pRenderer->m_mtIn.Format();
BITMAPINFOHEADER *pHeader = HEADER(pVideoInfo);
RECT SourceRect = {0,0,pHeader->biWidth,pHeader->biHeight};
m_pRenderer->m_DrawImage.SetSourceRect(&SourceRect);
return NOERROR;
}

この例では、CVideoText は CBaseControlVideo から派生したクラスであり、m_pRenderer は CBaseVideoRenderer から派生したクラスのオブジェクトを保持する。また、派生クラスで定義される m_DrawImage データ メンバは CDrawImage オブジェクトを保持する。この派生クラスで定義される m_mtIn データ メンバも、入力ピンのメディア タイプを持つ CMediaType オブジェクトを保持する。

CBaseControlVideo::SetDefaultTargetRect

CBaseControlVideo クラス

デフォルトのビデオの転送先矩形を設定する (純粋仮想)。これは、転送先矩形がリセットされたときに呼び出される内部的なメンバ関数である。

構文

virtual HRESULT SetDefaultTargetRect(void) PURE;

戻り値

HRESULT 値を返す。

注意

ビデオの転送先矩形をリセットするには、派生クラスでこれをオーバーライドする必要がある。このメンバ関数は CBaseControlVideo::SetDefaultDestinationPosition メンバ関数から呼び出される。

次の例は、この関数を派生クラスに実装する方法を示している。

// これはデフォルトの転送先矩形をリセットすると呼び出される。

HRESULT CVideoText::SetDefaultTargetRect()
{
VIDEOINFO *pVideoInfo = (VIDEOINFO *) m_pRenderer->m_mtIn.Format();
BITMAPINFOHEADER *pHeader = HEADER(pVideoInfo);
RECT TargetRect = {0,0,m_Size.cx,m_Size.cy};
m_pRenderer->m_DrawImage.SetTargetRect(&TargetRect);
return NOERROR;
}

この例では、CVideoText は CBaseControlVideo から派生したクラスであり、m_pRenderer は CBaseVideoRenderer から派生したクラスのオブジェクトを保持する。また、派生クラスで定義される m_DrawImage データ メンバは CDrawImage オブジェクトを保持する。この派生クラスで定義される m_mtIn データ メンバも、入力ピンのメディア タイプを持つ CMediaType オブジェクトを保持する。

CBaseControlVideo::SetDestinationPosition

CBaseControlVideo クラス

ビデオの転送先矩形を設定する。

構文

HRESULT SetDestinationPosition(
long Left,
long Top,
long Width,
long Height
    );

パラメータ

Left
新しい左の座標。
Top
新しい上の座標。
Width
新しい幅。
Height
新しい高さ。

戻り値

実装に応じた HRESULT 値を返す。この値は、次の値の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_INVALIDARG | 無効な引数。
E_POINTER | Null ポインタ引数。
NOERROR | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されていないため、処理を実行できない。

注意

IBasicVideo インターフェイスを使用して、アプリケーションでビデオの転送元矩形および転送先矩形を変更することができる。転送元矩形は、ネイティブ ビデオ ソースのいずれのセクションが画面上に表示されるかに影響を及ぼす。転送先矩形は、再生時にビデオが表示される場所に影響を及ぼす。転送先矩形は、再生されるウィンドウのクライアント領域に比例する。ウィンドウの左上角の座標は (0,0) である。

CBaseControlVideo::SetSourcePosition

CBaseControlVideo クラス

ビデオの新しい転送元の位置を設定する。

構文

HRESULT SetSourcePosition(
long Left,
long Top,
long Width,
long Height
    );

パラメータ

Left
新しい左の座標。
Top
新しい上の座標。
Width
新しい幅。
Height
新しい高さ。

戻り値

実装に応じた HRESULT 値を返す。この値は、次の値の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_INVALIDARG | 無効な引数。
E_POINTER | Null ポインタ引数。
NOERROR | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されていないため、処理を実行できない。

注意

IBasicVideo インターフェイスを使用して、アプリケーションでビデオの転送元矩形および転送先矩形を変更することができる。転送元矩形は、ネイティブ ビデオ ソースのいずれのセクションが画面上に表示されるかに影響を及ぼす。転送先矩形は、再生時にビデオが表示される場所に影響を及ぼす。転送先矩形は、再生されるウィンドウのクライアント領域に比例する。ウィンドウの左上角の座標は (0,0) である。

CBaseControlVideo::SetSourceRect

CBaseControlVideo クラス

現在のビデオの転送元矩形を設定する (純粋仮想)。これは、転送元矩形が変更されたときに呼び出される内部的なメンバ関数である。

構文

virtual HRESULT SetSourceRect(
RECT *pSourceRect
) PURE;

パラメータ

pSourceRect
転送元矩形へのポインタ。

戻り値

HRESULT 値を返す。

注意

転送元矩形が変更されたことを知るには、派生クラスでこのメンバ関数をオーバーライドする必要がある。このメンバ関数は、次のメンバ関数から呼び出される。

  • CBaseControlVideo::SetSourcePosition
  • CBaseControlVideo::put_SourceLeft
  • CBaseControlVideo::put_SourceWidth
  • CBaseControlVideo::put_SourceTop
  • CBaseControlVideo::put_SourceHeight

次の例は、この関数を派生クラスに実装する方法を示している。

HRESULT CVideoText::SetSourceRect(RECT *pSourceRect)
{
m_pRenderer->m_DrawImage.SetSourceRect(pSourceRect);
return NOERROR;
}

この例では、CVideoText は CBaseControlVideo から派生したクラスであり、m_pRenderer は CBaseVideoRenderer から派生したクラスのオブジェクトを保持する。また、派生クラスで定義される m_DrawImage データ メンバは CDrawImage オブジェクトを保持する。

CBaseControlVideo::SetTargetRect

CBaseControlVideo クラス

現在の転送先矩形を設定する (純粋仮想)。これは、転送先矩形が変更されたときに呼び出される内部的なメンバ関数である。

構文

virtual HRESULT SetTargetRect(
RECT *pTargetRect
) PURE;

パラメータ

pTargetRect
転送先矩形へのポインタ。

戻り値

HRESULT 値を返す。

注意

転送先矩形が変更されたことを知るには、派生クラスでこのメンバ関数をオーバーライドする必要がある。このメンバ関数は、次のメンバ関数から呼び出される。

  • CBaseControlVideo::SetDestinationPosition
  • CBaseControlVideo::put_DestinationLeft
  • CBaseControlVideo::put_DestinationWidth
  • CBaseControlVideo::put_DestinationTop
  • CBaseControlVideo::put_DestinationHeight

次の例は、この関数を派生クラスに実装する方法を示している。

HRESULT CVideoText::SetTargetRect(RECT *pTargetRect)
{
m_pRenderer->m_DrawImage.SetTargetRect(pTargetRect);
return NOERROR;
}

この例では、CVideoText は CBaseControlVideo から派生したクラスであり、m_pRenderer は CBaseVideoRenderer から派生したクラスのオブジェクトを保持する。また、派生クラスで定義される m_DrawImage データ メンバは CDrawImage オブジェクトを保持する。


CBaseControlWindow クラス

CBaseControlWindow クラスは IVideoWindow インターフェイスを実装し、これに関連付けられたフィルタへの外部のアクセスを制御する。クリティカル セクション同期オブジェクトへのポインタを渡すことによって、CBaseControlWindow オブジェクトをフィルタと同期しなければならない。クリティカル セクション同期オブジェクトの詳細については、Platform SDK を参照すること。CBaseControlWindow クラスは、このクリティカル セクションを処理せずにプロパティの設定を返す数多くのメソッドを提供する。たとえば、CBaseControlWindow::get_AutoShow を呼び出して m_bAutoShow データ メンバの値を取得すると、クリティカル セクションはロックされる。ただし、フィルタが既に内部クリティカル セクションをロックしている場合があり、この場合はフィルタのロック階層に違反する。この代わりに、CBaseControlWindow::IsAutoShowEnabled メンバ関数を呼び出すと、クリティカル セクションに影響を及ぼさずに必要な値が返される。

CBaseControlWindow が実装するすべての IVideoWindow メソッドでは、フィルタがアップストリーム フィルタに正しく接続されている必要がある。このため、クラス オブジェクトは同期ピンを必要とする。同期ピンは、CBaseControlWindow::SetControlWindowPin メソッドを呼び出すことによって設定される。IVideoWindow メソッドを呼び出すと、CBaseControlWindow オブジェクトはこのピンが接続されていることをチェックする。

プロテクト データ メンバ

m_bAutoShow | 状態が変化したときの結果。
m_bCursorHidden | カーソルが表示または非表示のいずれであるかの判別。
m_BorderColour | 現在のウィンドウの境界のカラー。
m_hwndDrain | 受信したメッセージの送信先のウィンドウ ハンドル。
m_hwndOwner | 所有するウィンドウ。
m_pFilter | 所有するメディア フィルタへのポインタ。
m_pInterfaceLock | 外部的に定義されるクリティカル セクション。
m_pPin | 接続のメディア タイプの制御。

メンバ関数

CBaseControlWindow | CBaseControlWindow オブジェクトを作成する。
DoGetWindowStyle | 標準ウィンドウ スタイルまたは拡張ウィンドウ スタイルのいずれかを取得する。
DoSetWindowStyle | 標準ウィンドウ スタイルまたは拡張ウィンドウ スタイルを設定する。
GetBorderColour | 現在の境界のカラーを取得する。これはヘルパー メンバ関数である。
GetOwnerWindow | 所有するウィンドウを取得する。これはヘルパー メンバ関数である。
IsAutoShowEnabled | レンダリング フィルタがポーズまたは実行されたときに、ビデオ ウィンドウが自動的に表示されるかどうかについての情報を取得する。
IsCursorHidden | クリティカル セクションをロックせずに、m_bCursorHidden データ メンバの現在の状態を取得する。これはヘルパー メンバ関数である。
PossiblyEatMessage | 親ウィンドウにメッセージを配信する。
SetControlWindowPin | オブジェクトが適用されるピンをオブジェクトに通知する。

実装される IVideoWindow メソッド

get_AutoShow | 現在の AutoShow フラグの設定を取得する。
get_BackgroundPalette | バックグラウンド フラグで実現されたパレットを取得する。
get_BorderColor | 現在の境界のカラーを取得する。
get_Caption | 現在のウィンドウ キャプションを取得する。
get_FullScreenMode | 現在のフルスクリーン モードを取得する。
get_Height | 現在のウィンドウの高さを取得する。
get_Left | 現在の左のウィンドウ座標を取得する。
GetMaxIdealImageSize | 理想的なイメージの最大サイズを取得する。
get_MessageDrain | 現在のメッセージ ドレーンを取得する。
GetMinIdealImageSize | 理想的なイメージの最小サイズを取得する。
get_Owner | Microsoft® Win32® 親ウィンドウ ハンドルを取得する。
GetRestorePosition | 最大化または最小化したときに、ウィンドウが復元される位置を取得する。
get_Top | ウィンドウ上部の y 座標を取得する。
get_Visible | ウィンドウの現在の表示の設定を取得する。
get_Width | ウィンドウの幅を取得する。
GetWindowPosition | 現在のウィンドウの座標を取得する。
get_WindowState | 現在のウィンドウの状態を取得する。
get_WindowStyle | 標準ウィンドウ スタイルを取得する。
get_WindowStyleEx | 拡張ウィンドウ スタイルを取得する。
HideCursor | カーソルの表示/非表示を切り替える。
IsCursorHidden | m_bCursorHidden データ メンバの現在の状態を取得する。
NotifyOwnerMessage | 所有するウィンドウに送信されるメッセージを渡す。
put_AutoShow | AutoShow プロパティを設定する。
put_BackgroundPalette | バックグラウンドでパレットを実現するためのフラグを設定する。
put_BorderColor | 現在の境界のカラーを設定する。
put_Caption | 現在のウィンドウ キャプションを設定する。
put_FullScreenMode | フルスクリーン モードを設定する。
put_Height | 現在のウィンドウの高さを設定する。
put_Left | ウィンドウの左の座標を設定する。
put_MessageDrain | メッセージ ドレーン ウィンドウを設定する。
put_Owner | Microsoft Win32 親ウィンドウ ハンドルを設定する。
put_Top | ウィンドウ上部の位置を設定する。
put_Visible | ウィンドウの表示/非表示を切り替える。
put_Width | ウィンドウの幅を設定する。
put_WindowState | ウィンドウの状態を設定する。
put_WindowStyle | 標準ウィンドウ スタイルを設定する。
put_WindowStyleEx | 拡張ウィンドウ スタイルを設定する。
SetWindowForeground | フォアグラウンドのウィンドウを設定する。
SetWindowPosition | ウィンドウの位置を設定する。

CBaseControlWindow::CBaseControlWindow

CBaseControlWindow クラス

CBaseControlWindow オブジェクトを作成する。

構文

CBaseControlWindow(
CBaseMediaFilter *pFilter,
CCritSec *pInterfaceLock,
TCHAR *pName,
LPUNKNOWN pUnk,
HRESULT *phr
);

パラメータ

pFilter
所有するメディア フィルタ オブジェクトへのポインタ。
pInterfaceLock
ロックのために使用するクリティカル セクションへのポインタ。
pName
オブジェクト記述へのポインタ。
pUnk
オブジェクトが集成の一部ではない場合は、制御する IUnknown インターフェイスへのポインタ。それ以外の場合は、NULL でなければならない。
phr
コンストラクタ メソッドの成功または失敗を示す HRESULT 値を受け取る変数へのポインタ。

戻り値

戻り値なし。

CBaseControlWindow::DoGetWindowStyle

CBaseControlWindow クラス

現在の標準ウィンドウ スタイルまたは拡張ウィンドウ スタイルを取得する。

構文

HRESULT DoGetWindowStyle(
long *pStyle,
long WindowLong
);

パラメータ

pStyle
スタイル情報を受け取る変数へのポインタ。
WindowLong
取得するスタイルを指定する値。次のいずれかでなければならない。
GWL_STYLE | ウィンドウ スタイルを取得する。
GWL_EXSTYLE | 拡張ウィンドウ スタイルを取得する。

戻り値

HRESULT 値を返す。

注意

このメンバ関数は、Win32 GetWindowLong 関数を呼び出してウィンドウ スタイルを取得する。このメンバ関数は、CBaseControlWindow::get_WindowStyle および CBaseControlWindow::get_WindowStyleEx メンバ関数によって呼び出される。

CBaseControlWindow::DoSetWindowStyle

CBaseControlWindow クラス

標準ウィンドウ スタイルまたは拡張ウィンドウ スタイルを変更する。

構文

HRESULT DoSetWindowStyle(
long Style,
long WindowLong
);

パラメータ

Style
適切なウィンドウ スタイル。
WindowLong
設定するスタイルを指定する値。次のいずれかでなければならない。
GWL_STYLE | ウィンドウ スタイルを取得する。
GWL_EXSTYLE | 拡張ウィンドウ スタイルを取得する。

戻り値

HRESULT 値を返す。

注意

このメンバ関数は、Win32 SetWindowLong 関数を呼び出してウィンドウ スタイルを設定し、次に現在の位置にウィンドウを再表示する。このメンバ関数は、CBaseControlWindow::put_WindowStyle および CBaseControlWindow::put_WindowStyleEx メンバ関数によって呼び出される。

CBaseControlWindow::get_AutoShow

CBaseControlWindow クラス

現在の AutoShow 状態フラグを取得する。

構文

HRESULT get_AutoShow(
long *AutoShow
);

パラメータ

AutoShow
オートメーション ブール型フラグへのポインタ (0 はオフ、-1 はオン)。

戻り値

HRESULT 値を返す。

注意

このメンバ関数は、IVideoWindow::get_AutoShow メソッドを実装する。このプロパティは、アプリケーションのウィンドウ表示アクセスを簡素化する。このプロパティが -1 (オン) に設定されている場合、通常フィルタの接続後は非表示になっているウィンドウは、フィルタがポーズまたは実行されると自動的に表示される。ただし、フィルタが停止した場合、ウィンドウを非表示にするべきではない。このパラメータが 0 (オフ) に設定されている場合、アプリケーションが適切なパラメータを指定して CBaseControlWindow::put_Visible または CBaseControlWindow::put_WindowState を呼び出したときにのみウィンドウが表示される。

このメンバ関数は、IVideoWindow インターフェイスを使用して外部オブジェクトによって呼び出されることを想定しているので、関連付けられたフィルタと同期するためにクリティカル セクションをロックする。外部オブジェクトから呼び出さない場合に、このプロパティを取得するには、CBaseControlWindow::IsAutoShowEnabled メンバ関数を呼び出す。

CBaseControlWindow::get_BackgroundPalette

CBaseControlWindow クラス

バックグラウンド フラグで実現されたパレットを取得する。

構文

HRESULT get_BackgroundPalette(
long *pBackgroundPalette
);

パラメータ

pBackgroundPalette
オートメーション ブール型フラグへのポインタ (0 はオフ、-1 はオン)。

戻り値

HRESULT 値を返す。

注意

このメンバ関数は、IVideoWindow::get_BackgroundPalette メソッドを実装する。ビデオを別のアプリケーションまたはドキュメントで再生する場合、そのアプリケーションで独自のパレットを使いたいことがある。このフラグを -1 に設定することによって、アプリケーションはビデオの再生に現在のフォアグラウンド パレットを使用することを要求できる。このフラグが 0 に設定されている場合、ウィンドウは独自の優先パレットをインストールして実現する。ウィンドウで別のパレットを使用するように指定すると、パフォーマンスが大幅に低下することに注意が必要である。

CBaseControlWindow::get_BorderColor

CBaseControlWindow クラス

現在の境界のカラーを取得する。

構文

HRESULT get_BorderColor(
long *Color
);

パラメータ

Color
現在の境界のカラーへのポインタ。

戻り値

HRESULT 値を返す。

注意

アプリケーションはビデオを表示する転送先矩形を設定できる。この矩形は、ウィンドウのクライアント領域に比例する。転送先矩形を設定した場合 (デフォルトでは常にウィンドウ全体が描画される)、ビデオの周囲に境界が表示される。このプロパティは、境界で使用されるカラーに影響する。このパラメータは LONG 型として指定されているが、実際には COLORREF 値である。

このメンバ関数は、IVideoWindow インターフェイスを使用して外部オブジェクトによって呼び出されることを想定しているので、関連付けられたフィルタと同期するためにクリティカル セクションをロックする。外部オブジェクトから呼び出さない場合に、このプロパティを取得するには、CBaseControlWindow::GetBorderColour メンバ関数を呼び出す。

CBaseControlWindow::GetBorderColour

CBaseControlWindow クラス

現在のウィンドウの境界カラー m_BorderColour を取得する。

構文

COLORREF GetBorderColour(void);

戻り値

境界のカラーを返す。

注意

アプリケーションはビデオを表示する転送先矩形を設定できる。この矩形は、ウィンドウのクライアント領域に比例する。転送先矩形を設定した場合 (デフォルトでは常にウィンドウ全体が描画される)、ビデオを囲む領域、つまり境界が表示される。境界のカラーは、CBaseControlWindow::put_BorderColor メンバ関数を使用して設定できる。このプロパティは、境界のカラーに影響する。IVideoWindow::get_BorderColor メソッドを使用して外部から呼び出す場合以外は、CBaseControlWindow::get_BorderColor の代わりにこのメンバ関数を使用する。

CBaseControlWindow::get_Caption

CBaseControlWindow クラス

現在のウィンドウ キャプションを取得する。

構文

HRESULT get_Caption(
BSTR *pstrCaption
);

パラメータ

pstrCaption
現在のウィンドウ キャプションへのポインタ。

戻り値

HRESULT 値を返す。

注意

Windows ベースのデスクトップ上の最上位ウィンドウには、タイトル (キャプション) が関連付けられる。このプロパティは、IVideoWindow インターフェイスを使用して問い合わせおよび設定することができる。設定されたキャプションは、ウィンドウに WS_CAPTION スタイルが適用されている場合にのみ表示される。このスタイルが適用されていない場合、ユーザーに対しては表示されないが、キャプションは設定 (および取得) できる。

CBaseControlWindow::get_FullScreenMode

CBaseControlWindow クラス

現在のフルスクリーン モードを取得する。

構文

HRESULT get_FullScreenMode(
long *FullScreenMode
);

パラメータ

FullScreenMode
現在のフルスクリーン モードへのポインタ。

戻り値

HRESULT 値を返す。

注意

このメンバ関数は、デフォルトで E_NOTIMPL を返す。これは、IVideoWindow PID に、このレンダラがフルスクリーン レンダラを実装していないことを通知する。

CBaseControlWindow::get_Height

CBaseControlWindow クラス

現在のウィンドウの高さを取得する。

構文

HRESULT get_Height(
long *pHeight
);

パラメータ

pHeight
ピクセル単位の現在のウィンドウの高さへのポインタ。

戻り値

HRESULT 値を返す。

注意

ウィンドウはデスクトップ上に位置座標を持つ。これはピクセル単位の 4 つの座標 (左、上、右、下) によって表される。OLE によって自動化されるインターフェイスでは、通常、左、上、幅、および高さでこの位置座標を表す。これは Microsoft® DirectShow® で採用されている規則である。座標はすべてピクセル単位で表され、座標が変更されるとウィンドウが即座に更新される。

左または上の座標を設定すると、ウィンドウはそれぞれ左または上に移動する。これらの座標はウィンドウの幅や高さには影響を与えない。同様に、幅および高さの設定は左および上の座標には影響を与えない。

CBaseControlWindow::get_Left

CBaseControlWindow クラス

現在の左のウィンドウ座標を取得する。

構文

HRESULT get_Left(
long *pLeft
);

パラメータ

pLeft
ピクセル単位の左の座標へのポインタ。

戻り値

HRESULT 値を返す。

注意

ウィンドウはデスクトップ上に位置座標を持つ。この位置座標はピクセル単位の 4 つの座標 (左、上、右、下) によって表される。OLE によって自動化されるインターフェイスでは、通常、左、上、幅、および高さでこの位置座標を表す。これは DirectShow で採用されている規則である。座標はすべてピクセル単位で表され、座標が変更されるとウィンドウが即座に更新される。

左または上の座標を設定すると、ウィンドウはそれぞれ左または上に移動する。これらの座標はウィンドウの幅や高さには影響を与えない。同様に、幅および高さの設定は左および上の座標には影響を与えない。

CBaseControlWindow::GetMaxIdealImageSize

CBaseControlWindow クラス

理想的なイメージの最大サイズを取得する。

構文

HRESULT GetMaxIdealImageSize(
long *pWidth,
long *pHeight
);

パラメータ

pWidth
ピクセル単位の理想的な最大の幅へのポインタ。
pHeight
ピクセル単位の理想的な最大の高さへのポインタ。

戻り値

HRESULT 値を返す。

注意

さまざまなレンダラには、表示できるイメージのサイズについてパフォーマンス上の制限がある。レンダラは指定された最大サイズよりも大きいイメージを表示するように要求された場合でも正しく機能するが、IVideoWindow インターフェイスを使用して、理想的な最小サイズおよび最大サイズを指定できる。このインターフェイスはフィルタ グラフがポーズまたは実行されている場合にのみ呼び出される。これは、このとき初めてリソースが割り当てられ、レンダラがその制限を認識できるからである。制限が存在しない場合は、レンダラは pWidth および pHeight パラメータにネイティブ ビデオのディメンジョンを格納し、S_FALSE を返す。制限が存在する場合は、制限された幅および高さが入力され、このメンバ関数は S_OK を返す。

このディメンジョンは転送先ビデオのサイズに適用され、全体的なウィンドウ サイズには適用されない。したがって、設定するウィンドウのサイズを計算するときは、現在のウィンドウ スタイル (WS_CAPTION や WS_BORDER など) を考慮する必要がある。

CBaseControlWindow::get_MessageDrain

CBaseControlWindow クラス

現在のメッセージ ドレーンを取得する。

構文

HRESULT get_MessageDrain(
OAHWND *Drain
);

パラメータ

Drain
ウィンドウ メッセージを受け取る現在のウィンドウへのポインタ。

戻り値

HRESULT 値を返す。

注意

ビデオ レンダリング フィルタに送信されたメッセージを、別のウィンドウに送信できる。CBaseControlWindow::get_MessageDrain メンバ関数を使用してこのメッセージを受信するように登録されているウィンドウが、現在のメッセージ ドレーンである。

CBaseControlWindow::GetMinIdealImageSize

CBaseControlWindow クラス

理想的なイメージの最小サイズを取得する。

構文

HRESULT GetMinIdealImageSize(
long *pWidth,
long *pHeight
);

パラメータ

pWidth
ピクセル単位の理想的な最小の幅へのポインタ。
pHeight
ピクセル単位の理想的な最小の高さへのポインタ。

戻り値

HRESULT 値を返す。

注意

さまざまなレンダラには、表示できるイメージのサイズについてパフォーマンス上の制限がある。レンダラは指定された最大サイズよりも大きいイメージを表示するように要求された場合でも正しく機能するが、IVideoWindow インターフェイスを使用して、理想的な最小サイズおよび最大サイズを指定できる。このインターフェイスはフィルタ グラフがポーズまたは実行されている場合にのみ呼び出される。これは、このとき初めてリソースが割り当てられ、レンダラがその制限を認識できるからである。 制限が存在しない場合は、レンダラは pWidth および pHeight パラメータにネイティブ ビデオのディメンジョンを格納し、S_FALSE を返す。制限が存在する場合は、制限された幅および高さが入力され、このメンバ関数は S_OK を返す。

このディメンジョンは転送先ビデオのサイズに適用され、全体的なウィンドウ サイズには適用されない。したがって、設定するウィンドウのサイズを計算するときは、現在のウィンドウ スタイル (WS_CAPTION や WS_BORDER など) を考慮する必要がある。

CBaseControlWindow::get_Owner

CBaseControlWindow クラス

現在のウィンドウの所有者を取得する。

構文

HRESULT get_Owner(
OAHWND *Owner
);

パラメータ

Owner
ウィンドウの所有者へのポインタ。

戻り値

HRESULT 値を返す。

注意

ビデオ ウィンドウはドキュメント環境内で再生できる。これを行うには、ウィンドウは別のウィンドウの子でなければならない (ウィンドウを適切にクリップおよび移動するため)。このプロパティによって、ウィンドウの所有者を設定および取得できる。ウィンドウが別のウィンドウによって所有されている場合、そのウィンドウは Microsoft Win32 SetParent 関数を呼び出す。この関数を呼び出すアプリケーションは、ウィンドウ スタイルを変更し、WS_CHILD ビットをオンに設定する。

ウィンドウが別のウィンドウに所有されている場合、特定のメッセージ (具体的にはマウスおよびキーボード メッセージ) を自動的に転送する。これによって、アプリケーションは簡単にホットスポット編集およびその他の相互作用を実行できる。

このメンバ関数は、IVideoWindow インターフェイスを使用して外部オブジェクトによって呼び出されることを想定しているので、関連付けられたフィルタと同期するためにクリティカル セクションをロックする。外部オブジェクトから呼び出さない場合に、このプロパティを取得するには、CBaseControlWindow::GetOwnerWindow メンバ関数を呼び出す。

CBaseControlWindow::GetOwnerWindow

CBaseControlWindow クラス

所有するウィンドウ ハンドル m_hwndOwner を取得する。

構文

HWND GetOwnerWindow(void);

戻り値

所有者ウィンドウを返す内部的なメソッドを返す。

注意

このメンバ関数は、インターフェイス メソッドを呼び出さずに、所有するウィンドウを取得する。IVideoWindow::get_Owner メソッドを使用して外部から呼び出す場合以外は、CBaseControlWindow::get_Owner の代わりにこのメンバ関数を使用する。

CBaseControlWindow::GetRestorePosition

CBaseControlWindow クラス

最大化または最小化しないときに、ウィンドウが復元される位置を取得する。

構文

HRESULT GetRestorePosition(
long *pLeft,
long *pTop,
long *pWidth,
long *pHeight
);

パラメータ

pLeft
最も左の座標の値へのポインタ。
pTop
ウィンドウ上部の値へのポインタ。
pWidth
ウィンドウの幅の値へのポインタ。
pHeight
ウィンドウの高さの値へのポインタ。

戻り値

HRESULT 値を返す。

注意

ウィンドウが最大化または最小化されていない場合、これは CBaseControlWindow::GetWindowPosition 関数によって返される値と同じである。

CBaseControlWindow::get_Top

CBaseControlWindow クラス

上のウィンドウ座標を取得する。

構文

HRESULT get_Top(
long *pTop
);

パラメータ

pTop
ピクセル単位の上の座標へのポインタ。

戻り値

HRESULT 値を返す。

注意

ウィンドウはデスクトップ上に位置座標を持つ。これはピクセル単位の 4 つの座標 (左、上、右、下) によって表される。OLE によって自動化されるインターフェイスでは、通常、左、上、幅、および高さでこの位置座標を表す。これは DirectShow で採用されている規則である。座標はすべてピクセル単位で表され、座標が変更されるとウィンドウが即座に更新される。

左または上の座標を設定すると、ウィンドウはそれぞれ左または上に移動する。これらの座標はウィンドウの幅や高さには影響を与えない。同様に、幅および高さの設定は左および上の座標には影響を与えない。

CBaseControlWindow::get_Visible

CBaseControlWindow クラス

現在のウィンドウの表示の設定を取得する。

構文

HRESULT get_Visible(
long *pVisible
);

パラメータ

pVisible
オートメーション ブール型フラグへのポインタ (0 はオフ、-1 はオン)。

戻り値

HRESULT 値を返す。

注意

このメンバ関数は、ウィンドウが WS_VISIBLE スタイルの場合は -1 を返す。それ以外の場合は 0 を返す。

CBaseControlWindow::get_Width

CBaseControlWindow クラス

現在のウィンドウの幅を取得する。

構文

HRESULT get_Width(
long *pWidth
);

パラメータ

pWidth
ピクセル単位のウィンドウの幅へのポインタ。

戻り値

HRESULT 値を返す。

注意

ウィンドウはデスクトップ上に位置座標を持つ。これはピクセル単位の 4 つの座標 (左、上、右、下) によって表される。OLE によって自動化されるインターフェイスでは、通常、左、上、幅、および高さでこの位置座標を表す。これは DirectShow で採用されている規則である。座標はすべてピクセル単位で表され、座標が変更されるとウィンドウが即座に更新される。

左または上の座標を設定すると、ウィンドウはそれぞれ左または上に移動する。これらの座標はウィンドウの幅や高さには影響を与えない。同様に、幅および高さの設定は左および上の座標には影響を与えない。

CBaseControlWindow::GetWindowPosition

CBaseControlWindow クラス

現在のウィンドウの座標を取得する。

構文

HRESULT GetWindowPosition(
long *pLeft,
long *pTop,
long *pWidth,
long *pHeight
);

パラメータ

pLeft
スクリーン座標での左の座標へのポインタ。
pTop
スクリーン座標での上の座標へのポインタ。
pWidth
スクリーン座標でのウィンドウの幅へのポインタ。
pHeight
スクリーン座標でのウィンドウの高さへのポインタ。

戻り値

HRESULT 値を返す。

CBaseControlWindow::get_WindowState

CBaseControlWindow クラス

現在のウィンドウの状態を取得する。

構文

HRESULT get_WindowState(
long *pWindowState
);

パラメータ

pWindowState
ウィンドウの状態へのポインタ。

戻り値

HRESULT 値を返す。

注意

このメンバ関数は、Microsoft Win32 ShowWindow 関数のパラメータのサブセットを返す。具体的には、現在のウィンドウの表示の設定に基づいて SW_SHOW および SW_HIDE を返す。また、ウィンドウがアイコン化されているか、最大化されているかに応じて、SW_MINIMIZE および SW_MAXIMIZE を返す。

CBaseControlWindow::get_WindowStyle

CBaseControlWindow クラス

標準ウィンドウ スタイルを取得する。

構文

HRESULT get_WindowStyle(
long *pWindowStyle
);

パラメータ

pWindowStyle
ウィンドウ スタイルへのポインタ。

戻り値

HRESULT 値を返す。

注意

このメンバ関数は、WS_CHILD および WS_VISIBLE などの標準ウィンドウ スタイルを返す。このメンバ関数は、CBaseControlWindow::DoGetWindowStyle メンバ関数を呼び出す。

CBaseControlWindow::get_WindowStyleEx

CBaseControlWindow クラス

拡張ウィンドウ スタイルを取得する。

構文

HRESULT get_WindowStyleEx(
long *pWindowStyleEx
);

パラメータ

pWindowStyleEx
拡張ウィンドウ スタイルへのポインタ。

戻り値

HRESULT 値を返す。

注意

このメンバ関数は、拡張ウィンドウ スタイルを取得する。このメンバ関数は、CBaseControlWindow::DoGetWindowStyle メンバ関数を呼び出す。

CBaseControlWindow::HideCursor

CBaseControlWindow クラス

カーソルの表示/非表示を切り替える。

構文

HRESULT HideCursor(
long HideCursor
);

パラメータ

HideCursor
カーソルを表示するかどうかを指定する値。カーソルを非表示にする場合は OATRUE に、カーソルを表示する場合は OAFALSE に設定する。

戻り値

HRESULT 値を返す。

CBaseControlWindow::IsCursorHidden

CBaseControlWindow クラス

m_bCursorHidden データ メンバの現在の状態を取得する。

構文

HRESULT IsCursorHidden(
long *CursorHidden
);

BOOL IsCursorHidden(void);

パラメータ

CursorHidden
m_bCursorHidden の値へのポインタ。

戻り値

パラメータを指定せずに呼び出した場合、カーソルが非表示の場合は OATRUE、カーソルが表示されている場合は OAFALSE を返す。

パラメータを指定して呼び出した場合は、HRESULT 値を返す。

注意

内部オブジェクトは、クリティカル セクションをロックしないように、CursorHidden パラメータを指定せずにこのメンバ関数を呼び出さなければならない。外部オブジェクトは、IVideoWindow::IsCursorHidden メソッドを使ってこのメンバ関数にアクセスする。

CBaseControlWindow::IsAutoShowEnabled

CBaseControlWindow クラス

レンダリング フィルタがポーズまたは実行されたときに、ビデオ ウィンドウが自動的に表示されるかどうかについての情報を取得する。

構文

BOOL IsAutoShowEnabled(void);

戻り値

m_bAutoShow メンバが -1 に設定されている場合は TRUE、0 に設定されている場合は FALSE を返す。

注意

非表示のビデオ ウィンドウについて m_bAutoShow メンバが -1 に設定されている場合、フィルタがポーズまたは実行されるとウィンドウが表示される。このメンバが 0 に設定されている場合、適切なパラメータを指定して CBaseControlWindow::put_Visible または CBaseControlWindow::put_WindowState を呼び出したときにのみウィンドウが表示される。

このメンバ関数は、m_bAutoShow メンバの設定を取得する。その結果は、IVideoWindow::get_AutoShow メソッドを使用した場合と同じである。

CBaseControlWindow::NotifyOwnerMessage

CBaseControlWindow クラス

特定のメッセージをビデオ ウィンドウに渡す。

構文

HRESULT NotifyOwnerMessage(
long hwnd,
long uMsg,
long wParam,
long lParam
);

パラメータ

hwnd
ビデオ ウィンドウのハンドル。
uMsg
メッセージの詳細。
wParam
最初のメッセージ パラメータ。
lParam
2 番目のメッセージ パラメータ。

戻り値

NO_ERROR を返す。

注意

ビデオ ウィンドウが別のウィンドウの子である場合、ビデオ ウィンドウは特定の最上位ウィンドウのメッセージを受信しない。このようなメッセージはレンダラの動作に影響する場合があるので、レンダラにとって有用なことがある。NotifyOwnerMessage は、以下のメッセージをビデオ ウィンドウに渡す。

  • WM_ACTIVATEAPP
  • WM_DEVMODECHANGE
  • WM_DISPLAYCHANGE
  • WM_PALETTECHANGED
  • WM_PALETTECHANGED
  • WM_QUERYNEWPALETTE
  • WM_SYSCOLORCHANGE

IVideoWindow PID に要求して、ウィンドウを別のウィンドウの子にすることができる。この場合、PID は所有するウィンドウに送信された特定のメッセージを検索する。次に、PID はこれらのメッセージを所有されるウィンドウに転送する。このメッセージのデフォルトの処理では、Win32 SendMessage 関数を呼び出して、所有されるウィンドウのプロシージャに同期的にメッセージが送信される。

CBaseControlWindow::PossiblyEatMessage

CBaseControlWindow クラス

キーボードおよびマウス メッセージを指定されたウィンドウに転送する。

構文

BOOL WINAPI PossiblyEatMessage(
HWND hwndDrain,
UINT uMsg,
WPARAM wParam,
LPARAM lParam
    )

パラメータ

hwndDrain
メッセージが転送されるウィンドウのハンドル。
uMsg
転送されるメッセージ。
wParam
最初のメッセージ パラメータ。
lParam
2 番目のメッセージ パラメータ。

戻り値

メッセージが送信された場合は TRUE、送信されなかった場合は FALSE を返す。

注意

ウィンドウが所有されている場合、このウィンドウは特定のクラスのメッセージ (キーボードおよびマウス メッセージ) を所有するウィンドウに渡す。この場合、Win32 PostMessage 関数を呼び出して、CBaseControlWindow::put_MessageDrain で設定された hwndDrain で指定されているウィンドウにメッセージを送信する。特定のメッセージを送信できない場合、このメッセージは FALSE を返す。

未変換のまま渡されて、TRUE を返すメッセージの一覧を以下に示す。
WM_CHAR | WM_DEADCHAR
WM_KEYDOWN | WM_KEYUP
WM_LBUTTONDBLCLK | WM_LBUTTONDOWN
WM_LBUTTONUP | WM_LBUTTONDBLCLK
WM_MBUTTONDOWN | WM_LBUTTONUP
WM_MOUSEACTIVATE | WM_MOUSEMOVE
WM_NCHITTEST | WM_NCLBUTTONDBLCLK
WM_NCLBUTTONDOWN | WM_NCLBUTTONUP
WM_NCMBUTTONDBLCLK | WM_NCMBUTTONDOWN
WM_NCMBUTTONUP | WM_NCMOUSEMOVE
WM_NCRBUTTONDBLCLK | WM_NCRBUTTONDOWN
WM_NCRBUTTONUP | WM_RBUTTONDBLCLK
WM_RBUTTONDOWN | WM_RBUTTONUP
WM_SYSCHAR | WM_SYSDEADCHAR
WM_SYSKEYDOWN | WM_SYSKEYUP

CBaseControlWindow::put_AutoShow

CBaseControlWindow クラス

AutoShow 状態フラグを設定する。

構文

HRESULT put_AutoShow(
long AutoShow
);

パラメータ

AutoShow
オートメーション ブール型フラグ (0 はオフ、-1 はオン)。

戻り値

HRESULT 値を返す。

注意

このプロパティは、アプリケーションのウィンドウ表示アクセスを簡素化する。このプロパティが -1 (オン) に設定されている場合、通常フィルタの接続後は非表示になっているウィンドウは、フィルタがポーズまたは実行されると自動的に表示される。ただし、フィルタが停止した場合、ウィンドウを非表示にするべきではない。このパラメータが 0 (オフ) に設定されている場合、アプリケーションが適切なパラメータを指定して CBaseControlWindow::put_Visible または CBaseControlWindow::put_WindowState を呼び出したときにのみウィンドウが表示される。

CBaseControlWindow::put_BackgroundPalette

CBaseControlWindow クラス

バックグラウンドでパレットを実現するためのフラグを設定する。

構文

HRESULT put_BackgroundPalette(
long BackgroundPalette
);

パラメータ

BackgroundPalette
オートメーション ブール型フラグ (0 はオフ、-1 はオン)。

戻り値

HRESULT 値を返す。

注意

ビデオを別のアプリケーションまたはドキュメントで再生するために、そのアプリケーションで独自のパレットを使いたいことがある。このフラグを -1 に設定することによって、アプリケーションはビデオのバックグラウンド パレットとして、独自のパレットではなく現在のフォアグラウンド パレットを使用することを要求できる。このフラグが 0 に設定されている場合、ウィンドウは独自の優先パレットをインストールして実現する。ウィンドウで別のパレットを使用するように指定すると、パフォーマンスが大幅に低下する。

CBaseControlWindow::put_BorderColor

CBaseControlWindow クラス

境界のカラーを変更する。

構文

HRESULT put_BorderColor(
long Color
);

パラメータ

Color
新しい境界のカラー。

戻り値

HRESULT 値を返す。

注意

アプリケーションはビデオを表示する転送先矩形を設定できる。この矩形は、ウィンドウのクライアント領域に比例する。転送先矩形を設定した場合 (デフォルトでは常にウィンドウ全体が描画される)、ビデオの周囲に境界が表示される。このプロパティは、境界で使用されるカラーに影響する。このパラメータは LONG 型として指定されているが、実際には COLORREF 値である。

CBaseControlWindow::put_Caption

CBaseControlWindow クラス

ウィンドウ タイトルまたはキャプションを設定する。

構文

HRESULT put_Caption(
BSTR strCaption
);

パラメータ

strCaption
新しいウィンドウ キャプション。

戻り値

HRESULT 値を返す。

注意

Windows ベースのデスクトップ上の最上位ウィンドウには、タイトル (キャプション) が関連付けられる。このプロパティは、IVideoWindow インターフェイスを使用して問い合わせおよび設定することができる。設定されたキャプションは、ウィンドウに WS_CAPTION スタイルが適用されている場合にのみ表示される。このスタイルが適用されていない場合、ユーザーに対しては表示されないが、キャプションは設定 (および取得) できる。

CBaseControlWindow::put_FullScreenMode

CBaseControlWindow クラス

レンダラのフルスクリーン モードを設定する。

構文

HRESULT put_FullScreenMode(
long FullScreenMode
);

パラメータ

FullScreenMode
適用するフルスクリーン モード。

戻り値

HRESULT 値を返す。現在の実装は E_NOTIMPL を返す。

注意

フルスクリーン モードを実装するビデオ レンダラは、このメンバ関数をオーバーライドして、サポートするモードを実装する。

CBaseControlWindow::put_Height

CBaseControlWindow クラス

ウィンドウの高さを設定する。

構文

HRESULT put_Height(
long Height
);

パラメータ

Height
ピクセル単位の新しいウィンドウの高さ。

戻り値

HRESULT 値を返す。

注意

ウィンドウはデスクトップ上に位置座標を持つ。これはピクセル単位の 4 つの座標 (左、上、右、下) によって表される。OLE によって自動化されるインターフェイスでは、通常、左、上、幅、および高さでこの位置座標を表す。これは DirectShow で採用されている規則である。座標はすべてピクセル単位で表され、座標が変更されるとウィンドウが即座に更新される。

左または上の座標を設定すると、ウィンドウはそれぞれ左または上に移動する。これらの座標はウィンドウの幅や高さには影響を与えない。同様に、幅および高さの設定は左および上の座標には影響を与えない。

CBaseControlWindow::put_Left

CBaseControlWindow クラス

ウィンドウの左の座標を設定する。

構文

HRESULT put_Left(
long Left
);

パラメータ

Left
ピクセル単位の新しい左の座標。

戻り値

HRESULT 値を返す。

注意

ウィンドウはデスクトップ上に位置座標を持つ。これはピクセル単位の 4 つの座標 (左、上、右、下) によって表される。OLE によって自動化されるインターフェイスでは、通常、左、上、幅、および高さでこの位置座標を表す。これは DirectShow で採用されている規則である。座標はすべてピクセル単位で表され、座標が変更されるとウィンドウが即座に更新される。

左または上の座標を設定すると、ウィンドウはそれぞれ左または上に移動する。これらの座標はウィンドウの幅や高さには影響を与えない。同様に、幅および高さの設定は左および上の座標には影響を与えない。

CBaseControlWindow::put_MessageDrain

CBaseControlWindow クラス

ビデオ レンダラに送信されたウィンドウ メッセージを受信するウィンドウを設定する。

構文

HRESULT put_MessageDrain(
OAHWND Drain
);

パラメータ

Drain
メッセージの送信先のウィンドウ。

戻り値

HRESULT 値を返す。

注意

ビデオ レンダリング フィルタに送信されたメッセージを、別のウィンドウに送信できる。このメンバ関数は、このようなメッセージを受信するウィンドウを登録する。CBaseControlWindow::put_Owner メンバ関数とは異なり、このメンバ関数はビデオ ウィンドウを別のウィンドウの子にしない。このメンバ関数は、子ウィンドウにすることができないフルスクリーン ビデオ レンダラで特に有用である。

CBaseControlWindow::put_Owner

CBaseControlWindow クラス

ビデオ ウィンドウの親ウィンドウを設定する。この親ウィンドウは特定のメッセージをビデオ ウィンドウに転送する。

構文

HRESULT put_Owner(
OAHWND Owner
);

パラメータ

Owner
親ウィンドウのハンドル。

戻り値

NOERROR を返す。

注意

内部的には、このメソッドは Microsoft Win32 SetParent 関数を呼び出して新しい所有者を設定し、ウィンドウのスタイルを WS_CHILD に設定する。この親ウィンドウは特定のメッセージ (具体的にはマウスおよびキーボード メッセージ) をビデオ ウィンドウに転送する。

ビデオ ウィンドウの所有者を設定した後、フィルタ グラフを解放する前に、所有者を NULL に設定し、所有者のウィンドウ スタイルを WS_OVERLAPPED および WS_CLIPCHILDREN に設定しなければならない。所有者を NULL に設定すると、このメソッドは親ウィンドウの WS_CHILD ビットをオフにする。所有者を NULL に設定しない場合、親ウィンドウはメッセージをビデオ ウィンドウに渡し続けるので、アプリケーションを終了したときにエラーが発生する可能性がある。

CBaseControlWindow::put_Top

CBaseControlWindow クラス

上のウィンドウ座標を設定する。

構文

HRESULT put_Top(
long Top
);

パラメータ

Top
ピクセル単位の新しい上の座標。

戻り値

HRESULT 値を返す。

注意

ウィンドウはデスクトップ上に位置座標を持つ。これはピクセル単位の 4 つの座標 (左、上、右、下) によって表される。OLE によって自動化されるインターフェイスでは、通常、左、上、幅、および高さでこの位置座標を表す。これは DirectShow で採用されている規則である。座標はすべてピクセル単位で表され、座標が変更されるとウィンドウが即座に更新される。

左または上の座標を設定すると、ウィンドウはそれぞれ左または上に移動する。これらの座標はウィンドウの幅や高さには影響を与えない。同様に、幅および高さの設定は左および上の座標には影響を与えない。

CBaseControlWindow::put_Visible

CBaseControlWindow クラス

ウィンドウを表示または非表示にする。

構文

HRESULT put_Visible(
long Visible
);

パラメータ

Visible
オートメーション ブール型フラグ (0 の場合、ウィンドウは非表示。-1 の場合、ウィンドウは表示される)。

戻り値

HRESULT 値を返す。

CBaseControlWindow::put_Width

CBaseControlWindow クラス

ウィンドウの幅を設定する。

構文

HRESULT put_Width(
long Width
);

パラメータ

Width
ピクセル単位の新しいウィンドウの幅。

戻り値

HRESULT 値を返す。

注意

ウィンドウはデスクトップ上に位置座標を持つ。これはピクセル単位の 4 つの座標 (左、上、右、下) によって表される。OLE によって自動化されるインターフェイスでは、通常、左、上、幅、および高さでこの位置座標を表す。これは DirectShow で採用されている規則である。座標はすべてピクセル単位で表され、座標が変更されるとウィンドウが即座に更新される。

左または上の座標を設定すると、ウィンドウはそれぞれ左または上に移動する。これらの座標はウィンドウの幅や高さには影響を与えない。同様に、幅および高さの設定は左および上の座標には影響を与えない。

CBaseControlWindow::put_WindowState

CBaseControlWindow クラス

ウィンドウの状態を設定する。

構文

HRESULT put_WindowState(
long WindowState
);

パラメータ

WindowState
新しいウィンドウの状態。

戻り値

HRESULT 値を返す。

注意

このメンバ関数は、Microsoft Win32 ShowWindow 関数と同じパラメータ (WS_SHOWNORMAL、WS_SHOWMINNOACTIVATE、および WS_SHOWMAXIMIZED など) を取る。

CBaseControlWindow::put_WindowStyle

CBaseControlWindow クラス

標準的な Windows ベースのスタイルを設定する。

構文

HRESULT put_WindowStyle(
long WindowStyle
);

パラメータ

WindowStyle
新しいウィンドウのスタイル。

戻り値

HRESULT 値を返す。

注意

ウィンドウ スタイルを変更する場合は注意が必要である。ほとんどの場合、アプリケーションは現在のスタイルを取得して、ビットを追加または不適切なビットを削除しなければならない。この手順によって、Windows® によって使用されるさまざまな内部ウィンドウ スタイルをそのままにしておくことができる。

CBaseControlWindow::put_WindowStyleEx

CBaseControlWindow クラス

コントロール ウィンドウのスタイルを設定する。

構文

HRESULT put_WindowStyleEx(
long WindowStyleEx
);

パラメータ

WindowStyleEx
[in] コントロール ウィンドウのスタイルを設定する値。

戻り値

NOERROR を返す。

注意

このメソッドは、EX (拡張) ウィンドウ スタイルを使用する。拡張ウィンドウ スタイルの詳細については、Microsoft Win32 の関数「CreateWindowEx」を参照すること。ウィンドウ スタイルを変更するには、現在のウィンドウ スタイルを取得し、次に必要なビット フィールドを追加または削除する。

以下のウィンドウ スタイルは有効ではないので、使用してはならない。

  • WS_DISABLED
  • WS_HSCROLL
  • WS_ICONIC
  • WS_MAXIMIZE
  • WS_MINIMIZE
  • WS_HSCROLL

ここに示されている一部の例外を除いて、使用可能なフラグは Win32 CreateWindow 関数で使用できるフラグと同じである。

CBaseControlWindow::SetControlWindowPin

CBaseControlWindow クラス

同期しなければならないピンを設定する。

構文

void SetControlWindowPin(
CBasePin *pPin
);

パラメータ

pPin
インターフェイスが同期するピンへのポインタ。

戻り値

戻り値なし。

注意

このメンバ関数は、m_pPin 変数を pPin パラメータに等しくなるように設定する。コンストラクタで説明したように、このインターフェイスは、フィルタが正常に接続された場合にのみ呼び出すことができる。オブジェクトは、このメンバ関数によって同期されるピンに渡される。ほとんどの場合、インターフェイス メソッドが呼び出されたときにピンが接続されているかどうかを判断し、失敗した場合は VFW_E_NOT_CONNECTED を返す。

CBaseControlWindow::SetWindowForeground

CBaseControlWindow クラス

ビデオ ウィンドウをフォアグラウンドに移動し、オプションでフォーカスを与える。

構文

HRESULT SetWindowForeground(
long Focus
);

パラメータ

Focus
ビデオ ウィンドウがフォーカスを受け取るかどうかを指定する値。値が -1 の場合、ウィンドウにフォーカスが与えられる。0 の場合、フォーカスは与えられない。

戻り値

次のいずれかの値を返す。
NOERROR | メソッドが成功した。
E_INVALIDARG | Focus が -1 または 0 ではない。
VFW_E_NOT_CONNECTED | 現在のフィルタが、完全なフィルタ グラフに接続されていない。

CBaseControlWindow::SetWindowPosition

CBaseControlWindow クラス

デスクトップ上のウィンドウの位置を設定する。

構文

HRESULT SetWindowPosition(
long Left,
long Top,
long Width,
long Height
);

パラメータ

Left
新しい左の座標。
Top
新しい上の座標。
Width
ウィンドウの幅。
Height
ウィンドウの高さ。

戻り値

HRESULT 値を返す。


CBaseDispatch クラス

IDispatch インターフェイスを実装する基底クラス。

宣言 : Ctlutil.h

このクラスは DirectShow タイプ ライブラリが公開するオートメーション互換インターフェイス QuartzTypeLib のサポートに限定されている。たとえば、CMediaControl と CMediaPosition クラスは CBaseDispatch を使用してそれぞれ IMediaControl と IMediaPosition を実装する。この制限により、CBaseDispatch を自身のフィルタを直接使用する理由はない。

このクラスを使うには、次のようにする :

  • IDispatch をサポートする新しいクラスを宣言。
  • CBaseDispatch タイプのプライベート メンバ 変数を新しいクラスに与える。
  • IDispatch メソッドを実装。IDispatch メソッド内で、CBaseDispatch メソッドを呼び出す。

詳細については、Ctlutil.h に宣言されているサンプル クラスのソースコードを参照すること。

IDispatch メソッドの詳細については、Microsoft® Platform SDK に含まれる COM ドキュメントを参照すること。

Public メソッド
CBaseDispatch | コンストラクタ メソッド。
~CBaseDispatch | デストラクタ メソッド。
GetIDsOfNames | DISPID に対応する一連の名前のマップ。
GetTypeInfo | オブジェクトのタイプ情報を取得、これはインターフェイスのタイプ情報を次に取得する際に用いられる。
GetTypeInfoCount | オブジェクトが提供するタイプ情報インターフェイスの数を取得。

CBaseDispatch::CBaseDispatch

CBaseDispatch クラス

コンストラクタ メソッド。

構文

CBaseDispatch(void);

CBaseDispatch::~CBaseDispatch

CBaseDispatch クラス

デストラクタ メソッド。

構文

~CBaseDispatch(void);

CBaseDispatch::GetIDsOfNames

CBaseDispatch クラス

DISPID に対応する一連の名前のマップ。

構文

HRESULT GetIDsOfNames(
    REFIID riid,
    OLECHAR **rgszNames,
    UINT cNames,
    LCID lcid,
    DISPID *rgdispid
);

パラメータ

riid
インターフェイスを指定するインターフェイスID (IID) への参照。
rgszNames
マップされる名前を含むワイド文字列のアドレス。
cNames
rgszNames パラメータによって与えられる配列のサイズ。
lcid
名前を解釈するロケール コンテキスト。NULL が有効。
rgdispid
DISPID を取得する配列のポインタ。取得した各要素は rgszNames パラメータに渡された各名前に対応する ID。

戻り値

HRESULT 値を返す。次のいずれかを含む。

S_OK | 成功。
E_OUTOFMEMORY | メモリ不足。
DISP_E_UNKNOWNNAME | 1 つあるいはそれ以上の名前が不明だった。O

注意

このメソッドは IDispatch::GetIDsOfNames メソッドと同じように動作するが、riid パラメータに DISPID を取得するインターフェイスを指定する。(IDispatch 版では、riid は未使用。)

このメソッドが DISP_E_UNKNOWNNAME を返すとき、返った DISPID は道の名前に対応するエントリーとして DISPID_UNKNOWN を含む。

CBaseDispatch::GetTypeInfo

CBaseDispatch クラス

オブジェクトのタイプ情報を取得、これはインターフェイスのタイプ情報を次に取得する際に用いられる。

構文

HRESULT GetTypeInfo(
    REFIID riid,
    UINT itinfo,
    LCID lcid,
    ITypeInfo **pptinfo
);

パラメータ

riid
インターフェイスを指定するインターフェイス ID (IID) への参照。
itinfo
返すインターフェイス情報。必ずゼロ。
lcid
ロケール ID。
pptinfo
ITypeInfo ポインタを取得する変数のアドレス。

戻り値

HRESULT 値を返す。次のいずれかを含む。

S_OK | 成功。
E_POINTER | Null ポインタ引数。
TYPE_E_ELEMENTNOTFOUND | itinfo パラメータがゼロではない。

注意

このメソッドは IDispatch::GetTypeInfo メソッドと同じように動作する。しかし riid パラメータが追加されている、これには取得するタイプ情報のインターフェイスを指定する。

CBaseDispatch::GetTypeInfoCount

CBaseDispatch クラス

オブジェクトが提供するタイプ情報インターフェイスの数を取得。

構文

HRESULT GetTypeInfoCount(
    UINT *pctinfo
);

パラメータ

pctinfo
オブジェクトが提供するタイプ情報インターフェイスの数を取得する変数へのポインタ。このメソッドが返ったとき、この値は 1 。

戻り値

次の 1 つが返る。

S_OK | 成功。
E_POINTER | NULL ポインタ引数。


CBaseFilter クラス

フィルタを実装するための抽象クラス。

宣言 : Amfilter.h

CBaseFilter を使用してフィルタを実装するには、最低限次のステップを実行しなければならない :

  • CBaseFilter から新しいクラスを派生する。
  • フィルタのピンを定義するメンバ変数をインクルードする。このピンは CBasePin クラスからから与えられなければならない。
  • フィルタのピンを取得する純粋仮想メソッド GetPin をオーバーライドする。
  • ピンの数を取得する純粋仮想メソッド GetPinCount をオーバーライドする。
  • メディア サンプルの生成、処理、レンダリング メソッドを提供する。

CSource や CBaseRenderer や CTransformFilter を含むいくつかの基底クラスが CBaseFilter から派生される。通常 CBaseFilter を使用するより、これらのクラスの 1 つを指定してフィルタを実装する方が容易である。

Protected メンバ変数
m_State | フィルタの現在の状態。
m_pClock | フィルタの基準クロックへのポインタ。
m_tStart | ストリームタイム ゼロに対応した基準クロック。
m_clsid | フィルタのクラス ID (CLSID)。
m_pLock | クリティカル セクションへのポインタ。
m_pName | フィルタ名。
m_pGraph | フィルタ グラフ マネージャへのポインタ。
m_pSink | フィルタ グラフ マネージャの IMediaEventSink インターフェイスへのポインタ。
m_PinVersion | このフィルタの一連のピンの現在のバージョン。
Public メソッド
CBaseFilter | コンストラクタ メソッド。
~CBaseFilter | デストラクタ メソッド。
StreamTime | 現在のストリーム タイムを取得。仮想。
IsActive | フィルタが現時アクティブかどうか(実行中かポーズが)を決定。
IsStopped | フィルタが現在停止しているかどうかを決定。
NotifyEvent | イベント通知をフィルタグラフマネージャに送る。
GetFilterGraph | フィルタ グラフ マネージャへのポインタを取得。
ReconnectPin | 既存のピン接続を壊し、指定したメディアピンを使って、同じピンにそれを再接続する。
GetPinVersion | このフィルタの一連のピンのバージョン数を取得。仮想。
IncrementPinVersion | 一連のピンのバージョン数をインクリメント。
GetSetupData | フィルタについての登録データを取得。仮想。
Pure Virtual メソッド
GetPinCount | ピンの数を取得。
GetPin | ピンを取得。
IPersist メソッド
GetClassID | クラス ID を取得。
IMediaFilter メソッド
GetState | フィルタの状態(実行中かポーズか)を取得。
SetSyncSource | フィルタの基準クロックをセット。
GetSyncSource | フィルタが使用している基準クロックを取得。
Stop | フィルタを停止。
Pause | フィルタをポーズ。
Run | フィルタを実行。
IBaseFilter メソッド
EnumPins | フィルタのピンを列挙する。
FindPin | 指定した ID のフィルタを取得する。
QueryFilterInfo | フィルタについての情報を取得する。
JoinFilterGraph | フィルタにフィルタ グラフに参加した、あるいはフィルタ グラフを離れたことを通知する。
QueryVendorInfo | ベンダー情報を含む文字列を取得。
IAMovieSetup メソッド
Register | レジストリにフィルタを追加。
Unregister | レジストリからフィルタを削除。

CBaseFilter.m_State

CBaseFilter クラス

フィルタの現在の状態。

構文

FILTER_STATE m_State;

CBaseFilter.m_pClock

CBaseFilter クラス

フィルタの基準クロックへのポインタ。

構文

IReferenceClock *m_pClock;

CBaseFilter.m_tStart

CBaseFilter クラス

ストリーム タイム 0 に対応した基準クロック。

構文

CRefTime m_tStart;

CBaseFilter.m_clsid

CBaseFilter クラス

フィルタのクラス ID (CLSID)。

構文

CLSID m_clsid;

CBaseFilter.m_pLock

CBaseFilter クラス

クリティカル セクションへのポインタ。

構文

CCritSec *m_pLock;

注意

状態移行中あるいはあるメソッドが複数の操作でその状態にアクセスしているとき、このクリティカル セクションを保持する。基底クラスでは以下のメソッドでクリティカル セクションを保持する :

  • FindPin
  • GetSyncSource
  • JoinFilterGraph
  • IsActive
  • SetSyncSource
  • Pause
  • Run
  • Stop

ストリーミング操作(すなわち、サンプルをストリーミング フィルタに出力している)とき、このクリティカル セクションを保持しては ならない 。異なったクリティカル セクションを使ってストリームング操作を継続する。そうしないと、デッドロックが起こりうる。

CBaseFilter.m_pName

CBaseFilter クラス

フィルタ名。

構文

WCHAR *m_pName;

CBaseFilter.m_pGraph

CBaseFilter クラス

フィルタ グラフ マネージャへのポインタ。

構文

IFilterGraph *m_pGraph;

CBaseFilter.m_pSink

CBaseFilter クラス

フィルタ グラフ マネージャの IMediaEventSink インターフェイスへのポインタ。

構文

IMediaEventSink *m_pSink;

CBaseFilter.m_PinVersion

CBaseFilter クラス

このフィルタの一連のピンの現在のバージョン。 詳細については、「GetPinVersion」を参照すること。

構文

LONG m_PinVersion;

CBaseFilter::CBaseFilter

CBaseFilter クラス

コンストラクタ メソッド。

構文

CBaseFilter(
    const TCHAR *pName,
    LPUNKNOWN pUnk,
    CCritSec *pLock,
    REFCLSID clsid
);

パラメータ

pName
デバッグ目的で使用する、フィルタの名前を含む文字列へのポインタ。
pUnk
オブジェクトの所有者へのポインタ。このオブジェクトが集成されているなら、集成されたオブジェクトの IUnknown インターフェイスを渡す。それ以外ではこのパラメータを NULL に設定する。
pLock
状態変化を継続する CCritSec ロックへのポインタ。
clsid
オブジェクトのクラス ID。

注意

クリティカル セクション オブジェクトについては、通常次のどちらかを行う :

  • CBaseFilter と CCritSec の両方を与えるクラスを派生。pLock に this ポインタを渡す。
  • CBaseFilter を与え、CCritSec メンバ変数を含むクラスを派生。pLock にはその変数のアドレスを渡す。

CBaseFilter::~CBaseFilter

CBaseFilter クラス

デストラクタ メソッド。

構文

CBaseFilter(void);

注意

削除する前にフィルタを必ず停止させること。

CBaseFilter::EnumPins

CBaseFilter クラス

フィルタのピンを列挙する。IBaseFilter::EnumPins メソッドの実装。

構文

HRESULT EnumPins(
    IEnumPins **ppEnum
);

パラメータ

ppEnum
IEnumPins インターフェイスへのポインタを取得する変数のアドレス。

戻り値

次の HRESULT 値の 1 つを返す。

S_OK | 成功。
E_OUTOFMEMORY | メモリ不足。
E_POINTER | NULL ポインタ引数。

注意

このメソッドは CEnumPins 基底クラスのインターフェイスを作成し、IEnumPins タイプのそのオブジェクトのポインタを返す。このメソッドが成功すると、IEnumPins インターフェイスは未処理の参照カウントを持つ。解放時には注意が必要である。

CBaseFilter::FindPin

CBaseFilter クラス

指定した ID でピンを取得。IBaseFilter::FindPin メソッドの実装。

構文

HRESULT FindPin(
    LPCWSTR Id,
    IPin **ppPin
);

パラメータ

Id
ピンを識別する定数、NULL で終わる Unicode™ 文字列のポインタ。
ppPin
ピンの IPin インターフェイスへのポインタを取得する変数のアドレス。

戻り値

次の HRESULT 値の 1 つを返す。

S_OK | 成功。
E_POINTER | NULL ポインタ引数。
VFW_E_NOT_FOUND | 適合するピンを見つけられなかった。

注意

このメソッドは CBasePin::Name メソッドを呼び出し、各ピンの名前と Id パラメータが示す文字列とを比較する。

このメソッドが成功すると、IEnumPins インターフェイスは未処理の参照カウントを持つ。解放時には注意が必要である。

CBaseFilter::GetClassID

CBaseFilter クラス

クラス ID を取得。IPersist::GetClassID メソッドの実装。

構文

HRESULT GetClassID(
    CLSID *pClsID
    );

パラメータ

pClsID
クラス ID を取得する変数のポインタ。

戻り値

S_OK あるいは E_POINTER を返す。

CBaseFilter::GetFilterGraph

CBaseFilter クラス

フィルタ グラフ マネージャへのポインタを取得。

構文

IFilterGraph *GetFilterGraph(void);

戻り値

m_pGraph の値を返す。

CBaseFilter::GetPin

CBaseFilter クラス

ピンを取得する。

構文

virtual CBasePin *GetPin(
    int n
) PURE;

パラメータ

n
指定されたピンの数。

戻り値

ピンを実装する CBasePin オブジェクトのポインタを返す。

注意

派生クラスはこの純粋仮想メソッドを実装しなければならない。このフィルタのゼロから始まる n 番目のピンのポインタを返す。

CBaseFilter::GetPinCount

CBaseFilter クラス

ピンの数を取得。

構文

virtual int GetPinCount(void) PURE;

戻り値

ピンの数を返す。

注意

派生クラスはこの純粋仮想メソッドを実装しなければならない。このフィルタで現在有効なピンの数を返す。フィルタは動的にピンを作成、削除できる。

CBaseFilter::GetPinVersion

CBaseFilter クラス

フィルタの一連のピンのバージョン数を取得。

構文

virtual long GetPinVersion(void);

戻り値

m_PinVersion メンバ変数を返す。

注意

CBaseFilter コンストラクタはピン バージョンを 1 で初期化する。基底クラスでは、この数は変化しない。フィルタが動的にピンを作成、削除するとき、ピンが替わるたびにピン バージョンをインクリメントするべきである。バージョン数をインクリメントするには、IncrementPinVersion メソッドを呼び出すこと。

CEnumPins クラスによって実装されるピン列挙オブジェクトはピンバージョンを使って、そのフィルタとの同期を取る。

CBaseFilter::GetSetupData

CBaseFilter クラス

フィルタの登録データを取得。

注意 このメソッドは現在使われていない。Register と Unregister メソッドによって呼び出される。

構文

virtual LPAMOVIESETUP_FILTER GetSetupData(void);

戻り値

フィルタの登録情報を含む AMOVIESETUP_FILTER 構造体へのポインタを返す。

注意

基底クラスは NULL を返す。

CBaseFilter::GetState

CBaseFilter クラス

フィルタの状態(実行中かポーズか)を取得。 IMediaFilter::GetState メソッドの実装。

構文

HRESULT GetState(
    DWORD dwMilliSecsTimeout,
    FILTER_STATE *State
);

パラメータ

dwMilliSecsTimeout
タイムアウト間隔、ミリ秒。
State
フィルタの状態を示す FILTER_STATE 列挙型のメンバを取得する変数のポインタ。

戻り値

S_OK あるいは E_POINTER を返す。

注意

基底クラスでは、すべての状態移行は同期され、dwMilliSecsTimeout パラメータは無視される。派生クラスが状態移行を同期するには、このメソッドをオーバーライドし、dwMilliSecsTimeout ミリ秒のタイムアウトの間、状態移行を待つべきだ。

CBaseFilter::GetSyncSource

CBaseFilter クラス

フィルタが使用している基準クロックを取得。IMediaFilter::GetSyncSource メソッドの実装。

構文

HRESULT GetSyncSource(
    IReferenceClock **pClock
    );

パラメータ

pClock
クロックの IReferenceClock インターフェイスのポインタを取得する変数のアドレス。

戻り値

S_OK あるいは E_POINTER を返す。

注意

フィルタが基準クロックを使っている場合、*pClock には NULL がセットされる。このメソッドが返ったとき、*pClock が NULL 以外なら、IReferenceClock インターフェイスが未処理の参照カウントを持つ。その解放時には注意が必要である。

CBaseFilter::IncrementPinVersion

CBaseFilter クラス

一連のピンのバージョン数をインクリメント。

構文

void IncrementPinVersion(void);

注意

このメソッドは m_PinVersion メンバ変数をインクリメントする。フィルタが動的にピンを作成、削除するさい、ピンが変更されるたびにこのメソッドを呼び出すこと。詳細については、「GetPinVersion」を参照すること。

CBaseFilter::IsActive

CBaseFilter クラス

フィルタが現在アクティブ(実行中あるいはポーズ)かどうかを決定する。

構文

BOOL IsActive(void);

戻り値

フィルタがポーズあるいは実行中のとき TRUE を返し、停止しているとき FALSE を返す。

CBaseFilter::IsStopped

CBaseFilter クラス

フィルタが現在停止しているかどうかを決定。

構文

BOOL IsStopped(void);

戻り値

フィルタが停止しているとき TRUE を返し、それ以外なら FALSE を返す。

CBaseFilter::JoinFilterGraph

CBaseFilter クラス

フィルタにフィルタグラフに参加した、あるいは離れたことを通知する。IBaseFilter::JoinFilterGraph メソッドの実装。

構文

HRESULT JoinFilterGraph(
    IFilterGraph *pGraph,
    LPCWSTR pName
);

パラメータ

pGraph
フィルタ グラフ マネージャの IFilterGraph インターフェイスのポインタ、フィルタが離れたときは NULL 。
pName
フィルタ名を含む Unicode 文字列の [in, string] ポインタ。

戻り値

S_OK を返す。

注意

このメソッドは m_pGraph メンバ変数を pGraph に等しく設定する。IMediaEventSink インターフェイス ポインタをもクエリし、m_pSink メンバ変数に保存する。しかし、このフィルタはこれらのインターフェイスの参照カウントを保持しない。フィルタ グラフ マネージャはフィルタの参照カウントを保持するので、この操作は繰り返し参照カウントを作成することになる。

このメソッドは pName によって指定された文字列を m_pName メンバ変数にコピーする。

CBaseFilter::NotifyEvent

CBaseFilter クラス

フィルタ グラフ マネージャにイベント通知を送る。

構文

HRESULT NotifyEvent(
    long EventCode,
    LONG_PTR EventParam1,
    LONG_PTR EventParam2
);

パラメータ

EventCode
イベント通知コード。
EventParam1
イベントの最初のパラメータ。
EventParam2
イベントの 2 つ目のパラメータ。

戻り値

HRESULT 値を返す。次の表は、可能な値を示している。

S_FALSE | フィルタ グラフ マネージャはイベント通知を受け取っていない。
S_OK | 成功。
E_NOTIMPL | フィルタは IMediaEventSink インターフェイスへのポインタを持っていない。

注意

通知コードとパラメータ値のリストについては、「イベント通知コード」を参照すること。

基底クラスでは、イベントコードが EC_COMPLETE なら、メソッドは EventParam2 パラメータをフィルタの IBaseFilter インターフェイスへのポインタに設定する。

CBaseFilter::Pause

CBaseFilter クラス

フィルタをポーズにする。IMediaFilter::Pause メソッドの実装。

構文

HRESULT Pause(void);

戻り値

成功すれば S_OK を返す、それ以外の場合エラーの原因を含む HRESULT 値を返す。

注意

このメソッドはピンに接続した各フィルタごとに CBasePin::Active メソッドを呼び出す。

CBaseFilter::QueryFilterInfo

CBaseFilter クラス

フィルタの情報を取得。IBaseFilter::QueryFilterInfo メソッドの実装。

構文

HRESULT QueryFilterInfo(
    FILTER_INFO *pInfo
);

パラメータ

pInfo
FILTER_INFO 構造体へのポインタ。

戻り値

S_OK あるいは E_POINTER を返す。

注意

このメソッドは m_pName メンバ変数から、FILTER_INFO 構造体の achName メンバにフィルタの名前をコピーする。m_pName が NULL のとき、メソッドは achName を L'\0' に設定する。

このメソッドはFILTER_INFO 構造体の achName メンバを m_pGraph メンバ変数と等しくし、参照カウントをインクリメントする。呼び出し元はそのインターフェイスを解放しなければならない。

CBaseFilter::QueryVendorInfo

CBaseFilter クラス

ベンダー情報を含む文字列を取得。

構文

HRESULT QueryVendorInfo(
    LPWSTR *pVendorInfo
    );

パラメータ

pVendorInfo
ベンダー情報を含むワイド文字列のポインタを取得する変数のアドレス。

戻り値

E_NOTIMPL を返す。

注意

フィルタのベンダー情報を提供し、このメソッドをオーバーライドする。このメソッドを実装する際、CoTaskMemAlloc 関数を使用して文字列のメモリ割り当てを行う。呼び出し元は CoTaskMemFree 関数を呼び出す責任を持つ。

CBaseFilter::ReconnectPin

CBaseFilter クラス

既存のピン接続を壊し、指定したメディアピンを使って、同じピンにそれを再接続する。

構文

HRESULT ReconnectPin(
    IPin *pPin,
    AM_MEDIA_TYPE const *pmt
);

パラメータ

pPin
ピンの IPin インターフェイスへのポインタ。
pmt
メディア タイプを指定する AM_MEDIA_TYPE 構造体へのポインタあるいは NULL 。

戻り値

HRESULT 値を返す。以下のいずれかの値を返す。

S_OK | 成功。
E_NOINTERFACE | m_pGraph メンバ 変数は NULL。

注意

このメソッドはフィルタ グラフ マネージャの IFilterGraph2::ReconnectEx メソッドを呼び出す。IFilterGraph2 が無効なら、メソッドは IFilterGraph::Reconnect を呼び出す。

CBaseFilter::Register

CBaseFilter クラス

フィルタをレジストリに追加する。IAMovieSetup::Register メソッドの実装。

注意 この IAMovieSetup インターフェイスは使われていない。新しいフィルタは IAMovieSetup を要求しない AMovieDllRegisterServer2 関数を使ってレジストリに追加すべきである。詳細については、「DirectShow オブジェクトの登録方法」を参照すること。

構文

HRESULT Register(void);

戻り値

以下の HRESULT 値の 1 つを返す。

S_OK | 成功。
S_FALSE | 有効なレジストリ情報はない。

注意

このメソッドは フィルタのレジストリ登録に、AMovieSetupRegisterFilter 関数を呼び出す。

CBaseFilter::Run

CBaseFilter クラス

フィルタを実行する。IMediaFilter::Run メソッドの実装。

構文

HRESULT Run(
    REFERENCE_TIME tStart
);

パラメータ

tStart
ストリーム タイム 0 に対応する基準タイム。

戻り値

成功すれば S_OK を返す、それ以外の場合エラーの原因を示す HRESULT 値を返す。

注意

フィルタが停止されると、このメソッドは CBaseFilter::Pause メソッドを呼び出してフィルタをポーズにする。次にフィルタに接続している各ピンのCBasePin::Run メソッドを呼び出す。最後に、m_State メンバ変数をState_Running に設定する。

ストリーム タイムは現在の基準時間引く tStart で計算される。タイム スタンプ ゼロのメディア サンプルは tStart タイムにレンダリングされる。

CBaseFilter::SetSyncSource

CBaseFilter クラス

フィルタの基準クロックをセット。IMediaFilter::SetSyncSource メソッドの実装。

構文

HRESULT SetSyncSource(
    IReferenceClock *pClock
    );

パラメータ

pClock
クロックの IReferenceClock インターフェイスへのポインタ、あるいは NULL 。

戻り値

S_OK を返す。

CBaseFilter::Stop

CBaseFilter クラス

フィルタを停止する。 IMediaFilter::Stop メソッドの実装。

構文

HRESULT Stop(void);

戻り値

成功すると S_OK を返す、それ以外の場合エラーの原因を含む HRESULT 値を返す。

注意

このメソッドはフィルタに接続している各ピンの CBasePin::Inactive メソッドを呼び出す。

CBaseFilter::StreamTime

CBaseFilter クラス

現在のストリーム タイムを取得。

構文

virtual HRESULT StreamTime(
    CRefTime& rtStream
);

パラメータ

rtStream
現在のストリーム タイムを受け取る CRefTime オブジェクトへの参照。

戻り値

HRESULT 値を返す。次の表は、可能な値を示している。

S_OK | 成功。
VFW_E_NO_CLOCK | 有効な基準クロックはない。

注意

ストリーム タイムは現在の(基準クロックで与えられる)基準タイム 引く (m_tStart によって指定される)開始タイムとして定義される。メディア サンプルの タイム スタンプ はレダリング時にストリーム タイムを指定する。現在のストリーム タイムより小さいタイム スタンプを持つサンプルがまだレンダリングされてないなら、それは遅れている。

CBaseFilter::Unregister

CBaseFilter クラス

レジストリからフィルタを削除する。IAMovieSetup::Unregister メソッドの実装。

注意 この IAMovieSetup インターフェイスは使われていない。新しいフィルタはレジストリの削除に AMovieDllRegisterServer2 関数を使用べきだ。詳細については、「DirectShow オブジェクトの登録方法」を参照すること。

構文

HRESULT Unregister(void);

戻り値

成功なら S_OK を返す、それ以外の場合エラーの原因を示す HRESULT 値を返す。

注意

このメソッドはAMovieSetupRegisterFilter 関数を呼び出してフィルタをレジストリから削除する。


CBaseInputPin クラス

入力ピンを実装する抽象基底クラス

宣言 : Amfilter.h

このクラスは IMemInputPin インターフェイスのサポートを追加し、さらに CBasePin によって提供される IPin インターフェイスのサポートを追加する。

このクラスを使用するには、新しいクラスを派生し、少なくとも以下のメソッドにオーバーライドする。

  • BeginFlush
  • EndFlush
  • Receive
Protected メンバ変数
m_pAllocator | メモリ アロケータへのポインタ。
m_bReadOnly | アロケータが読み込み専用メディア サンプルを扱うかどうかを示すフラグ。
m_bFlushing | 現在フラッシュしているピンかどうかを示すフラグ。
m_SampleProps | 最新サンプルのプロパティ。
Public メソッド
CBaseInputPin | コンストラクタ メソッド。
~CBaseInputPin | デストラクタ メソッド。
BreakConnect | 接続からピンを解放する。
IsReadOnly | アロケータが読み込み専用メディア サンプルを使用するかどうか確認する。
IsFlushing | フィルタが現在フラッシュしているかどうか確認する。
CheckStreaming | ピンがサンプルを受け入れるかどうか決定する。仮想。
PassNotify | 品質コントロール メッセージを適切なオブジェクトに送る。
Inactive | ピンにフィルタが現在アクティブではないと通知する。仮想。
SampleProps | 最新サンプルのプロパティを取得。
IPin メソッド
BeginFlush | フラッシュ処理を開始する。
EndFlush | フラッシュ処理を終了する。
IMemInputPin メソッド
GetAllocator | このピンが提出したメモリ アロケータを取得する。
NotifyAllocator | 接続のアロケータを指定する。
GetAllocatorRequirements | 入力ピンが要求したアロケータ プロパティを取得する。
Receive | ストリーム内の次のメディア サンプルを取得する。
ReceiveMultiple | ストリーム内の複数のサンプルを取得する。
ReceiveCanBlock | Receive メソッドへの呼び出しがブロックになるかどうかを決定する。
IQualityControl メソッド
Notify | 品質コントロール メッセージを取得する。

CBaseInputPin.m_pAllocator

CBaseInputPin クラス

メモリ アロケータへのポインタ。

構文

IMemAllocator *m_pAllocator;

CBaseInputPin.m_bReadOnly

CBaseInputPin クラス

アロケータが読み込み専用メディア サンプルを扱うかどうかを示すフラグ。 TRUE ならアロケータは読み込み専用サンプルを扱う。

構文

BYTE m_bReadOnly;

CBaseInputPin.m_bFlushing

CBaseInputPin クラス

現在フラッシュしているピンかどうかを示すフラグ。TRUE ならピンはフラッシュしている。

構文

BYTE m_bFlushing;

CBaseInputPin.m_SampleProps

CBaseInputPin クラス

最新サンプルのプロパティ。

構文

AM_SAMPLE2_PROPERTIES m_SampleProps;

CBaseInputPin::BeginFlush

CBaseInputPin クラス

フラッシュ処理を開始する。IPin::BeginFlush メソッドの実装。

構文

HRESULT BeginFlush(void);

戻り値

S_OK を返す。

注意

このメソッドは m_bFlushing フラグを TRUE にし、 Receive メソッドにこれ以上のサンプルを拒絶させる。

派生クラスはこのメソッドをオーバーライドし、次のステップを実行しなければならない。

  1. ダウンストリーム入力ピンの IPin::BeginFlush メソッドを呼び出す。ピンがまだメディア サンプル ダウンストリームを出力していないのなら、このステップは省略できる。出力ピンが CBaseOutputPin メソッドから出力されている場合は、 CBaseOutputPin::DeliverBeginFlush が呼び出せる。
  2. 基底クラス メソッドを呼び出す。
  3. キューにあるデータの廃棄を開始する。
  4. ブロックされている Receive メソッドへの呼び出しから戻る。

CBaseInputPin::BreakConnect

CBaseInputPin クラス

接続からピンを解放。

構文

HRESULT BreakConnect(void);

戻り値

成功すれば S_OK を返す、それ以外の場合エラーの原因を含む HRESULT 値を返す。

注意

このメソッドは CBasePin::BreakConnect メソッドをオーバーライドする。アロケータをデコミットにし、IMemAllocator インターフェイスを解放する。

このメソッドをオーバーライドする際は、オーバーライドするメソッドから基底クラスメソッドを呼び出すこと。そうしないとメモリ リークを起こす可能性がある。

CBaseInputPin::CBaseInputPin

CBaseInputPin クラス

コンストラクタ メソッド

構文

CBaseInputPin(
    TCHAR *pObjectName,
    CBaseFilter *pFilter,
    CCritSec *pLock,
    HRESULT *phr,
    LPCWSTR pPinName
);

パラメータ

pObjectName
オブジェクトのデバッグ用の名前が入る文字列。詳細については、「CBaseObject」を参照すること。
pFilter
このピンを作成したフィルタへのポインタ。
pLock
CCritSec ロックへのポインタで、状態移行を継続するために使用する。これはフィルタ ロック CBaseFilter.m_pLock と同様のクリティカル セクションとなりうる。
phr
メソッドの成功・失敗を示す HRESULT 値を取得する変数のポインタ。
pPinName
(ピン ID としても使われる)ピン名が入る Unicode™ 文字列。

注意

すべてのパラメータは直接 CBasePin コンストラクタに送られる。

CBaseInputPin::~CBaseInputPin

CBaseInputPin クラス

デストラクタ メソッド。

構文

~CBaseInputPin(void);

CBaseInputPin::CheckStreaming

CBaseInputPin クラス

ピンがサンプルを受け入れるかどうか決定する。

構文

virtual HRESULT CheckStreaming(void);

戻り値

次の表に示す HRESULT 値の 1 つを返す。

S_OK | 成功。
S_FALSE | ピンは現在フラッシュしている。
VFW_E_RUNTIME_ERROR | ランタイム エラーが起きた。
VFW_E_WRONG_STATE | ピンは停止された。

注意

派生クラスはこのメソッドをオーバーライドし更にチェックを行うことができる。オーバーライドするメソッドではまた基底クラスの実装を呼び出す。

CBasePin::Receive メソッドはこのメソッドを呼び出す。同様に、CBasePin::EndOfStream メソッドをオーバーライドして、このメソッドを呼び出すべきである。

CBaseInputPin::EndFlush

CBaseInputPin クラス

フラッシュ処理を終了する。IPin::EndFlush メソッドの実装。

構文

HRESULT EndFlush(void);

戻り値

S_OK を返す。

注意

このメソッドは m_bFlushing フラグを TRUE にセットし、Receive メソッドにサンプルを受け入れさせる。

派生クラスはこのメソッドをオーバーライドし、次のステップを実行しなければならない。

  1. バッファにあるデータを解放し、すべてのキューにあるサンプルを廃棄。
  2. ペンディングのEC_COMPLETE 通知をクリア。
  3. 基底クラス メソッドを呼び出す。
  4. ダウンストリーム 入力ピンの IPin::EndFlush を呼び出す。そのピンがまだメディア サンプル ダウンストリームをまだ送り出していない場合、このステップはスキップできる。出力ピンが CBaseOutputPin クラスから派生されているのなら、CBaseOutputPin::DeliverEndFlush メソッドが呼び出せる。

CBaseInputPin::GetAllocator

CBaseInputPin クラス

このピンが提出したメモリ アロケータを取得する。IMemInputPin::GetAllocator メソッドの実装。

構文

HRESULT GetAllocator(
    IMemAllocator **ppAllocator
);

パラメータ

ppAllocator
アロケータの IMemAllocator インターフェイスへのポインタを受け取る変数のアドレス。

戻り値

成功なら S_OK を返す、それ以外の場合 CoCreateInstance からエラーコードを返す。

注意

このメソッドは CMemAllocator オブジェクトを作成する。フィルタがダウンストリーム ピンからのアロケータあるいはカスタム アロケータを使用するなら、このメソッドをオーバーライドすべきだ。

メソッドが成功すると、IMemAllocator インターフェイスは未処理の参照カウントを持つ。解放時には注意が必要。

CBaseInputPin::GetAllocatorRequirements

CBaseInputPin クラス

入力ピンが要求したアロケータ プロパティを取得する。

構文

HRESULT GetAllocatorRequirements(
    ALLOCATOR_PROPERTIES *pProps
);

パラメータ

pProps
要求で満たされた ALLOCATOR_PROPERTIES 構造体へのポインタ。

戻り値

E_NOTIMPL を返す。

注意

出力ピンがメモリ アロケータを初期化するとき、このメソッドを呼び出して入力ピンがバッファ要求を持っているかどうかを調べることができる。詳細については、「CBaseOutputPin::DecideAllocator」を参照すること。

このメソッドの実装は任意である。フィルタが固有のアラインメントや前置値要求を持っているなら、このメソッドをオーバーライドすべきだ。

CBaseInputPin::Inactive

CBaseInputPin クラス

ピンにフィルタが現在アクティブではないと通知する。

構文

HRESULT Inactive(void);

戻り値

HRESULT 値を返す。次の表は、可能な値を示している。

S_OK | 成功。
VFW_E_NO_ALLOCATOR | 有効なメモリ アロケータがない。

注意

このメソッドは CBasePin::Inactive メソッドをオーバーライドする。それは IMemAllocator::Decommit メソッドを呼び出して、メモリ アロケータをデコミットにする。

このメソッドをオーバーライドするなら、そのオーバーライド メソッドから基底クラス メソッドを呼び出すこと。

CBaseInputPin::IsFlushing

CBaseInputPin クラス

フィルタが現在フラッシュしているかどうか確認する。

構文

BOOL IsFlushing(void);

戻り値

m_bFlushing メンバ変数を返す。

CBaseInputPin::IsReadOnly

CBaseInputPin クラス

アロケータが読み込み専用メディア サンプルかどうか確認する。

構文

BOOL IsReadOnly(void);

戻り値

m_bReadOnly メンバ変数を返す。

CBaseInputPin::Notify

CBaseInputPin クラス

品質変更が要求されたことをピンに知らせる。IQualityControl::Notify メソッドの実装。

構文

HRESULT Notify(
    IBaseFilter *pSelf,
    Quality q
);

パラメータ

pSelf
品質コントロール メッセージを送っているフィルタへのポインタ。
q
品質コントロール メッセージを含む Quality 構造体。

戻り値

S_OK を返す。

注意

普通、フィルタは品質コントロール メッセージをアップストリーム出力ピンに送り、入力ピンには送らない。それゆえこのメソッドは何もしない場合以外は S_OK を返す。

詳細については、「品質コントロールの管理」を参照すること。

CBaseInputPin::NotifyAllocator

CBaseInputPin クラス

接続のアロケータを指定する。IMemInputPin::NotifyAllocator メソッドの実装。

構文

HRESULT NotifyAllocator(
    IMemAllocator *pAllocator,
    BOOL bReadOnly
);

パラメータ

pAllocator
アロケータの IMemAllocator インターフェイスへのポインタ。
bReadOnly
このアロケータからのサンプルが読み込み専用かどうかを指定するフラグ。TRUE であればサンプルは読み込み専用。

戻り値

S_OK を返す。

注意

ピンが接続している間、出力ピンはアロケータを選択し、このメソッドを呼び出して入力ピンに通知する。出力ピンは入力ピンが IMemInputPin::GetAllocator メソッドで提供したアロケータを使用できる、あるいは自分自身のアロケータを提供できる。

CBaseInputPin::PassNotify

CBaseInputPin クラス

品質コントロール メッセージを適切なオブジェクトに送る。

構文

HRESULT PassNotify(
    Quality q
);

パラメータ

q
品質コントロール メッセージを含む Quality 構造体。

戻り値

HRESULT 値を返す。次の表は、可能な値を示している。

S_OK | 成功。
VFW_E_NOT_FOUND | メッセージを受け入れるオブジェクトを見つけられない。

注意

フィルタが品質コントロール メッセージを取り扱わないなら、このメソッドを呼び出すこと。このメソッドはオブジェクトの 1 つに次の優先順でそのメッセージを送る :

  • IQualityControl::SetSink が呼び出されたなら、外部品質コントロール マネージャ。
  • アップストリーム出力ピン。

詳細については、「品質コントロールの管理」を参照すること。

CBaseInputPin::Receive

CBaseInputPin クラス

ストリーム中の次のメディア サンプルを取得。IMemInputPin::Receive の実装。

構文

HRESULT Receive(
    IMediaSample *pSample
);

パラメータ

pSample
サンプルの IMediaSample インターフェイスへのポインタ。

戻り値

HRESULT 値を返す。次の値のいずれか。

S_OK | 成功。
S_FALSE | ピンは現在フラッシュしている、サンプルは拒否される。
E_POINTER | NULL ポインタ引数。
VFW_E_INVALIDMEDIATYPE | 不適切なメディア タイプ。
VFW_E_RUNTIME_ERROR | A ランタイム エラーが発生した。
VFW_E_WRONG_STATE | ピンは停止中。

注意

アップストリーム出力ピンはこのメソッドを呼び出し、入力ピンにサンプルを出力する。入力ピンは次の 1 つを行わなければならない :

  • 戻る前にサンプルを処理する。
  • 戻り、ワーカー スレッドでサンプルを処理する。
  • サンプルを拒否する。

ピンがワーカー スレッドを使ってサンプルを処理するなら、このメソッド内のサンプルへの参照カウントを追加する。このメソッドが戻った後で、アップストリーム ピンはサンプルを解放する。サンプルの参照カウントがゼロになると、サンプルは再使用のためにアロケータを返す。

このメソッドは同期され、ブロックできる。メソッドがブロックすると、ピンの ReceiveCanBlock メソッドは S_OK を返す。

基底クラスでは、このメソッドは次のステップを実行する :

  1. CheckStreaming メソッドを呼び出し、ピンがサンプルを今処理できることを検証する。できない場合—たとえばピンが停止中—メソッドは失敗する。
  2. サンプル プロパティを取得し、そのフォーマットが変更されたかどうかをチェック(次を参照)。
  3. フォーマットが変更になったなら、メソッドは CBasePin::CheckMediaType メソッドを呼び出し、新しいフォーマットが受け入れ可能かどうかを調べる。
  4. 新しいフォーマットが受け入れ可能でないなら、メソッドは CBasePin::EndOfStream メソッドを呼び出し、EC_ERRORABORT イベントをポストし、エラーコードを返す。
  5. エラーがないのであれば、メソッドは S_OK を返す。

フォーマット変更についてのテストは次のように行う :

  • そのサンプルが IMediaSample2 インターフェイスをサポートするなら、AM_SAMPLE2_PROPERTIES 構造体の dwSampleFlags メンバをチェックする。AM_SAMPLE_TYPECHANGED フラグが含まれていれば、フォーマットは変更されている。
  • そうではなく、IMediaSample2 サンプルをサポートしていないなら、IMediaSample::GetMediaType メソッドを呼び出す。メソッドが 非 NULL 値で返るなら、フォーマットは変更されている。

基底クラスでは、このメソッドはサンプルを処理しない。派生クラスはこのメソッドをオーバーライドし、処理を実行しなければならない(この結果はフィルタに完全に依存する)。 派生クラスは基底クラス メソッドを呼び出し、以前に記述されたエラーをチェックすべきだ。

CBaseInputPin::ReceiveCanBlock

CBaseInputPin クラス

IMemInputPin::Receive メソッドへの呼び出しがブロックされるかどうかを調べる。 IMemInputPin::ReceiveCanBlock メソッドの実装。

構文

HRESULT ReceiveCanBlock(void);

戻り値

Returns an HRESULT 値を返す。次の値のいずれか。

S_FALSE | ピンは Receive を呼び出してもブロックしない。
S_OK | ピンは Receive を呼び出すとブロックする可能性がある。

注意

Receive メソッドの呼び出しがブロックしないと保証されるなら、S_FALSE を返す。それ以外の場合は、S_OK かエラー コードを返す。Receive メソッドがダウンストリーム ピンの Receive を呼び出すと、ダウンストリーム ピンはブロックする可能性がある、 ReceiveCanBlock はアカウントにそのファクタを渡さなければならない。

アップストリーム フィルタはこのメソッドを使用して、スレッド戦略を決めることができる。Receive メソッドがブロックする可能性があるなら、アップストリーム フィルタはデータをバッファするワーカー スレッドの使用を決める事も可能だ。この戦略の実装については「COutputQueueクラス」を参照すること。

基底クラスでは、次のいずれかが真のときこのメソッドは S_OK を返す :

  • フィルタが出力ピンを持たない。
  • このフィルタに接続する入力ピンがブロックするかもしれないと通知する。
  • このフィルタに接続されている入力ピンが IMemInputPin インターフェイスをサポートしない。

CBaseInputPin::ReceiveMultiple

CBaseInputPin クラス

ストリーミング内の複数のサンプルを取得する。IMemInputPin::ReceiveMultiple メソッドの実装。

構文

HRESULT ReceiveMultiple(
    IMediaSample **pSamples,
    long nSamples,
    long *nSamplesProcessed
);

パラメータ

pSamples
nSamples サイズの、複数の IMediaSample ポインタの配列のアドレス。
nSamples
処理するサンプルの数。
nSamplesProcessed
処理されたサンプルの数を受け取る変数のポインタ。

戻り値

HRESULT 値を返す。次の表は、可能な値を示している。

S_OK | 成功。
S_FALSE | ピンは現在フラッシュしている、サンプルは拒否された。
E_POINTER | NULL ポインタ引数。
VFW_E_INVALIDMEDIATYPE | 不適切なメディア タイプ。
VFW_E_RUNTIME_ERROR | A ランタイム エラーが起きた。
VFW_E_WRONG_STATE | ピンは停止中。

注意

このメソッドは Receive メソッドと同様に動作するが、サンプルの配列を受け取る。基底クラスでは、このメソッドは配列でループし、各サンプルに Receive を呼び出す。フィルタがサンプルのバッチを一度に処理するより効果的に処理できるなら、この関数をオーバーライドすること。

CBaseInputPin::SampleProps

CBaseInputPin クラス

最新のサンプルのプロパティを AM_SAMPLE2_PROPERTIES 構造体として受け取る。

構文

AM_SAMPLE2_PROPERTIES *SampleProps(void);

戻り値

m_SampleProps メンバ変数のアドレスを返す。


CBaseList クラス

抽象リストの実装。CBaseList から派生した CGenericList クラス テンプレートはタイプ チェックと CBaseList クラスより単純な API を提供する。

宣言 : Wxlist.h

CBaseList クラスは Microsoft® Foundation Classes (MFC) ライブラリにある CObList の後で作成されている。リスト内の位置は POSITION 構造体によって示される。呼び出し元は POSITION 構造体の内部メンバにアクセスすべきではない、リスト ノードのポインタとして扱うべきだ。リスト内のオブジェクトの位置はオブジェクトが削除されるまで継続して有効である。

リストはそれを含むオブジェクトによるサポートを要求しない。ストレージ管理やオブジェクトのコピーは行わない。オブジェクトは複数のリストに存在し得る。

このクラスの約半数のメソッドはシングル オブジェクトである。これらのメソッドはメソッド名に I の接尾辞を持つ。他のメソッドは完全なリストとして動作する。たとえば、AddAfter メソッドはあるリストを他のリストに追加する、シングル オブジェクト操作は POSITION 値を返すか、失敗時は NULL を返す。リスト操作は成功時に TRUE を、失敗時に FALSE を返す。

Protected メンバ変数
m_Count | リストの項目数。
m_pFirst | リストの先頭ノードへのポインタ。
m_pLast | リストの末尾ノードへのポインタ。
Protected メソッド
GetNextI | 指定した位置の項目を取得し、位置を進める。
GetI | 指定した位置の項目を取得する。
FindI | 指定した項目を持つ最初の位置を取得する。
RemoveHeadI | リストの先頭項目を削除する。
RemoveTailI | リストの末尾項目を削除する。
RemoveI | 指定した位置の項目を削除する。
AddTailI | リストの末尾に項目を追加する。
AddHeadI | リストの先頭に項目を追加する。
AddAfterI | 指定した位置の後に項目を挿入する。
AddBeforeI | 指定した位置の前に項目を挿入する。
Public メソッド
CBaseList | コンストラクタ メソッド。
~CBaseList | デストラクタ メソッド。
RemoveAll | リストからすべてのノードを削除する。
GetHeadPositionI | リストの先頭項目の位置を取得する。
GetTailPositionI | リストの末尾項目の位置を取得する。
GetCountI | リストの項目数を取得する。
Next | リストの次の位置を取得する。
Prev | リストの前の位置を取得する。
AddHead | このリストの前に他のリストを挿入する。
AddTail | このリストの後に他のリストを追加する。
AddAfter | 指定した位置の後にリストを挿入する。
AddBefore | 指定した位置の前にリストを挿入する。
MoveToTail | リストを分割し、前側を他のリストの最後に追加する。
MoveToHead | リストを分割し、後ろ側を他のリストの前に挿入する。
Reverse | リストの順番を逆転する。

CBaseList.m_Count

CBaseList クラス

リストの項目数。

構文

LONG m_Count;

CBaseList.m_pFirst

CBaseList クラス

リストの先頭ノードへのポインタ。

構文

CNode *m_pFirst;

CBaseList.m_pLast

CBaseList クラス

リストの末尾ノードへのポインタ。

構文

CNode *m_pLast;

CBaseList::AddAfter

CBaseList クラス

指定した位置の後にリストを挿入する。

構文

BOOL AddAfter(
    POSITION pos,
    CBaseList *pList
);

パラメータ

pos
この後ろにリストを挿入する位置。
pList
挿入するリストへのポインタ。

戻り値

成功なら TRUE、それ以外なら FALSE を返す。

注意

pos パラメータで指定される情報を含む既存の位置情報は有効のまま残ってしまう。このメソッドが失敗するなら、いくつかの項目が既に追加された可能性がある。

CBaseList::AddAfterI

CBaseList クラス

指定した位置の後に項目を挿入する。

構文

POSITION AddAfterI(
    POSITION pos,
    void *pObj
);

パラメータ

pos
この後ろに項目を挿入する位置。
pObj
追加する項目へのポインタ。

戻り値

挿入された項目の位置情報が返る。

注意

pos が NULL なら、このメソッドはリストの先頭に項目を追加した ( AddHeadI メソッドを呼び出したのと同じ)。

CBaseList::AddBefore

CBaseList クラス

指定した位置の前にリストを挿入する。

構文

BOOL AddBefore(
    POSITION pos,
    CBaseList *pList
);

パラメータ

pos
この前にリストを挿入する位置。
pList
追加するリストへのポインタ。

戻り値

成功なら TRUE、それ以外なら FALSE を返す。

注意

pos パラメータで指定される情報を含む既存の位置情報は有効のまま残ってしまう。このメソッドが失敗するなら、いくつかの項目が既に追加された可能性がある。

CBaseList::AddBeforeI

CBaseList クラス

指定した位置の前に項目を挿入する。

構文

POSITION AddBeforeI(
    POSITION pos,
    void *pObj
);

パラメータ

pos
この前に項目を挿入する位置。
pObj
項目へのポインタ。

戻り値

挿入された項目の位置情報が返る。

注意

pos が NULL である場合、このメソッドはリストの末尾に項目を追加する (AddTailI メソッドの呼び出しと同じ)。

CBaseList::AddHead

CBaseList クラス

このリストの前に他のリストを挿入する。

構文

BOOL AddHead(
    CBaseList *pList
);

パラメータ

pList
追加する項目リストへのポインタ。

戻り値

成功なら TRUE、それ以外なら FALSE を返す。

注意

メソッドが失敗するなら、いくつかの項目が既にリストに追加された可能性がある。

CBaseList::AddHeadI

CBaseList クラス

リストの最初に項目を追加する。

構文

POSITION AddHeadI(
    void *pObj
);

パラメータ

pObj
項目へのポインタ。

戻り値

新しい先頭位置を示す POSITION 値を返す。

注意

メソッドが失敗すると、戻り値は NULL 。

CBaseList::AddTail

CBaseList クラス

このリストの後に他のリストを追加する。

構文

BOOL AddTail(
    CBaseList *pList
);

パラメータ

pList
追加するリストへのポインタ。

戻り値

成功なら TRUE、それ以外なら FALSE を返す。

注意

メソッドが失敗するなら、いくつかの項目が既に追加された可能性がある。

CBaseList::AddTailI

CBaseList クラス

リストの終わりに項目を追加する。

構文

POSITION AddTailI(
    void *pObj
);

パラメータ

pObj
項目へのポインタ。

戻り値

新しい末尾位置を示す POSITION 値を返す。

注意

メソッドが失敗すると、戻り値は NULL 。

CBaseList::CBaseList

CBaseList クラス

コンストラクタ メソッド。

構文

CBaseList(
    TCHAR *pName,
    INT iItems
);

CBaseList(
    TCHAR *pName
);

パラメータ

pName
リスト名へのポインタ。
iItems
ノード キャッシュのサイズ。

注意

効率のため、CBaseList クラスはリスト ノードのキャッシュを維持する。リストが持つおおよその項目数が分かっているのなら、コンストラクタの第 1 バージョンを使うべきだ。第 2 バージョンはデフォルトのキャッシュ サイズを使用すること。

CBaseList::~CBaseList

CBaseList クラス

デストラクタ メソッド。

構文

~CBaseList(void);

CBaseList::FindI

CBaseList クラス

指定した項目を持つ最初の位置を取得する。

構文

POSITION FindI(
    void *pObj
);

パラメータ

pObj
項目へのポインタ。

戻り値

POSITION 値を返す、リスト内に項目がなければ NULL を返す。

CBaseList::GetCountI

CBaseList クラス

リストの項目数を取得する。

構文

int GetCountI(void);

戻り値

リストの項目数を返す。

CBaseList::GetHeadPositionI

CBaseList クラス

リストの先頭項目の位置を取得する。

構文

POSITION GetHeadPositionI(void);

戻り値

POSITION 値を返す、リストが"から"の場合 NULL を返す。

CBaseList::GetI

CBaseList クラス

指定した位置の項目を取得する。

構文

void *GetI(
    POSITION pos
);

パラメータ

pos
取得する項目の位置情報。

戻り値

項目へのポインタを返す。

注意

pos が NULL なら、メソッドは NULL を返す。

CBaseList::GetNextI

CBaseList クラス

指定した位置の項目を取得し、位置を進める。

構文

void *GetNextI(
    POSITION& rp
);

パラメータ

rp
POSITION 値への参照。

戻り値

項目へのポインタを返す。

注意

このメソッドは位置情報を次の位置に進める。位置情報がリストの末尾を越えたなら、メソッドはそれに NULL を設定する。

rp が NULL なら、メソッドは NULL を返す。

CBaseList::GetTailPositionI

CBaseList クラス

リストの末尾項目の位置を取得する。

構文

POSITION GetTailPositionI(void);

戻り値

POSITION 値を返す、リストに何も入っていないなら NULL を返す。

CBaseList::MoveToHead

CBaseList クラス

リストを分割し、後ろ側を他のリストの前に挿入する。

構文

BOOL MoveToHead(
    POSITION pos,
    CBaseList *pList
);

パラメータ

pos
リストを分割する位置情報。
pList
別のリストへのポインタ。

戻り値

成功なら TRUE、それ以外なら FALSE を返す。

注意

このメソッドは pos パラメータが指定する位置の前でリストを分割する。前側の部分はリストに残る。後ろ側の部分は他のリストの先頭に挿入される。

CBaseList::MoveToTail

CBaseList クラス

リストを分割し、前側を他のリストの最後に追加する。

構文

BOOL MoveToTail(
    POSITION pos,
    CBaseList *pList
);

パラメータ

pos
リストを分割する位置情報。
pList
他のリストへのポインタ。

戻り値

成功なら TRUE、それ以外なら FALSE を返す。

注意

このメソッドは pos パラメータが指定する位置の前でリストを分割する。後ろ側の部分はリストに残る。前側の部分は他のリストの末尾に追加される。

CBaseList::Next

CBaseList クラス

リストの次の位置を取得する。

構文

POSITION Next(
    POSITION pos
);

パラメータ

pos
POSITION 値

戻り値

pos が指定する位置の次の位置情報を返す。

注意

pos がリストの末尾の位置なら、メソッドは NULL を返す。pos が NULL なら、メソッドはリストの先頭位置を返す。

CBaseList::Prev

CBaseList クラス

リストの前の位置を取得する。

構文

POSITION Prev(
    POSITION pos
);

パラメータ

pos
POSITION 値。

戻り値

pos で指定される位置の前の位置情報を返す。

注意

pos がリストの先頭の位置なら、メソッドは NULL を返す。pos が NULL なら、メソッドはリストの末尾の位置を返す。

CBaseList::RemoveAll

CBaseList クラス

リストからすべてのノードを削除する。

構文

void RemoveAll(void);

注意

すべてのノードに含まれる項目の削除は呼び出し元の責任である。

CBaseList::RemoveHeadI

CBaseList クラス

リストの先頭項目を削除する。

構文

void *RemoveHeadI(void);

戻り値

項目のポインタを返す、リストに何も入っていないなら NULL を返す。

注意

このメソッドはリストからノードを削除するが、ノードに含まれる項目は削除しない。

CBaseList::RemoveI

CBaseList クラス

指定した位置の項目を削除する。

構文

void *RemoveI(
    POSITION pos
);

パラメータ

pos
削除する項目を示す POSITION 値。

戻り値

項目のポインタを返す。

注意

このメソッドはリストからノードを削除するが、ノードに含まれる項目は削除しない。

pos が NULL なら、メソッドは NULL を返す。

CBaseList::RemoveTailI

CBaseList クラス

リストの末尾項目を削除する。

構文

void *RemoveTailI(void);

戻り値

項目のポインタを返す、リストがからなら NULL を返す。

注意

このメソッドはリストからノードを削除するが、ノードに含まれる項目は削除しない。

CBaseList::Reverse

CBaseList クラス

リストの順番を逆転する

構文

void Reverse(void);


CBaseMediaFilter クラス

IMediaFilter インターフェイスを実装する基底クラス。PID、 それ以外では IBaseFilter インターフェイスをサポートせずに IMediaFilter をサポートする必要のあるオブジェクトについてはこのクラスを使用する。フィルタについてはこのクラスを使用してはならない。そのかわり、CBaseFilter あるいは CBaseFilter から派生した基底クラスを使用する。

宣言 : Amfilter.h

Protected メンバ変数
m_State | オブジェクトの現在の状態。
m_pClock | オブジェクトの基準クロックへのポインタ。
m_tStart | ストリーム タイム 0 に対応する基準タイム。
m_clsid | オブジェクトのクラス ID (CLSID)。
m_pLock | クリティカル セクションへのポインタ。
Public メソッド
CBaseMediaFilter | コンストラクタ メソッド。
~CBaseMediaFilter | デストラクタ メソッド。 仮想。
StreamTime | 現在のストリーム タイムを取得する。仮想。
IsActive | オブジェクトがアクティブかどうか(実行中かポーズか)確認する。
IPersist メソッド
GetClassID | クラス ID を取得する。
IMediaFilter メソッド
GetState | オブジェクトがアクティブかどうか(実行中か、停止か、ポーズか)を取得する。
SetSyncSource | オブジェクトの基準クロックを設定する。
GetSyncSource | オブジェクトが使用中の基準クロックを取得する。
Stop | オブジェクトを停止する。
Pause | オブジェクトをポーズする。
Run | オブジェクトを実行する。

CBaseMediaFilter.m_State

CBaseMediaFilter クラス

オブジェクトの現在の状態。

構文

FILTER_STATE m_State;

CBaseMediaFilter.m_pClock

CBaseMediaFilter クラス

オブジェクトの基準クロックへのポインタ。

構文

IReferenceClock *m_pClock;

CBaseMediaFilter.m_tStart

CBaseMediaFilter クラス

ストリーム タイム 0 に対応する基準タイム。

構文

CRefTime m_tStart;

CBaseMediaFilter.m_clsid

CBaseMediaFilter クラス

オブジェクトのクラス ID (CLSID)。

構文

CLSID m_clsid;

CBaseMediaFilter.m_pLock

CBaseMediaFilter クラス

クリティカル セクションへのポインタ。

構文

CCritSec *m_pLock;

注意

基準クロックにアクセス(SetSyncSource や GetSyncSource)するときと、IsActive メソッドでは 、クリティカル セクションは状態移行中 (Run、Pause、Stop) に保持される。

CBaseMediaFilter::CBaseMediaFilter

CBaseMediaFilter クラス

コンストラクタ メソッド。

構文

CBaseMediaFilter(
    const TCHAR *pName,
    LPUNKNOWN pUnk,
    CCritSec *pLock,
    REFCLSID clsid
);

パラメータ

pName
オブジェクト名を含む文字列へのポインタ。
pUnk
このオブジェクトの所有者へのポインタ。オブジェクトが集成されていれば、集成されたオブジェクトの IUnknown インターフェイスへのポインタを渡す。それ以外の場合、このパラメータは NULL にセット。
pLock
CCritSec ロックへのポインタ、状態移行を継続するのに用いる。l
clsid
オブジェクトのクラス ID。

注意

他のオブジェクトが CBaseMediaFilter を含む、あるいは集成しているなら、CCritSec ロックは CBaseMediaFilter オブジェクト外で起きている可能性がある。この場合、pLock のロックへのポインタを渡すこと。

それ以外では次のようにする :

  • CBaseMediaFilter と CCritSec の両方を継承するクラスを派生させ、このポインタを渡す。
  • CBaseMediaFilter と CCritSec メンバ変数を継承するクラスを派生させる。pLock については、その変数のアドレスを渡す。

CBaseMediaFilter::~CBaseMediaFilter

CBaseMediaFilter クラス

デストラクタ メソッド。

構文

CBaseMediaFilter(void);

注意

削除する前に必ずオブジェクトを停止させること。

CBaseMediaFilter::GetClassID

CBaseMediaFilter クラス

クラス ID を取得。IPersist::GetClassID メソッドの実装。

構文

HRESULT GetClassID(
    CLSID *pClsID
);

パラメータ

pClsID
クラス ID を取得する変数のポインタ。

戻り値

S_OK か E_POINTER を返す。

CBaseMediaFilter::GetState

CBaseMediaFilter クラス

オブジェクトがアクティブかどうか(実行中か、停止か、ポーズか)を取得する。 IMediaFilter::GetState メソッドの実装。

構文

HRESULT GetState(
    DWORD dwMilliSecsTimeout,
    FILTER_STATE *State
);

パラメータ

dwMilliSecsTimeout
タイムアウト時間間隔、ミリ秒
State
オブジェクトの状態を示す FILTER_STATE 列挙型のメンバを取得する変数のポインタ。

戻り値

S_OK か E_POINTER を返す。

注意

基底クラスでは、すべての状態移行は同期され、dwMilliSecsTimeout パラメータは無視される。派生クラスが状態移行の同期を実行するなら、このメソッドをオーバーライドし、dwMilliSecsTimeout ミリ秒のタイムアウトで、状態移行を待つべきだ。

CBaseMediaFilter::GetSyncSource

CBaseMediaFilter クラス

オブジェクトが使用中の基準クロックを取得。IMediaFilter::GetSyncSource メソッドの実装。

構文

HRESULT GetSyncSource(
    IReferenceClock **pClock
);

パラメータ

pClock
クロックの IReferenceClock インターフェイスへのポインタを取得する変数のアドレス。

戻り値

S_OK か E_POINTER を返す。

注意

オブジェクトが基準クロックを使用していないなら、*pClock を NULL に設定する。メソッドが戻ったとき、*pClock が NULL 以外なら、IReferenceClock インターフェイスは参照カウントを残している。解放時には注意が必要である。

CBaseMediaFilter::IsActive

CBaseMediaFilter クラス

オブジェクトがアクティブかどうか(実行中かポーズか)確認する。

構文

BOOL IsActive(void);

戻り値

オブジェクトが実行中かポーズであれば、TRUE を返す。停止中であれば FALSE を返す。

CBaseMediaFilter::Pause

CBaseMediaFilter クラス

オブジェクトをポーズする。IMediaFilter::Pause メソッドの実装。

構文

HRESULT Pause(void);

戻り値

S_OK を返す。

注意

基底クラスでは、このメソッドは m_State メンバ変数を State_Paused に設定するが、それ以外は何もしない。

CBaseMediaFilter::Run

CBaseMediaFilter クラス

オブジェクトを実行する。IMediaFilter::Run メソッドの実装。

構文

HRESULT Run(
    REFERENCE_TIME tStart
);

パラメータ

tStart
ストリーム タイム 0 に対応した基準タイム。

戻り値

S_OK を返す。

注意

オブジェクトが停止していれば、このメソッドは CBaseMediaFilter::Pause メソッドを呼び出しオブジェクトをポーズする。次に m_State メンバ変数を State_Running に設定する。

ストリーム タイムは現在の基準タイム 引く tStart で計算される。タイム スタンプ ゼロのメディア サンプルは tStart タイムにレンダリングされるはずである。

CBaseMediaFilter::SetSyncSource

CBaseMediaFilter クラス

オブジェクトの基準クロックを設定する。IMediaFilter::SetSyncSource メソッドの実装。

構文

HRESULT SetSyncSource(
    IReferenceClock *pClock
);

パラメータ

pClock
クロックの IReferenceClock インターフェイスへのポインタ、あるいは NULL 。

戻り値

S_OK を返す。

CBaseMediaFilter::Stop

CBaseMediaFilter クラス

オブジェクトを停止する。IMediaFilter::Stop メソッドの実装。

構文

HRESULT Stop(void);

戻り値

S_OK を返す。

注意

基底クラスでは、このメソッドは m_State メンバ変数を State_Stopped に設定するが、それ以外は何もしない。

CBaseMediaFilter::StreamTime

CBaseMediaFilter クラス

現在のストリーム タイムを取得。

構文

virtual HRESULT StreamTime(
    CRefTime& rtStream
);

パラメータ

rtStream
現在のストリーム タイムを取得する CRefTime オブジェクトへの参照。

戻り値

HRESULT 値を返す。次の表は、可能な値を示している。

S_OK | 成功。
VFW_E_NO_CLOCK | 有効な基準クロックがない。

注意

ストリーム タイムは(基準クロックで与えられる)現在の基準タイム マイナス (m_tStartで与えれる)開始タイムによって定義される。メディア サンプルのタイム スタンプはレンダリングされるべきストリーム タイムを指定する。現在のストリーム タイムより小さなタイム スタンプを持つサンプルがまだレンダリングされないなら、それは遅れている。


CBaseObject クラス

Microsoft® DirectShow® オブジェクトを実装するための抽象クラス。

宣言 : Combase.h

このクラスは、静的な、プロセス全体のアクティブ オブジェクトの数のカウントを保持する。DllCanUnloadNow 関数は、このカウントを使用して DirectShow DLL をいつアンロードできるかを判断する。アプリケーションでは、このカウントを使用して、削除を取り消したオブジェクトによるメモリ リークを検出できる。

Component Object Model (COM) オブジェクトを実装するには、CBaseObject から派生した CUnknown クラスを使用する。

クラス メソッド
CBaseObject | コンストラクタ メソッド。
~CBaseObject | デストラクタ メソッド。
ObjectsActive | アクティブ オブジェクトのカウントを取得する。

CBaseObject::CBaseObject

CBaseObject クラス

コンストラクタ メソッド。

構文

CBaseObject(
const TCHAR *pName
);

パラメータ

pName
デバッグのために使用されるオブジェクトの名前を含む文字列。

注意

このメソッドは、アクティブ オブジェクトのカウントをインクリメントする。詳細については、「ObjectsActive」を参照すること。

スタティック メモリに pName パラメータを割り当てる。

// 正しい。
CBaseObject *pObject = new CObject(NAME("My Object"));

// 正しくない。
TCHAR ObjectName[] = TEXT("My Object");
CBaseObject *pObject = new CBaseObject(ObjectName);

NAME マクロは、リテール ビルドでは NULL にコンパイルされるので、静的文字列はデバッグ ビルドでのみ表示される。詳細については、「DbgDumpObjectRegister 」を参照すること。

CBaseObject::~CBaseObject

CBaseObject クラス

デストラクタ メソッド。

構文

~CBaseObject(void);

注意

このメソッドは、アクティブ オブジェクトのカウントをデクリメントする。詳細については、「ObjectsActive」を参照すること。

CBaseObject::ObjectsActive

CBaseObject クラス

プロセス全体のアクティブ オブジェクトのカウントを取得する。

構文

static LONG ObjectsActive(void);

戻り値

アクティブ オブジェクトの数を返す。


CBaseOutputPin クラス

出力ピンを実装する抽象基底クラス。

宣言 : Amfilter.h

このクラスは CBasePin から派生する。以下の面で CBasePin とは異なる。

  • IMemInput インターフェイスをサポートする入力ピンにのみ接続する。
  • IMemAllocator インターフェイスを通して、ローカル メモリ トランスポートをサポートする。
  • エンドオブストリーム、フラッシュ、新セグメント通知を拒絶する。(これらは出力ピンに送られるべきではない)
  • サンプル データストリームを出力するために提供されたメソッド

ピンが接続するとき、入力ピンからのメモリ アロケータを要求する。それが失敗すると、新しいアロケータ オブジェクトを作成する。出力ピンはアロケータ プロパティを設定する責任がある。純粋仮想メソッド DecideBufferSize を通してこれを行う。派生クラスではこのメソッドをオーバーライドする。入力ピンがバッファ要求を持つとき、その要求は DecideBufferSize メソッドに渡される。

空白のメディア サンプルを取得するには GetDeliveryBuffer を呼び出すこと。サンプル ダウンストリームを出力するには Deliver を呼び出すこと。

Protected メンバ変数
m_pAllocator | メモリ アロケータへのポインタ。
m_pInputPin | このピンに接続する入力ピンへのポインタ。
Public メソッド
CBaseOutputPin | コンストラクタ メソッド。
CompleteConnect | 入力ピンへの接続を完了する。仮想。
DecideAllocator | メモリ アロケータを選択する。仮想。
GetDeliveryBuffer | 空白バッファを持つメディア サンプルを取得。仮想。
Deliver | メディア サンプルを接続した入力ピンに出力する。仮想。
InitAllocator | メモリ アロケータを作成。仮想。
CheckConnect | ピン接続が適切かどうか確認する。
BreakConnect | 接続からピンを解放する。
Active | フィルタが現在アクティブであることをピンに通知する。
Inactive | フィルタがもうアクティブではないことをピンに通知する。
DeliverEndOfStream | エンドオブストリーム通知を接続する入力ピンに出力する。仮想。
DeliverBeginFlush | 接続する入力ピンにフラッシュ処理の開始を要求する。仮想。
DeliverEndFlush | 接続した入力ピンにフラッシュ処理の終了を要求する。仮想。
DeliverNewSegment | 新セグメント通知を接続する入力ピンに出力する。 仮想。
Pure Virtual メソッド
DecideBufferSize | バッファ要求を設定する。
IPin メソッド
BeginFlush | フラッシュ処理を開始する。
EndFlush | フラッシュ処理を終了する。
EndOfStream | 以降のデータはないことをピンに伝える。

CBaseOutputPin.m_pAllocator

CBaseOutputPin クラス

メモリ アロケータへのポインタ。

構文

IMemAllocator *m_pAllocator;

CBaseOutputPin.m_pInputPin

CBaseOutputPin クラス

このピンに接続する入力ピンへのポインタ。

構文

IMemInputPin *m_pInputPin;

CBaseOutputPin::Active

CBaseOutputPin クラス

フィルタが現在アクティブであることをピンに通知する。

構文

HRESULT Active(void);

戻り値

HRESULT 値を返す。次の表は、可能な値を示している。

S_OK | 成功。
VFW_E_NO_ALLOCATOR | 利用可能なメモリ アロケータがない。

注意

このメソッドは CBasePin::Active メソッドをオーバーライドする。アロケータの IMemAllocator::Commit メソッドを呼び出して、バッファにメモリを割り当てる。

このメソッドをオーバーライドするなら、そのオーバーライドする メソッドから基底クラス メソッドを呼び出すこと。

CBaseOutputPin::BeginFlush

CBaseOutputPin クラス

フラッシュ処理を開始する。IPin::BeginFlush メソッドの実装。

構文

HRESULT BeginFlush(void);

戻り値

E_UNEXPECTED を返す。

注意

このメソッドは入力ピンでのみ呼び出されるべきなので、CBaseOutputPin を実装すると E_UNEXPECTED を返す。

CBaseOutputPin::BreakConnect

CBaseOutputPin クラス

接続からピンを解放する。

構文

HRESULT BreakConnect(void);

戻り値

成功なら S_OK を返す、失敗ならエラーの原因を示す HRESULT 値を返す。

注意

このメソッドはCBasePin::BreakConnect メソッドをオーバーライドする。アロケータをデコミットにし、IMemAllocator と IPin インターフェイスを解放する。

このメソッドをオーバーライドするなら、そのオーバーライドする メソッドから基本メソッドを呼び出すこと。そうしないとメモリ リークの可能性がある。

CBaseOutputPin::CBaseOutputPin

CBaseOutputPin クラス

コンストラクタ メソッド。

構文

CBaseOutputPin(
    TCHAR *pObjectName,
    CBaseFilter *pFilter,
    CCritSec *pLock,
    HRESULT *phr,
    LPCWSTR pName
);

パラメータ

pObjectName
オブジェクトのデバッグ名が入る文字列。詳細については、「CbaseObject」を参照すること。
pFilter
このピンを作成したフィルタへのポインタ。
pLock
CCritSec ロックへのポインタ、状態移行を継続するために使用。これはフィルタ ロック CBaseFilter.m_pLock と同様のクリティカル セクションになり得る。
phr
メソッドの成功・失敗を示す HRESULT 値を取得する変数へのポインタ。
pName
(ピン ID としても使われる)ピン名が入る Unicode™ 文字列。

注意

すべてのパラメータは直接 CBasePin コンストラクタに送られる。

CBaseOutputPin::CheckConnect

CBaseOutputPin クラス

ピン接続が適切かどうか確認する。

構文

HRESULT CheckConnect(
    IPin *pPin
);

パラメータ

pPin
入力ピンの IPin インターフェイスへのポインタ。

戻り値

次の HRESULT 値の 1 つを返す。

S_OK | 成功。
E_NOINTERFACE | 入力ピンは IMemInputPinをサポートしていない。
VFW_E_INVALID_DIRECTION | ピンの向きに互換性がない。

注意

このメソッドは基底クラス CBasePin::CheckConnect メソッドを呼び出し、次に IMemInputPin インターフェイスに入力ピンを問い合わせる。

CBaseOutputPin::CompleteConnect

CBaseOutputPin クラス

入力ピンへの接続を完了する。

構文

virtual HRESULT CompleteConnect(
    IPin *pReceivePin
);

パラメータ

pReceivePin
入力ピンへのポインタ。

戻り値

成功なら S_OK を返す、失敗ならエラーの原因を示す HRESULT 値を返す。

注意

このメソッドは CBasePin::CompleteConnect メソッドをオーバーライドする。この接続に使用するメモリ アロケータを選択する DecideAllocator メソッドを呼び出す。

CBaseOutputPin::DecideAllocator

CBaseOutputPin クラス

メモリ アロケータを選択する。

構文

virtual HRESULT DecideAllocator(
    IMemInputPin *pPin,
    IMemAllocator **pAlloc
);

パラメータ

pPin
入力ピンの IMemInputPin インターフェイスへのポインタ。
pAlloc
アロケータの IMemAllocator インターフェイスへのポインタを取得する変数のアドレス。

戻り値

成功なら S_OK を返す、失敗ならエラーの原因を示す HRESULT 値を返す。

注意

このメソッドはピン接続プロセスの最後に呼び出される。次のステップで実行する :

  1. もしあれば、IMemInputPin::GetAllocatorRequirements メソッドを呼び出し、入力ピンのバッファ要求を取得する。
  2. IMemInputPin::GetAllocator メソッドを呼び出して、入力ピンからアロケータを要求する。その入力ピンがアロケータを提供しなければ、出力ピンは InitAllocator クラス メソッドを呼び出してアロケータを作成する。
  3. DecideBufferSize クラス メソッドを呼び出して、アロケータ プロパティを設定する。これは純粋仮想メソッドである、派生クラスはこれを実装しなければならない。
  4. IMemInputPin::NotifyAllocator メソッドを呼び出し、アロケータの使用を入力ピンに通知する。

CBaseOutputPin::DecideBufferSize

CBaseOutputPin クラス

バッファ要求を設定する。

構文

virtual HRESULT DecideBufferSize(
    IMemAllocator *pAlloc,
    ALLOCATOR_PROPERTIES *ppropInputRequest
) PURE;

パラメータ

pAlloc
アロケータの IMemAllocator インターフェイスへのポインタ。
ppropInputRequest
入力ピンのバッファ要求を含む ALLOCATOR_PROPERTIES 構造体へのポインタ。入力ピンが何の要求も指定しないなら、呼び出し元はこの構造体のメンバをゼロにするべである。

戻り値

成功なら S_OK を返す、失敗ならエラーの原因を示す HRESULT 値を返す。

注意

このメソッドを派生クラスでオーバーライドすること。バッファ要求を付けて IMemAllocator::SetProperties メソッドを呼び出す。通常派生クラスは入力バッファの要求を尊重するが、必ずしもそれをする必要はない。

CBaseOutputPin::Deliver

CBaseOutputPin クラス

メディア サンプルを接続した入力ピンに出力する。

構文

virtual HRESULT Deliver(
    IMediaSample *pSample
);

パラメータ

pSample
サンプルの IMediaSample インターフェイスへのポインタ。

戻り値

HRESULT 値を返す。次の表は、可能な値を示している。

S_OK | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されていない。

注意

このメソッドは入力ピンの IMemInputPin::Receive メソッドを呼び出す。IMemInputPin::ReceiveCanBlock メソッドが S_OK を返すなら、Receive はブロックする可能性がある。

このメソッドを呼び出した後で、サンプルを解放すること。入力ピンはサンプルの参照カウントを持ったままなので、サンプルを再使用してはならない。必ず GetDeliveryBuffer メソッドを呼び出して、新しいサンプルを取得する。

このメソッドを呼び出す前にフィルタのクリティカル セクションをホールドすること。そうしないと、そのピンはメソッド 呼び出し中に非接続になる可能性がある。フィルタがワーカー スレッドを使ってサンプルを出力するなら、フィルタがサンプルを出力可能になったとき、クリティカル セクションをホールドする。そうでなければ、フィルタの IMemInputPin::Receive メソッドでクリティカル セクションをホールドする、そこでフィルタはサンプルを処理する。

ワーカー スレッドはデッドロックの可能性を作成し得る。スレッドがクリティカル セクションをホールドするとき、フィルタの状態移行を待つかもしれない。同時に、状態移行はスレッドが完了するのを待っているかもしれない。これを避けるために、状態移行コードはスレッドを終わらせるイベントを通知し、次にスレッドがその通知を完了するまで待つこと。

CBaseOutputPin::DeliverBeginFlush

CBaseOutputPin クラス

接続する入力ピンにフラッシュ処理の開始を要求する。

構文

virtual HRESULT DeliverBeginFlush(void);

戻り値

HRESULT 値を返す。次の表は、可能な値を示している。

S_OK | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されていない。

注意

このメソッドは入力ピンの IPin::BeginFlush メソッドを呼び出す。

CBaseOutputPin::DeliverEndFlush

CBaseOutputPin クラス

接続した入力ピンにフラッシュ処理の終了を要求する。

構文

virtual HRESULT DeliverEndFlush(void);

戻り値

HRESULT 値を返す。次の表は、可能な値を示している。

S_OK | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されていない。

注意

このメソッドは入力ピンの IPin::EndFlush メソッドを呼び出す。

CBaseOutputPin::DeliverEndOfStream

CBaseOutputPin クラス

エンドオブストリーム通知を接続する入力ピンに出力する。

構文

virtual HRESULT DeliverEndOfStream(void);

戻り値

HRESULT 値を返す。次の表は、可能な値を示している。

S_OK | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されていない。

注意

このメソッドは入力ピンの IPin::EndOfStream メソッドを呼び出す。

CBaseOutputPin::DeliverNewSegment

CBaseOutputPin クラス

新セグメント通知を接続する入力ピンに出力する。

構文

virtual HRESULT DeliverNewSegment(
    REFERENCE_TIME tStart,
    REFERENCE_TIME tStop,
    double dRate
);

パラメータ

tStart
セグメントの開始メディア位置、100ナノ秒単位。
tStop
セグメントの終了メディア位置、100ナノ秒単位。
dRate
このセグメントが処理される割合、オリジナルのレートのパーセンテージ。

戻り値

HRESULT 値を返す。次の表は、可能な値を示している。

S_OK | 成功。
VFW_E_NOT_CONNECTED | ピンが接続されていない。

注意

このメソッドは入力ピンの IPin::NewSegment メソッドを呼び出す。

CBaseOutputPin::EndFlush

IPin Interface

フラッシュ処理を終了する。IPin::EndFlush メソッドの実装。

構文

HRESULT EndFlush(void);

戻り値

E_UNEXPECTED を返す。

注意

このメソッドは入力ピンでのみ呼び出されるべきなので、CBaseOutputPin を実装すると E_UNEXPECTED を返す。

CBaseOutputPin::EndOfStream

IPin Interface

以降のデータはないことをピンに伝える。 IPin::EndOfStream メソッドの実行。

構文

HRESULT EndOfStream(void);

戻り値

E_UNEXPECTED を返す。

注意

このメソッドは入力ピンでのみ呼び出されるべきなので、CBaseOutputPin を実装すると E_UNEXPECTED を返す。

CBaseOutputPin::GetDeliveryBuffer

CBaseOutputPin クラス

空白バッファを持つメディア サンプルを取得。

構文

virtual HRESULT GetDeliveryBuffer(
    IMediaSample **ppSample,
    REFERENCE_TIME *pStartTime,
    REFERENCE_TIME *pEndTime,
    DWORD dwFlags
);

パラメータ

ppSample
バッファの IMediaSample インターフェイスのポインタを取得する変数のアドレス。
pStartTime
サンプルの開始タイムへのポインタ、あるいは NULL 。
pEndTime
サンプルの終了タイムへのポインタ、あるいは NULL 。
dwFlags
IMemAllocator::GetBuffer インターフェイスによってサポートされる、フラグのビットごとの組み合わせ。

戻り値

HRESULT 値を返す。次の表は、可能な値を示している。

S_OK | 成功。
E_NOINTERFACE | 有効なメモリ アロケータがない。

注意

このメソッドは、アロケータの IMemAllocator::GetBuffer メソッドを呼び出し、このメソッドにパラメータを渡す。

CBaseOutputPin::Inactive

CBaseOutputPin クラス

フィルタがもうアクティブではないことをピンに通知する。

構文

HRESULT Inactive(void);

戻り値

HRESULT 値を返す。次の表は、可能な値を示している。

S_OK | 成功。
VFW_E_NO_ALLOCATOR | 有効なメモリ アロケータがない。

注意

このメソッドは CBasePin::Inactive メソッドをオーバーライドする。IMemAllocator::Decommit メソッドを呼び出して、メモリ アロケータをデコミットにする。

このメソッドをオーバーライドするなら、そのオーバーライドするメソッドから基底クラス メソッドを呼び出すこと。

CBaseOutputPin::InitAllocator

CBaseOutputPin クラス

メモリ アロケータを作成。

構文

virtual HRESULT InitAllocator(
    IMemAllocator **ppAlloc
);

パラメータ

ppAlloc
アロケータの IMemAllocator インターフェイスへのポインタを取得する変数のアドレス。

戻り値

成功なら S_OK を返す、失敗なら CoCreateInstance 関数からのエラーコードを返す。

注意

入力ピンがメモリ アロケータを提供しないなら、DecideAllocator メソッドはこのメソッドを呼び出し、アロケータを作成する。


CBasePin クラス

汎用ピンを実装する抽象クラス。

宣言 : Amfilter.h

  • 接続処理
  • CBasePin が IPin::Connect を実装する方法
  • フィルタ状態の移行

接続処理

フィルタ グラフ マネージャがすべてのピン接続を開始する。アプリケーションが 2 つのピンを接続する必要があるなら、フィルタ グラフ マネージャの IFilterGraph::ConnectDirect メソッドを呼び出すべきだ。

2 つのピンが接続されたとき、接続 ピンと 受信 ピンが存在する。フィルタ グラフ マネージャは接続ピンの IPin::Connect メソッドを呼び出す。これは受信ピンと接続している可能なメディア タイプを指定する。接続ピンは受信ピンの IPin::ReceiveConnection メソッドを呼び出すことで、接続を完了する。受信ピンは接続を受け入れることも拒否することも可能だ。

フィルタ グラフ マネージャがメディア タイプを指定すると、ピンはそのタイプで接続しようとする。そうでなければ、ピンは受け入れ可能なタイプをネゴシエーションする。タイプが一致できないと、接続は失敗する。フィルタ グラフ マネージャはパーシャル メディア タイプを指定する場合もある。パーシャル メディア タイプはメジャー タイプ、サブタイプ、フォーマットに GUID_NULL 値を持つ。この場合、ピンは指定した部分のタイプに合わせようとし、GUID_NULL はワイルドカードとして働く。

Microsoft® DirectShow® の実装では、接続ピンは必ず出力ピンで、受信ピンは必ず入力ピンである。

CBasePin が IPin::Connect を実装する方法

ピンが接続を受け入れることができるかを検証することによって CBasePin::Connect メソッドは開始する。たとえば、それはピンが既に接続されていることをチェックする。次に、接続処理の残りの部分を protected クラス メソッド AgreeMediaType に委任する。それ以降のすべては AgreeMediaType によって実行される。

メディア タイプが完全に指定されたら、ピンは AttemptConnection メソッドを呼び出す。そうでなければ、次の手順でピンは複数のメディア タイプを試す。

  1. 受信ピンが優先するタイプ。
  2. 接続ピンが優先するタイプ。

注意 この順番は m_bTryMyTypesFirst フラグを TRUE に設定することによって逆にできる。

それぞれの場合で、ピンは IPin::EnumMediaTypes を呼び出して、列挙オブジェクトを取得する。それは TryMediaTypes メソッドに列挙オブジェクトを渡す。このメソッドは列挙子が提供するすべてのメディア タイプについてループし、各タイプに AttemptConnection を呼び出す。

AttemptConnection 内で、接続ピンは次のメソッドを呼び出す :

  • CheckConnect: 受信ピンが適切かどうかをチェックする。
  • CheckMediaType: メディア タイプを有効にする。
  • IPin::ReceiveConnection (受信ピンで): 受信ピンが接続を受け入れるかどうかを決める。
  • CompleteConnect: 接続の完了。

以下に注意 :

  • CheckConnect は仮想メソッドである。基底クラスでは、ピンの向きに互換性があるかどうかチェックする。出力ピンは入力ピンにのみ接続し、入力ピンは出力ピンにのみ接続する。たとえば、あるインターフェイスに別のピンを問い合わせたり、そのインターフェイスをサポートしないピンを拒否したりする。
  • CheckMediaType は派生クラスが必ず実装しなければならない純粋仮想メソッドである。
  • CompleteConnect は基底クラスでは何も行わない仮想メソッドである。派生クラスはこのメソッドをオーバーライドして、メモリ アロケータの決定のような、接続を完了させるために必要な追加処理の実行メソッドをオーバーライドすることができる。

これらのステップが失敗すると、ピンは BreakConnect メソッドを呼び出して、CheckConnect によって行われたステップをすべて元に戻す。

受信サイドでは、ReceiveConnection は受信ピンの CheckConnect と CompleteConnect メソッドを呼び出す。これらのどちらかが失敗すると、接続の試みがまた失敗となる。

フィルタ状態の移行

ピンは、接続しているフィルタの状態が移行するたびに通知を受ける。次の表に示すように、フィルタはそれぞれの状態移行について、ピンの対応するメソッドを呼び出す。

フィルタ状態 | CBasePin メソッド
停止 | 非アクティブ
ポーズ | アクティブ
実行 | 実行

派生クラスはこれらのメソッドをオーバーライドし、状態移行に対応すべきである。フィルタによって、ピンはサンプルの出力、メモリ アロケータのコミット、コミット等を行うワーカースレッドを使う場合もある。

CBasePin からの派生

CBasePin を使ってピンを実装するには、基底クラスから新しいクラスを派生し、いくつかのメソッドをオーバーライドしなければならない。オーバーライドしなければならないのは、次のメソッドである。

  • CheckMediaType
  • GetMediaType

次のメソッドについても、オーバーライドが必要である可能性が高い。

  • Active
  • BreakConnect
  • CheckConnect
  • CompleteConnect
  • EndOfStream
  • Inactive
  • Notify
  • Run

最後に、必ず IPin::BeginFlush メソッドと IPin::EndFlush メソッドを実装しなければならない。

CBaseInputPin と CBaseOutputPin のように、これらのメソッドのいくつかは CBasePin から派生した基底クラスに実装されている。

Protected メンバ変数
m_pName | ピン名。
m_Connected | このピンに接続しているピンへのポインタ。
m_dir | ピンの向き。
m_pLock | クリティカル セクション オブジェクトへのポインタ。
m_bRunTimeError | ランタイム エラーが起きたかどうかを示すフラグ。
m_bCanReconnectWhenActive | ピンが動的再接続をサポートするかどうかを示すフラグ。
m_bTryMyTypesFirst | ピンが受信ピンの許容するメディア タイプの前に自分自身のそれを試みるかどうかを示すフラグ。
m_pFilter | ピンを作成したフィルタへのポインタ。
m_pQSink | 品質メッセージを扱うオブジェクトへのポインタ。
m_TypeVersion | 許容メディア タイプ セットの現在のバージョン。
m_mt | 現時のピン接続のメディア タイプ。
m_tStart | セグメント開始タイム。
m_tStop | セグメント終了タイム。
m_dRate | セグメント レート。
Protected メソッド
DisplayPinInfo | デバッグ中にピン接続をトレースする。
DisplayTypeInfo | デバッグ中にメディア タイプ情報を表示する。
AttemptConnection | 指定したメディア タイプを使用している他のピンへ接続する。
TryMediaTypes | メディア タイプのリストを与え、それらのタイプの 1 つを使用して接続を完了しようと試みる。
AgreeMediaType | ピン接続をするメディア タイプを調べる。
DisconnectInternal | 現在のピン接続を解除する。
Public メソッド
CBasePin | コンストラクタ メソッド。
~CBasePin | デストラクタ メソッド。 仮想。
IsConnected | ピンが他のピンと接続しているかどうかを確認する。
GetConnected | このピンに接続しているピンを取得。
IsStopped | このピンを含むフィルタが停止しているかどうかを確認する。
GetMediaTypeVersion | 許容するメディア タイプ セットのバージョン数を取得。 仮想。
IncrementTypeVersion | 許容するメディア タイプ セットのバージョン数をインクリメントする。
Active | ピンにフィルタが今アクティブであることを通知する。 仮想。
Inactive | ピンにフィルタが今既にアクティブではないことを通知する。 仮想。
Run | フィルタが今実行中であることをピンに知らせる。仮想。
SetMediaType | 接続するメディア タイプを設定する。 仮想。
CheckConnect | ピン接続が適切かどうかを確認する。 仮想。
BreakConnect | 接続からピンを解放する。 仮想。
CompleteConnect | 他のピンへの接続を完了する。仮想。
GetMediaType | 許容するメディア タイプをインデックス値で取得する。仮想。
CurrentStopTime | セグメント終了タイムを取得する。
CurrentStartTime | セグメント開始タイムを取得する。
CurrentRate | セグメント レートを取得する。
Name | ピンの識別名を取得する。
SetReconnectWhenActive | ピンが動的再接続をサポートするかどうかを指定する。
CanReconnectWhenActive | ピンが動的再接続をサポートするかどうかを問い合わせる。
Pure Virtual メソッド
CheckMediaType | ピンが指定したメディア タイプを受け入れるかを確認する。
IBasePin メソッド
Connect | ピンを他のピンに接続する。
ReceiveConnection | 他のピンからの接続を受け入れる。
Disconnect | 現在のピン接続を解除する。
ConnectedTo | このピンに接続しているピンを取得する。
ConnectionMediaType | もしあれば、現在のピン接続のメディア タイプを取得する。
QueryPinInfo | ピンについての情報を取得する。
QueryDirection | ピンの向き(入力か出力か)を取得する。
QueryId | ピンの ID を取得する。
QueryAccept | ピンが指定したメディア タイプを受け入れるかどうかを確認する。
EnumMediaTypes | ピンの許容するメディア タイプを列挙する。
QueryInternalConnections | (フィルタ内で) 内部的にこのピンに接続しているピンを取得する。
EndOfStream | ピンに追加データはもうないことを通知する。
NewSegment | セグメントとしてこの呼び出しがグループ化された後でメディア サンプルを受け取ったことをピンに知らせる。
IQualityControl メソッド
Notify | 品質変更が要求されたことをピンに通知する。
SetSink | 外部の品質マネージャを設定する。

CBasePin.m_pName

CBasePin クラス

ピン名。

構文

WCHAR *m_pName;

注意

The QueryPinInfo メソッドはこの文字列をピン名として返し、QueryId メソッドはそれをピン ID として返す。しかし一般的には、ピン名とピン ID は同じであると要求されてはいない。ピン ID はグラフで使用される。詳細については、「IBaseFilter::FindPin」を参照すること。

CBasePin.m_Connected

CBasePin クラス

このピンに接続しているピンへのポインタ。

構文

IPin *m_Connected;

CBasePin.m_dir

CBasePin クラス

ピンの向き。

構文

PIN_DIRECTION m_dir;

CBasePin.m_pLock

CBasePin クラス

クリティカル セクション オブジェクトへのポインタ。

構文

CCritSec *m_pLock;

CBasePin.m_bRunTimeError

CBasePin クラス

ランタイム エラーが起きたかどうかを示すフラグ。

構文

bool m_bRunTimeError;

注意

このフラグはデフォルトでは FALSE である。ストリーミング中にランタイム エラーが起きたら、このフラグを TRUE に設定すること。Inactive メソッドがこのフラグを FALSE に再設定する。

CBasePin.m_bCanReconnectWhenActive

CBasePin クラス

ピンが動的再接続をサポートするかどうかを示すフラグ。

構文

bool m_bCanReconnectWhenActive;

注意

このフラグはデフォルトでは FALSE である。

CBasePin.m_bTryMyTypesFirst

CBasePin クラス

ピンが受信ピンの許容するメディア タイプの前に自分自身のそれを試みるかどうかを示すフラグ。

構文

bool m_bTryMyTypesFirst;

注意

このフラグはデフォルトでは FALSE である。このフラグが TRUE なら、AgreeMediaType メソッドはメディア タイプを試みる順番を逆転させる。

CBasePin.m_pFilter

CBasePin クラス

ピンを作成したフィルタへのポインタ。

構文

CBaseFilter *m_pFilter;

CBasePin.m_pQSink

CBasePin クラス

品質メッセージを扱うオブジェクトへのポインタ。

構文

IQualityControl *m_pQSink;

CBasePin.m_TypeVersion

CBasePin クラス

許容メディア タイプ セットの現在のバージョン。

構文

LONG m_TypeVersion;

CBasePin.m_mt

CBasePin クラス

現時のピン接続のメディア タイプ。

構文

CMediaType m_mt;

CBasePin.m_tStart

CBasePin クラス

セグメント開始タイム。

構文

CRefTime m_tStart;

CBasePin.m_tStop

CBasePin クラス

セグメント終了タイム。

構文

CRefTime m_tStop;

CBasePin.m_dRate

CBasePin クラス

セグメント レート。

構文

double m_dRate;

CBasePin::Active

CBasePin クラス

ピンにフィルタが今アクティブであることを通知する。

構文

virtual HRESULT Active(void);

戻り値

S_OK を返す。

注意

フィルタが停止からポーズになるとき、CBaseFilter クラスは、フィルタの接続されたすべてピンにこのメソッドを呼び出す。

このメソッドは基底クラスでは何もしない。派生クラスはこのメソッドをオーバーライドできる、たとえば、ピンがアロケータをデコミットしたり、ハードウェア リソースを取得したり。

フィルタ グラフ マネージャの内部状態はこのメンバ関数が返るまでアップデートされないので、このメソッドから状態をテストすべきではない。

CBasePin::AgreeMediaType

CBasePin クラス

ピン接続をするメディア タイプを調べる。

構文

virtual HRESULT AgreeMediaType(
    IPin *pReceivePin,
    const CMediaType *pmt
);

パラメータ

pReceivePin
受信ピンの IPin インターフェイスへのポインタ。
pmt
メディア タイプを指定する CMediaType オブジェクトへのポインタ、あるいは NULL。

戻り値

HRESULT 値を返す。次の表は、可能な値を示している。

S_OK | 成功。
VFW_E_NO_ACCEPTABLE_TYPES | 受け入れ可能なメディア タイプは見つからなかった。

注意

pmt パラメータが NULL 以外で、メディア タイプを完全に指定したなら、このメソッドはそのメディア タイプを使って接続をしようとする。これが失敗すると、このメソッドはエラーを返す。

pmt パラメータが NULL あるいはパーシャル メディア タイプなら、このメソッドは次の順でメディア タイプを試みる :

  1. 受信ピンの許容するメディア タイプ。
  2. このピンの許容するメディア タイプ。

許容されたメディア タイプは EnumMediaTypes メソッドで列挙され、列挙された結果は TryMediaTypes メソッドに渡される。

CBasePin::AttemptConnection

CBasePin クラス

指定したメディア タイプを使用している他のピンへの接続。

構文

virtual HRESULT AttemptConnection(
    IPin *pReceivePin,
    const CMediaType *pmt
);

パラメータ

pReceivePin
受信ピンの IPin インターフェイスへのポインタ。
pmt
メディア タイプを指定する CMediaType オブジェクトへのポインタ。

戻り値

HRESULT 値を返す。次の表は、可能な値を示している。

S_OK | 成功。
VFW_E_TYPE_NOT_ACCEPTED | メディア タイプが受け入れられなかった。

注意

このメソッドは指定したメディア タイプで 2 つのピンを接続しようとする。そのタイプが受け入れられないと、このメソッドは他のメディア タイプを試みることなく失敗する。

メディア タイプが受け入れられたなら、このメソッドは受信ピンの IPin::ReceiveConnection メソッドを呼び出す。次に CompleteConnect メソッドを呼び出して、接続を完了する。

CBasePin::BreakConnect

CBasePin クラス

接続からピンを解放する

構文

virtual HRESULT BreakConnect(void);

戻り値

S_OK を返す。

注意

このメソッドは Disconnect メソッドによってピンが接続解除している間に呼び出される。CheckConnect メソッドが失敗すると、接続を試みる間にも呼び出される。

このメソッドは CheckConnect メソッドが取得したすべてのリソースをフリーにしなければならない。たとえば、CheckConnect でメモリを割り当てたなら、BreakConnect でメモリをフリーにすべきだ。CheckConnect でインターフェイスの接続ピンを問い合わせたなら、BreakConnect でインターフェイスをフリーにすべきだ。

CBasePin::CanReconnectWhenActive

CBasePin クラス

ピンが動的再接続をサポートするかどうかを問い合わせる。

構文

bool CanReconnectWhenActive(void);

戻り値

ピンが動的再接続可能かどうかを示すブール値を返す。TRUE なら、ピンは動的再接続可能。

注意

デフォルトでは、ピンの再接続をする前にフィルタを停止しなければならない。しかし、ピンが動的再接続をサポートするなら、フィルタがアクティブな間に再接続が可能である。詳細については、「動的グラフ作成」を参照すること。

CBasePin::CBasePin

CBasePin クラス

コンストラクタ メソッド。

構文

CBasePin(
    TCHAR *pObjectName,
    CBaseFilter *pFilter,
    CCritSec *pLock,
    HRESULT *phr,
    LPCWSTR pName,
    PIN_DIRECTION dir
);

パラメータ

pObjectName
オブジェクトのピン名が入る文字列のポインタ。詳細については、「CBaseObject」を参照すること。
pFilter
このピンを作成したフィルタへのポインタ。
pLock
CCritSec ロックへのポインタ、状態移行を継続するために用いられる。フィルタ ロック CBaseFilter.m_pLock として同じクリティカル セクションでありうる。
phr
メソッドの成功・失敗を示す HRESULT 値を受け取る変数へのポインタ。この値を S_OK に初期化してから、オブジェクトを作成する。この値は、エラーが発生した場合にだけ変更される。
pName
オブジェクトのピン名が入る Unicode™ 文字列。ピンの識別名はグラフ継続性をサポートする。詳細については、「QueryPinInfo」を参照すること。
dir
ピンの向きを指定する PIN_DIRECTION 列挙のメンバ。

注意

pLock によって指定されたクリティカル セクションはピンの状態を継続する、状態とは接続状態、アロケータの選択、メディア タイプ、フィラッシュ操作の状態を含む。このクリティカル セクションをストリーミング操作の継続に使ってはならない。詳細については、「フィルタ開発者が使用するデータ フロー」を参照すること。

フィルタはそのコンストラクタ メソッドでピンを作成する可能性があるので、この時 pFilter ポインタは有効なオブジェトを参照しない場合がある。ポインタをストアすること、しかしピンのコンストラクタ内の間はそれを再参照してはならない。

CBasePin::~CBasePin

CBasePin クラス

デストラクタ メソッド。

構文

CBasePin(void);

CBasePin::CheckConnect

CBasePin クラス

ピン接続が適切かどうかを確認する。

構文

virtual HRESULT CheckConnect(
    IPin *pPin
);

パラメータ

pPin
他のピンの IPin インターフェイスへのポインタ。

戻り値

以下の HRESULT 値の 1 つを返す。

S_OK | 成功。
VFW_E_INVALID_DIRECTION | ピンの向きに互換性がない。

注意

このメソッドは接続処理の終了時に両方のピンを呼び出される。接続ピンは CBasePin::Connect メソッドから呼び出し、受信ピンは CBasePin::ReceiveConnection メソッドから呼び出す。

このメソッドを使って pPin パラメータによって指定されたピンが接続に適しているかどうかを確認すること。両方のピンが同じ向き(両方とも入力、あるいは両方とも出力)なら、基底クラスはエラーを返す。派生クラスはこのメソッドをオーバーライドし、ピン内の他の機能を検証することができる。たとえば、CBaseOutputPin クラスは入力ピンにその IMemInputPin インターフェイスを問い合わせる。

このメソッドが失敗すると、接続は失敗しピンは BreakConnect メソッドを呼び出す。CheckConnect で取得したリソースをフリーにするには BreakConnect を使用すること。たとえば、CheckConnect が QueryInterface メソッドを呼び出すなら、BreakConnect はそのインターフェイスを解放しなければならない。

CBasePin::CheckMediaType

CBasePin クラス

ピンが指定したメディア タイプを受け入れるかをたずねる。

構文

virtual HRESULT CheckMediaType(
    const CMediaType *pmt
) PURE;

パラメータ

pmt
提案されたメディア タイプ含む CMediaType オブジェクトへのポインタ。

戻り値

提案されたメディア タイプが受け入れられるなら S_OK を返す。そうでなければ S_FALSE かエラー コードを返す。

注意

派生クラスはこの純粋仮想メソッドをオーバーライドしなければならない。

CBasePin::CompleteConnect

CBasePin クラス

他のピンへの接続を完了する。

構文

virtual HRESULT CompleteConnect(
    IPin *pReceivePin
);

パラメータ

pReceivePin
他のピンの IPin インターフェイスへのポインタ。

戻り値

S_OK を返す。

注意

このメソッドは接続処理の終わりに両方のピンで呼び出される。接続ピンは CBasePin::Connect 内から呼び出し、受信ピンは CBasePin::ReceiveConnection 内から呼び出す。

基底クラスでは、このメソッドはただ S_OK を返すだけである。派生クラスが接続を完了する要求を持っているなら、このメソッドをオーバーライドすべきだ。たとえば、CBaseOutputPin クラスはこのメソッドを使用して、メモリ アロケータを決定する。

このメソッドが失敗すると、すべての接続の試みも失敗し、ピンは受信ピンから切り離される。

CBasePin::Connect

CBasePin クラス

ピンを他のピンに接続する。 IPin::Connect メソッドの実装。

構文

HRESULT Connect(
    IPin *pReceivePin,
    const AM_MEDIA_TYPE *pmt
);

パラメータ

pReceivePin
受信ピンの IPin インターフェイスへのポインタ。
pmt
接続のメディア タイプを指定する AM_MEDIA_TYPE 構造体へのポインタ。

戻り値

HRESULT 値を返す。次の表は、可能な値を示している。

S_OK | 成功。
VFW_E_ALREADY_CONNECTED | ピンは既に接続している。
VFW_E_NO_ACCEPTABLE_TYPES | 許容可能なメディア タイプを発見できない。
VFW_E_NOT_STOPPED | フィルタがアクティブで、ピンは動的再接続をサポートしていない。
VFW_E_TYPE_NOT_ACCEPTED | 指定したメディアタイプは受け入れられない。

注意

pmt パラメータは NULL を取り得る。メジャー タイプやサブタイプやフォーマットを GUID_NULL 値にすることで、それはパーシャル メディア タイプをも指定し得る。

基底クラスでは、このメソッドはピンがすでに接続されているか、フィルタが停止しているかをテストする。接続処理の残りは AgreeMediaType メソッドに委任する。/P>

CBasePin::ConnectedTo

CBasePin クラス

もしあれば、このピンに接続しているピンを取得する。 IPin::ConnectedTo メソッドの実装。

構文

HRESULT ConnectedTo(
    IPin **ppPin
);

パラメータ

ppPin
他のピンの IPin インターフェイスへのポインタを取得する変数のアドレス。

戻り値

HRESULT 値を返す。次の表は、可能な値を示している。

S_OK | 成功。
E_POINTER | NULL ポインタ引数。
VFW_E_NOT_CONNECTED | ピンが接続されていない。

注意

このメソッドが成功すると、それが返す IPin インターフェイスには参照カウントが残る。解放時には注意が必要。

CBasePin::ConnectionMediaType

CBasePin クラス

もしあれば、現在のピン接続のメディア タイプを取得する。IPin::ConnectionMediaType メソッドの実装。

構文

HRESULT ConnectionMediaType(
    AM_MEDIA_TYPE *pmt
);

パラメータ

pmt
メディア タイプを受け取る AM_MEDIA_TYPE 構造体へのポインタ。

戻り値

HRESULT 値を返す。次の表は、可能な値を示している。

S_OK | 成功。
E_POINTER | Null ポインタ引数。
VFW_E_NOT_CONNECTED | ピンが接続されていない。

注意

ピンが接続されているなら、このメソッドはメディア タイプを pmt によって指定される AM_MEDIA_TYPE 構造体にコピーする。呼び出し元はメディア タイプのフォーマット ブロックをフリーにしなければならない。Microsoft® Win32® CoTaskMemFree を使用する、あるいは FreeMediaType ヘルパ 関数を使用することができる。

もしピンが接続されていないなら、このメソッドは pmt によって指定されたメモリ ブロックをゼロにし、エラー コードを返す。

CBasePin::CurrentRate

CBasePin クラス

CBasePin::NewSegment メソッドによってセットされたセグメント レートを取得する。

構文

double CurrentRate(void);

戻り値

m_dRate の戻り値。

CBasePin::CurrentStartTime

CBasePin クラス

CBasePin::NewSegment メソッドによってセットされたセグメント開始タイムを取得する。

構文

REFERENCE_TIME CurrentStartTime(void);

戻り値

m_tStart の戻り値。

CBasePin::CurrentStopTime

CBasePin クラス

CBasePin::NewSegment メソッドによってセットされたセグメント終了タイムを取得する。

構文

REFERENCE_TIME CurrentStopTime(void);

戻り値

m_tStop の値を返す。

CBasePin::Disconnect

CBasePin クラス

現在のピン接続を解除する。 IPin::Disconnect メソッドの実装。

構文

HRESULT Disconnect(void);

戻り値

HRESULT 値を返す。次の表は、可能な値を示している。

S_FALSE | ピンが接続されていない。
S_OK | 成功。
VFW_E_NOT_STOPPED | フィルタがアクティブで、ピンは動的再接続をサポートしていない。

注意

基底クラスは仕事の大部分を DisconnectInternal メソッドに委任する。

CBasePin::DisconnectInternal

CBasePin クラス

現在のピン接続を解除する。

構文

HRESULT DisconnectInternal(void);

戻り値

HRESULT 値を返す。次の表は、可能な値を示している。

S_FALSE | ピンが接続されていない。
S_OK | 成功。
VFW_E_NOT_STOPPED | フィルタがアクティブで、ピンは動的再接続をサポートしていない

注意

Disconnect メソッドは接続処理をこのメソッドに委任する。このメソッドは BreakConnect メソッドを呼び出す。それはまた m_Connected メンバ変数によって保持されている他のピンの参照カウントを解放する。

CBasePin::DisplayPinInfo

CBasePin クラス

デバッグ中にピン接続をトレースする。

構文

void DisplayPinInfo(
    IPin *pReceivePin
);

パラメータ

pReceivePin
受信ピンへのポインタ

注意

デバッグ ビルドでは、このメソッドは DbgLog 関数を呼び出し、接続の試みをトレースする。リテール ビルドではこのメソッドは何もしない。

CBasePin::DisplayTypeInfo

CBasePin クラス

デバッグ中にメディア タイプ情報を表示する。

構文

void DisplayTypeInfo(
    IPin *pPin,
    const CMediaType *pmt
);

パラメータ

pPin
無視される。
pmt
メディア タイプを指定する CMediaType オブジェクトへのポインタ。

注意

デバッグ ビルドでは、このメソッドは DbgLog 関数を呼び出し、接続の試みをトレースする。リテール ビルドではこのメソッドは何もしない。

CBasePin::EndOfStream

IPin Interface

ピンに追加データはもうないことを通知する。 IPin::EndOfStream メソッドの実装。このメソッドは入力ピンでのみ呼び出すこと。

構文

HRESULT EndOfStream(void);

戻り値

S_OK を返す。

注意

フィルタはエンドオブストリーム通知ダウンストリームをフィルタに接続している入力ピンに渡すべきである。フィルタがレンダラなら、EC_COMPLETE イベント通知をフィルタ グラフ マネージャに送るべきである。詳細については、「フィルタ開発者が使用するデータ フロー」を参照すること。

基底クラスでは、このメソッドは何もしない。派生クラスはこのメソッドをオーバーライドすべきである。

CBasePin::EnumMediaTypes

CBasePin クラス

ピンの許容するメディア タイプを列挙する。IPin::EnumMediaTypes メソッドの実装。

構文

HRESULT EnumMediaTypes(
    IEnumMediaTypes **ppEnum
);

パラメータ

ppEnum
IEnumMediaTypes インターフェイスへのポインタを受け取る変数のアドレス。

戻り値

HRESULT 値を返す。次の表は、可能な値を示している。

S_OK | 成功。
E_OUTOFMEMORY | メモリ不足。
E_POINTER | NULL ポインタ引数。

注意

入力ピンは許容できるタイプの列挙を要求されない。出力ピンは少なくとも 1 つの許容タイプを列挙しなければならない。そうしないと、両方のピンに許容可能なタイプがなくなり、接続が不可能になる。

標準的な COM 列挙子と同様に IEnumMediaTypes インターフェイスは動作する。詳細については、「フィルタ グラフ内のオブジェクトの列挙」を参照すること。メソッドが成功すると、IEnumMediaTypes インターフェイスには参照カウントが残る。解放時には注意が必要。

CEnumMediaTypes 基底クラスは IEnumMediaTypes を実装する。それはピンの CBasePin::GetMediaType メソッドを呼び出して、メディア タイプを列挙する。

CBasePin::GetConnected

CBasePin クラス

このピンに接続しているピンを取得。

構文

IPin *GetConnected(void);

戻り値

他のピンの IPin インターフェイスへのポインタを返す。

注意

ピンが接続していなければ、このメソッドは NULL を返す。CBasePin::IsConnected メソッドを呼び出して、ピンが接続されているかどうかを確認すること。

CBasePin::GetMediaType

CBasePin クラス

許容するメディア タイプをインデックス値で取得する。

構文

virtual HRESULT GetMediaType(
    int iPosition,
    CMediaType *pMediaType
);

パラメータ

iPosition
ゼロから始まるインデックス値。
pMediaType
メディア タイプを取得する CMediaType オブジェクトへのポインタ。

戻り値

HRESULT 値を返す。次の表は、可能な値を示している。

S_OK | 成功。
VFW_S_NO_MORE_ITEMS | インデックスが範囲外である。
E_INVALIDARG | インデックスがゼロより小さい。
E_UNEXPECTED | 予期しないエラー。

注意

ピンが許容可能なメディア タイプのリストから、このメソッドは iPosition 値でそのタイプを返す。CEnumMediaTypes クラスはこのメソッドを呼び出して許容可能なメディア タイプを列挙する。

基底クラスは E_UNEXPECTED を返す。派生クラスでこのメソッドをオーバーライドすること。

CBasePin::GetMediaTypeVersion

CBasePin クラス

許容するメディア タイプ セットのバージョン数を取得。

構文

virtual LONG GetMediaTypeVersion(void);

戻り値

m_TypeVersion メンバ変数を返す。

注意

CBasePin コンストラクタはバージョン数を 1 で初期化する。基底クラスでは、この数は決して変化しない。ピンが動的に許容可能なメディア タイプのリストを変更するなら、リストが変更されるたびにバージョン数をインクリメントするべきである。バージョン数をインクリメントするには、IncrementTypeVersion メソッドを呼び出すこと。

CEnumMediaTypes クラスによって実装されるメディア タイプ列挙子は、バージョン数を使ってそれ自身とピンとの同期を保つ。

CBasePin::Inactive

CBasePin クラス

ピンにフィルタが今既にアクティブではないことを通知する。

構文

virtual HRESULT Inactive(void);

戻り値

S_OK を返す。

注意

フィルタが停止すると、CBaseFilter クラスはフィルタに接続されたのすべてのピンで、このメソッドを呼び出す。

このメソッドは基底クラスでは何もしない。派生クラスはこのメソッドをオーバーライドし、Active メソッドが取得したすべてのリソースをフリーにすべきである、たとえばピンのアロケータをデコミットにする。

フィルタ グラフ マネージャの内部状態はこのメソッドが返るまでアップデートされないので、このメソッドから状態をテストしてはならない。

CBasePin::IncrementTypeVersion

CBasePin クラス

許容するメディア タイプ セットのバージョン数をインクリメントする。

構文

void IncrementTypeVersion(void);

注意

このメソッドは m_TypeVersion メンバ変数をインクリメントする。ピンが動的に許容するメディア タイプのリストを変更するなら、リストが変更されるたびにこのメソッドを呼び出すこと。詳細については、「GetMediaTypeVersion」を参照すること。

CBasePin::IsConnected

CBasePin クラス

ピンが他のピンと接続しているかどうかを確認する。

構文

BOOL IsConnected(void);

戻り値

ピンが接続されていれば TRUE を返す。そうでなければ FALSE を返す。

CBasePin::IsStopped

CBasePin クラス

このピンを含むフィルタが停止しているかどうかを確認する。

構文

BOOL IsStopped(void);

戻り値

フィルタが停止していれば TRUE を返す。そうでなければ FALSE を返す。

注意

CBasePin コンストラクタ メソッド内からこのメソッドを呼び出してはならない、なぜならフィルタはまだ初期化されていない可能性があるからである。

CBasePin::Name

CBasePin クラス

ピンの識別名を取得する。

構文

LPWSTR Name(void);

戻り値

m_pName メンバ変数の値を返す。

CBasePin::NewSegment

CBasePin クラス

セグメントとしてこの呼び出しがグループ化された後でメディア サンプルを受け取ったことをピンに知らせる。 IPin::NewSegment メソッドの実装。

構文

HRESULT NewSegment(
    REFERENCE_TIME tStart,
    REFERENCE_TIME tStop,
    double dRate
);

パラメータ

tStart
セグメントの開始メディア位置、100 ミリ秒単位。
tStop
セグメントの終了メディア位置、100 ミリ秒単位。
dRate
セグメントが処理されるべきレート、オリジナル レートのパーセンテージ。

戻り値

S_OK を返す。

注意

このメソッドは m_tStart と m_tStop と m_dRate メンバ変数を設定する。派生クラスでは、このメソッドをオーバーライドして、通知ダウンストリームに渡すこと。

CBasePin::Notify

CBasePin クラス

品質変更が要求されたことをピンに通知する。IQualityControl::Notify メソッドの実装。

構文

HRESULT Notify(
    IBaseFilter *pSelf,
    Quality q
);

パラメータ

pSelf
品質コントロール メッセージを出力するフィルタの IBaseFilter インターフェイスへのポインタ。
q
品質コントロール メッセージを含む Quality 構造体。

戻り値

基底クラスは E_NOTIMPL を返す。

注意

出力ピンはこのメソッドをオーバーライドして品質コントロール メッセージを受けれるべきである。

外部の品質コントロール マネージャがインストールされているなら (「SetSink」を参照)、メッセージをその品質マネージャに渡すこと。そうでなければ、フィルタはそのメッセージを自分自身で扱う、あるいはメッセージ アップストリームに送るべきである。詳細については、「品質コントロールの管理」を参照すること。

CBasePin::QueryAccept

CBasePin クラス

ピンが指定したメディア タイプを受け入れるかどうかを確認する。IPin::QueryAccept メソッドの実装。

構文

HRESULT QueryAccept(
    const AM_MEDIA_TYPE *pmt
);

パラメータ

pmt
メディア タイプを指定する AM_MEDIA_TYPE 構造体へのポインタ。

戻り値

メディア タイプが受け入れ可能なら S_TRUE を返す。そうでなければ、S_FALSE を返す。

注意

基底クラスでは、このメソッドは CheckMediaType メソッドに委任する。CheckMediaType が失敗すると、QueryAccept は S_FALSE を返す。

このメソッドはピンのクリティカル セクション (m_pLock) を保持しない。派生クラスで動的に許容可能なメディア タイプ セットを修正するなら、このメソッドをオーバーライドしてクリティカル セクションをホールドすべきである。

CBasePin::QueryDirection

CBasePin クラス

ピンの向き (入力か出力か) を取得する。 IPin::QueryDirection メソッドの実装。

構文

HRESULT QueryDirection(
    PIN_DIRECTION *pPinDir
);

パラメータ

pPinDir
PIN_DIRECTION 列挙型のメンバを受け取る変数へのポインタ。

戻り値

S_OK あるいは E_POINTER を返す。

CBasePin::QueryId

CBasePin クラス

ピンの ID を取得する。 IPin::QueryId メソッドの実装。

構文

HRESULT QueryId(
    LPWSTR *Id
);

パラメータ

Id
ピンの ID へのポインタ。

戻り値

HRESULT 値を返す。次の表は、可能な値を示している。

S_OK | 成功。
E_OUTOFMEMORY | メモリ不足。
E_POINTER | NULL ポインタ引数。

注意

このメソッドは m_pName メンバ変数を返す。

CBasePin::QueryInternalConnections

CBasePin クラス

(フィルタ内で) 内部的にこのピンに接続しているピンを取得する。 IPin::QueryInternalConnections メソッドの実装。

構文

HRESULT QueryInternalConnections(
    IPin *apPin,
    ULONG *nPin
);

パラメータ

apPin
IPin ポインタの配列のアドレス。
nPin
入力では、配列のサイズを指定。このメソッドが返るとき、この値は配列に戻ったポインタの数がセットされる。

戻り値

次の HRESULT 値の 1 つが返る。

S_FALSE | 配列のサイズが不適当。
S_OK | 成功。
E_FAIL | 失敗。
E_NOTIMPL | 実装されていない。

基底クラスは E_NOTIMPL を返す。

注意

いくつかのフィルタでは、入力ピンは固有の出力ピンに対応している。各ピンで、このメソッドは対応するピンのポインタで配列を埋める。すべての入力ピンがすべての出力ピンにデータを提供する場合は E_NOTIMPL をかえす。

CBasePin::QueryPinInfo

CBasePin クラス

ピンについての情報を取得する。IPin::QueryPinInfo メソッドの実装。

構文

HRESULT QueryPinInfo(
    PIN_INFO *pInfo
);

パラメータ

pInfo
ピン情報を受け取る PIN_INFO 構造体へのポインタ。

戻り値

S_OK あるいは E_POINTER を返す。

注意

このメソッドはPIN_INFO 構造体の achName メンバに対して m_pName メンバ変数を使う。

メソッドが返るとき、PIN_INFO 構造体の pFilter メンバが NULL 以外なら、参照カウントが残っている。そのインターフェイスを解放する際には注意が必要。

CBasePin::ReceiveConnection

CBasePin クラス

他のピンからの接続を受け入れる。 IPin::ReceiveConnection メソッドの実装。

構文

HRESULT ReceiveConnection(
    IPin *pConnector,
    AM_MEDIA_TYPE *pmt
);

パラメータ

pConnector
接続ピンの IPin インターフェイスへのポインタ。
pmt
メディア タイプを指定する AM_MEDIA_TYPE 構造体へのポインタ。

戻り値

HRESULT 値を返す。次の表は、可能な値を示している。

S_OK | 成功。
E_POINTER | Null ポインタ引数。
VFW_E_ALREADY_CONNECTED | ピンは既に接続している。
VFW_E_NOT_STOPPED | フィルタがアクティブで、ピンは動的再接続をサポートしていない
VFW_E_TYPE_NOT_ACCEPTED | 指定したメディアタイプは受け入れられない。

注意

接続を始めようとするピンは受信ピンでこのメソッドを呼び出す。受信ピンがエラー コードを返すなら、接続は失敗する。

基底クラスでは、このメソッドは次のステップを実行する :

  • ピンが既に接続していないかどうかチェックする。
  • フィルタが停止していないかどうかチェックする。
  • CheckConnect メソッドを呼び出して接続ピンが適切かどうかテストする。
  • Calls CheckMediaType メソッドを呼び出してメディア タイプが受け入れ可能かどうかテストする。

これらのすべてのステップが成功すると、このメソッドは CompleteConnect メソッドとSetMediaType メソッドを呼び出して接続を完了する。CheckConnect か CheckMediaType が失敗すると、このメソッドは BreakConnect メソッドを呼び出す。

CBasePin::Run

CBasePin クラス

フィルタが今実行中であることをピンに知らせる。

構文

HRESULT Run(
    REFERENCE_TIME tStart
);

パラメータ

tStart
フィルタの IMediaFilter::Run メソッドに送られる開始タイム。

戻り値

S_OK を返す。

注意

フィルタがポーズから実行になるとき、CBaseFilter クラスはフィルタのすべてのピンでこのメソッドを呼び出す。

このメソッドは基底クラスでは何もしない。派生クラスはこのメソッドをオーバーライドできる。たとえば、あるピンはサンプルを出力するワーカー スレッドを開始するかもしれない。

フィルタ グラフ マネージャの内部状態はこのメンバ関数が返るまでアップデータされないので、このメソッドから状態をテストしてはならない。

CBasePin::SetMediaType

CBasePin クラス

接続するメディア タイプを設定する。

構文

virtual HRESULT SetMediaType(
    const CMediaType *pmt
);

パラメータ

pmt
メディア タイプを指定する CMediaType オブジェクトへのポインタ。

戻り値

S_OK を返す。

注意

このメソッドはピン接続のフォーマットを確立する。このメソッドを呼び出す前に、ピンは CBasePin::CheckMediaType メソッドを呼び出してメディア タイプが受け入れ可能かどうかを確認する。したがって、pmt パラメータは受け入れ可能なメディアタイプとして仮定されている。

基底クラスでは、このメソッドは m_mt メンバ変数をセットし、S_OK を返す。メディア タイプがセットされたとき派生クラスが通知を要求するなら、その派生クラスはこのメソッドをオーバーライドできる。

CBasePin::SetReconnectWhenActive

CBasePin クラス

ピンが動的再接続をサポートするかどうかを指定する。

構文

void SetReconnectWhenActive(
    bool bCanReconnect
);

パラメータ

bCanReconnect
ピンが動的再接続をサポートするかどうかを示すブール値。TRUE ならピンは動的再接続が可能。

注意

デフォルトではピンへの再接続の前にフィルタを停止させなければならない。フィルタがアクティブな間に再接続できるのなら、このメソッドを値を TRUE にして呼び出すこと。詳細については、「動的グラフ作成」を参照すること。

CBasePin::SetSink

CBasePin クラス

外部の品質マネージャを設定する。 IQualityControl::SetSink メソッドの実装。

構文

HRESULT SetSink(
    IQualityControl *piqc
);

パラメータ

piqc
品質マネージャの IQualityControl インターフェイスへのポインタ。

戻り値

S_OK を返す。

注意

このメソッドを呼び出して品質コントロール マネージャを外部の品質マネージャにリダイレクトすること。詳細については、「品質コントロールの管理」を参照すること。

CBasePin::TryMediaTypes

CBasePin クラス

メディア タイプのリストを与え、それらのタイプの 1 つを使用して接続を完了しようと試みる。

構文

virtual HRESULT TryMediaTypes(
    IPin *pReceivePin,
    const CMediaType *pmt,
    IEnumMediaTypes *pEnum
);

パラメータ

pReceivePin
受信ピンの IPin インターフェイスへのポインタ。
pmt
可能なメディア タイプを限定する CMediaType オブジェクトへのポインタ、あるいは NULL。
pEnum
メディア タイプ リストを列挙するのに用いた IEnumMediaTypes インターフェイスへのポインタ。

戻り値

HRESULT 値を返す。次の表は、可能な値を示している。

S_OK | 成功。
VFW_E_NO_ACCEPTABLE_TYPES | 受け入れ可能なメディアタイプがない。

注意

IEnumMediaTypes インターフェイスが返した各メディア タイプで、このメソッドは AttemptConnection メソッドを呼び出して接続を試みる。

pmt パラメータが NULL 以外なら、ピンはこのタイプに適合しないメディア タイプをスキップする。pmt パラメータにはパーシャル メディア タイプを指定することができる。パーシャル メディア タイプはメジャー タイプ、サブタイプ、フォーマットのいずれかが GUID_NULL 値を持つ。GUID_NULL 値は「ワイルドカード」値のようにどんなタイプとも適合する。


CBasePropertyPage クラス

フィルタにプロパティ ページを実装して、フィルタのカスタム プロパティへのアクセスを提供できる。GraphEdit はこれらのプロパティ ページを表示するので、これはフィルタの開発およびデバッグに便利である。また、Microsoft® Windows Media™ Player コントロールは、その下位のフィルタ グラフ内のフィルタに、サポートするプロパティ ページを問い合わせ、それをユーザーに対して公開する。この例として、プロパティ ページを使用して品質管理情報を公開するビデオ レンダラがある。

このクラスは、フィルタに関連付けられたプロパティ ページのフレームワークを提供し、IPropertyPage インターフェイスを実装する。プロパティ ページは Component Object Model (COM) オブジェクトであり、必要に応じてロードされるダイアログ ボックスのリソース ID を使用して作成する必要がある。また、作成時にタイトル文字列のリソース ID も指定しなければならない。

IPropertyPage インターフェイス メソッドの実装に加えて、このクラスは派生クラスでオーバーライドして特殊化することができるいくつかの仮想メンバ関数 (デフォルトでは NOERROR を返す) を提供する。これらの仮想メンバ関数は、特定のイベントが発生すると呼び出される。たとえば、プロパティ ページがアクティブまたは非アクティブされたとき、接続または切断されたとき、プロパティに対する変更が適用されたとき、ダイアログ ボックスへのメッセージが受信されたときなどである。

カスタム プロパティ ページを公開するフィルタは、カスタム インターフェイスを使用してアプリケーションにも同じ機能を公開する必要がある。機能を公開しないと、アプリケーションはプロパティ ページを表示せずにフィルタを制御することができない。たとえば、ビデオ レンダラは IQualProp インターフェイスをサポートして、同じ品質管理情報にアクセスする。実際、レンダラのプロパティ ページは、このインターフェイスを使用してプロパティ ページの情報を取得する。アプリケーションが容易にカスタム インターフェイスにアクセスできるように、フィルタは PID も実装する必要がある。PID は、フィルタ グラフ マネージャによって集成されたオブジェクトである。通常、PID はアプリケーションからフィルタ インターフェイスに呼び出しを渡すことによって、関連付けられたフィルタのインターフェイスを実装する。

プロテクト データ メンバ

m_bDirty | 何かが変更されたかどうかを示すフラグ。
m_DialogId | ダイアログ ボックスのリソース識別子。
m_Dlg | プロパティ ページのダイアログ ボックス ウィンドウ ハンドル。
m_hwnd | プロパティ ページのウィンドウ ハンドル。
m_pPageSite | フィルタのプロパティ情報にアクセスするために使用される IPropertyPage インターフェイスのポインタ。
m_TitleId | プロパティ ページのタイトルのリソース識別子。

メンバ関数

CBasePropertyPage CBasePropetyPage オブジェクトを作成する。

オーバーライド可能なメンバ関数

OnActivate | プロパティ ページがアクティブにされたときに呼び出される。
OnApplyChanges | ユーザーがプロパティ ページに対する変更を適用したときに呼び出される。
OnConnect | プロパティ ページがフィルタに接続されたときに呼び出される。
OnDeactivate | プロパティ ページが消去されたときに呼び出される。
OnDisconnect | プロパティ ページが所有するフィルタから切断されたときに呼び出される。
OnReceiveMessage | メッセージがプロパティ ページのダイアログ ボックス ウィンドウに送信されたときに呼び出される。

実装される INonDelegatingUnknown メソッド

NonDelegatingAddRef | デフォルトの実装は、所有するフィルタの参照カウントをインクリメントする。
NonDelegatingQueryInterface | CBasePropertyPage インターフェイスを取得するために呼び出される。派生クラスで追加されるインターフェイスにポインタを渡すには、このメンバ関数をオーバーライドする。
NonDelegatingRelease | デフォルトの実装は、所有するフィルタの参照カウントをデクリメントする。

実装される IPropertyPage メソッド

Activate | プロパティ ページのダイアログ ボックス ウィンドウを作成する。
Apply | 現在のプロパティ ページの値を下位のオブジェクトに適用する。
Deactivate | CBasePropertyPage::Activate で作成したウィンドウを破棄する。
GetPageInfo | プロパティ ページに関する情報を取得する。
Help | ユーザー要求に応答してヘルプを呼び出す。
IsPageDirty | プロパティ ページが、アクティブにされた後、または CBasePropertyPage::Apply を最後に呼び出した後、変更されたかどうかを示す。
Move | プロパティ ページのダイアログ ボックスをフレーム内に配置およびサイズ変更する。
SetObjects | このプロパティ ページに関連付けられたオブジェクトの IUnknown ポインタの配列をプロパティ ページに提供する。
SetPageSite | プロパティ ページを初期化し、プロパティ ページがプロパティ フレームと通信するために使用する IPropertyPageSite インターフェイスへのポインタをプロパティ ページに提供する。
Show | プロパティ ページのダイアログ ボックスを表示または非表示にする。
TranslateAccelerator | 処理するキーストロークを指定する MSG 構造体へのポインタを提供する。

CBasePropertyPage::Activate

CBasePropertyPage クラス

プロパティ ページのダイアログ ボックスを作成する。

構文

HRESULT Activate(
HWND hwndParent,
LPCRECT prect,
BOOL fModal
    );

パラメータ

hwndParent
ダイアログ ボックスの親ウィンドウのハンドル。
prect
ダイアログ ボックスの画面上の位置を格納する RECT 構造体へのポインタ。
fModal
TRUE の場合はモーダル ダイアログ ボックス、FALSE の場合はモードレス ダイアログ ボックスを指定する値。

戻り値

ダイアログ ボックスの作成に失敗した場合は E_OUTOFMEMORY、プロパティ ページが既に存在している場合は E_UNEXPECTED を返す。

注意

このメンバ関数は、COM の IPropertyPage::Active メソッドを実装する。このメソッドは、親ウィンドウとして hwndParent を、配置矩形として prect を使用して、(フレーム、キャプション、システム メニュー、またはコントロールのない) プロパティ ページのダイアログ ボックスを作成する。

プロパティ ページはこの処理で作成したウィンドウ ハンドルを保持し、CBasePropertyPage::Deactivate でこのダイアログ ボックスを破棄するときに使用する。

CBasePropertyPage::Apply

CBasePropertyPage クラス

現在のプロパティ ページの値を下位のオブジェクトに適用する。

構文

HRESULT Apply(void);

戻り値

CBasePropertyPage::SetObjects が呼び出されていない場合、または m_pPageSite データ メンバがフィルタのプロパティ ページへのポインタを使用して初期化されていない場合は、E_UNEXPECTED を返す。

注意

このメンバ関数は、COM の IPropertyPage::Apply メソッドを実装する。変更されるオブジェクトは、CBasePropertyPage::SetObjects への以前の呼び出しによって提供される。これは、フィルタの IUnknown インターフェイスでなければならない。したがって、このメンバ関数は、インターフェイスが存在しない場合に失敗してはならない。

このメンバ関数は、m_bDirty データ メンバを FALSE に設定し、仮想メンバ関数 CBasePropertyPage::OnApplyChanges を呼び出す。プロパティに対する変更を適用するには、派生クラスでこの仮想メンバ関数をオーバーライドする必要がある。

CBasePropertyPage::CBasePropertyPage

CBasePropertyPage クラス

CBasePropetyPage オブジェクトを作成する。

構文

CBasePropertyPage(
TCHAR *pName,
LPUNKNOWN pUnk,
int DialogId,
int TitleId
    );

パラメータ

pName
デバッグのために使用されるプロパティ ページ オブジェクトの名前へのポインタ。
pUnk
COM 委任オブジェクトへのポインタ。
DialogId
ダイアログ ボックスのリソース ID。
TitleId
ダイアログ ボックスのタイトルのリソース ID。

注意

このコンストラクタは、CBasePropertyPage データ メンバを次のように設定する。

  • m_DialogId は DialogId に設定される。
  • m_TitleId は TitleId に設定される。
  • m_hwnd は NULL に設定される。
  • m_Dlg は NULL に設定される。
  • m_pPageSite は NULL に設定される。
  • m_bDirty は FALSE に設定される。

CBasePropertyPage::Deactivate

CBasePropertyPage クラス

CBasePropertyPage::Activate で作成したウィンドウを破棄する。

構文

HRESULT Deactivate(void);

戻り値

データ メンバ m_hwnd がプロパティ ページのウィンドウ ハンドルを含んでいない場合は、E_UNEXPECTED を返す。

注意

このメンバ関数は、COM の IPropertyPage::Deactivate メソッドを実装する。このメンバ関数は、仮想メンバ関数 CBasePropertyPage::OnDeactivate を呼び出して、プロパティ ページのダイアログ ボックスを破棄する。

CBasePropertyPage::GetPageInfo

CBasePropertyPage クラス

プロパティ ページに関する情報を取得する。

構文

HRESULT GetPageInfo(
LPPROPPAGEINFO pPageInfo
    );

パラメータ

pPageInfo
プロパティ ページがそのページ情報を格納する、呼び出し元割り当て済み PROPPAGEINFO 構造体へのポインタ。この構造体に格納されるすべての割り当ては、呼び出し元の責任になる。

戻り値

関数がプロパティ ページのタイトルにメモリを割り当てることができなかった場合は、E_OUTOFMEMORY を返す。

注意

このメンバ関数は、COM の IPropertyPage::GetPageInfo メソッドを実装する。このメンバ関数は、GetDialogSize 関数を呼び出して、ダイアログ ボックスのサイズを取得し、この呼び出しが失敗した場合はダイアログ ボックスのサイズをデフォルト値に設定する。

CBasePropertyPage::Help

CBasePropertyPage クラス

ユーザー要求に応答してヘルプを呼び出す。

構文

HRESULT Help(
LPCWSTR lpszHelpDir
    );

パラメータ

lpszHelpDir
レジストリ内でプロパティ ページの CLSID 情報の HelpDir キーの下にある文字列へのポインタ。HelpDir が存在しない場合は、InProcServer32 エントリで見つかったパスからサーバー ファイル名を除いたものになる。

戻り値

デフォルトでは E_NOTIMPL を返す。

注意

このメンバ関数は、COM の IPropertyPage::Help メソッドを実装するが、プレースホルダとしてである。この関数は、E_NOTIMPL を返す以外は何もしない。

このメンバ関数の呼び出しは、CBasePropertyPage::Activate の呼び出しと CBasePropertyPage::Deactivate の呼び出しの間で行う必要がある。

ページがこのメンバ関数で失敗した場合 (E_NOTIMPL など)、フレームは CBasePropertyPage::GetPageInfo を使用して取得された PROPPAGEINFO 構造体の pszHelpFile および dwHelpContext フィールドを使用しようとする。したがって、派生クラスは CBasePropertyPage::Help を実装するか、CBasePropertyPage::GetPageInfo を使用してヘルプ情報を返す必要がある。

CBasePropertyPage::IsPageDirty

CBasePropertyPage クラス

プロパティ ページが、アクティブにされた後、または CBasePropertyPage::Apply を最後に呼び出した後、変更されたかどうかを示す。

構文

HRESULT IsPageDirty(void);

戻り値

プロパティ ページの値の状態がダーティーである場合、つまり、値が変更され、オブジェクトの状態と異なる場合は、S_OK を返す。ページの値の状態が変更されておらず、オブジェクトの現在の状態と同じである場合は、S_FALSE を返す。

注意

このメンバ関数は、COM の IPropertyPage::IsPageDirty メソッドを実装する。このメンバ関数は、m_bDirty データ メンバの値を返す。

CBasePropertyPage::Move

CBasePropertyPage クラス

プロパティ ページのダイアログ ボックスをフレーム内に配置およびサイズ変更する。

構文

HRESULT Move(
LPCRECT prect
    );

パラメータ

prect
プロパティ ページのダイアログ ボックスの位置情報を格納する RECT 構造体へのポインタ。

戻り値

データ メンバ m_hwnd がプロパティ ページのウィンドウ ハンドルを含んでいない場合は、E_UNEXPECTED を返す。

注意

このメンバ関数は、Microsoft® Win32® MoveWindow 関数を呼び出すことによって、COM の IPropertyPage::Move メソッドを実装する。このメンバ関数は、プロパティ ページのダイアログ ボックスを配置するために、CBasePropertyPage::Activate メンバ関数から呼び出される。

CBasePropertyPage::NonDelegatingAddRef

CBasePropertyPage クラス

インターフェイスの参照カウントをインクリメントする。

構文

ULONG NonDelegatingAddRef(void);

戻り値

オブジェクトの参照カウントを返す。

注意

このメンバ関数は、INonDelegatingUnknown::NonDelegatingAddRef メソッドを実装する。所有するフィルタの参照カウントをインクリメントする。

CBasePropertyPage::NonDelegatingQueryInterface

CBasePropertyPage クラス

インターフェイスを取得し、参照カウントをインクリメントする。

構文

HRESULT NonDelegatingQueryInterface(
REFIID riid,
void **ppv
    );

パラメータ

riid
参照識別子。
ppv
インターフェイスへのポインタのアドレス。

戻り値

ppv が無効な場合は、E_POINTER を返す。クエリが成功した場合は NOERROR、失敗した場合は E_NOINTERFACE を返す。

注意

このメンバ関数は、INonDelegatingUnknown::NonDelegatingQueryInterface メソッドを実装し、IPropertyPage インターフェイスへの参照を渡す。次に、基底クラスのメンバ関数 CUnknown::NonDelegatingQueryInterface を呼び出す。このクラスをオーバーライドして、派生クラスのオブジェクトのその他のインターフェイスを返す。

CBasePropertyPage::NonDelegatingRelease

CBasePropertyPage クラス

インターフェイスの参照カウントをデクリメントする。

構文

ULONG NonDelegatingRelease(void);

戻り値

参照カウントを返す。

注意

このメンバ関数は、INonDelegatingUnknown::NonDelegatingRelease メソッドを実装する。これは所有するフィルタへの参照カウントを解放する。

CBasePropertyPage::OnActivate

CBasePropertyPage クラス

プロパティ ページがアクティブにされたときに呼び出される。

構文

virtual HRESULT OnActivate(void);

戻り値

デフォルトでは NOERROR を返す。オーバーライドするメンバ関数は、有効な HRESULT 値を返す。

注意

このメンバ関数は、プロパティ ページが表示されたときに派生クラスに通知するために、CBasePropertyPage::Activate メンバ関数から呼び出される。ダイアログ ボックスの値を初期化するには、このメンバ関数をオーバーライドする。この処理は、(オーバーライドされた CBasePropertyPage::OnConnect メンバ関数で) プロパティ ページが接続されたときに初期化された以前のデータ メンバの値を使用して Win32 SetDlgItemText 関数を呼び出すことによって行うことができる。

次に例を示す。

// プロパティ ページのテキスト フィールドを設定する。

HRESULT CQualityProperties::OnActivate()
{
SetEditFieldData();
return NOERROR;
}

// プロパティ ページのフィールドを初期化する。

void CQualityProperties::SetEditFieldData()
{
ASSERT(m_pQualProp);
TCHAR buffer[50];

wsprintf(buffer,"%d", m_iDropped);
SendDlgItemMessage(m_Dlg, IDD_QDROPPED, WM_SETTEXT, 0, (DWORD) (LPSTR) buffer);
wsprintf(buffer,"%d", m_iDrawn);
SendDlgItemMessage(m_Dlg, IDD_QDRAWN, WM_SETTEXT, 0, (DWORD) (LPSTR) buffer);
wsprintf(buffer,"%d.%02d", m_iFrameRate/100, m_iFrameRate%100);
SendDlgItemMessage(m_Dlg, IDD_QAVGFRM, WM_SETTEXT, 0, (DWORD) (LPSTR) buffer);
wsprintf(buffer,"%d", m_iFrameJitter);
SendDlgItemMessage(m_Dlg, IDD_QJITTER, WM_SETTEXT, 0, (DWORD) (LPSTR) buffer);
wsprintf(buffer,"%d", m_iSyncAvg);
SendDlgItemMessage(m_Dlg, IDD_QSYNCAVG, WM_SETTEXT, 0, (DWORD) (LPSTR) buffer);
wsprintf(buffer,"%d", m_iSyncDev);
SendDlgItemMessage(m_Dlg, IDD_QSYNCDEV, WM_SETTEXT, 0, (DWORD) (LPSTR) buffer);
}

CBasePropertyPage::OnApplyChanges

CBasePropertyPage クラス

ユーザーがプロパティ ページに対する変更を適用したときに呼び出される。

構文

virtual HRESULT OnApplyChanges(void);

戻り値

デフォルトでは NOERROR を返す。オーバーライドするメンバ関数は、有効な HRESULT 値を返す。

注意

プロパティ ページでユーザーがプロパティ値を設定できる場合は、このメンバ関数をオーバーライドする。このメンバ関数が呼び出されると、変更されたプロパティが処理される。たとえば、派生クラスで適切なデータ メンバを新しい値に設定したり、フィルタでメソッドを呼び出してプロパティを設定する。このメンバ関数が終了するときに、オブジェクト内のプロパティがプロパティ ページ内のプロパティを反映しない場合は、オーバーライドするメンバ関数で CBasePropertyPage::IsPageDirty を呼び出して m_bDirty データ メンバを TRUE に設定する。

CBasePropertyPage::OnConnect

CBasePropertyPage クラス

プロパティ ページがフィルタに接続されたときに呼び出される。

構文

virtual HRESULT OnConnect(
IUnknown *pUnknown
    );

パラメータ

pUnknown
プロパティ ページに関連付けられたフィルタの IUnknown インターフェイスへのポインタ。

戻り値

デフォルトでは NOERROR を返す。オーバーライドするメンバ関数は、有効な HRESULT 値を返す。

注意

このメンバ関数は、CBasePropertyPage::SetObjects メンバ関数から ppUnk パラメータを指定して呼び出される。このパラメータはフィルタの IUnknown インターフェイスでなければならない。後で (CBasePropertyPage::OnActivate で) プロパティ ページのダイアログ ボックスに送信されるプロパティ値を取得するには、このメンバ関数をオーバーライドする。

次の例は、このメンバ関数の使用方法を示している。

// 通信するためのフィルタを指定する。

HRESULT CQualityProperties::OnConnect(IUnknown *pUnknown)
{
ASSERT(m_pQualProp == NULL);

// レンダラに IQualProp インターフェイスを問い合わせる。

HRESULT hr = pUnknown->QueryInterface(IID_IQualProp,(void **)&m_pQualProp);
if (FAILED(hr)) {
return E_NOINTERFACE;
    }

ASSERT(m_pQualProp);

// ページの品質 データを取得する。

m_pQualProp->get_FramesDroppedInRenderer(&m_iDropped);
m_pQualProp->get_FramesDrawn(&m_iDrawn);
m_pQualProp->get_AvgFrameRate(&m_iFrameRate);
m_pQualProp->get_Jitter(&m_iFrameJitter);
m_pQualProp->get_AvgSyncOffset(&m_iSyncAvg);
m_pQualProp->get_DevSyncOffset(&m_iSyncDev);
return NOERROR;
}

CBasePropertyPage::OnDeactivate

CBasePropertyPage クラス

プロパティ ページが消去されたときに呼び出される。

構文

virtual HRESULT OnDeactivate(void);

戻り値

デフォルトでは NOERROR を返す。オーバーライドするメンバ関数は、有効な HRESULT 値を返す。

注意

このメンバ関数は、ユーザーがプロパティ ページを閉じたときに、CBasePropertyPage::Deactivate メンバ関数から呼び出される。その時点で特別な処理を行うには、このメンバ関数をオーバーライドする。

CBasePropertyPage::OnDisconnect

CBasePropertyPage クラス

プロパティ ページが所有するフィルタから切断されたときに呼び出される。

構文

virtual HRESULT OnDisconnect(void);

戻り値

デフォルトでは NOERROR を返す。オーバーライドするメンバ関数は、有効な HRESULT 値を返す。

注意

このメンバ関数は、プロパティ ページがフィルタから切断されたときに、CBasePropertyPage::SetObjects メンバ関数から呼び出される。下位のプロパティ インターフェイスで参照カウントを解放するなど、その時点で特別な処理を行うには、このメンバ関数をオーバーライドする。

次の例は、このメンバ関数を派生クラスに実装する方法を示している。

// 保持している IQualProp インターフェイスを解放する。

HRESULT CQualityProperties::OnDisconnect()
{
// インターフェイスを解放する。

if (m_pQualProp == NULL) {
return E_UNEXPECTED;
    }

m_pQualProp->Release();
m_pQualProp = NULL;
return NOERROR;
}

CBasePropertyPage::OnReceiveMessage

CBasePropertyPage クラス

メッセージがプロパティ ページのダイアログ ボックスに送信されたときに呼び出される。

構文

virtual BOOL OnReceiveMessage(
HWND hwnd,
UINT uMsg,
WPARAM wParam,
LPARAM lParam
    );

パラメータ

hwnd
メッセージを受信するウィンドウ プロシージャ。
uMsg
メッセージ。
wParam
追加のメッセージ情報。このパラメータの内容は、uMsg パラメータの値によって異なる。
lParam
追加のメッセージ情報。このパラメータの内容は、uMsg パラメータの値によって異なる。

戻り値

デフォルトでは、Win32 DefWindowProc 関数によって返される値を返す。

注意

このメンバ関数のデフォルトの実装は、指定されたパラメータを使用して DefWindowProc を呼び出す。メッセージに特別な処理が必要な場合は、このメンバ関数をオーバーライドする。

CBasePropertyPage::SetObjects

CBasePropertyPage クラス

このプロパティ ページに関連付けられたオブジェクトの IUnknown ポインタをプロパティ ページに提供する。

構文

HRESULT SetObjects(
ULONG cObjects,
LPUNKNOWN *ppUnk
    );

パラメータ

cObjects
ppUnk で示される配列内の IUnknown ポインタの数。この数値は 1 または 0 でなければならない。0 の場合、プロパティは以前にこのメソッドに渡されたポインタを解放しなければならない。
ppUnk
このプロパティ ページ (およびその他のプロパティ ページ) が表示されるプロパティ シートによって影響を受ける一意のオブジェクトを識別する単一の IUnknown インターフェイスへのポインタのアドレス。プロパティ ページは、IUnknown::AddRef を呼び出すことによって、このポインタをキャッシュしなければならない。

戻り値

ppUnk が Null の場合は E_POINTER、cObjects が 1 よりも大きい場合は E_UNEXPECTED、それ以外の場合はこのメンバ関数が呼び出した CBasePropertyPage::OnConnect または CBasePropertyPage::OnDisconnect メンバ関数によって返された値を返す。

注意

このメンバ関数は、COM の IPropertyPage::SetObjects メソッドを実装する。このメンバ関数は、cObjects の値が 1 の場合は仮想メンバ関数 CBasePropertyPage::OnConnect を呼び出し、cObjects の値が 0 の場合は仮想メンバ関数 CBasePropertyPage::OnDisconnect を呼び出す。このプロパティ ページが適用されるインターフェイスを取得したり (IUnknown::AddRef を呼び出す)、解放する (IUnknown::Release を呼び出す) には、この仮想メンバ関数をオーバーライドする。

呼び出し元は、CBasePropertyPage::Activate を呼び出す前に、このオブジェクトをプロパティ ページに提供し、ページを非アクティブにするとき、またはオブジェクトを完全に解放するときに、パラメータとして 0-v を指定して SetObjects を呼び出す必要がある。

このメンバ関数では、オブジェクトを 1 つだけプロパティ ページに関連付けることができる。

CBasePropertyPage::SetPageSite

CBasePropertyPage クラス

プロパティ ページを初期化し、プロパティ ページがプロパティ フレームと通信するために使用する IPropertyPageSite インターフェイスへのポインタをプロパティ ページに提供する。

構文

HRESULT SetPageSite(
LPPROPERTYPAGESITE pPageSite
    );

パラメータ

pPageSite
プロパティ シート内のこのプロパティ ページを管理し、サービスを提供するページ サイトの IPropertyPageSite インターフェイスへのポインタ。

戻り値

m_pPageSite データ メンバがフィルタのプロパティ ページへのポインタを使用して初期化されていない場合は、E_UNEXPECTED を返す。

注意

このメンバ関数は、COM の IPropertyPage::SetPageInfo メソッドを実装する。IPropertyPageSite インターフェイスが渡されると、このメンバ関数はインターフェイスへの参照をカウントし、m_pPageSite に割り当てる。Null 値が渡されると、IPropertyPageSite インターフェイスの参照カウントを解放する。

CBasePropertyPage::Show

CBasePropertyPage クラス

プロパティ ページのダイアログ ボックスを表示または非表示にする。

構文

HRESULT Show(
UINT nCmdShow
    );

パラメータ

nCmdShow
表示するかどうかを記述するコマンド。SW_SHOWNORMAL、SW_SHOW、および SW_HIDE のみ使用できる。

戻り値

データ メンバ m_hwnd がプロパティ ページのウィンドウ ハンドルを含んでいない場合は、E_UNEXPECTED を返す。nCmdShow パラメータが、SW_SHOW、SW_SHOWNORMAL (表示) または SW_HIDE (非表示) ではない場合は、E_INVALIDARG を返す。

注意

ページが表示に設定された場合、ページはそのページ自体にフォーカスを設定する必要がある。具体的には、ページの最初のプロパティにフォーカスを設定する。このメンバ関数は、COM の IPropertyPage::Show メソッドを実装する。このメンバ関数は、nCmdShow の値を SHOW_NORMAL にして、CBasePropertyPage::Activate メンバ関数を終了する直前に呼び出される。

CBasePropertyPage::TranslateAccelerator

CBasePropertyPage クラス

処理するキーストロークを指定する MSG 構造体へのポインタを提供する。

構文

HRESULT TranslateAccelerator(
LPMSG lpMsg
    );

パラメータ

lpMsg
処理するキーストロークを記述する MSG 構造体へのポインタ。

戻り値

デフォルトでは E_NOTIMPL を返す。

注意

このメンバ関数は、COM の IPropertyPage::TranslateAccelerator メソッドを実装する。このメンバ関数の呼び出しは、CBasePropertyPage::Activate を呼び出した後、対応する CBasePropertyPage::Deactivate を呼び出す前に行う必要がある。プロパティ ページのショートカット キーを実装するには、このメンバ関数をオーバーライドする。


CBaseReferenceClock クラス

宣言 : Refclock.h

このクラスは、IReferenceClock インターフェイスをサポートする基準クロックを実装する。ハードウェア デバイスにアクセスするなどして、フィルタがフィルタ グラフに基準クロックを提供できる場合、フィルタはこのクラスを使ってクロックを実装する。

CBaseReferenceClock オブジェクトは、次の 2 つの個別のタイム値を維持する。

  • 内部的には、GetPrivateTime メソッドが、クロックによって維持されている実際のタイムを返す。
  • 外部的には、GetTime メソッドが、フィルタ グラフの基準タイムを返す。

内部クロックが短時間にわたって戻ることは有効である。たとえば、クロックが進んだ場合、フィルタは逆方向に調整できる。詳細については、「SetTimeDelta」を参照すること。GetTime メソッドは、GetPrivateTime によって報告されたタイム値を使用する。しかし、基準タイムは単調増加している。つまり、決して戻ることはない。そのため、内部クロックが戻った場合、GetTime は内部クロックが追いつくまで古いタイムを報告し続ける。

たとえば、2 つのメソッドが次のシーケンスを返すとする。

GetPrivateTime: 105, 106, 103, 104, 105, 106, 107, 108
GetTime:        105, 106, 106, 106, 106, 106, 107, 108

3 つ目のクロック ティックでは、内部クロックは 103 に戻っている。GetTime メソッドは、内部クロックが追いつくまで、106 を報告し続ける。

デフォルトでは、timeGetTime 関数の呼び出しによって、GetPrivateTime はシステム タイムを返す。外部デバイスから基準クロックを提供しているフィルタは、次のいずれかを行うことができる。

  • GetPrivateTime をオーバーライドし、デバイスからのタイムを返す。
  • デバイス タイムとシステム タイムの差を監視し、SetTimeDelta を呼び出して訂正する。

このクラスは、CAMSchedule オブジェクトを使ってアドバイズ要求のスケジューリングを行う。詳細については、CAMSchedule クラスのドキュメントを参照すること。

プロテクト メンバ変数
m_pSchedule | クロックのスケジュール タスクを処理する CAMSchedule オブジェクト。
プロテクト メソッド
~CBaseReferenceClock | デストラクタ メソッド。
Public メソッド
CBaseReferenceClock | コンストラクタ メソッド。
GetPrivateTime | クロックから現在のタイムを取得する。
SetTimeDelta | 内部クロック タイムを調整する。
GetSchedule | クロックのスケジュール オブジェクトへのポインタを取得する。
TriggerThread | スケジューリングを処理するワーカー スレッドを起動する。
IReferenceClock メソッド
GetTime | 現在の基準タイムを取得する。
AdviseTime | 単発のアドバイズ要求を作成する。
AdvisePeriodic | 周期的アドバイズ要求を作成する。
Unadvise | 保留中のアドバイズ要求を削除する。
ヘルパー関数
ConvertToMilliseconds | 基準タイムをミリ秒に変換する。

CBaseReferenceClock.m_pSchedule

CBaseReferenceClock クラス

クロックのスケジュール タスクを行う CAMSchedule オブジェクト。

構文

CAMSchedule * const m_pSchedule;

CBaseReferenceClock::AdvisePeriodic

CBaseReferenceClock クラス

周期的アドバイズ要求を作成する。IReferenceClock::AdvisePeriodic メソッドを実装する。

構文

HRESULT AdvisePeriodic(
REFERENCE_TIME StartTime,
REFERENCE_TIME PeriodTime,
HSEMAPHORE hSemaphore,
DWORD *pdwAdviseToken
    );

パラメータ

StartTime
最初の通知のタイム (100 ナノ秒単位)。ゼロ以上、MAX_TIME 以下でなくてはならない。
PeriodTime
通知の間隔 (100 ナノ秒単位)。ゼロ以上でなくてはならない。
hSemaphore
セマフォへのハンドル。呼び出し元によって作成される。
pdwAdviseToken
アドバイズ要求の識別子を受け取る変数へのポインタ。

戻り値

次の表に示されるいずれかの HRESULT 値を返す。
S_OK | 成功
E_INVALIDARG | 無効なタイム値
E_OUTOFMEMORY | 失敗
E_POINTER | NULL ポインタ引数

注意

要求のたびに、クロックは hSemaphore パラメータで指定されたセマフォを解放する。以降の通知が必要ではない場合は、Unadvise を呼び出し、この呼び出しから返された pdwAdviseToken 値を渡す。

CBaseReferenceClock::AdviseTime

CBaseReferenceClock クラス

単発のアドバイズ要求を作成する。IReferenceClock::AdviseTime メソッドを実装する。

構文

HRESULT AdviseTime(
REFERENCE_TIME baseTime,
REFERENCE_TIME streamTime,
HEVENT hEvent,
DWORD *pdwAdviseToken
    );

パラメータ

baseTime
基準タイム (100 ナノ秒単位)。
streamTime
ストリーム オフセット タイム (100 ナノ秒単位)。
hEvent
イベントへのハンドル。呼び出し元によって作成される。
pdwAdviseToken
アドバイズ要求の識別子を受け取る変数へのポインタ。

戻り値

次の表に示されるいずれかの HRESULT 値を返す。
S_OK | 成功
E_INVALIDARG | 無効なタイム値
E_OUTOFMEMORY | 失敗
E_POINTER | NULL ポインタ変数

注意

このメソッドは、基準タイム baseTime + streamTime の単発のアドバイズ要求を作成する。この合計は、ゼロ以上、MAX_TIME 以下でなくてはならない。それ以外の場合、E_INVALIDARG を返す。要求のたびに、クロックは hEvent パラメータで指定されるイベントに通知する。

指定したタイムになる前に通知を取り消すには、Unadvise メソッドを呼び出して、この呼び出しから返された pdwAdviseToken の値を渡す。通知の発生後、クロックは自動的に通知を取り消すので、Unadvise を呼び出す必要はない。ただし、呼び出しても間違いではない。

CBaseReferenceClock::CBaseReferenceClock

CBaseReferenceClock クラス

コンストラクタ メソッド。

構文

CBaseReferenceClock(
TCHAR *pName,
LPUNKNOWN pUnk,
HRESULT *phr,
CAMSchedule *pSched = NULL
    );

パラメータ

pName
オブジェクトの名前を含む文字列へのポインタ。詳細については、「CBaseObject」を参照すること。
pUnk
委任オブジェクトの IUnknown インターフェイスへのポインタ。
phr
このオブジェクトの所有者へのポインタ。オブジェクトが集成された場合は、集成オブジェクトの IUnknown インターフェイスにポインタを渡す。それ以外の場合は、このパラメータに NULL を設定する。
pSched
CAMSchedule オブジェクトへのポインタ。NULL の場合、このメソッドは新しい CAMSchedule オブジェクトを作成する。

CBaseReferenceClock::~CBaseReferenceClock

CBaseReferenceClock クラス

デストラクタ メソッド。

構文

CBaseReferenceClock(void);

CBaseReferenceClock::GetPrivateTime

CBaseReferenceClock クラス

クロックからリアル タイムを取得する。

構文

virtual REFERENCE_TIME GetPrivateTime(void);

戻り値

現在のクロック タイムを返す (100 ナノ秒単位)。

注意

このメソッドは、クロックによって報告されるリアル タイムを返す。外部の呼び出し元は、このメソッドを呼び出す GetTime メソッドを使用する。GetTime メソッドとは異なり、内部クロックは戻ることが許可される。この場合、GetTime メソッドは、GetPrivateTime メソッドが追いつくまで、最後に報告されたタイムを返し続ける。

CBaseReferenceClock::GetSchedule

CBaseReferenceClock クラス

クロックのスケジュール オブジェクトへのポインタを取得する。

構文

CAMSchedule GetSchedule(void);

戻り値

m_pSchedule メンバ変数を返す。

CBaseReferenceClock::GetTime

CBaseReferenceClock クラス

現在の基準タイムを取得する。IReferenceClock::GetTime メソッドを実装する。

構文

HRESULT GetTime(
REFERENCE_TIME *pTime
    );

パラメータ

pTime
現在のタイムを受け取る変数へのポインタ (100 ナノ秒単位)。

戻り値

次の表に示されるいずれかの HRESULT 値を返す。

E_POINTER | NULL ポインタ変数。
S_FALSE | 返されたタイムは、以前の値と同じである。
S_OK | 成功。

注意

このメソッドは GetPrivateTime を呼び出して、実際のクロック タイムを決定する。クロック タイムが厳密に以前の値よりも大きな場合は、GetTime はそのクロック タイムを使って S_OK を返す。それ以外の場合は、以前の値を使って S_FALSE を返す。そのため、内部クロックは短時間にわたって戻ることができるが、基準タイムが戻ることはない。基準タイムは、内部クロックが追いつくまで同じ値で "ストール" 状態となる。

CBaseReferenceClock::SetTimeDelta

CBaseReferenceClock クラス

内部クロック タイムを調整する。

構文

HRESULT SetTimeDelta(
const REFERENCE_TIME& TimeDelta
    );

パラメータ

TimeDelta
クロック タイムを調整する量 (100 ナノ秒単位)。正の値によってクロックは進み、負の値によってクロックは戻る。

戻り値

S_OK を返す。

注意

派生したクラスは、タイム情報を提供するデバイスからタイムがずれた場合に、このメソッドを使って内部クロックを調整できる。

GetTime メソッドは、減少する値を返すことはない。クロックを戻す調整をした場合、GetTime は、クロックがその値に到達するまで以前の値を返す。

CBaseReferenceClock::TriggerThread

CBaseReferenceClock クラス

スケジューリングを処理するワーカー スレッドを起動できる。

構文

void TriggerThread(void);

戻り値

戻り値なし。

注意

クロックは、適切なときに CAMSchedule::Advise メソッドを呼び出すワーカー スレッドを使用する。派生したクラスは、TriggerThread を呼び出してワーカー スレッドを起動できる。

CBaseReferenceClock::Unadvise

CBaseReferenceClock クラス

保留中のアドバイズ要求を削除する。IReferenceClock::Unadvise メソッドを実装する。

構文

HRESULT Unadvise(
DWORD dwAdviseToken
    );

パラメータ

dwAdviseToken
削除する要求の識別子。AdviseTime メソッドまたは pdwAdviseToken パラメータの AdvisePeriodic メソッドによって返される値を使用する。

戻り値

次の表に示されるいずれかの HRESULT 値を返す。

S_FALSE | 見つからない。
S_OK | 成功。

ConvertToMilliseconds Function

CBaseReferenceClock クラス

基準タイムをミリ秒に変換する。

構文

LONGLONG ConvertToMilliseconds(
    const REFERENCE_TIME& RT
);

パラメータ

RT
基準タイム (100 ナノ秒単位)。

戻り値

ミリ秒単位に変換された基準タイムを返す。


CBaseRenderer クラス

レンダリング フィルタを実装するための基底クラス。CRendererInputPin クラスによって実装される入力ピンを 1 つサポートする。

宣言 : Renbase.h

このクラスを使用するには、CBaseRenderer を継承する派生クラスを宣言する。派生クラスでは、少なくとも以下のメソッドを実装する必要がある。これらのメソッドは、基底クラス内で純粋仮想関数として宣言される。

  • CheckMediaType : 掲示されたメディア タイプを受け付けるか拒否するかを判断する。フィルタは、ピン接続の処理中にこのメソッドを呼び出す。
  • DoRenderSample : サンプルをレンダリングする。フィルタは、実行中に受け取るサンプルそれぞれについて、このメソッドを呼び出す。

状態の変化および同期の問題を処理する基底クラス。この基底クラスは、サンプルのレンダリングのスケジュールも行う。ただし、品質コントロールのための手段は実装しない。

この基底クラスは、各種の "ハンドラ" メソッドも宣言する。これらは、ストリーミング処理におけるそれぞれ固有の段階で、フィルタが呼び出すメソッドである。基底クラスでは何もしないが、派生クラスでオーバーライドできる。後の一覧では、これらのメソッドが「Public メソッド : ハンドラ」としてまとめられている。

OnReceiveFirstSample ハンドラには少し説明が必要だろう。フィルタはこのメソッドを呼び出すのは、ポーズ中にサンプルを受け取る場合である。この状況は、グラフが停止からポーズに切り替わる場合か、またはポーズ中にグラフがシークされる場合に発生する可能性がある。ビデオ レンダラは、通常、このサンプルを使って静止フレームを表示する。ポーズから実行に切り替わると、フィルタは、DoRenderSample メソッドにストリーム内の最初のサンプルと同じサンプルを送る。

スケジューリング

アップストリーム フィルタが入力ピンの IMemInputPin::Receive メソッドを呼び出してサンプルを渡すと、ピンはその呼び出しをフィルタの Receive メソッドに渡す。フィルタは、サンプルをドロップするか、直ちにレンダリングするか、またはレンダリングをスケジュールする。

サンプルにタイム スタンプがない場合、または基準クロックが利用できない場合、フィルタはサンプルを直ちにレンダリングする。それ以外の場合、フィルタは ShouldDrawSampleNow メソッドを呼び出して、実行すべき処理を判断する。デフォルトでは、タイム スタンプに基づいてサンプルがスケジュールされる。派生クラスでは、ShouldDrawSampleNow をオーバーライドして、品質コントロールをサポートできる。

サンプルをスケジュールするため、フィルタは、アドバイズ要求を作成する IReferenceClock::AdviseTime メソッドを呼び出す。この結果、スケジュールされた時間になるか、またはフィルタの状態が変化するまで、Receive メソッドがブロックする。ブロックすると、アップストリーム フィルタは、現在のサンプルがレンダリングされるまで、次のサンプルを渡すことができなくなる。

アップストリーム フィルタが IPin::EndOfStream メソッドを呼び出してエンドオブストリームを通知すると、フィルタは、フィルタ グラフ マネージャに EC_COMPLETE イベントを送信する。フィルタは、このイベントを送信する前に、現在のサンプルの終了タイムまで待機する。

プロテクト メンバ変数
m_bAbort | レンダリングを停止して、以降のサンプルを拒否するかどうかを示すフラグ。
m_bEOS | エンドオブストリームに達しているかどうかを示すフラグ。
m_bEOSDelivered | フィルタが EC_COMPLETE イベントを発行したかどうかを示すフラグ。
m_bInReceive | フィルタが Receive 呼び出しの処理中かどうかを示すフラグ。
m_bRepaintStatus | 再描画イベントを有効または無効にするフラグ。
m_bStreaming | フィルタがデータのストリーミング中かどうかを示すフラグ。
m_dwAdvise | レンダリングをスケジュールするタイマ イベントの識別子。
m_EndOfStreamTimer | EC_COMPLETE 通知のスケジュールに使用されるタイマ イベントの識別子。
m_evComplete | 状態の移行が完了したときに通知済になるイベント。
m_InterfaceLock | フィルタ状態のロック。
m_pInputPin | フィルタの入力ピンへのポインタ。
m_pMediaSample | 現在のメディア サンプルへのポインタ。
m_pPosition | アップストリームにシーク コマンドを渡すためのヘルパー オブジェクト。
m_pQSink | 品質コントロール メッセージを受け取るオブジェクトへのポインタ。
m_RendererLock | ストリーミングのロック。
m_RenderEvent | レンダリングのスケジュールに使用されるイベント。
m_SignalTime | 現在のサンプル上の終了タイム。
m_ThreadSignal | ストリーミング スレッドを解放するために使用されるイベント。
Public メソッド
CancelNotification | レンダリングをスケジュールするタイマ イベントをキャンセルする。仮想。
CBaseRenderer | コンストラクタ メソッド。
~CBaseRenderer | デストラクタ メソッド。
GetMediaPositionInterface | フィルタの IMediaPosition および IMediaSeeking インターフェイス ポインタを取得する。仮想。
GetPin | ピンを取得する。仮想。
GetPinCount | ピンの数を取得する。仮想。
GetSampleTimes | サンプルからタイム スタンプを取得する。仮想。
OnDisplayChange | フィルタ グラフ マネージャに EC_DISPLAY_CHANGED イベントを発行する。
PrepareReceive | サンプルをレンダリングする準備をする。仮想。
Receive | ストリームの次のメディア サンプルを取得する。仮想。
Render | サンプルをレンダリングする。仮想。
ScheduleSample | サンプルのレンダリングをスケジュールする。仮想。
SendNotifyWindow | アップストリーム フィルタにビデオ ウィンドウのハンドルを通知する。
SendRepaint | フィルタ グラフ マネージャに再描画イベントを送信する。
SetMediaType | ピンのメディア タイプを設定するときに呼び出される。仮想。
SignalTimerFired | レンダリングのスケジュールに使用されるタイマ識別子をクリアする。
SourceThreadCanWait | ストリーミング スレッドを保持または解放する。仮想。
WaitForReceiveToComplete | Receive メソッドが完了するまで待機する。
WaitForRenderTime | 現在のサンプルのプレゼンテーション時間を待機する。仮想。
Public メソッド : アクセサ
ClearPendingSample | 現在のサンプルを解放する。仮想。
GetCurrentSample | 現在のサンプルを取得する。仮想。
GetRealState | フィルタの状態を取得する。
GetRenderEvent | レンダリングをスケジュールするイベントを取得する。
HaveCurrentSample | フィルタにサンプルがあるかどうかを判断する。仮想。
IsEndOfStream | エンドオブストリーム通知が受信されたかどうかを照会する。
IsEndOfStreamDelivered | EC_COMPLETE イベントがフィルタ グラフ マネージャに配信されたかどうかを照会する。
IsStreaming | フィルタがデータのストリーミング中かどうかを照会する。
SetAbortSignal | レンダリングを停止して以降のサンプルを拒否するかどうかを示す、中止フラグを設定する。
SetRepaintStatus | 再描画イベントを有効または無効にする。
Public メソッド : 状態変更関連
Active | 状態がポーズまたは実行に切り替わるときに呼び出される。仮想。
BeginFlush | フラッシュ処理を開始する。仮想。
BreakConnect | 接続から入力ピンを解放する。仮想。
CheckReady | 状態の移行が完了しているかどうかを照会する。
CompleteConnect | 入力ピンからほかのピンへの接続を完了する。仮想。
CompleteStateChange | ポーズ状態への移行が完了しているかどうかを判断する。仮想。
EndFlush | フラッシュ処理を終了する。仮想。
Inactive | 状態が停止に切り替わるときに呼び出される。仮想。
NotReady | 状態の移行がまだ完了していないことを通知する。
Ready | 状態の移行が完了していることを通知する。
StartStreaming | フィルタが実行状態に切り替わるときに、ストリーミングを開始する。仮想。
StopStreaming | フィルタが実行状態以外に切り替わるときに、ストリーミングを停止する。仮想。
Public メソッド : エンドオブストリーム関連
EndOfStream | 入力ピンがエンドオブストリーム通知を受信したことをフィルタに知らせる。仮想。
NotifyEndOfStream | フィルタ グラフ マネージャに EC_COMPLETE イベントを送信する。
ResetEndOfStream | エンドオブストリーム関連フラグをリセットする。
ResetEndOfStreamTimer | EC_COMPLETE 通知をスケジュールするタイマをキャンセルする。仮想。
SendEndOfStream | エンドオブストリームに達している場合に、フィルタ グラフ マネージャへの EC_COMPLETE イベントをスケジュールする。仮想。
TimerCallback | エンドオブストリーム用のタイマ イベントで使用するコールバック メソッド。
Public メソッド : ハンドラ
OnReceiveFirstSample | ポーズ中にフィルタがサンプルを受信するときに呼び出される。仮想。
OnRenderEnd | サンプルがレンダリングされた後で呼び出される。仮想。
OnRenderStart | レンダリングが開始されようとしているときに呼び出される。仮想。
OnStartStreaming | フィルタがストリーミングを開始するときに呼び出される。仮想。
OnStopStreaming | フィルタがストリーミングを停止するときに呼び出される。仮想。
OnWaitEnd | フィルタがサンプルのプレゼンテーション時間の待機を終了するときに呼び出される。仮想。
OnWaitStart | フィルタがサンプルのプレゼンテーション時間の待機を開始するときに呼び出される。仮想。
PrepareRender | フィルタがサンプルをレンダリングする前に呼び出される。仮想。
ShouldDrawSampleNow | サンプルのレンダリングをスケジュールする方法を判断する。仮想。
Pure Virtual メソッド
CheckMediaType | 特定のメディア タイプをフィルタが受け入れるかどうかを確認する。
DoRenderSample | サンプルをレンダリングする。
IMediaFilter メソッド
GetState | フィルタの状態 (実行、停止、ポーズ) を取得する。
Pause | フィルタをポーズする。
Run | フィルタを実行する。
Stop | フィルタを停止する。
IBaseFilter メソッド
FindPin | 指定された識別子を持つピンを取得する。

CBaseRenderer.m_bAbort

CBaseRenderer クラス

レンダリングを停止して、以降のサンプルを拒否するかどうかを示すフラグ。

構文

BOOL m_bAbort;

CBaseRenderer.m_bEOS

CBaseRenderer クラス

エンドオブストリームに達しているかどうかを示すフラグ。

構文

BOOL m_bEOS;

CBaseRenderer.m_bEOSDelivered

CBaseRenderer クラス

フィルタが EC_COMPLETE イベントを発行したかどうかを示すフラグ。

構文

BOOL m_bEOSDelivered;

CBaseRenderer.m_bInReceive

CBaseRenderer クラス

フィルタが Receive 呼び出しの処理中かどうかを示すフラグ。

構文

BOOL m_bInReceive;

CBaseRenderer.m_bRepaintStatus

CBaseRenderer クラス

再描画イベントを有効または無効にするフラグ。

構文

BOOL m_bRepaintStatus;

CBaseRenderer.m_bStreaming

CBaseRenderer クラス

フィルタがデータのストリーミング中かどうかを示すフラグ。

構文

BOOL m_bStreaming;

CBaseRenderer.m_dwAdvise

CBaseRenderer クラス

レンダリングをスケジュールするタイマ イベントの識別子。

構文

DWORD_PTR m_dwAdvise;

CBaseRenderer.m_EndOfStreamTimer

CBaseRenderer クラス

EC_COMPLETE 通知のスケジュールに使用されるタイマ イベントの識別子。

構文

UINT m_EndOfStreamTimer;

CBaseRenderer.m_evComplete

CBaseRenderer クラス

状態の移行が完了したときに通知済になるイベント。

構文

CAMEvent m_evComplete;

CBaseRenderer.m_InterfaceLock

CBaseRenderer クラス

フィルタ状態のロック。

構文

CCritSec m_InterfaceLock;

CBaseRenderer.m_pInputPin

CBaseRenderer クラス

フィルタの入力ピンへのポインタ。

構文

CRendererInputPin *m_pInputPin;

CBaseRenderer.m_pMediaSample

CBaseRenderer クラス

現在のメディア サンプルへのポインタ。

構文

IMediaSample *m_pMediaSample;

CBaseRenderer.m_pPosition

CBaseRenderer クラス

アップストリームにシーク コマンドを渡すためのヘルパー オブジェクト。

構文

CRendererPosPassThru *m_pPosition;

CBaseRenderer.m_pQSink

CBaseRenderer クラス

品質コントロール メッセージを受け取るオブジェクトへのポインタ。

構文

IQualityControl *m_pQSink;

注意

基底クラスでは品質コントロールを実装しない。このメンバ変数のデフォルト値は NULL である。

CBaseRenderer.m_RendererLock

CBaseRenderer クラス

ストリーミングのロック。

構文

CCritSec m_RendererLock;

CBaseRenderer.m_RenderEvent

CBaseRenderer クラス

レンダリングのスケジュールに使用されるイベント。

構文

CAMEvent m_RenderEvent;

CBaseRenderer.m_SignalTime

CBaseRenderer クラス

現在のサンプル上の終了タイム。

構文

REFERENCE_TIME m_SignalTime;

CBaseRenderer.m_ThreadSignal

CBaseRenderer クラス

ストリーミング スレッドを解放するために使用されるイベント。

構文

CAMEvent m_ThreadSignal;

CBaseRenderer::Active

CBaseRenderer クラス

状態がポーズまたは実行に切り替わるときに呼び出される。

構文

virtual HRESULT Active(void);

戻り値

S_OK を返す。

注意

入力ピンは、ピン自体の CRendererInputPin::Active メソッドからこのメソッドを呼び出す。このメソッドは基底クラスでは何もしない。

CBaseRenderer::BeginFlush

CBaseRenderer クラス

フラッシュ処理を開始する。

構文

virtual HRESULT BeginFlush(void);

戻り値

S_OK を返す。

注意

フィルタの入力ピンは、IPin::BeginFlush メソッドの呼び出しを受け取ると、このメソッドを呼び出す。フィルタは、ストリーミング スレッドを解放し、レンダリングのために保持しているサンプルをすべて解放する。

CBaseRenderer::BreakConnect

CBaseRenderer クラス

接続から入力ピンを解放する

構文

virtual HRESULT BreakConnect(void);

戻り値

次の一覧に含まれるいずれかの HRESULT 値を返す。

S_FALSE | ピンが接続されていない。
S_OK | 成功。
VFW_E_NOT_STOPPED | フィルタがまだアクティブである。

注意

フィルタの入力ピンは、ピン自体の BreakConnect メソッド内部からこのメソッドを呼び出す (詳細については｢CBasePin::BreakConnect｣を参照)。フィルタは、エンドオブストリーム関連フラグのリセットなどの内部的な定番処理をいくつか実行する。

CBaseRenderer::CancelNotification

CBaseRenderer クラス

レンダリングをスケジュールするタイマ イベントをキャンセルする。

構文

virtual HRESULT CancelNotification(void);

戻り値

次の一覧に含まれるいずれかの HRESULT 値を返す。

S_FALSE | 保留されているタイマ イベントがない。
S_OK | 成功。

注意

フィルタはストリーミングを停止するときにこのメソッドを呼び出す。メソッドは、スケジュールされているレンダリングをすべてキャンセルする。

CBaseRenderer::CBaseRenderer

CBaseRenderer クラス

コンストラクタ メソッド。

構文

CBaseRenderer(
    REFCLSID RenderClass,
    TCHAR *pName,
    LPUNKNOWN pUnk,
    HRESULT *phr
);

パラメータ

RenderClass
レンダラのクラス識別子。
pName
デバッグ目的で使用する、フィルタの名前を含む文字列へのポインタ。
pUnk
このオブジェクトの所有者へのポインタ。オブジェクトが集成されている場合は、集成オブジェクトの IUnknown インターフェイスにポインタを渡す。それ以外の場合は、このパラメータを NULL に設定する。
phr
HRESULT 変数へのポインタ。(無視される)

CBaseRenderer::~CBaseRenderer

CBaseRenderer クラス

デストラクタ メソッド。

構文

~CBaseRenderer(void);

CBaseRenderer::CheckMediaType

CBaseRenderer クラス

特定のメディア タイプをフィルタが受け入れるかどうかを確認する。

構文

virtual HRESULT CheckMediaType(
    const CMediaType *pmt
) PURE;

パラメータ

pmt
提案されたメディア タイプを含む CMediaType オブジェクトへのポインタ。

戻り値

提案されたメディア タイプが受け入れられるなら S_OK を返す。そうでなければ S_FALSE かエラー コードを返す。

注意

入力ピンは、ピン自体の CBasePin::CheckMediaType メソッドからこのメソッドを呼び出す。派生クラスではこのメソッドを実装する必要がある。

CBaseRenderer::CheckReady

CBaseRenderer クラス

状態の移行が完了しているかどうかを照会する。

構文

BOOL CheckReady(void);

戻り値

状態の移行が完了している場合は TRUE を返し、フィルタがまだ新しい状態に移行中の場合は FALSE を返す。

参照

NotReady、Ready

CBaseRenderer::ClearPendingSample

CBaseRenderer クラス

現在のサンプルを解放する。

構文

virtual HRESULT ClearPendingSample(void);

戻り値

S_OK を返す。

CBaseRenderer::CompleteConnect

CBaseRenderer クラス

入力ピンからほかのピンへの接続を完了する。

構文

virtual HRESULT CompleteConnect(
    IPin *pReceivePin
);

パラメータ

pReceivePin
出力ピンの IPin インターフェイスへのポインタ。

戻り値

S_OK を返す。

注意

フィルタの入力ピンは、ピン接続を完了するために呼び出される、ピン自体の CompleteConnect メソッド内部からこのメソッドを呼び出す (詳細については｢CBasePin::CompleteConnect｣を参照)。フィルタは、SetRepaintStatus メソッドを呼び出して EC_REPAINT イベントを有効にする。

CBaseRenderer::CompleteStateChange

CBaseRenderer クラス

ポーズ状態への移行が完了しているかどうかを判断する。

構文

virtual HRESULT CompleteStateChange(
    FILTER_STATE OldState
);

パラメータ

OldState
移行の前の状態。

戻り値

移行が完了している場合は、S_OK を返す。それ以外の場合は、S_FALSE を返す。

注意

Pause メソッドは、このメソッドを呼び出して、移行状態を更新する。通常、ポーズ状態への移行は、フィルタがサンプルを受け取るまで完了しない。ただし、たとえばフィルタが接続されていない場合や、エンドオブストリームに達している場合などには、移行が直ちに完了する。このメソッドは、各種の条件を確認したうえで、Ready メソッドまたは NotReady メソッドを呼び出して、移行状態を更新する。

CBaseRenderer::DoRenderSample

CBaseRenderer クラス

サンプルをレンダリングする。

構文

virtual HRESULT DoRenderSample(
    IMediaSample *pMediaSample
) PURE;

パラメータ

pMediaSample
サンプルの IMediaSample インターフェイスへのポインタ。

戻り値

HRESULT 値を返す。

注意

派生クラスではこのメソッドを実装する必要がある。メソッドの動作は、実装されるフィルタの種類によってまったく異なる。たとえばビデオ レンダラであれば、サンプルに含まれるビデオ イメージを描画する。

CBaseRenderer::EndFlush

CBaseRenderer クラス

フラッシュ処理を終了する。

構文

virtual HRESULT EndFlush(void);

戻り値

S_OK を返す。

注意

フィルタの入力ピンは、IPin::EndFlush メソッドの呼び出しを受け取ると、このメソッドを呼び出す。

CBaseRenderer::EndOfStream

CBaseRenderer クラス

入力ピンがエンドオブストリーム通知を受信したことをフィルタに知らせる。

構文

HRESULT EndOfStream(void);

戻り値

S_OK を返す。

注意

フィルタの入力ピンは、エンドオブストリーム通知を受信すると、このメソッドを呼び出す。

このメソッドは、m_bEOS フラグを TRUE に設定し、SendEndOfStream メソッドを呼び出して EC_COMPLETE イベントをスケジュールする。フィルタがポーズ中にサンプルを待機している場合、このメソッドは状態の移行を完了する。

CBaseRenderer::FindPin

CBaseRenderer クラス

指定された識別子を持つピンを取得する。

構文

HRESULT FindPin(
    LPCWSTR Id,
    IPin **ppPin
);

パラメータ

Id
ピンを識別する定数、NULL で終わる Unicode 文字列のポインタ。L"In" でなければならない。
ppPin
ピンの IPin インターフェイスへのポインタを受け取る変数のアドレス。メソッドが失敗すると、*ppPin は NULL にセットされる。

戻り値

次の一覧に含まれるいずれかの HRESULT 値を返す。

S_OK | 成功。
E_POINTER | NULL ポインタ引数。
VFW_E_NOT_FOUND | 見つからなかった。

注意

このメソッドは、CBaseFilter::FindPin メソッドをオーバーライドする。フィルタの唯一のピン (入力ピン) には、In という名前が付いている。

CBaseRenderer::GetCurrentSample

CBaseRenderer クラス

現在のサンプルを取得する。

構文

virtual IMediaSample *GetCurrentSample(void);

戻り値

サンプルの IMediaSample インターフェイスへのポインタを返し、サンプルがない場合は NULL を返す。

注意

戻り値が NULL 以外の場合、IMediaSample ポインタは未処理の参照カウントを持つ。この参照カウントは必ず解放すること。

CBaseRenderer::GetMediaPositionInterface

CBaseRenderer クラス

フィルタの IMediaPosition および IMediaSeeking インターフェイス ポインタを取得する。

構文

virtual HRESULT GetMediaPositionInterface(
    REFIID riid,
    void **ppv
);

パラメータ

riid
インターフェイスの参照識別子。
ppv
インターフェイス ポインタを受け取る変数のアドレス。

戻り値

HRESULT 値を返す。可能な値は次の一覧のとおり。

S_OK | 成功。
E_OUTOFMEMORY | メモリ不足。
E_NOINTERFACE | インターフェイスがサポートされていない。

注意

フィルタは、アップストリームへの受け渡しをする CRendererPosPassThru オブジェクトに、すべてのシーク コマンドを委任する。このメソッドは、CRendererPosPassThru オブジェクトがまだ存在しなければ作成し、要求されたインターフェイスをそのオブジェクトに照会する。

m_pPosition メンバ変数には、CRendererPosPassThru オブジェクトへのポインタが格納される。

CBaseRenderer::GetPin

CBaseRenderer クラス

ピンを取得する。

構文

virtual CBasePin *GetPin(
    int n
);

パラメータ

n
指定されたピンの数。0 でなければならない。

戻り値

m_pInputPin ポインタを返す。

注意

このメソッドは、CBaseFilter クラス内の純粋仮想メソッド CBaseFilter::GetPin を実装する。このフィルタは、ピンを 1 つだけ (入力ピン) サポートする。このメソッドは、初めて呼び出されたときに、新しい CRendererInputPin オブジェクトとしてこのピンを作成する。

CBaseRenderer::GetPinCount

CBaseRenderer クラス

ピンの数を取得する。

構文

virtual int GetPinCount(void);

戻り値

1 を返す。

注意

このメソッドは、CBaseFilter クラスの純粋仮想メソッド CBaseFilter::GetPinCount を実装する。

CBaseRenderer::GetRealState

CBaseRenderer クラス

フィルタの状態を取得する。

構文

FILTER_STATE GetRealState(void);

戻り値

CBaseFilter.m_State の値を返す。この値は FILTER_STATE 列挙型のメンバである。

注意

このメソッドは、GetState メソッドの代わりに内部的に使用できる、より簡単な手段である。

CBaseRenderer::GetRenderEvent

CBaseRenderer クラス

レンダリングをスケジュールするイベントを取得する。

構文

CAMEvent *GetRenderEvent(void);

戻り値

m_RenderEvent イベントへのポインタを返す。

CBaseRenderer::GetSampleTimes

CBaseRenderer クラス

サンプルからタイム スタンプを取得する。

構文

virtual HRESULT GetSampleTimes(
    IMediaSample *pMediaSample,
    REFERENCE_TIME *pStartTime,
    REFERENCE_TIME *pEndTime
);

パラメータ

pMediaSample
サンプルの IMediaSample インターフェイスへのポインタ。
pStartTime
開始タイムを受け取る変数へのポインタ。
pEndTime
終了タイムを受け取る変数へのポインタ。

戻り値

HRESULT 値を返す。可能な値は次の一覧のとおり。

S_OK | サンプルを直ちにレンダリングしなければならない。
S_FALSE | タイム スタンプに基づいて、サンプルのレンダリングをスケジュールしなければならない。
E_FAIL | このサンプルをレンダリングしてはならない。
VFW_E_START_TIME_AFTER_END | 不正なタイム スタンプ : 終了タイムが開始タイムより早い。

注意

フィルタは、このメソッドを呼び出すことにより、サンプルをどのように処理すべきかどうかを判断する。戻り値が S_OK の場合、フィルタは直ちにサンプルをレンダリングする。S_FALSE の場合は、タイム スタンプに基づいてサンプルのレンダリングをスケジュールする。エラー コードの場合は、サンプルを拒否する。

サンプルにタイム スタンプがない場合、またはフィルタに基準クロックがない場合、このメソッドは S_OK を返す。それ以外の場合、このメソッドは ShouldDrawSampleNow メソッドの値を返す。この場合、ShouldDrawSampleNow は必ず S_FALSE を返す。この動作は派生クラスでオーバーライドできる。たとえば、派生クラスが品質コントロールの管理を実装する場合は、サンプルをドロップするために E_FAIL を返すことができる。

CBaseRenderer::GetState

CBaseRenderer クラス

フィルタの状態 (実行、停止、ポーズ) を取得する。

構文

HRESULT GetState(
    DWORD dwMilliSecsTimeout,
    FILTER_STATE *State
);

パラメータ

dwMilliSecsTimeout
タイムアウト間隔 (ミリ秒単位)。
State
フィルタの状態を示す FILTER_STATE 列挙型のメンバを取得する変数のポインタ。

戻り値

次の一覧に含まれるいずれかの HRESULT 値を返す。

S_OK | 成功。
VFW_S_STATE_INTERMEDIATE | フィルタ グラフは指定された状態に移行中。
E_POINTER | NULL ポインタ引数。

注意

このメソッドは、CBaseFilter::GetState メソッドをオーバーライドする。レンダラがポーズしていると、状態の移行は、レンダリングするサンプルを受け取るまで完了しない。状態の移行が完了する前にタイムアウトすると、メソッドは VFW_S_STATE_INTERMEDIATE を返す。

CBaseRenderer::HaveCurrentSample

CBaseRenderer クラス

フィルタにサンプルがあるかどうかを判断する。

構文

virtual BOOL HaveCurrentSample(void);

戻り値

フィルタにサンプルがある場合は TRUE を返し、それ以外の場合は FALSE を返す。

CBaseRenderer::Inactive

CBaseRenderer クラス

状態が停止に切り替わるときに呼び出される。

構文

virtual HRESULT Inactive(void);

戻り値

S_OK を返す。

注意

入力ピンは、ピン自体の CRendererInputPin::Inactive メソッドからこのメソッドを呼び出す。フィルタは、ClearPendingSample メソッドを呼び出して最新のサンプルを解放する。

CBaseRenderer::IsEndOfStream

CBaseRenderer クラス

エンドオブストリーム通知が受信されたかどうかを照会する。

構文

BOOL IsEndOfStream(void);

戻り値

m_bEOS フラグを返す。

CBaseRenderer::IsEndOfStreamDelivered

CBaseRenderer クラス

EC_COMPLETE イベントがフィルタ グラフ マネージャに配信されたかどうかを照会する。

構文

BOOL IsEndOfStreamDelivered(void);

戻り値

m_bEOSDelivered フラグを返す。

CBaseRenderer::IsStreaming

CBaseRenderer クラス

フィルタがデータのストリーミング中かどうかを照会する。

構文

BOOL IsStreaming(void);

戻り値

m_bStreaming フラグを返す。

CBaseRenderer::NotReady

CBaseRenderer クラス

状態の移行がまだ完了していないことを通知する。

構文

void NotReady(void);

注意

このメソッドにより、GetState メソッドは VFW_S_STATE_INTERMEDIATE を返すようになる。この値は、フィルタが現在の状態へまだ移行中であることを示す。フィルタは、状態の移行が保留されるたびに、このメソッドを呼び出す。この状況は、フィルタがポーズしてから、サンプルを受け取るまでに発生する。

参照

CheckReady、Ready

CBaseRenderer::NotifyEndOfStream

CBaseRenderer クラス

フィルタ グラフ マネージャに EC_COMPLETE イベントを送信する。

構文

void NotifyEndOfStream(void);

参照

EndOfStream、SendEndOfStream

CBaseRenderer::OnDisplayChange

CBaseRenderer クラス

フィルタ グラフ マネージャに EC_DISPLAY_CHANGED イベントを送信する。

構文

BOOL CBaseRenderer::OnDisplayChange(void);

戻り値

イベントが発行された場合は TRUE を返し、それ以外の場合は FALSE を返す。

注意

ビデオ レンダラは、WM_DISPLAYCHANGE メッセージへの応答として、このメソッドを呼び出さなければならない。入力ピンが接続されている場合、メソッドはフィルタ グラフ マネージャに EC_DISPLAY_CHANGED イベントを送信する。

CBaseRenderer::OnReceiveFirstSample

CBaseRenderer クラス

ポーズ中にフィルタがサンプルを受信するときに呼び出される。

構文

virtual void OnReceiveFirstSample(
    IMediaSample *pMediaSample
);

パラメータ

pMediaSample
サンプルの IMediaSample インターフェイスへのポインタ。

注意

Receive メソッドはこのメソッドを呼び出す。このメソッドは基底クラスでは何もしないが、派生クラスでオーバーライドできる。このメソッドは、主にビデオ レンダラでの使用を目的としている。ビデオ レンダラがポーズ中なら、通常は、最初のサンプルを静止画として表示する。

ポーズ中にグラフをシークした場合にも、このメソッドが呼び出される。

CBaseRenderer::OnRenderEnd

CBaseRenderer クラス

サンプルがレンダリングされた後で呼び出される。

構文

virtual void OnRenderEnd(
    IMediaSample *pMediaSample
);

パラメータ

pMediaSample
サンプルの IMediaSample インターフェイスへのポインタ。

注意

Render メソッドはこのメソッドを呼び出す。このメソッドは基底クラスでは何もしないが、たとえば品質コントロール データを収集するように、派生クラスでオーバーライドできる。

CBaseRenderer::OnRenderStart

CBaseRenderer クラス

レンダリングが開始されようとしているときに呼び出される。

構文

virtual void OnRenderStart(
    IMediaSample *pMediaSample
);

パラメータ

pMediaSample
サンプルの IMediaSample インターフェイスへのポインタ。

注意

Render メソッドはこのメソッドを呼び出す。このメソッドは基底クラスでは何もしないが、たとえば品質コントロール データを収集するように、派生クラスでオーバーライドできる。

CBaseRenderer::OnStartStreaming

CBaseRenderer クラス

フィルタがストリーミングを開始するときに呼び出される。

構文

virtual HRESULT OnStartStreaming(void);

戻り値

S_OK を返す。

注意

StartStreaming メソッドはこのメソッドを呼び出す。このメソッドは基底クラスでは何もしないが、派生クラスでオーバーライドできる。

CBaseRenderer::OnStopStreaming

CBaseRenderer クラス

フィルタがストリーミングを停止するときに呼び出される。

構文

virtual HRESULT OnStopStreaming(void);

戻り値

S_OK を返す。

注意

StopStreaming メソッドはこのメソッドを呼び出す。このメソッドは基底クラスでは何もしないが、派生クラスでオーバーライドできる。

CBaseRenderer::OnWaitEnd

CBaseRenderer クラス

フィルタがサンプルのプレゼンテーション時間の待機を終了するときに呼び出される。

構文

virtual void OnWaitEnd(void);

注意

WaitForRenderTime メソッドは、サンプルのプレゼンテーション時間の待機を終了したとき、このメソッドを呼び出す。このメソッドは基底クラスでは何もしないが、派生クラスでオーバーライドできる。

品質コントロールを実装する場合には、このメソッドと共に OnWaitStart メソッドをオーバーライドしてもよい。これらのメソッドを使用すると、フィルタのパフォーマンスを追跡できる。

CBaseRenderer::OnWaitStart

CBaseRenderer クラス

フィルタがサンプルのプレゼンテーション時間の待機を開始するときに呼び出される。

構文

virtual void OnWaitStart(void);

注意

WaitForRenderTime メソッドは、サンプルのプレゼンテーション時間の待機を開始するとき、このメソッドを呼び出す。このメソッドは基底クラスでは何もしないが、派生クラスでオーバーライドできる。

品質コントロールを実装する場合には、このメソッドと共に OnEndStart メソッドをオーバーライドしてもよい。これらのメソッドを使用すると、フィルタのパフォーマンスを追跡できる。

CBaseRenderer::Pause

CBaseRenderer クラス

フィルタをポーズする。

構文

HRESULT Pause(void);

戻り値

HRESULT 値を返す。可能な値は次の一覧のとおり。

S_OK | 移行は完了している。
S_FALSE | 移行は完了していない。

注意

このメソッドは、CBaseFilter::Pause メソッドをオーバーライドする。以下のステップを実行する。

  • CBaseFilter::Pause メソッドを呼び出す。
  • アロケータにコミットする (「IMemAllocator::Commit」を参照)。
  • 直前の状態が停止だった場合、フィルタは保持しているサンプルをすべて解放する (そのサンプルはもう有効でない)。
  • CompleteStateChange メソッドを呼び出し、その値を返す。

CBaseRenderer::PrepareReceive

CBaseRenderer クラス

サンプルをレンダリングする準備をする。

構文

virtual HRESULT PrepareReceive(
    IMediaSample *pMediaSample
);

パラメータ

pMediaSample
サンプルの IMediaSample インターフェイスへのポインタ。

戻り値

HRESULT 値を返す。可能な値は次の一覧のとおり。

S_OK | 成功。
E_FAIL | 失敗。
E_UNEXPECTED | 予期せぬエラー。
VFW_E_SAMPLE_REJECTED | フィルタはこのサンプルをドロップする。

注意

フィルタは、サンプルをレンダリングする前に、Receive メソッド内からこのメソッドを呼び出す。フィルタが実行中の場合、このメソッドはサンプルのレンダリングをスケジュールする。

フィルタに既に保留されているサンプルがある場合、または既にエンドオブストリームに達している場合、メソッドは E_UNEXPECTED を返す。アップストリーム フィルタによるストリーミングの呼び出し順序が正しくない可能性がある。

スケジューリング アルゴリズムにより、サンプルをドロップしなければならないと判断される場合 (「ScheduleSample」参照)、メソッドは VFW_E_SAMPLE_REJECTED を返す。ただし、サンプルのドロップはエラーでないため、入力ピンの IMemInputPin::Receive メソッドは、このエラー コードをアップストリーム フィルタに渡さない。

CBaseRenderer::PrepareRender

CBaseRenderer クラス

フィルタがサンプルをレンダリングする前に呼び出される。

構文

virtual void PrepareRender(void);

注意

フィルタは、OnReceiveFirstSample メソッドまたは Render メソッドを呼び出す前に、このメソッドを呼び出す。PrepareRender は基底クラスでは何もしない。派生クラスでは、このメソッドをオーバーライドして、レンダリング前に必要な任意の処理を実行できる。たとえば、ビデオ レンダラであれば、このメソッドをオーバーライドしてパレットを実現してもよい。

CBaseRenderer::Ready

CBaseRenderer クラス

状態の移行が完了していることを通知する。

構文

void Ready(void);

注意

このメソッドにより、GetState メソッドは S_OK を返すようになる。この値は、フィルタが現在の状態への移行を完了していることを示す。フィルタは、状態の移行を完了するたびに、このメソッドを呼び出す。

参照

CheckReady、NotReady

CBaseRenderer::Receive

CBaseRenderer クラス

ストリーム内の次のメディア サンプルを取得する。

構文

virtual HRESULT Receive(
    IMediaSample *pMediaSample
);

パラメータ

pMediaSample
サンプルの IMediaSample インターフェイスへのポインタ。

戻り値

成功なら S_OK を返し、それ以外の場合はエラーの原因を示す HRESULT 値を返す。

注意

入力ピンは、アップストリーム フィルタからサンプルを受け取るときに、このメソッドを呼び出す。

フィルタが実行中の場合、このメソッドは以下のステップを実行する。

  1. サンプルのレンダリングをスケジュールする (PrepareReceive)。
  2. スケジュールされた時間を待機する (WaitForRenderTime)。
  3. サンプルをレンダリングする (Render)。
  4. サンプルを解放する (ClearPendingSample)。

フィルタがポーズ中の場合、このメソッドは次のステップを実行する。

  1. サンプルが利用可能なことを派生クラスに通知する (OnReceiveFirstSample)。
  2. スケジュールされた時間を待機する。
  3. サンプルをレンダリングする。
  4. サンプルを解放する。

ポーズ中の場合、メソッドはステップ 2. でフィルタが実行状態に切り替わるまで待機する。この時点で、フィルタがサンプルをスケジュールする。

OnReceiveFirstSample メソッドは基底クラスでは何もしない。派生クラスではこのメソッドをオーバーライドできる。たとえば、ビデオ レンダラがポーズ中なら、通常は、最初のサンプルを静止画として表示する。

CBaseRenderer::Render

CBaseRenderer クラス

サンプルをレンダリングする。

構文

virtual HRESULT Render(
    IMediaSample *pMediaSample
);

パラメータ

pMediaSample
サンプルの IMediaSample インターフェイスへのポインタ。

戻り値

HRESULT 値を返す。可能な値は次の一覧のとおり。

S_FALSE | フィルタが停止しているか、または pMediaSample が NULL。
S_OK | 成功。

注意

このメソッドは、実際の処理をする純粋仮想メソッド DoRenderSample を呼び出す。派生クラスでは DoRenderSample を実装する必要がある。

このメソッドは、DoRenderSample を呼び出す直前に OnRenderStart メソッドを呼び出す。また、直後には OnRenderEnd メソッドを呼び出す。派生クラスでは、必要に応じてこれらの 2 つのメソッドをオーバーライドできる。

CBaseRenderer::ResetEndOfStream

CBaseRenderer クラス

エンドオブストリーム関連フラグをリセットする。

構文

virtual HRESULT ResetEndOfStream(void);

戻り値

S_OK を返す。

注意

このメソッドは、直前のエンドオブストリーム状態をクリアする。その時点で、フィルタが新しいデータを受け取れるようになる。Stop および BeginFlush メソッドは、このメソッドを呼び出す。

CBaseRenderer::ResetEndOfStreamTimer

CBaseRenderer クラス

EC_COMPLETE 通知をスケジュールするタイマをキャンセルする。

構文

void ResetEndOfStreamTimer(void);

参照

SendEndOfStream、TimerCallback

CBaseRenderer::Run

CBaseRenderer クラス

フィルタを実行する。

構文

HRESULT Run(void);

戻り値

成功なら S_OK を返し、それ以外の場合はエラーの原因を示す HRESULT 値を返す。

注意

このメソッドは、CBaseFilter::Run メソッドをオーバーライドする。以下の処理を実行する。

  • CBaseFilter::Run メソッドを呼び出す。
  • アロケータにコミットする (「IMemAllocator::Commit」を参照)。
  • 直前の状態が停止だった場合、フィルタは保持しているサンプルをすべて解放する (そのサンプルはもう有効でない)。
  • StartStreaming メソッドを呼び出し、その結果を返す。サンプルが保留されている場合、StartStreaming メソッドはサンプルのレンダリングをスケジュールする。

フィルタが接続されていない場合は、直ちに EC_COMPLETE イベントを送信する。

CBaseRenderer::ScheduleSample

CBaseRenderer クラス

サンプルのレンダリングをスケジュールする。

構文

virtual BOOL ScheduleSample(
    IMediaSample *pMediaSample
);

パラメータ

pMediaSample
サンプルの IMediaSample インターフェイスへのポインタ。

戻り値

サンプルがスケジュールされた場合は TRUE を返し、サンプルがドロップされた場合は FALSE を返す。

注意

このメソッドは、最初に、サンプルを直ちにレンダリングすべきか、後でレンダリングすべきか、またはドロップすべきかを判断する (このために GetSampleTimes メソッドを呼び出す)。直ちにレンダリングする場合、メソッドは m_RenderEvent イベントを通知する。後でレンダリングする場合には、スケジュールするために IReferenceClock::AdviseTime メソッドを呼び出す。

CBaseRenderer::SendEndOfStream

CBaseRenderer クラス

エンドオブストリームに達している場合に、フィルタ グラフ マネージャへの EC_COMPLETE イベントをスケジュールする。

構文

virtual HRESULT SendEndOfStream(void);

戻り値

HRESULT 値を返す。可能な値は次の一覧のとおり。

S_FALSE | フィルタ グラフ マネージャはイベント通知を受け取っていない。
S_OK | 成功。

注意

現在のサンプルの終了タイムより前に、フィルタにエンドオブストリーム通知が届くことがある。この場合、フィルタは、フィルタ グラフ マネージャに EC_COMPLETE 通知を送信する前に、待機しなければならない。

したがって、以下のようになる。

  • フィルタがエンドオブストリーム (EOS) 通知を先に受け取った場合、このメソッドはタイマ イベントをスケジュールする。タイマ イベントをアクティブにすると、フィルタが EC_COMPLETE イベントを送信する。
  • フィルタが EOS 通知を後から 受け取った場合、このメソッドは直ちに EC_COMPLETE イベントを送信する。
  • フィルタに保留されている EOS 通知がない場合、メソッドは何もせずに戻る。

タイマ用のコールバック メソッドは、TimerCallback である。EC_COMPLETE イベントを配信するため、フィルタは NotifyEndOfStream メソッドを呼び出す。

CBaseRenderer::SendNotifyWindow

CBaseRenderer クラス

アップストリーム フィルタにビデオ ウィンドウのハンドルを通知する。

構文

void SendNotifyWindow(
    IPin *pPin,
    HWND hwnd
);

パラメータ

pPin
アップストリーム フィルタの出力ピンの IPin インターフェイスへのポインタ。
hwnd
ビデオ ウィンドウのハンドル、または NULL。

戻り値

戻り値なし。

注意

アップストリーム フィルタの出力ピンが IMediaEventSink インターフェイスをサポートする場合、このメソッドは、ウィンドウ ハンドルと共に EC_NOTIFY_WINDOW イベント コードをアップストリーム フィルタに送信する。

ビデオ レンダラは、レンダラ自体の CompleteConnect メソッドを、このメソッドを呼び出すようにオーバーライドできる。これは、アップストリーム フィルタにウィンドウ ハンドルを知らせるためのメカニズムである。この場合、BreakConnect メソッドもオーバーライドし、NULL ハンドルを指定して SendNotifyWindow を呼び出すようにする。

CBaseRenderer::SendRepaint

CBaseRenderer クラス

フィルタ グラフ マネージャに再描画イベントを送信する。

構文

void SendRepaint(void);

注意

このメソッドは、以下の条件が満たされる場合、フィルタ グラフ マネージャに EC_REPAINT イベントを送信する。

  • 入力ピンが接続されている。
  • フィルタがフラッシュ中でない。
  • エンドオブストリームに達していない。
  • m_bAbort フラグが FALSE。
  • m_bRepaintStatus フラグが TRUE。

EC_REPAINT イベントの結果、グラフの状態に応じて、アップストリーム フィルタがサンプルを再送信するか、フィルタ グラフが現在位置までシークするか、またはフィルタ グラフ マネージャが一瞬ポーズする (「EC_REPAINT」を参照)。有効でない可能性があるため、このイベントはあまり使用しないほうがよい。ただし、ビデオ レンダラでは表示をリフレッシュしなければならないこともある。

CBaseRenderer::SetAbortSignal

CBaseRenderer クラス

レンダリングを停止して以降のサンプルを拒否するかどうかを示す、中止フラグを設定する。

構文

void SetAbortSignal(
    BOOL bAbort
);

パラメータ

bAbort
レンダリングを停止するかどうかを示すブール型の値。TRUE の場合、フィルタは以降のサンプルをレンダリングしない。

注意

このメソッドは m_bAbort フラグを設定する。

CBaseRenderer::SetMediaType

CBaseRenderer クラス

ピンのメディア タイプを設定するときに呼び出される。

構文

virtual HRESULT SetMediaType(
    const CMediaType *pmt
);

パラメータ

pmt
メディア タイプを指定する CMediaType オブジェクトへのポインタ。

戻り値

S_OK を返す。

注意

入力ピンは、ピン自体の CRendererInputPin::SetMediaType メソッドからこのメソッドを呼び出す。このメソッドは基底クラスでは何もしない。

CBaseRenderer::SetRepaintStatus

CBaseRenderer クラス

再描画イベントを有効または無効にする。

構文

void SetRepaintStatus(
    BOOL bRepaint
);

パラメータ

bRepaint
再描画イベントが有効になっているかどうかを示すブール型の値。TRUE の場合、フィルタは EC_REPAINT イベントをフィルタ グラフ マネージャに送信する。それ以外の場合は、EC_REPAINT イベントを送信しない。

注意

このメソッドは、フィルタ グラフ マネージャに EC_REPAINT イベントが溜まることを防ぐ。フィルタは、EC_REPAINT イベントを送信した後で、値 TRUE を指定してこのメソッドを呼び出す。次のデータを受け取るまで、フィルタは以降の EC_REPAINT イベントを送信しない。

CBaseRenderer::ShouldDrawSampleNow

CBaseRenderer クラス

サンプルのレンダリングをスケジュールする方法を判断する。

構文

virtual HRESULT ShouldDrawSampleNow(
    IMediaSample *pMediaSample,
    REFERENCE_TIME *pStartTime,
    REFERENCE_TIME *pEndTime
);

パラメータ

pMediaSample
サンプルの IMediaSample インターフェイスへのポインタ。
pStartTime
サンプルの開始タイムが格納された変数へのポインタ。
pEndTime
サンプルの終了タイムが格納された変数へのポインタ。

戻り値

S_FALSE を返す。派生クラスでこのメソッドをオーバーライドする場合には、次の一覧に含まれるいずれかの値を返す。

S_OK | サンプルを直ちにレンダリングしなければならない。
S_FALSE | タイム スタンプに基づいて、サンプルのレンダリングをスケジュールしなければならない。
エラー コード | このサンプルをレンダリングしてはならない。

注意

GetSampleTimes メソッドはこのメソッドを呼び出す。デフォルトでは、サンプルのレンダリングが、常にタイム スタンプに基づいてスケジュールされる。このメソッドは、たとえば品質コントロール データを収集するように、派生クラスでオーバーライドできる。

CBaseRenderer::SignalTimerFired

CBaseRenderer クラス

レンダリングのスケジュールに使用されるタイマ識別子をクリアする。

構文

virtual void SignalTimerFired(void);

注意

フィルタは、レンダリング タイマをアクティブにするとき (「WaitForRenderTime」を参照)、またはキャンセルするとき (「CancelNotification」を参照) に、このメソッドを呼び出す。メソッドは、m_dwAdvise メンバ変数を 0 にリセットする。

CBaseRenderer::SourceThreadCanWait

CBaseRenderer クラス

ストリーミング スレッドを保持または解放する。

構文

virtual HRESULT SourceThreadCanWait(
    BOOL bCanWait
);

パラメータ

bCanWait
ストリーミング スレッドを保持するかどうかを示すブール型の値。TRUE の場合、以降のサンプルをレンダリングするまでフィルタが待機する間、ストリーミング スレッドがブロックされる。FALSE の場合、ストリーミング スレッドは解放される。

戻り値

S_OK を返す。

注意

値 FALSE を指定した SourceThreadCanWait メソッドの呼び出しは、ブロックされた IMemInputPin::Receive 呼び出しからフィルタを強制的に復帰させる。フィルタが実行中の場合、現在のサンプルのプレゼンテーション時間まで、Receive の呼び出しをブロックする。フィルタがポーズ中の場合は、Receive の呼び出しを無期限にブロックする。この動作によって、ストリーム内のデータの流れを調整する。ただし、フィルタが停止中またはフラッシュ中の場合、ブロックは行わない。

ブロックは、m_RenderEvent と m_ThreadSignal の 2 つのイベントを待機する WaitForRenderTime メソッドが制御する。m_RenderEvent イベントは、プレゼンテーション時間になると通知済になる。m_ThreadSignal イベントは、値 FALSE で SourceThreadCanWait を呼び出すと通知済になる。このイベントは、値 TRUE で SourceThreadCanWait を呼び出すとリセットされる。

Stop および BeginFlush メソッドは値 FALSE で SourceThreadCanWait を呼び出す (ストリーミング スレッドを解放する)。Pause、Run、および EndFlush メソッドは、値 TRUE で SourceThreadCanWait を呼び出す。

CBaseRenderer::StartStreaming

CBaseRenderer クラス

フィルタが実行状態に切り替わるときに、ストリーミングを開始する。

構文

virtual HRESULT StartStreaming(void);

戻り値

S_OK またはその他の HRESULT 値を返す。

注意

フィルタにサンプルがある場合、フィルタはそのサンプルのレンダリングをスケジュールする。それ以外の場合、保留されているエンドオブストリーム通知があれば、フィルタはフィルタ グラフ マネージャに EC_COMPLETE イベントを送信する。

このメソッドは OnStartStreaming メソッドを呼び出す。OnStartStreaming メソッドは基底クラスでは何もしないが、派生クラスでオーバーライドできる。

CBaseRenderer::Stop

CBaseRenderer クラス

フィルタを停止する。

構文

HRESULT Stop(void);

戻り値

S_OK を返す。

注意

このメソッドは CBaseFilter::Stop メソッドをオーバーライドする。以下の処理を実行する。

  • CBaseFilter::Stop を呼び出す。
  • アロケータへのコミットを解除する (「IMemAllocator::Decommit」を参照)。
  • スケジュールされているレンダリングをすべてキャンセルし、ストリーミング スレッドを解放する。
  • 保留されている Receive 呼び出しの完了を待機する。

CBaseRenderer::StopStreaming

CBaseRenderer クラス

フィルタが実行状態以外に切り替わるときに、ストリーミングを停止する。

構文

virtual HRESULT StopStreaming(void);

戻り値

S_OK を返す。

注意

このメソッドは OnStopStreaming メソッドを呼び出す。OnStopStreaming メソッドは基底クラスでは何もしないが、派生クラスでオーバーライドできる。

CBaseRenderer::TimerCallback

CBaseRenderer クラス

エンドオブストリーム用のタイマ イベントで使用するコールバック メソッド。

構文

void TimerCallback(void);

注意

SendEndOfStream メソッドは、タイマ イベントを使って EC_COMPLETE 通知をスケジュールする。TimerCallback メソッドは、タイマ イベント用のコールバック関数である。TimerCallback メソッドがもう 1 度 SendEndOfStream を呼び出し、SendEndOfStream が EC_COMPLETE 通知を送信するか、またはほかのタイマを設定するかを判断する。

ResetEndOfStreamTimer メソッドは、タイマ イベントをキャンセルする。

CBaseRenderer::WaitForReceiveToComplete

CBaseRenderer クラス

Receive メソッドが完了するまで待機する。

構文

void WaitForReceiveToComplete(void);

注意

Stop および BeginFlush メソッドはこのメソッドを呼び出して、状態の変化と Receive メソッドの同期をとる。

つまり、このメソッドは、m_bInReceive フラグが FALSE になるまで待機する間に、メッセージをディスパッチする。このフラグは、PrepareReceive メソッド内で TRUE になり、Receive メソッドが PrepareRender メソッドを呼び出した後で FALSE に戻る。派生クラスでは、PrepareRender を使ってパレットを設定できる。PrepareRender の完了を待機すると、状態の変化が起きる前に、パレット変更メッセージが確実にディスパッチされる。この結果、デッドロックの危険性を回避できる。

CBaseRenderer::WaitForRenderTime

CBaseRenderer クラス

現在のサンプルのプレゼンテーション時間を待機する。

構文

virtual HRESULT WaitForRenderTime(void);

戻り値

以下のいずれかの HRESULT 値を返す。

S_OK | 成功。
VFW_E_STATE_CHANGED | プレゼンテーション時間になる前に、フィルタの状態が変化した。

注意

このメソッドは、以下のいずれかが起きるまで待機する。

  • サンプルのプレゼンテーション時間になる (つまり、サンプルをレンダリングできる)。
  • フィルタがデータのフラッシュを停止または開始する。

プレゼンテーション時間になると、m_RenderEvent イベントが通知済になる。状態が変化すると、m_ThreadSignal イベントが通知済になる。このメソッドは、両方のイベントを待機する。派生クラスでは、必要に応じてこのメソッドをオーバーライドして、ほかのイベントを待機できる。

このメソッドは、待機を開始するとき OnWaitStart メソッドを呼び出し、待機を終了すると OnWaitEnd メソッドを呼び出す。どちらのメソッドも、基底クラスでは何もしないが、派生クラスでオーバーライドできる。


CBaseStreamControl クラス

このクラスは、入力ピンと出力ピンの両方について、IAMStreamControl インターフェイスを実装する。このクラスによって、フィルタ グラフ内の個々のストリームの開始および終了を制御できる。詳細については、「IAMStreamControl」を参照すること。

IAMStreamControl をサポートするピンを実装する場合は、この基底クラスから継承する必要がある。入力ピンの標準的な宣言を次に示す。

class CMyInputPin : public CBaseInputPin, public CBaseStreamControl

NonDelegatingQueryInteface をオーバーライドして IAMStreamControl を公開する必要がある。詳細については、「IUnknown の実装方法」を参照すること。

ストリーム制御の状態

このクラスは、StreamControlState 列挙を使用してストリームの現在の状態を記述する。

  • STREAM_FLOWING:ストリームはピンを介して流れている。
  • STREAM_DISCARDING:ピンがサンプルを破棄している。

このクラスは、現在の状態を取得するヘルパー関数 CheckStreamState も提供する。このクラスから派生したピンで、指定されたサンプルの処理方法を判断するには、この関数を呼び出す必要がある。

また、ピンが基準クロックと同期していることも重要である。基準クロックと同期していない場合、ピンはすべてのサンプルを直ちに破棄するので、ファイル全体がフィルタを介して可能な範囲で高速にプッシュされ、後でストリームを再開できなくなる場合がある。ピンが正しく同期している場合、ピンはスケジュールされた時間までサンプルを保持した後、サンプルを破棄する。基準クロックを指定するには、SetSyncSource メンバ関数を呼び出す。

CBaseStreamControl クラスの使用

この基底クラスを正しく使用するには、特定の時点で特定のメンバ関数を呼び出さなければならない。以下にその方法と、簡単なコードの例を示す。実際のコードでは、この例で省略されているその他の詳細な処理を行わなければならない場合がある。

  • 基準クロック: フィルタの IMediaFilter::SetSyncSource メソッドで、ピンの基準クロックを設定する。IReferenceClock インターフェイス ポインタを使用して、SetSyncSource メンバ関数を呼び出す。
    STDMETHODIMP CMyFilter::SetSyncSource(IReferenceClock *pClock)
{
m_pMyPin->SetSyncSource(pClock);
return CBaseFilter::SetSyncSource(pClock);
}
  • イベント シンク: フィルタの JoinFilterGraph メソッドで、フィルタがフィルタ グラフから IMediaEventSink インターフェイスへのポインタを取得した後、SetFilterGraph メンバ関数を呼び出すことによって、そのポインタをピンに渡す。
    STDMETHODIMP CMyFilter::JoinFilterGraph(IFilterGraph * pGraph, LPCWSTR pName)
{
HRESULT hr = CBaseFilter::JoinFilterGraph(pGraph, pName);
if (hr == S_OK)
m_pMyPin->SetFilterGraph(m_pSink);
return hr;
}
  • フィルタの状態: フィルタの状態が変化した場合は、ピンについて NotifyFilterState メンバ関数を呼び出す。次の例は、実行状態への移行を示している。
    STDMETHODIMP CMyFilter::Run(REFERENCE_TIME tStart)
{
m_pMyPin->NotifyFilterState(State_Running, tStart);
return CBaseFilter::Run(tStart);
}
  • フラッシュ: ピンがデータのフラッシュを開始 (IPin::BeginFlush) またはデータのフラッシュを終了 (IPin::EndFlush) したときには、それぞれ TRUE または FALSE の値を指定して Flushing メンバ関数を呼び出す。
    HRESULT CMyPin::BeginFlush()
{
Flushing(TRUE);
return CBaseOutputPin::BeginFlush();    // 入力ピンの場合は、CBaseInputPin
}

HRESULT CMyPin::EndFlush()
{
Flushing(FALSE);
return CBaseOutputPin::EndFlush();   // 入力ピンの場合は、CBaseInputPin
}
  • メディア サンプル: ピンの IMemInputPin::Receive メソッドで、CheckStreamState 関数を呼び出して、サンプルを配信するか、破棄するかを判断する。出力ピンがサンプルを破棄した場合は、出力ピンが配信する次のサンプルについて、不連続性のプロパティを設定しなければならない。次の例では、派生クラスで m_fLastSampleDiscarded というメンバ変数を使用して、不連続性を追跡している。
    CMyPin::Receive(IMediaSample *pSample)
{
int iStreamState = CheckStreamState(pSample);
if (iStreamState == STREAM_FLOWING) {
if (m_fLastSampleDiscarded)
pSample->SetDiscontinuity(TRUE);
m_fLastSampleDiscarded = FALSE;
// サンプルを配信するか、その他の処理を行う。
    }
else {
m_fLastSampleDiscarded = TRUE;     // 次のサンプルは不連続
// このサンプルを配信せずに、破棄する。
    }
}

メンバ関数

CBaseStreamControl | CBaseStreamControl オブジェクトを作成する。
CheckStreamState | ストリームの現在の状態を取得する。
Flushing | フィルタがフラッシュするときにピンに通知する。
GetInfo | 現在のストリーミングの設定に関する情報を取得する。
NotifyFilterState | ピンにフィルタの状態を通知する。
SetFilterGraph | フィルタ グラフが使用するイベント シンク通知を設定する。
SetSyncSource | フィルタが含まれるグラフによって使用される基準クロックを識別する。
StartAt | いつストリーミング データの送信を開始するかをピンに通知する。
StopAt | いつデータの処理を停止し、新しいサンプルを破棄するかをピンに通知する。

CBaseStreamControl::CBaseStreamControl

CBaseStreamControl クラス

CBaseStreamControl オブジェクトを作成する。

構文

CBaseStreamControl(void);

戻り値

戻り値なし。

注意

この関数は、開始タイムと終了タイムの両方を MAX_TIME に初期化し、ストリームの先頭から開始して、ストリームの最後まで停止しないことを指定する。

CBaseStreamControl::CheckStreamState

CBaseStreamControl クラス

ストリームの現在の状態を取得する。

構文

enum StreamControlState CheckStreamState(
IMediaSample *pSample
    );

パラメータ

pSample
IMediaSample インターフェイスへのポインタ。

戻り値

StreamControlState 列挙型を返す。

注意

フィルタは、ピンが転送しようとするサンプルを受信したときにこのメンバ関数を呼び出す。1 つ以上のサンプルを破棄した後で最初に転送するサンプルは、不連続性のマークを付ける必要がある。

フィルタが IAMDroppedFrames を実装し、ドロップされたフレームの数をカウントしている場合、破棄されたフレームをドロップされたフレームとしてカウントしてはならない。

CBaseStreamControl::Flushing

CBaseStreamControl クラス

フィルタがフラッシュしていることをピンに通知する。

構文

void Flushing(
BOOL bInProgress
    );

パラメータ

bInProgress
フィルタがフラッシュしているかどうかを示す値。TRUE はフラッシュが進行中であることを示す。FALSE はフラッシュしていないことを示す。

戻り値

戻り値なし。

注意

独自のフィルタを実装する場合は、ピンで BeginFlush および EndFlush を呼び出したときにこのメンバ関数を呼び出して、フラッシュしていることを通知しなければならない。

シークをサポートしないキャプチャ フィルタはこのメソッドを呼び出さない。

CBaseStreamControl::GetInfo

CBaseStreamControl クラス

現在のストリーミングの設定に関する情報を取得する。

構文

HRESULT GetInfo(
AM_STREAM_INFO *pInfo
    );

パラメータ

pInfo
AM_STREAM_INFO 構造体へのポインタ。

戻り値

S_OK を返す。

注意

このメンバ関数は、IAMStreamControl インターフェイスを実装し、ピンがストリーミング中であるかどうかを調べたり、ストリームの属性を取得するためにユーザーによって呼び出される。

CBaseStreamControl::NotifyFilterState

CBaseStreamControl クラス

ピンにフィルタの状態を通知する。

構文

void NotifyFilterState(
FILTER_STATE new_state,
REFERENCE_TIME tStart = 0
    );

パラメータ

new_state
フィルタの新しい状態。
tStart
ストリーミングが開始される時間 (new_state が State_Running の場合のみ有効)。

戻り値

戻り値なし。

注意

このメンバ関数は、FILTER_STATE 列挙型変数を設定することによって、ピンにフィルタの新しい状態を通知する。

独自のフィルタを実装している場合は、次の例に示すように、フィルタの状態が変化するたびに、ピンの CBaseStreamControl::NotifyFilterState メンバ関数にフィルタの状態を通知する。

STDMETHODIMP CMyFilter::Run(REFERENCE_TIME tStart)
{
// エラー チェックが成功した場合
m_pMyPin->NotifyFilterState(State_Running, tStart);

// 次のように、次に行うべき任意の処理を続行する。
return CBaseFilter::Run(tStart);
}

STDMETHODIMP CMyFilter::Pause()
{
// エラー チェックが成功した場合
m_pMyPin->NotifyFilterState(State_Paused, 0);

// 次のように、次に行うべき任意の処理を続行する。
return CBaseFilter::Pause();
}

STDMETHODIMP CMyFilter::Stop()
{
// エラー チェックが成功した場合
m_pMyPin->NotifyFilterState(State_Stopped, 0);

// 次のように、次に行うべき任意の処理を続行する。
return CBaseFilter::Stop(tStart);
}

CBaseStreamControl::SetFilterGraph

CBaseStreamControl クラス

フィルタ グラフがイベント通知で使用するイベント シンクを設定する。

構文

void SetFilterGraph(
IMediaEventSink *pSink
    );

パラメータ

pSink
IMediaEventSink インターフェイスへのポインタ。

戻り値

戻り値なし。

注意

フィルタは、IMediaEventSink を作成した後、JoinFilterGraph メンバ関数でこのメンバ関数を呼び出す。

CBaseStreamControl::SetSyncSource

CBaseStreamControl クラス

フィルタが含まれるグラフによって使用される基準クロックを識別する。

構文

void SetSyncSource(
IReferenceClock *pRefClock
    );

パラメータ

pRefClock
IReferenceClock インターフェイスへのポインタ。

戻り値

戻り値なし。

注意

このクラスを使用するピンを持つフィルタは、同期ソース情報をこのメンバ関数に渡すようにする必要がある。

CBaseStreamControl::StartAt

CBaseStreamControl クラス

いつストリーミング データの送信を開始するかをピンに通知する。

構文

HRESULT StartAt(
const REFERENCE_TIME *ptStart = NULL,
DWORD dwCookie = 0
    );

パラメータ

ptStart
ストリーミングを開始する基準タイムへのポインタ。NULL の場合は、直ちに開始する (通知しない)。MAX_TIME の場合、開始は取り消されるか、効果がない。
dwCookie
開始時に通知と共に送信される 0 以外の値。ptStart が NULL 以外または MAX_TIME の場合にのみ使用される。

戻り値

NOERROR を返す。

注意

ストリームはデフォルトで有効なので、このメンバ関数は、以前に StopAt を呼び出した場合以外は効果がない。

ストリームが STREAM_FLOWING 状態になると、フィルタは EC_STREAM_CONTROL_STARTED イベント通知をフィルタ グラフ マネージャに送信する。

注 開始と終了が同じ時点にスケジュールされている場合、開始は終了の極限小時間前に行われると見なされる。この効果を使用して、単一のフレームをキャプチャできる。

CBaseStreamControl::StopAt

CBaseStreamControl クラス

いつデータの処理を停止し、新しいサンプルを破棄するかをピンに通知する。

構文

HRESULT StopAt(
const REFERENCE_TIME *ptStop = NULL,
BOOL bSendExtra = FALSE,
DWORD dwCookie = 0
    );

パラメータ

ptStop
ストリーミングを終了する基準タイムへのポインタ。NULL の場合は、直ちに終了する (通知しない)。MAX_TIME の場合は、終了を取り消す。
bSendExtra
スケジュールされた ptStop 時間よりも後にピンが追加のサンプルを送信するかどうかを指定するフラグ。TRUE は追加のサンプルを送信することを示す。詳細については、「注意」を参照すること。
dwCookie
終了時に通知と共に送信される値。ptStart が NULL 以外または MAX_TIME の場合にのみ使用される。

戻り値

NOERROR を返す。

注意

このメンバ関数は、IAMStreamControl::StopAt メソッドを実装し、ストリームの終了をサポートする必要があるピンおよびフィルタによって使用される。このメンバ関数は、StreamControlState 列挙型を STREAM_DISCARDING に設定する。

ビデオ キャプチャの場合は、キャプチャ フィルタの出力ピンと、マルチプレクサの入力ピンの両方で StopAt 指定して、マルチプレクサに終了の通知を送信させる。これによって、キャプチャ フィルタは不必要に余分なフレームをキャプチャすることがなくなり、マルチプレクサが最後のフレームをディスクに書き込むことを保証できる。

さらに、キャプチャの出力ピンでは bSendExtra 変数に TRUE を指定し、ほかのすべてのピンでは FALSE を指定する必要がある。追加のフレームが送信されないと、マルチプレクサは終了タイムを無限に待機することになり、既にすべてのキャプチャ情報を受信していることが認識されない。

ICaptureGraphBuilder を使用している場合は、ICaptureGraphBuilder::ControlStream メソッドが自動的にこの処理を行う。

注 パケットの途中で終了タイムが指定されている場合、フィルタはパケット全体を配信した後、破棄状態になる。また、開始と終了が同じ時点にスケジュールされている場合、開始は終了の極限小時間前に行われると見なされる。この効果を使用して、単一のフレームをキャプチャできる。


CBaseVideoRenderer クラス

CBaseVideoRenderer 基底クラスは、ビデオ レンダラ フィルタを構築するために使用される。

Protected データ メンバ

m_bDrawLateFrames | フレームがドロップされないことを通知するフラグ。デバッグ専用。これは同期を破棄する。
m_bSupplierHandlingQuality | TRUE は品質 コントロール メッセージが処理されることを示す。これによって、レンダラはフレーム自体がドロップするまで待機し、サプライヤがフレームをドロップした直後に次のフレームを表示することができる。
m_cFramesDrawn | ストリーミングが開始された後に描画されたフレームの合計数。
m_cFramesDropped | ストリーミングが開始された後、レンダラでドロップされた累積フレーム数。フレームは、レンダラが認識せずに、アップストリームでもドロップできる。
m_idDecision | ShouldDrawSampleNow の決定コードの MSR_id。
m_idDuration | フレームの時間幅の MSR_id。
m_idFrameAccuracy | フレームが遅延した時間のパフォーマンス ログ識別子 (ミリ秒単位)。
m_idFrameAvg | 同期および品質 コントロールで使用される平均フレーム時間のパフォーマンス ログ識別子。
m_idQualityRate | 要求された品質 レートの MSR_id。
m_idQualityTime | 要求された品質 タイムの MSR_id。
m_idRenderAvg | 記録された平均レンダラ時間のパフォーマンス ログ識別子。
m_idSchLateTime | スケジュール時のフレームの遅延を示す MSR_id。
m_idSendQuality | 通知のタイミングの MSR_id (使用されない)。
m_idTimeStamp | フレームのタイム スタンプの MSR_id。
m_idWait | 記録された待機時間のパフォーマンス ログ識別子 (使用されない)。
m_idWaitReal | 実際の待機時間のパフォーマンス ログ識別子。
m_iSumFrameTime | フレーム間の時間の合計。プロパティ ページで必要になる。
m_iSumSqAcc | プロパティ ページで必要な精度 (ミリ秒単位) の 2 乗の合計。
m_iSumSqFrameTime | フレーム間の時間の 2 乗の合計。プロパティ ページで必要になる。
m_iTotAcc | プロパティ ページで必要な精度 (ミリ秒単位) の合計。
m_nNormal | スケジュールされた時間に描画される連続するフレームの数。負の数は、フレームがレンダラによってドロップされたことを示す。
m_trDuration | 最後のフレームの時間幅 (開始タイムと終了タイムの差)。
m_trEarliness | フレームがドロップされた場合に、どれくらい早くフレームを再生できるか。
m_trFrame | 最後に記録されたフレーム間の時間。統計的測定で使用される。
m_trFrameAvg | 基準タイムの単位でのフレーム間の平均時間。
m_trLastDraw | 前のフレームの時間。フレーム間の時間の参照で使用される。
m_trLate | 現在のフレームが遅延する時間。統計的測定で使用される。
m_trRenderAvg | フレームがビットブロック転送を実行するためにかかる時間。
m_trRenderLast | 最後のフレームのビットブロック転送の時間。
m_trRenderLast | ビットブロック転送を開始する時間。m_trRenderLast を取得するために使用される。
m_trThrottle | 各フレームをレンダリングした後に挿入する時間。通常、オーディオの品質を向上させたときに使用され、これを行うためにビデオのパフォーマンスを低下させる必要がある。
m_trWaitAvg | 基準タイムの単位での平均待機時間。
m_tStreamingStart | プロパティ ページの統計で使用される。現在のストリーミング処理の開始タイム、または現在ストリーミングが行われていない場合は前のストリーミング処理の開始タイムを表す。

メンバ関数

CBaseVideoRenderer | CBaseVideoRenderer オブジェクトを作成する。
GetStdDev | フレームごとの統計として、各フレームの予定時間と実際にレンダリングされた時間との標準偏差を予測する。
PreparePerformanceData | 現在のフレームの m_trLate および m_trFrame の値を設定する。
ThrottleWait | 各フレームの後に待機時間を挿入する。

オーバーライド可能なメンバ関数

JoinFilterGraph | フィルタがフィルタ グラフから削除されたときに、EC_WINDOW_DESTROYED イベント通知を送信する。
OnDirectRender | 同期および品質 コントロールを制御するタイミング情報を収集する。
OnRenderEnd | 品質 コントロールおよび同期の情報を記録する。
OnRenderStart | 品質 コントロールおよび同期の情報を記録する。
OnStartStreaming | ストリーミングを制御するすべての時間をリセットする。
OnStopStreaming | プロパティ ページのレポート用に時間を修正するために、ストリーミングの最後に呼び出される。
OnWaitEnd | 待機時間の終了時に呼び出される。パフォーマンス ログ専用。
OnWaitStart | 待機していた時間と待機していなかった時間を更新する。パフォーマンス ログ専用。
RecordFrameLateness | レンダリングがどの程度遅れずに行われたかを記録し、プロパティ ページの統計情報を収集する。
ResetStreamingTimes | ストリーミングを制御するすべての時間をリセットする。
ScheduleSample | クロックを使用してアドバイズ リンクを設定する。
SendQuality | サプライヤが品質に関して実行する処理を示す品質 メッセージを送信する。
ShouldDrawSampleNow | クロックを使用してタイマのアドバイズ リンクを設定せずに、ビデオを予定どおりに描画するかどうかを判断する。

実装される IQualProp メソッド

get_AvgFrameRate | ストリーミングが開始された後の平均フレーム レートを、100 秒あたりのフレーム数単位で取得する。
get_AvgSyncOffset | 各フレームの予定時間と実際にレンダリングされた時間の間の平均時間をミリ秒単位で取得する。これは、ストリーミングが開始された後、すべてのフレームに適用される。
get_DevSyncOffset | ストリーミングが開始された後のすべてのフレームについて、各フレームの予定時間と実際にレンダリングされた時間の間のミリ秒単位の時間の標準偏差を取得する。
get_FramesDrawn | ストリーミングの開始後に描画されたフレーム数を取得する。
get_FramesDroppedInRenderer | レンダラによってドロップされたフレーム数を取得する。フレームはアップストリームでもドロップできる。
get_Jitter | 各フレームと次のフレームの間のミリ秒単位の時間について標準偏差を取得する。これは、ストリーミングが開始された後、すべてのフレームに適用される。

実装される INonDelegatingUnknown メソッド

NonDelegatingQueryInterface ほかのインターフェイス、特にプロパティ ページへのアクセスを提供する。

実装される IQualityControl メソッド

Notify | 品質の変更が要求されたことを受信者に通知する。
SetSink | 品質 メッセージを受け取る IQualityControl オブジェクトを設定する。

CBaseVideoRenderer::CBaseVideoRenderer

CBaseVideoRenderer クラス

CBaseVideoRenderer オブジェクトを作成する。

構文

CBaseVideoRenderer(
REFCLSID RenderClass,
TCHAR *pName,
LPUNKNOWN pUnk,
HRESULT *phr
    );

パラメータ

RenderClass
このレンダラのクラス識別子。
pName
デバッグのために使用される記述へのポインタ。
pUnk
集成された所有者オブジェクトへのポインタ。
phr
HRESULT 値へのポインタ。

戻り値

戻り値なし。

CBaseVideoRenderer::get_AvgFrameRate

CBaseVideoRenderer クラス

到達した平均フレーム レートを計算して取得する。

構文

HRESULT get_AvgFrameRate(
int *piAvgFrameRate
    );

パラメータ

piAvgFrameRate
ストリーミング開始後の 1 秒あたりのフレーム数へのポインタ。

戻り値

HRESULT 値を返す。

注意

このメンバ関数は、IQualProp::get_AvgFrameRate メソッドを実装する。

CBaseVideoRenderer::get_AvgSyncOffset

CBaseVideoRenderer クラス

ストリーミングが開始された後のすべてのフレームについて、各フレームの予定時間と実際にレンダリングされた時間の間のミリ秒単位の時間の平均を取得する。

構文

HRESULT get_AvgSyncOffset(
int *piAvg
    );

パラメータ

piAvg
以前に記述された時間の平均へのポインタ。

戻り値

HRESULT 値を返す。

注意

このメンバ関数は、IQualProp::get_AvgSyncOffset メソッドを実装する。

CBaseVideoRenderer::get_DevSyncOffset

CBaseVideoRenderer クラス

ストリーミングが開始された後のすべてのフレームについて、各フレームの予定時間と実際にレンダリングされた時間の間のミリ秒単位の時間の標準偏差を取得する。

構文

HRESULT get_DevSyncOffset(
int *piDev
    );

パラメータ

piDev
以前に記述された時間の標準偏差へのポインタ。

戻り値

HRESULT 値を返す。

注意

このメンバ関数は、IQualProp::get_DevSyncOffset メソッドを実装する。

CBaseVideoRenderer::get_FramesDrawn

CBaseVideoRenderer クラス

ストリーミングの開始後に描画されたフレーム数を示す、m_cFramesDrawn メンバ変数を取得する。

構文

HRESULT get_FramesDrawn(
int *pcFramesDrawn
    );

パラメータ

pcFramesDrawn
描画されたフレームの数へのポインタ。

戻り値

HRESULT 値を返す。

注意

このメンバ関数は、IQualProp::get_FramesDrawn メソッドを実装する。

CBaseVideoRenderer::get_FramesDroppedInRenderer

CBaseVideoRenderer クラス

レンダラによってドロップされたフレーム数を取得する。

構文

HRESULT get_FramesDroppedInRenderer(
int *pcFramesDropped
    );

パラメータ

pcFramesDropped
ドロップされたフレームの数へのポインタ。

戻り値

HRESULT 値を返す。

注意

このメンバ関数は、IQualProp::get_FramesDroppedInRenderer メソッドを実装する。この方法で、プロパティ ページはスケジューラからのデータを取得できる。フレームは、レンダラが認識せずに、アップストリームでもドロップできる。

CBaseVideoRenderer::get_Jitter

CBaseVideoRenderer クラス

ストリーミング開始後のすべてのフレームについて、各フレームと次のフレームの間のミリ秒単位の時間について標準偏差を取得する。

構文

HRESULT get_Jitter(
int *piJitter
    );

パラメータ

piJitter
フレーム間の時間の標準偏差へのポインタ (ミリ秒単位)。

戻り値

HRESULT 値を返す。

注意

このメンバ関数は、IQualProp::get_Jitter メソッドを実装する。

CBaseVideoRenderer::GetStdDev

CBaseVideoRenderer クラス

フレームごとの統計として、各フレームの予定時間と実際にレンダリングされた時間との標準偏差を予測する。

構文

HRESULT GetStdDev(
int nSamples,
int *piResult,
LONGLONG llSumSq,
LONGLONG iTot
    );

パラメータ

nSamples
ビデオ レンダラによって受信されたビデオ サンプルの数を格納する整数値。
piResult
標準偏差を格納する整数値へのポインタ。
llSumSq
レンダリングされたすべてのビデオ サンプルのミリ秒単位の標準偏差を表す値。この値が小さいほど、レンダリングは一貫性がある。
iTot
レンダリングされたすべてのビデオ サンプルについて、スタンプの時間とレンダリングされた時間とのミリ秒単位の平均値を表す値。

戻り値

NOERROR を返す。

CBaseVideoRenderer::JoinFilterGraph

CBaseVideoRenderer クラス

フィルタがフィルタ グラフから削除されたときに、EC_WINDOW_DESTROYED イベント通知を送信する。

構文

HRESULT JoinFilterGraph(
IBaseFilterGraph *pGraph,
LPCWSTR pName
    );

パラメータ

pGraph
結合するフィルタ グラフへのポインタ。
pName
[in, string] 追加されるフィルタの名前へのポインタ。

戻り値

戻り値なし。

注意

このメンバ関数は、CBaseFilter::JoinFilterGraph メンバ関数をオーバーライドする。この関数が、フィルタがフィルタ グラフを離れたことがフィルタに通知されていると判断した場合 (pGraph が Null で、m_pGraph が Null ではない)、EC_WINDOW_DESTROYED イベント通知を送信して、リソース マネージャがレンダラをフォーカス オブジェクトとして保持しないようにする。

CBaseVideoRenderer::NonDelegatingQueryInterface

CBaseVideoRenderer クラス

インターフェイスを返し、参照カウントをインクリメントする。

構文

HRESULT NonDelegatingQueryInterface(
REFIID riid,
VOID **ppv
    );

パラメータ

riid
参照識別子。
ppv
インターフェイスへのポインタのアドレス。

戻り値

ppv が無効な場合は、E_POINTER を返す。クエリが成功した場合は NOERROR、失敗した場合は E_NOINTERFACE を返す。

CBaseVideoRenderer::Notify

CBaseVideoRenderer クラス

品質の変更が要求されたことを示す通知を受信する。

構文

HRESULT Notify(
IBaseFilter *pSelf,
Quality q
    );

パラメータ

pSelf
[in] 品質通知を送信しているフィルタへのポインタ。
q
[in] 品質通知構造体。

戻り値

HRESULT 値を返す。

注意

このメンバ関数は、ビデオ レンダラについて IQualityControl::Notify メソッドを実装する。このメンバ関数は、品質を削減しなければならない場合に、通常フィルタ グラフ マネージャによって呼び出される。これは、オーディオの再生品質を、ビデオの再生品質を低下させなければならない程度まで向上させた場合に行われる。

Notify は、m_trThrottle データ メンバを、ThrottleWait によってフレーム間に挿入される遅延値に設定する。

CBaseVideoRenderer::OnDirectRender

CBaseVideoRenderer クラス

同期および品質 コントロールを制御するタイミング情報を収集する。

構文

virtual void OnDirectRender(
IMediaSample *pMediaSample
    );

パラメータ

pMediaSample
メディア サンプルへのポインタ。

戻り値

HRESULT 値を返す。

注意

OnRenderStart および OnRenderEnd の代わりに、このメンバ関数を呼び出す。これは、Microsoft® DirectDraw® ビデオ レンダラによって使用される。

CBaseVideoRenderer::OnRenderEnd

CBaseVideoRenderer クラス

割り込みによってレンダリング時間が異なる場合に、スムージングを実行する。

構文

void OnRenderEnd(
IMediaSample *pMediaSample
    );

パラメータ

pMediaSample
メディア サンプルへのポインタ。

戻り値

戻り値なし。

注意

このメンバ関数は、イメージを描画した直後に呼び出す必要がある。

このメンバ関数は、CBaseRenderer::OnRenderEnd をオーバーライドする。

CBaseVideoRenderer::OnRenderStart

CBaseVideoRenderer クラス

レンダリングの情報を設定する。

構文

void OnRenderStart(
IMediaSample *pMediaSample
    );

パラメータ

pMediaSample
メディア サンプルへのポインタ。

戻り値

戻り値なし。

注意

このメンバ関数は、システムから現在のクロック タイムを取得し、描画が完了したしたときに使用されるメンバ変数に格納する。この関数は、パフォーマンス ログの記録も実行する。このメンバ関数は、描画が開始される直前に呼び出す必要がある。

このメンバ関数は、CBaseRenderer::OnRenderStart をオーバーライドする。

CBaseVideoRenderer::OnStartStreaming

CBaseVideoRenderer クラス

ストリーミングを制御するすべての時間をリセットする。

構文

HRESULT OnStartStreaming(void);

戻り値

HRESULT 値を返す。

注意

このメンバ関数は、CBaseRenderer::OnStartStreaming をオーバーライドする。

CBaseVideoRenderer::OnStopStreaming

CBaseVideoRenderer クラス

プロパティ ページのレポート用に時間を修正するために、ストリーミングの最後に呼び出される。

構文

HRESULT OnStopStreaming(void);

戻り値

HRESULT 値を返す。

注意

このメンバ関数は 2 回呼び出される。1 回はポーズしたときで、もう 1 回は実際に停止したときである。

このメンバ関数は、CBaseRenderer::OnStopStreaming をオーバーライドする。

CBaseVideoRenderer::OnWaitEnd

CBaseVideoRenderer クラス

待機時間の終了時に呼び出される。

構文

void OnWaitEnd(void);

戻り値

戻り値なし。

注意

このメンバ関数は、パフォーマンス ログの記録のみ実行する。このメンバ関数は、スレッドがウィンドウ内で起動したとき、または次のサンプルのレンダリングが予定されている時間に呼び出される。結果的に、このメンバ関数を使用して、同期を制御する情報を収集できる。

CBaseVideoRenderer::OnWaitStart

CBaseVideoRenderer クラス

待機していた時間と待機していなかった時間を更新する。

構文

void OnWaitStart(void);

戻り値

戻り値なし。

注意

このメンバ関数は、レンダリング イベントの待機を開始したときに呼び出される。このメンバ関数は、パフォーマンス測定のためにのみ使用される。

CBaseVideoRenderer::PreparePerformanceData

CBaseVideoRenderer クラス

現在のフレームの m_trLate および m_trFrame の値を設定する。

構文

void PreparePerformanceData(
int trLate,
int trFrame
    );

パラメータ

trLate
基準タイムの単位で、サンプルが予定時間からどの程度遅延するかを示す値。
trFrame
基準タイムの単位でのフレーム間の時間。

戻り値

戻り値なし。

注意

このメンバ関数は、m_trLate を trLate の値に、m_trFrame を trFrame の値に設定する。

CBaseVideoRenderer::RecordFrameLateness メンバ関数が、CBaseVideoRenderer::OnRenderStart または CBaseVideoRenderer::OnDirectRender のいずれかから呼び出されると、統計情報を更新するために m_trLate および m_trFrame の値を渡す。PreparePerformanceData は、これらのデータ メンバ値を設定するために CBaseVideoRenderer::OnWaitEnd から呼び出される。

CBaseVideoRenderer::RecordFrameLateness

CBaseVideoRenderer クラス

レンダリングがどの程度遅れずに行われたかを記録し、プロパティ ページの統計情報を収集する。

構文

virtual void RecordFrameLateness(
int trLate,
int trFrame
    );

パラメータ

trLate
基準タイムの単位で、サンプルが予定時間からどの程度遅延するかを示す値。
trFrame
基準タイムの単位でのフレーム間の時間。

戻り値

戻り値なし。

CBaseVideoRenderer::ResetStreamingTimes

CBaseVideoRenderer クラス

ストリーミングを制御するすべての時間をリセットする。

構文

virtual HRESULT ResetStreamingTimes(void);

戻り値

HRESULT 値を返す。

注意

この時間は、フレームが最初はドロップされず、最初のフレームが描画されるようにするために設定される。

CBaseVideoRenderer::ScheduleSample

CBaseVideoRenderer クラス

描画およびドロップされたサンプル数を保持する主な処理を実行する基底クラスをオーバーライドする。IQualProp の実装によって使用される。

構文

BOOL ScheduleSample(
IMediaSample *pMediaSample
    );

パラメータ

pMediaSample
メディア サンプルへのポインタ。

戻り値

サンプルがスケジュールされている場合は TRUE を返す。それ以外の場合は FALSE を返す。

CBaseVideoRenderer::SendQuality

CBaseVideoRenderer クラス

サプライヤが品質に関して実行する処理を示す品質 メッセージを送信する。

構文

virtual HRESULT SendQuality(
REFERENCE_TIME trLate,
REFERENCE_TIME trRealStream
    );

パラメータ

trLate
フレームが遅延する時間。
trRealStream
現在のストリーム タイム。

戻り値

HRESULT 値を返す。

注意

このメンバ関数は、品質管理を制御するために、品質 コントロール メッセージをアップストリームに送信する。品質 メッセージの性質 (つまり、サンプル数を増加させるか、減少させるか) は、この派生クラスでの品質管理の実装で決まる。「CBaseVideoRenderer::ShouldDrawSampleNow」を参照すること。

CBaseVideoRenderer::SetSink

CBaseVideoRenderer クラス

品質 メッセージを受け取る IQualityControl オブジェクトを設定する。

構文

HRESULT SetSink(
IQualityControl *piqc
    );

パラメータ

piqc
通知の送信先の IQualityControl オブジェクトへのポインタ。

戻り値

HRESULT 値を返す。

注意

このメンバ関数は、ビデオ レンダラについて IQualityControl::SetSink メソッドを実装する。

CBaseVideoRenderer::ShouldDrawSampleNow

CBaseVideoRenderer クラス

クロックを使用してタイマのアドバイズ リンクを設定せずに、ビデオを描画するかどうかを判断する。

構文

virtual HRESULT ShouldDrawSampleNow(
IMediaSample *pMediaSample,
REFERENCE_TIME *ptrStart,
REFERENCE_TIME *ptrEnd
    );

パラメータ

pMediaSample
このサンプルの IMediaSample インターフェイスへのポインタ。
ptrStart
レンダリングを開始する時間へのポインタ。
ptrEnd
レンダリングを終了する時間へのポインタ。

戻り値

HRESULT 値を返す。待機せずに、直ちに描画する場合は S_OK を返す。時間 ptrStart に描画する場合は S_FALSE を返す。サンプルを描画しない場合はエラーを返し、そのサンプルをスキップして時間を節約する。

注意

このメンバ関数は、CBaseRenderer::ShouldDrawSampleNow をオーバーライドする。

CBaseVideoRenderer::ThrottleWait

CBaseVideoRenderer クラス

各フレームの後に待機時間を挿入する。

構文

void ThrottleWait(void);

戻り値

戻り値なし。

注意

このメンバ関数は、m_trThrottle データ メンバから取得された時間待機する。


CBaseVideoWindow クラス

CBaseVideoWindow クラスは、IVideoWindow インターフェイスの IDispatch コンポーネントを処理し、IVideoWindow のプロパティおよびメソッドは純粋仮想のままにしておく。

メンバ関数

CBaseVideoWindow CBaseVideoWindow オブジェクトを作成する。

実装される INonDelegatingUnknown メソッド

NonDelegatingQueryInterface 指定された参照カウントのインターフェイスを返す。

実装される IDispatch メソッド

GetIDsOfNames | 単一のメンバおよびオプションのパラメータのセットを、対応する整数のディスパッチ識別子にマップする。この識別子は、以降の IDispatch::Invoke メソッドの呼び出しで使用できる。
GetTypeInfo | タイプ情報オブジェクトを取得する。インターフェイスのタイプ情報を取得できる。
GetTypeInfoCount | オブジェクトによって提供されるタイプ情報インターフェイスの数を取得する。
Invoke | オブジェクトによって公開されるプロパティおよびメソッドへのアクセスを提供する。

CBaseVideoWindow::CBaseVideoWindow

CBaseVideoWindow クラス

CBaseVideoWindow オブジェクトを作成する。

構文

CBaseVideoWindow(
  const TCHAR *pName,
  LPUNKNOWN pUnk
  );

パラメータ

pName
デバッグのために CBaseVideoWindow コンストラクタで使用されるオブジェクトの名前へのポインタ。
pUnk
このオブジェクトの所有者へのポインタ。

戻り値

戻り値なし。

注意

スタティック メモリに pName パラメータを割り当てる。この名前は、オブジェクトの作成および削除を行うデバッギング端末上に現れる。

CBaseVideoWindow::GetIDsOfNames

CBaseVideoWindow クラス

単一のメンバ関数およびオプションのパラメータのセットを、対応する整数のディスパッチ識別子にマップする。この識別子は、以降の CBaseVideoWindow::Invoke メンバ関数の呼び出しで使用できる。

構文

HRESULT GetIDsOfNames(

  REFIID riid,

  OLECHAR **rgszNames,

  UINT cNames,

  LCID lcid,

  DISPID *rgdispid

  );

パラメータ

riid
参照識別子。将来的な使用のために予約されている。NULL でなければならない。
rgszNames
渡されたマップする名前の配列へのポインタのアドレス。
cNames
マップされる名前の数。
lcid
名前を解釈するロケール コンテキスト。
rgdispid
呼び出し元割り当て済み配列へのポインタ。各要素には、rgszNames 配列に渡される名前の 1 つに対応する ID が含まれる。最初の要素はメンバの名前を表し、以降の要素は各メンバのパラメータを表す。

戻り値

次のいずれかの値を返す。
DISP_E_UNKNOWN_CLSID | CLSID が認識されなかった。
DISP_E_UNKNOWNNAME | 1 つ以上の名前が不明だった。返された DISPID には、不明な名前に対応する各エントリの DISPID_UNKNOWN が含まれる。
E_OUTOFMEMORY | メモリ不足。
S_OK | 成功。

CBaseVideoWindow::GetTypeInfo

CBaseVideoWindow クラス

タイプ情報オブジェクトを取得する。インターフェイスのタイプ情報を取得できる。

構文

HRESULT GetTypeInfo(

  UINT itinfo,

  LCID lcid,

  ITypeInfo **pptinfo

  );

パラメータ

itinfo
返されるタイプ情報。ゼロを渡して、IDispatch 実装のタイプ情報を取得する。
lcid
タイプ情報のロケール ID。ローカライズされたメンバ名をサポートするクラスの場合、オブジェクトは異なる言語の異なるタイプ情報を返すことができる場合がある。ローカライズされたメンバ名をサポートしないクラスの場合、このパラメータは無視することができる。
pptinfo
要求されたタイプ情報オブジェクトへのポインタのアドレス。

戻り値

pptinfo が無効な場合は、E_POINTER を返す。itinfo がゼロ以外の場合は、TYPE_E_ELEMENTNOTFOUND を返す。成功した場合は、S_OK を返す。それ以外の場合は、タイプを取得するための呼び出しの 1 つから HRESULT を返す。HRESULT はエラーを示し、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。

CBaseVideoWindow::GetTypeInfoCount

CBaseVideoWindow クラス

オブジェクトによって提供されるタイプ情報インターフェイスの数を取得する。

構文

HRESULT GetTypeInfoCount(

  UINT *pctinfo

  );

パラメータ

pctinfo
オブジェクトが提供するタイプ情報インターフェイスの数を受け取る場所へのポインタ。オブジェクトがタイプ情報を提供した場合、この数は 1 である。それ以外の場合は、0 である。

戻り値

pctinfo が無効な場合は、E_POINTER を返す。それ以外の場合は、S_OK を返す。

CBaseVideoWindow::Invoke

CBaseVideoWindow クラス

オブジェクトによって公開されるプロパティおよびメソッドへのアクセスを提供する。

構文

HRESULT Invoke(

  DISPID dispidMember,

  REFIID riid,

  LCID lcid,

  WORD wFlags,

  DISPPARAMS *pdispparams,

  VARIANT *pvarResult,

  EXCEPINFO *pexcepinfo,

  UINT *puArgErr

  );

パラメータ

dispidMember
メンバの識別子。ディスパッチ識別子を取得するには、CBaseVideoWindow::GetIDsOfNames またはオブジェクトのドキュメントを使用する。
riid
将来的な使用のために予約されている。IID_NULL でなければならない。
lcid
引数を解釈するロケール コンテキスト。
wFlags
CBaseVideoWindow::Invoke 呼び出しのコンテキストを記述するフラグ。
pdispparams
引数の配列、名前付き引数の引数ディスパッチ ID の配列、および配列内の要素の数を含む DISPPARAMS 構造体へのポインタ。
pvarResult
結果が格納されるポインタ、または呼び出し元が結果を求めていない場合は NULL。
pexcepinfo
例外情報を含む構造体へのポインタ。
puArgErr
rgvarg 配列内で、エラーがある最初の引数のインデックスへのポインタ。rgvarg 配列は DISPPARAMS 構造体のメンバである。

戻り値

riid が IID_NULL 以外の場合は、DISP_E_UNKNOWNINTERFACE を返す。呼び出しが失敗した場合は、CBaseVideoWindow::GetTypeInfo からエラー コードの 1 つを返す。それ以外の場合は、IDispatch::Invoke への呼び出しから HRESULT を返す。

CBaseVideoWindow::NonDelegatingQueryInterface

CBaseVideoWindow クラス

指定された参照カウントのインターフェイスを返す。

構文

HRESULT NonDelegatingQueryInterface(
  REFIID riid,
  void **ppv
  );

パラメータ

riid
参照識別子。
ppv
インターフェイスへのポインタのアドレス。

戻り値

ppv が無効な場合は、E_POINTER を返す。クエリが成功した場合は NOERROR、失敗した場合は E_NOINTERFACE を返す。

注意

デフォルトでは、IVideoWindow および IUnknown インターフェイスへのポインタを返す。このメソッドをオーバーライドして、派生クラスで実装された追加のインターフェイスを公開する。

このメンバ関数は、INonDelegatingUnknown::NonDelegatingQueryInterface メソッドを実装する。


CBaseWindow クラス

ウィンドウを管理する基底クラス。ビデオ レンダラはこのクラスを使ってビデオ ウィンドウを作成する。

宣言 : Winutil.h

このクラスを使うには、CBaseWindow から継承した派生クラスを作成すること。派生クラスでは :

  • ウィンドウ スタイルを定義する純粋仮想メソッド GetClassWindowStyles を実装する。
  • ウィンドウ メッセージをハンドルする OnReceiveMessage メソッドをオーバーライドする。
  • DoneWithWindow メソッドを呼び出すデストラクタを実装する。

派生クラスのインスタンスを使う前に、PrepareWindow メソッドを呼び出すこと。

Protected メンバ変数
m_hInstance | モジュール インスタンスのハンドル。
m_hwnd | オブジェクトのウィンドウのハンドル。
m_hdc | ウィンドウのデバイス コンテキストのハンドル。
m_Width | クライアント エリアの幅、ピクセル。
m_Height | クライアント エリアの高さ、ピクセル。
m_bActivated | ウィンドウがアクティブになっているかどうかを示すフラグ。
m_pClassName | ウィンドウ クラスの名前を含む静的文字列。
m_ClassStyles | ウィンドウのクラス スタイル。
m_WindowStyles | ウィンドウのウィンドウ スタイル。
m_WindowStylesEx | ウィンドウの拡張ウィンドウ スタイル。
m_ShowStageMessage | ウィンドウをフォアグラウンドにするプライベート メッセージ。
m_ShowStageTop | ウィンドウ スタイルを WS_EX_TOPMOST に設定するプライベート メッセージ。
m_RealizePalette | パレットを適用させるプライベート メッセージ。
m_MemoryDC | メモリ デバイス コンテキストのハンドル。
m_hPalette | ウィンドウのパレットのハンドル。
m_bNoRealize | ウィンドウがそのパレットを適用したかどうかを示すフラグ。
m_bBackground | パレットがバックグラウンド パレットであるべきかどうかを示すフラグ。
m_bRealizing | 新しいパレットが適用されたかどうかを示すフラグ。
m_WindowLock | クリティカル セクション、オブジェクトのアクセスを継続させる。
m_bDoGetDC | デバイス コンテキストを取得したかどうかを示すフラグ。
m_bDoPostToDestroy | ウィンドウがそのデストラクション メッセージに PostMessage を使うか SendMessage を使うかを指定するフラグ。
Protected メソッド
OnPaletteChange | パレット変更メッセージを扱う。仮想。
Public メソッド
CBaseWindow | コンストラクタ メソッド。
DoneWithWindow | ウィンドウを削除する。 仮想。
PrepareWindow | ウィンドウを作成する。 仮想。
InactivateWindow | ウィンドウを非アクティブにする。仮想。
ActivateWindow | 派生クラスの要求にしたがってウィンドウをアクティブにする。仮想。
OnSize | WM_SIZE メッセージを扱う。 仮想。
OnClose | WM_CLOSE メッセージを扱う。 仮想。
GetDefaultRect | クライアント エリアのデフォルト サイズを取得する。仮想。
UninitialiseWindow | ウィンドウのリソースを解放する。仮想。
InitialiseWindow | ウィンドウを初期化する。仮想。
CompleteConnect | ウィンドウにレンダラの入力ピンが接続されたことを通知する。
DoCreateWindow | ウィンドウを作成する。
PerformanceAlignWindow | パフォーマンスを最高にするためにウィンドウを DWORD 境界にそろえる。
DoShowWindow | ウィンドウの表示状態を設定する。
PaintWindow | ウィンドウを再描画させる。
DoSetWindowForeground | ウィンドウをフォアグランドに持ってくる。
SetPalette | ウィンドウにパレットをインストールする。仮想。
SetRealize | ウィンドウがパレットを適用するかどうかを指定する。
DoRealisePalette | ウィンドウの現在のパレットを適用する。仮想。
PossiblyEatMessage | 派生クラスに他のウィンドウへのメッセージの転送を許可する。 仮想。
GetWindowWidth | ウィンドウの現在の幅を取得する。
GetWindowHeight | ウィンドウの現在の高さを取得する。
GetWindowHWND | ウィンドウのハンドルを取得する。
GetMemoryHDC | メモリ デバイス コンテキストのハンドルを取得する。
GetWindowHDC | ウィンドウのデバイス コンテキストのハンドルを取得する。
OnReceiveMessage | ウィンドウ メッセージを扱う。仮想。
Pure Virtual メソッド
GetClassWindowStyles | ウィンドウのクラス スタイルを取得する。

CBaseWindow.m_hInstance

CBaseWindow クラス

モジュール インスタンスのハンドル。

構文

HINSTANCE m_hInstance;

注意

DLL エントリ ポイント関数はグローバル変数をモジュール インスタンスのハンドルで設定する。CBaseWindow クラスはこのハンドルをそのコンストラクタ メソッドにストアする。

CBaseWindow.m_hwnd

CBaseWindow クラス

オブジェクトのウィンドウのハンドル。

構文

HWND m_hwnd;

CBaseWindow.m_hdc

CBaseWindow クラス

ウィンドウのデバイス コンテキストのハンドル。

構文

HDC m_hdc;

CBaseWindow.m_Width

CBaseWindow クラス

クライアント エリアの幅、ピクセル。

構文

LONG m_Width;

CBaseWindow.m_Height

CBaseWindow クラス

クライアント エリアの高さ、ピクセル。

構文

LONG m_Height;

CBaseWindow.m_bActivated

CBaseWindow クラス

ウィンドウがアクティブになってどうかを示すフラグ。TRUE なら、ウィンドウはアクティブになっている。

構文

BOOL m_bActivated;

CBaseWindow.m_pClassName

CBaseWindow クラス

ウィンドウ クラスの名前を含む静的 (static) 文字列。

構文

LPTSTR m_pClassName;

CBaseWindow.m_ClassStyles

CBaseWindow クラス

ウィンドウのクラス スタイル。

構文

DWORD m_ClassStyles;

CBaseWindow.m_WindowStyles

CBaseWindow クラス

ウィンドウのウィンドウ スタイル。

構文

DWORD m_WindowStyles;

CBaseWindow.m_WindowStylesEx

CBaseWindow クラス

ウィンドウの拡張ウィンドウ スタイル。

構文

DWORD m_WindowStylesEx;

CBaseWindow.m_ShowStageMessage

CBaseWindow クラス

ウィンドウをフォアグラウンドにするプライベート メッセージ。

構文

UINT m_ShowStageMessage;

注意

DoSetWindowForeground メソッドはこのメッセージを送信する。

CBaseWindow.m_ShowStageTop

CBaseWindow クラス

ウィンドウ スタイルを WS_EX_TOPMOST に設定するプライベート メッセージ。

構文

UINT m_ShowStageTop;

注意

ビデオ レンダラがフルスクリーン モードに変更したなら、ビデオ レンダラはこのメッセージをウィンドウに送るべきである。

CBaseWindow.m_RealizePalette

CBaseWindow クラス

パレットを適用させるプライベート メッセージ。

構文

UINT m_RealizePalette;

注意

SetPalette メソッドはこのメッセージを送る。

CBaseWindow.m_MemoryDC

CBaseWindow クラス

メモリ デバイス コンテキストのハンドル。

構文

HDC m_MemoryDC;

CBaseWindow.m_hPalette

CBaseWindow クラス

ウィンドウのパレットのハンドル。

構文

HPALETTE m_hPalette;

CBaseWindow.m_bNoRealize

CBaseWindow クラス

ウィンドウがそのパレットを適用したかどうかを示すフラグ。 TRUE なら、ウィンドウはそのパレットを適用していない。デフォルト値は FALSE 。

構文

BYTE m_bNoRealize;

CBaseWindow.m_bBackground

CBaseWindow クラス

パレットがバックグラウンド パレットであるべきかどうかを示すフラグ。TRUE なら、そのパレットはバックグラウンド パレットとして選択される。

構文

m_bBackground;

CBaseWindow.m_bRealizing

CBaseWindow クラス

新しいパレットが適用されたかどうかを示すフラグ。 デバッグ ビルドでは、パレットが変わっている間この値は TRUE、それ以外なら FALSE。この変数はリテール ビルドでは使用されない。

構文

BYTE m_bRealizing;

CBaseWindow.m_WindowLock

CBaseWindow クラス

クリティカル セクション、オブジェクトのアクセスを継続させる。

構文

CCritSec m_WindowLock;

CBaseWindow.m_bDoGetDC

CBaseWindow クラス

デバイス コンテキスト (DC) を取得したかどうかを示すフラグ。TRUE なら、オブジェクトはウィンドウの DC を取得しメモリ DC を作成する。

構文

BOOL m_bDoGetDC;

CBaseWindow.m_bDoPostToDestroy

CBaseWindow Class

ウィンドウがそのデストラクション メッセージに PostMessage を使うか SendMessage を使うかを指定するフラグ。TRUE なら、DoneWithWindow メソッドは PostMessage 関数を使って自身にプライベート デストラクション メッセージを送る。FALSE なら、DoneWithWindow は SendMessage を使ってメッセージを送る。デフォルトではこの値は FALSE である。

構文

BOOL m_bDoPostToDestroy;

CBaseWindow::ActivateWindow

CBaseWindow クラス

派生クラスの要求にしたがってウィンドウをアクティブにする。

構文

virtual HRESULT ActivateWindow(void);

戻り値

以下の表に示される HRESULT 値の 1 つを返す。

S_FALSE | ウィンドウは既にアクティブになっている。
S_OK | 成功。

注意

このメソッドは CBaseWindow::GetDefaultRect を呼び出してウィンドウ サイズを決める。派生クラスは GetDefaultRect をオーバーライドして表示イメージのサイズを返すべきだ。

ウィンドウが既にアクティブなら、ActivateWindow の呼び出しはウィンドウを Z 順の一番上に動かす、しかしウィンドウのリサイズはしない。ウィンドウがペアレントを持っていても同様である。

CBaseWindow::CBaseWindow

CBaseWindow クラス

コンストラクタ メソッド。

構文

CBaseWindow(
    BOOL bDoGetDC = TRUE
    BOOL bPostToDestroy = FALSE
);

パラメータ

bDoGetDC
デバイス コンテキストを取得したかどうかを示すブール値。
bPostToDestroy
m_bDoPostToDestroy メンバ変数を指定するブール値。

注意

オブジェクトを作成した後で、PrepareWindow メソッドを呼び出しウィンドウを作成する。それはこれもまた仮想メソッドである InitialiseWindow を呼び出す。これらのメソッドはコンストラクタから分離されているので、必要なら派生クラスはそれらをオーバーライドすることができる。

bDoGetDC の値が TRUE なら、CBaseWindow オブジェクトはウィンドウのデバイス コンテキスト (DC) のハンドルを取得し、それを m_hdc メンバ変数にストアする。そのオブジェクトはまたm_MemoryDC メンバ変数にストアされている互換メモリ DC をも作成する。これらの処理は InitialiseWindow 内で行われる。

CBaseWindow::CompleteConnect

CBaseWindow クラス

ウィンドウにレンダラの入力ピンが接続されたことを通知する。

構文

HRESULT CompleteConnect(void);

戻り値

S_OK を返す。

注意

このメソッドはウィンドウのアクティブ フラグ (m_bActivated) を FALSE にリセットする。ビデオ レンダラがピン接続を完了したとき、ActivateWindow を呼び出してウィンドウのサイズと位置を設定する可能性がある。ActivateWindow にこれらの属性を再計算させるには、最初に CompleteConnect メソッドを呼び出すこと。

CBaseWindow::DoCreateWindow

CBaseWindow クラス

ウィンドウを作成する。

構文

HRESULT DoCreateWindow(void);

戻り値

成功なら S_OK を返す、失敗ならその原因を示す HRESULT 値を返す。

注意

PrepareWindow メソッドはこのメソッドを呼び出す。

CBaseWindow::DoneWithWindow

CBaseWindow クラス

ウィンドウを削除する。

構文

virtual HRESULT DoneWithWindow(void);

戻り値

S_OK を返す。

注意

このメソッドを派生オブジェクトのデストラクタ メソッドから呼び出すこと。

今メソッドがウィンドウを作成した同じスレッドから呼び出されるなら、メソッドは次の処理を行う :

  • InactivateWindow メソッドを呼び出して、ウィンドウを非アクティブにする 。
  • UninitialiseWindow メソッドを呼び出して、ウィンドウに使用されたりソースを解放する。
  • ウィンドウを削除する。

DoneWithWindow を呼び出すスレッドがそのウィンドウを作成したスレッドではないなら、メソッドはプライベート「destroy」メッセージをそのウィンドウに送る。そのウィンドウはこのメッセージを受け取ると、自分自身に DoneWithWindow を呼び出す。(もし m_bDoPostToDestroy が TRUE なら、そのウィンドウは PostMessage を使う。)

CBaseWindow::DoRealisePalette

CBaseWindow クラス

ウィンドウの現在のパレットを適用する。

構文

virtual HRESULT DoRealisePalette(
    BOOL bForceBackground
);

パラメータ

bForceBackground
パレットをバックグラウンド パレットにするかどうかを指定するブール値。詳細については、Platform SDK の「SelectPalette」を参照すること。

戻り値

以下の表に示される HRESULT 値の 1 つを返す。

S_FALSE | GdiFlush への内部呼び出しがエラーを返した。
S_OK | 成功。

注意

CBaseWindow::OnPaletteChange メソッドはこのメソッドを呼び出す。新しいパレットを設定するには、CBaseWindow::SetPalette メソッドを呼び出すこと。

CBaseWindow::DoSetWindowForeground

CBaseWindow クラス

ウィンドウをフォアグランドに持ってくる。

構文

void DoSetWindowForeground(
    BOOL bFocus
);

パラメータ

bFocus
ウィンドウにフォーカスを与えるかどうかを示すブール値。この値が TRUE なら、ウィンドウはフォーカスを得る。

CBaseWindow::DoShowWindow

CBaseWindow クラス

ウィンドウの表示状態を設定する。

構文

HRESULT DoShowWindow(
    LONG ShowCmd
);

パラメータ

ShowCmd
どのようにウィンドウを表示状態にするかを指定するフラグ。この値は Microsoft® Windows® ShowWindow 関数の nCmdShow パラメータで定義される定数を取り得る。詳細については、Platform SDK を参照すること。

戻り値

S_OK を返す。

CBaseWindow::GetClassWindowStyles

CBaseWindow クラス

ウィンドウのクラス スタイルを取得する。

構文

virtual LPTSTR GetClassWindowStyles(
    DWORD *pClassStyles,
    DWORD *pWindowStyles,
    DWORD *pWindowStylesEx
) PURE;

パラメータ

pClassStyles
クラス スタイルを受け取る変数へのポインタ。
pWindowStyles
ウィンドウ スタイルを受け取る変数へのポインタ。
pWindowStylesEx
拡張ウィンドウ スタイルを受け取る変数へのポインタ。

戻り値

クラス名を含む静的テキスト文字列を返す。

注意

CBaseWindow::PrepareWindow メソッドはこのメソッドを呼び出し、ウィンドウのクラス スタイルとウィンドウ スタイルを取得する。

このメソッドは純粋仮想、派生クラスはそれを実装しなければならない。次のサンプルはその実装例を示す。

LPTSTR CMyWindowClass::GetClassWindowStyles(DWORD *pClassStyles,
                                            DWORD *pWindowStyles,
                                            DWORD *pWindowStylesEx)
{
    *pClassStyles = CS_HREDRAW | CS_VREDRAW;
    *pWindowStyles = WS_OVERLAPPEDWINDOW | WS_CLIPCHILDREN;
    *pWindowStylesEx = WS_EX_WINDOWEDGE;
    return TEXT("MyWindowClass");
}

このオブジェクトは RegisterClass 関数に送られる WNDCLASS 構造体の lpszClassName メンバのクラス スタイルを使用する。このオブジェクトは CreateWindowEx 関数の dwExStyle と dwStyle パラメータのウィンドウ スタイルを使用する。詳細については、Platform SDK を参照すること。

CBaseWindow::GetDefaultRect

CBaseWindow クラス

クライアント エリアのデフォルト サイズを取得する。

構文

virtual RECT GetDefaultRect(void);

戻り値

デフォルト矩形を返す。

注意

ウィンドウがアクティブになるとき、オブジェクトはこのメソッドを呼び出し、ウィンドウのクライアントエリアをどの大きさにするかを確認する。基底クラスでは、このメソッドは定数 DEFHEIGHT と DEFWIDTH で定義される高さと幅の矩形を返す。ビデオ レンダラーでは、通常派生クラスはネイティブなビデオ イメージのサイズを返す。

CBaseWindow::GetMemoryHDC

CBaseWindow クラス

メモリ デバイス コンテキスト (DC) のハンドルを取得する。

構文

virtual HDC GetMemoryHDC(void);

戻り値

メモリ DC のハンドルを返す。

CBaseWindow::GetWindowHDC

CBaseWindow クラス

ウィンドウのデバイス コンテキスト (DC) のハンドルを取得する。

構文

HDC GetWindowHDC(void);

戻り値

DC のハンドルを返す。

CBaseWindow::GetWindowHeight

CBaseWindow クラス

ウィンドウの現在の高さを取得する。

構文

LONG GetWindowHeight(void);

戻り値

ウィンドウの高さを返す、ピクセル値。

CBaseWindow::GetWindowHWND

CBaseWindow クラス

ウィンドウのハンドルを取得する。

構文

HWND GetWindowHWND(void);

戻り値

ウィンドウのハンドルを返す。

CBaseWindow::GetWindowWidth

CBaseWindow クラス

ウィンドウの現在の幅を取得する。

構文

LONG GetWindowWidth(void);

戻り値

ウィンドウの幅を返す、ピクセル値。

CBaseWindow::InactivateWindow

CBaseWindow クラス

ウィンドウを非アクティブにする。 基底クラスでは、このメソッドはウィンドウを隠す。

構文

virtual HRESULT InactivateWindow(void);

戻り値

次の表に示される HRESULT 値の １ つを返す。

S_OK | 成功。
S_FALSE | ウィンドウは既に非アクティブ。

CBaseWindow::InitialiseWindow

CBaseWindow クラス

ウィンドウを初期化する。

構文

virtual InitialiseWindow(
    HWND hwnd
);

パラメータ

hwnd
ウィンドウのハンドル。

戻り値

S_OK を返す。

注意

デフォルトでは、このメソッドはウィンドウのデバイス コンテキスト (DC) を取得し、互換のメモリ DC を作成する。しかし m_bDoGetDC フラグの値が FALSE なら、このメソッドはデバイス コンテキストを取得しない。メモリ DC はウィンドウにビットマップをブリットする前にビットマップを選択する際に有用である。

DoCreateWindow メソッドはこのメソッドを呼び出す。

CBaseWindow::OnClose

CBaseWindow クラス

WM_CLOSE メッセージを扱う。

構文

virtual BOOL OnClose(void);

戻り値

TRUE を返す。

注意

基底クラスでは、このメソッドは単にウィンドウを隠すだけである。通常、派生クラスはこのメソッドをオーバーライドし、EC_USERABORT イベントを同時に送る。このメソッドをオーバーライドしてウィンドウを削除してはならない。その代わり、自身のフィルタが削除されるとき、CBaseWindow::DoneWithWindow メソッドを呼び出すこと。

CBaseWindow::OnPaletteChange

CBaseWindow クラス

パレット変更メッセージを扱う。

構文

virtual LRESULT OnPaletteChange(
    HWND hwnd,
    UINT Message
);

パラメータ

hwnd
ウィンドウのハンドル。
Message
メッセージ ID。

戻り値

メッセージが処理されたら 0 を返し、メッセージが処理されなかったら 1 を返す。

注意

このメソッドは WM_PALETTECHANGED と WM_QUERYNEWPALETTE メッセージを扱う。DoRealisePalette メソッドを呼び出して新しいパレットを適用する。

CBaseWindow::OnReceiveMessage

CBaseWindow クラス

ウィンドウ メッセージを扱う。

構文

virtual LRESULT OnReceiveMessage(
    HWND hwnd,
    INT uMsg,
    WPARAM wParam,
    LPARAM lParam
);

パラメータ

hwnd
ウィンドウのハンドル。
uMsg
メッセージ ID。
wParam
第 1 メッセージ パラメータ。
lParam
第 2 メッセージ パラメータ。

戻り値

メッセージが処理されたら 0 を返し、メッセージが処理されなかったら 1 を返す。

注意

基底クラスは次のメッセージを扱う。

  • WM_CLOSE
  • WM_MOVE
  • WM_PALETTECHANGED
  • WM_QUERYNEWPALETTE
  • WM_SIZE
  • WM_SYSCOLORCHANGE

派生クラスはこのメソッドをオーバーライドし、他のメッセージを扱うことができる。派生クラスは基底クラス メソッドを呼び出して、その派生クラスでは無視されるメッセージを扱うべきだ。

CBaseWindow::OnSize

CBaseWindow クラス

WM_SIZE メッセージを扱う。

構文

virtual BOOL OnSize(
    LONG Width,
    LONG Height
);

パラメータ

Width
クライアント エリアの幅、ピクセル値。
Height
クライアント エリアの高さ、ピクセル値。

戻り値

TRUE を返す。

注意

このメソッドは新しい幅と高さをストアする。受け取った値に対して、CBaseWindow::GetWindowHeight と CBaseWindow::GetWindowWidth メソッドを呼び出すこと。

CBaseWindow::PaintWindow

CBaseWindow クラス

ウィンドウを再描画させる。

構文

void PaintWindow(
    BOOL bErase
);

パラメータ

bErase
バックグラウンドが消去するかどうかを指定する値。この値が TRUE なら、バックグラウンドは消去される。

注意

このメソッドはウィンドウの全クライアントエリアを無効にすることによって WM_PAINT メッセージを生成する。

CBaseWindow::PerformanceAlignWindow

CBaseWindow クラス

パフォーマンスを最高にするためにウィンドウを DWORD 境界にそろえる。

構文

HRESULT PerformanceAlignWindow(void);

戻り値

S_OK を返す。

注意

このメソッドは左と上の端を DWORD 境界にそろえ、パフォーマンスを改善する。ウィンドウがペアレントを持っていても、このメソッドは S_OK を返すが境界へのそろえを実行する。

CBaseWindow::PossiblyEatMessage

CBaseWindow クラス

派生クラスに他のウィンドウへのメッセージの転送を許可する。

構文

virtual BOOL PossiblyEatMessage(
    UINT uMsg,
    WPARAM wParam,
    LPARAM lParam
);

パラメータ

uMsg
メッセージ ID。
wParam
第 1 メッセージ パラメータ。
lParam
第 2 メッセージ パラメータ。

戻り値

メッセージが転送されたら TRUE を返す、失敗したら FALSE を返す。基底クラスは FALSE を返す。

注意

CBaseWindow::OnReceiveMessage メソッドはメッセージを扱う前に PossiblyEatMessage を呼び出す。PossiblyEatMessage が TRUE を返したら、PossiblyEatMessage はそのメッセージを無視する。派生クラスは PossiblyEatMessage をオーバーライドして、所有者ウィンドウへメッセージを転送することができる。たとえば、CBaseWindow から派生した CBaseControlWindow クラスはキーボードとマウスのメッセージを転送する。

CBaseWindow::PrepareWindow

CBaseWindow クラス

ウィンドウを作成する。

構文

virtual HRESULT PrepareWindow(void);

戻り値

HRESULT 値を返す。以下の表に示されるいずれかの値。

S_OK | 成功。
E_FAIL | 失敗。

注意

このメソッドはオブジェクトを作成した後で呼び出すこと。このメソッドはいくつかの初期登録を行ってから DoCreateWindow メソッドを呼び出してウィンドウを作成する。

CBaseWindow::SetPalette

CBaseWindow クラス

ウィンドウにパレットをインストールする。

構文

virtual HRESULT SetPalette(
    HPALETTE hPalette
);

HRESULT SetPalette(void);

パラメータ

hPalette
新しいパレットのハンドル。NULL は不可。

戻り値

以下の表に示される HRESULT 値の 1 つを返す。

S_FALSE | GdiFlush への内部呼び出しがエラーを返した。
S_OK | 成功。

注意

hPalette パラメータは新しいパレットを指定する。メソッドがパラメータなしで呼び出されると、m_hPalette メンバ変数によって与えられるパレットが選択される。呼び出し元は m_hPalette の有効性を確認しなければならない。

m_bNoRealize メンバ変数の値が FALSE (デフォルト)なら、このメソッドはそのパレットを選択しそれを適用する。そうでなければ、パレットを選択するが、それを適用しない。オブジェクトは使用されていた以前のパレットを削除しない。呼び出し元はパレット削除の責任を持つ。

そのウィンドウを所有者とするスレッドでなくても、スレッドはこのメソッドを安全に呼び出すことができる。ウィンドウはそれ自身に OnPaletteChange メソッドへの呼び出しをキックするプライベート メッセージを送る。

CBaseWindow::SetRealize

CBaseWindow クラス

ウィンドウがパレットを適用するかどうかを指定する。

構文

void SetRealize(
    BOOL bRealize
);

パラメータ

bRealize
パレットをリアライズするかどうかを指定するブール値。もし TRUE なら、SetPalette メソッドがパレットをリアライズする。

注意

デフォルトでは、SetPalette メソッドは指定したパレットを適用する。このメソッドを呼び出してデフォルトを変更すること、そうすると複数のパレットが選択されるが適用されない。このメソッドは m_bNoRealize メンバ変数を設定する。

CBaseWindow::UninitialiseWindow

CBaseWindow クラス

ウィンドウのリソースを解放する。

構文

virtual UninitialiseWindow(void);

戻り値

S_OK を返す。

注意

このメソッドは InitialiseWindow メソッドによって取得されたリソースをフリーにする。DoneWithWindow メソッドはこのメソッドを呼び出す。


CBasicAudio クラス

CBaseBasicAudio クラスは、IBasicAudio インターフェイスの IDispatch インターフェイス コンポーネントを処理し、派生フィルタ クラスによって実装される IBasicAudio のプロパティおよびメソッドは純粋仮想のままにしておく。

CBasicAudio::GetIDsOfNames、CBasicAudio::GetTypeInfo、CBasicAudio::GetTypeInfoCount、および CBasicAudio::Invoke メンバ関数は、IDispatch インターフェイスの標準的な実装で、CBaseDispatch クラス (およびタイプ ライブラリ) を使用してコマンドを解析し、IBasicAudio インターフェイスの純粋仮想メソッドに渡す。

Microsoft® DirectShow® では、ボリュームのスケールとして 100 分の 1 デシベルの単位を使用する。この値が 0 の場合、デバイスでサポートされている最大ボリュームを示す。この値が -10,000 の場合は、最小ボリューム (通常、無音) である。バランスは -10,000 ～ 10,000 の範囲で表され、0 が中間である。バランス値が負の場合、右チャンネルがそのデシベル値の分だけ減衰される (つまり音が小さくなる) ことを意味する。同様に、バランス値が正の場合は、右チャンネルの音が左チャンネルよりも大きくなる。つまり、左チャンネルがそのデシベル値の分だけ減衰される。

メンバ関数

CBasicAudio CBasicAudio オブジェクトを作成する。

実装される INonDelegatingUnknown メソッド

NonDelegatingQueryInterface 指定された参照カウントのインターフェイスを取得する。

実装される IDispatch メソッド

GetIDsOfNames | 単一のメンバおよびオプションのパラメータのセットを、対応する整数のディスパッチ識別子にマップする。この識別子は、以降の CBasicAudio::Invoke メンバ関数の呼び出しで使用できる。
GetTypeInfo | タイプ情報オブジェクトを取得する。インターフェイスのタイプ情報を取得できる。
GetTypeInfoCount | オブジェクトによって提供されるタイプ情報インターフェイスの数を取得する。
Invoke | オブジェクトによって公開されるプロパティおよびメソッドへのアクセスを提供する。

CBasicAudio::CBasicAudio

CBasicAudio クラス

CBasicAudio オブジェクトを作成する。

構文

CBasicAudio(
  const TCHAR *pName,
  LPUNKNOWN pUnk
  );

パラメータ

pName
デバッグのために CBasicAudio コンストラクタで使用されるオブジェクトの名前へのポインタ。
pUnk
このオブジェクトの所有者へのポインタ。

戻り値

戻り値なし。

注意

スタティック メモリに pName パラメータを割り当てる。オブジェクトを作成および削除するときに、デバッグ画面にこの名前が表示される。

CBasicAudio::GetIDsOfNames

CBasicAudio クラス

単一のメンバ関数およびオプションのパラメータのセットを、対応する整数のディスパッチ識別子にマップする。この識別子は、以降の CBasicAudio::Invoke メンバ関数の呼び出しで使用できる。

構文

HRESULT GetIDsOfNames(

  REFIID riid,

  OLECHAR **rgszNames,

  UINT cNames,

  LCID lcid,

  DISPID *rgdispid

  );

パラメータ

riid
参照識別子。将来的な使用のために予約されている。NULL でなければならない。
rgszNames
渡されたマップする名前の配列へのポインタのアドレス。
cNames
マップされる名前の数。
lcid
名前を解釈するロケール コンテキスト。
rgdispid
呼び出し元割り当て済み配列へのポインタ。各要素には、rgszNames 配列に渡される名前の 1 つに対応する ID が含まれる。最初の要素はメンバの名前を表し、以降の要素は各メンバのパラメータを表す。

戻り値

次のいずれかの値を返す。
DISP_E_UNKNOWN_CLSID | CLSID が認識されなかった。
DISP_E_UNKNOWNNAME | 1 つ以上の名前が不明だった。返された DISPID には、不明な名前に対応する各エントリの DISPID_UNKNOWN が含まれる。
E_OUTOFMEMORY | メモリ不足。
S_OK | 成功。

CBasicAudio::GetTypeInfo

CBasicAudio クラス

タイプ情報オブジェクトを取得する。インターフェイスのタイプ情報を取得できる。

構文

HRESULT GetTypeInfo(

  UINT itinfo,

  LCID lcid,

  ITypeInfo **pptinfo

  );

パラメータ

itinfo
返されるタイプ情報。ゼロを渡して、IDispatch 実装のタイプ情報を取得する。
lcid
タイプ情報のロケール ID。ローカライズされたメンバ名をサポートするクラスの場合、オブジェクトは異なる言語の異なるタイプ情報を返すことができる場合がある。これは、ローカライズされたメンバ名をサポートするクラスで重要である。ローカライズされたメンバ名をサポートしないクラスの場合、このパラメータは無視することができる。
pptinfo
要求されたタイプ情報オブジェクトへのポインタのアドレス。

戻り値

pptinfo が無効な場合は、E_POINTER を返す。itinfo がゼロ以外の場合は、TYPE_E_ELEMENTNOTFOUND を返す。成功した場合は、S_OK を返す。それ以外の場合は、タイプを取得するための呼び出しの 1 つから HRESULT を返す。HRESULT はエラーを示し、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。

CBasicAudio::GetTypeInfoCount

CBasicAudio クラス

オブジェクトによって提供されるタイプ情報インターフェイスの数を取得する。

構文

HRESULT GetTypeInfoCount(

  UINT *pctinfo

  );

パラメータ

pctinfo
オブジェクトが提供するタイプ情報インターフェイスの数を受け取る場所へのポインタ。オブジェクトがタイプ情報を提供した場合、この数は 1 である。それ以外の場合は、0 である。

戻り値

pctinfo が無効な場合は、E_POINTER を返す。それ以外の場合は、S_OK を返す。

CBasicAudio::Invoke

CBasicAudio クラス

オブジェクトによって公開されるプロパティおよびメソッドへのアクセスを提供する。

構文

HRESULT Invoke(

  DISPID dispidMember,

  REFIID riid,

  LCID lcid,

  WORD wFlags,

  DISPPARAMS *pdispparams,

  VARIANT *pvarResult,

  EXCEPINFO *pexcepinfo,

  UINT *puArgErr

  );

パラメータ

dispidMember
メンバの識別子。ディスパッチ識別子を取得するには、CBasicAudio::GetIDsOfNames またはオブジェクトのドキュメントを使用する。
riid
将来的な使用のために予約されている。IID_NULL でなければならない。
lcid
引数を解釈するロケール コンテキスト。
wFlags
CBasicAudio::Invoke 呼び出しのコンテキストを記述するフラグ。
pdispparams
引数の配列、名前付き引数の引数ディスパッチ ID の配列、および配列内の要素の数を含む DISPPARAMS 構造体へのポインタ。
pvarResult
結果が格納されるポインタ、または呼び出し元が結果を求めていない場合は NULL。
pexcepinfo
例外情報を含む構造体へのポインタ。
puArgErr
rgvarg 配列内で、エラーがある最初の引数のインデックスへのポインタ。rgvarg 配列は DISPPARAMS 構造体のメンバである。

戻り値

riid が IID_NULL 以外の場合は、DISP_E_UNKNOWNINTERFACE を返す。呼び出しが失敗した場合は、CBasicAudio::GetTypeInfo からエラー コードの 1 つを返す。それ以外の場合は、IDispatch::Invoke への呼び出しから HRESULT を返す。

CBasicAudio::NonDelegatingQueryInterface

CBasicAudio クラス

指定された参照カウントのインターフェイスを返す。

構文

HRESULT NonDelegatingQueryInterface(
  REFIID riid,
  void **ppv
  );

パラメータ

riid
参照識別子。
ppv
インターフェイスへのポインタのアドレス。

戻り値

ppv が無効な場合は、E_POINTER を返す。クエリが成功した場合は NOERROR、失敗した場合は E_NOINTERFACE を返す。

注意

デフォルトでは、IBasicAudio および IUnknown インターフェイスへのポインタを返す。このメンバ関数をオーバーライドして、派生クラスで実装された追加のインターフェイスを公開する。

このメンバ関数は、INonDelegatingUnknown::NonDelegatingQueryInterface メソッドを実装する。


CCmdQueue クラス

CCmdQueue クラスは、CDeferredCommand オブジェクトのキュー、およびキューに入れられたコマンドの追加、削除、状態のチェック、および実行するためのメンバ関数を提供する基底クラスである。CCmdQueue オブジェクトは、IQueueCommand メソッドを実装するオブジェクトの一部である。フィルタ グラフ マネージャは、IQueueCommand メソッドを実装し、アプリケーションがフィルタ グラフに対するコマンドをキューに入れることができるようにする。IQueueCommand インターフェイスを実装するフィルタは、このクラスを直接使用する。CDeferredCommand オブジェクトを使用する場合は、このクラスからキューを派生させなければならない。

同期には、「粗い」と「正確」の 2 つのモードがある。粗いモードでは、アプリケーションは指定された時間まで待機した後、コマンドを実行する。正確モードでは、アプリケーションは、その時間に表示されるサンプルに対する処理が開始されるまで待機した後、コマンドを実行する。どちらを実装するかは、フィルタによって決まる。フィルタ グラフ マネージャは、フィルタ グラフ マネージャのキューに入れられるコマンドについて、常に粗いモードを実装する。

粗い同期が必要な場合、実行すべきコマンドがキューに入れられるまで待機した後、コマンドを実行することができる。これは、CCmdQueue::GetDueCommand を呼び出すことによって実行できる。複数の項目を待機している場合は、CCmdQueue::GetDueHandle からイベント ハンドルを取得し、通知済になったら CCmdQueue::GetDueCommand を呼び出す。ストリーム タイムは、CCmdQueue::Run メンバ関数と CCmdQueue::EndRun メンバ関数の呼び出しの間でのみ進む。ハンドルが設定されていても、コマンドの準備ができているという保証はない。イベントが通知済になるたびに、(タイムアウトを 0 にして) GetDueCommand メンバ関数を呼び出す。これによって、コマンドの準備ができていない場合、E_ABORT を返すことができる。

正確な同期が必要な場合は、CCmdQueue::GetCommandDueFor メンバ関数を呼び出して、処理しようとしているサンプルをパラメータとして渡す。これは、次のものを返す。

  • ストリーム タイム時またはその前に実行しなければならないストリームタイム コマンド。
  • ストリーム タイムのプレゼンテーション時またはその前に実行しなければならないプレゼンテーションタイム コマンド。これは、CCmdQueue::Run および CCmdQueue::EndRun メンバ関数の間でのみ行う。この範囲外の場合、ストリーム タイムからプレゼンテーション時間へのマッピングが認識されない。
  • 現在実行しなければならないプレゼンテーションタイム コマンド。

ポーズ モード時に処理される可能性のあるサンプルについて正確な同期が必要な場合は、ストリームタイム コマンドを使用しなければならない。

すべての場合において、コマンドは呼び出されるか、取り消されるまでキューに残る。イベント ハンドルの設定およびリセットは、すべてこのキュー オブジェクトによって管理される。

Protected データ メンバ

m_bRunning | 実行状態のフラグ。実行中の場合は TRUE に設定される。
m_dwAdvise | 基準クロックからのアドバイズ識別子 (未処理のアドバイズがない場合は 0)。
m_evDue | コマンドを実行する時間を設定する。
m_listPresentation | プレゼンテーション時間のキューに入れられたコマンドを格納する。
m_listStream | ストリーム タイムのキューに入れられたコマンドを格納する。
m_Lock | リストへのアクセスを保護する。
m_pClock | 現在の基準クロック。
m_StreamTimeOffset | m_bRunning が TRUE である場合のストリーム タイムのオフセットを格納する。
m_tCurrentAdvise | アドバイズ タイムはこのプレゼンテーション時間用である。

メンバ関数

CCmdQueue | CCmdQueue オブジェクトを作成する。
CheckTime | 指定された時間になったかどうかを判断する。
GetDueHandle | 通知済になるイベント ハンドルを取得する。

オーバーライド可能なメンバ関数

EndRun | 停止またはポーズ モードに切り替える。
GetCommandDueFor | 指定された時間にスケジュールされている遅延コマンドを取得する。
GetDueCommand | 次に実行する予定のコマンドへのポインタを取得する。
Insert | CDeferredCommand オブジェクトをキューに追加する。
New | 実行するコマンドを初期化し、新しい CDeferredCommand オブジェクトを返す。
Remove | CDeferredCommand オブジェクトをキューから削除する。
Run | 実行モードに切り替える。
SetSyncSource | タイミングに使用するクロックを設定する。
SetTimeAdvise | 基準クロックを使用してタイマ イベントを設定する。

CCmdQueue::CCmdQueue

CCmdQueue クラス

CCmdQueue オブジェクトを作成する。

構文

CCmdQueue(void);

戻り値

戻り値なし。

CCmdQueue::CheckTime

CCmdQueue クラス

指定された時間になったかどうかを判断する。

構文

BOOL CheckTime(
CRefTime time,
BOOL bStream
    );

パラメータ

time
チェックする時間。
bStream
time パラメータがストリームタイム値の場合は TRUE、time がプレゼンテーションタイム値の場合は FALSE。

戻り値

まだ指定された時間を過ぎていない場合は、TRUE を返す。

CCmdQueue::EndRun

CCmdQueue クラス

停止またはポーズ モードに切り替える。

構文

virtual HRESULT EndRun(void);

戻り値

実装に応じた HRESULT 値を返す。HRESULT はエラーを示し、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
S_OK または NOERROR | 成功。

注意

このメンバ関数を呼び出した後のストリーム タイムとプレゼンテーション時間との時間のマッピングは不明である。CCmdQueue::Run メンバ関数を呼び出して、このマッピングを実行する。

CCmdQueue::GetCommandDueFor

CCmdQueue クラス

指定された時間にスケジュールされている遅延コマンドを取得する。

構文

virtual HRESULT GetCommandDueFor(
REFERENCE_TIME tStream,
CDeferredCommand **ppCmd
    );

パラメータ

tStream
コマンドがスケジュールされている時間。
ppCmd
tStream パラメータで指定された時間に実行される遅延コマンドへのポインタのアドレス。

戻り値

実行するコマンドがない場合は VFW_E_NOT_FOUND を返す。それ以外の場合は S_OK を返す。

注意

このメンバ関数は、ストリーム タイムを取り、その時間にスケジュールされている遅延コマンドを返す。実際のストリーム タイムのオフセットは、コマンド キューを実行するときに計算される。コマンドは、実行されるか、取り消されるまでキューに残る。このメンバ関数はブロックしない。

CCmdQueue::GetDueCommand

CCmdQueue クラス

次に実行する予定のコマンドへのポインタを取得する。

構文

virtual HRESULT GetDueCommand(
CDeferredCommand **ppCmd,
long msTimeout
    );

パラメータ

ppCmd
遅延コマンドへのポインタのアドレス。
msTimeout
タイムアウトを実行するまでに待機する時間。

戻り値

タイムアウトが発生した場合は、E_ABORT を返す。成功した場合は、S_OK を返す。それ以外の場合は、エラーを返す。IUnknown::AddRef を使用してインクリメントされたオブジェクトを返す。

注意

このメンバ関数は、保留中のコマンドが実行されるまでブロックする。このメンバ関数は、msTimeout パラメータでミリ秒単位で指定された時間ブロックする。ストリーム タイム コマンドは、CCmdQueue::Run メンバ関数と CCmdQueue::EndRun メンバ関数の呼び出しの間でのみ実行される。このコマンドは、実行されるか、取り消されるまでキューに残る。

CCmdQueue::GetDueHandle

CCmdQueue クラス

通知済のイベント ハンドルを取得する。

構文

HANDLE GetDueHandle(void);

戻り値

イベント ハンドルを返す。

注意

実行する予定の遅延コマンドがある場合はイベント ハンドルを返す (CCmdQueue::GetDueCommand がブロックする場合)。

CCmdQueue::Insert

CCmdQueue クラス

CDeferredCommand オブジェクトをキューに追加する。

構文

virtual HRESULT Insert(
CDeferredCommand *pCmd
    );

パラメータ

pCmd
キューに追加する CDeferredCommand オブジェクトへのポインタ。

戻り値

デフォルトの実装では S_OK を返す。

CCmdQueue::New

CCmdQueue クラス

実行するコマンドを初期化し、新しい CDeferredCommand オブジェクトを返す。

構文

virtual HRESULT New(
CDeferredCommand **ppCmd,
LPUNKNOWN pUnk,
REFTIME time,
GUID *iid,
long dispidMethod,
short wFlags,
long cArgs,
VARIANT *pDispParams,
VARIANT *pvarResult,
short *puArgErr,
BOOL bStream
    );

パラメータ

ppCmd
CDeferredCommand オブジェクトへのポインタのアドレス。これによって、アプリケーションはコマンドを取り消したり、コマンドの新しいプレゼンテーション時間を設定したり、予測情報を取得することができる。
pUnk
コマンドを実行するオブジェクトへのポインタ。
time
キューに入れられたコマンドを実行する時間。
iid
呼び出すインターフェイスのグローバル ユニーク識別子 (GUID) へのポインタ。
dispidMethod
呼び出されるインターフェイス上のメソッド。
wFlags
呼び出しのコンテキストを記述するフラグ。このパラメータは、OLE IDispatch::Invoke メソッドと同じフラグをサポートする。
cArgs
渡される引数の数。
pDispParams
ディスパッチ パラメータに関連付けられたバリアント型のリストへのポインタ。
pvarResult
結果が返されるリストへのポインタ。
puArgErr
最後のエラーが発生した pDispParams パラメータ リスト内のインデックスへのポインタ。
bStream
time パラメータがストリームタイム値 (TRUE) であるか、プレゼンテーションタイム値 (FALSE) であるかを示す値。

戻り値

成功した場合は、S_OK を返す。ppCmd が新しい CDeferredCommand オブジェクトの作成時に NULL を返す場合は、E_OUTOFMEMORY を返す。それ以外の場合は、新しい CDeferredCommand オブジェクトを作成使用としたときのエラーを示す HRESULT を返す。エラーが発生した場合は、オブジェクトはキューに入れられない。

注意

新しい CDeferredCommand オブジェクトはパラメータを使用して初期化され、作成中にキューに追加される。このメソッドは、OLE IDispatch::Invoke メソッドに似ている。

wFlags パラメータは、次のような値になる。
DISPATCH_METHOD | メンバはメソッドとして実行されている。プロパティが同じ名前である場合は、これと DISPATCH_PROPERTYGET フラグの両方を設定できる。
DISPATCH_PROPERTYGET | メンバはプロパティまたはデータ メンバとして取得されている。
DISPATCH_PROPERTYPUT | メンバはプロパティまたはデータ メンバとして変更されている。
DISPATCH_PROPERTYPUTREF | メンバは、値の割り当てではなく、参照の割り当てによって変更されている。この値は、プロパティがオブジェクトへの参照を受け入れる場合にのみ有効である。

CCmdQueue::Remove

CCmdQueue クラス

CDeferredCommand オブジェクトをキューから削除する。

構文

virtual HRESULT Remove(
CDeferredCommand *pCmd
    );

パラメータ

pCmd
キューから削除する CDeferredCommand オブジェクトへのポインタ。

戻り値

キュー内にオブジェクトが見つからなかった場合は VFW_E_NOT_FOUND を返す。それ以外の場合は、S_OK を返す。

CCmdQueue::Run

CCmdQueue クラス

ストリーム タイムによって遅延されているコマンドを実行できるように実行モードに切り替える。

構文

virtual HRESULT Run(
REFERENCE_TIME tStreamTimeOffset
    );

パラメータ

tStreamTimeOffset
オフセット タイム。

戻り値

デフォルトの実装では S_OK を返す。

注意

実行モードでは、ストリーム タイムとプレゼンテーション時間のマッピングが認識される。

CCmdQueue::SetSyncSource

CCmdQueue クラス

タイミングに使用するクロックを設定する。

構文

virtual HRESULT SetSyncSource(
IReferenceClock *pIrc
    );

パラメータ

pIrc
IReferenceClock インターフェイスへのポインタ。

戻り値

デフォルトの実装では S_OK を返す。

CCmdQueue::SetTimeAdvise

CCmdQueue クラス

基準クロックを使用してタイマ イベントを設定する。

構文

void SetTimeAdvise(void);

戻り値

戻り値なし。

注意

このメンバ関数は、IReferenceClock::AdviseTime メソッドを呼び出して、キュー内で必要な最も早い時間の通知を設定する。遅延されるプレゼンテーション時間コマンドは常にチェックされる。フィルタ グラフが実行モードである場合、ストリーム タイムを使用する遅延コマンドもチェックされる。


CCritSec クラス

スレッドのロックを提供する。

宣言 : Wxutil.h

このクラスはクリティカル セクションのラッパーである。Lock および Unlock メソッドを呼び出すことによって、スレッドをロックおよびロック解除することができる。ただし、このクラスと CAutoLock クラスを組み合わせて使用する方が安全である。CAutoLock クラスがスコープの範囲外である場合は、自動的に CCritSec オブジェクトのロックを解除する。さらに、効率的なインライン コードにコンパイルする。

Puvlic メンバ変数
m_currentOwner | 所有するスレッドのスレッド識別子。
m_lockCount | このオブジェクトについて未処理のロックの数。
m_fTrace | このロックをトレースするかどうかを指定するブール型の値。
Public メソッド
CCritSec | コンストラクタ メソッド。
~CCritSec | デストラクタ メソッド。
Lock | クリティカル セクション オブジェクトをロックする。
Unlock | クリティカル セクション オブジェクトのロックを解除する。

CCritSec.m_currentOwner

CCritSec クラス

所有するスレッドのスレッド識別子。

構文

DWORD m_currentOwner;

注意

このメンバ変数は、基底クラスのデバッグ バージョンでのみ定義される。CCritSec debug 関数はこのメンバを使用する。

CCritSec.m_lockCount

CCritSec クラス

このオブジェクトについて未処理のロックの数。

構文

DWORD m_lockCount;

注意

このメンバ変数は、基底クラスのデバッグ バージョンでのみ定義される。CCritSec debug 関数はこのメンバを使用する。

CCritSec.m_fTrace

CCritSec クラス

このロックをトレースするかどうかを指定するブール型の値。

構文

BOOL m_fTrace;

注意

このメンバ変数は、基底クラスのデバッグ バージョンでのみ定義される。この変数が TRUE の場合、ロック状態のトレースがデバッグ ログに書き込まれる。クリティカル セクションのデバッグ ログがアクティブでなければならない。詳細については、「DbgLockTrace」を参照すること。

CCritSec::CCritSec

CCritSec クラス

コンストラクタ メソッド。

構文

CCritSec(void);

注意

このメソッドは、Microsoft® Win32® InitializeCriticalSection 関数を呼び出して、クリティカル セクションを初期化する。

CCritSec::~CCritSec

CCritSec クラス

デストラクタ メソッド。

構文

~CCritSec(void);

注意

このメソッドは、Microsoft® Win32® DeleteCriticalSection 関数を呼び出して、クリティカル セクションを削除する。

CCritSec::Lock

CCritSec クラス

クリティカル セクション オブジェクトをロックする。

構文

void Lock(void);

戻り値

戻り値なし。

注意

このメソッドは、Microsoft® Win32® EnterCriticalSection メソッドを呼び出す。

クリティカル セクションのロックを解除するには、CCritSec::Unlock メンバ関数を呼び出す。同じスレッドについて、Lock メソッドを複数呼び出すことができる。同じ回数だけ Unlock 呼び出す必要がある。

オブジェクトが既に別のスレッドによってロックされている場合、CCritSec::Lock メソッドは、そのオブジェクトが解放されるまで、または可能性のあるデッドロック例外が発生するまでブロックする。

CCritSec::Unlock

CCritSec クラス

クリティカル セクション オブジェクトのロックを解除する。

構文

void Unlock(void);

戻り値

戻り値なし。

注意

このメソッドは、Microsoft® Win32® LeaveCriticalSection メソッドを呼び出す。

Lock メソッドの各呼び出しについて、このメソッドを 1 回呼び出す。


CCrossbar クラス

CCrossbar は、アプリケーションで使用して、アナログ TV チューナー カードなどのデバイスで アナログ ビデオ クロスバー フィルタを制御できるヘルパー クラスである。通常、このようなカードは複数の入力 (コンポジット ビデオ、S ビデオ、TV オーディオ用など) を持つ。クロスバー フィルタは、特定の入力に送られた信号がハードウェアでルーティングされるための、可能なすべての方法を表す。デバイスには、連続して接続された複数のクロスバーを実装するものもあれば、クロスバーを持たないものもある。

CCrossbar は、任意の複雑なクロスバー フィルタのグラフをサポートしている。このようなフィルタをレイヤー化することができ、無効な入力および出力を含めることができる。CCrossbar は可能なすべての入力を列挙し、記録および表示するための単一の入力を選択できる。

開始入力ピンを指定すると (通常、キャプチャ フィルタへのアナログ ビデオ入力)、このクラスはすべての可変入力を検索して再帰的にアップストリームをトレースする。入力がビデオ ピンであり、接続されていないか、IAMCrossbar インターフェイスをサポートしていないフィルタに接続されている場合、可変であると見なされる。 このクラスの使用については、DirectX® 8 SDK の AMCap サンプルアプリケーションでデモが示されている。

メンバ関数

CCrossbar | CCrossbar オブジェクトを作成する。
GetInputCount | 選択できる一意のビデオ入力の数を取得する。
GetInputIndex | 現在選択されている入力を取得する。
GetInputName | 人が読んで理解できる各入力のタイプを示す文字列を取得する。
GetInputType | コンピュータで認識される各入力の物理的なタイプを取得する。
SetInputIndex | 特定の入力を選択する。

CCrossbar::CCrossbar

CCrossbar クラス

CCrossbar オブジェクトを作成する。

構文

CCrossbar(
IPin *pPin);

パラメータ

pPin
開始入力ピンへのポインタ。

戻り値

戻り値なし。

CCrossbar::GetInputCount

CCrossbar クラス

選択できる一意のビデオ入力の数を取得する。

構文

HRESULT GetInputCount(
LONG *pCount);

パラメータ

pCount
ビデオ入力の数へのポインタ。

戻り値

S_OK を返す。

CCrossbar::GetInputIndex

CCrossbar クラス

現在選択されている入力を取得する。

構文

HRESULT GetInputIndex(
LONG *Index);

パラメータ

Index
現在のルーティング インデックスへのポインタ。

戻り値

S_OK を返す。

CCrossbar::GetInputName

CCrossbar クラス

人が読んで理解できる各入力のタイプを示す文字列を取得する。

構文

HRESULT GetInputName(
LONG Index,
TCHAR *pName,
LONG NameSize);

パラメータ

Index
現在のルーティング インデックス。
pName
テキスト バージョンの現在のルーティング入力を受信するバッファへのポインタ。メソッドを呼び出す前は、NULL にすることはできない。NULL にすると、処理は失敗する。たとえば、現在のルーティング入力のタイプが PhysConn_Video_Tuner である場合、この関数はこのパラメータに "Video Tuner" という文字列を返す。詳細については、「注意」を参照すること。
NameSize
テキスト バージョンの現在のルーティング入力を受信するバッファのサイズ。pName で示されるバッファは、最後の NULL 文字を含めることができるサイズでなければならない。

戻り値

バッファが十分な大きさで、文字列名をコピーできる場合、このメソッドは S_OK を返す。それ以外の場合は、E_FAIL を返す。

注意

次の表に、現在のルーティング タイプに応じて、pName パラメータが返す値を示す。

物理的なタイプ | pName
PhysConn_Video_Tuner | Video Tuner
PhysConn_Video_Composite | Video Composite
PhysConn_Video_SVideo | Video SVideo
PhysConn_Video_RGB | Video RGB
PhysConn_Video_YRYBY | Video YRYBY
PhysConn_Video_SerialDigital | Video SerialDigital
PhysConn_Video_ParallelDigital | Video ParallelDigital
PhysConn_Video_SCSI | Video SCSI
PhysConn_Video_AUX | Video AUX
PhysConn_Video_1394 | Video 1394
PhysConn_Video_USB | Video USB
PhysConn_Video_VideoDecoder | Video Decoder
PhysConn_Video_VideoEncoder | Video Encoder
PhysConn_Audio_Tuner | Audio Tuner
PhysConn_Audio_Line | Audio Line
PhysConn_Audio_Mic | Audio Mic
PhysConn_Audio_AESDigital | Audio AESDigital
PhysConn_Audio_SPDIFDigital | Audio SPDIFDigital
PhysConn_Audio_SCSI | Audio SCSI
PhysConn_Audio_AUX | Audio AUX
PhysConn_Audio_1394 | Audio 1394
PhysConn_Audio_USB | Audio USB
PhysConn_Audio_AudioDecoder | Audio Decoder

CCrossbar::GetInputType

CCrossbar クラス

コンピュータで認識される各入力の物理的なタイプを取得する。

構文

HRESULT GetInputType(
LONG Index,
LONG *PhysicalType);

パラメータ

Index
現在のルーティング インデックス。
PhysicalType
ピン (ビデオ) の物理的な名前へのポインタ。 PhysicalConnectorType 列挙データ型のメンバを返す。

戻り値

Index パラメータが範囲外の場合は E_FAIL を返す。それ以外の場合は S_OK を返す。

CCrossbar::SetInputIndex

CCrossbar クラス

特定の入力を選択する。

構文

HRESULT SetInputIndex(
LONG Index);

パラメータ

Index
設定されるルーティング インデックス。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、E_FAIL を返す。


CDeferredCommand クラス

遅延コマンドは、IQueueCommand インターフェイスでのメソッドの呼び出しによってキューに入れられ、フィルタ グラフ マネージャおよび一部のフィルタによって公開される。このようなメソッドの呼び出しが成功すると、キューに入れられたコマンドを表す IDeferredCommand インターフェイスが返される。

CDeferredCommand オブジェクトは単一の遅延コマンドを表し、IDeferredCommand インターフェイスおよびタイム チェックと実際の実行を可能にするその他のメソッドを公開する。CDeferredCommand オブジェクトには、入れられるキューとなる CCmdQueue オブジェクトへの参照が含まれる。

参照カウントによって、CDeferredCommand クラスの有効期間が制御される。CDeferredCommand::Invoke メンバ関数を呼び出すと、呼び出し元のアプリケーションは参照がカウントされたインターフェイス ポインタを取得し、CCmdQueue オブジェクトも遅延コマンドの参照カウントを保持する。IDeferredCommand::Cancel メンバ関数を呼び出すと、遅延コマンドはコマンド キューから削除され、参照カウントは 1 減らされる。コマンドをキューから削除すると、キューに戻すことはできない。

プロテクト データ メンバ

m_bStream | メソッドを呼び出すために渡されるストリーム タイムまたはプレゼンテーション時間のフラグ。
m_Dispatch | ITypeInfo インターフェイスにアクセスする。
m_dispidMethod | 実行するインターフェイス上のメソッド。
m_DispParams | DISPPARAMS パラメータ リストを含む CDispParams オブジェクト。
m_hrResult | 返される HRESULT 値を格納する。
m_iid | インターフェイスのグローバル ユニーク識別子 (GUID)。
m_pQueue | IQueueCommand インターフェイスを公開する CCmdQueue オブジェクトへのポインタ。
m_pUnk | コマンドが実行されるインターフェイスへの IUnknown ポインタ。
m_pvarResult | 呼び出されたメソッドからの結果の情報。
m_time | コマンドが実行される時間。
m_wFlags | 呼び出しのコンテキストを指定するフラグ。

メンバ関数

CDeferredCommand | CDeferredCommand オブジェクトを作成する。
GetFlags | この遅延コマンドに関連付けられたコンテキスト フラグを取得する。
GetIID | メソッドが実行されるインターフェイスのインターフェイス識別子 (IID) を取得する。
GetMethod | 実行されるメソッドのディスパッチ識別子を取得する。
GetParams | メソッドに対する DISPPARAMS 引数リストを取得する。
GetResult | 存在する場合は、結果の引数リストを取得する。
GetTime | メソッドが実行される時間を取得する。
Invoke | オブジェクトによって公開されるメソッドおよびプロパティへのアクセスを提供する。
IsStreamTime | コマンドをストリーム タイムまたはプレゼンテーション時間のどちらで実行するかを指定する。

実装される IDeferredCommand メソッド

Cancel | 以前にキューに入れられた CDeferredCommand::Invoke 要求を取り消す。
Confidence | 現在は実装されていない。
Postpone | 以前にキューに入れられたコマンドの新しいプレゼンテーション時間を指定する。
GetHResult | 呼び出したメソッドの HRESULT 値を取得する。

実装される INonDelegatingUnknown メソッド

NonDelegatingQueryInterface 指定された参照カウントのインターフェイスを取得する。

CDeferredCommand::Cancel

CDeferredCommand クラス

以前にキューに入れられた CDeferredCommand::Invoke 要求を取り消す。

構文

HRESULT Cancel(void);

戻り値

m_pQueue が NULL の場合は、VFW_E_ALREADY_CANCELLED を返す。呼び出しがエラーを生成する場合は、CCmdQueue::Remove からの HRESULT を返す。成功した場合は、S_OK を返す。

注意

このメンバ関数は、IDeferredCommand::Cancel メソッドを実装する。

CDeferredCommand::CDeferredCommand

CDeferredCommand クラス

CDeferredCommand オブジェクトを作成する。

構文

CDeferredCommand(
CCmdQueue *pQ,
LPUNKNOWN pUnk,
HRESULT *phr,
LPUNKNOWN pUnkExecutor,
REFTIME time,
GUID *iid,
long dispidMethod,
short wFlags,
long cArgs,
VARIANT *pDispParams,
VARIANT *pvarResult,
short *puArgErr,
BOOL bStream
    );

パラメータ

pQ
IQueueCommand インターフェイスを公開するオブジェクトへのポインタ。
pUnk
集成のための外部 IUnknown インターフェイスへのポインタ。
phr
返された HRESULT 値へのポインタ。
pUnkExecutor
このコマンドを実行するオブジェクトへのポインタ。
time
コマンドが実行される時間。
iid
メソッドを含むインターフェイスのグローバル ユニーク識別子 (GUID) へのポインタ。
dispidMethod
呼び出すインターフェイス上のメソッド。
wFlags
呼び出しのコンテキスト。
cArgs
渡される引数の数。
pDispParams
引数バリアント型のリストへのポインタ。
pvarResult
返されたバリアント型リストへのポインタ。
puArgErr
エラーが発生した pDispParams パラメータ リスト内の最後の引数へのポインタ。
bStream
遅延コマンドの時間がストリームタイム (TRUE) であるか、プレゼンテーションタイム (FALSE) であるかを示す値。

戻り値

戻り値なし。

CDeferredCommand::Confidence

CDeferredCommand クラス

このメソッドは現在実装されていない。E_NOTIMPL を返す。

構文

HRESULT Confidence(
LONG *pConfidence
    );

パラメータ

pConfidence
コンフィデンス レベルへのポインタ。

戻り値

E_NOTIMPL を返す。

注意

このメソッドの実装については、「IDeferredCommand::Confidence」を参照すること。

CDeferredCommand::GetFlags

CDeferredCommand クラス

この遅延コマンドに関連付けられたコンテキスト フラグを取得する。

構文

short GetFlags(void);

戻り値

取得される値は次のいずれかの値になる。
DISPATCH_METHOD | メンバをメソッドとして実行する。プロパティが同じ名前である場合は、これと DISPATCH_PROPERTYGET フラグの両方を設定できる。
DISPATCH_PROPERTYGET | メンバはプロパティまたはデータ メンバとして取得されている。
DISPATCH_PROPERTYPUT | メンバはプロパティまたはデータ メンバとして変更されている。
DISPATCH_PROPERTYPUTREF | メンバは、値の割り当てではなく、参照の割り当てによって変更されている。このフラグは、プロパティがオブジェクトへの参照を受け入れる場合にのみ有効である。

CDeferredCommand::GetHResult

CDeferredCommand クラス

呼び出したコマンドからの HRESULT 値を取得する。

構文

HRESULT GetHResult(
HRESULT *phrResult
    );

パラメータ

phrResult
HRESULT 値へのポインタ。

戻り値

m_pQueue が NULL の場合は、E_ABORT を返す。それ以外の場合は、S_OK を返す。

注意

このメンバ関数は、IDeferredCommand::GetHResult メソッドを実装する。

CDeferredCommand::GetIID

CDeferredCommand クラス

メソッドが実行されるインターフェイスのインターフェイス識別子 (IID) を取得する。

構文

REFIID GetIID(void);

戻り値

メソッドが実行されるインターフェイスの IID を取得する。

CDeferredCommand::GetMethod

CDeferredCommand クラス

実行されるメソッドのディスパッチ識別子 (DISPID) を取得する。

構文

long GetMethod(void);

戻り値

実行するメソッドの DISPID を返す。

CDeferredCommand::GetParams

CDeferredCommand クラス

メソッドに対する DISPPARAMS 引数リストを取得する。

構文

DISPPARAMS* GetParams(void);

戻り値

DISPPARAMS 引数リストを返す。

CDeferredCommand::GetResult

CDeferredCommand クラス

存在する場合は、結果の引数リストを取得する。

構文

VARIANT* GetResult(void);

戻り値

存在する場合は、メソッドの引数リストを含むバリアントを返す。

CDeferredCommand::GetTime

CDeferredCommand クラス

メソッドが実行される時間を取得する。

構文

CRefTime GetTime(void);

戻り値

基準タイムを含む CRefTime オブジェクトを返す。

CDeferredCommand::Invoke

CDeferredCommand クラス

オブジェクトによって公開されるメソッドおよびプロパティへのアクセスを提供する。

構文

HRESULT Invoke(void);

戻り値

m_pQueue が NULL の場合は、VFW_E_ALREADY_CANCELLED を返す。それ以外の場合は、IDispatch::GetTypeInfo または IUnknown::QueryInterface の呼び出しの結果の HRESULT を返す。

CDeferredCommand::IsStreamTime

CDeferredCommand クラス

コマンドをストリーム タイムまたはプレゼンテーション時間のどちらで実行するかを指定する。

構文

BOOL IsStreamTime(void);

戻り値

ストリーム タイムに設定されている場合は TRUE を返す。それ以外の場合は FALSE を返す。

CDeferredCommand::NonDelegatingQueryInterface

CDeferredCommand クラス

指定された参照カウントのインターフェイスを取得する。

構文

HRESULT NonDelegatingQueryInterface(
REFIID riid,
void **ppv
    );

パラメータ

riid
参照識別子。
ppv
インターフェイスへのポインタのアドレス。

戻り値

ppv が無効な場合は、E_POINTER を返す。クエリが成功した場合は NOERROR、失敗した場合は E_NOINTERFACE を返す。

注意

デフォルトでは、IDeferredCommand および IUnknown インターフェイスへのポインタを返す。このメソッドをオーバーライドして、派生クラスで実装された追加のインターフェイスを公開する。

このメンバ関数は、INonDelegatingUnknown::NonDelegatingQueryInterface メソッドを実装する。

CDeferredCommand::Postpone

CDeferredCommand クラス

以前にキューに入れられたコマンドの新しいプレゼンテーション時間を指定する。

構文

HRESULT Postpone(
REFTIME newtime
    );

パラメータ

newtime
新しいプレゼンテーション時間。

戻り値

newtime が既に過ぎている場合は、VFW_E_TIME_ALREADY_PASSED を返す。それ以外の場合は、CCmdQueue::Remove (リストから削除する場合) または CCmdQueue::Insert (変更した時間に再び挿入する場合) の呼び出しの結果の HRESULT を返す。

注意

このメンバ関数は、IDeferredCommand::Postpone メソッドを実装する。


CDispParams クラス

CDispParams クラスは、C++ の基底クラスとして Automation で使用される DISPPARAMS 構造体を実装する。IDispatch::Invoke メソッドは、OLE DISPPARAMS 構造体を使用して、メソッドまたはプロパティに渡される引数を格納する。

DISPPARAMS 構造体は次のように定義される。

typedef struct FARSTRUCT tagDISPPARAMS{
VARIANTARG FAR* rgvarg;               // 引数の配列
DISPID FAR* rgdispidNamedArgs;     // 名前を付けた引数のディスパッチ ID
unsigned int cArgs;                // 引数の数
unsigned int cNamedArgs;           // 名前を付けた引数の数
} DISPPARAMS;

メンバ関数

CDispParams CDispParams オブジェクトを作成する。

CDispParams::CDispParams

CDispParams クラス

CDispParams オブジェクトを作成する。

構文

CDispParams(

  UINT nArgs,

  VARIANT *pArgs

  );

パラメータ

nArgs
メソッドまたはプロパティに渡される引数の数。
pArgs
引数のリストへのポインタ。リスト内で、各引数はバリアント型で格納される。

戻り値

戻り値なし。


CDrawImage クラス

CDrawImage クラスは、所有する CBaseWindow オブジェクトのワーカー クラスである。このクラスは、そのクラスからの実際の描画操作を処理する。このクラスを使用するには、アロケータが合意したときに CDrawImage::NotifyAllocator を呼び出し、合意されたときに CMediaType オブジェクトへのポインタ (ポインタはコピーを作成するのではなく、このクラスで管理されるので、スタック ベースであってはならない) を指定して CDrawImage::NotifyMediaType を呼び出す必要がある。

パレットが変更された場合は、CDrawImage::IncrementPaletteVersion を呼び出し、レンダリングの前に CDrawImage::SetDrawContext を呼び出して、このクラスが所有する CBaseWindow オブジェクトからデバイス コンテキスト ハンドル (HDC) を取得できるようにする。

Protected データ メンバ

m_bStretch | イメージを伸縮するフラグ。
m_bUsingImageAllocator | サンプルが DIBSECTION 構造体を共有するかどうかを判断するフラグ。
m_EndSample | 現在のサンプルの終了タイム。
m_hdc | メイン ウィンドウのデバイス コンテキスト (DC)。
m_MemoryDC | オフスクリーン描画 DC。
m_pBaseWindow | 所有するビデオ ウィンドウ オブジェクト。
m_PaletteVersion | 現在のパレットのバージョン トークン。
m_perfidRenderNow | 描画から返った瞬間 (パフォーマンス ログ用)。
m_perfidRenderNow | イメージのレンダリングにかかった時間 (パフォーマンス ログ用)。
m_pMediaType | 現在のメディア タイプ フォーマットへのポインタ。
m_SourceRect | 転送元イメージ矩形。
m_StartSample | 現在のサンプルの開始タイム。
m_TargetRect | 転送先矩形。

メンバ関数

CDrawImage | CDrawImage オブジェクトを作成する。
DisplaySampleTimes | イメージの先頭のサンプルのタイム スタンプを表示する。
DrawImage | ウィンドウへのイメージの描画を処理する。
FastRender | BitBlt および StretchBlt を使用してイメージを描画する。
GetPaletteVersion | 現在インストールされているパレットのバージョンを取得する。
GetSourceRect | 現在の転送元矩形を取得する。
GetTargetRect | 現在の転送先矩形を取得する。
IncrementPaletteVersion | 現在のパレットのバージョンをインクリメントする。
NotifyAllocator | 使用するアロケータを描画オブジェクトに通知する。
NotifyEndDraw | イメージ レンダリングの終了を指定する。
NotifyMediaType | 接続時に確立されたメディア タイプを渡す。
NotifyStartDraw | イメージ レンダリングの開始を指定する。
ResetPaletteVersion | 現在のパレットのバージョンをリセットする。
ScaleSourceRect | 指定された転送元矩形のスケーリングされたバージョンを取得する。
SetDrawContext | 描画に使用するウィンドウおよびオフスクリーン デバイス コンテキストを設定する。
SetSourceRect | ビデオの転送元矩形を設定する。
SetStretchMode | 伸縮する必要があるかどうかを判断する。
SetTargetRect | ウィンドウの転送先矩形を設定する。
SlowRender | Microsoft® Win32® SetDIBitsToDevice および StretchDIBits 関数を使用してイメージを描画する。
UpdateColourTable | DIBSECTION 構造体に保持されているパレットを更新する。
UsingImageAllocator | 描画されるサンプルのタイプを取得する。

CDrawImage::CDrawImage

CDrawImage クラス

CDrawImage オブジェクトを作成する。

構文

CDrawImage(
CBaseWindow *pBaseWindow
);

パラメータ

pBaseWindow
描画が行われるウィンドウへのポインタ。

戻り値

戻り値なし。

注意

このクラスは、GDI によるイメージの描画を処理する。このクラスは、CImageAllocator および CBaseWindow クラスと密接に連携して機能する。描画コードは、それが渡されるバッファが Microsoft® Win32® CreateDIBSection 関数によって作成されている場合、高速な描画を実装できるので、このクラスは CImageAllocator クラスを認識している必要がある。イメージ アロケータはこのタイプのサンプルを作成する。CDrawImage::NotifyAllocator メンバ関数を使用して、CImageAllocator オブジェクト (または派生クラス) によってバッファが割り当てられているかどうかが、このクラスに通知される。

描画に使用するバッファが互換性のあるアロケータによって割り当てられていない場合、バッファは Win32 SetDIBitsToDevice ファミリの API を使用して描画する。CBaseWindow クラスは、イメージが描画されるウィンドウ ハンドルを取得する。描画コードが使用するデバイス コンテキストは、CDrawImage::SetDrawContext メンバ関数を使用して渡される。

CImageAllocator、CImageSample、および CDrawImage クラスは、すべて密接に関連している。イメージ アロケータが使用するバッファは、Win32 CreateDIBSection 関数を使用して作成される。次に、アロケータは CImageSample クラスに基づいて独自のサンプルを作成する。イメージ サンプルは、バッファ ポインタとその長さを使って初期化される。サンプルは、CreateDIBSection 関数から取得されたさまざまな情報を保持する構造体 (DIBDATA 構造体) にも渡される。

これらのサンプルを描画オブジェクトに渡すことができる。描画オブジェクトは、サンプルのプライベート フォーマット、およびサンプルから DIBDATA 構造体を取得する方法を認識している。描画オブジェクトは、この情報を取得した後、サンプルに含まれるイメージを描画するときに、DIBDATA 構造体に格納されたビットマップ ハンドルを GDI に渡すことができる。描画時にバッファ ポインタ (サンプルが CImageSample ではない場合に使用される) ではなく、サンプルから取得したビットマップ ハンドルを使用することによって、パフォーマンスが若干向上する。

CDrawImage::DisplaySampleTimes

CDrawImage クラス

イメージの先頭のサンプルのタイム スタンプを表示する。

構文

void DisplaySampleTimes(
IMediaSample *pSample
);

パラメータ

pSample
タイム スタンプを含むサンプルへのポインタ。

戻り値

戻り値なし。

注意

デバッグ ビルドでは、オブジェクトが描画しているイメージのタイム スタンプを確認することが重要になる場合がある。このメンバ関数は、サンプルが保持しているイメージのデータ ポインタと共に、そのタイム スタンプを取得する。次に、オフスクリーン デバイス コンテキストを使用して、イメージの上から約 80 パーセントの位置に、中央に揃えて時間を描画する。

これはプロテクト メンバ関数である。

CDrawImage::DrawImage

CDrawImage クラス

イメージを描画する。

構文

BOOL DrawImage(
IMediaSample *pMediaSample
);

パラメータ

pMediaSample
描画するサンプルへのポインタ。

戻り値

戻り値なし。

注意

サンプルが CImageAllocator オブジェクト (または派生クラス) で割り当てられている場合、このサンプルが含むイメージは Microsoft Win32 BitBlt または StretchBlt 関数を使用して描画される。それ以外の場合は、SetDIBitsToDevice または StretchDIBits を使用して描画される。クライアントは、このメンバ関数を呼び出す前に CDrawImage::NotifyAllocator を呼び出して、イメージ バッファがどのように割り当てられているかを CDrawImage オブジェクトに通知しなければならない。転送元または転送先が (CDrawImage::SetSourceRect および CDrawImage::SetTargetRect メンバ関数によって) 変更されるたびに、このオブジェクトに通知される。オブジェクトはこの情報を使用して、描画時にイメージを伸縮する必要があるかどうかを判断する。

CDrawImage::FastRender

CDrawImage クラス

Microsoft Win32 BitBlt および StretchBlt 関数を使用して、サンプル イメージを描画する。

構文

void FastRender(
IMediaSample *pMediaSample
);

パラメータ

pMediaSample
描画するサンプルへのポインタ。

戻り値

戻り値なし。

注意

このプロテクト メンバ関数は、イメージ バッファを含むサンプルを指定して CDrawImage によって呼び出される。このイメージ バッファは、Win32 CreateDIBSection 関数および CImageAllocator オブジェクト (または派生クラス) を使用して割り当てられていなければならない。このメカニズムを使って作成されたイメージを描画することによって、若干パフォーマンスが向上する。

CDrawImage::GetPaletteVersion

CDrawImage クラス

現在のパレットのバージョンを取得する。

構文

LONG GetPaletteVersion(void);

戻り値

パレットのバージョンを返す。

注意

このメンバ関数は、CImageAllocator (または派生クラスの) オブジェクトを通して割り当てられたサンプルを使用した場合にのみ適用可能である。パレットの処理の詳細については、「CDrawImage::UpdateColourTable メンバ関数」を参照すること。

CDrawImage::GetSourceRect

CDrawImage クラス

描画オブジェクトが使用する現在の転送元矩形を取得する。

構文

void GetSourceRect(
RECT *pSourceRect
);

パラメータ

pSourceRect
転送元矩形へのポインタ。

戻り値

戻り値なし。

CDrawImage::GetTargetRect

CDrawImage クラス

描画オブジェクトが使用する現在の転送先矩形を取得する。

構文

void GetTargetRect(
RECT *pTargetRect
);

パラメータ

pTargetRect
転送先矩形へのポインタ。

戻り値

戻り値なし。

CDrawImage::IncrementPaletteVersion

CDrawImage クラス

現在のパレットのバージョンをインクリメントする。

構文

void IncrementPaletteVersion(void);

戻り値

戻り値なし。

注意

このメンバ関数は、CImageAllocator (または派生クラスの) オブジェクトを通して割り当てられたサンプルを使用した場合にのみ適用可能である。パレットの処理の詳細については、「CDrawImage::UpdateColourTable メンバ関数」を参照すること。

CDrawImage::NotifyAllocator

CDrawImage クラス

出力ピンが実際に使用するアロケータを描画オブジェクトに通知する。

構文

void NotifyAllocator(
BOOL bUsingImageAllocator
);

パラメータ

bUsingImageAllocator
CImageAllocator オブジェクト アロケータを使用するかどうかを指定するフラグ。詳細については、「注意」を参照すること。

戻り値

戻り値なし。

注意

このメンバ関数は、使用するアロケータを描画オブジェクトに通知する。フィルタが Microsoft® DirectShow® CImageAllocator 基底クラスに基づくアロケータを使用することに合意している場合は、TRUE を指定してこのメンバ関数を呼び出す必要がある。このようなイメージ バッファは、CreateDIBSection を使用して作成される。それ以外の場合は、FALSE を指定してこのメンバ関数を呼び出す必要があり、イメージは SetDIBitsToDevice および StretchDIBits を使用して描画される。

CDrawImage::NotifyEndDraw

CDrawImage クラス

イメージ レンダリングの終了を指定する。

構文

void NotifyEndDraw(void);

戻り値

戻り値なし。

注意

このメンバ関数はパフォーマンス測定のために使用され、MSR_STOP マクロを呼び出す。

CDrawImage::NotifyMediaType

CDrawImage クラス

描画オブジェクトにイメージ フォーマットを提供する。

構文

void NotifyMediaType(
CMediaType *pMediaType
);

パラメータ

pMediaType
メディア タイプへのポインタ。

戻り値

戻り値なし。

注意

描画オブジェクトは、描画するイメージのフォーマットを認識しなければならない。ほとんどの場合、これはイメージが 8 ビット パレット化されている場合にパレットを取得できるようにするためである。描画クラスを使用するフィルタは、通常、接続を完了した後、これを呼び出す。

この関数は、パフォーマンス上の理由から、メディア タイプのコピーを作成せずに、ポインタを格納するだけである。したがって、呼び出し元はメディア タイプが誤って破棄されていないことを確認する必要がある。

CDrawImage::NotifyStartDraw

CDrawImage クラス

イメージ レンダリングの開始を指定する。

構文

void NotifyStartDraw(void);

戻り値

戻り値なし。

注意

このメンバ関数はパフォーマンス測定のために使用され、MSR_START マクロを呼び出す。

CDrawImage::ResetPaletteVersion

CDrawImage クラス

現在のパレットのバージョンをリセットする。

構文

void ResetPaletteVersion(void);

戻り値

戻り値なし。

注意

このメンバ関数は、CImageAllocator (または派生クラスの) オブジェクトを通して割り当てられたサンプルを使用した場合にのみ適用可能である。パレットの処理の詳細については、「CDrawImage::UpdateColourTable メンバ関数」を参照すること。

CDrawImage::ScaleSourceRect

CDrawImage クラス

指定された転送元矩形のスケーリングされたバージョンを取得する。

構文

virtual RECT ScaleSourceRect(
const RECT *pSource
);

パラメータ

pSource
スケーリングされていない転送元矩形へのポインタ。

戻り値

スケーリングされた転送元矩形を返す。デフォルトでは、スケーリングされていない pSource を返す。

注意

基底クラスの実装は、転送元矩形をスケーリングしない。派生クラスはこれをオーバーライドして、必要に応じてスケーリングを実装できる。

CDrawImage::SetDrawContext

CDrawImage クラス

描画に使用されるデバイス コンテキストを設定する。

構文

void SetDrawContext(void);

戻り値

戻り値なし。

注意

描画オブジェクトは、常に、イメージを描画するウィンドウのデバイス コンテキストを必要とする。また、DIBSECTION バッファを使用する場合にビットマップを選択するオフスクリーン デバイス コンテキストを必要とする。DIBSECTION バッファおよび CreateDIBSection の詳細については、Microsoft Platform SDK のドキュメントを参照すること。このメンバ関数は、通常、このクラスを使用するフィルタがウィンドウを初期化した後、このフィルタによって呼び出される。

CDrawImage::SetSourceRect

CDrawImage クラス

ビデオの転送元矩形を設定する。

構文

void SetSourceRect(
RECT *pSourceRect
);

パラメータ

pSourceRect
新しい転送元矩形へのポインタ。

戻り値

戻り値なし。

注意

指定された転送元矩形が使用可能なビデオの境界を越えないようにするために、このメンバ関数を呼び出す前に、転送元矩形が有効になっている必要がある。

CDrawImage::SetStretchMode

CDrawImage クラス

ビデオを伸縮するかどうかを判断する。

構文

void SetStretchMode(void);

戻り値

戻り値なし。

注意

オブジェクトにイメージの描画を指示する場合、オブジェクトはビデオが伸縮されているかどうかを認識する必要がある。これは、オブジェクトが呼び出す関数 (BitBlt または StretchBlt など) に影響するからである。各フレームについてこれを計算するのではなく、転送元矩形または転送先矩形が更新されたときに 1 回だけ計算する。このメンバ関数は、この計算を行うために、SetSourceRect および SetTargetRect によって呼び出される。

これはプロテクト メンバ関数である。

CDrawImage::SetTargetRect

CDrawImage クラス

ビデオの転送先矩形を設定する。

構文

void SetTargetRect(
RECT *pTargetRect
);

パラメータ

pTargetRect
新しい転送先矩形へのポインタ。

戻り値

戻り値なし。

注意

指定された転送先が空の再生領域を定義しないように、このメンバ関数を呼び出す前に転送先矩形が有効になっている必要がある。

CDrawImage::SlowRender

CDrawImage クラス

SetDIBitsToDevice および StretchDIBits を使用してイメージを描画する。

構文

void SlowRender(
IMediaSample *pMediaSample
);

パラメータ

pMediaSample
描画するサンプルへのポインタ。

戻り値

戻り値なし。

注意

指定されたサンプルは、描画するイメージを含んでおり、NotifyMediaType を使用して描画オブジェクトに対して指定されたフォーマットと一致している必要がある。

これはプロテクト メンバ関数である。

CDrawImage::UpdateColourTable

CDrawImage クラス

サンプルに関連付けられたパレットを更新する。

構文

void UpdateColourTable(
HDC hdc,
BITMAPINFOHEADER *pbmi
);

パラメータ

hdc
サンプルのイメージを含むデバイス コンテキスト。
pbmi
新しいパレットを格納する BITMAPINFO 構造体へのポインタ。

戻り値

戻り値なし。

注意

このメンバ関数は、CImageAllocator (または派生クラスの) オブジェクトを通して割り当てられたサンプルを使用した場合にのみ適用可能である。CImageAllocator は、Microsoft Win32 CreateDIBSection 関数を使用して作成されたサンプルを作成する。パレット化されたバッファが CreateDIBSection を使用して割り当てられている場合、そのバッファに関連付けられたパレットが渡される。

パレットが変更された場合、新しいパレットを描画する前に、そのパレットをバッファに関連付ける必要がある。これは、Win32 SetDIBColorTable 関数、および内部的には UpdateColourTable メンバ関数によって処理される。サンプル内に格納されたパレットのバージョンと、パレットが内部に保持しているパレットのバージョンが異なるので、描画コードでパレットの更新が認識される。

基本的に、サンプルは、作成時に初期パレット バージョンを取得する。パレットがフィルタなどによって変更された場合、パレットは、IncrementPaletteVersion メンバ関数を使用してパレットのバージョンをインクリメントするように、描画オブジェクトに指示する。描画オブジェクトが次にサンプルを描画するときには、サンプルのパレットのバージョンが古いことを認識し、そのサンプルについて UpdateColourTable を呼び出す。

描画オブジェクトは、NotifyAllocator メンバ関数を使用して、サンプルで使用されるバッファのタイプを認識する。TRUE を指定して呼び出された場合、このメンバ関数に渡されるバッファは、CImageAllocator (または派生クラスの) オブジェクトによって割り当てられる。FALSE を指定して呼び出された場合、バッファは標準のシステム メモリ (または同じ方法で GDI からアクセスできるその他のメモリ) 内で割り当てられる。

アロケータがデコミットされると、通常、アロケータが保持しているすべてのサンプルが削除される。その後、アロケータがコミットされると、サンプルは最初のパレット バージョンを使用して再び作成される。この時点で、アロケータは描画オブジェクト内のパレットのバージョンをリセットし、同期させる必要がある。アロケータは、ResetPaletteVersion メンバ関数を呼び出すことによって、この処理を実行できる。

これはプロテクト メンバ関数である。

CDrawImage::UsingImageAllocator

CDrawImage クラス

描画されるサンプルのタイプを取得する。

構文

BOOL UsingImageAllocator(void);

戻り値

次のいずれかの値を返す。
TRUE | CreateDIBSection を使用して割り当てられた。
FALSE | CreateDIBSection を使用して割り当てられていない。

注意

このメンバ関数は、CImageAllocator (または派生クラスの) オブジェクトを通して割り当てられたサンプルを使用した場合にのみ適用可能である。パレット処理とイメージ アロケータの詳細については、「CDrawImage::UpdateColourTable メンバ関数」を参照すること。


CDynamicOutputPin クラス

動的再接続とフォーマット変更をサポートする出力ピンを実装する。

宣言 : Amfilter.h

このクラスは CBaseOutputPin ピンから派生し、IPinFlowControl インターフェイスを実装する。それは 動的グラフ作成 に重要ないくつかの操作をサポートする :

  • 動的再接続 : フィルタがアクティブ (ポーズか実行中) の間に、ピンが切れたり再接続したりできる。
  • 動的フィルタ変更 : フィルタがアクティブな間に再接続なしに、ピンが新しいメディア タイプを処理できる。
  • フロー コントロール : フィルタを停止せずに、自分自身のフィルタ (またはアプリケーション) がデータ フローをブロックできる。

このピンは 3 つの状態が可能である: ブロックされている (Blocked)、ブロック解除されている (not Blocked)、待機状態 (Pending)。待機 状態では、ピンがブロックされた状態になる前に、他のスレッド操作が完了するのを待っている。ピンがブロックされている間、フィルタはデータをピンから出力できない、あるいはピンの接続を変更できない。

所有するフィルタは、複数のスレッド間の調整を行うにために、あるルールに従わなければならない。フィルタ グラフのスレッドの詳細については、「スレッドとクリティカル セクション」を参照すること。最初に、ストリーミング スレッドは、次のメソッドのいずれかを呼び出す前に、必ずStartUsingOutputPin メソッドを呼び出さなければならない。

  • ChangeOutputFormat
  • ChangeMediaType
  • DynamicReconnect
  • CBaseOutputPin::Deliver
  • CBaseOutputPin::DeliverEndOfStream
  • CBaseOutputPin::DeliverNewSegment
  • IMemInputPin::Receive
  • IMemInputPin::ReceiveMultiple
  • IPin::EndOfStream
  • IPin::NewSegment

その後で、StopUsingOutputPin メソッドを呼び出さなければならない。

次に、アプリケーション スレッドは前述の一覧にあるいずれのメソッドも呼び出してはならない。また、ストリーミング スレッドは、ピンをブロックまたはブロック解除するクラス メソッドを呼び出してはならない。このようなメソッドには、Block、SynchronousBlockOutputPin、AsynchronousBlockOutputPin、および UnblockOutputPin がある。

これらのルールはストリーミング スレッドがピンを使用中に、アプリケーション スレッドがそのピンをブロックできなくするため (または逆も) である。ストリーミング スレッドが StartUsingOutputPin を呼び出した後、そのスレッドが StopUsingOutputPin を呼び出すまで、ピンはブロックされない。逆にピンがブロックされると、StartUsingOutputPin はピンが非ブロックになるまで待つ。

StopUsingOutputPin の呼び出しを忘れないために、CAutoUsingOutputPin クラスを使うことができる。それは 終了する前に自動的に StopUsingOutputPin を呼び出す。

(IBaseFilter::JoinFilterGraph メソッド内で) 自身のフィルタがフィルタ グラフに参加あるいは退出するとき、ピンの SetConfigInfo メソッドを呼び出さなければならない。

Protected メンバ変数
m_BlockStateLock | ブロック状態を保護するクリティカル セクション。
m_hUnblockOutputPinEvent | ピンがブロックされていないときに通知済のイベント。
m_hNotifyCallerPinBlockedEvent | ピンのブロックに成功したとき、あるいはユーザーが待機ブロックをキャンセルできないとき、通知済のイベント。
m_BlockState | ブロック状態。
m_dwBlockCallerThreadID | このピンで最後に IPinFlowControl::Block メソッドを呼び出したスレッドの ID。
m_dwNumOutstandingOutputPinUsers | このピンを使用しているストリーミング スレッドの数。
m_hStopEvent | フィルタが停止した、あるいはピンがデータをフラッシュしたとき、通知済のイベント。
m_pGraphConfig | 動的再接続を実行する IGraphConfig インターフェイスへのポインタ。
m_bPinUsesReadOnlyAllocator | ピンのアロケータからのサンプルが読み込み専用かどうかを指定するフラグ。
Protected メソッド
SynchronousBlockOutputPin | ピンをブロックする。ピンがブロックされるまで返らない。
AsynchronousBlockOutputPin | ピンをブロックする。ピンがブロックされるまでに返ることがある。
UnblockOutputPin | ピンをブロック解除する。
BlockOutputPin | ピンをブロックする。
WaitEvent | 指定したイベントが通知済になるまで待つ。
Public メソッド
CDynamicOutputPin | コンストラクタ メソッド。
~CDynamicOutputPin | デストラクタ メソッド。
SetConfigInfo | IGraphConfig ポインタと停止イベントを指定する。
DeliverBeginFlush | 接続した入力ピンにフラッシュ処理を要求する。
DeliverEndFlush | 接続した入力ピンにフラッシュ処理の終了を要求する。
Inactive | ピンにフィルタが停止していることを通知する。
Active | ピンにフィルタが今アクティブであることを通知する。
CompleteConnect | 入力ピンへの接続を完了する。 仮想。
StartUsingOutputPin | ストリーミング操作でピンのアクセスを獲得する。 仮想。
StopUsingOutputPin | ストリーミング操作の後ピンへのアクセスを解放する。 仮想。
StreamingThreadUsingOutputPin | スレッドがピンでストリーミング操作を行っているかどうかを確認する。仮想。
ChangeOutputFormat | 接続しているメディア タイプを動的に変更し、新しいセグメント情報を出力する。
ChangeMediaType | 接続しているメディア タイプを動的に変更する。
DynamicReconnect | 新しいメディア タイプと動的再接続を行う。
IPin メソッド
Disconnect | 現在のピン接続を解除する。
IPinFlowControl メソッド
Block | ピンからのデータのフローをブロック、あるいはブロック解除する。

CDynamicOutputPin.m_BlockStateLock

CDynamicOutputPin クラス

ブロック状態を保護するクリティカル セクション。

構文

CCritSec m_BlockStateLock;

注意

次のメンバ関数を使う前にこのクリティカルセッションを保持すること :

  • m_BlockState
  • m_dwBlockCallerThreadID
  • m_dwNumOutstandingOutputPinUsers
  • m_hNotifyCallerPinBlockedEvent

CDynamicOutputPin.m_hUnblockOutputPinEvent

CDynamicOutputPin クラス

ピンがブロックされていないときに通知済のイベント。

構文

HANDLE m_hUnblockOutputPinEvent;

CDynamicOutputPin.m_hNotifyCallerPinBlockedEvent

CDynamicOutputPin クラス

ピンのブロックが成功したとき、あるいはユーザーがブロック待機をキャンセルしたときに通知済のイベント。

構文

HANDLE m_hNotifyCallerPinBlockedEvent;

注意

この変数にアクセスする前に、m_BlockStateLock クリティカル セクションを保持すること。

CDynamicOutputPin.m_BlockState

CDynamicOutputPin クラス

ブロック状態。

構文

BLOCK_STATE m_BlockState;

注意

次の状態を確認する。

  • NOT_BLOCKED
  • PENDING
  • BLOCKED

この変数にアクセスする前に、m_BlockStateLock クリティカル セクションを保持すること。

CDynamicOutputPin.m_dwBlockCallerThreadID

CDynamicOutputPin クラス

このピンで最後に IPinFlowControl::Block メソッドを呼び出したスレッドの識別子。このメンバ変数は、ピンがブロックされているときだけ有効である。

構文

DWORD m_dwBlockCallerThreadID;

注意

この変数にアクセスする前に、m_BlockStateLock クリティカル セクションを保持すること。

CDynamicOutputPin.m_dwNumOutstandingOutputPinUsers

CDynamicOutputPin クラス

このピンを使用しているストリーミング スレッドの数。

構文

DWORD m_dwNumOutstandingOutputPinUsers;

注意

StartUsingOutputPin メソッドはこの変数をインクリメントし、StopUsingOutputPin メソッドはデクリメントする。この値がゼロより大きいとき、いくつかのスレッドがこのピンを使ってデータをストリームしている、あるいは接続タイプを変更している。この間はピンをブロック状態にできない。

この変数にアクセスする前に、m_BlockStateLock クリティカル セクションを保持すること。

参照

StreamingThreadUsingOutputPin

CDynamicOutputPin.m_hStopEvent

CDynamicOutputPin クラス

フィルタが停止した、あるいはピンがデータをフラッシュしたとき、通知済のイベント。

構文

HANDLE m_hStopEvent;

CDynamicOutputPin.m_pGraphConfig

CDynamicOutputPin クラス

動的再接続を実行する IGraphConfig インターフェイスへのポインタ。

構文

IGraphConfig* m_pGraphConfig;

CDynamicOutputPin.m_bPinUsesReadOnlyAllocator

CDynamicOutputPin クラス

ピンのアロケータからのサンプルが読み込み専用かどうかを指定するフラグ。 この値が TRUE ならサンプルは読み込み専用。デフォルト値は FALSE。

構文

BOOL m_bPinUsesReadOnlyAllocator;

CDynamicOutputPin::Active

CDynamicOutputPin クラス

フィルタがアクティブになったことをピンに通知する。

構文

HRESULT Active(void);

戻り値

HRESULT 値を返す。以下の表に示されるいずれかの値。

S_OK | 成功。
E_FAIL | 失敗。SetConfigInfo が呼び出されなかった。

注意

このメソッドは、CBaseOutputPin::Active メソッドをオーバーライドする。また、m_hStopEvent イベントをリセットする。所有するフィルタが SetConfigInfo を呼び出していない場合、このメソッドは E_FAIL を返す。

CDynamicOutputPin::AsynchronousBlockOutputPin

CDynamicOutputPin クラス

ピンをブロックする。ピンがブロックされる前に返ることがある。

構文

HRESULT AsynchronousBlockOutputPin(
    HANDLE hNotifyCallerPinBlockedEvent
);

パラメータ

hNotifyCallerPinBlockedEvent
イベントへのハンドル。出力ピンがブロックされるか、呼び出し元がブロック処理を取り消すと、イベントは通知済になる。

戻り値

HRESULT 値を返す。 以下の表に示されるいずれかの値。

S_OK | 成功。
VFW_E_PIN_ALREADY_BLOCKED | ピンは既に他のスレッドでブロックされている。
VFW_E_PIN_ALREADY_BLOCKED_ON_THIS_THREAD | ピンは既に呼び出し元のスレッドでブロックされている。

注意

ストリーミング スレッドからこのメソッドを呼び出してはならない。

ほかのストリーミング スレッドがピンを使っていない場合、このメソッドはすぐにピンをブロックする。それ以外の場合、このメソッドはピンの状態を "保留中" にして返る。ストリーミング処理が完了すると、ストリーミング スレッドは StopUsingOutputPin メソッドを呼び出してピンをブロックし、hNotifyCallerPinBlockedEvent イベントに通知する。保留中のブロックを取り消すには、UnblockOutputPin メソッドを呼び出す。

CDynamicOutputPin::Block

CDynamicOutputPin クラス

ピンからのデータの流れをブロック、またはブロック解除する。IPinFlowControl::Block メソッドを実装する。

構文

HRESULT Block(
    DWORD dwBlockFlags,
    HANDLE hEvent
);

パラメータ

dwBlockFlags
ピンをブロックするか、ブロック解除するかを示すフラグ。次のいずれかの値でなくてはならない。
  • ゼロ : ピンからのデータの流れをブロック解除する。
  • AM_PIN_FLOW_CONTROL_BLOCK : ピンからのデータの流れをブロックする。
hEvent
イベント オブジェクトへのハンドル、または NULL。

戻り値

HRESULT 値を返す。以下の表に示されるいずれかの値。

S_FALSE | ピンは既にブロック解除されている。
S_OK | 成功。
E_INVALIDARG | 無効な引数。
VFW_E_PIN_ALREADY_BLOCKED | ピンはほかのスレッドで既にブロックされている。
VFW_E_PIN_ALREADY_BLOCKED_ON_THIS_THREAD | ピンは呼び出し元スレッドで既にブロックされている。

注意

このメソッドの詳細については、「IPinFlowControl::Block」を参照すること。このメソッドは、内部的には次のプロテクト メソッドのいずれかを呼び出す。

  • ブロック (非同期) : AsynchronousBlockOutputPin
  • ブロック (同期) : SynchronousBlockOutputPin
  • ブロック解除 : UnblockOutputPin

ブロック解除は、常に同期に実行される。

CDynamicOutputPin::BlockOutputPin

CDynamicOutputPin クラス

ピンをブロックする。ピンがブロックされている間は、StartUsingOutputPin メソッドがピンのブロック解除を待つ。ブロック状態によって、出力ピンはサンプルの出力、出力フォーマットの変更、または再接続ができなくなる。

構文

void BlockOutputPin(void);

注意

このメソッドを呼び出す前に、m_BlockStateLock クリティカル セクションを保持すること。ストリーミング スレッドがこのピンを使用している、あるいはデータを出力している、あるいは接続を変更しているなら、このメソッドを呼び出してはならない。ストリーミング スレッドがこのピンを使用しているかどうかをチェックするには、StreamingThreadUsingOutputPin メソッドを呼び出すこと。

CDynamicOutputPin::CDynamicOutputPin

CDynamicOutputPin クラス

コンストラクタ メソッド。

構文

CDynamicOutputPin(
    TCHAR *pObjectName,
    CBaseFilter *pFilter,
    CCritSec *pLock,
    HRESULT *phr,
    LPCWSTR pName
);

パラメータ

pObjectName
オブジェクトの名前を含む文字列へのポインタ。詳細については、「CBaseObject」を参照すること。
pFilter
このピンを作成したフィルタへのポインタ。
pLock
状態変更を継続するために用いる CCritSec ロックへのポインタ。フィルタ ロック CBaseFilter.m_pLock と同じクリティカル セクションを使うこと。
phr
メソッドの成功または失敗を示す HRESULT 値を受け取る変数へのポインタ。値を S_OK に初期化してからオブジェクトを作成する。この値は、エラーが発生したときだけ変更される。
pName
ピン識別子を含む Unicode™ 文字列へのポインタ。詳細については、「IPin::QueryId」を参照すること。

CDynamicOutputPin::~CDynamicOutputPin

CDynamicOutputPin クラス

デストラクタ メソッド。

構文

~CDynamicOutputPin(void);

CDynamicOutputPin::ChangeMediaType

CDynamicOutputPin クラス

接続のメディア タイプを動的に変更する。この変更は、フィルタ グラフの実行中にだけ発生する。このメソッドが呼び出されると、古いメディア タイプのサンプルは、出力できなくなる。呼び出し元は、古いサンプルが待機中でないことを確認しなければならない。

構文

HRESULT ChangeMediaType(
    const CMediaType *pmt
);

パラメータ

pmt
メディア タイプを指定する AM_MEDIA_TYPE 構造体へのポインタ。

戻り値

HRESULT 値を返す。 以下の表に示されるいずれかの値。

S_OK | 成功。
E_FAIL | 失敗。 所有するフィルタが SetConfigInfo を呼び出さなかった可能性が高い。
VFW_E_NOT_CONNECTED | ピンが接続されていない。

注意

このメソッドを呼び出す前に StartUsingOutputPin メソッドを呼び出すこと。

このメソッドは最初にダウンストリーム入力ピンが再接続なしに新しいフォーマットを受け入れるかどうかをチェックする。それは IPinConnection インターフェイスで入力ピンに問い合わせる。入力ピンが IPinConnection をサポートするなら、メソッドは提案されたメディア タイプで IPinConnection::DynamicQueryAccept メソッドを呼び出す。入力ピンが新しいメディア タイプを受け入れるなら、メソッドは IPin::ReceiveConnection メソッドを呼び出して、アロケータ要求を再処理する。

一方、ダウンストリーム ピンが IPinConnection をサポートしない、あるいは新しいメディア タイプを拒否したなら、メソッドは DynamicReconnect メソッドを呼び出して動的再接続を実行する。

CDynamicOutputPin::ChangeOutputFormat

CDynamicOutputPin クラス

接続しているメディア タイプを動的に変更し、新しいセグメント情報を出力する。このメソッドが呼び出されると、古いメディア タイプのサンプルは、出力できなくなる。呼び出し元は、古いサンプルが待機中でないことを確認しなければならない。

構文

HRESULT ChangeOutputFormat(
    const AM_MEDIA_TYPE *pmt,
    REFERENCE_TIME tSegmentStart,
    REFERENCE_TIME tSegmentStop,
    double dSegmentRate
);

パラメータ

pmt
メディア タイプを指定する AM_MEDIA_TYPE 構造体へのポインタ。
tSegmentStart
セグメントの開始タイム。
tSegmentStop
セグメントの終了タイム。
dSegmentRate
セグメント レート。

戻り値

HRESULT 値を返す。 以下の表に示されるいずれかの値。

S_OK | 成功。
E_FAIL | 失敗。多分所有者であるフィルタが SetConfigInfo を呼び出さなかった。
VFW_E_NOT_CONNECTED | ピンが接続されていない。

注意

このメソッドはフィルタ実行中にフォーマットタイプを変更する。ダウンストリーム ピンが新しいフォーマットを承認すれば、再接続は不要である。そうでなければ、メソッドはピンを再接続しようとする。メソッドはフォーマットの変更に成功すると、新セグメント情報を出力する。このメソッドは ChangeMediaType メソッドを呼び出してフォーマット変更を実行する。

このメソッドを呼び出す前に StartUsingOutputPin メソッドを呼び出さなければならない。

CDynamicOutputPin::CompleteConnect

CDynamicOutputPin クラス

入力ピンへの接続を完了する。

構文

virtual HRESULT CompleteConnect(
    IPin *pReceivePin
);

パラメータ

pReceivePin
入力ピンの IPin インターフェイスへのポインタ。

戻り値

成功した場合は S_OK を返す。または、HRESULT 値を返し、失敗の原因を示す。

注意

このメソッドは、CBaseOutputPin::CompleteConnect メソッドにオーバーライドする。動的な再接続をサポートするため、このメソッドは、フィルタがアクティブな場合にアロケータをコミットする。基底クラスでは、フィルタが停止しているときだけに接続は発生するので、アロケータは常に CBaseOutputPin::Active メソッドでコミットされる。

CDynamicOutputPin::DeliverBeginFlush

CDynamicOutputPin クラス

接続した入力ピンにフラッシュ処理を要求する。

構文

HRESULT DeliverBeginFlush(void);

戻り値

成功なら S_OK を返す、 それ以外なら失敗の原因を示す HRESULT 値を返す。

注意

このメソッドは CBaseOutputPin::DeliverBeginFlush メソッドをオーバーライドする。それは m_hStopEvent イベントを設定する。

CDynamicOutputPin::DeliverEndFlush

CDynamicOutputPin クラス

接続した入力ピンにフラッシュ処理の終了を要求する。

構文

HRESULT DeliverEndFlush(void);

戻り値

成功なら S_OK を返す、 それ以外なら失敗の原因を示す HRESULT 値を返す。

注意

このメソッドは CBaseOutputPin::DeliverEndFlush メソッドをオーバーライドする。それは m_hStopEvent イベントをリセットする。

CDynamicOutputPin::Disconnect

CDynamicOutputPin クラス

現在のピン接続を解除する。IPin::Disconnect メソッドを実装する。

構文

HRESULT Disconnect(void);

戻り値

HRESULT 値を返す。以下の表に示されるいずれかの値。

S_FALSE | ピンは接続されなかった。
S_OK | 成功。

注意

このメソッドは、CBasePin::Disconnect メソッドにオーバーライドし、フィルタがアクティブな間に切断ができるようにする。

CDynamicOutputPin::DynamicReconnect

CDynamicOutputPin クラス

新しいメディア タイプを使って動的な再接続を行う。再接続は、フィルタ グラフが実行中に行うことができる。

構文

HRESULT DynamicReconnect(
    const CMediaType *pmt
);

パラメータ

pmt
メディア タイプを指定する AM_MEDIA_TYPE 構造体へのポインタ。

戻り値

HRESULT 値を返す。以下の表に示されるいずれかの値。

S_OK | 成功。
E_FAIL | 失敗。所有するフィルタが、SetConfigInfo メソッドを呼び出さなかった可能性が高い。

注意

このメソッドは、ピンにデータを提供するスレッドと同じスレッドから呼び出されなければならない。このメソッドが呼び出されると、古いメディア タイプのサンプルは提供できなくなる。呼び出し元は、古いサンプルが待機中でないことを確認しなければならない。

StartUsingOutputPin を呼び出して、このメソッドを呼び出す。

CDynamicOutputPin::Inactive

CDynamicOutputPin クラス

ピンにフィルタが停止していることを通知する。

構文

HRESULT Inactive(void);

戻り値

成功なら S_OK を返す、 それ以外なら失敗の原因を示す HRESULT 値を返す。

注意

このメソッドは CBaseOutputPin::Inactive メソッドをオーバーライドする。それは m_hStopEvent イベントを設定する。

CDynamicOutputPin::SetConfigInfo

CDynamicOutputPin クラス

IGraphConfig ポインタを指定し、イベントを停止する。

構文

void SetConfigInfo(
    IGraphConfig *pGraphConfig,
    HANDLE hStopEvent
);

パラメータ

pGraphConfig
IGraphConfig インターフェイスへのポインタ、あるいは NULL。
hStopEvent
フィルタが停止するときに通知済のイベントへのハンドル、あるいは NULL。

注意

フィルタは、フィルタ グラフに参加するときに、このメソッドを呼び出さなければならない。フィルタ グラフ マネージャは、IGraphConfig をサポートしている。hStopEvent パラメータについては、手動リセット イベントを作成する。フィルタがフィルタ グラフから退出するとき、両方のパラメータを NULL にして、このメソッドをもう一度呼び出す。

CDynamicOutputPin::StartUsingOutputPin

CDynamicOutputPin クラス

ストリーミング操作でピンのアクセスを獲得する。

構文

virtual HRESULT StartUsingOutputPin(void);

戻り値

HRESULT 値を返す。 以下の表に示されるいずれかの値。

S_OK | 成功。
E_UNEXPECTED | 予期せぬエラー。
VFW_E_STATE_CHANGED | フィルタは停止された。または、ピンがフラッシングを開始した。

注意

接続された入力ピンにデータを出力するメソッド、または接続のメディア タイプを変更するメソッドを呼び出す前に、このメソッドを呼び出すこと。次の一覧は、このルールの適用先となるメソッドの例を示している。

  • ChangeOutputFormat
  • ChangeMediaType
  • DynamicReconnect
  • CBaseOutputPin::Deliver
  • CBaseOutputPin::DeliverEndOfStream
  • CBaseOutputPin::DeliverNewSegment
  • IMemInputPin::Receive
  • IMemInputPin::ReceiveMultiple
  • IPin::EndOfStream
  • IPin::NewSegment

その後で、StopUsingOutputPin メソッドを呼び出してピンへのアクセスを解放する。

ピンがブロックされているなら、StartUsingOutputPin はピンがブロック解除になるまで待つ。このメソッドが待っている間フィルタが停止するなら、メソッドはすぐに VFW_E_STATE_CHANGED を返す。ピンは StopUsingOutputPin への対応する呼び出しなしに何度StartUsingOutputPin が呼び出されたかという数を維持する。このカウントがゼロ以外のときに、他のスレッドがピンをブロックしようとすると、ピンはそのブロック状態を「待機」に設定する。最終的な StopUsingOutputPin 呼び出しで、ピンはストリーミング操作がすべて完了した後でブロック状態になる。

このメソッドを呼び出すときは、m_BlockStateLock クリティカル セクションを保持してはならない。そうでないと、ピンがブロックされたときブロック解除ができなくなりデッドロックを起こす。

CDynamicOutputPin::StopUsingOutputPin

CDynamicOutputPin クラス

ストリーミング操作の後ピンへのアクセスを解放する。

構文

virtual void StopUsingOutputPin(void);

参照

StartUsingOutputPin

CDynamicOutputPin::StreamingThreadUsingOutputPin

CDynamicOutputPin クラス

スレッドがピンでストリーミング操作を行っているかどうかを確認する。

構文

virtual bool StreamingThreadUsingOutputPin(void);

戻り値

スレッドがピンでストリーミング操作を行っていれば TRUE を返す。それ以外なら FALSE を返す。

注意

StartUsingOutputPin メソッドから正しく返されたスレッドがあり、対応する StopUsingOutputPin メソッドを呼び出さないと、このメソッドは TRUE を返す。

CDynamicOutputPin::SynchronousBlockOutputPin

CDynamicOutputPin クラス

ピンをブロックする。ピンがブロック解除されるまで返らない。

構文

HRESULT SynchronousBlockOutputPin(void);

戻り値

HRESULT 値を返す。以下の表に示されるいずれかの値。

S_OK | 成功。
VFW_E_PIN_ALREADY_BLOCKED | ピンは既にほかのスレッドでブロックされている。
VFW_E_PIN_ALREADY_BLOCKED_ON_THIS_THREAD | ピンは既に呼び出し元スレッドでブロックされている。

注意

ストリーミング スレッドからこのメソッドを呼び出さないこと。

CDynamicOutputPin::UnblockOutputPin

CDynamicOutputPin クラス

ピンをブロック解除する。ピンがブロック解除されると、サンプルの出力、出力フォーマットの変更、および再接続ができるようになる。

構文

HRESULT UnblockOutputPin(void);

戻り値

次の表に示されるいずれかの HRESULT 値を返す。

S_FALSE | Pin は既にブロック解除されている。
S_OK | 成功。

CDynamicOutputPin::WaitEvent

CDynamicOutputPin クラス

指定されたイベントが通知済になるまで待つ。

構文

static HRESULT WaitEvent(
    HANDLE hEvent
);

パラメータ

hEvent
イベントへのハンドル。

戻り値

HRESULT 値を返す。以下の表に示されるいずれかの値。

S_OK | 成功。
E_UNEXPECTED | 予期しないエラー。


CEnumMediaTypes クラス

許容するメディアタイプの列挙子

宣言 : Amfilter.h

このクラスは IEnumMediaTypes インターフェイスを実装する。以下の CBasePin メソッドを呼び出す :

  • GetMediaType: ゼロで始まる ID で参照されるメディア タイプを取得する。
  • GetMediaTypeVersion: 許容するタイプのリストが変更されたかどうかを確認する。

ピンが許容するメディア タイプのリストを変更するたびに、ピンはメディアタイプ バージョン数をインクリメントする。これが起こると、列挙オブジェクトはピンとはもう同期せず、クラス メソッドは VFW_E_ENUM_OUT_OF_SYNC を返す。列挙子を同期するには Reset を呼び出すこと。

Public メソッド
CEnumMediaTypes | コンストラクタ メソッド。
~CEnumMediaTypes | デストラクタ メソッド。仮想。
IEnumMediaTypes メソッド。
Clone | 同じ列挙状態で列挙子のコピーを作成する。
Next | 指定した数だけメディア タイプを取得する。
Reset | 列挙シーケンスを開始状態にリセットする。
Skip | 指定した数だけメディア タイプをスキップする。

CEnumMediaTypes::CEnumMediaTypes

CEnumMediaTypes クラス

コンストラクタ メソッド。

構文

CEnumMediaTypes(
    CBasePin *pPin,
    CEnumMediaTypes *pEnumMediaTypes
);

パラメータ

pPin
列挙が行われるべきピンへのポインタ。
pEnumMediaTypes
コピーする列挙子の IEnumMediaTypes インターフェイスへのポインタ、あるいは NULL 。

注意

pEnumMediaTypes が NULL なら、このメソッドは列挙シーケンスの初期状態に列挙子を初期化する。そうでなければ、それは pEnumMediaTypes で指定される列挙子の内部状態をコピーする。

CEnumMediaTypes::~CEnumMediaTypes

CEnumMediaTypes クラス

デストラクタ メソッド。

構文

virtual ~CEnumMediaTypes(void);

CEnumMediaTypes::Clone

CEnumMediaTypes クラス

同じ列挙状態で列挙子のコピーを作る。IEnumMediaTypes::Clone メソッドの実装。

構文

HRESULT Clone(
    IEnumMediaTypes **ppEnum
);

パラメータ

ppEnum
新しい列挙子の IEnumMediaTypes インターフェイスへのポインタを受け取る変数のアドレス。

戻り値

以下の表に示される HRESULT 値の 1 つを返す。

S_OK | 成功。
E_OUTOFMEMORY | メモリ不足。
E_POINTER | NULL ポインタ引数。
VFW_E_ENUM_OUT_OF_SYNC | ピンの状態は変更され、現在その列挙子とは矛盾している。

CEnumMediaTypes::Next

CEnumMediaTypes クラス

指定した数だけメディア タイプを取得する。 IEnumMediaTypes::Next メソッドの実装。

構文

HRESULT Next(
    ULONG cMediaTypes,
    AM_MEDIA_TYPE **ppMediaTypes,
    ULONG *pcFetched
);

パラメータ

cMediaTypes
取得するメディア タイプの数。
ppMediaTypes
サイズ cPins の AM_MEDIA_TYPE 構造体へのポインタの配列。
pcFetched
メソッドが返すメディア タイプの数を受け取る変数のポインタ。cMediaTypes が 1 なら、NULL を取り得る。

戻り値

以下の表に示される HRESULT 値の 1 つを返す。

S_FALSE | 要求された数のメディア タイプを取得できなかった。
S_OK | 成功。
E_INVALIDARG | 不適切な引数。
E_POINTER | NULL ポインタ引数。
VFW_E_ENUM_OUT_OF_SYNC | ピンの状態は変更され、現在その列挙子とは矛盾している。

注意

メソッドが成功すると、ppMediaTypes によって指定される配列には AM_MEDIA_TYPE 構造体へのポインタが入る。構造体の数は *pcFetched と等しい。DeleteMediaType を呼び出して、各メディア タイプをフリーにすること。

このメディアはピンの CBasePin::GetMediaType メソッドを呼び出してメディア タイプを取得する。

CEnumMediaTypes::Reset

CEnumMediaTypes クラス

列挙シーケンスを開始状態にリセットする。IEnumMediaTypes::Reset メソッドの実装。

構文

HRESULT Reset(void);

戻り値

S_OK を返す。

CEnumMediaTypes::Skip

CEnumMediaTypes クラス

指定した数だけメディア タイプをスキップする。IEnumMediaTypes::Skip メソッドの実装。

構文

HRESULT Skip(
    ULONG cMediaTypes
);

パラメータ

cMediaTypes
スキップするメディア タイプの数。

戻り値

以下の表に示される HRESULT 値の 1 つを返す。

S_FALSE | シーケンスの最後までスキップした。
S_OK | 成功。
VFW_E_ENUM_OUT_OF_SYNC | ピンの状態は変更され、現在その列挙子とは矛盾する。


CEnumPins クラス

ピンの列挙子。

宣言 : Amfilter.h

このクラスは IEnumPins インターフェイスを実装する。次の CBaseFilter メソッドを呼び出す :

  • GetPin: ゼロから始まる ID で参照されるフィルタのピンを取得する。
  • GetPinCount: フィルタのピンの総数を取得する。
  • GetPinVersion: ピンが変更されたかどうかを確認する。

フィルタが動的にピンを作成したり削除したりするなら、ピンが変更されるたびにピンのバージョンをインクリメントする。バージョン数が変更されると、列挙オブジェクトはもうそのフィルタとは同期しない。列挙子が同期から外れると、CEnumPins 内のメソッドは VFW_E_ENUM_OUT_OF_SYNC を返す。Reset メソッドを呼び出して列挙子と再同期すること。

Public メソッド
CEnumPins | コンストラクタ メソッド。
~CEnumPins | デストラクタ メソッド。仮想。
IEnumPins メソッド
Clone | 同じ列挙状態で列挙子のコピーを作る。
Next | 指定した数のピンを取得する。
Reset | 列挙シーケンスを初期状態にリセットする。
Skip | 指定したピンの数だけスキップする。

CEnumPins::CEnumPins

CEnumPins クラス

コンストラクタ メソッド。

構文

CEnumPins(
    CBaseFilter *pFilter,
    CEnumPins *pEnumPins
);

パラメータ

pFilter
ピンを列挙するフィルタへのポインタ。
pEnumPins
コピーする列挙子の IEnumPins インターフェイスへのポインタ、あるいは NULL 。

注意

pEnumPins が NULL なら、このメソッドは列挙子を列挙シーケンスの初期状態に初期化する。それ以外なら、pEnumPins が指定する列挙子の内部状態をコピーする。

CEnumPins::~CEnumPins

CEnumPins クラス

デストラクタ メソッド。

構文

virtual ~CEnumPins(void);

CEnumPins::Clone

CEnumPins クラス

同じ列挙状態で列挙子のコピーを作る。IEnumPins::Clone の実装。

構文

HRESULT Clone(
    IEnumPins **ppEnum
);

パラメータ

ppEnum
新しい列挙子の IEnumPins インターフェイスへのポインタを受け取る変数のアドレス。

戻り値

以下の表に示される HRESULT 値の 1 つを返す。

S_OK | 成功。
E_OUTOFMEMORY | メモリ不足。
E_POINTER | NULL ポインタ引数。
VFW_E_ENUM_OUT_OF_SYNC | フィルタの状態は変更され、現在この列挙子とは矛盾する。

CEnumPins::Next

CEnumPins クラス

指定した数のピンを取得する。 IEnumPins::Next メソッドの実装。

構文

HRESULT Next(
    ULONG cPins,
    IPin **ppPins,
    ULONG *pcFetched
);

パラメータ

cPins
取得するピンの数。
ppPins
IPin ポインタで埋められる cPins サイズの配列。
pcFetched
取得するピンの数を受け取る変数のポインタ。cPins が 1 なら NULL が可能。

戻り値

以下の表に示される HRESULT 値の 1 つを返す。

S_FALSE | 要求された数のピンが取得できなかった。
S_OK | 成功。
E_INVALIDARG | 不適切な引数。
E_POINTER | NULL ポインタ引数。
VFW_E_ENUM_OUT_OF_SYNC | フィルタの状態は変更され、現在この列挙子とは矛盾する。

注意

このメソッドは指定した数のピンのポインタを取得し、列挙子の現在位置から開始し、そのポインタを指定した配列に置く。

このメソッドはフィルタの CBaseFilter::GetPin メソッドを呼び出しピンを取得する。

メソッドが成功すると、IPin ポインタはすべて参照カウントが残る。解放時に注意が必要。

CEnumPins::Reset

CEnumPins クラス

列挙シーケンスを初期状態にリセットする。 IEnumPins::Reset メソッドの実装。

構文

HRESULT Reset(void);

戻り値

S_OK を返す。

CEnumPins::Skip

CEnumPins クラス

指定したピンの数だけスキップする。 IEnumPins::Skip メソッドの実装。

構文

HRESULT Skip(
    ULONG cPins
);

パラメータ

cPins
スキップするピンの数。

戻り値

以下の表に示される HRESULT 値の 1 つを返す。

S_FALSE | シーケンスの終わりまでスキップした。
S_OK | 成功。
VFW_E_ENUM_OUT_OF_SYNC | フィルタの状態は変更され、現在この列挙子とは矛盾する。


CFactoryTemplate クラス

クラス ファクトリを作成するテンプレートを提供する。

宣言 : Combase.h

Microsoft® DirectShow® では、クラス ファクトリ は CFactoryTemplate クラスを使って特殊化されており、factory template を呼び出す。各クラス ファクトリはファクトリ テンプレートへのポインタを保持する。ファクトリ テンプレートはオブジェクトのクラス ID (CLSID) とオブジェクトを作成した関数へのポインタを含む COM オブジェクトの情報を持つ。

自分の DLL で、g_Templates と名づけられたファクトリ テンプレートのグローバル配列を宣言すること。DllGetClassObject 関数が新しいクラス ファクトリを作成するとき、適合する CLSID でテンプレートの配列を探す。1 つ見つけると、適合したテンプレートへのポインタを保持するクラス ファクトリを作成する。クライアントが IClassFactory::CreateInstance を呼び出すとき、そのクラス ファクトリはテンプレートに定義されたインスタンス化関数を呼び出す。

詳細については、「DLL の作成方法」を参照すること。

Public メンバ変数
m_Name | フィルタの名前。
m_ClsID | オブジェクトの CLSID へのポインタ。
m_lpfnNew | オブジェクトのインスタンスを作成する関数へのポインタ。
m_lpfnInit | DLL エントリ ポイントから呼び出される関数のポインタ。
m_pAMovieSetup_Filter | AMOVIESETUP_FILTER 構造体へのポインタ。
Public メソッド
IsClassID | CLSID がこのクラス テンプレートと合うかどうかを確認する。
CreateInstance | そのクラスのオブジェクト作成関数を呼び出す。

CFactoryTemplate.m_Name

CFactoryTemplate クラス

フィルタの名前が入るワイド キャラクタ文字列

構文

const WCHAR *m_Name;

CFactoryTemplate.m_ClsID

CFactoryTemplate クラス

オブジェクトの CLSID へのポインタ。

構文

const CLSID *m_ClsID;

CFactoryTemplate.m_lpfnNew

CFactoryTemplate クラス

オブジェクトのインスタンスを作成する関数へのポインタ。

構文

typedef CUnknown *(CALLBACK *LPFNNewCOMObject)(LPUNKNOWN pUnkOuter, HRESULT *phr);

LPFNNewCOMObject m_lpfnNew;

注意

自分の DLL で、オブジェクトの新しいインスタンスへのポインタを返す静的な関数を宣言すること。ファクトリ テンプレートでは、この静的な関数のアドレスに m_lpfnNew メンバ変数を設定する。

次の例は m_lpfnNew の典型的な関数を示す :

CUnknown * WINAPI CMyComponent::CreateInstance(LPUNKNOWN pUnk, HRESULT *pHr)
{
    CMyComponent *pNewObject = new CMyComponent(NAME("My Component"), pUnk, pHr );
    if (pNewObject == NULL)
{
        *phr = E_OUTOFMEMORY;
    }
    return pNewObject;
}

CFactoryTemplate.m_lpfnInit

CFactoryTemplate クラス

DLL エントリ ポイントから呼び出される関数のポインタ。 NULL も可。

構文

typedef void (CALLBACK *LPFNInitRoutine)(BOOL bLoading, const CLSID *rclsid);

LPFNInitRoutine m_lpfnInit;

注意

この関数を自分の DLL で提供すると、DLL エントリ ポイント関数は次のパラメータでそれを呼び出す :

  • bLoading: DLL がロードされているとき TRUE、DLL がロードされていないとき FALSE。
  • rclsid: m_ClsID メンバ関数で指定されるオブジェクトの CLISD へのポインタ。

CFactoryTemplate.m_pAMovieSetup_Filter

CFactoryTemplate クラス

AMOVIESETUP_FILTER 構造体へのポインタ。

構文

const AMOVIESETUP_FILTER *m_pAMovieSetup_Filter;

注意

この構造体を使ってフィルタをレジストリ自己登録にする。そのコンポーネントがフィルタではないなら、このメンバ変数は NULL も可能である。詳細については、「DirectShow オブジェクトの登録方法」を参照すること。

CFactoryTemplate::CreateInstance

CFactoryTemplate クラス

そのクラスのオブジェクト作成関数を呼び出す。

構文

CUnknown *CreateInstance(
    LPUNKNOWN pUnk,
    HRESULT *phr
);

パラメータ

pUnk
集成した IUnknown インターフェイスへのポインタ。
phr
メソッドの成功・失敗を示す HRESULT 値を受け取る変数へのポインタ。

戻り値

クラス オブジェクトのインスタンスを返す。

注意

IClassFactory::CreateInstance メソッドはこのクラス メソッドを呼び出す。このメソッドは m_lpfnNew メンバ変数によってポイントされる関数を呼び出す。

CFactoryTemplate::IsClassID

CFactoryTemplate クラス

CLSID がこのクラス テンプレートと合うかどうかを確認する。

構文

BOOL IsClassID(
    REFCLSID rclsid
);

パラメータ

rclsid
CLSID を返す。

戻り値

rclsid パラメータが m_ClsID と同じ CLSID なら TRUE を返し、それ以外なら FALSE を返す。


CGenericList クラス

タイプ固有のリストを実装するクラス テンプレート。詳細については、「CBaseList」を参照すること。

宣言 : Wxlist.h

このテンプレートを使うには、リスト内のオブジェクトのタイプを定義するテンプレート引数で、タイプ CGenericList の変数を宣言する。たとえば、次の記述は CBaseFilter オブジェクトのリストを宣言している :

CGenericList<CBaseFilter> myFilterList("Filters");

便宜上次のリストタイプが定義されている :

typedef CGenericList<CBaseObject> CBaseObjectList;
typedef CGenericList<IUnknown> CBaseInterfaceList;

Public メソッド
CGenericList | コンストラクタ メソッド。
~CGenericList | デストラクタ メソッド。
GetHeadPosition | リスト内の最初の項目の位置を取得する。
GetTailPosition | リスト内の最後の項目の位置を取得する。
GetCount | リスト内の項目の数を取得する。
GetNext | 指定した位置の項目を取得し、位置を進める。
Get | 指定した位置の項目を取得する。
GetHead | リストの先頭項目を取得する。
RemoveHead | リスト内の最初の項目を削除する。
RemoveTail | リスト内の最後の項目を削除する。
Remove | 指定した位置の項目を削除する。
AddBefore | 指定した位置の前に項目かリストを挿入する。
AddAfter | 指定した位置の後に項目かリストを挿入する。
AddHead | リストの先頭に項目かリストを追加する。
AddTail | 項目の末尾に項目かリストを付け加える。
Find | 指定した項目を保持する最初の位置を取得する。

CGenericList::AddAfter

CGenericList クラス

指定した位置の後に項目かリストを挿入する。

構文

POSITION AddAfter(
    POSITION p,
    OBJECT *pObj
);

パラメータ

p
その後に項目を追加する位置。p が NULL なら、メソッドは項目をリストの先頭に追加する。
pObj
タイプ OBJECT (テンプレート タイプ) のオブジェクトへのポインタ。

戻り値

挿入された項目の位置の ID を返す。

構文

BOOL AddAfter(
    POSITION pos,
    CGenericList<OBJECT> *pList
);

パラメータ

pos
その後に項目を追加する位置。
pList
挿入するリストへのポインタ。

戻り値

成功なら TRUE を、それ以外なら FALSE を返す。

CGenericList::AddBefore

CGenericList クラス

指定した位置の前に項目かリストを挿入する。

構文

POSITION AddBefore(
    POSITION p,
    OBJECT *pObj
);

パラメータ

p
その前に項目を追加する位置。p が NULL なら、メソッドは項目をリストの末尾に追加する。
pObj
タイプ OBJECT (テンプレート タイプ) のオブジェクトへのポインタ。

戻り値

挿入された項目の位置の ID を返す。

構文

BOOL AddBefore(
    POSITION pos,
    CGenericList<OBJECT> *pList
);

パラメータ

pos
その前にリストを挿入する位置。
pList
挿入するリストへのポインタ。

戻り値

成功なら TRUE を、それ以外なら FALSE を返す。

CGenericList::AddHead

CGenericList クラス

リストの先頭に項目かリストを追加する。

構文

POSITION AddHead(
    OBJECT *pObj
);

パラメータ

pObj
タイプ OBJECT (テンプレート タイプ) のオブジェクトへのポインタ。

戻り値

新しい先頭位置を示す POSITION 値を返す。メソッドが失敗すると、戻り値は NULL となる。

構文

BOOL AddHead(
    CGenericList<OBJECT> *pList
);

パラメータ

pList
追加する項目リストへのポインタ。

戻り値

成功なら TRUE を、それ以外なら FALSE を返す。

CGenericList::AddTail

CGenericList クラス

項目の末尾に項目かリストを付け加える。

構文

POSITION AddTail(
    OBJECT *pObj
);

パラメータ

pObj
タイプ OBJECT (テンプレート タイプ) のオブジェクトへのポインタ。

戻り値

新しい末尾位置の POSITION 値を返す。 メソッドが失敗すると、戻り値は NULL となる。

構文

BOOL AddTail(
    CGenericList<OBJECT> *pList
);

パラメータ

pList
付け加えるリストへのポインタ。

戻り値

成功なら TRUE を、それ以外なら FALSE を返す。

CGenericList::CGenericList

CGenericList クラス

コンストラクタ メソッド。

構文

CGenericList(
    TCHAR *pName,
    INT iItems,
    BOOL bLock,
    BOOL bAlert
);

CGenericList(
    TCHAR *pName
);

パラメータ

pName
リスト名へのポインタ。
iItems
ノードキャッシュのサイズ。
bLock
未使用。
bAlert
未使用。

注意

効率のため、CGenericList クラスはリストノードのキャッシュを維持する。リストが保持するおおよその項目数が分かっているのなら、コンストラクタの第 1 バージョンを使用するべきである。第 2 バージョンはデフォルトのキャッシュ サイズを使用する。

CGenericList::~CGenericList

CGenericList クラス

デストラクタ メソッド。

構文

CGenericList(void);

CGenericList::Find

CGenericList クラス

指定した項目を保持する最初の位置を取得する。

構文

POSITION Find(
    OBJECT *pObj
);

パラメータ

pObj
タイプ OBJECT (テンプレート タイプ) のオブジェクトへのポインタ。

戻り値

POSITION 値を返す、リストにその項目がなければ NULL を返す。

CGenericList::Get

CGenericList クラス

指定した位置の項目を取得する。

構文

OBJECT *Get(
    POSITION pos
);

パラメータ

pos
取得すべき項目の位置 ID。

戻り値

Returns a タイプ OBJECT (テンプレート タイプ) のオブジェクトへのポインタ。

注意

pos が NULL なら、メソッドは NULL を返す。

CGenericList::GetCount

CGenericList クラス

リスト内の項目の数を取得する。

構文

int GetCount(void);

戻り値

リスト内の項目数を返す。

CGenericList::GetHead

CGenericList クラス

リストの先頭項目を取得する。

構文

OBJECT GetHead(void);

戻り値

Returns a タイプ OBJECT (テンプレート タイプ) のオブジェクトへのポインタ。

CGenericList::GetHeadPosition

CGenericList クラス

リスト内の最初の項目の位置を取得する。

構文

POSITION GetHeadPosition(void);

戻り値

POSITION 値を返す、リストがカラなら NULL を返す。

CGenericList::GetNext

CGenericList クラス

指定した位置の項目を取得し、位置を進める。

構文

OBJECT *GetNext(
    POSITION& rp
);

パラメータ

rp
POSITION 値への参照。

戻り値

タイプ OBJECT (テンプレート タイプ) のオブジェクトへのポインタ。

注意

このメソッドは位置 ID を次の位置に進める。位置 ID がリストの末尾を越したなら、メソッドは NULL を設定する。

rp が NULL なら、メソッドは NULL を返す。

CGenericList::GetTailPosition

CGenericList クラス

リスト内の最後の項目の位置を取得する。

構文

POSITION GetTailPosition(void);

戻り値

POSITION 値を返す、リストがカラなら NULL を返す。

CGenericList::Remove

CGenericList クラス

指定した位置の項目を削除する。

構文

OBJECT *Remove(
    POSITION pos
    );

パラメータ

pos
削除すべき項目を示す POSITION 値。

戻り値

タイプ OBJECT (テンプレート タイプ) のオブジェクトへのポインタ。

注意

このメソッドはリストからノードを削除するが、そのノードに含まれる項目は削除しない。

rp が NULL なら、メソッドは NULL を返す。

CGenericList::RemoveHead

CGenericList クラス

リスト内の最初の項目を削除する。

構文

OBJECT *RemoveHead(void);

戻り値

タイプ OBJECT (テンプレート タイプ) のオブジェクトへのポインタ、リストがカラなら NULL を返す。

注意

このメソッドはリストノードを削除するが、ノードに含まれる項目は削除しない。

CGenericList::RemoveTail

CGenericList クラス

リスト内の最後の項目を削除する。

構文

OBJECT *RemoveTail(void);

戻り値

タイプ OBJECT (テンプレート タイプ) のオブジェクトへのポインタ、リストがカラなら NULL を返す。

注意

このメソッドはリストノードを削除するが、ノードに含まれる項目は削除しない。


CImageAllocator クラス

CImageAllocator クラスは、共有メモリでサンプル バッファを割り当てる CBaseAllocator クラスを継承する。ブロックの数、サイズ、およびアラインメントは、接続された出力ピンが CImageAllocator::SetProperties (IMemAllocator::SetProperties を実装する) を呼び出したときに決定される。共有メモリ ブロックは、それ以降の Microsoft® Win32® CreateDIBSection 関数の呼び出しで使用される。出力ピンはこれらのバッファにデータを格納することができ、このバッファは BitBlt を使用して GDI に渡される。

プロテクト データ メンバ

m_pFilter | このオブジェクトを所有するフィルタ。
m_pMediaType | 現在のメディア タイプ フォーマット。

メンバ関数

Alloc | CreateDIBSection を使用してサンプルを割り当てる。
CheckSizes | アロケータの条件をチェックする。
CImageAllocator | CImageAllocator オブジェクトを作成する。
CreateDIB | デバイスに依存しないビットマップ (DIB) を作成する。
Free | 割り当てられたすべてのサンプルのリソースを解放して削除する。
NotifyMediaType | 合意されたメディア タイプをアロケータに通知する。

オーバーライド可能なメンバ関数

CreateImageSample サンプルを作成する。

実装される INonDelegatingUnknown メソッド

NonDelegatingAddRef | インターフェイスの参照カウントをインクリメントする。
NonDelegatingRelease | インターフェイスの参照カウントをデクリメントする。

実装される IMemAllocator メソッド

SetProperties アロケータのバッファリングの条件を指定する。

CImageAllocator::Alloc

CImageAllocator クラス

CreateDIBSection に基づいてイメージ サンプルを作成する。

構文

HRESULT Alloc(void);

戻り値

HRESULT 値を返す。

注意

フィルタは、CImageAllocator::SetProperties メンバ関数を使用して、必要なバッファのサイズおよび数を定義する。このアロケータが派生したベース アロケータ クラスは、実際にメモリをコミットする必要があるときに、この内部仮想メンバ関数を呼び出す。このアロケータは、作成する各サンプルについて、Microsoft Win32 CreateDIBSection 関数を使用して DIBSECTION オブジェクトを作成する。この呼び出しから取得した情報を使用し、バッファのポインタおよび長さを渡して仮想メンバ関数 CreateImageSample を呼び出す。イメージ サンプルの作成に成功すると、その他の情報の中から、DIBSECTION 構造体を使ってイメージ サンプルを初期化する。

これはプロテクト メンバ関数である。

CImageAllocator::CheckSizes

CImageAllocator クラス

必要なバッファリングのプロパティをチェックする内部メンバ関数。

構文

HRESULT CheckSizes(
  ALLOCATOR_PROPERTIES *pRequest
  );

パラメータ

pRequest
要求されたアロケータのプロパティへのポインタ。

戻り値

HRESULT 値を返す。

注意

イメージ アロケータは、Microsoft Win32 CreateDIBSection 関数を使用してサンプルを割り当てる。CreateDIBSection 関数は、必要なビットマップが記述された BITMAPINFO 構造体へのポインタを入力として受け入れる。ビットマップのサイズは、ビデオの BITMAPINFO 構造体に応じて固定されるので、これよりも大きいバッファをアロケータに要求しても受け付けられない。したがって、このメンバ関数は、要求されたサイズがビットマップのサイズよりも大きくならないように、要求されたサイズを調整する。要求されたサイズがビットマップのサイズよりも小さい場合は、E_INVALIDARG を返す。

これはプロテクト メンバ関数である。

CImageAllocator::CImageAllocator

CImageAllocator クラス

CImageAllocator オブジェクトを作成する。

構文

CImageAllocator(
  CBaseFilter *pFilter,
  TCHAR *pName,
  HRESULT *phr
  );

パラメータ

pFilter
所有するフィルタ オブジェクトへのポインタ。
pName
デバッグ専用の文字列の記述へのポインタ。
phr
COM 戻りコードへのポインタ。

戻り値

戻り値なし。

注意

CImageAllocator、CImageSample、および CDrawImage クラスは、すべて密接に関連している。イメージ アロケータが使用するバッファは、Microsoft Win32 CreateDIBSection 関数を使用して作成される。次に、アロケータは CImageSample クラスに基づいて独自のサンプルを作成する。イメージ サンプルは、バッファ ポインタとその長さを使って初期化される。サンプルは、CreateDIBSection の呼び出しから取得されたさまざまな情報を保持する構造体 (DIBDATA 構造体) にも渡される。

これらのサンプルを描画オブジェクトに渡すことができる。描画オブジェクトは、サンプルのプライベート フォーマット、およびサンプルから DIBDATA 構造体を取得する方法を認識している。描画オブジェクトは、この情報を取得した後、サンプルに含まれるイメージを描画するときに、DIBDATA 構造体に格納されたビットマップ ハンドルを GDI に渡すことができる。描画時にバッファ ポインタ (サンプルが CImageSample ではない場合に使用される) ではなく、サンプルから取得したビットマップ ハンドルを使用することによって、パフォーマンスが若干向上する。

これはプロテクト メンバ関数である。

CImageAllocator::CreateDIB

CImageAllocator クラス

Win32 CreateDIBSection 関数を呼び出して、デバイスに依存しないビットマップ (DIB) を作成する。

構文

HRESULT CreateDIB(
  LONG InSize,
  DIBDATA &DibData
  );

パラメータ

InSize
必要なビットマップのサイズ。
DibData
詳細を格納する構造体。

戻り値

HRESULT 値を返す。

注意

これはプロテクト メンバ関数である。

CImageAllocator::CreateImageSample

CImageAllocator クラス

CImageSample オブジェクトを作成する。

構文

virtual CImageSample *CreateImageSample(
  LPBYTE pData,
  LONG Length
  );

パラメータ

pData
サンプルが処理するデータ バッファへのポインタ。
Length
関連付けられたバッファの長さ。

戻り値

新しい CImageSample サンプル オブジェクトを返す。

注意

この仮想メンバ関数は、アロケータの実際のサンプルを作成する。サンプルには、データ バッファと格納する長さが渡される。IMediaSample::GetPointer を使用して、サンプルに追加のバッファを要求すると、このポインタが返される。これが別の仮想メンバ関数に分割されている主な理由は、CImageAllocator の派生クラスが CImageSample からもクラスを派生させて、サンプルを作成するための場所を確保できるようにするためである。

これはプロテクト メンバ関数である。

CImageAllocator::Free

CImageAllocator クラス

サンプルを削除し、そのリソースを解放する。

構文

void Free(void);

戻り値

戻り値なし。

注意

ベース アロケータは、このアロケータをデコミットするときに、この内部仮想メンバ関数を呼び出す。

これはプロテクト メンバ関数である。

CImageAllocator::NonDelegatingAddRef

CImageAllocator クラス

所有するフィルタの参照カウントをインクリメントする。

構文

HRESULT NonDelegatingAddRef(void);

戻り値

HRESULT 値を返す。

注意

アロケータは、アロケータを作成するフィルタとは概念的に独立したオブジェクトである。ただし、イメージ アロケータは、アロケータを作成したフィルタに依存して、接続されたメディア タイプなどの追加情報を提供する。したがって、アロケータはそれ自体の NonDelegatingQueryInterface 関数を処理するが、すべての参照カウントを所有するフィルタに委任する。このため、たとえば、アロケータが NonDelegatingAddRef 関数の対象となる場合、実際に参照がカウントされるのは、このアロケータを所有するフィルタである。

CImageAllocator::NonDelegatingRelease

CImageAllocator クラス

所有するフィルタの参照カウントをデクリメントする。

構文

HRESULT NonDelegatingRelease(void);

戻り値

HRESULT 値を返す。

注意

アロケータは、アロケータを作成するフィルタとは概念的に独立したオブジェクトである。ただし、イメージ アロケータは、アロケータを作成したフィルタに依存して、接続されたメディア タイプなどの追加情報を提供する。したがって、アロケータはそれ自体の NonDelegatingQueryInterface 関数を処理するが、すべての参照カウントを所有するフィルタに委任する。このため、たとえば、アロケータが解放される場合、実際に NonDelegatingRelease 関数によって解放されるのは、このアロケータを所有するフィルタである。

CImageAllocator::NotifyMediaType

CImageAllocator クラス

フィルタからアロケータにメディア タイプを渡す。

構文

void NotifyMediaType(
  CMediaType *pMediaType
  );

パラメータ

pMediaType
フィルタが確立したメディア タイプへのポインタ。

戻り値

戻り値なし。

注意

イメージ アロケータが作成するバッファは、CreateDIBSection に基づいており、この関数には、フィルタが作成する必要があるビットマップの種類を指示しなければならない。フィルタは、アロケータについてこのメンバ関数を呼び出すことによってこれを処理する。フィルタは、通常、ピンの接続時にメディア タイプについて合意した後、このメンバ関数を呼び出す。このメンバ関数に渡されるメディア タイプはポインタである。アロケータは、メディア タイプのコピーではなく、このポインタを格納する。これは、メディア タイプをコピーするには時間がかかるというパフォーマンス上の理由からである。したがって、このメンバ関数を呼び出すフィルタは、このアロケータについて次にメディア タイプを設定するか、NULL 型を指定して呼び出されるまで、メディア タイプが常に有効であることを確認する必要がある。

CImageAllocator::SetProperties

CImageAllocator クラス

サイズ、数、およびブロックのアラインメントを判断する。

構文

HRESULT SetProperties(

  ALLOCATOR_PROPERTIES *pRequest,

  ALLOCATOR_PROPERTIES *pActual

  );

パラメータ

pRequest
要求されたアロケータのプロパティへのポインタ。
pActual
実際に設定されたアロケータのプロパティへのポインタ。

戻り値

HRESULT 値を返す。

注意

pRequest パラメータには、ALLOCATOR_PROPERTIES 構造体によって指定されているカウント、数、およびアラインメントについて要求された値が、呼び出し元によって格納される。pActual パラメータには、要求に対して提供可能な最も近い値がアロケータによって格納される。このメンバ関数は、アロケータが IMemAllocator::Decommit メソッドを使用してデコミットされるまで呼び出すことができない。


CImageDisplay クラス

CImageDisplay クラスはディスプレイ フォーマットを使用してそれ自体を初期化し、ほかのオブジェクトがディスプレイ タイプを問い合わせたり、リセットできるようにする。また、ディスプレイ フォーマットをチェックしたり、GDI の呼び出しを使用して効率的にレンダリングできるビデオ フォーマットだけを受け入れるためのメンバ関数も提供する。

プロテクト データ メンバ

m_Display 現在のデバイス ディスプレイ タイプに対応する VIDEOINFO 構造体。

メンバ関数

CheckBitFields | VIDEOINFO 構造体のビット フィールドが正しいことをチェックする。
CheckHeaderValidity | BITMAPINFOHEADER 構造体が有効であるかどうかを判断する。
CheckMediaType | フィルタが出力ピンによって指定されたメディア タイプをサポートできるかどうかを判断する。
CheckPaletteHeader | VIDEOINFO 構造体のパレットが正しいかどうかを判断する。
CheckVideoType | ビデオ タイプを比較し、現在のディスプレイ モードと互換性があるかどうかを判断する。
CImageDisplay | CImageDisplay オブジェクトを作成する。
CountPrefixBits | プレフィックス ビットの数をカウントする。
CountSetBits | フィールド内で設定されたビットの合計数をカウントする。
GetBitMasks | VIDEOINFO 構造体で提供されたカラー要素のビットマスクのセットを取得する。
GetColourMask | 個々のカラー要素のマスクのセットを取得する。
GetDisplayDepth | 現在のディスプレイ モードのビット深度を取得する。
GetDisplayFormat | 現在のディスプレイ モードを表す VIDEOINFO 構造体を取得する。
IsPalettized | ディスプレイがパレットを使用するかどうかを判断する。
RefreshDisplayType | 現在のディスプレイ タイプを使用して CImageDisplay オブジェクトを更新する。
UpdateFormat | VIDEOINFO 構造体を更新して暗黙の仮定を削除する。

CImageDisplay::CheckBitFields

CImageDisplay クラス

VIDEOINFO 構造体のビット フィールドが正しいことをチェックする。

構文

BOOL CheckBitFields(
const VIDEOINFO *pInput
    );

パラメータ

pInput
チェックする VIDEOINFO 構造体へのポインタ。

戻り値

次のいずれかの値を返す。
TRUE | ビット フィールドは正しい。
FALSE | ビット フィールドにエラーが含まれている。

注意

オブジェクト全体で、カラー コンポーネントを格納するために使用できるビットマスクは最大 8 ビットであると仮定されている。このメンバ関数は、このビット カウントの仮定が実施されていることをチェックし、すべてのビット セットが連続していることも確認する。

これはプロテクト メンバ関数である。

CImageDisplay::CheckHeaderValidity

CImageDisplay クラス

BITMAPINFOHEADER 構造体が有効であるかどうかを判断する。

構文

BOOL CheckHeaderValidity(
const VIDEOINFO *pInput
    );

パラメータ

pInput
ビットマップの詳細を格納する VIDEOINFO 構造体へのポインタ。

戻り値

次のいずれかの値を返す。
TRUE | フォーマットは有効である。
FALSE | フォーマットにエラーが含まれている。

注意

BITMAPINFOHEADER 構造体は、多くの理由で拒否される場合がある。たとえば、プレーン数のエントリが 1 よりも大きいか小さい、この構造体のサイズが BITMAPINFOHEADER のサイズと等しくない、または YUV フォーマットを確認するよう指示された (このメンバ関数は RGB フォーマットのみ確認する。YUV タイプについては常に FALSE を返す) などの理由である。

CImageDisplay::CheckMediaType

CImageDisplay クラス

フィルタが出力ピンによって指定されたメディア タイプをサポートできるかどうかを判断する。

構文

HRESULT CheckMediaType(
const CMediaType *pmtIn
    );

パラメータ

pmtIn
チェックするメディア タイプへのポインタ。

戻り値

HRESULT 値を返す。

注意

このヘルパー関数を使用して、ビデオのメディア タイプを確認できる。このヘルパー関数は、メジャー タイプおよびサブタイプの GUID を調べ、フォーマット GUID が VIDEOINFO 構造体を定義していることを確認する。

CImageDisplay::CheckPaletteHeader

CImageDisplay クラス

VIDEOINFO 構造体のパレットが正しいかどうかを判断する。

構文

BOOL CheckPaletteHeader(
const VIDEOINFO *pInput
    );

パラメータ

pInput
確認する VIDEOINFO 構造体へのポインタ。

戻り値

次のいずれかの値を返す。
TRUE | パレットは正しい。
FALSE | 有効なパレットがない。

注意

フォーマットがパレットを使用しないことを指定している場合 (トゥルーカラー フォーマットなどの場合)、このメンバ関数は FALSE を返す。また、使用される (または重要である) パレット カラーの数がビデオ フォーマットで指定されている数を超えている場合も、FALSE を返す。

CImageDisplay::CheckVideoType

CImageDisplay クラス

ビデオ タイプを比較し、現在のディスプレイ モードと互換性があるかどうかを判断する。

構文

HRESULT CheckVideoType(
const VIDEOINFO *pInput
    );

パラメータ

pInput
確認する VIDEOINFO 構造体へのポインタ。

戻り値

成功した場合は NOERROR を返す。それ以外の場合は E_INVALIDARG を返す。

注意

多くのビデオ レンダリング フィルタは、指定されたフォーマットが使用できるかどうかを判断する関数を必要とする。このメンバ関数は、メディア タイプとして渡された VIDEOINFO 構造体をチェックし、メディア タイプが有効である場合は NOERROR を返す。それ以外の場合は E_INVALIDARG434 を返す。ただし、現在のディスプレイ デバイスで容易に表示できるフォーマットのみ使用できる。たとえば、16 ビット デバイスで 24 ビット イメージは使用できない。多くのディスプレイは 8 ビットのパレット化されたイメージを効率的に表示できるので、ディスプレイが 16 色 VGA でない限り、このフォーマットは常に使用できる。

CImageDisplay::CImageDisplay

CImageDisplay クラス

CImageDisplay オブジェクトを作成する。

構文

CImageDisplay(void);

戻り値

戻り値なし。

注意

CImageDisplay クラスは、現在のディスプレイ モードのフォーマットを判断する必要があるレンダラを補助する。このメンバ関数は、ディスプレイ モードを取得し、そのフォーマットを表す VIDEOINFO 構造体を作成する。このクラスは、IsPalettized および GetDisplayFormat などのメンバ関数によって、そのフォーマットをクライアントに提供する。クライアントはディスプレイ フォーマットが変更されたことを検出した (クライアントが WM_DISPLAYCHANGED メッセージを受信する) 場合、RefreshDisplayType を呼び出す必要がある。

CImageDisplay::CountPrefixBits

CImageDisplay クラス

プレフィックス ビットの数をカウントする。

構文

DWORD CountPrefixBits(
const DWORD Field
    );

パラメータ

Field
入力ビットマスク フィールド。

戻り値

戻り値なし。

注意

ビットマスクを指定すると、このヘルパー関数は、最下位に設定されているビットまで、0 のビットの数をカウントする。したがって、2 進値 00000100 の場合、このメンバ関数は 2 (10 進値) を返す。ただし、このメンバ関数は DWORD 値に対して機能するので、最下位ビットから DWORD を通って、最終ビット (0x80000000) までカウントする。ビットが見つからない場合、このメンバ関数は不可能な値 32 (10 進値) を返す。

これはプロテクト メンバ関数である。

CImageDisplay::CountSetBits

CImageDisplay クラス

フィールド内で設定されたビットの合計数をカウントする。

構文

DWORD CountSetBits(
const DWORD Field
    );

パラメータ

Field
ビット セットをカウントするフィールド。

戻り値

ビット セットの数を返す。

注意

これはプロテクト メンバ関数である。

CImageDisplay::GetBitMasks

CImageDisplay クラス

VIDEOINFO 構造体で提供されたカラー要素のビットマスクのセットを取得する。

構文

const DWORD *GetBitMasks(
const VIDEOINFO *pVideoInfo
    );

パラメータ

pVideoInfo
入力 VIDEOINFO 構造体フォーマットへのポインタ。

戻り値

戻り値なし。

注意

このメンバ関数は、RGB フォーマットについてのみ呼び出す必要がある。RGB フォーマットのピクセルあたりのビット深度は 16/32 ビットであり、赤、緑、青の個々のカラー要素のビットマスク (RGB565 の場合は 0xF800、0x07E0、および 0x001F など) を返す。RGB24 の場合、このメンバ関数は 0xFF0000、0xFF00、および 0xFF を返す。パレット化されたフォーマットの場合、このメンバ関数はすべて 0 を返す。

CImageDisplay::GetColourMask

CImageDisplay クラス

個々のカラー要素のマスクのセットを取得する。

構文

BOOL GetColourMask(
DWORD *pMaskRed,
DWORD *pMaskGreen,
DWORD *pMaskBlue
    );

パラメータ

pMaskRed
赤のマスクへのポインタ。
pMaskGreen
緑のマスクへのポインタ。
pMaskBlue
青のマスクへのポインタ。

戻り値

次のいずれかの値を返す。
TRUE | マスクが正しく格納された。
FALSE | ディスプレイで使用できるマスクがなかった。

注意

VIDEOINFO 構造体によって表されるビデオ フォーマットを指定すると、このメンバ関数はこのタイプの使用可能なカラーの範囲を取得するために使用されるマスクを返す。たとえば、24 ビット トゥルーカラー フォーマットのマスクはすべての場合で 0xFF である。16 ビット 5:6:5 ディスプレイ フォーマットは、0xF8、0xFC、および 0xF8 を使用する。したがって、RGB トリプレットを指定すると、このメンバ関数は、ビットごとの AND 演算を使用して、ディスプレイ フォーマットと互換性のあるフォーマットを検索できる。

CImageDisplay::GetDisplayDepth

CImageDisplay クラス

現在のディスプレイ モードのビット深度を取得する。

構文

WORD GetDisplayDepth(void);

戻り値

ディスプレイ上で使用されるピクセルあたりのビット数を返す。

CImageDisplay::GetDisplayFormat

CImageDisplay クラス

現在のディスプレイ モードを表す VIDEOINFO 構造体を取得する。

構文

const VIDEOINFO *GetDisplayFormat(void);

戻り値

ディスプレイ フォーマットを表す VIDEOINFO 構造体を返す。

CImageDisplay::IsPalettized

CImageDisplay クラス

ディスプレイがパレットを使用するかどうかを判断する。

構文

BOOL IsPalettized(void);

戻り値

ディスプレイがパレットを使用する場合は TRUE を返す。それ以外の場合は FALSE を返す。

CImageDisplay::RefreshDisplayType

CImageDisplay クラス

現在のディスプレイ タイプを使用して CImageDisplay オブジェクトを更新する。

構文

HRESULT RefreshDisplayType(
LPSTR szDeviceName
    );

パラメータ

szDeviceName
更新するデバイスの名前。省略した場合、このパラメータのデフォルトはメイン デバイスになる。

戻り値

成功した場合は NOERROR を返す。それ以外の場合は E_FAIL を返す。

注意

このメンバ関数は、WM_DISPLAYCHANGED メッセージを受信したときに呼び出す必要がある。

CImageDisplay::UpdateFormat

CImageDisplay クラス

VIDEOINFO 構造体を更新して暗黙の仮定を削除する。

構文

HRESULT UpdateFormat(
VIDEOINFO *pVideoInfo
    );

パラメータ

pVideoInfo
更新する VIDEOINFO 構造体へのポインタ。

戻り値

HRESULT 値を返す。現在の実装では NOERROR を返す。

注意

このメンバ関数は、特定のフィルタでの使用にのみ適している。BITMAPINFO 構造体には、明確に指定されていない特定のフィールドが含まれている。具体的には、パレットについて指定されるカラーの数を 0 にすることができ、この場合、そのフォーマット タイプの最大値として定義される。このメンバ関数はこれらのフィールドを更新し、その内容が明示的になるようにする。


CImagePalette クラス

CImagePalette クラスは、パレットを作成および管理しなければならないイメージ レンダラ用の特殊なクラスである。このクラスを使用して、フォーマット ブロックに VIDEOINFO 構造体を格納するメディア フォーマットからパレット ハンドルを作成することができる。パフォーマンスを最大化するために、このクラスは同一パレット (現在のシステム パレットと同じパレット) であるパレットを作成し、更新の前に比較して、実際に必要な場合にのみパレットを変更する。

プロテクト データ メンバ

m_hPalette | このオブジェクトによって所有されるパレット ハンドル。
m_pBaseWindow | パレットが実現されるウィンドウ。
m_pDrawImage | 描画を実行するオブジェクト。
m_pMediaFilter | イベントの送信先のメディア フィルタ。

メンバ関数

CImagePalette | CImagePalette オブジェクトを作成する。
CopyPalette | YUV またはトゥルーカラーの VIDEOINFOHEADER 構造体からパレット化された VIDEOINFOHEADER 構造体にパレットをコピーする。
MakeIdentityPalette | パレット エントリを同一パレットにする。
MakePalette | 指定されたビデオ イメージからカラー パレットを取得する。
PreparePalette | パレットの更新および作成のエントリ ポイントを指定する。
RemovePalette | 割り当てられたすべてのパレット リソースを解放する。
ShouldUpdate | パレットを動的に更新するための内部ヘルパー メンバ関数を指定する。

CImagePalette::CImagePalette

CImagePalette クラス

CImagePalette オブジェクトを作成する。

構文

CImagePalette(
CBaseFilter *pBaseFilter,
CBaseWindow *pBaseWindow,
CDrawImage *pDrawImage
);

パラメータ

pBaseFilter
このクラスを所有するフィルタへのポインタ。
pBaseWindow
パレットを実現するウィンドウへのポインタ。
pDrawImage
このパレットを使用して描画するオブジェクトへのポインタ。

戻り値

戻り値なし。

注意

このクラスは、ウィンドウ パレットの作成、管理、および削除を処理する。このクラスは、パレットに関連するほかの多くのオブジェクトに渡される。このクラスは、新しいカラーのセットが現在のセットと異なる場合にのみ、要求されたパレットの変更を実行するように最適化されている。パレットの変更は時間がかかる処理なので、これはパフォーマンス上の最適化である。

このコンストラクタには、所有するフィルタ (pBaseFilter) が渡される。これは有効なポインタでなければならない。このクラスが実際にパレットを作成する場合、このクラスは、所有するフィルタに EC_PALETTE_CHANGED メッセージをフィルタ グラフ マネージャに送信するよう指示する。このコンストラクタには、さらに 2 つのオブジェクト ポインタが渡される。pBaseWindow が Null ではない場合、レンダラが新しいパレットを作成するときに、このクラスは自動的にそのパレットをこのウィンドウにインストールする。パレットを削除するように指示された場合、このクラスはベース ウィンドウからパレットを削除し、その代わりに標準 VGA パレットをインストールする。

このコンストラクタには、CDrawImage クラスから派生した描画オブジェクトを渡すこともできる。この描画オブジェクトが NULL 以外の場合、新しいパレットを作成するときに、このクラスは描画オブジェクトにパレットが変更されたことを通知する。これは、通常、ウィンドウ オブジェクトと組み合わせて使用される。これによって、パレットが変更されると描画オブジェクトに通知され、描画オブジェクトは、CreateDIBSection を使用して作成された、そのオブジェクトが所有するサンプルを更新できる。これはサンプルの内部カラー テーブルを更新しなければならないことがあるためである。

CImagePalette::CopyPalette

CImagePalette クラス

YUV またはトゥルーカラーの VIDEOINFOHEADER 構造体からパレット化された VIDEOINFOHEADER 構造体にパレットをコピーする。

構文

HRESULT CopyPalette(
const CMediaType *pSrc,
const CMediaType *pDest
);

パラメータ

pSrc
コピー元メディア タイプへのポインタ。
pDest
コピー先メディア タイプへのポインタ。

戻り値

成功した場合は NOERROR を返す。使用できるパレットがない場合は S_FALSE を返す。

注意

このメンバ関数は、DirectDraw® サンプルについてパレットを変更したときに使用される。レンダラへのコピー元になるフィルタは、パレットを任意のバッファにアタッチして、新しい VIDEOINFOHEADER フォーマットとしてレンダラに渡すことができる。次に、レンダラは CopyPalette を呼び出して、そのフォーマットから新しいパレットを作成し、パレット カラーを新しい接続タイプにコピーする。

CImagePalette::MakeIdentityPalette

CImagePalette クラス

PALETTEENTRY 構造体を変更し、同一パレットを作成する。

構文

HRESULT MakeIdentityPalette(
PALETTEENTRY *pEntry,
INT iColours,
LPSTR szDevice
);

パラメータ

pEntry
予測されるパレット カラーの配列へのポインタ。
iColours
配列のカラーの数。
szDevice
転送先デバイスの名前を含む文字列へのポインタ。省略した場合、このパラメータのデフォルトはメイン デバイスになる。

戻り値

成功した場合は NOERROR を返す。それ以外の場合は S_FALSE を返す。

注意

パレットがウィンドウにインストールされると、GDI は可能であれば要求されたカラーを圧縮する。したがって、たとえば、配列に黒のエントリが 5 つ含まれる場合、これらは 1 つのパレット エントリに圧縮される。これは、多くのアプリケーションで便利である。ただし、ビデオを描画する場合、これによって GDI は指定されたイメージ内のピクセルを圧縮されたパレットにマップしなければならない。この場合、パフォーマンスは大幅に低下する。

したがって、指定された PALETTEENTRY フィールドを調整して、カラーが圧縮されないようにしなければならない。これは、イメージを表示するウィンドウがフォアグラウンド フォーカスを持つ場合に、このオブジェクトによって作成されたパレットが、ディスプレイ デバイスで選択されたパレット (同一パレット) に直接マップすることを意味する。

CImagePalette::MakePalette

CImagePalette クラス

指定されたビデオ イメージからカラー パレットを取得する。

構文

HPALETTE MakePalette(
const VIDEOINFOHEADER *pVideoInfo,
LPSTR szDevice
);

パラメータ

pVideoInfo
必要なパレット カラーのコンテナへのポインタ。
szDevice
転送先デバイスの名前を含む文字列へのポインタ。省略した場合、このパラメータのデフォルトはメイン デバイスになる。

戻り値

新しいパレットのハンドルを返す。失敗した場合は NULL を返す。

CImagePalette::PreparePalette

CImagePalette クラス

パレットの作成およびインストールのエントリ ポイントを指定する。

構文

HRESULT PreparePalette(
const CMediaType *pmtNew,
const CMediaType *pmtOld,
LPSTR szDevice
);

パラメータ

pmtNew
新しいパレット情報を保持するメディア タイプへのポインタ。
pmtOld
古いパレット情報を保持するメディア タイプへのポインタ。
szDevice
転送先デバイスの名前を含む文字列へのポインタ。省略した場合、このパラメータのデフォルトはメイン デバイスになる。

戻り値

HRESULT 値を返す。

注意

これは、新しいパレットを作成するためのメイン エントリ ポイントである。このメンバ関数は、要求されたパレット カラーが変更されていないという状況を検出しようとする。パレット カラーが変更されていない場合は、新しいパレットを作成する必要がない。古いメディア タイプを使用して、カラーが変更されたかどうかを判断する。また、オプションでウィンドウへのパレットのインストール (指定された場合) や、フィルタ グラフ マネージャへのパレットの変更の通知 (このために、コンストラクタに渡されたフィルタを使用する) を処理する。最後に、描画オブジェクトへのパレットの変更の通知を処理する。これも、コンストラクタに描画オブジェクトが渡されたかどうかに応じてオプションである。

CImagePalette::RemovePalette

CImagePalette クラス

以前に作成したパレットを削除する。

構文

HRESULT RemovePalette(void);

戻り値

HRESULT 値を返す。現在の実装では NOERROR を返す。

CImagePalette::ShouldUpdate

CImagePalette クラス

新しいパレットを作成する必要があるかどうかを判断する。

構文

BOOL ShouldUpdate(
const VIDEOINFOHEADER *pNewInfo,
const VIDEOINFOHEADER *pOldInfo
);

パラメータ

pNewInfo
新しいカラーのセットを格納する VIDEOINFOHEADER 構造体へのポインタ。
pOldInfo
古いカラーのセットを格納する VIDEOINFOHEADER 構造体へのポインタ。

戻り値

次のいずれかの値を返す。
TRUE | 新しいパレットが必要である。
FALSE | 既存のパレットを使用できる。

注意

この関数を使用して、新しいパレットを作成する必要があるかどうかをテストする。元のタイプがパレットを使用せず、新しいタイプがパレットを使用する場合 (またはその逆の場合)、このメソッドは TRUE を返す。いずれのフォーマットもパレットを使用しない場合、このメソッドは FALSE を返す。両方のフォーマットがパレットを使用する場合はカラーが比較され、一致する場合、このメソッドは FALSE を返す。


CImageSample クラス

CImageSample クラスは CMediaSample を継承し、コンストラクタをオーバーライドして、DIBDATA 構造体を使用してそれ自体を初期化する。レンダラが独自のアロケータを使用している場合、レンダラはそのサンプル用にこのクラスを使用する。したがって、必要な DIBSECTION 構造体の情報を取得して、レンダリングする HBITMAP データを取得できる。

プロテクト データ メンバ

m_bInit | DIBSECTION 構造体の情報が初期化されているかどうかを判断するためのフラグ。
m_DibData | サンプルの DIBSECTION 構造体に関する情報。

メンバ関数

CImageSample | CImageSample オブジェクトを作成する。
GetDIBData | サンプルについて格納された DIBSECTION 構造体の情報を取得する。
SetDIBData | サンプルについて格納される DIBSECTION 情報を設定する。

CImageSample::CImageSample

CImageSample クラス

CImageSample オブジェクトを作成する。

構文

CImageSample(
  CBaseAllocator *pAllocator,
  TCHAR *pName,
  HRESULT *phr,
  LPBYTE pBuffer,
  LONG length
  );

パラメータ

pAllocator
サンプルが属するベース アロケータへのポインタ。
pName
デバッグ専用の文字列の記述へのポインタ。
phr
COM 戻りコードへのポインタ。
pBuffer
イメージ バッファへのポインタ。
length
イメージ バッファの長さ。

戻り値

戻り値なし。

注意

CImageAllocator、CImageSample、および CDrawImage クラスは、すべて密接に関連している。イメージ アロケータが使用するバッファは、Microsoft® Win32® CreateDIBSection 関数を使用して作成される。次に、アロケータは CImageSample クラスに基づいて独自のサンプルを作成する。イメージ サンプルは、バッファ ポインタとその長さを使って初期化される。サンプルは、CreateDIBSection の呼び出しから取得されたさまざまな情報を保持する構造体 (DIBDATA 構造体) にも渡される。

これらのサンプルを描画オブジェクトに渡すことができる。描画オブジェクトは、サンプルのプライベート フォーマット、およびサンプルから DIBDATA 構造体を取得する方法を認識している。描画オブジェクトは、この情報を取得した後、サンプルに含まれるイメージを描画するときに、DIBDATA 構造体に格納されたビットマップ ハンドルを GDI に渡すことができる。描画時にバッファ ポインタ (サンプルが CImageSample ではない場合に使用される) ではなく、サンプルから取得したビットマップ ハンドルを使用することによって、パフォーマンスが若干向上する。

CImageSample::GetDIBData

CImageSample クラス

サンプルによって保持されている DIBDATA 構造体を取得する。

構文

DIBDATA *GetDIBData(void);

戻り値

DIBDATA 構造体を返す。

CImageSample::SetDIBData

CImageSample クラス

サンプルが保持する必要がある DIBDATA 構造体を設定する。

構文

void SetDIBData(
  DIBDATA *pDibData
  );

パラメータ

pDibData
新しい DIBDATA 構造体へのポインタ。

戻り値

戻り値なし。


CLoadDirectDraw クラス

Microsoft® DirectShow® は複数のプラットフォームで機能しなければならない。特に、DirectDraw® 機能を持たない Microsoft Windows NT® 3.51 上でも実行される。したがって、フィルタは DirectDraw ライブラリに静的にリンクできない。このプラットフォームへの依存を容易に処理するために、このクラスはライブラリのロードとアンロード、および初期 IDirectDraw インターフェイスの作成を管理する。

メンバ関数

CLoadDirectDraw | CLoadDirectDraw オブジェクトを作成する。
GetDirectDraw | IDirectDraw インターフェイスへのポインタを取得する。
IsDirectDrawLoaded | DirectDraw がロードされていることを確認する。
IsDirectDrawVersion1 | 現在のシステムにインストールされている DirectDraw のバージョンをチェックする。
LoadDirectDraw | DirectDraw ライブラリをロードして初期化する。
ReleaseDirectDraw | IDirectDraw インターフェイスを解放する。

CLoadDirectDraw::CLoadDirectDraw

CLoadDirectDraw クラス

CLoadDirectDraw オブジェクトを作成する。

構文

CLoadDirectDraw(void);

戻り値

戻り値なし。

CLoadDirectDraw::GetDirectDraw

CLoadDirectDraw クラス

DirectDraw インターフェイスを取得する。

構文

LPDIRECTDRAW GetDirectDraw(void);

戻り値

IDirectDraw インターフェイスへのポインタを返す。

注意

このメンバ関数を呼び出す前に CLoadDirectDraw::LoadDirectDraw を呼び出し、処理が終了してインターフェイスを解放するには CLoadDirectDraw::ReleaseDirectDraw メンバ関数を呼び出す。

CLoadDirectDraw::IsDirectDrawLoaded

CLoadDirectDraw クラス

このオブジェクトが DirectDraw をロードしたことを確認する。

構文

HRESULT IsDirectDrawLoaded(void);

戻り値

ロードされている場合は、S_OK を返す。それ以外の場合は、S_FALSE を返す。

CLoadDirectDraw::IsDirectDrawVersion1

CLoadDirectDraw クラス

現在のシステムにインストールされている DirectDraw のバージョンをチェックする。

構文

BOOL IsDirectDrawVersion1(void);

戻り値

インストールされている DirectDraw のバージョンが IDirectDraw2 インターフェイスをサポートしていない場合は TRUE を返す。m_pDirectDraw データ メンバが NULL の場合、またはインストールされている DirectDraw のバージョンが IDirectDraw2 をサポートしている場合は FALSE を返す。

注意

ビデオ レンダラは、インストールされているどのバージョンの DirectDraw が IDirectDraw2 インターフェイスによってサポートされるフルスクリーン再生などの特定のタスクを実行するかを認識していなければならない。

CLoadDirectDraw::LoadDirectDraw

CLoadDirectDraw クラス

指定された領域に DirectDraw ライブラリをロードして初期化する。

構文

HRESULT LoadDirectDraw(
  LPSTR szDevice
  );

パラメータ

szDevice
このパラメータはオプションである。このメソッドはベース描画領域に DirectDraw をロードする。

戻り値

DirectDraw が正しくロードされた場合は S_OK を返す。それ以外の場合は E_NOINTERFACE を返す。

注意

DirectDraw は常に使用できるわけではないので、アプリケーションはライブラリに静的にリンクできない。したがって、このメンバ関数はライブラリをロードし、関数のエントリ ポイント アドレスを取得し、関数を呼び出してドライバ オブジェクトを作成する。このメンバ関数は、IDirectDraw インターフェイスを取得する CLoadDirectDraw::GetDirectDraw を呼び出す前に呼び出す。

CLoadDirectDraw::ReleaseDirectDraw

CLoadDirectDraw クラス

IDirectDraw インターフェイスを解放する。

構文

void ReleaseDirectDraw(void);

戻り値

戻り値なし。

注意

このメンバ関数は、以前にロードされた IDirectDraw インターフェイスを解放するために呼び出される。すべての参照カウントが解放された場合にのみこれを呼び出す。


CMediaControl クラス

CMediaControl クラスは、デュアル インターフェイス IMediaControl の IDispatch メソッドの基底クラスの処理を提供する。このクラスは、IMediaControl インターフェイスのプロパティおよびメソッドを純粋仮想のままにしておく。

通常、IMediaControl インターフェイスを実装するオブジェクトはフィルタ グラフ マネージャだけである。フィルタは、IBaseFilter から継承した IMediaFilter インターフェイスを実装して、フィルタ グラフ マネージャからの制御コマンドを受け取る。したがって、このクラス ライブラリを使用するのはフィルタ開発者に限定される。

CMediaControl::GetIDsOfNames、CMediaControl::GetTypeInfo、CMediaControl::GetTypeInfoCount、および CMediaControl::Invoke メンバ関数は、IDispatch メソッドの標準的な実装で、CBaseDispatch クラス (およびタイプ ライブラリ) を使用してコマンドを解析し、IMediaControl インターフェイスの純粋仮想メソッドに渡す。

control.odl で定義される IMediaControl は、純粋仮想のままである。

メンバ関数

CMediaControl CMediaControl オブジェクトを作成する。

実装される INonDelegatingUnknown メソッド

NonDelegatingQueryInterface 指定された参照カウントのインターフェイスを返す。

実装される IDispatch メソッド

GetIDsOfNames | 単一のメンバおよびオプションのパラメータのセットを、対応する整数のディスパッチ識別子 (DISPID) にマップする。この識別子は、以降の CMediaControl::Invoke メソッドの呼び出しで使用できる。
GetTypeInfo | タイプ情報オブジェクトを取得する。インターフェイスのタイプ情報を取得できる。
GetTypeInfoCount | オブジェクトによって提供されるタイプ情報インターフェイスの数を取得する。
Invoke | オブジェクトによって公開されるプロパティおよびメソッドへのアクセスを提供する。

CMediaControl::CMediaControl

CMediaControl クラス

CMediaControl オブジェクトを作成する。

構文

CMediaControl(
const TCHAR *pName,
LPUNKNOWN pUnk
    );

パラメータ

pName
デバッグのために使用されるオブジェクトの名前へのポインタ。
pUnk
このオブジェクトの所有者へのポインタ。

戻り値

戻り値なし。

注意

スタティック メモリに pName パラメータを割り当てる。この名前は、オブジェクトの作成および削除を行うデバッギング端末上に現れる。

CMediaControl::GetIDsOfNames

CMediaControl クラス

単一のメンバ関数およびオプションのパラメータのセットを、対応する整数のディスパッチ識別子 (DISPID) にマップする。この識別子は、以降の CMediaControl::Invoke メンバ関数の呼び出しで使用できる。

構文

HRESULT GetIDsOfNames(
REFIID riid,
OLECHAR **rgszNames,
UINT cNames,
LCID lcid,
DISPID *rgdispid
    );

パラメータ

riid
参照識別子。将来的な使用のために予約されている。NULL でなければならない。
rgszNames
渡されたマップする名前の配列へのポインタのアドレス。
cNames
マップされる名前の数。
lcid
名前を解釈するロケール コンテキスト。
rgdispid
呼び出し元割り当て済み配列へのポインタ。各要素には、rgszNames 配列に渡される名前の 1 つに対応する ID が含まれる。最初の要素はメンバの名前を表し、以降の要素は各メンバのパラメータを表す。

戻り値

次のいずれかの値を返す。
DISP_E_UNKNOWN_CLSID | CLSID が認識されなかった。
DISP_E_UNKNOWNNAME | 1 つ以上の名前が不明だった。返された DISPID には、不明な名前に対応する各エントリの DISPID_UNKNOWN が含まれる。
E_OUTOFMEMORY | メモリ不足。
S_OK | 成功。

CMediaControl::GetTypeInfo

CMediaControl クラス

タイプ情報オブジェクトを取得する。インターフェイスのタイプ情報を取得できる。

構文

HRESULT GetTypeInfo(
UINT itinfo,
LCID lcid,
ITypeInfo **pptinfo
    );

パラメータ

itinfo
返されるタイプ情報。ゼロを渡して、IDispatch 実装のタイプ情報を取得する。
lcid
タイプ情報のロケール ID。ローカライズされたメンバ名をサポートするクラスの場合、オブジェクトは異なる言語の異なるタイプ情報を返すことができる場合がある。ローカライズされたメンバ名をサポートしないクラスの場合、このパラメータは無視することができる。
pptinfo
要求されたタイプ情報オブジェクトへのポインタのアドレス。

戻り値

pptinfo が無効な場合は、E_POINTER を返す。itinfo がゼロ以外の場合は、TYPE_E_ELEMENTNOTFOUND を返す。成功した場合は、S_OK を返す。それ以外の場合は、タイプを取得するための呼び出しの 1 つから HRESULT を返す。HRESULT はエラーを示し、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
S_OK または NOERROR | 成功。

CMediaControl::GetTypeInfoCount

CMediaControl クラス

オブジェクトによって提供されるタイプ情報インターフェイスの数を取得する。

構文

HRESULT GetTypeInfoCount(
UINT *pctinfo
    );

パラメータ

pctinfo
オブジェクトが提供するタイプ情報インターフェイスの数へのポインタ。オブジェクトがタイプ情報を提供した場合、この数は 1 である。それ以外の場合は、0 である。

戻り値

pctinfo が無効な場合は、E_POINTER を返す。それ以外の場合は、S_OK を返す。

CMediaControl::Invoke

CMediaControl クラス

オブジェクトによって公開されるプロパティおよびメソッドへのアクセスを提供する。

構文

HRESULT Invoke(
DISPID dispidMember,
REFIID riid,
LCID lcid,
WORD wFlags,
DISPPARAMS *pdispparams,
VARIANT *pvarResult,
EXCEPINFO *pexcepinfo,
UINT *puArgErr
    );

パラメータ

dispidMember
メンバの識別子。ディスパッチ識別子を取得するには、CMediaControl::GetIDsOfNames またはオブジェクトのドキュメントを使用する。
riid
将来的な使用のために予約されている。IID_NULL でなければならない。
lcid
引数を解釈するロケール コンテキスト。
wFlags
CMediaControl::Invoke 呼び出しのコンテキストを記述するフラグ。
pdispparams
引数の配列、名前付き引数の引数ディスパッチ ID の配列、および配列内の要素の数を含む構造体へのポインタ。
pvarResult
結果が格納されるポインタ、または呼び出し元が結果を求めていない場合は NULL。
pexcepinfo
例外情報を含む構造体へのポインタ。
puArgErr
DISPPARAMS 構造体の rgvarg 配列内で、エラーがある最初の引数のインデックスへのポインタ。DISPPARAMS の詳細については、Platform SDK を参照すること。

戻り値

riid が IID_NULL 以外の場合は、DISP_E_UNKNOWNINTERFACE を返す。呼び出しが失敗した場合は、CMediaControl::GetTypeInfo からエラー コードの 1 つを返す。それ以外の場合は、IDispatch::Invoke への呼び出しから HRESULT を返す。

CMediaControl::NonDelegatingQueryInterface

CMediaControl クラス

指定された参照カウントのインターフェイスを取得する。

構文

HRESULT NonDelegatingQueryInterface(
REFIID riid,
void **ppv
    );

パラメータ

riid
参照識別子。
ppv
インターフェイスへのポインタのアドレス。

戻り値

ppv が無効な場合は、E_POINTER を返す。クエリが成功した場合は NOERROR、失敗した場合は E_NOINTERFACE を返す。

注意

デフォルトでは、IMediaControl および IUnknown インターフェイスへのポインタを返す。このメンバ関数をオーバーライドして、派生クラスで実装された追加のインターフェイスを公開する。

このメンバ関数は、INonDelegatingUnknown::NonDelegatingQueryInterface メソッドを実装する。


CMediaEvent クラス

CMediaEvent クラスは、デュアル インターフェイス IMediaEvent の IDispatch メソッドの基底クラスの実装を提供する。このクラスは、IMediaEvent インターフェイスのプロパティおよびメソッドを純粋仮想のままにしておく。

CMediaEvent クラスは、IMediaEvent から派生した IMediaEventEx インターフェイスの基底クラスの実装も提供する。

CMediaEvent::GetIDsOfNames、CMediaEvent::GetTypeInfo、CMediaEvent::GetTypeInfoCount、および CMediaEvent::Invoke メンバ関数は、IDispatch インターフェイスの標準的な実装で、CBaseDispatch クラス (およびタイプ ライブラリ) を使用してコマンドを解析し、IMediaEvent インターフェイスの純粋仮想メソッドに渡す。

メンバ関数

CMediaEvent CMediaEvent オブジェクトを作成する。

実装される INonDelegatingUnknown メソッド

NonDelegatingQueryInterface 指定された参照カウントのインターフェイスを返す。

実装される IDispatch メソッド

GetIDsOfNames | 単一のメンバおよびオプションのパラメータのセットを、対応する整数のディスパッチ識別子にマップする。この識別子は、以降の IDispatch::Invoke メソッドの呼び出しで使用できる。
GetTypeInfo | タイプ情報オブジェクトを取得する。このオブジェクトはインターフェイスのタイプ情報を取得する。
GetTypeInfoCount | オブジェクトによって提供されるタイプ情報インターフェイスの数を取得する。
Invoke | オブジェクトによって公開されるプロパティおよびメソッドへのアクセスを提供する。

CMediaEvent::CMediaEvent

CMediaEvent クラス

CMediaEvent オブジェクトを作成する。

構文

CMediaEvent(
const TCHAR *pName,
LPUNKNOWN pUnk
    );

パラメータ

pName
デバッグのために使用されるオブジェクトの名前へのポインタ。
pUnk
このオブジェクトの所有者へのポインタ。

戻り値

戻り値なし。

注意

スタティック メモリに pName パラメータを割り当てる。この名前は、オブジェクトの作成および削除を行うデバッギング端末上に現れる。

CMediaEvent::GetIDsOfNames

CMediaEvent クラス

単一のメンバ関数およびオプションのパラメータのセットを、対応する整数のディスパッチ識別子にマップする。この識別子は、以降の CMediaEvent::Invoke メンバ関数の呼び出しで使用できる。

構文

HRESULT GetIDsOfNames(
REFIID riid,
OLECHAR **rgszNames,
UINT cNames,
LCID lcid,
DISPID *rgdispid
    );

パラメータ

riid
参照識別子。将来的な使用のために予約されている。NULL でなければならない。
rgszNames
渡されたマップする名前の配列へのポインタのアドレス。
cNames
マップされる名前の数。
lcid
名前を解釈するロケール コンテキスト。
rgdispid
呼び出し元割り当て済み配列へのポインタ。各要素には、rgszNames 配列に渡される名前の 1 つに対応する ID が含まれる。最初の要素はメンバの名前を表し、以降の要素は各メンバのパラメータを表す。

戻り値

次のいずれかの値を返す。
DISP_E_UNKNOWN_CLSID | CLSID が認識されなかった。
DISP_E_UNKNOWNNAME | 1 つ以上の名前が不明だった。返された DISPID には、不明な名前に対応する各エントリの DISPID_UNKNOWN が含まれる。
E_OUTOFMEMORY | メモリ不足。
S_OK | 成功。

CMediaEvent::GetTypeInfo

CMediaEvent クラス

タイプ情報オブジェクトを取得する。インターフェイスのタイプ情報を取得できる。

構文

HRESULT GetTypeInfo(
UINT itinfo,
LCID lcid,
ITypeInfo **pptinfo
    );

パラメータ

itinfo
返されるタイプ情報。ゼロを渡して、IDispatch 実装のタイプ情報を取得する。
lcid
タイプ情報のロケール ID。ローカライズされたメンバ名をサポートするクラスの場合、オブジェクトは異なる言語の異なるタイプ情報を返すことができる場合がある。ローカライズされたメンバ名をサポートしないクラスの場合、このパラメータは無視することができる。
pptinfo
要求されたタイプ情報オブジェクトへのポインタのアドレス。

戻り値

pptinfo が無効な場合は、E_POINTER を返す。itinfo がゼロ以外の場合は、TYPE_E_ELEMENTNOTFOUND を返す。成功した場合は、S_OK を返す。それ以外の場合は、タイプを取得するための呼び出しの 1 つから HRESULT を返す。HRESULT はエラーを示し、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
S_OK または NOERROR | 成功。

CMediaEvent::GetTypeInfoCount

CMediaEvent クラス

オブジェクトによって提供されるタイプ情報インターフェイスの数を取得する。

構文

HRESULT GetTypeInfoCount(
UINT *pctinfo
    );

パラメータ

pctinfo
オブジェクトが提供するタイプ情報インターフェイスの数へのポインタ。オブジェクトがタイプ情報を提供した場合、この数は 1 である。それ以外の場合は、0 である。

戻り値

pctinfo が無効な場合は、E_POINTER を返す。それ以外の場合は、S_OK を返す。

CMediaEvent::Invoke

CMediaEvent クラス

オブジェクトによって公開されるプロパティおよびメソッドへのアクセスを提供する。

構文

HRESULT Invoke(
DISPID dispidMember,
REFIID riid,
LCID lcid,
WORD wFlags,
DISPPARAMS *pdispparams,
VARIANT *pvarResult,
EXCEPINFO *pexcepinfo,
UINT *puArgErr
    );

パラメータ

dispidMember
メンバの識別子。ディスパッチ識別子を取得するには、CMediaEvent::GetIDsOfNames またはオブジェクトのドキュメントを使用する。
riid
将来的な使用のために予約されている。IID_NULL でなければならない。
lcid
引数を解釈するロケール コンテキスト。
wFlags
CMediaEvent::Invoke 呼び出しのコンテキストを記述するフラグ。
pdispparams
引数の配列、名前付き引数の引数ディスパッチ ID の配列、および配列内の要素の数を含む構造体へのポインタ。
pvarResult
結果が格納されるポインタ、または呼び出し元が結果を求めていない場合は NULL。
pexcepinfo
例外情報を含む構造体へのポインタ。
puArgErr
DISPPARAMS 構造体の rgvarg 配列内で、エラーがある最初の引数のインデックスへのポインタ。DISPPARAMS の詳細については、Platform SDK を参照すること。

戻り値

riid が IID_NULL 以外の場合は、DISP_E_UNKNOWNINTERFACE を返す。呼び出しが失敗した場合は、CMediaEvent::GetTypeInfo からエラー コードの 1 つを返す。それ以外の場合は、IDispatch::Invoke への呼び出しから HRESULT を返す。

CMediaEvent::NonDelegatingQueryInterface

CMediaEvent クラス

指定された参照カウントのインターフェイスを返す。

構文

HRESULT NonDelegatingQueryInterface(
REFIID riid,
void **ppv
    );

パラメータ

riid
参照識別子。
ppv
インターフェイスへのポインタのアドレス。

戻り値

ppv が無効な場合は、E_POINTER を返す。クエリが成功した場合は NOERROR、失敗した場合は E_NOINTERFACE を返す。

注意

デフォルトでは、IMediaEvent および IUnknown インターフェイスへのポインタを返す。このメンバ関数をオーバーライドして、派生クラスで追加されたインターフェイスを公開する。

このメンバ関数は、INonDelegatingUnknown::NonDelegatingQueryInterface メソッドを実装する。


CMediaPosition クラス

IMediaPosition デュアル インターフェイスの IDispatch メソッド処理する。

このクラスは IMediaPosition インターフェイスを継承するが、それを実装してはならない。CBaseDispatch クラスと Microsoft® DirectShow® タイプ ライブラリを通して IDispatch を実装する。このクラスを直接使用してはならない。そうではなく、以下の 1 つを使用すること :

  • ソース フィルタ : CSourceSeeking 基底クラスを使ってシークを実装する。
  • 変換フィルタ : CPosPassThru クラスを使ってシーク コマンドをアップストリームに渡す。
  • レンダラ : CRendererPosPassThru クラスを使ってシーク コマンドをアップストリームに渡す。
Public メソッド
CMediaPosition | コンストラクタ メソッド。
IDispatch メソッド
GetIDsOfNames | 名前のセットを対応する DISPID のセットにマップする。
GetTypeInfo | オブジェクトのタイプ情報を取得する、それは次にインターフェイスのタイプ情報を取得するために使用される。
GetTypeInfoCount | オブジェクトが提供するタイプ情報インターフェイスの数を取得する。
Invoke | オブジェクトが公開するプロパティとメソッドへのアクセスを提供する。

CMediaPosition::CMediaPosition

CMediaPosition クラス

コンストラクタ メソッド。

構文

CMediaPosition(
    const TCHAR *pName,
    LPUNKNOWN pUnk
);

CMediaPosition(
    const TCHAR *pName,
    LPUNKNOWN pUnk
    HRESULT *phr
);

パラメータ

pName
オブジェクトの名前へのポインタ、デバッグ用。このパラメータはスタティック メモリに割り当てられる。
pUnk
このオブジェクトの所有者へのポインタ、あるいはオブジェクトが集成されているなら NULL 。
phr
無視される。

CMediaPosition::GetIDsOfNames

CMediaPosition クラス

名前のセットを対応する DISPID のセットにマップする。

構文

HRESULT GetIDsOfNames(
    REFIID riid,
    OLECHAR **rgszNames,
    UINT cNames,
    LCID lcid,
    DISPID *rgdispid
);

パラメータ

riid
予約済み。IID_NULL を使用。
rgszNames
マップされる名前が入るワイド キャラクタ文字列の配列のアドレス。
cNames
rgszNames パラメータによって与えられる配列のサイズ。
lcid
名前を解釈するロケール コンテキスト。NULL が可能。
rgdispid
DISPID を受け取る配列へのポインタ。受け取った各要素は rgszNames パラメータに渡された名前の 1 つ 1 つに対応する ID である。

戻り値

HRESULT を返す。以下のいずれかの値。

S_OK | 成功。
E_OUTOFMEMORY | メモリ不足。
DISP_E_UNKNOWNNAME | 1 つあるいはそれ以上の名前が不明だった。

CMediaPosition::GetTypeInfo

CMediaPosition クラス

オブジェクトのタイプ情報を取得する、それは次にインターフェイスのタイプ情報を取得するために使用される。

構文

HRESULT GetTypeInfo(
    UINT itinfo,
    LCID lcid,
    ITypeInfo **pptinfo
);

パラメータ

itinfo
返すべきタイプ 情報。ゼロでなければならない。
lcid
ロケール識別子。
pptinfo
ITypeInfo ポインタを受け取る変数のアドレス。

戻り値

HRESULT を返す。以下のいずれかの値。

S_OK | 成功。
E_POINTER | NULL ポインタ引数。
TYPE_E_ELEMENTNOTFOUND | itinfo パラメータはゼロであってはならない。

CMediaPosition::GetTypeInfoCount

CMediaPosition クラス

オブジェクトが提供するタイプ情報インターフェイスの数を取得する。

構文

HRESULT GetTypeInfoCount(
    UINT *pctinfo
);

パラメータ

pctinfo
オブジェクトによって提供されるタイプ情報インターフェイスの数を受け取る変数へのポインタ。メソッドが返るとき、値は 1 。

戻り値

次の値の 1 つを返す。

S_OK | 成功。
E_POINTER | NULL ポインタ引数。

CMediaPosition::Invoke

CMediaPosition クラス

オブジェクトが公開するプロパティとメソッドへのアクセスを提供する。

構文

HRESULT Invoke(
    DISPID dispidMember,
    REFIID riid,
    LCID lcid,
    WORD wFlags,
    DISPPARAMS *pdispparams,
    VARIANT *pvarResult,
    EXCEPINFO *pexcepinfo,
    UINT *puArgErr
);

パラメータ

dispidMember
メンバの ID 。ディスパッチ識別子を取得するには、CMediaPosition::GetIDsOfNames を使用する。
riid
将来的な使用のために予約されている。IID_NULL でなければならない。
lcid
引数を解釈するロケール コンテキスト。
wFlags
呼び出しのコンテキストを記述するフラグ。
pdispparams
引数を入れる DIPPARAMS 構造体へのポインタ。
pvarResult
結果を受け取る VARIANT へのポインタ、あるいは呼び出し元が結果を必要としないなら NULL 。
pexcepinfo
例外情報を受け取る構造体へのポインタ。
puArgErr
エラーを起こす最初の引数のインデックスを受け取る変数へのポインタ。

戻り値

HRESULT を返す。以下のいずれかの値を含む。

S_OK | 成功。
DISP_E_UNKNOWNINTERFACE | riid パラメータが IID_NULL ではない。


CMediaSample クラス

IMediaSample2 インターフェイスをサポートするメディア サンプルを定義する。メディア サンプルはメモリ バッファへのポインタと、プロテクト メンバ変数にストアされているいくつかのプロパティを持つ。

宣言 : Amfilter.h

メディア サンプルは CBaseAllocator クラスから派生されるアロケータによって作成される。CMediaSample コンストラクタはバッファ サイズと共にアロケータ バッファへのポインタを受け取る。他のプロパティは通常 IMediaSample インターフェイス メソッドを通してセットされるあるいは受け取られる。

メディア サンプルのライフ サイクルはほとんどの COM オブジェクトのそれとは異なる :

  • アロケータはフリー サンプルのリストを保持する。フィルタが新しいサンプルを必要とするとき、アロケータの IMemAllocator::GetBuffer メソッドを呼び出す。アロケータはそのフリー リストからサンプルを取得し、そのサンプルの参照カウントをインクリメントし、そのサンプルのポインタを返す。
  • フィルタがサンプルでの処理を終了したとき、サンプルの IUnknown::Release メソッドを呼び出す。ほとんどのオブジェクトは異なり、参照カウントがゼロになってもサンプルは自身を削除しない。そうではなく、アロケータの IMemAllocator::ReleaseBuffer メソッドを呼び出して、アロケータはフリー リストにそのサンプルを返す。
  • アロケータは IMemAllocator::Decommit が呼び出されるまでサンプルを削除しない。
Protected メンバ変数
m_dwFlags | サンプル プロパティ フラグ。
m_dwTypeSpecificFlags | タイプ固有のフラグ。
m_pBuffer | メディア データが入るメモリ バッファへのポインタ。
m_lActual | バッファ内の有効なデータの長さ、バイト単位。
m_cbBuffer | バッファのサイズ、バイト単位。
m_pAllocator | サンプルを作成したアロケータへのポインタ。
m_pNext | アロケータのサンプル リストにある次のサンプルへのポインタ。
m_Start | サンプル開始タイム。
m_End | サンプル終了タイム。
m_MediaStart | メディア開始タイム。
m_MediaEnd | メディア終了タイム。
m_pMediaType | メディア タイプがそのデータ ストリームの前のサンプルから変更されているなら、メディア タイプへのポインタ。
m_dwStreamId | ストリーム識別子。
Public メンバ変数
m_cRef | 参照カウント。
Public メソッド
CMediaSample | コンストラクタ メソッド。
~CMediaSample | デストラクタ メソッド。 仮想。
SetPointer | メモリ バッファへのポインタを設定する。
IMediaSample メソッド
GetPointer | バッファの読み込み/書き込みポインタを取得する。
GetSize | バッファのサイズを取得する。
GetTime | サンプルが開始・終了するストリーム タイムを取得する。
SetTime | サンプルが開始・終了するストリーム タイムを設定する。
IsSyncPoint | サンプルの開始が同期ポイントかどうかを確認する。
SetSyncPoint | サンプルの開始が同期ポイントかどうかを設定する。
IsPreroll | サンプルがプリロール サンプルかどうかを確認する。
SetPreroll | サンプルがプリロール サンプルかどうかを設定する。
GetActualDataLength | バッファ内の有効なデータの長さを取得する。
SetActualDataLength | バッファ内の有効なデータの長さを設定する。
GetMediaType | メディア タイプが前のサンプルと異なるなら、メディア タイプを取得する。
SetMediaType | サンプルのメディア タイプを設定する。
IsDiscontinuity | サンプルがデータ ストリーム内にブレークを表示する(不連続)かどうかを確認する。
SetDiscontinuity | サンプルがデータ ストリーム内でブレークを表示する(不連続)かどうかを設定する。
GetMediaTime | サンプルのメディア タイムを取得する。
SetMediaTime | サンプルのメディア タイムを設定する。
IMediaSample2 メソッド
GetProperties | サンプルのプロパティを取得する。
SetProperties | サンプルのプロパティを設定する。

CMediaSample.m_dwFlags

CMediaSample クラス

サンプル プロパティ フラグ。 AM_SAMPLE_PROPERTY_FLAGS 列挙型フラグのビットの組み合わせ。

構文

DWORD m_dwFlags;

CMediaSample.m_dwTypeSpecificFlags

CMediaSample クラス

タイプ固有のフラグ。このメンバ変数の意味はサンプルのメディア タイプに依存する。

構文

DWORD m_dwTypeSpecificFlags;

CMediaSample.m_pBuffer

CMediaSample クラス

メディア データが入るメモリ バッファへのポインタ。

構文

LPBYTE m_pBuffer;

CMediaSample.m_lActual

CMediaSample クラス

バッファ内の有効なデータの長さ、バイト単位。この値は (m_cbBuffer) バッファのサイズ以下でなければならない。

構文

LONG m_lActual;

CMediaSample.m_cbBuffer

CMediaSample クラス

バッファのサイズ、バイト単位。

構文

LONG m_cbBuffer;

CMediaSample.m_pAllocator

CMediaSample クラス

サンプルを作成したアロケータへのポインタ。

構文

CBaseAllocator *m_pAllocator;

注意

サンプルはアロケータへのポインタを保持するが、参照カウントは保持しない。そのかわり、アロケータはそれ自身の参照カウントを IMemAllocator::GetBuffer メソッドでインクリメントし、それ自身を IMemAllocator::ReleaseBuffer メソッドで解放する。これはアロケータは他のオブジェクトがそのサンプルを使っている限りは有効であることを保証している。

CMediaSample.m_pNext

CMediaSample クラス

アロケータのサンプル リストにある次のサンプルへのポインタ。

構文

CMediaSample *m_pNext;

CMediaSample.m_Start

CMediaSample クラス

サンプル開始タイム。この値は m_dwFlags メンバ変数が AM_SAMPLE_TIMEVALID フラグを含むときのみ有効。

構文

REFERENCE_TIME m_Start;

CMediaSample.m_End

CMediaSample クラス

サンプル終了タイム。 この値は m_dwFlags メンバ変数が AM_SAMPLE_STOPVALID フラグを含むときのみ有効。

構文

REFERENCE_TIME m_End;

CMediaSample.m_MediaStart

CMediaSample クラス

メディア開始タイム。

構文

LONGLONG m_MediaStart;

CMediaSample.m_MediaEnd

CMediaSample クラス

メディア終了タイム。この値はメディア開始タイム (m_MediaStart) からのオフセットとして計算される。

構文

LONG m_MediaEnd;

CMediaSample.m_pMediaType

CMediaSample クラス

メディア タイプがそのデータ ストリームの前のサンプルから変更されているなら、メディア タイプへのポインタ。 そうでなければ NULL。

構文

AM_MEDIA_TYPE *m_pMediaType;

CMediaSample.m_dwStreamId

CMediaSample クラス

ストリーム識別子。詳細については、「AM_SAMPLE2_PROPERTIES」を参照すること。

構文

DWORD m_dwStreamId;

CMediaSample.m_cRef

CMediaSample クラス

参照カウント。

構文

LONG m_cRef;

CMediaSample::CMediaSample

CMediaSample クラス

コンストラクタ メソッド。

構文

CMediaSample(
    TCHAR *pName,
    CBaseAllocator *pAllocator,
    HRESULT *phr,
    LPBYTE pBuffer = NULL,
    LONG length = 0
);

パラメータ

pName
メディアサンプルの名前を入れる文字列へのポインタ。
pAllocator
このサンプルを作成した CBaseAllocator オブジェクトへのポインタ。
phr
メソッドの成功・失敗を示す HRESULT 値を受け取る変数へのポインタ。
pBuffer
呼び出し元によって割り当てられた length サイズのメモリ バッファへのポインタ。
length
メモリ バッファの長さ。

注意

基底クラスは phr パラメータに渡された HRESULT 値を修正しない。

CMediaSample::~CMediaSample

CMediaSample クラス

デストラクタ メソッド。

構文

~CMediaSample(void);

CMediaSample::GetActualDataLength

CMediaSample クラス

バッファ内の有効なデータの長さを取得する。IMediaSample::GetActualDataLength メソッドの実装。

構文

LONG GetActualDataLength(void);

戻り値

有効なデータの長さ、バイト単位。

注意

このプロパティを指定する m_lActual メンバ変数。

CMediaSample::GetMediaTime

CMediaSample クラス

サンプルのメディア タイムを取得する。 IMediaSample::GetMediaTime メソッドの実装。

構文

HRESULT GetMediaTime(
    LONGLONG *pStart,
    LONGLONG *pEnd
);

パラメータ

pStart
メディア開始タイムを受け取る変数へのポインタ。
pEnd
メディア終了タイムを受け取る変数へのポインタ。

戻り値

以下の表に示される HRESULT 値の 1 つを返す。

S_OK | 成功。
VFW_E_MEDIA_TIME_NOT_SET | このサンプルにはメディア タイムがセットされていない。

注意

m_MediaEnd メンバ変数は m_MediaStart からのオフセットを示すが、pEnd パラメータが受け取る値は m_MediaStart + m_MediaEnd で計算される絶対メディア タイムである。

メディア タイムの詳細については、「DirectShow のタイムとクロック」を参照すること。

CMediaSample::GetMediaType

CMediaSample クラス

メディア タイプが前のサンプルと異なるなら、メディア タイプを取得する。 IMediaSample::GetMediaType メソッドの実装。

構文

HRESULT GetMediaType(
    AM_MEDIA_TYPE **ppMediaType
);

パラメータ

ppMediaType
AM_MEDIA_TYPE 構造体へのポインタを受け取る変数のアドレス。メディア タイプが前のサンプルから変更になっていないなら、*ppMediaType には NULL がセットされる。

戻り値

以下の表に示される HRESULT 値の 1 つを返す。

S_FALSE | 前のサンプルからメディア タイプは変更されていない。
S_OK | 成功。
E_OUTOFMEMORY | メモリ不足。

注意

メディア タイプの作業が終了したら、DeleteMediaType ユーティリティ関数を呼び出してメモリ ブロックをフリーにすること。

m_pMediaType メンバ変数はメディア タイプを示す。m_dwFlags メンバ変数はメディア タイプが変更されたかどうかを示す。

CMediaSample::GetPointer

CMediaSample クラス

バッファの読み込み/書き込みポインタを取得する。 IMediaSample::GetPointer メソッドの実装。

構文

HRESULT GetPointer(
    BYTE **ppBuffer
);

パラメータ

ppBuffer
バッファへのポインタを受け取る変数へのポインタ。

戻り値

S_OK を返す。

CMediaSample::GetProperties

CMediaSample クラス

サンプルのプロパティを取得する。IMediaSample2::GetProperties メソッドの実装。

構文

HRESULT GetProperties(
    DWORD cbProperties,
    BYTE *pbProperties
);

パラメータ

cbProperties
受け取るプロパティ データの長さ、バイト単位。
pbProperties
cbProperties サイズのバッファへのポインタ。

戻り値

以下の表に示される HRESULT 値の 1 つを返す。

S_OK | 成功。
E_POINTER | NULL ポインタ引数。

CMediaSample::GetSize

CMediaSample クラス

バッファのサイズを取得する。IMediaSample::GetSize メソッドの実装。

構文

LONG GetSize(void);

戻り値

バッファのサイズを返す、バイト単位。

CMediaSample::GetTime

CMediaSample クラス

サンプルが開始・終了するストリーム タイムを取得する。IMediaSample::GetTime メソッドの実装。

構文

HRESULT GetTime(
    REFERENCE_TIME *pTimeStart,
    REFERENCE_TIME *pTimeEnd
);

パラメータ

pTimeStart
開始ストリームタイムを受け取る変数へのポインタ、100 ナノ秒単位。
pTimeEnd
終了ストリームタイムを受け取る変数へのポインタ、100 ナノ秒単位。サンプルが終了タイムを持っていないなら、この値には開始タイム プラス 1 がセットされる。

戻り値

以下の表に示される HRESULT 値の 1 つを返す。

S_OK | 成功。
VFW_S_NO_STOP_TIME | サンプルは有効な開始タイムを持っているが、終了タイムを持っていない。
VFW_E_SAMPLE_TIME_NOT_SET | サンプルは有効なタイム スタンプを持っていない。

注意

m_Start と m_End メンバ変数はタイム スタンプを示す。m_dwFlags メンバ変数はタイム スタンプが有効かどうかを示す。

タイム スタンプの詳細については、「DirectShow のタイムとクロック」を参照すること。

CMediaSample::IsDiscontinuity

CMediaSample クラス

サンプルがデータ ストリーム内にブレークを表示するどうかを確認する。IMediaSample::IsDiscontinuity の実装。

構文

HRESULT IsDiscontinuity(void);

戻り値

サンプルのデータ ストリーム内にブレークがあれば S_OK を返す、そうでなければ S_FALSE を返す。

注意

m_dwFlags メンバ変数はこのプロパティを示す。

CMediaSample::IsPreroll

CMediaSample クラス

サンプルがプリロール サンプルかどうかを確認する。IMediaSample::IsPreroll メソッドの実装。

構文

HRESULT IsPreroll(void);

戻り値

サンプルがプリロール サンプルなら S_OK を返し、それ以外なら S_FALSE を返す。

注意

m_dwFlags メンバ変数はこのプロパティを示す。

CMediaSample::IsSyncPoint

CMediaSample クラス

サンプルの開始が同期ポイントかどうか確認する。IMediaSample::IsSyncPoint メソッドの実装。

構文

HRESULT IsSyncPoint(void);

戻り値

サンプルが同期ポイントなら S_OK を返す、それ以外なら S_FALSE を返す。

注意

m_dwFlags メンバ変数はこのプロパティを示す。

CMediaSample::SetActualDataLength

CMediaSample クラス

バッファ内の有効なデータの長さを設定する。IMediaSample::SetActualDataLength メソッドの実装。

構文

HRESULT SetActualDataLength(
    long lLen
);

パラメータ

lLen
有効なデータの長さ、バイト単位。

戻り値

以下の表に示される HRESULT 値の 1 つを返す。

S_OK | 成功。
VFW_E_BUFFER_OVERFLOW | lLen は割り当てられたバッファサイズより大きい。

注意

このメソッドは m_lActual メンバ変数を設定する。

CMediaSample::SetDiscontinuity

CMediaSample クラス

サンプルがデータ ストリーム内でブレークを表示するかどうかを設定する。IMediaSample::SetDiscontinuity メソッドの実装。

構文

HRESULT SetDiscontinuity(
    BOOL bDiscont
);

パラメータ

bDiscont
このサンプルが不連続かどうかを示すブール値。TURE ならメディア サンプルは前のサンプルと不連続。

戻り値

S_OK を返す。

注意

このメソッドは不連続プロパティを示す m_dwFlags メンバ変数をアップデートする。

CMediaSample::SetMediaTime

CMediaSample クラス

サンプルのメディア タイムを設定する。IMediaSample::SetMediaTime メソッドの実装。

構文

HRESULT SetMediaTime(
    LONGLONG *pStart,
    LONGLONG *pEnd
);

パラメータ

pStart
メディア開始タイムへのポインタ、あるいは NULL 。
pEnd
メディア終了タイムへのポインタ、あるいは NULL 。

戻り値

S_OK を返す。

注意

メディア終了タイムはメディア開始タイムより大きくなければならない。不適切なメディアタイムには NULL を使うこと。

pEnd パラメータは絶対メディア タイムを示すが、m_MediaEnd メンバ変数は pStart からのオフセットとして計算される。すなわち、m_MediaEnd = *pTimeEnd – *pTimeStart 。

メディア タイムの詳細については、「DirectShow のタイムとクロック」を参照すること。

CMediaSample::SetMediaType

CMediaSample クラス

サンプルのメディア タイプを設定する。 IMediaSample::SetMediaType メソッドの実装。

構文

HRESULT SetMediaType(
    AM_MEDIA_TYPE *pMediaType
);

パラメータ

pMediaType
AM_MEDIA_TYPE 構造体へのポインタ。

戻り値

以下の表に示される HRESULT 値の 1 つを返す。

S_OK | 成功
E_OUTOFMEMORY | メモリ不足

注意

このメソッドはメディア タイプを示す m_pMediaType メディア変数と、メディア タイプが変更されたかどうかを示す m_dwFlags メンバ変数設定する。

このメソッドは AM_MEDIA_TYPE 構造体のコピーを作る。

CMediaSample::SetPointer

CMediaSample クラス

メモリ バッファへのポインタを設定する。

構文

HRESULT SetPointer(
    BYTE *ptr,
    LONG cBytes
);

パラメータ

ptr
呼び出し元が割り当てた サイズ cBytes のメモリ バッファへのポインタ。
cBytes
バッファのサイズ、バイト単位。

戻り値

S_OK を返す。

注意

このメソッドによってアロケータはサンプルに新しいポインタをセットできる。

このメソッドは IMediaSample インターフェイスを通しては使えない。サンプルを作成したオブジェクトは (CMediaSample を通して) このメソッドにアクセスできるが、他のオブジェクトはアクセスできない。

CMediaSample::SetPreroll

CMediaSample クラス

サンプルがプリロール サンプルかどうかを設定する。プリロール サンプルは表示されるべきではない。IMediaSample::SetPreroll メソッドの実装。

構文

HRESULT SetPreroll(
    BOOL bIsPreroll
);

パラメータ

bIsPreroll
これがプリロール サンプルかどうかを示すブール値。TRUE ならこれはプリロール サンプル。

戻り値

S_OK を返す。

注意

このメソッドはプリロール プロパティを示す m_dwFlags メンバ変数をアップデートする。

CMediaSample::SetProperties

CMediaSample クラス

サンプルのプロパティを設定する。このメソッドは IMediaSample2::SetProperties を実装する。

構文

HRESULT SetProperties(
    DWORD cbProperties,
    const BYTE *pbProperties
);

パラメータ

cbProperties
セットすべきプロパティ データの長さ、バイト単位。
pbProperties
サイズ cbProperties のバッファへのポインタ。

戻り値

以下の表に示される HRESULT 値の 1 つを返す。

S_OK | 成功
E_INVALIDARG | 不適切な引数
E_OUTOFMEMORY | メモリ不足
E_POINTER | NULL ポインタ引数

CMediaSample::SetSyncPoint

CMediaSample クラス

サンプルの開始が同期ポイントかどうかを設定する。このメソッドは IMediaSample::SetSyncPoint メソッドを実装する。

構文

HRESULT SetSyncPoint(
    BOOL bIsSyncPoint
);

パラメータ

bIsSyncPoint
これが同期ポイントかどうかを示すブール値。TRUE ならこれは同期ポイント。

戻り値

S_OK を返す。

注意

このメソッドは同期ポイント プロパティを示す m_dwFlags メンバ変数をアップデートする。

CMediaSample::SetTime

CMediaSample クラス

サンプルが開始・終了するストリームタイムを設定する。 IMediaSample::SetTime メソッドの実装。

構文

HRESULT SetTime(
    REFERENCE_TIME *pTimeStart,
    REFERENCE_TIME *pTimeEnd
);

パラメータ

pTimeStart
サンプルが開始するストリーム タイムへのポインタ、100 ナノ秒単位。
pTimeEnd
サンプルが開始するストリーム タイムへのポインタ、100 ナノ秒単位、あるいは NULL 。

戻り値

S_OK を返す。

注意

このメソッドはタイム スタンプを示す m_Start と m_End メンバ変数を設定する。それはまたタイム スタンプが有効かどうかを示す m_dwFlags メンバ変数をもアップデートする。

タイム スタンプの詳細については、「DirectShow のタイムとクロック」を参照すること。


CMediaType クラス

メディア タイプを管理するためのクラス。このクラスは AM_MEDIA_TYPE 構造体を継承する。それは AM_MEDIA_TYPE タイプの変数にキャストされ得る。

宣言 : Mtype.h

Public メソッド
CMediaType | コンストラクタ メソッド
~CMediaType | デストラクタ メソッド
IsValid | メジャー タイプがこのオブジェクトにアサインされているかどうかを確認する。
Type | メジャー タイプを取得する。
SetType | メジャー タイプを指定する。
Subtype | サブタイプを取得する。
SetSubtype | サブタイプを指定する。
IsFixedSize | サンプルが固定サイズか可変サイズかを確認する。
IsTemporalCompressed | ストリームが時系列圧縮を使用しているかどうかを確認する。
GetSampleSize | サンプル サイズを取得する。
SetSampleSize | 固定サンプル サイズを指定する、あるいはサンプルが可変サイズを持つことを指定する。
SetVariableSize | サンプルが固定サイズを持たないことを指定する。
SetTemporalCompression | サンプルが時系列圧縮を使って圧縮されたかどうかを指定する。
Format | フォーマット ブロックへのポインタを取得する。
FormatLength | フォーマット ブロックの長さを取得する。
SetFormatType | フォーマット タイプを指定する。
FormatType | フォーマット タイプを取得する。
SetFormat | フォーマット ブロックを指定する。
ResetFormatBuffer | フォーマット ブロックを削除する。
AllocFormatBuffer | フォーマット ブロックのメモリを割り当てる。
ReallocFormatBuffer | フォーマット ブロックに新しいサイズを再割り当てする。
InitMediaType | メディア タイプを初期化する。
MatchesPartial | このメディア タイプが部分的に指定したメディア タイプと一致するかどうかを確認する。
IsPartiallySpecified | メディア タイプが部分的に指定されたかどうかを確認する。
演算子
operator = | メディア タイプをコピーする割り当て演算子をオーバーロードする。
operator == | 2 つの CMediaType オブジェクトが等しいことをテストする。
operator != | 2 つのCMediaType オブジェクトが等しくないことをテストする。

CMediaType::AllocFormatBuffer

CMediaType クラス

フォーマット ブロックのメモリを割り当てる。

構文

BYTE* AllocFormatBuffer(
    ULONG length
);

パラメータ

length
フォーマット ブロックに要求されるサイズ、バイト単位。

戻り値

成功なら新しいブロックへのポインタを返す。そうでなければ NULL を返す。

注意

メソッドが新しいフォーマット ブロックの割り当てに成功すると、既存のフォーマット ブロックをフリーにする。

CMediaType::CMediaType

CMediaType クラス

コンストラクタ メソッド。

構文

CMediaType(void);

CMediaType(
    const GUID *majortype
);

CMediaType(
    const AM_MEDIA_TYPE& mtype
);

CMediaType(
    const CMediaType& cmtype
);

パラメータ

majortype
メジャー タイプ GUID へのポインタ。
mtype
AM_MEDIA_TYPE 構造体への参照。
cmtype
CMediaType オブジェクトへの参照。

注意

コンストラクタは InitMediaType 関数を呼び出して、メディア タイプを初期化する。majortype パラメータが指定されると、コンストラクタはメジャー タイプを GUID で初期化する。mtype か cmtype パラメータが指定されると、コンストラクタは (フォーマット ブロックを含む) メディア タイプ情報を新しいオブジェクトにコピーする。

CMediaType::~CMediaType

CMediaType クラス

デストラクタ メソッド。

構文

~CMediaType(void);

注意

デストラクタは FreeMediaType 関数を自分自身で呼び出す。

CMediaType::Format

CMediaType クラス

フォーマット ブロックへのポインタを取得する。

構文

BYTE* Format(void) const;

戻り値

pbFormat メンバを返す。

CMediaType::FormatLength

CMediaType クラス

フォーマット ブロックの長さを取得する。

構文

ULONG FormatLength(void) const;

戻り値

cbFormat メンバを返す。

CMediaType::FormatType

CMediaType クラス

フォーマット タイプを取得する。

構文

const GUID *FormatType(void) const;

戻り値

formattype メンバへのポインタを返す。

CMediaType::GetSampleSize

CMediaType クラス

サンプル サイズを取得する。

構文

ULONG GetSampleSize(void) const;

戻り値

サンプル サイズが固定なら、バイト単位のサンプルサイズを返す。そうでなければゼロを返す。

CMediaType::InitMediaType

CMediaType クラス

メディア タイプを初期化する。

構文

void InitMediaType(void);

注意

このメソッドはオブジェクトのメモリをゼロにし、固定サンプル サイズ プロパティを TRUE にし、サンプル サイズを 1 に設定する。

CMediaType::IsFixedSize

CMediaType クラス

サンプルが固定サイズか可変サイズかを確認する。

構文

BOOL IsFixedSize(void) const;

戻り値

bFixedSizeSamples メンバの値を返す。

CMediaType::IsPartiallySpecified

CMediaType クラス

メディア タイプが部分的に指定されたかどうかを確認する。メジャー タイプ、サブタイプ、フォーマット タイプが GUID_NILL なら、メディア タイプは 部分的 である。

構文

BOOL IsPartiallySpecified(void) const;

戻り値

メディア タイプが部分的に指定されているなら TRUE を返す。そうでなければ FALSE を返す。

注意

IPin::Connect メソッドは部分的メディア タイプを許容できる。

その実装は実際にはサブタイプのテストではない。指定したフォーマット タイプがあれば、たとえサブタイプが GUID_NULL であっても、メディア タイプは部分的とは解釈されない。

CMediaType::IsTemporalCompressed

CMediaType クラス

ストリームが時系列圧縮を使用しているかどうかを確認する。

構文

BOOL IsTemporalCompressed(void) const;

戻り値

bTemporalCompression メンバの値を返す。

CMediaType::IsValid

CMediaType クラス

メジャー タイプがこのオブジェクトにアサインされているかどうかを確認する。

構文

BOOL IsValid(void) const;

戻り値

メジャータイプがこのオブジェクトにアサインされているなら TRUE を返す。それ以外なら FALSE を返す。

注意

デフォルトでは CMediaType オブジェクトは GUID_NULL のメジャー タイプで初期化される。このメソッドを呼び出して、オブジェクトが正しく初期化されたかどうかを確認すること。

CMediaType::MatchesPartial

CMediaType クラス

このメディア タイプが部分的に指定したメディア タイプと一致するかどうかを確認する。

構文

BOOL MatchesPartial(
    const CMediaType *ppartial
    ) const;

パラメータ

ppartial
一致すべきメディア タイプへのポインタ。

戻り値

メディア タイプが一致すれば TRUE を返す。それ以外なら FALSE を返す。

注意

ppartial によって指定されるメディア タイプはメジャータイプ、サブタイプ、フォーマット タイプに GUID_NULL 値を取り得る。GUID_NULL 値のメンバはテストされない。(基本的には、GUID_NULL はワイルドカードとして働く。) GUID_NULL 以外の値を持つメンバは一致すべきメディア タイプと一致しなければならない。

CMediaType::ReallocFormatBuffer

CMediaType クラス

フォーマット ブロックに新しいサイズを再割り当てする。

構文

BYTE* ReallocFormatBuffer(
    ULONG length
);

パラメータ

length
フォーマット ブロックに要求される新しいサイズ、バイト単位。ゼロより大きな値でなければならない。

戻り値

成功すれば新しいブロックへのポインタを返す。そうでなければ、古いフォーマット ブロックへのポインタか NULL を返す。

注意

このメソッドは新しいフォーマット ブロックを割り当てる。それは既存のフォーマット ブロックを新しいフォーマット ブロックにできるだけコピーする。新しいブロックが既存のブロックより小さいなら、既存のブロックは切り詰められる。新しいブロックがより大きければ、未定義の追加スペースを持つ。そこでは明示的にゼロがセットされているわけでは ない。

CMediaType::ResetFormatBuffer

CMediaType クラス

フォーマット ブロックを削除する。

構文

void ResetFormatBuffer(void);

CMediaType::SetFormat

CMediaType クラス

フォーマット ブロックを指定する

構文

BOOL SetFormat(
    BYTE *pFormat,
    ULONG length
);

パラメータ

pFormat
フォーマット ブロックが入るメモリのブロックへのポインタ。
length
フォーマット ブロックのサイズ、バイト単位。

戻り値

成功なら TRUE、エラーが起きたなら FALSE を返す。

注意

このメソッドは pFormat によって指定されたフォーマット ブロックをコピーする。フォーマット タイプを設定するには SetFormatType メソッドを呼び出すこと。

CMediaType::SetFormatType

CMediaType クラス

フォーマット タイプを指定する。

構文

void SetFormatType(
    const GUID *pformattype
);

パラメータ

pformattype
フォーマット タイプを指定する GUID へのポインタ。

注意

このメソッドは formattype メンバを設定する。フォーマット タイプはフォーマット ブロックのレイアウトを定義する。たとえば、フォーマット タイプが FORMAT_VideoInfo なら、フォーマット ブロックには VIDEOINFOHEADER が入るべきである。フォーマット ブロックを設定するには、SetFormat を呼び出すこと。呼び出し元はフォーマット ブロックがフォーマット タイプと一致することを保証する責任がある。

CMediaType::SetSampleSize

CMediaType クラス

固定サンプル サイズを指定する、あるいはサンプルが可変サイズを持つことを指定する。

構文

void SetSampleSize(
    ULONG sz
);

パラメータ

sz
サンプル サイズ (バイト単位)、あるいはゼロ。

注意

sz がゼロなら、メディア タイプは可変のサンプル サイズを使う。そうでなければ、サンプル サイズは sz バイト固定である。

CMediaType::SetSubtype

CMediaType クラス

サブタイプを指定する。

構文

void SetSubtype(
    const GUID *psubtype
);

パラメータ

psubtype
サブタイプを指定する GUID へのポインタ。

CMediaType::SetTemporalCompression

CMediaType クラス

ストリームが時系列圧縮を使用しているかどうかを確認する。

構文

void SetTemporalCompression(
    BOOL bCompressed
);

パラメータ

bCompressed
ストリームが時系列圧縮を使用しているかどうかを指定するブール値。ストリームが時系列圧縮を使用しているなら TRUE 値がセットされる。

注意

このメソッドは bTemporalCompression メンバを設定する。

CMediaType::SetType

CMediaType クラス

メジャー タイプを指定する。

構文

void SetType(
    const GUID *ptype
);

パラメータ

ptype
メジャー タイプを指定する GUID へのポインタ。

CMediaType::SetVariableSize

CMediaType クラス

サンプルが固定サイズを持たないことを指定する。

構文

void SetVariableSize(void);

注意

このメソッドは bFixedSizeSamples メンバを FALSE に設定する。この後で CMediaType::GetSampleSize メソッドを呼び出すとゼロを返す。

CMediaType::Subtype

CMediaType クラス

サブタイプを取得する。

構文

const GUID *Type(void) const;

戻り値

subtype メンバへのポインタを返す。

CMediaType::Type

CMediaType クラス

メジャー タイプを取得する。

構文

const GUID *Type(void) const;

戻り値

majortype メンバへのポインタを返す。

CMediaType::operator =

CMediaType クラス

メディア タイプをコピーする割り当て演算子をオーバーロードする。

構文

CMediaType& operator=(
    const CMediaType& cmtype
);

CMediaType& operator=(
    const AM_MEDIA_TYPE& mtype
);

パラメータ

cmtype
CMediaType オブジェクトへの参照。
mtype
AM_MEDIA_TYPE 構造体への参照。

戻り値

オブジェクトへの参照を返す。

CMediaType::operator ==

CMediaType クラス

2 つの CMediaType オブジェクトが等しいことをテストする。

構文

inline BOOL operator==(
    const CMediaType& rt
) const;

パラメータ

rt
比較する CMediaType オブジェクトへの参照。

戻り値

rt がこのオブジェクトと等しいなら TRUE を返す。そうでなければ FALSE を返す。

CMediaType::operator !=

CMediaType クラス

2 つのCMediaType オブジェクトが等しくないことをテストする。

構文

BOOL operator!=(
    const CMediaType& rt
) const;

パラメータ

rt
比較する CMediaType オブジェクトへの参照。

戻り値

rt がこのオブジェクトと等くないなら TRUE を返す。そうでなければ FALSE を返す。


CMemAllocator クラス

CMemAllocator class hierarchy

IMemAllocator インターフェイスをサポートするアロケータを実装する。

宣言 : Amfilter.h

このクラスは CBaseAllocator から派生する。アロケータの詳細については、CBaseAllocator のドキュメントを参照すること。

Protected メンバ変数
m_pBuffer | バッファが入るメモリ ブロックへのポインタ。
Protected メソッド
Free | デコミット操作の間に呼び出される。
ReallyFree | バッファのメモリを解放する。
Alloc | バッファにメモリを割り当てる。
Public メソッド
CMemAllocator | コンストラクタ メソッド。
~CMemAllocator | デストラクタ メソッド。
CreateInstance | CMemAllocator クラスの新しいインスタンスを作成する。
IMemAllocator メソッド
SetProperties | 割り当てるべきバッファの数と各バッファのサイズを指定する。

CMemAllocator.m_pBuffer

CMemAllocator クラス

バッファが入るメモリ ブロックへのポインタ。

構文

LPBYTE m_pBuffer;

注意

サンプル バッファはこのポインタからのオフセットとして計算される。

CMemAllocator::Alloc

CMemAllocator クラス

バッファにメモリを割り当てる。

構文

HRESULT Alloc(void);

戻り値

以下の表に示される HRESULT 値の 1 つを返す。

S_OK | 成功。
E_OUTOFMEMORY | メモリ不足。
VFW_E_SIZENOTSET | バッファ要求がセットされなかった。

注意

このメソッドは CBaseAllocator::Commit メソッドから呼び出される。それは SetProperties メソッドで与えられたバッファ要求に十分な連続的なメモリ ブロックを割り当てる。

CMemAllocator::CMemAllocator

CMemAllocator クラス

コンストラクタ メソッド。

構文

CMemAllocator(
    TCHAR *pName,
    LPUNKNOWN pUnk,
    HRESULT *phr,
);

パラメータ

pName
アロケータの名前が入る文字列へのポインタ。
pUnk
このオブジェクトの所有者へのポインタ。オブジェクトが集成されているなら、集成しているオブジェクトの IUnknown インターフェイスへのポインタを渡す。そうでなければ、このパラメータには NULL を設定する。
phr
メソッドの成功・失敗を示す HRESULT 値を受け取る変数へのポインタ。

CMemAllocator::~CMemAllocator

CMemAllocator クラス

デストラクタ メソッド。

構文

~CMemAllocator(void);

構文

このメソッドは基底クラス デストラクタをオーバーライドし、Decommit と ReallyFree を呼び出す。

CMemAllocator::CreateInstance

CMemAllocator クラス

CMemAllocator クラスの新しいインスタンスを作成する。

構文

static CUnknown *CreateInstance(
    LPUNKNOWN pUnk,
    HRESULT *phr
);

パラメータ

pUnk
このオブジェクトの所有者へのポインタ。オブジェクトが集成されているなら、集成しているオブジェクトの IUnknown インターフェイスへのポインタを渡す。そうでなければ、このパラメータには NULL を設定する。
phr
メソッドの成功・失敗を示す HRESULT 値を受け取る変数へのポインタ。

戻り値

CUnknown オブジェクトとしてタイプされる 新しい CMemAllocator オブジェクトへのポインタを返す。

CMemAllocator::Free

CMemAllocator クラス

デコミット操作の間に呼び出す。

構文

void Free(void);

注意

このメソッドはデコミット操作の間に呼び出される純粋仮想メソッド CBaseAllocator::Free をオーバーライドする。CMemAllocator クラスでは、このメソッドは何もしない。メモリはデストラクタ メソッドで ReallyFree メソッドを呼び出すことでフリーになる。

CMemAllocator::ReallyFree

CMemAllocator クラス

バッファのメモリを解放する

構文

void ReallyFree (void);

注意

CMemAllocator クラスはこのオブジェクトが削除されるまでメモリを保持する。

CMemAllocator::SetProperties

CMemAllocator クラス

割り当てるべきバッファの数と各バッファのサイズを指定する。

構文

HRESULT SetProperties(
    ALLOCATOR_PROPERTIES *pRequest,
    ALLOCATOR_PROPERTIES *pActual
);

パラメータ

pRequest
バッファ要求を入れる ALLOCATOR_PROPERTIES 構造体へのポインタ。
pActual
実際のバッファ プロパティを受け取る ALLOCATOR_PROPERTIES 構造体へのポインタ。

戻り値

以下の表に示される HRESULT 値の 1 つを返す。

S_OK | 成功。
E_POINTER | NULL ポインタ引数。
VFW_E_ALREADY_COMMITTED | フィルタがアクティブな間は割り当てられたメモリを変更することはできない。
VFW_E_BADALIGN | 不適切な引数が指定された。
VFW_E_BUFFERS_OUTSTANDING | 1 つあるいはそれ以上のバッファがまだアクティブ。

注意

このメソッドは CBaseAllocator::SetProperties メソッドをオーバーライドする。

ALLOCATOR_PROPERTIES 構造体の cbAlign メンバによって指定されるバッファのアラインメントは 2 の累乗でなければならない。


CMsg クラス

CMsgThread クラスは、要求を直接送信する代わりに、非同期的に送信できるワーカー スレッドのサポートを提供する。CAMThread クラスは、単一の要求を送信できるワーカー スレッドを提供する。一度に要求を行うことができるクライアントは 1 つだけなので、クライアントはワーカー スレッドが要求の処理を完了するまでブロックする。対照的に、CMsgThread クラスは、任意の数の要求を送信できるワーカー スレッドを提供する。CMsg オブジェクトのフォーマットの要求は、キューに入れられ、順番に、非同期的に実行される。応答や戻り値は受信されない。

データ メンバ

dwFlags | 要求コードへのフラグ パラメータ。
lpParam | パラメータまたは戻り値としてワーカー スレッドが必要とするデータ。このデータは、キューに入れる処理が完了した後でも参照されるので、スタック ベースであってはならない。
pEvent | ワーカー スレッドが処理の完了を通知するために送信できるイベント オブジェクト。
uMsg | スレッド クラスのクライアントによって定義され、オーバーライドされたワーカー スレッド関数によって認識される要求コード。

メンバ関数

CMsg CMsg オブジェクトを作成する。

CMsg::CMsg

CMsg クラス

CMsg オブジェクトを作成する。

構文

CMsg(

  UINT u,

  DWORD dw,

  LPVOID lp,

  CAMEvent *pEvent

  );

パラメータ

u
スレッド クラスのクライアントによって定義され、オーバーライドされたワーカー スレッド関数によって認識される要求コード。
dw
要求コードへのフラグ パラメータ。
lp
パラメータまたは戻り値としてワーカー スレッドが必要とするデータへのポインタ。このデータは、キューに入れる処理が完了した後でも参照されるので、スタック ベースであってはならない。
pEvent
ワーカー スレッドが処理の完了を通知するために送信できるイベント オブジェクトへのポインタ。

戻り値

戻り値なし。

注意

このメンバ関数は、CMsgThread ワーカー スレッドが処理の対象とする要求を格納する。すべてのパラメータは、このメッセージが処理されるときに、パラメータとしてワーカー スレッド関数に渡される。パラメータの意味は、ワーカー スレッドを呼び出すクライアント関数と、ワーカー スレッドの実行関数を提供する派生クラスで定義される。


CMsgThread クラス

CMsgThread クラスは、要求を非同期的に完了するために、キューを処理するスレッドのキューに入れるワーカー スレッド クラスである。このクラスを使用するには、このクラスからクラスを派生させ、CMsgThread::ThreadMessageProc メンバ関数をオーバーライドする。ThreadMessageProc メンバ関数は各要求を実行する。クライアント関数と ThreadMessageProc メンバ関数は、CMsg オブジェクトのパラメータについて共通の定義を共有しなければならない。

ネゴシエート メカニズムによって、ワーカー スレッドに終了が指示される。通常、これは CMsg クラスの uMsg メッセージ コードの値である。

派生クラスのデストラクタからこのメッセージを送信し、派生クラスの破棄が完了する前に CMsgThread::WaitForThreadExit メンバ関数を呼び出すことを推奨する。

Protected データ メンバ

m_hSem | 通知に使用するハンドルを示す。
m_Lock | リストへのアクセスを保護する。
m_lWaiting | 空きスレッドを待機することを示す。
m_ThreadQueue | CMsgThread::GetThreadMsg メンバ関数をオーバーライドし、このキュー以外をブロックする。

メンバ関数

CMsgThread | CMsgThread オブジェクトを作成する。
CreateThread | スレッドを作成する。
GetThreadHandle | スレッド ハンドルを取得する。
GetThreadID | スレッドの識別子を取得する。
GetThreadPriority | 現在のスレッドの優先度を取得する。
PutThreadMsg | ワーカー スレッドによって実行される要求をキューに入れる。
ResumeThread | ワーカー スレッドの処理を続行する。
SetThreadPriority | スレッドの優先度を新しい値に設定する。
SuspendThread | 実行中のスレッドの処理をポーズする。
WaitForThreadExit | CMsgThread::SuspendThread メンバ関数を呼び出した後、スレッドが終了するまでブロックする。

オーバーライド可能なメンバ関数

GetThreadMsg | 要求を格納するキューに入れられた CMsg オブジェクトを取得する。
OnThreadInit | スレッドについての初期化を提供する。
ThreadMessageProc | 要求を処理する。これは純粋仮想メンバ関数である。

CMsgThread::CMsgThread

CMsgThread クラス

CMsgThread オブジェクトを作成する。

構文

CMsgThread(void);

戻り値

戻り値なし。

注意

メッセージ スレッド オブジェクトを作成しても、スレッドは自動的に作成されない。スレッドを作成するには、CMsgThread::CreateThread メンバ関数を呼び出す必要がある。

CMsgThread::CreateThread

CMsgThread クラス

スレッドを作成する。

構文

BOOL CreateThread(void);

戻り値

次のいずれかの値を返す。
TRUE | スレッドが正しく作成された。
FALSE | スレッドが正しく作成されなかった。

注意

スレッドはループ処理を実行し、要求が CMsgThread::PutThreadMsg メンバ関数によってキューに入れられるまでブロックした後、各メッセージについて CMsgThread::ThreadMessageProc メンバ関数を呼び出す。

CMsgThread::GetThreadHandle

CMsgThread クラス

CMsgThread オブジェクト内のスレッドのハンドルを取得する。

構文

HANDLE GetThreadHandle(void);

戻り値

スレッド ハンドルを返す。

注意

スレッド ハンドルは、WaitForMultipleObjects などの Microsoft® Win32® アプリケーション プログラミング インターフェイス (API) 関数に渡すことができる。スレッド ハンドルは、スレッドが終了すると通知済になる。

CMsgThread::GetThreadID

CMsgThread クラス

スレッドの識別子を取得する。

構文

DWORD GetThreadID(void);

戻り値

プライベート データ メンバ m_ThreadId を返す。

注意

この関数は、ワーカー スレッドの Microsoft Win32 識別子を返す。ワーカー スレッドまたはクライアント スレッドのいずれかについて、このメンバ関数を呼び出すことができる。

CMsgThread::GetThreadMsg

CMsgThread クラス

要求を格納するキューに入れられた CMsg オブジェクトを取得する。

構文

void virtual GetThreadMsg(
CMsg *msg
    );

パラメータ

msg
割り当てられた CMsg オブジェクトへのポインタ。

注意

このメンバ関数は、ワーカー スレッドのプライベート関数 ThreadProc から呼び出されて、次のメンバ関数を取得する。msg パラメータは、キュー内の次の要求へのパラメータが格納される、割り当てられた CMsg オブジェクトを指す必要がある。キューに入れられた要求がない場合、このメンバ関数は CMsgThread::PutThreadMsg を呼び出して、次の要求がキューに入れられるまでブロックする。

CMsgThread::GetThreadPriority

CMsgThread クラス

Microsoft Win32 GetThreadPriority 関数を使用して、現在のワーカー スレッドの優先度を取得する。

構文

int GetThreadPriority(void);

戻り値

スレッドの優先度を整数として返す。

CMsgThread::OnThreadInit

CMsgThread クラス

スレッドについての初期化を提供する。

構文

virtual void OnThreadInit(void);

戻り値

戻り値なし。

注意

スレッドの起動時に独自の初期化を実行する場合は、この関数をオーバーライドする。

CMsgThread::PutThreadMsg

CMsgThread クラス

ワーカー スレッドによって実行される要求をキューに入れる。

構文

void PutThreadMsg(
UINT uMsg,
DWORD dwMsgFlags,
LPVOID lpMsgParam,
CAMEvent *pEvent = NULL
    );

パラメータ

uMsg
要求コード。
dwMsgFlags
オプションのフラグ パラメータ。
lpMsgParam
追加のパラメータまたは戻り値を格納するデータ ブロックへのオプションのポインタ。静的またはヒープによって割り当てられていなければならず、自動的であってはならない。
pEvent
完了時に通知済になるイベント オブジェクトへのオプションのポインタ。

戻り値

戻り値なし。

注意

このメンバ関数は、ワーカー スレッドによって実行される要求をキューに入れる。このメンバ関数のパラメータは CMsg オブジェクトとしてキューに入れられ、ワーカー スレッドの CMsgThread::ThreadMessageProc メンバ関数に渡される。このメンバ関数は要求をキューに入れた後、直ちに戻り、スレッドが要求を実行するまで待機しない。派生クラスの CMsgThread::ThreadMessageProc メンバ関数で 4 つのパラメータを定義する。

このメンバ関数はマルチスレッドで安全なリストを使用するので、異なるスレッドからこのメンバ関数を安全に複数呼び出すことができる。

CMsgThread::ResumeThread

CMsgThread クラス

Microsoft Win32 ResumeThread 関数を使用して、以前に CMsgThread::SuspendThread メンバ関数を呼び出した後のワーカー スレッドの処理を続行する。

構文

DWORD ResumeThread(void);

戻り値

このメンバ関数が成功した場合、戻り値は以前のスレッドのポーズ カウントである。このメンバ関数が失敗した場合、戻り値は 0xFFFFFFFF である。拡張エラー情報を取得するには、Microsoft Win32 GetLastError 関数を呼び出す。

CMsgThread::SetThreadPriority

CMsgThread クラス

Microsoft Win32 SetThreadPriority 関数を使用して、スレッドの優先度を新しい値に設定する。

構文

BOOL SetThreadPriority(
int nPriority
    );

パラメータ

nPriority
スレッドの優先度。

戻り値

次のいずれかの値を返す。
TRUE | 優先度が正しく設定された。
FALSE | 優先度が設定されなかった。

注意

クライアントおよびワーカー スレッドはこのメンバ関数を呼び出すことができる。

CMsgThread::SuspendThread

CMsgThread クラス

Microsoft Win32 SuspendThread 関数を使用して、実行中のスレッドの処理をポーズする。

構文

DWORD SuspendThread(void);

戻り値

このメンバ関数が成功した場合、戻り値は以前のスレッドのポーズ カウントである。このメンバ関数が失敗した場合、戻り値は 0xFFFFFFFF である。拡張エラー情報を取得するには、Microsoft Win32 GetLastError 関数を呼び出す。

注意

クライアントはこのメンバ関数を呼び出して、ワーカー スレッドの処理をポーズする。ワーカー スレッドはポーズされ、CMsgThread::ResumeThread メンバ関数が次に呼び出されるまで実行されない。

CMsgThread::ThreadMessageProc

CMsgThread クラス

要求を処理する。これは純粋仮想メンバ関数である。

構文

virtual LRESULT ThreadMessageProc(
UINT uMsg,
DWORD dwFlags,
LPVOID lpParam,
CAMEvent *pEvent
    );

パラメータ

uMsg
要求コード。
dwFlags
要求に対するオプションのフラグ パラメータ。
lpParam
追加のデータまたは戻りデータ ブロックへのオプションのポインタ。
pEvent
イベント オブジェクトへのオプションのポインタ。

戻り値

戻り値が 0 以外の場合、スレッドは終了する。終了要求が最近処理されたばかりである場合以外は、0 を返す。

注意

この純粋仮想関数は派生クラスでオーバーライドしなければならない。このメンバ関数は、CMsgThread::PutThreadMsg メンバ関数の呼び出しによってキューに入れられた各要求について 1 回呼び出される。

このメンバ関数は 4 つのパラメータを定義する。通常、uMsg パラメータを使用して要求を指定し、ほかの 3 つのパラメータはオプションの追加パラメータである。呼び出し元アプリケーションで必要な場合は、pEvent パラメータで CAMEvent オブジェクトへのポインタを指定できる。このイベントは、イベントを処理した後で、次のような式を使用して設定できる。

pEvent->SetEvent

ワーカー スレッドに終了を指示するために、1 つの要求コードを別に設定しなければならない。この要求を受信したら、このメンバ関数から 1 を返す。ワーカー スレッドを終了しない場合は 0 を返す。

CMsgThread::WaitForThreadExit

CMsgThread クラス

スレッドが終了するまでブロックする。

構文

BOOL WaitForThreadExit(
LPDWORD lpdwExitCode
    );

パラメータ

lpdwExitCode
スレッドによって返された終了コードへのポインタ。

戻り値

TRUE または FALSE のいずれかを返す。これらの意味はオーバーライドされた CMsgThread::ThreadMessageProc メンバ関数を提供するクラスおよび呼び出し元のメンバ関数によって決まる。

注意

派生クラスの破棄を完了する前に、ワーカー スレッドが完全に終了していることを確認する。そうしないと、ダイナミックリンク ライブラリ (DLL) がプロセスのアドレス空間からアンロードされた後もスレッドが実行されることになる。終了せずに残った命令が戻り値 1 つの命令であっても、これは例外を発生させる。スレッドが終了していることを確認する確実な方法は、( CMsgThread::PutThreadMsg メンバ関数に送信される、プライベートにネゴシエートした CMsg オブジェクトを使用して) スレッドに終了するように通知した後、このメンバ関数を呼び出す方法だけである。派生クラスのデストラクタでこの処理を行う必要がある。


COARefTime クラス

秒と 100 ナノ秒の間で基準時間の単位を変換する。

宣言 : Ctlutil.h

このクラスはオートメーション互換の基準タイムと C/C++ 互換の基準タイムの変換を行う。オートメーション互換のインターフェイスは double 値を使い秒で時間を表現する。他のインターフェイスは 64 ビット LONGLONG 値を使い 100 ナノ秒単位で時間を表現する。これらの値には次のタイプが定義されている :

typedef LONGLONG  REFERENCE_TIME;
typedef double    REFTIME;

フィルタは COARefTime クラスを使ってこの 2 つのフォーマット間の変換が可能だ。このクラスは CRefTime クラスから派生する。

メンバ関数

Public Methods
COARefTime | コンストラクタ メソッド。
演算子
double | 基準タイムを double 値に変換する。
REFERENCE_TIME | 基準タイムを REFERENCE_TIME 値で取得する。
Operator = | 新しい基準タイムをアサインする。
Operator == | 2 つの基準タイムが等しいことをテストする。
Operator != | 2 つの基準タイムが等しくないことをテストする。
Operator < | 1 つの基準タイムがもう 1 つより小さいかどうかをテストする。
Operator > | 1 つの基準タイムがもう 1 つより大きいかどうかをテストする。
Operator <= | 1 つの基準タイムがもう 1 つの基準タイム以下かどうかをテストする。
Operator >= | 1 つの基準タイムがもう 1 つの基準タイム以上かどうかをテストする。
Operator + | 2 つの基準タイムを加算する。
Operator – | 1 つの基準タイムからもう 1 つの基準タイムを減算する。
Operator += | 2 つの基準タイムを加算して、このオブジェクトにその結果を設定する。
Operator –= | 1 つの基準タイムからもう 1 つの基準タイムを減算して、このオブジェクトにその結果を設定する。
Operator * | 基準タイムを乗算する。
Operator / | 基準タイムを除算する。

COARefTime::COARefTime

COARefTime クラス

コンストラクタ メソッド。

構文

COARefTime(void);

COARefTime(
    CRefTime crt
);

COARefTime(
    REFERENCE_TIME t
);

COARefTime(
    double d
);

パラメータ

crt
基準タイムを示す CRefTime オブジェクト。
t
100 ナノ秒単位での基準タイムを示す REFERENCE_TIME 値。
d
秒単位での基準タイムを示す double 値

注意

デフォルトでは基準タイムはゼロ。

COARefTime::double

COARefTime クラス

基準タイムを double 値に変換する。

構文

operator double();

戻り値

基準タイムを秒単位で返す。

COARefTime::REFERENCE_TIME

COARefTime クラス

基準タイムを REFERENCE_TIME 値で取得する

構文

operator REFERENCE_TIME();

戻り値

基準タイムを 100 ナノ秒単位で返す。

COARefTime::Operator =

COARefTime クラス

新しい基準タイムをアサインする。

構文

COARefTime& operator=(
    const double& rd
);

COARefTime& operator=(
    const REFERENCE_TIME& rt
);

パラメータ

rd
秒単位の新しい基準タイムを示す double 値への参照。
rt
100 ナノ秒単位の新しい基準タイムを示す REFERENCE_TIME 値への参照

戻り値

オブジェクトへの参照を返す。

COARefTime::Operator ==

COARefTime クラス

2 つの基準タイムが等しいことをテストする。

構文

BOOL operator==(
    const COARefTime& rt
);

パラメータ

rt
比較する COARefTime オブジェクトへの参照。

戻り値

2 つのオブジェクトが等しければ TRUE を返す。それ以外なら FALSE を返す。

COARefTime::Operator !=

COARefTime クラス

2 つの基準タイムが等しくないことをテストする。

構文

BOOL operator!=(
    const COARefTime& rt
);

パラメータ

rt
比較する COARefTime オブジェクトへの参照。

戻り値

2 つのオブジェクトが等しくなければ TRUE を返す。それ以外なら FALSE を返す。

COARefTime::Operator <

COARefTime クラス

1 つの基準タイムがもう 1 つより小さいかどうかをテストする。

構文

BOOL operator < (
    const COARefTime& rt
);

パラメータ

rt
比較する COARefTime オブジェクトへの参照。

戻り値

このオブジェクトが厳密に rt より小さければ TRUE を返す。それ以外なら FALSE を返す。

COARefTime::Operator >

COARefTime クラス

1 つの基準タイムがもう 1 つより大きいかどうかをテストする。

構文

BOOL operator > (
    const COARefTime& rt
);

パラメータ

rt
比較する COARefTime オブジェクトへの参照。

戻り値

このオブジェクトが厳密に rt より大きければ TRUE を返す。 それ以外なら FALSE を返す。

COARefTime::Operator >=

COARefTime クラス

1 つの基準タイムがもう 1 つの基準タイム以上かどうかをテストする。

構文

BOOL operator >= (
    const COARefTime& rt
);

パラメータ

rt
比較する COARefTime オブジェクトへの参照。

戻り値

このオブジェクトが rt 以上なら TRUE を返す。 それ以外なら FALSE を返す。

COARefTime::Operator <=

COARefTime クラス

1 つの基準タイムがもう 1 つの基準タイム以下かどうかをテストする。

構文

BOOL operator <= (
    const COARefTime& rt
);

パラメータ

rt
比較する COARefTime オブジェクトへの参照。

戻り値

このオブジェクトが rt 以下なら TRUE を返す。それ以外なら FALSE を返す。

COARefTime::Operator +

COARefTime クラス

2 つの基準タイムを加算する。

構文

COARefTime operator+(
    const COARefTime& rt
);

パラメータ

rt
加算する COARefTime オブジェクトへの参照。

戻り値

基準タイムの加算結果と等しい COARefTime オブジェクトを返す。

COARefTime::Operator –

COARefTime クラス

1 つの基準タイムからもう 1 つの基準タイムを減算する。

構文

COARefTime operator-(
    const COARefTime& rt
);

パラメータ

rt
減算する COARefTime オブジェクトへの参照。

戻り値

基準タイムの差と等しい COARefTime オブジェクトを返す。

COARefTime::Operator +=

COARefTime クラス

2 つの基準タイムを加算して、このオブジェクトにその結果を設定する。

構文

COARefTime& operator+=(
    const COARefTime& rt
);

パラメータ

rt
加算する COARefTime オブジェクトへの参照。

戻り値

オブジェクトへの参照を返す。

COARefTime::Operator –=

COARefTime クラス

1 つの基準タイムからもう 1 つの基準タイムを減算して、このオブジェクトにその結果を設定する。

構文

COARefTime& operator-=(
    const COARefTime& rt
);

パラメータ

rt
減算する COARefTime オブジェクトへの参照。

戻り値

オブジェクトへの参照を返す。

COARefTime::Operator *

COARefTime クラス

基準タイムを乗算する。

構文

COARefTime operator*(
    LONG l
);

パラメータ

l
乗算する値

戻り値

このオブジェクトと l の乗算結果と等しい新しい COARefTime オブジェクトを返す。

COARefTime::Operator /

COARefTime クラス

基準タイムを除算する。

構文

COARefTime operator/(
    LONG l
    );

パラメータ

l
除算する値

戻り値

このオブジェクトと l の除算結果と等しい新しい COARefTime オブジェクトを返す。


COutputQueue クラス

メディア サンプルを出力するキューを実装する。

宣言 : Outputq.h

このクラスによって出力ピンはサンプルを非同期に出力することができる。サンプルはキューに置かれ、ワーカースレッドはそれを入力ピンに出力する。キューは新しいセグメント、エンドオブストリーム通知、あるいはフラッシュ処理を示すコントロール メッセージも保持する。

このクラスを使用するには、フィルタの出力ピンごとに COutputQueue オブジェクトを作成すること。コンストラクタ メソッドでその出力ピンに接続する入力ピンを指定すること。このクラスの使用中は、出力ピンは直接入力ピンを呼び出すことができない。代わりに、以下の表に示されているように COutputQueue の対応するメソッドを呼び出す :

Pin メソッド | COutputQueue メソッド
IPin::BeginFlush | BeginFlush
IPin::EndFlush | EndFlush
IPin::EndOfStream | EOS
IPin::NewSegment | NewSegment
MemInputPin::Receive | Receive
MemInputPin::ReceiveMultiple | ReceiveMultiple

オプションとして COutputQueue オブジェクトを構成して、ワーカースレッドを使わず同期を取ってサンプルを出力することができる。オブジェクトはランタイム時に、入力ピンの状態を基にワーカースレッドを使うかどうかを決めることもできる。詳細については、「COutputQueue::COutputQueue」を参照すること。

Protected メンバ変数
m_pPin | 入力ピンの IPin インターフェイスへのポインタ。
m_pInputPin | 入力ピンの IMemInputPin インターフェイスへのポインタ。
m_bBatchExact | オブジェクトが正確なバッチでサンプルを出力するかどうかを示すフラグ。
m_lBatchSize | バッチ サイズ。
m_List | メディア サンプル キュー。
m_hSem | セマフォへのハンドル、サンプルを待つスレッドによって使われる。
m_evFlushComplete | フラッシュ処理が終了したとき通知するイベント。
m_hThread | ワーカー スレッドへのハンドル。
m_ppSamples | m_lBatchSize サイズのサンプルの配列。
m_nBatched | 現在バッチされ処理を待っているサンプルの数。
m_lWaiting | スレッドがサンプルを待っているときゼロ以外の値を持つフラグ。
m_bFlushing | オブジェクトがフラッシュ処理を実行中かどうかを示すフラグ。
m_bTerminate | スレッドが終了すべきかどうかを示すフラグ。
m_bSendAnyway | バッチ プロセスをオーバーライドするフラグ。
m_hr | オブジェクトがサンプルを受け入れるかどうかを示す HRESULT 値。
m_hEventPop | オブジェクトがキューからサンプルを削除するたびに通知するイベント。
Protected メソッド
InitialThreadProc | スレッドが作成されたとき ThreadProc メソッドを呼び出す。
ThreadProc | サンプルをキューから取得し、それを入力ピンに出力する。
IsQueued | オブジェクトがワーカースレッドを使ってサンプルを出力しているかどうかを確認する。
QueueSample | メディア サンプルあるいはコントロール メッセージをキューに入れる。
IsSpecialSample | キューに入れられたデータがコントロール メッセージかどうかを確認する。
FreeSamples | すべての未処理のサンプルをフリーにする。
NotifyThread | スレッドにキューにデータが入っていることを知らせる。
Public メソッド
COutputQueue | コンストラクタ メソッド。
~COutputQueue | デストラクタ メソッド。
BeginFlush | フラッシュ処理の開始。
EndFlush | フラッシュ処理の終了。
EOS | 入力ピンにエンドオブストリーム呼び出しを出力する。
SendAnyway | 未処理のすべてのサンプルを出力する。
NewSegment | 入力ピンに新しいセグメントを出力する。
Receive | 入力ピンにメディア サンプルを出力する。
ReceiveMultiple | メディア サンプルのバッチを入力ピンに出力する。
Reset | オブジェクトをリセットし、再びデータを受け取れるようにする。
IsIdle | オブジェクトがデータを待っているかどうかを確認する。
SetPopEvent | オブジェクトがキューからサンプルを削除したかどうかを通知するイベントを指定する。

COutputQueue.m_pPin

COutputQueue クラス

入力ピンの IPin インターフェイスへのポインタ。

構文

IPin * const m_pPin;

COutputQueue.m_pInputPin

COutputQueue クラス

入力ピンの IMemInputPin インターフェイスへのポインタ。

構文

IMemInputPin *m_pInputPin;

COutputQueue.m_bBatchExact

COutputQueue クラス

オブジェクトが正確なバッチでサンプルを出力するかどうかを示すフラグ。

構文

BOOL const m_bBatchExact;

注意

この値が TRUE なら、オブジェクトは出力前にメディア サンプルのバッチが完成するまで待つ。それ以外なら、サンプルを受け取るとすぐそれを出力する。m_lBatchSize メンバ変数はバッチのサイズを定義する。

COutputQueue.m_lBatchSize

COutputQueue クラス

バッチ サイズ。

構文

LONG const m_lBatchSize;

COutputQueue.m_List

COutputQueue クラス

メディア サンプル キュー。

構文

typedef CGenericList<IMediaSample> CSampleList;
CSampleList *m_List;

注意

IMediaSample ポインタを保持するために特殊化された CGenericList クラス テンプレートへのポインタ。

COutputQueue.m_hSem

COutputQueue クラス

セマフォへのハンドル、サンプルを待つスレッドによって使われる。

構文

HANDLE m_hSem;

COutputQueue.m_evFlushComplete

COutputQueue クラス

フラッシュ処理が終了したとき通知するイベント。

構文

CAMEvent m_evFlushComplete;

COutputQueue.m_hThread

COutputQueue クラス

ワーカー スレッドへのハンドル。

構文

HANDLE m_hThread;

COutputQueue.m_ppSamples

COutputQueue クラス

m_lBatchSize サイズのサンプルの配列。

構文

IMediaSample  **m_ppSamples;

注意

ワーカー スレッドはサンプルをキュー (m_List) から引き抜いて、それをこの配列に入れる。それは配列を IMemInputPin::ReceiveMultiple メソッドに渡す。オブジェクトがワーカー スレッドを使わなければ、オブジェクトはサンプルをこの配列に直接入れる。

COutputQueue.m_nBatched

COutputQueue クラス

現在バッチされ処理を待っているサンプルの数。

構文

LONG m_nBatched;

COutputQueue.m_lWaiting

COutputQueue クラス

スレッドがサンプルを待っているときゼロ以外の値を持つフラグ。

構文

LONG m_lWaiting;

COutputQueue.m_bFlushing

COutputQueue クラス

オブジェクトがフラッシュ処理を実行中かどうかを示すフラグ。TRUE ならオブジェクトはフラッシュを開始している。

構文

BOOL m_bFlushing;

COutputQueue.m_bTerminate

COutputQueue クラス

スレッドが終了すべきかどうかを示すフラグ。 TRUE ならスレッドは終了する。

構文

BOOL m_bTerminate;

COutputQueue.m_bSendAnyway

COutputQueue クラス

バッチ プロセスをオーバーライドするフラグ。このフラグを TRUE にすると、m_bBatchExact フラグをオーバーライドし、すべての未処理サンプルを出力する。

構文

BOOL m_bSendAnyway;

COutputQueue.m_hr

COutputQueue クラス

オブジェクトがサンプルを受け入れるかどうかを示す HRESULT 値。この値が S_OK なら、オブジェクトはサンプルを受け入れる。それ以外なら、サンプルを拒否する。

構文

BOOL volatile m_hr;

注意

このメンバ変数はスレッド間の動作を調整する。入力ピンへのダウンストリームがサンプルを拒否する、あるいはオブジェクトがフラッシュを開始するなら、この値には S_FALSE かエラー コードがセットされる。オブジェクトはフラッシュが完了する、あるいは Reset メソッドが終了するまで、それ以降のサンプルを出力しない。

COutputQueue.m_hEventPop

COutputQueue クラス

オブジェクトがキューからサンプルを削除するたびに通知済になるオプション イベント。この値は NULL で初期化される。SetPopEvent メソッドを呼び出して、イベントハンドルを指定すること。

構文

HANDLE m_hEventPop;

COutputQueue::BeginFlush

COutputQueue クラス

フラッシュ処理の開始。

構文

void BeginFlush(void);

注意

このメソッドは m_bFlushing メンバ変数を TRUE に設定する。オブジェクトがスレッドを使っているなら、そのスレッドは FreeSamples メソッドを呼び出して未処理のサンプルをフリーにする。スレッドを使っていなければ、オブジェクトは COutputQueue::EndFlush メソッドの間に FreeSamples を呼び出す。このメソッドはまた m_hr メンバ変数を S_FALSE にセットし、オブジェクトにすべての新しいサンプルを放棄させる。

オブジェクトは入力ピンの IPin::BeginFlush メソッドを呼び出すことでダウンストリームにフラッシュ通知を渡す。

COutputQueue::COutputQueue

COutputQueue クラス

コンストラクタ メソッド。

構文

COutputQueue(
    IPin *pInputPin,
    HRESULT *phr,
    BOOL bAuto = TRUE,
    BOOL bQueue = TRUE,
    LONG lBatchSize = 1,
    BOOL bBatchExact = FALSE,
    LONG lListSize = DEFAULTCACHE,
    DWORD dwPriority = THREAD_PRIORITY_NORMAL
);

パラメータ

pInputPin
入力ピンの IPin インターフェイスへのポインタ。オブジェクトはこのピンにサンプルを出力する。
phr
HRESULT 戻り値へのポインタ。このメソッドを呼び出す前にこの値を S_OK に設定すること。返ったとき phr はメソッドの成功/失敗を示す値を返す。
bAuto
キューを作る時だとオブジェクトが決めたかどうかを指定するフラグ。TRUE なら、入力ピンがブロックしない場合にのみオブジェクトはキューを作成する。FALSE なら、bQueue パラメータがキューを作成するかどうかを指定する。
bQueue
bAuto が TRUEなら、このパラメータは無視される。bAuto が FALSE ならこのフラグはキューを作るかどうかを指定する。
lBatchSize
1 つのバッチに出力されるサンプルの最大数。
bBatchExact
正確なバッチ サイズを使うかどうかを指定するフラグ。TRUE なら、オブジェクトは入力ピンにそれらを出力する前に lBatchSize までサンプルを待つ。FALSE なら、オブジェクトはサンプルを受け取るとすぐ出力する。
lListSize
キューのキャッシュ サイズ。デフォルト値 DEFAULTCACHE は CBaseList クラスで定義される定数である。
dwPriority
サンプルを出力するスレッドの優先度。

注意

bAuto が TRUE なら、オブジェクトはダウンストリーム ピンの IMemInputPin::ReceiveCanBlock メソッドを呼び出す。ReceiveCanBlock が S_OK を返すなら (ピンが Receive 呼び出しでブロックするかもしれないことを意味する)、オブジェクトはサンプルを出力するスレッドを作成する。そうでなければ、オブジェクトはスレッドを作成しない。

bAuto が FALSE なら、bQueue の値がスレッドを作成するかどうかを決める。

オブジェクトがスレッドを作成するなら、オブジェクトはスレッド ハンドルを m_hThread メンバ変数にアサインする。スレッド プロシージャは InitialThreadProc であり、スレッド パラメータは this へのポインタである。オブジェクトはまたサンプルを保持するキューを作成する、それは m_List メンバ変数によって与えられる。

COutputQueue::~COutputQueue

COutputQueue クラス

デストラクタ メソッド。

構文

~COutputQueue(void);

COutputQueue::EndFlush

COutputQueue クラス

フラッシュ処理の終了。

構文

void EndFlush(void);

注意

オブジェクトがスレッドを使っているなら、このメソッドは m_evFlushComplete イベントを待つ。メソッドは未処理のサンプルをフリーにした後でこのイベントを通知する。オブジェクトがスレッドを使っていないなら、このメソッドは FreeSamples メソッドを呼び出す。

次に EndFlush メソッドは入力ピンの IPin::EndFlush を呼び出す。

COutputQueue::EOS

COutputQueue クラス

入力ピンにエンドオブストリーム呼び出しを出力する。

構文

void EOS(void);

注意

オブジェクトがスレッドを使っているなら、EOS_PACKET コントロール メッセージをキューに入れる。スレッドはすべての未処理のサンプルを出力し、入力ピンの IPin::EndOfStream メソッドを呼び出す。

オブジェクトがスレッドを使っていないなら、SendAnyway メソッドを呼び出して未処理のサンプルを出力する。次にオブジェクトは入力ピンの IPin::EndOfStream を呼び出す。

COutputQueue::FreeSamples

COutputQueue クラス

すべての未処理のサンプルをフリーにする。

構文

void FreeSamples(void);

注意

このメソッドはキューとサンプル配列 (m_ppSamples) からすべての未処理のサンプルを削除する。

COutputQueue::InitialThreadProc

COutputQueue クラス

スレッドが作成されたとき ThreadProc メソッドを呼び出す。

構文

static DWORD WINAPI InitialThreadProc(
    LPVOID pv
);

パラメータ

pv
this ポインタ。

戻り値

ThreadProc が返した値を返す。

注意

このメソッドはオブジェクトのワーカー スレッドのスレッド プロシージャである。オブジェクトの this ポインタはスレッド パラメータである。メソッドは this への参照を解除して、ThreadProc メソッドを呼び出す。

COutputQueue::IsIdle

COutputQueue クラス

オブジェクトがデータを待っているかどうかを確認する。

構文

BOOL IsIdle(void);

戻り値

スレッドが待っていて、サンプル配列がカラなら TRUE を返す。それ以外なら FALSE を返す。

COutputQueue::IsQueued

COutputQueue クラス

オブジェクトがワーカースレッドを使ってサンプルを出力しているかどうかを確認する。

構文

BOOL IsQueued(void);

戻り値

オブジェクトがワーカースレッドを使っているなら TRUE を返す、そうでなければ FALSE を返す。

COutputQueue::IsSpecialSample

COutputQueue クラス

キューに入れられたデータがコントロール メッセージかどうかを確認する。

構文

BOOL IsSpecialSample(
    IMediaSample *pSample
);

パラメータ

pSample
キュー内の項目へのポインタ。

戻り値

pSample がコントロール メッセージなら TRUE を返す、そうでなければ FALSE を返す。

注意

QueueSample メソッドはメディア サンプルに加えコントロールメッセージを受け取ることができる。コントロール メッセージはスレッドにある動作を指示する (LONG_PTR タイプにキャストされる) 定義済みの定数である。コントロール メッセージはメディア データを含まない。詳細については、「QueueSample」を参照すること。

COutputQueue::NewSegment

COutputQueue クラス

入力ピンに新しいセグメントを出力する。

構文

HRESULT NewSegment(
    REFERENCE_TIME tStart,
    REFERENCE_TIME tStop,
    double dRate
);

パラメータ

tStart
[in] セグメントの開始メディア位置、100ナノ秒単位。
tStop
[in] セグメントの終了メディア位置、100ナノ秒単位。
dRate
[in] このセグメントが処理されるべきレート、オリジナル レートのパーセンテージ。

戻り値

Returns an HRESULT value.

注意

オブジェクトがスレッドを使っているなら、それは次の項目を順番にキューに入れる :

  • NEW_SEGMENT コントロール メッセージ
  • セグメント データ。

The NEW_SEGMENT メッセージはスレッドにキューの次の項目にセグメント データが入っていることを知らせる。セグメント データは次に宣言される構造体に格納されている :

struct NewSegmentPacket {
    REFERENCE_TIME tStart;
    REFERENCE_TIME tStop;
    double dRate;
};

スレッドはこの構造体で与えられたデータを使って、入力ピンの IPin::NewSegment メソッドを呼び出す。

オブジェクトがスレッドを使っていないなら、SendAnyway メソッドを呼び出してすべての未処理のサンプルを出力する。次にオブジェクトは入力ピンの IPin::NewSegment を呼び出す。

COutputQueue::NotifyThread

COutputQueue クラス

スレッドにキューにデータが入っていることを知らせる。

構文

void NotifyThread(void);

注意

このメソッドを呼び出す前にクリティカル セクションを保持すること。

COutputQueue::QueueSample

COutputQueue クラス

サンプルをキューに入れる。

構文

void QueueSample(
    IMediaSample *pSample
);

パラメータ

pSample
サンプルの IMediaSample インターフェイスへのポインタ。

注意

このメソッドはサンプルをキューの末尾 (m_List) に追加する。このメソッドを呼び出す前にクリティカル セクションを保持すること、そしてオブジェクトがスレッドを使ってサンプルを出力しているときにはそれを呼び出すこと。オブジェクトがスレッドを使っているかどうかを確認するには、IsQueued メソッドを呼び出すこと。

このメソッドはコントロールメッセージをキューに置くために用いることもできる。コントロール メッセージはスレッドにある動作を指示する (LONG_PTR タイプにキャストされる) 定義済みの定数である。COutputQueue クラスは次の表に示されるコントロール メッセージを定義する :

メッセージ | 動作
EOS_PACKET | エンドオブストリーム通知を出力する。
NEW_SEGMENT | 新しいセグメントを出力する。
RESET_PACKET | キューの状態をリセットする。
SEND_PACKET | サンプルの部分的バッチを送る。

これは COutputQueue クラスが最初に使うプロテクト メソッドである。

COutputQueue::Receive

COutputQueue クラス

入力ピンにメディア サンプルを出力する。

構文

HRESULT Receive(
    IMediaSample *pSample
);

パラメータ

pSample
サンプルの IMediaSample インターフェイスへのポインタ。

戻り値

HRESULT 値を返す。以下の表に示されるいずれかの値を。

S_FALSE | このサンプルを処理する前にエンドオブストリーム通知を受け取った。
S_OK | 成功。

注意

このメソッドは COutputQueue::ReceiveMultiple メソッドを呼び出す。

COutputQueue::ReceiveMultiple

COutputQueue クラス

メディア サンプルのバッチを入力ピンに出力する。

構文

HRESULT ReceiveMultiple (
    IMediaSample **ppSamples,
    long nSamples,
    long *nSamplesProcessed
);

パラメータ

ppSamples
サンプル配列へのポインタのアドレス。
nSamples
配列内のサンプルの数。
nSamplesProcessed
出力に成功したサンプルの数を受け取る変数へのポインタ。

戻り値

HRESULT 値を返す。 以下の表に示されるいずれかの値。

S_FALSE | このサンプルを処理する前にエンドオブストリーム通知を受け取った。
S_OK | 成功。

注意

オブジェクトがスレッドを使っているなら、このメソッドは配列内で未処理のすべてのサンプルをキューに入れる。そうでなければ、このメソッドは入力ピンの IMemInputPin::ReceiveMultiple メソッドを呼び出す。

COutputQueue::Reset

COutputQueue クラス

オブジェクトをリセットし、再びデータを受け取れるようにする。

構文

void Reset(void);

戻り値

戻り値なし。

注意

このメソッドは m_hr メンバ変数を S_OK にリセットする。オブジェクトはメディア サンプルを再び受け取ることができる、たとえばフラッシュ処理の後。

COutputQueue::SendAnyway

COutputQueue クラス

未処理のすべてのサンプルを出力する。

構文

void SendAnyway(void);

注意

If the m_bBatchExact メンバ変数が TRUE なら、オブジェクトはサンプルのバッチを出力する前に m_ppSamples 配列にオブジェクトを入れる。たとえば、EOS メソッドは SendAnyway を呼び出してエンドオブストリーム メッセージを処理する。

COutputQueue::SetPopEvent

COutputQueue クラス

オブジェクトがキューからサンプルを削除したかどうかを通知するイベントを指定する。

構文

void COutputQueue::SetPopEvent(
    HANDLE hEvent
);

構文

hEvent
呼び出し元によって作成されたイベントへのハンドル。

COutputQueue::ThreadProc

COutputQueue クラス

サンプルをキューから取得し、それを入力ピンに出力する。

構文

DWORD ThreadProc(void);

戻り値

ゼロを返す。

注意

InitialThreadProc メソッドはこのメソッドを呼び出して、メインのスレッドループを実装する。そのループの中で、メソッドは次のステップを行う :

  1. キュー (m_List) のサンプルを取得する。
  2. サンプルがコントロール メッセージなら、スレッドはコントロール動作を実行する。そうでなければ、サンプルを m_ppSamples 配列に入れる。
  3. その配列がいっぱいなら (あるいは m_bBatchExact が FALSE なら) スレッドは IMemInputPin::ReceiveMultiple メソッドを呼び出してサンプルを出力する。
  4. キュー内にサンプルがなければ、スレッドは m_hSem セマフォで待つ。

スレッドは m_bTerminate メンバ変数が TRUE になると終了する。


CPersistStream クラス

CPersistStream は、フィルタの永続的なプロパティ (保存されたグラフのフィルタ プロパティ) の基底クラスである。

CPersistStream を使用する簡単な方法は次のとおりである。

  1. フィルタがこのクラスを継承するようにする。
  2. クラスに WriteToStream および ReadFromStream を実装する。これらの方法はここで示されている、プレースホルダとしてのみ機能する関数をオーバーライドする。
  3. NonDelegatingQueryInterface を、IPersistStream を処理するように変更する。
  4. 保存するデータのバイト数の上限を返す SizeMax を実装する。

    Unicode™ のデータを保存する場合は、WCHAR が 2 バイトであることに留意する。

  5. データが変更されたときに、SetDirty を呼び出す。

バージョン番号

ある時点で、データのフォーマットを変更または拡張したい場合がある。この場合、以前に保存したすべてのストリームにバージョン番号を付けて、ストリームを読み取ったときに、ストリームが古いフォーマットであるか、新しいフォーマットであるかを区別できるようにする必要がある。これを行うために、このクラスはバージョン番号の読み書きを行う。書き込み時には、このクラスは GetSoftwareVersion を呼び出して、そのときに使用されているソフトウェアのバージョンを問い合わせる。実質的に、これがファイル内のデータ レイアウトのバージョン番号になる。このクラスは、データ内の最初の項目としてこれを書き込む。バージョン番号を変更する場合は、GetSoftwareVersion を実装 (オーバーライド) する。このクラスは、ReadFromStream を呼び出す前に、ファイルから mPS_dwFileVersion にバージョン番号を読み取るので、ReadFromStream で mPS_dwFileVersion をチェックして、古いバージョンのファイルを読み取っているかどうかを確認できる。通常、ファイルを読み取るソフトウェアのバージョン以前のバージョンのファイルを受け入れる必要がある。

プロテクト データ メンバ

mPS_dwFileVersion | ファイルのバージョン番号。
mPS_fDirty | このストリームのデータを保存しなければならない。

メンバ関数

CPersistStream | CPersistStream オブジェクトを作成する。
SetDirty | オブジェクトをストリームに保存しなければならないことを指定する。

オーバーライド可能なメンバ関数

GetClassID | このストリームのクラス識別子を取得する。
GetSoftwareVersion | このファイル フォーマットのバージョン番号を取得する。
ReadFromStream | ストリームからフィルタのデータを読み取る。
SizeMax | データで必要なバイト数 (バージョン番号を含まない) を取得する。
WriteToStream | ストリームにフィルタのデータを書き込む。

CPersistStream は IPersistStream を実装する。実装の詳細については、Microsoft Platform SDK の「COM リファレンス」を参照すること。

実装される IPersistStream メソッド

GetSizeMax | データで必要なバイト数 (バージョン番号を含む) を取得する。
IsDirty | オブジェクトを保存しなければならないかどうかをチェックする。
Load | データをストリームからメモリにロードする。
Save | データをメモリからストリームに保存する。

CPersistStream::CPersistStream

CPersistStream クラス

CPersistStream オブジェクトを作成する。

構文

CPersistStream(
IUnknown *pUnk,
HRESULT *phr
);

パラメータ

pUnk
委任オブジェクトの IUnknown インターフェイスへのポインタ。
phr
一般的な COM 戻り値へのポインタ。この値は、この関数が失敗した場合にのみ変更される。

戻り値

戻り値なし。

CPersistStream::GetClassID

CPersistStream クラス

このフィルタのクラス識別子を取得する。

構文

HRESULT GetClassID(
CLSID *pClsID
);

パラメータ

pClsID
CLSID 構造体へのポインタ。クラス ID をここにコピーする。

戻り値

HRESULT 値を返す。

CPersistStream::GetSizeMax

CPersistStream クラス

バージョン番号を含む、現在のストリームに必要な最大バイト サイズを取得する。

構文

HRESULT GetSizeMax(
ULARGE_INTEGER *pcbSize
);

パラメータ

pcbSize
バージョン番号を含めて、このストリームを保存するために必要なバイト単位のサイズへのポインタ。

戻り値

HRESULT 値を返す。

注意

このメンバ関数は、IPersistStream::GetSizeMax メソッドを実装する。

CPersistStream::GetSoftwareVersion

CPersistStream クラス

このストリームのソフトウェア バージョンを取得する。

構文

virtual DWORD GetSoftwareVersion(void);

戻り値

バージョン番号を格納する DWORD 型の値を返す。ストリームのフォーマットが変更されるたびに、この関数を変更して以前よりも大きい数値を返すようにする必要がある。

注意

ファイル フォーマットのバージョン番号を使用する理由については、「バージョン番号」を参照すること。

CPersistStream::IsDirty

CPersistStream クラス

オブジェクトが現在のストリームに最後に保存された後、変更されたかどうかを示す。

構文

HRESULT IsDirty(void);

戻り値

フィルタを保存する必要がある場合は S_OK を返す。保存の必要がない場合は S_FALSE を返す。

注意

このメンバ関数は、IPersistStream::IsDirty メソッドを実装する。

CPersistStream::Load

CPersistStream クラス

指定されたストリームからフィルタのデータをロードする。

構文

HRESULT Load(
LPSTREAM pStm
);

パラメータ

pStm
ロード元のストリームへのポインタ。

戻り値

HRESULT 値を返す。

注意

このメンバ関数は、IPersistStream::Load メソッドを実装する。

CPersistStream::ReadFromStream

CPersistStream クラス

指定されたストリームからフィルタのデータを読み取る。

構文

virtual HRESULT ReadFromStream(
IStream *pStream
);

パラメータ

pStream
データが読み取られる IStream インターフェイスへのポインタ。

戻り値

デフォルトでは NOERROR を返す。オーバーライドするメンバ関数は、有効な HRESULT 値を返す。

注意

デフォルトのバージョンは何も読み取らない。これをオーバーライドして、クラスに固有のデータを読み取ることができる。

CPersistStream::Save

CPersistStream クラス

指定されたストリームにフィルタのデータを保存する。

構文

HRESULT Save(
LPSTREAM pStm,
BOOL fClearDirty
);

パラメータ

pStm
データが保存されるストリームへのポインタ。
fClearDirty
現在のストリームのダーティー フラグをリセットするかどうかを指定するフラグ。TRUE はダーティー フラグをリセットすることを意味する。Save 処理の中でこのメソッドを呼び出す場合、通常、この値は TRUE である。Save As 処理の中で呼び出す場合、通常、この値は FALSE である。

戻り値

HRESULT 値を返す。

注意

このメンバ関数は、IPersistStream::Save メソッドを実装する。このメンバ関数は、ソフトウェア バージョンを指定して WriteInt を呼び出し、pStm でストリームを指定して CPersistStream::WriteToStream を呼び出して、mPS_fDirty をリセットする。

CPersistStream::SetDirty

CPersistStream クラス

現在のストリームのダーティー フラグを変更する。

構文

HRESULT SetDirty(
BOOL fDirty
);

パラメータ

fDirty
このストリームの新しいダーティー フラグ。TRUE はデータが保存されていないことを意味する。

戻り値

HRESULT 値を返す。

CPersistStream::SizeMax

CPersistStream クラス

バージョン番号を含まない、現在のストリームに必要な最大バイト サイズを取得する。

構文

virtual int SizeMax(void);

戻り値

バージョン番号を含まない、データで必要なバイト数を返す。

注意

デフォルトのバージョンは 0 を返す。ほかの適切な値を返すには、これをオーバーライドする必要がある。

CPersistStream::WriteToStream

CPersistStream クラス

指定されたストリームにフィルタのデータを書き込む。

構文

virtual HRESULT WriteToStream(
IStream *pStream
);

パラメータ

pStream
フィルタ データの転送先ストリームを指定する IStream インターフェイスへのポインタ。

戻り値

デフォルトでは NOERROR を返す。オーバーライドするメンバ関数は、有効な HRESULT 値を返す。

注意

デフォルトのバージョンは何も書き込まない。これをオーバーライドして、クラスに固有のデータを書き込むことができる。


CPosPassThru クラス

自分自身ではシークを行わない入力ピンを持つフィルタのシーク コマンドを扱う。

宣言: Ctlutil.h

このヘルパー クラスはシーク コマンドをアップストリームに送るフィルタで IMediaPosition と IMediaSeeking インターフェイスを実装する。フィルタ グラフ マネージャがシーク コマンドをアプリケーションから受け取ったとき、そのコマンドをグラフのレンダリング フィルタに送る。そのコマンドは次に、(もしあれば)それを実行できるフィルタに到達するまで、各フィルタの出力ピンを通してアップストリームに送られる。通常、シークはソース フィルタかパーサー フィルタで実装される。

CPosPassThru クラスはフィルタの入力ピンへのポインタを保持する。以下のダイアグラムにあるように、それはシーク コマンドを接続されているアップストリーム フィルタの出力ピンに送る。

変換フィルタで CPosPassThru を使い、レンダリング フィルタで CRendererPosPassThru クラスを派生すること。

このクラスをフィルタで使うには、クラスのインターフェイスを作成し、CPosPassThru コンストラクタ メソッドのフィルタの入力ピンを指定すること。次にすべての IMediaPosition と IMediaSeeking 呼び出しを CPosPassThru オブジェクトに委任すること。

シーク コマンドを委任する最もシンプルな方法は CPosPassThru オブジェクトの IMediaPosition と IMediaSeeking インターフェイスを公開することだ。フィルタかピンがこれらのインターフェイスの 1 つを問い合わせたとき、そのインターフェイスの CPosPassThru 実装へのポインタが返る。次のコードはこの方法を示す。それは CTransformOutputPin クラスから適応されている。CreatePosPassThru 関数は CPosPassThru オブジェクトを作成するヘルパー関数である。

// 次のメンバ変数が仮定されている :
// CPosPassThru *m_pPos;
// IPin *m_pPin;

if (riid == IID_IMediaPosition || riid == IID_IMediaSeeking)
{
    if (m_pPos == NULL)
    {
        HRESULT hr;
        hr = CreatePosPassThru(GetOwner(), FALSE, m_pPin, &m_pPos);
        if (FAILED(hr))
            return hr;
    }
    return m_pPosition->QueryInterface(riid, ppv);
}
else
{
    // このピンの他のインターフェイスへのポインタを返す。
}

ここで説明している以外に、このクラスのすべての IMediaPosition と IMediaSeeking メソッドは接続しているピンの対応するメソッドを呼び出し、その結果を返す。

Public メソッド
CPosPassThru | コンストラクタ メソッド。
ForceRefresh | 使われていない。
GetMediaTime | 現在のサンプルのタイム スタンプを取得する。仮想。
IMediaPosition メソッド
get_Duration | ストリームの時間幅を取得する。
put_CurrentPosition | 現在の位置を設定する、ストリームの全時間幅からの相対値。
get_StopTime | 再生の終了タイムを取得する、ストリームの全時間幅からの相対値。
put_StopTime | 再生の終了タイムを設定する、ストリームの全時間幅からの相対値。
get_PrerollTime | 開始位置の前にキューに入るデータ量 (プリロール タイム) を取得する。
put_PrerollTime | 開始位置の前にキューに入るデータ量 (プリロール タイム) を設定する。
get_Rate | 再生レートを取得する。
put_Rate | 再生レートを設定する。
get_CurrentPosition | 現在位置を取得する、ストリームの全時間幅からの相対値。
CanSeekForward | ストリームが順方向にシークできるかどうかを確認する。
CanSeekBackward | ストリームが逆方向にシークできるかどうかを確認する。
IMediaSeeking メソッド
CheckCapabilities | ストリームに指定されたシーク能力を持つかどうかを問い合わせる。
ConvertTimeFormat | あるタイムフォーマットから別のフォーマットへ変換する。
GetAvailable | シークが効率的な時間幅を取得する。
GetCapabilities | ストリームのすべてのシーク能力を取得する。
GetCurrentPosition | 現在位置を取得する、ストリームの全時間幅からの相対値。
GetDuration | ストリームの時間幅を取得する。
GetPositions | 現在位置と停止位置を取得する、ストリームの全時間幅からの相対値。
GetPreroll | 開始位置の前にキューに入るデータ量 (プリロール タイム) を取得する。
GetRate | 再生レートを取得する。
GetStopPosition | 再生の終了タイムを取得する、ストリームの全時間幅からの相対値。
GetTimeFormat | 現在のタイム フォーマットを取得する。
IsFormatSupported | 指定したタイム フォーマットがサポートされているかどうかを確認する。
IsUsingTimeFormat | 指定したタイム フォーマットが現在使われているフォーマットかどうかを確認する。
QueryPreferredFormat | ストリームで許容されるタイム フォーマットを取得する。
SetPositions | 現在位置と停止位置を設定する。
SetRate | 再生レートを設定する。
SetTimeFormat | タイム フォーマットを設定する。
ヘルパー関数
CreatePosPassThru | CPosPassThru オブジェクトまたは CRendererPosPassThru オブジェクトを作成する。

CPosPassThru::CanSeekBackward

CPosPassThru クラス

ストリームが逆方向にシークできるかどうかを確認する。IMediaPosition::CanSeekBackward メソッドの実装。

構文

HRESULT CanSeekBackward(
    LONG *pCanSeekBackward
);

パラメータ

pCanSeekBackward
フィルタが逆方向にシーク可能なら OATRUE 値を受け取る変数のポインタを返す、そうでなければ OAFALSE を返す。

戻り値

接続されているピンから HRESULT 値を返す。

CPosPassThru::CanSeekForward

CPosPassThru クラス

ストリームが順方向にシークできるかどうかを確認する。IMediaPosition::CanSeekForward メソッドの実装。

構文

HRESULT CanSeekForward(
    LONG *pCanSeekForward
);

パラメータ

pCanSeekForward
フィルタが順方向にシーク可能なら OATRUE 値を受け取る変数のポインタを返す、そうでなければ OAFALSE を返す。

戻り値

接続されているピンから HRESULT 値を返す。

CPosPassThru::CheckCapabilities

CPosPassThru クラス

ストリームに指定されたシーク能力を持つかどうかを問い合わせる。IMediaSeeking::CheckCapabilities メソッドの実装。

構文

HRESULT CheckCapabilities(
    DWORD *pCapabilities
);

パラメータ

pCapabilities
AM_SEEKING_SEEKING_CAPABILITIES 属性の １ つあるいは複数のビット合成へのポインタ。メソッドが返る時、この値はそれらの属性が有効であることを示す。

戻り値

接続されているピンから HRESULT 値を返す。

CPosPassThru::ConvertTimeFormat

CPosPassThru クラス

あるタイムフォーマットから別のフォーマットへ変換する。IMediaSeeking::ConvertTimeFormat メソッドの実装。

構文

HRESULT ConvertTimeFormat(
    LONGLONG *pTarget,
    const GUID *pTargetFormat,
    LONGLONG Source,
    const GUID *pSourceFormat
);

パラメータ

pTarget
変換されたタイム値を受け取る変数へのポインタ。
pTargetFormat
ターゲット フォーマットのタイム フォーマット GUID へのポインタ。NULL なら現在のフォーマットが使われる。
Source
変換されるタイム値。
pSourceFormat
変換するフォーマットの タイム フォーマット GUID へのポインタ。NULL なら現在のフォーマットが使われる。

戻り値

接続されているピンから HRESULT 値を返す。

CPosPassThru::CPosPassThru

CPosPassThru クラス

コンストラクタ メソッド。

構文

CPosPassThru(
    const TCHAR *pName,
    LPUNKNOWN pUnk,
    HRESULT *phr,
    IPin *pPin
);

パラメータ

pName
オブジェクトの名前へのポインタ、デバッグ用。このパラメータはスタティック メモリに割り当てること。
pUnk
このオブジェクトの所有者へのポインタ。オブジェクトが集成されているなら、集成されたオブジェクトの IUnknown インターフェイスへのポインタを渡す。そうでなければ、このパラメータに NULL を設定する。
phr
HRESULT 値へのポインタ。無視される。
pPin
フィルタの入力ピンの IPin インターフェイスへのポインタ。

CPosPassThru::ForceRefresh

CPosPassThru クラス

使われていない。

構文

HRESULT ForceRefresh(void);

戻り値

S_OK を返す。

注意

当初このクラスは接続されているピンの IMediaPosition と IMediaSeeking インターフェイスへのポインタをキャッシュするために設計された。ForceRefresh メソッドはこれらのインターフェイスを解放した。

現在の実装では、このクラスはこれらのインターフェイスをキャッシュしない。互換性のために ForceRefresh メソッドはインクルードされているが、何もせず S_OK を返すだけである。

CPosPassThru::GetAvailable

CPosPassThru クラス

シークが効率的な時間幅を取得する。IMediaSeeking::GetAvailable メソッドの実装。

構文

HRESULT GetAvailable(
    LONGLONG *pEarliest,
    LONGLONG *pLatest
);

パラメータ

pEarliest
シークが効率的なもっとも早いタイム値を受け取る変数へのポインタ。
pLatest
シークが効率的なもっとも遅いタイム値を受け取る変数へのポインタ。

戻り値

接続されているピンから HRESULT 値を返す。

CPosPassThru::GetCapabilities

CPosPassThru クラス

ストリームのすべてのシーク能力を取得する。IMediaSeeking::GetCapabilities メソッドの実装。

構文

HRESULT GetCapabilities(
    DWORD *pCapabilities
);

パラメータ

pCapabilities
AM_SEEKING_SEEKING_CAPABILITIES フラグのビット合成へのポインタ。

戻り値

接続されているピンから HRESULT 値を返す。

CPosPassThru::GetCurrentPosition

CPosPassThru クラス

現在位置を取得する、ストリームの全時間幅からの相対値。IMediaSeeking::GetCurrentPosition メソッドの実装。

構文

HRESULT GetCurrentPosition(
    LONGLONG *pCurrent
);

パラメータ

pCurrent
現在の位置を受け取る変数へのポインタ、現在のタイム フォーマットの単位。

戻り値

HRESULT 値を返す。以下の表に示されるいずれかの値。

S_OK | 成功。
E_NOTIMPL | メソッドはサポートされていない。
E_POINTER | NULL ポインタ引数。

注意

このメソッドは CPosPassThru::GetMediaTime メソッドを呼び出して、最も最近の位置を取得する。GetMediaTime が失敗すると、このメソッドは接続されているピンの IMediaSeeking::GetCurrentPosition を呼び出す。

GetMediaTime メソッドは基底クラスのデフォルトでは失敗する。フィルタで現在位置をキャッシュするなら、キャッシュ値を返す GetMediaTime をオーバーライドすること。

CPosPassThru::get_CurrentPosition

CPosPassThru クラス

現在位置を取得する、ストリームの全時間幅からの相対値。IMediaPosition::get_CurrentPosition メソッドの実装。

構文

HRESULT get_CurrentPosition(
    REFTIME *pllTime
);

パラメータ

pllTime
現在位置を受け取る変数へのポインタ、秒単位。

戻り値

接続されているピンから HRESULT 値を返す。

CPosPassThru::GetDuration

CPosPassThru クラス

ストリームの時間幅を取得する。IMediaSeeking::GetDuration メソッドの実装。

構文

HRESULT GetDuration(
    LONGLONG *pDuration
);

パラメータ

pDuration
時間幅を受け取る変数へのポインタ、現在のタイム フォーマット単位。

戻り値

接続されているピンから HRESULT 値を返す。

CPosPassThru::get_Duration

CPosPassThru クラス

ストリームの時間幅を取得する。IMediaPosition::get_Duration メソッドの実装。

構文

HRESULT get_Duration(
    REFTIME *plength
);

パラメータ

plength
全ストリーム長を受け取る変数へのポインタ、秒単位。

戻り値

接続されているピンから HRESULT 値を返す。

CPosPassThru::GetMediaTime

CPosPassThru クラス

現在のサンプルのタイム スタンプを取得する。

構文

virtual HRESULT GetMediaTime(
    LONGLONG *pStartTime,
    LONGLONG *pEndTime
);

パラメータ

pStartTime
開始タイムを受け取る変数へのポインタ、現在のタイム フォーマットの単位。
pEndTime
終了タイムを受け取る変数へのポインタ、現在のタイム フォーマットの単位。

戻り値

Returns E_FAIL.

注意

フィルタで受け取ったサンプルのタイム スタンプをキャッシュするならこのメソッドをオーバーライドすること。

CPosPassThru::GetPositions

CPosPassThru クラス

現在位置と停止位置を取得する、ストリームの全時間幅からの相対値。IMediaSeeking::GetPositions メソッドの実装。

構文

HRESULT GetPositions(
    LONGLONG *pCurrent,
    LONGLONG *pStop
);

パラメータ

pCurrent
現在位置を受け取る変数へのポインタ、現在のタイム フォーマットの単位。
pStop
停止位置を受け取る変数へのポインタ、現在のタイム フォーマットの単位。

戻り値

接続されているピンから HRESULT 値を返す。

CPosPassThru::GetPreroll

CPosPassThru クラス

開始位置の前にキューに入るデータの量を取得する。IMediaSeeking::GetPreroll メソッドの実装。

構文

HRESULT GetPreroll(
    LONGLONG *pllPreroll
);

パラメータ

pllPreroll
プリロール タイム を受け取る変数へのポインタ、現在のタイム フォーマットの単位。

戻り値

接続されているピンから HRESULT 値を返す。

CPosPassThru::get_PrerollTime

CPosPassThru クラス

開始位置の前にキューに入るデータ量 (プリロール タイム) を取得する。IMediaPosition::get_PrerollTime メソッドの実装。

構文

HRESULT get_PrerollTime(
    REFTIME *pllTime
);

パラメータ

pllTime
プリロール タイムを受け取る変数へのポインタ。秒単位。

戻り値

接続されているピンから HRESULT 値を返す。

CPosPassThru::GetRate

CPosPassThru クラス

再生レートを取得する。IMediaSeeking::GetRate メソッドの実装。

構文

HRESULT GetRate(
    double *pdRate
);

パラメータ

pdRate
再生レートを受け取る変数へのポインタ。

戻り値

接続されているピンから HRESULT 値を返す。

CPosPassThru::get_Rate

CPosPassThru クラス

再生レートを取得する。IMediaPosition::get_Rate メソッドの実装。

構文

HRESULT get_Rate(
    double *pdRate
);

パラメータ

pdRate
再生レートを受け取る変数へのポインタ。

戻り値

接続されているピンから HRESULT 値を返す。

CPosPassThru::GetStopPosition

CPosPassThru クラス

再生終了タイムを取得する、ストリームの全時間幅からの相対値。IMediaSeeking::GetStopPosition メソッドの実装。

構文

HRESULT GetStopPosition(
    LONGLONG *pStop
);

パラメータ

pStop
終了タイムを受け取る変数へのポインタ、現在のタイムフォーマットの単位。

戻り値

接続されているピンから HRESULT 値を返す。

CPosPassThru::get_StopTime

CPosPassThru クラス

再生の終了タイムを取得する、ストリームの全時間幅からの相対値。IMediaPosition::get_StopTime メソッドの実装。

構文

HRESULT get_StopTime(
    REFTIME *pllTime
);

パラメータ

pllTime
終了タイムを受け取る変数へのポインタ、秒単位。

戻り値

接続されているピンから HRESULT 値を返す。

CPosPassThru::GetTimeFormat

CPosPassThru クラス

現在のタイム フォーマットを取得する。IMediaSeeking::GetTimeFormat メソッドの実装。

構文

HRESULT GetTimeFormat(
    const GUID *pFormat
);

パラメータ

pFormat
タイム フォーマット GUID を受け取る変数へのポインタ。

戻り値

接続されているピンから HRESULT 値を返す。

CPosPassThru::IsFormatSupported

CPosPassThru クラス

指定したタイム フォーマットがサポートされているかどうかを確認する。IMediaSeeking::IsFormatSupported メソッドの実装。

構文

HRESULT IsFormatSupported(
    const GUID *pFormat
);

パラメータ

pFormat
タイム フォーマット GUID へのポインタ。

戻り値

接続されているピンから HRESULT 値を返す。

CPosPassThru::IsUsingTimeFormat

CPosPassThru クラス

指定したタイム フォーマットが現在使われているフォーマットかどうかを確認する。IMediaSeeking::IsUsingTimeFormat メソッドの実装。

構文

HRESULT IsUsingTimeFormat(
    const GUID *pFormat
);

パラメータ

pFormat
タイム フォーマット GUIDへのポインタ。

戻り値

接続されているピンから HRESULT 値を返す。

CPosPassThru::put_CurrentPosition

CPosPassThru クラス

現在の位置を設定する、ストリームの全時間幅からの相対値。IMediaPosition::put_CurrentPosition メソッドの実装。

構文

HRESULT put_CurrentPosition(
    REFTIME llTime
);

パラメータ

llTime
新しい位置、秒単位。

戻り値

接続されているピンから HRESULT 値を返す。

CPosPassThru::put_PrerollTime

CPosPassThru クラス

開始位置の前にキューに入るデータの量を設定する。IMediaPosition::put_PrerollTime メソッドの実装。

構文

HRESULT put_PrerollTime(
    REFTIME llTime
);

パラメータ

llTime
プリロール タイム、秒単位。

戻り値

接続されているピンから HRESULT 値を返す。

注意

このメンバ関数はその呼び出しをアップストリームに渡すが、IMediaPosition::put_PrerollTime メソッドはすべての DirectShow ソース フィルタでサポートされているわけではない。

CPosPassThru::put_Rate

CPosPassThru クラス

再生レートを設定する。IMediaPosition::put_Rate メソッドの実装。

構文

HRESULT put_Rate(
    double dRate
);

パラメータ

dRate
再生レート。ゼロであってはならない。

戻り値

dRate がゼロなら E_INVALIDARG を返す。それ以外なら、接続されているピンから HRESULT 値を返す。

注意

マイナス値はリバース再生を示す。すべてのメディアがリバース再生をサポートしているわけではない。

CPosPassThru::put_StopTime

CPosPassThru クラス

再生の終了タイムを設定する、ストリームの全時間幅からの相対値。IMediaPosition::put_StopTime メソッドの実装。

構文

HRESULT put_StopTime(
    REFTIME llTime
);

パラメータ

llTime
停止 タイムの double 値、秒単位。

戻り値

接続されているピンから HRESULT 値を返す。

CPosPassThru::QueryPreferredFormat

CPosPassThru クラス

ストリームで許容されるタイム フォーマットを取得する。IMediaSeeking::QueryPreferredFormat メソッドの実装。

構文

HRESULT QueryPreferredFormat(
    GUID *pFormat
);

パラメータ

pFormat
タイム フォーマット GUID を受け取る変数へのポインタ。

戻り値

接続されているピンから HRESULT 値を返す。

CPosPassThru::SetPositions

CPosPassThru クラス

現在位置と停止位置を設定する。IMediaSeeking::SetPositions メソッドの実装。

構文

HRESULT SetPositions(
    LONGLONG *pCurrent,
    DWORD dwCurrentFlags,
    LONGLONG *pStop,
    DWORD dwStopFlags
);

パラメータ

pCurrent
現在位置を指定する変数へのポインタ、現在のタイム フォーマットの単位。
dwCurrentFlags
フラグのビットの組み合わせ。詳細については、「IMediaSeeking::SetPositions」を参照すること。
pStop
停止位置を指定する変数へのポインタ、現在のタイム フォーマットの単位。
dwStopFlags
フラグのビットの組み合わせ。詳細については、IMediaSeeking::SetPositions」を参照すること。

戻り値

接続されているピンから HRESULT 値を返す。

CPosPassThru::SetRate

CPosPassThru クラス

再生レートを設定する。IMediaSeeking::SetRate メソッドの実装。

構文

HRESULT SetRate(
    double dRate
);

パラメータ

dRate
再生レート。ゼロであってはならない。

戻り値

dRate がゼロなら E_INVALIDARG を返す。それ以外なら、接続されているピンから HRESULT 値を返す。

CPosPassThru::SetTimeFormat

CPosPassThru クラス

タイム フォーマットを設定する。IMediaSeeking::SetTimeFormat メソッドの実装。

構文

HRESULT SetTimeFormat(
    const GUID *pFormat
);

パラメータ

pFormat
タイム フォーマット GUID へのポインタ。

戻り値

接続されているピンから HRESULT 値を返す。

CreatePosPassThru 関数

CPosPassThru クラス

CPosPassThru オブジェクトまたは CRendererPosPassThru オブジェクトを作成する。

構文

STDAPI CreatePosPassThru(
    LPUNKNOWN pAgg,
    BOOL bRenderer,
    IPin *pPin,
    IUnknown **ppPassThru
);

パラメータ

pAgg
このオブジェクトの所有者へのポインタ。オブジェクトが集成された場合は、集成オブジェクトの IUnknown インターフェイスにポインタを渡す。それ以外の場合は、このパラメータに NULL を設定する。
bRenderer
ファイルがレンダラであるかどうかを示すブール値。フィルタがレンダラである場合は値 TRUE を使用し、レンダラでない場合は値 FALSE を使用する。
pPin
フィルタの入力ピンの IPin へのポインタ。
ppPassThru
オブジェクトの IUnknown インターフェイスへのポインタを受け取る変数のアドレス。

戻り値

成功の場合は S_OK を返す。それ以外の場合は HRESULT 値を返し、エラーの原因を示す。

注意

bSupportRendering の値が TRUE の場合、このメソッドは CRendererPosPassThru クラスのインスタンスを作成する。それ以外の場合は、CPosPassThru クラスのインスタンスを作成する。詳細については、「CSeekingPassThru」を参照すること。


CPullPin クラス

CPullPin クラスは、ソースからダウンストリームを受け取るフィルタがスレッドを作成し、IAsyncReader インターフェイスをサポートする非同期ソース フィルタからメディア ストリームを引き出すために用意されている。通常、このクラスは、パーサー フィルタの入力ピンで実装される。これは、Microsoft® DirectShow® 非同期リーダー フィルタが、ファイルからメディア ストリームを読み取るだけで、解析を行わないからである。

プロテクト データ メンバ

m_pAlloc 接続で使用される IMemAllocator インターフェイスへのポインタ。

メンバ関数

Active | 非同期リーダーからデータを引き出し始めるようにピンに指示する。
AlignDown | LONGLONG 型の値をすぐ下の LONG 境界にそろえる。
AlignUp | LONGLONG 型の値をすぐ上の LONG 境界にそろえる。
Connect | このピンから非同期リーダーへの接続を開始する。
CPullPin | CPullPin オブジェクトを作成する。
Disconnect | 非同期リーダーへの接続を切断する。
Duration | メディア ストリームの時間幅を取得する。
GetReader | 非同期リーダー インターフェイスを取得する。
Inactive | 非同期リーダーからデータを引き出しを終了するようにピンに指示する。
Seek | メディア ストリームの開始および終了タイムを設定する。

オーバーライド可能なメンバ関数

BeginFlush | このピンおよびすべてのダウンストリーム ピンをフラッシュする。
DecideAllocator | 非同期リーダーで使用するアロケータを指定する。
EndFlush | フラッシュ処理の終了を通知する。
EndOfStream | エンドオブストリーム通知をダウンストリームに送信する。
OnError | 引き出しを停止させる実行時エラーを処理する。
Receive | 非同期リーダーからのデータの受信を処理する。

CPullPin::Active

CPullPin クラス

非同期リーダーからデータを引き出し始めるようにピンに指示する。

構文

HRESULT Active(void);

戻り値

HRESULT 値を返す。

注意

このメンバ関数を呼び出す前に、リーダー インターフェイスを取得し、アロケータを決定しなければならない。この処理は CPullPin::Connect メンバ関数によって行われる。

CPullPin::AlignDown

CPullPin クラス

LONGLONG 型の値をすぐ下の LONG 境界にそろえる。

構文

LONGLONG AlignDown(
LONGLONG ll,
LONG lAlign
    );

パラメータ

ll
そろえる要素。
lAlign
アラインメント境界。

戻り値

lAlign にそろえた ll 値を返す。

注意

下位への整列は切り捨て処理である。

CPullPin::AlignUp

CPullPin クラス

LONGLONG 型の値をすぐ上の LONG 境界にそろえる。

構文

LONGLONG AlignUp(
LONGLONG ll,
LONG lAlign
    );

パラメータ

ll
そろえる要素。
lAlign
アラインメント境界。

戻り値

HRESULT 値を返す。

CPullPin::BeginFlush

CPullPin クラス

オーバーライドしてこのピンおよびすべてのダウンストリーム ピンをフラッシュする。

構文

virtual HRESULT BeginFlush(void);

戻り値

HRESULT 値を返す。

注意

このメンバ関数は、シーク処理に先立ってスレッドをポーズする前に CPullPin::Seek メンバ関数によって呼び出される。このメンバ関数を実装して、接続されたダウンストリーム ピンについて IPin::BeginFlush メソッドを呼び出す必要がある。

CPullPin::Connect

CPullPin クラス

このピンから非同期リーダーへの接続を開始する。

構文

HRESULT Connect(
IUnknown *pUnk,
IMemAllocator *pAlloc,
BOOL bSync
    );

パラメータ

pUnk
非同期リーダー (IAsyncReader) の存在を問い合わせるオブジェクトへのポインタ。
pAlloc
必要に応じて、優先アロケータとして指定するオプションのアロケータへのポインタ。
bSync
リーダーが非同期リーダーではなく、同期リーダーを使用する場合は TRUE に設定する。

戻り値

pUnk で指定されたオブジェクトから IAsyncReader インターフェイスに正常に接続された場合は S_OK を返す。

CPullPin::CPullPin

CPullPin クラス

CPullPin オブジェクトを作成する。

構文

CPullPin(void);

戻り値

戻り値なし。

CPullPin::DecideAllocator

CPullPin クラス

非同期リーダーと使用するアロケータをネゴシエートする。

構文

virtual HRESULT DecideAllocator(
IMemAllocator *pAlloc,
ALLOCATOR_PROPERTIES *pProps
    );

パラメータ

pAlloc
優先アロケータとして指定するアロケータへのポインタ (オプション)。アロケータを指定しない場合は、NULL を渡す。
pProps
アロケータのサイズ、カウント、およびアラインメントへのポインタ (オプション)。アロケータのプロパティを要求しない場合は 0 を渡す。

戻り値

成功した場合は S_OK を返す。eProps に無効なアラインメント プロパティが含まれている場合は VFW_E_BADALIGN を返す。アロケータを作成するために十分なメモリがない場合は E_OUTOFMEMORY を返す。作成した IMemAllocator インターフェイスが無効である場合は E_NOINTERFACE を返す。

注意

このメンバ関数は、IAsyncReader::RequestAllocator メソッドを呼び出してアロケータをネゴシエートする。

CPullPin::Disconnect

CPullPin クラス

非同期リーダーへの接続を切断する。

構文

HRESULT Disconnect(void);

戻り値

接続がない場合は NOERROR を返す。

注意

このメンバ関数は、CPullPin::Connect メソッドで作成された非同期ファイル リーダーへの接続を切断する。

CPullPin::Duration

CPullPin クラス

メディア ストリームの時間幅を取得する。

構文

HRESULT Duration(
REFERENCE_TIME *ptDuration
    );

パラメータ

ptDuration
UNIT (10,000,000) を乗算したバイト単位の時間幅へのポインタ。

戻り値

HRESULT 値を返す。

CPullPin::EndFlush

CPullPin クラス

オーバーライドしてフラッシュ処理の終了を通知する。

構文

virtual HRESULT EndFlush(void) PURE;

戻り値

HRESULT 値を返す。

注意

このメンバ関数は、シーク処理に先立ってスレッドをポーズした後に CPullPin::Seek メンバ関数によって呼び出される。このメンバ関数を実装して、接続されたダウンストリーム ピンについて IPin::EndFlush メソッドを呼び出す必要がある。

CPullPin::EndOfStream

CPullPin クラス

オーバーライドしてエンドオブストリーム通知をダウンストリームに送信する。

構文

virtual HRESULT EndOfStream(void) PURE;

戻り値

HRESULT 値を返す。

注意

このメンバ関数は、受信したサンプルの処理中に、ストリームの最後に到達した場合に呼び出される。このメンバ関数を実装して、接続されたダウンストリーム ピンについて IPin::EndOfStream メソッドを呼び出す必要がある。

CPullPin::GetReader

CPullPin クラス

非同期リーダーを取得する。

構文

IAsyncReader* GetReader(void);

戻り値

参照カウントされた IAsyncReader インターフェイスを返す。

CPullPin::Inactive

CPullPin クラス

非同期リーダーからデータを引き出しを終了するようにピンに指示する。

構文

HRESULT Inactive(void);

戻り値

HRESULT 値を返す。

注意

このメンバ関数は、IAsyncReader::BeginFlush メソッドを呼び出し、スレッドを終了して、IAsyncReader::EndFlush メソッドを呼び出して、アロケータをデコミットする。

CPullPin::OnError

CPullPin クラス

オーバーライドして引き出しを停止させる実行時エラーを処理する。

構文

virtual void OnError(
HRESULT hr
) PURE;

パラメータ

hr
トラップされたエラーの HRESULT 値。

戻り値

戻り値なし。

注意

これらのエラーはアップストリーム フィルタ (非同期リーダー) から返される。アップストリーム フィルタは既にエラーをフィルタ グラフ マネージャにレポート済みである。このメンバ関数は、エラーをトラップするときに複数の CPullPin メンバ関数から呼び出されるので、実装しなければならない。

CPullPin::Receive

CPullPin クラス

このメンバ関数をオーバーライドして、非同期リーダーからのデータの受信を処理する。

構文

virtual HRESULT Receive(
IMediaSample *pSample
) PURE;

パラメータ

pSample
[in] メディア サンプルへのポインタ。

戻り値

HRESULT 値を返す。S_OK 以外の値を返すと、データは終了する。

注意

派生クラスでこのメンバ関数を実装しなければならない。このメンバ関数は、サンプル ストリームの処理中に新しいサンプルを受信したときに必ず呼び出される。入力ピンの IMemInputPin::Receive メソッドと同じ方法で記述する必要がある。

CPullPin::Seek

CPullPin クラス

メディア ストリームの開始および終了タイムを設定する。

構文

HRESULT Seek(
REFERENCE_TIME tStart,
REFERENCE_TIME tStop
    );

パラメータ

tStart
開始タイム (デフォルトは 0)。
tStop
終了タイム (デフォルトは CPullPin::Duration の値)。

戻り値

HRESULT 値を返す。

注意

フィルタ グラフが実行中 (アクティブ) である場合、メディア レンダリングは tStart によって定義された新しい位置から直ちに開始される。


CQueue クラス

単純で静的にサイズを割り当てたキューを実装するテンプレート。

宣言 : Wxutil.h

クラス コンストラクタはキューのサイズを指定する。PutQueueObject メソッドはあるオブジェクトをキューに入れ、GetQueueObject メソッドはオブジェクトからキューを引き出す。新しいオブジェクトに対してキュー内にスペースができるまで、PutQueueObject メソッドはブロックする。キュー内に受け取るオブジェクトが来るまで、GetQueueObject メソッドはブロックする。

このクラス テンプレートは ２ つのセマフォを使ってキュー操作をコントロールする、１ つは 「get」 セマフォ、もう １ つは 「put」 セマフォである。GetQueueObject メソッドは (WaitForSingleObject 関数を使って)「get」セマフォで待ち、(ReleaseSemaphore 関数を使って) 「put」 セマフォを解放する。PutQueueObject メソッドは 「put」 セマフォで待ち、「get」 セマフォを解放する。このクラスはまたクリティカル セクションを使って複数スレッドでのキュー操作を処理する。

Public メソッド
CQueue | コンストラクタ メソッド。
~CQueue | デストラクタ メソッド。
GetQueueObject | キューから次のオブジェクトを取得する。
PutQueueObject | キューにオブジェクトを入れる。

CQueue::CQueue

CQueue クラス

コンストラクタ メソッド。

構文

CQueue(
    int n
);

CQueue(void);

パラメータ

n
作成するキューのサイズ。

注意

パラメータなしで作成すると、キューのサイズは DEFAULT_QUEUESIZE にセットされる。

CQueue::~CQueue

CQueue クラス

デストラクタ メソッド。

構文

~CQueue(void);

CQueue::GetQueueObject

CQueue クラス

キューから次のオブジェクトを取得する。

構文

T GetQueueObject(void);

戻り値

T タイプ (テンプレート タイプ) のオブジェクトを返す。

注意

このメソッドはキューのオブジェクトが有効になるまでブロックする。

CQueue::PutQueueObject

CQueue クラス

キューにオブジェクトを入れる。

構文

void PutQueueObject(
    T object
);

パラメータ

object
T タイプ (テンプレート タイプ) のオブジェクト。

注意

このメソッドはキュー内にオブジェクトのスペースができるまでブロックする。


CRefTime クラス

基準タイムを管理するヘルパー クラス。

宣言 : Reftime.h

基準タイム は 100 ナノ秒で表現される時間の単位である。このクラスは REFERENCE_TIME データ タイプと同じデータ レイアウトを共有するが、あるメソッドと演算子が追加されている、それは比較や変換や数式関数を提供する。基準タイムの詳細については、「DirectShow のタイムとクロック」を参照すること。

Public メンバ変数
m_time | REFERENCE_TIME 値。
Public メソッド
CRefTime | コンストラクタ メソッド。
GetUnits | 基準タイムを取得する、100 ナノ秒単位。
Millisecs | 基準タイムをミリ秒に変換する。
演算子
operator REFERENCE_TIME() | オブジェクトを REFERENCE_TIME データ タイプにキャストする。
operator = | 新しい基準タイムをアサインする。
operator += | 2 つの基準タイムを加える。
operator –= | ある基準タイムからもう 1 つの基準タイムを引く。

CRefTime.m_time

CRefTime クラス

REFERENCE_TIME 値。

構文

REFERENCE_TIME m_time;

CRefTime::CRefTime

CRefTime クラス

コンストラクタ メソッド。

構文

CRefTime(void);

CRefTime(
    LONG msecs
);

CRefTime(
    REFERENCE_TIME rt
);

パラメータ

msecs
ミリ秒単位の基準タイム。

rt
100ナノ秒単位の基準タイム。

注意

基準タイムはデフォルトではゼロ。

CRefTime::GetUnits

CRefTime クラス

基準タイムを取得する、100 ナノ秒単位。

構文

LONGLONG GetUnits(void);

戻り値

m_time の値を返す。

CRefTime::Millisecs

CRefTime クラス

基準タイムをミリ秒に変換する。

構文

LONG Millisecs(void);

戻り値

ミリ秒で基準タイムを返す。

CRefTime::operator (REFERENCE_TIME)

CRefTime クラス

オブジェクトを REFERENCE_TIME データ タイプにキャストする。

構文

operator REFERENCE_TIME() const;

戻り値

m_time の値を返す。

注意

次の例はこのキャスト演算子の使い方を示す。

CRefTime cRT(1000);
REFERENCE_TIME rt = (REFERENCE_TIME)cRT;

CRefTime::operator =

CRefTime クラス

新しい基準タイムをアサインする。

構文

CRefTime& operator=(
    const CRefTime& rt
);

CRefTime& operator=(
    const LONGLONG ll
);

パラメータ

rt
新しい基準タイムを指定する CRefTime オブジェクトへの参照。
ll
新しい基準タイム、100ナノ秒単位。

戻り値

オブジェクトへの参照を返す。

CRefTime::operator +=

CRefTime クラス

2 つの基準タイムを加える。

構文

CRefTime& operator+=(
    const CRefTime& rt
);

パラメータ

rt
CRefTime オブジェクトへの参照。

戻り値

オブジェクトへの参照を返す。

CRefTime::operator –=

CRefTime クラス

ある基準タイムからもう 1 つの基準タイムを引く。

構文

CRefTime& operator-=(
    const CRefTime& rt
);

パラメータ

rt
CRefTime オブジェクトへの参照。

戻り値

オブジェクトへの参照を返す。


CRenderedInputPin クラス

The CRenderedInputPin クラスは、入力ピンから送られたストリームをレンダリングするレンダラ フィルタ (つまり、データを渡すための出力ピンを持たない) のために提供される。このクラスは CBaseInputPin をオーバーライドしてエンドオブストリーム通知を処理する。このクラスは、このレンダラを使用して複数のストリームを扱えるようにするために実装される (各ピンはエンドオブストリームを個別に処理する必要がある)。

Protected データ メンバ

m_bAtEndOfStream | エンドオブストリーム通知が受け取られると TRUE に設定される。
m_bCompleteNotified | EC_COMPLETE 通知がフィルタ グラフ マネージャに送信されると TRUE に設定される。

メンバ関数

CRenderedInputPin CRenderedInputPin オブジェクトを作成する。

オーバーライド可能なメンバ関数

Active | フィルタの状態が停止からポーズに変化したことをピンに通知する。
EndFlush | フラッシュ処理を終了するようにピンに通知する。
EndOfStream | 新しく実行コマンドが発行されるまで、追加のデータがないことをピンに通知する。
Run | フィルタの状態がポーズから実行中に変化したことをピンに通知する。

CRenderedInputPin::Active

CRenderedInputPin クラス

フィルタの状態が停止からポーズまたは実行中に変化したことをピンに通知する。

構文

HRESULT Active(void);

戻り値

HRESULT 値を返す。

注意

このメンバ関数は CBasePin::Active をオーバーライドする。基底クラス実装を呼び出す前に、m_bAtEndOfStream および m_bCompleteNotified の両方を FALSE に設定する。

CRenderedInputPin::CRenderedInputPin

CRenderedInputPin クラス

CRenderedInputPin オブジェクトを作成する。

構文

CRenderedInputPin(
    TCHAR *pObjectName,
    CBaseFilter *pFilter,
    CCritSec *pLock,
    HRESULT *phr,
    LPCWSTR pName
    );

パラメータ

pObjectName
オブジェクトの名前へのポインタ (デバッグ用)。
pFilter
ピンを所有するフィルタへのポインタ。
pLock
ピンのクリティカル セクションへのポインタ。
phr
HRESULT 値へのポインタ。
pName
ピン名へのポインタ。

戻り値

戻り値なし。

CRenderedInputPin::EndFlush

CRenderedInputPin クラス

フラッシュ処理を終了するようにピンに通知する。

構文

HRESULT EndFlush(void);

戻り値

HRESULT 値を返す。

注意

このメンバ関数は CBaseInputPin::EndFlush をオーバーライドする。基底クラス実装を呼び出す前に、m_bAtEndOfStream および m_bCompleteNotified の両方を FALSE に設定する。

CRenderedInputPin::EndOfStream

CRenderedInputPin クラス

新しく実行コマンドが発行されるまで、追加のデータがないことをピンに通知する。

構文

HRESULT EndOfStream(void);

戻り値

HRESULT 値を返す。

注意

このメンバ関数は IPin::EndOfStream メソッドを実装する。このメンバ関数は、CheckStreaming を呼び出してフィルタがストリーミング状態にあるかどうかを調べ、m_bAtEndOfStream を TRUE に設定し、EC_COMPLETE 通知をフィルタ グラフ マネージャに送信する。

EC_COMPLETE フィルタ グラフ通知の発行は、このメンバ関数呼び出し以前にピンに配送されたすべてのデータが処理された後でなければならない。フィルタが処理を非同期に実行する場合は、CRenderedInputPin::EndOfStream をオーバーライドして、すべての入力データの処理が完了するまで EC_COMPLETE 通知の送信を遅らせる。

CRenderedInputPin::Run

CRenderedInputPin クラス

フィルタの状態が停止からポーズに変化したことをピンに通知する。

構文

HRESULT Run(
    REFERENCE_TIME tStart
    );

パラメータ

tStart
開始タイム。このクラスからは参照されない。派生クラスから使用されることがある。

戻り値

HRESULT 値を返す (デフォルトでは S_OK)。

注意

このメンバ関数は、CBasePin::Run メンバ関数をオーバーライドする。m_bAtEndOfStream が TRUE の場合、このメンバ関数は、EC_COMPLETE 通知をフィルタ グラフ マネージャに送信する。


CRendererInputPin クラス

CBaseRenderer クラスの入力ピン。特に注記がある場合をのぞいて、このクラスのメソッドは、CBaseRenderer クラスの該当メソッドに委任される。

宣言 : Renbase.h

プロテクト メンバ変数
m_pRenderer | フィルタへのポインタ。
Public メソッド
CRendererInputPin | コンストラクタ メソッド。
BreakConnect | 接続の切断時にカスタマイズしたコードを追加する。
CompleteConnect | 接続を完了する。
CheckMediaType | ピンが特定のメディア タイプをサポートするかどうかを判定する。
Active | ピンをアクティブ (ポーズまたは実行中) モードに切り替える。
Inactive | ピンを非アクティブ状態に切り替え、アロケータのメモリを解放する。
SetMediaType | ピンのメディア タイプを設定する。
Allocator | デフォルト メモリ アロケータへのポインタを取得する。
IPin Methods
QueryId | ピンの識別子を取得する。
EndOfStream | 新しく実行コマンドが発行されるまで、追加のデータがないことをピンに通知する。
BeginFlush | フラッシュ処理を開始するようにピンに通知する。
EndFlush | フラッシュ処理を終了するようにピンに通知する。
IMemInputPin Methods
Receive | ストリームから次のデータ ブロックを取得する。

CRendererInputPin.m_pRenderer

CRendererInputPin クラス

フィルタへのポインタ。

構文

CBaseRenderer *m_pRenderer;

CRendererInputPin::Active

CRendererInputPin クラス

フィルタがアクティブになったことをピンに通知する。CBasePin::Active メソッドをオーバーライドする。

構文

HRESULTActive(void);

戻り値

HRESULT 値を返す。

CRendererInputPin::Allocator

CRendererInputPin クラス

メモリ アロケータへのポインタを取得する。

構文

IMemAllocator* Allocator(void) const;

戻り値

アロケータの IMemAllocator インターフェイスへのポインタまたは NULL を返す。

注意

このメソッドは、CBaseInputPin::m_pAllocator メンバ変数を返す。このメソッドは、インターフェイスの参照カウントをインクリメントしない。また、厳密にアクセッサ メソッドである。

CRendererInputPin::BeginFlush

CRendererInputPin クラス

フラッシュ処理を開始する。CBaseInputPin::BeginFlush メソッドをオーバーライドする。

構文

HRESULT BeginFlush(void);

戻り値

HRESULT 値を返す。

CRendererInputPin::BreakConnect

CRendererInputPin クラス

接続からピンを解放する。CBaseInputPin::BreakConnect メソッドをオーバーライドする。

構文

HRESULT BreakConnect(void);

戻り値

HRESULT 値を返す。

CRendererInputPin::CheckMediaType

CRendererInputPin クラス

ピンが特定のメディア タイプを受け入れるかどうかを判定する。CBasePin::CheckMediaType メソッドをオーバーライドする。

構文

HRESULT CheckMediaType(
    const CMediaType *pmt
    );

パラメータ

pmt
指定されたメディア タイプを格納しているメディア タイプ オブジェクトへのポインタ。

戻り値

HRESULT 値を返す。

CRendererInputPin::CompleteConnect

CRendererInputPin クラス

出力ピンへの接続を完了する。CBasePin::CompleteConnect メソッドをオーバーライドする。

構文

HRESULT CompleteConnect(
    IPin *pReceivePin
    );

パラメータ

pReceivePin
出力ピンの IPin インターフェイスへのポインタ。

戻り値

HRESULT 値を返す。

CRendererInputPin::CRendererInputPin

CRendererInputPin クラス

コンストラクタ メソッド。

構文

CRendererInputPin(
    CBaseRenderer *pRenderer,
    HRESULT *phr,
    LPCWSTR Name
    );

パラメータ

pRenderer
フィルタを実装する CBaseRenderer オブジェクトへのポインタ。
phr
HRESULT 値を受け取る変数へのポインタ。
Name
ピン識別子が含まれた Unicode&153; 文字列へのポインタ。

CRendererInputPin::EndFlush

CRendererInputPin クラス

フラッシュ処理を終了する。CBaseInputPin::EndFlush メソッドをオーバーライドする。

構文

HRESULT EndFlush(void);

戻り値

HRESULT 値を返す。

CRendererInputPin::EndOfStream

CRendererInputPin クラス

追加のデータがないことをピンに通知する。CBasePin::EndOfStream メソッドをオーバーライドする。

構文

HRESULT EndOfStream(void);

戻り値

HRESULT 値を返す。

CRendererInputPin::Inactive

CRendererInputPin クラス

フィルタがアクティブではなくなったことをピンに通知する。CBaseInputPin::Inactive メソッドをオーバーライドする。

構文

HRESULT Inactive(void);

戻り値

HRESULT 値を返す。

CRendererInputPin::QueryId

CRendererInputPin クラス

ピンの識別子を取得する。CBasePin::QueryId メソッドをオーバーライドする。

構文

HRESULT QueryId(
    LPWSTR *Id
    );

パラメータ

Id
ピンの識別子が含まれた文字列を受け取る、変数のアドレス。

戻り値

次の表に示されるいずれかの HRESULT 値を返す。

S_OK | 成功。
E_OUTOFMEMORY | メモリ不足。
E_POINTER | NULL ポインタ引数。

注意

このメソッドは、ワイド文字列 "In" を割り当て、Id パラメータに割り当てる。呼び出し元は、CoTaskMemFree 関数を使って、割り当てられたメモリを解放しなければならない。

CRendererInputPin::Receive

CRendererInputPin クラス

ストリームの次のメディア サンプルを受け取る。CBaseInputPin::Receive メソッドをオーバーライドする。

構文

HRESULT Receive(
    IMediaSample *pMediaSample
    );

パラメータ

pMediaSample
サンプルの IMediaSample インターフェイスへのポインタ。

戻り値

HRESULT 値を返す。

CRendererInputPin::SetMediaType

CRendererInputPin クラス

接続のメディア タイプを設定する。CBasePin::SetMediaType メソッドをオーバーライドする。

構文

HRESULT SetMediaType(
    const CMediaType *pmt
    );

パラメータ

pmt
メディア タイプを指定する CMediaType オブジェクトへのポインタ。

戻り値

HRESULT 値を返す。


CRendererPosPassThru クラス

レンダリング フィルタのシーク コマンドを処理する。

宣言 : Ctlutil.h

このクラスは、CPosPassThru クラスから派生する。サンプルが届いたときサンプルからタイム スタンプをキャッシュするサポートが追加されている。

CPosPassThru クラスと同じやり方でこのクラスを使用する。詳細については、「CPosPassThru」を参照すること。さらに、レンダリング フィルタは、キャッシュされたオブジェクトのタイム スタンプを更新しなければならない。

  • フィルタが受け取った各サンプルに対して、RegisterMediaTime メソッドを呼び出すこと。
  • フィルタが停止あるいは EndFlush 呼び出しを受け取ったとき、ResetMediaTime メソッドを呼び出すこと。
  • フィルタがエンドオブストリーム (End-Of-Stream) 通知を受け取ったとき、EOS メソッドを呼び出すこと。

このクラスの使い方については、CBaseRenderer ソース コードを参照すること。

Public メソッド
CRendererPosPassThru | コンストラクタ メソッド。
GetMediaTime | 現在のサンプルのタイム スタンプを取得する。
RegisterMediaTime | 現在のサンプルからタイム スタンプをキャッシュする。
ResetMediaTime | キャッシュされたタイム スタンプをゼロにリセットする。
EOS | エンドオブストリーム通知の後でキャッシュされたタイム スタンプをアップデートする。

CRendererPosPassThru::CRendererPosPassThru

CRendererPosPassThru クラス

コンストラクタ メソッド。

構文

CRendererPosPassThru(
    const TCHAR *pName,
    LPUNKNOWN pUnk,
    HRESULT *phr,
    IPin *pPin
);

パラメータ

pName
オブジェクトの名前へのポインタ、デバッグ用。このパラメータをスタティック メモリに割り当てること。
pUnk
このオブジェクトの所有者へのポインタ。オブジェクトが集成されているなら、集成されたオブジェクトの IUnknown インターフェイスへのポインタを渡すこと。それ以外の場合、このパラメータはゼロに設定する。
phr
HRESULT 値へのポインタ。無視される。
pPin
フィルタの入力ピンのIPin インターフェイスへのポインタ

CRendererPosPassThru::EOS

CRendererPosPassThru クラス

エンドオブストリーム通知の後でキャッシュされたタイム スタンプをアップデートする。

構文

HRESULT EOS(void);

戻り値

HRESULT 値を返す。以下の表に示されるいずれかの値。

S_OK | 成功。
E_FAIL | 失敗。多分フィルタがストリーミングしていない。

注意

フィルタがエンドオブストリーム通知 (IPin::EndOfStream) を受け取ったとき、このメソッドを呼び出すべきだ。このメソッドはストップ位置と等しい ２ つのキャッシュされたタイム スタンプをセットし、IMediaStream::GetCurrentPosition メソッドに正しいストリームの終りの値を返させる。

CRendererPosPassThru::GetMediaTime

CRendererPosPassThru クラス

現在のサンプルのタイム スタンプを取得する。

構文

HRESULT GetMediaTime(
    LONGLONG *pStartTime,
    LONGLONG *pEndTime
);

パラメータ

pStartTime
開始タイムを受け取る変数へのポインタ、現在のタイム フォーマットの単位。
pEndTime
終了タイムを受け取る変数へのポインタ、現在のタイム フォーマットの単位。NULL も可。

戻り値

HRESULT 値を返す。 以下の表に示されるいずれかの値。

S_OK | 成功。
E_INVALIDARG | このフォーマットへの変換はサポートされていない。
E_POINTER | NULL ポインタ引数。

注意

このメソッドは CPosPassThru::GetMediaTime メソッドをオーバーライドする。CPosPassThru::ConvertTimeFormat メソッドを呼び出すことにより、タイム スタンプ値は現在のタイム フォーマットに変換される。

CRendererPosPassThru::RegisterMediaTime

CRendererPosPassThru クラス

現在のサンプルからタイム スタンプをキャッシュする。

構文

HRESULT RegisterMediaTime(
    IMediaSample *pMediaSample
);

HRESULT RegisterMediaTime(
    LONGLONG StartTime,
    LONGLONG EndTime
);

パラメータ

pMediaSample
サンプルの IMediaSample インターフェイスへのポインタ。
StartTime
サンプル開始タイム、100 ナノ秒単位。
EndTime
サンプル終了タイム、100 ナノ秒単位。

戻り値

HRESULT 値を返す。 以下の表に示されるいずれかの値。

S_OK | 成功。
VFW_E_MEDIA_TIME_NOT_SET | サンプルはタイム スタンプされていない。

注意

このメソッドは現在のサンプルからタイム スタンプをストアする。GetMediaTime メソッドは同じ値を取得する。

フィルタは受け取った各サンプルに対しこのメソッドを呼び出すべきだ。このメソッドはサンプルへのポインタかタイム サンプルそれ自身のどちらかを受け取るためにオーバーロードされる。

CRendererPosPassThru::ResetMediaTime

CRendererPosPassThru クラス

キャッシュされたタイム スタンプをゼロにリセットする。

構文

HRESULT ResetMediaTime(void);

戻り値

S_OK を返す。

注意

RegisterMediaTime がキャッシュしたタイム スタンプが無効になるたびに、フィルタはこのメソッドを呼び出すべきだ。とりわけ、IPin::EndFlush と IMediaFilter::Stop メソッドに対応する際にこのメソッドを呼び出すべきだ。

このメソッドが呼び出された後、GetMediaTime メソッドは開始タイムと終了タイムにゼロを返す。


CSeekingPassThru クラス

CPosPassThru オブジェクトおよび CRendererPosPassThru オブジェクトを作成するヘルパー オブジェクト。

宣言 : Seekpt.h

CPosPassThru クラスおよび CRendererPosPassThru クラスは、シーク コマンドをアップストリームに渡すヘルパー オブジェクトである。CSeekingPassThru クラスは、これらのヘルパー オブジェクトを作成するヘルパー オブジェクトである。DirectShow では、このクラスを COM コンポーネントとしてパッケージ化することで、サポートを追加している。詳細については、「SeekingPassThru」を参照すること。

このクラスは、ISeekingPassThru インターフェイスを公開する。ISeekingPassThru::Init メソッドは、オブジェクトを初期化する。オブジェクトが初期化されると、フィルタは IMediaSeeking インターフェイスおよび IMediaPosition インターフェイスについてオブジェクトに照会できる。

フィルタは、CreatePosPassThru ヘルパー関数を呼び出し、このオブジェクトのインスタンスを作成、初期化できる。次のサンプル コードは、フィルタの QueryInterface メソッドからのものである。このコードでは、ヘルパー オブジェクトを作成し、シーク インターフェイスについて照会している。

if (riid == IID_IMediaPosition || riid == IID_IMediaSeeking) {
    if (m_pPosition == NULL)
    {
        HRESULT hr = CreatePosPassThru(GetOwner(), FALSE,
                        m_pFilter->m_pPin, &m_pPosition);
        if (FAILED(hr))
            return hr;
    }
    return m_pPosition->QueryInterface(riid, ppv);
}

Public メソッド
CSeekingPassThru | コンストラクタ メソッド。
~CSeekingPassThru | デストラクタ メソッド。
CreateInstance | オブジェクトのインスタンスを作成する。
ISeekingPassThru メソッド
Init | オブジェクトを初期化する。

CSeekingPassThru::CSeekingPassThru

CSeekingPassThru クラス

コンストラクタ メソッド。

構文

CPosPassThru(
    const TCHAR *pName,
    LPUNKNOWN pUnk,
    HRESULT *phr,
);

パラメータ

pName
オブジェクトの名前が含まれた文字列。詳細については、「CBaseObject」を参照すること。
pUnk
このオブジェクトの所有者へのポインタ。オブジェクトが集成された場合は、集成オブジェクトの IUnknown インターフェイスにポインタを渡す。それ以外の場合は、このパラメータに NULL を設定する。
phr
HRESULT 値へのポインタ。無視される。

CSeekingPassThru::~CSeekingPassThru

CSeekingPassThru クラス

デストラクタ メソッド。

構文

~CPosPassThru(void);

CSeekingPassThru::CreateInstance

CSeekingPassThru クラス

オブジェクトのインスタンスを作成する。このメソッドは、クラス ファクトリを通じてオブジェクトの作成をサポートする。詳細については、「CFactoryTemplate」を参照すること。

構文

static CUnknown *CreateInstance(
    LPUNKNOWN pUnk,
    HRESULT *phr
);

パラメータ

pUnk
このオブジェクトの所有者へのポインタ。オブジェクトが集成された場合は、オブジェクトの IUnknown インターフェイスにポインタを渡す。それ以外の場合は、このパラメータに NULL を設定する。
phr
HRESULT 値へのポインタ。無視される。

戻り値

新しい CSeekingPassThru オブジェクトへのポインタを返す。

CSeekingPassThru::Init

CSeekingPassThru クラス

オブジェクトを初期化する。

構文

HRESULT Init(
    BOOL bSupportRendering,
    IPin *pPin
);

パラメータ

bSupportRendering
[in] ファイルがレンダラかどうかを指定するブール値。フィルタがレンダラの場合は値 TRUE を使用する。レンダラでない場合は FALSE を使用する。
pPin
フィルタの入力ピン上の IPin インターフェイスへのポインタ。

戻り値

次の表に示されるいずれかの HRESULT 値を返す。

S_OK | 成功。
E_FAIL | オブジェクトは既に初期化されている。
E_OUTOFMEMORY | オブジェクトを作成するための十分なメモリがない。

注意

bSupportRendering の値が TRUE の場合、このメソッドは CRendererPosPassThru クラスのインスタンスを作成する。TRUE でない場合は、CPosPassThru クラスのインスタンスを作成する。


CSource クラス

ソース フィルタ実装の基底クラス。

宣言: Source.h

CSource から派生したフィルタには、CSourceStream クラスから派生した 1 つまたは複数の出力ピンが含まれる。それぞれの出力ピンは、メディア サンプルをダウンストリームにプッシュするワーカー スレッドを作成する。

出力ピンを実装するには、次の操作を行う。

  • CSourceStream からクラスを派生する。
  • CSourceStream::GetMediaType メソッドをオーバーライドし、可能な場合はピンのメディア タイプを検証する CSourceStream::CheckMediaType メソッドもオーバーライドする。
  • ピンのバッファ条件を返す CBaseOutputPin::DecideBufferSize メソッドを実装する。
  • メディア サンプル バッファにデータを埋める CSourceStream::FillBuffer メソッドを実装する。

フィルタを実装するには、次の操作を行う。

  • CSource からクラスを派生する。
  • コンストラクタで、CSourceStream から派生した 1 つまたは複数のピンを作成する。ピンは、コンストラクタ メソッドで自動的にフィルタに追加され、デストラクタ メソッドで削除される。

複数のスレッド間でフィルタの状態を同期するには、CSource::pStateLock メソッドを呼び出す。このメソッドは、フィルタ状態のクリティカル セクションへのポインタを返す。CAutoLock クラスを使って、クリティカル セクションを保持する。次に示すように、ピンからはピンの CBasePin.m_pFilter メンバ変数から pStateLock にアクセスできる。

CAutoLock lock(m_pFilter->pStateLock());

注 : CSource クラスは、データ フローのプッシュ モデルをサポートするように設計されている。このクラスは、ファイル リーダー フィルタの作成には推奨されない。ファイル リーダーは、IAsyncReader インターフェイスを介して、プル モデルをサポートする必要がある。詳細については、「フィルタ開発者が使用するデータ フロー」を参照すること。

プロテクト メンバ変数
m_iPins | フィルタ上のピン数。
m_paStreams | ピンの配列。
m_cStateLock | フィルタの状態を保護するクリティカル セクション オブジェクト。
Public メソッド
CSource | コンストラクタ メソッド。
~CSource | デストラクタ メソッド。
GetPinCount | フィルタ上のピン数を取得する。
GetPin | ピンを取得する。
pStateLock | フィルタのクリティカル セクション オブジェクトへのポインタを取得する。
AddPin | フィルタに新しい出力ピンを追加する。
RemovePin | フィルタから指定されたピンを取り除く。
FindPinNumber | フィルタ上から、指定された数のピンを取得する。
IBaseFilter Methods
FindPin | 指定された識別子を持つピンを取得する。

CSource.m_iPins

CSource クラス

フィルタ上のピン数。

構文

int m_iPins;

CSource.m_paStreams

CSource クラス

ピンの配列。

構文

CSourceStream **m_paStreams;

CSource.m_cStateLock

CSource クラス

フィルタの状態を保護するクリティカル セクション オブジェクト。pStateLock ヘルパー メソッドは、このメンバ変数へのポインタを返す。

構文

CCritSec m_cStateLock;

CSource::AddPin

CSource クラス

新しい出力ピンをフィルタに追加する。

構文

HRESULT AddPin(
    CSourceStream *pStream
    );

パラメータ

pStream
ピンを実装する CSourceStream オブジェクトへのポインタ。

戻り値

次の表に示されるいずれかの HRESULT 値を返す。

S_OK | 成功。
E_OUTOFMEMORY | メモリ不足。

注意

CSourceStream コンストラクタはこのメソッドを呼び出し、出力ピンをフィルタに追加する。

CSource::CSource

CSource クラス

コンストラクタ メソッド。

構文

CSource(
    TCHAR *pName,
    LPUNKNOWN lpunk,
    CLSID clsid
    );

パラメータ

pName
オブジェクトの名前が含まれた文字列へのポインタ。詳細については、「CBaseObject」を参照すること。
lpunk
このオブジェクトの所有者へのポインタ。このオブジェクトが集成された場合は、派生クラスの CreateInstance 関数に渡された集成オブジェクトの IUnknown インターフェイスに、ポインタを渡す。それ以外の場合は、このパラメータに NULL を設定する。
clsid
フィルタのクラス識別子。

CSource::~CSource

CSource クラス

デストラクタ メソッド。

構文

~CSource(void);

CSource::FindPin

CSource クラス

指定された識別子を持つピンを取得する。IBaseFilter::FindPin メソッドを実装する。

構文

HRESULT FindPin(
    LPCWSTR Id,
    IPin **ppPin
);

パラメータ

Id
ピンを識別する、NULL で終了する文字列へのポインタ。
ppPin
ピンの IPin インターフェイスへのポインタを受け取る変数のアドレス。メソッドが失敗すると、*ppPin は NULL に設定される。

戻り値

次の表に示されるいずれかの HRESULT 値を返す。

S_OK | 成功。
E_POINTER | NULL ポインタ引数。
VFW_E_NOT_FOUND | この識別子を持つピンは見つからなかった。

注意

最初のピンは、"1"、2 つ目のピンは "2"、以後同様である。詳細については、「CSourceStream::QueryId」を参照すること。

CSource::FindPinNumber

CSource クラス

フィルタ上のピンを指定する。

構文

int FindPinNumber(
    IPin *iPin
    );

パラメータ

iPin
ピンの IPin インターフェイスへのポインタ。

戻り値

ピン番号を返す。フィルタ上にピンが見つからなかった場合は -1 を返す。最初のピンの番号は 0 である。

CSource::GetPin

CSource クラス

ピンを取得する。純粋仮想メソッド CBaseFilter::GetPin を実装する。

構文

CBasePin *GetPin(
    int n
    );

パラメータ

n
指定されたピンの数。

戻り値

ピンを実装する CBasePin オブジェクトへのポインタを返す。インデックスが範囲外の場合は NULL を返す。

CSource::GetPinCount

CSource クラス

フィルタ上のピンの数を取得する。純粋仮想メソッド CBaseFilter::GetPinCount を実装する。

構文

int GetPinCount(void);

戻り値

フィルタ上のピンの数を返す。

CSource::pStateLock

CSource クラス

フィルタのクリティカル セクション オブジェクトへのポインタを取得する。

構文

CCritSec* pStateLock(void);

戻り値

m_cStateLock メンバ変数へのポインタを返す。

CSource::RemovePin

CSource クラス

フィルタから指定されたピンを取り除く。このメソッドはピンを削除しない。

構文

HRESULT RemovePin(
    CSourceStream *pStream
    );

パラメータ

pStream
ピンを実装する CSourceStream オブジェクトへのポインタ。

戻り値

次の表に示されるいずれかの HRESULT 値を返す。

S_OK | 成功。
S_FALSE | フィルタには、このピンは含まれていない。

注意

CSourceStream デストラクタはこのメソッドを呼び出し、フィルタから出力ピンを取り除く。


CSourcePosition クラス

CSourcePosition は、ソース フィルタに IMediaPosition インターフェイスを実装するための抽象クラスである。

このクラスは使用しない。ソース フィルタがシーク可能であれば、IMediaPosition の代わりに IMediaSeeking インターフェイスを公開すべきである。この目的で CSourceSeeking 基底クラスを使用することができる。

CSourcePosition::put_CurrentPosition、CSourcePosition::put_StopTime、または CSourcePosition::put_Rate が呼び出されると、CSourcePosition は純粋仮想メンバ関数 CSourcePosition::ChangeStart、CSourcePosition::ChangeStop、または CSourcePosition::ChangeRate をそれぞれ呼び出す。派生クラス内でこれらの関数をオーバーライドする。

Protected データ メンバ

m_Duration | ストリームの時間幅。
m_pLock | ロックのための CCritSec オブジェクトへのポインタ。
m_Rate | サンプル レート。
m_Start | 開始タイム。
m_Stop | 終了タイム。

メンバ関数

CSourcePosition CSourcePosition オブジェクトを作成する。

オーバーライド可能なメンバ関数

ChangeRate | この純粋仮想関数をオーバーライドして、レート プロパティが変更された通知を処理する。
ChangeStart | この純粋仮想関数をオーバーライドして、開始位置プロパティが変更された通知を処理する。
ChangeStop | この純粋仮想関数をオーバーライドして、終了位置プロパティが変更された通知を処理する。

実装される IMediaPosition メソッド

get_CurrentPosition | 現在は実装されていない。
get_Duration | メディアの合計時間幅を取得する。
get_PrerollTime | 現在は実装されていない。
get_Rate | メディアの通常再生を基準にした再生レートを取得する。
get_StopTime | 再生が停止すべきメディア内の位置を取得する。
put_CurrentPosition | 再生が開始すべきメディア内の位置を設定する。
put_PrerollTime | 現在は実装されていない。
put_Rate | メディアの通常再生を基準にした再生レートを設定する。
put_StopTime | 再生が停止すべきメディア内の位置を設定する。

CSourcePosition::ChangeRate

CSourcePosition クラス

このメンバ関数をオーバーライドして、サンプル レートの変更通知を処理する。

構文

virtual HRESULT ChangeRate(void) PURE;

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
S_OK または NOERROR | 成功。

注意

このメンバ関数は、IMediaPosition::put_Rate の呼び出しによってレートが変更されると呼び出される。この関数をオーバーライドして送信されたデータのレートを変更する。通常は、CBaseInputPin::BeginFlush および CBaseInputPin::EndFlush の呼び出しの後で、新しいタイム スタンプがマークされたサンプルを送信する。

CSourcePosition::ChangeStart

CSourcePosition クラス

このメンバ関数をオーバーライドして、開始タイムの変更通知を処理する。

構文

virtual HRESULT ChangeStart(void) PURE;

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
S_OK または NOERROR | 成功。

注意

このメンバ関数は、IMediaPosition::put_CurrentPosition の呼び出しによって新しい開始位置が要求されると呼び出される。この関数をオーバーライドして送信されたデータを変更する。通常は、CBaseInputPin::BeginFlush および CBaseInputPin::EndFlush の呼び出しの後で、新しいタイム スタンプがマークされたサンプルを送信する。

CSourcePosition::ChangeStop

CSourcePosition クラス

このメンバ関数をオーバーライドして、終了タイムの変更通知を処理する。

構文

virtual HRESULT ChangeStop(void) PURE;

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
S_OK または NOERROR | 成功。

注意

このメンバ関数は、IMediaPosition::put_StopTime の呼び出しによって停止位置が変更されると呼び出される。この関数をオーバーライドして、正しい終了タイムが設定されていることを確認する。通常は、CBaseInputPin::BeginFlush および CBaseInputPin::EndFlush の呼び出しの後でデータを再送信する。

CSourcePosition::CSourcePosition

CSourcePosition クラス

CSourcePosition オブジェクトを作成する。

構文

CSourcePosition(

  const TCHAR *pName,

  LPUNKNOWN pUnk,

  HRESULT *phr,

  CCritSec *pLock

  );

パラメータ

pName
デバッギング目的で CSourcePosition コンストラクタで使用されるオブジェクトの名前へのポインタ。
pUnk
このオブジェクトの所有者へのポインタ。
phr
結果情報を返す HRESULT 値へのポインタ。
pLock
ロックのための CCritSec オブジェクトへのポインタ。

戻り値

戻り値なし。

注意

スタティック メモリに pName パラメータを割り当てる。この名前は、オブジェクトの作成および削除を行うデバッギング端末上に現れる。

CSourcePosition::get_CurrentPosition

CSourcePosition クラス

このメソッドは現在実装されていない。E_NOTIMPL を返す。

構文

HRESULT get_CurrentPosition(
  REFTIME *pllTime
);

パラメータ

pllTime
返された開始タイムへのポインタ (秒単位で示された double 値)。

戻り値

E_NOTIMPL を返す。

注意

実際に操作しているデータを返すことができる場合はこのメソッドをオーバーライドする。開始位置は、レートの前に適用される。したがって、通常の再生速度での位置になる。

CSourcePosition::get_Duration

CSourcePosition クラス

メディア ストリームの時間幅を取得する。

構文

HRESULT get_Duration(

  REFTIME *plength

  );

パラメータ

plength
返されたメディア ストリームの長さへのポインタ。

戻り値

pLength が無効な場合は、E_POINTER を返す。それ以外の場合は、S_OK を返す。

注意

時間幅は通常の再生速度を想定している。したがって、レートの影響を受けない。

CSourcePosition::get_PrerollTime

CSourcePosition クラス

ポインタを有効にするが、プリロールの取得は現在実装されていない。

構文

HRESULT get_PrerollTime(

  REFTIME *pllTime

  );

パラメータ

pllTime
返されたプリロール タイムへのポインタ (秒単位で示された double 値)。

戻り値

pllTime が無効な場合は、E_POINTER を返す。それ以外の場合は、E_NOTIMPL を返す。

注意

プリロール タイムとは、テープ プレーヤーなどのランダムでないアクセス デバイスがローリングを開始するべき開始位置より前の時間。

CSourcePosition::get_Rate

CSourcePosition クラス

通常の再生速度を基準にした再生レートを取得する。

構文

HRESULT get_Rate(

  double *pdRate

  );

パラメータ

pdRate
返されたレートへのポインタ。

戻り値

pdRate が無効な場合は、E_POINTER を返す。それ以外の場合は、S_OK を返す。

注意

レート 1.0 は通常の再生速度を示す。レート 0.5 は、半分の速度を示す。レート -1.0 は逆方向の通常速度を示す。

CSourcePosition::get_StopTime

CSourcePosition クラス

メディア ストリームが停止する時間を取得する。

構文

HRESULT get_StopTime(

  REFTIME *pllTime

  );

パラメータ

pllTime
返された終了タイムへのポインタ (秒単位で示された double 値)。

戻り値

pllTime が無効な場合は、E_POINTER を返す。それ以外の場合は、S_OK を返す。

注意

終了タイムは、ゼロと再生が停止するメディアの時間幅との間の位置である。

停止位置は、レートの前に適用される。したがって、通常の再生速度での位置になる。

CSourcePosition::put_CurrentPosition

CSourcePosition クラス

再生が開始すべきメディア ストリーム内のタイムを設定する。

構文

HRESULT put_CurrentPosition(
  REFTIME llTime
  );

パラメータ

llTime
開始タイムは、秒単位の double 値として表される。

戻り値

CSourcePosition::ChangeStart の呼び出しからの HRESULT 値を返す。

注意

開始タイムとは、ゼロと時間幅との間の、次の実行コマンドが発行されたときに再生が開始すべきメディアの位置である。

ポーズ状態で開始位置を設定した場合、実行コマンドが発行されると新しい開始位置から再生が再開される。

開始位置は、レートの前に適用される。したがって、通常の再生速度での位置になる。

CSourcePosition::put_PrerollTime

CSourcePosition クラス

このメソッドは現在実装されていない。E_NOTIMPL を返す。

構文

HRESULT put_PrerollTime(
   REFTIME llTime
);

パラメータ

llTime
設定するプリロール タイム。

戻り値

E_NOTIMPL を返す。

注意

プリロール タイムとは、テープ プレーヤーなどのランダムでないアクセス デバイスがローリングを開始するべき開始位置より前の時間。

CSourcePosition::put_Rate

CSourcePosition クラス

通常の速度を基準にした再生レートを設定する。

構文

HRESULT put_Rate(
  double dRate
  );

パラメータ

dRate
設定するレート。

戻り値

CSourcePosition::ChangeRate の呼び出しからの HRESULT 値を返す。

注意

このプロパティを使用すると、アプリケーションは通常のデフォルト再生速度を基準に再生をアクセラレーションまたは低速化することができる。レート 1.0 は通常の再生速度を示す。2.0 を指定すると、通常レートの 2 倍で再生が行われる。毎秒 10 フレーム (fps) で作成されたビデオは、リソースが許せば 20 fps で再生される。オーディオ ストリームを通常以上の速度で再生すると、フレームがドロップされる代わりにピッチが高くなる。

負の値のレートは、逆方向の再生を示す。すべてのメディアで逆方向再生がサポートされるとは限らない。

CSourcePosition::put_StopTime

CSourcePosition クラス

メディア ストリームが停止する時間を設定する。

構文

HRESULT put_StopTime(
  REFTIME llTime
  );

パラメータ

llTime
終了タイムは、秒単位の double 値として表される。

戻り値

CSourcePosition::ChangeStop の呼び出しからの HRESULT 値を返す。

注意

終了タイムは、ゼロと再生が停止するメディアの時間幅との間の位置である。

停止位置は、レートの前に適用される。したがって、通常の再生速度での位置になる。


CSourceSeeking クラス

1 つの出力ピンを持つソース フィルタで、シークを実装する抽象クラス。

宣言 : Ctlutil.h

このクラスは、IMediaSeeking インターフェイスをサポートし、すべての IMediaSeeking メソッドにデフォルトの実装を提供する。プロテクト メンバ変数は、開始タイム、終了タイム、および現在のレートを格納する。デフォルトでは、このクラスによってサポートされる唯一のタイム フォーマットは、TIME_FORMAT_MEDIA_TIME (100 ナノ秒単位) である。

CSourceSeeking オブジェクトは、開始位置、停止位置、または再生レートが変更されるたびに、次のように対応する純粋仮想メソッドを呼び出す。

  • 開始位置 : ChangeStart
  • 停止位置 : ChangeStop
  • 再生レート : ChangeRate

派生クラスは、これらのメソッドを実装しなければならない。シーク処理後、フィルタは次のことを行う必要がある。

  1. ダウンストリームの入力ピンで IPin::BeginFlush メソッドを呼び出す。
  2. データを提供するワーカー スレッドを停止する。
  3. 入力ピンで IPin::EndFlush メソッドを呼び出す。
  4. ワーカー スレッドを再起動する。
  5. 入力ピンで IPin::NewSegment メソッドを呼び出す。
  6. 最初のサンプルで非継続プロパティを設定する。IMediaSample::SetDiscontinuity メソッドを呼び出す。

ワーカー スレッドがブロックされ、サンプル出力の待機状態になっている場合は、BeginFlush を呼び出してワーカー スレッドを解放する。

ステップ 2 で、スレッドによるデータの送信が停止したことを確認する。実装によっては、スレッドが終了するのを待つか、またはスレッドがなんらかの応答を示すまで待つ必要がある。フィルタで CSourceStream クラスを使っている場合、CSourceStream::Stop メソッドは、ワーカー スレッドが応答するまで待機状態となる。

理想的には、新しいセグメント (ステップ 5) がワーカー スレッドから提供されることが望ましい。これは、フィルタがサンプルを使って継続して処理する限り、CSourceSeeking オブジェクトによっても実行できる。

次の例は、可能な実装を示している。ここでは、ソース フィルタの出力ピンが CSourceSeeking と CSourceStream から派生することを想定している。この例では、ステップ 1 ～ 4 を実行するヘルパー メソッド UpdateFromSeek を定義している。CSourceStream::OnThreadStartPlay メソッドはオーバーライドされ、新しいセグメントを送るとともに、非連続を示すフラグを設定する。ワーカー スレッドはこのフラグをピックアップし、IMediaSample::SetDiscontinuity を呼び出す。

void CMyStream::UpdateFromSeek()
{
    if (ThreadExists())
    {
        DeliverBeginFlush();
        Stop();
        DeliverEndFlush();
        Run();
    }
}

HRESULT CMyStream::OnThreadStartPlay()
{
    m_bDiscontinuity = TRUE;
    return DeliverNewSegment(m_rtStart, m_rtStop, m_dRateSeeking);
}

プロテクト メンバ変数
m_rtDuration | ストリームが再生される時間。
m_rtStart | 開始タイム。
m_rtStop | 終了タイム。
m_dRateSeeking | 再生レート。
m_dwSeekingCaps | シーク能力。
m_pLock | ロックのためのクリティカル セクション オブジェクトへのポインタ。
プロテクト メソッド
CSourceSeeking | コンストラクタ メソッド。
純粋仮想メソッド
ChangeRate | 再生レートが変更されたときに呼び出される。
ChangeStart | 開始位置が変更されたときに呼び出される。
ChangeStop | 停止位置が変更されたときに呼び出される。
IMediaSeeking メソッド
IsFormatSupported | 指定されたタイム フォーマットがサポートされているかどうかを判定する。
QueryPreferredFormat | オブジェクトの優先タイム フォーマットを取得する。
SetTimeFormat | タイム フォーマットを設定する。
IsUsingTimeFormat | 指定されたタイム フォーマットが、現在使用されているフォーマットかどうかを判定する。
GetTimeFormat | 現在のタイム フォーマットを取得する。
GetDuration | ストリームの時間幅を取得する。
GetStopPosition | ストリームの時間幅に対して、再生が停止するタイムを取得する。
GetCurrentPosition | ストリームの合計時間幅に対する、現在の位置を取得する。
GetCapabilities | ストリームのすべてのシーク能力を取得する。
CheckCapabilities | ストリームに指定されたシーク能力があるかどうかを照会する。
ConvertTimeFormat | 1 つのタイム フォーマットから別のタイム フォーマットに変換する。
SetPositions | 現在の位置と停止位置を設定する。
GetPositions | 現在の位置と停止位置を取得する。
GetAvailable | シークが有効であるタイムの範囲を取得する。
SetRate | 再生レートを設定する。
GetRate | 再生レートを取得する。
GetPreroll | プリロール タイムを取得する。

CSourceSeeking.m_rtDuration

CSourceSeeking クラス

ストリームの時間幅。デフォルトでは、この値は m_rtStop メンバ変数の値に設定される。

構文

CRefTime m_rtDuration;

CSourceSeeking.m_rtStart

CSourceSeeking クラス

開始タイム。デフォルトでは、この値はゼロに設定される。

構文

CRefTime m_rtStart;

CSourceSeeking.m_rtStop

CSourceSeeking クラス

終了タイム。デフォルトでは、この値は非常に大きな数値に設定される。派生クラスは、コンストラクタにおいて、またはフィルタが初期化されたときに、この値をリセットできる。

構文

CRefTime m_rtStop;

CSourceSeeking.m_dRateSeeking

CSourceSeeking クラス

再生レート。デフォルトでは、この値は 1.0 に設定される。

構文

double m_dRateSeeking;

CSourceSeeking.m_dwSeekingCaps

CSourceSeeking クラス

シーク能力。

構文

DWORD m_dwSeekingCaps;

注意

デフォルトでは、この値は次のフラグのビットごとの組み合わせに設定される。

  • AM_SEEKING_CanSeekForwards
  • AM_SEEKING_CanSeekBackwards
  • AM_SEEKING_CanSeekAbsolute
  • AM_SEEKING_CanGetStopPos
  • AM_SEEKING_CanGetDuration

フィルタが異なる能力の集まりをサポートしている場合、この値をオーバーライドする必要がある。

CSourceSeeking.m_pLock

CSourceSeeking クラス

ロックのためのクリティカル セクション オブジェクトへのポインタ。

構文

CCritSec *m_pLock;

CSourceSeeking::ChangeRate

CSourceSeeking クラス

再生レートが変更されたときに呼び出される。

構文

virtual HRESULT ChangeRate(void) PURE;

戻り値

HRESULT 値を返す。

注意

SetRate メソッドは、このクラスを呼び出す。このクラスは、派生クラスが実装しなければならない。SetRate メソッドは、m_dRateSeeking メンバ変数を更新するが、新しい値を確認しない。レート 0 は、常に拒否される。ゼロ以下のレートは、逆再生を示す。ほとんどのフィルタは、負のレートをサポートしていない。

次の例は、可能な実装を示している。

HRESULT CMyStream::ChangeRate( )
{
    {
        CAutoLock cAutoLockSeeking(CSourceSeeking::m_pLock);
        if( m_dRateSeeking <= 0 ) {
            m_dRateSeeking = 1.0;  // 妥当な値にリセットする。
            return E_FAIL;
        }
    }
    UpdateFromSeek();
    return S_OK;
}

CSourceSeeking::ChangeStart

CSourceSeeking クラス

開始位置が変更されたときに呼び出される。

構文

virtual HRESULT ChangeStart(void) PURE;

戻り値

HRESULT 値を返す。

注意

SetPositions メソッドは、開始位置が変更された場合にこのメソッドを呼び出す。これは、純粋仮想メソッドであり、派生クラスはこのメソッドを実装しなければならない。シーク処理後は、タイム スタンプはゼロからもう一度開始する必要がある。また、メディア タイムは、新しい開始タイムを反映する必要がある。次の例は、可能な実装を示している。

HRESULT CMyStream::ChangeStart( )
{
    m_rtSampleTime = 0;          // タイム スタンプをリセットする。
    m_rtMediaTime = m_rtStart;   // メディア タイムをリセットする。
    UpdateFromSeek();
    return S_OK;
}

CSourceSeeking::ChangeStop

CSourceSeeking クラス

停止位置が変更されたときに呼び出される。

構文

virtual HRESULT ChangeStop(void) PURE;

戻り値

HRESULT 値を返す。

注意

SetPositions メソッドは、停止位置が変更された場合にこのメソッドを呼び出す。これは純粋仮想メソッドであり、派生クラスはこのメソッドを実装しなければならない。次の例は、可能な実装を示している。

HRESULT CMyStream::ChangeStop( )
{
    UpdateFromSeek();
    return S_OK;
}

CSourceSeeking::CheckCapabilities

CSourceSeeking クラス

指定されたシーク能力があるかどうかをストリームに照会する。IMediaSeeking::CheckCapabilities メソッドを実装する。

構文

HRESULT CheckCapabilities(
    DWORD *pCapabilities
);

パラメータ

pCapabilities
1 つまたは複数の AM_SEEKING_SEEKING_CAPABILITIES 属性の、ビットごとの組み合わせへのポインタ。

戻り値

次の表に示す、いずれかの HRESULT 値を返す。

S_FALSE | pCapabilities のすべての能力は存在しない。
S_OK | pCapabilities のすべての能力が存在する。
E_POINTER | NULL ポインタ引数。

注意

実装されているように、このメソッドは m_dwSeekingCaps メンバ変数に対する *pCapabilities の値をチェックする。しかし、IMediaSeeking::CheckCapabilities メソッドで説明しているように、このメソッドは *pCapabilities を m_dwSeekingCaps と等しく設定しない。また、指定された能力のいずれも存在しない場合、このメソッドは E_FAIL を返さない。次に示すのは、より完全な実装である。

DWORD dwCaps;
HRESULT hr = GetCapabilities(&dwCaps);
if (SUCCEEDED(hr))
{
    dwCaps &= *pCapabilities;
    hr =  dwCaps ? ( dwCaps == *pCapabilities ? S_OK : S_FALSE ) : E_FAIL;
    *pCapabilities = dwCaps;
}
else *pCapabilities = 0;
return hr;

CSourceSeeking::ConvertTimeFormat

CSourceSeeking クラス

1 つのフォーマットを別のフォーマットに変換する。IMediaSeeking::ConvertTimeFormat メソッドを実装する。

構文

HRESULT ConvertTimeFormat(
    LONGLONG *pTarget,
    const GUID *pTargetFormat,
    LONGLONG Source,
    const GUID *pSourceFormat
);

パラメータ

pTarget
変換されたタイムを受け取る変数へのポインタ。
pTargetFormat
目的のフォーマットのタイム フォーマット GUID へのポインタ。NULL の場合は、現在のフォーマットが使用される。
Source
変換されるタイム値。
pSourceFormat
変換するフォーマットのタイム フォーマット GUID へのポインタ。NULL の場合は、現在のフォーマットが使われる。

戻り値

次の表に示す、いずれかの HRESULT 値を返す。

S_OK | 成功。
E_INVALIDARG | 無効な引数。
E_POINTER | NULL ポインタ引数。

注意

基底クラスによってサポートされる唯一のタイム フォーマットは、TIME_FORMAT_MEDIA_TIME (100 ナノ秒単位) である。pTargetFormat と pSourceFormat の両方が TIME_FORMAT_MEDIA_TIME を指定する単純な場合をのぞいて、このメソッドは、E_INVALIDARG を返す。

CSourceSeeking::CSourceSeeking

CSourceSeeking クラス

コンストラクタ メソッド。

構文

CSourceSeeking(
    const TCHAR *pName,
    LPUNKNOWN pUnk,
    HRESULT *phr,
    CCritSec *pLock
);

パラメータ

pName
オブジェクトの名前が含まれた文字列へのポインタ。詳細については、「CBaseObject」を参照すること。
pUnk
このオブジェクトの所有者へのポインタ。このオブジェクトが集成される場合、集成オブジェクトの IUnknown インターフェイスにポインタを渡す。それ以外の場合は、このパラメータに NULL を設定する。
phr
HRESULT 値へのポインタ。無視される。
pLock
このクラスによって使用される共有データを保護する、CCritSec オブジェクトへのポインタ。

CSourceSeeking::GetAvailable

CSourceSeeking クラス

シークが有効であるタイムの範囲を取得する。IMediaSeeking::GetAvailable メソッドを実装する。

構文

HRESULT GetAvailable(
    LONGLONG *pEarliest,
    LONGLONG *pLatest
);

パラメータ

pEarliest
有効なシークのため最も古いタイムを受け取る変数へのポインタ。この変数はゼロに設定される。
pLatest
有効なシークのために最も新しいタイムを受け取る変数へのポインタ。この変数は、m_rtDuration メンバ変数の値に設定される。

戻り値

S_OK を返す。

CSourceSeeking::GetCapabilities

CSourceSeeking クラス

ストリームのすべてのシーク能力を取得する。IMediaSeeking::GetCapabilities メソッドを実装する。

構文

HRESULT GetCapabilities(
    DWORD *pCapabilities
);

パラメータ

pCapabilities
AM_SEEKING_SEEKING_CAPABILITIES フラグのビットごとの組み合わせを受け取る変数へのポインタ。

戻り値

次の表に示す、いずれかの HRESULT 値を返す。

S_OK | 成功。
E_POINTER | NULL ポインタ値。

注意

シーク能力は、m_dwSeekingCaps メンバ変数によって指定される。

CSourceSeeking::GetCurrentPosition

CSourceSeeking クラス

ストリームの合計時間幅に対する、現在の位置を取得する。実装されていない。

構文

HRESULT GetCurrentPosition(
  LONGLONG *pCurrent
);

パラメータ

pCurrent
現在の位置を受け取る変数へのポインタ。現在のタイム フォーマット単位で示される。

戻り値

E_NOTIMPL を返す。

注意

通常、ソース フィルタはこのメソッドをサポートしていない。その代わり、レンダリング フィルタが CRendererPosPassThru クラスを使って現在の位置を報告する。

CSourceSeeking::GetDuration

CSourceSeeking クラス

ストリームの時間幅を取得する。IMediaSeeking::GetDuration メソッドを実装する。

構文

HRESULT GetDuration(
    LONGLONG *pDuration
);

パラメータ

pDuration
時間幅を現在のタイム フォーマット単位で受け取る変数へのポインタ。

戻り値

次の表に示す、いずれかの HRESULT 値を返す。

S_OK | 成功。
E_POINTER | NULL ポインタ値。

注意

この時間幅は、m_rtDuration メンバ変数によって指定される。

CSourceSeeking::GetPositions

CSourceSeeking クラス

現在の位置および停止位置を取得する。IMediaSeeking::GetPositions メソッドを実装する。

構文

HRESULT GetPositions(
    LONGLONG *pCurrent,
    LONGLONG *pStop
);

パラメータ

pCurrent
開始位置を受け取る変数へのポインタ。
pStop
停止位置を受け取る変数へのポインタ。

戻り値

S_OK を返す。

注意

このメソッドは、pCurrent パラメータ用に m_rtStart メンバ変数の値を返す。この変数は、現在のストリーミング位置ではない最後のシーク タイムを表す。しかし、アプリケーションがフィルタ グラフ マネージャを使って IMediaSeeking::GetPositions を呼び出すと、通常この値はソース フィルタではなく、レンダリング フィルタから提供される。

CSourceSeeking::GetPreroll

CSourceSeeking クラス

プリロール タイムを取得する。IMediaSeeking::GetPreroll メソッドを実装する。

構文

HRESULT GetPreroll(
    LONGLONG *pPreroll
);

パラメータ

pPreroll
プリロール タイムを受け取る変数へのポインタ。この値はゼロに設定される。

戻り値

次の表に示す、いずれかの値を HRESULT 値を返す。

S_OK | 成功。
E_POINTER | NULL ポインタ値。

CSourceSeeking::GetRate

CSourceSeeking クラス

再生レートを取得する。IMediaSeeking::GetRate メソッドを実装する。

構文

HRESULT GetRate(
    double *pdRate
);

パラメータ

pdRate
再生レートを受け取る変数へのポインタ。

戻り値

次の表に示す、いずれかの HRESULT 値を返す。

S_OK | 成功。
E_POINTER | NULL ポインタ値。

注意

再生レートは、m_dRateSeeking メンバ変数によって指定される。

CSourceSeeking::GetStopPosition

CSourceSeeking クラス

ストリームの時間幅に対して、再生が停止するタイムを取得する。IMediaSeeking::GetStopPosition メソッドを実装する。

構文

HRESULT GetStopPosition(
    LONGLONG *pStop
);

パラメータ

pStop
終了タイムを現在のタイム フォーマット単位で受け取る変数へのポインタ。

戻り値

次の表に示す、いずれかの HRESULT 値を返す。

S_OK | 成功。
E_POINTER | NULL ポインタ値。

注意

終了タイムは、m_rtStop メンバ関数によって指定される。

CSourceSeeking::GetTimeFormat

CSourceSeeking クラス

現在のタイム フォーマットを取得する。IMediaSeeking::GetTimeFormat メソッドを実装する。

構文

HRESULT GetTimeFormat(
    const GUID *pFormat
);

パラメータ

pFormat
タイム フォーマット GUID を受け取る変数へのポインタ。

戻り値

次の表に示す、いずれかの HRESULT 値を返す。

S_OK | 成功。
E_POINTER | NULL ポインタ値。

注意

基底クラスによってサポートされる唯一のタイム フォーマットは、TIME_FORMAT_MEDIA_TIME (100 ナノ秒単位) である。

CSourceSeeking::IsFormatSupported

CSourceSeeking クラス

特定のタイム フォーマットがサポートされているかどうかを判定する。IMediaSeeking::IsFormatSupported メソッドを実装する。

構文

HRESULT IsFormatSupported(
    const GUID *pFormat
);

パラメータ

pFormat
タイム フォーマット GUID へのポインタ。

戻り値

次の表に示す、いずれかの HRESULT 値を返す。

S_FALSE | フォーマットはサポートされていない。
S_OK | フォーマットはサポートされている。
E_POINTER | NULL ポインタ引数。

注意

基底クラスによってサポートされている唯一のタイム フォーマットは、TIME_FORMAT_MEDIA_TIME (100 ナノ秒) である。

CSourceSeeking::IsUsingTimeFormat

CSourceSeeking クラス

特定のタイム フォーマットが現在使用されているフォーマットかどうかを判定する。

構文

HRESULT IsUsingTimeFormat(
    const GUID *pFormat
);

パラメータ

pFormat
タイム フォーマット GUID へのポインタ。

戻り値

次の表に示す、いずれかの HRESULT 値を返す。

S_FALSE | 指定されたフォーマットは、現在のフォーマットではない。
S_OK | 指定されたフォーマットは、現在のフォーマットである。
E_POINTER | NULL ポインタ引数。

注意

基底クラスによってサポートされている唯一のタイム フォーマットは、TIME_FORMAT_MEDIA_TIME (100 ナノ秒単位) である。

CSourceSeeking::QueryPreferredFormat

CSourceSeeking クラス

オブジェクトの優先タイム フォーマットを取得する。IMediaSeeking::QueryPreferredFormat メソッドを実装する。

構文

HRESULT QueryPreferredFormat(
    GUID *pFormat
);

パラメータ

pFormat
タイム フォーマット GUID を受け取る変数へのポインタ。

戻り値

次の表に示す、いずれかの HRESULT 値を返す。

S_OK | 成功。
E_POINTER | NULL ポインタ値。

注意

基底クラスによってサポートされている唯一のタイム フォーマットは、TIME_FORMAT_MEDIA_TIME (100 ナノ秒単位) である。

CSourceSeeking::SetPositions

CSourceSeeking クラス

現在の位置と停止位置を設定する。IMediaSeeking::SetPositions メソッドを実装する。

構文

HRESULT SetPositions(
    LONGLONG *pCurrent,
    DWORD CurrentFlags,
    LONGLONG *pStop,
    DWORD StopFlags
);

パラメータ

pCurrent
現在の位置を指定する変数へのポインタ。
CurrentFlags
フラグのビットごとの組み合わせ。「注意」を参照すること。
pStop
終了タイムを現在のタイム フォーマットで指定する変数へのポインタ。
StopFlags
フラグのビットごとの組み合わせ。「注意」を参照すること。

戻り値

HRESULT 値を返す。次の可能な値がある。

S_OK | 成功。
E_INVALIDARG | 無効なフラグ。
E_POINTER | NULL ポインタ引数。

注意

次のフラグがサポートされる。

  • AM_SEEKING_NoPositioning
  • AM_SEEKING_AbsolutePositioning
  • AM_SEEKING_RelativePositioning
  • AM_SEEKING_IncrementalPositioning (pStop のみ)

詳細については、「IMediaSeeking::SetPositions」を参照すること。

このメソッドは、m_rtStart メンバ変数および m_rtStop メンバ変数の値を更新し、純粋仮想メソッド ChangeStart および ChangeStop を呼び出す。

CSourceSeeking::SetRate

CSourceSeeking クラス

再生レートを設定する。IMediaSeeking::SetRate メソッドを実装する。

構文

HRESULT SetRate(
    double dRate
);

パラメータ

dRate
再生レート。

戻り値

HRESULT 値を返す。

注意

このメソッドは、m_dRateSeeking メンバ変数の値を更新し、純粋仮想メソッド ChangeRate を呼び出す。このメソッドは、dRate パラメータを確認しない。

CSourceSeeking::SetTimeFormat

CSourceSeeking クラス

タイム フォーマットを設定する。IMediaSeeking::SetTimeFormat メソッドを実装する。

構文

HRESULT SetTimeFormat(
    const GUID *pFormat
);

パラメータ

pFormat
タイム フォーマット GUID へのポインタ。

戻り値

次の表に示す、いずれかの HRESULT 値を返す。

S_OK | 成功。
E_INVALIDARG | 指定されたフォーマットはサポートされていない。
E_POINTER | NULL ポインタ引数。

注意

基底クラスによってサポートされている唯一のフォーマットは、TIME_FORMAT_MEDIA_TIME (100 ナノ秒単位) である。


CSourceStream クラス

CSource フィルタ クラスの出力ピン。

宣言: Source.h

このクラスの使用の詳細については、「CSource」を参照すること。このクラスは、ピンからのストリーミング データにワーカー スレッドを提供する CAMThread クラスを継承する。CSourceStream クラスは、次のヘルパー メソッドを実装して、スレッドに要求を送る。

  • Exit
  • Init
  • Pause
  • Run
  • Stop

スレッドへの最初の要求は、Init でなくてはならない。Exit 要求によって、スレッドが終了される。実際には、これらのいずれのメソッドも直接呼び出す必要はない。これは、ピンの Active メソッドと Inactive メソッドが、必要に応じてメソッドを呼び出すためである。

このクラスは、次に示すいくつかの "ハンドラ" メソッドも提供する。

  • OnThreadCreate
  • OnThreadDestroy
  • OnThreadStartPlay

これらのメソッドは、基底クラスでは何も処理を行わないが、派生クラスはそれらにオーバーライドできる。

プロテクト メンバ変数
m_pFilter | このピンが含まれているフィルタへのポインタ。
プロテクト メソッド
OnThreadCreate | ストリーミング スレッドが初期化されたときに呼び出される。仮想。
OnThreadDestroy | ストリーミング スレッドがまもなく終了するときに呼び出される。仮想。
OnThreadStartPlay | DoBufferProcessingLoop メソッドの処理が開始されたときに呼び出される。仮想。
Active | フィルタがアクティブになったことをピンに通知する。
Inactive | フィルタがアクティブでなくなったことをピンに通知する。
GetRequest | 次のスレッド要求を待つ。
CheckRequest | ブロックせずに、スレッド要求があるかどうかを調べる。
ThreadProc | スレッド プロシージャ。仮想。
DoBufferProcessingLoop | メディア サンプルを生成し、ダウンストリームの入力ピンに提供する。仮想。
CheckMediaType | ピンが特定のメディア タイプを受け入れることができるかどうかを判定する。仮想。
GetMediaType | 優先メディア タイプを取得する。仮想。
Public メソッド
CSourceStream | コンストラクタ メソッド。
~CSourceStream | デストラクタ メソッド。仮想。
Init | ストリーミング スレッドを初期化する。
Exit | ストリーミングに終了するように通知する。
Run | ストリーミングに実行するように通知する。
Pause | ストリーミング スレッドにアクティブになるように通知する。
Stop | ストリーミング スレッドに停止するように通知する。
純粋仮想メソッド
FillBuffer | メディア タイプにデータを埋める。
IPin メソッド
QueryId | ピンの識別子を取得する。

CSourceStream.m_pFilter

CSourceStream クラス

このピンが含まれているフィルタへのポインタ。

構文

CSource *m_pFilter;

CSourceStream::Active

CSourceStream クラス

フィルタがアクティブになったことをピンに通知する。CBasePin::Active メソッドをオーバーライドする。ピンが接続されると、このメソッドはストリーミング スレッドを開始する。

構文

HRESULT Active(void);

戻り値

HRESULT 値を返す。 以下の表に示されるいずれかの値。

S_FALSE | ピンは既にアクティブである。
S_OK | 成功。
E_FAIL | スレッドを開始できなかった。

CSourceStream::CheckMediaType

CSourceStream クラス

ピンが特定のメディア タイプを受け入れることができるかどうかを判定する。純粋仮想メソッド CBasePin::CheckMediaType を実装する。

構文

virtual HRESULT CheckMediaType(
    CMediaType *pMediaType
);

パラメータ

pMediaType
照会されたメディア タイプが含まれた CMediaType オブジェクトへのポインタ。

戻り値

次の表に示されるいずれかの HRESULT 値を返す。

S_OK | ピンは、このメディア タイプをサポートしている。
E_FAIL | ピンは、このメディア タイプをサポートしていない。

注意

デフォルトでは、このピンは 1 つのメディア タイプをサポートする。このメソッドは、1 つのパラメータ版の GetMediaType メソッドを呼び出して、サポートされているタイプを取得し、照会されたタイプと比較する。ピンが 2 つ以上のメディア タイプをサポートしている場合は、このメソッドをオーバーライドする。

CSourceStream::CheckRequest

CSourceStream クラス

ブロックせずに、スレッド要求があるかどうかを調べる。

構文

BOOL CheckRequest(
    Command *pCom
);

パラメータ

pCom
最後の呼び出しで CAMThread::CallWorker メソッドに渡された値を受け取る変数へのポインタ。

戻り値

保留中の要求がある場合は TRUE を返し、ない場合は FALSE を返す。

注意

このメソッドは、CAMThread::CheckRequest メソッドをオーバーライドし、タイプ チェックを実行する。CSourceStream クラスは、pCom パラメータ用の次の列挙型を定義する。

enum Command {CMD_INIT, CMD_PAUSE, CMD_RUN, CMD_STOP, CMD_EXIT};

CSourceStream::CSourceStream

CSourceStream クラス

コンストラクタ メソッド。

構文

CSourceStream(
    TCHAR *pObjectName,
    HRESULT *phr,
    CSource *pms,
    LPCWSTR pName
);

パラメータ

pObjectName
ピンのデバッグ名が含まれた文字列へのポインタ。
phr
メソッドの成功または失敗を示す、HRESULT 値を受け取る変数へのポインタ。値を S_OK に初期化してから、オブジェクトを作成する。この値は、エラーが発生したときだけ変更される。
pms
このピンを作成した CSource フィルタへのポインタ。
pName
ピンの名前が含まれた文字列へのポインタ。

注意

pObjectName パラメータに指定された文字列は、デバッグの目的だけに使用される。詳細については、「CBaseObject」を参照すること。

pName パラメータに指定された文字列は、IPin::QueryPinInfo メソッドによって返される名前である。この名前は、QueryId メソッドが返すピン識別には使用されない。その代わり、QueryId はピン番号に基づいてピン識別子を計算する。ピン識別子は、グラフの永続性をサポートしている。詳細については、「IPin::QueryId」を参照すること。

CSourceStream::~CSourceStream

CSourceStream クラス

デストラクタ メソッド。

構文

~CSourceStream(void);

CSourceStream::DoBufferProcessingLoop

CSourceStream クラス

メディア タイプを生成し、ダウンストリームの入力ピンに提供する。

構文

virtual HRESULT DoBufferProcessingLoop(void);

戻り値

HRESULT 値を返す。 以下の表に示されるいずれかの値。

S_FALSE | スレッドは停止要求を受け取った。
S_OK | ストリームが終了したか、またはダウンストリーム フィルタはサンプルを受け入れていない。

注意

このメソッドは、データを処理するメイン ループを実装し、ダウンストリームにそのループを提供する。メソッドは、毎回ループを通じてアロケータから空のメディア サンプルを取得し、このサンプルを FillBuffer メソッドに渡す。FillBuffer メソッド (派生クラスが実装しなければならない) は、次にメディア データを生成し、サンプル バッファにそのデータを移動する。

次のいずれかの場合に、ループは終了する。

  • 入力ピンの IMemInputPin::Receive メソッドがサンプルを拒否した。
  • FillBuffer メソッドが S_FALSE を返し、ストリームの終了を示すか、またはエラー コードを返した。
  • スレッドが Stop 要求を受け取った。

DoBufferProcessingLoop メソッドは、エンドオブストリーム通知を処理する。エラーが発生すると、このメソッドは EC_ERRORABORT イベントをフィルタ グラフ マネージャに送る。

CSourceStream::Exit

CSourceStream クラス

ストリーミング スレッドに終了するように通知する。

構文

HRESULT Exit(void);

戻り値

S_OK または E_UNEXPECTED を返す。

注意

Inactive メソッドは、このメソッドを呼び出す。

CSourceStream::FillBuffer

CSourceStream クラス

メディア サンプルにデータを埋める。

構文

virtual HRESULT FillBuffer(
    IMediaSample *pSample
) PURE;

パラメータ

pSample
サンプルの IMediaSample インターフェイスへのポインタ。

戻り値

HRESULT 値を返す。 以下の表に示されるいずれかの値。

S_FALSE | ストリームの終了
S_OK | 成功

注意

派生クラスは、このメソッドを実装しなければならない。

このメソッドに提供されたメディア サンプルには、タイム スタンプがない。派生クラスは、IMediaSample::SetTime メソッドを呼び出し、タイム スタンプを設定する必要がある。メディア サンプルに対して適切な場合、派生クラスは IMediaSample::SetMediaTime メソッドを呼び出して、メディア タイムも設定する必要がある。詳細については、「DirectShow のタイムとクロック」を参照すること。

CSourceStream::GetMediaType

CSourceStream クラス

優先メディア タイプを取得する。

構文

virtual HRESULT GetMediaType(
    int iPosition,
    CMediaType *pMediaType
);

virtual HRESULT GetMediaType(
    CMediaType *pMediaType
);

パラメータ

iPosition
ゼロ ベースのインデックス値。
pMediaType
メディア タイプを受け取る CMediaType オブジェクトへのポインタ。

戻り値

次の表に示されるいずれかの HRESULT 値を返す。
S_OK | 成功。
VFW_S_NO_MORE_ITEMS | インデックスが範囲外である。
E_INVALIDARG | インデックスがゼロ以下である。
E_UNEXPECTED | 予期しないエラー。

注意

このメソッドには、2 つの版がある。1 つの版は CBasePin::GetMediaType メソッドにオーバーライドし、インデックス値をパラメータとしてとる。もう 1 つの版は 1 つのメディア タイプを取得するように設計されているので、インデックス パラメータはない。

1 つのパラメータ版のメソッドは、E_UNEXPECTED を返す。2 つのパラメータ版のメソッドは、iPosition パラメータが 1 であることを確認し、1 つのパラメータ版のメソッドを呼び出す。ピンがサポートするメディア タイプ数に応じて、これらのいずれかのメソッドをオーバーライドしなければならない。

  • ピンが確実に 1 つのメディア タイプをサポートしている場合は、1 つのパラメータ版にオーバーライドする。ピンがサポートするメディア タイプを埋め込む。
  • ピンが 2 つ以上のメディア タイプをサポートしている場合は、2 つのパラメータ版をオーバーライドする。CheckMediaType メソッドもオーバーライドする。

CSourceStream::GetRequest

CSourceStream クラス

次のスレッド要求を待つ。

構文

Command GetRequest(void);

戻り値

次のスレッド要求を返す。

注意

このメソッドは、CAMThread::GetRequest メソッドをオーバーライドする。戻り値は、次の列挙型にキャストされる。

enum Command {CMD_INIT, CMD_PAUSE, CMD_RUN, CMD_STOP, CMD_EXIT};

CSourceStream::Inactive

CSourceStream クラス

フィルタがアクティブではなくなったことをピンに通知し、CBasePin::Inactive メソッドをオーバーライドする。ストリーミング スレッドがアクティブな場合、このメソッドはストリーミング スレッドを停止し、スレッドが終了するのを待つ。

構文

HRESULT Inactive(void);

戻り値

S_OK またはほかの HRESULT 値を返す。

CSourceStream::Init

CSourceStream クラス

ストリーミング スレッドを初期化する。

構文

HRESULT Init(void);

戻り値

S_OK またはほかの HRESULT 値を返す。

注意

このメソッドは、ThreadProc メソッドに送られる最初のスレッド要求でなくてはならない。Active メソッドは、このメソッドを呼び出す。

CSourceStream::OnThreadCreate

CSourceStream クラス

ストリーミング スレッドが初期化されたときに呼び出される。

構文

virtual HRESULT OnThreadCreate(void);

戻り値

S_OK を返す。

注意

スレッド プロシージャ ThreadProc は、最初に Init 要求を受け取ったときにこのメソッドを呼び出す。このメソッドは、基底クラスでは何も処理を行わない。派生クラスは、このメソッドをオーバーライドし、スレッドを初期化できる。派生クラスがエラー コードを返した場合、スレッドでエラーが発生し、スレッドは終了される。

CSourceStream::OnThreadDestroy

CSourceStream クラス

ストリーミング スレッドがまもなく終了するときに呼び出される。

構文

virtual HRESULT OnThreadDestroy(void);

戻り値

S_OK を返す。

注意

スレッド プロシージャ ThreadProc は、このメソッドを呼び出してから終了する。このメソッドは、基底クラスでは何も処理を行わなず、派生クラスがオーバーライドするために利用可能となる。派生クラスがエラー コードを返すと、スレッドでエラー が発生し、スレッドは終了される。

CSourceStream::OnThreadStartPlay

CSourceStream クラス

DoBufferProcessingLoop メソッドの処理が開始されたときに呼び出される。

構文

virtual HRESULT OnThreadStartPlay(void);

戻り値

S_OK を返す。

注意

このメソッドは、基底クラスでは何も処理を行わず、派生クラスがオーバーライドするために利用可能となる。

CSourceStream::Pause

CSourceStream クラス

ストリーミング スレッドにアクティブになるように通知する。

構文

HRESULT Pause(void);

戻り値

S_OK または E_UNEXPECTED を返す。

注意

Active メソッドは、このメソッドを呼び出す。ThreadProc メソッドがこの要求を受け取ると、DoBufferProcessingLoop メソッドを呼び出す。

CSourceStream::QueryId

CSourceStream クラス

ピンの識別子を取得する。

構文

HRESULT QueryId(
    LPWSTR *Id
);

パラメータ

Id
ピン ID が入る文字列を受け取る変数へのポインタ。

戻り値

HRESULT 値を返す。以下の表に示されるいずれかの値。

S_OK | 成功。
E_OUTOFMEMORY | メモリ不足。
E_POINTER | NULL ポインタ引数。
VFW_E_NOT_FOUND | ピンはフィルタで見つからなかった。

注意

このメソッドは、IPin::QueryId メソッドを実装する。識別子文字列を構築するため、ピンはそれ自身をパラメータとして、CSource::FindPinNumber メソッドを呼び出す。FindPinNumber メソッドは、ゼロからインデックス設定されるピン番号を返す。QueryId は、1 つずつ戻り値をインクリメントし、結果を文字列に変換する。たとえば、最初のピンは "1" となり、2 番目のピンは "2"になり、以降も同様となる。

このメソッドが VFW_E_NOT_FOUND を返す場合は、フィルタのピン配列が無効であることを示す。この原因は、フィルタのバグである可能性が高い。

CSourceStream::Run

CSourceStream クラス

ストリーミング スレッドに実行するように通知する。

構文

HRESULT Run(void);

戻り値

S_OK または E_UNEXPECTED を返す。

注意

基底クラスでは、このメソッドは Pause 要求と同じ効果があり、使用されない。

CSourceStream::Stop

CSourceStream クラス

ストリーミング スレッドに停止するように通知する。

構文

HRESULT Stop(void);

戻り値

S_OK または E_UNEXPECTED を返す。

注意

Inactive メソッドは、このメソッドを呼び出す。

CSourceStream::ThreadProc

CSourceStream クラス

スレッド プロシージャ。純粋仮想メソッド CAMThread::ThreadProc を実装する。

構文

virtual DWORD ThreadProc(void);

戻り値

スレッドが正常に完了された場合は 0 を返し、それ以外の場合は 1 を返す。戻り値が 1 の場合、スレッドのリソースは割り当てられたままになっている可能性がある。

注意

このメソッドは、CAMThread::GetRequest メソッドを呼び出して、スレッド要求を無限に待つ。 Run または Pause 要求を受け取ると、DoBufferProcessingLoop メソッドを呼び出す。 DoBufferProcessingLoop メソッドは、Stop 要求を受け取るまでデータをプッシュする。スレッド プロシージャは、Exit 要求を受け取ったときに終了する。


CSystemClock クラス

CSystemClock クラスは、タイム情報とタイミング信号をアプリケーションに提供するシステム クロックを実装する。このクラスは、CBaseReferenceClock 基底クラスを使用して、持続性を追加したその機能のほとんどを提供する。

CSystemClock は IPersist インターフェイスを実装する。実装については、『OLE Programmers Reference (Vol. 1): Structured Storage Overview』を参照すること。

メンバ関数

CreateInstance | システム クロックのインスタンスを作成する。
CSystemClock | CSystemClock オブジェクトを作成する。

実装される IPersist メソッド

GetClassID このクロックのクラス識別子を取得する (CLSID_SystemClock)。

実装される INonDelegatingUnknown メソッド

NonDelegatingQueryInterface IID_IPersist へのポインタを渡し、ほかのインターフェイス クエリのためのベース クロックを呼び出す。

CSystemClock::CreateInstance

CSystemClock クラス

ファクトリ テンプレート テーブル内に配置されたときに新しいインスタンスを作成する。

構文

static CUnknown * WINAPI CreateInstance(
    LPUNKNOWN pUnk,
    HRESULT *phr
);

パラメータ

pUnk
制御する IUnknown インターフェイスへのポインタ。
phr
結果情報を返す HRESULT 値へのポインタ。

戻り値

新しい Component Object Model (COM) オブジェクトへのポインタを返す。

注意

このメンバ関数は、クラス ファクトリを使用してオブジェクトを作成する場合に必要である。このメンバ関数はクラス コンストラクタを呼び出す。

phr パラメータは、エラーが発生した場合にのみ変更される。入力のエラー コードの場合、作成を終了することができる。ただし、いずれにしても HRESULT エラーが検出されると作成者によってデストラクタが呼び出される。

CSystemClock::CSystemClock

CSystemClock クラス

CSystemClock オブジェクトを作成する。

構文

CSystemClock(
    TCHAR *pName,
    LPUNKNOWN pUnk,
    HRESULT *phr
);

パラメータ

pName
このオブジェクトの名前へのポインタ (デバッグ目的のみ)。
pUnk
制御する IUnknown インターフェイスへのポインタ。
phr
エラーが発生した場合に設定される HRESULT 値へのポインタ。

戻り値

戻り値なし。

注意

phr がエントリ時に S_OK 以外の値をポイントする場合、オブジェクトは作成されない。作成中にエラーが発生すると、この変数が設定される。それ以外の場合、その内容は変更されない。

CSystemClock::GetClassID

CSystemClock クラス

このクロックのクラス識別子を取得する。

構文

HRESULT GetClassID(
    CLSID *pClsID
);

パラメータ

pClsID
CLSID_SystemClock が入力される CLSID 構造体へのポインタ。

戻り値

HRESULT 値を返す。

CSystemClock::NonDelegatingQueryInterface

CSystemClock クラス

インターフェイスを取得し、参照カウントをインクリメントする。

構文

HRESULT NonDelegatingQueryInterface(
    REFIID riid,
    void **ppv
);

パラメータ

riid
参照識別子。
ppv
インターフェイスへのポインタのアドレス。

戻り値

ppv が無効な場合は、E_POINTER を返す。クエリが成功した場合は NOERROR、失敗した場合は E_NOINTERFACE を返す。

注意

このメンバ関数は、INonDelegatingUnknown::NonDelegatingQueryInterface メソッドを実装し、IReferenceClock、IPersist、および IUnknown インターフェイスへの参照を渡す。


CTransformFilter クラス

変換フィルタを実装する基底クラス。

宣言 : Transfrm.h

このクラスは 1 つの入力ピント 1 つの出力ピンを持つ変換フィルタを実装するために設計されている。入力ピント出力ピンに別のアロケータを使用する。替わってデータを処理するフィルタを作成するには、CTransInPlaceFilter クラスを使用すること。

このフィルタは入力ピンに CTransformInputPin クラスを使い、出力ピンに CTransformOutputPin クラスを使う。通常、これらのピン クラスをオーバーライドする必要はない。大部分のピン メソッドは CTransformFilter クラスに対応するメソッドを呼び出すので、必要ならそのフィルタ メソッドをオーバーライドできる。フィルタは GetPin メソッド内で両方のピンを作成する。ピン クラスをオーバーライドするなら、GetPin をオーバーライドしてカスタム ピンを作成しなければならない。

デフォルトでは、入力ピンは接続プロセス中にメディア タイプを提案しない。それゆえ、入力ピン接続はアップストリーム フィルタ (利用可能であると仮定) が提案したメディア タイプを使って作成される。フィルタを登録するとき入力メディア タイプを登録するべきである、そうすればフィルタ マッパーはそれを見つけることができる。詳細については、「DirectShow オブジェクトの登録方法」を参照すること。

出力ピンはフィルタの GetMediaType メソッドを通してメディア タイプを提案する。出力ピンはそのフィルタの入力ピンが接続されるまで、接続を拒否する。

このクラスは出力データをキューに入れない。各出力サンプルは IMemInputPin::Receive 内部から出力される。

このクラスを使うには、新しいクラスを CTransformFilter から派生し、以下のメソッドを実装する :

  • CheckInputType
  • CheckTransform
  • DecideBufferSize
  • GetMediaType
  • Transform

フィルタの要求によって、他のメソッドを同様にオーバーライドする必要がある場合もある。

Protected メンバ変数
m_bEOSDelivered | フィルタがエンドオブストリーム (EOS) 通知を送ったかどうかを示すフラグ。
m_bSampleSkipped | 最新のサンプルが落とされたかどうかを示すフラグ。
m_bQualityChanged | 品質が変更されたかどうかを示すフラグ。
m_csFilter | フィルタ状態を保護するクリティカル セクション。
m_csReceive | ストリーミング状態を保護するクリティカル セクション。
m_pInput | 入力ピンへのポインタ。
m_pOutput | 出力ピンへのポインタ。
Public メソッド
CTransformFilter | コンストラクタ メソッド。
~CTransformFilter | デストラクタ メソッド。
GetPinCount | フィルタ上のピンの数を取得する。仮想。
GetPin | ピンを取得する。仮想。
Transform | 入力サンプルを変換して出力サンプルを作成する。 仮想。
StartStreaming | フィルタがポーズ状態にスイッチしたとき呼び出される。仮想。
StopStreaming | フィルタが停止状態にスイッチしたとき呼び出される。仮想。
AlterQuality | 品質変更が要求されたことをフィルタに通知する。仮想。
SetMediaType | メディア タイプがフィルタのピンの 1 つにセットされたとき呼び出される。仮想。
CheckConnect | ピン接続が適切かどうかを確認する。 仮想。
BreakConnect | ピン接続を解除する。仮想。
CompleteConnect | ピン接続を完了する。仮想。
Receive | メディア サンプルを取得し、それを処理し、ダウンストリーム フィルタに出力サンプルを出力する。仮想。
InitializeOutputSample | 新しい出力サンプルを取得し、それを初期化する。
EndOfStream | 入力ピンから追加のデータは来ないことをフィルタに通知する。仮想。
BeginFlush | フラッシュ処理を開始する。仮想。
EndFlush | フラッシュ処理を終了する。仮想。
NewSegment | この呼出し語に受け取ったメディア サンプルがセグメントとしてグループ化されていることをフィルタに通知する。仮想。
Pure Virtual メソッド
CheckInputType | 指定されたメディア タイプが入力として許容されるかどうかチェックする。
CheckTransform | 入力メディア タイプが出力メディア タイプと互換性があるかどうかチェックする。
DecideBufferSize | 出力ピンのバッファ要求を設定する。
GetMediaType | 出力ピンの優先メディア タイプを取得する。
IMediaFilter メソッド
Stop | フィルタを停止する。
Pause | フィルタをポーズする。
IBaseFilter メソッド
FindPin | 指定した ID でピンを取得する。

CTransformFilter.m_bEOSDelivered

CTransformFilter クラス

フィルタがエンドオブストリーム (EOS) 通知を送ったかどうかを示すフラグ。

構文

BOOL m_bEOSDelivered;

注意

入力接続を持っていないとき、フィルタがポーズなら、フィルタはエンドオブストリーム (EOS) 通知をダウンストリームに送り、このフラグを TRUE に設定する。エンドオブストリーム (EOS) 通知によってダウンストリーム フィルタはサンプルを待たなくなる。フィルタの EndOfStream メソッドはこのフラグを セットしない ことに注意。

CTransformFilter.m_bSampleSkipped

CTransformFilter クラス

最新のサンプルが落とされたかどうかを示すフラグ。もし Receive がサンプルを落としたなら、それはこの値を TRUE に設定する。

構文

BOOL m_bSampleSkipped;

CTransformFilter.m_bQualityChanged

CTransformFilter クラス

品質が変更されたかどうかを示すフラグ。フィルタがサンプルを落とすと、最初に EC_QUALITY_CHANGE イベントをフィルタ グラフ マネージャに送り、このフラグを TRUE に設定する。たとえサンプルのドロップが続いても、フィルタが停止し再スタートするまで、このイベントは再送信されない。

構文

BOOL m_bQualityChanged;

CTransformFilter.m_csFilter

CTransformFilter クラス

フィルタ状態を保護するクリティカル セクション。詳細については、「フィルタ開発者が使用するデータ フロー」を参照すること。

構文

CCritSec m_csFilter;

CTransformFilter.m_csReceive

CTransformFilter クラス

ストリーミング状態を保護するクリティカル セクション。詳細については、「フィルタ開発者が使用するデータ フロー」を参照すること。

構文

CCritSec m_csReceive;

CTransformFilter.m_pInput

CTransformFilter クラス

入力ピンへのポインタ。

構文

CTransformInputPin *m_pInput;

CTransformFilter.m_pOutput

CTransformFilter クラス

出力ピンへのポインタ。

構文

CTransformOutputPin *m_pOutput;

CTransformFilter::AlterQuality

CTransformFilter クラス

品質変更が要求されたことをフィルタに通知する。

構文

virtual HRESULT AlterQuality(
    Quality q
);

パラメータ

q
品質管理メッセージが入る Quality 構造体。

戻り値

HRESULT 値を返す。 以下の表に示されるいずれかの値。

S_FALSE | 品質メッセージを処理できなかった。メッセージはアップストリームに渡されるべきだ。
S_OK | 品質メッセージを処理した。これ以上の作業は不要である。

基底クラスは S_FALSE を返す。

注意

フィルタが品質コントロールを処理できるなら、このメソッドをオーバーライドすること。詳細については、「品質コントロールの管理」を参照すること。

CTransformFilter::BeginFlush

CTransformFilter クラス

フラッシュ処理を開始する。

構文

virtual HRESULT BeginFlush(void);

戻り値

S_OK を返す、あるいは他の HRESULT 値を返す。

注意

フラッシュ処理開始時に入力ピンの CTransformInputPin::BeginFlush メソッドはこのメソッドを呼び出す。このメソッドは BeginFlush 呼び出しをダウンストリームに渡す。

派生クラスがサンプルの出力にワーカー スレッドを使っているなら、フラッシュ処理中にキューに入っているデータを破棄すべきである。それは BeginFlush メソッド内か、EndFlush メソッド内で行うことができる。しかし、 BeginFlush への呼び出しはストリーミング スレッドとは同期していないことに注意。もし BeginFlush メソッドがキューに入っているデータを破棄するなら、フィルタは BeginFlush 呼び出しと EndFlush 呼び出しの間にデータの処理をしない事に注意しなければならない。詳細については、「フィルタ開発者が使用するデータ フロー」を参照すること。

CTransformFilter::BreakConnect

CTransformFilter クラス

ピン接続を解除する。

構文

virtual HRESULT BreakConnect(
    PIN_DIRECTION dir
);

パラメータ

dir
PIN_DIRECTION 列挙型のメンバ、(入力ピンあるいは出力ピンの)ピン接続が離れたかどうかを示す。

戻り値

S_OK を返す。

注意

CTransformInputPin::BreakConnect と CTransformOutputPin::BreakConnect メソッドはピン接続を解除するときこのメソッドを呼び出す。このメソッドは基底クラスでは何もしない。CheckConnect メソッドをオーバーライドするなら、このメソッドをオーバーライドして CheckConnect メソッドで取得したインターフェイスのポインタを含むリソースをリリ－スする。

CTransformFilter::CheckConnect

CTransformFilter クラス

ピン接続が適切かどうかを確認する。

構文

virtual HRESULT CheckConnect(
    PIN_DIRECTION dir,
    IPin *pPin
);

パラメータ

dir
PIN_DIRECTION 列挙型のメンバ、フィルタのどのピンが接続を作成するかを示す。
pPin
この接続を試みている相手の IPin インターフェイスへのポインタ。

戻り値

S_OK を返す。

注意

CTransformInputPin::CheckConnect と CTransformOutputPin::CheckConnect メソッドはピン接続プロセス中にこのメソッドを呼び出す。このメソッドは基底クラスでは何もしない。派生クラスはそれをオーバーライドできる。たとえば、派生クラスは個別のインターフェイスで別のピンをクエリする場合がある。

CTransformFilter::CheckInputType

CTransformFilter クラス

指定されたメディア タイプが入力として許容されるかどうかチェックする。

構文

virtual HRESULT CheckInputType(
    const CMediaType *mtIn
) PURE;

パラメータ

mtIn
メディア タイプを指定する CMediaType オブジェクトへのポインタ。

戻り値

HRESULT 値を返す。 以下の表に示されるいずれかの値。

S_OK | メディア タイプは許容された。
VFW_E_TYPE_NOT_ACCEPTED | メディア タイプは許容されない。

注意

派生クラスはこのメソッドを実装しなければならない。提案された入力フォーマットが許容可能であれば S_OK が返る、そうでなければエラーコードが返る。

このメソッドは (必要だとしても) 入力フォーマットが出力フォーマットと互換性があるかを検証しない。入力ピンは CheckTransform メソッドを呼び出してそれを検証する。

CTransformFilter::CheckTransform

CTransformFilter クラス

入力メディア タイプが出力メディア タイプと互換性があるかどうかチェックする。

構文

virtual HRESULT CheckTransform(
    const CMediaType *mtIn,
    const CMediaType *mtOut
) PURE;

パラメータ

mtIn
入力タイプを指定する CMediaType オブジェクトへのポインタ。
mtOut
出力タイプを指定する CMediaType オブジェクトへのポインタ。

戻り値

HRESULT 値を返す。 以下の表に示されるいずれかの値。

S_OK | メディア タイプは互換性がある。
VFW_E_TYPE_NOT_ACCEPTED | メディア タイプは互換性がない。

注意

派生クラスはこのメソッドを実装しなければならない。提案された入力フォーマットが許容可能であれば S_OK が返る、そうでなければエラーコードが返る。

CTransformFilter::CompleteConnect

CTransformFilter クラス

ピン接続を完了する。

構文

virtual HRESULT CompleteConnect(
    PIN_DIRECTION direction,
    IPin *pReceivePin
);

パラメータ

direction
PIN_DIRECTION 列挙型のメンバ、フィルタのどのピンが接続を作成するかを示す。
pReceivePin
この接続を試みている相手の IPin インターフェイスへのポインタ。

戻り値

S_OK を返す。

注意

CTransformInputPin::CompleteConnect と CTransformOutputPin::CompleteConnect メソッドはピン接続プロセス中にこのメソッドを呼び出す。このメソッドは基底クラスでは何もしないが、派生クラスはそれをオーバーライドできる。

CTransformFilter::CTransformFilter

CTransformFilter クラス

コンストラクタ メソッド。

構文

CTransformFilter(
    TCHAR *pObjectName,
    LPUNKNOWN lpUnk,
    CLSID clsid
);

パラメータ

pObjectName
フィルタのデバッグ名が入る文字列。詳細については、「CBaseObject」を参照すること。
lpUnk
このオブジェクトの所有者へのポインタ。オブジェクトが集成されているなら、集成オブジェクトの IUnknown インターフェイスへのポインタを渡し、このパラメータを NULL にする。
clsid
フィルタのクラス ID。

注意

コンストラクタはフィルタのピンを作成しない。それは GetPin メソッドを最初に呼び出す間に行われる。コンストラクタは m_pInput と m_pOutput メンバ変数を NULL に初期化する。

CTransformFilter::~CTransformFilter

CTransformFilter クラス

デストラクタ メソッド。

構文

~CTransformFilter(void);

CTransformFilter::DecideBufferSize

CTransformFilter クラス

出力ピンのバッファ要求を設定する。

構文

virtual HRESULT DecideBufferSize(
    IMemAllocator *pAlloc,
    ALLOCATOR_PROPERTIES *ppropInputRequest
) PURE;

パラメータ

pAlloc
出力ピンのアロケータの IMemAllocator インターフェイスへのポインタ。
ppropInputRequest
ダウンストリーム入力ピンからのバッファ要求が入る ALLOCATOR_PROPERTIES 構造体へのポインタ。

戻り値

S_OK を返す、あるいは他の HRESULT 値を返す。

注意

出力ピンの CTransformOutputPin::DecideBufferSize メソッドはこのメソッドを呼び出す。派生クラスはこのメソッドを実装しなければならない。詳細については、「CBaseOutputPin::DecideBufferSize」を参照すること。

CTransformFilter::EndFlush

CTransformFilter クラス

フラッシュ処理を終了する。

構文

virtual HRESULT EndFlush(void);

戻り値

S_OK を返す、あるいは他の HRESULT 値を返す。

注意

フラッシュ処理の終りに、入力ピンの CTransformInputPin::EndFlush メソッドはコンメソッドを呼び出す。このメソッドは EndFlush 呼び出しをダウンストリームに渡す。

派生クラスがワーカースレッドを使ってサンプルを出力するなら、EndFlush 呼び出しをダウンストリームに送る前にキュー内のデータを破棄しなければならない。詳細については、「フィルタ開発者が使用するデータ フロー」を参照すること。

CTransformFilter::EndOfStream

CTransformFilter クラス

入力ピンから追加のデータは来ないことをフィルタに通知する。

構文

virtual HRESULT EndOfStream(void);

戻り値

S_OK を返す、あるいは他の HRESULT 値を返す。

注意

入力ピンの CTransformInputPin::EndOfStream メソッドはこのメソッドを呼び出す。このメソッドはエンドオブストリーム (EOS) 通知をダウンストリームに出力する。派生クラスがワーカースレッドを使ってメディア サンプルを出力するなら、このメソッドをオーバーライドしてエンドオブストリーム (EOS) 通知をキューに入れるべきである。

CTransformFilter::FindPin

CTransformFilter クラス

指定した ID でピンを取得する。IBaseFilter::FindPin メソッドの実装。

構文

HRESULT FindPin(
    LPCWSTR Id,
    IPin **ppPin
);

パラメータ

Id
ピン ID が入るワイド文字列。
ppPin
ピンの IPin インターフェイスへのポインタを受け取る変数のアドレス。メソッドが失敗すると、*ppPin は NULL にセットされる。

戻り値

以下の表に示される HRESULT 値の 1 つを返す。

S_OK | 成功。
E_OUTOFMEMORY | メモリ不足。
E_POINTER | NULL ポインタ引数。
VFW_E_NOT_FOUND | この ID でピンを見つけられなかった。

注意

入力ピンの ID は In であり、出力ピンの ID は Out である。

CTransformFilter::GetMediaType

CTransformFilter クラス

出力ピンの優先メディア タイプを取得する。

構文

virtual HRESULT GetMediaType(
    int iPosition,
    CMediaType *pMediaType
) PURE;

パラメータ

iPosition
ゼロから始まるインデックス値
pMediaType
メディア タイプを受け取る CMediaType オブジェクトへのポインタ。

戻り値

HRESULT 値を返す。 以下の表に示されるいずれかの値。

S_OK | 成功。
VFW_S_NO_MORE_ITEMS | インデックスが許容幅を超えた。
E_INVALIDARG | インデックスがゼロより小さい。

注意

出力ピンの CTransformOutputPin::GetMediaType メソッドはこのメソッドを呼び出す。派生クラスはこのメソッドを実装しなければならない。 詳細については、「CBasePin::GetMediaType を参照すること。

CTransformFilter::GetPin

CTransformFilter クラス

ピンを取得する。

構文

virtual CBasePin *GetPin(
    int n
);

パラメータ

n
指定されたピンの数、ゼロから始まるインデックス。このフィルタでは、ピン 0 は入力ピンで、ピン 1 は出力ピン。

戻り値

ピンを実装する CBasePin オブジェクトへのポインタを返す、メソッドが失敗すると NULL を返す。

注意

このメソッドは純粋仮想 CBaseFilter::GetPin メソッドを実装する。初めてメソッドが呼び出されると、両方のピンを作成する。

このメソッドは返ったピンの参照カウントをインクリメントしないので、返ったピンは未処理の参照カウントを持たない。呼び出し元がピンへの参照を保持する必要があるなら、そのピンで IUnknown::AddRef を呼び出すべきである。

フィルタがデフォルトCTransformInputPin ピンと CTransformOutputPin ピンを使うなら、このメソッドをオーバーライドする必要はない。しかしフィルタがクラスを拡張したピンを使うなら。このメソッドをオーバーライドしてそのタイプのピンを作成しなければならない。

CTransformFilter::GetPinCount

CTransformFilter クラス

フィルタ上のピンの数を取得する。

構文

virtual int GetPinCount(void);

戻り値

2 を返す。

注意

このメソッドは CBaseFilter::GetPinCount メソッドをオーバーライドする。実際にはこのクラスは入力ピン 1 つと出力ピン 1 つをサポートする。

CTransformFilter::InitializeOutputSample

CTransformFilter クラス

新しい出力サンプルを取得し、それを初期化する。

構文

HRESULT InitializeOutputSample(
    IMediaSample *pSample,
    IMediaSample **ppOutSample
);

パラメータ

pSample
入力サンプルの IMediaSample インターフェイスへのポインタ。
ppOutSample
出力サンプルの IMediaSample インターフェイスへのポインタを受け取る変数のアドレス。

戻り値

S_OK を返す、あるいは別の HRESULT 値を返す。

注意

このメソッドは新しいサンプルを出力ピンのアロケータから取得する、次に入力サンプルから出力サンプルにサンプル プロパティをコピーする。

CTransformFilter::NewSegment

CTransformFilter クラス

この呼出し語に受け取ったメディア サンプルがセグメントとしてグループ化されていることをフィルタに通知する。

構文

virtual HRESULT NewSegment(
    REFERENCE_TIME tStart,
    REFERENCE_TIME tStop,
    double dRate
);

パラメータ

tStart
セグメントの開始タイム、オリジナル ソースからの相対値。
tStop
セグメントのストップ タイム、オリジナル ソースからの相対値。
dRate
セグメントが処理されるべきレート。

戻り値

S_OK を返す。

注意

入力ピンの CTransformInputPin::NewSegment メソッドはこのメソッドを呼び出す。このメソッドは NewSegment 呼び出しをダウンストリームの入力ピンに出力する。

CTransformFilter::Pause

CTransformFilter クラス

フィルタをポーズする。IMediaFilter::Pause を実装。

構文

HRESULT Pause(void);

戻り値

S_OK を返す、あるいは他の HRESULT 値を返す。

注意

このメソッドは StartStreaming メソッドを呼び出す。StartStreaming メソッドは基底クラスでは何もしないが、派生クラスはそれをオーバーライドできる。

CTransformFilter::Receive

CTransformFilter クラス

メディア サンプルを取得し、それを処理し、ダウンストリーム フィルタに出力サンプルを出力する。

構文

HRESULT Receive(
    IMediaSample *pSample
);

パラメータ

pSample
入力サンプルの IMediaSample インターフェイスへのポインタ。

戻り値

HRESULT 値を返す。

注意

フィルタの入力ピンはサンプルを取得したときこのメソッドを呼び出す。このメソッドは InitializeOutputSample メソッドを呼び出す、それは新しい出力サンプルを準備する。次にそれは Transform メソッドを呼び出す、これは派生クラスが実装しなければならない。Transform メソッドは入力データを処理し、出力データを作成する。

Transform メソッドが S_FALSE を返すと、Receive メソッドはこのサンプルをドロップする。最初のドロップ サンプルで、フィルタは EC_QUALITY_CHANGE イベントをフィルタ グラフ マネージャに送る。一方、Transform が S_OK を返すなら、フィルタは出力サンプルを出力する。そのために、IMemInputPin::Receive メソッドをダウンストリーム入力ピンで呼び出す。

CTransformFilter::SetMediaType

CTransformFilter クラス

メディア タイプがフィルタのピンの 1 つにセットされたとき呼び出される。

構文

virtual HRESULT SetMediaType(
    PIN_DIRECTION direction,
    const CMediaType *pmt
);

パラメータ

direction
PIN_DIRECTION 列挙型のメンバ、フィルタのピン(入力ピンあるいは出力ピン)を指定する。
pmt
メディア タイプを指定する CMediaType オブジェクトへのポインタ。

戻り値

S_OK を返す。

注意

CTransformInputPin::SetMediaType メソッドと CTransformOutputPin::SetMediaType メソッドはピンのメディアタイプを設定するときこのメソッドを呼び出す。このメソッドは基底クラスでは何もしないが、派生クラスはそれをオーバーライドできる。

CTransformFilter::StartStreaming

CTransformFilter クラス

フィルタがポーズ状態にスイッチしたとき呼び出される。

構文

virtual HRESULT StartStreaming(void);

戻り値

S_OK を返す。

注意

このメソッドは基底クラスでは何もしないが、派生クラスはそれをオーバーライドできる。

CTransformFilter::Stop

CTransformFilter クラス

フィルタを停止する。IMediaFilter::Stop メソッドの実装。

構文

HRESULT Stop(void);

戻り値

S_OK を返す、あるいは他の HRESULT 値を返す。

注意

このメソッドは両方のアロケータをデコミットにした後で、StopStreaming メソッドを呼び出す。StopStreaming メソッドは基底クラスでは何もしないが、派生クラスはそれをオーバーライドできる。

CTransformFilter::StopStreaming

CTransformFilter クラス

フィルタが停止状態にスイッチしたとき呼び出される。

構文

virtual HRESULT StopStreaming(void);

戻り値

S_OK を返す。

注意

このメソッドは基底クラスでは何もしないが、派生クラスはそれをオーバーライドできる。

CTransformFilter::Transform

CTransformFilter クラス

入力サンプルを変換して出力サンプルを作成する。

構文

virtual HRESULT Transform(
    IMediaSample *pIn,
    IMediaSample *pOut
)

パラメータ

pIn
入力サンプルの IMediaSample インターフェイスへのポインタ。
pOut
出力サンプルの IMediaSample インターフェイスへのポインタ。

戻り値

基底クラスは E_UNEXPECTED を返す。

派生クラスは成功失敗を示す HRESULT 値を返すべきである。 以下の表に示されるいずれかの値。

S_FALSE | このサンプルを出力しない。
S_OK | 成功。

注意

出力データを作成するにはこのメソッドをオーバーライドすること。入力データを pIn パラメータで指定されたサンプルから読み込み。新しいデータを pOut パラメータで指定されたサンプルに書き込む。

フィルタがこのメソッドを呼び出す前に、それは入力サンプルから出力サンプルにプロパティをコピーする。Transform メソッドは 2 つのサンプル間で異なるプロパティをセットすべきである、それには IMediaSample メソッドを使うか、あるいは (もし利用可能なら) IMediaSample2 インターフェイスを使う。

フィルタがこのサンプルを出力するべきではないなら (たとえば、品質管理をコントロールするため)、このメソッドは S_FALSE を返すべきである。


CTransformInputPin クラス

CTransformFilter クラスが使用する入力ピン。

宣言 : Transfrm.h

通常、このクラスを派生させる必要はない。このクラスの大部分のメソッドはオーバーライド可能な CTransformFilter クラスの対応するメソッドを呼び出している。このクラスから派生させるなら、フィルタの CTransformFilter::GetPin メソッドをオーバーライドし、その派生クラスのインスタンスを作成しなければならない。

Protected メンバ変数
m_pTransformFilter | 所有者フィルタへのポインタ。
Public メソッド
CTransformInputPin | コンストラクタ メソッド。
CheckConnect | ピン接続が適切かどうかを確認する。
BreakConnect | ピンの接続を解除する。
CompleteConnect | 別のピンへの接続を完了する。
CheckMediaType | ピンが指定したメディア タイプを許容するかどうかを確認する。
SetMediaType | 接続の際のメディア タイプを設定する。
CheckStreaming | ピンがサンプルを許容するかどうかを確認する。 仮想。
CurrentMediaType | 現在のピン接続のメディア タイプを取得する。
IPin メソッド
QueryId | ピンの ID を取得する。
EndOfStream | 追加データがない事をピンに通知する。
BeginFlush | フラッシュ処理を開始する。
EndFlush | フラッシュ処理を終了する。
NewSegment | この呼び出し後に受け取ったメディア サンプルがセグメントとしてグループ化されたことをピンに通知する。
IMemInputPin メソッド
Receive | ストリーム内の次のメディア サンプルを取得する。

CTransformInputPin.m_pTransformFilter

CTransformInputPin クラス

所有者フィルタへのポインタ。

構文

CTransformFilter *m_pTransformFilter;

CTransformInputPin::BeginFlush

CTransformInputPin クラス

フラッシュ処理を開始する。IPin::BeginFlush メソッドの実装。

構文

HRESULT BeginFlush(void);

戻り値

HRESULT 値を返す。 以下の表に示されるいずれかの値。

S_OK | 成功。
VFW_E_NOT_CONNECTED | 出力ピンが接続されていない。

注意

このメソッドはピンの CBaseInputPin::BeginFlush メソッドを呼び出す。次にそれはフィルタの CTransformFilter::BeginFlush メソッドを呼び出し、データストリーム呼び出しを出力する。

CTransformInputPin::BreakConnect

CTransformInputPin クラス

ピンの接続を解除する。

構文

HRESULT BreakConnect(void);

戻り値

S_OK を返す、あるいは他の HRESULT 値を返す。

注意

このメソッドは CBaseInputPin::BreakConnect メソッドをオーバーライドする。それは基底クラスでは S_OK を返す、フィルタの CTransformFilter::BreakConnect メソッドを呼び出す。派生クラスは CTransformFilter::BreakConnect メソッドをオーバーライドすることができる。

CTransformInputPin::CheckConnect

CTransformInputPin クラス

ピン接続が適切かどうかを確認する。

構文

HRESULT CheckConnect(
    IPin *pPin
);

パラメータ

pPin
出力ピンの IPin インターフェイスへのポインタ。

戻り値

HRESULT 値を返す。以下の表に示されるいずれかの値。

S_OK | 成功。
VFW_E_INVALID_DIRECTION | ピンの向きが正しくない。

注意

このメソッドは CBasePin::CheckConnect メソッドをオーバーライドする。それは基底クラスでは S_OK を返すフィルタの CTransformFilter::CheckConnect メソッドを呼び出す。派生クラスは CTransformFilter::CheckConnect メソッドをオーバーライドして、追加のチェックを行うことができる。

CTransformInputPin::CheckMediaType

CTransformInputPin クラス

ピンが指定したメディア タイプを許容するかどうかを確認する。

構文

HRESULT CheckMediaType(
    const CMediaType *mtIn
);

パラメータ

mtIn
提案されたメディア タイプが入る CMediaType オブジェクトへのポインタ。

戻り値

S_OK を返す、あるいは他の HRESULT 値を返す。

注意

このメソッドは純粋仮想 CBasePin::CheckMediaType メソッドを実装する。それはフィルタの CTransformFilter::CheckInputType メソッドを呼び出す、それもまた純粋仮想である。フィルタの派生クラスは CheckInputType を実装して、与えられた入力タイプが許容されるかどうかを確認しなければならない。

フィルタの出力ピンが接続されているなら、今メソッドはまたフィルタの CTransformFilter::CheckTransform メソッドを呼び出し、入力タイプが出力タイプと互換性があるかどうかをも確認する。CheckTransform メソッドは同様に純粋仮想である。

CTransformInputPin::CheckStreaming

CTransformInputPin クラス

ピンがサンプルを許容するかどうかを確認する。

構文

HRESULT CheckStreaming(void);

戻り値

HRESULT 値を返す。以下の表に示されるいずれかの値。

S_OK | 成功。
S_FALSE | ピンは現在フラッシュ中である。
VFW_E_NOT_CONNECTED | 出力ピンが接続されていない。
VFW_E_RUNTIME_ERROR | ランタイムエラーが発生した。
VFW_E_WRONG_STATE | ピンが停止している。

注意

このメソッドは CBaseInputPin::CheckStreaming メソッド をオーバーライドする。

CTransformInputPin::CompleteConnect

CTransformInputPin クラス

別のピンへの接続を完了する。

構文

HRESULT CompleteConnect(
    IPin *pReceivePin
);

パラメータ

pReceivePin
別のピンの IPin インターフェイスへのポインタ。

戻り値

S_OK を返す、あるいは他の HRESULT 値を返す。

注意

このメソッドは CBasePin::CompleteConnect メソッドをオーバーライドする。それは基底クラスでは S_OK を返すフィルタの CTransformFilter::CompleteConnect メソッドを呼び出す。派生クラスは CTransformFilter::CompleteConnect メソッドをオーバーライドして追加チェックを行うことができる。

CTransformInputPin::CTransformInputPin

CTransformInputPin クラス

コンストラクタ メソッド。

構文

CTransformInputPin(
    TCHAR *pObjectName,
    CTransformFilter *pTransformFilter,
    HRESULT *phr,
    LPCWSTR pName
);

パラメータ

pObjectName
オブジェクトのデバッグ名が入る文字列。詳細については、「CBaseObject」を参照すること。
pTransformFilter
このピンを作成したフィルタへのポインタ、それは CTransformFilter オブジェクトでなければならない。
phr
メソッドの成功失敗を示す HRESULT 値を受け取る変数へのポインタ。オブジェクトを作成する前に S_OK でその値を初期化すること。この値はエラーが起きた場合のみ変更される。
pName
接続しているピン名が入る Unicode™ 文字列。

注意

pName パラメータは IPin::QueryPinInfo メソッドが返すピン名を指定する。しかし、この文字列はピン ID としては 使われていない。このクラスではピン ID は必ず In である。詳細については、「QueryId」を参照すること。

CTransformInputPin::CurrentMediaType

CTransformInputPin クラス

現在のピン接続のメディア タイプを取得する。

構文

CMediaType& CurrentMediaType(void);

戻り値

CBasePin::m_mt メンバ変数への参照を返す。

CTransformInputPin::EndFlush

CTransformInputPin クラス

フラッシュ処理を終了する。IPin::EndFlush メソッドの実装。

構文

HRESULT EndFlush(void);

戻り値

HRESULT 値を返す。 以下の表に示されるいずれかの値。

S_OK | 成功。
VFW_E_NOT_CONNECTED | 出力ピンが接続されていない。

注意

このメソッドはフィルタの CTransformFilter::EndFlush メソッドを呼び出し、ダウンストリーム呼び出しを出力する。次にそれはピンの CBaseInputPin::EndFlush メソッドを呼び出す。

CTransformInputPin::EndOfStream

CTransformInputPin クラス

追加データがない事をピンに通知する。 IPin::EndOfStream メソッドの実装。

構文

HRESULT EndOfStream(void);

戻り値

HRESULT 値を返す。 以下の表に示されるいずれかの値。

S_OK | 成功。
S_FALSE | ピンは現在フラッシュ中である。
VFW_E_NOT_CONNECTED | 出力ピンが接続されていない。
VFW_E_RUNTIME_ERROR | ランタイムエラーが発生。
VFW_E_WRONG_STATE | ピンは停止中である。

注意

このメソッドはフィルタの CTransformFilter::EndOfStream メソッドを呼び出し、エンドオブストリーム (EOS) 通知をダウンストリームに出力する。

CTransformInputPin::NewSegment

CTransformInputPin クラス

この呼び出し後に受け取ったメディア サンプルがセグメントとしてグループ化されたことをピンに通知する。IPin::NewSegment メソッドの実装。

構文

HRESULT NewSegment(
    REFERENCE_TIME tStart,
    REFERENCE_TIME tStop,
    double dRate
);

パラメータ

tStart
セグメントの開始タイム。
tStop
セグメントのストップ タイム。
dRate
セグメントのレート。

戻り値

S_OK を返す、あるいは他の HRESULT 値を返す。

注意

このメソッドは CBasePin::NewSegment メソッドをオーバーライドする。それはフィルタの CTransformFilter::NewSegment メソッド を呼び出し、ダウンストリーム呼び出しを出力する。

CTransformInputPin::QueryId

CTransformInputPin クラス

ピンの ID を取得する。IPin::QueryId メソッドの実装。

構文

HRESULT QueryId(
    LPWSTR *Id
);

パラメータ

Id
ピン ID が入る文字列を受け取る変数のアドレス。

戻り値

以下の表に示される HRESULT 値の 1 つを返す。

S_OK | 成功。
E_OUTOFMEMORY | メモリ不足。
E_POINTER | NULL ポインタ引数。

注意

ピン ID はグラフで用いられる。このクラスのピン ID は In である。このクラスは CBasePin クラスの振る舞いをオーバーライドする。CBasePin クラスでは、ピン ID はクラス コンストラクタで指定されたピン名と同じである。CTransformInputPin クラスでは、ピン ID とピン名は同じではない。

CTransformInputPin::Receive

CTransformInputPin クラス

ストリーム内の次のメディア サンプルを取得する。IMemInputPin::Receive メソッドの実装。

構文

HRESULT Receive(
    IMediaSample *pSample
);

パラメータ

pSample
サンプルの IMediaSample インターフェイスへのポインタ。

戻り値

HRESULT 値を返す。 以下の表に示されるいずれかの値。

S_FALSE | ピンは現在フラッシュ中である、サンプルは拒否された。
S_OK | 成功。

注意

このメソッドはピンの CBaseInputPin::Receive メソッドを呼び出す、それはピンのストリーミング状態をチェックし、メディアタイプのフォーマット変更をチェックする。次にフィルタの CTransformFilter::Receive メソッドを呼び出す、それはサンプルを処理し、ダウンストリームに出力する。

このメソッドが返った後でフィルタがサンプルにアクセスする必要があるなら、サンプルで IUnknown::AddRef メソッドを呼び出し、参照カウントを保持すべきである。たとえば、あるデコーダ フィルタは次のサンプルをでコードするために現在のサンプルを必要とする。

CTransformInputPin::SetMediaType

CTransformInputPin クラス

接続の際のメディア タイプを設定する。

構文

HRESULT SetMediaType(
    const CMediaType *mt
);

パラメータ

mt
メディア タイプを指定する CMediaType オブジェクトへのポインタ。

戻り値

S_OK を返す。

注意

このメソッドは CBasePin::SetMediaType メソッドをオーバーライドする。それはフィルタの CTransformFilter::SetMediaType メソッドを呼び出し、フィルタに情報を与える。

ピンはメディア タイプがこのメソッドを呼び出す前にアクセス可能であることを検証しなければならない。


CTransformOutputPin クラス

CTransformFilter クラスが使用する出力ピン。

宣言: Transfrm.h

通常、このクラスを派生させる必要はない。このクラスの大部分のメソッドはオーバーライド可能な CTransformFilter クラスの対応するメソッドを呼び出している。このクラスから派生させるなら、フィルタの CTransformFilter::GetPin メソッドをオーバーライドし、その派生クラスのインスタンスを作成しなければならない。

Protected メンバ変数
m_pTransformFilter | 所有者フィルタへのポインタ。
Public Member Variables
m_pPosition | シークコマンドをアップストリームに渡すヘルパー オブジェクト。
Public メソッド
CTransformOutputPin | コンストラクタ メソッド。
~CTransformOutputPin | デストラクタ メソッド。
CheckConnect | ピン接続が適切かどうかを確認する。
BreakConnect | ピンの接続を解除する。
CompleteConnect | 別のピンへの接続を完了する。
CheckMediaType | ピンが指定したメディア タイプを許容するかどうかを確認する。
SetMediaType | 接続の際のメディア タイプを設定する。
DecideBufferSize | バッファ要求を設定する。
GetMediaType | インデックス値で優先メディア タイプを取得する。
CurrentMediaType | 現在のピン接続のメディア タイプを取得する。
IPin Methods
QueryId | ピンの ID を取得する。
IQualityControl Methods
Notify | 品質変更が要求された事をピンに通知する。

CTransformOutputPin.m_pTransformFilter

CTransformOutputPin クラス

所有者フィルタへのポインタ。

構文

CTransformOutputPin *m_pTransformFilter;

CTransformOutputPin.m_pPosition

CTransformOutputPin クラス

シークコマンドをアップストリームに渡すヘルパー オブジェクト。

構文

IUnknown *m_pPosition;

注意

ピンが最初に IMediaPosition インターフェイスあるいは IMediaSeeking インターフェイスでクエリされるとき、それは CPosPassThru オブジェクトを作成、集成する。

CTransformOutputPin::BreakConnect

CTransformOutputPin クラス

ピンの接続を解除する。

構文

HRESULT BreakConnect(void);

戻り値

S_OK を返す、あるいは他の HRESULT 値を返す。

注意

このメソッドは CBaseOutputPin::BreakConnect メソッドをオーバーライドする。それは基底クラスでは S_OK を返す、フィルタの CTransformFilter::BreakConnect メソッドを呼び出す。派生クラスは CTransformFilter::BreakConnect メソッドをオーバーライドすることができる。

CTransformOutputPin::CheckConnect

CTransformOutputPin クラス

ピン接続が適切かどうかを確認する。

構文

HRESULT CheckConnect(
    IPin *pPin
);

パラメータ

pPin
出力ピンの IPin インターフェイスへのポインタ。

戻り値

HRESULT 値を返す。以下の表に示されるいずれかの値。

S_OK | 成功。
E_UNEXPECTED | フィルタの入力ピンが接続されていない。

注意

このメソッドは CBaseOutputPin::CheckConnect メソッドをオーバーライドする。それは基底クラスでは S_OK を返すフィルタの CTransformFilter::CheckConnect メソッドを呼び出す。派生クラスは CTransformFilter::CheckConnect メソッドをオーバーライドして、追加のチェックを行うことができる。

CTransformOutputPin::CheckMediaType

CTransformOutputPin クラス

ピンが指定したメディア タイプを許容するかどうかを確認する。

構文

HRESULT CheckMediaType(
    const CMediaType *mtIn
);

パラメータ

mtIn
提案されたメディア タイプが入る CMediaType オブジェクトへのポインタ。

戻り値

HRESULT 値を返す。 以下の表に示されるいずれかの値。

S_OK | 成功。
E_INVALIDARG | フィルタの入力ピンが接続されていない。

注意

このメソッドは純粋仮想 CBasePin::CheckMediaType メソッドを実装する。このメソッドはフィルタの入力ピンが接続されていないと失敗する。そうでなければ、それはフィルタの CTransformFilter::CheckTransform メソッドを呼び出す、それもまた純粋仮想である。フィルタの派生クラスは CheckTransform を実装して、提案された出力メディア タイプが入力メディア タイプと互換性があるかどうかを確認する。

CTransformOutputPin::CompleteConnect

CTransformOutputPin クラス

別のピンへの接続を完了する。

構文

HRESULT CompleteConnect(
    IPin *pReceivePin
);

パラメータ

pReceivePin
別のピンの IPin インターフェイスへのポインタ。

戻り値

S_OK を返す、あるいは他の HRESULT 値を返す。

注意

このメソッドは CBaseOutputPin::CompleteConnect メソッドをオーバーライドする。それは基底クラスでは S_OK を返すフィルタの CTransformFilter::CompleteConnect メソッドを呼び出す。派生クラスは CTransformFilter::CompleteConnect メソッドをオーバーライドして追加チェックを行うことができる。

CTransformOutputPin::CTransformOutputPin

CTransformOutputPin クラス

コンストラクタ メソッド。

構文

CTransformOutputPin(
    TCHAR *pObjectName,
    CTransformFilter *pTransformFilter,
    HRESULT *phr,
    LPCWSTR pName
);

パラメータ

pObjectName
オブジェクトのデバッグ名が入る文字列。詳細については、「CBaseObject」を参照すること。
pTransformFilter
このピンを作成したフィルタへのポインタ、それは CTransformFilter オブジェクトでなければならない。
phr
メソッドの成功失敗を示す HRESULT 値を受け取る変数へのポインタ。オブジェクトを作成する前に S_OK でその値を初期化すること。この値はエラーが起きた場合のみ変更される。
pName
接続しているピン名が入る Unicode™ 文字列。

注意

pName パラメータは IPin::QueryPinInfo メソッドが返すピン名を指定する。しかし、この文字列はピン ID としては 使われていない。このクラスではピン ID は必ず Out である。詳細については、「QueryId」を参照すること。

CTransformOutputPin::~CTransformOutputPin

CTransformOutputPin クラス

デストラクタ メソッド。

構文

~CTransformOutputPin(void);

CTransformOutputPin::CurrentMediaType

CTransformOutputPin クラス

現在のピン接続のメディア タイプを取得する。

構文

CMediaType& CurrentMediaType(void);

戻り値

CBasePin::m_mt メンバ変数への参照を返す。

CTransformOutputPin::DecideBufferSize

CTransformOutputPin クラス

バッファ要求を設定する。

構文

HRESULT DecideBufferSize(
    IMemAllocator *pAlloc,
    ALLOCATOR_PROPERTIES *ppropInputRequest
);

パラメータ

pAlloc
アロケータの IMemAllocator インターフェイスへのポインタ。
ppropInputRequest
入力ピンのバッファ要求が入る ALLOCATOR_PROPERTIES 構造体のポインタ。

戻り値

HRESULT 値を返す。

注意

このメソッドは CBaseOutputPin::DecideBufferSize メソッドをオーバーライドする。フィルタの純粋仮想 CTransformFilter::DecideBufferSize メソッドを呼び出す、フィルタの派生クラスはそれを実装しなければならない。

CTransformOutputPin::GetMediaType

CTransformOutputPin クラス

インデックス値で優先メディア タイプを取得する

構文

HRESULT GetMediaType(
    int iPosition,
    CMediaType *pMediaType
);

パラメータ

iPosition
ゼロから始まるインデックス データ。
pMediaType
メディア タイプを受け取る CMediaType オブジェクトへのポインタ。

戻り値

HRESULT 値を返す。 以下の表に示されるいずれかの値。

S_OK | 成功。
VFW_S_NO_MORE_ITEMS | インデックスが制限幅を超えた。

注意

このメソッドは CBasePin::GetMediaType メソッドをオーバーライドする。フィルタの入力ピンが接続されていないと、そのメソッドは VFW_S_NO_MORE_ITEMS を返す。そうでなければ、フィルタの CTransformFilter::GetMediaType メソッドを呼び出し、メディア タイプを取得する。CTransformFilter::GetMediaType メソッドは純粋仮想である、フィルタの派生クラスはそれをオーバーライドしなければならない。

CTransformOutputPin::Notify

CTransformOutputPin クラス

品質変更が要求されたことをピンに通知する。IQualityControl::Notify メソッドの実装。

構文

HRESULT Notify(
    IBaseFilter *pSelf,
    Quality q
);

パラメータ

pSelf
品質管理メッセージを出力するフィルタの IBaseFilter インターフェイスへのポインタ。
q
品質管理メッセージが入る Quality 構造体。

戻り値

HRESULT 値を返す。 以下の表に示されるいずれかの値。

S_OK | 成功。
VFW_E_NOT_FOUND | メッセージを許容するオブジェクトを見つけられなかった。

注意

このメソッドはフィルタの CTransformFilter::AlterQuality メソッドを呼び出す。フィルタが品質メッセージを処理しないなら、このメソッドは CBaseInputPin::PassNotify メソッドをフィルタの入力ピンで呼び出す。PassNotify メソッドは品質メッセージをアップストリームに渡す (あるいは、インストールされているなら、カスタム品質マネージャに渡す)。

CTransformOutputPin::QueryId

CTransformOutputPin クラス

ピンの ID を取得する。IPin::QueryId メソッドの実装

構文

HRESULT QueryId(
    LPWSTR *Id
);

パラメータ

Id
ピン ID が入る文字列を受け取る変数のアドレス。

戻り値

以下の表に示される HRESULT 値の 1 つを返す。

S_OK | 成功。
E_OUTOFMEMORY | メモリ不足。
E_POINTER | NULL ポインタ引数。

注意

ピン ID はグラフで用いられる。このクラスのピン ID は Out である。このクラスは CBasePin クラスの振る舞いをオーバーライドする。CBasePin クラスでは、ピン ID はクラス コンストラクタで指定されたピン名と同じである。CTransformInputPin クラスでは、ピン ID とピン名は同じではない。

CTransformOutputPin::SetMediaType

CTransformOutputPin クラス

接続の際のメディア タイプを設定する。

構文

HRESULT SetMediaType(
    const CMediaType *mt
);

パラメータ

mt
メディア タイプを指定する CMediaType オブジェクトへのポインタ。

戻り値

S_OK を返す。

注意

このメソッドは CBasePin::SetMediaType メソッドをオーバーライドする。それはフィルタの CTransformFilter::SetMediaType メソッドを呼び出し、フィルタに情報を与える。

ピンはメディア タイプがこのメソッドを呼び出す前にアクセス可能であることを検証しなければならない。


CTransInPlaceFilter クラス

インプレイス変換フィルタを実装する基底クラス。

宣言 : Transfrm.h

CTransInPlaceFilter クラスはデータ変換を、バッファ間のデータ コピーをせずに、インプレイスで行うフィルタ用に設計されている。

可能な限り、フィルタは 1 つのアロケータを使う。詳細については、CompleteConnect」を参照すること。

このクラスを使うには、CTransInPlaceFilter から新しいクラスを派生し。以下のメソッドを実装すること :

  • CTransformFilter::CheckInputType
  • Transform

このフィルタは入力ピンに CTransInPlaceInputPin クラスを使い、出力ピンに CTransInPlaceOutputPin クラスを使う。通常、これらのピンクラスをオーバーライドする必要はない。フィルタは両ピンを GetPin メソッドで作成する。ピンクラスをオーバーライドするなら、カスタム ピンを作る GetPin をオーバーライドしなければならない。

Protected メソッド
Copy | メディア サンプルをコピーする。
InputPin | フィルタの入力ピンへのポインタを取得する。
OutputPin | フィルタの出力ピンへのポインタを取得する。
TypesMatch | 入力メディア タイプが出力メディア タイプと一致するかどうか確認する。
UsingDifferentAllocators | 入力ピンと出力ピンが異なるアロケータを使っているかどうかを確認する。
Public メソッド
CTransInPlaceFilter | コンストラクタ メソッド。
GetPin | ピンを取得する。
GetMediaType | 出力ピン用の優先メディア タイプを取得する。
DecideBufferSize | 出力ピンのバッファ要求を設定する。
CheckTransform | 入力メディア タイプが出力メディア タイプと互換性があるかどうかをチェックする。
CompleteConnect | ピン接続を完了する。
Receive | メディア サンプルを受け取り、それを処理し、ダウンストリーム フィルタに出力する。
Pure Virtual メソッド
Transform | サンプルをインプレイスで変換する。

CTransInPlaceFilter::CheckTransform

CTransInPlaceFilter クラス

入力メディア タイプが出力メディア タイプと互換性があるかどうかをチェックする。

構文

HRESULT CheckTransform(
    const CMediaType *mtIn,
    const CMediaType *mtOut
);

パラメータ

mtIn
入力タイプを指定する CMediaType オブジェクトへのポインタ。
mtOut
出力タイプを指定する CMediaType オブジェクトへのポインタ。

戻り値

S_OK を返す。

注意

このメソッドは CTransformFilter::CheckTransform メソッドをオーバーライドする。CTransInPlace 内のメソッドは、入力タイプと出力タイプが同じであると仮定して、CheckTransform の代わりに、CTransformFilter::CheckInputType メソッドを呼び出す。

CTransInPlaceFilter::CompleteConnect

CTransInPlaceFilter クラス

ピン接続を完了する。

構文

HRESULT CompleteConnect(
    PIN_DIRECTION direction,
    IPin *pReceivePin
);

パラメータ

direction
フィルタのどのピンが接続を作成しているかを指定する PIN_DIRECTION 列挙型のメンバ。
pReceivePin
この接続を試みている別のピンの IPin インターフェイスへのポインタ。

戻り値

HRESULT 値を返す。以下のテーブルに示されるいずれかの値。

S_OK | 成功。
VFW_E_NOT_IN_GRAPH | フィルタがフィルタ グラフにない。

注意

このメソッドは CTransformFilter::CompleteConnect メソッドをオーバーライドする。

フィルタの振る舞いはピン接続の順番に依存する :

  • 入力ピンが最初に接続されると、接続はテンポラリ ロケータを使用する。出力ピンが接続されるとき、フィルタは入力ピンを再接続する。入力ピンの再接続によってアップストリーム フィルタはアロケータと再度ネゴシエーションする。そのときに、入力ピンはデータストリーム フィルタのアロケータを使おうとする。詳細については、「CTransInPlaceInputPin::GetAllocator」を参照すること。
  • 出力ピンが最初に接続されると、出力ピンはアロケータを選択しない。入力ピンが接続されるとき、両方の接続に 1 つのアロケータをネゴシエーションする。入力メディア タイプと出力メディア タイプが同じではない場合、フィルタは入力タイプを使って出力ピンと再接続する。

フィルタは CBaseFilter::ReconnectPin メソッドを呼び出すことによって、すべてのピンの再接続を行う。 ReconnectPin メソッドはフィルタ グラフ マネージャの IFilterGraph2::ReconnectEx メソッドを順順に呼び出す。

CTransInPlaceFilter::Copy

CTransInPlaceFilter クラス

メディア サンプルをコピーする。

構文

IMediaSample *CTransInPlaceFilter::Copy(
    IMediaSample *pSource
);

パラメータ

pSource
サンプルの IMediaSample インターフェイスへのポインタ。

戻り値

新しいサンプルの IMediaSample インターフェイスへのポインタを返す。

注意

このメソッドはダウンストリーム アロケータから空のバッファを取得する。それはサンプル内の実際のデータと共に、pSource からすべてのサンプル プロパティを新しいサンプルにコピーする。フィルタが 2 つのアロケータを使っているなら、このメソッドを呼び出して、バッファ間でデータをコピーする。

CTransInPlaceFilter::CTransInPlaceFilter

CTransInPlaceFilter クラス

コンストラクタ メソッド。

構文

CTransInPlaceFilter(
    TCHAR *pObjectName,
    LPUNKNOWN lpUnk,
    REFCLSID clsid,
    HRESULT *phr,
    bool bModifiesData = true
);

パラメータ

pObjectName
フィルタのデバッグ名が入る文字列。詳細については、「CBaseObject」を参照すること。
lpUnk
このオブジェクトの所有者へのポインタ。オブジェクトが集成されているなら、集成オブジェクトの IUnknown へのポインタを渡す。そうでなければ、このパラメータを NULL に設定する。
clsid
フィルタのクラス ID。
phr
無視される。
bModifiesData
フィルタが入力データを修正するかどうかを指定するブール値。TRUE なら、フィルタはデータを修正する。それ以外なら、フィルタはデータを変更せずダウンストリームに渡す。

CTransInPlaceFilter::DecideBufferSize

CTransInPlaceFilter クラス

出力ピンのバッファ要求を設定する。

構文

HRESULT DecideBufferSize(
    IMemAllocator *pAlloc,
    ALLOCATOR_PROPERTIES *pProperties
);

パラメータ

pAlloc
出力ピンが使用する IMemAllocator オブジェクトへのポインタ。
pProperties
要求されたアロケータ プロパティ へのポインタ、それは ALLOCATOR_PROPERTIES に指定されているカウント、サイズ、アラインメントである。

戻り値

HRESULT 値を返す。以下のテーブルに示されるいずれかの値。

S_OK | 成功。
E_FAIL | 失敗。

注意

このメソッドは CTransformFilter::DecideBufferSize メソッドをオーバーライドする。それは以前のバージョンの CTransInPlaceFilter 暮らすとの互換性のために存在する。現在のバージョンでは、アップストリーム出力ピンはアロケータのダウンストリーム入力ピンと直接ネゴシエーションする。フィルタの出力ピンはこれに関わらない。

CTransInPlaceFilter::GetMediaType

CTransInPlaceFilter クラス

出力ピン用の優先メディア タイプを取得する。

構文

HRESULT GetMediaType(
    int iPosition,
    CMediaType *pMediaType
);

パラメータ

iPosition
ゼロから始まるインデックス値。
pMediaType
メディア タイプを受け取る CMediaType オブジェクトへのポインタ。

戻り値

E_UNEXPECTED を返す。

注意

このメソッドは CTransformFilter::GetMediaType メソッドをオーバーライドする。CTransInPlaceFilter クラスでは、各ピンは向かいの接続ピンを呼び出し、優先メディア タイプを列挙する。入力ピンはダウンストリーム フィルタの入力ピンを呼び出し、出力ピンはアップストリーム フィルタの出力ピンをアップストリームを呼び出す。それゆえ、フィルタの GetMediaType メソッドは決して呼び出されない。

CTransInPlaceFilter::GetPin

CTransInPlaceFilter クラス

ピンを取得する。

構文

virtual CBasePin *GetPin(
    int n
);

パラメータ

n
指定したピンの数、ゼロから始まるインデックス。このフィルタでは、ピン 0 は入力ピンで、ピン 1 は出力ピンである。

戻り値

ピンを実装する CBasePin オブジェクトへのポインタを返す、メソッドが失敗すると NULL を返す。

注意

このメソッドは CTransformFilter::GetPin メソッドをオーバーライドする。最初にこのメソッドが呼び出されたとき、両方のピンを作成する。

このメソッドは返ってきたピンの参照カウントをインクリメントしないので、返ったピンは参照カウントを残さない。呼び出し元がそのピンの参照カウントを保持する必要があるなら、そのピンの IUnknown::AddRef メソッドを呼び出すべきである。

フィルタがデフォルトの CTransInPlaceInputPin ピンと CTransInPlaceOutputPin ピンを使うなら、このメソッドをオーバーライドする必要はない。しかし、フィルタがこれらのクラスを拡張したピンを使うなら、このメソッドをオーバーライドしてそのタイプのピンを作成しなければならない。

CTransInPlaceFilter::InputPin

CTransInPlaceFilter クラス

フィルタの入力ピンへのポインタを取得する。

構文

CTransInPlaceInputPin *InputPin(void);

戻り値

CTransformFilter.m_pInput メンバ変数を返す。

CTransInPlaceFilter::OutputPin

CTransInPlaceFilter クラス

フィルタの出力ピンへのポインタを取得する。

構文

CTransInPlaceOutputPin *OutputPin(void);

戻り値

CTransformFilter.m_pOutput メンバ変数を返す。

CTransInPlaceFilter::Receive

CTransInPlaceFilter クラス

メディア サンプルを受け取り、それを処理し、ダウンストリーム フィルタに出力する。

構文

HRESULT Receive(
    IMediaSample *pSample
);

パラメータ

pSample
サンプルの IMediaSample インターフェイスへのポインタ。

戻り値

HRESULT 値を返す。以下のテーブルに示されるいずれかの値。

S_OK | 成功。
E_UNEXPECTED | 予期せぬエラー。

注意

フィルタの入力ピンはサンプルを取得するとき、このメソッドを呼び出す。フィルタは Transform メソッドを呼び出す、派生クラスはそれを実装しなければならない。Transform メソッドはデータを処理する。フィルタが 1 つのアロケータだけを使っているなら、pSample を直接 Tranform メソッドに渡す。それ以外なら、pSample をコピーして、そのコピーを渡す。

Transform メソッドが S_FALSE を返すと、Receive メソッドはサンプルをドロップする。最初にドロップされたサンプルでは、フィルタは EC_QUALITY_CHANGE イベントをフィルタ グラフ マネージャに送る。一方、Transform メソッドが S_OK を返すと、フィルタは出力サンプルを出力する。それを行うため、ダウンストリーム入力ピンの IMemInputPin::Receive メソッドを呼び出す。

CTransInPlaceFilter::Transform

CTransInPlaceFilter クラス

サンプルをインプレイスで変換する。

構文

virtual HRESULT Transform(
    IMediaSample *pSample
) PURE;

パラメータ

pSample
サンプルの IMediaSample インターフェイスへのポインタ。

戻り値

HRESULT 値を返す。以下のテーブルに示されるいずれかの値。

S_FALSE | このサンプルを出力できない。
S_OK | 成功。

注意

派生クラスはこのメソッドを実装しなければならない。サンプル データをインプレイスで変換すること。フィルタが 2 つのアロケータを使っているなら、入力サンプルから新しいサンプルにデータをコピーし、そのコピーをこのメソッドに渡す。

(たとえば、品質管理をサポートするために)フィルタがこのサンプルを出力するべきでないなら、メソッドは S_FALSE を返すべきである。

CTransInPlaceFilter::TypesMatch

CTransInPlaceFilter クラス

入力メディア タイプが出力メディア タイプと一致するかどうか確認する。

構文

BOOL TypesMatch(void);

戻り値

入力メディア タイプと出力メディア タイプが同じなら TRUE を返し、それ以外なら FALSE を返す。

CTransInPlaceFilter::UsingDifferentAllocators

CTransInPlaceFilter クラス

入力ピンと出力ピンが異なるアロケータを使っているかどうかを確認する。

構文

BOOL UsingDifferentAllocators(void) const;

戻り値

入力ピンと出力ピンが違うアロケータを使っているなら TRUE を返し、それ以外なら FALSE を返す。


CTransInPlaceInputPin クラス

CTransInPlaceFilter クラスが使用する入力ピン。

宣言 : Transip.h

通常、このクラスから派生させる必要はない。派生させるなら、フィルタの CTransInPlaceFilter::GetPin メソッド をオーバーライドし、派生クラスのインスタンスを作成しなければならない。

Protected Member 変数
m_bReadOnly | 入力ストリームが読み込み専用かどうかを指定するフラグ。
m_pTIPFilter | このピンを作成したフィルタへのポインタ。
Public メソッド
CTransInPlaceInputPin | コンストラクタ メソッド。
CheckMediaType | 指定したメディア タイプが許容されることを確認する。
PeekAllocator | ピンのアロケータへのポインタを取得する。
ReadOnly | 入力ストリームが読み込み専用かどうかを確認する。
IPin メソッド
EnumMediaTypes | ピンの優先メディア タイプを列挙する。
IMemInputPin メソッド
GetAllocator | このピンが提案したメモリ アロケータを取得する。
NotifyAllocator | 接続のアロケータを指定する。
GetAllocatorRequirements | ピンが要求したアロケータを取得する。

CTransInPlaceInputPin.m_bReadOnly

CTransInPlaceInputPin クラス

入力ストリームが読み込み専用かどうかを指定するフラグ。アップストリーム フィルタ が NotifyAllocator メソッドを呼び出したとき、この情報を指定する。デフォルトではこの値は FALSE である。

構文

BOOL m_bReadOnly;

CTransInPlaceInputPin.m_pTIPFilter

CTransInPlaceInputPin クラス

このピンを作成したフィルタへのポインタ。

構文

CTransInPlaceFilter * const m_pTIPFilter;

CTransInPlaceInputPin::CheckMediaType

CTransInPlaceInputPin クラス

指定したメディア タイプが許容されることを確認する。

構文

HRESULT CheckMediaType(
    const CMediaType *pmt
);

パラメータ

pmt
提案されたメディア タイプが入る CMediaType オブジェクトへのポインタ。

戻り値

メディア タイプが許容されるなら S_OK が返る。それ以外なら、S_FLASE かエラーコードが返る。

注意

このメソッドは CTransformInputPin::CheckMediaType メソッドをオーバーライドする。それはフィルタの CTransformFilter::CheckInputType メソッドを呼び出し、入力タイプをチェックする。出力ピンが接続されていれば、このメソッドはダウンストリーム入力ピンの IPin::QueryAccept メソッドをも呼び出し。

CTransInPlaceInputPin::CTransInPlaceInputPin

CTransInPlaceInputPin クラス

コンストラクタ メソッド。

構文

CTransInPlaceInputPin(
    TCHAR *pObjectName,
    CTransInPlaceFilter *pFilter,
    HRESULT *phr,
    LPCWSTR pName
);

パラメータ

pObjectName
オブジェクトのデバッグ名が入る文字列。詳細については、「CBaseObject」を参照すること。
pFilter
このピンを作成したフィルタへのポインタ、これは CTransformFilter オブジェクトでなければならない。
phr
メソッドの成功失敗を示す HRESULT 値を受け取る変数へのポインタ。この値はオブジェクトを作成する前に S_OK で初期化される。値はエラーが起きた場合のみ変更される。
pName
ピン名が入る Unicode™ 文字列。

注意

pName パラメータは IPin::QueryPinInfo メソッドが返すピン名を指定する。しかし、この文字列はピン ID としては 使われていない。このクラスではピン ID は必ず In である。詳細については、「QueryId」を参照すること。

CTransInPlaceInputPin::EnumMediaTypes

CTransInPlaceInputPin クラス

ピンの優先メディア タイプを列挙する。IPin::EnumMediaTypes メソッドの実装。

構文

HRESULT EnumMediaTypes(
    IEnumMediaTypes **ppEnum
);

パラメータ

ppEnum
IEnumMediaTypes インターフェイスへのポインタを受け取る変数のアドレス。

戻り値

HRESULT 値を返す。以下の表に示されるいずれかの値。

S_OK | 成功。
E_OUTOFMEMORY | メモリ不足。
E_POINTER | NULL ポインタ。
VFW_E_NOT_CONNECTED | 出力ピンが接続されていない。

注意

このメソッドはダウンストリーム入力ピンから IEnumMediaTypes インターフェイスを返す。

CTransInPlaceInputPin::GetAllocator

CTransInPlaceInputPin クラス

このピンが提案したメモリ アロケータを取得する。 IMemInputPin::GetAllocator メソッドの実装。

構文

HRESULT GetAllocator(
    IMemAllocator **ppAllocator
);

パラメータ

ppAllocator
アロケータの IMemAllocator インターフェイスへのポインタを受け取る変数のアドレス。

戻り値

HRESULT 値を返す。以下のテーブルに示されるいずれかの値。

S_OK | 成功。
VFW_E_NO_ALLOCATOR | 利用可能なアロケータがない。

注意

フィルタの出力ピンが接続されているなら、このメソッドはダウンストリーム フィルタの入力ピンを要求する。

フィルタの出力ピンが接続されていないなら、このメソッドはテンポラリ アロケータを作成する。後で、出力ピンが接続されたとき、フィルタは入力ピンと再接続し、アロケータを再ネゴシエーションする。

CTransInPlaceInputPin::GetAllocatorRequirements

CTransInPlaceInputPin クラス

ピンが要求したアロケータを取得する。IMemInputPin::GetAllocatorRequirements メソッドの実装。

構文

HRESULT GetAllocatorRequirements(
    ALLOCATOR_PROPERTIES *pProps
);

パラメータ

pProps
要求が書き込まれる ALLOCATOR_PROPERTIES 構造体へのポインタ

戻り値

HRESULT 値を返す。以下のテーブルに示されるいずれかの値。

S_OK | 成功。
E_NOTIMPL | 出力ピンが接続されていない、あるいはダウン ストリームピンがメソッドをサポートしていない。
E_POINTER | Null ポインタ引数。

注意

出力ピンが接続されていれば、このメソッドは呼び出しをダウンストリーム入力ピンに渡す。それ以外なら E_NOTIMPL を返す。

CTransInPlaceInputPin::NotifyAllocator

CTransInPlaceInputPin クラス

接続のアロケータを指定する。IMemInputPin::NotifyAllocator メソッドの実装。

構文

HRESULT NotifyAllocator(
    IMemAllocator *pAllocator,
    BOOL bReadOnly
);

パラメータ

pAllocator
アロケータの IMemAllocator インターフェイスへのポインタ。
bReadOnly
このアロケータからのサンプルが読み込み専用かどうかを示すフラグ。TRUE ならサンプルは読み込み専用。

戻り値

HRESULT 値を返す。 以下の表に示されるいずれかの値。

S_OK | 成功。
E_FAIL | 失敗。
E_POINTER | NULL ポインタ引数。

注意

フィルタは両方のピン接続に同じアロケータを使おうとする。

  • 出力ピンが接続されていないなら、入力ピンは自動的にアロケータを承認する。出力ピンが接続されていると、フィルタは入力ピンを再接続する。そのとき、フィルタは再び 1 つのアロケータを使おうとする。
  • 出力ピンが接続されていると、入力ピンはアロケータを許容する。出力ピンも同じアロケータを使用する。それはダウンストリーム入力ピンの NotifyAllocator を呼び出す。

上記のケースには次の例外がある :

  • 提案されたアロケータが読み込み専用 (これは bReadOnly が TRUE) かつ、フィルタがサンプルを集成する必要がある場合、フィルタは 2 つの異なったアロケータ使う必要がある。この場合、アップストリーム フィルタはダウンストリーム フィルタのアロケータの使用を提案すれば、メソッドは E_FAIL を返す。

CTransInPlaceInputPin::PeekAllocator

CTransInPlaceInputPin クラス

ピンのアロケータへのポインタを取得する。このメソッドはインターフェイスの参照カウントをインクリメントしない。

構文

IMemAllocator *PeekAllocator(void)

戻り値

CBaseInputPin.m_pAllocator メンバ変数を返す。

CTransInPlaceInputPin::ReadOnly

CTransInPlaceInputPin クラス

入力ストリームが読み込み専用かどうかを確認する。

構文

const BOOL ReadOnly(void);

戻り値

m_bReadOnly メンバ変数の値を返す。


CTransInPlaceOutputPin クラス

CTransInPlaceFilter クラスが使用する出力ピン。

宣言 : Transip.h

通常、このクラスから派生させる必要はない。派生させるなら、フィルタの CTransInPlaceFilter::GetPin メソッド をオーバーライドし、派生クラスのインスタンスを作成しなければならない。

Protected Member 変数
m_pTIPFilter | このピンを作成したフィルタへのポインタ。
Public メソッド
CTransInPlaceOutputPin | コンストラクタ メソッド。
DecideAllocator | メモリ アロケータを選択する。
CheckMediaType | 指定したメディア タイプをピンが許容することを確認する。
SetAllocator | 接続の際のアロケータを指定する。
ConnectedIMemInputPin | ダウンストリーム入力ピンへのポインタを取得する。
PeekAllocator | ピンのアロケータへのポインタを取得する。
IPin メソッド
EnumMediaTypes | ピンの優先メディア タイプを列挙する。

CTransInPlaceOutputPin.m_pTIPFilter

CTransInPlaceOutputPin クラス

このピンを作成したフィルタへのポインタ。

構文

CTransInPlaceFilter * const m_pTIPFilter;

CTransInPlaceOutputPin::CheckMediaType

CTransInPlaceOutputPin クラス

指定したメディア タイプをピンが許容することを確認する。

構文

HRESULT CheckMediaType(
    const CMediaType *pmt
);

パラメータ

pmt
提案されたメディアタイプを入れる CMediaType オブジェクトへのポインタ。

戻り値

HRESULT 値を返す。以下のテーブルに示されるいずれかの値。

S_OK | 成功。
VFW_E_TYPE_NOT_ACCEPTED | メディア タイプは許容されなかった。

注意

このメソッドは CTransformOutputPin::CheckMediaType メソッドをオーバーライドする。

フィルタが既にストリーミングを流し、2 つのアロケータを使っているなら、このメソッドはすべてのフォーマット変更を拒否する。それ以外なら、このメソッドはフィルタの CTransformFilter::CheckInputType メソッドを呼び出し、メディア タイプをチェックする。入力ピンが接続されているなら、アップストリーム出力ピンの IPin::QueryAccept メソッドをも呼び出す。

CTransInPlaceOutputPin::ConnectedIMemInputPin

CTransInPlaceOutputPin クラス

ダウンストリーム入力ピンへのポインタを取得する。このメソッドは CBaseOutputPin.m_pInputPin メンバ変数を返す。

構文

IMemInputPin *ConnectedIMemInputPin(void);

戻り値

ダウンストリーム入力ピンの IMemInputPin インターフェイスへのポインタを返す。

CTransInPlaceOutputPin::CTransInPlaceOutputPin

CTransInPlaceOutputPin クラス

コンストラクタ メソッド。

構文

CTransInPlaceOutputPin(
    TCHAR *pObjectName,
    CTransInPlaceFilter *pFilter,
    HRESULT *phr,
    LPCWSTR pName
);

パラメータ

pObjectName
オブジェクトのデバッグ名が入る文字列。詳細については、「CBaseObject」を参照すること。
pFilter
このピンを作成したフィルタへのポインタ、これは CTransInPlaceFilter オブジェクトでなければならない。
phr
メソッドの成功失敗を示す HRESULT 値を受け取る変数へのポインタ。この値はオブジェクトを作成する前に S_OK で初期化される。値はエラーが起きた場合のみ変更される。
pName
ピン名が入る Unicode™ 文字列。

注意

pName パラメータは IPin::QueryPinInfo メソッドが返すピン名を指定する。しかし、この文字列はピン ID としては 使われていない。このクラスではピン ID は必ず Out である。詳細については、「QueryId」を参照すること。

CTransInPlaceOutputPin::DecideAllocator

CTransInPlaceOutputPin クラス

メモリ アロケータを選択する。

構文

HRESULT DecideAllocator(
    IMemInputPin *pPin,
    IMemAllocator **ppAlloc
);

パラメータ

pPin
入力ピンの IMemInputPin インターフェイスへのポインタ。
ppAlloc
アロケータの IMemAllocator インターフェイスのポインタを受け取る変数のアドレス。

戻り値

S_OK を返す。

注意

このメソッドは CBaseOutputPin::DecideAllocator メソッドをオーバーライドする。

これは何もしないダミーメソッドである、なぜならこのフィルタの出力ピンはアロケータを提供しないからである。そのかわり、アロケータは入力ピンの接続プロセス中に決定される。入力ピンの CTransInPlaceInputPin::NotifyAllocator メソッドはダウンストリーム入力ピンの NotifyAllocator を呼び出す。

CTransInPlaceOutputPin::EnumMediaTypes

CTransInPlaceOutputPin クラス

ピンの優先メディア タイプを列挙する。IPin::EnumMediaTypes メソッドの実装。

構文

HRESULT EnumMediaTypes(
    IEnumMediaTypes **ppEnum
);

パラメータ

ppEnum
IEnumMediaTypes インターフェイスへのポインタを受け取る変数のアドレス。

戻り値

HRESULT 値を返す。以下の表に示されるいずれかの値。

S_OK | 成功。
E_OUTOFMEMORY | メモリ不足。
E_POINTER | NULL ポインタ。
VFW_E_NOT_CONNECTED | フィルタの入力ピンが接続されていない。

注意

このメソッドはアップストリーム出力ピンから IEnumMediaTypes インターフェイスを返す。

CTransInPlaceOutputPin::PeekAllocator

CTransInPlaceOutputPin クラス

ピンのアロケータへのポインタを取得する。このメソッドはインターフェイスの参照カウントをインクリメントしない。

構文

IMemAllocator *PeekAllocator(void)

戻り値

CBaseOutputPin.m_pAllocator メンバ変数を返す。

CTransInPlaceOutputPin::SetAllocator

CTransInPlaceOutputPin クラス

接続の際のアロケータを指定する。

構文

void SetAllocator(
    IMemAllocator *pAllocator
);

パラメータ

pAllocator
アロケータの IMemAllocator インターフェイスへのポインタ。

注意

このフィルタの出力ピンはアロケータを提供しない。このメソッドは出力ピン用のアロケータを指定する。それは CBaseOutputPin.m_pAllocator メンバ変数の値を設定する。


CUnknown クラス

IUnknown インターフェイスを実装する。Microsoft® DirectShow® のほとんどの Component Object Model (COM) オブジェクトは CUnknown から派生する。

宣言 : Cobmase.h

オブジェクトを実装する場合、CUnknown から派生させたい場合もある。CUknown から派生させると、スレッド対応の実装が提供されるほか、IUnknown を実装する面倒がなくなる。

この基底クラスの使い方については、「IUnknown の実装方法」を参照すること。以下にその要約を示す。

  • クラス定義の public セクションに DECLARE_IUNKNOWN マクロをインクルードする。このマクロは、IUnknown インターフェイスの 3 つのメソッドを宣言する。
  • NonDelegatingQueryInterface メソッドをオーバーライドして、IUnknown 以外のインターフェイスをサポートする。このメソッド内で GetInterface 関数を呼び出して、インターフェイス ポインタを取得する。
  • クラス コンストラクタ内で CUnknown コンストラクタ メソッドを呼び出す。
Protected メンバ変数
m_cRef | 参照カウント。
Public メソッド
CUnknown | コンストラクタ メソッド。
~CUnknown | デストラクタ メソッド。
GetOwner | 制御する IUnknown へのポインタを取得する。
INonDelegatingUnknown メソッド
NonDelegatingAddRef | 参照カウントをインクリメントする。
NonDelegatingQueryInterface | インターフェイス ポインタを取得し、参照カウントをインクリメントする。
NonDelegatingRelease | 参照カウントをデクリメントする。

CUnknown.m_cRef

CUnknown クラス

参照カウント。

構文

volatile LONG m_cRef;

注意

NonDelegatingAddRef または NonDelegatingRelease メソッドをオーバーライドする場合はこのメンバ変数を使用する。

CUnknown::CUnknown

CUnknown クラス

コンストラクタ メソッド。

構文

CUnknown(
    const TCHAR *pName,
    LPUNKNOWN pUnk
);

パラメータ

pName
オブジェクトの名前を格納している文字列。デバッギングのために CBaseObject コンストラクタで使用される。
pUnk
このオブジェクトの所有者へのポインタ。オブジェクトが集成されている場合は、集成オブジェクトの IUnknown インターフェイスにポインタを渡す。それ以外の場合は、このパラメータを NULL に設定する。

注意

オブジェクトは参照カウントがゼロとして初期化される。

CUnknown::~CUnknown

CUnknown クラス

デストラクタ メソッド。

構文

virtual ~CUnknown(void);

CUnknown::GetOwner

CUnknown クラス

所有コンポーネントの IUnknown インターフェイスへのポインタを取得する。集成したコンポーネントの場合、その所有者は外部コンポーネントである。それ以外の場合、コンポーネントはそれ自体を所有する。

構文

LPUNKNOWN GetOwner(void);

戻り値

制御する IUnknown インターフェイスへのポインタを返す。

CUnknown::NonDelegatingAddRef

CUnknown クラス

オブジェクトの参照カウントをインクリメントする。INonDelegatingUnknown::NonDelegatingAddRef メソッドを実装する。

構文

ULONG NonDelegatingAddRef(void);

戻り値

参照カウントを返す。

CUnknown::NonDelegatingQueryInterface

CUnknown クラス

インターフェイス ポインタを取得し、参照カウントをインクリメントする。INonDelegatingUnknown::NonDelegatingQueryInterface メソッドを実装する。

構文

HRESULT NonDelegatingQueryInterface(
    REFIID riid,
    void **ppv
);

パラメータ

riid
インターフェイスの識別子。
ppv
インターフェイスを受け取るポインタのアドレス。

戻り値

次の表に示されるいずれかの HRESULT 値を返す。
S_OK | 成功。
E_NOINTERFACE | オブジェクトはこのインターフェイスをサポートしていない。
E_POINTER | NULL ポインタ引数。

注意

CUnknown クラスは IUknown インターフェイスのみを公開する。このメソッドのオーバーライド方法については、「IUnknown の実装方法」を参照すること。

CUnknown::NonDelegatingRelease

CUnknown クラス

オブジェクトの参照カウントをデクリメントする。INonDelegatingUnknown::NonDelegatingRelease メソッドを実装する。

構文

ULONG NonDelegatingRelease(void);

戻り値

参照カウントを返す。

注意

参照カウントがゼロになると、オブジェクトはそれ自体を削除する。


CVideoTransformFilter クラス

CVideoTransformFilter クラスは、基本的には AVI デコンプレッサ フィルタの基底クラスとして設計されている。このクラスは、"コピー" 変換クラスに基づいており、出力バッファとしてビデオ バッファまたは Microsoft® DirectDraw® バッファを想定している。このクラスは、ほかのタイプの変換フィルタの基底クラスとしても使用できる。このクラスの主な機能は、変換フィルタでの品質 コントロールを可能にすることにある。つまり、このクラスは、処理中のメディア ストリームに関するほかの要素やフィルタの動作を考慮しながら、レンダラから受け取った品質通知に基づいてフレームをドロップすることを決定する。

CVideoTransformFilter::Receive メンバ関数が呼び出されるごとに、この関数は CVideoTransformFilter::ShouldSkipFrame を呼び出して、フレームのスキップを開始、続行、または停止するかどうかを決める。このメンバ関数は、以下の条件がすべて満たされる場合にのみ、サンプルのスキップを開始する。

  • デコードの平均タイムがフレーム タイムの 1/4 を超えている。
  • フィルタが少なくとも 1 フレーム遅れて実行されている。
  • 次のキー フレームがわずか 1 フレーム先にあると予想される。
  • キー フレームが十分な頻度で現れる。

フレームのスキップを開始すると、このクラスはキー フレームが現れるまでフレームをスキップする。このとき、m_bSkipping フラグをリセットしてサンプルを処理する。

キー フレームは、AVI キー フレームまたは MPEG I フレームとして定義される。これらはデコードするヒストリを必要とせず、これらがスキップされた場合は、次のキー フレームまでほかのフレームをデコードすることができなくなる。非キー フレームには、AVI 非キー フレーム、MPEG P フレーム、および MPEG B フレームがある。MPEG B フレームは、ほかの非キー フレームと同じようにこのクラスで扱われる。(MPEG B フレームは、フレームをスキップする必要なく、ドロップすることができる。ただし、このクラスは主に AVI デコンプレッサを対象としているので、そのような操作は許されない。いずれかのフレームがスキップされると、次のキー フレームまでのすべてのフレームがスキップされる。)

Protected データ メンバ

m_bNoSkip | 次のキー フレームまでのスキップを行わない場合は、TRUE に設定する (フィルタをデバッグする場合)。
m_bQualityChanged | ストリームが低下しているかどうかを示す状態フラグ。派生クラスの Transform メンバ関数呼び出しが失敗した場合は CVideoTransformFilter::Receive 内で TRUE に設定される。(S_FALSE はエンドオブストリームに到達したことを示すので、この場合、Receive は NOERROR を返す。)
m_bSkipping | フィルタが次のキー フレームまでスキップしている場合は TRUE に設定される.
m_idFrameType | パフォーマンス測定フレーム タイプ識別子。
m_idLate | 遅延を測定するためのパフォーマンス識別子 (PERF が定義されている場合に利用可能)。
m_idSkip | フレームのスキップを測定するためのパフォーマンス識別子。
m_idTimeTillKey | 次のキー フレームが来るまでの予想時間 (ミリ秒単位) を表すパフォーマンス識別子。
m_itrAvgDecode | サンプルのデコード (変換) に要する平均タイム。この値がフレーム タイムの 1/4 よりも小さい場合は、このフィルタでは品質に関する問題が発生しておらず、フレームのドロップも発生していないと想定される。
m_itrLate | 現在のフレームが遅れているタイム。本来この値は、レンダリング フィルタから渡された品質 コントロール メッセージ内の Quality 構造体の Late メンバの値に設定される。この値は、スキップされた各フレームのフレーム タイムから求められる。
m_nFramesSinceKeyFrame | 前回のキー フレーム以降のフレーム数をカウントするために使用する。
m_nKeyFramePeriod | キー フレーム間の間隔の最大値。
m_nWaitForKey | 最初のキー フレームを取得する前に、フォーマット変更後の出力を保証するために使用する。ゼロ以外の値の場合、フレームはレンダラに渡されない。フォーマットが変更されてそれぞれの非キー フレームでデクリメントされる場合は、30 に設定される。
m_tDecodeStart | デコーディングの開始時以降のタイム。

メンバ関数

AlterQuality | 出力ピンから品質 コントロール通知を受け取り、メディア ストリームの品質を変更する機会を提供する。
CVideoTransformFilter | CVideoTransformFilter オブジェクトを作成する。
ShouldSkipFrame | フィルタがフレームのスキップを開始、続行、または停止すべきかどうかを判定する。

オーバーライド可能なメンバ関数

EndFlush | フラッシング状態を終了した旨の通知を受け取り、それをダウンストリームに渡す。
Receive | メディア サンプルを受け取り、サンプルをスキップするか、またはメディア サンプルを変換して配送する。
RegisterPerfId | パフォーマンス計測識別子を登録する。
StartStreaming | CTransformFilter::StartStreaming をオーバーライドして、ストリーミングまたはフラッシングの開始時に品質 コントロール情報をリセットする。

CVideoTransformFilter::AlterQuality

CVideoTransformFilter クラス

品質 コントロール通知を受け取り、メディア ストリームの品質を変更する機会を提供する。

構文

virtual HRESULT AlterQuality(
    Quality q
);

パラメータ

q
品質 コントロール通知メッセージ。

戻り値

デフォルトでは E_FAIL を返す。

注意

このメンバ関数は、CTransformFilter::AlterQuality メンバ関数をオーバーライドする。このメンバ関数は、品質 コントロール メッセージをアップストリームに渡すために CBaseInputPin::PassNotify メンバ関数を呼び出す前に、CTransformOutputPin::Notify メンバ関数から呼び出される。この関数は、CVideoTransformFilter::m_itrLate データ メンバを Quality 構造体の Late メンバの値に設定して、フィルタがフレームをスキップするかどうかを判定できるようにする。この関数は E_FAIL を返すので、レンダラのダウンストリームは品質 コントロールを続行する。

CVideoTransformFilter::CVideoTransformFilter

CVideoTransformFilter クラス

CVideoTransformFilter オブジェクトを作成する。

構文

CVideoTransformFilter(
    TCHAR *pName,
    LPUNKNOWN pUnk,
    REFCLSID clsid
);

パラメータ

pName
CVideoTransformFilter オブジェクトの名前へのポインタ。
pUnk
制御する IUnknown インターフェイスへのポインタ。
clsid
CVideoTransformFilter クラスのクラス識別子。

戻り値

戻り値なし。

CVideoTransformFilter::EndFlush

CVideoTransformFilter クラス

フィルタがフラッシング状態を終了した旨の通知を受け取り、それをダウンストリームに渡す。

構文

HRESULT EndFlush(void);

戻り値

フィルタで入力ピンが検出されなかった場合は、VFW_E_NOT_CONNECTED を返す。それ以外の場合は、IPin::EndFlush メソッドが返す値を返す。

注意

このメンバ関数は、CTransformFilter::EndFlush メンバ関数をオーバーライドして品質管理情報をリセットする。

CVideoTransformFilter::Receive

CVideoTransformFilter クラス

メディア サンプルを受け取り、サンプルをスキップするか、またはメディア サンプルを変換して配送する。

構文

HRESULT Receive(
    IMediaSample *pSample
);

パラメータ

pSample
配送するサンプルへのポインタ。

戻り値

HRESULT 値を返す。

注意

このメンバ関数は、CTransformFilter::Receive メンバ関数をオーバーライドする。プロセスをさらに詳細に制御したい場合にのみオーバーライドする。

CVideoTransformFilter::RegisterPerfId

CVideoTransformFilter クラス

パフォーマンス計測識別子を登録する。

構文

virtual void RegisterPerfId(void);

戻り値

戻り値なし。

注意

デフォルトでは、このメンバ関数は以下のパフォーマンス識別子を登録する。
パフォーマンス識別子 | 登録される文字列
m_idSkip | ビデオ変換スキップ フレーム。
m_idFrameType | ビデオ変換フレーム タイプ。
m_idLate | ビデオ変換の遅延。
m_idTimeTillKey | 次のキーまでのビデオ変換の予想タイム。

派生クラスでパフォーマンス計測識別子を登録したいなら、このメンバをオーバーライドすること。その場合、同じように登録することに注意すること。

CVideoTransformFilter::ShouldSkipFrame

CVideoTransformFilter クラス

フィルタがフレームのスキップを開始、続行、または停止すべきかどうかを判定する。

構文

BOOL ShouldSkipFrame(
    IMediaSample *pIn
);

パラメータ

pIn
変換またはスキップする、受け取ったサンプルへのポインタ。

戻り値

フィルタがこのサンプルをスキップすべき場合は TRUE を返し、それ以外の場合は FALSE を返す。

注意

このメンバ関数は、サンプルがキー フレーム (sync ポイント) の場合に m_bSkipping メンバ変数を FALSE に設定し、FALSE を返す。これにより、既に開始されているスキップ処理が停止される。このメンバ関数は、以下の条件がすべて満たされる場合にのみ、サンプルのスキップを開始する (m_bSkipping を TRUE に設定し、TRUE を返す)。

  • デコードの平均タイムがフレーム タイムの 1/4 を超えている。
  • フィルタが少なくとも 1 フレーム遅れて実行されている。
  • 次のキー フレームがわずか 1 フレーム先にあると予想される。
  • キー フレームが十分な頻度で現れる。

このメンバ関数は、サンプルのスキップが開始されると EC_QUALITY_CHANGE 通知を送信する。スキップが開始されると、次のキー フレームが来るまでのすべてのサンプルがスキップされる。

CVideoTransformFilter::StartStreaming

CVideoTransformFilter クラス

CTransformFilter::StartStreaming をオーバーライドして、ストリーミングまたはフラッシングの開始時に品質 コントロール情報をリセットする。

構文

virtual HRESULT StartStreaming(void);

戻り値

NOERROR を返す。

注意

このメンバ関数は、いくつかの品質 コントロール メンバ変数 (m_itrLate、m_nKeyFramePeriod、m_nFramesSinceKeyFrame、m_bSkipping、m_tDecodeStart) を 0 に設定する。このメンバ関数は、m_itrAvgDecode を 3000 に設定し、m_bQualityChanged および m_bSampleSkipped を FALSE に設定する。


FOURCCMap クラス

FOURCCMap クラスは、GUID メディア サブタイプと古いフォーマットの FOURCC 32 ビット メディア タグとの間の変換を提供する。オリジナルの Microsoft® Windows® マルチメディア API では、メディア タイプは 4 つの 8 ビット文字から作成された 32 ビット値のタグが付けられていて、FOURCC と呼ばれていた。Microsoft DirectShow® メディア タイプでは、サブタイプとして GUID が使用される。これには、これらの作成が容易であるという 1 つの理由がある (新しい FOURCC の作成には Microsoft への登録が必要である)。FOURCC は一意なので、FOURCC を表す 40 億個の GUID の範囲を割り当てることによって 1 対 1 の関係が可能であった。この範囲は、すべて以下のフォーマットの GUID である。

XXXXXXXX-0000-0010-8000-00AA00389B71

このクラスは GUID と FOURCC との間の変換を容易にする。このクラスは、互換性を保つ目的でのみ提供される。すべての新しいメディア サブタイプは、FOURCC をマッピングするのではなく、Guidgen.exe または同様のツールで作成した GUID で表すことが推奨される。

オブジェクトは、追加のデータ メンバを持たずに GUID から派生し、GUID にキャストすることができる。オブジェクトは、作成時に FOURCC に渡すことができる。デフォルトのコンストラクタは、FOURCC をゼロに初期化する。

GetFOURCC および SetFOURCC メソッドは、GUID の固定部分が FOURCC 範囲に対応するかどうかをチェックしない。 したがって、GUID へのポインタを FOURCC へのポインタにキャストして FOURCC フィールドを設定または取得する場合は、GUID が FOURCC 範囲内に収まっていることを別個に確認する必要がある。

メンバ関数

FOURCCMap | FOURCCMap オブジェクトを作成する。
GetFOURCC | FOURCCMap オブジェクトから FOURCC を取得する。
SetFOURCC | FOURCCMap オブジェクトの FOURCC 部分を設定する。

FOURCCMap::FOURCCMap

FOURCCMap クラス

FOURCCMap オブジェクトを作成する。古いフォーマットのマルチメディア フォーマットの DWORD タイプと新しいフォーマットの GUID タイプの間のマッピングを提供する。

構文

FOURCCMap( );

FOURCCMap(

  DWORD Fourcc

  );

FOURCCMap(

  const GUID *pguid

  );

パラメータ

Fourcc
以前に Microsoft マルチメディア タイプとして使用されていた DWORD メディア タグ。
pguid
GUID (グローバル ユニーク識別子) へのポインタ。

戻り値

戻り値なし。

注意

このオブジェクトが FOURCC コードを使用して作成される場合、それに対応する GUID が作成される。このオブジェクトが既存の GUID を使用して作成される場合、オブジェクトの FOURCC 値がゼロに設定される。その FOURCC 値は、SetFOURCC または GetFOURCC メンバ関数を使用してそれぞれ設定または取得できる。

FOURCCMap::GetFOURCC

FOURCCMap クラス

FOURCCMap オブジェクトから FOURCC DWORD を取得する。

構文

DWORD GetFOURCC(void);

戻り値

FOURCC DWORD 値を返す。FOURCC から派生していない GUID を作成した場合、戻り値は基本的にランダムになる。

FOURCCMap::SetFOURCC

FOURCCMap クラス

FOURCCMap オブジェクトの FOURCC 部分を設定する。

構文

void SetFOURCC(

  const GUID *pguid

  );

パラメータ

pguid
FOURCCMap オブジェクトの返された GUID (グローバル ユニーク識別子) 部分へのポインタ。

戻り値

戻り値なし。


ユーティリティ関数

このトピックには、Microsoft® DirectShow® のユーティリティ関数およびマクロに関する説明が含まれている。

  • COM ヘルパー関数
  • DLL セットアップ関数
  • メディア タイプ関数
  • その他のヘルパー関数
  • プロパティ ページ ヘルパー関数
  • 文字列関数
  • ビデオ関数とイメージ関数


COM ヘルパー関数

宣言 : Combase.h

DECLARE_IUNKNOWN | 新しいインターフェイスの基本インターフェイスの 3 つのメソッドを宣言する。
GetInterface | 要求されたクライアントへのインターフェイス ポインタを取得する。
INonDelegatingUnknown | IUnknown インターフェイスの非委任版。
LoadOLEAut32 | Automation DLL (OleAut32.dll) を読み込む。

DECLARE_IUNKNOWN

COM ヘルパー関数

新しいインターフェイスの基本インターフェイスの 3 つのメソッドを宣言する。

構文

#define DECLARE_IUNKNOWN                                        \
    STDMETHODIMP QueryInterface(REFIID riid, void **ppv) {      \
        return GetOwner()->QueryInterface(riid,ppv);            \
    };                                                          \
    STDMETHODIMP_(ULONG) AddRef() {                             \
        return GetOwner()->AddRef();                            \
    };                                                          \
    STDMETHODIMP_(ULONG) Release() {                            \
        return GetOwner()->Release();                           \
    };

注意

新しいインターフェイスを作成する際は、IUnknown から派生しなければならない。これには、QueryInterface、AddRef、および Release の 3 つのメソッドがある。このマクロは、新しいインターフェイス用にこれらの各メソッドを宣言し、宣言プロセスを簡略化する。

GetInterface

COM ヘルパー関数

インターフェイス ポインタを取得する。

構文

HRESULT GetInterface(
    LPUNKNOWN pUnk,
    void **ppv
);

パラメータ

pUnk
IUnknown インターフェイスへのポインタ。
ppv
取得されたインターフェイスへのポインタのアドレス。

戻り値

HRESULT 値を返す。

注意

このメンバ関数は、参照カウントのスレッドセーフ インクリメントを実行する。インターフェイスを取得し、参照を追加するには、INonDelegatingUnknown::NonDelegatingQueryInterface メソッドにオーバーライドする実装から、この関数を呼び出すこと。

INonDelegatingUnknown

COM ヘルパー関数

同じ COM オブジェクトの非委任および委任 IUnknown インターフェイスの両方をサポートするクラスを有効にするために、名前を変更した IUnknown の版。このインターフェイスは、vtable 順に次の 3 つのメソッドをサポートしている。

構文

interface INonDelegatingUnknown
{
    virtual HRESULT NonDelegatingQueryInterface) (REFIID riid, LPVOID *ppv) PURE;
    virtual ULONG NonDelegatingAddRef)(void) PURE;
    virtual ULONG NonDelegatingRelease)(void) PURE;
};

注意

複数の継承に対して INonDelegatingUnknown を使うには、次のステップを実行する。

  1. インターフェイス (IMyInterface など) からクラスを派生する。
  2. クラス定義に DECLARE_IUNKNOWN をインクルードし、外部 unknown を呼び出す QueryInterface、AddRef、および Release の実装を宣言する。
  3. NonDelegatingQueryInterface にオーバーライドし、次のようなコードを使って IMyInterface を公開する。
         if (riid == IID_IMyInterface) {
         return GetInterface((IMyInterface *) this, ppv);
     } else {
         return CUnknown::NonDelegatingQueryInterface(riid, ppv);
     }
  4. MyInterface のメンバ関数を宣言し、実装する。

ネストしたインターフェイスで INonDelegatingUnknown を使うには、次のステップを実行する。

  1. CUnknown から派生したクラスを宣言する。
  2. クラス定義に DECLARE_IUNKNOWN をインクルードする。
  3. NonDelegatingQueryInterface をオーバーライドし、次のようなコードを使って IMyInterface を公開する。
         if (riid == IID_IMyInterface) {
         return GetInterface((IMyInterface *) this, ppv);
     } else {
         return CUnknown::NonDelegatingQueryInterface(riid, ppv);
     }
  4. IMyInterface のメンバ関数を実装する。CUnknown::GetOwner を使って、COM オブジェクト クラスにアクセスする。
  5. COM オブジェクト クラスで、ネストしたクラスを COM オブジェクト クラスのフレンドとし、ネストしたクラスのインスタンスを COM オブジェクト クラスのメンバとして宣言する。

    外部 unknown と HRESULT は必ず CUnknown コンストラクタに渡さなければならないので、デフォルトのコンストラクタは使用できない。メンバ変数をクラスへのポインタとし、コンストラクタで新しい呼び出しを行って、実際に作成する必要がある。

  6. 次のようなコードを使って、NonDelegatingQueryInterface をオーバーライドする。

     if (riid == IID_IMyInterface) {
         return m_pImplFilter->
            NonDelegatingQueryInterface(IID_IMyInterface, ppv);
     } else {
         return CUnknown::NonDelegatingQueryInterface(riid, ppv);
     }

複数の継承およびネストしたクラスによって、一部のインターフェイスをサポートする混合クラスを持つことができる。

LoadOLEAut32

COM ヘルパー関数

Automation ダイナミック リンク ライブラリ (OleAut32.dll) を読み込む。

構文

HINSTANCE LoadOLEAut32( );

戻り値

Automation DLL インスタンスへのハンドルを返す。

注意

CBaseObject デストラクタが OleAut32.dll を読み込んだオブジェクトを破壊する際に、ライブラリが読み込まれていると、そのライブラリはアンロードされる。


DLL セットアップ関数

宣言 : Dllsetup.h

AMovieDllRegisterServer | 使わない。
AMovieDllRegisterServer2 | フィルタを登録および登録解除する。
AMovieDllUnregisterServer | 使わない。
AMovieSetupRegisterFilter | 使わない。
AMovieSetupRegisterFilter2 | フィルタのメリット、ピン、およびメディア タイプを登録する。

AMovieDllRegisterServer

DLL セットアップ関数

使わない。代わりに AMovieDllRegisterServer2 を使用する。

構文

HRESULT AMovieDllRegisterServer(void);

AMovieDllRegisterServer2

DLL セットアップ関数

フィルタを登録および登録解除する。

構文

HRESULT AMovieDllRegisterServer2(
    BOOL bRegister
);

パラメータ

bRegister
TRUE はフィルタを登録することを表し、FALSE はフィルタの登録を解除することを表す。

戻り値

成功した場合は HRESULT 値 NOERROR を返す。それ以外の場合はエラー コードを返す。

注意

この関数はフィルタを設定するために使用する。詳細については、「DirectShow オブジェクトの登録方法」および SDK に含まれるサンプル フィルタを参照すること。

注 : フィルタ登録プロセスでは、カテゴリ別によるフィルタの登録が可能になっている。たとえば、キャプチャ フィルタと圧縮フィルタをそれぞれ対応するカテゴリにまとめて列挙することができる。以下の関数は、フィルタのカテゴリ別の登録および登録解除がどのように行われるかを示す。 以下の関数では、IFilterMapper2 インターフェイスを使用している。

static const WCHAR *g_wszName = L"Sample Compressor Filter" ;

// サンプル コンプレッサ フィルタを登録する。
STDAPI
DllRegisterServer( void )
{

    // サーバーを登録する。
    HRESULT hr = AMovieDllRegisterServer2( TRUE );
    if( FAILED(hr) )
        return hr;

    IFilterMapper2 *pFm2 = 0;

    hr = CoCreateInstance( CLSID_FilterMapper2
                           , NULL
                           , CLSCTX_INPROC_SERVER
                           , IID_IFilterMapper2
                           , (void **)&pFm2 );

    if(FAILED(hr))
        return hr;

    static const AMOVIESETUP_MEDIATYPE sudAVICoTypeOut =  {
        &MEDIATYPE_Video,
        &MEDIASUBTYPE_SampleVideoType };

    static const AMOVIESETUP_MEDIATYPE sudAVICoTypeIn =  {
        &MEDIATYPE_Video,
        &GUID_NULL };

    static const AMOVIESETUP_PIN psudAVICoPins[] =
    {
        {
            L"Input"        // strName
            , FALSE         // bRendered
            , FALSE         // bOutput
            , FALSE         // bZero
            , FALSE         // bMany
            , &CLSID_NULL   // clsConnectsToFilter
            , 0             // strConnectsToPin
            , 1             // nTypes
            , &sudAVICoTypeIn } // lpTypes
        , { L"Output"       // strName
            , FALSE         // bRendered
            , TRUE          // bOutput
            , FALSE         // bZero
            , FALSE         // bMany
            , &CLSID_NULL   // clsConnectsToFilter
            , 0             // strConnectsToPin
            , 1             // nTypes
            , &sudAVICoTypeOut
        }
    };   // lpTypes

    REGFILTER2 rf2;
    rf2.dwVersion = 1;
    rf2.dwMerit = MERIT_DO_NOT_USE;
    rf2.cPins = NUMELMS(psudAVICoPins);
    rf2.rgPins = psudAVICoPins;

    hr = pFm2->RegisterFilter(
        CLSID_SampleCompressorFilter,
        g_wszName,              // ユーザーに表示する名前
        0,                      // デバイス モニカ
        &CLSID_VideoCompressorCategory,
        g_wszName,              // 一意なインスタンス名
        &rf2);

    pFm2->Release();

    return hr;

}

// サンプル コンプレッサ フィルタの登録を解除する。
STDAPI
DllUnregisterServer( void )
{

    HRESULT hr = AMovieDllRegisterServer2( FALSE );
    if( FAILED(hr) )
        return hr;

    IFilterMapper2 *pFm2 = 0;

    hr = CoCreateInstance( CLSID_FilterMapper2
                           , NULL
                           , CLSCTX_INPROC_SERVER
                           , IID_IFilterMapper2
                           , (void **)&pFm2       );

    if(FAILED(hr))
        return hr;

    hr = pFm2->UnregisterFilter(
        &CLSID_VideoCompressorCategory,
        g_wszName,
        CLSID_SampleCompressorFilter);

    pFm2->Release();

    return hr;
}

AMovieDllUnregisterServer

DLL セットアップ関数

使わない。代わりに AMovieDllRegisterServer2 を使用する。

構文

HRESULT AMovieDllUnregisterServer(void);

AMovieSetupRegisterFilter

DLL セットアップ関数

使わない。代わりに AMovieSetupRegisterFilter2 を使用する。

構文

HRESULT AMovieSetupRegisterFilter(
    const AMOVIESETUP_FILTER const *psetupdata,
    IFilterMapper *pIFM,
    BOOL bRegister
);

AMovieSetupRegisterFilter2

DLL セットアップ関数

IFilterMapper2 を使用して、フィルタのメリット、ピン、およびメディア タイプをレジストリに登録する。

構文

HRESULT AMovieSetupRegisterFilter2(
    const AMOVIESETUP_FILTER const *psetupdata,
    IFilterMapper2 *pIFM2,
    BOOL bRegister
);

パラメータ

psetupdata
AMOVIESETUP_FILTER データへのポインタ。
pIFM
IFilterMapper2 インターフェイスへのポインタ。
bRegister
フィルタを登録するかどうかを示す値。TRUE はフィルタを登録することを表し、FALSE はフィルタの登録を解除することを表す。

戻り値

成功した場合は HRESULT 値 NOERROR を返す。それ以外の場合はエラー コードを返す。

注意

AMovieDllRegisterServer2 は、COM サーバーが登録された後に、このヘルパー関数を使用してフィルタを登録する。

通常、フィルタは AMovieDllRegisterServer2 を使用し、この関数は直接呼び出さない。


メディア タイプ関数

宣言 : Mtype.h

Microsoft® DirectShow® 基底クラスの Mtype.h ヘッダー ファイルは、メディア タイプを処理するためのヘルパー関数を提供する。これらの汎用関数は、タスク割り当て AM_MEDIA_TYPE 構造体を、作成、コピー、および削除する。これらの関数は、IEnumMediaTypes インターフェイスを使用する場合に便利である。なぜなら、後で削除しなければならない構造体が実装によって割り当てられるからである。

関数は次のように対になっている。

  • CreateMediaType は DeleteMediaType と逆の動作を行う。
  • FreeMediaType は CopyMediaType と逆の動作を行う。
AreEqualVideoTypes | 2 つのビデオ ソースのフォーマット、高さ、および幅を比較する。
CopyMediaType | タスク割り当て AM_MEDIA_TYPE 構造体をコピーする。
CreateAudioMediaType | ウェーブ フォーマット構造体が指定されたメディア タイプ構造体を初期化する。
CreateMediaType | AM_MEDIA_TYPE 構造体の割り当てと初期化を行う。
DeleteMediaType | タスク割り当て AM_MEDIA_TYPE 構造体を削除する。
FreeMediaType | タスク割り当て AM_MEDIA_TYPE 構造体をメモリから解放する。

AreEqualVideoTypes

メディア タイプ関数

2 つのメディア タイプのビデオ フォーマット、幅、および高さが同じかどうかを判定する。

構文

BOOL WINAPI AreEqualVideoTypes (
    CMediaType *pmt1,
    CMediaType *pmt2
    );

パラメータ

pmt1
比較する 1 番目のメディア タイプへのポインタ。
pmt2
比較する 2 番目のメディア タイプへのポインタ。

戻り値

pmt1 と pmt2 のビデオ フォーマット、幅、および高さが同じ場合は TRUE を返し、それ以外の場合は FALSE を返す。

CopyMediaType

メディア タイプ関数

タスク割り当て AM_MEDIA_TYPE 構造体をコピーする。

構文

void WINAPI CopyMediaType(
    AM_MEDIA_TYPE *pmtTarget,
    const AM_MEDIA_TYPE *pmtSource
    );

パラメータ

pmtTarget
構造体の新しいコピーを配置するメモリ領域へのポインタ。
pmtSource
コピーするソース構造体へのポインタ。

戻り値

戻り値なし。

注意

構造体の処理が終ったら、FreeMediaType を呼び出して pmtTarget 構造体内のリソースを解放すること。

CreateAudioMediaType

メディア タイプ関数

ウェーブ フォーマット構造体が指定されたメディア タイプ構造体を初期化する。

構文

STDAPI CreateAudioMediaType(
    const WAVEFORMATEX *pwfx,
    AM_MEDIA_TYPE *pmt,
    BOOL bSetFormat
    );

パラメータ

pwfx
提供された WAVEFORMATEX 構造体へのポインタ。
pmt
初期化する AM_MEDIA_TYPE 構造体へのポインタ。
bSetFormat
AM_MEDIA_TYPE 構造体のフォーマット セクション、つまり、cbFormat および pbFormat メンバを初期化するかどうかを示すフラグ。フォーマット セクションを初期化するには TRUE を、それ以外の場合は FALSE を指定する。

戻り値

フォーマット データのメモリを割り当てられなかった場合は E_OUTOFMEMORY を返し、それ以外の場合は S_OK を返す。

CreateMediaType

メディア タイプ関数

タスク割り当て AM_MEDIA_TYPE 構造体を作成する。

構文

AM_MEDIA_TYPE * WINAPI CreateMediaType(
    AM_MEDIA_TYPE const *pSrc
    );

パラメータ

pSrc
AM_MEDIA_TYPE ソース構造体へのポインタ。

戻り値

新しい AM_MEDIA_TYPE 構造体を返す。エラーが発生した場合は、NULL を返す。

注意

構造体の処理が終ったら、DeleteMediaType を呼び出して、このルーチンによって割り当てられた構造体およびリソースを解放すること。

DeleteMediaType

メディア タイプ関数

タスク割り当て AM_MEDIA_TYPE 構造体を削除する。

構文

void WINAPI DeleteMediaType(
    AM_MEDIA_TYPE *pmt
    );

パラメータ

pmt
AM_MEDIA_TYPE 構造体へのポインタ。

戻り値

戻り値なし。

注意

構造体は、CreateMediaType 呼び出しによって作成されていなければならない。

FreeMediaType

メディア タイプ関数

タスク割り当て AM_MEDIA_TYPE 構造体をメモリから解放する。

構文

void WINAPI FreeMediaType(
    AM_MEDIA_TYPE& mt
    );

パラメータ

mt
構造体へのポインタ。

戻り値

戻り値なし。

注意

構造体は、CopyMediaType 呼び出しによって初期化されていなければならない。


その他のヘルパー関数

宣言 : Wxutil.h

EqualPins | 同じオブジェクト上に 2 つのピンがあるかどうかを確認する。
Int64x32Div32 | a の 64 ビット値に ((a*b)+rnd)/c を実装する。
IsEqualObject | 同じオブジェクト上に 2 つのインターフェイスがあるかどうかを確認する。
llMulDiv | a の 32 ビット値に ((a*b)+rnd)/c を実装する。
WaitDispatchingMessages | ウィンドウ メッセージをディスパッチ中に、オブジェクトが通知済になるまで待つ。

EqualPins

その他のヘルパー関数

同じオブジェクト上に 2 つのピンがあるかどうかを確認する。

構文

BOOL EqualPins(
    IUnknown *pPin1,
    IUnknown *pPin2
);

パラメータ

pPin1
1 つのピンへのポインタ。
pPin2
もう 1 つのピンへのポインタ。

戻り値

同じオブジェクト上に両方のピンがある場合は TRUE を返し、ない場合は FALSE を返す。

Int64x32Div32

その他のヘルパー関数

a に b を掛け、96 ビットの結果に rnd を足し、c で割る。

構文

LONGLONG WINAPI Int64x32Div32(
  LONGLONG a,
  LONG b,
  LONG c,
  LONG rnd
  );

戻り値

(a * b + rnd)/c 計算、または次の値を返す。

0x7FFFFFFFFFFFFFFF | 結果が非常に大きい (正) ため、オーバーフローが発生した。
0x8000000000000000 | 結果が非常に大きい (負) ため、オーバーフローが発生した。

注意

除算の丸めは、ゼロとする。ゼロの除算は、オーバーフロー状態として扱われる。

IsEqualObject

その他のヘルパー関数

同じオブジェクト上に 2 つのインターフェイスがあるかどうかを確認する。

構文

BOOL WINAPI IsEqualObject(
    IUnknown *pFirst,
    IUnknown *pSecond
);

パラメータ

pFirst
1 つのインターフェイスへのポインタ。
pSecond
もう 1 つのインターフェイスへのポインタ。

戻り値

同じオブジェクト上に両方のインターフェイスがある場合は TRUE を返し、ない場合は FALSE を返す。

llMulDiv

その他のヘルパー関数

a に b を掛け、128 ビットの結果に rnd を足し、c で割る。

構文

LONGLONG WINAPI llMulDiv(
  LONGLONG a,
  LONGLONG b,
  LONGLONG c,
  LONGLONG rnd
  );

戻り値

(a * b + rnd)/c 計算、または次の値を返す。

0x7FFFFFFFFFFFFFFF | 結果が非常に大きい (正) ため、オーバーフローが発生した。
0x8000000000000000 | 結果が非常に大きい (負) ため、オーバーフローが発生した。

注意

除算の丸めは、ゼロとする。ゼロの除算は、オーバーフロー状態として扱われる。

WaitDispatchingMessages

その他のヘルパー関数

ウィンドウ メッセージをディスパッチ中に、オブジェクトが通知済になるまで待つ。

構文

DWORD WINAPI WaitDispatchingMessages(
    HANDLE hObject,
    DWORD dwWait,
    HWND hwnd = NULL,
    UINT uMsg = 0
    HANDLE hEvent = NULL;
);

パラメータ

hObject
待機するオブジェクトのハンドル。
dwWait
タイムアウトの間隔 (ミリ秒単位)。
hwnd
ウィンドウへのオプション ハンドル。
uMsg
オプションのウィンドウ メッセージ。ディスパッチするメッセージを指定する。
hEvent
待機するイベントへのオプション ハンドル。

戻り値

WaitForMultipleObjects 関数からの値を返す。

注意

オブジェクトがウィンドウを所有している場合、待機中にウィンドウ メッセージをディスパッチする必要がある。この関数によって、オブジェクトはメッセージのディスパッチ中に、イベント、セマフォ、またはほかの相互排他オブジェクトを待つことができる。


プロパティ ページ ヘルパー関数

Microsoft® DirectShow® 基底クラスの Videoctl.h ヘッダー ファイルは、プロパティ ページの実装に役立つ関数を提供する。

GetDialogSize | リソース ダイアログ ボックスのサイズを画面ピクセル単位で取得する。
StringFromResource | 指定されたリソース識別子を持つリソース ファイルから文字列をロードする。
WideStringFromResource | 指定されたリソース識別子を持つリソース ファイルから Unicode™ 文字列をロードする。

GetDialogSize

プロパティ ページ ヘルパー関数

リソース ダイアログ ボックスのサイズを取得する。

構文

BOOL WINAPI GetDialogSize(
    int iResourceID,
    DLGPROC pDlgProc,
    LPARAM lParam,
    SIZE *pResult
);

パラメータ

iResourceID
ダイアログ ボックス リソース識別子。
pDlgProc
ダイアログ ボックス プロシージャへのポインタ。
lParam
一時ダイアログ ボックスが作成された直後にその一時ダイアログ ボックスに送信される WM_INITDIALOG メッセージで渡される値。
pResult
ダイアログ ボックスの寸法 (画面ピクセル単位) を受け取る SIZE 構造体へのポインタ。

戻り値

ダイアログ ボックス リソースが検出された場合は TRUE を返し、それ以外の場合は FALSE を返す。

注意

この関数を使用して、プロパティ ページは必要な実際の表示サイズを返すことができる。ほとんどのプロパティ ページはダイアログ ボックスで、リソース ファイルに格納されたダイアログ ボックス テンプレートを持つ。テンプレートは、画面ピクセルに直接マッピングされないダイアログ ボックス単位を使用する。ただし、プロパティ ページの GetPageInfo 関数は実際の表示サイズをピクセル単位で返さなければならない。プロパティ ページは、GetDialogSize を呼び出して表示サイズを計算することができる。

この関数は、ダイアログ ボックスの一時インスタンスを作成する。ダイアログ ボックスが画面に表示されないようにするためには、リソース ファイル内のダイアログ ボックス テンプレートに WS_VISIBLE プロパティが設定されていてはならない。

StringFromResource

プロパティ ページ ヘルパー関数

指定されたリソース識別子を持つリソース ファイルから文字列をロードする。

構文

TCHAR * WINAPI StringFromResource(
    TCHAR *pBuffer,
    int iResourceID
);

パラメータ

pBuffer
iResourceID に対応する文字列へのポインタ。
iResourceID
取得する文字列のリソース識別子。

戻り値

pBuffer と同じ文字列を返す。関数が成功しなかった場合は NULL 文字列を返す。

注意

pBuffer バッファは、STR_MAX_LENGTH バイト以上でなければならない。

WideStringFromResource

プロパティ ページ ヘルパー関数

指定されたリソース識別子を持つリソース ファイルから Unicode™ 文字列をロードする。

構文

WCHAR * WINAPI WideStringFromResource(
    WCHAR *pBuffer,
    int iResourceID
);

パラメータ

pBuffer
iResourceID に対応する文字列へのポインタ。
iResourceID
取得する文字列のリソース識別子。

戻り値

pBuffer と同じ文字列を返す。関数が成功しなかった場合は NULL 文字列を返す。

注意

通常、プロパティ ページは、バイナリの作成方法に関係なく Unicode™ 文字列を使用する COM インターフェイスを介して呼び出される。この関数を使用すると、リソースの文字列を Unicode 文字列に変換することができる。この関数は、リソースをロードし、それが Unicode でない場合に Unicode 文字列に変換する。


文字列関数

宣言 : Wxutil.h

AMGetWideString | 既存の非ワイド文字列のワイド文字列バージョンを割り当ておよび作成する。
atoi | 文字列を整数に変換する。
FreeBSTR | タスクが割り当てた BSTR 文字列を解放する。
IntToWstr | 整数をワイド文字列に変換する。
lstrcmpiW | 大文字/小文字を無視して 2 つのワイド文字列を比較する。
lstrcmpW | 2 つのワイド文字列を比較する。
lstrcpynW | ワイド文字列を最大長までコピーする。
lstrcpyW | ワイド文字列をコピーする。
lstrlenW | ワイド文字でのワイド文字列の長さを取得する。
WriteBSTR | タスクが割り当てたメモリを割り当て、ワイド文字列をメモリにコピーして、タスクが割り当てた BSTR 文字列を作成する。
WstrToInt | ワイド文字列を整数に変換する。

AMGetWideString

文字列関数

既存の非 Unicode™ 文字列の Unicode バージョンを割り当ておよび作成する。

構文

STDAPI AMGetWideString(
    LPCWSTR pszString,
    LPWSTR *ppszReturn
    );

パラメータ

pszString
非 Unicode ソース 文字列へのポインタ。
ppszReturn
pszString を格納する Unicode™ 文字列へのポインタのアドレス。

戻り値

成功した場合は S_OK を返す。ppszReturn が NULL の場合は E_POINTER を、利用可能なメモリが不足している場合は E_OUTOFMEMORY を返す。

atoi

文字列関数

文字列を整数に変換する。

構文

int WINAPI atoi(
    const TCHAR *sz
    );

パラメータ

sz
ソース文字列へのポインタ。

戻り値

文字列の整数値を返す。

注意

この版の atoi は、10 進数のみをサポートし、先頭にあるスペースまたは記号は許可されない。Unicode™ 文字列と ANSI 文字列の両方をサポートする。ほかの版では異なることがある。

FreeBSTR

文字列関数

タスクが割り当てた BSTR 文字列をメモリから解放する

構文

STDAPI FreeBSTR(
    BSTR *pstr
    );

パラメータ

pstr
解放する BSTR へのポインタ。

戻り値

成功の場合は S_OK を返し、pstr が NULL の場合は S_FALSE を返す。

注意

メモリは、CoTaskMemAlloc を呼び出すことによって、インターフェイスにまたがったオブジェクト間の受け渡しのために割り当てられる。また、CoTaskMemFree の呼び出しによって解放される。集中メモリ アロケータを使うと、異なるプログラミング言語で作成されたオブジェクト間で、メモリの割り当て、受け渡し、および解放を安全に行うことができる。

IntToWstr

文字列関数

整数値をワイド文字列に変換する。

構文

void IntToWstr(
    int i,
    LPWSTR wstrDest
    );

パラメータ

i
変換する整数値。
wstrDest
変換された文字列が含まれるワイド文字列へのポインタ。

戻り値

戻り値はない。

lstrcmpiW

文字列関数

2 つのワイド文字列を比較する。大文字と/小文字は区別されない。

構文

int lstrcmpiW(
    LPCWSTR lpszString1,
    LPCWSTR lpszString2
    );

パラメータ

lpszString1
比較対象の NULL で終了する 1 番目のワイド文字列へのポインタ。
lpszString2
比較対象の NULL で終了する 2 番目のワイド文字列へのポインタ。

戻り値

関数が成功した場合、および lpszString1 によって示される文字列が lpszString2 によって示される文字列よりも小さい場合は、負の値を返す。lpszString1 によって示される文字列が lpszString2 によって示される文字列よりも大きい場合は、正の値を返す。2 つの文字列が等しい場合はゼロを返す。

注意

lstrcmpiW 関数は、2 つのワイド文字列の同じ位置にある文字どうし (たとえば 1番目の文字、2 番目の文字、...) を不一致が検出されるかまたは文字列の終わりに到達するまで照合して比較する。

この関数は、最初に検出した不一致文字の値の差を返す。たとえば lstrcmpiW は L"abcz" を L"abcdefg" より大きいと判断し、L'z' と L'd' の差を返す。

言語 (ロケール) は常に英語として扱われる。

lstrcmpW

文字列関数

2 つのワイド文字列を比較する。大文字と小文字が区別される。

構文

int lstrcmpW(
    LPCWSTR lpszString1,
    LPCWSTR lpszString2
    );

パラメータ

lpszString1
比較対象の NULL で終了する 1 番目のワイド文字列へのポインタ。
lpszString2
比較対象の NULL で終了する 2 番目のワイド文字列へのポインタ。

戻り値

関数が成功した場合、および lpszString1 によって示される文字列が lpszString2 によって示される文字列よりも小さい場合は、負の値を返す。lpszString1 によって示される文字列が lpszString2 によって示される文字列よりも大きい場合は、正の値を返す。2 つの文字列が等しい場合はゼロを返す。

注意

lstrcmpW 関数は、2 つのワイド文字列の同じ位置にある文字どうし (たとえば 1番目の文字、2 番目の文字、...) を不一致が検出されるかまたは文字列の終わりに到達するまで照合して比較する。

この関数は、最初に検出した不一致文字の値の差を返す。たとえば lstrcmpW は L"abcz" を L"abcdefg" より大きいと判断し、L'z' と L'd' の差を返す。

言語 (ロケール) は常に英語として扱われる。

lstrcpyW

文字列関数

ワイド文字列をバッファにコピーする。

構文

LPWSTR lstrcpyW(
    LPWSTR lpszString1,
    LPCWSTR lpszString2
    );

パラメータ

lpszString1
lpszString2 パラメータによって指し示される文字列の内容を受け取るバッファへのポインタ。バッファは、終端のワイド NULL 文字を含めた文字列を格納するのに十分な大きさを持たなければならない。
lpszString2
コピー対象の NULL で終了するワイド文字列へのポインタ。

戻り値

バッファへのポインタを返す。

lstrcpynW

文字列関数

指定されたワイド文字数までのワイド文字列をバッファにコピーする。

構文

LPWSTR lstrcpynW(
    LPWSTR lpszString1,
    LPCWSTR lpszString2,
    int iMaxLength
    );

パラメータ

lpszString1
lpszString2 によって指し示される文字列の内容を受け取るバッファへのポインタ。バッファは、終端のワイド NULL 文字を含めた文字列を格納するのに十分な大きさを持たなければならない。
lpszString2
コピー対象の NULL で終了するワイド文字列へのポインタ。
iMaxLength
終端 NULL 文字を含めた、コピーするワイド文字の最大数。

戻り値

バッファへのポインタを返す。

注意

iMaxLength がゼロ以外の値の場合、lstrcpynW は必ずコピー先の文字列に終端 NULL ワイド文字を挿入する。これにより、ソース文字列が切り捨てられることがある。

lstrlenW

文字列関数

指定されたワイド文字列の長さを取得する。

構文

int lstrlenW(
    LPCWSTR lpszString
    );

パラメータ

lpszString
NULL で終了するワイド文字列へのポインタ。

戻り値

関数が成功した場合、戻り値は文字列のワイド文字での長さを表す。

WriteBSTR

文字列関数

タスクが割り当てた BSTR 文字列の割り当てと埋め込みを行う。

構文

STDAPI WriteBSTR(
    BSTR *pstrDest,
    LPCWSTR szSrc
    );

パラメータ

pstrDest
割り当てられた BSTR の格納先へのポインタ。
szSrc
新しく割り当てられた BSTR 文字列にコピーされるワイド (Unicode™) 文字列へのポインタ。

戻り値

HRESULT 値を返す。

注意

メモリは、CoTaskMemAlloc を呼び出すことによって、インターフェイスにまたがったオブジェクト間の受け渡しのために割り当てられる。また、CoTaskMemFree の呼び出しによって解放される。集中メモリ アロケータを使うと、異なるプログラミング言語で作成されたオブジェクト間で、メモリの割り当て、受け渡し、および解放を安全に行うことができる。

WstrToInt

文字列関数

ワイド文字列を整数に変換する。

構文

int WstrToInt(
    LPCWSTR wstrSrc
    );

パラメータ

wstrSrc
ソースのワイド文字列へのポインタ。

戻り値

文字列の整数値を返す。


ビデオ関数とイメージ関数

宣言 : Wxutil.h

Microsoft® DirectShow® 基底クラスの Wxutil.h ヘッダー ファイルは、VIDEOINFOHEADER 構造体と BITMAPINFO 構造体との間で変換を行うのに役立つ関数およびマクロを提供する。

BIT_MASKS_MATCH | 2 つのビデオ イメージのマスクを比較する。
BITMASKS | 指定された VIDEOINFOHEADER 構造体のビットマスクの配列へのポインタを取得する。
COLORS | 指定された VIDEOINFOHEADER 構造体のカラー パレットを記述する RGBQUAD へのポインタを取得する。
ContainsPalette | ビデオ イメージにカラー パレットが含まれているかどうかをチェックする。
ConvertVideoInfoToVideoInfo2 | VIDEOINFO ストリーム フォーマットを VIDEOINFOHEADER2 フォーマットに変換する。
DIBSIZE | 指定されたビットマップのバイト サイズを計算する。
GetBitCount | ピクセルあたりのビット数を調べる。
GetBitmapFormatSize | VIDEOINFOHEADER 構造体とその関連データを作成するのに必要なサイズ (バイト単位) を調べる。
GetBitmapPalette | VIDEOINFOHEADER 構造体の最初のパレット エントリを取得する。
GetBitmapSize | イメージを保持するのに必要なサイズ (バイト単位) を調べる。
GetBitmapSubtype | 任意のビットマップ情報ヘッダー構造体の GUID サブタイプを調べる。
GetSubtypeName | 任意の GUID サブタイプの (デバッグ) 名前を調べる。
GetTrueColorType | 任意のビットマップ ヘッダーの GUID サブタイプを調べる。
HEADER | 指定されたビデオ イメージからイメージ データへのポインタを取得する。
MPEG1_SEQUENCE_INFO | 指定された MPEG-1 ビデオ イメージのシーケンス ヘッダーを取得する。
PALETTISED | ビデオ イメージのカラー パレットが 8 ビット以下であるかどうかをチェックする。
PALETTE_ENTRIES | ビデオ イメージのパレットの色数を返す。
RESET_MASKS | 指定されたビデオ イメージのビットマスクをクリアする。
RESET_HEADER | 指定されたビデオ イメージをクリアする。
RESET_PALETTE | 指定されたビデオ イメージのカラー パレットをクリアする。
SIZE_EGA_PALETTE | EGA (4 ビット) カラー パレットのサイズを計算する。
SIZE_MASKS | マスクのカラー パレットのサイズを計算する。
SIZE_MPEG1VIDEOINFO | 指定された MPEG-1 ビデオ イメージのサイズを計算する。
SIZE_PALETTE | 8 ビット カラー パレットのサイズを計算する。
SIZE_PREHEADER | ビデオ イメージのビットマップ情報のバイト オフセットを計算する。
SIZE_VIDEOHEADER | ビデオ イメージのサイズを計算する。
TRUECOLORINFO | 指定された VIDEOINFOHEADER 構造体のビットマスクおよびカラー パレットを記述する TRUECOLORINFO 構造体の配列へのポインタを取得する。

これらの関数は、ビデオ データ ストリームを記述するために DirectShow 全般で使用される VIDEOINFOHEADER 構造体の管理に役立つ。Microsoft® Win32® および既存のマルチメディアで使用される BITMAPINFO 構造体に似ているが、VIDEOINFOHEADER にはいくつかの新しいビデオ固有のフィールドが追加されている。

グローバル データ | 説明
bits555 | RGB 555 ビットマップのカラー ビットマスクの配列
bits565 | RGB 565 ビットマップのカラー ビットマスクの配列
bits888 | RGB 24 ビット ビットマップのカラー ビットマスクの配列

BIT_MASKS_MATCH

ビデオ関数とイメージ関数

指定されたビデオ イメージのビットマスクを取得する。

構文

BIT_MASKS_MATCH(
  pbmi1,
  pbmi2
  )

パラメータ

pbmi1
最初のビデオ イメージを含む Win32 VIDEOINFOHEADER 構造体へのポインタ。
pbmi2
2 番目のビデオ イメージを含む Win32 VIDEOINFOHEADER 構造体へのポインタ。

戻り値

両方のビデオ イメージのビットマスクが同じ場合はゼロ以外の値を返し、それ以外の場合はゼロを返す。

BITMASKS

ビデオ関数とイメージ関数

指定されたビデオ イメージのビットマスクを取得する。

構文

BITMASKS(
  pbmi
  )

パラメータ

pbmi
ビデオ イメージを含む Win32 VIDEOINFOHEADER 構造体へのポインタ。

戻り値

指定された VIDEOINFOHEADER 構造体のビットマスクの配列へのポインタを返す。

COLORS

ビデオ関数とイメージ関数

指定されたビデオ イメージのカラー パレットを取得する。

構文

COLORS(
  pbmi
  )

パラメータ

pbmi
ビデオ イメージを含む Win32 VIDEOINFOHEADER 構造体へのポインタ。

戻り値

指定された VIDEOINFOHEADER 構造体のカラー パレットを記述する RGBQUAD 構造体の配列へのポインタを返す。

ContainsPalette

ビデオ関数とイメージ関数

ビデオ イメージにカラー パレットが含まれているかどうかをチェックする。

構文

BOOL ContainsPalette(
  const VIDEOINFOHEADER *pVideoInfo
  );

パラメータ

pVideoInfo
VIDEOINFOHEADER 構造体へのポインタ。

戻り値

VIDEOINFOHEADER 構造体がカラー パレットを含んでいる場合は TRUE を返し、それ以外の場合は FALSE を返す。

ConvertVideoInfoToVideoInfo2

ビデオ関数とイメージ関数

VIDEOINFO ストリーム フォーマットを VIDEOINFOHEADER2 フォーマットに変換する。

構文

STDAPI ConvertVideoInfoToVideoInfo2(
    AM_MEDIA_TYPE *pmt
    );

パラメータ

pmt
[in/out] AM_MEDIA_TYPE 列挙型へのポインタ。

戻り値

インターフェイスの実装に依存する HRESULT 値を返す。HRESULT には、次のいずれかの標準定数、または一覧にないほかの値が含まれる。

E_OUTOFMEMORY | 処理でメモリ不足が発生した。
S_OK | 成功。

注意

成功した場合、この関数は AM_MEDIA_TYPE の formattype メンバを変更し、登録された GUID を VIDEOINFO 型から VIDEOINFOHEADER2 型に変更する。

DIBSIZE

ビデオ関数とイメージ関数

指定された (デバイスに依存しない) ビットマップのバイト サイズを計算する。

構文

DIBSIZE(
  bi
  )

パラメータ

bi
ソース ビットマップを指定する Win32 BITMAPINFOHEADER 構造体。

戻り値

bi パラメータのバイト サイズを返す。

GetBitCount

ビデオ関数とイメージ関数

ピクセルあたりのビット数を調べる。

構文

WORD GetBitCount(
  const GUID *pSubtype
  );

パラメータ

pSubtype
任意の ビデオ サブタイプの GUID へのポインタ。

戻り値

このサブタイプのピクセルあたりのビット数を返す。エラーが発生した場合は、USHRT_MAX を返す。

GetBitmapFormatSize

ビデオ関数とイメージ関数

VIDEOINFOHEADER 構造体とその関連データを作成するのに必要なサイズ (バイト単位) を調べる。

構文

LONG GetBitmapFormatSize(
  const BITMAPINFOHEADER *pHeader
  );

パラメータ

pHeader
Win32 BITMAPINFOHEADER 構造体へのポインタ。

戻り値

この BITMAPINFOHEADER によって記述された VIDEOINFOHEADER 構造体のバイト数を返す (プレフィックス情報、BITMAPINFOHEADER フィールド、およびその他の色情報を含む)。

GetBitmapPalette

ビデオ関数とイメージ関数

VIDEOINFOHEADER 構造体の最初のパレットを取得する。

構文

const RGBQUAD * GetBitmapPalette(
  const VIDEOINFOHEADER *pVideoInfo
  );

パラメータ

pVideoInfo
VIDEOINFOHEADER 構造体へのポインタ。

戻り値

パレットの最初のエントリへのポインタ。

GetBitmapSize

ビデオ関数とイメージ関数

イメージを保持するのに必要なバイト数を調べる。

構文

DWORD GetBitmapSize(
  const BITMAPINFOHEADER *pHeader
  );

パラメータ

pHeader
Win32 BITMAPINFOHEADER 構造体へのポインタ。

戻り値

イメージを保持するのに必要なバイト数を返す。

GetBitmapSubtype

ビデオ関数とイメージ関数

指定されたビットマップのサブタイプを調べる。

構文

const GUID GetBitmapSubtype(
  const BITMAPINFOHEADER *pHeader
  );

パラメータ

pHeader
Win32 BITMAPINFOHEADER 構造体へのポインタ。

戻り値

pHeader によって指定されたビットマップのビデオ サブタイプ GUID を返す。pHeader が NULL の場合は、GUID_NULL を返す。

GetSubtypeName

ビデオ関数とイメージ関数

任意の GUID サブタイプの名前を取得する。

構文

TCHAR * GetSubtypeName(
  const GUID *pSubtype
  );

パラメータ

pSubtype
任意のビデオ サブタイプの GUID へのポインタ。

戻り値

この GUID のデバッグ名を返す。名前が不明の場合は、UNKNOWN を返す。

GetTrueColorType

ビデオ関数とイメージ関数

指定された 16 ビット色ビットマップのサブタイプを調べる。

構文

const GUID GetTrueColorType(
  const BITMAPINFOHEADER *pHeader
  );

パラメータ

pHeader
Win32 BITMAPINFOHEADER 構造体へのポインタ。

戻り値

pHeader によって指定された 16 ビット色ビットマップのビデオ サブタイプ GUID を返す。pHeader が NULL の場合は、GUID_NULL を返す。

HEADER

ビデオ関数とイメージ関数

指定されたビデオ イメージからイメージ データへのポインタを取得する。

構文

HEADER(
  pVideoInfo
  )

パラメータ

pVideoInfo
ビデオ イメージを指定する VIDEOINFOHEADER 構造体へのポインタ。

戻り値

VIDEOINFOHEADER 構造体の bmiHeader データ メンバに含まれる Win32 BITMAPINFOHEADER 構造体へのポインタを返す。

MPEG1_SEQUENCE_INFO

ビデオ関数とイメージ関数

指定された MPEG-1 ビデオ イメージのシーケンス ヘッダーを取得する。

構文

MPEG1_SEQUENCE_INFO(
  pv
  )

パラメータ

pv
MPEG1VIDEOINFO 構造体へのポインタ。

戻り値

指定された MPEG1VIDEOINFO 構造体の bSequenceHeader データ メンバを返す。

PALETTISED

ビデオ関数とイメージ関数

ビデオ イメージのカラー パレットが 8 ビット以下であるかどうかをチェックする。

構文

PALETTISED(
  pbmi
  )

パラメータ

pbmi
ビデオ イメージを指定する Win32 BITMAPINFOHEADER 構造体へのポインタ。

戻り値

ビデオ イメージのパレットが 256 色以下の色を含んでいる場合はゼロ以外の値を返し、それ以外の場合はゼロを返す。

PALETTE_ENTRIES

ビデオ関数とイメージ関数

ビデオ イメージのパレットの色の数を取得する。

構文

PALETTE_ENTRIES(
  pbmi
  )

パラメータ

pbmi
ビデオ イメージを指定する Win32 BITMAPINFOHEADER 構造体へのポインタ。

戻り値

ビデオ イメージのパレットの色の数を返す。

RESET_MASKS

指定されたビデオ イメージのビットマスクをクリアする。

構文

RESET_MASKS(
  pbmi
  )

パラメータ

pbmi
ビデオ イメージを指定する Win32 BITMAPINFOHEADER 構造体へのポインタ。

戻り値

戻り値なし。

RESET_HEADER

ビデオ関数とイメージ関数

指定されたビデオ イメージをクリアする。

構文

RESET_HEADER(
  pbmi
  )

パラメータ

pbmi
ビデオ イメージを指定する Win32 BITMAPINFOHEADER 構造体へのポインタ。

戻り値

戻り値なし。

RESET_PALETTE

ビデオ関数とイメージ関数

指定されたビデオ イメージのカラー パレットをクリアする。

構文

RESET_PALETTE(
  pbmi
  )

パラメータ

pbmi
ビデオ イメージを指定する Win32 BITMAPINFOHEADER 構造体へのポインタ。

戻り値

戻り値なし。

SIZE_EGA_PALETTE

ビデオ関数とイメージ関数

4 ビット カラー パレットのサイズを計算する。

構文

SIZE_EGA_PALETTE

戻り値

16 色パレットのサイズをバイト単位で返す。

SIZE_MASKS

ビデオ関数とイメージ関数

ビットマスクのカラー パレットのサイズを計算する。

構文

SIZE_MASKS

戻り値

3 色を持つビットマップ マスクのカラー パレットのサイズをバイト単位で返す。

SIZE_MPEG1VIDEOINFO

ビデオ関数とイメージ関数

指定された MPEG-1 ビデオ イメージのサイズを計算する。

構文

SIZE_MPEG1VIDEOINFO(
  pv
  )

パラメータ

pv
ビデオ イメージを指定する MPEG1VIDEOINFO 構造体へのポインタ。

戻り値

指定された MPEG1VIDEOINFO 構造体のバイト サイズを返す。

SIZE_PALETTE

ビデオ関数とイメージ関数

8 ビット カラー パレットのサイズを計算する。

構文

SIZE_PALETTE

戻り値

256 色パレットのサイズを返す。

SIZE_PREHEADER

ビデオ関数とイメージ関数

ビデオ イメージのビットマップ情報のバイト オフセットを計算する。

構文

SIZE_PREHEADER

戻り値

VIDEOINFOHEADER 構造体の bmiHeader データ メンバのバイト オフセットを返す。

SIZE_VIDEOHEADER

ビデオ関数とイメージ関数

ビデオ イメージのサイズを計算する。

構文

SIZE_VIDEOHEADER

戻り値

VIDEOINFOHEADER 構造体のすべてのデータ メンバの合計サイズを返す。

TRUECOLORINFO

ビデオ関数とイメージ関数

指定されたビデオ イメージのカラー パレットおよびビットマスクを取得する。

構文

TRUECOLORINFO(
  pbmi
  )

パラメータ

pbmi
ビデオ イメージを含む Win32 VIDEOINFOHEADER 構造体へのポインタ。

戻り値

指定された VIDEOINFOHEADER 構造体のビットマスクおよびカラー パレットを記述する TRUECOLORINFO 構造体の配列へのポインタを取得する。


デバッグ ユーティリティ

このセクションには Microsoft® DirectShow® がデバッグ援助のために提供するマクロや関数の参照エントリがある。これらの関数を使うには、基底クラス ライブラリをビルドしなければならない。詳細については、「DirectShow でのデバッグ」を参照すること。

  • アサート マクロとブレークポイント マクロ
  • クリティカル セクション デバッグ関数
  • デバッグ出力関数
  • ポインタ有効マクロ
  • 待機デバッグ関数


アサート マクロとブレークポイント マクロ

Microsoft® DirectShow® 基底クラスはアサートを行ったり、ブレークポイントを発生させるいくつかのマクロを提供する。

宣言 : Wxdebug.h

マクロ | 説明
ASSERT | 条件式を評価し、その条件が FALSE なら診断メッセージを表示する。
DbgAssertAligned | ポインタが指定された範囲にあるかどうかをテストする。
DbgBreak | 指定した文字列、ソース ファイル名、ライン ナンバーでメッセージボックスを表示する。
EXECUTE_ASSERT | デバッグ ビルドとリテール ビルドの条件式を評価する。デバッグ ビルドでは、条件が FALSE なら診断メッセージを表示する。
KASSERT | 条件式を評価し、条件が FALSE ならブレークポイント例外を発生させる。
KDbgBreak | ボレークポイント例外を発生させ、指定した文字列をログする。

ASSERT

アサート マクロとブレークポイント マクロ

条件式を評価し、その条件が FALSE なら診断メッセージを表示する。リテール ビルドでは無視される。

構文

ASSERT(
    cond
);

パラメータ

cond
評価する条件式。

注意

デバッグ ビルドでは、条件式が FALSE なら、このマクロはメッセージ ボックスに条件のテキストと、ソース ファイルの名前と、ライン ナンバーを表示する。ユーザーはアサートを無視することも、デバッガに入ることも、アプリケーションを終了させることもできる。

例

ASSERT(rtStartTime <= rtEndTime);

DbgAssertAligned

アサート マクロとブレークポイント マクロ

ポインタが指定された範囲にあるかどうかをテストする。範囲外なら、このマクロは ASSERT マクロを動作させる。リテール ビルドでは無視される。

構文

DbgAssertAligned(
    ptr,
    alignment
);

パラメータ

ptr
ポインタ変数。
alignment
要求されたアラインメント。

DbgBreak

アサート マクロとブレークポイント マクロ

メッセージ ボックスに指定した文字列と、ソース ファイルの名前と、ライン ナンバーを表示する。ユーザーはアサートを無視することも、デバッガに入ることも、アプリケーションを終了させることもできる。リテール ビルドでは無視される。

構文

DbgBreak(
    strLiteral
);

パラメータ

strLiteral
テキスト文字列。

例

DbgBreak("Unrecoverable error occurred.");

EXECUTE_ASSERT

アサート マクロとブレークポイント マクロ

デバッグ ビルドとリテール ビルドの条件式を評価する。デバッグ ビルドでは、条件が FALSE なら診断メッセージを表示する。

構文

EXECUTE_ASSERT(
    cond
);

パラメータ

cond
評価する条件式。

注意

ASSERT マクロと違って、このマクロはリテール ビルドで条件式を評価する。デバッグ ビルドでは、条件式が FALSE なら、マクロは条件のテキストと、ソース ファイルの名前と、ライン ナンバーを表示する。ユーザーはアサートを無視することも、デバッガに入ることも、アプリケーションを終了させることもできる。

KASSERT

アサート マクロとブレークポイント マクロ

条件式を評価し、条件が FALSE ならブレークポイント例外を発生させる。条件のテキストと、ソース ファイルの名前と、ライン ナンバーが DbgLog マクロを使ってログされる。リテール ビルドでは無視される。

構文

KASSERT(
    cond
);

パラメータ

cond
評価する条件式。

注意

ASSERT and EXECUTE_ASSERT マクロと違って、このマクロはユーザーに知らせるメッセージ ボックスを表示させない。デバッグ ビルドでは、条件が FALSE なら、マクロは自動的にブレークポイント例外を発生させる。

KDbgBreak

アサート マクロとブレークポイント マクロ

ブレークポイント冷害を発生させ、DbgLog マクロを使って指定した文字列をログする。リテール ビルドでは無視される。

構文

KDbgBreak(
    strLiteral
);

パラメータ

strLiteral
テキスト文字列。

注意

DbgBreak マクロと違って、このマクロはユーザーに知らせるメッセージ ボックスを表示しない。デバッグ ビルドでは、自動的にブレークポイント例外を発生させる。


クリティカル セクション デバッグ関数

これらの関数はコード内のクリティカル セクションのデバッグの手助けとなり、デッドロックの原因の発見が容易になる。これらの関数はCCritSec ヘルパー クラスを使用している

宣言 : Wxutil.h

CritCheckIn | 現在のスレッドが特定のクリティカル セクションを所有していることをチェックする。
CritCheckOut | 現在のスレッドが特定のクリティカル セクションを所有していることをチェックする。
DbgLockTrace | 特定のクリティカル セクションのデバッグ ロギングを有効または無効にする。

CritCheckIn

クリティカル セクション デバッグ関数

現在のスレッドが指定したクリティカル セクションの所有者なら TRUE を返す。

構文

BOOL WINAPI CritCheckIn(

  CCritSec *pcCrit

  );

パラメータ

pcCrit
CCritSec クリティカル セクションへのポインタ。

戻り値

デバッグ ビルドのとき、現在のスレッドがこのクリティカル セクションの所有者である場合は TRUE を返し、それ以外の場合は FALSE を返す。リテール ビルドのとき、常に TRUE を返す。

注意

この関数は ASSERT マクロと同時に使うと、スレッドが与えられたロックを所有しているかどうかをテストするのに非常に便利です。

次のコード例はこの関数の使い方を示す :

{
    CCritSec MyLock;  // クリティカル セクションはまだロックしていない

    ASSERT(CritCheckIn(&MyLock)); // この assert はメッセージを出す

    // クリティカル セクションをロックする
    CAutoLock cObjectLock(&MyLock);

    ASSERT(CritCheckIn(&MyLock)); // この assert はメッセージを出さない

} // ロックのデバッグはここまで

CritCheckOut

クリティカル セクション デバッグ関数

現在のスレッドが指定したクリティカル セクションの所有者のとき FALSE を返す

構文

BOOL WINAPI CritCheckOut(

  CCritSec *pcCrit

  );

パラメータ

pcCrit
CCritSec クリティカル セクションへのポインタ。

戻り値

デバッグ ビルドのとき、現在のスレッドがこのクリティカル セクションの所有者の場合は FALSE を返し、それ以外の場合は TRUE を返す。リテール ビルドのとき、常に TRUE を返す。

注意

この関数は CritCheckIn 関数の逆である。CritCheckIn が TRUE のとき、CritCheckOut は FALSE を返し、反対なら TRUE を返す。

DbgLockTrace

クリティカル セクション デバッグ関数

特定のクリティカル セクションのデバッグ ロギングを有効または無効にする。

構文

void WINAPI DbgLockTrace(

  CCritSec *pcCrit,

  BOOL fTrace

  );

パラメータ

pcCrit
CCritSec クリティカル セクションへのポインタ。
fTrace
ロギングを有効にするかどうかを指定する値。ロギングを有効にするには TRUE を使用し、ロギングを無効にするには FALSE を使用する。

注意

この関数を使って指定したクリティカル セクションをトレースする。デフォルトではクリティカル セクションでデバッグ ロギングは無効です、なぜならクリティカル セクションの数が非常に多いからです。

クリティカル セクションをトレースするには、次のステップを行う:

  1. DirectShow ヘッダーをインクルードする前に DEBUG を定義する。
  2. DbgSetModuleLevel を LOG_LOCKING フラグで呼び出してクリティカル セクションのデバッグ ロギングを有効にする。
  3. トレースしたいクリティカル セクションで DbgLockTrace を呼び出す。

次のコード例はクリティカル セクションのトレース方法を示す :

DbgInitialise(g_hInst);
DbgSetModuleLevel(LOG_LOCKING, 3);

{
    CCritSec MyLock;
    DbgLockTrace(&MyLock, TRUE);

    CAutoLock cObjectLock(&MyLock);

    // コードの保護された部分
    DbgOutString("This code is inside a critical section.\n");

} // ロックのデバッグはここまで

DbgTerminate();

デバッグ出力は以下の様に見ることができる :

Example.exe(tid 360)     2012 : Thread 864 now owns lock 12fc2c
This code is inside a critical section.
Example.exe(tid 360)     4887 : Thread 864 releasing lock 12fc2c

DirectShow ヘッダーをインクルードするとき、DEBUG が定義されていないと、DbgLockTrace 関数は有効にならない。


デバッグ出力関数

Microsoft® DirectShow® 基底クラスはデバッグ情報表示用のいくつかのマクロを提供する。

宣言 : Wxdebug.h

DirectShow のデバッグ環境は特定のタイプのデバッグ情報を、他の者を無視して、ファインチューンすることができる。この機能で、コード内の特定の範囲に問題をピンポイントさせることができる。DirectShow は以下の表に示されるいくつかのメッセージタイプを定義する。

LOG_ERROR | エラー通知。
LOG_LOCKING | クリティカル セクションのロックとアンロック。
LOG_MEMORY | メモリ割り当てと、オブジェクトの作成および破棄。
LOG_TIMING | タイミングとパフォーマンスの測定。
LOG_TRACE | 一般的な呼び出しトレース。

すべてのモジュールは各メッセージタイプに対し自身のデバッグレベルを設定することができる。(モジュール は DLL もしくは実行モジュールであり、Microsoft® Win32® LoadLibrary 関数を使ってロードされる。) モジュールの与えられたメッセージタイプに対するロギング レベルはレジストリ内の次のキーで見ることができる :

\HKEY_LOCAL_MACHINE\SOFTWARE\Debug\<Module Name>\<Message Type>

<Message Type> はメッセージ タイプ から頭の "LOG_" を取ったものである。たとえば、LOCKING は LOG_LOCKING メッセージ。

モジュールがロードされると、デバッグ ライブラリはモジュールのロギング レベルをレジストリから読み込む。レジストリ キーがないと、デバッグ ライブラリはそれを作成する。メッセージタイプのグローバル ロギング レベルは次のキーで指定される :

\HKEY_LOCAL_MACHINE\SOFTWARE\Debug\GLOBAL\<Message Type>

デバッグ ライブラリは大きい方のレベルを使用する。モジュールは DbgSetModuleLevel 関数を使って、自身のレベルをランタイム時に設定することもできる。デバッグ出力にメッセージを送るには、DbgLog マクロを呼び出すこと。次の例はタイプ LOG_TRACE のレベル 3 メッセージを作成している :

DbgLog((LOG_TRACE, 3, "This is a debug message."));

デバッグ ビルドでは、現在のLOG_TRACE メッセージのロギング レベルが 3 あるいはそれ以上なら、メッセージはデバッグ出力を送る。それ以外なら無視される。デバッグ ビルドはストリームクラス ヘッダー ファイル Streams.h に含まれているプリプロセッサ シンボル DEBUG を定義しなければならない。

デバッグ出力位置は別のレジストリキーによって定義されている :

\HKEY_LOCAL_MACHINE\SOFTWARE\Debug\<Module Name>\LogToFile

この値が Console なら、出力はコンソール ウィンドウになる。この値が Deb、Debug、Debugger あるいは空白文字列なら、出力はデバッガ ウィンドウになる。それ以外なら、出力はレジストリ キーで指定されたファイルに書き込まれる。

実行モジュールが DirectShow デバッグ ライブラリを使う前に、DbgInitialise 関数を呼び出さなければならない。最後に、DbgTerminate 関数呼び出さなければならない。これらの関数を呼び出すのに DLL は必要ない。

関数 | 説明
DbgCheckModuleLevel | 与えられたメッセージ タイプとレベルでロギングが可能かどうかをチェックする。
DbgDumpObjectRegister | アクティブなオブジェクトについての情報を表示する。
DbgInitialise | デバッグ ライブラリを初期化する。
DbgLog | 指定したタイプとレベルでロギング可能なら、デバッグ出力位置に文字列を送る。
DbgOutString | デバッグ出力位置に文字列を送る。
DbgSetModuleLevel | 1 つ以上のメッセージ タイプのロギング レベルを設定する。
DbgTerminate | デバッグ ライブラリをクリーン アップする。
DisplayType | メディア タイプについての情報をデバッグ出力位置に送る。
DumpGraph | フィルタ グラフについての情報をデバッグ出力位置に送る。
NAME | デバッグ専用文字列を生成する。
NOTE | デバッグ出力位置に文字列を送る。
REMIND | コンパイル時に注意を生成する。

DbgCheckModuleLevel

デバッグ出力関数

与えられたメッセージ タイプとレベルでロギングが可能かどうかをチェックする。リテール ビルドでは無視される。

構文

BOOL DbgCheckModuleLevel(
    DWORD Types,
    DWORD Level
);

パラメータ

Types
1 つ以上のメッセージ タイプのビットの組み合わせ。
Level
ロギング レベル

戻り値

もし指定したメッセージタイプに対するロギングが指定したレベルあるいはそれ以上にセットされていると、TRUE を返す。それ以外なら、FALSE を返す。

DbgDumpObjectRegister

デバッグ出力関数

アクティブなオブジェクトについての情報を表示する。リテール ビルドでは無視される。

構文

void DbgDumpObjectRegister(void);

注意

デバッグ ビルドでは、デバッグ ライブラリはアクティブなオブジェクトのリストを保持する。CBaseObjectから派生したすべてのオブジェクトを含むリストは、現在のモジュールによって作成され、削除されない。CBaseObject コンストラクタとデストラクタ メソッドがこのリストをアップデートする。

この関数はいくつかの LOG_MEMORY メッセージを生成する。ロギング レベル 1 では、この関数はオブジェクトの全数だけを表示する。ロギング レベル 2 以上では、オブジェクトのリストを表示する。

DbgInitialise

デバッグ出力関数

デバッグ ライブラリを初期化する。リテール ビルドでは無視される。

構文

void DbgInitialise(
    HINSTANCE hInst
);

パラメータ

hInst
モジュール インスタンスへのハンドル。

注意

実行モジュールでは、DirectShow デバッグ環境を使う前にこのメソッドを呼び出すこと。実行モジュールが終了する前に、DbgTerminate 関数を呼び出し、デバッグ ライブラリをクリーン アップすること。

基底クラス ライブラリ (Strmbase.lib) にリンクしている DLL では、この関数を呼び出す必要はない。この関数は DLL がロードされるとき、自動的に呼び出される。

DbgLog

デバッグ出力関数

指定したタイプとレベルでロギング可能なら、デバッグ出力位置に文字列を送る。リテール ビルドでは無視される。

構文

void DbgLog((
    DWORD Types,
    DWORD Level,
    const TCHAR *pFormat,
    ...
));

パラメータ

Types
1 つ以上のメッセージ タイプのビットの組み合わせ。
Level
このメッセージのロギング レベル
pFormat
printfスタイルのフォーマット文字列。
...
フォーマット文字列の追加引数。

注意

任意のメッセージタイプのデバッグ ロギングが指定したレベル以上に設定されていれば、デバッグ出力位置に文字列を送る

例

DbgLog((LOG_TRACE, 3, TEXT("Connected input pin %d"), nPinNumber));

カッコを追加するときはマクロ パラメータで包まなければならないことに注意。

DbgOutString

デバッグ出力関数

デバッグ出力位置に文字列を送る。リテール ビルドでは無視される。

構文

void DbgOutString(
    LPCTSTR psz
);

パラメータ

psz
出力する文字列。

注意

デバッグ ビルドでは、現在のデバッグ出力レベルと関係なく、この関数は必ず文字列を出力する。出力に関してより細かなコントロールをするには、DbgLog マクロを使うこと。

例

DbgOutString("Creating the filter graph...\n");

DbgSetModuleLevel

デバッグ出力関数

1 つ以上のメッセージ タイプのロギング レベルを設定する。リテール ビルドでは無視される。

構文

void DbgSetModuleLevel(
    DWORD Types,
    DWORD Level
);

パラメータ

Types
1 つ以上のメッセージ タイプのビットの組み合わせ。
Level
指定したメッセージタイプのロギング レベル

DbgTerminate

デバッグ出力関数

デバッグ ライブラリをクリーン アップする。リテール ビルドでは無視される。

構文

void DbgTerminate(void);

注意

DbgInitialise 関数を呼び出したなら、この関数を呼び出すこと。

DisplayType

デバッグ出力関数

メディア タイプについての情報をデバッグ出力位置に送る。リテール ビルドでは無視される。

構文

void DisplayType(
    LPSTR label,
    const AM_MEDIA_TYPE *pmtIn
);

パラメータ

label
メディア タイプ情報を表示するメッセージが入る文字列。
pmtIn
メディア タイプが入る AM_MEDIA_TYPE 構造体へのポインタ。

注意

この関数はいくつかの LOG_TRACE メッセージを生成する。ロギング レベル 2 以上では、この関数はメジャー タイプ、マイナー タイプ、フォーマット タイプ、フォーマット ブロックからのデータを表示する。ロギング レベル 5 以上では、この関数はビデオ タイプの転送元矩形やターゲット矩形のような追加情報を表示する。

DumpGraph

デバッグ出力関数

フィルタ グラフについての情報をデバッグ出力位置に送る。リテール ビルドでは無視される。

構文

void DumpGraph(
    IFilterGraph *pGraph,
    DWORD dwLevel
)

パラメータ

pGraph
フィルタ グラフ マネージャの IFilterGraph インターフェイスへのポインタ。
dwLevel
ロギング レベル。関数は指定したロギング レベルで LOG_TRACE メッセージを生成する。

NAME

デバッグ出力関数

デバッグ専用文字列を生成する。

構文

NAME(
    strLiteral
);

パラメータ

strLiteral
テキスト 文字列。

注意

デバッグ ビルドでは、このマクロは TEXT マクロと同じである。リテール ビルドでは、(TCHAR*) NULL を解決する。このマクロは CBaseObject クラスから派生したオブジェクトの名前を宣言するとき便利である。

例

pObject = new CBaseObject(NAME("My Object"));

NOTE, NOTE1, NOTE2, NOTE3, NOTE4, NOTE5

デバッグ出力関数

デバッグ出力位置に文字列を送る。リテール ビルドでは無視される。

構文

NOTE(
    pFormat
);

NOTEn(
    pFormat,
    arg1 ... arg5
);

パラメータ

pFormat
printfスタイルのフォーマット文字列。
arg1 – arg5
フォーマット文字列の追加引数。引数の数はマクロの名前と一致しなければならない。たとえば、NOTE1 は 1 つの引数を持ち、NOTE5 は 5 つの引数を持つ。

注意

これらのマクロは DbgLog マクロの変形である。それらはレベル 5 LOG_TRACE メッセージを生成する。

例

NOTE("Warning, failed to created graph.");

NOTE2("Width: %d, Height: %d", width, height);

REMIND

デバッグ出力関数

コンパイル時に注意を生成する。このマクロはパラメータ文字列、ソース ファイル名、ライン ナンバーを含む文字列を生成する。

構文

REMIND(
    strLiteral
);

パラメータ

strLiteral
テキスト文字列。

例

このマクロはコンパイル時のワーニングを生成する際に便利である :

#pragma message (REMIND("TO DO: Add support for IDispatch."))


ポインタ有効マクロ

Microsoft® DirectShow® はポインタの有効性を確認するいくつかのマクロを提供する。

宣言 : Wxdebug.h

マクロ | 説明
CheckPointer | ポインタが NULL かどうかチェックする。
ValidateReadPtr | 呼び出しプロセスがメモリ ブロックへの読み込みアクセスを持っている事を検証する。
ValidateReadWritePtr | 呼び出しプロセスがメモリ ブロックへの読み込みと書き込みのアクセスを持っている事を検証する。
ValidateStringPtr | 呼び出しプロセスが文字列への読み込みアクセスを持っている事を検証する。
ValidateStringPtrA | 呼び出しプロセスが ANSI 文字列への読み込みアクセスを持っている事を検証する。
ValidateStringPtrW | 呼び出しプロセスがワイド キャラクタ文字列への読み込みアクセスを持っている事を検証する。
ValidateWritePtr | 呼び出しプロセスがメモリ ブロックへの書き込みアクセスを持っている事を検証する。

CheckPointer

ポインタ有効マクロ

ポインタが NULL かどうかチェックする。ポインタが NULL なら、マクロがあるその関数あるいはメソッドは指定した値を返す。

構文

CheckPointer(
    p,
    ret
);

パラメータ

p
チェックするポインタ。
ret
p が NULL のとき、この関数あるいはメソッドが返す値。

例

HRESULT MyFunction(VOID *pSomeParameter)
{
    CheckPointer(pSomeParameter, E_INVALIDARG)

    // 関数の残り (省略)。
}

ValidateReadPtr

ポインタ有効マクロ

呼び出しプロセスがメモリ ブロックへの読み込みアクセスを持っている事を検証する。持っていない場合、このマクロは DbgBreak マクロを呼び出す。

構文

ValidateReadPtr(
    const void *p,
    UINT cb
);

パラメータ

p
メモリ ブロックへのポインタ。
cb
メモリ ブロックのサイズ、バイト単位。

注意

DirectShow 基底クラス ヘッダー ファイルがインクルードされたとき、DEBUG あるいは VFWROBUST が定義されるまで、このマクロは無視される。このマクロはパフォーマンスに大きな影響を与える。

ValidateReadWritePtr

ポインタ有効マクロ

呼び出しプロセスがメモリ ブロックへの読み込みと書き込みのアクセスを持っている事を検証する。持っていない場合、このマクロは DbgBreak を呼び出す。

構文

ValidateReadWritePtr(
    const void *p,
    UINT cb
);

パラメータ

p
メモリ ブロックへのポインタ。
cb
メモリ ブロックのサイズ、バイト単位。

注意

DirectShow 基底クラス ヘッダー ファイルがインクルードされたとき、DEBUG あるいは VFWROBUST が定義されるまで、このマクロは無視される。このマクロはパフォーマンスに大きな影響を与える。

ValidateStringPtr

ポインタ有効マクロ

呼び出しプロセスが文字列への読み込みアクセスを持っている事を検証する。 持っていない場合、このマクロは DbgBreak を呼び出す。

構文

ValidateStringPtr(
    LPCTSTR p
);

パラメータ

p
NULL で終わる TCHAR 文字列へのポインタ。

注意

DirectShow 基底クラス ヘッダー ファイルがインクルードされたとき、DEBUG あるいは VFWROBUST が定義されるまで、このマクロは無視される。このマクロはパフォーマンスに大きな影響を与える。

ValidateStringPtrA

ポインタ有効マクロ

呼び出しプロセスが ANSI 文字列への読み込みアクセスを持っている事を検証する。持っていない場合、このマクロは DbgBreak を呼び出す。

構文

ValidateStringPtrA(
    LPCSTR p
);

パラメータ

p
NULL で終わる ANSI 文字列へのポインタ。

注意

DirectShow 基底クラス ヘッダー ファイルがインクルードされたとき、DEBUG あるいは VFWROBUST が定義されるまで、このマクロは無視される

ValidateStringPtrW

ポインタ有効マクロ

呼び出しプロセスがワイド キャラクタ文字列への読み込みアクセスを持っている事を検証する。持っていない場合、このマクロは DbgBreak を呼び出す。

構文

ValidateStringPtrW(
    LPCWSTR p
);

パラメータ

p
NULL 出終わるワイド キャラクタ文字列へのポインタ。

注意

DirectShow 基底クラス ヘッダー ファイルがインクルードされたとき、DEBUG あるいは VFWROBUST が定義されるまで、このマクロは無視される。このマクロはパフォーマンスに大きな影響を与える。

ValidateWritePtr

ポインタ有効マクロ

呼び出しプロセスがメモリ ブロックへの書き込みアクセスを持っている事を検証する。 持っていない場合、このマクロは DbgBreak を呼び出す。

構文

ValidateWritePtr(
    const void *p,
    UINT cb
);

パラメータ

p
メモリ ブロックへのポインタ。
cb
メモリ ブロックのサイズ、バイト単位。

注意

DirectShow 基底クラス ヘッダー ファイルがインクルードされたとき、DEBUG あるいは VFWROBUST が定義されるまで、このマクロは無視される。このマクロはパフォーマンスに大きな影響を与える。


待機デバッグ関数

Microsoft® DirectShow® はいくつかの無限に待機するデバッグ関数を提供する。

宣言 : Wxdebug.h

リテール ビルドでは、DbgWaitForMultipleObjects 関数と DbgWaitForSingleObject 関数はタイムアウト間隔が無限で、Microsoft® Win32® のカウンター パート WaitForMultipleObjects と WaitForSingleObject と同じように動作する。

デバッグ ビルドでは、これらの関数はグローバルなタイムアウト値を使う。タイムアウトが時間切れになると、この関数はアサートを起動する。次のレジストリ キーがミリ秒でタイムアウト値を指定する :

\HKEY_LOCAL_MACHINE\SOFTWARE\Debug\<Module Name>\TIMEOUT

このキーがない場合、タイムアウト値はデフォルトの INFINITE となる。DbgSetWaitTimeout 関数を使ってレジストリの値をオーバーライドすることができる。

関数 | 説明
DbgSetWaitTimeout | デバッグ タイムアウト値を設定する。
DbgWaitForMultipleObjects | 指定された任意の(あるいはすべての)オブジェクトが通知済になるまで待つ。
DbgWaitForSingleObject | あるオブジェクトが通知済になるまで待つ。

DbgSetWaitTimeout

待機デバッグ関数

デバッグ タイムアウト値を設定する。 リテール ビルドでは無視される。

構文

void DbgSetWaitTimeout(
    DWORD dwTimeout
);

パラメータ

dwTimeout
ミリ秒単位のタイムアウト値、あるいは無限に待つ INFINITE 。

注意

デバッグ ビルドでは、DbgWaitForMultipleObjects 関数と DbgWaitForSingleObject 関数はこの値をタイムアウト間隔として使用する。

DbgWaitForMultipleObjects

待機デバッグ関数

指定された任意の(あるいはすべての)オブジェクトが通知済になるまで待つ。

デバッグ ビルドでは、オブジェクトが通知済になる前にタイムアウト間隔が時間切れになると、この関数はアサートを起動する。タイムアウト間隔を設定するには、DbgSetWaitTimeout 関数を呼び出すこと。

リテール ビルドでは、この関数は INFINITE のタイムアウト間隔で WaitForMultipleObjects 関数と同じである。

構文

DWORD DbgWaitForMultipleObjects(
    DWORD nCount,
    CONST HANDLE *lpHandles,
    BOOL bWaitAll
);

パラメータ

nCount
オブジェクトの数。
lpHandles
オブジェクトのハンドルの配列、nCount サイズ
bWaitAll
すべてのオブジェクトを待つかどうかを指定するブール値。TRUE なら、この関数はすべてのオブジェクトが通知済になるまで待つ。それ以外なら、少なくとも 1 つのオブジェクト通知済になるまで待つ。

DbgWaitForSingleObject

待機デバッグ関数

あるオブジェクトが通知済になるまで待つ。

デバッグ ビルドでは、オブジェクトが通知済になる前にタイムアウト間隔が時間切れになると、この関数はアサートを起動する。タイムアウト間隔を設定するには、DbgSetWaitTimeout 関数を呼び出すこと。

リテール ビルドでは、この関数は INFINITE のタイムアウト間隔で WaitForMSingleObject 関数と同じである。

構文

DWORD DbgWaitForSingleObject(
    HANDLE h
);

パラメータ

h
オブジェクトのハンドル。


DirectShow サンプル

Microsoft® DirectShow® SDK サンプルは、機能に応じて以下のカテゴリに分けられる。

  • 基底クラス
  • BDA サンプル アプリケーション
  • サンプル キャプチャ アプリケーション
  • DMO サンプル
  • サンプル DVD アプリケーション
  • サンプル DirectShow フィルタ
  • DirectShow のその他のサンプル
  • サンプル プレーヤー アプリケーション
  • サンプル ビデオ編集アプリケーション

基底クラスは、フィルタの作成やメディア タイプの操作など DirectShow の作業を実行するのに便利な C++ クラスのセットである。

注

多くの DirectShow サンプルはこの基底クラス ライブラリをリンクし、フィルタの作成、メディア タイプの操作、それ以外の DirectShow タスクを実行する。

サンプルを作成する最も簡単な方法は、DirectShow サンプル ルート ディレクトリにあるワークスペース ファイル DShow.dsw を使用する方法である。このワークスペースには、すべてのサンプル プロジェクト ファイルに対する参照が含まれる。

  • すべてのプロジェクトを作成するには、[ビルド] メニューの [バッチ ビルド] を選択する。
  • 特定のサンプル (依存を含む) を作成するには、[FileView] ペインのプロジェクト名を右クリックし、表示されたポップアップ メニューで [ビルド] をクリックする。

また、各サンプルに対するプロジェクト ファイルも含まれており、サンプルの作成、変更、デバッグに使用できる。DShow.dsw ワークスペースを使用せずに、この方法でサンプルを作成する場合は、必ず、最初に基底クラス ライブラリを作成すること。

参照

ビルド環境の設定


基底クラス

説明

Microsoft® DirectShow® の基底クラスは C++ クラスのセットであり、DirectShow フィルタを実装するために使用できるユーティリティ関数である。基底クラスの詳細については、「DirectShow 基底クラス」を参照すること。

パス

ソース : (SDK ルート)\Samples\Multimedia\DirectShow\BaseClasses


BDA サンプル アプリケーション

説明

新しい Microsoft® Broadcast Driver Architecture (BDA) をサポートするデジタル TV チューナー カードをベースとしたフィルタ グラフを構築する方法をデモンストレーションする。このサンプルは新しい Microsoft® Tuning Model をベースとしたチューニングの方法をも示す。このサンプルは デジタル TV アプリケーションを書く の中でより詳細に説明されている。

パス

ソース: (SDK root)\Samples\Multimedia\DirectShow\BDA\BDASample

実行可能ファイル : (SDK root)\Samples\Multimedia\DirectShow\Bin\Bdasample.exe

注: このサンプルをビルドするにはシステムにある strmbasd.lib か strmbase.lib がなければならない。このライブラリは DirectShow 基底クラスをビルドすると作成される。詳細については、「DirectShow 基底クラスの使い方」を参照すること。


サンプル キャプチャ アプリケーション

Microsoft® DirectShow® SDK には、以下のサンプル キャプチャ アプリケーションが含まれている。

C++ アプリケーション

  • AmCap サンプル
  • DVApp サンプル
  • PlayCap サンプル


AmCap サンプル

説明

ビデオ キャプチャ アプリケーション

パス

ソース : (SDK ルート)\Samples\Multimedia\DirectShow\Capture\AMCap

実行可能ファイル : (SDK ルート)\Samples\Multimedia\DirectShow\Bin\AMCap.exe

ユーザー ガイド

このサンプル アプリケーションは、オーディオおよびビデオ キャプチャに関連する以下のタスクをデモンストレーションする。

  • ファイルへのキャプチャ
  • ライブ プレビュー
  • キャプチャ ファイルの割り当て
  • デバイス プロパティ ページの表示
  • デバイスの列挙
  • ストリーム コントロール

参照

ビデオ キャプチャ


DVApp サンプル

説明

デジタル ビデオ (DV) キャプチャ アプリケーション。

このサンプルはDV カムコーダを制御する様々なタイプのフィルタ グラフを構築する方法をデモンストレーションする。DV カムコーダを使ったキャプチャ、プレビュー、転送、デバイス制御の方法をも示す。

パス

ソース: (SDK ルート)\Samples\Multimedia\DirectShow\Capture\DVApp

実行可能ファイル : (SDK ルート)\Samples\Multimedia\DirectShow\Bin\DVApp.exe

ユーザー ガイド

DVApp アプリケーションは以下のモードをサポートする :

  • Preview: カムコーダからビデオ ウィンドウに DV をレンダリングする。
  • DV to type-1 file: カムコーダからType-1 DV ファイルに DV データをキャプチャする。
  • Type-1 file to DV: Type-1 DV ファイルからカムコーダにデータを転送する。
  • DV to type-2 file: カムコーダからType-2 DV ファイルにDV データをキャプチャする。
  • Type-2 file to DV: Type-2 DV ファイルからカムコーダにデータを転送する。

キャプチャ モードと転送モードではプレビューも行われる。これらの各モードはプレビューを不可にする No Preview オプションも同様に持っている。 プレビューなしでのキャプチャリングはより効率的で、ドロップ フレームを減らすことができる。Type-1 ファイルと Type-2 ファイルについての情報は、「DirectShow でのデジタル ビデオ」を参照すること。

アプリケーションはプレビュー モードで開始する。別のモードを選択するには、Graph Mode メニューから選択すること。各モードに対して、DVApp はそのモードの機能をサポートするフィルタ グラフを構築する。GraphEdit (.grf) ファイルとしてそのグラフを保存するには、File メニューから Save Graph to File を選ぶこと。GraphEdit でファイルを開く前に、DVApp を終了させること。

ファイルにキャプチャするには :

  1. Graph Mode メニューから、(type 1 か type 2、with preview か without preview で) DV to File モードを選択する。
  2. File メニューから、Set Output File を選び、ファイル名を入力する。
  3. Record をクリックする。
  4. カムコーダが VTR なら、Play をクリックする。
  5. キャプチャを停止するには、Stop をクリックする。

ファイルからカムコーダに転送するには :

  1. Graph Mode メニューから、(type 1 か type 2、with preview か without preview で) File to DV モードを選択する。
  2. File メニューから、Set Input File をクリックし DV ファイルを選択する。ファイルは選択されたモード (Type-1 か Type-2) と一致しなければならない。
  3. Play をクリック。
  4. データをテープに録画するには、Record をクリックする。
  5. 転送を停止するには、Stop をクリックする。

カムコーダが VTR モードなら、ユーザーはアプリケーションの VCR-style ボタンを通して転送メカニズムを制御できる。テープをシークするには、ターゲット タイムコードを入力してシークボタンを押す。

アプリケーションがキャプチャするデータ量を制限するには、File メニューから Capture Size を選択する。

テープ フォーマット (NTSC か PAL) をチェックするには、Options メニューから Check Tape を選択する。

プレビュー ウィンドウのサイズを変更するには、Options メニューから Change Decode Size を選択する。

プログラミングの注意

このアプリケーションの主目的は様々な DV キャプチャと DV 転送 グラフの構築方法を示すことである。アプリケーションは ICaptureGraphBuilder2 インターフェイスを使ってプレビュー グラフと Type-1 キャプチャ グラフを構築することができる。他のタイプの DV グラフは一度に１つのフィルタしか構築できない。DVApp サンプルはプレビュー グラフの構築に ICaptureGraphBuilder2 だけを使っている。

次のダイアグラムは Type-1 ファイルをキャプチャするフィルタ グラフを示す :

Type-1 DV ファイル キャプチャ グラフ

インターリーブされたオーディオ ビデオ データは MSDV から スマート ティー フィルタに送られる。スマート ティー フィルタのキャプチャ ピンからのデータはファイルに書き込まれる、一方プレビュー ピンからのデータはビデオ レンダラとオーディオ レンダラに送られる。

次のダイアグラムは Type-2 ファイルからカムコーダへの転送をするフィルタ グラフを示す :

Type-2 DV ファイル転送グラフ

AVI スプリッタ フィルタは AVI ファイルをパースし、DV Muxer フィルタは 2 つのストリームをマルチプレックスし、インターリーブ オーディオ ビデオ ストリームを作成する。インフィニット ピン ティー フィルタはそのストリームを 2 つの同じストリームに分割する。1 つのストリームは MSDV に行き、一方もう 1 つは DV スプリッタ フィルタを通してプレビューに行く。これと等価な別のグラフ構成も可能である。

デバイスの着脱

アプリケーションは 2 つの異なるテクニックを使ってデバイスの着脱を処理する。デバイスが装着されたとき、アプリケーションのメッセージ ループは WM_DEVICECHANGE メッセージに対応する。デバイスが外されたとき、アプリケーションはフィルタ グラフマネージャからの EC_DEVICE_LOST イベントを処理する。どちらのアプローチも動作する、しかし EC_DEVICE_LOST イベントはフィルタ グラフにデバイスの存在することが必要である。

アプリケーションは 1 度に 1 つのデバイスだけを処理する。現在のデバイスが外されると、アプリケーションはシステム上の別の DV デバイスを探す。

いくつかの DV カムコーダでは、カメラ モードと VTR モード間でスイッチしたときデバイス ロスト メッセージを発生するため、ユーザーがデバイスをシャットオフしなければならない。アプリケーションは適切なメニューコマンドを利用可、利用不可にすることでこれに対応する。しかし、ユーザーがモード間をすばやく切り替えると、カムコーダはデバイス ロスト メッセージを生成しない場合がある。Options メニューから Refresh Mode を選ぶことによってメニューをアップデートさせることができる。シャットオプなしでモードを切り替えることができるが、VTR モードにスイッチされたときだけデバイス ロスト メッセージを送る DV カムコーダもある。

注 Microsoft® Windows® 95 and Microsoft® Windows NT® 4.0 以前ではデバイス装着に用いられるデバイスタイプをサポートしない。これらのプラットフォームに対して、アプリケーションをコンパイルするために、WINVER が 0x500 より小さい場合データタイプは条件的にインクルードされる。しかし、アプリケーションはこれらのプラットフォームでデバイス検知をサポートしない。

デバイス制御

アプリケーションの Play と Record ボタンは現在のモードに依存する :

  • Preview: フィルタ グラフは自動的に実行する。Play ボタンは転送を開始する。
  • Capture to file: Record ボタンはグラフを実行し、Play ボタンは転送を開始する。
  • Transmit to device: Play ボタンはグラフを実行し、Record ボタンは転送を開始する。

サンプル アプリケーションはフレーム精度のキャプチャは行わない。いくつかのポイントで、アプリケーションは Sleep 関数を呼び出しデバイスの反応を待つ。デバイス変更の状態時には DV カムコーダは絶対に通知を送らない。以前のデバイスは通知をサポートしていない場合がある、サンプルの目的からは、Sleep 呼び出しがシンプルな解決方法である。詳細は「DV カムコーダの制御」を参照すること。


PlayCap サンプル

説明

単純なキャプチャ アプリケーション。

このアプリケーションでは、ユーザーのシステムで見つかった最初のビデオ キャプチャ デバイス (ある場合) のプレビュー ウィンドウが作成される。また、ICaptureGraphBuilder2 インターフェイスおよび ICreateDevEnum インターフェイスを使ってキャプチャ グラフを構築する単純な例が示される。

さらに多くの機能をサポートするサンプル キャプチャ アプリケーションについては、「AmCap」を参照すること。

パス

ソース : (SDK ルート)\Samples\Multimedia\DirectShow\Capture\PlayCap

実行可能ファイル : (SDK ルート)\Samples\Multimedia\DirectShow\Bin\PlayCap.exe

参照

ビデオ キャプチャ


DMO サンプル

Microsoft® DirectShow® SDK には、次の Microsoft® DirectX® メディア オブジェクト (DMO) サンプルが含まれている。

  • DMO デモ
  • DMO サンプル
  • ガーグル DMO サンプル


DMO デモ

説明

このサンプル アプリケーションは、Microsoft® DirectX® メディア オブジェクト (DMO) の使い方について示している。WAV ファイルからオーディオ エフェクト DMO を通じて、オーディオ データを Microsoft® DirectSound® バッファにストリーミングする。

パス

ソース : (SDK ルート)\Samples\Multimedia\DirectShow\DMO\DMODemo

実行可能ファイル : (SDK ルート)\Samples\Multimedia\DirectShow\Bin\DMODemo.exe

ユーザー ガイド

サウンド ファイルを読み込むには、[Sound File] をクリックする。ドロップダウン コンボ ボックスを使ってオーディオ エフェクト DMO を選択する。次に、[Play] をクリックして、オーディオ エフェクトが設定されたサウンド ファイルを再生する。


DMO サンプル

説明

DMO サンプルは、Microsoft® DirectX® メディア オブジェクト (DMO) のサンプルである。MPEG-1 ビデオ パケットを入力とし、出力ストリームを 2 つ生成する。最初の出力ストリームには、RGB 565 フォーマットのビデオ フレームが含まれている。各フレームは MPEG-1 ビデオから取得したタイム コードを表示し、それがない場合は何も表示しない。2 つめの出力ストリームは、タイム コードの付いた、オプションのテキスト ストリームである。

DMO サンプルは、IMediaObjectImpl 基底クラス テンプレートを使用して、IMediaObject インターフェイスを実装する。このテンプレートの使用法の詳細については、「DMO 基底クラスの使い方」を参照すること。Active Template Library (ATL) は、登録、集合、IUnknown、DLL エントリ ポイントなど、さまざまな COM の詳細を処理する。

パス

ソース :(SDK ルート)\samples\Multimedia\DirectShow\DMO\DMOSample

ユーザー ガイド

このプロジェクト ワークスペースでは、Dmosample.dll という名前の DLL を作成する。Regsvr32 ユーティリティを使って DLL を作成する。この DMO の動作を見るには、 Microsoft® DirectShow® GraphEdit ユーティリティを使用する。ただし、MPEG-1 ビデオ ファイルが必要である。次の手順に従って実行する。

  1. GraphEdit を実行する。
  2. MPEG-1 ファイルをレンダリングする。
    • [File] メニューで [Render Media File] をクリックする。
    • MPEG-1 ビデオ ファイルを選択して、[Open] をクリックする。
  3. フィルタ グラフから MPEG-1 ビデオ デコーダ フィルタを選択して、Del キーを押す。
  4. グラフに DMO サンプルを挿入する。
    • [Graph] メニューで、[Insert Filters] をクリックする。
    • [DirectShow Filters] リストを展開する。
    • [DMO Sample] を選択して、[Insert Filters] をクリックする。
    • [Close] をクリックする。
  5. MPEG-1 ストリーム スプリッタ上の [Video] というラベルの付いた小さなボックスから、DMO サンプル上の [in0] というボックスまでマウスをドラッグして、MPEG-1 ストリーム スプリッタを DMO サンプルに接続する。(図を参照すること)
  6. DMO サンプルをビデオ レンダラに接続する。
    • DMO サンプル上の [out0] というラベルの付いたボックスから、ビデオ レンダラ上の [Input] というラベルの付いたボックスまでマウスをドラッグする。
    • GraphEdit により、RGB タイプ間の変換を行うカラー スペース変換 フィルタが自動的に挿入される。
  7. [GraphEdit] ツール バーの [Play] ボタンを押すか、または [Graph] メニューで [Play] をクリックする。

グラフを実行すると、タイム コードを表示する [Video] ウィンドウが現れる。

DMO サンプル フィルタの接続

プログラミング上の注意

DMO サンプルには、以下のソースおよびヘッダー ファイルが含まれている。

  • Dmosample.cpp: 基本的な COM 機能をATL に実装するためのコード。
  • Resource.h: リソース定数。
  • Sample.h、Sample.cpp DMO を実装する CSample クラス。
  • State.h、State.cpp MPEG データからタイム スタンプを生成するヘルパ クラスである、CStreamState クラス。
  • Stdafx.h、Stdafx.cpp ATL が必要とする基本機能。
  • Util.h、Util.cpp 出力イメージを秒がするためのユーティリティ機能。

DMO サンプルは、以下のリソース ファイルも使用する。

  • Dmosample.rc: バージョン情報を使用してリソースを定義し、Sample.rgs ファイルにリンクする。
  • Sample.rgs: レジストリ情報を使用してテキスト リソースを定義する。ATL はこのリソースを使用して、DLL の登録時にレジストリ エントリを作成する。

次の注意は、実装について詳細に説明している。

Dmosample.cpp

このファイルには、ATL が DMO オブジェクトを作成して登録するのに使用するオブジェクト マップが含まれる。また、エクスポートされる DLL 関数も含まれる。このような関数には、エントリ ポイント関数 (DllMain)、および COM に必要な関数 (DllCanUnloadNow、DllGetClassObject、DllRegisterServer、および DllUnregisterServer) がある。

ATL COM AppWizard は、このファイルに含まれるコードの大部分を自動生成する。次の 2 つが追加される。

  • DllRegisterServer 関数は、DMORegister を呼び出して、DMO に関するレジストリ情報を追加する。DMO は DMOCATEGORY_VIDEO_DECODER カテゴリに登録される。
  • DllUnregisterServer 関数は DMOUnregister を呼び出す。

Resource.h

このヘッダー ファイルで宣言される 1 つの定数 IDR_SAMPLE は、ATL の自動登録メカニズムで使用される。定数 IDR_SAMPLE は、テキスト リソースを識別する。これはリソース ファイル Sample.rgs で定義され、リソース ファイル Dmosample.rc によりインポートされる。ヘッダー ファイル Sample.h には、次の行がある。

DECLARE_REGISTRY_RESOURCEID(IDR_SAMPLE)

これにより、ATL は IDR_SAMPLE リソースに宣言された登録情報を使用できる。

Sample.h

DEFINE_GUID マクロは、DMO のクラス識別子 (CLSID) を宣言する。

CSample クラスは次のクラスから派生する。

  • IMediaObjectImpl。DMO 基底クラス。テンプレート パラメータは、DMO が 1 つの入力ストリームと 2 つの出力ストリームを持つことを指定する。
  • CComObjectRootEx。スレッド モデルを宣言する ATL クラス。テンプレート パラメータ CComMultiThreadModel は、スレッド対応オブジェクトを作成し、Lock メソッドと Unlock メソッドを提供する。
  • CComCoClass。標準 COM オブジェクトを宣言する ATL クラス。

CSample は、 カスタム マーシャリングを実行するフリー スレッド マーシャラ オブジェクトを集める。COM ライブラリが、サンプル プロセス内の複数のスレッドにまたがって CSample ポインタをマーシャリングする場合、まったく同じポインタが返される。COM ライブラリが複数のプロセスまたは複数のマシンにまたがってオブジェクトをマーシャリングしようとすると、エラーが発生する。ATL は、フリー スレッド マーシャラを集成するために必要なすべてのコードを追加する。このコードは、FinalConstruct メソッドと FinalRelease メソッドに現れる。COM マップ内の COM_INTERFACE_ENTRY_AGGREGATE エントリは、フリー スレッド マーシャラに IMarshal インターフェイスを委任する。

CSample クラスは、次のメンバ変数を宣言する。

m_pUnkMarshaler | フリー スレッド マーシャラ オブジェクトへのポインタ。
m_pBuffer | 入力バッファへのポインタ。DMO はすべての入力を処理するまで、バッファの参照カウントを保持する。
m_pbData | 入力バッファ内の次のバイトへのポインタ。
m_cbData | 未処理のバイト数。
m_rtFrame | 最後の出力フレームのタイム スタンプ。
m_StreamState | MPEG データを解析する、CStreamState ヘルパ クラスのインスタンス。
m_bPicture | DMO が出力するピクチャ情報を持っているかどうかを示す、ブール型フラグ。

Sample.cpp

このファイルは、CSample クラスにメソッドを実装する。

InternalGetInputStreamInfo

DMO は、任意のバウンダリに整列された任意のバイト数を処理できるので、このメソッドはゼロ フラグを返す。

InternalGetOutputStreamInfo

最初の出力ストリームは、固定サイズのサンプル全体を一度に作成する。これは、ビデオ デコーダでよく行われる。2 番目の出力ストリームはオプションである。返されるフラグは、これらの属性を示す。

InternalCheckInputType

入力タイプは、FORMAT_MPEGVide フォーマット タイプの MPEG-1 ビデオ ペイロードでなければならない。入力タイプの設定後、メソッドはフォーマットの変更を受け付けない。

InternalCheckOutputType

このメソッドは、出力フォーマットを検証する。出力ストリームは次の 2 つである。

  • ストリーム 0。このストリームでサポートされる唯一のメディア タイプは RGB-565 である。実際のビデオ デコーダは通常、複数のフォーマットをサポートする。また、出力のフレーム サイズは、入力のフレーム サイズと一致しなければならない。これは、実際のビデオ デコーダの多くに当てはまる。このストリームは、入力タイプが設定されてからでないと設定できない。
  • ストリーム 1。メディア タイプは MEDIATYPE_Text でなければならない。

タイプの設定後、新しいタイプが現在のタイプに一致しない場合、メソッドは失敗する。DMO がストリーミング中にフォーマット変更を処理できない場合は、同様のコードを含める必要がある。実際、サンプル DMO は、1 度に 1 つの出力フレームを生成するので、フォーマット変更を容易に受け入れることができる。

InternalGetInputType

このメソッドは、タイプを返さない。このため、あらゆるインデックス値が範囲外となり、戻り値は DMO_E_NO_MORE_ITEMS である。詳細については、「IMediaObject::GetInputType」を参照すること。

InternalGetOutputType

入力タイプが設定されていない場合、このメソッドはタイプを返さない。設定されている場合、各ストリームに 1 つのタイプが返される。ストリーム 0 の場合、入力サイズに等しいフレーム サイズの RGB-565 が返される。ストリーム 1 の場合、MEDIATYPE_Text が返される。

InternalGetInputSizeInfo

入力ストリームの最小バッファ サイズは 1 バイトであり、整列要件はない。ストリームはルックアヘッドを実行しない。

InternalGetOutputSizeInfo

ストリーム 0 の場合、バッファは出力サンプルを保持できるサイズが必要である。ストリーム 1 の場合、バッファはタイム スタンプ付きのテキスト文字列を保持できるサイズが必要である。

InternalFlush

このメソッドは、m_pBuffer (ATL スマート ポインタ) を NULL に設定することで、入力バッファを解放する。また、CStreamState オブジェクトをリセットする InternalDiscontinuity メソッドも呼び出す。

InternalProcessInput

このメソッドは、可能な限り多くの入力データを処理する。処理は次の手順で実行される。

  • Calls IMediaBuffer::GetBufferAndLength メソッドを呼び出して、入力データへのポインタと入力データのサイズを取得する。
  • 入力バッファへの参照カウントを保持する。m_pBuffer 変数は、ATL スマート ポインタなので、この変数に値を設定すると、IUnknown::AddRef メソッドを呼び出す効果を持つ。
  • タイム スタンプを CStreamState オブジェクトに渡す。サンプルにタイム スタンプがない場合は、値 INVALID_TIME を使用する。
  • プロセス ヘルパ メソッドを呼び出して、データを処理する。

InternalProcessOutput

出力するデータがない場合、このメソッドは S_FALSE を返す。データがある場合、出力データを生成する。ストリーム 0 の場合、次の手順で実行される。

  • 出力バッファが出力データを保持するのに十分なサイズであることを確認する。ない場合、メソッドはエラーを返す。
  • OurFillRect メソッドを呼び出して、背景を描画し、DrawOurText メソッドを呼び出して、テキストを描画する。
  • タイム スタンプを設定する。このフレームに有効なタイム スタンプがある場合は、それを使用する。ない場合は、前のタイム スタンプを平均フレーム レートでインクリメントする。
  • Process メソッドを再び呼び出して、入力バッファに残っていればすべてのデータを処理する。これにより出力データが増えた場合、DMO_OUTPUT_DATA_BUFFERF_INCOMPLETE フラグを設定する。

ストリーム 1 はオプションであるので、呼び出し側はストリーム 1 用のバッファを割り当てていないことがある。ストリーム 1 に出力バッファがないとしても、DMO はタイム コードをテキスト文字列として書き込む。タイム スタンプと処理フラグはストリーム 0 のものを参照する。

InternalAcceptingInput

DMO に前の入力バッファの参照カウントがまだある場合、DMO はそれ以上の入力を受け付けない。

Process

このプライベート メソッドは、CStreamState オブジェクトを更新しながら、入力データを 1 度に 1 バイトずつ順に処理する。入力データを処理し終えるまでに CStreamState オブジェクトがピクチャ バウンダリを見つけると、Process メソッドは S_OK を返す。ピクチャ バウンダリがない場合は、S_FALSE を返す。


ガーグル DMO サンプル

説明

このサンプルは Microsoft® DirectShow® ガーグル フィルタ サンプルと同じガーグル エフェクトを生成する Microsoft® DirectX® Media Object (DMO) のサンプルである。

このサンプルは次のインターフェイスの実装方法をデモンストレーションする :

  • IMediaObject
  • IMediaObjectInPlace
  • IMediaParamInfo
  • IMediaParams

パス

ソース: (SDK ルート)\Samples\Multimedia\DirectShow\DMO\GargleDMO

ユーザー ガイド

この DMO を使うには、Gargle.dll をビルドし登録すること。サンプル プロジェクトはいくつかの内部ライブラリをビルドする。Microsoft® Visual Studio® で DLL をビルドするには、[ビルド] メニューから [バッチ ビルド] を選択すること。

DMO デモ サンプルアプリケーションの DMO を使うことができる、あるいは DirectShow GraphEdit ユーティリティを使って DMO を使うこともできる。GraphEdit は自動的に DMO を DMO ラッパー フィルタでラップする。

SDK に入っている Microsoft® DirectMusic® Producer アプリケーションを含む Microsoft® DirectMusic® アプリケーションで DMO を使うこともできる。DirectMusic Producer では、Audiopath デザイナを使って DMO をオーディオパスに挿入する。メディア パラメータをコントロールするには、Parameter Control トラックを使う。トラックにカーブを挿入し、それをアサインして DMO の任意のパラメータをコントロールする。詳細は、DirectMusic Producer アプリケーション ヘルプの Audiopath Designer と Parameter Control Track を参照すること。

ガーグル DMO は操作している波形の形状 (矩形波あるいは三角波) と周波数をユーザーが設定する。それらのプロパティを設定するカスタム インターフェイス IGargleDMOSample をもサポートする。

プログラミングの注意

ガーグル DMO サンプルは Active Template Library (ATL) でビルドされる。ソース コードは 3 つのライブラリに整理されている :

ControlBase ライブラリ

  • Controlhelp.h, Controlhelp.cpp: ユーザー インターフェイス コントロール用のヘルパー ライブラリ、プロパティページによって使用される。

GargleDMO ライブラリ

  • Gargle.h, Gargle.cpp: ガーグル DMO の実装、IMediaObjectInPlace インターフェイスとカスタム IGargleDMOSample インターフェイスを含む。
  • GargleDMO.cpp: DllGetClassObject のような COM ライブラリに必要な DLL エントリ ポイント関数と DLL 関数。
  • GargleDMO.def: COM ライブラリに必要な DLL 関数を公開。
  • GargleDMOProp.h, GargleDMOProp.cpp: プロパティ ページの実装。プロパティ ページは ATL の IPropertyPageImpl クラス テンプレートを使用する。
  • IGargle.h: IGargleDMOSample インターフェイスを宣言する。
  • Resource.h: リソース定数。
  • Stdafx.h, Stdafx.cpp: ATL が要求する基本関数。

MedParamBase ライブラリ

  • Alist.h, Alist.cpp: 単純なリンク リスト クラス。
  • Param.h, Param.cpp: CParamsManager クラスが入る、これはメディア パラメータの IMediaParams インターフェイスと IMediaParamInfo インターフェイスを実装する。

ガーグル DMO は IMediaObjectImpl 基底クラスを使わない。IMediaObjectImpl が置き換わった古い DMO 基底クラスを使う。

IMediaObjectImpl クラスでは次の改善がされている :

  • より良いパラメータチェックの実装。
  • より厳格な呼び出しシーケンス。
  • IMediaObject::AllocateStreamingResources メソッド内のストリーミング リソース初期化に、よりシンプルなモデルを提供。

将来のリリースでは、ガーグル DMO は IMediaObjectImpl を使って書き直される。


サンプル DVD アプリケーション

Microsoft® DirectShow® SDK には以下のサンプル DVD アプリケーションが含まれている。

C++ アプリケーション

  • DVD サンプル

Microsoft® Visual Basic® アプリケーション

  • WebDVD サンプル


DVD サンプル

説明

DVDSample は、C++ DVD アプリケーションである。このサンプルでは、基本的なすべての再生機能とナビゲーション機能をはじめ、ペアレンタル ロック レベル、ブックマーク、カラオケ、コマンドの同期など、高度な機能についても示される。

パス

ソース : (SDK ルート)\Samples\Multimedia\DirectShow\DVD\DVDSample

実行可能ファイル : (SDK ルート)\Samples\Multimedia\DirectShow\Bin\DVDSample.exe


WebDVD サンプル

説明

単純な Microsoft® Visual Basic® DVD アプリケーション。

パス

ソース : (SDK ルート)\Samples\Multimedia\VBSamples\DirectShow\WebDVD

実行可能ファイル : (SDK ルート)\Samples\Multimedia\VBSamples\DirectShow\Bin\VB_WebDVDSample.exe

ユーザー ガイド

WebDVD サンプルでは、MSWebDVD Active X® コントロールを使って、DVD ビデオ再生とナビゲーションのすべての機能を実行する方法が示される。

Play メソッドを呼び出して再生を開始できる。再生後は、次のメソッドを使って再生のパスまたは動作を変更できる。

  • StopStop : 再生を停止する。
  • Eject : ドライブから DVD ディスクを取り出す。
  • Pause : 目的の時間だけ再生をポーズする。
  • ActivateButton : 現在選択されたボタンを有効にする。ボタンは、次の方法で選択できる。
    • ボタンの上にマウスを移動し、反転表示されるのを待つ。そのためには、DisableAutoMouseProcessing プロパティを FALSE (デフォルト) に設定する必要がある。
    • SelectAtPosition、SelectLeftButton、SelectRightButton、SelectLowerButton、あるいは SelectUpperButton を呼び出す。
  • PlayNextChapter : 現在のタイトル内の次のチャプターを再生する。
  • PlayPrevChapter : 現在のタイトル内の前の章を再生する。

ShowMenu メソッドを使うと、DVD ディスクに存在する可能性がある、次の 6 つのメニューを表示できる。

  • タイトル
  • ルート
  • サブピクチャ
  • オーディオ
  • アングル
  • チャプター

メニューが存在しない場合は、指定されたメニューが存在しないことを示すエラーが表示される。

クリップされたビデオ ディスプレイのサイズは GetClipVideoRect メソッドを通して変更可能である。ネイティブ ビデオのサイズは変更できない。


サンプル DirectShow フィルタ

Microsoft® DirectShow® SDK には、以下のサンプル フィルタが含まれている。

  • Async フィルタ サンプル
  • ボール フィルタ サンプル
  • コントラスト フィルタ サンプル
  • ダンプ フィルタ サンプル
  • EZRGB24 フィルタ サンプル
  • ガーグル フィルタ サンプル
  • InfTee フィルタ サンプル
  • NullIP フィルタ サンプル
  • NullNull フィルタ サンプル
  • SampVid フィルタ サンプル
  • スコープ フィルタ サンプル
  • Synth フィルタ サンプル
  • TextOut フィルタ サンプル
  • WavDest フィルタ サンプル


Async フィルタ サンプル

説明

段階的なダウンロードをサポートするファイル リーダー フィルタ。このサンプル フィルタは、IAsyncReader および IFileSourceFilter インターフェイスを実装する。MPEG ファイルはサポートしているが、AVI ファイルはサポートしていない。

パス

ソース : (SDK ルート)\Samples\Multimedia\DirectShow\Filters\Async

ユーザー ガイド

このサンプルには、フィルタのデモを行う小さなコマンド ライン アプリケーション Memfile.exe が含まれている。コマンド ラインの引数として、メディア ファイルおよびビット レート (単位は Kbps) を指定する。アプリケーションは、指定されたレートでメモリにファイルを読み込んで再生する。この作業を行うために、アプリケーションはフィルタのインスタンスを作成し、フィルタ グラフにフィルタを追加して、フィルタの出力ピンをレンダリングする。

使用法 :

Memfile ファイル名 ビットレート

Async サンプル フィルタは、AVI スプリッタ フィルタに接続できないため、AVI ファイルをサポートしていない。Async フィルタの出力ピンは、MEDIATYPE_Stream とそのメディア タイプの MEDIASUBTYPE_NULL を照会する。AVI スプリッタ フィルタの入力ピンは、MEDIASUBTYPE_NULL を受け入れることはできず、いずれのタイプも出力しない。そのため、ピンの接続は失敗する。Async フィルタは、必要な場合に MEDIASUBTYPE_Avi を提供するように強化できる。たとえば、ファイル フォーマットを調べたり、ファイル拡張を使うなどである。


ボール フィルタ サンプル

説明

はずんでいるボールのイメージを生成するビデオ ソース フィルタ。 このサンプルは、フォーマット ネゴシエーション、およびソース フィルタ基底クラスの CSource と CSourceStream の使用法を示す。

パス

ソース : (SDK ルート)\Samples\Multimedia\DirectShow\Filters\Ball

ユーザー ガイド

Fball.h および Fball.cpp のコードは、フィルタ インターフェイスを管理する。これら 2 つのファイルには、ソース フィルタに必要なほとんど最小限のコードが含まれている。Ball.h および Ball.cpp ファイルには、ボールをはずませるコードが含まれている。

このフィルタには出力ピンが 1 つあり、フレーム内ではねまわるボールを表示するビデオ ストリームを出力する。ボール フィルタは、ダウンストリーム グラフからの品質管理要求の受け入れも行うが、これは単純な品質管理の方法を示すものである。このフィルタは、品質管理のための IQualityControl インターフェイスを実装する。


コントラスト フィルタ サンプル

説明

コントラスト エフェクトを実装するビデオ変換フィルタ。このサンプルは、簡単なカスタム インターフェイスの定義および実装の方法を示す。また、CTransformFilter クラスを使用して簡単なエフェクト フィルタを実装する方法のデモも行う。

パス

ソース : (SDK ルート)\Samples\Multimedia\DirectShow\Filters\Contrast

ユーザー ガイド

コントラスト フィルタは、簡単な変換フィルタであり、フィルタを通過するビデオ ストリームのコントラストを調整する。このフィルタは、コントラストを調整するためのカスタム インターフェイスを提供する。また、コントラスト フィルタは CBasePropertyPage クラスを使用して、ユーザー インターフェイスを持たないアプリケーションのためのプロパティ ページも提供する。

コントラスト フィルタは、パレットによるトリックでコントラストを調整する。イメージのカラー パレットにより、イメージがどのように表示されるかを効果的に決定できる。パレットを変更することにより、フィルタはイメージ ピクセル自体を変更せずにコントラストを変更できる。


ダンプ フィルタ サンプル

説明

受け取ったメディア サンプルをテキスト ファイルに書き込むレンダリング フィルタ

パス

ソース : (SDK ルート)\Samples\Multimedia\DirectShow\Filters\Dump

ユーザー ガイド

このサンプルは、ベース フィルタ クラス CBaseFilter およびレンダリングされた入力ピン クラス CRenderedInputPin の使用法を示す。また、IFileSinkFilter インターフェイスも使用する。ダンプ フィルタは、レンダリングされた入力ピン クラスの Receive メソッドをオーバーライドして実際のメディア サンプルを処理する方法のデモを行う。ダンプ フィルタは、その入力ピンに対する CDumpInputPin::EndOfStream の呼び出しを受け取ると、フィルタ グラフに EC_COMPLETE 通知を送る。

このフィルタは、便利なデバッグ ツールである。たとえば、変換フィルタの結果をビットごとに確認できる。GraphEdit を使用して手動でグラフを作成し、変換フィルタの出力やその他の出力ピンにダンプ フィルタを接続することができる。ティー フィルタの接続では、ティー フィルタの 1 つのピンにダンプ フィルタを接続し、もう 1 つのピンに標準的な出力を接続して、リアルタイム シナリオにおける結果を監視することもできる。

ダンプ フィルタには入力ピンが 1 つあり、これはファイルにダンプされる。ダンプ フィルタは、インスタンス化されるときにユーザーにファイル名の入力を求め、解放されるとファイルを閉じる。


EZRGB24 フィルタ サンプル

説明

イメージ処理フィルタ。このフィルタは、赤、緑、青、暗色化、XOR、ぼかし、グレー、エンボスなど、個別のビデオ エフェクトを多数作成する。

パス

ソース : (SDK ルート)\Samples\Multimedia\DirectShow\Filters\EZRGB24

ユーザー ガイド

このサンプルは、CTransformFilter、CPersistStream、CBasePropertyPage など、Microsoft® DirectShow® クラスの使用法をいくつか示す。


ガーグル フィルタ サンプル

説明

オーディオ エフェクト フィルタ。

ガーグル フィルタは、フィルタを通過する波形にフィルタ内で数学的に生成される波形を掛けることにより、通過する波形を変調する。 デフォルトの変調波形は三角波である。プロパティ シートには、方形波という選択肢もある。変調波形の周波数は、フィルタのプロパティ シートにおいて設定できる。周波数が低い場合、エフェクトはトレモロのような音になる。周波数が高い場合、フィルタは元のサウンドに追加の周波数を生成し、エフェクトはディストーションのような音になる。

パス

ソース : (SDK ルート)\Samples\Multimedia\DirectShow\Filters\Gargle


InfTee フィルタ サンプル

説明

インフィニット ピン ティー フィルタ。このフィルタには入力ピンが 1 つと、数が動的である出力ピンが含まれている。フィルタに送られるデータ サンプルはいずれも、すべてのパスに同時に配信される。これにより、入力は複数の出力ストリームに接続される。

パス

ソース : (SDK ルート)\Samples\Multimedia\DirectShow\Filters\InfTee

ユーザー ガイド

フィルタは、すべての出力ピンに同じデータを送る。したがって、出力ピンは接続中に同じメディア タイプにネゴシエートしていなければならない。インフィニット ピン ティー フィルタは、同じメディア タイプを使用した場合に入力ピンと両方の出力ピンが集合するようにこのネゴシエーションを処理する。適切なメディア タイプが見つからない場合、接続は拒否される。

フィルタは常に、指定されたアロケータを使用する。アロケータを指定するのは、データを提供するフィルタである。入力ピンに到着するデータは、出力ピンに送られるまでコピーされない。また、フィルタは、データがダウンストリーム フィルタに確実に出力されるようにし、両方の出力が適時にサービスを受けることを保証する。特に、出力の 1 つが COutputQueue::Receive メンバ関数においてブロックされる可能性がある場合、ティーはサンプルを送信するスレッドをスピン オフする。サンプルを送信するスレッドがない場合は、ティー入力ピンにサンプルを送信するスレッドがダウンストリーム フィルタにデータを渡す。その時点でブロックされると、他方のダウンストリーム フィルタには長時間にわたってデータが送信されない。


NullIP フィルタ サンプル

説明

Null インプレイス変換フィルタ。このサンプル変換フィルタは、データを変更せずに、入力ピンからのデータをすべて出力ピンに渡す。

パス

ソース : (SDK ルート)\Samples\Multimedia\DirectShow\Filters\NullIP


NullNull フィルタ サンプル

説明

最小 Null フィルタ。このサンプル変換フィルタは、可能な限り最も簡単なフィルタを示す。このフィルタがサポートする機能はない。

パス

ソース :(SDK ルート)\Samples\Multimedia\DirectShow\Filters\NullNull


SampVid フィルタ サンプル

説明

サンプル ビデオ レンダリング フィルタ

パス

ソース : (SDK ルート)\Samples\Multimedia\DirectShow\Filters\SampVid


スコープ フィルタ サンプル

説明

サウンド データを波形で表示するレンダリング フィルタ

パス

ソース : (SDK ルート)\Samples\Multimedia\DirectShow\Filters\Scope

ユーザー ガイド

このフィルタを使用するには、GraphEdit を開いてオーディオ ファイル (または、オーディオ ストリームを含むビデオ ファイル) をレンダリングする。オーディオ レンダラの接続を一時的に解除して、インフィニット ピン ティー (InfTee) サンプル フィルタを挿入したら、オーディオ レンダラを再度接続する。続いて、インフィニット ピン ティー フィルタの 2 つめの出力ピンをスコープ フィルタに接続する。この状態で、グラフを実行する。

スコープ ウィンドウは、実際のウィンドウではなくダイアログ ボックスとして実装される。フィルタ パラメータをリアルタイムで変更するためのコントロール パネルを作成する開発者は、プロパティ ページの代わりにこのような技術を利用できる。

スコープ フィルタは、データ処理用に別スレッドを設定する方法を示す。この場合、データは単に IMemInputPin::Receive メソッドのバッファにコピーされた後、別スレッドのスコープ ウィンドウ上に表示される。

スコープ フィルタでオーディオ出力を監視して、クリッピングが起こっているかどうかを確認し、ゲインを調整することもできる。

このフィルタは、GraphEdit に "オシロスコープ" として表示される。


Synth フィルタ サンプル

説明

オーディオ波形を生成するソース フィルタ。

このフィルタは 動的グラフ作成 をデモンストレーションする。非圧縮 PCM オーディオと圧縮 MS_ADPCM (Microsoft Adaptive Delta Pulse Code Modulation) フォーマット間でスイッチ可能である。

このフィルタは GraphEdit 内で "Audio Synthesizer Filter" として表示される。

パス

ソース: (SDK root)\Samples\Multimedia\DirectShow\Filters\Synth

ユーザー ガイド

Synth フィルタを使うと、ユーザーは波形、周波数、チャンネル数、その他のプロパティをプロパティページを通して設定することができる。スイープ周波数レンジの上下のエンド ポイントを設定するには、シフトを押して周波数スライダを調整すること。このフィルタはこれらのプロパティ設定にカスタム インターフェイス ISynth2 をもサポートする。

動的グラフ作成機能をデモンストレーションするには、次のようにすること :

  1. フィルタを構築し、それを Regsvr32 ユーティリティで登録する。
  2. GraphEdit を開始する。
  3. Audio Synthesizer フィルタを挿入する。それは DirectShow フィルタ カテゴリを表示する。
  4. フィルタの出力ピンをレンダリングする。
  5. Play ボタンをクリックする。
  6. フィルタのプロパティ ページを開く。
  7. Output Format エリアで、PCM か Microsoft ADPCM を選ぶ。

プログラミングの注意

このサンプルは以下のファイルを含む :

  • Dynsrc.h, Dynsrc.cpp: 動的グラフ作成をサポートするソースフィルタの 2 つの基底クラス CDynamicSource と CDynamicSourceStream が入る。
  • ISynth.h: フィルタでプロパティを設定する カスタム ISynth2 インターフェイスの宣言。
  • Resource.h: リソース定数が入る。
  • Synth.def: COM ライブラリが必要とする DLL 関数を公開する。
  • Synth.h, Synth.cpp: オーディオ データを生成する CAudioSynth クラスと、フィルタを実装する CSynthFilter クラスが入る。
  • Synth.rc: フィルタが使用するリソースが入る。
  • Synthprp.h, Synthprp.cpp: フィルタのプロパティ ページの実装。

CDynamicSource クラスは CSource 基底クラスから適用されている。それは CDynamicSourceStream から派生された 1 つ以上の出力ピンを使用する。CDynamicSourceStream クラスは CSourceStream から適用されているが、CBaseOutputPin クラスではなく、CDynamicOutputPin クラスから派生する。

CDynamicSource クラスは CSource にはない以下のメソッドを持つ :

  • Stop: ストップ イベント (CDynamicOutputPin.m_hStopEvent) を知らせ、接続されていないすべてのピンのワーカー スレッドをシャットダウンする。接続されているピンでは、ピンの非アクティブなメソッドがそのワーカー スレッドをシャットダウンする。
  • Pause: ストップ イベントのリセット。
  • JoinFilterGraph: 各ピンで CDynamicOutputPin::SetConfigInfo メソッドを呼び出す。

CDynamicSourceStream クラスは CSourceStream にはない次のメソッドを持つ :

  • DestroySourceThread: ワーカー スレッドをシャットダウンする。
  • FatalError: フィルタ グラフ マネージャにエラーを知らせる。
  • OutputPinNeedsToBeReconnected: 出力ピンが再接続するべきであると知らせる。このメソッドが呼び出されると、ワーカー スレッドは CDynamicOutputPin::DynamicReconnect メソッドを呼び出しピンを再接続する。


TextOut フィルタ サンプル

説明

テキスト データを表示するレンダリング フィルタ

パス

ソース : (SDK ルート)\Samples\Multimedia\DirectShow\Filters\TextOut


WavDest フィルタ サンプル

説明

WAV ファイルにオーディオ ストリームを書き込む。入力としてオーディオ ストリームを 1 つ取得する。また、出力ピンは ファイル ライタ フィルタに接続しなければならない。このサンプル フィルタは、CTransformFilter クラスに基づいている。

パス

ソース : (SDK ルート)\Samples\Multimedia\DirectShow\Filters\WavDest


DirectShow のその他のサンプル

Microsoft® DirectShow® SDK には、ほかにも次のサンプルが含まれている。

C++ アプリケーション

  • ASFCopy サンプル
  • SysEnum サンプル

Microsoft® Visual Basic® アプリケーション

  • ビルダ サンプル


ASFCopy サンプル

説明

1 つ以上のファイルを 1 つの ASF ファイルにする。

パス

ソース: (SDK root)\Samples\Multimedia\DirectShow\Misc\ASFCopy

ユーザー ガイド

このサンプルをビルドするには、Microsoft® Windows Media™ Format SDK をインストールしてソフトウェア認証を受けなければならない。ソフトウェア認証を受けた後で、2 つの追加ライブラリ (WMStub.lib と WMVCore.lib) をリンクして、サンプルをビルドすること。

使用方法:

ASFCopy [/v] /p profile file1 [file2 ...] target

次のコマンドライン スイッチがサポートされている。

スイッチ | 説明
/p | プロファイル数を指定する。
/v | 冗長モード。

/p スイッチを使って ASF プロファイルを指定すること。このスイッチを省略すると、ASFCopy は標準システム プロファイルのリストを表示する。

1 つ以上のソース ファイルとターゲット ファイル名を指定すること。1 つ上のソースファイルを指定すると、アプリケーションはすべてのソースファイルをマルチプレックスする。ソースファイルに含まれているストリームにマッチするプロファイルを指定しなければならない、そうしないとアプリケーションは正しく動作しない。たとえば、Video for Web Servers (56 Kbps) を指定したら、結合されるソースファイルは実際に 1 つのビデオ ストリームと 1 つのオーディオ ストリームを持っていなければならない。

参照

Windows Media アプリケーション


SysEnum サンプル

説明

デバイスの列挙のために、システム デバイス列挙子の使い方を示す。詳細については、「デバイスとフィルタの列挙」を参照すること。

パス

ソース : (SDK ルート)\Samples\Multimedia\DirectShow\Misc\SysEnum

実行可能ファイル : (SDK ルート)\Samples\Multimedia\DirectShow\Bin\SysEnum.exe


ビルダ サンプル

説明

Microsoft® Visual Basic® のグラフ ビルダ アプリケーション。

このサンプル アプリケーションは Visual Basic でカスタム フィルタ グラフを構築する方法をデモンストレーションする。

パス

ソース: (SDK root)Samples\Multimedia\VBSamples\DirectShow\Builder


サンプル プレーヤー アプリケーション

Microsoft® DirectShow® SDK には、以下のサンプル プレーヤー アプリケーションが含まれる。

  • BGMusic サンプル
  • CutScene サンプル
  • Jukebox サンプル
  • PlayWnd サンプル
  • テクスチャ 3D サンプル

Microsoft® Visual Basic® Applications

  • VBDemo サンプル


BGMusic サンプル

説明

一連のオーディオ ファイルを順番に再生する再生アプリケーション。

このサンプルは、フィルタ グラフ内でソース フィルタを入れ替える方法を示す。アプリケーションが起動すると、シーケンスの先頭に位置するオーディオ ファイルがレンダリングされ、タイマが設定される。タイマが切れると、アプリケーションはソース フィルタを削除し、次のファイルに対するソース フィルタで置き換える。これらのファイルはすべて同じタイプであるため、グラフ全体を再作成する必要はない。

パス

ソース : (SDK root)\Samples\Multimedia\DirectShow\Players\BGMusic

実行可能ファイル : (SDK root)\Samples\Multimedia\DirectShow\Bin\BGNusic.exe


CutScene サンプル

説明

ユーザーが ESC キー、ENTER キー、または SPACE キーを押すまで、フルスクリーン モードでビデオ ファイルを再生する。

パス

ソース : (SDK ルート)\Samples\Multimedia\DirectShow\Players\CutScene

ユーザー ガイド

このサンプルはコマンド ラインから実行し、引数としてビデオ ファイルの名前を指定する。


Jukebox サンプル

説明

ビデオ ジュークボックス アプリケーション。

このアプリケーションは、ディレクトリでメディア ファイルを走査し、ファイル名の一覧を表示する。ユーザーは個別のファイルを再生したり、すべてのファイルを順に再生したりできる。Jukebox には、作成するフィルタ グラフに関する情報も表示される。これには、フィルタの名前、ピンの名前、および生成されるイベント コードが含まれる。

注 このサンプルには Microsoft Foundation Class Library 4.2 (Mfc42.dll) が必要である。

パス

ソース : (SDK ルート)\Samples\Multimedia\DirectShow\Players\Jukebox

実行可能ファイル : (SDK ルート)\Samples\Multimedia\DirectShow\Bin\Jukebox.exe

ユーザー ガイド

ディレクトリ名がコマンドライン引数として指定されると、Jukebox は起動時にそのディレクトリを走査する。それ以外の場合は、SDK ルート ディレクトリ以下の Samples\Multimedia\Media にある、デフォルトの SDK メディア ディレクトリを走査する。Jukebox では、ディレクトリのすべてのメディア ファイル一覧が表示されるので、ユーザーは一覧から再生するファイルを選択できる。

Jukebox では、次のユーザー インターフェイス要素が提供される。

  • [Play]、[Stop]、[Pause]、および [FrameStep] ボタン : これらのボタンを使って、グラフの再生を制御する。グラフが IVideoFrameStep をサポートしてない場合、[FrameStep] ボタンは無効になっていることがある。
  • [Thru] および [Loop] ボタン : [Thru] をクリックすると、現在選択されているファイルから、ファイルの一覧全体が再生される。[Loop] をクリックすると、同じファイルが繰り返し再生される。これらの 2 つのボタンは、相互排他的である。
  • [Mute] ボタン : オーディオをミュートする。
  • [Filters]、[Input Pins]、および [Output Pins] : Jukebox がグラフを作成する際に、グラフのフィルタ一覧を表示する。ユーザーがフィルタ名のいずれかを選択すると、フィルタの入力ピンと出力ピンの一覧が表示される。
  • [Display Events] : このチェック ボックスをオンにすると、Jukebox が受け取るイベント コードが表示される。一覧を消去するには、[Clear] をクリックする。
  • [Properties] ボタン : フィルタのプロパティ ページを表示するには、フィルタ名を選択し、[Properties] をクリックする。フィルタがプロパティ ページをサポートしていない場合、このボタンは無効になる。


PlayWnd サンプル

説明

簡単なメディア プレーヤー アプリケーション

パス

ソース : (SDK ルート)\Samples\Multimedia\DirectShow\Players\PlayWnd

実行可能ファイル : (SDK ルート)\Samples\Multimedia\DirectShow\Bin\PlayWnd.exe

ユーザー ガイド

再生ファイルは、コマンド ラインの引数として指定できる。指定されていない場合、アプリケーションは起動時に Open Media File ダイアログを表示する。選択されたファイルの再生が自動的に開始される。


テクスチャ 3D サンプル

説明

Microsoft® DirectX® 8.0 のテクスチャ サーフェス上にビデオを描画する。

注 : このサンプルは、サンプル実行中のモニタの表示プロパティの変更はサポートしていない。

パス

ソース : (SDK ルート)\Samples\Multimedia\DirectShow\Players\Texture3D

実行可能ファイル : (SDK ルート)\Samples\Multimedia\DirectShow\Bin\Texture3D.exe


VBDemo サンプル

説明

Microsoft® Visual Basic® のシンプルなメディア プレーヤー。

パス

ソース: (SDK root)Samples\Multimedia\VBSamples\DirectShow\VBDemo


サンプル ビデオ編集アプリケーション

Microsoft® DirectShow® SDK には、ビデオ編集に関連した、次のサンプル アプリケーションが含まれている :

C++ アプリケーション

  • SampGrabCB サンプル
  • StillCap サンプル
  • TimeLine テスト サンプル
  • XTLTest サンプル

Microsoft® Visual Basic® アプリケーション

  • DexterVB サンプル
  • SlideShowVB サンプル
  • TrimmerVB サンプル
  • XTLTestVB サンプル


SampGrabCB サンプル

説明

フィルタ グラフを通過する際に、メディア サンプルに関する情報を表示する。

パス

ソース : (SDK ルート)\Samples\Multimedia\DirectShow\Editing\SampGrabCB

ユーザー ガイド

このコンソール アプリケーションは、IMediaDet インターフェイスを使って、サンプル グラバ フィルタが含まれたフィルタ グラフを作成する。アプリケーションは、コールバック関数を使ってビデオ ファイルからサンプルを取得する。

使用法

SampGrabCB ファイル名

次に示すのは、アプリケーションからの出力例である。

Sample received = 00000  Clock = 4464847
Sample received = 00001  Clock = 4464848
Sample received = 00002  Clock = 4464849
Sample received = 00003  Clock = 4464850
Sample received = 00004  Clock = 4464853


StillCap サンプル

説明

スティル イメージをビットマップ ファイルに書き込む、ビデオ キャプチャ アプリケーション。

パス

ソース : (SDK ルート)\Samples\Multimedia\DirectShow\Editing\StillCap

ユーザー ガイド

このアプリケーションは、ISampleGrabber インターフェイスを使って、ライブ キャプチャ ストリームからビットマップ ファイルにスティル イメージをキャプチャする。また、サンプル グラバ フィルタをフィルタ グラフに配置する方法と、コールバック関数を使ってリアルタイムでサンプル データを取得する方法について示している。

このアプリケーションは、見つかった最初のビデオ キャプチャ デバイスを使って、キャプチャ グラフを構築する。スティル イメージをキャプチャするには、[Snap Still] をクリックする。デフォルトでは、ビットマップは StillCap0000.bmp というファイル名で保存される。[Increment filename after each capture?] チェック ボックスをオンにすると、各イメージは新しいファイル名で保存される。それ以外の場合は、新しいイメージをキャプチャすると、以前のイメージにオーバーライドされる。

このアプリケーションは、ビデオ ファイルもキャプチャできる。[Capture Type] エリアの [Video Capture] をクリックすると、ビデオ キャプチャが自動的に開始される。キャプチャ セッションを終了するには、[Start Playback] をクリックする。記録されたファイルは、自動的に再生される。

簡単にするため、このサンプルでは 24 ビット RGB フォーマットが使われる。ビデオ ドライバが 16 ビット色に設定されている場合は、アプリケーションの実行中にフリッカーが発生することがある。この問題を解決するには、ディスプレイのビット数を 24 ビットまたは 32 ビットに設定する。


Timeline Test サンプル

説明

このサンプル アプリケーションはトランジションを使ってタイムラインを構築する。Microsoft® DirectShow® 編集サービス の以下のタスクをデモンストレーションする :

  • タイムラインを作成する。
  • トラック、ソース、トランジション、エフェクトをタイムラインに追加する。
  • SMPTE ワイプ トランジションを作成する。
  • ボリューム エンベロープ エフェクトを使ってオーディオ クロスフェードを作成する。
  • タイムライン オブジェクトのプロパティを設定する。
  • タイムラインを修正して、フィルタグラフを再度レンダリングする。

パス

ソース: (SDK ルート)\Samples\Multimedia\DirectShow\Editing\TimelineTest


XTLTest サンプル

説明

ビデオ編集プロジェクトのレンダリングとプレビューのためのコマンドライン ツール。このツールは、Microsoft® DirectShow® 編集サービス (DES) のプロジェクト ファイルをレンダリングする。

このアプリケーションで ASF サポートを有効にするには、プロジェクトを Microsoft® Windows Media™ Format (WMF) SDK 認証にリンクし、アプリケーションをコンパイルする際に USE_WMF_CERT を定義すること。認証の入手方法については、WMF SDK のドキュメントを参照すること。

注 このアプリケーションには Internet Explorer 4.0 以降が必要である。それがないと、アプリケーションは次のエラーメッセージを表示する : Unexpected error = Dshow not installed correctly 詳細については「IXml2Dex」を参照すること。

パス

ソース : (SDK ルート)\Samples\Multimedia\DirectShow\Editing\Xtltest

ユーザー ガイド

このサンプル アプリケーションでは、ビデオ編集に関連する次のタスクが示される。

  • タイムラインのプレビューと、レンダリングされた出力のファイルへの書き込み
  • タイムラインをレンダリングする際のタイムライン オプションの設定

使用法

xtltest.exe [スイッチ] input.xtl

デフォルトでは、プロジェクトはプレビューされる。次のコマンドライン スイッチがサポートされている。

スイッチ | 説明
/C | クロックなし。オーディオとビデオを同期せずに、できる限り速くプロジェクトをレンダリングする。
/D | ソース ファイルを動的に読み込む。詳細については、「IRenderEngine::SetDynamicReconnectLevel」を参照すること。
/[double-double] | レンダリングの開始タイムと終了タイムを設定する。たとえば、/[3-4] と指定すると、プロジェクトの 3 秒目から開始して、タイムラインの 1 秒間がレンダリングされる。
/G filename.grf | GraphEdit ファイルを .grf フォーマットで出力する。
/N | レンダリングなし。このプロジェクトはプレビューまたはファイルへのレンダリングは行われない。このオプションは、入力ファイルを確認したり、/G スイッチを使うときに役立つ。
/P [number] | ASF 圧縮プロファイルを選択する。アプリケーションが WMF SDK 証明書を使ってコンパイルされた場合にだけ利用できる。
/P | 利用可能な ASF プロファイルを一覧にする。アプリケーションが WMF SDK 証明書を使ってコンパイルされた場合にだけ利用できる。
/R | スマート再圧縮を有効にする。アプリケーションは、圧縮フォーマット用にタイムラインの最初のクリップを使用する。このオプションは、/W スイッチと共に使用する。詳細については、「レンダリング エンジンについて」を参照すること。
/W filename | タイムラインをファイルにレンダリングする。このファイル タイプは、ファイルの拡張子によって決定される。アプリケーションは、AVI ファイルおよび WAV ファイルをサポートする。アプリケーションが WMF SDK 証明書を使ってコンパイルされる場合は、ASF ファイルもサポートする。このオプションでは、プレビューは抑止される。
/X filename.xtl | プロジェクトを XML ファイルとして保存する。新しいファイルは、入力ファイルと機能的には同じになるが、XML タグが異なることがある。

プログラミングの注意

このサンプルでは、XML プロジェクト ファイルの読み取りをはじめ、そのプレビューまたはファイルへの出力に必要なすべてのステップが示される。

スマート再圧縮では、アプリケーションはタイムラインでミュートされていない最初のソースのフォーマットを使用する。最初のソースがオーディオ ファイルであると失敗する。GetFirstSourceOnTimeline 関数は、ミュートされていない最初のソースを取得する。この関数は、タイムラインでオブジェクトを走査する方法を示す。GetSourceVideoType 関数は、ソースの最初のビデオ ソースのメディア タイプを取得する。アプリケーションは、IAMTimelineGroup::SetSmartRecompressFormat を呼び出して再圧縮フォーマットを設定する際に、このメディア タイプを使用する。詳細については、「プロジェクトのレンダリング」を参照すること。

エラー ログを処理するために、アプリケーションはカスタム クラス CErrorReporter を定義する。このクラスは、IAMErrorLog インターフェイスを公開する。しかし、参照カウントを正しく処理しないので、これは真の COM オブジェクトではない。そのため、アプリケーションは静的に COM オブジェクトを作成しなければならない。詳細については、「エラーのログ」を参照すること。

USE_WMF_CERT が定義された場合、アプリケーションは WMF ファイルの書き込みサポートを含める。CKeyProvider クラスは、IServiceProvider インターフェイスを実装する。このクラスは WMCreateCertificate 関数を呼び出して、WMF 証明書を作成する。ヘルパー関数 ListWMSDKProfiles は、WMK SDK で提供される標準プロファイルを一覧にする。詳細については、「Windows Media アプリケーション」および Windows Media Format SDK を参照すること。


DexterVB サンプル

説明

Microsoft® Visual Basic® のビデオ編集アプリケーション。

このサンプル アプリケーションは Microsoft® DirectShow® 編集サービス タイムラインを作成するグラフィカル ツールである。以下のタスクをデモンストレーションする :

  • Loading and saving XTL プロジェクト ファイルのロードとセーブ
  • タイムライン オブジェクトの追加、編集、削除
  • タイムラインのプレビュー

パス

ソース: (SDK root)\Samples\Multimedia\VBSamples\DirectShow\Editing\DexterVB

ユーザー ガイド

次の図は VexterVB アプリケーション ウィンドウを示す。

DexterVB ユーザー インターフェイス

左のペインはタイムラインを持つツリー ビュー コントロールを表示する。右のペインはタイムラインについての情報を表示する、タイムライン内のオブジェクトについての情報を見るには、ツリー ビュー内のオブジェクトのアイコンを選択すること。

新しいタイムラインを作成するにはFile メニューから New を選択すること。プロジェクト ファイルを開くにはFile メニューから Open を選択すること。現在のタイムラインをプロジェクト ファイルに保存するには File メニューから Save As を選択すること。

タイムラインあるいはタイムラインのオブジェクトのいずれかを変更するには、左のペインで対応するアイコンを右クリックすること。DexterVB はそのオブジェクトのポップアップ メニューを表示する。次の図はタイムラインのポップアップ メニューを示す。

各オブジェクトについて、ポップアップ メニューはそのオブジェクトに対して適用するコマンドだけを持つ。次のコマンドがサポートされている :

  • Add (オブジェクト タイプ): 指定したタイプの新しい子オブジェクトを挿入する。
  • Collapse: このオブジェクトのツリー ビュー ノードを折りたたむ。
  • Delete: タイムラインからオブジェクトを削除する。
  • Edit: オブジェクトのプロパティをユーザーから編集可能にする。
  • Expand: このオブジェクトのツリー ビュー ノードを展開する。

次のコマンドはタイムライン自身に固有のものである :

  • Clear Render Engine: フィルタ グラフを削除する。
  • Insert Group: タイムラインに新しいグループを挿入する。
  • Play: プロジェクトのプレビュー。ユーザーはタイムラインを最初にレンダリングしなければならない。
  • Pause: プレビューのポーズ。
  • Render Timeline: このタイムラインからプレビュー グラフ を構築する。
  • Stop: プレビューの停止。


SlideShowVB サンプル

説明

一連のビデオ クリップや(複数の)イメージ ファイルからスライドを見せる Microsoft® Visual Basic® アプリケーション。

パス

ソース: (SDK root)\Samples\Multimedia\VBSamples\DirectShow\Editing\SlideShowVB

ユーザー ガイド

このサンプル アプリケーションは以下のタスクをデモンストレーションする :

  • Using the MediaDet オブジェクトを使って、ソース クリップからポスター フレームを取得する。
  • タイムラインを XTL ファイルに保存する。
  • タイムラインを AVI ファイルに書き込む。
  • メディア クリップを読み込む。

このアプリケーションを使うには、次のようにする :

  • ビデオ ファイルか(複数の)イメージ ファイルをアプリケーション ウィンドウのセルにドラッグし、左上角のセルから開始する。
  • 各クリップが再生される時間幅を秒単位で入力する。
  • コンボ ボックスを使ってトランジションを選択する。トランジションは 2 秒の時間幅で固定されている。
  • スライド ショーをプレビューするには、Play をクリックする。
  • XTL プロジェクトとしてスライド ショーを保存するには、Write XTL をクリックする。
  • AVI ファイルとしてスライド ショーを保存するには、Write AVI をクリックする。


TrimmerVB サンプル

説明

ソース クリップをトリムし、トリムされたクリップを新しいファイルに書き込む Microsoft® Visual Basic® アプリケーション。

パス

ソース: (SDK ルート)\Samples\Multimedia\VBSamples\DirectShow\Editing\TrimmerVB

ユーザー ガイド

このアプリケーションを使うとユーザーはビデオ ソースファイルを開き、開始点と終了点から希望する分だけクリップをトリムし、次に残った部分を新しいファイルに保存する。

このアプリケーションを使うには以下のようにする :

  1. ソースファイルを選択するには、Browse ボタンをクリックする。クリップの最初のフレームが 3 つのプレビューエリアに表示される。
  2. 開始位置を選択するには、スライダを動かすかフレームストップボタンをクリックする。Current Video Frame エリアのプレビュー フレームがアップデートされる。
  3. 開始位置を設定するには、Set Trim Preview Start Position ボタンをクリックする。Video Start Frame エリアのポスター フレームがアップデートされる。
  4. 停止位置を選択するには、スライダを動かすかフレームストップボタンをクリックする。
  5. 停止位置を設定するには、Set Trim Preview Stop Position ボタンをクリックする。Video Stop Frame エリアのポスター フレームがアップデートされる。
  6. 新しいファイルに書き込むには、Write ボタンをクリックする。プログレス インジケータが完了するまで待つ。
  7. 新しいファイルを見るには、Playback ボタンをクリックする。


XTLTestVB サンプル

説明

ビデオ編集プロジェクト ファイルをプレビューする Microsoft® Visual Basic® アプリケーション。

このアプリケーションを使うには、Microsoft® DirectShow® 編集サービス XTL ファイルをアプリケーションのウィンドウにドラッグする。

パス

ソース: (SDK root)Samples\Multimedia\VBSamples\DirectShow\Editing\XTLTestVB


DirectX Media Object

ここでは、Microsoft® DirectX® Media Object (DMO) について説明する。

  • DirectX Media Object の概要
  • DirectX Media Object の使用
  • DMO とメディア タイプ
  • DirectShow アプリケーションでの DMO の使用
  • DMO の関連情報


DirectX Media Object の概要

Microsoft® DirectX® Media Object (DMO) は、データ ストリーミング コンポーネントを作成するための新しい手段である。DMO と Microsoft® DirectShow® フィルタにはいくつかの共通点がある。DirectShow フィルタと同様に、DMO も入力データを受け取り、それを使って出力データを生成する。ただし、DMO のアプリケーション プログラミング インターフェイス (API) は、DirectShow の同等の API よりずっと単純である。したがって、DMO は、より簡単に作成でき、テストでき、使用できる。

DMO は DirectShow と完全な互換性を持っているが、アプリケーションは DirectShow を使わずに DMO を使用できる。 DMO は、DirectShow アプリケーションの内部で DMO ラッパー フィルタという DirectShow フィルタによってラップされる。フィルタと DMO の区別はアプリケーションに対しては透過的であり、アプリケーションが DMO API を使う必要はない。一方、DirectShow に基づいていないアプリケーションは、DMO を直接使用できる。したがって、DMO を作成すれば、広範囲のアプリケーションで使用できるコンポーネントを作成できる。

  • DMO と DirectShow フィルタの違い
  • DMO を使う理由
  • DMO テスト アプリケーション

DMO と DirectShow フィルタの違い

DirectShow フィルタは DirectShow フィルタ グラフ内でのみ機能する。フィルタ グラフ マネージャがアプリケーションとグラフ内のフィルタを仲介する。DMO ではその必要がない。アプリケーションは単独で DMO を使用できる。

DirectShow では、フィルタが、データのストリーミングに必要な大半の作業を実行する。その作業は以下のとおりである。

  • バッファを割り当てる。
  • メディア タイプおよびほかのフィルタとの接続をネゴシエートする。
  • データをフィルタ グラフに送り、通過させる。
  • フィルタ グラフ マネージャへイベントを送信する。
  • 複数のスレッドを同期させる。

これと対照的に、DMO はこれらの作業をまったく行わない。この種の作業を実行する役割は、DMO を使用するクライアントが担う。クライアントは、バッファを割り当て、割り当てたバッファにデータを格納する。その後、クライアントはバッファを DMO に配布し、DMO はそれを処理する。クライアントは出力バッファを取り出す。

DirectShow の内部では DMO ラッパー フィルタが DMO のクライアントであるため、DMO ラッパー フィルタがこれらすべての作業を処理する。ほかのアプリケーションは、独自の実装を提供できる。

DMO を使う理由

DMO の利点

  • 一般的に、DMO はサポートする機能が少ないため、 DirectShow フィルタより小さく、単純である。
  • DMO はフィルタ グラフを必要としないため、DirectShow フィルタより順応性がある。グラフの同期、インテリジェント接続、データ フローの自動処理、スレッド管理など、DirectShow のサービスが必要なときは、DMO を DirectShow と組み合わせて使用できる。これらのサービスが必要ないときは、DMO に直接アクセスできる。
  • DMO は常に同期データ処理を実行する。そのため、フィルタ開発者は、スレッドに関するさまざまな問題を考慮する必要がない。
  • ACM CODEC や VCM CODEC と異なり、DMO は Component Object Model (COM) に基づいているため、QueryInterface を使って拡張できる。
  • DMO がサポートするストリーミング モデルは、ACM CODEC や VCM CODEC のサポートするモデルより汎用性が高い。DirectShow フィルタと同様に、DMO は複数の入力と複数の出力をサポートできる。

これらの理由により、できる限り、DirectShow フィルタより DMO を実装した方がよい。ただし、たとえば以下のように DMO が適していない状況もある。

  • 特殊な転送要件がある場合。DMO ラッパー フィルタは、IMemInputPin 転送を使用する。DirectShow アプリケーション内で、ほかの転送メカニズムが必要な場合は、フィルタを作成しなければならない。
  • 動的グラフ作成を行う場合。アプリケーションが動的グラフ作成を実行する場合は、独自のフィルタの作成が必要になることがある。たとえば、アロケータを作成する方法を制御する必要が生じることがある。

DMO テスト アプリケーション

DirectX 8.0 SDK には、DMOTest という名前の DMO テスト アプリケーションが含まれている。このテスト アプリケーションは、DMO が DMO 仕様に一致しているかどうかを検証する手助けになる。このアプリケーションは、SDK ルート ディレクトリ以下の Bin\DXUtils ディレクトリにインストールされている。DMO を開発する場合は、テストの一部として DMO テスト アプリケーションを含める必要がある。

DMOTest を使うためには、DMO 用のテスト データを生成しなければならない。SDK には、そのために DirectShow フィルタが含まれている。このフィルタは、DLL ファイル DMODump.dll に存在する。また、Regsvr32 ユーティリティを使って登録する必要がある。

テスト アプリケーションの詳細は、DMOTest アプリケーションのヘルプに説明されている。アプリケーションで、[Help] メニューの [Contents] をクリックする。このヘルプには、テスト データの生成とテスト アプリケーションの実行に関する詳細な指示が含まれている。


DirectX Media Object の使い方

ここでは、アプリケーションで Microsoft® DirectX® Media Object (DMO) を使う方法を説明する。このトピックの説明は、DMO に直接アクセスするアプリケーションに対してのみ当てはまる。Microsoft® DirectShow® フィルタ グラフで DMO を使用する場合は、DMO ラッパー フィルタを使用する。

以下の項目について説明する。

  • ストリームとバッファ
  • データの流れ
  • データを処理する方法
  • 破棄可能ストリームとオプション ストリーム
  • インプレイス DMO

ストリームとバッファ

概念的にいえば、DMO は、m 個の入力を受け取り、n 個の出力を生成するオブジェクトである。入力と出力は "ストリーム" と呼ばれる。すべての DMO には少なくとも 1 つのストリームがある。入力ストリームのない DMO や出力ストリームのない DMO もあるが、通常の DMO には入力と出力の両方がある。

注 DirectShow のピンと異なり、ストリームは個別の COM オブジェクトではない。ストリームは DMO オブジェクト自体からゼロベース インデックスを使って参照される。

DMO は入力ストリームを通じてデータを受け取る。DMO はデータを処理し、出力ストリームを通じて出力を生成する。すべてのデータは "メディア タイプ" によって分類される。メディア タイプは、データの内容を解釈する方法を定義する。たとえば、320 x 240 24 ビット RGB は 1 つのタイプであり、44.1KHz 16 ビット ステレオ PCM オーディオは別のタイプである。メディア タイプは、DMO_MEDIA_TYPE 構造体を使って記述される。

DMO の各ストリームは、特定の範囲のメディア タイプを受け入れることができる。DMO によって、受け入れるタイプの範囲が広いことも (たとえば任意のビット深度のビデオ)、狭いこともある (たとえば 16 ビット ビデオのみ)。また、特定の入力と出力の組み合わせに限定された DMO もある。たとえば、入力ストリームが 16 ビット ビデオに設定されている場合は、出力ストリームのビット深度を同じにしなければならないことがある。アプリケーションは、各ストリームの優先タイプを列挙した後、特定の組み合わせをテストすることができる。

例:

  • ビデオ用とオーディオ用の 2 つの入力ストリームを持つ、AVI データを作成する DMO。この DMO は、インターリーブされたオーディオ ビデオ データ用の 1 つの出力ストリームを生成する。
  • RGB 画像のポスタリゼーションを行う、入力が 24 ビット RGB ビデオ、出力が 8 ビット RGB ビデオの DMO。

アプリケーションは、メモリ ブロックごとにグループ分けされた入力データを配布する。個々のメモリ ブロックは、IMediaBuffer インターフェイスをサポートする "バッファ" と呼ばれる COM オブジェクトによってカプセル化される。このインターフェイスは、バッファ内のデータ長を設定するメソッド、データを指すポインタを取得するメソッド、および割り当てられたバッファのサイズを取得するメソッドを備えている。アプリケーションは、DMO が入力と出力の両方に使用するすべてのバッファを割り当てる役割を担う。

データの流れ

ここでは、データがアプリケーションと DMO の間で、どのように移動するかを説明する。

アプリケーションは、入力バッファの配布と出力の要求を交互に行う。アプリケーションは、DMO に対して IMediaObject::ProcessInput メソッドを呼び出すことによって入力バッファを配布し、IMediaObject::ProcessOutput メソッドを呼び出すことによって出力を要求する。

入力データの流れを止めるには 2 つの方法がある。

  • 途切れ (discontinuity): アプリケーションが入力データの末尾に到達するか、データに途切れがあると、アプリケーションは "途切れ (discontinuity)" を通知する。途切れは、それ以上入力がないことを DMO に知らせる。その時点で、処理するデータが DMO に残っていることがあるため、データがなくなったことを DMO が通知するまで、アプリケーションは出力の要求を続ける必要がある。
  • フラッシュ: アプリケーションは、"フラッシュする" ことによってデータの流れを中断することができる。DMO が内部でデータをバッファリングしている場合、DMO はデータを解放する。

ストリーミングは、アプリケーションが最初に DMO に対して IMediaObject::ProcessInput を呼び出したときに始まる。DMO は、アプリケーションがすべてのストリームのメディア タイプを設定するまで、ストリーミングを開始しない。(オプション ストリームは例外である。「破棄可能ストリームとオプション ストリーム」を参照すること。) アプリケーションが DMO をフラッシュするか、すべての入力ストリームの途切れを通知した後、すべての出力を処理すると、ストリーミングが停止する。これらの動作によって DMO は非ストリーミング状態に戻る。DMO はすべてのメディア タイプの設定を保持するが、すべての IMediaBuffer ポインタを解放する。それ以降、アプリケーションが少なくとも 1 回 ProcessInput を呼び出すまで、DMO は出力を生成できない。

データをストリーミングするには、以下の手順を実行する。

  1. DMO がサポートするストリームの数と各ストリームの優先メディア タイプを DMO に問い合わせる。
  2. すべてのストリームのメディア タイプを設定する。
  3. 入力バッファと出力バッファを割り当てる。
  4. 入力バッファにデータを格納し、ProcessInput を呼び出す。
  5. ProcessOutput を呼び出し、出力データを取得する。すべての入力データが処理されるまで、手順 4 ～ 5 を繰り返す。
  6. 途切れを通知し、残っているすべての出力を処理する。

データをフラッシュすることによって手順 4 ～ 5 を中断できる。

データを処理する方法

ここでは、前のセクションで示した手順を詳しく説明する。

手順 1: DMO に対する問い合わせ

まず、DMO がサポートするストリームの数と各ストリームの優先メディア タイプを DMO に問い合わせる。入力ストリームと出力ストリームの数を取得するには、IMediaObject::GetStreamCount メソッドを呼び出す。

各ストリームについて、DMO は優先順位に従って優先メディア タイプのランク付けを行い、各タイプにゼロから始まるインデックスを割り当てる。特定のストリームの優先メディア タイプを取得するには、IMediaObject::GetInputType メソッドまたは IMediaObject::GetOutputType メソッドを呼び出す。ストリーム番号とメディア タイプ インデックスを指定する。ストリームのすべてのメディア タイプを列挙するには、以下の疑似コードに示すように、メソッドが DMO_E_NO_MORE_ITEMS を返すまで、メディア タイプ インデックスをインクリメントするループを使用する。

DWORD cInputs, cOutputs, type = 0
DMO_MEDIA_TYPE mt

pDMO->GetStreamCount(&cInputs, &cOutputs)

for (DWORD i = 0; i < cInputs; i++)
{
    while (pDMO->GetInputType(i, type, &mt) != DMO_E_NO_MORE_ITEMS)
    {
        if ( this media type is one you want )
            break
        MoFreeMediaType(&mt)
        type++
    }
}

GetInputType メソッドと GetOutputType メソッドは、メディア タイプと共に DMO_MEDIA_TYPE 構造体を返す。以下の構造体メンバが関係する。

  • majortype: ストリームの "メジャー タイプ" を指定するグローバルに一意な識別子 (GUID)。 メジャー タイプは、ビデオやオーディオなどの大まかな分類である。メジャー タイプの一覧については、「メジャー タイプ」を参照すること。
  • subtype: ストリームの "サブタイプ" を指定する GUID。サブタイプは、タイプをさらに細かく分類する。たとえば、MEDIASUBTYPE_RGB24 は 24 ビット RGB ビデオを示す。サブタイプの一覧については、「メディア タイプ」を参照すること。
  • pbFormat: フォーマットを詳しく記述する構造体を指すポインタ。フォーマット構造体は、ビデオ画像の幅と高さやオーディオ サンプルのサンプリング レートなどの情報を指定する。メディア タイプが異なれば、使用するフォーマット構造体も異なる。ほとんどのビデオ データは、VIDEOINFOHEADER 構造体を使用する。オーディオ データは、WAVEFORMATEX 構造体を使用する。
  • formattype: pbFormat に格納されているフォーマット構造体を指定する。

メディア タイプは、formattype メンバの値 GUID_NULL によって表される NULL フォーマット構造体を持っていることがある。NULL フォーマットは、DMO が、指定されたメディア タイプの一定の範囲内のフォーマットを受け入れられることを示す。たとえば、PCM オーディオを必要とするストリームは、一定の範囲のサンプリング レートを受け入れることがある。したがって、そのストリームは、メジャー タイプを MEDIATYPE_Audio に、サブタイプを MEDIASUBTYPE_PCMAudio にして、NULL フォーマットを返す。

アプリケーションは、MoFreeMediaType 関数を呼び出して pbFormat メンバを解放する必要がある。

手順 2: メディア タイプの設定

DMO の優先メディア タイプがわかったら、IMediaObject::SetInputType メソッドと IMediaObject::SetOutputType メソッドを呼び出して、各ストリームのメディア タイプを設定する。

DMO が報告するすべてのメディア タイプの組み合わせが有効であるとは限らない。たとえば、出力タイプを入力タイプに合わせなければならないことがある。DMO_SET_TYPEF_TEST_ONLY フラグを設定して SetInputType または SetOutputType を呼び出すことにより、メディア タイプをテストできる。デコーダの場合は、通常、まず入力タイプを設定し、次に出力タイプを選択する。エンコーダの場合は、まず出力タイプを設定し、次に入力タイプを選択する。

1 つのストリームの設定が別のストリームに影響を及ぼすことがあるため、前に設定したメディア タイプを消去する必要が生じることがある。これを行うには、DMO_SET_TYPEF_CLEAR フラグを設定して SetInputType または SetOutputType を呼び出す。

手順 3: バッファの割り当て

メディア タイプを設定したら、各ストリームのバッファ要件を DMO に問い合わせる。バッファ要件はメディア タイプによって異なることがある。各ストリームについて、IMediaObject::GetInputSizeInfo メソッドまたは IMediaObject::GetOutputSizeInfo メソッドを呼び出す。これらのメソッドは、以下の 3 つの値を返す。

  • バイト単位の最小バッファ サイズ。
  • 設定されていれば、アラインメント要件。開始アドレスが、指定された特定の整数の倍数になっていれば、バッファは "アライン" されている。
  • 入力バッファの場合は、DMO がルックアヘッド用に保持するデータの最大量。一部の DMO は、データを処理するために複数の入力バッファを保持する必要がある。ルックアヘッド値は、この要件を指定する。

これらの要件を満たすのに十分なバッファを割り当てる必要がある。

サイズ要件のほかに、入力ストリームでは、各バッファにサンプル全体または 1 つのサンプルだけが含まれていることや、各バッファが一定のサンプル サイズを使用することが必要とされることがある。これらの要件を調べるには、IMediaObject::GetInputStreamInfo メソッドを呼び出す。

手順 4: 入力の処理

この時点で、入力バッファを DMO に配布できる。

各入力ストリームについて、1 つ以上のバッファにメディア データを格納する。データを直接バッファに書き込むことも、別の DMO の出力バッファを使うこともできる。ProcessInput メソッドを呼び出して、各バッファを配布する。通常、DMO はバッファの参照カウントを保持する。DMO は、生成できるすべての出力を生成したとき、またはアプリケーションが DMO をフラッシュしたときに、バッファを解放する。DMO がバッファを解放するまで、バッファを再利用しないこと。

入力ストリームがデータをこれ以上受け入れられるかどうかを判別するには、IMediaObject::GetInputStatus メソッドを呼び出す。ストリームがデータをこれ以上受け入れられる場合、メソッドは DMO_INPUT_STATUSF_ACCEPT_DATA フラグを返す。

手順 5: 出力の処理

ProcessInput は一度に 1 つずつ入力バッファを配布するが、ProcessOutput はいっぺんにすべての出力ストリームの出力を生成する。アプリケーションは、各出力ストリームに 1 つの構造体を割り当てて、DMO_OUTPUT_DATA_BUFFER 構造体の配列を渡す。構造体には、アプリケーションが割り当てた出力バッファおよび DMO がデータを格納するさまざまなフィールドが含まれている。

ProcessOutput メソッドにより、DMO は、指定された出力バッファのサイズの範囲内で、できるだけ多くのデータを生成する。すべてのデータを処理するまえに出力バッファがいっぱいになった場合、DMO は構造体の dwStatus メンバの DMO_OUTPUT_DATA_BUFFERF_INCOMPLETE フラグを設定する。メソッドが終了したら、各構造体にこのフラグがあるかどうかを確認する。フラグがある場合は、もう一度 ProcessOutput を呼び出す。

ストリーミングが始まると、DMO は常に入力を受け入れるか、出力を生成するか、その両方を行うことができる。したがって、GetInputStatus が DMO_INPUT_STATUSF_ACCEPT_DATA フラグを返すか、ProcessOutput が DMO_OUTPUT_DATA_BUFFERF_INCOMPLETE フラグを返す。アプリケーションは、これらのフラグの有無をテストし、ProcessInput または ProcessOutput を呼び出すことによって、データの流れを維持する。

手順 6: 途切れ (discontinuity) の通知

使用できるすべての入力データを特定の入力ストリームに配布したら、IMediaObject::Discontinuity メソッドを呼び出す。DMO は、残っている出力の処理が終わるまで、そのストリームに対する入力をそれ以上受け入れない。

破棄可能ストリームとオプション ストリーム

DMO は、出力ストリームの一部を破棄可能またはオプション ストリームとして指定できる。

  • "破棄可能" ストリームには、アプリケーションが完全に破棄できる、または一部のサンプルについて破棄できるデータが含まれている。
  • "オプション" ストリームは、一部のアプリケーションしか必要としない、または、主ストリームに関する追加情報が含まれた二次的なストリームである。

ストリームが破棄可能またはオプションであるかどうかを問い合わせるには、IMediaObject::GetOutputStreamInfo メソッドを呼び出し、pdwFlags パラメータをチェックする。DMO_OUTPUT_STREAMF_DISCARDABLE フラグはストリームが破棄可能であることを示し、DMO_OUTPUT_STREAMF_OPTIONAL フラグはストリームがオプション ストリームであることを示す。一般的に、少なくとも 1 つのストリームは、オプション ストリーム以外のストリームでなければならない。

IMediaObject::ProcessOutput メソッドを呼び出すときは、dwFlags パラメータの DMO_PROCESS_OUTPUT_DISCARD_WHEN_NO_BUFFER フラグを設定することによって、1 つ以上のストリームのデータを破棄できる。破棄したい個々のストリームについて、DMO_OUTPUT_DATA_BUFFER 構造体の pBuffer メンバを NULL に設定する。DMO は、以下の操作によって、これらのストリームのデータの破棄を試みる。

  • ストリームが破棄可能またはオプションの場合は、DMO がデータを破棄することが保証される。
  • それ以外の場合、DMO は、可能であればデータを破棄する。ただし、DMO がデータを破棄することは保証されない。

pBuffer メンバは NULL であるが、DMO_PROCESS_OUTPUT_DISCARD_WHEN_NO_BUFFER フラグを設定しなかった場合、DMO は、ストリームが破棄可能またはオプションであっても、データを破棄しない。pBuffer は NULL であるが、データが破棄されなかった場合、DMO は、ストリームにデータが残っていることを示す DMO_OUTPUT_DATA_BUFFERF_INCOMPLETE フラグを送る。出力ストリームを処理した後、その出力ストリームを破棄しないと、DMO がほかの出力ストリームのデータを生成できなくなることがある。

オプション ストリームを絶対に使用しない場合は、オプション ストリームのメディア タイプを設定する必要はない。破棄可能なストリームの場合は、これと異なる。破棄可能なストリームのメディア タイプは、必ず設定する必要がある。オプション ストリームと破棄可能ストリームの機能上の相違は、この点だけである。

インプレイス DMO

一部のデータ変換は、データを直接変更することによって行われる。これは、"インプレイス" 処理と呼ばれる。多くのオーディオ エフェクトやビデオ エフェクトは、インプレイスで行うことができる。インプレイス処理は、別のバッファにデータをコピーする方法より効率がよい。データをインプレイスで処理するには、ProcessInput と ProcessOutput を別々に呼び出す代わりに、IMediaObjectInPlace::Process メソッドだけを呼び出す。入力データが含まれたバイトの配列を渡す。メソッドが終了すると、バイト配列には出力データが格納される。

IMediaObjectInPlace をサポートする DMO は、すべての IMediaObject メソッドもサポートする必要がある。インプレイス処理を使用するか、別々の入力バッファと出力バッファを作成するかは、選択できる。ただし、2 つの種類の処理を混在させないこと。Process を呼び出すときは、ProcessInput または ProcessOutput を呼び出してはいけないし、その逆を行ってもいけない。

インプレイス DMO は、入力が停止した後で、追加の出力を生成することがある。これは、"エフェクト テール" と呼ばれる。たとえば、残響エフェクトは、入力が無音になった後も継続する。DMO がエフェクト テールを生成する場合、アプリケーションは、テールが完全に処理されるまで、入力バッファをゼロにして Process メソッドを呼び出す必要がある。詳細については、「IMediaObjectInPlace::Process」を参照すること。


DMO とメディア タイプ

メディア タイプとは、メディア データのストリームに関連付けられたフォーマットの説明である。ここでは、Microsoft® DirectX® Media Objects (DMO) によるメディア タイプの処理方法について説明する。これは主にカスタム DMO を作成する開発者向けの内容である。DMO を使用するアプリケーションについては、「DirectX Media Object の使用」を参照すること。

ここでは、以下の項目について説明する。

  • 概要
  • レジストリ内のメディア タイプ
  • 優先されるメディア タイプ
  • メディア タイプの設定
  • 使用例

概要

メディア タイプを記述する情報は大別して次の 3 つである。

  • メジャー タイプ:オーディオ、ビデオなど、データの大まかな分類を定義するグローバル一意識別子 (GUID)。
  • サブタイプ:ビデオ データ用 24 ビット RGB など、メディア タイプのより詳細な部分を定義する GUID。
  • フォーマット ブロック:フォーマットを詳細に指定する、タイプ固有の構造体。

詳細については、DMO_MEDIA_TYPE 構造体を参照すること。

アプリケーションがまず DMO のインスタンスを作成する時点では、DMO 内のストリームには特定のメディア タイプが指定されていない。アプリケーションが DMO を使ってデータを処理できるようになるには、ストリーム全体に対してメディア タイプを指定する必要がある(オプションのストリームは例外である。「破棄可能ストリームとオプション ストリーム」を参照すること)。

特定のストリームに適合するメディア タイプを見つけるために、アプリケーションは DMO に問い合わせる。DMO は利用できるタイプを列挙し、アプリケーションはその中から 1 つを選択する。あるストリームにメディア タイプを設定すると、ほかのストリームで利用できるタイプを変更できる。たとえば、オーディオ エフェクト DMO は一定の範囲のサンプリング レートをサポートするが、出力レートを入力レートに一致させる必要がある。この場合、入力タイプを設定すると、使用できる出力タイプが限定される。

レジストリ内のメディア タイプ

DMORegister 関数は、入力用および出力用のメディア タイプの一覧など、DMO に関する情報をレジストリに追加する。アプリケーションはこの情報を使って、要件に合致する DMO を検索する。この情報は包括的なものであるとは限らない。多くの場合、DMO がサポートする主なタイプのみを含めることになる。

レジストリ情報には入力タイプと出力タイプの一覧が設定されるが、個別のストリームは区別されない。たとえば、DMO がオーディオとビデオで別個の入力ストリームを持つ場合、レジストリ情報には、入力タイプとしてその両方が設定されることになる。

DMORegister 関数の場合、メディア タイプは DMO_PARTIAL_MEDIATYPE 構造体で指定される。この点で、DMO_MEDIA_TYPE を使用する IMediaObject インターフェイスとは異なる。DMO_PARTIAL_MEDIATYPE 構造体には、メジャー タイプとサブタイプを表す 2 つのフィールドのみが含まれる。フォーマット ブロック用のフィールドはない。多くの場合、フォーマットには、ビデオ イメージの高さと幅など、レジストリに格納するには向かない詳細な情報が含まれる。

優先されるメディア タイプ

サポートされるタイプを DMO に問い合わせるために、アプリケーションは IMediaObject::GetInputType メソッドと IMediaObject::GetOutputType メソッドを呼び出す。これら 2 つのメソッドは、指定されたストリームで優先されるタイプを優先順に列挙する。ストリームで優先されるタイプは、アプリケーションがほかのストリームにメディア タイプを設定するときに動的に変更できる。たとえば、優先される出力タイプを入力タイプに応じて変更できる (またはその逆も可)。ストリームはほかのストリームにタイプが指定されるまで優先タイプを持たないこともある。ただし、DMO は優先タイプをこの方法で更新する必要はない。アプリケーションは、受け取るタイプがすべて有効であるとは仮定できない。このため、SetInputType メソッドと SetOutputType メソッドは特定のタイプを検査するためのフラグをサポートしている。

詳細に指定されたメディア タイプは、詳細すぎて優先タイプとして使用しにくいことがある。より一般的なタイプを示すために、DMO は不完全なタイプを返すことができる。メディア タイプのメジャー タイプ、サブタイプ、またはフォーマット タイプに値 GUID_NULL が設定されている場合、メディア タイプは不完全である。GetInputType メソッドと GetOutputType メソッドでは通常、フォーマット タイプを GUID_NULL に設定する。

アプリケーションがすべての入力タイプを設定した後でも、DMO は通常、各出力ストリームに対して 1 つ以上の完全なタイプを返す必要がある。完全なタイプを設定すると、機能の検査やアプリケーションでは、そのタイプを妥当な既定値として使用できる(一部のメディア タイプはフォーマット タイプがなくても完全であることに注意)。SDK に付属する DMO テスト アプリケーションは、この方法で動作する DMO に依存している (「DMO テスト アプリケーション」を参照すること)。

メディア タイプの設定

ストリームに対してタイプをテスト、設定、または消去するために、アプリケーションは IMediaObject::SetInputType メソッドと IMediaObject::SetOutputType メソッドを使う。DMO がデータを正しく処理できるように、タイプは詳細に指定する必要がある。DMO は各ストリームについて、提案されたタイプがほかのストリームとの互換性を備えていることを検証する必要がある。DMO_SET_TYPEF_CLEAR フラグを使ってストリームのタイプを消去すると、アプリケーションは元の状態に戻って別の組み合わせを試すことができる。

使用例

次の例では、いくつかの典型的なシナリオを用いて、これまでの説明を具体的に示す。

デコーダ

一般的なビデオ デコーダでは、出力フォーマットは入力フォーマットにより部分的に決定される。たとえば、出力ストリームは通常、入力ストリームと同じフレーム レートおよびビデオ サイズを持つ必要がある。デコーダ用のあるオプションは、入力タイプが設定されるまで出力タイプを返さないことになっている。別のオプションは、フォーマット ブロックを持たない不完全なタイプのセットを列挙することになっている。その場合、サブタイプを使って、16 ビット RGB、24 ビット RGB など、サポートされる非圧縮タイプを指定する。

また、ビデオ デコーダは通常、入力タイプを設定する前に出力タイプを設定するアプリケーションはサポートしない。多くの場合、既知の入力フォーマットからデコードすることになるので、この制限は妥当である。

オーディオ レコーダでは、サポートする出力フォーマット群が固定されていることがある。このような場合、アプリケーションが入力フォーマットを設定する前に、出力フォーマットを列挙できる。

コンプレッサ

通常、ビデオ コンプレッサは、アプリケーションが入力フォーマットを設定するまで、優先される出力フォーマットを詳細に指定することはできない (その逆も同様)。その代わりに、フォーマット ブロックを持たない不完全なタイプを返すことになる。オーディオ圧縮とビデオ圧縮の両方で、アプリケーションは、出力ビット レートなどさまざまなフォーマット パラメータを制御する必要がある。ただし、入力タイプが設定されている場合は、前に説明した理由から、コンプレッサは完全な出力タイプを 1 つ以上列挙することになる。


DirectShow アプリケーションでの DMO の使い方

ここでは、Microsoft® DirectShow® アプリケーションで Microsoft® DirectX® Media Object (DMO) を使用する方法を説明する。DirectShow の外で DMO を使用する方法については、「DirectX Media Object の使用」を参照すること。

次のトピックスがある。

  • DirectShow での DMO の概要
  • DMO ラッパー フィルタの使い方
  • システム デバイス列挙子を使った DMO の検索

DirectShow での DMO の概要

DMO ラッパー フィルタを利用すれば、DirectShow アプリケーションは、フィルタ グラフ内で DMO を使用できる。このフィルタは、DMO をラップし、DMO とのデータの受け渡しなど、DMO を使用する際のすべての細かい作業を処理する。また、このフィルタは DMO を集成するため、アプリケーションは DMO が公開するすべての COM インターフェイスをフィルタに問い合わせることができる。

ただし、すべてのストリーム制御は、アプリケーションとフィルタの間、またはアプリケーションとフィルタ グラフ マネージャの間で行う必要がある。DMO の状態を変更する可能性がある DMO インターフェイスのメソッドを呼び出してはいけない。たとえば、ストリームのメディア タイプの設定、バッファの処理、DMO のフラッシュ、DMO のロック、品質コントロールの有効化または無効化、またはビデオ最適化の設定を行ってはいけない。DMO ラッパー フィルタは DMO のすべてのストリーミングを処理するため、これらのメソッドを直接呼び出すとエラーが発生することがある。

DMO をフィルタ グラフに追加するには 2 つの方法がある。

  • 使用する特定の DMO のクラス識別子 (CLSID) がわかっていれば、その DMO で DMO ラッパー フィルタを初期化することができる。
  • それ以外の場合は、システム デバイス列挙子を使って、DMO および DirectShow フィルタを含むデバイスのカテゴリ全体を列挙することができる。

以下では、それぞれの方法について説明する。

DMO ラッパー フィルタの使い方

まず、DMO ラッパー フィルタのインスタンスを作成する。DMO ラッパー フィルタに IDMOWrapperFilter インターフェイスを問い合わせる。次に、IDMOWrapperFilter::Init メソッドを呼び出す。このメソッドは、DMO の CLSID および DMO のカテゴリの GUID を受け取る。

DMOEnum 関数を使って、ユーザーのシステムに登録されている DMO を列挙できる。DMO は、DirectShow フィルタに使われるカテゴリ GUID とは異なるカテゴリ GUID を使って登録される。DMO カテゴリの一覧については、「カテゴリ GUID」を参照すること。

次のコードは、IDMOWrapperFilter インターフェイスの使い方を示している。

// IMediaObject

// DMO ラッパー フィルタを作成する。
IBaseFilter *pFilter;
HRESULT hr = CoCreateInstance(CLSID_DMOWrapperFilter, NULL,
    CLSCTX_INPROC, IID_IBaseFilter, (void **)&pFilter);

if (SUCCEEDED(hr))
{
    IDMOWrapperFilter *pWrap;
    hr = pFilter->QueryInterface(IID_IDMOWrapperFilter, (void **)&pWrap);

    if (SUCCEEDED(hr)) {     // フィルタを初期化。
        hr = pWrap->Init(CLSID_MyDMO, CLSID_MyDMOCategory);
        pWrap->Release();
    }

    if (SUCCEEDED(hr)) {     // フィルタをグラフに追加。
        hr = pGraph->AddFilter(pFilter, L"My DMO");
    }
    pFilter->Release();
}

システム デバイス列挙子を使った DMO の検索

システム デバイス列挙子は、一部の DirectShow デバイス カテゴリを列挙するときに DMO も列挙する。システム デバイス列挙子は、以下の DMO カテゴリを 同等の DirectShow カテゴリにマップする。

DMO カテゴリ | 同等の DirectShow カテゴリ
DMOCATEGORY_AUDIO_ENCODER | CLSID_AudioCompressorCategory
DMOCATEGORY_AUDIO_DECODER | CLSID_LegacyAmFilterCategory
DMOCATEGORY_VIDEO_ENCODER | CLSID_VideoCompressorCategory
DMOCATEGORY_VIDEO_DECODER | CLSID_LegacyAmFilterCategory

さらに、システム デバイス列挙子を使って、DMOCATEGORY_AUDIO_EFFECT および DMOCATEGORY_VIDEO_EFFECT を含むすべての DMO カテゴリを列挙できる。システム デバイス列挙子の使い方の詳細については、「システム デバイス列挙子の使用」を参照すること。IMoniker::BindToObject メソッドは、DMO を DMO ラッパー フィルタで自動的にラップする。


DMO の関連情報

ここには、Microsoft® DirectX® Media Object (DMO) に関連するすべての情報が記載されている。

  • インターフェイス
  • 構造体
  • 列挙型
  • 関数
  • DMO エラー コード
  • グローバルに一意な識別子 (GUID)
  • DMO 基底クラス リファレンス


インターフェイス

ここでは、すべての Microsoft® DirectX® Media Object (DMO) COM インターフェイスおよび各インターフェイスが備えるメソッドの参照エントリを示す。

  • IDMOQualityControl
  • IDMOVideoOutputOptimizations
  • IEnumDMO
  • IMediaBuffer
  • IMediaObject
  • IMediaObjectInPlace


IDMOQualityControl インターフェイス

Microsoft® DirectX® Media Object (DMO) の品質コントロールをサポートする。

DMO が遅延サンプルに対応できる場合、DMO はこのインターフェイスを公開する。品質コントロールが有効になっていると、DMO は、必要に応じて遅延サンプルを破棄し、サンプルを予定どおりに処理しようとする。品質コントロールが無効になっていると、DMO はすべてのサンプルを処理する。デフォルトでは、品質コントロールは無効になっている。

アプリケーションは、このインターフェイスを使って品質コントロールを有効または無効にする。メディア データをリアルタイムで表示しているときは、品質コントロールを使用した方がよい。品質コントロールを有効にすると DMO がサンプルを破棄する可能性があるため、データをファイルにキャプチャしている場合は、品質コントロールを有効にしないこと。サンプルの遅延はファイル キャプチャでは問題にならないし、データの欠損を避けた方がよい。

品質コントロールを使用するには、次の手順を実行する。

  1. 処理の対象となる最も早いサンプルを基準時間にして、SetNow メソッドを呼び出す。
  2. DMO_QUALITY_STATUS_ENABLED フラグを設定して SetStatus メソッドを呼び出す。

品質コントロールを無効にするには、フラグを設定せずに SetStatus を呼び出す。

Vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスを指すポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IDMOQualityControl メソッド | 説明
SetNow | DMO がデータを配布する必要がある最も早いタイム スタンプを指定する。
SetStatus | 品質コントロールを有効または無効にする。
GetStatus | 品質コントロールがアクティブかどうかを判別する。

IDMOQualityControl::SetNow

IDMOQualityControl インターフェイス

DMO が配布する最も早いタイム スタンプを指定する。

構文

HRESULT SetNow(
    REFERENCE_TIME rtNow
);

パラメータ

rtNow
[in] 配布する最も早いタイム スタンプを指定する基準時間。

戻り値

HRESULT 値を返す。以下の値をとる。

S_OK | 成功
E_FAIL | 失敗

注意

品質コントロールが有効になっていると、DMO は、タイム スタンプが rtNow 未満のすべてのサンプルを破棄する。タイム スタンプが rtNow 以降のサンプルは、できる限り効率的に処理される。実装によっては、ペースを保つために DMO が一部のサンプルをドロップすることがある。

品質コントロールが無効になっていると、このメソッドは直ちには効果を及ぼさない。ただし、DMO は指定された基準時間を保存しておく。後で品質コントロールが有効になった場合、DMO はこの値を使用する。品質コントロールを有効にするには、SetNow メソッドを呼び出す。

入力されるサンプルにタイム スタンプがない場合、DMO は品質コントロールを実行しない。アプリケーションは、IMediaObject::ProcessInput メソッドでタイム スタンプを設定する。

IDMOQualityControl::SetStatus

IDMOQualityControl インターフェイス

品質コントロールを有効または無効にする。

構文

HRESULT SetStatus(
DWORD dwFlags
);

パラメータ

dwFlags
[in] 品質コントロールを有効にするか、無効にするかを指定する値。品質コントロールを有効にするには DMO_QUALITY_STATUS_ENABLED を指定し、品質コントロールを無効にするにはゼロを指定する。

戻り値

HRESULT 値を返す。以下の値をとる。

S_OK | 成功。
E_INVALIDARG | 無効な引数。

注意

品質コントロールが有効になっている場合、DMO はサンプルを予定どおりに配布しようとする。必要な場合、DMO は遅延サンプルをスキップすることができる。品質コントロールが無効になっていると、DMO はすべてのサンプルを配布する。品質コントロールを有効にする場合は、SetNow メソッドを呼び出して、DMO が処理する必要がある最も早いタイム スタンプを指定すること。そうしないと、SetStatus の呼び出しは成功するが、DMO は品質コントロールを実行しない。

デフォルトでは、品質コントロールは無効になっている。

IDMOQualityControl::GetStatus

IDMOQualityControl インターフェイス

品質コントロールがアクティブかどうかを判別する。

構文

HRESULT GetStatus(
DWORD *pdwFlags
);

パラメータ

pdwFlags
[out] 品質コントロールの状態を受け取る変数を指すポインタ。品質コントロールが無効になっている場合の値はゼロである。品質コントロールが有効になっている場合の値は DMO_QUALITY_STATUS_ENABLED である。

戻り値

HRESULT 値を返す。以下の値をとる。

S_OK | 成功。
E_POINTER | NULL ポインタ値。


IDMOVideoOutputOptimizations インターフェイス

Microsoft® DirectX® Media Object (DMO) のビデオ最適化をサポートする。

アプリケーションは、このインターフェイスを使って、DMO との間でビデオ出力最適化をネゴシエートできる。DMO は、アプリケーションからのサポートを必要とする最適化を実行できるときに、このインターフェイスを公開する。アプリケーションは、DMO の優先機能を DMO に照会し、その機能を提供することを承諾または拒否することができる。DMO は、アプリケーションが最適化を拒否した場合でも出力を処理する必要がある。

たとえば、ビデオ デコーダは、前の出力フレームにデルタを適用することによって出力フレームを生成することがある。照会を受けると、ビデオ デコーダは、出力バッファを使って前のフレームを供給するようにアプリケーションに要求する。アプリケーションはこの要求を承諾することも拒否することもできる。

ビデオ最適化は、出力ストリームごとに個別にネゴシエートされる。

以下の疑似コードはアプリケーションが DMO とネゴシエートする方法を示している。

IDMOVideoOutputOptimizations *pVidOpt;
// DMO に対して IDMOVideoOutputOptimizations を照会する (表示されていない) 。

BOOL  bWantsPreviousBuffer = FALSE;
DWORD wFlags;
pVidOpt->QueryOperationModePreferences(0,&dwFlags);

if (dwFlags & DMO_VOSF_NEEDS_PREVIOUS_SAMPLE)
{
    // 要求を承諾する。
    pVidOpt->SetOperationMode(0, DMO_VOSF_NEEDS_PREVIOUS_SAMPLE);
    bWantsPreviousBuffer = TRUE;
}

// ループ処理
while (there is input)
{
    ProcessInput(0, ...);
    if (bWantsPreviousBuffer)
pDMO->ProcessOutput(0, ...) // 前回と同じバッファを使う。
    else
pDMO->ProcessOutput(0, ...) // 新しいバッファを使ってもよい。
}

Vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスを指すポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IDMOVideoOutputOptimizations メソッド | 説明
QueryOperationModePreferences | DMO の優先最適化機能を取得する。
SetOperationMode | 現在有効な最適化機能を DMO に通知する。
GetCurrentOperationMode | 現在有効な最適化機能を取得する。
GetCurrentSampleRequirements | アプリケーションが既に承諾した機能がある場合に、次のサンプルを処理するのに必要な最適化機能を取得する。

IDMOVideoOutputOptimizations::QueryOperationModePreferences

IDMOVideoOutputOptimizations インターフェイス

DMO の優先最適化機能を取得する。

構文

HRESULT QueryOperationModePreferences(
ULONG ulOutputStreamIndex,
    DWORD *pdwRequestedCapabilities
);

パラメータ

ulOutputStreamIndex
DMO の出力ストリームのゼロベースのインデックス。
pdwRequestedCapabilities
要求されている DMO の機能を受け取る変数を指すポインタ。返される値は、DMO_VIDEO_OUTPUT_STREAM_FLAGS 列挙の 0 個以上のフラグのビット単位の論理和である。

戻り値

HRESULT 値を返す。以下の値をとる。

S_OK | 成功
DMO_E_INVALIDSTREAMINDEX | 無効なストリーム インデックス
E_POINTER | NULL ポインタ引数

IDMOVideoOutputOptimizations::SetOperationMode

IDMOVideoOutputOptimizations インターフェイス

現在有効な最適化機能を DMO に通知する。

構文

HRESULT SetOperationMode(
ULONG ulOutputStreamIndex,
    DWORD dwEnabledFeatures
);

パラメータ

ulOutputStreamIndex
DMO の出力ストリームのゼロベースのインデックス。
dwEnabledFeatures
DMO_VIDEO_OUTPUT_STREAM_FLAGS 列挙の 0 個以上のフラグのビット単位の論理和。

戻り値

HRESULT 値を返す。以下の値をとる。

S_OK | 成功
DMO_E_INVALIDSTREAMINDEX | 無効なストリーム インデックス
E_INVALIDARG | 無効な引数

注意

このメソッドを呼び出す前に、QueryOperationModePreferences メソッドを呼び出して、DMO が要求している機能を調べる。その後、このメソッドを呼び出して、どの機能を提供するかを DMO に通知する。いずれの機能も提供しない場合は、このメソッドを呼び出す必要はない。DMO は、いずれかの機能が提供されるものとは見なさない。

アプリケーションは、承諾した機能をすべて提供する必要がある。ただし、一部の機能については、DMO がすべてのサンプルについて機能を要求しないことがある。DMO が次のサンプルについて省略できる機能があるかどうかを調べるには、GetCurrentSampleRequirements メソッドを呼び出す。これにより、DMO は、1 つのサンプルに対して、承諾済みの機能を放棄することができる。

ストリーミングが始まる前に、さらにこのメソッドを呼び出すと、前の呼び出しはオーバーライドされる。複数の機能を設定するには、1 回のメソッド呼び出しで機能を設定する必要がある。ストリーミングが始まると、このメソッドはエラーを返す。ストリーミングは、アプリケーションが少なくとも 1 つの入力ストリームに対して IMediaObject::ProcessInput を呼び出したときに始まる。

ストリーミングが終了すれば、アプリケーションは機能をネゴシエートできる。ストリーミングは、アプリケーションが IMediaObject::Flush メソッドを呼び出したとき、または、すべての入力ストリームに対して IMediaObject::Discontinuity を呼び出した後、残っているすべての出力を処理したときに終了する。

IDMOVideoOutputOptimizations::GetCurrentOperationMode

IDMOVideoOutputOptimizations インターフェイス

現在有効な最適化機能を取得する。

構文

HRESULT GetCurrentOperationMode(
ULONG ulOutputStreamIndex,
    DWORD *pdwEnabledFeatures
);

パラメータ

ulOutputStreamIndex
DMO の出力ストリームのゼロベースのインデックス。
pdwEnabledFeatures
現在の機能を受け取る変数を指すポインタ。返される値は、DMO_VIDEO_OUTPUT_STREAM_FLAGS 列挙の 0 個以上のフラグのビット単位の論理和である。

戻り値

HRESULT 値を返す。以下の値をとる。

S_OK | 成功
DMO_E_INVALIDSTREAMINDEX | 無効なストリーム インデックス
E_POINTER | NULL ポインタ引数

IDMOVideoOutputOptimizations::GetCurrentSampleRequirements

IDMOVideoOutputOptimizations インターフェイス

アプリケーションが既に承諾した機能がある場合に、次のサンプルを処理するのに必要な最適化機能を取得する。

構文

HRESULT GetCurrentSampleRequirements(
ULONG ulOutputStreamIndex,
    DWORD *pdwRequestedFeatures
);

パラメータ

ulOutputStreamIndex
DMO の出力ストリームのゼロベースのインデックス。
pdwRequestedFeatures
必要な機能を受け取る変数を指すポインタ。返される値は、DMO_VIDEO_OUTPUT_STREAM_FLAGS 列挙の 0 個以上のフラグのビット単位の論理和である。

戻り値

HRESULT 値を返す。以下の値をとる。

S_OK | 成功
DMO_E_INVALIDSTREAMINDEX | 無効なストリーム インデックス
E_POINTER | NULL ポインタ引数

注意

アプリケーションは、SetOperationMode メソッドを呼び出した後、承諾したすべての機能を提供する必要がある。ただし、一部の機能については、DMO がすべてのサンプルに対して必要としないことがある。DMO は、このメソッドを利用して、1 つのサンプルに対して、承諾済みの機能を放棄することができる。

アプリケーションは、サンプルを処理する前にこのメソッドを呼び出す。DMO は、次のサンプルを処理するために特定の機能を必要としない場合、その機能に対応するフラグを pdwRequestedFeatures パラメータから削除する。次のサンプルに限って、アプリケーションは、その機能を無視できる。このメソッドの結果は、IMediaObject::ProcessOutput メソッドに対する次の呼び出しに対してのみ有効である。

DMO は、SetOperationMode メソッドで承諾されたフラグのみを返す。つまり、このメソッドを使って新しい機能を動的に有効にすることはできない。


IEnumDMO インターフェイス

このインターフェイスは、Microsoft® DirectX® Media Object (DMO) を列挙するためのメソッドを提供する。このインターフェイスは、OLE 列挙インターフェイスに基づいている。詳細については、Platform SDK の「IEnumXXXX」を参照すること。

登録されている DMO を列挙するには、DMOEnum 関数を呼び出す。

Vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスを指すポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IEnumDMO メソッド | 説明
Next | 列挙シーケンス内の指定された数のアイテムを取得する。
Skip | 列挙シーケンス内の指定された数のアイテムをスキップする。
Reset | 列挙シーケンスを先頭にリセットする。
Clone | 実装されていない。

IEnumDMO::Next

IEnumDMO インターフェイス

列挙シーケンス内の指定された数のアイテムを取得する。

構文

HRESULT Next(
    DWORD cItemsToFetch,
    CLSID *pCLSID,
    WCHAR **Names,
    DWORD *pcItemsFetched
);

パラメータ

cItemsToFetch
取得するアイテムの数。
pCLSID
[out] 列挙された DMO の CLSID が格納される、サイズが cItemsToFetch の配列。
Names
[out] 列挙された DMO のフレンドリ名が格納される、サイズが cItemsToFetch の配列。
pcItemsFetched
[out] 実際に取得されたアイテムの数を受け取る変数を指すポインタ。cItemsToFetch が 1 の場合は、NULL を指定できる。

戻り値

HRESULT 値を返す。以下の値をとる。

S_FALSE | 取得したアイテムの数が要求されたアイテムの数より少ない。
S_OK | 要求された数のアイテムを取得した。
E_INVALIDARG | 無効な引数。
E_OUTOFMEMORY | メモリ不足。
E_POINTER | NULL ポインタ引数。

注意

このメソッドが成功すると、pCLSID パラメータと Names パラメータによって返された配列には、CLSID とワイド文字の文字列が格納される。*pcItemsFetched の値は、これらの配列によって返されたアイテムの数を示す。

このメソッドは、要求された数のアイテムを取得すると、つまり、*pcItemsFetched が cItemsToFetch と等しければ、S_OK を返す。それ以外の場合、メソッドは S_FALSE またはエラー コードを返す。

呼び出し元は、Names パラメータによって返された個々の文字列に割り当てられたメモリを、CoTaskMemFree 関数を使って解放する必要がある。

IEnumDMO::Skip

IEnumDMO インターフェイス

列挙シーケンス内の指定された数のアイテムをスキップする。

構文

HRESULT Skip(
    DWORD cItemsToSkip
);

パラメータ

cItemsToSkip
スキップするアイテムの数。

戻り値

スキップされたアイテムの数が cItemsToSkip と一致すれば、S_OK を返す。それ以外の場合は、S_FALSE を返す。

IEnumDMO::Reset

IEnumDMO インターフェイス

列挙シーケンスを先頭にリセットする。

構文

HRESULT Reset(void);

戻り値

S_OK を返す。

IEnumDMO::Clone

IEnumDMO インターフェイス

このメソッドは実装されていない。

構文

HRESULT Clone(
IEnumDMO **ppEnum
);

戻り値

E_NOTIMPL を返す。


IMediaBuffer インターフェイス

このインターフェイスは、データ バッファを操作するためのメソッドを備えている。Microsoft® DirectX® Media Object (DMO) に渡されるすべてのバッファは、このインターフェイスを実装する必要がある。

Vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスを指すポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IMediaBuffer メソッド | 説明
SetLength | 現在バッファ内にあるデータの長さを指定する。
GetMaxLength | このバッファに格納できる最大バイト数を取得する。
GetBufferAndLength | バッファとバッファ内の有効なデータのサイズを取得する。

IMediaBuffer::SetLength

IMediaBuffer インターフェイス

現在バッファ内にあるデータの長さを指定する。

構文

HRESULT SetLength(
   DWORD cbLength
);

パラメータ

cbLength
バイト単位で表すデータのサイズ。値はバッファの最大サイズを超えてはいけない。最大サイズを取得するには、GetMaxLength メソッドを呼び出す。

戻り値

成功すれば S_OK を返す。それ以外の場合は、エラーの原因を示す HRESULT 値を返す。

注意

このメソッドは、バッファに割り当てられたサイズではなく、現在バッファ内にある有効なデータのサイズを設定する。

IMediaBuffer::GetMaxLength

IMediaBuffer インターフェイス

このバッファに格納できる最大バイト数を取得する。

構文

HRESULT GetMaxLength(
    DWORD *pcbMaxLength
);

パラメータ

pcbMaxLength
[out] バッファの最大サイズをバイト単位で受け取る変数を指すポインタ。

戻り値

成功すれば S_OK を返す。それ以外の場合は、エラーの原因を示す HRESULT 値を返す。

IMediaBuffer::GetBufferAndLength

IMediaBuffer インターフェイス

バッファとバッファ内の有効なデータのサイズを取得する。

構文

HRESULT GetBufferAndLength(
    BYTE **ppBuffer,
    DWORD *pcbLength
);

パラメータ

ppBuffer
[out] バッファ配列を受け取るポインタのアドレス。pcbLength が NULL でなければ、NULL を指定できる。
pcbLength
[out] 有効なデータのサイズをバイト単位で受け取る変数を指すポインタ。ppBuffer が NULL でなkれば、NULL を指定できる。

戻り値

HRESULT 値を返す。以下の値をとる。

S_OK | 成功
E_POINTER | NULL ポインタ引数

注意

どちらか一方のパラメータを NULL にすることができる。その場合、NULL にしたパラメータは、値を受け取らない。少なくとも 1 つのパラメータは、NULL でない値にする必要がある。両方のパラメータが NULL の場合、メソッドは E_POINTER を返す。

pcbLength パラメータによって返される値は、バッファに割り当てられたサイズではなく、バッファ内の有効なデータのサイズである。バッファに割り当てられたサイズを取得するには、GetMaxLength メソッドを呼び出す。


IMediaObject インターフェイス

このインターフェイスは、Microsoft® DirectX® Media Object (DMO) を操作するためのメソッドを備えている。

Vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスを指すポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IMediaObject メソッド | 説明
GetStreamCount | 入力ストリームと出力ストリームの数を取得する。
GetInputStreamInfo | 指定された入力ストリームに関する情報を取得する。
GetOutputStreamInfo | 指定された出力ストリームに関する情報を取得する。
GetInputType | 指定された入力ストリームの優先メディア タイプを取得する。
GetOutputType | 指定された出力ストリームの優先メディア タイプを取得する。
SetInputType | 入力ストリームのメディア タイプを設定する、または特定のメディア タイプが使用可能かどうかをテストする。
SetOutputType | 出力ストリームのメディア タイプを設定する、または特定のメディア タイプが使用可能かどうかをテストする。
GetInputCurrentType | 前に設定された入力ストリームのメディア タイプがあれば、それを取得する。
GetOutputCurrentType | 前に設定された出力ストリームのメディア タイプがあれば、それを取得する。
GetInputSizeInfo | 指定された入力ストリームのバッファ要件を取得する。
GetOutputSizeInfo | 指定された出力ストリームのバッファ要件を取得する。
GetInputMaxLatency | 指定された入力ストリームの最大待機時間を取得する。
SetInputMaxLatency | 指定された入力ストリームの最大待機時間を設定する。
Flush | 内部でバッファリングされたすべてのデータをフラッシュする。
Discontinuity | 指定された入力ストリームの途切れを知らせる。
AllocateStreamingResources | DMO が必要とするすべてのリソースを割り当てる。
FreeStreamingResources | DMO が割り当てたリソースを解放する。
GetInputStatus | 指定された入力ストリームが入力データをこれ以上受け入れられるかどうかを問い合わせる。
ProcessInput | 指定された入力ストリームにバッファを配布する。
ProcessOutput | 現在の入力データから出力を生成する。
Lock | DMO のロックを取得または解除する。

IMediaObject::GetStreamCount

IMediaObject インターフェイス

入力ストリームと出力ストリームの数を取得する。

構文

HRESULT GetStreamCount(
    DWORD *pcInputStreams,
    DWORD *pcOutputStreams
);

パラメータ

pcInputStreams
[out] 入力ストリームの数を受け取る変数を指すポインタ。NULL は指定できない。
pcOutputStreams
[out] 出力ストリームの数を受け取る変数を指すポインタ。NULL は指定できない。

戻り値

HRESULT 値を返す。以下の値をとる。

S_OK | 成功
E_POINTER | NULL ポインタ引数

注意

DMO は入力ストリームまたは出力ストリームをまったく持っていないことがある。ストリームの数は変わらない。DMO はストリームを動的に追加または削除できない。

IMediaObject::GetInputStreamInfo

IMediaObject インターフェイス

バッファあたりのサンプル数に関する制限、ストリームが入力データに対してルックアヘッドを実行するかどうかなど、入力ストリームに関する情報を取得する。この情報が変わることはない。

構文

HRESULT GetInputStreamInfo(
DWORD dwInputStreamIndex,
DWORD *pdwFlags
);

パラメータ

dwInputStreamIndex
DMO の入力ストリームのゼロベースのインデックス。
pdwFlags
[out] 0 個以上の DMO_INPUT_STREAM_INFO_FLAGS フラグのビット単位の論理和を受け取る変数を指すポインタ。

戻り値

HRESULT 値を返す。以下の値をとる。

S_OK | 成功
DMO_E_INVALIDSTREAMINDEX | 無効なストリーム インデックス
E_POINTER | NULL ポインタ引数

注意

DMO_INPUT_STREAMF_HOLDS_BUFFERS フラグは、DMO が入力データに対してルックアヘッドを実行することを示す。

アプリケーションは、DMO が入力を処理するのに十分なバッファを割り当てる必要がある。バッファ要件を調べるには、GetInputSizeInfo メソッドを呼び出す。

IMediaObject::GetOutputStreamInfo

IMediaObject インターフェイス

ストリームが破棄できるかどうか、ストリームが固定サンプル サイズを使うかどうかなど、出力ストリームに関する情報を取得する。この情報が変わることはない。

構文

HRESULT GetOutputStreamInfo(
DWORD dwOutputStreamIndex,
DWORD *pdwFlags
);

パラメータ

dwOutputStreamIndex
DMO の出力ストリームのゼロベースのインデックス。
pdwFlags
[out] 0 個以上の DMO_OUTPUT_STREAM_INFO_FLAGS フラグのビット単位の論理和を受け取る変数を指すポインタ。

戻り値

HRESULT 値を返す。以下の値をとる。

S_OK | 成功
DMO_E_INVALIDSTREAMINDEX | 無効なストリーム インデックス
E_POINTER | NULL ポインタ引数

IMediaObject::GetInputType

IMediaObject インターフェイス

指定された入力ストリームの優先メディア タイプを取得する。

構文

HRESULT GetInputType(
DWORD dwInputStreamIndex,
DWORD dwTypeIndex,
DMO_MEDIA_TYPE *pmt
);

パラメータ

dwInputStreamIndex
DMO の入力ストリームのゼロベースのインデックス。
dwTypeIndex
使用可能なメディア タイプのセットのゼロベースのインデックス。
pmt
[out] 呼び出し元によって割り当てられた DMO_MEDIA_TYPE 構造体を指すポインタ。メソッドは構造体にメディア タイプを格納する。フォーマット ブロックは NULL になることがある。その場合のフォーマット タイプ GUID は GUID_NULL である。

戻り値

HRESULT 値を返す。以下の値をとる。

S_OK | 成功。
DMO_E_INVALIDSTREAMINDEX | 無効なストリーム インデックス。
DMO_E_NO_MORE_ITEMS | タイプ インデックスが範囲外である。
E_OUTOFMEMORY | メモリ不足。
E_POINTER | NULL ポインタ引数。

注意

このメソッドを呼び出して、入力ストリームの優先メディア タイプを列挙する。DMO は、優先順位に従って、個々のメディア タイプにインデックス値を割り当てる。最優先タイプのインデックスは 0 になる。すべてのタイプを列挙するには、メソッドが DMO_E_NO_MORE_ITEMS を返すまで、タイプ インデックスをインクリメントしながら、呼び出しを繰り返す。

メソッドが成功したら、MoFreeMediaType を呼び出してフォーマット ブロックを解放する。

メディア タイプを設定するには、SetInputType メソッドを呼び出す。1 つのストリームのメディア タイプを設定すると、別のストリームの優先タイプが変わることがある。実際、ストリームは、別のストリームのタイプが設定されるまで、優先タイプを持たないことがある。たとえば、デコーダは、入力タイプが設定されるまで優先出力タイプを持たないことがある。ただし、DMO は、この方法で動的に優先タイプを更新する必要はない。したがって、このメソッドによって返されるタイプが有効であることは保証されない。返されるタイプを SetInputType メソッドで使用すると、失敗することがある。逆に、DMO が、サポートするすべてのメディア タイプを列挙することも保証されない。特定のメディア タイプが使用可能かどうかをテストするには、DMO_SET_TYPEF_TEST_ONLY フラグを設定して SetInputType を呼び出す。

pmt パラメータは NULL を取り得る。この場合、タイプ インデックスが範囲内なら、メソッドは S_OK を返す。それ以外なら、DMO_E_NO_MORE_ITEMS かほかのエラー コードを返す。

IMediaObject::GetOutputType

IMediaObject インターフェイス

指定された出力ストリームの優先メディア タイプを取得する。

構文

HRESULT GetOutputType(
DWORD dwOutputStreamIndex,
DWORD dwTypeIndex,
DMO_MEDIA_TYPE *pmt
);

パラメータ

dwOutputStreamIndex
DMO の出力ストリームのゼロベースのインデックス。
dwTypeIndex
使用可能なメディア タイプのセットのゼロベースのインデックス。
pmt
[out] 呼び出し元によって割り当てられた DMO_MEDIA_TYPE 構造体を指すポインタ。メソッドは構造体にメディア タイプを格納する。フォーマット ブロックは NULL になることがある。その場合のフォーマット タイプ GUID は GUID_NULL である。

戻り値

HRESULT 値を返す。以下の値をとる。

S_OK | 成功。
DMO_E_INVALIDSTREAMINDEX | 無効なストリーム インデックス。
DMO_E_NO_MORE_ITEMS | タイプ インデックスが範囲外である。
E_OUTOFMEMORY | メモリ不足。
E_POINTER | NULL ポインタ引数。

注意

このメソッドを呼び出して、出力ストリームの優先メディア タイプを列挙する。DMO は、優先順位に従って、個々のメディア タイプにインデックス値を割り当てる。最優先タイプのインデックスは 0 になる。すべてのタイプを列挙するには、メソッドが DMO_E_NO_MORE_ITEMS を返すまで、タイプ インデックスをインクリメントしながら、呼び出しを繰り返す。

メソッドが成功したら、MoFreeMediaType を呼び出してフォーマット ブロックを解放する。

メディア タイプを設定するには、SetOutputType メソッドを呼び出す。1 つのストリームのメディア タイプを設定すると、別のストリームの優先タイプが変わることがある。実際、ストリームは、別のストリームのタイプが設定されるまで、優先タイプを持たないことがある。たとえば、デコーダは、入力タイプが設定されるまで優先出力タイプを持たないことがある。ただし、DMO は、この方法で動的に優先タイプを更新する必要はない。したがって、このメソッドによって返されるタイプが有効であることは保証されない。返されるタイプを SetOutputType メソッドで使用すると、失敗することがある。逆に、DMO が、サポートするすべてのメディア タイプを列挙することも保証されない。特定のメディア タイプが使用可能かどうかをテストするには、DMO_SET_TYPEF_TEST_ONLY フラグを設定して SetOutputType を呼び出す。

pmt パラメータは NULL を取り得る。この場合、タイプ インデックスが範囲内なら、メソッドは S_OK を返す。それ以外なら、DMO_E_NO_MORE_ITEMS かほかのエラー コードを返す。

IMediaObject::SetInputType

IMediaObject インターフェイス

入力ストリームのメディア タイプを設定する、またはメディア タイプが使用可能かどうかをテストする。

構文

HRESULT SetInputType(
DWORD dwInputStreamIndex,
const DMO_MEDIA_TYPE *pmt,
DWORD dwFlags
);

パラメータ

dwInputStreamIndex
DMO の入力ストリームのゼロベースのインデックス。
pmt
[in] メディア タイプを指定する DMO_MEDIA_TYPE 構造体を指すポインタ。
dwFlags
DMO_SET_TYPE_FLAGS 列挙の 0 個以上のフラグのビット単位の論理和。

戻り値

HRESULT 値を返す。以下の値をとる。

S_OK | メディア タイプが正しく設定された、または使用可能である。
S_FALSE | メディア タイプが使用できない。
DMO_E_INVALIDSTREAMINDEX | 無効なストリーム インデックス。
DMO_E_TYPE_NOT_ACCEPTED | メディア タイプが受け入れられなかった。

注意

このメソッドを呼び出して、入力ストリームのメディア タイプをテスト、設定または消去する。

  • メディア タイプを設定せずにテストするには、DMO_SET_TYPEF_TEST_ONLY フラグを使用する。メディア タイプが使用できなければ、メソッドは S_FALSE を返す。
  • メディア タイプを設定するには、dwFlags をゼロに設定する。メディア タイプが使用不能であれば、メソッドは DMO_E_TYPE_NOT_ACCEPTED を返す。
  • 現在設定されているメディア タイプを消去するには、DMO_SET_TYPEF_CLEAR フラグを使用し、pmt を NULL に設定する。メソッドが終了すると、ストリームに設定されているメディア タイプはなくなる。DMO は、アプリケーションが新しいメディア タイプを設定するまで、サンプルを処理できない。

現在ほかのストリームに対して設定されているメディア タイプによって、メディア タイプが使用可能かどうかが影響を受けることがある。

IMediaObject::SetOutputType

IMediaObject インターフェイス

出力ストリームのメディア タイプを設定する、またはメディア タイプが使用可能かどうかをテストする。

構文

HRESULT SetOutputType(
DWORD dwOutputStreamIndex,
const DMO_MEDIA_TYPE *pmt,
DWORD dwFlags
);

パラメータ

dwOutputStreamIndex
DMO の出力ストリームのゼロベースのインデックス。
pmt
[in] メディア タイプを指定する DMO_MEDIA_TYPE 構造体を指すポインタ。
dwFlags
DMO_SET_TYPE_FLAGS 列挙の 0 個以上のフラグのビット単位の論理和。

戻り値

HRESULT 値を返す。以下の値をとる。

S_OK | メディア タイプが正しく設定された、または使用可能である。
S_FALSE | メディア タイプが使用できない。
DMO_E_INVALIDSTREAMINDEX | 無効なストリーム インデックス。
DMO_E_TYPE_NOT_ACCEPTED | メディア タイプが受け入れられなかった。

注意

このメソッドを呼び出して、出力ストリームのメディア タイプをテスト、設定または消去する。

  • メディア タイプを設定せずにテストするには、DMO_SET_TYPEF_TEST_ONLY フラグを使用する。メディア タイプが使用できなければ、メソッドは S_FALSE を返す。
  • メディア タイプを設定するには、dwFlags をゼロに設定する。メディア タイプが使用不能であれば、メソッドは DMO_E_TYPE_NOT_ACCEPTED を返す。
  • 現在設定されているメディア タイプを消去するには、DMO_SET_TYPEF_CLEAR フラグを使用し、pmt を NULL に設定する。メソッドが終了すると、ストリームに設定されているメディア タイプはなくなる。ストリームがオプション ストリームでない限り、DMO はアプリケーションが新しいメディア タイプを設定するまで、サンプルを処理できない。

現在ほかのストリームに対して設定されているメディア タイプによって、メディア タイプが使用可能かどうかが影響を受けることがある。

IMediaObject::GetInputCurrentType

IMediaObject インターフェイス

設定された入力ストリームのメディア タイプがあれば、それを取得する。

構文

HRESULT GetInputCurrentType(
DWORD dwInputStreamIndex,
DMO_MEDIA_TYPE *pmt
);

パラメータ

dwInputStreamIndex
DMO の入力ストリームのゼロベースのインデックス。
pmt
[out] 呼び出し元によって割り当てられた DMO_MEDIA_TYPE 構造体を指すポインタ。メソッドは構造体にメディア タイプを格納する。

戻り値

HRESULT 値を返す。以下の値をとる。

S_OK | 成功。
DMO_E_INVALIDSTREAMINDEX | 無効なストリーム インデックス。
DMO_E_TYPE_NOT_SET | メディア タイプが設定されなかった。
E_OUTOFMEMORY | メモリ不足。

注意

呼び出し元は、このメソッドを呼び出す前に、ストリームのメディア タイプを設定する必要がある。メディア タイプを設定するには、SetInputType メソッドを呼び出す。

メソッドが成功したら、MoFreeMediaType を呼び出してフォーマット ブロックを解放する。

IMediaObject::GetOutputCurrentType

IMediaObject インターフェイス

設定された出力ストリームのメディア タイプがあれば、それを取得する。

構文

HRESULT GetOutputCurrentType(
DWORD dwOutputStreamIndex,
DMO_MEDIA_TYPE *pmt
);

パラメータ

dwOutputStreamIndex
DMO の出力ストリームのゼロベースのインデックス。
pmt
[out] 呼び出し元によって割り当てられた DMO_MEDIA_TYPE 構造体を指すポインタ。メソッドは構造体にメディア タイプを格納する。

戻り値

HRESULT 値を返す。以下の値をとる。

S_OK | 成功。
DMO_E_INVALIDSTREAMINDEX | 無効なストリーム インデックス。
DMO_E_TYPE_NOT_SET | メディア タイプが設定されなかった。
E_OUTOFMEMORY | メモリ不足。

注意

呼び出し元は、このメソッドを呼び出す前に、ストリームのメディア タイプを設定する必要がある。メディア タイプを設定するには、SetOutputType メソッドを呼び出す。

メソッドが成功したら、MoFreeMediaType を呼び出してフォーマット ブロックを解放する。

IMediaObject::GetInputSizeInfo

IMediaObject インターフェイス

指定された入力ストリームのバッファ要件を取得する。

構文

HRESULT GetInputSizeInfo(
DWORD dwInputStreamIndex,
DWORD *pcbSize,
    DWORD *pcbMaxLookahead,
DWORD *pcbAlignment
);

パラメータ

dwInputStreamIndex
DMO の入力ストリームのゼロベースのインデックス。
pcbSize
[out] このストリームの入力バッファの最小サイズをバイト単位で受け取る変数を指すポインタ。
pcbMaxLookahead
[out] DMO がルックアヘッド用に保持する最大データ量をバイト単位で受け取る変数を指すポインタ。DMO がストリームに対してルックアヘッドを実行しない場合の値は 0 である。
pcbAlignment
[out] 必要なバッファ アラインメントをバイト単位で受け取る変数を指すポインタ。入力ストリームにアラインメント要件がない場合の値は 1 である。

戻り値

HRESULT 値を返す。以下の値をとる。

S_OK | 成功。
DMO_E_INVALIDSTREAMINDEX | 無効なストリーム インデックス。
DMO_E_TYPE_NOT_SET | メディア タイプが設定されなかった。

注意

バッファ要件は、さまざまなストリームのメディア タイプによって異なることがある。このメソッドを呼び出す前に、SetInputType メソッドと SetOutputType メソッドを呼び出すことによって、各ストリームのメディア タイプを設定する。メディア タイプが設定されていない場合、このメソッドはエラーを返すことがある。

DMO が入力ストリームに対してルックアヘッドを実行する場合、DMO は GetInputStreamInfo メソッドで DMO_INPUT_STREAMF_HOLDS_BUFFERS フラグを返す。DMO は、処理中に、pcbMaxLookahead パラメータが示す数を最大バイト数とするデータを保持する。アプリケーションは、DMO がそれだけの量のデータを保持するのに十分なバッファを割り当てる必要がある。

バッファの開始アドレスが *pcbAlignment の倍数であれば、バッファは "アライン" されている。アラインメントは、2 の累乗でなければならない。マイクロプロセッサによっては、アラインされているバッファに対する読み取り、書き込みの方が、アラインされていないバッファに対する読み取り、書き込みより速い。また、一部のマイクロプロセッサは、アラインされていない読み取りと書き込みをサポートしていない。

IMediaObject::GetOutputSizeInfo

IMediaObject インターフェイス

指定された出力ストリームのバッファ要件を取得する。

構文

HRESULT GetOutputSizeInfo(
DWORD dwOutputStreamIndex,
DWORD *pcbSize,
DWORD *pcbAlignment
);

パラメータ

dwOutputStreamIndex
DMO の出力ストリームのゼロベースのインデックス。
pcbSize
[out] このストリームの出力バッファの最小サイズをバイト単位で受け取る変数を指すポインタ。
pcbAlignment
[out] 必要なバッファ アラインメントをバイト単位で受け取る変数を指すポインタ。出力ストリームにアラインメント要件がない場合の値は 1 である。

戻り値

HRESULT 値を返す。以下の値をとる。

S_OK | 成功。
DMO_E_INVALIDSTREAMINDEX | 無効なストリーム インデックス。
DMO_E_TYPE_NOT_SET | メディア タイプが設定されなかった。

注意

バッファ要件は、各ストリームに対して設定されているメディア タイプによって異なることがある。

このメソッドを呼び出す前に、SetInputType メソッドと SetOutputType メソッドを呼び出すことによって、各ストリームのメディア タイプを設定する。メディア タイプが設定されていない場合、このメソッドはエラーを返すことがある。ただし、ストリームがオプション ストリームであれば、アプリケーションはストリームを使用しないし、ストリームのメディア タイプを設定する必要もない。

バッファの開始アドレスが *pcbAlignment の倍数であれば、バッファは "アライン" されている。 マイクロプロセッサのアーキテクチャによっては、アラインされたバッファに対する読み取り、書き込みの方が、アラインされていないバッファに対する読み取り、書き込みより速い。一部のマイクロプロセッサでは、アラインされていないバッファに対する読み取り、書き込みがサポートされていないため、これを実行するとプログラムがクラッシュすることがある。0 は有効なアラインメントではない。

IMediaObject::GetInputMaxLatency

IMediaObject インターフェイス

指定された入力ストリームの最大待機時間を取得する。

構文

HRESULT GetInputMaxLatency(
DWORD dwInputStreamIndex,
    REFERENCE_TIME *prtMaxLatency
);

パラメータ

dwInputStreamIndex
DMO の入力ストリームのゼロベースのインデックス。
prtMaxLatency
[out] 最大待機時間を受け取る変数を指すポインタ。

戻り値

HRESULT 値を返す。以下の値をとる。

S_OK | 成功。
DMO_E_INVALIDSTREAMINDEX | 無効なストリーム インデックス。
E_FAIL | 失敗。
E_NOTIMPL | 実装されていない。待機時間ゼロと見なす。

待機時間とは、入力ストリーム上のタイム スタンプと、それに対応する出力ストリーム上のタイム スタンプとの差である。最大待機時間は、2 つのタイム スタンプ間で生じる可能性のある最大の差異である。DMO の場合は、次のようにして最大待機時間を調べる。

  • DMO が出力を生成できるようになるまで、入力バッファを処理する。
  • できるだけ多くの出力バッファを処理する。
  • 最大待機時間は、入力タイム スタンプと出力タイム スタンプの間の最大増分 (絶対値) である。

この定義によれば、待機時間にはサンプルを処理する時間は含まれない。また、入力バッファのサイズが要因となる待機時間も含まれない。

DMO が一度に 1 つのサンプルだけを処理する特殊な場合の最大待機時間は、単にタイム スタンプ間の差異である。

待機時間は、サンプルがタイム スタンプを持っており、タイム スタンプが単調増加あるいは単調減少する場合にのみ定義される。最大待機時間は、入力ストリームおよび出力ストリームのメディア タイプによって異なることがある。

IMediaObject::SetInputMaxLatency

IMediaObject インターフェイス

指定された入力ストリームの最大待機時間を設定する。最大待機時間の定義については、「GetInputMaxLatency」を参照すること。

構文

HRESULT SetInputMaxLatency(
DWORD dwInputStreamIndex,
    REFERENCE_TIME rtMaxLatency
);

パラメータ

dwInputStreamIndex
DMO の入力ストリームのゼロベースのインデックス。
rtMaxLatency
最大待機時間。

戻り値

HRESULT 値を返す。以下の値をとる。

S_OK | 成功
DMO_E_INVALIDSTREAMINDEX | 無効なストリーム インデックス
E_FAIL | 失敗
E_NOTIMPL | 実装されていない

IMediaObject::Flush

IMediaObject インターフェイス

内部でバッファリングされたすべてのデータをフラッシュする。

構文

HRESULT Flush(void);

戻り値

成功すれば S_OK を返す。それ以外の場合は、エラーの原因を示す HRESULT 値を返す。

注意

このメソッドが呼び出されると、DMO は以下の操作を行う。

  • 保持しているすべての IMediaBuffer 参照を解放する。
  • メディア バッファのタイム スタンプまたはサンプル長を指定するすべての値を破棄する。
  • メディア サンプルの内容に依存するすべての内部状態を再初期化する。

メディア タイプ、最大待機時間、およびロック状態は変わらない。

メソッドが終了すると、すべての入力ストリームはデータを受け入れる。出力ストリームは、アプリケーションが少なくとも 1 つの入力ストリームに対して ProcessInput メソッドを呼び出すまで、データを生成できない。

IMediaObject::Discontinuity

IMediaObject インターフェイス

指定された入力ストリームの途切れを知らせる。

構文

HRESULT Discontinuity(
    DWORD dwInputStreamIndex
);

パラメータ

dwInputStreamIndex
DMO の入力ストリームのゼロベースのインデックス。

戻り値

HRESULT 値を返す。以下の値をとる。

S_OK | 成功
DMO_E_INVALIDSTREAMINDEX | 無効なストリーム インデックス

注意

途切れは入力の中断に相当する。途切れは、入力データがなくなった、フォーマットが変更された、データにギャップがある、などの理由で発生する。途切れが発生すると、DMO は、保留されているすべてのデータが処理されるまで、そのストリームの入力をそれ以上受け入れなくなる。アプリケーションは、DMO_OUTPUT_DATA_BUFFERF_INCOMPLETE フラグを返すストリームがなくなるまで、ProcessOutput メソッドを呼び出す必要がある。

IMediaObject::AllocateStreamingResources

IMediaObject インターフェイス

DMO が必要とするすべてのリソースを割り当てる。このメソッドの呼び出しは、常に省略できる。

構文

HRESULT AllocateStreamingResources(void);

戻り値

成功すれば S_OK を返す。それ以外の場合は、エラーの原因を示す HRESULT 値を返す。

注意

アプリケーションは、ストリーミング最適化としてこのメソッドを呼び出すことができる。このメソッドを利用して、DMO は、ストリーミングが始まる前に、時間のかかるすべての初期化を実行できる。このメソッドを呼び出す場合は、DMO のメディア タイプを設定した後、最初に ProcessInput または ProcessOutput を呼び出す前に、メソッドを呼び出すこと。

このメソッドは、次の意味でオプションである。

  • DMO がこのメソッドをサポートしない場合、メソッドは S_OK を返す。
  • アプリケーションがこのメソッドを呼び出さない場合、DMO は ProcessInput または ProcessOutput に対する呼び出しの中でリソースを割り当てる。

DMO がこのメソッドをサポートする場合、その DMO は FreeStreamingResources メソッドもサポートする必要がある。

IMediaObject::FreeStreamingResources

IMediaObject インターフェイス

DMO が割り当てたリソースを解放する。このメソッドの呼び出しは、常に省略できる。

構文

HRESULT FreeStreamingResources(void);

戻り値

成功すれば S_OK を返す。それ以外の場合は、エラーの原因を示す HRESULT 値を返す。

注意

このメソッドは、AllocateStreamingResources メソッドが初期化するすべてのリソースを解放する。

DMO がこのメソッドをサポートしない場合、メソッドは S_OK を返す。ストリーミングの最中にこのメソッドを呼び出すと、メソッドは失敗し、DMO はいずれのリソースも解放しない。

メソッドが成功するか、失敗するかにかかわらず、アプリケーションは、DMO に対するほかのメソッドの呼び出しを続けることができる。DMO が前に解放されたリソースを再初期化することが必要になることもある。

IMediaObject::GetInputStatus

IMediaObject インターフェイス

入力ストリームが入力データをこれ以上受け入れられるかどうかを問い合わせる。

構文

HRESULT GetInputStatus(
DWORD dwInputStreamIndex,
    DWORD *dwFlags
);

パラメータ

dwInputStreamIndex
DMO の入力ストリームのゼロベースのインデックス。
dwFlags
[out] ゼロまたは DMO_INPUT_STATUSF_ACCEPT_DATA を受け取る変数を指すポインタ。

戻り値

HRESULT 値を返す。以下の値をとる。

S_OK | 成功
DMO_E_INVALIDSTREAMINDEX | 無効なストリーム インデックス

注意

入力ストリームがデータをこれ以上受け入れる場合、メソッドは、dwFlags パラメータによって DMO_INPUT_STATUSF_ACCEPT_DATA フラグを返す。それ以外の場合、メソッドはこのパラメータをゼロに設定する。ストリームがデータをこれ以上受け入れる場合、アプリケーションは ProcessInput メソッドを呼び出すことができる。

入力ストリームの状態が変わるのは、以下のいずれかのメソッドを呼び出したときに限られる。

  • Discontinuity
  • Flush
  • ProcessInput
  • ProcessOutput

IMediaObject::ProcessInput

IMediaObject インターフェイス

指定された入力ストリームにバッファを配布する。

構文

HRESULT ProcessInput(
DWORD dwInputStreamIndex,
    IMediaBuffer *pBuffer,
DWORD dwFlags,
    REFERENCE_TIME rtTimestamp,
    REFERENCE_TIME rtTimelength
);

パラメータ

dwInputStreamIndex
DMO の入力ストリームのゼロベースのインデックス。
pBuffer
バッファの IMediaBuffer インターフェイスを指すポインタ。
dwFlags
DMO_INPUT_DATA_BUFFER_FLAGS 列挙の 0 個以上のフラグのビット単位の論理和。
rtTimestamp
バッファ内のデータの開始タイムを指定するタイム スタンプ。バッファが有効なタイム スタンプを持っている場合は、dwFlags パラメータで DMO_INPUT_DATA_BUFFERF_TIME フラグを設定する。それ以外の場合、DMO はこの値を無視する。
rtTimelength
バッファ内のデータの時間幅を指定する基準時間。この値が有効である場合は、dwFlags パラメータで DMO_INPUT_DATA_BUFFERF_TIMELENGTH フラグを設定する。それ以外の場合、DMO はこの値を無視する。

戻り値

HRESULT 値を返す。以下の値をとる。

S_FALSE | 処理する出力がない
S_OK | 成功。
DMO_E_INVALIDSTREAMINDEX | 無効なストリーム インデックス。
DMO_E_NOTACCEPTING | データを受け入れられない。

注意

DMO がバッファ内のすべてのデータを処理しない場合、その DMO はバッファの参照カウントを保持する。DMO は、データに対してルックアヘッドを実行する必要がある場合を除いて、すべての出力を生成した後、バッファを解放する。DMO がルックアヘッドを実行するかどうかを調べるには、GetInputStreamInfo メソッドを呼び出す。

このメソッドが DMO_E_NOTACCEPTING を返した場合は、入力ストリームがデータをこれ以上受け入れるようになるまで、ProcessOutput メソッドを呼び出す。ストリームがデータをこれ以上受け入れられるかどうかを調べるには、GetInputStatus メソッドを呼び出す。

メソッドが S_FALSE を返した場合、この入力から出力は生成されていない。その場合、アプリケーションは ProcessOutput を呼び出す必要はない。ただし、この場合、DMO は S_FALSE を返す必要はない。DMO は S_OK を返すことがある。

IMediaObject::ProcessOutput

IMediaObject インターフェイス

現在の入力データから出力を生成する。

構文

HRESULT ProcessOutput(
DWORD dwFlags,
    DWORD cOutputBufferCount,
    DMO_OUTPUT_DATA_BUFFER *pOutputBuffers,
    DWORD *pdwStatus
);

パラメータ

dwFlags
DMO_PROCESS_OUTPUT_FLAGS 列挙の 0 個以上のフラグのビット単位の論理和。
cOutputBufferCount
出力バッファの数。
pOutputBuffers
[in, out] 出力バッファが格納された DMO_OUTPUT_DATA_BUFFER 構造体の配列を指すポインタ。cOutputBufferCount パラメータで配列のサイズを指定する。
pdwStatus
[out] 予約済みの値 (ゼロ) を受け取る変数を指すポインタ。アプリケーションはこの値を無視する必要がある。

戻り値

HRESULT 値を返す。以下の値をとる。

S_FALSE | 出力が生成されなかった。
S_OK | 成功。
E_FAIL | 失敗。
E_INVALIDARG | 無効な引数。
E_POINTER | NULL ポインタ引数。

注意

pOutputBuffers パラメータは、DMO_OUTPUT_DATA_BUFFER 構造体の配列を指す。アプリケーションは、各出力ストリームに対して 1 つの構造体を割り当てる必要がある。GetStreamCount メソッドを呼び出して、出力ストリームの数を調べる。cOutputBufferCount パラメータをその数に設定する。

個々の DMO_OUTPUT_DATA_BUFFER 構造体には、バッファの IMediaBuffer インターフェイスを指すポインタが格納されている。アプリケーションはこれらのバッファを割り当てる。構造体のほかのメンバは、状態フィールドである。メソッドが成功すると、DMO はこれらのフィールドを設定する。メソッドが失敗すると、これらの値は確定しない。

アプリケーションが ProcessOutput を呼び出すと、DMO はできるだけ多くの入力データを処理する。DMO は、各バッファ内のデータの末尾から順に出力データを出力バッファに書き込む。データの末尾を見つけるには、IMediaBuffer::GetBufferAndLength メソッドを呼び出す。DMO が出力バッファの参照カウントを保持することはない。

DMO が格納したデータで出力バッファがいっぱいになった状態で、まだ処理する入力データがある場合、DMO は DMO_OUTPUT_DATA_BUFFER 構造体によって DMO_OUTPUT_DATA_BUFFERF_INCOMPLETE フラグを返す。アプリケーションは、各構造体の dwStatus メンバをテストすることによって、このフラグの有無をチェックする必要がある。

メソッドが S_FALSE を返した場合、出力は生成されていない。ただし、この場合、DMO は S_FALSE を返す必要はない。DMO は S_OK を返すことがある。

データの破棄

dwFlags パラメータで DMO_PROCESS_OUTPUT_DISCARD_WHEN_NO_BUFFER フラグを設定することにより、ストリームのデータを破棄することができる。破棄する各ストリームに対して、DMO_OUTPUT_DATA_BUFFER 構造体の pBuffer メンバを NULL に設定する。

pBuffer が NULL である個々のストリームは、以下のように処理される。

  • DMO_PROCESS_OUTPUT_DISCARD_WHEN_NO_BUFFER フラグが設定されており、かつ、ストリームが破棄可能またはオプション ストリームであれば、DMO はデータを破棄する。
  • フラグは設定されているが、ストリームが破棄可能でもオプション ストリームでもない場合、DMO は可能であればデータを破棄する。DMO がデータを破棄することは保証されない。
  • フラグが設定されていない場合、DMO はそのストリームの出力データを生成しないが、データは破棄しない。

ストリームが破棄可能またはオプション ストリームであるかどうかを確認するには、GetOutputStreamInfo メソッドを呼び出す。

IMediaObject::Lock

IMediaObject インターフェイス

DMO のロックを取得または解除する。複数の操作を実行するときに、このメソッドを呼び出して、DMO を継続して処理された状態に保つ。

構文

HRESULT Lock(
    LONG bLock
);

パラメータ

bLock
ロックを取得するか解除するかを指定する値。値が 0 以外の場合はロックが取得される。値が 0 の場合はロックが解除される。

戻り値

HRESULT 値を返す。以下の値をとる。

S_OK | 成功
E_FAIL | 失敗

注意

このメソッドは、ほかのスレッドが DMO に対するメソッドを呼び出さないようにする。ほかのスレッドが DMO に対するメソッドを呼び出すと、そのスレッドはロックが解除されるまで動作を停止する。


IMediaObjectInPlace インターフェイス

このインターフェイスは、データが存在する場所でデータを処理するためのメソッドを備えている。以下の条件が満たされていれば、Microsoft® DirectX® Media Object (DMO) はこのインターフェイスを公開できる。

  • DMO が 1 つの入力ストリームと 1 つの出力ストリームを持っている。
  • 両方のストリームが同じメディア タイプを使用している。
  • 出力が、入力データの存在するバッファ上で、つまりデータをコピーすることなく、生成される。

このインターフェイスは、最適化されたデータ処理手段を提供する。アプリケーションは、IMediaObject::ProcessInput メソッドと IMediaObject::ProcessOutput メソッドを呼び出す代わりに、1 つの Process メソッドを呼び出す。ただし、このインターフェイスを実装する DMO は、必ず IMediaObject インターフェイスも実装する必要がある。したがって、アプリケーションにはこのインターフェイスを使用する義務はなく、DMO がこのインターフェイスを実装することも保証されない。

Vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスを指すポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IMediaObjectInPlace メソッド | 説明
Process | データのブロックを処理する。
Clone | 現在の状態の DMO のコピーを作成する。
GetLatency | この DMO によって生じる待機時間を取得する。

IMediaObjectInPlace::Process

IMediaObjectInPlace インターフェイス

データのブロックを処理する。アプリケーションは入力データのブロックを指すポインタを供給する。DMO は指定された場所でデータを処理する。

構文

HRESULT Process(
    ULONG ulSize,
    BYTE *pData
    REFERENCE_TIME refTimeStart,
    DWORD dwFlags
);

パラメータ

ulSize
[in] バイト単位で表すデータのサイズ。
pData
[in, out] サイズが ulSize のバッファを指すポインタ。入力時にはバッファに入力データが格納される。メソッドが正常に終了すると、バッファには出力データが格納される。
refTimeStart
[in] データの開始タイム。
dwFlags
[in] DMO_INPLACE_NORMAL または DMO_INPLACE_ZERO のいずれか。詳細については、「注意」を参照すること。

戻り値

HRESULT 値を返す。以下の値をとる。

S_FALSE | 成功。処理するデータがまだある。
S_TRUE | 成功。処理するデータが残っていない。
E_FAIL | 失敗。

注意

メソッドが失敗すると、バッファに不要データが残ることがある。アプリケーションはバッファの内容を使ってはいけない。

DMO は、入力データの長さを超える出力データを生成することがある。この現象は "エフェクト テール" と呼ばれる。たとえば、残響エフェクトは、入力が無音になった後も継続する。DMO でエフェクト テールが発生すると、このメソッドは S_FALSE を返す。

アプリケーションに処理する入力データがある間は、dwFlags パラメータを DMO_INPLACE_NORMAL に設定して Process メソッドを呼び出す。この呼び出しが S_FALSE を返したら、入力バッファをゼロにして、DMO_INPLACE_ZERO フラグを設定し、Process を再び呼び出す。DMO はゼロなったバッファにエフェクト テールを格納する。戻り値が、DMO がエフェクト テールの処理を終了したことを示す S_TRUE になるまで、この方法で Process の呼び出しを繰り返す。

DMO でエフェクト テールが発生しなければ、このメソッドは常に S_TRUE (またはエラー コード) を返す。

IMediaObjectInPlace::Clone

IMediaObjectInPlace インターフェイス

現在の状態の DMO のコピーを作成する。

構文

HRESULT Clone(
    IMediaObjectInPlace **ppMediaObject
);

パラメータ

ppMediaObject
[out] 新しい DMO の IMediaObjectInPlace インターフェイスを受け取るポインタのアドレス。

戻り値

成功すれば S_OK を返す。それ以外の場合は、エラーの原因を示す HRESULT 値を返す。

注意

メソッドが成功すると、メソッドが返す IMediaObjectInPlace インターフェイスには未処理の参照カウントが残る。インターフェイスを使い終わったら、必ずインターフェイスを解放すること。

IMediaObjectInPlace::GetLatency

IMediaObjectInPlace インターフェイス

この DMO によって生じる待機時間を取得する。

構文

HRESULT GetLatency(
    REFERENCE_TIME *pLatencyTime
);

パラメータ

pLatencyTime
[out] 待機時間を 100 ナノ秒単位で受け取る変数を指すポインタ。

戻り値

成功すれば S_OK を返す。それ以外の場合は、エラーの原因を示す HRESULT 値を返す。

注意

このメソッドは、各バッファを処理するのに必要な平均時間を返す。通常、この値は、プロセッサ速度および CPU 負荷などの実行時環境の要因に依存する。このメソッドを実装する方法の 1 つは、DMO が履歴データに基づいて稼働平均値を記録する方法である。


構造体

ここでは、Microsoft® DirectX® Media Object (DMO) 構造体について説明する。

構造体 | 説明
DMO_MEDIA_TYPE | DMO のストリームが使用するデータのフォーマットを記述する。
DMO_OUTPUT_DATA_BUFFER | DMO が使用する出力バッファを記述する。
DMO_PARTIAL_MEDIATYPE | DMO が使用するメディア タイプを部分的に記述する。


DMO_MEDIA_TYPE 構造体

構造体

Microsoft® DirectX® Media Object (DMO) のストリームによって使用されるデータのフォーマットを記述する。

注 : この構造体は、Microsoft® DirectShow® AM_MEDIA_TYPE 構造体と同じである。

構文

typedef struct _DMOMediaType {
    GUID     majortype;
    GUID     subtype;
    BOOL     bFixedSizeSamples;
    BOOL     bTemporalCompression;
    ULONG    lSampleSize;
    GUID     formattype;
    IUnknown *pUnk;
    ULONG    cbFormat;
    [size_is(cbFormat)] BYTE * pbFormat;
} DMO_MEDIA_TYPE;

メンバ

majortype
ストリームのメジャー タイプ GUID。
subtype
ストリームのサブタイプ GUID。
bFixedSizeSamples
TRUE であれば、サンプルは固定サイズである。このフィールドは情報提供専用である。オーディオの場合は、通常、TRUE に設定される。ビデオの場合は、通常、非圧縮ビデオは TRUE、圧縮ビデオは FALSE に設定される。
bTemporalCompression
TRUE であれば、サンプルは時間 (フレーム間) 圧縮を使って圧縮されている。(TRUE は一部のフレームがキー フレームでないことを示す。)このフィールドは情報提供専用である。
lSampleSize
バイト単位で表すサンプルのサイズ。圧縮データの場合、値は 0 になる。
formattype
フォーマット タイプを指定する GUID。pbFormat メンバは、対応するフォーマット構造体を指す。フォーマット タイプには以下が含まれている。
フォーマット タイプ | フォーマット構造体
FORMAT_None | フォーマット タイプなし
FORMAT_MPEGVideo | MPEG1VIDEOINFO
FORMAT_MPEG2Video | MPEG2VIDEOINFO
FORMAT_VideoInfo | VIDEOINFOHEADER
FORMAT_VideoInfo2 | VIDEOINFOHEADER2
FORMAT_WaveFormatEx | WAVEFORMATEX
pUnk
使われていない。
cbFormat
メディア タイプのフォーマット ブロックのサイズ。
pbFormat
フォーマット構造体を指すポインタ。構造体のタイプは、formattype メンバによって指定される。formattype が GUID_NULL または FORMAT_None でない限り、フォーマット構造体がなければならない。

注意

bFixedSizeSamples メンバ、bTemporalCompression メンバ および lSampleSize メンバは、Microsoft® DirectShow® との互換性を保つために用意されている。ほかの DMO クライアントは、これらを使う必要はない。


DMO_OUTPUT_DATA_BUFFER 構造体

構造体

Microsoft® DirectX® Media Object (DMO) が使用する出力バッファを記述する。

構文

typedef struct _DMO_OUTPUT_DATA_BUFFER {
    IMediaBuffer *pBuffer;
    DWORD dwStatus;
    REFERENCE_TIME rtTimestamp;
    REFERENCE_TIME rtTimelength;
} DMO_OUTPUT_DATA_BUFFER, *PDMO_OUTPUT_DATA_BUFFER;

メンバ

pBuffer
[in] アプリケーションによって割り当てられたバッファの IMediaBuffer インターフェイスを指すポインタ。
dwStatus
[out] 状態フラグ。DMO は、出力を処理した後、このメンバを 0 個以上の DMO_OUTPUT_DATA_BUFFER_FLAGS フラグのビット単位の論理和に設定する。
rtTimestamp
[out] バッファ内のデータの開始タイムを指定するタイム スタンプ。バッファが有効なタイム スタンプを持っていれば、DMO はこのメンバを設定し、dwStatus メンバの DMO_OUTPUT_DATA_BUFFERF_TIME フラグも設定する。それ以外の場合はこのメンバを無視する。
rtTimelength
[out] バッファ内のデータの長さを指定する基準時間。DMO がこのメンバを有効な値に設定する場合は、dwStatus メンバの DMO_OUTPUT_DATA_BUFFERF_TIMELENGTH フラグも設定する。それ以外の場合はこのメンバを無視する。

参照

IMediaObject::ProcessOutput


DMO_PARTIAL_MEDIATYPE 構造体

構造体

Microsoft® DirectX® Media Object (DMO) が使用するメディア タイプを部分的に記述する。DMO 登録関数は、この構造体を使って、サポートされているメディア タイプを指定する。

構文

typedef struct _DMO_PARTIAL_MEDIATYPE {
    GUID type;
    GUID subtype;
} DMO_PARTIAL_MEDIATYPE, *PDMO_PARTIAL_MEDIATYPE;

メンバ

type
メジャー タイプ GUID。すべてのメジャー タイプを適合させるには GUID_NULL を使用する。
subtype
サブタイプ GUID。すべてのサブタイプを適合させるには GUID_NULL を使用する。


列挙型

ここでは、Microsoft® DirectX® Media Object (DMO) 列挙型について説明する。

列挙型 | 説明
DMO_ENUM_FLAGS | DMO を列挙するときの検索条件を指定するフラグを定義する。
DMO_INPUT_DATA_BUFFER_FLAGS | 入力バッファを説明するフラグを定義する。
DMO_INPUT_STREAM_INFO_FLAGS | 入力ストリームを説明するフラグを定義する。
DMO_OUTPUT_DATA_BUFFER_FLAGS | 出力バッファを説明するフラグを定義する。
DMO_OUTPUT_STREAM_INFO_FLAGS | 出力ストリームを説明するフラグを定義する。
DMO_PROCESS_OUTPUT_FLAGS | 出力処理要求を指定するフラグを定義する。
DMO_REGISTER_FLAGS | DMO のレジストリ情報を指定するフラグを定義する。
DMO_SET_TYPE_FLAGS | ストリームのメディア タイプを設定するためのフラグを定義する。
DMO_VIDEO_OUTPUT_STREAM_FLAGS | ビデオ最適化に対して要求する機能を説明するフラグを定義する。


DMO_ENUM_FLAGS 列挙

列挙型

Microsoft® DirectX® Media Object (DMO) を列挙するときの検索条件を指定するフラグを定義する。

構文

enum DMO_ENUM_FLAGS {
    DMO_ENUMF_INCLUDE_KEYED = 0x00000001
};

要素

DMO_ENUMF_INCLUDE_KEYED
列挙には、ソフトウェア キーによって使用が制限されている DMO を含める。このフラグがない場合、キーで保護された DMO は列挙から除外される。

注意

DMO の開発者は、ソフトウェア キーを使って DMO の利用者を制限できる。ソフトウェア キーで保護された DMO を使用する場合、アプリケーションは DMO のロックを解除する必要がある。DMO のロックを解除する方法は、実装によって異なる。個々の DMO のドキュメントを参照すること。

参照

DMOEnum


DMO_INPUT_DATA_BUFFER_FLAGS 列挙

列挙型

入力バッファを説明するフラグを定義する。

構文

enum _DMO_INPUT_DATA_BUFFER_FLAGS {
    DMO_INPUT_DATA_BUFFERF_SYNCPOINT       = 0x00000001,
    DMO_INPUT_DATA_BUFFERF_TIME            = 0x00000002,
    DMO_INPUT_DATA_BUFFERF_TIMELENGTH      = 0x00000004
};

要素

DMO_INPUT_DATA_BUFFERF_SYNCPOINT
データの先頭が同期ポイントである。
DMO_INPUT_DATA_BUFFERF_TIME
バッファのタイム スタンプが有効である。
DMO_INPUT_DATA_BUFFERF_TIMELENGTH
バッファが示す時間の長さが有効である。

参照

IMediaObject::ProcessInput


DMO_INPUT_STREAM_INFO_FLAGS 列挙

列挙型

入力ストリームを説明するフラグを定義する。

構文

enum _DMO_INPUT_STREAM_INFO_FLAGS {
    DMO_INPUT_STREAMF_WHOLE_SAMPLES            = 0x00000001,
    DMO_INPUT_STREAMF_SINGLE_SAMPLE_PER_BUFFER = 0x00000002,
    DMO_INPUT_STREAMF_FIXED_SAMPLE_SIZE        = 0x00000004,
    DMO_INPUT_STREAMF_HOLDS_BUFFERS            = 0x00000008
};

要素

DMO_INPUT_STREAMF_WHOLE_SAMPLES
ストリームがサンプル全体を必要とする。サンプルが複数のバッファにまたがっていたり、バッファにサンプルの一部が含まれていたりしてはいけない。
DMO_INPUT_STREAMF_SINGLE_SAMPLE_PER_BUFFER
個々のバッファに 1 つだけサンプルが含まれている必要がある。
DMO_INPUT_STREAMF_FIXED_SAMPLE_SIZE
このストリームのすべてのサンプルのサイズを同じにする必要がある。
DMO_INPUT_STREAMF_HOLDS_BUFFERS
DMO が入力データのルックアヘッドを実行する。DMO はこのストリーム用の複数の入力バッファを保持することができる。

参照

IMediaObject::GetInputStreamInfo


DMO_OUTPUT_DATA_BUFFER_FLAGS 列挙

列挙型

出力バッファを説明するフラグを定義する。

構文

enum _DMO_OUTPUT_DATA_BUFFER_FLAGS {
    DMO_OUTPUT_DATA_BUFFERF_SYNCPOINT       = 0x00000001,
    DMO_OUTPUT_DATA_BUFFERF_TIME            = 0x00000002,
    DMO_OUTPUT_DATA_BUFFERF_TIMELENGTH      = 0x00000004,
    DMO_OUTPUT_DATA_BUFFERF_INCOMPLETE      = 0x01000000
};

要素

DMO_OUTPUT_DATA_BUFFERF_SYNCPOINT
データの先頭が同期ポイントである。
DMO_OUTPUT_DATA_BUFFERF_TIME
バッファのタイム スタンプが有効である。
DMO_OUTPUT_DATA_BUFFERF_TIMELENGTH
バッファが示す時間の長さが有効である。
DMO_OUTPUT_DATA_BUFFERF_INCOMPLETE
処理できる入力データがまだあるが、出力バッファがいっぱいである。

参照

IMediaObject::ProcessOutput


DMO_OUTPUT_STREAM_INFO_FLAGS 列挙

列挙型

出力ストリームを説明するフラグを定義する。

構文

enum _DMO_OUTPUT_STREAM_INFO_FLAGS {
    DMO_OUTPUT_STREAMF_WHOLE_SAMPLES            = 0x00000001,
    DMO_OUTPUT_STREAMF_SINGLE_SAMPLE_PER_BUFFER = 0x00000002,
    DMO_OUTPUT_STREAMF_FIXED_SAMPLE_SIZE        = 0x00000004,
    DMO_OUTPUT_STREAMF_DISCARDABLE              = 0x00000008,
    DMO_OUTPUT_STREAMF_OPTIONAL                 = 0x00000010
};

要素

DMO_OUTPUT_STREAMF_WHOLE_SAMPLES
ストリームにサンプル全体が含まれている。サンプルは複数のバッファにまたがっていないし、バッファにサンプルの一部が含まれていることもない。
DMO_OUTPUT_STREAMF_SINGLE_SAMPLE_PER_BUFFER
各バッファに 1 つだけサンプルが含まれている。
DMO_OUTPUT_STREAMF_FIXED_SAMPLE_SIZE
このストリームの中のすべてのサンプルはサイズが同じである。
DMO_OUTPUT_STREAMF_DISCARDABLE
このストリームは破棄できる。DMO は、IMediaObject::ProcessOutput に対する呼び出しの中で、出力バッファにデータをコピーせずに、このストリームのデータを破棄することができる。
DMO_OUTPUT_STREAMF_OPTIONAL
このストリームはオプションである。オプションのストリームは破棄できる。また、アプリケーションはこのストリーム全体を無視できる。アプリケーションはこのストリームのメディア タイプを設定する必要はない。一般的に、オプションのストリームには、追加情報や一部のアプリケーションだけが必要とするデータが含まれている。

注意

DMO_OUTPUT_STREAMF_DISCARDABLE フラグと DMO_OUTPUT_STREAMF_OPTIONAL フラグは両立しない。DMO はこれらのフラグのいずれかを設定できる (どちらのフラグも設定しなくてもよい) が、両方を設定することはできない。

参照

IMediaObject::GetOutputStreamInfo


DMO_PROCESS_OUTPUT_FLAGS 列挙

列挙型

出力処理要求を指定するフラグを定義する。

構文

enum _DMO_PROCESS_OUTPUT_FLAGS {
    DMO_PROCESS_OUTPUT_DISCARD_WHEN_NO_BUFFER = 0x00000001
};

要素

DMO_PROCESS_OUTPUT_DISCARD_WHEN_NO_BUFFER
出力バッファを指すポインタが NULL の場合に出力を破棄する。

参照

IMediaObject::ProcessOutput


DMO_REGISTER_FLAGS 列挙

列挙型

Microsoft® DirectX® Media Object (DMO) のレジストリ情報を指定するフラグを定義する。

構文

enum DMO_REGISTER_FLAGS {
    DMO_REGISTERF_IS_KEYED = 0x00000001
};

要素

DMO_REGISTERF_IS_KEYED
ソフトウェア キーによって DMO の使用が制限されている。

注意

DMO の開発者は、ソフトウェア キーを使って DMO の利用者を制限できる。ソフトウェア キーで保護された DMO を使用する場合、アプリケーションは DMO のロックを解除する必要がある。DMO のロックを解除する方法は、実装によって異なる。個々の DMO のドキュメントを参照すること。

参照

DMORegister


DMO_SET_TYPE_FLAGS 列挙

列挙型

ストリームのメディア タイプを設定するためのフラグを定義する。

構文

enum _DMO_SET_TYPE_FLAGS {
    DMO_SET_TYPEF_TEST_ONLY = 0x00000001,
    DMO_SET_TYPEF_CLEAR     = 0x00000002
};

要素

DMO_SET_TYPEF_TEST_ONLY
メディア タイプをテストするが、設定はしない。
DMO_SET_TYPEF_CLEAR
ストリームに対して設定されたメディア タイプを消去する。

注意

DMO_SET_TYPEF_TEST_ONLY フラグと DMO_SET_TYPEF_CLEAR フラグは両立しない。両方のフラグを設定しないこと。

参照

IMediaObject::SetInputType、IMediaObject::SetOutputType


DMO_VIDEO_OUTPUT_STREAM_FLAGS 列挙

列挙型

ビデオ最適化に対して要求する機能を説明するフラグを定義する。

構文

enum _DMO_VIDEO_OUTPUT_STREAM_FLAGS {
    DMO_VOSF_NEEDS_PREVIOUS_SAMPLE = 0x00000001
};

要素

DMO_VOSF_NEEDS_PREVIOUS_SAMPLE
DMO に渡されるすべての出力バッファに、生成された前のデータを含めることを要求する。

参照

IDMOVideoOutputOptimizations


関数

ここでは、Microsoft® DirectX® Media Object (DMO) 関数について説明する。

  • DMO 登録関数
  • メディア タイプ ヘルパー関数


DMO 登録関数

アプリケーションは DMO 登録関数を利用して、Microsoft® DirectX® Media Object (DMO) の登録と列挙を行うことができる。これらの関数は、Dmoreg.h ファイルで宣言される。

DMORegister | DMO を登録する。
DMOUnregister | DMO の登録を解除する。
DMOEnum | 登録されている DMO を列挙する。
DMOGetTypes | DMO の登録されているメディア タイプを取得する。
DMOGetName | DMO の登録名を取得する。

DMORegister

DMO 登録関数

DMO を登録する。

構文

HRESULT DMORegister(
   LPCWSTR szName,
   REFCLSID clsidDMO,
   REFGUID guidCategory,
   DWORD dwFlags,
   DWORD cInTypes,
   const DMO_PARTIAL_MEDIATYPE *pInTypes,
   DWORD cOutTypes,
   const DMO_PARTIAL_MEDIATYPE *pOutTypes
);

パラメータ

szName
DMO のわかりやすい名前が格納された、NULL で終わる文字列。79 文字を超える名前は切り詰められることがある。
clsidDMO
DMO のクラス識別子 (CLSID)。
guidCategory
DMO のカテゴリを指定するカテゴリ GUID。
dwFlags
DMO_REGISTER_FLAGS 列挙の 0 個以上のフラグのビット単位の論理和。
cInTypes
登録する入力メディア タイプの数。0 も指定できる。
pInTypes
入力メディア タイプを指定する DMO_PARTIAL_MEDIATYPE 構造体の配列を指すポインタ。配列のサイズは cInTypes パラメータによって指定する。
cOutTypes
登録する出力メディア タイプの数。
pOutTypes
出力メディア タイプを指定する DMO_PARTIAL_MEDIATYPE 構造体の配列を指すポインタ。配列のサイズは cOutTypes パラメータによって指定する。0 も指定できる。

戻り値

HRESULT 値を返す。以下の値をとる。

S_OK | 成功
E_FAIL | 失敗
E_INVALIDARG | 無効な引数

注意

この関数は、DMO に関する情報をレジストリに追加する。アプリケーションまたはソフトウェア コンポーネントは、DMOEnum 関数を呼び出すことにより、この情報を使って、使用する必要がある DMO を見つける。たとえば、ビデオ ストリームをエンコードするには、DMOCATEGORY_VIDEO_ENCODER カテゴリで、条件に一致したメディア タイプの DMO を検索する。

この関数によって登録されるメディア タイプは、DMO の検索だけを目的としている。IMediaObject::GetInputType メソッドおよび IMediaObject::GetOutputType メソッドによって返されるタイプに、必ずしも一致しない。たとえば、デコーダは、主要な入力タイプだけを登録することがある。DMO が作成され、入力タイプを設定すると、GetOutputType メソッドは生成可能なすべての圧縮解除タイプを返す。

DMOUnregister

DMO 登録関数

DMO の登録を解除する。

構文

HRESULT DMOUnregister(
   REFCLSID clsidDMO,
   REFGUID guidCategory
);

パラメータ

clsidDMO
DMO のクラス識別子 (CLSID)。
guidCategory
削除する DMO が属するカテゴリを指定する カテゴリ GUID。すべてのカテゴリで DMO の登録を解除するには GUID_NULL を使用する。

戻り値

HRESULT 値を返す。以下の値をとる。

S_FALSE | この CLSID は指定されたカテゴリに登録されていない。
S_OK | 成功。
E_INVALIDARG | 無効な引数。

DMOEnum

DMO 登録関数

登録されている DMO を列挙する。呼び出し元はカテゴリ、メディア タイプ、またはその両方を基準にして検索できる。

構文

HRESULT DMOEnum(
    REFGUID guidCategory,
    DWORD dwFlags,
    DWORD cInTypes,
    const DMO_PARTIAL_MEDIATYPE *pInTypes,
    DWORD cOutTypes,
    const DMO_PARTIAL_MEDIATYPE *pOutTypes,
    IEnumDMO **ppEnum
);

パラメータ

guidCategory
検索する DMO のカテゴリを指定する カテゴリ GUID。すべてのカテゴリを検索するには GUID_NULL を使用する。
dwFlags
DMO_ENUM_FLAGS 列挙の 0 個以上のフラグのビット単位の論理和。
cInTypes
検索条件として使用する入力メディア タイプの数。すべての入力タイプを条件に適合させるには 0 を使用する。
pInTypes
入力メディア タイプが格納された DMO_PARTIAL_MEDIATYPE 構造体の配列を指すポインタ。cInTypes パラメータで配列のサイズを指定する。
cOutTypes
検索条件として使用する出力メディア タイプの数。すべての出力タイプを条件に適合させるには 0 を使用する。
pOutTypes
出力メディア タイプが格納された DMO_PARTIAL_MEDIATYPE 構造体の配列を指すポインタ。cOutTypes パラメータで配列のサイズを指定する。
ppEnum
列挙子の IEnumDMO インターフェイスを受け取る変数のアドレス。

戻り値

HRESULT 値を返す。以下の値をとる。

S_OK | 成功
E_FAIL | 失敗
E_OUTOFMEMORY | メモリ不足

注意

このメソッドは、IEnumDMO インターフェイスをサポートする列挙子オブジェクトを指すポインタを返す。アプリケーションは IEnumDMO インターフェイスを使って、検索条件に適合する DMO のセットを列挙する。

DMOGetTypes

DMO 登録関数

DMO に対して登録されているメディア タイプを取得する。

構文

HRESULT DMOGetTypes(
    REFCLSID clsidDMO,
    unsigned long ulInputTypesRequested,
    unsigned long *pulInputTypesSupplied,
    DMO_PARTIAL_MEDIATYPE *pInputTypes,
    unsigned long ulOutputTypesRequested,
    unsigned long *pulOutputTypesSupplied,
    DMO_PARTIAL_MEDIATYPE *pOutputTypes
);

パラメータ

clsidDMO
DMO のクラス識別子 (CLSID)。
ulInputTypesRequested
pInputTypes パラメータによって渡される配列のサイズ。
pulInputTypesSupplied
関数がデータを格納する pInputTypes の DMO_PARTIAL_MEDIATYPE 構造体の数を受け取る変数を指すポインタ。
pInputTypes
呼び出し元によって割り当てられた DMO_PARTIAL_MEDIATYPE 構造体の配列を指すポインタ。配列のサイズは ulInputTypesRequested パラメータによって取得される。関数は、DMO に対して登録されている入力タイプを配列に格納する。
ulOutputTypesRequested
pOutputTypes パラメータによって渡される配列のサイズ。
pulOutputTypesSupplied
関数がデータを格納する pOutputTypes の DMO_PARTIAL_MEDIATYPE 構造体の数を受け取る変数を指すポインタ。
pOutputTypes
呼び出し元によって割り当てられた DMO_PARTIAL_MEDIATYPE 構造体の配列を指すポインタ。配列のサイズは ulOutputTypesRequested パラメータによって取得される。関数は、DMO に対して登録されている DMO 出力タイプを配列に格納する。

戻り値

HRESULT 値を返す。以下の値をとる。

S_FALSE | 配列が小さすぎる
S_OK | 成功
E_FAIL | 失敗

注意

配列のいずれかが、登録されているすべてのタイプを格納するには小さすぎる場合、関数は配列にデータを格納するが、S_FALSE を返す。

DMO がメディア タイプを登録しなかった場合、関数は S_OK を返し、*pulInputTypesSupplied と *pulOutputTypesSupplied を 0 に設定する。

DMOGetName

DMO 登録関数

DMO の登録名を取得する。

構文

HRESULT DMOGetName(
   REFCLSID clsidDMO,
   WCHAR szName[]
);

パラメータ

clsidDMO
DMO のクラス識別子 (CLSID)。
szName
DMO の名前を受け取る 80 個の Unicode 文字の配列。呼び出し元は配列を割り当てる必要がある。名前は NULL で終わる文字列である。

戻り値

HRESULT 値を返す。以下の値をとる。

S_FALSE | この DMO に対して名前が登録されていない、または名前の長さが 0 である。
S_OK | 成功。
E_FAIL | 失敗。

注意

メソッドが S_FALSE を返すと、szName が '\0' に設定される。


メディア タイプ ヘルパー関数

これらの関数は、DMO_MEDIA_TYPE 構造体を操作する。これらの関数は Dmort.h ファイルで宣言される。

MoInitMediaType | メディア タイプ構造体を初期化する。
MoFreeMediaType | メディア タイプ構造体の割り当て済みのメンバを解放する。
MoCopyMediaType | 1 つのメディア タイプ構造体のメンバを別のメディア タイプ構造体にコピーする。
MoCreateMediaType | 新しいメディア タイプ構造体を割り当てる。
MoDeleteMediaType | 前に割り当てられたメディア タイプ構造体を削除する。
MoDuplicateMediaType | メディア タイプ構造体を複製する。

MoInitMediaType

DMO 登録関数

メディア タイプ構造体を初期化する。

構文

HRESULT MoInitMediaType(
    DMO_MEDIA_TYPE *pmt,
    DWORD cbFormat
);

パラメータ

pmt
呼び出し元によって割り当てられており、初期化されていない DMO_MEDIA_TYPE 構造体を指すポインタ。
cbFormat
フォーマット ブロックに割り当てるバイトの数。0 も指定できる。

戻り値

HRESULT 値を返す。以下の値をとる。

S_OK | 成功
E_OUTOFMEMORY | メモリ不足
E_POINTER | NULL ポインタ引数

注意

この関数はフォーマット ブロックを割り当てて、DMO_MEDIA_TYPE 構造体の cbFormat メンバと pbFormat メンバを設定する。

呼び出し元は、MoFreeMediaType 関数を呼び出すことによってメディア タイプを解放する必要がある。

MoFreeMediaType

DMO 登録関数

メディア タイプ構造体の割り当て済みのメンバを解放する。

構文

HRESULT MoFreeMediaType(
    DMO_MEDIA_TYPE *pmt
);

パラメータ

pmt
初期化された DMO_MEDIA_TYPE 構造体を指すポインタ。

戻り値

HRESULT 値を返す。以下の値をとる。

S_OK | 成功
E_POINTER | NULL ポインタ引数

注意

この関数は、DMO_MEDIA_TYPE 構造体の pbFormat メンバが指すフォーマット ブロックを解放する。

MoCopyMediaType

DMO 登録関数

1 つのメディア タイプ構造体のメンバを別のメディア タイプ構造体にコピーする。

構文

HRESULT MoCopyMediaType(
    DMO_MEDIA_TYPE *pmtDest,
    const DMO_MEDIA_TYPE *pmtSrc
);

パラメータ

pmtDest
コピー先の DMO_MEDIA_TYPE 構造体を指すポインタ。呼び出し元はこの構造体を割り当てる必要があるが、初期化してはいけない。
pmtSrc
コピー元の DMO_MEDIA_TYPE 構造体を指すポインタ。

戻り値

HRESULT 値を返す。以下の値をとる。

S_OK | 成功
E_OUTOFMEMORY | メモリ不足
E_POINTER | NULL ポインタ引数

注意

この関数は、*pmtSrc のすべてのメンバを *pmtDest にコピーし、フォーマット ブロックをコピーする。

呼び出し元は、MoFreeMediaType 関数を呼び出すことによってコピー先メディア タイプを解放する必要がある。

MoCreateMediaType

DMO 登録関数

新しいメディア タイプ構造体を割り当てる。

構文

HRESULT MoCreateMediaType(
    DMO_MEDIA_TYPE **ppmt,
    DWORD cbFormat
);

パラメータ

ppmt
割り当てられた構造体を受け取る DMO_MEDIA_TYPE 構造体を指すポインタのアドレス。
cbFormat
フォーマット ブロックに割り当てるバイトの数。0 も指定できる。

戻り値

HRESULT 値を返す。以下の値をとる。

S_OK | 成功
E_OUTOFMEMORY | メモリ不足
E_POINTER | NULL ポインタ引数

注意

この関数は新しい DMO_MEDIA_TYPE 構造体を割り当てて、MoInitMediaType 関数を呼び出すことによって、その構造体を初期化する。

呼び出し元は、MoDeleteMediaType 関数を呼び出すことによってメディア タイプ構造体を削除する必要がある。

MoDeleteMediaType

DMO 登録関数

前に割り当てられたメディア タイプ構造体を削除する。

構文

HRESULT MoDeleteMediaType(
    DMO_MEDIA_TYPE *pmt
);

パラメータ

pmt
初期化された DMO_MEDIA_TYPE 構造体を指すポインタ。

戻り値

HRESULT 値を返す。以下の値をとる。

S_OK | 成功
E_POINTER | NULL ポインタ引数

注意

この関数は、MoFreeMediaType を呼び出すことによって、メディア タイプ構造体の割り当て済みのメンバを解放する。次に、この関数は、メディア タイプ構造体そのものを解放する。

MoDuplicateMediaType

DMO 登録関数

メディア タイプ構造体を複製する。

構文

HRESULT MoDuplicateMediaType(
    DMO_MEDIA_TYPE **ppmtDest,
    const DMO_MEDIA_TYPE *pmtSrc
);

パラメータ

ppmtDest
複製された構造体を受け取る DMO_MEDIA_TYPE 構造体を指すポインタのアドレス。
pmtSrc
複製するメディア タイプ構造体を指すポインタ。

戻り値

HRESULT 値を返す。以下の値をとる。

S_OK | 成功
E_OUTOFMEMORY | メモリ不足
E_POINTER | NULL ポインタ引数

注意

このメソッドを実行することは、MoCreateMediaType と MoCopyMediaType を呼び出すことに等しい。

呼び出し元は、MoDeleteMediaType 関数を呼び出すことによって、返されたメディア タイプ構造体を削除する必要がある。


DMO エラー コード

次の表は、Microsoft® DirectX® メディア オブジェクト (DMO) に関連したエラー コードを示す。これらのエラー コードは、ヘッダー ファイル Mediaerr.h に定義されている。

戻りコード | 説明 | 16 進数値
DMO_E_INVALIDSTREAMINDEX | 無効なストリーム インデックス。 | 0x80040201
DMO_E_INVALIDTYPE | 無効なメディア タイプ。 | 0x80040202
DMO_E_TYPE_NOT_SET | 設定されなかったメディア タイプ。1 つまたは複数のストリームは、この操作を実行する前にメディア タイプを必要とする。 | 0x80040203
DMO_E_NOTACCEPTING | このストリームではデータは受け入れられない。より多くの出力データを処理しなければならないこともある。詳細については、「IMediaObject::ProcessInput」を参照すること。 | 0x80040204
DMO_E_TYPE_NOT_ACCEPTED | メディア タイプが受け入れられなかった。 | 0x80040205
DMO_E_NO_MORE_ITEMS | メディア タイプ インデックスが範囲外である。 | 0x80040206


DMO の GUID

ここでは、Microsoft® DirectX® Media Object (DMO) で定義されているグローバルに一意な識別子 (GUID) の一部を示す。

  • カテゴリ GUID

カテゴリ GUID

次の表は、DMO カテゴリの GUID を示している。カテゴリに登録されている DMO を列挙するには、カテゴリに対応する GUID を DMOEnum 関数に渡す。

GUID | 説明
DMOCATEGORY_AUDIO_DECODER | オーディオ デコーダ
DMOCATEGORY_AUDIO_EFFECT | オーディオ エフェクト
DMOCATEGORY_AUDIO_ENCODER | オーディオ エンコーダ
DMOCATEGORY_VIDEO_DECODER | ビデオ デコーダ
DMOCATEGORY_VIDEO_EFFECT | ビデオ エフェクト
DMOCATEGORY_VIDEO_ENCODER | ビデオ エンコーダ
DMOCATEGORY_AUDIO_CAPTURE_EFFECT | オーディオ キャプチャ エフェクト


DMO 基底クラス リファレンス

Microsoft® DirectX® 8.0 には、DirectX Media Object (DMO) を作成するための基底クラス テンプレートが含まれている。DMO の作成にテンプレートを使用する必要はない。ただし、テンプレートはすべての DMO に共通する各種の処理を行うようになっている。テンプレートを使用すれば、その DMO 固有の機能のみに専念できる。さらに、テンプレートは堅牢な実装を作成する助けにもなる。

この項は、以下のトピックから構成される。

  • DMO 基底クラスの使い方
  • IMediaObjectImpl クラス テンプレート


DMO 基底クラスの使い方

Microsoft® DirectX® 8.0 SDK には、DMO 作成のための基底クラス テンプレート IMediaObjectImpl が含まれている。DMO が IUnknown インターフェイスと IMediaObject インターフェイスを完全にサポートしていれば、DMO 作成時にこのクラス テンプレートを使用する必要はない。ただし、Microsoft 提供のクラス テンプレートは、入力パラメータの確認などの "定番" 処理の多くを行うようになっている。テンプレートを使用すれば、その DMO 固有の機能のみに専念できる。さらに、テンプレートは堅牢な実装を作成する助けにもなる。

ここでは、以下のトピックについて説明する。

  • IMediaObjectImpl の概要
  • 派生クラスの宣言
  • DMO メソッドの実装

IMediaObjectImpl の概要

IMediaObjectImpl テンプレートは、IMediaObject インターフェイスを継承するクラス テンプレートである。このテンプレートを使って DMO を作成するには、IMediaObjectImpl から派生する新しいクラスを定義する。テンプレートは IMediaObject のメソッドをすべて実装する。多くの場合、テンプレート メソッドは対応する内部メソッドを呼び出し、これらの内部メソッドを派生クラスから提供する。このように、テンプレートはパラメータ チェックなどの汎用機能を提供し、派生クラスは DMO の核になる機能を提供する。

テンプレートは以下の機能を提供する。

  • 基本的なパラメータ チェック。テンプレート メソッドは、必須パラメータが NULL でなく、ストリームのインデックスが範囲内であり、フラグが有効であることを検査する。
  • ロック。テンプレート メソッドは、Lock と Unlock の 2 つの内部メソッドを呼び出して、DMO に関する処理を逐次化する。この機能により、DMO をスレッドセーフにすることができる。
  • メディア タイプ。テンプレートは、DMO 内のストリームに対して設定されたメディア タイプを保持する。また、テンプレートはメディア タイプにアクセスするメソッドも提供する。
  • ストリーミング。テンプレートは、クライアントがすべての必須ストリームのメディア タイプを設定するまで、ストリーミングを実行しない。また、ProcessInput メソッドと ProcessOutput メソッドは、自動的に AllocateStreamingResources を呼び出す。

IUnknown インターフェイスは、テンプレートから提供されないため、派生クラスで実装すること。IUnknown は、ATL (Active Template Library) を使って実装できるが、ほかの実装を提供してもよい。

また、テンプレートにはロック メカニズムが実装されない。このため、Lock メソッドと Unlock メソッドは派生クラス側で実装する必要がある。ただし、ATL を使ってクラスを作成する場合には、ATL によるこれらのメソッドのデフォルト実装で足りることが多い。

派生クラスの宣言

IMediaObjectImpl テンプレートは、SDK のインクルード ディレクトリにあるヘッダー ファイル Dmoimpl.h で以下のように宣言される。

template <class _DERIVED_, int NUMBEROFINPUTS, int NUMBEROFOUTPUTS>
class IMediaObjectImpl : public IMediaObject

テンプレートには以下の表に示す 3 つのパラメータがある。

_DERIVED_ | 派生クラス型
NUMBEROFINPUTS | 入力ストリーム数
NUMBEROFOUTPUTS | 出力ストリーム数

たとえば、入力ストリームと出力ストリームそれぞれ 1 つをサポートする CMyDmoClass という派生クラスを作成するには、次のように宣言する。

class CMyDmoClass :
    public IMediaObjectImpl<CMyDmoClass, 1, 1>  // 入力が 1 つ、出力が 1 つ

DMO はストリームを動的に作成または破棄できないため、ストリーム数は定数である。

DMO メソッドの実装

テンプレートは、以下の IMediaObject メソッドの部分的な実装を提供する。IMediaObject のメソッドは内部的に対応するメソッドを呼び出すので、それらの内部メソッドを派生クラス側で提供する必要がある。内部メソッド名には、Internal- というプレフィックスが付く。内部メソッドでは、インターフェイス メソッドと同じパラメータが使用される。

IMediaObject メソッド | 派生クラスのメソッド
AllocateStreamingResources | InternalAllocateStreamingResources
Discontinuity | InternalDiscontinuity
Flush | InternalFlush
FreeStreamingResources | InternalFreeStreamingResources
GetInputMaxLatency | InternalGetInputMaxLatency
GetInputSizeInfo | InternalGetInputSizeInfo
GetInputStreamInfo | InternalGetInputStreamInfo
GetInputType | InternalGetInputType
GetOutputSizeInfo | InternalGetOutputSizeInfo
GetOutputStreamInfo | InternalGetOutputStreamInfo
GetOutputType | InternalGetOutputType
ProcessInput | InternalProcessInput
ProcessOutput | InternalProcessOutput
SetInputMaxLatency | InternalSetInputMaxLatency

IMediaObject の残りのメソッドでは、インターフェイス メソッドと内部メソッドが 1 対 1 に対応していない。次の一覧は、テンプレートで完全に実装されるメソッドと、派生クラス提供のヘルパー メソッドを呼び出すメソッドをまとめたものである。

IMediaObject メソッド | IMediaObjectImpl での実装
GetInputCurrentType | 完全に実装される。
GetOutputCurrentType | 完全に実装される。
GetStreamCount | 完全に実装される。
GetInputStatus | InternalAcceptingInput を呼び出す。
Lock | DMOLock として実装される。Lock または Unlock を呼び出す。
SetInputType | InternalCheckInputType を呼び出す。
SetOutputType | InternalCheckOutputType を呼び出す。

詳細については、「IMediaObjectImpl」を参照すること。


IMediaObjectImpl クラス テンプレート

IMediaObject インターフェイスの基本的な実装を提供する。

このテンプレート使用の詳細については、「DMO 基底クラスの使い方」を参照すること。

ヘルパー クラス
LockIt | ロックとその解除を処理する内部ヘルパー クラス。
IMediaObjectImpl メソッド
CheckTypesSet | すべての必須ストリームにメディア タイプが設定されているかどうかを判断する。
InputType | 入力ストリームのメディア タイプを取得する。
InputTypeSet | 入力ストリームにメディア タイプが設定されているかどうかを照会する。
OutputType | 出力ストリームのメディア タイプを取得する。
OutputTypeSet | 出力ストリームにメディア タイプが設定されているかどうかを照会する。
IMediaObject メソッド | IMediaObject インターフェイスを実装するメソッド。
派生クラスのメソッド
InternalAcceptingInput | 入力ストリームがさらに入力を受け付けるかどうかを照会する。
InternalCheckInputType | 入力ストリームが所定のメディア タイプを受け付けるかどうかを照会する。
InternalCheckOutputType | 出力ストリームが所定のメディア タイプを受け付けるかどうかを照会する。
Lock | オブジェクトをロックする。
Unlock | オブジェクトのロックを解除する。

LockIt 内部クラス

ロックとその解除を処理する内部ヘルパー クラス。

構文

LockIt(
    _DERIVED_ *p
);

パラメータ

p
派生オブジェクトへのポインタ。

注意

コンストラクタ メソッドがオブジェクトをロックし、デストラクタ メソッドがオブジェクトのロックを解除する。派生クラスの内部からオブジェクトをロックするには、次のように LockIt 型のローカル変数を宣言する。

{
    LockIt lck(static_cast<_DERIVED_ *>(this)); // オブジェクトをロックする。

} // lck がスコープ外に出て、オブジェクトのロックが解除される。

IMediaObjectImpl のメソッドではロックが処理されるため、多くの場合、派生クラスでオブジェクトをロックする必要はない。

IMediaObjectImpl::CheckTypesSet

すべての必須ストリームにメディア タイプが設定されているかどうかを判断する。

構文

bool CheckTypesSet(void);

戻り値

オブジェクトの必須ストリームすべてにメディア タイプが設定されている場合は、TRUE を返す。それ以外の場合は、FALSE を返す。

注意

ストリームのメディア タイプを変更する操作をした場合には、その後にこのメソッドを呼び出す。このメソッドは、クラス内部のプライベートなフラグを設定する。IMediaObjectImpl の一部メソッドでは、一定の処理を実行してよいかどうかを判断するために、このフラグをテストする。フラグが FALSE の場合は、通常、DMO_E_TYPE_NOT_SET が返される。

ストリームのメディア タイプを変更する IMediaObject メソッドは、SetInputType と SetOutputType の 2 つのみである。クラス テンプレートは、これらのメソッドの両方を実装する。

IMediaObjectImpl::InputType

入力ストリームのメディア タイプを取得する。

構文

const DMO_MEDIA_TYPE *InputType(
DWORD ulInputStreamIndex
);

パラメータ

ulInputStreamIndex
入力ストリームのインデックス。

戻り値

メディア タイプを記述する DMO_MEDIA_TYPE 構造体へのポインタを返す。タイプが設定されていない場合には、NULL を返す。

IMediaObjectImpl::InputTypeSet

入力ストリームにメディア タイプが設定されているかどうかを照会する。

構文

bool InputTypeSet(
DWORD ulInputStreamIndex
);

パラメータ

ulInputStreamIndex
入力ストリームのインデックス。

戻り値

このストリームにメディア タイプが設定されている場合は、TRUE を返す。それ以外の場合は、FALSE を返す。

IMediaObjectImpl::OutputType

出力ストリームのメディア タイプを取得する。

構文

const DMO_MEDIA_TYPE *OutputType(
DWORD ulOutputStreamIndex
);

パラメータ

ulOutputStreamIndex
出力ストリームのインデックス。

戻り値

メディア タイプを記述する DMO_MEDIA_TYPE 構造体へのポインタを返す。タイプが設定されていない場合には、NULL を返す。

IMediaObjectImpl::OutputTypeSet

出力ストリームにメディア タイプが設定されているかどうかを照会する。

構文

bool OutputTypeSet(
DWORD ulOutputStreamIndex
);

パラメータ

ulOutputStreamIndex
出力ストリームのインデックス。

戻り値

このストリームにメディア タイプが設定されている場合は、TRUE を返す。それ以外の場合は、FALSE を返す。

_DERIVED_::InternalAcceptingInput

入力ストリームがさらに入力を受け付けるかどうかを照会する。派生クラスは、このメソッドを宣言および実装する必要がある。

構文

HRESULT InternalAcceptingInput(
    DWORD dwInputStreamIndex
);

パラメータ

dwInputStreamIndex
入力ストリームのインデックス。

戻り値

入力ストリームが入力を受け付ける場合は、S_OK を返す。それ以外の場合は、S_FALSE を返す。

_DERIVED_::InternalCheckInputType

入力ストリームが所定のメディア タイプを受け付けるかどうかを照会する。派生クラスは、このメソッドを宣言および実装する必要がある。

構文

HRESULT InternalCheckInputType(
    DWORD dwInputStreamIndex,
    const DMO_MEDIA_TYPE *pmt
);

パラメータ

dwInputStreamIndex
入力ストリームのインデックス。
pmt
メディア タイプを記述する DMO_MEDIA_TYPE 構造体へのポインタ。

戻り値

メディア タイプが有効な場合は、S_OK を返す。それ以外の場合は、DMO_E_INVALIDTYPE を返す。

_DERIVED_::InternalCheckOutputType

出力ストリームが所定のメディア タイプを受け付けるかどうかを照会する。派生クラスは、このメソッドを宣言および実装する必要がある。

構文

HRESULT InternalCheckOutputType(
    DWORD dwOutputStreamIndex,
    const DMO_MEDIA_TYPE *pmt
);

パラメータ

dwOutputStreamIndex
出力ストリームのインデックス。
pmt
メディア タイプを記述する DMO_MEDIA_TYPE 構造体へのポインタ。

戻り値

メディア タイプが有効な場合は、S_OK を返す。それ以外の場合は、DMO_E_INVALIDTYPE を返す。

_DERIVED_::Lock

オブジェクトをロックする。派生クラスは、このメソッドを宣言および実装する必要がある。

構文

void Lock(void);

注意

ATL (Active Template Library) を使って派生クラスを実装すると、ATL によるこのメソッドのデフォルト実装を使用できる。

_DERIVED_::Unlock

オブジェクトのロックを解除する。派生クラスは、このメソッドを宣言および実装する必要がある。

構文

void Unlock(void);

注意

ATL (Active Template Library) を使って派生クラスを実装すると、ATL によるこのメソッドのデフォルト実装を使用できる。

IMediaObject メソッド

IMediaObject のメソッドの大半は、同じメソッドの内部バージョンを呼び出すラッパーである。派生クラスは、Internal- というプレフィックスを持つ内部バージョンを実装する必要がある。

派生クラスで実装すべきメソッドの一覧については、「DMO 基底クラスの使い方」を参照すること。ここでは、いくつかの実装の詳細について説明する。

AllocateStreamingResources

テンプレートは、このメソッドが呼び出されたかどうかを示すプライベートなフラグを保持する。このフラグが既に TRUE になっているときにメソッドが呼び出されると、InternalAllocateStreamingResources メソッドを呼び出さずに S_OK を返す。FreeStreamingResources メソッドはこのフラグを FALSE にリセットする。

DMOLock

このメソッドは IMediaObject::Lock メソッドを実装する。ATL との名前の競合を避けるため、IMediaObjectImpl ではメソッド名が DMOLock に変更されている。

注 : 派生クラスを構築するときには、DMO ヘッダー ファイルをインクルードする前に FIX_LOCK_NAME を定義する。FIX_LOCK_NAME 疑似命令があると、プリプロセッサは、IMediaObject インターフェイスの宣言にある Lock を DMOLock に置きかえる。ただし、vtable 順は変わらないため、アプリケーションでは Lock という名前を使ってメソッドを起動できる。

#define FIX_LOCK_NAME
#include <dmo.h>

このメソッドは、パラメータが TRUE なら Lock を呼び出し、パラメータが FALSE なら Unlock を呼び出す。派生クラスは、Lock メソッドと Unlock メソッドを実装する必要がある。

Flush

テンプレートは、オブジェクトがフラッシュされたかどうかを示すプライベートなフラグを保持する。Flush メソッドはこのフラグを TRUE にセットし、ProcessInput メソッドは FALSE にリセットする。フラグが既に TRUE になっているときに Flush が呼び出されると、InternalFlush メソッドを呼び出さずに S_OK を返す。

GetInputSizeInfo、GetOutputSizeInfo

メディア タイプが設定されていない必須ストリームがある場合、この 2 つのメソッドは DMO_E_TYPE_NOT_SET を返す。したがって、派生クラスの内部メソッドでは、すべての必須ストリームにメディア タイプが設定されていることを前提に処理できる。

GetInputStatus

このメソッドは、派生クラスが実装する InternalAcceptingInput メソッドを呼び出す。InternalAcceptingInput メソッドは、指定された入力ストリームが入力を受け付ける場合には S_OK を返す。それ以外の場合には、S_FALSE を返す。

メディア タイプが設定されていない必須ストリームがある場合、GetInputStatus メソッドは DMO_E_TYPE_NOT_SET を返す。したがって、InternalAcceptingInput の実装でこの条件を確認する必要はない。

ProcessInput

このメソッドは、InternalProcessInput を呼び出す前に AllocateStreamingResources と InternalAcceptingInput を呼び出す。したがって、InternalProcessInput の実装では、以下の条件を前提に処理ができる。

  • リソースはすべて割り当てられている。
  • 入力ストリームはデータを受け付ける。

ProcessOutput

このメソッドは、InternalProcessOutput を呼び出す前に AllocateStreamingResources を呼び出す。したがって、InternalProcessOutput の実装では、リソースがすべて割り当てられていることを前提に処理できる。

SetInputType

このメソッドは、入力ストリームのメディア タイプをテスト、設定、または消去する。このメソッドは、派生クラスが実装する InternalCheckInputType メソッドを呼び出す。InternalCheckInputType メソッドは、メディア タイプが受け付け可能な場合には S_OK を返し、それ以外の場合にはエラー コードを返す。残りの機能は SetInputType メソッドが実現する。

このメソッドはリソースの割り当てを行わない。DMO がストリーム状態に切り替わると、AllocateStreamingResources メソッドが呼び出される。派生クラスでは、InternalAllocateStreamingResources メソッドを使って、メモリ バッファなどの必要なリソースを割り当てなければならない。

SetOutputType

このメソッドは、出力ストリームのメディア タイプをテスト、設定、または消去する。このメソッドは、派生クラスが実装する InternalCheckOutputType メソッドを呼び出す。InternalCheckOutputType メソッドは、メディア タイプが受け付け可能な場合には S_OK を返し、それ以外の場合にはエラー コードを返す。残りの機能は SetOutputType メソッドが実装する。

このメソッドはリソースの割り当てを行わない。DMO がストリーム状態に切り替わると、AllocateStreamingResources メソッドが呼び出される。派生クラスでは、InternalAllocateStreamingResources メソッドを使ってメモリ バッファなどの必要なリソースを割り当てなければならない。


メディア パラメータ

メディア パラメータは、オブジェクトのプロパティに対する実行時の変更をサポートする新しい API のセットである。急速に変化し、高いパフォーマンスと反復性の両方が要求されるプロパティを正確に制御できる。メディア パラメータを使用すると、プロパティによって正弦波や逆矩形曲線などの厳密な曲線をリアルタイムでフォローできる。

データ変換オブジェクトは、メディア パラメータを使用して、実行時の動作を制御する標準インターフェイスをサポートできる。メディア パラメータを Microsoft® DirectX® Media Objects (DMO) と組み合わせて使用すると、オーディオ エフェクトの作成で特に便利である。たとえば、エコー エフェクトでは、ドライ (未処理の) 信号に対するウェット (処理済み) 信号の比率がスムーズな曲線をフォローするようにすることができる。このような動作は、オーディオ エンジニアリングにおいてレコーディングに不自然な効果が導入されるのを防ぐために重要である。

ここでは、次の内容について説明する。

  • メディア パラメータのリファレンス


メディア パラメータのリファレンス

ここでは、すべてのメディア パラメータのリファレンス情報を示す。

  • インターフェイス
  • 構造体
  • 列挙型
  • 定数
  • グローバル一意識別子 (GUID)


インターフェイス

ここでは、すべての Microsoft® DirectX® メディア パラメータ COM インターフェイスおよび各インターフェイスのメソッドのリファレンス項目を示す。

  • IMediaParamInfo
  • IMediaParams


IMediaParamInfo インターフェイス

オブジェクトがサポートするパラメータに関する情報を取得する。アプリケーションの実行中、オブジェクトがサポートするパラメータの集合は変わらない。パラメータ値を設定するには、IMediaParams インターフェイスを使用する。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントの値を増やす。
Release | 参照カウントの値を減らす。
IMediaParamInfo メソッド | 説明
GetParamCount | オブジェクトがサポートするパラメータの数を取得する。
GetParamInfo | 指定されたパラメータに関する情報を取得する。
GetParamText | パラメータを説明する文字列の配列を取得する。
GetNumTimeFormats | オブジェクトがサポートするタイム フォーマットの数を取得する。
GetSupportedTimeFormat | サポートされているタイム フォーマットを取得する。
GetCurrentTimeFormat | 現在のタイム フォーマットを取得する。

IMediaParamInfo::GetParamCount

IMediaParamInfo インターフェイス

オブジェクトがサポートするパラメータの数を取得する。

構文

HRESULT GetParamCount(
    DWORD *pdwParams
);

パラメータ

pdwParams
[out] パラメータの数を受け取る変数へのポインタ。

戻り値

HRESULT 値を返す。返される値は次のとおり。

S_OK | 成功。
E_POINTER | NULL ポインタ引数。

IMediaParamInfo::GetParamInfo

IMediaParamInfo インターフェイス

指定されたパラメータに関する情報を取得する。

構文

HRESULT GetParamInfo(
    DWORD dwParamIndex,
    MP_PARAMINFO *pInfo
);

パラメータ

dwParamIndex
[in] パラメータのゼロベースのインデックス。
pInfo
[out] パラメータ情報が挿入される MP_PARAMINFO 構造体へのポインタ。

戻り値

HRESULT 値を返す。返される値は次のとおり。

S_OK | 成功。
E_INVALIDARG | 範囲外のインデックス。
E_POINTER | NULL ポインタ引数。

注意

オブジェクトがサポートするパラメータの数を取得するには、GetParamCount メソッドを呼び出すこと。

IMediaParamInfo::GetParamText

IMediaParamInfo インターフェイス

パラメータを説明する一連の文字列を取得する。

構文

HRESULT GetParamText(
    DWORD dwParamIndex,
    WCHAR **ppwchText
);

パラメータ

dwParamIndex
[in] パラメータのゼロベースのインデックス。
ppwchText
[out] 一連の Unicode? 文字列へのポインタを受け取る変数のアドレス。

戻り値

HRESULT 値を返す。返される値は次のとおり。

S_OK | 成功。
E_INVALIDARG | 範囲外のインデックス。
E_POINTER | NULL ポインタ引数。

戻り値

メソッドが成功した場合、*ppwchText は次の書式を持つ文字列を指す。

Name\0Unit\0Enum1\0Enum2\0...EnumN\0\0

各項目は次のとおり。

  • Name は、パラメータの名前である。
  • Unit は、単位の名前である。たとえば milliseconds など。
  • Enum1 ～ EnumN は、パラメータの列挙値を表すわかりやすい名前である。MPT_ENUM 型のパラメータだけに適用される。

アプリケーションはユーザー インターフェイス内にこれらの値を表示できる。これらの値は必ずしも一貫性のある命名規則に従っていない。ユーザーのコンピュータで国際コード ページが使用されている場合は、このメソッドは、そのコード ページに対応するローカライズされた文字列を返すことがある。

オブジェクトは CoTaskMemAlloc 関数を使用して文字列のメモリを割り当てる。このメソッドを呼び出した後、CoTaskMemFree を呼び出してバッファを解放すること。

IMediaParamInfo::GetNumTimeFormats

IMediaParamInfo インターフェイス

オブジェクトがサポートするタイム フォーマットの数を取得する。

構文

HRESULT GetNumTimeFormats(
    DWORD *pdwNumTimeFormats
);

パラメータ

pdwNumTimeFormats
[out] サポートされているタイム フォーマットの数を受け取る変数へのポインタ。

戻り値

HRESULT 値を返す。返される値は次のとおり。

S_OK | 成功。
E_POINTER | NULL ポインタ引数。

IMediaParamInfo::GetSupportedTimeFormat

IMediaParamInfo インターフェイス

サポートされているタイム フォーマットを取得する。

構文

HRESULT GetSupportedTimeFormat(
    DWORD dwFormatIndex,
    GUID *pguidTimeFormat
);

パラメータ

dwFormatIndex
[in] 取得するタイム フォーマットのインデックス。
pguidTimeFormat
[out] タイム フォーマット GUID を受け取る変数へのポインタ。

戻り値

HRESULT 値を返す。返される値は次のとおり。

S_OK | 成功。
E_INVALIDARG | 範囲外のインデックス。
E_POINTER | NULL ポインタ引数。

注意

オブジェクトがサポートするタイム フォーマットの数を取得するには、GetNumTimeFormats メソッドを呼び出すこと。

IMediaParamInfo::GetCurrentTimeFormat

IMediaParamInfo インターフェイス

現在のタイム フォーマットを取得する。

構文

HRESULT GetCurrentTimeFormat(
    GUID *pguidTimeFormat,
    MP_TIMEDATA *pTimeData
);

パラメータ

pguidTimeFormat
[out] タイム フォーマット GUID を受け取る変数へのポインタ。
pTimeData
[out] 新しいフォーマットの単位を指定する MP_TIMEDATA 値を受け取る変数へのポインタ。

戻り値

HRESULT 値を返す。返される値は次のとおり。

S_OK | 成功。
E_POINTER | NULL ポインタ引数。

注意

pTimeData パラメータに返される値の意味は、タイム フォーマット GUID によって異なる。詳細については、「IMediaParams::SetTimeFormat」を参照すること。


IMediaParams インターフェイス

オブジェクトのエンベロープ フォロー パラメータを取得する。

オーバーヘッドを減らすために、パラメータはインデックス値によって参照され、すべてのパラメータ値は MP_DATA 型として定義される 32 ビットである。指定されたパラメータが整数、浮動小数点値、ブール値、または列挙型のメンバのいずれであるかを確認するには、IMediaParamInfo インターフェイスを使用する。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントの値を増やす。
Release | 参照カウントの値を減らす。
IMediaParams メソッド | 説明
GetParam | 指定されたパラメータの最新の値を取得する。
SetParam | パラメータの値を設定する。
AddEnvelope | パラメータにエンベロープを追加する。
FlushEnvelope | 指定されたパラメータのエンベロープ データを指定された時間の範囲でフラッシュする。
SetTimeFormat | オブジェクトのタイム フォーマットを指定する。

IMediaParams::GetParam

IMediaParams インターフェイス

指定されたパラメータの現在の値を取得する。パラメータが現在エンベロープ セグメント内にある場合は、戻り値は最後に処理されたサンプルの値である。

構文

HRESULT GetParam(
    DWORD dwParamIndex,
    MP_DATA *pValue
);

パラメータ

dwParamIndex
[in] パラメータのゼロベースのインデックス。
pValue
[out] パラメータ値を受け取る MP_DATA 型の変数へのポインタ。

戻り値

HRESULT 値を返す。返される値は次のとおり。

S_OK | 成功。
E_INVALIDARG | 範囲外のインデックス。
E_POINTER | NULL ポインタ引数。

注意

このオブジェクトによってサポートされるパラメータをインデックス値とともに列挙するには、IMediaParamInfo インターフェイスを使用すること。

IMediaParams::SetParam

IMediaParams インターフェイス

パラメータの値を設定する。

構文

HRESULT SetParam(
    DWORD dwParamIndex,
    MP_DATA value
);

パラメータ

dwParamIndex
[in] パラメータのゼロベースのインデックス、またはすべてのパラメータに値を適用する DWORD_ALLPARAMS。
value
[in] パラメータの新しい値。

戻り値

HRESULT 値を返す。返される値は次のとおり。

S_OK | 成功。
E_INVALIDARG | 範囲外のインデックス、またはパラメータ値が無効。

注意

パラメータが現在エンベロープ セグメント内にある場合、エンベロープ セグメントは新しい値をオーバーライドする。エンベロープ セグメントを削除するには、FlushEnvelope メソッドを呼び出すこと。

このオブジェクトによってサポートされるパラメータをインデックス値とともに列挙するには、IMediaParamInfo インターフェイスを使用すること。

IMediaParams::AddEnvelope

IMediaParams インターフェイス

パラメータにエンベロープを追加する。

構文

HRESULT AddEnvelope(
    DWORD dwParamIndex,
    DWORD cPoints,
    MP_ENVELOPE *pEnvelope,
);

パラメータ

dwParamIndex
[in] インデックスのゼロベースのインデックス、またはすべてのパラメータにエンベロープを追加する DWORD_ALLPARAMS。
cPoints
[in] エンベロープ内のセグメントの数。
pEnvelope
[in] エンベロープ セグメントを定義する MP_ENVELOPE 構造体の配列。配列のサイズは cPoints パラメータで指定する。

戻り値

HRESULT 値を返す。返される値は次のとおり。

S_OK | 成功。
E_INVALIDARG | 範囲外のインデックス。
E_OUTOFMEMEORY | メモリ不足。
E_POINTER | NULL ポインタ引数。

注意

エンベロープが既存のエンベロープとオーバーラップするときは、新しいエンベロープが優先される。

このオブジェクトによってサポートされるパラメータをインデックス値とともに列挙するには、IMediaParamInfo インターフェイスを使用すること。

IMediaParams::FlushEnvelope

IMediaParams インターフェイス

指定されたパラメータのエンベロープ データを指定された時間の範囲でフラッシュする。

構文

HRESULT FlushEnvelope(
    DWORD dwParamIndex,
    REFERENCE_TIME refTimeStart,
    REFERENCE_TIME refTimeEnd
);

パラメータ

dwParamIndex
[in] パラメータのゼロベースのインデックス、またはすべてのパラメータのエンベロープ データをフラッシュする DWORD_ALLPARAMS。
refTimeStart
[in] エンベロープ データのフラッシュを開始する時間。
refTimeEnd
[in] エンベロープ データのフラッシュを停止する時間。

戻り値

HRESULT 値を返す。返される値は次のとおり。

S_OK | 成功。
E_INVALIDARG | 範囲外のインデックス。

注意

refTimeStart と refTimeEnd によって指定された時間の範囲がエンベロープ セグメントでオーバーラップする場合は、セグメント全体がフラッシュされる。一方、エンベロープ セグメントの境界にあたる場合は、セグメント全体が保持される。つまり、次のようになる。

  • 開始タイムがエンベロープ セグメントの内側である場合は、セグメントはフラッシュされる。
  • 終了タイムがエンベロープ セグメントの内側である場合は、セグメントはフラッシュされる。
  • 開始タイムがエンベロープ セグメントの終了タイムに等しい場合は、セグメントは保持される。
  • 終了タイムがエンベロープ セグメントの開始タイムに等しい場合は、セグメントは保持される。

このオブジェクトによってサポートされるパラメータをインデックス値とともに列挙するには、IMediaParamInfo インターフェイスを使用すること。

IMediaParams::SetTimeFormat

IMediaParams インターフェイス

オブジェクトのタイム フォーマットを指定する。

構文

HRESULT SetTimeFormat(
    GUID guidTimeFormat,
    MP_TIMEDATA mpTimeData
);

パラメータ

guidTimeFormat
[in] タイム フォーマットを指定するタイム フォーマット GUID。
mpTimeData
[in] 新しいフォーマットの単位を指定する MP_TIMEDATA 型の値。

戻り値

HRESULT 値を返す。返される値は次のとおり。

S_OK | 成功。
E_DMOTIMESTAMPFORMAT | オブジェクトはこのタイム フォーマットをサポートしていない。

注意

オブジェクトは複数のタイム フォーマットをサポートできる。すべてのオブジェクトは、100 ナノ秒 (ns) 単位の基準タイムをサポートする必要がある。その他のフォーマットはオプションである。アプリケーションは、入力バッファのタイム スタンプが、このメソッドを使用して設定されたタイム フォーマットに一致することを保証しなければならない。

mpTimeData パラメータの値は、guidTimeFormat パラメータの値によって異なる。

タイム フォーマット | タイム データの意味
GUID_TIME_REFERENCE | 無視される。
GUID_TIME_MUSIC | 四分音符 1 個あたりのパート数。
GUID_TIME_SAMPLES | 1 秒あたりのサンプル数。

このメソッドを呼び出す場合は、FlushEnvelope メソッドも呼び出し、前のタイム フォーマットを使用して設定されたエンベロープをフラッシュする。

オブジェクトがどのタイム フォーマットをサポートしているかを確認するには、IMediaParamInfo::GetSupportedTimeFormat メソッドを呼び出す。現在のフォーマットを取得するには、IMediaParamInfo::GetCurrentTimeFormat メソッドを呼び出す。


構造体

ここでは、Microsoft® DirectX® のメディア パラメータ構造体について説明する。

構造体 | 説明
MP_ENVELOPE | エンベロープ フォロー パラメータによって使用されるエンベロープ セグメントを定義する。
MP_PARAMINFO | パラメータに関する情報を含む。


MP_ENVELOPE 構造体

構造体

エンベロープ フォロー パラメータによって使用されるエンベロープ セグメントを定義する。

構文

typedef struct _MP_ENVELOPE {
    REFERENCE_TIME   rtStart;
    REFERENCE_TIME   rtEnd;
    MP_DATA          valStart;
    MP_DATA          valEnd;
    MP_CURVE_TYPE    iCurve;
    MP_FLAGS         flags;
} MP_ENVELOPE;

メンバ

rtStart
セグメントの開始タイム。最初のバッファのタイム スタンプに対して相対的に、100 ナノ秒単位で表す。
rtEnd
セグメントの終了タイム。最初のバッファのタイム スタンプに対して相対的に、100 ナノ秒単位で表す。
valStart
セグメント開始時点でのパラメータの初期値。
valEnd
セグメント終了時点でのパラメータの最終値。
iCurve
パラメータがフォローする曲線を指定する MP_CURVE_TYPE 列挙型のメンバ。
フラグ
エンベロープ フラグのビット単位の組み合わせ。


MP_PARAMINFO 構造体

構造体

パラメータに関する情報を含む。

構文

typedef struct _MP_PARAMINFO {
    MP_TYPE    mpType;
    MP_CAPS    mopCaps;
    MP_DATA    mpdMinValue;
    MP_DATA    mpdMaxValue;
    MP_DATA    mpdNeutralValue;
    WCHAR      szUnitText[32];
    WCHAR      szLabel[32];
} MP_PARAMINFO;

メンバ

mpType
このパラメータの有効なデータ型を指定する MP_TYPE 列挙型のメンバ。
mopCaps
どのエンベロープ曲線がサポートされるかを指定する 1 つ以上の能力フラグのビット単位の組み合わせ。ブール型および列挙型パラメータでは MP_CAPS_CURVE_JUMP だけが有効である。
mpdMinValue
パラメータの最小値。数値を持つパラメータだけに使用する。
mpdMaxValue
パラメータの最大値。数値を持つパラメータだけに使用する。
mpdNeutralValue
パラメータのデフォルトまたは "中間" 値。
szUnitText
パラメータの単位の名前を含む NULL 終端 Unicode™ 文字列。
szLabel
パラメータの名前を含む NULL 終端 Unicode™ 文字列。

メンバ

szUnitText および szLabel メンバは、常に英語の文字列を含む。多言語サポートが必要な場合は、IMediaParamInfo::GetParamText メソッドを使用すること。


列挙型

ここでは、Microsoft® DirectX® のメディア パラメータ列挙型について説明する。

列挙型 | 説明
MP_CURVE_TYPE | エンベロープ セグメント内でメディア パラメータがフォローする曲線を定義する。
MP_TYPE | パラメータのデータ型を指定する。


MP_CURVE_TYPE 列挙

列挙型

エンベロープ セグメント内でメディア パラメータがフォローする曲線を定義する。

構文

typedef enum _MP_CURVE_TYPE {
    MP_CURVE_JUMP       = 0x0001,
    MP_CURVE_LINEAR     = 0x0002,
    MP_CURVE_SQUARE     = 0x0004,
    MP_CURVE_INVSQUARE  = 0x0008,
    MP_CURVE_SINE       = 0x0010,
    MP_CURVE_CURRENTVAL = 0x8000,
} MP_CURVE_TYPE;

要素

MP_CURVE_JUMP
補間なし。次のポイントへジャンプ。
MP_CURVE_LINEAR
リニア補間。
MP_CURVE_SQUARE
放物線曲線。
MP_CURVE_INVSQUARE
逆矩形曲線。
MP_CURVE_SINE
正弦曲線。
MP_CURVE_CURRENTVAL
このセグメントに対して指定された開始値を無視する。直前のセグメントの最終値から開始する。

注意

次の表は、あらかじめ定義されている曲線と各曲線の数学的表現の一覧である。

値 | 適合する曲線 | 範囲
MP_CURVE_LINEAR | y = x | 0.0 – 1.0
MP_CURVE_SQUARE | y = x2 | 0.0 – 1.0
MP_CURVE_INVSQUARE | y = 1 – x2 | 0.0 – 1.0
MP_CURVE_SINE | y = sin(x) | –π/2 – π/2

ブール型または列挙型パラメータでは MP_CURVE_JUMP だけが有効である。

参照

MP_ENVELOPE


MP_TYPE 列挙

列挙型

パラメータのデータ型を指定する。

構文

typedef enum _MP_Type {
    MPT_INT,
    MPT_FLOAT,
    MPT_BOOL,
    MPT_ENUM,
    MPT_MAX,
} MP_TYPE;

要素

MPT_INT
値は 32 ビットの符号付き整数である。
MPT_FLOAT
値は 32 ビットの IEEE 浮動小数点値である。
MPT_BOOL
値はブール値である。ブール型パラメータには次の定数を使用すること。
定数 | 説明
MP_DATA MPBOOL_TRUE | TRUE
MP_DATA MPBOOL_FALSE | FALSE
MPT_ENUM
値は連続する整数の組から取得される。
MPT_MAX
予約済み。

注意

実行時の型変換を少なくするために、すべてのパラメータは、MP_DATA として定義される 32 ビットの浮動小数点値を持つ。この列挙のメンバは、指定されたパラメータをどのように解釈するかを指定する。

参照

MP_PARAMINFO


定数

Microsoft® DirectX® メディア パラメータとして次の定数が定義されている。

  • パラメータ能力フラグ
  • エンベロープ フラグ

パラメータ能力フラグ

パラメータ能力フラグは、サポートされているエンベロープ曲線を指定する。

定数 | 説明
MP_CAPS_CURVE_JUMP | 補間を行わずに次のポイントへジャンプする。「MP_CURVE_JUMP」を参照すること。
MP_CAPS_CURVE_LINEAR | リニア補間。「MP_CURVE_LINEAR」を参照すること。
MP_CAPS_CURVE_SQUARE | 放物線曲線。「MP_CURVE_SQUARE」を参照すること。
MP_CAPS_CURVE_INVSQUARE | 逆矩形曲線。「MP_CURVE_INVSQUARE」を参照すること。
MP_CAPS_CURVE_SINE | 正弦曲線。「MP_CURVE_SINE」を参照すること。

エンベロープ フラグ

エンベロープ フラグは、エンベロープ セグメントに関する情報を指定する。

定数 | 説明
MPF_ENVLP_STANDARD | エンベロープ セグメントで提供されるすべての情報を使用する。
MPF_ENVLP_BEGIN_CURRENTVAL | 指定された開始値を無視する。現在の値から開始する。
MPF_ENVLP_BEGIN_NEUTRALVAL | 指定された開始値を無視する。中間値から開始する。「MP_PARAMINFO」を参照すること。

参照

MP_ENVELOPE


メディア パラメータ GUID

ここでは、Microsoft® DirectX® のメディア パラメータ用に定義されているグローバル一意識別子 (GUID) を示す。

  • タイム フォーマット GUID

タイム フォーマット GUID

次の表は、メディア パラメータのタイム フォーマットで使用する GUID の一覧である。

GUID | 説明
GUID_TIME_REFERENCE | 100 ナノ秒単位の基準タイム。
GUID_TIME_MUSIC | 四分音符 1 個あたりのパート数で表したミュージック タイム。
GUID_TIME_SAMPLES | 1 秒あたりのサンプル数。


付録

  • C によるフィルタ グラフの制御
  • 使用が禁止されているインターフェイス
  • DirectShow グラフ ファイル フォーマット
  • Filter Graph Markup Language (XGR)
  • 国際アナログ テレビのチューニング
  • マルチメディア ストリーミング
  • SMPTE タイムコード
  • Visual Basic での DirectShow の使い方
  • 関連情報


C によるフィルタ グラフの制御

Microsoft® DirectShow® アプリケーションを (C++ ではなく) C で書いているなら、メソッドを呼び出す際に vtable を使用しなければならない。以下の例は IUnknown::QueryInterface メソッドを C で書かれたアプリケーションから呼び出す方法を示す :

pGraph->lpVtbl->QueryInterface(pGraph, &IID_IMediaEvent, (void **)&pEvent);

以下は上記と等しい C++ の呼び出しである :

pGraph->QueryInterface(IID_IMediaEvent, (void **)&pEvent);

C ではインターフェイスは構造体として定義されている。lpVtbl メンバはインターフェイス メソッドの表 (vtable) へのポインタである。すべてのメソッドはインターフェイスへのポインタである追加パラメータを持っている。


使用が禁止されているインターフェイス

次のインターフェイスは使用が禁止されている。これらのインターフェイスは、既存のアプリケーションとの互換性を保つために引き続きサポートされるが、新しいアプリケーションではこれらのインターフェイスを使用するべきではない。

  • IAMovieSetup
  • IAMDevMemoryAllocator
  • IAMDevMemoryControl
  • IAMPhysicalPinInfo
  • ICaptureGraphBuilder
  • IDirectDrawFactory
  • IDirectDraw3
  • IDvdControl
  • IDvdInfo
  • IEnumRegFilters
  • IFilterMapper


IAMovieSetup インターフェイス

注 : このインターフェイスの使用は避けること。このインターフェイスは、以前のバージョンにおける AMovieDllRegisterServer および AMovieDllUnregisterServer という 2 つの関数で使用されていた。これらの関数に代わって現在は AMovieDllRegisterServer2 が使用されており、この関数は IAMovieSetup を必要としない。ただし、IAMovieSetup は、既存のアプリケーションとの後方互換性を保つために、継続してサポートされる。

Microsoft® ActiveMovie® 1.0 では、フィルタは次に示す自己レジストリ登録を実装していた。

  • DllRegisterServer 関数の内部で、フィルタの DLL が AMovieDllRegisterServer 関数を呼び出していた。この関数は、各フィルタの IAMovie インターフェイスについて照会し、IAMovieSetup::Register メソッドを呼び出す。
  • DllUnregisterServer 関数の内部で、フィルタの DLL が AMovieDllUnregisterServer 関数を呼び出していた。この関数も各フィルタの IAMovie インターフェイスを照会するが、IAMovieSetup::Unregister メソッドを呼び出す。

上に示したように、現在は AMovieDllRegisterServer2 関数を使用すべきである。この関数で登録されるフィルタは、IAMovieSetup を実装する必要はない。詳細については、「DirectShow オブジェクトの登録方法」を参照すること。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMovieSetup メソッド | 説明
Register | レジストリにフィルタを追加する。
Unregister | レジストリからフィルタを削除する。

IAMovieSetup::Register

IAMovieSetup インターフェイス

レジストリにフィルタを追加する。

構文

HRESULT Register(void);

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
S_OK または NOERROR | 成功。

注意

このメソッドは、フィルタ、そのピン、およびピンに関連付けられているメディア タイプを登録する。これを行うためには、IFilterMapper メソッドを使用するように実装する必要がある。その実装については、「CBaseFilter::Register」メンバ関数を参照すること。

IAMovieSetup::Unregister

IAMovieSetup インターフェイス

レジストリからフィルタを削除する。

構文

HRESULT Unregister(void);

戻り値

実装に応じた HRESULT 値を返す。HRESULT は、次の標準的な定数の 1 つか、または一覧に示されていないその他の値となる。
E_FAIL | 失敗。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
E_NOTIMPL | メソッドがサポートされていない。
S_OK または NOERROR | 成功。

注意

このメソッドでレジストリからフィルタを削除するには、IFilterMapper::UnregisterFilter メソッドを使用するようにこのメソッドを実装する必要がある。このメソッドは、ピンとメディア タイプも効率よく削除する。


IAMDevMemoryAllocator インターフェイス

注 このインターフェイスは古くなっている。それは AVI ファイルのハードウェア メモリへの直接読み込を要求するある古いハードウェア デコーダをサポートするために定義された。このインターフェイスによって PVI パーサーはダウンストリーム フィルタからメモリを割り当てることができるが、それ自身のアロケータを依然として提供する。新しいデバイスがこのインターフェイスをサポートする必要はない。

IAMDevMemoryAllocator インターフェイスによって、オンボード メモリ マネージャ オブジェクトを使用してサードパーティのメモリ アロケータを作成できる。多くの CODEC ハードウェア メーカーでは、CODEC にオンボード マップ メモリを装備することで、バッファ操作の効率を高めている。このインターフェイスではそのメモリを割り当て、GetDevMemoryObject メソッドを使用して、IAMDevMemoryControl インターフェイスをサポートするデバイス メモリ制御オブジェクトを取得する。同じデバイス ID を共有するデバイスがメモリを使用できる。

グローバル メモリ マネージャ オブジェクトは、このインターフェイスを利用することで、特定のデバイス上のメモリからメモリを割り当てる。

ピンにおいてオンボード メモリ アロケータの作成をサポートする必要がある場合は、このインターフェイスを実装する。ソース フィルタが、オンボード メモリを認識し、独自のアロケータを作成する必要がある場合は、このインターフェイスを照会し、メモリを要求し、デバイス メモリ制御オブジェクトを集成するアロケータを作成する。独自のアロケータを作成する必要がないソース フィルタの場合は、ダウンストリームのピンのアロケータをそのまま使用する。なお、このアロケータも、デバイス メモリ制御オブジェクトを集成する。ハードウェア ベースのフィルタは、集成されたアロケータのメソッドを呼び出すことによって、自身のオンボード メモリの使用を確認できる。

このインターフェイスは、オンボード メモリを装備した CODEC のメモリをアプリケーションで制御する必要がある場合に使用する。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMDevMemoryAllocator メソッド | 説明
GetInfo | メモリ機能に関する情報を取得する。
CheckMemory | アロケータの特定のデバイスがメモリ ポインタを割り当てているかどうかを調べる。
Alloc | メモリ バッファを割り当てる。
Free | 割り当て済みのメモリを解放する。
GetDevMemoryObject | カスタム アロケータで集成できるデバイス メモリ制御オブジェクトへの IUnknown インターフェイス ポインタを取得する。

IAMDevMemoryAllocator::Alloc

IAMDevMemoryAllocator インターフェイス

メモリ バッファを割り当てる。

構文

HRESULT Alloc(
    BYTE **ppBuffer,
    DWORD *pdwcbBuffer
);

パラメータ

ppBuffer
[out] 割り当てられたメモリ バッファのアドレスを受け取るポインタ。
pdwcbBuffer
[in, out] DWORD へのポインタ。入力値は割り当てるバイト数で、出力値は実際に割り当てられたバイト数である。

戻り値

目的のメモリ量が割り当てられた場合は S_OK を返す。メモリが使用できない場合は S_FALSE を返す。

注意

利用可能なプールからメモリのブロックを割り当てるには、このメソッドを呼び出す。

参照

IAMDevMemoryAllocator::Free

IAMDevMemoryAllocator::CheckMemory

IAMDevMemoryAllocator インターフェイス

アロケータの特定のインスタンス (デバイス) がメモリ ポインタを割り当てているかどうかを調べる。

構文

HRESULT CheckMemory(
    const BYTE *pBuffer
);

パラメータ

pBuffer
[in] 割り当て済みのメモリ バッファのアドレスへのポインタ。

戻り値

オンボード アロケータがメモリを割り当てている場合は S_OK を返す。割り当てていない場合は S_FALSE を返す。特定のデバイス上にメモリがあるが割り当てられていない場合も S_FALSE を返す。

注意

通常、ハードウェア フィルタはこのメソッドを使用して、ポインタが実際にオンボード メモリを指しているかどうかを調べる。

IAMDevMemoryAllocator::Free

IAMDevMemoryAllocator インターフェイス

割り当て済みのメモリを解放する。

構文

HRESULT Free(
    BYTE *pBuffer
);

パラメータ

pBuffer
[in] 割り当て済みのメモリへのポインタ。

戻り値

指定のアロケータがメモリを割り当てていない場合、つまり、CheckMemory を実行すると失敗する場合は、E_INVALIDARG を返す。

注意

このメソッドは、プールからメモリ ブロックを解放する。

IAMDevMemoryAllocator::GetDevMemoryObject

IAMDevMemoryAllocator インターフェイス

カスタム アロケータで集成できるデバイス メモリ制御オブジェクトへの IUnknown インターフェイス ポインタを取得する。

構文

HRESULT GetDevMemoryObject(
    IUnknown **ppUnkInner,
    IUnknown *pUnkOuter
);

パラメータ

ppUnkInner
[out] 新しく作成される制御オブジェクトの IUnknown へのポインタのアドレス。この内部 IUnknown インターフェイスは、外側のオブジェクトが破棄されるときに解放される。カスタム アロケータは、このポインタにおいて QueryInterface メソッドを呼び出し、IAMDevMemoryControl インターフェイスを取得する。
pUnkOuter
[in] カスタム アロケータの IUnknown インターフェイスへのポインタ。このインターフェイスは、カスタム アロケータ内部のデバイス メモリ制御オブジェクトを集成する。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

デバイス メモリ制御オブジェクトは、カスタム アロケータで集成する必要がある。これは、オンボード メモリを使用するレンダラが、新しいアロケータを受け取ると IAMDevMemoryControl を照会し、メモリが同じデバイスに基づくことを確認するからである。ハードウェア フィルタが受け取る IMemAllocator オブジェクトは、オンボード メモリを使用する場合も使用しない場合もあるので、このような状態が発生する。互換性のあるアロケータかどうかを判別するには、IAMDevMemoryControl インターフェイスを照会し、特定のメソッドにアクセスする。IAMDevMemoryControl は、IAMDevMemoryControl のメソッドを実装する集成オブジェクトを作成する。なお、このメソッドは、ハードウェアによってしばしば異なる。

外側のオブジェクトが集成化を実装する際の規則については、COM のドキュメントを参照すること。

IAMDevMemoryAllocator::GetInfo

IAMDevMemoryAllocator インターフェイス

メモリ機能に関する情報を取得する。

構文

HRESULT GetInfo(
    DWORD *pdwcbTotalFree,
    DWORD *pdwcbLargestFree,
    DWORD *pdwcbTotalMemory,
    DWORD *pdwcbMinimumChunk
);

パラメータ

pdwcbTotalFree
[out] 空きメモリの合計サイズへのポインタ。
pdwcbLargestFree
[out] 返された中で一番大きな空きメモリ サイズへのポインタ。
pdwcbTotalMemory
[out] 返されたメモリの合計サイズへのポインタ。
pdwcbMinimumChunk
[out] 返された中で最小のチャンク サイズへのポインタ。これによって、細分度とアラインメントの規則が決まる。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

このメソッドを使用すると、利用可能なメモリの合計量を検出できる。このメソッドは、デバイスで利用可能なオンボード メモリ全体の値を返す。複数のフィルタ (デバイス) がメモリを共有している場合は、その特定のデバイスで利用可能な量が返される。場合によってこの値は、オンボード メモリの全体量の一部である。この値は、実装によってそれぞれ異なる。たとえば、CODEC 上のオンボード メモリ マネージャは、カード上のオンボード メモリの 32 MB すべてにアクセスできる。しかし、IAMDevMemoryAllocator を個別に実装しているピンでは、このメモリの一部しか報告されない。


IAMDevMemoryControl インターフェイス

注 このインターフェイスは古くなっている。それは AVI ファイルのハードウェア メモリへの直接読み込を要求するある古いハードウェア デコーダをサポートするために定義された。このインターフェイスによって PVI パーサーはダウンストリーム フィルタからメモリを割り当てることができるが、それ自身のアロケータを依然として提供する。新しいデバイスがこのインターフェイスをサポートする必要はない。

デバイス メモリ制御オブジェクトは IAMDevMemoryControl をサポートする。このオブジェクトは接続に使われる IMemAllocator オブジェクトで集成されている。通常、フィルタは IAMDevMemoryAllocator::GetDevMemoryObject メソッドを呼び出して、このインターフェイスへのポインタを取得する。

ピンにおいてメモリの割り当てを詳細に制御する必要がある場合は、IAMDevMemoryAllocator インターフェイスと共にこのインターフェイスを実装する。

このインターフェイスを使用すると、メモリ アロケータへのデータの書き込み終了の同期をとり、オンボード メモリ アロケータのデバイス ID を取得できる。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMDevMemoryControl メソッド | 説明
QueryWriteSync | アロケータがサポートしているメモリが、WriteSync メソッドの使用を必要とするかどうかを確認する。
WriteSync | 指定のアロケータ リージョンに書き込まれているデータがメモリに完全に書き込まれたら返ることによって、書き込み処理の終了の同期をとる。
GetDevId | オンボード メモリ アロケータのデバイス ID を取得する。

IAMDevMemoryControl::GetDevId

IAMDevMemoryControl インターフェイス

オンボード メモリ アロケータのデバイス ID を取得する。

構文

HRESULT GetDevId(
  DWORD *pdwDevId
  );

パラメータ

pdwDevId
[out] デバイス ID へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

このメソッドは、一意な ID を取得する。ハードウェア フィルタはこの ID を使用して、渡された指定のアロケータが自身のオンボード メモリを使用していることを確認できる。このような確認が行われるのは、複数のオンボード メモリが存在するからである。ID は、CoCreateInstance を使用してアロケータ オブジェクトを作成するときに使用された ID と同じものである。ほかのフィルタがオンボード メモリを使用するには、オンボード メモリ アロケータと同じデバイス ID を持つ必要がある。

IAMDevMemoryControl::QueryWriteSync

IAMDevMemoryControl インターフェイス

アロケータがサポートしているメモリが、IAMDevMemoryControl::WriteSync メソッドの使用を必要とするかどうかを調べる。

構文

HRESULT QueryWriteSync(void);

戻り値

メソッドが必要な場合は S_OK を返す。それ以外の場合は S_FALSE を返す。

注意

WriteSync を呼び出して書き込み終了の同期をとる必要がないオンボード メモリもある。このメソッドは、その呼び出しが必要かどうかを調べるために使用する。

IAMDevMemoryControl::WriteSync

IAMDevMemoryControl インターフェイス

書き込み終了の同期をとるために使用する。このメソッドは、特定のアロケータ リージョンに書き込まれているデータが、メモリに完全に書き込まれると返される。

構文

HRESULT WriteSync(void);

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。一般的な戻り値は次のとおりである。
E_FAIL | データが書き込まれたことをこのメソッドが確認する前にタイムアウトが発生した。
S_OK | データがメモリに書き込まれた。
VFW_E_NOT_COMMITTED | アロケータが IMemAllocator::Commit メソッドを呼び出していない。

注意

このメソッドでは、割り当て済みのメモリへのこれまでのすべての書き込み処理が、正常に終了していることが前提である。以降のメモリ書き込み処理では、WriteSync を新たに呼び出す必要がある。

このメソッドは実装によってそれぞれ異なり、メモリへの書き込み処理の同期をとるために、必要に応じて使用される。オンボード メモリのドライバが実装を提供する。

IAMDevMemoryControl インターフェイスは、通常、PCI (Peripheral Component Interconnect) ブリッジを介してアクセスされるメモリ上にある。PCI はパーソナル コンピュータ用のローカル バスで、プロセッサと周辺機器との間の高速なデータ パスを提供する。PCI ブリッジに接続しているメモリは、やはり PCI ブリッジに接続している別のデバイスがメモリにアクセスしてくる場合、メモリ書き込み処理の終了後に同期をとる必要がある。これは、メモリにアクセスするホストは PCI ブリッジの FIFO (先入れ先出し) フォーマットでバッファリングされ、書き込みが完了してからブリッジが実際にデータを書き込むことを前提にしているためである。IAMDevMemoryControl::WriteSync メソッドが呼び出されない場合は、SCSI コントローラなど、ブリッジに接続しているデバイスが、書き込みが完了する前にメモリを読み取ることがある。


IAMPhysicalPinInfo インターフェイス

注 : このインターフェイスの使用は避けること。既存のアプリケーションとの後方互換性を保つため、継続してサポートされるが、新しいアプリケーションおよびフィルタでは、これを使用してはならない。

このインターフェイスによって、アプリケーションまたはフィルタは、物理ピンのタイプと名前を取得できる。このインターフェイスは、物理的なハードウェア接続に相当するピンで実装される。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMPhysicalPinInfo メソッド | 説明
GetPhysicalType | 物理ピンのタイプと名前を取得する。

IAMPhysicalPinInfo::GetPhysicalType

IAMPhysicalPinInfo インターフェイス

物理ピンのタイプと名前を取得する。

構文

HRESULT GetPhysicalType(
    long *pType
     LPOLESTR *ppszType
);

パラメータ

pType
[out] ピンのタイプを示す値を受け取る変数へのポインタ。ピンのタイプ値は、PhysicalConnectorType 列挙型で定義される。
ppszType
[out] ピンのタイプをわかりやすく示した文字列を受け取るバッファへのポインタのアドレス。

戻り値

有効なピンの値が見つかった場合は、S_OK を返す。それ以外の場合は、VFW_E_NO_ACCEPTABLE_TYPES を返す。


ICaptureGraphBuilder インターフェイス

注 : このインターフェイスの使用は避けること。既存のアプリケーションとの後方互換性を保つため、継続してサポートされるが、新しいアプリケーションでは ICaptureGraphBuilder2 インターフェイスを使用すること。

ICaptureGraphBuilder インターフェイスを利用すると、キャプチャ グラフ、プレビュー グラフ、ファイル再圧縮グラフ、または特殊なカスタム グラフまで簡単に作成できる。

このインターフェイスを使って、WDM フィルタを使用するキャプチャ グラフを作成するときは、TV チューナー フィルタやアナログ ビデオ クロスバー フィルタなど、特別なアップストリーム フィルタをグラフに追加する必要がある。これらのフィルタは、RenderStream メソッドや FindInterface を呼び出して、キャプチャ フィルタのピンをレンダリングしたとき、フィルタ グラフに組み込まれる。

このインターフェイスを実装しないこと。このインターフェイスは Microsoft® DirectShow® が自動的に実装する。

キャプチャ アプリケーションおよび再圧縮アプリケーションでこのインターフェイスを使って、フィルタ グラフの作成を簡易化する。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
ICaptureGraphBuilder メソッド | 説明
SetFiltergraph | 使用するフィルタ グラフをグラフ ビルダ オブジェクトに通知する。
GetFiltergraph | ビルダが使用しているフィルタ グラフを取得する。
SetOutputFileName | 指定されたファイル名でビットをディスクに保存するフィルタ グラフのレンダリング セクションを作成する。
FindInterface | 指定されたインターフェイスをフィルタ、フィルタのアップストリームおよびダウンストリームで検索する。また、オプションで、指定されたインターフェイスを特定のカテゴリの出力ピンでのみ検索する。
RenderStream | オプションで指定されるカテゴリのソース フィルタのピンを、オプションでほかのフィルタを経由して、レンダリング フィルタに接続する。
ControlStream | グラフ内の 1 つ以上のキャプチャ フィルタ上の指定されたカテゴリのピンにストリーム コントロール メッセージを送る。
AllocCapFile | キャプチャ ファイルを指定されたサイズにあらかじめ割り当てる。
CopyCaptureFile | あらかじめ割り当てられたキャプチャ ファイルから有効なメディア データをコピーする。

ICaptureGraphBuilder::AllocCapFile

ICaptureGraphBuilder インターフェイス

キャプチャ ファイルを指定されたサイズにあらかじめ割り当てる。

構文

HRESULT AllocCapFile(
    LPCOLESTR lpwstr,
    DWORDLONG dwlSize
);

パラメータ

lpwstr
[in] 作成する、またはサイズを変更するファイルの名前が格納された Unicode™ 文字列へのポインタ。
dwSize
[in] 割り当てられるファイルのサイズ (バイト単位)。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

ファイルが読み取り専用の場合、この呼び出しは失敗する。キャプチャで最良の結果を得るには、常に、キャプチャ データよりサイズが大きく、最適化され、あらかじめ割り当てられたキャプチャ ファイルにキャプチャする。

このインターフェイスの現在の DirectShow 実装環境では、Windows NT® 4.x プラットフォーム上または Windows 2000 プラットフォーム上より、Windows 9x プラットフォーム上の方がこのメソッドの呼び出しがずっと高速である点に注意すること。

ICaptureGraphBuilder::ControlStream

ICaptureGraphBuilder インターフェイス

グラフ内の 1 つ以上のキャプチャ フィルタ上の指定されたカテゴリのピンにストリーム コントロール メッセージを送る。

構文

HRESULT ControlStream(
    const GUID *pCategory,
    IBaseFilter *pFilter,
    REFERENCE_TIME *pstart,
    REFERENCE_TIME *pstop,
    WORD wStartCookie,
    WORD wStopCookie
);

パラメータ

pCategory
[in] 出力ピン カテゴリを指定する GUID へのポインタ。通常は、次の値が含まれる。すべてのピン カテゴリの一覧については、「AMPROPERTY_PIN_CATEGORY」を参照すること。この値を NULL にすることはできない。
  • PIN_CATEGORY_CAPTURE
  • PIN_CATEGORY_PREVIEW
pFilter
[in] 制御するフィルタの IBaseFilter インターフェイスへのポインタ。NULL を指定すると、グラフ内のすべてのキャプチャ フィルタが制御される。各キャプチャ フィルタにつき 1 つの通知が取得される。
pstart
[in] キャプチャの開始タイムへのポインタ。NULL は今すぐ開始することを意味する。MAX_TIME は前の要求をキャンセルするか、前の要求がない場合は、何もしないことを意味する。
pstop
[in] キャプチャの終了タイムへのポインタ。NULL は今すぐ終了することを意味する。MAX_TIME は前の要求をキャンセルするか、前の要求がない場合は、何もしないことを意味する。
wStartCookie
[in] 開始動作が起きたときに送る特定の値を指定する。
wStopCookie
[in] 終了動作が起きたときに送る特定の値を指定する。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。現在実装されている DirectShow は、キャプチャ フィルタから送られた最後のサンプルがレンダリングされる前に終了通知が送られると S_FALSE を返し、それ以外の場合は S_OK を返す。

このメソッドが S_FALSE を返した場合、アプリケーションは、すべてのサンプルがグラフを通過してレンダリングされるまで、フィルタ グラフの終了を待機した方がよい。そうしないと、サンプルが失われることがある。

指定した説明に一致するピンがない場合、または指定されたピンの一部がストリーム コントロールをサポートできない場合、この関数は失敗コードを返す。

注意

このメソッドは、フレーム単位の精度が要求されるキャプチャや、個別のキャプチャ動作およびプレビュー動作の制御に使用する。たとえば、キャプチャ画像のプレビューだけを行うときは、ディスクへのキャプチャ画像の書き込みをオフにすることができる。

このメソッドは、ピンの IAMStreamControl インターフェイスを呼び出す。

このメソッドは、指定されたカテゴリのピンで見つかった各フィルタにつき 1 つの通知を送る。

ICaptureGraphBuilder::CopyCaptureFile

ICaptureGraphBuilder インターフェイス

あらかじめ割り当てられたキャプチャ ファイルから有効なメディア データをコピーする。

構文

HRESULT CopyCaptureFile(
    LPOLESTR lpwstrOld,
    LPOLESTR lpwstrNew,
    int fAllowEscAbort,
    IAMCopyCaptureFileProgress *pCallback
);

パラメータ

lpwstrOld
[in] コピー元ファイル名が格納された Unicode™ 文字列へのポインタ。
lpwstrNew
[in] コピー先ファイル名が格納された Unicode™ 文字列へのポインタ。このファイルに有効なデータがコピーされる。
fAllowEscAbort
[in] Esc キーを押すとコピー操作が中断されるかどうかを示す値。TRUE は中断されることを示し、FALSE はこのメソッドが Esc キー操作を無視することを示す。
pCallback
[in] コピー操作の進行状況 (パーセント単位の達成率) を表示するために実装する IAMCopyCaptureFileProgress インターフェイスへのオプションのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

新しいファイルには有効なデータのみが格納されるため、コピー元ファイルより新しいファイルの方がずっと小さくなることがある。通常は、常に、あらかじめ割り当てられた同じサイズの大きいファイルにキャプチャし、このメソッドを使って、各キャプチャから保存したいデータだけを新しいファイルにコピーする。

pCallback を指定した場合は、パーセント単位の達成率に相当する 0 から 100 の間の整数を指定して IAMCopyCaptureFileProgress インターフェイスの Progress メソッドを定期的に呼び出す。

ICaptureGraphBuilder::FindInterface

ICaptureGraphBuilder インターフェイス

指定されたインターフェイスをフィルタ、フィルタのアップストリームおよびダウンストリームで検索する。また、オプションで、指定されたインターフェイスを特定のカテゴリの出力ピンでのみ検索する。

構文

HRESULT FindInterface(
    const GUID *pCategory,
    IBaseFilter *pf,
    REFIID riid,
    void **ppint
);

パラメータ

pCategory
[in] 出力ピン カテゴリを指定する GUID へのポインタ。通常は、次の値が含まれる。すべてのピン カテゴリの一覧については、「AMPROPERTY_PIN_CATEGORY」を参照すること。NULL は、カテゴリに関係なく、すべての出力ピンを検索することを示す。
  • PIN_CATEGORY_CAPTURE
  • PIN_CATEGORY_PREVIEW
  • NULL
pf
[in] フィルタの IBaseFilter インターフェイスへのポインタ。
riid
[in] 目的のインターフェイスの参照識別子。
ppint
[out] 空のポインタのアドレス。インターフェイスが見つかった場合、このメソッドは ppint を初期化して、見つかったインターフェイスへのポインタのアドレスを ppint に格納できるようにする。インターフェイスを使用した後は、Release メソッドを呼び出して参照カウントをデクリメントする。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

このメソッドは、カテゴリが指定されていない限り、フィルタ、フィルタのアップストリームおよびダウンストリームでインターフェイスを検索する。カテゴリが指定されている場合、このメソッドは、そのカテゴリの出力ピンのダウンストリームのみを検索の対象とする。このメソッドを使って、レンダラ、マルチプレクサ、TV チューナー、クロスバーなどを対象としてインターフェイスを検索できる。

pCategory == &LOOK_UPSTREAM_ONLY である場合、グラフ ビルダは、pf パラメータで指定されているフィルタのアップストリームを検索の対象とするが、フィルタ自体やフィルタのダウンストリームは検索の対象としない。

pCategory == &LOOK_DOWNSTREAM_ONLY である場合、グラフ ビルダは、pf パラメータで指定されているフィルタのダウンストリームを検索の対象とするが、フィルタ自体やフィルタのアップストリームは検索の対象としない

たとえば、キャプチャ グラフは、ビデオ クロスバー (ビデオ キャプチャ フィルタのアップストリーム) とオーディオ クロスバー (ビデオ クロスバーのアップストリーム) の 2 つのクロスバーを備えていることがある。次に示すコードによって、IAMCrossbar インターフェイスを実装するビデオ クロスバー フィルタを検索できる。

IAMCrossbar *pVideoCrossbar;
FindInterface(NULL, pVideoCaptureFilter, IID_IAMCrossbar, (void **)&pVideoCrossbar);

さらに、次に示すコードによって、オーディオ クロスバーの IAMCrossbar フィルタを検索できる。

IBaseFilter *pBaseFilter;
IAMCrossbar *pAudioCrossbar;
pVideoCrossbar->QueryInterface(IID_IBaseFilter, (void **)pBaseFilter);
FindInterface(
    &LOOK_UPSTREAM_ONLY, pBaseFilter, IID_IAMCrossbar, (void **)&pAudioCrossbar);
pBaseFilter->Release();

ICaptureGraphBuilder::GetFiltergraph

ICaptureGraphBuilder インターフェイス

ビルダが使用しているフィルタ グラフを取得する。

構文

HRESULT GetFiltergraph(
    IGraphBuilder **ppfg
);

パラメータ

ppfg
[out] IGraphBuilder インターフェイスへのポインタのアドレス。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

このメソッドは IGraphBuilder インターフェイスの参照カウントをインクリメントする。必ず Release メソッドを呼び出して、IGraphBuilder の参照カウントをデクリメントすること。

ICaptureGraphBuilder::RenderStream

ICaptureGraphBuilder インターフェイス

オプションで指定されるカテゴリのソース フィルタのピンを、オプションでほかのフィルタを経由して、レンダリング フィルタに接続する。

構文

HRESULT RenderStream(
    const GUID *pCategory,
    IUnknown *pSource,
    IBaseFilter *pfCompressor,
    IBaseFilter *pfRenderer
);

パラメータ

pCategory
[in] ソース フィルタのどの出力ピンを接続するかを指定する GUID へのポインタ。通常は、次の値が含まれる。すべてのピン カテゴリの一覧については、「AMPROPERTY_PIN_CATEGORY」を参照すること。NULL は、カテゴリに関係なく、出力ピンのみをレンダリングすることを示す。
  • PIN_CATEGORY_CAPTURE
  • PIN_CATEGORY_PREVIEW
  • NULL
pSource
[in] ソース フィルタまたは出力ピンに相当する IBaseFilter インターフェイスまたは IPin インターフェイスへのポインタ。ソース フィルタは、通常、AVI ファイル ソース フィルタやキャプチャ フィルタなどのファイル ソース フィルタである。
pfCompressor
[in] オプションの圧縮フィルタに相当する IBaseFilter インターフェイスへのポインタ。
pfRenderer
[in] レンダラに相当する IBaseFilter インターフェイスへのポインタ。ICaptureGraphBuilder::SetOutputFileName の ppf (マルチプレクサ) パラメータを使用して、この値を渡すことができる。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。キャプチャ フィルタにキャプチャ ピンはあるが、プレビュー ピンがない場合、キャプチャ ピンに対して &PIN_CATEGORY_PREVIEW カテゴリを指定して RenderStream を呼び出すと、VFW_S_NOPREVIEWPIN が返される。その場合、RenderStream はスマート ティー フィルタのプレビュー ピンをレンダリングする。 詳細については、「注意」を参照すること。

注意

pCategory として NULL 以外の AMPROPERTY_PIN_CATEGORY を指定し、pSource としてキャプチャ フィルタを指定した場合、このメソッドは、TV チューナーやクロスバーなど、必要とされる追加のアップストリーム フィルタのインスタンスを生成し、それらのフィルタを接続する。次に、このメソッドは、pSource のキャプチャ ピンをレンダリングする。

pSource がピンの場合は、pCategory として NULL を指定すると、このメソッドは、そのピンのストリームをレンダリングする。

ソース フィルタに出力ピンが 1 つしかない場合は、pCategory として NULL を指定する。

パラメータとして指定された pSource フィルタ、pfCompressor フィルタおよび pfRenderer フィルタは、このメソッドが呼び出される前にグラフ内に存在している必要がある。

WDM キャプチャ フィルタを使用するキャプチャ グラフを作成する場合、このメソッドは、すべての必要なアップストリーム フィルタおよびダウンストリーム フィルタを作成する。

新しい WDM VPE (ビデオ ポート エクステンション) ビデオ キャプチャ ハードウェアを使用する一部のキャプチャ フィルタは、プレビュー用として PREVIEW ピンの代わりに VIDEO PORT ピンを備えている。これらの VIDEO PORT ピンは、ビデオ レンダラに直接接続されず、オーバーレイ ミキサーと呼ばれる特殊なフィルタに接続される。アプリケーションは、この点を考慮に入れる必要はない。&PIN_CATEGORY_PREVIEW を指定して RenderStream を呼び出せば、必要な場合には、キャプチャ グラフ ビルダがオーバーレイ ミキサーを通じて VIDEO PORT ピンを正しくレンダリングする。

&PIN_CATEGORY_CAPTURE カテゴリまたは &PIN_CATEGORY_PREVIEW カテゴリを指定して RenderStream を使用し、ビデオ キャプチャ フィルタのキャプチャ ピンまたはプレビュー ピンをレンダリングする場合で、キャプチャ フィルタにキャプチャ ピンはあるが、プレビュー ピンがない場合は、スマート ティー フィルタ (Qcap.dll) が自動的に使用され、キャプチャとプレビューが同時に行われる。たとえば、&PIN_CATEGORY_CAPTURE カテゴリを指定して RenderStream を呼び出すと、フィルタのキャプチャ ピンにスマート ティー フィルタが実際に接続され、スマート ティーのキャプチャ ピンがレンダリングされる。次に、&PIN_CATEGORY_PREVIEW カテゴリを指定して RenderStream を呼び出すと、実際にスマート ティーのプレビュー ピンがレンダリングされる。&PIN_CATEGORY_PREVIEW を指定して RenderStream を呼び出した結果、キャプチャ ピンとスマート ティー フィルタが使用された場合、RenderStream は VFW_S_NOPREVIEWPIN を返すことによってそれを示す。したがって、FindInterface がプレビュー インターフェイスを見つけられない場合は、キャプチャ フィルタのキャプチャ ピンのダウンストリームでプレビュー インターフェイスが見つかることがあるため、&PIN_CATEGORY_PREVIEW カテゴリと &PIN_CATEGORY_CAPTURE カテゴリを指定して FindInterface を呼び出す必要が生じることがある。

ICaptureGraphBuilder::SetFiltergraph

ICaptureGraphBuilder インターフェイス

使用するフィルタ グラフをグラフ ビルダ オブジェクトに通知する。

構文

HRESULT SetFiltergraph(
    IGraphBuilder *pfg
);

パラメータ

pfg
[in] これ以降の IFilterGraph::AddFilter メソッドの呼び出しで使用するフィルタ グラフを指定する IGraphBuilder インターフェイスへのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。

注意

このメソッドを呼び出さない場合は、グラフ ビルダが自動的にフィルタ グラフを作成する。グラフ ビルダが独自のフィルタ グラフを作成した後で、このメソッドを呼び出すと、呼び出しは失敗する。

ICaptureGraphBuilder::SetOutputFileName

ICaptureGraphBuilder インターフェイス

指定されたファイル名でビットをディスクに保存するフィルタ グラフのレンダリング セクションを作成する。

構文

HRESULT SetOutputFileName(
    const GUID *pType,
    LPCOLESTR lpwstrFile,
    IBaseFilter **ppf,
    IFileSinkFilter **pSink
);

パラメータ

pType
[in] メディア サブタイプを表す GUID へのポインタ。現在サポートされている唯一の出力フォーマットは AVI であるため、これは &MEDIASUBTYPE_Avi でなければならない。
lpwstrFile
[in] 出力ファイル名が格納されている Unicode™ 文字列へのポインタ。
ppf
[out] マルチプレクサ フィルタに相当する IBaseFilter インターフェイスへのポインタのアドレス。このメソッドは IBaseFilter インターフェイスの参照カウントをインクリメントため、フィルタを使用した後は、このパラメータに対して Release メソッドを使用することによって、参照カウントをデクリメントする必要がある。
pSink
[out] フィルタ ライタに相当する IFileSinkFilter インターフェイスへのポインタのアドレス。このメソッドは IFileSinkFilter インターフェイスの参照カウントをインクリメントするため、フィルタを使用した後は、このパラメータに対して Release メソッドを使用することによって、参照カウントをデクリメントする必要がある。

戻り値

操作の状態を示す HRESULT 値を返す。
E_FAIL | 失敗。
E_INVALIDARG | 無効な引数。サポートされている出力フォーマットは AVI (Audio-Video Interleaved) のみである。
E_OUTOFMEMORY | メモリ不足。
E_POINTER | Null ポインタ引数。
E_UNEXPECTED | 予期しないエラーが発生した。
NOERROR | 成功。
S_OK | AVI マルチプレクサ フィルタのインスタンスが正しく作成された。

注意

このメソッドは、マルチプレクサとファイル ライタをフィルタ グラフに挿入し、IFileSinkFilter::SetFileName を呼び出して出力ファイル名を設定する。

このメソッドから返される ppf パラメータを RenderStream の呼び出しで pfRenderer パラメータとして使うことができる。

このメソッドの pSink パラメータを SetFileName の呼び出しで使って、ICaptureGraphBuilder::SetOutputFileName によって設定されたファイル名を変更できる。


IDirectDrawFactory インターフェイス

注 : このインターフェイスの使用は避けること。新しいアプリケーションで使用してはならない。

IDirectDrawFactory インターフェイスは、拡張機能をサポートする DirectDraw オブジェクトを作成および列挙するために使用される。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IDirectDrawFactory メソッド | 説明
CreateDirectDraw | DirectDraw オブジェクトを作成し、IUnknown インターフェイスと IDirectDraw インターフェイスへのポインタを取得する。
DirectDrawEnumerate | システムにインストールされている DirectDraw サーフェスを列挙する。

IDirectDrawFactory::CreateDirectDraw

IDirectDrawFactory インターフェイス

DirectDraw オブジェクトを作成し、その IDirectDraw インターフェイスへのポインタを取得する。

構文

STDMETHOD CreateDirectDraw(
    GUID *pGUID,
    HWND hWnd,
    DWORD dwCoopLevelFlags,
    DWORD dwReserved,
    IUnknown *pUnkOuter,
    IDirectDraw **ppDirectDraw
) PURE;

パラメータ

pGUID
[out] 作成するドライバを表すグローバル ユニーク識別子 (GUID) へのポインタ。アクティブなディスプレイ ドライバを指定するには、NULL を設定する。また、デバッグのためにアクティブなディスプレイ ドライバの動作を制限するには、次のフラグの 1 つを渡す。
DDCREATE_EMULATIONONLY | すべての機能を DirectDraw オブジェクトでエミュレートする。ハードウェアがサポートする機能は利用しない。
DDCREATE_HARDWAREONLY | ハードウェアがサポートしない機能を DirectDraw オブジェクトでエミュレートしない。サポートされていない機能が必要なメソッドを呼び出すと、失敗し、DDERR_UNSUPPORTED (操作がサポートされていない) が返される。
hWnd
[in] アプリケーションのウィンドウ ハンドル。
dwCoopLevelFlags
[in] アプリケーションの最上位動作。以下のフラグを 1 つ以上指定する。
DDSCL_ALLOWMODEX | モード X ディスプレイ モードを使用可能にする。このフラグは、DDSCL_EXCLUSIVE フラグおよび DDSCL_FULLSCREEN フラグと共に使用しなければならない。
DDSCL_ALLOWREBOOT | アプリケーションがフルスクリーン モードかつ排他モードのときに、ユーザーが Ctrl + Alt + Del キーを押して再起動できるようにする。
DDSCL_EXCLUSIVE | 排他レベルを要求する。このフラグは、DDSCL_FULLSCREEN フラグと共に使用しなければならない。フルスクリーンかつ排他協調レベルでは、ハードウェアを最大限利用できる。このモードでは、カスタム パレットや動的パレットの設定、ディスプレイ解像度の変更、メモリの圧縮、およびページ フリッピングの実現ができる。排他 (フルスクリーン) モードでは、ほかのアプリケーションから、サーフェスを割り当てることもできるし、DirectDraw や GDI を使用することもできる。ただし、排他モードでは、そのとき排他アクセスを持っているアプリケーション以外のアプリケーションから、ディスプレイ モードやパレットを変更できない。
DDSCL_FULLSCREEN | 排他モードの所有者がプライマリ サーフェス全体を制御することを示す。このフラグは、DDSCL_EXCLUSIVE フラグと共に使用しなければならない。
DDSCL_NORMAL | アプリケーションが通常の Microsoft® Windows® アプリケーションとして動作することを示す。このフラグを DDSCL_ALLOWMODEX、DDSCL_EXCLUSIVE、または DDSCL_FULLSCREEN フラグと共に使用することはできない。
DDSCL_NOWINDOWCHANGES | アプリケーションがアクティブになったときに、DirectDraw がアプリケーション ウィンドウを最小化または復元できないことを示す。
dwReserved
[in] 将来の使用に備えて予約されている。NULL でなければならない。
pUnkOuter
[in] NULL でなければならない。将来の COM 集約機能との互換性のために用意されている。現時点では、このパラメータが NULL でない場合、CreateDirectDraw はエラーを返す。
ppDirectDraw
[out] IDirectDraw インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、DD_OK を返す。それ以外の場合は、次のいずれかのエラー値を返す。

E_OUTOFMEMORY | メモリ不足のため、DirectDraw オブジェクトを作成できない。
DDERR_GENERIC | 未定義のエラー状態である。
DDERR_UNSUPPORTED | 処理が DirectDraw でサポートされていない。
DDERR_DIRECTDRAWALREADYCREATED | このドライバを表す DirectDrawEx オブジェクトが、このプロセスで既に作成されていることを表す。
DDERR_INVALIDDIRECTDRAWGUID | このメソッドに渡された GUID が、DirectDrawEx ドライバの有効な識別子でない。
DDERR_INVALIDPARAMS | メソッドに渡された 1 つ以上のパラメータが不正である。
DDERR_NODIRECTDRAWHW | ハードウェア専用 DirectDrawEx オブジェクトを作成できない。ドライバはハードウェアをサポートしない。

注意

このメソッドは、DirectDraw の DirectDrawCreate 関数を使用して DirectDraw オブジェクトを作成するのと同じ方法で、DirectDraw オブジェクトを作成する。さらに、IDirectDraw2::SetCooperativeLevel メソッドが協調レベルを設定するのと同じ方法で、協調レベルを設定する。ただし、IDirectDrawFactory::CreateDirectDraw メソッドの呼び出しが成功すると、DirectDraw オブジェクトが作成されるだけでなく、DirectDraw オブジェクトが公開する IUnknown インターフェイスと IDirectDraw インターフェイスへのポインタが得られる。現在では、アプリケーションから DirectDraw オブジェクトに照会することによって、IDirectDraw3 インターフェイスへのポインタのアドレスを取得できる。

IDirectDrawFactory::DirectDrawEnumerate

IDirectDrawFactory インターフェイス

システム内の利用可能な DirectDraw 互換デバイスを列挙する。

構文

STDMETHOD DirectDrawEnumerate(
    LPDDENUMCALLBACK lpCallback,
    LPVOID lpContext
) PURE;

パラメータ

lpCallback
[in] システム内の DirectDrawEx で有効なハードウェア アブストラクション レイヤ (HAL) それぞれの記述で呼び出される DDEnumCallback 関数へのポインタ。
lpContext
[in] 関数を呼び出すたびにコールバック関数に渡されるアプリケーション定義構造体のアドレス。

戻り値

失敗した場合は、DD_OKを返す。それ以外の場合は、DDERR_INVALIDPARAMS を返す。

注意

このメソッドは、DirectX SDK で定義されている DirectDraw の DirectDrawEnumerate 関数に似た役割をする。


IDirectDraw3 インターフェイス

注 : このインターフェイスの使用は避けること。新しいアプリケーションで使用してはならない。

IDirectDraw3 インターフェイスは、IDirectDrawFactory::CreateDirectDraw メソッドを通じて DirectDraw オブジェクトを作成したアプリケーションから利用できる。このメソッドは、IDirectDraw インターフェイスへのポインタのアドレスを取得する。アプリケーションでは、これを使って IDirectDraw3 インターフェイスを照会することができる。

IDirectDraw3 インターフェイスは、IDirectDraw3::GetSurfaceFromDC メソッドを追加し、IDirectDraw3::CreateSurface メソッドで異なった動作を提供することにより、IDirectDraw インターフェイスと IDirectDraw2 インターフェイスを拡張したものである。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IDirectDraw3 メソッド | 説明
CreateSurface | DirectDraw オブジェクトから DirectDrawSurface オブジェクトを作成する。
GetSurfaceFromDC | デバイス コンテキストのハンドルから IDirectDrawSurface インターフェイスへのポインタを取得する。

IDirectDraw3::CreateSurface

IDirectDraw3 インターフェイス

DirectDraw オブジェクトから DirectDrawSurface オブジェクトを作成する。

構文

STDMETHOD CreateSurface(
    LPDDSURFACEDESC lpDDSurfaceDesc,
    LPDIRECTDRAWSURFACE FAR *lplpDDSurface,
    IUnknown FAR *pUnkOuter
) PURE;

パラメータ

lpDDSurfaceDesc
[in] 要求するサーフェスを記述する DDSURFACEDESC 構造体へのポインタ。このメソッドを呼び出す前に、使用しない DDSURFACEDESC メンバすべてを 0 に設定しなければならない。DDSCAPS 構造体は DDSURFACEDESC のメンバである。
lplpDDSurface
[out] 有効な DirectDrawSurface ポインタで初期化するポインタのアドレス (呼び出しが成功した場合)。
pUnkOuter
[in] 内側のオブジェクトの IUnknown インターフェイスと集成される外側のオブジェクトの IUnknown インターフェイスへのポインタ。

戻り値

成功した場合は、DD_OK を返す。それ以外の場合は、次のいずれかのエラー値を返す。

DDERR_INCOMPATIBLEPRIMARY | プライマリ サーフェスの作成要求が既存のプライマリ サーフェスと一致していない。
DDERR_INVALIDCAPS | コールバック関数に渡された 1 つ以上の能力ビットが不正である。
DDERR_INVALIDOBJECT | DirectDraw が無効な DirectDraw オブジェクトへのポインタを受け取った。
DDERR_INVALIDPARAMS | メソッドに渡された 1 つ以上のパラメータが不正である。
DDERR_INVALIDPIXELFORMAT | 指定されたピクセル フォーマットが無効である。
DDERR_NOALPHAHW | アルファ アクセラレーション ハードウェアが存在しないか、利用できないため、要求された処理が失敗した。
DDERR_NOCOOPERATIVELEVELSET | サーフェスの作成前に IDirectDraw2::SetCooperativeLevel メソッドが呼び出されなかった。
DDERR_NODIRECTDRAWHW | ハードウェア専用 DirectDraw オブジェクトを作成できない。ドライバはハードウェアをサポートしない。
DDERR_NOEMULATION | ソフトウェア エミュレーションが利用できない。
DDERR_NOEXCLUSIVEMODE | アプリケーションに対して排他モードが要求されたが、アプリケーションに排他モードがない。
DDERR_NOFLIPHW | 表示されるサーフェスをフリッピングできない。
DDERR_NOMIPMAPHW | ミップマップ テクスチャをマッピングするハードウェアが存在しないか、利用できないため、処理を実行できない。
DDERR_NOOVERLAYHW | オーバーレイ ハードウェアが存在しないか、利用できないため、処理を実行できない。
DDERR_NOZBUFFERHW | Z バッファに対するハードウェア サポートがないため、ディスプレイ メモリでの Z バッファ作成、あるいは Z バッファを使用したブリットが実行できない。
DDERR_OUTOFMEMORY | DirectDraw が利用できるメモリが足りないため、処理を実行できない。
DDERR_OUTOFVIDEOMEMORY | DirectDraw が利用できるディスプレイ メモリが足りないため、処理を実行できない。
DDERR_PRIMARYSURFACEALREADYEXISTS | アプリケーションは既にプライマリ サーフェスを作成している。
DDERR_UNSUPPORTEDMODE | 処理がサポートされていない。

注意

pUnkOuter パラメータに NULL を渡すと、lplpDDSurface パラメータに DirectDraw サーフェスのアドレスが返される。また、内側のインターフェイスと集成する外側のインターフェイスへのポインタを渡すと、lplpDDSurface パラメータに対応する IUnknown ポインタが返される。

現在の DirectDrawEx は、DDSCAPS 構造体の dwcaps メンバに対応する DDSCAPS_DATAEXCHANGE フラグも提供する。このフラグは、Ddrawex.h に DDSCAPS_SYSTEMMEMORY と DDSCAPS_VIDEOMEMORY の組み合わせとして定義されている。DDSCAPS_DATAEXCHANGE フラグを使ってサーフェスを作成した場合、十分なビデオ メモリが利用できないと、サーフェスが自動的にビデオ メモリへ移される。それ以外の場合には、システム メモリ サーフェスが作成される。また、このフラグを DDSCAPS_OWNDC フラグと共に設定すると、アプリケーションから IDirectDrawSurface::GetDC メソッドを呼び出すことにより、サーフェスのロックを保持せずに、デバイス コンテキストを不要になるまでロックできる。

このメソッドは、IDirectDraw::CreateSurface メソッドと IDirectDraw2::CreateSurface メソッドを呼び出す。

IDirectDraw3::GetSurfaceFromDC

IDirectDraw3 インターフェイス

デバイス コンテキストのハンドルから IDirectDrawSurface インターフェイスへのポインタを取得する。

構文

STDMETHOD GetSurfaceFromDC(
  HDC hdc,
  IDirectDrawSurface **ppSurface
  ) PURE;

パラメータ

hdc
[in] デバイス コンテキスト (DC) のハンドル。
ppSurface
[out] IDirectDrawSurface インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、次のいずれかの値を返す。

E_POINTER | IDirectDrawSurface へのポインタが無効。
DDERR_NOTFOUND | 要求された項目が見つからない。


IDvdControl インターフェイス

注 : このインターフェイスの使用は避けること。既存のアプリケーションとの後方互換性を保つため、継続してサポートされるが、新しいアプリケーションでは IDvdControl2 を使用すること。

IDvdControl インターフェイスでは、1 つ以上のビデオ ムービーから構成される DVD タイトルの再生とサーチのメカニズムを制御する。

DVD ファイル システムは、作成者が簡単にカスタマイズできない連続的なトラックから構成される CD-ROM などのフォーマットとは大きく異なる。DVD フォーマットのメディア ファイルの作成者は、メディア ファイル自体が備える多くの構成要素と制御メカニズムを利用して、必要に応じて再生順序を変更できるため、トラックのレイアウトとナビゲーションを従来のメディアよりはるかに正確に制御できる。また、時間 (時、分、秒、フレーム) またはチャプター値を基準にしてファイルの特定の部分を検索できる。

メディア ファイルはプログラム チェーン (PGC) のリストから構成されている。個々のプログラム チェーンはプログラムのリストから構成されており、個々のプログラムはセルのリストから構成されており、個々のセルはビデオ オブジェクト ユニット (VOBU) のリストから構成されており、個々のビデオ オブジェクト ユニットはパックのリストから構成されており、個々のパックは実際の MPEG データから構成されている。

このインターフェイスは、DVD の再生に対応するために Microsoft® DirectShow® DVD ナビゲータによって実装される。

このインターフェイスを使用して、再生を制御したり (ルート ドライブの設定、再生、停止など)、DVD-Video ファイルの再生時にメニューやボタンなど、DVD 固有の機能を利用する。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IDvdControl methods | 説明
TitlePlay | 指定されたタイトル インデックスを持つメディア ファイルを検索し、それを再生する。
ChapterPlay | 指定されたタイトル インデックスとチャプター値を持つメディア ファイルを再生する。
TimePlay | 指定されたタイトル インデックスを持つメディア ファイルの指定された時間から再生を開始する。
StopForResume | 再開情報を保存した後、再生を DVD_DOMAIN_Stop 状態に移行させる。
GoUp | 現在のメディア ファイルの再生を停止し、指定された前のプログラム チェーン (PGC) の再生を開始する。
TimeSearch | 現在のチャプターの再生を停止し、同じメディア ファイルの指定された時間から再生を開始する。
ChapterSearch | 現在のチャプターの再生を停止し、同じメディア ファイルの指定されたチャプター値から再生を開始する。
PrevPGSearch | 現在のプログラムの再生を停止し、プログラム チェーン (PGC) 内の前のプログラムから再生を開始する。
TopPGSearch | 現在のプログラムの再生を停止し、プログラム チェーン内の現在のプログラムの再生を再び開始する。
NextPGSearch | 現在のプログラムの再生を停止し、プログラム チェーン (PGC) 内の次のプログラムから再生を開始する。
ForwardScan | 指定された速度で現在のディスクを順方向にサーチする。
BackwardScan | 指定された速度で現在のディスクを逆方向にサーチする。
MenuCall | 指定されたメニューを画面上に表示する。
Resume | メニューを使ったタイトルの再生に戻る。
UpperButtonSelect | 表示されたメニューから上方向ボタンを選択する。
LowerButtonSelect | 表示されたメニューから下方向ボタンを選択する。
LeftButtonSelect | 表示されたメニューから左方向ボタンを選択する。
RightButtonSelect | 表示されたメニューから右方向ボタンを選択する。
ButtonActivate | 選択されているボタンをアクティブにする。
ButtonSelectAndActivate | 指定されたボタンを選択し、アクティブにする。
StillOff | 再生を再開し、静止モードをキャンセルする。
PauseOn | 現在のメディア ファイルの再生をポーズする。
PauseOff | 現在のメディア ファイルの再生ポーズを解除する。
MenuLanguageSelect | ナビゲーション メニューに表示される言語を設定する。
AudioStreamChange | 現在のオーディオ ストリームを設定する。
SubpictureStreamChange | 新しいサブピクチャ ストリームを選択し、その表示を有効または無効にする。
AngleChange | 新しい表示アングルを設定する。
ParentalLevelSelect | 現在のメディア ファイルのペアレンタル ロック アクセス レベルを設定する。
ParentalCountrySelect | ペアレンタル ロック アクセス レベルを制御するときの基準となる現在の国を設定する。
KaraokeAudioPresentationModeChange | オーディオ再生モードをカラオケに設定する。
VideoModePreferrence | ユーザーの好みのビデオ表示モードを設定する。
SetRoot | DVD-Video ボリュームが格納されているルート ディレクトリを設定する。
MouseActivate | マウスのクリックに応じて DVD ボタンを選択し、アクティブにする。
MouseSelect | マウスの移動に応じて DVD ボタンを選択する。
ChapterPlayAutoStop | 指定されたタイトル内の指定されたチャプターから再生を開始し、指定された数のチャプターを再生する。

IDvdControl::AngleChange

IDvdControl インターフェイス

新しい表示アングルを設定する。

構文

HRESULT AngleChange(
    ULONG ulAngle
);

パラメータ

ulAngle
[in] 新しいアングルの値。1 から 9 の間でなければならない。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_OUTOFMEMORY | メモリ不足 (バッファ スペース不足)。
E_UNEXPECTED | DVD が初期化されていない。
S_OK | 成功。

注意

このメソッドは、ドメインが DVD_DOMAIN_VideoManagerMenu、DVD_DOMAIN_VideoTitleSetMenu、DVD_DOMAIN_Title、または DVD_DOMAIN_Stop でない限りエラーを返す。詳細については、「DVD_DOMAIN」を参照すること。

IDvdControl::AudioStreamChange

IDvdControl インターフェイス

現在のオーディオ ストリームを設定する。

構文

HRESULT AudioStreamChange(
    ULONG nAudio
);

パラメータ

nAudio
[in] 使用するオーディオ トラックを指定する値。0 から 7 の間でなければならない。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_OUTOFMEMORY | メモリ不足 (バッファ スペース不足)。
E_UNEXPECTED | DVD が初期化されていない。
S_OK | 成功。

注意

このメソッドは、ドメインが DVD_DOMAIN_VideoManagerMenu、DVD_DOMAIN_VideoTitleSetMenu、DVD_DOMAIN_Title、または DVD_DOMAIN_Stop でない限りエラーを返す。詳細については、「DVD_DOMAIN」を参照すること。

AudioStreamChange は現在のビデオ タイトル セット (VTS) を対象とする。メニュー内からこのメソッドを呼び出した場合は、メニューを呼び出したタイトルのオーディオ ストリームが設定される。

IDvdControl::BackwardScan

IDvdControl インターフェイス

指定された速度で現在のディスクを逆方向にサーチする。

構文

HRESULT BackwardScan(
    double dwSpeed
);

パラメータ

dwSpeed
[in] DirectShow でメディア ファイルをサーチするときの速度を指定する値。この値は、作成されたときの速度を 1.0 とする乗数である。したがって、2.5 を指定すると、作成速度の 2.5 倍の速度で逆方向のサーチが行われ、0.5 を指定すると作成速度の半分の速度で逆方向のサーチが行われる。実際の再生速度は、ビデオ デコーダの機能によって異なり、指定された速度と異なることがある。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_OUTOFMEMORY | メモリ不足 (バッファ スペース不足)。
E_UNEXPECTED | DVD が初期化されていない。
S_OK | 成功。

注意

このメソッドは、ドメインが DVD_DOMAIN_VideoManagerMenu、DVD_DOMAIN_VideoTitleSetMenu、または DVD_DOMAIN_Title でない限りエラーを返す。詳細については、「DVD_DOMAIN」を参照すること。

IDvdControl::ButtonActivate

IDvdControl インターフェイス

選択されているボタンをアクティブにする。

構文

HRESULT ButtonActivate(void);

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_NOTIMPL | メソッドがサポートされていない。
E_OUTOFMEMORY | メモリ不足 (バッファ スペース不足)。
E_UNEXPECTED | DVD が初期化されていない。
S_OK | 成功。

注意

DVD ボタンを "選択" しても、ボタンが強調表示されるだけで "アクティブ" にはならない。選択するとは、Microsoft® Windows® でいえば、Tab キーでボタンを選択し、Space キーまたは Enter キーを押さないことと同じである。アクティブとは、Windows の場合に、ボタンを (Tab キーで) 選択した後に Space キーまたは Enter キーを押すことと同じである。

このメソッドは、ドメインが DVD_DOMAIN_VideoManagerMenu、DVD_DOMAIN_VideoTitleSetMenu、または DVD_DOMAIN_Title でない限りエラーを返す。詳細については、「DVD_DOMAIN」を参照すること。

参照

IDvdControl::ButtonSelectAndActivate

IDvdControl::ButtonSelectAndActivate

IDvdControl インターフェイス

指定されたボタンを選択し、アクティブにする。

構文

HRESULT ButtonSelectAndActivate(
    ULONG uiButton
);

パラメータ

uiButton
[in] 選択し、アクティブにするボタンを指定する値。1 から 36 の間でなければならない。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_OUTOFMEMORY | メモリ不足 (バッファ スペース不足)。
E_UNEXPECTED | DVD が初期化されていない。
S_OK | 成功。

注意

電子的なリモート コントロール デバイスは、通常、DVD 再生装置のさまざまな機能をアクティブにするための数多くのボタンを備えている。このメソッドは、通常、ユーザーがコントロール デバイスのボタンをクリックしたときに呼び出される。このメソッドが呼び出されると、DirectShow は、たとえば、音を鳴らしたり画像を変更したりすることによってボタンが選択されたことを示し、選択されているボタンに対応する ButtonActivate などのメソッドを呼び出す。

このメソッドは、ドメインが DVD_DOMAIN_VideoManagerMenu、DVD_DOMAIN_VideoTitleSetMenu、または DVD_DOMAIN_Title でない限りエラーを返す。詳細については、「DVD_DOMAIN」を参照すること。

IDvdControl::ChapterPlay

IDvdControl インターフェイス

指定されたタイトル インデックスとチャプター値を持つメディア ファイルを再生する。

構文

HRESULT ChapterPlay(
    ULONG uiTitle,
    ULONG uiChapter
);

パラメータ

uiTitle
[in] DirectShow が再生するタイトル番号を指定する値。1 から 99 の間でなければならない。
uiChapter
[in] 指定されたタイトル内の DirectShow が再生を開始するチャプターを指定する値。1 から 999 の間でなければならない。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_OUTOFMEMORY | メモリ不足 (バッファ スペース不足)。
E_UNEXPECTED | DVD が初期化されていない。
S_OK | 成功。

注意

このメソッドは、ドメインが DVD_DOMAIN_VideoManagerMenu、DVD_DOMAIN_VideoTitleSetMenu、DVD_DOMAIN_Title、または DVD_DOMAIN_Stop でない限りエラーを返す。詳細については、「DVD_DOMAIN」を参照すること。

IDvdControl::ChapterPlayAutoStop

IDvdControl インターフェイス

指定されたタイトル内の指定されたチャプターから再生を開始し、指定された数のチャプターを再生するように DVD プレーヤーに指示する。

構文

HRESULT ChapterPlayAutoStop(
    ULONG ulTitle,
    ULONG ulChapter,
    ULONG ulChaptersToPlay
);

パラメータ

ulTitle
[in] 再生するタイトル番号。
ulChapter
[in] 再生を開始するチャプター番号。
ulChaptersToPlay
[in] 開始チャプターから再生するチャプターの数。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_OUTOFMEMORY | メモリ不足 (バッファ スペース不足)。
E_UNEXPECTED | DVD が初期化されていない。
S_OK | 成功。

注意

このメソッドは、いずれのドメインでも有効である。詳細については、「DVD_DOMAIN」を参照すること。

チャプターは 1 から 999 の範囲である。詳細については「EC_DVD_CHAPTER_AUTOSTOP」を参照すること。

IDvdControl::ChapterSearch

IDvdControl インターフェイス

現在のチャプターの再生を停止し、同じタイトル内の指定されたチャプターから再生を開始する。

構文

HRESULT ChapterSearch(
    ULONG Chapter
);

パラメータ

Chapter
再生の開始位置を指定するチャプター値。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_OUTOFMEMORY | メモリ不足 (バッファ スペース不足)。
E_UNEXPECTED | DVD が初期化されていない。
S_OK | 成功。

注意

このメソッドは、ドメインが DVD_DOMAIN_Title でない限りエラーを返す。詳細については、「DVD_DOMAIN」を参照すること。

IDvdControl::ForwardScan

IDvdControl インターフェイス

指定された速度で現在のディスクを順方向にサーチする。

構文

HRESULT ForwardScan(
    double dwSpeed
);

パラメータ

dwSpeed
[in] DirectShow でメディア ファイルをサーチするときの速度を指定する値。この値は、作成されたときの速度を 1.0 とする乗数である。したがって、2.5 を指定すると、作成速度の 2.5 倍の速度で順方向のサーチが行われ、0.5 を指定すると作成速度の半分の速度で順方向のサーチが行われる。実際の再生速度は、ビデオ デコーダの機能によって異なり、指定された速度と異なることがある。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_OUTOFMEMORY | メモリ不足 (バッファ スペース不足)。
E_UNEXPECTED | DVD が初期化されていない。
S_OK | 成功。

注意

このメソッドは、ドメインが DVD_DOMAIN_VideoManagerMenu、DVD_DOMAIN_VideoTitleSetMenu、または DVD_DOMAIN_Title でない限りエラーを返す。詳細については、「DVD_DOMAIN」を参照すること。

IDvdControl::GoUp

IDvdControl インターフェイス

現在のメディア ファイルの再生を停止し、指定された前のプログラム チェーン (PGC) の再生を開始する。

構文

HRESULT GoUp(void);

戻り値

HRESULT 値を返す。

注意

個々の PGC は作成時に前の PGC に関連付けられる。このメソッドは、関連付けられた前の PGC を新しい再生ファイルとして設定する。

このメソッドは、ドメインが DVD_DOMAIN_VideoManagerMenu、DVD_DOMAIN_VideoTitleSetMenu、または DVD_DOMAIN_Title でない限りエラーを返す。詳細については、「DVD_DOMAIN」を参照すること。

IDvdControl::KaraokeAudioPresentationModeChange

IDvdControl インターフェイス

オーディオ再生モードをカラオケに設定する。

構文

HRESULT KaraokeAudioPresentationModeChange(
    ULONG ulMode
);

パラメータ

ulMode
[in] 要求されているオーディオ再生モード。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_OUTOFMEMORY | メモリ不足 (バッファ スペース不足)。
E_UNEXPECTED | DVD が初期化されていない。
S_OK | 成功。

注意

現在、カラオケのサポートは実装されていない。

このメソッドは、ドメインが DVD_DOMAIN_VideoManagerMenu、DVD_DOMAIN_VideoTitleSetMenu、DVD_DOMAIN_Title、または DVD_DOMAIN_Stop でない限りエラーを返す。詳細については、「DVD_DOMAIN」を参照すること。

IDvdControl::LeftButtonSelect

IDvdControl インターフェイス

表示されたメニューから左方向ボタンを選択する。

構文

HRESULT LeftButtonSelect(void);

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_NOTIMPL | メソッドがサポートされていない。
E_UNEXPECTED | DVD が初期化されていない。
S_OK | 成功。

注意

多くの場合、物理的または電子的なリモート コントロール デバイスには、メニューの選択など、特定の種類の操作に使われる 4 個の方向ボタンが付属している。このメソッドは、何か (多くの場合はユーザー) によって、左方向ボタンがトリガされたことを DirectShow に知らせる。

DVD ボタンを "選択" しても、ボタンが強調表示されるだけで "アクティブ" にはならない。選択するとは、Windows でいえば、Tab キーでボタンを選択し、Space キーまたは Enter キーを押さないことと同じである。アクティブとは、Windows の場合に、ボタンを (Tab キーで) 選択した後に Space キーまたは Enter キーを押すことと同じである。

このメソッドは、ドメインが DVD_DOMAIN_VideoManagerMenu、DVD_DOMAIN_VideoTitleSetMenu、または DVD_DOMAIN_Title でない限りエラーを返す。詳細については、「DVD_DOMAIN」を参照すること。

IDvdControl::LowerButtonSelect

IDvdControl インターフェイス

表示されたメニューから下方向ボタンを選択する。

構文

HRESULT LowerButtonSelect(void);

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_NOTIMPL | メソッドがサポートされていない。
E_UNEXPECTED | DVD が初期化されていない。
S_OK | 成功。

注意

多くの場合、物理的または電子的なリモート コントロール デバイスには、メニューの選択など、特定の種類の操作に使われる 4 個の方向ボタンが付属している。このメソッドは、何か (多くの場合はユーザー) によって、下方向ボタンがトリガされたことを DirectShow に知らせる。

DVD ボタンを "選択" しても、ボタンが強調表示されるだけで "アクティブ" にはならない。選択するとは、Windows でいえば、Tab キーでボタンを選択し、Space キーまたは Enter キーを押さないことと同じである。アクティブとは、Windows の場合に、ボタンを (Tab キーで) 選択した後に Space キーまたは Enter キーを押すことと同じである。

このメソッドは、ドメインが DVD_DOMAIN_VideoManagerMenu、DVD_DOMAIN_VideoTitleSetMenu、または DVD_DOMAIN_Title でない限りエラーを返す。詳細については、「DVD_DOMAIN」を参照すること。

IDvdControl::MenuCall

IDvdControl インターフェイス

指定されたメニューを画面上に表示する。

構文

HRESULT MenuCall(
    DVD_MENU_ID MenuID
);

パラメータ

MenuID
[in] 表示するメニューを指定する値。DVD_MENU_ID 列挙型のメンバである。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_UNEXPECTED | DVD が初期化されていない。
S_OK | 成功。

注意

このメソッドは、ドメインが DVD_DOMAIN_VideoManagerMenu、DVD_DOMAIN_VideoTitleSetMenu、DVD_DOMAIN_Title、または DVD_DOMAIN_Stop でない限りエラーを返す。詳細については、「DVD_DOMAIN」を参照すること。

IDvdControl::MenuLanguageSelect

IDvdControl インターフェイス

ナビゲーション メニューに表示される言語を設定する。

構文

HRESULT MenuLanguageSelect(
    LCID LanguageCode
);

パラメータ

LanguageCode
新しい言語を指定する値。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_UNEXPECTED | DVD が初期化されていない。
S_OK | 成功。

注意

このメソッドは、メニューのデフォルトの言語を選択する。

このメソッドは、ドメインが DVD_DOMAIN_Stop でない限りエラーを返す。詳細については、「DVD_DOMAIN」を参照すること。

アプリケーションは標準 Windows LCID を使って言語を指定する。

IDvdControl::MouseActivate

IDvdControl インターフェイス

マウスのクリックに応じて DVD ボタンを選択し、アクティブにする。

構文

HRESULT MouseActivate(
    POINT point );

パラメータ

point
[in] 表示ウィンドウ内の指定された位置。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_UNEXPECTED | DVD が初期化されていない。
S_OK | 成功。

注意

このメソッドは、表示ウィンドウ内の指定された位置が現在の DVD ボタンの四角い強調表示領域内にあるかどうかを確認する。指定された位置が強調表示領域内にある場合、このメソッドはそのボタンを選択し、アクティブにする。

DVD ボタンの中には、強調表示領域がないものもある。ボタンの強調表示領域どうしは重なることがあり、強調表示領域が DVD ボタンの外観と一致しないこともある。

このメソッドは、ドメインが DVD_DOMAIN_VideoManagerMenu、DVD_DOMAIN_VideoTitleSetMenu、または DVD_DOMAIN_Title でない限りエラーを返す。詳細については、「DVD_DOMAIN」を参照すること。

IDvdControl::MouseSelect

IDvdControl インターフェイス

マウスの移動に応じて DVD ボタンを選択する。

構文

HRESULT MouseSelect(
    POINT point );

パラメータ

point
[in] 表示ウィンドウ内の指定された位置。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_UNEXPECTED | DVD が初期化されていない。
S_OK | 成功。

注意

このメソッドは、いずれのドメインでも有効である。詳細については、「DVD_DOMAIN」を参照すること。

このメソッドは、表示ウィンドウ内の指定された位置が現在の DVD ボタンの四角い強調表示領域内にあるかどうかを確認する。指定された位置が強調表示領域内にある場合、このメソッドはそのボタンを選択し、アクティブにする。

DVD ボタンの中には、強調表示領域がないものもある。ボタンの強調表示領域どうしは重なることがあり、強調表示領域が DVD ボタンの外観と一致しないこともある。

IDvdControl::NextPGSearch

IDvdControl インターフェイス

現在のプログラムの再生を停止し、プログラム チェーン (PGC) 内の次のプログラムから再生を開始する。

構文

HRESULT NextPGSearch(void);

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_NOTIMPL | メソッドがサポートされていない。
E_UNEXPECTED | DVD が初期化されていない。
S_OK | 成功。

注意

通常、1 つのプログラムは 1 つのチャプターに相当し、1 つの PGC は 1 つのタイトルに相当する。One_Sequential_PGC_Title の場合、各プログラムは 1 つのチャプターに相当する必要があり、各タイトルには PGC が 1 つだけ含まれるが、それ以外の場合、特にランダム/シャッフル PGC およびペアレンタル ブロックの場合は、チャプター間に複数のプログラムを含めたり、1 つのタイトルに複数の PGC を含めることができる。

このメソッドは、ドメインが DVD_DOMAIN_VideoManagerMenu、DVD_DOMAIN_VideoTitleSetMenu、または DVD_DOMAIN_Title でない限りエラーを返す。詳細については、「DVD_DOMAIN」を参照すること。

IDvdControl::ParentalCountrySelect

IDvdControl インターフェイス

ペアレンタル ロック アクセス レベルを制御するときの基準となる現在の国を設定する。

構文

HRESULT ParentalCountrySelect(
    WORD wCountry
);

パラメータ

wCountry
[in] ISO3166 で定義されている Alpha-2 Code に従って現在の国を指定する値。「注意」を参照すること。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_UNEXPECTED | DVD が初期化されていない。
S_OK | 成功。

注意

このメソッドは、ドメインが DVD_DOMAIN_Stop でない限りエラーを返す。詳細については、「DVD_DOMAIN」を参照すること。

wCountry パラメータの ISO3166 の 2 文字国コードは、このメソッドに WORD として渡す必要がある。以下のコードは、アメリカ (US) の場合の変換の例を示している。

WORD wCountry  =  ( WORD( 'U' ) << 8 ) | 'S';

参照

IDVDControl::ParentalLevelSelect

IDvdControl::ParentalLevelSelect

IDvdControl インターフェイス

現在のメディア ファイルのペアレンタル ロック アクセス レベルを設定する。

構文

HRESULT ParentalLevelSelect(
    ULONG ulParentalLevel
);

パラメータ

ulParentalLevel
現在のメディア ファイルのペアレンタル ロック アクセス レベルを指定する値。1 以上、8 以下の値でなければならない。以下は定義済みのペアレンタル ロック レベルである。
1 | 格付けは一般向けの G である。
3 | 格付けは保護者の指導が望ましい PG である。
4 | 格付けは保護者の指導が望ましく、13 歳未満の子供には推奨できない PG-13 である。
6 | 格付けは制限付きの R である。
7 | 格付けは NC-17 である。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_UNEXPECTED | DVD が初期化されていない。
S_OK | 成功。

注意

このメソッドは、ドメインが DVD_DOMAIN_Stop でない限りエラーを返す。詳細については、「DVD_DOMAIN」を参照すること。

このメソッドは、現在のユーザーのアクセス レベルを設定する。アクセス レベルによって、ユーザーが再生できるメディア ファイルが決まる。高いレベルは低いレベルのコンテンツを再生できるが、低いレベルは高いレベルのコンテンツを再生できない。たとえば、成人は子供向けのコンテンツを見ることができるが、子供は成人向けのコンテンツを見ることはできない。

DVD ナビゲータ フィルタには、ペアレンタル ロック レベルの設定を制限する機能はない。DVD プレーヤー アプリケーションでは、現在のペアレンタル ロック レベルを上げる操作をパスワードによって保護するなど、ペアレンタル ロック レベルの設定を強制的に制限することができる。DVD ナビゲータのデフォルトの設定では、ペアレンタル ロックが無効になっている。

ペアレンタル ロックを無効にするには、ulParentalLevel として 0xffffffff を渡す。ペアレンタル ロックが無効になっていれば、プレーヤーは、ペアレンタル ID に関係なく、ペアレンタル ブロック内の最初のプログラム チェーン (PGC) を再生する。

参照

IDVDControl::ParentalCountrySelect

IDvdControl::PauseOff

IDvdControl インターフェイス

ポーズ後、現在のメディア ファイルの再生を再開する。

構文

HRESULT PauseOff(void);

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_NOTIMPL | メソッドがサポートされていない。
E_UNEXPECTED | DVD が初期化されていない。
S_OK | 成功。

注意

メディア ファイルの再生がポーズになっていない場合、このメソッドは何もしない。

このメソッドは、ドメインが DVD_DOMAIN_VideoManagerMenu、DVD_DOMAIN_VideoTitleSetMenu、または DVD_DOMAIN_Title でない限りエラーを返す。詳細については、「DVD_DOMAIN」を参照すること。

参照

IDvdControl::PauseOn

IDvdControl::PauseOn

IDvdControl インターフェイス

現在のメディアファイルの再生をポーズする。

構文

HRESULT PauseOn(void);

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_NOTIMPL | メソッドがサポートされていない。
E_UNEXPECTED | DVD が初期化されていない。
S_OK | 成功。

注意

IMediaControl::Pause と同様に、このメソッドは再生とすべての内部タイマを静止させる。メディア ファイルが動作していない場合、このメソッドは何もしない。

このメソッドは、ドメインが DVD_DOMAIN_VideoManagerMenu、DVD_DOMAIN_VideoTitleSetMenu、または DVD_DOMAIN_Title でない限りエラーを返す。詳細については、「DVD_DOMAIN」を参照すること。

参照

IDvdControl::PauseOff

IDvdControl::PrevPGSearch

IDvdControl インターフェイス

現在のプログラムの再生を停止し、プログラム チェーン (PGC) 内の前のプログラムから再生を開始する。

構文

HRESULT PrevPGSearch(void);

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_NOTIMPL | メソッドがサポートされていない。
E_UNEXPECTED | DVD が初期化されていない。
S_OK | 成功。

注意

通常、1 つのプログラムは 1 つのチャプターに相当し、1 つの PGC は 1 つのタイトルに相当する。One_Sequential_PGC_Title の場合、各プログラムは 1 つのチャプターに相当する必要があり、各タイトルには PGC が 1 つだけ含まれるが、それ以外の場合、特にランダム/シャッフル PGC およびペアレンタル ブロックの場合は、チャプター間に複数のプログラムを含めたり、1 つのタイトルに複数の PGC を含めることができる。

このメソッドは、ドメインが DVD_DOMAIN_VideoManagerMenu、DVD_DOMAIN_VideoTitleSetMenu、または DVD_DOMAIN_Title でない限りエラーを返す。詳細については、「DVD_DOMAIN」を参照すること。

IDvdControl::Resume

IDvdControl インターフェイス

メニューを使ったタイトルの再生に戻る。

構文

HRESULT Resume(void);

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_NOTIMPL | メソッドがサポートされていない。
E_UNEXPECTED | DVD が初期化されていない。
S_OK | 成功。

注意

ファイルの再生が停止している場合、またはファイルが既に動作している場合、このメソッドは何もしない。

このメソッドは、動作を DVD_DOMAIN_Title のタイトル再生に戻す。通常、アプリケーションは、DVD ナビゲータを DVD_DOMAIN_VideoTitleSetMenu または DVD_DOMAIN_VideoManagerMenu に移行させる MenuCall を呼び出した後でこのメソッドを呼び出す。

このメソッドは、ドメインが DVD_DOMAIN_VideoManagerMenu または DVD_DOMAIN_VideoTitleSetMenu でない限りエラーを返す。詳細については、「DVD_DOMAIN」を参照すること。

IDvdControl::RightButtonSelect

IDvdControl インターフェイス

表示されたメニューから右方向ボタンを選択する。

構文

HRESULT RightButtonSelect(void);

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_NOTIMPL | メソッドがサポートされていない。
E_OUTOFMEMORY | メモリ不足 (バッファ スペース不足)。
E_UNEXPECTED | DVD が初期化されていない。
S_OK | 成功。

注意

多くの場合、物理的または電子的なリモート コントロール デバイスには、メニューの選択など、特定の種類の操作に使われる 4 個の方向ボタンが付属している。このメソッドは、何か (多くの場合はユーザー) によって、右方向ボタンがトリガされたことを DirectShow に知らせる。

DVD ボタンを "選択" しても、ボタンが強調表示されるだけで "アクティブ" にはならない。選択するとは、Windows でいえば、Tab キーでボタンを選択し、Space キーまたは Enter キーを押さないことと同じである。アクティブとは、Windows の場合に、ボタンを (Tab キーで) 選択した後に Space キーまたは Enter キーを押すことと同じである。

このメソッドは、ドメインが DVD_DOMAIN_VideoManagerMenu、DVD_DOMAIN_VideoTitleSetMenu、または DVD_DOMAIN_Title でない限りエラーを返す。詳細については、「DVD_DOMAIN」を参照すること。

IDvdControl::SetRoot

IDvdControl インターフェイス

DVD-Video ボリュームが格納されているルート ディレクトリを設定する。

構文

HRESULT SetRoot(
    LPCWSTR pszPath
);

パラメータ

pszPath
[in] ルート ディレクトリとして設定するディレクトリ名へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_POINTER | NULL ポインタ引数。
S_OK | 成功。

注意

このメソッドは、ドメインが DVD_DOMAIN_Stop でない限りエラーを返す。詳細については、「DVD_DOMAIN」を参照すること。

IDvdControl::TitlePlay を呼び出す前にルート ディレクトリを設定しなかった場合は、最上位レベルのディレクトリに VIDEO_TS ディレクトリが含まれている C: 以降の最初のドライブがルートとして使用される。

IDvdControl::StillOff

IDvdControl インターフェイス

再生を再開し、静止モードをキャンセルする。

構文

HRESULT StillOff(void);

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_NOTIMPL | メソッドがサポートされていない。
E_UNEXPECTED | DVD が初期化されていない。
S_OK | 成功。

注意

表示画像が静止画保持モードになっていない場合、このメソッドは何もしない。

このメソッドは、ドメインが DVD_DOMAIN_VideoManagerMenu、DVD_DOMAIN_VideoTitleSetMenu、または DVD_DOMAIN_Title でない限りエラーを返す。詳細については、「DVD_DOMAIN」を参照すること。

IDvdControl::StopForResume

IDvdControl インターフェイス

再開情報を保存した後、再生を DVD_DOMAIN_Stop 状態に移行させる。

構文

HRESULT StopForResume(void);

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_NOTIMPL | メソッドがサポートされていない。
E_UNEXPECTED | DVD が初期化されていない。
S_OK | 成功。

注意

再生されているファイルまたはポーズしているファイルがない場合、このメソッドは何もしない。

DVD ナビゲータ フィルタは停止状態に移行するが、フィルタのグラフは DirectShow 実行状態にとどまる。

このメソッドは、ドメインが DVD_DOMAIN_VideoManagerMenu、DVD_DOMAIN_VideoTitleSetMenu、または DVD_DOMAIN_Title でない限りエラーを返す。詳細については、「DVD_DOMAIN」を参照すること。

IDvdControl::SubpictureStreamChange

IDvdControl インターフェイス

新しいサブピクチャ ストリームを選択し、その表示を有効または無効にする。

構文

HRESULT SubpictureStreamChange(
    ULONG nSubPicture,
    BOOL bDisplay
);

パラメータ

nSubPicture
サブピクチャのソースを指定する値。0 から 32 の間または 63 でなければならない。
0-31 | ストリームが有効であることを示す。
32 | 現在のストリームを変更せずに表示をオン、オフできる。つまり、現在のストリームを変更せずに bDisplay を変更できる。
63 | ストリームがダミー ストリームであることを示す。
bDisplay
サブピクチャが有効であるかどうかを指定する値。TRUE に設定すると、サブピクチャが表示され、FALSE に設定するとサブピクチャが表示されない。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_UNEXPECTED | DVD が初期化されていない。
S_OK | 成功。

注意

このメソッドは、ドメインが DVD_DOMAIN_VideoManagerMenu、DVD_DOMAIN_VideoTitleSetMenu、DVD_DOMAIN_Title、または DVD_DOMAIN_Stop でない限りエラーを返す。詳細については、「DVD_DOMAIN」を参照すること。

IDvdControl::TimePlay

IDvdControl インターフェイス

指定されたタイトル インデックスを持つメディア ファイルの指定された時間から再生を開始する。

構文

HRESULT TimePlay(
    ULONG uiTitle,
    ULONG bcdTime
);

パラメータ

uiTitle
DirectShow で再生するタイトル番号を指定する値。この値は 1 から 99 の間でなければならない。
bcdTime
DirectShow が再生を開始する DVD_TIMECODE 構造体へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_UNEXPECTED | DVD が初期化されていない。
S_OK | 成功。

注意

このメソッドは、ドメインが DVD_DOMAIN_VideoManagerMenu、DVD_DOMAIN_VideoTitleSetMenu、DVD_DOMAIN_Title、または DVD_DOMAIN_Stop でない限りエラーを返す。詳細については、「DVD_DOMAIN」を参照すること。

IDvdControl::TimeSearch

IDvdControl インターフェイス

現在のチャプターの再生を停止し、同じメディア ファイルの指定された時間から再生を開始する。

構文

HRESULT TimeSearch(
    ULONG bcdTime
);

パラメータ

bcdTime
DirectShow が再生を開始する DVD_TIMECODE 構造体へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_UNEXPECTED | DVD が初期化されていない。
S_OK | 成功。

注意

このメソッドは、ドメインが DVD_DOMAIN_Title でない限りエラーを返す。詳細については、「DVD_DOMAIN」を参照すること。

IDvdControl::TitlePlay

IDvdControl インターフェイス

指定されたタイトル インデックスを持つメディア ファイルを検索し、それを再生する。

構文

HRESULT TitlePlay(
    ULONG uiTitle
);

パラメータ

uiTitle
DirectShow で再生するタイトル番号を指定する値。この値は 1 から 99 の間でなければならない。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_UNEXPECTED | DVD が初期化されていない。
S_OK | 成功。

注意

このメソッドは、ドメインが DVD_DOMAIN_VideoManagerMenu、DVD_DOMAIN_VideoTitleSetMenu、DVD_DOMAIN_Title、または DVD_DOMAIN_Stop でない限りエラーを返す。詳細については、「DVD_DOMAIN」を参照すること。

IDvdControl::TopPGSearch

IDvdControl インターフェイス

現在のプログラムの再生を停止し、プログラム チェーン (PGC) 内の現在のプログラムの再生を再び開始する。

構文

HRESULT TopPGSearch(void);

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_NOTIMPL | メソッドがサポートされていない。
E_UNEXPECTED | DVD が初期化されていない。
S_OK | 成功。

注意

通常、1 つのプログラムは 1 つのチャプターに相当し、1 つの PGC は 1 つのタイトルに相当する。One_Sequential_PGC_Title の場合、各プログラムは 1 つのチャプターに相当する必要があり、各タイトルには PGC が 1 つだけ含まれるが、それ以外の場合、特にランダム/シャッフル PGC およびペアレンタル ブロックの場合は、チャプター間に複数のプログラムを含めたり、1 つのタイトルに複数の PGC を含めることができる。

このメソッドは、ドメインが DVD_DOMAIN_VideoManagerMenu、DVD_DOMAIN_VideoTitleSetMenu、または DVD_DOMAIN_Title でない限りエラーを返す。詳細については、「DVD_DOMAIN」を参照すること。

IDvdControl::UpperButtonSelect

IDvdControl インターフェイス

表示されたメニューから上方向ボタンを選択する。

構文

HRESULT UpperButtonSelect(void);

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_NOTIMPL | メソッドがサポートされていない。
S_OK | 成功。

注意

多くの場合、物理的または電子的なリモート コントロール デバイスには、メニューの選択など、特定の種類の操作に使われる 4 個の方向ボタンが付属している。このメソッドは、何か (多くの場合はユーザー) によって、上方向ボタンがトリガされたことを DirectShow に知らせる。

DVD ボタンを "選択" しても、ボタンが強調表示されるだけで "アクティブ" にはならない。選択するとは、Windows でいえば、Tab キーでボタンを選択し、Space キーまたは Enter キーを押さないことと同じである。アクティブとは、Windows の場合に、ボタンを (Tab キーで) 選択した後に Space キーまたは Enter キーを押すことと同じである。

このメソッドは、ドメインが DVD_DOMAIN_VideoManagerMenu、DVD_DOMAIN_VideoTitleSetMenu、または DVD_DOMAIN_Title でない限りエラーを返す。詳細については、「DVD_DOMAIN」を参照すること。

IDvdControl::VideoModePreferrence

IDvdControl インターフェイス

ユーザーの好みのビデオ表示モードを設定する。

構文

HRESULT VideoModePreferrence(
    ULONG ulPreferredDisplayMode
);

パラメータ

ulPreferredDisplayMode
[in] DVD コンテンツの新しい表示モードを指定する値。DVD_PREFERRED_DISPLAY_MODE 列挙型のメンバである。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
S_OK | 成功。

注意

このメソッドは、デフォルトのビデオ ウィンドウのアスペクト比を変更する。このメソッドによってデフォルトのアスペクト比変換メカニズムを指定することもできる。

このメソッドは、ドメインが DVD_DOMAIN_VideoManagerMenu、DVD_DOMAIN_VideoTitleSetMenu、DVD_DOMAIN_Title、または DVD_DOMAIN_Stop でない限りエラーを返す。詳細については、「DVD_DOMAIN」を参照すること。


IDvdInfo インターフェイス

注 : このインターフェイスの使用は避けること。既存のアプリケーションとの後方互換性を保つため、継続してサポートされるが、新しいアプリケーションでは IDvdInfo2 インターフェイスを使用すること。

アプリケーションは IDvdInfo インターフェイスを使用して、利用可能な DVD タイトルの属性および DVD プレーヤーの状態を問い合わせることができる。また、DVD の仕様の Annex J の範囲を超えて DVD プレーヤーを制御することもできる。

このインターフェイスを実装しないこと。このインターフェイスは Microsoft® DirectShow® が自動的に実装する。

アプリケーションでこのインターフェイスを使用し、DVD-Video または DVD プレーヤー フィルタ グラフの現在の状態に関する詳細情報を取得する。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IDvdInfo メソッド | 説明
GetCurrentDomain | DVD プレーヤーの現在の DVD ドメインを取得する。
GetCurrentLocation | 現在の再生位置を取得する。
GetTotalTitleTime | 現在のタイトルの総再生時間を取得する。
GetCurrentButton | 利用可能なボタンの数と現在選択されているボタン番号を取得する。
GetCurrentAngle | 利用可能なアングルの数と現在選択されているアングル番号を取得する。
GetCurrentAudio | 利用可能なオーディオ ストリームの数と現在選択されているオーディオ ストリームの番号を取得する。
GetCurrentSubpicture | 利用可能なサブピクチャ ストリームの数、現在選択されているサブピクチャ ストリーム番号、およびサブピクチャの表示が無効になっているかどうかを示す値を取得する。
GetCurrentUOPS | 有効な IDvdControl メソッドを取得する。
GetAllSPRMs | すべてのシステム パラメータ レジスタ (SPRM) の現在の内容を取得する。
GetAllGPRMs | すべての汎用パラメータ レジスタ (GPRM) の現在の内容を取得する。
GetAudioLanguage | 現在のタイトル内の指定されたオーディオ ストリームの言語を取得する。
GetSubpictureLanguage | 現在のタイトル内の指定されたサブピクチャ ストリームの言語を取得する。
GetTitleAttributes | メニューを含む指定されたタイトルのすべてのビデオ ストリーム、オーディオ ストリーム、およびサブピクチャ ストリームの属性を取得する。
GetVMGAttributes | ビデオ マネージャ (VMG) メニューのすべてのビデオ ストリーム、オーディオ ストリーム、およびサブピクチャ ストリームの属性を取得する。
GetCurrentVideoAttributes | 現在のタイトルまたはメニューの現在のビデオ属性を取得する。
GetCurrentAudioAttributes | 現在のタイトルまたはメニューの現在のオーディオ ストリームの属性を取得する。
GetCurrentSubpictureAttributes | 現在のタイトルまたはメニューの現在のサブピクチャ ストリームの属性を取得する。
GetCurrentVolumeInfo | 現在の DVD ボリューム情報を取得する。
GetDVDTextInfo | さまざまな言語のタイトル名、ボリューム名、プロデューサー名、ボーカリスト名などの説明テキストが格納される TXTDT_MG 構造体を取得する。
GetPlayerParentalLevel | DVD プレーヤーの現在のペアレンタル ロック レベルと国コードの設定を取得する。
GetNumberOfChapters | 特定のタイトルに対して定義されているチャプターの数を取得する。
GetTitleParentalLevels | 特定のタイトルに対して定義されているペアレンタル ロック レベルを取得する。
GetRoot | プレーヤーで設定されているルート ディレクトリを取得する。

IDvdInfo::GetAllGPRMs

IDvdInfo インターフェイス

すべての汎用パラメータ レジスタ (GPRM) の現在の内容を取得する。

構文

HRESULT GetAllGPRMs(
    GPRMARRAY *pRegisterArray
    );

パラメータ

pRegisterArray
[out] 取得された汎用パラメータ レジスタの配列へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 入力引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_OUTOFMEMORY | メモリ不足 (バッファ スペース不足)。
E_POINTER | NULL ポインタ引数。
E_UNEXPECTED | DVD が初期化されていないか、またはドメインが DVD_DOMAIN_Title ではない。
VFW_E_DVD_OPERATION_INHIBITED | 現在の DVD ビデオのディスクを作成しているため、現時点では要求されたアクションをムービーで実行できない。
S_OK | 成功。
VFW_E_DVD_INVALIDDOMAIN | 要求されたアクションはこのドメインではサポートされていない (DVD_DOMAIN)。

注意

このメソッドは、いずれのドメインでも有効である。詳細については、「DVD_DOMAIN」を参照すること。

GPRM は各タイトルに固有の用途で使用される。GPRM は汎用パラメータ レジスタである。GPRM については、DVD の仕様を参照すること。

IDvdInfo::GetAllSPRMs

IDvdInfo インターフェイス

すべてのシステム パラメータ レジスタ (SPRM) の現在の内容を取得する。

構文

HRESULT GetAllSPRMs(
    SPRMARRAY *pRegisterArray
    );

パラメータ

pRegisterArray
[out] 取得されたシステム パラメータ レジスタの配列へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 入力引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_OUTOFMEMORY | メモリ不足 (バッファ スペース不足)。
E_POINTER | NULL ポインタ引数。
E_UNEXPECTED | DVD が初期化されていないか、またはドメインが DVD_DOMAIN_Title ではない。
VFW_E_DVD_OPERATION_INHIBITED | 現在の DVD ビデオのディスクを作成しているため、現時点では要求されたアクションをムービーで実行できない。
S_OK | 成功。
VFW_E_DVD_INVALIDDOMAIN | 要求されたアクションはこのドメインではサポートされていない (DVD_DOMAIN)。

注意

このメソッドは、いずれのドメインでも有効である。詳細については、「DVD_DOMAIN」を参照すること。

個々のレジスタの使い方については、「DVD ビデオの仕様」を参照すること。

IDvdInfo::GetAudioLanguage

IDvdInfo インターフェイス

現在のタイトル内の指定されたオーディオ ストリームの言語を取得する。

構文

HRESULT GetAudioLanguage(
    ULONG nStream,
    LCID *pLanguage
    );

パラメータ

nStream
[in] ストリーム番号。
pLanguage
[out] 取得された言語へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 入力引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_OUTOFMEMORY | メモリ不足 (バッファ スペース不足)。
E_POINTER | NULL ポインタ引数。
E_UNEXPECTED | DVD が初期化されていないか、またはドメインが DVD_DOMAIN_Title ではない。
VFW_E_DVD_OPERATION_INHIBITED | 現在の DVD ビデオのディスクを作成しているため、現時点では要求されたアクションをムービーで実行できない。
S_OK | 成功。
VFW_E_DVD_INVALIDDOMAIN | 要求されたアクションはこのドメインではサポートされていない (DVD_DOMAIN)。

注意

このメソッドは、ドメインが DVD_DOMAIN_Title でない限りエラーを返す。詳細については、「DVD_DOMAIN」を参照すること。

このメソッドはメニューの言語は返さない。ストリームに言語が含まれていない場合、このメソッドは、pLanguage が指す値をゼロに設定する。pLanguage から読み取り可能な文字列名を作成するには、次のように Win32 GetLocaleInfo 関数を呼び出す。LOCALE_SENGLANGUAGE はロケール情報型であり、pszString は要求されたデータを受け取るバッファへのポインタであり、cbSize は pszString のサイズを指定する。

GetLocaleInfo(*pLanguage, LOCALE_SENGLANGUAGE, pszString, cbSize);

IDvdInfo::GetCurrentAngle

IDvdInfo インターフェイス

利用可能なアングルの数と現在選択されているアングル番号を取得する。

構文

HRESULT GetCurrentAngle(
    ULONG *pnAnglesAvailable,
    ULONG *pnCurrentAngle
    );

パラメータ

pnAnglesAvailable
[out] 取得された利用可能なアングルの数へのポインタ。指している値が 1 である場合、現在のビデオには複数のアングルが含まれていない。
pnCurrentAngle
[out] 取得された現在のアングル番号へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 入力引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_OUTOFMEMORY | メモリ不足 (バッファ スペース不足)。
E_POINTER | NULL ポインタ引数。
E_UNEXPECTED | DVD が初期化されていないか、またはドメインが DVD_DOMAIN_Title ではない。
VFW_E_DVD_OPERATION_INHIBITED | 現在の DVD ビデオのディスクを作成しているため、現時点では要求されたアクションをムービーで実行できない。
S_OK | 成功。
VFW_E_DVD_INVALIDDOMAIN | 要求されたアクションはこのドメインではサポートされていない (DVD_DOMAIN)。

注意

アングルとは、重ねて記録されているビデオ ストリームで、その中には、異なるカメラ アングルから撮影された同じ場面が収録されている。

このメソッドは、ドメインが DVD_DOMAIN_Title でない限りエラーを返す。詳細については、「DVD_DOMAIN」を参照すること。

IDvdInfo::GetCurrentAudio

IDvdInfo インターフェイス

利用可能なオーディオ ストリームの数と現在選択されているオーディオ ストリームの番号を取得する。

構文

HRESULT GetCurrentAudio(
    ULONG *pnStreamsAvailable,
    ULONG *pnCurrentStream
    );

パラメータ

pnStreamsAvailable
[out] 取得された利用可能なオーディオ ストリームの数へのポインタ。
pnCurrentStream
[out] 現在のストリーム番号へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 入力引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_OUTOFMEMORY | メモリ不足 (バッファ スペース不足)。
E_POINTER | NULL ポインタ引数。
E_UNEXPECTED | DVD が初期化されていないか、またはドメインが DVD_DOMAIN_Title ではない。
VFW_E_DVD_OPERATION_INHIBITED | 現在の DVD ビデオのディスクを作成しているため、現時点では要求されたアクションをムービーで実行できない。
S_OK | 成功。
VFW_E_DVD_INVALIDDOMAIN | 要求されたアクションはこのドメインではサポートされていない (DVD_DOMAIN)。

注意

このメソッドは、ドメインが DVD_DOMAIN_Title でない限りエラーを返す。詳細については、「DVD_DOMAIN」を参照すること。

IDvdInfo::GetCurrentAudioAttributes

IDvdInfo インターフェイス

現在のタイトルまたはメニューの現在のオーディオ ストリームの属性を取得する。

構文

HRESULT GetCurrentAudioAttributes(
    DVD_AudioATR *pATR
    );

パラメータ

pATR
[out] 取得されたオーディオ属性へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 入力引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_OUTOFMEMORY | メモリ不足 (バッファ スペース不足)。
E_POINTER | NULL ポインタ引数。
E_UNEXPECTED | DVD が初期化されていないか、またはドメインが DVD_DOMAIN_Title ではない。
VFW_E_DVD_OPERATION_INHIBITED | 現在の DVD ビデオのディスクを作成しているため、現時点では要求されたアクションをムービーで実行できない。
S_OK | 成功。
VFW_E_DVD_INVALIDDOMAIN | 要求されたアクションはこのドメインではサポートされていない (DVD_DOMAIN)。

注意

このメソッドは、ドメインが DVD_DOMAIN_VideoManagerMenu、DVD_DOMAIN_VideoTitleSetMenu、または DVD_DOMAIN_Title でない限りエラーを返す。詳細については、「DVD_DOMAIN」を参照すること。

DVD_AudioATR データ型については、「DVD-Video 仕様」を参照すること。

IDvdInfo::GetCurrentButton

IDvdInfo インターフェイス

利用可能なボタンの数と現在選択されているボタン番号を取得する。

構文

HRESULT GetCurrentButton(
    ULONG *pnButtonsAvailable,
    ULONG *pnCurrentButton
    );

パラメータ

pnButtonsAvailable
[out] 利用可能なボタンの数へのポインタ。
pnCurrentButton
[out] 現在のボタン番号へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 入力引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_OUTOFMEMORY | メモリ不足 (バッファ スペース不足)。
E_POINTER | NULL ポインタ引数。
E_UNEXPECTED | DVD が初期化されていないか、またはドメインが DVD_DOMAIN_Title ではない。
VFW_E_DVD_OPERATION_INHIBITED | 現在の DVD ビデオのディスクを作成しているため、現時点では要求されたアクションをムービーで実行できない。
S_OK | 成功。
VFW_E_DVD_INVALIDDOMAIN | 要求されたアクションはこのドメインではサポートされていない (DVD_DOMAIN)。

注意

ボタンがない場合、このメソッドは pnButtonsAvailable と pnCurrentButton の両方をゼロにして返す。

このメソッドは、いずれのドメインでも有効である。詳細については、「DVD_DOMAIN」を参照すること。

IDvdInfo::GetCurrentDomain

IDvdInfo インターフェイス

DVD プレーヤーの現在の DVD ドメインを取得する。

構文

HRESULT GetCurrentDomain(
    DVD_DOMAIN *pDomain
    );

パラメータ

pDomain
[out] DVD_DOMAIN 列挙型のメンバである現在のドメインへのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 入力引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_OUTOFMEMORY | メモリ不足 (バッファ スペース不足)。
E_POINTER | NULL ポインタ引数。
E_UNEXPECTED | DVD が初期化されていないか、またはドメインが DVD_DOMAIN_Title ではない。
VFW_E_DVD_OPERATION_INHIBITED | 現在の DVD ビデオのディスクを作成しているため、現時点では要求されたアクションをムービーで実行できない。
S_OK | 成功。
VFW_E_DVD_INVALIDDOMAIN | 要求されたアクションはこのドメインではサポートされていない (DVD_DOMAIN)。

注意

このメソッドは、いずれのドメインでも有効である。詳細については、「DVD_DOMAIN」を参照すること。

IDvdInfo::GetCurrentLocation

IDvdInfo インターフェイス

現在の再生位置を取得する。

構文

HRESULT GetCurrentLocation(
    DVD_PLAYBACK_LOCATION *pLocation
    );

パラメータ

pLocation
[out] DVD_PLAYBACK_LOCATION 構造体内の取得された再生位置情報へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 入力引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_OUTOFMEMORY | メモリ不足 (バッファ スペース不足)。
E_POINTER | NULL ポインタ引数。
E_UNEXPECTED | DVD が初期化されていないか、またはドメインが DVD_DOMAIN_Title ではない。
VFW_E_DVD_OPERATION_INHIBITED | 現在の DVD ビデオのディスクを作成しているため、現時点では要求されたアクションをムービーで実行できない。
S_OK | 成功。
VFW_E_DVD_INVALIDDOMAIN | 要求されたアクションはこのドメインではサポートされていない (DVD_DOMAIN)。

このメソッドのデフォルトの実装は、現在のドメインが DVD_DOMAIN_Title でない場合、E_UNEXPECTED を返す。

注意

このメソッドは、現在の位置のシークを明示的に禁止していないタイトルの現在の再生位置からビデオの再生を再開するのに十分な情報を取得する。

このメソッドは、ドメインが DVD_DOMAIN_Title でない限りエラーを返す。詳細については、「DVD_DOMAIN」を参照すること。

IDvdInfo::GetCurrentSubpicture

IDvdInfo インターフェイス

利用可能なサブピクチャ ストリームの数、現在選択されているサブピクチャ ストリーム番号、およびサブピクチャの表示が無効になっているかどうかを示す値を取得する。

構文

HRESULT GetCurrentSubpicture(
    ULONG *pnStreamsAvailable,
    ULONG *pnCurrentStream,
    BOOL *pIsDisabled
    );

パラメータ

pnStreamsAvailable
[out] 取得された利用可能なサブピクチャ ストリームの数へのポインタ。
pnCurrentStream
[out] 取得された現在選択されているサブピクチャ ストリーム番号へのポインタ。
pIsDisabled
[out] サブピクチャの表示が無効になっているかどうかを示す値へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 入力引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_OUTOFMEMORY | メモリ不足 (バッファ スペース不足)。
E_POINTER | NULL ポインタ引数。
E_UNEXPECTED | DVD が初期化されていないか、またはドメインが DVD_DOMAIN_Title ではない。
VFW_E_DVD_OPERATION_INHIBITED | 現在の DVD ビデオのディスクを作成しているため、現時点では要求されたアクションをムービーで実行できない。
S_OK | 成功。
VFW_E_DVD_INVALIDDOMAIN | 要求されたアクションはこのドメインではサポートされていない (DVD_DOMAIN)。

注意

強制的にアクティブにするストリームとして作成されたサブピクチャ ストリームは、アプリケーションが IDvdControl::SubpictureStreamChange メソッドでサブピクチャの表示を無効にしていても表示される。

このメソッドは、ドメインが DVD_DOMAIN_Title でない限りエラーを返す。詳細については、「DVD_DOMAIN」を参照すること。

IDvdInfo::GetCurrentSubpictureAttributes

IDvdInfo インターフェイス

現在のタイトルまたはメニューの現在のサブピクチャ ストリームの属性を取得する。

構文

HRESULT GetCurrentSubpictureAttributes(
    DVD_SubpictureATR *pATR
    );

パラメータ

pATR
[out] 取得されたサブピクチャ属性へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 入力引数が無効。
E_FAIL | 指定されたサブピクチャが属性を持っていない。
E_NOTIMPL | メソッドがサポートされていない。
E_OUTOFMEMORY | メモリ不足 (バッファ スペース不足)。
E_POINTER | NULL ポインタ引数。
E_UNEXPECTED | DVD が初期化されていないか、またはドメインが DVD_DOMAIN_Title ではない。
VFW_E_DVD_OPERATION_INHIBITED | 現在の DVD ビデオのディスクを作成しているため、現時点では要求されたアクションをムービーで実行できない。
S_OK | 成功。

注意

このメソッドは、ドメインが DVD_DOMAIN_VideoManagerMenu、DVD_DOMAIN_VideoTitleSetMenu、または DVD_DOMAIN_Title でない限りエラーを返す。詳細については、「DVD_DOMAIN」を参照すること。

DVD_SubpictureATR については、「DVD ビデオの仕様」を参照すること。

IDvdInfo::GetCurrentUOPS

IDvdInfo インターフェイス

現在有効になっている IDvdControl メソッドを取得する。

構文

HRESULT GetCurrentUOPS(
    VALID_UOP_SOMTHING_OR_OTHER *pUOP
    );

パラメータ

pUOP
[out] すべてのユーザー操作 (UOP) のビットが格納されている DWORD 値へのポインタ。DWORD 内の各ビットは、個々のユーザー操作の状態 (有効または無効) を表す。あるユーザー操作に対応するビットがセットされていれば、そのユーザー操作は禁止されている。詳細については、「注意」を参照すること。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 入力引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_OUTOFMEMORY | メモリ不足 (バッファ スペース不足)。
E_POINTER | NULL ポインタ引数。
E_UNEXPECTED | DVD が初期化されていないか、またはドメインが DVD_DOMAIN_Title ではない。
VFW_E_DVD_OPERATION_INHIBITED | 現在の DVD ビデオのディスクを作成しているため、現時点では要求されたアクションをムービーで実行できない。
S_OK | 成功。
VFW_E_DVD_INVALIDDOMAIN | 要求されたアクションはこのドメインではサポートされていない (DVD_DOMAIN)。

注意

このメソッドは、いずれのドメインでも有効である。詳細については、「DVD_DOMAIN」を参照すること。

pUOP の値は、次のように定義されたビット フィールドである。

ビット | フラグ | ユーザー関数
0 | UOP_FLAG_Title_Or_Time_Play | TitlePlay、TimePlay
1 | UOP_FLAG_Chapter_Search_Or_Play | ChapterSearch、ChapterPlay
2 | UOP_FLAG_Title_Play | TitlePlay
3 | UOP_FLAG_Stop | StopForResume
4 | UOP_FLAG_GoUp | GoUp
5 | UOP_FLAG_Time_Or_Chapter_Search | TimeSearch、ChapterSearch
6 | UOP_FLAG_Prev_Or_Top_PG_Search | PrevPGSearch、TopPGSearch
7 | UOP_FLAG_Next_PG_Search | NextPGSearch
8 | UOP_FLAG_Forward_Scan | ForwardScan
9 | UOP_FLAG_Backward_Scan | BackwardScan
10 | UOP_FLAG_Title_Menu_Call | パラメータ値 2 (DVD_MENU_Title) の MenuCall
11 | UOP_FLAG_Root_Menu_Call | パラメータ値 3 (DVD_MENU_Root) の MenuCall
12 | UOP_FLAG_SubPic_Menu_Call | パラメータ値 4 (DVD_MENU_Subpicture) の MenuCall
13 | UOP_FLAG_Audio_Menu_Call | パラメータ値 5 (DVD_MENU_Audio) の MenuCall
14 | UOP_FLAG_Angle_Menu_Call | パラメータ値 6 (DVD_MENU_Angle) の MenuCall
15 | UOP_FLAG_Chapter_Menu_Call | パラメータ値 7 (DVD_MENU_Chapter) の MenuCall
16 | UOP_FLAG_Resume | Resume
17 | UOP_FLAG_Button_Select_Or_Activate | UpperButtonSelect、 LowerButtonSelect、 LeftButtonSelect、RightButtonSelect、ButtonActivate、ButtonSelectAndActivate
18 | UOP_FLAG_Still_Off | StillOff
19 | UOP_FLAG_Pause_On | PauseOn、MenuLanguageSelect
20 | UOP_FLAG_Audio_Stream_Change | AudioStreamChange
21 | UOP_FLAG_SubPic_Stream_Change | SubpictureStreamChange
22 | UOP_FLAG_Angle_Change | AngleChange、ParentalLevelSelect
23 | UOP_FLAG_Karaoke_Audio_Pres_Mode_Change | KaraokeAudioPresentationModeChange
24 | UOP_FLAG_Video_Pres_Mode_Change | VideoModePreferrence

DVD タイトルでは、再生中にほとんど任意の位置で個々のユーザー操作を許可または禁止できるため、このメソッドは有用である。

IDvdInfo::GetCurrentVideoAttributes

IDvdInfo インターフェイス

現在のタイトルまたはメニューの現在のビデオ属性を取得する。

構文

HRESULT GetCurrentVideoAttributes(
    DVD_VideoATR *pATR
    );

パラメータ

pATR
[out] 取得されたビデオ属性へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 入力引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_OUTOFMEMORY | メモリ不足 (バッファ スペース不足)。
E_POINTER | NULL ポインタ引数。
E_UNEXPECTED | DVD が初期化されていないか、またはドメインが DVD_DOMAIN_Title ではない。
VFW_E_DVD_OPERATION_INHIBITED | 現在の DVD ビデオのディスクを作成しているため、現時点では要求されたアクションをムービーで実行できない。
S_OK | 成功。
VFW_E_DVD_INVALIDDOMAIN | 要求されたアクションはこのドメインではサポートされていない (DVD_DOMAIN)。

注意

このメソッドは、ドメインが DVD_DOMAIN_VideoManagerMenu、DVD_DOMAIN_VideoTitleSetMenu、または DVD_DOMAIN_Title でない限りエラーを返す。詳細については、「DVD_DOMAIN」を参照すること。

DVD_VideoATR については、「DVD ビデオの仕様」を参照すること。

IDvdInfo::GetCurrentVolumeInfo

IDvdInfo インターフェイス

現在の DVD ボリューム情報を取得する。

構文

HRESULT GetCurrentVolumeInfo(
    ULONG *pNumOfVol,
    ULONG *pThisVolNum,
    DVD_DISC_SIDE *pSide,
    ULONG *pNumOfTitles
    );

パラメータ

pNumOfVol
[out] 取得されたボリューム セット内のボリュームの数へのポインタ。
pThisVolNum
[out] 取得されたこのルート ディレクトリのボリューム番号へのポインタ。
pSide
[out] 取得された現在のディスク面 (DVD_DISC_SIDE) へのポインタ。
pNumOfTitles
[out] 取得されたこのボリュームで利用可能なタイトルの数へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 入力引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_OUTOFMEMORY | メモリ不足 (バッファ スペース不足)。
E_POINTER | NULL ポインタ引数。
E_UNEXPECTED | DVD が初期化されていないか、またはドメインが DVD_DOMAIN_Title ではない。
VFW_E_DVD_OPERATION_INHIBITED | 現在の DVD ビデオのディスクを作成しているため、現時点では要求されたアクションをムービーで実行できない。
S_OK | 成功。
VFW_E_DVD_INVALIDDOMAIN | 要求されたアクションはこのドメインではサポートされていない (DVD_DOMAIN)。

注意

このメソッドは、いずれのドメインでも有効である。詳細については、「DVD_DOMAIN」を参照すること。

IDvdInfo::GetDVDTextInfo

IDvdInfo インターフェイス

さまざまな言語のタイトル名、ボリューム名、プロデューサー名、ボーカリスト名などの説明テキストが格納される TXTDT_MG 構造体を取得する。

構文

HRESULT GetDVDTextInfo(
    BYTE *pTextManager,
    ULONG cbBufSize,
    ULONG *pcbActualSize
    );

パラメータ

pTextManager
[out, size_is(cbBufSize)] 取得されたテキスト マネージャへのポインタ。
cbBufSize
[in] pTextManager のバッファ サイズ (バイト単位)。
pcbActualSize
[out] 返されたデータのバイト数が格納されている値へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 入力引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_OUTOFMEMORY | メモリ不足 (バッファ スペース不足)。
E_POINTER | NULL ポインタ引数。
E_UNEXPECTED | DVD が初期化されていないか、またはドメインが DVD_DOMAIN_Title ではない。
VFW_E_DVD_OPERATION_INHIBITED | 現在の DVD ビデオのディスクを作成しているため、現時点では要求されたアクションをムービーで実行できない。
S_OK | 成功。
VFW_E_DVD_INVALIDDOMAIN | 要求されたアクションはこのドメインではサポートされていない (DVD_DOMAIN)。

注意

このメソッドは、いずれのドメインでも有効である。詳細については、「DVD_DOMAIN」を参照すること。

cbBufSize で渡されたバッファ サイズがデータに比べて小さすぎる場合 (たとえば、cbBufSize がゼロの場合)、このメソッドは E_OUTOFMEMORY を返し、pcbActualSize の指す値を必要なサイズに設定する。

詳細については、「DVD ビデオの仕様」の Section 4.1.6 および Annex A を参照すること。

IDvdInfo::GetNumberOfChapters

IDvdInfo インターフェイス

特定のタイトルに対して定義されているチャプターの数を取得する。

構文

HRESULT GetNumberOfChapters(
    ULONG ulTitle,
    ULONG *pNumberOfChapters
    );

パラメータ

ulTitle
[in] チャプター数を取得するタイトル。
pNumberOfChapters
[out] 指定されたタイトルの取得されたチャプター数へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 入力引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_OUTOFMEMORY | メモリ不足 (バッファ スペース不足)。
E_POINTER | NULL ポインタ引数。
E_UNEXPECTED | DVD が初期化されていないか、またはドメインが DVD_DOMAIN_Title ではない。
VFW_E_DVD_OPERATION_INHIBITED | 現在の DVD ビデオのディスクを作成しているため、現時点では要求されたアクションをムービーで実行できない。
S_OK | 成功。
VFW_E_DVD_INVALIDDOMAIN | 要求されたアクションはこのドメインではサポートされていない (DVD_DOMAIN)。

注意

このメソッドは、いずれのドメインでも有効である。詳細については、「DVD_DOMAIN」を参照すること。

IDvdInfo::GetPlayerParentalLevel

IDvdInfo インターフェイス

DVD プレーヤーの現在のペアレンタル ロック レベルと国コードの設定を取得する。

構文

HRESULT GetPlayerParentalLevel(
    ULONG *pParentalLevel,
    ULONG *pCountryCode
    );

パラメータ

pParentalLevel
[out] 現在のペアレンタル ロック レベルを示す値へのポインタ。
pCountryCode
[out] 現在の国コードを示す値へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 入力引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_OUTOFMEMORY | メモリ不足 (バッファ スペース不足)。
E_POINTER | NULL ポインタ引数。
E_UNEXPECTED | DVD が初期化されていないか、またはドメインが DVD_DOMAIN_Title ではない。
VFW_E_DVD_OPERATION_INHIBITED | 現在の DVD ビデオのディスクを作成しているため、現時点では要求されたアクションをムービーで実行できない。
S_OK | 成功。
VFW_E_DVD_INVALIDDOMAIN | 要求されたアクションはこのドメインではサポートされていない (DVD_DOMAIN)。

注意

このメソッドは、いずれのドメインでも有効である。詳細については、「DVD_DOMAIN」を参照すること。

定義されているペアレンタル ロック レベルについては、「DVD ビデオの仕様」の表 3.3.4-1 を参照すること。

有効なペアレンタル ロック レベルは、ペアレンタル ロックが有効になっている場合は 1 から 8 の間であり、ペアレンタル ロックが無効になっている場合は 0xffffffff である。

国コードについては、ISO3166 : Alpha-2 コードを参照すること。

IDvdInfo::GetRoot

IDvdInfo インターフェイス

プレーヤーで設定されているルート ディレクトリを取得する。

構文

HRESULT GetRoot(
    LPSTR pRoot,
    ULONG cbBufSize,
    ULONG *pcbActualSize
    );

パラメータ

pRoot
[out, size_is(cbBufSize)] ルート文字列を受け取るバッファへのポインタ。Unicode スタイルの文字列を渡すという COM 規則に反して、ルート文字列では ANSI 文字を使用する点に注意すること。
cbBufSize
[in] 渡されたバッファのサイズ (バイト単位)。
pcbActualSize
[out] 返された実際のデータのサイズが格納されている値へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 入力引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_OUTOFMEMORY | メモリ不足 (バッファ スペース不足)。
E_POINTER | NULL ポインタ引数。
E_UNEXPECTED | DVD が初期化されていないか、またはドメインが DVD_DOMAIN_Title ではない。
VFW_E_DVD_OPERATION_INHIBITED | 現在の DVD ビデオのディスクを作成しているため、現時点では要求されたアクションをムービーで実行できない。
S_OK | 成功。
VFW_E_DVD_INVALIDDOMAIN | 要求されたアクションはこのドメインではサポートされていない (DVD_DOMAIN)。

注意

有効なルートが見つかると、このメソッドはルート文字列を返す。それ以外の場合は、pcbActualSize をゼロにして返し、有効なルート ディレクトリが見つからない、または初期化されていないことを示す。

IDvdInfo::GetSubpictureLanguage

IDvdInfo インターフェイス

現在のタイトル内の指定されたサブピクチャ ストリームの言語を取得する。

構文

HRESULT GetSubpictureLanguage(
    ULONG nStream,
    LCID *pLanguage );

パラメータ

nStream
[in] ストリーム番号。
pLanguage
[out] 取得された言語へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 入力引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_OUTOFMEMORY | メモリ不足 (バッファ スペース不足)。
E_POINTER | NULL ポインタ引数。
E_UNEXPECTED | DVD が初期化されていないか、またはドメインが DVD_DOMAIN_Title ではない。
VFW_E_DVD_OPERATION_INHIBITED | 現在の DVD ビデオのディスクを作成しているため、現時点では要求されたアクションをムービーで実行できない。
S_OK | 成功。
VFW_E_DVD_INVALIDDOMAIN | 要求されたアクションはこのドメインではサポートされていない (DVD_DOMAIN)。

注意

このメソッドは、ドメインが DVD_DOMAIN_Title でない限りエラーを返す。詳細については、「DVD_DOMAIN」を参照すること。

このメソッドはメニューの言語は返さない。ストリームに言語が含まれていない場合、このメソッドは、pLanguage が指す値をゼロに設定する。pLanguage から読み取り可能な文字列名を作成するには、次のように Win32 GetLocaleInfo 関数を呼び出す。LOCALE_SENGLANGUAGE はロケール情報型であり、pszString は要求されたデータを受け取るバッファへのポインタであり、cbSize は pszString のサイズを指定する。

GetLocaleInfo(*pLanguage, LOCALE_SENGLANGUAGE, pszString, cbSize);

IDvdInfo::GetTitleAttributes

IDvdInfo インターフェイス

メニューを含む指定されたタイトルのすべてのビデオ ストリーム、オーディオ ストリーム、およびサブピクチャ ストリームの属性を取得する。

構文

HRESULT GetTitleAttributes(
    ULONG nTitle,
    DVD_ATR *pATR );

パラメータ

nTitle
[in] 要求されているタイトル番号。現在のタイトルの場合は 0xFFFFFFFF を指定する。
pATR
[out] 取得された属性構造体 (DVD_ATR) へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 入力引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_OUTOFMEMORY | メモリ不足 (バッファ スペース不足)。
E_POINTER | NULL ポインタ引数。
E_UNEXPECTED | DVD が初期化されていないか、またはドメインが DVD_DOMAIN_Title ではない。
VFW_E_DVD_OPERATION_INHIBITED | 現在の DVD ビデオのディスクを作成しているため、現時点では要求されたアクションをムービーで実行できない。
S_OK | 成功。
VFW_E_DVD_INVALIDDOMAIN | 要求されたアクションはこのドメインではサポートされていない (DVD_DOMAIN)。

注意

このメソッドは、いずれのドメインでも有効である。詳細については、「DVD_DOMAIN」を参照すること。

IDvdInfo::GetTitleParentalLevels

IDvdInfo インターフェイス

特定のタイトルに対して定義されているペアレンタル ロック レベルを取得する。

構文

HRESULT GetTitleParentalLevels(
    ULONG ulTitle,
    ULONG *pParentalLevels
    );

パラメータ

ulTitle
[in] ペアレンタル ロック レベルが要求されているタイトル。
pParentalLevels
[out] タイトルに対して定義されているペアレンタル ロック レベルの論理 OR の組み合わせへのポインタ。設定レベルが高くなるほど、再生されないコンテンツが多くなる。有効なペアレンタル ロック レベルは以下のとおりである。
  • DVD_PARENTAL_LEVEL_8
  • DVD_PARENTAL_LEVEL_7
  • DVD_PARENTAL_LEVEL_6
  • DVD_PARENTAL_LEVEL_5
  • DVD_PARENTAL_LEVEL_4
  • DVD_PARENTAL_LEVEL_3
  • DVD_PARENTAL_LEVEL_2
  • DVD_PARENTAL_LEVEL_1

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 入力引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_OUTOFMEMORY | メモリ不足 (バッファ スペース不足)。
E_POINTER | NULL ポインタ引数。
E_UNEXPECTED | DVD が初期化されていないか、またはドメインが DVD_DOMAIN_Title ではない。
VFW_E_DVD_OPERATION_INHIBITED | 現在の DVD ビデオのディスクを作成しているため、現時点では要求されたアクションをムービーで実行できない。
S_OK | 成功。
VFW_E_DVD_INVALIDDOMAIN | 要求されたアクションはこのドメインではサポートされていない (DVD_DOMAIN)。

注意

このメソッドは、いずれのドメインでも有効である。詳細については、「DVD_DOMAIN」を参照すること。

IDvdInfo::GetTotalTitleTime

IDvdInfo インターフェイス

現在のタイトルの総再生時間を取得する。

構文

HRESULT GetTotalTitleTime(
    ULONG *pTotalTime
    );

パラメータ

pTotalTime
[out] 時、分、秒、フレームから構成される DVD_TIMECODE フォーマットで表す総時間へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 入力引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_OUTOFMEMORY | メモリ不足 (バッファ スペース不足)。
E_POINTER | NULL ポインタ引数。
E_UNEXPECTED | DVD が初期化されていないか、またはドメインが DVD_DOMAIN_Title ではない。
VFW_E_DVD_OPERATION_INHIBITED | 現在の DVD ビデオのディスクを作成しているため、現時点では要求されたアクションをムービーで実行できない。
S_OK | 成功。
VFW_E_DVD_INVALIDDOMAIN | 要求されたアクションはこのドメインではサポートされていない (DVD_DOMAIN)。

注意

このメソッドは、ドメインが DVD_DOMAIN_Title でない限りエラーを返す。詳細については、「DVD_DOMAIN」を参照すること。

このメソッドの用途は、意図的に、分岐構造を持たない単純なムービーに限定されている。

IDvdInfo::GetVMGAttributes

IDvdInfo インターフェイス

ビデオ マネージャ (VMG) メニューのすべてのビデオ ストリーム、オーディオ ストリーム、およびサブピクチャ ストリームの属性を取得する。

構文

HRESULT GetVMGAttributes(
    DVD_ATR *pATR
    );

パラメータ

pATR
[out] 取得された属性構造体 (DVD_ATR) へのポインタ。

戻り値

インターフェイスの実装に応じた HRESULT 値を返す。通常の戻り値は次のいずれかである。
E_FAIL | 失敗。
E_INVALIDARG | 入力引数が無効。
E_NOTIMPL | メソッドがサポートされていない。
E_OUTOFMEMORY | メモリ不足 (バッファ スペース不足)。
E_POINTER | NULL ポインタ引数。
E_UNEXPECTED | DVD が初期化されていないか、またはドメインが DVD_DOMAIN_Title ではない。
VFW_E_DVD_OPERATION_INHIBITED | 現在の DVD ビデオのディスクを作成しているため、現時点では要求されたアクションをムービーで実行できない。
S_OK | 成功。
VFW_E_DVD_INVALIDDOMAIN | 要求されたアクションはこのドメインではサポートされていない (DVD_DOMAIN)。

注意

このメソッドは、いずれのドメインでも有効である。詳細については、「DVD_DOMAIN」を参照すること。

ビデオ マネージャには、DVD_MENU_Title メニューなど、複数のストリームのグループが含まれており、ストリームは特定のタイトル番号と関連付けられていない。


IEnumRegFilters インターフェイス

注 : このインターフェイスの使用は避けること。新しいアプリケーションでは、モニカを列挙し、IEnumMoniker インターフェイスへのポインタを返す IFilterMapper2::EnumMatchingFilters を使用すること。

このインターフェイスは、登録済みフィルタを列挙するメソッドを備えている。IFilterMapper::EnumMatchingFilters メソッドが、このインターフェイスへのポインタを返す。ただし、IFilterMapper に代わって、IFilterMapper2 が使用されるようになった。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IEnumRegFilters メソッド | 説明
Next | 条件を満たす次のフィルタを配列に設定する。
Skip | 現在は実装されていない。
Reset | 1 番目のフィルタを先頭に、Next メソッドを再び開始する。
Clone | 現在は実装されていない。

IEnumRegFilters::Clone

IEnumRegFilters インターフェイス

現在の列挙子の状態と同じ状態の、別の列挙子を作成する。

このメソッドは現在実装されていない。E_NOTIMPL を返す。

構文

HRESULT Clone(
    IEnumRegFilters **ppEnum
);

パラメータ

ppEnum
[out] 重複する列挙子インターフェイスへのポインタのアドレス。

戻り値

E_NOTIMPL を返す。

IEnumRegFilters::Next

IEnumRegFilters インターフェイス

列挙子の作成時に指定した条件を満たす、cFilters パラメータで指定される次のフィルタ セットの記述を配列に設定する。

構文

HRESULT Next(
    ULONG cFilters,
    REGFILTER **apRegFilter,
    ULONG *pcFetched
);

パラメータ

cFilters
[in] フィルタ数。
apRegFilter
[out] REGFILTER ポインタで構成される配列へのポインタのアドレス。
pcFetched
[out] 実際に渡されたフィルタ数へのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。

E_INVALIDARG | 無効な引数。
E_OUTOFMEMORY | メモリ不足。
E_POINTER | Null ポインタ引数。
E_UNEXPECTED | 予期せぬエラー。
S_FALSE | 取得されたフィルタ数が、要求された数よりも少ない。
S_OK | 成功。
VFW_E_ENUM_OUT_OF_SYNC | 列挙子が無効になった。詳細については、「注意」を参照すること。

注意

呼び出し側のアプリケーションは、Microsoft Win32 CoTaskMemFree 関数を使用して、配列に返された各 REGFILTER ポインタを解放する必要がある。REGFILTER 構造体の Name メンバを個別に解放してはならない。IEnumRegFilters::Next は、REGFILTER 構造体の一部として、この文字列に対してメモリを割り当てているからである。

登録済みフィルタ数が変更を受けると、列挙子の状態とレジストリの状態の一貫性が失われる。この結果、VFW_E_ENUM_OUT_OF_SYNC が返される。データが無効の可能性があるため、列挙子への前の呼び出しから取得したデータはいずれも破棄し、Reset メソッドを呼び出して列挙子を更新する必要がある。この後であれば、Next メソッドを正しく呼び出すことができる。

IEnumRegFilters::Reset

IEnumRegFilters インターフェイス

列挙子をリセットする。これによって、IEnumRegFilters::Next メソッドの次回の呼び出しは、再び先頭のフィルタ (ある場合) から開始する。

構文

HRESULT Reset(void);

戻り値

成功を示す S_OK を返す。

IEnumRegFilters::Skip

IEnumRegFilters インターフェイス

列挙シーケンスの中で指定の項目数をスキップする。

このメソッドは現在実装されていない。E_NOTIMPL を返す。

構文

HRESULT Skip(
  ULONG celt
);

パラメータ

celt
[in] スキップする項目数。

戻り値

E_NOTIMPL を返す。


IFilterMapper インターフェイス

注 : このインターフェイスの使用は避けること。既存のアプリケーションとの後方互換性を保つため、継続してサポートされるが、新しいアプリケーションでは IFilterMapper2 インターフェイスを使用すること。

このインターフェイスは、フィルタを登録および登録解除するメソッドと、特性に基づいてフィルタを検索するメソッドを提供する。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IFilterMapper メソッド | 説明
RegisterFilter | レジストリにフィルタの詳細を記録する。
RegisterFilterInstance | フィルタの識別可能なインスタンスを登録する。
RegisterPin | レジストリにピンの詳細を記録する。
RegisterPinType | レジストリにピンのタイプを追加する。
UnregisterFilter | レジストリからフィルタを削除する。
UnregisterFilterInstance | フィルタの識別可能なインスタンスを削除する。
UnregisterPin | レジストリからピンを削除する。
EnumMatchingFilters | 特定の要件を満たすフィルタをすべて検索する。

IFilterMapper::EnumMatchingFilters

IFilterMapper インターフェイス

指定された要件を満たす登録済みフィルタを列挙する列挙子を提供する。

構文

HRESULT EnumMatchingFilters(
    IEnumRegFilters **ppEnum,
    DWORD dwMerit,
    BOOL bInputNeeded,
    CLSID clsInMaj,
    CLSID clsInSub,
    BOOL bRender,
    BOOL bOutputNeeded,
    CLSID clsOutMaj,
    CLSID clsOutSub
);

パラメータ

ppEnum
[out] 返された列挙子へのポインタのアドレス。
dwMerit
[in] 列挙するフィルタの最小メリット値。
bInputNeeded
入力ピンが少なくとも 1 つ必要かどうかを示す値。TRUE は、必要であることを示す。
clsInMaj
[in] 必要な入力メジャー タイプ。不要の場合は、GUID_NULL を設定する。
clsInSub
[in] 必要な入力サブタイプ。不要の場合は、GUID_NULL を設定する。
bRender
[in] フィルタが入力をレンダリングする必要があるかどうかを指定するフラグ。TRUE は、レンダリングする必要があることを示す。
bOutputNeeded
出力ピンが少なくとも 1 つ必要かどうかを示す値。TRUE は、必要であることを示す。
clsOutMaj
[in] 必要な出力メジャー タイプ。不要の場合は、GUID_NULL を設定する。
clsOutSub
[in] 必要な出力サブタイプ。不要の場合は、GUID_NULL を設定する。

戻り値

HRESULT 値を返す。

注意

ppEnum パラメータに、要件を満たすフィルタを列挙する列挙子が設定される。dwMerit パラメータのメリット値の詳細については、「IFilterMapper::RegisterFilter」を参照すること。

IFilterMapper::RegisterFilter

IFilterMapper インターフェイス

レジストリにフィルタを追加する。このフィルタは列挙できる。

構文

HRESULT RegisterFilter(
    CLSID clsid,
    LPCWSTR Name,
    DWORD dwMerit
);

パラメータ

clsid
[in] フィルタのグローバル ユニーク識別子 (GUID)。
Name
[in] フィルタの内容を表すわかりやすい名前。
dwMerit
[in] 列挙での優先順位。メリット値が高いフィルタほど先に列挙される。

戻り値

HRESULT 値を返す。

注意

メリット (dwMerit パラメータで定義する) は、IGraphBuilder::Connect、IGraphBuilder::Render、または IGraphBuilder::RenderFile の呼び出しによってフィルタ グラフ マネージャが操作を実行するときに、フィルタを試す順序を制御する。フィルタ グラフ マネージャは、正しいメディア タイプで登録されているフィルタをすべて検索したうえで、最もメリットの高いものを試す。このとき、メリットが等しいフィルタが複数あれば、登録されているその他の条件に基づいて選択する。

dwMerit パラメータでは、事前に定義された以下の値を使用できる。その他の値 (MERIT_NORMAL+1 など) も使用できるが、その場合には (MERIT_NORMAL+MERIT_UNLIKELY)/2 のような式を使って計算するとよい。こうすると下位ビットが残り、そのビットを使ってさらに細かく区別できるからである。
0x900000 | ハードウェア レンダラ フィルタ。このメリット値を持つフィルタは最初に試される。
MERIT_PREFERRED (0x800000) | 操作を直接実行することが多いフィルタ (レンダラなど)。
0x680000 | MPEG デコンプレッサ フィルタ。フィルタ グラフ内で機能するかどうかの判断に時間がかかる AVI デコンプレッサ フィルタより先に検索される。
MERIT_NORMAL (0x600000) | 接続の確立に関与する可能性が高いフィルタ。AVI デコンプレッサ フィルタおよびスプリッタ 変換フィルタは、この値で登録される。
MERIT_UNLIKELY (0x400000) | 接続の確立に関与する可能性があるフィルタ (カラー スペース変換フィルタなど)。フィルタ グラフ マネージャは、ほかのオプションに失敗した場合にのみ、このフィルタを使用する。ソース フィルタはこの値で登録する。
MERIT_DO_NOT_USE (0x200000) | 接続の確立に関与しないフィルタ。フィルタ グラフ マネージャは、フィルタ グラフを自動構築するとき、これ以下の値で登録されたフィルタを試さない。明示的に追加する必要があるフィルタを、事前に定義されたフィルタ グラフの一部として登録するか、または IFilterGraph::AddFilter を使って追加するときには、この値を使用する。例としては、ティー フィルタまたはエフェクト フィルタが挙げられる。
MERIT_HW_COMPRESSOR (0x100050) | ハードウェア コンプレッサ フィルタ。フィルタ グラフ マネージャは、フィルタ グラフを自動構築するとき、この値で登録されたフィルタを試さない。
MERIT_SW_COMPRESSOR (0x100000) | ソフトウェア コンプレッサ フィルタ。フィルタ グラフ マネージャは、フィルタ グラフを自動構築するとき、この値で登録されたフィルタを試さない。

IFilterMapper::RegisterFilterInstance

IFilterMapper インターフェイス

フィルタの識別可能なインスタンスを登録する。

構文

HRESULT RegisterFilterInstance(
    CLSID clsid,
    LPCWSTR Name,
    CLSID *MRId
);

パラメータ

clsid
[in] フィルタの GUID。
Name
[in] インスタンスの内容を表すわかりやすい名前。
MRId
[out] 返されたメディア リソース ID へのポインタ。このパラメータは、このフィルタのこのインスタンスに付けられたローカル一意識別子である。

戻り値

HRESULT 値を返す。

注意

このメソッドは、同じドライバで制御する類似のサウンド カードが 2 つ利用可能で、音を鳴らすサウンド カードを選ぶ必要があるような場合に使用する。フィルタのインスタンスが 1 つしかない場合 (コンピュータにあるサウンド カードが 1 つのみの場合など)、またはフィルタのインスタンスがすべて同等である場合、このメソッドは必要ない。

フィルタ自体は既に登録されていなければならない。

IFilterMapper::RegisterPin

IFilterMapper インターフェイス

レジストリにピンの詳細を記録する。

構文

HRESULT RegisterPin(
    CLSID Filter,
    LPCWSTR Name,
    BOOL bRendered,
    BOOL bOutput,
    BOOL bZero,
    BOOL bMany,
    CLSID ConnectsToFilter,
    LPWSTR ConnectsToPin
);

パラメータ

Filter
[in] フィルタの GUID。
Name
[in] ピンの名前。フィルタ内で一意でなければならない。タイプ情報を示す以外に意味はない。フィルタの列挙で問題が発生するため、ピンに 99 文字を超える名前を使用してはならない。
bRendered
[in] フィルタがこの入力をレンダリングするかどうかを指定する値。レンダリングする場合は、TRUE を設定する。それ以外の場合は、FALSE を設定する。
bOutput
[in] 出力ピンかどうかを指定する値。出力ピンの場合は、TRUE を設定する。それ以外の場合は、FALSE を設定する。
bZero
[in] このピンのインスタンスを 1 つも持たないフィルタを許すかどうかを指定する値。許す場合は、TRUE を設定する。それ以外の場合は、FALSE を設定する。たとえば、サウンド トラックのないムービーの場合、デコンプレッサ フィルタでサウンド出力ピンを作成する必要はない。
bMany
[in] このピンのインスタンスを複数持つフィルタを許すかどうかを指定する値。許す場合は、TRUE を設定する。それ以外の場合は、FALSE を設定する。たとえば、ミキサーには入力ピンのインスタンスが複数必要になる。
ConnectsToFilter
[in] 予約済み。NULL でなければならない。このパラメータは、フィルタ グラフ外部への接続を持つシステム規模のミキサーのようなフィルタでの使用を目的としている。ただし、まだ実装はされない。
ConnectsToPin
[in] 予約済み。NULL でなければならない。

戻り値

HRESULT 値を返す。

IFilterMapper::RegisterPinType

IFilterMapper インターフェイス

ピンのタイプを登録する。

構文

HRESULT RegisterPinType(
    CLSID clsFilter,
    LPCWSTR strName,
    CLSID clsMajorType,
    CCLSID clsSubType
);

パラメータ

clsFilter
ピンが属するフィルタのクラス識別子 (CLSID)。
strName
ピンの名前。
clsMajorType
このピン クラスでサポートされるメディア サンプルのメジャー タイプ。
clsSubType
このピン クラスでサポートされるメディア サンプルのサブタイプ。

戻り値

HRESULT 値を返す。

注意

clsMajorType パラメータおよび clsSubType パラメータは、ピンのメディア タイプを指定するものであり、それぞれ AM_MEDIA_TYPE 構造体の majortype メンバおよび subtype メンバに対応する。

IFilterMapper::UnregisterFilter

IFilterMapper インターフェイス

レジストリからフィルタを削除する。

構文

HRESULT UnregisterFilter(
    CLSID Filter
);

パラメータ

Filter
[in] フィルタの GUID。

戻り値

HRESULT 値を返す。

IFilterMapper::UnregisterFilterInstance

IFilterMapper インターフェイス

レジストリからフィルタのインスタンスを削除する。

構文

HRESULT UnregisterFilterInstance(
    CLSID MRId
);

パラメータ

MRId
[in] このインスタンスのメディア リソース ID。

戻り値

HRESULT 値を返す。

IFilterMapper::UnregisterPin

IFilterMapper インターフェイス

レジストリからピンを削除する。

構文

HRESULT UnregisterPin(
    CLSID Filter,
    LPCWSTR Name
);

パラメータ

Filter
[in] このピンが属するフィルタの GUID。
Name
[in] ピンの名前。

戻り値

HRESULT 値を返す。


DirectShow グラフ ファイル フォーマット

ここでは、GraphEdit によって作成されて保存された Microsoft® DirectShow® グラフ ファイル (.grf) のフォーマットについて説明する。

docfile (保存ファイル) は、ActiveMovieGraph という名前のストリームを格納している。この単独のストリームの中に、すべてのフィルタ、フィルタ名、ファイル名、接続などが含まれている。

グラフをロードするには :

  • 保存ファイル名を RenderFile に渡す。RenderFile はそれがメディア ファイルではなく保存されたグラフであると認識して、グラフを復元する。

または、

  1. (StgOpenStorage を使用して) 保存ファイルを開く。
  2. フィルタ グラフ マネージャに対して IPersistStream を照会する。
  3. (IStorage::OpenStream を使用して) L"ActiveMovieGraph" ストリームを開く。
  4. (IPersistStream::Load を使用して) ストリームをフィルタ グラフに渡す。

ストリーム内のグラフの構文を以下に示す。

<graph> ::= <version3><filters><connections><clock>END | <version2><filters><connections>END
<version3> ::= 0003\r\n
<version2> ::= 0002\r\n
<clock> ::= CLOCK <b> <required><b><clockid>\r\n
<required> ::= 1|0
<clockid> ::= <n>|<class id>
<filters ::= FILTERS <b>[<filter list><b>]
<connections> ::= CONNECTIONS [<b> <connection list>]
<filter list> ::= [<filter> <b>] <filter list>
<connection list> ::= [<connection><b>]<connection list>
<filter> ::= <n><b>"<name>"<b><class id><b>[<file>]<length><b1><filter data>
<file> ::= SOURCE "<name>"<b> | SINK "<name>"<b>
<class id> ::= 標準文字列フォーマットのフィルタのクラス ID。
<name> ::= " を含まない任意の文字シーケンス。
<length> ::= 符号なし 10 進数 (たとえば 23) を表す文字列。
これは、空白をはさんで後に続くデータのバイト数である。
<b> ::= 空白、\t、\r、または \n の任意の組み合わせ。
<b1> ::= 1 つの空白文字。
<n> ::= 整数 (たとえば 0001、0002、0003) の識別子。
<connection> ::= <n1><b>"<pin1 id>"<b><n2><b>"<pin2 id>" <media type>
<n1> ::= 1 番目のフィルタの識別子。
<n2> ::= 2 番目のフィルタの識別子。
<pin1 id> ::= <name>
<pin2 id> ::= <name>
<media type> ::= <major type><b><sub type><b><flags><length><b1><format>
<major type> ::= <class id>
<sub type> ::= <class id>
<flags> ::= <FixedSizeSamples><b><TemporalCompression><b>
<FixedSizeSamples> ::= 1|0
<TemporalCompression> ::= 1|0
<Format> ::= <SampleSize><b><FormatType><b><FormatLength><b1><FormatData>
<FormatType> ::= 標準文字列フォーマットのフォーマットのクラス ID。
<FormatLength> ::= 符号なし 10 進数 (たとえば 23) を表す文字列。
これは、空白をはさんで後に続くデータのバイト数である。
<FormatData> ::= バイナリ データ。

出力では、フィルタごと、接続ごと、およびキーワード FILTERS と CONNECTIONS ごとに復帰改行 (\r\n) が挿入される。それ以外の <B> は 1 つの空白である。キーワード FILTERS、CONNECTIONS、および END はローカライズ可能ではない。フィルタ データとフォーマット データはバイナリなので、不適切な改行や NULL 値などを含むことがある。

以下に、出力の例を示す (接続行は長いのでここでは分割している。コメントは、<コメント> のフォーマットで示してある)。

0002
<構文のバージョン 2>
FILTERS
0001 "Source" {00000000-0000-0000-0000-000000000001} SOURCE "MyFile.mpg" 0000000000
<ID   名前   フィルタの GUID (ロードに必要)
         ソース ファイル名   プライベート データなし>
0002 "another filter" {00000000-0000-0000-0000-000000000002} 0000000008 XXXXXXXX
<ID   名前   GUID   (これはファイル ソースまたはシンクではない)   8 バイト プライベート データ>
CONNECTIONS
0001 "Output pin" 0002 "In"   <ここには改行なし>
<フィルタ ID ピン ID   フィルタ ID ピン ID  (出力ピンが先でその次に入力ピン)>
    0000000172 {00000000-0000-0000-0000-000000000003}   <ここには改行なし>
<サンプル サイズ、   メディア タイプ メジャー タイプ>
    {00000000-0000-0000-0000-000000000004} 1 0   <ここには改行なし>
<メディア タイプ サブタイプ、 固定サイズ サンプル、時系列圧縮なし>
    0000000093 {00000000-0000-0000-0000-000000000005} 18 YYYYYYYYYYYYYYYYYY
<フォーマットの長さ   フォーマット タイプ   18 バイトのバイナリ フォーマット データ>
END

ここで、

  • XXX... フィルタ データを表す。
  • YYY... フォーマット データを表す。

ファイル内の文字列および文字は常に Unicode™ で表される。


Filter Graph Markup Language (XGR)

DirectShow グラフ ビルダの XML インターフェイスは、DirectShow グラフの新しい永続性フォーマットを提供する。このフォーマットは、グラフの永続性を読み取り可能な形にしてデバッグを行うことだけを目的としていて、アプリケーションで使用することは目的としていない。

GraphEdit でグラフを XGR フォーマットで保存するには、[File] メニューの [Save As XML] を選択する。

目次

  • FGML の規則と規約
  • 名前付けの競合
  • XGR 用の XML タグ
    • GRAPH
    • FILTER
    • PARAM
    • CONNECT
    • RENDER
    • FILESOURCE
    • INCLUDE
    • VIDEOCOMPRESS
    • AUDIOCOMPRESS
    • SUBGRAPH
    • FRAGMENT
  • FGML スキーマ

FGML の規則と規約

FGML ファイルのデフォルトのファイル拡張子は .XGR である。このドキュメントでは、XGR と FGML が同義語として使われている。

FGML のファイル フォーマット、トークン化、および解析は XML 1.0 規格に準拠している。

さらに、DirectShow フィルタ グラフに固有の問題に対処するため、以下の規則が追加されている。

名前付けの競合

XGR ファイルのそれぞれのフィルタ定義およびピン定義では、一意な識別子を定義する必要がある。一意な識別子が定義されていない場合は、XGR リーダーが自動的に競合を解決する。XGR ファイルが読み込まれると、フィルタのインスタンスが生成され、ドキュメントの指定に従ってピンが命名される。競合が発生した場合は、同じ名前を使おうとした 2 番目のフィルタまたはピンに別の名前が付けられる。この名前は、要求された名前を基にして、一意性を持たせるためにサフィックスを追加した名前になる。XGR リーダーはこのような名前の変更が発生したことをクライアント コードに通知しないため、クライアントは、XGR ファイルがロードされた後、それらの名前が正しい名前を使ってオブジェクトを参照するように取り計らう必要がある。

名前付けの競合を回避するため、XGR 仕様にはスコープ演算子が追加されている。スコープ演算子は、<SUBGRAPH> タグを使って定義される。サブグラフ内で定義されたすべてのフィルタは、複合名 "subgraph_name.child_filter_name" を使って参照できる。DirectShow の現在のリリースは、ネイティブではサブグラフをサポートしていないが、将来のリリースではこれが変わる可能性がある。その場合は、ネイティブの DirectShow サブグラフに対しても同じ名前付け規約が適用され、'.’ 演算子が、子フィルタを包含するサブグラフ フィルタと子フィルタの名前を区切る手段になる。

XGR 用の XML タグ

GRAPH 要素

GRAPH 要素は、グラフ ビルダ ドキュメントのルート要素である。この要素のパラメータは定義されていない。XGR ファイル内では GRAPH タグをネストできない。

構文:

<GRAPH version=”{number} >
...
</GRAPH>

属性 | 必須かどうか | 説明
version | 必須ではない | このファイルが従う XGR ファイル仕様のバージョンを指定する。特に指定がない場合、この値は、現在唯一の有効なバージョンである "1" になる。

関連するタグ

親要素 | 子要素
なし | FILTER
 | CONNECT
 | SUBGRAPH

例

<GRAPH>

<FILTER id=”videocompress” clsid=”{…}” />

</GRAPH>

FILTER 要素

説明

FILTER 要素は、グラフ内のフィルタを定義するために使用する。グラフ ビルダは、この要素で定義されている情報を利用して、適切なフィルタを選択し、作成する。この要素は、フィルタに対して設定されるプロパティも定義する。FILTER 要素を有効にするには、'category' 属性または 'clsid' 属性のいずれかを指定する必要があるが、両方を指定することはできない。両方の属性が指定された場合は、'clsid' が使用され、'category' 属性および 'instance' 属性は無視される。

構文:

<FILTER
id=”filter_name”
clsid=”{GUID}”
category=”category_name”
instance=”instance name”
/>

属性 | 必須かどうか | 説明
id | 必須 | グラフ内のフィルタのインスタンスの名前を指定する。
clsid | 必須ではない | フィルタのクラス ID を指定する。グラフ ビルダは、これを利用してフィルタのインスタンスを作成する。clsid が指定されている場合、category 属性と instance 属性は使用できない。
category | 必須ではない | グラフ ビルダが使用するフィルタのカテゴリを指定する。グラフ ビルダはこれを使用して、フィルタを検索する。'instance' が指定されていない場合は、このカテゴリのデフォルトのフィルタのインスタンスが生成される。clsid が指定されていると、この属性は無視される。
instance | 必須ではない | カテゴリが指定されている場合は、'Instance' 属性を使って、そのカテゴリのどのフィルタのインスタンスを生成するかを指定する。clsid が指定されていると、この属性は無視される。

注意

親要素 | 子要素
GRAPH | PARAM

例

<FILTER id=”asfmux” clsid=”{….} />

<FILTER id=”capture” category=”{Video Capture Sources}” instance=”winnov” />

<FILTER id=”videocompress” clsid=”{?c}”>

<PARAM name=”bitrate” value=”24000” />

</FILTER>

PARAM 要素

説明

PARAM 要素は、フィルタのプロパティを設定する一般的な方法を定義する。この要素は、フィルタに渡される名前と値の組み合わせを定義する。名前と値の組み合わせは、PARAM 要素の属性として定義される。

構文:

<PARAM name=”fps” value=”15” />

属性 | 必須かどうか | 説明
name | 必須 | name プロパティを指定する。
Value | 必須 | プロパティの値を指定する。

注意

親要素 | 子要素
FILTER | なし

例

<FILTER id=”videocompress” clsid=”{?c}”>

<PARAM name=”bitrate” value=”24000” />

<PARAM name=”fps” value=”15” />

</FILTER>

CONNECT 要素

説明

CONNECT 要素は、2 つのフィルタ間の接続を定義するために使用する。使用するピンが指定されていない場合、CONNECT は、方向が正しく、接続されていないフィルタ上のピンを検索し、その中の 1 つを選択する。その場合、それ以降に XGR から生成されるグラフのインスタンスでも同じピンが選択される保証はないため、特定のピンが必要なときは、絶対パス名で指定する必要がある。

構文:

<CONNECT
src=”src_filter_name”
srcpin=”src_pin_name”
dest=”dest_filter_name”
destpin=”dest_pin_name”
CONNECT/>

属性 | 必須かどうか | 説明
src | 必須 | 接続のデータ ソースとして使用するフィルタの絶対パス名。
srcpin | 必須ではない | データ ソースの接続相手となる特定のピンの名前。
dest | 必須 | 接続のデータ シンクとして使用するフィルタの絶対パス名。
destpin | 必須ではない | データ シンクの接続相手となる特定のピンの名前。

注意

親要素 | 子要素
GRAPH | なし

例

<CONNECT src=”vidcap.video” srcpin=’pin1’ dest=’renderer’ destpin=’pin3’ />

RENDER 要素

説明

RENDER 要素は、グラフ ビルダに対して、指定されたフィルタとピンをレンダリングする必要があることを通知する。

構文:

<RENDER id=”filter_name” pin=”pin_name />

属性 | 必須かどうか | 説明
Id | 必須 | レンダリングに使用するフィルタの名前。
pin | 必須 | 使用するピンの名前。

注意

親要素 | 子要素
GRAPH | なし

例

<FILTER id=”waveout” clsid=”{….} />

<RENDER id=”waveout”>

FILESOURCE 要素

説明

FILESOURCE 要素は、再生するファイルの URL を指定する。この URL のメディア タイプに基づいて、指定された id のソース フィルタのインスタンスが生成される。

問題 – これは 1 つのフィルタを作成するのか、入力サブグラフを作成するのか。

構文:

<FILESOURCE id=”source_filter_name” url=”file url” />

属性 | 必須かどうか | 説明
id | 必須 | インスタンスが生成されたソース フィルタで使用される名前。
url | 必須 | ソース フィルタが開くメディア ファイルを識別する URL。

注意

親要素 | 子要素
GRAPH | なし

例

<FILESOURCE id="ASF1" url="http://example.microsoft.com/"/>

INCLUDE 要素

説明

INCLUDE 要素は、別の XGR ファイルまたは FRAGMENT を現在の XGR ストリームに含めるために使用する。これにより、共通のソースのコードを使って、小さいコードから複雑なグラフを作成できる。GRAPH 要素のネストを禁じている規則に違反するため、INCLUDE されたファイルに GRAPH 要素を含めることはできない。"url" 属性が設定されている場合、"fragment" 属性はすべて無視される。これらの属性は両立しない。指定された url または fragment が存在しない場合、INCLUDE 要素は無視される。

構文:

< INCLUDE
url=”url_for_file”
fragment=”fragment_name”
subgraph=”subgraph_name”
/>

属性 | 必須かどうか | 説明
url | 必須ではない | グラフに含める XGR ファイルを指す URL。fragment 属性が設定されていない場合は、これを指定する必要がある。
fragment | 必須ではない | 含める XGR FRAGMENT 要素の名前。url 属性が設定されていない場合は、これを指定する必要がある。url が設定されている場合、これは無視される。
subgraph | 必須ではない | サブグラフが指定されている場合は、ファイル フラグメントがグラフ内に別のサブグラフを作成するものと見なされる。これは、SUBGRAPH 要素の中に INCLUDE 要素をラップすることに等しい。subgraph 属性が使用されていない場合、ファイルはデフォルトの名前空間にロードされる。

注意

親要素 | 子要素
GRAPH | なし

例

<INCLUDE url="http://example.microsoft.com/" subgraph="capture"/>

VIDEOCOMPRESS 要素

説明

VIDEOCOMPRESS 要素は、あるフォーマットの入力ビデオ ストリームを受け取り、それを、必要とされる出力フォーマットに変換するフィルタの標準的なセットのインスタンスを生成するために使用する。これは、このタスクを実行するために必要なフィルタの完全なセットのインスタンスを生成するのに代わる方法である。使用するピンが指定されていない場合は、フィルタ上の利用可能な最初のピンが使用される。それ以降に、XGR から生成されるグラフのインスタンスでも同じピンがデフォルトで使用される保証はないため、特定のピンが必要な場合は、絶対パス名で指定する必要がある。

構文:

< VIDEOCOMPRESS
src=”src_filter_name”
srcpin=”src_filter_pin_name”
dest=”dest_filter”
destpin=”dest_filter_pin_name”
width="{number}"
size="{number}"
codec=”codec_name”
datarate=”{number}”
keyframespacing=”{number}”
frametime=”{number}”
subgraph=”subgraph_name”
/>

属性 | 必須かどうか | 説明
src | 必須 | 接続のデータ ソースとして使用するフィルタの絶対パス名。
srcpin | 必須ではない | データ ソースの接続相手となる特定のピンの名前。
dest | 必須 | 接続のデータ シンクとして使用するフィルタの絶対パス名。
destpin | 必須ではない | データ シンクの接続相手となる特定のピンの名前。
width | 必須 | ピクセル単位で表す出力ストリームの幅。
height | 必須 | ピクセル単位で表す出力ストリームの高さ。
CODEC | 必須 | ビデオ変換を行うときに使用する CODEC。
datarate | 必須 | kb/秒単位で表す出力ストリームのデータ速度。
keyframespacing | 必須 | keyframespacing を定義する。
frametime | 必須 | frametime を定義する。
subgraph | 必須ではない | subgraph が指定されている場合、ビデオ圧縮フィルタは、グラフ内の別のサブグラフ内にあるものと見なされる。これは、VIDEOCOMPRESS 要素を SUBGRAPH 要素の中にラップすることに等しい。subgraph 属性が使用されていない場合、ファイルはデフォルトの名前空間にロードされる。

注意

親要素 | 子要素
GRAPH | なし

例

AUDIOCOMPRESS 要素

説明

AUDIOCOMPRESS 要素は、あるフォーマットの入力オーディオ ストリームを受け取り、それを、必要とされる出力フォーマットに変換するフィルタの標準的なセットのインスタンスを生成するために使用する。これは、このタスクを実行するために必要なフィルタの完全なセットのインスタンスを生成するのに代わる方法である。使用するピンが指定されていない場合は、フィルタ上の利用可能な最初のピンが使用される。それ以降に XGR から生成されるグラフのインスタンスでも同じピンがデフォルトで使用される保証はないため、特定のピンが必要な場合は、絶対パス名で指定する必要がある。

構文:

< AUDIOCOMPRESS
src=”src_filter_name”
srcpin=”src_filter_pin_name”
dest=”dest_filter”
destpin=”dest_filter_pin_name”
samplerate="{number}"
sampledepth=”{number}”
channels=”{number}”
subgraph=”subgraph_name”
/>

属性 | 必須かどうか | 説明
src | 必須 | 接続のデータ ソースとして使用するフィルタの絶対パス名。
srcpin | 必須ではない | データ ソースの接続相手となる特定のピンの名前。
dest | 必須 | 接続のデータ シンクとして使用するフィルタの絶対パス名。
destpin | 必須ではない | データ シンクの接続相手となる特定のピンの名前。
samplerate | 必須 | k/秒で表す出力ストリームのサンプル速度。
sampledepth | 必須 | ビット単位で表す各オーディオ サンプルのサンプル サイズ。
channels | 必須ではない | 出力ストリーム内の別のオーディオ チャンネルの数。指定されていない場合のデフォルトは、"1" になる。
subgraph | 必須ではない | subgraph が指定されている場合、ビデオ圧縮フィルタは、グラフ内の別のサブグラフ内にあるものと見なされる。これは、VIDEOCOMPRESS 要素を SUBGRAPH 要素の中にラップすることに等しい。subgraph 属性が使用されていない場合、ファイルはデフォルトの名前空間にロードされる。

注意

親要素 | 子要素
GRAPH | なし

例

SUBGRAPH 要素

説明

SUBGRAPH 要素は、フィルタ グラフ内で名前空間と分割動作を作成するために使用する。SUBGRAPH 要素内で定義されたすべてのフィルタは、フィルタ タグ内でサブグラフ名をプリフィックスとして追加した名前を使って参照できる。たとえば、サブグラフ "SG1" 内の "Filter" という名前のフィルタは、"SG1.Filter" という名前によって参照される。

構文:

< SUBGRAPH name=”subgraph_name”> ... </SUBGRAPH>

属性 | 必須かどうか | 説明
subgraph_name | 必須 | このサブグラフで使用される名前。

注意

親要素 | 子要素
GRAPH | なし

FRAGMENT 要素

説明

FRAGMENT 要素は、グラフ内のさまざまな場所に含めることができる XGR コードの再利用可能なセクションを作成する。FRAGMENT 要素があると、タグ内のそれ以降のすべての要素はフィルタ グラフに追加されない。この FRAGMENT を参照する INCLUDE タグがあると、フラグメントの要素は、INCLUDE 要素の位置にある XGR ファイル内にあるかのように、XGR ストリームに挿入される。XGR ファイル内には何回でも FRAGMENT を INCLUDE することができる。FRAGMENT には、GRAPH 以外であれば、どのような要素でも含めることができる。

構文:

< FRAGMENT name=”fragment_name”>
...
</FRAGMENT>

属性 | 必須かどうか | 説明
fragment _name | 必須 | このフラグメントで使用される名前

注意

親要素 | 子要素
GRAPH | なし

例

FGML スキーマ

<?xml version="1.0"?>

<Schema xmlns="urn:schemas-microsoft-com:xml-data"

xmlns:dt="urn:schemas-microsoft-com:datatypes">

<!-- Define standard attribute types -->

<AttributeType name="category" dt:type="string" />

<AttributeType name="clsid" dt:type="string" />

<AttributeType name="dest" dt:type="string" />

<AttributeType name="destpin" dt:type="string" />

<AttributeType name="id" dt:type="string" />

<AttributeType name="instance" dt:type="string" />

<AttributeType name="name" dt:type="string" />

<AttributeType name="pin" dt:type="string" />

<AttributeType name="src" dt:type="string" />

<AttributeType name="srcpin" dt:type="string" />

<AttributeType name="url" dt:type="string" />

<AttributeType name="value" dt:type="string" />

<!-- GRAPH element definition -->

<ElementType name="GRAPH" content="eltOnly" model="closed" order="many">

<!-- decide if a version attribute is required -->

<element type="FILTER" />

<element type="CONNECT" />

<element type="SUBGRAPH" />

<element type="PARAM" />

<element type="FILESOURCE" />

</ElementType>

<!-- FILTER element definition -->

<ElementType name="FILTER" content="eltOnly" model="closed" order="many">

<attribute type="id" required="yes" />

<attribute type="clsid" required="no" />

<attribute type="category" required="no" />

<attribute type="instance" required="no" />

<element type="PARAM" />

</ElementType>

<!-- PARAM element definition -->

<ElementType name="PARAM" content="empty" model="closed" order="many">

<attribute type="name" required="yes" />

<attribute type="value" required="yes" />

</ElementType>

<!-- CONNECT element definition -->

<ElementType name="CONNECT" content="empty" model="closed">

<attribute type="src" required="yes" />

<attribute type="srcpin" required="no" />

<attribute type="dest" required="yes" />

<attribute type="destpin" required="no" />

</ElementType>

<!-- RENDER element definition -->

<ElementType name="RENDER" content="empty" model="closed">

<attribute type="id" required="yes" />

<attribute type="pin" required="yes" />

</ElementType>

<!-- FILESOURCE element definition -->

<ElementType name="FILESOURCE" content="empty" model="closed">

<attribute type="id" required="yes" />

<attribute type="url" required="yes" />

</ElementType>

<!-- VIDEOCOMPRESS element definition -->

<!-- AUDIOCOMPRESS element definition -->

<!-- INCLUDE element definition -->

<!-- FRAGMENT element definition -->

<!-- SUBGRAPH element definition -->

</Schema>


国際アナログ テレビのチューニング

  • 1 はじめに
  • 2 チャンネル番号の代わりに使われる周波数インデックス
  • 3 周波数のオーバーライド
  • 3.1 レジストリを使った周波数のオーバーライド
  • 3.2 レジストリの変換
  • 4 TV チューナー フィルタの使用
  • 4.1 微調整情報の収集
  • 4.2 周波数テーブルとチューニング空間の関連付け
  • 5 テーブルと割り当て
  • 5.1 周波数テーブル
  • 5.1.1 オーストラリア
  • 5.1.2 中国
  • 5.1.3 チェコ共和国
  • 5.1.4 東ヨーロッパ
  • 5.1.5 フランス
  • 5.1.6 海外フランス領国
  • 5.1.7 アイルランド
  • 5.1.8 イタリア
  • 5.1.9 日本
  • 5.1.10 ニュージーランド
  • 5.1.11 NTSC (アメリカ合衆国)
  • 5.1.12 英国
  • 5.1.13 西ヨーロッパ
  • 5.1.14 Unicable
  • 5.2 国割り当て

1 はじめに

Windows 98 オペレーティング システムおよび Microsoft® Windows® 98 SE オペレーティング システムに付属の TV チューナー サポートは、米国市場のテレビ選局だけに適合していた。国際的な選局に関する大まかな枠組みは制定されていたが、いくつかの問題があったため、その枠組みは米国国外では使用できなかった。

チャンネル番号

TV チューナー フィルタ (kstvtune.ax) には、チャンネル番号から周波数へのマッピング用の内部テーブルが含まれている。すべての市場で固定チャンネル番号が通用するわけではない。たとえば、ヨーロッパの消費者は、実際にはチャンネル番号を使用していない。ヨーロッパの消費者は、自分でチャンネル番号を選択し、放送局やケーブルテレビ業者が各地域で使用している周波数に割り当てているだけである。

この問題に対処するために、チャンネル番号から周波数インデックスへ方式が変更された。周波数の選択には相変わらず順位番号が使われているが、この場合の順位番号は、チャンネル番号というよりは周波数テーブルのインデックスとして扱われている。特に米国市場や米国と同じチャンネル構成が使われている市場など、チャンネル番号が通用する地域では、今でもインデックスがチャンネル番号に直接対応している。

固定周波数割り当て

周波数テーブルが TV チューナー フィルタに組み込まれていたため、周波数が間違っていた場合や廃止された場合でも、周波数を更新することは不可能だった。新しい周波数を追加することもできなかった。テーブルの間違いを修正するには新しいバイナリ ファイルの出荷が必要だったが、こうした不都合は放送局用の周波数ではあまり問題にならなかった。しかし、ケーブルテレビの周波数では、これが非常に大きな問題になる。米国外のケーブルテレビ業者は、自ら選択した周波数で自由に放送できるため、多くの場合、同じチャンネル構成に別々の規格の周波数が混在することになった。この問題には、2 つの対処方法が使われた。1 つは、ケーブルチャンネル規格制定機関がないすべての国に対して "Unicable" 周波数テーブルを供給する方法であり、もう 1 つは、1 つ以上の周波数をオーバーライドするための Windows レジストリ ベースのメカニズムを提供する方法である。

間違ったデータ

TV チューナー フィルタによってカプセル化されているデータには、周波数テーブル、カラーテレビ方式、および国別の周波数とカラーテレビ方式の割り当てが含まれている。従来は、これらのテーブルの間違いを修正するには、新しい TV チューナー フィルタを出荷するしかなかった。この問題に対処するため、上記の方法の組み合わせが使用されると同時に、徹底的な調査の結果、内部のテーブルおよび割り当てが更新された。すべての国の放送周波数およびカラーテレビ方式の割り当てが正しいことを確認するために、多大な努力が払われた。

このドキュメントでは、新しい機能について説明し、周波数テーブルと国別の割り当てを示す。新しい機能は Microsoft Windows ME に導入される。

2 チャンネル番号の代わりに使われる周波数インデックス

新しい国際選局サポートの最も重要な点は、実装が非常に簡単なことだった。実際、コードの変更はまったく必要なかった。考え方を "チャンネル番号" から "周波数インデックス" に変えるだけで済む。これは、テレビ受信アプリケーションが、周波数インデックス番号をエンドユーザーに見せてはいけないことを意味している。その代わりに、ユーザーに見えるチャンネル番号からアプリケーションが特定の周波数を選局するときに使用する周波数インデックスへの内部マッピングを設ける必要がある。米国を始めとする一部の国では、アプリケーションがチャンネル番号から周波数インデックスへの一対一のマッピングを行うことができる。しかし、国際選局に対応したアプリケーションでは、エンドユーザー (またはエンドユーザーを代表する代理人) が各周波数 (インデックス) に使用するチャンネル番号を選択できるようにする。

周波数テーブルは調査の産物であるというだけの理由により、TV チューナー フィルタでは、従来どおり、周波数テーブルを使用する。この責任をテレビ受信アプリケーションに押しつけることには意味がない。

3 周波数のオーバーライド

3.1 レジストリを使った周波数のオーバーライド

細心の注意を払っても、周波数テーブルが十分でなかったり、周波数テーブルに間違いがあったり、周波数テーブルが古くなることがある。この問題に対処するため、TV チューナー フィルタの周波数テーブルに含まれている周波数は、レジストリを利用して選択式でオーバーライドできるようになっている。

図 1:

[HKEY_LOCAL_MACHINE\Software\Microsoft\TV System Services\TVAutoTune\TS0-1]
"12"=dword:04022750
"AutoTune"=hex:00,00,00,00,50,0c,4b,03,d0,99,a6,03,50,27,02,04,d0,bd,9a,04,50,\
4b,f6,04,50,1a,72,0a,00,00,00,00,50,35,29,0b,d0,c2,84,0b,50,50,e0,0b,d0,dd,\
3b,0c,50,6b,97,0c,d0,20,3a,07,50,ae,95,07,d0,3b,f1,07,50,c9,4c,08,d0,56,a8,\
08,50,e4,03,09,d0,71,5f,09,50,ff,ba,09,d0,8c,16,0a,d0,f8,f2,0c,50,86,4e,0d,\
d0,13,aa,0d,50,a1,05,0e,d0,2e,61,0e,50,bc,bc,0e,d0,49,18,0f,50,d7,73,0f,d0,\
64,cf,0f,50,f2,2a,10,d0,7f,86,10,50,0d,e2,10,d0,9a,3d,11,50,28,99,11,d0,b5,\
f4,11,50,43,50,12,d0,d0,ab,12,50,5e,07,13,d0,eb,62,13,74,6d,bf,13,00,00,00,\
00,00,00,00,00,d0,21,d1,14,50,af,2c,15,d0,3c,88,15,00,00,00,00,00,00,00,00,\
00,00,00,00,00,00,00,00,00,00,00,00,d0,8d,ad,17,50,1b,09,18,d0,a8,64,18,50,\
36,c0,18,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,\
00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,\
00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,\
00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,f4,e0,fa,20,50,7a,55,21,00,\
00,00,00,00,00,00,00,d0,22,68,22,00,00,00,00,00,00,00,00,50,cb,7a,23,00,00,\
00,00,50,e6,31,24,d0,73,8d,24,00,00,00,00,d0,8e,44,25,50,1c,a0,25,d0,a9,fb,\
25,50,37,57,26,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,74,87,df,06,\
d0,c4,b2,26,50,52,0e,27,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,\
00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,\
00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,\
00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,\
00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,\
00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,\
00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,\
00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,\
00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,\
00,00,00,00,00,00,00,00,00,00,00

図 1 および上記のテキスト バージョンは、微調整情報および周波数オーバーライド情報が格納されているレジストリ パスを示している。この図の "TS0-1" は、ケーブルテレビ周波数のチューニング空間 0 を表している。チューニング空間 0 には放送周波数用の TS0-0 もある。これらのレジストリの構造は、新しい周波数オーバーライド メカニズムをサポートするため、前のバージョンから変更されている。以前の TS*-* キーは、微調整が行われる時点で有効な周波数テーブルの微調整情報から構成されるバイナリ値だった。新しいフォーマットでは、微調整情報が "AutoTune" サブキーに移動している。その他のサブキーは、すべて周波数オーバーライド情報の候補である。周波数オーバーライド値に適した値にするには、キー名を、現在有効な周波数テーブルの最小インデックス値と最大インデックス値の間の有効な数値にする必要がある。さらに、サブキーの値は、DWORD タイプである必要があり、Hz 単位で周波数を指定する必要がある。周波数オーバーライド値として適格でないエントリは単に無視される。図 1 の例では、インデックス 12 の周波数を 67.25MHz でオーバーライドしている。

周波数インデックスの数よりオーバーライド値の数を多くすることにあまり意味はないが、特定のチューニング空間に周波数オーバーライド値をいくつでも割り当てることができる。同じキー名を持つ複数のインデックスの中のどれがオーバーライド値として選択されるかを保証することはできない。

アプリケーションは、IAMTVTuner::put_TuningSpace メソッドを利用して、使用するオーバーライド情報と微調整情報のセットを選択できる。チューニング空間と周波数テーブルの間の関係を維持する役割はアプリケーションが担う。

3.2 レジストリの変換

レジストリに周波数オーバーライド値情報を追加するアプリケーションは、チューニング空間用のレジストリの場所が新しいフォーマットに従っていることを確認する必要がある。TV チューナー フィルタを使って変換を行うことができる。IAMTVTuner::StoreAutoTune メソッドが呼び出されるたびに、古いレジストリ フォーマットは新しいフォーマットに変換される。StoreAutoTune メソッドを呼び出す前に微調整情報を収集する必要はない。微調整を実行するために、あるいは単に変換を行うために、セットアップの一部として TV チューナー フィルタのインスタンスを生成することに問題はない。

4 TV チューナー フィルタの使用

以下のセクションでは、推奨されている TV チューナー フィルタ (kstvtune.ax) の使い方について説明する。

4.1 微調整情報の収集

微調整情報の収集は、放送周波数に対してのみ推奨されている。ケーブルテレビの周波数は一般的に正確であるのに対して、放送周波数の場合は、隣接チャンネルとの干渉の可能性を軽減させるため、放送局が数キロヘルツ単位で上げたり下げたりすることがある。アプリケーションは、従来どおり、IAMTVTuner::AutoTune メソッドを使用して、放送周波数に合わせて微調整を行うことができる。このメソッドを利用すると、アプリケーションは、1 回の操作で、インデックスを利用して現在有効なテーブルから周波数を選択し、選局操作を実行し、選局操作の結果 (水平ロックが達成されたかどうか) を報告することができる。このメソッドは、周波数オーバーライド情報を無視するため、TV チューナー フィルタの周波数テーブルの周波数が間違っていることが判明した場合でも、AutoTune は、その周波数インデックスに適した結果を生成しない。

アプリケーションは、IAMTVTuner::ChannelMinMax によって報告された範囲内の各周波数インデックスにつき 1 回 AutoTune を呼び出す。アプリケーションが終了した後は、IAMTVTuner::StoreAutoTune を呼び出して、微調整情報をレジストリに保存する必要がある。AutoTune メソッドは周波数オーバーライド情報を正しく処理できないため、StoreAutoTune の後で IAMTVTuner::put_TuningSpace を呼び出して、もう一度オーバーライド情報を取得する必要がある。

これに代わる方法は、IAMTVTuner::put_Channel メソッドと IAMTuner::SignalPresent メソッドを使って AutoTune メソッドの動作を模倣する方法である。put_Channel メソッドと AutoTune メソッドは同じ実装を共有するため、IAMTVTuner::StoreAutoTune でも put_Channel に対する呼び出しの結果を利用し、それをレジストリに保存することができる。以下の動作は、IAMTVTuner::AutoTune と同じである。

HRESULT
MyAutoTune(IAMTVTuner *pTuner, long lIndex, long *plFoundSignal)
{
long SignalStrength = AMTUNER_NOSIGNAL;
HRESULT hr;

hr = pTuner->put_Channel(lIndex, AMTUNER_SUBCHAN_DEFAULT, AMTUNER_SUBCHAN_DEFAULT);
if (NOERROR == hr)
pTuner->SignalPresent(&SignalStrength);

// Assume AMTUNER_HASNOSIGNALSTRENGTH means tuned
*plFoundSignal = (SignalStrength != AMTUNER_NOSIGNAL);

return hr;
}

放送受信の信頼性の低さを補償するため、put_Channel メソッドと AutoTune メソッドから得られる戻り値が少し拡張されている。放送の受信では、映像が見えていても、水平ロックを取得できないことがある。その場合、チューナーのハードウェアは周波数ロックを取得しているが、デコーダは水平ロックを取得していない。この状態は、put_Channel または AutoTune を使用するときに、戻り値を調べることによって検出できる。

S_OK (or NOERROR)

選局操作が成功し、チューナーが周波数ロックを取得した (AutoTune の FoundSignal パラメータが、水平ロックが達成されたかどうかを示すデコーダの状態によって更新された)。放送周波数に対して AutoTune を実行する場合、アプリケーションは、チューナーが周波数ロックを報告していれば、FoundSignal パラメータを無視するように設定することもできる。ノイズに対して周波数がロックしている可能性があるが、その可能性を受信可能チャンネルがスキップされる可能性と比較検討する必要がある。

S_FALSE

選局操作中にエラーは発生しなかったが、チューナーは周波数ロックを取得できなかった。この操作によって受信可能チャンネルが取得できる可能性はきわめて低い。

E_*

ほかのすべての戻り値は、何らかのエラーが発生したことを示す。

4.2 周波数テーブルとチューニング空間の関連付け

アプリケーションは、IAMTVTuner::put_CountryCode メソッドを使って該当する国コードを選択することによって、周波数テーブルとカラーテレビ方式を選択する。国コードおよびそれに対応する周波数テーブルとカラーテレビ方式の割り当ては、後のセクション 5 に記載されている。

周波数オーバーライドの使用を正しくサポートするには、アプリケーションが、一意なチューニング空間番号を、選択される可能性のあるそれぞれの国コードに関連付ける方法が推奨される。適切な方法は、国コード値をチューニング空間値として使用する方法である。そうすると、アプリケーションが新しい国コードに切り替わるたびに、その国コードに対応するチューニング空間への切り替えも行われる (国コード、チューニング空間の順に切り替わる)。これにより、新しく有効になった周波数テーブルが周波数オーバーライド情報と微調整情報に正しく反映されることが保証される。

5 テーブルと割り当て

5.1 周波数テーブル

全世界には一定数の既知の放送周波数規格のセットが存在する。これらの規格は、各国が制定しているものだが、多くの場合、複数の国が同じ規格を採用している。TV チューナー フィルタ (kstvtune.ax) では、それぞれの規格のテーブルを定義している。

残念ながら、ケーブルテレビ周波数規格の場合は事情が異なる。一部の国のケーブルテレビ業者は、自社が選択した周波数で自由に番組を放送できる。この場合は、複数の規格の周波数が混在していることが多い。ほとんどの場合、この慣例はそれぞれの周波数規格が制定された国と直接関連している。TV チューナー フィルタでは、信頼性のあるケーブルテレビ周波数割り当てが含まれたいくつかのケーブルテレビ規格 (および国) のテーブルを定義している。その他すべての場合は、Unicable 周波数テーブルを使用する必要がある。

以下に示す周波数テーブルは、TV チューナー フィルタでテーブルを構築するときに使用されるリソース ファイル定義から抽出されたものである。各テーブルは、それぞれのリソース ID から始まる。これらのリソース ID を使って、以下のセクション 5.2 に記載された国コード割り当てから相互参照を行い、それぞれの国またはロケールで使用されているテーブルを判別することができる。

5.1.1 オーストラリア

オーストラリアのテーブルに含まれている周波数インデックスは、チャンネル番号の用途に適していない。チャンネル 3、4、5、および 5A は段階的に廃止され、ほかの用途に振り向けられる点にも注意する必要がある。

5.1.1.1 オーストラリアの放送割り当て

F_OZ__BROAD RCDATA
BEGIN
1L,             // 最小インデックス
53L,            // 最大インデックス

46250000L,      // 0    (1) VHF 帯 1
57250000L,      // 1    (2)
64250000L,      // 2    (3) VHF 帯 2
86250000L,      // 3    (4)
95250000L,      // 4    (5)
102250000L,     // 5    (6)
138250000L,     // 5a   (7) VHF 帯 3
175250000L,     // 6    (8)
182250000L,     // 7    (9)
189250000L,     // 8    (10)
196250000L,     // 9    (11)
209250000L,     // 10   (12)
216250000L,     // 11   (13)
223250000L,     // 12   (14)
527250000L,     // 28   (15) UHF 帯 4
534250000L,     // 29   (16)
541250000L,     // 30   (17)
548250000L,     // 31   (18)
555250000L,     // 32   (19)
562250000L,     // 33   (20)
569250000L,     // 34   (21)
576250000L,     // 35   (22)
604250000L,     // 39   (23) UHF 帯 5
611250000L,     // 40   (24)
618250000L,     // 41   (25)
625250000L,     // 42   (26)
632250000L,     // 43   (27)
639250000L,     // 44   (28)
646250000L,     // 45   (29)
653250000L,     // 46   (30)
660250000L,     // 47   (31)
667250000L,     // 48   (32)
674250000L,     // 49   (33)
681250000L,     // 50   (34)
688250000L,     // 51   (35)
695250000L,     // 52   (36)
702250000L,     // 53   (37)
709250000L,     // 54   (38)
716250000L,     // 55   (39)
723250000L,     // 56   (40)
730250000L,     // 57   (41)
737250000L,     // 58   (42)
744250000L,     // 59   (43)
751250000L,     // 60   (44)
758250000L,     // 61   (45)
765250000L,     // 62   (46)
772250000L,     // 63   (47)
779250000L,     // 64   (48)
786250000L,     // 65   (49)
793250000L,     // 66   (50)
800250000L,     // 67   (51)
807250000L,     // 68   (52)
814250000L,     // 69   (53)
END

5.1.1.2 オーストラリアのケーブルテレビ割り当て

標準化されたケーブルテレビ構成に対応するデータがないため、Unicable 周波数テーブルが使用される。

5.1.2 中国

中国のテーブルに含まれている周波数インデックスは、チャンネル番号の用途に適している。

5.1.2.1 中国の放送割り当て

F_CHN_BROAD RCDATA
BEGIN
1L,             // 最小チャンネル
36L,            // 最大チャンネル

49750000L,      // 1
57750000L,      // 2
65750000L,      // 3
77250000L,      // 4
85250000L,      // 5
168250000L,     // 6
176250000L,     // 7
184250000L,     // 8
192250000L,     // 9
200250000L,     // 10
208250000L,     // 11
216250000L,     // 12
471250000L,     // 13
479250000L,     // 14
487250000L,     // 15
495250000L,     // 16
503250000L,     // 17
511250000L,     // 18
519250000L,     // 19
527250000L,     // 20
535250000L,     // 21
543250000L,     // 22
551250000L,     // 23
559250000L,     // 24
605250000L,     // 25
613250000L,     // 26
621250000L,     // 27
629250000L,     // 28
637250000L,     // 29
645250000L,     // 30
653250000L,     // 31
661250000L,     // 32
669250000L,     // 33
677250000L,     // 34
685250000L,     // 35
693250000L,     // 36
END

5.1.2.2 中国のケーブルテレビ割り当て

F_CHN_CABLE RCDATA
BEGIN
1L,             // 最小チャンネル
52L,            // 最大チャンネル

49750000L,      // 1
57750000L,      // 2
65750000L,      // 3
77250000L,      // 4
85250000L,      // 5
112250000L,     // 6
120250000L,     // 7
128250000L,     // 8
136250000L,     // 9
144250000L,     // 10
152250000L,     // 11
160250000L,     // 12
168250000L,     // 13
176250000L,     // 14
184250000L,     // 15
192250000L,     // 16
200250000L,     // 17
208250000L,     // 18
216250000L,     // 19
224250000L,     // 20
232250000L,     // 21
240250000L,     // 22
248250000L,     // 23
256250000L,     // 24
264250000L,     // 25
272250000L,     // 26
280250000L,     // 27
288250000L,     // 28
471250000L,     // 29
479250000L,     // 30
487250000L,     // 31
495250000L,     // 32
503250000L,     // 33
511250000L,     // 34
519250000L,     // 35
527250000L,     // 36
535250000L,     // 37
543250000L,     // 38
551250000L,     // 39
559250000L,     // 40
567250000L,     // 41
575250000L,     // 42
583250000L,     // 43
591250000L,     // 44
599250000L,     // 45
607250000L,     // 46
615250000L,     // 47
623250000L,     // 48
631250000L,     // 49
639250000L,     // 50
647250000L,     // 51
655250000L,     // 52
END

5.1.3 チェコ共和国

チェコ共和国のテーブルに含まれている周波数インデックスは、チャンネル番号の用途に適していない。

5.1.3.1 チェコ共和国の放送割り当て

F_CZE_BROAD RCDATA
BEGIN
1L,             // 最小インデックス
69L,            // 最大インデックス

49750000L,      // 1
57750000L,      // 2
59250000L,      // 3
65750000L,      // 4
77250000L,      // 5
85250000L,      // 6
93250000L,      // 7
175250000L,     // 8
183250000L,     // 9
191250000L,     // 10
199250000L,     // 11
207250000L,     // 12
215250000L,     // 13
223250000L,     // 14

0L,             // 15 未使用
0L,             // 16 未使用
0L,             // 17 未使用
0L,             // 18 未使用
0L,             // 19 未使用
0L,             // 20 未使用

471250000L,     // 21
479250000L,     // 22
487250000L,     // 23
495250000L,     // 24
503250000L,     // 25
511250000L,     // 26
519250000L,     // 27
527250000L,     // 28
535250000L,     // 29
543250000L,     // 30
551250000L,     // 31
559250000L,     // 32
567250000L,     // 33
575250000L,     // 34
583250000L,     // 35
591250000L,     // 36
599250000L,     // 37
607250000L,     // 38
615250000L,     // 39
623250000L,     // 40
631250000L,     // 41
639250000L,     // 42
647250000L,     // 43
655250000L,     // 44
663250000L,     // 45
671250000L,     // 46
679250000L,     // 47
687250000L,     // 48
695250000L,     // 49
703250000L,     // 50
711250000L,     // 51
719250000L,     // 52
727250000L,     // 53
735250000L,     // 54
743250000L,     // 55
751250000L,     // 56
759250000L,     // 57
767250000L,     // 58
775250000L,     // 59
783250000L,     // 60
791250000L,     // 61
799250000L,     // 62
807250000L,     // 63
815250000L,     // 64
823250000L,     // 65
831250000L,     // 66
839250000L,     // 67
847250000L,     // 68
855250000L,     // 69

END

5.1.3.2 チェコ共和国のケーブルテレビ割り当て

標準化されたケーブルテレビ構成に対応するデータがないため、Unicable 周波数テーブルが使用される。

5.1.4 東ヨーロッパ

東ヨーロッパのテーブルに含まれている周波数インデックスは、チャンネル番号の用途に適していない。

5.1.4.1 東ヨーロッパの放送割り当て

F_EEU_BROAD RCDATA
BEGIN
1L,             // 最小インデックス
69L,            // 最大インデックス

49750000L,      // 1
59250000L,      // 2
77250000L,      // 3
85250000L,      // 4
93250000L,      // 5
175250000L,     // 6
183250000L,     // 7
191250000L,     // 8
199250000L,     // 9
207250000L,     // 10
215250000L,     // 11
223250000L,     // 12

0L,             // 13 未使用
0L,             // 14 未使用
0L,             // 15 未使用
0L,             // 16 未使用
0L,             // 17 未使用
0L,             // 18 未使用
0L,             // 19 未使用
0L,             // 20 未使用

471250000L,     // 21
479250000L,     // 22
487250000L,     // 23
495250000L,     // 24
503250000L,     // 25
511250000L,     // 26
519250000L,     // 27
527250000L,     // 28
535250000L,     // 29
543250000L,     // 30
551250000L,     // 31
559250000L,     // 32
567250000L,     // 33
575250000L,     // 34
583250000L,     // 35
591250000L,     // 36
599250000L,     // 37
607250000L,     // 38
615250000L,     // 39
623250000L,     // 40
631250000L,     // 41
639250000L,     // 42
647250000L,     // 43
655250000L,     // 44
663250000L,     // 45
671250000L,     // 46
679250000L,     // 47
687250000L,     // 48
695250000L,     // 49
703250000L,     // 50
711250000L,     // 51
719250000L,     // 52
727250000L,     // 53
735250000L,     // 54
743250000L,     // 55
751250000L,     // 56
759250000L,     // 57
767250000L,     // 58
775250000L,     // 59
783250000L,     // 60
791250000L,     // 61
799250000L,     // 62
807250000L,     // 63
815250000L,     // 64
823250000L,     // 65
831250000L,     // 66
839250000L,     // 67
847250000L,     // 68
855250000L,     // 69

END

5.1.4.2 東ヨーロッパのケーブルテレビ割り当て

標準化されたケーブルテレビ構成に対応するデータがないため、Unicable 周波数テーブル (下を参照) が使用される。

5.1.5 フランス

フランスのテーブルに含まれている周波数インデックスは、チャンネル番号の用途に適していない。

5.1.5.1 フランスの放送割り当て

F_FRA_BROAD RCDATA
BEGIN
2L,              // 最小インデックス
69L,             // 最大インデックス

55750000L,       // 2
60500000L,       // 3
63750000L,       // 4
176000000L,      // 5
184000000L,      // 6
192000000L,      // 7
200000000L,      // 8
208000000L,      // 9
216000000L,      // 10
0L,              // 11 未使用
0L,              // 12 未使用
0L,              // 13 未使用
0L,              // 14 未使用
0L,              // 15 未使用
0L,              // 16 未使用
0L,              // 17 未使用
0L,              // 18 未使用
0L,              // 19 未使用
0L,              // 20 未使用
471250000L,      // 21
479250000L,      // 22
487250000L,      // 23
495250000L,      // 24
503250000L,      // 25
511250000L,      // 26
519250000L,      // 27
527250000L,      // 28
535250000L,      // 29
543250000L,      // 30
551250000L,      // 31
559250000L,      // 32
567250000L,      // 33
575250000L,      // 34
583250000L,      // 35
591250000L,      // 36
599250000L,      // 37
607250000L,      // 38
615250000L,      // 39
623250000L,      // 40
631250000L,      // 41
639250000L,      // 42
647250000L,      // 43
655250000L,      // 44
663250000L,      // 45
671250000L,      // 46
679250000L,      // 47
687250000L,      // 48
695250000L,      // 49
703250000L,      // 50
711250000L,      // 51
719250000L,      // 52
727250000L,      // 53
735250000L,      // 54
743250000L,      // 55
751250000L,      // 56
759250000L,      // 57
767250000L,      // 58
775250000L,      // 59
783250000L,      // 60
791250000L,      // 61
799250000L,      // 62
807250000L,      // 63
815250000L,      // 64
823250000L,      // 65
831250000L,      // 66
839250000L,      // 67
847250000L,      // 68
855250000L,      // 69

END

5.1.5.2 フランスのケーブルテレビ割り当て

標準化されたケーブルテレビ構成に対応するデータがないため、Unicable 周波数テーブル (下を参照) が使用される。

5.1.6 海外フランス領国

海外フランス領国の放送テーブルに含まれている周波数インデックスは、チャンネル番号の用途に適していない。また、ケーブルテレビ周波数インデックスは、チャンネル番号の用途に適していない。

5.1.6.1 海外フランス領国の放送割り当て

F_FOT_BROAD RCDATA
BEGIN
4L,              // 最小チャンネル
9L,              // 最大チャンネル

175250000L,      // 4
183250000L,      // 5
191250000L,      // 6
199250000L,      // 7
207250000L,      // 8
215250000L,      // 9
END

5.1.6.2 海外フランス領国のケーブルテレビ割り当て

標準化されたケーブルテレビ構成に対応するデータがないため、Unicable 周波数テーブル (下を参照) が使用される。

5.1.7 アイルランド

アイルランドのテーブルに含まれている周波数インデックスは、チャンネル番号の用途に適していない。

5.1.7.1 アイルランドの放送割り当て

F_IRE_BROAD RCDATA
BEGIN
1L,              // 最小インデックス
10L,             // 最大インデックス

45750000L,       // A
53750000L,       // B
61750000L,       // C
175250000L,      // D
183750000L,      // E
191250000L,      // F
199250000L,      // G
207250000L,      // H
215250000L,      // I
223250000L,      // J
END

5.1.7.2 アイルランドのケーブルテレビ割り当て

標準化されたケーブルテレビ構成に対応するデータがないため、Unicable 周波数テーブル (下を参照) が使用される。

5.1.8 イタリア

イタリアのテーブルに含まれている周波数インデックスは、チャンネル番号の用途に適していない。

5.1.8.1. イタリアの放送割り当て

F_ITA_BROAD RCDATA
BEGIN
1L,             // 最小インデックス
10L,            // 最大インデックス

53750000L,      // 1    A
59750000L,      // 2    B
82750000L,      // 3    C
175250000L,     // 4    D
183750000L,     // 5    E
192250000L,     // 6    F
201250000L,     // 7    G
210250000L,     // 8    H
217250000L,     // 9    H1
224250000L,     // 10   H2

END

5.1.8.2 イタリアのケーブルテレビ割り当て

標準化されたケーブルテレビ構成に対応するデータがないため、Unicable 周波数テーブル (下を参照) が使用される。

5.1.9 日本

日本のテーブルに含まれている周波数インデックスは、チャンネル番号の用途に適している。

5.1.9.1 日本の放送割り当て

F_JAP_BROAD RCDATA
BEGIN
1L,             // 最小チャンネル
62L,            // 最大チャンネル

91250000L,      // 1
97250000L,      // 2
103250000L,     // 3
171250000L,     // 4
177250000L,     // 5
183250000L,     // 6
189250000L,     // 7
193250000L,     // 8
199250000L,     // 9
205250000L,     // 10
211250000L,     // 11
217250000L,     // 12
471250000L,     // 13
477250000L,     // 14
483250000L,     // 15
489250000L,     // 16
495250000L,     // 17
501250000L,     // 18
507250000L,     // 19
513250000L,     // 20
519250000L,     // 21
525250000L,     // 22
531250000L,     // 23
537250000L,     // 24
543250000L,     // 25
549250000L,     // 26
555250000L,     // 27
561250000L,     // 28
567250000L,     // 29
573250000L,     // 30
579250000L,     // 31
585250000L,     // 32
591250000L,     // 33
597250000L,     // 34
603250000L,     // 35
609250000L,     // 36
615250000L,     // 37
621250000L,     // 38
627250000L,     // 39
633250000L,     // 40
639250000L,     // 41
645250000L,     // 42
651250000L,     // 43
657250000L,     // 44
663250000L,     // 45
669250000L,     // 46
675250000L,     // 47
681250000L,     // 48
687250000L,     // 49
693250000L,     // 50
699250000L,     // 51
705250000L,     // 52
711250000L,     // 53
717250000L,     // 54
723250000L,     // 55
729250000L,     // 56
735250000L,     // 57
741250000L,     // 58
747250000L,     // 59
753250000L,     // 60
759250000L,     // 61
765250000L,     // 62
END

5.1.9.2 日本のケーブルテレビ割り当て

F_JAP_CABLE RCDATA
BEGIN
1L,             // 最小チャンネル
113L,           // 最大チャンネル

91250000L,      // 1
97250000L,      // 2
103250000L,     // 3
109250000L,     // 4
115250000L,     // 5
121250000L,     // 6
127250000L,     // 7
133250000L,     // 8
139250000L,     // 9
145250000L,     // 10
151250000L,     // 11
157250000L,     // 12
165250000L,     // 13
171250000L,     // 14
177250000L,     // 15
183250000L,     // 16
189250000L,     // 17
193250000L,     // 18
199250000L,     // 19
205250000L,     // 20
211250000L,     // 21
217250000L,     // 22
223250000L,     // 23
231250000L,     // 24
237250000L,     // 25
243250000L,     // 26
249250000L,     // 27
253250000L,     // 28
259250000L,     // 29
265250000L,     // 30
271250000L,     // 31
277250000L,     // 32
283250000L,     // 33
289250000L,     // 34
295250000L,     // 35
301250000L,     // 36
307250000L,     // 37
313250000L,     // 38
319250000L,     // 39
325250000L,     // 40
331250000L,     // 41
337250000L,     // 42
343250000L,     // 43
349250000L,     // 44
355250000L,     // 45
361250000L,     // 46
367250000L,     // 47
373250000L,     // 48
379250000L,     // 49
385250000L,     // 50
391250000L,     // 51
397250000L,     // 52
403250000L,     // 53
409250000L,     // 54
415250000L,     // 55
421250000L,     // 56
427250000L,     // 57
433250000L,     // 58
439250000L,     // 59
445250000L,     // 60
451250000L,     // 61
457250000L,     // 62
463250000L,     // 63

471250000L,     // テスト
477250000L,     // テスト
483250000L,     // テスト
489250000L,     // テスト
495250000L,     // テスト
501250000L,     // テスト
507250000L,     // テスト
513250000L,     // テスト
519250000L,     // テスト
525250000L,     // テスト
531250000L,     // テスト
537250000L,     // テスト
543250000L,     // テスト
549250000L,     // テスト
555250000L,     // テスト
561250000L,     // テスト
567250000L,     // テスト
573250000L,     // テスト
579250000L,     // テスト
585250000L,     // テスト
591250000L,     // テスト
597250000L,     // テスト
603250000L,     // テスト
609250000L,     // テスト
615250000L,     // テスト
621250000L,     // テスト
627250000L,     // テスト
633250000L,     // テスト
639250000L,     // テスト
645250000L,     // テスト
651250000L,     // テスト
657250000L,     // テスト
663250000L,     // テスト
669250000L,     // テスト
675250000L,     // テスト
681250000L,     // テスト
687250000L,     // テスト
693250000L,     // テスト
699250000L,     // テスト
705250000L,     // テスト
711250000L,     // テスト
717250000L,     // テスト
723250000L,     // テスト
729250000L,     // テスト
735250000L,     // テスト
741250000L,     // テスト
747250000L,     // テスト
753250000L,     // テスト
759250000L,     // テスト
765250000L,     // テスト
END

5.1.10 ニュージーランド

ニュージーランドの放送のテーブルに含まれている周波数インデックスは、チャンネル番号の用途に適している。ケーブルテレビの周波数インデックスは、チャンネル番号の用途に適していない。

5.1.10.1 ニュージーランドの放送割り当て

F_NZ__BROAD RCDATA
BEGIN
1L,              // 最小チャンネル
11L,             // 最大チャンネル

45250000L,       // 1
55250000L,       // 2
62250000L,       // 3
175250000L,      // 4
182250000L,      // 5
189250000L,      // 6
196250000L,      // 7
203250000L,      // 8
210250000L,      // 9
217250000L,      // 10
224250000L,      // 11
END

5.1.10.2 ニュージーランドのケーブルテレビ割り当て

標準化されたケーブルテレビ構成に対応するデータがないため、Unicable 周波数テーブル (下を参照) が使用される。

5.1.11 NTSC (アメリカ合衆国)

NTSC のテーブルは、NTSC 方式のチャンネル構成を使用しているすべてのロケールに該当する。放送およびケーブルテレビの両方の構成が標準化されていて、安定している。また、周波数インデックスは、チャンネル番号の用途に適している。

5.1.11.1 NTSC の放送割り当て

F_USA_BROAD RCDATA
BEGIN
2L,              // 最小チャンネル
69L,             // 最大チャンネル

55250000L,       // 2
61250000L,       // 3
67250000L,       // 4
77250000L,       // 5
83250000L,       // 6
175250000L,      // 7
181250000L,      // 8
187250000L,      // 9
193250000L,      // 10
199250000L,      // 11
205250000L,      // 12
211250000L,      // 13
471250000L,      // 14
477250000L,      // 15
483250000L,      // 16
489250000L,      // 17
495250000L,      // 18
501250000L,      // 19
507250000L,      // 20
513250000L,      // 21
519250000L,      // 22
525250000L,      // 23
531250000L,      // 24
537250000L,      // 25
543250000L,      // 26
549250000L,      // 27
555250000L,      // 28
561250000L,      // 29
567250000L,      // 30
573250000L,      // 31
579250000L,      // 32
585250000L,      // 33
591250000L,      // 34
597250000L,      // 35
603250000L,      // 36
609250000L,      // 37
615250000L,      // 38
621250000L,      // 39
627250000L,      // 40
633250000L,      // 41
639250000L,      // 42
645250000L,      // 43
651250000L,      // 44
657250000L,      // 45
663250000L,      // 46
669250000L,      // 47
675250000L,      // 48
681250000L,      // 49
687250000L,      // 50
693250000L,      // 51
699250000L,      // 52
705250000L,      // 53
711250000L,      // 54
717250000L,      // 55
723250000L,      // 56
729250000L,      // 57
735250000L,      // 58
741250000L,      // 59
747250000L,      // 60
753250000L,      // 61
759250000L,      // 62
765250000L,      // 63
771250000L,      // 64
777250000L,      // 65
783250000L,      // 66
789250000L,      // 67
795250000L,      // 68
801250000L,      // 69
END

5.1.11.2 NTSC のケーブルテレビ割り当て

F_USA_CABLE RCDATA
BEGIN
1L,              // 最小チャンネル
158L,            // 最大チャンネル

73250000L,       // 1
55250000L,       // 2
61250000L,       // 3
67250000L,       // 4
77250000L,       // 5
83250000L,       // 6
175250000L,      // 7
181250000L,      // 8
187250000L,      // 9
193250000L,      // 10
199250000L,      // 11
205250000L,      // 12
211250000L,      // 13
121250000L,      // 14
127250000L,      // 15
133250000L,      // 16
139250000L,      // 17
145250000L,      // 18
151250000L,      // 19
157250000L,      // 20
163250000L,      // 21
169250000L,      // 22
217250000L,      // 23
223250000L,      // 24
229250000L,      // 25
235250000L,      // 26
241250000L,      // 27
247250000L,      // 28
253250000L,      // 29
259250000L,      // 30
265250000L,      // 31
271250000L,      // 32
277250000L,      // 33
283250000L,      // 34
289250000L,      // 35
295250000L,      // 36
301250000L,      // 37
307250000L,      // 38
313250000L,      // 39
319250000L,      // 40
325250000L,      // 41
331250000L,      // 42
337250000L,      // 43
343250000L,      // 44
349250000L,      // 45
355250000L,      // 46
361250000L,      // 47
367250000L,      // 48
373250000L,      // 49
379250000L,      // 50
385250000L,      // 51
391250000L,      // 52
397250000L,      // 53
403250000L,      // 54
409250000L,      // 55
415250000L,      // 56
421250000L,      // 57
427250000L,      // 58
433250000L,      // 59
439250000L,      // 60
445250000L,      // 61
451250000L,      // 62
457250000L,      // 63
463250000L,      // 64
469250000L,      // 65
475250000L,      // 66
481250000L,      // 67
487250000L,      // 68
493250000L,      // 69
499250000L,      // 70
505250000L,      // 71
511250000L,      // 72
517250000L,      // 73
523250000L,      // 74
529250000L,      // 75
535250000L,      // 76
541250000L,      // 77
547250000L,      // 78
553250000L,      // 79
559250000L,      // 80
565250000L,      // 81
571250000L,      // 82
577250000L,      // 83
583250000L,      // 84
589250000L,      // 85
595250000L,      // 86
601250000L,      // 87
607250000L,      // 88
613250000L,      // 89
619250000L,      // 90
625250000L,      // 91
631250000L,      // 92
637250000L,      // 93
643250000L,      // 94
91250000L,       // 95
97250000L,       // 96
103250000L,      // 97
109250000L,      // 98
115250000L,      // 99
649250000L,      // 100
655250000L,      // 101
661250000L,      // 102
667250000L,      // 103
673250000L,      // 104
679250000L,      // 105
685250000L,      // 106
691250000L,      // 107
697250000L,      // 108
703250000L,      // 109
709250000L,      // 110
715250000L,      // 111
721250000L,      // 112
727250000L,      // 113
733250000L,      // 114
739250000L,      // 115
745250000L,      // 116
751250000L,      // 117
757250000L,      // 118
763250000L,      // 119
769250000L,      // 120
775250000L,      // 121
781250000L,      // 122
787250000L,      // 123
793250000L,      // 124
799250000L,      // 125
805250000L,      // 126
811250000L,      // 127
817250000L,      // 128
823250000L,      // 129
829250000L,      // 130
835250000L,      // 131
841250000L,      // 132
847250000L,      // 133
853250000L,      // 134
859250000L,      // 135
865250000L,      // 136
871250000L,      // 137
877250000L,      // 138
883250000L,      // 139
889250000L,      // 140
895250000L,      // 141
901250000L,      // 142
907250000L,      // 143
913250000L,      // 144
919250000L,      // 145
925250000L,      // 146
931250000L,      // 147
937250000L,      // 148
943250000L,      // 149
949250000L,      // 150
955250000L,      // 151
961250000L,      // 152
967250000L,      // 153
973250000L,      // 154
979250000L,      // 155
985250000L,      // 156
991250000L,      // 157
997250000L,      // 158
END

5.1.12 英国

英国のテーブルに含まれている周波数インデックスは、チャンネル番号の用途に適していない。

5.1.12.1 英国の放送割り当て

F_UK__BROAD RCDATA
BEGIN
1L,              // 最小インデックス
69L,             // 最大インデックス

45750000L,       // 1
53750000L,       // 2
61750000L,       // 3
175250000L,      // 4
183250000L,      // 5
191250000L,      // 6
199250000L,      // 7
207250000L,      // 8
215250000L,      // 9
223250000L,      // 10
231250000L,      // 11

0L,              // 12  未使用
0L,              // 13  未使用
0L,              // 14  未使用
0L,              // 15  未使用
0L,              // 16  未使用
0L,              // 17  未使用
0L,              // 18  未使用
0L,              // 19  未使用
0L,              // 20  未使用

471250000L,      // 21
479250000L,      // 22
487250000L,      // 23
495250000L,      // 24
503250000L,      // 25
511250000L,      // 26
519250000L,      // 27
527250000L,      // 28
535250000L,      // 29
543250000L,      // 30
551250000L,      // 31
559250000L,      // 32
567250000L,      // 33
575250000L,      // 34
583250000L,      // 35
591250000L,      // 36
599250000L,      // 37
607250000L,      // 38
615250000L,      // 39
623250000L,      // 40
631250000L,      // 41
639250000L,      // 42
647250000L,      // 43
655250000L,      // 44
663250000L,      // 45
671250000L,      // 46
679250000L,      // 47
687250000L,      // 48
695250000L,      // 49
703250000L,      // 50
711250000L,      // 51
719250000L,      // 52
727250000L,      // 53
735250000L,      // 54
743250000L,      // 55
751250000L,      // 56
759250000L,      // 57
767250000L,      // 58
775250000L,      // 59
783250000L,      // 60
791250000L,      // 61
799250000L,      // 62
807250000L,      // 63
815250000L,      // 64
823250000L,      // 65
831250000L,      // 66
839250000L,      // 67
847250000L,      // 68
855250000L,      // 69

END

英国のケーブルテレビ割り当て

F_UK__CABLE RCDATA
BEGIN
1L,              // 最小インデックス
107L,            // 最大インデックス

48250000L,       // 1    E2
49750000L,       // 2    E2A
55250000L,       // 3    E3
62250000L,       // 4    E4
69250000L,       // 5    S01
76250000L,       // 6    S02
83250000L,       // 7    S03
90250000L,       // 8    S04
97250000L,       // 9    S05
105250000L,      // 10   S1
112250000L,      // 11   S2
119250000L,      // 12   S3
126250000L,      // 13   S4
133250000L,      // 14   S5
140250000L,      // 15   S6
147250000L,      // 16   S7
154250000L,      // 17   S8
161250000L,      // 18   S9
168250000L,      // 19   S10
175250000L,      // 20   E5
182250000L,      // 21   E6
189250000L,      // 22   E7
196250000L,      // 23   E8
203250000L,      // 24   E9
210250000L,      // 25   E10
217250000L,      // 26   E11
224250000L,      // 27   E12
231250000L,      // 28   S11
238250000L,      // 29   S12
245250000L,      // 30   S13
252250000L,      // 31   S14
259250000L,      // 32   S15
266250000L,      // 33   S16
273250000L,      // 34   S17
280250000L,      // 35   S18
287250000L,      // 36   S19
294250000L,      // 37   S20
303250000L,      // 38   S21
311250000L,      // 39   S22
319250000L,      // 40   S23
327250000L,      // 41   S24
335250000L,      // 42   S25
343250000L,      // 43   S26
351250000L,      // 44   S27
359250000L,      // 45   S28
367250000L,      // 46   S29
375250000L,      // 47   S30
383250000L,      // 48   S31
391250000L,      // 49   S32
399250000L,      // 50   S33
407250000L,      // 51   S34
415250000L,      // 52   S35
423250000L,      // 53   S36
431250000L,      // 54   S37
439250000L,      // 55   S38
447250000L,      // 56   S39
455250000L,      // 57   S40
463250000L,      // 58   S41

471250000L,      // 59
479250000L,      // 60
487250000L,      // 61
495250000L,      // 62
503250000L,      // 63
511250000L,      // 64
519250000L,      // 65
527250000L,      // 66
535250000L,      // 67
543250000L,      // 68
551250000L,      // 69
559250000L,      // 70
567250000L,      // 71
575250000L,      // 72
583250000L,      // 73
591250000L,      // 74
599250000L,      // 75
607250000L,      // 76
615250000L,      // 77
623250000L,      // 78
631250000L,      // 79
639250000L,      // 80
647250000L,      // 81
655250000L,      // 82
663250000L,      // 83
671250000L,      // 84
679250000L,      // 85
687250000L,      // 86
695250000L,      // 87
703250000L,      // 88
711250000L,      // 89
719250000L,      // 90
727250000L,      // 91
735250000L,      // 92
743250000L,      // 93
751250000L,      // 94
759250000L,      // 95
767250000L,      // 96
775250000L,      // 97
783250000L,      // 98
791250000L,      // 99
799250000L,      // 100
807250000L,      // 101
815250000L,      // 102
823250000L,      // 103
831250000L,      // 104
839250000L,      // 105
847250000L,      // 106
855250000L,      // 107

END

5.1.13 西ヨーロッパ

西ヨーロッパのテーブルに含まれている周波数インデックスは、チャンネル番号の用途に適していない。

5.1.13.1 西ヨーロッパの放送割り当て

F_WEU_BROAD RCDATA
BEGIN
1L,              // 最小インデックス
69L,             // 最大インデックス

48250000L,       // 2
49750000L,       // 2A
55250000L,       // 3
62250000L,       // 4
175250000L,      // 5
182250000L,      // 6
189250000L,      // 7
196250000L,      // 8
203250000L,      // 9
210250000L,      // 10
217250000L,      // 11
224250000L,      // 12

0L,              // 13 未使用
0L,              // 14 未使用
0L,              // 15 未使用
0L,              // 16 未使用
0L,              // 17 未使用
0L,              // 18 未使用
0L,              // 19 未使用
0L,              // 20 未使用

471250000L,      // 21
479250000L,      // 22
487250000L,      // 23
495250000L,      // 24
503250000L,      // 25
511250000L,      // 26
519250000L,      // 27
527250000L,      // 28
535250000L,      // 29
543250000L,      // 30
551250000L,      // 31
559250000L,      // 32
567250000L,      // 33
575250000L,      // 34
583250000L,      // 35
591250000L,      // 36
599250000L,      // 37
607250000L,      // 38
615250000L,      // 39
623250000L,      // 40
631250000L,      // 41
639250000L,      // 42
647250000L,      // 43
655250000L,      // 44
663250000L,      // 45
671250000L,      // 46
679250000L,      // 47
687250000L,      // 48
695250000L,      // 49
703250000L,      // 50
711250000L,      // 51
719250000L,      // 52
727250000L,      // 53
735250000L,      // 54
743250000L,      // 55
751250000L,      // 56
759250000L,      // 57
767250000L,      // 58
775250000L,      // 59
783250000L,      // 60
791250000L,      // 61
799250000L,      // 62
807250000L,      // 63
815250000L,      // 64
823250000L,      // 65
831250000L,      // 66
839250000L,      // 67
847250000L,      // 68
855250000L,      // 69

END

5.1.13.2 西ヨーロッパのケーブルテレビ割り当て

一部の国については、標準化されたケーブルテレビ構成に対応するデータがある。チャンネル構成データが報告されていない国では、Unicable 周波数テーブル (下を参照) が使用される。

F_WEU_CABLE RCDATA
BEGIN
1L,              // 最小インデックス
107L,            // 最大インデックス

48250000L,       // 1    E2
49750000L,       // 2    E2A
55250000L,       // 3    E3
62250000L,       // 4    E4
69250000L,       // 5    S01
76250000L,       // 6    S02
83250000L,       // 7    S03
90250000L,       // 8    S04
97250000L,       // 9    S05
105250000L,      // 10   S1
112250000L,      // 11   S2
119250000L,      // 12   S3
126250000L,      // 13   S4
133250000L,      // 14   S5
140250000L,      // 15   S6
147250000L,      // 16   S7
154250000L,      // 17   S8
161250000L,      // 18   S9
168250000L,      // 19   S10
175250000L,      // 20   E5
182250000L,      // 21   E6
189250000L,      // 22   E7
196250000L,      // 23   E8
203250000L,      // 24   E9
210250000L,      // 25   E10
217250000L,      // 26   E11
224250000L,      // 27   E12
231250000L,      // 28   S11
238250000L,      // 29   S12
245250000L,      // 30   S13
252250000L,      // 31   S14
259250000L,      // 32   S15
266250000L,      // 33   S16
273250000L,      // 34   S17
280250000L,      // 35   S18
287250000L,      // 36   S19
294250000L,      // 37   S20
303250000L,      // 38   S21
311250000L,      // 39   S22
319250000L,      // 40   S23
327250000L,      // 41   S24
335250000L,      // 42   S25
343250000L,      // 43   S26
351250000L,      // 44   S27
359250000L,      // 45   S28
367250000L,      // 46   S29
375250000L,      // 47   S30
383250000L,      // 48   S31
391250000L,      // 49   S32
399250000L,      // 50   S33
407250000L,      // 51   S34
415250000L,      // 52   S35
423250000L,      // 53   S36
431250000L,      // 54   S37
439250000L,      // 55   S38
447250000L,      // 56   S39
455250000L,      // 57   S40
463250000L,      // 58   S41

471250000L,      // 59
479250000L,      // 60
487250000L,      // 61
495250000L,      // 62
503250000L,      // 63
511250000L,      // 64
519250000L,      // 65
527250000L,      // 66
535250000L,      // 67
543250000L,      // 68
551250000L,      // 69
559250000L,      // 70
567250000L,      // 71
575250000L,      // 72
583250000L,      // 73
591250000L,      // 74
599250000L,      // 75
607250000L,      // 76
615250000L,      // 77
623250000L,      // 78
631250000L,      // 79
639250000L,      // 80
647250000L,      // 81
655250000L,      // 82
663250000L,      // 83
671250000L,      // 84
679250000L,      // 85
687250000L,      // 86
695250000L,      // 87
703250000L,      // 88
711250000L,      // 89
719250000L,      // 90
727250000L,      // 91
735250000L,      // 92
743250000L,      // 93
751250000L,      // 94
759250000L,      // 95
767250000L,      // 96
775250000L,      // 97
783250000L,      // 98
791250000L,      // 99
799250000L,      // 100
807250000L,      // 101
815250000L,      // 102
823250000L,      // 103
831250000L,      // 104
839250000L,      // 105
847250000L,      // 106
855250000L,      // 107
END

5.1.14 Unicable

量が多いため、Unicable テーブルはここに記載されていない。Unicable テーブルの目標は、1 つのテーブルに周波数の包括的な集合、つまり、ほかのすべてのテーブルと実際の調査に基づくデータを含めることにより、周波数スペクトル全体にわたって直線的な検索を行わなくても、自動的にチャンネル スキャンを行えるようにすることである。このテーブルに含まれていない周波数については、消費者が独自のユーザー インターフェイスを使って入力する必要があり、その結果は、レジストリに周波数オーバーライド エントリとして登録される (前のセクション 0 を参照)。

5.2 国割り当て

1 列目の数値は、国際電話ダイヤル規格で定められている国コードである。この国コード番号を IAMTVTuner::put_CountryCode メソッドに渡すことによって、カラーテレビ方式およびデフォルトの周波数マッピングを選択することができる。

RCDATA_COUNTRYLIST RCDATA

BEGIN

1,   F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,
// アメリカ合衆国
// アングイラ
// アンティグア
// バハマ
// バルバドス
// バーミューダ
// 英領バージン諸島
// カナダ
// ケイマン諸島
// ドミニカ
// ドミニカ共和国
// グレナダ
// ジャマイカ
// モントセラト
// ネビス
// セントキッツ
// セントビンセント-グレナディン
// トリニダードトバゴ
// タークス アンド ケーコス諸島
// バルブダ
// プエルトリコ
// セントルシア
// 米領バージン諸島

2,   F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // カナダ (WIN.INI はこの一国用のダミーである)

20,  F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_SECAM_B,     // エジプト
212, F_UNI_CABLE, F_FIX_BROAD, AnalogVideo_SECAM_B,     // モロッコ
213, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // アルジェリア
216, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_SECAM_B,     // チュニジア
218, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_SECAM_B,     // リビア
220, F_UNI_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // ガンビア
221, F_UNI_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // セネガル共和国
222, F_UNI_CABLE, F_FIX_BROAD, AnalogVideo_SECAM_B,     // モーリタニア
223, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_SECAM_K,     // マリ
224, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_SECAM_K,     // ギニア
225, F_UNI_CABLE, F_FIX_BROAD, AnalogVideo_SECAM_K,     // コートジボアール
226, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_SECAM_K,     // ブルキナファソ
227, F_UNI_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // ニジェール
228, F_UNI_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // トーゴ
229, F_UNI_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // ベニン
230, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_SECAM_B,     // モーリシャス
231, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // リベリア
232, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // シエラレオーネ
233, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // ガーナ
234, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // ナイジェリア
235, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // チャド
236, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // 中央アフリカ共和国
237, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // カメルーン
238, F_UNI_CABLE, F_FIX_BROAD, AnalogVideo_FIX___,      // カボベルデ諸島
239, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // サントーメ-プリンシペ
240, F_UNI_CABLE, F_FIX_BROAD, AnalogVideo_SECAM_B,     // 赤道ギニア
241, F_UNI_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // ガボン
242, F_UNI_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_D,     // コンゴ
243, F_UNI_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // コンゴ民主共和国
244, F_UNI_CABLE, F_FIX_BROAD, AnalogVideo_PAL_I,       // アンゴラ
245, F_UNI_CABLE, F_FIX_BROAD, AnalogVideo_FIX___,      // ギニア-ビサウ
246, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // ディエゴガルシア
247, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // アセンション島
248, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // セーシェル諸島
249, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // スーダン
250, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,,      // ルワンダ
251, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // エチオピア
252, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // ソマリア
253, F_UNI_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // ジブチ
254, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // ケニア
255, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // タンザニア
256, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // ウガンダ
257, F_UNI_CABLE, F_FIX_BROAD, AnalogVideo_SECAM_K,     // ブルンジ
258, F_UNI_CABLE, F_FIX_BROAD, AnalogVideo_PAL_B,       // モザンビーク
260, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // ザンビア
261, F_UNI_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // マダガスカル
262, F_UNI_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // レユニオン島
263, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // ジンバブウェ
264, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_PAL_I,       // ナミビア
265, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // マラウィ
266, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_PAL_I,       // レソト
267, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_SECAM_K,     // ボツワナ
268, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // スワジランド
269, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_SECAM_K,     // マヨット島
269, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // コモロ
27,  F_UNI_CABLE, F_UK__BROAD, AnalogVideo_PAL_I,       // 南アフリカ
290, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // セントヘレナ
291, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // エリトリア
297, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // アルーバ
298, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // フェロー諸島
299, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // グリーンランド
30,  F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_SECAM_B,     // ギリシア
31,  F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // オランダ
32,  F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // ベルギー
33,  F_UNI_CABLE, F_FRA_BROAD, AnalogVideo_SECAM_L,     // フランス
34,  F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // スペイン
350, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // ジブラルタル
351, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // ポルトガル
352, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // ルクセンブルク
353, F_UNI_CABLE, F_IRE_BROAD, AnalogVideo_PAL_I,       // アイルランド
354, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // アイスランド
355, F_UNI_CABLE, F_ITA_BROAD, AnalogVideo_PAL_B,       // アルバニア
356, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // マルタ
357, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // キプロス
358, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // フィンランド
359, F_UNI_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // ブルガリア
36,  F_UNI_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // ハンガリー
370, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // リトアニア
371, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_SECAM_D,     // ラトビア
372, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // エストニア
373, F_UNI_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // モルダビア
374, F_UNI_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // アルメニア
375, F_UNI_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // ベラルーシ
376, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // アンドラ
377, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_SECAM_G,     // モナコ
378, F_UNI_CABLE, F_ITA_BROAD, AnalogVideo_PAL_B,       // サンマリノ
380, F_UNI_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // ウクライナ
381, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // ユーゴスラビア
385, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // クロアチア
386, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // スロベニア
387, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // ボスニア-ヘルツェゴビナ
389, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // マケドニア・旧ユーゴースラビア共和国
39,  F_UNI_CABLE, F_ITA_BROAD, AnalogVideo_PAL_B,       // イタリア
39,  F_UNI_CABLE, F_ITA_BROAD, AnalogVideo_PAL_B,       // バチカン市国
40,  F_UNI_CABLE, F_EEU_BROAD, AnalogVideo_PAL_D,       // ルーマニア
41,  F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // スイス
41,  F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // リヒテンシュタイン
420, F_UNI_CABLE, F_CZE_BROAD, AnalogVideo_PAL_D,       // チェコ共和国
421, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // スロバキア共和国
43,  F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // オーストリア
44,  F_UK__CABLE, F_UK__BROAD, AnalogVideo_PAL_I,       // 英国
45,  F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // デンマーク
46,  F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // スウェーデン
47,  F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // ノルウェー
48,  F_UNI_CABLE, F_EEU_BROAD, AnalogVideo_PAL_B,       // ポーランド
49,  F_WEU_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // ドイツ
500, F_UNI_CABLE, F_UK__BROAD, AnalogVideo_PAL_I,       // フォークランド諸島
501, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // ベリーズ
502, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // グアテマラ
503, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // エルサルバドル
504, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // ホンジュラス
505, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // ニカラグア
506, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // コスタリカ
507, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // パナマ
508, F_UNI_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // サンピエール島・ミクロン島
509, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // ハイチ
51,  F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // ペルー
52,  F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // メキシコ
53,  F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // キューバ
53,  F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // グアンタナモ湾
54,  F_USA_CABLE, F_USA_BROAD, AnalogVideo_PAL_N,       // アルゼンチン
55,  F_USA_CABLE, F_USA_BROAD, AnalogVideo_PAL_M,       // ブラジル
56,  F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // チリ
57,  F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // コロンビア
58,  F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // ベネズエラ
590, F_UNI_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // グアドループ
590, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // 仏領アンティル諸島
591, F_USA_CABLE, F_USA_BROAD, AnalogVideo_PAL_N,       // ボリビア
592, F_UNI_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // ガイアナ
593, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // エクアドル
594, F_UNI_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // 仏領ギアナ
595, F_USA_CABLE, F_USA_BROAD, AnalogVideo_PAL_N,       // パラグアイ
596, F_UNI_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // マルチニーク
597, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // スリナム
598, F_USA_CABLE, F_USA_BROAD, AnalogVideo_PAL_N,       // ウルグアイ
599, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // オランダ領アンティル
60,  F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // マレーシア
61,  F_UNI_CABLE, F_OZ__BROAD, AnalogVideo_PAL_B,       // オーストラリア
61,  F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // ココス-キーリング諸島
62,  F_UNI_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // インドネシア
63,  F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // フィリピン
64,  F_UNI_CABLE, F_NZ__BROAD, AnalogVideo_PAL_B,       // ニュージーランド
65,  F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // シンガポール
66,  F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // タイ
670, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // サイパン島
670, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // ロタ島
670, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // ティニアン島
671, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // グアム
672, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // クリスマス島
672, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // 南極オーストラリア領
672, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // ノーフォーク島
673, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // ブルネイ
674, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // ナウル
675, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // パプアニューギニア
676, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // トンガ
677, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // ソロモン諸島
678, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // バヌアツ
679, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // フィジー
680, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // パラオ
681, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_SECAM_K,     // ワリス・フテュナ諸島
682, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // クック諸島
683, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // ニウエ
684, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // 米領サモア
685, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // 西サモア
686, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // キリバス共和国
687, F_UNI_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // ニューカレドニア
688, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // ツバル
689, F_UNI_CABLE, F_FOT_BROAD, AnalogVideo_SECAM_K,     // 仏領ポリネシア
690, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // トケラウ
691, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // ミクロネシア
692, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // マーシャル諸島
7,   F_UNI_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // ロシア
7,   F_UNI_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // カザフスタン
7,   F_UNI_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // キルギスタン
7,   F_UNI_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // タジキスタン
7,   F_UNI_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // トルクメニスタン
7,   F_UNI_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // ウズベキスタン

81,  F_JAP_CABLE, F_JAP_BROAD, AnalogVideo_NTSC_M_J,    // 日本

82,  F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // 韓国
84,  F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // ベトナム
850, F_UNI_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // 北朝鮮
852, F_UNI_CABLE, F_UK__BROAD, AnalogVideo_PAL_I,       // ホンコン
853, F_UNI_CABLE, F_UK__BROAD, AnalogVideo_PAL_I,       // マカオ
855, F_USA_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // カンボジア
856, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // ラオス
86,  F_CHN_CABLE, F_CHN_BROAD, AnalogVideo_PAL_D,       // 中国
871, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // INMARSAT (東大西洋)
872, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // INMARSAT (太平洋)
873, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // INMARSAT (インド洋)
874, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // INMARSAT (西大西洋)
880, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // バングラデシュ
886, F_USA_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // 台湾、中華民国
90,  F_UNI_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // トルコ
91,  F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // インド
92,  F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // パキスタン
93,  F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // アフガニスタン
94,  F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // スリランカ
95,  F_UNI_CABLE, F_USA_BROAD, AnalogVideo_NTSC_M,      // ミャンマー
960, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // モルジブ
961, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_SECAM_B,     // レバノン
962, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // ヨルダン
963, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_SECAM_B,     // シリア
964, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_SECAM_B,     // イラク
965, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // クウェート
966, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_SECAM_B,     // サウジアラビア
967, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // イエメン
968, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // オマーン
971, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // アラブ首長国連邦
972, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // イスラエル
973, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // バーレーン
974, F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_PAL_B,       // カタール
975, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_FIX___,      // ブータン
976, F_UNI_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // モンゴル
977, F_UNI_CABLE, F_USA_BROAD, AnalogVideo_PAL_B,       // ネパール
98,  F_UNI_CABLE, F_WEU_BROAD, AnalogVideo_SECAM_B,     // イラン
994, F_UNI_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // アゼルバイジャン
995, F_UNI_CABLE, F_EEU_BROAD, AnalogVideo_SECAM_D,     // グルジア

0,   0,           0,           0  // ゼロはリストの末尾を示す

END


マルチメディア ストリーミング

この項では、ソースからアプリケーションに渡されるデータの転送と変換を自動的にネゴシエートする、マルチメディア ストリーミング インターフェイスについて説明する。マルチメディア ストリーミングのデータ タイプ、インターフェイス、およびインターフェイス メソッドのリファレンス エントリを記載する。また、サンプル コードを紹介し、各マルチメディア ストリーミング コンポーネント オブジェクトについて、説明、CLSID、およびサポートするインターフェイスを記載する。

  • マルチメディア ストリーミング アーキテクチャについて
  • マルチメディア ストリーミング インターフェイスの一覧
  • マルチメディア ストリーミング リファレンス
  • マルチメディア ストリーミング コンポーネント オブジェクト
  • マルチメディア ストリーミングのサンプル コード


マルチメディア ストリーミング アーキテクチャについて

ここでは、マルチメディア ストリーミングのアーキテクチャと、ソフトウェア開発者がツールまたはアプリケーションでストリームを使用するときの標準的な使い方について説明する。また、データ転送の基盤としてのストリーミングの利点、およびマルチメディア プログラミングの要点 (ストリーミング アプリケーションでのデータ転送、パフォーマンスの最適化、タイム スタンプ処理など) についても説明する。マルチメディア ストリーミングを使用するプログラマは、COM プログラミングの概念を十分理解している必要がある。

以下の項で構成される。

  • マルチメディア ストリーミングの利点
  • オブジェクトの階層構造
  • マルチメディア ストリーム オブジェクトとストリーム サンプルの作成
  • アプリケーションでのマルチメディア ストリームの使い方
  • ストリーム間のデータ共有

マルチメディア ストリーミングの利点

マルチメディア ストリーミングを使用すると、フォーマット固有のプログラム量を大幅に削減できる。通常、アプリケーションからファイルやハードウェアのメディア データを取得するには、データ フォーマットおよびハードウェア デバイスについてわからないことがあってはならない。接続、データ転送、必要なデータ変換、および実際のデータ レンダリングやファイル格納を、すべて処理する必要があるからである。フォーマットおよびデバイスはそれそれ微妙に異なるため、この処理は複雑で煩雑なものになることが多い。対照的に、マルチメディア ストリーミングを使用すると、ソースからアプリケーションに渡されるデータの転送と変換が自動的にネゴシエートされる。ストリーミング インターフェイスは、データのアクセスと制御のための均一でわかりやすいメソッドを提供する。アプリケーションでは、これらのメソッドを使用することによって、ソースやフォーマットにかかわりなく、データを簡単に再生することができる。

以下のステップは、ハードウェア デバイスからレンダリング再生へのストリーミングの実装方法を示す。

  1. ビデオ データのソース (Microsoft® DirectShow® など) が、ストリーミング インターフェイスを公開する。
  2. アプリケーション開発者が、マルチメディア ストリーミング インターフェイスを使用して、データ フォーマットを変換する。
  3. アプリケーション開発者が、Microsoft DirectDraw® インターフェイスを使用して、得られたデータをレンダリングする。

マルチメディア ストリームの仕様は、複数のインターフェイスから構成され、各インターフェイスは、ストリーム処理の特定の性質を制御するメソッドや、特定の種類のデータを処理するメソッドから構成される。詳細については、「マルチメディア ストリーミング インターフェイスの一覧」を参照すること。

オブジェクトの階層構造

次の図は、マルチメディア ストリーミングに使用する基本的なオブジェクトの階層構造を示す。

マルチメディア ストリーミング アーキテクチャには、以下の 3 種類の基本オブジェクトが定義されている。

  1. IMultiMediaStream インターフェイスをサポートするマルチメディア ストリーム。
  2. IMediaStream インターフェイスをサポートするデータ固有のメディア ストリーム。すべてのマルチメディア ストリームには、このメディア ストリームが少なくとも 1 つ含まれる。
  3. メディア ストリームによって作成され、IStreamSample インターフェイスをサポートするストリーム サンプル。このオブジェクトはストリームの基本的な処理単位である。

マルチメディア ストリーム オブジェクトとストリーム サンプルの作成

IMultiMediaStream インターフェイスをサポートするオブジェクトは、マルチメディア データ ストリームのための基本的なコンテナである。IMultiMediaStream インターフェイスには、オブジェクトのデータ ストリームを列挙するメソッドが含まれる。これらのストリームには、通常、ビデオ データおよびオーディオ データが含まれるが、クローズド キャプション、プレーン テキスト、SMPTE タイムコードなどの任意のフォーマットのデータを含めることができる。IMultiMediaStream インターフェイスは汎用コンテナだが、開発者はこのインターフェイスから特定のデータ フォーマットをサポートする別バージョンのインターフェイスを作成できる。たとえば、IAMMultiMediaStream インターフェイスを実装するオブジェクトは、DirectShow の任意のデータ フォーマットを持つストリームを列挙および制御できる。個々のデータ ストリームはフォーマット固有なので、これらのオブジェクトは、異なったインターフェイスを少なくとも 2 つ (汎用インターフェイスとデータ固有のインターフェイス) サポートする。すべてのストリームは、そのフォーマットとストリーム自体へのポインタを取得するメソッドを提供する IMediaStream インターフェイスをサポートする。一方、IDirectDrawMediaStream インターフェイスには、ビデオ データのレンダリングを専門に処理するメソッドが含まれる。IMultiMediaStream から派生するすべてのインターフェイスは、ストリーム サンプル (データ ストリーミングの基本単位) の作成もサポートする。

マルチメディア サンプルは、メディア データが格納されたオブジェクトへの参照である。ビデオ イメージでは、これが DirectDraw サーフェスとなる。サンプルの正確な内容は、メディアの種類 (サウンドやテキストなど) によって異なる。サンプルはデータ オブジェクトへの単なる参照なので、任意の数のストリーム サンプルから 1 つのサンプル オブジェクトを参照することができる。IStreamSample インターフェイスは、サンプルの特性 (開始タイム、終了タイム、状態、およびストリームとの関連) を取得および設定するメソッドを提供する。IStreamSample::Update メソッドは、ストリームが読み取り可能であれば、サンプルのデータに最新状態を反映する。また、ストリームが書き込み可能であれば、サンプルのデータをストリームに書き込む。通常、Update メソッドは、ストリーミング データをレンダリング、転送、または格納するループで使用する。

アプリケーションでのマルチメディア ストリームの使い方

マルチメディア ストリーミング インターフェイスは、ハードウェア ソースまたはソフトウェア ソースの特定の特性への依存性を排除し、Microsoft DirectX® の全メディア フォーマットのサポートを提供することにより、マルチメディア データの処理を大幅に単純化する。ストリームによってデータが非常に高いレベルまで抽象化されるため、アプリケーションでは、フォーマットをまったく意識せずに、データを別のストリームに移動できる。

マルチメディア ストリームを作成するには、以下のステップを実行する。

  1. マルチメディア ストリームを作成する。ストリームを作成および初期化するメソッドは、アーキテクチャ固有である。DirectShow は、ストリームの初期化に使用する IAMMultiMediaStream インターフェイスをサポートする。IMultiMediaStream のその他のインプロセス サーバー実装は、別のメカニズムを使用して作成および初期化される。
  2. マルチメディア ストリーム オブジェクトを初期化した後、アプリケーションでは、QueryInterface を使用してそのオブジェクトに対応する IMultiMediaStream インターフェイスを取得する。このインターフェイスを使用して、ストリームのプロパティを判断し、ストリーム自体を列挙する。個々のストリームを取得するには、目的 ID を指定して IMultiMediaStream::GetMediaStream メソッドを呼び出す。ビデオのプライマリ ストリームを表す MSPID_PrimaryVideo と、オーディオのプライマリ ストリームを表す MSPID_PrimaryAudio は、最もよく使用される目的 ID である。
  3. IUnknown::QueryInterface を呼び出して、ストリームのメディア タイプに固有のインターフェイスを照会する。たとえば、ビデオ ストリームをレンダリングするには、その IDirectDrawMediaStream インターフェイスを取得する。メディア固有のインターフェイスには、フォーマットの能力を十分引き出すために必要な追加メソッドが定義されている。
  4. ストリーム データから 1 つ以上のサンプルを作成する。すべてのメディア ストリームは、サンプルを作成する IMediaStream::CreateSharedSample メソッドをサポートする。作成されたサンプルは、サンプルとその特性の制御を提供する IStreamSample インターフェイスをサポートする。通常、メディア ストリームでは、この IStreamSample メソッドより強力なフォーマット固有のサンプル作成メソッドがサポートされる。たとえば、IDirectDrawMediaStream では、希望の DirectDraw サーフェスおよびクリッピング矩形にアタッチされたサンプルを作成できる。ただし、状況によっては、データのフォーマットを知らずにデータを処理しなければならないことがある。フォーマットに依存しない方法でデータをストリームするには、IMediaStream::CreateSharedSample メソッドを使用してデータ サンプルを作成する。
  5. 希望のストリーム サンプルをすべて作成した後、パラメータに STREAMSTATE_RUN フラグを指定して IMultiMediaStream::SetState メソッドを呼び出すことにより、ストリームを開始する。
  6. IStreamSample::Update を呼び出してストリーム サンプルを更新する。IStreamSample::Update メソッドが終了すると、サンプルのデータにアクセスできる。更新から戻ったときに特定のイベントを発行するか、または特定の関数を呼び出すには、IStreamSample::Update メソッドに適切なポインタを渡す。

マルチメディア ストリーミング インターフェイスの詳細については、「マルチメディア ストリーミング」を参照すること。

ストリーム間のデータ共有

マルチメディア データの処理には、通常、大量のシステム リソースが必要になる。したがって、データのコピーはできる限り避けなければならない。ストリーミング アーキテクチャは、データをコピーぜすに別のストリームに移動するためのメカニズムである、共有ストリーム サンプルをサポートする。このバッファを使用すると、基盤となるデータ フォーマットが転送先ストリームで明確にサポートされていなくても、2 つのストリーム間で効率よくデータを転送できる。

たとえば、3 つのデータ ストリーム (ビデオ、オーディオ、およびビデオ コンテンツに対応するタイム スタンプが入った URL データ) を持つマルチメディア ストリームがあり、ビデオ フレームすべてに著作権表記を追加し、保存のためにデータを別のストリームに書き込むアプリケーションを作成したいが、アプリケーションがビデオ ストリーム以外のデータ フォーマットを理解できないものと想定する。ビデオ ストリームについて、希望の DirectDraw サーフェスにアタッチされたサンプルを作成する。次に、同じサーフェスへのポインタを指定して IDirectDrawMediaStream::CreateSample メソッドを呼び出すか、または IMediaStream::CreateSharedSample を呼び出して、出力ストリームを作成する。どちらの場合も、入力ストリームと出力ストリームは DirectDraw サーフェスを共有する。ビデオ フォーマットは理解できるので、このサーフェスには必要に応じてアクセスすることができる。

その他のソース ストリーム ポインタ (オーディオおよび URL) を取得するには、ソース コンテナ ストリームを列挙して、ビデオ以外のストリームへのポインタを把握する。これらの各ソース ストリームには、出力ストリーム コンテナ内の出力ストリームが関連付けられている。ソース ストリーム ポインタそれぞれについて、出力コンテナ上の IMultiMediaStream::GetMediaStream メソッドを呼び出してこれらの出力ポインタを取得する。この処理は以下のステップで行われる。

  1. IMultiMediaStream::EnumMediaStreams を呼び出してソース ストリームへのポインタを取得する。ビデオ ストリームのフォーマットは既に理解しているので、ビデオ ストリームでないことを確認する。
  2. ステップ 1 で得られたポインタを指定して出力コンテナ ストリーム上の IMultiMediaStream::GetMediaStream を呼び出す。目的の出力ストリームへのポインタが返される。
  3. ソース ストリーム上の AllocateSample を呼び出す。
  4. 出力ストリーム上の CreateSharedSample を呼び出す。
  5. ソース ストリーム上の Update を呼び出してデータを読み取る。
  6. 出力ストリーム上の Update を呼び出してデータを書き込む。

フォーマットをサポートしないストリームそれぞれについて、これらのステップを繰り返す。両方のサンプルが更新を終了すると、ソース ストリームのデータがすべて出力ストリームに渡され、処理が完了する。


マルチメディア ストリーミング インターフェイスの一覧

マルチメディア ストリーミングは、多数のインターフェイスから成り立っている。ここでは、個々のインターフェイスについて簡単に説明する。マルチメディア ストリーミングの詳細については、「マルチメディア ストリーミング アーキテクチャについて」を参照すること。

以下の項で構成される。

  • 基本のマルチメディア ストリーミング インターフェイス
  • DirectDraw ストリーミング インターフェイス
  • オーディオ ストリーミング インターフェイス
  • DirectShow マルチメディア ストリーミング インターフェイス

基本のマルチメディア ストリーミング インターフェイス

基本のマルチメディア ストリーミング インターフェイスは、マルチメディア ストリームにアクセスするための 1 つのプログラム手段である。ただし、基本インターフェイスを使って特定タイプのデータにアクセスする場合、データを制御できる範囲がある程度制限される可能性がある。したがって、メディア開発者は、メディア タイプ固有の能力をより強力に制御するため、これらのインターフェイスを基に、派生インターフェイスを作成しなければならない。

IMultiMediaStream
最上位レベルのマルチメディア ストリーム オブジェクトへのアクセス方法を定義する。このオブジェクトは、ほかのストリーム オブジェクトを含み、それらのオブジェクトへのアクセスを提供する。IMultiMediaStream には、ストリームの総時間幅を確認し、ストリーム内のシークを行うメソッドだけでなく、個々のストリームを列挙または取得するメソッドも用意されている。
IMediaStream
汎用のストリーム オブジェクトを定義する。このインターフェイスのメソッドを使用して、ストリームへのポインタを取得し、ストリームに関する情報を取得し、ストリーム データからサンプルを作成する。また、共有ストリーム サンプルを作成することもできる。共有ストリーム サンプルとは、サンプルのデータを複製せずに複数のストリームからアクセスできるサンプルである。
IStreamSample
個々のストリーム サンプルの動作を制御する。サンプルを作成したストリームを取得し、サンプルの開始タイム、終了タイム、および完了状態を確認し、(Update メソッドを通じて) サンプル自体にユーザー定義関数を実行することができる。通常、Update メソッドでは、ビデオ データであればレンダリングし、オーディオ データであれば再生するなど、適切な方法でサンプル データが処理される。

DirectDraw ストリーミング インターフェイス

ストリーム内で Microsoft® DirectDraw® がサポートするビデオ フォーマットを使う場合には、以下のインターフェイスを使用すると、汎用の基本インターフェイスより強力にデータを制御できる。

IDirectDrawMediaStream
メディア ストリームに関連付けられたストリーム フォーマットおよび DirectDraw オブジェクトを設定および取得する。このインターフェイスは IMediaStream から派生する。このインターフェイスを使用して、ビデオ サンプルを作成することもできる。
IDirectDrawStreamSample
このインターフェイスを使用すると、DirectDraw サーフェスにビデオ サンプルをアタッチできる。このインターフェイスは IStreamSample インターフェイスから派生する。レンダリングしやすくするため、アタッチされたサーフェスそれぞれにクリッピング矩形が含まれる。

オーディオ ストリーミング インターフェイス

IAudioMediaStream
オーディオ メディア ストリームを制御する。このインターフェイスは、IMediaStream インターフェイスを継承し、1 つ以上の IAudioStreamSample オブジェクトを作成するために使用される。また、ストリーム データの現在のフォーマットを設定および取得するためにも使用される。
IAudioStreamSample
基盤となる IAudioData データ オブジェクトから情報を取得する。
IMemoryData
オーディオ データ オブジェクト上のメモリ データを設定および取得するメソッドが含まれる。オーディオ データ オブジェクトは、ストリーム サンプルがアクセスする、基盤となるデータを提供するものである。このインターフェイスは、メモリ バッファを初期化し、実際にオブジェクト内にあるオーディオ データの量を設定する手段を提供する。また、IMemoryData::GetInfo メソッドを使用すると、オーディオ メモリ データを取得できる。
IAudioData
アプリケーションから、オーディオ ストリームから参照される、基盤となるオーディオ データを設定および取得するためのメソッドを提供する。オーディオ データのフォーマットは、WAVEFORMATEX 構造体に設定される。

DirectShow マルチメディア ストリーミング インターフェイス

以下のインターフェイスは、マルチメディア ストリーム開発者に Microsoft® DirectShow® の機能を公開する。アプリケーション開発者は、アプリケーション内で IAMMultiMediaStream インターフェイスだけを実装しなければならない。ほかの 2 つのインターフェイスは、DirectShow が内部的に使用する。

IAMMultiMediaStream
ストリームおよび DirectShow フィルタ グラフ間の接続を制御する。このインターフェイスは、フィルタ グラフをインスタンス化し、DirectShow がサポートするメディア ファイルを開き、再生用の適切なフィルタ グラフを生成するメソッドを提供する。クラス識別子 CLSID_ActiveMovieMMStream は、このインターフェイスをサポートする。
IAMMediaStream
マルチメディア ストリームおよび DirectShow フィルタ グラフ間の接続の内部的なネゴシエーションを処理する。このインターフェイスは、IMediaStream インターフェイスから派生した DirectShow 固有のインターフェイスである。アプリケーションからこのインターフェイスを使用または実装してはならない。


マルチメディア ストリーミング リファレンス

この項には、すべてのマルチメディア ストリーミング インターフェイスおよびそのメソッドのリファレンス エントリを、Microsoft® DirectShow® がサポートするものも含めて記載する。また、インターフェイスが使用するマルチメディア ストリーミング データ タイプの一覧、およびメソッドが返すエラー コードと成功コードの一覧も記載する。

マルチメディア ストリーミング インターフェイス

  • IAMMediaStream
  • IAMMediaTypeSample
  • IAMMediaTypeStream
  • IAMMultiMediaStream
  • IAudioData
  • IAudioMediaStream
  • IAudioStreamSample
  • IDirectDrawMediaStream
  • IDirectDrawStreamSample
  • IMediaStream
  • IMemoryData
  • IMultiMediaStream
  • IStreamSample

データ タイプとリターン コード

  • マルチメディア ストリーミング データ タイプ
  • マルチメディア ストリーミングのエラー コードと成功コード


IAMMediaStream インターフェイス

IAMMediaStream インターフェイスは、マルチメディア ストリーミングを使用するアプリケーションでの Microsoft® DirectShow® フィルタとフィルタ グラフとの内部的な接続を処理する。このインターフェイスを使用すると、ソースからアプリケーションに渡されるデータの転送と変換が自動的にネゴシエートされ、データ転送、データ変換、および実際のデータ レンダリングやファイル格納を処理するコードを作成せずに、簡単にデータを再生できる。このインターフェイスは、データのアクセスと制御のために、均一で理解しやすい手段を提供する。

このインターフェイスは、アプリケーション開発者による実装または使用を目的としたものではない。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMMediaStream メソッド | 説明
Initialize | 指定されたストリーム タイプおよび目的 ID を持つ新しいメディア ストリームを作成および初期化する。
SetState | フィルタの状態を設定する。
JoinAMMultiMediaStream | 指定されたメディア ストリームを現在のマルチメディア ストリームに追加する。IAMMultiMediaStream::AddMediaStream メソッドはこのメソッドを呼び出す。
JoinFilter | 基盤となるフィルタ グラフ内のメディア ストリーム フィルタにメディア ストリームを接続する。
JoinFilterGraph | メディア ストリーム フィルタをフィルタ グラフに接続する。

IAMMediaStream::Initialize

IAMMediaStream インターフェイス

指定されたストリーム タイプおよび目的 ID を持つ新しいメディア ストリームを作成および初期化する。

構文

HRESULT Initialize(
    IUnknown *pSourceObject,
    DWORD dwFlags,
    REFMSPID PurposeID,
    STREAM_TYPE StreamType
    );

パラメータ

pSourceObject
[in] IUnknown ソース オブジェクトへのポインタ。
dwFlags
[in] メディア ストリームの動作を修正する、以下の値を 1 つ以上組み合わせた値。
AMMSF_ADDDEFAULTRENDERER | デフォルトのレンダラを追加する。
AMMSF_CREATEPEER | pStreamObject と同じオブジェクトに基づくピア ストリームを作成する。
AMMSF_STOPIFNOSAMPLES | サンプルが 1 つも作成されていない場合、または最後のサンプルが削除された場合には、ストリームを終了する。
AMMSF_NOSTALL | Update が呼び出されなくてもストリームを実行する。
PurposeID
[in] 新しいメディア ストリームの目的 ID。
StreamType
[in] 新しいメディア ストリームのメディア タイプを指定する STREAM_TYPE 列挙値。

戻り値

成功した場合は、S_OK を返す。無効な必須パラメータがある場合は、E_POINTER を返す。

注意

dwFlags に AMMSF_ADDDEFAULTRENDERER を指定すると、指定された目的 ID のデフォルト レンダラが作成される (可能な場合)。現時点では、Microsoft® DirectSound® を使用するオーディオのデフォルト レンダラのみがサポートされる。この場合、pStreamObject パラメータは NULL である必要があり、IMultiMediaStream::GetMediaStream メソッドまたは IMultiMediaStream::EnumMediaStreams メソッドの呼び出しではストリームが認識されない。

dwFlags に AMMSF_CREATEPEER を指定すると、pStreamObject を使用してメディア ストリームが作成され、そのメディア ストリームが現在のマルチメディア ストリームに追加される。pStreamObject パラメータはストリーム タイプによって異なる。通常、pStreamObject には IMediaStream オブジェクトへのポインタを指定できる。この場合、サンプルと同じ目的 ID およびフォーマットを持つストリームが作成される。IDirectDraw ストリームの場合には、IDirectDraw オブジェクトへのポインタも指定できる。

dwFlags に AMMSF_STOPIFNOSAMPLES を指定すると、ストリームが終了される。

フラグが 1 つもセットされていない場合、pStreamObject は次のいずれかの値をとる。
IAMMediaStream オブジェクト | この場合、このストリームはマルチメディア ストリーム内のストリームに追加される。
NULL | この場合、デフォルトの IMediaStream オブジェクトが、基盤となるデフォルトのオブジェクトを持つストリームに追加される (必要な場合)。
基盤となるオブジェクトへのポインタ | このポインタを使用して、デフォルト ストリームが構築される。ビデオ ストリームの場合には、IDirectDraw ポインタの可能性がある。

IAMMediaStream::JoinAMMultiMediaStream

IAMMediaStream インターフェイス

指定されたメディア ストリームを現在のマルチメディア ストリームに追加する。IAMMultiMediaStream::AddMediaStream メソッドはこのメソッドを呼び出す。

構文

HRESULT JoinAMMultiMediaStream(
    IAMMultiMediaStream *pAMMultiMediaStream
    );

パラメータ

pAMMultiMediaStream
[in] 現在のメディア ストリームを追加する IAMMultiMediaStream オブジェクトへのポインタ。

戻り値

成功した場合は、S_OK を返す。メディア ストリームに既に割り当て済みのストリーム サンプルがある場合は、MS_E_SAMPLEALLOC を返す。

注意

提供するマルチメディア ストリームの参照カウントは、作成時に処理されているので、インクリメントしないこと。

アプリケーションからこのメソッドを呼び出さないこと。

IAMMediaStream::JoinFilter

IAMMediaStream インターフェイス

基盤となるフィルタ グラフ内のメディア ストリーム フィルタにメディア ストリームを接続する。

構文

HRESULT JoinFilter( );

戻り値

成功した場合は、S_OK を返す。

注意

指定するメディア ストリーム フィルタの参照カウントはインクリメントしないこと。

アプリケーションからこのメソッドを呼び出さないこと。

IAMMediaStream::JoinFilterGraph

IAMMediaStream インターフェイス

メディア ストリーム フィルタをフィルタ グラフに接続する。

構文

HRESULT JoinFilterGraph(
    IFilterGraph *pGraph
    );

パラメータ

pGraph
[in] 指定されたフィルタ グラフに追加する現在のメディア ストリーム フィルタへのポインタ。

戻り値

成功した場合は、S_OK を返す。pGraph が NULL の場合は、E_POINTER を返す。

注意

指定するフィルタ グラフの参照カウントはインクリメントしないこと。

アプリケーションからこのメソッドを呼び出さないこと。

IAMMediaStream::SetState

IAMMediaStream インターフェイス

フィルタの状態を設定する。

構文

HRESULT SetState(
    FILTER_STATE State
    );

パラメータ

State
[in] フィルタの状態を設定する。状態は FILTER_STATE 列挙型で指定される。

戻り値

成功した場合は、S_OK を返す。State パラメータが無効な場合は、E_INVALIDARG を返す。

注意

アプリケーションからこのメソッドを呼び出さないこと。


IAMMediaTypeSample インターフェイス

このインターフェイスは、任意のメディア タイプのストリーム サンプルを操作するメソッドを提供する。このインターフェイスを公開するサンプルを作成するには、IAMMediaTypeStream::CreateSample メソッドを呼び出す。

このインターフェイスは、IStreamSample インターフェイスを継承する。

このインターフェイスのメソッドは、IMediaSample インターフェイスのメソッドに相当する。ただし、IAMMediaTypeSample には SetPointer メソッドと GetPointer メソッドが加わっている。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IStreamSample メソッド | 説明
GetMediaStream | 現在のサンプルを作成したメディア ストリーム オブジェクトへのポインタを取得する。
GetSampleTimes | 現在のサンプルの開始タイムと終了タイムを取得する。
SetSampleTimes | 現在のサンプルの開始タイムと終了タイムを設定する。
Update | 現在のサンプルを同期または非同期に更新する。
CompletionStatus | 現在のサンプルに行われた最後の非同期更新の状態を取得する。更新が完了していない場合には強制終了できる。
IAMMediaTypeSample メソッド | 説明
SetPointer | メディア サンプルのメモリ バッファへのポインタを設定する。
GetPointer | バッファのメモリへの読み取り/書き込みポインタを取得する。
GetSize | バッファのデータ領域のサイズ (バイト単位) を取得する。
GetTime | このサンプルが開始および停止すべきストリーム タイムを取得する。
SetTime | このサンプルが開始および停止すべきストリーム タイムを設定する。
IsSyncPoint | サンプルの始まりが同期ポイントかどうかを判断する。
SetSyncPoint | このサンプルの始まりが同期ポイントかどうかを指定する。
IsPreroll | このサンプルがプリロールの一部かどうかを判断する。
SetPreroll | これがプリロール サンプルかどうかを指定する。
GetActualDataLength | サンプルのデータ長 (バイト単位) を取得する。
SetActualDataLength | サンプルのデータ長を設定する。
GetMediaType | サンプルのメディア タイプを取得する。
SetMediaType | サンプルのメディア タイプを設定する。
IsDiscontinuity | このサンプルがデータ ストリームの不連続性を表しているかどうかを判断する。
SetDiscontinuity | 不連続性のプロパティを設定する。
GetMediaTime | このサンプルのメディア タイム スタンプを取得する。
SetMediaTime | このサンプルのメディア タイム スタンプを設定する。

IAMMediaTypeSample::GetActualDataLength

IAMMediaTypeSample インターフェイス

サンプルのデータ長 (バイト単位) を取得する。

構文

long GetActualDataLength(void);

戻り値

サンプルのデータ長 (バイト単位) を返す。

IAMMediaTypeSample::GetMediaTime

IAMMediaTypeSample インターフェイス

サンプルのメディア タイム スタンプを取得する。

構文

HRESULT GetMediaTime(
LONGLONG *pTimeStart,
LONGLONG *pTimeEnd
);

パラメータ

pTimeEnd
[out] メディアの開始タイムを受け取る変数へのポインタ。
pTimeStart
[out] メディアの終了タイムを受け取る変数へのポインタ。

戻り値

次のいずれかの値を返す。

S_OK | 成功。
VFW_E_MEDIA_TIME_NOT_SET | このサンプルにはメディア タイム スタンプが設定されていない。

IAMMediaTypeSample::GetMediaType

IAMMediaTypeSample インターフェイス

サンプルのメディア タイプを取得する。フォーマットが直前のサンプルから変わっていない場合には、サンプルにメディア タイプが付いていない可能性がある。

構文

HRESULT GetMediaType(
    AM_MEDIA_TYPE **ppMediaType
);

パラメータ

ppMediaType
AM_MEDIA_TYPE 構造体を受け取るポインタのアドレス。

戻り値

次のいずれかの値を返す。

E_OUTOFMEMORY | メモリ不足。
S_FALSE | フォーマットが直前のサンプルから変わっていない。
S_OK | 成功。

IAMMediaTypeSample::GetPointer

IAMMediaTypeSample インターフェイス

バッファのメモリへの読み取り/書き込みポインタを取得する。

構文

HRESULT GetPointer(
    BYTE **ppBuffer
);

パラメータ

ppBuffer
[out] バッファへのポインタのアドレス。

戻り値

S_OK を返す。

IAMMediaTypeSample::GetSize

IAMMediaTypeSample インターフェイス

バッファのデータ領域のサイズ (バイト単位) を取得する。

構文

long GetSize(void);

戻り値

バッファのデータ領域のサイズ (バイト単位) を返す。

IAMMediaTypeSample::GetTime

IAMMediaTypeSample インターフェイス

サンプルが開始および停止すべきストリーム タイムを取得する。

構文

HRESULT GetTime(
REFERENCE_TIME *pTimeStart,
REFERENCE_TIME *pTimeEnd
);

パラメータ

pTimeStart
[out] 開始タイムを受け取る変数へのポインタ。
pTimeEnd
[out] 終了タイムを受け取る変数へのポインタ。サンプルに終了タイムがない場合、この値には開始タイムに 1 加えた値が設定される。

戻り値

次のいずれかの値を返す。

S_OK | 成功。
VFW_E_SAMPLE_TIME_NOT_SET | サンプルにタイム スタンプがない。
VFW_S_NO_STOP_TIME | サンプルには有効な開始タイムがあるが、終了タイムがない。

IAMMediaTypeSample::IsDiscontinuity

IAMMediaTypeSample インターフェイス

このサンプルがデータ ストリームの不連続性を表しているかどうかを判断する。

構文

HRESULT IsDiscontinuity(void);

戻り値

サンプルが不連続な場合は、S_OK を返す。それ以外の場合は、S_FALSE を返す。

IAMMediaTypeSample::IsPreroll

IAMMediaTypeSample インターフェイス

このサンプルがプリロールの一部かどうかを判断する。プリロール サンプルを表示してはならない。

構文

HRESULT IsPreroll(void);

戻り値

サンプルがプリロール サンプルである場合は、S_OK を返す。それ以外の場合は、S_FALSE を返す。

IAMMediaTypeSample::IsSyncPoint

IAMMediaTypeSample インターフェイス

サンプルの始まりが同期ポイントかどうかを判断する。

構文

HRESULT IsSyncPoint(void);

戻り値

サンプルの始まりが同期ポイントである場合は、S_OK を返す。それ以外の場合は、S_FALSE を返す。

IAMMediaTypeSample::SetActualDataLength

IAMMediaTypeSample インターフェイス

サンプルのデータ長を設定する。

構文

HRESULT SetActualDataLength(
    long lActual
);

パラメータ

lActual
メディア サンプルのデータ長 (バイト単位)。

戻り値

次のいずれかの値を返す。
S_OK | 成功。
VFW_E_BUFFER_OVERFLOW | バッファの大きさが足りない。

IAMMediaTypeSample::SetDiscontinuity

IAMMediaTypeSample インターフェイス

不連続性のプロパティを設定する。

構文

HRESULT SetDiscontinuity(
    BOOL bDiscontinuity
);

パラメータ

bDiscontinuity
このサンプルが不連続かどうかを指定する値。サンプルが直前のサンプルと不連続な場合にはこの値を TRUE に設定し、それ以外の場合は FALSE に設定する。

戻り値

S_OK を返す。

IAMMediaTypeSample::SetMediaTime

IAMMediaTypeSample インターフェイス

このサンプルのメディア タイム スタンプを設定する。

構文

HRESULT SetMediaTime(
LONGLONG *pTimeStart,
LONGLONG *pTimeEnd
);

パラメータ

pTimeEnd
[in] メディアの開始タイムが格納された変数へのポインタ。
pTimeStart
[in] メディアの終了タイムが格納された変数へのポインタ。

戻り値

S_OK を返す。

IAMMediaTypeSample::SetMediaType

IAMMediaTypeSample インターフェイス

サンプルのメディア タイプを設定する。

構文

HRESULT SetMediaType(
    AM_MEDIA_TYPE *pMediaType
);

パラメータ

pMediaType
メディア タイプを記述する AM_MEDIA_TYPE 構造体へのポインタ。

戻り値

次のいずれかの値を返す。

E_OUTOFMEMORY | メモリ不足。
S_OK | 成功。

IAMMediaTypeSample::SetPointer

IAMMediaTypeSample インターフェイス

メディア サンプルのメモリ バッファへのポインタを設定する。

構文

HRESULT SetPointer(
    BYTE *pBuffer,
    long lSize
);

パラメータ

pBuffer
[in] 呼び出し元で割り当てられたメモリ バッファへのポインタ、または NULL。
lSize
[in] バッファのサイズ (バイト単位)。

戻り値

次のいずれかの HRESULT 値を返す。

S_OK | 成功。
E_OUTOFMEMORY | メモリ不足。

注意

pBuffer パラメータの値が NULL の場合、メソッドは lSize パラメータの値と等しいサイズ (バイト単位) のメモリ ブロックを割り当てる。メモリが初期化されているという保障はない。

IAMMediaTypeSample::SetPreroll

IAMMediaTypeSample インターフェイス

これがプリロール サンプルかどうかを指定する。プリロール サンプルを表示してはならない。

構文

HRESULT SetPreroll(
    BOOL bIsPreroll
);

パラメータ

bIsPreroll
サンプルがプリロール サンプルかどうかを指定するブール値。TRUE の場合、このサンプルはプリロール用であり、表示してはならない。

戻り値

S_OK を返す。

IAMMediaTypeSample::SetSyncPoint

IAMMediaTypeSample インターフェイス

このサンプルの始まりが同期ポイントかどうかを指定する。

構文

HRESULT SetSyncPoint(
    BOOL bIsSyncPoint
);

パラメータ

bIsSyncPoint
このサンプルの始まりが同期ポイントかどうかを指定するブール値。TRUE の場合、サンプルの始まりは同期ポイントである。

戻り値

S_OK を返す。

IAMMediaTypeSample::SetTime

IAMMediaTypeSample インターフェイス

サンプルが開始および停止すべきストリーム タイムを設定する。

構文

HRESULT SetTime(
REFERENCE_TIME *pTimeStart,
REFERENCE_TIME *pTimeEnd
);

パラメータ

pTimeStart
[in] 開始タイムが格納された変数へのポインタ。
pTimeEnd
[in] 終了タイムが格納された変数へのポインタ。

戻り値

S_OK を返す。


IAMMediaTypeStream インターフェイス

このインターフェイスは、任意のメディア タイプのマルチメディア ストリームを作成するメソッドを提供する。作成するマルチメディア ストリームのフォーマットが、ほかの Microsoft® DirectShow® マルチメディア ストリーミング インターフェイスでサポートされていない場合は、このインターフェイスを使用する。

このインターフェイスは、IMediaStream インターフェイスを継承する。

注意 : ビデオ ストリームには、このインターフェイスの代わりに IDirectDrawMediaStream インターフェイスを使用する。オーディオ ストリームには、IAudioMediaStream インターフェイスを使用する。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IMediaStream メソッド | 説明
GetMultiMediaStream | 指定されたメディア ストリームが格納されたマルチメディア ストリームへのポインタを取得する。
GetInformation | ストリームの目的 ID とメディア タイプを取得する。
SetSameFormat | メディア ストリームを直前のストリームと同じフォーマットに設定する。
AllocateSample | 現在のメディア ストリームに新しいストリーム サンプル オブジェクトを割り当てる。
CreateSharedSample | 既存サンプルと同じバッキング オブジェクトを共有する新しいストリーム サンプルを作成する。
SendEndOfStream | 現在のストリームを強制終了する。現在のストリームが書き込み可能でない場合、このメソッドの呼び出しは効果がない。
IAMMediaTypeStream メソッド | 説明
GetFormat | ストリームのフォーマットを取得する。
SetFormat | ストリームのフォーマットを設定する。
CreateSample | ストリーム サンプルを作成し、オプションでサンプル バッファを指定する。
GetStreamAllocatorRequirements | ストリームのアロケータ要件を取得する。現在、このメソッドは実装されていない。
SetStreamAllocatorRequirements | ストリームのアロケータ要件を設定する。現在、このメソッドは実装されていない。

IAMMediaTypeStream::CreateSample

IAMMediaTypeStream インターフェイス

ストリーム サンプルを作成し、オプションでサンプル バッファを指定する。

構文

HRESULT CreateSample(
    long lSampleSize,
    BYTE *pbBuffer,
    DWORD dwFlags,
    IUnknown *pUnkOuter,
    IAMMediaTypeSample **ppAMMediaTypeSample
);

パラメータ

lSampleSize
[in] サンプルのサイズ。
pbBuffer
[in] [optional] サンプル データが格納されたバイト配列へのポインタ、または NULL。
dwFlags
[in] 予約済み。
pUnkOuter
[in] [optional] ストリーム サンプルを集成するオブジェクトの IUnknown インターフェイスへのポインタ。
ppAMMediaTypeSample
[in] 作成されたサンプルへのポインタを受け取る IAMMediaTypeSample インターフェイス ポインタのアドレス。

戻り値

次のいずれかの値を返す。

E_OUTOFMEMORY | メモリ不足。
E_POINTER | NULL ポインタ引数。
S_OK | 成功。

注意

pUnkOuter が NULL でない場合、新しいストリーム サンプルは指定されたオブジェクトに集成される。サンプルを受け取るフィルタは、集成したオブジェクトでサポートされるインターフェイスを、そのサンプルに照会できる。

IAMMediaTypeStream::GetFormat

IAMMediaTypeStream インターフェイス

ストリームのフォーマットを取得する。

構文

HRESULT GetFormat(
AM_MEDIA_TYPE *pMediaType,
DWORD dwFlags
);

パラメータ

pMediaType
[out] ストリームのフォーマットを受け取る AM_MEDIA_TYPE 構造体へのポインタ。
dwFlags
[in] 予約済み。

戻り値

次のいずれかの値を返す。

MS_E_NOSTREAM | このオブジェクトにはストリームが関連付けられていない。
S_OK | 成功。

IAMMediaTypeStream::GetStreamAllocatorRequirements

IAMMediaTypeStream インターフェイス

ストリームのアロケータ要件を取得する。現在、このメソッドは実装されていない。

構文

HRESULT GetStreamAllocatorRequirements(
ALLOCATOR_PROPERTIES *pProps
);

パラメータ

pProps
[out] ストリームのアロケータ要件を受け取る ALLOCATOR_PROPERTIES 構造体へのポインタ。

戻り値

E_FAIL を返す。

IAMMediaTypeStream::SetFormat

IAMMediaTypeStream インターフェイス

ストリームのフォーマットを設定する。

構文

HRESULT SetFormat(
AM_MEDIA_TYPE *pMediaType,
DWORD dwFlags
);

パラメータ

pMediaType
[in] ストリームのフォーマットが格納された AM_MEDIA_TYPE 構造体へのポインタ。
dwFlags
[in] 予約済み。

戻り値

次のいずれかの値を返す。

MS_E_SAMPLEALLOC | ストリームが既に別のメディア タイプのサンプルを割り当てた。
S_OK | 成功。

IAMMediaTypeStream::SetStreamAllocatorRequirements

IAMMediaTypeStream インターフェイス

ストリームのアロケータ要件を設定する。現在、このメソッドは実装されていない。

構文

HRESULT SetStreamAllocatorRequirements(
ALLOCATOR_PROPERTIES *pProps
);

パラメータ

pProps
[in] ストリームのアロケータ要件が格納された ALLOCATOR_PROPERTIES 構造体へのポインタ。

戻り値

E_FAIL を返す。


IAMMultiMediaStream インターフェイス

IAMMultiMediaStream インターフェイスは、マルチメディア ストリーム開発者に Microsoft® DirectShow® の機能を公開する。このインターフェイスのメソッドを使用すると、フィルタ グラフを自動生成し、受信データを再生またはキャプチャするためにファイルまたはモニカを開き、所定のフィルタ グラフをレンダリングすることができる。

アプリケーションで DirectShow のメディア タイプに対応するマルチメディア ストリーム ベースのサポートを提供するには、このインターフェイスを実装する。

マルチメディア ストリーミング アプリケーションで、DirectShow がサポートするメディア再生を制御するには、このインターフェイスを使用する。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAMMultiMediaStream メソッド | 説明
Initialize | ストリーム タイプを設定する。pFilterGraph パラメータが NULL でない場合には、渡されたフィルタ グラフをストリームに使用する。
GetFilterGraph | 関連付けられたフィルタ グラフの IGraphBuilder インターフェイスを取得する。
GetFilter | 現在のフィルタ グラフから指定されたフィルタを取得する。
AddMediaStream | 現在のフィルタ グラフに指定されたメディア ストリームを追加する。
OpenFile | 指定されたメディア ファイルに対応するフィルタ グラフを開き、自動作成する。ファイル フォーマットが DirectShow でサポートされていない場合、メソッドは何も実行しない。
OpenMoniker | ファイル モニカまたはデバイス モニカを開く。メディア タイプが DirectShow でサポートされていれば、このモニカからメディア データを読み取ることができる。
Render | 現在のフィルタ グラフをレンダリングする。

IAMMultiMediaStream::AddMediaStream

IAMMultiMediaStream インターフェイス

現在のフィルタ グラフに指定されたメディア ストリームを追加する。

構文

HRESULT AddMediaStream(
    IUnknown *pStreamObject,
    const MSPID *pPurposeID,
    DWORD dwFlags,
    IMediaStream **ppNewStream
    );

パラメータ

pStreamObject
[in] 現在のフィルタ グラフに追加するメディア ストリームまたは基盤となるストリーム オブジェクトを指す IUnknown インターフェイスへのポインタ。
pPurposeID
[in] 新しく追加するメディア ストリームの目的 ID へのポインタ。
dwFlags
[in] メディア ストリームの動作を修正する、以下の値を 1 つ以上組み合わせた値。
AMMSF_ADDDEFAULTRENDERER | デフォルトのレンダラを追加する。
AMMSF_CREATEPEER | pStreamObject と同じオブジェクトに基づくピア ストリームを作成する。
AMMSF_STOPIFNOSAMPLES | サンプルが 1 つも作成されていない場合、または最後のサンプルが削除された場合には、ストリームを終了する。
AMMSF_NOSTALL | Update が呼び出されなくてもストリームを実行する。
ppNewStream
[out] IMediaStream インターフェイスへのポインタのアドレス。このポインタに、新しく追加されたメディア ストリームのアドレスを受け取る。このパラメータは省略可能。

戻り値

次のいずれかの HRESULT 値を返す。
MS_E_PURPOSEID | 追加するストリームが持つ目的 ID が指定された ID と異なっているか、または指定された目的 ID を持つストリームが既に存在する。
E_POINTER | Null ポインタ引数。
S_OK | 成功。

注意

dwFlags に AMMSF_ADDDEFAULTRENDERER を指定すると、指定された目的 ID に対応するデフォルト レンダラが作成される (可能な場合)。現時点では、DirectSound を使用するオーディオに対応するデフォルト レンダラのみがサポートされる。この場合、pStreamObject パラメータは NULL でなければならない。また、IMultiMediaStream::GetMediaStream メソッドまたは IMultiMediaStream::EnumMediaStreams メソッドの呼び出しでは、ストリームが認識されない。

dwFlags に AMMSF_CREATEPEER を指定すると、pStreamObject を使用してメディア ストリームが作成され、そのメディア ストリームが現在のマルチメディア ストリームに追加される。pStreamObject パラメータはストリーム タイプによって異なる。通常、pStreamObject には IMediaStream オブジェクトへのポインタを指定できる。この場合、サンプルと同じ目的 ID およびフォーマットを持つストリームが作成される。IDirectDraw ストリームの場合には、IDirectDraw オブジェクトへのポインタも指定できる。

dwFlags に AMMSF_STOPIFNOSAMPLES を指定すると、ストリームが終了される。

フラグが 1 つもセットされていない場合、pStreamObject は次のいずれかの値をとる。
IAMMediaStream オブジェクト | この場合、このストリームはマルチメディア ストリーム内のストリームに追加される。
NULL | この場合、デフォルトの IMediaStream オブジェクトが、基盤となるデフォルトのオブジェクトを持つストリームに追加される (必要な場合)。
基盤となるオブジェクトへのポインタ | このポインタを使用して、デフォルト ストリームが構築される。ビデオ ストリームの場合には、IDirectDraw ポインタの可能性がある。

IAMMultiMediaStream::GetFilter

IAMMultiMediaStream インターフェイス

現在のフィルタ グラフから指定されたフィルタを取得する。

構文

HRESULT GetFilter(
    IMediaStreamFilter **ppFilter
    );

パラメータ

ppFilter
[out] IMediaStreamFilter インターフェイスへのポインタのアドレス。このポインタに、現在のフィルタのアドレスを受け取る。

戻り値

成功した場合は、S_OK を返す。NULL の必須パラメータがある場合は、E_POINTER を返す。

IAMMultiMediaStream::GetFilterGraph

IAMMultiMediaStream インターフェイス

関連付けられたフィルタ グラフの IGraphBuilder インターフェイスを取得する。

構文

HRESULT GetFilterGraph(
    IGraphBuilder **ppGraphBuilder
    );

パラメータ

ppGraphBuilder
[out] IGraphBuilder インターフェイスへのポインタのアドレス。このポインタに、現在のフィルタ グラフのアドレスを受け取る。

戻り値

成功した場合は、S_OK を返す。NULL の必須パラメータがある場合は、E_POINTER を返す。

IAMMultiMediaStream::Initialize

IAMMultiMediaStream インターフェイス

ストリーム タイプを設定する。pFilterGraph パラメータが NULL でない場合には、渡されたフィルタ グラフをストリームに使用する。

構文

HRESULT Initialize(
    STREAM_TYPE StreamType,
    DWORD dwFlags,
    IGraphBuilder *pFilterGraph
    );

パラメータ

StreamType
[in] 新しいフィルタ グラフのストリーム タイプを指定する STREAM_TYPE 列挙値。
dwFlags
[in] AMMSF_NOGRAPHTHREAD フラグまたは 0。AMMSF_NOGRAPHTHREAD フラグは、現在のスレッドでフィルタ グラフ オブジェクトを作成することを示す。
pFilterGraph
[in] [optional] 新しいフィルタ グラフのアドレスを受け取る IGraphBuilder インターフェイスへのポインタ。このパラメータは省略可能。後からフィルタ グラフにアクセスする必要がある場合にのみ、有効なポインタを渡す。

戻り値

成功した場合は、S_OK を返す。NULL の必須パラメータがある場合は、E_POINTER を返す。

注意

AMMSF_NOGRAPHTHREAD フラグを安全に使用するには、現在のスレッドが終了するまでアプリケーションがストリーム オブジェクトを解放せず、ウィンドウ メッセージが現在のスレッドで処理されなければならない。

IAMMultiMediaStream::OpenFile

IAMMultiMediaStream インターフェイス

指定されたメディア ファイルに対応するフィルタ グラフを開き、自動作成する。ファイル フォーマットが DirectShow でサポートされていない場合、メソッドは何も実行しない。

構文

HRESULT OpenFile(
    LPCWSTR pszFileName,
    DWORD dwFlags
    );

パラメータ

pszFileName
[in] 開くファイルの名前へのポインタ。
dwFlags
[in] フィルタ グラフが指定されたファイルをレンダリングする方法を修正する値。この値は、以下のフラグを 1 つ以上組み合わせたものである。
AMMSF_RENDERTOEXISTING | 既存のストリームだけにレンダリングする。
AMMSF_RENDERALLSTREAMS | 既存のメディア ストリームを持たないストリームを含めて、すべてのストリームをレンダリングする。
AMMSF_NORENDER | ファイルを開くが、ストリームのレンダリングはしない。このフラグは常に AMMSF_RUN フラグと共に指定しなければならない。
AMMSF_NOCLOCK | クロックのないストリームを実行する。
AMMSF_RUN | ストリームを実行状態に切り替える。

戻り値

次のいずれかの値を返す。
E_INVALIDARG | dwFlags パラメータが無効。
E_POINTER | このメソッドが無効なポインタにアクセスしようとした。
S_OK | 成功。

注意

AMMSF_RENDERALLSTREAMS フラグがオンの場合、ビデオおよびオーディオ用のデフォルト レンダリング フィルタがなければ作成する。ただし、これらのデフォルト フィルタは、IStreamSample::GetMediaStream メソッドでアクセスすることができない。

IAMMultiMediaStream::OpenMoniker

IAMMultiMediaStream インターフェイス

ファイル モニカまたはデバイス モニカを開く。モニカが DirectShow でサポートされていれば、このモニカからメディア データを読み取ることができる。

構文

HRESULT OpenMoniker(
    IBindCtx *pCtx,
    IMoniker *pMoniker,
    DWORD dwFlags
    );

パラメータ

pCtx
[in] モニカに関連付けられたバインド コンテキストへのポインタ。
pMoniker
[in] 開くモニカを指定する IMoniker インターフェイスへのポインタ。
dwFlags
[in] フィルタ グラフが指定されたファイルをレンダリングする方法を修正する値。この値は、以下のフラグを 1 つ以上組み合わせたものである。
AMMSF_RENDERTOEXISTING | 既存のストリームだけにレンダリングする。
AMMSF_RENDERALLSTREAMS | 既存のメディア ストリームを持たないストリームを含めて、すべてのストリームをレンダリングする。
AMMSF_NORENDER | ファイルを開くが、ストリームのレンダリングはしない。このフラグは常に AMMSF_RUN フラグと共に指定しなければならない。
AMMSF_NOCLOCK | クロックのないストリームを実行する。
AMMSF_RUN | ストリームを実行状態に切り替える。

戻り値

成功した場合は、S_OK を返す。dwFlags パラメータが無効な場合は、E_INVALIDARG を返す。

IAMMultiMediaStream::Render

IAMMultiMediaStream インターフェイス

現在のフィルタ グラフをレンダリングする。

構文

HRESULT Render(
DWORD dwFlags
    );

パラメータ

dwFlags
[in] フィルタ グラフが現在のマルチメディア ストリームをレンダリングする方法を指定する値。現在、この値は AMMSF_NOCLOCK でなければならない。

戻り値

成功した場合は、S_OK を返す。dwFlags パラメータが無効な場合は、E_INVALIDARG を返す。

注意

このメソッドは、各ソース ストリームを STREAMTYPE_WRITE タイプのストリームにレンダリングする。このメソッドは繰り返し呼び出すことができる (たとえばソース ストリームが追加されるたびに呼び出すなど)。ストリームは実行状態に切り替わらない。ストリームを実行状態に切り替えるには、このメソッドの呼び出し後に IMultiMediaStream::SetState メソッドを使用する。

AMMSF_RENDERALLSTREAMS フラグがオンの場合、ビデオおよびオーディオ用のデフォルト レンダリング ストリームがなければ作成される。


IAudioData インターフェイス

IAudioData インターフェイスは、アプリケーションから、オーディオ ストリームから参照される、基盤となるオーディオ データを設定および取得するためのメソッドを提供する。オーディオ データのフォーマットは、WAVEFORMATEX 構造体に設定される。

このインターフェイスは、オーディオ ストリーム サンプル オブジェクトからアクセスされる、基盤となるオーディオ データ オブジェクト上に実装する。

オーディオ ストリームが参照する基盤となるデータ オブジェクトに関する情報を、アプリケーションから設定および取得するには、このインターフェイスを使用する。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAudioData メソッド | 説明
GetFormat | 現在のデータ フォーマットを取得する。
SetFormat | 現在のデータ フォーマットを設定する。

IAudioData::GetFormat

IAudioData インターフェイス

現在のデータ フォーマットを取得する。

構文

HRESULT GetFormat(
    WAVEFORMATEX *pWaveFormatCurrent
    );

パラメータ

pWaveFormatCurrent
[out] 現在のデータ フォーマットが格納された WAVEFORMATEX 構造体へのポインタ。

戻り値

成功した場合は、S_OK を返す。ポインタが無効な場合は、E_POINTER を返す。

注意

現在、Microsoft® DirectShow® は PCM ウェーブ データのみをサポートする。

参照

IAudioData::SetFormat

IAudioData::SetFormat

IAudioData インターフェイス

現在のデータ フォーマットを設定する。

構文

HRESULT SetFormat(
    const WAVEFORMATEX *lpWaveFormat
    );

パラメータ

lpWaveFormat
[in] 現在のデータ フォーマットを格納する WAVEFORMATEX 構造体へのポインタ。

戻り値

次のいずれかの HRESULT 値を返す。
E_POINTER | 無効なポインタ引数。
E_INVALIDARG | 無効なフォーマット。
S_OK | 成功。

参照

IAudioData::GetFormat


IAudioMediaStream インターフェイス

IAudioMediaStream インターフェイスは、ストリームのフォーマットを設定および取得するメソッドを提供することにより、オーディオ メディア ストリームを制御する。このインターフェイスは、IMediaStream インターフェイスを継承し、1 つ以上の IAudioStreamSample オブジェクトを作成するために使用される。また、ストリーム データの現在のフォーマットを設定および取得することもできる。

現在、このインターフェイスは PCM フォーマットのオーディオ データ用のみに定義されている。

オーディオ ストリーミング インターフェイスを実装するサンプル コードについては、「マルチメディア ストリーミングのサンプル コード」を参照すること。

ビデオ同様、オーディオはその内容を記述するコンテナ オブジェクトに格納される。オブジェクトからオーディオのストリーミングを制御する必要がある場合は、このインターフェイスを実装する。

アプリケーションでオーディオを生成するには、このインターフェイスを使用する。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAudioMediaStream メソッド | 説明
GetFormat | ストリーム データの現在のフォーマットを取得する。
SetFormat | ストリームのフォーマットを設定する。
CreateSample | このストリームで使用するオーディオ ストリーム サンプルを作成する。

IAudioMediaStream::CreateSample

IAudioMediaStream インターフェイス

指定されたストリームで使用するオーディオ ストリーム サンプルを作成する。

構文

HRESULT CreateSample(
    IAudioData *pAudioData,
    DWORD dwFlags,
    IAudioStreamSample **ppSample
    );

パラメータ

pAudioData
[in] IAudioData コンテナへのポインタ。IAudioData オブジェクトは複数のストリームのサンプルから参照できる。
dwFlags
[in] フラグ データ用に予約されている。ゼロでなくてはならない。
ppSample
[out] 新しい IAudioStreamSample インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、S_OK を返す。NULL の必須パラメータがある場合は、E_POINTER を返す。

注意

pAudioData オブジェクトでデータのフォーマットを定義する。

IAudioMediaStream::GetFormat

IAudioMediaStream インターフェイス

ストリーム データの現在のフォーマットを取得する。

構文

HRESULT GetFormat(
    WAVEFORMATEX *pWaveFormatCurrent );

パラメータ

pWaveFormatCurrent
[out] ストリーム データの現在のフォーマットが格納された WAVEFORMATEX 構造体へのポインタ。

戻り値

成功した場合は、S_OK を返す。必須パラメータが NULL の場合は、E_POINTER を返す。

注意

現在、Microsoft® DirectShow® は PCM ウェーブ データのみをサポートする。

IAudioMediaStream::SetFormat

IAudioMediaStream インターフェイス

ストリームのフォーマットを設定する。

構文

HRESULT SetFormat(
const WAVEFORMATEX *lpWaveFormat
    );

パラメータ

lpWaveFormat
[in] ストリーム フォーマット情報が格納された WAVEFORMATEX 構造体へのポインタ。

戻り値

HRESULT 値を返す。この値は、以下の値か、または一覧に示されていないその他の値となる。
MS_E_INCOMPATIBLE | IAudioData オブジェクトのフォーマットがストリームと互換でない。
E_POINTER | Null ポインタ引数。
E_INVALIDARG | 無効な引数。
S_OK | 成功。


IAudioStreamSample インターフェイス

IAudioStreamSample インターフェイスは、基盤となる IAudioData データ オブジェクトから情報を取得する。

オーディオ ストリーミング インターフェイスを実装するサンプル コードについては、「マルチメディア ストリーミングのサンプル コード」を参照すること。

IAudioData オブジェクトのデータにアクセスする必要があるオーディオ ストリーム サンプル オブジェクトには、このインターフェイスを実装する。

アプリケーションからそのオーディオ ストリームに対応する IAudioData オブジェクトのデータにアクセスするには、このインターフェイスを使用する。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IAudioStreamSample メソッド | 説明
GetAudioData | サンプルに関連付けられた IAudioData オブジェクトへのポインタのアドレスを取得する。

IAudioStreamSample::GetAudioData

IAudioStreamSample インターフェイス

サンプルに関連付けられた IAudioData オブジェクトへのポインタのアドレスを取得する。

構文

HRESULT GetAudioData(
  IAudioData **ppAudio );

パラメータ

ppAudio
[out] IAudioData オブジェクトへのポインタのアドレス。

戻り値

成功した場合は、S_OK を返す。パラメータが NULL の場合は、E_POINTER を返す。


IDirectDrawMediaStream インターフェイス

IDirectDrawMediaStream インターフェイスは、Microsoft® DirectDraw® サーフェスに表示されるメディア ストリームを制御する。DirectDraw サーフェスにストリームするには、DirectDraw がビデオ ストリーム フォーマットをサポートしている必要がある。

マルチメディア ストリーミング インターフェイスを実装するサンプル コードについては、「マルチメディア ストリーミングのサンプル コード」を参照すること。

このインターフェイスは、アプリケーション開発者による実装を目的としたものではない。Microsoft® DirectShow® マルチメディア ストリームに追加できる DirectDraw メディア ストリーム上で公開される。

DirectDraw サーフェスにビデオ ストリームを送るには、このインターフェイスを使用する。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IDirectDrawMediaStream メソッド | 説明
GetFormat | 現在のメディア ストリームのフォーマットを取得し、オプションでその望ましいフォーマットも取得する。
SetFormat | 現在のメディア ストリームのフォーマットを設定する。ストリームに既に割り当て済みのサンプルがあり、そのサンプルのフォーマットと指定されたフォーマットが一致しない場合、このメソッドは失敗する。
GetDirectDraw | 現在のメディア ストリームで使用される DirectDraw オブジェクトへのポインタを取得する。
SetDirectDraw | 現在のメディア ストリームの DirectDraw オブジェクトを設定する。
CreateSample | 指定された DirectDraw サーフェス オブジェクトを使用するストリーム サンプルを作成する。
GetTimePerFrame | ビデオ ストリームから得られる 1 秒あたりの平均フレーム数を取得する。

IDirectDrawMediaStream::CreateSample

IDirectDrawMediaStream インターフェイス

指定された DirectDraw サーフェス オブジェクトを使用するストリーム サンプルを作成する。

構文

HRESULT CreateSample(
    IDirectDrawSurface *pSurface,
    const RECT *pRect,
    DWORD dwFlags,
    IDirectDrawStreamSample **ppSample
    );

パラメータ

pSurface
[in] 既存の DirectDraw サーフェスへのポインタ。
pRect
[in] 指定したサーフェスに使用するクリッピング矩形へのポインタ。サーフェス全体を使用するには、このパラメータを NULL に設定する。
dwFlags
[in] レンダリング方式がプログレッシブかどうかを指定するフラグ。プログレッシブ レンダリングを実行するには、この値を DDSFF_PROGRESSIVERENDER に設定する。このフラグをセットした場合、サンプルを更新すると、サンプル データがサーフェスにコピーされる。
ppSample
[out] IDirectDrawStreamSample インターフェイスへのポインタのアドレス。このポインタに、新しく作成されたサンプルのアドレスを受け取る。

戻り値

次のいずれかの値を返す。
DDERR_INVALIDPIXELFORMAT | 指定されたピクセル フォーマットがストリーム フォーマットと互換でない。
DDERR_INVALIDRECT | 指定されたクリッピング矩形が無効。
DDERR_INVALIDSURFACETYPE | 指定されたサーフェスがストリーム フォーマットと互換でない。
E_POINTER | 無効な必須パラメータがある。
MS_E_SAMPLEALLOC | ストリームに既に割り当て済みサンプルがあり、サンプルのフォーマットがサーフェスと一致しない。
S_OK | 成功。

注意

このメソッドは、現在のストリームからサンプルを作成し、そのサンプルをこのサーフェスにアタッチする。

ストリームに割り当て済みのサーフェスがなく、指定されたサーフェスがストリームのフォーマットと一致しない場合、このメソッドはストリームの IDirectDrawMediaStream::SetFormat メソッドを呼び出して 2 つのフォーマットを一致させる。

プログレッシブ レンダリングを実行するには、サンプルを 1 つ作成し、そのサンプルをそれ以降のビデオ フレームに繰り返し使用する。ビデオ デコンプレッサ フィルタは、直前のフレームを部分的に更新するためにこのテクニックを使う。

pRect パラメータは、ストリームのフォーマットと一致していなければならない (「IDirectDrawMediaStream::GetFormat」を参照)。誤まったクリッピング矩形を設定したか、またはクリッピング矩形を設定していない場合、サーフェスとサイズが異なるムービーは再生されない可能性がある。プライマリ サーフェスが使用される場合には、ユーザーがディスプレイ設定を変更するとプライマリ サーフェスのサイズが変わる可能性があるため、クリッピング矩形の使用を推奨する。

IDirectDrawMediaStream::GetDirectDraw

IDirectDrawMediaStream インターフェイス

現在のメディア ストリームで使用される DirectDraw オブジェクトへのポインタを取得する。

構文

HRESULT GetDirectDraw(
    IDirectDraw **ppDirectDraw
    );

パラメータ

ppDirectDraw
[out] 現在のメディア ストリームに関連付けられた DirectDraw オブジェクトが格納される IDirectDraw インターフェイスへのポインタのアドレス。

戻り値

成功した場合は、S_OK を返す。パラメータが無効な場合は、E_POINTER を返す。

注意

ストリームをまだ初期化していない場合、取得されるポインタは NULL となり、メソッドは S_OK を返す。ストリームが初期化されている場合、メソッドは取得されたポインタの参照カウントをインクリメントする。

IDirectDrawMediaStream::GetFormat

IDirectDrawMediaStream インターフェイス

現在のメディア ストリームのフォーマットを取得し、オプションでその望ましいフォーマットも取得する。

構文

HRESULT GetFormat(
    DDSURFACEDESC *pDDSDCurrent,
    IDirectDrawPalette **ppDirectDrawPalette,
    DDSURFACEDESC *pDDSDDesired,
    DWORD *pdwFlags
    );

パラメータ

pDDSDCurrent
[out] 現在のメディア ストリームのフォーマットが格納される DirectDraw サーフェス記述へのポインタ。
ppDirectDrawPalette
[out] IDirectDrawPalette インターフェイスへのポインタのアドレス (ある場合)。
pDDSDDesired
[out] 現在のメディア ストリームの望ましいフォーマットが格納される DirectDraw サーフェス記述へのポインタ。
pdwFlags
[out] DDSURFACEDESC 構造体にセットされるフラグへのポインタ。有効なフィールドには以下のものがある。
DDSD_HEIGHT | 構造体の高さのメンバが有効なことを示す。
DDSD_WIDTH | 構造体の幅のメンバが有効なことを示す。
DDSD_PIXELFORMAT | 構造体のピクセル フォーマットのメンバが有効なことを示す。
DDSD_CAPS | 構造体のサーフェス能力のメンバが有効なことを示す。

戻り値

次のいずれかの値を返す。
DDERR_INVALIDPARAMS | DirectDraw サーフェス パラメータの 1 つが無効。
E_POINTER | 無効な必須パラメータがある。
S_OK | 成功。

注意

このメソッドを呼び出した後、現在のフォーマットに従うか、または IDirectDrawMediaStream::SetFormat メソッドを呼び出してフォーマットの変更を試みる。

このメソッドのパラメータはすべて省略可能である。取得しないでよい情報がある場合は、そのパラメータを NULL に設定する。

プログレッシブ レンダリングを実行するには、サンプルを 1 つ作成し、そのサンプルをそれ以降のビデオ フレームに繰り返し使用する。ビデオ デコンプレッサ フィルタは、直前のフレームを部分的に更新するためにこのテクニックを使う。

このメソッドを呼び出す前に、DDSURFACEDESC 構造体の dwSize メンバを初期化する必要がある。

DDSD_CAPS フラグがオンの場合、DDSCAPS 構造体に含まれる値の 1 つ、または DDSCAPS_DATAEXCHANGE を返す。DDSCAPS_DATAEXCHANGE は、Ddrawex.h に DDSCAPS_SYSTEMMEMORY|DDSCAPS_VIDEOMEMORY として定義されている。

IDirectDrawMediaStream::GetTimePerFrame

IDirectDrawMediaStream インターフェイス

ビデオ ストリームから得られる 1 秒あたりの平均フレーム数を取得する。

構文

HRESULT GetTimePerFrame(
    STREAM_TIME *pFrameTime
    );

パラメータ

pFrameTime
[out] フレームあたりの平均時間 (100 ナノ秒単位) を示す STREAM_TIME 値へのポインタ。

戻り値

成功した場合は、S_OK を返す。ポインタが無効な場合は、E_POINTER を返す。

IDirectDrawMediaStream::SetDirectDraw

IDirectDrawMediaStream インターフェイス

現在のメディア ストリームの DirectDraw オブジェクトを設定する。

構文

HRESULT SetDirectDraw(
    IDirectDraw *pDirectDraw
    );

パラメータ

pDirectDraw
[in] メディア ストリームの新しい DirectDraw オブジェクトが格納された IDirectDraw インターフェイスへのポインタ。

戻り値

成功した場合は、S_OK を返す。ポインタが無効な場合は、E_POINTER を返す。

注意

現在のストリームに既に割り当て済みのサンプルがあり、その DirectDraw オブジェクトと指定されたオブジェクトが一致しない場合、このメソッドは失敗する。指定された DirectDraw オブジェクトがストリームの現在のオブジェクトと一致する場合には、必ず成功する。

このストリームに割り当て済みのサンプルがない場合、pDirectDraw を NULL に設定することができる。こうすると、ストリームから現在の DirectDraw オブジェクトの参照が強制的に解放される。

IDirectDrawMediaStream::SetFormat

IDirectDrawMediaStream インターフェイス

現在のメディア ストリームのフォーマットを設定する。

構文

HRESULT SetFormat(
    const DDSURFACEDESC *pDDSurfaceDesc,
    IDirectDrawPalette *pDirectDrawPalette
    );

パラメータ

pDDSurfaceDesc
[in] 新しいフォーマットが格納された DirectDraw サーフェス記述へのポインタ。
pDirectDrawPalette
[in] IDirectDrawPalette インターフェイスへのポインタ (省略可能)。

戻り値

次のいずれかの値を返す。
S_OK | 成功。
DDERR_INVALIDSURFACETYPE | 指定されたフォーマットが現在のストリームと互換でない。
MS_E_SAMPLEALLOC | このストリームには既に割り当て済みのストリーム サンプルがあるため、フォーマットを変更できない。

注意

ストリームに既に割り当て済みのサンプルがあり、そのサンプルのフォーマットと指定されたフォーマットが一致しない場合、このメソッドは失敗する。指定されたフォーマットが現在のフォーマットと一致している場合、このメソッドは必ず成功する。


IDirectDrawStreamSample インターフェイス

IDirectDrawStreamSample インターフェイスは、現在のストリーム サンプルに関連付けられた Microsoft® DirectDraw® サーフェスへのポインタを設定および取得するメソッドを提供する。

このインターフェイスは、アプリケーション開発者による実装を目的としたものではない。DirectDraw ストリームによって作成されたサンプル オブジェクトで公開される。

アプリケーションから、クリッピング矩形を設定し、DirectDraw ストリーム サンプル用のレンダリング サーフェスを取得するには、このインターフェイスを使用する。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IDirectDrawStreamSample メソッド | 説明
GetSurface | 現在のサンプルの DirectDraw サーフェスへのポインタ、および関連付けられた矩形へのポインタを取得する。
SetRect | サンプルのクリッピング矩形を変更する。

IDirectDrawStreamSample::GetSurface

IDirectDrawStreamSample インターフェイス

現在のサンプルの DirectDraw サーフェスへのポインタ、および関連付けられた矩形へのポインタを取得する。

構文

HRESULT GetSurface(

  IDirectDrawSurface **ppDirectDrawSurface,

  RECT *pRect

  );

パラメータ

ppDirectDrawSurface
[out] サンプルの新しいサーフェスを指定する IDirectDrawSurface インターフェイスへのポインタのアドレス。新しいサーフェスを指定しない場合は、このパラメータを NULL に設定する。
pRect
[out] 現在のサンプルのクリッピング矩形が格納される RECT 構造体へのポインタ。クリッピング矩形を取得しない場合は、このパラメータを NULL に設定する。

戻り値

HRESULT 値を返す。

注意

どちらのパラメータも省略可能である。このインターフェイスの実装はすべて、NULL を有効なパラメータと見なす必要がある。サーフェス ポインタを取得する場合、メソッド側でその参照カウントがインクリメントされるので、呼び出し元で参照を解放すること。

IDirectDrawStreamSample::SetRect

IDirectDrawStreamSample インターフェイス

サンプルのクリッピング矩形を変更する。

構文

HRESULT SetRect (

  const RECT *pRect

  );

パラメータ

pRect
[in] ストリームの新しいクリッピング矩形を指定する RECT 構造体へのポインタ。

戻り値

次のいずれかの値を返す。
DDERR_INVALIDPIXELFORMAT | ストリームがピクセル フォーマットと互換でない。
DDERR_INVALIDRECT | 指定された矩形が無効。
DDERR_INVALIDSURFACETYPE | ストリームがサーフェスと互換でない。
E_POINTER | ポインタの 1 つが無効。
MS_E_SAMPLEALLOC | ストリーム フォーマットがサーフェスと一致せず、現在、ストリームにサンプルが割り当てられている。
S_OK | 成功。

注意

パラメータは省略可能である。値を変更しない場合には、そのパラメータを NULL に設定する。サーフェス フォーマットがストリーム フォーマットと一致しない場合、このメソッドは失敗する。

新しい矩形と現在の矩形のサイズが異なる場合、このメソッドの呼び出しは失敗する。


IMediaStream インターフェイス

IMediaStream インターフェイスは、メディア ストリームの特性 (ストリームのメディア タイプ、目的 ID など) へのアクセスを提供する。また、データ サンプルを作成するメソッドも用意されている。

マルチメディア ストリーミング インターフェイスを実装するサンプル コードについては、「マルチメディア ストリーミングのサンプル コード」を参照すること。

メディア ストリームにメディア タイプ固有の機能を追加するには、このインターフェイスを実装する。このインターフェイスは、マルチメディア ストリーム オブジェクト上に実装される。IMediaStream には汎用のサンプル作成メソッドがあるが、通常は、メディア タイプの個々の特性を十分引き出すために、これらのメソッドをより強力に書き直す必要がある。

アプリケーションから、ストリームのメディア タイプ情報にアクセスし、データ サンプルを作成するには、このインターフェイスを使用する。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IMediaStream メソッド | 説明
GetMultiMediaStream | 指定されたメディア ストリームが格納されたマルチメディア ストリームへのポインタを取得する。
GetInformation | ストリームの目的 ID とメディア タイプを取得する。
SetSameFormat | メディア ストリームを直前のストリームと同じフォーマットに設定する。
AllocateSample | 現在のメディア ストリームに新しいストリーム サンプル オブジェクトを割り当てる。
CreateSharedSample | 既存サンプルと同じバッキング オブジェクトを共有する新しいストリーム サンプルを作成する。
SendEndOfStream | 現在のストリームを強制終了する。現在のストリームが書き込み可能でない場合、このメソッドは何も実行しない。

IMediaStream::AllocateSample

IMediaStream インターフェイス

現在のメディア ストリームに新しいストリーム サンプル オブジェクトを割り当てる。

構文

HRESULT AllocateSample(
  DWORD dwFlags,
  IStreamSample **ppSample
  );

パラメータ

dwFlags
[in] フラグ。ゼロでなくてはならない。
ppSample
[out] 新しく作成されたストリーム サンプルの IStreamSample インターフェイスへのポインタのアドレス。

戻り値

次のいずれかの値を返す。
E_OUTOFMEMORY | メモリ不足のため、ストリーム サンプルを作成できない。
E_POINTER | パラメータが無効。
S_OK | 成功。

注意

このメソッドは、サンプルとそのバッキング オブジェクトまたはバッファを割り当てる。バッキング オブジェクトは、ビデオ用の DirectDraw サーフェスか、またはオーディオ用の IAudioData オブジェクトのどちらかである。

IMediaStream::CreateSharedSample

IMediaStream インターフェイス

既存サンプルと同じバッキング オブジェクトを共有する新しいストリーム サンプルを作成する。

構文

HRESULT CreateSharedSample(

  IStreamSample *pExistingSample,

  DWORD dwFlags ,

  IStreamSample **ppNewSample

  );

パラメータ

pExistingSample
[in] 既存のサンプルへのポインタ。
dwFlags
[in] フラグ データ用に予約されている。ゼロでなくてはならない。
ppNewSample
[out] IStreamSample インターフェイスへのポインタのアドレス。このポインタに、新しく作成された共有サンプルのアドレスを受け取る。

戻り値

次のいずれかの値を返す。
E_OUTOFMEMORY | メモリ不足のため、サンプルを作成できない。
E_POINTER | パラメータの 1 つが無効。
MS_E_INCOMPATIBLE | 既存のサンプルが指定されたメディア ストリームと互換でない。
S_OK | 成功。ppNewSample は新しく作成されたサンプルを指す。

注意

このメソッドは、既存のサンプル上の IUnknown::QueryInterface を呼び出してメディア タイプ固有の情報を取得し、その情報を使って共有サンプルを作成する。

IMediaStream::GetInformation

IMediaStream インターフェイス

ストリームの目的 ID とメディア タイプを取得する。

構文

HRESULT GetInformation(

  MSPID *pPurposeId,

  STREAM_TYPE *pType

  );

パラメータ

pPurposeId
[out] ストリームの目的 ID が格納される MSPID 値へのポインタ。このパラメータに NULL を渡した場合、メソッドは目的 ID を取得しない。
pType
[out] ストリームのメディア タイプが格納される STREAM_TYPE 列挙型値へのポインタ。このパラメータに NULL を渡した場合、メソッドはメディア タイプを取得しない。

戻り値

成功した場合は、S_OK を返す。パラメータの 1 つが無効な場合は、E_POINTER を返す。

注意

pPurposeId パラメータに取得される値は、通常、プライマリ ビデオ ストリームを識別する MSPID_PrimaryVideo か、またはプライマリ オーディオ ストリームを識別する MSPID_PrimaryAudio のどちらかである。ただし、必要に応じてほかの値を定義することもできる。

IMediaStream::GetMultiMediaStream

IMediaStream インターフェイス

指定されたメディア ストリームが格納されたマルチメディア ストリームへのポインタを取得する。

構文

HRESULT GetMultiMediaStream(

  IMultiMediaStream **ppMultiMediaStream

  );

パラメータ

ppMultiMediaStream
[out] IMultiMediaStream インターフェイス オブジェクトへのポインタのアドレス。このポインタに、現在のメディア ストリームを作成する際に基になったメディア ストリームのアドレスを受け取る。

戻り値

成功した場合は、S_OK を返す。ppMultiMediaStream が無効な場合は、E_POINTER を返す。

注意

このメソッドは、取得されたオブジェクト ポインタの参照カウントをインクリメントする。

IMediaStream::SendEndOfStream

IMediaStream インターフェイス

現在のストリームを強制終了する。現在のストリームが書き込み可能でない場合、このメソッドは何も実行しない。

構文

HRESULT SendEndOfStream(

  DWORD dwFlags

  );

パラメータ

dwFlags
[in] フラグ データ用に予約されている。ゼロでなくてはならない。

戻り値

成功した場合は、S_OK を返す。既存のサンプルが現在のメディア ストリームと互換でない場合は、MS_E_INCOMPATIBLE を返す。

注意

アプリケーションからこの内部メソッドを呼び出すことはない。

IMediaStream::SetSameFormat

IMediaStream インターフェイス

メディア ストリームを直前のストリームと同じフォーマットに設定する。

構文

HRESULT SetSameFormat(

  IMediaStream *pStreamThatHasDesiredFormat,

  DWORD dwFlags

  );

パラメータ

pStreamThatHasDesiredFormat
[in] 同じフォーマットを持つメディア ストリーム オブジェクトへのポインタ。
dwFlags
[in] フラグ データ用に予約されている。ゼロでなくてはならない。

戻り値

成功した場合は、S_OK を返す。パラメータの 1 つが無効な場合は、E_POINTER を返す。


IMemoryData インターフェイス

IMemoryData インターフェイスには、オーディオ データ オブジェクト上のメモリ データを設定および取得するメソッドが含まれる。オーディオ データ オブジェクトは、ストリーム サンプルがアクセスする、基盤となるデータを提供するものである。このインターフェイスは、メモリ バッファを初期化し、実際にオブジェクト内にあるオーディオ データの量を設定する手段を提供する。また、GetInfo メソッドを使用すると、オーディオ メモリ データを取得できる。

このインターフェイスは、オーディオ ストリーム サンプル オブジェクトからアクセスされる、基盤となるオーディオ データ オブジェクト上に実装する。

通常、これらのメソッドは、アプリケーションではなく、IAudioMediaStream オブジェクトまたは IAudioStreamSample オブジェクトから呼び出される。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IMemoryData メソッド | 説明
SetBuffer | メモリへのポインタと長さを指定してメモリ バッファを初期化する。
GetInfo | オーディオ データ オブジェクトを記述する情報を取得する。
SetActual | 現在オブジェクト内にあるオーディオ データの量 (バイト単位) を設定する。

IMemoryData::GetInfo

IMemoryData インターフェイス

オーディオ データ オブジェクトを記述する情報を取得する。

構文

HRESULT GetInfo(
  DWORD *pdwLength,
  BYTE **ppbData,
  DWORD *pcbActualData );

パラメータ

pdwLength
[out] バイト単位で表したメモリの長さ (NULL でない場合)。
ppbData
[out] メモリへのポインタ (NULL でない場合)。
pcbActualData
[out] バイト単位で表したデータ長 (NULL でない場合)。

戻り値

HRESULT 値を返す。

注意

このメソッドは、SetActual によって最後に設定された、現在オブジェクト内にあるデータの数を判断する。

IMemoryData::SetActual

IMemoryData インターフェイス

現在オブジェクト内にあるオーディオ データの量を設定する。

構文

HRESULT SetActual(
  DWORD cbDataValid
  );

パラメータ

cbDataValid
[in] データの量 (バイト単位)。

戻り値

成功した場合は、S_OK を返す。必須パラメータが NULL の場合は、E_POINTER を返す。

注意

これらのメソッドは、通常、アプリケーションではなく、IAudioMediaStream オブジェクトまたは IAudioStreamSample オブジェクトから呼び出される。

IMemoryData::SetBuffer

IMemoryData インターフェイス

メモリへのポインタと長さを指定してメモリ バッファを初期化する。

構文

HRESULT SetBuffer(
  DWORD cbSize,
  BYTE *pbData,
  DWORD dwFlags );

パラメータ

cbSize
[in] pbData が指すメモリのサイズ (バイト単位)。
pbData
[in] このオブジェクトが使用するメモリへのポインタ。
dwFlags
[in] フラグ データ用に予約されている。ゼロでなくてはならない。

戻り値

成功した場合は、S_OK を返す。cbSize が 0 の場合、または pbData が NULL の場合は、E_INVALIDARG を返す。

注意

このメソッドは必要なだけ繰り返して呼び出すことができる。IStreamSample::Update を使ってサンプルを非同期に更新するときには、サンプルの更新が完了する前に SetBuffer が呼び出されないように注意する。


IMultiMediaStream インターフェイス

IMultiMediaStream インターフェイスは、マルチメディア ストリームを制御し、その基盤となるメディア ストリームにアクセスするメソッドを提供する。マルチメディア ストリームは、最上位レベルのストリーミング オブジェクトであり、1 つ以上のメディア ストリームを格納することができる。個々のメディア ストリームがメディア タイプ固有 (オーディオ、ビデオなど) であるのに対し、マルチメディア ストリームは、メディア タイプの異なる多数のストリームへのアクセスを提供する必要があるため、すべてのタイプに共通である。IMultiMediaStream インターフェイスのメソッドを使用すると、特定のストリームへのポインタを列挙および取得できる。また、IMediaStream インターフェイスのメソッドを使用すると、メディア ストリームの動作を個別に制御できる。

マルチメディア ストリーミング インターフェイスを実装するサンプル コードについては、「マルチメディア ストリーミングのサンプル コード」を参照すること。

特定のタイプのメディア ストリームに使用するコンテナを作成するには、このインターフェイスを実装する。

アプリケーションでマルチメディア ストリームの基盤となるタイプ固有のストリームを列挙および制御するには、このインターフェイスを使用する。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IMultiMediaStream メソッド | 説明
GetInformation | マルチメディア ストリームの能力およびストリーム タイプを取得する。
GetMediaStream | 指定された目的 ID を持つメディア ストリームを取得する。
EnumMediaStreams | 0 から始まるインデックスを指定して、マルチメディア ストリームからメディア ストリームを取得する。
GetState | マルチメディア ストリームの現在の状態を取得する。
SetState | メディア ストリームを実行状態または停止状態に切り替える。
GetTime | マルチメディア ストリームのクロックから現在の時間を取得する (クロックがある場合)。
GetDuration | メディア ストリームの時間幅を取得する。
Seek | 派生メディア ストリームすべてのシーク位置を、指定された時間に設定する。
GetEndOfStreamEventHandle | ストリームが再生を完了したときに発行されるイベントのハンドルを取得する。

IMultiMediaStream::EnumMediaStreams

IMultiMediaStream インターフェイス

0 から始まるインデックスを指定して、マルチメディア ストリームからメディア ストリームを取得する。

構文

HRESULT EnumMediaStreams(

  long Index,

  IMediaStream **ppMediaStream

  );

パラメータ

Index
[in] 確認するストリーム配列のインデックス。
ppMediaStream
[out] IMediaStream インターフェイス オブジェクトへのポインタのアドレス。メソッド終了時には、指定されたインデックス位置にあるストリームへのポインタが格納される。

戻り値

次のいずれかの値を返す。
E_POINTER | ppMediaStream ポインタが無効。
S_FALSE | Index が範囲外。列挙するストリームが残っていない。この値が返される場合、ppMediaStream は NULL に設定される。
S_OK | 成功。

注意

このメソッドは、ストリームの列挙が完了したことを示す S_FALSE が返されるまで、呼び出さなければならない。

IMultiMediaStream::GetDuration

IMultiMediaStream インターフェイス

メディア ストリームの時間幅を返す。

構文

HRESULT GetDuration(
  STREAM_TIME *pDuration
  );

パラメータ

pDuration
[out] メディアの時間幅が格納される STREAM_TIME 値へのポインタ。

戻り値

次のいずれかの値を返す。
E_POINTER | pDuration の値が無効。
MS_E_WRITESTREAM | 書き込み可能なメディア ストリームなので、時間幅がない。
S_FALSE | ストリームにライブ データが含まれているか、またはこのメソッドが時間幅を判断できない。メソッド終了時には、pDuration が 0 に設定される。
S_OK | ストリームに記録済みメディアが含まれている。メソッド終了時には、pDuration にメディアの時間幅が格納される。

IMultiMediaStream::GetEndOfStreamEventHandle

IMultiMediaStream インターフェイス

ストリームが再生を完了したときに発行されるイベントのハンドルを取得する。

構文

HRESULT GetEndOfStreamEventHandle(

  HANDLE *phEOS

  );

パラメータ

phEOS
[out] 再生を完了したときに現在のオブジェクトから返されたイベント HANDLE へのポインタ。オブジェクトに HANDLE が関連付けられていない場合、この値は NULL となる。

戻り値

成功した場合は、S_OK を返す。NULL の必須パラメータがある場合は、E_POINTER を返す。

注意

Microsoft® Win32® の WaitForSingleObject 関数と WaitForMultipleObjects 関数は、取得されたハンドルを使って再生の完了を待つ。

IMultiMediaStream::GetInformation

IMultiMediaStream インターフェイス

指定されたメディア タイプと一致するメディア ストリームの能力を取得する。

構文

HRESULT GetInformation(
  DWORD *pdwFlags,
  STREAM_TYPE *pStreamType

  );

パラメータ

pdwFlags
[out] 以下のフラグを 1 つ以上組み合わせたものが格納される値へのポインタ。NULL の場合がある。
MMSSF_ASYNCHRONOUS | ストリームがサンプルの同期更新をサポートする。IMultiMediaStream の実装ではすべて同期更新がサポートされる。このフラグはそれを確認するものである。
MMSSF_HASCLOCK | ストリームにクロックがある。
MMSSF_SUPPORTSEEK | ストリームがシークをサポートしている。
pStreamType
[out] 派生メディア ストリームに対応するメディア タイプ情報が格納される STREAM_TYPE 列挙型へのポインタ。NULL の場合がある。

戻り値

HRESULT 値を返す。

注意

ストリームの能力には、クロックの有無、シークをサポートするかどうか、および非同期更新をサポートするかどうかが含まれる。

IMultiMediaStream::GetMediaStream

IMultiMediaStream インターフェイス

指定された目的 ID を持つメディア ストリームを取得する。

構文

HRESULT GetMediaStream(
  REFMSPID idPurpose,
  IMediaStream **ppMediaStream

  );

パラメータ

idPurpose
目的のストリームを指定する値。
ppMediaStream
IMediaStream インターフェイスへのポインタのアドレス。このポインタに、目的のメディア ストリームのアドレスを受け取る。

戻り値

次のいずれかの値を返す。
E_POINTER | ppMediaStream ポインタが無効。
MS_E_NOSTREAM | 指定された目的 ID を持つストリームがない。
S_OK | 成功。

注意

idPurpose の目的 ID と一致するストリームが存在する場合には、ppMediaStream パラメータはストリームを指し、その参照カウントがインクリメントされる。

MSPID_PrimaryVideo および MSPID_PrimaryAudio は、それぞれプライマリ ビデオ ストリームおよびプライマリ ビデオ ストリームを表す。これらは最もよく使用される目的 ID である。

IMultiMediaStream::GetState

IMultiMediaStream インターフェイス

マルチメディア ストリームの現在の状態を取得する。

構文

HRESULT GetState(

  STREAM_STATE *pCurrentState

  );

パラメータ

pCurrentState
[out] 現在のマルチメディア ストリームの状態が格納される STREAM_STATE 列挙型へのポインタ。

戻り値

成功した場合は、S_OK を返す。pCurrentState が無効な場合は、E_POINTER を返す。

IMultiMediaStream::GetTime

IMultiMediaStream インターフェイス

マルチメディア ストリームのクロックから現在の時間を取得する (クロックがある場合)。

構文

HRESULT GetTime(

  STREAM_TIME *pCurrentTime

  );

パラメータ

pCurrentTime
[out] 現在の時間が格納される STREAM_TIME 値へのポインタ (メディア ストリームにクロックがある場合)。

戻り値

次のいずれかの値を返す。
E_POINTER | pCurrentTime ポインタが無効。
S_FALSE | ストリームにクロックがない。*pCurrentTime は 0 となる。
S_OK | ストリームにクロックがあり、メソッドは成功した。pCurrentTime には現在の時間が格納される。

注意

ストリームにクロックがない場合、このメソッドは、*pCurrentTime に 0 を設定し、S_FALSE を返す。ストリームにクロックがある場合、ストリーム サンプルの時間は、ストリームのクロックに対する相対時間となる。

STREAM_TIME は LONGLONG 値として定義されている。

IMultiMediaStream::Seek

IMultiMediaStream インターフェイス

含まれるメディア ストリームすべてのシーク位置を、指定された時間に設定する。

構文

HRESULT Seek(
  STREAM_TIME SeekTime
  );

パラメータ

SeekTime
[in] シーク時間を指定する STREAM_TIME 値。

戻り値

次のいずれかの値を返す。
E_POINTER | ポインタの 1 つが無効。
MS_E_NOSEEKING | シークをサポートしないメディア ストリームがある。
MS_E_WRITESTREAM | 書き込み可能なストリームなので、シークをサポートしない。
S_OK | 成功。

注意

このメソッドは、シークをサポートしないストリームには機能しない。このメソッドを呼び出す前に、IMultiMediaStream::GetInformation を呼び出してストリームの能力を取得する。取得された値に MMSSF_SUPPORTSEEK フラグが含まれれば、このメソッドを呼び出すことができる。

クロックがあるストリームをシークすることにより、現在の時間が予測不可能な値 (たとえば目的のシーク時間より前の時間など) に変わる可能性がある。その結果、メソッドは失敗する。

このメソッドは、マルチメディア ストリーム オブジェクトから派生したすべてのメディア ストリーム内の指定された時間までシークする。

IMultiMediaStream::SetState

IMultiMediaStream インターフェイス

メディア ストリームを実行状態または停止状態に切り替える。

構文

HRESULT SetState(
  STREAM_STATE NewState
  );

パラメータ

NewState
[in] メディア ストリームの新しい状態を指定する STREAM_STATE 列挙値。

戻り値

S_OK を返す。

注意

ストリームを STREAMSTATE_STOP に切り替えると、このメソッドは保留されているデータをすべて削除する。


IStreamSample インターフェイス

IStreamSample インターフェイスは、ストリーム サンプルの動作を制御するものである。サンプルを作成したメディア ストリームを取得し、サンプルの開始タイムと終了タイムを設定または取得し、サンプルの完了状態を確認し、サンプル自体に開発者が指定した関数を実行することができる。

新しいメディア タイプのメディア ストリームを実装するときには、このインターフェイスを実装する。このインターフェイスは、メディア ストリームが作成したサンプル オブジェクト上で公開される。

IMediaStream が作成したデータ サンプルまたはその派生インターフェイスを制御するには、このインターフェイスを使用する。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IStreamSample メソッド | 説明
GetMediaStream | 現在のサンプルを作成したメディア ストリーム オブジェクトへのポインタを取得する。
GetSampleTimes | 現在のサンプルの開始タイムと終了タイムを取得する。
SetSampleTimes | 現在のサンプルの開始タイムと終了タイムを設定する。
Update | 現在のサンプルを同期または非同期に更新する。
CompletionStatus | 現在のサンプルに行われた最後の非同期更新の状態を取得する。更新が完了していない場合には強制終了できる。

IStreamSample::CompletionStatus

IStreamSample インターフェイス

現在のサンプルに行われた最後の非同期更新の状態を取得する。更新が完了していない場合には強制終了できる。

構文

HRESULT CompletionStatus(
  DWORD dwFlags,
  DWORD dwMilliseconds
  );

パラメータ

dwFlags
[in] 更新を強制終了するかどうかを指定する値。この値は、以下のフラグを 1 つ以上組み合わせたものである。
COMPSTAT_NOUPDATEOK (0x01) | サンプル更新が完了していない場合も含め、更新をできる限り早く強制終了する。サンプルが更新中で、COMPSTAT_WAIT フラグが設定されていない場合、メソッドは MS_S_PENDING を返す。サンプルが更新待ちの場合、メソッドはサンプルをキューから削除し、MS_S_NOTUPDATED を返す。
COMPSTAT_WAIT (0x02) | サンプル更新の終了を待ったうえで、メソッドから戻る。
COMPSTAT_ABORT (0x04) | サンプルが現在更新中の場合も含め、更新を強制終了する。この方法では、サンプル データの状態が不定になる。更新を確実にキャンセルするには、COMPSTAT_WAITFORCOMPLETION フラグと組み合わせる。
dwMilliseconds
[in] dwFlags パラメータが COMPSTAT_WAIT の場合、この値は更新完了を待つ待機時間 (ミリ秒単位) となる。サンプル更新が完了するまで待ってからメソッドが戻るようにするには、INFINITE を指定する。

戻り値

次のいずれかの値を返す。
E_ABORT | 更新が中止された。
MS_S_ENDOFSTREAM | ストリームの終端に達したため、サンプルが更新されなかった。
MS_S_NOUPDATE | 更新が強制終了され、サンプルがストリームによって更新されなかった。
MS_S_PENDING | 非同期更新が保留されている。
S_OK | 成功。

IStreamSample::GetMediaStream

IStreamSample インターフェイス

現在のサンプルを作成したメディア ストリーム オブジェクトへのポインタを取得する。

構文

HRESULT GetMediaStream(

  IMediaStream **ppMediaStream

  );

パラメータ

ppMediaStream
[in] IMediaStream インターフェイスへのポインタのアドレス。このポインタに、現在のサンプルを作成したメディア ストリームのアドレスを受け取る。

戻り値

成功した場合は、S_OK を返す。ppMediaStream が無効な場合は、E_POINTER を返す。

注意

成功した場合、このメソッドは ppMediaStream で指定されたメディア ストリームの参照カウントをインクリメントする。

IStreamSample::GetSampleTimes

IStreamSample インターフェイス

現在のサンプルの開始タイムと終了タイムを取得する。サンプルが更新中の場合、このメソッドは更新完了後の時間を返す。

構文

HRESULT GetSampleTimes(

  STREAM_TIME *pStartTime,

  STREAM_TIME *pEndTime,

  STREAM_TIME *pCurrentTime

  );

パラメータ

pStartTime
[out] サンプルの開始タイムが格納される STREAM_TIME 値へのポインタ。
pEndTime
[out] サンプルの終了タイムが格納される STREAM_TIME 値へのポインタ。
pCurrentTime
[out] メディア ストリームの現在のメディア タイムが格納される STREAM_TIME 値へのポインタ。

戻り値

成功した場合は、S_OK を返す。パラメータの 1 つが無効な場合は、E_POINTER を返す。

注意

ストリームにクロックがある場合、開始タイムと終了タイムはストリームの現在時間に対する相対時間となる。ストリームにクロックがない場合、開始タイムと終了タイムはメディアに対する相対時間であり、現在時間は 0 となる。

pCurrentTime パラメータを使用すると、メディア ストリームの現在時間を簡単に追跡できるため、IMultiMediaStream::GetTime を呼び出さないで済む。ただし、ストリームにクロックがない場合、GetTime は S_FALSE を返すが、このメソッドは S_OK を返す。pCurrentTime に割り当てられる値は、次のコードで生成される値と同じである。

pSample->GetMediaStream(&pMediaStream);
pMediaStream->GetMultiMediaStream(&pMultiMediaStream);
pMediaStream->Release();
pMultiMediaStream->GetTime(&pCurrentTime);
pMultiMediaStream->Release();

IStreamSample::SetSampleTimes

IStreamSample インターフェイス

現在のサンプルの開始タイムと終了タイムを設定する。このメソッドは、サンプルを更新する前に呼び出すことができる。

構文

HRESULT SetSampleTimes(

  const STREAM_TIME *pStartTime,

  const STREAM_TIME *pEndTime

  );

パラメータ

pStartTime
[in] サンプルの新しい開始タイムが格納された STREAM_TIME 値へのポインタ。
pEndTime
[in] サンプルの新しい終了タイムが格納された STREAM_TIME 値へのポインタ。

戻り値

成功した場合は、S_OK を返す。パラメータの 1 つが NULL の場合は、E_POINTER を返す。

注意

ストリームにクロックがある場合、開始タイムと終了タイムはストリームの現在時間に対する相対で指定する。ストリームにクロックがない場合、開始タイムと終了タイムはメディアに対する相対で指定する。

このメソッドは、書き込み可能なストリームにのみ適用される。

IStreamSample::Update

IStreamSample インターフェイス

現在のサンプルを同期または非同期に更新する。

構文

HRESULT Update(
  DWORD dwFlags,
  HANDLE hEvent,
  PAPCFUNC pfnAPC,
  DWORD dwAPCData
  );

パラメータ

dwFlags
[in] 更新が同期か非同期かを指定するフラグ。SSUPDATE_ASYNC フラグは、非同期の更新を示し、hEvent と pfnAPC の両方が NULL の場合に設定することができる。IStreamSample::CompletionStatus メソッドを呼び出すまでサンプルを連続的に更新するには、SSUPDATE_CONTINUOUS を指定する。
hEvent
[in] 更新完了時にこのメソッドが発行するイベントへのハンドル。
pfnAPC
[in] 更新完了時にこのメソッドが呼び出す Win32 非同期プロシージャ呼び出し (APC) 関数へのポインタ。
dwAPCData
[in] pfnAPC パラメータで指定された関数にこのメソッドが渡す値。

戻り値

次のいずれかの値を返す。
E_ABORT | 更新が中止された。
E_INVALIDARG | パラメータの 1 つが無効。
E_POINTER | パラメータの 1 つが無効。
MS_E_BUSY | このサンプルには既に保留中の更新がある。
MS_S_ENDOFSTREAM | ストリーム終端に達した。サンプルは更新されない。
MS_S_PENDING | 非同期更新が保留されている。
S_OK | 成功。

注意

このメソッドを使用すると、サンプルの同期更新または非同期更新を実行できる。hEvent と pfnAPC の両方が NULL の場合、SSUPDATE_ASYNC フラグと SSUPDATE_CONTINUOUS フラグのどちらかを指定しない限り、更新は同期となる。同期更新から戻ったときには、関数の結果に I/O の完了状態が格納されている。

hEvent と pfnAPC の両方に値を指定することはできない。指定した場合、メソッドは失敗する。

非同期更新は、更新から戻る前に完了する可能性がある。この場合、戻り値は S_OK になる。イベントを指定した場合、更新から S_OK が返されると、このメソッドは終了時にイベントを設定する。APC 関数を指定した場合、更新から S_OK が返されたときには、APC がキューに入れられることも、関数が呼び出されることもない。

戻る前に完了しない非同期更新は、値 MS_S_PENDING を返す。

アプリケーションが複数のストリームを作成する場合、それぞれのストリームで非同期更新を実行しなければならない。WaitForMultipleObjects を呼び出し、それぞれのストリームの更新が完了するのを待ってから、次の更新を行う。このようにしないと、アプリケーションがブロックする可能性がある。


マルチメディア ストリーミング データ タイプ

ここでは、Microsoft® DirectShow® マルチメディア ストリーミングのデータ タイプについて説明する。
データ タイプ | 説明
MSPID | メディア ストリームの目的を定義する目的 ID。目的 ID は typedef で GUID として宣言できる。
STREAM_STATE | ストリームの状態を記述する。
STREAM_TIME | 100 ナノ秒単位のストリーム タイム。このデータ タイプは 64 ビット整数 (LONGLONG) として定義される。
STREAM_TYPE | ストリームのデータが流れる方向を定義する。

STREAM_STATE

マルチメディア ストリーミング データ タイプ

ストリームの状態を記述する。

構文

typedef enum {
    STREAMSTATE_STOP        = 0,
    STREAMSTATE_RUN         = 1
} STREAM_STATE;

要素

STREAMSTATE_STOP
停止状態。
STREAMSTATE_RUN
実行状態。

注意

IMultiMediaStream::SetState メソッドを呼び出して状態を変更する。

STREAM_TYPE

マルチメディア ストリーミング データ タイプ

ストリームのデータが流れる方向を定義する。

構文

typedef enum {
    STREAMTYPE_READ         = 0,
    STREAMTYPE_WRITE        = 1,
    STREAMTYPE_TRANSFORM    = 2
} STREAM_TYPE;

要素

STREAMTYPE_READ
アプリケーションからストリームを読み取ることができる。
STREAMTYPE_WRITE
アプリケーションからストリームに書き込むことができる。
STREAMTYPE_TRANSFORM
アプリケーションからストリームを読み書きできる。

注意

変換ストリームは読み書き可能であり、サンプルが同じ位置に書き戻される。


マルチメディア ストリーミングのエラー コードと成功コード

次の一覧は、マルチメディア ストリーミング インターフェイスを使用するアプリケーションに渡されるエラー メッセージと成功通知である。ただし、可能なエラーにはこの一覧にないものもある。これらのエラーは、Microsoft® DirectShow® によるマルチメディア ストリーミング インターフェイスの実装に固有のエラーのみに適用される。成功コードは、MS_S で始まり、SUCCEEDED マクロからの TRUE を返すか、または FAILED マクロからの FALSE を返す。
メッセージ | 16 進コード | 意味
MS_S_PENDING | 0x00040001 | サンプルの更新がまだ完了していない。
MS_S_NOUPDATE | 0x00040002 | 強制終了後にサンプルが更新されなかった。
MS_S_ENDOFSTREAM | 0x00040003 | ストリーム終了。サンプルは更新されていない。
MS_E_SAMPLEALLOC | 0x80040401 | 割り当て済みのサンプルが少なくとも 1 つ含まれているため、IMediaStream オブジェクトを IMultiMediaStream オブジェクトから削除できない。
MS_E_PURPOSEID | 0x80040402 | 指定された目的 ID は呼び出しに使用できない。
MS_E_NOSTREAM | 0x80040403 | 指定された属性を持つストリームが見つからない。
MS_E_NOSEEKING | 0x80040404 | この IMultiMediaStream オブジェクトではシークがサポートされない。
MS_E_INCOMPATIBLE | 0x80040405 | ストリーム フォーマットが互換でない。
MS_E_BUSY | 0x80040406 | サンプルが使用中。
MS_E_NOTINIT | 0x80040407 | 初期化関数またはそれに相当するものが呼び出されていないため、オブジェクトが呼び出しを受け付けられない。
MS_E_SOURCEALREADYDEFINED | 0x80040408 | ソースが既に定義されている。
MS_E_INVALIDSTREAMTYPE | 0x80040409 | ストリーム タイプがこの操作に有効でない。
MS_E_NOTRUNNING | 0x8004040A | IMultiMediaStream オブジェクトが実行状態にない。


マルチメディア ストリーミング コンポーネント オブジェクト

ここでは、Microsoft® DirectShow® がサポートする各種コンポーネントの一覧を記載する。これらのオブジェクトは、マルチメディア ストリーミング インターフェイスをサポートする。また、コンポーネント オブジェクトの階層構造図も記載する。

以下の項で構成される。

  • コンポーネント オブジェクトの一覧
  • オブジェクト参照図

コンポーネント オブジェクトの一覧

この項では、DirectShow がサポートする各種コンポーネントについて説明する。
オブジェクト | 説明 | サポートされるインターフェイス
CLSID_AMMultiMediaStream | DirectShow によるマルチメディア ストリームの実装 | IAMMultiMediaStream、IMultiMediaStream
CLSID_MediaStreamFilter | IAMMultiMediaStream インターフェイスを通じて、CLSID_AMMultiMediaStream オブジェクトに対応するマルチメディア ストリーミング機能を提供する | IBaseFilter
CLSID_AMDirectDrawStream | DirectShow マルチメディア ストリームに追加できる Microsoft® DirectDraw® メディア ストリーム | IAMMediaStream、IMediaStream、IDirectDrawMediaStream、IPin、IMemInputPin
DirectDraw ストリームによって作成されたサンプル |  | IStreamSample、IDirectDrawStreamSample、IMediaSample
CLSID_ AMMediaTypeStream | DirectShow でサポートされる任意のデータ タイプに対応するメディア サンプルを作成できる | IAMMediaStream、IMediaStream、IPin、IMemInputPin
CLSID_ AMMediaTypeStream オブジェクトによって作成されたサンプル |  | IStreamSample、IMediaSample、IMediaSample2
CLSID_AMAudioData | IAudioData オーディオ コンテナ オブジェクトの実装 | IAudioData

オブジェクト参照図

オブジェクトの階層構造には、DirectShow オブジェクト間に興味深い循環参照がいくつか存在する。次の図は、すべてのオブジェクトとその参照を示す。実線は強い参照 (参照されるオブジェクトをインクリメントするもの)、点線は弱い参照 (参照されるオブジェクトに対して AddRef を実行しないもの) を表している。

サンプルはマルチメディア ストリーム オブジェクトへの強い参照を保持するが、メディア ストリームは保持しない。


マルチメディア ストリーミングのサンプル コード

ここには、マルチメディア ストリーミング インターフェイスを実装するサンプル コードを記載する。ビデオ ストリーミングのサンプル コードは、ファイルを読み取り、それをプライマリ Microsoft® DirectDraw® サーフェスにレンダリングする方法を示す。このコードでは簡潔さのため、エラー チェックが省略されている。

2 番目のサンプル コードは、オーディオ ストリーミング インターフェイスを使ってオーディオ データをストリームする方法を示す。

以下の項で構成される。

  • ビデオ ストリーミングのサンプル コード
  • オーディオ ストリーミングのサンプル コード

ビデオ ストリーミングのサンプル コード

このサンプル コードでは、ファイルを読み取り、それをプライマリ DirectDraw サーフェスにレンダリングする。

#include <stdio.h>
#include "ddraw.h"       // DirectDraw インターフェイス
#include "mmstream.h"    // マルチメディア ストリーム インターフェイス
#include "amstream.h"    // DirectShow マルチメディア ストリーム インターフェイス
#include "ddstream.h"    // DirectDraw マルチメディア ストリーム インターフェイス

void RenderStreamToSurface(IDirectDrawSurface *pSurface,
    IMultiMediaStream *pMMStream)
{
    IMediaStream *pPrimaryVidStream;
    IDirectDrawMediaStream *pDDStream;
    IDirectDrawStreamSample *pSample;
    RECT rect;
    DDSURFACEDESC ddsd;

    pMMStream->GetMediaStream(MSPID_PrimaryVideo, &pPrimaryVidStream);
    pPrimaryVidStream->QueryInterface(IID_IDirectDrawMediaStream, (void **)&pDDStream);
    ddsd.dwSize = sizeof(ddsd);
    pDDStream->GetFormat(&ddsd, NULL, NULL, NULL);
    rect.top = rect.left = 0;
    rect.bottom = ddsd.dwHeight;
    rect.right = ddsd.dwWidth;
    pDDStream->CreateSample(pSurface, &rect, 0, &pSample);

    pMMStream->SetState(STREAMSTATE_RUN);
    while (pSample->Update(0, NULL, NULL, NULL) == S_OK);
    pMMStream->SetState(STREAMSTATE_STOP);

    pSample->Release();
    pDDStream->Release();
    pPrimaryVidStream->Release();
}

void RenderFileToMMStream(const char * szFileName,
    IMultiMediaStream **ppMMStream,
    IDirectDraw *pDD)
{
IAMMultiMediaStream *pAMStream;
CoCreateInstance(CLSID_AMMultiMediaStream, NULL, CLSCTX_INPROC_SERVER,
    IID_IAMMultiMediaStream, (void **)&pAMStream);
    WCHAR    wPath[MAX_PATH];        // ワイド (32 ビット) 文字列名
    MultiByteToWideChar(CP_ACP, 0, szFileName, -1, wPath,
        sizeof(wPath)/sizeof(wPath[0]));

    pAMStream->Initialize(STREAMTYPE_READ, AMMSF_NOGRAPHTHREAD, NULL);
    pAMStream->AddMediaStream(pDD, &MSPID_PrimaryVideo, 0, NULL);
    pAMStream->AddMediaStream(NULL, &MSPID_PrimaryAudio, AMMSF_ADDDEFAULTRENDERER, NULL);
    pAMStream->OpenFile(wPath, 0);
    *ppMMStream = pAMStream;
}

int _CRTAPI1 main(int argc, char *argv[])
{
    if (argc < 2) {
    printf("Usage : showstrm movie.ext\n");
    exit(0);}

    DDSURFACEDESC ddsd;
    IDirectDraw *pDD;
    IDirectDrawSurface *pPrimarySurface;
    IMultiMediaStream *pMMStream;

    CoInitialize(NULL);

    DirectDrawCreate(NULL, &pDD, NULL);
    pDD->SetCooperativeLevel(GetDesktopWindow(), DDSCL_NORMAL);
    ddsd.dwSize = sizeof(ddsd);
    ddsd.dwFlags = DDSD_CAPS;
    ddsd.ddsCaps.dwCaps = DDSCAPS_PRIMARYSURFACE;
    pDD->CreateSurface(&ddsd, &pPrimarySurface, NULL);
    RenderFileToMMStream(argv[1], &pMMStream, pDD);
    RenderStreamToSurface(pPrimarySurface, pMMStream);
    pMMStream->Release();
    pPrimarySurface->Release();
    pDD->Release();

CoUninitialize();
return 0;
}

オーディオ ストリーミングのサンプル コード

次のサンプル コードは、IAudioMediaStream、IAudioStreamSample、IMemoryData、および IAudioData の 4 つのインターフェイスを使ってオーディオ データをストリームする方法を示す。

#include <windows.h>
#include <mmsystem.h>
#include <amstream.h>

/********************************************************************

   簡単なウェーブ プレーヤー処理

 ********************************************************************/

class CWaveBuffer;

class CWaveBuffer {
public:
        CWaveBuffer();
        ~CWaveBuffer();
        BOOL Init(HWAVEOUT hWave, int Size);
        void Done();
        BOOL Write(PBYTE pData, int nBytes, int& BytesWritten);
void Flush();

private:
        WAVEHDR      m_Hdr;
        HWAVEOUT     m_hWave;
        int          m_nBytes;
};

class CWaveOut {
public:
        CWaveOut(LPCWAVEFORMATEX Format, int nBuffers, int BufferSize);
        ~CWaveOut();
        void Write(PBYTE Data, int nBytes);
void Flush();
        void Wait();
        void Reset();
private:
        const HANDLE   m_hSem;
        const int      m_nBuffers;
        int            m_CurrentBuffer;
        BOOL           m_NoBuffer;
        CWaveBuffer   *m_Hdrs;
        HWAVEOUT     m_hWave;
};

/*
    CWaveBuffer
*/

CWaveBuffer::CWaveBuffer()
{
}

BOOL CWaveBuffer::Init(HWAVEOUT hWave, int Size)
{
    m_hWave  = hWave;
    m_nBytes = 0;

    /*  バッファを割り当て、ヘッダーを初期化する。 */
    m_Hdr.lpData = (LPSTR)LocalAlloc(LMEM_FIXED, Size);
    if (m_Hdr.lpData == NULL) {
return FALSE;
    }
    m_Hdr.dwBufferLength  = Size;
    m_Hdr.dwBytesRecorded = 0;
    m_Hdr.dwUser = 0;
    m_Hdr.dwFlags = 0;
    m_Hdr.dwLoops = 0;
    m_Hdr.lpNext = 0;
    m_Hdr.reserved = 0;

    /*  準備をする。 */
    waveOutPrepareHeader(hWave, &m_Hdr, sizeof(WAVEHDR));

return TRUE;
}

CWaveBuffer::~CWaveBuffer() {
    if (m_Hdr.lpData) {
        waveOutUnprepareHeader(m_hWave, &m_Hdr, sizeof(WAVEHDR));
        LocalFree(m_Hdr.lpData);
    }
}

void CWaveBuffer::Flush()
{
    // ASSERT(m_nBytes != 0);
m_nBytes = 0;
waveOutWrite(m_hWave, &m_Hdr, sizeof(WAVEHDR));
}

BOOL CWaveBuffer::Write(PBYTE pData, int nBytes, int& BytesWritten)
{
    // ASSERT((DWORD)m_nBytes != m_Hdr.dwBufferLength);
    BytesWritten = min((int)m_Hdr.dwBufferLength - m_nBytes, nBytes);
    CopyMemory((PVOID)(m_Hdr.lpData + m_nBytes), (PVOID)pData, BytesWritten);
    m_nBytes += BytesWritten;
    if (m_nBytes == (int)m_Hdr.dwBufferLength) {
        /*  書き込む。 */
m_nBytes = 0;
waveOutWrite(m_hWave, &m_Hdr, sizeof(WAVEHDR));
return TRUE;
    }
return FALSE;
}

void CALLBACK WaveCallback(HWAVEOUT hWave, UINT uMsg, DWORD dwUser,
                           DWORD dw1, DWORD dw2)
{
    if (uMsg == WOM_DONE) {
        ReleaseSemaphore((HANDLE)dwUser, 1, NULL);
    }
}

/*
    CWaveOut
*/

CWaveOut::CWaveOut(LPCWAVEFORMATEX Format, int nBuffers, int BufferSize) :
    m_nBuffers(nBuffers),
    m_CurrentBuffer(0),
    m_NoBuffer(TRUE),
    m_hSem(CreateSemaphore(NULL, nBuffers, nBuffers, NULL)),
    m_Hdrs(new CWaveBuffer[nBuffers]),
    m_hWave(NULL)
{
    /*  ウェーブ デバイスを作成する。 */
    waveOutOpen(&m_hWave,
                WAVE_MAPPER,
                Format,
                (DWORD)WaveCallback,
                (DWORD)m_hSem,
                CALLBACK_FUNCTION);

    /*  ウェーブ バッファを初期化する。 */
    for (int i = 0; i < nBuffers; i++) {
        m_Hdrs[i].Init(m_hWave, BufferSize);
    }
}

CWaveOut::~CWaveOut()
{
    /*  まず、バッファをリセットする。 */
    waveOutReset(m_hWave);

    /*  バッファを解放する。 */
    delete [] m_Hdrs;

    /*  ウェーブ デバイスを閉じる。 */
    waveOutClose(m_hWave);

    /*  セマフォを解放する。 */
    CloseHandle(m_hSem);
}

void CWaveOut::Flush()
{
    if (!m_NoBuffer) {
        m_Hdrs[m_CurrentBuffer].Flush();
        m_NoBuffer = TRUE;
        m_CurrentBuffer = (m_CurrentBuffer + 1) % m_nBuffers;
    }
}

void CWaveOut::Reset()
{
waveOutReset(m_hWave);
}

void CWaveOut::Write(PBYTE pData, int nBytes)
{
    while (nBytes != 0) {
        /*  必要ならバッファを取得する。 */
        if (m_NoBuffer) {
WaitForSingleObject(m_hSem, INFINITE);
            m_NoBuffer = FALSE;
        }

        /*  バッファに書き込む。 */
        int nWritten;
        if (m_Hdrs[m_CurrentBuffer].Write(pData, nBytes, nWritten)) {
            m_NoBuffer = TRUE;
            m_CurrentBuffer = (m_CurrentBuffer + 1) % m_nBuffers;
            nBytes -= nWritten;
            pData += nWritten;
        } else {
            // ASSERT(nWritten == nBytes);
break;
        }
    }
}

void CWaveOut::Wait()
{
    /*  残っているバッファをすべて送る。 */
    Flush();

    /*  バッファが戻るまで待つ。 */
    for (int i = 0; i < m_nBuffers; i++) {
        WaitForSingleObject(m_hSem, INFINITE);
    }
    LONG lPrevCount;
    ReleaseSemaphore(m_hSem, m_nBuffers, &lPrevCount);
}

/************************************************************

  ウェーブ プレーヤー処理はここまで

 ************************************************************/

HRESULT RenderStreamToDevice(IMultiMediaStream *pMMStream)
{
    WAVEFORMATEX wfx;
    #define DATA_SIZE 5000
    PBYTE pBuffer = (PBYTE)LocalAlloc(LMEM_FIXED, DATA_SIZE);

    IMediaStream *pStream;
    IAudioStreamSample *pSample;
    IAudioMediaStream *pAudioStream;
    IAudioData *pAudioData;

    pMMStream->GetMediaStream(MSPID_PrimaryAudio, &pStream);
    pStream->QueryInterface(IID_IAudioMediaStream, (void **)&pAudioStream);
    pAudioStream->GetFormat(&wfx);
    CoCreateInstance(CLSID_AMAudioData, NULL, CLSCTX_INPROC_SERVER,
                                    IID_IAudioData, (void **)&pAudioData);
    pAudioData->SetBuffer(DATA_SIZE, pBuffer, 0);
    pAudioData->SetFormat(&wfx);
    pAudioStream->CreateSample(pAudioData, 0, &pSample);
    HANDLE hEvent = CreateEvent(FALSE, NULL, NULL, FALSE);
    CWaveOut WaveOut(&wfx, 4, 2048);
    int iTimes;
    for (iTimes = 0; iTimes < 3; iTimes++) {
        DWORD dwStart = timeGetTime();
        for (; ; ) {
            HRESULT hr = pSample->Update(0, hEvent, NULL, 0);
            if (FAILED(hr) || MS_S_ENDOFSTREAM == hr) {
break;
            }
            WaitForSingleObject(hEvent, INFINITE);
            DWORD dwTimeDiff = timeGetTime() - dwStart;
            // 10 秒以内に限定する
            if (dwTimeDiff > 10000) {
break;
            }
            DWORD dwLength;
            pAudioData->GetInfo(NULL, NULL, &dwLength);
            WaveOut.Write(pBuffer, dwLength);
        }
        pMMStream->Seek(0);
    }

    pAudioData->Release();
    pSample->Release();
    pStream->Release();
    pAudioStream->Release();
    LocalFree((HLOCAL)pBuffer);

return S_OK;
}

HRESULT RenderFileToMMStream(
    WCHAR * pszFileName, IMultiMediaStream **ppMMStream)
{
IAMMultiMediaStream *pAMStream;
CoCreateInstance(CLSID_AMMultiMediaStream, NULL, CLSCTX_INPROC_SERVER,
IID_IAMMultiMediaStream, (void **)&pAMStream);
pAMStream->Initialize(STREAMTYPE_READ, AMMSF_NOGRAPHTHREAD, NULL);
    pAMStream->AddMediaStream(NULL, &MSPID_PrimaryAudio, 0, NULL);
    pAMStream->OpenFile(pszFileName, AMMSF_RUN);
*ppMMStream = pAMStream;
return S_OK;
}

int _CRTAPI1 main(int argc, char *argv[])
{
IMultiMediaStream *pMMStream;
CoInitialize(NULL);
    WCHAR wszName[1000];
    MultiByteToWideChar(CP_ACP, 0, argv[1], -1, wszName,
        sizeof(wszName) / sizeof(wszName[0]));
    RenderFileToMMStream(wszName, &pMMStream);
    RenderStreamToDevice(pMMStream);
pMMStream->Release();
CoUninitialize();
return 0;
}


SMPTE タイムコード

このトピックでは、SMPTE (Society of Motion Picture and Television Engineers) タイムコードについて解説する。プロダクション環境でのタイムコードの使用方法についても説明し、外部デバイスに依存するアプリケーションで代表的なものをいくつか示す。最後に、Microsoft® DirectShow® に外部デバイス制御を実装する方法を解説し、DirectShow で VCR 制御とタイムコードに対応したフィルタを作成するために使用できるインターフェイスへのリンクを与える。

このトピックは、以下のセクションで構成される。

  • SMPTE タイムコードについて
  • タイムコードの典型的な使用方法
  • タイムコードのキャプチャ
  • 外部デバイス制御
  • 参考書と補足資料

SMPTE タイムコードについて

SMPTE タイムコードは、ポストプロダクション処理をつなぎ合わせる接着剤である。ビデオおよびオーディオのソースを識別し、トラックの自動同期を可能にし、プロダクションに関連する補助データのコンテナを提供する。このデータ ストリームを理解すると共に、メディア プロダクション、ツール開発、またはシステム設計への応用について理解することが必要になる。

SMPTE タイムコードは、正確には SMPTE タイムおよび制御コードとして知られ、ANSI/SMPTE 12-1986 で定義されている。SMPTE タイムコードは、ビデオまたはオーディオ ストリームに適用されるデジタル フレームのアドレス値、フラグ、およびその他の一連のデータである。SMPTE タイムコードの目的は、マシンが判読可能なビデオまたはオーディオのアドレスを提供することである。

SMPTE タイムコード データ構造体の最も一般的なフォーマットは、以下の情報が含まれる 80 ビットのフレームである。

  • hh:mm:ss:ff (時間:分:秒:フレーム) フォーマットでのタイム スタンプ。
  • 一般にユーザービットとして知られる 8 個の 4 ビット バイナリ グループ。
  • さまざまなフラグ ビット。
  • 同期シーケンス。
  • チェックサム。

DirectShow の TIMECODE_SAMPLE 構造体は、ビデオ データやオーディオ データのタイムコード情報が含まれるタイムコード データ構造体の例である。

SMPTE タイムコードには 2 つのタイプがある。アナログ オーディオ トラックにバイフェーズ マークでエンコードされた信号として記録されるタイムコードは、LTC (Linear TimeCode、以前は Longitudinal TimeCode) と呼ばれる。タイムコードの各フレームは、時間幅内の 1 つのビデオ フレーム タイムである。タイムコードのもう 1 つの一般的なタイプは、VITC (Vertical TimeCode) と呼ばれる。通常、VITC はビデオ信号の垂直同期間隔のライン 10 ～ 20 の中の 2 ラインに格納される。

LTC タイムコードは、独立したオーディオ信号にエンコードされるので、録画済みのテープに簡単に追加できる。しかし、テープがポーズしていたり、超低速または超高速で動いているときは読み出すことができない。また、プロ仕様ではない VCR では 1 つのオーディオ チャンネルを消費する。

一方、VITC タイムコードは、通常速度の 0 ～ 15 倍の速度で読み出すことができる。フィールドに依存するデータを含むことができ、ビデオ キャプチャ カードから読み出すこともできる。しかし、録画済みのテープに追加するのは簡単ではなく、高価なハードウェアが必要になることが多い。

SMPTE タイムコードには 2 つのモードがある。ノンドロップ フレームとドロップ フレームである。ノンドロップ フレームは、一貫して増加しているシーケンシャルなタイムコードである。リアルタイム クロックの役割を果たすことができ、ちょうど 30 フレーム/秒のフレーム レートで再生される白黒ビデオの場合にうまく機能する。

ただし、NTSC カラー ビデオは白黒テレビとの互換性の問題のために、実際には 29.97 Hz (フレーム/秒) のフレーム レートで再生される。これによって、1 時間あたり 108 フレーム (3.6 秒) の割合で実際の時間と一致しなくなり、ノンドロップ フレーム タイムコードでは問題が発生する。つまり、開始点を 00:00:00:00 とすると、1 時間の再生後にタイムコードは 00:59:56:12 になるということだ。このため、表示時間幅を計算したり、"時刻" を参照したりすると問題が発生する。

この問題の解決策は、誤差が許容できるレベルになる程度にフレームを飛ばすことである。この補正法を "ドロップ フレーム" と呼び、00、10、20、30、40、および 50 分を除いて、1 分ごとに最初の 2 つのフレームを飛ばすことで実装する。最終的に、エラーは 1 フレーム/時間未満になり、24 時間あたり 3 フレーム程度になる。

何らかの実装で両モードの混合をサポートすべきだが、現在のプロダクションではドロップ フレームの使用がさらに一般的になっている。

タイムコードの典型的な使用方法

通常、ビデオ キャプチャと編集機能を提供するアプリケーションは、外部デバイスの制御を必要とする。これらのアプリケーションは、SMPTE タイムコードを参照して、ビデオおよびオーディオのフレームを識別し、インデックス付けをする必要がある。リニア編集システム コンピュータは、一般に 3 台以上のテープ装置とビデオ切替器を制御し、場合によってはデジタル ディスク レコーダも制御する。制御コンピュータは、正確な時期にコマンドを発行しなければならないので、ビデオテープを特定の時点で特定の場所に挿入しなければならない。

アプリケーションは以下のようなさまざまな方法でタイムコードを使用するが、方法はこれらに限定されるわけではない。

  • アーカイブまたはほかのシステムへのエクスポート用に EDL (Edit Decision List) を作成できるようにするための編集プロセスを通したビデオおよびオーディオ ソースの追跡。EDL は以下の手順で作成する。
    1. ビデオを撮影する。
    2. フレーム内だけの圧縮 (MJPEG、DV など) を使用するノンリニア オフライン システムにキャプチャする。
    3. 素材を編集し、EDL と、オフラインで編集したマスターを作成する。
    4. EDL をオンライン システムにインポートし、オリジナルのソースを使用して "自動粗編集" を行い、必要な場所にタイトルとエフェクトを追加して最終的なマスターを作成する。
  • オーディオのビデオへの同期。通常、後のフィルム プロダクションで、オーディオはタイムコードと共に別のテープ レコーダに録音される。特別装備のフィルム カメラも、フィルム上の送り穴の間にタイムコードを記録できる。撮影された画像が電子的にビデオテープに転送された後、"ラッシュの同期" と呼ばれるプロセスで、オーディオを映像と揃えるためにタイムコードが使用される。オーディオとビデオのタイムコードが異なる場合、VITC と LTC を併用できることがある。一方をビデオのタイムコード用に、他方をオーディオのタイムコード用に使用する。
  • ATR、デジタル ディスク レコーダまたはプレーヤー、VCR などの複数のデバイスの同期と起動。これは、前に説明したものより広いクラスの同期であり、リニアおよびノンリニア編集システム、クローズド キャプション システム、または字幕システムでごく一般的に見られる。
  • タイムコード内の"ユーザービット">と呼ばれる未定義ビットの使用。ユーザービットには、日付、ASCII コード、ムービー業界の情報などがよく入れられるが、ユーザービットの使用はユーザーの工夫だけに限定される。

タイムコードを正しく扱えば多くのことが可能になるが、残念ながら、技術の貧弱さやハードウェアの故障のために悪くなることも多い。タイムコードが含まれるテープについては、以下のようなことに気を付けなければならない。

  • ビデオまたはオーディオに関して安定しない、またはドリフトするタイムコード。
  • タイムコード フィールドの整合性の低さ。これは、LTC ワードがフレームの開始部ではなく中央から始まったり、実際のフレーム境界上で VITC が更新されなかったりすることを意味する。結果として、あいまいな参照が生じる。
  • 意図しない VITC/LTC の食い違い。
  • 断続的なドロップアウト。
  • タイムコードの欠落。
  • タイムコードの信号品質の悪さ。
  • 不適切なコピーによるフレーム オフセットの増加。

タイムコードのキャプチャ

タイムコードは、外部のタイムコード ジェネレータや、タイムコードを生成できるキャプチャ カード、デバイス制御フィルタ自体、またはタイムコード リーダーが組み込まれている VCR などのデバイスによって生成できる。外部デバイスがタイムコードをホストに送信する場合、通常は RS-422 接続が必要である。

タイムコードが生成されたら、後で編集中にアクセスできるように、ビデオまたはオーディオと共にテーブルまたはストリーム フォーマットでタイムコードをキャプチャする必要がある。これを処理するには、以下の 2 とおりの方法がある。

1. ストリーム内のフレーム位置にインデックス付けされた、タイムコードの不連続性のリストを示すテーブルを作成し、キャプチャが完了した後で、そのテーブルをファイルの最後に書き込む。このリストは、以下のような構造体の配列になるだろう (この構造体は、DirectShow の TIMECODE_SAMPLE 構造体を簡略化したもので、例として示すだけであることに注意してほしい)。

struct    {
        DWORD dwOffset;   // フレーム内のストリームへのオフセット
        char[11] szTC;    // オフセット位置における hh:mm:ss:ff フォーマットでのタイムコードの値
                          // ノンドロップの場合は hh:mm:ss。ff はドロップ フレーム用
        } TIMECODE;

たとえば、タイムコード ブレークが 1 つ入ったビデオ ストリームをキャプチャしたとすると、リストは以下のようになると思われる。

{0, 02:00:00:02},
{16305, 15:21:13:29}        // タイムコードはフレーム 16305 でジャンプする

このテーブルを使えば、任意のフレームのタイムコードを簡単に計算できる。

2. データをストリームとして扱い、ビデオやオーディオを書き込むようにデータをファイルに書き込む。これは、急速に変化するデータの場合に便利で、クローズドキャプション データなど、垂直同期間隔 (VBI) 内のタイムコードのないデータの場合にも便利である。

タイムコード データがそれに関連するフレーム データと共に正しく格納されたら、編集、合成、同期、または起動するアプリケーションは、よく知られた標準のインデックス システムにアクセスしてそれを使用することができる。

外部デバイス制御

デバイス制御フィルタを実装すると、DirectShow で外部デバイスを制御することができる。これらのフィルタは、完全にコンピュータの外部にあり、IAMExtDevice、IAMExtTransport、IAMTimecodeGenerator、IAMTimecodeReader などのインターフェイスを公開しているデバイスやデータ ストリームを制御する。通常、外部デバイス制御フィルタはピンを公開する必要はないが、ピンを公開する外部デバイス制御フィルタの例として、VCR などのデータのソースを表すフィルタがある。VCR からキャプチャ ボードへ流れるデータを表すピン間の接続によって、デバイス制御フィルタとビデオ キャプチャ フィルタが、互いに通信してデータ型を交渉することが可能になる。ただし、これらは標準の転送を使用せず、フィルタ間に制御情報以外のデータは流れない。アプリケーションは、外部デバイス フィルタのインスタンスを生成して直接制御することができるが、フィルタ グラフのコンテキスト内では、グラフ内の唯一のフィルタである場合でもフィルタを常にインスタンス化しておくことを強くお勧めする。

外部デバイスには、VCR、ビデオ編集ステーション、オーディオ テープ レコーダ (ATR)、ミキサー、またはビデオのキャプチャや編集で使用するその他のデバイスがある。キャプチャや編集では、DirectShow の外部デバイス制御フィルタでオーディオとビデオの同期をとり、正確に制御する必要がある。再生、編集、およびキャプチャの間、外部クロックや SMPTE タイムコードによってオーディオとビデオの同期をとることができる。

外部デバイス制御を理解するには、タイムコードを理解する必要がある。タイムコードについては、基本事項として以下のことを覚えておかなければならない。

  • SMPTE タイムコードは、ビデオおよびオーディオ フレームを識別するためのフレーム アドレッシング システムである。これには、LTC、VITC、ドロップ フレーム、ノンドロップ フレームなどの多くのタイプとモードがあり、24、25、29.97、30 フレーム/秒といったさまざまなフレーム レートで機能する。
  • SMPTE タイムコードは EDL で使用される。EDL は、ハードウェア デバイスを同期するためのタイミング基準として、またプロダクション ソースやフィルム参照情報などの追加データの媒体として、オフラインおよびオンライン編集用に生成される。
  • SMPTE タイムコードは、ストリームまたは不連続性のテーブルとして格納できる。
  • タイムラインは同期のために必要であり、制御コンピュータ、外部同期装置、または被制御デバイス自体にローカルなものであってもよい。

これらのことを考えると、デバイス制御には 2 つの根本的な問題がある。第 1 に、さまざまなメーカーのさまざまなデバイス用に、何百種類もの通信プロトコルが存在する。VCR やレーザー ディスク プレーヤーのように、ほかのデバイスより広く使用されているものもあるが、ほぼすべてのデバイスが異なるリモート コントロール インターフェイスを持っている。さらに洗練されたプロ仕様のビデオおよびオーディオ アプリケーションが小型化するにつれて、この問題はますます大きくなっている。これら無数のプロトコルのために、制御する外部デバイスごとに別々の DirectShow フィルタを実装しなければならない。

第 2 に、プロ仕様のビデオおよびオーディオ システムの設計では、イベントが正確な時点で発生しなければならないという問題がある。この問題の概要を見るために、次のタイミング図を考えてみよう。

ビデオ プロダクション システムの基本的なタイミング図

水平軸はビデオ フィールド内の時間を示す。NTSC ビデオの場合、これは約 1/60 秒である。ここで重要なのは、すべての信号が時間順に並んでいること、すなわちタイムコードはフレームの先頭から開始される点である (システム フレーム パルス)。テープ装置などの外部デバイスは、AVI 対応アプリケーションから実行された AVI ファイルなどのデジタル ビデオ再生と共に、システム基準によって並べられる。

このタイミング要件に適合させるにはさまざまな方法があるが、最も一般的なのは、システム内のすべてのコンポーネントにマスター基準信号を配布する方法である。この基準は、ビデオの世界では"ブラックバースト"として知られ、ブラック レベルを超えるアクティブなビデオが含まれないコンポジット ビデオ信号であることからこう呼ばれる。名前の "バースト" の部分は、ビデオ信号のカラー バースト部分を指している。この基準に接続された各デバイスは、自身の同期を維持しなければならない。すなわち、デジタル ビデオ プレーヤーは垂直同期間隔間にフレームを切り換えなければならず、テープ装置は垂直同期間隔間は録画モードに切り換えなければならず、シリアル ポートを通じて外部デバイスに送信されるコマンドはフレーム パルスに合わせなければならない。そして、これらすべてとその他の同期イベントは、SMPTE タイムコードに定義済みの値が現れたときに発生しなければならない。これらの規則に適合させられなければ、ビデオ画像にテアリングが発生したり、具合の悪いときに編集が発生したりする。

プロ仕様のビデオの世界でこれを実現するのは比較的簡単だが、混成されたデスクトップ ビデオの世界では実現は非常に難しい。

これまでに与えた考え方に基づき、次の 2 つの設計例に外部デバイスの設定を示す。

単一 VCR デジタル ビデオ編集システムの基本ブロック図

複数 VCR デジタル ビデオ編集システムの基本ブロック図

これらのブロック図を見れば、すべてのボックスに基準信号を配布するのは比較的簡単であることがわかる。たとえば、タイムコード リーダーとデジタル ビデオ プレーヤーの間など、コンピュータ内部で行われる同期を扱うには、オペレーティング システムの専用サービスである "垂直駆動" のハードウェア割り込み、またはその他のカスタム ソリューションを使用することをお勧めする。

最後に、外部デバイスを制御するフィルタを書く場合は、IAMExtDevice および IAMExtTransport インターフェイスを実装しなければならない。フィルタがタイムコードを読み込んだり生成したりする場合は、DirectShow が提供するインターフェイス、IAMTimecodeReader、IAMTimecodeGenerator、および IAMTimecodeDisplay も実装しなければならない。さらに、外部デバイスのマイクロプロセッサ用の実行モジュール コードをダウンロードして実行する場合のように、外部デバイスとの間でバイナリ メッセージをやりとりすることが必要な場合は、COM IDataObject インターフェイスを実装することでそれを行わなければならない。このインターフェイスには、バイナリ データの転送を扱うためのメソッドがすべて揃っている。フィルタに必要な独自のデータ転送には、このインターフェイスを使用する。

参考書と補足資料

SMPTE タイムコードと外部デバイス制御の補足資料としては、以下のようなドキュメントがある。

  • Proposed revision to ANSI/SMPTE 12M-1986, SMPTE Standard for Television, Audio and Film Time and Control Code, SMPTE Journal, February 1995.
  • SMPTE RP 135-1990 "Use of Binary User Groups in Motion-Picture Time and Control Codes"
  • SMPTE RP 169 "Television, Audio and Film Time and Control Code—Auxiliary Time Address Data in Binary Groups—Dialect Specification of Directory Index Locations"
  • SMPTE RP 179-1994 "Dialect Specification of Page-Line Directory Index for Television, Audio and Film Time and Control Code for Video-Assisted Film Editing"
  • "Touring the Vertical Interval", Warner Johnston, TV Technology, August 1991
  • "Closed Captioning in Real Time", Marc Oakrand, SMPTE Journal, June 1991
  • Timecode Handbook, 3rd. Edition, Cipher Digital, Inc. (available from Mix Bookshelf)
  • Timecode: A User's Guide, John Ratcliffe (available from Mix Bookshelf)
  • SMPTE RP 138—Control Message Architecture
  • SMPTE RP 139—Tributary Interconnection
  • SMPTE RP 163—System Service Messages
  • SMPTE RP 170—Video Tape Recorder Type Specific Messages for Digital Control Interface
  • SMPTE RP 171—Type-Specific Messages for Digital Control Interface of Analog Audio Tape Recorders
  • SMPTE RP 172—Common Messages for Digital Control Interface
  • SMPTE 275M—ESlan-1 Remote Control System

SMPTE の規格とリプリントは、(914) 761-1100 (米国) に電話すると SMPTE から入手できる。


Visual Basic での DirectShow の使い方

ここでは、Microsoft® Visual Basic® を使用して Microsoft® DirectShow® アプリケーションを作成する方法について説明する。内容は次のとおりである。

  • Visual Basic を使用したフィルタ グラフの作成
  • Visual Basic を使用したフィルタ グラフの制御
  • Visual Basic オブジェクト


Visual Basic を使用したフィルタ グラフの作成方法

ここでは、Microsoft® Visual Basic® を使用してフィルタ グラフのコンポーネントを管理する方法について説明する。

この内容は、Microsoft® Windows® でのアプリケーション プログラミング、Windows ベースのマルチメディア プログラミング、および Visual Basic プログラミング システムの Automation 機能について既に理解している Visual Basic の開発者を対象にしている。

ここでは次の内容について説明する。

  • DirectShow Quartz.dll オブジェクトについて
  • フィルタ グラフの作成
  • 完全なフィルタ グラフの生成
  • 新しいフィルタ グラフの作成とフィルタの追加
  • フィルタ ピンの接続
  • ピン接続情報の表示
  • まとめ

DirectShow Quartz.dll オブジェクトについて

Quartz.dll は、Visual Basic ベースのアプリケーションでフィルタおよびピンを管理するオブジェクトを提供する。それらのオブジェクト間には暗黙的な階層が存在する。つまり、多くの場合、オブジェクトを取得するには別のオブジェクトのプロパティにアクセスする必要がある。次の例で、オブジェクトの下に別のオブジェクトがインデントして示されている場合、その下位レベル オブジェクトは、上位レベル オブジェクトのプロパティまたはメソッドから取得する必要がある。

Filter graph object (IMediaControl)
  Filter collection (RegFilterCollection, FilterCollection properties)
    Filter Info object (IFilterInfo or IRegFilterInfo in filter collection)
      Pin collection (Pins property)
        Pin Info object (IPinInfo item in pins collection)

階層の最上位レベル オブジェクトは、フィルタ グラフ オブジェクトつまり IMediaControl オブジェクトであり、フィルタ グラフ全体を表す。IMediaControl オブジェクトの 2 つのプロパティにアクセスすることによって、フィルタ オブジェクトのコレクションを取得できる。RegFilterCollection プロパティは、システムに登録されているフィルタを表す。FilterCollection プロパティは、フィルタ グラフの一部であるフィルタを表す。

Visual Basic でアクセス可能なほかのコレクションと同様に、Visual Basic の for each...next ステートメントを使ってコレクション内の個々の項目にアクセスできる。コレクション内の項目の数は、コレクションの Count プロパティによって示される。

フィルタ コレクションには、IFilterInfo オブジェクトが含まれている。各 IFilterInfo オブジェクトは、そのフィルタに対して定義されているピンのコレクションを表す Pins プロパティを持つ。

ピン コレクションには、IPinInfo オブジェクトが含まれている。各 IPinInfo オブジェクトは、メディア タイプや別のピンへの接続など、そのピンに関する詳細情報を含む。

フィルタ グラフ内のフィルタの特定のピンについて調べるには、次の手順を実行する。

  1. フィルタ グラフ オブジェクトを取得する。
  2. フィルタ グラフ オブジェクトの IMediaControl.FilterCollection プロパティを使用して、フィルタ グラフ内に存在するフィルタのコレクションを取得する。
  3. フィルタ コレクション内の特定のフィルタを検索する。
  4. フィルタ オブジェクトの IFilterInfo.Pins プロパティを使用して、そのフィルタに対して定義されているピンのコレクションを取得する。
  5. ピン コレクション内の特定のピンを検索する。
  6. ピン オブジェクトのプロパティを調べて、ピンの接続情報およびその他の情報を見つける。

フィルタ グラフの作成

Quartz.dll を使用してフィルタ グラフを作成するには、異なる 3 つの方法がある。それぞれの方法でフィルタ グラフに対する制御の度合いが異なり、フィルタ グラフ全体を自動生成することから、すべてのフィルタとピン接続を指定することまで可能である。3 つの方法を次に示す。

  • 自動 : マルチメディア ソースまたは保存されているフィルタ グラフのファイルから完全なフィルタ グラフを生成する。
  • 半自動 : 新しい (空の) フィルタ グラフを作成して 1 つ以上のフィルタを追加し、特定のピンをレンダリングするために必要なすべてのフィルタと接続を自動的に生成する。
  • 手動 : 新しい (空の) フィルタ グラフを作成し、グラフに個々のフィルタを追加し、ピンの間の接続を明示的に追加する。

完全なフィルタ グラフの生成

次の例は、コードの一部分であり、マルチメディア ソースまたは保存されているフィルタ グラフに基づいて完全なフィルタ グラフを生成する方法を示している。アプリケーションでは、IMediaControl オブジェクト (最初は "空") を作成した後、IMediaControl.RenderFile メソッドを呼び出して完全なグラフを構築する。

' 最初に新しい空のフィルタ グラフを作成する
Dim g_objMC as IMediaControl       ' 汎用宣言セクションから
...
Set g_objMC = New FilgraphManager  ' 新しいフィルタ グラフを作成する
...
' 共通のファイルを開くダイアログ ボックスを使用してユーザーに入力ファイルを選択させる
CommonDialog1.ShowOpen             ' ユーザーがソースまたはフィルタ グラフを選択する
' IMediaControl.RenderFile を呼び出してすべてのフィルタを追加し、すべてのピンを接続する
g_objMC.RenderFile CommonDialog1.filename  ' 完全なグラフを生成する

新しいフィルタ グラフの作成とフィルタの追加

次の例は、コードの一部分であり、新しい (空の) フィルタ グラフ オブジェクトを作成する方法を示している。

Dim g_objMC as IMediaControl  ' 汎用宣言セクションから
    ...
Set g_objMC = New FilgraphManager  ' 新しいフィルタ グラフを作成する

空のフィルタ グラフを作成して個々のフィルタを追加する場合は、フィルタ タイプがわかっている必要がある。通常、フィルタには 3 つのカテゴリがある。ソース フィルタ、変換フィルタ、およびレンダリング フィルタの 3 つである。ソース フィルタを追加する手順では、変換フィルタおよびレンダリング フィルタを追加する手順とは異なるメソッドを使用する。

フィルタ グラフにソース フィルタを追加する。そのためには、IMediaControl.AddSourceFilter メソッドを呼び出し、指定のソース タイプまたは保存されているフィルタ グラフのファイルの名前を指定する。

Dim objFilter As Object  ' 有効な構文用の一時オブジェクト; 使用しない

CommonDialog1.ShowOpen  ' ソースまたはフィルタ グラフ ファイルの名前を取得する
g_objMC.AddSourceFilter CommonDialog1.filename, objFilter

IRegFilterInfo.Filter メソッドを呼び出して、フィルタ グラフに変換フィルタおよびレンダリング フィルタを追加する。IRegFilterInfo オブジェクトは、IMediaControl.RegFilterCollection プロパティから取得できる。このプロパティは、システムに登録されていて利用可能なフィルタ オブジェクトのコレクションを表す。

フィルタ グラフを作成して IMediaControl オブジェクトを取得した後、次の手順に従ってフィルタを追加する。

  1. 登録済みフィルタの一覧を取得するために、IMediaControl.RegFilterCollection プロパティを取得する。
  2. コレクションで目的のフィルタを検索する。コレクション内の各要素は IRegFilterInfo オブジェクトである。
  3. フィルタ グラフにフィルタを追加するために、IRegFilterInfo.Filter メソッドを呼び出す。

次の例は、コードの一部分で、この手順の 1 と 2 に対応する。

' 登録したフィルタ リスト ボックスにデータを挿入するコードの一部分
' グローバル変数 g_objRegFilters に IMediaControl.RegFilterCollection を設定する
' g_objRegFilters = g_objMC.RegFilterCollection と設定する
Dim filter As IRegFilterInfo
    listRegFilters.Clear
    If Not g_objRegFilters Is Nothing Then
        For Each filter In g_objRegFilters  ' コレクション内のフィルタごとに
            listRegFilters.AddItem filter.Name ' 名前をリスト ボックスに追加する
Next filter
End If

次の例は、コードの一部分で、手順 3 に対応する。

Dim filter As IRegFilterInfo
' 選択したフィルタを検索してグラフに追加する
' g_objRegFilters は IMediaControl オブジェクトの RegFilterCollection プロパティ
For Each filter In g_objRegFilters
    If filter.Name = listRegFilters.Text Then  ' 選択したフィルタか?
        Dim f As IFilterInfo  ' 答えが yes なら
        filter.filter f  ' フィルタ グラフに追加、IFilterInfo f を返す
        If f.IsFileSource Then
            CommonDialog1.ShowOpen
            f.filename = CommonDialog1.filename
End If
        Exit For
End If
Next filter

フィルタ ピンの接続

フィルタ グラフに個々のフィルタを追加した後、各ピンを明示的に接続するか、特定のピンからダウンストリームに必要なすべての接続を自動的に生成して、フィルタ間の接続を確立できる。

いずれの場合も、Microsoft® DirectShow® オブジェクトの階層を走査して、フィルタ オブジェクトのピンを表す IPinInfo オブジェクトを取得する必要がある。そのためには、フィルタ グラフ オブジェクトのフィルタ コレクション内で目的のフィルタを見つけ、次にフィルタ オブジェクトのピン コレクション内で目的のピンを見つける。

ここでは次の内容について説明する。

  • フィルタ グラフのフィルタの一覧表示
  • フィルタに対して定義されているピンの一覧表示
  • 2 つのピンの明示的な接続
  • ピンの自動接続

フィルタ グラフのフィルタの一覧表示

フィルタ グラフ内のすべてのフィルタは、IMediaControl.FilterCollection プロパティを使用してアクセスできるコレクション内のフィルタとして利用可能である。

' グラフ内の現在のフィルタを含むリスト ボックスを最新の状態に更新する
listFilters.Clear
For Each objFI In g_objMC.FilterCollection
    listFilters.AddItem objFI.Name ' リスト ボックスに追加する
Next objFI

フィルタに対して定義されているピンの一覧表示

フィルタ オブジェクトに対して定義されているピンは、IFilterInfo.Pins プロパティを使用してアクセスできる。Pins プロパティは、個々の IPinInfo オブジェクトのコレクションである。

コレクションから個々の IPinInfo オブジェクトを取得した後、オブジェクトのプロパティにアクセスし、オブジェクトのメソッドを呼び出すことができる。次の例は、これを示すコードの一部分である。

For Each objPin In g_objSelFilter.Pins
If objPin.Name = listPins.Text Then  ' 選択したピンか?
    Set g_objSelPin = objPin ' 答えが yes なら、情報を更新する
    ' ... そのピンを使用して操作を実行する
End If
Next objPin

ピン オブジェクトを取得した後、もう 1 つのピンに明示的に接続するか、ピンをレンダリングするために必要な残りのピン接続すべてを自動的に生成できる。

2 つのピンの明示的な接続

IPinInfo オブジェクトは、ピンを接続する 3 つのメソッドを提供する。Connect、ConnectDirect、および ConnectWithType である。Connect は、必要に応じてほかの変換フィルタを追加する。ConnectDirect は変換フィルタを追加しない。ConnectWithType は、指定されたピンが指定されたメディア タイプに一致する場合にのみ、接続を実行する。

frmSelectPin.OtherDir = g_objSelPin.Direction
Set frmSelectPin.Graph = g_objMC             ' そのフォームにグラフのコピーと
Set frmSelectPin.SelFilter = g_objSelFilter  ' 現在のフィルタを渡す
frmSelectPin.RefreshFilters                  ' 接続できるフィルタを表示する
frmSelectPin.Show 1                          ' フォームを表示する
If frmSelectPin.bOK Then        ' ユーザーがフォームを選択--OK ボタンが使用された
    Dim objPI As IPinInfo
    Set objPI = frmSelectPin.SelPin          ' フォームから新しいピンを取得する
    g_objSelPin.Connect objPI                ' 2 つのピンを接続する
    RefreshFilters                           ' ピンの最新情報を表示する
End If

ピンの自動接続

ピンのダウンストリームに必要なフィルタ グラフのすべての部分を自動的に生成するには、IPinInfo.Render メソッドを呼び出す。

ダウンストリームという用語は、そのピンからレンダリング フィルタまでの完全なパスを構築するために必要なすべての接続を意味する。たとえば、GraphEdit ユーティリティによるフィルタ グラフの表現を考える。これは、左側のソース フィルタから右側のレンダリング フィルタまで移動する接続を示す。Render メソッドは、指定されたピンの右に必要なすべてのフィルタと接続を追加する。

' IPinInfo.Render を呼び出す
' このピンからダウンストリームにグラフを完成する
' g_objSelPin は 'Pins' とラベル付けされたリスト ボックスで選択されたピンを参照する
    g_objSelPin.Render

ピン接続情報の表示

フィルタ オブジェクトの IFilterInfo.Pins プロパティからアクセス可能なコレクションのピン オブジェクトを取得した後、接続およびその他の情報を一覧表示できる。

  Dim strTemp As String
  On Error Resume Next
  Dim objPin As IPinInfo
For Each objPin In g_objSelFilter.Pins
    If objPin.Name = listPins.Text Then    ' リスト ボックスで選択されたか?
      Set g_objSelPin = objPin             '答えが yes なら、すべての情報を取得する
      strTemp = ""               ' 既存の表示されているピンの情報を消去する
      Dim objPinOther As IPinInfo
      Set objPinOther = objPin.ConnectedTo
      If Err.Number = 0 Then               ' yes、接続がある
        strTemp = "Connected to pin: " + objPinOther.Name + " "
        Dim objPeer As IFilterInfo
        Set objPeer = objPinOther.FilterInfo
        strTemp = strTemp + " on filter: " + objPeer.Name + " "
        Dim objMTI As IMediaTypeInfo
        Set objMTI = objPin.ConnectionMediaType
        strTemp = strTemp + vbCrLf + "Media Type: " + objMTI.Type
End If
      If objPin.Direction = 0 Then
strTemp = strTemp + " " + vbCrLf + "Direction: Input"
      Else
strTemp = strTemp + " " + vbCrLf + "Direction: Output"
End If
    txtPinInfo.Text = strTemp
End If
Next objPin

まとめ

ここで説明した DirectShow オブジェクト、プロパティ、およびメソッドの使い方を次にまとめて示す。
タスク | DirectShow のプロパティまたはメソッド
新しい空のフィルタ グラフを作成する。 | objMediaControl = New FilgraphManager を設定する。
特定のファイルの完全なフィルタ グラフを生成する。 | IMediaControl.RenderFile メソッドを呼び出す。
ソース フィルタを追加する。 | IMediaControl.AddSourceFilter メソッドを呼び出す。
レンダリング フィルタまたは変換フィルタを追加する。 | IMediaControl.RegFilterCollection プロパティを使用して IRegFilterInfo オブジェクトを取得する。 IRegFilterInfo.Filter メソッドを呼び出す。
フィルタ オブジェクトのピンを一覧表示する。 | IFilterInfo.Pins プロパティを使用して IPinInfo オブジェクトを取得する。
2 つのピンを明示的に接続する。 | IPinInfo.Connect メソッドを呼び出す。
ピンからレンダリング フィルタまでのすべての接続を作成する。 | IPinInfo.Render メソッドを呼び出す。


Visual Basic を使用したフィルタ グラフの制御方法

ここでは、Microsoft® DirectShow® のダイナミック リンク ライブラリである Quartz.dll によって公開されているメソッド、イベント、およびプロパティを使用して、Microsoft® Visual Basic® ベースのアプリケーションでタイム スタンプ付きのビデオ データのストリームをレンダリングする方法を説明する。この内容は、Microsoft® Windows® ベースのアプリケーション プログラミング、Windows ベースのマルチメディア プログラミング、および Visual Basic プログラミング システム バージョン 5.x の Automation 機能について既に理解している開発者が対象である。

ここでは次の内容について説明する。

  • DirectShow のフィルタとフィルタ グラフ
  • DirectShow インターフェイスにアクセスするために Quartz.dll を登録する方法
  • Visual Basic でのフィルタ グラフの制御

DirectShow のフィルタとフィルタ グラフ

アプリケーションで Quartz.dll を使用してマルチメディアを表示するには、フィルタと呼ばれるオブジェクトのコレクションを使用する。このコレクションはフィルタ グラフとも呼ばれる。次の図は、AVI (Audio-Video Interleaved) ファイルをレンダリングするフィルタ グラフを示している。

AVI フィルタ グラフ

この図では、AVI ソース フィルタがディスクからファイルを読み取る。AVI デコンプレッサ フィルタ (CODEC) は、ソース フィルタから渡されたビデオ データを圧縮解除する。次に、CODEC フィルタはこのデータをビデオ レンダラに渡す。その次に、ビデオ レンダラはデバイスが認識できるフォーマットのデータをデバイスに渡す。AVI ソース フィルタはオーディオ レンダラに直接オーディオ データを渡し、オーディオ レンダラはオーディオ デバイスにデータを渡す。

DirectShow は、フィルタのほかにも、フィルタ グラフ マネージャと呼ばれる Automation オブジェクトをサポートしている。このオブジェクトは、利用可能なフィルタについて知っている。また、どのファイル フォーマットをレンダリングするためにどのフィルタ タイプが必要かを認識している。フィルタ グラフ マネージャは、特定のグラフ内のフィルタがサポートしているメソッド、イベント、およびプロパティを公開する。さらに、独自のメソッド、イベント、およびプロパティのセットを、インターフェイスを使用して公開する。インターフェイスは、関連したメソッド、イベント、およびプロパティのコレクションである。

次の表では、Visual Basic ベースのアプリケーションで使用する、Quartz.dll に提供されている DirectShow のインターフェイスを示し、各インターフェイスの目的を説明する。
インターフェイス | 説明
IAMCollection | ピン コレクションおよびフィルタ コレクションにアクセスする。
IBasicAudio | 現在のボリューム設定を制御し、取得する。
IBasicVideo | 汎用ビデオ レンダラを制御する。
IFilterInfo | フィルタに関する情報、およびフィルタ内のピン オブジェクトに関する情報を取得する。
IMediaControl | フィルタ グラフをインスタンス化し、メディア フロー (実行、ポーズ、停止) を制御する。
IMediaEvent | 再ペイント、ユーザー終了、完了などのイベントに対するカスタマイズしたイベント処理を可能にする。
IMediaPosition | 開始タイム、終了タイム、レート、および現在位置を制御し、取得する。
IMediaTypeInfo | メディア タイプとサブタイプを取得する。
IPinInfo | ピンの方向やメディア タイプなどのピン情報にアクセスし、ピンの接続、切断、およびレンダリングを制御する。
IRegFilterInfo | 登録済みの (変換およびレンダリング) フィルタに関する情報を含む。
IVideoWindow | ビデオ レンダラのウィンドウ アスペクトを制御する。

DirectShow インターフェイスにアクセスするために Quartz.dll を登録する方法

Microsoft Visual Basic ベースのアプリケーションで DirectShow のインターフェイスを使用するには、Visual Basic プロジェクトで Microsoft® ActiveMovie® コントロール タイプ ライブラリを登録する必要がある。そのためには、[プロジェクト] メニューの [参照設定] をクリックし、次に [ActiveMovie control type library] の左のチェック ボックスをオンにする。

Visual Basic の [参照設定] ダイアログ ボックスを使用して ActiveMovie コントロール タイプ ライブラリを登録することによって、Visual Basic に必要な Automation 情報を含むタイプ ライブラリを特定する。次の図に [参照設定] ダイアログ ボックスを示す。

Visual Basic の [参照設定] ダイアログ ボックス

タイプ ライブラリを登録した後、[オブジェクト ブラウザ] ダイアログ ボックスを使用して、特定のインターフェイスに関連したメソッド、イベント、およびプロパティの一覧を表示できる。[表示] メニューの [オブジェクト ブラウザ] をクリックし、次に、[オブジェクト ブラウザ] ダイアログ ボックスの左上にあるライブラリのドロップダウン リストから [QuartzTypeLib] を選択する。

注 : QuartzTypeLib 内のタイプ情報は、オブジェクト別ではなくインターフェイス別に編成されている。

Visual Basic でのフィルタ グラフの制御

ここでは次の内容について説明する。

  • ファイルのインストール
  • Visual Basic への Quartz.dll の登録
  • DirectShow のオブジェクトを使用するための準備
  • フィルタ グラフのインスタンス化
  • ビデオのレンダリング
  • オーディオの制御
  • ビデオ出力のスケーリングと移動
  • 状態の追跡
  • 開始位置の取得と設定
  • レートの取得と設定
  • クリーン アップ

ファイルのインストール

Visual Basic ベースのアプリケーションで DirectShow オブジェクトを使用するには、Windows\System ディレクトリに Quartz.dll をインストールし、システムのレジストリ データベースに適切な項目が作成されたことを確認する必要がある。現在、このプロセスは Microsoft® DirectX® Software Development Kit (SDK) セットアップ プログラムによって自動化されている。インストールするには、Setup.exe を起動し、Runtime オプションを選択する。ダイナミック リンク ライブラリ (DLL) が正しい場所にコピーされ、レジストリが自動的に更新される。

Visual Basic への Quartz.dll の登録

ファイルが正しくインストールされたことを確認するには、Visual Basic アプリケーションを開き、[表示] メニューの [参照設定] コマンドをクリックする。起動時に Visual Basic によってレジストリ データベースの登録済み Automation コントロールが確認され、このダイアログ ボックスに表示される一覧にコントロールの名前が追加される。フィルタ グラフ マネージャを使用するには、[ActiveMovie control type library] をクリックする。

Visual Basic にタイプ情報が登録されると、アプリケーションでフィルタ グラフ マネージャおよび関連するインターフェイスを使用できる。

DirectShow のオブジェクトを使用するための準備

Visual Basic は、FilgraphManager オブジェクトを使用してすべてのオブジェクトを初期化する。FilgraphManager オブジェクトは次のインターフェイスを実装する。

  • IBasicAudio
  • IBasicVideo
  • IMediaControl
  • IMediaEvent
  • IMediaPosition
  • IVideoWindow

各インターフェイスには、そのインターフェイス タイプとして定義した Visual Basic のプログラム可能なオブジェクトからアクセスする。オブジェクトは、次の例に示すように、汎用宣言セクションでグローバル変数として定義できる。

Dim g_objVideoWindow As IVideoWindow            ' VideoWindow オブジェクト
Dim g_objMediaControl As IMediaControl          ' MediaControl オブジェクト
Dim g_objMediaPosition As IMediaPosition        ' MediaPosition オブジェクト
Dim g_objBasicAudio  As IBasicAudio             ' Basic Audio オブジェクト
Dim g_objBasicVideo As IBasicVideo              ' Basic Video オブジェクト

次の例に示すように、FilgraphManager を使用してすべてのプログラム可能なオブジェクトを初期化する。

Set g_objMediaControl = New FilgraphManager
g_objMediaControl.RenderFile (g_strFileName)    ' 入力ファイルの名前
...
Set g_objBasicAudio = g_objMediaControl
Set g_objVideoWindow = g_objMediaControl
Set g_objMediaEvent = g_objMediaControl
Set g_objMediaPosition = g_objMediaControl

目的のインターフェイスを明示的に返すメソッドを呼び出すことによって、ほかのインターフェイスを取得する。次の表は、これらのインターフェイスの取得方法を示している。
インターフェイス | インターフェイス ポインタを返すメソッド
IAMCollection | IPinInfo.MediaTypes、IFilterInfo.Pins、IMediaControl.FilterCollection、IMediaControl.RegFilterCollection
IFilterInfo | 最初に IMediaControl.FilterCollection、次に IAMCollection.Item または IPinInfo.FilterInfo
IMediaTypeInfo | IPinInfo.ConnectionMediaType
IPinInfo | IFilterInfo.FindPin、IAMCollection.Item
IRegFilterInfo | 最初に IMediaControl.RegFilterCollection、次に IAMCollection.Item

これらのフィルタ インターフェイスおよびピン インターフェイスの操作方法を示す例については、「Visual Basic を使用したフィルタ グラフの作成」を参照すること。

フィルタ グラフのインスタンス化

フィルタ グラフ マネージャを使用して、次のタイプの既存ファイルをレンダリングできる。

  • .avi (Audio-Video Interleaved)
  • .mov (Apple® QuickTime®)
  • .mpg (Motion Picture Experts Group)

さらに、フィルタ グラフ マネージャを使用して既存のフィルタ グラフをレンダリングできる。そのためには、そのグラフを含むファイルを RenderFile メソッドのパラメータとして指定する。

フィルタ グラフ内のフィルタはレンダリングするファイルのタイプに依存するため、ユーザーがファイルを選択してからフィルタ グラフをインスタンス化すること。フィルタ グラフ マネージャは、Visual Basic のキーワード New を使用して AUTOMATION オブジェクトを作成するときにインスタンス化される。フィルタ グラフ オブジェクトは、次の例に示すように、IMediaControl::RenderFile メソッドを呼び出したときに作成される。

    '要求されたファイル フォーマットのフィルタ グラフを
    'インスタンス化する

    Set g_objMediaControl = New FileGraphManager
    g_objMediaControl.RenderFile (g_strFileName)

ビデオのレンダリング

IMediaControl インターフェイスは 3 つのメソッドをサポートしている (Run、Pause、および Stop)。アプリケーションでは、これらのメソッドを呼び出してビデオ ストリームをレンダリング、ポーズ、または停止することができる。フィルタ グラフ オブジェクトがインスタンス化された後、アプリケーションでこれらのメソッドを呼び出すことができる。

次のコード例は、ユーザーがボタンをクリックしたとき、それに応答して Run、Pause、および Stop メソッドを起動する。

Private Sub Toolbar1_ButtonClick(ByVal Button As Button)
' ツール バーのボタンを処理する

    ' オブジェクトが定義されていない場合はエラーを回避する
    If g_objMediaControl Is Nothing Then
Exit Sub
End If

    If Button.Index = 1 Then 'PLAY
        'MediaControl Run() メソッドを呼び出して
        'ビデオを再生する (あらかじめ定義された
        'フィルタ グラフを使用)

        g_objMediaControl.Run
        g_fVideoRun = True

    ElseIf Button.Index = 2 Then 'PAUSE
        'MediaControl Pause() メソッドを呼び出して
        '表示中のビデオをポーズする (ビデオの表示には
        'あらかじめ定義されたフィルタ グラフを使用)

        g_objMediaControl.Pause
        g_fVideoRun = False

    ElseIf Button.Index = 3 Then 'STOP

        'MediaControl Stop() メソッドを呼び出して
        '表示中のビデオを停止する (ビデオの表示には
        'あらかじめ定義されたフィルタ グラフを使用)

        g_objMediaControl.Stop
        g_fVideoRun = False
        ' ビデオの先頭にリセットする
        g_objMediaPosition.CurrentPosition = 0
        txtElapsed.Text = "0.0"

オーディオの制御

IBasicAudio インターフェイスは、Volume プロパティと Balance プロパティという 2 つのプロパティをサポートしている。Volume プロパティはボリュームを取得または設定する。サンプル アプリケーションでは、このプロパティはスライダ コントロール slVolume にバインドされている。Balance プロパティはステレオのバランスを取得または設定する。サンプル アプリケーションでは、このプロパティはスライダ コントロール slBalance にバインドされている。

注 : ボリュームはリニア ボリューム スケールであるため、有用なのはスライダの右端だけである。

次の例では、g_objBasicAudio.Volume プロパティを設定してボリュームを調整している。

Private Sub slVolume_Change()
'スライダのボリュームを設定する

    If Not g_objMediaControl Is Nothing Then
    'g_objMediaControl が割り当てられている場合

       g_objBasicAudio.Volume = slVolume.Value

End If

End Sub

ビデオ出力のスケーリングと移動

IVideoWindow インターフェイスは、転送先ウィンドウのサイズ、状態、所有者、パレット、可視性などを変更するメソッドとプロパティをサポートしている。転送先ウィンドウの位置または外観を考慮する必要がない場合は、これらのメソッドとプロパティを呼び出さず、デフォルトのウィンドウ (デスクトップの左上に表示される) に出力をレンダリングすることができる。

キャプション、境界、およびダイアログ ボックスの枠を移動してウィンドウのスタイルを変更することもできる。そのためには、g_objVideoWindow.WindowStyle プロパティを 0x06000000 に設定する。これは、値 WS_DLGFRAME (0x04000000) と WS_VSCROLL (0x02000000) の 論理 OR に相当する。ウィンドウのスタイルおよび対応する値すべての一覧については、Microsoft® Platform SDK の Winuser.h ファイルを参照すること。

転送先ウィンドウをフォームの上に移動する場合、新しい位置を指定するには、g_objVideoWindow の Top および Left プロパティを設定する。Top および Left プロパティは、矩形をした空のコントロールの左上隅に対応するように設定する。これはフォームに表示されるある種のプレースホルダである。フォームの ScaleMode プロパティは 3 に設定されている。これはピクセルの単位を指定する。これでフォームのプロパティと DirectShow オブジェクトのプロパティを変換することなく使用できる。DirectShow オブジェクトのプロパティもピクセルで表される。Visual Basic フォームのデフォルトの単位は twip である。

ソース ビデオの幅と高さを取得して必要な矩形のサイズを決定する。これらの値は、IBasicVideo オブジェクトの VideoWidth および VideoHeight プロパティに対応する。

Top および Left プロパティを設定することに加えて、アプリケーションのフォームを新しい親ウィンドウとして識別する必要がある。そのためには、フォームのウィンドウ ハンドルである hWnd をオブジェクトの Owner プロパティに渡す。ハンドルを渡さない場合、転送先ウィンドウはフォームではなくデスクトップに対して相対的な位置に表示される。

次に例は、これらのタスクを示している。

    Set g_objVideoWindow = g_objMediaControl
    g_objVideoWindow.WindowStyle = CLng(&H6000000)   ' WS_DLGFRAME | WS_VSCROLL
    g_objVideoWindow.Left = CLng(Shape1.Left)   ' shape はフォームのプレースホルダ
    g_objVideoWindow.Top = CLng(Shape1.Top)
    Shape1.Width = g_objVideoWindow.Width       ' 入力ビデオに応じて shape をサイズ変更する
    Shape1.Height = g_objVideoWindow.Height
    g_objVideoWindow.Owner = frmMain.hWnd       ' フォームを親として設定する

次の例は、ScaleMode プロパティを初期化する方法を示している。

' ...
    frmMain.ScaleMode = 3    ' ピクセル
' ...

パフォーマンスに大きく影響するため、IVideoWindow オブジェクトの Width および Height プロパティを設定して転送先ウィンドウのスケールを変更しないこと。

状態の追跡

IMediaPosition オブジェクトによって公開されている多数のプロパテイを使用して、現在位置、停止位置、時間幅、およびレートを取得または設定できる。次のコード例は、その方法を示している。

    Set g_objMediaPosition = g_objMediaControl
    g_dblRunLength = g_objMediaPosition.Duration
    txtDuration.Text = CStr(g_dblRunLength)    ' 時間幅を表示する
    g_dblStartPosition = 0.0
    txtStart.Text = CDbl(g_dblStartPosition)   ' 開始タイムを表示する
    g_dblRate = g_objMediaPosition.Rate
    txtRate.Text = CStr(g_dblRate)

開始位置の取得と設定

IMediaPosition.CurrentPosition プロパティを使用すると、ユーザーがビデオのレンダリング開始位置を調整できる。次のコード例では、ユーザーがキーを押すと、それに応じて現在の位置を変更する。

Private Sub txtStart_KeyDown(KeyCode As Integer, Shift As Integer)
' ユーザー入力を処理して開始位置を変更する
If KeyCode = vbKeyReturn Then
If g_objMediaPosition Is Nothing Then
Exit Sub
    ElseIf CDbl(txtStart.Text) > g_dblRunLength Then
MsgBox "Specified position invalid:re-enter new position."
    ElseIf CDbl(txtStart.Text) < 0 Then
MsgBox "Specified position invalid:re-enter new position."
    ElseIf CDbl(txtStart.Text) <> "" Then
        g_dblStartPosition = CDbl(txtStart.Text)
        g_objMediaPosition.CurrentPosition = g_dblStartPosition
End If
End If
End Sub

レートの取得と設定

IMediaPosition.Rate プロパティを使用すると、ユーザーがビデオのレンダリング レートを調整できる。このレートは、標準再生速度を基準にしている。たとえば、レートが 0.5 の場合、ビデオは標準速度の 2 分の 1 の速度でレンダリングされ、レートが 2.0 の場合は標準レートの 2 倍の速度でレンダリングされる。

CurrentPosition プロパティはビデオのレンダリング中に設定できるが、Rate プロパティはレンダリングの前にあらかじめ設定しておく必要がある。

注 : レートが 1.0 未満のときはサウンド トラックを無効にできるビデオもある。

次のコード例では、ユーザーがキーを押すと、それに応じてレートを変更する。

Private Sub txtRate_KeyDown(KeyCode As Integer, Shift As Integer)
' DirectShow VB サンプル
' Rate 値に対するユーザーによる更新を処理する
If KeyCode = vbKeyReturn Then
If g_objMediaPosition Is Nothing Then
Exit Sub
    ElseIf CDbl(txtRate.Text) < 0# Then
        MsgBox "Negative values invalid: re-enter value between 0 and 2.0"
    ElseIf CStr(txtRate.Text) <> "" Then
        g_dblRate = CDbl(txtRate.Text)
        g_objMediaPosition.Rate = g_dblRate
End If
End If
End Sub

クリーン アップ

アプリケーションでは、Visual Basic の Set ステートメントを使用して新しい DirectShow オブジェクトのインスタンスを作成するたびに、次のコード例に示すように、対応する Set ステートメントでそのオブジェクト (および関連するリソース) をメモリから削除してからシャットダウンする必要がある。

Set g_objBasicAudio = Nothing


Visual Basic オブジェクト

Microsoft® DirectShow® は、その機能のサブセットを Microsoft® Visual Basic® アプリケーションに公開する。

フィルタ グラフの作成と制御には、次のオブジェクトを使用する。

  • IAMCollection オブジェクト
  • IBasicAudio オブジェクト
  • IBasicVideo オブジェクト
  • IFilterInfo オブジェクト
  • IMediaControl オブジェクト
  • IMediaEvent オブジェクト
  • IMediaPosition オブジェクト
  • IMediaTypeInfo オブジェクト
  • IPinInfo オブジェクト
  • IRegFilterInfo オブジェクト
  • IVideoWindow オブジェクト

DirectShow 編集サービス (DES) は、ビデオ編集のために次のオブジェクトをサポートしている。

  • AMTimeline
  • AMTimelineComp
  • AMTimelineEffect
  • AMTimelineGroup
  • AMTimelineObj
  • AMTimelineSrc
  • AMTimelineTrack
  • AMTimelineTrans
  • IAMTimelineEffectable
  • IAMTimelineSplittable
  • IAMTimelineTransable
  • IAMTimelineVirtualTrack
  • MediaDet
  • MediaLocator
  • RenderEngine
  • Xml2Dex


AMTimeline オブジェクト

Microsoft® DirectShow 編集サービス (DES) の中心的オブジェクトであるタイムラインを操作するメソッドを提供する。タイムラインは、ビデオ クリップ、オーディオ クリップ、エフェクト、およびクリップ間のトランジションなど、時間順の要素のコレクションである。レンダリング エンジンは、タイムラインを使用してフィルタ グラフを作成する。アプリケーションは、フィルタ グラフからレンダリングされた出力を生成できる。

AMTimeline オブジェクトは、3 つの基本的なサービスを提供する。

  • タイムライン内にオブジェクトを作成する。
  • 作成されたオブジェクトのコンテナとして機能する。
  • タイムラインの一般的パラメータの設定と取得を行う。

メソッド

AddGroup | タイムラインにグループを追加する。
ClearAllGroups | タイムライン内のすべてのグループ、およびそれらに含まれるすべてのオブジェクトを削除する。
CreateEmptyNode | 新しいタイムライン オブジェクトを作成する。
EffectsEnabled | エフェクトが有効かどうかを調べる。
EnableEffects | タイムライン内のすべてのエフェクトを有効または無効にする。
EnableTransitions | タイムライン内のすべてのトランジションを有効または無効にする。
GetCountOfType | 指定されたグループとそのすべての子に含まれる、指定されたタイプのオブジェクトの個数を取得する。
GetDefaultEffect | Visual Basic ではサポートされていない。
GetDefaultEffectB | デフォルトのエフェクトを取得する。
GetDefaultFPS | デフォルトの出力フレーム レート (毎秒のフレーム数) を取得する。
GetDefaultTransition | Visual Basic ではサポートされていない。
GetDefaultTransitionB | デフォルトのトランジションを取得する。
GetDirtyRange | Visual Basic ではサポートされていない。
GetDuration | Visual Basic ではサポートされていない。
GetDuration2 | タイムラインの時間幅を取得する。
GetGroup | 指定されたグループを取得する。
GetGroupCount | タイムラインに含まれるグループの個数を取得する。
GetInsertMode | Visual Basic ではサポートされていない。
IsDirty | Visual Basic ではサポートされていない。
RemGroupFromList | Visual Basic ではサポートされていない。
SetDefaultEffect | Visual Basic ではサポートされていない。
SetDefaultEffectB | デフォルトのエフェクトを設定する。
SetDefaultFPS | デフォルトの出力フレーム レート (毎秒のフレーム数) を設定する。
SetDefaultTransition | Visual Basic ではサポートされていない。
SetDefaultTransitionB | デフォルトのトランジションを設定する。
SetInsertMode | Visual Basic ではサポートされていない。
SetInterestRange | Visual Basic ではサポートされていない。
TransitionsEnabled | トランジションが有効かどうかを調べる。
ValidateSourceNames | タイムライン内のソース名を検証する。

AddGroup メソッド (AMTimeline オブジェクト)

AMTimeline オブジェクト

タイムラインにグループを追加する。

構文

object.AddGroup(
pGroup As IAMTimelineObj
)

パラメータ

object
結果が AMTimeline オブジェクトになるオブジェクト式。
pGroup
グループを指定する AMTimelineObj オブジェクト。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次の値が設定される場合がある。

E_INVALIDARG | グループの最大数を超えた。
E_NOINTERFACE | このオブジェクトはグループではない。

注意

現在、タイムラインがサポートするグループの最大数は 32 である。

ClearAllGroups メソッド (AMTimeline オブジェクト)

AMTimeline オブジェクト

タイムライン内のすべてのグループ、およびそれらに含まれるすべてのオブジェクトを削除する。

構文

object.ClearAllGroups()

パラメータ

object
結果が AMTimeline オブジェクトになるオブジェクト式。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

CreateEmptyNode メソッド (AMTimeline オブジェクト)

AMTimeline オブジェクト

新しいタイムライン オブジェクトを作成する。

このメソッドは重要な初期化ルーチンを実行するので、タイムラインの作成にはこのメソッドを使用し、New キーワードは使用しない。

構文

object.CreateEmptyNode(
ppObj As AMTimelineObj,
Type As TIMELINE_MAJOR_TYPE
)

パラメータ

object
結果が AMTimeline オブジェクトになるオブジェクト式。
ppObj
新しいオブジェクトを受け取る AMTimelineObj オブジェクト。
Type
作成するオブジェクトのタイプを指定する TIMELINE_MAJOR_TYPE 列挙型のメンバ。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次のいずれかの値が設定される場合がある。

E_INVALIDARG | オブジェクト タイプが有効ではない。
E_OUTOFMEMORY | メモリ不足。

EffectsEnabled メソッド (AMTimeline オブジェクト)

AMTimeline オブジェクト

エフェクトが有効かどうかを調べる。エフェクトが無効の場合、エフェクトはタイムライン内に存在したままだが、レンダリングはされない。

構文

object.EffectsEnabled(
pfEnabled As Long
)

パラメータ

object
結果が AMTimeline オブジェクトになるオブジェクト式。
pfEnabled
エフェクトが有効かどうかを示す値を受け取る変数。値がゼロの場合は、エフェクトは無効である。値がゼロ以外の場合は、エフェクトは有効である。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

EnableEffects メソッド (AMTimeline オブジェクト)

AMTimeline オブジェクト

タイムライン内のすべてのエフェクトを有効または無効にする。エフェクトが無効の場合、エフェクトはタイムライン内に存在したままだが、レンダリングはされない。

構文

object.EnableEffects(
fEnabled As Long
)

パラメータ

object
結果が AMTimeline オブジェクトになるオブジェクト式。
fEnabled
エフェクトを有効または無効のどちらに設定するかを示す値。ゼロの場合は、エフェクトは無効になる。ゼロ以外の場合は、エフェクトは有効になる。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

EnableTransitions メソッド (AMTimeline オブジェクト)

AMTimeline オブジェクト

タイムライン内のすべてのトランジションを有効または無効にする。トランジションが無効の場合、レンダリング エンジンはトランジションをカット (直接切り替え) として扱う。 つまり、レンダリングされた出力では、トラックから次のトラックに即座に切り替わる。デフォルトのカット ポイントは、トランジションの時間幅の中間点である。トランジションに対して IAMTimelineTrans.SetCutPoint メソッドを呼び出すことで、カット ポイントを変更できる。トランジションは、無効になってもタイムラインに残っている。

構文

object.EnableTransitions(
fEnabled As Long
)

パラメータ

object
結果が AMTimeline オブジェクトになるオブジェクト式。
fEnabled
トランジションを有効または無効のどちらに設定するかを示す値。ゼロの場合は、トランジションは無効になる。ゼロ以外の場合は、トランジションは有効になる。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

GetCountOfType メソッド (AMTimeline オブジェクト)

AMTimeline オブジェクト

指定されたグループとそのすべての子に含まれる、指定されたタイプのオブジェクトの個数を取得する。

構文

object.GetCountOfType(
Group As Long,
pVal As Long,
pValWithComps As Long,
MajorType As TIMELINE_MAJOR_TYPE
)

パラメータ

object
結果が AMTimeline オブジェクトになるオブジェクト式。
Group
オブジェクトの個数を取得するグループのインデックス番号。
pVal
グループおよびそのすべての仮想トラックに含まれる (再帰的に内部に含まれるオブジェクトも含む)、指定されたタイプのオブジェクトの個数を受け取る変数。
pValWithComps
pVal に返された個数に、これ自体も含めて検索された合成の個数を加えた数を受け取る変数。
MajorType
TIMELINE_MAJOR_TYPE 列挙型のメンバ。 個数を数えるオブジェクトのタイプを指定する。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次の値が設定される場合がある。

E_INVALIDARG 無効なグループ番号。

注意

このメソッドの呼び出しは、指定したグループに対する AMTimelineComp.GetCountOfType の呼び出しに相当する。詳細については、そのメソッドの「注意」を参照すること。

通常、アプリケーションではこのメソッドを呼び出さない。レンダリング エンジンによって内部的に呼び出される。

GetDefaultEffect メソッド (AMTimeline オブジェクト)

AMTimeline オブジェクト

Visual Basic ではサポートされていない。

構文

object.GetDefaultEffect(
pGuid As GUID
)

GetDefaultEffectB メソッド (AMTimeline オブジェクト)

AMTimeline オブジェクト

デフォルトのエフェクトを取得する。レンダリング エンジンがエフェクトをレンダリングできない場合、デフォルトのエフェクトが代用される。

構文

object.GetDefaultEffectB() As String

パラメータ

object
結果が AMTimeline オブジェクトになるオブジェクト式。

戻り値

デフォルト エフェクトの GUID を表す文字列を返す。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次の値が設定される場合がある。

E_OUTOFMEMORY メモリ不足。

GetDefaultFPS メソッド (AMTimeline オブジェクト)

AMTimeline オブジェクト

デフォルトの出力フレーム レート (毎秒のフレーム数、FPS) を取得する。グループは、この値をデフォルトのフレーム レートとして使用する。グループのフレーム レートを設定するには、グループに対して AMTimelineGroup.SetOutputFPS メソッドを呼び出す。

構文

object.GetDefaultFPS(
pFPS As Double
)

パラメータ

object
結果が AMTimeline オブジェクトになるオブジェクト式。
pFPS
デフォルトのフレーム レート (毎秒のフレーム数) を受け取る変数。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

GetDefaultTransition メソッド (AMTimeline オブジェクト)

AMTimeline オブジェクト

Visual Basic ではサポートされていない。

構文

object.GetDefaultTransition(
pGuid As GUID
)

GetDefaultTransitionB メソッド (AMTimeline オブジェクト)

AMTimeline オブジェクト

デフォルトのトランジションを取得する。レンダリング エンジンがトランジションをレンダリングできない場合は、デフォルトのトランジションが代用される。

構文

object.GetDefaultTransitionB() As *pGuid

パラメータ

object
結果が AMTimeline オブジェクトになるオブジェクト式。

戻り値

デフォルトのトランジションの GUID を表す文字列を返す。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次の値が設定される場合がある。

E_OUTOFMEMORY メモリ不足。

GetDirtyRange メソッド (AMTimeline オブジェクト)

AMTimeline オブジェクト

Visual Basic ではサポートされていない。

構文

object.GetDirtyRange(
pStart As <Unsupported variant type>,
pStop As <Unsupported variant type>
)

GetDuration メソッド (AMTimeline オブジェクト)

AMTimeline オブジェクト

Visual Basic ではサポートされていない。

構文

object.GetDuration(
pDuration As <Unsupported variant type>
)

GetDuration2 メソッド (AMTimeline オブジェクト)

AMTimeline オブジェクト

タイムラインの時間幅を取得する。

構文

object.GetDuration2(
pDuration As Double
)

パラメータ

object
結果が AMTimeline オブジェクトになるオブジェクト式。
pDuration
タイムラインの時間幅 (秒数) を受け取る変数。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

GetGroup メソッド (AMTimeline オブジェクト)

AMTimeline オブジェクト

指定されたグループを取得する。

構文

object.GetGroup(
ppGroup As AMTimelineObj,
WhichGroup As Long
)

パラメータ

object
結果が AMTimeline オブジェクトになるオブジェクト式。
ppGroup
指定したグループを受け取る AMTimelineObj オブジェクト。
WhichGroup
取得するグループのインデックス。 このインデックスは、グループがタイムラインに追加された順序に基づく。タイムラインに最初に追加されたグループのインデックスは 0 となる。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次の値が設定される場合がある。

E_INVALIDARG 無効な引数。

GetGroupCount メソッド (AMTimeline オブジェクト)

AMTimeline オブジェクト

タイムラインに含まれるグループの個数を取得する。

構文

object.GetGroupCount(
pCount As Long
)

パラメータ

object
結果が AMTimeline オブジェクトになるオブジェクト式。
pCount
タイムライン内のグループの個数を受け取る変数。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

GetInsertMode メソッド (AMTimeline オブジェクト)

AMTimeline オブジェクト

Visual Basic ではサポートされていない。

構文

object.GetInsertMode(
pMode As Long
)

IsDirty メソッド (AMTimeline オブジェクト)

AMTimeline オブジェクト

Visual Basic ではサポートされていない。

構文

object.IsDirty(
pDirty As Long
);

RemGroupFromList メソッド (AMTimeline オブジェクト)

AMTimeline オブジェクト

Visual Basic ではサポートされていない。

構文

object.RemGroupFromList(
pGroup As AMTimelineObj
);

SetDefaultEffect メソッド (AMTimeline オブジェクト)

AMTimeline オブジェクト

Visual Basic ではサポートされていない。

構文

object.SetDefaultEffect(
pGuid As GUID
)

SetDefaultEffectB メソッド (AMTimeline オブジェクト)

AMTimeline オブジェクト

デフォルトのエフェクトを設定する。レンダリング エンジンがエフェクトをレンダリングできない場合は、デフォルトのエフェクトが代用される。

構文

object.SetDefaultEffectB(
pGuid As String
)

パラメータ

object
結果が AMTimeline オブジェクトになるオブジェクト式。
pGuid
デフォルト エフェクトの GUID を表す文字列。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次の値が設定される場合がある。

E_OUTOFMEMORY メモリ不足。

注意

デフォルト エフェクトを設定していない場合、またはデフォルトに指定したエフェクトでエラーが発生した場合は、DES 自体のデフォルト エフェクトが使用される。

SetDefaultFPS メソッド (AMTimeline オブジェクト)

AMTimeline オブジェクト

デフォルトの出力フレーム レート (毎秒のフレーム数) を設定する。グループは、この値をデフォルトのフレーム レートとして使用する。グループのフレーム レートを設定するには、グループに対して AMTimelineGroup.SetOutputFPS メソッドを呼び出す。

構文

object.SetDefaultFPS(
FPS As Double
)

パラメータ

object
結果が AMTimeline オブジェクトになるオブジェクト式。
FPS
デフォルトのフレーム レート (毎秒のフレーム数)。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

SetDefaultTransition メソッド (AMTimeline オブジェクト)

AMTimeline オブジェクト

Visual Basic ではサポートされていない。

構文

object.SetDefaultTransition(
pGuid As GUID
)

SetDefaultTransitionB メソッド (AMTimeline オブジェクト)

AMTimeline オブジェクト

デフォルトのトランジションを設定する。レンダリング エンジンがトランジションをレンダリングできない場合は、デフォルトのトランジションが代用される。

構文

object.SetDefaultTransitionB(
pGuid As String
)

パラメータ

object
結果が AMTimeline オブジェクトになるオブジェクト式。
pGuid
デフォルトのトランジションの GUID を表す文字列。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次の値が設定される場合がある。

E_OUTOFMEMORY メモリ不足。

注意

デフォルトのトランジションを設定していない場合、またはデフォルトに指定したトランジションでエラーが発生した場合は、DES 自体のデフォルトのトランジションが使用される。

SetInsertMode メソッド (AMTimeline オブジェクト)

AMTimeline オブジェクト

Visual Basic ではサポートされていない。

構文

object.SetInsertMode(
Mode As Long
)

SetInterestRange メソッド (AMTimeline オブジェクト)

AMTimeline オブジェクト

Visual Basic ではサポートされていない。

構文

object.SetInterestRange(
Start As <Unsupported variant type>,
Stop As <Unsupported variant type>
)

TransitionsEnabled メソッド (AMTimeline オブジェクト)

AMTimeline オブジェクト

トランジションが有効かどうかを調べる。

構文

object.TransitionsEnabled(
pfEnabled As Long
)

パラメータ

object
結果が AMTimeline オブジェクトになるオブジェクト式。
pfEnabled
トランジションが有効かどうかを指定する値。ゼロの場合は、トランジションは無効である。ゼロ以外の場合は、トランジションは有効である。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

参照

EnableTransitions

ValidateSourceNames メソッド (AMTimeline オブジェクト)

AMTimeline オブジェクト

メディア ロケータを使用して、タイムライン内のソース名を検証する。オプションで、このメソッドは見つかったファイルのソース オブジェクトを更新する。

構文

object.ValidateSourceNames(
ValidateFlags As Long,
pOverride As MediaLocator,
NotifyEventHandle As LONG_PTR
)

パラメータ

object
結果が AMTimeline オブジェクトになるオブジェクト式。
ValidateFlags
メディア ロケータの動作を指定する、検証フラグ のビットごとの組み合わせ。SFN_VALIDATEF_REPLACE フラグと SFN_VALIDATEF_CHECK フラグは、必ず指定しなければならない。指定しないと、メソッドから E_INVALIDARG が返る。
pOverride
省略可能。デフォルトの代わりに使用する MediaLocator オブジェクト。デフォルトのメディア ロケータを使用するには、このパラメータの値を Nothing に設定する。
NotifyEventHandle
LONG_PTR タイプの変数。このパラメータは無視されるので、ゼロでかまわない。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次の値が設定される場合がある。

E_INVALIDARG 無効な引数。


AMTimelineComp オブジェクト

Microsoft® DirectShow 編集サービス (DES) で、合成上の仮想トラックを挿入または取得する。

合成は、合成されたトラックとして機能する、レイヤのコレクションである。たとえば、2 つのトラックとそれらの間のトランジションからなる合成は、そのトランジションがあらかじめ合成されている単一のトラックとして機能する。合成には、同じタイプ (オーディオまたはビデオ) のメディアだけを入れるようにする必要があるが、この制限は強制されない。仮想トラックは、合成内に配置できる、トラックおよび他の合成も含めた任意のオブジェクトである。

タイムラインの最上位のノードはグループである。グループは、AMTimelineComp と AMTimelineGroup の両方をサポートする。

詳細については、「タイムライン モデル」を参照すること。

メソッド

GetCountOfType | この合成およびそのすべての仮想トラックに含まれる (再帰的に内部に含まれるオブジェクトも含む)、指定されたタイプのオブジェクトの個数を取得する。
GetNextVTrack | 指定された仮想トラックの次の仮想トラックを取得する。
GetRecursiveLayerOfType | この合成に含まれる仮想トラックを深度の深い順に順序付け、その順序で n 番目の仮想トラックを取得する。
GetRecursiveLayerOfTypeI | Visual Basic ではサポートされていない。
GetVTrack | 指定された優先順位の仮想トラックを取得する。
VTrackGetCount | 合成に含まれる仮想トラックの個数を取得する。
VTrackInsBefore | 合成に指定の優先順位で仮想トラックを挿入する。
VTrackSwapPriorities | 2 つのトラックの優先順位レベルを入れ替える。

GetCountOfType メソッド (AMTimelineComp オブジェクト)

AMTimelineComp オブジェクト

この合成およびそのすべての仮想トラックに含まれる (再帰的に内部に含まれるオブジェクトも含む)、指定されたタイプのオブジェクトの個数を取得する。

構文

object.GetCountOfType(
pVal As Long,
pValWithComps As Long,
MajorType As TIMELINE_MAJOR_TYPE
)

パラメータ

object
結果が AMTimelineComp オブジェクトになるオブジェクト式。
pVal
この合成およびそのすべての仮想トラックに含まれる (再帰的に内部に含まれるオブジェクトも含む)、指定されたタイプのオブジェクトの個数を受け取る変数。
pValWithComps
pVal に返された個数と、これ自体も含めて検索された合成の個数を加えた数を受け取る変数。
MajorType
TIMELINE_MAJOR_TYPE 列挙型のメンバ。 個数を数えるオブジェクトのタイプを指定する。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

注意

通常、アプリケーションではこのメソッドを呼び出さない。このメソッドは、レンダリング エンジンによって呼び出される。

合成の個数を調べた場合、pVal に返される値はゼロで、pValWithComps に返される値が合成の個数である。pValWithComps の値には、メソッドを呼び出した合成も含まれる。たとえば、空の合成でこのメソッドを呼び出した場合、pValWithComps は 1 になる。

グループは合成の中に配置できないので、このメソッドでグループの数を調べることはできない (返される数は常にゼロとなる)。グループの数を調べるには、AMTimeline.GetGroupCount メソッドを呼び出す。

GetNextVTrack メソッド (AMTimelineComp オブジェクト)

AMTimelineComp オブジェクト

指定された仮想トラックの次の仮想トラックを取得する。

構文

object.GetNextVTrack(
pVirtualTrack As AMTimelineObj,
ppNextVirtualTrack As AMTimelineObj
)

パラメータ

object
結果が AMTimelineComp オブジェクトになるオブジェクト式。
pVirtualTrack
前の仮想トラックを指定する AMTimelineObj オブジェクト。合成内の最初の仮想トラックを取得する場合は Nothing。
ppNextVirtualTrack
次の優先順位の仮想トラックを受け取る AMTimelineObj オブジェクト。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

GetRecursiveLayerOfType メソッド (AMTimelineComp オブジェクト)

AMTimelineComp オブジェクト

この合成に含まれる仮想トラックを深度の深い順に順序付け、その順序で n 番目の仮想トラックを取得する。

構文

object.GetRecursiveLayerOfType(
ppVirtualTrack As AMTimelineObj,
WhichLayer As Long,
Type As TIMELINE_MAJOR_TYPE
)

パラメータ

object
結果が AMTimelineComp オブジェクトになるオブジェクト式。
ppVirtualTrack
仮想トラックを受け取る AMTimelineObj オブジェクト。
WhichLayer
取得する仮想トラックを指定する、ゼロから始まるインデックスの値。
Type
TIMELINE_MAJOR_TYPE 列挙型のメンバ。 検索にトラックを含めるかどうかを指定する。

エラー コード

メソッドが失敗するとエラーが発生し、Err.Number には次の値が設定される場合がある。

E_INVALIDARG 指定されたタイプのオブジェクトがない。

注意

通常、アプリケーションでこのメソッドを呼び出す必要はない。

Type パラメータが TIMELINE_MAJOR_TYPE_TRACK の場合は、深度の順序付けにトラックも含まれる。それ以外の場合は、合成とグループだけが含まれる。そのオブジェクト自体も順序付けに含まれる。

たとえば、合成 A から始まる次のような配置では、順序は B、C、F、D、E、A となる。

GetRecursiveLayerOfTypeI メソッド (AMTimelineComp オブジェクト)

AMTimelineComp オブジェクト

Visual Basic ではサポートされていない。代わりに、GetRecursiveLayerOfType メソッドを使用する。

構文

object.GetRecursiveLayerOfTypeI(
ppVirtualTrack As AMTimelineObj,
pWhichLayer As Long,
Type As TIMELINE_MAJOR_TYPE
)

GetVTrack メソッド (AMTimelineComp オブジェクト)

AMTimelineComp オブジェクト

指定された優先順位の仮想トラックを取得する。

構文

object.GetVTrack(
ppVirtualTrack As AMTimelineObj,
Which As Long
)

パラメータ

object
結果が AMTimelineComp オブジェクトになるオブジェクト式。
ppVirtualTrack
仮想トラックを受け取る AMTimelineObj オブジェクト。
Which
取得する仮想トラックの優先順位。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次の値が設定される場合がある。

E_INVALIDARG 指定された優先順位の仮想トラックがない。

VTrackGetCount メソッド (AMTimelineComp オブジェクト)

AMTimelineComp オブジェクト

合成に含まれる仮想トラックの個数を取得する。

構文

object.VTrackGetCount(
pVal As Long
)

パラメータ

object
結果が AMTimelineComp オブジェクトになるオブジェクト式。
pVal
仮想トラックの数を受け取る変数。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

VTrackInsBefore メソッド (AMTimelineComp オブジェクト)

AMTimelineComp オブジェクト

合成に指定の優先順位で仮想トラックを挿入する。

構文

object.VTrackInsBefore(
pVirtualTrack As AMTimelineObj,
Priority As Long
)

パラメータ

object
結果が AMTimelineComp オブジェクトになるオブジェクト式。
pVirtualTrack
仮想トラックを指定する AMTimelineObj オブジェクト。
Priority
仮想トラックを挿入する優先順位。 優先順位リストの最後に仮想トラックを挿入する場合は -1。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次のいずれかの値が設定される場合がある。

E_INVALIDARG | 無効な引数。
E_NOINTERFACE | pVirtualTrack で指定されているオブジェクトが、仮想トラックではない。

注意

優先順位レベルはゼロから始まる。タイムラインに、指定された優先順位レベルの仮想トラックが既に存在する場合、優先順位リストのその位置以下のすべてが 1 レベルずつ繰り下げられ、挿入されるトラックの場所が確保される。現在のトラックの個数より大きい値を優先順位に指定した場合、このメソッドは失敗する。

VTrackSwapPriorities メソッド (AMTimelineComp オブジェクト)

AMTimelineComp オブジェクト

2 つのトラックの優先順位レベルを入れ替える。

このメソッドは、指定された 2 つの優先順位レベルを持つそれぞれの仮想トラックの優先順位を入れ替える。このメソッドから戻った時点で、最初に指定された優先順位にあったトラックの優先順位は、2 番目に指定された優先順位レベルになり、2 番目に指定された優先順位にあったトラックの優先順位は、最初に指定された優先順位レベルになっている。

構文

object.VTrackSwapPriorities(
VirtualTrackA As Long,
VirtualTrackB As Long
)

パラメータ

object
結果が AMTimelineComp オブジェクトになるオブジェクト式。
VirtualTrackA
仮想トラックを入れ替える最初の優先順位レベル。
VirtualTrackB
仮想トラックを入れ替える 2 番目の優先順位レベル。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次の値が設定される場合がある。

E_INVALIDARG 無効な引数。


AMTimelineEffect オブジェクト

Microsoft® DirectShow 編集サービス (DES) でエフェクトを操作するためのメソッドを提供する。

AMTimelineEffect オブジェクトは、DES がサポートするすべてのタイプの単一入力エフェクトのラッパー オブジェクトである。使用するエフェクトを指定するには、目的のエフェクトに対して AMTimelineObj.SetSubObjectGUID メソッドを呼び出す。

メソッド

EffectGetPriority エフェクトの優先順位レベルを取得する。

EffectGetPriority メソッド (AMTimelineEffect オブジェクト)

AMTimelineEffect オブジェクト

エフェクトの優先順位レベルを取得する。エフェクトを持つ各タイムライン オブジェクトに対し、レンダリング エンジンは、優先順位レベル 0 から始めて優先順位の順に、そのオブジェクトのエフェクトを適用する。

構文

object.EffectGetPriority(
pVal As Long
)

パラメータ

object
結果が AMTimelineEffect オブジェクトになるオブジェクト式。
pVal
優先順位レベルを受け取る変数。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。


AMTimelineGroup オブジェクト

Microsoft® DirectShow 編集サービス (DES) でグループのプロパティを設定および取得する。

グループは 1 つ以上のトラックと、場合により 1 つ以上の合成を持ち、トラックは同一タイプ (ビデオやオーディオなど) のソース クリップを持つ。グループは、タイムラインの最上位の合成であり、また AMTimelineComp オブジェクトをサポートする。タイムラインは、複数のグループを持つことができる。

各グループには以下の属性がある。

  • 関連付けられたメディア タイプ。
  • グループがレンダリングされるフレーム レート (毎秒のフレーム数、FPS)。すべての編集が始まる時間は、グループの FPS 設定によって定義される最も近いフレーム境界に丸められる。
  • 優先順位レベル。同じメディア タイプの複数のストリームを持つファイル (たとえば、2 つのビデオ ストリームを持つ AVI ファイル) を書き込む際に使用される。

メソッド

ClearRecompressFormatDirty | Visual Basic ではサポートされていない。
GetGroupName | アプリケーションで定義されているグループの名前を取得する。
GetMediaType | Visual Basic ではサポートされていない。
GetOutputBuffering | プレビュー時に先行してレンダリングされるフレーム数を取得する。
GetOutputFPS | このグループの出力フレーム レートを取得する。
GetPreviewMode | グループのプレビュー モードを取得する。
GetPriority | グループの優先順位を取得する。
GetSmartRecompressFormat | Visual Basic ではサポートされていない。
GetTimeline | このグループが所属するタイムラインを取得する。
IsRecompressFormatDirty | Visual Basic ではサポートされていない。
IsSmartRecompressFormatSet | Visual Basic ではサポートされていない。
SetGroupName | アプリケーションで定義されているグループの名前を設定する。
SetMediaType | Visual Basic ではサポートされていない。
SetMediaTypeForVB | グループのメディア タイプを指定する。
SetOutputBuffering | プレビュー時に先行してレンダリングされるフレーム数を指定する。
SetOutputFPS | このグループの非圧縮出力フレーム レートを設定する。
SetPreviewMode | グループのプレビュー モードを設定する。
SetRecompFormatFromSource | ソース ファイルの圧縮フォーマットを使ってビデオ再圧縮フォーマットを設定する。
SetSmartRecompressFormat | Visual Basic ではサポートされていない。
SetTimeline | Visual Basic ではサポートされていない。

ClearRecompressFormatDirty メソッド (AMTimelineGroup オブジェクト)

AMTimelineGroup オブジェクト

Visual Basic ではサポートされていない。

構文

object.ClearRecompressFormatDirty()

GetGroupName メソッド (AMTimelineGroup オブジェクト)

AMTimelineGroup オブジェクト

アプリケーションで定義されているグループの名前を取得する。

構文

object.GetGroupName() As String

パラメータ

object
結果が AMTimelineGroup オブジェクトになるオブジェクト式。

戻り値

アプリケーションで定義されているグループの名前を返す。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

GetMediaType メソッド (AMTimelineGroup オブジェクト)

AMTimelineGroup オブジェクト

Visual Basic ではサポートされていない。

構文

object.GetMediaType(
pmt As _AMMediaType
)

GetOutputBuffering メソッド (AMTimelineGroup オブジェクト)

AMTimelineGroup オブジェクト

プレビュー時に先行してレンダリングされるフレーム数を取得する。

構文

object.GetOutputBuffering(
pnBuffer As Long
)

パラメータ

object
結果が AMTimelineGroup オブジェクトになるオブジェクト式。
pnBuffer
バッファリングされるフレームの数を受け取る変数。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

GetOutputFPS メソッド (AMTimelineGroup オブジェクト)

AMTimelineGroup オブジェクト

このグループの出力フレーム レートを取得する。

構文

object.GetOutputFPS(
pFPS As Double
)

パラメータ

object
結果が AMTimelineGroup オブジェクトになるオブジェクト式。
pFPS
出力フレーム レート (毎秒のフレーム数) を受け取る変数。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

GetPreviewMode メソッド (AMTimelineGroup オブジェクト)

AMTimelineGroup オブジェクト

グループのプレビュー モードを取得する。

構文

object.GetPreviewMode(
pfPreview As Long
)

パラメータ

object
結果が AMTimelineGroup オブジェクトになるオブジェクト式。
pfPreview
プレビュー モードを示す値を受け取る変数。ゼロの場合、グループはオーサリング モードである。ゼロ以外の場合、グループはプレビュー モードである。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

注意

プレビュー モードでは、ビデオとオーディオの同期を維持するために、時間のかかるエフェクトまたはトランジションではフレーム落ちが生じる。そのため、ビデオの動きがぎこちなくなることがある。オーサリング モードでは、すべてのフレームがレンダリングされる。オーサリング モードはファイルへの書き込みに適している。 オーサリング モードで画面にプレビューを行うと、ビデオとオーディオの同期がくずれることがある。

GetPriority メソッド (AMTimelineGroup オブジェクト)

AMTimelineGroup オブジェクト

グループの優先順位を取得する。

構文

object.GetPriority(
pPriority As Long
)

パラメータ

object
結果が AMTimelineGroup オブジェクトになるオブジェクト式。
pPriority
グループの優先順位を受け取る変数。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

GetSmartRecompressFormat メソッド (AMTimelineGroup オブジェクト)

AMTimelineGroup オブジェクト

Visual Basic ではサポートされていない。

構文

object.GetSmartRecompressFormat(
ppFormat As Long
)

GetTimeline メソッド (AMTimelineGroup オブジェクト)

AMTimelineGroup オブジェクト

このグループが所属するタイムラインを取得する。

構文

object.GetTimeline(
ppTimeline As AMTimeline
)

パラメータ

object
結果が AMTimeline オブジェクトになるオブジェクト式。
ppTimeline
タイムラインを受け取る AMTimeline オブジェクト。グループがタイムラインの一部でない場合、オブジェクトは Nothing に設定される。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

IsRecompressFormatDirty メソッド (AMTimelineGroup オブジェクト)

AMTimelineGroup オブジェクト

Visual Basic ではサポートされていない。

構文

object.IsRecompressFormatDirty(
pVal As Long
)

IsSmartRecompressFormatSet メソッド (AMTimelineGroup オブジェクト)

AMTimelineGroup オブジェクト

Visual Basic ではサポートされていない。

構文

object.IsSmartRecompressFormatSet(
pVal As Long
)

SetGroupName メソッド (AMTimelineGroup オブジェクト)

AMTimelineGroup オブジェクト

アプリケーションで定義されているグループの名前を設定する。

構文

object.SetGroupName(
pGroupName As String
)

パラメータ

object
結果が AMTimelineGroup オブジェクトになるオブジェクト式。
pGroupName
グループの名前。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

SetMediaType メソッド (AMTimelineGroup オブジェクト)

AMTimelineGroup オブジェクト

Visual Basic ではサポートされていない。代わりに、SetMediaTypeForVB メソッドを使用する。

構文

object.SetMediaType(
pmt As _AMMediaType
)

SetMediaTypeForVB メソッド (AMTimelineGroup オブジェクト)

AMTimelineGroup オブジェクト

グループのメディア タイプを指定する。

構文

object.SetMediaTypeForVB(
Val As Long
)

パラメータ

object
結果が AMTimelineGroup オブジェクトになるオブジェクト式。
Val
メディア タイプを指定する値。
ゼロ | ビデオ
ゼロ以外 | オーディオ

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

注意

このメソッドは、次のフォーマットをサポートしている。

  • ビデオ:320 × 240 16 ビット RGB、555 フォーマット (MEDIASUBTYPE_RGB555).
  • オーディオ:44.1kHz ステレオ PCM、1 サンプル 16 ビット (MEDIASUBTYPE_PCM)

SetOutputBuffering メソッド (AMTimelineGroup オブジェクト)

AMTimelineGroup オブジェクト

プレビュー時に先行してレンダリングされるフレーム数を指定する。

構文

object.SetOutputBuffering(
nBuffer As Long
)

パラメータ

object
結果が AMTimelineGroup オブジェクトになるオブジェクト式。
nBuffer
プレビュー時にバッファリングされるフレーム数。2 以上でなければならない。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次の値が設定される場合がある。

E_INVALIDARG 無効な引数。

注意

バッファが大きくなれば、必要なメモリ量も大きくなるが、プレビューはよりスムースになる。 特に、レンダリングに時間がかかるエフェクトまたはトランジションで、それが顕著である。デフォルトのバッファは 30 フレームである。

SetOutputFPS メソッド (AMTimelineGroup オブジェクト)

AMTimelineGroup オブジェクト

このグループの非圧縮出力フレーム レートを設定する。

構文

object.SetOutputFPS(
FPS As Double
)

パラメータ

object
結果が AMTimelineGroup オブジェクトになるオブジェクト式。
FPS
このグループの出力フレーム レート (毎秒のフレーム数)。この値は、ゼロにすることはできず、小数点以下を 8 桁以上指定することはできない。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次の値が設定される場合がある。

E_INVALIDARG 無効な引数。

注意

このグループからレンダリングされた出力は、指定されたフレーム レートで実行され、ソース素材上のすべての編集は、フレーム レートによって定義される最も近いフレーム境界に丸められる。

SetPreviewMode メソッド (AMTimelineGroup オブジェクト)

AMTimelineGroup オブジェクト

グループのプレビュー モードを設定する。

構文

object.SetPreviewMode(
fPreview As Long
)

パラメータ

object
結果が AMTimelineGroup オブジェクトになるオブジェクト式。
fPreview
プレビュー モードを指定する値。ゼロを指定すると、グループはオーサリング モードになる。ゼロ以外を指定すると、グループはプレビュー モードになる。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

注意

プレビュー モードでは、ビデオとオーディオの同期を維持するために、時間のかかるエフェクトまたはトランジションではフレーム落ちが生じる。そのため、ビデオの動きがぎこちなくなることがある。オーサリング モードでは、すべてのフレームがレンダリングされる。オーサリング モードはファイルへの書き込みに適している。 オーサリング モードで画面にプレビューを行うと、ビデオとオーディオの同期がくずれることがある。

SetRecompFormatFromSource メソッド (AMTimelineGroup オブジェクト)

AMTimelineGroup オブジェクト

ソース ファイルの圧縮フォーマットを使ってビデオ再圧縮フォーマットを設定する。

構文

object.SetRecompFormatFromSource(
pSource As AMTimelineSrc
)

パラメータ

object
結果が AMTimelineGroup オブジェクトになるオブジェクト式。
pSource
IAMTimelineSrc オブジェクト。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次のいずれかの値が設定される場合がある。

E_NO_TIMELINE | グループがタイムライン内にない。
E_OUTOFMEMORY | メモリ不足。
VFW_E_INVALIDMEDIATYPE | ソース ファイルにビデオ ストリームがない。

注意

このメソッドは、pSource に関連付けられたソース ファイルを探し、ファイルの最初のビデオ ストリームのメディア タイプを取得する。 次に、そのタイプを使ってグループの圧縮フォーマットを設定する。

SetSmartRecompressFormat メソッド (AMTimelineGroup オブジェクト)

AMTimelineGroup オブジェクト

Visual Basic ではサポートされていない。

構文

object.SetSmartRecompressFormat(
pFormat As Long
)

SetTimeline メソッド (AMTimelineGroup オブジェクト)

AMTimelineGroup オブジェクト

Visual Basic ではサポートされていない。

構文

object.SetTimeline(
pTimeline As AMTimeline
)


AMTimelineObj オブジェクト

Microsoft® DirectShow 編集サービス (DES) のタイムライン オブジェクトを操作するメソッドを提供する。ソース、エフェクト、トランジション、トラック、グループ、および合成を含むすべてのタイムライン オブジェクトは、AMTimelienObj をサポートする。AMTimeline.CreateEmptyNode メソッドを呼び出して、タイムライン オブジェクトを作成しなければならない。

メソッド

ClearDirty | Visual Basic ではサポートされていない。
FixTimes | Visual Basic ではサポートされていない。
FixTimes2 | 指定された開始タイムと終了タイムを、親グループのフレーム レート設定によって定義される最も近いフレーム境界に丸める。
GetDirtyRange | Visual Basic ではサポートされていない。
GetDirtyRange2 | Visual Basic ではサポートされていない。
GetEmbedDepth | Visual Basic ではサポートされていない。
GetGenID | オブジェクトの生成された識別子を取得する。
GetGroupIBelongTo | Visual Basic ではサポートされていない。
GetLocked | オブジェクトの編集状態 (ロックまたはロック解除) を取得する。
GetMuted | オブジェクトのミュート状態を取得する。
GetPropertySetter | Visual Basic ではサポートされていない。
GetStartStop | Visual Basic ではサポートされていない。
GetStartStop2 | オブジェクトの親を基準とする、オブジェクトの開始タイムと終了タイムを取得する。
GetSubObject | Visual Basic ではサポートされていない。
GetSubObjectGUID | Visual Basic ではサポートされていない。
GetSubObjectGUIDB | このオブジェクトに関連付けられているサブオブジェクトの GUID を取得する。
GetSubObjectLoaded | オブジェクトにサブオブジェクトが作成されているかどうかを調べる。
GetTimelineNoRef | Visual Basic ではサポートされていない。
GetTimelineType | オブジェクトのタイプを取得する。
GetUserData | アプリケーション定義の持続的データを取得する。
GetUserID | オブジェクトのアプリケーション定義の識別子を取得する。
GetUserName | オブジェクトのアプリケーション定義の名前を取得する。
Remove | このオブジェクトをタイムラインから削除して、他の場所に再挿入できるようにする。
RemoveAll | このオブジェクトを、サブオブジェクトと子を含めて、タイムラインから永続的に削除する。
SetDirtyRange | Visual Basic ではサポートされていない。
SetDirtyRange2 | Visual Basic ではサポートされていない。
SetLocked | オブジェクトの編集状態をロックまたはロック解除に設定する。
SetMuted | オブジェクトのミュート状態を設定する。
SetPropertySetter | Visual Basic ではサポートされていない。
SetStartStop | Visual Basic ではサポートされていない。
SetStartStop2 | オブジェクトの親を基準として、オブジェクトの開始タイムと終了タイムを設定する。
SetSubObject | Visual Basic ではサポートされていない。
SetSubObjectGUID | Visual Basic ではサポートされていない。
SetSubObjectGUIDB | このオブジェクトに関連付けられているサブオブジェクトの GUID を指定する。
SetTimelineType | Visual Basic ではサポートされていない。
SetUserData | アプリケーション定義の持続的データを設定する。
SetUserID | オブジェクトに対するアプリケーション定義の識別子を設定する。
SetUserName | オブジェクトに対するアプリケーション定義の名前を設定する。

ClearDirty メソッド (AMTimelineObj オブジェクト)

AMTimelineObj オブジェクト

Visual Basic ではサポートされていない。

構文

object.ClearDirty()

FixTimes メソッド (AMTimelineObj オブジェクト)

AMTimelineObj オブジェクト

Visual Basic ではサポートされていない。

構文

object.FixTimes(
pStart As <Unsupported variant type>,
pStop As <Unsupported variant type>
)

FixTimes2 メソッド (AMTimelineObj オブジェクト)

AMTimelineObj オブジェクト

指定された開始タイムと終了タイムを、親グループのフレーム レート設定によって定義される最も近いフレーム境界に丸める。

構文

object.FixTimes2(
pStart As Double,
REFTIME As Double*pStop
)

パラメータ

object
結果が AMTimelineObj オブジェクトになるオブジェクト式。
pStart
開始タイム (秒単位) が設定されている変数。呼び出しが成功した場合は、丸められた時間が設定される。
pStop
終了タイム (秒単位) が設定されている変数。呼び出しが成功した場合は、丸められた時間が設定される。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次の値が設定される場合がある。

E_NOTINTREE オブジェクトがタイムライン内にない。

注意

レンダリング時に、DES はオブジェクトの開始タイムと終了タイムを、最も近いフレーム境界に丸める。ただし、DES はオブジェクトの時間は書き換えない。グループのフレーム レートを変更した場合、丸められた時間は必ず元の時間から計算される。詳細については、「フレーム レート」を参照すること。

このメソッドを使用して、レンダリングされたオブジェクト内での正確な開始タイムと終了タイムを特定できる。たとえば、プロジェクト内でシークする場合は、元の時間ではなく丸められた時間をシークしなければならない。GetStartStop2 を呼び出して元の時間を取得し、その値を FixTimes2 に渡す。

GetDirtyRange メソッド (AMTimelineObj オブジェクト)

AMTimelineObj オブジェクト

Visual Basic ではサポートされていない。

構文

object.GetDirtyRange(
pStart As <Unsupported variant type>,
pStop As <Unsupported variant type>
)

GetDirtyRange2 メソッド (AMTimelineObj オブジェクト)

AMTimelineObj オブジェクト

Visual Basic ではサポートされていない。

構文

object.GetDirtyRange2(
pStart As Double,
pStop As Double
)

GetEmbedDepth メソッド (AMTimelineObj オブジェクト)

AMTimelineObj オブジェクト

Visual Basic ではサポートされていない。

構文

object.GetEmbedDepth(
pVal As Long
)

GetGenID メソッド (AMTimelineObj オブジェクト)

AMTimelineObj オブジェクト

オブジェクトの生成された識別子を取得する。識別子は予約された番号である。アプリケーションで使用してはならない。

構文

object.GetGenID(
pVal As Long
)

パラメータ

object
結果が AMTimelineObj オブジェクトになるオブジェクト式。
pVal
生成された識別子を受け取る変数。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

GetGroupIBelongTo メソッド (AMTimelineObj オブジェクト)

AMTimelineObj オブジェクト

Visual Basic ではサポートされていない。

構文

object.GetGroupIBelongTo(
ppGroup As AMTimelineGroup
)

GetLocked メソッド (AMTimelineObj オブジェクト)

AMTimelineObj オブジェクト

オブジェクトの編集状態 (ロックまたはロック解除) を取得する。ロック状態はオブジェクトを編集してはならないことを示し、ロック解除状態はオブジェクトを編集できることを示す。タイムライン側では、ロックを強制しない。ロック状態の設定は、アプリケーション側の利便性のためにのみ存在する。

構文

GetLocked(
pVal As Long
)

パラメータ

object
結果が AMTimelineObj オブジェクトになるオブジェクト式。
pVal
オブジェクトの編集状態を受け取る変数。値がゼロの場合は、オブジェクトはロック解除されているので編集できる。値がゼロ以外の場合は、オブジェクトはロックされているので、編集してはならない。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

GetMuted メソッド (AMTimelineObj オブジェクト)

AMTimelineObj オブジェクト

オブジェクトのミュート状態を取得する。ミュートされたオブジェクトはレンダリングされないが、タイムライン内には存在したままとなる。

構文

object.GetMuted(
pVal As Long
)

パラメータ

object
結果が AMTimelineObj オブジェクトになるオブジェクト式。
pVal
ミュート状態を示す値を受け取る変数。値がゼロの場合は、オブジェクトはミュートされていない。値がゼロ以外の場合は、オブジェクトとその子はミュートされている。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

注意

オブジェクトの親がミュートされている場合、ミュート状態とは無関係に、そのオブジェクトもミュートされる。親のミュートが解除されたときは、そのオブジェクトの前のミュート状態が復元される。

GetPropertySetter メソッド (AMTimelineObj オブジェクト)

AMTimelineObj オブジェクト

Visual Basic ではサポートされていない。

構文

object.GetPropertySetter() As PropertySetter

GetStartStop メソッド (AMTimelineObj オブジェクト)

AMTimelineObj オブジェクト

Visual Basic ではサポートされていない。

構文

object.GetStartStop(
pStart As <Unsupported variant type>,
pStop As <Unsupported variant type>
)

GetStartStop2 メソッド (AMTimelineObj オブジェクト)

AMTimelineObj オブジェクト

オブジェクトの親を基準とする、オブジェクトの開始タイムと終了タイムを取得する。

構文

object.GetStartStop2(
pStart As Double,
pStop As Double
)

パラメータ

object
結果が AMTimelineObj オブジェクトになるオブジェクト式。
pStart
開始タイム (秒単位) を受け取る変数。
pStop
終了タイム (秒単位) を受け取る変数。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

注意

合成、グループ、およびトラックの開始タイムは常に 0 である。

レンダリング時に、DES はオブジェクトの開始タイムと終了タイムを、最も近いフレーム境界に丸める。ただし、DES はオブジェクトの時間は書き換えない。グループのフレーム レートを変更した場合、丸められた時間は必ず元の時間から計算される。詳細については、「フレーム レート」を参照すること。レンダリングされたプロジェクト内での開始タイムを終了タイムを調べるには、GetStartStop2 が返す値を FixTimes2 メソッドに渡す。

GetSubObject メソッド (AMTimelineObj オブジェクト)

AMTimelineObj オブジェクト

Visual Basic ではサポートされていない。

構文

object.GetSubObject(
pVal As Unknown
)

GetSubObjectGUID メソッド (AMTimelineObj オブジェクト)

AMTimelineObj オブジェクト

Visual Basic ではサポートされていない。

構文

object.GetSubObjectGUID(
pVal As GUID
)

GetSubObjectGUIDB メソッド (AMTimelineObj オブジェクト)

AMTimelineObj オブジェクト

このタイムライン オブジェクトに関連付けられているサブオブジェクトの GUID を取得する。

構文

object.GetSubObjectGUIDB() As String

パラメータ

object
結果が AMTimelineObj オブジェクトになるオブジェクト式。

戻り値

サブオブジェクトの GUID を表す文字列を返す。オブジェクトにサブオブジェクトがない場合は、戻り値は {00000000-0000-0000-0000-000000000000} である。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次の値が設定される場合がある。

E_OUTOFMEMORY メモリ不足。

GetSubObjectLoaded メソッド (AMTimelineObj オブジェクト)

AMTimelineObj オブジェクト

オブジェクトにサブオブジェクトが作成されているかどうかを調べる。

構文

object.GetSubObjectLoaded(
pVal As Long
)

パラメータ

object
結果が AMTimelineObj オブジェクトになるオブジェクト式。
pVal
サブオブジェクトが作成されているかどうかを示す値を受け取る変数。ゼロの場合は、サブオブジェクトは作成されていない。ゼロ以外の場合は、サブオブジェクトは作成されている。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

GetTimelineNoRef メソッド (AMTimelineObj オブジェクト)

AMTimelineObj オブジェクト

Visual Basic ではサポートされていない。

構文

object.GetTimelineNoRef(
ppResult As AMTimeline
)

GetTimelineType メソッド (AMTimelineObj オブジェクト)

AMTimelineObj オブジェクト

オブジェクトのタイプを取得する。

構文

object.GetTimelineType(
pVal As TIMELINE_MAJOR_TYPE
)

パラメータ

object
結果が AMTimelineObj オブジェクトになるオブジェクト式。
pVal
オブジェクトのタイプを示す、TIMELINE_MAJOR_TYPE 列挙型のメンバを受け取る変数。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

GetUserData メソッド (AMTimelineObj オブジェクト)

AMTimelineObj オブジェクト

Visual Basic ではサポートされていない。

構文

object.GetUserData(
pData As Byte,
pSize As Long
)

パラメータ

object
結果が AMTimelineObj オブジェクトになるオブジェクト式。
pData
データを保持するバイト配列への参照。
pSize
配列のサイズ (バイト単位)。メソッドから戻った時点では、必要なサイズが設定されている。「注意」を参照すること。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

注意

このメソッドは、ユーザー データに必要な配列サイズを pSize の値に設定する。ReDim 文を使って配列のサイズを変更し、メソッドをもう一度呼び出す。配列の最初の要素をパラメータの値として使い、pData パラメータを参照として渡す。

Dim UserData(0) As Byte
Dim Size As Long

' 必要なサイズを調べる
ReDim UserData(1)
objTimelineObject.GetUserData UserData(0), Size

' 配列のサイズを変更し、すべてのデータを取得する
If Size <> 0 Then
ReDim UserData(Size)
objTimelineObject.GetUserData UserData(0), Size
End If

GetUserID メソッド (AMTimelineObj オブジェクト)

AMTimelineObj オブジェクト

オブジェクトのアプリケーション定義の識別子を取得する。

構文

object.GetUserID(
pVal As Long
)

パラメータ

object
結果が AMTimelineObj オブジェクトになるオブジェクト式。
pVal
アプリケーション定義の識別子を受け取る変数。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

GetUserName メソッド (AMTimelineObj オブジェクト)

AMTimelineObj オブジェクト

オブジェクトのアプリケーション定義の名前を取得する。

構文

object.GetUserName() As String

パラメータ

object
結果が AMTimelineObj オブジェクトになるオブジェクト式。

戻り値

アプリケーション定義の名前を示す文字列を返す。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次の値が設定される場合がある。

E_OUTOFMEMORY メモリ不足。

Remove メソッド (AMTimelineObj オブジェクト)

AMTimelineObj オブジェクト

このオブジェクトを (サブオブジェクトは含むが、子は含まない)、他の場所へ再挿入できるように、タイムラインから削除する。

構文

object.Remove()

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

注意

このメソッドは、アプリケーションが即座にそのオブジェクトをタイムラインに挿入する場合にのみ呼び出す。このメソッドの呼び出しに続いてオブジェクトを再挿入しないのは、無効な操作である。オブジェクトを永続的に削除するには、RemoveAll を使用する。

RemoveAll メソッド (AMTimelineObj オブジェクト)

AMTimelineObj オブジェクト

このオブジェクトを、サブオブジェクトと子を含めて、タイムラインから永続的に削除する。

構文

object.RemoveAll()

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

注意

オブジェクトをタイムラインの別の場所に再挿入する目的で削除するには、Remove を使用する。

SetDirtyRange メソッド (AMTimelineObj オブジェクト)

AMTimelineObj オブジェクト

Visual Basic ではサポートされていない。

構文

object.SetDirtyRange(
Start As <Unsupported variant type>,
Stop As <Unsupported variant type>
)

SetDirtyRange2 メソッド (AMTimelineObj オブジェクト)

AMTimelineObj オブジェクト

Visual Basic ではサポートされていない。

構文

object.SetDirtyRange2(
Start As Double,
Stop As Double
)

SetLocked メソッド (AMTimelineObj オブジェクト)

AMTimelineObj オブジェクト

オブジェクトの編集状態をロックまたはロック解除に設定する。ロック状態はオブジェクトを編集してはならないことを示し、ロック解除状態はオブジェクトを編集できることを示す。タイムライン側では、ロックを強制しない。ロック状態の設定は、アプリケーション側の利便性のためにのみ存在する。

構文

object.SetLocked(
newVal As Long
)

パラメータ

object
結果が AMTimelineObj オブジェクトになるオブジェクト式。
newVal
オブジェクトの編集状態を指定する値。ゼロの場合は、オブジェクトはロック解除されて、編集できるようになる。ゼロ以外の場合は、オブジェクトはロックされて、編集できなくなる。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

SetMuted メソッド (AMTimelineObj オブジェクト)

AMTimelineObj オブジェクト

オブジェクトのミュート状態を設定する。ミュートされたオブジェクトはレンダリングされないが、タイムライン内には存在したままとなる。

構文

object.SetMuted(
newVal As Long
)

パラメータ

object
結果が AMTimelineObj オブジェクトになるオブジェクト式。
newVal
ミュート状態を指定する値。ゼロの場合は、オブジェクトはミュートされない。ゼロ以外の場合は、オブジェクトとそのすべての子はミュートされる。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

注意

オブジェクトをミュートすると、そのオブジェクトが持つ子もすべてミュートされる。たとえば、あるトラックをミュートすると、そのトラック内のトランジション、ソース、およびエフェクトもすべてミュートされる。オブジェクトのミュートが解除されると、その子はそれぞれの前の状態 (ミュートまたはミュート解除) に戻る。

SetPropertySetter メソッド (AMTimelineObj オブジェクト)

AMTimelineObj オブジェクト

Visual Basic ではサポートされていない。

構文

object.SetPropertySetter(
newVal As PropertySetter
)

SetStartStop メソッド (AMTimelineObj オブジェクト)

AMTimelineObj オブジェクト

Visual Basic ではサポートされていない。

構文

object.SetStartStop(
Start As <Unsupported variant type>,
Stop As <Unsupported variant type>
)

SetStartStop2 メソッド (AMTimelineObj オブジェクト)

AMTimelineObj オブジェクト

オブジェクトの親を基準として、オブジェクトの開始タイムと終了タイムを設定する。

構文

object.SetStartStop2(
Start As Double,
Stop As Double
)

パラメータ

object
結果が AMTimelineObj オブジェクトになるオブジェクト式。
Start
新しい開始タイム (秒単位)。 既存の開始タイムを維持する場合は -1。
Stop
新しい終了タイム (秒単位)。 既存の終了タイムを維持する場合は -1。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次のいずれかの値が設定される場合がある。

E_INVALIDARG | 無効な引数。
E_NOTIMPL | 実装されていない。

注意

トラック、合成、およびグループは、このメソッドを実装しない。これらのオブジェクトでは、開始タイムは常にゼロであり、終了タイムは含まれるオブジェクトの最大の終了タイムである。

同じトラック内のソース オブジェクトで重なり合う時間を設定してはならない。そのような設定を行うと、未定義の動作が発生する場合がある。

ソース オブジェクトの場合、開始タイムと終了タイムは、メディア開始タイムおよびメディア終了タイムから独立している。これらの一方の組を変更しても、もう一方に影響はない。メディアの開始タイムと終了タイムを設定するには、AMTimelineSrc.SetMediaTimes2 メソッドを使用する。詳細については、「DirectShow 編集サービスにおける時間」を参照すること。

SetSubObject メソッド (AMTimelineObj オブジェクト)

AMTimelineObj オブジェクト

Visual Basic ではサポートされていない。

構文

object.SetSubObject(
newVal As Unknown
)

SetSubObjectGUID メソッド (AMTimelineObj オブジェクト)

AMTimelineObj オブジェクト

Visual Basic ではサポートされていない。

構文

object.SetSubObjectGUID(
newVal As GUID
)

SetSubObjectGUIDB メソッド (AMTimelineObj オブジェクト)

AMTimelineObj オブジェクト

このオブジェクトに関連付けられているサブオブジェクトの GUID を指定する。

構文

object.SetSubObjectGUIDB(
newVal As String
)

パラメータ

object
結果が AMTimelineObj オブジェクトになるオブジェクト式。
newVal
サブオブジェクトの GUID を表す文字列。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

注意

レンダリング エンジンは、必要に応じてサブオブジェクトのインスタンスを作成する。

SetTimelineType メソッド (AMTimelineObj オブジェクト)

AMTimelineObj オブジェクト

Visual Basic ではサポートされていない。新しいタイムライン オブジェクトを作成するには、AMTimeline.CreateEmptyNode メソッドを使用する。オブジェクトを作成した後では、そのタイプは変更できない。

構文

object.SetTimelineType(
newVal As TIMELINE_MAJOR_TYPE
)

SetUserData メソッド (AMTimelineObj オブジェクト)

AMTimelineObj オブジェクト

アプリケーション定義の持続的データを設定する。

構文

object.SetUserData(
pData As Byte,
Size As Long
)

パラメータ

object
結果が AMTimelineObj オブジェクトになるオブジェクト式。
pData
データを保持するバイト配列への参照。
Size
配列のサイズ (バイト単位)。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次の値が設定される場合がある。

E_OUTOFMEMORY メモリ不足。

注意

配列の最初の要素をパラメータの値として使い、pData パラメータを参照として渡す。

Dim UserData(100) As Byte
' 配列を初期化する (省略)
objTimelineObject.SetUserData UserData(0), 100

SetUserID メソッド (AMTimelineObj オブジェクト)

AMTimelineObj オブジェクト

オブジェクトに対するアプリケーション定義の識別子を設定する。

構文

object.SetUserID(
newVal As Long
)

パラメータ

object
結果が AMTimelineObj オブジェクトになるオブジェクト式。
newVal
識別子を指定する値。この識別子は、アプリケーションによってのみ使用され、どのような値でもかまわない。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

SetUserName メソッド (AMTimelineObj オブジェクト)

AMTimelineObj オブジェクト

オブジェクトに対するアプリケーション定義の名前を設定する。

構文

object.SetUserName(
newVal As String
)

パラメータ

object
結果が AMTimelineObj オブジェクトになるオブジェクト式。
newVal
名前を表す文字列。256 文字を超える文字列は、切り詰められることがある。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。


AMTimelineSrc オブジェクト

Microsoft® DirectShow 編集サービス (DES) のソースの操作とプロパティの設定を行うメソッドを提供する。AMTimelineSrc オブジェクトは、メディア ソースの 1 つのストリームから取得されたクリップを表している。

メディア開始タイムとメディア終了タイムを設定することにより、ソース ファイル内のデータの一部分を使用できる。この 2 つの値は、元のメディア ソースを基準として、AMTimelineSrc オブジェクトの始まりと終わりを指定する。メディア タイムは、タイムライン上でのオブジェクトの開始タイムおよび終了タイムとは異なる場合があり、速度を変えた再生 (オーディオ ソースではピッチ シフト) が可能である。

メソッド

FixMediaTimes | Visual Basic ではサポートされていない。
FixMediaTimes2 | 指定されたタイム値を、出力フレーム レートによって定義される最も近いフレーム境界に丸める。
GetDefaultFPS | ソース オブジェクトのデフォルトのフレーム レートを取得する。
GetMediaLength | Visual Basic ではサポートされていない。
GetMediaLength2 | このオブジェクトのメディア長を取得する。
GetMediaName | このオブジェクトが表すソース ファイルの名前を取得する。
GetMediaTimes | Visual Basic ではサポートされていない。
GetMediaTimes2 | メディアの開始タイムと終了タイムを取得する。
GetStreamNumber | ソース オブジェクトの現在のストリーム番号を取得する。
GetStretchMode | 伸縮モードを取得する。
IsNormalRate | クリップが作成時の再生レートで再生されるかどうかを示す。
ModifyStopTime | Visual Basic ではサポートされていない。
ModifyStopTime2 | 終了タイムを設定する。
SetDefaultFPS | ソース オブジェクトのデフォルトのフレーム レートを設定する。
SetMediaLength | Visual Basic ではサポートされていない。
SetMediaLength2 | ソース ファイルの時間幅を指定する。
SetMediaName | ソース ファイルの名前を指定する。
SetMediaTimes | Visual Basic ではサポートされていない。
SetMediaTimes2 | メディアの終了タイムと開始タイムを設定する。
SetStretchMode | 伸縮モードを設定する。
SetStreamNumber | ソース ファイルから読み取るストリームを指定する。
SpliceWithNext | AMTimelineSrc オブジェクトを別の AMTimelineSrc オブジェクトに結合する。

FixMediaTimes メソッド (AMTimelineSrc オブジェクト)

AMTimelineSrc オブジェクト

Visual Basic ではサポートされていない。

構文

object.FixMediaTimes(
pStart As <Unsupported variant type>,
pStop As <Unsupported variant type>
)

FixMediaTimes2 メソッド (AMTimelineSrc オブジェクト)

AMTimelineSrc オブジェクト

指定されたタイム値を、出力フレーム レートによって定義される最も近いフレーム境界に丸める。通常、アプリケーションでこのメソッドを呼び出す必要はない。

構文

object.FixMediaTimes2(
pStart As Double,
pStop As Double
)

パラメータ

object
結果が AMTimelineSrc オブジェクトになるオブジェクト式。
pStart
開始タイム (秒単位)。呼び出しが成功した場合、この変数には丸められた時間が設定される。
pStop
終了タイム (秒単位)。呼び出しが成功した場合、この変数には丸められた時間が設定される。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

注意

このメソッドは AMTimelineObj.FixTimes2 メソッドと似ているが、このメソッドではメディア タイムとタイムライン タイムの元の比率が維持される。最も近いフレーム境界に時間を丸めることにより、この比が変化することがある。

GetDefaultFPS メソッド (AMTimelineSrc オブジェクト)

AMTimelineSrc オブジェクト

ソース オブジェクトのデフォルトのフレーム レートを取得する。レンダリング エンジンが元のソースからフレーム レートを特定できない場合、この値が使用される。

構文

object.GetDefaultFPS(
pFPS As Double
)

パラメータ

object
結果が AMTimelineSrc オブジェクトになるオブジェクト式。
pFPS
デフォルトのフレーム レート (毎秒のフレーム数) を受け取る変数。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

注意

ファイル フォーマットでフレーム レートが指定されている場合は、デフォルトのフレーム レートは必要ない。これは、オーディオおよびビデオのフォーマットの場合に当てはまる。

ソースがビットマップまたは JPEG イメージの場合、レンダリング エンジンはそれをデバイスに依存しないビットマップ (DIB) シーケンスの最初のイメージとして使用し、フレーム レートはデフォルトのフレーム レートを使用する。DIB シーケンスではなくスタティック イメージをレンダリングするには、デフォルトのフレーム レートを 0 に設定する。

ソースが GIF の場合は、フレーム レートを設定してはならない。アニメーション GIF の場合は、GIF ファイルが各イメージ間の遅延を指定する。

GetMediaLength メソッド (AMTimelineSrc オブジェクト)

AMTimelineSrc オブジェクト

Visual Basic ではサポートされていない。

構文

object.GetMediaLength(
pLength As <Unsupported variant type>
)

GetMediaLength2 メソッド (AMTimelineSrc オブジェクト)

AMTimelineSrc オブジェクト

このオブジェクトのメディア長を取得する。

構文

object.GetMediaLength2(
pLength As Double
)

パラメータ

object
結果が AMTimelineSrc オブジェクトになるオブジェクト式。
pLength
メディア長 (秒単位) を受け取る変数。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次の値が設定される場合がある。

E_NOTDETERMINED このオブジェクトにメディア時間は設定されていない。

参照

SetMediaLength2

GetMediaName メソッド (AMTimelineSrc オブジェクト)

AMTimelineSrc オブジェクト

このオブジェクトが表すソース ファイルの名前を取得する。

構文

object.GetMediaName() As String

パラメータ

object
結果が AMTimelineSrc オブジェクトになるオブジェクト式。

戻り値

ソース ファイルの名前を返す。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次の値が設定される場合がある。

E_OUTOFMEMORY メモリ不足。

GetMediaTimes メソッド (AMTimelineSrc オブジェクト)

AMTimelineSrc オブジェクト

Visual Basic ではサポートされていない。

構文

object.GetMediaTimes(
pStart As <Unsupported variant type>,
pStop As <Unsupported variant type>
)

GetMediaTimes2 メソッド (AMTimelineSrc オブジェクト)

AMTimelineSrc オブジェクト

メディアの開始タイムと終了タイムを取得する。

構文

object.GetMediaTimes2(
pStart As Double,
pStop As Double
)

パラメータ

object
結果が AMTimelineSrc オブジェクトになるオブジェクト式。
pStart
メディアの開始タイム (秒単位) を受け取る変数。
pStop
メディアの終了タイム (秒単位) を受け取る変数。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

注意

メディアの時間は、元のメディア ファイルを基準とする。詳細については、「DirectShow 編集サービスにおける時間」を参照すること。

GetStreamNumber メソッド (AMTimelineSrc オブジェクト)

AMTimelineSrc オブジェクト

ソース オブジェクトの現在のストリーム番号を取得する。

構文

object.GetStreamNumber(
pVal As Long
)

パラメータ

object
結果が AMTimelineSrc オブジェクトになるオブジェクト式。
pVal
ストリーム番号を受け取る変数。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

GetStretchMode メソッド (AMTimelineSrc オブジェクト)

AMTimelineSrc オブジェクト

伸縮モードを取得する。伸縮モードは、ビデオ ソースのサイズが出力ディメンジョンと一致しない場合の、ビデオ ソースのレンダリング方法を指定する。

構文

object.GetStretchMode(
pnStretchMode As Long
)

パラメータ

object
結果が AMTimelineSrc オブジェクトになるオブジェクト式。
pnStretchMode
次のいずれかの値を受け取る変数。
  • RESIZEF_STRETCH
  • RESIZEF_CROP
  • RESIZEF_PRESERVEASPECTRATIO
  • RESIZEF_PRESERVEASPECTRATIO_NOLETTERBOX

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

IsNormalRate メソッド (AMTimelineSrc オブジェクト)

AMTimelineSrc オブジェクト

クリップが作成時の再生レートで再生されるかどうかを示す。

構文

object.IsNormalRate(
pVal As Long
)

パラメータ

object
結果が AMTimelineSrc オブジェクトになるオブジェクト式。
pVal
クリップのレンダリング方法を示す値を受け取る変数。ゼロ以外の場合は、クリップは通常のレートで再生される。ゼロの場合は、通常とは異なる速度で再生される。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

注意

クリップの再生レートは、タイムライン タイムを基準とするメディアの開始タイムと終了タイムによって決まる。

再生レート = (メディア終了タイム - メディア開始タイム) / (タイムライン終了タイム - タイムライン開始タイム)

この比が 1 に等しい場合、クリップは作成時の速度で再生される。そうでない場合は、通常とは異なる速度で再生される。詳細については、「DirectShow 編集サービスにおける時間」を参照すること。

ModifyStopTime メソッド (AMTimelineSrc オブジェクト)

AMTimelineSrc オブジェクト

Visual Basic ではサポートされていない。

構文

object.ModifyStopTime(
Stop As <Unsupported variant type>
)

ModifyStopTime2 メソッド (AMTimelineSrc オブジェクト)

AMTimelineSrc オブジェクト

終了タイムを設定する。

構文

object.ModifyStopTime2(
Stop As Double
)

パラメータ

object
結果が AMTimelineSrc オブジェクトになるオブジェクト式。
Stop
新しい終了タイム (秒単位)。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次の値が設定される場合がある。

E_INVALIDARG 指定された時間が無効である。

SetDefaultFPS メソッド (AMTimelineSrc オブジェクト)

AMTimelineSrc オブジェクト

ソース オブジェクトのデフォルト フレーム レートを設定する。

構文

object.SetDefaultFPS(
FPS As Double
)

パラメータ

object
結果が AMTimelineSrc オブジェクトになるオブジェクト式。
FPS
デフォルトのフレーム レート (毎秒のフレーム数)。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次の値が設定される場合がある。

E_INVALIDARG 指定されたフレーム レートが、ゼロより小さい。

注意

レンダリング エンジンが元のソース ファイルからフレーム レートを特定できない場合、この値が使用される。

このメソッドは、定義済みのフレーム レートを持たないソース ファイルに対してのみ呼び出す。ビットマップおよび JPEG ファイルの場合、デフォルト フレーム レートはゼロであり、それによりソースはスティル イメージとしてレンダリングされる。イメージを DIB シーケンスの最初のフレームとして使用するには、フレーム レートをゼロより大きな値に設定する。

SetMediaLength メソッド (AMTimelineSrc オブジェクト)

AMTimelineSrc オブジェクト

Visual Basic ではサポートされていない。

構文

object.SetMediaLength(
Length As <Unsupported variant type>
)

SetMediaLength2 メソッド (AMTimelineSrc オブジェクト)

AMTimelineSrc オブジェクト

ソース ファイルの時間幅を指定する。このメソッドは SetMediaLength メソッドと同じ機能だが、パラメータとして REFTIME の値をとる。

構文

object.SetMediaLength2(
Length As Double
)

パラメータ

object
結果が AMTimelineSrc オブジェクトになるオブジェクト式。
Length
メディア長 (秒単位)。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

注意

メディア終了タイムを設定する前にメディア長を設定することにより、潜在的なレンダリング エラーを回避できる。メディア終了タイムを設定すると、DES はそれをメディア長と付き合わせてチェックする。

このメソッドは Length パラメータを検証しないが、その値はソース ファイルの実際の時間幅と等しくなければならない。ソース ファイルの時間幅は、IMediaDet.StreamLength プロパティから取得する。

SetMediaName メソッド (AMTimelineSrc オブジェクト)

AMTimelineSrc オブジェクト

ソース ファイルの名前を指定する。

構文

object.SetMediaName(
newVal As String
)

パラメータ

object
結果が AMTimelineSrc オブジェクトになるオブジェクト式。
newVal
メディア ファイルの名前を指定する文字列。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

SetMediaTimes メソッド (AMTimelineSrc オブジェクト)

AMTimelineSrc オブジェクト

Visual Basic ではサポートされていない。

構文

object.SetMediaTimes(
Start As <Unsupported variant type>,
Stop As <Unsupported variant type>
)

SetMediaTimes2 メソッド (AMTimelineSrc オブジェクト)

AMTimelineSrc オブジェクト

メディアの終了タイムと開始タイムを設定する。

構文

object.SetMediaTimes2(
Start As Double,
Stop As Double
)

パラメータ

object
結果が AMTimelineSrc オブジェクトになるオブジェクト式。
Start
メディア開始タイム (秒単位)。
Stop
メディア終了タイム (秒単位)。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

注意

メディア タイムは、元のメディア ファイルを基準とするメディア終了タイムとメディア開始タイムである。ビデオ ソースまたはオーディオ ソースをタイムラインに追加するときは、必ずメディア タイムを設定する。設定しないと、レンダリングで問題が発生する場合がある。終了タイムは、開始タイムより大きな値でなければならない。

ビデオ ソースからスティル フレームを使用するには、開始タイムから小数点以下の値 (たとえば 100 ナノ秒) だけ大きい終了タイムを設定する。開始タイムと終了タイムを同じ値に設定すると、レンダリング エラーが発生する。

タイムラインの時間幅がメディアの時間幅と一致しない場合は、それに合わせてソースが伸縮する。これにより、クリップの再生は、作成時とは異なるレートで行われることになる (オーディオ ソースでは、ピッチ シフトが発生する)。詳細については、「DirectShow 編集サービスにおける時間」を参照すること。

ソース ファイルの時間幅は、SetMediaLength メソッドを呼び出すことにより指定できる。メディア終了タイムが時間幅を超える場合、DES は終了タイムを繰り上げる。

SetStreamNumber メソッド (AMTimelineSrc オブジェクト)

AMTimelineSrc オブジェクト

ソース ファイルから読み取るストリームを指定する。

構文

object.SetStreamNumber(
Val As Long
)

パラメータ

object
結果が AMTimelineSrc オブジェクトになるオブジェクト式。
Val
ストリーム番号。 親グループの、一致するメディア タイプのストリームのセットから指定する。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次の値が設定される場合がある。

E_INVALIDARG Val パラメータの値がゼロより小さい。

注意

Val パラメータは、親グループのメディア タイプに一致するストリームのセットにおけるストリーム番号を指定する。 これは、ソース ファイルのストリームのセット全体における番号ではない。たとえば、2 つのビデオ ストリームと 2 つのオーディオ ストリームがファイルにあるものとすて、AMTimelineSrc オブジェクトがビデオ グループの中にある場合は、Val に 0 を設定すると、最初のビデオ ストリームが選択される。呼び出し元が有効なストリーム番号を指定しなければならない。

ストリーム番号のデフォルトはゼロである。

SetStretchMode メソッド (AMTimelineSrc オブジェクト)

AMTimelineSrc オブジェクト

伸縮モードを設定する。伸縮モードは、ビデオ ソースのサイズが出力ディメンジョンと一致しない場合の、ビデオ ソースのレンダリング方法を指定する。

構文

object.SetStretchMode(
nStretchMode As Long
)

パラメータ

object
結果が AMTimelineSrc オブジェクトになるオブジェクト式。
nStretchMode
現在の伸縮モードを示すフラグ。次のいずれかの値でなければならない。
  • RESIZEF_STRETCH
  • RESIZEF_CROP
  • RESIZEF_PRESERVEASPECTRATIO
  • RESIZEF_PRESERVEASPECTRATIO_NOLETTERBOX

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

SpliceWithNext メソッド (AMTimelineSrc オブジェクト)

AMTimelineSrc オブジェクト

AMTimelineSrc オブジェクトを別の AMTimelineSrc オブジェクトに結合する。

構文

object.SpliceWithNext(
pNext As AMTimelineObj
)

パラメータ

object
結果が AMTimelineSrc オブジェクトになるオブジェクト式。
pNext
現在のソースに結合する AMTimelineObj オブジェクト。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次のいずれかの値が設定される場合がある。

E_INVALIDARG | 無効な引数。
E_NOINTERFACE | pNext パラメータによって指定されたオブジェクトがソース オブジェクトではない。

注意

現在の実装では、このメソッドは pNext 上のエフェクトは破棄する。

このメソッドを正しく動作させるには、pNext は現在のソース オブジェクトのフレームに一致していなければならない。

  • 同じソース ファイルを共有していなければならない。
  • メディア開始タイムが、現在のソースのメディア終了タイムと等しくなければならない。
  • 再生レートが同一でなければならない。再生レートは、メディア時間幅をタイムライン時間幅で割った値である。


AMTimelineTrack オブジェクト

Microsoft® DirectShow 編集サービス (DES) のトラック を操作するメソッドを提供する。

トラックには、最終出力でレンダリングされるソースのリストが入る。同じトラック内のソースは、オーバーラップできない。ビデオ トラックは、エフェクトとトランジションの両方を持つことができる。レンダリング エンジンは、トランジションを適用する前にエフェクトを適用する。オーディオ トラックは、エフェクトを持つことはできるが、トランジションを持つことはできない。

詳細については、「タイムライン モデル」を参照すること。

メソッド

AreYouBlank | トラックが空白 (ソース オブジェクトが入っていない) かどうかを調べる。
GetNextSrc | Visual Basic ではサポートされていない。
GetNextSrc2 | トラックで、指定された時間以降に出現する次のソースを検索する。
GetNextSrcEx | 指定されたソースに続く次のソースを取得する。
GetSourcesCount | トラック内のソースの個数を取得する。
GetSrcAtTime | Visual Basic ではサポートされていない。
GetSrcAtTime2 | 指定された境界条件に従って、指定された時間に最も近いソース オブジェクトを取得する。
InsertSpace | Visual Basic ではサポートされていない。
InsertSpace2 | 指定された時間に存在するすべてのオブジェクトを分割し、その間にスペースを挿入する。
MoveEverythingBy | Visual Basic ではサポートされていない。
MoveEverythingBy2 | トラックのオブジェクトのうち指定された時間に開始するものをすべて、タイムラインに沿って指定された距離だけ移動する。
SrcAdd | トラックにソースを追加する。
ZeroBetween | Visual Basic ではサポートされていない。
ZeroBetween2 | トラックから、指定された時間の間にあるものをすべて削除する。

AreYouBlank メソッド (AMTimelineTrack オブジェクト)

AMTimelineTrack オブジェクト

トラックが空白 (ソース オブジェクトが入っていない) かどうかを調べる。

構文

object.AreYouBlank(
pVal As Long
)

パラメータ

object
結果が AMTimelineTrack オブジェクトになるオブジェクト式。
pVal
トラックがブランクかどうかを指定する値を受け取る変数。ゼロ以外の場合は、オブジェクトは空白であり、ソース オブジェクトは入っていない。ゼロの場合は、トラックは空白ではない。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

GetNextSrc メソッド (AMTimelineTrack オブジェクト)

AMTimelineTrack オブジェクト

Visual Basic ではサポートされていない。

構文

object.GetNextSrc(
ppSrc AMTimelineObj,
pInOut As <Unsupported variant type>
)

GetNextSrc2 メソッド (AMTimelineTrack オブジェクト)

AMTimelineTrack オブジェクト

トラックで、指定された時間以降に出現する次のソースを検索する。

構文

object.GetNextSrc2(
ppSrc As AMTimelineObj,
pInOut As Double
)

パラメータ

object
結果が AMTimelineTrack オブジェクトになるオブジェクト式。
ppSrc
ソース オブジェクトを受け取る AMTimelineObj オブジェクト。
pInOut
検索を開始する時間 (秒単位)。ソースが取得された場合、この変数にはそのソースの終了タイムが設定される。ソースが取得されなかった場合、この値は無効になるので、アプリケーションで使用してはならない。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

注意

pInOut で指定された値がソースの開始タイムと終了タイムの間にある場合、メソッドはそのソースを取得する。

GetNextSrcEx メソッド (AMTimelineTrack オブジェクト)

AMTimelineTrack オブジェクト

指定されたソースに続く次のソースを取得する。

構文

object.GetNextSrcEx(
pLast As AMTimelineObj,
ppNext As AMTimelineObj
)

パラメータ

object
結果が AMTimelineTrack オブジェクトになるオブジェクト式。
pLast
前の AMTimelineObj オブジェクト。 トラック内の最初のソースを取得する場合は Nothing。
ppNext
次のソースを受け取る AMTimelineObj オブジェクト。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

GetSourcesCount メソッド (AMTimelineTrack オブジェクト)

AMTimelineTrack オブジェクト

トラック内のソースの個数を取得する。

構文

object.GetSourcesCount(
pVal As Long
)

パラメータ

object
結果が AMTimelineTrack オブジェクトになるオブジェクト式。
pVal
トラック内のソースの個数を受け取る変数。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

GetSrcAtTime メソッド (AMTimelineTrack オブジェクト)

AMTimelineTrack オブジェクト

Visual Basic ではサポートされていない。

構文

object.GetSrcAtTime(
ppSrc As AMTimelineObj,
Time As <Unsupported variant type>,
SearchDirection As Long
)

GetSrcAtTime2 メソッド (AMTimelineTrack オブジェクト)

AMTimelineTrack オブジェクト

指定された境界条件に従って、指定された時間に最も近いソース オブジェクトを取得する。

構文

object.GetSrcAtTime2(
ppSrc As AMTimelineObj,
Time As Double,
SearchDirection As Long
)

パラメータ

object
結果が AMTimelineTrack オブジェクトになるオブジェクト式。
ppSrc
ソースを受け取る AMTimelineObj オブジェクト。
Time
検索を開始する時間 (秒単位)。
SearchDirection
DEXTERF_TRACK_SEARCH_FLAGS 列挙型のメンバ。 検索の境界条件を指定する。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次の値が設定される場合がある。

E_INVALIDARG 無効な引数。

InsertSpace メソッド (AMTimelineTrack オブジェクト)

AMTimelineTrack オブジェクト

Visual Basic ではサポートされていない。

構文

object.InsertSpace(
rtStart As <Unsupported variant type>,
rtEnd As <Unsupported variant type>
)

InsertSpace2 メソッド (AMTimelineTrack オブジェクト)

AMTimelineTrack オブジェクト

指定された時間に存在するすべてのオブジェクトを分割し、その間にスペースを挿入する。

構文

object.InsertSpace2(
rtStart As Double,
rtEnd As Double
)

パラメータ

object
結果が AMTimelineTrack オブジェクトになるオブジェクト式。
rtStart
分割を行う時間、また挿入されるスペースの始点 (秒単位)。
rtEnd
挿入されるスペースの終点 (秒単位)。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次の値が設定される場合がある。

E_INVALIDARG 無効な引数。

MoveEverythingBy メソッド (AMTimelineTrack オブジェクト)

AMTimelineTrack オブジェクト

Visual Basic ではサポートされていない。

構文

object.MoveEverythingBy(
Start As <Unsupported variant type>,
MoveBy As <Unsupported variant type>
)

MoveEverythingBy2 メソッド (AMTimelineTrack オブジェクト)

AMTimelineTrack オブジェクト

トラックのオブジェクトのうち指定された時間に開始するものをすべて、タイムラインに沿って指定された距離だけ移動する。

構文

object.MoveEverythingBy2(
Start As Double,
MoveBy As Double
)

パラメータ

object
結果が AMTimelineTrack オブジェクトになるオブジェクト式。
Start
移動の開始タイム (秒単位)。この時間以降に開始するオブジェクトだけが移動される。
MoveBy
タイムライン上でオブジェクトを移動する時間の量 (秒単位)。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

SrcAdd メソッド (AMTimelineTrack オブジェクト)

AMTimelineTrack オブジェクト

トラックにソースを追加する。

構文

object.SrcAdd(
pSrc As AMTimelineObj
)

パラメータ

object
結果が AMTimelineTrack オブジェクトになるオブジェクト式。
pSrc
追加する AMTimelineObj オブジェクト。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次の値が設定される場合がある。

E_NOINTERFACE pSrc で指定されているオブジェクトが、ソース オブジェクトではない。

注意

このメソッドを呼び出す前に、ソースの開始タイムと終了タイムを設定する必要がある (AMTimelineObj.SetStartStop メソッドを呼び出す)。

現在 DES は、ビデオ圧縮マネージャ (VCM) CODECで圧縮されたソースは、同時に 75 個までしかレンダリングできない。また、そのようなソースがプロジェクト全体で 75 個を超える場合は、動的な再接続を使わなければ、DES はプロジェクトをプレビューできない。詳細については、「RenderEngine.SetDynamicReconnectLevel」を参照すること。

ZeroBetween メソッド (AMTimelineTrack オブジェクト)

AMTimelineTrack オブジェクト

Visual Basic ではサポートされていない。

構文

object.ZeroBetween(
rtStart As <Unsupported variant type>,
rtEnd As <Unsupported variant type>
)

ZeroBetween2 メソッド (AMTimelineTrack オブジェクト)

AMTimelineTrack オブジェクト

トラックから、指定された時間の間にあるものをすべて削除する。このメソッドは、指定された時間範囲にかかっているすべてのオブジェクトを分割し、その範囲内にある部分を削除する。

構文

object.ZeroBetween2(
rtStart As Double,
rtEnd As Double
)

パラメータ

object
結果が AMTimelineTrack オブジェクトになるオブジェクト式。
rtStart
クリアする範囲の始点 (秒単位)。
rtEnd
クリアする範囲の終点 (秒単位)。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。


AMTimelineTrans オブジェクト

Microsoft® DirectShow 編集サービス (DES) でトランジションを操作するためのメソッドを提供する。

トランジションは、1 つのレイヤと、それより低い優先順位のすべてのレイヤのレンダリングされた合成との間で進行する。AMTimelineTrans オブジェクトは、2 つの入力を持つ Microsoft® DirectX® 変換オブジェクトに対するラッパーである。DirectX Transform オブジェクトを指定するには、AMTimelineObj.SetSubObjectGUID メソッドを呼び出す。

トランジションを持つことのできるタイムライン オブジェクトは、IAMTimelineTransable オブジェクトをサポートする。

メソッド

GetCutPoint | Visual Basic ではサポートされていない。
GetCutPoint2 | カット ポイントを取得する。
GetCutsOnly | トランジションがカットとしてレンダリングされるかどうかを調べる。
GetSwapInputs | トランジションの入力がスワップされるかどうかを調べる。
SetCutPoint | Visual Basic ではサポートされていない。
SetCutPoint2 | カット ポイントを設定する。
SetCutsOnly | トランジションがカットとしてレンダリングされるかどうかを指定する。
SetSwapInputs | トランジションの入力がスワップされるかどうかを指定する。

GetCutPoint メソッド (AMTimelineTrans オブジェクト)

AMTimelineTrans オブジェクト

Visual Basic ではサポートされていない。

構文

object.GetCutPoint(
pTLTime As <Unsupported variant type>
)

GetCutPoint2 メソッド (AMTimelineTrans オブジェクト)

AMTimelineTrans オブジェクト

カット ポイントを取得する。トランジションをカット (直接切り替え) としてレンダリングする場合、カット ポイントはトランジションが一方のソースから次のソースに切り替わる時間である。デフォルトでは、この値はトランジションの中間点である。たとえば、2 秒間のトランジションでは、デフォルトのカット ポイントはトランジションの 1 秒の位置である。

構文

object.GetCutPoint2(
pTLTime As Double
)

パラメータ

object
結果が AMTimelineTrans オブジェクトになるオブジェクト式。
pTLTime
トランジションの開始タイムを基準とするカット ポイントの値を受け取る変数。単位は秒。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

参照

SetCutPoint2、GetCutsOnly、AMTimeline.TransitionsEnabled

GetCutsOnly メソッド (AMTimelineTrans オブジェクト)

AMTimelineTrans オブジェクト

トランジションがカットとしてレンダリングされるかどうかを調べる。カットとしてレンダリングされる場合、トランジションはカット ポイントで即座に行われる。

構文

object.GetCutsOnly(
pVal As Long
)

パラメータ

object
結果が AMTimelineTrans オブジェクトになるオブジェクト式。
pVal
トランジションがカットとしてレンダリングされるかどうかを示す値を受け取る変数。ゼロ以外の場合、トランジションは即時カットである。ゼロの場合、トランジションは通常の時間幅で行われる。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

参照

SetCutsOnly、GetCutPoint、AMTimeline.TransitionsEnabled

GetSwapInputs メソッド (AMTimelineTrans オブジェクト)

AMTimelineTrans オブジェクト

トランジションの入力がスワップされるかどうかを調べる。

デフォルトでは、トランジションは優先順位の低いレイヤの合成から、トランジションが存在するレイヤに向かって行われる。この進行方向を逆にすることができ、その場合、トランジションはトランジションが存在するレイヤから、優先順位の低いレイヤの合成に向かって行われる。

構文

object.GetSwapInputs(
pVal As Long
)

パラメータ

object
結果が AMTimelineTrans オブジェクトになるオブジェクト式。
pVal
入力がスワップされるかどうかを示す値を受け取る変数。この値がゼロの場合、トランジションは優先順位の低いすべてのレイヤの合成から、そのトランジションが存在するレイヤに向かって行われる。この値がゼロ以外の場合、トランジションは逆の方向で行われる。デフォルト値はゼロ。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

SetCutPoint メソッド (AMTimelineTrans オブジェクト)

AMTimelineTrans オブジェクト

Visual Basic ではサポートされていない。

構文

object.SetCutPoint(
TLTime As <Unsupported variant type>
)

SetCutPoint2 メソッド (AMTimelineTrans オブジェクト)

AMTimelineTrans オブジェクト

カット ポイントを設定する。トランジションをカット (直接切り替え) としてレンダリングする場合、カット ポイントはトランジションが一方のソースから次のソースに切り替わる時間である。デフォルトでは、カット ポイントはトランジションの中間点である。たとえば、2 秒間のトランジションでは、デフォルトのカット ポイントはトランジションの 1 秒の位置である。

構文

object.SetCutPoint2(
TLTime As Double
)

パラメータ

object
結果が AMTimelineTrans オブジェクトになるオブジェクト式。
TLTime
トランジションの始点を基準とするカット ポイント (秒単位)。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

SetCutsOnly メソッド (AMTimelineTrans オブジェクト)

AMTimelineTrans オブジェクト

トランジションがカットとしてレンダリングされるかどうかを指定する。カットとしてレンダリングされる場合、トランジションはカット ポイントで即座に行われる。トランジションのレンダリングに時間がかかる場合、カットとしてレンダリングしてプレビューの時間を短縮できる。

構文

object.SetCutsOnly(
Val As Long
)

パラメータ

object
結果が AMTimelineTrans オブジェクトになるオブジェクト式。
Val
トランジションをカットとしてレンダリングするかどうかを示す値。ゼロを指定すると、トランジションは即時カットとしてレンダリングされる。ゼロ以外を指定すると、トランジションは通常の時間幅でレンダリングされる。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

SetSwapInputs メソッド (AMTimelineTrans オブジェクト)

AMTimelineTrans オブジェクト

トランジションの入力がスワップされるかどうかを指定する。

デフォルトでは、トランジションは優先順位の低いレイヤの合成から、トランジションが存在するレイヤに向かって行われる。この進行方向を逆にすることができ、その場合、トランジションはトランジションが存在するレイヤから、優先順位の低いレイヤの合成に向かって行われる。

構文

object.SetSwapInputs(
Val As Long
)

パラメータ

object
結果が AMTimelineTrans オブジェクトになるオブジェクト式。
Val
トランジションの入力がスワップされるかどうかを指定する値。ゼロを指定すると、トランジションは優先順位の低いすべてのレイヤの合成から、そのトランジションが存在するレイヤに向かって行われる。ゼロ以外を指定すると、トランジションは逆の方向で行われる。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

注意

このメソッドは、ビジュアル エフェクトの方向は変更しない。たとえば、左から右へのワイプは、左から右へ行われる。


IAMTimelineEffectable オブジェクト

Microsoft® DirectShow 編集サービス (DES) のタイムライン オブジェクトにエフェクトを追加するためのメソッド、およびオブジェクトのエフェクトを操作するメソッドを提供する。ソース、トラック、合成など、適用するエフェクトを持つことのできるタイムライン オブジェクトに適用される。

メソッド

EffectGetCount | このオブジェクトに適用されるエフェクトの数を取得する。
EffectInsBefore | 指定された優先順位のオブジェクトにエフェクトを挿入する。
EffectSwapPriorities | 2 つのエフェクトの優先順位レベルを入れ替える。
GetEffect | 指定された優先順位レベルのエフェクトを取得する。

EffectGetCount メソッド (IAMTimelineEffectable オブジェクト)

IAMTimelineEffectable オブジェクト

このオブジェクトに適用されるエフェクトの数を取得する。

構文

object.EffectGetCount(
pCount As Long
)

パラメータ

object
結果が IAMTimelineEffectable オブジェクトになるオブジェクト式。
pCount
エフェクトの数を受け取る変数。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

IAMTimelineEffectable::EffectInsBefore メソッド (IAMTimelineEffectable オブジェクト)

IAMTimelineEffectable インターフェイス

指定された優先順位のオブジェクトにエフェクトを挿入する。

構文

object.EffectInsBefore(
pFX As AMTimelineObj,
Priority As Long
)

パラメータ

object
結果が IAMTimelineEffectable オブジェクトになるオブジェクト式。
pFX
エフェクトを指定する AMTimelineObj オブジェクト。
Priority
エフェクトを挿入する優先順位レベル。エフェクトを優先順位リストの最後に挿入する場合は、値として -1 を使用する。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次の値が設定される場合がある。

E_NOTIMPL pFX で指定されているオブジェクトがエフェクトではない。

注意

エフェクトの開始タイムと終了タイムは、必要に応じて、オブジェクトの時間範囲の境界内に収められる。

指定された優先順位レベルのエフェクトが既に存在する場合、優先順位リストのその位置以下のエフェクトがすべて 1 レベルずつ繰り下げられ、新しいエフェクトの場所が確保される。

IAMTimelineEffectable::EffectSwapPriorities メソッド (IAMTimelineEffectable オブジェクト)

IAMTimelineEffectable インターフェイス

2 つのエフェクトの優先順位レベルを入れ替える。

このメソッドは、指定された 2 つの優先順位レベルを持つそれぞれのエフェクトの優先順位を入れ替える。このメソッドから戻った時点では、最初に指定された優先順位にあったエフェクトの優先順位は、2 番目に指定された優先順位レベルになり、2 番目に指定された優先順位にあったエフェクトの優先順位は、最初に指定された優先順位レベルになっている。

構文

object.EffectSwapPriorities(
PriorityA As Long,
PriorityB As Long
)

パラメータ

object
結果が IAMTimelineEffectable オブジェクトになるオブジェクト式。
PriorityA
エフェクトを入れ替える最初の優先順位レベル。
PriorityB
エフェクトを入れ替える 2 番目の優先順位レベル。

エラー コード

メソッドが失敗すると、エラーが発生し、Err.Number には次の値が設定される場合がある。

E_INVALIDARG 無効な引数。

IAMTimelineEffectable::GetEffect メソッド (IAMTimelineEffectable オブジェクト)

IAMTimelineEffectable インターフェイス

指定された優先順位レベルのエフェクトを取得する。

構文

object.GetEffect(
ppFx As AMTimelineObj,
Which As Long
)

パラメータ

object
結果が IAMTimelineEffectable オブジェクトになるオブジェクト式。
ppFX
エフェクトを受け取る AMTimelineObj オブジェクト。
Which
取得するエフェクトの優先順位レベル。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。


IAMTimelineSplittable オブジェクト

Microsoft® DirectShow 編集サービス (DES) のタイムライン オブジェクトを分割する。ソース、エフェクト、トランジション、およびトラックはこのオブジェクトをサポートする。

メソッド

SplitAt | Visual Basic ではサポートされていない。
SplitAt2 | 指定された時間でオブジェクトを分割する。

SplitAt メソッド (IAMTimelineSplittable オブジェクト)

IAMTimelineSplittable オブジェクト

Visual Basic ではサポートされていない。

構文

object.SplitAt(
Time As <Unsupported variant type>
)

SplitAt2 メソッド (IAMTimelineSplittable オブジェクト)

IAMTimelineSplittable オブジェクト

指定された時間でオブジェクトを分割する。

構文

object.SplitAt2(
Time As Double
)

パラメータ

object
結果が IAMTimelineSplittable オブジェクトになるオブジェクト式。
Time
オブジェクトを分割する時間。 オブジェクトの開始を基準とし、単位は秒。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次のいずれかの値が設定される場合がある。

E_INVALIDARG | 無効な引数。
E_OUTOFMEMORY | メモリ不足。

注意

ソース、エフェクト、またはトランジションを分割する場合、このメソッドは同じタイプの 2 番目のオブジェクトを作成する。元のオブジェクトは、分割を指定された時間まで切り詰められ、切り詰められた部分が新しいオブジェクトとなる。新しいオブジェクトは、同じプロパティをすべて継承する。ソース オブジェクトでは、このメソッドは分割時間にかかるエフェクトも分割する。

トラックでこのメソッドを呼び出すと、指定された分割時間にトラック内にあるすべてのソース、エフェクト、およびトランジションが分割される。この場合、2 番目のトラックは作成されない (トラックは、時間ゼロから始まり、無限に伸張する)。分割時間がトラック内のすべてのものより後になる場合、このメソッドはオブジェクトに対していかなる影響も及ぼさない。


IAMTimelineTransable オブジェクト

Microsoft® DirectShow 編集サービス (DES) のオブジェクトにトランジションを追加する。トラック、合成、グループ など、適用するトランジションを持つことのできるオブジェクトに適用される。トランジションをサポートしているオブジェクトはトランジションをいくつでも持つことができるが、その時間をオーバーラップさせることはできない。

注 : オーディオはトランジションをサポートしていない。

メソッド

GetNextTrans | Visual Basic ではサポートされていない。
GetNextTrans2 | 指定された時間以降に始まる最初のトランジションを取得する。
GetTransAtTime | Visual Basic ではサポートされていない。
GetTransAtTime2 | 指定された境界条件に従って、指定された時間に最も近いトランジションを取得する。
TransAdd | オブジェクトにトランジションを追加する。
TransGetCount | このオブジェクトのトランジションの個数を取得する。

GetNextTrans メソッド (IAMTimelineTransable オブジェクト)

IAMTimelineTransable オブジェクト

Visual Basic ではサポートされていない。

構文

object.GetNextTrans(
ppTrans As AMTimelineObj,
pInOut As <Unsupported variant type>
)

GetNextTrans2 メソッド (IAMTimelineTransable オブジェクト)

IAMTimelineTransable オブジェクト

指定された時間以降に出現する最初のトランジションを取得する。

構文

object.GetNextTrans2(
ppTrans As IAMTimelineObj,
pInOut As Double
)

パラメータ

object
結果が IAMTimelineTransable オブジェクトになるオブジェクト式。
ppTrans
トランジションを受け取る AMTimelineObj オブジェクト。
pInOut
入力では、このパラメータはトランジションの検索を開始する時間を指定する。出力では、トランジションが取得された場合、このパラメータはそのトランジションの終了タイムに設定される。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

注意

トランジションが指定された時間をまたぐ場合、トランジションの開始タイムは pInOut で指定されている時間より小くなることがある。

GetTransAtTime メソッド (IAMTimelineTransable オブジェクト)

IAMTimelineTransable オブジェクト

Visual Basic ではサポートされていない。

構文

object.GetTransAtTime(
ppObj As AMTimelineObj,
Time As <Unsupported variant type>,
SearchDirection As Long
)

GetTransAtTime2 メソッド (IAMTimelineTransable オブジェクト)

IAMTimelineTransable オブジェクト

指定された境界条件に従って、指定された時間に最も近いトランジションを取得する。

構文

object.GetTransAtTime2(
ppObj As AMTimelineObj,
Time As Double,
SearchDirection As Long
)

パラメータ

object
結果が IAMTimelineTransable オブジェクトになるオブジェクト式。
ppObj
トランジションを受け取る IAMTimelineObj オブジェクト。
Time
検索を開始する時間 (秒単位)。
SearchDirection
DEXTERF_TRACK_SEARCH_FLAGS 列挙型のメンバ。 検索の境界条件を指定する。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次の値が設定される。

E_INVALIDARG 無効な引数。

TransAdd メソッド (IAMTimelineTransable オブジェクト)

IAMTimelineTransable オブジェクト

オブジェクトにトランジションを追加する。オブジェクトは複数のトランジションを持つことができるが、その時間がオーバーラップしてはならない。トランジションは、オブジェクトの時間境界内に収まっていなければならない。

構文

object.TransAdd(
pTrans As AMTimelineObj
)

パラメータ

object
結果が IAMTimelineTransable オブジェクトになるオブジェクト式。
pTrans
追加するトランジションを指定する AMTimelineObj オブジェクト。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次のいずれかの値が設定される場合がある。

E_INVALIDARG | トランジションを挿入できない。
E_NOINTERFACE | pTrans がトランジションではない。

注意

挿入するトランジションが既存のトランジションにオーバーラップする場合、このメソッドでは E_INVALIDARG エラーが発生する。

TransGetCount メソッド (IAMTimelineTransable オブジェクト)

IAMTimelineTransable オブジェクト

このオブジェクトのトランジションの個数を取得する。

構文

object.TransGetCount(
pCount As Long
)

パラメータ

object
結果が IAMTimelineTransable オブジェクトになるオブジェクト式。
pCount
トランジションの数を受け取る変数。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。


IAMTimelineVirtualTrack オブジェクト

Microsoft® DirectShow 編集サービス (DES) の仮想トラックを操作するメソッドを提供する。合成およびトラックは、このオブジェクトをサポートする。

メソッド

SetTrackDirty | Visual Basic ではサポートされていない。
TrackGetPriority | オブジェクトの優先順位レベルを取得する。

SetTrackDirty メソッド (IAMTimelineVirtualTrack オブジェクト)

IAMTimelineVirtualTrack オブジェクト

Visual Basic ではサポートされていない。

構文

object.SetTrackDirty()

TrackGetPriority メソッド (IAMTimelineVirtualTrack オブジェクト)

IAMTimelineVirtualTrack オブジェクト

オブジェクトの優先順位レベルを取得する。

構文

object.TrackGetPriority(
pPriority As Long
)

パラメータ

object
結果が IAMTimelineVirtualTrack オブジェクトになるオブジェクト式。
pPriority
優先順位レベルを受け取る変数へのポインタ。オブジェクトがタイムラインの一部でない場合、値は -1 に設定される。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。


IAMCollection オブジェクト

フィルタ グラフ マネージャは IAMCollection オブジェクトを公開する。このオブジェクトを利用すると、オブジェクト コレクションにアクセスできる。これらのコレクションには、IPinInfo、IFilterInfo、または IMediaTypeInfo オブジェクトが含まれる。

プロパティ

Count コレクション内のアイテムの数を返す。

メソッド

Item コレクションの指定されたメンバを取得する。

Count プロパティ (IAMCollection オブジェクト)

IAMCollection オブジェクト

コレクション内のアイテムの数を返す。

構文

objCollection.Count

指定項目

objCollection
評価結果が IAMCollection になるオブジェクト式。

Item メソッド (IAMCollection オブジェクト)

IAMCollection オブジェクト

指定されたコレクション メンバを取得し、渡されたオブジェクトにそれを格納する。

構文

 objCollection.Item lItem, objNew

指定項目

objCollection
評価結果が IAMCollection になるオブジェクト式。
lItem
取得するアイテムのインデックス。
objNew
コレクションの種類に応じて、評価結果が IFilterInfo、IPinInfo、または IMediaTypeInfo オブジェクトになるオブジェクト式。この引数には、取得されたアイテムが格納される。

注意

インデックス値は、0 から (Count – 1) の範囲内になる。


IBasicAudio オブジェクト

IBasicAudio オブジェクトは、フィルタ グラフのオーディオ コンポーネントをサポートする。このオブジェクトを利用して、ボリューム機能とバランス機能にアクセスできる。

Volume プロパティは、線形的な段階の集合を表す –10,000 から 0 の間の値である。識別可能な 10,000 段階をサポートしないデバイスもある。

Balance プロパティは、–10,000 から 10,000 の間の値である。値 –10,000 は、右スピーカが無効になっていて、左スピーカだけにオーディオ信号が入力されていることを示す。値 0 は、両方のスピーカに同じボリュームのオーディオ信号が入力されていることを示す。値 10,000 は、左スピーカが無効になっていて、右スピーカだけにオーディオ信号が入力されていることを示す。

プロパティ

Balance | オーディオ信号のバランスを設定する、または返す。
Volume | オーディオ信号のボリューム (大きさ) を設定する、または返す。

Balance プロパティ (IBasicAudio オブジェクト)

IBasicAudio オブジェクト

オーディオ チャンネルのバランスを設定する、または返す。

構文

objAudio.Balance [= lValue ]

指定項目

objAudio
評価結果が IBasicAudio オブジェクトになるオブジェクト式。
lValue
Balance プロパティの新しい値。

注意

Balance プロパティは、–10,000 から 10,000 の間の値である。値 –10,000 は、右スピーカが無効になっていて、左スピーカだけにオーディオ信号が入力されていることを示す。値 0 は、両方のスピーカに同じボリュームのオーディオ信号が入力されていることを示す。値 10,000 は、左スピーカが無効になっていて、右スピーカだけにオーディオ信号が入力されていることを示す。

識別可能な 10,000 段階をサポートしないデバイスもある点に注意すること。

Balance プロパティをこの範囲外の値に設定しようとすると、IBasicAudio オブジェクトは実行時エラー 5 を生成する。

Volume プロパティ (IBasicAudio オブジェクト)

IBasicAudio オブジェクト

オーディオ チャンネルのボリュームを設定する、または返す。

構文

objAudio.Volume [= lValue]

指定項目

objAudio
評価結果が IBasicAudio オブジェクトになるオブジェクト式。
lValue
Volume プロパティの新しい値。

注意

–10,000 から 0 の間の値を入力できる。

フル ボリュームは 0 であり、–10,000 は無音である。目盛りは線形である。この範囲外の値を指定すると、実行時エラー 5 が返される。

識別可能な 10,000 段階をサポートしないデバイスもある点に注意すること。


IBasicVideo オブジェクト

フィルタ グラフ マネージャは、汎用ビデオ ウィンドウのビデオ プロパティをサポートする IBasicVideo オブジェクトを公開する。一般的に、これは、ディスプレイ上のウィンドウ内でビデオを描画するビデオ レンダラである。

IBasicVideo オブジェクトのメソッドを使用するには、ビデオ レンダラが接続されている必要がある。ビデオ レンダラが接続されていない場合、すべてのメソッドは実行時エラー 521 を返す。ビデオ レンダラで設定されているプロパティは、通常、接続と切断を繰り返しても変わらない。すべてのアプリケーションは、ビデオの表示を開始する前に、レンダラのプロパティがリセットされていることを確認する必要がある。

アプリケーションは、ビデオを使用するときに、使用するビデオの一部を選択することができる。選択される部分は、IBasicVideo オブジェクトが制御する転送元矩形である。IBasicVideo を使用して、転送元矩形を設定したり、取得したりすることができる。すべての IBasicVideo 矩形は、上、左、幅、高さのプロパティを持っている。転送元矩形が設定されていない場合、転送元矩形のプロパティは、本来のビデオのフル サイズを返す。

プロパティ

AvgTimePerFrame | 連続するフレーム間の平均時間を 100 ナノ秒単位で取得する。
BitErrorRate | ビデオ ストリームのおおよそのビット エラー レートを取得する。
BitRate | ビデオ ストリームのおおよそのビット レートを取得する。
DestinationLeft | ビデオの転送先矩形の x 軸の座標を設定または取得する。
DestinationHeight | ビデオの転送先矩形の高さを設定または取得する。
DestinationTop | ビデオの転送先矩形の y 軸の座標を設定または取得する。
DestinationWidth | ビデオの転送先矩形の幅を設定または取得する。
SourceHeight | ビデオの転送元矩形の高さを設定または取得する。
SourceLeft | ビデオの転送元矩形の x 軸の座標を設定または取得する。
SourceTop | ビデオの転送元矩形の y 軸の座標を設定または取得する。
SourceWidth | ビデオの転送元矩形の幅を設定または取得する。
VideoHeight | 現在のビデオの高さを取得する。
VideoWidth | 現在のビデオの幅を取得する。

メソッド

GetCurrentImage | 現在レンダラで待機中の画像のコピーを返す。
GetDestinationPosition | ウィンドウの転送先矩形を取得する。
GetSourcePosition | ビデオの転送元矩形を取得する。
GetVideoPaletteEntries | ビデオが必要とするカラー パレット エントリを取得する。
GetVideoSize | 本来のビデオの大きさを取得する。
IsUsingDefaultSource | デフォルトの転送元が使われているかどうかを示す。
SetDefaultDestinationPosition | ウィンドウのデフォルトの転送先位置を設定する。
SetDefaultSourcePosition | レンダラに対して、デフォルトの転送元矩形を使用するように通知する。
SetDestinationPosition | ウィンドウの転送先矩形を設定する。
SetSourcePosition | ビデオの転送元矩形を設定する。

AvgTimePerFrame プロパティ (IBasicVideo オブジェクト)

IBasicVideo オブジェクト

連続するフレーム間の平均時間を 100 ナノ秒単位で取得する。

構文

objVideo.AvgTimePerFrame

指定項目

objVideo
評価結果が IBasicVideo オブジェクトになるオブジェクト式。

BitErrorRate プロパティ (IBasicVideo オブジェクト)

IBasicVideo オブジェクト

ビデオ ストリームのビット エラー レート (おおよそ何ビットごとに 1 回エラーが発生するかを示す値) を取得する。

構文

objVideo.BitErrorRate

指定項目

objVideo
評価結果が IBasicVideo オブジェクトになるオブジェクト式。

BitRate プロパティ (IBasicVideo オブジェクト)

IBasicVideo オブジェクト

ビデオ ストリームのおおよそのビット レートを 1 秒あたりのビット数単位で取得する。

構文

objVideo.BitRate

指定項目

objVideo
評価結果が IBasicVideo オブジェクトになるオブジェクト式。

DestinationHeight プロパティ (IBasicVideo オブジェクト)

IBasicVideo オブジェクト

転送先矩形の高さを取得または設定する。

構文

objVideo.DestinationHeight [= lValue]

指定項目

objVideo
評価結果が IBasicVideo オブジェクトになるオブジェクト式。
lValue
転送先矩形の高さの新しい値。

注意

この座標を設定しても、転送先矩形の y 軸の原点は影響を受けない。

DestinationLeft プロパティ (IBasicVideo オブジェクト)

IBasicVideo オブジェクト

転送先の x 軸の原点の座標を取得または設定する。

構文

objVideo.DestinationLeft [= lValue]

指定項目

objVideo
評価結果が IBasicVideo オブジェクトになるオブジェクト式。
lValue
転送先の x 軸の原点の新しい値。

注意

この座標を設定しても、転送先矩形の幅は影響を受けない。

DestinationTop プロパティ (IBasicVideo オブジェクト)

IBasicVideo オブジェクト

転送先の y 軸の原点の座標を取得または設定する。

構文

objVideo.DestinationTop [= lValue]

指定項目

objVideo
評価結果が IBasicVideo オブジェクトになるオブジェクト式。
lValue
y 軸の原点の新しい値。

注意

この座標を設定しても、転送先矩形の高さは影響を受けない。

DestinationWidth プロパティ (IBasicVideo オブジェクト)

IBasicVideo オブジェクト

転送先矩形の幅を取得または設定する。

構文

objVideo.DestinationWidth [= lValue]

指定項目

objVideo
評価結果が IBasicVideo オブジェクトになるオブジェクト式。
lValue
新しい幅の値。

注意

この座標を設定しても、転送先矩形の x 軸の原点は影響を受けない。

GetCurrentImage メソッド (IBasicVideo オブジェクト)

IBasicVideo オブジェクト

現在、レンダラで待機中の画像を取得する。

構文

objVideo.GetCurrentImage BufferSize, DIBImage

指定項目

objVideo
評価結果が IBasicVideo オブジェクトになるオブジェクト式。
BufferSize
呼び出し元が渡すバッファのサイズを指定する Long 型の値。GetCurrentImage は、終了前に、この値をバッファ内の実際のバイト数に設定する。
DIBImage
画像全体が DIB (デバイスに依存しないビットマップ) フォーマットで格納されるバッファが含まれている Long 型の値。バッファは参照によって渡す必要がある。

注意

このメソッドを呼び出す前にビデオ レンダラをポーズさせること。ビデオ レンダラがほかの状態にあるときにこのメソッドを呼び出すと、実行時エラー 549 が返される。ソース フィルタで利用可能なデータの種類によっては、ビデオ レンダラがこの要求に応じないこともある。

DIBImage を Nothing に設定し、このメソッドを呼び出すことにより、アプリケーションはこのメソッドを利用して、ポーズしているビデオ レンダラに格納されている現在の画像のコピーを取得できる。

GetDestinationPosition メソッド (IBasicVideo オブジェクト)

IBasicVideo オブジェクト

転送先矩形のウィンドウ座標上の位置を取得する。

構文

objVideo.GetDestinationPosition Left, Top, Width, Height

指定項目

objVideo
評価結果が IBasicVideo オブジェクトになるオブジェクト式。
Left
転送先ウィンドウの x 軸の原点が格納されている Long 型の整数値。
Top
転送先ウィンドウの y 軸の原点が格納されている Long 型の整数値。
Width
転送先ウィンドウの幅が格納されている Long 型の整数値。
Height
転送先ウィンドウの高さが格納されている Long 型の整数値。

注意

このメソッドには、DestinationLeft プロパティ、DestinationTop プロパティ、DestinationWidth プロパティ、および DestinationHeight プロパティを個別に取得するのと同じ効果がある。

GetSourcePosition メソッド (IBasicVideo オブジェクト)

IBasicVideo オブジェクト

利用可能なビデオにクリップされる転送元の位置を取得する。

構文

objVideo.GetSourcePosition Left, Top, Width, Height

指定項目

objVideo
評価結果が IBasicVideo オブジェクトになるオブジェクト式。
Left
転送元ウィンドウの x 軸の原点が格納される Long 型の整数値。
Top
転送元ウィンドウの y 軸の原点が格納される Long 型の整数値。
Width
転送元ウィンドウの幅が格納される Long 型の整数値。
Height
転送元ウィンドウの高さが格納される Long 型の整数値。

注意

このメソッドには、SourceLeft プロパティ、SourceTopプロパティ、SourceWidthプロパティ、および SourceHeight プロパティを個別に取得するのと同じ効果がある。

GetVideoPaletteEntries メソッド (IBasicVideo オブジェクト)

IBasicVideo オブジェクト

ビデオのパレット カラーを取得する。

構文

objVideo.GetVideoPaletteEntries StartIndex, Entries, Retrieved, Palette

指定項目

objVideo
評価結果が IBasicVideo オブジェクトになるオブジェクト式。
StartIndex
パレットの開始インデックスを指定する Long 型の整数値。
Entries
必要なパレット エントリの数を指定する Long 型の整数値。
Retrieved
Palette によって実際に返されるエントリの数が格納される Long 型の整数値。
Palette
Microsoft® Win32® PALETTEENTRY 構造体の配列を指すポインタが格納される Long 型の整数値。

GetVideoSize メソッド (IBasicVideo オブジェクト)

IBasicVideo オブジェクト

本来のビデオの大きさを取得する。

構文

objVideo.GetVideoSize Width, Height

指定項目

objVideo
評価結果が IBasicVideo オブジェクトになるオブジェクト式。
Width
ビデオ ウィンドウの幅が格納される Long 型の整数値。
Height
ビデオ ウィンドウの高さが格納される Long 型の整数値。

注意

設定されている可能性のある転送元矩形はすべて無視して、本来のビデオの幅と高さを取得する。ActiveX コントロールまたはその他のアプリケーションは、この情報を使って、複合ドキュメント内のスペースを確保することができる。

IsUsingDefaultSource メソッド (IBasicVideo オブジェクト)

IBasicVideo オブジェクト

このオブジェクトがデフォルトの転送元を使用しているかどうかの情報を取得する。

構文

objVideo.IsUsingDefaultSource

指定項目

objVideo
評価結果が IBasicVideo オブジェクトになるオブジェクト式。

戻り値

TRUE は IBasicVideo オブジェクトがデフォルトの転送元を使っていることを示し、FALSE は使っていないことを示す。

SetDefaultDestinationPosition メソッド (IBasicVideo オブジェクト)

IBasicVideo オブジェクト

レンダラが再生にウィンドウ全体を使用するように、ビデオ ウィンドウのデフォルトの転送先位置を設定する。

構文

objVideo.SetDefaultDestinationPosition

指定項目

objVideo
評価結果が IBasicVideo オブジェクトになるオブジェクト式。

SetDefaultSourcePosition メソッド (IBasicVideo オブジェクト)

IBasicVideo オブジェクト

レンダラに対して、デフォルトの転送元矩形を使用するように通知する。

構文

objVideo.SetDefaultSourcePosition

指定項目

objVideo
評価結果が IBasicVideo オブジェクトになるオブジェクト式。

SetDestinationPosition メソッド (IBasicVideo オブジェクト)

IBasicVideo オブジェクト

ウィンドウ座標上で転送先矩形を設定する。

構文

objVideo.SetDestinationPosition Left, Top, Width, Height

指定項目

objVideo
評価結果が IBasicVideo オブジェクトになるオブジェクト式。
Left
転送先ウィンドウの x 軸の原点をピクセル単位で指定する Long 型の整数値。
Top
転送先ウィンドウの y 軸の原点をピクセル単位で指定する Long 型の整数値。
Width
転送先ウィンドウの幅をピクセル単位で指定する Long 型の整数値。
Height
転送先ウィンドウの高さをピクセル単位で指定する Long 型の整数値。

注意

このメソッドには、DestinationLeft プロパティ、DestinationTop プロパティ、DestinationWidth プロパティ、および DestinationHeight プロパティを個別に設定するのと同じ効果がある。

SetSourcePosition メソッド (IBasicVideo オブジェクト)

IBasicVideo オブジェクト

利用可能なビデオにクリップされる転送元矩形を設定する。

構文

objVideo.SetSourcePosition Left, Top, Width, Height

指定項目

objVideo
評価結果が IBasicVideo オブジェクトになるオブジェクト式。
Left
転送元ウィンドウの x 軸の原点を指定する Long 型の値。
Top
転送元ウィンドウの y 軸の原点を指定する Long 型の値。
Width
転送元ウィンドウの幅を指定する Long 型の値。
Height
転送元ウィンドウの高さを指定する Long 型の値。

注意

このメソッドには、SourceLeft プロパティ、SourceTopプロパティ、SourceWidthプロパティ、および SourceHeight プロパティを個別に設定するのと同じ効果がある。

SourceHeight プロパティ (IBasicVideo オブジェクト)

IBasicVideo オブジェクト

転送元矩形の高さを取得または設定する。

構文

objVideo.SourceHeight [= lValue]

指定項目

objVideo
評価結果が IBasicVideo オブジェクトになるオブジェクト式。
lValue
現在の矩形の高さをピクセル単位で指定する Long 型の値。

注意

転送元矩形の高さを設定しても、転送元の幅などの値は影響を受けない。

SourceLeft プロパティ (IBasicVideo オブジェクト)

IBasicVideo オブジェクト

転送元矩形の x 座標を取得または設定する。

構文

objVideo.SourceLeft [= lValue]

指定項目

objVideo
評価結果が IBasicVideo オブジェクトになるオブジェクト式。
lValue
転送元矩形の x 軸の原点の新しい値。

注意

このプロパティを変更しても、転送元の幅およびその他の値は影響を受けない。

SourceTop プロパティ (IBasicVideo オブジェクト)

IBasicVideo オブジェクト

転送元矩形の y 軸の原点の座標を取得または設定する。

構文

objVideo.SourceTop [= lValue]

指定項目

objVideo
評価結果が IBasicVideo オブジェクトになるオブジェクト式。
lValue
ディスプレイの上端から現在のウィンドウの上端までの距離をピクセル単位で指定する Long 型の値。

注意

このメソッドを設定しても、転送元矩形の高さは影響を受けない。

SourceWidth プロパティ (IBasicVideo オブジェクト)

IBasicVideo オブジェクト

転送元矩形の幅を取得または設定する。

構文

objVideo.SourceWidth [= lValue]

指定項目

objVideo
評価結果が IBasicVideo オブジェクトになるオブジェクト式。
lValue
現在の幅をピクセル単位で指定する Long 型の値。

注意

このメソッドに、転送元矩形の x 軸座標を変更する効果はない。

VideoHeight プロパティ (IBasicVideo オブジェクト)

IBasicVideo オブジェクト

本来のビデオの高さを取得する。

構文

objVideo.VideoHeight

指定項目

objVideo
評価結果が IBasicVideo オブジェクトになるオブジェクト式。

注意

このメソッドは、レンダラに供給されるビデオの実際の高さを返す。このメソッドは、設定されている転送元矩形は無視して、本来の垂直方向の長さだけを返す。アプリケーションは、これを使って、埋め込み先コンテナ ドキュメントとの間でサイズ要件をネゴシエートできる。

VideoWidth プロパティ (IBasicVideo オブジェクト)

IBasicVideo オブジェクト

ビデオの本来の幅を取得する。

構文

objVideo.VideoWidth

指定項目

objVideo
評価結果が IBasicVideo オブジェクトになるオブジェクト式。

注意

このメソッドは、レンダラに供給されるビデオの実際の幅を返す。このメソッドは、設定されている転送元矩形は無視して、本来の水平方向の長さだけを返す。アプリケーションは、これを使って、埋め込み先コンテナ ドキュメントとの間でサイズ要件をネゴシエートできる。


IFilterInfo オブジェクト

IFilterInfo は、フィルタに関する情報を管理するオブジェクトで、これを利用して、フィルタ オブジェクトおよび IPinInfo オブジェクトにアクセスできる。

プロパティ

Filename | ソース フィルタに関連付けられたファイル名を取得または設定する。
Filter | 実際のフィルタ オブジェクトを取得する。
IsFileSource | フィルタがファイル ソース フィルタであるかどうかを示す。
Name | フィルタ名を取得する。
Pins | このフィルタの IPinInfo オブジェクトが含まれている IAMCollection オブジェクトを取得する。
VendorInfo | 指定されたフィルタに関してベンダが提供しているオプションの情報が格納された文字列を取得する。

メソッド

FindPin 指定された識別子に基づいてピンを検索し、IPinInfo をサポートするオブジェクトを返す。

Filename プロパティ (IFilterInfo オブジェクト)

IFilterInfo オブジェクト

フィルタが格納されているファイルの名前を取得または設定する。

構文

objFilterInfo.Filename [= string]

指定項目

objFilterInfo
評価結果が IFilterInfo オブジェクトになるオブジェクト式。
string
新しいファイル名を指定する文字列式。

Filter プロパティ (IFilterInfo オブジェクト)

IFilterInfo オブジェクト

フィルタ オブジェクトを取得する。

構文

Set objFilter = objFilterInfo.Filter

指定項目

objFilter
評価結果が IBaseFilter オブジェクトになるオブジェクト式。
objFilterInfo
評価結果が IFilterInfo オブジェクトになるオブジェクト式。

注意

IBaseFilter インターフェイスに対してプログラミング可能なオブジェクト インターフェイスは提供されていない。ただし、Visual Basic® プログラマは、返されたオブジェクトを、IBaseFilter インターフェイス ポインタをパラメータとしてとる関数に対する呼び出しでパラメータとして使用できる。

FindPin メソッド (IFilterInfo オブジェクト)

IFilterInfo オブジェクト

指定された識別子に基づいてピンを検索し、IPinInfo オブジェクトを返す。

構文

objFilterInfo.FindPin string, objPin

指定項目

objFilterInfo
評価結果が IFilterInfo オブジェクトになるオブジェクト式。
string
検索するピンの名前が格納された文字列。
objPin
ピンが見つかった場合に、指定されたピンが格納される IPinInfo オブジェクト。

注意

IPin インターフェイスに対してプログラミング可能なオブジェクト インターフェイスは提供されていない。ただし、Visual Basic プログラマは、返されたオブジェクトを、IPin インターフェイス ポインタをパラメータとしてとる関数に対する呼び出しでパラメータとして使用できる。

IsFileSource プロパティ (IFilterInfo オブジェクト)

IFilterInfo オブジェクト

ファイルにソース ビデオが格納されているかどうかを判別する。

構文

objFilterInfo.IsFileSource

指定項目

objFilterInfo
評価結果が IFilterInfo オブジェクトになるオブジェクト式。

戻り値

TRUE はファイルにソース ビデオが格納されていることを示し、FALSE はファイルにソース ビデオが格納されていないことを示す。

Name プロパティ (IFilterInfo オブジェクト)

IFilterInfo オブジェクト

フィルタ名を取得する。

構文

objFilterInfo.Name

指定項目

objFilterInfo
評価結果が IFilterInfo オブジェクトになるオブジェクト式。

注意

ベンダがフィルタ名を指定する。

Pins プロパティ (IFilterInfo オブジェクト)

IFilterInfo オブジェクト

このフィルタの IPinInfo オブジェクトが含まれている IAMCollection オブジェクトを取得する。

構文

Set objPinCollection = objFilterInfo.Pins

指定項目

objPinCollection
特定のフィルタのピンが格納される IAMCollection オブジェクト。
objFilterInfo
ピンを取得するフィルタを指定する IFilterInfo オブジェクト。

注意

Count プロパティと Item メソッドを使って、コレクション内のそれぞれのピン オブジェクトについて繰り返し処理を行うことができる。

VendorInfo プロパティ (IFilterInfo オブジェクト)

IFilterInfo オブジェクト

指定されたフィルタに関してベンダが提供しているオプションの情報が格納された文字列を取得する。

構文

objFilterInfo.VendorInfo

指定項目

objFilterInfo
評価結果が IFilterInfo オブジェクトになるオブジェクト式。

注意

このプロパティには、ベンダが提供する情報が格納される。通常、その情報は、フィルタに関する説明である。


IMediaControl オブジェクト

フィルタ グラフは IMediaControl オブジェクトを公開し、アプリケーションがグラフ内のフィルタを使ってメディアのストリーミングを制御できるようにする。インターフェイスは、データのストリーミングのトランスポート、ポーズ、および停止を処理するメソッドを備えている。また、インターフェイスは、メディア ファイルを再生するグラフを作成するための簡単なメソッドをアプリケーションに提供する。

プロパティ

FilterCollection | グラフ内の現在のフィルタを表す IFilterInfo オブジェクトのコレクションを取得する。
RegFilterCollection | レジストリ内の利用可能なフィルタを表す IRegFilterInfo オブジェクトのコレクションを取得する。

メソッド

AddSourceFilter | 指定されたファイル名を読み取れるソース フィルタをグラフに追加する。
GetState | フィルタ グラフの状態を取得する。
Pause | フィルタ グラフ内のすべてのフィルタをポーズさせる。
RenderFile | 特定のファイルの再生に必要なすべてのフィルタを追加し、接続する。
Run | フィルタ グラフ全体を実行モードに切り替える。
Stop | フィルタ グラフ内のすべてのフィルタを停止状態に切り替える。

AddSourceFilter メソッド (IMediaControl オブジェクト)

IMediaControl オブジェクト

指定されたファイル名を読み取れるソース フィルタをグラフに追加し、作成された IFilterInfo オブジェクトを返す。

構文

objMediaControl.AddSourceFilter string, objFilterInfo

指定項目

objMediaControl
評価結果が IMediaControl オブジェクトになるオブジェクト式。
string
ソース メディアが格納されているファイルの名前。
objFilterInfo
指定されたソース ファイルに対して作成されたソース フィルタである IFilterInfo オブジェクト。

FilterCollection プロパティ (IMediaControl オブジェクト)

IMediaControl オブジェクト

グラフ内のフィルタを表す IFilterInfo オブジェクトのコレクションを取得する。IAMCollection オブジェクトを返す。

構文

Set objCollection = objMediaControl.FilterCollection

指定項目

objCollection
フィルタ グラフ内に現在あるフィルタのコレクションを表す IAMCollection オブジェクト。
objMediaControl
評価結果が IMediaControl オブジェクトになるオブジェクト式。

GetState メソッド (IMediaControl オブジェクト)

IMediaControl オブジェクト

現在の状態値を示す Long 型の整数を返す。

構文

objMediaControl.GetState msTimeout, State

指定項目

objMediaControl
評価結果が IMediaControl オブジェクトになるオブジェクト式。
msTimeout
ミリ秒単位で表すタイムアウトの時間幅。
State
現在の状態が格納される Long 型の値。この引数は、次のいずれかになる。
State_Paused | メディア ソースがポーズしている。
State_Running | メディア ソースがトランスポートしている。
State_Stopped | メディア ソースが停止している。

戻り値

状態の移行が完了していない場合は実行時エラー 567 を返し、状態の移行が完了していれば 0 を返す。

注意

すべての状態移行は、同期を取って行われるわけではない。たとえば、通常 Pause メソッドがすぐに返された場合でも、レンダラでデータが準備できるまで、グラフはポーズ モードへの移行を完了しない。このメソッドは、状態移行が完了するまでゼロを返さない。

ゼロ以外のタイムアウトを指定すると、このメソッドはグラフが中間状態から移行するまで、グラフに指定されたミリ秒まで待つ。状態移行が完了する前にタイムアウトの期限が切れると、戻りコードは 567 となり、返される状態はグラフの移行先の状態 (State_Stopped、State_Paused、または State_Running) となる。

RegFilterCollection プロパティ (IMediaControl オブジェクト)

IMediaControl オブジェクト

レジストリ内の利用可能なフィルタを表す IRegFilterInfo オブジェクトのコレクションを取得する。

構文

Set objCollection = objMediaControl.RegFilterCollection

指定項目

objCollection
IAMCollection object that contains IRegFilterInfo objects.
objMediaControl
評価結果が IMediaControl オブジェクトになるオブジェクト式。

戻り値

IAMCollection オブジェクトを返す。

Pause メソッド (IMediaControl オブジェクト)

IMediaControl オブジェクト

フィルタ グラフ内のすべてのフィルタをポーズさせる。

構文

objMediaControl.Pause

指定項目

objMediaControl
評価結果が IMediaControl オブジェクトになるオブジェクト式。

注意

ポーズ状態では、フィルタはデータを処理するが、レンダリングは行わない。データはフィルタ グラフにプッシュ ダウンされ、バッファリングで許可される限り、変換フィルタによって処理される。 ビデオなど、静的にレンダリング可能なメディア タイプに、ポーズ モードでレンダリングされる静的なポスター フレームがある場合を除き、データはレンダリングされない。そのため、フィルタ グラフをポーズ状態にすると、実行状態になったときにすぐにレンダリングされるキューに入れられる。

RenderFile メソッド (IMediaControl オブジェクト)

IMediaControl オブジェクト

指定されたファイルを再生するために必要なフィルタを追加、接続する。

構文

objMediaControl.RenderFile string

指定項目

objMediaControl
評価結果が IMediaControl オブジェクトになるオブジェクト式。
string
レンダリングするファイルの名前。

注意

このメソッドを使うと、アプリケーションはレンダリングするメディア ファイルの名前をグラフ マネージャに渡すことができる。フィルタ グラフ マネージャは、このファイルを再生するために必要なフィルタのグラフを構築する。

Run メソッド (IMediaControl オブジェクト)

IMediaControl オブジェクト

フィルタ グラフ全体を実行状態に切り替える。

構文

objMediaControl.Run

指定項目

objMediaControl
評価結果が IMediaControl オブジェクトになるオブジェクト式。

注意

フィルタ グラフが停止状態にある場合、このメソッドは最初にグラフをポーズしてから実行する。

エラー値が返された場合、グラフ内の一部のフィルタは、正しく実行状態になっている可能性がある。マルチストリーム グラフでは、ストリーム全体が正しく再生されている可能性がある。アプリケーションは、実行を停止するかどうかを判定しなければならない。

Stop メソッド (IMediaControl オブジェクト)

IMediaControl オブジェクト

フィルタ グラフ内のすべてのフィルタを停止状態に切り替える。

構文

objMediaControl.Stop

指定項目

objMediaControl
評価結果が IMediaControl オブジェクトになるオブジェクト式。

注意

このモードでは、フィルタはリソースを解放し、データは処理されない。フィルタが実行状態の場合、このメソッドはフィルタをポーズしてから停止する。これによって、ビデオ レンダラは、停止中にポスター フレームを表示するために、現在のフレームをコピーできる。


IMediaEvent オブジェクト

このオブジェクトは、フィルタ グラフおよびフィルタ グラフ内のフィルタからアプリケーションへのイベント通知をサポートする。

1 つのイベント コードと 2 つのパラメータで通知情報を表す。これを利用して、非同期動作の完了、非同期動作の最中に発生したエラー、または、ユーザーによるホット スポットのクリックなどのユーザー操作イベントを通知できる。

フィルタ グラフ内のフィルタおよびフィルタ グラフ自体がイベント通知を生成する。通知できるイベントには、再生の完了または非同期再生のエラーが含まれる。また、フィルタ グラフは、特定の基準クロック時間にイベントを生成するメソッドを備えている。

イベント通知はキューに入れられる。アプリケーションは IMediaEvent オブジェクトの GetEvent メソッドを呼び出して、次の通知をキューから取り出す。このメソッドは、返すイベントがキューに入るまで動作を停止する。GetEvent メソッドのタイムアウト パラメータを利用して、アプリケーションは、イベントを待機する時間をミリ秒単位で指定することができる。ゼロ (待機しない) および無限大 (常に待機) も指定できる。

さらに、アプリケーションはイベント ハンドルを取得できる。GetEventHandle は、Microsoft® Win32® CreateEvent 関数によって作成された手動リセット イベントのハンドルを返す。このイベントは、収集するイベント通知が存在する限り、通知済状態に置かれる。収集するイベント通知がなくなると、GetEvent メソッドはイベントを消去する。この機能により、アプリケーションは、MsgWaitForMultipleObjects などの API (アプリケーション プログラミング インターフェイス) を利用して、イベントとその他の対象を同時に待つことができる。このイベント ハンドルは、フィルタ グラフが解放されたときに閉じる。したがって、アプリケーションは、その時点以降にイベント ハンドルを使用しないように注意する必要がある。

フィルタ グラフは、フィルタによって生成され、アプリケーションに渡されない一部のイベントを処理する。EC_REPAINT イベント通知がその例である。このイベントのデフォルトの処理は、フィルタ グラフをポーズさせることによって、ビデオ レンダラの静止画像を再描画することである。アプリケーションは、イベント値をパラメータとして CancelDefaultHandling メソッドを呼び出すことにより、特定のイベントのデフォルト処理をオーバーライドすることができる。RestoreDefaultHandling メソッドは、指定されたイベント値のデフォルト処理を元に戻す。これらのメソッドは、デフォルト処理がないイベントには影響を与えない。

トランスポート状態への移行中にフィルタ上でエラーが発生した場合は、Run メソッドがエラー値を返す。この場合、フィルタ グラフ内の一部のフィルタは問題なくトランスポートしている可能性がある。フィルタ グラフは、エラーが発生したときにグラフを停止するかどうかの判断をアプリケーションに任せる。Run メソッドが終了した後、イベント通知は、その他のエラーを報告する。EC_ERRORABORT イベント通知と EC_USERABORT イベント通知は、グラフで (しかもエラーが報告されたフィルタで) 再生が停止した可能性があることを示す。その他のエラーおよびイベントは、グラフがまだトランスポート中であることを示す。ただし、どんな場合でも、アプリケーションが明示的にグラフを停止モードまたはポーズ モードに移行させるまで、グラフはトランスポート モードにとどまる点に注意すること。

フィルタ グラフ内のストリームがストリームの末尾を検出すると、ストリームは、EC_COMPLETE イベント通知を使ってそれを報告する。フィルタ グラフは、"シーク可能なレンダラ" 経由で EC_COMPLETE を報告できるかどうかをフィルタに問い合わせる。

シーク可能なレンダラは、フィルタ上で IMediaPosition オブジェクトをサポートし、入力ピンだけを持つレンダラ、または、その時点でレンダリングが終了したことを報告する入力ピンを持つレンダラである。フィルタ グラフはシーク可能なレンダラを検出する。シーク可能なレンダラは、そのフィルタ上のすべてのシーク可能なストリームがストリームの末尾に達すると EC_COMPLETE を報告する。

フィルタ グラフ マネージャは、各ストリームから EC_COMPLETE イベント通知を受け取るまで、EC_COMPLETE をアプリケーションに渡さない。たとえば、ファイル再生ビデオのバックグラウンドとしてライブ カメラのストリームが再生されている場合、アプリケーションは、ファイルのビデオ ストリームとオーディオ ストリームがストリームの末尾に達すると、ライブ ソースがまだ再生中であっても EC_COMPLETE の通知を受け取る。この場合も、フィルタ グラフは、アプリケーションが明示的に Pause メソッドまたは Stop メソッドを呼び出すまで、トランスポート状態にとどまる。

EC_COMPLETE をパラメータとして CancelDefaultHandling を呼び出すことにより、EC_COMPLETE メッセージの集合を無効にすることができる。この場合、フィルタによって生成されたすべての EC_COMPLETE イベントは直接アプリケーションに渡される。

システム定義のイベント通知の一覧については、GetEvent メソッドを参照すること。

メソッド

CancelDefaultHandling | 指定されたイベントのフィルタ グラフによるデフォルト処理をキャンセルする。
GetEvent | 次の通知イベントを取得する。
GetEventHandle | 通知済になる手動リセット イベントのハンドルを取得する。
RestoreDefaultHandling | このイベントのデフォルト処理を復元する。
WaitForCompletion | フィルタ グラフの動作が完了するまで待機する。

CancelDefaultHandling メソッド (IMediaEvent オブジェクト)

IMediaEvent オブジェクト

指定されたイベントのフィルタ グラフによるデフォルト処理をキャンセルし、イベントがアプリケーションに渡されるようにする。

構文

objMediaEvent.CancelDefaultHandling lEvCode

指定項目

objMediaEvent
評価結果が IMediaEvent オブジェクトになるオブジェクト式。
lEvCode
デフォルト処理をキャンセルするイベント コードを指定する Long 型の値。 次の値が有効である。
  • EC_COMPLETE
  • EC_ERRORABORT
  • EC_PALETTE_CHANGED
  • EC_REPAINT
  • EC_USERABORT

戻り値

このメソッドは、イベントにデフォルト処理がない場合にエラーを生成する。

注意

現在、フィルタ グラフ マネージャは、EC_COMPLETE と EC_REPAINT のみにデフォルト処理を適用する。

GetEvent メソッド (IMediaEvent オブジェクト)

IMediaEvent オブジェクト

次の通知済イベントを取得する。

構文

objMediaEvent.GetEvent lEventCode, lParam1, lParam2, msTimeout

指定項目

objMediaEvent
評価結果が IMediaEvent オブジェクトになるオブジェクト式。
IEventCode
次のイベント通知を返す。以下の値が有効である。
  • EC_COMPLETE
  • EC_ERRORABORT
  • EC_PALETTE_CHANGED
  • EC_REPAINT
  • EC_USERABORT
lParam1
イベントの第 1 パラメータを指定する Long 型の値。
lParam2
イベントの第 2 パラメータを指定する Long 型の値。
msTimeout
イベントがないと見なすまでのミリ秒単位の時間。直ちに終了するには、タイムアウト値を 0 にする。

注意

このメソッドは、キューの先頭から次のイベント通知を削除し、そのイベント通知を返す。イベントがない場合、このメソッドは msTimeout ミリ秒が経過するまで待機する。

GetEventHandle メソッド (IMediaEvent オブジェクト)

IMediaEvent オブジェクト

渡すイベント通知がある限り通知済になる、手動リセット イベントのハンドルを返す。

構文

objMediaEvent.GetEventHandle hEvent

指定項目

objMediaEvent
評価結果が IMediaEvent オブジェクトになるオブジェクト式。
hEvent
イベント ハンドルが格納される Long 型の値。

注意

イベントを Win32 WaitForMultipleObjects 関数または MsgWaitForMultipleObjects 関数に渡し、1 つのスレッド上で、ほかのメッセージやイベントと同時に、イベント通知を待つことができる。

RestoreDefaultHandling メソッド (IMediaEvent オブジェクト)

IMediaEvent オブジェクト

指定されたイベントのフィルタ グラフによる通常のデフォルト処理があれば、それを復元する。

構文

objMediaEvent.RestoreDefaultHandling lEvCode

指定項目

objMediaEvent
評価結果が IMediaEvent オブジェクトになるオブジェクト式。
lEvCode
復元するイベント。次の一覧は、システム定義イベント通知を示している。
  • EC_COMPLETE
  • EC_ERRORABORT
  • EC_PALETTE_CHANGED
  • EC_REPAINT
  • EC_USERABORT

注意

EC_REPAINT などのようにデフォルト処理が指定されているイベントは、通常、アプリケーションに渡されない。

WaitForCompletion メソッド (IMediaEvent オブジェクト)

IMediaEvent オブジェクト

フィルタ グラフの動作が完了するまで待機する。

構文

objMediaEvent.WaitForCompletion msTimeout, EvCode

指定項目

objMediaEvent
評価結果が IMediaEvent オブジェクトになるオブジェクト式。
msTimeout
タイムアウトの時間幅をミリ秒単位で指定する Long 型の値。無期限で動作を停止させるには、–1 を渡す。直ちに終了させるには、ゼロを渡す。
EvCode
EC_COMPLETE などのイベント終了コードの値が格納された Long 型の値。ゼロは、動作が完了しなかったことを示す。

注意

このメソッドは、メソッドが EC_COMPLETE イベント通知、EC_ERRORABORT イベント通知、または EC_USERABORT イベント通知を受け取るか、タイムアウトの期限が切れるか、どちらかが最初に起きるまで GetEvent を繰り返し呼び出すことによって、動作停止状態にとどまる。

タイムアウトの値に達した場合、メソッドは、終了コード値 0 を返し、「アプリケーション定義エラーまたはオブジェクト定義エラー」を示す実行時エラー 287 を生成する。msTimeOut パラメータを –1 (無限大) 以外の値に設定すると、この実行時エラーが発生する可能性がある。On Error Resume Next ステートメントでこのエラーを処理し、EvCode の値をチェックすることができる。0 はタイムアウトが起きたことを示し、1 (EC_COMPLETE) 以上の値は、動作が完了していることを示す。次の例は、タイムアウトを 0 にしてこのメソッドを使用するのを示している。

Dim pME As IMediaEvent
Dim EventCode As Long
Set pME = pMC

    On Error Resume Next

pME.WaitForCompletion 0, EventCode	'WaitForCompletion から直ちに戻る

    Set pME = Nothing

If EventCode = 0 Then Exit Sub

無期限のタイムアウトを使用するには、次の例のように、戻りイベント コード 1 をチェックする。

Dim pME As IMediaEvent
Dim EventCode As Long
Set pME = pMC

pME.WaitForCompletion -1, EventCode	'EC_COMPLETE まで待機

If EventCode = 1 Then Exit Sub

メソッドが終了した時点で、フィルタ グラフはまだトランスポート状態になっている。このメソッドでは、アプリケーションが IMediaEvent への別の呼び出しを行っていないものと想定している。グラフがトランスポート状態になっていない場合、またはトランスポート状態へ移行中でない場合、このメソッドは失敗する。


IMediaPosition オブジェクト

フィルタ グラフは、グラフ内のいずれかのフィルタがシーク可能であれば (ストリーム内の任意の位置をシークできれば)、IMediaPosition オブジェクトを公開する。フィルタがフィルタのデータをシークできる場合、または、シーク可能なストリームを表す出力ピンに接続される場合、フィルタは IMediaPosition を公開する。

フィルタ グラフと通信するアプリケーションは、このインターフェイスのメソッドを呼び出して、ストリームの時間幅、開始タイムと終了タイム、プリロール タイム、速度、現在位置などのプロパティを設定または取得できる。フィルタ グラフは、シーク可能なフィルタ上でこれらのプロパティを使って、グラフ内のストリームの再生を制御する。複数のストリームがある場合、フィルタ グラフは、それらすべてが同じ位置を開始位置として並行して再生されるように設定し、最も長いストリームの時間幅を時間幅として報告する。このインターフェイスで使われるパラメータは、小数点値の秒を表す double 型の値である。フィルタは、内部的には、時間を 100 ナノ秒の精度で格納する。

プロパティ

CurrentPosition | メディア ストリーム全体の長さに対する現在の位置を取得または設定する。
Duration | メディア ストリームの総時間幅を取得する。
PrerollTime | 非ランダム アクセス デバイスが回転を開始する必要がある、開始位置より前の位置から開始位置までの時間を取得または設定する。
Rate | メディア ストリームの標準再生速度に対する相対的な再生速度を取得または設定する。
StopTime | 再生を停止する必要があるメディア ストリーム内の位置を取得または設定する。

メソッド

CanSeekBackward | 現在のストリームを逆方向にシークできるかどうかを示す値を取得する。
CanSeekForward | 現在のストリームを順方向にシークできるかどうかを示す値を取得する。

CurrentPosition プロパティ (IMediaPosition オブジェクト)

IMediaPosition オブジェクト

メディア ストリーム全体の長さに対する現在の位置を取得または設定する。

構文

objMediaPosition.CurrentPosition [=dblValue]

指定項目

objMediaPosition
評価結果が IMediaPosition オブジェクトになるオブジェクト式。
dblValue
新しい現在位置を指定する Double 型の値。

注意

CurrentPosition プロパティは、現在までに再生が達した位置を表す。このプロパティは、ゼロと時間幅の間の値 (速度と開始タイムによって調整された値) になる。グラフがポーズしている場合、このプロパティは、グラフが動作を再開する位置を示す。

このプロパティを使用して、開始タイムを設定することもできる。その場合の現在位置は、Run メソッドが呼び出されたときに再生を開始する、ゼロと時間幅の間の位置を示す。

フィルタ グラフが停止またはポーズしている場合、このプロパティは、再生を再開する位置を返す。フィルタ グラフがトランスポートしている場合、フィルタ グラフ マネージャは、基準クロックに従って位置を返す。それぞれのフィルタがこれを実装する場合、フィルタは、ポーズまたはトランスポートしているときに、現在処理しているサンプルのストリーム タイム (開始位置からのオフセット時間) を返す必要がある。

停止またはポーズした後、run コマンドを実行すると、再生が現在の位置から開始される。アプリケーションが CurrentPosition 呼び出しを変更しない限り、この位置は、再生が停止またはポーズした位置になる。

フィルタ グラフ マネージャが動作している間にこのメソッドが呼び出されると、フィルタ グラフ マネージャはグラフをポーズさせ、メソッドを実行し、新しい run コマンドを実行する。

ポーズ中または停止中に現在位置を設定すると、run コマンドを実行したときに、新しい開始位置から再生が再開される。

現在位置は速度の前に適用されるため、通常の再生速度での位置になる。

Duration プロパティ (IMediaPosition オブジェクト)

IMediaPosition オブジェクト

メディア ストリームの総時間幅を取得する。

構文

objMediaPosition.Duration

指定項目

objMediaPosition
評価結果が IMediaPosition オブジェクトになるオブジェクト式。

注意

時間幅は標準再生速度を前提としているため、速度の影響を受けない。

PrerollTime プロパティ (IMediaPosition オブジェクト)

IMediaPosition オブジェクト

デバイスが回転を開始する必要がある、開始位置より前の位置から開始位置までの時間を取得または設定する。

構文

objMediaPosition.PrerollTime [=dblValue]

指定項目

objMediaPosition
評価結果が IMediaPosition オブジェクトになるオブジェクト式。
dblValue
PrerollTime プロパティを示す Double 型の値。

注意

プリロール時間とは、テープ プレーヤーなどの非ランダム アクセス デバイスが回転を開始する必要がある、開始位置より前の位置から開始位置までの時間のことである。

Rate プロパティ (IMediaPosition オブジェクト)

IMediaPosition オブジェクト

標準再生速度に対する相対的な再生速度を取得または設定する。

構文

objMediaPosition.Rate [= dblValue]

指定項目

objMediaPosition
評価結果が IMediaPosition オブジェクトになるオブジェクト式。
dblValue
速度の新しい値。Double 型。

注意

このプロパティを利用して、アプリケーションは、再生速度を標準のデフォルト再生速度より速くしたり遅くしたりすることができる。速度 1.0 は標準再生速度を示し、速度 0.5 は半分の速度を示す。また、–1.0 は、標準の逆再生速度を示す。2.0 を指定すると、再生速度は標準速度の 2 倍になり、リソースが十分にあれば、1 秒あたり 10 フレーム (fps) で作成されたビデオが 20 fps で再生される。標準速度より速い速度でオーディオ ストリームを再生すると、サンプルはドロップされず、ピッチが高くなる。速度 0.5 は、半分の速度を示す。

StopTime プロパティ (IMediaPosition オブジェクト)

IMediaPosition オブジェクト

メディア ストリームが停止する時間を取得または設定する。

構文

objMediaPosition.StopTime [ = dblValue]

指定項目

objMediaPosition
評価結果が IMediaPosition オブジェクトになるオブジェクト式。
dblValue
終了タイムの新しい値。

注意

終了タイムは、再生が停止する、ゼロとメディアの時間幅の間の位置である。

停止位置は速度の前に適用されるため、標準再生速度での位置になる。

CanSeekBackward メソッド (IMediaPosition オブジェクト)

IMediaPosition オブジェクト

現在のストリームを逆方向にシークできるかどうかを示す値を取得する。

構文

objMediaPosition.CanSeekBackward

指定項目

objMediaPosition
評価結果が IMediaPosition オブジェクトになるオブジェクト式。

注意

戻り値は整数型の値である。値が 0 の場合、現在のストリームはシークできない。値が –1 であれば、シークできる。ストリームをシークできない場合でも、CurrentPosition でストリームの現在位置を設定できる。

このメソッドは、WAV ファイルやビデオのみの MPEG ファイルなど、メディア ストリームが 1 つのメディア タイプから構成されている場合にのみ –1 (TRUE) を返すことができる。

CanSeekForward メソッド (IMediaPosition オブジェクト)

IMediaPosition オブジェクト

現在のストリームを順方向にシークできるかどうかを示す値を取得する。

構文

objMediaPosition.CanSeekForward

指定項目

objMediaPosition
評価結果が IMediaPosition オブジェクトになるオブジェクト式。

注意

戻り値は整数型の値である。値が 0 の場合、現在のストリームはシークできない。値が –1 であれば、シークできる。ストリームをシークできない場合でも、CurrentPosition でストリームの現在位置を設定できる。

このメソッドは、WAV ファイルやビデオのみの MPEG ファイルなど、メディア ストリームが 1 つのメディア タイプから構成されている場合にのみ –1 (TRUE) を返すことができる。


IMediaTypeInfo オブジェクト

フィルタ グラフ マネージャは、メジャー GUID (グローバルに一意な識別子) などのメディア タイプ情報へのアクセスに利用できる IMediaTypeInfo を公開する。

プロパティ

Subtype | サブタイプ GUID を文字列として取得する。
Type | メジャー タイプ GUID を文字列として取得する。

Subtype プロパティ (IMediaTypeInfo オブジェクト)

IMediaTypeInfo オブジェクト

サブタイプ GUID を文字列として取得する。

構文

objMediaTypeInfo.Subtype

指定項目

objMediaTypeInfo
評価結果が IMediaTypeInfo オブジェクトになるオブジェクト式。

戻り値

サブタイプ GUID が格納された文字列を返す。

Type プロパティ (IMediaTypeInfo オブジェクト)

IMediaTypeInfo オブジェクト

メジャー タイプ GUID を文字列として取得する。

構文

objMediaTypeInfo.Type

指定項目

objMediaTypeInfo
評価結果が IMediaTypeInfo オブジェクトになるオブジェクト式。

戻り値

メジャー タイプ GUID が格納された文字列を返す。


IPinInfo オブジェクト

フィルタ グラフ マネージャは、メディア タイプ、ピン方向などのピン情報へのアクセスに使用できる IPinInfo オブジェクトを公開する。このオブジェクトを使って、接続、切断、レンダリングなどのピンの制御を行うこともできる。

プロパティ

ConnectedTo | フィルタが接続されているピンの IPinInfo オブジェクトを取得する。
ConnectionMediaType | この接続のメディア タイプを取得する。
Direction | ピン方向を取得する。
FilterInfo | このピンが属するフィルタの IFilterInfo オブジェクトを取得する。
MediaTypes | 優先メディア タイプの IAMCollection オブジェクトを取得する。
Name | このピンの名前を取得する。
Pin | この IPinInfo オブジェクトに関連付けられているピンを取得する。
PinID | ピン識別子を取得する。

メソッド

Connect | 次に続くピンに接続する。
ConnectDirect | 指定されたピンに直接接続する。
ConnectWithType | 指定されたメディア タイプのみを使用して指定されたピンに直接接続する。
Disconnect | このピンと接続相手のピンとの相互接続を切断する。
Render | このピンのダウンストリームのフィルタ グラフを作成する。つまり、このピンからレンダラ フィルタの間でグラフを生成するために必要とされるすべてのフィルタと接続を生成する。

Connect メソッド (IPinInfo オブジェクト)

IPinInfo オブジェクト

必要に応じて変換フィルタを使用して、2 つのピンを接続する。

構文

objPinInfo.Connect objPin

指定項目

objPinInfo
評価結果が IPinInfo オブジェクトになるオブジェクト式。
objPin
接続相手のピンを指定する IPinInfo オブジェクト。

ConnectDirect メソッド (IPinInfo オブジェクト)

IPinInfo オブジェクト

変換フィルタを使用せずに、2 つのピンを直接接続する。

構文

objPinInfo.ConnectDirect objPin

指定項目

objPinInfo
接続相手のピンを指定する IPinInfo オブジェクト。
objPin
接続相手のピンを指定する IPinInfo オブジェクト。

ConnectedTo プロパティ (IPinInfo オブジェクト)

IPinInfo オブジェクト

フィルタが接続されているピンの IPinInfo オブジェクトを取得する。

構文

Set objConnectedPinInfo = objPinInfo.ConnectedTo

指定項目

objConnectedPinInfo
ピンの IPinInfo オブジェクト。
objPinInfo
評価結果が IPinInfo オブジェクトになるオブジェクト式。

ConnectionMediaType プロパティ (IPinInfo オブジェクト)

IPinInfo オブジェクト

この接続の IMediaTypeInfo オブジェクトを取得する。

構文

Set objMediaTypeInfo = objPinInfo.ConnectionMediaType

指定項目

objMediaTypeInfo
新しいメディア タイプが格納される IMediaTypeInfo オブジェクト。
objPinInfo
ソース ピンを指定する IPinInfo オブジェクト。objMediaTypeInfo オブジェクトは、このピンのメディア タイプをコピーする。

注意

IMediaTypeInfo オブジェクトには、このピンがサポートしているメジャー タイプとサブタイプに関する情報が格納されている。

ConnectWithType メソッド (IPinInfo オブジェクト)

IPinInfo オブジェクト

指定されたメディア タイプを使用して指定されたピンに直接接続する。

構文

objPinInfo.ConnectWithType objPin, objMediaType

指定項目

objPinInfo
評価結果が IPinInfo オブジェクトになるオブジェクト式。
objPin
接続相手のピンを指定する IPinInfo オブジェクト。
objMediaType
接続に使用されるメディア タイプを指定する値。objMediaType オブジェクトは、IPinInfo をサポートする必要がある。

注意

Connect メソッドと ConnectDirect メソッドを使用してピンを接続することもできる。

Direction プロパティ (IPinInfo オブジェクト)

IPinInfo オブジェクト

ピン方向を取得する。

構文

objPinInfo.Direction

指定項目

objPinInfo
評価結果が IPinInfo オブジェクトになるオブジェクト式。

注意

値 0 は入力を示し、値 1 は出力を示す。

Disconnect メソッド (IPinInfo オブジェクト)

IPinInfo オブジェクト

このピンと接続相手のピンとの相互の接続を切断する。

構文

objPinInfo.Disconnect

指定項目

objPinInfo
評価結果が IPinInfo オブジェクトになるオブジェクト式。

注意

各ピンは、それぞれが対応するピンとの接続を持っている。このメソッドは、両方のピンの接続を切断する。

FilterInfo プロパティ (IPinInfo オブジェクト)

IPinInfo オブジェクト

現在のピンが含まれているフィルタの IFilterInfo オブジェクトを取得する。

構文

Set objFilterInfo = objPinInfo.FilterInfo

指定項目

objFilterInfo
評価結果が IFilterInfo オブジェクトになるオブジェクト式。
objPinInfo
評価結果が IPinInfo オブジェクトになるオブジェクト式。

注意

詳細については、「IFilterInfo」の参照項目を参照すること。

MediaTypes プロパティ (IPinInfo オブジェクト)

IPinInfo オブジェクト

現在のピンの優先メディア タイプを指定する IAMCollection オブジェクトを取得する。

構文

Set objCollection = objPinInfo.MediaTypes

指定項目

objCollection
返される IAMCollection オブジェクト。
objPinInfo
評価結果が IPinInfo オブジェクトになるオブジェクト式。

Name プロパティ (IPinInfo オブジェクト)

IPinInfo オブジェクト

このピンの名前を取得する。

構文

objPinInfo.Name

指定項目

objPinInfo
評価結果が IPinInfo オブジェクトになるオブジェクト式。

Pin プロパティ (IPinInfo オブジェクト)

IPinInfo オブジェクト

IPin オブジェクトを返す。

構文

Set objPin = objPinInfo.Pin

指定項目

objPin
取得されたピンが格納される IPinInfo オブジェクト。
objPinInfo
評価結果が IPinInfo オブジェクトになるオブジェクト式。

注意

Visual Basic® プログラマが利用できる IPin のプログラミング可能なオブジェクト インターフェイスは提供されていない。このプロパティは、IPin パラメータをとる DLL で使用するため、および、IPinInfo オブジェクトの Connect メソッド、ConnectDirectメソッド、と ConnectWithType メソッドへの呼び出しのパラメータとして使用するために用意されている。

PinID プロパティ (IPinInfo オブジェクト)

IPinInfo オブジェクト

ピン識別子を取得する。

構文

objPinInfo.PinID

指定項目

objPinInfo
評価結果が IPinInfo オブジェクトになるオブジェクト式。

注意

PinID を IFilterInfo オブジェクトの FindPin メソッドにパラメータとして渡すことができる。

Render メソッド (IPinInfo オブジェクト)

IPinInfo オブジェクト

すべての変換フィルタおよびレンダリング フィルタを追加し、必要とされるすべての接続を確立して、このソース フィルタの出力ピンに属するメディア タイプをレンダリングできるフィルタ グラフを作成する。

構文

objPinInfo.Render

指定項目

objPinInfo
評価結果が IPinInfo オブジェクトになるオブジェクト式。

注意

このメソッドは、指定されたピンのダウンストリームで、つまりレンダリング フィルタに向かう方向で必要とされる接続のみを確立する。このメソッドは、すべてのピン用の完全なフィルタ グラフを確立する RenderFile メソッドとは異なる。


IRegFilterInfo オブジェクト

IRegFilterInfo オブジェクトは、このコンピュータに登録されているフィルタに関する情報を提供する。

プロパティ

Name フィルタの名前を取得する。

メソッド

Filter このフィルタのインスタンスを作成し、それをグラフに追加し、新しく追加されたフィルタの IFilterInfo オブジェクトを返す。

Filter メソッド (IRegFilterInfo オブジェクト)

IRegFilterInfo オブジェクト

このフィルタのインスタンスを作成し、それをグラフに追加する。

構文

objRegFilterInfo.Filter objFilterInfo

指定項目

objRegFilterInfo
評価結果が IRegFilterInfo オブジェクトになるオブジェクト式。
objFilterInfo
追加するフィルタを指定する IFilterInfo オブジェクト。

Name プロパティ (IRegFilterInfo オブジェクト)

IRegFilterInfo オブジェクト

フィルタの名前を取得する。

構文

objRegFilterInfo.Name

指定項目

objRegFilterInfo
評価結果が IRegFilterInfo オブジェクトになるオブジェクト式。

戻り値

登録されているフィルタ オブジェクトの名前を返す。

注意

ベンダがフィルタ名を指定する。


IVideoWindow オブジェクト

IVideoWindow オブジェクトは、ビデオ レンダラのビデオ ウィンドウのプロパティをサポートする。このオブジェクトは、Microsoft® Visual Basic® および Microsoft® Visual C++® を通じてアクセスできるデュアル インターフェイスであり、汎用ビデオ ウィンドウを制御する。一般的にこのオブジェクトは、ディスプレイ上のウィンドウ内でビデオを描画するビデオ レンダラである。

IVideoWindow オブジェクトはプロパティとメソッドの両方をサポートする。複数のプロパティを同時に変更する必要がある操作では、関連する多数のプロパティを同時に変更するメソッドを利用できる。たとえば、ウィンドウの位置とサイズを設定するときは、4 個の別々のプロパティを呼び出してもよいし、SetWindowPosition という 1 つのメソッドを呼び出してもよい。

IVideoWindow のプロパティとメソッドを使用するには、ビデオ レンダラを接続する必要がある。

プロパティ

AutoShow | 最初に状態が変化したときにウィンドウを自動的に表示するかどうかを指定するフラグを取得または設定する。
BackgroundPalette | レンダラがパレットをバックグラウンドで適用するかどうかを示すフラグを取得または設定する。
BorderColor | ビデオ ウィンドウの境界線の色を取得または設定する。
Caption | 再生ウィンドウのテキスト キャプションを取得または設定する。
FullScreenMode | フルスクリーン モードの種類を取得または設定する。
Height | ビデオ ウィンドウの高さを取得または設定する。
Left | ビデオ ウィンドウの x 軸座標を取得または設定する。
MessageDrain | ビデオ ウィンドウがメッセージの受信またはポストに使用するウィンドウ ハンドルを取得または設定する。
NotifyOwnerMessage | 親ウィンドウが受信したメッセージを、フィルタの所有する子ウィンドウに転送する。
Owner | ビデオ再生ウィンドウを所有する親ウィンドウを取得または設定する。
Top | ビデオ ウィンドウの y 軸座標を取得または設定する。
Visible | ウィンドウの表示/非表示の状態を取得または設定する。
Width | ビデオ ウィンドウの幅を取得または設定する。
WindowState | 表示/非表示、最小化など、現在のウィンドウの状態を取得または設定する。
WindowStyle | 再生ウィンドウのスタイルを取得または設定する。
WindowStyleEx | 再生ウィンドウの拡張スタイル ビットを取得または設定する。

メソッド

GetMaxIdealImageSize | ビデオ画像再生 (クライアント) 領域の理想最大画像サイズを取得する。
GetMinIdealImageSize | ビデオ画像再生 (クライアント) 領域の理想最小画像サイズを取得する。
GetRestorePosition | 最大化および最小化を行うときに、元のビデオ ウィンドウ サイズを取得する。
GetWindowPosition | ビデオ ウィンドウの位置を取得する。
HideCursor | カーソルを非表示にする。
IsCursorHidden | カーソルの表示/非表示の状態を取得する。
NotifyOwnerMessage | フィルタ グラフのパレットおよび色の変更メッセージを渡す。
SetWindowForeground | ビデオ ウィンドウをフォアグラウンド ウィンドウに設定し、オプションでビデオ ウィンドウにフォーカスを移す。
SetWindowPosition | ディスプレイ上のビデオ ウィンドウの位置を設定する。

AutoShow プロパティ (IVideoWindow オブジェクト)

IVideoWindow オブジェクト

ウィンドウを自動的に表示するかどうかの情報を取得または設定する。

構文

objVideoWindow.AutoShow [= boolean]

指定項目

objVideoWindow
評価結果が IVideoWindow オブジェクトになるオブジェクト式。
boolean
TRUE は、状態が変わったときにウィンドウが表示されることを示す。

注意

多くの簡単なアプリケーションでは、フィルタ グラフがトランスポート状態に設定されたときにウィンドウを表示する必要がある。このプロパティはデフォルトでオン (–1) に設定されているため、グラフがポーズ状態からトランスポート状態に移行すると、ウィンドウが表示される。ウィンドウは同時にフォアグラウンド ウィンドウに設定される。ウィンドウを閉じない限り、それ以降は、ポーズ状態またはトランスポート状態に移行するたびにウィンドウが表示される。ウィンドウを閉じた場合は、レンダラがいったん停止状態になるまでウィンドウは表示されない。このプロパティをオフ (0) に設定すると、ウィンドウを明示的に表示しない限り、ウィンドウは非表示状態にとどまる。ウィンドウを明示的に表示するには Visible プロパティを設定する。

BackgroundPalette プロパティ (IVideoWindow オブジェクト)

IVideoWindow オブジェクト

必要なパレットがバックグラウンドで適用されるかどうかを決定する。

構文

objVideoWindow.BackgroundPalette [= boolean]

指定項目

objVideoWindow
評価結果が IVideoWindow オブジェクトになるオブジェクト式。
boolean
パレットが適用されるかどうかを示すフラグ。

注意

このプロパティが TRUE (–1) の場合、レンダラは、必要とされるすべてのビデオ パレットをバックグラウンドで適用する。これは、パレットが使用するすべての色が、描画を行う前に、ディスプレイ パレットの最も近い色に変更されることを意味する。これにより、ビデオを再生するときにアプリケーションのパレットが乱れないことが保証される。ただし、この操作はビデオにかかるパフォーマンスの負担が大きいため、絶対に必要でない限り、使用しないこと。このプロパティのデフォルト値は FALSE (0) である。

BorderColor プロパティ (IVideoWindow オブジェクト)

IVideoWindow オブジェクト

ビデオ ウィンドウの境界線の色を取得または設定する。

構文

objVideoWindow.BorderColor [= Color]

指定項目

objVideoWindow
評価結果が IVideoWindow オブジェクトになるオブジェクト式。
Color
新しい境界線の色。

注意

設定されている転送先矩形がウィンドウの表示クライアント領域と異なる場合は、周辺部に境界線が表示される。このプロパティを利用して、アプリケーションは、境界線の色を変更できる。色はデフォルトでは黒に設定されている。システム カラー以外の色を渡すと、渡された色は、色を使用する前に、現在のパレットに従って、最も近い色に変換される。True Color デバイスではその必要はない。このプロパティを設定すると、ウィンドウの境界線は、自動的に新しい色で再描画される。

Caption プロパティ (IVideoWindow オブジェクト)

IVideoWindow オブジェクト

ビデオ ウィンドウのテキストのタイトル文字列を取得または設定する。

構文

objVideoWindow.Caption [= string]

指定項目

objVideoWindow
評価結果が IVideoWindow オブジェクトになるオブジェクト式。
string
ウィンドウのタイトル キャプションの新しい値。

FullScreenMode プロパティ (IVideoWindow オブジェクト)

IVideoWindow オブジェクト

ビデオ ウィンドウでフルスクリーン モードを使用するかどうかを示すフラグを取得または設定する。

構文

objVideoWindow.FullScreenMode [= boolean]

指定項目

objVideoWindow
評価結果が IVideoWindow オブジェクトになるオブジェクト式。
boolean
新しいフラグの値。TRUE はフルスクリーン モードを示し、FALSE はフルスクリーン モードを使用しないことを示す。

GetMaxIdealImageSize メソッド (IVideoWindow オブジェクト)

IVideoWindow オブジェクト

ビデオ画像再生 (クライアント) 領域の理想最大画像サイズを取得する。

構文

objVideoWindow.GetMaxIdealImageSize Width, Height

指定項目

objVideoWindow
評価結果が IVideoWindow オブジェクトになるオブジェクト式。
Width
画像の幅が格納される Long 型の値。
Height
画像の高さが格納される Long 型の値。

GetMinIdealImageSize メソッド (IVideoWindow オブジェクト)

IVideoWindow オブジェクト

ビデオ画像再生 (クライアント) 領域の理想最小画像サイズを取得する。

構文

objVideoWindow.GetMinIdealImageSize Width, Height

指定項目

objVideoWindow
評価結果が IVideoWindow オブジェクトになるオブジェクト式。
Width
画像の幅が格納される Long 型の値。
Height
画像の高さが格納される Long 型の値。

GetRestorePosition メソッド (IVideoWindow オブジェクト)

IVideoWindow オブジェクト

ウィンドウを最小化した後、元に戻す場合に、ウィンドウのサイズと位置を取得する。

構文

objVideoWindow.GetRestorePosition Left, Top, Width, Height

指定項目

objVideoWindow
評価結果が IVideoWindow オブジェクトになるオブジェクト式。
Left
ビデオ ウィンドウの x 軸の原点を返す。
Top
ビデオ ウィンドウの y 軸の原点を返す。
Width
ビデオ ウィンドウの幅を返す。
Height
ビデオ ウィンドウの高さを返す。

GetWindowPosition メソッド (IVideoWindow オブジェクト)

IVideoWindow オブジェクト

現在のウィンドウ矩形 (クライアント領域ではない) をデバイスの座標で取得する。

構文

objVideoWindow.GetWindowPosition Left, Top, Width, Height

指定項目

objVideoWindow
評価結果が IVideoWindow オブジェクトになるオブジェクト式。
Left
ウィンドウの x 軸の原点を返す。
Top
ウィンドウの y 軸の原点を返す。
Width
ウィンドウの幅を返す。
Height
ウィンドウの高さを返す。

注意

このメソッドには、Left プロパティ、Top プロパティ、Width プロパティ、および Height プロパティを個別に設定するのと同じ効果がある。

Height プロパティ (IVideoWindow オブジェクト)

IVideoWindow オブジェクト

ビデオ ウィンドウの高さを取得または設定する。

構文

objVideoWindow.Height [= lValue]

指定項目

objVideoWindow
評価結果が IVideoWindow オブジェクトになるオブジェクト式。
lValue
ビデオ ウィンドウの縦の長さの新しい値。

注意

Height プロパティを変更しても、Width プロパティ (ビデオ ウィンドウの y 座標) は影響を受けない。

HideCursor メソッド (IVideoWindow オブジェクト)

IVideoWindow オブジェクト

カーソルがビデオ再生ウィンドウの上を通過したときに、カーソルを表示するかどうかを指定する。

構文

objVideoWindow.HideCursor bValue

指定項目

objVideoWindow
評価結果が IVideoWindow オブジェクトになるオブジェクト式。
bValue
カーソルを表示するかどうかを示すブール型の値。TRUE はカーソルを表示せず、FALSE はカーソルを表示する。

注意

通常、フルスクリーン再生を使用する場合は、ユーザーの気が散らないようにカーソルを表示しない。

次のコードは、このメソッドの使い方を示している。

    Dim o_objVideoWindow As IVideoWindow	'IVideoWindow オブジェクトを初期化
    Dim g_objMediaControl As IMediaControl	'IMediaControl オブジェクトを初期化

    Set g_objVideoWindow = g_objMediaControl	'再生ウィンドウを
                    'フィルタ グラフに割り当てる
    g_objVideoWindow.HideCursor (True)	'カーソルを非表示にする

IsCursorHidden メソッド (IVideoWindow オブジェクト)

IVideoWindow オブジェクト

カーソルの表示/非表示の状態を取得する。

構文

objVideoWindow.IsCursorHidden bValue

指定項目

objVideoWindow
評価結果が IVideoWindow オブジェクトになるオブジェクト式。
bValue
カーソルの表示/非表示の状態が格納されるブール型の値。カーソルが非表示状態であれば TRUE、表示状態であれば FALSE になる。

注意

通常、フルスクリーン再生を使用する場合は、ユーザーの気が散らないようにカーソルを表示しない。

次のコードは、このメソッドの使い方を示している。

    Dim o_objVideoWindow As IVideoWindow	'IVideoWindow オブジェクトを初期化
    Dim g_objMediaControl As IMediaControl	'IMediaControl オブジェクトを初期化
    Dim bTest As Boolean			'ストレージ変数を初期化

    Set g_objVideoWindow = g_objMediaControl	'再生ウィンドウを
                    'フィルタ グラフに割り当てる
    g_objVideoWindow.IsCursorHidden (bTest)	'カーソルが非表示かどうかをチェックする

Left プロパティ (IVideoWindow オブジェクト)

IVideoWindow オブジェクト

ビデオ ウィンドウの x 座標を取得または設定する。

構文

objVideoWindow.Left [= lValue]

指定項目

objVideoWindow
評価結果が IVideoWindow オブジェクトになるオブジェクト式。
lValue
x 軸座標の新しい値。

注意

このプロパティを呼び出しても、ビデオ ウィンドウの幅は影響を受けない。

MessageDrain プロパティ (IVideoWindow オブジェクト)

IVideoWindow オブジェクト

ビデオ ウィンドウ宛てにポストされたメッセージを受け取るウィンドウのウィンドウ ハンドルを取得または設定する。

構文

objVideoWindow.MessageDrain [= handle]

指定項目

objVideoWindow
評価結果が IVideoWindow オブジェクトになるオブジェクト式。
handle
ウィンドウ ハンドルの新しい値。

NotifyOwnerMessage メソッド (IVideoWindow オブジェクト)

IVideoWindow オブジェクト

親ウィンドウが受信したメッセージを、フィルタが所有する子ウィンドウに転送する。

構文

objVideoWindow.NotifyOwnerMessage hwnd, uMsg, wParam, lParam

指定項目

objVideoWindow
評価結果が IVideoWindow オブジェクトになるオブジェクト式。
hwnd
ウィンドウ ハンドル。
uMsg
送られるメッセージ。
wParam
メッセージの wParam。
lParam
メッセージの lParam。

Owner プロパティ (IVideoWindow オブジェクト)

IVideoWindow オブジェクト

ビデオ ウィンドウを所有する親を取得または設定する。

構文

objVideoWindow.Owner [= handle]

指定項目

objVideoWindow
評価結果が IVideoWindow オブジェクトになるオブジェクト式。
handle
ウィンドウ ハンドルの新しい値。

注意

このプロパティを利用して、アプリケーションはビデオ ウィンドウの所有者を設定できる。この機能は、複合ドキュメントでビデオを再生するときによく使用される。

SetWindowForeground メソッド (IVideoWindow オブジェクト)

IVideoWindow オブジェクト

ビデオ ウィンドウをフォアグラウンド ウィンドウに設定し、オプションでビデオ ウィンドウにフォーカスを移す。

構文

objVideoWindow.SetWindowForeground Focus

指定項目

objVideoWindow
評価結果が IVideoWindow オブジェクトになるオブジェクト式。
Focus
ビデオ ウィンドウにフォーカスを移すかどうかを指定する Long 型の値。値 –1 は、ウィンドウにフォーカスを移す。0 はウィンドウにフォーカスを移さない。

SetWindowPosition メソッド (IVideoWindow オブジェクト)

IVideoWindow オブジェクト

ビデオ ウィンドウの位置 (クライアント矩形の位置ではない) をデバイスの座標で設定する。

構文

objVideoWindow.SetWindowPosition Left, Top, Width, Height

指定項目

objVideoWindow
評価結果が IVideoWindow オブジェクトになるオブジェクト式。
Left
ウィンドウの x 軸の原点を指定する。
Top
ウィンドウの y 軸の原点を指定する。
Width
ウィンドウの幅を指定する。
Height
ウィンドウの高さを指定する。

注意

ビデオを表示する位置をウィンドウの座標で指定する。たとえば、転送先を (100,50,200,400) に設定すると、ビデオ再生画像は、クライアント領域の左端から 100 ピクセル、上端から 50 ピクセルの位置に原点を持ち、全体のサイズが 200 x 400 ピクセルになる。ビデオがこれより小さい場合、またはビデオより小さい転送元矩形が指定されている場合は、ビデオ画像が表示領域に合わせて拡大される。同様に、ビデオが転送先矩形より大きい場合、ビデオは矩形の表示領域に合わせて縮小される。アプリケーション側で転送元と転送先の矩形を同じサイズにしないと、パフォーマンスに大きな負担がかかる。

転送先矩形が設定されていない標準的な環境では、ユーザーがウィンドウをどれだけ拡大しても、ビデオは表示クライアント ウィンドウ領域全体を満たす。また、転送先矩形のプロパティは、ビデオ ウィンドウ クライアント領域のサイズを正しく返す。

このメソッドには、Left プロパティ、Top プロパティ、Width プロパティ、および Height プロパティを個別に設定するのと同じ効果がある。

Top プロパティ (IVideoWindow オブジェクト)

IVideoWindow オブジェクト

ビデオ ウィンドウの y 軸座標を取得または設定する。

構文

objVideoWindow.Top [= lValue]

指定項目

objVideoWindow
評価結果が IVideoWindow オブジェクトになるオブジェクト式。
lValue
y 軸の原点の新しい値。

注意

このプロパティを呼び出しても、ビデオ ウィンドウの高さは影響を受けない。

Visible プロパティ (IVideoWindow オブジェクト)

IVideoWindow オブジェクト

ビデオ ウィンドウの表示/非表示の状態を取得または設定する。

構文

objVideoWindow.Visible [= boolean]

指定項目

objVideoWindow
評価結果が IVideoWindow オブジェクトになるオブジェクト式。
boolean
TRUE に設定されているとウィンドウが表示される。FALSE の場合、ウィンドウは表示されない。

Width プロパティ (IVideoWindow オブジェクト)

IVideoWindow オブジェクト

ビデオ ウィンドウの幅を取得または設定する。

構文

objVideoWindow.Width [= lValue]

指定項目

objVideoWindow
評価結果が IVideoWindow オブジェクトになるオブジェクト式。
lValue
幅の新しい値。

注意

Width プロパティは、ビデオ ウィンドウの Height プロパティ (x 座標) とは無関係である。

WindowState プロパティ (IVideoWindow オブジェクト)

IVideoWindow オブジェクト

ビデオ ウィンドウの状態を取得または設定する。

構文

objVideoWindow.WindowState [= lValue]

指定項目

objVideoWindow
評価結果が IVideoWindow オブジェクトになるオブジェクト式。
lValue
WindowState プロパティの新しい値。

WindowStyle プロパティ (IVideoWindow オブジェクト)

IVideoWindow オブジェクト

ビデオ ウィンドウのスタイル パラメータを取得または設定する。

構文

objVideoWindow.WindowStyle [= lValue]

指定項目

objVideoWindow
評価結果が IVideoWindow オブジェクトになるオブジェクト式。
lValue
WindowStyle プロパティの新しい値。

注意

すべてのウィンドウ スタイルの一覧については、Microsoft® Platform Software Development Kit (SDK) の「CreateWindow 関数」を参照すること。

WindowStyleEx プロパティ (IVideoWindow オブジェクト)

IVideoWindow オブジェクト

ビデオ ウィンドウのスタイル パラメータを変更する。

構文

objVideoWindow.WindowStyleEx [= lValue]

指定項目

objVideoWindow
評価結果が IVideoWindow オブジェクトになるオブジェクト式。
lValue
フラグの新しい値。有効な値は、Microsoft Win32 GetWindowLong 関数の GWL_STYLE 値によって設定できるフラグに限られる。


MediaDet オブジェクト

メディア ファイルに関して、ストリームの数とタイプ、時間幅、各ストリームのフレーム レートなどの情報を取得する。このインターフェイスには、ビデオ ストリームからポスター フレームを取得するメソッドも含まれている。

ファイルに関する情報を取得するには、以下の手順を実行する。

  1. MediaDet オブジェクトの新しいインスタンスを作成する。
  2. Filename プロパティにソース ファイルの名前を設定する。
  3. OutputStreams プロパティから、ソース内の出力ストリームの数を取得する。
  4. CurrentStream プロパティに、特定のストリームを設定する。
  5. 次のプロパティのいずれかを取得する : StreamType、StreamMediaType、StreamLength、または FrameRate。

ポスター フレームを取得するには、WriteBitmapBits を呼び出す。このメソッドを呼び出すと、MediaDet オブジェクトはビットマップ グラブ モードという新しいモードに設定される。前述の情報取得メソッドは、このモードでは動作しない。そのため、情報の取得はポスター フレームの取得の前に行う必要がある。 または、ストリームごとに MediaDet オブジェクトの新しいインスタンスを作成する。

次のコードは、このオブジェクトの使用方法の例である。

Dim Det As New MediaDet
Const VideoGUID As String = "{73646976-0000-0010-8000-00AA00389B71}"
bFoundVidStream = False

Det.FileName = "C:\Media\Example.avi"

' ビデオ ストリームを検索する
For i = 0 To Det.OutputStreams - 1
Det.CurrentStream = i
StreamType = Det.StreamTypeB
If StrComp(StreamType, VideoGUID, vbTextCompare) = 0 Then
bFoundVidStream = True
Exit For
End If
Next

If bFoundVidStream Then
' 時間幅を使ってラベルを更新する
VideoInfo.Caption = Det.FileName + ":" + Str(Det.StreamLength) + " seconds"

' ポスター フレームをロードする
TempFile = "C:\Temp.bmp"
Preview.ScaleMode = vbPixels  ' Scale twips to pixels.
Det.WriteBitmapBits 0, Preview.ScaleWidth, Preview.ScaleHeight, TempFile
Preview.Picture = LoadPicture(TempFile)
End If

プロパティ

CurrentStream | MediaDet オブジェクトが現在使用しているストリームの数。
Filename | MediaDet オブジェクトが現在使用しているソース ファイルの名前。
Filter | Visual Basic ではサポートされていない。
OutputStreams | メディア ソースに含まれる出力ストリームの数。
FrameRate | 現在のストリームのフレーム レート (1 秒あたりのフレーム数)。
StreamLength | 現在のストリームの時間幅、単位は秒。
StreamMediaType | Visual Basic ではサポートされていない。
StreamType | Visual Basic ではサポートされていない。
StreamTypeB | 現在のストリームのメディア タイプの GUID を表す文字列。

メソッド

EnterBitmapGrabMode | MediaDet オブジェクトをビットマップ グラブ モードに切り替え、フィルタ グラフの指定の時間をシークする。
GetBitmapBits | Visual Basic ではサポートされていない。
GetSampleGrabber | Visual Basic ではサポートされていない。
WriteBitmapBits | 指定されたメディア タイムのポスター フレームを取得し、それをファイルに書き込む。

CurrentStream プロパティ (MediaDet オブジェクト)

MediaDet オブジェクト

MediaDet オブジェクトが現在使用しているストリームの数。読み取り/書き込み。

構文

object.CurrentStream As Long

パラメータ

object
結果が MediaDet オブジェクトになるオブジェクト式。

Filename プロパティ (MediaDet オブジェクト)

MediaDet オブジェクト

MediaDet オブジェクトが現在使用しているソース ファイルの名前。読み取り/書き込み。

構文

object.Filename As String

パラメータ

object
結果が MediaDet オブジェクトになるオブジェクト式。

Filter プロパティ (MediaDet オブジェクト)

MediaDet オブジェクト

Visual Basic ではサポートされていない。

構文

object.Filter As Unknown

FrameRate プロパティ (MediaDet オブジェクト)

MediaDet オブジェクト

現在のストリームのフレーム レート (1 秒あたりのフレーム数)。読み取り専用。

構文

object.FrameRate As Double

パラメータ

object
結果が MediaDet オブジェクトになるオブジェクト式。

注意

このストリームは、ビデオ ストリームでなければならない。このプロパティは、ASF ファイルに対しては無効である。MediaDet オブジェクトがビットマップ グラブ モードの場合、このプロパティは無効である。詳細については、「EnterBitmapGrabMode」を参照すること。

このプロパティを取得するには、先に Filename プロパティと CurrentStream プロパティを設定しておかなければならない。

OutputStreams プロパティ (MediaDet オブジェクト)

MediaDet オブジェクト

メディア ソースに含まれる出力ストリームの数。読み取り専用。

構文

object.OutputStreams As Long

パラメータ

object
結果が MediaDet オブジェクトになるオブジェクト式。

注意

このプロパティを取得するには、先に Filename プロパティを設定しておかなければならない

MediaDet オブジェクトがビットマップ グラブ モードの場合、このプロパティは無効である。詳細については、「EnterBitmapGrabMode」を参照すること。

StreamLength プロパティ (MediaDet オブジェクト)

MediaDet オブジェクト

現在のストリームの時間幅、単位は秒。

構文

object.StreamLength As Double

パラメータ

object
結果が MediaDet オブジェクトになるオブジェクト式。

注意

このプロパティを取得するには、先に Filename プロパティと CurrentStream プロパティを設定しておかなければならない。

MediaDet オブジェクトがビットマップ グラブ モードの場合、このプロパティは無効である。詳細については、「EnterBitmapGrabMode」を参照すること。

StreamMediaType プロパティ (MediaDet オブジェクト)

MediaDet オブジェクト

Visual Basic ではサポートされていない。

構文

object.get_StreamMediaType As _AMMediaType

StreamType プロパティ (MediaDet オブジェクト)

MediaDet オブジェクト

Visual Basic ではサポートされていない。

構文

object.StreamType As GUID

StreamTypeB プロパティ (MediaDet オブジェクト)

MediaDet オブジェクト

現在のストリームのメディア タイプの GUID を表す文字列。読み取り専用。

構文

object.StreamTypeB As String

パラメータ

object
結果が MediaDet オブジェクトになるオブジェクト式。

注意

文字列の書式は次のように設定されている: {73647561-0000-0010-8000-00AA00389B71}。

このプロパティを取得するには、先に Filename プロパティと CurrentStream プロパティを設定しておかなければならない。MediaDet オブジェクトがビットマップ グラブ モードの場合、このプロパティは無効である。詳細については、「EnterBitmapGrabMode」を参照すること。

EnterBitmapGrabMode メソッド (MediaDet オブジェクト)

MediaDet オブジェクト

MediaDet オブジェクトをビットマップ グラブ モードに切り替え、フィルタ グラフの指定の時間をシークする。

構文

object.EnterBitmapGrabMode(
SeekTime As Double
)

パラメータ

object
結果が MediaDet オブジェクトになるオブジェクト式。
SeekTime
グラフをシークする時間 (秒単位)。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次のいずれかの値が設定される場合がある。

E_INVALIDARG | 無効な引数。
VFW_E_INVALIDMEDIATYPE | ファイルはビデオ ストリームを持っていない。
VFW_E_TIME_EXPIRED | シークできなかった。

注意

このメソッドを呼び出すには、先に Filename プロパティと CurrentStream プロパティを設定しておかなければならない。

このメソッドは、サンプル グラバ フィルタをフィルタ グラフに挿入する。MediaDet オブジェクトがビットマップ グラブ モードになったなら、MediaDet の各種の情報取得メソッドは機能しない。

GetBitmapBits メソッドおよび WriteBitmapBits メソッドも、オブジェクトをビットマップ グラブ モードに設定する。

GetBitmapBits メソッド (Media オブジェクト)

MediaDet オブジェクト

Visual Basic ではサポートされていない。

構文

object.GetBitmapBits(
StreamTime As Double,
pBufferSize As Long,
pBuffer As Byte,
Width As Long,
Height As Long
)

GetSampleGrabber メソッド (MediaDet オブジェクト)

MediaDet オブジェクト

Visual Basic ではサポートされていない。

構文

object.GetSampleGrabber(
ppVal As SampleGrabber
)

WriteBitmapBits メソッド (MediaDet オブジェクト)

MediaDet オブジェクト

指定されたメディア タイムのポスター フレームを取得し、それをファイルに書き込む。

構文

object.WriteBitmapBits(
StreamTime As Double,
Width As Long,
Height As Long,
Filename As String
)

パラメータ

object
結果が MediaDet オブジェクトになるオブジェクト式。
StreamTime
ポスター フレームを取得する時間 (秒単位)。
Width
ポスター フレーム イメージの幅 (ピクセル単位)。
Height
ポスター フレーム イメージの高さ (ピクセル単位)。
Filename
ポスター フレームを保存するファイルのパス。ファイルが既に存在する場合、このメソッドはそのファイルにオーバーライドする。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次のいずれかの値が設定される場合がある。

E_NOINTERFACE | サンプル グラバ フィルタをグラフに追加できなかった。
E_FAIL | 失敗。
E_OUTOFMEMORY | メモリ不足。
E_UNEXPECTED | 予期しないエラー。
STG_E_ACCESSDENIED | ファイルをオーバーライドできない。
VFW_E_INVALIDMEDIATYPE | 無効なメディア タイプ。

注意

このメソッドを呼び出すには、先に Filename プロパティと CurrentStream プロパティを設定しておかなければならない。

このメソッドは、MediaDet オブジェクトをビットマップ グラブ モードに設定する。このメソッドが呼び出された後は、オブジェクトの新しいインスタンスを作成しなければ、IMediaDet の各種のストリーム情報取得メソッドは機能しない。


MediaLocator オブジェクト

Microsoft® DirectShow 編集サービス (DES) でファイル名の妥当性を検証するためのメソッドを提供する。MediaLocator オブジェクトを使うと、特定のファイル名とパスが既存のファイルに対応することを確認できる。このオブジェクトは、他の場所にあるファイルを検索する手段、および [開く] ダイアログ ボックスを表示してユーザーがファイルを探せるようにする手段も提供する。

タイムラインおよびレンダリング エンジンも、次のメソッドを通してファイル名の妥当性検査をサポートする。

  • AMTimeline.ValidateSourceNames: タイムライン内のファイル名を検証および更新する。
  • RenderEngine.SetSourceNameValidation: レンダリング エンジンがレンダリング時にファイル名を検証する方法を指定する。

普通、DES アプリケーションは、MediaLocator オブジェクトのインスタンスを直接作成するのではなく、次のメソッドを呼び出す。

メソッド

FindMediaFile | ファイルを検索し、成功した場合は、そのファイルへのパスを取得する。
AddFoundLocation | ディレクトリ キャッシュにディレクトリを追加する。

AddFoundLocation メソッド (MediaLocator オブジェクト)

MediaLocator オブジェクト

ディレクトリ キャッシュにディレクトリを追加する。

構文

object.AddFoundLocation(
DirectoryName As String
)

パラメータ

object
結果が MediaLocator オブジェクトになるオブジェクト式。
DirectoryName
キャッシュに追加するディレクトリ パス。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

注意

MediaLocator オブジェクトは、過去の検索でファイルが見つかったディレクトリ パスのキャッシュを維持する。ファイルが見つかった場合は、そのディレクトリをキャッシュに追加する。

FindMediaFile (MediaLocator オブジェクト)

MediaLocator オブジェクト

ファイルを検索し、成功した場合は、そのファイルへのパスを取得する。

構文

object.FindMediaFile(
Input As String,
FilterString As String,
pOutput As String,
Flags As Long
)

パラメータ

object
結果が MediaLocator オブジェクトになるオブジェクト式。
Input
ファイル名。 そのファイルが最後に存在していたことがわかっているパスも含む。タイムライン内のソース オブジェクトの場合は、現在のメディア名を使用する。
FilterString
Microsoft® Win32® の OPENFILENAME 構造体の lpstrFilter メンバで必要な書式に設定されたフィルタ文字列のペアを含む文字列。メディア ロケータは、[開く] ダイアログ ボックスを表示する場合に、このフィルタを使用する。
pOutput
ファイルへの実際のパスが Input 内の値と異なる場合、およびメソッドがファイルを見つけられた場合、ファイルの実際のパスを受け取る変数。
Flags
次のフラグの 0 個以上をビットごとに組み合わせたもの。
  • SFN_VALIDATEF_NOFIND
  • SFN_VALIDATEF_POPUP
  • SFN_VALIDATEF_TELLME
  • SFN_VALIDATEF_USELOCAL

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次のいずれかの値が設定される場合がある。

E_FAIL | 失敗。
E_INVALIDARG | 引数が無効。
E_POINTER | NULL ポインタ引数。

注意

SFN_VALIDATEF_POPUP フラグが指定されていて、メディア ロケータがファイルを見つけられない場合、このメソッドは、ユーザーがファイルを見つけられるように [開く] ダイアログ ボックスを表示する。ユーザーがダイアログ ボックスをキャンセルすると、メソッドでは E_FAIL エラーが発生する。アプリケーションでは、On Error ステートメントを使ってこのエラーを獲得する必要がある。

If Err.Number = &H80004005 Then
' Did not locate the file.
End If

SFN_VALIDATEF_POPUP フラグが指定されていなくて、 メディア ロケータがファイルを見つけられない場合は、メソッドはダイアログ ボックスを表示しないで E_FAIL エラーを生成する。

FilterString パラメータによって指定される、[開く] ダイアログ ボックスのフィルタ文字列には、内部的な NULL 文字列が含まれる (例 : Video\0*.avi\0\0)。Chr(0) を使って Null 文字を指定できる。

sNullStr = Chr(0)
sFilterStr = "Video" + sNullStr + "*.avi" + sNullStr + sNullStr


RenderEngine オブジェクト

タイムラインからフィルタ グラフを構築することにより、Microsoft® DirectShow 編集サービス (DES) プロジェクトをレンダリングする。

DES では、タイムラインをレンダリングする 2 つのオブジェクトが提供されている。

  • RenderEngine は、非圧縮フォーマットの出力を作成する。この出力は、プレビューに使用でき、また圧縮フィルタを経由して最終出力ファイルの書き込みにも使用できる。
  • SmartRenderEngine オブジェクトは、スマート再圧縮を使用して、圧縮された出力を作成する。スマート再圧縮を使用すると、ソース ファイルのフォーマットが出力フォーマットと異なる場合にのみ、ソース ファイルが再圧縮される。ソースのフォーマットが一致しているときには、出力ファイルに直接書き込まれる。状況によっては、スマート再圧縮を使うことでレンダリング時間を大幅に改善できる。

アプリケーションでフィルタ グラフを作成してレンダリング エンジンに渡すこともできるが、通常の状況では、レンダリング エンジンにフィルタ グラフを作成させる。グラフの作成は、2 段階の処理で行われる。まず、ConnectFrontEnd メソッドを呼び出してフロント エンドを構築する。次に、フロント エンドの出力ピンを目的のレンダリング フィルタに接続する。

  • プレビュー用のビデオ レンダラおよびオーディオ レンダラ、または
  • コンプレッサ、マルチプレクサ、および最終出力を生成するファイル ライタ。

メソッド

Commit | Visual Basic ではサポートされていない。
ConnectFrontEnd | 現在のタイムラインからフィルタ グラフのフロント エンドを構築する。
Decommit | Visual Basic ではサポートされていない。
DoSmartRecompression | Visual Basic ではサポートされていない。
GetCaps | Visual Basic ではサポートされていない。
GetFilterGraph | レンダリング エンジンが構築したフィルタ グラフ (ある場合) を取得する。
GetGroupOutputPin | 指定されたグループの出力ピンを取得する。
GetTimelineObject | レンダリング エンジンが現在使用しているタイムラインを取得する。
GetVendorString | ベンダー文字列を取得する。
RenderOutputPins | フィルタ グラフのプレビュー部分を作成する。
SetDynamicReconnectLevel | レンダリング時の動的再接続のレベルを設定する。
SetFilterGraph | 使用するレンダリング エンジン用のフィルタ グラフを指定する。
SetInterestRange | Visual Basic ではサポートされていない。
SetInterestRange2 | Visual Basic ではサポートされていない。
SetRenderRange | Visual Basic ではサポートされていない。
SetRenderRange2 | タイムライン上の、レンダリングされる時間の範囲を設定する。
SetSourceConnectCallback | Visual Basic ではサポートされていない。
SetSourceNameValidation | レンダリング エンジンがファイル名を検証する方法を指定する。
SetTimelineObject | 使用するレンダリング エンジン用のタイムラインを設定する。
ScrapIt | レンダリング エンジンのフィルタ グラフおよび関連付けられているすべてのオブジェクトを破棄する。
UseInSmartRecompressionGraph | Visual Basic ではサポートされていない。

Commit メソッド (RenderEngine オブジェクト)

RenderEngine オブジェクト

Visual Basic ではサポートされていない。

構文

object.Commit()

ConnectFrontEnd (RenderEngine オブジェクト)

RenderEngine オブジェクト

現在のタイムラインからフィルタ グラフのフロント エンドを構築する。

構文

object.ConnectFrontEnd()

パラメータ

object
結果が RenderEngine オブジェクトになるオブジェクト式。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次のいずれかの値が設定される場合がある。

E_INVALIDARG | このレンダリング エンジンにはタイムラインが設定されていない。
E_MUST_INIT_RENDERER | レンダリング エンジンが初期化に失敗した。
E_RENDER_ENGINE_IS_BROKEN | プロジェクトが正しくレンダリングされなかったため、処理が失敗した。
E_UNEXPECTED | 予期しないエラー。
VFW_E_INVALIDMEDIATYPE | 無効なメディア タイプ。

注意

このメソッドは、フィルタ グラフのレンダリング部分を構築しない。アプリケーションでは、フロント エンドの出力ピンを目的のレンダリング フィルタに接続しなければならない。

  • プレビューを行うには、RenderOutputPins メソッドを呼び出す。
  • ファイルに出力するには、GetGroupOutputPin を呼び出してグループごとの出力ピンを取得してから、そのピンをマルチプレクサ フィルタに接続する。

RenderEngine オブジェクトを使っている場合は、フロント エンド上の出力ピンは非圧縮データを生成する。SmartRenderEngine オブジェクトを使っている場合は、出力ピンは圧縮データを出力する。

フィルタ グラフを構築した後でタイムラインを変更した場合は、ConnectFrontEnd をもう一度呼び出してフロント エンドを再構築しなければならない。このメソッドは、可能であればグラフのレンダリング部分を維持する。ただし、グループを追加または削除した場合、またはグループの順序を変更した場合は、ConnectFrontEnd はレンダリング部分を削除するため、アプリケーションでレンダリング部分を再構築しなければならない。

Decommit (RenderEngine オブジェクト)

RenderEngine オブジェクト

Visual Basic ではサポートされていない。

構文

object.Decommit()

DoSmartRecompression (RenderEngine オブジェクト)

RenderEngine オブジェクト

Visual Basic ではサポートされていない。

構文

object.DoSmartRecompression()

GetCaps (RenderEngine オブジェクト)

RenderEngine オブジェクト

Visual Basic ではサポートされていない。

構文

object.GetCaps(
Index As Long,
pReturn As Long
)

GetFilterGraph (RenderEngine オブジェクト)

RenderEngine オブジェクト

レンダリング エンジンが構築したフィルタ グラフ (ある場合) を取得する。

構文

object.GetFilterGraph(
ppFG As IGraphBuilder
)

パラメータ

object
結果が RenderEngine オブジェクトになるオブジェクト式。
ppFG
フィルタ グラフを受け取る FilgraphManager オブジェクト。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次の値が設定される場合がある。

E_MUST_INIT_RENDERER レンダリング エンジンが初期化に失敗した。

GetGroupOutputPin (RenderEngine オブジェクト)

RenderEngine オブジェクト

指定されたグループの出力ピンを取得する。

構文

object.GetGroupOutputPin(
Group As Long,
ppRenderPin As IPin
)

パラメータ

object
結果が RenderEngine オブジェクトになるオブジェクト式。
Group
グループを指定する、ゼロから始まるインデックス。
ppRenderPin
出力ピンを受け取る IPin オブジェクト。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次のいずれかの値が設定される場合がある。

E_INVALIDARG | 無効な引数。
E_MUST_INIT_RENDERER | レンダリング エンジンが初期化に失敗した。
E_RENDER_ENGINE_IS_BROKEN | プロジェクトが正しくレンダリングされなかったため、処理が失敗した。
E_UNEXPECTED | 予期しないエラー。

注意

このメソッドを呼び出す前に、ConnectFrontEnd を呼び出してグラフのフロント エンドを構築する。各グループは単一のメディア ストリームを表し、フロント エンドには対応する出力ピンがある。

このメソッドを使用して、ファイル書き込みグラフのレンダリング部分を作成できる。出力ピンをマルチプレクサ フィルタおよびファイル ライタ フィルタに接続する。詳細については、「プロジェクトのレンダリング」を参照すること。

プレビューの場合は、このメソッドを呼び出す必要はない。単純に、ConnectFrontEnd の後に RenderOutputPins を呼び出せばよい。

GetTimelineObject (RenderEngine オブジェクト)

RenderEngine オブジェクト

レンダリング エンジンが現在使用しているタイムラインを取得する。

構文

object.GetTimelineObject(
ppTimeline As AMTimeline
)

パラメータ

object
結果が RenderEngine オブジェクトになるオブジェクト式。
ppTimeline
タイムラインを受け取る AMTimeline オブジェクト。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次の値が設定される場合がある。

E_MUST_INIT_RENDERER レンダリング エンジンが初期化に失敗した。

GetVendorString (RenderEngine オブジェクト)

RenderEngine オブジェクト

ベンダー文字列を取得する。

構文

object.GetVendorString() As String

パラメータ

object
結果が RenderEngine オブジェクトになるオブジェクト式。

戻り値

ベンダー名を含む文字列を返す。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

RenderOutputPins (RenderEngine オブジェクト)

RenderEngine オブジェクト

フィルタ グラフのプレビュー部分を作成する。

構文

object.RenderOutputPins()

パラメータ

object
結果が RenderEngine オブジェクトになるオブジェクト式。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次のいずれかの値が設定される場合がある。

E_INVALIDARG | 無効な引数。
E_RENDER_ENGINE_IS_BROKEN | プロジェクトが正しくレンダリングされなかったため、処理が失敗した。
E_UNEXPECTED | 予期しないエラー。

注意

このメソッドを呼び出す前に、ConnectFrontEnd を呼び出してグラフのフロント エンドを構築する。プレビュー以外の処理を行う場合は、このメソッドを呼び出してはならない。代わりに、GetGroupOutputPin を呼び出して出力ピンへのポインタを取得する。

ScrapIt (RenderEngine オブジェクト)

RenderEngine オブジェクト

レンダリング エンジンのフィルタ グラフおよび関連付けられているすべてのオブジェクトを破棄する。

構文

object.ScrapIt()

パラメータ

object
結果が RenderEngine オブジェクトになるオブジェクト式。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次の値が設定される場合がある。

E_MUST_INIT_RENDERER レンダリング エンジンが初期化に失敗した。

SetDynamicReconnectLevel (RenderEngine オブジェクト)

RenderEngine オブジェクト

レンダリング時の動的再接続のレベルを設定する。

構文

object.SetDynamicReconnectLevel(
Level As Long
)

パラメータ

object
結果が RenderEngine オブジェクトになるオブジェクト式。
Level
0 個以上の動的再接続フラグのビットごとの組み合わせ。 動的再接続のレベルを指定する。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次の値が設定される場合がある。

E_NOTIMPL 実装されていない。

注意

デフォルトでは、RenderEngine オブジェクトはプロジェクトをレンダリングする前にすべてのソースをロードする。このため、起動時間が長くなることがある。動的再接続を使用すると、ソースは必要なときにのみロードされる。これによって起動時間は短くなるが、スムースな再生が妨げられることがある。一般に、プロジェクトで使用するソース クリップが多いほど、動的再接続を使用するメリットは大きい。

SmartRenderEngine オブジェクトは、このメソッドを実装していない。

SetFilterGraph (RenderEngine オブジェクト)

RenderEngine オブジェクト

使用するレンダリング エンジン用のフィルタ グラフを指定する。

構文

object.SetFilterGraph(
pFG As IGraphBuilder
)

パラメータ

object
結果が RenderEngine オブジェクトになるオブジェクト式。
pFG
フィルタ グラフを指定する FilgraphManager オブジェクト。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次のいずれかの値が設定される場合がある。

E_INVALIDARG | 無効な引数。
E_MUST_INIT_RENDERER | レンダリング エンジンが初期化に失敗した。

注意

ほとんどのアプリケーションではこのメソッドを呼び出す必要はない。より一般的な方法は、ConnectFrontEnd メソッドを呼び出すことにより、レンダリング エンジンにグラフを構築させることである。

レンダリング エンジンに既にフィルタ グラフがある場合、このメソッドは失敗する。

レンダリング エンジンが作成したフィルタ グラフを取得し、それをパラメータとして別のレンダリング エンジンでこのメソッドを呼び出してはならない。それを行うと、予測できない結果になる。

SetInterestRange (RenderEngine オブジェクト)

RenderEngine オブジェクト

Visual Basic ではサポートされていない。

構文

object.SetInterestRange(
Start As <Unsupported variant type>,
Stop As <Unsupported variant type>
)

SetInterestRange2 (RenderEngine オブジェクト)

RenderEngine オブジェクト

Visual Basic ではサポートされていない。

構文

object.SetInterestRange2(
double Start As Double,
double Stop As Double
)

SetRenderRange (RenderEngine オブジェクト)

RenderEngine オブジェクト

Visual Basic ではサポートされていない。

構文

object.SetRenderRange(
Start As <Unsupported variant type>,
Stop As <Unsupported variant type>
)

SetRenderRange2 (RenderEngine オブジェクト)

RenderEngine オブジェクト

タイムライン上の、レンダリングされる時間の範囲を設定する。指定された範囲の外にあるオブジェクトはレンダリングされず、それらに対してリソースは割り当てられない。

構文

object.SetRenderRange2(
Start As Double,
Stop As Double
)

パラメータ

object
結果が RenderEngine オブジェクトになるオブジェクト式。
Start
開始タイム (秒単位)。
Stop
終了タイム (秒単位)。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次の値が設定される場合がある。

E_MUST_INIT_RENDERER レンダリング エンジンが初期化に失敗した。

SetSourceConnectCallback (RenderEngine オブジェクト)

RenderEngine オブジェクト

Visual Basic ではサポートされていない。

構文

object.SetSourceConnectCallback(
pCallback As IGrfCache
)

SetSourceNameValidation (RenderEngine オブジェクト)

RenderEngine オブジェクト

レンダリング エンジンがファイル名を検証する方法を指定する。

構文

object.SetSourceNameValidation(
FilterString As String,
pOverride As MediaLocator,
Flags As Long
)

パラメータ

object
結果が RenderEngine オブジェクトになるオブジェクト式。
FilterString
Microsoft® Win32® の OPENFILENAME 構造体の lpstrFilter メンバで必要な書式に設定されたフィルタ文字列のペアを含む文字列。メディア ロケータは、[開く] ダイアログ ボックスを表示する場合に、このフィルタを使用する。
pOverride
省略可能。デフォルトの代わりに使用する MediaLocator オブジェクト。デフォルトのメディア ロケータを使用する場合は、このパラメータを NULL に設定する。詳細については、「注意」を参照すること。
Flags
MediaLocator オブジェクトの動作を指定するフラグのビットごとの組み合わせ。SFN_VALIDATEF_CHECK フラグは、必ず設定されていなければならない。SFN_VALIDATEF_IGNOREMUTED フラグは、このメソッドでは意味を持たない。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次の値が設定される場合がある。

E_MUST_INIT_RENDERER レンダリング エンジンが初期化に失敗した。

注意

pOverride パラメータを使用すると、MediaLocator オブジェクトの独自のカスタム実装を使用できる。

現在、このメソッドは動的にロードされたソースを検証しない。詳細については、「SetDynamicReconnectLevel」を参照すること。

SetTimelineObject (RenderEngine オブジェクト)

RenderEngine オブジェクト

使用するレンダリング エンジン用のタイムラインを設定する。

構文

object.SetTimelineObject(
pTimeline As AMTimeline
)

パラメータ

object
結果が RenderEngine オブジェクトになるオブジェクト式。
pTimeline
タイムラインを指定する AMTimeline オブジェクト。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次のいずれかの値が設定される場合がある。

E_MUST_INIT_RENDERER | レンダリング エンジンが初期化に失敗した。
E_OUTOFMEMORY | メモリ不足。

UseInSmartRecompressionGraph (RenderEngine オブジェクト)

RenderEngine オブジェクト

Visual Basic ではサポートされていない。

構文

object.UseInSmartRecompressionGraph()


Xml2Dex オブジェクト

Microsoft® DirectShow® 編集サービス (DES) の、拡張可能マークアップ言語 (XML) で記述されたプロジェクト ファイルの保存とロードを行う。

必要事項

Internet Explore 4.0 以降が必要。

メソッド

CopyXML | Visual Basic ではサポートされていない。
CreateGraphFromFile | Visual Basic ではサポートされていない。
Delete | Visual Basic ではサポートされていない。
PasteXML | Visual Basic ではサポートされていない。
PasteXMLFile | Visual Basic ではサポートされていない。
ReadXML | Visual Basic ではサポートされていない。
ReadXMLFile | XML プロジェクト ファイルをロードする。
Reset | Visual Basic ではサポートされていない。
WriteGrfFile | フィルタ グラフを .grf フォーマットでファイルに書き込む。
WriteXML | タイムラインを XML 文字列に変換する。
WriteXMLFile | タイムラインを XML に変換し、XML データをファイルに書き込む。
WriteXMLPart | Visual Basic ではサポートされていない。

CopyXML メソッド (Xml2Dex オブジェクト)

Xml2Dex オブジェクト

Visual Basic ではサポートされていない。

構文

object.CopyXML(
pTimeline As Unknown,
dStart As Double,
dEnd As Double
)

CreateGraphFromFile メソッド (Xml2Dex オブジェクト)

Xml2Dex オブジェクト

Visual Basic ではサポートされていない。

構文

object.CreateGraphFromFile(
ppGraph As Unknown,
pTimeline As Unknown,
FileName As String
)

Delete メソッド (Xml2Dex オブジェクト)

Xml2Dex オブジェクト

Visual Basic ではサポートされていない。

構文

object.Delete(
pTimeline As Unknown,
dStart As Double,
dEnd As Double
)

PasteXML メソッド (Xml2Dex オブジェクト)

Xml2Dex オブジェクト

Visual Basic ではサポートされていない。

構文

object.PasteXML(
pTimeline As Unknown,
dStart As Double
)

PasteXMLFile メソッド (Xml2Dex オブジェクト)

Xml2Dex オブジェクト

Visual Basic ではサポートされていない。

構文

object.PasteXMLFile(
pTimeline As Unknown,
dStart As Double,
FileName As String
)

ReadXML メソッド (Xml2Dex オブジェクト)

Xml2Dex オブジェクト

Visual Basic ではサポートされていない。

構文

object.ReadXML(
pXML As Unknown
)

ReadXMLFile メソッド (Xml2Dex オブジェクト)

Xml2Dex オブジェクト

XML プロジェクト ファイルをロードする。このメソッドは、XML ファイルで表現されているすべてのオブジェクトのインスタンスを作成し、タイムラインに挿入する。また、フレーム レートやデフォルト エフェクトなど、タイムラインに対して指定されている属性を適用する。

構文

object.ReadXMLFile(
pTimeline As Unknown,
XMLName As String
)

パラメータ

object
結果が Xml2Dex オブジェクトになるオブジェクト式。
pTimeline
タイムラインを受け取る AMTimeline オブジェクト。
XMLName
ロードするファイルの名前を指定する文字列。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次の値が設定される場合がある。

VFW_E_INVALID_FILE_FORMAT 無効なファイル フォーマット。

注意

pTimeline パラメータは、Microsoft® Visual Basic® のオブジェクト ブラウザでは Unknown タイプとして表示される。ただし、実際には、このパラメータは AMTimeline オブジェクトを表している。次のコードは、このメソッドの呼び出し方法の例である。

Dim objTimeline as New AMTimeline
Dim objXmlParse as New Xml2Dex
objXmlParse.ReadXMLFile objTimeline, "C:\XTL\Example.xtl"

このメソッドは、XML ファイルで定義されている新しいオブジェクトをタイムラインに挿入する前に、タイムラインから既存のオブジェクトをクリアしない。既存のタイムラインを更新する必要がある場合は、先に IAMTimeline.ClearAllGroups を呼び出す。

Reset メソッド (Xml2Dex オブジェクト)

Xml2Dex オブジェクト

Visual Basic ではサポートされていない。

構文

object.Reset()

WriteGrfFile メソッド (Xml2Dex オブジェクト)

Xml2Dex オブジェクト

フィルタ グラフを .grf フォーマットでファイルに書き込む。

構文

object.WriteGrfFile(
pGraph As Unknown,
FileName As String
)

パラメータ

object
結果が Xml2Dex オブジェクトになるオブジェクト式。
pGraph
フィルタ グラフを指定する FilgraphManager オブジェクト。
FileName
書き込むファイルの名前を指定する文字列。

エラー コード

メソッドでの処理が失敗すると、エラーが発生する。

注意

pGraph パラメータは、Microsoft® Visual Basic® のオブジェクト ブラウザでは Unknown タイプとして表示される。ただし、実際には、このパラメータは FilgraphManager オブジェクトを表している。GraphEdit ファイルは、デバッグでの使用だけを目的としたものである。詳細については、「GraphEdit によるグラフ構築のシミュレーション」を参照すること。

WriteXML メソッド (Xml2Dex オブジェクト)

Xml2Dex オブジェクト

タイムラインを XML 文字列に変換する。

構文

object.WriteXML(
pTimeline As Unknown,
pbstrXML As String
)

パラメータ

object
結果が Xml2Dex オブジェクトになるオブジェクト式。
pTimeline
タイムラインを指定する AMTimeline オブジェクト。
pbstrXML
変換された XML 文字列を受け取る変数。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次の値が設定される場合がある。

E_OUTOFMEMORY メモリ不足。

注意

pTimeline パラメータは、Microsoft® Visual Basic® のオブジェクト ブラウザでは Unknown タイプとして表示される。ただし、実際には、このパラメータは AMTimeline オブジェクトを表している。次のコードは、このメソッドの呼び出し方法の例である。

Dim objTimeline As New AMTimeline
' タイムラインを作成する (省略)

Dim objXmlParser As New Xml2Dex
Dim sXml As String
objXmlParser.WriteXml objTimeline, sXml

WriteXMLFile メソッド (Xml2Dex オブジェクト)

Xml2Dex オブジェクト

タイムラインを XML に変換し、XML データをファイルに書き込む。

構文

object.WriteXMLFile(
pTimeline As Unknown,
FileName As String
)

パラメータ

object
結果が Xml2Dex オブジェクトになるオブジェクト式。
pTimeline
タイムラインを指定する AMTimeline オブジェクト。
FileName
書き込むファイルの名前を指定する文字列。

エラー コード

メソッドでの処理が失敗するとエラーが発生し、Err.Number には次のいずれかの値が設定される場合がある。

E_INVALIDARG | 無効な引数。
E_OUTOFMEMORY | メモリ不足。

注意

このメソッドは、タイムライン内のすべてのコンポーネントを表す XML ファイルを生成する。

pTimeline パラメータは、Microsoft® Visual Basic® のオブジェクト ブラウザでは Unknown タイプとして表示される。ただし、実際には、このパラメータは AMTimeline オブジェクトを表している。次のコードは、このメソッドの呼び出し方法の例である。

Dim objTimeline As New AMTimeline
' タイムラインを作成する (省略)

Dim objXmlParser As New Xml2Dex
objXmlParser.WriteXmlFile objTimeline, "C:\XTL\Example.xtl"

WriteXMLPart メソッド (Xml2Dex オブジェクト)

Xml2Dex オブジェクト

Visual Basic ではサポートされていない。

構文

object.WriteXMLPart(
pTimeline As Unknown,
dStart As Double,
dEnd As Double,
FileName As String
)


関連情報

_CrtSetDbgFlag
_crtDbgFlag フラグの状態を取得または変更し、デバッグ ヒープ マネージャの割り当て動作を制御する (デバッグ バージョンのみ)。詳細については、Microsoft® Visual C++® のドキュメントを参照すること。
BitBlt
BitBlt 関数は、指定された転送元デバイス コンテキストから転送先デバイス コンテキストへ、ピクセルの矩形を表すカラー データのビットブロック転送を行う。詳細については、Microsoft Platform SDK のドキュメントを参照すること。
biHeight
ピクセル単位でビットマップの高さを指定する BITMAPINFOHEADER 構造体のデータ メンバ。biHeight が正の値であれば、ビットマップは、左下隅に原点を持つボトムアップ DIB (デバイスに依存しないビットマップ) である。biHeight が負の値であれば、ビットマップは、左上隅に原点を持つトップダウン DIB である。
biWidth
ピクセル単位でビットマップの幅を指定する BITMAPINFOHEADER 構造体のデータ メンバ。
CAUUID
UUID タイプまたは GUID タイプのカウント配列を定義する構造体。配列の大きさを指定する cElems メンバと、配列を指すポインタが格納されている pElems メンバの 2 つのメンバを持つ。詳細については、Platform SDK を参照すること。
CClassFactory
IClassFactory インターフェイスを実装するクラス。IClassFactory インターフェイスには、オブジェクトのクラス全体を処理するための 2 つのメソッドが含まれているため、このインターフェイスは、CLSID によって識別されるオブジェクトの特定のクラスに対応するクラス オブジェクトに実装される。最初のメソッド CreateInstance は、指定された CLSID の初期化されていないオブジェクトを作成し、2 番目の LockServer は、メモリ内のオブジェクトのサーバーをロックし、新しいオブジェクトをすばやく作成できるようにする。詳細については、Platform SDK の IClassFactory インターフェイスのドキュメントを参照すること。
クラス ファクトリ
IClassFactory インターフェイスを実装し、特定の CLSID (クラス識別子) によって識別されるオブジェクトの 1 つ以上のインスタンスを作成する COM オブジェクト。詳細については、「CClassFactory」および「IClassFactory」を参照すること。
CoCreateInstance
指定された CLSID に関連付けられたクラスの初期化されてない 1 つのオブジェクトを作成する。詳細については、Platform SDK のドキュメントを参照すること。
CoGetClassObject
指定された CLSID に関連付けられたクラス オブジェクトのインターフェイスへのポインタを提供する。CoGetClassObject は、これを行うために必要な実行モジュール コードを検索し、必要に応じて、そのコードを動的にロードする。詳細については、Platform SDK のドキュメントを参照すること。
CoInitialize
COM (Component Object Model) ライブラリを初期化する。詳細については、Platform SDK のドキュメントを参照すること。
COLORREF
RGB カラーを指定するときに使用する 32 ビット値。詳細については、Platform SDK のドキュメントを参照すること。
CoTaskMemAlloc
IMalloc::Alloc と同じ方法でタスク メモリのブロックを割り当てる。詳細については、Platform SDK のドキュメントを参照すること。
CoTaskMemFree
CoTaskMemAlloc 関数または CoTaskMemRealloc 関数への呼び出しによって以前割り当てられたタスク メモリのブロックを解放する。詳細については、Platform SDK のドキュメントを参照すること。
CreateDIBSection
アプリケーションが直接書き込める DIB (デバイスに依存しないビットマップ) を作成する。この関数は、ビットマップのビット値の場所を指すポインタを提供する。関数がビットマップの作成に使用するファイル マッピング オブジェクトへのハンドルを渡してもよいし、ビットマップ用のメモリの割り当てをオペレーティング システムに任せてもよい。詳細については、Platform SDK のドキュメントを参照すること。
CreateEvent
名前付きイベント オブジェクトまたは名前のないイベント オブジェクトを作成する。詳細については、Platform SDK のドキュメントを参照すること。
CreateFile
さまざまなオブジェクトを作成またはオープンし、オブジェクトへのアクセスに使用できるハンドルを返す。詳細については、Platform SDK のドキュメントを参照すること。
CreateWindow
重なるウィンドウ、ポップアップ ウィンドウ、または子ウィンドウを作成する。詳細については、Platform SDK のドキュメントを参照すること。
CreateWindowEx
拡張スタイルを持つ、重なるウィンドウ、ポップアップ ウィンドウ、または子ウィンドウを作成する。それ以外の点については、この関数は CreateWindow 関数と同じである。詳細については、Platform SDK のドキュメントを参照すること。
CRITICAL_SECTION
1 つのプロセスのスレッドを同期させるときに使用するオブジェクトであるクリティカル セクション オブジェクト。同時に 1 つのスレッドだけがクリティカル セクション オブジェクトを所有できる。詳細については、Platform SDK のドキュメントを参照すること。
DDCOLORCONTROL
DirectDrawVideoPort オブジェクト、オーバーレイ サーフェス、またはプライマリ サーフェスに関連付けられたカラー コントロールを定義する構造体。詳細については、DirectX SDK のドキュメントを参照すること。
DDPIXELFORMAT
IDirectDrawSurface3::GetPixelFormat メソッド用に DirectDrawSurface オブジェクトのピクセル フォーマットを記述する構造体。詳細については、DirectX SDK の DirectShow のドキュメントを参照すること。
DDSCAPS
DirectDrawSurface オブジェクトの機能を定義する構造体。この構造体は、DirectDraw オブジェクトの機能の定義に使用される DDCAPS 構造体の一部である。詳細については、DirectX SDK の DirectShow のドキュメントを参照すること。
DDSURFACEDESC
作成されるサーフェスに関する記述が含まれている構造体。この構造体は IDirectDraw2::CreateSurface メソッドに渡される。サーフェスを使用可能な種類によって関連メンバは異なる。詳細については、DirectX SDK の DirectShow のドキュメントを参照すること。
DDVIDEOPORTCONNECT
ビデオ ポート接続を記述する構造体。詳細については、DirectX SDK のドキュメントを参照すること。
DefWindowProc
アプリケーションが処理しないすべてのウィンドウ メッセージのデフォルト処理を行うためにデフォルトのウィンドウ プロシージャを呼び出すメンバ関数。詳細については、Platform SDK のドキュメントを参照すること。
DIBSECTION
CreateDIBSection 関数を呼び出すことによって作成された、デバイスに依存しないビットマップに関する情報が含まれている構造体。詳細については、Platform SDK のドキュメントを参照すること。
DirectDrawSurface
画像がほかのサーフェスに移動するときにモニタに表示されるデータが格納されているメモリ内の領域を表すオブジェクト。詳細については、DirectX SDK の「DirectDraw Essentials」セクションの「Surfaces」を参照すること。
DISPPARAMS
IDispatch::Invoke および CBasicAudio::Invoke が、メソッドまたはプロパティに渡されるパラメータを格納するために使用する構造体。CDispParams クラスはこの構造体を実装する。詳細については、Platform SDK のドキュメントを参照すること。
DllCanUnloadNow
この関数を実装する DLL が使用中であるかどうかを判別する関数。使用中でない場合、呼び出し元は、DLL を安全にメモリからアンロードできる。詳細については、Platform SDK のドキュメントを参照すること。
DllGetClassObject
C++ ファイルおよびストリーム ハンドルがハンドラのインスタンスを作成するときに使用するエントリ ポイントとなる関数。詳細については、Platform SDK のドキュメントを参照すること。
DllRegisterServer
このサーバー モジュールでサポートされているすべてのクラスに対応するインプロセス サーバーのレジストリ エントリを作成するようにインプロセス サーバーに指示する関数。詳細については、Platform SDK のドキュメントを参照すること。
DllUnregisterServer
DllRegisterServer を使って作成されたエントリだけを削除するようにインプロセス サーバーに指示する関数。詳細については、Platform SDK のドキュメントを参照すること。
Err オブジェクト
実行時エラーに関する情報が格納される Visual Basic オブジェクト。実行時エラーが発生すると、エラーを識別する情報が Err オブジェクトのプロパティに格納される。Visual Basic コードで実行時エラーを生成するには、Raise メソッドを使用する。詳細については、Microsoft® Visual Basic® のドキュメントを参照すること。
FILETIME
ファイルの符号なし 64 ビット日付時刻値が格納される構造体。この値は、1601 年 1 月 1日を基点とする 100 ナノ秒単位の数に相当する。詳細については、Platform SDK のドキュメントを参照すること。
FOURCC
RIFF (Resource Interchange File Format) チャンクを識別するために使用される 4 文字のコード。FOURCC は、連続する 1 個から 4 個の ASCII 英文字の右側の桁を空白文字で埋めた 32 ビットの数量である。RIFF は、マルチメディア ファイルの標準フォーマットを定義するときに使用する標準であり、ファイル フォーマットの定義が時と共に変化するときによく起きる互換性の問題を防止する役割を担う。ファイル内のそれぞれのデータは標準ヘッダーによって識別されるため、特定のデータ要素を認識しないアプリケーションは、未知の情報をスキップできる。詳細については、Platform SDK のドキュメントを参照すること。
GdiFlush
呼び出し元スレッドの現在のバッチをフラッシュする関数。一括処理を行うことにより、ブール値を返す GDI 描画関数の呼び出しに必要な時間が最小限に抑えられ、描画パフォーマンスが向上する。
GetClassFile
特定のファイル名に関連付けられた CLSID を供給する関数。詳細については、Platform SDK のドキュメントを参照すること。
GetClientRect
ウィンドウのクライアント領域の座標を取得する関数。詳細については、Platform SDK のドキュメントを参照すること。
GetLastError
呼び出し元スレッドの最新のエラー コード値を返す関数。詳細については、Platform SDK のドキュメントを参照すること。
GetSystemPaletteEntries
指定されたデバイス コンテキストに関連付けられたシステム パレットから、ある範囲のパレット エントリを取得する関数。詳細については、Platform SDK のドキュメントを参照すること。
GetWindowLong
指定されたウィンドウに関する情報を取得する関数。また、ウィンドウの余分なウィンドウ メモリ内の指定されたオフセットにある 32 ビット (long 型) 値も取得する。詳細については、Platform SDK のドキュメントを参照すること。
GUID
インターフェイスや PID などのオブジェクトを一意に識別するために使用されるグローバルに一意な識別子。クラス識別子 (CLSID) およびインターフェイス識別子 (IID) は GUID である。Platform SDK に付属のコマンドライン ユーティリティ UUIDGEN を使って、または Microsoft Visual C++® に付属の Microsoft Foundation Class ライブラリ (MFC) のサンプル アプリケーション GUIDGEN を使用して、GUID を生成できる。
HBITMAP
ビットマップのハンドル。詳細については、Platform SDK のドキュメントを参照すること。
Win32 HRESULT
インターフェイスへの関数呼び出しから返される値で、重大度コード、コンテキスト情報、ファシリティー コード、および結果を説明する状態コードから構成される。詳細については、Platform SDK のドキュメントを参照すること。
IBindCtx
特定の moniker バインド操作に関する情報が格納されるオブジェクトであるバインド コンテキストへのアクセスを提供するインターフェイス。詳細については、Platform SDK のドキュメントを参照すること。
ICAbout
ビデオ圧縮ドライバに、ドライバのバージョン情報を表示するように通知するマクロ。詳細については、『Video for Windows Development Kit Version 1.1』を参照すること。
ICConfigure
ビデオ圧縮ドライバに、ドライバの構成ダイアログ ボックスを表示するように通知するマクロ。詳細については、『Video for Windows Development Kit Version 1.1』を参照すること。
IClassFactory
オブジェクトのクラス全体を処理するための 2 つのメソッドが含まれたインターフェイス。したがって、このインターフェイスは、CLSID によって識別されるオブジェクトの特定のクラスに対応するクラス オブジェクトに実装される。最初のメソッド CreateInstance は、指定された CLSID の初期化されていないオブジェクトを作成し、2 番目の LockServer は、メモリ内のオブジェクトのサーバーをロックし、新しいオブジェクトをすばやく作成できるようにする。詳細については、Platform SDK のドキュメントを参照すること。
IClassFactory::CreateInstance
初期化されていないオブジェクトを作成するメソッド。詳細については、Platform SDK のドキュメントを参照すること。
ICSendMessage
コンプレッサにメッセージを送る関数。詳細については、『Video for Windows Development Kit Version 1.1』を参照すること。
ICGetState
ビデオ圧縮ドライバを照会し、メモリ ブロック内の現在のドライバの構成を返すように求めるマクロ。このマクロを使うことも、明示的に ICM_GETSTATE メッセージを呼び出すこともできる。詳細については、Platform SDK のドキュメントを参照すること。
IDirectDraw
アプリケーションは、このインターフェイスのメソッドを使って DirectDraw オブジェクトを作成し、システムレベルの変数を操作する。詳細については、DirectX SDK を参照すること。
IDirectDraw2
アプリケーションは、このインターフェイスのメソッドを使って DirectDraw オブジェクトを作成し、システムレベルの変数を操作する。詳細については、DirectX SDK を参照すること。
IDirectSound
アプリケーションはこのインターフェイスのメソッドを使って DirectSound オブジェクトを作成し、環境を設定する。詳細については、DirectX SDK を参照すること。
IDirectSoundBuffer
アプリケーションはこのインターフェイスのメソッドを使って DirectSoundBuffer オブジェクトを作成し、環境を設定する。詳細については、DirectX SDK を参照すること。
IDispatch
Automation プログラミング ツールおよびその他のアプリケーションに対してオブジェクト、メソッド、およびプロパティを公開するインターフェイス。IDispatch から派生するデュアル インターフェイスは、Automation 対応タイプのみを使用する。IDispatch インターフェイスと同様に、デュアル インターフェイスは、事前バインディングおよび実行時バインディングをサポートする。ただし、デュアル インターフェイスは、関数テーブル バインディングもサポートする点が異なる。詳細については、Platform SDK のドキュメントを参照すること。
IEnumMoniker
モニカのコンポーネントを列挙するため、またはモニカのテーブル内のモニカを列挙するために使用するインターフェイス。詳細については、Platform SDK のドキュメントを参照すること。
IEnumVARIANT
コレクション オブジェクトに対する繰り返しの手段を提供するディスパッチ インターフェイス。詳細については、Platform SDK のドキュメントを参照すること。
IEnumXXXX
列挙インターフェイスのセット。これを利用して、オブジェクトが管理する特定のタイプのアイテムの数を列挙することができる。アイテムのタイプごとに 1 つのインターフェイスがある。これらのインターフェイスを使用する際は、クライアントが、アイテムのコレクションを管理するオブジェクトに対して列挙子オブジェクトを作成するように要求する。列挙オブジェクトのインターフェイスは、列挙インターフェイスの 1 つであり、すべてが IEnumItem_name というフォーマットの名前を持つ。それぞれの列挙インターフェイス間で異なるのは、列挙の対象だけである。すべての列挙インターフェイスは同じメソッドのセットを持ち、同じ方法で使用される。詳細については、Platform SDK のドキュメントを参照すること。
IMoniker
COM オブジェクトを一意に識別する情報が格納されているモニカ オブジェクトを使用できるようにするメソッドが含まれたインターフェイス。モニカ オブジェクトの IMoniker インターフェイスへのポインタを持つオブジェクトは、オブジェクトが実際に分散システム上のどこにあるかに関する特定の情報がほかにまったくない場合でも、識別されたオブジェクトを検索し、アクティブにして、そのオブジェクトにアクセスすることができる。詳細については、Platform SDK の COM のドキュメントを参照すること。
IMoniker::BindToStorage
モニカによって識別されるオブジェクトが格納されている記憶領域を指すインターフェイス ポインタを取得するメソッド。IMoniker::BindToObject と異なり、このメソッドはモニカによって識別されるオブジェクトをアクティブにすることはない。詳細については、Platform SDK の COM のドキュメントを参照すること。
IMoniker::BindToObject
モニカを使って、モニカが識別するオブジェクトにバインドするメソッド。バインド処理では、オブジェクトを検索し、必要であればオブジェクトを実行状態にして、識別されたオブジェクトの指定されたインターフェイスを指すポインタを呼び出し元に渡す。詳細については、Platform SDK の COM のドキュメントを参照すること。
IPersist
システムに永続的に格納できるオブジェクトの CLSID を供給するための GetClassID という単一のメソッドを持つインターフェイス。ほかの永続性インターフェイス IPersistStorage、IPersistStream、または IPersistFile のいずれかを実装するときは、IPersist が備える単一のメソッドを実装する必要がある。マーシャリングで使用する場合のように、永続的オブジェクトの CLSID を取得することだけが目的の場合は、IPersist を使用できる。詳細については、Platform SDK のドキュメントを参照すること。
IPersistFile
オブジェクトのロードまたは保存を、ストレージ オブジェクトやストリームではなく、ディスク ファイルで行えるようにするメソッドを備えたインターフェイス。通常は、たとえば、リンク オブジェクトに IPersistFile を実装する。詳細については、Platform SDK のドキュメントを参照すること。
IPersistPropertyBag
IPropertyBag および IErrorLog と連携して機能し、それぞれのプロパティ ベースの永続性メカニズムを定義するインターフェイス。詳細については、Platform SDK の COM のドキュメントを参照すること。
IPersistStream
単純なシリアル ストリームを使って格納を行うオブジェクトを保存し、ロードするためのメソッドを備えたインターフェイス。詳細については、Platform SDK のドキュメントを参照すること。
IPropertyBag
オブジェクトにプロパティ バッグを提供するインターフェイス。オブジェクトはプロパティ バッグにオブジェクトのプロパティを永続的に保存できる。詳細については、Platform SDK のドキュメントを参照すること。
IPropertyPage
プロパティ シート内の特定のページを管理するプロパティ ページ オブジェクトの主な機能を提供するインターフェイス。詳細については、Platform SDK のドキュメントを参照すること。
IPropertyPageSite
プロパティ ページ サイト オブジェクトの主な機能を提供するインターフェイス。詳細については、Platform SDK のドキュメントを参照すること。
IsBadReadPtr
呼び出し元プロセスが指定された範囲のメモリの読み取り権限を持っていることを確認する Win32 関数。詳細については、Platform SDK のドキュメントを参照すること。
ISpecifyPropertyPages
オブジェクトがプロパティ ページをサポートしていることを示すインターフェイス。詳細については、Platform SDK のドキュメントを参照すること。
IStorage::OpenStream
grfMode パラメータで指定されたアクセス権限を使って、このストレージ オブジェクト内の既存のストリーム オブジェクトをオープンするメソッド。詳細については、Platform SDK のドキュメントを参照すること。
IStream
ストリーム オブジェクトに対するデータの読み取りおよび書き込みをサポートするインターフェイス。詳細については、Platform SDK のドキュメントを参照すること。
ITypeInfo
通常、オブジェクトに関する情報の読み取りに使われるインターフェイス。たとえば、オブジェクト ブラウザ ツールは、ITypeInfo を使って、オブジェクトの特性および機能に関する情報をタイプ ライブラリから取得できる。詳細については、Platform SDK のドキュメントを参照すること。
LoadLibrary
指定された実行モジュールを呼び出し元プロセスのアドレス空間にマップする関数。詳細については、Platform SDK のドキュメントを参照すること。
LONGLONG
64 ビットの符号付き整数。詳細については、Platform SDK のドキュメントを参照すること。
LRESULT
ウィンドウ プロシージャまたはコールバック関数から返される 32 ビット値。詳細については、Platform SDK のドキュメントを参照すること。
MainAVIHeader
AVI ファイル全体に関するグローバル情報が格納されている構造体。詳細については、Platform SDK のドキュメントを参照すること。
moniker
IMoniker インターフェイスを実装するオブジェクト。モニカは、COM オブジェクトを一意に識別する名前として機能する。パスがファイル システム内のファイルを識別するのと同様に、モニカはディレクトリ名前空間内の COM オブジェクトを識別する。
MoveWindow
指定されたウィンドウの位置と大きさを変更する関数。詳細については、Platform SDK のドキュメントを参照すること。
MSG
スレッドのメッセージ キューにあるメッセージ情報が格納されている構造体。詳細については、Platform SDK のドキュメントを参照すること。
MsgWaitForMultipleObjects
待機条件が満たされたかどうかを判別する関数。詳細については、Platform SDK のドキュメントを参照すること。
MultiByteToWideChar
文字列をワイド文字列 (Unicode) にマップする関数。詳細については、Platform SDK のドキュメントを参照すること。
OleCreatePropertyFrame
新しいプロパティ フレームを起動する関数。新しいプロパティ フレームとは、親が "hwndOwner" であり、親ウィンドウ内のポイント (x,y) にダイアログがあり、キャプションが "lpszCaption" のプロパティ シート ダイアログ ボックスである。詳細については、Platform SDK のドキュメントを参照すること。
OPENFILENAME
GetOpenFileName 関数および GetSaveFileName 関数が、[開く] コモン ダイアログ ボックスまたは [名前を付けて保存] コモン ダイアログ ボックスを初期化するときに使用する情報が格納されている構造体。詳細については、Platform SDK のドキュメントを参照すること。
OutputDebugString
現在のアプリケーションのデバッガに文字列を送る関数。詳細については、Platform SDK のドキュメントを参照すること。
PALETTEENTRY
論理カラー パレット内のエントリの色と用途を指定する構造体。論理パレットは、LOGPALETTE 構造体によって定義される。詳細については、Platform SDK のドキュメントを参照すること。
PCMWAVEFORMAT
PCM waveform オーディオ データのデータ フォーマットを記述する構造体。詳細については、Platform SDK のドキュメントを参照すること。
PeekMessage
スレッド メッセージ キューにメッセージがあるかどうかをチェックし、メッセージがあれば、そのメッセージを指定された構造体に格納する関数。詳細については、Platform SDK のドキュメントを参照すること。
PostMessage
指定されたウィンドウを作成したスレッドに関連付けられているメッセージ キューにメッセージを格納 (ポスト) し、スレッドがメッセージを処理するのを待たずに終了する関数。詳細については、Platform SDK のドキュメントを参照すること。
プロパティ バッグ
IPropertyBag インターフェイスを実装する、永続的オブジェクトの記述用のコンテナ。
PROPPAGEINFO
プロパティ フレームに対してプロパティ ページを説明するのに使用するパラメータが格納されている構造体。詳細については、Platform SDK のドキュメントを参照すること。
RECT
矩形の左上隅と右下隅の座標を定義する構造体。詳細については、Platform SDK のドキュメントを参照すること。
ReleaseSemaphore
指定されたセマフォ オブジェクトのカウントを指定された量だけ増加させる関数。詳細については、Platform SDK のドキュメントを参照すること。
RGBQUAD
赤、緑、および青の相対的な濃度から構成される色を記述する構造体。詳細については、Platform SDK のドキュメントを参照すること。
SendMessage
指定されたメッセージを 1 つ以上のウィンドウに送る関数。詳細については、Platform SDK のドキュメントを参照すること。
SetDIBColorTable
指定されたデバイス コンテキストで選択されている DIB (デバイスに依存しないビットマップ) のカラー テーブルに含まれる一定の範囲のエントリの RGB (赤、緑、青) 値を設定する関数。詳細については、Platform SDK のドキュメントを参照すること。
SetDIBitsToDevice
DIB (デバイスに依存しないビットマップ) のカラー データを使って、転送先デバイス コンテキストに関連付けられているデバイス上の指定された矩形内のピクセルを設定する関数。詳細については、Platform SDK のドキュメントを参照すること。
SetDlgItemText
ダイアログ ボックスのタイトルまたはコントロールのテキストを設定する関数。詳細については、Platform SDK のドキュメントを参照すること。
SetParent
指定された子ウィンドウの親ウィンドウを変更する関数。詳細については、Platform SDK のドキュメントを参照すること。
SetWindowLong
指定されたウィンドウの属性を変更する関数。この関数は、ウィンドウの余分なウィンドウ メモリ内の指定されたオフセットにある 32 ビット (long 型) の値も設定する。詳細については、Platform SDK のドキュメントを参照すること。
ShowWindow
指定されたウィンドウの表示状態を設定する関数。詳細については、Platform SDK のドキュメントを参照すること。
SIZE
矩形の幅と高さを指定する構造体。詳細については、Platform SDK のドキュメントを参照すること。
StretchBlt
コピー元矩形からコピー先矩形へビットマップをコピーし、必要な場合は、コピー先矩形の大きさに合わせてビットマップを拡張または圧縮する関数。Windows は、コピー先デバイス コンテキストで現在設定されている拡張モードに従ってビットマップを拡張または圧縮する。詳細については、Platform SDK のドキュメントを参照すること。
StretchDIBits
デバイスに依存しないビットマップ (DIB) 内のピクセルの矩形のカラー データを、指定されたコピー先矩形にコピーする関数。コピー先矩形がコピー元矩形より大きい場合、この関数は、コピー先矩形に合わせてカラー データの行と列を拡張する。コピー先矩形がコピー元矩形より小さい場合、この関数は、指定されたラスタ操作を行って、行と列を圧縮する。詳細については、Platform SDK のドキュメントを参照すること。
SysAllocString
新しい文字列を割り当てて、渡された文字列をその文字列にコピーする関数。詳細については、Platform SDK のドキュメントを参照すること。
SysFreeString
前に割り当てられた文字列を解放する関数。詳細については、Platform SDK のドキュメントを参照すること。
timeBeginPeriod
アプリケーションまたはデバイス ドライバの最小タイマ解像度を設定する関数。詳細については、Platform SDK のドキュメントを参照すること。
timeGetTime
システム時間をミリ秒単位で取得する関数。システム時間とは、Windows が起動してから経過した時間である。詳細については、Platform SDK のドキュメントを参照すること。
timeSetEvent
指定されたタイマ イベントを開始する関数。マルチメディア タイマは、タイマ自体のスレッドで実行される。イベントがアクティブになると、タイマは指定されたコールバック関数を呼び出す。詳細については、Platform SDK のドキュメントを参照すること。
TXTDT_MG
ビデオに関するテキストの記述を格納できる構造体。詳細については、『DVD-Video 仕様』の「セクション 4.1.6」および「Annex A」を参照すること。仕様のコピーを入手するには、〒105-01 東京都港区芝浦 1 丁目 1-1、電話 03-5444-9580、ファックス 03-5444-9430 の東芝に連絡すること。
videoDialog
ビデオ キャプチャ デバイス ドライバの構成パラメータを設定するときに使用するダイアログ ボックスを表示する関数。詳細については、『Video for Windows Development Kit Version 1.1』を参照すること。
videoMessage
ビデオ キャプチャ デバイス ドライバにメッセージを送る関数。詳細については、『Video for Windows Development Kit Version 1.1』を参照すること。
WaitForMultipleObjects
待機条件が満たされたかどうかを判別する Win32 関数。条件が満たされていなければ、呼び出し元スレッドは待機状態になる。この関数は、指定されたオブジェクトの 1 つまたはすべてが通知済状態になったとき、または、タイムアウト間隔が経過したときに終了する。詳細については、Platform SDK のドキュメントを参照すること。
WaitForSingleObject
指定されたオブジェクトの現在の状態をチェックする Win32 関数。オブジェクトが未通知状態になっていれば、呼び出し元スレッドは待機状態になる。この関数は、指定されたオブジェクトが通知済状態になったとき、またはタイムアウト間隔が経過したときに終了する。詳細については、Platform SDK のドキュメントを参照すること。
WAVEFORMAT
waveform オーディオ データのフォーマットを記述する構造体。詳細については、Platform SDK のドキュメントを参照すること。


DirectSetup

ここでは、Platform Software Development Kit (SDK) またはスタンドアローン DirectX SDK における Microsoft® DirectX® アプリケーション プログラミング インターフェイス (API) の Microsoft® DirectSetup® コンポーネントについて説明する。ここで説明する内容の大部分は、C++ 開発者向けのものである。Visual Basic® でのセットアップについては、「DirectX for Visual Basic アプリケーションのインストール」を参照すること。ここでは次のトピックに分けて説明する。

  • DirectSetup について
  • DirectSetup の要点
  • DirectX for Visual Basic アプリケーションのインストール
  • DirectSetup リファレンス
  • DirectSetup サンプル


DirectSetup について

Microsoft® DirectSetup は、Microsoft DirectX® のすべてのコンポーネントを一度の呼び出しでインストールするためのシンプルな API である。この API の意義は、単に便利というだけにとどまらない。DirectX は複雑な構成になっているため、インストールも複雑なタスクとなる。そのため、DirectX のインストールは手動で行うべきではない。

DirectSetup には、いくつかの API 関数と構造体が含まれる。そのほか、インストール プロセス用のユーザー インターフェイスをアプリケーション側でカスタマイズするためのプロトタイプとして、DirectXSetupCallbackFunction も 用意されている。DirectX SDK には、このコールバック関数の使用例を示すサンプル アプリケーションが収録されている。詳細については、「Dinstall サンプル」を参照すること。


DirectSetup の要点

ここでは、Microsoft® DirectSetup® コンポーネントの概要について説明する。説明する内容は以下のとおりである。

  • DirectSetup のセットアップの概要
  • セットアップ フォルダの準備
  • セットアップのカスタマイズ
  • セットアップ プログラムのテスト
  • AutoPlay の使用


DirectSetup のセットアップの概要

Microsoft® DirectX® をベースとするアプリケーションおよびゲームは、DirectXSetup 関数を使用して、既にインストールされている Microsoft Windows® システムに必要なシステム コンポーネントをインストールすることができる。この関数では、ディスプレイやオーディオ デバイスで適切に DirectX がサポートされるよう、ドライバのアップデートも行うことができる。DirectXSetup は、通常、アプリケーション ファイルのインストールに使用するプログラムから呼び出す。

注 : DirectXSetup 関数は、旧バージョンの DirectX システム コンポーネントを上書きする。たとえば、既に DirectX 7.0 のコンポーネントが存在するシステムに DirectX 8.0 をインストールすると、DirectX 7.0 のコンポーネントすべてが上書きされる。ただし、DirectX のコンポーネントはすべてコンポーネント オブジェクト モデル (COM) の下位互換性規則に準拠しているので、DirectX 7.0 用に記述したソフトウェアも引き続き正常に機能する。

DirectXSetup 関数は、DirectX コンポーネント、ディスプレイ ドライバ、オーディオ ドライバのアップグレードが必要なことを知らせることができる。また、これらのコンポーネントを、Windows オペレーティング システムに悪影響を与えることなしにアップグレードできるかどうかも判断できる。これがいわゆるセーフ アップグレードである。アップグレードの際は、コンピュータ上で動作しているアプリケーションだけでなく、オペレーティング システムに対する安全性も考慮する。また、Windows にとっては安全でも、一部のハードウェア依存アプリケーションに悪影響を与えてしまう場合もある。

デフォルトでは、DirectXSetup 関数は安全なアップグレードのみを実行する。デバイス ドライバのアップグレードによって Windows の動作に悪影響が及ぶ可能性がある場合、アップグレードは行われない。

セットアップ処理中、DirectSetup は置き換えるシステム コンポーネントとドライバのバックアップ コピーを作成する。これらのコピーは、問題が発生した場合に復元するためのものである。

ディスプレイ ドライバまたはオーディオ ドライバをアップグレードするとき、DirectXSetup 関数は、Microsoft 社が作成したデータベースを利用してアップグレード プロセスを管理する。このデータベースには、Microsoft 社、ハードウェアの製造元、またはハードウェアの販売元から提供されている既存のドライバについての情報が含まれている。また、Microsoft 社やその他のサイトで行われたテスト基づくそれぞれのドライバのアップグレード状況も記録されている。

DirectXSetup 関数を実行したら、戻り値をチェックする。戻り値が DSETUPERR_SUCCESS_RESTART の場合は、再起動するまで変更内容が有効にならないことをユーザーに知らせ、すぐに再起動するかどうか選択させる。この方法については、Dinstall サンプル アプリケーションの Dinstall.c の例を参照すること。


セットアップ フォルダの準備

DirectXSetup 関数は、インストールのルート ディレクトリを示すパラメータ lpszRootPath を取る。このパラメータを NULL にして、現在のディレクトリ (つまり、セットアップ プログラムが保存されているディレクトリ) をルート パスとすることもできる。

ルート ディレクトリには、dsetup.dll と dsetup32.dll を保存する必要がある。また、この中には「DirectX」 (大文字小文字の区別なし) という名前のフォルダを用意し、再配布可能なすべてのファイルおよびドライバを保存する。正しい構造のアプリケーション セットアップ ディスクは、Microsoft® DirectX SDK ディスクの Dxf\Redist\DirectX8 フォルダの内容すべてをセットアップ プログラムのルート パスにコピーすると作成できる。このフォルダは、SDK のインストール時に開発用のコンピュータにコピーされないので、オリジナル ディスクから別途コピーする必要がある。


セットアップのカスタマイズ

Microsoft® DirectSetup® では、Microsoft DirectX® セットアップ プロセスをカスタマイズするためのコールバック関数を定義することができる。このコールバック関数は、DirectSetup ドキュメントの中では DirectXSetupCallbackFunction と呼ばれているが、実際には任意の名前を割り当てることができる。

セットアップ プログラムでコールバック関数を使用しない場合、DirectXSetup 関数は、Microsoft Win32® MessageBox 関数を呼び出して、ダイアログ ボックス内にステータス情報やエラー情報を表示し、ユーザー入力の取得を行う。コールバック関数を使用する場合、このステータス ダイアログまたはメッセージ ボックスの作成に使用されるはずの情報は、代わりにコールバック関数に渡される。コールバック関数は、インストールまたはアップグレード可能な DirectX コンポーネントおよびデバイス ドライバごとに一度ずつ呼び出される。

コールバック関数は、以下の用途に使用できる。

  • カスタム インターフェイスの使用 - MessageBox や Microsoft Windows® の標準ダイアログ ボックス以外の方法で、セットアップ プログラムのメッセージを表示できる。コールバック関数を使うことで、DirectX コンポーネントのインストール用メッセージを、独自のインターフェイスに統合できる。
  • プログレス インジケータの更新
  • ステータス メッセージおよびエラー メッセージの表示制御 - 初心者向けのプログラムを開発する場合には、エラー メッセージを制御して、セットアップ プログラムにエラーの処理やアップグレードの選択を自動的に処理させたい場合がある。このようなセットアップ プログラムの開発には手間がかかるが、対象ユーザー層を考えると適切な措置といえる。

セットアップのカスタマイズにあたっては、次の各トピックを参考にすること。

  • DirectSetup コールバック関数の作成
  • コールバック関数の設定
  • コールバック関数でのアップグレード フラグの使い方
  • コールバック関数によるデフォルト動作の無効化


DirectSetup コールバック関数の作成

セットアップ プロセスをカスタマイズするには、まず次の宣言で示した DirectXSetupCallbackFunction プロトタイプに適合するコールバック関数を作成する。

DWORD WINAPI DirectXSetupCallbackFunction(
        DWORD dwReason,
        DWORD dwMsgType,
        LPSTR szMessage,
        LPSTR szName,
        void *pInfo);

この例 (Dinstall を修正したもの) では、関数名がプロトタイプと同じになっているが、これは変更可能である。パラメータ名は、dsetup.h ヘッダー ファイルで宣言されているプロトタイプと若干異なるが、以下の説明ではこれらの名前を使用する。

パラメータ

dwReason は、コールバック関数が呼び出された理由を示すパラメータである。有効値の一覧および各有効値の説明については、DirectXSetupCallbackFunction のリファレンスを参照すること。

dwMsgType パラメータは、Microsoft® DirectSetup® がデフォルトで MessageBox に渡すフラグ (表示するボタンやアイコンを制御するフラグなど) と同等のフラグを受け取る。中でも、ボタン フラグは、必要な戻り値の指定に使用できる。この値が 0 の場合、イベントはユーザー入力を要求しないため、DirectSetup は通常ステータス メッセージを表示する。

szMessage パラメータは、コールバック関数を使用しない場合に DirectSetup がステータス ダイアログ ボックスまたは MessageBox に渡すものと同じテキストを受け取る。

ドライバがアップグレード対象の場合、szName パラメータにドライバ名が渡され、pInfo はアップグレードの処理方法 (既存のドライバの使用を推奨する、アップグレードを推奨するなど) に関する情報を示す。詳細については、「コールバック関数でのアップグレード フラグの使い方」を参照すること。

コールバック関数が各パラメータをどのように解釈するかについては、開発者の裁量で決定する。通常は、表示するメッセージ (dwReason に基づく) とユーザーに選択肢を提示するタイミングを選択し、それに応じてインターフェイスを変更する。

戻り値

コールバック関数からの戻り値は、次の規則に従う必要がある。

  • dwMsgType が 0 の場合、戻り値は IDOK でなければならない。この場合、ユーザーに対する選択肢はない。(入力が必要ない場合でも、アプリケーションはステータス メッセージを表示してかまわない。)
  • dwMsgType が 0 以外の場合の戻り値は、MessageBox を使用した場合にユーザーが同様の選択をしたときに返される値と同じ値でなければならない。

dwMsgType が 0 以外の場合の適切な戻り値を確認するには、通常ならどのようなボタンがメッセージ ボックスに表示されるか実際にテストしてみる。次の例 (Dinstall の GetReply 関数より) は、このテスト方法を示したものである。

/* グローバル g_wReply は、ユーザーが選択したカスタム
ダイアログ ボタンを示す。 */

switch (dwMsgType & 0x0000000F)
{
   / * 通常、[OK] ボタンと [キャンセル] ボタンが配置される。
       IDBUT1 は [OK] ボタンに対応する。ユーザーが [OK] ボタンをクリックしなかった場合は、
       [キャンセル] ボタンがクリックされたと判定される。*/
    case MB_OKCANCEL:
        wDefaultButton = (g_wReply == IDBUT1) ? IDOK : IDCANCEL;
        break;

    / * 上記以外のボタンの組み合わせの場合は、以下のようになる。*/
    case MB_OK:
        wDefaultButton = IDOK;
        break;
    case MB_RETRYCANCEL:
        wDefaultButton = (g_wReply == IDBUT1) ? IDRETRY : IDCANCEL;
        break;
    case MB_ABORTRETRYIGNORE:
        if (g_wReply == IDBUT1)
            wDefaultButton = IDABORT;
        else if (g_wReply == IDBUT2)
            wDefaultButton = IDRETRY;
        else
            wDefaultButton = IDIGNORE;
        break;
    case MB_YESNOCANCEL:
        if (g_wReply == IDBUT1)
            wDefaultButton = IDYES;
        else if (g_wReply == IDBUT2)
            wDefaultButton = IDNO;
        else
            wDefaultButton = IDCANCEL;
        break;
    case MB_YESNO:
        wDefaultButton = (g_wReply == IDBUT1) ? IDYES : IDNO;
        break;
    default:
        wDefaultButton = IDOK;
}

このルーチンは、カスタム インターフェイスからのボタン クリックを、コールバック関数なしの場合に DirectSetup が作成する標準ダイアログ ボックス内の対応するボックス識別子に平行移動する。wDefaultButton 変数は、対応する標準ダイアログ ボックス ボタンの識別子に設定される。コールバック関数から返されるのは、この値である。

dwMsgType が 0 以外の値の場合でも、必ずしもユーザーに選択肢を与える必要はない。たとえば、DirectSetup が通常ユーザーに確認を求めるような場合でも、自動的にドライバをアップグレードすることも可能である。サンプルの Dinstall は、問題のある場合のみメッセージを表示するようユーザーが選択している場合で、しかもドライバをアップグレードしても安全であると考えられるときに、次のように自動アップグレードを行うようになっている。

case DSETUP_CB_UPGRADE_SAFE:
    switch (dwMsgType & 0x0000000F)
    {
        case MB_YESNO:
        case MB_YESNOCANCEL:
            return IDYES;
        case MB_OKCANCEL:
        case MB_OK:
        default:
            return IDOK;
    }
    break;

コールバック関数は、ユーザーにアップグレードを続行するかどうか確認するダイアログ ボックスで肯定を表すボタンに応じて、IDYES または IDOK を返す。


コールバック関数の設定

コールバック関数を使用する場合は、DirectXSetup を呼び出す前にシステムに知らせておく必要がある。これには、コールバックへのポインタをパラメータとして渡して DirectXSetupSetCallback 関数を呼び出す。次の例を参照すること。

DirectXSetupSetCallback(
        (DSETUP_CALLBACK) DirectXSetupCallbackFunction);


コールバック関数でのアップグレード フラグの使い方

アプリケーションで定義されたコールバック関数 DirectXSetupCallbackFunction が DirectXSetup 関数で呼び出されると、コールバック関数に呼び出し理由を示すパラメータが渡される。理由が DSETUP_CB_MSG_CHECK_DRIVER_UPGRADE の場合、pInfo パラメータは、DirextXSetup 関数が推奨する Microsoft® DirectX® コンポーネントおよびドライバのアップグレード方法をまとめたフラグを保持する DSETUP_CB_UPGRADEINFO 構造体を示す。これらのフラグを格納する構造体メンバは、UpgradeFlags と呼ばれる。

UpgradeFlags には次のようなカテゴリがある。

プライマリ アップグレード フラグ
これらのフラグは互いに排他的である。構造体メンバ UpgradeFlags には常にいずれか 1 つのフラグが存在する。フラグを抽出するには、DSETUP_CB_UPGRADE_TYPE_MASK とのビットごとの AND 処理をとる。

DSETUP_CB_UPGRADE_FORCE

DSETUP_CB_UPGRADE_KEEP

DSETUP_CB_UPGRADE_SAFE

DSETUP_CB_UPGRADE_UNKNOWN

セカンダリ アップグレード フラグ
これらのフラグの 1 つまたは両方を指定することができる。

DSETUP_CB_UPGRADE_CANTBACKUP

DSETUP_CB_UPGRADE_HASWARNINGS

デバイス アクティブ フラグ
ドライバをアップグレード中のデバイスがアクティブな場合に存在するフラグ。ほかのフラグと組み合わせて使用できる。

DSETUP_CB_UPGRADE_DEVICE_ACTIVE

デバイス クラス フラグ
これらのフラグは互いに排他的である。どちらかのフラグが必ず存在する。

DSETUP_CB_UPGRADE_DISPLAY

DSETUP_CB_UPGRADE_MEDIA

つまり、Reason パラメータの値が DSETUP_CB_MSG_CHECK_DRIVER_UPGRADE であれば、pInfo で指定される構造体メンバ UpgradeFlags には、常に 1 つの一次アップグレード フラグ、0 個以上の二次アップグレード フラグ、0 個または 1 つのデバイス アクティブ フラグ、および 1 つのデバイス クラス フラグが含まれる。

UpgradeFlags のメンバに DSETUP_CB_UPGRADE_KEEP が設定されている場合は、Windows® が正常に機能しなくなる恐れがあるため、DirectX コンポーネントやデバイス ドライバをアップグレードすることはできない。DirectXSetup 関数によるコンポーネントまたはドライバのアップグレードは行われない。

UpgradeFlags に DSETUP_CB_UPGRADE_FORCE という値がある場合は、Windows を正常に機能させるため、コンポーネントまたはドライバのアップグレードが必要である。このため、DirectXSetup 関数は、ドライバまたはコンポーネントのアップグレードを行う。ただし、アップグレードによって、システム上の一部のプログラムに悪影響が及ぶ可能性がある。DirectXSetup 関数がこの状態を検出すると、UpgradeFlags のメンバは (DSETUP_CB_UPGRADE_FORCE | DSETUP_CB_UPGRADE_HAS_WARNINGS) に設定される。この場合、DirectXSetup 関数は、アップグレードを実行する一方で、ユーザーに警告を発する。

コンポーネントおよびドライバをインストールしても Windows の動作に悪影響が及ばない場合、そのコンポーネントやドライバは安全にアップグレードできると見なされる。この場合、UpgradeFlags のメンバには DSETUP_CB_UPGRADE_SAFE が設定される。ただし、Windows に対しては安全であっても、システムにインストールされているプログラムに問題が発生する可能性はある。DirectXSetup 関数がこの状態を検出すると、UpgradeFlags のメンバには、値 (DSETUP_CB_UPGRADE_SAFE | DSETUP_CB_UPGRADE_HAS_WARNINGS) が格納される。この場合、DirectXSetup 関数のデフォルト動作では、アップグレードは実行されない。


コールバック関数によるデフォルト動作の無効化

アプリケーションで定義された関数 DirectXSetupCallbackFunction の戻り値を使って、DirectXSetup 関数のデフォルト動作の一部を無効化することができる。

たとえば、DirectXSetup のデフォルト動作では、pInfo パラメータが示す構造体内のアップグレード タイプが (DSETUP_CB_UPGRADE_SAFE | DSETUP_CB_UPGRADE_HAS_WARNINGS) に設定されているとコンポーネントはインストールされない。この場合、コールバック関数の MsgType パラメータは (MB_YESNO | MB_DEFBUTTON2) に設定される。コールバック関数を使用しない場合は、[No] がデフォルト ボタンになったダイアログ ボックスがユーザーに表示される。ユーザー入力を調べずにデフォルトを受け付ける場合、コールバック関数は IDNO を返す。デフォルトを無効にする場合は、IDYES を返す。デフォルトを無効にする場合、DirectXSetup 関数はユーザーに通知する。


セットアップ プログラムのテスト

作成したセットアップ プログラムの Microsoft® DirectSetup® コンポーネントをテストするには、DirectXSetup 関数に DSETUP_TESTINSTALL フラグを渡したバージョンをコンパイルする。そして、「セットアップ フォルダの準備」で説明したインストール ディレクトリをセットアップする。

セットアップ プログラムを実行すると、DirectSetup は、実際にはコンポーネントをインストールせずに、Microsoft DirectX® インストール時の模擬動作を行う。コールバック関数を設定している場合は、コールバック関数の動作も調べられる。


AutoPlay の使用

AutoPlay 対応の CD タイトルを作成するには、Microsoft® DirectX® SDK CD のルート ディレクトリ中の Autorun.inf ファイルを、アプリケーション ディレクトリのルートにコピーする。Autorun.inf は、以下の情報を格納するテキスト ファイルである。

[autorun]
OPEN=SETUP.EXE

アプリケーションのセットアップ プログラム名が Setup.exe の場合、このファイルを変更する必要はない。それ以外の名前が付いている場合は、実際のセットアップ プログラム名に合わせてこのファイルを編集しなければならない。


DirectX for Visual Basic アプリケーションのインストール

モジュール内で関数に参照を宣言すると、Microsoft Visual Basic アプリケーションで Microsoft® DirectSetup® 関数を使用できるが、推奨方法はアプリケーション ウィザードの使用である。CD-ROM でアプリケーションを配布するには、以下の操作を実行する。

Visual Basic アプリケーションの配布

  1. アプリケーション ウィザードを起動する。
  2. 依存リストから DxVBLib.dll を削除する。
  3. Microsoft Direct® SDK CD の Redist フォルダ (リテール用 \Dxf\Redist\Directx7、デバッグ用 \Dxf\Debug) のすべてのファイルを追加する。
  4. [Finish] ボタンをクリックし、アプリケーション ウィザードを終了する。
  5. DirectX SDK CD の support フォルダにある Setup1.exe を (アプリケーション ウィザードで作成された) Setup1.exe に上書きする。
  6. Visual Basic 5.0 を使用している場合は、圧縮ユーティリティを使って Setup1.exe を Setup1.ex_ に圧縮する。Visual Basic 6.0 で開発している場合は、アプリケーション ウィザードで作成されたバッチ ファイルを実行する。

これで、CD でファイルを配布する準備が整う。


DirectSetup リファレンス

ここでは、Microsoft® DirectSetup® の API 要素のリファレンス情報を記述する。リファレンス情報は以下のカテゴリに分類される。

  • 関数
  • 構造体
  • 戻り値

このリファレンスは主に、C++ でプログラミングを行うときに使用する。Microsoft® DirectX® for Microsoft Visual Basic® のセットアップ情報については、「DirectX for Visual Basic アプリケーションのインストール」を参照すること。


関数

ここでは、Microsoft® DirectSetup® で使用する以下のグローバル関数について説明する。

  • DirectXRegisterApplication
  • DirectXSetup
  • DirectXSetupCallbackFunction
  • DirectXSetupGetVersion
  • DirectXSetupSetCallback
  • DirectXUnRegisterApplication


DirectXRegisterApplication

アプリケーションを DirectPlayLobby 対応アプリケーションとして登録する。

int WINAPI DirectXRegisterApplication(
  HWND hWnd,
  LPDIRECTXREGISTERAPP lpDXRegApp
);

パラメータ

hWnd
親ウィンドウのハンドル。このパラメータが NULL の場合は、デスクトップが親ウィンドウとなる。
lpDXRegApp
DirectPlayLobby で正しくアプリケーションを動作させるために必要なレジストリ エントリを含む DIRECTXREGISTERAPP 構造体のアドレス。

戻り値

成功した場合は、TRUE を返す。

失敗した場合は、FALSE を返す。GetLastError 関数を使用すると、拡張エラー情報を取得できる。

注意

DirectXRegisterApplication 関数では、Dsetup.dll と Dsetup32.dll の両方が必要となる。これらのファイルはシステムにインストールされていないが、SDK に含まれている。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dsetup.h で宣言。
インポート ライブラリ : dsetup.lib を使用。

参照

DirectXUnRegisterApplication


DirectXSetup

1 つまたは複数の Microsoft® DirectX® コンポーネントをインストールする。

int WINAPI DirectXSetup(
  HWND  hWnd,
  LPSTR lpszRootPath,
  DWORD dwFlags
);

パラメータ

hWnd
セットアップ ダイアログ ボックスの親ウィンドウのハンドル。
lpszRootPath
DirectX コンポーネント ファイルのルート パスを含む文字列のアドレス。この文字列には、ファイル Dsetup.dll および Dsetup32.dll と、再配布可能ファイルを格納した「DirectX」 (大文字小文字の区別なし) ディレクトリのあるディレクトリへのフル パスを指定しなければならない。この値が NULL の場合は、現在の作業ディレクトリが使用される。
dwFlags
インストール対象となる DirectX コンポーネントを示す 1 つまたは複数のフラグ。推奨は、フル インストール (DSETUP_DIRECTX)。
DSETUP_D3D | 使用しない。このフラグを使用する DirectX プログラムは、DirectX コンポーネントをすべてインストールする。
DSETUP_DDRAW | 使用しない。このフラグを使用する DirectX プログラムは、DirectX コンポーネントをすべてインストールする。
DSETUP_DDRAWDRV | DirectX 8.0 では使用しない。
DSETUP_DINPUT | 使用しない。このフラグを使用する DirectX プログラムは、DirectX コンポーネントをすべてインストールする。
DSETUP_DIRECTX | DirectX と互換性のあるディスプレイ ドライバおよびオーディオ ドライバに加え、DirectX ランタイム コンポーネントをインストールする。
DSETUP_DIRECTXSETUP | 使用しない。このフラグを使用する DirectX プログラムは、DirectX コンポーネントをすべてインストールする。
DSETUP_DPLAY | 使用しない。このフラグを使用する DirectX プログラムは、DirectX コンポーネントをすべてインストールする。
DSETUP_DPLAYSP | 使用しない。このフラグを使用する DirectX プログラムは、DirectX コンポーネントをすべてインストールする。
DSETUP_DSOUND | 使用しない。このフラグを使用する DirectX プログラムは、DirectX コンポーネントをすべてインストールする。
DSETUP_DSOUNDDRV | DirectX 8.0 では使用しない。
DSETUP_DXCORE | DirectX ランタイム コンポーネントをインストールする。DirectX と互換性のあるディスプレイ ドライバとオーディオ ドライバはインストールしない。
DSETUP_TESTINSTALL | インストール内容をテストする。新しいコンポーネントをインストールすることはない。
DSETUP_USEROLDERFLAG | -14 を返せる。これは、インストールされている DirectX のバージョンがインストールするバージョンよりも新しいことを意味する。

戻り値

この関数が成功した場合、以下の成功コードのうちの 1 つを返す。

DSETUPERR_SUCCESS | インストールが成功した。
DSETUPERR_SUCCESS_RESTART | インストールが成功したが、変更内容を有効にするためにシステムを再起動する必要がある。

失敗した場合は、エラー コードを返す。戻り値については、「戻り値」を参照すること。

注意

セットアップ プログラムで DirectXSetup 関数を使用する前に、システムに最低 15 MB の空きディスク領域があることを確認すること。これは適切なファイルをセット アップするために DirectX が必要とする最大領域である。ただし、システムに DirectX ファイルが既に存在する場合は必要ない。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dsetup.h で宣言。
インポート ライブラリ : dsetup.lib を使用。


DirectXSetupCallbackFunction

オプションでセットアップ プログラムに設定するコールバック関数のプレースホルダ名である。設定されたコールバック関数は、セットアップ プロセスの各ステップごとに一度ずつ呼び出される。

DWORD DirectXSetupCallbackFunction(
  DWORD  Reason,
  DWORD  MsgType,
  char  *szMessage,
  char  *szName,
  void  *pInfo
);

パラメータ

Reason
コールバックの理由。次のいずれかの値を取る。
DSETUP_CB_MSG_BEGIN_INSTALL
DirectXSetup が Microsoft® DirectX® コンポーネントとデバイス ドライバのインストールを始めようとしている。
DSETUP_CB_MSG_BEGIN_INSTALL_DRIVERS
DirectXSetup がデバイス ドライバのインストールを始めようとしている。
DSETUP_CB_MSG_BEGIN_INSTALL_RUNTIME
DirectXSetup が DirectX コンポーネントのインストールを始めようとしている。
DSETUP_CB_MSG_BEGIN_RESTORE_DRIVERS
DirectXSetup が以前のドライバの復元を始めようとしている。
DSETUP_CB_MSG_CANTINSTALL_BETA
Microsoft Windows® 95 オペレーティング システムのベータ バージョンが検出された。DirectX コンポーネントまたはデバイス ドライバをインストールできない。
DSETUP_CB_MSG_CANTINSTALL_NOTWIN32
Windows 32 ビット以外のオペレーティング システムが検出された。DirectX は Windows3.x と互換性はない。
DSETUP_CB_MSG_CANTINSTALL_NT
DirectX コンポーネントまたはデバイス ドライバは、バージョン 4.0 より前の Microsoft Windows NT® オペレーティング システムにはインストールできない。
DSETUP_CB_MSG_CANTINSTALL_UNKNOWNOS
オペレーティング システムが既知のものではない。DirectX コンポーネントまたはデバイス ドライバをインストールできない。
DSETUP_CB_MSG_CANTINSTALL_WRONGLANGUAGE
DirectX コンポーネントまたはデバイス ドライバを、Windows で使用されている言語にローカライズすることができない。
DSETUP_CB_MSG_CANTINSTALL_WRONGPLATFORM
DirectX コンポーネントまたはデバイス ドライバが別の種類のコンピュータ用のものである。
DSETUP_CB_MSG_CHECK_DRIVER_UPGRADE
ドライバのアップグレードが必要と考えられる。ユーザー側の確認を推奨する。
DSETUP_CB_MSG_FILECOPYERROR
DirectX コンポーネントまたはデバイス ドライバ ファイルのセットアップがコピー プロセス中に失敗した。
DSETUP_CB_MSG_INTERNAL_ERROR
内部エラーが発生した。DirectX コンポーネントまたはデバイス ドライバのセットアップが失敗した。
DSETUP_CB_MSG_NOMESSAGE
表示するメッセージがない。コールバック関数は戻らなければならない。
DSETUP_CB_MSG_NOTPREINSTALLEDONNT
使用している Microsoft Windows NT または Microsoft Windows 2000 のバージョンに DirectX コンポーネントまたはデバイス ドライバがインストールできない。
DSETUP_CB_MSG_OUTOFDISKSPACE
DirectX コンポーネントのセットアップがディスク領域不足のために失敗した。
DSETUP_CB_MSG_PREINSTALL_NT
使用している Windows NT または Windows 2000 のバージョンに既に DirectX がインストールされている。
DSETUP_CB_MSG_SETUP_INIT_FAILED
DirectX コンポーネントまたはデバイス ドライバのセットアップが失敗した。
MsgType
メッセージ ボックスの表示を制御するフラグ。これらのフラグは、MessageBox 関数に渡すことができる。MsgType が 0 のときは例外で、セットアップ プログラムはステータス情報を表示することはできるが、ユーザーからの入力待ちをしてはいけない。
szMessage
エラー メッセージまたはステータス情報を含むローカライズ文字列へのポインタ。これらの文字列は、MessageBox 関数で作成されるダイアログ ボックスに表示できる。
szName
Reason パラメータが DSETUP_CB_MSG_CHECK_DRIVER_UPGRADE でない限り NULL である。この場合、szName にはアップグレードするドライバの名前へのポインタが入る。
pInfo
アップグレード情報を含む構造体のアドレスへのポインタ。Reason が DSETUP_CB_MSG_CHECK_DRIVER_UPGRADE の場合は、セットアップ プログラムがドライバのアップグレード中で、ユーザーにアップグレードを行うべきかどうかを問い合わせている。この場合、pInfo は、アップグレードに関する情報を格納する DSETUP_CB_UPGRADEINFO 構造体を示す。

戻り値

1 つの例外を除いて、戻り値は MessageBox 関数から返される戻り値と同じでなければならない。この関数が 0 を返した場合、DirectXSetup 関数は デフォルトの動作で DirectX コンポーネントまたはドライバのアップグレードを実行する。

注意

DirectXSetupCallbackFunction の名前はセットアップ プログラムから与えられる。DirectXSetupSetCallback 関数は、DirectSetup にコールバック関数のアドレスを渡す際に使用される。

MsgType が 0 の場合、セットアップ プログラムでステータス情報を表示できるが、ユーザーからの入力待ちをしてはいけない。この場合、関数は IDOK を返す。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dsetup.h で宣言。
インポート ライブラリ : ユーザー定義。

参照

MessageBox、DirectXSetupSetCallback、セットアップのカスタマイズ


DirectXSetupGetVersion

現在インストールされている Microsoft® DirectX® コンポーネントのバージョン番号を取得する。

INT WINAPI DirectXSetupGetVersion(
  DWORD  *pdwVersion,
  DWORD  *pdwRevision
);

パラメータ

pdwVersion
バージョン番号を受け取る変数のアドレスへのポインタ。バージョン番号が不要の場合は NULL でも可。
pdwRevision
リビジョン番号を受け取る変数のアドレスへのポインタ。リビジョン番号が不要の場合は NULL でも可。

戻り値

成功した場合は、0 以外の値を返す。

失敗した場合は、0 を返す。

注意

DirectXSetupGetVersion 関数は、DirectXSetup 関数を呼び出す前後にバージョン番号とリビジョン番号を取得するために使用する。DirectXSetup の呼び出し前にこの関数を呼び出した場合は、現在インストールされている DirectX コンポーネントのバージョン番号とリビジョン番号が与えられる。DirectXSetup の呼び出し後で、しかもコンピュータを再起動する前にこの関数を呼び出した場合は、コンピュータを再起動した後に有効になる DirectX コンポーネントのバージョン番号とリビジョン番号が与えられる。

pdwVersion パラメータに格納されるバージョン番号は、メジャー バージョン番号とマイナー バージョン番号から成る。関数から返されたメジャー バージョン番号は、DWORD の上位 16 ビットに格納される。関数から返されたマイナー バージョン番号は、DWORD の下位 16 ビットに格納される。バージョン番号と実際のバージョンは次のように対応している。

DirectX のバージョン | pdwVersion によってポイントされる値
DirectX 1 | 0x00000000
DirectX 2 | 0x00000000
DirectX 3 | 0x00000000
DirectX 5.0 | 0x00040005
DirectX 6.0 | 0x00040006
DirectX 7.0 | 0x00040007
DirectX 8.0 | 0x00040008

DirectX のバージョン 4 は存在しない。

pdwRevision パラメータに格納されるバージョン番号は、リリース番号とビルド番号から成る。関数から返されたリリース番号は、DWORD の上位 16 ビットに格納される。関数から返されたビルド番号は、DWORD の下位 16 ビットに格納される。

次のサンプル コードは、DirectXSetupGetVersion から返された情報を取り出して使用する方法を示したものである。

DWORD dwVersion;
DWORD dwRevision;
if (DirectXSetupGetVersion(&dwVersion, &dwRevision))
{
    printf("DirectX version is %d.%d.%d.%d\n",
           HIWORD(dwVersion), LOWORD(dwVersion),
           HIWORD(dwRevision), LOWORD(dwRevision));
}

バージョン番号とリビジョン番号は、64 ビット データに結合して比較することができる。このとき、バージョン番号は上位 32 ビットに、リビジョン番号は下位 32 ビットにそれぞれ格納される。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dsetup.h で宣言。
インポート ライブラリ : dsetup.lib を使用。

参照

DirectXSetup


DirectXSetupSetCallback

DirectXSetup から周期的に呼び出されるコールバック関数にポインタをセットする。コールバック関数は、セットアップの進行状況の通知と、アプリケーションのセットアップ プログラム用のカスタム ユーザー インターフェイスの実装に使用することができる。詳細については、DirectXSetupCallbackFunction を参照すること。セットアップ プログラムがコールバック関数を与えない場合、DirectXSetupSetCallback は呼び出されない。

INT WINAPI DirectXSetupSetCallback(
  DSETUP_CALLBACK  Callback
);

パラメータ

Callback
コールバック関数のアドレス。

戻り値

現状では 0 を返す。

注意

コールバック関数を設定するには、DirectXSetup を呼び出す前に DirectXSetupSetCallback を呼び出さなければならない。

DirectXSetupSetCallback に渡されるコールバック関数の名前は、セットアップ プログラムによって与えられる。ただし、DirectXSetupCallbackFunction で与えられるプロトタイプに適合するものでなければならない。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dsetup.h で宣言。
インポート ライブラリ : dsetup.lib を使用。

参照

DirectXSetupCallbackFunction、DirectXSetup


DirectXUnRegisterApplication

DirectPlayLobby 対応アプリケーションの登録を削除する。

int WINAPI DirectXUnRegisterApplication(
  HWND   hWnd,
  LPGUID lpGUID
);

パラメータ

hWnd
親ウィンドウのハンドル。デスクトップが親ウィンドウのときは、このパラメータに NULL を設定する。
lpGUID
削除対象となる Microsoft® DirectPlay アプリケーションの GUID のアドレス。

戻り値

成功した場合は、TRUE を返す。これは登録の削除に成功したことを示す。

失敗した場合は、FALSE を返す。

注意

DirectXUnRegisterApplication 関数では、Dsetup.dll と Dsetup32.dll の両方が必要となる。これら 2 つのファイルはシステムにインストールされていないが、SDK に含まれている。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dsetup.h で宣言。
インポート ライブラリ : dsetup.lib を使用。

参照

DirectXRegisterApplication


構造体

ここでは、Microsoft® DirectSetup® で使用される以下の構造体について説明する。

  • DIRECTXREGISTERAPP
  • DSETUP_CB_UPGRADEINFO

注 : Microsoft DirectX® 構造体のメモリはすべて、使用前に 0 に初期化しなければならない。また、dwSize メンバを持つすべての構造体は、使用前にこのメンバを構造体のサイズ (バイト単位) に設定しなければならない。


DIRECTXREGISTERAPP

DirectPlayLobby 対応アプリケーションに必要なレジストリ エントリを格納する。

typedef struct _DIRECTXREGISTERAPP {
    DWORD  dwSize;
    DWORD  dwFlags;
    LPSTR  lpszApplicationName;
    LPGUID lpGUID;
    LPSTR  lpszFilename;
    LPSTR  lpszCommandLine;
    LPSTR  lpszPath;
    LPSTR  lpszCurrentDirectory;
} DIRECTXREGISTERAPP, *PDIRECTXREGISTERAPP, *LPDIRECTXREGISTERAPP;

メンバ

dwSize
構造体の大きさ。DIRECTXREGISTERAPP 構造体の大きさに初期化されなければならない。
dwFlags
予約ビット。
lpszApplicationName
アプリケーションの名称。
lpGUID
アプリケーションのグローバル ユニーク識別子 (GUID)。
lpszFilename
呼び出される実行ファイル名。
lpszCommandLine
実行ファイルのコマンドライン引数。
lpszPath
実行ファイルのパス。
lpszCurrentDirectory
カレント ディレクトリ。通常は lpszPath と同じ。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dsetup.h で宣言。


DSETUP_CB_UPGRADEINFO

パラメータとしてアプリケーションで定義した DirectXSetupCallbackFunction へ渡される。この構造体には、Reason パラメータが DSETUP_CB_MSG_CHECK_DRIVER_UPGRADE のときだけ、有効な情報が格納される。コールバック関数は、この構造体を使用して、実行するアップグレードに関するステータス情報を取得することができる。

typedef struct _DSETUP_CB_UPGRADEINFO {
    DWORD UpgradeFlags;
} DSETUP_CB_UPGRADEINFO;

メンバ

UpgradeFlags
アップグレード ステータスは 1 つ以上のフラグで示される。次の各値が定義されている。
DSETUP_CB_UPGRADE_CANTBACKUP
古いシステム コンポーネントをバック アップできない。アップグレードは実行可能だが、アップグレード後のコンポーネントやドライバの復元はできない。
DSETUP_CB_UPGRADE_DEVICE_ACTIVE
デバイスは現在使用中である。
DSETUP_CB_UPGRADE_DEVICE_DISPLAY
アップグレード対象のデバイス ドライバは、ディスプレイ デバイス用のドライバである。
DSETUP_CB_UPGRADE_DEVICE_MEDIA
アップグレード対象のデバイス ドライバは、メディア デバイス用のドライバである。
DSETUP_CB_UPGRADE_FORCE
コンポーネントがアップグレードされなければ、Microsoft® Windows® が正常に機能しない恐れがある。アップグレードは実行される。
DSETUP_CB_UPGRADE_HASWARNINGS
Microsoft DirectSetup® でこのデバイスのドライバをアップグレードすることはできるが、システム上の 1 つ以上のプログラムに影響を与える恐れがある。影響を受けると見られるプログラムの名前は szMessage に格納される。アップグレードは推奨されない。
DSETUP_CB_UPGRADE_KEEP
このデバイス ドライバをアップグレードすると、システムに障害が発生する恐れがある。アップグレードは許可されない。
DSETUP_CB_UPGRADE_SAFE
DirectSetup はこのデバイス ドライバを安全にアップグレードできる。アップグレードが推奨される。安全なアップグレードとは、Windows の動作に悪影響を与えないことを示す。ハードウェアに依存する一部のプログラムについては、悪影響が及ぶ可能性がある。
DSETUP_CB_UPGRADE_UNKNOWN
このデバイスの既存のドライバが認識できない。この値の状況は頻繁に発生する。アップグレードすることにより、このデバイスの使用に悪影響を与える可能性がある。アップグレードを実行しないよう強く推奨する。

注意

UpgradeFlags からアップグレード タイプ (FORCE、KEEP、SAFE、または UNKNOWN) を取得するには、値 DSETUP_CB_UPGRADE_TYPE_MASK を使用する。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dsetup.h で宣言。

参照

DirectXSetupCallbackFunction


戻り値

DirectXSetup 関数は以下の値を返す。この関数では標準 COM エラーを返すこともできる。

DSETUPERR_SUCCESS
セットアップが成功した。再起動の必要はない。
DSETUPERR_SUCCESS_RESTART
セットアップが成功した。再起動する必要がある。
DSETUPERR_BADSOURCESIZE
ファイル サイズを検証できなかったか、誤りであった。
DSETUPERR_BADSOURCETIME
ファイルの日付およびタイムを検証できなかったか、誤りであった。
DSETUPERR_BADWINDOWSVERSION
システムで実行中の Microsoft Windows® は、Microsoft® DirectX® ではサポートされない。
DSETUPERR_CANTFINDDIR
セットアップ プログラムで作業ディレクトリが見つからなかった。
DSETUPERR_CANTFINDINF
必要な .inf ファイルが見つからなかった。
DSETUPERR_INTERNAL
内部エラーが発生した。
DSETUPERR_NEWERVERSION
DirectX の上位バージョンが既にインストールされている。上位バージョンが上書きされることはなく、以前のバージョン用に記述されたアプリケーションとも完全に互換性があるため、アプリケーションは安全にこのエラーを無視できる。
DSETUPERR_NOTADMIN
カレント ユーザーが管理者権限を持っていない。Windows 2000 システムでは、セットアップの際に管理者権限が必要な場合がある。
DSETUPERR_NOCOPY
ファイルのバージョンを検証できなかったか、誤りであった。
DSETUPERR_NOTPREINSTALLEDONNT
システムの Windows NT® または Windows 2000 のバージョンに、DirectX の最新バージョンが含まれていない。DirectX の古いバージョンが存在するか、DirectX のどのバージョンも存在しないか、どちらかの可能性がある。
DSETUPERR_OUTOFDISKSPACE
セットアップ プログラムによるインストール中にディスク領域が足りなくなった。
DSETUPERR_SOURCEFILENOTFOUND
必要なソース ファイルのうちのいずれかが見つからなかった。
DSETUPERR_UNKNOWNOS
サポートされていないバージョンのオペレーティング システムである。
DSETUPERR_UNSUPPORTEDPROCESSOR
サポートされていないプロセッサ タイプである。DirectX 8 では、Pentium または K6 互換プロセッサおよびこれら以降のプロセッサのみをサポートしている。
DSETUPERR_USERHITCANCEL
アプリケーションのインストールが完了する前に、[Cancel] ボタンが押された。


DirectSetup サンプル

Microsoft® DirectSetup® の使用方法および機能を説明するサンプルとして、次のプログラムが提供されている。

  • Dinstall サンプル (C/C++)
  • DXVBSetup サンプル (Microsoft Visual Basic)

DirectX サンプルには Microsoft Visual C++® のプロジェクト ワークスペース ファイルが含まれているが、各自の開発環境で正しくコンパイルできるようにほかの設定を確認する必要がある場合がある。詳細については、「DirectX のサンプルおよびその他の DirectX アプリケーションのコンパイル」を参照すること。


Dinstall サンプル

説明

Dinstall は、Microsoft® DirectSetup® 関数を使って Microsoft DirectX® サブシステムをインストールするサンプルである。ここでは、コールバック関数を使って、カスタム インターフェイス (この場合はシンプルなモードレス ダイアログ ボックス) 経由でメッセージの表示とユーザー入力の取得を行う例を示している。

パス

ソース ファイル :(SDK ルート)\Samples\Multimedia\Misc\DXInstall

ユーザーズ ガイド

  1. DirectX SDK CD の \Redist\DirectX8 フォルダの内容をすべて Dinstall.exe と同じフォルダにコピーする。
  2. 開発環境の作業ディレクトリもこのフォルダに設定する。 (Microsoft Visual C++® では、[Project Settings] ダイアログ ボックスの [Debug] ページにこの設定がある)。
  3. プログラムを実行し、[File] メニューの [Start Install] をクリックする。DirectSetup は、DirectX の模擬インストールを実行し (「プログラミング上の注意」を参照)、モードレス ダイアログ ボックスに進捗状況を表示する。[Options] メニューでは、表示するメッセージ レベルを変更できる。ただし、模擬インストールのみを行う場合は、問題発生メッセージやアップデート メッセージは表示されない。
  4. [File] メニューの [Get Version] をクリックする。システムに現在インストールされている DirectX のバージョン番号およびリビジョン番号が表示される。

プログラミング上の注意

デフォルトでは、プログラムは DirectXSetup 関数に DSETUP_TESTINSTALL を渡す。これは、実際にファイルはコピーされず、レジストリの変更も行われないことを示す。実際にインストールを行うには、このフラグを関数呼び出しから削除する。

Dinstall では、インストール進捗状況の監視やメッセージのインターセプトにコールバック関数を使用している。ユーザーが指定した警告レベル (g_fStatus で追跡) に応じて、メッセージを無視したり、モードレス ダイアログ ボックスにメッセージを表示したりできる。ユーザー入力が必要な場合は適切なボタンが表示され、いずれかのボタンが押されるまで GetReply 関数がメッセージ キューを監視する。


DXVBSetup サンプル

ここでは、Microsoft® Visual Basic® でのアプリケーション開発について説明する。C++ については、「Dinstall サンプル」を参照すること。


用語集

ここでは、Microsoft® DirectX® SDK のドキュメントで使用される技術用語を解説する。

A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z


A

アルファ チャネル (alpha channel)
アルファ値によって定義される、画像の不透明度。不透明度を定義するアルファ値は、ピクセル単位にほかの色成分と共に与えられるか (ARGB などの場合)、独立したアルファ サーフェス内でピクセル単位に与えられるか、またはサーフェス全体に固定の値で与えられる。
アルファ色成分 (alpha color component)
32 ビット カラーの不透明度を決める部分。32 ビット カラーの場合、アルファ値は、ピクセル単位にほかの色成分と共に与えられる (ARGB など)。まれに、独立したアルファ サーフェス内にピクセル単位のアルファ値が格納されている画像のアルファ値を指して 買Aルファ成分� という場合もある。
アルファ定数 (alpha constant)
サーフェス全体に適用される不透明度 (アルファ値)。
アルファ エッジ ブレンド (alpha edge blend)
アルファ ブレンディング (およびアルファ チャネル情報) の用法の 1 つ。 ピクセルの適用範囲に基づいてエッジを混色することにより、エイリアシングを減少させる方法である。
アンビエント属性 (ambient property)
環境光属性、ライトからの角度に依存せず反射するマテリアル属性。 オブジェクトの向き、位置、表面特性などに関係なく、シーンのすべてを照らす光源およびマテリアル属性。シーンのすべての場所を同じ光源で照らすため、アンビエント光源に置かれたフレームの位置や向きは重要ではない。複数のアンビエント光源がシーン内で組み合わされる。
異方性フィルタリング (anisotropic filtering)
異方性の歪みを補正するミップマップ フィルタリング モードの 1 つ。
異方性 (anisotropy)
表面が表示面に対して角度を持って位置する 3D オブジェクトのイメージに生じる、目に見える歪み。異方性はテクスチャ空間へ逆マップされたスクリーン ピクセルの伸び (長さ÷幅) として計測できる。
配列オブジェクト (array object)
1 つの配列にまとめられたオブジェクト群。配列オブジェクトを使用すると、一連のオブジェクトすべてに何らかの処理を行う場合の操作が簡単になる。配列オブジェクトを扱うことができる COM インターフェイスには、GetElement と GetSize というメソッドが用意されている。この 2 つのメソッドはそれぞれ、配列要素へのポインタの取得、および配列サイズの取得を行う。
アタッチ (attach)
複数の DirectDrawSurface オブジェクトを接続して、Z バッファ付きの 3D ページ プリッピングをサポートする場合などに必要となる複合構造体にすること。アタッチは双方向的なものではない。 サーフェスをそのサーフェス自身にアタッチすることはできない。また、(システム メモリ内で) エミュレートされているサーフェスを、エミュレートによらないサーフェスにアタッチすることもできない。2 つのサーフェスをアタッチする場合、片方のサーフェスがテクスチャ マップでない限り、アタッチされるサーフェスどうしは同一サイズでなければならない。
アタッチ状態 (attached)
システムに物理的に接続されている状態。デバイスは、インストールされていても、アタッチ状態にはない場合もある。
アタック (attack)
マグニチュードが基本レベル (維持期間レベル) に達してフォース フィードバック エフェクトが始まるときの初期期間。


B

バック バッファ (back buffer)
画面に表示されていないサーフェス。 アプリケーションは、フロント バッファのイメージが画面に表示されている間に、ビットマップやその他のイメージをバック バッファに描き込むことができる。
後方クリップ面 (back clipping plane)
視錐台の奥行きの限界。 この向こう側にあるオブジェクトはレンダリングされない。「前方クリップ面」を参照すること。
バンク セレクト (bank select)
MIDI のコントロール チェンジ。 異なるグループ (バンク) からの音色選択を可能にする。 各バンクの識別には、2 バイト コードが使用される。
ビルボード (billboard)
1 つの面がビューアに向くような方向で 3D シーンへ挿入されたプリミティブ。テクスチャ (通常は、アニメーションされたスプライト) をビルボードに適用すると、3D オブジェクトがシーン上に現れる。
ビルボーディング (billboarding)
シーン上の 3D オブジェクトの外観をシミュレートする 2D 技法。アプリケーションは、プリミティブ (通常は矩形) を 1 つの面がビューアに向くような方向でシーンに挿入し、1 つのテクスチャまたは一連のテクスチャをそこへ適用する。適用されたテクスチャは、アニメーションされた 3D オブジェクトに見える。
ブレンディング係数 (blend factor)
テクスチャ ブレンディングにおいて、各色成分がどのように混色されるかを示す係数。
ブレンディング モード (blend mode)
テクスチャが適用先のサーフェスの色とどのように混色されるかを決定するアルゴリズム。
ブレンディング ステージ (blending stage)
テクスチャ カスケードの 1 ステップ。ブレンディング ステージは、1 つのテクスチャと、複数のテクスチャを混色する際に使用される一連のテクスチャ ブレンディング処理から成る。
ブリット (blit)
ビットのブロック転送。
境界チェック (bounds checking)
画面上のイメージが画面の境界内に表示されているかどうかをチェックする処理。
バンプ マッピング (bump mapping)
3D シーンでサーフェスが凸凹した外観をシミュレートする技法。深さの変化がテクスチャ内に格納され、標準のテクスチャ ブレンディング技術を使用してプリミティブに適用される。


C

カメラ (camera)
表示位置と方向を定義するため、ビューポートが用いる Direct3DRMFrame オブジェクト。ビューポートは、カメラ フレームの正の z 軸上にある可視オブジェクトだけを、y 軸上の正方向にレンダリングする。
カメラ空間 (camera space)
視点が原点に位置し、そこから z 軸の正の方向を見ている基準フレーム。オブジェクトの座標は、ビュー トランスフォームによりワールド空間からカメラ空間へとトランスフォームされる。
クライアント/サーバー セッション (client/server session)
サーバーだけがセッションの完全な状態を格納する Microsoft® DirectPlay® セッション。 各クライアントはセッション状態のサブセットだけを保持する。各クライアントは、サーバーからそのコンピュータに関する情報だけを受け取る。あるコンピュータで何かを変更した場合は、サーバーにその変更を伝える。その後、サーバーは変更についてどのクライアントに通知すべきかを判断する。「ピアツーピア セッション」を参照すること。
クリップ リスト (clip list)
サーフェスの可視領域を示す矩形のリスト。既に DirectDrawClipper オブジェクトにウィンドウ ハンドルが結び付けられている場合は、クリップ リストを設定することはできない。
クリッパー (clipper)
DirectDrawClipper オブジェクトのこと。
CODEC
圧縮伸張システム (COmpressor and DECompressor) を表す略語。
衝突検出 (collision detection)
2 つのイメージに画面上の同じ位置を共有するピクセルがないか判断する処理。「ヒット検出」を参照すること。
カラー キー (color key)
透明エフェクトや半透明エフェクトに使用される色を示す値。たとえば、ハードウェアのブリット機能を使用した場合、矩形領域内のカラー キーとして設定された値を持つピクセル以外のすべてのピクセルがブリットされる。 これは、矩形でないスプライトをサーフェス上に作成する。
色空間 (color space)
3 つ以上の座標値で色を表すモデルのこと。色空間モデルは、色の各成分を、3 次元以上のデカルト座標系にマッピングする。色空間は、色のコード化と可視化に複数の手法を用いる場合もある。最も一般的な色空間モデルは、RGB と YUV の 2 つである。
色空間の変換 (color-space conversion)
異なる色空間間で色を変換すること。通常は、ビデオ ソースの YUV カラーから表示用の RGB 色への変換のことをいう。
カラー テーブル (color table)
n 色のカラー値の配列 (通常は RGB 三原色)。
複合サーフェス (complex surface)
ルート サーフェスにアタッチされている複数の DirectDrawSurface オブジェクトをまとめて指す用語。複合サーフェス構造体は、ルートを破棄することによってしか破棄できない。
制御セグメント (control segment)
再生の一定局面を制御するミュージカル セグメント。通常はプライマリ セグメントであるが、制御セグメントとしてセカンダリ セグメントを指定することができる。
カリング (culling)
レンダリング処理で 3D プリミティブの背面等を省くこと。
カーブ (curve)
Microsoft® DirectMusic® で、開始と終了の値を持つ一連のイベント。ボリュームのフェードなど。


D

暗色光 (dark light)
シーンからライトを除去する光源。 暗色光は、ライトの色に負の値を指定することにより作成できる。
DCI
Display Control Interface (ディスプレイ コントロール インターフェイス) の略。DCI は、Intel および Microsoft® により定義されたインターフェイスで、ビデオ メモリに直接アクセスすることによって、より高いグラフィックス パフォーマンスを提供する。
デッドバンド (deadband)
フォース フィードバック軸のオフセットの周囲にある、条件が作用しない領域。
デッド ゾーン (dead zone)
軸の物理的な動作範囲内で、軸が中心に位置していると見なされる領域。
デカール (decal)
ビジュアル オブジェクトとして直接レンダリングされるテクスチャ。ビューポートに位置を合わせた矩形にレンダリングされる。
転送先カラー キー (destination color key)
ブリットの場合は置き換えられる色、オーバーレイの場合は転送先のサーフェス上で覆い隠される色のこと。
デバイス ウィンドウ (device window)
Microsoft® DirectDraw® が表示用に使用するアプリケーション ウィンドウ。アプリケーションは、与えられたコンピュータにアタッチされている各表示デバイスに 1 つずつデバイス ウィンドウを持つことができる。「フォーカス ウィンドウ」を参照すること。
ディレクショナル (directional)
フレームにアタッチされるが、すべてのオブジェクトを同じ輝度で照らす光源の記述。 あたかも光源がオブジェクトから無限の距離に位置するかのようなエフェクトを与える。ディレクショナル ライトは、向きは持つが位置を持たず、一般に、太陽のような遠く離れた光源をシミュレートするために用いられる。
DirectPlay アドレス (DirectPlay address)
Microsoft® DirectPlay® がロビー サーバー、アプリケーション、DirectPlay、およびサービス プロバイダの間でアドレス情報を渡すために使用するデータ形式。DirectPlay アドレスは、グローバル ユニーク識別子 (GUID) でタグ付けされた一連の可変長のデータ チャンクである。 GUID は、DirectPlay に必要なアドレス情報をすべて提供する。アドレス情報の例として、サーバーのネットワーク アドレス、プレーヤーのネットワーク アドレス、プレーヤーの電子メール名、セッションのネットワーク アドレスなどが挙げられる。
DLS
DownLoadable Sounds (ダウンロード可能なサウンド) の略。ソフトウェアに格納されているデジタル サンプルからウェーブ サウンドを合成する機能についての標準。MIDI Manufacturers Association から DLS レベル 1 およびレベル 2 の標準が発表されている。
DMO
Microsoft® DirectX® Media Object (Microsoft® DirectX® メディア オブジェクト) の略。クライアントによって割り当てられたバッファからのマルチメディア データ ストリームを処理する COM オブジェクト。


E

エミッション属性 (emissive property)
自己発色属性、マテリアル (素材) のライトに依存しない色属性を示すマテリアル属性、発光または発色。マテリアルの反射および発光を決定する属性は 4 つあるが、エミッション属性はそのうちの 1 つである。「アンビエント属性」、「ディフューズ属性」、および「スペキュラ属性」を参照すること。
エミッション設定 (emissive setting)
「エミッション属性」を参照すること。
有効フレーム (enable frame)
光源を適用することができるフレーム。
エンベロープ (envelope)
フォース フィードバックで、初期 (アタック) と終期 (フェード) でのマグニチュードを変更することにより、エフェクトの形状を定義する一連の値。

オーディオでは、サウンドの振幅またはピッチの形状を定義する一連の値。DLS レベル 1 では、アタック、ディケイ、サステイン、リリース (ADSR) の 4 セグメント エンベロープが定義されている。DLS レベル 2 では、ディレイ、アタック、ホールド、ディケイ、サステイン、リリース (DAHDSR) の 6 セグメントが定義されている。

偶数フィールド (even field)
ビデオ フレームを構成する奇数/偶数のフィールド セットの 2 つ目のフィールド。フィールド 2 とも呼ばれる。
実行バッファ (execute buffer)
3D シーンを記述する、すべての情報が格納されていて独立した情報パケット。実行バッファには、頂点のリストが格納され、それに続いて命令ストリームが格納される。命令ストリームは、オペレーション コード (オペコード) と、そのオペコードによる処理の対象となるデータから成る。


F

面 (face)
メッシュ内の単一のポリゴン。
フェード (fade)
フォース フィードバック エフェクトの中央部分 (維持期間) からフォース フィードバック エフェクトが終わるまでの期間。
フォールオフ (falloff)
スポットライトの内側の円錐面と外側の円錐面との間の光の減衰。
フィールド (field)
ビデオ ストリーム内の単一のビデオ フレームの半分に相当するデータ。各フィールドには、1 つおきの走査線のデータが格納される。フィールドの送受信は、奇数フィールド、偶数フィールドの順で行われる。
フィールド極性 (field polarity)
フィールドが偶数フィールドと奇数フィールドのどちらであるかを表す特性。奇数フィールドでは、走査線中に VREF の立ち下がりエッジは発生しない。偶数フィールドでは、走査線中に VREF の立ち下がりエッジが発生する。
フリマリング (flimmering)
z 値の分離が不完全なため、転写時に 3D プリミティブ上に発生する表示のちらつき。背面のテクスチャの一部のピクセルが前面のテクスチャ上にレンダリングされたり、その逆が起こったりする。
フリップ (flip)
バック バッファとフロント バッファのアドレスをスワップ (交換) すること。これにより、バック バッファ内のイメージをフロント バッファへコピーまたはブリットする必要がない。その結果、バック バッファ内にあったイメージを効率よく画面に表示できる。
フリッピング チェーン (flipping chain)
相互に接続されており、フリップ可能な一連のサーフェス。「フリップ」を参照すること。
フリッピング サーフェス (flipping surface)
フリッピング可能なメモリ。「フリップ」を参照すること。
フォーカス ウィンドウ (focus window)
Microsoft® DirectDraw® がウィンドウ メッセージを受け取るために使用するアプリケーション ウィンドウ。 実際に画面に表示される場合も、表示されない場合もある。フォーカス ウィンドウのメッセージ ハンドラは、DirectDraw により転送された入力メッセージを受け取る。アプリケーションが持つことのできるフォーカス ウィンドウは 1 つだけである。「デバイス ウィンドウ」を参照すること。
フレーム (frame)
シーン上のオブジェクトの配置の基になる非表示のボックス。シーン上でのオブジェクトの位置は、適切な基準フレームに対する空間的な関係を指定することによって決めることができる。ビジュアル オブジェクトは、その位置や向きをフレームから取得する。

動画やアニメーション内の単一のイメージも同様である。

フロント バッファ (front buffer)
グラフィックス アダプタによって変換され、モニタまたはほかの出力デバイスに表示されるメモリの矩形。
前方クリップ面 (front clipping plane)
視錐台の前面の限界。前方クリップ面よりもカメラ寄りにあるオブジェクトはレンダリングされない。前方クリップ面の高さにより、視野が決まる。「後方クリップ面」を参照すること。


G

ゲンロッキング (genlocking)
2 つのビデオ信号の同期を取る処理。ゲンロッキングされた信号は元の信号と同期が取れているため、元の信号とミキシングすることができ、ディゾルブ、ワイプなどのトランジション エフェクトが可能となる。
グリッド (grid)
拍 (ビート) の小分割。ビートごとのグリッド数は、Microsoft® DirectMusic® の拍子記号の一部である。
グルーブ レベル (groove level)
スタイルの再生中にミュージックに指定される値。グルーブ レベルによって、指定された時間に選択できるパターンが決定される。オーサーは、広範囲のグルーブ レベルを各パターンに割り当てる。
グループ (group)
プレーヤーの論理的な集まり。Microsoft® DirectPlay® は、セッション内でグループをサポートする。プレーヤーのグループを作成することにより、アプリケーションはグループに単一のメッセージを送信でき、グループ内のすべてのプレーヤーがそのメッセージを受信できる。グループは、ネットワークのマルチキャスト機能をアプリケーションに公開する手段になる。

グループは、セッション内のプレーヤーをまとめるために使用できる。プレーヤーは、1 つ以上のグループに属すことができる。DirectPlay では、グループやそのメンバシップを管理することができる。


H

HAL
Hardware Abstraction Layer (ハードウェア アブストラクション レイヤ) の略。HAL は、ハードウェアおよびデバイス ドライバのメカニズムにより構成され、個々のデバイス固有の実装の詳細をアプリケーションから隠す働きを担う。使用しているハードウェアが、アプリケーションから要求された機能を実装していなかった場合は、その機能をソフトウェアによりエミュレートする。
ハードウェア ブリット (ブロック転送) (hardware blitter)
ディスプレイ アダプタに組み込まれており、効果的なブリット処理を行うハードウェア コンポーネント。
HEL
Hardware Emulation Layer (ハードウェア エミュレーション レイヤ) の略。HEL は、ハードウェアがサポートしていない機能をソフトウェアによりエミュレートする。
HID
Human Interface Device (ヒューマン インターフェイス デバイス) の略。人間がコンピュータを制御できるデバイスを示す USB クラス。
ヒット検出 (hit detection)
「衝突検出」を参照すること。
ホスト (host)
Microsoft® DirectPlay® で、DPID_SYSMSG という ID を持つ仮想プレーヤー。ホストは、システム メッセージやセッション内のすべてのプレーヤーに送られるメッセージを管理する。
HREF
Horizontal REFresh (水平リフレッシュ) の略。HREF 信号は、ビデオ ストリーム内で、ディスプレイが新しい走査線を開始しようとしていることを知らせるときにアクティブになる。「VREF」を参照すること。
HRTF
Head-Related Transfer Function (頭部伝達関数) の略。異なる方向からくる音のピッチやタイミングに対してリスナーの生理機能が及ぼす影響の数学的表現。


I, J, K

インデックス パレット (index palette)
ほかのパレット オブジェクトのインデックスとなるエントリを持つ DirectDrawPalette オブジェクト。
IPX サービス プロバイダ (IPX service provider)
Internetwork Packet Exchange (IPX) プロトコルを使用してローカル エリア ネットワーク (LAN) 上で通信を行うために Windows Sockets を使用するサービス プロバイダ。このサービス プロバイダは、非保証のメッセージ交換だけをサポートする。1 台のコンピュータは、IPX を使用して 1 つの Microsoft® DirectPlay® セッションのみのホストとして機能する。
IRE 率 (IRE scale)
International Radio Engineers の割合。IRE は、ある要素を全要素にコピーするビデオ信号の輝度を定義する 0 ～ 100 までの範囲の値。IRE 値が高くなると、ビデオ信号の輝度が増加する。7.5 IRE の輝度ユニット (National Television System Committee (NTSC) 信号の黒によるカットオフのしきい値) では、NTSC ディスプレイ デバイスの電子銃はカットオフされ、画面にはイメージが表示されない。


L

遅延時間 (latency)
応答遅延時間。たとえば Microsoft® DirectSound® では、サウンド バッファが再生されてから実際にサウンドがスピーカから出てくるまでの間の時間である。Microsoft DirectPlay® では、パケットが指定された宛先に到達するまでの時間である。
ライト マップ (light map)
3D シーンのライティング情報の入ったテクスチャ。
ロビーアウェア アプリケーション (lobby-aware application)
ロビーからの起動を最小限サポートするアプリケーション。
ロビー クライアント (lobby client)
ユーザーのコンピュータ上で実行されるロビー管理ルーチン。 アプリケーションの起動、ユーザー インターフェイスの更新、ロビー サーバーとの通信を行う。
ロビー プロバイダ (lobby provider)
ロビー サーバーの開発者が提供するクライアント コンポーネント (ダイナミックリンク ライブラリ)。これには、Microsoft® DirectPlay® の要求に応じてロビー サーバーとの通信機能が実装される。
ロビー サーバー (lobby server)
リモート サーバー上で実行されるロビー管理ルーチン。ロビー サーバーは、管理対象のアプリケーションに接続してきたユーザーに関するすべての情報を調整する。
ロビー セッション (lobby session)
クライアントとサーバーが相互運用するよう特別に記述されていなかったロビー サーバーへの接続。


M

マッハ バンド (Mach bands)
3D プリミティブのブレンディングがスムーズに行われない色範囲。
マテリアル (material)
サーフェスがどのように光を反射および発色するかを決定する属性。マテリアル (素材) には、エミッション属性 (ライトに依存せず発色)、アンビエント属性、ディフューズ属性、およびスペキュラ属性の 4 つの構成要素がある。 反射の明るさは、強度の設定により決定される。
メッシュ (mesh)
単純なポリゴンで表現される面が集まったもの。
ミップマップ (mipmap)
MIP マップとも呼ばれる。MIP は、英語の "much in little" を意味するラテン語 �multium in parvo� の略。同一イメージが徐々に低解像度になっていく一連のテクスチャのことで、1 つのイメージに何種類ものフィルタをかけることにより作成される。オブジェクトが近くに表示されるときには高解像度のイメージが使用され、オブジェクトが遠ざかるに従って (つまり画面での表示が小さくなるに従って) 低解像度のイメージが使用される。
ミキシング (mixing)
Microsoft® DirectSound® で、再生中の複数のサウンド バッファを合成し、生成されたサウンドをプライマリ サウンド バッファ (サウンド ハードウェアにオーディオ データを出力するバッファ) へ書き込む処理。処理時間が範囲内に収まるかどうかを考慮しなければ、ミキシングできるバッファの数に制限はない。
モード X (Mode X)
標準 VGA のモード 13 から派生したハイブリッド ディスプレイ モード。 このモードでは、VGA ディスプレイ アダプタの EGA マルチ ビデオ平面システムを使用することにより、最大 256 KB のディスプレイ メモリが使用可能となっている (モード 13 で使用可能なディスプレイ メモリ量は 64 KB)。
モデル座標 (model coordinates)
ローカル原点に対する相対座標。「モデル空間」および「ワールド座標」を参照すること。
モデル空間 (model space)
単一の 3D モデル用のローカル原点に対する相対的な頂点を使用する (モデル座標のための) 基準フレーム。
マルチパス テクスチャ ブレンディング (multipass texture blending)
各パスごとに一度ずつテクスチャ上にブレンディングして、3D プリミティブを繰り返しレンダリングする手法。この手法は、さまざまな特殊効果を得るために幅広く使用されている。


N

ナグリング (nagling)
TCP/IP サービス プロバイダに、小さなデータ パケットをバッファに入れて大きなデータ パケットにしてから送信させるようにするアルゴリズム。ナグリングは、小さなデータ パケットを 1 つの大きなパケットに結合できるまで蓄積するか、事前のパケットの確認を受け取るまでサーバーに待機するよう要求することにより、TCP/IP サーバーが多くの非常に小さなパケットを送信しないようにする。ナグリングはメッセージ送信のオーバーヘッド (および必要な帯域幅) を削減できるが、小さなデータ パケットを送信する前に遅れが生じる (遅延時間が増える)。
法線ベクトル (normal vector)
サーフェスから垂直に伸びる架空のレイで、面の向きの定義に使用される。
NRPN
NonRegistered Parameter Number (非登録パラメータ番号) の略。非登録パラメータは異なるメーカーによる異なる機能に対して使用することができ、パラメータには MIDI コントローラを通してアクセスする。詳細については、MIDI の仕様を参照すること。


O

奇数フィールド (odd field)
ビデオ フレームを構成する奇数/偶数のフィールド セットの 1 つ目のフィールド。
オフスクリーン サーフェス (off-screen surface)
メモリ上の概念的な矩形領域。 一般に、表示する前にバック バッファへブリットするビットマップを格納するために使用する。通常、スプライトが格納される。
オペコード (opcode)
実行バッファ内の頂点を解釈する方法やシステムの状態を変更する方法を定義するオペレーション コード。
オーバードロー (overdraw)
スクリーン ピクセルが描画される平均回数。
オーバーレイ サーフェス (overlay surface)
メモリ上の概念的な矩形領域。 オーバーレイ サーフェスに格納されたイメージ情報は、そのオーバーレイ サーフェスが適用されるプライマリ サーフェスのイメージ情報の上に被せられる。オーバーレイは、その他のすべてのスクリーン要素よりも上にあるものとして処理される。
オーバーレイ Z オーダー (overlay z-order)
オーバーレイどうしのクリッピングの順番を決定する。 これにより、ハードウェア スプライト システムを Microsoft® DirectDraw® に実装することが可能になる。


P

ページ フリッピング (page flipping)
「フリップ」を参照すること。
パレット (palette)
オブジェクトやアプリケーションが使用する色セット。Microsoft® DirectX® では、DirectDrawPalette オブジェクトのことを指す。
パレット インデックス (palette index)
色を選択するときに使用されるパレット テーブル配列のインデックスとなる整数。
パレット化されたサーフェス (palettized surface)
アタッチされたパレットを色情報の格納場所として使用する DirectDrawSurface オブジェクト。
パン値 (pan value)
左右のオーディオ チャネルの相対音量。 100 分の 1 デシベル単位で表される。
パラレル ポイント (parallel point)
平行な光線でオブジェクトを照らすが、光の向きはその位置から決定されるような光源の記述。たとえば、パラレル ポイント光源の両側に置かれた 2 つのメッシュがある場合、各メッシュは光源に面している方の面が照らされる。
P チャンネル (PChannel)
Performance channel (パフォーマンス チャンネル) の略。特定のポート上にある特定のチャンネル グループ内の MIDI チャンネル。
PCM
Pulse Code Modulation (パルス符号変調) の略。非圧縮形式のウェーブ データ形式で、各値はサンプリング時の信号の振幅を表している。
ピアツーピア セッション (peer-to-peer session)
セッションの完全な状態がそのセッション内のすべてのコンピュータ上に複製される Microsoft® DirectPlay® セッション。セッション記述データ (プレーヤーとグループのリスト、および各セッションに関する名前とリモート データ) は、すべてのコンピュータに複製される。1 台のコンピュータで何か変更した場合は、ほかのすべてのコンピュータに即座に通知される。これは、DirectPlay の通信のデフォルト モードである。「クライアント/サーバー セッション」を参照すること。
パースペクティブ補正 (perspective correction)
遠近補正のこと。 カメラから角度をなして離れていくポリゴンにテクスチャ マップを適用する際に、ポリゴンの奥行きがわかるようにテクスチャをポリゴン上に広げる技法。Microsoft® Direct3D® では、パースペクティブ補正は自動的に行われる。
ピッキング (pick)
ビューポートの 2D 座標で与えられた場所にあるビジュアル オブジェクトをシーン内で探すこと。
PID
Physical Interface Device (物理インターフェイス デバイス) の略。人間がコンピュータからフォース フィードバックを感じることのできる USB クラス。
ピッチ (pitch)
ビットマップ ラインの先頭を表すアドレスと次のラインの先頭を表すアドレスの間の距離。 バイト単位で表される。すべてのディスプレイ メモリが 1 つの線形ブロックとして配置されているとは限らないので、メモリ ピッチとメモリ幅を混同しないこと。たとえば、矩形メモリのように、ビットマップの幅とキャッシュ部分が足されたものがディスプレイ メモリのピッチとなっている場合もある。「幅」および「ストライド」を参照すること。
プレーヤー (player)
Microsoft® DirectPlay® セッションの参加者。各プレーヤーには、プレーヤー間でのメッセージ交換を可能にするためにプレーヤー ID が与えられる。
プレーヤー ID (player ID)
Microsoft® DirectPlay® セッションの参加者の作成時に参加者に与えられる、その参加者固有の番号。アプリケーションは、プレーヤー ID を使用して参加者どうしにメッセージ交換を行わせる。ホストには、常に DPID_SYSMSG というプレーヤー ID が与えられる。
PNG
Portable Network Graphics (ポータブル ネットワーク グラフィックス) の略。劣化のない圧縮方式を使用するビットマップ フォーマット。特定のメーカーの所有物ではない。
ポイント ライト (point light)
その起点からすべての方向へ均等に光を照射する光源。
ポイント リスト (point list)
最も単純な 3D プリミティブ。3D 空間内の互いに接続されていない点の集まりである。
強度 (power)
マテリアルのスペキュラ属性で、スペキュラ ハイライトの鮮明度を決める値。この値が 5 のときは金属的な外観になり、値がもっと高くなるとよりプラスチック的な外観になる。
プライマリ サウンド バッファ (primary sound buffer)
最終的なオーディオ出力をミキシングして再生するオブジェクト。一般にはセカンダリ バッファのサウンドをミキシングした結果の出力先とされるが、カスタム ミキシングやその他の特別処理を行うために直接アクセスすることもできる。
プライマリ サーフェス (primary surface)
ディスプレイに表示されるイメージが格納されるメモリ領域。
射影空間 (projection space)
射影トランスフォームによってワールド空間の位置からトランスフォームされた頂点の入った基準フレーム。射影空間は、シーン上のすべての頂点が、－ 1.0 ～ 1.0 の範囲内の x 座標と y 座標、および 0.0 ～ 1.0 の範囲内の z 座標を持つ同次立方体空間である。遠近補正後同次空間と呼ばれる場合もある。
射影トランスフォーム (projection transformation)
頂点に行列を適用して、頂点をカメラ空間から射影空間へ変更するトランスフォーム。


Q

クオータニオン (quaternion)
ベクトルを定義する [x, y, z] 値に追加される 4 つ目の要素。3D 軸とその回りの回転を定義する。


R

参照カウント (reference count)
コンポーネント オブジェクト モデル (COM) オブジェクトをコントロールするためのカウンタ。参照カウントは、オブジェクトが作成されたときに 1 に設定される。 その後、インターフェイスがオブジェクトに結び付けられるたびにインクリメントされ、インターフェイス接続が切断されるとデクリメントされる。参照カウントが 0 になると、オブジェクトは破棄される。 破棄されたオブジェクトへのインターフェイスはすべて無効となる。
リージョン (region)
DLS では、楽器の音色を合成する際に、そのデジタル サンプルが使用される音色の範囲。
ルート フレーム (root frame)
Microsoft® Direct3D® での、親フレームを持たない (つまり、フレームの階層構造の最上位に位置する) フレーム。ルート フレームには、シーンを構成する一連のオブジェクトすべてが格納される。「シーン」を参照すること。
PRN
Registered Parameter Number (登録パラメータ番号) の略。登録パラメータ番号は MMA (MIDI Manufacturers Association) によって機能に割り当てられており、コントローラを通してアクセスできる。詳細については、MIDI の仕様を参照すること。


S

飽和 (saturation)
入力およびフォース フィードバックにおいて、軸が物理的な極限に達する前に最小値または最大値が取得または設定されるようにするために行う、軸の範囲に対する調整。範囲内の最大値が 1,000 で、最大飽和ポイントが 900 に設定されている場合、軸がその方向に 90% 移動すると、最大値に達する。
シーン (scene)
仮想環境を構成する一連のオブジェクトすべてを指す。 可視オブジェクト、サウンド、ライト、フレームが含まれる。Microsoft® Direct3D® では、ルート フレーム内のオブジェクト全体のことを指す。
スクリーン空間 (screen space)
座標がフレーム バッファ内の 2D (2 次元) の位置に直接マッピングされている基準フレーム。 ディスプレイやその他の表示デバイスに表示するためのフレームである。スクリーン空間の座標は、ビューポートのパラメータから作成したトランスフォーム行列を使用して射影空間の座標をトランスフォームすることにより得られる。
セカンダリ サウンド バッファ (secondary sound buffer)
1 つのサウンドまたはオーディオ ストリームを管理し、それをプライマリ サウンド バッファに対して再生するオブジェクト。
セキュア セッション (secure session)
セッションに参加する前に、既知のユーザーのデータベースに対してすべてのユーザーが認証されたセッション。セキュア セッションでは、Microsoft® DirectPlay® のシステム メッセージはすべてデジタル署名され、送信元の身元が確認される。機密性の高い情報を送信する特定のシステム メッセージは暗号化される。1 人のプレーヤーから発生し、セッション内のほかのすべてのプレーヤーにある要素を全要素にコピーしなければならないシステム メッセージは、まず最初にサーバーに送信される。その後、サーバーはメッセージに署名し、セッション内のほかのすべてのコンピュータにメッセージを転送する。デフォルトでは、プレーヤーからプレーヤーへのメッセージは署名されず、サーバー経由でルーティングされない。
センド (send)
(名詞) セカンド バッファにサウンド データを送信することで適用される、バッファに対するサウンド エフェクト。
サービス プロバイダ (service provider)
Microsoft® DirectPlay® がネットワークを介した通信を行うために使用するダイナミックリンク ライブラリ。サービス プロバイダには、メッセージを送受信するために必要となるネットワーク固有のコードがすべて含まれている。各種オンライン サービスやネットワーク オペレータは、サービス プロバイダを提供することにより、ハードウェア、プロトコル、通信媒体、ネットワーク資源などに特殊なものを使用することができる。
セッション (session)
Microsoft® DirectPlay® で、リモート コンピュータ上で実行され互いに通信しているいくつかのアプリケーションのインスタンス。アプリケーションがほかのコンピュータとの通信を開始する場合、アプリケーションはいずれかのセッションに属している必要がある。アプリケーションはネットワーク上の既存のセッションすべてを列挙し、それらの 1 つに参加したり、新しいセッションを作成し、作成したセッションにほかのコンピュータが参加するのを待機したりすることができる。アプリケーションがセッションの一部になると、プレーヤーを作成し、セッション内のほかのすべてのプレーヤーとメッセージを交換できる。
サウンド バッファ (sound buffer)
Microsoft® DirectSound® のオーディオ データを管理するオブジェクト。
転送元カラー キー (source color key)
ブリットの場合は転送でコピーされない色、オーバーレイの場合は出力先で表示されない色のこと。
スペキュラ属性 (specular property)
スペキュラ反射属性、ライトからの入射光の角度と視点への反射光の角度の両方に依存したマテリアル属性。マテリアルの光の反射および発色を決定する属性は 4 つあるが、スペキュラ属性はそのうちの 1 つである。「アンビエント属性」、「ディフューズ属性」、および「エミッション属性」を参照すること。
スポットライト (spotlight)
円錐状の光を放つ光源。円錐の中にあるオブジェクトだけが照らされる。円錐は 2 つの輝度を生成する。 中央の明るい部分はポイント ライトと同じ働きをし、周囲の薄暗い部分は周辺の暗い影とマージされる。
スタティック バッファ (static buffer)
サウンド全体を保持するセカンダリ サウンド バッファ。通常、データは 1 回だけ書き込まれる。「ストリーミング バッファ」と比較すること。
スティッキー フォーカス (sticky focus)
Microsoft® DirectSound® で、バッファを所有するアプリケーションが入力フォーカスを持っていないときにもサウンド バッファを再生できる能力。たとえば、ユーザーがほかのアプリケーションで作業している間にも、DirectSound アプリケーションはサウンド バッファを再生し続けることができる。
ストリーミング バッファ (streaming buffer)
サウンドの一部だけを保持するセカンダリ サウンド バッファ。ストリーミング バッファのデータは、再生に合わせてリフレッシュされなければならない。「スタティック バッファ」と比較すること。
伸縮 (stretching)
サイズの異なる転送先にイメージをブリットすること。この処理を直接サポートするハードウェアもある。
ストライド (stride)
ピッチ の同義語。「幅」を参照すること。
サーフェス (surface)
ビジュアル イメージが格納されるメモリ。たいていの場合はディスプレイ メモリ内に置かれるが、システム メモリに置くこともできる。「複合サーフェス」、「オフスクリーン サーフェス」、「オーバーレイ サーフェス」および「プライマリ サーフェス」を参照すること。
維持期間 (sustain)
フォース フィードバック エフェクトの基本マグニチュードが到達されている期間。 アタックからフェードまでの間。
システム メッセージ (system message)
Microsoft® DirectPlay® では、プレーヤー ID の DPID_SYSMSG からのメッセージ。すべてのシステム メッセージは DWORD 値で始まる。


T

TCP/IP サービス プロバイダ (TCP/IP service provider)
TCP/IP プロトコルを使用してインターネットやローカル エリア ネットワーク (LAN) 上で通信を行うために Windows Sockets を使用するサービス プロバイダ。非保証メッセージに User Datagram Protocol (UDP) パケットを使用し、保証付きメッセージに TCP を使用する。TCP/IP を使用して、1 台のコンピュータは、複数の Microsoft® DirectPlay® セッションとして機能できる。
テアリング (tearing)
スクリーンのリフレッシュ レートがアプリケーションのフレーム レートと同期していないときに発生する、表示がうねるように見える現象。1 つのフレームの上部が別のフレームの下部と同時に表示され、2 つのイメージの間に裂け目が生じる。
テッセレーション (tessellation)
3D グラフィックスでオブジェクトのサーフェスを三角形ポリゴンに細分化すること。
テクセル (texel)
テクスチャ内の単一の要素。テクスチャがオブジェクトに適用されたとき、テクセルがスクリーン上のピクセルに対応することはめったにない。アプリケーションは、テクスチャ フィルタリングを使用して、シーン内にピクセルを作成するためにシステムがテクセル間を補間する方法を制御できる。
テクスチャ (texture)
Microsoft® Direct3D® でビジュアル オブジェクトに適用される、ピクセルが矩形に並んだ配列。
テクスチャ ブレンディング (texture blending)
テクスチャの色をマップ先のサーフェスの色と組み合わせる技法。
テクスチャ座標 (texture coordinates)
各テクスチャのどのテクセルがオブジェクトの各頂点に割り当てられるかを決める座標。
テクスチャ フィルタリング (texture filtering)
1 つまたは複数のテクスチャから得たテクセルの色を、3D プリミティブのイメージを構成するピクセルにマップする処理。
テクスチャ マッピング (texture mapping)
テクスチャをオブジェクトに適用すること。テクスチャはフラットなイメージなのに対し、多くの場合オブジェクトは立方体であるため、テクスチャは、テクスチャ座標とラッピング フラグを使用して、オブジェクトの表面にマップされなければならない。「テクスチャ座標」および「ラップ」を参照すること。
スラッシング (thrashing)
次のフレームでテクスチャ メモリを再利用するよう、現在のフレームで使用したテクスチャを削除すること。
スロットリング (throttling)
元の伝送形態よりもメッセージを早く送信しないよう、メッセージ数を制限すること。


U

単位ベクトル (unit vector)
マグニチュード (長さ) 1.0 のベクトル。
USB
Universal Serial Bus (ユニバーサル シリアル バス) の略。


V

VBI
Vertical Blanking Interval (垂直帰線消去間隔) の略。ある要素を全要素にコピーするビデオでは、ビデオ フレーム間に短い時間がある。 この間に、ディスプレイ デバイスは次のフレームのためにディスプレイをリフレッシュする。
ベロシティ (velocity)
ミュージックでは、MIDI キーが押される速度。この速度は、いくつかの音色のティンバーでノートが再生される動的レベルとほぼ等しい。

3D サウンドでは、ドップラー シフトを計算するために使用される、音源またはリスナーが移動していると見なされる場合の速度。

頂点 (vertex)
3D 空間のポイント。
ビデオ フレーム (video frame)
ビデオ ストリーム内の単一のイメージ。 1 つの奇数フィールドと 1 つの偶数フィールドから成る。「フィールド」を参照すること。
ビュー空間 (view space)
「カメラ空間」を参照すること。
ビュー トランスフォーム (view transformation)
モデルの頂点に行列を適用して、モデルの向きをワールド空間からビュー空間へ変えるトランスフォーム。
視錐台 (viewing frustum)
ビューポートのカメラに対して相対的に配置されたシーン内の 3D ボリューム。視錐台の中にあるオブジェクトは、画面に表示される。遠近ビューでは、前方クリップ面と後方クリップ面の間にある仮想的なピラミッド型のボリュームとなる。正射ビューでは、立方体になる。
ビューポート (viewport)
3D シーンがどのように 2D ウィンドウにレンダリングされるかを決める矩形。ビューポートは、デバイス上での、オブジェクトがレンダリングされる領域も決める。
VREF
Vertical REFresh (垂直リフレッシュ) の略。VREF は、ビデオ ストリーム内で、ディスプレイが新しい画面を開始しようとしていることを知らせるときにアクティブになる。「HREF」を参照すること。


W

幅 (width)
メモリ内に格納されているビットマップの 1 つのラインの始点を表すアドレスとそのラインの終点を表すアドレスの距離。この距離は、メモリ内でのビットマップの幅だけを表すものである。矩形メモリ内のキャッシュなど、ビットマップの次のラインの始点に達するまでに必要となるような余分なメモリは、この距離には含まれない。
ワールド座標 (world coordinates)
シーンの頂点に達する相対座標。「モデル座標」および「ワールド空間」を参照すること。
ワールド空間 (world space)
ワールド座標 (3D シーン内の単一の原点に対する相対的な頂点を表す) により使用される基準フレーム。
ワールド トランスフォーム (world transformation)
モデルの頂点に行列を適用して、モデルの向きをモデル空間からワールド空間へ変えるトランスフォーム。
ラップ (wrap)
面やメッシュのテクスチャ座標の計算に使用されるプロシージャ。基本的なラッピング タイプには、フラット、円柱、球状、クロムがある。


X, Y, Z

Z バッファ (z-buffer)
シーン上の各ピクセルの深度を格納したバッファ。z 値の小さいピクセルは z 値の大きいピクセルを上書きする。
Z ファイティング (z fighting)
「フリマリング」を参照すること。


Locator オブジェクト

Locator オブジェクトにはチューニング空間の情報が入る。Locator オブジェクトは通常ネットワーク プロバイダによって使用され、チューナーによる転送ストリームの発見と取得を助ける。アプリケーションはデバッグの目的以外には Locator オブジェクトを多分使わないであろう。

メソッド名またはプロパティ名 | 説明
CarrierFrequency | キャリア周波数 (デカ Hz) の設定あるいは取得。
Clone | ロケータをコピーする。
InnerFEC | 内部 FEC タイプの設定あるいは取得。
InnerFECRate | 内部 FEC レートの設定あるいは取得。
Modulation | 変調タイプの設定あるいは取得。
OuterFEC | 外部 FEC タイプの設定あるいは取得。
OuterFECRate | 外部 FEC レートの設定あるいは取得。
SymbolRate | QPSK シンボル レートの設定あるいは取得。

Locator.CarrierFrequency プロパティ

Locator オブジェクト

キャリア周波数 (デカ Hz)。

構文

Locator.CarrierFrequency

注意

このプロパティは、読み書き可能なプロパティである。

参照

Locator.Clone メソッド

Locator オブジェクト

ロケータをコピーする。

構文

Locator.Clone(NewLocator);

パラメータ

NewLocator paramDesc

戻り値

注意

参照

Locator.InnerFEC プロパティ

Locator オブジェクト

内部 FEC タイプ。

構文

Locator.InnerFEC

注意

このプロパティは、読み書き可能なプロパティである。

参照

Locator.InnerFECRate プロパティ

Locator オブジェクト

内部 FEC レート。

構文

Locator.InnerFECRate

注意

このプロパティは、読み書き可能なプロパティである。

参照

Locator.Modulation プロパティ

Locator オブジェクト

変調タイプ。

構文

Locator.Modulation

注意

このプロパティは、読み書き可能なプロパティである。

参照

Locator.OuterFEC プロパティ

Locator オブジェクト

外部 FEC タイプ。

構文

Locator.OuterFEC

注意

このプロパティは、読み書き可能なプロパティである。

参照

Locator.OuterFECRate プロパティ

Locator オブジェクト

外部 FEC レート。

構文

Locator.OuterFECRate

注意

このプロパティは、読み書き可能なプロパティである。

Locator.SymbolRate プロパティ

Locator オブジェクト

QPSK シンボル レートを設定あるいは取得する。

構文

Locator.SymbolRate

注意

このプロパティは読み書き可能なプロパティである。QPSK は RF 信号にシンボルを変調する。これらのシンボルは復調器によって検出され、ビット ストリームを再構築するのに使われる。OPSK は変更のために変調/復調されるレートを許可する。

参照


基準タイム

Microsoft® DirectShow® 編集サービス (DES) は、2 つのフォーマットを使用して基準タイム (REFERENCE_TIME 値および REFTIME 値) を指定する。

  • REFERENCE_TIME : ほぼ 100 ナノ秒を表す LONGLONG (64 ビット符号なし整数) 値 (1 ナノ秒は 1 X 10-9 秒であり、したがって 1 秒は 1 X 107、または 10,0000,000 基準タイムである)。
  • REFTIME : 秒数を示す小数を表す倍精度浮動小数点数。

メソッドによって、REFERENCE_TIME パラメータをとるものと REFTIME パラメータをとるものがある。また、基準タイムの 2 つのタイプごとに異なるバージョンを持つメソッドもある。


DirectShow による DVD アプリケーションの開発

Microsoft® DirectShow® は、DVD の操作における低レベルの複雑な処理を DVD ナビゲータ ソース フィルタと呼ばれるコンポーネントにカプセル化する。DVD ナビゲータには、本格的なスタンドアロン DVD プレーヤーが備えるすべての機能に加えて、パソコン上で DVD を再生するための追加機能が含まれている。DVD ナビゲータと C++ およびスクリプト機能を使用することで、開発者は DVD の仕様を参照する必要なしに完全な機能を持つ DVD プレーヤーを作成できる。

C++ を使用する開発者は、DVD ナビゲータが公開する Component Object Model (COM) インターフェイスを通じて、DVD ナビゲータを直接制御できる。スクリプト言語または Microsoft® Visual Basic® を使用する開発者は、MSWebDVD ActiveX® コントロールを通じて間接的に DVD ナビゲータを制御できる。

注 : DirectShow は、DVD-Video の操作と再生に必要なフィルタをすべて備えているが、MPEG-2 デコーダは含まれていない。DirectShow に基づいたアプリケーションを使用して DVD を再生するには、ユーザーのシステム上に DirectShow に対応したサードパーティ製のハードウェア デコーダまたはソフトウェア デコーダをインストールする必要がある。

ここには、以下のトピックが含まれる。

  • DVD プレーヤー アプリケーションの開発に必要な背景知識
  • DVD の操作に関するトピック
  • C++ による DVD プレーヤー アプリケーションの開発
  • C++ アプリケーション用 DVD API リファレンス
  • スクリプトに基づいた DVD プレーヤー アプリケーションの開発
  • MSWebDVD ActiveX コントロール API リファレンス


A

アドバイズ (advise)
一定時間が経過している非同期通知に対する要求。
アルファ (alpha)
ピクセルの不透明度を表す。ピクセルが最大アルファ値の場合は不透明、アルファ値 0 の場合は透明、中間の値の場合は半透明である。
アプリケーション通知 (application notification)
アプリケーションがイベント通知キューから取得するイベント。
非同期リーダー フィルタ (asynchronous reader filter)
独自に解析は行わず、メディア ファイルから単にデータを読み込むファイル ソース フィルタ。
ATR
オーディオ テープ レコーダ。


B

バッキング オブジェクト (backing object)
マルチメディア ストリーミングでは、ビデオ用の Microsoft® DirectDraw® サーフェスまたはオーディオ用の IAudioData オブジェクトのどちらかである。
バイフェーズ マーク (bi-phase mark)
矩形波にエンコードされるクロック タイミングおよびビット ストリーム データなどのデジタル データをエンコードする方法。広範囲な演奏速度で読み込み可能なため、(元は Manchester-1 コードとして知られる) LTC 信号用に使用される。
ブラックバースト (blackburst)
複数のビデオ ソースの同期に使用できるビデオ信号。ブラックバーストには、垂直同期、水平同期、およびクロマ バーストの情報が含まれるが、アクティブな画像情報は含まれない。
ブリット (blit)
ビットのブロック転送。メモリやスクリーンなどのソースから全ビットマップまたはビットマップの一部を、別のメモリやディスプレイ サーフェスなどの送信先に転送するために使用される。
Bob
インターレース ビデオ フィールドをプログレッシブ モニタ上に表示する方法。Bob モードでは、1 つのフィールドが一度に表示され、偶数の線と奇数の線が交互になる。線は、ディスプレイ領域全体に適合するように 2 倍に伸ばされる。


C

チェース モード (chase mode)
ビデオ テープ レコーダおよびその他の転送における処理モード。このモードで、1 つまたは複数のデバイスがマスタ デバイスに同期される。
クロマ バースト (chroma burst)
ビデオのアクティブなラインに関する色情報をカラー デコーダに提供する。
CODEC
コンプレッサ/デコンプレッサ。
カラー キー (color key)
透明エフェクトや半透明エフェクトに使用される色を示す値。たとえば、ハードウェアのブリット機能を使用した場合、矩形領域内のカラー キーとして設定された値を持つピクセル以外のすべてのピクセルがブリットされる。これは、矩形でないスプライトをサーフェス上に作成する。
合成 (composition)
トラックおよび (オプションとして) その他の合成のコレクション。レンダリング時、合成のソースは 1 つのイメージに合成される。
圧縮フィルタ (compression filter)
データを受け取り、圧縮スキームを使用してデータを変換し、圧縮されたデータ ダウンストリームを渡す変換フィルタの特殊なタイプ。


D

デバッグ ビルド (debug build)
最も大きく、速度の遅いタイプのビルド。ただし、新しいコードのデバッグおよび問題の追跡に対して充実した機能を提供する。
デバッグ レベル (debug level)
デバッグの出力に対して相対的な重要性を示す DWORD 値。値ゼロ (0) は最も重要なレベル。
DIB シーケンス (DIB sequence)
ビデオ内の連続するフレームであるかのような、シーケンス内でレンダリングされる一連の DIB (device-independent bitmap) イメージ。
ダウンサンプル (downsample)
アベレージングなどの処理を適用することによって、サンプルまたはピクセルの数を減少させる。
ダウンストリーム フィルタ (downstream filter)
アップストリーム フィルタから次にデータを取得するフィルタ。アップストリーム フィルタは、出力ピンから、接続されているダウンストリーム フィルタの入力ピンにデータを送信する。


E

EDL (Edit Decision List)
イベントと呼ばれる項目のリスト。このリストには、ビデオおよびオーディオの素材 (ソース マテリアル) を識別する SMPTE タイムコードを使用して、ビデオ シーケンス、オーディオ シーケンスまたはその両方が示される。
エフェクト フィルタ (effect filter)
メディアの種類は変更せずに、エフェクトをメディア データに適用するフィルタ。
エンドオブストリーム プロトコル (end-of-stream protocol)
フィルタがエンドオブストリーム情報を生成して処理する方法、およびフィルタ グラフ マネージャに通知される方法を定義するプロトコル。
エラー検出およびエラー報告プロトコル (error detection and reporting protocol)
フィルタでエラーが処理される方法およびフィルタ グラフ マネージャにエラーが通知される方法を定義するプロトコル。
イベント通知 (event notification)
フィルタからフィルタ グラフ マネージャに送信されるシステム定義のイベント。


F

フィールド (field)
インターレース ビデオ フレームの一部。インターレース ビデオでは、偶数フィールドの走査線は、奇数フィールドの走査線間の中間に存在する。
ファイル ライタ (file writer)
マルチプレクサとファイル ライタ フィルタから成るフィルタ グラフのセクション。
フラッシング プロトコル (flushing protocol)
フィルタがフィルタ グラフを通してデータをフラッシュする方法を定義するプロトコル。
フォーマット タイプ (format type)
フォーマット ブロックのコンテンツを示す GUID。
フレーム ブリット (frame blitting)
メディア データをプライマリ サーフェス上のアプリケーション ウィンドウのクライアント領域にブリット (ビット ブロック転送) すること。


G

ガンマ (gamma)
電圧レベルの変化を蛍光体ディスプレイ画面上の輝度レベルの変化にマップする機能の曲線。輝度に特定の変化を与えるために必要な電圧レベルの変化は、電圧レベルによって異なる場合がある。
グループ (group)
合成およびトラックの最上位レベルのコレクション。すべて同じメディア タイプを表している。それぞれのグループは、レンダリング プロジェクト内に個別のストリームを生成する。


H

色相 (hue)
可視光によって生成される色。緑、赤、オレンジなどの一般的な色の用語は色相を表す。


I

入力ピン (input pin)
フィルタへのデータを受け取るピン。
インテリジェント接続
IGraphBuilder Connect、Render と RenderFile を含むメソッド呼び出し内で、フィルタ グラフ マネージャによって実装されるロジック。このロジックは次のいずれかを決定することによりグラフ作成のプロセスを自動化する、1 つはどのフィルタが与えられたファイルあるいは出力ピンへのレンダリングを要求されているか、もう 1 つはどの中間フィルタが指定された 2 つのピンを接続するよう要求されているのか。
メディアタイプを変換するソースとレンダラ間にフィルタセットを挿入するように DirectShow に教える。
インターレース (interlace)
2 つのフィールドで構成されるフレームを含むラスタ スキャン。
インターリーブ (interleaving)
ファイル内での対応するビデオ フレームとオーディオ サンプルの配列。通常、ビデオ データの 1 つ以上のフレームがオーディオ データの特定の数のサンプルと共にファイル内に混在する。インターリーブは、演奏効率およびファイルをストリームする能力に影響を及ぼす。
補間 (interpolation)
シーケンス内の 2 つの認識されている値間の中間値を見積もることによって、紛失した情報または必要な情報を生成する数学的な方法。


K

カーネル モード (kernel mode)
システムへのフル アクセスおよび非保護アクセスが可能なプロセッサ モード。カーネル モードで動作しているドライバやスレッドは、システム メモリおよびハードウェアへのアクセス権を持っている。
キー フレーム (key frame)
フレームの作成に必要なすべてのデータを含むビデオ データのフレーム。対照的に、デルタ フレームには最後のキー フレームからの変更に関するデータが含まれており、完全なフレームを作成するための十分な情報は含まれていない。


L

遅延時間 (latency)
フィルタでサンプルの処理にかかる総時間。
レターボックス (letterbox)
クロッピングまたは伸縮を行わずに表示ウィンドウ内でビデオを可能な限り大きなサイズで表示するビデオ ディスプレイ フォーマット。
ロックされたオーディオ (locked audio)
特定の配布の後に 1 フレームのオーディオ サンプル数が続くデジタル ビデオ フォーマット。たとえば、NTSC 48kHz のロックされたオーディオでは、フレーム 1 に 1600 個のサンプルが含まれ、フレーム 2 ～ 5 にはそれぞれ 1602 個のサンプルが含まれる。ロックされないオーディオでは、サンプル数は変更できる。ただし、その平均は所定のサンプル レートと等しくなければならない。
ルックアヘッド (lookahead)
ストリームの後続のデータを使用して、現在のデータを処理すること。たとえば、次のキー フレームを使用してデルタ フレームを計算する。
LTC
Linear Timecode (リニア タイムコード) の略。以前は Longitudinal Timecode と呼ばれていた。タイムコードは個別のオーディオ トラック上に保存され、時間幅内の 1 つのビデオ フレーム タイムである。


M

メジャー タイプ (major type)
データ ストリーム用のメディア データのすべてのクラスを表す GUID 値。
メリット (merit)
フィルタ グラフ マネージャがフィルタに接続する順番を制御する値。
メディア サンプル プロトコル (media sample protocol)
メディア サンプルを割り当て、フィルタ間に渡す方法を定義するプロトコル。
メディア タイム (media time)
シーク可能なメディア内の位置を示すために使用される用語。メディア タイムはさまざまな単位で表すことができ、ファイルのデータ内の位置を示す。
ミディアム (medium)
ミディアムはホスト システムのデバイス間のハードウェア データパスを示す。このパスは同じ内部カードの 2 つのデバイスである場合もある、たとえば、TV カードのクロスバーとチューナー、あるいは 2 つの別のカード間であったり、外部デバイス間である場合もある。Windows® ドライバ モデルでカーネルモード フィルタのピンを接続するとき、その接続がハードウェアで提供されている固有のデータパスをベースにしているならミディアムはメディア タイプの代わりに使われる。
単調増加あるいは単調減少 (monotonic)
決して増加または減少しないシーケンスを示す。単調増加するシーケンスでは、各要素は前の要素と等しいか、または大きい。単調減少するシーケンスでは、各要素は前の要素と等しいか、または小さい。
マルチプレクサ (MUX)
複数の入力ストリームを 1 つの出力ストリームに結合するフィルタ。


N

新セグメント プロトコル (new segment protocol)
データに先立って開始タイムと終了タイム、およびデータ レート情報をフィルタに示す方法を定義するプロトコル。これによって、フィルタは状況に応じて処理を調節できる。
NTSC
国際テレビジョン システム委員会 (National TV Systems Committee) アナログ合成カラー テレビジョン規格。速度は 29.97 フレーム/秒、59.94 フィールド/秒。北アメリカ、日本、およびその他多くの国で NTSC を採用している。


O

出力ピン (output pin)
データをその他のフィルタに渡すピン。


P

PAL
アナログ合成カラー テレビジョン規格。速度は 25 フレーム/秒、50 フィールド/秒。主にヨーロッパ、オーストラリア、およびその他の地域の一部で採用されている。
パン-スキャン (pan-scan)
ビデオの製作者が定義したパラメータを使用して、16 × 9 のビデオ画面を切り出し、4 × 3 のウィンドウに表示する DVD のビデオ ディスプレイ フォーマット。
パーサー フィルタ (parser filter)
非同期ファイル リーダー フィルタを使用してディスクから情報を抽出するフィルタ。または、URL モニカ フィルタを使用してインターネットから情報を抽出するフィルタ。
周期的アドバイズ (periodic advise)
一連の一般的なアドバイズの呼び出し。
ピクセル ダブリング (pixel doubling)
イメージを 2 倍にスケーリングすること。
PID
フィルタ グラフのフィルタを列挙することによって、コントロール インターフェイスを公開し、実装するオブジェクト。同じインターフェイスを公開するフィルタを検索し、それらのフィルタどうしが直接やり取りする。
プリロール (preroll)
目的の再生時間または再生位置に先立つデータの待ち行列。
プリロール タイム (preroll time)
ランダムでないアクセス デバイスがローリングを開始するべき開始位置より前の時間。
プレゼンテーション時間 (presentation time)
フィルタが取得するデータ パケットがダウンストリームされ、レンダリングされるストリーム タイム。
プレビュー セクション (preview section)
キャプチャ フィルタのプレビュー ピン ダウンストリームからビデオ レンダラを含むフィルタ グラフの一部。
プライマリ サーフェス (primary surface)
モニタに表示されるイメージが格納されるメモリ領域。Microsoft® DirectX® では、プライマリ サーフェスは、プライマリ DirectDrawSurface オブジェクトにより表される。


Q

品質コントロール (quality control)
実行時の条件に合わせてデータ フローの速度を調整するメカニズム。
品質シンク (quality sink)
品質コントロール メッセージを受け取るために指定されるオブジェクト。


R

基準クロック (reference clock)
クロックを提供し、フィルタ グラフ内でイベントのスケジューリングをサポートするオブジェクト。
基準タイム (reference time)
フィルタ グラフの基準クロックによって作成される絶対時間。
REFTIME
秒数を表す double タイプの浮動小数点値。
レンダラ (renderer)
メディア データをコンピュータ モニタ、サウンド カード、ファイルなどの場所にレンダリングするフィルタ。
リテール ビルド (retail build)
最も小さく、速度の速いタイプのビルド。一般的にデバッグ ビルドに比べて堅牢性に欠ける。


S

彩度 (saturation)
色の純度。完全にまじりけのない色は飽和度 100 パーセントとして表される。飽和度が低くなるほど、色はグレイに近くなる。
SECAM
アナログ合成カラー テレビジョン規格。速度は 25 フレーム/秒、50 フィールド/秒。ヨーロッパの多くの国、オーストラリア、およびその他の地域で採用されている。
シーク可能なレンダラ (seekable renderer)
フィルタ上のシーク可能なストリームがストリームの終端に到着した場合に EC_COMPLETE を報告するレンダラ。
サーボ (servo)
VCR のビデオ ヘッドの適切な速度とフェーズおよびテープ転送を維持する電子システム。
シンク ファイル (sink file)
メディア サンプルが書き込まれる現在のファイル。
ソース フィルタ (source filter)
ハード ドライブ、ネットワーク、インターネットなどのソースからデータを受け取り、フィルタ グラフに渡すフィルタ。
スマート再圧縮 (smart recompression)
フォーマットが出力フォーマットと適合しない場合のみ、ソース ファイルを圧縮および再圧縮すること。
ストリーム通知 (stream notification)
メディア ストリームで発生し、1 つのフィルタから次のフィルタに渡されるイベント。
ストリーム タイム (stream time)
フィルタ グラフが最後に開始されてからの時間。定義では、ストリーム タイムは、基準タイムから前の開始タイムを引いた値と等しい。ストリーム タイムは、実行しているフィルタ グラフのみに関係がある。
サブタイプ (subtype)
データ ストリーム用のメディア データの特定のフォーマットを記述する GUID 値。マイナー タイプとも呼ばれる。
同期ポイント (synchronization point)
その他のサンプルを検証せずにデコードできるメディア サンプル。たとえば、キー フレームなど。


T

テアリング (tearing)
表示されている 1 つのビデオ フレームに 2 つの異なるソースのビデオ フレームの一部がが含まれている場合に発生する、裂け目が見える現象。通常、ビデオのレンダリングがグラフィックスの表示と適切に同期されていないときに生じる。
タイム スタンプ (time stamp)
記録された時間と再生時間を示すメディア サンプルの時間。タイム スタンプは、100 ナノ秒単位 (REFERENCE_TIME) で測定され、正規化される。ゼロ (0) はグラフが実行されるときを示す。
タイムコード (timecode)
ビデオやオーディオ ストリームに適用されるデジタル フレームのアドレス (番地) 値、フラグ、および付加的なデータ。ANSI/SMPTE 12-1986 で定義される。ビデオおよびオーディオ用にマシンで読み込み可能なアドレスを提供することが目的。SMPTE タイムコードとも呼ばれる。
タイムライン (timeline)
ビデオ編集プロジェクトのルート ノード。プロジェクト内のその他すべてのオブジェクトのコンテナ。
トラック (track)
一様なメディア (オーディオまたはビデオ) を使用したオーバーラップしないソースのコレクション。
変換フィルタ (transform filter)
データを取得して処理し、フィルタ グラフの次のフィルタに渡すフィルタ。
変換インプレイス フィルタ (transform-inplace filter)
データのコピーやデータのメディア タイプの変更を行わずに、その場で処理を実行できる変換フィルタ。
転送 (transport)
オーディオ データ、ビデオ データ、またはその両方を外部デバイスからコンピュータ、およびコンピュータから外部デバイスに渡すメカニズム。


U

アップサンプル (upsample)
補間などの処理によって、サンプルまたはピクセルの数が増加すること。
アップストリーム フィルタ (upstream filter)
データを出力ピンから、フィルタ グラフの次のフィルタの接続されている入力ピンに渡すフィルタ。
URL モニカ フィルタ (URL moniker filter)
インターネット サーバーから読み込むソース フィルタ。
ユーザービット (userbits)
SMPTE タイムコードで定義されていないビット。これらのビットは、ユーザーがエンコードしたい任意の情報に使用できるため、ポストプロダクション処理中ソース マテリアルと共に移動する。ユーザービットには、オリジナル フィルムおよびオーディオ テープ情報が含まれる場合がある。


V

VITC
Vertical Interval Timecode の略。ビデオ信号の垂直同期間隔に格納されるタイムコード情報。通常、ライン 10 から 20 の 1 つまたは 2 つのライン上に配置されている。
垂直同期間隔 (vertical blanking interval)
アクティブな画像情報が転送されないときのビデオ信号の同期期間。
仮想トラック (virtual track)
合成内でトラックとして動作できるオブジェクト。合成およびトラックは仮想トラック。
VPE
ビデオ ポート エクステンション。VGA メモリのコンテキスト内でビデオ ポートからビデオ ストリームを制御する Microsoft® DirectDraw® API (アプリケーション プログラミング インターフェイス) のエクステンション。
VTR
ビデオ テープ レコーダ。


W

Weave
インターレース ビデオ フィールドをプログレッシブ モニタ上に表示する方法。Weave モードでは、2 つの連続するフィールドが一度に表示される。水平の走査線が 2 つのフィールド間で交互に繰り返される。
ホワイト バランス (white balance)
オリジナル イメージの白い領域が白として正しく表示されるように、イメージのカラー レベルを調整すること。


GLOSSARY HEAD

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z


CDisp クラス

CDisp クラスは、デバッグ用のさまざまなデータ型を表示するメソッドを提供する。このクラスは、各型のコンストラクタを提供し、デバッグ文の文字列として使用するための LPCTSTR 型にキャストできる。

たとえば、次のようなコードを考えてみる。

int MyFunc(REFERENCE_TIME rt, IPin *pPin)
{
DbgLog((LOG_TRACE, 2, TEXT("MyFunc(%s, %s)"),
(LPCTSTR) CDisp(CRefTime(rt)),
(LPCTSTR) CDisp(pPin)));
...
}

このコードは、次のような基準タイムおよびピン情報をデバッグ ログに出力する。

Quartz.dll(tid d7) :MyFunc(1.003 sec,
CLSID_AudioRender(Audio Input pin (rendered)))

メンバ関数

CDisp CDisp オブジェクトを作成する。

演算子

LPCTSTR デバッグ文字列で使用するために LPCTSTR 型にキャストする。

CDisp::CDisp

CDisp クラス

CDisp オブジェクトを作成する。

構文

CDisp(
LONGLONG ll,
int Format = CDISP_HEX
    );
CDisp(
REFCLSID clsid
    );
CDisp(
double d
    );
CDisp(
CRefTime t
    );
CDisp(
IPin *pPin
    );

パラメータ

ll
表示用の LONGLONG 型の値。
Format
値を 10 進法 (CDISP_DEC) で表示するか、16 新法 (CDISP_HEX) (デフォルト) で表示するかを示す値。
clsid
表示するクラス識別子。
d
表示する double 型の値。
t
表示する基準タイム。REFERENCE_TIME 型の値の受け渡しでは、LONGLONG コンストラクタを使用する。
pPin
ピンを "CLSID of the filter(Pin name)" のフォーマットで、CLSID_AudioRenderer(Audio 入力ピン) のように表示する IPin インターフェイスへのポインタ。

戻り値

戻り値なし。

注意

情報を最適な方法で表示できるようにするためのさまざまなコンストラクタが用意されている。

CDisp::LPCTSTR

CDisp クラス

デバッグ文字列で使用するために CDisp オブジェクトを LPCTSTR 値にキャストする。

構文

operator LPCTSTR();

戻り値

コンストラクタで使用される変数の文字列表現を返す。


CDispBasic

CDispBasic は CDisp クラスを実装するために使用される内部クラスである。

プロテクト データ メンバ

m_PString | 表示される文字列を示す。これは、最初は m_String を指すが、文字列が大きい場合は動的に割り当てられる記憶領域を指すように更新される場合もある。
m_String[50] | このオブジェクトの初期バッファ領域。

メンバ関数

CDispBasic CDispBasic クラスのコンストラクタ。

CDispBasic::CDispBasic

CDispBasic

このクラスのオブジェクトをインスタンス化する。

構文

CDispBasic( );


DirectShow ファイル ライタ フィルタ

ビデオのキャプチャ時またはファイルのオーサリング時にファイルをディスクに書き込む。

フィルタ インターフェイス | IAMFilterMiscFlags、IBaseFilter、IFileSinkFilter、IFileSinkFilter2、IMediaSeeking、IPersistStream
入力ピン メディア タイプ | MEDIATYPE_Stream
入力ピン インターフェイス | IMemInputPin、IPin、IQualityControl、IStream
出力ピン メディア タイプ | 利用できない。
出力ピン インターフェイス | 利用できない。
フィルタ CLSID | CLSID_FileWriter
プロパティ ページ CLSID | プロパティ ページなし。
実行モジュール | quartz.dll
メリット | MERIT_DO_NOT_USE
カテゴリ | CLSID_LegacyAmFilterCategory

注意

DirectShow を使用してオーディオ/ビデオ ストリームをディスクにキャプチャするビデオ キャプチャ デバイスは、DirectShow ファイル ライタ フィルタを使用してディスクへの書き込みを行う。


IConfigAsfWriter インターフェイス

IConfigAsfWriter インターフェイスは、DirectShow ASF ライタ フィルタによって実装され、フィルタがファイルを書き込むときに使用する ASF (Advanced Streaming Format) プロファイルの取得や設定を行うメソッドを備えている。

作成された ASF ライタ フィルタには、入力されるストリームに基づいて、自動的にデフォルトの ASF オーディオビジュアル プロファイルが設定される。profile には、ビット レート、ストリームの数と種類、圧縮品質など、ASF ファイルのさまざまな属性が記述されている。フィルタはプロファイルを使って、どの種類の ASF ファイルを書き込むか、いくつの入力ピンを設定する必要があるか、どのメディア タイプが受け入れられるかを判断する。ほとんどの場合はデフォルトのプロファイルが使えるが、使えない場合、アプリケーションは、フィルタの IConfigAsfWriter インターフェイス メソッドを使ってプロファイルを変更できる。ASF プロファイルの詳細については、『Microsoft® Windows Media™ Software Development Kit (SDK)』を参照すること。ASF ファイルの書き方については、「DirectShow での ASF ファイルの作成」を参照すること。

要件

Dshowasf.h、Windows Media Format SDK が必要である。

vtable 順のメソッド

IUnknown メソッド | 説明
QueryInterface | サポートされているインターフェイスへのポインタを取得する。
AddRef | 参照カウントをインクリメントする。
Release | 参照カウントをデクリメントする。
IConfigAsfWriter メソッド | 説明
ConfigureFilterUsingProfileId | システム プロファイル リストのプロファイル識別子 (ID) インデックスを付けて ASF ファイルを書き込むようにフィルタを設定する (Windows Media Format 4.0 プロファイルのみ)。
GetCurrentProfileId | 現在の ASF プロファイル ID を取得する (Windows Media Format 4.0 プロファイルのみ)。
ConfigureFilterUsingProfileGuid | 指定された定義済みの Windows Media Format SDK プロファイル GUID に基づいて ASF ファイルを書き込むようにフィルタを設定する。
GetCurrentProfileGuid | Windows Media Format SDK によって定義されている現在の ASF プロファイル GUID を取得する。
ConfigureFilterUsingProfile | 指定されたアプリケーション定義のプロファイルに基づいて ASF ファイルを書き込むようにフィルタを設定する。
GetCurrentProfile | アプリケーション定義の ASF プロファイルを取得する。
SetIndexMode | ファイルにインデックスを付けて、ファイルをシークできるようにするかどうかをアプリケーションが制御できるようにする。
GetIndexMode | 現在のインデックス モードを取得する。

IConfigAsfWriter::ConfigureFilterUsingProfile

IConfigAsfWriter インターフェイス

指定されたアプリケーション定義のプロファイルに基づいて ASF ファイルを書き込むようにフィルタを設定する。

構文

HRESULT ConfigureFilterUsingProfile(
  IWMProfile *pProfile
);

パラメータ

pProfile
[in] アプリケーション定義のプロファイルへの IWMProfile インターフェイス ポインタ。

戻り値

次のいずれかの値を返す。
S_OK | 成功。
VFW_E_WRONG_STATE | グラフが停止している。
E_POINTER | IWMProfile インターフェイス ポインタが無効である。

注意

IWMProfile は Windows Media Format SDK で定義されている。

成功すると、このメソッドは、アプリケーションに EC_GRAPH_CHANGED イベント通知が送られるようにする。

IConfigAsfWriter::ConfigureFilterUsingProfileGuid

IConfigAsfWriter インターフェイス

指定された定義済みのプロファイルに基づいて ASF ファイルを書き込むようにフィルタを設定する。

構文

HRESULT ConfigureFilterUsingProfileGuid(
  REFGUID guidProfile
);

パラメータ

guidProfile
[in] Windows Media Format SDK ヘッダー ファイル Wmsysprf.h で定義されているプロファイル GUID。

戻り値

次のいずれかの値を返す。
S_OK | 成功。
E_FAIL | プロファイルが無効である。
VFW_E_WRONG_STATE | フィルタ グラフが停止している。

IConfigAsfWriter::ConfigureFilterUsingProfileId

IConfigAsfWriter インターフェイス

システム プロファイル リストのプロファイル識別子 (ID) インデックスを付けて ASF ファイルを書き込むようにフィルタを設定する (Windows Media Format 4.0 プロファイルのみ)。

構文

HRESULT ConfigureFilterUsingProfileId(
  DWORD dwProfileId
);

パラメータ

dwProfileId
[in] Windows Media Format SDK で定義されているプロファイル ID。

戻り値

次のいずれかの値を返す。
S_OK | 成功。
E_FAIL | プロファイルが無効である。
VFW_E_WRONG_STATE | フィルタ グラフが停止している。

注意

このメソッドは、version 4.0 の Windows Media Format SDK プロファイルを想定しているため、使わない。version 7.0 以降のフィルタを設定するためには、ConfigureFilterUsingProfile または ConfigureFilterUsingProfileGuid を使用する。

IConfigAsfWriter::GetCurrentProfile

IConfigAsfWriter インターフェイス

アプリケーション定義の ASF プロファイルを取得する。

構文

HRESULT GetCurrentProfile(
  IWMProfile **ppProfile
);

パラメータ

ppProfile
[out] アプリケーション定義のプロファイルへの IWMProfile インターフェイス ポインタを受け取るポインタのアドレス。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、HRESULT エラー コードを返す。

注意

メソッドが成功すると、返される IWMProfile ポインタが参照カウントを残す。使用狩猟時にインターフェイスの解放に注意すること。

IConfigAsfWriter::GetCurrentProfileGuid

IConfigAsfWriter インターフェイス

現在の ASF プロファイル ID を取得する。

構文

HRESULT GetCurrentProfileGuid(
  GUID *pProfileGuid
);

パラメータ

pProfileGuid
[out] プロファイル ID を受け取る GUID 型の変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、HRESULT エラー コードを返す。

IConfigAsfWriter::GetCurrentProfileId

IConfigAsfWriter インターフェイス

現在の ASF プロファイル ID を取得する (Windows Media Format 4.0 プロファイルのみ)。

構文

HRESULT GetCurrentProfileId(
  DWORD *pdwProfileId
);

パラメータ

pdwProfileId
[out] 現在のプロファイル ID を受け取る DWORD 型の変数へのポインタ。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、HRESULT エラー コードを返す。

注意

このメソッドは、version 4.0 の Windows Media Format SDK プロファイルを想定しているため、使わない。version 4.0 および 7.0 以降のプロファイルを正しく識別するためには、GetCurrentProfile または GetCurrentProfileGuid を使用する。

IConfigAsfWriter::GetIndexMode

IConfigAsfWriter インターフェイス

現在のインデックス モードを取得する。

構文

HRESULT GetIndexMode(
  BOOL *pbIndexFile
  );

パラメータ

pbIndexFile
[out] インデックス モードの設定を受け取る BOOL 型の変数へのポインタ。TRUE は、ASF ライタが、インデックスの付いたファイルを書き込むように設定されていることを示す。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、HRESULT エラー コードを返す。

注意

このメソッドを使って、ASF ライタが、現在、インデックス付きの ASF ファイルを書き込むように設定されているかどうかを判別する。詳細については、「SetIndexMode」の「注意」を参照すること。

IConfigAsfWriter::SetIndexMode

IConfigAsfWriter インターフェイス

ファイルにインデックスを付けて、ファイルをシークできるようにするかどうかをアプリケーションが制御できるようにする。

構文

HRESULT SetIndexMode(
  BOOL bIndexFile
);

パラメータ

bIndexFile
[in] BOOL 型の変数。TRUE はファイルにインデックスを付けるように指定する。

戻り値

成功した場合は、S_OK を返す。それ以外の場合は、HRESULT エラー コードを返す。

注意

ASF ライタは、デフォルトで、インデックス付きの ASF ファイルを作成する。インデックス付けは、グラフが停止したときに行われる。処理後の操作で独自にインデックス付けを行う場合は、この動作を無効にすることができる。


DVD_AudioAttributes 構造体

構造体

DVD_AudioAttributes 構造体は、ディスクの各種オーディオ属性を受け取るために、IDvdInfo2::GetAudioAttributes 内で使用される。

構文

typedef struct tagDVD_AudioAttributes
{
    DVD_AUDIO_APPMODE   AppMode;
    DVD_AUDIO_FORMAT    AudioFormat;
    LCID                Language;
    DVD_AUDIO_LANG_EXT  LanguageExtension;
    BOOL                fHasMultichannelInfo;
    DWORD               dwFrequency;
    BYTE                bQuantization;  0 is unknown
    BYTE                bNumberOfChannels;
    DWORD               dwReserved[2];
} DVD_AudioAttributes;

メンバ

AppMode
現在のオーディオ モードを示す。モード DVD_AudioMode_Karaoke が返される場合は、IDvdInfo2::GetKaraokeAttributes を呼び出して詳細情報を取得する。
AudioFormat
オーディオ ストリームのフォーマット (エンコード方式) を記述する。
Language
オーディオ ストリームの言語を示す LCID 値。言語が存在しない場合は 0。
LanguageExtension
ディスクに利用可能な情報がある場合に設定される DVD_AUDIO_LANG_EXT 列挙型。
fHasMultichannelInfo
マルチチャンネル属性が存在するかどうかを示す。TRUE は SurroundSound などの追加のミキシング情報が利用可能なことを意味する。マルチチャンネル情報を取得するには、IDvdInfo2::GetTitleAttributes を呼び出す。
dwFrequency
オーディオ ストリームの周波数 (48k、96k)。単位は Hz。
bQuantization
オーディオ ストリームの解像度 (16、20、24 ビットなど)。0 は解像度が不明であることを示す。
bNumberOfChannels
チャンネル数。たとえば、5.1 Dolby AC-3 にはチャンネルが 3 つある。
dwReserved
現在は使用されない。


パフォーマンス マクロ

Microsoft® DirectShow® 基底クラスの Measure.h ヘッダー ファイルは、特定のイベントの開始タイムおよび終了タイムの循環ログを維持することによってパフォーマンス データを記録するマクロを提供する。

MSR_START | イベントの開始タイムを記録する。
MSR_STOP | イベントの終了タイムを記録する。

MSR_START

パフォーマンス マクロ

循環ログに開始タイムを追加してそのタイムを StatBuffer に記録することにより、特定の登録済み ID を持つイベントの開始タイムを記録する。

構文

#define MSR_START(
  int Id
  )

パラメータ

Id
開始タイムを記録するイベントの登録済み ID。

注意

このマクロは統計情報を更新しない。統計情報の更新は、MSR_STOP の呼び出しによって行われる。

MSR_STOP

パフォーマンス マクロ

循環ログに終了タイムを追加して StopTime-StartTime エントリを統計レコード StatBuffer に記録することにより、特定の登録済み ID を持つイベントの終了タイムを記録する。

構文

#define MSR_STOP(
  int Id
  )

パラメータ

Id
終了タイムを記録するイベントの登録済み ID。


ストリーム整数関数

Microsoft® DirectShow® 基底クラスの Pstream.h ヘッダー ファイルは、一式のストリーム整数関数を含む。これらの関数は、ストリーム オブジェクト内の整数を、後ろに Unicode の空白が続く 11 個の Unicode™ 文字にエンコードする。これらの関数へのインターフェイスは、32 ビットへの切り捨てを行う。(符号なし) 0x80000000 のような値は -2147483648 と記述されるが、ReadInt を使用するとやはり 0x80000000 としてロードされる。

ReadInt | Unicode 文字列にエンコードされた整数をストリームから読み込む。
WriteInt | 整数を Unicode 文字列にエンコードされた文字列としてストリームに書き込む。

ReadInt

ストリーム整数関数

IStream から整数を読み込む。

構文

STDAPI_(
  int
  )ReadInt(
  IStream *pIStream,
  HRESULT &hr
  );

パラメータ

pIStream
エンコードされた整数を読み込む先の IStream へのポインタ。
hr
HRESULT 値 (出力) への参照。

戻り値

(32 ビットに切り捨てられた) 整数値を返す。エラーが発生した場合は、ゼロを返す。

注意

この関数は sscanf の機能を縮小したサブセットで、完全な C ランタイム ライブラリのオーバーヘッドはない。

ReadInt 関数は、WriteInt によって書き込まれた値を読み出すために使用する。

WriteInt

ストリーム整数関数

ストリーム整数関数でエンコードされた IStream に整数を書き込む。

構文

STDAPI WriteInt(
  IStream *pIStream,
  int n
  );

パラメータ

pIStream
エンコードされた整数を書き込む先の IStream へのポインタ。
n
書き込む整数値。

戻り値

HRESULT 値を返す。

注意

ReadInt 関数は、WriteInt によって書き込まれた値を読み出すために使用する。


トピックが見つかりません

クリックしたリンク先のトピックが見つかりません。考えられる原因と対処方法は以下のとおりです。

  • リンク先のトピックを含むファイル (.chm) が適切な位置にない。

    対処方法 : MSDN ライブラリ セットアップを再度、実行する。

  • 現在のトピック、またはリンク先のトピックを含むファイル (.chm) が古いため、リンク情報が適切に設定されていない。

    対処方法 : 最新の MSDN ライブラリをインストールする。

  • MSDN ライブラリ CD が CD-ROM ドライブにない。

    対処方法 : MSDN ライブラリ CD を CD-ROM ドライブに挿入する。

Built on 2000年11月20日


Microsoft DirectX 8.0

動作環境

API 要素の構文を紹介する各トピックには、これらの要素を使うときに必要となる、ビルドおよび実行時の動作環境についての情報が含まれている。動作環境の書式は、次のとおりである。

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
Windows CE : バージョン 1.0 以降が必要。
ヘッダー : winuser.h で宣言。
インポート ライブラリ : user32.lib を使用。
Unicode : Windows NT/2000 上の Unicode および ANSI バージョンとして実装される。

1 行目では、API 要素をサポートしている Windows NT のバージョンについての情報が記述されている。この情報には、必要とされるサービス パック、オプション パック、または Internet Explorer などのコンポーネントについての情報が含まれる。Windows NT または Windows 2000 で API 要素がサポートされていない場合は、"Windows NT/2000 : 未対応。" という書式で表される。

2 行目では、API 要素が Windows 95 または Windows 98 上でサポートされているかどうかについての情報が記述されている。この情報には、必要とされる OEM サービス リリース、再配布可能かどうか、または Internet Explorer などのコンポーネントについての情報が含まれる。Windows 95 または Windows 98 で API 要素がサポートされていない場合は、"Windows 95/98 : 未対応。" という書式で表される。

3 行目では、API 要素をサポートしている Windows CE のバージョンについての情報が記述されている。Windows CE で API 要素がサポートされていない場合は、"Windows CE : 未対応。" という書式で表される。

4 行目では、API 要素が定義されているファイルについての情報が記述されている。この情報には、.h ファイル、.idl ファイル、または .odl ファイルについての情報が含まれる。ヘッダー ファイルがユーザーによって提供される場合は、"ヘッダー : ユーザー定義。" という書式で表される。

5 行目では、関数またはメンバへの呼び出しの解決に使用されるファイルについての情報が記述されている。この情報には、.lib ファイル、.dll ファイル、または .tlb ファイルについての情報が含まれる。インポート ライブラリがユーザーによって提供される場合は、"インポート ライブラリ : ユーザー定義。" という書式で表される。インポート ライブラリを必要としない API 要素では、この行は省略される。

6 行目では、API 要素が Unicode (W) バージョンおよび ANSI (A) バージョンの両方でサポートされているかどうかについての情報が記述されている。API 要素が Unicode バージョンでサポートされていない場合、この行は省略される。

Built on 2000年11月20日